Skip to content

Advanced Usage

Jump to bottom
Jimmy Pautz edited this page Jun 30, 2026 · 15 revisions

Advanced Configuration

If you want to configure custom API endpoints, edit the raw configuration files, or integrate custom models, this page outlines the advanced setup options.

Manual Config Editing

While most settings are handled through the UI, you can manually enter your API keys or customize the default behaviour by editing xray_config.lua in the plugin folder (koreader/plugins/xray.koplugin/xray_config.lua).

Here is a template config file:

-- X-Ray API Configuration

return {
    -- Google Gemini API Key
    -- To get an API key: https://aistudio.google.com/
    gemini_api_key = "", 
    
    -- ChatGPT API Key 
    -- To get an API key: https://platform.openai.com/api-keys
    chatgpt_api_key = "",  

    -- DeepSeek API Key
    -- To get an API key: https://platform.deepseek.com/
    deepseek_api_key = "",

    -- Anthropic Claude API Key
    -- To get an API key: https://console.anthropic.com/
    claude_api_key = "",

    -- Custom API slot 1 (e.g., OpenRouter, any OpenAI-compatible endpoint)
    custom1_api_key  = "",   -- Your API key for this endpoint
    custom1_endpoint = "",   -- e.g., "https://openrouter.ai/api/v1/chat/completions"
    custom1_model    = "",   -- e.g., "google/gemini-2.5-pro"
    custom1_format   = "",   -- optional: "openai" or "anthropic" (default: auto-detected from endpoint)

    -- Custom API slot 2 (e.g., a local Ollama server)
    custom2_api_key  = "",
    custom2_endpoint = "",   -- e.g., "http://localhost:11434/v1/chat/completions"
    custom2_model    = "",   -- e.g., "llama3"
    custom2_format   = "",   -- optional: "openai" or "anthropic" (default: auto-detected from endpoint)
}

Note

Settings like model selection, language preferences, and spoiler modes are managed through the on-screen UI menu and stored in a separate settings.json file outside the plugin folder. This ensures your settings persist even if you uninstall and reinstall the plugin.

Custom API Providers

For advanced users, you can configure up to two custom API providers (e.g., OpenRouter, openmodel.ai, LiteLLM, or a self-hosted server) supporting either OpenAI or Anthropic payload formats.

  • Configurable Endpoint: Set your own endpoint (e.g., https://openrouter.ai/api/v1/chat/completions or https://api.openmodel.ai/v1/messages).
  • Auto-Format Detection: The plugin automatically detects Anthropic-compatible endpoints (if the URL contains /v1/messages or /messages) and formats the request body/headers accordingly. You can also explicitly set "openai" or "anthropic" in the customX_format config key.
  • Reasoning Models: If your custom model is a reasoning model (e.g., DeepSeek-R1), toggle Is Reasoning Model in the UI to allocate a larger token budget for extended thinking chains.
  • Provider-Specific Headers: The plugin automatically includes required attribution headers (like HTTP-Referer and X-Title for OpenRouter) and required version/authorization headers for Anthropic-compatible endpoints.

Maintenance & Logs

Under the Maintenance menu (Tools Menu → X-Ray → Maintenance), you'll find several useful utilities:

  • Clear Cache: If the AI gets confused or returns weird data, hit this to wipe the saved file for your current book and start fresh.
  • View Log: Opens the plugin's xray.log file in a scrollable viewer directly inside KOReader — no file manager needed. The viewer automatically scrolls to the bottom so the most recent entries are immediately visible. This is the fastest way to see what the plugin is doing or to diagnose a problem.
  • Clear Logs: Deletes both the current log (xray.log) and its backup (xray.log.old). Useful if you want a clean slate before reproducing an issue. The log is also rotated automatically once it exceeds 512 KB, so it won't grow unbounded even if you never manually clear it.
  • Beta Channel: Opt into pre-release builds to test the latest features before they are officially released.

Related Pages

Clone this wiki locally