{"repo": "caozhiyuan/copilot-api", "files": {"README.md": {"f85b0ba46a963386713123a74ce49d0220c29fc4": {"t": 1785746548.776482, "n": 51345, "h": "7addb396a41c2c85", "c": "# Copilot API Proxy\n\nEnglish | [简体中文](./README.zh-CN.md)\n\n## Important Notes\n\n> [!IMPORTANT]\n> **Before using, please be aware of the following:**\n>\n> 1. **Claude Code configuration:** When using with Claude Code, please configure the model ID as `claude-opus-4-8`. Example claude `settings.json` see [Manual Configuration with `settings.json`](#manual-configuration-with-settingsjson). \n>\n> 2. **Built-in `copilot`, `codex` and third-party providers:** Run `npx @jeffreycao/copilot-api@latest auth` and choose `copilot`, `codex`, `deepseek`, `custom`, or other providers.\n>\n> 3. **Note:** See [GitHub Copilot Security Notice](./NOTICE.md#github-copilot-security-notice) for the warning removed from the README header.\n\n---\n\n## Project Overview\n\nA small AI gateway that can use GitHub Copilot, the built-in `codex` provider, or configured third-party providers such as DashScope. GitHub Copilot is optional: if no GitHub token is available, the server can still start in provider-only mode as long as at least one enabled provider is configured.\n\nThe gateway exposes OpenAI- and Anthropic-compatible APIs from one local endpoint, so tools like [Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview), OpenCode, Codex, and OpenAI-compatible clients can share the same local server.\n\nOn the GitHub Copilot path, the gateway prefers Copilot's native Anthropic-style Messages API when available, preserving more Claude-native behavior for tool-heavy workflows.\n\n## Features\n\n- **OpenAI and Anthropic compatibility**: Serve `/v1/responses`, `/v1/chat/completions`, `/v1/models`, `/v1/embeddings`, and `/v1/messages` from one local gateway.\n- **Copilot is optional**: Use GitHub Copilot when credentials are present, or run the server with only configured providers.\n- **One gateway for Copilot, `codex`, and external providers**: Route GitHub Copilot, the built-in `codex` provider, and configured third-party providers behind the same endpoint.\n- **Standalone third-party providers**: Configure providers such as DashScope, DeepSeek, OpenRouter, or a custom provider and start the gateway without a GitHub Copilot login.\n- **OpenAI-compatible providers on chat and Messages APIs**: `openai-compatible` providers can serve top-level `/v1/chat/completions` through `model: \"provider/model\"` and Anthropic-style `/v1/messages` through request/response translation.\n- **Agent-friendly Claude handling on Copilot**: Prefer native `/v1/messages` when available, preserve Claude-style tool flows, support Anthropic beta features, Claude WebSearch through Responses-capable models, and keep subagent/session markers intact.\n- **Claude Code and OpenCode integration**: Works with Claude Code and OpenCode, including direct Anthropic-compatible usage through `@ai-sdk/anthropic`.\n- **Flexible auth and deployment options**: Supports interactive login or direct tokens, individual/business/enterprise plans, GitHub Enterprise, opencode OAuth, and custom data directories.\n- **Multi-provider routing**: Expose provider-specific `/:provider/...` routes or use `model: \"provider/model\"` on the top-level API.\n\n## Prerequisites\n\n- Bun (>= 1.2.x)\n- Node.js if you plan to run the published CLI with `npx`\n- GitHub account with Copilot subscription only if you want to use the GitHub Copilot provider\n- An API key or OAuth login for at least one configured provider if you want to run without GitHub Copilot\n\n## Installation\n\nTo install dependencies, run:\n\n```sh\nbun install\n```\n\nTo start the server directly from source:\n\n```sh\nbun run start start\n```\n\n## Running from Source\n\nThe project can be run from source in several ways:\n\n### Development Mode\n\n```sh\nbun run dev start\n```\n\n### Production Mode\n\n```sh\nbun run start start\n```\n\n## Using with npx\n\nYou can run the project directly using npx:\n\n> [!IMPORTANT]\n> Token usage storage uses Node's built-in `node:sqlite` module when running with `npx`. It is enabled on Node.js >= 22.13.0. On Node.js < 22.13.0, the CLI still starts, but token usage storage is disabled.\n>\n> If you want token usage storage without upgrading Node.js, run the published CLI with Bun instead: `bunx --bun @jeffreycao/copilot-api@latest start`.\n\n```sh\nnpx @jeffreycao/copilot-api@latest start\n```\n\nWith options:\n\n```sh\nnpx @jeffreycao/copilot-api@latest start --port 8080\n```\n\nFor authentication or provider configuration only:\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth\n```\n\nTo run without GitHub Copilot, configure at least one provider first, then start the server normally:\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth login --provider dashscope\nnpx @jeffreycao/copilot-api@latest start\n```\n\n## Using with Docker\n\nBuild the image:\n\n```sh\ndocker build -t copilot-api .\n```\n\nRun the container with a bind mount so auth data survives restarts:\n\n```sh\nmkdir -p ./copilot-data\ndocker run -p 4141:4141 -v $(pwd)/copilot-data:/root/.local/share/copilot-api copilot-api\n```\n\nThis stores GitHub auth data, provider config, and other gateway state in `./copilot-data` on the host, mapped to `/root/.local/share/copilot-api` in the container.\n\nOr pass a GitHub token directly:\n\n```sh\ndocker run -p 4141:4141 -e GH_TOKEN=your_github_token_here copilot-api\n```\n\n## Electron Desktop App\n\nIf you prefer a GUI, this repository also includes an Electron desktop app in `desktop/`. It supports GitHub Copilot sign-in, OpenAI Codex OAuth, and API-key configuration for DeepSeek, DashScope, OpenRouter, or a custom provider. After authorization or provider configuration, it can start and stop the local proxy with one click and shows the local endpoint, auth header, available models, usage, and logs in the app.\n\nThe settings screen also exposes `OAuth App`, `API Home`, `Enterprise URL`, verbose logging, and minimize-to-tray. Windows x64 (`.exe`), macOS Apple Silicon (`.dmg`), and Linux x64 (`.AppImage`) packages are published in GitHub Releases:\n\nhttps://github.com/caozhiyuan/copilot-api/releases\n\nOn Linux, make the downloaded AppImage executable before launching it:\n\n```sh\nchmod +x Copilot-API-*-linux-x86_64.AppImage\n./Copilot-API-*-linux-x86_64.AppImage\n```\n\nDownload the installer for your platform, authorize or configure a provider inside the app, choose a port, start the server, then point your client at the local endpoint shown in the app. Packaged desktop builds use the bundled Electron runtime, so normal desktop usage does not require installing Node.js separately. Token usage history is enabled when that bundled runtime supports SQLite.\n\nThe desktop app's Advanced Config page reads and writes the shared model mappings through `GET/POST /admin/config/model-mappings`. The same mappings apply across `POST /v1/messages`, `POST /v1/messages/count_tokens`, `POST /v1/responses`, and `POST /v1/chat/completions` instead of being split per interface. It uses `auth.adminApiKey` instead of the regular `auth.apiKeys`, and the app reads that key directly from `config.json` after the server has generated it on startup.\n\n### Desktop App Screenshots\n\nMain dashboard, token usage breakdown in the bundled Electron app:\n\n<p align=\"center\">\n  <img src=\"./docs/screenshots/desktop-dashboard.png\" alt=\"Copilot API desktop app dashboard\" width=\"49%\" />\n  <img src=\"./docs/screenshots/desktop-token-usage.png\" alt=\"Copilot API desktop app token usage view\" width=\"49%\" />\n</p>\n\n## Using with Claude Code\n\nThis AI gateway can be used to power [Claude Code](https://docs.anthropic.com/en/claude-code), an experimental conversational AI assistant for developers from Anthropic.\n\nThere are two ways to configure Claude Code to use this AI gateway:\n\n### Interactive Setup with `--claude-code` flag\n\nTo get started, run the `start` command with the `--claude-code` flag:\n\n```sh\nnpx @jeffreycao/copilot-api@latest start --claude-code\n```\n\nYou will no longer be prompted to pick models manually. The gateway automatically detects the latest available model for each Claude Code size tier — opus maps to the newest Opus model, sonnet to the newest Sonnet model, and haiku to the newest Haiku model — and generates a command that sets `ANTHROPIC_DEFAULT_OPUS_MODEL`, `ANTHROPIC_DEFAULT_SONNET_MODEL`, and `ANTHROPIC_DEFAULT_HAIKU_MODEL` accordingly. Any tier without a matching model available is omitted. The command is copied to your clipboard and sets the environment variables needed for Claude Code to use the gateway.\n\nPaste and run this command in a new terminal to launch Claude Code.\n\n### Manual Configuration with `settings.json`\n\nAlternatively, you can configure Claude Code by creating a `.claude/settings.json` file in your project's root directory. This file should contain the environment variables needed by Claude Code. This way you don't need to run the interactive setup every time.\n\nHere is an example `.claude/settings.json` file:\n\n```json\n{\n  \"env\": {\n    \"ANTHROPIC_BASE_URL\": \"http://localhost:4141\",\n    \"ANTHROPIC_AUTH_TOKEN\": \"dummy\",\n    \"ANTHROPIC_MODEL\": \"gpt-5.6-sol[1m]\",\n    \"ANTHROPIC_DEFAULT_OPUS_MODEL\": \"gpt-5.6-sol[1m]\",\n    \"ANTHROPIC_DEFAULT_SONNET_MODEL\": \"gpt-5.6-sol[1m]\",\n    \"ANTHROPIC_DEFAULT_HAIKU_MODEL\": \"gpt-5.6-luna[1m]\",\n    \"CLAUDE_CODE_AUTO_COMPACT_WINDOW\": \"272000\",\n    \"CLAUDE_CODE_USE_VERTEX\": \"0\",\n    \"CLAUDE_CODE_USE_BEDROCK\": \"0\",\n    \"DISABLE_NON_ESSENTIAL_MODEL_CALLS\": \"1\",\n    \"CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC\": \"1\",\n    \"CLAUDE_CODE_ATTRIBUTION_HEADER\": \"0\",\n    \"CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION\": \"false\",\n    \"CLAUDE_CODE_DISABLE_TERMINAL_TITLE\": \"true\",\n    \"CLAUDE_CODE_ENABLE_AWAY_SUMMARY\": \"0\"\n  },\n  \"alwaysThinkingEnabled\": true,\n  \"effortLevel\": \"xhigh\",\n  \"showThinkingSummaries\": true\n}\n```\n\n- Replace `ANTHROPIC_MODEL`, `ANTHROPIC_DEFAULT_OPUS_MODEL`, `ANTHROPIC_DEFAULT_SONNET_MODEL`, and `ANTHROPIC_DEFAULT_HAIKU_MODEL` according to your needs. After configuration, please install the claude code plugin [Plugin Integrations](#plugin-integrations).  \n- If you are using the codex provider, it is recommended **not** to configure the model name in the `codex/xxx` format (e.g. `codex/gpt-5.6-sol`). Claude Code treats the `codex/` prefix as a special pattern and applies degraded behavior — for example, it strips all previously returned thinking blocks on every request. Use the plain model name (e.g. `gpt-5.6-sol`) instead, and add a `modelMappings` entry in `config.json` to route it back to the codex provider:\n  ```json\n  \"modelMappings\": {\n    \"gpt-5.6-sol\": \"codex/gpt-5.6-sol\",\n    \"gpt-5.6-terra\": \"codex/gpt-5.6-terra\",\n    \"gpt-5.6-luna\": \"codex/gpt-5.6-luna\"\n  },\n  ```\n- Setting CLAUDE_CODE_ATTRIBUTION_HEADER to 0 can prevent Claude code from adding billing and version information in system prompts, thereby avoiding prompt cache invalidation.\n- Turning off CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION and CLAUDE_CODE_ENABLE_AWAY_SUMMARY can prevent quota from being consumed unnecessarily.\n- Claude Code WebSearch is supported for pure search requests. For Copilot, keep the global `messageApiWebSearchModel` set to a Responses-capable GPT model or a `provider/model` alias. For provider routes, use a native Anthropic provider or an `openai-responses` provider. Add `WebSearch` to `permissions.deny` only if you want to forbid this traffic.\n- If using a non-Claude model, do not enable ENABLE_TOOL_SEARCH. If using the Claude model, can enable ENABLE_TOOL_SEARCH. The current Claude Code uses the client tool search mode. In this mode, loading defer tools requires an additional request each time.\n- `CLAUDE_CODE_AUTO_COMPACT_WINDOW`: Set the context capacity in tokens used for auto-compaction calculations. Defaults to the model's context window: 200K for standard models or 1M for extended context models. Use a lower value like `500000` on a 1M model (e.g., `claude-opus-4-6[1m]`) to treat the window as 500K for compaction purposes. The value is capped at the model's actual context window. `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` is applied as a percentage of this value. Setting this variable decouples the compaction threshold from the status line's `used_percentage`, which always uses the model's full context window.\n\nYou can find more options here: [Claude Code settings](https://docs.anthropic.com/en/docs/claude-code/settings#environment-variables)\n\nYou can also read more about IDE integration here: [Add Claude Code to your IDE](https://docs.anthropic.com/en/docs/claude-code/ide-integrations)\n\n## Using with OpenCode\n\nOpenCode already has a direct GitHub Copilot provider. Use this section when you want OpenCode to point at this AI gateway through `@ai-sdk/anthropic` and reuse the agent behaviors described earlier in this README.\n\n### Minimal setup\n\nStart the AI gateway with the OpenCode OAuth app:\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth --oauth-app=opencode\nnpx @jeffreycao/copilot-api@latest start\n```\n\nThen point OpenCode at the gateway with `@ai-sdk/anthropic`.\n\nExample `~/.config/opencode/opencode.json`:\n\n```json\n{\n  \"$schema\": \"https://opencode.ai/config.json\",\n  \"provider\": {\n    \"local\": {\n      \"npm\": \"@ai-sdk/anthropic\",\n      \"name\": \"My Local\",\n      \"options\": {\n        \"baseURL\": \"http://localhost:4141/v1\",\n        \"apiKey\": \"dummy\"\n      },\n      \"models\": {\n        \"gpt-5.4\": {\n          \"name\": \"gpt-5.4\",\n          \"modalities\": {\n            \"input\": [\"text\", \"image\"],\n            \"output\": [\"text\"]\n          },\n          \"limit\": {\n            \"context\": 400000,\n            \"input\": 272000,\n            \"output\": 128000\n          }\n        },\n        \"claude-sonnet-4.6\": {\n          \"id\": \"claude-sonnet-4.6\",\n          \"name\": \"claude-sonnet-4.6\",\n          \"modalities\": {\n            \"input\": [\"text\", \"image\"],\n            \"output\": [\"text\"]\n          },          \n          \"limit\": {\n            \"context\": 200000,\n            \"output\": 32000\n          },\n          \"options\": {\n            \"thinking\": {\n              \"type\": \"adaptive\"\n            },\n            \"effort\": \"max\"\n          }\n        }\n      }\n    }\n  }\n}\n```\n\nWhy these fields matter:\n\n- `npm: \"@ai-sdk/anthropic\"` is the important part. OpenCode will speak Anthropic Messages semantics to this AI gateway instead of flattening everything into OpenAI Chat Completions.\n- `options.baseURL` should be `http://localhost:4141/v1`; the Anthropic SDK will append `/messages`, `/models`, and `/messages/count_tokens` automatically.\n- If you enable `auth.apiKeys` in this AI gateway, replace `dummy` with a real key. Otherwise any placeholder value is fine.\n\n## Using with Codex\n\nThis AI gateway can also power Codex.\n\n### Codex `config.toml` Reference\n\nAdd the following `[model_providers.copilot_api]` section to your Codex `~/.codex/config.toml`:\n\n```toml\nmodel_provider = \"copilot_api\"\nmodel_reasoning_summary = \"auto\"\nmodel_context_window = 272000\nmodel_auto_compact_token_limit = 244800\n\n[model_providers.copilot_api]\nname = \"OpenAI\"\nbase_url = \"http://localhost:4141\"\nenv_key = \"GITHUB_COPILOT_API_KEY\"\nrequires_openai_auth = true\nsupports_websockets = false\nwire_api = \"responses\"\nrequest_max_retries = 3\nstream_max_retries = 1\nstream_idle_timeout_ms = 300000\n\n[features]\nremote_compaction_v2 = true\n\n[analytics]\nenabled = false\n```\n\n> [!NOTE]\n> This configuration is specific to Codex and the GitHub Copilot provider. `name` must be set to `\"OpenAI\"`. It can help mitigate Codex local compact cache miss issues.\n> If you are using the codex provider, it is recommended to set `base_url` to `\"http://localhost:4141/codex\"`.\n\n## GPT Tool Search\n\nFor GPT Responses models such as `gpt-5.4+`, this AI gateway can expose Responses `tool_search` through a small MCP bridge. The same bridge can be used by Claude Code and opencode, as long as the client loads MCP servers and sends Anthropic Messages traffic through this gateway.\n\nDo not set Claude Code's native `ENABLE_TOOL_SEARCH` for GPT models. That flag enables Claude Code's own client-side tool search mode, and it may stop forwarding deferred tool definitions. This gateway needs the full tool definitions so it can keep the small always-loaded tool set eager and translate every other tool into Responses deferred namespaces.\n\nIf you install `tool-search@copilot-api-marketplace`, Claude Code receives this MCP bridge automatically and you can skip the manual Claude Code MCP setup below.\n\nAdd the tool search bridge to the MCP config used by Claude Code:\n\n```json\n{\n  \"mcpServers\": {\n    \"tool_search\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@jeffreycao/copilot-api@latest\", \"mcp\"]\n    }\n  }\n}\n```\n\nAdd the tool search bridge to the MCP config used by opencode:\n\n```json\n{\n  \"mcp\": {\n    \"tool_search\": {\n      \"type\": \"local\",\n      \"command\": [\"npx\", \"-y\", \"@jeffreycao/copilot-api@latest\", \"mcp\"]\n    }\n  }\n}\n```\n\nFor local development, use `bun` as the command and `[\"run\", \"./src/main.ts\", \"mcp\"]` as the args.\n\nInternally, the gateway now configures OpenAI Responses `tool_search` in client-executed mode. Deferred tools are still exposed as searchable namespaces, but the model is explicitly asked to return the exact deferred tool names it wants to load next.\n\nThe bridge uses direct tool selection, not query search. Its tool input is `names`, a comma-separated list of exact deferred tool names, for example `TaskList,TaskGet,mcp__fetch__fetch`.\n\n## Plugin Integrations\n\nPlugin integrations are available for Claude Code and opencode.\n\n#### Claude Code plugin integration (marketplace-based)\n\nThe Claude Code integration is packaged as two plugins:\n\n- `agent-inject` injects `__SUBAGENT_MARKER__...` on `SubagentStart`, so the gateway can infer `x-initiator: agent`.\n- `tool-search` registers the `tool_search` MCP bridge used for GPT Responses deferred tool loading.\n\n- Marketplace catalog in this repository: `.claude-plugin/marketplace.json`\n- Plugin sources in this repository: `plugin/claude/agent-inject`, `plugin/claude/tool-search`\n\nAdd the marketplace remotely:\n\n```sh\n/plugin marketplace add https://github.com/caozhiyuan/copilot-api.git\n```\n\nInstall the plugins from the marketplace:\n\n```sh\n/plugin install agent-inject@copilot-api-marketplace\n/plugin install tool-search@copilot-api-marketplace\n```\n\nAfter installation, `agent-inject` injects `__SUBAGENT_MARKER__...` on `SubagentStart`, and the gateway uses it to infer `x-initiator: agent`.\n\nThe `agent-inject` plugin also registers a `UserPromptSubmit` hook that returns `{\"continue\": true}`, and it can inject `SessionStart` reminder rules through environment variables:\n\n- `CLAUDE_PLUGIN_ENABLE_QUESTION_RULES=1` enables the two reminders about using the `question` tool automatically for Claude Code. Alternatively, you can add the same reminders manually in `CLAUDE.md`; see [CLAUDE.md or AGENTS.md Recommended Content](#claudemd-or-agentsmd-recommended-content).\n- `CLAUDE_PLUGIN_ENABLE_NO_BACKGROUND_AGENTS_RULE=1` enables the `run_in_background: true` avoidance reminder for agent hooks.\n\nThe `tool-search` plugin bundles the same MCP bridge described in [GPT Tool Search](#gpt-tool-search), so Claude Code users do not need to add the `tool_search` server manually when they install that plugin.\n\n#### Opencode plugin\n\nThe subagent marker producer is packaged as an opencode plugin located at `plugin/opencode/subagent-marker.js`.\n\n**Installation:**\n\nCopy the plugin file to your opencode plugins directory:\n\n```sh\n# Clone or download this repository, then copy the plugin\ncp plugin/opencode/subagent-marker.js ~/.config/opencode/plugins/\n```\n\nOr manually create the file at `~/.config/opencode/plugins/subagent-marker.js` with the plugin content.\n\n**Features:**\n\n- Tracks sub-sessions created by subagents\n- Automatically prepends a marker system reminder (`__SUBAGENT_MARKER__...`) to subagent chat messages\n- Sets `x-session-id` header for session tracking\n- Enables the gateway to infer `x-initiator: agent` for subagent-originated requests\n\nThe plugin hooks into `session.created`, `session.deleted`, `chat.message`, and `chat.headers` events to provide seamless subagent marker functionality.\n\n## Using the Usage Viewer\n\nAfter starting the server, a URL to the Copilot Usage Dashboard will be displayed in your console. This dashboard is a web interface for monitoring your API usage.\n\n1.  Start the server. For example, using npx:\n    ```sh\n    npx @jeffreycao/copilot-api@latest start\n    ```\n2.  The server will output a URL to the usage viewer. Copy and paste this URL into your browser. It will look something like this:\n    `http://localhost:4141/usage-viewer?endpoint=http://localhost:4141/usage`\n    - If you use the `start.bat` script on Windows, this page will open automatically.\n\nThe dashboard provides a user-friendly interface to view your Copilot usage data:\n\n> Token usage history requires Bun or Node.js >= 22.13.0. On Node.js < 22.13.0, the server runs normally but token usage storage is disabled.\n\n- **API Endpoint URL**: The dashboard is pre-configured to fetch data from your local server endpoint via a URL query parameter. You can manually switch this to any other compatible API endpoint.\n- **x-api-key Authentication**: If API Key authentication is enabled, you can provide the `x-api-key` request header. The key is persisted in the browser's local storage.\n- **Period Selector**: Choose from Day, Week, or Month time ranges. The URL query parameter updates automatically when you switch, making it easy to bookmark and share.\n- **Fetch Data**: Click the \"Refresh\" button to load or refresh the usage data. The dashboard also fetches data automatically on page load.\n- **Copilot Quotas**: View quota usage for services such as Chat and Completions via progress bars. Hover over a card to see used/remaining details.\n- **Token Usage Metric Cards**: See a summary of Total, Input, Output, Cache Read, Cache Write, Requests, and estimated cost for the current period.\n- **Trend Chart (Week / Month)**: An interactive line chart with model and metric filters. Click a data point to inspect the usage breakdown for a specific day.\n- **Model Breakdown Table**: A per-model summary of requests, input/output/cache tokens, and estimated cost for the selected period.\n- **Request Events (Paginated)**: A time-sorted list of request event records with pagination support, showing timestamps, models, request IDs, and token counts.\n- **Detailed Information**: See the full JSON response from the API for a detailed breakdown of all available usage statistics.\n- **URL-based Configuration**: You can also specify the API endpoint and period directly via `endpoint` and `period` query parameters. For example:\n  `http://localhost:4141/usage-viewer?endpoint=http://your-api-server/usage&period=week`\n\n### Usage Viewer Screenshot\n\n<p align=\"center\">\n  <img src=\"./docs/screenshots/usage-viewer.png\" alt=\"Copilot API usage viewer\" width=\"900\" />\n</p>\n\n## Command Structure\n\nCopilot API now uses a subcommand structure with these main commands:\n\n- `start`: Start the gateway server. If a GitHub token is available, the server starts with Copilot enabled. If no GitHub token is available, it starts in provider-only mode when at least one enabled provider exists; otherwise it guides you through provider setup.\n- `auth`: Run provider login or configuration without starting the server. Use it for GitHub Copilot login, Codex OAuth, or third-party provider API key setup.\n- `debug`: Display diagnostic information including version, runtime details, file paths, and authentication status. Useful for troubleshooting and support.\n\n## Command Line Options\n\n### Global Options\n\nThe following options can be used with any subcommand. When passing them before the subcommand, use the `--key=value` form:\n\n| Option            | Description                                            | Default | Alias |\n| ----------------- | ------------------------------------------------------ | ------- | ----- |\n| --api-home        | Path to the API home directory (sets COPILOT_API_HOME) | none    | none  |\n| --oauth-app       | OAuth app identifier (sets COPILOT_API_OAUTH_APP)      | none    | none  |\n| --enterprise-url  | Enterprise URL for GitHub (sets COPILOT_API_ENTERPRISE_URL) | none | none |\n\n### Start Command Options\n\nThe following command line options are available for the `start` command:\n\n| Option         | Description                                                                   | Default    | Alias |\n| -------------- | ----------------------------------------------------------------------------- | ---------- | ----- |\n| --port         | Port to listen on                                                             | 4141       | -p    |\n| --verbose      | Enable verbose logging                                                        | false      | -v    |\n| --github-token | Provide GitHub token directly (must be generated using the `auth` subcommand) | none       | -g    |\n| --claude-code  | Generate a command to launch Claude Code with Copilot API config              | false      | -c    |\n| --show-token   | Show GitHub and Copilot tokens on fetch and refresh                           | false      | none  |\n| --proxy-env    | Initialize proxy from environment variables                                   | false      | none  |\n\n### Auth Command Options\n\n| Option       | Description               | Default | Alias |\n| ------------ | ------------------------- | ------- | ----- |\n| --provider   | Provider to log in with or configure (`copilot`, `codex`, `opencode-go`, `deepseek`, `dashscope`, `openrouter`, or `custom`) | prompt | none |\n| --verbose    | Enable verbose logging    | false   | -v    |\n| --show-token | Show GitHub token on auth | false   | none  |\n\nUse `copilot-api auth login --provider copilot` only when you want to enable the GitHub Copilot provider. Copilot is not required for `codex` or third-party provider-only usage.\n\nUse `copilot-api auth login --provider deepseek`, `--provider dashscope`, `--provider openrouter`, or `--provider opencode-go` to add or update those common third-party providers from the CLI. DeepSeek prompts for masked `apiKey`, provider `type` (default `anthropic`), and `baseUrl` defaulting to `https://api.deepseek.com/anthropic`. DashScope prompts for masked `apiKey`, provider `type` (default `openai-compatible`), and prefilled `baseUrl`. OpenRouter prompts for masked `apiKey` and prefilled `baseUrl` only, and writes `type: \"anthropic\"`. OpenCode Go prompts for masked `apiKey` and prefilled `baseUrl` only, and writes `type: \"openai-compatible\"` (baseUrl `https://opencode.ai/zen/go`). After a provider is configured and enabled, `copilot-api start` can run without any GitHub token.\n\nUse `copilot-api auth login --provider custom` to add or update another third-party provider from the CLI. The command prompts for the provider name, supported type (`anthropic`, `openai-compatible`, or `openai-responses`), `baseUrl`, masked `apiKey`, and `authType`; `authType` may be left as the type default or set to `x-api-key` / `authorization`.\n\n### Debug Command Options\n\n| Option | Description               | Default | Alias |\n| ------ | ------------------------- | ------- | ----- |\n| --json | Output debug info as JSON | false   | none  |\n\n## Configuration (config.json)\n\n- **Location:** `~/.local/share/copilot-api/config.json` (Linux/macOS) or `%USERPROFILE%\\.local\\share\\copilot-api\\config.json` (Windows).\n- **Default shape:**\n  ```json\n  {\n    \"auth\": {\n      \"apiKeys\": [],\n      \"adminApiKey\": \"<auto-generated-on-startup>\"\n    },\n    \"providers\": {},\n    \"modelMappings\": {},\n    \"extraPrompts\": {\n      \"gpt-5-mini\": \"<built-in exploration prompt>\"\n    },\n    \"smallModel\": \"gpt-5-mini\",\n    \"contextManagement\": {\n      \"messages\": true,\n      \"responses\": false\n    },\n    \"modelResponsesApiCompactThresholds\": {\n      \"gpt-5.4\": 217600,\n      \"gpt-5.5\": 217600\n    },\n    \"modelReasoningEfforts\": {\n      \"gpt-5-mini\": \"low\"\n    },\n    \"useMessagesApi\": true,\n    \"useResponsesApiWebSocket\": true,\n    \"useResponsesApiWebSearch\": true,\n    \"messageApiWebSearchModel\": \"gpt-5-mini\"\n  }\n  ```\n- **auth.apiKeys:** API keys used for request authentication on non-admin routes. Supports multiple keys for rotation. Requests can authenticate with either `x-api-key: <key>` or `Authorization: Bearer <key>`. If empty or omitted, authentication for non-admin routes is disabled.\n- **auth.adminApiKey:** Single admin key used only for `/admin/*` routes. If missing, the server generates a random key at startup and writes it back to `config.json`. Requests use the same `x-api-key` or `Authorization: Bearer` headers, but regular `auth.apiKeys` never grant access to `/admin/*`.\n- **modelMappings:** Exact `sourceModel -> targetModel` rewrites shared by top-level `POST /v1/messages`, `POST /v1/messages/count_tokens`, `POST /v1/responses`, and `POST /v1/chat/completions` requests. Omit it or leave it as `{}` to disable rewrites. Both the source and target must be non-empty strings. Targets can be regular model IDs or `provider/model` aliases such as `dashscope/qwen3.6-plus`, and the rewrite happens before provider alias parsing. These mappings are not split per interface. The admin endpoints `GET/POST /admin/config/model-mappings` read and update only this field.\n- **extraPrompts:** Map of `model -> prompt` appended to the first system prompt when translating Anthropic-style requests to Responses API. Use this to inject guardrails or guidance per model. Missing default entries are auto-added without overwriting your custom prompts. For GPT-5.3+ models (e.g. `gpt-5.3-codex`, `gpt-5.4`, `gpt-5.5`), a built-in commentary prompt is used as fallback when not explicitly configured. The built-in prompts enable phase-aware commentary, which lets the model emit a short user-facing progress update before tools or deeper reasoning.\n- **providers:** Global upstream provider map. Each provider key (for example `dashscope`) becomes a route prefix (`/dashscope/v1/messages`). Supports `type: \"anthropic\"`, `type: \"openai-compatible\"`, and `type: \"openai-responses\"`. Top-level clients can also use `model: \"dashscope/model-id\"` with `/v1/messages`, `/v1/messages/count_tokens`, `/v1/responses`, and `/v1/chat/completions`; the gateway strips the `dashscope/` prefix before forwarding upstream. `openai-compatible` providers support both chat and Messages flows: `/v1/chat/completions` is proxied to upstream `/v1/chat/completions`, while `/v1/messages` and `/:provider/v1/messages` are translated to upstream chat completions and translated back to Anthropic Messages responses. `GET /v1/models` aggregates enabled provider models with `provider/model-id` IDs; use `GET /dashscope/v1/models` for a single provider's raw model list.\n  - `enabled` defaults to `true` if omitted.\n  - `baseUrl` should be provider API base URL without the final endpoint. For Anthropic providers, omit `/v1/messages`; for OpenAI-compatible providers, omit `/v1/chat/completions`; for OpenAI Responses providers, omit `/v1/responses`.\n  - `apiKey` is used as the upstream credential value and is required for regular providers.\n  - `authType` (optional): Controls how `apiKey` is sent upstream. Supports `x-api-key` and `authorization` for regular providers. Anthropic providers default to `x-api-key`; OpenAI-compatible and OpenAI Responses providers default to `authorization`. When set to `authorization`, the proxy sends `Authorization: Bearer <apiKey>`. `oauth2` is reserved for the built-in `codex` provider and is written automatically by `auth login --provider codex`.\n  - `pricingCurrency` (optional): Provider-level currency used for token cost calculation, for example `USD` or `CNY`. Quick providers default to `CNY` for DashScope and DeepSeek, and `USD` for Codex/OpenRouter. Costs are grouped by currency and are not exchange-rate converted.\n  - `models` (optional): Per-model configuration map. Each key is a model ID (matching the model name in requests), and the value is:\n    - `temperature` (optional): Default temperature value used when the request does not specify one.\n    - `topP` (optional): Default top_p value used when the request does not specify one.\n    - `topK` (optional): Default top_k value used when the request does not specify one.\n    - `extraBody` (optional): Dynamic fields merged into the upstream request body for that model. Request body fields with the same name take precedence. OpenAI-compatible providers can use this for fields such as `enable_thinking`, `preserve_thinking`, `reasoning_effort`. `thinking_budget` is a special OpenAI-compatible provider override: when configured in `extraBody`, it is forced after Anthropic `thinking.budget_tokens` translation and overrides the request-derived budget. For providers whose name is `dashscope` or whose `baseUrl` contains `aliyuncs.com`, the request-derived `thinking_budget` (from Anthropic `thinking.budget_tokens`) is forwarded upstream; for other OpenAI-compatible providers the request-derived `thinking_budget` is stripped, while an `extraBody` `thinking_budget` is still honored. For DashScope providers, `preserve_thinking` defaults to `true` when not explicitly set in `extraBody` or the request body.\n    - `pricing` (optional): Per-model token prices, in the provider `pricingCurrency`, per 1M tokens. Supported fields are `input`, `output`, `cachedInput` (implicit cache read), `explicitCachedInput` (explicit cache read), and `cacheCreationInput`. Use `tiers` with `maxInputTokens` for input-size tiered pricing.\n    - `contextCache` (optional): Defaults to `true` for providers whose name is `dashscope` or whose `baseUrl` contains `aliyuncs.com`; defaults to `false` for other OpenAI-compatible providers. This enables Alibaba Cloud Model Studio/DashScope explicit context cache by injecting `cache_control: { \"type\": \"ephemeral\" }` on up to 4 content blocks using the Context Cache format. The cache breakpoint strategy matches opencode's main provider flow: the first 2 system messages plus the last 2 non-system messages. Marked string content is converted to text content part arrays for `system` / `user` / `assistant` / `tool` messages; existing array content is marked on the last part. Set this to `false` when the model already supports implicit caching, or when the upstream does not accept this explicit-cache extension field. Set this to `true` for non-DashScope providers that support the same explicit-cache extension. Applied on both `/v1/messages` and `/v1/chat/completions` routes.\n    - `supportPdf` (optional): Controls whether the model supports PDF/document content. Defaults to `false`; unsupported PDFs are converted to a text notice. Set it to `true` to send PDF/document blocks as OpenAI Chat Completions file parts.\n    - `toolContentSupportType` (optional): Tool result content capabilities for that model, as an array of `array`, `image`, and `pdf`. Provider routes default to string-only tool content when omitted. If `supportPdf` is `true` but this list does not include `pdf`, file parts in tool results are moved to user role messages. This provider default does not change the Copilot main flow, which continues to support array + image and not PDF.\n    - `type` (optional): Per-model override of the provider protocol type. Supports `anthropic`, `openai-compatible`, and `openai-responses`. When set, the provider's `/v1/messages` route uses this model's type instead of the provider-level type for request routing, auth header resolution, and upstream endpoint selection. This is useful for providers like OpenCode Go whose upstream supports both OpenAI-compatible and Anthropic Messages APIs for different models. When the type is overridden, the auth header is resolved from the overridden type's default (Anthropic defaults to `x-api-key`; OpenAI-compatible/Responses default to `authorization`).\n\n  Example DashScope model settings:\n  ```json\n  {\n    \"providers\": {\n      \"dashscope\": {\n        \"type\": \"openai-compatible\",\n        \"enabled\": true,\n        \"baseUrl\": \"https://dashscope.aliyuncs.com/compatible-mode\",\n        \"apiKey\": \"sk-your-dashscope-key\",\n        \"pricingCurrency\": \"CNY\",\n        \"models\": {\n          \"qwen3.7-plus\": {\n            \"temperature\": 1,\n            \"topP\": 0.95,\n            \"topK\": 20,\n            \"extraBody\": {\n              \"preserve_thinking\": true\n            }\n          },\n          \"glm-5.1\": {\n            \"temperature\": 0.7,\n            \"topP\": 0.95,\n            \"contextCache\": true,\n            \"pricing\": {\n              \"tiers\": [\n                {\n                  \"maxInputTokens\": 32000,\n                  \"input\": 6,\n                  \"cachedInput\": 1.2,\n                  \"explicitCachedInput\": 0.6,\n                  \"cacheCreationInput\": 7.5,\n                  \"output\": 24\n                },\n                {\n                  \"maxInputTokens\": 200000,\n                  \"input\": 8,\n                  \"cachedInput\": 1.6,\n                  \"explicitCachedInput\": 0.8,\n                  \"cacheCreationInput\": 10,\n                  \"output\": 28\n                }\n              ]\n            },\n            \"extraBody\": {\n              \"preserve_thinking\": true\n            }\n          }\n        }\n      }\n    }\n  }\n  ```\n  Built-in token prices cover Codex GPT models in USD, DashScope `qwen3.7-max`, `qwen3.7-plus`, `glm-5.1`, `glm-5.2` in CNY, DeepSeek `deepseek-v4-flash`, `deepseek-v4-pro`, `deepseek-chat`, `deepseek-reasoner` in CNY, and OpenCode Go models (`hy3`, `gpt-5.6-luna`, `glm-5.2`, `grok-4.5`, `deepseek-v4-flash`, `deepseek-v4-pro`, `kimi-k2.7-code`, `kimi-k3`, `mimo-v2.5`, `mimo-v2.5-pro`, `qwen3.7-plus`, `qwen3.7-max`, `minimax-m2.7`, `minimax-m3`) in USD. User `pricing` entries override built-ins. For DashScope, cached tokens are charged as explicit cache reads when the upstream usage includes `cache_creation_input_tokens`; otherwise `cachedInput` is used as the implicit cache read price. For DeepSeek, `prompt_cache_hit_tokens` map to cached input and `prompt_cache_miss_tokens` map to regular input.\n- **smallModel:** Fallback model used for tool-less warmup messages (e.g., Claude Code probe requests); defaults to gpt-5-mini. The gateway forces this small model on no-tool warmup or probe requests to avoid consuming premium requests. This behavior only applies to non-token-based-billing GitHub Copilot accounts (`token_based_billing` is false); for token-based-billing accounts the warmup small-model fallback is skipped since there is no premium-request quota to preserve.\n- **contextManagement:** Controls whether the proxy adds Responses API `context_management` compaction instructions. `messages` applies when Anthropic-style `/v1/messages` requests are translated to Responses API, including `openai-responses` provider message routes, and defaults to `true`. `responses` applies to native `/v1/responses` traffic, including `provider/model` aliases and the built-in `codex` provider, and defaults to `false`. Enable `responses` only after checking that your client supports context management compaction. When enabled, the request includes `context_management` in the body and keeps only the latest compaction carrier on follow-up turns. **Note:** Context management is forcibly disabled for GPT-5.6 and above models (e.g. `gpt-5.6-sol`, `gpt-5.6-terra`, `gpt-5.6-luna`) because enabling it breaks prompt cache hits on those models. This override takes precedence over the `contextManagement` and `modelResponsesApiCompactThresholds` settings.\n - **modelResponsesApiCompactThresholds:** Per-model Responses API `compact_threshold` overrides used when the proxy adds `context_management`. These values take precedence over the fallback threshold from `resolveResponsesCompactThreshold` (`max_prompt_tokens * ratio`, or the default fallback). Defaults set `gpt-5.4` and `gpt-5.5` to `217600` (`272000 * 0.8`). Models not listed continue to use the normal fallback logic.\n- **modelReasoningEfforts:** Per-model fallback reasoning effort for `/v1/messages` requests. It is used only when the request does not provide `output_config.effort`.\n  - **Priority:** request `output_config.effort` > `modelReasoningEfforts[model]` > built-in default (`xhigh` for GPT-5.3+ models, otherwise `high`).\n  - **Forwarding:** the resolved value remains `output_config.effort` for the Copilot native Messages API and becomes `reasoning.effort` when translated to the Responses API.\n  - **Configuration values:** `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`.\n- **useMessagesApi:** When `true`, Claude-family models that support Copilot's native `/v1/messages` endpoint will use the Messages API; otherwise they fall back to `/chat/completions`. Set to `false` to disable Messages API routing and always use `/chat/completions`. Defaults to `true`.\n- **useResponsesApiWebSocket:** When `true`, Responses API requests use Copilot's websocket transport for models that advertise `ws:/responses`; models that only advertise `/responses` continue to use HTTP. Set to `false` to disable websocket routing and use HTTP `/responses` whenever the selected model supports it. Defaults to `true`. If the Responses API WebSocket gets closed, it is usually caused by your own network. If you are using a VPN, try switching to a different node.\n- **useResponsesApiWebSearch:** When `true`, the server keeps Responses API tools with `type: \"web_search\"` and forwards them upstream. Set to `false` to strip those tools from `/responses` payloads. Defaults to `true`.\n- **messageApiWebSearchModel:** Global fallback model used when a top-level Copilot `/v1/messages` request contains only the server-side `web_search` tool. Defaults to `gpt-5-mini`. If the value is a `provider/model` alias, the request is routed into that provider's Messages API path with the provider prefix stripped. For Copilot GPT models, web search runs through `/responses`. Mixed `web_search` plus custom tools are not supported and the server-side `web_search` tool is stripped.\n- **claudeTokenMultiplier:** Multiplier applied to the fallback GPT-tokenizer estimate for Claude `/v1/messages/count_tokens` requests. Defaults to `1.15`. Increase it if your client is still compacting too late. This setting is only used when the proxy is estimating Claude tokens locally; if `anthropicApiKey` is configured and Anthropic token counting succeeds, the exact Anthropic count is returned instead.\n- **anthropicApiKey:** Anthropic API key used to forward Claude `/v1/messages/count_tokens` requests to Anthropic's real token counting endpoint, which returns exact counts instead of GPT tokenizer estimates. Can also be set via the `ANTHROPIC_API_KEY` environment variable. If not set, or if the upstream call fails, token counting falls back to local GPT tokenizer estimation controlled by `claudeTokenMultiplier`.\n\nEdit this file to customize prompts or swap in your own fast model. Restart the server (or rerun the command) after changes so the cached config is refreshed.\n\n## API Authentication\n\n- **Protected non-admin routes:** All routes except `/`, `/usage-viewer`, and `/usage-viewer/` require authentication when `auth.apiKeys` is configured and non-empty.\n- **Admin routes:** All `/admin/*` routes require `auth.adminApiKey`. If it is missing, the server generates one at startup and persists it to `config.json` before serving requests.\n- **Allowed auth headers:**\n  - `x-api-key: <your_key>`\n  - `Authorization: Bearer <your_key>`\n- **CORS preflight:** `OPTIONS` requests are always allowed.\n- **When no regular keys are configured:** Non-admin routes continue to allow requests. This does not apply to `/admin/*`, which only accepts `auth.adminApiKey`.\n\nExample request for a regular protected route:\n\n```sh\ncurl http://localhost:4141/v1/models \\\n  -H \"x-api-key: your_api_key\"\n```\n\nExample request for an admin route:\n\n```sh\ncurl http://localhost:4141/admin/config/model-mappings \\\n  -H \"x-api-key: your_admin_api_key\"\n```\n\n## API Endpoints\n\nThe server exposes several OpenAI- and Anthropic-compatible endpoints. Requests can target GitHub Copilot, the built-in `codex` provider, or configured providers depending on the selected model and `provider/model` alias.\n\n### OpenAI Compatible Endpoints\n\nThese endpoints mimic the OpenAI API structure.\n\n| Endpoint                    | Method | Description                                                      |\n| --------------------------- | ------ | ---------------------------------------------------------------- |\n| `POST /v1/responses`        | `POST` | OpenAI Most advanced interface for generating model responses. Supports `provider/model` aliases for `openai-responses` providers. |\n| `POST /v1/chat/completions` | `POST` | Creates a model response for the given chat conversation. Supports `provider/model` aliases for `openai-compatible` providers and can be used without Copilot when the target provider is configured. |\n| `GET /v1/models`            | `GET`  | Lists Copilot models plus enabled provider models using `provider/model-id` IDs. Requests from Codex clients (`User-Agent` beginning with `codex`) are forwarded to the Codex Models upstream. |\n| `POST /v1/embeddings`       | `POST` | Creates an embedding vector representing the input text.         |\n\n### Codex Backend Proxy Endpoints\n\nThese endpoints require an active Codex login. Each endpoint is available both without a version prefix and under `/v1`.\n\n| Endpoint | Method | Description |\n| --- | --- | --- |\n| `POST /alpha/search`<br>`POST /v1/alpha/search` | `POST` | Transparently forwards the JSON body and query parameters to the Codex Alpha Search upstream. |\n| `POST /images/generations`<br>`POST /v1/images/generations` | `POST` | Forwards a JSON image generation request to the Codex Images upstream. When the request omits `Content-Type`, the gateway defaults it to `application/json`. |\n| `POST /images/edits`<br>`POST /v1/images/edits` | `POST` | Forwards an image edit request to the Codex Images upstream. Send this request as `multipart/form-data` and let the HTTP client generate the `boundary`; the gateway preserves the incoming content type and streams the upload body. |\n\nFor every endpoint above, the gateway replaces client authorization and account headers with the active Codex login, preserves query parameters and compatible request headers, and returns the upstream status, headers, and body.\n\n### Anthropic Compatible Endpoints\n\nThese endpoints are designed to be compatible with the Anthropic Messages API. Provider-scoped models, Responses, alpha-search, and images routes accept both unversioned and `/v1` paths; Messages routes remain under `/v1`.\n\n| Endpoint                         | Method | Description                                                  |\n| -------------------------------- | ------ | ------------------------------------------------------------ |\n| `POST /v1/messages`              | `POST` | Creates a model response for a given conversation. Supports `provider/model` aliases for configured providers, including translation through `openai-compatible` providers. |\n| `POST /v1/messages/count_tokens` | `POST` | Calculates the number of tokens for a given set of messages. Supports `provider/model` aliases for configured providers. |\n| `POST /:provider/v1/messages`       | `POST` | Proxies Anthropic Messages requests to the configured Anthropic provider, translates them through an OpenAI-compatible provider, or translates them through an OpenAI Responses provider. |\n| `GET /:provider/models`<br>`GET /:provider/v1/models` | `GET` | Proxies model listing requests to the configured provider. For `codex`, returns the built-in catalog by default; Codex clients (`User-Agent` starting with `codex`) are forwarded to the Codex Models upstream. |\n| `POST /:provider/v1/messages/count_tokens` | `POST` | Calculates tokens locally for provider route requests. |\n| `POST /:provider/responses`<br>`POST /:provider/v1/responses` | `POST` | Proxies OpenAI Responses requests to a configured `openai-responses` provider (including `codex`). |\n| `POST /:provider/alpha/search`<br>`POST /:provider/v1/alpha/search` | `POST` | Proxies alpha-search requests. For `codex`, forwards to the Codex Alpha Search upstream; for other providers, forwards to `{baseUrl}/v1/alpha/search`. |\n| `POST /:provider/images/generations`<br>`POST /:provider/v1/images/generations` | `POST` | Proxies image generation. For `codex`, uses the Codex Images upstream; for other providers, forwards to `{baseUrl}/v1/images/generations` (15-minute timeout). |\n| `POST /:provider/images/edits`<br>`POST /:provider/v1/images/edits` | `POST` | Proxies image edits. For `codex`, uses the Codex Images upstream; for other providers, forwards multipart/streamed bodies to `{baseUrl}/v1/images/edits` (15-minute timeout). |\n\n### Usage Monitoring Endpoints\n\nNew endpoints for monitoring your Copilot usage and quotas.\n\n| Endpoint     | Method | Description                                                  |\n| ------------ | ------ | ------------------------------------------------------------ |\n| `GET /usage` | `GET`  | Get detailed Copilot usage statistics and quota information. |\n| `GET /token` | `GET`  | Get the current Copilot token being used by the API.         |\n\n### Admin / Configuration Endpoints\n\nThese endpoints are reserved for local administrative actions and only accept `auth.adminApiKey`.\n\n| Endpoint                              | Method | Description                                                                 |\n| ------------------------------------- | ------ | --------------------------------------------------------------------------- |\n| `GET /admin/config/model-mappings`    | `GET`  | Returns the current `config.json` path and the active `modelMappings` map.  |\n| `POST /admin/config/model-mappings`   | `POST` | Updates only the `modelMappings` field in `config.json` and returns it back. |\n\n## Example Usage\n\nCommon `npx` commands:\n\n```sh\n# Start the gateway\nnpx @jeffreycao/copilot-api@latest start\n\n# Start on a custom port with verbose logging\nnpx @jeffreycao/copilot-api@latest start --port 8080 --verbose\n\n# Run the auth flow\nnpx @jeffreycao/copilot-api@latest auth login\n\n# Configure a third-party provider, then run without GitHub Copilot\nnpx @jeffreycao/copilot-api@latest auth login --provider dashscope\nnpx @jeffreycao/copilot-api@latest start\n\n# Print debug information as JSON\nnpx @jeffreycao/copilot-api@latest debug --json\n\n# Run the published CLI with Bun instead of Node.js\nbunx --bun @jeffreycao/copilot-api@latest start\n```\n\nOpenAI-compatible provider examples after configuring `dashscope`:\n\n```sh\ncurl http://localhost:4141/v1/chat/completions \\\n  -H \"content-type: application/json\" \\\n  -d '{\"model\":\"dashscope/qwen3.6-plus\",\"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]}'\n\ncurl http://localhost:4141/dashscope/v1/messages \\\n  -H \"content-type: application/json\" \\\n  -d '{\"model\":\"qwen3.6-plus\",\"max_tokens\":1024,\"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]}'\n```\n\n## Usage Tips\n\n### CLAUDE.md or AGENTS.md Recommended Content\n\nTo add these reminders manually, include the following in `CLAUDE.md` for Claude Code, or `AGENTS.md` for opencode/codex:\n\n```\n- Prohibited from directly asking questions to users, MUST use question tool.\n- Once you can confirm that the task is complete, MUST use question tool to make user confirm. The user may respond with feedback if they are not satisfied with the result, which you can use to make improvements and try again, after try again, MUST use question tool to make user confirm again.\n```\n"}, "25cf6508396ef7c5ce20335ea4414a01c32a7549": {"t": 1785765527.6808326, "n": 52153, "h": "3204752227a17af1", "c": "# Copilot API Proxy\n\nEnglish | [简体中文](./README.zh-CN.md)\n\n## Important Notes\n\n> [!IMPORTANT]\n> **Before using, please be aware of the following:**\n>\n> 1. **Claude Code configuration:** When using with Claude Code, please configure the model ID as `claude-opus-4-8`. Example claude `settings.json` see [Manual Configuration with `settings.json`](#manual-configuration-with-settingsjson). \n>\n> 2. **Built-in `copilot`, `codex` and third-party providers:** Run `npx @jeffreycao/copilot-api@latest auth` and choose `copilot`, `codex`, `deepseek`, `custom`, or other providers.\n>\n> 3. **Note:** See [GitHub Copilot Security Notice](./NOTICE.md#github-copilot-security-notice) for the warning removed from the README header.\n\n---\n\n## Project Overview\n\nA small AI gateway that can use GitHub Copilot, the built-in `codex` provider, or configured third-party providers such as DashScope. GitHub Copilot is optional: if no GitHub token is available, the server can still start in provider-only mode as long as at least one enabled provider is configured.\n\nThe gateway exposes OpenAI- and Anthropic-compatible APIs from one local endpoint, so tools like [Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview), OpenCode, Codex, and OpenAI-compatible clients can share the same local server.\n\nOn the GitHub Copilot path, the gateway prefers Copilot's native Anthropic-style Messages API when available, preserving more Claude-native behavior for tool-heavy workflows.\n\n## Features\n\n- **OpenAI and Anthropic compatibility**: Serve `/v1/responses`, `/v1/chat/completions`, `/v1/models`, `/v1/embeddings`, and `/v1/messages` from one local gateway.\n- **Copilot is optional**: Use GitHub Copilot when credentials are present, or run the server with only configured providers.\n- **One gateway for Copilot, `codex`, and external providers**: Route GitHub Copilot, the built-in `codex` provider, and configured third-party providers behind the same endpoint.\n- **Standalone third-party providers**: Configure providers such as DashScope, DeepSeek, OpenRouter, or a custom provider and start the gateway without a GitHub Copilot login.\n- **OpenAI-compatible providers on chat and Messages APIs**: `openai-compatible` providers can serve top-level `/v1/chat/completions` through `model: \"provider/model\"` and Anthropic-style `/v1/messages` through request/response translation.\n- **Agent-friendly Claude handling on Copilot**: Prefer native `/v1/messages` when available, preserve Claude-style tool flows, support Anthropic beta features, Claude WebSearch through Responses-capable models, and keep subagent/session markers intact.\n- **Claude Code and OpenCode integration**: Works with Claude Code and OpenCode, including direct Anthropic-compatible usage through `@ai-sdk/anthropic`.\n- **Flexible auth and deployment options**: Supports interactive login or direct tokens, individual/business/enterprise plans, GitHub Enterprise, opencode OAuth, and custom data directories.\n- **Multi-provider routing**: Expose provider-specific `/:provider/...` routes or use `model: \"provider/model\"` on the top-level API.\n\n## Prerequisites\n\n- Bun (>= 1.2.x)\n- Node.js if you plan to run the published CLI with `npx`\n- GitHub account with Copilot subscription only if you want to use the GitHub Copilot provider\n- An API key or OAuth login for at least one configured provider if you want to run without GitHub Copilot\n\n## Installation\n\nTo install dependencies, run:\n\n```sh\nbun install\n```\n\nTo start the server directly from source:\n\n```sh\nbun run start start\n```\n\n## Running from Source\n\nThe project can be run from source in several ways:\n\n### Development Mode\n\n```sh\nbun run dev start\n```\n\n### Production Mode\n\n```sh\nbun run start start\n```\n\n## Using with npx\n\nYou can run the project directly using npx:\n\n> [!IMPORTANT]\n> Token usage storage uses Node's built-in `node:sqlite` module when running with `npx`. It is enabled on Node.js >= 22.13.0. On Node.js < 22.13.0, the CLI still starts, but token usage storage is disabled.\n>\n> If you want token usage storage without upgrading Node.js, run the published CLI with Bun instead: `bunx --bun @jeffreycao/copilot-api@latest start`.\n\n```sh\nnpx @jeffreycao/copilot-api@latest start\n```\n\nWith options:\n\n```sh\nnpx @jeffreycao/copilot-api@latest start --port 8080\n```\n\nFor authentication or provider configuration only:\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth\n```\n\nTo run without GitHub Copilot, configure at least one provider first, then start the server normally:\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth login --provider dashscope\nnpx @jeffreycao/copilot-api@latest start\n```\n\n## Using with Docker\n\nBuild the image:\n\n```sh\ndocker build -t copilot-api .\n```\n\nRun the container with a bind mount so auth data survives restarts:\n\n```sh\nmkdir -p ./copilot-data\ndocker run -p 4141:4141 -v $(pwd)/copilot-data:/root/.local/share/copilot-api copilot-api\n```\n\nThis stores GitHub auth data, provider config, and other gateway state in `./copilot-data` on the host, mapped to `/root/.local/share/copilot-api` in the container.\n\nOr pass a GitHub token directly:\n\n```sh\ndocker run -p 4141:4141 -e GH_TOKEN=your_github_token_here copilot-api\n```\n\n## Electron Desktop App\n\nIf you prefer a GUI, this repository also includes an Electron desktop app in `desktop/`. It supports GitHub Copilot sign-in, OpenAI Codex OAuth, and API-key configuration for DeepSeek, DashScope, OpenRouter, or a custom provider. After authorization or provider configuration, it can start and stop the local proxy with one click and shows the local endpoint, auth header, available models, usage, and logs in the app.\n\nThe settings screen also exposes `OAuth App`, `API Home`, `Enterprise URL`, verbose logging, and minimize-to-tray. Windows x64 (`.exe`), macOS Apple Silicon (`.dmg`), and Linux x64 (`.AppImage`) packages are published in GitHub Releases:\n\nhttps://github.com/caozhiyuan/copilot-api/releases\n\nOn Linux, make the downloaded AppImage executable before launching it:\n\n```sh\nchmod +x Copilot-API-*-linux-x86_64.AppImage\n./Copilot-API-*-linux-x86_64.AppImage\n```\n\nDownload the installer for your platform, authorize or configure a provider inside the app, choose a port, start the server, then point your client at the local endpoint shown in the app. Packaged desktop builds use the bundled Electron runtime, so normal desktop usage does not require installing Node.js separately. Token usage history is enabled when that bundled runtime supports SQLite.\n\nThe desktop app's Advanced Config page reads and writes the shared model mappings through `GET/POST /admin/config/model-mappings`. The same mappings apply across `POST /v1/messages`, `POST /v1/messages/count_tokens`, `POST /v1/responses`, and `POST /v1/chat/completions` instead of being split per interface. It uses `auth.adminApiKey` instead of the regular `auth.apiKeys`, and the app reads that key directly from `config.json` after the server has generated it on startup.\n\n### Desktop App Screenshots\n\nMain dashboard, token usage breakdown in the bundled Electron app:\n\n<p align=\"center\">\n  <img src=\"./docs/screenshots/desktop-dashboard.png\" alt=\"Copilot API desktop app dashboard\" width=\"49%\" />\n  <img src=\"./docs/screenshots/desktop-token-usage.png\" alt=\"Copilot API desktop app token usage view\" width=\"49%\" />\n</p>\n\n## Using with Claude Code\n\nThis AI gateway can be used to power [Claude Code](https://docs.anthropic.com/en/claude-code), an experimental conversational AI assistant for developers from Anthropic.\n\nThere are two ways to configure Claude Code to use this AI gateway:\n\n### Interactive Setup with `--claude-code` flag\n\nTo get started, run the `start` command with the `--claude-code` flag:\n\n```sh\nnpx @jeffreycao/copilot-api@latest start --claude-code\n```\n\nYou will no longer be prompted to pick models manually. The gateway automatically detects the latest available model for each Claude Code size tier — opus maps to the newest Opus model, sonnet to the newest Sonnet model, and haiku to the newest Haiku model — and generates a command that sets `ANTHROPIC_DEFAULT_OPUS_MODEL`, `ANTHROPIC_DEFAULT_SONNET_MODEL`, and `ANTHROPIC_DEFAULT_HAIKU_MODEL` accordingly. Any tier without a matching model available is omitted. The command is copied to your clipboard and sets the environment variables needed for Claude Code to use the gateway.\n\nPaste and run this command in a new terminal to launch Claude Code.\n\n### Manual Configuration with `settings.json`\n\nAlternatively, you can configure Claude Code by creating a `.claude/settings.json` file in your project's root directory. This file should contain the environment variables needed by Claude Code. This way you don't need to run the interactive setup every time.\n\nHere is an example `.claude/settings.json` file:\n\n```json\n{\n  \"env\": {\n    \"ANTHROPIC_BASE_URL\": \"http://localhost:4141\",\n    \"ANTHROPIC_AUTH_TOKEN\": \"dummy\",\n    \"ANTHROPIC_MODEL\": \"gpt-5.6-sol[1m]\",\n    \"ANTHROPIC_DEFAULT_OPUS_MODEL\": \"gpt-5.6-sol[1m]\",\n    \"ANTHROPIC_DEFAULT_SONNET_MODEL\": \"gpt-5.6-sol[1m]\",\n    \"ANTHROPIC_DEFAULT_HAIKU_MODEL\": \"gpt-5.6-luna[1m]\",\n    \"CLAUDE_CODE_AUTO_COMPACT_WINDOW\": \"272000\",\n    \"CLAUDE_CODE_USE_VERTEX\": \"0\",\n    \"CLAUDE_CODE_USE_BEDROCK\": \"0\",\n    \"DISABLE_NON_ESSENTIAL_MODEL_CALLS\": \"1\",\n    \"CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC\": \"1\",\n    \"CLAUDE_CODE_ATTRIBUTION_HEADER\": \"0\",\n    \"CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION\": \"false\",\n    \"CLAUDE_CODE_DISABLE_TERMINAL_TITLE\": \"true\",\n    \"CLAUDE_CODE_ENABLE_AWAY_SUMMARY\": \"0\"\n  },\n  \"alwaysThinkingEnabled\": true,\n  \"effortLevel\": \"xhigh\",\n  \"showThinkingSummaries\": true\n}\n```\n\n- Replace `ANTHROPIC_MODEL`, `ANTHROPIC_DEFAULT_OPUS_MODEL`, `ANTHROPIC_DEFAULT_SONNET_MODEL`, and `ANTHROPIC_DEFAULT_HAIKU_MODEL` according to your needs. After configuration, please install the claude code plugin [Plugin Integrations](#plugin-integrations).  \n- If you are using the codex provider, it is recommended **not** to configure the model name in the `codex/xxx` format (e.g. `codex/gpt-5.6-sol`). Claude Code treats the `codex/` prefix as a special pattern and applies degraded behavior — for example, it strips all previously returned thinking blocks on every request. Use the plain model name (e.g. `gpt-5.6-sol`) instead, and add a `modelMappings` entry in `config.json` to route it back to the codex provider:\n  ```json\n  \"modelMappings\": {\n    \"gpt-5.6-sol\": \"codex/gpt-5.6-sol\",\n    \"gpt-5.6-terra\": \"codex/gpt-5.6-terra\",\n    \"gpt-5.6-luna\": \"codex/gpt-5.6-luna\"\n  },\n  ```\n- Setting CLAUDE_CODE_ATTRIBUTION_HEADER to 0 can prevent Claude code from adding billing and version information in system prompts, thereby avoiding prompt cache invalidation.\n- Turning off CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION and CLAUDE_CODE_ENABLE_AWAY_SUMMARY can prevent quota from being consumed unnecessarily.\n- Claude Code WebSearch is supported for pure search requests. For Copilot, keep the global `messageApiWebSearchModel` set to a Responses-capable GPT model or a `provider/model` alias. For provider routes, use a native Anthropic provider or an `openai-responses` provider. Add `WebSearch` to `permissions.deny` only if you want to forbid this traffic.\n- If using a non-Claude model, do not enable ENABLE_TOOL_SEARCH. If using the Claude model, can enable ENABLE_TOOL_SEARCH. The current Claude Code uses the client tool search mode. In this mode, loading defer tools requires an additional request each time.\n- `CLAUDE_CODE_AUTO_COMPACT_WINDOW`: Set the context capacity in tokens used for auto-compaction calculations. Defaults to the model's context window: 200K for standard models or 1M for extended context models. Use a lower value like `500000` on a 1M model (e.g., `claude-opus-4-6[1m]`) to treat the window as 500K for compaction purposes. The value is capped at the model's actual context window. `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` is applied as a percentage of this value. Setting this variable decouples the compaction threshold from the status line's `used_percentage`, which always uses the model's full context window.\n\nYou can find more options here: [Claude Code settings](https://docs.anthropic.com/en/docs/claude-code/settings#environment-variables)\n\nYou can also read more about IDE integration here: [Add Claude Code to your IDE](https://docs.anthropic.com/en/docs/claude-code/ide-integrations)\n\n## Using with OpenCode\n\nOpenCode already has a direct GitHub Copilot provider. Use this section when you want OpenCode to point at this AI gateway through `@ai-sdk/anthropic` and reuse the agent behaviors described earlier in this README.\n\n### Minimal setup\n\nStart the AI gateway with the OpenCode OAuth app:\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth --oauth-app=opencode\nnpx @jeffreycao/copilot-api@latest start\n```\n\nThen point OpenCode at the gateway with `@ai-sdk/anthropic`.\n\nExample `~/.config/opencode/opencode.json`:\n\n```json\n{\n  \"$schema\": \"https://opencode.ai/config.json\",\n  \"provider\": {\n    \"local\": {\n      \"npm\": \"@ai-sdk/anthropic\",\n      \"name\": \"My Local\",\n      \"options\": {\n        \"baseURL\": \"http://localhost:4141/v1\",\n        \"apiKey\": \"dummy\"\n      },\n      \"models\": {\n        \"gpt-5.4\": {\n          \"name\": \"gpt-5.4\",\n          \"modalities\": {\n            \"input\": [\"text\", \"image\"],\n            \"output\": [\"text\"]\n          },\n          \"limit\": {\n            \"context\": 400000,\n            \"input\": 272000,\n            \"output\": 128000\n          }\n        },\n        \"claude-sonnet-4.6\": {\n          \"id\": \"claude-sonnet-4.6\",\n          \"name\": \"claude-sonnet-4.6\",\n          \"modalities\": {\n            \"input\": [\"text\", \"image\"],\n            \"output\": [\"text\"]\n          },          \n          \"limit\": {\n            \"context\": 200000,\n            \"output\": 32000\n          },\n          \"options\": {\n            \"thinking\": {\n              \"type\": \"adaptive\"\n            },\n            \"effort\": \"max\"\n          }\n        }\n      }\n    }\n  }\n}\n```\n\nWhy these fields matter:\n\n- `npm: \"@ai-sdk/anthropic\"` is the important part. OpenCode will speak Anthropic Messages semantics to this AI gateway instead of flattening everything into OpenAI Chat Completions.\n- `options.baseURL` should be `http://localhost:4141/v1`; the Anthropic SDK will append `/messages`, `/models`, and `/messages/count_tokens` automatically.\n- If you enable `auth.apiKeys` in this AI gateway, replace `dummy` with a real key. Otherwise any placeholder value is fine.\n\n## Using with Codex\n\nThis AI gateway can also power Codex.\n\n### Codex `config.toml` Reference\n\nAdd the following `[model_providers.copilot_api]` section to your Codex `~/.codex/config.toml`:\n\n```toml\nmodel_provider = \"copilot_api\"\nmodel_reasoning_summary = \"auto\"\nmodel_context_window = 272000\nmodel_auto_compact_token_limit = 244800\n\n[model_providers.copilot_api]\nname = \"OpenAI\"\nbase_url = \"http://localhost:4141\"\nenv_key = \"GITHUB_COPILOT_API_KEY\"\nrequires_openai_auth = true\nsupports_websockets = false\nwire_api = \"responses\"\nrequest_max_retries = 3\nstream_max_retries = 1\nstream_idle_timeout_ms = 300000\n\n[features]\nremote_compaction_v2 = true\n\n[analytics]\nenabled = false\n```\n\n> [!NOTE]\n> This configuration is specific to Codex and the GitHub Copilot provider. `name` must be set to `\"OpenAI\"`. It can help mitigate Codex local compact cache miss issues.\n> If you are using the codex provider, it is recommended to set `base_url` to `\"http://localhost:4141/codex\"`.\n\n## GPT Tool Search\n\nFor GPT Responses models such as `gpt-5.4+`, this AI gateway can expose Responses `tool_search` through a small MCP bridge. The same bridge can be used by Claude Code and opencode, as long as the client loads MCP servers and sends Anthropic Messages traffic through this gateway.\n\nDo not set Claude Code's native `ENABLE_TOOL_SEARCH` for GPT models. That flag enables Claude Code's own client-side tool search mode, and it may stop forwarding deferred tool definitions. This gateway needs the full tool definitions so it can keep the small always-loaded tool set eager and translate every other tool into Responses deferred namespaces.\n\nIf you install `tool-search@copilot-api-marketplace`, Claude Code receives this MCP bridge automatically and you can skip the manual Claude Code MCP setup below.\n\nAdd the tool search bridge to the MCP config used by Claude Code:\n\n```json\n{\n  \"mcpServers\": {\n    \"tool_search\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@jeffreycao/copilot-api@latest\", \"mcp\"]\n    }\n  }\n}\n```\n\nAdd the tool search bridge to the MCP config used by opencode:\n\n```json\n{\n  \"mcp\": {\n    \"tool_search\": {\n      \"type\": \"local\",\n      \"command\": [\"npx\", \"-y\", \"@jeffreycao/copilot-api@latest\", \"mcp\"]\n    }\n  }\n}\n```\n\nFor local development, use `bun` as the command and `[\"run\", \"./src/main.ts\", \"mcp\"]` as the args.\n\nInternally, the gateway now configures OpenAI Responses `tool_search` in client-executed mode. Deferred tools are still exposed as searchable namespaces, but the model is explicitly asked to return the exact deferred tool names it wants to load next.\n\nThe bridge uses direct tool selection, not query search. Its tool input is `names`, a comma-separated list of exact deferred tool names, for example `TaskList,TaskGet,mcp__fetch__fetch`.\n\n## Plugin Integrations\n\nPlugin integrations are available for Claude Code and opencode.\n\n#### Claude Code plugin integration (marketplace-based)\n\nThe Claude Code integration is packaged as two plugins:\n\n- `agent-inject` injects `__SUBAGENT_MARKER__...` on `SubagentStart`, so the gateway can infer `x-initiator: agent`.\n- `tool-search` registers the `tool_search` MCP bridge used for GPT Responses deferred tool loading.\n\n- Marketplace catalog in this repository: `.claude-plugin/marketplace.json`\n- Plugin sources in this repository: `plugin/claude/agent-inject`, `plugin/claude/tool-search`\n\nAdd the marketplace remotely:\n\n```sh\n/plugin marketplace add https://github.com/caozhiyuan/copilot-api.git\n```\n\nInstall the plugins from the marketplace:\n\n```sh\n/plugin install agent-inject@copilot-api-marketplace\n/plugin install tool-search@copilot-api-marketplace\n```\n\nAfter installation, `agent-inject` injects `__SUBAGENT_MARKER__...` on `SubagentStart`, and the gateway uses it to infer `x-initiator: agent`.\n\nThe `agent-inject` plugin also registers a `UserPromptSubmit` hook that returns `{\"continue\": true}`, and it can inject `SessionStart` reminder rules through environment variables:\n\n- `CLAUDE_PLUGIN_ENABLE_QUESTION_RULES=1` enables the two reminders about using the `question` tool automatically for Claude Code. Alternatively, you can add the same reminders manually in `CLAUDE.md`; see [CLAUDE.md or AGENTS.md Recommended Content](#claudemd-or-agentsmd-recommended-content).\n- `CLAUDE_PLUGIN_ENABLE_NO_BACKGROUND_AGENTS_RULE=1` enables the `run_in_background: true` avoidance reminder for agent hooks.\n\nThe `tool-search` plugin bundles the same MCP bridge described in [GPT Tool Search](#gpt-tool-search), so Claude Code users do not need to add the `tool_search` server manually when they install that plugin.\n\n#### Opencode plugin\n\nThe subagent marker producer is packaged as an opencode plugin located at `plugin/opencode/subagent-marker.js`.\n\n**Installation:**\n\nCopy the plugin file to your opencode plugins directory:\n\n```sh\n# Clone or download this repository, then copy the plugin\ncp plugin/opencode/subagent-marker.js ~/.config/opencode/plugins/\n```\n\nOr manually create the file at `~/.config/opencode/plugins/subagent-marker.js` with the plugin content.\n\n**Features:**\n\n- Tracks sub-sessions created by subagents\n- Automatically prepends a marker system reminder (`__SUBAGENT_MARKER__...`) to subagent chat messages\n- Sets `x-session-id` header for session tracking\n- Enables the gateway to infer `x-initiator: agent` for subagent-originated requests\n\nThe plugin hooks into `session.created`, `session.deleted`, `chat.message`, and `chat.headers` events to provide seamless subagent marker functionality.\n\n## Using the Usage Viewer\n\nAfter starting the server, a URL to the Copilot Usage Dashboard will be displayed in your console. This dashboard is a web interface for monitoring your API usage.\n\n1.  Start the server. For example, using npx:\n    ```sh\n    npx @jeffreycao/copilot-api@latest start\n    ```\n2.  The server will output a URL to the usage viewer. Copy and paste this URL into your browser. It will look something like this:\n    `http://localhost:4141/usage-viewer?endpoint=http://localhost:4141/usage`\n    - If you use the `start.bat` script on Windows, this page will open automatically.\n\nThe dashboard provides a user-friendly interface to view your Copilot usage data:\n\n> Token usage history requires Bun or Node.js >= 22.13.0. On Node.js < 22.13.0, the server runs normally but token usage storage is disabled.\n\n- **API Endpoint URL**: The dashboard is pre-configured to fetch data from your local server endpoint via a URL query parameter. You can manually switch this to any other compatible API endpoint.\n- **x-api-key Authentication**: If API Key authentication is enabled, you can provide the `x-api-key` request header. The key is persisted in the browser's local storage.\n- **Period Selector**: Choose from Day, Week, or Month time ranges. The URL query parameter updates automatically when you switch, making it easy to bookmark and share.\n- **Fetch Data**: Click the \"Refresh\" button to load or refresh the usage data. The dashboard also fetches data automatically on page load.\n- **Copilot Quotas**: View quota usage for services such as Chat and Completions via progress bars. Hover over a card to see used/remaining details.\n- **Token Usage Metric Cards**: See a summary of Total, Input, Output, Cache Read, Cache Write, Requests, and estimated cost for the current period.\n- **Trend Chart (Week / Month)**: An interactive line chart with model and metric filters. Click a data point to inspect the usage breakdown for a specific day.\n- **Model Breakdown Table**: A per-model summary of requests, input/output/cache tokens, and estimated cost for the selected period.\n- **Request Events (Paginated)**: A time-sorted list of request event records with pagination support, showing timestamps, models, request IDs, and token counts.\n- **Detailed Information**: See the full JSON response from the API for a detailed breakdown of all available usage statistics.\n- **URL-based Configuration**: You can also specify the API endpoint and period directly via `endpoint` and `period` query parameters. For example:\n  `http://localhost:4141/usage-viewer?endpoint=http://your-api-server/usage&period=week`\n\n### Usage Viewer Screenshot\n\n<p align=\"center\">\n  <img src=\"./docs/screenshots/usage-viewer.png\" alt=\"Copilot API usage viewer\" width=\"900\" />\n</p>\n\n## Command Structure\n\nCopilot API now uses a subcommand structure with these main commands:\n\n- `start`: Start the gateway server. If a GitHub token is available, the server starts with Copilot enabled. If no GitHub token is available, it starts in provider-only mode when at least one enabled provider exists; otherwise it guides you through provider setup.\n- `auth`: Run provider login or configuration without starting the server. Use it for GitHub Copilot login, Codex OAuth, or third-party provider API key setup.\n- `debug`: Display diagnostic information including version, runtime details, file paths, and authentication status. Useful for troubleshooting and support.\n\n## Command Line Options\n\n### Global Options\n\nThe following options can be used with any subcommand. When passing them before the subcommand, use the `--key=value` form:\n\n| Option            | Description                                            | Default | Alias |\n| ----------------- | ------------------------------------------------------ | ------- | ----- |\n| --api-home        | Path to the API home directory (sets COPILOT_API_HOME) | none    | none  |\n| --oauth-app       | OAuth app identifier (sets COPILOT_API_OAUTH_APP)      | none    | none  |\n| --enterprise-url  | Enterprise URL for GitHub (sets COPILOT_API_ENTERPRISE_URL) | none | none |\n\n### Start Command Options\n\nThe following command line options are available for the `start` command:\n\n| Option         | Description                                                                   | Default    | Alias |\n| -------------- | ----------------------------------------------------------------------------- | ---------- | ----- |\n| --port         | Port to listen on                                                             | 4141       | -p    |\n| --verbose      | Enable verbose logging                                                        | false      | -v    |\n| --github-token | Provide GitHub token directly (must be generated using the `auth` subcommand) | none       | -g    |\n| --claude-code  | Generate a command to launch Claude Code with Copilot API config              | false      | -c    |\n| --show-token   | Show GitHub and Copilot tokens on fetch and refresh                           | false      | none  |\n| --proxy-env    | Initialize proxy from environment variables                                   | false      | none  |\n\n### Auth Command Options\n\n| Option       | Description               | Default | Alias |\n| ------------ | ------------------------- | ------- | ----- |\n| --provider   | Provider to log in with or configure (`copilot`, `codex`, `opencode-go`, `deepseek`, `dashscope`, `openrouter`, or `custom`) | prompt | none |\n| --verbose    | Enable verbose logging    | false   | -v    |\n| --show-token | Show GitHub token on auth | false   | none  |\n\nUse `copilot-api auth login --provider copilot` only when you want to enable the GitHub Copilot provider. Copilot is not required for `codex` or third-party provider-only usage.\n\nUse `copilot-api auth login --provider deepseek`, `--provider dashscope`, `--provider openrouter`, or `--provider opencode-go` to add or update those common third-party providers from the CLI. DeepSeek prompts for masked `apiKey`, provider `type` (default `anthropic`), and `baseUrl` defaulting to `https://api.deepseek.com/anthropic`. DashScope prompts for masked `apiKey`, provider `type` (default `openai-compatible`), and prefilled `baseUrl`. OpenRouter prompts for masked `apiKey` and prefilled `baseUrl` only, and writes `type: \"anthropic\"`. OpenCode Go prompts for masked `apiKey` and prefilled `baseUrl` only, and writes `type: \"openai-compatible\"` (baseUrl `https://opencode.ai/zen/go`). OpenCode Go additionally routes built-in `qwen*` and `minimax*` models through Anthropic Messages and `gpt*` models through OpenAI Responses; other models keep the OpenAI-compatible default. After a provider is configured and enabled, `copilot-api start` can run without any GitHub token.\n\nUse `copilot-api auth login --provider custom` to add or update another third-party provider from the CLI. The command prompts for the provider name, supported type (`anthropic`, `openai-compatible`, or `openai-responses`), `baseUrl`, masked `apiKey`, and `authType`; `authType` may be left as the type default or set to `x-api-key` / `authorization`.\n\n### Debug Command Options\n\n| Option | Description               | Default | Alias |\n| ------ | ------------------------- | ------- | ----- |\n| --json | Output debug info as JSON | false   | none  |\n\n## Configuration (config.json)\n\n- **Location:** `~/.local/share/copilot-api/config.json` (Linux/macOS) or `%USERPROFILE%\\.local\\share\\copilot-api\\config.json` (Windows).\n- **Default shape:**\n  ```json\n  {\n    \"auth\": {\n      \"apiKeys\": [],\n      \"adminApiKey\": \"<auto-generated-on-startup>\"\n    },\n    \"providers\": {},\n    \"modelMappings\": {},\n    \"extraPrompts\": {\n      \"gpt-5-mini\": \"<built-in exploration prompt>\"\n    },\n    \"smallModel\": \"gpt-5-mini\",\n    \"contextManagement\": {\n      \"messages\": true,\n      \"responses\": false\n    },\n    \"modelResponsesApiCompactThresholds\": {\n      \"gpt-5.4\": 217600,\n      \"gpt-5.5\": 217600\n    },\n    \"modelReasoningEfforts\": {\n      \"gpt-5-mini\": \"low\"\n    },\n    \"useMessagesApi\": true,\n    \"useResponsesApiWebSocket\": true,\n    \"useResponsesApiWebSearch\": true,\n    \"messageApiWebSearchModel\": \"gpt-5-mini\"\n  }\n  ```\n- **auth.apiKeys:** API keys used for request authentication on non-admin routes. Supports multiple keys for rotation. Requests can authenticate with either `x-api-key: <key>` or `Authorization: Bearer <key>`. If empty or omitted, authentication for non-admin routes is disabled.\n- **auth.adminApiKey:** Single admin key used only for `/admin/*` routes. If missing, the server generates a random key at startup and writes it back to `config.json`. Requests use the same `x-api-key` or `Authorization: Bearer` headers, but regular `auth.apiKeys` never grant access to `/admin/*`.\n- **modelMappings:** Exact `sourceModel -> targetModel` rewrites shared by top-level `POST /v1/messages`, `POST /v1/messages/count_tokens`, `POST /v1/responses`, and `POST /v1/chat/completions` requests. Omit it or leave it as `{}` to disable rewrites. Both the source and target must be non-empty strings. Targets can be regular model IDs or `provider/model` aliases such as `dashscope/qwen3.6-plus`, and the rewrite happens before provider alias parsing. These mappings are not split per interface. The admin endpoints `GET/POST /admin/config/model-mappings` read and update only this field.\n- **extraPrompts:** Map of `model -> prompt` appended to the first system prompt when translating Anthropic-style requests to Responses API. Use this to inject guardrails or guidance per model. Missing default entries are auto-added without overwriting your custom prompts. For GPT-5.3+ models (e.g. `gpt-5.3-codex`, `gpt-5.4`, `gpt-5.5`), a built-in commentary prompt is used as fallback when not explicitly configured. The built-in prompts enable phase-aware commentary, which lets the model emit a short user-facing progress update before tools or deeper reasoning.\n- **providers:** Global upstream provider map. Each provider key (for example `dashscope`) becomes a route prefix (`/dashscope/v1/messages`). Supports `type: \"anthropic\"`, `type: \"openai-compatible\"`, and `type: \"openai-responses\"`. Top-level clients can also use `model: \"dashscope/model-id\"` with `/v1/messages`, `/v1/messages/count_tokens`, `/v1/responses`, and `/v1/chat/completions`; the gateway strips the `dashscope/` prefix before forwarding upstream. `openai-compatible` providers support both chat and Messages flows: `/v1/chat/completions` is proxied to upstream `/v1/chat/completions`, while `/v1/messages` and `/:provider/v1/messages` are translated to upstream chat completions and translated back to Anthropic Messages responses. `GET /v1/models` aggregates enabled provider models with `provider/model-id` IDs; use `GET /dashscope/v1/models` for a single provider's raw model list.\n  - `enabled` defaults to `true` if omitted.\n  - `baseUrl` should be provider API base URL without the final endpoint. For Anthropic providers, omit `/v1/messages`; for OpenAI-compatible providers, omit `/v1/chat/completions`; for OpenAI Responses providers, omit `/v1/responses`.\n  - `apiKey` is used as the upstream credential value and is required for regular providers.\n  - `authType` (optional): Controls how `apiKey` is sent upstream. Supports `x-api-key` and `authorization` for regular providers. Anthropic providers default to `x-api-key`; OpenAI-compatible and OpenAI Responses providers default to `authorization`. When set to `authorization`, the proxy sends `Authorization: Bearer <apiKey>`. `oauth2` is reserved for the built-in `codex` provider and is written automatically by `auth login --provider codex`.\n  - `pricingCurrency` (optional): Provider-level currency used for token cost calculation, for example `USD` or `CNY`. Quick providers default to `CNY` for DashScope and DeepSeek, and `USD` for Codex/OpenRouter. Costs are grouped by currency and are not exchange-rate converted.\n  - `models` (optional): Per-model configuration map. Each key is a model ID (matching the model name in requests), and the value is:\n    - `temperature` (optional): Default temperature value used when the request does not specify one.\n    - `topP` (optional): Default top_p value used when the request does not specify one.\n    - `topK` (optional): Default top_k value used when the request does not specify one.\n    - `extraBody` (optional): Dynamic fields merged into the upstream request body for that model. Request body fields with the same name take precedence. OpenAI-compatible providers can use this for fields such as `enable_thinking`, `preserve_thinking`, `reasoning_effort`. `thinking_budget` is a special OpenAI-compatible provider override: when configured in `extraBody`, it is forced after Anthropic `thinking.budget_tokens` translation and overrides the request-derived budget. For providers whose name is `dashscope` or whose `baseUrl` contains `aliyuncs.com`, the request-derived `thinking_budget` (from Anthropic `thinking.budget_tokens`) is forwarded upstream; for other OpenAI-compatible providers the request-derived `thinking_budget` is stripped, while an `extraBody` `thinking_budget` is still honored. For DashScope providers, `preserve_thinking` defaults to `true` when not explicitly set in `extraBody` or the request body.\n    - `pricing` (optional): Per-model token prices, in the provider `pricingCurrency`, per 1M tokens. Supported fields are `input`, `output`, `cachedInput` (implicit cache read), `explicitCachedInput` (explicit cache read), and `cacheCreationInput`. Use `tiers` with `maxInputTokens` for input-size tiered pricing.\n    - `contextCache` (optional): Defaults to `true` for providers whose name is `dashscope` or whose `baseUrl` contains `aliyuncs.com`; defaults to `false` for other OpenAI-compatible providers. This enables Alibaba Cloud Model Studio/DashScope explicit context cache by injecting `cache_control: { \"type\": \"ephemeral\" }` on up to 4 content blocks using the Context Cache format. The cache breakpoint strategy matches opencode's main provider flow: the first 2 system messages plus the last 2 non-system messages. Marked string content is converted to text content part arrays for `system` / `user` / `assistant` / `tool` messages; existing array content is marked on the last part. Set this to `false` when the model already supports implicit caching, or when the upstream does not accept this explicit-cache extension field. Set this to `true` for non-DashScope providers that support the same explicit-cache extension. Applied on both `/v1/messages` and `/v1/chat/completions` routes.\n    - `supportPdf` (optional): Controls whether the model supports PDF/document content. Defaults to `false`; unsupported PDFs are converted to a text notice. Set it to `true` to send PDF/document blocks as OpenAI Chat Completions file parts.\n    - `toolContentSupportType` (optional): Tool result content capabilities for that model, as an array of `array`, `image`, and `pdf`. Provider routes default to string-only tool content when omitted. If `supportPdf` is `true` but this list does not include `pdf`, file parts in tool results are moved to user role messages. This provider default does not change the Copilot main flow, which continues to support array + image and not PDF.\n    - `type` (optional): Per-model override of the provider protocol type. Supports `anthropic`, `openai-compatible`, and `openai-responses`. When set, the provider's `/v1/messages` route uses this model's type instead of the provider-level type for request routing, auth header resolution, and upstream endpoint selection. This is useful for providers like OpenCode Go whose upstream supports both OpenAI-compatible and Anthropic Messages APIs for different models. When the type is overridden, the auth header is resolved from the overridden type's default (Anthropic defaults to `x-api-key`; OpenAI-compatible/Responses default to `authorization`).\n\n  Example DashScope model settings:\n  ```json\n  {\n    \"providers\": {\n      \"dashscope\": {\n        \"type\": \"openai-compatible\",\n        \"enabled\": true,\n        \"baseUrl\": \"https://dashscope.aliyuncs.com/compatible-mode\",\n        \"apiKey\": \"sk-your-dashscope-key\",\n        \"pricingCurrency\": \"CNY\",\n        \"models\": {\n          \"qwen3.7-plus\": {\n            \"temperature\": 1,\n            \"topP\": 0.95,\n            \"topK\": 20,\n            \"extraBody\": {\n              \"preserve_thinking\": true\n            }\n          },\n          \"glm-5.1\": {\n            \"temperature\": 0.7,\n            \"topP\": 0.95,\n            \"contextCache\": true,\n            \"pricing\": {\n              \"tiers\": [\n                {\n                  \"maxInputTokens\": 32000,\n                  \"input\": 6,\n                  \"cachedInput\": 1.2,\n                  \"explicitCachedInput\": 0.6,\n                  \"cacheCreationInput\": 7.5,\n                  \"output\": 24\n                },\n                {\n                  \"maxInputTokens\": 200000,\n                  \"input\": 8,\n                  \"cachedInput\": 1.6,\n                  \"explicitCachedInput\": 0.8,\n                  \"cacheCreationInput\": 10,\n                  \"output\": 28\n                }\n              ]\n            },\n            \"extraBody\": {\n              \"preserve_thinking\": true\n            }\n          }\n        }\n      }\n    }\n  }\n  ```\n  Built-in token prices cover Codex GPT models in USD, DashScope `qwen3.7-max`, `qwen3.7-plus`, `glm-5.1`, `glm-5.2` in CNY, DeepSeek `deepseek-v4-flash`, `deepseek-v4-pro`, `deepseek-chat`, `deepseek-reasoner` in CNY, and OpenCode Go models (`hy3`, `gpt-5.6-luna`, `glm-5.2`, `grok-4.5`, `deepseek-v4-flash`, `deepseek-v4-pro`, `kimi-k2.7-code`, `kimi-k3`, `mimo-v2.5`, `mimo-v2.5-pro`, `qwen3.7-plus`, `qwen3.7-max`, `minimax-m2.7`, `minimax-m3`) in USD. User `pricing` entries override built-ins. For DashScope, cached tokens are charged as explicit cache reads when the upstream usage includes `cache_creation_input_tokens`; otherwise `cachedInput` is used as the implicit cache read price. For DeepSeek, `prompt_cache_hit_tokens` map to cached input and `prompt_cache_miss_tokens` map to regular input.\n- **smallModel:** Fallback model used for tool-less warmup messages (e.g., Claude Code probe requests); defaults to gpt-5-mini. The gateway forces this small model on no-tool warmup or probe requests to avoid consuming premium requests. This behavior only applies to non-token-based-billing GitHub Copilot accounts (`token_based_billing` is false); for token-based-billing accounts the warmup small-model fallback is skipped since there is no premium-request quota to preserve.\n- **contextManagement:** Controls whether the proxy adds Responses API `context_management` compaction instructions. `messages` applies when Anthropic-style `/v1/messages` requests are translated to Responses API, including `openai-responses` provider message routes, and defaults to `true`. `responses` applies to native `/v1/responses` traffic, including `provider/model` aliases and the built-in `codex` provider, and defaults to `false`. Enable `responses` only after checking that your client supports context management compaction. When enabled, the request includes `context_management` in the body and keeps only the latest compaction carrier on follow-up turns. **Note:** Context management is forcibly disabled for GPT-5.6 and above models (e.g. `gpt-5.6-sol`, `gpt-5.6-terra`, `gpt-5.6-luna`) because enabling it breaks prompt cache hits on those models. This override takes precedence over the `contextManagement` and `modelResponsesApiCompactThresholds` settings.\n - **modelResponsesApiCompactThresholds:** Per-model Responses API `compact_threshold` overrides used when the proxy adds `context_management`. These values take precedence over the fallback threshold from `resolveResponsesCompactThreshold` (`max_prompt_tokens * ratio`, or the default fallback). Defaults set `gpt-5.4` and `gpt-5.5` to `217600` (`272000 * 0.8`). Models not listed continue to use the normal fallback logic.\n- **modelReasoningEfforts:** Per-model fallback reasoning effort for `/v1/messages` requests. It is used only when the request does not provide `output_config.effort`.\n  - **Priority:** request `output_config.effort` > `modelReasoningEfforts[model]` > built-in default (`xhigh` for GPT-5.3+ models, otherwise `high`).\n  - **Forwarding:** the resolved value remains `output_config.effort` for the Copilot native Messages API and becomes `reasoning.effort` when translated to the Responses API.\n  - **Configuration values:** `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`.\n- **useMessagesApi:** When `true`, Claude-family models that support Copilot's native `/v1/messages` endpoint will use the Messages API; otherwise they fall back to `/chat/completions`. Set to `false` to disable Messages API routing and always use `/chat/completions`. Defaults to `true`.\n- **useResponsesApiWebSocket:** When `true`, Responses API requests use Copilot's websocket transport for models that advertise `ws:/responses`; models that only advertise `/responses` continue to use HTTP. Set to `false` to disable websocket routing and use HTTP `/responses` whenever the selected model supports it. Defaults to `true`. If the Responses API WebSocket gets closed, it is usually caused by your own network. If you are using a VPN, try switching to a different node.\n- **useResponsesApiWebSearch:** When `true`, the server keeps Responses API tools with `type: \"web_search\"` and forwards them upstream. Set to `false` to strip those tools from `/responses` payloads. Defaults to `true`.\n- **messageApiWebSearchModel:** Global fallback model used when a top-level Copilot `/v1/messages` request contains only the server-side `web_search` tool. Defaults to `gpt-5-mini`. If the value is a `provider/model` alias, the request is routed into that provider's Messages API path with the provider prefix stripped. For Copilot GPT models, web search runs through `/responses`. Mixed `web_search` plus custom tools are not supported and the server-side `web_search` tool is stripped.\n- **claudeAutoModel:** Model used for Claude Code background security-monitor requests on `/v1/messages` and provider message routes. A request is treated as a security-monitor request when it carries no tools, sets `stop_sequences` to `[\"</block>\"]`, and contains a system text block starting with `You are a security monitor for autonomous AI coding agents.`; its model is then replaced with this value. For top-level requests, a `provider/model` alias is forwarded into that provider's Messages API; provider routes keep their current provider and use this configured value directly. Defaults to empty (disabled).\n- **claudeTokenMultiplier:** Multiplier applied to the fallback GPT-tokenizer estimate for Claude `/v1/messages/count_tokens` requests. Defaults to `1.15`. Increase it if your client is still compacting too late. This setting is only used when the proxy is estimating Claude tokens locally; if `anthropicApiKey` is configured and Anthropic token counting succeeds, the exact Anthropic count is returned instead.\n- **anthropicApiKey:** Anthropic API key used to forward Claude `/v1/messages/count_tokens` requests to Anthropic's real token counting endpoint, which returns exact counts instead of GPT tokenizer estimates. Can also be set via the `ANTHROPIC_API_KEY` environment variable. If not set, or if the upstream call fails, token counting falls back to local GPT tokenizer estimation controlled by `claudeTokenMultiplier`.\n\nEdit this file to customize prompts or swap in your own fast model. Restart the server (or rerun the command) after changes so the cached config is refreshed.\n\n## API Authentication\n\n- **Protected non-admin routes:** All routes except `/`, `/usage-viewer`, and `/usage-viewer/` require authentication when `auth.apiKeys` is configured and non-empty.\n- **Admin routes:** All `/admin/*` routes require `auth.adminApiKey`. If it is missing, the server generates one at startup and persists it to `config.json` before serving requests.\n- **Allowed auth headers:**\n  - `x-api-key: <your_key>`\n  - `Authorization: Bearer <your_key>`\n- **CORS preflight:** `OPTIONS` requests are always allowed.\n- **When no regular keys are configured:** Non-admin routes continue to allow requests. This does not apply to `/admin/*`, which only accepts `auth.adminApiKey`.\n\nExample request for a regular protected route:\n\n```sh\ncurl http://localhost:4141/v1/models \\\n  -H \"x-api-key: your_api_key\"\n```\n\nExample request for an admin route:\n\n```sh\ncurl http://localhost:4141/admin/config/model-mappings \\\n  -H \"x-api-key: your_admin_api_key\"\n```\n\n## API Endpoints\n\nThe server exposes several OpenAI- and Anthropic-compatible endpoints. Requests can target GitHub Copilot, the built-in `codex` provider, or configured providers depending on the selected model and `provider/model` alias.\n\n### OpenAI Compatible Endpoints\n\nThese endpoints mimic the OpenAI API structure.\n\n| Endpoint                    | Method | Description                                                      |\n| --------------------------- | ------ | ---------------------------------------------------------------- |\n| `POST /v1/responses`        | `POST` | OpenAI Most advanced interface for generating model responses. Supports `provider/model` aliases for `openai-responses` providers. |\n| `POST /v1/chat/completions` | `POST` | Creates a model response for the given chat conversation. Supports `provider/model` aliases for `openai-compatible` providers and can be used without Copilot when the target provider is configured. |\n| `GET /v1/models`            | `GET`  | Lists Copilot models plus enabled provider models using `provider/model-id` IDs. Requests from Codex clients (`User-Agent` beginning with `codex`) are forwarded to the Codex Models upstream. |\n| `POST /v1/embeddings`       | `POST` | Creates an embedding vector representing the input text.         |\n\n### Codex Backend Proxy Endpoints\n\nThese endpoints require an active Codex login. Each endpoint is available both without a version prefix and under `/v1`.\n\n| Endpoint | Method | Description |\n| --- | --- | --- |\n| `POST /alpha/search`<br>`POST /v1/alpha/search` | `POST` | Transparently forwards the JSON body and query parameters to the Codex Alpha Search upstream. |\n| `POST /images/generations`<br>`POST /v1/images/generations` | `POST` | Forwards a JSON image generation request to the Codex Images upstream. When the request omits `Content-Type`, the gateway defaults it to `application/json`. |\n| `POST /images/edits`<br>`POST /v1/images/edits` | `POST` | Forwards an image edit request to the Codex Images upstream. Send this request as `multipart/form-data` and let the HTTP client generate the `boundary`; the gateway preserves the incoming content type and streams the upload body. |\n\nFor every endpoint above, the gateway replaces client authorization and account headers with the active Codex login, preserves query parameters and compatible request headers, and returns the upstream status, headers, and body.\n\n### Anthropic Compatible Endpoints\n\nThese endpoints are designed to be compatible with the Anthropic Messages API. Provider-scoped models, Responses, alpha-search, and images routes accept both unversioned and `/v1` paths; Messages routes remain under `/v1`.\n\n| Endpoint                         | Method | Description                                                  |\n| -------------------------------- | ------ | ------------------------------------------------------------ |\n| `POST /v1/messages`              | `POST` | Creates a model response for a given conversation. Supports `provider/model` aliases for configured providers, including translation through `openai-compatible` providers. |\n| `POST /v1/messages/count_tokens` | `POST` | Calculates the number of tokens for a given set of messages. Supports `provider/model` aliases for configured providers. |\n| `POST /:provider/v1/messages`       | `POST` | Proxies Anthropic Messages requests to the configured Anthropic provider, translates them through an OpenAI-compatible provider, or translates them through an OpenAI Responses provider. |\n| `GET /:provider/models`<br>`GET /:provider/v1/models` | `GET` | Proxies model listing requests to the configured provider. For `codex`, returns the built-in catalog by default; Codex clients (`User-Agent` starting with `codex`) are forwarded to the Codex Models upstream. |\n| `POST /:provider/v1/messages/count_tokens` | `POST` | Calculates tokens locally for provider route requests. |\n| `POST /:provider/responses`<br>`POST /:provider/v1/responses` | `POST` | Proxies OpenAI Responses requests to a configured `openai-responses` provider (including `codex`). |\n| `POST /:provider/alpha/search`<br>`POST /:provider/v1/alpha/search` | `POST` | Proxies alpha-search requests. For `codex`, forwards to the Codex Alpha Search upstream; for other providers, forwards to `{baseUrl}/v1/alpha/search`. |\n| `POST /:provider/images/generations`<br>`POST /:provider/v1/images/generations` | `POST` | Proxies image generation. For `codex`, uses the Codex Images upstream; for other providers, forwards to `{baseUrl}/v1/images/generations` (15-minute timeout). |\n| `POST /:provider/images/edits`<br>`POST /:provider/v1/images/edits` | `POST` | Proxies image edits. For `codex`, uses the Codex Images upstream; for other providers, forwards multipart/streamed bodies to `{baseUrl}/v1/images/edits` (15-minute timeout). |\n\n### Usage Monitoring Endpoints\n\nNew endpoints for monitoring your Copilot usage and quotas.\n\n| Endpoint     | Method | Description                                                  |\n| ------------ | ------ | ------------------------------------------------------------ |\n| `GET /usage` | `GET`  | Get detailed Copilot usage statistics and quota information. |\n| `GET /token` | `GET`  | Get the current Copilot token being used by the API.         |\n\n### Admin / Configuration Endpoints\n\nThese endpoints are reserved for local administrative actions and only accept `auth.adminApiKey`.\n\n| Endpoint                              | Method | Description                                                                 |\n| ------------------------------------- | ------ | --------------------------------------------------------------------------- |\n| `GET /admin/config/model-mappings`    | `GET`  | Returns the current `config.json` path and the active `modelMappings` map.  |\n| `POST /admin/config/model-mappings`   | `POST` | Updates only the `modelMappings` field in `config.json` and returns it back. |\n\n## Example Usage\n\nCommon `npx` commands:\n\n```sh\n# Start the gateway\nnpx @jeffreycao/copilot-api@latest start\n\n# Start on a custom port with verbose logging\nnpx @jeffreycao/copilot-api@latest start --port 8080 --verbose\n\n# Run the auth flow\nnpx @jeffreycao/copilot-api@latest auth login\n\n# Configure a third-party provider, then run without GitHub Copilot\nnpx @jeffreycao/copilot-api@latest auth login --provider dashscope\nnpx @jeffreycao/copilot-api@latest start\n\n# Print debug information as JSON\nnpx @jeffreycao/copilot-api@latest debug --json\n\n# Run the published CLI with Bun instead of Node.js\nbunx --bun @jeffreycao/copilot-api@latest start\n```\n\nOpenAI-compatible provider examples after configuring `dashscope`:\n\n```sh\ncurl http://localhost:4141/v1/chat/completions \\\n  -H \"content-type: application/json\" \\\n  -d '{\"model\":\"dashscope/qwen3.6-plus\",\"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]}'\n\ncurl http://localhost:4141/dashscope/v1/messages \\\n  -H \"content-type: application/json\" \\\n  -d '{\"model\":\"qwen3.6-plus\",\"max_tokens\":1024,\"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]}'\n```\n\n## Usage Tips\n\n### CLAUDE.md or AGENTS.md Recommended Content\n\nTo add these reminders manually, include the following in `CLAUDE.md` for Claude Code, or `AGENTS.md` for opencode/codex:\n\n```\n- Prohibited from directly asking questions to users, MUST use question tool.\n- Once you can confirm that the task is complete, MUST use question tool to make user confirm. The user may respond with feedback if they are not satisfied with the result, which you can use to make improvements and try again, after try again, MUST use question tool to make user confirm again.\n```\n"}, "69601b83760614c5b3edb65a27c7a881a6e3f0e2": {"t": 1785765529.2476854, "n": 51536, "h": "f497851251f7478e", "c": "# Copilot API Proxy\n\nEnglish | [简体中文](./README.zh-CN.md)\n\n## Important Notes\n\n> [!IMPORTANT]\n> **Before using, please be aware of the following:**\n>\n> 1. **Claude Code configuration:** When using with Claude Code, please configure the model ID as `claude-opus-4-8`. Example claude `settings.json` see [Manual Configuration with `settings.json`](#manual-configuration-with-settingsjson). \n>\n> 2. **Built-in `copilot`, `codex` and third-party providers:** Run `npx @jeffreycao/copilot-api@latest auth` and choose `copilot`, `codex`, `deepseek`, `custom`, or other providers.\n>\n> 3. **Note:** See [GitHub Copilot Security Notice](./NOTICE.md#github-copilot-security-notice) for the warning removed from the README header.\n\n---\n\n## Project Overview\n\nA small AI gateway that can use GitHub Copilot, the built-in `codex` provider, or configured third-party providers such as DashScope. GitHub Copilot is optional: if no GitHub token is available, the server can still start in provider-only mode as long as at least one enabled provider is configured.\n\nThe gateway exposes OpenAI- and Anthropic-compatible APIs from one local endpoint, so tools like [Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview), OpenCode, Codex, and OpenAI-compatible clients can share the same local server.\n\nOn the GitHub Copilot path, the gateway prefers Copilot's native Anthropic-style Messages API when available, preserving more Claude-native behavior for tool-heavy workflows.\n\n## Features\n\n- **OpenAI and Anthropic compatibility**: Serve `/v1/responses`, `/v1/chat/completions`, `/v1/models`, `/v1/embeddings`, and `/v1/messages` from one local gateway.\n- **Copilot is optional**: Use GitHub Copilot when credentials are present, or run the server with only configured providers.\n- **One gateway for Copilot, `codex`, and external providers**: Route GitHub Copilot, the built-in `codex` provider, and configured third-party providers behind the same endpoint.\n- **Standalone third-party providers**: Configure providers such as DashScope, DeepSeek, OpenRouter, or a custom provider and start the gateway without a GitHub Copilot login.\n- **OpenAI-compatible providers on chat and Messages APIs**: `openai-compatible` providers can serve top-level `/v1/chat/completions` through `model: \"provider/model\"` and Anthropic-style `/v1/messages` through request/response translation.\n- **Agent-friendly Claude handling on Copilot**: Prefer native `/v1/messages` when available, preserve Claude-style tool flows, support Anthropic beta features, Claude WebSearch through Responses-capable models, and keep subagent/session markers intact.\n- **Claude Code and OpenCode integration**: Works with Claude Code and OpenCode, including direct Anthropic-compatible usage through `@ai-sdk/anthropic`.\n- **Flexible auth and deployment options**: Supports interactive login or direct tokens, individual/business/enterprise plans, GitHub Enterprise, opencode OAuth, and custom data directories.\n- **Multi-provider routing**: Expose provider-specific `/:provider/...` routes or use `model: \"provider/model\"` on the top-level API.\n\n## Prerequisites\n\n- Bun (>= 1.2.x)\n- Node.js if you plan to run the published CLI with `npx`\n- GitHub account with Copilot subscription only if you want to use the GitHub Copilot provider\n- An API key or OAuth login for at least one configured provider if you want to run without GitHub Copilot\n\n## Installation\n\nTo install dependencies, run:\n\n```sh\nbun install\n```\n\nTo start the server directly from source:\n\n```sh\nbun run start start\n```\n\n## Running from Source\n\nThe project can be run from source in several ways:\n\n### Development Mode\n\n```sh\nbun run dev start\n```\n\n### Production Mode\n\n```sh\nbun run start start\n```\n\n## Using with npx\n\nYou can run the project directly using npx:\n\n> [!IMPORTANT]\n> Token usage storage uses Node's built-in `node:sqlite` module when running with `npx`. It is enabled on Node.js >= 22.13.0. On Node.js < 22.13.0, the CLI still starts, but token usage storage is disabled.\n>\n> If you want token usage storage without upgrading Node.js, run the published CLI with Bun instead: `bunx --bun @jeffreycao/copilot-api@latest start`.\n\n```sh\nnpx @jeffreycao/copilot-api@latest start\n```\n\nWith options:\n\n```sh\nnpx @jeffreycao/copilot-api@latest start --port 8080\n```\n\nFor authentication or provider configuration only:\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth\n```\n\nTo run without GitHub Copilot, configure at least one provider first, then start the server normally:\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth login --provider dashscope\nnpx @jeffreycao/copilot-api@latest start\n```\n\n## Using with Docker\n\nBuild the image:\n\n```sh\ndocker build -t copilot-api .\n```\n\nRun the container with a bind mount so auth data survives restarts:\n\n```sh\nmkdir -p ./copilot-data\ndocker run -p 4141:4141 -v $(pwd)/copilot-data:/root/.local/share/copilot-api copilot-api\n```\n\nThis stores GitHub auth data, provider config, and other gateway state in `./copilot-data` on the host, mapped to `/root/.local/share/copilot-api` in the container.\n\nOr pass a GitHub token directly:\n\n```sh\ndocker run -p 4141:4141 -e GH_TOKEN=your_github_token_here copilot-api\n```\n\n## Electron Desktop App\n\nIf you prefer a GUI, this repository also includes an Electron desktop app in `desktop/`. It supports GitHub Copilot sign-in, OpenAI Codex OAuth, and API-key configuration for DeepSeek, DashScope, OpenRouter, or a custom provider. After authorization or provider configuration, it can start and stop the local proxy with one click and shows the local endpoint, auth header, available models, usage, and logs in the app.\n\nThe settings screen also exposes `OAuth App`, `API Home`, `Enterprise URL`, verbose logging, and minimize-to-tray. Windows x64 (`.exe`), macOS Apple Silicon (`.dmg`), and Linux x64 (`.AppImage`) packages are published in GitHub Releases:\n\nhttps://github.com/caozhiyuan/copilot-api/releases\n\nOn Linux, make the downloaded AppImage executable before launching it:\n\n```sh\nchmod +x Copilot-API-*-linux-x86_64.AppImage\n./Copilot-API-*-linux-x86_64.AppImage\n```\n\nDownload the installer for your platform, authorize or configure a provider inside the app, choose a port, start the server, then point your client at the local endpoint shown in the app. Packaged desktop builds use the bundled Electron runtime, so normal desktop usage does not require installing Node.js separately. Token usage history is enabled when that bundled runtime supports SQLite.\n\nThe desktop app's Advanced Config page reads and writes the shared model mappings through `GET/POST /admin/config/model-mappings`. The same mappings apply across `POST /v1/messages`, `POST /v1/messages/count_tokens`, `POST /v1/responses`, and `POST /v1/chat/completions` instead of being split per interface. It uses `auth.adminApiKey` instead of the regular `auth.apiKeys`, and the app reads that key directly from `config.json` after the server has generated it on startup.\n\n### Desktop App Screenshots\n\nMain dashboard, token usage breakdown in the bundled Electron app:\n\n<p align=\"center\">\n  <img src=\"./docs/screenshots/desktop-dashboard.png\" alt=\"Copilot API desktop app dashboard\" width=\"49%\" />\n  <img src=\"./docs/screenshots/desktop-token-usage.png\" alt=\"Copilot API desktop app token usage view\" width=\"49%\" />\n</p>\n\n## Using with Claude Code\n\nThis AI gateway can be used to power [Claude Code](https://docs.anthropic.com/en/claude-code), an experimental conversational AI assistant for developers from Anthropic.\n\nThere are two ways to configure Claude Code to use this AI gateway:\n\n### Interactive Setup with `--claude-code` flag\n\nTo get started, run the `start` command with the `--claude-code` flag:\n\n```sh\nnpx @jeffreycao/copilot-api@latest start --claude-code\n```\n\nYou will no longer be prompted to pick models manually. The gateway automatically detects the latest available model for each Claude Code size tier — opus maps to the newest Opus model, sonnet to the newest Sonnet model, and haiku to the newest Haiku model — and generates a command that sets `ANTHROPIC_DEFAULT_OPUS_MODEL`, `ANTHROPIC_DEFAULT_SONNET_MODEL`, and `ANTHROPIC_DEFAULT_HAIKU_MODEL` accordingly. Any tier without a matching model available is omitted. The command is copied to your clipboard and sets the environment variables needed for Claude Code to use the gateway.\n\nPaste and run this command in a new terminal to launch Claude Code.\n\n### Manual Configuration with `settings.json`\n\nAlternatively, you can configure Claude Code by creating a `.claude/settings.json` file in your project's root directory. This file should contain the environment variables needed by Claude Code. This way you don't need to run the interactive setup every time.\n\nHere is an example `.claude/settings.json` file:\n\n```json\n{\n  \"env\": {\n    \"ANTHROPIC_BASE_URL\": \"http://localhost:4141\",\n    \"ANTHROPIC_AUTH_TOKEN\": \"dummy\",\n    \"ANTHROPIC_MODEL\": \"gpt-5.6-sol[1m]\",\n    \"ANTHROPIC_DEFAULT_OPUS_MODEL\": \"gpt-5.6-sol[1m]\",\n    \"ANTHROPIC_DEFAULT_SONNET_MODEL\": \"gpt-5.6-sol[1m]\",\n    \"ANTHROPIC_DEFAULT_HAIKU_MODEL\": \"gpt-5.6-luna[1m]\",\n    \"CLAUDE_CODE_AUTO_COMPACT_WINDOW\": \"272000\",\n    \"CLAUDE_CODE_USE_VERTEX\": \"0\",\n    \"CLAUDE_CODE_USE_BEDROCK\": \"0\",\n    \"DISABLE_NON_ESSENTIAL_MODEL_CALLS\": \"1\",\n    \"CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC\": \"1\",\n    \"CLAUDE_CODE_ATTRIBUTION_HEADER\": \"0\",\n    \"CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION\": \"false\",\n    \"CLAUDE_CODE_DISABLE_TERMINAL_TITLE\": \"true\",\n    \"CLAUDE_CODE_ENABLE_AWAY_SUMMARY\": \"0\"\n  },\n  \"alwaysThinkingEnabled\": true,\n  \"effortLevel\": \"xhigh\",\n  \"showThinkingSummaries\": true\n}\n```\n\n- Replace `ANTHROPIC_MODEL`, `ANTHROPIC_DEFAULT_OPUS_MODEL`, `ANTHROPIC_DEFAULT_SONNET_MODEL`, and `ANTHROPIC_DEFAULT_HAIKU_MODEL` according to your needs. After configuration, please install the claude code plugin [Plugin Integrations](#plugin-integrations).  \n- If you are using the codex provider, it is recommended **not** to configure the model name in the `codex/xxx` format (e.g. `codex/gpt-5.6-sol`). Claude Code treats the `codex/` prefix as a special pattern and applies degraded behavior — for example, it strips all previously returned thinking blocks on every request. Use the plain model name (e.g. `gpt-5.6-sol`) instead, and add a `modelMappings` entry in `config.json` to route it back to the codex provider:\n  ```json\n  \"modelMappings\": {\n    \"gpt-5.6-sol\": \"codex/gpt-5.6-sol\",\n    \"gpt-5.6-terra\": \"codex/gpt-5.6-terra\",\n    \"gpt-5.6-luna\": \"codex/gpt-5.6-luna\"\n  },\n  ```\n- Setting CLAUDE_CODE_ATTRIBUTION_HEADER to 0 can prevent Claude code from adding billing and version information in system prompts, thereby avoiding prompt cache invalidation.\n- Turning off CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION and CLAUDE_CODE_ENABLE_AWAY_SUMMARY can prevent quota from being consumed unnecessarily.\n- Claude Code WebSearch is supported for pure search requests. For Copilot, keep the global `messageApiWebSearchModel` set to a Responses-capable GPT model or a `provider/model` alias. For provider routes, use a native Anthropic provider or an `openai-responses` provider. Add `WebSearch` to `permissions.deny` only if you want to forbid this traffic.\n- If using a non-Claude model, do not enable ENABLE_TOOL_SEARCH. If using the Claude model, can enable ENABLE_TOOL_SEARCH. The current Claude Code uses the client tool search mode. In this mode, loading defer tools requires an additional request each time.\n- `CLAUDE_CODE_AUTO_COMPACT_WINDOW`: Set the context capacity in tokens used for auto-compaction calculations. Defaults to the model's context window: 200K for standard models or 1M for extended context models. Use a lower value like `500000` on a 1M model (e.g., `claude-opus-4-6[1m]`) to treat the window as 500K for compaction purposes. The value is capped at the model's actual context window. `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` is applied as a percentage of this value. Setting this variable decouples the compaction threshold from the status line's `used_percentage`, which always uses the model's full context window.\n\nYou can find more options here: [Claude Code settings](https://docs.anthropic.com/en/docs/claude-code/settings#environment-variables)\n\nYou can also read more about IDE integration here: [Add Claude Code to your IDE](https://docs.anthropic.com/en/docs/claude-code/ide-integrations)\n\n## Using with OpenCode\n\nOpenCode already has a direct GitHub Copilot provider. Use this section when you want OpenCode to point at this AI gateway through `@ai-sdk/anthropic` and reuse the agent behaviors described earlier in this README.\n\n### Minimal setup\n\nStart the AI gateway with the OpenCode OAuth app:\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth --oauth-app=opencode\nnpx @jeffreycao/copilot-api@latest start\n```\n\nThen point OpenCode at the gateway with `@ai-sdk/anthropic`.\n\nExample `~/.config/opencode/opencode.json`:\n\n```json\n{\n  \"$schema\": \"https://opencode.ai/config.json\",\n  \"provider\": {\n    \"local\": {\n      \"npm\": \"@ai-sdk/anthropic\",\n      \"name\": \"My Local\",\n      \"options\": {\n        \"baseURL\": \"http://localhost:4141/v1\",\n        \"apiKey\": \"dummy\"\n      },\n      \"models\": {\n        \"gpt-5.4\": {\n          \"name\": \"gpt-5.4\",\n          \"modalities\": {\n            \"input\": [\"text\", \"image\"],\n            \"output\": [\"text\"]\n          },\n          \"limit\": {\n            \"context\": 400000,\n            \"input\": 272000,\n            \"output\": 128000\n          }\n        },\n        \"claude-sonnet-4.6\": {\n          \"id\": \"claude-sonnet-4.6\",\n          \"name\": \"claude-sonnet-4.6\",\n          \"modalities\": {\n            \"input\": [\"text\", \"image\"],\n            \"output\": [\"text\"]\n          },          \n          \"limit\": {\n            \"context\": 200000,\n            \"output\": 32000\n          },\n          \"options\": {\n            \"thinking\": {\n              \"type\": \"adaptive\"\n            },\n            \"effort\": \"max\"\n          }\n        }\n      }\n    }\n  }\n}\n```\n\nWhy these fields matter:\n\n- `npm: \"@ai-sdk/anthropic\"` is the important part. OpenCode will speak Anthropic Messages semantics to this AI gateway instead of flattening everything into OpenAI Chat Completions.\n- `options.baseURL` should be `http://localhost:4141/v1`; the Anthropic SDK will append `/messages`, `/models`, and `/messages/count_tokens` automatically.\n- If you enable `auth.apiKeys` in this AI gateway, replace `dummy` with a real key. Otherwise any placeholder value is fine.\n\n## Using with Codex\n\nThis AI gateway can also power Codex.\n\n### Codex `config.toml` Reference\n\nAdd the following `[model_providers.copilot_api]` section to your Codex `~/.codex/config.toml`:\n\n```toml\nmodel_provider = \"copilot_api\"\nmodel_reasoning_summary = \"auto\"\nmodel_context_window = 272000\nmodel_auto_compact_token_limit = 244800\n\n[model_providers.copilot_api]\nname = \"OpenAI\"\nbase_url = \"http://localhost:4141\"\nenv_key = \"GITHUB_COPILOT_API_KEY\"\nrequires_openai_auth = true\nsupports_websockets = false\nwire_api = \"responses\"\nrequest_max_retries = 3\nstream_max_retries = 1\nstream_idle_timeout_ms = 300000\n\n[features]\nremote_compaction_v2 = true\n\n[analytics]\nenabled = false\n```\n\n> [!NOTE]\n> This configuration is specific to Codex and the GitHub Copilot provider. `name` must be set to `\"OpenAI\"`. It can help mitigate Codex local compact cache miss issues.\n> If you are using the codex provider, it is recommended to set `base_url` to `\"http://localhost:4141/codex\"`.\n\n## GPT Tool Search\n\nFor GPT Responses models such as `gpt-5.4+`, this AI gateway can expose Responses `tool_search` through a small MCP bridge. The same bridge can be used by Claude Code and opencode, as long as the client loads MCP servers and sends Anthropic Messages traffic through this gateway.\n\nDo not set Claude Code's native `ENABLE_TOOL_SEARCH` for GPT models. That flag enables Claude Code's own client-side tool search mode, and it may stop forwarding deferred tool definitions. This gateway needs the full tool definitions so it can keep the small always-loaded tool set eager and translate every other tool into Responses deferred namespaces.\n\nIf you install `tool-search@copilot-api-marketplace`, Claude Code receives this MCP bridge automatically and you can skip the manual Claude Code MCP setup below.\n\nAdd the tool search bridge to the MCP config used by Claude Code:\n\n```json\n{\n  \"mcpServers\": {\n    \"tool_search\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@jeffreycao/copilot-api@latest\", \"mcp\"]\n    }\n  }\n}\n```\n\nAdd the tool search bridge to the MCP config used by opencode:\n\n```json\n{\n  \"mcp\": {\n    \"tool_search\": {\n      \"type\": \"local\",\n      \"command\": [\"npx\", \"-y\", \"@jeffreycao/copilot-api@latest\", \"mcp\"]\n    }\n  }\n}\n```\n\nFor local development, use `bun` as the command and `[\"run\", \"./src/main.ts\", \"mcp\"]` as the args.\n\nInternally, the gateway now configures OpenAI Responses `tool_search` in client-executed mode. Deferred tools are still exposed as searchable namespaces, but the model is explicitly asked to return the exact deferred tool names it wants to load next.\n\nThe bridge uses direct tool selection, not query search. Its tool input is `names`, a comma-separated list of exact deferred tool names, for example `TaskList,TaskGet,mcp__fetch__fetch`.\n\n## Plugin Integrations\n\nPlugin integrations are available for Claude Code and opencode.\n\n#### Claude Code plugin integration (marketplace-based)\n\nThe Claude Code integration is packaged as two plugins:\n\n- `agent-inject` injects `__SUBAGENT_MARKER__...` on `SubagentStart`, so the gateway can infer `x-initiator: agent`.\n- `tool-search` registers the `tool_search` MCP bridge used for GPT Responses deferred tool loading.\n\n- Marketplace catalog in this repository: `.claude-plugin/marketplace.json`\n- Plugin sources in this repository: `plugin/claude/agent-inject`, `plugin/claude/tool-search`\n\nAdd the marketplace remotely:\n\n```sh\n/plugin marketplace add https://github.com/caozhiyuan/copilot-api.git\n```\n\nInstall the plugins from the marketplace:\n\n```sh\n/plugin install agent-inject@copilot-api-marketplace\n/plugin install tool-search@copilot-api-marketplace\n```\n\nAfter installation, `agent-inject` injects `__SUBAGENT_MARKER__...` on `SubagentStart`, and the gateway uses it to infer `x-initiator: agent`.\n\nThe `agent-inject` plugin also registers a `UserPromptSubmit` hook that returns `{\"continue\": true}`, and it can inject `SessionStart` reminder rules through environment variables:\n\n- `CLAUDE_PLUGIN_ENABLE_QUESTION_RULES=1` enables the two reminders about using the `question` tool automatically for Claude Code. Alternatively, you can add the same reminders manually in `CLAUDE.md`; see [CLAUDE.md or AGENTS.md Recommended Content](#claudemd-or-agentsmd-recommended-content).\n- `CLAUDE_PLUGIN_ENABLE_NO_BACKGROUND_AGENTS_RULE=1` enables the `run_in_background: true` avoidance reminder for agent hooks.\n\nThe `tool-search` plugin bundles the same MCP bridge described in [GPT Tool Search](#gpt-tool-search), so Claude Code users do not need to add the `tool_search` server manually when they install that plugin.\n\n#### Opencode plugin\n\nThe subagent marker producer is packaged as an opencode plugin located at `plugin/opencode/subagent-marker.js`.\n\n**Installation:**\n\nCopy the plugin file to your opencode plugins directory:\n\n```sh\n# Clone or download this repository, then copy the plugin\ncp plugin/opencode/subagent-marker.js ~/.config/opencode/plugins/\n```\n\nOr manually create the file at `~/.config/opencode/plugins/subagent-marker.js` with the plugin content.\n\n**Features:**\n\n- Tracks sub-sessions created by subagents\n- Automatically prepends a marker system reminder (`__SUBAGENT_MARKER__...`) to subagent chat messages\n- Sets `x-session-id` header for session tracking\n- Enables the gateway to infer `x-initiator: agent` for subagent-originated requests\n\nThe plugin hooks into `session.created`, `session.deleted`, `chat.message`, and `chat.headers` events to provide seamless subagent marker functionality.\n\n## Using the Usage Viewer\n\nAfter starting the server, a URL to the Copilot Usage Dashboard will be displayed in your console. This dashboard is a web interface for monitoring your API usage.\n\n1.  Start the server. For example, using npx:\n    ```sh\n    npx @jeffreycao/copilot-api@latest start\n    ```\n2.  The server will output a URL to the usage viewer. Copy and paste this URL into your browser. It will look something like this:\n    `http://localhost:4141/usage-viewer?endpoint=http://localhost:4141/usage`\n    - If you use the `start.bat` script on Windows, this page will open automatically.\n\nThe dashboard provides a user-friendly interface to view your Copilot usage data:\n\n> Token usage history requires Bun or Node.js >= 22.13.0. On Node.js < 22.13.0, the server runs normally but token usage storage is disabled.\n\n- **API Endpoint URL**: The dashboard is pre-configured to fetch data from your local server endpoint via a URL query parameter. You can manually switch this to any other compatible API endpoint.\n- **x-api-key Authentication**: If API Key authentication is enabled, you can provide the `x-api-key` request header. The key is persisted in the browser's local storage.\n- **Period Selector**: Choose from Day, Week, or Month time ranges. The URL query parameter updates automatically when you switch, making it easy to bookmark and share.\n- **Fetch Data**: Click the \"Refresh\" button to load or refresh the usage data. The dashboard also fetches data automatically on page load.\n- **Copilot Quotas**: View quota usage for services such as Chat and Completions via progress bars. Hover over a card to see used/remaining details.\n- **Token Usage Metric Cards**: See a summary of Total, Input, Output, Cache Read, Cache Write, Requests, and estimated cost for the current period.\n- **Trend Chart (Week / Month)**: An interactive line chart with model and metric filters. Click a data point to inspect the usage breakdown for a specific day.\n- **Model Breakdown Table**: A per-model summary of requests, input/output/cache tokens, and estimated cost for the selected period.\n- **Request Events (Paginated)**: A time-sorted list of request event records with pagination support, showing timestamps, models, request IDs, and token counts.\n- **Detailed Information**: See the full JSON response from the API for a detailed breakdown of all available usage statistics.\n- **URL-based Configuration**: You can also specify the API endpoint and period directly via `endpoint` and `period` query parameters. For example:\n  `http://localhost:4141/usage-viewer?endpoint=http://your-api-server/usage&period=week`\n\n### Usage Viewer Screenshot\n\n<p align=\"center\">\n  <img src=\"./docs/screenshots/usage-viewer.png\" alt=\"Copilot API usage viewer\" width=\"900\" />\n</p>\n\n## Command Structure\n\nCopilot API now uses a subcommand structure with these main commands:\n\n- `start`: Start the gateway server. If a GitHub token is available, the server starts with Copilot enabled. If no GitHub token is available, it starts in provider-only mode when at least one enabled provider exists; otherwise it guides you through provider setup.\n- `auth`: Run provider login or configuration without starting the server. Use it for GitHub Copilot login, Codex OAuth, or third-party provider API key setup.\n- `debug`: Display diagnostic information including version, runtime details, file paths, and authentication status. Useful for troubleshooting and support.\n\n## Command Line Options\n\n### Global Options\n\nThe following options can be used with any subcommand. When passing them before the subcommand, use the `--key=value` form:\n\n| Option            | Description                                            | Default | Alias |\n| ----------------- | ------------------------------------------------------ | ------- | ----- |\n| --api-home        | Path to the API home directory (sets COPILOT_API_HOME) | none    | none  |\n| --oauth-app       | OAuth app identifier (sets COPILOT_API_OAUTH_APP)      | none    | none  |\n| --enterprise-url  | Enterprise URL for GitHub (sets COPILOT_API_ENTERPRISE_URL) | none | none |\n\n### Start Command Options\n\nThe following command line options are available for the `start` command:\n\n| Option         | Description                                                                   | Default    | Alias |\n| -------------- | ----------------------------------------------------------------------------- | ---------- | ----- |\n| --port         | Port to listen on                                                             | 4141       | -p    |\n| --verbose      | Enable verbose logging                                                        | false      | -v    |\n| --github-token | Provide GitHub token directly (must be generated using the `auth` subcommand) | none       | -g    |\n| --claude-code  | Generate a command to launch Claude Code with Copilot API config              | false      | -c    |\n| --show-token   | Show GitHub and Copilot tokens on fetch and refresh                           | false      | none  |\n| --proxy-env    | Initialize proxy from environment variables                                   | false      | none  |\n\n### Auth Command Options\n\n| Option       | Description               | Default | Alias |\n| ------------ | ------------------------- | ------- | ----- |\n| --provider   | Provider to log in with or configure (`copilot`, `codex`, `opencode-go`, `deepseek`, `dashscope`, `openrouter`, or `custom`) | prompt | none |\n| --verbose    | Enable verbose logging    | false   | -v    |\n| --show-token | Show GitHub token on auth | false   | none  |\n\nUse `copilot-api auth login --provider copilot` only when you want to enable the GitHub Copilot provider. Copilot is not required for `codex` or third-party provider-only usage.\n\nUse `copilot-api auth login --provider deepseek`, `--provider dashscope`, `--provider openrouter`, or `--provider opencode-go` to add or update those common third-party providers from the CLI. DeepSeek prompts for masked `apiKey`, provider `type` (default `anthropic`), and `baseUrl` defaulting to `https://api.deepseek.com/anthropic`. DashScope prompts for masked `apiKey`, provider `type` (default `openai-compatible`), and prefilled `baseUrl`. OpenRouter prompts for masked `apiKey` and prefilled `baseUrl` only, and writes `type: \"anthropic\"`. OpenCode Go prompts for masked `apiKey` and prefilled `baseUrl` only, and writes `type: \"openai-compatible\"` (baseUrl `https://opencode.ai/zen/go`). OpenCode Go additionally routes built-in `qwen*` and `minimax*` models through Anthropic Messages and `gpt*` models through OpenAI Responses; other models keep the OpenAI-compatible default. After a provider is configured and enabled, `copilot-api start` can run without any GitHub token.\n\nUse `copilot-api auth login --provider custom` to add or update another third-party provider from the CLI. The command prompts for the provider name, supported type (`anthropic`, `openai-compatible`, or `openai-responses`), `baseUrl`, masked `apiKey`, and `authType`; `authType` may be left as the type default or set to `x-api-key` / `authorization`.\n\n### Debug Command Options\n\n| Option | Description               | Default | Alias |\n| ------ | ------------------------- | ------- | ----- |\n| --json | Output debug info as JSON | false   | none  |\n\n## Configuration (config.json)\n\n- **Location:** `~/.local/share/copilot-api/config.json` (Linux/macOS) or `%USERPROFILE%\\.local\\share\\copilot-api\\config.json` (Windows).\n- **Default shape:**\n  ```json\n  {\n    \"auth\": {\n      \"apiKeys\": [],\n      \"adminApiKey\": \"<auto-generated-on-startup>\"\n    },\n    \"providers\": {},\n    \"modelMappings\": {},\n    \"extraPrompts\": {\n      \"gpt-5-mini\": \"<built-in exploration prompt>\"\n    },\n    \"smallModel\": \"gpt-5-mini\",\n    \"contextManagement\": {\n      \"messages\": true,\n      \"responses\": false\n    },\n    \"modelResponsesApiCompactThresholds\": {\n      \"gpt-5.4\": 217600,\n      \"gpt-5.5\": 217600\n    },\n    \"modelReasoningEfforts\": {\n      \"gpt-5-mini\": \"low\"\n    },\n    \"useMessagesApi\": true,\n    \"useResponsesApiWebSocket\": true,\n    \"useResponsesApiWebSearch\": true,\n    \"messageApiWebSearchModel\": \"gpt-5-mini\"\n  }\n  ```\n- **auth.apiKeys:** API keys used for request authentication on non-admin routes. Supports multiple keys for rotation. Requests can authenticate with either `x-api-key: <key>` or `Authorization: Bearer <key>`. If empty or omitted, authentication for non-admin routes is disabled.\n- **auth.adminApiKey:** Single admin key used only for `/admin/*` routes. If missing, the server generates a random key at startup and writes it back to `config.json`. Requests use the same `x-api-key` or `Authorization: Bearer` headers, but regular `auth.apiKeys` never grant access to `/admin/*`.\n- **modelMappings:** Exact `sourceModel -> targetModel` rewrites shared by top-level `POST /v1/messages`, `POST /v1/messages/count_tokens`, `POST /v1/responses`, and `POST /v1/chat/completions` requests. Omit it or leave it as `{}` to disable rewrites. Both the source and target must be non-empty strings. Targets can be regular model IDs or `provider/model` aliases such as `dashscope/qwen3.6-plus`, and the rewrite happens before provider alias parsing. These mappings are not split per interface. The admin endpoints `GET/POST /admin/config/model-mappings` read and update only this field.\n- **extraPrompts:** Map of `model -> prompt` appended to the first system prompt when translating Anthropic-style requests to Responses API. Use this to inject guardrails or guidance per model. Missing default entries are auto-added without overwriting your custom prompts. For GPT-5.3+ models (e.g. `gpt-5.3-codex`, `gpt-5.4`, `gpt-5.5`), a built-in commentary prompt is used as fallback when not explicitly configured. The built-in prompts enable phase-aware commentary, which lets the model emit a short user-facing progress update before tools or deeper reasoning.\n- **providers:** Global upstream provider map. Each provider key (for example `dashscope`) becomes a route prefix (`/dashscope/v1/messages`). Supports `type: \"anthropic\"`, `type: \"openai-compatible\"`, and `type: \"openai-responses\"`. Top-level clients can also use `model: \"dashscope/model-id\"` with `/v1/messages`, `/v1/messages/count_tokens`, `/v1/responses`, and `/v1/chat/completions`; the gateway strips the `dashscope/` prefix before forwarding upstream. `openai-compatible` providers support both chat and Messages flows: `/v1/chat/completions` is proxied to upstream `/v1/chat/completions`, while `/v1/messages` and `/:provider/v1/messages` are translated to upstream chat completions and translated back to Anthropic Messages responses. `GET /v1/models` aggregates enabled provider models with `provider/model-id` IDs; use `GET /dashscope/v1/models` for a single provider's raw model list.\n  - `enabled` defaults to `true` if omitted.\n  - `baseUrl` should be provider API base URL without the final endpoint. For Anthropic providers, omit `/v1/messages`; for OpenAI-compatible providers, omit `/v1/chat/completions`; for OpenAI Responses providers, omit `/v1/responses`.\n  - `apiKey` is used as the upstream credential value and is required for regular providers.\n  - `authType` (optional): Controls how `apiKey` is sent upstream. Supports `x-api-key` and `authorization` for regular providers. Anthropic providers default to `x-api-key`; OpenAI-compatible and OpenAI Responses providers default to `authorization`. When set to `authorization`, the proxy sends `Authorization: Bearer <apiKey>`. `oauth2` is reserved for the built-in `codex` provider and is written automatically by `auth login --provider codex`.\n  - `pricingCurrency` (optional): Provider-level currency used for token cost calculation, for example `USD` or `CNY`. Quick providers default to `CNY` for DashScope and DeepSeek, and `USD` for Codex/OpenRouter. Costs are grouped by currency and are not exchange-rate converted.\n  - `models` (optional): Per-model configuration map. Each key is a model ID (matching the model name in requests), and the value is:\n    - `temperature` (optional): Default temperature value used when the request does not specify one.\n    - `topP` (optional): Default top_p value used when the request does not specify one.\n    - `topK` (optional): Default top_k value used when the request does not specify one.\n    - `extraBody` (optional): Dynamic fields merged into the upstream request body for that model. Request body fields with the same name take precedence. OpenAI-compatible providers can use this for fields such as `enable_thinking`, `preserve_thinking`, `reasoning_effort`. `thinking_budget` is a special OpenAI-compatible provider override: when configured in `extraBody`, it is forced after Anthropic `thinking.budget_tokens` translation and overrides the request-derived budget. For providers whose name is `dashscope` or whose `baseUrl` contains `aliyuncs.com`, the request-derived `thinking_budget` (from Anthropic `thinking.budget_tokens`) is forwarded upstream; for other OpenAI-compatible providers the request-derived `thinking_budget` is stripped, while an `extraBody` `thinking_budget` is still honored. For DashScope providers, `preserve_thinking` defaults to `true` when not explicitly set in `extraBody` or the request body.\n    - `pricing` (optional): Per-model token prices, in the provider `pricingCurrency`, per 1M tokens. Supported fields are `input`, `output`, `cachedInput` (implicit cache read), `explicitCachedInput` (explicit cache read), and `cacheCreationInput`. Use `tiers` with `maxInputTokens` for input-size tiered pricing.\n    - `contextCache` (optional): Defaults to `true` for providers whose name is `dashscope` or whose `baseUrl` contains `aliyuncs.com`; defaults to `false` for other OpenAI-compatible providers. This enables Alibaba Cloud Model Studio/DashScope explicit context cache by injecting `cache_control: { \"type\": \"ephemeral\" }` on up to 4 content blocks using the Context Cache format. The cache breakpoint strategy matches opencode's main provider flow: the first 2 system messages plus the last 2 non-system messages. Marked string content is converted to text content part arrays for `system` / `user` / `assistant` / `tool` messages; existing array content is marked on the last part. Set this to `false` when the model already supports implicit caching, or when the upstream does not accept this explicit-cache extension field. Set this to `true` for non-DashScope providers that support the same explicit-cache extension. Applied on both `/v1/messages` and `/v1/chat/completions` routes.\n    - `supportPdf` (optional): Controls whether the model supports PDF/document content. Defaults to `false`; unsupported PDFs are converted to a text notice. Set it to `true` to send PDF/document blocks as OpenAI Chat Completions file parts.\n    - `toolContentSupportType` (optional): Tool result content capabilities for that model, as an array of `array`, `image`, and `pdf`. Provider routes default to string-only tool content when omitted. If `supportPdf` is `true` but this list does not include `pdf`, file parts in tool results are moved to user role messages. This provider default does not change the Copilot main flow, which continues to support array + image and not PDF.\n    - `type` (optional): Per-model override of the provider protocol type. Supports `anthropic`, `openai-compatible`, and `openai-responses`. When set, the provider's `/v1/messages` route uses this model's type instead of the provider-level type for request routing, auth header resolution, and upstream endpoint selection. This is useful for providers like OpenCode Go whose upstream supports both OpenAI-compatible and Anthropic Messages APIs for different models. When the type is overridden, the auth header is resolved from the overridden type's default (Anthropic defaults to `x-api-key`; OpenAI-compatible/Responses default to `authorization`).\n\n  Example DashScope model settings:\n  ```json\n  {\n    \"providers\": {\n      \"dashscope\": {\n        \"type\": \"openai-compatible\",\n        \"enabled\": true,\n        \"baseUrl\": \"https://dashscope.aliyuncs.com/compatible-mode\",\n        \"apiKey\": \"sk-your-dashscope-key\",\n        \"pricingCurrency\": \"CNY\",\n        \"models\": {\n          \"qwen3.7-plus\": {\n            \"temperature\": 1,\n            \"topP\": 0.95,\n            \"topK\": 20,\n            \"extraBody\": {\n              \"preserve_thinking\": true\n            }\n          },\n          \"glm-5.1\": {\n            \"temperature\": 0.7,\n            \"topP\": 0.95,\n            \"contextCache\": true,\n            \"pricing\": {\n              \"tiers\": [\n                {\n                  \"maxInputTokens\": 32000,\n                  \"input\": 6,\n                  \"cachedInput\": 1.2,\n                  \"explicitCachedInput\": 0.6,\n                  \"cacheCreationInput\": 7.5,\n                  \"output\": 24\n                },\n                {\n                  \"maxInputTokens\": 200000,\n                  \"input\": 8,\n                  \"cachedInput\": 1.6,\n                  \"explicitCachedInput\": 0.8,\n                  \"cacheCreationInput\": 10,\n                  \"output\": 28\n                }\n              ]\n            },\n            \"extraBody\": {\n              \"preserve_thinking\": true\n            }\n          }\n        }\n      }\n    }\n  }\n  ```\n  Built-in token prices cover Codex GPT models in USD, DashScope `qwen3.7-max`, `qwen3.7-plus`, `glm-5.1`, `glm-5.2` in CNY, DeepSeek `deepseek-v4-flash`, `deepseek-v4-pro`, `deepseek-chat`, `deepseek-reasoner` in CNY, and OpenCode Go models (`hy3`, `gpt-5.6-luna`, `glm-5.2`, `grok-4.5`, `deepseek-v4-flash`, `deepseek-v4-pro`, `kimi-k2.7-code`, `kimi-k3`, `mimo-v2.5`, `mimo-v2.5-pro`, `qwen3.7-plus`, `qwen3.7-max`, `minimax-m2.7`, `minimax-m3`) in USD. User `pricing` entries override built-ins. For DashScope, cached tokens are charged as explicit cache reads when the upstream usage includes `cache_creation_input_tokens`; otherwise `cachedInput` is used as the implicit cache read price. For DeepSeek, `prompt_cache_hit_tokens` map to cached input and `prompt_cache_miss_tokens` map to regular input.\n- **smallModel:** Fallback model used for tool-less warmup messages (e.g., Claude Code probe requests); defaults to gpt-5-mini. The gateway forces this small model on no-tool warmup or probe requests to avoid consuming premium requests. This behavior only applies to non-token-based-billing GitHub Copilot accounts (`token_based_billing` is false); for token-based-billing accounts the warmup small-model fallback is skipped since there is no premium-request quota to preserve.\n- **contextManagement:** Controls whether the proxy adds Responses API `context_management` compaction instructions. `messages` applies when Anthropic-style `/v1/messages` requests are translated to Responses API, including `openai-responses` provider message routes, and defaults to `true`. `responses` applies to native `/v1/responses` traffic, including `provider/model` aliases and the built-in `codex` provider, and defaults to `false`. Enable `responses` only after checking that your client supports context management compaction. When enabled, the request includes `context_management` in the body and keeps only the latest compaction carrier on follow-up turns. **Note:** Context management is forcibly disabled for GPT-5.6 and above models (e.g. `gpt-5.6-sol`, `gpt-5.6-terra`, `gpt-5.6-luna`) because enabling it breaks prompt cache hits on those models. This override takes precedence over the `contextManagement` and `modelResponsesApiCompactThresholds` settings.\n - **modelResponsesApiCompactThresholds:** Per-model Responses API `compact_threshold` overrides used when the proxy adds `context_management`. These values take precedence over the fallback threshold from `resolveResponsesCompactThreshold` (`max_prompt_tokens * ratio`, or the default fallback). Defaults set `gpt-5.4` and `gpt-5.5` to `217600` (`272000 * 0.8`). Models not listed continue to use the normal fallback logic.\n- **modelReasoningEfforts:** Per-model fallback reasoning effort for `/v1/messages` requests. It is used only when the request does not provide `output_config.effort`.\n  - **Priority:** request `output_config.effort` > `modelReasoningEfforts[model]` > built-in default (`xhigh` for GPT-5.3+ models, otherwise `high`).\n  - **Forwarding:** the resolved value remains `output_config.effort` for the Copilot native Messages API and becomes `reasoning.effort` when translated to the Responses API.\n  - **Configuration values:** `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`.\n- **useMessagesApi:** When `true`, Claude-family models that support Copilot's native `/v1/messages` endpoint will use the Messages API; otherwise they fall back to `/chat/completions`. Set to `false` to disable Messages API routing and always use `/chat/completions`. Defaults to `true`.\n- **useResponsesApiWebSocket:** When `true`, Responses API requests use Copilot's websocket transport for models that advertise `ws:/responses`; models that only advertise `/responses` continue to use HTTP. Set to `false` to disable websocket routing and use HTTP `/responses` whenever the selected model supports it. Defaults to `true`. If the Responses API WebSocket gets closed, it is usually caused by your own network. If you are using a VPN, try switching to a different node.\n- **useResponsesApiWebSearch:** When `true`, the server keeps Responses API tools with `type: \"web_search\"` and forwards them upstream. Set to `false` to strip those tools from `/responses` payloads. Defaults to `true`.\n- **messageApiWebSearchModel:** Global fallback model used when a top-level Copilot `/v1/messages` request contains only the server-side `web_search` tool. Defaults to `gpt-5-mini`. If the value is a `provider/model` alias, the request is routed into that provider's Messages API path with the provider prefix stripped. For Copilot GPT models, web search runs through `/responses`. Mixed `web_search` plus custom tools are not supported and the server-side `web_search` tool is stripped.\n- **claudeTokenMultiplier:** Multiplier applied to the fallback GPT-tokenizer estimate for Claude `/v1/messages/count_tokens` requests. Defaults to `1.15`. Increase it if your client is still compacting too late. This setting is only used when the proxy is estimating Claude tokens locally; if `anthropicApiKey` is configured and Anthropic token counting succeeds, the exact Anthropic count is returned instead.\n- **anthropicApiKey:** Anthropic API key used to forward Claude `/v1/messages/count_tokens` requests to Anthropic's real token counting endpoint, which returns exact counts instead of GPT tokenizer estimates. Can also be set via the `ANTHROPIC_API_KEY` environment variable. If not set, or if the upstream call fails, token counting falls back to local GPT tokenizer estimation controlled by `claudeTokenMultiplier`.\n\nEdit this file to customize prompts or swap in your own fast model. Restart the server (or rerun the command) after changes so the cached config is refreshed.\n\n## API Authentication\n\n- **Protected non-admin routes:** All routes except `/`, `/usage-viewer`, and `/usage-viewer/` require authentication when `auth.apiKeys` is configured and non-empty.\n- **Admin routes:** All `/admin/*` routes require `auth.adminApiKey`. If it is missing, the server generates one at startup and persists it to `config.json` before serving requests.\n- **Allowed auth headers:**\n  - `x-api-key: <your_key>`\n  - `Authorization: Bearer <your_key>`\n- **CORS preflight:** `OPTIONS` requests are always allowed.\n- **When no regular keys are configured:** Non-admin routes continue to allow requests. This does not apply to `/admin/*`, which only accepts `auth.adminApiKey`.\n\nExample request for a regular protected route:\n\n```sh\ncurl http://localhost:4141/v1/models \\\n  -H \"x-api-key: your_api_key\"\n```\n\nExample request for an admin route:\n\n```sh\ncurl http://localhost:4141/admin/config/model-mappings \\\n  -H \"x-api-key: your_admin_api_key\"\n```\n\n## API Endpoints\n\nThe server exposes several OpenAI- and Anthropic-compatible endpoints. Requests can target GitHub Copilot, the built-in `codex` provider, or configured providers depending on the selected model and `provider/model` alias.\n\n### OpenAI Compatible Endpoints\n\nThese endpoints mimic the OpenAI API structure.\n\n| Endpoint                    | Method | Description                                                      |\n| --------------------------- | ------ | ---------------------------------------------------------------- |\n| `POST /v1/responses`        | `POST` | OpenAI Most advanced interface for generating model responses. Supports `provider/model` aliases for `openai-responses` providers. |\n| `POST /v1/chat/completions` | `POST` | Creates a model response for the given chat conversation. Supports `provider/model` aliases for `openai-compatible` providers and can be used without Copilot when the target provider is configured. |\n| `GET /v1/models`            | `GET`  | Lists Copilot models plus enabled provider models using `provider/model-id` IDs. Requests from Codex clients (`User-Agent` beginning with `codex`) are forwarded to the Codex Models upstream. |\n| `POST /v1/embeddings`       | `POST` | Creates an embedding vector representing the input text.         |\n\n### Codex Backend Proxy Endpoints\n\nThese endpoints require an active Codex login. Each endpoint is available both without a version prefix and under `/v1`.\n\n| Endpoint | Method | Description |\n| --- | --- | --- |\n| `POST /alpha/search`<br>`POST /v1/alpha/search` | `POST` | Transparently forwards the JSON body and query parameters to the Codex Alpha Search upstream. |\n| `POST /images/generations`<br>`POST /v1/images/generations` | `POST` | Forwards a JSON image generation request to the Codex Images upstream. When the request omits `Content-Type`, the gateway defaults it to `application/json`. |\n| `POST /images/edits`<br>`POST /v1/images/edits` | `POST` | Forwards an image edit request to the Codex Images upstream. Send this request as `multipart/form-data` and let the HTTP client generate the `boundary`; the gateway preserves the incoming content type and streams the upload body. |\n\nFor every endpoint above, the gateway replaces client authorization and account headers with the active Codex login, preserves query parameters and compatible request headers, and returns the upstream status, headers, and body.\n\n### Anthropic Compatible Endpoints\n\nThese endpoints are designed to be compatible with the Anthropic Messages API. Provider-scoped models, Responses, alpha-search, and images routes accept both unversioned and `/v1` paths; Messages routes remain under `/v1`.\n\n| Endpoint                         | Method | Description                                                  |\n| -------------------------------- | ------ | ------------------------------------------------------------ |\n| `POST /v1/messages`              | `POST` | Creates a model response for a given conversation. Supports `provider/model` aliases for configured providers, including translation through `openai-compatible` providers. |\n| `POST /v1/messages/count_tokens` | `POST` | Calculates the number of tokens for a given set of messages. Supports `provider/model` aliases for configured providers. |\n| `POST /:provider/v1/messages`       | `POST` | Proxies Anthropic Messages requests to the configured Anthropic provider, translates them through an OpenAI-compatible provider, or translates them through an OpenAI Responses provider. |\n| `GET /:provider/models`<br>`GET /:provider/v1/models` | `GET` | Proxies model listing requests to the configured provider. For `codex`, returns the built-in catalog by default; Codex clients (`User-Agent` starting with `codex`) are forwarded to the Codex Models upstream. |\n| `POST /:provider/v1/messages/count_tokens` | `POST` | Calculates tokens locally for provider route requests. |\n| `POST /:provider/responses`<br>`POST /:provider/v1/responses` | `POST` | Proxies OpenAI Responses requests to a configured `openai-responses` provider (including `codex`). |\n| `POST /:provider/alpha/search`<br>`POST /:provider/v1/alpha/search` | `POST` | Proxies alpha-search requests. For `codex`, forwards to the Codex Alpha Search upstream; for other providers, forwards to `{baseUrl}/v1/alpha/search`. |\n| `POST /:provider/images/generations`<br>`POST /:provider/v1/images/generations` | `POST` | Proxies image generation. For `codex`, uses the Codex Images upstream; for other providers, forwards to `{baseUrl}/v1/images/generations` (15-minute timeout). |\n| `POST /:provider/images/edits`<br>`POST /:provider/v1/images/edits` | `POST` | Proxies image edits. For `codex`, uses the Codex Images upstream; for other providers, forwards multipart/streamed bodies to `{baseUrl}/v1/images/edits` (15-minute timeout). |\n\n### Usage Monitoring Endpoints\n\nNew endpoints for monitoring your Copilot usage and quotas.\n\n| Endpoint     | Method | Description                                                  |\n| ------------ | ------ | ------------------------------------------------------------ |\n| `GET /usage` | `GET`  | Get detailed Copilot usage statistics and quota information. |\n| `GET /token` | `GET`  | Get the current Copilot token being used by the API.         |\n\n### Admin / Configuration Endpoints\n\nThese endpoints are reserved for local administrative actions and only accept `auth.adminApiKey`.\n\n| Endpoint                              | Method | Description                                                                 |\n| ------------------------------------- | ------ | --------------------------------------------------------------------------- |\n| `GET /admin/config/model-mappings`    | `GET`  | Returns the current `config.json` path and the active `modelMappings` map.  |\n| `POST /admin/config/model-mappings`   | `POST` | Updates only the `modelMappings` field in `config.json` and returns it back. |\n\n## Example Usage\n\nCommon `npx` commands:\n\n```sh\n# Start the gateway\nnpx @jeffreycao/copilot-api@latest start\n\n# Start on a custom port with verbose logging\nnpx @jeffreycao/copilot-api@latest start --port 8080 --verbose\n\n# Run the auth flow\nnpx @jeffreycao/copilot-api@latest auth login\n\n# Configure a third-party provider, then run without GitHub Copilot\nnpx @jeffreycao/copilot-api@latest auth login --provider dashscope\nnpx @jeffreycao/copilot-api@latest start\n\n# Print debug information as JSON\nnpx @jeffreycao/copilot-api@latest debug --json\n\n# Run the published CLI with Bun instead of Node.js\nbunx --bun @jeffreycao/copilot-api@latest start\n```\n\nOpenAI-compatible provider examples after configuring `dashscope`:\n\n```sh\ncurl http://localhost:4141/v1/chat/completions \\\n  -H \"content-type: application/json\" \\\n  -d '{\"model\":\"dashscope/qwen3.6-plus\",\"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]}'\n\ncurl http://localhost:4141/dashscope/v1/messages \\\n  -H \"content-type: application/json\" \\\n  -d '{\"model\":\"qwen3.6-plus\",\"max_tokens\":1024,\"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]}'\n```\n\n## Usage Tips\n\n### CLAUDE.md or AGENTS.md Recommended Content\n\nTo add these reminders manually, include the following in `CLAUDE.md` for Claude Code, or `AGENTS.md` for opencode/codex:\n\n```\n- Prohibited from directly asking questions to users, MUST use question tool.\n- Once you can confirm that the task is complete, MUST use question tool to make user confirm. The user may respond with feedback if they are not satisfied with the result, which you can use to make improvements and try again, after try again, MUST use question tool to make user confirm again.\n```\n"}, "de17a027c73ef7a4f5d2703660dea2ba987c62a0": {"t": 1785765530.894732, "n": 51290, "h": "60c1e6070a814cf4", "c": "# Copilot API Proxy\n\nEnglish | [简体中文](./README.zh-CN.md)\n\n## Important Notes\n\n> [!IMPORTANT]\n> **Before using, please be aware of the following:**\n>\n> 1. **Claude Code configuration:** When using with Claude Code, please configure the model ID as `claude-opus-4-8`. Example claude `settings.json` see [Manual Configuration with `settings.json`](#manual-configuration-with-settingsjson). \n>\n> 2. **Built-in `copilot`, `codex` and third-party providers:** Run `npx @jeffreycao/copilot-api@latest auth` and choose `copilot`, `codex`, `deepseek`, `custom`, or other providers.\n>\n> 3. **Note:** See [GitHub Copilot Security Notice](./NOTICE.md#github-copilot-security-notice) for the warning removed from the README header.\n\n---\n\n## Project Overview\n\nA small AI gateway that can use GitHub Copilot, the built-in `codex` provider, or configured third-party providers such as DashScope. GitHub Copilot is optional: if no GitHub token is available, the server can still start in provider-only mode as long as at least one enabled provider is configured.\n\nThe gateway exposes OpenAI- and Anthropic-compatible APIs from one local endpoint, so tools like [Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview), OpenCode, Codex, and OpenAI-compatible clients can share the same local server.\n\nOn the GitHub Copilot path, the gateway prefers Copilot's native Anthropic-style Messages API when available, preserving more Claude-native behavior for tool-heavy workflows.\n\n## Features\n\n- **OpenAI and Anthropic compatibility**: Serve `/v1/responses`, `/v1/chat/completions`, `/v1/models`, `/v1/embeddings`, and `/v1/messages` from one local gateway.\n- **Copilot is optional**: Use GitHub Copilot when credentials are present, or run the server with only configured providers.\n- **One gateway for Copilot, `codex`, and external providers**: Route GitHub Copilot, the built-in `codex` provider, and configured third-party providers behind the same endpoint.\n- **Standalone third-party providers**: Configure providers such as DashScope, DeepSeek, OpenRouter, or a custom provider and start the gateway without a GitHub Copilot login.\n- **OpenAI-compatible providers on chat and Messages APIs**: `openai-compatible` providers can serve top-level `/v1/chat/completions` through `model: \"provider/model\"` and Anthropic-style `/v1/messages` through request/response translation.\n- **Agent-friendly Claude handling on Copilot**: Prefer native `/v1/messages` when available, preserve Claude-style tool flows, support Anthropic beta features, Claude WebSearch through Responses-capable models, and keep subagent/session markers intact.\n- **Claude Code and OpenCode integration**: Works with Claude Code and OpenCode, including direct Anthropic-compatible usage through `@ai-sdk/anthropic`.\n- **Flexible auth and deployment options**: Supports interactive login or direct tokens, individual/business/enterprise plans, GitHub Enterprise, opencode OAuth, and custom data directories.\n- **Multi-provider routing**: Expose provider-specific `/:provider/...` routes or use `model: \"provider/model\"` on the top-level API.\n\n## Prerequisites\n\n- Bun (>= 1.2.x)\n- Node.js if you plan to run the published CLI with `npx`\n- GitHub account with Copilot subscription only if you want to use the GitHub Copilot provider\n- An API key or OAuth login for at least one configured provider if you want to run without GitHub Copilot\n\n## Installation\n\nTo install dependencies, run:\n\n```sh\nbun install\n```\n\nTo start the server directly from source:\n\n```sh\nbun run start start\n```\n\n## Running from Source\n\nThe project can be run from source in several ways:\n\n### Development Mode\n\n```sh\nbun run dev start\n```\n\n### Production Mode\n\n```sh\nbun run start start\n```\n\n## Using with npx\n\nYou can run the project directly using npx:\n\n> [!IMPORTANT]\n> Token usage storage uses Node's built-in `node:sqlite` module when running with `npx`. It is enabled on Node.js >= 22.13.0. On Node.js < 22.13.0, the CLI still starts, but token usage storage is disabled.\n>\n> If you want token usage storage without upgrading Node.js, run the published CLI with Bun instead: `bunx --bun @jeffreycao/copilot-api@latest start`.\n\n```sh\nnpx @jeffreycao/copilot-api@latest start\n```\n\nWith options:\n\n```sh\nnpx @jeffreycao/copilot-api@latest start --port 8080\n```\n\nFor authentication or provider configuration only:\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth\n```\n\nTo run without GitHub Copilot, configure at least one provider first, then start the server normally:\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth login --provider dashscope\nnpx @jeffreycao/copilot-api@latest start\n```\n\n## Using with Docker\n\nBuild the image:\n\n```sh\ndocker build -t copilot-api .\n```\n\nRun the container with a bind mount so auth data survives restarts:\n\n```sh\nmkdir -p ./copilot-data\ndocker run -p 4141:4141 -v $(pwd)/copilot-data:/root/.local/share/copilot-api copilot-api\n```\n\nThis stores GitHub auth data, provider config, and other gateway state in `./copilot-data` on the host, mapped to `/root/.local/share/copilot-api` in the container.\n\nOr pass a GitHub token directly:\n\n```sh\ndocker run -p 4141:4141 -e GH_TOKEN=your_github_token_here copilot-api\n```\n\n## Electron Desktop App\n\nIf you prefer a GUI, this repository also includes an Electron desktop app in `desktop/`. It supports GitHub Copilot sign-in, OpenAI Codex OAuth, and API-key configuration for DeepSeek, DashScope, OpenRouter, or a custom provider. After authorization or provider configuration, it can start and stop the local proxy with one click and shows the local endpoint, auth header, available models, usage, and logs in the app.\n\nThe settings screen also exposes `OAuth App`, `API Home`, `Enterprise URL`, verbose logging, and minimize-to-tray. Windows x64 (`.exe`), macOS Apple Silicon (`.dmg`), and Linux x64 (`.AppImage`) packages are published in GitHub Releases:\n\nhttps://github.com/caozhiyuan/copilot-api/releases\n\nOn Linux, make the downloaded AppImage executable before launching it:\n\n```sh\nchmod +x Copilot-API-*-linux-x86_64.AppImage\n./Copilot-API-*-linux-x86_64.AppImage\n```\n\nDownload the installer for your platform, authorize or configure a provider inside the app, choose a port, start the server, then point your client at the local endpoint shown in the app. Packaged desktop builds use the bundled Electron runtime, so normal desktop usage does not require installing Node.js separately. Token usage history is enabled when that bundled runtime supports SQLite.\n\nThe desktop app's Advanced Config page reads and writes the shared model mappings through `GET/POST /admin/config/model-mappings`. The same mappings apply across `POST /v1/messages`, `POST /v1/messages/count_tokens`, `POST /v1/responses`, and `POST /v1/chat/completions` instead of being split per interface. It uses `auth.adminApiKey` instead of the regular `auth.apiKeys`, and the app reads that key directly from `config.json` after the server has generated it on startup.\n\n### Desktop App Screenshots\n\nMain dashboard, token usage breakdown in the bundled Electron app:\n\n<p align=\"center\">\n  <img src=\"./docs/screenshots/desktop-dashboard.png\" alt=\"Copilot API desktop app dashboard\" width=\"49%\" />\n  <img src=\"./docs/screenshots/desktop-token-usage.png\" alt=\"Copilot API desktop app token usage view\" width=\"49%\" />\n</p>\n\n## Using with Claude Code\n\nThis AI gateway can be used to power [Claude Code](https://docs.anthropic.com/en/claude-code), an experimental conversational AI assistant for developers from Anthropic.\n\nThere are two ways to configure Claude Code to use this AI gateway:\n\n### Interactive Setup with `--claude-code` flag\n\nTo get started, run the `start` command with the `--claude-code` flag:\n\n```sh\nnpx @jeffreycao/copilot-api@latest start --claude-code\n```\n\nYou will no longer be prompted to pick models manually. The gateway automatically detects the latest available model for each Claude Code size tier — opus maps to the newest Opus model, sonnet to the newest Sonnet model, and haiku to the newest Haiku model — and generates a command that sets `ANTHROPIC_DEFAULT_OPUS_MODEL`, `ANTHROPIC_DEFAULT_SONNET_MODEL`, and `ANTHROPIC_DEFAULT_HAIKU_MODEL` accordingly. Any tier without a matching model available is omitted. The command is copied to your clipboard and sets the environment variables needed for Claude Code to use the gateway.\n\nPaste and run this command in a new terminal to launch Claude Code.\n\n### Manual Configuration with `settings.json`\n\nAlternatively, you can configure Claude Code by creating a `.claude/settings.json` file in your project's root directory. This file should contain the environment variables needed by Claude Code. This way you don't need to run the interactive setup every time.\n\nHere is an example `.claude/settings.json` file:\n\n```json\n{\n  \"env\": {\n    \"ANTHROPIC_BASE_URL\": \"http://localhost:4141\",\n    \"ANTHROPIC_AUTH_TOKEN\": \"dummy\",\n    \"ANTHROPIC_MODEL\": \"gpt-5.6-sol[1m]\",\n    \"ANTHROPIC_DEFAULT_SONNET_MODEL\": \"gpt-5.6-sol[1m]\",\n    \"ANTHROPIC_DEFAULT_HAIKU_MODEL\": \"gpt-5.6-luna[1m]\",\n    \"CLAUDE_CODE_AUTO_COMPACT_WINDOW\": \"272000\",\n    \"CLAUDE_CODE_USE_VERTEX\": \"0\",\n    \"CLAUDE_CODE_USE_BEDROCK\": \"0\",\n    \"DISABLE_NON_ESSENTIAL_MODEL_CALLS\": \"1\",\n    \"CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC\": \"1\",\n    \"CLAUDE_CODE_ATTRIBUTION_HEADER\": \"0\",\n    \"CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION\": \"false\",\n    \"CLAUDE_CODE_DISABLE_TERMINAL_TITLE\": \"true\",\n    \"CLAUDE_CODE_ENABLE_AWAY_SUMMARY\": \"0\"\n  },\n  \"alwaysThinkingEnabled\": true,\n  \"effortLevel\": \"xhigh\",\n  \"showThinkingSummaries\": true\n}\n```\n\n- Replace `ANTHROPIC_MODEL`, `ANTHROPIC_DEFAULT_OPUS_MODEL`, `ANTHROPIC_DEFAULT_SONNET_MODEL`, and `ANTHROPIC_DEFAULT_HAIKU_MODEL` according to your needs. After configuration, please install the claude code plugin [Plugin Integrations](#plugin-integrations).  \n- If you are using the codex provider, it is recommended **not** to configure the model name in the `codex/xxx` format (e.g. `codex/gpt-5.6-sol`). Claude Code treats the `codex/` prefix as a special pattern and applies degraded behavior — for example, it strips all previously returned thinking blocks on every request. Use the plain model name (e.g. `gpt-5.6-sol`) instead, and add a `modelMappings` entry in `config.json` to route it back to the codex provider:\n  ```json\n  \"modelMappings\": {\n    \"gpt-5.6-sol\": \"codex/gpt-5.6-sol\",\n    \"gpt-5.6-terra\": \"codex/gpt-5.6-terra\",\n    \"gpt-5.6-luna\": \"codex/gpt-5.6-luna\"\n  },\n  ```\n- Setting CLAUDE_CODE_ATTRIBUTION_HEADER to 0 can prevent Claude code from adding billing and version information in system prompts, thereby avoiding prompt cache invalidation.\n- Turning off CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION and CLAUDE_CODE_ENABLE_AWAY_SUMMARY can prevent quota from being consumed unnecessarily.\n- Claude Code WebSearch is supported for pure search requests. For Copilot, keep the global `messageApiWebSearchModel` set to a Responses-capable GPT model or a `provider/model` alias. For provider routes, use a native Anthropic provider or an `openai-responses` provider. Add `WebSearch` to `permissions.deny` only if you want to forbid this traffic.\n- If using a non-Claude model, do not enable ENABLE_TOOL_SEARCH. If using the Claude model, can enable ENABLE_TOOL_SEARCH. The current Claude Code uses the client tool search mode. In this mode, loading defer tools requires an additional request each time.\n- `CLAUDE_CODE_AUTO_COMPACT_WINDOW`: Set the context capacity in tokens used for auto-compaction calculations. Defaults to the model's context window: 200K for standard models or 1M for extended context models. Use a lower value like `500000` on a 1M model (e.g., `claude-opus-4-6[1m]`) to treat the window as 500K for compaction purposes. The value is capped at the model's actual context window. `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` is applied as a percentage of this value. Setting this variable decouples the compaction threshold from the status line's `used_percentage`, which always uses the model's full context window.\n\nYou can find more options here: [Claude Code settings](https://docs.anthropic.com/en/docs/claude-code/settings#environment-variables)\n\nYou can also read more about IDE integration here: [Add Claude Code to your IDE](https://docs.anthropic.com/en/docs/claude-code/ide-integrations)\n\n## Using with OpenCode\n\nOpenCode already has a direct GitHub Copilot provider. Use this section when you want OpenCode to point at this AI gateway through `@ai-sdk/anthropic` and reuse the agent behaviors described earlier in this README.\n\n### Minimal setup\n\nStart the AI gateway with the OpenCode OAuth app:\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth --oauth-app=opencode\nnpx @jeffreycao/copilot-api@latest start\n```\n\nThen point OpenCode at the gateway with `@ai-sdk/anthropic`.\n\nExample `~/.config/opencode/opencode.json`:\n\n```json\n{\n  \"$schema\": \"https://opencode.ai/config.json\",\n  \"provider\": {\n    \"local\": {\n      \"npm\": \"@ai-sdk/anthropic\",\n      \"name\": \"My Local\",\n      \"options\": {\n        \"baseURL\": \"http://localhost:4141/v1\",\n        \"apiKey\": \"dummy\"\n      },\n      \"models\": {\n        \"gpt-5.4\": {\n          \"name\": \"gpt-5.4\",\n          \"modalities\": {\n            \"input\": [\"text\", \"image\"],\n            \"output\": [\"text\"]\n          },\n          \"limit\": {\n            \"context\": 400000,\n            \"input\": 272000,\n            \"output\": 128000\n          }\n        },\n        \"claude-sonnet-4.6\": {\n          \"id\": \"claude-sonnet-4.6\",\n          \"name\": \"claude-sonnet-4.6\",\n          \"modalities\": {\n            \"input\": [\"text\", \"image\"],\n            \"output\": [\"text\"]\n          },          \n          \"limit\": {\n            \"context\": 200000,\n            \"output\": 32000\n          },\n          \"options\": {\n            \"thinking\": {\n              \"type\": \"adaptive\"\n            },\n            \"effort\": \"max\"\n          }\n        }\n      }\n    }\n  }\n}\n```\n\nWhy these fields matter:\n\n- `npm: \"@ai-sdk/anthropic\"` is the important part. OpenCode will speak Anthropic Messages semantics to this AI gateway instead of flattening everything into OpenAI Chat Completions.\n- `options.baseURL` should be `http://localhost:4141/v1`; the Anthropic SDK will append `/messages`, `/models`, and `/messages/count_tokens` automatically.\n- If you enable `auth.apiKeys` in this AI gateway, replace `dummy` with a real key. Otherwise any placeholder value is fine.\n\n## Using with Codex\n\nThis AI gateway can also power Codex.\n\n### Codex `config.toml` Reference\n\nAdd the following `[model_providers.copilot_api]` section to your Codex `~/.codex/config.toml`:\n\n```toml\nmodel_provider = \"copilot_api\"\nmodel_reasoning_summary = \"auto\"\nmodel_context_window = 272000\nmodel_auto_compact_token_limit = 244800\n\n[model_providers.copilot_api]\nname = \"OpenAI\"\nbase_url = \"http://localhost:4141\"\nenv_key = \"GITHUB_COPILOT_API_KEY\"\nrequires_openai_auth = true\nsupports_websockets = false\nwire_api = \"responses\"\nrequest_max_retries = 3\nstream_max_retries = 1\nstream_idle_timeout_ms = 300000\n\n[features]\nremote_compaction_v2 = true\n\n[analytics]\nenabled = false\n```\n\n> [!NOTE]\n> This configuration is specific to Codex and the GitHub Copilot provider. `name` must be set to `\"OpenAI\"`. It can help mitigate Codex local compact cache miss issues.\n> If you are using the codex provider, it is recommended to set `base_url` to `\"http://localhost:4141/codex\"`.\n\n## GPT Tool Search\n\nFor GPT Responses models such as `gpt-5.4+`, this AI gateway can expose Responses `tool_search` through a small MCP bridge. The same bridge can be used by Claude Code and opencode, as long as the client loads MCP servers and sends Anthropic Messages traffic through this gateway.\n\nDo not set Claude Code's native `ENABLE_TOOL_SEARCH` for GPT models. That flag enables Claude Code's own client-side tool search mode, and it may stop forwarding deferred tool definitions. This gateway needs the full tool definitions so it can keep the small always-loaded tool set eager and translate every other tool into Responses deferred namespaces.\n\nIf you install `tool-search@copilot-api-marketplace`, Claude Code receives this MCP bridge automatically and you can skip the manual Claude Code MCP setup below.\n\nAdd the tool search bridge to the MCP config used by Claude Code:\n\n```json\n{\n  \"mcpServers\": {\n    \"tool_search\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@jeffreycao/copilot-api@latest\", \"mcp\"]\n    }\n  }\n}\n```\n\nAdd the tool search bridge to the MCP config used by opencode:\n\n```json\n{\n  \"mcp\": {\n    \"tool_search\": {\n      \"type\": \"local\",\n      \"command\": [\"npx\", \"-y\", \"@jeffreycao/copilot-api@latest\", \"mcp\"]\n    }\n  }\n}\n```\n\nFor local development, use `bun` as the command and `[\"run\", \"./src/main.ts\", \"mcp\"]` as the args.\n\nInternally, the gateway now configures OpenAI Responses `tool_search` in client-executed mode. Deferred tools are still exposed as searchable namespaces, but the model is explicitly asked to return the exact deferred tool names it wants to load next.\n\nThe bridge uses direct tool selection, not query search. Its tool input is `names`, a comma-separated list of exact deferred tool names, for example `TaskList,TaskGet,mcp__fetch__fetch`.\n\n## Plugin Integrations\n\nPlugin integrations are available for Claude Code and opencode.\n\n#### Claude Code plugin integration (marketplace-based)\n\nThe Claude Code integration is packaged as two plugins:\n\n- `agent-inject` injects `__SUBAGENT_MARKER__...` on `SubagentStart`, so the gateway can infer `x-initiator: agent`.\n- `tool-search` registers the `tool_search` MCP bridge used for GPT Responses deferred tool loading.\n\n- Marketplace catalog in this repository: `.claude-plugin/marketplace.json`\n- Plugin sources in this repository: `plugin/claude/agent-inject`, `plugin/claude/tool-search`\n\nAdd the marketplace remotely:\n\n```sh\n/plugin marketplace add https://github.com/caozhiyuan/copilot-api.git\n```\n\nInstall the plugins from the marketplace:\n\n```sh\n/plugin install agent-inject@copilot-api-marketplace\n/plugin install tool-search@copilot-api-marketplace\n```\n\nAfter installation, `agent-inject` injects `__SUBAGENT_MARKER__...` on `SubagentStart`, and the gateway uses it to infer `x-initiator: agent`.\n\nThe `agent-inject` plugin also registers a `UserPromptSubmit` hook that returns `{\"continue\": true}`, and it can inject `SessionStart` reminder rules through environment variables:\n\n- `CLAUDE_PLUGIN_ENABLE_QUESTION_RULES=1` enables the two reminders about using the `question` tool automatically for Claude Code. Alternatively, you can add the same reminders manually in `CLAUDE.md`; see [CLAUDE.md or AGENTS.md Recommended Content](#claudemd-or-agentsmd-recommended-content).\n- `CLAUDE_PLUGIN_ENABLE_NO_BACKGROUND_AGENTS_RULE=1` enables the `run_in_background: true` avoidance reminder for agent hooks.\n\nThe `tool-search` plugin bundles the same MCP bridge described in [GPT Tool Search](#gpt-tool-search), so Claude Code users do not need to add the `tool_search` server manually when they install that plugin.\n\n#### Opencode plugin\n\nThe subagent marker producer is packaged as an opencode plugin located at `plugin/opencode/subagent-marker.js`.\n\n**Installation:**\n\nCopy the plugin file to your opencode plugins directory:\n\n```sh\n# Clone or download this repository, then copy the plugin\ncp plugin/opencode/subagent-marker.js ~/.config/opencode/plugins/\n```\n\nOr manually create the file at `~/.config/opencode/plugins/subagent-marker.js` with the plugin content.\n\n**Features:**\n\n- Tracks sub-sessions created by subagents\n- Automatically prepends a marker system reminder (`__SUBAGENT_MARKER__...`) to subagent chat messages\n- Sets `x-session-id` header for session tracking\n- Enables the gateway to infer `x-initiator: agent` for subagent-originated requests\n\nThe plugin hooks into `session.created`, `session.deleted`, `chat.message`, and `chat.headers` events to provide seamless subagent marker functionality.\n\n## Using the Usage Viewer\n\nAfter starting the server, a URL to the Copilot Usage Dashboard will be displayed in your console. This dashboard is a web interface for monitoring your API usage.\n\n1.  Start the server. For example, using npx:\n    ```sh\n    npx @jeffreycao/copilot-api@latest start\n    ```\n2.  The server will output a URL to the usage viewer. Copy and paste this URL into your browser. It will look something like this:\n    `http://localhost:4141/usage-viewer?endpoint=http://localhost:4141/usage`\n    - If you use the `start.bat` script on Windows, this page will open automatically.\n\nThe dashboard provides a user-friendly interface to view your Copilot usage data:\n\n> Token usage history requires Bun or Node.js >= 22.13.0. On Node.js < 22.13.0, the server runs normally but token usage storage is disabled.\n\n- **API Endpoint URL**: The dashboard is pre-configured to fetch data from your local server endpoint via a URL query parameter. You can manually switch this to any other compatible API endpoint.\n- **x-api-key Authentication**: If API Key authentication is enabled, you can provide the `x-api-key` request header. The key is persisted in the browser's local storage.\n- **Period Selector**: Choose from Day, Week, or Month time ranges. The URL query parameter updates automatically when you switch, making it easy to bookmark and share.\n- **Fetch Data**: Click the \"Refresh\" button to load or refresh the usage data. The dashboard also fetches data automatically on page load.\n- **Copilot Quotas**: View quota usage for services such as Chat and Completions via progress bars. Hover over a card to see used/remaining details.\n- **Token Usage Metric Cards**: See a summary of Total, Input, Output, Cache Read, Cache Write, Requests, and estimated cost for the current period.\n- **Trend Chart (Week / Month)**: An interactive line chart with model and metric filters. Click a data point to inspect the usage breakdown for a specific day.\n- **Model Breakdown Table**: A per-model summary of requests, input/output/cache tokens, and estimated cost for the selected period.\n- **Request Events (Paginated)**: A time-sorted list of request event records with pagination support, showing timestamps, models, request IDs, and token counts.\n- **Detailed Information**: See the full JSON response from the API for a detailed breakdown of all available usage statistics.\n- **URL-based Configuration**: You can also specify the API endpoint and period directly via `endpoint` and `period` query parameters. For example:\n  `http://localhost:4141/usage-viewer?endpoint=http://your-api-server/usage&period=week`\n\n### Usage Viewer Screenshot\n\n<p align=\"center\">\n  <img src=\"./docs/screenshots/usage-viewer.png\" alt=\"Copilot API usage viewer\" width=\"900\" />\n</p>\n\n## Command Structure\n\nCopilot API now uses a subcommand structure with these main commands:\n\n- `start`: Start the gateway server. If a GitHub token is available, the server starts with Copilot enabled. If no GitHub token is available, it starts in provider-only mode when at least one enabled provider exists; otherwise it guides you through provider setup.\n- `auth`: Run provider login or configuration without starting the server. Use it for GitHub Copilot login, Codex OAuth, or third-party provider API key setup.\n- `debug`: Display diagnostic information including version, runtime details, file paths, and authentication status. Useful for troubleshooting and support.\n\n## Command Line Options\n\n### Global Options\n\nThe following options can be used with any subcommand. When passing them before the subcommand, use the `--key=value` form:\n\n| Option            | Description                                            | Default | Alias |\n| ----------------- | ------------------------------------------------------ | ------- | ----- |\n| --api-home        | Path to the API home directory (sets COPILOT_API_HOME) | none    | none  |\n| --oauth-app       | OAuth app identifier (sets COPILOT_API_OAUTH_APP)      | none    | none  |\n| --enterprise-url  | Enterprise URL for GitHub (sets COPILOT_API_ENTERPRISE_URL) | none | none |\n\n### Start Command Options\n\nThe following command line options are available for the `start` command:\n\n| Option         | Description                                                                   | Default    | Alias |\n| -------------- | ----------------------------------------------------------------------------- | ---------- | ----- |\n| --port         | Port to listen on                                                             | 4141       | -p    |\n| --verbose      | Enable verbose logging                                                        | false      | -v    |\n| --github-token | Provide GitHub token directly (must be generated using the `auth` subcommand) | none       | -g    |\n| --claude-code  | Generate a command to launch Claude Code with Copilot API config              | false      | -c    |\n| --show-token   | Show GitHub and Copilot tokens on fetch and refresh                           | false      | none  |\n| --proxy-env    | Initialize proxy from environment variables                                   | false      | none  |\n\n### Auth Command Options\n\n| Option       | Description               | Default | Alias |\n| ------------ | ------------------------- | ------- | ----- |\n| --provider   | Provider to log in with or configure (`copilot`, `codex`, `opencode-go`, `deepseek`, `dashscope`, `openrouter`, or `custom`) | prompt | none |\n| --verbose    | Enable verbose logging    | false   | -v    |\n| --show-token | Show GitHub token on auth | false   | none  |\n\nUse `copilot-api auth login --provider copilot` only when you want to enable the GitHub Copilot provider. Copilot is not required for `codex` or third-party provider-only usage.\n\nUse `copilot-api auth login --provider deepseek`, `--provider dashscope`, `--provider openrouter`, or `--provider opencode-go` to add or update those common third-party providers from the CLI. DeepSeek prompts for masked `apiKey`, provider `type` (default `anthropic`), and `baseUrl` defaulting to `https://api.deepseek.com/anthropic`. DashScope prompts for masked `apiKey`, provider `type` (default `openai-compatible`), and prefilled `baseUrl`. OpenRouter prompts for masked `apiKey` and prefilled `baseUrl` only, and writes `type: \"anthropic\"`. OpenCode Go prompts for masked `apiKey` and prefilled `baseUrl` only, and writes `type: \"openai-compatible\"` (baseUrl `https://opencode.ai/zen/go`). After a provider is configured and enabled, `copilot-api start` can run without any GitHub token.\n\nUse `copilot-api auth login --provider custom` to add or update another third-party provider from the CLI. The command prompts for the provider name, supported type (`anthropic`, `openai-compatible`, or `openai-responses`), `baseUrl`, masked `apiKey`, and `authType`; `authType` may be left as the type default or set to `x-api-key` / `authorization`.\n\n### Debug Command Options\n\n| Option | Description               | Default | Alias |\n| ------ | ------------------------- | ------- | ----- |\n| --json | Output debug info as JSON | false   | none  |\n\n## Configuration (config.json)\n\n- **Location:** `~/.local/share/copilot-api/config.json` (Linux/macOS) or `%USERPROFILE%\\.local\\share\\copilot-api\\config.json` (Windows).\n- **Default shape:**\n  ```json\n  {\n    \"auth\": {\n      \"apiKeys\": [],\n      \"adminApiKey\": \"<auto-generated-on-startup>\"\n    },\n    \"providers\": {},\n    \"modelMappings\": {},\n    \"extraPrompts\": {\n      \"gpt-5-mini\": \"<built-in exploration prompt>\"\n    },\n    \"smallModel\": \"gpt-5-mini\",\n    \"contextManagement\": {\n      \"messages\": true,\n      \"responses\": false\n    },\n    \"modelResponsesApiCompactThresholds\": {\n      \"gpt-5.4\": 217600,\n      \"gpt-5.5\": 217600\n    },\n    \"modelReasoningEfforts\": {\n      \"gpt-5-mini\": \"low\"\n    },\n    \"useMessagesApi\": true,\n    \"useResponsesApiWebSocket\": true,\n    \"useResponsesApiWebSearch\": true,\n    \"messageApiWebSearchModel\": \"gpt-5-mini\"\n  }\n  ```\n- **auth.apiKeys:** API keys used for request authentication on non-admin routes. Supports multiple keys for rotation. Requests can authenticate with either `x-api-key: <key>` or `Authorization: Bearer <key>`. If empty or omitted, authentication for non-admin routes is disabled.\n- **auth.adminApiKey:** Single admin key used only for `/admin/*` routes. If missing, the server generates a random key at startup and writes it back to `config.json`. Requests use the same `x-api-key` or `Authorization: Bearer` headers, but regular `auth.apiKeys` never grant access to `/admin/*`.\n- **modelMappings:** Exact `sourceModel -> targetModel` rewrites shared by top-level `POST /v1/messages`, `POST /v1/messages/count_tokens`, `POST /v1/responses`, and `POST /v1/chat/completions` requests. Omit it or leave it as `{}` to disable rewrites. Both the source and target must be non-empty strings. Targets can be regular model IDs or `provider/model` aliases such as `dashscope/qwen3.6-plus`, and the rewrite happens before provider alias parsing. These mappings are not split per interface. The admin endpoints `GET/POST /admin/config/model-mappings` read and update only this field.\n- **extraPrompts:** Map of `model -> prompt` appended to the first system prompt when translating Anthropic-style requests to Responses API. Use this to inject guardrails or guidance per model. Missing default entries are auto-added without overwriting your custom prompts. For GPT-5.3+ models (e.g. `gpt-5.3-codex`, `gpt-5.4`, `gpt-5.5`), a built-in commentary prompt is used as fallback when not explicitly configured. The built-in prompts enable phase-aware commentary, which lets the model emit a short user-facing progress update before tools or deeper reasoning.\n- **providers:** Global upstream provider map. Each provider key (for example `dashscope`) becomes a route prefix (`/dashscope/v1/messages`). Supports `type: \"anthropic\"`, `type: \"openai-compatible\"`, and `type: \"openai-responses\"`. Top-level clients can also use `model: \"dashscope/model-id\"` with `/v1/messages`, `/v1/messages/count_tokens`, `/v1/responses`, and `/v1/chat/completions`; the gateway strips the `dashscope/` prefix before forwarding upstream. `openai-compatible` providers support both chat and Messages flows: `/v1/chat/completions` is proxied to upstream `/v1/chat/completions`, while `/v1/messages` and `/:provider/v1/messages` are translated to upstream chat completions and translated back to Anthropic Messages responses. `GET /v1/models` aggregates enabled provider models with `provider/model-id` IDs; use `GET /dashscope/v1/models` for a single provider's raw model list.\n  - `enabled` defaults to `true` if omitted.\n  - `baseUrl` should be provider API base URL without the final endpoint. For Anthropic providers, omit `/v1/messages`; for OpenAI-compatible providers, omit `/v1/chat/completions`; for OpenAI Responses providers, omit `/v1/responses`.\n  - `apiKey` is used as the upstream credential value and is required for regular providers.\n  - `authType` (optional): Controls how `apiKey` is sent upstream. Supports `x-api-key` and `authorization` for regular providers. Anthropic providers default to `x-api-key`; OpenAI-compatible and OpenAI Responses providers default to `authorization`. When set to `authorization`, the proxy sends `Authorization: Bearer <apiKey>`. `oauth2` is reserved for the built-in `codex` provider and is written automatically by `auth login --provider codex`.\n  - `pricingCurrency` (optional): Provider-level currency used for token cost calculation, for example `USD` or `CNY`. Quick providers default to `CNY` for DashScope and DeepSeek, and `USD` for Codex/OpenRouter. Costs are grouped by currency and are not exchange-rate converted.\n  - `models` (optional): Per-model configuration map. Each key is a model ID (matching the model name in requests), and the value is:\n    - `temperature` (optional): Default temperature value used when the request does not specify one.\n    - `topP` (optional): Default top_p value used when the request does not specify one.\n    - `topK` (optional): Default top_k value used when the request does not specify one.\n    - `extraBody` (optional): Dynamic fields merged into the upstream request body for that model. Request body fields with the same name take precedence. OpenAI-compatible providers can use this for fields such as `enable_thinking`, `preserve_thinking`, `reasoning_effort`. `thinking_budget` is a special OpenAI-compatible provider override: when configured in `extraBody`, it is forced after Anthropic `thinking.budget_tokens` translation and overrides the request-derived budget. For providers whose name is `dashscope` or whose `baseUrl` contains `aliyuncs.com`, the request-derived `thinking_budget` (from Anthropic `thinking.budget_tokens`) is forwarded upstream; for other OpenAI-compatible providers the request-derived `thinking_budget` is stripped, while an `extraBody` `thinking_budget` is still honored. For DashScope providers, `preserve_thinking` defaults to `true` when not explicitly set in `extraBody` or the request body.\n    - `pricing` (optional): Per-model token prices, in the provider `pricingCurrency`, per 1M tokens. Supported fields are `input`, `output`, `cachedInput` (implicit cache read), `explicitCachedInput` (explicit cache read), and `cacheCreationInput`. Use `tiers` with `maxInputTokens` for input-size tiered pricing.\n    - `contextCache` (optional): Defaults to `true` for providers whose name is `dashscope` or whose `baseUrl` contains `aliyuncs.com`; defaults to `false` for other OpenAI-compatible providers. This enables Alibaba Cloud Model Studio/DashScope explicit context cache by injecting `cache_control: { \"type\": \"ephemeral\" }` on up to 4 content blocks using the Context Cache format. The cache breakpoint strategy matches opencode's main provider flow: the first 2 system messages plus the last 2 non-system messages. Marked string content is converted to text content part arrays for `system` / `user` / `assistant` / `tool` messages; existing array content is marked on the last part. Set this to `false` when the model already supports implicit caching, or when the upstream does not accept this explicit-cache extension field. Set this to `true` for non-DashScope providers that support the same explicit-cache extension. Applied on both `/v1/messages` and `/v1/chat/completions` routes.\n    - `supportPdf` (optional): Controls whether the model supports PDF/document content. Defaults to `false`; unsupported PDFs are converted to a text notice. Set it to `true` to send PDF/document blocks as OpenAI Chat Completions file parts.\n    - `toolContentSupportType` (optional): Tool result content capabilities for that model, as an array of `array`, `image`, and `pdf`. Provider routes default to string-only tool content when omitted. If `supportPdf` is `true` but this list does not include `pdf`, file parts in tool results are moved to user role messages. This provider default does not change the Copilot main flow, which continues to support array + image and not PDF.\n    - `type` (optional): Per-model override of the provider protocol type. Supports `anthropic`, `openai-compatible`, and `openai-responses`. When set, the provider's `/v1/messages` route uses this model's type instead of the provider-level type for request routing, auth header resolution, and upstream endpoint selection. This is useful for providers like OpenCode Go whose upstream supports both OpenAI-compatible and Anthropic Messages APIs for different models. When the type is overridden, the auth header is resolved from the overridden type's default (Anthropic defaults to `x-api-key`; OpenAI-compatible/Responses default to `authorization`).\n\n  Example DashScope model settings:\n  ```json\n  {\n    \"providers\": {\n      \"dashscope\": {\n        \"type\": \"openai-compatible\",\n        \"enabled\": true,\n        \"baseUrl\": \"https://dashscope.aliyuncs.com/compatible-mode\",\n        \"apiKey\": \"sk-your-dashscope-key\",\n        \"pricingCurrency\": \"CNY\",\n        \"models\": {\n          \"qwen3.7-plus\": {\n            \"temperature\": 1,\n            \"topP\": 0.95,\n            \"topK\": 20,\n            \"extraBody\": {\n              \"preserve_thinking\": true\n            }\n          },\n          \"glm-5.1\": {\n            \"temperature\": 0.7,\n            \"topP\": 0.95,\n            \"contextCache\": true,\n            \"pricing\": {\n              \"tiers\": [\n                {\n                  \"maxInputTokens\": 32000,\n                  \"input\": 6,\n                  \"cachedInput\": 1.2,\n                  \"explicitCachedInput\": 0.6,\n                  \"cacheCreationInput\": 7.5,\n                  \"output\": 24\n                },\n                {\n                  \"maxInputTokens\": 200000,\n                  \"input\": 8,\n                  \"cachedInput\": 1.6,\n                  \"explicitCachedInput\": 0.8,\n                  \"cacheCreationInput\": 10,\n                  \"output\": 28\n                }\n              ]\n            },\n            \"extraBody\": {\n              \"preserve_thinking\": true\n            }\n          }\n        }\n      }\n    }\n  }\n  ```\n  Built-in token prices cover Codex GPT models in USD, DashScope `qwen3.7-max`, `qwen3.7-plus`, `glm-5.1`, `glm-5.2` in CNY, DeepSeek `deepseek-v4-flash`, `deepseek-v4-pro`, `deepseek-chat`, `deepseek-reasoner` in CNY, and OpenCode Go models (`hy3`, `gpt-5.6-luna`, `glm-5.2`, `grok-4.5`, `deepseek-v4-flash`, `deepseek-v4-pro`, `kimi-k2.7-code`, `kimi-k3`, `mimo-v2.5`, `mimo-v2.5-pro`, `qwen3.7-plus`, `qwen3.7-max`, `minimax-m2.7`, `minimax-m3`) in USD. User `pricing` entries override built-ins. For DashScope, cached tokens are charged as explicit cache reads when the upstream usage includes `cache_creation_input_tokens`; otherwise `cachedInput` is used as the implicit cache read price. For DeepSeek, `prompt_cache_hit_tokens` map to cached input and `prompt_cache_miss_tokens` map to regular input.\n- **smallModel:** Fallback model used for tool-less warmup messages (e.g., Claude Code probe requests); defaults to gpt-5-mini. The gateway forces this small model on no-tool warmup or probe requests to avoid consuming premium requests. This behavior only applies to non-token-based-billing GitHub Copilot accounts (`token_based_billing` is false); for token-based-billing accounts the warmup small-model fallback is skipped since there is no premium-request quota to preserve.\n- **contextManagement:** Controls whether the proxy adds Responses API `context_management` compaction instructions. `messages` applies when Anthropic-style `/v1/messages` requests are translated to Responses API, including `openai-responses` provider message routes, and defaults to `true`. `responses` applies to native `/v1/responses` traffic, including `provider/model` aliases and the built-in `codex` provider, and defaults to `false`. Enable `responses` only after checking that your client supports context management compaction. When enabled, the request includes `context_management` in the body and keeps only the latest compaction carrier on follow-up turns. **Note:** Context management is forcibly disabled for GPT-5.6 and above models (e.g. `gpt-5.6-sol`, `gpt-5.6-terra`, `gpt-5.6-luna`) because enabling it breaks prompt cache hits on those models. This override takes precedence over the `contextManagement` and `modelResponsesApiCompactThresholds` settings.\n - **modelResponsesApiCompactThresholds:** Per-model Responses API `compact_threshold` overrides used when the proxy adds `context_management`. These values take precedence over the fallback threshold from `resolveResponsesCompactThreshold` (`max_prompt_tokens * ratio`, or the default fallback). Defaults set `gpt-5.4` and `gpt-5.5` to `217600` (`272000 * 0.8`). Models not listed continue to use the normal fallback logic.\n- **modelReasoningEfforts:** Per-model fallback reasoning effort for `/v1/messages` requests. It is used only when the request does not provide `output_config.effort`.\n  - **Priority:** request `output_config.effort` > `modelReasoningEfforts[model]` > built-in default (`xhigh` for GPT-5.3+ models, otherwise `high`).\n  - **Forwarding:** the resolved value remains `output_config.effort` for the Copilot native Messages API and becomes `reasoning.effort` when translated to the Responses API.\n  - **Configuration values:** `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`.\n- **useMessagesApi:** When `true`, Claude-family models that support Copilot's native `/v1/messages` endpoint will use the Messages API; otherwise they fall back to `/chat/completions`. Set to `false` to disable Messages API routing and always use `/chat/completions`. Defaults to `true`.\n- **useResponsesApiWebSocket:** When `true`, Responses API requests use Copilot's websocket transport for models that advertise `ws:/responses`; models that only advertise `/responses` continue to use HTTP. Set to `false` to disable websocket routing and use HTTP `/responses` whenever the selected model supports it. Defaults to `true`. If the Responses API WebSocket gets closed, it is usually caused by your own network. If you are using a VPN, try switching to a different node.\n- **useResponsesApiWebSearch:** When `true`, the server keeps Responses API tools with `type: \"web_search\"` and forwards them upstream. Set to `false` to strip those tools from `/responses` payloads. Defaults to `true`.\n- **messageApiWebSearchModel:** Global fallback model used when a top-level Copilot `/v1/messages` request contains only the server-side `web_search` tool. Defaults to `gpt-5-mini`. If the value is a `provider/model` alias, the request is routed into that provider's Messages API path with the provider prefix stripped. For Copilot GPT models, web search runs through `/responses`. Mixed `web_search` plus custom tools are not supported and the server-side `web_search` tool is stripped.\n- **claudeTokenMultiplier:** Multiplier applied to the fallback GPT-tokenizer estimate for Claude `/v1/messages/count_tokens` requests. Defaults to `1.15`. Increase it if your client is still compacting too late. This setting is only used when the proxy is estimating Claude tokens locally; if `anthropicApiKey` is configured and Anthropic token counting succeeds, the exact Anthropic count is returned instead.\n- **anthropicApiKey:** Anthropic API key used to forward Claude `/v1/messages/count_tokens` requests to Anthropic's real token counting endpoint, which returns exact counts instead of GPT tokenizer estimates. Can also be set via the `ANTHROPIC_API_KEY` environment variable. If not set, or if the upstream call fails, token counting falls back to local GPT tokenizer estimation controlled by `claudeTokenMultiplier`.\n\nEdit this file to customize prompts or swap in your own fast model. Restart the server (or rerun the command) after changes so the cached config is refreshed.\n\n## API Authentication\n\n- **Protected non-admin routes:** All routes except `/`, `/usage-viewer`, and `/usage-viewer/` require authentication when `auth.apiKeys` is configured and non-empty.\n- **Admin routes:** All `/admin/*` routes require `auth.adminApiKey`. If it is missing, the server generates one at startup and persists it to `config.json` before serving requests.\n- **Allowed auth headers:**\n  - `x-api-key: <your_key>`\n  - `Authorization: Bearer <your_key>`\n- **CORS preflight:** `OPTIONS` requests are always allowed.\n- **When no regular keys are configured:** Non-admin routes continue to allow requests. This does not apply to `/admin/*`, which only accepts `auth.adminApiKey`.\n\nExample request for a regular protected route:\n\n```sh\ncurl http://localhost:4141/v1/models \\\n  -H \"x-api-key: your_api_key\"\n```\n\nExample request for an admin route:\n\n```sh\ncurl http://localhost:4141/admin/config/model-mappings \\\n  -H \"x-api-key: your_admin_api_key\"\n```\n\n## API Endpoints\n\nThe server exposes several OpenAI- and Anthropic-compatible endpoints. Requests can target GitHub Copilot, the built-in `codex` provider, or configured providers depending on the selected model and `provider/model` alias.\n\n### OpenAI Compatible Endpoints\n\nThese endpoints mimic the OpenAI API structure.\n\n| Endpoint                    | Method | Description                                                      |\n| --------------------------- | ------ | ---------------------------------------------------------------- |\n| `POST /v1/responses`        | `POST` | OpenAI Most advanced interface for generating model responses. Supports `provider/model` aliases for `openai-responses` providers. |\n| `POST /v1/chat/completions` | `POST` | Creates a model response for the given chat conversation. Supports `provider/model` aliases for `openai-compatible` providers and can be used without Copilot when the target provider is configured. |\n| `GET /v1/models`            | `GET`  | Lists Copilot models plus enabled provider models using `provider/model-id` IDs. Requests from Codex clients (`User-Agent` beginning with `codex`) are forwarded to the Codex Models upstream. |\n| `POST /v1/embeddings`       | `POST` | Creates an embedding vector representing the input text.         |\n\n### Codex Backend Proxy Endpoints\n\nThese endpoints require an active Codex login. Each endpoint is available both without a version prefix and under `/v1`.\n\n| Endpoint | Method | Description |\n| --- | --- | --- |\n| `POST /alpha/search`<br>`POST /v1/alpha/search` | `POST` | Transparently forwards the JSON body and query parameters to the Codex Alpha Search upstream. |\n| `POST /images/generations`<br>`POST /v1/images/generations` | `POST` | Forwards a JSON image generation request to the Codex Images upstream. When the request omits `Content-Type`, the gateway defaults it to `application/json`. |\n| `POST /images/edits`<br>`POST /v1/images/edits` | `POST` | Forwards an image edit request to the Codex Images upstream. Send this request as `multipart/form-data` and let the HTTP client generate the `boundary`; the gateway preserves the incoming content type and streams the upload body. |\n\nFor every endpoint above, the gateway replaces client authorization and account headers with the active Codex login, preserves query parameters and compatible request headers, and returns the upstream status, headers, and body.\n\n### Anthropic Compatible Endpoints\n\nThese endpoints are designed to be compatible with the Anthropic Messages API. Provider-scoped models, Responses, alpha-search, and images routes accept both unversioned and `/v1` paths; Messages routes remain under `/v1`.\n\n| Endpoint                         | Method | Description                                                  |\n| -------------------------------- | ------ | ------------------------------------------------------------ |\n| `POST /v1/messages`              | `POST` | Creates a model response for a given conversation. Supports `provider/model` aliases for configured providers, including translation through `openai-compatible` providers. |\n| `POST /v1/messages/count_tokens` | `POST` | Calculates the number of tokens for a given set of messages. Supports `provider/model` aliases for configured providers. |\n| `POST /:provider/v1/messages`       | `POST` | Proxies Anthropic Messages requests to the configured Anthropic provider, translates them through an OpenAI-compatible provider, or translates them through an OpenAI Responses provider. |\n| `GET /:provider/models`<br>`GET /:provider/v1/models` | `GET` | Proxies model listing requests to the configured provider. For `codex`, returns the built-in catalog by default; Codex clients (`User-Agent` starting with `codex`) are forwarded to the Codex Models upstream. |\n| `POST /:provider/v1/messages/count_tokens` | `POST` | Calculates tokens locally for provider route requests. |\n| `POST /:provider/responses`<br>`POST /:provider/v1/responses` | `POST` | Proxies OpenAI Responses requests to a configured `openai-responses` provider (including `codex`). |\n| `POST /:provider/alpha/search`<br>`POST /:provider/v1/alpha/search` | `POST` | Proxies alpha-search requests. For `codex`, forwards to the Codex Alpha Search upstream; for other providers, forwards to `{baseUrl}/v1/alpha/search`. |\n| `POST /:provider/images/generations`<br>`POST /:provider/v1/images/generations` | `POST` | Proxies image generation. For `codex`, uses the Codex Images upstream; for other providers, forwards to `{baseUrl}/v1/images/generations` (15-minute timeout). |\n| `POST /:provider/images/edits`<br>`POST /:provider/v1/images/edits` | `POST` | Proxies image edits. For `codex`, uses the Codex Images upstream; for other providers, forwards multipart/streamed bodies to `{baseUrl}/v1/images/edits` (15-minute timeout). |\n\n### Usage Monitoring Endpoints\n\nNew endpoints for monitoring your Copilot usage and quotas.\n\n| Endpoint     | Method | Description                                                  |\n| ------------ | ------ | ------------------------------------------------------------ |\n| `GET /usage` | `GET`  | Get detailed Copilot usage statistics and quota information. |\n| `GET /token` | `GET`  | Get the current Copilot token being used by the API.         |\n\n### Admin / Configuration Endpoints\n\nThese endpoints are reserved for local administrative actions and only accept `auth.adminApiKey`.\n\n| Endpoint                              | Method | Description                                                                 |\n| ------------------------------------- | ------ | --------------------------------------------------------------------------- |\n| `GET /admin/config/model-mappings`    | `GET`  | Returns the current `config.json` path and the active `modelMappings` map.  |\n| `POST /admin/config/model-mappings`   | `POST` | Updates only the `modelMappings` field in `config.json` and returns it back. |\n\n## Example Usage\n\nCommon `npx` commands:\n\n```sh\n# Start the gateway\nnpx @jeffreycao/copilot-api@latest start\n\n# Start on a custom port with verbose logging\nnpx @jeffreycao/copilot-api@latest start --port 8080 --verbose\n\n# Run the auth flow\nnpx @jeffreycao/copilot-api@latest auth login\n\n# Configure a third-party provider, then run without GitHub Copilot\nnpx @jeffreycao/copilot-api@latest auth login --provider dashscope\nnpx @jeffreycao/copilot-api@latest start\n\n# Print debug information as JSON\nnpx @jeffreycao/copilot-api@latest debug --json\n\n# Run the published CLI with Bun instead of Node.js\nbunx --bun @jeffreycao/copilot-api@latest start\n```\n\nOpenAI-compatible provider examples after configuring `dashscope`:\n\n```sh\ncurl http://localhost:4141/v1/chat/completions \\\n  -H \"content-type: application/json\" \\\n  -d '{\"model\":\"dashscope/qwen3.6-plus\",\"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]}'\n\ncurl http://localhost:4141/dashscope/v1/messages \\\n  -H \"content-type: application/json\" \\\n  -d '{\"model\":\"qwen3.6-plus\",\"max_tokens\":1024,\"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]}'\n```\n\n## Usage Tips\n\n### CLAUDE.md or AGENTS.md Recommended Content\n\nTo add these reminders manually, include the following in `CLAUDE.md` for Claude Code, or `AGENTS.md` for opencode/codex:\n\n```\n- Prohibited from directly asking questions to users, MUST use question tool.\n- Once you can confirm that the task is complete, MUST use question tool to make user confirm. The user may respond with feedback if they are not satisfied with the result, which you can use to make improvements and try again, after try again, MUST use question tool to make user confirm again.\n```\n"}, "bdf6879d12488b3c3c32fd9c73bc2cb71cc8eb73": {"t": 1785765532.4341707, "n": 51267, "h": "0638b4cf07fcd150", "c": "# Copilot API Proxy\n\nEnglish | [简体中文](./README.zh-CN.md)\n\n## Important Notes\n\n> [!IMPORTANT]\n> **Before using, please be aware of the following:**\n>\n> 1. **Claude Code configuration:** When using with Claude Code, please configure the model ID as `claude-opus-4-8`. Example claude `settings.json` see [Manual Configuration with `settings.json`](#manual-configuration-with-settingsjson). \n>\n> 2. **Built-in `copilot`, `codex` and third-party providers:** Run `npx @jeffreycao/copilot-api@latest auth` and choose `copilot`, `codex`, `deepseek`, `custom`, or other providers.\n>\n> 3. **Note:** See [GitHub Copilot Security Notice](./NOTICE.md#github-copilot-security-notice) for the warning removed from the README header.\n\n---\n\n## Project Overview\n\nA small AI gateway that can use GitHub Copilot, the built-in `codex` provider, or configured third-party providers such as DashScope. GitHub Copilot is optional: if no GitHub token is available, the server can still start in provider-only mode as long as at least one enabled provider is configured.\n\nThe gateway exposes OpenAI- and Anthropic-compatible APIs from one local endpoint, so tools like [Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview), OpenCode, Codex, and OpenAI-compatible clients can share the same local server.\n\nOn the GitHub Copilot path, the gateway prefers Copilot's native Anthropic-style Messages API when available, preserving more Claude-native behavior for tool-heavy workflows.\n\n## Features\n\n- **OpenAI and Anthropic compatibility**: Serve `/v1/responses`, `/v1/chat/completions`, `/v1/models`, `/v1/embeddings`, and `/v1/messages` from one local gateway.\n- **Copilot is optional**: Use GitHub Copilot when credentials are present, or run the server with only configured providers.\n- **One gateway for Copilot, `codex`, and external providers**: Route GitHub Copilot, the built-in `codex` provider, and configured third-party providers behind the same endpoint.\n- **Standalone third-party providers**: Configure providers such as DashScope, DeepSeek, OpenRouter, or a custom provider and start the gateway without a GitHub Copilot login.\n- **OpenAI-compatible providers on chat and Messages APIs**: `openai-compatible` providers can serve top-level `/v1/chat/completions` through `model: \"provider/model\"` and Anthropic-style `/v1/messages` through request/response translation.\n- **Agent-friendly Claude handling on Copilot**: Prefer native `/v1/messages` when available, preserve Claude-style tool flows, support Anthropic beta features, Claude WebSearch through Responses-capable models, and keep subagent/session markers intact.\n- **Claude Code and OpenCode integration**: Works with Claude Code and OpenCode, including direct Anthropic-compatible usage through `@ai-sdk/anthropic`.\n- **Flexible auth and deployment options**: Supports interactive login or direct tokens, individual/business/enterprise plans, GitHub Enterprise, opencode OAuth, and custom data directories.\n- **Multi-provider routing**: Expose provider-specific `/:provider/...` routes or use `model: \"provider/model\"` on the top-level API.\n\n## Prerequisites\n\n- Bun (>= 1.2.x)\n- Node.js if you plan to run the published CLI with `npx`\n- GitHub account with Copilot subscription only if you want to use the GitHub Copilot provider\n- An API key or OAuth login for at least one configured provider if you want to run without GitHub Copilot\n\n## Installation\n\nTo install dependencies, run:\n\n```sh\nbun install\n```\n\nTo start the server directly from source:\n\n```sh\nbun run start start\n```\n\n## Running from Source\n\nThe project can be run from source in several ways:\n\n### Development Mode\n\n```sh\nbun run dev start\n```\n\n### Production Mode\n\n```sh\nbun run start start\n```\n\n## Using with npx\n\nYou can run the project directly using npx:\n\n> [!IMPORTANT]\n> Token usage storage uses Node's built-in `node:sqlite` module when running with `npx`. It is enabled on Node.js >= 22.13.0. On Node.js < 22.13.0, the CLI still starts, but token usage storage is disabled.\n>\n> If you want token usage storage without upgrading Node.js, run the published CLI with Bun instead: `bunx --bun @jeffreycao/copilot-api@latest start`.\n\n```sh\nnpx @jeffreycao/copilot-api@latest start\n```\n\nWith options:\n\n```sh\nnpx @jeffreycao/copilot-api@latest start --port 8080\n```\n\nFor authentication or provider configuration only:\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth\n```\n\nTo run without GitHub Copilot, configure at least one provider first, then start the server normally:\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth login --provider dashscope\nnpx @jeffreycao/copilot-api@latest start\n```\n\n## Using with Docker\n\nBuild the image:\n\n```sh\ndocker build -t copilot-api .\n```\n\nRun the container with a bind mount so auth data survives restarts:\n\n```sh\nmkdir -p ./copilot-data\ndocker run -p 4141:4141 -v $(pwd)/copilot-data:/root/.local/share/copilot-api copilot-api\n```\n\nThis stores GitHub auth data, provider config, and other gateway state in `./copilot-data` on the host, mapped to `/root/.local/share/copilot-api` in the container.\n\nOr pass a GitHub token directly:\n\n```sh\ndocker run -p 4141:4141 -e GH_TOKEN=your_github_token_here copilot-api\n```\n\n## Electron Desktop App\n\nIf you prefer a GUI, this repository also includes an Electron desktop app in `desktop/`. It supports GitHub Copilot sign-in, OpenAI Codex OAuth, and API-key configuration for DeepSeek, DashScope, OpenRouter, or a custom provider. After authorization or provider configuration, it can start and stop the local proxy with one click and shows the local endpoint, auth header, available models, usage, and logs in the app.\n\nThe settings screen also exposes `OAuth App`, `API Home`, `Enterprise URL`, verbose logging, and minimize-to-tray. Windows x64 (`.exe`), macOS Apple Silicon (`.dmg`), and Linux x64 (`.AppImage`) packages are published in GitHub Releases:\n\nhttps://github.com/caozhiyuan/copilot-api/releases\n\nOn Linux, make the downloaded AppImage executable before launching it:\n\n```sh\nchmod +x Copilot-API-*-linux-x86_64.AppImage\n./Copilot-API-*-linux-x86_64.AppImage\n```\n\nDownload the installer for your platform, authorize or configure a provider inside the app, choose a port, start the server, then point your client at the local endpoint shown in the app. Packaged desktop builds use the bundled Electron runtime, so normal desktop usage does not require installing Node.js separately. Token usage history is enabled when that bundled runtime supports SQLite.\n\nThe desktop app's Advanced Config page reads and writes the shared model mappings through `GET/POST /admin/config/model-mappings`. The same mappings apply across `POST /v1/messages`, `POST /v1/messages/count_tokens`, `POST /v1/responses`, and `POST /v1/chat/completions` instead of being split per interface. It uses `auth.adminApiKey` instead of the regular `auth.apiKeys`, and the app reads that key directly from `config.json` after the server has generated it on startup.\n\n### Desktop App Screenshots\n\nMain dashboard, token usage breakdown in the bundled Electron app:\n\n<p align=\"center\">\n  <img src=\"./docs/screenshots/desktop-dashboard.png\" alt=\"Copilot API desktop app dashboard\" width=\"49%\" />\n  <img src=\"./docs/screenshots/desktop-token-usage.png\" alt=\"Copilot API desktop app token usage view\" width=\"49%\" />\n</p>\n\n## Using with Claude Code\n\nThis AI gateway can be used to power [Claude Code](https://docs.anthropic.com/en/claude-code), an experimental conversational AI assistant for developers from Anthropic.\n\nThere are two ways to configure Claude Code to use this AI gateway:\n\n### Interactive Setup with `--claude-code` flag\n\nTo get started, run the `start` command with the `--claude-code` flag:\n\n```sh\nnpx @jeffreycao/copilot-api@latest start --claude-code\n```\n\nYou will no longer be prompted to pick models manually. The gateway automatically detects the latest available model for each Claude Code size tier — opus maps to the newest Opus model, sonnet to the newest Sonnet model, and haiku to the newest Haiku model — and generates a command that sets `ANTHROPIC_DEFAULT_OPUS_MODEL`, `ANTHROPIC_DEFAULT_SONNET_MODEL`, and `ANTHROPIC_DEFAULT_HAIKU_MODEL` accordingly. Any tier without a matching model available is omitted. The command is copied to your clipboard and sets the environment variables needed for Claude Code to use the gateway.\n\nPaste and run this command in a new terminal to launch Claude Code.\n\n### Manual Configuration with `settings.json`\n\nAlternatively, you can configure Claude Code by creating a `.claude/settings.json` file in your project's root directory. This file should contain the environment variables needed by Claude Code. This way you don't need to run the interactive setup every time.\n\nHere is an example `.claude/settings.json` file:\n\n```json\n{\n  \"env\": {\n    \"ANTHROPIC_BASE_URL\": \"http://localhost:4141\",\n    \"ANTHROPIC_AUTH_TOKEN\": \"dummy\",\n    \"ANTHROPIC_MODEL\": \"gpt-5.6-sol[1m]\",\n    \"ANTHROPIC_DEFAULT_SONNET_MODEL\": \"gpt-5.6-sol[1m]\",\n    \"ANTHROPIC_DEFAULT_HAIKU_MODEL\": \"gpt-5.6-luna[1m]\",\n    \"CLAUDE_CODE_AUTO_COMPACT_WINDOW\": \"272000\",\n    \"CLAUDE_CODE_USE_VERTEX\": \"0\",\n    \"CLAUDE_CODE_USE_BEDROCK\": \"0\",\n    \"DISABLE_NON_ESSENTIAL_MODEL_CALLS\": \"1\",\n    \"CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC\": \"1\",\n    \"CLAUDE_CODE_ATTRIBUTION_HEADER\": \"0\",\n    \"CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION\": \"false\",\n    \"CLAUDE_CODE_DISABLE_TERMINAL_TITLE\": \"true\",\n    \"CLAUDE_CODE_ENABLE_AWAY_SUMMARY\": \"0\"\n  },\n  \"alwaysThinkingEnabled\": true,\n  \"effortLevel\": \"xhigh\",\n  \"showThinkingSummaries\": true\n}\n```\n\n- Replace `ANTHROPIC_MODEL`, `ANTHROPIC_DEFAULT_OPUS_MODEL`, `ANTHROPIC_DEFAULT_SONNET_MODEL`, and `ANTHROPIC_DEFAULT_HAIKU_MODEL` according to your needs. After configuration, please install the claude code plugin [Plugin Integrations](#plugin-integrations).  \n- If you are using the codex provider, it is recommended **not** to configure the model name in the `codex/xxx` format (e.g. `codex/gpt-5.6-sol`). Claude Code treats the `codex/` prefix as a special pattern and applies degraded behavior — for example, it strips all previously returned thinking blocks on every request. Use the plain model name (e.g. `gpt-5.6-sol`) instead, and add a `modelMappings` entry in `config.json` to route it back to the codex provider:\n  ```json\n  \"modelMappings\": {\n    \"gpt-5.6-sol\": \"codex/gpt-5.6-sol\",\n    \"gpt-5.6-terra\": \"codex/gpt-5.6-terra\",\n    \"gpt-5.6-luna\": \"codex/gpt-5.6-luna\"\n  },\n  ```\n- Setting CLAUDE_CODE_ATTRIBUTION_HEADER to 0 can prevent Claude code from adding billing and version information in system prompts, thereby avoiding prompt cache invalidation.\n- Turning off CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION and CLAUDE_CODE_ENABLE_AWAY_SUMMARY can prevent quota from being consumed unnecessarily.\n- Claude Code WebSearch is supported for pure search requests. For Copilot, keep the global `messageApiWebSearchModel` set to a Responses-capable GPT model or a `provider/model` alias. For provider routes, use a native Anthropic provider or an `openai-responses` provider. Add `WebSearch` to `permissions.deny` only if you want to forbid this traffic.\n- If using a non-Claude model, do not enable ENABLE_TOOL_SEARCH. If using the Claude model, can enable ENABLE_TOOL_SEARCH. The current Claude Code uses the client tool search mode. In this mode, loading defer tools requires an additional request each time.\n- `CLAUDE_CODE_AUTO_COMPACT_WINDOW`: Set the context capacity in tokens used for auto-compaction calculations. Defaults to the model's context window: 200K for standard models or 1M for extended context models. Use a lower value like `500000` on a 1M model (e.g., `claude-opus-4-6[1m]`) to treat the window as 500K for compaction purposes. The value is capped at the model's actual context window. `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` is applied as a percentage of this value. Setting this variable decouples the compaction threshold from the status line's `used_percentage`, which always uses the model's full context window.\n\nYou can find more options here: [Claude Code settings](https://docs.anthropic.com/en/docs/claude-code/settings#environment-variables)\n\nYou can also read more about IDE integration here: [Add Claude Code to your IDE](https://docs.anthropic.com/en/docs/claude-code/ide-integrations)\n\n## Using with OpenCode\n\nOpenCode already has a direct GitHub Copilot provider. Use this section when you want OpenCode to point at this AI gateway through `@ai-sdk/anthropic` and reuse the agent behaviors described earlier in this README.\n\n### Minimal setup\n\nStart the AI gateway with the OpenCode OAuth app:\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth --oauth-app=opencode\nnpx @jeffreycao/copilot-api@latest start\n```\n\nThen point OpenCode at the gateway with `@ai-sdk/anthropic`.\n\nExample `~/.config/opencode/opencode.json`:\n\n```json\n{\n  \"$schema\": \"https://opencode.ai/config.json\",\n  \"provider\": {\n    \"local\": {\n      \"npm\": \"@ai-sdk/anthropic\",\n      \"name\": \"My Local\",\n      \"options\": {\n        \"baseURL\": \"http://localhost:4141/v1\",\n        \"apiKey\": \"dummy\"\n      },\n      \"models\": {\n        \"gpt-5.4\": {\n          \"name\": \"gpt-5.4\",\n          \"modalities\": {\n            \"input\": [\"text\", \"image\"],\n            \"output\": [\"text\"]\n          },\n          \"limit\": {\n            \"context\": 400000,\n            \"input\": 272000,\n            \"output\": 128000\n          }\n        },\n        \"claude-sonnet-4.6\": {\n          \"id\": \"claude-sonnet-4.6\",\n          \"name\": \"claude-sonnet-4.6\",\n          \"modalities\": {\n            \"input\": [\"text\", \"image\"],\n            \"output\": [\"text\"]\n          },          \n          \"limit\": {\n            \"context\": 200000,\n            \"output\": 32000\n          },\n          \"options\": {\n            \"thinking\": {\n              \"type\": \"adaptive\"\n            },\n            \"effort\": \"max\"\n          }\n        }\n      }\n    }\n  }\n}\n```\n\nWhy these fields matter:\n\n- `npm: \"@ai-sdk/anthropic\"` is the important part. OpenCode will speak Anthropic Messages semantics to this AI gateway instead of flattening everything into OpenAI Chat Completions.\n- `options.baseURL` should be `http://localhost:4141/v1`; the Anthropic SDK will append `/messages`, `/models`, and `/messages/count_tokens` automatically.\n- If you enable `auth.apiKeys` in this AI gateway, replace `dummy` with a real key. Otherwise any placeholder value is fine.\n\n## Using with Codex\n\nThis AI gateway can also power Codex.\n\n### Codex `config.toml` Reference\n\nAdd the following `[model_providers.copilot_api]` section to your Codex `~/.codex/config.toml`:\n\n```toml\nmodel_provider = \"copilot_api\"\nmodel_reasoning_summary = \"auto\"\nmodel_context_window = 272000\nmodel_auto_compact_token_limit = 244800\n\n[model_providers.copilot_api]\nname = \"OpenAI\"\nbase_url = \"http://localhost:4141\"\nenv_key = \"GITHUB_COPILOT_API_KEY\"\nrequires_openai_auth = true\nsupports_websockets = false\nwire_api = \"responses\"\nrequest_max_retries = 3\nstream_max_retries = 1\nstream_idle_timeout_ms = 300000\n\n[features]\nremote_compaction_v2 = true\n\n[analytics]\nenabled = false\n```\n\n> [!NOTE]\n> This configuration is specific to Codex and the GitHub Copilot provider. `name` must be set to `\"OpenAI\"`. It can help mitigate Codex local compact cache miss issues.\n> If you are using the codex provider, it is recommended to set `base_url` to `\"http://localhost:4141/codex\"`.\n\n## GPT Tool Search\n\nFor GPT Responses models such as `gpt-5.4+`, this AI gateway can expose Responses `tool_search` through a small MCP bridge. The same bridge can be used by Claude Code and opencode, as long as the client loads MCP servers and sends Anthropic Messages traffic through this gateway.\n\nDo not set Claude Code's native `ENABLE_TOOL_SEARCH` for GPT models. That flag enables Claude Code's own client-side tool search mode, and it may stop forwarding deferred tool definitions. This gateway needs the full tool definitions so it can keep the small always-loaded tool set eager and translate every other tool into Responses deferred namespaces.\n\nIf you install `tool-search@copilot-api-marketplace`, Claude Code receives this MCP bridge automatically and you can skip the manual Claude Code MCP setup below.\n\nAdd the tool search bridge to the MCP config used by Claude Code:\n\n```json\n{\n  \"mcpServers\": {\n    \"tool_search\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@jeffreycao/copilot-api@latest\", \"mcp\"]\n    }\n  }\n}\n```\n\nAdd the tool search bridge to the MCP config used by opencode:\n\n```json\n{\n  \"mcp\": {\n    \"tool_search\": {\n      \"type\": \"local\",\n      \"command\": [\"npx\", \"-y\", \"@jeffreycao/copilot-api@latest\", \"mcp\"]\n    }\n  }\n}\n```\n\nFor local development, use `bun` as the command and `[\"run\", \"./src/main.ts\", \"mcp\"]` as the args.\n\nInternally, the gateway now configures OpenAI Responses `tool_search` in client-executed mode. Deferred tools are still exposed as searchable namespaces, but the model is explicitly asked to return the exact deferred tool names it wants to load next.\n\nThe bridge uses direct tool selection, not query search. Its tool input is `names`, a comma-separated list of exact deferred tool names, for example `TaskList,TaskGet,mcp__fetch__fetch`.\n\n## Plugin Integrations\n\nPlugin integrations are available for Claude Code and opencode.\n\n#### Claude Code plugin integration (marketplace-based)\n\nThe Claude Code integration is packaged as two plugins:\n\n- `agent-inject` injects `__SUBAGENT_MARKER__...` on `SubagentStart`, so the gateway can infer `x-initiator: agent`.\n- `tool-search` registers the `tool_search` MCP bridge used for GPT Responses deferred tool loading.\n\n- Marketplace catalog in this repository: `.claude-plugin/marketplace.json`\n- Plugin sources in this repository: `plugin/claude/agent-inject`, `plugin/claude/tool-search`\n\nAdd the marketplace remotely:\n\n```sh\n/plugin marketplace add https://github.com/caozhiyuan/copilot-api.git\n```\n\nInstall the plugins from the marketplace:\n\n```sh\n/plugin install agent-inject@copilot-api-marketplace\n/plugin install tool-search@copilot-api-marketplace\n```\n\nAfter installation, `agent-inject` injects `__SUBAGENT_MARKER__...` on `SubagentStart`, and the gateway uses it to infer `x-initiator: agent`.\n\nThe `agent-inject` plugin also registers a `UserPromptSubmit` hook that returns `{\"continue\": true}`, and it can inject `SessionStart` reminder rules through environment variables:\n\n- `CLAUDE_PLUGIN_ENABLE_QUESTION_RULES=1` enables the two reminders about using the `question` tool automatically for Claude Code. Alternatively, you can add the same reminders manually in `CLAUDE.md`; see [CLAUDE.md or AGENTS.md Recommended Content](#claudemd-or-agentsmd-recommended-content).\n- `CLAUDE_PLUGIN_ENABLE_NO_BACKGROUND_AGENTS_RULE=1` enables the `run_in_background: true` avoidance reminder for agent hooks.\n\nThe `tool-search` plugin bundles the same MCP bridge described in [GPT Tool Search](#gpt-tool-search), so Claude Code users do not need to add the `tool_search` server manually when they install that plugin.\n\n#### Opencode plugin\n\nThe subagent marker producer is packaged as an opencode plugin located at `plugin/opencode/subagent-marker.js`.\n\n**Installation:**\n\nCopy the plugin file to your opencode plugins directory:\n\n```sh\n# Clone or download this repository, then copy the plugin\ncp plugin/opencode/subagent-marker.js ~/.config/opencode/plugins/\n```\n\nOr manually create the file at `~/.config/opencode/plugins/subagent-marker.js` with the plugin content.\n\n**Features:**\n\n- Tracks sub-sessions created by subagents\n- Automatically prepends a marker system reminder (`__SUBAGENT_MARKER__...`) to subagent chat messages\n- Sets `x-session-id` header for session tracking\n- Enables the gateway to infer `x-initiator: agent` for subagent-originated requests\n\nThe plugin hooks into `session.created`, `session.deleted`, `chat.message`, and `chat.headers` events to provide seamless subagent marker functionality.\n\n## Using the Usage Viewer\n\nAfter starting the server, a URL to the Copilot Usage Dashboard will be displayed in your console. This dashboard is a web interface for monitoring your API usage.\n\n1.  Start the server. For example, using npx:\n    ```sh\n    npx @jeffreycao/copilot-api@latest start\n    ```\n2.  The server will output a URL to the usage viewer. Copy and paste this URL into your browser. It will look something like this:\n    `http://localhost:4141/usage-viewer?endpoint=http://localhost:4141/usage`\n    - If you use the `start.bat` script on Windows, this page will open automatically.\n\nThe dashboard provides a user-friendly interface to view your Copilot usage data:\n\n> Token usage history requires Bun or Node.js >= 22.13.0. On Node.js < 22.13.0, the server runs normally but token usage storage is disabled.\n\n- **API Endpoint URL**: The dashboard is pre-configured to fetch data from your local server endpoint via a URL query parameter. You can manually switch this to any other compatible API endpoint.\n- **x-api-key Authentication**: If API Key authentication is enabled, you can provide the `x-api-key` request header. The key is persisted in the browser's local storage.\n- **Period Selector**: Choose from Day, Week, or Month time ranges. The URL query parameter updates automatically when you switch, making it easy to bookmark and share.\n- **Fetch Data**: Click the \"Refresh\" button to load or refresh the usage data. The dashboard also fetches data automatically on page load.\n- **Copilot Quotas**: View quota usage for services such as Chat and Completions via progress bars. Hover over a card to see used/remaining details.\n- **Token Usage Metric Cards**: See a summary of Total, Input, Output, Cache Read, Cache Write, Requests, and estimated cost for the current period.\n- **Trend Chart (Week / Month)**: An interactive line chart with model and metric filters. Click a data point to inspect the usage breakdown for a specific day.\n- **Model Breakdown Table**: A per-model summary of requests, input/output/cache tokens, and estimated cost for the selected period.\n- **Request Events (Paginated)**: A time-sorted list of request event records with pagination support, showing timestamps, models, request IDs, and token counts.\n- **Detailed Information**: See the full JSON response from the API for a detailed breakdown of all available usage statistics.\n- **URL-based Configuration**: You can also specify the API endpoint and period directly via `endpoint` and `period` query parameters. For example:\n  `http://localhost:4141/usage-viewer?endpoint=http://your-api-server/usage&period=week`\n\n### Usage Viewer Screenshot\n\n<p align=\"center\">\n  <img src=\"./docs/screenshots/usage-viewer.png\" alt=\"Copilot API usage viewer\" width=\"900\" />\n</p>\n\n## Command Structure\n\nCopilot API now uses a subcommand structure with these main commands:\n\n- `start`: Start the gateway server. If a GitHub token is available, the server starts with Copilot enabled. If no GitHub token is available, it starts in provider-only mode when at least one enabled provider exists; otherwise it guides you through provider setup.\n- `auth`: Run provider login or configuration without starting the server. Use it for GitHub Copilot login, Codex OAuth, or third-party provider API key setup.\n- `debug`: Display diagnostic information including version, runtime details, file paths, and authentication status. Useful for troubleshooting and support.\n\n## Command Line Options\n\n### Global Options\n\nThe following options can be used with any subcommand. When passing them before the subcommand, use the `--key=value` form:\n\n| Option            | Description                                            | Default | Alias |\n| ----------------- | ------------------------------------------------------ | ------- | ----- |\n| --api-home        | Path to the API home directory (sets COPILOT_API_HOME) | none    | none  |\n| --oauth-app       | OAuth app identifier (sets COPILOT_API_OAUTH_APP)      | none    | none  |\n| --enterprise-url  | Enterprise URL for GitHub (sets COPILOT_API_ENTERPRISE_URL) | none | none |\n\n### Start Command Options\n\nThe following command line options are available for the `start` command:\n\n| Option         | Description                                                                   | Default    | Alias |\n| -------------- | ----------------------------------------------------------------------------- | ---------- | ----- |\n| --port         | Port to listen on                                                             | 4141       | -p    |\n| --verbose      | Enable verbose logging                                                        | false      | -v    |\n| --github-token | Provide GitHub token directly (must be generated using the `auth` subcommand) | none       | -g    |\n| --claude-code  | Generate a command to launch Claude Code with Copilot API config              | false      | -c    |\n| --show-token   | Show GitHub and Copilot tokens on fetch and refresh                           | false      | none  |\n| --proxy-env    | Initialize proxy from environment variables                                   | false      | none  |\n\n### Auth Command Options\n\n| Option       | Description               | Default | Alias |\n| ------------ | ------------------------- | ------- | ----- |\n| --provider   | Provider to log in with or configure (`copilot`, `codex`, `opencode-go`, `deepseek`, `dashscope`, `openrouter`, or `custom`) | prompt | none |\n| --verbose    | Enable verbose logging    | false   | -v    |\n| --show-token | Show GitHub token on auth | false   | none  |\n\nUse `copilot-api auth login --provider copilot` only when you want to enable the GitHub Copilot provider. Copilot is not required for `codex` or third-party provider-only usage.\n\nUse `copilot-api auth login --provider deepseek`, `--provider dashscope`, `--provider openrouter`, or `--provider opencode-go` to add or update those common third-party providers from the CLI. DeepSeek prompts for masked `apiKey`, provider `type` (default `anthropic`), and `baseUrl` defaulting to `https://api.deepseek.com/anthropic`. DashScope prompts for masked `apiKey`, provider `type` (default `openai-compatible`), and prefilled `baseUrl`. OpenRouter prompts for masked `apiKey` and prefilled `baseUrl` only, and writes `type: \"anthropic\"`. OpenCode Go prompts for masked `apiKey` and prefilled `baseUrl` only, and writes `type: \"openai-compatible\"` (baseUrl `https://opencode.ai/zen/go`). After a provider is configured and enabled, `copilot-api start` can run without any GitHub token.\n\nUse `copilot-api auth login --provider custom` to add or update another third-party provider from the CLI. The command prompts for the provider name, supported type (`anthropic`, `openai-compatible`, or `openai-responses`), `baseUrl`, masked `apiKey`, and `authType`; `authType` may be left as the type default or set to `x-api-key` / `authorization`.\n\n### Debug Command Options\n\n| Option | Description               | Default | Alias |\n| ------ | ------------------------- | ------- | ----- |\n| --json | Output debug info as JSON | false   | none  |\n\n## Configuration (config.json)\n\n- **Location:** `~/.local/share/copilot-api/config.json` (Linux/macOS) or `%USERPROFILE%\\.local\\share\\copilot-api\\config.json` (Windows).\n- **Default shape:**\n  ```json\n  {\n    \"auth\": {\n      \"apiKeys\": [],\n      \"adminApiKey\": \"<auto-generated-on-startup>\"\n    },\n    \"providers\": {},\n    \"modelMappings\": {},\n    \"extraPrompts\": {\n      \"gpt-5-mini\": \"<built-in exploration prompt>\"\n    },\n    \"smallModel\": \"gpt-5-mini\",\n    \"contextManagement\": {\n      \"messages\": true,\n      \"responses\": false\n    },\n    \"modelResponsesApiCompactThresholds\": {\n      \"gpt-5.4\": 217600,\n      \"gpt-5.5\": 217600\n    },\n    \"modelReasoningEfforts\": {\n      \"gpt-5-mini\": \"low\"\n    },\n    \"useMessagesApi\": true,\n    \"useResponsesApiWebSocket\": true,\n    \"useResponsesApiWebSearch\": true,\n    \"messageApiWebSearchModel\": \"gpt-5-mini\"\n  }\n  ```\n- **auth.apiKeys:** API keys used for request authentication on non-admin routes. Supports multiple keys for rotation. Requests can authenticate with either `x-api-key: <key>` or `Authorization: Bearer <key>`. If empty or omitted, authentication for non-admin routes is disabled.\n- **auth.adminApiKey:** Single admin key used only for `/admin/*` routes. If missing, the server generates a random key at startup and writes it back to `config.json`. Requests use the same `x-api-key` or `Authorization: Bearer` headers, but regular `auth.apiKeys` never grant access to `/admin/*`.\n- **modelMappings:** Exact `sourceModel -> targetModel` rewrites shared by top-level `POST /v1/messages`, `POST /v1/messages/count_tokens`, `POST /v1/responses`, and `POST /v1/chat/completions` requests. Omit it or leave it as `{}` to disable rewrites. Both the source and target must be non-empty strings. Targets can be regular model IDs or `provider/model` aliases such as `dashscope/qwen3.6-plus`, and the rewrite happens before provider alias parsing. These mappings are not split per interface. The admin endpoints `GET/POST /admin/config/model-mappings` read and update only this field.\n- **extraPrompts:** Map of `model -> prompt` appended to the first system prompt when translating Anthropic-style requests to Responses API. Use this to inject guardrails or guidance per model. Missing default entries are auto-added without overwriting your custom prompts. For GPT-5.3+ models (e.g. `gpt-5.3-codex`, `gpt-5.4`, `gpt-5.5`), a built-in commentary prompt is used as fallback when not explicitly configured. The built-in prompts enable phase-aware commentary, which lets the model emit a short user-facing progress update before tools or deeper reasoning.\n- **providers:** Global upstream provider map. Each provider key (for example `dashscope`) becomes a route prefix (`/dashscope/v1/messages`). Supports `type: \"anthropic\"`, `type: \"openai-compatible\"`, and `type: \"openai-responses\"`. Top-level clients can also use `model: \"dashscope/model-id\"` with `/v1/messages`, `/v1/messages/count_tokens`, `/v1/responses`, and `/v1/chat/completions`; the gateway strips the `dashscope/` prefix before forwarding upstream. `openai-compatible` providers support both chat and Messages flows: `/v1/chat/completions` is proxied to upstream `/v1/chat/completions`, while `/v1/messages` and `/:provider/v1/messages` are translated to upstream chat completions and translated back to Anthropic Messages responses. `GET /v1/models` aggregates enabled provider models with `provider/model-id` IDs; use `GET /dashscope/v1/models` for a single provider's raw model list.\n  - `enabled` defaults to `true` if omitted.\n  - `baseUrl` should be provider API base URL without the final endpoint. For Anthropic providers, omit `/v1/messages`; for OpenAI-compatible providers, omit `/v1/chat/completions`; for OpenAI Responses providers, omit `/v1/responses`.\n  - `apiKey` is used as the upstream credential value and is required for regular providers.\n  - `authType` (optional): Controls how `apiKey` is sent upstream. Supports `x-api-key` and `authorization` for regular providers. Anthropic providers default to `x-api-key`; OpenAI-compatible and OpenAI Responses providers default to `authorization`. When set to `authorization`, the proxy sends `Authorization: Bearer <apiKey>`. `oauth2` is reserved for the built-in `codex` provider and is written automatically by `auth login --provider codex`.\n  - `pricingCurrency` (optional): Provider-level currency used for token cost calculation, for example `USD` or `CNY`. Quick providers default to `CNY` for DashScope and DeepSeek, and `USD` for Codex/OpenRouter. Costs are grouped by currency and are not exchange-rate converted.\n  - `models` (optional): Per-model configuration map. Each key is a model ID (matching the model name in requests), and the value is:\n    - `temperature` (optional): Default temperature value used when the request does not specify one.\n    - `topP` (optional): Default top_p value used when the request does not specify one.\n    - `topK` (optional): Default top_k value used when the request does not specify one.\n    - `extraBody` (optional): Dynamic fields merged into the upstream request body for that model. Request body fields with the same name take precedence. OpenAI-compatible providers can use this for fields such as `enable_thinking`, `preserve_thinking`, `reasoning_effort`. `thinking_budget` is a special OpenAI-compatible provider override: when configured in `extraBody`, it is forced after Anthropic `thinking.budget_tokens` translation and overrides the request-derived budget. For providers whose name is `dashscope` or whose `baseUrl` contains `aliyuncs.com`, the request-derived `thinking_budget` (from Anthropic `thinking.budget_tokens`) is forwarded upstream; for other OpenAI-compatible providers the request-derived `thinking_budget` is stripped, while an `extraBody` `thinking_budget` is still honored. For DashScope providers, `preserve_thinking` defaults to `true` when not explicitly set in `extraBody` or the request body.\n    - `pricing` (optional): Per-model token prices, in the provider `pricingCurrency`, per 1M tokens. Supported fields are `input`, `output`, `cachedInput` (implicit cache read), `explicitCachedInput` (explicit cache read), and `cacheCreationInput`. Use `tiers` with `maxInputTokens` for input-size tiered pricing.\n    - `contextCache` (optional): Defaults to `true` for providers whose name is `dashscope` or whose `baseUrl` contains `aliyuncs.com`; defaults to `false` for other OpenAI-compatible providers. This enables Alibaba Cloud Model Studio/DashScope explicit context cache by injecting `cache_control: { \"type\": \"ephemeral\" }` on up to 4 content blocks using the Context Cache format. The cache breakpoint strategy matches opencode's main provider flow: the first 2 system messages plus the last 2 non-system messages. Marked string content is converted to text content part arrays for `system` / `user` / `assistant` / `tool` messages; existing array content is marked on the last part. Set this to `false` when the model already supports implicit caching, or when the upstream does not accept this explicit-cache extension field. Set this to `true` for non-DashScope providers that support the same explicit-cache extension. Applied on both `/v1/messages` and `/v1/chat/completions` routes.\n    - `supportPdf` (optional): Controls whether the model supports PDF/document content. Defaults to `false`; unsupported PDFs are converted to a text notice. Set it to `true` to send PDF/document blocks as OpenAI Chat Completions file parts.\n    - `toolContentSupportType` (optional): Tool result content capabilities for that model, as an array of `array`, `image`, and `pdf`. Provider routes default to string-only tool content when omitted. If `supportPdf` is `true` but this list does not include `pdf`, file parts in tool results are moved to user role messages. This provider default does not change the Copilot main flow, which continues to support array + image and not PDF.\n    - `type` (optional): Per-model override of the provider protocol type. Supports `anthropic`, `openai-compatible`, and `openai-responses`. When set, the provider's `/v1/messages` route uses this model's type instead of the provider-level type for request routing, auth header resolution, and upstream endpoint selection. This is useful for providers like OpenCode Go whose upstream supports both OpenAI-compatible and Anthropic Messages APIs for different models. When the type is overridden, the auth header is resolved from the overridden type's default (Anthropic defaults to `x-api-key`; OpenAI-compatible/Responses default to `authorization`).\n\n  Example DashScope model settings:\n  ```json\n  {\n    \"providers\": {\n      \"dashscope\": {\n        \"type\": \"openai-compatible\",\n        \"enabled\": true,\n        \"baseUrl\": \"https://dashscope.aliyuncs.com/compatible-mode\",\n        \"apiKey\": \"sk-your-dashscope-key\",\n        \"pricingCurrency\": \"CNY\",\n        \"models\": {\n          \"qwen3.7-plus\": {\n            \"temperature\": 1,\n            \"topP\": 0.95,\n            \"topK\": 20,\n            \"extraBody\": {\n              \"preserve_thinking\": true\n            }\n          },\n          \"glm-5.1\": {\n            \"temperature\": 0.7,\n            \"topP\": 0.95,\n            \"contextCache\": true,\n            \"pricing\": {\n              \"tiers\": [\n                {\n                  \"maxInputTokens\": 32000,\n                  \"input\": 6,\n                  \"cachedInput\": 1.2,\n                  \"explicitCachedInput\": 0.6,\n                  \"cacheCreationInput\": 7.5,\n                  \"output\": 24\n                },\n                {\n                  \"maxInputTokens\": 200000,\n                  \"input\": 8,\n                  \"cachedInput\": 1.6,\n                  \"explicitCachedInput\": 0.8,\n                  \"cacheCreationInput\": 10,\n                  \"output\": 28\n                }\n              ]\n            },\n            \"extraBody\": {\n              \"preserve_thinking\": true\n            }\n          }\n        }\n      }\n    }\n  }\n  ```\n  Built-in token prices cover Codex GPT models in USD, DashScope `qwen3.7-max`, `qwen3.7-plus`, `glm-5.1`, `glm-5.2` in CNY, DeepSeek `deepseek-v4-flash`, `deepseek-v4-pro`, `deepseek-chat`, `deepseek-reasoner` in CNY, and OpenCode Go models (`glm-5.2`, `grok-4.5`, `deepseek-v4-flash`, `deepseek-v4-pro`, `kimi-k2.7-code`, `kimi-k3`, `mimo-v2.5`, `mimo-v2.5-pro`, `qwen3.7-plus`, `qwen3.7-max`, `minimax-m2.7`, `minimax-m3`) in USD. User `pricing` entries override built-ins. For DashScope, cached tokens are charged as explicit cache reads when the upstream usage includes `cache_creation_input_tokens`; otherwise `cachedInput` is used as the implicit cache read price. For DeepSeek, `prompt_cache_hit_tokens` map to cached input and `prompt_cache_miss_tokens` map to regular input.\n- **smallModel:** Fallback model used for tool-less warmup messages (e.g., Claude Code probe requests); defaults to gpt-5-mini. The gateway forces this small model on no-tool warmup or probe requests to avoid consuming premium requests. This behavior only applies to non-token-based-billing GitHub Copilot accounts (`token_based_billing` is false); for token-based-billing accounts the warmup small-model fallback is skipped since there is no premium-request quota to preserve.\n- **contextManagement:** Controls whether the proxy adds Responses API `context_management` compaction instructions. `messages` applies when Anthropic-style `/v1/messages` requests are translated to Responses API, including `openai-responses` provider message routes, and defaults to `true`. `responses` applies to native `/v1/responses` traffic, including `provider/model` aliases and the built-in `codex` provider, and defaults to `false`. Enable `responses` only after checking that your client supports context management compaction. When enabled, the request includes `context_management` in the body and keeps only the latest compaction carrier on follow-up turns. **Note:** Context management is forcibly disabled for GPT-5.6 and above models (e.g. `gpt-5.6-sol`, `gpt-5.6-terra`, `gpt-5.6-luna`) because enabling it breaks prompt cache hits on those models. This override takes precedence over the `contextManagement` and `modelResponsesApiCompactThresholds` settings.\n - **modelResponsesApiCompactThresholds:** Per-model Responses API `compact_threshold` overrides used when the proxy adds `context_management`. These values take precedence over the fallback threshold from `resolveResponsesCompactThreshold` (`max_prompt_tokens * ratio`, or the default fallback). Defaults set `gpt-5.4` and `gpt-5.5` to `217600` (`272000 * 0.8`). Models not listed continue to use the normal fallback logic.\n- **modelReasoningEfforts:** Per-model fallback reasoning effort for `/v1/messages` requests. It is used only when the request does not provide `output_config.effort`.\n  - **Priority:** request `output_config.effort` > `modelReasoningEfforts[model]` > built-in default (`xhigh` for GPT-5.3+ models, otherwise `high`).\n  - **Forwarding:** the resolved value remains `output_config.effort` for the Copilot native Messages API and becomes `reasoning.effort` when translated to the Responses API.\n  - **Configuration values:** `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`.\n- **useMessagesApi:** When `true`, Claude-family models that support Copilot's native `/v1/messages` endpoint will use the Messages API; otherwise they fall back to `/chat/completions`. Set to `false` to disable Messages API routing and always use `/chat/completions`. Defaults to `true`.\n- **useResponsesApiWebSocket:** When `true`, Responses API requests use Copilot's websocket transport for models that advertise `ws:/responses`; models that only advertise `/responses` continue to use HTTP. Set to `false` to disable websocket routing and use HTTP `/responses` whenever the selected model supports it. Defaults to `true`. If the Responses API WebSocket gets closed, it is usually caused by your own network. If you are using a VPN, try switching to a different node.\n- **useResponsesApiWebSearch:** When `true`, the server keeps Responses API tools with `type: \"web_search\"` and forwards them upstream. Set to `false` to strip those tools from `/responses` payloads. Defaults to `true`.\n- **messageApiWebSearchModel:** Global fallback model used when a top-level Copilot `/v1/messages` request contains only the server-side `web_search` tool. Defaults to `gpt-5-mini`. If the value is a `provider/model` alias, the request is routed into that provider's Messages API path with the provider prefix stripped. For Copilot GPT models, web search runs through `/responses`. Mixed `web_search` plus custom tools are not supported and the server-side `web_search` tool is stripped.\n- **claudeTokenMultiplier:** Multiplier applied to the fallback GPT-tokenizer estimate for Claude `/v1/messages/count_tokens` requests. Defaults to `1.15`. Increase it if your client is still compacting too late. This setting is only used when the proxy is estimating Claude tokens locally; if `anthropicApiKey` is configured and Anthropic token counting succeeds, the exact Anthropic count is returned instead.\n- **anthropicApiKey:** Anthropic API key used to forward Claude `/v1/messages/count_tokens` requests to Anthropic's real token counting endpoint, which returns exact counts instead of GPT tokenizer estimates. Can also be set via the `ANTHROPIC_API_KEY` environment variable. If not set, or if the upstream call fails, token counting falls back to local GPT tokenizer estimation controlled by `claudeTokenMultiplier`.\n\nEdit this file to customize prompts or swap in your own fast model. Restart the server (or rerun the command) after changes so the cached config is refreshed.\n\n## API Authentication\n\n- **Protected non-admin routes:** All routes except `/`, `/usage-viewer`, and `/usage-viewer/` require authentication when `auth.apiKeys` is configured and non-empty.\n- **Admin routes:** All `/admin/*` routes require `auth.adminApiKey`. If it is missing, the server generates one at startup and persists it to `config.json` before serving requests.\n- **Allowed auth headers:**\n  - `x-api-key: <your_key>`\n  - `Authorization: Bearer <your_key>`\n- **CORS preflight:** `OPTIONS` requests are always allowed.\n- **When no regular keys are configured:** Non-admin routes continue to allow requests. This does not apply to `/admin/*`, which only accepts `auth.adminApiKey`.\n\nExample request for a regular protected route:\n\n```sh\ncurl http://localhost:4141/v1/models \\\n  -H \"x-api-key: your_api_key\"\n```\n\nExample request for an admin route:\n\n```sh\ncurl http://localhost:4141/admin/config/model-mappings \\\n  -H \"x-api-key: your_admin_api_key\"\n```\n\n## API Endpoints\n\nThe server exposes several OpenAI- and Anthropic-compatible endpoints. Requests can target GitHub Copilot, the built-in `codex` provider, or configured providers depending on the selected model and `provider/model` alias.\n\n### OpenAI Compatible Endpoints\n\nThese endpoints mimic the OpenAI API structure.\n\n| Endpoint                    | Method | Description                                                      |\n| --------------------------- | ------ | ---------------------------------------------------------------- |\n| `POST /v1/responses`        | `POST` | OpenAI Most advanced interface for generating model responses. Supports `provider/model` aliases for `openai-responses` providers. |\n| `POST /v1/chat/completions` | `POST` | Creates a model response for the given chat conversation. Supports `provider/model` aliases for `openai-compatible` providers and can be used without Copilot when the target provider is configured. |\n| `GET /v1/models`            | `GET`  | Lists Copilot models plus enabled provider models using `provider/model-id` IDs. Requests from Codex clients (`User-Agent` beginning with `codex`) are forwarded to the Codex Models upstream. |\n| `POST /v1/embeddings`       | `POST` | Creates an embedding vector representing the input text.         |\n\n### Codex Backend Proxy Endpoints\n\nThese endpoints require an active Codex login. Each endpoint is available both without a version prefix and under `/v1`.\n\n| Endpoint | Method | Description |\n| --- | --- | --- |\n| `POST /alpha/search`<br>`POST /v1/alpha/search` | `POST` | Transparently forwards the JSON body and query parameters to the Codex Alpha Search upstream. |\n| `POST /images/generations`<br>`POST /v1/images/generations` | `POST` | Forwards a JSON image generation request to the Codex Images upstream. When the request omits `Content-Type`, the gateway defaults it to `application/json`. |\n| `POST /images/edits`<br>`POST /v1/images/edits` | `POST` | Forwards an image edit request to the Codex Images upstream. Send this request as `multipart/form-data` and let the HTTP client generate the `boundary`; the gateway preserves the incoming content type and streams the upload body. |\n\nFor every endpoint above, the gateway replaces client authorization and account headers with the active Codex login, preserves query parameters and compatible request headers, and returns the upstream status, headers, and body.\n\n### Anthropic Compatible Endpoints\n\nThese endpoints are designed to be compatible with the Anthropic Messages API. Provider-scoped models, Responses, alpha-search, and images routes accept both unversioned and `/v1` paths; Messages routes remain under `/v1`.\n\n| Endpoint                         | Method | Description                                                  |\n| -------------------------------- | ------ | ------------------------------------------------------------ |\n| `POST /v1/messages`              | `POST` | Creates a model response for a given conversation. Supports `provider/model` aliases for configured providers, including translation through `openai-compatible` providers. |\n| `POST /v1/messages/count_tokens` | `POST` | Calculates the number of tokens for a given set of messages. Supports `provider/model` aliases for configured providers. |\n| `POST /:provider/v1/messages`       | `POST` | Proxies Anthropic Messages requests to the configured Anthropic provider, translates them through an OpenAI-compatible provider, or translates them through an OpenAI Responses provider. |\n| `GET /:provider/models`<br>`GET /:provider/v1/models` | `GET` | Proxies model listing requests to the configured provider. For `codex`, returns the built-in catalog by default; Codex clients (`User-Agent` starting with `codex`) are forwarded to the Codex Models upstream. |\n| `POST /:provider/v1/messages/count_tokens` | `POST` | Calculates tokens locally for provider route requests. |\n| `POST /:provider/responses`<br>`POST /:provider/v1/responses` | `POST` | Proxies OpenAI Responses requests to a configured `openai-responses` provider (including `codex`). |\n| `POST /:provider/alpha/search`<br>`POST /:provider/v1/alpha/search` | `POST` | Proxies alpha-search requests. For `codex`, forwards to the Codex Alpha Search upstream; for other providers, forwards to `{baseUrl}/v1/alpha/search`. |\n| `POST /:provider/images/generations`<br>`POST /:provider/v1/images/generations` | `POST` | Proxies image generation. For `codex`, uses the Codex Images upstream; for other providers, forwards to `{baseUrl}/v1/images/generations` (15-minute timeout). |\n| `POST /:provider/images/edits`<br>`POST /:provider/v1/images/edits` | `POST` | Proxies image edits. For `codex`, uses the Codex Images upstream; for other providers, forwards multipart/streamed bodies to `{baseUrl}/v1/images/edits` (15-minute timeout). |\n\n### Usage Monitoring Endpoints\n\nNew endpoints for monitoring your Copilot usage and quotas.\n\n| Endpoint     | Method | Description                                                  |\n| ------------ | ------ | ------------------------------------------------------------ |\n| `GET /usage` | `GET`  | Get detailed Copilot usage statistics and quota information. |\n| `GET /token` | `GET`  | Get the current Copilot token being used by the API.         |\n\n### Admin / Configuration Endpoints\n\nThese endpoints are reserved for local administrative actions and only accept `auth.adminApiKey`.\n\n| Endpoint                              | Method | Description                                                                 |\n| ------------------------------------- | ------ | --------------------------------------------------------------------------- |\n| `GET /admin/config/model-mappings`    | `GET`  | Returns the current `config.json` path and the active `modelMappings` map.  |\n| `POST /admin/config/model-mappings`   | `POST` | Updates only the `modelMappings` field in `config.json` and returns it back. |\n\n## Example Usage\n\nCommon `npx` commands:\n\n```sh\n# Start the gateway\nnpx @jeffreycao/copilot-api@latest start\n\n# Start on a custom port with verbose logging\nnpx @jeffreycao/copilot-api@latest start --port 8080 --verbose\n\n# Run the auth flow\nnpx @jeffreycao/copilot-api@latest auth login\n\n# Configure a third-party provider, then run without GitHub Copilot\nnpx @jeffreycao/copilot-api@latest auth login --provider dashscope\nnpx @jeffreycao/copilot-api@latest start\n\n# Print debug information as JSON\nnpx @jeffreycao/copilot-api@latest debug --json\n\n# Run the published CLI with Bun instead of Node.js\nbunx --bun @jeffreycao/copilot-api@latest start\n```\n\nOpenAI-compatible provider examples after configuring `dashscope`:\n\n```sh\ncurl http://localhost:4141/v1/chat/completions \\\n  -H \"content-type: application/json\" \\\n  -d '{\"model\":\"dashscope/qwen3.6-plus\",\"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]}'\n\ncurl http://localhost:4141/dashscope/v1/messages \\\n  -H \"content-type: application/json\" \\\n  -d '{\"model\":\"qwen3.6-plus\",\"max_tokens\":1024,\"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]}'\n```\n\n## Usage Tips\n\n### CLAUDE.md or AGENTS.md Recommended Content\n\nTo add these reminders manually, include the following in `CLAUDE.md` for Claude Code, or `AGENTS.md` for opencode/codex:\n\n```\n- Prohibited from directly asking questions to users, MUST use question tool.\n- Once you can confirm that the task is complete, MUST use question tool to make user confirm. The user may respond with feedback if they are not satisfied with the result, which you can use to make improvements and try again, after try again, MUST use question tool to make user confirm again.\n```\n"}, "453b0867b4291c00a08689b6dd303cee6c0544e0": {"t": 1785765533.9680138, "n": 51438, "h": "0bb57ea56ad7c178", "c": "# Copilot API Proxy\n\nEnglish | [简体中文](./README.zh-CN.md)\n\n## Important Notes\n\n> [!IMPORTANT]\n> **Before using, please be aware of the following:**\n>\n> 1. **Claude Code configuration:** When using with Claude Code, please configure the model ID as `claude-opus-4-8`. Example claude `settings.json` see [Manual Configuration with `settings.json`](#manual-configuration-with-settingsjson). \n>\n> 2. **Built-in `copilot`, `codex` and third-party providers:** Run `npx @jeffreycao/copilot-api@latest auth` and choose `copilot`, `codex`, `deepseek`, `custom`, or other providers.\n>\n> 3. **Note:** See [GitHub Copilot Security Notice](./NOTICE.md#github-copilot-security-notice) for the warning removed from the README header.\n\n---\n\n## Project Overview\n\nA small AI gateway that can use GitHub Copilot, the built-in `codex` provider, or configured third-party providers such as DashScope. GitHub Copilot is optional: if no GitHub token is available, the server can still start in provider-only mode as long as at least one enabled provider is configured.\n\nThe gateway exposes OpenAI- and Anthropic-compatible APIs from one local endpoint, so tools like [Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview), OpenCode, Codex, and OpenAI-compatible clients can share the same local server.\n\nOn the GitHub Copilot path, the gateway prefers Copilot's native Anthropic-style Messages API when available, preserving more Claude-native behavior for tool-heavy workflows.\n\n## Features\n\n- **OpenAI and Anthropic compatibility**: Serve `/v1/responses`, `/v1/chat/completions`, `/v1/models`, `/v1/embeddings`, and `/v1/messages` from one local gateway.\n- **Copilot is optional**: Use GitHub Copilot when credentials are present, or run the server with only configured providers.\n- **One gateway for Copilot, `codex`, and external providers**: Route GitHub Copilot, the built-in `codex` provider, and configured third-party providers behind the same endpoint.\n- **Standalone third-party providers**: Configure providers such as DashScope, DeepSeek, OpenRouter, or a custom provider and start the gateway without a GitHub Copilot login.\n- **OpenAI-compatible providers on chat and Messages APIs**: `openai-compatible` providers can serve top-level `/v1/chat/completions` through `model: \"provider/model\"` and Anthropic-style `/v1/messages` through request/response translation.\n- **Agent-friendly Claude handling on Copilot**: Prefer native `/v1/messages` when available, preserve Claude-style tool flows, support Anthropic beta features, Claude WebSearch through Responses-capable models, and keep subagent/session markers intact.\n- **Claude Code and OpenCode integration**: Works with Claude Code and OpenCode, including direct Anthropic-compatible usage through `@ai-sdk/anthropic`.\n- **Flexible auth and deployment options**: Supports interactive login or direct tokens, individual/business/enterprise plans, GitHub Enterprise, opencode OAuth, and custom data directories.\n- **Multi-provider routing**: Expose provider-specific `/:provider/...` routes or use `model: \"provider/model\"` on the top-level API.\n\n## Prerequisites\n\n- Bun (>= 1.2.x)\n- Node.js if you plan to run the published CLI with `npx`\n- GitHub account with Copilot subscription only if you want to use the GitHub Copilot provider\n- An API key or OAuth login for at least one configured provider if you want to run without GitHub Copilot\n\n## Installation\n\nTo install dependencies, run:\n\n```sh\nbun install\n```\n\nTo start the server directly from source:\n\n```sh\nbun run start start\n```\n\n## Running from Source\n\nThe project can be run from source in several ways:\n\n### Development Mode\n\n```sh\nbun run dev start\n```\n\n### Production Mode\n\n```sh\nbun run start start\n```\n\n## Using with npx\n\nYou can run the project directly using npx:\n\n> [!IMPORTANT]\n> Token usage storage uses Node's built-in `node:sqlite` module when running with `npx`. It is enabled on Node.js >= 22.13.0. On Node.js < 22.13.0, the CLI still starts, but token usage storage is disabled.\n>\n> If you want token usage storage without upgrading Node.js, run the published CLI with Bun instead: `bunx --bun @jeffreycao/copilot-api@latest start`.\n\n```sh\nnpx @jeffreycao/copilot-api@latest start\n```\n\nWith options:\n\n```sh\nnpx @jeffreycao/copilot-api@latest start --port 8080\n```\n\nFor authentication or provider configuration only:\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth\n```\n\nTo run without GitHub Copilot, configure at least one provider first, then start the server normally:\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth login --provider dashscope\nnpx @jeffreycao/copilot-api@latest start\n```\n\n## Using with Docker\n\nBuild the image:\n\n```sh\ndocker build -t copilot-api .\n```\n\nRun the container with a bind mount so auth data survives restarts:\n\n```sh\nmkdir -p ./copilot-data\ndocker run -p 4141:4141 -v $(pwd)/copilot-data:/root/.local/share/copilot-api copilot-api\n```\n\nThis stores GitHub auth data, provider config, and other gateway state in `./copilot-data` on the host, mapped to `/root/.local/share/copilot-api` in the container.\n\nOr pass a GitHub token directly:\n\n```sh\ndocker run -p 4141:4141 -e GH_TOKEN=your_github_token_here copilot-api\n```\n\n## Electron Desktop App\n\nIf you prefer a GUI, this repository also includes an Electron desktop app in `desktop/`. It supports GitHub Copilot sign-in, OpenAI Codex OAuth, and API-key configuration for DeepSeek, DashScope, OpenRouter, or a custom provider. After authorization or provider configuration, it can start and stop the local proxy with one click and shows the local endpoint, auth header, available models, usage, and logs in the app.\n\nThe settings screen also exposes `OAuth App`, `API Home`, `Enterprise URL`, verbose logging, and minimize-to-tray. Windows x64 (`.exe`), macOS Apple Silicon (`.dmg`), and Linux x64 (`.AppImage`) packages are published in GitHub Releases:\n\nhttps://github.com/caozhiyuan/copilot-api/releases\n\nOn Linux, make the downloaded AppImage executable before launching it:\n\n```sh\nchmod +x Copilot-API-*-linux-x86_64.AppImage\n./Copilot-API-*-linux-x86_64.AppImage\n```\n\nDownload the installer for your platform, authorize or configure a provider inside the app, choose a port, start the server, then point your client at the local endpoint shown in the app. Packaged desktop builds use the bundled Electron runtime, so normal desktop usage does not require installing Node.js separately. Token usage history is enabled when that bundled runtime supports SQLite.\n\nThe desktop app's Advanced Config page reads and writes the shared model mappings through `GET/POST /admin/config/model-mappings`. The same mappings apply across `POST /v1/messages`, `POST /v1/messages/count_tokens`, `POST /v1/responses`, and `POST /v1/chat/completions` instead of being split per interface. It uses `auth.adminApiKey` instead of the regular `auth.apiKeys`, and the app reads that key directly from `config.json` after the server has generated it on startup.\n\n### Desktop App Screenshots\n\nMain dashboard, token usage breakdown in the bundled Electron app:\n\n<p align=\"center\">\n  <img src=\"./docs/screenshots/desktop-dashboard.png\" alt=\"Copilot API desktop app dashboard\" width=\"49%\" />\n  <img src=\"./docs/screenshots/desktop-token-usage.png\" alt=\"Copilot API desktop app token usage view\" width=\"49%\" />\n</p>\n\n## Using with Claude Code\n\nThis AI gateway can be used to power [Claude Code](https://docs.anthropic.com/en/claude-code), an experimental conversational AI assistant for developers from Anthropic.\n\nThere are two ways to configure Claude Code to use this AI gateway:\n\n### Interactive Setup with `--claude-code` flag\n\nTo get started, run the `start` command with the `--claude-code` flag:\n\n```sh\nnpx @jeffreycao/copilot-api@latest start --claude-code\n```\n\nYou will no longer be prompted to pick models manually. The gateway automatically detects the latest available model for each Claude Code size tier — opus maps to the newest Opus model, sonnet to the newest Sonnet model, and haiku to the newest Haiku model — and generates a command that sets `ANTHROPIC_DEFAULT_OPUS_MODEL`, `ANTHROPIC_DEFAULT_SONNET_MODEL`, and `ANTHROPIC_DEFAULT_HAIKU_MODEL` accordingly. Any tier without a matching model available is omitted. The command is copied to your clipboard and sets the environment variables needed for Claude Code to use the gateway.\n\nPaste and run this command in a new terminal to launch Claude Code.\n\n### Manual Configuration with `settings.json`\n\nAlternatively, you can configure Claude Code by creating a `.claude/settings.json` file in your project's root directory. This file should contain the environment variables needed by Claude Code. This way you don't need to run the interactive setup every time.\n\nHere is an example `.claude/settings.json` file:\n\n```json\n{\n  \"env\": {\n    \"ANTHROPIC_BASE_URL\": \"http://localhost:4141\",\n    \"ANTHROPIC_AUTH_TOKEN\": \"dummy\",\n    \"ANTHROPIC_MODEL\": \"gpt-5.6-sol[1m]\",\n    \"ANTHROPIC_DEFAULT_SONNET_MODEL\": \"gpt-5.6-sol[1m]\",\n    \"ANTHROPIC_DEFAULT_HAIKU_MODEL\": \"gpt-5.6-luna[1m]\",\n    \"CLAUDE_CODE_AUTO_COMPACT_WINDOW\": \"272000\",\n    \"CLAUDE_CODE_USE_VERTEX\": \"0\",\n    \"CLAUDE_CODE_USE_BEDROCK\": \"0\",\n    \"DISABLE_NON_ESSENTIAL_MODEL_CALLS\": \"1\",\n    \"CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC\": \"1\",\n    \"CLAUDE_CODE_ATTRIBUTION_HEADER\": \"0\",\n    \"CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION\": \"false\",\n    \"CLAUDE_CODE_DISABLE_TERMINAL_TITLE\": \"true\",\n    \"CLAUDE_CODE_ENABLE_AWAY_SUMMARY\": \"0\"\n  },\n  \"alwaysThinkingEnabled\": true,\n  \"effortLevel\": \"xhigh\",\n  \"showThinkingSummaries\": true\n}\n```\n\n- Replace `ANTHROPIC_MODEL`, `ANTHROPIC_DEFAULT_OPUS_MODEL`, `ANTHROPIC_DEFAULT_SONNET_MODEL`, and `ANTHROPIC_DEFAULT_HAIKU_MODEL` according to your needs. After configuration, please install the claude code plugin [Plugin Integrations](#plugin-integrations).  \n- If you are using the codex provider, it is recommended **not** to configure the model name in the `codex/xxx` format (e.g. `codex/gpt-5.6-sol`). Claude Code treats the `codex/` prefix as a special pattern and applies degraded behavior — for example, it strips all previously returned thinking blocks on every request. Use the plain model name (e.g. `gpt-5.6-sol`) instead, and add a `modelMappings` entry in `config.json` to route it back to the codex provider:\n  ```json\n  \"modelMappings\": {\n    \"gpt-5.6-sol\": \"codex/gpt-5.6-sol\",\n    \"gpt-5.6-terra\": \"codex/gpt-5.6-terra\",\n    \"gpt-5.6-luna\": \"codex/gpt-5.6-luna\"\n  },\n  ```\n- Setting CLAUDE_CODE_ATTRIBUTION_HEADER to 0 can prevent Claude code from adding billing and version information in system prompts, thereby avoiding prompt cache invalidation.\n- Turning off CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION and CLAUDE_CODE_ENABLE_AWAY_SUMMARY can prevent quota from being consumed unnecessarily.\n- Claude Code WebSearch is supported for pure search requests. For Copilot, keep the global `messageApiWebSearchModel` set to a Responses-capable GPT model or a `provider/model` alias. For provider routes, use a native Anthropic provider or an `openai-responses` provider. Add `WebSearch` to `permissions.deny` only if you want to forbid this traffic.\n- If using a non-Claude model, do not enable ENABLE_TOOL_SEARCH. If using the Claude model, can enable ENABLE_TOOL_SEARCH. The current Claude Code uses the client tool search mode. In this mode, loading defer tools requires an additional request each time.\n- `CLAUDE_CODE_AUTO_COMPACT_WINDOW`: Set the context capacity in tokens used for auto-compaction calculations. Defaults to the model's context window: 200K for standard models or 1M for extended context models. Use a lower value like `500000` on a 1M model (e.g., `claude-opus-4-6[1m]`) to treat the window as 500K for compaction purposes. The value is capped at the model's actual context window. `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` is applied as a percentage of this value. Setting this variable decouples the compaction threshold from the status line's `used_percentage`, which always uses the model's full context window.\n\nYou can find more options here: [Claude Code settings](https://docs.anthropic.com/en/docs/claude-code/settings#environment-variables)\n\nYou can also read more about IDE integration here: [Add Claude Code to your IDE](https://docs.anthropic.com/en/docs/claude-code/ide-integrations)\n\n## Using with OpenCode\n\nOpenCode already has a direct GitHub Copilot provider. Use this section when you want OpenCode to point at this AI gateway through `@ai-sdk/anthropic` and reuse the agent behaviors described earlier in this README.\n\n### Minimal setup\n\nStart the AI gateway with the OpenCode OAuth app:\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth --oauth-app=opencode\nnpx @jeffreycao/copilot-api@latest start\n```\n\nThen point OpenCode at the gateway with `@ai-sdk/anthropic`.\n\nExample `~/.config/opencode/opencode.json`:\n\n```json\n{\n  \"$schema\": \"https://opencode.ai/config.json\",\n  \"provider\": {\n    \"local\": {\n      \"npm\": \"@ai-sdk/anthropic\",\n      \"name\": \"My Local\",\n      \"options\": {\n        \"baseURL\": \"http://localhost:4141/v1\",\n        \"apiKey\": \"dummy\"\n      },\n      \"models\": {\n        \"gpt-5.4\": {\n          \"name\": \"gpt-5.4\",\n          \"modalities\": {\n            \"input\": [\"text\", \"image\"],\n            \"output\": [\"text\"]\n          },\n          \"limit\": {\n            \"context\": 400000,\n            \"input\": 272000,\n            \"output\": 128000\n          }\n        },\n        \"claude-sonnet-4.6\": {\n          \"id\": \"claude-sonnet-4.6\",\n          \"name\": \"claude-sonnet-4.6\",\n          \"modalities\": {\n            \"input\": [\"text\", \"image\"],\n            \"output\": [\"text\"]\n          },          \n          \"limit\": {\n            \"context\": 200000,\n            \"output\": 32000\n          },\n          \"options\": {\n            \"thinking\": {\n              \"type\": \"adaptive\"\n            },\n            \"effort\": \"max\"\n          }\n        }\n      }\n    }\n  }\n}\n```\n\nWhy these fields matter:\n\n- `npm: \"@ai-sdk/anthropic\"` is the important part. OpenCode will speak Anthropic Messages semantics to this AI gateway instead of flattening everything into OpenAI Chat Completions.\n- `options.baseURL` should be `http://localhost:4141/v1`; the Anthropic SDK will append `/messages`, `/models`, and `/messages/count_tokens` automatically.\n- If you enable `auth.apiKeys` in this AI gateway, replace `dummy` with a real key. Otherwise any placeholder value is fine.\n\n## Using with Codex\n\nThis AI gateway can also power Codex.\n\n### Codex `config.toml` Reference\n\nAdd the following `[model_providers.copilot_api]` section to your Codex `~/.codex/config.toml`:\n\n```toml\nmodel_provider = \"copilot_api\"\nmodel_reasoning_summary = \"auto\"\nmodel_context_window = 272000\nmodel_auto_compact_token_limit = 244800\n\n[model_providers.copilot_api]\nname = \"OpenAI\"\nbase_url = \"http://localhost:4141\"\nenv_key = \"GITHUB_COPILOT_API_KEY\"\nrequires_openai_auth = true\nsupports_websockets = false\nwire_api = \"responses\"\nrequest_max_retries = 3\nstream_max_retries = 1\nstream_idle_timeout_ms = 300000\n\n[features]\nremote_compaction_v2 = true\n\n[analytics]\nenabled = false\n```\n\n> [!NOTE]\n> This configuration is specific to Codex and the GitHub Copilot provider. `name` must be set to `\"OpenAI\"`. It can help mitigate Codex local compact cache miss issues.\n> If you are using the codex provider, it is recommended to set `base_url` to `\"http://localhost:4141/codex\"`.\n\n## GPT Tool Search\n\nFor GPT Responses models such as `gpt-5.4+`, this AI gateway can expose Responses `tool_search` through a small MCP bridge. The same bridge can be used by Claude Code and opencode, as long as the client loads MCP servers and sends Anthropic Messages traffic through this gateway.\n\nDo not set Claude Code's native `ENABLE_TOOL_SEARCH` for GPT models. That flag enables Claude Code's own client-side tool search mode, and it may stop forwarding deferred tool definitions. This gateway needs the full tool definitions so it can keep the small always-loaded tool set eager and translate every other tool into Responses deferred namespaces.\n\nIf you install `tool-search@copilot-api-marketplace`, Claude Code receives this MCP bridge automatically and you can skip the manual Claude Code MCP setup below.\n\nAdd the tool search bridge to the MCP config used by Claude Code:\n\n```json\n{\n  \"mcpServers\": {\n    \"tool_search\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@jeffreycao/copilot-api@latest\", \"mcp\"]\n    }\n  }\n}\n```\n\nAdd the tool search bridge to the MCP config used by opencode:\n\n```json\n{\n  \"mcp\": {\n    \"tool_search\": {\n      \"type\": \"local\",\n      \"command\": [\"npx\", \"-y\", \"@jeffreycao/copilot-api@latest\", \"mcp\"]\n    }\n  }\n}\n```\n\nFor local development, use `bun` as the command and `[\"run\", \"./src/main.ts\", \"mcp\"]` as the args.\n\nInternally, the gateway now configures OpenAI Responses `tool_search` in client-executed mode. Deferred tools are still exposed as searchable namespaces, but the model is explicitly asked to return the exact deferred tool names it wants to load next.\n\nThe bridge uses direct tool selection, not query search. Its tool input is `names`, a comma-separated list of exact deferred tool names, for example `TaskList,TaskGet,mcp__fetch__fetch`.\n\n## Plugin Integrations\n\nPlugin integrations are available for Claude Code and opencode.\n\n#### Claude Code plugin integration (marketplace-based)\n\nThe Claude Code integration is packaged as two plugins:\n\n- `agent-inject` injects `__SUBAGENT_MARKER__...` on `SubagentStart`, so the gateway can infer `x-initiator: agent`.\n- `tool-search` registers the `tool_search` MCP bridge used for GPT Responses deferred tool loading.\n\n- Marketplace catalog in this repository: `.claude-plugin/marketplace.json`\n- Plugin sources in this repository: `plugin/claude/agent-inject`, `plugin/claude/tool-search`\n\nAdd the marketplace remotely:\n\n```sh\n/plugin marketplace add https://github.com/caozhiyuan/copilot-api.git\n```\n\nInstall the plugins from the marketplace:\n\n```sh\n/plugin install agent-inject@copilot-api-marketplace\n/plugin install tool-search@copilot-api-marketplace\n```\n\nAfter installation, `agent-inject` injects `__SUBAGENT_MARKER__...` on `SubagentStart`, and the gateway uses it to infer `x-initiator: agent`.\n\nThe `agent-inject` plugin also registers a `UserPromptSubmit` hook that returns `{\"continue\": true}`, and it can inject `SessionStart` reminder rules through environment variables:\n\n- `CLAUDE_PLUGIN_ENABLE_QUESTION_RULES=1` enables the two reminders about using the `question` tool automatically for Claude Code. Alternatively, you can add the same reminders manually in `CLAUDE.md`; see [CLAUDE.md or AGENTS.md Recommended Content](#claudemd-or-agentsmd-recommended-content).\n- `CLAUDE_PLUGIN_ENABLE_NO_BACKGROUND_AGENTS_RULE=1` enables the `run_in_background: true` avoidance reminder for agent hooks.\n\nThe `tool-search` plugin bundles the same MCP bridge described in [GPT Tool Search](#gpt-tool-search), so Claude Code users do not need to add the `tool_search` server manually when they install that plugin.\n\n#### Opencode plugin\n\nThe subagent marker producer is packaged as an opencode plugin located at `plugin/opencode/subagent-marker.js`.\n\n**Installation:**\n\nCopy the plugin file to your opencode plugins directory:\n\n```sh\n# Clone or download this repository, then copy the plugin\ncp plugin/opencode/subagent-marker.js ~/.config/opencode/plugins/\n```\n\nOr manually create the file at `~/.config/opencode/plugins/subagent-marker.js` with the plugin content.\n\n**Features:**\n\n- Tracks sub-sessions created by subagents\n- Automatically prepends a marker system reminder (`__SUBAGENT_MARKER__...`) to subagent chat messages\n- Sets `x-session-id` header for session tracking\n- Enables the gateway to infer `x-initiator: agent` for subagent-originated requests\n\nThe plugin hooks into `session.created`, `session.deleted`, `chat.message`, and `chat.headers` events to provide seamless subagent marker functionality.\n\n## Using the Usage Viewer\n\nAfter starting the server, a URL to the Copilot Usage Dashboard will be displayed in your console. This dashboard is a web interface for monitoring your API usage.\n\n1.  Start the server. For example, using npx:\n    ```sh\n    npx @jeffreycao/copilot-api@latest start\n    ```\n2.  The server will output a URL to the usage viewer. Copy and paste this URL into your browser. It will look something like this:\n    `http://localhost:4141/usage-viewer?endpoint=http://localhost:4141/usage`\n    - If you use the `start.bat` script on Windows, this page will open automatically.\n\nThe dashboard provides a user-friendly interface to view your Copilot usage data:\n\n> Token usage history requires Bun or Node.js >= 22.13.0. On Node.js < 22.13.0, the server runs normally but token usage storage is disabled.\n\n- **API Endpoint URL**: The dashboard is pre-configured to fetch data from your local server endpoint via a URL query parameter. You can manually switch this to any other compatible API endpoint.\n- **x-api-key Authentication**: If API Key authentication is enabled, you can provide the `x-api-key` request header. The key is persisted in the browser's local storage.\n- **Period Selector**: Choose from Day, Week, or Month time ranges. The URL query parameter updates automatically when you switch, making it easy to bookmark and share.\n- **Fetch Data**: Click the \"Refresh\" button to load or refresh the usage data. The dashboard also fetches data automatically on page load.\n- **Copilot Quotas**: View quota usage for services such as Chat and Completions via progress bars. Hover over a card to see used/remaining details.\n- **Token Usage Metric Cards**: See a summary of Total, Input, Output, Cache Read, Cache Write, Requests, and estimated cost for the current period.\n- **Trend Chart (Week / Month)**: An interactive line chart with model and metric filters. Click a data point to inspect the usage breakdown for a specific day.\n- **Model Breakdown Table**: A per-model summary of requests, input/output/cache tokens, and estimated cost for the selected period.\n- **Request Events (Paginated)**: A time-sorted list of request event records with pagination support, showing timestamps, models, request IDs, and token counts.\n- **Detailed Information**: See the full JSON response from the API for a detailed breakdown of all available usage statistics.\n- **URL-based Configuration**: You can also specify the API endpoint and period directly via `endpoint` and `period` query parameters. For example:\n  `http://localhost:4141/usage-viewer?endpoint=http://your-api-server/usage&period=week`\n\n### Usage Viewer Screenshot\n\n<p align=\"center\">\n  <img src=\"./docs/screenshots/usage-viewer.png\" alt=\"Copilot API usage viewer\" width=\"900\" />\n</p>\n\n## Command Structure\n\nCopilot API now uses a subcommand structure with these main commands:\n\n- `start`: Start the gateway server. If a GitHub token is available, the server starts with Copilot enabled. If no GitHub token is available, it starts in provider-only mode when at least one enabled provider exists; otherwise it guides you through provider setup.\n- `auth`: Run provider login or configuration without starting the server. Use it for GitHub Copilot login, Codex OAuth, or third-party provider API key setup.\n- `debug`: Display diagnostic information including version, runtime details, file paths, and authentication status. Useful for troubleshooting and support.\n\n## Command Line Options\n\n### Global Options\n\nThe following options can be used with any subcommand. When passing them before the subcommand, use the `--key=value` form:\n\n| Option            | Description                                            | Default | Alias |\n| ----------------- | ------------------------------------------------------ | ------- | ----- |\n| --api-home        | Path to the API home directory (sets COPILOT_API_HOME) | none    | none  |\n| --oauth-app       | OAuth app identifier (sets COPILOT_API_OAUTH_APP)      | none    | none  |\n| --enterprise-url  | Enterprise URL for GitHub (sets COPILOT_API_ENTERPRISE_URL) | none | none |\n\n### Start Command Options\n\nThe following command line options are available for the `start` command:\n\n| Option         | Description                                                                   | Default    | Alias |\n| -------------- | ----------------------------------------------------------------------------- | ---------- | ----- |\n| --port         | Port to listen on                                                             | 4141       | -p    |\n| --verbose      | Enable verbose logging                                                        | false      | -v    |\n| --github-token | Provide GitHub token directly (must be generated using the `auth` subcommand) | none       | -g    |\n| --claude-code  | Generate a command to launch Claude Code with Copilot API config              | false      | -c    |\n| --show-token   | Show GitHub and Copilot tokens on fetch and refresh                           | false      | none  |\n| --proxy-env    | Initialize proxy from environment variables                                   | false      | none  |\n\n### Auth Command Options\n\n| Option       | Description               | Default | Alias |\n| ------------ | ------------------------- | ------- | ----- |\n| --provider   | Provider to log in with or configure (`copilot`, `codex`, `opencode-go`, `deepseek`, `dashscope`, `openrouter`, or `custom`) | prompt | none |\n| --verbose    | Enable verbose logging    | false   | -v    |\n| --show-token | Show GitHub token on auth | false   | none  |\n\nUse `copilot-api auth login --provider copilot` only when you want to enable the GitHub Copilot provider. Copilot is not required for `codex` or third-party provider-only usage.\n\nUse `copilot-api auth login --provider deepseek`, `--provider dashscope`, `--provider openrouter`, or `--provider opencode-go` to add or update those common third-party providers from the CLI. DeepSeek prompts for masked `apiKey`, provider `type` (default `anthropic`), and `baseUrl` defaulting to `https://api.deepseek.com/anthropic`. DashScope prompts for masked `apiKey`, provider `type` (default `openai-compatible`), and prefilled `baseUrl`. OpenRouter prompts for masked `apiKey` and prefilled `baseUrl` only, and writes `type: \"anthropic\"`. OpenCode Go prompts for masked `apiKey` and prefilled `baseUrl` only, and writes `type: \"openai-compatible\"` (baseUrl `https://opencode.ai/zen/go`). After a provider is configured and enabled, `copilot-api start` can run without any GitHub token.\n\nUse `copilot-api auth login --provider custom` to add or update another third-party provider from the CLI. The command prompts for the provider name, supported type (`anthropic`, `openai-compatible`, or `openai-responses`), `baseUrl`, masked `apiKey`, and `authType`; `authType` may be left as the type default or set to `x-api-key` / `authorization`.\n\n### Debug Command Options\n\n| Option | Description               | Default | Alias |\n| ------ | ------------------------- | ------- | ----- |\n| --json | Output debug info as JSON | false   | none  |\n\n## Configuration (config.json)\n\n- **Location:** `~/.local/share/copilot-api/config.json` (Linux/macOS) or `%USERPROFILE%\\.local\\share\\copilot-api\\config.json` (Windows).\n- **Default shape:**\n  ```json\n  {\n    \"auth\": {\n      \"apiKeys\": [],\n      \"adminApiKey\": \"<auto-generated-on-startup>\"\n    },\n    \"providers\": {},\n    \"modelMappings\": {},\n    \"extraPrompts\": {\n      \"gpt-5-mini\": \"<built-in exploration prompt>\"\n    },\n    \"smallModel\": \"gpt-5-mini\",\n    \"contextManagement\": {\n      \"messages\": true,\n      \"responses\": false\n    },\n    \"modelResponsesApiCompactThresholds\": {\n      \"gpt-5.4\": 217600,\n      \"gpt-5.5\": 217600,\n      \"gpt-5.6-sol\": 231200,\n      \"gpt-5.6-terra\": 231200,\n      \"gpt-5.6-luna\": 231200\n    },\n    \"modelReasoningEfforts\": {\n      \"gpt-5-mini\": \"low\"\n    },\n    \"useMessagesApi\": true,\n    \"useResponsesApiWebSocket\": true,\n    \"useResponsesApiWebSearch\": true,\n    \"messageApiWebSearchModel\": \"gpt-5-mini\"\n  }\n  ```\n- **auth.apiKeys:** API keys used for request authentication on non-admin routes. Supports multiple keys for rotation. Requests can authenticate with either `x-api-key: <key>` or `Authorization: Bearer <key>`. If empty or omitted, authentication for non-admin routes is disabled.\n- **auth.adminApiKey:** Single admin key used only for `/admin/*` routes. If missing, the server generates a random key at startup and writes it back to `config.json`. Requests use the same `x-api-key` or `Authorization: Bearer` headers, but regular `auth.apiKeys` never grant access to `/admin/*`.\n- **modelMappings:** Exact `sourceModel -> targetModel` rewrites shared by top-level `POST /v1/messages`, `POST /v1/messages/count_tokens`, `POST /v1/responses`, and `POST /v1/chat/completions` requests. Omit it or leave it as `{}` to disable rewrites. Both the source and target must be non-empty strings. Targets can be regular model IDs or `provider/model` aliases such as `dashscope/qwen3.6-plus`, and the rewrite happens before provider alias parsing. These mappings are not split per interface. The admin endpoints `GET/POST /admin/config/model-mappings` read and update only this field.\n- **extraPrompts:** Map of `model -> prompt` appended to the first system prompt when translating Anthropic-style requests to Responses API. Use this to inject guardrails or guidance per model. Missing default entries are auto-added without overwriting your custom prompts. For GPT-5.3+ models (e.g. `gpt-5.3-codex`, `gpt-5.4`, `gpt-5.5`), a built-in commentary prompt is used as fallback when not explicitly configured. The built-in prompts enable phase-aware commentary, which lets the model emit a short user-facing progress update before tools or deeper reasoning.\n- **providers:** Global upstream provider map. Each provider key (for example `dashscope`) becomes a route prefix (`/dashscope/v1/messages`). Supports `type: \"anthropic\"`, `type: \"openai-compatible\"`, and `type: \"openai-responses\"`. Top-level clients can also use `model: \"dashscope/model-id\"` with `/v1/messages`, `/v1/messages/count_tokens`, `/v1/responses`, and `/v1/chat/completions`; the gateway strips the `dashscope/` prefix before forwarding upstream. `openai-compatible` providers support both chat and Messages flows: `/v1/chat/completions` is proxied to upstream `/v1/chat/completions`, while `/v1/messages` and `/:provider/v1/messages` are translated to upstream chat completions and translated back to Anthropic Messages responses. `GET /v1/models` aggregates enabled provider models with `provider/model-id` IDs; use `GET /dashscope/v1/models` for a single provider's raw model list.\n  - `enabled` defaults to `true` if omitted.\n  - `baseUrl` should be provider API base URL without the final endpoint. For Anthropic providers, omit `/v1/messages`; for OpenAI-compatible providers, omit `/v1/chat/completions`; for OpenAI Responses providers, omit `/v1/responses`.\n  - `apiKey` is used as the upstream credential value and is required for regular providers.\n  - `authType` (optional): Controls how `apiKey` is sent upstream. Supports `x-api-key` and `authorization` for regular providers. Anthropic providers default to `x-api-key`; OpenAI-compatible and OpenAI Responses providers default to `authorization`. When set to `authorization`, the proxy sends `Authorization: Bearer <apiKey>`. `oauth2` is reserved for the built-in `codex` provider and is written automatically by `auth login --provider codex`.\n  - `pricingCurrency` (optional): Provider-level currency used for token cost calculation, for example `USD` or `CNY`. Quick providers default to `CNY` for DashScope and DeepSeek, and `USD` for Codex/OpenRouter. Costs are grouped by currency and are not exchange-rate converted.\n  - `models` (optional): Per-model configuration map. Each key is a model ID (matching the model name in requests), and the value is:\n    - `temperature` (optional): Default temperature value used when the request does not specify one.\n    - `topP` (optional): Default top_p value used when the request does not specify one.\n    - `topK` (optional): Default top_k value used when the request does not specify one.\n    - `extraBody` (optional): Dynamic fields merged into the upstream request body for that model. Request body fields with the same name take precedence. OpenAI-compatible providers can use this for fields such as `enable_thinking`, `preserve_thinking`, `reasoning_effort`. `thinking_budget` is a special OpenAI-compatible provider override: when configured in `extraBody`, it is forced after Anthropic `thinking.budget_tokens` translation and overrides the request-derived budget. For providers whose name is `dashscope` or whose `baseUrl` contains `aliyuncs.com`, the request-derived `thinking_budget` (from Anthropic `thinking.budget_tokens`) is forwarded upstream; for other OpenAI-compatible providers the request-derived `thinking_budget` is stripped, while an `extraBody` `thinking_budget` is still honored. For DashScope providers, `preserve_thinking` defaults to `true` when not explicitly set in `extraBody` or the request body.\n    - `pricing` (optional): Per-model token prices, in the provider `pricingCurrency`, per 1M tokens. Supported fields are `input`, `output`, `cachedInput` (implicit cache read), `explicitCachedInput` (explicit cache read), and `cacheCreationInput`. Use `tiers` with `maxInputTokens` for input-size tiered pricing.\n    - `contextCache` (optional): Defaults to `true` for providers whose name is `dashscope` or whose `baseUrl` contains `aliyuncs.com`; defaults to `false` for other OpenAI-compatible providers. This enables Alibaba Cloud Model Studio/DashScope explicit context cache by injecting `cache_control: { \"type\": \"ephemeral\" }` on up to 4 content blocks using the Context Cache format. The cache breakpoint strategy matches opencode's main provider flow: the first 2 system messages plus the last 2 non-system messages. Marked string content is converted to text content part arrays for `system` / `user` / `assistant` / `tool` messages; existing array content is marked on the last part. Set this to `false` when the model already supports implicit caching, or when the upstream does not accept this explicit-cache extension field. Set this to `true` for non-DashScope providers that support the same explicit-cache extension. Applied on both `/v1/messages` and `/v1/chat/completions` routes.\n    - `supportPdf` (optional): Controls whether the model supports PDF/document content. Defaults to `false`; unsupported PDFs are converted to a text notice. Set it to `true` to send PDF/document blocks as OpenAI Chat Completions file parts.\n    - `toolContentSupportType` (optional): Tool result content capabilities for that model, as an array of `array`, `image`, and `pdf`. Provider routes default to string-only tool content when omitted. If `supportPdf` is `true` but this list does not include `pdf`, file parts in tool results are moved to user role messages. This provider default does not change the Copilot main flow, which continues to support array + image and not PDF.\n    - `type` (optional): Per-model override of the provider protocol type. Supports `anthropic`, `openai-compatible`, and `openai-responses`. When set, the provider's `/v1/messages` route uses this model's type instead of the provider-level type for request routing, auth header resolution, and upstream endpoint selection. This is useful for providers like OpenCode Go whose upstream supports both OpenAI-compatible and Anthropic Messages APIs for different models. When the type is overridden, the auth header is resolved from the overridden type's default (Anthropic defaults to `x-api-key`; OpenAI-compatible/Responses default to `authorization`).\n\n  Example DashScope model settings:\n  ```json\n  {\n    \"providers\": {\n      \"dashscope\": {\n        \"type\": \"openai-compatible\",\n        \"enabled\": true,\n        \"baseUrl\": \"https://dashscope.aliyuncs.com/compatible-mode\",\n        \"apiKey\": \"sk-your-dashscope-key\",\n        \"pricingCurrency\": \"CNY\",\n        \"models\": {\n          \"qwen3.7-plus\": {\n            \"temperature\": 1,\n            \"topP\": 0.95,\n            \"topK\": 20,\n            \"extraBody\": {\n              \"preserve_thinking\": true\n            }\n          },\n          \"glm-5.1\": {\n            \"temperature\": 0.7,\n            \"topP\": 0.95,\n            \"contextCache\": true,\n            \"pricing\": {\n              \"tiers\": [\n                {\n                  \"maxInputTokens\": 32000,\n                  \"input\": 6,\n                  \"cachedInput\": 1.2,\n                  \"explicitCachedInput\": 0.6,\n                  \"cacheCreationInput\": 7.5,\n                  \"output\": 24\n                },\n                {\n                  \"maxInputTokens\": 200000,\n                  \"input\": 8,\n                  \"cachedInput\": 1.6,\n                  \"explicitCachedInput\": 0.8,\n                  \"cacheCreationInput\": 10,\n                  \"output\": 28\n                }\n              ]\n            },\n            \"extraBody\": {\n              \"preserve_thinking\": true\n            }\n          }\n        }\n      }\n    }\n  }\n  ```\n  Built-in token prices cover Codex GPT models in USD, DashScope `qwen3.7-max`, `qwen3.7-plus`, `glm-5.1`, `glm-5.2` in CNY, DeepSeek `deepseek-v4-flash`, `deepseek-v4-pro`, `deepseek-chat`, `deepseek-reasoner` in CNY, and OpenCode Go models (`glm-5.2`, `grok-4.5`, `deepseek-v4-flash`, `deepseek-v4-pro`, `kimi-k2.7-code`, `kimi-k3`, `mimo-v2.5`, `mimo-v2.5-pro`, `qwen3.7-plus`, `qwen3.7-max`, `minimax-m2.7`, `minimax-m3`) in USD. User `pricing` entries override built-ins. For DashScope, cached tokens are charged as explicit cache reads when the upstream usage includes `cache_creation_input_tokens`; otherwise `cachedInput` is used as the implicit cache read price. For DeepSeek, `prompt_cache_hit_tokens` map to cached input and `prompt_cache_miss_tokens` map to regular input.\n- **smallModel:** Fallback model used for tool-less warmup messages (e.g., Claude Code probe requests); defaults to gpt-5-mini. The gateway forces this small model on no-tool warmup or probe requests to avoid consuming premium requests. This behavior only applies to non-token-based-billing GitHub Copilot accounts (`token_based_billing` is false); for token-based-billing accounts the warmup small-model fallback is skipped since there is no premium-request quota to preserve.\n- **contextManagement:** Controls whether the proxy adds Responses API `context_management` compaction instructions. `messages` applies when Anthropic-style `/v1/messages` requests are translated to Responses API, including `openai-responses` provider message routes, and defaults to `true`. `responses` applies to native `/v1/responses` traffic, including `provider/model` aliases and the built-in `codex` provider, and defaults to `false`. Enable `responses` only after checking that your client supports context management compaction. When enabled, the request includes `context_management` in the body and keeps only the latest compaction carrier on follow-up turns. **Note:** Context management is forcibly disabled for GPT-5.6 and above models (e.g. `gpt-5.6-sol`, `gpt-5.6-terra`, `gpt-5.6-luna`) because enabling it breaks prompt cache hits on those models. This override takes precedence over the `contextManagement` and `modelResponsesApiCompactThresholds` settings.\n- **modelResponsesApiCompactThresholds:** Per-model Responses API `compact_threshold` overrides used when the proxy adds `context_management`. These values take precedence over the fallback threshold from `resolveResponsesCompactThreshold` (`max_prompt_tokens * ratio`, or the default fallback). Defaults set `gpt-5.4` and `gpt-5.5` to `217600` (`272000 * 0.8`), and `gpt-5.6-sol`, `gpt-5.6-terra`, `gpt-5.6-luna` to `231200` (`272000 * 0.85`). Models not listed continue to use the normal fallback logic.\n- **modelReasoningEfforts:** Per-model fallback reasoning effort for `/v1/messages` requests. It is used only when the request does not provide `output_config.effort`.\n  - **Priority:** request `output_config.effort` > `modelReasoningEfforts[model]` > built-in default (`xhigh` for GPT-5.3+ models, otherwise `high`).\n  - **Forwarding:** the resolved value remains `output_config.effort` for the Copilot native Messages API and becomes `reasoning.effort` when translated to the Responses API.\n  - **Configuration values:** `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`.\n- **useMessagesApi:** When `true`, Claude-family models that support Copilot's native `/v1/messages` endpoint will use the Messages API; otherwise they fall back to `/chat/completions`. Set to `false` to disable Messages API routing and always use `/chat/completions`. Defaults to `true`.\n- **useResponsesApiWebSocket:** When `true`, Responses API requests use Copilot's websocket transport for models that advertise `ws:/responses`; models that only advertise `/responses` continue to use HTTP. Set to `false` to disable websocket routing and use HTTP `/responses` whenever the selected model supports it. Defaults to `true`. If the Responses API WebSocket gets closed, it is usually caused by your own network. If you are using a VPN, try switching to a different node.\n- **useResponsesApiWebSearch:** When `true`, the server keeps Responses API tools with `type: \"web_search\"` and forwards them upstream. Set to `false` to strip those tools from `/responses` payloads. Defaults to `true`.\n- **messageApiWebSearchModel:** Global fallback model used when a top-level Copilot `/v1/messages` request contains only the server-side `web_search` tool. Defaults to `gpt-5-mini`. If the value is a `provider/model` alias, the request is routed into that provider's Messages API path with the provider prefix stripped. For Copilot GPT models, web search runs through `/responses`. Mixed `web_search` plus custom tools are not supported and the server-side `web_search` tool is stripped.\n- **claudeTokenMultiplier:** Multiplier applied to the fallback GPT-tokenizer estimate for Claude `/v1/messages/count_tokens` requests. Defaults to `1.15`. Increase it if your client is still compacting too late. This setting is only used when the proxy is estimating Claude tokens locally; if `anthropicApiKey` is configured and Anthropic token counting succeeds, the exact Anthropic count is returned instead.\n- **anthropicApiKey:** Anthropic API key used to forward Claude `/v1/messages/count_tokens` requests to Anthropic's real token counting endpoint, which returns exact counts instead of GPT tokenizer estimates. Can also be set via the `ANTHROPIC_API_KEY` environment variable. If not set, or if the upstream call fails, token counting falls back to local GPT tokenizer estimation controlled by `claudeTokenMultiplier`.\n\nEdit this file to customize prompts or swap in your own fast model. Restart the server (or rerun the command) after changes so the cached config is refreshed.\n\n## API Authentication\n\n- **Protected non-admin routes:** All routes except `/`, `/usage-viewer`, and `/usage-viewer/` require authentication when `auth.apiKeys` is configured and non-empty.\n- **Admin routes:** All `/admin/*` routes require `auth.adminApiKey`. If it is missing, the server generates one at startup and persists it to `config.json` before serving requests.\n- **Allowed auth headers:**\n  - `x-api-key: <your_key>`\n  - `Authorization: Bearer <your_key>`\n- **CORS preflight:** `OPTIONS` requests are always allowed.\n- **When no regular keys are configured:** Non-admin routes continue to allow requests. This does not apply to `/admin/*`, which only accepts `auth.adminApiKey`.\n\nExample request for a regular protected route:\n\n```sh\ncurl http://localhost:4141/v1/models \\\n  -H \"x-api-key: your_api_key\"\n```\n\nExample request for an admin route:\n\n```sh\ncurl http://localhost:4141/admin/config/model-mappings \\\n  -H \"x-api-key: your_admin_api_key\"\n```\n\n## API Endpoints\n\nThe server exposes several OpenAI- and Anthropic-compatible endpoints. Requests can target GitHub Copilot, the built-in `codex` provider, or configured providers depending on the selected model and `provider/model` alias.\n\n### OpenAI Compatible Endpoints\n\nThese endpoints mimic the OpenAI API structure.\n\n| Endpoint                    | Method | Description                                                      |\n| --------------------------- | ------ | ---------------------------------------------------------------- |\n| `POST /v1/responses`        | `POST` | OpenAI Most advanced interface for generating model responses. Supports `provider/model` aliases for `openai-responses` providers. |\n| `POST /v1/chat/completions` | `POST` | Creates a model response for the given chat conversation. Supports `provider/model` aliases for `openai-compatible` providers and can be used without Copilot when the target provider is configured. |\n| `GET /v1/models`            | `GET`  | Lists Copilot models plus enabled provider models using `provider/model-id` IDs. Requests from Codex clients (`User-Agent` beginning with `codex`) are forwarded to the Codex Models upstream. |\n| `POST /v1/embeddings`       | `POST` | Creates an embedding vector representing the input text.         |\n\n### Codex Backend Proxy Endpoints\n\nThese endpoints require an active Codex login. Each endpoint is available both without a version prefix and under `/v1`.\n\n| Endpoint | Method | Description |\n| --- | --- | --- |\n| `POST /alpha/search`<br>`POST /v1/alpha/search` | `POST` | Transparently forwards the JSON body and query parameters to the Codex Alpha Search upstream. |\n| `POST /images/generations`<br>`POST /v1/images/generations` | `POST` | Forwards a JSON image generation request to the Codex Images upstream. When the request omits `Content-Type`, the gateway defaults it to `application/json`. |\n| `POST /images/edits`<br>`POST /v1/images/edits` | `POST` | Forwards an image edit request to the Codex Images upstream. Send this request as `multipart/form-data` and let the HTTP client generate the `boundary`; the gateway preserves the incoming content type and streams the upload body. |\n\nFor every endpoint above, the gateway replaces client authorization and account headers with the active Codex login, preserves query parameters and compatible request headers, and returns the upstream status, headers, and body.\n\n### Anthropic Compatible Endpoints\n\nThese endpoints are designed to be compatible with the Anthropic Messages API. Provider-scoped models, Responses, alpha-search, and images routes accept both unversioned and `/v1` paths; Messages routes remain under `/v1`.\n\n| Endpoint                         | Method | Description                                                  |\n| -------------------------------- | ------ | ------------------------------------------------------------ |\n| `POST /v1/messages`              | `POST` | Creates a model response for a given conversation. Supports `provider/model` aliases for configured providers, including translation through `openai-compatible` providers. |\n| `POST /v1/messages/count_tokens` | `POST` | Calculates the number of tokens for a given set of messages. Supports `provider/model` aliases for configured providers. |\n| `POST /:provider/v1/messages`       | `POST` | Proxies Anthropic Messages requests to the configured Anthropic provider, translates them through an OpenAI-compatible provider, or translates them through an OpenAI Responses provider. |\n| `GET /:provider/models`<br>`GET /:provider/v1/models` | `GET` | Proxies model listing requests to the configured provider. For `codex`, returns the built-in catalog by default; Codex clients (`User-Agent` starting with `codex`) are forwarded to the Codex Models upstream. |\n| `POST /:provider/v1/messages/count_tokens` | `POST` | Calculates tokens locally for provider route requests. |\n| `POST /:provider/responses`<br>`POST /:provider/v1/responses` | `POST` | Proxies OpenAI Responses requests to a configured `openai-responses` provider (including `codex`). |\n| `POST /:provider/alpha/search`<br>`POST /:provider/v1/alpha/search` | `POST` | Proxies alpha-search requests. For `codex`, forwards to the Codex Alpha Search upstream; for other providers, forwards to `{baseUrl}/v1/alpha/search`. |\n| `POST /:provider/images/generations`<br>`POST /:provider/v1/images/generations` | `POST` | Proxies image generation. For `codex`, uses the Codex Images upstream; for other providers, forwards to `{baseUrl}/v1/images/generations` (15-minute timeout). |\n| `POST /:provider/images/edits`<br>`POST /:provider/v1/images/edits` | `POST` | Proxies image edits. For `codex`, uses the Codex Images upstream; for other providers, forwards multipart/streamed bodies to `{baseUrl}/v1/images/edits` (15-minute timeout). |\n\n### Usage Monitoring Endpoints\n\nNew endpoints for monitoring your Copilot usage and quotas.\n\n| Endpoint     | Method | Description                                                  |\n| ------------ | ------ | ------------------------------------------------------------ |\n| `GET /usage` | `GET`  | Get detailed Copilot usage statistics and quota information. |\n| `GET /token` | `GET`  | Get the current Copilot token being used by the API.         |\n\n### Admin / Configuration Endpoints\n\nThese endpoints are reserved for local administrative actions and only accept `auth.adminApiKey`.\n\n| Endpoint                              | Method | Description                                                                 |\n| ------------------------------------- | ------ | --------------------------------------------------------------------------- |\n| `GET /admin/config/model-mappings`    | `GET`  | Returns the current `config.json` path and the active `modelMappings` map.  |\n| `POST /admin/config/model-mappings`   | `POST` | Updates only the `modelMappings` field in `config.json` and returns it back. |\n\n## Example Usage\n\nCommon `npx` commands:\n\n```sh\n# Start the gateway\nnpx @jeffreycao/copilot-api@latest start\n\n# Start on a custom port with verbose logging\nnpx @jeffreycao/copilot-api@latest start --port 8080 --verbose\n\n# Run the auth flow\nnpx @jeffreycao/copilot-api@latest auth login\n\n# Configure a third-party provider, then run without GitHub Copilot\nnpx @jeffreycao/copilot-api@latest auth login --provider dashscope\nnpx @jeffreycao/copilot-api@latest start\n\n# Print debug information as JSON\nnpx @jeffreycao/copilot-api@latest debug --json\n\n# Run the published CLI with Bun instead of Node.js\nbunx --bun @jeffreycao/copilot-api@latest start\n```\n\nOpenAI-compatible provider examples after configuring `dashscope`:\n\n```sh\ncurl http://localhost:4141/v1/chat/completions \\\n  -H \"content-type: application/json\" \\\n  -d '{\"model\":\"dashscope/qwen3.6-plus\",\"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]}'\n\ncurl http://localhost:4141/dashscope/v1/messages \\\n  -H \"content-type: application/json\" \\\n  -d '{\"model\":\"qwen3.6-plus\",\"max_tokens\":1024,\"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]}'\n```\n\n## Usage Tips\n\n### CLAUDE.md or AGENTS.md Recommended Content\n\nTo add these reminders manually, include the following in `CLAUDE.md` for Claude Code, or `AGENTS.md` for opencode/codex:\n\n```\n- Prohibited from directly asking questions to users, MUST use question tool.\n- Once you can confirm that the task is complete, MUST use question tool to make user confirm. The user may respond with feedback if they are not satisfied with the result, which you can use to make improvements and try again, after try again, MUST use question tool to make user confirm again.\n```\n"}, "65d5c76f68a6bdbe663df12cf6117ba479fbf509": {"t": 1785765535.6355062, "n": 51088, "h": "d634da9f61d113c6", "c": "# Copilot API Proxy\n\nEnglish | [简体中文](./README.zh-CN.md)\n\n## Important Notes\n\n> [!IMPORTANT]\n> **Before using, please be aware of the following:**\n>\n> 1. **Claude Code configuration:** When using with Claude Code, please configure the model ID as `claude-opus-4-8`. Example claude `settings.json` see [Manual Configuration with `settings.json`](#manual-configuration-with-settingsjson). \n>\n> 2. **Built-in `copilot`, `codex` and third-party providers:** Run `npx @jeffreycao/copilot-api@latest auth` and choose `copilot`, `codex`, `deepseek`, `custom`, or other providers.\n>\n> 3. **Note:** See [GitHub Copilot Security Notice](./NOTICE.md#github-copilot-security-notice) for the warning removed from the README header.\n\n---\n\n## Project Overview\n\nA small AI gateway that can use GitHub Copilot, the built-in `codex` provider, or configured third-party providers such as DashScope. GitHub Copilot is optional: if no GitHub token is available, the server can still start in provider-only mode as long as at least one enabled provider is configured.\n\nThe gateway exposes OpenAI- and Anthropic-compatible APIs from one local endpoint, so tools like [Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview), OpenCode, Codex, and OpenAI-compatible clients can share the same local server.\n\nOn the GitHub Copilot path, the gateway prefers Copilot's native Anthropic-style Messages API when available, preserving more Claude-native behavior for tool-heavy workflows.\n\n## Features\n\n- **OpenAI and Anthropic compatibility**: Serve `/v1/responses`, `/v1/chat/completions`, `/v1/models`, `/v1/embeddings`, and `/v1/messages` from one local gateway.\n- **Copilot is optional**: Use GitHub Copilot when credentials are present, or run the server with only configured providers.\n- **One gateway for Copilot, `codex`, and external providers**: Route GitHub Copilot, the built-in `codex` provider, and configured third-party providers behind the same endpoint.\n- **Standalone third-party providers**: Configure providers such as DashScope, DeepSeek, OpenRouter, or a custom provider and start the gateway without a GitHub Copilot login.\n- **OpenAI-compatible providers on chat and Messages APIs**: `openai-compatible` providers can serve top-level `/v1/chat/completions` through `model: \"provider/model\"` and Anthropic-style `/v1/messages` through request/response translation.\n- **Agent-friendly Claude handling on Copilot**: Prefer native `/v1/messages` when available, preserve Claude-style tool flows, support Anthropic beta features, Claude WebSearch through Responses-capable models, and keep subagent/session markers intact.\n- **Claude Code and OpenCode integration**: Works with Claude Code and OpenCode, including direct Anthropic-compatible usage through `@ai-sdk/anthropic`.\n- **Flexible auth and deployment options**: Supports interactive login or direct tokens, individual/business/enterprise plans, GitHub Enterprise, opencode OAuth, and custom data directories.\n- **Multi-provider routing**: Expose provider-specific `/:provider/...` routes or use `model: \"provider/model\"` on the top-level API.\n\n## Prerequisites\n\n- Bun (>= 1.2.x)\n- Node.js if you plan to run the published CLI with `npx`\n- GitHub account with Copilot subscription only if you want to use the GitHub Copilot provider\n- An API key or OAuth login for at least one configured provider if you want to run without GitHub Copilot\n\n## Installation\n\nTo install dependencies, run:\n\n```sh\nbun install\n```\n\nTo start the server directly from source:\n\n```sh\nbun run start start\n```\n\n## Running from Source\n\nThe project can be run from source in several ways:\n\n### Development Mode\n\n```sh\nbun run dev start\n```\n\n### Production Mode\n\n```sh\nbun run start start\n```\n\n## Using with npx\n\nYou can run the project directly using npx:\n\n> [!IMPORTANT]\n> Token usage storage uses Node's built-in `node:sqlite` module when running with `npx`. It is enabled on Node.js >= 22.13.0. On Node.js < 22.13.0, the CLI still starts, but token usage storage is disabled.\n>\n> If you want token usage storage without upgrading Node.js, run the published CLI with Bun instead: `bunx --bun @jeffreycao/copilot-api@latest start`.\n\n```sh\nnpx @jeffreycao/copilot-api@latest start\n```\n\nWith options:\n\n```sh\nnpx @jeffreycao/copilot-api@latest start --port 8080\n```\n\nFor authentication or provider configuration only:\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth\n```\n\nTo run without GitHub Copilot, configure at least one provider first, then start the server normally:\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth login --provider dashscope\nnpx @jeffreycao/copilot-api@latest start\n```\n\n## Using with Docker\n\nBuild the image:\n\n```sh\ndocker build -t copilot-api .\n```\n\nRun the container with a bind mount so auth data survives restarts:\n\n```sh\nmkdir -p ./copilot-data\ndocker run -p 4141:4141 -v $(pwd)/copilot-data:/root/.local/share/copilot-api copilot-api\n```\n\nThis stores GitHub auth data, provider config, and other gateway state in `./copilot-data` on the host, mapped to `/root/.local/share/copilot-api` in the container.\n\nOr pass a GitHub token directly:\n\n```sh\ndocker run -p 4141:4141 -e GH_TOKEN=your_github_token_here copilot-api\n```\n\n## Electron Desktop App\n\nIf you prefer a GUI, this repository also includes an Electron desktop app in `desktop/`. It supports GitHub Copilot sign-in, OpenAI Codex OAuth, and API-key configuration for DeepSeek, DashScope, OpenRouter, or a custom provider. After authorization or provider configuration, it can start and stop the local proxy with one click and shows the local endpoint, auth header, available models, usage, and logs in the app.\n\nThe settings screen also exposes `OAuth App`, `API Home`, `Enterprise URL`, verbose logging, and minimize-to-tray. Windows x64 (`.exe`), macOS Apple Silicon (`.dmg`), and Linux x64 (`.AppImage`) packages are published in GitHub Releases:\n\nhttps://github.com/caozhiyuan/copilot-api/releases\n\nOn Linux, make the downloaded AppImage executable before launching it:\n\n```sh\nchmod +x Copilot-API-*-linux-x86_64.AppImage\n./Copilot-API-*-linux-x86_64.AppImage\n```\n\nDownload the installer for your platform, authorize or configure a provider inside the app, choose a port, start the server, then point your client at the local endpoint shown in the app. Packaged desktop builds use the bundled Electron runtime, so normal desktop usage does not require installing Node.js separately. Token usage history is enabled when that bundled runtime supports SQLite.\n\nThe desktop app's Advanced Config page reads and writes the shared model mappings through `GET/POST /admin/config/model-mappings`. The same mappings apply across `POST /v1/messages`, `POST /v1/messages/count_tokens`, `POST /v1/responses`, and `POST /v1/chat/completions` instead of being split per interface. It uses `auth.adminApiKey` instead of the regular `auth.apiKeys`, and the app reads that key directly from `config.json` after the server has generated it on startup.\n\n### Desktop App Screenshots\n\nMain dashboard, token usage breakdown in the bundled Electron app:\n\n<p align=\"center\">\n  <img src=\"./docs/screenshots/desktop-dashboard.png\" alt=\"Copilot API desktop app dashboard\" width=\"49%\" />\n  <img src=\"./docs/screenshots/desktop-token-usage.png\" alt=\"Copilot API desktop app token usage view\" width=\"49%\" />\n</p>\n\n## Using with Claude Code\n\nThis AI gateway can be used to power [Claude Code](https://docs.anthropic.com/en/claude-code), an experimental conversational AI assistant for developers from Anthropic.\n\nThere are two ways to configure Claude Code to use this AI gateway:\n\n### Interactive Setup with `--claude-code` flag\n\nTo get started, run the `start` command with the `--claude-code` flag:\n\n```sh\nnpx @jeffreycao/copilot-api@latest start --claude-code\n```\n\nYou will no longer be prompted to pick models manually. The gateway automatically detects the latest available model for each Claude Code size tier — opus maps to the newest Opus model, sonnet to the newest Sonnet model, and haiku to the newest Haiku model — and generates a command that sets `ANTHROPIC_DEFAULT_OPUS_MODEL`, `ANTHROPIC_DEFAULT_SONNET_MODEL`, and `ANTHROPIC_DEFAULT_HAIKU_MODEL` accordingly. Any tier without a matching model available is omitted. The command is copied to your clipboard and sets the environment variables needed for Claude Code to use the gateway.\n\nPaste and run this command in a new terminal to launch Claude Code.\n\n### Manual Configuration with `settings.json`\n\nAlternatively, you can configure Claude Code by creating a `.claude/settings.json` file in your project's root directory. This file should contain the environment variables needed by Claude Code. This way you don't need to run the interactive setup every time.\n\nHere is an example `.claude/settings.json` file:\n\n```json\n{\n  \"env\": {\n    \"ANTHROPIC_BASE_URL\": \"http://localhost:4141\",\n    \"ANTHROPIC_AUTH_TOKEN\": \"dummy\",\n    \"ANTHROPIC_MODEL\": \"gpt-5.6-sol[1m]\",\n    \"ANTHROPIC_DEFAULT_SONNET_MODEL\": \"gpt-5.6-sol[1m]\",\n    \"ANTHROPIC_DEFAULT_HAIKU_MODEL\": \"gpt-5.6-luna[1m]\",\n    \"CLAUDE_CODE_AUTO_COMPACT_WINDOW\": \"272000\",\n    \"CLAUDE_CODE_USE_VERTEX\": \"0\",\n    \"CLAUDE_CODE_USE_BEDROCK\": \"0\",\n    \"DISABLE_NON_ESSENTIAL_MODEL_CALLS\": \"1\",\n    \"CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC\": \"1\",\n    \"CLAUDE_CODE_ATTRIBUTION_HEADER\": \"0\",\n    \"CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION\": \"false\",\n    \"CLAUDE_CODE_DISABLE_TERMINAL_TITLE\": \"true\",\n    \"CLAUDE_CODE_ENABLE_AWAY_SUMMARY\": \"0\"\n  },\n  \"alwaysThinkingEnabled\": true,\n  \"effortLevel\": \"xhigh\",\n  \"showThinkingSummaries\": true\n}\n```\n\n- Replace `ANTHROPIC_MODEL`, `ANTHROPIC_DEFAULT_OPUS_MODEL`, `ANTHROPIC_DEFAULT_SONNET_MODEL`, and `ANTHROPIC_DEFAULT_HAIKU_MODEL` according to your needs. After configuration, please install the claude code plugin [Plugin Integrations](#plugin-integrations).  \n- If you are using the codex provider, it is recommended **not** to configure the model name in the `codex/xxx` format (e.g. `codex/gpt-5.6-sol`). Claude Code treats the `codex/` prefix as a special pattern and applies degraded behavior — for example, it strips all previously returned thinking blocks on every request. Use the plain model name (e.g. `gpt-5.6-sol`) instead, and add a `modelMappings` entry in `config.json` to route it back to the codex provider:\n  ```json\n  \"modelMappings\": {\n    \"gpt-5.6-sol\": \"codex/gpt-5.6-sol\",\n    \"gpt-5.6-terra\": \"codex/gpt-5.6-terra\",\n    \"gpt-5.6-luna\": \"codex/gpt-5.6-luna\"\n  },\n  ```\n- Setting CLAUDE_CODE_ATTRIBUTION_HEADER to 0 can prevent Claude code from adding billing and version information in system prompts, thereby avoiding prompt cache invalidation.\n- Turning off CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION and CLAUDE_CODE_ENABLE_AWAY_SUMMARY can prevent quota from being consumed unnecessarily.\n- Claude Code WebSearch is supported for pure search requests. For Copilot, keep the global `messageApiWebSearchModel` set to a Responses-capable GPT model or a `provider/model` alias. For provider routes, use a native Anthropic provider or an `openai-responses` provider. Add `WebSearch` to `permissions.deny` only if you want to forbid this traffic.\n- If using a non-Claude model, do not enable ENABLE_TOOL_SEARCH. If using the Claude model, can enable ENABLE_TOOL_SEARCH. The current Claude Code uses the client tool search mode. In this mode, loading defer tools requires an additional request each time.\n- `CLAUDE_CODE_AUTO_COMPACT_WINDOW`: Set the context capacity in tokens used for auto-compaction calculations. Defaults to the model's context window: 200K for standard models or 1M for extended context models. Use a lower value like `500000` on a 1M model (e.g., `claude-opus-4-6[1m]`) to treat the window as 500K for compaction purposes. The value is capped at the model's actual context window. `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` is applied as a percentage of this value. Setting this variable decouples the compaction threshold from the status line's `used_percentage`, which always uses the model's full context window.\n\nYou can find more options here: [Claude Code settings](https://docs.anthropic.com/en/docs/claude-code/settings#environment-variables)\n\nYou can also read more about IDE integration here: [Add Claude Code to your IDE](https://docs.anthropic.com/en/docs/claude-code/ide-integrations)\n\n## Using with OpenCode\n\nOpenCode already has a direct GitHub Copilot provider. Use this section when you want OpenCode to point at this AI gateway through `@ai-sdk/anthropic` and reuse the agent behaviors described earlier in this README.\n\n### Minimal setup\n\nStart the AI gateway with the OpenCode OAuth app:\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth --oauth-app=opencode\nnpx @jeffreycao/copilot-api@latest start\n```\n\nThen point OpenCode at the gateway with `@ai-sdk/anthropic`.\n\nExample `~/.config/opencode/opencode.json`:\n\n```json\n{\n  \"$schema\": \"https://opencode.ai/config.json\",\n  \"provider\": {\n    \"local\": {\n      \"npm\": \"@ai-sdk/anthropic\",\n      \"name\": \"My Local\",\n      \"options\": {\n        \"baseURL\": \"http://localhost:4141/v1\",\n        \"apiKey\": \"dummy\"\n      },\n      \"models\": {\n        \"gpt-5.4\": {\n          \"name\": \"gpt-5.4\",\n          \"modalities\": {\n            \"input\": [\"text\", \"image\"],\n            \"output\": [\"text\"]\n          },\n          \"limit\": {\n            \"context\": 400000,\n            \"input\": 272000,\n            \"output\": 128000\n          }\n        },\n        \"claude-sonnet-4.6\": {\n          \"id\": \"claude-sonnet-4.6\",\n          \"name\": \"claude-sonnet-4.6\",\n          \"modalities\": {\n            \"input\": [\"text\", \"image\"],\n            \"output\": [\"text\"]\n          },          \n          \"limit\": {\n            \"context\": 200000,\n            \"output\": 32000\n          },\n          \"options\": {\n            \"thinking\": {\n              \"type\": \"adaptive\"\n            },\n            \"effort\": \"max\"\n          }\n        }\n      }\n    }\n  }\n}\n```\n\nWhy these fields matter:\n\n- `npm: \"@ai-sdk/anthropic\"` is the important part. OpenCode will speak Anthropic Messages semantics to this AI gateway instead of flattening everything into OpenAI Chat Completions.\n- `options.baseURL` should be `http://localhost:4141/v1`; the Anthropic SDK will append `/messages`, `/models`, and `/messages/count_tokens` automatically.\n- If you enable `auth.apiKeys` in this AI gateway, replace `dummy` with a real key. Otherwise any placeholder value is fine.\n\n## Using with Codex\n\nThis AI gateway can also power Codex.\n\n### Codex `config.toml` Reference\n\nAdd the following `[model_providers.copilot_api]` section to your Codex `~/.codex/config.toml`:\n\n```toml\nmodel_provider = \"copilot_api\"\nmodel_reasoning_summary = \"auto\"\nmodel_context_window = 272000\nmodel_auto_compact_token_limit = 244800\n\n[model_providers.copilot_api]\nname = \"OpenAI\"\nbase_url = \"http://localhost:4141\"\nenv_key = \"GITHUB_COPILOT_API_KEY\"\nrequires_openai_auth = true\nsupports_websockets = false\nwire_api = \"responses\"\nrequest_max_retries = 3\nstream_max_retries = 1\nstream_idle_timeout_ms = 300000\n\n[features]\nremote_compaction_v2 = true\n\n[analytics]\nenabled = false\n```\n\n> [!NOTE]\n> This configuration is specific to Codex and the GitHub Copilot provider. `name` must be set to `\"OpenAI\"`. It can help mitigate Codex local compact cache miss issues.\n> If you are using the codex provider, it is recommended to set `base_url` to `\"http://localhost:4141/codex\"`.\n\n## GPT Tool Search\n\nFor GPT Responses models such as `gpt-5.4+`, this AI gateway can expose Responses `tool_search` through a small MCP bridge. The same bridge can be used by Claude Code and opencode, as long as the client loads MCP servers and sends Anthropic Messages traffic through this gateway.\n\nDo not set Claude Code's native `ENABLE_TOOL_SEARCH` for GPT models. That flag enables Claude Code's own client-side tool search mode, and it may stop forwarding deferred tool definitions. This gateway needs the full tool definitions so it can keep the small always-loaded tool set eager and translate every other tool into Responses deferred namespaces.\n\nIf you install `tool-search@copilot-api-marketplace`, Claude Code receives this MCP bridge automatically and you can skip the manual Claude Code MCP setup below.\n\nAdd the tool search bridge to the MCP config used by Claude Code:\n\n```json\n{\n  \"mcpServers\": {\n    \"tool_search\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@jeffreycao/copilot-api@latest\", \"mcp\"]\n    }\n  }\n}\n```\n\nAdd the tool search bridge to the MCP config used by opencode:\n\n```json\n{\n  \"mcp\": {\n    \"tool_search\": {\n      \"type\": \"local\",\n      \"command\": [\"npx\", \"-y\", \"@jeffreycao/copilot-api@latest\", \"mcp\"]\n    }\n  }\n}\n```\n\nFor local development, use `bun` as the command and `[\"run\", \"./src/main.ts\", \"mcp\"]` as the args.\n\nInternally, the gateway now configures OpenAI Responses `tool_search` in client-executed mode. Deferred tools are still exposed as searchable namespaces, but the model is explicitly asked to return the exact deferred tool names it wants to load next.\n\nThe bridge uses direct tool selection, not query search. Its tool input is `names`, a comma-separated list of exact deferred tool names, for example `TaskList,TaskGet,mcp__fetch__fetch`.\n\n## Plugin Integrations\n\nPlugin integrations are available for Claude Code and opencode.\n\n#### Claude Code plugin integration (marketplace-based)\n\nThe Claude Code integration is packaged as two plugins:\n\n- `agent-inject` injects `__SUBAGENT_MARKER__...` on `SubagentStart`, so the gateway can infer `x-initiator: agent`.\n- `tool-search` registers the `tool_search` MCP bridge used for GPT Responses deferred tool loading.\n\n- Marketplace catalog in this repository: `.claude-plugin/marketplace.json`\n- Plugin sources in this repository: `plugin/claude/agent-inject`, `plugin/claude/tool-search`\n\nAdd the marketplace remotely:\n\n```sh\n/plugin marketplace add https://github.com/caozhiyuan/copilot-api.git\n```\n\nInstall the plugins from the marketplace:\n\n```sh\n/plugin install agent-inject@copilot-api-marketplace\n/plugin install tool-search@copilot-api-marketplace\n```\n\nAfter installation, `agent-inject` injects `__SUBAGENT_MARKER__...` on `SubagentStart`, and the gateway uses it to infer `x-initiator: agent`.\n\nThe `agent-inject` plugin also registers a `UserPromptSubmit` hook that returns `{\"continue\": true}`, and it can inject `SessionStart` reminder rules through environment variables:\n\n- `CLAUDE_PLUGIN_ENABLE_QUESTION_RULES=1` enables the two reminders about using the `question` tool automatically for Claude Code. Alternatively, you can add the same reminders manually in `CLAUDE.md`; see [CLAUDE.md or AGENTS.md Recommended Content](#claudemd-or-agentsmd-recommended-content).\n- `CLAUDE_PLUGIN_ENABLE_NO_BACKGROUND_AGENTS_RULE=1` enables the `run_in_background: true` avoidance reminder for agent hooks.\n\nThe `tool-search` plugin bundles the same MCP bridge described in [GPT Tool Search](#gpt-tool-search), so Claude Code users do not need to add the `tool_search` server manually when they install that plugin.\n\n#### Opencode plugin\n\nThe subagent marker producer is packaged as an opencode plugin located at `plugin/opencode/subagent-marker.js`.\n\n**Installation:**\n\nCopy the plugin file to your opencode plugins directory:\n\n```sh\n# Clone or download this repository, then copy the plugin\ncp plugin/opencode/subagent-marker.js ~/.config/opencode/plugins/\n```\n\nOr manually create the file at `~/.config/opencode/plugins/subagent-marker.js` with the plugin content.\n\n**Features:**\n\n- Tracks sub-sessions created by subagents\n- Automatically prepends a marker system reminder (`__SUBAGENT_MARKER__...`) to subagent chat messages\n- Sets `x-session-id` header for session tracking\n- Enables the gateway to infer `x-initiator: agent` for subagent-originated requests\n\nThe plugin hooks into `session.created`, `session.deleted`, `chat.message`, and `chat.headers` events to provide seamless subagent marker functionality.\n\n## Using the Usage Viewer\n\nAfter starting the server, a URL to the Copilot Usage Dashboard will be displayed in your console. This dashboard is a web interface for monitoring your API usage.\n\n1.  Start the server. For example, using npx:\n    ```sh\n    npx @jeffreycao/copilot-api@latest start\n    ```\n2.  The server will output a URL to the usage viewer. Copy and paste this URL into your browser. It will look something like this:\n    `http://localhost:4141/usage-viewer?endpoint=http://localhost:4141/usage`\n    - If you use the `start.bat` script on Windows, this page will open automatically.\n\nThe dashboard provides a user-friendly interface to view your Copilot usage data:\n\n> Token usage history requires Bun or Node.js >= 22.13.0. On Node.js < 22.13.0, the server runs normally but token usage storage is disabled.\n\n- **API Endpoint URL**: The dashboard is pre-configured to fetch data from your local server endpoint via a URL query parameter. You can manually switch this to any other compatible API endpoint.\n- **x-api-key Authentication**: If API Key authentication is enabled, you can provide the `x-api-key` request header. The key is persisted in the browser's local storage.\n- **Period Selector**: Choose from Day, Week, or Month time ranges. The URL query parameter updates automatically when you switch, making it easy to bookmark and share.\n- **Fetch Data**: Click the \"Refresh\" button to load or refresh the usage data. The dashboard also fetches data automatically on page load.\n- **Copilot Quotas**: View quota usage for services such as Chat and Completions via progress bars. Hover over a card to see used/remaining details.\n- **Token Usage Metric Cards**: See a summary of Total, Input, Output, Cache Read, Cache Write, Requests, and estimated cost for the current period.\n- **Trend Chart (Week / Month)**: An interactive line chart with model and metric filters. Click a data point to inspect the usage breakdown for a specific day.\n- **Model Breakdown Table**: A per-model summary of requests, input/output/cache tokens, and estimated cost for the selected period.\n- **Request Events (Paginated)**: A time-sorted list of request event records with pagination support, showing timestamps, models, request IDs, and token counts.\n- **Detailed Information**: See the full JSON response from the API for a detailed breakdown of all available usage statistics.\n- **URL-based Configuration**: You can also specify the API endpoint and period directly via `endpoint` and `period` query parameters. For example:\n  `http://localhost:4141/usage-viewer?endpoint=http://your-api-server/usage&period=week`\n\n### Usage Viewer Screenshot\n\n<p align=\"center\">\n  <img src=\"./docs/screenshots/usage-viewer.png\" alt=\"Copilot API usage viewer\" width=\"900\" />\n</p>\n\n## Command Structure\n\nCopilot API now uses a subcommand structure with these main commands:\n\n- `start`: Start the gateway server. If a GitHub token is available, the server starts with Copilot enabled. If no GitHub token is available, it starts in provider-only mode when at least one enabled provider exists; otherwise it guides you through provider setup.\n- `auth`: Run provider login or configuration without starting the server. Use it for GitHub Copilot login, Codex OAuth, or third-party provider API key setup.\n- `debug`: Display diagnostic information including version, runtime details, file paths, and authentication status. Useful for troubleshooting and support.\n\n## Command Line Options\n\n### Global Options\n\nThe following options can be used with any subcommand. When passing them before the subcommand, use the `--key=value` form:\n\n| Option            | Description                                            | Default | Alias |\n| ----------------- | ------------------------------------------------------ | ------- | ----- |\n| --api-home        | Path to the API home directory (sets COPILOT_API_HOME) | none    | none  |\n| --oauth-app       | OAuth app identifier (sets COPILOT_API_OAUTH_APP)      | none    | none  |\n| --enterprise-url  | Enterprise URL for GitHub (sets COPILOT_API_ENTERPRISE_URL) | none | none |\n\n### Start Command Options\n\nThe following command line options are available for the `start` command:\n\n| Option         | Description                                                                   | Default    | Alias |\n| -------------- | ----------------------------------------------------------------------------- | ---------- | ----- |\n| --port         | Port to listen on                                                             | 4141       | -p    |\n| --verbose      | Enable verbose logging                                                        | false      | -v    |\n| --github-token | Provide GitHub token directly (must be generated using the `auth` subcommand) | none       | -g    |\n| --claude-code  | Generate a command to launch Claude Code with Copilot API config              | false      | -c    |\n| --show-token   | Show GitHub and Copilot tokens on fetch and refresh                           | false      | none  |\n| --proxy-env    | Initialize proxy from environment variables                                   | false      | none  |\n\n### Auth Command Options\n\n| Option       | Description               | Default | Alias |\n| ------------ | ------------------------- | ------- | ----- |\n| --provider   | Provider to log in with or configure (`copilot`, `codex`, `opencode-go`, `deepseek`, `dashscope`, `openrouter`, or `custom`) | prompt | none |\n| --verbose    | Enable verbose logging    | false   | -v    |\n| --show-token | Show GitHub token on auth | false   | none  |\n\nUse `copilot-api auth login --provider copilot` only when you want to enable the GitHub Copilot provider. Copilot is not required for `codex` or third-party provider-only usage.\n\nUse `copilot-api auth login --provider deepseek`, `--provider dashscope`, `--provider openrouter`, or `--provider opencode-go` to add or update those common third-party providers from the CLI. DeepSeek prompts for masked `apiKey`, provider `type` (default `anthropic`), and `baseUrl` defaulting to `https://api.deepseek.com/anthropic`. DashScope prompts for masked `apiKey`, provider `type` (default `openai-compatible`), and prefilled `baseUrl`. OpenRouter prompts for masked `apiKey` and prefilled `baseUrl` only, and writes `type: \"anthropic\"`. OpenCode Go prompts for masked `apiKey` and prefilled `baseUrl` only, and writes `type: \"openai-compatible\"` (baseUrl `https://opencode.ai/zen/go`). After a provider is configured and enabled, `copilot-api start` can run without any GitHub token.\n\nUse `copilot-api auth login --provider custom` to add or update another third-party provider from the CLI. The command prompts for the provider name, supported type (`anthropic`, `openai-compatible`, or `openai-responses`), `baseUrl`, masked `apiKey`, and `authType`; `authType` may be left as the type default or set to `x-api-key` / `authorization`.\n\n### Debug Command Options\n\n| Option | Description               | Default | Alias |\n| ------ | ------------------------- | ------- | ----- |\n| --json | Output debug info as JSON | false   | none  |\n\n## Configuration (config.json)\n\n- **Location:** `~/.local/share/copilot-api/config.json` (Linux/macOS) or `%USERPROFILE%\\.local\\share\\copilot-api\\config.json` (Windows).\n- **Default shape:**\n  ```json\n  {\n    \"auth\": {\n      \"apiKeys\": [],\n      \"adminApiKey\": \"<auto-generated-on-startup>\"\n    },\n    \"providers\": {},\n    \"modelMappings\": {},\n    \"extraPrompts\": {\n      \"gpt-5-mini\": \"<built-in exploration prompt>\"\n    },\n    \"smallModel\": \"gpt-5-mini\",\n    \"contextManagement\": {\n      \"messages\": true,\n      \"responses\": false\n    },\n    \"modelResponsesApiCompactThresholds\": {\n      \"gpt-5.4\": 217600,\n      \"gpt-5.5\": 217600,\n      \"gpt-5.6-sol\": 231200,\n      \"gpt-5.6-terra\": 231200,\n      \"gpt-5.6-luna\": 231200\n    },\n    \"modelReasoningEfforts\": {\n      \"gpt-5-mini\": \"low\"\n    },\n    \"useMessagesApi\": true,\n    \"useResponsesApiWebSocket\": true,\n    \"useResponsesApiWebSearch\": true,\n    \"messageApiWebSearchModel\": \"gpt-5-mini\"\n  }\n  ```\n- **auth.apiKeys:** API keys used for request authentication on non-admin routes. Supports multiple keys for rotation. Requests can authenticate with either `x-api-key: <key>` or `Authorization: Bearer <key>`. If empty or omitted, authentication for non-admin routes is disabled.\n- **auth.adminApiKey:** Single admin key used only for `/admin/*` routes. If missing, the server generates a random key at startup and writes it back to `config.json`. Requests use the same `x-api-key` or `Authorization: Bearer` headers, but regular `auth.apiKeys` never grant access to `/admin/*`.\n- **modelMappings:** Exact `sourceModel -> targetModel` rewrites shared by top-level `POST /v1/messages`, `POST /v1/messages/count_tokens`, `POST /v1/responses`, and `POST /v1/chat/completions` requests. Omit it or leave it as `{}` to disable rewrites. Both the source and target must be non-empty strings. Targets can be regular model IDs or `provider/model` aliases such as `dashscope/qwen3.6-plus`, and the rewrite happens before provider alias parsing. These mappings are not split per interface. The admin endpoints `GET/POST /admin/config/model-mappings` read and update only this field.\n- **extraPrompts:** Map of `model -> prompt` appended to the first system prompt when translating Anthropic-style requests to Responses API. Use this to inject guardrails or guidance per model. Missing default entries are auto-added without overwriting your custom prompts. For GPT-5.3+ models (e.g. `gpt-5.3-codex`, `gpt-5.4`, `gpt-5.5`), a built-in commentary prompt is used as fallback when not explicitly configured. The built-in prompts enable phase-aware commentary, which lets the model emit a short user-facing progress update before tools or deeper reasoning.\n- **providers:** Global upstream provider map. Each provider key (for example `dashscope`) becomes a route prefix (`/dashscope/v1/messages`). Supports `type: \"anthropic\"`, `type: \"openai-compatible\"`, and `type: \"openai-responses\"`. Top-level clients can also use `model: \"dashscope/model-id\"` with `/v1/messages`, `/v1/messages/count_tokens`, `/v1/responses`, and `/v1/chat/completions`; the gateway strips the `dashscope/` prefix before forwarding upstream. `openai-compatible` providers support both chat and Messages flows: `/v1/chat/completions` is proxied to upstream `/v1/chat/completions`, while `/v1/messages` and `/:provider/v1/messages` are translated to upstream chat completions and translated back to Anthropic Messages responses. `GET /v1/models` aggregates enabled provider models with `provider/model-id` IDs; use `GET /dashscope/v1/models` for a single provider's raw model list.\n  - `enabled` defaults to `true` if omitted.\n  - `baseUrl` should be provider API base URL without the final endpoint. For Anthropic providers, omit `/v1/messages`; for OpenAI-compatible providers, omit `/v1/chat/completions`; for OpenAI Responses providers, omit `/v1/responses`.\n  - `apiKey` is used as the upstream credential value and is required for regular providers.\n  - `authType` (optional): Controls how `apiKey` is sent upstream. Supports `x-api-key` and `authorization` for regular providers. Anthropic providers default to `x-api-key`; OpenAI-compatible and OpenAI Responses providers default to `authorization`. When set to `authorization`, the proxy sends `Authorization: Bearer <apiKey>`. `oauth2` is reserved for the built-in `codex` provider and is written automatically by `auth login --provider codex`.\n  - `pricingCurrency` (optional): Provider-level currency used for token cost calculation, for example `USD` or `CNY`. Quick providers default to `CNY` for DashScope and DeepSeek, and `USD` for Codex/OpenRouter. Costs are grouped by currency and are not exchange-rate converted.\n  - `models` (optional): Per-model configuration map. Each key is a model ID (matching the model name in requests), and the value is:\n    - `temperature` (optional): Default temperature value used when the request does not specify one.\n    - `topP` (optional): Default top_p value used when the request does not specify one.\n    - `topK` (optional): Default top_k value used when the request does not specify one.\n    - `extraBody` (optional): Dynamic fields merged into the upstream request body for that model. Request body fields with the same name take precedence. OpenAI-compatible providers can use this for fields such as `enable_thinking`, `preserve_thinking`, `reasoning_effort`. `thinking_budget` is a special OpenAI-compatible provider override: when configured in `extraBody`, it is forced after Anthropic `thinking.budget_tokens` translation and overrides the request-derived budget. For providers whose name is `dashscope` or whose `baseUrl` contains `aliyuncs.com`, the request-derived `thinking_budget` (from Anthropic `thinking.budget_tokens`) is forwarded upstream; for other OpenAI-compatible providers the request-derived `thinking_budget` is stripped, while an `extraBody` `thinking_budget` is still honored. For DashScope providers, `preserve_thinking` defaults to `true` when not explicitly set in `extraBody` or the request body.\n    - `pricing` (optional): Per-model token prices, in the provider `pricingCurrency`, per 1M tokens. Supported fields are `input`, `output`, `cachedInput` (implicit cache read), `explicitCachedInput` (explicit cache read), and `cacheCreationInput`. Use `tiers` with `maxInputTokens` for input-size tiered pricing.\n    - `contextCache` (optional): Defaults to `true` for providers whose name is `dashscope` or whose `baseUrl` contains `aliyuncs.com`; defaults to `false` for other OpenAI-compatible providers. This enables Alibaba Cloud Model Studio/DashScope explicit context cache by injecting `cache_control: { \"type\": \"ephemeral\" }` on up to 4 content blocks using the Context Cache format. The cache breakpoint strategy matches opencode's main provider flow: the first 2 system messages plus the last 2 non-system messages. Marked string content is converted to text content part arrays for `system` / `user` / `assistant` / `tool` messages; existing array content is marked on the last part. Set this to `false` when the model already supports implicit caching, or when the upstream does not accept this explicit-cache extension field. Set this to `true` for non-DashScope providers that support the same explicit-cache extension. Applied on both `/v1/messages` and `/v1/chat/completions` routes.\n    - `supportPdf` (optional): Controls whether the model supports PDF/document content. Defaults to `false`; unsupported PDFs are converted to a text notice. Set it to `true` to send PDF/document blocks as OpenAI Chat Completions file parts.\n    - `toolContentSupportType` (optional): Tool result content capabilities for that model, as an array of `array`, `image`, and `pdf`. Provider routes default to string-only tool content when omitted. If `supportPdf` is `true` but this list does not include `pdf`, file parts in tool results are moved to user role messages. This provider default does not change the Copilot main flow, which continues to support array + image and not PDF.\n    - `type` (optional): Per-model override of the provider protocol type. Supports `anthropic`, `openai-compatible`, and `openai-responses`. When set, the provider's `/v1/messages` route uses this model's type instead of the provider-level type for request routing, auth header resolution, and upstream endpoint selection. This is useful for providers like OpenCode Go whose upstream supports both OpenAI-compatible and Anthropic Messages APIs for different models. When the type is overridden, the auth header is resolved from the overridden type's default (Anthropic defaults to `x-api-key`; OpenAI-compatible/Responses default to `authorization`).\n\n  Example DashScope model settings:\n  ```json\n  {\n    \"providers\": {\n      \"dashscope\": {\n        \"type\": \"openai-compatible\",\n        \"enabled\": true,\n        \"baseUrl\": \"https://dashscope.aliyuncs.com/compatible-mode\",\n        \"apiKey\": \"sk-your-dashscope-key\",\n        \"pricingCurrency\": \"CNY\",\n        \"models\": {\n          \"qwen3.7-plus\": {\n            \"temperature\": 1,\n            \"topP\": 0.95,\n            \"topK\": 20,\n            \"extraBody\": {\n              \"preserve_thinking\": true\n            }\n          },\n          \"glm-5.1\": {\n            \"temperature\": 0.7,\n            \"topP\": 0.95,\n            \"contextCache\": true,\n            \"pricing\": {\n              \"tiers\": [\n                {\n                  \"maxInputTokens\": 32000,\n                  \"input\": 6,\n                  \"cachedInput\": 1.2,\n                  \"explicitCachedInput\": 0.6,\n                  \"cacheCreationInput\": 7.5,\n                  \"output\": 24\n                },\n                {\n                  \"maxInputTokens\": 200000,\n                  \"input\": 8,\n                  \"cachedInput\": 1.6,\n                  \"explicitCachedInput\": 0.8,\n                  \"cacheCreationInput\": 10,\n                  \"output\": 28\n                }\n              ]\n            },\n            \"extraBody\": {\n              \"preserve_thinking\": true\n            }\n          }\n        }\n      }\n    }\n  }\n  ```\n  Built-in token prices cover Codex GPT models in USD, DashScope `qwen3.7-max`, `qwen3.7-plus`, `glm-5.1`, `glm-5.2` in CNY, DeepSeek `deepseek-v4-flash`, `deepseek-v4-pro`, `deepseek-chat`, `deepseek-reasoner` in CNY, and OpenCode Go models (`glm-5.2`, `grok-4.5`, `deepseek-v4-flash`, `deepseek-v4-pro`, `kimi-k2.7-code`, `kimi-k3`, `mimo-v2.5`, `mimo-v2.5-pro`, `qwen3.7-plus`, `qwen3.7-max`, `minimax-m2.7`, `minimax-m3`) in USD. User `pricing` entries override built-ins. For DashScope, cached tokens are charged as explicit cache reads when the upstream usage includes `cache_creation_input_tokens`; otherwise `cachedInput` is used as the implicit cache read price. For DeepSeek, `prompt_cache_hit_tokens` map to cached input and `prompt_cache_miss_tokens` map to regular input.\n- **smallModel:** Fallback model used for tool-less warmup messages (e.g., Claude Code probe requests); defaults to gpt-5-mini.\n- **contextManagement:** Controls whether the proxy adds Responses API `context_management` compaction instructions. `messages` applies when Anthropic-style `/v1/messages` requests are translated to Responses API, including `openai-responses` provider message routes, and defaults to `true`. `responses` applies to native `/v1/responses` traffic, including `provider/model` aliases and the built-in `codex` provider, and defaults to `false`. Enable `responses` only after checking that your client supports context management compaction. When enabled, the request includes `context_management` in the body and keeps only the latest compaction carrier on follow-up turns. **Note:** Context management is forcibly disabled for GPT-5.6 and above models (e.g. `gpt-5.6-sol`, `gpt-5.6-terra`, `gpt-5.6-luna`) because enabling it breaks prompt cache hits on those models. This override takes precedence over the `contextManagement` and `modelResponsesApiCompactThresholds` settings.\n- **modelResponsesApiCompactThresholds:** Per-model Responses API `compact_threshold` overrides used when the proxy adds `context_management`. These values take precedence over the fallback threshold from `resolveResponsesCompactThreshold` (`max_prompt_tokens * ratio`, or the default fallback). Defaults set `gpt-5.4` and `gpt-5.5` to `217600` (`272000 * 0.8`), and `gpt-5.6-sol`, `gpt-5.6-terra`, `gpt-5.6-luna` to `231200` (`272000 * 0.85`). Models not listed continue to use the normal fallback logic.\n- **modelReasoningEfforts:** Per-model fallback reasoning effort for `/v1/messages` requests. It is used only when the request does not provide `output_config.effort`.\n  - **Priority:** request `output_config.effort` > `modelReasoningEfforts[model]` > built-in default (`xhigh` for GPT-5.3+ models, otherwise `high`).\n  - **Forwarding:** the resolved value remains `output_config.effort` for the Copilot native Messages API and becomes `reasoning.effort` when translated to the Responses API.\n  - **Configuration values:** `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`.\n- **useMessagesApi:** When `true`, Claude-family models that support Copilot's native `/v1/messages` endpoint will use the Messages API; otherwise they fall back to `/chat/completions`. Set to `false` to disable Messages API routing and always use `/chat/completions`. Defaults to `true`.\n- **useResponsesApiWebSocket:** When `true`, Responses API requests use Copilot's websocket transport for models that advertise `ws:/responses`; models that only advertise `/responses` continue to use HTTP. Set to `false` to disable websocket routing and use HTTP `/responses` whenever the selected model supports it. Defaults to `true`. If the Responses API WebSocket gets closed, it is usually caused by your own network. If you are using a VPN, try switching to a different node.\n- **useResponsesApiWebSearch:** When `true`, the server keeps Responses API tools with `type: \"web_search\"` and forwards them upstream. Set to `false` to strip those tools from `/responses` payloads. Defaults to `true`.\n- **messageApiWebSearchModel:** Global fallback model used when a top-level Copilot `/v1/messages` request contains only the server-side `web_search` tool. Defaults to `gpt-5-mini`. If the value is a `provider/model` alias, the request is routed into that provider's Messages API path with the provider prefix stripped. For Copilot GPT models, web search runs through `/responses`. Mixed `web_search` plus custom tools are not supported and the server-side `web_search` tool is stripped.\n- **claudeTokenMultiplier:** Multiplier applied to the fallback GPT-tokenizer estimate for Claude `/v1/messages/count_tokens` requests. Defaults to `1.15`. Increase it if your client is still compacting too late. This setting is only used when the proxy is estimating Claude tokens locally; if `anthropicApiKey` is configured and Anthropic token counting succeeds, the exact Anthropic count is returned instead.\n- **anthropicApiKey:** Anthropic API key used to forward Claude `/v1/messages/count_tokens` requests to Anthropic's real token counting endpoint, which returns exact counts instead of GPT tokenizer estimates. Can also be set via the `ANTHROPIC_API_KEY` environment variable. If not set, or if the upstream call fails, token counting falls back to local GPT tokenizer estimation controlled by `claudeTokenMultiplier`.\n\nEdit this file to customize prompts or swap in your own fast model. Restart the server (or rerun the command) after changes so the cached config is refreshed.\n\n## API Authentication\n\n- **Protected non-admin routes:** All routes except `/`, `/usage-viewer`, and `/usage-viewer/` require authentication when `auth.apiKeys` is configured and non-empty.\n- **Admin routes:** All `/admin/*` routes require `auth.adminApiKey`. If it is missing, the server generates one at startup and persists it to `config.json` before serving requests.\n- **Allowed auth headers:**\n  - `x-api-key: <your_key>`\n  - `Authorization: Bearer <your_key>`\n- **CORS preflight:** `OPTIONS` requests are always allowed.\n- **When no regular keys are configured:** Non-admin routes continue to allow requests. This does not apply to `/admin/*`, which only accepts `auth.adminApiKey`.\n\nExample request for a regular protected route:\n\n```sh\ncurl http://localhost:4141/v1/models \\\n  -H \"x-api-key: your_api_key\"\n```\n\nExample request for an admin route:\n\n```sh\ncurl http://localhost:4141/admin/config/model-mappings \\\n  -H \"x-api-key: your_admin_api_key\"\n```\n\n## API Endpoints\n\nThe server exposes several OpenAI- and Anthropic-compatible endpoints. Requests can target GitHub Copilot, the built-in `codex` provider, or configured providers depending on the selected model and `provider/model` alias.\n\n### OpenAI Compatible Endpoints\n\nThese endpoints mimic the OpenAI API structure.\n\n| Endpoint                    | Method | Description                                                      |\n| --------------------------- | ------ | ---------------------------------------------------------------- |\n| `POST /v1/responses`        | `POST` | OpenAI Most advanced interface for generating model responses. Supports `provider/model` aliases for `openai-responses` providers. |\n| `POST /v1/chat/completions` | `POST` | Creates a model response for the given chat conversation. Supports `provider/model` aliases for `openai-compatible` providers and can be used without Copilot when the target provider is configured. |\n| `GET /v1/models`            | `GET`  | Lists Copilot models plus enabled provider models using `provider/model-id` IDs. Requests from Codex clients (`User-Agent` beginning with `codex`) are forwarded to the Codex Models upstream. |\n| `POST /v1/embeddings`       | `POST` | Creates an embedding vector representing the input text.         |\n\n### Codex Backend Proxy Endpoints\n\nThese endpoints require an active Codex login. Each endpoint is available both without a version prefix and under `/v1`.\n\n| Endpoint | Method | Description |\n| --- | --- | --- |\n| `POST /alpha/search`<br>`POST /v1/alpha/search` | `POST` | Transparently forwards the JSON body and query parameters to the Codex Alpha Search upstream. |\n| `POST /images/generations`<br>`POST /v1/images/generations` | `POST` | Forwards a JSON image generation request to the Codex Images upstream. When the request omits `Content-Type`, the gateway defaults it to `application/json`. |\n| `POST /images/edits`<br>`POST /v1/images/edits` | `POST` | Forwards an image edit request to the Codex Images upstream. Send this request as `multipart/form-data` and let the HTTP client generate the `boundary`; the gateway preserves the incoming content type and streams the upload body. |\n\nFor every endpoint above, the gateway replaces client authorization and account headers with the active Codex login, preserves query parameters and compatible request headers, and returns the upstream status, headers, and body.\n\n### Anthropic Compatible Endpoints\n\nThese endpoints are designed to be compatible with the Anthropic Messages API. Provider-scoped models, Responses, alpha-search, and images routes accept both unversioned and `/v1` paths; Messages routes remain under `/v1`.\n\n| Endpoint                         | Method | Description                                                  |\n| -------------------------------- | ------ | ------------------------------------------------------------ |\n| `POST /v1/messages`              | `POST` | Creates a model response for a given conversation. Supports `provider/model` aliases for configured providers, including translation through `openai-compatible` providers. |\n| `POST /v1/messages/count_tokens` | `POST` | Calculates the number of tokens for a given set of messages. Supports `provider/model` aliases for configured providers. |\n| `POST /:provider/v1/messages`       | `POST` | Proxies Anthropic Messages requests to the configured Anthropic provider, translates them through an OpenAI-compatible provider, or translates them through an OpenAI Responses provider. |\n| `GET /:provider/models`<br>`GET /:provider/v1/models` | `GET` | Proxies model listing requests to the configured provider. For `codex`, returns the built-in catalog by default; Codex clients (`User-Agent` starting with `codex`) are forwarded to the Codex Models upstream. |\n| `POST /:provider/v1/messages/count_tokens` | `POST` | Calculates tokens locally for provider route requests. |\n| `POST /:provider/responses`<br>`POST /:provider/v1/responses` | `POST` | Proxies OpenAI Responses requests to a configured `openai-responses` provider (including `codex`). |\n| `POST /:provider/alpha/search`<br>`POST /:provider/v1/alpha/search` | `POST` | Proxies alpha-search requests. For `codex`, forwards to the Codex Alpha Search upstream; for other providers, forwards to `{baseUrl}/v1/alpha/search`. |\n| `POST /:provider/images/generations`<br>`POST /:provider/v1/images/generations` | `POST` | Proxies image generation. For `codex`, uses the Codex Images upstream; for other providers, forwards to `{baseUrl}/v1/images/generations` (15-minute timeout). |\n| `POST /:provider/images/edits`<br>`POST /:provider/v1/images/edits` | `POST` | Proxies image edits. For `codex`, uses the Codex Images upstream; for other providers, forwards multipart/streamed bodies to `{baseUrl}/v1/images/edits` (15-minute timeout). |\n\n### Usage Monitoring Endpoints\n\nNew endpoints for monitoring your Copilot usage and quotas.\n\n| Endpoint     | Method | Description                                                  |\n| ------------ | ------ | ------------------------------------------------------------ |\n| `GET /usage` | `GET`  | Get detailed Copilot usage statistics and quota information. |\n| `GET /token` | `GET`  | Get the current Copilot token being used by the API.         |\n\n### Admin / Configuration Endpoints\n\nThese endpoints are reserved for local administrative actions and only accept `auth.adminApiKey`.\n\n| Endpoint                              | Method | Description                                                                 |\n| ------------------------------------- | ------ | --------------------------------------------------------------------------- |\n| `GET /admin/config/model-mappings`    | `GET`  | Returns the current `config.json` path and the active `modelMappings` map.  |\n| `POST /admin/config/model-mappings`   | `POST` | Updates only the `modelMappings` field in `config.json` and returns it back. |\n\n## Example Usage\n\nCommon `npx` commands:\n\n```sh\n# Start the gateway\nnpx @jeffreycao/copilot-api@latest start\n\n# Start on a custom port with verbose logging\nnpx @jeffreycao/copilot-api@latest start --port 8080 --verbose\n\n# Run the auth flow\nnpx @jeffreycao/copilot-api@latest auth login\n\n# Configure a third-party provider, then run without GitHub Copilot\nnpx @jeffreycao/copilot-api@latest auth login --provider dashscope\nnpx @jeffreycao/copilot-api@latest start\n\n# Print debug information as JSON\nnpx @jeffreycao/copilot-api@latest debug --json\n\n# Run the published CLI with Bun instead of Node.js\nbunx --bun @jeffreycao/copilot-api@latest start\n```\n\nOpenAI-compatible provider examples after configuring `dashscope`:\n\n```sh\ncurl http://localhost:4141/v1/chat/completions \\\n  -H \"content-type: application/json\" \\\n  -d '{\"model\":\"dashscope/qwen3.6-plus\",\"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]}'\n\ncurl http://localhost:4141/dashscope/v1/messages \\\n  -H \"content-type: application/json\" \\\n  -d '{\"model\":\"qwen3.6-plus\",\"max_tokens\":1024,\"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]}'\n```\n\n## Usage Tips\n\n### CLAUDE.md or AGENTS.md Recommended Content\n\nTo add these reminders manually, include the following in `CLAUDE.md` for Claude Code, or `AGENTS.md` for opencode/codex:\n\n```\n- Prohibited from directly asking questions to users, MUST use question tool.\n- Once you can confirm that the task is complete, MUST use question tool to make user confirm. The user may respond with feedback if they are not satisfied with the result, which you can use to make improvements and try again, after try again, MUST use question tool to make user confirm again.\n```\n"}, "bc113f6a4c5909c996bb791d388dff51831459b3": {"t": 1785765537.1739821, "n": 51088, "h": "a3e38b6a36cb71d2", "c": "# Copilot API Proxy\n\nEnglish | [简体中文](./README.zh-CN.md)\n\n## Important Notes\n\n> [!IMPORTANT]\n> **Before using, please be aware of the following:**\n>\n> 1. **Claude Code configuration:** When using with Claude Code, please configure the model ID as `claude-opus-4-8`. Example claude `settings.json` see [Manual Configuration with `settings.json`](#manual-configuration-with-settingsjson). \n>\n> 2. **Built-in `copilot`, `codex` and third-party providers:** Run `npx @jeffreycao/copilot-api@latest auth` and choose `copilot`, `codex`, `deepseek`, `custom`, or other providers.\n>\n> 3. **Note:** See [GitHub Copilot Security Notice](./NOTICE.md#github-copilot-security-notice) for the warning removed from the README header.\n\n---\n\n## Project Overview\n\nA small AI gateway that can use GitHub Copilot, the built-in `codex` provider, or configured third-party providers such as DashScope. GitHub Copilot is optional: if no GitHub token is available, the server can still start in provider-only mode as long as at least one enabled provider is configured.\n\nThe gateway exposes OpenAI- and Anthropic-compatible APIs from one local endpoint, so tools like [Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview), OpenCode, Codex, and OpenAI-compatible clients can share the same local server.\n\nOn the GitHub Copilot path, the gateway prefers Copilot's native Anthropic-style Messages API when available, preserving more Claude-native behavior for tool-heavy workflows.\n\n## Features\n\n- **OpenAI and Anthropic compatibility**: Serve `/v1/responses`, `/v1/chat/completions`, `/v1/models`, `/v1/embeddings`, and `/v1/messages` from one local gateway.\n- **Copilot is optional**: Use GitHub Copilot when credentials are present, or run the server with only configured providers.\n- **One gateway for Copilot, `codex`, and external providers**: Route GitHub Copilot, the built-in `codex` provider, and configured third-party providers behind the same endpoint.\n- **Standalone third-party providers**: Configure providers such as DashScope, DeepSeek, OpenRouter, or a custom provider and start the gateway without a GitHub Copilot login.\n- **OpenAI-compatible providers on chat and Messages APIs**: `openai-compatible` providers can serve top-level `/v1/chat/completions` through `model: \"provider/model\"` and Anthropic-style `/v1/messages` through request/response translation.\n- **Agent-friendly Claude handling on Copilot**: Prefer native `/v1/messages` when available, preserve Claude-style tool flows, support Anthropic beta features, Claude WebSearch through Responses-capable models, and keep subagent/session markers intact.\n- **Claude Code and OpenCode integration**: Works with Claude Code and OpenCode, including direct Anthropic-compatible usage through `@ai-sdk/anthropic`.\n- **Flexible auth and deployment options**: Supports interactive login or direct tokens, individual/business/enterprise plans, GitHub Enterprise, opencode OAuth, and custom data directories.\n- **Multi-provider routing**: Expose provider-specific `/:provider/...` routes or use `model: \"provider/model\"` on the top-level API.\n\n## Prerequisites\n\n- Bun (>= 1.2.x)\n- Node.js if you plan to run the published CLI with `npx`\n- GitHub account with Copilot subscription only if you want to use the GitHub Copilot provider\n- An API key or OAuth login for at least one configured provider if you want to run without GitHub Copilot\n\n## Installation\n\nTo install dependencies, run:\n\n```sh\nbun install\n```\n\nTo start the server directly from source:\n\n```sh\nbun run start start\n```\n\n## Running from Source\n\nThe project can be run from source in several ways:\n\n### Development Mode\n\n```sh\nbun run dev start\n```\n\n### Production Mode\n\n```sh\nbun run start start\n```\n\n## Using with npx\n\nYou can run the project directly using npx:\n\n> [!IMPORTANT]\n> Token usage storage uses Node's built-in `node:sqlite` module when running with `npx`. It is enabled on Node.js >= 22.13.0. On Node.js < 22.13.0, the CLI still starts, but token usage storage is disabled.\n>\n> If you want token usage storage without upgrading Node.js, run the published CLI with Bun instead: `bunx --bun @jeffreycao/copilot-api@latest start`.\n\n```sh\nnpx @jeffreycao/copilot-api@latest start\n```\n\nWith options:\n\n```sh\nnpx @jeffreycao/copilot-api@latest start --port 8080\n```\n\nFor authentication or provider configuration only:\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth\n```\n\nTo run without GitHub Copilot, configure at least one provider first, then start the server normally:\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth login --provider dashscope\nnpx @jeffreycao/copilot-api@latest start\n```\n\n## Using with Docker\n\nBuild the image:\n\n```sh\ndocker build -t copilot-api .\n```\n\nRun the container with a bind mount so auth data survives restarts:\n\n```sh\nmkdir -p ./copilot-data\ndocker run -p 4141:4141 -v $(pwd)/copilot-data:/root/.local/share/copilot-api copilot-api\n```\n\nThis stores GitHub auth data, provider config, and other gateway state in `./copilot-data` on the host, mapped to `/root/.local/share/copilot-api` in the container.\n\nOr pass a GitHub token directly:\n\n```sh\ndocker run -p 4141:4141 -e GH_TOKEN=your_github_token_here copilot-api\n```\n\n## Electron Desktop App\n\nIf you prefer a GUI, this repository also includes an Electron desktop app in `desktop/`. It supports GitHub Copilot sign-in, OpenAI Codex OAuth, and API-key configuration for DeepSeek, DashScope, OpenRouter, or a custom provider. After authorization or provider configuration, it can start and stop the local proxy with one click and shows the local endpoint, auth header, available models, usage, and logs in the app.\n\nThe settings screen also exposes `OAuth App`, `API Home`, `Enterprise URL`, verbose logging, and minimize-to-tray. Windows x64 (`.exe`), macOS Apple Silicon (`.dmg`), and Linux x64 (`.AppImage`) packages are published in GitHub Releases:\n\nhttps://github.com/caozhiyuan/copilot-api/releases\n\nOn Linux, make the downloaded AppImage executable before launching it:\n\n```sh\nchmod +x Copilot-API-*-linux-x86_64.AppImage\n./Copilot-API-*-linux-x86_64.AppImage\n```\n\nDownload the installer for your platform, authorize or configure a provider inside the app, choose a port, start the server, then point your client at the local endpoint shown in the app. Packaged desktop builds use the bundled Electron runtime, so normal desktop usage does not require installing Node.js separately. Token usage history is enabled when that bundled runtime supports SQLite.\n\nThe desktop app's Advanced Config page reads and writes the shared model mappings through `GET/POST /admin/config/model-mappings`. The same mappings apply across `POST /v1/messages`, `POST /v1/messages/count_tokens`, `POST /v1/responses`, and `POST /v1/chat/completions` instead of being split per interface. It uses `auth.adminApiKey` instead of the regular `auth.apiKeys`, and the app reads that key directly from `config.json` after the server has generated it on startup.\n\n### Desktop App Screenshots\n\nMain dashboard, token usage breakdown in the bundled Electron app:\n\n<p align=\"center\">\n  <img src=\"./docs/screenshots/desktop-dashboard.png\" alt=\"Copilot API desktop app dashboard\" width=\"49%\" />\n  <img src=\"./docs/screenshots/desktop-token-usage.png\" alt=\"Copilot API desktop app token usage view\" width=\"49%\" />\n</p>\n\n## Using with Claude Code\n\nThis AI gateway can be used to power [Claude Code](https://docs.anthropic.com/en/claude-code), an experimental conversational AI assistant for developers from Anthropic.\n\nThere are two ways to configure Claude Code to use this AI gateway:\n\n### Interactive Setup with `--claude-code` flag\n\nTo get started, run the `start` command with the `--claude-code` flag:\n\n```sh\nnpx @jeffreycao/copilot-api@latest start --claude-code\n```\n\nYou will no longer be prompted to pick models manually. The gateway automatically detects the latest available model for each Claude Code size tier — opus maps to the newest Opus model, sonnet to the newest Sonnet model, and haiku to the newest Haiku model — and generates a command that sets `ANTHROPIC_DEFAULT_OPUS_MODEL`, `ANTHROPIC_DEFAULT_SONNET_MODEL`, and `ANTHROPIC_DEFAULT_HAIKU_MODEL` accordingly. Any tier without a matching model available is omitted. The command is copied to your clipboard and sets the environment variables needed for Claude Code to use the gateway.\n\nPaste and run this command in a new terminal to launch Claude Code.\n\n### Manual Configuration with `settings.json`\n\nAlternatively, you can configure Claude Code by creating a `.claude/settings.json` file in your project's root directory. This file should contain the environment variables needed by Claude Code. This way you don't need to run the interactive setup every time.\n\nHere is an example `.claude/settings.json` file:\n\n```json\n{\n  \"env\": {\n    \"ANTHROPIC_BASE_URL\": \"http://localhost:4141\",\n    \"ANTHROPIC_AUTH_TOKEN\": \"dummy\",\n    \"ANTHROPIC_MODEL\": \"gpt-5.6-sol[1m]\",\n    \"ANTHROPIC_DEFAULT_SONNET_MODEL\": \"gpt-5.6-sol[1m]\",\n    \"ANTHROPIC_DEFAULT_HAIKU_MODEL\": \"gpt-5.6-luna[1m]\",\n    \"CLAUDE_CODE_AUTO_COMPACT_WINDOW\": \"272000\",\n    \"CLAUDE_CODE_USE_VERTEX\": \"0\",\n    \"CLAUDE_CODE_USE_BEDROCK\": \"0\",\n    \"DISABLE_NON_ESSENTIAL_MODEL_CALLS\": \"1\",\n    \"CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC\": \"1\",\n    \"CLAUDE_CODE_ATTRIBUTION_HEADER\": \"0\",\n    \"CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION\": \"false\",\n    \"CLAUDE_CODE_DISABLE_TERMINAL_TITLE\": \"true\",\n    \"CLAUDE_CODE_ENABLE_AWAY_SUMMARY\": \"0\"\n  },\n  \"alwaysThinkingEnabled\": true,\n  \"effortLevel\": \"xhigh\",\n  \"showThinkingSummaries\": true\n}\n```\n\n- Replace `ANTHROPIC_MODEL`, `ANTHROPIC_DEFAULT_OPUS_MODEL`, `ANTHROPIC_DEFAULT_SONNET_MODEL`, and `ANTHROPIC_DEFAULT_HAIKU_MODEL` according to your needs. After configuration, please install the claude code plugin [Plugin Integrations](#plugin-integrations).  \n- If you are using the codex provider, it is recommended **not** to configure the model name in the `codex/xxx` format (e.g. `codex/gpt-5.6-sol`). Claude Code treats the `codex/` prefix as a special pattern and applies degraded behavior — for example, it strips all previously returned thinking blocks on every request. Use the plain model name (e.g. `gpt-5.6-sol`) instead, and add a `modelMappings` entry in `config.json` to route it back to the codex provider:\n  ```json\n  \"modelMappings\": {\n    \"gpt-5.6-sol\": \"codex/gpt-5.6-sol\",\n    \"gpt-5.6-terra\": \"codex/gpt-5.6-terra\",\n    \"gpt-5.6-luna\": \"codex/gpt-5.6-luna\"\n  },\n  ```\n- Setting CLAUDE_CODE_ATTRIBUTION_HEADER to 0 can prevent Claude code from adding billing and version information in system prompts, thereby avoiding prompt cache invalidation.\n- Turning off CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION and CLAUDE_CODE_ENABLE_AWAY_SUMMARY can prevent quota from being consumed unnecessarily.\n- Claude Code WebSearch is supported for pure search requests. For Copilot, keep the global `messageApiWebSearchModel` set to a Responses-capable GPT model or a `provider/model` alias. For provider routes, use a native Anthropic provider or an `openai-responses` provider. Add `WebSearch` to `permissions.deny` only if you want to forbid this traffic.\n- If using a non-Claude model, do not enable ENABLE_TOOL_SEARCH. If using the Claude model, can enable ENABLE_TOOL_SEARCH. The current Claude Code uses the client tool search mode. In this mode, loading defer tools requires an additional request each time.\n- `CLAUDE_CODE_AUTO_COMPACT_WINDOW`: Set the context capacity in tokens used for auto-compaction calculations. Defaults to the model's context window: 200K for standard models or 1M for extended context models. Use a lower value like `500000` on a 1M model (e.g., `claude-opus-4-6[1m]`) to treat the window as 500K for compaction purposes. The value is capped at the model's actual context window. `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` is applied as a percentage of this value. Setting this variable decouples the compaction threshold from the status line's `used_percentage`, which always uses the model's full context window.\n\nYou can find more options here: [Claude Code settings](https://docs.anthropic.com/en/docs/claude-code/settings#environment-variables)\n\nYou can also read more about IDE integration here: [Add Claude Code to your IDE](https://docs.anthropic.com/en/docs/claude-code/ide-integrations)\n\n## Using with OpenCode\n\nOpenCode already has a direct GitHub Copilot provider. Use this section when you want OpenCode to point at this AI gateway through `@ai-sdk/anthropic` and reuse the agent behaviors described earlier in this README.\n\n### Minimal setup\n\nStart the AI gateway with the OpenCode OAuth app:\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth --oauth-app=opencode\nnpx @jeffreycao/copilot-api@latest start\n```\n\nThen point OpenCode at the gateway with `@ai-sdk/anthropic`.\n\nExample `~/.config/opencode/opencode.json`:\n\n```json\n{\n  \"$schema\": \"https://opencode.ai/config.json\",\n  \"provider\": {\n    \"local\": {\n      \"npm\": \"@ai-sdk/anthropic\",\n      \"name\": \"My Local\",\n      \"options\": {\n        \"baseURL\": \"http://localhost:4141/v1\",\n        \"apiKey\": \"dummy\"\n      },\n      \"models\": {\n        \"gpt-5.4\": {\n          \"name\": \"gpt-5.4\",\n          \"modalities\": {\n            \"input\": [\"text\", \"image\"],\n            \"output\": [\"text\"]\n          },\n          \"limit\": {\n            \"context\": 400000,\n            \"input\": 272000,\n            \"output\": 128000\n          }\n        },\n        \"claude-sonnet-4.6\": {\n          \"id\": \"claude-sonnet-4.6\",\n          \"name\": \"claude-sonnet-4.6\",\n          \"modalities\": {\n            \"input\": [\"text\", \"image\"],\n            \"output\": [\"text\"]\n          },          \n          \"limit\": {\n            \"context\": 200000,\n            \"output\": 32000\n          },\n          \"options\": {\n            \"thinking\": {\n              \"type\": \"adaptive\"\n            },\n            \"effort\": \"max\"\n          }\n        }\n      }\n    }\n  }\n}\n```\n\nWhy these fields matter:\n\n- `npm: \"@ai-sdk/anthropic\"` is the important part. OpenCode will speak Anthropic Messages semantics to this AI gateway instead of flattening everything into OpenAI Chat Completions.\n- `options.baseURL` should be `http://localhost:4141/v1`; the Anthropic SDK will append `/messages`, `/models`, and `/messages/count_tokens` automatically.\n- If you enable `auth.apiKeys` in this AI gateway, replace `dummy` with a real key. Otherwise any placeholder value is fine.\n\n## Using with Codex\n\nThis AI gateway can also power Codex.\n\n### Codex `config.toml` Reference\n\nAdd the following `[model_providers.copilot_api]` section to your Codex `~/.codex/config.toml`:\n\n```toml\nmodel_provider = \"copilot_api\"\nmodel_reasoning_summary = \"auto\"\nmodel_context_window = 272000\nmodel_auto_compact_token_limit = 244800\n\n[model_providers.copilot_api]\nname = \"OpenAI\"\nbase_url = \"http://localhost:4141\"\nenv_key = \"GITHUB_COPILOT_API_KEY\"\nrequires_openai_auth = true\nsupports_websockets = false\nwire_api = \"responses\"\nrequest_max_retries = 3\nstream_max_retries = 1\nstream_idle_timeout_ms = 300000\n\n[features]\nremote_compaction_v2 = true\n\n[analytics]\nenabled = false\n```\n\n> [!NOTE]\n> This configuration is specific to Codex and the GitHub Copilot provider. `name` must be set to `\"OpenAI\"`. It can help mitigate Codex local compact cache miss issues.\n> If you are using the codex provider, it is recommended to set `base_url` to `\"http://localhost:4141/codex\"`.\n\n## GPT Tool Search\n\nFor GPT Responses models such as `gpt-5.4+`, this AI gateway can expose Responses `tool_search` through a small MCP bridge. The same bridge can be used by Claude Code and opencode, as long as the client loads MCP servers and sends Anthropic Messages traffic through this gateway.\n\nDo not set Claude Code's native `ENABLE_TOOL_SEARCH` for GPT models. That flag enables Claude Code's own client-side tool search mode, and it may stop forwarding deferred tool definitions. This gateway needs the full tool definitions so it can keep the small always-loaded tool set eager and translate every other tool into Responses deferred namespaces.\n\nIf you install `tool-search@copilot-api-marketplace`, Claude Code receives this MCP bridge automatically and you can skip the manual Claude Code MCP setup below.\n\nAdd the tool search bridge to the MCP config used by Claude Code:\n\n```json\n{\n  \"mcpServers\": {\n    \"tool_search\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@jeffreycao/copilot-api@latest\", \"mcp\"]\n    }\n  }\n}\n```\n\nAdd the tool search bridge to the MCP config used by opencode:\n\n```json\n{\n  \"mcp\": {\n    \"tool_search\": {\n      \"type\": \"local\",\n      \"command\": [\"npx\", \"-y\", \"@jeffreycao/copilot-api@latest\", \"mcp\"]\n    }\n  }\n}\n```\n\nFor local development, use `bun` as the command and `[\"run\", \"./src/main.ts\", \"mcp\"]` as the args.\n\nInternally, the gateway now configures OpenAI Responses `tool_search` in client-executed mode. Deferred tools are still exposed as searchable namespaces, but the model is explicitly asked to return the exact deferred tool names it wants to load next.\n\nThe bridge uses direct tool selection, not query search. Its tool input is `names`, a comma-separated list of exact deferred tool names, for example `TaskList,TaskGet,mcp__fetch__fetch`.\n\n## Plugin Integrations\n\nPlugin integrations are available for Claude Code and opencode.\n\n#### Claude Code plugin integration (marketplace-based)\n\nThe Claude Code integration is packaged as two plugins:\n\n- `agent-inject` injects `__SUBAGENT_MARKER__...` on `SubagentStart`, so the gateway can infer `x-initiator: agent`.\n- `tool-search` registers the `tool_search` MCP bridge used for GPT Responses deferred tool loading.\n\n- Marketplace catalog in this repository: `.claude-plugin/marketplace.json`\n- Plugin sources in this repository: `plugin/claude/agent-inject`, `plugin/claude/tool-search`\n\nAdd the marketplace remotely:\n\n```sh\n/plugin marketplace add https://github.com/caozhiyuan/copilot-api.git\n```\n\nInstall the plugins from the marketplace:\n\n```sh\n/plugin install agent-inject@copilot-api-marketplace\n/plugin install tool-search@copilot-api-marketplace\n```\n\nAfter installation, `agent-inject` injects `__SUBAGENT_MARKER__...` on `SubagentStart`, and the gateway uses it to infer `x-initiator: agent`.\n\nThe `agent-inject` plugin also registers a `UserPromptSubmit` hook that returns `{\"continue\": true}`, and it can inject `SessionStart` reminder rules through environment variables:\n\n- `CLAUDE_PLUGIN_ENABLE_QUESTION_RULES=1` enables the two reminders about using the `question` tool automatically for Claude Code. Alternatively, you can add the same reminders manually in `CLAUDE.md`; see [CLAUDE.md or AGENTS.md Recommended Content](#claudemd-or-agentsmd-recommended-content).\n- `CLAUDE_PLUGIN_ENABLE_NO_BACKGROUND_AGENTS_RULE=1` enables the `run_in_background: true` avoidance reminder for agent hooks.\n\nThe `tool-search` plugin bundles the same MCP bridge described in [GPT Tool Search](#gpt-tool-search), so Claude Code users do not need to add the `tool_search` server manually when they install that plugin.\n\n#### Opencode plugin\n\nThe subagent marker producer is packaged as an opencode plugin located at `plugin/opencode/subagent-marker.js`.\n\n**Installation:**\n\nCopy the plugin file to your opencode plugins directory:\n\n```sh\n# Clone or download this repository, then copy the plugin\ncp plugin/opencode/subagent-marker.js ~/.config/opencode/plugins/\n```\n\nOr manually create the file at `~/.config/opencode/plugins/subagent-marker.js` with the plugin content.\n\n**Features:**\n\n- Tracks sub-sessions created by subagents\n- Automatically prepends a marker system reminder (`__SUBAGENT_MARKER__...`) to subagent chat messages\n- Sets `x-session-id` header for session tracking\n- Enables the gateway to infer `x-initiator: agent` for subagent-originated requests\n\nThe plugin hooks into `session.created`, `session.deleted`, `chat.message`, and `chat.headers` events to provide seamless subagent marker functionality.\n\n## Using the Usage Viewer\n\nAfter starting the server, a URL to the Copilot Usage Dashboard will be displayed in your console. This dashboard is a web interface for monitoring your API usage.\n\n1.  Start the server. For example, using npx:\n    ```sh\n    npx @jeffreycao/copilot-api@latest start\n    ```\n2.  The server will output a URL to the usage viewer. Copy and paste this URL into your browser. It will look something like this:\n    `http://localhost:4141/usage-viewer?endpoint=http://localhost:4141/usage`\n    - If you use the `start.bat` script on Windows, this page will open automatically.\n\nThe dashboard provides a user-friendly interface to view your Copilot usage data:\n\n> Token usage history requires Bun or Node.js >= 22.13.0. On Node.js < 22.13.0, the server runs normally but token usage storage is disabled.\n\n- **API Endpoint URL**: The dashboard is pre-configured to fetch data from your local server endpoint via a URL query parameter. You can manually switch this to any other compatible API endpoint.\n- **x-api-key Authentication**: If API Key authentication is enabled, you can provide the `x-api-key` request header. The key is persisted in the browser's local storage.\n- **Period Selector**: Choose from Day, Week, or Month time ranges. The URL query parameter updates automatically when you switch, making it easy to bookmark and share.\n- **Fetch Data**: Click the \"Refresh\" button to load or refresh the usage data. The dashboard also fetches data automatically on page load.\n- **Copilot Quotas**: View quota usage for services such as Chat and Completions via progress bars. Hover over a card to see used/remaining details.\n- **Token Usage Metric Cards**: See a summary of Total, Input, Output, Cache Read, Cache Write, Requests, and estimated cost for the current period.\n- **Trend Chart (Week / Month)**: An interactive line chart with model and metric filters. Click a data point to inspect the usage breakdown for a specific day.\n- **Model Breakdown Table**: A per-model summary of requests, input/output/cache tokens, and estimated cost for the selected period.\n- **Request Events (Paginated)**: A time-sorted list of request event records with pagination support, showing timestamps, models, request IDs, and token counts.\n- **Detailed Information**: See the full JSON response from the API for a detailed breakdown of all available usage statistics.\n- **URL-based Configuration**: You can also specify the API endpoint and period directly via `endpoint` and `period` query parameters. For example:\n  `http://localhost:4141/usage-viewer?endpoint=http://your-api-server/usage&period=week`\n\n### Usage Viewer Screenshot\n\n<p align=\"center\">\n  <img src=\"./docs/screenshots/usage-viewer.png\" alt=\"Copilot API usage viewer\" width=\"900\" />\n</p>\n\n## Command Structure\n\nCopilot API now uses a subcommand structure with these main commands:\n\n- `start`: Start the gateway server. If a GitHub token is available, the server starts with Copilot enabled. If no GitHub token is available, it starts in provider-only mode when at least one enabled provider exists; otherwise it guides you through provider setup.\n- `auth`: Run provider login or configuration without starting the server. Use it for GitHub Copilot login, Codex OAuth, or third-party provider API key setup.\n- `debug`: Display diagnostic information including version, runtime details, file paths, and authentication status. Useful for troubleshooting and support.\n\n## Command Line Options\n\n### Global Options\n\nThe following options can be used with any subcommand. When passing them before the subcommand, use the `--key=value` form:\n\n| Option            | Description                                            | Default | Alias |\n| ----------------- | ------------------------------------------------------ | ------- | ----- |\n| --api-home        | Path to the API home directory (sets COPILOT_API_HOME) | none    | none  |\n| --oauth-app       | OAuth app identifier (sets COPILOT_API_OAUTH_APP)      | none    | none  |\n| --enterprise-url  | Enterprise URL for GitHub (sets COPILOT_API_ENTERPRISE_URL) | none | none |\n\n### Start Command Options\n\nThe following command line options are available for the `start` command:\n\n| Option         | Description                                                                   | Default    | Alias |\n| -------------- | ----------------------------------------------------------------------------- | ---------- | ----- |\n| --port         | Port to listen on                                                             | 4141       | -p    |\n| --verbose      | Enable verbose logging                                                        | false      | -v    |\n| --github-token | Provide GitHub token directly (must be generated using the `auth` subcommand) | none       | -g    |\n| --claude-code  | Generate a command to launch Claude Code with Copilot API config              | false      | -c    |\n| --show-token   | Show GitHub and Copilot tokens on fetch and refresh                           | false      | none  |\n| --proxy-env    | Initialize proxy from environment variables                                   | false      | none  |\n\n### Auth Command Options\n\n| Option       | Description               | Default | Alias |\n| ------------ | ------------------------- | ------- | ----- |\n| --provider   | Provider to log in with or configure (`copilot`, `codex`, `opencode-go`, `deepseek`, `dashscope`, `openrouter`, or `custom`) | prompt | none |\n| --verbose    | Enable verbose logging    | false   | -v    |\n| --show-token | Show GitHub token on auth | false   | none  |\n\nUse `copilot-api auth login --provider copilot` only when you want to enable the GitHub Copilot provider. Copilot is not required for `codex` or third-party provider-only usage.\n\nUse `copilot-api auth login --provider deepseek`, `--provider dashscope`, `--provider openrouter`, or `--provider opencode-go` to add or update those common third-party providers from the CLI. DeepSeek prompts for masked `apiKey`, provider `type` (default `anthropic`), and `baseUrl` defaulting to `https://api.deepseek.com/anthropic`. DashScope prompts for masked `apiKey`, provider `type` (default `openai-compatible`), and prefilled `baseUrl`. OpenRouter prompts for masked `apiKey` and prefilled `baseUrl` only, and writes `type: \"anthropic\"`. OpenCode Go prompts for masked `apiKey` and prefilled `baseUrl` only, and writes `type: \"openai-compatible\"` (baseUrl `https://opencode.ai/zen/go`). After a provider is configured and enabled, `copilot-api start` can run without any GitHub token.\n\nUse `copilot-api auth login --provider custom` to add or update another third-party provider from the CLI. The command prompts for the provider name, supported type (`anthropic`, `openai-compatible`, or `openai-responses`), `baseUrl`, masked `apiKey`, and `authType`; `authType` may be left as the type default or set to `x-api-key` / `authorization`.\n\n### Debug Command Options\n\n| Option | Description               | Default | Alias |\n| ------ | ------------------------- | ------- | ----- |\n| --json | Output debug info as JSON | false   | none  |\n\n## Configuration (config.json)\n\n- **Location:** `~/.local/share/copilot-api/config.json` (Linux/macOS) or `%USERPROFILE%\\.local\\share\\copilot-api\\config.json` (Windows).\n- **Default shape:**\n  ```json\n  {\n    \"auth\": {\n      \"apiKeys\": [],\n      \"adminApiKey\": \"<auto-generated-on-startup>\"\n    },\n    \"providers\": {},\n    \"modelMappings\": {},\n    \"extraPrompts\": {\n      \"gpt-5-mini\": \"<built-in exploration prompt>\"\n    },\n    \"smallModel\": \"gpt-5-mini\",\n    \"contextManagement\": {\n      \"messages\": true,\n      \"responses\": false\n    },\n    \"modelResponsesApiCompactThresholds\": {\n      \"gpt-5.4\": 217600,\n      \"gpt-5.5\": 217600,\n      \"gpt-5.6-sol\": 231200,\n      \"gpt-5.6-terra\": 231200,\n      \"gpt-5.6-luna\": 231200\n    },\n    \"modelReasoningEfforts\": {\n      \"gpt-5-mini\": \"low\"\n    },\n    \"useMessagesApi\": true,\n    \"useResponsesApiWebSocket\": true,\n    \"useResponsesApiWebSearch\": true,\n    \"messageApiWebSearchModel\": \"gpt-5-mini\"\n  }\n  ```\n- **auth.apiKeys:** API keys used for request authentication on non-admin routes. Supports multiple keys for rotation. Requests can authenticate with either `x-api-key: <key>` or `Authorization: Bearer <key>`. If empty or omitted, authentication for non-admin routes is disabled.\n- **auth.adminApiKey:** Single admin key used only for `/admin/*` routes. If missing, the server generates a random key at startup and writes it back to `config.json`. Requests use the same `x-api-key` or `Authorization: Bearer` headers, but regular `auth.apiKeys` never grant access to `/admin/*`.\n- **modelMappings:** Exact `sourceModel -> targetModel` rewrites shared by top-level `POST /v1/messages`, `POST /v1/messages/count_tokens`, `POST /v1/responses`, and `POST /v1/chat/completions` requests. Omit it or leave it as `{}` to disable rewrites. Both the source and target must be non-empty strings. Targets can be regular model IDs or `provider/model` aliases such as `dashscope/qwen3.6-plus`, and the rewrite happens before provider alias parsing. These mappings are not split per interface. The admin endpoints `GET/POST /admin/config/model-mappings` read and update only this field.\n- **extraPrompts:** Map of `model -> prompt` appended to the first system prompt when translating Anthropic-style requests to Responses API. Use this to inject guardrails or guidance per model. Missing default entries are auto-added without overwriting your custom prompts. For GPT-5.3+ models (e.g. `gpt-5.3-codex`, `gpt-5.4`, `gpt-5.5`), a built-in commentary prompt is used as fallback when not explicitly configured. The built-in prompts enable phase-aware commentary, which lets the model emit a short user-facing progress update before tools or deeper reasoning.\n- **providers:** Global upstream provider map. Each provider key (for example `dashscope`) becomes a route prefix (`/dashscope/v1/messages`). Supports `type: \"anthropic\"`, `type: \"openai-compatible\"`, and `type: \"openai-responses\"`. Top-level clients can also use `model: \"dashscope/model-id\"` with `/v1/messages`, `/v1/messages/count_tokens`, `/v1/responses`, and `/v1/chat/completions`; the gateway strips the `dashscope/` prefix before forwarding upstream. `openai-compatible` providers support both chat and Messages flows: `/v1/chat/completions` is proxied to upstream `/v1/chat/completions`, while `/v1/messages` and `/:provider/v1/messages` are translated to upstream chat completions and translated back to Anthropic Messages responses. `GET /v1/models` aggregates enabled provider models with `provider/model-id` IDs; use `GET /dashscope/v1/models` for a single provider's raw model list.\n  - `enabled` defaults to `true` if omitted.\n  - `baseUrl` should be provider API base URL without the final endpoint. For Anthropic providers, omit `/v1/messages`; for OpenAI-compatible providers, omit `/v1/chat/completions`; for OpenAI Responses providers, omit `/v1/responses`.\n  - `apiKey` is used as the upstream credential value and is required for regular providers.\n  - `authType` (optional): Controls how `apiKey` is sent upstream. Supports `x-api-key` and `authorization` for regular providers. Anthropic providers default to `x-api-key`; OpenAI-compatible and OpenAI Responses providers default to `authorization`. When set to `authorization`, the proxy sends `Authorization: Bearer <apiKey>`. `oauth2` is reserved for the built-in `codex` provider and is written automatically by `auth login --provider codex`.\n  - `pricingCurrency` (optional): Provider-level currency used for token cost calculation, for example `USD` or `CNY`. Quick providers default to `CNY` for DashScope and DeepSeek, and `USD` for Codex/OpenRouter. Costs are grouped by currency and are not exchange-rate converted.\n  - `models` (optional): Per-model configuration map. Each key is a model ID (matching the model name in requests), and the value is:\n    - `temperature` (optional): Default temperature value used when the request does not specify one.\n    - `topP` (optional): Default top_p value used when the request does not specify one.\n    - `topK` (optional): Default top_k value used when the request does not specify one.\n    - `extraBody` (optional): Dynamic fields merged into the upstream request body for that model. Request body fields with the same name take precedence. OpenAI-compatible providers can use this for fields such as `enable_thinking`, `preserve_thinking`, `reasoning_effort`. `thinking_budget` is a special OpenAI-compatible provider override: when configured in `extraBody`, it is forced after Anthropic `thinking.budget_tokens` translation and overrides the request-derived budget. For providers whose name is `dashscope` or whose `baseUrl` contains `aliyuncs.com`, the request-derived `thinking_budget` (from Anthropic `thinking.budget_tokens`) is forwarded upstream; for other OpenAI-compatible providers the request-derived `thinking_budget` is stripped, while an `extraBody` `thinking_budget` is still honored. For DashScope providers, `preserve_thinking` defaults to `true` when not explicitly set in `extraBody` or the request body.\n    - `pricing` (optional): Per-model token prices, in the provider `pricingCurrency`, per 1M tokens. Supported fields are `input`, `output`, `cachedInput` (implicit cache read), `explicitCachedInput` (explicit cache read), and `cacheCreationInput`. Use `tiers` with `maxInputTokens` for input-size tiered pricing.\n    - `contextCache` (optional): Defaults to `true` for providers whose name is `dashscope` or whose `baseUrl` contains `aliyuncs.com`; defaults to `false` for other OpenAI-compatible providers. This enables Alibaba Cloud Model Studio/DashScope explicit context cache by injecting `cache_control: { \"type\": \"ephemeral\" }` on up to 4 content blocks using the Context Cache format. The cache breakpoint strategy matches opencode's main provider flow: the first 2 system messages plus the last 2 non-system messages. Marked string content is converted to text content part arrays for `system` / `user` / `assistant` / `tool` messages; existing array content is marked on the last part. Set this to `false` when the model already supports implicit caching, or when the upstream does not accept this explicit-cache extension field. Set this to `true` for non-DashScope providers that support the same explicit-cache extension. Applied on both `/v1/messages` and `/v1/chat/completions` routes.\n    - `supportPdf` (optional): Controls whether the model supports PDF/document content. Defaults to `false`; unsupported PDFs are converted to a text notice. Set it to `true` to send PDF/document blocks as OpenAI Chat Completions file parts.\n    - `toolContentSupportType` (optional): Tool result content capabilities for that model, as an array of `array`, `image`, and `pdf`. Provider routes default to string-only tool content when omitted. If `supportPdf` is `true` but this list does not include `pdf`, file parts in tool results are moved to user role messages. This provider default does not change the Copilot main flow, which continues to support array + image and not PDF.\n    - `type` (optional): Per-model override of the provider protocol type. Supports `anthropic`, `openai-compatible`, and `openai-responses`. When set, the provider's `/v1/messages` route uses this model's type instead of the provider-level type for request routing, auth header resolution, and upstream endpoint selection. This is useful for providers like OpenCode Go whose upstream supports both OpenAI-compatible and Anthropic Messages APIs for different models. When the type is overridden, the auth header is resolved from the overridden type's default (Anthropic defaults to `x-api-key`; OpenAI-compatible/Responses default to `authorization`).\n\n  Example DashScope model settings:\n  ```json\n  {\n    \"providers\": {\n      \"dashscope\": {\n        \"type\": \"openai-compatible\",\n        \"enabled\": true,\n        \"baseUrl\": \"https://dashscope.aliyuncs.com/compatible-mode\",\n        \"apiKey\": \"sk-your-dashscope-key\",\n        \"pricingCurrency\": \"CNY\",\n        \"models\": {\n          \"qwen3.7-plus\": {\n            \"temperature\": 1,\n            \"topP\": 0.95,\n            \"topK\": 20,\n            \"extraBody\": {\n              \"preserve_thinking\": true\n            }\n          },\n          \"glm-5.1\": {\n            \"temperature\": 0.7,\n            \"topP\": 0.95,\n            \"contextCache\": true,\n            \"pricing\": {\n              \"tiers\": [\n                {\n                  \"maxInputTokens\": 32000,\n                  \"input\": 6,\n                  \"cachedInput\": 1.2,\n                  \"explicitCachedInput\": 0.6,\n                  \"cacheCreationInput\": 7.5,\n                  \"output\": 24\n                },\n                {\n                  \"maxInputTokens\": 200000,\n                  \"input\": 8,\n                  \"cachedInput\": 1.6,\n                  \"explicitCachedInput\": 0.8,\n                  \"cacheCreationInput\": 10,\n                  \"output\": 28\n                }\n              ]\n            },\n            \"extraBody\": {\n              \"preserve_thinking\": true\n            }\n          }\n        }\n      }\n    }\n  }\n  ```\n  Built-in token prices cover Codex GPT models in USD, DashScope `qwen3.7-max`, `qwen3.7-plus`, `glm-5.1`, `glm-5.2` in CNY, DeepSeek `deepseek-v4-flash`, `deepseek-v4-pro`, `deepseek-chat`, `deepseek-reasoner` in CNY, and OpenCode Go models (`glm-5.2`, `grok-4.5`, `deepseek-v4-flash`, `deepseek-v4-pro`, `kimi-k2.7-code`, `kimi-k3`, `mimo-v2.5`, `mimo-v2.5-pro`, `qwen3.7-plus`, `qwen3.7-max`, `minimax-m2.5`, `minimax-m3`) in USD. User `pricing` entries override built-ins. For DashScope, cached tokens are charged as explicit cache reads when the upstream usage includes `cache_creation_input_tokens`; otherwise `cachedInput` is used as the implicit cache read price. For DeepSeek, `prompt_cache_hit_tokens` map to cached input and `prompt_cache_miss_tokens` map to regular input.\n- **smallModel:** Fallback model used for tool-less warmup messages (e.g., Claude Code probe requests); defaults to gpt-5-mini.\n- **contextManagement:** Controls whether the proxy adds Responses API `context_management` compaction instructions. `messages` applies when Anthropic-style `/v1/messages` requests are translated to Responses API, including `openai-responses` provider message routes, and defaults to `true`. `responses` applies to native `/v1/responses` traffic, including `provider/model` aliases and the built-in `codex` provider, and defaults to `false`. Enable `responses` only after checking that your client supports context management compaction. When enabled, the request includes `context_management` in the body and keeps only the latest compaction carrier on follow-up turns. **Note:** Context management is forcibly disabled for GPT-5.6 and above models (e.g. `gpt-5.6-sol`, `gpt-5.6-terra`, `gpt-5.6-luna`) because enabling it breaks prompt cache hits on those models. This override takes precedence over the `contextManagement` and `modelResponsesApiCompactThresholds` settings.\n- **modelResponsesApiCompactThresholds:** Per-model Responses API `compact_threshold` overrides used when the proxy adds `context_management`. These values take precedence over the fallback threshold from `resolveResponsesCompactThreshold` (`max_prompt_tokens * ratio`, or the default fallback). Defaults set `gpt-5.4` and `gpt-5.5` to `217600` (`272000 * 0.8`), and `gpt-5.6-sol`, `gpt-5.6-terra`, `gpt-5.6-luna` to `231200` (`272000 * 0.85`). Models not listed continue to use the normal fallback logic.\n- **modelReasoningEfforts:** Per-model fallback reasoning effort for `/v1/messages` requests. It is used only when the request does not provide `output_config.effort`.\n  - **Priority:** request `output_config.effort` > `modelReasoningEfforts[model]` > built-in default (`xhigh` for GPT-5.3+ models, otherwise `high`).\n  - **Forwarding:** the resolved value remains `output_config.effort` for the Copilot native Messages API and becomes `reasoning.effort` when translated to the Responses API.\n  - **Configuration values:** `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`.\n- **useMessagesApi:** When `true`, Claude-family models that support Copilot's native `/v1/messages` endpoint will use the Messages API; otherwise they fall back to `/chat/completions`. Set to `false` to disable Messages API routing and always use `/chat/completions`. Defaults to `true`.\n- **useResponsesApiWebSocket:** When `true`, Responses API requests use Copilot's websocket transport for models that advertise `ws:/responses`; models that only advertise `/responses` continue to use HTTP. Set to `false` to disable websocket routing and use HTTP `/responses` whenever the selected model supports it. Defaults to `true`. If the Responses API WebSocket gets closed, it is usually caused by your own network. If you are using a VPN, try switching to a different node.\n- **useResponsesApiWebSearch:** When `true`, the server keeps Responses API tools with `type: \"web_search\"` and forwards them upstream. Set to `false` to strip those tools from `/responses` payloads. Defaults to `true`.\n- **messageApiWebSearchModel:** Global fallback model used when a top-level Copilot `/v1/messages` request contains only the server-side `web_search` tool. Defaults to `gpt-5-mini`. If the value is a `provider/model` alias, the request is routed into that provider's Messages API path with the provider prefix stripped. For Copilot GPT models, web search runs through `/responses`. Mixed `web_search` plus custom tools are not supported and the server-side `web_search` tool is stripped.\n- **claudeTokenMultiplier:** Multiplier applied to the fallback GPT-tokenizer estimate for Claude `/v1/messages/count_tokens` requests. Defaults to `1.15`. Increase it if your client is still compacting too late. This setting is only used when the proxy is estimating Claude tokens locally; if `anthropicApiKey` is configured and Anthropic token counting succeeds, the exact Anthropic count is returned instead.\n- **anthropicApiKey:** Anthropic API key used to forward Claude `/v1/messages/count_tokens` requests to Anthropic's real token counting endpoint, which returns exact counts instead of GPT tokenizer estimates. Can also be set via the `ANTHROPIC_API_KEY` environment variable. If not set, or if the upstream call fails, token counting falls back to local GPT tokenizer estimation controlled by `claudeTokenMultiplier`.\n\nEdit this file to customize prompts or swap in your own fast model. Restart the server (or rerun the command) after changes so the cached config is refreshed.\n\n## API Authentication\n\n- **Protected non-admin routes:** All routes except `/`, `/usage-viewer`, and `/usage-viewer/` require authentication when `auth.apiKeys` is configured and non-empty.\n- **Admin routes:** All `/admin/*` routes require `auth.adminApiKey`. If it is missing, the server generates one at startup and persists it to `config.json` before serving requests.\n- **Allowed auth headers:**\n  - `x-api-key: <your_key>`\n  - `Authorization: Bearer <your_key>`\n- **CORS preflight:** `OPTIONS` requests are always allowed.\n- **When no regular keys are configured:** Non-admin routes continue to allow requests. This does not apply to `/admin/*`, which only accepts `auth.adminApiKey`.\n\nExample request for a regular protected route:\n\n```sh\ncurl http://localhost:4141/v1/models \\\n  -H \"x-api-key: your_api_key\"\n```\n\nExample request for an admin route:\n\n```sh\ncurl http://localhost:4141/admin/config/model-mappings \\\n  -H \"x-api-key: your_admin_api_key\"\n```\n\n## API Endpoints\n\nThe server exposes several OpenAI- and Anthropic-compatible endpoints. Requests can target GitHub Copilot, the built-in `codex` provider, or configured providers depending on the selected model and `provider/model` alias.\n\n### OpenAI Compatible Endpoints\n\nThese endpoints mimic the OpenAI API structure.\n\n| Endpoint                    | Method | Description                                                      |\n| --------------------------- | ------ | ---------------------------------------------------------------- |\n| `POST /v1/responses`        | `POST` | OpenAI Most advanced interface for generating model responses. Supports `provider/model` aliases for `openai-responses` providers. |\n| `POST /v1/chat/completions` | `POST` | Creates a model response for the given chat conversation. Supports `provider/model` aliases for `openai-compatible` providers and can be used without Copilot when the target provider is configured. |\n| `GET /v1/models`            | `GET`  | Lists Copilot models plus enabled provider models using `provider/model-id` IDs. Requests from Codex clients (`User-Agent` beginning with `codex`) are forwarded to the Codex Models upstream. |\n| `POST /v1/embeddings`       | `POST` | Creates an embedding vector representing the input text.         |\n\n### Codex Backend Proxy Endpoints\n\nThese endpoints require an active Codex login. Each endpoint is available both without a version prefix and under `/v1`.\n\n| Endpoint | Method | Description |\n| --- | --- | --- |\n| `POST /alpha/search`<br>`POST /v1/alpha/search` | `POST` | Transparently forwards the JSON body and query parameters to the Codex Alpha Search upstream. |\n| `POST /images/generations`<br>`POST /v1/images/generations` | `POST` | Forwards a JSON image generation request to the Codex Images upstream. When the request omits `Content-Type`, the gateway defaults it to `application/json`. |\n| `POST /images/edits`<br>`POST /v1/images/edits` | `POST` | Forwards an image edit request to the Codex Images upstream. Send this request as `multipart/form-data` and let the HTTP client generate the `boundary`; the gateway preserves the incoming content type and streams the upload body. |\n\nFor every endpoint above, the gateway replaces client authorization and account headers with the active Codex login, preserves query parameters and compatible request headers, and returns the upstream status, headers, and body.\n\n### Anthropic Compatible Endpoints\n\nThese endpoints are designed to be compatible with the Anthropic Messages API. Provider-scoped models, Responses, alpha-search, and images routes accept both unversioned and `/v1` paths; Messages routes remain under `/v1`.\n\n| Endpoint                         | Method | Description                                                  |\n| -------------------------------- | ------ | ------------------------------------------------------------ |\n| `POST /v1/messages`              | `POST` | Creates a model response for a given conversation. Supports `provider/model` aliases for configured providers, including translation through `openai-compatible` providers. |\n| `POST /v1/messages/count_tokens` | `POST` | Calculates the number of tokens for a given set of messages. Supports `provider/model` aliases for configured providers. |\n| `POST /:provider/v1/messages`       | `POST` | Proxies Anthropic Messages requests to the configured Anthropic provider, translates them through an OpenAI-compatible provider, or translates them through an OpenAI Responses provider. |\n| `GET /:provider/models`<br>`GET /:provider/v1/models` | `GET` | Proxies model listing requests to the configured provider. For `codex`, returns the built-in catalog by default; Codex clients (`User-Agent` starting with `codex`) are forwarded to the Codex Models upstream. |\n| `POST /:provider/v1/messages/count_tokens` | `POST` | Calculates tokens locally for provider route requests. |\n| `POST /:provider/responses`<br>`POST /:provider/v1/responses` | `POST` | Proxies OpenAI Responses requests to a configured `openai-responses` provider (including `codex`). |\n| `POST /:provider/alpha/search`<br>`POST /:provider/v1/alpha/search` | `POST` | Proxies alpha-search requests. For `codex`, forwards to the Codex Alpha Search upstream; for other providers, forwards to `{baseUrl}/v1/alpha/search`. |\n| `POST /:provider/images/generations`<br>`POST /:provider/v1/images/generations` | `POST` | Proxies image generation. For `codex`, uses the Codex Images upstream; for other providers, forwards to `{baseUrl}/v1/images/generations` (15-minute timeout). |\n| `POST /:provider/images/edits`<br>`POST /:provider/v1/images/edits` | `POST` | Proxies image edits. For `codex`, uses the Codex Images upstream; for other providers, forwards multipart/streamed bodies to `{baseUrl}/v1/images/edits` (15-minute timeout). |\n\n### Usage Monitoring Endpoints\n\nNew endpoints for monitoring your Copilot usage and quotas.\n\n| Endpoint     | Method | Description                                                  |\n| ------------ | ------ | ------------------------------------------------------------ |\n| `GET /usage` | `GET`  | Get detailed Copilot usage statistics and quota information. |\n| `GET /token` | `GET`  | Get the current Copilot token being used by the API.         |\n\n### Admin / Configuration Endpoints\n\nThese endpoints are reserved for local administrative actions and only accept `auth.adminApiKey`.\n\n| Endpoint                              | Method | Description                                                                 |\n| ------------------------------------- | ------ | --------------------------------------------------------------------------- |\n| `GET /admin/config/model-mappings`    | `GET`  | Returns the current `config.json` path and the active `modelMappings` map.  |\n| `POST /admin/config/model-mappings`   | `POST` | Updates only the `modelMappings` field in `config.json` and returns it back. |\n\n## Example Usage\n\nCommon `npx` commands:\n\n```sh\n# Start the gateway\nnpx @jeffreycao/copilot-api@latest start\n\n# Start on a custom port with verbose logging\nnpx @jeffreycao/copilot-api@latest start --port 8080 --verbose\n\n# Run the auth flow\nnpx @jeffreycao/copilot-api@latest auth login\n\n# Configure a third-party provider, then run without GitHub Copilot\nnpx @jeffreycao/copilot-api@latest auth login --provider dashscope\nnpx @jeffreycao/copilot-api@latest start\n\n# Print debug information as JSON\nnpx @jeffreycao/copilot-api@latest debug --json\n\n# Run the published CLI with Bun instead of Node.js\nbunx --bun @jeffreycao/copilot-api@latest start\n```\n\nOpenAI-compatible provider examples after configuring `dashscope`:\n\n```sh\ncurl http://localhost:4141/v1/chat/completions \\\n  -H \"content-type: application/json\" \\\n  -d '{\"model\":\"dashscope/qwen3.6-plus\",\"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]}'\n\ncurl http://localhost:4141/dashscope/v1/messages \\\n  -H \"content-type: application/json\" \\\n  -d '{\"model\":\"qwen3.6-plus\",\"max_tokens\":1024,\"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]}'\n```\n\n## Usage Tips\n\n### CLAUDE.md or AGENTS.md Recommended Content\n\nTo add these reminders manually, include the following in `CLAUDE.md` for Claude Code, or `AGENTS.md` for opencode/codex:\n\n```\n- Prohibited from directly asking questions to users, MUST use question tool.\n- Once you can confirm that the task is complete, MUST use question tool to make user confirm. The user may respond with feedback if they are not satisfied with the result, which you can use to make improvements and try again, after try again, MUST use question tool to make user confirm again.\n```\n"}, "d5b3aa096a08d14e6f5743efbd6b44c2bce6b810": {"t": 1785765539.6121495, "n": 50850, "h": "03e57ef2131d611f", "c": "# Copilot API Proxy\n\nEnglish | [简体中文](./README.zh-CN.md)\n\n## Important Notes\n\n> [!IMPORTANT]\n> **Before using, please be aware of the following:**\n>\n> 1. **Claude Code configuration:** When using with Claude Code, please configure the model ID as `claude-opus-4-8`. Example claude `settings.json` see [Manual Configuration with `settings.json`](#manual-configuration-with-settingsjson). \n>\n> 2. **Built-in `copilot`, `codex` and third-party providers:** Run `npx @jeffreycao/copilot-api@latest auth` and choose `copilot`, `codex`, `deepseek`, `custom`, or other providers.\n>\n> 3. **Note:** See [GitHub Copilot Security Notice](./NOTICE.md#github-copilot-security-notice) for the warning removed from the README header.\n\n---\n\n## Project Overview\n\nA small AI gateway that can use GitHub Copilot, the built-in `codex` provider, or configured third-party providers such as DashScope. GitHub Copilot is optional: if no GitHub token is available, the server can still start in provider-only mode as long as at least one enabled provider is configured.\n\nThe gateway exposes OpenAI- and Anthropic-compatible APIs from one local endpoint, so tools like [Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview), OpenCode, Codex, and OpenAI-compatible clients can share the same local server.\n\nOn the GitHub Copilot path, the gateway prefers Copilot's native Anthropic-style Messages API when available, preserving more Claude-native behavior for tool-heavy workflows.\n\n## Features\n\n- **OpenAI and Anthropic compatibility**: Serve `/v1/responses`, `/v1/chat/completions`, `/v1/models`, `/v1/embeddings`, and `/v1/messages` from one local gateway.\n- **Copilot is optional**: Use GitHub Copilot when credentials are present, or run the server with only configured providers.\n- **One gateway for Copilot, `codex`, and external providers**: Route GitHub Copilot, the built-in `codex` provider, and configured third-party providers behind the same endpoint.\n- **Standalone third-party providers**: Configure providers such as DashScope, DeepSeek, OpenRouter, or a custom provider and start the gateway without a GitHub Copilot login.\n- **OpenAI-compatible providers on chat and Messages APIs**: `openai-compatible` providers can serve top-level `/v1/chat/completions` through `model: \"provider/model\"` and Anthropic-style `/v1/messages` through request/response translation.\n- **Agent-friendly Claude handling on Copilot**: Prefer native `/v1/messages` when available, preserve Claude-style tool flows, support Anthropic beta features, Claude WebSearch through Responses-capable models, and keep subagent/session markers intact.\n- **Claude Code and OpenCode integration**: Works with Claude Code and OpenCode, including direct Anthropic-compatible usage through `@ai-sdk/anthropic`.\n- **Flexible auth and deployment options**: Supports interactive login or direct tokens, individual/business/enterprise plans, GitHub Enterprise, opencode OAuth, and custom data directories.\n- **Multi-provider routing**: Expose provider-specific `/:provider/...` routes or use `model: \"provider/model\"` on the top-level API.\n\n## Prerequisites\n\n- Bun (>= 1.2.x)\n- Node.js if you plan to run the published CLI with `npx`\n- GitHub account with Copilot subscription only if you want to use the GitHub Copilot provider\n- An API key or OAuth login for at least one configured provider if you want to run without GitHub Copilot\n\n## Installation\n\nTo install dependencies, run:\n\n```sh\nbun install\n```\n\nTo start the server directly from source:\n\n```sh\nbun run start start\n```\n\n## Running from Source\n\nThe project can be run from source in several ways:\n\n### Development Mode\n\n```sh\nbun run dev start\n```\n\n### Production Mode\n\n```sh\nbun run start start\n```\n\n## Using with npx\n\nYou can run the project directly using npx:\n\n> [!IMPORTANT]\n> Token usage storage uses Node's built-in `node:sqlite` module when running with `npx`. It is enabled on Node.js >= 22.13.0. On Node.js < 22.13.0, the CLI still starts, but token usage storage is disabled.\n>\n> If you want token usage storage without upgrading Node.js, run the published CLI with Bun instead: `bunx --bun @jeffreycao/copilot-api@latest start`.\n\n```sh\nnpx @jeffreycao/copilot-api@latest start\n```\n\nWith options:\n\n```sh\nnpx @jeffreycao/copilot-api@latest start --port 8080\n```\n\nFor authentication or provider configuration only:\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth\n```\n\nTo run without GitHub Copilot, configure at least one provider first, then start the server normally:\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth login --provider dashscope\nnpx @jeffreycao/copilot-api@latest start\n```\n\n## Using with Docker\n\nBuild the image:\n\n```sh\ndocker build -t copilot-api .\n```\n\nRun the container with a bind mount so auth data survives restarts:\n\n```sh\nmkdir -p ./copilot-data\ndocker run -p 4141:4141 -v $(pwd)/copilot-data:/root/.local/share/copilot-api copilot-api\n```\n\nThis stores GitHub auth data, provider config, and other gateway state in `./copilot-data` on the host, mapped to `/root/.local/share/copilot-api` in the container.\n\nOr pass a GitHub token directly:\n\n```sh\ndocker run -p 4141:4141 -e GH_TOKEN=your_github_token_here copilot-api\n```\n\n## Electron Desktop App\n\nIf you prefer a GUI, this repository also includes an Electron desktop app in `desktop/`. It supports GitHub Copilot sign-in, OpenAI Codex OAuth, and API-key configuration for DeepSeek, DashScope, OpenRouter, or a custom provider. After authorization or provider configuration, it can start and stop the local proxy with one click and shows the local endpoint, auth header, available models, usage, and logs in the app.\n\nThe settings screen also exposes `OAuth App`, `API Home`, `Enterprise URL`, verbose logging, and minimize-to-tray. Desktop packages are published in GitHub Releases:\n\nhttps://github.com/caozhiyuan/copilot-api/releases\n\nDownload the installer for your platform, authorize or configure a provider inside the app, choose a port, start the server, then point your client at the local endpoint shown in the app. Packaged desktop builds use the bundled Electron runtime, so normal desktop usage does not require installing Node.js separately. Token usage history is enabled when that bundled runtime supports SQLite.\n\nThe desktop app's Advanced Config page reads and writes the shared model mappings through `GET/POST /admin/config/model-mappings`. The same mappings apply across `POST /v1/messages`, `POST /v1/messages/count_tokens`, `POST /v1/responses`, and `POST /v1/chat/completions` instead of being split per interface. It uses `auth.adminApiKey` instead of the regular `auth.apiKeys`, and the app reads that key directly from `config.json` after the server has generated it on startup.\n\n### Desktop App Screenshots\n\nMain dashboard, token usage breakdown in the bundled Electron app:\n\n<p align=\"center\">\n  <img src=\"./docs/screenshots/desktop-dashboard.png\" alt=\"Copilot API desktop app dashboard\" width=\"49%\" />\n  <img src=\"./docs/screenshots/desktop-token-usage.png\" alt=\"Copilot API desktop app token usage view\" width=\"49%\" />\n</p>\n\n## Using with Claude Code\n\nThis AI gateway can be used to power [Claude Code](https://docs.anthropic.com/en/claude-code), an experimental conversational AI assistant for developers from Anthropic.\n\nThere are two ways to configure Claude Code to use this AI gateway:\n\n### Interactive Setup with `--claude-code` flag\n\nTo get started, run the `start` command with the `--claude-code` flag:\n\n```sh\nnpx @jeffreycao/copilot-api@latest start --claude-code\n```\n\nYou will no longer be prompted to pick models manually. The gateway automatically detects the latest available model for each Claude Code size tier — opus maps to the newest Opus model, sonnet to the newest Sonnet model, and haiku to the newest Haiku model — and generates a command that sets `ANTHROPIC_DEFAULT_OPUS_MODEL`, `ANTHROPIC_DEFAULT_SONNET_MODEL`, and `ANTHROPIC_DEFAULT_HAIKU_MODEL` accordingly. Any tier without a matching model available is omitted. The command is copied to your clipboard and sets the environment variables needed for Claude Code to use the gateway.\n\nPaste and run this command in a new terminal to launch Claude Code.\n\n### Manual Configuration with `settings.json`\n\nAlternatively, you can configure Claude Code by creating a `.claude/settings.json` file in your project's root directory. This file should contain the environment variables needed by Claude Code. This way you don't need to run the interactive setup every time.\n\nHere is an example `.claude/settings.json` file:\n\n```json\n{\n  \"env\": {\n    \"ANTHROPIC_BASE_URL\": \"http://localhost:4141\",\n    \"ANTHROPIC_AUTH_TOKEN\": \"dummy\",\n    \"ANTHROPIC_MODEL\": \"gpt-5.6-sol[1m]\",\n    \"ANTHROPIC_DEFAULT_SONNET_MODEL\": \"gpt-5.6-sol[1m]\",\n    \"ANTHROPIC_DEFAULT_HAIKU_MODEL\": \"gpt-5.6-luna[1m]\",\n    \"CLAUDE_CODE_AUTO_COMPACT_WINDOW\": \"272000\",\n    \"CLAUDE_CODE_USE_VERTEX\": \"0\",\n    \"CLAUDE_CODE_USE_BEDROCK\": \"0\",\n    \"DISABLE_NON_ESSENTIAL_MODEL_CALLS\": \"1\",\n    \"CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC\": \"1\",\n    \"CLAUDE_CODE_ATTRIBUTION_HEADER\": \"0\",\n    \"CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION\": \"false\",\n    \"CLAUDE_CODE_DISABLE_TERMINAL_TITLE\": \"true\",\n    \"CLAUDE_CODE_ENABLE_AWAY_SUMMARY\": \"0\"\n  },\n  \"alwaysThinkingEnabled\": true,\n  \"effortLevel\": \"xhigh\",\n  \"showThinkingSummaries\": true\n}\n```\n\n- Replace `ANTHROPIC_MODEL`, `ANTHROPIC_DEFAULT_OPUS_MODEL`, `ANTHROPIC_DEFAULT_SONNET_MODEL`, and `ANTHROPIC_DEFAULT_HAIKU_MODEL` according to your needs. After configuration, please install the claude code plugin [Plugin Integrations](#plugin-integrations).  \n- If you are using the codex provider, it is recommended **not** to configure the model name in the `codex/xxx` format (e.g. `codex/gpt-5.6-sol`). Claude Code treats the `codex/` prefix as a special pattern and applies degraded behavior — for example, it strips all previously returned thinking blocks on every request. Use the plain model name (e.g. `gpt-5.6-sol`) instead, and add a `modelMappings` entry in `config.json` to route it back to the codex provider:\n  ```json\n  \"modelMappings\": {\n    \"gpt-5.6-sol\": \"codex/gpt-5.6-sol\",\n    \"gpt-5.6-terra\": \"codex/gpt-5.6-terra\",\n    \"gpt-5.6-luna\": \"codex/gpt-5.6-luna\"\n  },\n  ```\n- Setting CLAUDE_CODE_ATTRIBUTION_HEADER to 0 can prevent Claude code from adding billing and version information in system prompts, thereby avoiding prompt cache invalidation.\n- Turning off CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION and CLAUDE_CODE_ENABLE_AWAY_SUMMARY can prevent quota from being consumed unnecessarily.\n- Claude Code WebSearch is supported for pure search requests. For Copilot, keep the global `messageApiWebSearchModel` set to a Responses-capable GPT model or a `provider/model` alias. For provider routes, use a native Anthropic provider or an `openai-responses` provider. Add `WebSearch` to `permissions.deny` only if you want to forbid this traffic.\n- If using a non-Claude model, do not enable ENABLE_TOOL_SEARCH. If using the Claude model, can enable ENABLE_TOOL_SEARCH. The current Claude Code uses the client tool search mode. In this mode, loading defer tools requires an additional request each time.\n- `CLAUDE_CODE_AUTO_COMPACT_WINDOW`: Set the context capacity in tokens used for auto-compaction calculations. Defaults to the model's context window: 200K for standard models or 1M for extended context models. Use a lower value like `500000` on a 1M model (e.g., `claude-opus-4-6[1m]`) to treat the window as 500K for compaction purposes. The value is capped at the model's actual context window. `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` is applied as a percentage of this value. Setting this variable decouples the compaction threshold from the status line's `used_percentage`, which always uses the model's full context window.\n\nYou can find more options here: [Claude Code settings](https://docs.anthropic.com/en/docs/claude-code/settings#environment-variables)\n\nYou can also read more about IDE integration here: [Add Claude Code to your IDE](https://docs.anthropic.com/en/docs/claude-code/ide-integrations)\n\n## Using with OpenCode\n\nOpenCode already has a direct GitHub Copilot provider. Use this section when you want OpenCode to point at this AI gateway through `@ai-sdk/anthropic` and reuse the agent behaviors described earlier in this README.\n\n### Minimal setup\n\nStart the AI gateway with the OpenCode OAuth app:\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth --oauth-app=opencode\nnpx @jeffreycao/copilot-api@latest start\n```\n\nThen point OpenCode at the gateway with `@ai-sdk/anthropic`.\n\nExample `~/.config/opencode/opencode.json`:\n\n```json\n{\n  \"$schema\": \"https://opencode.ai/config.json\",\n  \"provider\": {\n    \"local\": {\n      \"npm\": \"@ai-sdk/anthropic\",\n      \"name\": \"My Local\",\n      \"options\": {\n        \"baseURL\": \"http://localhost:4141/v1\",\n        \"apiKey\": \"dummy\"\n      },\n      \"models\": {\n        \"gpt-5.4\": {\n          \"name\": \"gpt-5.4\",\n          \"modalities\": {\n            \"input\": [\"text\", \"image\"],\n            \"output\": [\"text\"]\n          },\n          \"limit\": {\n            \"context\": 400000,\n            \"input\": 272000,\n            \"output\": 128000\n          }\n        },\n        \"claude-sonnet-4.6\": {\n          \"id\": \"claude-sonnet-4.6\",\n          \"name\": \"claude-sonnet-4.6\",\n          \"modalities\": {\n            \"input\": [\"text\", \"image\"],\n            \"output\": [\"text\"]\n          },          \n          \"limit\": {\n            \"context\": 200000,\n            \"output\": 32000\n          },\n          \"options\": {\n            \"thinking\": {\n              \"type\": \"adaptive\"\n            },\n            \"effort\": \"max\"\n          }\n        }\n      }\n    }\n  }\n}\n```\n\nWhy these fields matter:\n\n- `npm: \"@ai-sdk/anthropic\"` is the important part. OpenCode will speak Anthropic Messages semantics to this AI gateway instead of flattening everything into OpenAI Chat Completions.\n- `options.baseURL` should be `http://localhost:4141/v1`; the Anthropic SDK will append `/messages`, `/models`, and `/messages/count_tokens` automatically.\n- If you enable `auth.apiKeys` in this AI gateway, replace `dummy` with a real key. Otherwise any placeholder value is fine.\n\n## Using with Codex\n\nThis AI gateway can also power Codex.\n\n### Codex `config.toml` Reference\n\nAdd the following `[model_providers.copilot_api]` section to your Codex `~/.codex/config.toml`:\n\n```toml\nmodel_provider = \"copilot_api\"\nmodel_reasoning_summary = \"auto\"\nmodel_context_window = 272000\nmodel_auto_compact_token_limit = 244800\n\n[model_providers.copilot_api]\nname = \"OpenAI\"\nbase_url = \"http://localhost:4141\"\nenv_key = \"GITHUB_COPILOT_API_KEY\"\nrequires_openai_auth = true\nsupports_websockets = false\nwire_api = \"responses\"\nrequest_max_retries = 3\nstream_max_retries = 1\nstream_idle_timeout_ms = 300000\n\n[features]\nremote_compaction_v2 = true\n\n[analytics]\nenabled = false\n```\n\n> [!NOTE]\n> This configuration is specific to Codex and the GitHub Copilot provider. `name` must be set to `\"OpenAI\"`. It can help mitigate Codex local compact cache miss issues.\n> If you are using the codex provider, it is recommended to set `base_url` to `\"http://localhost:4141/codex\"`.\n\n## GPT Tool Search\n\nFor GPT Responses models such as `gpt-5.4+`, this AI gateway can expose Responses `tool_search` through a small MCP bridge. The same bridge can be used by Claude Code and opencode, as long as the client loads MCP servers and sends Anthropic Messages traffic through this gateway.\n\nDo not set Claude Code's native `ENABLE_TOOL_SEARCH` for GPT models. That flag enables Claude Code's own client-side tool search mode, and it may stop forwarding deferred tool definitions. This gateway needs the full tool definitions so it can keep the small always-loaded tool set eager and translate every other tool into Responses deferred namespaces.\n\nIf you install `tool-search@copilot-api-marketplace`, Claude Code receives this MCP bridge automatically and you can skip the manual Claude Code MCP setup below.\n\nAdd the tool search bridge to the MCP config used by Claude Code:\n\n```json\n{\n  \"mcpServers\": {\n    \"tool_search\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@jeffreycao/copilot-api@latest\", \"mcp\"]\n    }\n  }\n}\n```\n\nAdd the tool search bridge to the MCP config used by opencode:\n\n```json\n{\n  \"mcp\": {\n    \"tool_search\": {\n      \"type\": \"local\",\n      \"command\": [\"npx\", \"-y\", \"@jeffreycao/copilot-api@latest\", \"mcp\"]\n    }\n  }\n}\n```\n\nFor local development, use `bun` as the command and `[\"run\", \"./src/main.ts\", \"mcp\"]` as the args.\n\nInternally, the gateway now configures OpenAI Responses `tool_search` in client-executed mode. Deferred tools are still exposed as searchable namespaces, but the model is explicitly asked to return the exact deferred tool names it wants to load next.\n\nThe bridge uses direct tool selection, not query search. Its tool input is `names`, a comma-separated list of exact deferred tool names, for example `TaskList,TaskGet,mcp__fetch__fetch`.\n\n## Plugin Integrations\n\nPlugin integrations are available for Claude Code and opencode.\n\n#### Claude Code plugin integration (marketplace-based)\n\nThe Claude Code integration is packaged as two plugins:\n\n- `agent-inject` injects `__SUBAGENT_MARKER__...` on `SubagentStart`, so the gateway can infer `x-initiator: agent`.\n- `tool-search` registers the `tool_search` MCP bridge used for GPT Responses deferred tool loading.\n\n- Marketplace catalog in this repository: `.claude-plugin/marketplace.json`\n- Plugin sources in this repository: `plugin/claude/agent-inject`, `plugin/claude/tool-search`\n\nAdd the marketplace remotely:\n\n```sh\n/plugin marketplace add https://github.com/caozhiyuan/copilot-api.git\n```\n\nInstall the plugins from the marketplace:\n\n```sh\n/plugin install agent-inject@copilot-api-marketplace\n/plugin install tool-search@copilot-api-marketplace\n```\n\nAfter installation, `agent-inject` injects `__SUBAGENT_MARKER__...` on `SubagentStart`, and the gateway uses it to infer `x-initiator: agent`.\n\nThe `agent-inject` plugin also registers a `UserPromptSubmit` hook that returns `{\"continue\": true}`, and it can inject `SessionStart` reminder rules through environment variables:\n\n- `CLAUDE_PLUGIN_ENABLE_QUESTION_RULES=1` enables the two reminders about using the `question` tool automatically for Claude Code. Alternatively, you can add the same reminders manually in `CLAUDE.md`; see [CLAUDE.md or AGENTS.md Recommended Content](#claudemd-or-agentsmd-recommended-content).\n- `CLAUDE_PLUGIN_ENABLE_NO_BACKGROUND_AGENTS_RULE=1` enables the `run_in_background: true` avoidance reminder for agent hooks.\n\nThe `tool-search` plugin bundles the same MCP bridge described in [GPT Tool Search](#gpt-tool-search), so Claude Code users do not need to add the `tool_search` server manually when they install that plugin.\n\n#### Opencode plugin\n\nThe subagent marker producer is packaged as an opencode plugin located at `plugin/opencode/subagent-marker.js`.\n\n**Installation:**\n\nCopy the plugin file to your opencode plugins directory:\n\n```sh\n# Clone or download this repository, then copy the plugin\ncp plugin/opencode/subagent-marker.js ~/.config/opencode/plugins/\n```\n\nOr manually create the file at `~/.config/opencode/plugins/subagent-marker.js` with the plugin content.\n\n**Features:**\n\n- Tracks sub-sessions created by subagents\n- Automatically prepends a marker system reminder (`__SUBAGENT_MARKER__...`) to subagent chat messages\n- Sets `x-session-id` header for session tracking\n- Enables the gateway to infer `x-initiator: agent` for subagent-originated requests\n\nThe plugin hooks into `session.created`, `session.deleted`, `chat.message`, and `chat.headers` events to provide seamless subagent marker functionality.\n\n## Using the Usage Viewer\n\nAfter starting the server, a URL to the Copilot Usage Dashboard will be displayed in your console. This dashboard is a web interface for monitoring your API usage.\n\n1.  Start the server. For example, using npx:\n    ```sh\n    npx @jeffreycao/copilot-api@latest start\n    ```\n2.  The server will output a URL to the usage viewer. Copy and paste this URL into your browser. It will look something like this:\n    `http://localhost:4141/usage-viewer?endpoint=http://localhost:4141/usage`\n    - If you use the `start.bat` script on Windows, this page will open automatically.\n\nThe dashboard provides a user-friendly interface to view your Copilot usage data:\n\n> Token usage history requires Bun or Node.js >= 22.13.0. On Node.js < 22.13.0, the server runs normally but token usage storage is disabled.\n\n- **API Endpoint URL**: The dashboard is pre-configured to fetch data from your local server endpoint via a URL query parameter. You can manually switch this to any other compatible API endpoint.\n- **x-api-key Authentication**: If API Key authentication is enabled, you can provide the `x-api-key` request header. The key is persisted in the browser's local storage.\n- **Period Selector**: Choose from Day, Week, or Month time ranges. The URL query parameter updates automatically when you switch, making it easy to bookmark and share.\n- **Fetch Data**: Click the \"Refresh\" button to load or refresh the usage data. The dashboard also fetches data automatically on page load.\n- **Copilot Quotas**: View quota usage for services such as Chat and Completions via progress bars. Hover over a card to see used/remaining details.\n- **Token Usage Metric Cards**: See a summary of Total, Input, Output, Cache Read, Cache Write, Requests, and estimated cost for the current period.\n- **Trend Chart (Week / Month)**: An interactive line chart with model and metric filters. Click a data point to inspect the usage breakdown for a specific day.\n- **Model Breakdown Table**: A per-model summary of requests, input/output/cache tokens, and estimated cost for the selected period.\n- **Request Events (Paginated)**: A time-sorted list of request event records with pagination support, showing timestamps, models, request IDs, and token counts.\n- **Detailed Information**: See the full JSON response from the API for a detailed breakdown of all available usage statistics.\n- **URL-based Configuration**: You can also specify the API endpoint and period directly via `endpoint` and `period` query parameters. For example:\n  `http://localhost:4141/usage-viewer?endpoint=http://your-api-server/usage&period=week`\n\n### Usage Viewer Screenshot\n\n<p align=\"center\">\n  <img src=\"./docs/screenshots/usage-viewer.png\" alt=\"Copilot API usage viewer\" width=\"900\" />\n</p>\n\n## Command Structure\n\nCopilot API now uses a subcommand structure with these main commands:\n\n- `start`: Start the gateway server. If a GitHub token is available, the server starts with Copilot enabled. If no GitHub token is available, it starts in provider-only mode when at least one enabled provider exists; otherwise it guides you through provider setup.\n- `auth`: Run provider login or configuration without starting the server. Use it for GitHub Copilot login, Codex OAuth, or third-party provider API key setup.\n- `debug`: Display diagnostic information including version, runtime details, file paths, and authentication status. Useful for troubleshooting and support.\n\n## Command Line Options\n\n### Global Options\n\nThe following options can be used with any subcommand. When passing them before the subcommand, use the `--key=value` form:\n\n| Option            | Description                                            | Default | Alias |\n| ----------------- | ------------------------------------------------------ | ------- | ----- |\n| --api-home        | Path to the API home directory (sets COPILOT_API_HOME) | none    | none  |\n| --oauth-app       | OAuth app identifier (sets COPILOT_API_OAUTH_APP)      | none    | none  |\n| --enterprise-url  | Enterprise URL for GitHub (sets COPILOT_API_ENTERPRISE_URL) | none | none |\n\n### Start Command Options\n\nThe following command line options are available for the `start` command:\n\n| Option         | Description                                                                   | Default    | Alias |\n| -------------- | ----------------------------------------------------------------------------- | ---------- | ----- |\n| --port         | Port to listen on                                                             | 4141       | -p    |\n| --verbose      | Enable verbose logging                                                        | false      | -v    |\n| --github-token | Provide GitHub token directly (must be generated using the `auth` subcommand) | none       | -g    |\n| --claude-code  | Generate a command to launch Claude Code with Copilot API config              | false      | -c    |\n| --show-token   | Show GitHub and Copilot tokens on fetch and refresh                           | false      | none  |\n| --proxy-env    | Initialize proxy from environment variables                                   | false      | none  |\n\n### Auth Command Options\n\n| Option       | Description               | Default | Alias |\n| ------------ | ------------------------- | ------- | ----- |\n| --provider   | Provider to log in with or configure (`copilot`, `codex`, `opencode-go`, `deepseek`, `dashscope`, `openrouter`, or `custom`) | prompt | none |\n| --verbose    | Enable verbose logging    | false   | -v    |\n| --show-token | Show GitHub token on auth | false   | none  |\n\nUse `copilot-api auth login --provider copilot` only when you want to enable the GitHub Copilot provider. Copilot is not required for `codex` or third-party provider-only usage.\n\nUse `copilot-api auth login --provider deepseek`, `--provider dashscope`, `--provider openrouter`, or `--provider opencode-go` to add or update those common third-party providers from the CLI. DeepSeek prompts for masked `apiKey`, provider `type` (default `anthropic`), and `baseUrl` defaulting to `https://api.deepseek.com/anthropic`. DashScope prompts for masked `apiKey`, provider `type` (default `openai-compatible`), and prefilled `baseUrl`. OpenRouter prompts for masked `apiKey` and prefilled `baseUrl` only, and writes `type: \"anthropic\"`. OpenCode Go prompts for masked `apiKey` and prefilled `baseUrl` only, and writes `type: \"openai-compatible\"` (baseUrl `https://opencode.ai/zen/go`). After a provider is configured and enabled, `copilot-api start` can run without any GitHub token.\n\nUse `copilot-api auth login --provider custom` to add or update another third-party provider from the CLI. The command prompts for the provider name, supported type (`anthropic`, `openai-compatible`, or `openai-responses`), `baseUrl`, masked `apiKey`, and `authType`; `authType` may be left as the type default or set to `x-api-key` / `authorization`.\n\n### Debug Command Options\n\n| Option | Description               | Default | Alias |\n| ------ | ------------------------- | ------- | ----- |\n| --json | Output debug info as JSON | false   | none  |\n\n## Configuration (config.json)\n\n- **Location:** `~/.local/share/copilot-api/config.json` (Linux/macOS) or `%USERPROFILE%\\.local\\share\\copilot-api\\config.json` (Windows).\n- **Default shape:**\n  ```json\n  {\n    \"auth\": {\n      \"apiKeys\": [],\n      \"adminApiKey\": \"<auto-generated-on-startup>\"\n    },\n    \"providers\": {},\n    \"modelMappings\": {},\n    \"extraPrompts\": {\n      \"gpt-5-mini\": \"<built-in exploration prompt>\"\n    },\n    \"smallModel\": \"gpt-5-mini\",\n    \"contextManagement\": {\n      \"messages\": true,\n      \"responses\": false\n    },\n    \"modelResponsesApiCompactThresholds\": {\n      \"gpt-5.4\": 217600,\n      \"gpt-5.5\": 217600,\n      \"gpt-5.6-sol\": 231200,\n      \"gpt-5.6-terra\": 231200,\n      \"gpt-5.6-luna\": 231200\n    },\n    \"modelReasoningEfforts\": {\n      \"gpt-5-mini\": \"low\"\n    },\n    \"useMessagesApi\": true,\n    \"useResponsesApiWebSocket\": true,\n    \"useResponsesApiWebSearch\": true,\n    \"messageApiWebSearchModel\": \"gpt-5-mini\"\n  }\n  ```\n- **auth.apiKeys:** API keys used for request authentication on non-admin routes. Supports multiple keys for rotation. Requests can authenticate with either `x-api-key: <key>` or `Authorization: Bearer <key>`. If empty or omitted, authentication for non-admin routes is disabled.\n- **auth.adminApiKey:** Single admin key used only for `/admin/*` routes. If missing, the server generates a random key at startup and writes it back to `config.json`. Requests use the same `x-api-key` or `Authorization: Bearer` headers, but regular `auth.apiKeys` never grant access to `/admin/*`.\n- **modelMappings:** Exact `sourceModel -> targetModel` rewrites shared by top-level `POST /v1/messages`, `POST /v1/messages/count_tokens`, `POST /v1/responses`, and `POST /v1/chat/completions` requests. Omit it or leave it as `{}` to disable rewrites. Both the source and target must be non-empty strings. Targets can be regular model IDs or `provider/model` aliases such as `dashscope/qwen3.6-plus`, and the rewrite happens before provider alias parsing. These mappings are not split per interface. The admin endpoints `GET/POST /admin/config/model-mappings` read and update only this field.\n- **extraPrompts:** Map of `model -> prompt` appended to the first system prompt when translating Anthropic-style requests to Responses API. Use this to inject guardrails or guidance per model. Missing default entries are auto-added without overwriting your custom prompts. For GPT-5.3+ models (e.g. `gpt-5.3-codex`, `gpt-5.4`, `gpt-5.5`), a built-in commentary prompt is used as fallback when not explicitly configured. The built-in prompts enable phase-aware commentary, which lets the model emit a short user-facing progress update before tools or deeper reasoning.\n- **providers:** Global upstream provider map. Each provider key (for example `dashscope`) becomes a route prefix (`/dashscope/v1/messages`). Supports `type: \"anthropic\"`, `type: \"openai-compatible\"`, and `type: \"openai-responses\"`. Top-level clients can also use `model: \"dashscope/model-id\"` with `/v1/messages`, `/v1/messages/count_tokens`, `/v1/responses`, and `/v1/chat/completions`; the gateway strips the `dashscope/` prefix before forwarding upstream. `openai-compatible` providers support both chat and Messages flows: `/v1/chat/completions` is proxied to upstream `/v1/chat/completions`, while `/v1/messages` and `/:provider/v1/messages` are translated to upstream chat completions and translated back to Anthropic Messages responses. `GET /v1/models` aggregates enabled provider models with `provider/model-id` IDs; use `GET /dashscope/v1/models` for a single provider's raw model list.\n  - `enabled` defaults to `true` if omitted.\n  - `baseUrl` should be provider API base URL without the final endpoint. For Anthropic providers, omit `/v1/messages`; for OpenAI-compatible providers, omit `/v1/chat/completions`; for OpenAI Responses providers, omit `/v1/responses`.\n  - `apiKey` is used as the upstream credential value and is required for regular providers.\n  - `authType` (optional): Controls how `apiKey` is sent upstream. Supports `x-api-key` and `authorization` for regular providers. Anthropic providers default to `x-api-key`; OpenAI-compatible and OpenAI Responses providers default to `authorization`. When set to `authorization`, the proxy sends `Authorization: Bearer <apiKey>`. `oauth2` is reserved for the built-in `codex` provider and is written automatically by `auth login --provider codex`.\n  - `pricingCurrency` (optional): Provider-level currency used for token cost calculation, for example `USD` or `CNY`. Quick providers default to `CNY` for DashScope and DeepSeek, and `USD` for Codex/OpenRouter. Costs are grouped by currency and are not exchange-rate converted.\n  - `models` (optional): Per-model configuration map. Each key is a model ID (matching the model name in requests), and the value is:\n    - `temperature` (optional): Default temperature value used when the request does not specify one.\n    - `topP` (optional): Default top_p value used when the request does not specify one.\n    - `topK` (optional): Default top_k value used when the request does not specify one.\n    - `extraBody` (optional): Dynamic fields merged into the upstream request body for that model. Request body fields with the same name take precedence. OpenAI-compatible providers can use this for fields such as `enable_thinking`, `preserve_thinking`, `reasoning_effort`. `thinking_budget` is a special OpenAI-compatible provider override: when configured in `extraBody`, it is forced after Anthropic `thinking.budget_tokens` translation and overrides the request-derived budget. For providers whose name is `dashscope` or whose `baseUrl` contains `aliyuncs.com`, the request-derived `thinking_budget` (from Anthropic `thinking.budget_tokens`) is forwarded upstream; for other OpenAI-compatible providers the request-derived `thinking_budget` is stripped, while an `extraBody` `thinking_budget` is still honored. For DashScope providers, `preserve_thinking` defaults to `true` when not explicitly set in `extraBody` or the request body.\n    - `pricing` (optional): Per-model token prices, in the provider `pricingCurrency`, per 1M tokens. Supported fields are `input`, `output`, `cachedInput` (implicit cache read), `explicitCachedInput` (explicit cache read), and `cacheCreationInput`. Use `tiers` with `maxInputTokens` for input-size tiered pricing.\n    - `contextCache` (optional): Defaults to `true` for providers whose name is `dashscope` or whose `baseUrl` contains `aliyuncs.com`; defaults to `false` for other OpenAI-compatible providers. This enables Alibaba Cloud Model Studio/DashScope explicit context cache by injecting `cache_control: { \"type\": \"ephemeral\" }` on up to 4 content blocks using the Context Cache format. The cache breakpoint strategy matches opencode's main provider flow: the first 2 system messages plus the last 2 non-system messages. Marked string content is converted to text content part arrays for `system` / `user` / `assistant` / `tool` messages; existing array content is marked on the last part. Set this to `false` when the model already supports implicit caching, or when the upstream does not accept this explicit-cache extension field. Set this to `true` for non-DashScope providers that support the same explicit-cache extension. Applied on both `/v1/messages` and `/v1/chat/completions` routes.\n    - `supportPdf` (optional): Controls whether the model supports PDF/document content. Defaults to `false`; unsupported PDFs are converted to a text notice. Set it to `true` to send PDF/document blocks as OpenAI Chat Completions file parts.\n    - `toolContentSupportType` (optional): Tool result content capabilities for that model, as an array of `array`, `image`, and `pdf`. Provider routes default to string-only tool content when omitted. If `supportPdf` is `true` but this list does not include `pdf`, file parts in tool results are moved to user role messages. This provider default does not change the Copilot main flow, which continues to support array + image and not PDF.\n    - `type` (optional): Per-model override of the provider protocol type. Supports `anthropic`, `openai-compatible`, and `openai-responses`. When set, the provider's `/v1/messages` route uses this model's type instead of the provider-level type for request routing, auth header resolution, and upstream endpoint selection. This is useful for providers like OpenCode Go whose upstream supports both OpenAI-compatible and Anthropic Messages APIs for different models. When the type is overridden, the auth header is resolved from the overridden type's default (Anthropic defaults to `x-api-key`; OpenAI-compatible/Responses default to `authorization`).\n\n  Example DashScope model settings:\n  ```json\n  {\n    \"providers\": {\n      \"dashscope\": {\n        \"type\": \"openai-compatible\",\n        \"enabled\": true,\n        \"baseUrl\": \"https://dashscope.aliyuncs.com/compatible-mode\",\n        \"apiKey\": \"sk-your-dashscope-key\",\n        \"pricingCurrency\": \"CNY\",\n        \"models\": {\n          \"qwen3.7-plus\": {\n            \"temperature\": 1,\n            \"topP\": 0.95,\n            \"topK\": 20,\n            \"extraBody\": {\n              \"preserve_thinking\": true\n            }\n          },\n          \"glm-5.1\": {\n            \"temperature\": 0.7,\n            \"topP\": 0.95,\n            \"contextCache\": true,\n            \"pricing\": {\n              \"tiers\": [\n                {\n                  \"maxInputTokens\": 32000,\n                  \"input\": 6,\n                  \"cachedInput\": 1.2,\n                  \"explicitCachedInput\": 0.6,\n                  \"cacheCreationInput\": 7.5,\n                  \"output\": 24\n                },\n                {\n                  \"maxInputTokens\": 200000,\n                  \"input\": 8,\n                  \"cachedInput\": 1.6,\n                  \"explicitCachedInput\": 0.8,\n                  \"cacheCreationInput\": 10,\n                  \"output\": 28\n                }\n              ]\n            },\n            \"extraBody\": {\n              \"preserve_thinking\": true\n            }\n          }\n        }\n      }\n    }\n  }\n  ```\n  Built-in token prices cover Codex GPT models in USD, DashScope `qwen3.7-max`, `qwen3.7-plus`, `glm-5.1`, `glm-5.2` in CNY, DeepSeek `deepseek-v4-flash`, `deepseek-v4-pro`, `deepseek-chat`, `deepseek-reasoner` in CNY, and OpenCode Go models (`glm-5.2`, `grok-4.5`, `deepseek-v4-flash`, `deepseek-v4-pro`, `kimi-k2.7-code`, `kimi-k3`, `mimo-v2.5`, `mimo-v2.5-pro`, `qwen3.7-plus`, `qwen3.7-max`, `minimax-m2.5`, `minimax-m3`) in USD. User `pricing` entries override built-ins. For DashScope, cached tokens are charged as explicit cache reads when the upstream usage includes `cache_creation_input_tokens`; otherwise `cachedInput` is used as the implicit cache read price. For DeepSeek, `prompt_cache_hit_tokens` map to cached input and `prompt_cache_miss_tokens` map to regular input.\n- **smallModel:** Fallback model used for tool-less warmup messages (e.g., Claude Code probe requests); defaults to gpt-5-mini.\n- **contextManagement:** Controls whether the proxy adds Responses API `context_management` compaction instructions. `messages` applies when Anthropic-style `/v1/messages` requests are translated to Responses API, including `openai-responses` provider message routes, and defaults to `true`. `responses` applies to native `/v1/responses` traffic, including `provider/model` aliases and the built-in `codex` provider, and defaults to `false`. Enable `responses` only after checking that your client supports context management compaction. When enabled, the request includes `context_management` in the body and keeps only the latest compaction carrier on follow-up turns. **Note:** Context management is forcibly disabled for GPT-5.6 and above models (e.g. `gpt-5.6-sol`, `gpt-5.6-terra`, `gpt-5.6-luna`) because enabling it breaks prompt cache hits on those models. This override takes precedence over the `contextManagement` and `modelResponsesApiCompactThresholds` settings.\n- **modelResponsesApiCompactThresholds:** Per-model Responses API `compact_threshold` overrides used when the proxy adds `context_management`. These values take precedence over the fallback threshold from `resolveResponsesCompactThreshold` (`max_prompt_tokens * ratio`, or the default fallback). Defaults set `gpt-5.4` and `gpt-5.5` to `217600` (`272000 * 0.8`), and `gpt-5.6-sol`, `gpt-5.6-terra`, `gpt-5.6-luna` to `231200` (`272000 * 0.85`). Models not listed continue to use the normal fallback logic.\n- **modelReasoningEfforts:** Per-model fallback reasoning effort for `/v1/messages` requests. It is used only when the request does not provide `output_config.effort`.\n  - **Priority:** request `output_config.effort` > `modelReasoningEfforts[model]` > built-in default (`xhigh` for GPT-5.3+ models, otherwise `high`).\n  - **Forwarding:** the resolved value remains `output_config.effort` for the Copilot native Messages API and becomes `reasoning.effort` when translated to the Responses API.\n  - **Configuration values:** `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`.\n- **useMessagesApi:** When `true`, Claude-family models that support Copilot's native `/v1/messages` endpoint will use the Messages API; otherwise they fall back to `/chat/completions`. Set to `false` to disable Messages API routing and always use `/chat/completions`. Defaults to `true`.\n- **useResponsesApiWebSocket:** When `true`, Responses API requests use Copilot's websocket transport for models that advertise `ws:/responses`; models that only advertise `/responses` continue to use HTTP. Set to `false` to disable websocket routing and use HTTP `/responses` whenever the selected model supports it. Defaults to `true`. If the Responses API WebSocket gets closed, it is usually caused by your own network. If you are using a VPN, try switching to a different node.\n- **useResponsesApiWebSearch:** When `true`, the server keeps Responses API tools with `type: \"web_search\"` and forwards them upstream. Set to `false` to strip those tools from `/responses` payloads. Defaults to `true`.\n- **messageApiWebSearchModel:** Global fallback model used when a top-level Copilot `/v1/messages` request contains only the server-side `web_search` tool. Defaults to `gpt-5-mini`. If the value is a `provider/model` alias, the request is routed into that provider's Messages API path with the provider prefix stripped. For Copilot GPT models, web search runs through `/responses`. Mixed `web_search` plus custom tools are not supported and the server-side `web_search` tool is stripped.\n- **claudeTokenMultiplier:** Multiplier applied to the fallback GPT-tokenizer estimate for Claude `/v1/messages/count_tokens` requests. Defaults to `1.15`. Increase it if your client is still compacting too late. This setting is only used when the proxy is estimating Claude tokens locally; if `anthropicApiKey` is configured and Anthropic token counting succeeds, the exact Anthropic count is returned instead.\n- **anthropicApiKey:** Anthropic API key used to forward Claude `/v1/messages/count_tokens` requests to Anthropic's real token counting endpoint, which returns exact counts instead of GPT tokenizer estimates. Can also be set via the `ANTHROPIC_API_KEY` environment variable. If not set, or if the upstream call fails, token counting falls back to local GPT tokenizer estimation controlled by `claudeTokenMultiplier`.\n\nEdit this file to customize prompts or swap in your own fast model. Restart the server (or rerun the command) after changes so the cached config is refreshed.\n\n## API Authentication\n\n- **Protected non-admin routes:** All routes except `/`, `/usage-viewer`, and `/usage-viewer/` require authentication when `auth.apiKeys` is configured and non-empty.\n- **Admin routes:** All `/admin/*` routes require `auth.adminApiKey`. If it is missing, the server generates one at startup and persists it to `config.json` before serving requests.\n- **Allowed auth headers:**\n  - `x-api-key: <your_key>`\n  - `Authorization: Bearer <your_key>`\n- **CORS preflight:** `OPTIONS` requests are always allowed.\n- **When no regular keys are configured:** Non-admin routes continue to allow requests. This does not apply to `/admin/*`, which only accepts `auth.adminApiKey`.\n\nExample request for a regular protected route:\n\n```sh\ncurl http://localhost:4141/v1/models \\\n  -H \"x-api-key: your_api_key\"\n```\n\nExample request for an admin route:\n\n```sh\ncurl http://localhost:4141/admin/config/model-mappings \\\n  -H \"x-api-key: your_admin_api_key\"\n```\n\n## API Endpoints\n\nThe server exposes several OpenAI- and Anthropic-compatible endpoints. Requests can target GitHub Copilot, the built-in `codex` provider, or configured providers depending on the selected model and `provider/model` alias.\n\n### OpenAI Compatible Endpoints\n\nThese endpoints mimic the OpenAI API structure.\n\n| Endpoint                    | Method | Description                                                      |\n| --------------------------- | ------ | ---------------------------------------------------------------- |\n| `POST /v1/responses`        | `POST` | OpenAI Most advanced interface for generating model responses. Supports `provider/model` aliases for `openai-responses` providers. |\n| `POST /v1/chat/completions` | `POST` | Creates a model response for the given chat conversation. Supports `provider/model` aliases for `openai-compatible` providers and can be used without Copilot when the target provider is configured. |\n| `GET /v1/models`            | `GET`  | Lists Copilot models plus enabled provider models using `provider/model-id` IDs. Requests from Codex clients (`User-Agent` beginning with `codex`) are forwarded to the Codex Models upstream. |\n| `POST /v1/embeddings`       | `POST` | Creates an embedding vector representing the input text.         |\n\n### Codex Backend Proxy Endpoints\n\nThese endpoints require an active Codex login. Each endpoint is available both without a version prefix and under `/v1`.\n\n| Endpoint | Method | Description |\n| --- | --- | --- |\n| `POST /alpha/search`<br>`POST /v1/alpha/search` | `POST` | Transparently forwards the JSON body and query parameters to the Codex Alpha Search upstream. |\n| `POST /images/generations`<br>`POST /v1/images/generations` | `POST` | Forwards a JSON image generation request to the Codex Images upstream. When the request omits `Content-Type`, the gateway defaults it to `application/json`. |\n| `POST /images/edits`<br>`POST /v1/images/edits` | `POST` | Forwards an image edit request to the Codex Images upstream. Send this request as `multipart/form-data` and let the HTTP client generate the `boundary`; the gateway preserves the incoming content type and streams the upload body. |\n\nFor every endpoint above, the gateway replaces client authorization and account headers with the active Codex login, preserves query parameters and compatible request headers, and returns the upstream status, headers, and body.\n\n### Anthropic Compatible Endpoints\n\nThese endpoints are designed to be compatible with the Anthropic Messages API. Provider-scoped models, Responses, alpha-search, and images routes accept both unversioned and `/v1` paths; Messages routes remain under `/v1`.\n\n| Endpoint                         | Method | Description                                                  |\n| -------------------------------- | ------ | ------------------------------------------------------------ |\n| `POST /v1/messages`              | `POST` | Creates a model response for a given conversation. Supports `provider/model` aliases for configured providers, including translation through `openai-compatible` providers. |\n| `POST /v1/messages/count_tokens` | `POST` | Calculates the number of tokens for a given set of messages. Supports `provider/model` aliases for configured providers. |\n| `POST /:provider/v1/messages`       | `POST` | Proxies Anthropic Messages requests to the configured Anthropic provider, translates them through an OpenAI-compatible provider, or translates them through an OpenAI Responses provider. |\n| `GET /:provider/models`<br>`GET /:provider/v1/models` | `GET` | Proxies model listing requests to the configured provider. For `codex`, returns the built-in catalog by default; Codex clients (`User-Agent` starting with `codex`) are forwarded to the Codex Models upstream. |\n| `POST /:provider/v1/messages/count_tokens` | `POST` | Calculates tokens locally for provider route requests. |\n| `POST /:provider/responses`<br>`POST /:provider/v1/responses` | `POST` | Proxies OpenAI Responses requests to a configured `openai-responses` provider (including `codex`). |\n| `POST /:provider/alpha/search`<br>`POST /:provider/v1/alpha/search` | `POST` | Proxies alpha-search requests. For `codex`, forwards to the Codex Alpha Search upstream; for other providers, forwards to `{baseUrl}/v1/alpha/search`. |\n| `POST /:provider/images/generations`<br>`POST /:provider/v1/images/generations` | `POST` | Proxies image generation. For `codex`, uses the Codex Images upstream; for other providers, forwards to `{baseUrl}/v1/images/generations` (15-minute timeout). |\n| `POST /:provider/images/edits`<br>`POST /:provider/v1/images/edits` | `POST` | Proxies image edits. For `codex`, uses the Codex Images upstream; for other providers, forwards multipart/streamed bodies to `{baseUrl}/v1/images/edits` (15-minute timeout). |\n\n### Usage Monitoring Endpoints\n\nNew endpoints for monitoring your Copilot usage and quotas.\n\n| Endpoint     | Method | Description                                                  |\n| ------------ | ------ | ------------------------------------------------------------ |\n| `GET /usage` | `GET`  | Get detailed Copilot usage statistics and quota information. |\n| `GET /token` | `GET`  | Get the current Copilot token being used by the API.         |\n\n### Admin / Configuration Endpoints\n\nThese endpoints are reserved for local administrative actions and only accept `auth.adminApiKey`.\n\n| Endpoint                              | Method | Description                                                                 |\n| ------------------------------------- | ------ | --------------------------------------------------------------------------- |\n| `GET /admin/config/model-mappings`    | `GET`  | Returns the current `config.json` path and the active `modelMappings` map.  |\n| `POST /admin/config/model-mappings`   | `POST` | Updates only the `modelMappings` field in `config.json` and returns it back. |\n\n## Example Usage\n\nCommon `npx` commands:\n\n```sh\n# Start the gateway\nnpx @jeffreycao/copilot-api@latest start\n\n# Start on a custom port with verbose logging\nnpx @jeffreycao/copilot-api@latest start --port 8080 --verbose\n\n# Run the auth flow\nnpx @jeffreycao/copilot-api@latest auth login\n\n# Configure a third-party provider, then run without GitHub Copilot\nnpx @jeffreycao/copilot-api@latest auth login --provider dashscope\nnpx @jeffreycao/copilot-api@latest start\n\n# Print debug information as JSON\nnpx @jeffreycao/copilot-api@latest debug --json\n\n# Run the published CLI with Bun instead of Node.js\nbunx --bun @jeffreycao/copilot-api@latest start\n```\n\nOpenAI-compatible provider examples after configuring `dashscope`:\n\n```sh\ncurl http://localhost:4141/v1/chat/completions \\\n  -H \"content-type: application/json\" \\\n  -d '{\"model\":\"dashscope/qwen3.6-plus\",\"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]}'\n\ncurl http://localhost:4141/dashscope/v1/messages \\\n  -H \"content-type: application/json\" \\\n  -d '{\"model\":\"qwen3.6-plus\",\"max_tokens\":1024,\"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]}'\n```\n\n## Usage Tips\n\n### CLAUDE.md or AGENTS.md Recommended Content\n\nTo add these reminders manually, include the following in `CLAUDE.md` for Claude Code, or `AGENTS.md` for opencode/codex:\n\n```\n- Prohibited from directly asking questions to users, MUST use question tool.\n- Once you can confirm that the task is complete, MUST use question tool to make user confirm. The user may respond with feedback if they are not satisfied with the result, which you can use to make improvements and try again, after try again, MUST use question tool to make user confirm again.\n```\n"}, "6f97faf757e5f903eb239a1047939a053a1086a9": {"t": 1785765541.0818126, "n": 50237, "h": "0230e6adacdcf1ea", "c": "# Copilot API Proxy\n\nEnglish | [简体中文](./README.zh-CN.md)\n\n## Important Notes\n\n> [!IMPORTANT]\n> **Before using, please be aware of the following:**\n>\n> 1. **Claude Code configuration:** When using with Claude Code, please configure the model ID as `claude-opus-4-8`. Example claude `settings.json` see [Manual Configuration with `settings.json`](#manual-configuration-with-settingsjson). \n>\n> 2. **Built-in `copilot`, `codex` and third-party providers:** Run `npx @jeffreycao/copilot-api@latest auth` and choose `copilot`, `codex`, `deepseek`, `custom`, or other providers.\n>\n> 3. **Note:** See [GitHub Copilot Security Notice](./NOTICE.md#github-copilot-security-notice) for the warning removed from the README header.\n\n---\n\n## Project Overview\n\nA small AI gateway that can use GitHub Copilot, the built-in `codex` provider, or configured third-party providers such as DashScope. GitHub Copilot is optional: if no GitHub token is available, the server can still start in provider-only mode as long as at least one enabled provider is configured.\n\nThe gateway exposes OpenAI- and Anthropic-compatible APIs from one local endpoint, so tools like [Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview), OpenCode, Codex, and OpenAI-compatible clients can share the same local server.\n\nOn the GitHub Copilot path, the gateway prefers Copilot's native Anthropic-style Messages API when available, preserving more Claude-native behavior for tool-heavy workflows.\n\n## Features\n\n- **OpenAI and Anthropic compatibility**: Serve `/v1/responses`, `/v1/chat/completions`, `/v1/models`, `/v1/embeddings`, and `/v1/messages` from one local gateway.\n- **Copilot is optional**: Use GitHub Copilot when credentials are present, or run the server with only configured providers.\n- **One gateway for Copilot, `codex`, and external providers**: Route GitHub Copilot, the built-in `codex` provider, and configured third-party providers behind the same endpoint.\n- **Standalone third-party providers**: Configure providers such as DashScope, DeepSeek, OpenRouter, or a custom provider and start the gateway without a GitHub Copilot login.\n- **OpenAI-compatible providers on chat and Messages APIs**: `openai-compatible` providers can serve top-level `/v1/chat/completions` through `model: \"provider/model\"` and Anthropic-style `/v1/messages` through request/response translation.\n- **Agent-friendly Claude handling on Copilot**: Prefer native `/v1/messages` when available, preserve Claude-style tool flows, support Anthropic beta features, Claude WebSearch through Responses-capable models, and keep subagent/session markers intact.\n- **Claude Code and OpenCode integration**: Works with Claude Code and OpenCode, including direct Anthropic-compatible usage through `@ai-sdk/anthropic`.\n- **Flexible auth and deployment options**: Supports interactive login or direct tokens, individual/business/enterprise plans, GitHub Enterprise, opencode OAuth, and custom data directories.\n- **Multi-provider routing**: Expose provider-specific `/:provider/...` routes or use `model: \"provider/model\"` on the top-level API.\n\n## Prerequisites\n\n- Bun (>= 1.2.x)\n- Node.js if you plan to run the published CLI with `npx`\n- GitHub account with Copilot subscription only if you want to use the GitHub Copilot provider\n- An API key or OAuth login for at least one configured provider if you want to run without GitHub Copilot\n\n## Installation\n\nTo install dependencies, run:\n\n```sh\nbun install\n```\n\nTo start the server directly from source:\n\n```sh\nbun run start start\n```\n\n## Running from Source\n\nThe project can be run from source in several ways:\n\n### Development Mode\n\n```sh\nbun run dev start\n```\n\n### Production Mode\n\n```sh\nbun run start start\n```\n\n## Using with npx\n\nYou can run the project directly using npx:\n\n> [!IMPORTANT]\n> Token usage storage uses Node's built-in `node:sqlite` module when running with `npx`. It is enabled on Node.js >= 22.13.0. On Node.js < 22.13.0, the CLI still starts, but token usage storage is disabled.\n>\n> If you want token usage storage without upgrading Node.js, run the published CLI with Bun instead: `bunx --bun @jeffreycao/copilot-api@latest start`.\n\n```sh\nnpx @jeffreycao/copilot-api@latest start\n```\n\nWith options:\n\n```sh\nnpx @jeffreycao/copilot-api@latest start --port 8080\n```\n\nFor authentication or provider configuration only:\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth\n```\n\nTo run without GitHub Copilot, configure at least one provider first, then start the server normally:\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth login --provider dashscope\nnpx @jeffreycao/copilot-api@latest start\n```\n\n## Using with Docker\n\nBuild the image:\n\n```sh\ndocker build -t copilot-api .\n```\n\nRun the container with a bind mount so auth data survives restarts:\n\n```sh\nmkdir -p ./copilot-data\ndocker run -p 4141:4141 -v $(pwd)/copilot-data:/root/.local/share/copilot-api copilot-api\n```\n\nThis stores GitHub auth data, provider config, and other gateway state in `./copilot-data` on the host, mapped to `/root/.local/share/copilot-api` in the container.\n\nOr pass a GitHub token directly:\n\n```sh\ndocker run -p 4141:4141 -e GH_TOKEN=your_github_token_here copilot-api\n```\n\n## Electron Desktop App\n\nIf you prefer a GUI, this repository also includes an Electron desktop app in `desktop/`. It supports GitHub Copilot sign-in, OpenAI Codex OAuth, and API-key configuration for DeepSeek, DashScope, OpenRouter, or a custom provider. After authorization or provider configuration, it can start and stop the local proxy with one click and shows the local endpoint, auth header, available models, usage, and logs in the app.\n\nThe settings screen also exposes `OAuth App`, `API Home`, `Enterprise URL`, verbose logging, and minimize-to-tray. Desktop packages are published in GitHub Releases:\n\nhttps://github.com/caozhiyuan/copilot-api/releases\n\nDownload the installer for your platform, authorize or configure a provider inside the app, choose a port, start the server, then point your client at the local endpoint shown in the app. Packaged desktop builds use the bundled Electron runtime, so normal desktop usage does not require installing Node.js separately. Token usage history is enabled when that bundled runtime supports SQLite.\n\nThe desktop app's Advanced Config page reads and writes the shared model mappings through `GET/POST /admin/config/model-mappings`. The same mappings apply across `POST /v1/messages`, `POST /v1/messages/count_tokens`, `POST /v1/responses`, and `POST /v1/chat/completions` instead of being split per interface. It uses `auth.adminApiKey` instead of the regular `auth.apiKeys`, and the app reads that key directly from `config.json` after the server has generated it on startup.\n\n### Desktop App Screenshots\n\nMain dashboard, token usage breakdown in the bundled Electron app:\n\n<p align=\"center\">\n  <img src=\"./docs/screenshots/desktop-dashboard.png\" alt=\"Copilot API desktop app dashboard\" width=\"49%\" />\n  <img src=\"./docs/screenshots/desktop-token-usage.png\" alt=\"Copilot API desktop app token usage view\" width=\"49%\" />\n</p>\n\n## Using with Claude Code\n\nThis AI gateway can be used to power [Claude Code](https://docs.anthropic.com/en/claude-code), an experimental conversational AI assistant for developers from Anthropic.\n\nThere are two ways to configure Claude Code to use this AI gateway:\n\n### Interactive Setup with `--claude-code` flag\n\nTo get started, run the `start` command with the `--claude-code` flag:\n\n```sh\nnpx @jeffreycao/copilot-api@latest start --claude-code\n```\n\nYou will no longer be prompted to pick models manually. The gateway automatically detects the latest available model for each Claude Code size tier — opus maps to the newest Opus model, sonnet to the newest Sonnet model, and haiku to the newest Haiku model — and generates a command that sets `ANTHROPIC_DEFAULT_OPUS_MODEL`, `ANTHROPIC_DEFAULT_SONNET_MODEL`, and `ANTHROPIC_DEFAULT_HAIKU_MODEL` accordingly. Any tier without a matching model available is omitted. The command is copied to your clipboard and sets the environment variables needed for Claude Code to use the gateway.\n\nPaste and run this command in a new terminal to launch Claude Code.\n\n### Manual Configuration with `settings.json`\n\nAlternatively, you can configure Claude Code by creating a `.claude/settings.json` file in your project's root directory. This file should contain the environment variables needed by Claude Code. This way you don't need to run the interactive setup every time.\n\nHere is an example `.claude/settings.json` file:\n\n```json\n{\n  \"env\": {\n    \"ANTHROPIC_BASE_URL\": \"http://localhost:4141\",\n    \"ANTHROPIC_AUTH_TOKEN\": \"dummy\",\n    \"ANTHROPIC_MODEL\": \"codex/gpt-5.6-sol[1m]\",\n    \"ANTHROPIC_DEFAULT_SONNET_MODEL\": \"codex/gpt-5.6-sol[1m]\",\n    \"ANTHROPIC_DEFAULT_HAIKU_MODEL\": \"codex/gpt-5.6-luna[1m]\",\n    \"CLAUDE_CODE_AUTO_COMPACT_WINDOW\": \"272000\",\n    \"CLAUDE_CODE_USE_VERTEX\": \"0\",\n    \"CLAUDE_CODE_USE_BEDROCK\": \"0\",\n    \"DISABLE_NON_ESSENTIAL_MODEL_CALLS\": \"1\",\n    \"CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC\": \"1\",\n    \"CLAUDE_CODE_ATTRIBUTION_HEADER\": \"0\",\n    \"CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION\": \"false\",\n    \"CLAUDE_CODE_DISABLE_TERMINAL_TITLE\": \"true\",\n    \"CLAUDE_CODE_ENABLE_AWAY_SUMMARY\": \"0\"\n  },\n  \"alwaysThinkingEnabled\": true,\n  \"effortLevel\": \"xhigh\",\n  \"showThinkingSummaries\": true\n}\n```\n\n- Replace `ANTHROPIC_MODEL`, `ANTHROPIC_DEFAULT_OPUS_MODEL`, `ANTHROPIC_DEFAULT_SONNET_MODEL`, and `ANTHROPIC_DEFAULT_HAIKU_MODEL` according to your needs. After configuration, please install the claude code plugin [Plugin Integrations](#plugin-integrations).  \n- Setting CLAUDE_CODE_ATTRIBUTION_HEADER to 0 can prevent Claude code from adding billing and version information in system prompts, thereby avoiding prompt cache invalidation.\n- Turning off CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION and CLAUDE_CODE_ENABLE_AWAY_SUMMARY can prevent quota from being consumed unnecessarily.\n- Claude Code WebSearch is supported for pure search requests. For Copilot, keep the global `messageApiWebSearchModel` set to a Responses-capable GPT model or a `provider/model` alias. For provider routes, use a native Anthropic provider or an `openai-responses` provider. Add `WebSearch` to `permissions.deny` only if you want to forbid this traffic.\n- If using a non-Claude model, do not enable ENABLE_TOOL_SEARCH. If using the Claude model, can enable ENABLE_TOOL_SEARCH. The current Claude Code uses the client tool search mode. In this mode, loading defer tools requires an additional request each time.\n- `CLAUDE_CODE_AUTO_COMPACT_WINDOW`: Set the context capacity in tokens used for auto-compaction calculations. Defaults to the model's context window: 200K for standard models or 1M for extended context models. Use a lower value like `500000` on a 1M model (e.g., `claude-opus-4-6[1m]`) to treat the window as 500K for compaction purposes. The value is capped at the model's actual context window. `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` is applied as a percentage of this value. Setting this variable decouples the compaction threshold from the status line's `used_percentage`, which always uses the model's full context window.\n\nYou can find more options here: [Claude Code settings](https://docs.anthropic.com/en/docs/claude-code/settings#environment-variables)\n\nYou can also read more about IDE integration here: [Add Claude Code to your IDE](https://docs.anthropic.com/en/docs/claude-code/ide-integrations)\n\n## Using with OpenCode\n\nOpenCode already has a direct GitHub Copilot provider. Use this section when you want OpenCode to point at this AI gateway through `@ai-sdk/anthropic` and reuse the agent behaviors described earlier in this README.\n\n### Minimal setup\n\nStart the AI gateway with the OpenCode OAuth app:\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth --oauth-app=opencode\nnpx @jeffreycao/copilot-api@latest start\n```\n\nThen point OpenCode at the gateway with `@ai-sdk/anthropic`.\n\nExample `~/.config/opencode/opencode.json`:\n\n```json\n{\n  \"$schema\": \"https://opencode.ai/config.json\",\n  \"provider\": {\n    \"local\": {\n      \"npm\": \"@ai-sdk/anthropic\",\n      \"name\": \"My Local\",\n      \"options\": {\n        \"baseURL\": \"http://localhost:4141/v1\",\n        \"apiKey\": \"dummy\"\n      },\n      \"models\": {\n        \"gpt-5.4\": {\n          \"name\": \"gpt-5.4\",\n          \"modalities\": {\n            \"input\": [\"text\", \"image\"],\n            \"output\": [\"text\"]\n          },\n          \"limit\": {\n            \"context\": 400000,\n            \"input\": 272000,\n            \"output\": 128000\n          }\n        },\n        \"claude-sonnet-4.6\": {\n          \"id\": \"claude-sonnet-4.6\",\n          \"name\": \"claude-sonnet-4.6\",\n          \"modalities\": {\n            \"input\": [\"text\", \"image\"],\n            \"output\": [\"text\"]\n          },          \n          \"limit\": {\n            \"context\": 200000,\n            \"output\": 32000\n          },\n          \"options\": {\n            \"thinking\": {\n              \"type\": \"adaptive\"\n            },\n            \"effort\": \"max\"\n          }\n        }\n      }\n    }\n  }\n}\n```\n\nWhy these fields matter:\n\n- `npm: \"@ai-sdk/anthropic\"` is the important part. OpenCode will speak Anthropic Messages semantics to this AI gateway instead of flattening everything into OpenAI Chat Completions.\n- `options.baseURL` should be `http://localhost:4141/v1`; the Anthropic SDK will append `/messages`, `/models`, and `/messages/count_tokens` automatically.\n- If you enable `auth.apiKeys` in this AI gateway, replace `dummy` with a real key. Otherwise any placeholder value is fine.\n\n## Using with Codex\n\nThis AI gateway can also power Codex.\n\n### Codex `config.toml` Reference\n\nAdd the following `[model_providers.copilot_api]` section to your Codex `~/.codex/config.toml`:\n\n```toml\nmodel_provider = \"copilot_api\"\nmodel_reasoning_summary = \"auto\"\nmodel_context_window = 272000\nmodel_auto_compact_token_limit = 244800\n\n[model_providers.copilot_api]\nname = \"OpenAI\"\nbase_url = \"http://localhost:4141\"\nenv_key = \"GITHUB_COPILOT_API_KEY\"\nrequires_openai_auth = true\nsupports_websockets = false\nwire_api = \"responses\"\nrequest_max_retries = 3\nstream_max_retries = 1\nstream_idle_timeout_ms = 300000\n\n[features]\nremote_compaction_v2 = true\n\n[analytics]\nenabled = false\n```\n\n> [!NOTE]\n> This configuration is specific to Codex and the GitHub Copilot provider. `name` must be set to `\"OpenAI\"`. It can help mitigate Codex local compact cache miss issues.\n> If you are using the codex provider, it is recommended to set `base_url` to `\"http://localhost:4141/codex\"`.\n\n## GPT Tool Search\n\nFor GPT Responses models such as `gpt-5.4+`, this AI gateway can expose Responses `tool_search` through a small MCP bridge. The same bridge can be used by Claude Code and opencode, as long as the client loads MCP servers and sends Anthropic Messages traffic through this gateway.\n\nDo not set Claude Code's native `ENABLE_TOOL_SEARCH` for GPT models. That flag enables Claude Code's own client-side tool search mode, and it may stop forwarding deferred tool definitions. This gateway needs the full tool definitions so it can keep the small always-loaded tool set eager and translate every other tool into Responses deferred namespaces.\n\nIf you install `tool-search@copilot-api-marketplace`, Claude Code receives this MCP bridge automatically and you can skip the manual Claude Code MCP setup below.\n\nAdd the tool search bridge to the MCP config used by Claude Code:\n\n```json\n{\n  \"mcpServers\": {\n    \"tool_search\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@jeffreycao/copilot-api@latest\", \"mcp\"]\n    }\n  }\n}\n```\n\nAdd the tool search bridge to the MCP config used by opencode:\n\n```json\n{\n  \"mcp\": {\n    \"tool_search\": {\n      \"type\": \"local\",\n      \"command\": [\"npx\", \"-y\", \"@jeffreycao/copilot-api@latest\", \"mcp\"]\n    }\n  }\n}\n```\n\nFor local development, use `bun` as the command and `[\"run\", \"./src/main.ts\", \"mcp\"]` as the args.\n\nInternally, the gateway now configures OpenAI Responses `tool_search` in client-executed mode. Deferred tools are still exposed as searchable namespaces, but the model is explicitly asked to return the exact deferred tool names it wants to load next.\n\nThe bridge uses direct tool selection, not query search. Its tool input is `names`, a comma-separated list of exact deferred tool names, for example `TaskList,TaskGet,mcp__fetch__fetch`.\n\n## Plugin Integrations\n\nPlugin integrations are available for Claude Code and opencode.\n\n#### Claude Code plugin integration (marketplace-based)\n\nThe Claude Code integration is packaged as two plugins:\n\n- `agent-inject` injects `__SUBAGENT_MARKER__...` on `SubagentStart`, so the gateway can infer `x-initiator: agent`.\n- `tool-search` registers the `tool_search` MCP bridge used for GPT Responses deferred tool loading.\n\n- Marketplace catalog in this repository: `.claude-plugin/marketplace.json`\n- Plugin sources in this repository: `plugin/claude/agent-inject`, `plugin/claude/tool-search`\n\nAdd the marketplace remotely:\n\n```sh\n/plugin marketplace add https://github.com/caozhiyuan/copilot-api.git\n```\n\nInstall the plugins from the marketplace:\n\n```sh\n/plugin install agent-inject@copilot-api-marketplace\n/plugin install tool-search@copilot-api-marketplace\n```\n\nAfter installation, `agent-inject` injects `__SUBAGENT_MARKER__...` on `SubagentStart`, and the gateway uses it to infer `x-initiator: agent`.\n\nThe `agent-inject` plugin also registers a `UserPromptSubmit` hook that returns `{\"continue\": true}`, and it can inject `SessionStart` reminder rules through environment variables:\n\n- `CLAUDE_PLUGIN_ENABLE_QUESTION_RULES=1` enables the two reminders about using the `question` tool automatically for Claude Code. Alternatively, you can add the same reminders manually in `CLAUDE.md`; see [CLAUDE.md or AGENTS.md Recommended Content](#claudemd-or-agentsmd-recommended-content).\n- `CLAUDE_PLUGIN_ENABLE_NO_BACKGROUND_AGENTS_RULE=1` enables the `run_in_background: true` avoidance reminder for agent hooks.\n\nThe `tool-search` plugin bundles the same MCP bridge described in [GPT Tool Search](#gpt-tool-search), so Claude Code users do not need to add the `tool_search` server manually when they install that plugin.\n\n#### Opencode plugin\n\nThe subagent marker producer is packaged as an opencode plugin located at `plugin/opencode/subagent-marker.js`.\n\n**Installation:**\n\nCopy the plugin file to your opencode plugins directory:\n\n```sh\n# Clone or download this repository, then copy the plugin\ncp plugin/opencode/subagent-marker.js ~/.config/opencode/plugins/\n```\n\nOr manually create the file at `~/.config/opencode/plugins/subagent-marker.js` with the plugin content.\n\n**Features:**\n\n- Tracks sub-sessions created by subagents\n- Automatically prepends a marker system reminder (`__SUBAGENT_MARKER__...`) to subagent chat messages\n- Sets `x-session-id` header for session tracking\n- Enables the gateway to infer `x-initiator: agent` for subagent-originated requests\n\nThe plugin hooks into `session.created`, `session.deleted`, `chat.message`, and `chat.headers` events to provide seamless subagent marker functionality.\n\n## Using the Usage Viewer\n\nAfter starting the server, a URL to the Copilot Usage Dashboard will be displayed in your console. This dashboard is a web interface for monitoring your API usage.\n\n1.  Start the server. For example, using npx:\n    ```sh\n    npx @jeffreycao/copilot-api@latest start\n    ```\n2.  The server will output a URL to the usage viewer. Copy and paste this URL into your browser. It will look something like this:\n    `http://localhost:4141/usage-viewer?endpoint=http://localhost:4141/usage`\n    - If you use the `start.bat` script on Windows, this page will open automatically.\n\nThe dashboard provides a user-friendly interface to view your Copilot usage data:\n\n> Token usage history requires Bun or Node.js >= 22.13.0. On Node.js < 22.13.0, the server runs normally but token usage storage is disabled.\n\n- **API Endpoint URL**: The dashboard is pre-configured to fetch data from your local server endpoint via a URL query parameter. You can manually switch this to any other compatible API endpoint.\n- **x-api-key Authentication**: If API Key authentication is enabled, you can provide the `x-api-key` request header. The key is persisted in the browser's local storage.\n- **Period Selector**: Choose from Day, Week, or Month time ranges. The URL query parameter updates automatically when you switch, making it easy to bookmark and share.\n- **Fetch Data**: Click the \"Refresh\" button to load or refresh the usage data. The dashboard also fetches data automatically on page load.\n- **Copilot Quotas**: View quota usage for services such as Chat and Completions via progress bars. Hover over a card to see used/remaining details.\n- **Token Usage Metric Cards**: See a summary of Total, Input, Output, Cache Read, Cache Write, Requests, and estimated cost for the current period.\n- **Trend Chart (Week / Month)**: An interactive line chart with model and metric filters. Click a data point to inspect the usage breakdown for a specific day.\n- **Model Breakdown Table**: A per-model summary of requests, input/output/cache tokens, and estimated cost for the selected period.\n- **Request Events (Paginated)**: A time-sorted list of request event records with pagination support, showing timestamps, models, request IDs, and token counts.\n- **Detailed Information**: See the full JSON response from the API for a detailed breakdown of all available usage statistics.\n- **URL-based Configuration**: You can also specify the API endpoint and period directly via `endpoint` and `period` query parameters. For example:\n  `http://localhost:4141/usage-viewer?endpoint=http://your-api-server/usage&period=week`\n\n### Usage Viewer Screenshot\n\n<p align=\"center\">\n  <img src=\"./docs/screenshots/usage-viewer.png\" alt=\"Copilot API usage viewer\" width=\"900\" />\n</p>\n\n## Command Structure\n\nCopilot API now uses a subcommand structure with these main commands:\n\n- `start`: Start the gateway server. If a GitHub token is available, the server starts with Copilot enabled. If no GitHub token is available, it starts in provider-only mode when at least one enabled provider exists; otherwise it guides you through provider setup.\n- `auth`: Run provider login or configuration without starting the server. Use it for GitHub Copilot login, Codex OAuth, or third-party provider API key setup.\n- `debug`: Display diagnostic information including version, runtime details, file paths, and authentication status. Useful for troubleshooting and support.\n\n## Command Line Options\n\n### Global Options\n\nThe following options can be used with any subcommand. When passing them before the subcommand, use the `--key=value` form:\n\n| Option            | Description                                            | Default | Alias |\n| ----------------- | ------------------------------------------------------ | ------- | ----- |\n| --api-home        | Path to the API home directory (sets COPILOT_API_HOME) | none    | none  |\n| --oauth-app       | OAuth app identifier (sets COPILOT_API_OAUTH_APP)      | none    | none  |\n| --enterprise-url  | Enterprise URL for GitHub (sets COPILOT_API_ENTERPRISE_URL) | none | none |\n\n### Start Command Options\n\nThe following command line options are available for the `start` command:\n\n| Option         | Description                                                                   | Default    | Alias |\n| -------------- | ----------------------------------------------------------------------------- | ---------- | ----- |\n| --port         | Port to listen on                                                             | 4141       | -p    |\n| --verbose      | Enable verbose logging                                                        | false      | -v    |\n| --github-token | Provide GitHub token directly (must be generated using the `auth` subcommand) | none       | -g    |\n| --claude-code  | Generate a command to launch Claude Code with Copilot API config              | false      | -c    |\n| --show-token   | Show GitHub and Copilot tokens on fetch and refresh                           | false      | none  |\n| --proxy-env    | Initialize proxy from environment variables                                   | false      | none  |\n\n### Auth Command Options\n\n| Option       | Description               | Default | Alias |\n| ------------ | ------------------------- | ------- | ----- |\n| --provider   | Provider to log in with or configure (`copilot`, `codex`, `opencode-go`, `deepseek`, `dashscope`, `openrouter`, or `custom`) | prompt | none |\n| --verbose    | Enable verbose logging    | false   | -v    |\n| --show-token | Show GitHub token on auth | false   | none  |\n\nUse `copilot-api auth login --provider copilot` only when you want to enable the GitHub Copilot provider. Copilot is not required for `codex` or third-party provider-only usage.\n\nUse `copilot-api auth login --provider deepseek`, `--provider dashscope`, `--provider openrouter`, or `--provider opencode-go` to add or update those common third-party providers from the CLI. DeepSeek prompts for masked `apiKey`, provider `type` (default `anthropic`), and `baseUrl` defaulting to `https://api.deepseek.com/anthropic`. DashScope prompts for masked `apiKey`, provider `type` (default `openai-compatible`), and prefilled `baseUrl`. OpenRouter prompts for masked `apiKey` and prefilled `baseUrl` only, and writes `type: \"anthropic\"`. OpenCode Go prompts for masked `apiKey` and prefilled `baseUrl` only, and writes `type: \"openai-compatible\"` (baseUrl `https://opencode.ai/zen/go`). After a provider is configured and enabled, `copilot-api start` can run without any GitHub token.\n\nUse `copilot-api auth login --provider custom` to add or update another third-party provider from the CLI. The command prompts for the provider name, supported type (`anthropic`, `openai-compatible`, or `openai-responses`), `baseUrl`, masked `apiKey`, and `authType`; `authType` may be left as the type default or set to `x-api-key` / `authorization`.\n\n### Debug Command Options\n\n| Option | Description               | Default | Alias |\n| ------ | ------------------------- | ------- | ----- |\n| --json | Output debug info as JSON | false   | none  |\n\n## Configuration (config.json)\n\n- **Location:** `~/.local/share/copilot-api/config.json` (Linux/macOS) or `%USERPROFILE%\\.local\\share\\copilot-api\\config.json` (Windows).\n- **Default shape:**\n  ```json\n  {\n    \"auth\": {\n      \"apiKeys\": [],\n      \"adminApiKey\": \"<auto-generated-on-startup>\"\n    },\n    \"providers\": {},\n    \"modelMappings\": {},\n    \"extraPrompts\": {\n      \"gpt-5-mini\": \"<built-in exploration prompt>\"\n    },\n    \"smallModel\": \"gpt-5-mini\",\n    \"contextManagement\": {\n      \"messages\": true,\n      \"responses\": false\n    },\n    \"modelResponsesApiCompactThresholds\": {\n      \"gpt-5.4\": 217600,\n      \"gpt-5.5\": 217600,\n      \"gpt-5.6-sol\": 231200,\n      \"gpt-5.6-terra\": 231200,\n      \"gpt-5.6-luna\": 231200\n    },\n    \"modelReasoningEfforts\": {\n      \"gpt-5-mini\": \"low\"\n    },\n    \"useMessagesApi\": true,\n    \"useResponsesApiWebSocket\": true,\n    \"useResponsesApiWebSearch\": true,\n    \"messageApiWebSearchModel\": \"gpt-5-mini\"\n  }\n  ```\n- **auth.apiKeys:** API keys used for request authentication on non-admin routes. Supports multiple keys for rotation. Requests can authenticate with either `x-api-key: <key>` or `Authorization: Bearer <key>`. If empty or omitted, authentication for non-admin routes is disabled.\n- **auth.adminApiKey:** Single admin key used only for `/admin/*` routes. If missing, the server generates a random key at startup and writes it back to `config.json`. Requests use the same `x-api-key` or `Authorization: Bearer` headers, but regular `auth.apiKeys` never grant access to `/admin/*`.\n- **modelMappings:** Exact `sourceModel -> targetModel` rewrites shared by top-level `POST /v1/messages`, `POST /v1/messages/count_tokens`, `POST /v1/responses`, and `POST /v1/chat/completions` requests. Omit it or leave it as `{}` to disable rewrites. Both the source and target must be non-empty strings. Targets can be regular model IDs or `provider/model` aliases such as `dashscope/qwen3.6-plus`, and the rewrite happens before provider alias parsing. These mappings are not split per interface. The admin endpoints `GET/POST /admin/config/model-mappings` read and update only this field.\n- **extraPrompts:** Map of `model -> prompt` appended to the first system prompt when translating Anthropic-style requests to Responses API. Use this to inject guardrails or guidance per model. Missing default entries are auto-added without overwriting your custom prompts. For GPT-5.3+ models (e.g. `gpt-5.3-codex`, `gpt-5.4`, `gpt-5.5`), a built-in commentary prompt is used as fallback when not explicitly configured. The built-in prompts enable phase-aware commentary, which lets the model emit a short user-facing progress update before tools or deeper reasoning.\n- **providers:** Global upstream provider map. Each provider key (for example `dashscope`) becomes a route prefix (`/dashscope/v1/messages`). Supports `type: \"anthropic\"`, `type: \"openai-compatible\"`, and `type: \"openai-responses\"`. Top-level clients can also use `model: \"dashscope/model-id\"` with `/v1/messages`, `/v1/messages/count_tokens`, `/v1/responses`, and `/v1/chat/completions`; the gateway strips the `dashscope/` prefix before forwarding upstream. `openai-compatible` providers support both chat and Messages flows: `/v1/chat/completions` is proxied to upstream `/v1/chat/completions`, while `/v1/messages` and `/:provider/v1/messages` are translated to upstream chat completions and translated back to Anthropic Messages responses. `GET /v1/models` aggregates enabled provider models with `provider/model-id` IDs; use `GET /dashscope/v1/models` for a single provider's raw model list.\n  - `enabled` defaults to `true` if omitted.\n  - `baseUrl` should be provider API base URL without the final endpoint. For Anthropic providers, omit `/v1/messages`; for OpenAI-compatible providers, omit `/v1/chat/completions`; for OpenAI Responses providers, omit `/v1/responses`.\n  - `apiKey` is used as the upstream credential value and is required for regular providers.\n  - `authType` (optional): Controls how `apiKey` is sent upstream. Supports `x-api-key` and `authorization` for regular providers. Anthropic providers default to `x-api-key`; OpenAI-compatible and OpenAI Responses providers default to `authorization`. When set to `authorization`, the proxy sends `Authorization: Bearer <apiKey>`. `oauth2` is reserved for the built-in `codex` provider and is written automatically by `auth login --provider codex`.\n  - `pricingCurrency` (optional): Provider-level currency used for token cost calculation, for example `USD` or `CNY`. Quick providers default to `CNY` for DashScope and DeepSeek, and `USD` for Codex/OpenRouter. Costs are grouped by currency and are not exchange-rate converted.\n  - `models` (optional): Per-model configuration map. Each key is a model ID (matching the model name in requests), and the value is:\n    - `temperature` (optional): Default temperature value used when the request does not specify one.\n    - `topP` (optional): Default top_p value used when the request does not specify one.\n    - `topK` (optional): Default top_k value used when the request does not specify one.\n    - `extraBody` (optional): Dynamic fields merged into the upstream request body for that model. Request body fields with the same name take precedence. OpenAI-compatible providers can use this for fields such as `enable_thinking`, `preserve_thinking`, `reasoning_effort`. `thinking_budget` is a special OpenAI-compatible provider override: when configured in `extraBody`, it is forced after Anthropic `thinking.budget_tokens` translation and overrides the request-derived budget. For providers whose name is `dashscope` or whose `baseUrl` contains `aliyuncs.com`, the request-derived `thinking_budget` (from Anthropic `thinking.budget_tokens`) is forwarded upstream; for other OpenAI-compatible providers the request-derived `thinking_budget` is stripped, while an `extraBody` `thinking_budget` is still honored. For DashScope providers, `preserve_thinking` defaults to `true` when not explicitly set in `extraBody` or the request body.\n    - `pricing` (optional): Per-model token prices, in the provider `pricingCurrency`, per 1M tokens. Supported fields are `input`, `output`, `cachedInput` (implicit cache read), `explicitCachedInput` (explicit cache read), and `cacheCreationInput`. Use `tiers` with `maxInputTokens` for input-size tiered pricing.\n    - `contextCache` (optional): Defaults to `true` for providers whose name is `dashscope` or whose `baseUrl` contains `aliyuncs.com`; defaults to `false` for other OpenAI-compatible providers. This enables Alibaba Cloud Model Studio/DashScope explicit context cache by injecting `cache_control: { \"type\": \"ephemeral\" }` on up to 4 content blocks using the Context Cache format. The cache breakpoint strategy matches opencode's main provider flow: the first 2 system messages plus the last 2 non-system messages. Marked string content is converted to text content part arrays for `system` / `user` / `assistant` / `tool` messages; existing array content is marked on the last part. Set this to `false` when the model already supports implicit caching, or when the upstream does not accept this explicit-cache extension field. Set this to `true` for non-DashScope providers that support the same explicit-cache extension. Applied on both `/v1/messages` and `/v1/chat/completions` routes.\n    - `supportPdf` (optional): Controls whether the model supports PDF/document content. Defaults to `false`; unsupported PDFs are converted to a text notice. Set it to `true` to send PDF/document blocks as OpenAI Chat Completions file parts.\n    - `toolContentSupportType` (optional): Tool result content capabilities for that model, as an array of `array`, `image`, and `pdf`. Provider routes default to string-only tool content when omitted. If `supportPdf` is `true` but this list does not include `pdf`, file parts in tool results are moved to user role messages. This provider default does not change the Copilot main flow, which continues to support array + image and not PDF.\n    - `type` (optional): Per-model override of the provider protocol type. Supports `anthropic`, `openai-compatible`, and `openai-responses`. When set, the provider's `/v1/messages` route uses this model's type instead of the provider-level type for request routing, auth header resolution, and upstream endpoint selection. This is useful for providers like OpenCode Go whose upstream supports both OpenAI-compatible and Anthropic Messages APIs for different models. When the type is overridden, the auth header is resolved from the overridden type's default (Anthropic defaults to `x-api-key`; OpenAI-compatible/Responses default to `authorization`).\n\n  Example DashScope model settings:\n  ```json\n  {\n    \"providers\": {\n      \"dashscope\": {\n        \"type\": \"openai-compatible\",\n        \"enabled\": true,\n        \"baseUrl\": \"https://dashscope.aliyuncs.com/compatible-mode\",\n        \"apiKey\": \"sk-your-dashscope-key\",\n        \"pricingCurrency\": \"CNY\",\n        \"models\": {\n          \"qwen3.7-plus\": {\n            \"temperature\": 1,\n            \"topP\": 0.95,\n            \"topK\": 20,\n            \"extraBody\": {\n              \"preserve_thinking\": true\n            }\n          },\n          \"glm-5.1\": {\n            \"temperature\": 0.7,\n            \"topP\": 0.95,\n            \"contextCache\": true,\n            \"pricing\": {\n              \"tiers\": [\n                {\n                  \"maxInputTokens\": 32000,\n                  \"input\": 6,\n                  \"cachedInput\": 1.2,\n                  \"explicitCachedInput\": 0.6,\n                  \"cacheCreationInput\": 7.5,\n                  \"output\": 24\n                },\n                {\n                  \"maxInputTokens\": 200000,\n                  \"input\": 8,\n                  \"cachedInput\": 1.6,\n                  \"explicitCachedInput\": 0.8,\n                  \"cacheCreationInput\": 10,\n                  \"output\": 28\n                }\n              ]\n            },\n            \"extraBody\": {\n              \"preserve_thinking\": true\n            }\n          }\n        }\n      }\n    }\n  }\n  ```\n  Built-in token prices cover Codex GPT models in USD, DashScope `qwen3.7-max`, `qwen3.7-plus`, `glm-5.1`, `glm-5.2` in CNY, DeepSeek `deepseek-v4-flash`, `deepseek-v4-pro`, `deepseek-chat`, `deepseek-reasoner` in CNY, and OpenCode Go models (`glm-5.2`, `grok-4.5`, `deepseek-v4-flash`, `deepseek-v4-pro`, `kimi-k2.7-code`, `kimi-k3`, `mimo-v2.5`, `mimo-v2.5-pro`, `qwen3.7-plus`, `qwen3.7-max`, `minimax-m2.5`, `minimax-m3`) in USD. User `pricing` entries override built-ins. For DashScope, cached tokens are charged as explicit cache reads when the upstream usage includes `cache_creation_input_tokens`; otherwise `cachedInput` is used as the implicit cache read price. For DeepSeek, `prompt_cache_hit_tokens` map to cached input and `prompt_cache_miss_tokens` map to regular input.\n- **smallModel:** Fallback model used for tool-less warmup messages (e.g., Claude Code probe requests); defaults to gpt-5-mini.\n- **contextManagement:** Controls whether the proxy adds Responses API `context_management` compaction instructions. `messages` applies when Anthropic-style `/v1/messages` requests are translated to Responses API, including `openai-responses` provider message routes, and defaults to `true`. `responses` applies to native `/v1/responses` traffic, including `provider/model` aliases and the built-in `codex` provider, and defaults to `false`. Enable `responses` only after checking that your client supports context management compaction. When enabled, the request includes `context_management` in the body and keeps only the latest compaction carrier on follow-up turns. **Note:** Context management is forcibly disabled for GPT-5.6 and above models (e.g. `gpt-5.6-sol`, `gpt-5.6-terra`, `gpt-5.6-luna`) because enabling it breaks prompt cache hits on those models. This override takes precedence over the `contextManagement` and `modelResponsesApiCompactThresholds` settings.\n- **modelResponsesApiCompactThresholds:** Per-model Responses API `compact_threshold` overrides used when the proxy adds `context_management`. These values take precedence over the fallback threshold from `resolveResponsesCompactThreshold` (`max_prompt_tokens * ratio`, or the default fallback). Defaults set `gpt-5.4` and `gpt-5.5` to `217600` (`272000 * 0.8`), and `gpt-5.6-sol`, `gpt-5.6-terra`, `gpt-5.6-luna` to `231200` (`272000 * 0.85`). Models not listed continue to use the normal fallback logic.\n- **modelReasoningEfforts:** Per-model fallback reasoning effort for `/v1/messages` requests. It is used only when the request does not provide `output_config.effort`.\n  - **Priority:** request `output_config.effort` > `modelReasoningEfforts[model]` > built-in default (`xhigh` for GPT-5.3+ models, otherwise `high`).\n  - **Forwarding:** the resolved value remains `output_config.effort` for the Copilot native Messages API and becomes `reasoning.effort` when translated to the Responses API.\n  - **Configuration values:** `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`.\n- **useMessagesApi:** When `true`, Claude-family models that support Copilot's native `/v1/messages` endpoint will use the Messages API; otherwise they fall back to `/chat/completions`. Set to `false` to disable Messages API routing and always use `/chat/completions`. Defaults to `true`.\n- **useResponsesApiWebSocket:** When `true`, Responses API requests use Copilot's websocket transport for models that advertise `ws:/responses`; models that only advertise `/responses` continue to use HTTP. Set to `false` to disable websocket routing and use HTTP `/responses` whenever the selected model supports it. Defaults to `true`. If the Responses API WebSocket gets closed, it is usually caused by your own network. If you are using a VPN, try switching to a different node.\n- **useResponsesApiWebSearch:** When `true`, the server keeps Responses API tools with `type: \"web_search\"` and forwards them upstream. Set to `false` to strip those tools from `/responses` payloads. Defaults to `true`.\n- **messageApiWebSearchModel:** Global fallback model used when a top-level Copilot `/v1/messages` request contains only the server-side `web_search` tool. Defaults to `gpt-5-mini`. If the value is a `provider/model` alias, the request is routed into that provider's Messages API path with the provider prefix stripped. For Copilot GPT models, web search runs through `/responses`. Mixed `web_search` plus custom tools are not supported and the server-side `web_search` tool is stripped.\n- **claudeTokenMultiplier:** Multiplier applied to the fallback GPT-tokenizer estimate for Claude `/v1/messages/count_tokens` requests. Defaults to `1.15`. Increase it if your client is still compacting too late. This setting is only used when the proxy is estimating Claude tokens locally; if `anthropicApiKey` is configured and Anthropic token counting succeeds, the exact Anthropic count is returned instead.\n- **anthropicApiKey:** Anthropic API key used to forward Claude `/v1/messages/count_tokens` requests to Anthropic's real token counting endpoint, which returns exact counts instead of GPT tokenizer estimates. Can also be set via the `ANTHROPIC_API_KEY` environment variable. If not set, or if the upstream call fails, token counting falls back to local GPT tokenizer estimation controlled by `claudeTokenMultiplier`.\n\nEdit this file to customize prompts or swap in your own fast model. Restart the server (or rerun the command) after changes so the cached config is refreshed.\n\n## API Authentication\n\n- **Protected non-admin routes:** All routes except `/`, `/usage-viewer`, and `/usage-viewer/` require authentication when `auth.apiKeys` is configured and non-empty.\n- **Admin routes:** All `/admin/*` routes require `auth.adminApiKey`. If it is missing, the server generates one at startup and persists it to `config.json` before serving requests.\n- **Allowed auth headers:**\n  - `x-api-key: <your_key>`\n  - `Authorization: Bearer <your_key>`\n- **CORS preflight:** `OPTIONS` requests are always allowed.\n- **When no regular keys are configured:** Non-admin routes continue to allow requests. This does not apply to `/admin/*`, which only accepts `auth.adminApiKey`.\n\nExample request for a regular protected route:\n\n```sh\ncurl http://localhost:4141/v1/models \\\n  -H \"x-api-key: your_api_key\"\n```\n\nExample request for an admin route:\n\n```sh\ncurl http://localhost:4141/admin/config/model-mappings \\\n  -H \"x-api-key: your_admin_api_key\"\n```\n\n## API Endpoints\n\nThe server exposes several OpenAI- and Anthropic-compatible endpoints. Requests can target GitHub Copilot, the built-in `codex` provider, or configured providers depending on the selected model and `provider/model` alias.\n\n### OpenAI Compatible Endpoints\n\nThese endpoints mimic the OpenAI API structure.\n\n| Endpoint                    | Method | Description                                                      |\n| --------------------------- | ------ | ---------------------------------------------------------------- |\n| `POST /v1/responses`        | `POST` | OpenAI Most advanced interface for generating model responses. Supports `provider/model` aliases for `openai-responses` providers. |\n| `POST /v1/chat/completions` | `POST` | Creates a model response for the given chat conversation. Supports `provider/model` aliases for `openai-compatible` providers and can be used without Copilot when the target provider is configured. |\n| `GET /v1/models`            | `GET`  | Lists Copilot models plus enabled provider models using `provider/model-id` IDs. Requests from Codex clients (`User-Agent` beginning with `codex`) are forwarded to the Codex Models upstream. |\n| `POST /v1/embeddings`       | `POST` | Creates an embedding vector representing the input text.         |\n\n### Codex Backend Proxy Endpoints\n\nThese endpoints require an active Codex login. Each endpoint is available both without a version prefix and under `/v1`.\n\n| Endpoint | Method | Description |\n| --- | --- | --- |\n| `POST /alpha/search`<br>`POST /v1/alpha/search` | `POST` | Transparently forwards the JSON body and query parameters to the Codex Alpha Search upstream. |\n| `POST /images/generations`<br>`POST /v1/images/generations` | `POST` | Forwards a JSON image generation request to the Codex Images upstream. When the request omits `Content-Type`, the gateway defaults it to `application/json`. |\n| `POST /images/edits`<br>`POST /v1/images/edits` | `POST` | Forwards an image edit request to the Codex Images upstream. Send this request as `multipart/form-data` and let the HTTP client generate the `boundary`; the gateway preserves the incoming content type and streams the upload body. |\n\nFor every endpoint above, the gateway replaces client authorization and account headers with the active Codex login, preserves query parameters and compatible request headers, and returns the upstream status, headers, and body.\n\n### Anthropic Compatible Endpoints\n\nThese endpoints are designed to be compatible with the Anthropic Messages API. Provider-scoped models, Responses, alpha-search, and images routes accept both unversioned and `/v1` paths; Messages routes remain under `/v1`.\n\n| Endpoint                         | Method | Description                                                  |\n| -------------------------------- | ------ | ------------------------------------------------------------ |\n| `POST /v1/messages`              | `POST` | Creates a model response for a given conversation. Supports `provider/model` aliases for configured providers, including translation through `openai-compatible` providers. |\n| `POST /v1/messages/count_tokens` | `POST` | Calculates the number of tokens for a given set of messages. Supports `provider/model` aliases for configured providers. |\n| `POST /:provider/v1/messages`       | `POST` | Proxies Anthropic Messages requests to the configured Anthropic provider, translates them through an OpenAI-compatible provider, or translates them through an OpenAI Responses provider. |\n| `GET /:provider/models`<br>`GET /:provider/v1/models` | `GET` | Proxies model listing requests to the configured provider. For `codex`, returns the built-in catalog by default; Codex clients (`User-Agent` starting with `codex`) are forwarded to the Codex Models upstream. |\n| `POST /:provider/v1/messages/count_tokens` | `POST` | Calculates tokens locally for provider route requests. |\n| `POST /:provider/responses`<br>`POST /:provider/v1/responses` | `POST` | Proxies OpenAI Responses requests to a configured `openai-responses` provider (including `codex`). |\n| `POST /:provider/alpha/search`<br>`POST /:provider/v1/alpha/search` | `POST` | Proxies alpha-search requests. For `codex`, forwards to the Codex Alpha Search upstream; for other providers, forwards to `{baseUrl}/v1/alpha/search`. |\n| `POST /:provider/images/generations`<br>`POST /:provider/v1/images/generations` | `POST` | Proxies image generation. For `codex`, uses the Codex Images upstream; for other providers, forwards to `{baseUrl}/v1/images/generations` (15-minute timeout). |\n| `POST /:provider/images/edits`<br>`POST /:provider/v1/images/edits` | `POST` | Proxies image edits. For `codex`, uses the Codex Images upstream; for other providers, forwards multipart/streamed bodies to `{baseUrl}/v1/images/edits` (15-minute timeout). |\n\n### Usage Monitoring Endpoints\n\nNew endpoints for monitoring your Copilot usage and quotas.\n\n| Endpoint     | Method | Description                                                  |\n| ------------ | ------ | ------------------------------------------------------------ |\n| `GET /usage` | `GET`  | Get detailed Copilot usage statistics and quota information. |\n| `GET /token` | `GET`  | Get the current Copilot token being used by the API.         |\n\n### Admin / Configuration Endpoints\n\nThese endpoints are reserved for local administrative actions and only accept `auth.adminApiKey`.\n\n| Endpoint                              | Method | Description                                                                 |\n| ------------------------------------- | ------ | --------------------------------------------------------------------------- |\n| `GET /admin/config/model-mappings`    | `GET`  | Returns the current `config.json` path and the active `modelMappings` map.  |\n| `POST /admin/config/model-mappings`   | `POST` | Updates only the `modelMappings` field in `config.json` and returns it back. |\n\n## Example Usage\n\nCommon `npx` commands:\n\n```sh\n# Start the gateway\nnpx @jeffreycao/copilot-api@latest start\n\n# Start on a custom port with verbose logging\nnpx @jeffreycao/copilot-api@latest start --port 8080 --verbose\n\n# Run the auth flow\nnpx @jeffreycao/copilot-api@latest auth login\n\n# Configure a third-party provider, then run without GitHub Copilot\nnpx @jeffreycao/copilot-api@latest auth login --provider dashscope\nnpx @jeffreycao/copilot-api@latest start\n\n# Print debug information as JSON\nnpx @jeffreycao/copilot-api@latest debug --json\n\n# Run the published CLI with Bun instead of Node.js\nbunx --bun @jeffreycao/copilot-api@latest start\n```\n\nOpenAI-compatible provider examples after configuring `dashscope`:\n\n```sh\ncurl http://localhost:4141/v1/chat/completions \\\n  -H \"content-type: application/json\" \\\n  -d '{\"model\":\"dashscope/qwen3.6-plus\",\"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]}'\n\ncurl http://localhost:4141/dashscope/v1/messages \\\n  -H \"content-type: application/json\" \\\n  -d '{\"model\":\"qwen3.6-plus\",\"max_tokens\":1024,\"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]}'\n```\n\n## Usage Tips\n\n### CLAUDE.md or AGENTS.md Recommended Content\n\nTo add these reminders manually, include the following in `CLAUDE.md` for Claude Code, or `AGENTS.md` for opencode/codex:\n\n```\n- Prohibited from directly asking questions to users, MUST use question tool.\n- Once you can confirm that the task is complete, MUST use question tool to make user confirm. The user may respond with feedback if they are not satisfied with the result, which you can use to make improvements and try again, after try again, MUST use question tool to make user confirm again.\n```\n"}, "5952198121b3da7fb798c1462720ac730dd1fa7d": {"t": 1785765542.6051326, "n": 50219, "h": "81148c9713f78ed1", "c": "# Copilot API Proxy\n\nEnglish | [简体中文](./README.zh-CN.md)\n\n## Important Notes\n\n> [!IMPORTANT]\n> **Before using, please be aware of the following:**\n>\n> 1. **Claude Code configuration:** When using with Claude Code, please configure the model ID as `claude-opus-4-8`. Example claude `settings.json` see [Manual Configuration with `settings.json`](#manual-configuration-with-settingsjson). \n>\n> 2. **Built-in `copilot`, `codex` and third-party providers:** Run `npx @jeffreycao/copilot-api@latest auth` and choose `copilot`, `codex`, `deepseek`, `custom`, or other providers.\n>\n> 3. **Note:** See [GitHub Copilot Security Notice](./NOTICE.md#github-copilot-security-notice) for the warning removed from the README header.\n\n---\n\n## Project Overview\n\nA small AI gateway that can use GitHub Copilot, the built-in `codex` provider, or configured third-party providers such as DashScope. GitHub Copilot is optional: if no GitHub token is available, the server can still start in provider-only mode as long as at least one enabled provider is configured.\n\nThe gateway exposes OpenAI- and Anthropic-compatible APIs from one local endpoint, so tools like [Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview), OpenCode, Codex, and OpenAI-compatible clients can share the same local server.\n\nOn the GitHub Copilot path, the gateway prefers Copilot's native Anthropic-style Messages API when available, preserving more Claude-native behavior for tool-heavy workflows.\n\n## Features\n\n- **OpenAI and Anthropic compatibility**: Serve `/v1/responses`, `/v1/chat/completions`, `/v1/models`, `/v1/embeddings`, and `/v1/messages` from one local gateway.\n- **Copilot is optional**: Use GitHub Copilot when credentials are present, or run the server with only configured providers.\n- **One gateway for Copilot, `codex`, and external providers**: Route GitHub Copilot, the built-in `codex` provider, and configured third-party providers behind the same endpoint.\n- **Standalone third-party providers**: Configure providers such as DashScope, DeepSeek, OpenRouter, or a custom provider and start the gateway without a GitHub Copilot login.\n- **OpenAI-compatible providers on chat and Messages APIs**: `openai-compatible` providers can serve top-level `/v1/chat/completions` through `model: \"provider/model\"` and Anthropic-style `/v1/messages` through request/response translation.\n- **Agent-friendly Claude handling on Copilot**: Prefer native `/v1/messages` when available, preserve Claude-style tool flows, support Anthropic beta features, Claude WebSearch through Responses-capable models, and keep subagent/session markers intact.\n- **Claude Code and OpenCode integration**: Works with Claude Code and OpenCode, including direct Anthropic-compatible usage through `@ai-sdk/anthropic`.\n- **Flexible auth and deployment options**: Supports interactive login or direct tokens, individual/business/enterprise plans, GitHub Enterprise, opencode OAuth, and custom data directories.\n- **Multi-provider routing**: Expose provider-specific `/:provider/...` routes or use `model: \"provider/model\"` on the top-level API.\n\n## Prerequisites\n\n- Bun (>= 1.2.x)\n- Node.js if you plan to run the published CLI with `npx`\n- GitHub account with Copilot subscription only if you want to use the GitHub Copilot provider\n- An API key or OAuth login for at least one configured provider if you want to run without GitHub Copilot\n\n## Installation\n\nTo install dependencies, run:\n\n```sh\nbun install\n```\n\nTo start the server directly from source:\n\n```sh\nbun run start start\n```\n\n## Running from Source\n\nThe project can be run from source in several ways:\n\n### Development Mode\n\n```sh\nbun run dev start\n```\n\n### Production Mode\n\n```sh\nbun run start start\n```\n\n## Using with npx\n\nYou can run the project directly using npx:\n\n> [!IMPORTANT]\n> Token usage storage uses Node's built-in `node:sqlite` module when running with `npx`. It is enabled on Node.js >= 22.13.0. On Node.js < 22.13.0, the CLI still starts, but token usage storage is disabled.\n>\n> If you want token usage storage without upgrading Node.js, run the published CLI with Bun instead: `bunx --bun @jeffreycao/copilot-api@latest start`.\n\n```sh\nnpx @jeffreycao/copilot-api@latest start\n```\n\nWith options:\n\n```sh\nnpx @jeffreycao/copilot-api@latest start --port 8080\n```\n\nFor authentication or provider configuration only:\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth\n```\n\nTo run without GitHub Copilot, configure at least one provider first, then start the server normally:\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth login --provider dashscope\nnpx @jeffreycao/copilot-api@latest start\n```\n\n## Using with Docker\n\nBuild the image:\n\n```sh\ndocker build -t copilot-api .\n```\n\nRun the container with a bind mount so auth data survives restarts:\n\n```sh\nmkdir -p ./copilot-data\ndocker run -p 4141:4141 -v $(pwd)/copilot-data:/root/.local/share/copilot-api copilot-api\n```\n\nThis stores GitHub auth data, provider config, and other gateway state in `./copilot-data` on the host, mapped to `/root/.local/share/copilot-api` in the container.\n\nOr pass a GitHub token directly:\n\n```sh\ndocker run -p 4141:4141 -e GH_TOKEN=your_github_token_here copilot-api\n```\n\n## Electron Desktop App\n\nIf you prefer a GUI, this repository also includes an Electron desktop app in `desktop/`. It supports GitHub Copilot sign-in, OpenAI Codex OAuth, and API-key configuration for DeepSeek, DashScope, OpenRouter, or a custom provider. After authorization or provider configuration, it can start and stop the local proxy with one click and shows the local endpoint, auth header, available models, usage, and logs in the app.\n\nThe settings screen also exposes `OAuth App`, `API Home`, `Enterprise URL`, verbose logging, and minimize-to-tray. Desktop packages are published in GitHub Releases:\n\nhttps://github.com/caozhiyuan/copilot-api/releases\n\nDownload the installer for your platform, authorize or configure a provider inside the app, choose a port, start the server, then point your client at the local endpoint shown in the app. Packaged desktop builds use the bundled Electron runtime, so normal desktop usage does not require installing Node.js separately. Token usage history is enabled when that bundled runtime supports SQLite.\n\nThe desktop app's Advanced Config page reads and writes the shared model mappings through `GET/POST /admin/config/model-mappings`. The same mappings apply across `POST /v1/messages`, `POST /v1/messages/count_tokens`, `POST /v1/responses`, and `POST /v1/chat/completions` instead of being split per interface. It uses `auth.adminApiKey` instead of the regular `auth.apiKeys`, and the app reads that key directly from `config.json` after the server has generated it on startup.\n\n### Desktop App Screenshots\n\nMain dashboard, token usage breakdown in the bundled Electron app:\n\n<p align=\"center\">\n  <img src=\"./docs/screenshots/desktop-dashboard.png\" alt=\"Copilot API desktop app dashboard\" width=\"49%\" />\n  <img src=\"./docs/screenshots/desktop-token-usage.png\" alt=\"Copilot API desktop app token usage view\" width=\"49%\" />\n</p>\n\n## Using with Claude Code\n\nThis AI gateway can be used to power [Claude Code](https://docs.anthropic.com/en/claude-code), an experimental conversational AI assistant for developers from Anthropic.\n\nThere are two ways to configure Claude Code to use this AI gateway:\n\n### Interactive Setup with `--claude-code` flag\n\nTo get started, run the `start` command with the `--claude-code` flag:\n\n```sh\nnpx @jeffreycao/copilot-api@latest start --claude-code\n```\n\nYou will no longer be prompted to pick models manually. The gateway automatically detects the latest available model for each Claude Code size tier — opus maps to the newest Opus model, sonnet to the newest Sonnet model, and haiku to the newest Haiku model — and generates a command that sets `ANTHROPIC_DEFAULT_OPUS_MODEL`, `ANTHROPIC_DEFAULT_SONNET_MODEL`, and `ANTHROPIC_DEFAULT_HAIKU_MODEL` accordingly. Any tier without a matching model available is omitted. The command is copied to your clipboard and sets the environment variables needed for Claude Code to use the gateway.\n\nPaste and run this command in a new terminal to launch Claude Code.\n\n### Manual Configuration with `settings.json`\n\nAlternatively, you can configure Claude Code by creating a `.claude/settings.json` file in your project's root directory. This file should contain the environment variables needed by Claude Code. This way you don't need to run the interactive setup every time.\n\nHere is an example `.claude/settings.json` file:\n\n```json\n{\n  \"env\": {\n    \"ANTHROPIC_BASE_URL\": \"http://localhost:4141\",\n    \"ANTHROPIC_AUTH_TOKEN\": \"dummy\",\n    \"ANTHROPIC_MODEL\": \"codex/gpt-5.6-sol[1m]\",\n    \"ANTHROPIC_DEFAULT_SONNET_MODEL\": \"codex/gpt-5.6-sol[1m]\",\n    \"ANTHROPIC_DEFAULT_HAIKU_MODEL\": \"codex/gpt-5.6-luna[1m]\",\n    \"CLAUDE_CODE_AUTO_COMPACT_WINDOW\": \"272000\",\n    \"CLAUDE_CODE_USE_VERTEX\": \"0\",\n    \"CLAUDE_CODE_USE_BEDROCK\": \"0\",\n    \"DISABLE_NON_ESSENTIAL_MODEL_CALLS\": \"1\",\n    \"CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC\": \"1\",\n    \"CLAUDE_CODE_ATTRIBUTION_HEADER\": \"0\",\n    \"CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION\": \"false\",\n    \"CLAUDE_CODE_DISABLE_TERMINAL_TITLE\": \"true\",\n    \"CLAUDE_CODE_ENABLE_AWAY_SUMMARY\": \"0\"\n  },\n  \"permissions\": {\n    \"deny\": [\n      \"mcp__ide__executeCode\"\n    ]\n  }\n}\n```\n\n- Replace `ANTHROPIC_MODEL`, `ANTHROPIC_DEFAULT_OPUS_MODEL`, `ANTHROPIC_DEFAULT_SONNET_MODEL`, and `ANTHROPIC_DEFAULT_HAIKU_MODEL` according to your needs. After configuration, please install the claude code plugin [Plugin Integrations](#plugin-integrations).  \n- Setting CLAUDE_CODE_ATTRIBUTION_HEADER to 0 can prevent Claude code from adding billing and version information in system prompts, thereby avoiding prompt cache invalidation.\n- Turning off CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION and CLAUDE_CODE_ENABLE_AWAY_SUMMARY can prevent quota from being consumed unnecessarily.\n- Claude Code WebSearch is supported for pure search requests. For Copilot, keep the global `messageApiWebSearchModel` set to a Responses-capable GPT model or a `provider/model` alias. For provider routes, use a native Anthropic provider or an `openai-responses` provider. Add `WebSearch` to `permissions.deny` only if you want to forbid this traffic.\n- If using a non-Claude model, do not enable ENABLE_TOOL_SEARCH. If using the Claude model, can enable ENABLE_TOOL_SEARCH. The current Claude Code uses the client tool search mode. In this mode, loading defer tools requires an additional request each time.\n- `CLAUDE_CODE_AUTO_COMPACT_WINDOW`: Set the context capacity in tokens used for auto-compaction calculations. Defaults to the model's context window: 200K for standard models or 1M for extended context models. Use a lower value like `500000` on a 1M model (e.g., `claude-opus-4-6[1m]`) to treat the window as 500K for compaction purposes. The value is capped at the model's actual context window. `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` is applied as a percentage of this value. Setting this variable decouples the compaction threshold from the status line's `used_percentage`, which always uses the model's full context window.\n\nYou can find more options here: [Claude Code settings](https://docs.anthropic.com/en/docs/claude-code/settings#environment-variables)\n\nYou can also read more about IDE integration here: [Add Claude Code to your IDE](https://docs.anthropic.com/en/docs/claude-code/ide-integrations)\n\n## Using with OpenCode\n\nOpenCode already has a direct GitHub Copilot provider. Use this section when you want OpenCode to point at this AI gateway through `@ai-sdk/anthropic` and reuse the agent behaviors described earlier in this README.\n\n### Minimal setup\n\nStart the AI gateway with the OpenCode OAuth app:\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth --oauth-app=opencode\nnpx @jeffreycao/copilot-api@latest start\n```\n\nThen point OpenCode at the gateway with `@ai-sdk/anthropic`.\n\nExample `~/.config/opencode/opencode.json`:\n\n```json\n{\n  \"$schema\": \"https://opencode.ai/config.json\",\n  \"provider\": {\n    \"local\": {\n      \"npm\": \"@ai-sdk/anthropic\",\n      \"name\": \"My Local\",\n      \"options\": {\n        \"baseURL\": \"http://localhost:4141/v1\",\n        \"apiKey\": \"dummy\"\n      },\n      \"models\": {\n        \"gpt-5.4\": {\n          \"name\": \"gpt-5.4\",\n          \"modalities\": {\n            \"input\": [\"text\", \"image\"],\n            \"output\": [\"text\"]\n          },\n          \"limit\": {\n            \"context\": 400000,\n            \"input\": 272000,\n            \"output\": 128000\n          }\n        },\n        \"claude-sonnet-4.6\": {\n          \"id\": \"claude-sonnet-4.6\",\n          \"name\": \"claude-sonnet-4.6\",\n          \"modalities\": {\n            \"input\": [\"text\", \"image\"],\n            \"output\": [\"text\"]\n          },          \n          \"limit\": {\n            \"context\": 200000,\n            \"output\": 32000\n          },\n          \"options\": {\n            \"thinking\": {\n              \"type\": \"adaptive\"\n            },\n            \"effort\": \"max\"\n          }\n        }\n      }\n    }\n  }\n}\n```\n\nWhy these fields matter:\n\n- `npm: \"@ai-sdk/anthropic\"` is the important part. OpenCode will speak Anthropic Messages semantics to this AI gateway instead of flattening everything into OpenAI Chat Completions.\n- `options.baseURL` should be `http://localhost:4141/v1`; the Anthropic SDK will append `/messages`, `/models`, and `/messages/count_tokens` automatically.\n- If you enable `auth.apiKeys` in this AI gateway, replace `dummy` with a real key. Otherwise any placeholder value is fine.\n\n## Using with Codex\n\nThis AI gateway can also power Codex.\n\n### Codex `config.toml` Reference\n\nAdd the following `[model_providers.copilot_api]` section to your Codex `~/.codex/config.toml`:\n\n```toml\nmodel_provider = \"copilot_api\"\nmodel_reasoning_summary = \"auto\"\nmodel_context_window = 272000\nmodel_auto_compact_token_limit = 244800\n\n[model_providers.copilot_api]\nname = \"OpenAI\"\nbase_url = \"http://localhost:4141\"\nenv_key = \"GITHUB_COPILOT_API_KEY\"\nrequires_openai_auth = true\nsupports_websockets = false\nwire_api = \"responses\"\nrequest_max_retries = 3\nstream_max_retries = 1\nstream_idle_timeout_ms = 300000\n\n[features]\nremote_compaction_v2 = true\n\n[analytics]\nenabled = false\n```\n\n> [!NOTE]\n> This configuration is specific to Codex and the GitHub Copilot provider. `name` must be set to `\"OpenAI\"`. It can help mitigate Codex local compact cache miss issues.\n> If you are using the codex provider, it is recommended to set `base_url` to `\"http://localhost:4141/codex\"`.\n\n## GPT Tool Search\n\nFor GPT Responses models such as `gpt-5.4+`, this AI gateway can expose Responses `tool_search` through a small MCP bridge. The same bridge can be used by Claude Code and opencode, as long as the client loads MCP servers and sends Anthropic Messages traffic through this gateway.\n\nDo not set Claude Code's native `ENABLE_TOOL_SEARCH` for GPT models. That flag enables Claude Code's own client-side tool search mode, and it may stop forwarding deferred tool definitions. This gateway needs the full tool definitions so it can keep the small always-loaded tool set eager and translate every other tool into Responses deferred namespaces.\n\nIf you install `tool-search@copilot-api-marketplace`, Claude Code receives this MCP bridge automatically and you can skip the manual Claude Code MCP setup below.\n\nAdd the tool search bridge to the MCP config used by Claude Code:\n\n```json\n{\n  \"mcpServers\": {\n    \"tool_search\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@jeffreycao/copilot-api@latest\", \"mcp\"]\n    }\n  }\n}\n```\n\nAdd the tool search bridge to the MCP config used by opencode:\n\n```json\n{\n  \"mcp\": {\n    \"tool_search\": {\n      \"type\": \"local\",\n      \"command\": [\"npx\", \"-y\", \"@jeffreycao/copilot-api@latest\", \"mcp\"]\n    }\n  }\n}\n```\n\nFor local development, use `bun` as the command and `[\"run\", \"./src/main.ts\", \"mcp\"]` as the args.\n\nInternally, the gateway now configures OpenAI Responses `tool_search` in client-executed mode. Deferred tools are still exposed as searchable namespaces, but the model is explicitly asked to return the exact deferred tool names it wants to load next.\n\nThe bridge uses direct tool selection, not query search. Its tool input is `names`, a comma-separated list of exact deferred tool names, for example `TaskList,TaskGet,mcp__fetch__fetch`.\n\n## Plugin Integrations\n\nPlugin integrations are available for Claude Code and opencode.\n\n#### Claude Code plugin integration (marketplace-based)\n\nThe Claude Code integration is packaged as two plugins:\n\n- `agent-inject` injects `__SUBAGENT_MARKER__...` on `SubagentStart`, so the gateway can infer `x-initiator: agent`.\n- `tool-search` registers the `tool_search` MCP bridge used for GPT Responses deferred tool loading.\n\n- Marketplace catalog in this repository: `.claude-plugin/marketplace.json`\n- Plugin sources in this repository: `plugin/claude/agent-inject`, `plugin/claude/tool-search`\n\nAdd the marketplace remotely:\n\n```sh\n/plugin marketplace add https://github.com/caozhiyuan/copilot-api.git\n```\n\nInstall the plugins from the marketplace:\n\n```sh\n/plugin install agent-inject@copilot-api-marketplace\n/plugin install tool-search@copilot-api-marketplace\n```\n\nAfter installation, `agent-inject` injects `__SUBAGENT_MARKER__...` on `SubagentStart`, and the gateway uses it to infer `x-initiator: agent`.\n\nThe `agent-inject` plugin also registers a `UserPromptSubmit` hook that returns `{\"continue\": true}`, and it can inject `SessionStart` reminder rules through environment variables:\n\n- `CLAUDE_PLUGIN_ENABLE_QUESTION_RULES=1` enables the two reminders about using the `question` tool automatically for Claude Code. Alternatively, you can add the same reminders manually in `CLAUDE.md`; see [CLAUDE.md or AGENTS.md Recommended Content](#claudemd-or-agentsmd-recommended-content).\n- `CLAUDE_PLUGIN_ENABLE_NO_BACKGROUND_AGENTS_RULE=1` enables the `run_in_background: true` avoidance reminder for agent hooks.\n\nThe `tool-search` plugin bundles the same MCP bridge described in [GPT Tool Search](#gpt-tool-search), so Claude Code users do not need to add the `tool_search` server manually when they install that plugin.\n\n#### Opencode plugin\n\nThe subagent marker producer is packaged as an opencode plugin located at `plugin/opencode/subagent-marker.js`.\n\n**Installation:**\n\nCopy the plugin file to your opencode plugins directory:\n\n```sh\n# Clone or download this repository, then copy the plugin\ncp plugin/opencode/subagent-marker.js ~/.config/opencode/plugins/\n```\n\nOr manually create the file at `~/.config/opencode/plugins/subagent-marker.js` with the plugin content.\n\n**Features:**\n\n- Tracks sub-sessions created by subagents\n- Automatically prepends a marker system reminder (`__SUBAGENT_MARKER__...`) to subagent chat messages\n- Sets `x-session-id` header for session tracking\n- Enables the gateway to infer `x-initiator: agent` for subagent-originated requests\n\nThe plugin hooks into `session.created`, `session.deleted`, `chat.message`, and `chat.headers` events to provide seamless subagent marker functionality.\n\n## Using the Usage Viewer\n\nAfter starting the server, a URL to the Copilot Usage Dashboard will be displayed in your console. This dashboard is a web interface for monitoring your API usage.\n\n1.  Start the server. For example, using npx:\n    ```sh\n    npx @jeffreycao/copilot-api@latest start\n    ```\n2.  The server will output a URL to the usage viewer. Copy and paste this URL into your browser. It will look something like this:\n    `http://localhost:4141/usage-viewer?endpoint=http://localhost:4141/usage`\n    - If you use the `start.bat` script on Windows, this page will open automatically.\n\nThe dashboard provides a user-friendly interface to view your Copilot usage data:\n\n> Token usage history requires Bun or Node.js >= 22.13.0. On Node.js < 22.13.0, the server runs normally but token usage storage is disabled.\n\n- **API Endpoint URL**: The dashboard is pre-configured to fetch data from your local server endpoint via a URL query parameter. You can manually switch this to any other compatible API endpoint.\n- **x-api-key Authentication**: If API Key authentication is enabled, you can provide the `x-api-key` request header. The key is persisted in the browser's local storage.\n- **Period Selector**: Choose from Day, Week, or Month time ranges. The URL query parameter updates automatically when you switch, making it easy to bookmark and share.\n- **Fetch Data**: Click the \"Refresh\" button to load or refresh the usage data. The dashboard also fetches data automatically on page load.\n- **Copilot Quotas**: View quota usage for services such as Chat and Completions via progress bars. Hover over a card to see used/remaining details.\n- **Token Usage Metric Cards**: See a summary of Total, Input, Output, Cache Read, Cache Write, Requests, and estimated cost for the current period.\n- **Trend Chart (Week / Month)**: An interactive line chart with model and metric filters. Click a data point to inspect the usage breakdown for a specific day.\n- **Model Breakdown Table**: A per-model summary of requests, input/output/cache tokens, and estimated cost for the selected period.\n- **Request Events (Paginated)**: A time-sorted list of request event records with pagination support, showing timestamps, models, request IDs, and token counts.\n- **Detailed Information**: See the full JSON response from the API for a detailed breakdown of all available usage statistics.\n- **URL-based Configuration**: You can also specify the API endpoint and period directly via `endpoint` and `period` query parameters. For example:\n  `http://localhost:4141/usage-viewer?endpoint=http://your-api-server/usage&period=week`\n\n### Usage Viewer Screenshot\n\n<p align=\"center\">\n  <img src=\"./docs/screenshots/usage-viewer.png\" alt=\"Copilot API usage viewer\" width=\"900\" />\n</p>\n\n## Command Structure\n\nCopilot API now uses a subcommand structure with these main commands:\n\n- `start`: Start the gateway server. If a GitHub token is available, the server starts with Copilot enabled. If no GitHub token is available, it starts in provider-only mode when at least one enabled provider exists; otherwise it guides you through provider setup.\n- `auth`: Run provider login or configuration without starting the server. Use it for GitHub Copilot login, Codex OAuth, or third-party provider API key setup.\n- `debug`: Display diagnostic information including version, runtime details, file paths, and authentication status. Useful for troubleshooting and support.\n\n## Command Line Options\n\n### Global Options\n\nThe following options can be used with any subcommand. When passing them before the subcommand, use the `--key=value` form:\n\n| Option            | Description                                            | Default | Alias |\n| ----------------- | ------------------------------------------------------ | ------- | ----- |\n| --api-home        | Path to the API home directory (sets COPILOT_API_HOME) | none    | none  |\n| --oauth-app       | OAuth app identifier (sets COPILOT_API_OAUTH_APP)      | none    | none  |\n| --enterprise-url  | Enterprise URL for GitHub (sets COPILOT_API_ENTERPRISE_URL) | none | none |\n\n### Start Command Options\n\nThe following command line options are available for the `start` command:\n\n| Option         | Description                                                                   | Default    | Alias |\n| -------------- | ----------------------------------------------------------------------------- | ---------- | ----- |\n| --port         | Port to listen on                                                             | 4141       | -p    |\n| --verbose      | Enable verbose logging                                                        | false      | -v    |\n| --github-token | Provide GitHub token directly (must be generated using the `auth` subcommand) | none       | -g    |\n| --claude-code  | Generate a command to launch Claude Code with Copilot API config              | false      | -c    |\n| --show-token   | Show GitHub and Copilot tokens on fetch and refresh                           | false      | none  |\n| --proxy-env    | Initialize proxy from environment variables                                   | false      | none  |\n\n### Auth Command Options\n\n| Option       | Description               | Default | Alias |\n| ------------ | ------------------------- | ------- | ----- |\n| --provider   | Provider to log in with or configure (`copilot`, `codex`, `opencode-go`, `deepseek`, `dashscope`, `openrouter`, or `custom`) | prompt | none |\n| --verbose    | Enable verbose logging    | false   | -v    |\n| --show-token | Show GitHub token on auth | false   | none  |\n\nUse `copilot-api auth login --provider copilot` only when you want to enable the GitHub Copilot provider. Copilot is not required for `codex` or third-party provider-only usage.\n\nUse `copilot-api auth login --provider deepseek`, `--provider dashscope`, `--provider openrouter`, or `--provider opencode-go` to add or update those common third-party providers from the CLI. DeepSeek prompts for masked `apiKey`, provider `type` (default `anthropic`), and `baseUrl` defaulting to `https://api.deepseek.com/anthropic`. DashScope prompts for masked `apiKey`, provider `type` (default `openai-compatible`), and prefilled `baseUrl`. OpenRouter prompts for masked `apiKey` and prefilled `baseUrl` only, and writes `type: \"anthropic\"`. OpenCode Go prompts for masked `apiKey` and prefilled `baseUrl` only, and writes `type: \"openai-compatible\"` (baseUrl `https://opencode.ai/zen/go`). After a provider is configured and enabled, `copilot-api start` can run without any GitHub token.\n\nUse `copilot-api auth login --provider custom` to add or update another third-party provider from the CLI. The command prompts for the provider name, supported type (`anthropic`, `openai-compatible`, or `openai-responses`), `baseUrl`, masked `apiKey`, and `authType`; `authType` may be left as the type default or set to `x-api-key` / `authorization`.\n\n### Debug Command Options\n\n| Option | Description               | Default | Alias |\n| ------ | ------------------------- | ------- | ----- |\n| --json | Output debug info as JSON | false   | none  |\n\n## Configuration (config.json)\n\n- **Location:** `~/.local/share/copilot-api/config.json` (Linux/macOS) or `%USERPROFILE%\\.local\\share\\copilot-api\\config.json` (Windows).\n- **Default shape:**\n  ```json\n  {\n    \"auth\": {\n      \"apiKeys\": [],\n      \"adminApiKey\": \"<auto-generated-on-startup>\"\n    },\n    \"providers\": {},\n    \"modelMappings\": {},\n    \"extraPrompts\": {\n      \"gpt-5-mini\": \"<built-in exploration prompt>\"\n    },\n    \"smallModel\": \"gpt-5-mini\",\n    \"contextManagement\": {\n      \"messages\": true,\n      \"responses\": false\n    },\n    \"modelResponsesApiCompactThresholds\": {\n      \"gpt-5.4\": 217600,\n      \"gpt-5.5\": 217600,\n      \"gpt-5.6-sol\": 231200,\n      \"gpt-5.6-terra\": 231200,\n      \"gpt-5.6-luna\": 231200\n    },\n    \"modelReasoningEfforts\": {\n      \"gpt-5-mini\": \"low\"\n    },\n    \"useMessagesApi\": true,\n    \"useResponsesApiWebSocket\": true,\n    \"useResponsesApiWebSearch\": true,\n    \"messageApiWebSearchModel\": \"gpt-5-mini\"\n  }\n  ```\n- **auth.apiKeys:** API keys used for request authentication on non-admin routes. Supports multiple keys for rotation. Requests can authenticate with either `x-api-key: <key>` or `Authorization: Bearer <key>`. If empty or omitted, authentication for non-admin routes is disabled.\n- **auth.adminApiKey:** Single admin key used only for `/admin/*` routes. If missing, the server generates a random key at startup and writes it back to `config.json`. Requests use the same `x-api-key` or `Authorization: Bearer` headers, but regular `auth.apiKeys` never grant access to `/admin/*`.\n- **modelMappings:** Exact `sourceModel -> targetModel` rewrites shared by top-level `POST /v1/messages`, `POST /v1/messages/count_tokens`, `POST /v1/responses`, and `POST /v1/chat/completions` requests. Omit it or leave it as `{}` to disable rewrites. Both the source and target must be non-empty strings. Targets can be regular model IDs or `provider/model` aliases such as `dashscope/qwen3.6-plus`, and the rewrite happens before provider alias parsing. These mappings are not split per interface. The admin endpoints `GET/POST /admin/config/model-mappings` read and update only this field.\n- **extraPrompts:** Map of `model -> prompt` appended to the first system prompt when translating Anthropic-style requests to Responses API. Use this to inject guardrails or guidance per model. Missing default entries are auto-added without overwriting your custom prompts. For GPT-5.3+ models (e.g. `gpt-5.3-codex`, `gpt-5.4`, `gpt-5.5`), a built-in commentary prompt is used as fallback when not explicitly configured. The built-in prompts enable phase-aware commentary, which lets the model emit a short user-facing progress update before tools or deeper reasoning.\n- **providers:** Global upstream provider map. Each provider key (for example `dashscope`) becomes a route prefix (`/dashscope/v1/messages`). Supports `type: \"anthropic\"`, `type: \"openai-compatible\"`, and `type: \"openai-responses\"`. Top-level clients can also use `model: \"dashscope/model-id\"` with `/v1/messages`, `/v1/messages/count_tokens`, `/v1/responses`, and `/v1/chat/completions`; the gateway strips the `dashscope/` prefix before forwarding upstream. `openai-compatible` providers support both chat and Messages flows: `/v1/chat/completions` is proxied to upstream `/v1/chat/completions`, while `/v1/messages` and `/:provider/v1/messages` are translated to upstream chat completions and translated back to Anthropic Messages responses. `GET /v1/models` aggregates enabled provider models with `provider/model-id` IDs; use `GET /dashscope/v1/models` for a single provider's raw model list.\n  - `enabled` defaults to `true` if omitted.\n  - `baseUrl` should be provider API base URL without the final endpoint. For Anthropic providers, omit `/v1/messages`; for OpenAI-compatible providers, omit `/v1/chat/completions`; for OpenAI Responses providers, omit `/v1/responses`.\n  - `apiKey` is used as the upstream credential value and is required for regular providers.\n  - `authType` (optional): Controls how `apiKey` is sent upstream. Supports `x-api-key` and `authorization` for regular providers. Anthropic providers default to `x-api-key`; OpenAI-compatible and OpenAI Responses providers default to `authorization`. When set to `authorization`, the proxy sends `Authorization: Bearer <apiKey>`. `oauth2` is reserved for the built-in `codex` provider and is written automatically by `auth login --provider codex`.\n  - `pricingCurrency` (optional): Provider-level currency used for token cost calculation, for example `USD` or `CNY`. Quick providers default to `CNY` for DashScope and DeepSeek, and `USD` for Codex/OpenRouter. Costs are grouped by currency and are not exchange-rate converted.\n  - `models` (optional): Per-model configuration map. Each key is a model ID (matching the model name in requests), and the value is:\n    - `temperature` (optional): Default temperature value used when the request does not specify one.\n    - `topP` (optional): Default top_p value used when the request does not specify one.\n    - `topK` (optional): Default top_k value used when the request does not specify one.\n    - `extraBody` (optional): Dynamic fields merged into the upstream request body for that model. Request body fields with the same name take precedence. OpenAI-compatible providers can use this for fields such as `enable_thinking`, `preserve_thinking`, `reasoning_effort`. `thinking_budget` is a special OpenAI-compatible provider override: when configured in `extraBody`, it is forced after Anthropic `thinking.budget_tokens` translation and overrides the request-derived budget. For providers whose name is `dashscope` or whose `baseUrl` contains `aliyuncs.com`, the request-derived `thinking_budget` (from Anthropic `thinking.budget_tokens`) is forwarded upstream; for other OpenAI-compatible providers the request-derived `thinking_budget` is stripped, while an `extraBody` `thinking_budget` is still honored. For DashScope providers, `preserve_thinking` defaults to `true` when not explicitly set in `extraBody` or the request body.\n    - `pricing` (optional): Per-model token prices, in the provider `pricingCurrency`, per 1M tokens. Supported fields are `input`, `output`, `cachedInput` (implicit cache read), `explicitCachedInput` (explicit cache read), and `cacheCreationInput`. Use `tiers` with `maxInputTokens` for input-size tiered pricing.\n    - `contextCache` (optional): Defaults to `true` for providers whose name is `dashscope` or whose `baseUrl` contains `aliyuncs.com`; defaults to `false` for other OpenAI-compatible providers. This enables Alibaba Cloud Model Studio/DashScope explicit context cache by injecting `cache_control: { \"type\": \"ephemeral\" }` on up to 4 content blocks using the Context Cache format. The cache breakpoint strategy matches opencode's main provider flow: the first 2 system messages plus the last 2 non-system messages. Marked string content is converted to text content part arrays for `system` / `user` / `assistant` / `tool` messages; existing array content is marked on the last part. Set this to `false` when the model already supports implicit caching, or when the upstream does not accept this explicit-cache extension field. Set this to `true` for non-DashScope providers that support the same explicit-cache extension. Applied on both `/v1/messages` and `/v1/chat/completions` routes.\n    - `supportPdf` (optional): Controls whether the model supports PDF/document content. Defaults to `false`; unsupported PDFs are converted to a text notice. Set it to `true` to send PDF/document blocks as OpenAI Chat Completions file parts.\n    - `toolContentSupportType` (optional): Tool result content capabilities for that model, as an array of `array`, `image`, and `pdf`. Provider routes default to string-only tool content when omitted. If `supportPdf` is `true` but this list does not include `pdf`, file parts in tool results are moved to user role messages. This provider default does not change the Copilot main flow, which continues to support array + image and not PDF.\n    - `type` (optional): Per-model override of the provider protocol type. Supports `anthropic`, `openai-compatible`, and `openai-responses`. When set, the provider's `/v1/messages` route uses this model's type instead of the provider-level type for request routing, auth header resolution, and upstream endpoint selection. This is useful for providers like OpenCode Go whose upstream supports both OpenAI-compatible and Anthropic Messages APIs for different models. When the type is overridden, the auth header is resolved from the overridden type's default (Anthropic defaults to `x-api-key`; OpenAI-compatible/Responses default to `authorization`).\n\n  Example DashScope model settings:\n  ```json\n  {\n    \"providers\": {\n      \"dashscope\": {\n        \"type\": \"openai-compatible\",\n        \"enabled\": true,\n        \"baseUrl\": \"https://dashscope.aliyuncs.com/compatible-mode\",\n        \"apiKey\": \"sk-your-dashscope-key\",\n        \"pricingCurrency\": \"CNY\",\n        \"models\": {\n          \"qwen3.7-plus\": {\n            \"temperature\": 1,\n            \"topP\": 0.95,\n            \"topK\": 20,\n            \"extraBody\": {\n              \"preserve_thinking\": true\n            }\n          },\n          \"glm-5.1\": {\n            \"temperature\": 0.7,\n            \"topP\": 0.95,\n            \"contextCache\": true,\n            \"pricing\": {\n              \"tiers\": [\n                {\n                  \"maxInputTokens\": 32000,\n                  \"input\": 6,\n                  \"cachedInput\": 1.2,\n                  \"explicitCachedInput\": 0.6,\n                  \"cacheCreationInput\": 7.5,\n                  \"output\": 24\n                },\n                {\n                  \"maxInputTokens\": 200000,\n                  \"input\": 8,\n                  \"cachedInput\": 1.6,\n                  \"explicitCachedInput\": 0.8,\n                  \"cacheCreationInput\": 10,\n                  \"output\": 28\n                }\n              ]\n            },\n            \"extraBody\": {\n              \"preserve_thinking\": true\n            }\n          }\n        }\n      }\n    }\n  }\n  ```\n  Built-in token prices cover Codex GPT models in USD, DashScope `qwen3.7-max`, `qwen3.7-plus`, `glm-5.1`, `glm-5.2` in CNY, DeepSeek `deepseek-v4-flash`, `deepseek-v4-pro`, `deepseek-chat`, `deepseek-reasoner` in CNY, and OpenCode Go models (`glm-5.2`, `grok-4.5`, `deepseek-v4-flash`, `deepseek-v4-pro`, `kimi-k2.7-code`, `kimi-k3`, `mimo-v2.5`, `mimo-v2.5-pro`, `qwen3.7-plus`, `qwen3.7-max`, `minimax-m2.5`, `minimax-m3`) in USD. User `pricing` entries override built-ins. For DashScope, cached tokens are charged as explicit cache reads when the upstream usage includes `cache_creation_input_tokens`; otherwise `cachedInput` is used as the implicit cache read price. For DeepSeek, `prompt_cache_hit_tokens` map to cached input and `prompt_cache_miss_tokens` map to regular input.\n- **smallModel:** Fallback model used for tool-less warmup messages (e.g., Claude Code probe requests); defaults to gpt-5-mini.\n- **contextManagement:** Controls whether the proxy adds Responses API `context_management` compaction instructions. `messages` applies when Anthropic-style `/v1/messages` requests are translated to Responses API, including `openai-responses` provider message routes, and defaults to `true`. `responses` applies to native `/v1/responses` traffic, including `provider/model` aliases and the built-in `codex` provider, and defaults to `false`. Enable `responses` only after checking that your client supports context management compaction. When enabled, the request includes `context_management` in the body and keeps only the latest compaction carrier on follow-up turns. **Note:** Context management is forcibly disabled for GPT-5.6 and above models (e.g. `gpt-5.6-sol`, `gpt-5.6-terra`, `gpt-5.6-luna`) because enabling it breaks prompt cache hits on those models. This override takes precedence over the `contextManagement` and `modelResponsesApiCompactThresholds` settings.\n- **modelResponsesApiCompactThresholds:** Per-model Responses API `compact_threshold` overrides used when the proxy adds `context_management`. These values take precedence over the fallback threshold from `resolveResponsesCompactThreshold` (`max_prompt_tokens * ratio`, or the default fallback). Defaults set `gpt-5.4` and `gpt-5.5` to `217600` (`272000 * 0.8`), and `gpt-5.6-sol`, `gpt-5.6-terra`, `gpt-5.6-luna` to `231200` (`272000 * 0.85`). Models not listed continue to use the normal fallback logic.\n- **modelReasoningEfforts:** Per-model fallback reasoning effort for `/v1/messages` requests. It is used only when the request does not provide `output_config.effort`.\n  - **Priority:** request `output_config.effort` > `modelReasoningEfforts[model]` > built-in default (`xhigh` for GPT-5.3+ models, otherwise `high`).\n  - **Forwarding:** the resolved value remains `output_config.effort` for the Copilot native Messages API and becomes `reasoning.effort` when translated to the Responses API.\n  - **Configuration values:** `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`.\n- **useMessagesApi:** When `true`, Claude-family models that support Copilot's native `/v1/messages` endpoint will use the Messages API; otherwise they fall back to `/chat/completions`. Set to `false` to disable Messages API routing and always use `/chat/completions`. Defaults to `true`.\n- **useResponsesApiWebSocket:** When `true`, Responses API requests use Copilot's websocket transport for models that advertise `ws:/responses`; models that only advertise `/responses` continue to use HTTP. Set to `false` to disable websocket routing and use HTTP `/responses` whenever the selected model supports it. Defaults to `true`. If the Responses API WebSocket gets closed, it is usually caused by your own network. If you are using a VPN, try switching to a different node.\n- **useResponsesApiWebSearch:** When `true`, the server keeps Responses API tools with `type: \"web_search\"` and forwards them upstream. Set to `false` to strip those tools from `/responses` payloads. Defaults to `true`.\n- **messageApiWebSearchModel:** Global fallback model used when a top-level Copilot `/v1/messages` request contains only the server-side `web_search` tool. Defaults to `gpt-5-mini`. If the value is a `provider/model` alias, the request is routed into that provider's Messages API path with the provider prefix stripped. For Copilot GPT models, web search runs through `/responses`. Mixed `web_search` plus custom tools are not supported and the server-side `web_search` tool is stripped.\n- **claudeTokenMultiplier:** Multiplier applied to the fallback GPT-tokenizer estimate for Claude `/v1/messages/count_tokens` requests. Defaults to `1.15`. Increase it if your client is still compacting too late. This setting is only used when the proxy is estimating Claude tokens locally; if `anthropicApiKey` is configured and Anthropic token counting succeeds, the exact Anthropic count is returned instead.\n- **anthropicApiKey:** Anthropic API key used to forward Claude `/v1/messages/count_tokens` requests to Anthropic's real token counting endpoint, which returns exact counts instead of GPT tokenizer estimates. Can also be set via the `ANTHROPIC_API_KEY` environment variable. If not set, or if the upstream call fails, token counting falls back to local GPT tokenizer estimation controlled by `claudeTokenMultiplier`.\n\nEdit this file to customize prompts or swap in your own fast model. Restart the server (or rerun the command) after changes so the cached config is refreshed.\n\n## API Authentication\n\n- **Protected non-admin routes:** All routes except `/`, `/usage-viewer`, and `/usage-viewer/` require authentication when `auth.apiKeys` is configured and non-empty.\n- **Admin routes:** All `/admin/*` routes require `auth.adminApiKey`. If it is missing, the server generates one at startup and persists it to `config.json` before serving requests.\n- **Allowed auth headers:**\n  - `x-api-key: <your_key>`\n  - `Authorization: Bearer <your_key>`\n- **CORS preflight:** `OPTIONS` requests are always allowed.\n- **When no regular keys are configured:** Non-admin routes continue to allow requests. This does not apply to `/admin/*`, which only accepts `auth.adminApiKey`.\n\nExample request for a regular protected route:\n\n```sh\ncurl http://localhost:4141/v1/models \\\n  -H \"x-api-key: your_api_key\"\n```\n\nExample request for an admin route:\n\n```sh\ncurl http://localhost:4141/admin/config/model-mappings \\\n  -H \"x-api-key: your_admin_api_key\"\n```\n\n## API Endpoints\n\nThe server exposes several OpenAI- and Anthropic-compatible endpoints. Requests can target GitHub Copilot, the built-in `codex` provider, or configured providers depending on the selected model and `provider/model` alias.\n\n### OpenAI Compatible Endpoints\n\nThese endpoints mimic the OpenAI API structure.\n\n| Endpoint                    | Method | Description                                                      |\n| --------------------------- | ------ | ---------------------------------------------------------------- |\n| `POST /v1/responses`        | `POST` | OpenAI Most advanced interface for generating model responses. Supports `provider/model` aliases for `openai-responses` providers. |\n| `POST /v1/chat/completions` | `POST` | Creates a model response for the given chat conversation. Supports `provider/model` aliases for `openai-compatible` providers and can be used without Copilot when the target provider is configured. |\n| `GET /v1/models`            | `GET`  | Lists Copilot models plus enabled provider models using `provider/model-id` IDs. Requests from Codex clients (`User-Agent` beginning with `codex`) are forwarded to the Codex Models upstream. |\n| `POST /v1/embeddings`       | `POST` | Creates an embedding vector representing the input text.         |\n\n### Codex Backend Proxy Endpoints\n\nThese endpoints require an active Codex login. Each endpoint is available both without a version prefix and under `/v1`.\n\n| Endpoint | Method | Description |\n| --- | --- | --- |\n| `POST /alpha/search`<br>`POST /v1/alpha/search` | `POST` | Transparently forwards the JSON body and query parameters to the Codex Alpha Search upstream. |\n| `POST /images/generations`<br>`POST /v1/images/generations` | `POST` | Forwards a JSON image generation request to the Codex Images upstream. When the request omits `Content-Type`, the gateway defaults it to `application/json`. |\n| `POST /images/edits`<br>`POST /v1/images/edits` | `POST` | Forwards an image edit request to the Codex Images upstream. Send this request as `multipart/form-data` and let the HTTP client generate the `boundary`; the gateway preserves the incoming content type and streams the upload body. |\n\nFor every endpoint above, the gateway replaces client authorization and account headers with the active Codex login, preserves query parameters and compatible request headers, and returns the upstream status, headers, and body.\n\n### Anthropic Compatible Endpoints\n\nThese endpoints are designed to be compatible with the Anthropic Messages API. Provider-scoped models, Responses, alpha-search, and images routes accept both unversioned and `/v1` paths; Messages routes remain under `/v1`.\n\n| Endpoint                         | Method | Description                                                  |\n| -------------------------------- | ------ | ------------------------------------------------------------ |\n| `POST /v1/messages`              | `POST` | Creates a model response for a given conversation. Supports `provider/model` aliases for configured providers, including translation through `openai-compatible` providers. |\n| `POST /v1/messages/count_tokens` | `POST` | Calculates the number of tokens for a given set of messages. Supports `provider/model` aliases for configured providers. |\n| `POST /:provider/v1/messages`       | `POST` | Proxies Anthropic Messages requests to the configured Anthropic provider, translates them through an OpenAI-compatible provider, or translates them through an OpenAI Responses provider. |\n| `GET /:provider/models`<br>`GET /:provider/v1/models` | `GET` | Proxies model listing requests to the configured provider. For `codex`, returns the built-in catalog by default; Codex clients (`User-Agent` starting with `codex`) are forwarded to the Codex Models upstream. |\n| `POST /:provider/v1/messages/count_tokens` | `POST` | Calculates tokens locally for provider route requests. |\n| `POST /:provider/responses`<br>`POST /:provider/v1/responses` | `POST` | Proxies OpenAI Responses requests to a configured `openai-responses` provider (including `codex`). |\n| `POST /:provider/alpha/search`<br>`POST /:provider/v1/alpha/search` | `POST` | Proxies alpha-search requests. For `codex`, forwards to the Codex Alpha Search upstream; for other providers, forwards to `{baseUrl}/v1/alpha/search`. |\n| `POST /:provider/images/generations`<br>`POST /:provider/v1/images/generations` | `POST` | Proxies image generation. For `codex`, uses the Codex Images upstream; for other providers, forwards to `{baseUrl}/v1/images/generations` (15-minute timeout). |\n| `POST /:provider/images/edits`<br>`POST /:provider/v1/images/edits` | `POST` | Proxies image edits. For `codex`, uses the Codex Images upstream; for other providers, forwards multipart/streamed bodies to `{baseUrl}/v1/images/edits` (15-minute timeout). |\n\n### Usage Monitoring Endpoints\n\nNew endpoints for monitoring your Copilot usage and quotas.\n\n| Endpoint     | Method | Description                                                  |\n| ------------ | ------ | ------------------------------------------------------------ |\n| `GET /usage` | `GET`  | Get detailed Copilot usage statistics and quota information. |\n| `GET /token` | `GET`  | Get the current Copilot token being used by the API.         |\n\n### Admin / Configuration Endpoints\n\nThese endpoints are reserved for local administrative actions and only accept `auth.adminApiKey`.\n\n| Endpoint                              | Method | Description                                                                 |\n| ------------------------------------- | ------ | --------------------------------------------------------------------------- |\n| `GET /admin/config/model-mappings`    | `GET`  | Returns the current `config.json` path and the active `modelMappings` map.  |\n| `POST /admin/config/model-mappings`   | `POST` | Updates only the `modelMappings` field in `config.json` and returns it back. |\n\n## Example Usage\n\nCommon `npx` commands:\n\n```sh\n# Start the gateway\nnpx @jeffreycao/copilot-api@latest start\n\n# Start on a custom port with verbose logging\nnpx @jeffreycao/copilot-api@latest start --port 8080 --verbose\n\n# Run the auth flow\nnpx @jeffreycao/copilot-api@latest auth login\n\n# Configure a third-party provider, then run without GitHub Copilot\nnpx @jeffreycao/copilot-api@latest auth login --provider dashscope\nnpx @jeffreycao/copilot-api@latest start\n\n# Print debug information as JSON\nnpx @jeffreycao/copilot-api@latest debug --json\n\n# Run the published CLI with Bun instead of Node.js\nbunx --bun @jeffreycao/copilot-api@latest start\n```\n\nOpenAI-compatible provider examples after configuring `dashscope`:\n\n```sh\ncurl http://localhost:4141/v1/chat/completions \\\n  -H \"content-type: application/json\" \\\n  -d '{\"model\":\"dashscope/qwen3.6-plus\",\"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]}'\n\ncurl http://localhost:4141/dashscope/v1/messages \\\n  -H \"content-type: application/json\" \\\n  -d '{\"model\":\"qwen3.6-plus\",\"max_tokens\":1024,\"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]}'\n```\n\n## Usage Tips\n\n### CLAUDE.md or AGENTS.md Recommended Content\n\nTo add these reminders manually, include the following in `CLAUDE.md` for Claude Code, or `AGENTS.md` for opencode/codex:\n\n```\n- Prohibited from directly asking questions to users, MUST use question tool.\n- Once you can confirm that the task is complete, MUST use question tool to make user confirm. The user may respond with feedback if they are not satisfied with the result, which you can use to make improvements and try again, after try again, MUST use question tool to make user confirm again.\n```\n"}, "1043f72adafc89638932face4e837f7606e93a3e": {"t": 1785765544.0250666, "n": 50180, "h": "bc07d19ba0d89bb1", "c": "# Copilot API Proxy\n\nEnglish | [简体中文](./README.zh-CN.md)\n\n## Important Notes\n\n> [!IMPORTANT]\n> **Before using, please be aware of the following:**\n>\n> 1. **Claude Code configuration:** When using with Claude Code, please configure the model ID as `claude-opus-4-8`. Example claude `settings.json` see [Manual Configuration with `settings.json`](#manual-configuration-with-settingsjson). \n>\n> 2. **Built-in `copilot`, `codex` and third-party providers:** Run `npx @jeffreycao/copilot-api@latest auth` and choose `copilot`, `codex`, `deepseek`, `custom`, or other providers.\n>\n> 3. **Note:** See [GitHub Copilot Security Notice](./NOTICE.md#github-copilot-security-notice) for the warning removed from the README header.\n\n---\n\n## Project Overview\n\nA small AI gateway that can use GitHub Copilot, the built-in `codex` provider, or configured third-party providers such as DashScope. GitHub Copilot is optional: if no GitHub token is available, the server can still start in provider-only mode as long as at least one enabled provider is configured.\n\nThe gateway exposes OpenAI- and Anthropic-compatible APIs from one local endpoint, so tools like [Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview), OpenCode, Codex, and OpenAI-compatible clients can share the same local server.\n\nOn the GitHub Copilot path, the gateway prefers Copilot's native Anthropic-style Messages API when available, preserving more Claude-native behavior for tool-heavy workflows.\n\n## Features\n\n- **OpenAI and Anthropic compatibility**: Serve `/v1/responses`, `/v1/chat/completions`, `/v1/models`, `/v1/embeddings`, and `/v1/messages` from one local gateway.\n- **Copilot is optional**: Use GitHub Copilot when credentials are present, or run the server with only configured providers.\n- **One gateway for Copilot, `codex`, and external providers**: Route GitHub Copilot, the built-in `codex` provider, and configured third-party providers behind the same endpoint.\n- **Standalone third-party providers**: Configure providers such as DashScope, DeepSeek, OpenRouter, or a custom provider and start the gateway without a GitHub Copilot login.\n- **OpenAI-compatible providers on chat and Messages APIs**: `openai-compatible` providers can serve top-level `/v1/chat/completions` through `model: \"provider/model\"` and Anthropic-style `/v1/messages` through request/response translation.\n- **Agent-friendly Claude handling on Copilot**: Prefer native `/v1/messages` when available, preserve Claude-style tool flows, support Anthropic beta features, Claude WebSearch through Responses-capable models, and keep subagent/session markers intact.\n- **Claude Code and OpenCode integration**: Works with Claude Code and OpenCode, including direct Anthropic-compatible usage through `@ai-sdk/anthropic`.\n- **Flexible auth and deployment options**: Supports interactive login or direct tokens, individual/business/enterprise plans, GitHub Enterprise, opencode OAuth, and custom data directories.\n- **Multi-provider routing**: Expose provider-specific `/:provider/...` routes or use `model: \"provider/model\"` on the top-level API.\n\n## Prerequisites\n\n- Bun (>= 1.2.x)\n- Node.js if you plan to run the published CLI with `npx`\n- GitHub account with Copilot subscription only if you want to use the GitHub Copilot provider\n- An API key or OAuth login for at least one configured provider if you want to run without GitHub Copilot\n\n## Installation\n\nTo install dependencies, run:\n\n```sh\nbun install\n```\n\nTo start the server directly from source:\n\n```sh\nbun run start start\n```\n\n## Running from Source\n\nThe project can be run from source in several ways:\n\n### Development Mode\n\n```sh\nbun run dev start\n```\n\n### Production Mode\n\n```sh\nbun run start start\n```\n\n## Using with npx\n\nYou can run the project directly using npx:\n\n> [!IMPORTANT]\n> Token usage storage uses Node's built-in `node:sqlite` module when running with `npx`. It is enabled on Node.js >= 22.13.0. On Node.js < 22.13.0, the CLI still starts, but token usage storage is disabled.\n>\n> If you want token usage storage without upgrading Node.js, run the published CLI with Bun instead: `bunx --bun @jeffreycao/copilot-api@latest start`.\n\n```sh\nnpx @jeffreycao/copilot-api@latest start\n```\n\nWith options:\n\n```sh\nnpx @jeffreycao/copilot-api@latest start --port 8080\n```\n\nFor authentication or provider configuration only:\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth\n```\n\nTo run without GitHub Copilot, configure at least one provider first, then start the server normally:\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth login --provider dashscope\nnpx @jeffreycao/copilot-api@latest start\n```\n\n## Using with Docker\n\nBuild the image:\n\n```sh\ndocker build -t copilot-api .\n```\n\nRun the container with a bind mount so auth data survives restarts:\n\n```sh\nmkdir -p ./copilot-data\ndocker run -p 4141:4141 -v $(pwd)/copilot-data:/root/.local/share/copilot-api copilot-api\n```\n\nThis stores GitHub auth data, provider config, and other gateway state in `./copilot-data` on the host, mapped to `/root/.local/share/copilot-api` in the container.\n\nOr pass a GitHub token directly:\n\n```sh\ndocker run -p 4141:4141 -e GH_TOKEN=your_github_token_here copilot-api\n```\n\n## Electron Desktop App\n\nIf you prefer a GUI, this repository also includes an Electron desktop app in `desktop/`. It supports GitHub Copilot sign-in, OpenAI Codex OAuth, and API-key configuration for DeepSeek, DashScope, OpenRouter, or a custom provider. After authorization or provider configuration, it can start and stop the local proxy with one click and shows the local endpoint, auth header, available models, usage, and logs in the app.\n\nThe settings screen also exposes `OAuth App`, `API Home`, `Enterprise URL`, verbose logging, and minimize-to-tray. Desktop packages are published in GitHub Releases:\n\nhttps://github.com/caozhiyuan/copilot-api/releases\n\nDownload the installer for your platform, authorize or configure a provider inside the app, choose a port, start the server, then point your client at the local endpoint shown in the app. Packaged desktop builds use the bundled Electron runtime, so normal desktop usage does not require installing Node.js separately. Token usage history is enabled when that bundled runtime supports SQLite.\n\nThe desktop app's Advanced Config page reads and writes the shared model mappings through `GET/POST /admin/config/model-mappings`. The same mappings apply across `POST /v1/messages`, `POST /v1/messages/count_tokens`, `POST /v1/responses`, and `POST /v1/chat/completions` instead of being split per interface. It uses `auth.adminApiKey` instead of the regular `auth.apiKeys`, and the app reads that key directly from `config.json` after the server has generated it on startup.\n\n### Desktop App Screenshots\n\nMain dashboard, token usage breakdown in the bundled Electron app:\n\n<p align=\"center\">\n  <img src=\"./docs/screenshots/desktop-dashboard.png\" alt=\"Copilot API desktop app dashboard\" width=\"49%\" />\n  <img src=\"./docs/screenshots/desktop-token-usage.png\" alt=\"Copilot API desktop app token usage view\" width=\"49%\" />\n</p>\n\n## Using with Claude Code\n\nThis AI gateway can be used to power [Claude Code](https://docs.anthropic.com/en/claude-code), an experimental conversational AI assistant for developers from Anthropic.\n\nThere are two ways to configure Claude Code to use this AI gateway:\n\n### Interactive Setup with `--claude-code` flag\n\nTo get started, run the `start` command with the `--claude-code` flag:\n\n```sh\nnpx @jeffreycao/copilot-api@latest start --claude-code\n```\n\nYou will no longer be prompted to pick models manually. The gateway automatically detects the latest available model for each Claude Code size tier — opus maps to the newest Opus model, sonnet to the newest Sonnet model, and haiku to the newest Haiku model — and generates a command that sets `ANTHROPIC_DEFAULT_OPUS_MODEL`, `ANTHROPIC_DEFAULT_SONNET_MODEL`, and `ANTHROPIC_DEFAULT_HAIKU_MODEL` accordingly. Any tier without a matching model available is omitted. The command is copied to your clipboard and sets the environment variables needed for Claude Code to use the gateway.\n\nPaste and run this command in a new terminal to launch Claude Code.\n\n### Manual Configuration with `settings.json`\n\nAlternatively, you can configure Claude Code by creating a `.claude/settings.json` file in your project's root directory. This file should contain the environment variables needed by Claude Code. This way you don't need to run the interactive setup every time.\n\nHere is an example `.claude/settings.json` file:\n\n```json\n{\n  \"env\": {\n    \"ANTHROPIC_BASE_URL\": \"http://localhost:4141\",\n    \"ANTHROPIC_AUTH_TOKEN\": \"dummy\",\n    \"ANTHROPIC_MODEL\": \"deepseek/deepseek-v4-pro\",\n    \"ANTHROPIC_DEFAULT_SONNET_MODEL\": \"deepseek/deepseek-v4-pro\",\n    \"ANTHROPIC_DEFAULT_HAIKU_MODEL\": \"deepseek/deepseek-v4-flash\",\n    \"CLAUDE_CODE_USE_VERTEX\": \"0\",\n    \"CLAUDE_CODE_USE_BEDROCK\": \"0\",\n    \"DISABLE_NON_ESSENTIAL_MODEL_CALLS\": \"1\",\n    \"CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC\": \"1\",\n    \"CLAUDE_CODE_ATTRIBUTION_HEADER\": \"0\",\n    \"CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION\": \"false\",\n    \"CLAUDE_CODE_DISABLE_TERMINAL_TITLE\": \"true\",\n    \"CLAUDE_CODE_ENABLE_AWAY_SUMMARY\": \"0\"\n  },\n  \"permissions\": {\n    \"deny\": [\n      \"mcp__ide__executeCode\"\n    ]\n  }\n}\n```\n\n- Replace `ANTHROPIC_MODEL`, `ANTHROPIC_DEFAULT_OPUS_MODEL`, `ANTHROPIC_DEFAULT_SONNET_MODEL`, and `ANTHROPIC_DEFAULT_HAIKU_MODEL` according to your needs. After configuration, please install the claude code plugin [Plugin Integrations](#plugin-integrations).  \n- Setting CLAUDE_CODE_ATTRIBUTION_HEADER to 0 can prevent Claude code from adding billing and version information in system prompts, thereby avoiding prompt cache invalidation.\n- Turning off CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION and CLAUDE_CODE_ENABLE_AWAY_SUMMARY can prevent quota from being consumed unnecessarily.\n- Claude Code WebSearch is supported for pure search requests. For Copilot, keep the global `messageApiWebSearchModel` set to a Responses-capable GPT model or a `provider/model` alias. For provider routes, use a native Anthropic provider or an `openai-responses` provider. Add `WebSearch` to `permissions.deny` only if you want to forbid this traffic.\n- If using a non-Claude model, do not enable ENABLE_TOOL_SEARCH. If using the Claude model, can enable ENABLE_TOOL_SEARCH. The current Claude Code uses the client tool search mode. In this mode, loading defer tools requires an additional request each time.\n- `CLAUDE_CODE_AUTO_COMPACT_WINDOW`: Set the context capacity in tokens used for auto-compaction calculations. Defaults to the model's context window: 200K for standard models or 1M for extended context models. Use a lower value like `500000` on a 1M model (e.g., `claude-opus-4-6[1m]`) to treat the window as 500K for compaction purposes. The value is capped at the model's actual context window. `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` is applied as a percentage of this value. Setting this variable decouples the compaction threshold from the status line's `used_percentage`, which always uses the model's full context window.\n\nYou can find more options here: [Claude Code settings](https://docs.anthropic.com/en/docs/claude-code/settings#environment-variables)\n\nYou can also read more about IDE integration here: [Add Claude Code to your IDE](https://docs.anthropic.com/en/docs/claude-code/ide-integrations)\n\n## Using with OpenCode\n\nOpenCode already has a direct GitHub Copilot provider. Use this section when you want OpenCode to point at this AI gateway through `@ai-sdk/anthropic` and reuse the agent behaviors described earlier in this README.\n\n### Minimal setup\n\nStart the AI gateway with the OpenCode OAuth app:\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth --oauth-app=opencode\nnpx @jeffreycao/copilot-api@latest start\n```\n\nThen point OpenCode at the gateway with `@ai-sdk/anthropic`.\n\nExample `~/.config/opencode/opencode.json`:\n\n```json\n{\n  \"$schema\": \"https://opencode.ai/config.json\",\n  \"provider\": {\n    \"local\": {\n      \"npm\": \"@ai-sdk/anthropic\",\n      \"name\": \"My Local\",\n      \"options\": {\n        \"baseURL\": \"http://localhost:4141/v1\",\n        \"apiKey\": \"dummy\"\n      },\n      \"models\": {\n        \"gpt-5.4\": {\n          \"name\": \"gpt-5.4\",\n          \"modalities\": {\n            \"input\": [\"text\", \"image\"],\n            \"output\": [\"text\"]\n          },\n          \"limit\": {\n            \"context\": 400000,\n            \"input\": 272000,\n            \"output\": 128000\n          }\n        },\n        \"claude-sonnet-4.6\": {\n          \"id\": \"claude-sonnet-4.6\",\n          \"name\": \"claude-sonnet-4.6\",\n          \"modalities\": {\n            \"input\": [\"text\", \"image\"],\n            \"output\": [\"text\"]\n          },          \n          \"limit\": {\n            \"context\": 200000,\n            \"output\": 32000\n          },\n          \"options\": {\n            \"thinking\": {\n              \"type\": \"adaptive\"\n            },\n            \"effort\": \"max\"\n          }\n        }\n      }\n    }\n  }\n}\n```\n\nWhy these fields matter:\n\n- `npm: \"@ai-sdk/anthropic\"` is the important part. OpenCode will speak Anthropic Messages semantics to this AI gateway instead of flattening everything into OpenAI Chat Completions.\n- `options.baseURL` should be `http://localhost:4141/v1`; the Anthropic SDK will append `/messages`, `/models`, and `/messages/count_tokens` automatically.\n- If you enable `auth.apiKeys` in this AI gateway, replace `dummy` with a real key. Otherwise any placeholder value is fine.\n\n## Using with Codex\n\nThis AI gateway can also power Codex.\n\n### Codex `config.toml` Reference\n\nAdd the following `[model_providers.copilot_api]` section to your Codex `~/.codex/config.toml`:\n\n```toml\nmodel_provider = \"copilot_api\"\nmodel_reasoning_summary = \"auto\"\nmodel_context_window = 272000\nmodel_auto_compact_token_limit = 244800\n\n[model_providers.copilot_api]\nname = \"OpenAI\"\nbase_url = \"http://localhost:4141\"\nenv_key = \"GITHUB_COPILOT_API_KEY\"\nrequires_openai_auth = true\nsupports_websockets = false\nwire_api = \"responses\"\nrequest_max_retries = 3\nstream_max_retries = 1\nstream_idle_timeout_ms = 300000\n\n[features]\nremote_compaction_v2 = true\n\n[analytics]\nenabled = false\n```\n\n> [!NOTE]\n> This configuration is specific to Codex and the GitHub Copilot provider. `name` must be set to `\"OpenAI\"`. It can help mitigate Codex local compact cache miss issues.\n> If you are using the codex provider, it is recommended to set `base_url` to `\"http://localhost:4141/codex\"`.\n\n## GPT Tool Search\n\nFor GPT Responses models such as `gpt-5.4+`, this AI gateway can expose Responses `tool_search` through a small MCP bridge. The same bridge can be used by Claude Code and opencode, as long as the client loads MCP servers and sends Anthropic Messages traffic through this gateway.\n\nDo not set Claude Code's native `ENABLE_TOOL_SEARCH` for GPT models. That flag enables Claude Code's own client-side tool search mode, and it may stop forwarding deferred tool definitions. This gateway needs the full tool definitions so it can keep the small always-loaded tool set eager and translate every other tool into Responses deferred namespaces.\n\nIf you install `tool-search@copilot-api-marketplace`, Claude Code receives this MCP bridge automatically and you can skip the manual Claude Code MCP setup below.\n\nAdd the tool search bridge to the MCP config used by Claude Code:\n\n```json\n{\n  \"mcpServers\": {\n    \"tool_search\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@jeffreycao/copilot-api@latest\", \"mcp\"]\n    }\n  }\n}\n```\n\nAdd the tool search bridge to the MCP config used by opencode:\n\n```json\n{\n  \"mcp\": {\n    \"tool_search\": {\n      \"type\": \"local\",\n      \"command\": [\"npx\", \"-y\", \"@jeffreycao/copilot-api@latest\", \"mcp\"]\n    }\n  }\n}\n```\n\nFor local development, use `bun` as the command and `[\"run\", \"./src/main.ts\", \"mcp\"]` as the args.\n\nInternally, the gateway now configures OpenAI Responses `tool_search` in client-executed mode. Deferred tools are still exposed as searchable namespaces, but the model is explicitly asked to return the exact deferred tool names it wants to load next.\n\nThe bridge uses direct tool selection, not query search. Its tool input is `names`, a comma-separated list of exact deferred tool names, for example `TaskList,TaskGet,mcp__fetch__fetch`.\n\n## Plugin Integrations\n\nPlugin integrations are available for Claude Code and opencode.\n\n#### Claude Code plugin integration (marketplace-based)\n\nThe Claude Code integration is packaged as two plugins:\n\n- `agent-inject` injects `__SUBAGENT_MARKER__...` on `SubagentStart`, so the gateway can infer `x-initiator: agent`.\n- `tool-search` registers the `tool_search` MCP bridge used for GPT Responses deferred tool loading.\n\n- Marketplace catalog in this repository: `.claude-plugin/marketplace.json`\n- Plugin sources in this repository: `plugin/claude/agent-inject`, `plugin/claude/tool-search`\n\nAdd the marketplace remotely:\n\n```sh\n/plugin marketplace add https://github.com/caozhiyuan/copilot-api.git\n```\n\nInstall the plugins from the marketplace:\n\n```sh\n/plugin install agent-inject@copilot-api-marketplace\n/plugin install tool-search@copilot-api-marketplace\n```\n\nAfter installation, `agent-inject` injects `__SUBAGENT_MARKER__...` on `SubagentStart`, and the gateway uses it to infer `x-initiator: agent`.\n\nThe `agent-inject` plugin also registers a `UserPromptSubmit` hook that returns `{\"continue\": true}`, and it can inject `SessionStart` reminder rules through environment variables:\n\n- `CLAUDE_PLUGIN_ENABLE_QUESTION_RULES=1` enables the two reminders about using the `question` tool automatically for Claude Code. Alternatively, you can add the same reminders manually in `CLAUDE.md`; see [CLAUDE.md or AGENTS.md Recommended Content](#claudemd-or-agentsmd-recommended-content).\n- `CLAUDE_PLUGIN_ENABLE_NO_BACKGROUND_AGENTS_RULE=1` enables the `run_in_background: true` avoidance reminder for agent hooks.\n\nThe `tool-search` plugin bundles the same MCP bridge described in [GPT Tool Search](#gpt-tool-search), so Claude Code users do not need to add the `tool_search` server manually when they install that plugin.\n\n#### Opencode plugin\n\nThe subagent marker producer is packaged as an opencode plugin located at `plugin/opencode/subagent-marker.js`.\n\n**Installation:**\n\nCopy the plugin file to your opencode plugins directory:\n\n```sh\n# Clone or download this repository, then copy the plugin\ncp plugin/opencode/subagent-marker.js ~/.config/opencode/plugins/\n```\n\nOr manually create the file at `~/.config/opencode/plugins/subagent-marker.js` with the plugin content.\n\n**Features:**\n\n- Tracks sub-sessions created by subagents\n- Automatically prepends a marker system reminder (`__SUBAGENT_MARKER__...`) to subagent chat messages\n- Sets `x-session-id` header for session tracking\n- Enables the gateway to infer `x-initiator: agent` for subagent-originated requests\n\nThe plugin hooks into `session.created`, `session.deleted`, `chat.message`, and `chat.headers` events to provide seamless subagent marker functionality.\n\n## Using the Usage Viewer\n\nAfter starting the server, a URL to the Copilot Usage Dashboard will be displayed in your console. This dashboard is a web interface for monitoring your API usage.\n\n1.  Start the server. For example, using npx:\n    ```sh\n    npx @jeffreycao/copilot-api@latest start\n    ```\n2.  The server will output a URL to the usage viewer. Copy and paste this URL into your browser. It will look something like this:\n    `http://localhost:4141/usage-viewer?endpoint=http://localhost:4141/usage`\n    - If you use the `start.bat` script on Windows, this page will open automatically.\n\nThe dashboard provides a user-friendly interface to view your Copilot usage data:\n\n> Token usage history requires Bun or Node.js >= 22.13.0. On Node.js < 22.13.0, the server runs normally but token usage storage is disabled.\n\n- **API Endpoint URL**: The dashboard is pre-configured to fetch data from your local server endpoint via a URL query parameter. You can manually switch this to any other compatible API endpoint.\n- **x-api-key Authentication**: If API Key authentication is enabled, you can provide the `x-api-key` request header. The key is persisted in the browser's local storage.\n- **Period Selector**: Choose from Day, Week, or Month time ranges. The URL query parameter updates automatically when you switch, making it easy to bookmark and share.\n- **Fetch Data**: Click the \"Refresh\" button to load or refresh the usage data. The dashboard also fetches data automatically on page load.\n- **Copilot Quotas**: View quota usage for services such as Chat and Completions via progress bars. Hover over a card to see used/remaining details.\n- **Token Usage Metric Cards**: See a summary of Total, Input, Output, Cache Read, Cache Write, Requests, and estimated cost for the current period.\n- **Trend Chart (Week / Month)**: An interactive line chart with model and metric filters. Click a data point to inspect the usage breakdown for a specific day.\n- **Model Breakdown Table**: A per-model summary of requests, input/output/cache tokens, and estimated cost for the selected period.\n- **Request Events (Paginated)**: A time-sorted list of request event records with pagination support, showing timestamps, models, request IDs, and token counts.\n- **Detailed Information**: See the full JSON response from the API for a detailed breakdown of all available usage statistics.\n- **URL-based Configuration**: You can also specify the API endpoint and period directly via `endpoint` and `period` query parameters. For example:\n  `http://localhost:4141/usage-viewer?endpoint=http://your-api-server/usage&period=week`\n\n### Usage Viewer Screenshot\n\n<p align=\"center\">\n  <img src=\"./docs/screenshots/usage-viewer.png\" alt=\"Copilot API usage viewer\" width=\"900\" />\n</p>\n\n## Command Structure\n\nCopilot API now uses a subcommand structure with these main commands:\n\n- `start`: Start the gateway server. If a GitHub token is available, the server starts with Copilot enabled. If no GitHub token is available, it starts in provider-only mode when at least one enabled provider exists; otherwise it guides you through provider setup.\n- `auth`: Run provider login or configuration without starting the server. Use it for GitHub Copilot login, Codex OAuth, or third-party provider API key setup.\n- `debug`: Display diagnostic information including version, runtime details, file paths, and authentication status. Useful for troubleshooting and support.\n\n## Command Line Options\n\n### Global Options\n\nThe following options can be used with any subcommand. When passing them before the subcommand, use the `--key=value` form:\n\n| Option            | Description                                            | Default | Alias |\n| ----------------- | ------------------------------------------------------ | ------- | ----- |\n| --api-home        | Path to the API home directory (sets COPILOT_API_HOME) | none    | none  |\n| --oauth-app       | OAuth app identifier (sets COPILOT_API_OAUTH_APP)      | none    | none  |\n| --enterprise-url  | Enterprise URL for GitHub (sets COPILOT_API_ENTERPRISE_URL) | none | none |\n\n### Start Command Options\n\nThe following command line options are available for the `start` command:\n\n| Option         | Description                                                                   | Default    | Alias |\n| -------------- | ----------------------------------------------------------------------------- | ---------- | ----- |\n| --port         | Port to listen on                                                             | 4141       | -p    |\n| --verbose      | Enable verbose logging                                                        | false      | -v    |\n| --github-token | Provide GitHub token directly (must be generated using the `auth` subcommand) | none       | -g    |\n| --claude-code  | Generate a command to launch Claude Code with Copilot API config              | false      | -c    |\n| --show-token   | Show GitHub and Copilot tokens on fetch and refresh                           | false      | none  |\n| --proxy-env    | Initialize proxy from environment variables                                   | false      | none  |\n\n### Auth Command Options\n\n| Option       | Description               | Default | Alias |\n| ------------ | ------------------------- | ------- | ----- |\n| --provider   | Provider to log in with or configure (`copilot`, `codex`, `opencode-go`, `deepseek`, `dashscope`, `openrouter`, or `custom`) | prompt | none |\n| --verbose    | Enable verbose logging    | false   | -v    |\n| --show-token | Show GitHub token on auth | false   | none  |\n\nUse `copilot-api auth login --provider copilot` only when you want to enable the GitHub Copilot provider. Copilot is not required for `codex` or third-party provider-only usage.\n\nUse `copilot-api auth login --provider deepseek`, `--provider dashscope`, `--provider openrouter`, or `--provider opencode-go` to add or update those common third-party providers from the CLI. DeepSeek prompts for masked `apiKey`, provider `type` (default `anthropic`), and `baseUrl` defaulting to `https://api.deepseek.com/anthropic`. DashScope prompts for masked `apiKey`, provider `type` (default `openai-compatible`), and prefilled `baseUrl`. OpenRouter prompts for masked `apiKey` and prefilled `baseUrl` only, and writes `type: \"anthropic\"`. OpenCode Go prompts for masked `apiKey` and prefilled `baseUrl` only, and writes `type: \"openai-compatible\"` (baseUrl `https://opencode.ai/zen/go`). After a provider is configured and enabled, `copilot-api start` can run without any GitHub token.\n\nUse `copilot-api auth login --provider custom` to add or update another third-party provider from the CLI. The command prompts for the provider name, supported type (`anthropic`, `openai-compatible`, or `openai-responses`), `baseUrl`, masked `apiKey`, and `authType`; `authType` may be left as the type default or set to `x-api-key` / `authorization`.\n\n### Debug Command Options\n\n| Option | Description               | Default | Alias |\n| ------ | ------------------------- | ------- | ----- |\n| --json | Output debug info as JSON | false   | none  |\n\n## Configuration (config.json)\n\n- **Location:** `~/.local/share/copilot-api/config.json` (Linux/macOS) or `%USERPROFILE%\\.local\\share\\copilot-api\\config.json` (Windows).\n- **Default shape:**\n  ```json\n  {\n    \"auth\": {\n      \"apiKeys\": [],\n      \"adminApiKey\": \"<auto-generated-on-startup>\"\n    },\n    \"providers\": {},\n    \"modelMappings\": {},\n    \"extraPrompts\": {\n      \"gpt-5-mini\": \"<built-in exploration prompt>\"\n    },\n    \"smallModel\": \"gpt-5-mini\",\n    \"contextManagement\": {\n      \"messages\": true,\n      \"responses\": false\n    },\n    \"modelResponsesApiCompactThresholds\": {\n      \"gpt-5.4\": 217600,\n      \"gpt-5.5\": 217600,\n      \"gpt-5.6-sol\": 231200,\n      \"gpt-5.6-terra\": 231200,\n      \"gpt-5.6-luna\": 231200\n    },\n    \"modelReasoningEfforts\": {\n      \"gpt-5-mini\": \"low\"\n    },\n    \"useMessagesApi\": true,\n    \"useResponsesApiWebSocket\": true,\n    \"useResponsesApiWebSearch\": true,\n    \"messageApiWebSearchModel\": \"gpt-5-mini\"\n  }\n  ```\n- **auth.apiKeys:** API keys used for request authentication on non-admin routes. Supports multiple keys for rotation. Requests can authenticate with either `x-api-key: <key>` or `Authorization: Bearer <key>`. If empty or omitted, authentication for non-admin routes is disabled.\n- **auth.adminApiKey:** Single admin key used only for `/admin/*` routes. If missing, the server generates a random key at startup and writes it back to `config.json`. Requests use the same `x-api-key` or `Authorization: Bearer` headers, but regular `auth.apiKeys` never grant access to `/admin/*`.\n- **modelMappings:** Exact `sourceModel -> targetModel` rewrites shared by top-level `POST /v1/messages`, `POST /v1/messages/count_tokens`, `POST /v1/responses`, and `POST /v1/chat/completions` requests. Omit it or leave it as `{}` to disable rewrites. Both the source and target must be non-empty strings. Targets can be regular model IDs or `provider/model` aliases such as `dashscope/qwen3.6-plus`, and the rewrite happens before provider alias parsing. These mappings are not split per interface. The admin endpoints `GET/POST /admin/config/model-mappings` read and update only this field.\n- **extraPrompts:** Map of `model -> prompt` appended to the first system prompt when translating Anthropic-style requests to Responses API. Use this to inject guardrails or guidance per model. Missing default entries are auto-added without overwriting your custom prompts. For GPT-5.3+ models (e.g. `gpt-5.3-codex`, `gpt-5.4`, `gpt-5.5`), a built-in commentary prompt is used as fallback when not explicitly configured. The built-in prompts enable phase-aware commentary, which lets the model emit a short user-facing progress update before tools or deeper reasoning.\n- **providers:** Global upstream provider map. Each provider key (for example `dashscope`) becomes a route prefix (`/dashscope/v1/messages`). Supports `type: \"anthropic\"`, `type: \"openai-compatible\"`, and `type: \"openai-responses\"`. Top-level clients can also use `model: \"dashscope/model-id\"` with `/v1/messages`, `/v1/messages/count_tokens`, `/v1/responses`, and `/v1/chat/completions`; the gateway strips the `dashscope/` prefix before forwarding upstream. `openai-compatible` providers support both chat and Messages flows: `/v1/chat/completions` is proxied to upstream `/v1/chat/completions`, while `/v1/messages` and `/:provider/v1/messages` are translated to upstream chat completions and translated back to Anthropic Messages responses. `GET /v1/models` aggregates enabled provider models with `provider/model-id` IDs; use `GET /dashscope/v1/models` for a single provider's raw model list.\n  - `enabled` defaults to `true` if omitted.\n  - `baseUrl` should be provider API base URL without the final endpoint. For Anthropic providers, omit `/v1/messages`; for OpenAI-compatible providers, omit `/v1/chat/completions`; for OpenAI Responses providers, omit `/v1/responses`.\n  - `apiKey` is used as the upstream credential value and is required for regular providers.\n  - `authType` (optional): Controls how `apiKey` is sent upstream. Supports `x-api-key` and `authorization` for regular providers. Anthropic providers default to `x-api-key`; OpenAI-compatible and OpenAI Responses providers default to `authorization`. When set to `authorization`, the proxy sends `Authorization: Bearer <apiKey>`. `oauth2` is reserved for the built-in `codex` provider and is written automatically by `auth login --provider codex`.\n  - `pricingCurrency` (optional): Provider-level currency used for token cost calculation, for example `USD` or `CNY`. Quick providers default to `CNY` for DashScope and DeepSeek, and `USD` for Codex/OpenRouter. Costs are grouped by currency and are not exchange-rate converted.\n  - `models` (optional): Per-model configuration map. Each key is a model ID (matching the model name in requests), and the value is:\n    - `temperature` (optional): Default temperature value used when the request does not specify one.\n    - `topP` (optional): Default top_p value used when the request does not specify one.\n    - `topK` (optional): Default top_k value used when the request does not specify one.\n    - `extraBody` (optional): Dynamic fields merged into the upstream request body for that model. Request body fields with the same name take precedence. OpenAI-compatible providers can use this for fields such as `enable_thinking`, `preserve_thinking`, `reasoning_effort`. `thinking_budget` is a special OpenAI-compatible provider override: when configured in `extraBody`, it is forced after Anthropic `thinking.budget_tokens` translation and overrides the request-derived budget. For providers whose name is `dashscope` or whose `baseUrl` contains `aliyuncs.com`, the request-derived `thinking_budget` (from Anthropic `thinking.budget_tokens`) is forwarded upstream; for other OpenAI-compatible providers the request-derived `thinking_budget` is stripped, while an `extraBody` `thinking_budget` is still honored. For DashScope providers, `preserve_thinking` defaults to `true` when not explicitly set in `extraBody` or the request body.\n    - `pricing` (optional): Per-model token prices, in the provider `pricingCurrency`, per 1M tokens. Supported fields are `input`, `output`, `cachedInput` (implicit cache read), `explicitCachedInput` (explicit cache read), and `cacheCreationInput`. Use `tiers` with `maxInputTokens` for input-size tiered pricing.\n    - `contextCache` (optional): Defaults to `true` for providers whose name is `dashscope` or whose `baseUrl` contains `aliyuncs.com`; defaults to `false` for other OpenAI-compatible providers. This enables Alibaba Cloud Model Studio/DashScope explicit context cache by injecting `cache_control: { \"type\": \"ephemeral\" }` on up to 4 content blocks using the Context Cache format. The cache breakpoint strategy matches opencode's main provider flow: the first 2 system messages plus the last 2 non-system messages. Marked string content is converted to text content part arrays for `system` / `user` / `assistant` / `tool` messages; existing array content is marked on the last part. Set this to `false` when the model already supports implicit caching, or when the upstream does not accept this explicit-cache extension field. Set this to `true` for non-DashScope providers that support the same explicit-cache extension. Applied on both `/v1/messages` and `/v1/chat/completions` routes.\n    - `supportPdf` (optional): Controls whether the model supports PDF/document content. Defaults to `false`; unsupported PDFs are converted to a text notice. Set it to `true` to send PDF/document blocks as OpenAI Chat Completions file parts.\n    - `toolContentSupportType` (optional): Tool result content capabilities for that model, as an array of `array`, `image`, and `pdf`. Provider routes default to string-only tool content when omitted. If `supportPdf` is `true` but this list does not include `pdf`, file parts in tool results are moved to user role messages. This provider default does not change the Copilot main flow, which continues to support array + image and not PDF.\n    - `type` (optional): Per-model override of the provider protocol type. Supports `anthropic`, `openai-compatible`, and `openai-responses`. When set, the provider's `/v1/messages` route uses this model's type instead of the provider-level type for request routing, auth header resolution, and upstream endpoint selection. This is useful for providers like OpenCode Go whose upstream supports both OpenAI-compatible and Anthropic Messages APIs for different models. When the type is overridden, the auth header is resolved from the overridden type's default (Anthropic defaults to `x-api-key`; OpenAI-compatible/Responses default to `authorization`).\n\n  Example DashScope model settings:\n  ```json\n  {\n    \"providers\": {\n      \"dashscope\": {\n        \"type\": \"openai-compatible\",\n        \"enabled\": true,\n        \"baseUrl\": \"https://dashscope.aliyuncs.com/compatible-mode\",\n        \"apiKey\": \"sk-your-dashscope-key\",\n        \"pricingCurrency\": \"CNY\",\n        \"models\": {\n          \"qwen3.7-plus\": {\n            \"temperature\": 1,\n            \"topP\": 0.95,\n            \"topK\": 20,\n            \"extraBody\": {\n              \"preserve_thinking\": true\n            }\n          },\n          \"glm-5.1\": {\n            \"temperature\": 0.7,\n            \"topP\": 0.95,\n            \"contextCache\": true,\n            \"pricing\": {\n              \"tiers\": [\n                {\n                  \"maxInputTokens\": 32000,\n                  \"input\": 6,\n                  \"cachedInput\": 1.2,\n                  \"explicitCachedInput\": 0.6,\n                  \"cacheCreationInput\": 7.5,\n                  \"output\": 24\n                },\n                {\n                  \"maxInputTokens\": 200000,\n                  \"input\": 8,\n                  \"cachedInput\": 1.6,\n                  \"explicitCachedInput\": 0.8,\n                  \"cacheCreationInput\": 10,\n                  \"output\": 28\n                }\n              ]\n            },\n            \"extraBody\": {\n              \"preserve_thinking\": true\n            }\n          }\n        }\n      }\n    }\n  }\n  ```\n  Built-in token prices cover Codex GPT models in USD, DashScope `qwen3.7-max`, `qwen3.7-plus`, `glm-5.1`, `glm-5.2` in CNY, DeepSeek `deepseek-v4-flash`, `deepseek-v4-pro`, `deepseek-chat`, `deepseek-reasoner` in CNY, and OpenCode Go models (`glm-5.2`, `grok-4.5`, `deepseek-v4-flash`, `deepseek-v4-pro`, `kimi-k2.7-code`, `kimi-k3`, `mimo-v2.5`, `mimo-v2.5-pro`, `qwen3.7-plus`, `qwen3.7-max`, `minimax-m2.5`, `minimax-m3`) in USD. User `pricing` entries override built-ins. For DashScope, cached tokens are charged as explicit cache reads when the upstream usage includes `cache_creation_input_tokens`; otherwise `cachedInput` is used as the implicit cache read price. For DeepSeek, `prompt_cache_hit_tokens` map to cached input and `prompt_cache_miss_tokens` map to regular input.\n- **smallModel:** Fallback model used for tool-less warmup messages (e.g., Claude Code probe requests); defaults to gpt-5-mini.\n- **contextManagement:** Controls whether the proxy adds Responses API `context_management` compaction instructions. `messages` applies when Anthropic-style `/v1/messages` requests are translated to Responses API, including `openai-responses` provider message routes, and defaults to `true`. `responses` applies to native `/v1/responses` traffic, including `provider/model` aliases and the built-in `codex` provider, and defaults to `false`. Enable `responses` only after checking that your client supports context management compaction. When enabled, the request includes `context_management` in the body and keeps only the latest compaction carrier on follow-up turns. **Note:** Context management is forcibly disabled for GPT-5.6 and above models (e.g. `gpt-5.6-sol`, `gpt-5.6-terra`, `gpt-5.6-luna`) because enabling it breaks prompt cache hits on those models. This override takes precedence over the `contextManagement` and `modelResponsesApiCompactThresholds` settings.\n- **modelResponsesApiCompactThresholds:** Per-model Responses API `compact_threshold` overrides used when the proxy adds `context_management`. These values take precedence over the fallback threshold from `resolveResponsesCompactThreshold` (`max_prompt_tokens * ratio`, or the default fallback). Defaults set `gpt-5.4` and `gpt-5.5` to `217600` (`272000 * 0.8`), and `gpt-5.6-sol`, `gpt-5.6-terra`, `gpt-5.6-luna` to `231200` (`272000 * 0.85`). Models not listed continue to use the normal fallback logic.\n- **modelReasoningEfforts:** Per-model fallback reasoning effort for `/v1/messages` requests. It is used only when the request does not provide `output_config.effort`.\n  - **Priority:** request `output_config.effort` > `modelReasoningEfforts[model]` > built-in default (`xhigh` for GPT-5.3+ models, otherwise `high`).\n  - **Forwarding:** the resolved value remains `output_config.effort` for the Copilot native Messages API and becomes `reasoning.effort` when translated to the Responses API.\n  - **Configuration values:** `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`.\n- **useMessagesApi:** When `true`, Claude-family models that support Copilot's native `/v1/messages` endpoint will use the Messages API; otherwise they fall back to `/chat/completions`. Set to `false` to disable Messages API routing and always use `/chat/completions`. Defaults to `true`.\n- **useResponsesApiWebSocket:** When `true`, Responses API requests use Copilot's websocket transport for models that advertise `ws:/responses`; models that only advertise `/responses` continue to use HTTP. Set to `false` to disable websocket routing and use HTTP `/responses` whenever the selected model supports it. Defaults to `true`. If the Responses API WebSocket gets closed, it is usually caused by your own network. If you are using a VPN, try switching to a different node.\n- **useResponsesApiWebSearch:** When `true`, the server keeps Responses API tools with `type: \"web_search\"` and forwards them upstream. Set to `false` to strip those tools from `/responses` payloads. Defaults to `true`.\n- **messageApiWebSearchModel:** Global fallback model used when a top-level Copilot `/v1/messages` request contains only the server-side `web_search` tool. Defaults to `gpt-5-mini`. If the value is a `provider/model` alias, the request is routed into that provider's Messages API path with the provider prefix stripped. For Copilot GPT models, web search runs through `/responses`. Mixed `web_search` plus custom tools are not supported and the server-side `web_search` tool is stripped.\n- **claudeTokenMultiplier:** Multiplier applied to the fallback GPT-tokenizer estimate for Claude `/v1/messages/count_tokens` requests. Defaults to `1.15`. Increase it if your client is still compacting too late. This setting is only used when the proxy is estimating Claude tokens locally; if `anthropicApiKey` is configured and Anthropic token counting succeeds, the exact Anthropic count is returned instead.\n- **anthropicApiKey:** Anthropic API key used to forward Claude `/v1/messages/count_tokens` requests to Anthropic's real token counting endpoint, which returns exact counts instead of GPT tokenizer estimates. Can also be set via the `ANTHROPIC_API_KEY` environment variable. If not set, or if the upstream call fails, token counting falls back to local GPT tokenizer estimation controlled by `claudeTokenMultiplier`.\n\nEdit this file to customize prompts or swap in your own fast model. Restart the server (or rerun the command) after changes so the cached config is refreshed.\n\n## API Authentication\n\n- **Protected non-admin routes:** All routes except `/`, `/usage-viewer`, and `/usage-viewer/` require authentication when `auth.apiKeys` is configured and non-empty.\n- **Admin routes:** All `/admin/*` routes require `auth.adminApiKey`. If it is missing, the server generates one at startup and persists it to `config.json` before serving requests.\n- **Allowed auth headers:**\n  - `x-api-key: <your_key>`\n  - `Authorization: Bearer <your_key>`\n- **CORS preflight:** `OPTIONS` requests are always allowed.\n- **When no regular keys are configured:** Non-admin routes continue to allow requests. This does not apply to `/admin/*`, which only accepts `auth.adminApiKey`.\n\nExample request for a regular protected route:\n\n```sh\ncurl http://localhost:4141/v1/models \\\n  -H \"x-api-key: your_api_key\"\n```\n\nExample request for an admin route:\n\n```sh\ncurl http://localhost:4141/admin/config/model-mappings \\\n  -H \"x-api-key: your_admin_api_key\"\n```\n\n## API Endpoints\n\nThe server exposes several OpenAI- and Anthropic-compatible endpoints. Requests can target GitHub Copilot, the built-in `codex` provider, or configured providers depending on the selected model and `provider/model` alias.\n\n### OpenAI Compatible Endpoints\n\nThese endpoints mimic the OpenAI API structure.\n\n| Endpoint                    | Method | Description                                                      |\n| --------------------------- | ------ | ---------------------------------------------------------------- |\n| `POST /v1/responses`        | `POST` | OpenAI Most advanced interface for generating model responses. Supports `provider/model` aliases for `openai-responses` providers. |\n| `POST /v1/chat/completions` | `POST` | Creates a model response for the given chat conversation. Supports `provider/model` aliases for `openai-compatible` providers and can be used without Copilot when the target provider is configured. |\n| `GET /v1/models`            | `GET`  | Lists Copilot models plus enabled provider models using `provider/model-id` IDs. Requests from Codex clients (`User-Agent` beginning with `codex`) are forwarded to the Codex Models upstream. |\n| `POST /v1/embeddings`       | `POST` | Creates an embedding vector representing the input text.         |\n\n### Codex Backend Proxy Endpoints\n\nThese endpoints require an active Codex login. Each endpoint is available both without a version prefix and under `/v1`.\n\n| Endpoint | Method | Description |\n| --- | --- | --- |\n| `POST /alpha/search`<br>`POST /v1/alpha/search` | `POST` | Transparently forwards the JSON body and query parameters to the Codex Alpha Search upstream. |\n| `POST /images/generations`<br>`POST /v1/images/generations` | `POST` | Forwards a JSON image generation request to the Codex Images upstream. When the request omits `Content-Type`, the gateway defaults it to `application/json`. |\n| `POST /images/edits`<br>`POST /v1/images/edits` | `POST` | Forwards an image edit request to the Codex Images upstream. Send this request as `multipart/form-data` and let the HTTP client generate the `boundary`; the gateway preserves the incoming content type and streams the upload body. |\n\nFor every endpoint above, the gateway replaces client authorization and account headers with the active Codex login, preserves query parameters and compatible request headers, and returns the upstream status, headers, and body.\n\n### Anthropic Compatible Endpoints\n\nThese endpoints are designed to be compatible with the Anthropic Messages API. Provider-scoped models, Responses, alpha-search, and images routes accept both unversioned and `/v1` paths; Messages routes remain under `/v1`.\n\n| Endpoint                         | Method | Description                                                  |\n| -------------------------------- | ------ | ------------------------------------------------------------ |\n| `POST /v1/messages`              | `POST` | Creates a model response for a given conversation. Supports `provider/model` aliases for configured providers, including translation through `openai-compatible` providers. |\n| `POST /v1/messages/count_tokens` | `POST` | Calculates the number of tokens for a given set of messages. Supports `provider/model` aliases for configured providers. |\n| `POST /:provider/v1/messages`       | `POST` | Proxies Anthropic Messages requests to the configured Anthropic provider, translates them through an OpenAI-compatible provider, or translates them through an OpenAI Responses provider. |\n| `GET /:provider/models`<br>`GET /:provider/v1/models` | `GET` | Proxies model listing requests to the configured provider. For `codex`, returns the built-in catalog by default; Codex clients (`User-Agent` starting with `codex`) are forwarded to the Codex Models upstream. |\n| `POST /:provider/v1/messages/count_tokens` | `POST` | Calculates tokens locally for provider route requests. |\n| `POST /:provider/responses`<br>`POST /:provider/v1/responses` | `POST` | Proxies OpenAI Responses requests to a configured `openai-responses` provider (including `codex`). |\n| `POST /:provider/alpha/search`<br>`POST /:provider/v1/alpha/search` | `POST` | Proxies alpha-search requests. For `codex`, forwards to the Codex Alpha Search upstream; for other providers, forwards to `{baseUrl}/v1/alpha/search`. |\n| `POST /:provider/images/generations`<br>`POST /:provider/v1/images/generations` | `POST` | Proxies image generation. For `codex`, uses the Codex Images upstream; for other providers, forwards to `{baseUrl}/v1/images/generations` (15-minute timeout). |\n| `POST /:provider/images/edits`<br>`POST /:provider/v1/images/edits` | `POST` | Proxies image edits. For `codex`, uses the Codex Images upstream; for other providers, forwards multipart/streamed bodies to `{baseUrl}/v1/images/edits` (15-minute timeout). |\n\n### Usage Monitoring Endpoints\n\nNew endpoints for monitoring your Copilot usage and quotas.\n\n| Endpoint     | Method | Description                                                  |\n| ------------ | ------ | ------------------------------------------------------------ |\n| `GET /usage` | `GET`  | Get detailed Copilot usage statistics and quota information. |\n| `GET /token` | `GET`  | Get the current Copilot token being used by the API.         |\n\n### Admin / Configuration Endpoints\n\nThese endpoints are reserved for local administrative actions and only accept `auth.adminApiKey`.\n\n| Endpoint                              | Method | Description                                                                 |\n| ------------------------------------- | ------ | --------------------------------------------------------------------------- |\n| `GET /admin/config/model-mappings`    | `GET`  | Returns the current `config.json` path and the active `modelMappings` map.  |\n| `POST /admin/config/model-mappings`   | `POST` | Updates only the `modelMappings` field in `config.json` and returns it back. |\n\n## Example Usage\n\nCommon `npx` commands:\n\n```sh\n# Start the gateway\nnpx @jeffreycao/copilot-api@latest start\n\n# Start on a custom port with verbose logging\nnpx @jeffreycao/copilot-api@latest start --port 8080 --verbose\n\n# Run the auth flow\nnpx @jeffreycao/copilot-api@latest auth login\n\n# Configure a third-party provider, then run without GitHub Copilot\nnpx @jeffreycao/copilot-api@latest auth login --provider dashscope\nnpx @jeffreycao/copilot-api@latest start\n\n# Print debug information as JSON\nnpx @jeffreycao/copilot-api@latest debug --json\n\n# Run the published CLI with Bun instead of Node.js\nbunx --bun @jeffreycao/copilot-api@latest start\n```\n\nOpenAI-compatible provider examples after configuring `dashscope`:\n\n```sh\ncurl http://localhost:4141/v1/chat/completions \\\n  -H \"content-type: application/json\" \\\n  -d '{\"model\":\"dashscope/qwen3.6-plus\",\"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]}'\n\ncurl http://localhost:4141/dashscope/v1/messages \\\n  -H \"content-type: application/json\" \\\n  -d '{\"model\":\"qwen3.6-plus\",\"max_tokens\":1024,\"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]}'\n```\n\n## Usage Tips\n\n### CLAUDE.md or AGENTS.md Recommended Content\n\nTo add these reminders manually, include the following in `CLAUDE.md` for Claude Code, or `AGENTS.md` for opencode/codex:\n\n```\n- Prohibited from directly asking questions to users, MUST use question tool.\n- Once you can confirm that the task is complete, MUST use question tool to make user confirm. The user may respond with feedback if they are not satisfied with the result, which you can use to make improvements and try again, after try again, MUST use question tool to make user confirm again.\n```\n"}, "201ab8f1d74eaa72deec7a1de83cbac439927561": {"t": 1785765545.523269, "n": 50157, "h": "09f8b586337f9853", "c": "# Copilot API Proxy\n\nEnglish | [简体中文](./README.zh-CN.md)\n\n## Important Notes\n\n> [!IMPORTANT]\n> **Before using, please be aware of the following:**\n>\n> 1. **Claude Code configuration:** When using with Claude Code, please configure the model ID as `claude-opus-4-8`. Example claude `settings.json` see [Manual Configuration with `settings.json`](#manual-configuration-with-settingsjson). \n>\n> 2. **Built-in `copilot`, `codex` and third-party providers:** Run `npx @jeffreycao/copilot-api@latest auth` and choose `copilot`, `codex`, `deepseek`, `custom`, or other providers.\n>\n> 3. **Note:** See [GitHub Copilot Security Notice](./NOTICE.md#github-copilot-security-notice) for the warning removed from the README header.\n\n---\n\n## Project Overview\n\nA small AI gateway that can use GitHub Copilot, the built-in `codex` provider, or configured third-party providers such as DashScope. GitHub Copilot is optional: if no GitHub token is available, the server can still start in provider-only mode as long as at least one enabled provider is configured.\n\nThe gateway exposes OpenAI- and Anthropic-compatible APIs from one local endpoint, so tools like [Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview), OpenCode, Codex, and OpenAI-compatible clients can share the same local server.\n\nOn the GitHub Copilot path, the gateway prefers Copilot's native Anthropic-style Messages API when available, preserving more Claude-native behavior for tool-heavy workflows.\n\n## Features\n\n- **OpenAI and Anthropic compatibility**: Serve `/v1/responses`, `/v1/chat/completions`, `/v1/models`, `/v1/embeddings`, and `/v1/messages` from one local gateway.\n- **Copilot is optional**: Use GitHub Copilot when credentials are present, or run the server with only configured providers.\n- **One gateway for Copilot, `codex`, and external providers**: Route GitHub Copilot, the built-in `codex` provider, and configured third-party providers behind the same endpoint.\n- **Standalone third-party providers**: Configure providers such as DashScope, DeepSeek, OpenRouter, or a custom provider and start the gateway without a GitHub Copilot login.\n- **OpenAI-compatible providers on chat and Messages APIs**: `openai-compatible` providers can serve top-level `/v1/chat/completions` through `model: \"provider/model\"` and Anthropic-style `/v1/messages` through request/response translation.\n- **Agent-friendly Claude handling on Copilot**: Prefer native `/v1/messages` when available, preserve Claude-style tool flows, support Anthropic beta features, Claude WebSearch through Responses-capable models, and keep subagent/session markers intact.\n- **Claude Code and OpenCode integration**: Works with Claude Code and OpenCode, including direct Anthropic-compatible usage through `@ai-sdk/anthropic`.\n- **Flexible auth and deployment options**: Supports interactive login or direct tokens, individual/business/enterprise plans, GitHub Enterprise, opencode OAuth, and custom data directories.\n- **Multi-provider routing**: Expose provider-specific `/:provider/...` routes or use `model: \"provider/model\"` on the top-level API.\n\n## Prerequisites\n\n- Bun (>= 1.2.x)\n- Node.js if you plan to run the published CLI with `npx`\n- GitHub account with Copilot subscription only if you want to use the GitHub Copilot provider\n- An API key or OAuth login for at least one configured provider if you want to run without GitHub Copilot\n\n## Installation\n\nTo install dependencies, run:\n\n```sh\nbun install\n```\n\nTo start the server directly from source:\n\n```sh\nbun run start start\n```\n\n## Running from Source\n\nThe project can be run from source in several ways:\n\n### Development Mode\n\n```sh\nbun run dev start\n```\n\n### Production Mode\n\n```sh\nbun run start start\n```\n\n## Using with npx\n\nYou can run the project directly using npx:\n\n> [!IMPORTANT]\n> Token usage storage uses Node's built-in `node:sqlite` module when running with `npx`. It is enabled on Node.js >= 22.13.0. On Node.js < 22.13.0, the CLI still starts, but token usage storage is disabled.\n>\n> If you want token usage storage without upgrading Node.js, run the published CLI with Bun instead: `bunx --bun @jeffreycao/copilot-api@latest start`.\n\n```sh\nnpx @jeffreycao/copilot-api@latest start\n```\n\nWith options:\n\n```sh\nnpx @jeffreycao/copilot-api@latest start --port 8080\n```\n\nFor authentication or provider configuration only:\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth\n```\n\nTo run without GitHub Copilot, configure at least one provider first, then start the server normally:\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth login --provider dashscope\nnpx @jeffreycao/copilot-api@latest start\n```\n\n## Using with Docker\n\nBuild the image:\n\n```sh\ndocker build -t copilot-api .\n```\n\nRun the container with a bind mount so auth data survives restarts:\n\n```sh\nmkdir -p ./copilot-data\ndocker run -p 4141:4141 -v $(pwd)/copilot-data:/root/.local/share/copilot-api copilot-api\n```\n\nThis stores GitHub auth data, provider config, and other gateway state in `./copilot-data` on the host, mapped to `/root/.local/share/copilot-api` in the container.\n\nOr pass a GitHub token directly:\n\n```sh\ndocker run -p 4141:4141 -e GH_TOKEN=your_github_token_here copilot-api\n```\n\n## Electron Desktop App\n\nIf you prefer a GUI, this repository also includes an Electron desktop app in `desktop/`. It supports GitHub Copilot sign-in, OpenAI Codex OAuth, and API-key configuration for DeepSeek, DashScope, OpenRouter, or a custom provider. After authorization or provider configuration, it can start and stop the local proxy with one click and shows the local endpoint, auth header, available models, usage, and logs in the app.\n\nThe settings screen also exposes `OAuth App`, `API Home`, `Enterprise URL`, verbose logging, and minimize-to-tray. Desktop packages are published in GitHub Releases:\n\nhttps://github.com/caozhiyuan/copilot-api/releases\n\nDownload the installer for your platform, authorize or configure a provider inside the app, choose a port, start the server, then point your client at the local endpoint shown in the app. Packaged desktop builds use the bundled Electron runtime, so normal desktop usage does not require installing Node.js separately. Token usage history is enabled when that bundled runtime supports SQLite.\n\nThe desktop app's Advanced Config page reads and writes the shared model mappings through `GET/POST /admin/config/model-mappings`. The same mappings apply across `POST /v1/messages`, `POST /v1/messages/count_tokens`, `POST /v1/responses`, and `POST /v1/chat/completions` instead of being split per interface. It uses `auth.adminApiKey` instead of the regular `auth.apiKeys`, and the app reads that key directly from `config.json` after the server has generated it on startup.\n\n### Desktop App Screenshots\n\nMain dashboard, token usage breakdown in the bundled Electron app:\n\n<p align=\"center\">\n  <img src=\"./docs/screenshots/desktop-dashboard.png\" alt=\"Copilot API desktop app dashboard\" width=\"49%\" />\n  <img src=\"./docs/screenshots/desktop-token-usage.png\" alt=\"Copilot API desktop app token usage view\" width=\"49%\" />\n</p>\n\n## Using with Claude Code\n\nThis AI gateway can be used to power [Claude Code](https://docs.anthropic.com/en/claude-code), an experimental conversational AI assistant for developers from Anthropic.\n\nThere are two ways to configure Claude Code to use this AI gateway:\n\n### Interactive Setup with `--claude-code` flag\n\nTo get started, run the `start` command with the `--claude-code` flag:\n\n```sh\nnpx @jeffreycao/copilot-api@latest start --claude-code\n```\n\nYou will no longer be prompted to pick models manually. The gateway automatically detects the latest available model for each Claude Code size tier — opus maps to the newest Opus model, sonnet to the newest Sonnet model, and haiku to the newest Haiku model — and generates a command that sets `ANTHROPIC_DEFAULT_OPUS_MODEL`, `ANTHROPIC_DEFAULT_SONNET_MODEL`, and `ANTHROPIC_DEFAULT_HAIKU_MODEL` accordingly. Any tier without a matching model available is omitted. The command is copied to your clipboard and sets the environment variables needed for Claude Code to use the gateway.\n\nPaste and run this command in a new terminal to launch Claude Code.\n\n### Manual Configuration with `settings.json`\n\nAlternatively, you can configure Claude Code by creating a `.claude/settings.json` file in your project's root directory. This file should contain the environment variables needed by Claude Code. This way you don't need to run the interactive setup every time.\n\nHere is an example `.claude/settings.json` file:\n\n```json\n{\n  \"env\": {\n    \"ANTHROPIC_BASE_URL\": \"http://localhost:4141\",\n    \"ANTHROPIC_AUTH_TOKEN\": \"dummy\",\n    \"ANTHROPIC_MODEL\": \"deepseek/deepseek-v4-pro\",\n    \"ANTHROPIC_DEFAULT_SONNET_MODEL\": \"deepseek/deepseek-v4-pro\",\n    \"ANTHROPIC_DEFAULT_HAIKU_MODEL\": \"deepseek/deepseek-v4-flash\",\n    \"CLAUDE_CODE_USE_VERTEX\": \"0\",\n    \"CLAUDE_CODE_USE_BEDROCK\": \"0\",\n    \"DISABLE_NON_ESSENTIAL_MODEL_CALLS\": \"1\",\n    \"CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC\": \"1\",\n    \"CLAUDE_CODE_ATTRIBUTION_HEADER\": \"0\",\n    \"CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION\": \"false\",\n    \"CLAUDE_CODE_DISABLE_TERMINAL_TITLE\": \"true\",\n    \"CLAUDE_CODE_ENABLE_AWAY_SUMMARY\": \"0\"\n  },\n  \"permissions\": {\n    \"deny\": [\n      \"mcp__ide__executeCode\"\n    ]\n  }\n}\n```\n\n- Replace `ANTHROPIC_MODEL`, `ANTHROPIC_DEFAULT_OPUS_MODEL`, `ANTHROPIC_DEFAULT_SONNET_MODEL`, and `ANTHROPIC_DEFAULT_HAIKU_MODEL` according to your needs. After configuration, please install the claude code plugin [Plugin Integrations](#plugin-integrations).  \n- Setting CLAUDE_CODE_ATTRIBUTION_HEADER to 0 can prevent Claude code from adding billing and version information in system prompts, thereby avoiding prompt cache invalidation.\n- Turning off CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION and CLAUDE_CODE_ENABLE_AWAY_SUMMARY can prevent quota from being consumed unnecessarily.\n- Claude Code WebSearch is supported for pure search requests. For Copilot, keep the global `messageApiWebSearchModel` set to a Responses-capable GPT model or a `provider/model` alias. For provider routes, use a native Anthropic provider or an `openai-responses` provider. Add `WebSearch` to `permissions.deny` only if you want to forbid this traffic.\n- If using a non-Claude model, do not enable ENABLE_TOOL_SEARCH. If using the Claude model, can enable ENABLE_TOOL_SEARCH. The current Claude Code uses the client tool search mode. In this mode, loading defer tools requires an additional request each time.\n- `CLAUDE_CODE_AUTO_COMPACT_WINDOW`: Set the context capacity in tokens used for auto-compaction calculations. Defaults to the model's context window: 200K for standard models or 1M for extended context models. Use a lower value like `500000` on a 1M model (e.g., `claude-opus-4-6[1m]`) to treat the window as 500K for compaction purposes. The value is capped at the model's actual context window. `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` is applied as a percentage of this value. Setting this variable decouples the compaction threshold from the status line's `used_percentage`, which always uses the model's full context window.\n\nYou can find more options here: [Claude Code settings](https://docs.anthropic.com/en/docs/claude-code/settings#environment-variables)\n\nYou can also read more about IDE integration here: [Add Claude Code to your IDE](https://docs.anthropic.com/en/docs/claude-code/ide-integrations)\n\n## Using with OpenCode\n\nOpenCode already has a direct GitHub Copilot provider. Use this section when you want OpenCode to point at this AI gateway through `@ai-sdk/anthropic` and reuse the agent behaviors described earlier in this README.\n\n### Minimal setup\n\nStart the AI gateway with the OpenCode OAuth app:\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth --oauth-app=opencode\nnpx @jeffreycao/copilot-api@latest start\n```\n\nThen point OpenCode at the gateway with `@ai-sdk/anthropic`.\n\nExample `~/.config/opencode/opencode.json`:\n\n```json\n{\n  \"$schema\": \"https://opencode.ai/config.json\",\n  \"provider\": {\n    \"local\": {\n      \"npm\": \"@ai-sdk/anthropic\",\n      \"name\": \"My Local\",\n      \"options\": {\n        \"baseURL\": \"http://localhost:4141/v1\",\n        \"apiKey\": \"dummy\"\n      },\n      \"models\": {\n        \"gpt-5.4\": {\n          \"name\": \"gpt-5.4\",\n          \"modalities\": {\n            \"input\": [\"text\", \"image\"],\n            \"output\": [\"text\"]\n          },\n          \"limit\": {\n            \"context\": 400000,\n            \"input\": 272000,\n            \"output\": 128000\n          }\n        },\n        \"claude-sonnet-4.6\": {\n          \"id\": \"claude-sonnet-4.6\",\n          \"name\": \"claude-sonnet-4.6\",\n          \"modalities\": {\n            \"input\": [\"text\", \"image\"],\n            \"output\": [\"text\"]\n          },          \n          \"limit\": {\n            \"context\": 200000,\n            \"output\": 32000\n          },\n          \"options\": {\n            \"thinking\": {\n              \"type\": \"adaptive\"\n            },\n            \"effort\": \"max\"\n          }\n        }\n      }\n    }\n  }\n}\n```\n\nWhy these fields matter:\n\n- `npm: \"@ai-sdk/anthropic\"` is the important part. OpenCode will speak Anthropic Messages semantics to this AI gateway instead of flattening everything into OpenAI Chat Completions.\n- `options.baseURL` should be `http://localhost:4141/v1`; the Anthropic SDK will append `/messages`, `/models`, and `/messages/count_tokens` automatically.\n- If you enable `auth.apiKeys` in this AI gateway, replace `dummy` with a real key. Otherwise any placeholder value is fine.\n\n## Using with Codex\n\nThis AI gateway can also power Codex.\n\n### Codex `config.toml` Reference\n\nAdd the following `[model_providers.copilot_api]` section to your Codex `~/.codex/config.toml`:\n\n```toml\nmodel_provider = \"copilot_api\"\nmodel_reasoning_summary = \"auto\"\nmodel_context_window = 272000\nmodel_auto_compact_token_limit = 244800\n\n[model_providers.copilot_api]\nname = \"OpenAI\"\nbase_url = \"http://localhost:4141\"\nenv_key = \"GITHUB_COPILOT_API_KEY\"\nrequires_openai_auth = true\nsupports_websockets = false\nwire_api = \"responses\"\nrequest_max_retries = 3\nstream_max_retries = 1\nstream_idle_timeout_ms = 300000\n\n[features]\nremote_compaction_v2 = true\n\n[analytics]\nenabled = false\n```\n\n> [!NOTE]\n> This configuration is specific to Codex and the GitHub Copilot provider. `name` must be set to `\"OpenAI\"`. It can help mitigate Codex local compact cache miss issues.\n> If you are using the codex provider, it is recommended to set `base_url` to `\"http://localhost:4141/codex\"`.\n\n## GPT Tool Search\n\nFor GPT Responses models such as `gpt-5.4+`, this AI gateway can expose Responses `tool_search` through a small MCP bridge. The same bridge can be used by Claude Code and opencode, as long as the client loads MCP servers and sends Anthropic Messages traffic through this gateway.\n\nDo not set Claude Code's native `ENABLE_TOOL_SEARCH` for GPT models. That flag enables Claude Code's own client-side tool search mode, and it may stop forwarding deferred tool definitions. This gateway needs the full tool definitions so it can keep the small always-loaded tool set eager and translate every other tool into Responses deferred namespaces.\n\nIf you install `tool-search@copilot-api-marketplace`, Claude Code receives this MCP bridge automatically and you can skip the manual Claude Code MCP setup below.\n\nAdd the tool search bridge to the MCP config used by Claude Code:\n\n```json\n{\n  \"mcpServers\": {\n    \"tool_search\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@jeffreycao/copilot-api@latest\", \"mcp\"]\n    }\n  }\n}\n```\n\nAdd the tool search bridge to the MCP config used by opencode:\n\n```json\n{\n  \"mcp\": {\n    \"tool_search\": {\n      \"type\": \"local\",\n      \"command\": [\"npx\", \"-y\", \"@jeffreycao/copilot-api@latest\", \"mcp\"]\n    }\n  }\n}\n```\n\nFor local development, use `bun` as the command and `[\"run\", \"./src/main.ts\", \"mcp\"]` as the args.\n\nInternally, the gateway now configures OpenAI Responses `tool_search` in client-executed mode. Deferred tools are still exposed as searchable namespaces, but the model is explicitly asked to return the exact deferred tool names it wants to load next.\n\nThe bridge uses direct tool selection, not query search. Its tool input is `names`, a comma-separated list of exact deferred tool names, for example `TaskList,TaskGet,mcp__fetch__fetch`.\n\n## Plugin Integrations\n\nPlugin integrations are available for Claude Code and opencode.\n\n#### Claude Code plugin integration (marketplace-based)\n\nThe Claude Code integration is packaged as two plugins:\n\n- `agent-inject` injects `__SUBAGENT_MARKER__...` on `SubagentStart`, so the gateway can infer `x-initiator: agent`.\n- `tool-search` registers the `tool_search` MCP bridge used for GPT Responses deferred tool loading.\n\n- Marketplace catalog in this repository: `.claude-plugin/marketplace.json`\n- Plugin sources in this repository: `plugin/claude/agent-inject`, `plugin/claude/tool-search`\n\nAdd the marketplace remotely:\n\n```sh\n/plugin marketplace add https://github.com/caozhiyuan/copilot-api.git\n```\n\nInstall the plugins from the marketplace:\n\n```sh\n/plugin install agent-inject@copilot-api-marketplace\n/plugin install tool-search@copilot-api-marketplace\n```\n\nAfter installation, `agent-inject` injects `__SUBAGENT_MARKER__...` on `SubagentStart`, and the gateway uses it to infer `x-initiator: agent`.\n\nThe `agent-inject` plugin also registers a `UserPromptSubmit` hook that returns `{\"continue\": true}`, and it can inject `SessionStart` reminder rules through environment variables:\n\n- `CLAUDE_PLUGIN_ENABLE_QUESTION_RULES=1` enables the two reminders about using the `question` tool automatically for Claude Code. Alternatively, you can add the same reminders manually in `CLAUDE.md`; see [CLAUDE.md or AGENTS.md Recommended Content](#claudemd-or-agentsmd-recommended-content).\n- `CLAUDE_PLUGIN_ENABLE_NO_BACKGROUND_AGENTS_RULE=1` enables the `run_in_background: true` avoidance reminder for agent hooks.\n\nThe `tool-search` plugin bundles the same MCP bridge described in [GPT Tool Search](#gpt-tool-search), so Claude Code users do not need to add the `tool_search` server manually when they install that plugin.\n\n#### Opencode plugin\n\nThe subagent marker producer is packaged as an opencode plugin located at `plugin/opencode/subagent-marker.js`.\n\n**Installation:**\n\nCopy the plugin file to your opencode plugins directory:\n\n```sh\n# Clone or download this repository, then copy the plugin\ncp plugin/opencode/subagent-marker.js ~/.config/opencode/plugins/\n```\n\nOr manually create the file at `~/.config/opencode/plugins/subagent-marker.js` with the plugin content.\n\n**Features:**\n\n- Tracks sub-sessions created by subagents\n- Automatically prepends a marker system reminder (`__SUBAGENT_MARKER__...`) to subagent chat messages\n- Sets `x-session-id` header for session tracking\n- Enables the gateway to infer `x-initiator: agent` for subagent-originated requests\n\nThe plugin hooks into `session.created`, `session.deleted`, `chat.message`, and `chat.headers` events to provide seamless subagent marker functionality.\n\n## Using the Usage Viewer\n\nAfter starting the server, a URL to the Copilot Usage Dashboard will be displayed in your console. This dashboard is a web interface for monitoring your API usage.\n\n1.  Start the server. For example, using npx:\n    ```sh\n    npx @jeffreycao/copilot-api@latest start\n    ```\n2.  The server will output a URL to the usage viewer. Copy and paste this URL into your browser. It will look something like this:\n    `http://localhost:4141/usage-viewer?endpoint=http://localhost:4141/usage`\n    - If you use the `start.bat` script on Windows, this page will open automatically.\n\nThe dashboard provides a user-friendly interface to view your Copilot usage data:\n\n> Token usage history requires Bun or Node.js >= 22.13.0. On Node.js < 22.13.0, the server runs normally but token usage storage is disabled.\n\n- **API Endpoint URL**: The dashboard is pre-configured to fetch data from your local server endpoint via a URL query parameter. You can manually switch this to any other compatible API endpoint.\n- **x-api-key Authentication**: If API Key authentication is enabled, you can provide the `x-api-key` request header. The key is persisted in the browser's local storage.\n- **Period Selector**: Choose from Day, Week, or Month time ranges. The URL query parameter updates automatically when you switch, making it easy to bookmark and share.\n- **Fetch Data**: Click the \"Refresh\" button to load or refresh the usage data. The dashboard also fetches data automatically on page load.\n- **Copilot Quotas**: View quota usage for services such as Chat and Completions via progress bars. Hover over a card to see used/remaining details.\n- **Token Usage Metric Cards**: See a summary of Total, Input, Output, Cache Read, Cache Write, Requests, and estimated cost for the current period.\n- **Trend Chart (Week / Month)**: An interactive line chart with model and metric filters. Click a data point to inspect the usage breakdown for a specific day.\n- **Model Breakdown Table**: A per-model summary of requests, input/output/cache tokens, and estimated cost for the selected period.\n- **Request Events (Paginated)**: A time-sorted list of request event records with pagination support, showing timestamps, models, request IDs, and token counts.\n- **Detailed Information**: See the full JSON response from the API for a detailed breakdown of all available usage statistics.\n- **URL-based Configuration**: You can also specify the API endpoint and period directly via `endpoint` and `period` query parameters. For example:\n  `http://localhost:4141/usage-viewer?endpoint=http://your-api-server/usage&period=week`\n\n### Usage Viewer Screenshot\n\n<p align=\"center\">\n  <img src=\"./docs/screenshots/usage-viewer.png\" alt=\"Copilot API usage viewer\" width=\"900\" />\n</p>\n\n## Command Structure\n\nCopilot API now uses a subcommand structure with these main commands:\n\n- `start`: Start the gateway server. If a GitHub token is available, the server starts with Copilot enabled. If no GitHub token is available, it starts in provider-only mode when at least one enabled provider exists; otherwise it guides you through provider setup.\n- `auth`: Run provider login or configuration without starting the server. Use it for GitHub Copilot login, Codex OAuth, or third-party provider API key setup.\n- `debug`: Display diagnostic information including version, runtime details, file paths, and authentication status. Useful for troubleshooting and support.\n\n## Command Line Options\n\n### Global Options\n\nThe following options can be used with any subcommand. When passing them before the subcommand, use the `--key=value` form:\n\n| Option            | Description                                            | Default | Alias |\n| ----------------- | ------------------------------------------------------ | ------- | ----- |\n| --api-home        | Path to the API home directory (sets COPILOT_API_HOME) | none    | none  |\n| --oauth-app       | OAuth app identifier (sets COPILOT_API_OAUTH_APP)      | none    | none  |\n| --enterprise-url  | Enterprise URL for GitHub (sets COPILOT_API_ENTERPRISE_URL) | none | none |\n\n### Start Command Options\n\nThe following command line options are available for the `start` command:\n\n| Option         | Description                                                                   | Default    | Alias |\n| -------------- | ----------------------------------------------------------------------------- | ---------- | ----- |\n| --port         | Port to listen on                                                             | 4141       | -p    |\n| --verbose      | Enable verbose logging                                                        | false      | -v    |\n| --github-token | Provide GitHub token directly (must be generated using the `auth` subcommand) | none       | -g    |\n| --claude-code  | Generate a command to launch Claude Code with Copilot API config              | false      | -c    |\n| --show-token   | Show GitHub and Copilot tokens on fetch and refresh                           | false      | none  |\n| --proxy-env    | Initialize proxy from environment variables                                   | false      | none  |\n\n### Auth Command Options\n\n| Option       | Description               | Default | Alias |\n| ------------ | ------------------------- | ------- | ----- |\n| --provider   | Provider to log in with or configure (`copilot`, `codex`, `opencode-go`, `deepseek`, `dashscope`, `openrouter`, or `custom`) | prompt | none |\n| --verbose    | Enable verbose logging    | false   | -v    |\n| --show-token | Show GitHub token on auth | false   | none  |\n\nUse `copilot-api auth login --provider copilot` only when you want to enable the GitHub Copilot provider. Copilot is not required for `codex` or third-party provider-only usage.\n\nUse `copilot-api auth login --provider deepseek`, `--provider dashscope`, `--provider openrouter`, or `--provider opencode-go` to add or update those common third-party providers from the CLI. DeepSeek prompts for masked `apiKey`, provider `type` (default `anthropic`), and `baseUrl` defaulting to `https://api.deepseek.com/anthropic`. DashScope prompts for masked `apiKey`, provider `type` (default `openai-compatible`), and prefilled `baseUrl`. OpenRouter prompts for masked `apiKey` and prefilled `baseUrl` only, and writes `type: \"anthropic\"`. OpenCode Go prompts for masked `apiKey` and prefilled `baseUrl` only, and writes `type: \"openai-compatible\"` (baseUrl `https://opencode.ai/zen/go`). After a provider is configured and enabled, `copilot-api start` can run without any GitHub token.\n\nUse `copilot-api auth login --provider custom` to add or update another third-party provider from the CLI. The command prompts for the provider name, supported type (`anthropic`, `openai-compatible`, or `openai-responses`), `baseUrl`, masked `apiKey`, and `authType`; `authType` may be left as the type default or set to `x-api-key` / `authorization`.\n\n### Debug Command Options\n\n| Option | Description               | Default | Alias |\n| ------ | ------------------------- | ------- | ----- |\n| --json | Output debug info as JSON | false   | none  |\n\n## Configuration (config.json)\n\n- **Location:** `~/.local/share/copilot-api/config.json` (Linux/macOS) or `%USERPROFILE%\\.local\\share\\copilot-api\\config.json` (Windows).\n- **Default shape:**\n  ```json\n  {\n    \"auth\": {\n      \"apiKeys\": [],\n      \"adminApiKey\": \"<auto-generated-on-startup>\"\n    },\n    \"providers\": {},\n    \"modelMappings\": {},\n    \"extraPrompts\": {\n      \"gpt-5-mini\": \"<built-in exploration prompt>\"\n    },\n    \"smallModel\": \"gpt-5-mini\",\n    \"contextManagement\": {\n      \"messages\": true,\n      \"responses\": false\n    },\n    \"modelResponsesApiCompactThresholds\": {\n      \"gpt-5.4\": 217600,\n      \"gpt-5.5\": 217600,\n      \"gpt-5.6-sol\": 231200,\n      \"gpt-5.6-terra\": 231200,\n      \"gpt-5.6-luna\": 231200\n    },\n    \"modelReasoningEfforts\": {\n      \"gpt-5-mini\": \"low\"\n    },\n    \"useMessagesApi\": true,\n    \"useResponsesApiWebSocket\": true,\n    \"useResponsesApiWebSearch\": true,\n    \"messageApiWebSearchModel\": \"gpt-5-mini\"\n  }\n  ```\n- **auth.apiKeys:** API keys used for request authentication on non-admin routes. Supports multiple keys for rotation. Requests can authenticate with either `x-api-key: <key>` or `Authorization: Bearer <key>`. If empty or omitted, authentication for non-admin routes is disabled.\n- **auth.adminApiKey:** Single admin key used only for `/admin/*` routes. If missing, the server generates a random key at startup and writes it back to `config.json`. Requests use the same `x-api-key` or `Authorization: Bearer` headers, but regular `auth.apiKeys` never grant access to `/admin/*`.\n- **modelMappings:** Exact `sourceModel -> targetModel` rewrites shared by top-level `POST /v1/messages`, `POST /v1/messages/count_tokens`, `POST /v1/responses`, and `POST /v1/chat/completions` requests. Omit it or leave it as `{}` to disable rewrites. Both the source and target must be non-empty strings. Targets can be regular model IDs or `provider/model` aliases such as `dashscope/qwen3.6-plus`, and the rewrite happens before provider alias parsing. These mappings are not split per interface. The admin endpoints `GET/POST /admin/config/model-mappings` read and update only this field.\n- **extraPrompts:** Map of `model -> prompt` appended to the first system prompt when translating Anthropic-style requests to Responses API. Use this to inject guardrails or guidance per model. Missing default entries are auto-added without overwriting your custom prompts. For GPT-5.3+ models (e.g. `gpt-5.3-codex`, `gpt-5.4`, `gpt-5.5`), a built-in commentary prompt is used as fallback when not explicitly configured. The built-in prompts enable phase-aware commentary, which lets the model emit a short user-facing progress update before tools or deeper reasoning.\n- **providers:** Global upstream provider map. Each provider key (for example `dashscope`) becomes a route prefix (`/dashscope/v1/messages`). Supports `type: \"anthropic\"`, `type: \"openai-compatible\"`, and `type: \"openai-responses\"`. Top-level clients can also use `model: \"dashscope/model-id\"` with `/v1/messages`, `/v1/messages/count_tokens`, `/v1/responses`, and `/v1/chat/completions`; the gateway strips the `dashscope/` prefix before forwarding upstream. `openai-compatible` providers support both chat and Messages flows: `/v1/chat/completions` is proxied to upstream `/v1/chat/completions`, while `/v1/messages` and `/:provider/v1/messages` are translated to upstream chat completions and translated back to Anthropic Messages responses. `GET /v1/models` aggregates enabled provider models with `provider/model-id` IDs; use `GET /dashscope/v1/models` for a single provider's raw model list.\n  - `enabled` defaults to `true` if omitted.\n  - `baseUrl` should be provider API base URL without the final endpoint. For Anthropic providers, omit `/v1/messages`; for OpenAI-compatible providers, omit `/v1/chat/completions`; for OpenAI Responses providers, omit `/v1/responses`.\n  - `apiKey` is used as the upstream credential value and is required for regular providers.\n  - `authType` (optional): Controls how `apiKey` is sent upstream. Supports `x-api-key` and `authorization` for regular providers. Anthropic providers default to `x-api-key`; OpenAI-compatible and OpenAI Responses providers default to `authorization`. When set to `authorization`, the proxy sends `Authorization: Bearer <apiKey>`. `oauth2` is reserved for the built-in `codex` provider and is written automatically by `auth login --provider codex`.\n  - `pricingCurrency` (optional): Provider-level currency used for token cost calculation, for example `USD` or `CNY`. Quick providers default to `CNY` for DashScope and DeepSeek, and `USD` for Codex/OpenRouter. Costs are grouped by currency and are not exchange-rate converted.\n  - `models` (optional): Per-model configuration map. Each key is a model ID (matching the model name in requests), and the value is:\n    - `temperature` (optional): Default temperature value used when the request does not specify one.\n    - `topP` (optional): Default top_p value used when the request does not specify one.\n    - `topK` (optional): Default top_k value used when the request does not specify one.\n    - `extraBody` (optional): Dynamic fields merged into the upstream request body for that model. Request body fields with the same name take precedence. OpenAI-compatible providers can use this for fields such as `enable_thinking`, `preserve_thinking`, `reasoning_effort`. `thinking_budget` is a special OpenAI-compatible provider override: when configured in `extraBody`, it is forced after Anthropic `thinking.budget_tokens` translation and overrides the request-derived budget. For providers whose name is `dashscope` or whose `baseUrl` contains `aliyuncs.com`, the request-derived `thinking_budget` (from Anthropic `thinking.budget_tokens`) is forwarded upstream; for other OpenAI-compatible providers the request-derived `thinking_budget` is stripped, while an `extraBody` `thinking_budget` is still honored. For DashScope providers, `preserve_thinking` defaults to `true` when not explicitly set in `extraBody` or the request body.\n    - `pricing` (optional): Per-model token prices, in the provider `pricingCurrency`, per 1M tokens. Supported fields are `input`, `output`, `cachedInput` (implicit cache read), `explicitCachedInput` (explicit cache read), and `cacheCreationInput`. Use `tiers` with `maxInputTokens` for input-size tiered pricing.\n    - `contextCache` (optional): Defaults to `true` for providers whose name is `dashscope` or whose `baseUrl` contains `aliyuncs.com`; defaults to `false` for other OpenAI-compatible providers. This enables Alibaba Cloud Model Studio/DashScope explicit context cache by injecting `cache_control: { \"type\": \"ephemeral\" }` on up to 4 content blocks using the Context Cache format. The cache breakpoint strategy matches opencode's main provider flow: the first 2 system messages plus the last 2 non-system messages. Marked string content is converted to text content part arrays for `system` / `user` / `assistant` / `tool` messages; existing array content is marked on the last part. Set this to `false` when the model already supports implicit caching, or when the upstream does not accept this explicit-cache extension field. Set this to `true` for non-DashScope providers that support the same explicit-cache extension. Applied on both `/v1/messages` and `/v1/chat/completions` routes.\n    - `supportPdf` (optional): Controls whether the model supports PDF/document content. Defaults to `false`; unsupported PDFs are converted to a text notice. Set it to `true` to send PDF/document blocks as OpenAI Chat Completions file parts.\n    - `toolContentSupportType` (optional): Tool result content capabilities for that model, as an array of `array`, `image`, and `pdf`. Provider routes default to string-only tool content when omitted. If `supportPdf` is `true` but this list does not include `pdf`, file parts in tool results are moved to user role messages. This provider default does not change the Copilot main flow, which continues to support array + image and not PDF.\n    - `type` (optional): Per-model override of the provider protocol type. Supports `anthropic`, `openai-compatible`, and `openai-responses`. When set, the provider's `/v1/messages` route uses this model's type instead of the provider-level type for request routing, auth header resolution, and upstream endpoint selection. This is useful for providers like OpenCode Go whose upstream supports both OpenAI-compatible and Anthropic Messages APIs for different models. When the type is overridden, the auth header is resolved from the overridden type's default (Anthropic defaults to `x-api-key`; OpenAI-compatible/Responses default to `authorization`).\n\n  Example DashScope model settings:\n  ```json\n  {\n    \"providers\": {\n      \"dashscope\": {\n        \"type\": \"openai-compatible\",\n        \"enabled\": true,\n        \"baseUrl\": \"https://dashscope.aliyuncs.com/compatible-mode\",\n        \"apiKey\": \"sk-your-dashscope-key\",\n        \"pricingCurrency\": \"CNY\",\n        \"models\": {\n          \"qwen3.7-plus\": {\n            \"temperature\": 1,\n            \"topP\": 0.95,\n            \"topK\": 20,\n            \"extraBody\": {\n              \"preserve_thinking\": true\n            }\n          },\n          \"glm-5.1\": {\n            \"temperature\": 0.7,\n            \"topP\": 0.95,\n            \"contextCache\": true,\n            \"pricing\": {\n              \"tiers\": [\n                {\n                  \"maxInputTokens\": 32000,\n                  \"input\": 6,\n                  \"cachedInput\": 1.2,\n                  \"explicitCachedInput\": 0.6,\n                  \"cacheCreationInput\": 7.5,\n                  \"output\": 24\n                },\n                {\n                  \"maxInputTokens\": 200000,\n                  \"input\": 8,\n                  \"cachedInput\": 1.6,\n                  \"explicitCachedInput\": 0.8,\n                  \"cacheCreationInput\": 10,\n                  \"output\": 28\n                }\n              ]\n            },\n            \"extraBody\": {\n              \"preserve_thinking\": true\n            }\n          }\n        }\n      }\n    }\n  }\n  ```\n  Built-in token prices cover Codex GPT models in USD, DashScope `qwen3.7-max`, `qwen3.7-plus`, `glm-5.1`, `glm-5.2` in CNY, DeepSeek `deepseek-v4-flash`, `deepseek-v4-pro`, `deepseek-chat`, `deepseek-reasoner` in CNY, and OpenCode Go models (`glm-5.2`, `deepseek-v4-flash`, `deepseek-v4-pro`, `kimi-k2.7-code`, `mimo-v2.5`, `mimo-v2.5-pro`, `qwen3.7-plus`, `qwen3.7-max`, `minimax-m2.5`, `minimax-m3`) in USD. User `pricing` entries override built-ins. For DashScope, cached tokens are charged as explicit cache reads when the upstream usage includes `cache_creation_input_tokens`; otherwise `cachedInput` is used as the implicit cache read price. For DeepSeek, `prompt_cache_hit_tokens` map to cached input and `prompt_cache_miss_tokens` map to regular input.\n- **smallModel:** Fallback model used for tool-less warmup messages (e.g., Claude Code probe requests); defaults to gpt-5-mini.\n- **contextManagement:** Controls whether the proxy adds Responses API `context_management` compaction instructions. `messages` applies when Anthropic-style `/v1/messages` requests are translated to Responses API, including `openai-responses` provider message routes, and defaults to `true`. `responses` applies to native `/v1/responses` traffic, including `provider/model` aliases and the built-in `codex` provider, and defaults to `false`. Enable `responses` only after checking that your client supports context management compaction. When enabled, the request includes `context_management` in the body and keeps only the latest compaction carrier on follow-up turns. **Note:** Context management is forcibly disabled for GPT-5.6 and above models (e.g. `gpt-5.6-sol`, `gpt-5.6-terra`, `gpt-5.6-luna`) because enabling it breaks prompt cache hits on those models. This override takes precedence over the `contextManagement` and `modelResponsesApiCompactThresholds` settings.\n- **modelResponsesApiCompactThresholds:** Per-model Responses API `compact_threshold` overrides used when the proxy adds `context_management`. These values take precedence over the fallback threshold from `resolveResponsesCompactThreshold` (`max_prompt_tokens * ratio`, or the default fallback). Defaults set `gpt-5.4` and `gpt-5.5` to `217600` (`272000 * 0.8`), and `gpt-5.6-sol`, `gpt-5.6-terra`, `gpt-5.6-luna` to `231200` (`272000 * 0.85`). Models not listed continue to use the normal fallback logic.\n- **modelReasoningEfforts:** Per-model fallback reasoning effort for `/v1/messages` requests. It is used only when the request does not provide `output_config.effort`.\n  - **Priority:** request `output_config.effort` > `modelReasoningEfforts[model]` > built-in default (`xhigh` for GPT-5.3+ models, otherwise `high`).\n  - **Forwarding:** the resolved value remains `output_config.effort` for the Copilot native Messages API and becomes `reasoning.effort` when translated to the Responses API.\n  - **Configuration values:** `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`.\n- **useMessagesApi:** When `true`, Claude-family models that support Copilot's native `/v1/messages` endpoint will use the Messages API; otherwise they fall back to `/chat/completions`. Set to `false` to disable Messages API routing and always use `/chat/completions`. Defaults to `true`.\n- **useResponsesApiWebSocket:** When `true`, Responses API requests use Copilot's websocket transport for models that advertise `ws:/responses`; models that only advertise `/responses` continue to use HTTP. Set to `false` to disable websocket routing and use HTTP `/responses` whenever the selected model supports it. Defaults to `true`. If the Responses API WebSocket gets closed, it is usually caused by your own network. If you are using a VPN, try switching to a different node.\n- **useResponsesApiWebSearch:** When `true`, the server keeps Responses API tools with `type: \"web_search\"` and forwards them upstream. Set to `false` to strip those tools from `/responses` payloads. Defaults to `true`.\n- **messageApiWebSearchModel:** Global fallback model used when a top-level Copilot `/v1/messages` request contains only the server-side `web_search` tool. Defaults to `gpt-5-mini`. If the value is a `provider/model` alias, the request is routed into that provider's Messages API path with the provider prefix stripped. For Copilot GPT models, web search runs through `/responses`. Mixed `web_search` plus custom tools are not supported and the server-side `web_search` tool is stripped.\n- **claudeTokenMultiplier:** Multiplier applied to the fallback GPT-tokenizer estimate for Claude `/v1/messages/count_tokens` requests. Defaults to `1.15`. Increase it if your client is still compacting too late. This setting is only used when the proxy is estimating Claude tokens locally; if `anthropicApiKey` is configured and Anthropic token counting succeeds, the exact Anthropic count is returned instead.\n- **anthropicApiKey:** Anthropic API key used to forward Claude `/v1/messages/count_tokens` requests to Anthropic's real token counting endpoint, which returns exact counts instead of GPT tokenizer estimates. Can also be set via the `ANTHROPIC_API_KEY` environment variable. If not set, or if the upstream call fails, token counting falls back to local GPT tokenizer estimation controlled by `claudeTokenMultiplier`.\n\nEdit this file to customize prompts or swap in your own fast model. Restart the server (or rerun the command) after changes so the cached config is refreshed.\n\n## API Authentication\n\n- **Protected non-admin routes:** All routes except `/`, `/usage-viewer`, and `/usage-viewer/` require authentication when `auth.apiKeys` is configured and non-empty.\n- **Admin routes:** All `/admin/*` routes require `auth.adminApiKey`. If it is missing, the server generates one at startup and persists it to `config.json` before serving requests.\n- **Allowed auth headers:**\n  - `x-api-key: <your_key>`\n  - `Authorization: Bearer <your_key>`\n- **CORS preflight:** `OPTIONS` requests are always allowed.\n- **When no regular keys are configured:** Non-admin routes continue to allow requests. This does not apply to `/admin/*`, which only accepts `auth.adminApiKey`.\n\nExample request for a regular protected route:\n\n```sh\ncurl http://localhost:4141/v1/models \\\n  -H \"x-api-key: your_api_key\"\n```\n\nExample request for an admin route:\n\n```sh\ncurl http://localhost:4141/admin/config/model-mappings \\\n  -H \"x-api-key: your_admin_api_key\"\n```\n\n## API Endpoints\n\nThe server exposes several OpenAI- and Anthropic-compatible endpoints. Requests can target GitHub Copilot, the built-in `codex` provider, or configured providers depending on the selected model and `provider/model` alias.\n\n### OpenAI Compatible Endpoints\n\nThese endpoints mimic the OpenAI API structure.\n\n| Endpoint                    | Method | Description                                                      |\n| --------------------------- | ------ | ---------------------------------------------------------------- |\n| `POST /v1/responses`        | `POST` | OpenAI Most advanced interface for generating model responses. Supports `provider/model` aliases for `openai-responses` providers. |\n| `POST /v1/chat/completions` | `POST` | Creates a model response for the given chat conversation. Supports `provider/model` aliases for `openai-compatible` providers and can be used without Copilot when the target provider is configured. |\n| `GET /v1/models`            | `GET`  | Lists Copilot models plus enabled provider models using `provider/model-id` IDs. Requests from Codex clients (`User-Agent` beginning with `codex`) are forwarded to the Codex Models upstream. |\n| `POST /v1/embeddings`       | `POST` | Creates an embedding vector representing the input text.         |\n\n### Codex Backend Proxy Endpoints\n\nThese endpoints require an active Codex login. Each endpoint is available both without a version prefix and under `/v1`.\n\n| Endpoint | Method | Description |\n| --- | --- | --- |\n| `POST /alpha/search`<br>`POST /v1/alpha/search` | `POST` | Transparently forwards the JSON body and query parameters to the Codex Alpha Search upstream. |\n| `POST /images/generations`<br>`POST /v1/images/generations` | `POST` | Forwards a JSON image generation request to the Codex Images upstream. When the request omits `Content-Type`, the gateway defaults it to `application/json`. |\n| `POST /images/edits`<br>`POST /v1/images/edits` | `POST` | Forwards an image edit request to the Codex Images upstream. Send this request as `multipart/form-data` and let the HTTP client generate the `boundary`; the gateway preserves the incoming content type and streams the upload body. |\n\nFor every endpoint above, the gateway replaces client authorization and account headers with the active Codex login, preserves query parameters and compatible request headers, and returns the upstream status, headers, and body.\n\n### Anthropic Compatible Endpoints\n\nThese endpoints are designed to be compatible with the Anthropic Messages API. Provider-scoped models, Responses, alpha-search, and images routes accept both unversioned and `/v1` paths; Messages routes remain under `/v1`.\n\n| Endpoint                         | Method | Description                                                  |\n| -------------------------------- | ------ | ------------------------------------------------------------ |\n| `POST /v1/messages`              | `POST` | Creates a model response for a given conversation. Supports `provider/model` aliases for configured providers, including translation through `openai-compatible` providers. |\n| `POST /v1/messages/count_tokens` | `POST` | Calculates the number of tokens for a given set of messages. Supports `provider/model` aliases for configured providers. |\n| `POST /:provider/v1/messages`       | `POST` | Proxies Anthropic Messages requests to the configured Anthropic provider, translates them through an OpenAI-compatible provider, or translates them through an OpenAI Responses provider. |\n| `GET /:provider/models`<br>`GET /:provider/v1/models` | `GET` | Proxies model listing requests to the configured provider. For `codex`, returns the built-in catalog by default; Codex clients (`User-Agent` starting with `codex`) are forwarded to the Codex Models upstream. |\n| `POST /:provider/v1/messages/count_tokens` | `POST` | Calculates tokens locally for provider route requests. |\n| `POST /:provider/responses`<br>`POST /:provider/v1/responses` | `POST` | Proxies OpenAI Responses requests to a configured `openai-responses` provider (including `codex`). |\n| `POST /:provider/alpha/search`<br>`POST /:provider/v1/alpha/search` | `POST` | Proxies alpha-search requests. For `codex`, forwards to the Codex Alpha Search upstream; for other providers, forwards to `{baseUrl}/v1/alpha/search`. |\n| `POST /:provider/images/generations`<br>`POST /:provider/v1/images/generations` | `POST` | Proxies image generation. For `codex`, uses the Codex Images upstream; for other providers, forwards to `{baseUrl}/v1/images/generations` (15-minute timeout). |\n| `POST /:provider/images/edits`<br>`POST /:provider/v1/images/edits` | `POST` | Proxies image edits. For `codex`, uses the Codex Images upstream; for other providers, forwards multipart/streamed bodies to `{baseUrl}/v1/images/edits` (15-minute timeout). |\n\n### Usage Monitoring Endpoints\n\nNew endpoints for monitoring your Copilot usage and quotas.\n\n| Endpoint     | Method | Description                                                  |\n| ------------ | ------ | ------------------------------------------------------------ |\n| `GET /usage` | `GET`  | Get detailed Copilot usage statistics and quota information. |\n| `GET /token` | `GET`  | Get the current Copilot token being used by the API.         |\n\n### Admin / Configuration Endpoints\n\nThese endpoints are reserved for local administrative actions and only accept `auth.adminApiKey`.\n\n| Endpoint                              | Method | Description                                                                 |\n| ------------------------------------- | ------ | --------------------------------------------------------------------------- |\n| `GET /admin/config/model-mappings`    | `GET`  | Returns the current `config.json` path and the active `modelMappings` map.  |\n| `POST /admin/config/model-mappings`   | `POST` | Updates only the `modelMappings` field in `config.json` and returns it back. |\n\n## Example Usage\n\nCommon `npx` commands:\n\n```sh\n# Start the gateway\nnpx @jeffreycao/copilot-api@latest start\n\n# Start on a custom port with verbose logging\nnpx @jeffreycao/copilot-api@latest start --port 8080 --verbose\n\n# Run the auth flow\nnpx @jeffreycao/copilot-api@latest auth login\n\n# Configure a third-party provider, then run without GitHub Copilot\nnpx @jeffreycao/copilot-api@latest auth login --provider dashscope\nnpx @jeffreycao/copilot-api@latest start\n\n# Print debug information as JSON\nnpx @jeffreycao/copilot-api@latest debug --json\n\n# Run the published CLI with Bun instead of Node.js\nbunx --bun @jeffreycao/copilot-api@latest start\n```\n\nOpenAI-compatible provider examples after configuring `dashscope`:\n\n```sh\ncurl http://localhost:4141/v1/chat/completions \\\n  -H \"content-type: application/json\" \\\n  -d '{\"model\":\"dashscope/qwen3.6-plus\",\"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]}'\n\ncurl http://localhost:4141/dashscope/v1/messages \\\n  -H \"content-type: application/json\" \\\n  -d '{\"model\":\"qwen3.6-plus\",\"max_tokens\":1024,\"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]}'\n```\n\n## Usage Tips\n\n### CLAUDE.md or AGENTS.md Recommended Content\n\nTo add these reminders manually, include the following in `CLAUDE.md` for Claude Code, or `AGENTS.md` for opencode/codex:\n\n```\n- Prohibited from directly asking questions to users, MUST use question tool.\n- Once you can confirm that the task is complete, MUST use question tool to make user confirm. The user may respond with feedback if they are not satisfied with the result, which you can use to make improvements and try again, after try again, MUST use question tool to make user confirm again.\n```\n"}, "9d7b1f8aea1fb41ea13222b47689fd2acf5b0c60": {"t": 1785765547.0485718, "n": 49832, "h": "e195c40d98175bec", "c": "# Copilot API Proxy\n\nEnglish | [简体中文](./README.zh-CN.md)\n\n## Important Notes\n\n> [!IMPORTANT]\n> **Before using, please be aware of the following:**\n>\n> 1. **Claude Code configuration:** When using with Claude Code, please configure the model ID as `claude-opus-4-8`. Example claude `settings.json` see [Manual Configuration with `settings.json`](#manual-configuration-with-settingsjson). \n>\n> 2. **Built-in `copilot`, `codex` and third-party providers:** Run `npx @jeffreycao/copilot-api@latest auth` and choose `copilot`, `codex`, `deepseek`, `custom`, or other providers.\n>\n> 3. **Note:** See [GitHub Copilot Security Notice](./NOTICE.md#github-copilot-security-notice) for the warning removed from the README header.\n\n---\n\n## Project Overview\n\nA small AI gateway that can use GitHub Copilot, the built-in `codex` provider, or configured third-party providers such as DashScope. GitHub Copilot is optional: if no GitHub token is available, the server can still start in provider-only mode as long as at least one enabled provider is configured.\n\nThe gateway exposes OpenAI- and Anthropic-compatible APIs from one local endpoint, so tools like [Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview), OpenCode, Codex, and OpenAI-compatible clients can share the same local server.\n\nOn the GitHub Copilot path, the gateway prefers Copilot's native Anthropic-style Messages API when available, preserving more Claude-native behavior for tool-heavy workflows.\n\n## Features\n\n- **OpenAI and Anthropic compatibility**: Serve `/v1/responses`, `/v1/chat/completions`, `/v1/models`, `/v1/embeddings`, and `/v1/messages` from one local gateway.\n- **Copilot is optional**: Use GitHub Copilot when credentials are present, or run the server with only configured providers.\n- **One gateway for Copilot, `codex`, and external providers**: Route GitHub Copilot, the built-in `codex` provider, and configured third-party providers behind the same endpoint.\n- **Standalone third-party providers**: Configure providers such as DashScope, DeepSeek, OpenRouter, or a custom provider and start the gateway without a GitHub Copilot login.\n- **OpenAI-compatible providers on chat and Messages APIs**: `openai-compatible` providers can serve top-level `/v1/chat/completions` through `model: \"provider/model\"` and Anthropic-style `/v1/messages` through request/response translation.\n- **Agent-friendly Claude handling on Copilot**: Prefer native `/v1/messages` when available, preserve Claude-style tool flows, support Anthropic beta features, Claude WebSearch through Responses-capable models, and keep subagent/session markers intact.\n- **Claude Code and OpenCode integration**: Works with Claude Code and OpenCode, including direct Anthropic-compatible usage through `@ai-sdk/anthropic`.\n- **Flexible auth and deployment options**: Supports interactive login or direct tokens, individual/business/enterprise plans, GitHub Enterprise, opencode OAuth, and custom data directories.\n- **Multi-provider routing**: Expose provider-specific `/:provider/...` routes or use `model: \"provider/model\"` on the top-level API.\n\n## Prerequisites\n\n- Bun (>= 1.2.x)\n- Node.js if you plan to run the published CLI with `npx`\n- GitHub account with Copilot subscription only if you want to use the GitHub Copilot provider\n- An API key or OAuth login for at least one configured provider if you want to run without GitHub Copilot\n\n## Installation\n\nTo install dependencies, run:\n\n```sh\nbun install\n```\n\nTo start the server directly from source:\n\n```sh\nbun run start start\n```\n\n## Running from Source\n\nThe project can be run from source in several ways:\n\n### Development Mode\n\n```sh\nbun run dev start\n```\n\n### Production Mode\n\n```sh\nbun run start start\n```\n\n## Using with npx\n\nYou can run the project directly using npx:\n\n> [!IMPORTANT]\n> Token usage storage uses Node's built-in `node:sqlite` module when running with `npx`. It is enabled on Node.js >= 22.13.0. On Node.js < 22.13.0, the CLI still starts, but token usage storage is disabled.\n>\n> If you want token usage storage without upgrading Node.js, run the published CLI with Bun instead: `bunx --bun @jeffreycao/copilot-api@latest start`.\n\n```sh\nnpx @jeffreycao/copilot-api@latest start\n```\n\nWith options:\n\n```sh\nnpx @jeffreycao/copilot-api@latest start --port 8080\n```\n\nFor authentication or provider configuration only:\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth\n```\n\nTo run without GitHub Copilot, configure at least one provider first, then start the server normally:\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth login --provider dashscope\nnpx @jeffreycao/copilot-api@latest start\n```\n\n## Using with Docker\n\nBuild the image:\n\n```sh\ndocker build -t copilot-api .\n```\n\nRun the container with a bind mount so auth data survives restarts:\n\n```sh\nmkdir -p ./copilot-data\ndocker run -p 4141:4141 -v $(pwd)/copilot-data:/root/.local/share/copilot-api copilot-api\n```\n\nThis stores GitHub auth data, provider config, and other gateway state in `./copilot-data` on the host, mapped to `/root/.local/share/copilot-api` in the container.\n\nOr pass a GitHub token directly:\n\n```sh\ndocker run -p 4141:4141 -e GH_TOKEN=your_github_token_here copilot-api\n```\n\n## Electron Desktop App\n\nIf you prefer a GUI, this repository also includes an Electron desktop app in `desktop/`. It supports GitHub Copilot sign-in, OpenAI Codex OAuth, and API-key configuration for DeepSeek, DashScope, OpenRouter, or a custom provider. After authorization or provider configuration, it can start and stop the local proxy with one click and shows the local endpoint, auth header, available models, usage, and logs in the app.\n\nThe settings screen also exposes `OAuth App`, `API Home`, `Enterprise URL`, verbose logging, and minimize-to-tray. Desktop packages are published in GitHub Releases:\n\nhttps://github.com/caozhiyuan/copilot-api/releases\n\nDownload the installer for your platform, authorize or configure a provider inside the app, choose a port, start the server, then point your client at the local endpoint shown in the app. Packaged desktop builds use the bundled Electron runtime, so normal desktop usage does not require installing Node.js separately. Token usage history is enabled when that bundled runtime supports SQLite.\n\nThe desktop app's Advanced Config page reads and writes the shared model mappings through `GET/POST /admin/config/model-mappings`. The same mappings apply across `POST /v1/messages`, `POST /v1/messages/count_tokens`, `POST /v1/responses`, and `POST /v1/chat/completions` instead of being split per interface. It uses `auth.adminApiKey` instead of the regular `auth.apiKeys`, and the app reads that key directly from `config.json` after the server has generated it on startup.\n\n### Desktop App Screenshots\n\nMain dashboard, token usage breakdown in the bundled Electron app:\n\n<p align=\"center\">\n  <img src=\"./docs/screenshots/desktop-dashboard.png\" alt=\"Copilot API desktop app dashboard\" width=\"49%\" />\n  <img src=\"./docs/screenshots/desktop-token-usage.png\" alt=\"Copilot API desktop app token usage view\" width=\"49%\" />\n</p>\n\n## Using with Claude Code\n\nThis AI gateway can be used to power [Claude Code](https://docs.anthropic.com/en/claude-code), an experimental conversational AI assistant for developers from Anthropic.\n\nThere are two ways to configure Claude Code to use this AI gateway:\n\n### Interactive Setup with `--claude-code` flag\n\nTo get started, run the `start` command with the `--claude-code` flag:\n\n```sh\nnpx @jeffreycao/copilot-api@latest start --claude-code\n```\n\nYou will be prompted to select a primary model and a \"small, fast\" model for background tasks. After selecting the models, a command will be copied to your clipboard. This command sets the necessary environment variables for Claude Code to use the gateway.\n\nPaste and run this command in a new terminal to launch Claude Code.\n\n### Manual Configuration with `settings.json`\n\nAlternatively, you can configure Claude Code by creating a `.claude/settings.json` file in your project's root directory. This file should contain the environment variables needed by Claude Code. This way you don't need to run the interactive setup every time.\n\nHere is an example `.claude/settings.json` file:\n\n```json\n{\n  \"env\": {\n    \"ANTHROPIC_BASE_URL\": \"http://localhost:4141\",\n    \"ANTHROPIC_AUTH_TOKEN\": \"dummy\",\n    \"ANTHROPIC_MODEL\": \"deepseek/deepseek-v4-pro\",\n    \"ANTHROPIC_DEFAULT_SONNET_MODEL\": \"deepseek/deepseek-v4-pro\",\n    \"ANTHROPIC_DEFAULT_HAIKU_MODEL\": \"deepseek/deepseek-v4-flash\",\n    \"CLAUDE_CODE_USE_VERTEX\": \"0\",\n    \"CLAUDE_CODE_USE_BEDROCK\": \"0\",\n    \"DISABLE_NON_ESSENTIAL_MODEL_CALLS\": \"1\",\n    \"CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC\": \"1\",\n    \"CLAUDE_CODE_ATTRIBUTION_HEADER\": \"0\",\n    \"CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION\": \"false\",\n    \"CLAUDE_CODE_DISABLE_TERMINAL_TITLE\": \"true\",\n    \"CLAUDE_CODE_ENABLE_AWAY_SUMMARY\": \"0\"\n  },\n  \"permissions\": {\n    \"deny\": [\n      \"mcp__ide__executeCode\"\n    ]\n  }\n}\n```\n\n- Replace `ANTHROPIC_MODEL`, `ANTHROPIC_DEFAULT_OPUS_MODEL`, `ANTHROPIC_DEFAULT_SONNET_MODEL`, and `ANTHROPIC_DEFAULT_HAIKU_MODEL` according to your needs. After configuration, please install the claude code plugin [Plugin Integrations](#plugin-integrations).  \n- Setting CLAUDE_CODE_ATTRIBUTION_HEADER to 0 can prevent Claude code from adding billing and version information in system prompts, thereby avoiding prompt cache invalidation.\n- Turning off CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION and CLAUDE_CODE_ENABLE_AWAY_SUMMARY can prevent quota from being consumed unnecessarily.\n- Claude Code WebSearch is supported for pure search requests. For Copilot, keep the global `messageApiWebSearchModel` set to a Responses-capable GPT model or a `provider/model` alias. For provider routes, use a native Anthropic provider or an `openai-responses` provider. Add `WebSearch` to `permissions.deny` only if you want to forbid this traffic.\n- If using a non-Claude model, do not enable ENABLE_TOOL_SEARCH. If using the Claude model, can enable ENABLE_TOOL_SEARCH. The current Claude Code uses the client tool search mode. In this mode, loading defer tools requires an additional request each time.\n- `CLAUDE_CODE_AUTO_COMPACT_WINDOW`: Set the context capacity in tokens used for auto-compaction calculations. Defaults to the model's context window: 200K for standard models or 1M for extended context models. Use a lower value like `500000` on a 1M model (e.g., `claude-opus-4-6[1m]`) to treat the window as 500K for compaction purposes. The value is capped at the model's actual context window. `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` is applied as a percentage of this value. Setting this variable decouples the compaction threshold from the status line's `used_percentage`, which always uses the model's full context window.\n\nYou can find more options here: [Claude Code settings](https://docs.anthropic.com/en/docs/claude-code/settings#environment-variables)\n\nYou can also read more about IDE integration here: [Add Claude Code to your IDE](https://docs.anthropic.com/en/docs/claude-code/ide-integrations)\n\n## Using with OpenCode\n\nOpenCode already has a direct GitHub Copilot provider. Use this section when you want OpenCode to point at this AI gateway through `@ai-sdk/anthropic` and reuse the agent behaviors described earlier in this README.\n\n### Minimal setup\n\nStart the AI gateway with the OpenCode OAuth app:\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth --oauth-app=opencode\nnpx @jeffreycao/copilot-api@latest start\n```\n\nThen point OpenCode at the gateway with `@ai-sdk/anthropic`.\n\nExample `~/.config/opencode/opencode.json`:\n\n```json\n{\n  \"$schema\": \"https://opencode.ai/config.json\",\n  \"provider\": {\n    \"local\": {\n      \"npm\": \"@ai-sdk/anthropic\",\n      \"name\": \"My Local\",\n      \"options\": {\n        \"baseURL\": \"http://localhost:4141/v1\",\n        \"apiKey\": \"dummy\"\n      },\n      \"models\": {\n        \"gpt-5.4\": {\n          \"name\": \"gpt-5.4\",\n          \"modalities\": {\n            \"input\": [\"text\", \"image\"],\n            \"output\": [\"text\"]\n          },\n          \"limit\": {\n            \"context\": 400000,\n            \"input\": 272000,\n            \"output\": 128000\n          }\n        },\n        \"claude-sonnet-4.6\": {\n          \"id\": \"claude-sonnet-4.6\",\n          \"name\": \"claude-sonnet-4.6\",\n          \"modalities\": {\n            \"input\": [\"text\", \"image\"],\n            \"output\": [\"text\"]\n          },          \n          \"limit\": {\n            \"context\": 200000,\n            \"output\": 32000\n          },\n          \"options\": {\n            \"thinking\": {\n              \"type\": \"adaptive\"\n            },\n            \"effort\": \"max\"\n          }\n        }\n      }\n    }\n  }\n}\n```\n\nWhy these fields matter:\n\n- `npm: \"@ai-sdk/anthropic\"` is the important part. OpenCode will speak Anthropic Messages semantics to this AI gateway instead of flattening everything into OpenAI Chat Completions.\n- `options.baseURL` should be `http://localhost:4141/v1`; the Anthropic SDK will append `/messages`, `/models`, and `/messages/count_tokens` automatically.\n- If you enable `auth.apiKeys` in this AI gateway, replace `dummy` with a real key. Otherwise any placeholder value is fine.\n\n## Using with Codex\n\nThis AI gateway can also power Codex.\n\n### Codex `config.toml` Reference\n\nAdd the following `[model_providers.copilot_api]` section to your Codex `~/.codex/config.toml`:\n\n```toml\nmodel_provider = \"copilot_api\"\nmodel_reasoning_summary = \"auto\"\nmodel_context_window = 272000\nmodel_auto_compact_token_limit = 244800\n\n[model_providers.copilot_api]\nname = \"OpenAI\"\nbase_url = \"http://localhost:4141\"\nenv_key = \"GITHUB_COPILOT_API_KEY\"\nrequires_openai_auth = true\nsupports_websockets = false\nwire_api = \"responses\"\nrequest_max_retries = 3\nstream_max_retries = 1\nstream_idle_timeout_ms = 300000\n\n[features]\nremote_compaction_v2 = true\n\n[analytics]\nenabled = false\n```\n\n> [!NOTE]\n> This configuration is specific to Codex and the GitHub Copilot provider. `name` must be set to `\"OpenAI\"`. It can help mitigate Codex local compact cache miss issues.\n> If you are using the codex provider, it is recommended to set `base_url` to `\"http://localhost:4141/codex\"`.\n\n## GPT Tool Search\n\nFor GPT Responses models such as `gpt-5.4+`, this AI gateway can expose Responses `tool_search` through a small MCP bridge. The same bridge can be used by Claude Code and opencode, as long as the client loads MCP servers and sends Anthropic Messages traffic through this gateway.\n\nDo not set Claude Code's native `ENABLE_TOOL_SEARCH` for GPT models. That flag enables Claude Code's own client-side tool search mode, and it may stop forwarding deferred tool definitions. This gateway needs the full tool definitions so it can keep the small always-loaded tool set eager and translate every other tool into Responses deferred namespaces.\n\nIf you install `tool-search@copilot-api-marketplace`, Claude Code receives this MCP bridge automatically and you can skip the manual Claude Code MCP setup below.\n\nAdd the tool search bridge to the MCP config used by Claude Code:\n\n```json\n{\n  \"mcpServers\": {\n    \"tool_search\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@jeffreycao/copilot-api@latest\", \"mcp\"]\n    }\n  }\n}\n```\n\nAdd the tool search bridge to the MCP config used by opencode:\n\n```json\n{\n  \"mcp\": {\n    \"tool_search\": {\n      \"type\": \"local\",\n      \"command\": [\"npx\", \"-y\", \"@jeffreycao/copilot-api@latest\", \"mcp\"]\n    }\n  }\n}\n```\n\nFor local development, use `bun` as the command and `[\"run\", \"./src/main.ts\", \"mcp\"]` as the args.\n\nInternally, the gateway now configures OpenAI Responses `tool_search` in client-executed mode. Deferred tools are still exposed as searchable namespaces, but the model is explicitly asked to return the exact deferred tool names it wants to load next.\n\nThe bridge uses direct tool selection, not query search. Its tool input is `names`, a comma-separated list of exact deferred tool names, for example `TaskList,TaskGet,mcp__fetch__fetch`.\n\n## Plugin Integrations\n\nPlugin integrations are available for Claude Code and opencode.\n\n#### Claude Code plugin integration (marketplace-based)\n\nThe Claude Code integration is packaged as two plugins:\n\n- `agent-inject` injects `__SUBAGENT_MARKER__...` on `SubagentStart`, so the gateway can infer `x-initiator: agent`.\n- `tool-search` registers the `tool_search` MCP bridge used for GPT Responses deferred tool loading.\n\n- Marketplace catalog in this repository: `.claude-plugin/marketplace.json`\n- Plugin sources in this repository: `plugin/claude/agent-inject`, `plugin/claude/tool-search`\n\nAdd the marketplace remotely:\n\n```sh\n/plugin marketplace add https://github.com/caozhiyuan/copilot-api.git\n```\n\nInstall the plugins from the marketplace:\n\n```sh\n/plugin install agent-inject@copilot-api-marketplace\n/plugin install tool-search@copilot-api-marketplace\n```\n\nAfter installation, `agent-inject` injects `__SUBAGENT_MARKER__...` on `SubagentStart`, and the gateway uses it to infer `x-initiator: agent`.\n\nThe `agent-inject` plugin also registers a `UserPromptSubmit` hook that returns `{\"continue\": true}`, and it can inject `SessionStart` reminder rules through environment variables:\n\n- `CLAUDE_PLUGIN_ENABLE_QUESTION_RULES=1` enables the two reminders about using the `question` tool automatically for Claude Code. Alternatively, you can add the same reminders manually in `CLAUDE.md`; see [CLAUDE.md or AGENTS.md Recommended Content](#claudemd-or-agentsmd-recommended-content).\n- `CLAUDE_PLUGIN_ENABLE_NO_BACKGROUND_AGENTS_RULE=1` enables the `run_in_background: true` avoidance reminder for agent hooks.\n\nThe `tool-search` plugin bundles the same MCP bridge described in [GPT Tool Search](#gpt-tool-search), so Claude Code users do not need to add the `tool_search` server manually when they install that plugin.\n\n#### Opencode plugin\n\nThe subagent marker producer is packaged as an opencode plugin located at `plugin/opencode/subagent-marker.js`.\n\n**Installation:**\n\nCopy the plugin file to your opencode plugins directory:\n\n```sh\n# Clone or download this repository, then copy the plugin\ncp plugin/opencode/subagent-marker.js ~/.config/opencode/plugins/\n```\n\nOr manually create the file at `~/.config/opencode/plugins/subagent-marker.js` with the plugin content.\n\n**Features:**\n\n- Tracks sub-sessions created by subagents\n- Automatically prepends a marker system reminder (`__SUBAGENT_MARKER__...`) to subagent chat messages\n- Sets `x-session-id` header for session tracking\n- Enables the gateway to infer `x-initiator: agent` for subagent-originated requests\n\nThe plugin hooks into `session.created`, `session.deleted`, `chat.message`, and `chat.headers` events to provide seamless subagent marker functionality.\n\n## Using the Usage Viewer\n\nAfter starting the server, a URL to the Copilot Usage Dashboard will be displayed in your console. This dashboard is a web interface for monitoring your API usage.\n\n1.  Start the server. For example, using npx:\n    ```sh\n    npx @jeffreycao/copilot-api@latest start\n    ```\n2.  The server will output a URL to the usage viewer. Copy and paste this URL into your browser. It will look something like this:\n    `http://localhost:4141/usage-viewer?endpoint=http://localhost:4141/usage`\n    - If you use the `start.bat` script on Windows, this page will open automatically.\n\nThe dashboard provides a user-friendly interface to view your Copilot usage data:\n\n> Token usage history requires Bun or Node.js >= 22.13.0. On Node.js < 22.13.0, the server runs normally but token usage storage is disabled.\n\n- **API Endpoint URL**: The dashboard is pre-configured to fetch data from your local server endpoint via a URL query parameter. You can manually switch this to any other compatible API endpoint.\n- **x-api-key Authentication**: If API Key authentication is enabled, you can provide the `x-api-key` request header. The key is persisted in the browser's local storage.\n- **Period Selector**: Choose from Day, Week, or Month time ranges. The URL query parameter updates automatically when you switch, making it easy to bookmark and share.\n- **Fetch Data**: Click the \"Refresh\" button to load or refresh the usage data. The dashboard also fetches data automatically on page load.\n- **Copilot Quotas**: View quota usage for services such as Chat and Completions via progress bars. Hover over a card to see used/remaining details.\n- **Token Usage Metric Cards**: See a summary of Total, Input, Output, Cache Read, Cache Write, Requests, and estimated cost for the current period.\n- **Trend Chart (Week / Month)**: An interactive line chart with model and metric filters. Click a data point to inspect the usage breakdown for a specific day.\n- **Model Breakdown Table**: A per-model summary of requests, input/output/cache tokens, and estimated cost for the selected period.\n- **Request Events (Paginated)**: A time-sorted list of request event records with pagination support, showing timestamps, models, request IDs, and token counts.\n- **Detailed Information**: See the full JSON response from the API for a detailed breakdown of all available usage statistics.\n- **URL-based Configuration**: You can also specify the API endpoint and period directly via `endpoint` and `period` query parameters. For example:\n  `http://localhost:4141/usage-viewer?endpoint=http://your-api-server/usage&period=week`\n\n### Usage Viewer Screenshot\n\n<p align=\"center\">\n  <img src=\"./docs/screenshots/usage-viewer.png\" alt=\"Copilot API usage viewer\" width=\"900\" />\n</p>\n\n## Command Structure\n\nCopilot API now uses a subcommand structure with these main commands:\n\n- `start`: Start the gateway server. If a GitHub token is available, the server starts with Copilot enabled. If no GitHub token is available, it starts in provider-only mode when at least one enabled provider exists; otherwise it guides you through provider setup.\n- `auth`: Run provider login or configuration without starting the server. Use it for GitHub Copilot login, Codex OAuth, or third-party provider API key setup.\n- `debug`: Display diagnostic information including version, runtime details, file paths, and authentication status. Useful for troubleshooting and support.\n\n## Command Line Options\n\n### Global Options\n\nThe following options can be used with any subcommand. When passing them before the subcommand, use the `--key=value` form:\n\n| Option            | Description                                            | Default | Alias |\n| ----------------- | ------------------------------------------------------ | ------- | ----- |\n| --api-home        | Path to the API home directory (sets COPILOT_API_HOME) | none    | none  |\n| --oauth-app       | OAuth app identifier (sets COPILOT_API_OAUTH_APP)      | none    | none  |\n| --enterprise-url  | Enterprise URL for GitHub (sets COPILOT_API_ENTERPRISE_URL) | none | none |\n\n### Start Command Options\n\nThe following command line options are available for the `start` command:\n\n| Option         | Description                                                                   | Default    | Alias |\n| -------------- | ----------------------------------------------------------------------------- | ---------- | ----- |\n| --port         | Port to listen on                                                             | 4141       | -p    |\n| --verbose      | Enable verbose logging                                                        | false      | -v    |\n| --github-token | Provide GitHub token directly (must be generated using the `auth` subcommand) | none       | -g    |\n| --claude-code  | Generate a command to launch Claude Code with Copilot API config              | false      | -c    |\n| --show-token   | Show GitHub and Copilot tokens on fetch and refresh                           | false      | none  |\n| --proxy-env    | Initialize proxy from environment variables                                   | false      | none  |\n\n### Auth Command Options\n\n| Option       | Description               | Default | Alias |\n| ------------ | ------------------------- | ------- | ----- |\n| --provider   | Provider to log in with or configure (`copilot`, `codex`, `opencode-go`, `deepseek`, `dashscope`, `openrouter`, or `custom`) | prompt | none |\n| --verbose    | Enable verbose logging    | false   | -v    |\n| --show-token | Show GitHub token on auth | false   | none  |\n\nUse `copilot-api auth login --provider copilot` only when you want to enable the GitHub Copilot provider. Copilot is not required for `codex` or third-party provider-only usage.\n\nUse `copilot-api auth login --provider deepseek`, `--provider dashscope`, `--provider openrouter`, or `--provider opencode-go` to add or update those common third-party providers from the CLI. DeepSeek prompts for masked `apiKey`, provider `type` (default `anthropic`), and `baseUrl` defaulting to `https://api.deepseek.com/anthropic`. DashScope prompts for masked `apiKey`, provider `type` (default `openai-compatible`), and prefilled `baseUrl`. OpenRouter prompts for masked `apiKey` and prefilled `baseUrl` only, and writes `type: \"anthropic\"`. OpenCode Go prompts for masked `apiKey` and prefilled `baseUrl` only, and writes `type: \"openai-compatible\"` (baseUrl `https://opencode.ai/zen/go`). After a provider is configured and enabled, `copilot-api start` can run without any GitHub token.\n\nUse `copilot-api auth login --provider custom` to add or update another third-party provider from the CLI. The command prompts for the provider name, supported type (`anthropic`, `openai-compatible`, or `openai-responses`), `baseUrl`, masked `apiKey`, and `authType`; `authType` may be left as the type default or set to `x-api-key` / `authorization`.\n\n### Debug Command Options\n\n| Option | Description               | Default | Alias |\n| ------ | ------------------------- | ------- | ----- |\n| --json | Output debug info as JSON | false   | none  |\n\n## Configuration (config.json)\n\n- **Location:** `~/.local/share/copilot-api/config.json` (Linux/macOS) or `%USERPROFILE%\\.local\\share\\copilot-api\\config.json` (Windows).\n- **Default shape:**\n  ```json\n  {\n    \"auth\": {\n      \"apiKeys\": [],\n      \"adminApiKey\": \"<auto-generated-on-startup>\"\n    },\n    \"providers\": {},\n    \"modelMappings\": {},\n    \"extraPrompts\": {\n      \"gpt-5-mini\": \"<built-in exploration prompt>\"\n    },\n    \"smallModel\": \"gpt-5-mini\",\n    \"contextManagement\": {\n      \"messages\": true,\n      \"responses\": false\n    },\n    \"modelResponsesApiCompactThresholds\": {\n      \"gpt-5.4\": 217600,\n      \"gpt-5.5\": 217600,\n      \"gpt-5.6-sol\": 231200,\n      \"gpt-5.6-terra\": 231200,\n      \"gpt-5.6-luna\": 231200\n    },\n    \"modelReasoningEfforts\": {\n      \"gpt-5-mini\": \"low\"\n    },\n    \"useMessagesApi\": true,\n    \"useResponsesApiWebSocket\": true,\n    \"useResponsesApiWebSearch\": true,\n    \"messageApiWebSearchModel\": \"gpt-5-mini\"\n  }\n  ```\n- **auth.apiKeys:** API keys used for request authentication on non-admin routes. Supports multiple keys for rotation. Requests can authenticate with either `x-api-key: <key>` or `Authorization: Bearer <key>`. If empty or omitted, authentication for non-admin routes is disabled.\n- **auth.adminApiKey:** Single admin key used only for `/admin/*` routes. If missing, the server generates a random key at startup and writes it back to `config.json`. Requests use the same `x-api-key` or `Authorization: Bearer` headers, but regular `auth.apiKeys` never grant access to `/admin/*`.\n- **modelMappings:** Exact `sourceModel -> targetModel` rewrites shared by top-level `POST /v1/messages`, `POST /v1/messages/count_tokens`, `POST /v1/responses`, and `POST /v1/chat/completions` requests. Omit it or leave it as `{}` to disable rewrites. Both the source and target must be non-empty strings. Targets can be regular model IDs or `provider/model` aliases such as `dashscope/qwen3.6-plus`, and the rewrite happens before provider alias parsing. These mappings are not split per interface. The admin endpoints `GET/POST /admin/config/model-mappings` read and update only this field.\n- **extraPrompts:** Map of `model -> prompt` appended to the first system prompt when translating Anthropic-style requests to Responses API. Use this to inject guardrails or guidance per model. Missing default entries are auto-added without overwriting your custom prompts. For GPT-5.3+ models (e.g. `gpt-5.3-codex`, `gpt-5.4`, `gpt-5.5`), a built-in commentary prompt is used as fallback when not explicitly configured. The built-in prompts enable phase-aware commentary, which lets the model emit a short user-facing progress update before tools or deeper reasoning.\n- **providers:** Global upstream provider map. Each provider key (for example `dashscope`) becomes a route prefix (`/dashscope/v1/messages`). Supports `type: \"anthropic\"`, `type: \"openai-compatible\"`, and `type: \"openai-responses\"`. Top-level clients can also use `model: \"dashscope/model-id\"` with `/v1/messages`, `/v1/messages/count_tokens`, `/v1/responses`, and `/v1/chat/completions`; the gateway strips the `dashscope/` prefix before forwarding upstream. `openai-compatible` providers support both chat and Messages flows: `/v1/chat/completions` is proxied to upstream `/v1/chat/completions`, while `/v1/messages` and `/:provider/v1/messages` are translated to upstream chat completions and translated back to Anthropic Messages responses. `GET /v1/models` aggregates enabled provider models with `provider/model-id` IDs; use `GET /dashscope/v1/models` for a single provider's raw model list.\n  - `enabled` defaults to `true` if omitted.\n  - `baseUrl` should be provider API base URL without the final endpoint. For Anthropic providers, omit `/v1/messages`; for OpenAI-compatible providers, omit `/v1/chat/completions`; for OpenAI Responses providers, omit `/v1/responses`.\n  - `apiKey` is used as the upstream credential value and is required for regular providers.\n  - `authType` (optional): Controls how `apiKey` is sent upstream. Supports `x-api-key` and `authorization` for regular providers. Anthropic providers default to `x-api-key`; OpenAI-compatible and OpenAI Responses providers default to `authorization`. When set to `authorization`, the proxy sends `Authorization: Bearer <apiKey>`. `oauth2` is reserved for the built-in `codex` provider and is written automatically by `auth login --provider codex`.\n  - `pricingCurrency` (optional): Provider-level currency used for token cost calculation, for example `USD` or `CNY`. Quick providers default to `CNY` for DashScope and DeepSeek, and `USD` for Codex/OpenRouter. Costs are grouped by currency and are not exchange-rate converted.\n  - `models` (optional): Per-model configuration map. Each key is a model ID (matching the model name in requests), and the value is:\n    - `temperature` (optional): Default temperature value used when the request does not specify one.\n    - `topP` (optional): Default top_p value used when the request does not specify one.\n    - `topK` (optional): Default top_k value used when the request does not specify one.\n    - `extraBody` (optional): Dynamic fields merged into the upstream request body for that model. Request body fields with the same name take precedence. OpenAI-compatible providers can use this for fields such as `enable_thinking`, `preserve_thinking`, `reasoning_effort`. `thinking_budget` is a special OpenAI-compatible provider override: when configured in `extraBody`, it is forced after Anthropic `thinking.budget_tokens` translation and overrides the request-derived budget. For providers whose name is `dashscope` or whose `baseUrl` contains `aliyuncs.com`, the request-derived `thinking_budget` (from Anthropic `thinking.budget_tokens`) is forwarded upstream; for other OpenAI-compatible providers the request-derived `thinking_budget` is stripped, while an `extraBody` `thinking_budget` is still honored. For DashScope providers, `preserve_thinking` defaults to `true` when not explicitly set in `extraBody` or the request body.\n    - `pricing` (optional): Per-model token prices, in the provider `pricingCurrency`, per 1M tokens. Supported fields are `input`, `output`, `cachedInput` (implicit cache read), `explicitCachedInput` (explicit cache read), and `cacheCreationInput`. Use `tiers` with `maxInputTokens` for input-size tiered pricing.\n    - `contextCache` (optional): Defaults to `true` for providers whose name is `dashscope` or whose `baseUrl` contains `aliyuncs.com`; defaults to `false` for other OpenAI-compatible providers. This enables Alibaba Cloud Model Studio/DashScope explicit context cache by injecting `cache_control: { \"type\": \"ephemeral\" }` on up to 4 content blocks using the Context Cache format. The cache breakpoint strategy matches opencode's main provider flow: the first 2 system messages plus the last 2 non-system messages. Marked string content is converted to text content part arrays for `system` / `user` / `assistant` / `tool` messages; existing array content is marked on the last part. Set this to `false` when the model already supports implicit caching, or when the upstream does not accept this explicit-cache extension field. Set this to `true` for non-DashScope providers that support the same explicit-cache extension. Applied on both `/v1/messages` and `/v1/chat/completions` routes.\n    - `supportPdf` (optional): Controls whether the model supports PDF/document content. Defaults to `false`; unsupported PDFs are converted to a text notice. Set it to `true` to send PDF/document blocks as OpenAI Chat Completions file parts.\n    - `toolContentSupportType` (optional): Tool result content capabilities for that model, as an array of `array`, `image`, and `pdf`. Provider routes default to string-only tool content when omitted. If `supportPdf` is `true` but this list does not include `pdf`, file parts in tool results are moved to user role messages. This provider default does not change the Copilot main flow, which continues to support array + image and not PDF.\n    - `type` (optional): Per-model override of the provider protocol type. Supports `anthropic`, `openai-compatible`, and `openai-responses`. When set, the provider's `/v1/messages` route uses this model's type instead of the provider-level type for request routing, auth header resolution, and upstream endpoint selection. This is useful for providers like OpenCode Go whose upstream supports both OpenAI-compatible and Anthropic Messages APIs for different models. When the type is overridden, the auth header is resolved from the overridden type's default (Anthropic defaults to `x-api-key`; OpenAI-compatible/Responses default to `authorization`).\n\n  Example DashScope model settings:\n  ```json\n  {\n    \"providers\": {\n      \"dashscope\": {\n        \"type\": \"openai-compatible\",\n        \"enabled\": true,\n        \"baseUrl\": \"https://dashscope.aliyuncs.com/compatible-mode\",\n        \"apiKey\": \"sk-your-dashscope-key\",\n        \"pricingCurrency\": \"CNY\",\n        \"models\": {\n          \"qwen3.7-plus\": {\n            \"temperature\": 1,\n            \"topP\": 0.95,\n            \"topK\": 20,\n            \"extraBody\": {\n              \"preserve_thinking\": true\n            }\n          },\n          \"glm-5.1\": {\n            \"temperature\": 0.7,\n            \"topP\": 0.95,\n            \"contextCache\": true,\n            \"pricing\": {\n              \"tiers\": [\n                {\n                  \"maxInputTokens\": 32000,\n                  \"input\": 6,\n                  \"cachedInput\": 1.2,\n                  \"explicitCachedInput\": 0.6,\n                  \"cacheCreationInput\": 7.5,\n                  \"output\": 24\n                },\n                {\n                  \"maxInputTokens\": 200000,\n                  \"input\": 8,\n                  \"cachedInput\": 1.6,\n                  \"explicitCachedInput\": 0.8,\n                  \"cacheCreationInput\": 10,\n                  \"output\": 28\n                }\n              ]\n            },\n            \"extraBody\": {\n              \"preserve_thinking\": true\n            }\n          }\n        }\n      }\n    }\n  }\n  ```\n  Built-in token prices cover Codex GPT models in USD, DashScope `qwen3.7-max`, `qwen3.7-plus`, `glm-5.1`, `glm-5.2` in CNY, DeepSeek `deepseek-v4-flash`, `deepseek-v4-pro`, `deepseek-chat`, `deepseek-reasoner` in CNY, and OpenCode Go models (`glm-5.2`, `deepseek-v4-flash`, `deepseek-v4-pro`, `kimi-k2.7-code`, `mimo-v2.5`, `mimo-v2.5-pro`, `qwen3.7-plus`, `qwen3.7-max`, `minimax-m2.5`, `minimax-m3`) in USD. User `pricing` entries override built-ins. For DashScope, cached tokens are charged as explicit cache reads when the upstream usage includes `cache_creation_input_tokens`; otherwise `cachedInput` is used as the implicit cache read price. For DeepSeek, `prompt_cache_hit_tokens` map to cached input and `prompt_cache_miss_tokens` map to regular input.\n- **smallModel:** Fallback model used for tool-less warmup messages (e.g., Claude Code probe requests); defaults to gpt-5-mini.\n- **contextManagement:** Controls whether the proxy adds Responses API `context_management` compaction instructions. `messages` applies when Anthropic-style `/v1/messages` requests are translated to Responses API, including `openai-responses` provider message routes, and defaults to `true`. `responses` applies to native `/v1/responses` traffic, including `provider/model` aliases and the built-in `codex` provider, and defaults to `false`. Enable `responses` only after checking that your client supports context management compaction. When enabled, the request includes `context_management` in the body and keeps only the latest compaction carrier on follow-up turns. **Note:** Context management is forcibly disabled for GPT-5.6 and above models (e.g. `gpt-5.6-sol`, `gpt-5.6-terra`, `gpt-5.6-luna`) because enabling it breaks prompt cache hits on those models. This override takes precedence over the `contextManagement` and `modelResponsesApiCompactThresholds` settings.\n- **modelResponsesApiCompactThresholds:** Per-model Responses API `compact_threshold` overrides used when the proxy adds `context_management`. These values take precedence over the fallback threshold from `resolveResponsesCompactThreshold` (`max_prompt_tokens * ratio`, or the default fallback). Defaults set `gpt-5.4` and `gpt-5.5` to `217600` (`272000 * 0.8`), and `gpt-5.6-sol`, `gpt-5.6-terra`, `gpt-5.6-luna` to `231200` (`272000 * 0.85`). Models not listed continue to use the normal fallback logic.\n- **modelReasoningEfforts:** Per-model fallback reasoning effort for `/v1/messages` requests. It is used only when the request does not provide `output_config.effort`.\n  - **Priority:** request `output_config.effort` > `modelReasoningEfforts[model]` > built-in default (`xhigh` for GPT-5.3+ models, otherwise `high`).\n  - **Forwarding:** the resolved value remains `output_config.effort` for the Copilot native Messages API and becomes `reasoning.effort` when translated to the Responses API.\n  - **Configuration values:** `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`.\n- **useMessagesApi:** When `true`, Claude-family models that support Copilot's native `/v1/messages` endpoint will use the Messages API; otherwise they fall back to `/chat/completions`. Set to `false` to disable Messages API routing and always use `/chat/completions`. Defaults to `true`.\n- **useResponsesApiWebSocket:** When `true`, Responses API requests use Copilot's websocket transport for models that advertise `ws:/responses`; models that only advertise `/responses` continue to use HTTP. Set to `false` to disable websocket routing and use HTTP `/responses` whenever the selected model supports it. Defaults to `true`. If the Responses API WebSocket gets closed, it is usually caused by your own network. If you are using a VPN, try switching to a different node.\n- **useResponsesApiWebSearch:** When `true`, the server keeps Responses API tools with `type: \"web_search\"` and forwards them upstream. Set to `false` to strip those tools from `/responses` payloads. Defaults to `true`.\n- **messageApiWebSearchModel:** Global fallback model used when a top-level Copilot `/v1/messages` request contains only the server-side `web_search` tool. Defaults to `gpt-5-mini`. If the value is a `provider/model` alias, the request is routed into that provider's Messages API path with the provider prefix stripped. For Copilot GPT models, web search runs through `/responses`. Mixed `web_search` plus custom tools are not supported and the server-side `web_search` tool is stripped.\n- **claudeTokenMultiplier:** Multiplier applied to the fallback GPT-tokenizer estimate for Claude `/v1/messages/count_tokens` requests. Defaults to `1.15`. Increase it if your client is still compacting too late. This setting is only used when the proxy is estimating Claude tokens locally; if `anthropicApiKey` is configured and Anthropic token counting succeeds, the exact Anthropic count is returned instead.\n- **anthropicApiKey:** Anthropic API key used to forward Claude `/v1/messages/count_tokens` requests to Anthropic's real token counting endpoint, which returns exact counts instead of GPT tokenizer estimates. Can also be set via the `ANTHROPIC_API_KEY` environment variable. If not set, or if the upstream call fails, token counting falls back to local GPT tokenizer estimation controlled by `claudeTokenMultiplier`.\n\nEdit this file to customize prompts or swap in your own fast model. Restart the server (or rerun the command) after changes so the cached config is refreshed.\n\n## API Authentication\n\n- **Protected non-admin routes:** All routes except `/`, `/usage-viewer`, and `/usage-viewer/` require authentication when `auth.apiKeys` is configured and non-empty.\n- **Admin routes:** All `/admin/*` routes require `auth.adminApiKey`. If it is missing, the server generates one at startup and persists it to `config.json` before serving requests.\n- **Allowed auth headers:**\n  - `x-api-key: <your_key>`\n  - `Authorization: Bearer <your_key>`\n- **CORS preflight:** `OPTIONS` requests are always allowed.\n- **When no regular keys are configured:** Non-admin routes continue to allow requests. This does not apply to `/admin/*`, which only accepts `auth.adminApiKey`.\n\nExample request for a regular protected route:\n\n```sh\ncurl http://localhost:4141/v1/models \\\n  -H \"x-api-key: your_api_key\"\n```\n\nExample request for an admin route:\n\n```sh\ncurl http://localhost:4141/admin/config/model-mappings \\\n  -H \"x-api-key: your_admin_api_key\"\n```\n\n## API Endpoints\n\nThe server exposes several OpenAI- and Anthropic-compatible endpoints. Requests can target GitHub Copilot, the built-in `codex` provider, or configured providers depending on the selected model and `provider/model` alias.\n\n### OpenAI Compatible Endpoints\n\nThese endpoints mimic the OpenAI API structure.\n\n| Endpoint                    | Method | Description                                                      |\n| --------------------------- | ------ | ---------------------------------------------------------------- |\n| `POST /v1/responses`        | `POST` | OpenAI Most advanced interface for generating model responses. Supports `provider/model` aliases for `openai-responses` providers. |\n| `POST /v1/chat/completions` | `POST` | Creates a model response for the given chat conversation. Supports `provider/model` aliases for `openai-compatible` providers and can be used without Copilot when the target provider is configured. |\n| `GET /v1/models`            | `GET`  | Lists Copilot models plus enabled provider models using `provider/model-id` IDs. Requests from Codex clients (`User-Agent` beginning with `codex`) are forwarded to the Codex Models upstream. |\n| `POST /v1/embeddings`       | `POST` | Creates an embedding vector representing the input text.         |\n\n### Codex Backend Proxy Endpoints\n\nThese endpoints require an active Codex login. Each endpoint is available both without a version prefix and under `/v1`.\n\n| Endpoint | Method | Description |\n| --- | --- | --- |\n| `POST /alpha/search`<br>`POST /v1/alpha/search` | `POST` | Transparently forwards the JSON body and query parameters to the Codex Alpha Search upstream. |\n| `POST /images/generations`<br>`POST /v1/images/generations` | `POST` | Forwards a JSON image generation request to the Codex Images upstream. When the request omits `Content-Type`, the gateway defaults it to `application/json`. |\n| `POST /images/edits`<br>`POST /v1/images/edits` | `POST` | Forwards an image edit request to the Codex Images upstream. Send this request as `multipart/form-data` and let the HTTP client generate the `boundary`; the gateway preserves the incoming content type and streams the upload body. |\n\nFor every endpoint above, the gateway replaces client authorization and account headers with the active Codex login, preserves query parameters and compatible request headers, and returns the upstream status, headers, and body.\n\n### Anthropic Compatible Endpoints\n\nThese endpoints are designed to be compatible with the Anthropic Messages API. Provider-scoped models, Responses, alpha-search, and images routes accept both unversioned and `/v1` paths; Messages routes remain under `/v1`.\n\n| Endpoint                         | Method | Description                                                  |\n| -------------------------------- | ------ | ------------------------------------------------------------ |\n| `POST /v1/messages`              | `POST` | Creates a model response for a given conversation. Supports `provider/model` aliases for configured providers, including translation through `openai-compatible` providers. |\n| `POST /v1/messages/count_tokens` | `POST` | Calculates the number of tokens for a given set of messages. Supports `provider/model` aliases for configured providers. |\n| `POST /:provider/v1/messages`       | `POST` | Proxies Anthropic Messages requests to the configured Anthropic provider, translates them through an OpenAI-compatible provider, or translates them through an OpenAI Responses provider. |\n| `GET /:provider/models`<br>`GET /:provider/v1/models` | `GET` | Proxies model listing requests to the configured provider. For `codex`, returns the built-in catalog by default; Codex clients (`User-Agent` starting with `codex`) are forwarded to the Codex Models upstream. |\n| `POST /:provider/v1/messages/count_tokens` | `POST` | Calculates tokens locally for provider route requests. |\n| `POST /:provider/responses`<br>`POST /:provider/v1/responses` | `POST` | Proxies OpenAI Responses requests to a configured `openai-responses` provider (including `codex`). |\n| `POST /:provider/alpha/search`<br>`POST /:provider/v1/alpha/search` | `POST` | Proxies alpha-search requests. For `codex`, forwards to the Codex Alpha Search upstream; for other providers, forwards to `{baseUrl}/v1/alpha/search`. |\n| `POST /:provider/images/generations`<br>`POST /:provider/v1/images/generations` | `POST` | Proxies image generation. For `codex`, uses the Codex Images upstream; for other providers, forwards to `{baseUrl}/v1/images/generations` (15-minute timeout). |\n| `POST /:provider/images/edits`<br>`POST /:provider/v1/images/edits` | `POST` | Proxies image edits. For `codex`, uses the Codex Images upstream; for other providers, forwards multipart/streamed bodies to `{baseUrl}/v1/images/edits` (15-minute timeout). |\n\n### Usage Monitoring Endpoints\n\nNew endpoints for monitoring your Copilot usage and quotas.\n\n| Endpoint     | Method | Description                                                  |\n| ------------ | ------ | ------------------------------------------------------------ |\n| `GET /usage` | `GET`  | Get detailed Copilot usage statistics and quota information. |\n| `GET /token` | `GET`  | Get the current Copilot token being used by the API.         |\n\n### Admin / Configuration Endpoints\n\nThese endpoints are reserved for local administrative actions and only accept `auth.adminApiKey`.\n\n| Endpoint                              | Method | Description                                                                 |\n| ------------------------------------- | ------ | --------------------------------------------------------------------------- |\n| `GET /admin/config/model-mappings`    | `GET`  | Returns the current `config.json` path and the active `modelMappings` map.  |\n| `POST /admin/config/model-mappings`   | `POST` | Updates only the `modelMappings` field in `config.json` and returns it back. |\n\n## Example Usage\n\nCommon `npx` commands:\n\n```sh\n# Start the gateway\nnpx @jeffreycao/copilot-api@latest start\n\n# Start on a custom port with verbose logging\nnpx @jeffreycao/copilot-api@latest start --port 8080 --verbose\n\n# Run the auth flow\nnpx @jeffreycao/copilot-api@latest auth login\n\n# Configure a third-party provider, then run without GitHub Copilot\nnpx @jeffreycao/copilot-api@latest auth login --provider dashscope\nnpx @jeffreycao/copilot-api@latest start\n\n# Print debug information as JSON\nnpx @jeffreycao/copilot-api@latest debug --json\n\n# Run the published CLI with Bun instead of Node.js\nbunx --bun @jeffreycao/copilot-api@latest start\n```\n\nOpenAI-compatible provider examples after configuring `dashscope`:\n\n```sh\ncurl http://localhost:4141/v1/chat/completions \\\n  -H \"content-type: application/json\" \\\n  -d '{\"model\":\"dashscope/qwen3.6-plus\",\"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]}'\n\ncurl http://localhost:4141/dashscope/v1/messages \\\n  -H \"content-type: application/json\" \\\n  -d '{\"model\":\"qwen3.6-plus\",\"max_tokens\":1024,\"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]}'\n```\n\n## Usage Tips\n\n### CLAUDE.md or AGENTS.md Recommended Content\n\nTo add these reminders manually, include the following in `CLAUDE.md` for Claude Code, or `AGENTS.md` for opencode/codex:\n\n```\n- Prohibited from directly asking questions to users, MUST use question tool.\n- Once you can confirm that the task is complete, MUST use question tool to make user confirm. The user may respond with feedback if they are not satisfied with the result, which you can use to make improvements and try again, after try again, MUST use question tool to make user confirm again.\n```\n"}, "287d2d330c299bbdf3ed213a1bc05b1739aecf03": {"t": 1785765548.7925396, "n": 49761, "h": "da4119356b143f6f", "c": "# Copilot API Proxy\n\nEnglish | [简体中文](./README.zh-CN.md)\n\n## Important Notes\n\n> [!IMPORTANT]\n> **Before using, please be aware of the following:**\n>\n> 1. **Claude Code configuration:** When using with Claude Code, please configure the model ID as `claude-opus-4-8`. Example claude `settings.json` see [Manual Configuration with `settings.json`](#manual-configuration-with-settingsjson). \n>\n> 2. **Built-in `copilot`, `codex` and third-party providers:** Run `npx @jeffreycao/copilot-api@latest auth` and choose `copilot`, `codex`, `deepseek`, `custom`, or other providers.\n>\n> 3. **Note:** See [GitHub Copilot Security Notice](./NOTICE.md#github-copilot-security-notice) for the warning removed from the README header.\n\n---\n\n## Project Overview\n\nA small AI gateway that can use GitHub Copilot, the built-in `codex` provider, or configured third-party providers such as DashScope. GitHub Copilot is optional: if no GitHub token is available, the server can still start in provider-only mode as long as at least one enabled provider is configured.\n\nThe gateway exposes OpenAI- and Anthropic-compatible APIs from one local endpoint, so tools like [Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview), OpenCode, Codex, and OpenAI-compatible clients can share the same local server.\n\nOn the GitHub Copilot path, the gateway prefers Copilot's native Anthropic-style Messages API when available, preserving more Claude-native behavior for tool-heavy workflows.\n\n## Features\n\n- **OpenAI and Anthropic compatibility**: Serve `/v1/responses`, `/v1/chat/completions`, `/v1/models`, `/v1/embeddings`, and `/v1/messages` from one local gateway.\n- **Copilot is optional**: Use GitHub Copilot when credentials are present, or run the server with only configured providers.\n- **One gateway for Copilot, `codex`, and external providers**: Route GitHub Copilot, the built-in `codex` provider, and configured third-party providers behind the same endpoint.\n- **Standalone third-party providers**: Configure providers such as DashScope, DeepSeek, OpenRouter, or a custom provider and start the gateway without a GitHub Copilot login.\n- **OpenAI-compatible providers on chat and Messages APIs**: `openai-compatible` providers can serve top-level `/v1/chat/completions` through `model: \"provider/model\"` and Anthropic-style `/v1/messages` through request/response translation.\n- **Agent-friendly Claude handling on Copilot**: Prefer native `/v1/messages` when available, preserve Claude-style tool flows, support Anthropic beta features, Claude WebSearch through Responses-capable models, and keep subagent/session markers intact.\n- **Claude Code and OpenCode integration**: Works with Claude Code and OpenCode, including direct Anthropic-compatible usage through `@ai-sdk/anthropic`.\n- **Flexible auth and deployment options**: Supports interactive login or direct tokens, individual/business/enterprise plans, GitHub Enterprise, opencode OAuth, and custom data directories.\n- **Multi-provider routing**: Expose provider-specific `/:provider/...` routes or use `model: \"provider/model\"` on the top-level API.\n\n## Prerequisites\n\n- Bun (>= 1.2.x)\n- Node.js if you plan to run the published CLI with `npx`\n- GitHub account with Copilot subscription only if you want to use the GitHub Copilot provider\n- An API key or OAuth login for at least one configured provider if you want to run without GitHub Copilot\n\n## Installation\n\nTo install dependencies, run:\n\n```sh\nbun install\n```\n\nTo start the server directly from source:\n\n```sh\nbun run start start\n```\n\n## Running from Source\n\nThe project can be run from source in several ways:\n\n### Development Mode\n\n```sh\nbun run dev start\n```\n\n### Production Mode\n\n```sh\nbun run start start\n```\n\n## Using with npx\n\nYou can run the project directly using npx:\n\n> [!IMPORTANT]\n> Token usage storage uses Node's built-in `node:sqlite` module when running with `npx`. It is enabled on Node.js >= 22.13.0. On Node.js < 22.13.0, the CLI still starts, but token usage storage is disabled.\n>\n> If you want token usage storage without upgrading Node.js, run the published CLI with Bun instead: `bunx --bun @jeffreycao/copilot-api@latest start`.\n\n```sh\nnpx @jeffreycao/copilot-api@latest start\n```\n\nWith options:\n\n```sh\nnpx @jeffreycao/copilot-api@latest start --port 8080\n```\n\nFor authentication or provider configuration only:\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth\n```\n\nTo run without GitHub Copilot, configure at least one provider first, then start the server normally:\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth login --provider dashscope\nnpx @jeffreycao/copilot-api@latest start\n```\n\n## Using with Docker\n\nBuild the image:\n\n```sh\ndocker build -t copilot-api .\n```\n\nRun the container with a bind mount so auth data survives restarts:\n\n```sh\nmkdir -p ./copilot-data\ndocker run -p 4141:4141 -v $(pwd)/copilot-data:/root/.local/share/copilot-api copilot-api\n```\n\nThis stores GitHub auth data, provider config, and other gateway state in `./copilot-data` on the host, mapped to `/root/.local/share/copilot-api` in the container.\n\nOr pass a GitHub token directly:\n\n```sh\ndocker run -p 4141:4141 -e GH_TOKEN=your_github_token_here copilot-api\n```\n\n## Electron Desktop App\n\nIf you prefer a GUI, this repository also includes an Electron desktop app in `desktop/`. It supports GitHub Copilot sign-in, OpenAI Codex OAuth, and API-key configuration for DeepSeek, DashScope, OpenRouter, or a custom provider. After authorization or provider configuration, it can start and stop the local proxy with one click and shows the local endpoint, auth header, available models, usage, and logs in the app.\n\nThe settings screen also exposes `OAuth App`, `API Home`, `Enterprise URL`, verbose logging, and minimize-to-tray. Desktop packages are published in GitHub Releases:\n\nhttps://github.com/caozhiyuan/copilot-api/releases\n\nDownload the installer for your platform, authorize or configure a provider inside the app, choose a port, start the server, then point your client at the local endpoint shown in the app. Packaged desktop builds use the bundled Electron runtime, so normal desktop usage does not require installing Node.js separately. Token usage history is enabled when that bundled runtime supports SQLite.\n\nThe desktop app's Advanced Config page reads and writes the shared model mappings through `GET/POST /admin/config/model-mappings`. The same mappings apply across `POST /v1/messages`, `POST /v1/messages/count_tokens`, `POST /v1/responses`, and `POST /v1/chat/completions` instead of being split per interface. It uses `auth.adminApiKey` instead of the regular `auth.apiKeys`, and the app reads that key directly from `config.json` after the server has generated it on startup.\n\n### Desktop App Screenshots\n\nMain dashboard, token usage breakdown in the bundled Electron app:\n\n<p align=\"center\">\n  <img src=\"./docs/screenshots/desktop-dashboard.png\" alt=\"Copilot API desktop app dashboard\" width=\"49%\" />\n  <img src=\"./docs/screenshots/desktop-token-usage.png\" alt=\"Copilot API desktop app token usage view\" width=\"49%\" />\n</p>\n\n## Using with Claude Code\n\nThis AI gateway can be used to power [Claude Code](https://docs.anthropic.com/en/claude-code), an experimental conversational AI assistant for developers from Anthropic.\n\nThere are two ways to configure Claude Code to use this AI gateway:\n\n### Interactive Setup with `--claude-code` flag\n\nTo get started, run the `start` command with the `--claude-code` flag:\n\n```sh\nnpx @jeffreycao/copilot-api@latest start --claude-code\n```\n\nYou will be prompted to select a primary model and a \"small, fast\" model for background tasks. After selecting the models, a command will be copied to your clipboard. This command sets the necessary environment variables for Claude Code to use the gateway.\n\nPaste and run this command in a new terminal to launch Claude Code.\n\n### Manual Configuration with `settings.json`\n\nAlternatively, you can configure Claude Code by creating a `.claude/settings.json` file in your project's root directory. This file should contain the environment variables needed by Claude Code. This way you don't need to run the interactive setup every time.\n\nHere is an example `.claude/settings.json` file:\n\n```json\n{\n  \"env\": {\n    \"ANTHROPIC_BASE_URL\": \"http://localhost:4141\",\n    \"ANTHROPIC_AUTH_TOKEN\": \"dummy\",\n    \"ANTHROPIC_MODEL\": \"deepseek/deepseek-v4-pro\",\n    \"ANTHROPIC_DEFAULT_SONNET_MODEL\": \"deepseek/deepseek-v4-pro\",\n    \"ANTHROPIC_DEFAULT_HAIKU_MODEL\": \"deepseek/deepseek-v4-flash\",\n    \"DISABLE_NON_ESSENTIAL_MODEL_CALLS\": \"1\",\n    \"CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC\": \"1\",\n    \"CLAUDE_CODE_ATTRIBUTION_HEADER\": \"0\",\n    \"CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION\": \"false\",\n    \"CLAUDE_CODE_DISABLE_TERMINAL_TITLE\": \"true\",\n    \"CLAUDE_CODE_ENABLE_AWAY_SUMMARY\": \"0\"\n  },\n  \"permissions\": {\n    \"deny\": [\n      \"mcp__ide__executeCode\"\n    ]\n  }\n}\n```\n\n- Replace `ANTHROPIC_MODEL`, `ANTHROPIC_DEFAULT_OPUS_MODEL`, `ANTHROPIC_DEFAULT_SONNET_MODEL`, and `ANTHROPIC_DEFAULT_HAIKU_MODEL` according to your needs. After configuration, please install the claude code plugin [Plugin Integrations](#plugin-integrations).  \n- Setting CLAUDE_CODE_ATTRIBUTION_HEADER to 0 can prevent Claude code from adding billing and version information in system prompts, thereby avoiding prompt cache invalidation.\n- Turning off CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION and CLAUDE_CODE_ENABLE_AWAY_SUMMARY can prevent quota from being consumed unnecessarily.\n- Claude Code WebSearch is supported for pure search requests. For Copilot, keep the global `messageApiWebSearchModel` set to a Responses-capable GPT model or a `provider/model` alias. For provider routes, use a native Anthropic provider or an `openai-responses` provider. Add `WebSearch` to `permissions.deny` only if you want to forbid this traffic.\n- If using a non-Claude model, do not enable ENABLE_TOOL_SEARCH. If using the Claude model, can enable ENABLE_TOOL_SEARCH. The current Claude Code uses the client tool search mode. In this mode, loading defer tools requires an additional request each time.\n- `CLAUDE_CODE_AUTO_COMPACT_WINDOW`: Set the context capacity in tokens used for auto-compaction calculations. Defaults to the model's context window: 200K for standard models or 1M for extended context models. Use a lower value like `500000` on a 1M model (e.g., `claude-opus-4-6[1m]`) to treat the window as 500K for compaction purposes. The value is capped at the model's actual context window. `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` is applied as a percentage of this value. Setting this variable decouples the compaction threshold from the status line's `used_percentage`, which always uses the model's full context window.\n\nYou can find more options here: [Claude Code settings](https://docs.anthropic.com/en/docs/claude-code/settings#environment-variables)\n\nYou can also read more about IDE integration here: [Add Claude Code to your IDE](https://docs.anthropic.com/en/docs/claude-code/ide-integrations)\n\n## Using with OpenCode\n\nOpenCode already has a direct GitHub Copilot provider. Use this section when you want OpenCode to point at this AI gateway through `@ai-sdk/anthropic` and reuse the agent behaviors described earlier in this README.\n\n### Minimal setup\n\nStart the AI gateway with the OpenCode OAuth app:\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth --oauth-app=opencode\nnpx @jeffreycao/copilot-api@latest start\n```\n\nThen point OpenCode at the gateway with `@ai-sdk/anthropic`.\n\nExample `~/.config/opencode/opencode.json`:\n\n```json\n{\n  \"$schema\": \"https://opencode.ai/config.json\",\n  \"provider\": {\n    \"local\": {\n      \"npm\": \"@ai-sdk/anthropic\",\n      \"name\": \"My Local\",\n      \"options\": {\n        \"baseURL\": \"http://localhost:4141/v1\",\n        \"apiKey\": \"dummy\"\n      },\n      \"models\": {\n        \"gpt-5.4\": {\n          \"name\": \"gpt-5.4\",\n          \"modalities\": {\n            \"input\": [\"text\", \"image\"],\n            \"output\": [\"text\"]\n          },\n          \"limit\": {\n            \"context\": 400000,\n            \"input\": 272000,\n            \"output\": 128000\n          }\n        },\n        \"claude-sonnet-4.6\": {\n          \"id\": \"claude-sonnet-4.6\",\n          \"name\": \"claude-sonnet-4.6\",\n          \"modalities\": {\n            \"input\": [\"text\", \"image\"],\n            \"output\": [\"text\"]\n          },          \n          \"limit\": {\n            \"context\": 200000,\n            \"output\": 32000\n          },\n          \"options\": {\n            \"thinking\": {\n              \"type\": \"adaptive\"\n            },\n            \"effort\": \"max\"\n          }\n        }\n      }\n    }\n  }\n}\n```\n\nWhy these fields matter:\n\n- `npm: \"@ai-sdk/anthropic\"` is the important part. OpenCode will speak Anthropic Messages semantics to this AI gateway instead of flattening everything into OpenAI Chat Completions.\n- `options.baseURL` should be `http://localhost:4141/v1`; the Anthropic SDK will append `/messages`, `/models`, and `/messages/count_tokens` automatically.\n- If you enable `auth.apiKeys` in this AI gateway, replace `dummy` with a real key. Otherwise any placeholder value is fine.\n\n## Using with Codex\n\nThis AI gateway can also power Codex.\n\n### Codex `config.toml` Reference\n\nAdd the following `[model_providers.copilot_api]` section to your Codex `~/.codex/config.toml`:\n\n```toml\nmodel_provider = \"copilot_api\"\nmodel_reasoning_summary = \"auto\"\nmodel_context_window = 272000\nmodel_auto_compact_token_limit = 244800\n\n[model_providers.copilot_api]\nname = \"OpenAI\"\nbase_url = \"http://localhost:4141\"\nenv_key = \"GITHUB_COPILOT_API_KEY\"\nrequires_openai_auth = true\nsupports_websockets = false\nwire_api = \"responses\"\nrequest_max_retries = 3\nstream_max_retries = 1\nstream_idle_timeout_ms = 300000\n\n[features]\nremote_compaction_v2 = true\n\n[analytics]\nenabled = false\n```\n\n> [!NOTE]\n> This configuration is specific to Codex and the GitHub Copilot provider. `name` must be set to `\"OpenAI\"`. It can help mitigate Codex local compact cache miss issues.\n> If you are using the codex provider, it is recommended to set `base_url` to `\"http://localhost:4141/codex\"`.\n\n## GPT Tool Search\n\nFor GPT Responses models such as `gpt-5.4+`, this AI gateway can expose Responses `tool_search` through a small MCP bridge. The same bridge can be used by Claude Code and opencode, as long as the client loads MCP servers and sends Anthropic Messages traffic through this gateway.\n\nDo not set Claude Code's native `ENABLE_TOOL_SEARCH` for GPT models. That flag enables Claude Code's own client-side tool search mode, and it may stop forwarding deferred tool definitions. This gateway needs the full tool definitions so it can keep the small always-loaded tool set eager and translate every other tool into Responses deferred namespaces.\n\nIf you install `tool-search@copilot-api-marketplace`, Claude Code receives this MCP bridge automatically and you can skip the manual Claude Code MCP setup below.\n\nAdd the tool search bridge to the MCP config used by Claude Code:\n\n```json\n{\n  \"mcpServers\": {\n    \"tool_search\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@jeffreycao/copilot-api@latest\", \"mcp\"]\n    }\n  }\n}\n```\n\nAdd the tool search bridge to the MCP config used by opencode:\n\n```json\n{\n  \"mcp\": {\n    \"tool_search\": {\n      \"type\": \"local\",\n      \"command\": [\"npx\", \"-y\", \"@jeffreycao/copilot-api@latest\", \"mcp\"]\n    }\n  }\n}\n```\n\nFor local development, use `bun` as the command and `[\"run\", \"./src/main.ts\", \"mcp\"]` as the args.\n\nInternally, the gateway now configures OpenAI Responses `tool_search` in client-executed mode. Deferred tools are still exposed as searchable namespaces, but the model is explicitly asked to return the exact deferred tool names it wants to load next.\n\nThe bridge uses direct tool selection, not query search. Its tool input is `names`, a comma-separated list of exact deferred tool names, for example `TaskList,TaskGet,mcp__fetch__fetch`.\n\n## Plugin Integrations\n\nPlugin integrations are available for Claude Code and opencode.\n\n#### Claude Code plugin integration (marketplace-based)\n\nThe Claude Code integration is packaged as two plugins:\n\n- `agent-inject` injects `__SUBAGENT_MARKER__...` on `SubagentStart`, so the gateway can infer `x-initiator: agent`.\n- `tool-search` registers the `tool_search` MCP bridge used for GPT Responses deferred tool loading.\n\n- Marketplace catalog in this repository: `.claude-plugin/marketplace.json`\n- Plugin sources in this repository: `plugin/claude/agent-inject`, `plugin/claude/tool-search`\n\nAdd the marketplace remotely:\n\n```sh\n/plugin marketplace add https://github.com/caozhiyuan/copilot-api.git\n```\n\nInstall the plugins from the marketplace:\n\n```sh\n/plugin install agent-inject@copilot-api-marketplace\n/plugin install tool-search@copilot-api-marketplace\n```\n\nAfter installation, `agent-inject` injects `__SUBAGENT_MARKER__...` on `SubagentStart`, and the gateway uses it to infer `x-initiator: agent`.\n\nThe `agent-inject` plugin also registers a `UserPromptSubmit` hook that returns `{\"continue\": true}`, and it can inject `SessionStart` reminder rules through environment variables:\n\n- `CLAUDE_PLUGIN_ENABLE_QUESTION_RULES=1` enables the two reminders about using the `question` tool automatically for Claude Code. Alternatively, you can add the same reminders manually in `CLAUDE.md`; see [CLAUDE.md or AGENTS.md Recommended Content](#claudemd-or-agentsmd-recommended-content).\n- `CLAUDE_PLUGIN_ENABLE_NO_BACKGROUND_AGENTS_RULE=1` enables the `run_in_background: true` avoidance reminder for agent hooks.\n\nThe `tool-search` plugin bundles the same MCP bridge described in [GPT Tool Search](#gpt-tool-search), so Claude Code users do not need to add the `tool_search` server manually when they install that plugin.\n\n#### Opencode plugin\n\nThe subagent marker producer is packaged as an opencode plugin located at `plugin/opencode/subagent-marker.js`.\n\n**Installation:**\n\nCopy the plugin file to your opencode plugins directory:\n\n```sh\n# Clone or download this repository, then copy the plugin\ncp plugin/opencode/subagent-marker.js ~/.config/opencode/plugins/\n```\n\nOr manually create the file at `~/.config/opencode/plugins/subagent-marker.js` with the plugin content.\n\n**Features:**\n\n- Tracks sub-sessions created by subagents\n- Automatically prepends a marker system reminder (`__SUBAGENT_MARKER__...`) to subagent chat messages\n- Sets `x-session-id` header for session tracking\n- Enables the gateway to infer `x-initiator: agent` for subagent-originated requests\n\nThe plugin hooks into `session.created`, `session.deleted`, `chat.message`, and `chat.headers` events to provide seamless subagent marker functionality.\n\n## Using the Usage Viewer\n\nAfter starting the server, a URL to the Copilot Usage Dashboard will be displayed in your console. This dashboard is a web interface for monitoring your API usage.\n\n1.  Start the server. For example, using npx:\n    ```sh\n    npx @jeffreycao/copilot-api@latest start\n    ```\n2.  The server will output a URL to the usage viewer. Copy and paste this URL into your browser. It will look something like this:\n    `http://localhost:4141/usage-viewer?endpoint=http://localhost:4141/usage`\n    - If you use the `start.bat` script on Windows, this page will open automatically.\n\nThe dashboard provides a user-friendly interface to view your Copilot usage data:\n\n> Token usage history requires Bun or Node.js >= 22.13.0. On Node.js < 22.13.0, the server runs normally but token usage storage is disabled.\n\n- **API Endpoint URL**: The dashboard is pre-configured to fetch data from your local server endpoint via a URL query parameter. You can manually switch this to any other compatible API endpoint.\n- **x-api-key Authentication**: If API Key authentication is enabled, you can provide the `x-api-key` request header. The key is persisted in the browser's local storage.\n- **Period Selector**: Choose from Day, Week, or Month time ranges. The URL query parameter updates automatically when you switch, making it easy to bookmark and share.\n- **Fetch Data**: Click the \"Refresh\" button to load or refresh the usage data. The dashboard also fetches data automatically on page load.\n- **Copilot Quotas**: View quota usage for services such as Chat and Completions via progress bars. Hover over a card to see used/remaining details.\n- **Token Usage Metric Cards**: See a summary of Total, Input, Output, Cache Read, Cache Write, Requests, and estimated cost for the current period.\n- **Trend Chart (Week / Month)**: An interactive line chart with model and metric filters. Click a data point to inspect the usage breakdown for a specific day.\n- **Model Breakdown Table**: A per-model summary of requests, input/output/cache tokens, and estimated cost for the selected period.\n- **Request Events (Paginated)**: A time-sorted list of request event records with pagination support, showing timestamps, models, request IDs, and token counts.\n- **Detailed Information**: See the full JSON response from the API for a detailed breakdown of all available usage statistics.\n- **URL-based Configuration**: You can also specify the API endpoint and period directly via `endpoint` and `period` query parameters. For example:\n  `http://localhost:4141/usage-viewer?endpoint=http://your-api-server/usage&period=week`\n\n### Usage Viewer Screenshot\n\n<p align=\"center\">\n  <img src=\"./docs/screenshots/usage-viewer.png\" alt=\"Copilot API usage viewer\" width=\"900\" />\n</p>\n\n## Command Structure\n\nCopilot API now uses a subcommand structure with these main commands:\n\n- `start`: Start the gateway server. If a GitHub token is available, the server starts with Copilot enabled. If no GitHub token is available, it starts in provider-only mode when at least one enabled provider exists; otherwise it guides you through provider setup.\n- `auth`: Run provider login or configuration without starting the server. Use it for GitHub Copilot login, Codex OAuth, or third-party provider API key setup.\n- `debug`: Display diagnostic information including version, runtime details, file paths, and authentication status. Useful for troubleshooting and support.\n\n## Command Line Options\n\n### Global Options\n\nThe following options can be used with any subcommand. When passing them before the subcommand, use the `--key=value` form:\n\n| Option            | Description                                            | Default | Alias |\n| ----------------- | ------------------------------------------------------ | ------- | ----- |\n| --api-home        | Path to the API home directory (sets COPILOT_API_HOME) | none    | none  |\n| --oauth-app       | OAuth app identifier (sets COPILOT_API_OAUTH_APP)      | none    | none  |\n| --enterprise-url  | Enterprise URL for GitHub (sets COPILOT_API_ENTERPRISE_URL) | none | none |\n\n### Start Command Options\n\nThe following command line options are available for the `start` command:\n\n| Option         | Description                                                                   | Default    | Alias |\n| -------------- | ----------------------------------------------------------------------------- | ---------- | ----- |\n| --port         | Port to listen on                                                             | 4141       | -p    |\n| --verbose      | Enable verbose logging                                                        | false      | -v    |\n| --github-token | Provide GitHub token directly (must be generated using the `auth` subcommand) | none       | -g    |\n| --claude-code  | Generate a command to launch Claude Code with Copilot API config              | false      | -c    |\n| --show-token   | Show GitHub and Copilot tokens on fetch and refresh                           | false      | none  |\n| --proxy-env    | Initialize proxy from environment variables                                   | false      | none  |\n\n### Auth Command Options\n\n| Option       | Description               | Default | Alias |\n| ------------ | ------------------------- | ------- | ----- |\n| --provider   | Provider to log in with or configure (`copilot`, `codex`, `opencode-go`, `deepseek`, `dashscope`, `openrouter`, or `custom`) | prompt | none |\n| --verbose    | Enable verbose logging    | false   | -v    |\n| --show-token | Show GitHub token on auth | false   | none  |\n\nUse `copilot-api auth login --provider copilot` only when you want to enable the GitHub Copilot provider. Copilot is not required for `codex` or third-party provider-only usage.\n\nUse `copilot-api auth login --provider deepseek`, `--provider dashscope`, `--provider openrouter`, or `--provider opencode-go` to add or update those common third-party providers from the CLI. DeepSeek prompts for masked `apiKey`, provider `type` (default `anthropic`), and `baseUrl` defaulting to `https://api.deepseek.com/anthropic`. DashScope prompts for masked `apiKey`, provider `type` (default `openai-compatible`), and prefilled `baseUrl`. OpenRouter prompts for masked `apiKey` and prefilled `baseUrl` only, and writes `type: \"anthropic\"`. OpenCode Go prompts for masked `apiKey` and prefilled `baseUrl` only, and writes `type: \"openai-compatible\"` (baseUrl `https://opencode.ai/zen/go`). After a provider is configured and enabled, `copilot-api start` can run without any GitHub token.\n\nUse `copilot-api auth login --provider custom` to add or update another third-party provider from the CLI. The command prompts for the provider name, supported type (`anthropic`, `openai-compatible`, or `openai-responses`), `baseUrl`, masked `apiKey`, and `authType`; `authType` may be left as the type default or set to `x-api-key` / `authorization`.\n\n### Debug Command Options\n\n| Option | Description               | Default | Alias |\n| ------ | ------------------------- | ------- | ----- |\n| --json | Output debug info as JSON | false   | none  |\n\n## Configuration (config.json)\n\n- **Location:** `~/.local/share/copilot-api/config.json` (Linux/macOS) or `%USERPROFILE%\\.local\\share\\copilot-api\\config.json` (Windows).\n- **Default shape:**\n  ```json\n  {\n    \"auth\": {\n      \"apiKeys\": [],\n      \"adminApiKey\": \"<auto-generated-on-startup>\"\n    },\n    \"providers\": {},\n    \"modelMappings\": {},\n    \"extraPrompts\": {\n      \"gpt-5-mini\": \"<built-in exploration prompt>\"\n    },\n    \"smallModel\": \"gpt-5-mini\",\n    \"contextManagement\": {\n      \"messages\": true,\n      \"responses\": false\n    },\n    \"modelResponsesApiCompactThresholds\": {\n      \"gpt-5.4\": 217600,\n      \"gpt-5.5\": 217600,\n      \"gpt-5.6-sol\": 231200,\n      \"gpt-5.6-terra\": 231200,\n      \"gpt-5.6-luna\": 231200\n    },\n    \"modelReasoningEfforts\": {\n      \"gpt-5-mini\": \"low\"\n    },\n    \"useMessagesApi\": true,\n    \"useResponsesApiWebSocket\": true,\n    \"useResponsesApiWebSearch\": true,\n    \"messageApiWebSearchModel\": \"gpt-5-mini\"\n  }\n  ```\n- **auth.apiKeys:** API keys used for request authentication on non-admin routes. Supports multiple keys for rotation. Requests can authenticate with either `x-api-key: <key>` or `Authorization: Bearer <key>`. If empty or omitted, authentication for non-admin routes is disabled.\n- **auth.adminApiKey:** Single admin key used only for `/admin/*` routes. If missing, the server generates a random key at startup and writes it back to `config.json`. Requests use the same `x-api-key` or `Authorization: Bearer` headers, but regular `auth.apiKeys` never grant access to `/admin/*`.\n- **modelMappings:** Exact `sourceModel -> targetModel` rewrites shared by top-level `POST /v1/messages`, `POST /v1/messages/count_tokens`, `POST /v1/responses`, and `POST /v1/chat/completions` requests. Omit it or leave it as `{}` to disable rewrites. Both the source and target must be non-empty strings. Targets can be regular model IDs or `provider/model` aliases such as `dashscope/qwen3.6-plus`, and the rewrite happens before provider alias parsing. These mappings are not split per interface. The admin endpoints `GET/POST /admin/config/model-mappings` read and update only this field.\n- **extraPrompts:** Map of `model -> prompt` appended to the first system prompt when translating Anthropic-style requests to Responses API. Use this to inject guardrails or guidance per model. Missing default entries are auto-added without overwriting your custom prompts. For GPT-5.3+ models (e.g. `gpt-5.3-codex`, `gpt-5.4`, `gpt-5.5`), a built-in commentary prompt is used as fallback when not explicitly configured. The built-in prompts enable phase-aware commentary, which lets the model emit a short user-facing progress update before tools or deeper reasoning.\n- **providers:** Global upstream provider map. Each provider key (for example `dashscope`) becomes a route prefix (`/dashscope/v1/messages`). Supports `type: \"anthropic\"`, `type: \"openai-compatible\"`, and `type: \"openai-responses\"`. Top-level clients can also use `model: \"dashscope/model-id\"` with `/v1/messages`, `/v1/messages/count_tokens`, `/v1/responses`, and `/v1/chat/completions`; the gateway strips the `dashscope/` prefix before forwarding upstream. `openai-compatible` providers support both chat and Messages flows: `/v1/chat/completions` is proxied to upstream `/v1/chat/completions`, while `/v1/messages` and `/:provider/v1/messages` are translated to upstream chat completions and translated back to Anthropic Messages responses. `GET /v1/models` aggregates enabled provider models with `provider/model-id` IDs; use `GET /dashscope/v1/models` for a single provider's raw model list.\n  - `enabled` defaults to `true` if omitted.\n  - `baseUrl` should be provider API base URL without the final endpoint. For Anthropic providers, omit `/v1/messages`; for OpenAI-compatible providers, omit `/v1/chat/completions`; for OpenAI Responses providers, omit `/v1/responses`.\n  - `apiKey` is used as the upstream credential value and is required for regular providers.\n  - `authType` (optional): Controls how `apiKey` is sent upstream. Supports `x-api-key` and `authorization` for regular providers. Anthropic providers default to `x-api-key`; OpenAI-compatible and OpenAI Responses providers default to `authorization`. When set to `authorization`, the proxy sends `Authorization: Bearer <apiKey>`. `oauth2` is reserved for the built-in `codex` provider and is written automatically by `auth login --provider codex`.\n  - `pricingCurrency` (optional): Provider-level currency used for token cost calculation, for example `USD` or `CNY`. Quick providers default to `CNY` for DashScope and DeepSeek, and `USD` for Codex/OpenRouter. Costs are grouped by currency and are not exchange-rate converted.\n  - `models` (optional): Per-model configuration map. Each key is a model ID (matching the model name in requests), and the value is:\n    - `temperature` (optional): Default temperature value used when the request does not specify one.\n    - `topP` (optional): Default top_p value used when the request does not specify one.\n    - `topK` (optional): Default top_k value used when the request does not specify one.\n    - `extraBody` (optional): Dynamic fields merged into the upstream request body for that model. Request body fields with the same name take precedence. OpenAI-compatible providers can use this for fields such as `enable_thinking`, `preserve_thinking`, `reasoning_effort`. `thinking_budget` is a special OpenAI-compatible provider override: when configured in `extraBody`, it is forced after Anthropic `thinking.budget_tokens` translation and overrides the request-derived budget. For providers whose name is `dashscope` or whose `baseUrl` contains `aliyuncs.com`, the request-derived `thinking_budget` (from Anthropic `thinking.budget_tokens`) is forwarded upstream; for other OpenAI-compatible providers the request-derived `thinking_budget` is stripped, while an `extraBody` `thinking_budget` is still honored. For DashScope providers, `preserve_thinking` defaults to `true` when not explicitly set in `extraBody` or the request body.\n    - `pricing` (optional): Per-model token prices, in the provider `pricingCurrency`, per 1M tokens. Supported fields are `input`, `output`, `cachedInput` (implicit cache read), `explicitCachedInput` (explicit cache read), and `cacheCreationInput`. Use `tiers` with `maxInputTokens` for input-size tiered pricing.\n    - `contextCache` (optional): Defaults to `true` for providers whose name is `dashscope` or whose `baseUrl` contains `aliyuncs.com`; defaults to `false` for other OpenAI-compatible providers. This enables Alibaba Cloud Model Studio/DashScope explicit context cache by injecting `cache_control: { \"type\": \"ephemeral\" }` on up to 4 content blocks using the Context Cache format. The cache breakpoint strategy matches opencode's main provider flow: the first 2 system messages plus the last 2 non-system messages. Marked string content is converted to text content part arrays for `system` / `user` / `assistant` / `tool` messages; existing array content is marked on the last part. Set this to `false` when the model already supports implicit caching, or when the upstream does not accept this explicit-cache extension field. Set this to `true` for non-DashScope providers that support the same explicit-cache extension. Applied on both `/v1/messages` and `/v1/chat/completions` routes.\n    - `supportPdf` (optional): Controls whether the model supports PDF/document content. Defaults to `false`; unsupported PDFs are converted to a text notice. Set it to `true` to send PDF/document blocks as OpenAI Chat Completions file parts.\n    - `toolContentSupportType` (optional): Tool result content capabilities for that model, as an array of `array`, `image`, and `pdf`. Provider routes default to string-only tool content when omitted. If `supportPdf` is `true` but this list does not include `pdf`, file parts in tool results are moved to user role messages. This provider default does not change the Copilot main flow, which continues to support array + image and not PDF.\n    - `type` (optional): Per-model override of the provider protocol type. Supports `anthropic`, `openai-compatible`, and `openai-responses`. When set, the provider's `/v1/messages` route uses this model's type instead of the provider-level type for request routing, auth header resolution, and upstream endpoint selection. This is useful for providers like OpenCode Go whose upstream supports both OpenAI-compatible and Anthropic Messages APIs for different models. When the type is overridden, the auth header is resolved from the overridden type's default (Anthropic defaults to `x-api-key`; OpenAI-compatible/Responses default to `authorization`).\n\n  Example DashScope model settings:\n  ```json\n  {\n    \"providers\": {\n      \"dashscope\": {\n        \"type\": \"openai-compatible\",\n        \"enabled\": true,\n        \"baseUrl\": \"https://dashscope.aliyuncs.com/compatible-mode\",\n        \"apiKey\": \"sk-your-dashscope-key\",\n        \"pricingCurrency\": \"CNY\",\n        \"models\": {\n          \"qwen3.7-plus\": {\n            \"temperature\": 1,\n            \"topP\": 0.95,\n            \"topK\": 20,\n            \"extraBody\": {\n              \"preserve_thinking\": true\n            }\n          },\n          \"glm-5.1\": {\n            \"temperature\": 0.7,\n            \"topP\": 0.95,\n            \"contextCache\": true,\n            \"pricing\": {\n              \"tiers\": [\n                {\n                  \"maxInputTokens\": 32000,\n                  \"input\": 6,\n                  \"cachedInput\": 1.2,\n                  \"explicitCachedInput\": 0.6,\n                  \"cacheCreationInput\": 7.5,\n                  \"output\": 24\n                },\n                {\n                  \"maxInputTokens\": 200000,\n                  \"input\": 8,\n                  \"cachedInput\": 1.6,\n                  \"explicitCachedInput\": 0.8,\n                  \"cacheCreationInput\": 10,\n                  \"output\": 28\n                }\n              ]\n            },\n            \"extraBody\": {\n              \"preserve_thinking\": true\n            }\n          }\n        }\n      }\n    }\n  }\n  ```\n  Built-in token prices cover Codex GPT models in USD, DashScope `qwen3.7-max`, `qwen3.7-plus`, `glm-5.1`, `glm-5.2` in CNY, DeepSeek `deepseek-v4-flash`, `deepseek-v4-pro`, `deepseek-chat`, `deepseek-reasoner` in CNY, and OpenCode Go models (`glm-5.2`, `deepseek-v4-flash`, `deepseek-v4-pro`, `kimi-k2.7-code`, `mimo-v2.5`, `mimo-v2.5-pro`, `qwen3.7-plus`, `qwen3.7-max`, `minimax-m2.5`, `minimax-m3`) in USD. User `pricing` entries override built-ins. For DashScope, cached tokens are charged as explicit cache reads when the upstream usage includes `cache_creation_input_tokens`; otherwise `cachedInput` is used as the implicit cache read price. For DeepSeek, `prompt_cache_hit_tokens` map to cached input and `prompt_cache_miss_tokens` map to regular input.\n- **smallModel:** Fallback model used for tool-less warmup messages (e.g., Claude Code probe requests); defaults to gpt-5-mini.\n- **contextManagement:** Controls whether the proxy adds Responses API `context_management` compaction instructions. `messages` applies when Anthropic-style `/v1/messages` requests are translated to Responses API, including `openai-responses` provider message routes, and defaults to `true`. `responses` applies to native `/v1/responses` traffic, including `provider/model` aliases and the built-in `codex` provider, and defaults to `false`. Enable `responses` only after checking that your client supports context management compaction. When enabled, the request includes `context_management` in the body and keeps only the latest compaction carrier on follow-up turns. **Note:** Context management is forcibly disabled for GPT-5.6 and above models (e.g. `gpt-5.6-sol`, `gpt-5.6-terra`, `gpt-5.6-luna`) because enabling it breaks prompt cache hits on those models. This override takes precedence over the `contextManagement` and `modelResponsesApiCompactThresholds` settings.\n- **modelResponsesApiCompactThresholds:** Per-model Responses API `compact_threshold` overrides used when the proxy adds `context_management`. These values take precedence over the fallback threshold from `resolveResponsesCompactThreshold` (`max_prompt_tokens * ratio`, or the default fallback). Defaults set `gpt-5.4` and `gpt-5.5` to `217600` (`272000 * 0.8`), and `gpt-5.6-sol`, `gpt-5.6-terra`, `gpt-5.6-luna` to `231200` (`272000 * 0.85`). Models not listed continue to use the normal fallback logic.\n- **modelReasoningEfforts:** Per-model fallback reasoning effort for `/v1/messages` requests. It is used only when the request does not provide `output_config.effort`.\n  - **Priority:** request `output_config.effort` > `modelReasoningEfforts[model]` > built-in default (`xhigh` for GPT-5.3+ models, otherwise `high`).\n  - **Forwarding:** the resolved value remains `output_config.effort` for the Copilot native Messages API and becomes `reasoning.effort` when translated to the Responses API.\n  - **Configuration values:** `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`.\n- **useMessagesApi:** When `true`, Claude-family models that support Copilot's native `/v1/messages` endpoint will use the Messages API; otherwise they fall back to `/chat/completions`. Set to `false` to disable Messages API routing and always use `/chat/completions`. Defaults to `true`.\n- **useResponsesApiWebSocket:** When `true`, Responses API requests use Copilot's websocket transport for models that advertise `ws:/responses`; models that only advertise `/responses` continue to use HTTP. Set to `false` to disable websocket routing and use HTTP `/responses` whenever the selected model supports it. Defaults to `true`. If the Responses API WebSocket gets closed, it is usually caused by your own network. If you are using a VPN, try switching to a different node.\n- **useResponsesApiWebSearch:** When `true`, the server keeps Responses API tools with `type: \"web_search\"` and forwards them upstream. Set to `false` to strip those tools from `/responses` payloads. Defaults to `true`.\n- **messageApiWebSearchModel:** Global fallback model used when a top-level Copilot `/v1/messages` request contains only the server-side `web_search` tool. Defaults to `gpt-5-mini`. If the value is a `provider/model` alias, the request is routed into that provider's Messages API path with the provider prefix stripped. For Copilot GPT models, web search runs through `/responses`. Mixed `web_search` plus custom tools are not supported and the server-side `web_search` tool is stripped.\n- **claudeTokenMultiplier:** Multiplier applied to the fallback GPT-tokenizer estimate for Claude `/v1/messages/count_tokens` requests. Defaults to `1.15`. Increase it if your client is still compacting too late. This setting is only used when the proxy is estimating Claude tokens locally; if `anthropicApiKey` is configured and Anthropic token counting succeeds, the exact Anthropic count is returned instead.\n- **anthropicApiKey:** Anthropic API key used to forward Claude `/v1/messages/count_tokens` requests to Anthropic's real token counting endpoint, which returns exact counts instead of GPT tokenizer estimates. Can also be set via the `ANTHROPIC_API_KEY` environment variable. If not set, or if the upstream call fails, token counting falls back to local GPT tokenizer estimation controlled by `claudeTokenMultiplier`.\n\nEdit this file to customize prompts or swap in your own fast model. Restart the server (or rerun the command) after changes so the cached config is refreshed.\n\n## API Authentication\n\n- **Protected non-admin routes:** All routes except `/`, `/usage-viewer`, and `/usage-viewer/` require authentication when `auth.apiKeys` is configured and non-empty.\n- **Admin routes:** All `/admin/*` routes require `auth.adminApiKey`. If it is missing, the server generates one at startup and persists it to `config.json` before serving requests.\n- **Allowed auth headers:**\n  - `x-api-key: <your_key>`\n  - `Authorization: Bearer <your_key>`\n- **CORS preflight:** `OPTIONS` requests are always allowed.\n- **When no regular keys are configured:** Non-admin routes continue to allow requests. This does not apply to `/admin/*`, which only accepts `auth.adminApiKey`.\n\nExample request for a regular protected route:\n\n```sh\ncurl http://localhost:4141/v1/models \\\n  -H \"x-api-key: your_api_key\"\n```\n\nExample request for an admin route:\n\n```sh\ncurl http://localhost:4141/admin/config/model-mappings \\\n  -H \"x-api-key: your_admin_api_key\"\n```\n\n## API Endpoints\n\nThe server exposes several OpenAI- and Anthropic-compatible endpoints. Requests can target GitHub Copilot, the built-in `codex` provider, or configured providers depending on the selected model and `provider/model` alias.\n\n### OpenAI Compatible Endpoints\n\nThese endpoints mimic the OpenAI API structure.\n\n| Endpoint                    | Method | Description                                                      |\n| --------------------------- | ------ | ---------------------------------------------------------------- |\n| `POST /v1/responses`        | `POST` | OpenAI Most advanced interface for generating model responses. Supports `provider/model` aliases for `openai-responses` providers. |\n| `POST /v1/chat/completions` | `POST` | Creates a model response for the given chat conversation. Supports `provider/model` aliases for `openai-compatible` providers and can be used without Copilot when the target provider is configured. |\n| `GET /v1/models`            | `GET`  | Lists Copilot models plus enabled provider models using `provider/model-id` IDs. Requests from Codex clients (`User-Agent` beginning with `codex`) are forwarded to the Codex Models upstream. |\n| `POST /v1/embeddings`       | `POST` | Creates an embedding vector representing the input text.         |\n\n### Codex Backend Proxy Endpoints\n\nThese endpoints require an active Codex login. Each endpoint is available both without a version prefix and under `/v1`.\n\n| Endpoint | Method | Description |\n| --- | --- | --- |\n| `POST /alpha/search`<br>`POST /v1/alpha/search` | `POST` | Transparently forwards the JSON body and query parameters to the Codex Alpha Search upstream. |\n| `POST /images/generations`<br>`POST /v1/images/generations` | `POST` | Forwards a JSON image generation request to the Codex Images upstream. When the request omits `Content-Type`, the gateway defaults it to `application/json`. |\n| `POST /images/edits`<br>`POST /v1/images/edits` | `POST` | Forwards an image edit request to the Codex Images upstream. Send this request as `multipart/form-data` and let the HTTP client generate the `boundary`; the gateway preserves the incoming content type and streams the upload body. |\n\nFor every endpoint above, the gateway replaces client authorization and account headers with the active Codex login, preserves query parameters and compatible request headers, and returns the upstream status, headers, and body.\n\n### Anthropic Compatible Endpoints\n\nThese endpoints are designed to be compatible with the Anthropic Messages API. Provider-scoped models, Responses, alpha-search, and images routes accept both unversioned and `/v1` paths; Messages routes remain under `/v1`.\n\n| Endpoint                         | Method | Description                                                  |\n| -------------------------------- | ------ | ------------------------------------------------------------ |\n| `POST /v1/messages`              | `POST` | Creates a model response for a given conversation. Supports `provider/model` aliases for configured providers, including translation through `openai-compatible` providers. |\n| `POST /v1/messages/count_tokens` | `POST` | Calculates the number of tokens for a given set of messages. Supports `provider/model` aliases for configured providers. |\n| `POST /:provider/v1/messages`       | `POST` | Proxies Anthropic Messages requests to the configured Anthropic provider, translates them through an OpenAI-compatible provider, or translates them through an OpenAI Responses provider. |\n| `GET /:provider/models`<br>`GET /:provider/v1/models` | `GET` | Proxies model listing requests to the configured provider. For `codex`, returns the built-in catalog by default; Codex clients (`User-Agent` starting with `codex`) are forwarded to the Codex Models upstream. |\n| `POST /:provider/v1/messages/count_tokens` | `POST` | Calculates tokens locally for provider route requests. |\n| `POST /:provider/responses`<br>`POST /:provider/v1/responses` | `POST` | Proxies OpenAI Responses requests to a configured `openai-responses` provider (including `codex`). |\n| `POST /:provider/alpha/search`<br>`POST /:provider/v1/alpha/search` | `POST` | Proxies alpha-search requests. For `codex`, forwards to the Codex Alpha Search upstream; for other providers, forwards to `{baseUrl}/v1/alpha/search`. |\n| `POST /:provider/images/generations`<br>`POST /:provider/v1/images/generations` | `POST` | Proxies image generation. For `codex`, uses the Codex Images upstream; for other providers, forwards to `{baseUrl}/v1/images/generations` (15-minute timeout). |\n| `POST /:provider/images/edits`<br>`POST /:provider/v1/images/edits` | `POST` | Proxies image edits. For `codex`, uses the Codex Images upstream; for other providers, forwards multipart/streamed bodies to `{baseUrl}/v1/images/edits` (15-minute timeout). |\n\n### Usage Monitoring Endpoints\n\nNew endpoints for monitoring your Copilot usage and quotas.\n\n| Endpoint     | Method | Description                                                  |\n| ------------ | ------ | ------------------------------------------------------------ |\n| `GET /usage` | `GET`  | Get detailed Copilot usage statistics and quota information. |\n| `GET /token` | `GET`  | Get the current Copilot token being used by the API.         |\n\n### Admin / Configuration Endpoints\n\nThese endpoints are reserved for local administrative actions and only accept `auth.adminApiKey`.\n\n| Endpoint                              | Method | Description                                                                 |\n| ------------------------------------- | ------ | --------------------------------------------------------------------------- |\n| `GET /admin/config/model-mappings`    | `GET`  | Returns the current `config.json` path and the active `modelMappings` map.  |\n| `POST /admin/config/model-mappings`   | `POST` | Updates only the `modelMappings` field in `config.json` and returns it back. |\n\n## Example Usage\n\nCommon `npx` commands:\n\n```sh\n# Start the gateway\nnpx @jeffreycao/copilot-api@latest start\n\n# Start on a custom port with verbose logging\nnpx @jeffreycao/copilot-api@latest start --port 8080 --verbose\n\n# Run the auth flow\nnpx @jeffreycao/copilot-api@latest auth login\n\n# Configure a third-party provider, then run without GitHub Copilot\nnpx @jeffreycao/copilot-api@latest auth login --provider dashscope\nnpx @jeffreycao/copilot-api@latest start\n\n# Print debug information as JSON\nnpx @jeffreycao/copilot-api@latest debug --json\n\n# Run the published CLI with Bun instead of Node.js\nbunx --bun @jeffreycao/copilot-api@latest start\n```\n\nOpenAI-compatible provider examples after configuring `dashscope`:\n\n```sh\ncurl http://localhost:4141/v1/chat/completions \\\n  -H \"content-type: application/json\" \\\n  -d '{\"model\":\"dashscope/qwen3.6-plus\",\"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]}'\n\ncurl http://localhost:4141/dashscope/v1/messages \\\n  -H \"content-type: application/json\" \\\n  -d '{\"model\":\"qwen3.6-plus\",\"max_tokens\":1024,\"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]}'\n```\n\n## Usage Tips\n\n### CLAUDE.md or AGENTS.md Recommended Content\n\nTo add these reminders manually, include the following in `CLAUDE.md` for Claude Code, or `AGENTS.md` for opencode/codex:\n\n```\n- Prohibited from directly asking questions to users, MUST use question tool.\n- Once you can confirm that the task is complete, MUST use question tool to make user confirm. The user may respond with feedback if they are not satisfied with the result, which you can use to make improvements and try again, after try again, MUST use question tool to make user confirm again.\n```\n"}, "cb458e50d8a4d4db635bf3eb3ecd27c0c21ad0a1": {"t": 1785765550.88848, "n": 49506, "h": "7f921f98895d4e67", "c": "# Copilot API Proxy\n\nEnglish | [简体中文](./README.zh-CN.md)\n\n## Important Notes\n\n> [!IMPORTANT]\n> **Before using, please be aware of the following:**\n>\n> 1. **Claude Code configuration:** When using with Claude Code, please configure the model ID as `claude-opus-4-8`. Example claude `settings.json` see [Manual Configuration with `settings.json`](#manual-configuration-with-settingsjson). \n>\n> 2. **Built-in `copilot`, `codex` and third-party providers:** Run `npx @jeffreycao/copilot-api@latest auth` and choose `copilot`, `codex`, `deepseek`, `custom`, or other providers.\n>\n> 3. **Note:** See [GitHub Copilot Security Notice](./NOTICE.md#github-copilot-security-notice) for the warning removed from the README header.\n\n---\n\n## Project Overview\n\nA small AI gateway that can use GitHub Copilot, the built-in `codex` provider, or configured third-party providers such as DashScope. GitHub Copilot is optional: if no GitHub token is available, the server can still start in provider-only mode as long as at least one enabled provider is configured.\n\nThe gateway exposes OpenAI- and Anthropic-compatible APIs from one local endpoint, so tools like [Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview), OpenCode, Codex, and OpenAI-compatible clients can share the same local server.\n\nOn the GitHub Copilot path, the gateway prefers Copilot's native Anthropic-style Messages API when available, preserving more Claude-native behavior for tool-heavy workflows.\n\n## Features\n\n- **OpenAI and Anthropic compatibility**: Serve `/v1/responses`, `/v1/chat/completions`, `/v1/models`, `/v1/embeddings`, and `/v1/messages` from one local gateway.\n- **Copilot is optional**: Use GitHub Copilot when credentials are present, or run the server with only configured providers.\n- **One gateway for Copilot, `codex`, and external providers**: Route GitHub Copilot, the built-in `codex` provider, and configured third-party providers behind the same endpoint.\n- **Standalone third-party providers**: Configure providers such as DashScope, DeepSeek, OpenRouter, or a custom provider and start the gateway without a GitHub Copilot login.\n- **OpenAI-compatible providers on chat and Messages APIs**: `openai-compatible` providers can serve top-level `/v1/chat/completions` through `model: \"provider/model\"` and Anthropic-style `/v1/messages` through request/response translation.\n- **Agent-friendly Claude handling on Copilot**: Prefer native `/v1/messages` when available, preserve Claude-style tool flows, support Anthropic beta features, Claude WebSearch through Responses-capable models, and keep subagent/session markers intact.\n- **Claude Code and OpenCode integration**: Works with Claude Code and OpenCode, including direct Anthropic-compatible usage through `@ai-sdk/anthropic`.\n- **Flexible auth and deployment options**: Supports interactive login or direct tokens, individual/business/enterprise plans, GitHub Enterprise, opencode OAuth, and custom data directories.\n- **Multi-provider routing**: Expose provider-specific `/:provider/...` routes or use `model: \"provider/model\"` on the top-level API.\n\n## Prerequisites\n\n- Bun (>= 1.2.x)\n- Node.js if you plan to run the published CLI with `npx`\n- GitHub account with Copilot subscription only if you want to use the GitHub Copilot provider\n- An API key or OAuth login for at least one configured provider if you want to run without GitHub Copilot\n\n## Installation\n\nTo install dependencies, run:\n\n```sh\nbun install\n```\n\nTo start the server directly from source:\n\n```sh\nbun run start start\n```\n\n## Running from Source\n\nThe project can be run from source in several ways:\n\n### Development Mode\n\n```sh\nbun run dev start\n```\n\n### Production Mode\n\n```sh\nbun run start start\n```\n\n## Using with npx\n\nYou can run the project directly using npx:\n\n> [!IMPORTANT]\n> Token usage storage uses Node's built-in `node:sqlite` module when running with `npx`. It is enabled on Node.js >= 22.13.0. On Node.js < 22.13.0, the CLI still starts, but token usage storage is disabled.\n>\n> If you want token usage storage without upgrading Node.js, run the published CLI with Bun instead: `bunx --bun @jeffreycao/copilot-api@latest start`.\n\n```sh\nnpx @jeffreycao/copilot-api@latest start\n```\n\nWith options:\n\n```sh\nnpx @jeffreycao/copilot-api@latest start --port 8080\n```\n\nFor authentication or provider configuration only:\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth\n```\n\nTo run without GitHub Copilot, configure at least one provider first, then start the server normally:\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth login --provider dashscope\nnpx @jeffreycao/copilot-api@latest start\n```\n\n## Using with Docker\n\nBuild the image:\n\n```sh\ndocker build -t copilot-api .\n```\n\nRun the container with a bind mount so auth data survives restarts:\n\n```sh\nmkdir -p ./copilot-data\ndocker run -p 4141:4141 -v $(pwd)/copilot-data:/root/.local/share/copilot-api copilot-api\n```\n\nThis stores GitHub auth data, provider config, and other gateway state in `./copilot-data` on the host, mapped to `/root/.local/share/copilot-api` in the container.\n\nOr pass a GitHub token directly:\n\n```sh\ndocker run -p 4141:4141 -e GH_TOKEN=your_github_token_here copilot-api\n```\n\n## Electron Desktop App\n\nIf you prefer a GUI, this repository also includes an Electron desktop app in `desktop/`. It supports GitHub Copilot sign-in, OpenAI Codex OAuth, and API-key configuration for DeepSeek, DashScope, OpenRouter, or a custom provider. After authorization or provider configuration, it can start and stop the local proxy with one click and shows the local endpoint, auth header, available models, usage, and logs in the app.\n\nThe settings screen also exposes `OAuth App`, `API Home`, `Enterprise URL`, verbose logging, and minimize-to-tray. Desktop packages are published in GitHub Releases:\n\nhttps://github.com/caozhiyuan/copilot-api/releases\n\nDownload the installer for your platform, authorize or configure a provider inside the app, choose a port, start the server, then point your client at the local endpoint shown in the app. Packaged desktop builds use the bundled Electron runtime, so normal desktop usage does not require installing Node.js separately. Token usage history is enabled when that bundled runtime supports SQLite.\n\nThe desktop app's Advanced Config page reads and writes the shared model mappings through `GET/POST /admin/config/model-mappings`. The same mappings apply across `POST /v1/messages`, `POST /v1/messages/count_tokens`, `POST /v1/responses`, and `POST /v1/chat/completions` instead of being split per interface. It uses `auth.adminApiKey` instead of the regular `auth.apiKeys`, and the app reads that key directly from `config.json` after the server has generated it on startup.\n\n### Desktop App Screenshots\n\nMain dashboard, token usage breakdown in the bundled Electron app:\n\n<p align=\"center\">\n  <img src=\"./docs/screenshots/desktop-dashboard.png\" alt=\"Copilot API desktop app dashboard\" width=\"49%\" />\n  <img src=\"./docs/screenshots/desktop-token-usage.png\" alt=\"Copilot API desktop app token usage view\" width=\"49%\" />\n</p>\n\n## Using with Claude Code\n\nThis AI gateway can be used to power [Claude Code](https://docs.anthropic.com/en/claude-code), an experimental conversational AI assistant for developers from Anthropic.\n\nThere are two ways to configure Claude Code to use this AI gateway:\n\n### Interactive Setup with `--claude-code` flag\n\nTo get started, run the `start` command with the `--claude-code` flag:\n\n```sh\nnpx @jeffreycao/copilot-api@latest start --claude-code\n```\n\nYou will be prompted to select a primary model and a \"small, fast\" model for background tasks. After selecting the models, a command will be copied to your clipboard. This command sets the necessary environment variables for Claude Code to use the gateway.\n\nPaste and run this command in a new terminal to launch Claude Code.\n\n### Manual Configuration with `settings.json`\n\nAlternatively, you can configure Claude Code by creating a `.claude/settings.json` file in your project's root directory. This file should contain the environment variables needed by Claude Code. This way you don't need to run the interactive setup every time.\n\nHere is an example `.claude/settings.json` file:\n\n```json\n{\n  \"env\": {\n    \"ANTHROPIC_BASE_URL\": \"http://localhost:4141\",\n    \"ANTHROPIC_AUTH_TOKEN\": \"dummy\",\n    \"ANTHROPIC_MODEL\": \"deepseek/deepseek-v4-pro\",\n    \"ANTHROPIC_DEFAULT_SONNET_MODEL\": \"deepseek/deepseek-v4-pro\",\n    \"ANTHROPIC_DEFAULT_HAIKU_MODEL\": \"deepseek/deepseek-v4-flash\",\n    \"DISABLE_NON_ESSENTIAL_MODEL_CALLS\": \"1\",\n    \"CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC\": \"1\",\n    \"CLAUDE_CODE_ATTRIBUTION_HEADER\": \"0\",\n    \"CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION\": \"false\",\n    \"CLAUDE_CODE_DISABLE_TERMINAL_TITLE\": \"true\",\n    \"CLAUDE_CODE_ENABLE_AWAY_SUMMARY\": \"0\"\n  },\n  \"permissions\": {\n    \"deny\": [\n      \"mcp__ide__executeCode\"\n    ]\n  }\n}\n```\n\n- Replace `ANTHROPIC_MODEL`, `ANTHROPIC_DEFAULT_OPUS_MODEL`, `ANTHROPIC_DEFAULT_SONNET_MODEL`, and `ANTHROPIC_DEFAULT_HAIKU_MODEL` according to your needs. After configuration, please install the claude code plugin [Plugin Integrations](#plugin-integrations).  \n- Setting CLAUDE_CODE_ATTRIBUTION_HEADER to 0 can prevent Claude code from adding billing and version information in system prompts, thereby avoiding prompt cache invalidation.\n- Turning off CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION and CLAUDE_CODE_ENABLE_AWAY_SUMMARY can prevent quota from being consumed unnecessarily.\n- Claude Code WebSearch is supported for pure search requests. For Copilot, keep the global `messageApiWebSearchModel` set to a Responses-capable GPT model or a `provider/model` alias. For provider routes, use a native Anthropic provider or an `openai-responses` provider. Add `WebSearch` to `permissions.deny` only if you want to forbid this traffic.\n- If using a non-Claude model, do not enable ENABLE_TOOL_SEARCH. If using the Claude model, can enable ENABLE_TOOL_SEARCH. The current Claude Code uses the client tool search mode. In this mode, loading defer tools requires an additional request each time.\n- `CLAUDE_CODE_AUTO_COMPACT_WINDOW`: Set the context capacity in tokens used for auto-compaction calculations. Defaults to the model's context window: 200K for standard models or 1M for extended context models. Use a lower value like `500000` on a 1M model (e.g., `claude-opus-4-6[1m]`) to treat the window as 500K for compaction purposes. The value is capped at the model's actual context window. `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` is applied as a percentage of this value. Setting this variable decouples the compaction threshold from the status line's `used_percentage`, which always uses the model's full context window.\n\nYou can find more options here: [Claude Code settings](https://docs.anthropic.com/en/docs/claude-code/settings#environment-variables)\n\nYou can also read more about IDE integration here: [Add Claude Code to your IDE](https://docs.anthropic.com/en/docs/claude-code/ide-integrations)\n\n## Using with OpenCode\n\nOpenCode already has a direct GitHub Copilot provider. Use this section when you want OpenCode to point at this AI gateway through `@ai-sdk/anthropic` and reuse the agent behaviors described earlier in this README.\n\n### Minimal setup\n\nStart the AI gateway with the OpenCode OAuth app:\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth --oauth-app=opencode\nnpx @jeffreycao/copilot-api@latest start\n```\n\nThen point OpenCode at the gateway with `@ai-sdk/anthropic`.\n\nExample `~/.config/opencode/opencode.json`:\n\n```json\n{\n  \"$schema\": \"https://opencode.ai/config.json\",\n  \"provider\": {\n    \"local\": {\n      \"npm\": \"@ai-sdk/anthropic\",\n      \"name\": \"My Local\",\n      \"options\": {\n        \"baseURL\": \"http://localhost:4141/v1\",\n        \"apiKey\": \"dummy\"\n      },\n      \"models\": {\n        \"gpt-5.4\": {\n          \"name\": \"gpt-5.4\",\n          \"modalities\": {\n            \"input\": [\"text\", \"image\"],\n            \"output\": [\"text\"]\n          },\n          \"limit\": {\n            \"context\": 400000,\n            \"input\": 272000,\n            \"output\": 128000\n          }\n        },\n        \"claude-sonnet-4.6\": {\n          \"id\": \"claude-sonnet-4.6\",\n          \"name\": \"claude-sonnet-4.6\",\n          \"modalities\": {\n            \"input\": [\"text\", \"image\"],\n            \"output\": [\"text\"]\n          },          \n          \"limit\": {\n            \"context\": 200000,\n            \"output\": 32000\n          },\n          \"options\": {\n            \"thinking\": {\n              \"type\": \"adaptive\"\n            },\n            \"effort\": \"max\"\n          }\n        }\n      }\n    }\n  }\n}\n```\n\nWhy these fields matter:\n\n- `npm: \"@ai-sdk/anthropic\"` is the important part. OpenCode will speak Anthropic Messages semantics to this AI gateway instead of flattening everything into OpenAI Chat Completions.\n- `options.baseURL` should be `http://localhost:4141/v1`; the Anthropic SDK will append `/messages`, `/models`, and `/messages/count_tokens` automatically.\n- If you enable `auth.apiKeys` in this AI gateway, replace `dummy` with a real key. Otherwise any placeholder value is fine.\n\n## Using with Codex\n\nThis AI gateway can also power Codex.\n\n### Codex `config.toml` Reference\n\nAdd the following `[model_providers.copilot_api]` section to your Codex `~/.codex/config.toml`:\n\n```toml\nmodel_provider = \"copilot_api\"\nmodel_reasoning_summary = \"auto\"\nmodel_context_window = 272000\nmodel_auto_compact_token_limit = 244800\n\n[model_providers.copilot_api]\nname = \"OpenAI\"\nbase_url = \"http://localhost:4141\"\nenv_key = \"GITHUB_COPILOT_API_KEY\"\nrequires_openai_auth = true\nsupports_websockets = false\nwire_api = \"responses\"\nrequest_max_retries = 3\nstream_max_retries = 1\nstream_idle_timeout_ms = 300000\n\n[features]\nremote_compaction_v2 = true\n\n[analytics]\nenabled = false\n```\n\n> [!NOTE]\n> This configuration is specific to Codex and the GitHub Copilot provider. `name` must be set to `\"OpenAI\"`. It can help mitigate Codex local compact cache miss issues. \n\n## GPT Tool Search\n\nFor GPT Responses models such as `gpt-5.4+`, this AI gateway can expose Responses `tool_search` through a small MCP bridge. The same bridge can be used by Claude Code and opencode, as long as the client loads MCP servers and sends Anthropic Messages traffic through this gateway.\n\nDo not set Claude Code's native `ENABLE_TOOL_SEARCH` for GPT models. That flag enables Claude Code's own client-side tool search mode, and it may stop forwarding deferred tool definitions. This gateway needs the full tool definitions so it can keep the small always-loaded tool set eager and translate every other tool into Responses deferred namespaces.\n\nIf you install `tool-search@copilot-api-marketplace`, Claude Code receives this MCP bridge automatically and you can skip the manual Claude Code MCP setup below.\n\nAdd the tool search bridge to the MCP config used by Claude Code:\n\n```json\n{\n  \"mcpServers\": {\n    \"tool_search\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@jeffreycao/copilot-api@latest\", \"mcp\"]\n    }\n  }\n}\n```\n\nAdd the tool search bridge to the MCP config used by opencode:\n\n```json\n{\n  \"mcp\": {\n    \"tool_search\": {\n      \"type\": \"local\",\n      \"command\": [\"npx\", \"-y\", \"@jeffreycao/copilot-api@latest\", \"mcp\"]\n    }\n  }\n}\n```\n\nFor local development, use `bun` as the command and `[\"run\", \"./src/main.ts\", \"mcp\"]` as the args.\n\nInternally, the gateway now configures OpenAI Responses `tool_search` in client-executed mode. Deferred tools are still exposed as searchable namespaces, but the model is explicitly asked to return the exact deferred tool names it wants to load next.\n\nThe bridge uses direct tool selection, not query search. Its tool input is `names`, a comma-separated list of exact deferred tool names, for example `TaskList,TaskGet,mcp__fetch__fetch`.\n\n## Plugin Integrations\n\nPlugin integrations are available for Claude Code and opencode.\n\n#### Claude Code plugin integration (marketplace-based)\n\nThe Claude Code integration is packaged as two plugins:\n\n- `agent-inject` injects `__SUBAGENT_MARKER__...` on `SubagentStart`, so the gateway can infer `x-initiator: agent`.\n- `tool-search` registers the `tool_search` MCP bridge used for GPT Responses deferred tool loading.\n\n- Marketplace catalog in this repository: `.claude-plugin/marketplace.json`\n- Plugin sources in this repository: `plugin/claude/agent-inject`, `plugin/claude/tool-search`\n\nAdd the marketplace remotely:\n\n```sh\n/plugin marketplace add https://github.com/caozhiyuan/copilot-api.git\n```\n\nInstall the plugins from the marketplace:\n\n```sh\n/plugin install agent-inject@copilot-api-marketplace\n/plugin install tool-search@copilot-api-marketplace\n```\n\nAfter installation, `agent-inject` injects `__SUBAGENT_MARKER__...` on `SubagentStart`, and the gateway uses it to infer `x-initiator: agent`.\n\nThe `agent-inject` plugin also registers a `UserPromptSubmit` hook that returns `{\"continue\": true}`, and it can inject `SessionStart` reminder rules through environment variables:\n\n- `CLAUDE_PLUGIN_ENABLE_QUESTION_RULES=1` enables the two reminders about using the `question` tool automatically for Claude Code. Alternatively, you can add the same reminders manually in `CLAUDE.md`; see [CLAUDE.md or AGENTS.md Recommended Content](#claudemd-or-agentsmd-recommended-content).\n- `CLAUDE_PLUGIN_ENABLE_NO_BACKGROUND_AGENTS_RULE=1` enables the `run_in_background: true` avoidance reminder for agent hooks.\n\nThe `tool-search` plugin bundles the same MCP bridge described in [GPT Tool Search](#gpt-tool-search), so Claude Code users do not need to add the `tool_search` server manually when they install that plugin.\n\n#### Opencode plugin\n\nThe subagent marker producer is packaged as an opencode plugin located at `plugin/opencode/subagent-marker.js`.\n\n**Installation:**\n\nCopy the plugin file to your opencode plugins directory:\n\n```sh\n# Clone or download this repository, then copy the plugin\ncp plugin/opencode/subagent-marker.js ~/.config/opencode/plugins/\n```\n\nOr manually create the file at `~/.config/opencode/plugins/subagent-marker.js` with the plugin content.\n\n**Features:**\n\n- Tracks sub-sessions created by subagents\n- Automatically prepends a marker system reminder (`__SUBAGENT_MARKER__...`) to subagent chat messages\n- Sets `x-session-id` header for session tracking\n- Enables the gateway to infer `x-initiator: agent` for subagent-originated requests\n\nThe plugin hooks into `session.created`, `session.deleted`, `chat.message`, and `chat.headers` events to provide seamless subagent marker functionality.\n\n## Using the Usage Viewer\n\nAfter starting the server, a URL to the Copilot Usage Dashboard will be displayed in your console. This dashboard is a web interface for monitoring your API usage.\n\n1.  Start the server. For example, using npx:\n    ```sh\n    npx @jeffreycao/copilot-api@latest start\n    ```\n2.  The server will output a URL to the usage viewer. Copy and paste this URL into your browser. It will look something like this:\n    `http://localhost:4141/usage-viewer?endpoint=http://localhost:4141/usage`\n    - If you use the `start.bat` script on Windows, this page will open automatically.\n\nThe dashboard provides a user-friendly interface to view your Copilot usage data:\n\n> Token usage history requires Bun or Node.js >= 22.13.0. On Node.js < 22.13.0, the server runs normally but token usage storage is disabled.\n\n- **API Endpoint URL**: The dashboard is pre-configured to fetch data from your local server endpoint via a URL query parameter. You can manually switch this to any other compatible API endpoint.\n- **x-api-key Authentication**: If API Key authentication is enabled, you can provide the `x-api-key` request header. The key is persisted in the browser's local storage.\n- **Period Selector**: Choose from Day, Week, or Month time ranges. The URL query parameter updates automatically when you switch, making it easy to bookmark and share.\n- **Fetch Data**: Click the \"Refresh\" button to load or refresh the usage data. The dashboard also fetches data automatically on page load.\n- **Copilot Quotas**: View quota usage for services such as Chat and Completions via progress bars. Hover over a card to see used/remaining details.\n- **Token Usage Metric Cards**: See a summary of Total, Input, Output, Cache Read, Cache Write, Requests, and estimated cost for the current period.\n- **Trend Chart (Week / Month)**: An interactive line chart with model and metric filters. Click a data point to inspect the usage breakdown for a specific day.\n- **Model Breakdown Table**: A per-model summary of requests, input/output/cache tokens, and estimated cost for the selected period.\n- **Request Events (Paginated)**: A time-sorted list of request event records with pagination support, showing timestamps, models, request IDs, and token counts.\n- **Detailed Information**: See the full JSON response from the API for a detailed breakdown of all available usage statistics.\n- **URL-based Configuration**: You can also specify the API endpoint and period directly via `endpoint` and `period` query parameters. For example:\n  `http://localhost:4141/usage-viewer?endpoint=http://your-api-server/usage&period=week`\n\n### Usage Viewer Screenshot\n\n<p align=\"center\">\n  <img src=\"./docs/screenshots/usage-viewer.png\" alt=\"Copilot API usage viewer\" width=\"900\" />\n</p>\n\n## Command Structure\n\nCopilot API now uses a subcommand structure with these main commands:\n\n- `start`: Start the gateway server. If a GitHub token is available, the server starts with Copilot enabled. If no GitHub token is available, it starts in provider-only mode when at least one enabled provider exists; otherwise it guides you through provider setup.\n- `auth`: Run provider login or configuration without starting the server. Use it for GitHub Copilot login, Codex OAuth, or third-party provider API key setup.\n- `debug`: Display diagnostic information including version, runtime details, file paths, and authentication status. Useful for troubleshooting and support.\n\n## Command Line Options\n\n### Global Options\n\nThe following options can be used with any subcommand. When passing them before the subcommand, use the `--key=value` form:\n\n| Option            | Description                                            | Default | Alias |\n| ----------------- | ------------------------------------------------------ | ------- | ----- |\n| --api-home        | Path to the API home directory (sets COPILOT_API_HOME) | none    | none  |\n| --oauth-app       | OAuth app identifier (sets COPILOT_API_OAUTH_APP)      | none    | none  |\n| --enterprise-url  | Enterprise URL for GitHub (sets COPILOT_API_ENTERPRISE_URL) | none | none |\n\n### Start Command Options\n\nThe following command line options are available for the `start` command:\n\n| Option         | Description                                                                   | Default    | Alias |\n| -------------- | ----------------------------------------------------------------------------- | ---------- | ----- |\n| --port         | Port to listen on                                                             | 4141       | -p    |\n| --verbose      | Enable verbose logging                                                        | false      | -v    |\n| --github-token | Provide GitHub token directly (must be generated using the `auth` subcommand) | none       | -g    |\n| --claude-code  | Generate a command to launch Claude Code with Copilot API config              | false      | -c    |\n| --show-token   | Show GitHub and Copilot tokens on fetch and refresh                           | false      | none  |\n| --proxy-env    | Initialize proxy from environment variables                                   | false      | none  |\n\n### Auth Command Options\n\n| Option       | Description               | Default | Alias |\n| ------------ | ------------------------- | ------- | ----- |\n| --provider   | Provider to log in with or configure (`copilot`, `codex`, `opencode-go`, `deepseek`, `dashscope`, `openrouter`, or `custom`) | prompt | none |\n| --verbose    | Enable verbose logging    | false   | -v    |\n| --show-token | Show GitHub token on auth | false   | none  |\n\nUse `copilot-api auth login --provider copilot` only when you want to enable the GitHub Copilot provider. Copilot is not required for `codex` or third-party provider-only usage.\n\nUse `copilot-api auth login --provider deepseek`, `--provider dashscope`, `--provider openrouter`, or `--provider opencode-go` to add or update those common third-party providers from the CLI. DeepSeek prompts for masked `apiKey`, provider `type` (default `anthropic`), and `baseUrl` defaulting to `https://api.deepseek.com/anthropic`. DashScope prompts for masked `apiKey`, provider `type` (default `openai-compatible`), and prefilled `baseUrl`. OpenRouter prompts for masked `apiKey` and prefilled `baseUrl` only, and writes `type: \"anthropic\"`. OpenCode Go prompts for masked `apiKey` and prefilled `baseUrl` only, and writes `type: \"openai-compatible\"` (baseUrl `https://opencode.ai/zen/go`). After a provider is configured and enabled, `copilot-api start` can run without any GitHub token.\n\nUse `copilot-api auth login --provider custom` to add or update another third-party provider from the CLI. The command prompts for the provider name, supported type (`anthropic`, `openai-compatible`, or `openai-responses`), `baseUrl`, masked `apiKey`, and `authType`; `authType` may be left as the type default or set to `x-api-key` / `authorization`.\n\n### Debug Command Options\n\n| Option | Description               | Default | Alias |\n| ------ | ------------------------- | ------- | ----- |\n| --json | Output debug info as JSON | false   | none  |\n\n## Configuration (config.json)\n\n- **Location:** `~/.local/share/copilot-api/config.json` (Linux/macOS) or `%USERPROFILE%\\.local\\share\\copilot-api\\config.json` (Windows).\n- **Default shape:**\n  ```json\n  {\n    \"auth\": {\n      \"apiKeys\": [],\n      \"adminApiKey\": \"<auto-generated-on-startup>\"\n    },\n    \"providers\": {},\n    \"modelMappings\": {},\n    \"extraPrompts\": {\n      \"gpt-5-mini\": \"<built-in exploration prompt>\"\n    },\n    \"smallModel\": \"gpt-5-mini\",\n    \"contextManagement\": {\n      \"messages\": true,\n      \"responses\": false\n    },\n    \"modelResponsesApiCompactThresholds\": {\n      \"gpt-5.4\": 217600,\n      \"gpt-5.5\": 217600,\n      \"gpt-5.6-sol\": 231200,\n      \"gpt-5.6-terra\": 231200,\n      \"gpt-5.6-luna\": 231200\n    },\n    \"modelReasoningEfforts\": {\n      \"gpt-5-mini\": \"low\"\n    },\n    \"useMessagesApi\": true,\n    \"useResponsesApiWebSocket\": true,\n    \"useResponsesApiWebSearch\": true,\n    \"messageApiWebSearchModel\": \"gpt-5-mini\"\n  }\n  ```\n- **auth.apiKeys:** API keys used for request authentication on non-admin routes. Supports multiple keys for rotation. Requests can authenticate with either `x-api-key: <key>` or `Authorization: Bearer <key>`. If empty or omitted, authentication for non-admin routes is disabled.\n- **auth.adminApiKey:** Single admin key used only for `/admin/*` routes. If missing, the server generates a random key at startup and writes it back to `config.json`. Requests use the same `x-api-key` or `Authorization: Bearer` headers, but regular `auth.apiKeys` never grant access to `/admin/*`.\n- **modelMappings:** Exact `sourceModel -> targetModel` rewrites shared by top-level `POST /v1/messages`, `POST /v1/messages/count_tokens`, `POST /v1/responses`, and `POST /v1/chat/completions` requests. Omit it or leave it as `{}` to disable rewrites. Both the source and target must be non-empty strings. Targets can be regular model IDs or `provider/model` aliases such as `dashscope/qwen3.6-plus`, and the rewrite happens before provider alias parsing. These mappings are not split per interface. The admin endpoints `GET/POST /admin/config/model-mappings` read and update only this field.\n- **extraPrompts:** Map of `model -> prompt` appended to the first system prompt when translating Anthropic-style requests to Responses API. Use this to inject guardrails or guidance per model. Missing default entries are auto-added without overwriting your custom prompts. For GPT-5.3+ models (e.g. `gpt-5.3-codex`, `gpt-5.4`, `gpt-5.5`), a built-in commentary prompt is used as fallback when not explicitly configured. The built-in prompts enable phase-aware commentary, which lets the model emit a short user-facing progress update before tools or deeper reasoning.\n- **providers:** Global upstream provider map. Each provider key (for example `dashscope`) becomes a route prefix (`/dashscope/v1/messages`). Supports `type: \"anthropic\"`, `type: \"openai-compatible\"`, and `type: \"openai-responses\"`. Top-level clients can also use `model: \"dashscope/model-id\"` with `/v1/messages`, `/v1/messages/count_tokens`, `/v1/responses`, and `/v1/chat/completions`; the gateway strips the `dashscope/` prefix before forwarding upstream. `openai-compatible` providers support both chat and Messages flows: `/v1/chat/completions` is proxied to upstream `/v1/chat/completions`, while `/v1/messages` and `/:provider/v1/messages` are translated to upstream chat completions and translated back to Anthropic Messages responses. `GET /v1/models` aggregates enabled provider models with `provider/model-id` IDs; use `GET /dashscope/v1/models` for a single provider's raw model list.\n  - `enabled` defaults to `true` if omitted.\n  - `baseUrl` should be provider API base URL without the final endpoint. For Anthropic providers, omit `/v1/messages`; for OpenAI-compatible providers, omit `/v1/chat/completions`; for OpenAI Responses providers, omit `/v1/responses`.\n  - `apiKey` is used as the upstream credential value and is required for regular providers.\n  - `authType` (optional): Controls how `apiKey` is sent upstream. Supports `x-api-key` and `authorization` for regular providers. Anthropic providers default to `x-api-key`; OpenAI-compatible and OpenAI Responses providers default to `authorization`. When set to `authorization`, the proxy sends `Authorization: Bearer <apiKey>`. `oauth2` is reserved for the built-in `codex` provider and is written automatically by `auth login --provider codex`.\n  - `pricingCurrency` (optional): Provider-level currency used for token cost calculation, for example `USD` or `CNY`. Quick providers default to `CNY` for DashScope and DeepSeek, and `USD` for Codex/OpenRouter. Costs are grouped by currency and are not exchange-rate converted.\n  - `models` (optional): Per-model configuration map. Each key is a model ID (matching the model name in requests), and the value is:\n    - `temperature` (optional): Default temperature value used when the request does not specify one.\n    - `topP` (optional): Default top_p value used when the request does not specify one.\n    - `topK` (optional): Default top_k value used when the request does not specify one.\n    - `extraBody` (optional): Dynamic fields merged into the upstream request body for that model. Request body fields with the same name take precedence. OpenAI-compatible providers can use this for fields such as `enable_thinking`, `preserve_thinking`, `reasoning_effort`. `thinking_budget` is a special OpenAI-compatible provider override: when configured in `extraBody`, it is forced after Anthropic `thinking.budget_tokens` translation and overrides the request-derived budget. For providers whose name is `dashscope` or whose `baseUrl` contains `aliyuncs.com`, the request-derived `thinking_budget` (from Anthropic `thinking.budget_tokens`) is forwarded upstream; for other OpenAI-compatible providers the request-derived `thinking_budget` is stripped, while an `extraBody` `thinking_budget` is still honored. For DashScope providers, `preserve_thinking` defaults to `true` when not explicitly set in `extraBody` or the request body.\n    - `pricing` (optional): Per-model token prices, in the provider `pricingCurrency`, per 1M tokens. Supported fields are `input`, `output`, `cachedInput` (implicit cache read), `explicitCachedInput` (explicit cache read), and `cacheCreationInput`. Use `tiers` with `maxInputTokens` for input-size tiered pricing.\n    - `contextCache` (optional): Defaults to `true` for providers whose name is `dashscope` or whose `baseUrl` contains `aliyuncs.com`; defaults to `false` for other OpenAI-compatible providers. This enables Alibaba Cloud Model Studio/DashScope explicit context cache by injecting `cache_control: { \"type\": \"ephemeral\" }` on up to 4 content blocks using the Context Cache format. The cache breakpoint strategy matches opencode's main provider flow: the first 2 system messages plus the last 2 non-system messages. Marked string content is converted to text content part arrays for `system` / `user` / `assistant` / `tool` messages; existing array content is marked on the last part. Set this to `false` when the model already supports implicit caching, or when the upstream does not accept this explicit-cache extension field. Set this to `true` for non-DashScope providers that support the same explicit-cache extension. Applied on both `/v1/messages` and `/v1/chat/completions` routes.\n    - `supportPdf` (optional): Controls whether the model supports PDF/document content. Defaults to `false`; unsupported PDFs are converted to a text notice. Set it to `true` to send PDF/document blocks as OpenAI Chat Completions file parts.\n    - `toolContentSupportType` (optional): Tool result content capabilities for that model, as an array of `array`, `image`, and `pdf`. Provider routes default to string-only tool content when omitted. If `supportPdf` is `true` but this list does not include `pdf`, file parts in tool results are moved to user role messages. This provider default does not change the Copilot main flow, which continues to support array + image and not PDF.\n    - `type` (optional): Per-model override of the provider protocol type. Supports `anthropic`, `openai-compatible`, and `openai-responses`. When set, the provider's `/v1/messages` route uses this model's type instead of the provider-level type for request routing, auth header resolution, and upstream endpoint selection. This is useful for providers like OpenCode Go whose upstream supports both OpenAI-compatible and Anthropic Messages APIs for different models. When the type is overridden, the auth header is resolved from the overridden type's default (Anthropic defaults to `x-api-key`; OpenAI-compatible/Responses default to `authorization`).\n\n  Example DashScope model settings:\n  ```json\n  {\n    \"providers\": {\n      \"dashscope\": {\n        \"type\": \"openai-compatible\",\n        \"enabled\": true,\n        \"baseUrl\": \"https://dashscope.aliyuncs.com/compatible-mode\",\n        \"apiKey\": \"sk-your-dashscope-key\",\n        \"pricingCurrency\": \"CNY\",\n        \"models\": {\n          \"qwen3.7-plus\": {\n            \"temperature\": 1,\n            \"topP\": 0.95,\n            \"topK\": 20,\n            \"extraBody\": {\n              \"preserve_thinking\": true\n            }\n          },\n          \"glm-5.1\": {\n            \"temperature\": 0.7,\n            \"topP\": 0.95,\n            \"contextCache\": true,\n            \"pricing\": {\n              \"tiers\": [\n                {\n                  \"maxInputTokens\": 32000,\n                  \"input\": 6,\n                  \"cachedInput\": 1.2,\n                  \"explicitCachedInput\": 0.6,\n                  \"cacheCreationInput\": 7.5,\n                  \"output\": 24\n                },\n                {\n                  \"maxInputTokens\": 200000,\n                  \"input\": 8,\n                  \"cachedInput\": 1.6,\n                  \"explicitCachedInput\": 0.8,\n                  \"cacheCreationInput\": 10,\n                  \"output\": 28\n                }\n              ]\n            },\n            \"extraBody\": {\n              \"preserve_thinking\": true\n            }\n          }\n        }\n      }\n    }\n  }\n  ```\n  Built-in token prices cover Codex GPT models in USD, DashScope `qwen3.7-max`, `qwen3.7-plus`, `glm-5.1`, `glm-5.2` in CNY, DeepSeek `deepseek-v4-flash`, `deepseek-v4-pro`, `deepseek-chat`, `deepseek-reasoner` in CNY, and OpenCode Go models (`glm-5.2`, `deepseek-v4-flash`, `deepseek-v4-pro`, `kimi-k2.7-code`, `mimo-v2.5`, `mimo-v2.5-pro`, `qwen3.7-plus`, `qwen3.7-max`, `minimax-m2.5`, `minimax-m3`) in USD. User `pricing` entries override built-ins. For DashScope, cached tokens are charged as explicit cache reads when the upstream usage includes `cache_creation_input_tokens`; otherwise `cachedInput` is used as the implicit cache read price. For DeepSeek, `prompt_cache_hit_tokens` map to cached input and `prompt_cache_miss_tokens` map to regular input.\n- **smallModel:** Fallback model used for tool-less warmup messages (e.g., Claude Code probe requests); defaults to gpt-5-mini.\n- **contextManagement:** Controls whether the proxy adds Responses API `context_management` compaction instructions. `messages` applies when Anthropic-style `/v1/messages` requests are translated to Responses API, including `openai-responses` provider message routes, and defaults to `true`. `responses` applies to native `/v1/responses` traffic, including `provider/model` aliases and the built-in `codex` provider, and defaults to `false`. Enable `responses` only after checking that your client supports context management compaction. When enabled, the request includes `context_management` in the body and keeps only the latest compaction carrier on follow-up turns. **Note:** Context management is forcibly disabled for GPT-5.6 and above models (e.g. `gpt-5.6-sol`, `gpt-5.6-terra`, `gpt-5.6-luna`) because enabling it breaks prompt cache hits on those models. This override takes precedence over the `contextManagement` and `modelResponsesApiCompactThresholds` settings.\n- **modelResponsesApiCompactThresholds:** Per-model Responses API `compact_threshold` overrides used when the proxy adds `context_management`. These values take precedence over the fallback threshold from `resolveResponsesCompactThreshold` (`max_prompt_tokens * ratio`, or the default fallback). Defaults set `gpt-5.4` and `gpt-5.5` to `217600` (`272000 * 0.8`), and `gpt-5.6-sol`, `gpt-5.6-terra`, `gpt-5.6-luna` to `231200` (`272000 * 0.85`). Models not listed continue to use the normal fallback logic.\n- **modelReasoningEfforts:** Per-model fallback reasoning effort for `/v1/messages` requests. It is used only when the request does not provide `output_config.effort`.\n  - **Priority:** request `output_config.effort` > `modelReasoningEfforts[model]` > built-in default (`xhigh` for GPT-5.3+ models, otherwise `high`).\n  - **Forwarding:** the resolved value remains `output_config.effort` for the Copilot native Messages API and becomes `reasoning.effort` when translated to the Responses API.\n  - **Configuration values:** `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`.\n- **useMessagesApi:** When `true`, Claude-family models that support Copilot's native `/v1/messages` endpoint will use the Messages API; otherwise they fall back to `/chat/completions`. Set to `false` to disable Messages API routing and always use `/chat/completions`. Defaults to `true`.\n- **useResponsesApiWebSocket:** When `true`, Responses API requests use Copilot's websocket transport for models that advertise `ws:/responses`; models that only advertise `/responses` continue to use HTTP. Set to `false` to disable websocket routing and use HTTP `/responses` whenever the selected model supports it. Defaults to `true`.\n- **useResponsesApiWebSearch:** When `true`, the server keeps Responses API tools with `type: \"web_search\"` and forwards them upstream. Set to `false` to strip those tools from `/responses` payloads. Defaults to `true`.\n- **messageApiWebSearchModel:** Global fallback model used when a top-level Copilot `/v1/messages` request contains only the server-side `web_search` tool. Defaults to `gpt-5-mini`. If the value is a `provider/model` alias, the request is routed into that provider's Messages API path with the provider prefix stripped. For Copilot GPT models, web search runs through `/responses`. Mixed `web_search` plus custom tools are not supported and the server-side `web_search` tool is stripped.\n- **claudeTokenMultiplier:** Multiplier applied to the fallback GPT-tokenizer estimate for Claude `/v1/messages/count_tokens` requests. Defaults to `1.15`. Increase it if your client is still compacting too late. This setting is only used when the proxy is estimating Claude tokens locally; if `anthropicApiKey` is configured and Anthropic token counting succeeds, the exact Anthropic count is returned instead.\n- **anthropicApiKey:** Anthropic API key used to forward Claude `/v1/messages/count_tokens` requests to Anthropic's real token counting endpoint, which returns exact counts instead of GPT tokenizer estimates. Can also be set via the `ANTHROPIC_API_KEY` environment variable. If not set, or if the upstream call fails, token counting falls back to local GPT tokenizer estimation controlled by `claudeTokenMultiplier`.\n\nEdit this file to customize prompts or swap in your own fast model. Restart the server (or rerun the command) after changes so the cached config is refreshed.\n\n## API Authentication\n\n- **Protected non-admin routes:** All routes except `/`, `/usage-viewer`, and `/usage-viewer/` require authentication when `auth.apiKeys` is configured and non-empty.\n- **Admin routes:** All `/admin/*` routes require `auth.adminApiKey`. If it is missing, the server generates one at startup and persists it to `config.json` before serving requests.\n- **Allowed auth headers:**\n  - `x-api-key: <your_key>`\n  - `Authorization: Bearer <your_key>`\n- **CORS preflight:** `OPTIONS` requests are always allowed.\n- **When no regular keys are configured:** Non-admin routes continue to allow requests. This does not apply to `/admin/*`, which only accepts `auth.adminApiKey`.\n\nExample request for a regular protected route:\n\n```sh\ncurl http://localhost:4141/v1/models \\\n  -H \"x-api-key: your_api_key\"\n```\n\nExample request for an admin route:\n\n```sh\ncurl http://localhost:4141/admin/config/model-mappings \\\n  -H \"x-api-key: your_admin_api_key\"\n```\n\n## API Endpoints\n\nThe server exposes several OpenAI- and Anthropic-compatible endpoints. Requests can target GitHub Copilot, the built-in `codex` provider, or configured providers depending on the selected model and `provider/model` alias.\n\n### OpenAI Compatible Endpoints\n\nThese endpoints mimic the OpenAI API structure.\n\n| Endpoint                    | Method | Description                                                      |\n| --------------------------- | ------ | ---------------------------------------------------------------- |\n| `POST /v1/responses`        | `POST` | OpenAI Most advanced interface for generating model responses. Supports `provider/model` aliases for `openai-responses` providers. |\n| `POST /v1/chat/completions` | `POST` | Creates a model response for the given chat conversation. Supports `provider/model` aliases for `openai-compatible` providers and can be used without Copilot when the target provider is configured. |\n| `GET /v1/models`            | `GET`  | Lists Copilot models plus enabled provider models using `provider/model-id` IDs. Requests from Codex clients (`User-Agent` beginning with `codex`) are forwarded to the Codex Models upstream. |\n| `POST /v1/embeddings`       | `POST` | Creates an embedding vector representing the input text.         |\n\n### Codex Backend Proxy Endpoints\n\nThese endpoints require an active Codex login. Each endpoint is available both without a version prefix and under `/v1`.\n\n| Endpoint | Method | Description |\n| --- | --- | --- |\n| `POST /alpha/search`<br>`POST /v1/alpha/search` | `POST` | Transparently forwards the JSON body and query parameters to the Codex Alpha Search upstream. |\n| `POST /images/generations`<br>`POST /v1/images/generations` | `POST` | Forwards a JSON image generation request to the Codex Images upstream. When the request omits `Content-Type`, the gateway defaults it to `application/json`. |\n| `POST /images/edits`<br>`POST /v1/images/edits` | `POST` | Forwards an image edit request to the Codex Images upstream. Send this request as `multipart/form-data` and let the HTTP client generate the `boundary`; the gateway preserves the incoming content type and streams the upload body. |\n\nFor every endpoint above, the gateway replaces client authorization and account headers with the active Codex login, preserves query parameters and compatible request headers, and returns the upstream status, headers, and body.\n\n### Anthropic Compatible Endpoints\n\nThese endpoints are designed to be compatible with the Anthropic Messages API. Provider-scoped models, Responses, alpha-search, and images routes accept both unversioned and `/v1` paths; Messages routes remain under `/v1`.\n\n| Endpoint                         | Method | Description                                                  |\n| -------------------------------- | ------ | ------------------------------------------------------------ |\n| `POST /v1/messages`              | `POST` | Creates a model response for a given conversation. Supports `provider/model` aliases for configured providers, including translation through `openai-compatible` providers. |\n| `POST /v1/messages/count_tokens` | `POST` | Calculates the number of tokens for a given set of messages. Supports `provider/model` aliases for configured providers. |\n| `POST /:provider/v1/messages`       | `POST` | Proxies Anthropic Messages requests to the configured Anthropic provider, translates them through an OpenAI-compatible provider, or translates them through an OpenAI Responses provider. |\n| `GET /:provider/models`<br>`GET /:provider/v1/models` | `GET` | Proxies model listing requests to the configured provider. For `codex`, returns the built-in catalog by default; Codex clients (`User-Agent` starting with `codex`) are forwarded to the Codex Models upstream. |\n| `POST /:provider/v1/messages/count_tokens` | `POST` | Calculates tokens locally for provider route requests. |\n| `POST /:provider/responses`<br>`POST /:provider/v1/responses` | `POST` | Proxies OpenAI Responses requests to a configured `openai-responses` provider (including `codex`). |\n| `POST /:provider/alpha/search`<br>`POST /:provider/v1/alpha/search` | `POST` | Proxies alpha-search requests. For `codex`, forwards to the Codex Alpha Search upstream; for other providers, forwards to `{baseUrl}/v1/alpha/search`. |\n| `POST /:provider/images/generations`<br>`POST /:provider/v1/images/generations` | `POST` | Proxies image generation. For `codex`, uses the Codex Images upstream; for other providers, forwards to `{baseUrl}/v1/images/generations` (15-minute timeout). |\n| `POST /:provider/images/edits`<br>`POST /:provider/v1/images/edits` | `POST` | Proxies image edits. For `codex`, uses the Codex Images upstream; for other providers, forwards multipart/streamed bodies to `{baseUrl}/v1/images/edits` (15-minute timeout). |\n\n### Usage Monitoring Endpoints\n\nNew endpoints for monitoring your Copilot usage and quotas.\n\n| Endpoint     | Method | Description                                                  |\n| ------------ | ------ | ------------------------------------------------------------ |\n| `GET /usage` | `GET`  | Get detailed Copilot usage statistics and quota information. |\n| `GET /token` | `GET`  | Get the current Copilot token being used by the API.         |\n\n### Admin / Configuration Endpoints\n\nThese endpoints are reserved for local administrative actions and only accept `auth.adminApiKey`.\n\n| Endpoint                              | Method | Description                                                                 |\n| ------------------------------------- | ------ | --------------------------------------------------------------------------- |\n| `GET /admin/config/model-mappings`    | `GET`  | Returns the current `config.json` path and the active `modelMappings` map.  |\n| `POST /admin/config/model-mappings`   | `POST` | Updates only the `modelMappings` field in `config.json` and returns it back. |\n\n## Example Usage\n\nCommon `npx` commands:\n\n```sh\n# Start the gateway\nnpx @jeffreycao/copilot-api@latest start\n\n# Start on a custom port with verbose logging\nnpx @jeffreycao/copilot-api@latest start --port 8080 --verbose\n\n# Run the auth flow\nnpx @jeffreycao/copilot-api@latest auth login\n\n# Configure a third-party provider, then run without GitHub Copilot\nnpx @jeffreycao/copilot-api@latest auth login --provider dashscope\nnpx @jeffreycao/copilot-api@latest start\n\n# Print debug information as JSON\nnpx @jeffreycao/copilot-api@latest debug --json\n\n# Run the published CLI with Bun instead of Node.js\nbunx --bun @jeffreycao/copilot-api@latest start\n```\n\nOpenAI-compatible provider examples after configuring `dashscope`:\n\n```sh\ncurl http://localhost:4141/v1/chat/completions \\\n  -H \"content-type: application/json\" \\\n  -d '{\"model\":\"dashscope/qwen3.6-plus\",\"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]}'\n\ncurl http://localhost:4141/dashscope/v1/messages \\\n  -H \"content-type: application/json\" \\\n  -d '{\"model\":\"qwen3.6-plus\",\"max_tokens\":1024,\"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]}'\n```\n\n## Usage Tips\n\n### CLAUDE.md or AGENTS.md Recommended Content\n\nTo add these reminders manually, include the following in `CLAUDE.md` for Claude Code, or `AGENTS.md` for opencode/codex:\n\n```\n- Prohibited from directly asking questions to users, MUST use question tool.\n- Once you can confirm that the task is complete, MUST use question tool to make user confirm. The user may respond with feedback if they are not satisfied with the result, which you can use to make improvements and try again, after try again, MUST use question tool to make user confirm again.\n```\n"}, "4bbb57890d6fa1f5490258f417700298605e14fe": {"t": 1785765553.5910447, "n": 49215, "h": "56efa00286618909", "c": "# Copilot API Proxy\n\nEnglish | [简体中文](./README.zh-CN.md)\n\n## Important Notes\n\n> [!IMPORTANT]\n> **Before using, please be aware of the following:**\n>\n> 1. **Claude Code configuration:** When using with Claude Code, please configure the model ID as `claude-opus-4-8`. Example claude `settings.json` see [Manual Configuration with `settings.json`](#manual-configuration-with-settingsjson). \n>\n> 2. **Built-in `copilot`, `codex` and third-party providers:** Run `npx @jeffreycao/copilot-api@latest auth` and choose `copilot`, `codex`, `deepseek`, `custom`, or other providers.\n>\n> 3. **Note:** See [GitHub Copilot Security Notice](./NOTICE.md#github-copilot-security-notice) for the warning removed from the README header.\n\n---\n\n## Project Overview\n\nA small AI gateway that can use GitHub Copilot, the built-in `codex` provider, or configured third-party providers such as DashScope. GitHub Copilot is optional: if no GitHub token is available, the server can still start in provider-only mode as long as at least one enabled provider is configured.\n\nThe gateway exposes OpenAI- and Anthropic-compatible APIs from one local endpoint, so tools like [Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview), OpenCode, Codex, and OpenAI-compatible clients can share the same local server.\n\nOn the GitHub Copilot path, the gateway prefers Copilot's native Anthropic-style Messages API when available, preserving more Claude-native behavior for tool-heavy workflows.\n\n## Features\n\n- **OpenAI and Anthropic compatibility**: Serve `/v1/responses`, `/v1/chat/completions`, `/v1/models`, `/v1/embeddings`, and `/v1/messages` from one local gateway.\n- **Copilot is optional**: Use GitHub Copilot when credentials are present, or run the server with only configured providers.\n- **One gateway for Copilot, `codex`, and external providers**: Route GitHub Copilot, the built-in `codex` provider, and configured third-party providers behind the same endpoint.\n- **Standalone third-party providers**: Configure providers such as DashScope, DeepSeek, OpenRouter, or a custom provider and start the gateway without a GitHub Copilot login.\n- **OpenAI-compatible providers on chat and Messages APIs**: `openai-compatible` providers can serve top-level `/v1/chat/completions` through `model: \"provider/model\"` and Anthropic-style `/v1/messages` through request/response translation.\n- **Agent-friendly Claude handling on Copilot**: Prefer native `/v1/messages` when available, preserve Claude-style tool flows, support Anthropic beta features, Claude WebSearch through Responses-capable models, and keep subagent/session markers intact.\n- **Claude Code and OpenCode integration**: Works with Claude Code and OpenCode, including direct Anthropic-compatible usage through `@ai-sdk/anthropic`.\n- **Flexible auth and deployment options**: Supports interactive login or direct tokens, individual/business/enterprise plans, GitHub Enterprise, opencode OAuth, and custom data directories.\n- **Multi-provider routing**: Expose provider-specific `/:provider/...` routes or use `model: \"provider/model\"` on the top-level API.\n\n## Prerequisites\n\n- Bun (>= 1.2.x)\n- Node.js if you plan to run the published CLI with `npx`\n- GitHub account with Copilot subscription only if you want to use the GitHub Copilot provider\n- An API key or OAuth login for at least one configured provider if you want to run without GitHub Copilot\n\n## Installation\n\nTo install dependencies, run:\n\n```sh\nbun install\n```\n\nTo start the server directly from source:\n\n```sh\nbun run start start\n```\n\n## Running from Source\n\nThe project can be run from source in several ways:\n\n### Development Mode\n\n```sh\nbun run dev start\n```\n\n### Production Mode\n\n```sh\nbun run start start\n```\n\n## Using with npx\n\nYou can run the project directly using npx:\n\n> [!IMPORTANT]\n> Token usage storage uses Node's built-in `node:sqlite` module when running with `npx`. It is enabled on Node.js >= 22.13.0. On Node.js < 22.13.0, the CLI still starts, but token usage storage is disabled.\n>\n> If you want token usage storage without upgrading Node.js, run the published CLI with Bun instead: `bunx --bun @jeffreycao/copilot-api@latest start`.\n\n```sh\nnpx @jeffreycao/copilot-api@latest start\n```\n\nWith options:\n\n```sh\nnpx @jeffreycao/copilot-api@latest start --port 8080\n```\n\nFor authentication or provider configuration only:\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth\n```\n\nTo run without GitHub Copilot, configure at least one provider first, then start the server normally:\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth login --provider dashscope\nnpx @jeffreycao/copilot-api@latest start\n```\n\n## Using with Docker\n\nBuild the image:\n\n```sh\ndocker build -t copilot-api .\n```\n\nRun the container with a bind mount so auth data survives restarts:\n\n```sh\nmkdir -p ./copilot-data\ndocker run -p 4141:4141 -v $(pwd)/copilot-data:/root/.local/share/copilot-api copilot-api\n```\n\nThis stores GitHub auth data, provider config, and other gateway state in `./copilot-data` on the host, mapped to `/root/.local/share/copilot-api` in the container.\n\nOr pass a GitHub token directly:\n\n```sh\ndocker run -p 4141:4141 -e GH_TOKEN=your_github_token_here copilot-api\n```\n\n## Electron Desktop App\n\nIf you prefer a GUI, this repository also includes an Electron desktop app in `desktop/`. It supports GitHub Copilot sign-in, OpenAI Codex OAuth, and API-key configuration for DeepSeek, DashScope, OpenRouter, or a custom provider. After authorization or provider configuration, it can start and stop the local proxy with one click and shows the local endpoint, auth header, available models, usage, and logs in the app.\n\nThe settings screen also exposes `OAuth App`, `API Home`, `Enterprise URL`, verbose logging, and minimize-to-tray. Desktop packages are published in GitHub Releases:\n\nhttps://github.com/caozhiyuan/copilot-api/releases\n\nDownload the installer for your platform, authorize or configure a provider inside the app, choose a port, start the server, then point your client at the local endpoint shown in the app. Packaged desktop builds use the bundled Electron runtime, so normal desktop usage does not require installing Node.js separately. Token usage history is enabled when that bundled runtime supports SQLite.\n\nThe desktop app's Advanced Config page reads and writes the shared model mappings through `GET/POST /admin/config/model-mappings`. The same mappings apply across `POST /v1/messages`, `POST /v1/messages/count_tokens`, `POST /v1/responses`, and `POST /v1/chat/completions` instead of being split per interface. It uses `auth.adminApiKey` instead of the regular `auth.apiKeys`, and the app reads that key directly from `config.json` after the server has generated it on startup.\n\n### Desktop App Screenshots\n\nMain dashboard, token usage breakdown in the bundled Electron app:\n\n<p align=\"center\">\n  <img src=\"./docs/screenshots/desktop-dashboard.png\" alt=\"Copilot API desktop app dashboard\" width=\"49%\" />\n  <img src=\"./docs/screenshots/desktop-token-usage.png\" alt=\"Copilot API desktop app token usage view\" width=\"49%\" />\n</p>\n\n## Using with Claude Code\n\nThis AI gateway can be used to power [Claude Code](https://docs.anthropic.com/en/claude-code), an experimental conversational AI assistant for developers from Anthropic.\n\nThere are two ways to configure Claude Code to use this AI gateway:\n\n### Interactive Setup with `--claude-code` flag\n\nTo get started, run the `start` command with the `--claude-code` flag:\n\n```sh\nnpx @jeffreycao/copilot-api@latest start --claude-code\n```\n\nYou will be prompted to select a primary model and a \"small, fast\" model for background tasks. After selecting the models, a command will be copied to your clipboard. This command sets the necessary environment variables for Claude Code to use the gateway.\n\nPaste and run this command in a new terminal to launch Claude Code.\n\n### Manual Configuration with `settings.json`\n\nAlternatively, you can configure Claude Code by creating a `.claude/settings.json` file in your project's root directory. This file should contain the environment variables needed by Claude Code. This way you don't need to run the interactive setup every time.\n\nHere is an example `.claude/settings.json` file:\n\n```json\n{\n  \"env\": {\n    \"ANTHROPIC_BASE_URL\": \"http://localhost:4141\",\n    \"ANTHROPIC_AUTH_TOKEN\": \"dummy\",\n    \"ANTHROPIC_MODEL\": \"deepseek/deepseek-v4-pro\",\n    \"ANTHROPIC_DEFAULT_SONNET_MODEL\": \"deepseek/deepseek-v4-pro\",\n    \"ANTHROPIC_DEFAULT_HAIKU_MODEL\": \"deepseek/deepseek-v4-flash\",\n    \"DISABLE_NON_ESSENTIAL_MODEL_CALLS\": \"1\",\n    \"CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC\": \"1\",\n    \"CLAUDE_CODE_ATTRIBUTION_HEADER\": \"0\",\n    \"CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION\": \"false\",\n    \"CLAUDE_CODE_DISABLE_TERMINAL_TITLE\": \"true\",\n    \"CLAUDE_CODE_ENABLE_AWAY_SUMMARY\": \"0\"\n  },\n  \"permissions\": {\n    \"deny\": [\n      \"mcp__ide__executeCode\"\n    ]\n  }\n}\n```\n\n- Replace `ANTHROPIC_MODEL`, `ANTHROPIC_DEFAULT_OPUS_MODEL`, `ANTHROPIC_DEFAULT_SONNET_MODEL`, and `ANTHROPIC_DEFAULT_HAIKU_MODEL` according to your needs. After configuration, please install the claude code plugin [Plugin Integrations](#plugin-integrations).  \n- Setting CLAUDE_CODE_ATTRIBUTION_HEADER to 0 can prevent Claude code from adding billing and version information in system prompts, thereby avoiding prompt cache invalidation.\n- Turning off CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION and CLAUDE_CODE_ENABLE_AWAY_SUMMARY can prevent quota from being consumed unnecessarily.\n- Claude Code WebSearch is supported for pure search requests. For Copilot, keep the global `messageApiWebSearchModel` set to a Responses-capable GPT model or a `provider/model` alias. For provider routes, use a native Anthropic provider or an `openai-responses` provider. Add `WebSearch` to `permissions.deny` only if you want to forbid this traffic.\n- If using a non-Claude model, do not enable ENABLE_TOOL_SEARCH. If using the Claude model, can enable ENABLE_TOOL_SEARCH. The current Claude Code uses the client tool search mode. In this mode, loading defer tools requires an additional request each time.\n- `CLAUDE_CODE_AUTO_COMPACT_WINDOW`: Set the context capacity in tokens used for auto-compaction calculations. Defaults to the model's context window: 200K for standard models or 1M for extended context models. Use a lower value like `500000` on a 1M model (e.g., `claude-opus-4-6[1m]`) to treat the window as 500K for compaction purposes. The value is capped at the model's actual context window. `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` is applied as a percentage of this value. Setting this variable decouples the compaction threshold from the status line's `used_percentage`, which always uses the model's full context window.\n\nYou can find more options here: [Claude Code settings](https://docs.anthropic.com/en/docs/claude-code/settings#environment-variables)\n\nYou can also read more about IDE integration here: [Add Claude Code to your IDE](https://docs.anthropic.com/en/docs/claude-code/ide-integrations)\n\n## Using with OpenCode\n\nOpenCode already has a direct GitHub Copilot provider. Use this section when you want OpenCode to point at this AI gateway through `@ai-sdk/anthropic` and reuse the agent behaviors described earlier in this README.\n\n### Minimal setup\n\nStart the AI gateway with the OpenCode OAuth app:\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth --oauth-app=opencode\nnpx @jeffreycao/copilot-api@latest start\n```\n\nThen point OpenCode at the gateway with `@ai-sdk/anthropic`.\n\nExample `~/.config/opencode/opencode.json`:\n\n```json\n{\n  \"$schema\": \"https://opencode.ai/config.json\",\n  \"provider\": {\n    \"local\": {\n      \"npm\": \"@ai-sdk/anthropic\",\n      \"name\": \"My Local\",\n      \"options\": {\n        \"baseURL\": \"http://localhost:4141/v1\",\n        \"apiKey\": \"dummy\"\n      },\n      \"models\": {\n        \"gpt-5.4\": {\n          \"name\": \"gpt-5.4\",\n          \"modalities\": {\n            \"input\": [\"text\", \"image\"],\n            \"output\": [\"text\"]\n          },\n          \"limit\": {\n            \"context\": 400000,\n            \"input\": 272000,\n            \"output\": 128000\n          }\n        },\n        \"claude-sonnet-4.6\": {\n          \"id\": \"claude-sonnet-4.6\",\n          \"name\": \"claude-sonnet-4.6\",\n          \"modalities\": {\n            \"input\": [\"text\", \"image\"],\n            \"output\": [\"text\"]\n          },          \n          \"limit\": {\n            \"context\": 200000,\n            \"output\": 32000\n          },\n          \"options\": {\n            \"thinking\": {\n              \"type\": \"adaptive\"\n            },\n            \"effort\": \"max\"\n          }\n        }\n      }\n    }\n  }\n}\n```\n\nWhy these fields matter:\n\n- `npm: \"@ai-sdk/anthropic\"` is the important part. OpenCode will speak Anthropic Messages semantics to this AI gateway instead of flattening everything into OpenAI Chat Completions.\n- `options.baseURL` should be `http://localhost:4141/v1`; the Anthropic SDK will append `/messages`, `/models`, and `/messages/count_tokens` automatically.\n- If you enable `auth.apiKeys` in this AI gateway, replace `dummy` with a real key. Otherwise any placeholder value is fine.\n\n## Using with Codex\n\nThis AI gateway can also power Codex.\n\n### Codex `config.toml` Reference\n\nAdd the following `[model_providers.copilot_api]` section to your Codex `~/.codex/config.toml`:\n\n```toml\nmodel_provider = \"copilot_api\"\nmodel_reasoning_summary = \"auto\"\nmodel_context_window = 272000\nmodel_auto_compact_token_limit = 244800\n\n[model_providers.copilot_api]\nname = \"OpenAI\"\nbase_url = \"http://localhost:4141\"\nenv_key = \"GITHUB_COPILOT_API_KEY\"\nrequires_openai_auth = true\nsupports_websockets = false\nwire_api = \"responses\"\nrequest_max_retries = 3\nstream_max_retries = 1\nstream_idle_timeout_ms = 300000\n\n[features]\nremote_compaction_v2 = true\n\n[analytics]\nenabled = false\n```\n\n> [!NOTE]\n> This configuration is specific to Codex and the GitHub Copilot provider. `name` must be set to `\"OpenAI\"`. It can help mitigate Codex local compact cache miss issues. \n\n## GPT Tool Search\n\nFor GPT Responses models such as `gpt-5.4+`, this AI gateway can expose Responses `tool_search` through a small MCP bridge. The same bridge can be used by Claude Code and opencode, as long as the client loads MCP servers and sends Anthropic Messages traffic through this gateway.\n\nDo not set Claude Code's native `ENABLE_TOOL_SEARCH` for GPT models. That flag enables Claude Code's own client-side tool search mode, and it may stop forwarding deferred tool definitions. This gateway needs the full tool definitions so it can keep the small always-loaded tool set eager and translate every other tool into Responses deferred namespaces.\n\nIf you install `tool-search@copilot-api-marketplace`, Claude Code receives this MCP bridge automatically and you can skip the manual Claude Code MCP setup below.\n\nAdd the tool search bridge to the MCP config used by Claude Code:\n\n```json\n{\n  \"mcpServers\": {\n    \"tool_search\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@jeffreycao/copilot-api@latest\", \"mcp\"]\n    }\n  }\n}\n```\n\nAdd the tool search bridge to the MCP config used by opencode:\n\n```json\n{\n  \"mcp\": {\n    \"tool_search\": {\n      \"type\": \"local\",\n      \"command\": [\"npx\", \"-y\", \"@jeffreycao/copilot-api@latest\", \"mcp\"]\n    }\n  }\n}\n```\n\nFor local development, use `bun` as the command and `[\"run\", \"./src/main.ts\", \"mcp\"]` as the args.\n\nInternally, the gateway now configures OpenAI Responses `tool_search` in client-executed mode. Deferred tools are still exposed as searchable namespaces, but the model is explicitly asked to return the exact deferred tool names it wants to load next.\n\nThe bridge uses direct tool selection, not query search. Its tool input is `names`, a comma-separated list of exact deferred tool names, for example `TaskList,TaskGet,mcp__fetch__fetch`.\n\n## Plugin Integrations\n\nPlugin integrations are available for Claude Code and opencode.\n\n#### Claude Code plugin integration (marketplace-based)\n\nThe Claude Code integration is packaged as two plugins:\n\n- `agent-inject` injects `__SUBAGENT_MARKER__...` on `SubagentStart`, so the gateway can infer `x-initiator: agent`.\n- `tool-search` registers the `tool_search` MCP bridge used for GPT Responses deferred tool loading.\n\n- Marketplace catalog in this repository: `.claude-plugin/marketplace.json`\n- Plugin sources in this repository: `plugin/claude/agent-inject`, `plugin/claude/tool-search`\n\nAdd the marketplace remotely:\n\n```sh\n/plugin marketplace add https://github.com/caozhiyuan/copilot-api.git\n```\n\nInstall the plugins from the marketplace:\n\n```sh\n/plugin install agent-inject@copilot-api-marketplace\n/plugin install tool-search@copilot-api-marketplace\n```\n\nAfter installation, `agent-inject` injects `__SUBAGENT_MARKER__...` on `SubagentStart`, and the gateway uses it to infer `x-initiator: agent`.\n\nThe `agent-inject` plugin also registers a `UserPromptSubmit` hook that returns `{\"continue\": true}`, and it can inject `SessionStart` reminder rules through environment variables:\n\n- `CLAUDE_PLUGIN_ENABLE_QUESTION_RULES=1` enables the two reminders about using the `question` tool automatically for Claude Code. Alternatively, you can add the same reminders manually in `CLAUDE.md`; see [CLAUDE.md or AGENTS.md Recommended Content](#claudemd-or-agentsmd-recommended-content).\n- `CLAUDE_PLUGIN_ENABLE_NO_BACKGROUND_AGENTS_RULE=1` enables the `run_in_background: true` avoidance reminder for agent hooks.\n\nThe `tool-search` plugin bundles the same MCP bridge described in [GPT Tool Search](#gpt-tool-search), so Claude Code users do not need to add the `tool_search` server manually when they install that plugin.\n\n#### Opencode plugin\n\nThe subagent marker producer is packaged as an opencode plugin located at `plugin/opencode/subagent-marker.js`.\n\n**Installation:**\n\nCopy the plugin file to your opencode plugins directory:\n\n```sh\n# Clone or download this repository, then copy the plugin\ncp plugin/opencode/subagent-marker.js ~/.config/opencode/plugins/\n```\n\nOr manually create the file at `~/.config/opencode/plugins/subagent-marker.js` with the plugin content.\n\n**Features:**\n\n- Tracks sub-sessions created by subagents\n- Automatically prepends a marker system reminder (`__SUBAGENT_MARKER__...`) to subagent chat messages\n- Sets `x-session-id` header for session tracking\n- Enables the gateway to infer `x-initiator: agent` for subagent-originated requests\n\nThe plugin hooks into `session.created`, `session.deleted`, `chat.message`, and `chat.headers` events to provide seamless subagent marker functionality.\n\n## Using the Usage Viewer\n\nAfter starting the server, a URL to the Copilot Usage Dashboard will be displayed in your console. This dashboard is a web interface for monitoring your API usage.\n\n1.  Start the server. For example, using npx:\n    ```sh\n    npx @jeffreycao/copilot-api@latest start\n    ```\n2.  The server will output a URL to the usage viewer. Copy and paste this URL into your browser. It will look something like this:\n    `http://localhost:4141/usage-viewer?endpoint=http://localhost:4141/usage`\n    - If you use the `start.bat` script on Windows, this page will open automatically.\n\nThe dashboard provides a user-friendly interface to view your Copilot usage data:\n\n> Token usage history requires Bun or Node.js >= 22.13.0. On Node.js < 22.13.0, the server runs normally but token usage storage is disabled.\n\n- **API Endpoint URL**: The dashboard is pre-configured to fetch data from your local server endpoint via a URL query parameter. You can manually switch this to any other compatible API endpoint.\n- **x-api-key Authentication**: If API Key authentication is enabled, you can provide the `x-api-key` request header. The key is persisted in the browser's local storage.\n- **Period Selector**: Choose from Day, Week, or Month time ranges. The URL query parameter updates automatically when you switch, making it easy to bookmark and share.\n- **Fetch Data**: Click the \"Refresh\" button to load or refresh the usage data. The dashboard also fetches data automatically on page load.\n- **Copilot Quotas**: View quota usage for services such as Chat and Completions via progress bars. Hover over a card to see used/remaining details.\n- **Token Usage Metric Cards**: See a summary of Total, Input, Output, Cache Read, Cache Write, Requests, and estimated cost for the current period.\n- **Trend Chart (Week / Month)**: An interactive line chart with model and metric filters. Click a data point to inspect the usage breakdown for a specific day.\n- **Model Breakdown Table**: A per-model summary of requests, input/output/cache tokens, and estimated cost for the selected period.\n- **Request Events (Paginated)**: A time-sorted list of request event records with pagination support, showing timestamps, models, request IDs, and token counts.\n- **Detailed Information**: See the full JSON response from the API for a detailed breakdown of all available usage statistics.\n- **URL-based Configuration**: You can also specify the API endpoint and period directly via `endpoint` and `period` query parameters. For example:\n  `http://localhost:4141/usage-viewer?endpoint=http://your-api-server/usage&period=week`\n\n### Usage Viewer Screenshot\n\n<p align=\"center\">\n  <img src=\"./docs/screenshots/usage-viewer.png\" alt=\"Copilot API usage viewer\" width=\"900\" />\n</p>\n\n## Command Structure\n\nCopilot API now uses a subcommand structure with these main commands:\n\n- `start`: Start the gateway server. If a GitHub token is available, the server starts with Copilot enabled. If no GitHub token is available, it starts in provider-only mode when at least one enabled provider exists; otherwise it guides you through provider setup.\n- `auth`: Run provider login or configuration without starting the server. Use it for GitHub Copilot login, Codex OAuth, or third-party provider API key setup.\n- `debug`: Display diagnostic information including version, runtime details, file paths, and authentication status. Useful for troubleshooting and support.\n\n## Command Line Options\n\n### Global Options\n\nThe following options can be used with any subcommand. When passing them before the subcommand, use the `--key=value` form:\n\n| Option            | Description                                            | Default | Alias |\n| ----------------- | ------------------------------------------------------ | ------- | ----- |\n| --api-home        | Path to the API home directory (sets COPILOT_API_HOME) | none    | none  |\n| --oauth-app       | OAuth app identifier (sets COPILOT_API_OAUTH_APP)      | none    | none  |\n| --enterprise-url  | Enterprise URL for GitHub (sets COPILOT_API_ENTERPRISE_URL) | none | none |\n\n### Start Command Options\n\nThe following command line options are available for the `start` command:\n\n| Option         | Description                                                                   | Default    | Alias |\n| -------------- | ----------------------------------------------------------------------------- | ---------- | ----- |\n| --port         | Port to listen on                                                             | 4141       | -p    |\n| --verbose      | Enable verbose logging                                                        | false      | -v    |\n| --github-token | Provide GitHub token directly (must be generated using the `auth` subcommand) | none       | -g    |\n| --claude-code  | Generate a command to launch Claude Code with Copilot API config              | false      | -c    |\n| --show-token   | Show GitHub and Copilot tokens on fetch and refresh                           | false      | none  |\n| --proxy-env    | Initialize proxy from environment variables                                   | false      | none  |\n\n### Auth Command Options\n\n| Option       | Description               | Default | Alias |\n| ------------ | ------------------------- | ------- | ----- |\n| --provider   | Provider to log in with or configure (`copilot`, `codex`, `opencode-go`, `deepseek`, `dashscope`, `openrouter`, or `custom`) | prompt | none |\n| --verbose    | Enable verbose logging    | false   | -v    |\n| --show-token | Show GitHub token on auth | false   | none  |\n\nUse `copilot-api auth login --provider copilot` only when you want to enable the GitHub Copilot provider. Copilot is not required for `codex` or third-party provider-only usage.\n\nUse `copilot-api auth login --provider deepseek`, `--provider dashscope`, `--provider openrouter`, or `--provider opencode-go` to add or update those common third-party providers from the CLI. DeepSeek prompts for masked `apiKey`, provider `type` (default `anthropic`), and `baseUrl` defaulting to `https://api.deepseek.com/anthropic`. DashScope prompts for masked `apiKey`, provider `type` (default `openai-compatible`), and prefilled `baseUrl`. OpenRouter prompts for masked `apiKey` and prefilled `baseUrl` only, and writes `type: \"anthropic\"`. OpenCode Go prompts for masked `apiKey` and prefilled `baseUrl` only, and writes `type: \"openai-compatible\"` (baseUrl `https://opencode.ai/zen/go`). After a provider is configured and enabled, `copilot-api start` can run without any GitHub token.\n\nUse `copilot-api auth login --provider custom` to add or update another third-party provider from the CLI. The command prompts for the provider name, supported type (`anthropic`, `openai-compatible`, or `openai-responses`), `baseUrl`, masked `apiKey`, and `authType`; `authType` may be left as the type default or set to `x-api-key` / `authorization`.\n\n### Debug Command Options\n\n| Option | Description               | Default | Alias |\n| ------ | ------------------------- | ------- | ----- |\n| --json | Output debug info as JSON | false   | none  |\n\n## Configuration (config.json)\n\n- **Location:** `~/.local/share/copilot-api/config.json` (Linux/macOS) or `%USERPROFILE%\\.local\\share\\copilot-api\\config.json` (Windows).\n- **Default shape:**\n  ```json\n  {\n    \"auth\": {\n      \"apiKeys\": [],\n      \"adminApiKey\": \"<auto-generated-on-startup>\"\n    },\n    \"providers\": {},\n    \"modelMappings\": {},\n    \"extraPrompts\": {\n      \"gpt-5-mini\": \"<built-in exploration prompt>\"\n    },\n    \"smallModel\": \"gpt-5-mini\",\n    \"contextManagement\": {\n      \"messages\": true,\n      \"responses\": false\n    },\n    \"modelResponsesApiCompactThresholds\": {\n      \"gpt-5.4\": 217600,\n      \"gpt-5.5\": 217600,\n      \"gpt-5.6-sol\": 231200,\n      \"gpt-5.6-terra\": 231200,\n      \"gpt-5.6-luna\": 231200\n    },\n    \"modelReasoningEfforts\": {\n      \"gpt-5-mini\": \"low\"\n    },\n    \"useMessagesApi\": true,\n    \"useResponsesApiWebSocket\": true,\n    \"useResponsesApiWebSearch\": true,\n    \"messageApiWebSearchModel\": \"gpt-5-mini\"\n  }\n  ```\n- **auth.apiKeys:** API keys used for request authentication on non-admin routes. Supports multiple keys for rotation. Requests can authenticate with either `x-api-key: <key>` or `Authorization: Bearer <key>`. If empty or omitted, authentication for non-admin routes is disabled.\n- **auth.adminApiKey:** Single admin key used only for `/admin/*` routes. If missing, the server generates a random key at startup and writes it back to `config.json`. Requests use the same `x-api-key` or `Authorization: Bearer` headers, but regular `auth.apiKeys` never grant access to `/admin/*`.\n- **modelMappings:** Exact `sourceModel -> targetModel` rewrites shared by top-level `POST /v1/messages`, `POST /v1/messages/count_tokens`, `POST /v1/responses`, and `POST /v1/chat/completions` requests. Omit it or leave it as `{}` to disable rewrites. Both the source and target must be non-empty strings. Targets can be regular model IDs or `provider/model` aliases such as `dashscope/qwen3.6-plus`, and the rewrite happens before provider alias parsing. These mappings are not split per interface. The admin endpoints `GET/POST /admin/config/model-mappings` read and update only this field.\n- **extraPrompts:** Map of `model -> prompt` appended to the first system prompt when translating Anthropic-style requests to Responses API. Use this to inject guardrails or guidance per model. Missing default entries are auto-added without overwriting your custom prompts. For GPT-5.3+ models (e.g. `gpt-5.3-codex`, `gpt-5.4`, `gpt-5.5`), a built-in commentary prompt is used as fallback when not explicitly configured. The built-in prompts enable phase-aware commentary, which lets the model emit a short user-facing progress update before tools or deeper reasoning.\n- **providers:** Global upstream provider map. Each provider key (for example `dashscope`) becomes a route prefix (`/dashscope/v1/messages`). Supports `type: \"anthropic\"`, `type: \"openai-compatible\"`, and `type: \"openai-responses\"`. Top-level clients can also use `model: \"dashscope/model-id\"` with `/v1/messages`, `/v1/messages/count_tokens`, `/v1/responses`, and `/v1/chat/completions`; the gateway strips the `dashscope/` prefix before forwarding upstream. `openai-compatible` providers support both chat and Messages flows: `/v1/chat/completions` is proxied to upstream `/v1/chat/completions`, while `/v1/messages` and `/:provider/v1/messages` are translated to upstream chat completions and translated back to Anthropic Messages responses. `GET /v1/models` aggregates enabled provider models with `provider/model-id` IDs; use `GET /dashscope/v1/models` for a single provider's raw model list.\n  - `enabled` defaults to `true` if omitted.\n  - `baseUrl` should be provider API base URL without the final endpoint. For Anthropic providers, omit `/v1/messages`; for OpenAI-compatible providers, omit `/v1/chat/completions`; for OpenAI Responses providers, omit `/v1/responses`.\n  - `apiKey` is used as the upstream credential value and is required for regular providers.\n  - `authType` (optional): Controls how `apiKey` is sent upstream. Supports `x-api-key` and `authorization` for regular providers. Anthropic providers default to `x-api-key`; OpenAI-compatible and OpenAI Responses providers default to `authorization`. When set to `authorization`, the proxy sends `Authorization: Bearer <apiKey>`. `oauth2` is reserved for the built-in `codex` provider and is written automatically by `auth login --provider codex`.\n  - `pricingCurrency` (optional): Provider-level currency used for token cost calculation, for example `USD` or `CNY`. Quick providers default to `CNY` for DashScope and DeepSeek, and `USD` for Codex/OpenRouter. Costs are grouped by currency and are not exchange-rate converted.\n  - `models` (optional): Per-model configuration map. Each key is a model ID (matching the model name in requests), and the value is:\n    - `temperature` (optional): Default temperature value used when the request does not specify one.\n    - `topP` (optional): Default top_p value used when the request does not specify one.\n    - `topK` (optional): Default top_k value used when the request does not specify one.\n    - `extraBody` (optional): Dynamic fields merged into the upstream request body for that model. Request body fields with the same name take precedence. OpenAI-compatible providers can use this for fields such as `enable_thinking`, `preserve_thinking`, `reasoning_effort`. `thinking_budget` is a special OpenAI-compatible provider override: when configured in `extraBody`, it is forced after Anthropic `thinking.budget_tokens` translation and overrides the request-derived budget. For providers whose name is `dashscope` or whose `baseUrl` contains `aliyuncs.com`, the request-derived `thinking_budget` (from Anthropic `thinking.budget_tokens`) is forwarded upstream; for other OpenAI-compatible providers the request-derived `thinking_budget` is stripped, while an `extraBody` `thinking_budget` is still honored. For DashScope providers, `preserve_thinking` defaults to `true` when not explicitly set in `extraBody` or the request body.\n    - `pricing` (optional): Per-model token prices, in the provider `pricingCurrency`, per 1M tokens. Supported fields are `input`, `output`, `cachedInput` (implicit cache read), `explicitCachedInput` (explicit cache read), and `cacheCreationInput`. Use `tiers` with `maxInputTokens` for input-size tiered pricing.\n    - `contextCache` (optional): Defaults to `true` for providers whose name is `dashscope` or whose `baseUrl` contains `aliyuncs.com`; defaults to `false` for other OpenAI-compatible providers. This enables Alibaba Cloud Model Studio/DashScope explicit context cache by injecting `cache_control: { \"type\": \"ephemeral\" }` on up to 4 content blocks using the Context Cache format. The cache breakpoint strategy matches opencode's main provider flow: the first 2 system messages plus the last 2 non-system messages. Marked string content is converted to text content part arrays for `system` / `user` / `assistant` / `tool` messages; existing array content is marked on the last part. Set this to `false` when the model already supports implicit caching, or when the upstream does not accept this explicit-cache extension field. Set this to `true` for non-DashScope providers that support the same explicit-cache extension. Applied on both `/v1/messages` and `/v1/chat/completions` routes.\n    - `supportPdf` (optional): Controls whether the model supports PDF/document content. Defaults to `false`; unsupported PDFs are converted to a text notice. Set it to `true` to send PDF/document blocks as OpenAI Chat Completions file parts.\n    - `toolContentSupportType` (optional): Tool result content capabilities for that model, as an array of `array`, `image`, and `pdf`. Provider routes default to string-only tool content when omitted. If `supportPdf` is `true` but this list does not include `pdf`, file parts in tool results are moved to user role messages. This provider default does not change the Copilot main flow, which continues to support array + image and not PDF.\n    - `type` (optional): Per-model override of the provider protocol type. Supports `anthropic`, `openai-compatible`, and `openai-responses`. When set, the provider's `/v1/messages` route uses this model's type instead of the provider-level type for request routing, auth header resolution, and upstream endpoint selection. This is useful for providers like OpenCode Go whose upstream supports both OpenAI-compatible and Anthropic Messages APIs for different models. When the type is overridden, the auth header is resolved from the overridden type's default (Anthropic defaults to `x-api-key`; OpenAI-compatible/Responses default to `authorization`).\n\n  Example DashScope model settings:\n  ```json\n  {\n    \"providers\": {\n      \"dashscope\": {\n        \"type\": \"openai-compatible\",\n        \"enabled\": true,\n        \"baseUrl\": \"https://dashscope.aliyuncs.com/compatible-mode\",\n        \"apiKey\": \"sk-your-dashscope-key\",\n        \"pricingCurrency\": \"CNY\",\n        \"models\": {\n          \"qwen3.7-plus\": {\n            \"temperature\": 1,\n            \"topP\": 0.95,\n            \"topK\": 20,\n            \"extraBody\": {\n              \"preserve_thinking\": true\n            }\n          },\n          \"glm-5.1\": {\n            \"temperature\": 0.7,\n            \"topP\": 0.95,\n            \"contextCache\": true,\n            \"pricing\": {\n              \"tiers\": [\n                {\n                  \"maxInputTokens\": 32000,\n                  \"input\": 6,\n                  \"cachedInput\": 1.2,\n                  \"explicitCachedInput\": 0.6,\n                  \"cacheCreationInput\": 7.5,\n                  \"output\": 24\n                },\n                {\n                  \"maxInputTokens\": 200000,\n                  \"input\": 8,\n                  \"cachedInput\": 1.6,\n                  \"explicitCachedInput\": 0.8,\n                  \"cacheCreationInput\": 10,\n                  \"output\": 28\n                }\n              ]\n            },\n            \"extraBody\": {\n              \"preserve_thinking\": true\n            }\n          }\n        }\n      }\n    }\n  }\n  ```\n  Built-in token prices cover Codex GPT models in USD, DashScope `qwen3.7-max`, `qwen3.7-plus`, `glm-5.1`, `glm-5.2` in CNY, DeepSeek `deepseek-v4-flash`, `deepseek-v4-pro`, `deepseek-chat`, `deepseek-reasoner` in CNY, and OpenCode Go models (`glm-5.2`, `deepseek-v4-flash`, `deepseek-v4-pro`, `kimi-k2.7-code`, `mimo-v2.5`, `mimo-v2.5-pro`, `qwen3.7-plus`, `qwen3.7-max`, `minimax-m2.5`, `minimax-m3`) in USD. User `pricing` entries override built-ins. For DashScope, cached tokens are charged as explicit cache reads when the upstream usage includes `cache_creation_input_tokens`; otherwise `cachedInput` is used as the implicit cache read price. For DeepSeek, `prompt_cache_hit_tokens` map to cached input and `prompt_cache_miss_tokens` map to regular input.\n- **smallModel:** Fallback model used for tool-less warmup messages (e.g., Claude Code probe requests); defaults to gpt-5-mini.\n- **contextManagement:** Controls whether the proxy adds Responses API `context_management` compaction instructions. `messages` applies when Anthropic-style `/v1/messages` requests are translated to Responses API, including `openai-responses` provider message routes, and defaults to `true`. `responses` applies to native `/v1/responses` traffic, including `provider/model` aliases and the built-in `codex` provider, and defaults to `false`. Enable `responses` only after checking that your client supports context management compaction. When enabled, the request includes `context_management` in the body and keeps only the latest compaction carrier on follow-up turns. **Note:** Context management is forcibly disabled for GPT-5.6 and above models (e.g. `gpt-5.6-sol`, `gpt-5.6-terra`, `gpt-5.6-luna`) because enabling it breaks prompt cache hits on those models. This override takes precedence over the `contextManagement` and `modelResponsesApiCompactThresholds` settings.\n- **modelResponsesApiCompactThresholds:** Per-model Responses API `compact_threshold` overrides used when the proxy adds `context_management`. These values take precedence over the fallback threshold from `resolveResponsesCompactThreshold` (`max_prompt_tokens * ratio`, or the default fallback). Defaults set `gpt-5.4` and `gpt-5.5` to `217600` (`272000 * 0.8`), and `gpt-5.6-sol`, `gpt-5.6-terra`, `gpt-5.6-luna` to `231200` (`272000 * 0.85`). Models not listed continue to use the normal fallback logic.\n- **modelReasoningEfforts:** Per-model fallback reasoning effort for `/v1/messages` requests. It is used only when the request does not provide `output_config.effort`.\n  - **Priority:** request `output_config.effort` > `modelReasoningEfforts[model]` > built-in default (`xhigh` for GPT-5.3+ models, otherwise `high`).\n  - **Forwarding:** the resolved value remains `output_config.effort` for the Copilot native Messages API and becomes `reasoning.effort` when translated to the Responses API.\n  - **Configuration values:** `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`.\n- **useMessagesApi:** When `true`, Claude-family models that support Copilot's native `/v1/messages` endpoint will use the Messages API; otherwise they fall back to `/chat/completions`. Set to `false` to disable Messages API routing and always use `/chat/completions`. Defaults to `true`.\n- **useResponsesApiWebSocket:** When `true`, Responses API requests use Copilot's websocket transport for models that advertise `ws:/responses`; models that only advertise `/responses` continue to use HTTP. Set to `false` to disable websocket routing and use HTTP `/responses` whenever the selected model supports it. Defaults to `true`.\n- **useResponsesApiWebSearch:** When `true`, the server keeps Responses API tools with `type: \"web_search\"` and forwards them upstream. Set to `false` to strip those tools from `/responses` payloads. Defaults to `true`.\n- **messageApiWebSearchModel:** Global fallback model used when a top-level Copilot `/v1/messages` request contains only the server-side `web_search` tool. Defaults to `gpt-5-mini`. If the value is a `provider/model` alias, the request is routed into that provider's Messages API path with the provider prefix stripped. For Copilot GPT models, web search runs through `/responses`. Mixed `web_search` plus custom tools are not supported and the server-side `web_search` tool is stripped.\n- **claudeTokenMultiplier:** Multiplier applied to the fallback GPT-tokenizer estimate for Claude `/v1/messages/count_tokens` requests. Defaults to `1.15`. Increase it if your client is still compacting too late. This setting is only used when the proxy is estimating Claude tokens locally; if `anthropicApiKey` is configured and Anthropic token counting succeeds, the exact Anthropic count is returned instead.\n- **anthropicApiKey:** Anthropic API key used to forward Claude `/v1/messages/count_tokens` requests to Anthropic's real token counting endpoint, which returns exact counts instead of GPT tokenizer estimates. Can also be set via the `ANTHROPIC_API_KEY` environment variable. If not set, or if the upstream call fails, token counting falls back to local GPT tokenizer estimation controlled by `claudeTokenMultiplier`.\n\nEdit this file to customize prompts or swap in your own fast model. Restart the server (or rerun the command) after changes so the cached config is refreshed.\n\n## API Authentication\n\n- **Protected non-admin routes:** All routes except `/`, `/usage-viewer`, and `/usage-viewer/` require authentication when `auth.apiKeys` is configured and non-empty.\n- **Admin routes:** All `/admin/*` routes require `auth.adminApiKey`. If it is missing, the server generates one at startup and persists it to `config.json` before serving requests.\n- **Allowed auth headers:**\n  - `x-api-key: <your_key>`\n  - `Authorization: Bearer <your_key>`\n- **CORS preflight:** `OPTIONS` requests are always allowed.\n- **When no regular keys are configured:** Non-admin routes continue to allow requests. This does not apply to `/admin/*`, which only accepts `auth.adminApiKey`.\n\nExample request for a regular protected route:\n\n```sh\ncurl http://localhost:4141/v1/models \\\n  -H \"x-api-key: your_api_key\"\n```\n\nExample request for an admin route:\n\n```sh\ncurl http://localhost:4141/admin/config/model-mappings \\\n  -H \"x-api-key: your_admin_api_key\"\n```\n\n## API Endpoints\n\nThe server exposes several OpenAI- and Anthropic-compatible endpoints. Requests can target GitHub Copilot, the built-in `codex` provider, or configured providers depending on the selected model and `provider/model` alias.\n\n### OpenAI Compatible Endpoints\n\nThese endpoints mimic the OpenAI API structure.\n\n| Endpoint                    | Method | Description                                                      |\n| --------------------------- | ------ | ---------------------------------------------------------------- |\n| `POST /v1/responses`        | `POST` | OpenAI Most advanced interface for generating model responses. Supports `provider/model` aliases for `openai-responses` providers. |\n| `POST /v1/chat/completions` | `POST` | Creates a model response for the given chat conversation. Supports `provider/model` aliases for `openai-compatible` providers and can be used without Copilot when the target provider is configured. |\n| `GET /v1/models`            | `GET`  | Lists Copilot models plus enabled provider models using `provider/model-id` IDs. Requests from Codex clients (`User-Agent` beginning with `codex`) are forwarded to the Codex Models upstream. |\n| `POST /v1/embeddings`       | `POST` | Creates an embedding vector representing the input text.         |\n\n### Codex Backend Proxy Endpoints\n\nThese endpoints require an active Codex login. Each endpoint is available both without a version prefix and under `/v1`.\n\n| Endpoint | Method | Description |\n| --- | --- | --- |\n| `POST /alpha/search`<br>`POST /v1/alpha/search` | `POST` | Transparently forwards the JSON body and query parameters to the Codex Alpha Search upstream. |\n| `POST /images/generations`<br>`POST /v1/images/generations` | `POST` | Forwards a JSON image generation request to the Codex Images upstream. When the request omits `Content-Type`, the gateway defaults it to `application/json`. |\n| `POST /images/edits`<br>`POST /v1/images/edits` | `POST` | Forwards an image edit request to the Codex Images upstream. Send this request as `multipart/form-data` and let the HTTP client generate the `boundary`; the gateway preserves the incoming content type and streams the upload body. |\n\nFor every endpoint above, the gateway replaces client authorization and account headers with the active Codex login, preserves query parameters and compatible request headers, and returns the upstream status, headers, and body.\n\n### Anthropic Compatible Endpoints\n\nThese endpoints are designed to be compatible with the Anthropic Messages API.\n\n| Endpoint                         | Method | Description                                                  |\n| -------------------------------- | ------ | ------------------------------------------------------------ |\n| `POST /v1/messages`              | `POST` | Creates a model response for a given conversation. Supports `provider/model` aliases for configured providers, including translation through `openai-compatible` providers. |\n| `POST /v1/messages/count_tokens` | `POST` | Calculates the number of tokens for a given set of messages. Supports `provider/model` aliases for configured providers. |\n| `POST /:provider/v1/messages`       | `POST` | Proxies Anthropic Messages requests to the configured Anthropic provider, translates them through an OpenAI-compatible provider, or translates them through an OpenAI Responses provider. |\n| `GET /:provider/v1/models`          | `GET`  | Proxies model listing requests to the configured provider. For `codex`, returns the built-in catalog by default; Codex clients (`User-Agent` starting with `codex`) are forwarded to the Codex Models upstream. |\n| `POST /:provider/v1/messages/count_tokens` | `POST` | Calculates tokens locally for provider route requests. |\n| `POST /:provider/v1/responses`      | `POST` | Proxies OpenAI Responses requests to a configured `openai-responses` provider (including `codex`). |\n| `POST /:provider/v1/alpha/search`   | `POST` | Proxies alpha-search requests. For `codex`, forwards to the Codex Alpha Search upstream; for other providers, forwards to `{baseUrl}/v1/alpha/search`. |\n| `POST /:provider/v1/images/generations` | `POST` | Proxies image generation. For `codex`, uses the Codex Images upstream; for other providers, forwards to `{baseUrl}/v1/images/generations` (15-minute timeout). |\n| `POST /:provider/v1/images/edits`   | `POST` | Proxies image edits. For `codex`, uses the Codex Images upstream; for other providers, forwards multipart/streamed bodies to `{baseUrl}/v1/images/edits` (15-minute timeout). |\n\n### Usage Monitoring Endpoints\n\nNew endpoints for monitoring your Copilot usage and quotas.\n\n| Endpoint     | Method | Description                                                  |\n| ------------ | ------ | ------------------------------------------------------------ |\n| `GET /usage` | `GET`  | Get detailed Copilot usage statistics and quota information. |\n| `GET /token` | `GET`  | Get the current Copilot token being used by the API.         |\n\n### Admin / Configuration Endpoints\n\nThese endpoints are reserved for local administrative actions and only accept `auth.adminApiKey`.\n\n| Endpoint                              | Method | Description                                                                 |\n| ------------------------------------- | ------ | --------------------------------------------------------------------------- |\n| `GET /admin/config/model-mappings`    | `GET`  | Returns the current `config.json` path and the active `modelMappings` map.  |\n| `POST /admin/config/model-mappings`   | `POST` | Updates only the `modelMappings` field in `config.json` and returns it back. |\n\n## Example Usage\n\nCommon `npx` commands:\n\n```sh\n# Start the gateway\nnpx @jeffreycao/copilot-api@latest start\n\n# Start on a custom port with verbose logging\nnpx @jeffreycao/copilot-api@latest start --port 8080 --verbose\n\n# Run the auth flow\nnpx @jeffreycao/copilot-api@latest auth login\n\n# Configure a third-party provider, then run without GitHub Copilot\nnpx @jeffreycao/copilot-api@latest auth login --provider dashscope\nnpx @jeffreycao/copilot-api@latest start\n\n# Print debug information as JSON\nnpx @jeffreycao/copilot-api@latest debug --json\n\n# Run the published CLI with Bun instead of Node.js\nbunx --bun @jeffreycao/copilot-api@latest start\n```\n\nOpenAI-compatible provider examples after configuring `dashscope`:\n\n```sh\ncurl http://localhost:4141/v1/chat/completions \\\n  -H \"content-type: application/json\" \\\n  -d '{\"model\":\"dashscope/qwen3.6-plus\",\"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]}'\n\ncurl http://localhost:4141/dashscope/v1/messages \\\n  -H \"content-type: application/json\" \\\n  -d '{\"model\":\"qwen3.6-plus\",\"max_tokens\":1024,\"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]}'\n```\n\n## Usage Tips\n\n### CLAUDE.md or AGENTS.md Recommended Content\n\nTo add these reminders manually, include the following in `CLAUDE.md` for Claude Code, or `AGENTS.md` for opencode/codex:\n\n```\n- Prohibited from directly asking questions to users, MUST use question tool.\n- Once you can confirm that the task is complete, MUST use question tool to make user confirm. The user may respond with feedback if they are not satisfied with the result, which you can use to make improvements and try again, after try again, MUST use question tool to make user confirm again.\n```\n"}, "c2a6d2201a264a7f9b8b544b7390fd62a9dafd03": {"t": 1785765556.1389434, "n": 48277, "h": "1a9b46244fae3634", "c": "# Copilot API Proxy\n\nEnglish | [简体中文](./README.zh-CN.md)\n\n## Important Notes\n\n> [!IMPORTANT]\n> **Before using, please be aware of the following:**\n>\n> 1. **Claude Code configuration:** When using with Claude Code, please configure the model ID as `claude-opus-4-8`. Example claude `settings.json` see [Manual Configuration with `settings.json`](#manual-configuration-with-settingsjson). \n>\n> 2. **Built-in `copilot`, `codex` and third-party providers:** Run `npx @jeffreycao/copilot-api@latest auth` and choose `copilot`, `codex`, `deepseek`, `custom`, or other providers.\n>\n> 3. **Note:** See [GitHub Copilot Security Notice](./NOTICE.md#github-copilot-security-notice) for the warning removed from the README header.\n\n---\n\n## Project Overview\n\nA small AI gateway that can use GitHub Copilot, the built-in `codex` provider, or configured third-party providers such as DashScope. GitHub Copilot is optional: if no GitHub token is available, the server can still start in provider-only mode as long as at least one enabled provider is configured.\n\nThe gateway exposes OpenAI- and Anthropic-compatible APIs from one local endpoint, so tools like [Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview), OpenCode, Codex, and OpenAI-compatible clients can share the same local server.\n\nOn the GitHub Copilot path, the gateway prefers Copilot's native Anthropic-style Messages API when available, preserving more Claude-native behavior for tool-heavy workflows.\n\n## Features\n\n- **OpenAI and Anthropic compatibility**: Serve `/v1/responses`, `/v1/chat/completions`, `/v1/models`, `/v1/embeddings`, and `/v1/messages` from one local gateway.\n- **Copilot is optional**: Use GitHub Copilot when credentials are present, or run the server with only configured providers.\n- **One gateway for Copilot, `codex`, and external providers**: Route GitHub Copilot, the built-in `codex` provider, and configured third-party providers behind the same endpoint.\n- **Standalone third-party providers**: Configure providers such as DashScope, DeepSeek, OpenRouter, or a custom provider and start the gateway without a GitHub Copilot login.\n- **OpenAI-compatible providers on chat and Messages APIs**: `openai-compatible` providers can serve top-level `/v1/chat/completions` through `model: \"provider/model\"` and Anthropic-style `/v1/messages` through request/response translation.\n- **Agent-friendly Claude handling on Copilot**: Prefer native `/v1/messages` when available, preserve Claude-style tool flows, support Anthropic beta features, Claude WebSearch through Responses-capable models, and keep subagent/session markers intact.\n- **Claude Code and OpenCode integration**: Works with Claude Code and OpenCode, including direct Anthropic-compatible usage through `@ai-sdk/anthropic`.\n- **Flexible auth and deployment options**: Supports interactive login or direct tokens, individual/business/enterprise plans, GitHub Enterprise, opencode OAuth, and custom data directories.\n- **Multi-provider routing**: Expose provider-specific `/:provider/...` routes or use `model: \"provider/model\"` on the top-level API.\n\n## Prerequisites\n\n- Bun (>= 1.2.x)\n- Node.js if you plan to run the published CLI with `npx`\n- GitHub account with Copilot subscription only if you want to use the GitHub Copilot provider\n- An API key or OAuth login for at least one configured provider if you want to run without GitHub Copilot\n\n## Installation\n\nTo install dependencies, run:\n\n```sh\nbun install\n```\n\nTo start the server directly from source:\n\n```sh\nbun run start start\n```\n\n## Running from Source\n\nThe project can be run from source in several ways:\n\n### Development Mode\n\n```sh\nbun run dev start\n```\n\n### Production Mode\n\n```sh\nbun run start start\n```\n\n## Using with npx\n\nYou can run the project directly using npx:\n\n> [!IMPORTANT]\n> Token usage storage uses Node's built-in `node:sqlite` module when running with `npx`. It is enabled on Node.js >= 22.13.0. On Node.js < 22.13.0, the CLI still starts, but token usage storage is disabled.\n>\n> If you want token usage storage without upgrading Node.js, run the published CLI with Bun instead: `bunx --bun @jeffreycao/copilot-api@latest start`.\n\n```sh\nnpx @jeffreycao/copilot-api@latest start\n```\n\nWith options:\n\n```sh\nnpx @jeffreycao/copilot-api@latest start --port 8080\n```\n\nFor authentication or provider configuration only:\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth\n```\n\nTo run without GitHub Copilot, configure at least one provider first, then start the server normally:\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth login --provider dashscope\nnpx @jeffreycao/copilot-api@latest start\n```\n\n## Using with Docker\n\nBuild the image:\n\n```sh\ndocker build -t copilot-api .\n```\n\nRun the container with a bind mount so auth data survives restarts:\n\n```sh\nmkdir -p ./copilot-data\ndocker run -p 4141:4141 -v $(pwd)/copilot-data:/root/.local/share/copilot-api copilot-api\n```\n\nThis stores GitHub auth data, provider config, and other gateway state in `./copilot-data` on the host, mapped to `/root/.local/share/copilot-api` in the container.\n\nOr pass a GitHub token directly:\n\n```sh\ndocker run -p 4141:4141 -e GH_TOKEN=your_github_token_here copilot-api\n```\n\n## Electron Desktop App\n\nIf you prefer a GUI, this repository also includes an Electron desktop app in `desktop/`. It supports GitHub Copilot sign-in, OpenAI Codex OAuth, and API-key configuration for DeepSeek, DashScope, OpenRouter, or a custom provider. After authorization or provider configuration, it can start and stop the local proxy with one click and shows the local endpoint, auth header, available models, usage, and logs in the app.\n\nThe settings screen also exposes `OAuth App`, `API Home`, `Enterprise URL`, verbose logging, and minimize-to-tray. Desktop packages are published in GitHub Releases:\n\nhttps://github.com/caozhiyuan/copilot-api/releases\n\nDownload the installer for your platform, authorize or configure a provider inside the app, choose a port, start the server, then point your client at the local endpoint shown in the app. Packaged desktop builds use the bundled Electron runtime, so normal desktop usage does not require installing Node.js separately. Token usage history is enabled when that bundled runtime supports SQLite.\n\nThe desktop app's Advanced Config page reads and writes the shared model mappings through `GET/POST /admin/config/model-mappings`. The same mappings apply across `POST /v1/messages`, `POST /v1/messages/count_tokens`, `POST /v1/responses`, and `POST /v1/chat/completions` instead of being split per interface. It uses `auth.adminApiKey` instead of the regular `auth.apiKeys`, and the app reads that key directly from `config.json` after the server has generated it on startup.\n\n### Desktop App Screenshots\n\nMain dashboard, token usage breakdown in the bundled Electron app:\n\n<p align=\"center\">\n  <img src=\"./docs/screenshots/desktop-dashboard.png\" alt=\"Copilot API desktop app dashboard\" width=\"49%\" />\n  <img src=\"./docs/screenshots/desktop-token-usage.png\" alt=\"Copilot API desktop app token usage view\" width=\"49%\" />\n</p>\n\n## Using with Claude Code\n\nThis AI gateway can be used to power [Claude Code](https://docs.anthropic.com/en/claude-code), an experimental conversational AI assistant for developers from Anthropic.\n\nThere are two ways to configure Claude Code to use this AI gateway:\n\n### Interactive Setup with `--claude-code` flag\n\nTo get started, run the `start` command with the `--claude-code` flag:\n\n```sh\nnpx @jeffreycao/copilot-api@latest start --claude-code\n```\n\nYou will be prompted to select a primary model and a \"small, fast\" model for background tasks. After selecting the models, a command will be copied to your clipboard. This command sets the necessary environment variables for Claude Code to use the gateway.\n\nPaste and run this command in a new terminal to launch Claude Code.\n\n### Manual Configuration with `settings.json`\n\nAlternatively, you can configure Claude Code by creating a `.claude/settings.json` file in your project's root directory. This file should contain the environment variables needed by Claude Code. This way you don't need to run the interactive setup every time.\n\nHere is an example `.claude/settings.json` file:\n\n```json\n{\n  \"env\": {\n    \"ANTHROPIC_BASE_URL\": \"http://localhost:4141\",\n    \"ANTHROPIC_AUTH_TOKEN\": \"dummy\",\n    \"ANTHROPIC_MODEL\": \"deepseek/deepseek-v4-pro\",\n    \"ANTHROPIC_DEFAULT_SONNET_MODEL\": \"deepseek/deepseek-v4-pro\",\n    \"ANTHROPIC_DEFAULT_HAIKU_MODEL\": \"deepseek/deepseek-v4-flash\",\n    \"DISABLE_NON_ESSENTIAL_MODEL_CALLS\": \"1\",\n    \"CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC\": \"1\",\n    \"CLAUDE_CODE_ATTRIBUTION_HEADER\": \"0\",\n    \"CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION\": \"false\",\n    \"CLAUDE_CODE_DISABLE_TERMINAL_TITLE\": \"true\",\n    \"CLAUDE_CODE_ENABLE_AWAY_SUMMARY\": \"0\"\n  },\n  \"permissions\": {\n    \"deny\": [\n      \"mcp__ide__executeCode\"\n    ]\n  }\n}\n```\n\n- Replace `ANTHROPIC_MODEL`, `ANTHROPIC_DEFAULT_OPUS_MODEL`, `ANTHROPIC_DEFAULT_SONNET_MODEL`, and `ANTHROPIC_DEFAULT_HAIKU_MODEL` according to your needs. After configuration, please install the claude code plugin [Plugin Integrations](#plugin-integrations).  \n- Setting CLAUDE_CODE_ATTRIBUTION_HEADER to 0 can prevent Claude code from adding billing and version information in system prompts, thereby avoiding prompt cache invalidation.\n- Turning off CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION and CLAUDE_CODE_ENABLE_AWAY_SUMMARY can prevent quota from being consumed unnecessarily.\n- Claude Code WebSearch is supported for pure search requests. For Copilot, keep the global `messageApiWebSearchModel` set to a Responses-capable GPT model or a `provider/model` alias. For provider routes, use a native Anthropic provider or an `openai-responses` provider. Add `WebSearch` to `permissions.deny` only if you want to forbid this traffic.\n- If using a non-Claude model, do not enable ENABLE_TOOL_SEARCH. If using the Claude model, can enable ENABLE_TOOL_SEARCH. The current Claude Code uses the client tool search mode. In this mode, loading defer tools requires an additional request each time.\n- `CLAUDE_CODE_AUTO_COMPACT_WINDOW`: Set the context capacity in tokens used for auto-compaction calculations. Defaults to the model's context window: 200K for standard models or 1M for extended context models. Use a lower value like `500000` on a 1M model (e.g., `claude-opus-4-6[1m]`) to treat the window as 500K for compaction purposes. The value is capped at the model's actual context window. `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` is applied as a percentage of this value. Setting this variable decouples the compaction threshold from the status line's `used_percentage`, which always uses the model's full context window.\n\nYou can find more options here: [Claude Code settings](https://docs.anthropic.com/en/docs/claude-code/settings#environment-variables)\n\nYou can also read more about IDE integration here: [Add Claude Code to your IDE](https://docs.anthropic.com/en/docs/claude-code/ide-integrations)\n\n## Using with OpenCode\n\nOpenCode already has a direct GitHub Copilot provider. Use this section when you want OpenCode to point at this AI gateway through `@ai-sdk/anthropic` and reuse the agent behaviors described earlier in this README.\n\n### Minimal setup\n\nStart the AI gateway with the OpenCode OAuth app:\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth --oauth-app=opencode\nnpx @jeffreycao/copilot-api@latest start\n```\n\nThen point OpenCode at the gateway with `@ai-sdk/anthropic`.\n\nExample `~/.config/opencode/opencode.json`:\n\n```json\n{\n  \"$schema\": \"https://opencode.ai/config.json\",\n  \"provider\": {\n    \"local\": {\n      \"npm\": \"@ai-sdk/anthropic\",\n      \"name\": \"My Local\",\n      \"options\": {\n        \"baseURL\": \"http://localhost:4141/v1\",\n        \"apiKey\": \"dummy\"\n      },\n      \"models\": {\n        \"gpt-5.4\": {\n          \"name\": \"gpt-5.4\",\n          \"modalities\": {\n            \"input\": [\"text\", \"image\"],\n            \"output\": [\"text\"]\n          },\n          \"limit\": {\n            \"context\": 400000,\n            \"input\": 272000,\n            \"output\": 128000\n          }\n        },\n        \"claude-sonnet-4.6\": {\n          \"id\": \"claude-sonnet-4.6\",\n          \"name\": \"claude-sonnet-4.6\",\n          \"modalities\": {\n            \"input\": [\"text\", \"image\"],\n            \"output\": [\"text\"]\n          },          \n          \"limit\": {\n            \"context\": 200000,\n            \"output\": 32000\n          },\n          \"options\": {\n            \"thinking\": {\n              \"type\": \"adaptive\"\n            },\n            \"effort\": \"max\"\n          }\n        }\n      }\n    }\n  }\n}\n```\n\nWhy these fields matter:\n\n- `npm: \"@ai-sdk/anthropic\"` is the important part. OpenCode will speak Anthropic Messages semantics to this AI gateway instead of flattening everything into OpenAI Chat Completions.\n- `options.baseURL` should be `http://localhost:4141/v1`; the Anthropic SDK will append `/messages`, `/models`, and `/messages/count_tokens` automatically.\n- If you enable `auth.apiKeys` in this AI gateway, replace `dummy` with a real key. Otherwise any placeholder value is fine.\n\n## Using with Codex\n\nThis AI gateway can also power Codex.\n\n### Codex `config.toml` Reference\n\nAdd the following `[model_providers.copilot_api]` section to your Codex `~/.codex/config.toml`:\n\n```toml\nmodel_provider = \"copilot_api\"\nmodel_reasoning_summary = \"auto\"\nmodel_context_window = 272000\nmodel_auto_compact_token_limit = 244800\n\n[model_providers.copilot_api]\nname = \"OpenAI\"\nbase_url = \"http://localhost:4141\"\nenv_key = \"GITHUB_COPILOT_API_KEY\"\nrequires_openai_auth = true\nsupports_websockets = false\nwire_api = \"responses\"\nrequest_max_retries = 3\nstream_max_retries = 1\nstream_idle_timeout_ms = 300000\n\n[features]\nremote_compaction_v2 = true\n\n[analytics]\nenabled = false\n```\n\n> [!NOTE]\n> This configuration is specific to Codex and the GitHub Copilot provider. `name` must be set to `\"OpenAI\"`. It can help mitigate Codex local compact cache miss issues. \n\n## GPT Tool Search\n\nFor GPT Responses models such as `gpt-5.4+`, this AI gateway can expose Responses `tool_search` through a small MCP bridge. The same bridge can be used by Claude Code and opencode, as long as the client loads MCP servers and sends Anthropic Messages traffic through this gateway.\n\nDo not set Claude Code's native `ENABLE_TOOL_SEARCH` for GPT models. That flag enables Claude Code's own client-side tool search mode, and it may stop forwarding deferred tool definitions. This gateway needs the full tool definitions so it can keep the small always-loaded tool set eager and translate every other tool into Responses deferred namespaces.\n\nIf you install `tool-search@copilot-api-marketplace`, Claude Code receives this MCP bridge automatically and you can skip the manual Claude Code MCP setup below.\n\nAdd the tool search bridge to the MCP config used by Claude Code:\n\n```json\n{\n  \"mcpServers\": {\n    \"tool_search\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@jeffreycao/copilot-api@latest\", \"mcp\"]\n    }\n  }\n}\n```\n\nAdd the tool search bridge to the MCP config used by opencode:\n\n```json\n{\n  \"mcp\": {\n    \"tool_search\": {\n      \"type\": \"local\",\n      \"command\": [\"npx\", \"-y\", \"@jeffreycao/copilot-api@latest\", \"mcp\"]\n    }\n  }\n}\n```\n\nFor local development, use `bun` as the command and `[\"run\", \"./src/main.ts\", \"mcp\"]` as the args.\n\nInternally, the gateway now configures OpenAI Responses `tool_search` in client-executed mode. Deferred tools are still exposed as searchable namespaces, but the model is explicitly asked to return the exact deferred tool names it wants to load next.\n\nThe bridge uses direct tool selection, not query search. Its tool input is `names`, a comma-separated list of exact deferred tool names, for example `TaskList,TaskGet,mcp__fetch__fetch`.\n\n## Plugin Integrations\n\nPlugin integrations are available for Claude Code and opencode.\n\n#### Claude Code plugin integration (marketplace-based)\n\nThe Claude Code integration is packaged as two plugins:\n\n- `agent-inject` injects `__SUBAGENT_MARKER__...` on `SubagentStart`, so the gateway can infer `x-initiator: agent`.\n- `tool-search` registers the `tool_search` MCP bridge used for GPT Responses deferred tool loading.\n\n- Marketplace catalog in this repository: `.claude-plugin/marketplace.json`\n- Plugin sources in this repository: `plugin/claude/agent-inject`, `plugin/claude/tool-search`\n\nAdd the marketplace remotely:\n\n```sh\n/plugin marketplace add https://github.com/caozhiyuan/copilot-api.git\n```\n\nInstall the plugins from the marketplace:\n\n```sh\n/plugin install agent-inject@copilot-api-marketplace\n/plugin install tool-search@copilot-api-marketplace\n```\n\nAfter installation, `agent-inject` injects `__SUBAGENT_MARKER__...` on `SubagentStart`, and the gateway uses it to infer `x-initiator: agent`.\n\nThe `agent-inject` plugin also registers a `UserPromptSubmit` hook that returns `{\"continue\": true}`, and it can inject `SessionStart` reminder rules through environment variables:\n\n- `CLAUDE_PLUGIN_ENABLE_QUESTION_RULES=1` enables the two reminders about using the `question` tool automatically for Claude Code. Alternatively, you can add the same reminders manually in `CLAUDE.md`; see [CLAUDE.md or AGENTS.md Recommended Content](#claudemd-or-agentsmd-recommended-content).\n- `CLAUDE_PLUGIN_ENABLE_NO_BACKGROUND_AGENTS_RULE=1` enables the `run_in_background: true` avoidance reminder for agent hooks.\n\nThe `tool-search` plugin bundles the same MCP bridge described in [GPT Tool Search](#gpt-tool-search), so Claude Code users do not need to add the `tool_search` server manually when they install that plugin.\n\n#### Opencode plugin\n\nThe subagent marker producer is packaged as an opencode plugin located at `plugin/opencode/subagent-marker.js`.\n\n**Installation:**\n\nCopy the plugin file to your opencode plugins directory:\n\n```sh\n# Clone or download this repository, then copy the plugin\ncp plugin/opencode/subagent-marker.js ~/.config/opencode/plugins/\n```\n\nOr manually create the file at `~/.config/opencode/plugins/subagent-marker.js` with the plugin content.\n\n**Features:**\n\n- Tracks sub-sessions created by subagents\n- Automatically prepends a marker system reminder (`__SUBAGENT_MARKER__...`) to subagent chat messages\n- Sets `x-session-id` header for session tracking\n- Enables the gateway to infer `x-initiator: agent` for subagent-originated requests\n\nThe plugin hooks into `session.created`, `session.deleted`, `chat.message`, and `chat.headers` events to provide seamless subagent marker functionality.\n\n## Using the Usage Viewer\n\nAfter starting the server, a URL to the Copilot Usage Dashboard will be displayed in your console. This dashboard is a web interface for monitoring your API usage.\n\n1.  Start the server. For example, using npx:\n    ```sh\n    npx @jeffreycao/copilot-api@latest start\n    ```\n2.  The server will output a URL to the usage viewer. Copy and paste this URL into your browser. It will look something like this:\n    `http://localhost:4141/usage-viewer?endpoint=http://localhost:4141/usage`\n    - If you use the `start.bat` script on Windows, this page will open automatically.\n\nThe dashboard provides a user-friendly interface to view your Copilot usage data:\n\n> Token usage history requires Bun or Node.js >= 22.13.0. On Node.js < 22.13.0, the server runs normally but token usage storage is disabled.\n\n- **API Endpoint URL**: The dashboard is pre-configured to fetch data from your local server endpoint via a URL query parameter. You can manually switch this to any other compatible API endpoint.\n- **x-api-key Authentication**: If API Key authentication is enabled, you can provide the `x-api-key` request header. The key is persisted in the browser's local storage.\n- **Period Selector**: Choose from Day, Week, or Month time ranges. The URL query parameter updates automatically when you switch, making it easy to bookmark and share.\n- **Fetch Data**: Click the \"Refresh\" button to load or refresh the usage data. The dashboard also fetches data automatically on page load.\n- **Copilot Quotas**: View quota usage for services such as Chat and Completions via progress bars. Hover over a card to see used/remaining details.\n- **Token Usage Metric Cards**: See a summary of Total, Input, Output, Cache Read, Cache Write, Requests, and estimated cost for the current period.\n- **Trend Chart (Week / Month)**: An interactive line chart with model and metric filters. Click a data point to inspect the usage breakdown for a specific day.\n- **Model Breakdown Table**: A per-model summary of requests, input/output/cache tokens, and estimated cost for the selected period.\n- **Request Events (Paginated)**: A time-sorted list of request event records with pagination support, showing timestamps, models, request IDs, and token counts.\n- **Detailed Information**: See the full JSON response from the API for a detailed breakdown of all available usage statistics.\n- **URL-based Configuration**: You can also specify the API endpoint and period directly via `endpoint` and `period` query parameters. For example:\n  `http://localhost:4141/usage-viewer?endpoint=http://your-api-server/usage&period=week`\n\n### Usage Viewer Screenshot\n\n<p align=\"center\">\n  <img src=\"./docs/screenshots/usage-viewer.png\" alt=\"Copilot API usage viewer\" width=\"900\" />\n</p>\n\n## Command Structure\n\nCopilot API now uses a subcommand structure with these main commands:\n\n- `start`: Start the gateway server. If a GitHub token is available, the server starts with Copilot enabled. If no GitHub token is available, it starts in provider-only mode when at least one enabled provider exists; otherwise it guides you through provider setup.\n- `auth`: Run provider login or configuration without starting the server. Use it for GitHub Copilot login, Codex OAuth, or third-party provider API key setup.\n- `debug`: Display diagnostic information including version, runtime details, file paths, and authentication status. Useful for troubleshooting and support.\n\n## Command Line Options\n\n### Global Options\n\nThe following options can be used with any subcommand. When passing them before the subcommand, use the `--key=value` form:\n\n| Option            | Description                                            | Default | Alias |\n| ----------------- | ------------------------------------------------------ | ------- | ----- |\n| --api-home        | Path to the API home directory (sets COPILOT_API_HOME) | none    | none  |\n| --oauth-app       | OAuth app identifier (sets COPILOT_API_OAUTH_APP)      | none    | none  |\n| --enterprise-url  | Enterprise URL for GitHub (sets COPILOT_API_ENTERPRISE_URL) | none | none |\n\n### Start Command Options\n\nThe following command line options are available for the `start` command:\n\n| Option         | Description                                                                   | Default    | Alias |\n| -------------- | ----------------------------------------------------------------------------- | ---------- | ----- |\n| --port         | Port to listen on                                                             | 4141       | -p    |\n| --verbose      | Enable verbose logging                                                        | false      | -v    |\n| --github-token | Provide GitHub token directly (must be generated using the `auth` subcommand) | none       | -g    |\n| --claude-code  | Generate a command to launch Claude Code with Copilot API config              | false      | -c    |\n| --show-token   | Show GitHub and Copilot tokens on fetch and refresh                           | false      | none  |\n| --proxy-env    | Initialize proxy from environment variables                                   | false      | none  |\n\n### Auth Command Options\n\n| Option       | Description               | Default | Alias |\n| ------------ | ------------------------- | ------- | ----- |\n| --provider   | Provider to log in with or configure (`copilot`, `codex`, `opencode-go`, `deepseek`, `dashscope`, `openrouter`, or `custom`) | prompt | none |\n| --verbose    | Enable verbose logging    | false   | -v    |\n| --show-token | Show GitHub token on auth | false   | none  |\n\nUse `copilot-api auth login --provider copilot` only when you want to enable the GitHub Copilot provider. Copilot is not required for `codex` or third-party provider-only usage.\n\nUse `copilot-api auth login --provider deepseek`, `--provider dashscope`, `--provider openrouter`, or `--provider opencode-go` to add or update those common third-party providers from the CLI. DeepSeek prompts for masked `apiKey`, provider `type` (default `anthropic`), and `baseUrl` defaulting to `https://api.deepseek.com/anthropic`. DashScope prompts for masked `apiKey`, provider `type` (default `openai-compatible`), and prefilled `baseUrl`. OpenRouter prompts for masked `apiKey` and prefilled `baseUrl` only, and writes `type: \"anthropic\"`. OpenCode Go prompts for masked `apiKey` and prefilled `baseUrl` only, and writes `type: \"openai-compatible\"` (baseUrl `https://opencode.ai/zen/go`). After a provider is configured and enabled, `copilot-api start` can run without any GitHub token.\n\nUse `copilot-api auth login --provider custom` to add or update another third-party provider from the CLI. The command prompts for the provider name, supported type (`anthropic`, `openai-compatible`, or `openai-responses`), `baseUrl`, masked `apiKey`, and `authType`; `authType` may be left as the type default or set to `x-api-key` / `authorization`.\n\n### Debug Command Options\n\n| Option | Description               | Default | Alias |\n| ------ | ------------------------- | ------- | ----- |\n| --json | Output debug info as JSON | false   | none  |\n\n## Configuration (config.json)\n\n- **Location:** `~/.local/share/copilot-api/config.json` (Linux/macOS) or `%USERPROFILE%\\.local\\share\\copilot-api\\config.json` (Windows).\n- **Default shape:**\n  ```json\n  {\n    \"auth\": {\n      \"apiKeys\": [],\n      \"adminApiKey\": \"<auto-generated-on-startup>\"\n    },\n    \"providers\": {},\n    \"modelMappings\": {},\n    \"extraPrompts\": {\n      \"gpt-5-mini\": \"<built-in exploration prompt>\"\n    },\n    \"smallModel\": \"gpt-5-mini\",\n    \"contextManagement\": {\n      \"messages\": true,\n      \"responses\": false\n    },\n    \"modelResponsesApiCompactThresholds\": {\n      \"gpt-5.4\": 217600,\n      \"gpt-5.5\": 217600,\n      \"gpt-5.6-sol\": 231200,\n      \"gpt-5.6-terra\": 231200,\n      \"gpt-5.6-luna\": 231200\n    },\n    \"modelReasoningEfforts\": {\n      \"gpt-5-mini\": \"low\"\n    },\n    \"useMessagesApi\": true,\n    \"useResponsesApiWebSocket\": true,\n    \"useResponsesApiWebSearch\": true,\n    \"messageApiWebSearchModel\": \"gpt-5-mini\"\n  }\n  ```\n- **auth.apiKeys:** API keys used for request authentication on non-admin routes. Supports multiple keys for rotation. Requests can authenticate with either `x-api-key: <key>` or `Authorization: Bearer <key>`. If empty or omitted, authentication for non-admin routes is disabled.\n- **auth.adminApiKey:** Single admin key used only for `/admin/*` routes. If missing, the server generates a random key at startup and writes it back to `config.json`. Requests use the same `x-api-key` or `Authorization: Bearer` headers, but regular `auth.apiKeys` never grant access to `/admin/*`.\n- **modelMappings:** Exact `sourceModel -> targetModel` rewrites shared by top-level `POST /v1/messages`, `POST /v1/messages/count_tokens`, `POST /v1/responses`, and `POST /v1/chat/completions` requests. Omit it or leave it as `{}` to disable rewrites. Both the source and target must be non-empty strings. Targets can be regular model IDs or `provider/model` aliases such as `dashscope/qwen3.6-plus`, and the rewrite happens before provider alias parsing. These mappings are not split per interface. The admin endpoints `GET/POST /admin/config/model-mappings` read and update only this field.\n- **extraPrompts:** Map of `model -> prompt` appended to the first system prompt when translating Anthropic-style requests to Responses API. Use this to inject guardrails or guidance per model. Missing default entries are auto-added without overwriting your custom prompts. For GPT-5.3+ models (e.g. `gpt-5.3-codex`, `gpt-5.4`, `gpt-5.5`), a built-in commentary prompt is used as fallback when not explicitly configured. The built-in prompts enable phase-aware commentary, which lets the model emit a short user-facing progress update before tools or deeper reasoning.\n- **providers:** Global upstream provider map. Each provider key (for example `dashscope`) becomes a route prefix (`/dashscope/v1/messages`). Supports `type: \"anthropic\"`, `type: \"openai-compatible\"`, and `type: \"openai-responses\"`. Top-level clients can also use `model: \"dashscope/model-id\"` with `/v1/messages`, `/v1/messages/count_tokens`, `/v1/responses`, and `/v1/chat/completions`; the gateway strips the `dashscope/` prefix before forwarding upstream. `openai-compatible` providers support both chat and Messages flows: `/v1/chat/completions` is proxied to upstream `/v1/chat/completions`, while `/v1/messages` and `/:provider/v1/messages` are translated to upstream chat completions and translated back to Anthropic Messages responses. `GET /v1/models` aggregates enabled provider models with `provider/model-id` IDs; use `GET /dashscope/v1/models` for a single provider's raw model list.\n  - `enabled` defaults to `true` if omitted.\n  - `baseUrl` should be provider API base URL without the final endpoint. For Anthropic providers, omit `/v1/messages`; for OpenAI-compatible providers, omit `/v1/chat/completions`; for OpenAI Responses providers, omit `/v1/responses`.\n  - `apiKey` is used as the upstream credential value and is required for regular providers.\n  - `authType` (optional): Controls how `apiKey` is sent upstream. Supports `x-api-key` and `authorization` for regular providers. Anthropic providers default to `x-api-key`; OpenAI-compatible and OpenAI Responses providers default to `authorization`. When set to `authorization`, the proxy sends `Authorization: Bearer <apiKey>`. `oauth2` is reserved for the built-in `codex` provider and is written automatically by `auth login --provider codex`.\n  - `pricingCurrency` (optional): Provider-level currency used for token cost calculation, for example `USD` or `CNY`. Quick providers default to `CNY` for DashScope and DeepSeek, and `USD` for Codex/OpenRouter. Costs are grouped by currency and are not exchange-rate converted.\n  - `models` (optional): Per-model configuration map. Each key is a model ID (matching the model name in requests), and the value is:\n    - `temperature` (optional): Default temperature value used when the request does not specify one.\n    - `topP` (optional): Default top_p value used when the request does not specify one.\n    - `topK` (optional): Default top_k value used when the request does not specify one.\n    - `extraBody` (optional): Dynamic fields merged into the upstream request body for that model. Request body fields with the same name take precedence. OpenAI-compatible providers can use this for fields such as `enable_thinking`, `preserve_thinking`, `reasoning_effort`. `thinking_budget` is a special OpenAI-compatible provider override: when configured in `extraBody`, it is forced after Anthropic `thinking.budget_tokens` translation and overrides the request-derived budget. For providers whose name is `dashscope` or whose `baseUrl` contains `aliyuncs.com`, the request-derived `thinking_budget` (from Anthropic `thinking.budget_tokens`) is forwarded upstream; for other OpenAI-compatible providers the request-derived `thinking_budget` is stripped, while an `extraBody` `thinking_budget` is still honored. For DashScope providers, `preserve_thinking` defaults to `true` when not explicitly set in `extraBody` or the request body.\n    - `pricing` (optional): Per-model token prices, in the provider `pricingCurrency`, per 1M tokens. Supported fields are `input`, `output`, `cachedInput` (implicit cache read), `explicitCachedInput` (explicit cache read), and `cacheCreationInput`. Use `tiers` with `maxInputTokens` for input-size tiered pricing.\n    - `contextCache` (optional): Defaults to `true` for providers whose name is `dashscope` or whose `baseUrl` contains `aliyuncs.com`; defaults to `false` for other OpenAI-compatible providers. This enables Alibaba Cloud Model Studio/DashScope explicit context cache by injecting `cache_control: { \"type\": \"ephemeral\" }` on up to 4 content blocks using the Context Cache format. The cache breakpoint strategy matches opencode's main provider flow: the first 2 system messages plus the last 2 non-system messages. Marked string content is converted to text content part arrays for `system` / `user` / `assistant` / `tool` messages; existing array content is marked on the last part. Set this to `false` when the model already supports implicit caching, or when the upstream does not accept this explicit-cache extension field. Set this to `true` for non-DashScope providers that support the same explicit-cache extension. Applied on both `/v1/messages` and `/v1/chat/completions` routes.\n    - `supportPdf` (optional): Controls whether the model supports PDF/document content. Defaults to `false`; unsupported PDFs are converted to a text notice. Set it to `true` to send PDF/document blocks as OpenAI Chat Completions file parts.\n    - `toolContentSupportType` (optional): Tool result content capabilities for that model, as an array of `array`, `image`, and `pdf`. Provider routes default to string-only tool content when omitted. If `supportPdf` is `true` but this list does not include `pdf`, file parts in tool results are moved to user role messages. This provider default does not change the Copilot main flow, which continues to support array + image and not PDF.\n    - `type` (optional): Per-model override of the provider protocol type. Supports `anthropic`, `openai-compatible`, and `openai-responses`. When set, the provider's `/v1/messages` route uses this model's type instead of the provider-level type for request routing, auth header resolution, and upstream endpoint selection. This is useful for providers like OpenCode Go whose upstream supports both OpenAI-compatible and Anthropic Messages APIs for different models. When the type is overridden, the auth header is resolved from the overridden type's default (Anthropic defaults to `x-api-key`; OpenAI-compatible/Responses default to `authorization`).\n\n  Example DashScope model settings:\n  ```json\n  {\n    \"providers\": {\n      \"dashscope\": {\n        \"type\": \"openai-compatible\",\n        \"enabled\": true,\n        \"baseUrl\": \"https://dashscope.aliyuncs.com/compatible-mode\",\n        \"apiKey\": \"sk-your-dashscope-key\",\n        \"pricingCurrency\": \"CNY\",\n        \"models\": {\n          \"qwen3.7-plus\": {\n            \"temperature\": 1,\n            \"topP\": 0.95,\n            \"topK\": 20,\n            \"extraBody\": {\n              \"preserve_thinking\": true\n            }\n          },\n          \"glm-5.1\": {\n            \"temperature\": 0.7,\n            \"topP\": 0.95,\n            \"contextCache\": true,\n            \"pricing\": {\n              \"tiers\": [\n                {\n                  \"maxInputTokens\": 32000,\n                  \"input\": 6,\n                  \"cachedInput\": 1.2,\n                  \"explicitCachedInput\": 0.6,\n                  \"cacheCreationInput\": 7.5,\n                  \"output\": 24\n                },\n                {\n                  \"maxInputTokens\": 200000,\n                  \"input\": 8,\n                  \"cachedInput\": 1.6,\n                  \"explicitCachedInput\": 0.8,\n                  \"cacheCreationInput\": 10,\n                  \"output\": 28\n                }\n              ]\n            },\n            \"extraBody\": {\n              \"preserve_thinking\": true\n            }\n          }\n        }\n      }\n    }\n  }\n  ```\n  Built-in token prices cover Codex GPT models in USD, DashScope `qwen3.7-max`, `qwen3.7-plus`, `glm-5.1`, `glm-5.2` in CNY, DeepSeek `deepseek-v4-flash`, `deepseek-v4-pro`, `deepseek-chat`, `deepseek-reasoner` in CNY, and OpenCode Go models (`glm-5.2`, `deepseek-v4-flash`, `deepseek-v4-pro`, `kimi-k2.7-code`, `mimo-v2.5`, `mimo-v2.5-pro`, `qwen3.7-plus`, `qwen3.7-max`, `minimax-m2.5`, `minimax-m3`) in USD. User `pricing` entries override built-ins. For DashScope, cached tokens are charged as explicit cache reads when the upstream usage includes `cache_creation_input_tokens`; otherwise `cachedInput` is used as the implicit cache read price. For DeepSeek, `prompt_cache_hit_tokens` map to cached input and `prompt_cache_miss_tokens` map to regular input.\n- **smallModel:** Fallback model used for tool-less warmup messages (e.g., Claude Code probe requests); defaults to gpt-5-mini.\n- **contextManagement:** Controls whether the proxy adds Responses API `context_management` compaction instructions. `messages` applies when Anthropic-style `/v1/messages` requests are translated to Responses API, including `openai-responses` provider message routes, and defaults to `true`. `responses` applies to native `/v1/responses` traffic, including `provider/model` aliases and the built-in `codex` provider, and defaults to `false`. Enable `responses` only after checking that your client supports context management compaction. When enabled, the request includes `context_management` in the body and keeps only the latest compaction carrier on follow-up turns. **Note:** Context management is forcibly disabled for GPT-5.6 and above models (e.g. `gpt-5.6-sol`, `gpt-5.6-terra`, `gpt-5.6-luna`) because enabling it breaks prompt cache hits on those models. This override takes precedence over the `contextManagement` and `modelResponsesApiCompactThresholds` settings.\n- **modelResponsesApiCompactThresholds:** Per-model Responses API `compact_threshold` overrides used when the proxy adds `context_management`. These values take precedence over the fallback threshold from `resolveResponsesCompactThreshold` (`max_prompt_tokens * ratio`, or the default fallback). Defaults set `gpt-5.4` and `gpt-5.5` to `217600` (`272000 * 0.8`), and `gpt-5.6-sol`, `gpt-5.6-terra`, `gpt-5.6-luna` to `231200` (`272000 * 0.85`). Models not listed continue to use the normal fallback logic.\n- **modelReasoningEfforts:** Per-model fallback reasoning effort for `/v1/messages` requests. It is used only when the request does not provide `output_config.effort`.\n  - **Priority:** request `output_config.effort` > `modelReasoningEfforts[model]` > built-in default (`xhigh` for GPT-5.3+ models, otherwise `high`).\n  - **Forwarding:** the resolved value remains `output_config.effort` for the Copilot native Messages API and becomes `reasoning.effort` when translated to the Responses API.\n  - **Configuration values:** `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`.\n- **useMessagesApi:** When `true`, Claude-family models that support Copilot's native `/v1/messages` endpoint will use the Messages API; otherwise they fall back to `/chat/completions`. Set to `false` to disable Messages API routing and always use `/chat/completions`. Defaults to `true`.\n- **useResponsesApiWebSocket:** When `true`, Responses API requests use Copilot's websocket transport for models that advertise `ws:/responses`; models that only advertise `/responses` continue to use HTTP. Set to `false` to disable websocket routing and use HTTP `/responses` whenever the selected model supports it. Defaults to `true`.\n- **useResponsesApiWebSearch:** When `true`, the server keeps Responses API tools with `type: \"web_search\"` and forwards them upstream. Set to `false` to strip those tools from `/responses` payloads. Defaults to `true`.\n- **messageApiWebSearchModel:** Global fallback model used when a top-level Copilot `/v1/messages` request contains only the server-side `web_search` tool. Defaults to `gpt-5-mini`. If the value is a `provider/model` alias, the request is routed into that provider's Messages API path with the provider prefix stripped. For Copilot GPT models, web search runs through `/responses`. Mixed `web_search` plus custom tools are not supported and the server-side `web_search` tool is stripped.\n- **claudeTokenMultiplier:** Multiplier applied to the fallback GPT-tokenizer estimate for Claude `/v1/messages/count_tokens` requests. Defaults to `1.15`. Increase it if your client is still compacting too late. This setting is only used when the proxy is estimating Claude tokens locally; if `anthropicApiKey` is configured and Anthropic token counting succeeds, the exact Anthropic count is returned instead.\n- **anthropicApiKey:** Anthropic API key used to forward Claude `/v1/messages/count_tokens` requests to Anthropic's real token counting endpoint, which returns exact counts instead of GPT tokenizer estimates. Can also be set via the `ANTHROPIC_API_KEY` environment variable. If not set, or if the upstream call fails, token counting falls back to local GPT tokenizer estimation controlled by `claudeTokenMultiplier`.\n\nEdit this file to customize prompts or swap in your own fast model. Restart the server (or rerun the command) after changes so the cached config is refreshed.\n\n## API Authentication\n\n- **Protected non-admin routes:** All routes except `/`, `/usage-viewer`, and `/usage-viewer/` require authentication when `auth.apiKeys` is configured and non-empty.\n- **Admin routes:** All `/admin/*` routes require `auth.adminApiKey`. If it is missing, the server generates one at startup and persists it to `config.json` before serving requests.\n- **Allowed auth headers:**\n  - `x-api-key: <your_key>`\n  - `Authorization: Bearer <your_key>`\n- **CORS preflight:** `OPTIONS` requests are always allowed.\n- **When no regular keys are configured:** Non-admin routes continue to allow requests. This does not apply to `/admin/*`, which only accepts `auth.adminApiKey`.\n\nExample request for a regular protected route:\n\n```sh\ncurl http://localhost:4141/v1/models \\\n  -H \"x-api-key: your_api_key\"\n```\n\nExample request for an admin route:\n\n```sh\ncurl http://localhost:4141/admin/config/model-mappings \\\n  -H \"x-api-key: your_admin_api_key\"\n```\n\n## API Endpoints\n\nThe server exposes several OpenAI- and Anthropic-compatible endpoints. Requests can target GitHub Copilot, the built-in `codex` provider, or configured providers depending on the selected model and `provider/model` alias.\n\n### OpenAI Compatible Endpoints\n\nThese endpoints mimic the OpenAI API structure.\n\n| Endpoint                    | Method | Description                                                      |\n| --------------------------- | ------ | ---------------------------------------------------------------- |\n| `POST /v1/responses`        | `POST` | OpenAI Most advanced interface for generating model responses. Supports `provider/model` aliases for `openai-responses` providers. |\n| `POST /v1/chat/completions` | `POST` | Creates a model response for the given chat conversation. Supports `provider/model` aliases for `openai-compatible` providers and can be used without Copilot when the target provider is configured. |\n| `GET /v1/models`            | `GET`  | Lists Copilot models plus enabled provider models using `provider/model-id` IDs. Requests from Codex clients (`User-Agent` beginning with `codex`) are forwarded to the Codex Models upstream. |\n| `POST /v1/embeddings`       | `POST` | Creates an embedding vector representing the input text.         |\n\n### Codex Backend Proxy Endpoints\n\nThese endpoints require an active Codex login. Each endpoint is available both without a version prefix and under `/v1`.\n\n| Endpoint | Method | Description |\n| --- | --- | --- |\n| `POST /alpha/search`<br>`POST /v1/alpha/search` | `POST` | Transparently forwards the JSON body and query parameters to the Codex Alpha Search upstream. |\n| `POST /images/generations`<br>`POST /v1/images/generations` | `POST` | Forwards a JSON image generation request to the Codex Images upstream. When the request omits `Content-Type`, the gateway defaults it to `application/json`. |\n| `POST /images/edits`<br>`POST /v1/images/edits` | `POST` | Forwards an image edit request to the Codex Images upstream. Send this request as `multipart/form-data` and let the HTTP client generate the `boundary`; the gateway preserves the incoming content type and streams the upload body. |\n\nFor every endpoint above, the gateway replaces client authorization and account headers with the active Codex login, preserves query parameters and compatible request headers, and returns the upstream status, headers, and body.\n\n### Anthropic Compatible Endpoints\n\nThese endpoints are designed to be compatible with the Anthropic Messages API.\n\n| Endpoint                         | Method | Description                                                  |\n| -------------------------------- | ------ | ------------------------------------------------------------ |\n| `POST /v1/messages`              | `POST` | Creates a model response for a given conversation. Supports `provider/model` aliases for configured providers, including translation through `openai-compatible` providers. |\n| `POST /v1/messages/count_tokens` | `POST` | Calculates the number of tokens for a given set of messages. Supports `provider/model` aliases for configured providers. |\n| `POST /:provider/v1/messages`       | `POST` | Proxies Anthropic Messages requests to the configured Anthropic provider, translates them through an OpenAI-compatible provider, or translates them through an OpenAI Responses provider. |\n| `GET /:provider/v1/models`          | `GET`  | Proxies model listing requests to the configured provider.   |\n| `POST /:provider/v1/messages/count_tokens` | `POST` | Calculates tokens locally for provider route requests. |\n\n### Usage Monitoring Endpoints\n\nNew endpoints for monitoring your Copilot usage and quotas.\n\n| Endpoint     | Method | Description                                                  |\n| ------------ | ------ | ------------------------------------------------------------ |\n| `GET /usage` | `GET`  | Get detailed Copilot usage statistics and quota information. |\n| `GET /token` | `GET`  | Get the current Copilot token being used by the API.         |\n\n### Admin / Configuration Endpoints\n\nThese endpoints are reserved for local administrative actions and only accept `auth.adminApiKey`.\n\n| Endpoint                              | Method | Description                                                                 |\n| ------------------------------------- | ------ | --------------------------------------------------------------------------- |\n| `GET /admin/config/model-mappings`    | `GET`  | Returns the current `config.json` path and the active `modelMappings` map.  |\n| `POST /admin/config/model-mappings`   | `POST` | Updates only the `modelMappings` field in `config.json` and returns it back. |\n\n## Example Usage\n\nCommon `npx` commands:\n\n```sh\n# Start the gateway\nnpx @jeffreycao/copilot-api@latest start\n\n# Start on a custom port with verbose logging\nnpx @jeffreycao/copilot-api@latest start --port 8080 --verbose\n\n# Run the auth flow\nnpx @jeffreycao/copilot-api@latest auth login\n\n# Configure a third-party provider, then run without GitHub Copilot\nnpx @jeffreycao/copilot-api@latest auth login --provider dashscope\nnpx @jeffreycao/copilot-api@latest start\n\n# Print debug information as JSON\nnpx @jeffreycao/copilot-api@latest debug --json\n\n# Run the published CLI with Bun instead of Node.js\nbunx --bun @jeffreycao/copilot-api@latest start\n```\n\nOpenAI-compatible provider examples after configuring `dashscope`:\n\n```sh\ncurl http://localhost:4141/v1/chat/completions \\\n  -H \"content-type: application/json\" \\\n  -d '{\"model\":\"dashscope/qwen3.6-plus\",\"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]}'\n\ncurl http://localhost:4141/dashscope/v1/messages \\\n  -H \"content-type: application/json\" \\\n  -d '{\"model\":\"qwen3.6-plus\",\"max_tokens\":1024,\"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]}'\n```\n\n## Usage Tips\n\n### CLAUDE.md or AGENTS.md Recommended Content\n\nTo add these reminders manually, include the following in `CLAUDE.md` for Claude Code, or `AGENTS.md` for opencode/codex:\n\n```\n- Prohibited from directly asking questions to users, MUST use question tool.\n- Once you can confirm that the task is complete, MUST use question tool to make user confirm. The user may respond with feedback if they are not satisfied with the result, which you can use to make improvements and try again, after try again, MUST use question tool to make user confirm again.\n```\n"}, "c6f762a44b8b8eefe09eff16586cfc6706f5eb14": {"t": 1785765558.0222952, "n": 47671, "h": "c3189acd507877b4", "c": "# Copilot API Proxy\n\nEnglish | [简体中文](./README.zh-CN.md)\n\n## Important Notes\n\n> [!IMPORTANT]\n> **Before using, please be aware of the following:**\n>\n> 1. **Claude Code configuration:** When using with Claude Code, please configure the model ID as `claude-opus-4-8`. Example claude `settings.json` see [Manual Configuration with `settings.json`](#manual-configuration-with-settingsjson). \n>\n> 2. **Built-in `copilot`, `codex` and third-party providers:** Run `npx @jeffreycao/copilot-api@latest auth` and choose `copilot`, `codex`, `deepseek`, `custom`, or other providers.\n>\n> 3. **Note:** See [GitHub Copilot Security Notice](./NOTICE.md#github-copilot-security-notice) for the warning removed from the README header.\n\n---\n\n## Project Overview\n\nA small AI gateway that can use GitHub Copilot, the built-in `codex` provider, or configured third-party providers such as DashScope. GitHub Copilot is optional: if no GitHub token is available, the server can still start in provider-only mode as long as at least one enabled provider is configured.\n\nThe gateway exposes OpenAI- and Anthropic-compatible APIs from one local endpoint, so tools like [Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview), OpenCode, Codex, and OpenAI-compatible clients can share the same local server.\n\nOn the GitHub Copilot path, the gateway prefers Copilot's native Anthropic-style Messages API when available, preserving more Claude-native behavior for tool-heavy workflows.\n\n## Features\n\n- **OpenAI and Anthropic compatibility**: Serve `/v1/responses`, `/v1/chat/completions`, `/v1/models`, `/v1/embeddings`, and `/v1/messages` from one local gateway.\n- **Copilot is optional**: Use GitHub Copilot when credentials are present, or run the server with only configured providers.\n- **One gateway for Copilot, `codex`, and external providers**: Route GitHub Copilot, the built-in `codex` provider, and configured third-party providers behind the same endpoint.\n- **Standalone third-party providers**: Configure providers such as DashScope, DeepSeek, OpenRouter, or a custom provider and start the gateway without a GitHub Copilot login.\n- **OpenAI-compatible providers on chat and Messages APIs**: `openai-compatible` providers can serve top-level `/v1/chat/completions` through `model: \"provider/model\"` and Anthropic-style `/v1/messages` through request/response translation.\n- **Agent-friendly Claude handling on Copilot**: Prefer native `/v1/messages` when available, preserve Claude-style tool flows, support Anthropic beta features, Claude WebSearch through Responses-capable models, and keep subagent/session markers intact.\n- **Claude Code and OpenCode integration**: Works with Claude Code and OpenCode, including direct Anthropic-compatible usage through `@ai-sdk/anthropic`.\n- **Flexible auth and deployment options**: Supports interactive login or direct tokens, individual/business/enterprise plans, GitHub Enterprise, opencode OAuth, and custom data directories.\n- **Multi-provider routing**: Expose provider-specific `/:provider/...` routes or use `model: \"provider/model\"` on the top-level API.\n\n## Prerequisites\n\n- Bun (>= 1.2.x)\n- Node.js if you plan to run the published CLI with `npx`\n- GitHub account with Copilot subscription only if you want to use the GitHub Copilot provider\n- An API key or OAuth login for at least one configured provider if you want to run without GitHub Copilot\n\n## Installation\n\nTo install dependencies, run:\n\n```sh\nbun install\n```\n\nTo start the server directly from source:\n\n```sh\nbun run start start\n```\n\n## Running from Source\n\nThe project can be run from source in several ways:\n\n### Development Mode\n\n```sh\nbun run dev start\n```\n\n### Production Mode\n\n```sh\nbun run start start\n```\n\n## Using with npx\n\nYou can run the project directly using npx:\n\n> [!IMPORTANT]\n> Token usage storage uses Node's built-in `node:sqlite` module when running with `npx`. It is enabled on Node.js >= 22.13.0. On Node.js < 22.13.0, the CLI still starts, but token usage storage is disabled.\n>\n> If you want token usage storage without upgrading Node.js, run the published CLI with Bun instead: `bunx --bun @jeffreycao/copilot-api@latest start`.\n\n```sh\nnpx @jeffreycao/copilot-api@latest start\n```\n\nWith options:\n\n```sh\nnpx @jeffreycao/copilot-api@latest start --port 8080\n```\n\nFor authentication or provider configuration only:\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth\n```\n\nTo run without GitHub Copilot, configure at least one provider first, then start the server normally:\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth login --provider dashscope\nnpx @jeffreycao/copilot-api@latest start\n```\n\n## Using with Docker\n\nBuild the image:\n\n```sh\ndocker build -t copilot-api .\n```\n\nRun the container with a bind mount so auth data survives restarts:\n\n```sh\nmkdir -p ./copilot-data\ndocker run -p 4141:4141 -v $(pwd)/copilot-data:/root/.local/share/copilot-api copilot-api\n```\n\nThis stores GitHub auth data, provider config, and other gateway state in `./copilot-data` on the host, mapped to `/root/.local/share/copilot-api` in the container.\n\nOr pass a GitHub token directly:\n\n```sh\ndocker run -p 4141:4141 -e GH_TOKEN=your_github_token_here copilot-api\n```\n\n## Electron Desktop App\n\nIf you prefer a GUI, this repository also includes an Electron desktop app in `desktop/`. It supports GitHub Copilot sign-in, OpenAI Codex OAuth, and API-key configuration for DeepSeek, DashScope, OpenRouter, or a custom provider. After authorization or provider configuration, it can start and stop the local proxy with one click and shows the local endpoint, auth header, available models, usage, and logs in the app.\n\nThe settings screen also exposes `OAuth App`, `API Home`, `Enterprise URL`, verbose logging, and minimize-to-tray. Desktop packages are published in GitHub Releases:\n\nhttps://github.com/caozhiyuan/copilot-api/releases\n\nDownload the installer for your platform, authorize or configure a provider inside the app, choose a port, start the server, then point your client at the local endpoint shown in the app. Packaged desktop builds use the bundled Electron runtime, so normal desktop usage does not require installing Node.js separately. Token usage history is enabled when that bundled runtime supports SQLite.\n\nThe desktop app's Advanced Config page reads and writes the shared model mappings through `GET/POST /admin/config/model-mappings`. The same mappings apply across `POST /v1/messages`, `POST /v1/messages/count_tokens`, `POST /v1/responses`, and `POST /v1/chat/completions` instead of being split per interface. It uses `auth.adminApiKey` instead of the regular `auth.apiKeys`, and the app reads that key directly from `config.json` after the server has generated it on startup.\n\n### Desktop App Screenshots\n\nMain dashboard, token usage breakdown in the bundled Electron app:\n\n<p align=\"center\">\n  <img src=\"./docs/screenshots/desktop-dashboard.png\" alt=\"Copilot API desktop app dashboard\" width=\"49%\" />\n  <img src=\"./docs/screenshots/desktop-token-usage.png\" alt=\"Copilot API desktop app token usage view\" width=\"49%\" />\n</p>\n\n## Using with Claude Code\n\nThis AI gateway can be used to power [Claude Code](https://docs.anthropic.com/en/claude-code), an experimental conversational AI assistant for developers from Anthropic.\n\nThere are two ways to configure Claude Code to use this AI gateway:\n\n### Interactive Setup with `--claude-code` flag\n\nTo get started, run the `start` command with the `--claude-code` flag:\n\n```sh\nnpx @jeffreycao/copilot-api@latest start --claude-code\n```\n\nYou will be prompted to select a primary model and a \"small, fast\" model for background tasks. After selecting the models, a command will be copied to your clipboard. This command sets the necessary environment variables for Claude Code to use the gateway.\n\nPaste and run this command in a new terminal to launch Claude Code.\n\n### Manual Configuration with `settings.json`\n\nAlternatively, you can configure Claude Code by creating a `.claude/settings.json` file in your project's root directory. This file should contain the environment variables needed by Claude Code. This way you don't need to run the interactive setup every time.\n\nHere is an example `.claude/settings.json` file:\n\n```json\n{\n  \"env\": {\n    \"ANTHROPIC_BASE_URL\": \"http://localhost:4141\",\n    \"ANTHROPIC_AUTH_TOKEN\": \"dummy\",\n    \"ANTHROPIC_MODEL\": \"deepseek/deepseek-v4-pro\",\n    \"ANTHROPIC_DEFAULT_SONNET_MODEL\": \"deepseek/deepseek-v4-pro\",\n    \"ANTHROPIC_DEFAULT_HAIKU_MODEL\": \"deepseek/deepseek-v4-flash\",\n    \"DISABLE_NON_ESSENTIAL_MODEL_CALLS\": \"1\",\n    \"CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC\": \"1\",\n    \"CLAUDE_CODE_ATTRIBUTION_HEADER\": \"0\",\n    \"CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION\": \"false\",\n    \"CLAUDE_CODE_DISABLE_TERMINAL_TITLE\": \"true\",\n    \"CLAUDE_CODE_ENABLE_AWAY_SUMMARY\": \"0\"\n  },\n  \"permissions\": {\n    \"deny\": [\n      \"mcp__ide__executeCode\"\n    ]\n  }\n}\n```\n\n- Replace `ANTHROPIC_MODEL`, `ANTHROPIC_DEFAULT_OPUS_MODEL`, `ANTHROPIC_DEFAULT_SONNET_MODEL`, and `ANTHROPIC_DEFAULT_HAIKU_MODEL` according to your needs. After configuration, please install the claude code plugin [Plugin Integrations](#plugin-integrations).  \n- Setting CLAUDE_CODE_ATTRIBUTION_HEADER to 0 can prevent Claude code from adding billing and version information in system prompts, thereby avoiding prompt cache invalidation.\n- Turning off CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION and CLAUDE_CODE_ENABLE_AWAY_SUMMARY can prevent quota from being consumed unnecessarily.\n- Claude Code WebSearch is supported for pure search requests. For Copilot, keep the global `messageApiWebSearchModel` set to a Responses-capable GPT model or a `provider/model` alias. For provider routes, use a native Anthropic provider or an `openai-responses` provider. Add `WebSearch` to `permissions.deny` only if you want to forbid this traffic.\n- If using a non-Claude model, do not enable ENABLE_TOOL_SEARCH. If using the Claude model, can enable ENABLE_TOOL_SEARCH. The current Claude Code uses the client tool search mode. In this mode, loading defer tools requires an additional request each time.\n- `CLAUDE_CODE_AUTO_COMPACT_WINDOW`: Set the context capacity in tokens used for auto-compaction calculations. Defaults to the model's context window: 200K for standard models or 1M for extended context models. Use a lower value like `500000` on a 1M model (e.g., `claude-opus-4-6[1m]`) to treat the window as 500K for compaction purposes. The value is capped at the model's actual context window. `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` is applied as a percentage of this value. Setting this variable decouples the compaction threshold from the status line's `used_percentage`, which always uses the model's full context window.\n\nYou can find more options here: [Claude Code settings](https://docs.anthropic.com/en/docs/claude-code/settings#environment-variables)\n\nYou can also read more about IDE integration here: [Add Claude Code to your IDE](https://docs.anthropic.com/en/docs/claude-code/ide-integrations)\n\n## Using with OpenCode\n\nOpenCode already has a direct GitHub Copilot provider. Use this section when you want OpenCode to point at this AI gateway through `@ai-sdk/anthropic` and reuse the agent behaviors described earlier in this README.\n\n### Minimal setup\n\nStart the AI gateway with the OpenCode OAuth app:\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth --oauth-app=opencode\nnpx @jeffreycao/copilot-api@latest start\n```\n\nThen point OpenCode at the gateway with `@ai-sdk/anthropic`.\n\nExample `~/.config/opencode/opencode.json`:\n\n```json\n{\n  \"$schema\": \"https://opencode.ai/config.json\",\n  \"provider\": {\n    \"local\": {\n      \"npm\": \"@ai-sdk/anthropic\",\n      \"name\": \"My Local\",\n      \"options\": {\n        \"baseURL\": \"http://localhost:4141/v1\",\n        \"apiKey\": \"dummy\"\n      },\n      \"models\": {\n        \"gpt-5.4\": {\n          \"name\": \"gpt-5.4\",\n          \"modalities\": {\n            \"input\": [\"text\", \"image\"],\n            \"output\": [\"text\"]\n          },\n          \"limit\": {\n            \"context\": 400000,\n            \"input\": 272000,\n            \"output\": 128000\n          }\n        },\n        \"claude-sonnet-4.6\": {\n          \"id\": \"claude-sonnet-4.6\",\n          \"name\": \"claude-sonnet-4.6\",\n          \"modalities\": {\n            \"input\": [\"text\", \"image\"],\n            \"output\": [\"text\"]\n          },          \n          \"limit\": {\n            \"context\": 200000,\n            \"output\": 32000\n          },\n          \"options\": {\n            \"thinking\": {\n              \"type\": \"adaptive\"\n            },\n            \"effort\": \"max\"\n          }\n        }\n      }\n    }\n  }\n}\n```\n\nWhy these fields matter:\n\n- `npm: \"@ai-sdk/anthropic\"` is the important part. OpenCode will speak Anthropic Messages semantics to this AI gateway instead of flattening everything into OpenAI Chat Completions.\n- `options.baseURL` should be `http://localhost:4141/v1`; the Anthropic SDK will append `/messages`, `/models`, and `/messages/count_tokens` automatically.\n- If you enable `auth.apiKeys` in this AI gateway, replace `dummy` with a real key. Otherwise any placeholder value is fine.\n\n## Using with Codex\n\nThis AI gateway can also power Codex.\n\n### Codex `config.toml` Reference\n\nAdd the following `[model_providers.copilot_api]` section to your Codex `~/.codex/config.toml`:\n\n```toml\nmodel_provider = \"copilot_api\"\nmodel_reasoning_summary = \"auto\"\nmodel_context_window = 272000\nmodel_auto_compact_token_limit = 244800\n\n[model_providers.copilot_api]\nname = \"OpenAI\"\nbase_url = \"http://localhost:4141\"\nenv_key = \"GITHUB_COPILOT_API_KEY\"\nrequires_openai_auth = true\nsupports_websockets = false\nwire_api = \"responses\"\nrequest_max_retries = 3\nstream_max_retries = 1\nstream_idle_timeout_ms = 300000\n\n[features]\nremote_compaction_v2 = true\n\n[analytics]\nenabled = false\n```\n\n> [!NOTE]\n> This configuration is specific to Codex and the GitHub Copilot provider. `name` must be set to `\"OpenAI\"`. It can help mitigate Codex local compact cache miss issues. \n\n## GPT Tool Search\n\nFor GPT Responses models such as `gpt-5.4+`, this AI gateway can expose Responses `tool_search` through a small MCP bridge. The same bridge can be used by Claude Code and opencode, as long as the client loads MCP servers and sends Anthropic Messages traffic through this gateway.\n\nDo not set Claude Code's native `ENABLE_TOOL_SEARCH` for GPT models. That flag enables Claude Code's own client-side tool search mode, and it may stop forwarding deferred tool definitions. This gateway needs the full tool definitions so it can keep the small always-loaded tool set eager and translate every other tool into Responses deferred namespaces.\n\nIf you install `tool-search@copilot-api-marketplace`, Claude Code receives this MCP bridge automatically and you can skip the manual Claude Code MCP setup below.\n\nAdd the tool search bridge to the MCP config used by Claude Code:\n\n```json\n{\n  \"mcpServers\": {\n    \"tool_search\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@jeffreycao/copilot-api@latest\", \"mcp\"]\n    }\n  }\n}\n```\n\nAdd the tool search bridge to the MCP config used by opencode:\n\n```json\n{\n  \"mcp\": {\n    \"tool_search\": {\n      \"type\": \"local\",\n      \"command\": [\"npx\", \"-y\", \"@jeffreycao/copilot-api@latest\", \"mcp\"]\n    }\n  }\n}\n```\n\nFor local development, use `bun` as the command and `[\"run\", \"./src/main.ts\", \"mcp\"]` as the args.\n\nInternally, the gateway now configures OpenAI Responses `tool_search` in client-executed mode. Deferred tools are still exposed as searchable namespaces, but the model is explicitly asked to return the exact deferred tool names it wants to load next.\n\nThe bridge uses direct tool selection, not query search. Its tool input is `names`, a comma-separated list of exact deferred tool names, for example `TaskList,TaskGet,mcp__fetch__fetch`.\n\n## Plugin Integrations\n\nPlugin integrations are available for Claude Code and opencode.\n\n#### Claude Code plugin integration (marketplace-based)\n\nThe Claude Code integration is packaged as two plugins:\n\n- `agent-inject` injects `__SUBAGENT_MARKER__...` on `SubagentStart`, so the gateway can infer `x-initiator: agent`.\n- `tool-search` registers the `tool_search` MCP bridge used for GPT Responses deferred tool loading.\n\n- Marketplace catalog in this repository: `.claude-plugin/marketplace.json`\n- Plugin sources in this repository: `plugin/claude/agent-inject`, `plugin/claude/tool-search`\n\nAdd the marketplace remotely:\n\n```sh\n/plugin marketplace add https://github.com/caozhiyuan/copilot-api.git\n```\n\nInstall the plugins from the marketplace:\n\n```sh\n/plugin install agent-inject@copilot-api-marketplace\n/plugin install tool-search@copilot-api-marketplace\n```\n\nAfter installation, `agent-inject` injects `__SUBAGENT_MARKER__...` on `SubagentStart`, and the gateway uses it to infer `x-initiator: agent`.\n\nThe `agent-inject` plugin also registers a `UserPromptSubmit` hook that returns `{\"continue\": true}`, and it can inject `SessionStart` reminder rules through environment variables:\n\n- `CLAUDE_PLUGIN_ENABLE_QUESTION_RULES=1` enables the two reminders about using the `question` tool automatically for Claude Code. Alternatively, you can add the same reminders manually in `CLAUDE.md`; see [CLAUDE.md or AGENTS.md Recommended Content](#claudemd-or-agentsmd-recommended-content).\n- `CLAUDE_PLUGIN_ENABLE_NO_BACKGROUND_AGENTS_RULE=1` enables the `run_in_background: true` avoidance reminder for agent hooks.\n\nThe `tool-search` plugin bundles the same MCP bridge described in [GPT Tool Search](#gpt-tool-search), so Claude Code users do not need to add the `tool_search` server manually when they install that plugin.\n\n#### Opencode plugin\n\nThe subagent marker producer is packaged as an opencode plugin located at `plugin/opencode/subagent-marker.js`.\n\n**Installation:**\n\nCopy the plugin file to your opencode plugins directory:\n\n```sh\n# Clone or download this repository, then copy the plugin\ncp plugin/opencode/subagent-marker.js ~/.config/opencode/plugins/\n```\n\nOr manually create the file at `~/.config/opencode/plugins/subagent-marker.js` with the plugin content.\n\n**Features:**\n\n- Tracks sub-sessions created by subagents\n- Automatically prepends a marker system reminder (`__SUBAGENT_MARKER__...`) to subagent chat messages\n- Sets `x-session-id` header for session tracking\n- Enables the gateway to infer `x-initiator: agent` for subagent-originated requests\n\nThe plugin hooks into `session.created`, `session.deleted`, `chat.message`, and `chat.headers` events to provide seamless subagent marker functionality.\n\n## Using the Usage Viewer\n\nAfter starting the server, a URL to the Copilot Usage Dashboard will be displayed in your console. This dashboard is a web interface for monitoring your API usage.\n\n1.  Start the server. For example, using npx:\n    ```sh\n    npx @jeffreycao/copilot-api@latest start\n    ```\n2.  The server will output a URL to the usage viewer. Copy and paste this URL into your browser. It will look something like this:\n    `http://localhost:4141/usage-viewer?endpoint=http://localhost:4141/usage`\n    - If you use the `start.bat` script on Windows, this page will open automatically.\n\nThe dashboard provides a user-friendly interface to view your Copilot usage data:\n\n> Token usage history requires Bun or Node.js >= 22.13.0. On Node.js < 22.13.0, the server runs normally but token usage storage is disabled.\n\n- **API Endpoint URL**: The dashboard is pre-configured to fetch data from your local server endpoint via a URL query parameter. You can manually switch this to any other compatible API endpoint.\n- **x-api-key Authentication**: If API Key authentication is enabled, you can provide the `x-api-key` request header. The key is persisted in the browser's local storage.\n- **Period Selector**: Choose from Day, Week, or Month time ranges. The URL query parameter updates automatically when you switch, making it easy to bookmark and share.\n- **Fetch Data**: Click the \"Refresh\" button to load or refresh the usage data. The dashboard also fetches data automatically on page load.\n- **Copilot Quotas**: View quota usage for services such as Chat and Completions via progress bars. Hover over a card to see used/remaining details.\n- **Token Usage Metric Cards**: See a summary of Total, Input, Output, Cache Read, Cache Write, Requests, and estimated cost for the current period.\n- **Trend Chart (Week / Month)**: An interactive line chart with model and metric filters. Click a data point to inspect the usage breakdown for a specific day.\n- **Model Breakdown Table**: A per-model summary of requests, input/output/cache tokens, and estimated cost for the selected period.\n- **Request Events (Paginated)**: A time-sorted list of request event records with pagination support, showing timestamps, models, request IDs, and token counts.\n- **Detailed Information**: See the full JSON response from the API for a detailed breakdown of all available usage statistics.\n- **URL-based Configuration**: You can also specify the API endpoint and period directly via `endpoint` and `period` query parameters. For example:\n  `http://localhost:4141/usage-viewer?endpoint=http://your-api-server/usage&period=week`\n\n### Usage Viewer Screenshot\n\n<p align=\"center\">\n  <img src=\"./docs/screenshots/usage-viewer.png\" alt=\"Copilot API usage viewer\" width=\"900\" />\n</p>\n\n## Command Structure\n\nCopilot API now uses a subcommand structure with these main commands:\n\n- `start`: Start the gateway server. If a GitHub token is available, the server starts with Copilot enabled. If no GitHub token is available, it starts in provider-only mode when at least one enabled provider exists; otherwise it guides you through provider setup.\n- `auth`: Run provider login or configuration without starting the server. Use it for GitHub Copilot login, Codex OAuth, or third-party provider API key setup.\n- `debug`: Display diagnostic information including version, runtime details, file paths, and authentication status. Useful for troubleshooting and support.\n\n## Command Line Options\n\n### Global Options\n\nThe following options can be used with any subcommand. When passing them before the subcommand, use the `--key=value` form:\n\n| Option            | Description                                            | Default | Alias |\n| ----------------- | ------------------------------------------------------ | ------- | ----- |\n| --api-home        | Path to the API home directory (sets COPILOT_API_HOME) | none    | none  |\n| --oauth-app       | OAuth app identifier (sets COPILOT_API_OAUTH_APP)      | none    | none  |\n| --enterprise-url  | Enterprise URL for GitHub (sets COPILOT_API_ENTERPRISE_URL) | none | none |\n\n### Start Command Options\n\nThe following command line options are available for the `start` command:\n\n| Option         | Description                                                                   | Default    | Alias |\n| -------------- | ----------------------------------------------------------------------------- | ---------- | ----- |\n| --port         | Port to listen on                                                             | 4141       | -p    |\n| --verbose      | Enable verbose logging                                                        | false      | -v    |\n| --github-token | Provide GitHub token directly (must be generated using the `auth` subcommand) | none       | -g    |\n| --claude-code  | Generate a command to launch Claude Code with Copilot API config              | false      | -c    |\n| --show-token   | Show GitHub and Copilot tokens on fetch and refresh                           | false      | none  |\n| --proxy-env    | Initialize proxy from environment variables                                   | false      | none  |\n\n### Auth Command Options\n\n| Option       | Description               | Default | Alias |\n| ------------ | ------------------------- | ------- | ----- |\n| --provider   | Provider to log in with or configure (`copilot`, `codex`, `opencode-go`, `deepseek`, `dashscope`, `openrouter`, or `custom`) | prompt | none |\n| --verbose    | Enable verbose logging    | false   | -v    |\n| --show-token | Show GitHub token on auth | false   | none  |\n\nUse `copilot-api auth login --provider copilot` only when you want to enable the GitHub Copilot provider. Copilot is not required for `codex` or third-party provider-only usage.\n\nUse `copilot-api auth login --provider deepseek`, `--provider dashscope`, `--provider openrouter`, or `--provider opencode-go` to add or update those common third-party providers from the CLI. DeepSeek prompts for masked `apiKey`, provider `type` (default `anthropic`), and `baseUrl` defaulting to `https://api.deepseek.com/anthropic`. DashScope prompts for masked `apiKey`, provider `type` (default `openai-compatible`), and prefilled `baseUrl`. OpenRouter prompts for masked `apiKey` and prefilled `baseUrl` only, and writes `type: \"anthropic\"`. OpenCode Go prompts for masked `apiKey` and prefilled `baseUrl` only, and writes `type: \"openai-compatible\"` (baseUrl `https://opencode.ai/zen/go`). After a provider is configured and enabled, `copilot-api start` can run without any GitHub token.\n\nUse `copilot-api auth login --provider custom` to add or update another third-party provider from the CLI. The command prompts for the provider name, supported type (`anthropic`, `openai-compatible`, or `openai-responses`), `baseUrl`, masked `apiKey`, and `authType`; `authType` may be left as the type default or set to `x-api-key` / `authorization`.\n\n### Debug Command Options\n\n| Option | Description               | Default | Alias |\n| ------ | ------------------------- | ------- | ----- |\n| --json | Output debug info as JSON | false   | none  |\n\n## Configuration (config.json)\n\n- **Location:** `~/.local/share/copilot-api/config.json` (Linux/macOS) or `%USERPROFILE%\\.local\\share\\copilot-api\\config.json` (Windows).\n- **Default shape:**\n  ```json\n  {\n    \"auth\": {\n      \"apiKeys\": [],\n      \"adminApiKey\": \"<auto-generated-on-startup>\"\n    },\n    \"providers\": {},\n    \"modelMappings\": {},\n    \"extraPrompts\": {\n      \"gpt-5-mini\": \"<built-in exploration prompt>\"\n    },\n    \"smallModel\": \"gpt-5-mini\",\n    \"contextManagement\": {\n      \"messages\": true,\n      \"responses\": false\n    },\n    \"modelResponsesApiCompactThresholds\": {\n      \"gpt-5.4\": 217600,\n      \"gpt-5.5\": 217600,\n      \"gpt-5.6-sol\": 231200,\n      \"gpt-5.6-terra\": 231200,\n      \"gpt-5.6-luna\": 231200\n    },\n    \"modelReasoningEfforts\": {\n      \"gpt-5-mini\": \"low\"\n    },\n    \"useMessagesApi\": true,\n    \"useResponsesApiWebSocket\": true,\n    \"useResponsesApiWebSearch\": true,\n    \"messageApiWebSearchModel\": \"gpt-5-mini\"\n  }\n  ```\n- **auth.apiKeys:** API keys used for request authentication on non-admin routes. Supports multiple keys for rotation. Requests can authenticate with either `x-api-key: <key>` or `Authorization: Bearer <key>`. If empty or omitted, authentication for non-admin routes is disabled.\n- **auth.adminApiKey:** Single admin key used only for `/admin/*` routes. If missing, the server generates a random key at startup and writes it back to `config.json`. Requests use the same `x-api-key` or `Authorization: Bearer` headers, but regular `auth.apiKeys` never grant access to `/admin/*`.\n- **modelMappings:** Exact `sourceModel -> targetModel` rewrites shared by top-level `POST /v1/messages`, `POST /v1/messages/count_tokens`, `POST /v1/responses`, and `POST /v1/chat/completions` requests. Omit it or leave it as `{}` to disable rewrites. Both the source and target must be non-empty strings. Targets can be regular model IDs or `provider/model` aliases such as `dashscope/qwen3.6-plus`, and the rewrite happens before provider alias parsing. These mappings are not split per interface. The admin endpoints `GET/POST /admin/config/model-mappings` read and update only this field.\n- **extraPrompts:** Map of `model -> prompt` appended to the first system prompt when translating Anthropic-style requests to Responses API. Use this to inject guardrails or guidance per model. Missing default entries are auto-added without overwriting your custom prompts. For GPT-5.3+ models (e.g. `gpt-5.3-codex`, `gpt-5.4`, `gpt-5.5`), a built-in commentary prompt is used as fallback when not explicitly configured. The built-in prompts enable phase-aware commentary, which lets the model emit a short user-facing progress update before tools or deeper reasoning.\n- **providers:** Global upstream provider map. Each provider key (for example `dashscope`) becomes a route prefix (`/dashscope/v1/messages`). Supports `type: \"anthropic\"`, `type: \"openai-compatible\"`, and `type: \"openai-responses\"`. Top-level clients can also use `model: \"dashscope/model-id\"` with `/v1/messages`, `/v1/messages/count_tokens`, `/v1/responses`, and `/v1/chat/completions`; the gateway strips the `dashscope/` prefix before forwarding upstream. `openai-compatible` providers support both chat and Messages flows: `/v1/chat/completions` is proxied to upstream `/v1/chat/completions`, while `/v1/messages` and `/:provider/v1/messages` are translated to upstream chat completions and translated back to Anthropic Messages responses. `GET /v1/models` aggregates enabled provider models with `provider/model-id` IDs; use `GET /dashscope/v1/models` for a single provider's raw model list.\n  - `enabled` defaults to `true` if omitted.\n  - `baseUrl` should be provider API base URL without the final endpoint. For Anthropic providers, omit `/v1/messages`; for OpenAI-compatible providers, omit `/v1/chat/completions`; for OpenAI Responses providers, omit `/v1/responses`.\n  - `apiKey` is used as the upstream credential value and is required for regular providers.\n  - `authType` (optional): Controls how `apiKey` is sent upstream. Supports `x-api-key` and `authorization` for regular providers. Anthropic providers default to `x-api-key`; OpenAI-compatible and OpenAI Responses providers default to `authorization`. When set to `authorization`, the proxy sends `Authorization: Bearer <apiKey>`. `oauth2` is reserved for the built-in `codex` provider and is written automatically by `auth login --provider codex`.\n  - `pricingCurrency` (optional): Provider-level currency used for token cost calculation, for example `USD` or `CNY`. Quick providers default to `CNY` for DashScope and DeepSeek, and `USD` for Codex/OpenRouter. Costs are grouped by currency and are not exchange-rate converted.\n  - `models` (optional): Per-model configuration map. Each key is a model ID (matching the model name in requests), and the value is:\n    - `temperature` (optional): Default temperature value used when the request does not specify one.\n    - `topP` (optional): Default top_p value used when the request does not specify one.\n    - `topK` (optional): Default top_k value used when the request does not specify one.\n    - `extraBody` (optional): Dynamic fields merged into the upstream request body for that model. Request body fields with the same name take precedence. OpenAI-compatible providers can use this for fields such as `enable_thinking`, `preserve_thinking`, `reasoning_effort`. `thinking_budget` is a special OpenAI-compatible provider override: when configured in `extraBody`, it is forced after Anthropic `thinking.budget_tokens` translation and overrides the request-derived budget. For providers whose name is `dashscope` or whose `baseUrl` contains `aliyuncs.com`, the request-derived `thinking_budget` (from Anthropic `thinking.budget_tokens`) is forwarded upstream; for other OpenAI-compatible providers the request-derived `thinking_budget` is stripped, while an `extraBody` `thinking_budget` is still honored. For DashScope providers, `preserve_thinking` defaults to `true` when not explicitly set in `extraBody` or the request body.\n    - `pricing` (optional): Per-model token prices, in the provider `pricingCurrency`, per 1M tokens. Supported fields are `input`, `output`, `cachedInput` (implicit cache read), `explicitCachedInput` (explicit cache read), and `cacheCreationInput`. Use `tiers` with `maxInputTokens` for input-size tiered pricing.\n    - `contextCache` (optional): Defaults to `true` for providers whose name is `dashscope` or whose `baseUrl` contains `aliyuncs.com`; defaults to `false` for other OpenAI-compatible providers. This enables Alibaba Cloud Model Studio/DashScope explicit context cache by injecting `cache_control: { \"type\": \"ephemeral\" }` on up to 4 content blocks using the Context Cache format. The cache breakpoint strategy matches opencode's main provider flow: the first 2 system messages plus the last 2 non-system messages. Marked string content is converted to text content part arrays for `system` / `user` / `assistant` / `tool` messages; existing array content is marked on the last part. Set this to `false` when the model already supports implicit caching, or when the upstream does not accept this explicit-cache extension field. Set this to `true` for non-DashScope providers that support the same explicit-cache extension. Applied on both `/v1/messages` and `/v1/chat/completions` routes.\n    - `supportPdf` (optional): Controls whether the model supports PDF/document content. Defaults to `false`; unsupported PDFs are converted to a text notice. Set it to `true` to send PDF/document blocks as OpenAI Chat Completions file parts.\n    - `toolContentSupportType` (optional): Tool result content capabilities for that model, as an array of `array`, `image`, and `pdf`. Provider routes default to string-only tool content when omitted. If `supportPdf` is `true` but this list does not include `pdf`, file parts in tool results are moved to user role messages. This provider default does not change the Copilot main flow, which continues to support array + image and not PDF.\n    - `type` (optional): Per-model override of the provider protocol type. Supports `anthropic`, `openai-compatible`, and `openai-responses`. When set, the provider's `/v1/messages` route uses this model's type instead of the provider-level type for request routing, auth header resolution, and upstream endpoint selection. This is useful for providers like OpenCode Go whose upstream supports both OpenAI-compatible and Anthropic Messages APIs for different models. When the type is overridden, the auth header is resolved from the overridden type's default (Anthropic defaults to `x-api-key`; OpenAI-compatible/Responses default to `authorization`).\n\n  Example DashScope model settings:\n  ```json\n  {\n    \"providers\": {\n      \"dashscope\": {\n        \"type\": \"openai-compatible\",\n        \"enabled\": true,\n        \"baseUrl\": \"https://dashscope.aliyuncs.com/compatible-mode\",\n        \"apiKey\": \"sk-your-dashscope-key\",\n        \"pricingCurrency\": \"CNY\",\n        \"models\": {\n          \"qwen3.7-plus\": {\n            \"temperature\": 1,\n            \"topP\": 0.95,\n            \"topK\": 20,\n            \"extraBody\": {\n              \"preserve_thinking\": true\n            }\n          },\n          \"glm-5.1\": {\n            \"temperature\": 0.7,\n            \"topP\": 0.95,\n            \"contextCache\": true,\n            \"pricing\": {\n              \"tiers\": [\n                {\n                  \"maxInputTokens\": 32000,\n                  \"input\": 6,\n                  \"cachedInput\": 1.2,\n                  \"explicitCachedInput\": 0.6,\n                  \"cacheCreationInput\": 7.5,\n                  \"output\": 24\n                },\n                {\n                  \"maxInputTokens\": 200000,\n                  \"input\": 8,\n                  \"cachedInput\": 1.6,\n                  \"explicitCachedInput\": 0.8,\n                  \"cacheCreationInput\": 10,\n                  \"output\": 28\n                }\n              ]\n            },\n            \"extraBody\": {\n              \"preserve_thinking\": true\n            }\n          }\n        }\n      }\n    }\n  }\n  ```\n  Built-in token prices cover Codex GPT models in USD, DashScope `qwen3.7-max`, `qwen3.7-plus`, `glm-5.1`, `glm-5.2` in CNY, DeepSeek `deepseek-v4-flash`, `deepseek-v4-pro`, `deepseek-chat`, `deepseek-reasoner` in CNY, and OpenCode Go models (`glm-5.2`, `deepseek-v4-flash`, `deepseek-v4-pro`, `kimi-k2.7-code`, `mimo-v2.5`, `mimo-v2.5-pro`, `qwen3.7-plus`, `qwen3.7-max`, `minimax-m2.5`, `minimax-m3`) in USD. User `pricing` entries override built-ins. For DashScope, cached tokens are charged as explicit cache reads when the upstream usage includes `cache_creation_input_tokens`; otherwise `cachedInput` is used as the implicit cache read price. For DeepSeek, `prompt_cache_hit_tokens` map to cached input and `prompt_cache_miss_tokens` map to regular input.\n- **smallModel:** Fallback model used for tool-less warmup messages (e.g., Claude Code probe requests); defaults to gpt-5-mini.\n- **contextManagement:** Controls whether the proxy adds Responses API `context_management` compaction instructions. `messages` applies when Anthropic-style `/v1/messages` requests are translated to Responses API, including `openai-responses` provider message routes, and defaults to `true`. `responses` applies to native `/v1/responses` traffic, including `provider/model` aliases and the built-in `codex` provider, and defaults to `false`. Enable `responses` only after checking that your client supports context management compaction. When enabled, the request includes `context_management` in the body and keeps only the latest compaction carrier on follow-up turns. **Note:** Context management is forcibly disabled for GPT-5.6 and above models (e.g. `gpt-5.6-sol`, `gpt-5.6-terra`, `gpt-5.6-luna`) because enabling it breaks prompt cache hits on those models. This override takes precedence over the `contextManagement` and `modelResponsesApiCompactThresholds` settings.\n- **modelResponsesApiCompactThresholds:** Per-model Responses API `compact_threshold` overrides used when the proxy adds `context_management`. These values take precedence over the fallback threshold from `resolveResponsesCompactThreshold` (`max_prompt_tokens * ratio`, or the default fallback). Defaults set `gpt-5.4` and `gpt-5.5` to `217600` (`272000 * 0.8`), and `gpt-5.6-sol`, `gpt-5.6-terra`, `gpt-5.6-luna` to `231200` (`272000 * 0.85`). Models not listed continue to use the normal fallback logic.\n- **modelReasoningEfforts:** Per-model fallback reasoning effort for `/v1/messages` requests. It is used only when the request does not provide `output_config.effort`.\n  - **Priority:** request `output_config.effort` > `modelReasoningEfforts[model]` > built-in default (`xhigh` for GPT-5.3+ models, otherwise `high`).\n  - **Forwarding:** the resolved value remains `output_config.effort` for the Copilot native Messages API and becomes `reasoning.effort` when translated to the Responses API.\n  - **Configuration values:** `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`.\n- **useMessagesApi:** When `true`, Claude-family models that support Copilot's native `/v1/messages` endpoint will use the Messages API; otherwise they fall back to `/chat/completions`. Set to `false` to disable Messages API routing and always use `/chat/completions`. Defaults to `true`.\n- **useResponsesApiWebSocket:** When `true`, Responses API requests use Copilot's websocket transport for models that advertise `ws:/responses`; models that only advertise `/responses` continue to use HTTP. Set to `false` to disable websocket routing and use HTTP `/responses` whenever the selected model supports it. Defaults to `true`.\n- **useResponsesApiWebSearch:** When `true`, the server keeps Responses API tools with `type: \"web_search\"` and forwards them upstream. Set to `false` to strip those tools from `/responses` payloads. Defaults to `true`.\n- **messageApiWebSearchModel:** Global fallback model used when a top-level Copilot `/v1/messages` request contains only the server-side `web_search` tool. Defaults to `gpt-5-mini`. If the value is a `provider/model` alias, the request is routed into that provider's Messages API path with the provider prefix stripped. For Copilot GPT models, web search runs through `/responses`. Mixed `web_search` plus custom tools are not supported and the server-side `web_search` tool is stripped.\n- **claudeTokenMultiplier:** Multiplier applied to the fallback GPT-tokenizer estimate for Claude `/v1/messages/count_tokens` requests. Defaults to `1.15`. Increase it if your client is still compacting too late. This setting is only used when the proxy is estimating Claude tokens locally; if `anthropicApiKey` is configured and Anthropic token counting succeeds, the exact Anthropic count is returned instead.\n- **anthropicApiKey:** Anthropic API key used to forward Claude `/v1/messages/count_tokens` requests to Anthropic's real token counting endpoint, which returns exact counts instead of GPT tokenizer estimates. Can also be set via the `ANTHROPIC_API_KEY` environment variable. If not set, or if the upstream call fails, token counting falls back to local GPT tokenizer estimation controlled by `claudeTokenMultiplier`.\n\nEdit this file to customize prompts or swap in your own fast model. Restart the server (or rerun the command) after changes so the cached config is refreshed.\n\n## API Authentication\n\n- **Protected non-admin routes:** All routes except `/`, `/usage-viewer`, and `/usage-viewer/` require authentication when `auth.apiKeys` is configured and non-empty.\n- **Admin routes:** All `/admin/*` routes require `auth.adminApiKey`. If it is missing, the server generates one at startup and persists it to `config.json` before serving requests.\n- **Allowed auth headers:**\n  - `x-api-key: <your_key>`\n  - `Authorization: Bearer <your_key>`\n- **CORS preflight:** `OPTIONS` requests are always allowed.\n- **When no regular keys are configured:** Non-admin routes continue to allow requests. This does not apply to `/admin/*`, which only accepts `auth.adminApiKey`.\n\nExample request for a regular protected route:\n\n```sh\ncurl http://localhost:4141/v1/models \\\n  -H \"x-api-key: your_api_key\"\n```\n\nExample request for an admin route:\n\n```sh\ncurl http://localhost:4141/admin/config/model-mappings \\\n  -H \"x-api-key: your_admin_api_key\"\n```\n\n## API Endpoints\n\nThe server exposes several OpenAI- and Anthropic-compatible endpoints. Requests can target GitHub Copilot, the built-in `codex` provider, or configured providers depending on the selected model and `provider/model` alias.\n\n### OpenAI Compatible Endpoints\n\nThese endpoints mimic the OpenAI API structure.\n\n| Endpoint                    | Method | Description                                                      |\n| --------------------------- | ------ | ---------------------------------------------------------------- |\n| `POST /v1/responses`        | `POST` | OpenAI Most advanced interface for generating model responses. Supports `provider/model` aliases for `openai-responses` providers. |\n| `POST /v1/chat/completions` | `POST` | Creates a model response for the given chat conversation. Supports `provider/model` aliases for `openai-compatible` providers and can be used without Copilot when the target provider is configured. |\n| `GET /v1/models`            | `GET`  | Lists Copilot models plus enabled provider models using `provider/model-id` IDs. Requests from Codex clients (`User-Agent` beginning with `codex`) are forwarded to the Codex Models upstream. |\n| `POST /v1/embeddings`       | `POST` | Creates an embedding vector representing the input text.         |\n\n### Codex Backend Proxy Endpoints\n\n| Endpoint             | Method | Description |\n| -------------------- | ------ | ----------- |\n| `POST /alpha/search` | `POST` | Transparently forwards the JSON body and query parameters to the Codex Alpha Search upstream. The gateway replaces client authorization and account headers with the active Codex login, forwards compatible headers such as `accept`, `content-type`, `originator`, `user-agent`, and `cookie`, and returns the upstream status, headers, and body unchanged. |\n\n### Anthropic Compatible Endpoints\n\nThese endpoints are designed to be compatible with the Anthropic Messages API.\n\n| Endpoint                         | Method | Description                                                  |\n| -------------------------------- | ------ | ------------------------------------------------------------ |\n| `POST /v1/messages`              | `POST` | Creates a model response for a given conversation. Supports `provider/model` aliases for configured providers, including translation through `openai-compatible` providers. |\n| `POST /v1/messages/count_tokens` | `POST` | Calculates the number of tokens for a given set of messages. Supports `provider/model` aliases for configured providers. |\n| `POST /:provider/v1/messages`       | `POST` | Proxies Anthropic Messages requests to the configured Anthropic provider, translates them through an OpenAI-compatible provider, or translates them through an OpenAI Responses provider. |\n| `GET /:provider/v1/models`          | `GET`  | Proxies model listing requests to the configured provider.   |\n| `POST /:provider/v1/messages/count_tokens` | `POST` | Calculates tokens locally for provider route requests. |\n\n### Usage Monitoring Endpoints\n\nNew endpoints for monitoring your Copilot usage and quotas.\n\n| Endpoint     | Method | Description                                                  |\n| ------------ | ------ | ------------------------------------------------------------ |\n| `GET /usage` | `GET`  | Get detailed Copilot usage statistics and quota information. |\n| `GET /token` | `GET`  | Get the current Copilot token being used by the API.         |\n\n### Admin / Configuration Endpoints\n\nThese endpoints are reserved for local administrative actions and only accept `auth.adminApiKey`.\n\n| Endpoint                              | Method | Description                                                                 |\n| ------------------------------------- | ------ | --------------------------------------------------------------------------- |\n| `GET /admin/config/model-mappings`    | `GET`  | Returns the current `config.json` path and the active `modelMappings` map.  |\n| `POST /admin/config/model-mappings`   | `POST` | Updates only the `modelMappings` field in `config.json` and returns it back. |\n\n## Example Usage\n\nCommon `npx` commands:\n\n```sh\n# Start the gateway\nnpx @jeffreycao/copilot-api@latest start\n\n# Start on a custom port with verbose logging\nnpx @jeffreycao/copilot-api@latest start --port 8080 --verbose\n\n# Run the auth flow\nnpx @jeffreycao/copilot-api@latest auth login\n\n# Configure a third-party provider, then run without GitHub Copilot\nnpx @jeffreycao/copilot-api@latest auth login --provider dashscope\nnpx @jeffreycao/copilot-api@latest start\n\n# Print debug information as JSON\nnpx @jeffreycao/copilot-api@latest debug --json\n\n# Run the published CLI with Bun instead of Node.js\nbunx --bun @jeffreycao/copilot-api@latest start\n```\n\nOpenAI-compatible provider examples after configuring `dashscope`:\n\n```sh\ncurl http://localhost:4141/v1/chat/completions \\\n  -H \"content-type: application/json\" \\\n  -d '{\"model\":\"dashscope/qwen3.6-plus\",\"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]}'\n\ncurl http://localhost:4141/dashscope/v1/messages \\\n  -H \"content-type: application/json\" \\\n  -d '{\"model\":\"qwen3.6-plus\",\"max_tokens\":1024,\"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]}'\n```\n\n## Usage Tips\n\n### CLAUDE.md or AGENTS.md Recommended Content\n\nTo add these reminders manually, include the following in `CLAUDE.md` for Claude Code, or `AGENTS.md` for opencode/codex:\n\n```\n- Prohibited from directly asking questions to users, MUST use question tool.\n- Once you can confirm that the task is complete, MUST use question tool to make user confirm. The user may respond with feedback if they are not satisfied with the result, which you can use to make improvements and try again, after try again, MUST use question tool to make user confirm again.\n```\n"}, "58960693803eed3dd5f44ebc2c1d98d27b024687": {"t": 1785765559.861787, "n": 47899, "h": "844c7d10528b36f2", "c": "# Copilot API Proxy\n\nEnglish | [简体中文](./README.zh-CN.md)\n\n## Important Notes\n\n> [!IMPORTANT]\n> **Before using, please be aware of the following:**\n>\n> 1. **Claude Code configuration:** When using with Claude Code, please configure the model ID as `claude-opus-4-8`. Example claude `settings.json` see [Manual Configuration with `settings.json`](#manual-configuration-with-settingsjson). \n>\n> 2. **Built-in `copilot`, `codex` and third-party providers:** Run `npx @jeffreycao/copilot-api@latest auth` and choose `copilot`, `codex`, `deepseek`, `custom`, or other providers.\n>\n> 3. **Note:** See [GitHub Copilot Security Notice](./NOTICE.md#github-copilot-security-notice) for the warning removed from the README header.\n\n---\n\n## Project Overview\n\nA small AI gateway that can use GitHub Copilot, the built-in `codex` provider, or configured third-party providers such as DashScope. GitHub Copilot is optional: if no GitHub token is available, the server can still start in provider-only mode as long as at least one enabled provider is configured.\n\nThe gateway exposes OpenAI- and Anthropic-compatible APIs from one local endpoint, so tools like [Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview), OpenCode, Codex, and OpenAI-compatible clients can share the same local server.\n\nOn the GitHub Copilot path, the gateway prefers Copilot's native Anthropic-style Messages API when available, preserving more Claude-native behavior for tool-heavy workflows.\n\n## Features\n\n- **OpenAI and Anthropic compatibility**: Serve `/v1/responses`, `/v1/chat/completions`, `/v1/models`, `/v1/embeddings`, and `/v1/messages` from one local gateway.\n- **Copilot is optional**: Use GitHub Copilot when credentials are present, or run the server with only configured providers.\n- **One gateway for Copilot, `codex`, and external providers**: Route GitHub Copilot, the built-in `codex` provider, and configured third-party providers behind the same endpoint.\n- **Standalone third-party providers**: Configure providers such as DashScope, DeepSeek, OpenRouter, or a custom provider and start the gateway without a GitHub Copilot login.\n- **OpenAI-compatible providers on chat and Messages APIs**: `openai-compatible` providers can serve top-level `/v1/chat/completions` through `model: \"provider/model\"` and Anthropic-style `/v1/messages` through request/response translation.\n- **Agent-friendly Claude handling on Copilot**: Prefer native `/v1/messages` when available, preserve Claude-style tool flows, support Anthropic beta features, Claude WebSearch through Responses-capable models, and keep subagent/session markers intact.\n- **Claude Code and OpenCode integration**: Works with Claude Code and OpenCode, including direct Anthropic-compatible usage through `@ai-sdk/anthropic`.\n- **Flexible auth and deployment options**: Supports interactive login or direct tokens, individual/business/enterprise plans, GitHub Enterprise, opencode OAuth, and custom data directories.\n- **Multi-provider routing**: Expose provider-specific `/:provider/...` routes or use `model: \"provider/model\"` on the top-level API.\n\n## Prerequisites\n\n- Bun (>= 1.2.x)\n- Node.js if you plan to run the published CLI with `npx`\n- GitHub account with Copilot subscription only if you want to use the GitHub Copilot provider\n- An API key or OAuth login for at least one configured provider if you want to run without GitHub Copilot\n\n## Installation\n\nTo install dependencies, run:\n\n```sh\nbun install\n```\n\nTo start the server directly from source:\n\n```sh\nbun run start start\n```\n\n## Running from Source\n\nThe project can be run from source in several ways:\n\n### Development Mode\n\n```sh\nbun run dev start\n```\n\n### Production Mode\n\n```sh\nbun run start start\n```\n\n## Using with npx\n\nYou can run the project directly using npx:\n\n> [!IMPORTANT]\n> Token usage storage uses Node's built-in `node:sqlite` module when running with `npx`. It is enabled on Node.js >= 22.13.0. On Node.js < 22.13.0, the CLI still starts, but token usage storage is disabled.\n>\n> If you want token usage storage without upgrading Node.js, run the published CLI with Bun instead: `bunx --bun @jeffreycao/copilot-api@latest start`.\n\n```sh\nnpx @jeffreycao/copilot-api@latest start\n```\n\nWith options:\n\n```sh\nnpx @jeffreycao/copilot-api@latest start --port 8080\n```\n\nFor authentication or provider configuration only:\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth\n```\n\nTo run without GitHub Copilot, configure at least one provider first, then start the server normally:\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth login --provider dashscope\nnpx @jeffreycao/copilot-api@latest start\n```\n\n## Using with Docker\n\nBuild the image:\n\n```sh\ndocker build -t copilot-api .\n```\n\nRun the container with a bind mount so auth data survives restarts:\n\n```sh\nmkdir -p ./copilot-data\ndocker run -p 4141:4141 -v $(pwd)/copilot-data:/root/.local/share/copilot-api copilot-api\n```\n\nThis stores GitHub auth data, provider config, and other gateway state in `./copilot-data` on the host, mapped to `/root/.local/share/copilot-api` in the container.\n\nOr pass a GitHub token directly:\n\n```sh\ndocker run -p 4141:4141 -e GH_TOKEN=your_github_token_here copilot-api\n```\n\n## Electron Desktop App\n\nIf you prefer a GUI, this repository also includes an Electron desktop app in `desktop/`. It supports GitHub Copilot sign-in, OpenAI Codex OAuth, and API-key configuration for DeepSeek, DashScope, OpenRouter, or a custom provider. After authorization or provider configuration, it can start and stop the local proxy with one click and shows the local endpoint, auth header, available models, usage, and logs in the app.\n\nThe settings screen also exposes `OAuth App`, `API Home`, `Enterprise URL`, verbose logging, and minimize-to-tray. Desktop packages are published in GitHub Releases:\n\nhttps://github.com/caozhiyuan/copilot-api/releases\n\nDownload the installer for your platform, authorize or configure a provider inside the app, choose a port, start the server, then point your client at the local endpoint shown in the app. Packaged desktop builds use the bundled Electron runtime, so normal desktop usage does not require installing Node.js separately. Token usage history is enabled when that bundled runtime supports SQLite.\n\nThe desktop app's Advanced Config page reads and writes the shared model mappings through `GET/POST /admin/config/model-mappings`. The same mappings apply across `POST /v1/messages`, `POST /v1/messages/count_tokens`, `POST /v1/responses`, and `POST /v1/chat/completions` instead of being split per interface. It uses `auth.adminApiKey` instead of the regular `auth.apiKeys`, and the app reads that key directly from `config.json` after the server has generated it on startup.\n\n### Desktop App Screenshots\n\nMain dashboard, token usage breakdown in the bundled Electron app:\n\n<p align=\"center\">\n  <img src=\"./docs/screenshots/desktop-dashboard.png\" alt=\"Copilot API desktop app dashboard\" width=\"49%\" />\n  <img src=\"./docs/screenshots/desktop-token-usage.png\" alt=\"Copilot API desktop app token usage view\" width=\"49%\" />\n</p>\n\n## Using with Claude Code\n\nThis AI gateway can be used to power [Claude Code](https://docs.anthropic.com/en/claude-code), an experimental conversational AI assistant for developers from Anthropic.\n\nThere are two ways to configure Claude Code to use this AI gateway:\n\n### Interactive Setup with `--claude-code` flag\n\nTo get started, run the `start` command with the `--claude-code` flag:\n\n```sh\nnpx @jeffreycao/copilot-api@latest start --claude-code\n```\n\nYou will be prompted to select a primary model and a \"small, fast\" model for background tasks. After selecting the models, a command will be copied to your clipboard. This command sets the necessary environment variables for Claude Code to use the gateway.\n\nPaste and run this command in a new terminal to launch Claude Code.\n\n### Manual Configuration with `settings.json`\n\nAlternatively, you can configure Claude Code by creating a `.claude/settings.json` file in your project's root directory. This file should contain the environment variables needed by Claude Code. This way you don't need to run the interactive setup every time.\n\nHere is an example `.claude/settings.json` file:\n\n```json\n{\n  \"env\": {\n    \"ANTHROPIC_BASE_URL\": \"http://localhost:4141\",\n    \"ANTHROPIC_AUTH_TOKEN\": \"dummy\",\n    \"ANTHROPIC_MODEL\": \"deepseek/deepseek-v4-pro\",\n    \"ANTHROPIC_DEFAULT_SONNET_MODEL\": \"deepseek/deepseek-v4-pro\",\n    \"ANTHROPIC_DEFAULT_HAIKU_MODEL\": \"deepseek/deepseek-v4-flash\",\n    \"DISABLE_NON_ESSENTIAL_MODEL_CALLS\": \"1\",\n    \"CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC\": \"1\",\n    \"CLAUDE_CODE_ATTRIBUTION_HEADER\": \"0\",\n    \"CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION\": \"false\",\n    \"CLAUDE_CODE_DISABLE_TERMINAL_TITLE\": \"true\",\n    \"CLAUDE_CODE_ENABLE_AWAY_SUMMARY\": \"0\"\n  },\n  \"permissions\": {\n    \"deny\": [\n      \"mcp__ide__executeCode\"\n    ]\n  }\n}\n```\n\n- Replace `ANTHROPIC_MODEL`, `ANTHROPIC_DEFAULT_OPUS_MODEL`, `ANTHROPIC_DEFAULT_SONNET_MODEL`, and `ANTHROPIC_DEFAULT_HAIKU_MODEL` according to your needs. After configuration, please install the claude code plugin [Plugin Integrations](#plugin-integrations).  \n- Setting CLAUDE_CODE_ATTRIBUTION_HEADER to 0 can prevent Claude code from adding billing and version information in system prompts, thereby avoiding prompt cache invalidation.\n- Turning off CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION and CLAUDE_CODE_ENABLE_AWAY_SUMMARY can prevent quota from being consumed unnecessarily.\n- Claude Code WebSearch is supported for pure search requests. For Copilot, keep the global `messageApiWebSearchModel` set to a Responses-capable GPT model or a `provider/model` alias. For provider routes, use a native Anthropic provider or an `openai-responses` provider. Add `WebSearch` to `permissions.deny` only if you want to forbid this traffic.\n- If using a non-Claude model, do not enable ENABLE_TOOL_SEARCH. If using the Claude model, can enable ENABLE_TOOL_SEARCH. The current Claude Code uses the client tool search mode. In this mode, loading defer tools requires an additional request each time.\n- `CLAUDE_CODE_AUTO_COMPACT_WINDOW`: Set the context capacity in tokens used for auto-compaction calculations. Defaults to the model's context window: 200K for standard models or 1M for extended context models. Use a lower value like `500000` on a 1M model (e.g., `claude-opus-4-6[1m]`) to treat the window as 500K for compaction purposes. The value is capped at the model's actual context window. `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` is applied as a percentage of this value. Setting this variable decouples the compaction threshold from the status line's `used_percentage`, which always uses the model's full context window.\n\nYou can find more options here: [Claude Code settings](https://docs.anthropic.com/en/docs/claude-code/settings#environment-variables)\n\nYou can also read more about IDE integration here: [Add Claude Code to your IDE](https://docs.anthropic.com/en/docs/claude-code/ide-integrations)\n\n## Using with OpenCode\n\nOpenCode already has a direct GitHub Copilot provider. Use this section when you want OpenCode to point at this AI gateway through `@ai-sdk/anthropic` and reuse the agent behaviors described earlier in this README.\n\n### Minimal setup\n\nStart the AI gateway with the OpenCode OAuth app:\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth --oauth-app=opencode\nnpx @jeffreycao/copilot-api@latest start\n```\n\nThen point OpenCode at the gateway with `@ai-sdk/anthropic`.\n\nExample `~/.config/opencode/opencode.json`:\n\n```json\n{\n  \"$schema\": \"https://opencode.ai/config.json\",\n  \"provider\": {\n    \"local\": {\n      \"npm\": \"@ai-sdk/anthropic\",\n      \"name\": \"My Local\",\n      \"options\": {\n        \"baseURL\": \"http://localhost:4141/v1\",\n        \"apiKey\": \"dummy\"\n      },\n      \"models\": {\n        \"gpt-5.4\": {\n          \"name\": \"gpt-5.4\",\n          \"modalities\": {\n            \"input\": [\"text\", \"image\"],\n            \"output\": [\"text\"]\n          },\n          \"limit\": {\n            \"context\": 400000,\n            \"input\": 272000,\n            \"output\": 128000\n          }\n        },\n        \"claude-sonnet-4.6\": {\n          \"id\": \"claude-sonnet-4.6\",\n          \"name\": \"claude-sonnet-4.6\",\n          \"modalities\": {\n            \"input\": [\"text\", \"image\"],\n            \"output\": [\"text\"]\n          },          \n          \"limit\": {\n            \"context\": 200000,\n            \"output\": 32000\n          },\n          \"options\": {\n            \"thinking\": {\n              \"type\": \"adaptive\"\n            },\n            \"effort\": \"max\"\n          }\n        }\n      }\n    }\n  }\n}\n```\n\nWhy these fields matter:\n\n- `npm: \"@ai-sdk/anthropic\"` is the important part. OpenCode will speak Anthropic Messages semantics to this AI gateway instead of flattening everything into OpenAI Chat Completions.\n- `options.baseURL` should be `http://localhost:4141/v1`; the Anthropic SDK will append `/messages`, `/models`, and `/messages/count_tokens` automatically.\n- If you enable `auth.apiKeys` in this AI gateway, replace `dummy` with a real key. Otherwise any placeholder value is fine.\n\n## Using with Codex\n\nThis AI gateway can also power Codex.\n\n### Codex `config.toml` Reference\n\nAdd the following `[model_providers.copilot_api]` section to your Codex `~/.codex/config.toml`:\n\n```toml\nmodel_provider = \"copilot_api\"\nmodel_reasoning_summary = \"auto\"\nmodel_verbosity = \"medium\"\nmodel_context_window = 272000\nmodel_auto_compact_token_limit = 244800\n\n[model_providers.copilot_api]\nname = \"OpenAI\"\nbase_url = \"http://localhost:4141\"\nenv_key = \"GITHUB_COPILOT_API_KEY\"\nrequires_openai_auth = true\nsupports_websockets = false\nwire_api = \"responses\"\nrequest_max_retries = 3\nstream_max_retries = 1\nstream_idle_timeout_ms = 300000\n\n[features]\nremote_compaction_v2 = true\n\n[analytics]\nenabled = false\n```\n\n> [!NOTE]\n> This configuration is specific to Codex and the GitHub Copilot provider. `name` must be set to `\"OpenAI\"`. It can help mitigate Codex local compact cache miss issues. If you enable `contextManagement.responses` (Responses API context management compaction), `remote_compaction_v2` or local compact is generally not triggered, but it may still occur when tool results return a large number of tokens. Before enabling it for native Responses API traffic, check that your client supports context management compaction.\n\n## GPT Tool Search\n\nFor GPT Responses models such as `gpt-5.4+`, this AI gateway can expose Responses `tool_search` through a small MCP bridge. The same bridge can be used by Claude Code and opencode, as long as the client loads MCP servers and sends Anthropic Messages traffic through this gateway.\n\nDo not set Claude Code's native `ENABLE_TOOL_SEARCH` for GPT models. That flag enables Claude Code's own client-side tool search mode, and it may stop forwarding deferred tool definitions. This gateway needs the full tool definitions so it can keep the small always-loaded tool set eager and translate every other tool into Responses deferred namespaces.\n\nIf you install `tool-search@copilot-api-marketplace`, Claude Code receives this MCP bridge automatically and you can skip the manual Claude Code MCP setup below.\n\nAdd the tool search bridge to the MCP config used by Claude Code:\n\n```json\n{\n  \"mcpServers\": {\n    \"tool_search\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@jeffreycao/copilot-api@latest\", \"mcp\"]\n    }\n  }\n}\n```\n\nAdd the tool search bridge to the MCP config used by opencode:\n\n```json\n{\n  \"mcp\": {\n    \"tool_search\": {\n      \"type\": \"local\",\n      \"command\": [\"npx\", \"-y\", \"@jeffreycao/copilot-api@latest\", \"mcp\"]\n    }\n  }\n}\n```\n\nFor local development, use `bun` as the command and `[\"run\", \"./src/main.ts\", \"mcp\"]` as the args.\n\nInternally, the gateway now configures OpenAI Responses `tool_search` in client-executed mode. Deferred tools are still exposed as searchable namespaces, but the model is explicitly asked to return the exact deferred tool names it wants to load next.\n\nThe bridge uses direct tool selection, not query search. Its tool input is `names`, a comma-separated list of exact deferred tool names, for example `TaskList,TaskGet,mcp__fetch__fetch`.\n\n## Plugin Integrations\n\nPlugin integrations are available for Claude Code and opencode.\n\n#### Claude Code plugin integration (marketplace-based)\n\nThe Claude Code integration is packaged as two plugins:\n\n- `agent-inject` injects `__SUBAGENT_MARKER__...` on `SubagentStart`, so the gateway can infer `x-initiator: agent`.\n- `tool-search` registers the `tool_search` MCP bridge used for GPT Responses deferred tool loading.\n\n- Marketplace catalog in this repository: `.claude-plugin/marketplace.json`\n- Plugin sources in this repository: `plugin/claude/agent-inject`, `plugin/claude/tool-search`\n\nAdd the marketplace remotely:\n\n```sh\n/plugin marketplace add https://github.com/caozhiyuan/copilot-api.git\n```\n\nInstall the plugins from the marketplace:\n\n```sh\n/plugin install agent-inject@copilot-api-marketplace\n/plugin install tool-search@copilot-api-marketplace\n```\n\nAfter installation, `agent-inject` injects `__SUBAGENT_MARKER__...` on `SubagentStart`, and the gateway uses it to infer `x-initiator: agent`.\n\nThe `agent-inject` plugin also registers a `UserPromptSubmit` hook that returns `{\"continue\": true}`, and it can inject `SessionStart` reminder rules through environment variables:\n\n- `CLAUDE_PLUGIN_ENABLE_QUESTION_RULES=1` enables the two reminders about using the `question` tool automatically for Claude Code. Alternatively, you can add the same reminders manually in `CLAUDE.md`; see [CLAUDE.md or AGENTS.md Recommended Content](#claudemd-or-agentsmd-recommended-content).\n- `CLAUDE_PLUGIN_ENABLE_NO_BACKGROUND_AGENTS_RULE=1` enables the `run_in_background: true` avoidance reminder for agent hooks.\n\nThe `tool-search` plugin bundles the same MCP bridge described in [GPT Tool Search](#gpt-tool-search), so Claude Code users do not need to add the `tool_search` server manually when they install that plugin.\n\n#### Opencode plugin\n\nThe subagent marker producer is packaged as an opencode plugin located at `plugin/opencode/subagent-marker.js`.\n\n**Installation:**\n\nCopy the plugin file to your opencode plugins directory:\n\n```sh\n# Clone or download this repository, then copy the plugin\ncp plugin/opencode/subagent-marker.js ~/.config/opencode/plugins/\n```\n\nOr manually create the file at `~/.config/opencode/plugins/subagent-marker.js` with the plugin content.\n\n**Features:**\n\n- Tracks sub-sessions created by subagents\n- Automatically prepends a marker system reminder (`__SUBAGENT_MARKER__...`) to subagent chat messages\n- Sets `x-session-id` header for session tracking\n- Enables the gateway to infer `x-initiator: agent` for subagent-originated requests\n\nThe plugin hooks into `session.created`, `session.deleted`, `chat.message`, and `chat.headers` events to provide seamless subagent marker functionality.\n\n## Using the Usage Viewer\n\nAfter starting the server, a URL to the Copilot Usage Dashboard will be displayed in your console. This dashboard is a web interface for monitoring your API usage.\n\n1.  Start the server. For example, using npx:\n    ```sh\n    npx @jeffreycao/copilot-api@latest start\n    ```\n2.  The server will output a URL to the usage viewer. Copy and paste this URL into your browser. It will look something like this:\n    `http://localhost:4141/usage-viewer?endpoint=http://localhost:4141/usage`\n    - If you use the `start.bat` script on Windows, this page will open automatically.\n\nThe dashboard provides a user-friendly interface to view your Copilot usage data:\n\n> Token usage history requires Bun or Node.js >= 22.13.0. On Node.js < 22.13.0, the server runs normally but token usage storage is disabled.\n\n- **API Endpoint URL**: The dashboard is pre-configured to fetch data from your local server endpoint via a URL query parameter. You can manually switch this to any other compatible API endpoint.\n- **x-api-key Authentication**: If API Key authentication is enabled, you can provide the `x-api-key` request header. The key is persisted in the browser's local storage.\n- **Period Selector**: Choose from Day, Week, or Month time ranges. The URL query parameter updates automatically when you switch, making it easy to bookmark and share.\n- **Fetch Data**: Click the \"Refresh\" button to load or refresh the usage data. The dashboard also fetches data automatically on page load.\n- **Copilot Quotas**: View quota usage for services such as Chat and Completions via progress bars. Hover over a card to see used/remaining details.\n- **Token Usage Metric Cards**: See a summary of Total, Input, Output, Cache Read, Cache Write, Requests, and estimated cost for the current period.\n- **Trend Chart (Week / Month)**: An interactive line chart with model and metric filters. Click a data point to inspect the usage breakdown for a specific day.\n- **Model Breakdown Table**: A per-model summary of requests, input/output/cache tokens, and estimated cost for the selected period.\n- **Request Events (Paginated)**: A time-sorted list of request event records with pagination support, showing timestamps, models, request IDs, and token counts.\n- **Detailed Information**: See the full JSON response from the API for a detailed breakdown of all available usage statistics.\n- **URL-based Configuration**: You can also specify the API endpoint and period directly via `endpoint` and `period` query parameters. For example:\n  `http://localhost:4141/usage-viewer?endpoint=http://your-api-server/usage&period=week`\n\n### Usage Viewer Screenshot\n\n<p align=\"center\">\n  <img src=\"./docs/screenshots/usage-viewer.png\" alt=\"Copilot API usage viewer\" width=\"900\" />\n</p>\n\n## Command Structure\n\nCopilot API now uses a subcommand structure with these main commands:\n\n- `start`: Start the gateway server. If a GitHub token is available, the server starts with Copilot enabled. If no GitHub token is available, it starts in provider-only mode when at least one enabled provider exists; otherwise it guides you through provider setup.\n- `auth`: Run provider login or configuration without starting the server. Use it for GitHub Copilot login, Codex OAuth, or third-party provider API key setup.\n- `debug`: Display diagnostic information including version, runtime details, file paths, and authentication status. Useful for troubleshooting and support.\n\n## Command Line Options\n\n### Global Options\n\nThe following options can be used with any subcommand. When passing them before the subcommand, use the `--key=value` form:\n\n| Option            | Description                                            | Default | Alias |\n| ----------------- | ------------------------------------------------------ | ------- | ----- |\n| --api-home        | Path to the API home directory (sets COPILOT_API_HOME) | none    | none  |\n| --oauth-app       | OAuth app identifier (sets COPILOT_API_OAUTH_APP)      | none    | none  |\n| --enterprise-url  | Enterprise URL for GitHub (sets COPILOT_API_ENTERPRISE_URL) | none | none |\n\n### Start Command Options\n\nThe following command line options are available for the `start` command:\n\n| Option         | Description                                                                   | Default    | Alias |\n| -------------- | ----------------------------------------------------------------------------- | ---------- | ----- |\n| --port         | Port to listen on                                                             | 4141       | -p    |\n| --verbose      | Enable verbose logging                                                        | false      | -v    |\n| --github-token | Provide GitHub token directly (must be generated using the `auth` subcommand) | none       | -g    |\n| --claude-code  | Generate a command to launch Claude Code with Copilot API config              | false      | -c    |\n| --show-token   | Show GitHub and Copilot tokens on fetch and refresh                           | false      | none  |\n| --proxy-env    | Initialize proxy from environment variables                                   | false      | none  |\n\n### Auth Command Options\n\n| Option       | Description               | Default | Alias |\n| ------------ | ------------------------- | ------- | ----- |\n| --provider   | Provider to log in with or configure (`copilot`, `codex`, `opencode-go`, `deepseek`, `dashscope`, `openrouter`, or `custom`) | prompt | none |\n| --verbose    | Enable verbose logging    | false   | -v    |\n| --show-token | Show GitHub token on auth | false   | none  |\n\nUse `copilot-api auth login --provider copilot` only when you want to enable the GitHub Copilot provider. Copilot is not required for `codex` or third-party provider-only usage.\n\nUse `copilot-api auth login --provider deepseek`, `--provider dashscope`, `--provider openrouter`, or `--provider opencode-go` to add or update those common third-party providers from the CLI. DeepSeek prompts for masked `apiKey`, provider `type` (default `anthropic`), and `baseUrl` defaulting to `https://api.deepseek.com/anthropic`. DashScope prompts for masked `apiKey`, provider `type` (default `openai-compatible`), and prefilled `baseUrl`. OpenRouter prompts for masked `apiKey` and prefilled `baseUrl` only, and writes `type: \"anthropic\"`. OpenCode Go prompts for masked `apiKey` and prefilled `baseUrl` only, and writes `type: \"openai-compatible\"` (baseUrl `https://opencode.ai/zen/go`). After a provider is configured and enabled, `copilot-api start` can run without any GitHub token.\n\nUse `copilot-api auth login --provider custom` to add or update another third-party provider from the CLI. The command prompts for the provider name, supported type (`anthropic`, `openai-compatible`, or `openai-responses`), `baseUrl`, masked `apiKey`, and `authType`; `authType` may be left as the type default or set to `x-api-key` / `authorization`.\n\n### Debug Command Options\n\n| Option | Description               | Default | Alias |\n| ------ | ------------------------- | ------- | ----- |\n| --json | Output debug info as JSON | false   | none  |\n\n## Configuration (config.json)\n\n- **Location:** `~/.local/share/copilot-api/config.json` (Linux/macOS) or `%USERPROFILE%\\.local\\share\\copilot-api\\config.json` (Windows).\n- **Default shape:**\n  ```json\n  {\n    \"auth\": {\n      \"apiKeys\": [],\n      \"adminApiKey\": \"<auto-generated-on-startup>\"\n    },\n    \"providers\": {},\n    \"modelMappings\": {},\n    \"extraPrompts\": {\n      \"gpt-5-mini\": \"<built-in exploration prompt>\"\n    },\n    \"smallModel\": \"gpt-5-mini\",\n    \"contextManagement\": {\n      \"messages\": true,\n      \"responses\": false\n    },\n    \"modelResponsesApiCompactThresholds\": {\n      \"gpt-5.4\": 217600,\n      \"gpt-5.5\": 217600,\n      \"gpt-5.6-sol\": 231200,\n      \"gpt-5.6-terra\": 231200,\n      \"gpt-5.6-luna\": 231200\n    },\n    \"modelReasoningEfforts\": {\n      \"gpt-5-mini\": \"low\"\n    },\n    \"useMessagesApi\": true,\n    \"useResponsesApiWebSocket\": true,\n    \"useResponsesApiWebSearch\": true,\n    \"messageApiWebSearchModel\": \"gpt-5-mini\"\n  }\n  ```\n- **auth.apiKeys:** API keys used for request authentication on non-admin routes. Supports multiple keys for rotation. Requests can authenticate with either `x-api-key: <key>` or `Authorization: Bearer <key>`. If empty or omitted, authentication for non-admin routes is disabled.\n- **auth.adminApiKey:** Single admin key used only for `/admin/*` routes. If missing, the server generates a random key at startup and writes it back to `config.json`. Requests use the same `x-api-key` or `Authorization: Bearer` headers, but regular `auth.apiKeys` never grant access to `/admin/*`.\n- **modelMappings:** Exact `sourceModel -> targetModel` rewrites shared by top-level `POST /v1/messages`, `POST /v1/messages/count_tokens`, `POST /v1/responses`, and `POST /v1/chat/completions` requests. Omit it or leave it as `{}` to disable rewrites. Both the source and target must be non-empty strings. Targets can be regular model IDs or `provider/model` aliases such as `dashscope/qwen3.6-plus`, and the rewrite happens before provider alias parsing. These mappings are not split per interface. The admin endpoints `GET/POST /admin/config/model-mappings` read and update only this field.\n- **extraPrompts:** Map of `model -> prompt` appended to the first system prompt when translating Anthropic-style requests to Responses API. Use this to inject guardrails or guidance per model. Missing default entries are auto-added without overwriting your custom prompts. For GPT-5.3+ models (e.g. `gpt-5.3-codex`, `gpt-5.4`, `gpt-5.5`), a built-in commentary prompt is used as fallback when not explicitly configured. The built-in prompts enable phase-aware commentary, which lets the model emit a short user-facing progress update before tools or deeper reasoning.\n- **providers:** Global upstream provider map. Each provider key (for example `dashscope`) becomes a route prefix (`/dashscope/v1/messages`). Supports `type: \"anthropic\"`, `type: \"openai-compatible\"`, and `type: \"openai-responses\"`. Top-level clients can also use `model: \"dashscope/model-id\"` with `/v1/messages`, `/v1/messages/count_tokens`, `/v1/responses`, and `/v1/chat/completions`; the gateway strips the `dashscope/` prefix before forwarding upstream. `openai-compatible` providers support both chat and Messages flows: `/v1/chat/completions` is proxied to upstream `/v1/chat/completions`, while `/v1/messages` and `/:provider/v1/messages` are translated to upstream chat completions and translated back to Anthropic Messages responses. `GET /v1/models` aggregates enabled provider models with `provider/model-id` IDs; use `GET /dashscope/v1/models` for a single provider's raw model list.\n  - `enabled` defaults to `true` if omitted.\n  - `baseUrl` should be provider API base URL without the final endpoint. For Anthropic providers, omit `/v1/messages`; for OpenAI-compatible providers, omit `/v1/chat/completions`; for OpenAI Responses providers, omit `/v1/responses`.\n  - `apiKey` is used as the upstream credential value and is required for regular providers.\n  - `authType` (optional): Controls how `apiKey` is sent upstream. Supports `x-api-key` and `authorization` for regular providers. Anthropic providers default to `x-api-key`; OpenAI-compatible and OpenAI Responses providers default to `authorization`. When set to `authorization`, the proxy sends `Authorization: Bearer <apiKey>`. `oauth2` is reserved for the built-in `codex` provider and is written automatically by `auth login --provider codex`.\n  - `pricingCurrency` (optional): Provider-level currency used for token cost calculation, for example `USD` or `CNY`. Quick providers default to `CNY` for DashScope and DeepSeek, and `USD` for Codex/OpenRouter. Costs are grouped by currency and are not exchange-rate converted.\n  - `models` (optional): Per-model configuration map. Each key is a model ID (matching the model name in requests), and the value is:\n    - `temperature` (optional): Default temperature value used when the request does not specify one.\n    - `topP` (optional): Default top_p value used when the request does not specify one.\n    - `topK` (optional): Default top_k value used when the request does not specify one.\n    - `extraBody` (optional): Dynamic fields merged into the upstream request body for that model. Request body fields with the same name take precedence. OpenAI-compatible providers can use this for fields such as `enable_thinking`, `preserve_thinking`, `reasoning_effort`. `thinking_budget` is a special OpenAI-compatible provider override: when configured in `extraBody`, it is forced after Anthropic `thinking.budget_tokens` translation and overrides the request-derived budget. For providers whose name is `dashscope` or whose `baseUrl` contains `aliyuncs.com`, the request-derived `thinking_budget` (from Anthropic `thinking.budget_tokens`) is forwarded upstream; for other OpenAI-compatible providers the request-derived `thinking_budget` is stripped, while an `extraBody` `thinking_budget` is still honored. For DashScope providers, `preserve_thinking` defaults to `true` when not explicitly set in `extraBody` or the request body.\n    - `pricing` (optional): Per-model token prices, in the provider `pricingCurrency`, per 1M tokens. Supported fields are `input`, `output`, `cachedInput` (implicit cache read), `explicitCachedInput` (explicit cache read), and `cacheCreationInput`. Use `tiers` with `maxInputTokens` for input-size tiered pricing.\n    - `contextCache` (optional): Defaults to `true` for providers whose name is `dashscope` or whose `baseUrl` contains `aliyuncs.com`; defaults to `false` for other OpenAI-compatible providers. This enables Alibaba Cloud Model Studio/DashScope explicit context cache by injecting `cache_control: { \"type\": \"ephemeral\" }` on up to 4 content blocks using the Context Cache format. The cache breakpoint strategy matches opencode's main provider flow: the first 2 system messages plus the last 2 non-system messages. Marked string content is converted to text content part arrays for `system` / `user` / `assistant` / `tool` messages; existing array content is marked on the last part. Set this to `false` when the model already supports implicit caching, or when the upstream does not accept this explicit-cache extension field. Set this to `true` for non-DashScope providers that support the same explicit-cache extension. Applied on both `/v1/messages` and `/v1/chat/completions` routes.\n    - `supportPdf` (optional): Controls whether the model supports PDF/document content. Defaults to `false`; unsupported PDFs are converted to a text notice. Set it to `true` to send PDF/document blocks as OpenAI Chat Completions file parts.\n    - `toolContentSupportType` (optional): Tool result content capabilities for that model, as an array of `array`, `image`, and `pdf`. Provider routes default to string-only tool content when omitted. If `supportPdf` is `true` but this list does not include `pdf`, file parts in tool results are moved to user role messages. This provider default does not change the Copilot main flow, which continues to support array + image and not PDF.\n    - `type` (optional): Per-model override of the provider protocol type. Supports `anthropic`, `openai-compatible`, and `openai-responses`. When set, the provider's `/v1/messages` route uses this model's type instead of the provider-level type for request routing, auth header resolution, and upstream endpoint selection. This is useful for providers like OpenCode Go whose upstream supports both OpenAI-compatible and Anthropic Messages APIs for different models. When the type is overridden, the auth header is resolved from the overridden type's default (Anthropic defaults to `x-api-key`; OpenAI-compatible/Responses default to `authorization`).\n\n  Example DashScope model settings:\n  ```json\n  {\n    \"providers\": {\n      \"dashscope\": {\n        \"type\": \"openai-compatible\",\n        \"enabled\": true,\n        \"baseUrl\": \"https://dashscope.aliyuncs.com/compatible-mode\",\n        \"apiKey\": \"sk-your-dashscope-key\",\n        \"pricingCurrency\": \"CNY\",\n        \"models\": {\n          \"qwen3.7-plus\": {\n            \"temperature\": 1,\n            \"topP\": 0.95,\n            \"topK\": 20,\n            \"extraBody\": {\n              \"preserve_thinking\": true\n            }\n          },\n          \"glm-5.1\": {\n            \"temperature\": 0.7,\n            \"topP\": 0.95,\n            \"contextCache\": true,\n            \"pricing\": {\n              \"tiers\": [\n                {\n                  \"maxInputTokens\": 32000,\n                  \"input\": 6,\n                  \"cachedInput\": 1.2,\n                  \"explicitCachedInput\": 0.6,\n                  \"cacheCreationInput\": 7.5,\n                  \"output\": 24\n                },\n                {\n                  \"maxInputTokens\": 200000,\n                  \"input\": 8,\n                  \"cachedInput\": 1.6,\n                  \"explicitCachedInput\": 0.8,\n                  \"cacheCreationInput\": 10,\n                  \"output\": 28\n                }\n              ]\n            },\n            \"extraBody\": {\n              \"preserve_thinking\": true\n            }\n          }\n        }\n      }\n    }\n  }\n  ```\n  Built-in token prices cover Codex GPT models in USD, DashScope `qwen3.7-max`, `qwen3.7-plus`, `glm-5.1`, `glm-5.2` in CNY, DeepSeek `deepseek-v4-flash`, `deepseek-v4-pro`, `deepseek-chat`, `deepseek-reasoner` in CNY, and OpenCode Go models (`glm-5.2`, `deepseek-v4-flash`, `deepseek-v4-pro`, `kimi-k2.7-code`, `mimo-v2.5`, `mimo-v2.5-pro`, `qwen3.7-plus`, `qwen3.7-max`, `minimax-m2.5`, `minimax-m3`) in USD. User `pricing` entries override built-ins. For DashScope, cached tokens are charged as explicit cache reads when the upstream usage includes `cache_creation_input_tokens`; otherwise `cachedInput` is used as the implicit cache read price. For DeepSeek, `prompt_cache_hit_tokens` map to cached input and `prompt_cache_miss_tokens` map to regular input.\n- **smallModel:** Fallback model used for tool-less warmup messages (e.g., Claude Code probe requests); defaults to gpt-5-mini.\n- **contextManagement:** Controls whether the proxy adds Responses API `context_management` compaction instructions. `messages` applies when Anthropic-style `/v1/messages` requests are translated to Responses API, including `openai-responses` provider message routes, and defaults to `true`. `responses` applies to native `/v1/responses` traffic, including `provider/model` aliases and the built-in `codex` provider, and defaults to `false`. Enable `responses` only after checking that your client supports context management compaction. When enabled, the request includes `context_management` in the body and keeps only the latest compaction carrier on follow-up turns. **Note:** Context management is forcibly disabled for GPT-5.6 and above models (e.g. `gpt-5.6-sol`, `gpt-5.6-terra`, `gpt-5.6-luna`) because enabling it breaks prompt cache hits on those models. This override takes precedence over the `contextManagement` and `modelResponsesApiCompactThresholds` settings.\n- **modelResponsesApiCompactThresholds:** Per-model Responses API `compact_threshold` overrides used when the proxy adds `context_management`. These values take precedence over the fallback threshold from `resolveResponsesCompactThreshold` (`max_prompt_tokens * ratio`, or the default fallback). Defaults set `gpt-5.4` and `gpt-5.5` to `217600` (`272000 * 0.8`), and `gpt-5.6-sol`, `gpt-5.6-terra`, `gpt-5.6-luna` to `231200` (`272000 * 0.85`). Models not listed continue to use the normal fallback logic.\n- **modelReasoningEfforts:** Per-model reasoning effort applied to `/v1/messages` requests. When routed to the Copilot native Messages API it sets `output_config.effort`; when translated to the Responses API it sets `reasoning.effort`. Allowed values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. If a model isn't listed, `high` is used by default; GPT-5.3+ models fall back to `xhigh` when not explicitly configured.\n- **useMessagesApi:** When `true`, Claude-family models that support Copilot's native `/v1/messages` endpoint will use the Messages API; otherwise they fall back to `/chat/completions`. Set to `false` to disable Messages API routing and always use `/chat/completions`. Defaults to `true`.\n- **useResponsesApiWebSocket:** When `true`, Responses API requests use Copilot's websocket transport for models that advertise `ws:/responses`; models that only advertise `/responses` continue to use HTTP. Set to `false` to disable websocket routing and use HTTP `/responses` whenever the selected model supports it. Defaults to `true`.\n- **useResponsesApiWebSearch:** When `true`, the server keeps Responses API tools with `type: \"web_search\"` and forwards them upstream. Set to `false` to strip those tools from `/responses` payloads. Defaults to `true`.\n- **messageApiWebSearchModel:** Global fallback model used when a top-level Copilot `/v1/messages` request contains only the server-side `web_search` tool. Defaults to `gpt-5-mini`. If the value is a `provider/model` alias, the request is routed into that provider's Messages API path with the provider prefix stripped. For Copilot GPT models, web search runs through `/responses`. Mixed `web_search` plus custom tools are not supported and the server-side `web_search` tool is stripped.\n- **claudeTokenMultiplier:** Multiplier applied to the fallback GPT-tokenizer estimate for Claude `/v1/messages/count_tokens` requests. Defaults to `1.15`. Increase it if your client is still compacting too late. This setting is only used when the proxy is estimating Claude tokens locally; if `anthropicApiKey` is configured and Anthropic token counting succeeds, the exact Anthropic count is returned instead.\n- **anthropicApiKey:** Anthropic API key used to forward Claude `/v1/messages/count_tokens` requests to Anthropic's real token counting endpoint, which returns exact counts instead of GPT tokenizer estimates. Can also be set via the `ANTHROPIC_API_KEY` environment variable. If not set, or if the upstream call fails, token counting falls back to local GPT tokenizer estimation controlled by `claudeTokenMultiplier`.\n\nEdit this file to customize prompts or swap in your own fast model. Restart the server (or rerun the command) after changes so the cached config is refreshed.\n\n## API Authentication\n\n- **Protected non-admin routes:** All routes except `/`, `/usage-viewer`, and `/usage-viewer/` require authentication when `auth.apiKeys` is configured and non-empty.\n- **Admin routes:** All `/admin/*` routes require `auth.adminApiKey`. If it is missing, the server generates one at startup and persists it to `config.json` before serving requests.\n- **Allowed auth headers:**\n  - `x-api-key: <your_key>`\n  - `Authorization: Bearer <your_key>`\n- **CORS preflight:** `OPTIONS` requests are always allowed.\n- **When no regular keys are configured:** Non-admin routes continue to allow requests. This does not apply to `/admin/*`, which only accepts `auth.adminApiKey`.\n\nExample request for a regular protected route:\n\n```sh\ncurl http://localhost:4141/v1/models \\\n  -H \"x-api-key: your_api_key\"\n```\n\nExample request for an admin route:\n\n```sh\ncurl http://localhost:4141/admin/config/model-mappings \\\n  -H \"x-api-key: your_admin_api_key\"\n```\n\n## API Endpoints\n\nThe server exposes several OpenAI- and Anthropic-compatible endpoints. Requests can target GitHub Copilot, the built-in `codex` provider, or configured providers depending on the selected model and `provider/model` alias.\n\n### OpenAI Compatible Endpoints\n\nThese endpoints mimic the OpenAI API structure.\n\n| Endpoint                    | Method | Description                                                      |\n| --------------------------- | ------ | ---------------------------------------------------------------- |\n| `POST /v1/responses`        | `POST` | OpenAI Most advanced interface for generating model responses. Supports `provider/model` aliases for `openai-responses` providers. |\n| `POST /v1/chat/completions` | `POST` | Creates a model response for the given chat conversation. Supports `provider/model` aliases for `openai-compatible` providers and can be used without Copilot when the target provider is configured. |\n| `GET /v1/models`            | `GET`  | Lists Copilot models plus enabled provider models using `provider/model-id` IDs. Requests from Codex clients (`User-Agent` beginning with `codex`) are forwarded to the Codex Models upstream. |\n| `POST /v1/embeddings`       | `POST` | Creates an embedding vector representing the input text.         |\n\n### Codex Backend Proxy Endpoints\n\n| Endpoint             | Method | Description |\n| -------------------- | ------ | ----------- |\n| `POST /alpha/search` | `POST` | Transparently forwards the JSON body and query parameters to the Codex Alpha Search upstream. The gateway replaces client authorization and account headers with the active Codex login, forwards compatible headers such as `accept`, `content-type`, `originator`, `user-agent`, and `cookie`, and returns the upstream status, headers, and body unchanged. |\n\n### Anthropic Compatible Endpoints\n\nThese endpoints are designed to be compatible with the Anthropic Messages API.\n\n| Endpoint                         | Method | Description                                                  |\n| -------------------------------- | ------ | ------------------------------------------------------------ |\n| `POST /v1/messages`              | `POST` | Creates a model response for a given conversation. Supports `provider/model` aliases for configured providers, including translation through `openai-compatible` providers. |\n| `POST /v1/messages/count_tokens` | `POST` | Calculates the number of tokens for a given set of messages. Supports `provider/model` aliases for configured providers. |\n| `POST /:provider/v1/messages`       | `POST` | Proxies Anthropic Messages requests to the configured Anthropic provider, translates them through an OpenAI-compatible provider, or translates them through an OpenAI Responses provider. |\n| `GET /:provider/v1/models`          | `GET`  | Proxies model listing requests to the configured provider.   |\n| `POST /:provider/v1/messages/count_tokens` | `POST` | Calculates tokens locally for provider route requests. |\n\n### Usage Monitoring Endpoints\n\nNew endpoints for monitoring your Copilot usage and quotas.\n\n| Endpoint     | Method | Description                                                  |\n| ------------ | ------ | ------------------------------------------------------------ |\n| `GET /usage` | `GET`  | Get detailed Copilot usage statistics and quota information. |\n| `GET /token` | `GET`  | Get the current Copilot token being used by the API.         |\n\n### Admin / Configuration Endpoints\n\nThese endpoints are reserved for local administrative actions and only accept `auth.adminApiKey`.\n\n| Endpoint                              | Method | Description                                                                 |\n| ------------------------------------- | ------ | --------------------------------------------------------------------------- |\n| `GET /admin/config/model-mappings`    | `GET`  | Returns the current `config.json` path and the active `modelMappings` map.  |\n| `POST /admin/config/model-mappings`   | `POST` | Updates only the `modelMappings` field in `config.json` and returns it back. |\n\n## Example Usage\n\nCommon `npx` commands:\n\n```sh\n# Start the gateway\nnpx @jeffreycao/copilot-api@latest start\n\n# Start on a custom port with verbose logging\nnpx @jeffreycao/copilot-api@latest start --port 8080 --verbose\n\n# Run the auth flow\nnpx @jeffreycao/copilot-api@latest auth login\n\n# Configure a third-party provider, then run without GitHub Copilot\nnpx @jeffreycao/copilot-api@latest auth login --provider dashscope\nnpx @jeffreycao/copilot-api@latest start\n\n# Print debug information as JSON\nnpx @jeffreycao/copilot-api@latest debug --json\n\n# Run the published CLI with Bun instead of Node.js\nbunx --bun @jeffreycao/copilot-api@latest start\n```\n\nOpenAI-compatible provider examples after configuring `dashscope`:\n\n```sh\ncurl http://localhost:4141/v1/chat/completions \\\n  -H \"content-type: application/json\" \\\n  -d '{\"model\":\"dashscope/qwen3.6-plus\",\"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]}'\n\ncurl http://localhost:4141/dashscope/v1/messages \\\n  -H \"content-type: application/json\" \\\n  -d '{\"model\":\"qwen3.6-plus\",\"max_tokens\":1024,\"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]}'\n```\n\n## Usage Tips\n\n### CLAUDE.md or AGENTS.md Recommended Content\n\nTo add these reminders manually, include the following in `CLAUDE.md` for Claude Code, or `AGENTS.md` for opencode/codex:\n\n```\n- Prohibited from directly asking questions to users, MUST use question tool.\n- Once you can confirm that the task is complete, MUST use question tool to make user confirm. The user may respond with feedback if they are not satisfied with the result, which you can use to make improvements and try again, after try again, MUST use question tool to make user confirm again.\n```\n"}, "a23edf6fd0b46cf7f2ca2034954c4a6acf1ee408": {"t": 1785765561.3276074, "n": 47593, "h": "2d167f58848700ca", "c": "# Copilot API Proxy\n\nEnglish | [简体中文](./README.zh-CN.md)\n\n## Important Notes\n\n> [!IMPORTANT]\n> **Before using, please be aware of the following:**\n>\n> 1. **Claude Code configuration:** When using with Claude Code, please configure the model ID as `claude-opus-4-8`. Example claude `settings.json` see [Manual Configuration with `settings.json`](#manual-configuration-with-settingsjson). \n>\n> 2. **Built-in `copilot`, `codex` and third-party providers:** Run `npx @jeffreycao/copilot-api@latest auth` and choose `copilot`, `codex`, `deepseek`, `custom`, or other providers.\n>\n> 3. **Note:** See [GitHub Copilot Security Notice](./NOTICE.md#github-copilot-security-notice) for the warning removed from the README header.\n\n---\n\n## Project Overview\n\nA small AI gateway that can use GitHub Copilot, the built-in `codex` provider, or configured third-party providers such as DashScope. GitHub Copilot is optional: if no GitHub token is available, the server can still start in provider-only mode as long as at least one enabled provider is configured.\n\nThe gateway exposes OpenAI- and Anthropic-compatible APIs from one local endpoint, so tools like [Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview), OpenCode, Codex, and OpenAI-compatible clients can share the same local server.\n\nOn the GitHub Copilot path, the gateway prefers Copilot's native Anthropic-style Messages API when available, preserving more Claude-native behavior for tool-heavy workflows.\n\n## Features\n\n- **OpenAI and Anthropic compatibility**: Serve `/v1/responses`, `/v1/chat/completions`, `/v1/models`, `/v1/embeddings`, and `/v1/messages` from one local gateway.\n- **Copilot is optional**: Use GitHub Copilot when credentials are present, or run the server with only configured providers.\n- **One gateway for Copilot, `codex`, and external providers**: Route GitHub Copilot, the built-in `codex` provider, and configured third-party providers behind the same endpoint.\n- **Standalone third-party providers**: Configure providers such as DashScope, DeepSeek, OpenRouter, or a custom provider and start the gateway without a GitHub Copilot login.\n- **OpenAI-compatible providers on chat and Messages APIs**: `openai-compatible` providers can serve top-level `/v1/chat/completions` through `model: \"provider/model\"` and Anthropic-style `/v1/messages` through request/response translation.\n- **Agent-friendly Claude handling on Copilot**: Prefer native `/v1/messages` when available, preserve Claude-style tool flows, support Anthropic beta features, Claude WebSearch through Responses-capable models, and keep subagent/session markers intact.\n- **Claude Code and OpenCode integration**: Works with Claude Code and OpenCode, including direct Anthropic-compatible usage through `@ai-sdk/anthropic`.\n- **Flexible auth and deployment options**: Supports interactive login or direct tokens, individual/business/enterprise plans, GitHub Enterprise, opencode OAuth, and custom data directories.\n- **Multi-provider routing**: Expose provider-specific `/:provider/...` routes or use `model: \"provider/model\"` on the top-level API.\n\n## Prerequisites\n\n- Bun (>= 1.2.x)\n- Node.js if you plan to run the published CLI with `npx`\n- GitHub account with Copilot subscription only if you want to use the GitHub Copilot provider\n- An API key or OAuth login for at least one configured provider if you want to run without GitHub Copilot\n\n## Installation\n\nTo install dependencies, run:\n\n```sh\nbun install\n```\n\nTo start the server directly from source:\n\n```sh\nbun run start start\n```\n\n## Running from Source\n\nThe project can be run from source in several ways:\n\n### Development Mode\n\n```sh\nbun run dev start\n```\n\n### Production Mode\n\n```sh\nbun run start start\n```\n\n## Using with npx\n\nYou can run the project directly using npx:\n\n> [!IMPORTANT]\n> Token usage storage uses Node's built-in `node:sqlite` module when running with `npx`. It is enabled on Node.js >= 22.13.0. On Node.js < 22.13.0, the CLI still starts, but token usage storage is disabled.\n>\n> If you want token usage storage without upgrading Node.js, run the published CLI with Bun instead: `bunx --bun @jeffreycao/copilot-api@latest start`.\n\n```sh\nnpx @jeffreycao/copilot-api@latest start\n```\n\nWith options:\n\n```sh\nnpx @jeffreycao/copilot-api@latest start --port 8080\n```\n\nFor authentication or provider configuration only:\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth\n```\n\nTo run without GitHub Copilot, configure at least one provider first, then start the server normally:\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth login --provider dashscope\nnpx @jeffreycao/copilot-api@latest start\n```\n\n## Using with Docker\n\nBuild the image:\n\n```sh\ndocker build -t copilot-api .\n```\n\nRun the container with a bind mount so auth data survives restarts:\n\n```sh\nmkdir -p ./copilot-data\ndocker run -p 4141:4141 -v $(pwd)/copilot-data:/root/.local/share/copilot-api copilot-api\n```\n\nThis stores GitHub auth data, provider config, and other gateway state in `./copilot-data` on the host, mapped to `/root/.local/share/copilot-api` in the container.\n\nOr pass a GitHub token directly:\n\n```sh\ndocker run -p 4141:4141 -e GH_TOKEN=your_github_token_here copilot-api\n```\n\n## Electron Desktop App\n\nIf you prefer a GUI, this repository also includes an Electron desktop app in `desktop/`. It supports GitHub Copilot sign-in, OpenAI Codex OAuth, and API-key configuration for DeepSeek, DashScope, OpenRouter, or a custom provider. After authorization or provider configuration, it can start and stop the local proxy with one click and shows the local endpoint, auth header, available models, usage, and logs in the app.\n\nThe settings screen also exposes `OAuth App`, `API Home`, `Enterprise URL`, verbose logging, and minimize-to-tray. Desktop packages are published in GitHub Releases:\n\nhttps://github.com/caozhiyuan/copilot-api/releases\n\nDownload the installer for your platform, authorize or configure a provider inside the app, choose a port, start the server, then point your client at the local endpoint shown in the app. Packaged desktop builds use the bundled Electron runtime, so normal desktop usage does not require installing Node.js separately. Token usage history is enabled when that bundled runtime supports SQLite.\n\nThe desktop app's Advanced Config page reads and writes the shared model mappings through `GET/POST /admin/config/model-mappings`. The same mappings apply across `POST /v1/messages`, `POST /v1/messages/count_tokens`, `POST /v1/responses`, and `POST /v1/chat/completions` instead of being split per interface. It uses `auth.adminApiKey` instead of the regular `auth.apiKeys`, and the app reads that key directly from `config.json` after the server has generated it on startup.\n\n### Desktop App Screenshots\n\nMain dashboard, token usage breakdown in the bundled Electron app:\n\n<p align=\"center\">\n  <img src=\"./docs/screenshots/desktop-dashboard.png\" alt=\"Copilot API desktop app dashboard\" width=\"49%\" />\n  <img src=\"./docs/screenshots/desktop-token-usage.png\" alt=\"Copilot API desktop app token usage view\" width=\"49%\" />\n</p>\n\n## Using with Claude Code\n\nThis AI gateway can be used to power [Claude Code](https://docs.anthropic.com/en/claude-code), an experimental conversational AI assistant for developers from Anthropic.\n\nThere are two ways to configure Claude Code to use this AI gateway:\n\n### Interactive Setup with `--claude-code` flag\n\nTo get started, run the `start` command with the `--claude-code` flag:\n\n```sh\nnpx @jeffreycao/copilot-api@latest start --claude-code\n```\n\nYou will be prompted to select a primary model and a \"small, fast\" model for background tasks. After selecting the models, a command will be copied to your clipboard. This command sets the necessary environment variables for Claude Code to use the gateway.\n\nPaste and run this command in a new terminal to launch Claude Code.\n\n### Manual Configuration with `settings.json`\n\nAlternatively, you can configure Claude Code by creating a `.claude/settings.json` file in your project's root directory. This file should contain the environment variables needed by Claude Code. This way you don't need to run the interactive setup every time.\n\nHere is an example `.claude/settings.json` file:\n\n```json\n{\n  \"env\": {\n    \"ANTHROPIC_BASE_URL\": \"http://localhost:4141\",\n    \"ANTHROPIC_AUTH_TOKEN\": \"dummy\",\n    \"ANTHROPIC_MODEL\": \"deepseek/deepseek-v4-pro\",\n    \"ANTHROPIC_DEFAULT_SONNET_MODEL\": \"deepseek/deepseek-v4-pro\",\n    \"ANTHROPIC_DEFAULT_HAIKU_MODEL\": \"deepseek/deepseek-v4-flash\",\n    \"DISABLE_NON_ESSENTIAL_MODEL_CALLS\": \"1\",\n    \"CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC\": \"1\",\n    \"CLAUDE_CODE_ATTRIBUTION_HEADER\": \"0\",\n    \"CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION\": \"false\",\n    \"CLAUDE_CODE_DISABLE_TERMINAL_TITLE\": \"true\",\n    \"CLAUDE_CODE_ENABLE_AWAY_SUMMARY\": \"0\"\n  },\n  \"permissions\": {\n    \"deny\": [\n      \"mcp__ide__executeCode\"\n    ]\n  }\n}\n```\n\n- Replace `ANTHROPIC_MODEL`, `ANTHROPIC_DEFAULT_OPUS_MODEL`, `ANTHROPIC_DEFAULT_SONNET_MODEL`, and `ANTHROPIC_DEFAULT_HAIKU_MODEL` according to your needs. After configuration, please install the claude code plugin [Plugin Integrations](#plugin-integrations).  \n- Setting CLAUDE_CODE_ATTRIBUTION_HEADER to 0 can prevent Claude code from adding billing and version information in system prompts, thereby avoiding prompt cache invalidation.\n- Turning off CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION and CLAUDE_CODE_ENABLE_AWAY_SUMMARY can prevent quota from being consumed unnecessarily.\n- Claude Code WebSearch is supported for pure search requests. For Copilot, keep the global `messageApiWebSearchModel` set to a Responses-capable GPT model or a `provider/model` alias. For provider routes, use a native Anthropic provider or an `openai-responses` provider. Add `WebSearch` to `permissions.deny` only if you want to forbid this traffic.\n- If using a non-Claude model, do not enable ENABLE_TOOL_SEARCH. If using the Claude model, can enable ENABLE_TOOL_SEARCH. The current Claude Code uses the client tool search mode. In this mode, loading defer tools requires an additional request each time.\n- `CLAUDE_CODE_AUTO_COMPACT_WINDOW`: Set the context capacity in tokens used for auto-compaction calculations. Defaults to the model's context window: 200K for standard models or 1M for extended context models. Use a lower value like `500000` on a 1M model (e.g., `claude-opus-4-6[1m]`) to treat the window as 500K for compaction purposes. The value is capped at the model's actual context window. `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` is applied as a percentage of this value. Setting this variable decouples the compaction threshold from the status line's `used_percentage`, which always uses the model's full context window.\n\nYou can find more options here: [Claude Code settings](https://docs.anthropic.com/en/docs/claude-code/settings#environment-variables)\n\nYou can also read more about IDE integration here: [Add Claude Code to your IDE](https://docs.anthropic.com/en/docs/claude-code/ide-integrations)\n\n## Using with OpenCode\n\nOpenCode already has a direct GitHub Copilot provider. Use this section when you want OpenCode to point at this AI gateway through `@ai-sdk/anthropic` and reuse the agent behaviors described earlier in this README.\n\n### Minimal setup\n\nStart the AI gateway with the OpenCode OAuth app:\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth --oauth-app=opencode\nnpx @jeffreycao/copilot-api@latest start\n```\n\nThen point OpenCode at the gateway with `@ai-sdk/anthropic`.\n\nExample `~/.config/opencode/opencode.json`:\n\n```json\n{\n  \"$schema\": \"https://opencode.ai/config.json\",\n  \"provider\": {\n    \"local\": {\n      \"npm\": \"@ai-sdk/anthropic\",\n      \"name\": \"My Local\",\n      \"options\": {\n        \"baseURL\": \"http://localhost:4141/v1\",\n        \"apiKey\": \"dummy\"\n      },\n      \"models\": {\n        \"gpt-5.4\": {\n          \"name\": \"gpt-5.4\",\n          \"modalities\": {\n            \"input\": [\"text\", \"image\"],\n            \"output\": [\"text\"]\n          },\n          \"limit\": {\n            \"context\": 400000,\n            \"input\": 272000,\n            \"output\": 128000\n          }\n        },\n        \"claude-sonnet-4.6\": {\n          \"id\": \"claude-sonnet-4.6\",\n          \"name\": \"claude-sonnet-4.6\",\n          \"modalities\": {\n            \"input\": [\"text\", \"image\"],\n            \"output\": [\"text\"]\n          },          \n          \"limit\": {\n            \"context\": 200000,\n            \"output\": 32000\n          },\n          \"options\": {\n            \"thinking\": {\n              \"type\": \"adaptive\"\n            },\n            \"effort\": \"max\"\n          }\n        }\n      }\n    }\n  }\n}\n```\n\nWhy these fields matter:\n\n- `npm: \"@ai-sdk/anthropic\"` is the important part. OpenCode will speak Anthropic Messages semantics to this AI gateway instead of flattening everything into OpenAI Chat Completions.\n- `options.baseURL` should be `http://localhost:4141/v1`; the Anthropic SDK will append `/messages`, `/models`, and `/messages/count_tokens` automatically.\n- If you enable `auth.apiKeys` in this AI gateway, replace `dummy` with a real key. Otherwise any placeholder value is fine.\n\n## Using with Codex\n\nThis AI gateway can also power Codex.\n\n### Codex `config.toml` Reference\n\nAdd the following `[model_providers.copilot_api]` section to your Codex `~/.codex/config.toml`:\n\n```toml\nmodel_provider = \"copilot_api\"\nmodel_reasoning_summary = \"auto\"\nmodel_verbosity = \"medium\"\nmodel_context_window = 272000\nmodel_auto_compact_token_limit = 244800\n\n[model_providers.copilot_api]\nname = \"OpenAI\"\nbase_url = \"http://localhost:4141\"\nenv_key = \"GITHUB_COPILOT_API_KEY\"\nrequires_openai_auth = true\nsupports_websockets = false\nwire_api = \"responses\"\nrequest_max_retries = 3\nstream_max_retries = 1\nstream_idle_timeout_ms = 300000\n\n[features]\nremote_compaction_v2 = true\n\n[analytics]\nenabled = false\n```\n\n> [!NOTE]\n> This configuration is specific to Codex and the GitHub Copilot provider. `name` must be set to `\"OpenAI\"`. It can help mitigate Codex local compact cache miss issues. If you enable `contextManagement.responses` (Responses API context management compaction), `remote_compaction_v2` or local compact is generally not triggered, but it may still occur when tool results return a large number of tokens. Before enabling it for native Responses API traffic, check that your client supports context management compaction.\n\n## GPT Tool Search\n\nFor GPT Responses models such as `gpt-5.4+`, this AI gateway can expose Responses `tool_search` through a small MCP bridge. The same bridge can be used by Claude Code and opencode, as long as the client loads MCP servers and sends Anthropic Messages traffic through this gateway.\n\nDo not set Claude Code's native `ENABLE_TOOL_SEARCH` for GPT models. That flag enables Claude Code's own client-side tool search mode, and it may stop forwarding deferred tool definitions. This gateway needs the full tool definitions so it can keep the small always-loaded tool set eager and translate every other tool into Responses deferred namespaces.\n\nIf you install `tool-search@copilot-api-marketplace`, Claude Code receives this MCP bridge automatically and you can skip the manual Claude Code MCP setup below.\n\nAdd the tool search bridge to the MCP config used by Claude Code:\n\n```json\n{\n  \"mcpServers\": {\n    \"tool_search\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@jeffreycao/copilot-api@latest\", \"mcp\"]\n    }\n  }\n}\n```\n\nAdd the tool search bridge to the MCP config used by opencode:\n\n```json\n{\n  \"mcp\": {\n    \"tool_search\": {\n      \"type\": \"local\",\n      \"command\": [\"npx\", \"-y\", \"@jeffreycao/copilot-api@latest\", \"mcp\"]\n    }\n  }\n}\n```\n\nFor local development, use `bun` as the command and `[\"run\", \"./src/main.ts\", \"mcp\"]` as the args.\n\nInternally, the gateway now configures OpenAI Responses `tool_search` in client-executed mode. Deferred tools are still exposed as searchable namespaces, but the model is explicitly asked to return the exact deferred tool names it wants to load next.\n\nThe bridge uses direct tool selection, not query search. Its tool input is `names`, a comma-separated list of exact deferred tool names, for example `TaskList,TaskGet,mcp__fetch__fetch`.\n\n## Plugin Integrations\n\nPlugin integrations are available for Claude Code and opencode.\n\n#### Claude Code plugin integration (marketplace-based)\n\nThe Claude Code integration is packaged as two plugins:\n\n- `agent-inject` injects `__SUBAGENT_MARKER__...` on `SubagentStart`, so the gateway can infer `x-initiator: agent`.\n- `tool-search` registers the `tool_search` MCP bridge used for GPT Responses deferred tool loading.\n\n- Marketplace catalog in this repository: `.claude-plugin/marketplace.json`\n- Plugin sources in this repository: `plugin/claude/agent-inject`, `plugin/claude/tool-search`\n\nAdd the marketplace remotely:\n\n```sh\n/plugin marketplace add https://github.com/caozhiyuan/copilot-api.git\n```\n\nInstall the plugins from the marketplace:\n\n```sh\n/plugin install agent-inject@copilot-api-marketplace\n/plugin install tool-search@copilot-api-marketplace\n```\n\nAfter installation, `agent-inject` injects `__SUBAGENT_MARKER__...` on `SubagentStart`, and the gateway uses it to infer `x-initiator: agent`.\n\nThe `agent-inject` plugin also registers a `UserPromptSubmit` hook that returns `{\"continue\": true}`, and it can inject `SessionStart` reminder rules through environment variables:\n\n- `CLAUDE_PLUGIN_ENABLE_QUESTION_RULES=1` enables the two reminders about using the `question` tool automatically for Claude Code. Alternatively, you can add the same reminders manually in `CLAUDE.md`; see [CLAUDE.md or AGENTS.md Recommended Content](#claudemd-or-agentsmd-recommended-content).\n- `CLAUDE_PLUGIN_ENABLE_NO_BACKGROUND_AGENTS_RULE=1` enables the `run_in_background: true` avoidance reminder for agent hooks.\n\nThe `tool-search` plugin bundles the same MCP bridge described in [GPT Tool Search](#gpt-tool-search), so Claude Code users do not need to add the `tool_search` server manually when they install that plugin.\n\n#### Opencode plugin\n\nThe subagent marker producer is packaged as an opencode plugin located at `plugin/opencode/subagent-marker.js`.\n\n**Installation:**\n\nCopy the plugin file to your opencode plugins directory:\n\n```sh\n# Clone or download this repository, then copy the plugin\ncp plugin/opencode/subagent-marker.js ~/.config/opencode/plugins/\n```\n\nOr manually create the file at `~/.config/opencode/plugins/subagent-marker.js` with the plugin content.\n\n**Features:**\n\n- Tracks sub-sessions created by subagents\n- Automatically prepends a marker system reminder (`__SUBAGENT_MARKER__...`) to subagent chat messages\n- Sets `x-session-id` header for session tracking\n- Enables the gateway to infer `x-initiator: agent` for subagent-originated requests\n\nThe plugin hooks into `session.created`, `session.deleted`, `chat.message`, and `chat.headers` events to provide seamless subagent marker functionality.\n\n## Using the Usage Viewer\n\nAfter starting the server, a URL to the Copilot Usage Dashboard will be displayed in your console. This dashboard is a web interface for monitoring your API usage.\n\n1.  Start the server. For example, using npx:\n    ```sh\n    npx @jeffreycao/copilot-api@latest start\n    ```\n2.  The server will output a URL to the usage viewer. Copy and paste this URL into your browser. It will look something like this:\n    `http://localhost:4141/usage-viewer?endpoint=http://localhost:4141/usage`\n    - If you use the `start.bat` script on Windows, this page will open automatically.\n\nThe dashboard provides a user-friendly interface to view your Copilot usage data:\n\n> Token usage history requires Bun or Node.js >= 22.13.0. On Node.js < 22.13.0, the server runs normally but token usage storage is disabled.\n\n- **API Endpoint URL**: The dashboard is pre-configured to fetch data from your local server endpoint via a URL query parameter. You can manually switch this to any other compatible API endpoint.\n- **x-api-key Authentication**: If API Key authentication is enabled, you can provide the `x-api-key` request header. The key is persisted in the browser's local storage.\n- **Period Selector**: Choose from Day, Week, or Month time ranges. The URL query parameter updates automatically when you switch, making it easy to bookmark and share.\n- **Fetch Data**: Click the \"Refresh\" button to load or refresh the usage data. The dashboard also fetches data automatically on page load.\n- **Copilot Quotas**: View quota usage for services such as Chat and Completions via progress bars. Hover over a card to see used/remaining details.\n- **Token Usage Metric Cards**: See a summary of Total, Input, Output, Cache Read, Cache Write, Requests, and estimated cost for the current period.\n- **Trend Chart (Week / Month)**: An interactive line chart with model and metric filters. Click a data point to inspect the usage breakdown for a specific day.\n- **Model Breakdown Table**: A per-model summary of requests, input/output/cache tokens, and estimated cost for the selected period.\n- **Request Events (Paginated)**: A time-sorted list of request event records with pagination support, showing timestamps, models, request IDs, and token counts.\n- **Detailed Information**: See the full JSON response from the API for a detailed breakdown of all available usage statistics.\n- **URL-based Configuration**: You can also specify the API endpoint and period directly via `endpoint` and `period` query parameters. For example:\n  `http://localhost:4141/usage-viewer?endpoint=http://your-api-server/usage&period=week`\n\n### Usage Viewer Screenshot\n\n<p align=\"center\">\n  <img src=\"./docs/screenshots/usage-viewer.png\" alt=\"Copilot API usage viewer\" width=\"900\" />\n</p>\n\n## Command Structure\n\nCopilot API now uses a subcommand structure with these main commands:\n\n- `start`: Start the gateway server. If a GitHub token is available, the server starts with Copilot enabled. If no GitHub token is available, it starts in provider-only mode when at least one enabled provider exists; otherwise it guides you through provider setup.\n- `auth`: Run provider login or configuration without starting the server. Use it for GitHub Copilot login, Codex OAuth, or third-party provider API key setup.\n- `debug`: Display diagnostic information including version, runtime details, file paths, and authentication status. Useful for troubleshooting and support.\n\n## Command Line Options\n\n### Global Options\n\nThe following options can be used with any subcommand. When passing them before the subcommand, use the `--key=value` form:\n\n| Option            | Description                                            | Default | Alias |\n| ----------------- | ------------------------------------------------------ | ------- | ----- |\n| --api-home        | Path to the API home directory (sets COPILOT_API_HOME) | none    | none  |\n| --oauth-app       | OAuth app identifier (sets COPILOT_API_OAUTH_APP)      | none    | none  |\n| --enterprise-url  | Enterprise URL for GitHub (sets COPILOT_API_ENTERPRISE_URL) | none | none |\n\n### Start Command Options\n\nThe following command line options are available for the `start` command:\n\n| Option         | Description                                                                   | Default    | Alias |\n| -------------- | ----------------------------------------------------------------------------- | ---------- | ----- |\n| --port         | Port to listen on                                                             | 4141       | -p    |\n| --verbose      | Enable verbose logging                                                        | false      | -v    |\n| --github-token | Provide GitHub token directly (must be generated using the `auth` subcommand) | none       | -g    |\n| --claude-code  | Generate a command to launch Claude Code with Copilot API config              | false      | -c    |\n| --show-token   | Show GitHub and Copilot tokens on fetch and refresh                           | false      | none  |\n| --proxy-env    | Initialize proxy from environment variables                                   | false      | none  |\n\n### Auth Command Options\n\n| Option       | Description               | Default | Alias |\n| ------------ | ------------------------- | ------- | ----- |\n| --provider   | Provider to log in with or configure (`copilot`, `codex`, `opencode-go`, `deepseek`, `dashscope`, `openrouter`, or `custom`) | prompt | none |\n| --verbose    | Enable verbose logging    | false   | -v    |\n| --show-token | Show GitHub token on auth | false   | none  |\n\nUse `copilot-api auth login --provider copilot` only when you want to enable the GitHub Copilot provider. Copilot is not required for `codex` or third-party provider-only usage.\n\nUse `copilot-api auth login --provider deepseek`, `--provider dashscope`, `--provider openrouter`, or `--provider opencode-go` to add or update those common third-party providers from the CLI. DeepSeek prompts for masked `apiKey`, provider `type` (default `anthropic`), and `baseUrl` defaulting to `https://api.deepseek.com/anthropic`. DashScope prompts for masked `apiKey`, provider `type` (default `openai-compatible`), and prefilled `baseUrl`. OpenRouter prompts for masked `apiKey` and prefilled `baseUrl` only, and writes `type: \"anthropic\"`. OpenCode Go prompts for masked `apiKey` and prefilled `baseUrl` only, and writes `type: \"openai-compatible\"` (baseUrl `https://opencode.ai/zen/go`). After a provider is configured and enabled, `copilot-api start` can run without any GitHub token.\n\nUse `copilot-api auth login --provider custom` to add or update another third-party provider from the CLI. The command prompts for the provider name, supported type (`anthropic`, `openai-compatible`, or `openai-responses`), `baseUrl`, masked `apiKey`, and `authType`; `authType` may be left as the type default or set to `x-api-key` / `authorization`.\n\n### Debug Command Options\n\n| Option | Description               | Default | Alias |\n| ------ | ------------------------- | ------- | ----- |\n| --json | Output debug info as JSON | false   | none  |\n\n## Configuration (config.json)\n\n- **Location:** `~/.local/share/copilot-api/config.json` (Linux/macOS) or `%USERPROFILE%\\.local\\share\\copilot-api\\config.json` (Windows).\n- **Default shape:**\n  ```json\n  {\n    \"auth\": {\n      \"apiKeys\": [],\n      \"adminApiKey\": \"<auto-generated-on-startup>\"\n    },\n    \"providers\": {},\n    \"modelMappings\": {},\n    \"extraPrompts\": {\n      \"gpt-5-mini\": \"<built-in exploration prompt>\"\n    },\n    \"smallModel\": \"gpt-5-mini\",\n    \"contextManagement\": {\n      \"messages\": true,\n      \"responses\": false\n    },\n    \"modelResponsesApiCompactThresholds\": {\n      \"gpt-5.4\": 217600,\n      \"gpt-5.5\": 217600,\n      \"gpt-5.6-sol\": 231200,\n      \"gpt-5.6-terra\": 231200,\n      \"gpt-5.6-luna\": 231200\n    },\n    \"modelReasoningEfforts\": {\n      \"gpt-5-mini\": \"low\"\n    },\n    \"useMessagesApi\": true,\n    \"useResponsesApiWebSocket\": true,\n    \"useResponsesApiWebSearch\": true,\n    \"messageApiWebSearchModel\": \"gpt-5-mini\"\n  }\n  ```\n- **auth.apiKeys:** API keys used for request authentication on non-admin routes. Supports multiple keys for rotation. Requests can authenticate with either `x-api-key: <key>` or `Authorization: Bearer <key>`. If empty or omitted, authentication for non-admin routes is disabled.\n- **auth.adminApiKey:** Single admin key used only for `/admin/*` routes. If missing, the server generates a random key at startup and writes it back to `config.json`. Requests use the same `x-api-key` or `Authorization: Bearer` headers, but regular `auth.apiKeys` never grant access to `/admin/*`.\n- **modelMappings:** Exact `sourceModel -> targetModel` rewrites shared by top-level `POST /v1/messages`, `POST /v1/messages/count_tokens`, `POST /v1/responses`, and `POST /v1/chat/completions` requests. Omit it or leave it as `{}` to disable rewrites. Both the source and target must be non-empty strings. Targets can be regular model IDs or `provider/model` aliases such as `dashscope/qwen3.6-plus`, and the rewrite happens before provider alias parsing. These mappings are not split per interface. The admin endpoints `GET/POST /admin/config/model-mappings` read and update only this field.\n- **extraPrompts:** Map of `model -> prompt` appended to the first system prompt when translating Anthropic-style requests to Responses API. Use this to inject guardrails or guidance per model. Missing default entries are auto-added without overwriting your custom prompts. For GPT-5.3+ models (e.g. `gpt-5.3-codex`, `gpt-5.4`, `gpt-5.5`), a built-in commentary prompt is used as fallback when not explicitly configured. The built-in prompts enable phase-aware commentary, which lets the model emit a short user-facing progress update before tools or deeper reasoning.\n- **providers:** Global upstream provider map. Each provider key (for example `dashscope`) becomes a route prefix (`/dashscope/v1/messages`). Supports `type: \"anthropic\"`, `type: \"openai-compatible\"`, and `type: \"openai-responses\"`. Top-level clients can also use `model: \"dashscope/model-id\"` with `/v1/messages`, `/v1/messages/count_tokens`, `/v1/responses`, and `/v1/chat/completions`; the gateway strips the `dashscope/` prefix before forwarding upstream. `openai-compatible` providers support both chat and Messages flows: `/v1/chat/completions` is proxied to upstream `/v1/chat/completions`, while `/v1/messages` and `/:provider/v1/messages` are translated to upstream chat completions and translated back to Anthropic Messages responses. `GET /v1/models` aggregates enabled provider models with `provider/model-id` IDs; use `GET /dashscope/v1/models` for a single provider's raw model list.\n  - `enabled` defaults to `true` if omitted.\n  - `baseUrl` should be provider API base URL without the final endpoint. For Anthropic providers, omit `/v1/messages`; for OpenAI-compatible providers, omit `/v1/chat/completions`; for OpenAI Responses providers, omit `/v1/responses`.\n  - `apiKey` is used as the upstream credential value and is required for regular providers.\n  - `authType` (optional): Controls how `apiKey` is sent upstream. Supports `x-api-key` and `authorization` for regular providers. Anthropic providers default to `x-api-key`; OpenAI-compatible and OpenAI Responses providers default to `authorization`. When set to `authorization`, the proxy sends `Authorization: Bearer <apiKey>`. `oauth2` is reserved for the built-in `codex` provider and is written automatically by `auth login --provider codex`.\n  - `pricingCurrency` (optional): Provider-level currency used for token cost calculation, for example `USD` or `CNY`. Quick providers default to `CNY` for DashScope and DeepSeek, and `USD` for Codex/OpenRouter. Costs are grouped by currency and are not exchange-rate converted.\n  - `models` (optional): Per-model configuration map. Each key is a model ID (matching the model name in requests), and the value is:\n    - `temperature` (optional): Default temperature value used when the request does not specify one.\n    - `topP` (optional): Default top_p value used when the request does not specify one.\n    - `topK` (optional): Default top_k value used when the request does not specify one.\n    - `extraBody` (optional): Dynamic fields merged into the upstream request body for that model. Request body fields with the same name take precedence. OpenAI-compatible providers can use this for fields such as `enable_thinking`, `preserve_thinking`, `reasoning_effort`. `thinking_budget` is a special OpenAI-compatible provider override: when configured in `extraBody`, it is forced after Anthropic `thinking.budget_tokens` translation and overrides the request-derived budget. For providers whose name is `dashscope` or whose `baseUrl` contains `aliyuncs.com`, the request-derived `thinking_budget` (from Anthropic `thinking.budget_tokens`) is forwarded upstream; for other OpenAI-compatible providers the request-derived `thinking_budget` is stripped, while an `extraBody` `thinking_budget` is still honored. For DashScope providers, `preserve_thinking` defaults to `true` when not explicitly set in `extraBody` or the request body.\n    - `pricing` (optional): Per-model token prices, in the provider `pricingCurrency`, per 1M tokens. Supported fields are `input`, `output`, `cachedInput` (implicit cache read), `explicitCachedInput` (explicit cache read), and `cacheCreationInput`. Use `tiers` with `maxInputTokens` for input-size tiered pricing.\n    - `contextCache` (optional): Defaults to `true` for providers whose name is `dashscope` or whose `baseUrl` contains `aliyuncs.com`; defaults to `false` for other OpenAI-compatible providers. This enables Alibaba Cloud Model Studio/DashScope explicit context cache by injecting `cache_control: { \"type\": \"ephemeral\" }` on up to 4 content blocks using the Context Cache format. The cache breakpoint strategy matches opencode's main provider flow: the first 2 system messages plus the last 2 non-system messages. Marked string content is converted to text content part arrays for `system` / `user` / `assistant` / `tool` messages; existing array content is marked on the last part. Set this to `false` when the model already supports implicit caching, or when the upstream does not accept this explicit-cache extension field. Set this to `true` for non-DashScope providers that support the same explicit-cache extension. Applied on both `/v1/messages` and `/v1/chat/completions` routes.\n    - `supportPdf` (optional): Controls whether the model supports PDF/document content. Defaults to `false`; unsupported PDFs are converted to a text notice. Set it to `true` to send PDF/document blocks as OpenAI Chat Completions file parts.\n    - `toolContentSupportType` (optional): Tool result content capabilities for that model, as an array of `array`, `image`, and `pdf`. Provider routes default to string-only tool content when omitted. If `supportPdf` is `true` but this list does not include `pdf`, file parts in tool results are moved to user role messages. This provider default does not change the Copilot main flow, which continues to support array + image and not PDF.\n    - `type` (optional): Per-model override of the provider protocol type. Supports `anthropic`, `openai-compatible`, and `openai-responses`. When set, the provider's `/v1/messages` route uses this model's type instead of the provider-level type for request routing, auth header resolution, and upstream endpoint selection. This is useful for providers like OpenCode Go whose upstream supports both OpenAI-compatible and Anthropic Messages APIs for different models. When the type is overridden, the auth header is resolved from the overridden type's default (Anthropic defaults to `x-api-key`; OpenAI-compatible/Responses default to `authorization`).\n\n  Example DashScope model settings:\n  ```json\n  {\n    \"providers\": {\n      \"dashscope\": {\n        \"type\": \"openai-compatible\",\n        \"enabled\": true,\n        \"baseUrl\": \"https://dashscope.aliyuncs.com/compatible-mode\",\n        \"apiKey\": \"sk-your-dashscope-key\",\n        \"pricingCurrency\": \"CNY\",\n        \"models\": {\n          \"qwen3.7-plus\": {\n            \"temperature\": 1,\n            \"topP\": 0.95,\n            \"topK\": 20,\n            \"extraBody\": {\n              \"preserve_thinking\": true\n            }\n          },\n          \"glm-5.1\": {\n            \"temperature\": 0.7,\n            \"topP\": 0.95,\n            \"contextCache\": true,\n            \"pricing\": {\n              \"tiers\": [\n                {\n                  \"maxInputTokens\": 32000,\n                  \"input\": 6,\n                  \"cachedInput\": 1.2,\n                  \"explicitCachedInput\": 0.6,\n                  \"cacheCreationInput\": 7.5,\n                  \"output\": 24\n                },\n                {\n                  \"maxInputTokens\": 200000,\n                  \"input\": 8,\n                  \"cachedInput\": 1.6,\n                  \"explicitCachedInput\": 0.8,\n                  \"cacheCreationInput\": 10,\n                  \"output\": 28\n                }\n              ]\n            },\n            \"extraBody\": {\n              \"preserve_thinking\": true\n            }\n          }\n        }\n      }\n    }\n  }\n  ```\n  Built-in token prices cover Codex GPT models in USD, DashScope `qwen3.7-max`, `qwen3.7-plus`, `glm-5.1`, `glm-5.2` in CNY, DeepSeek `deepseek-v4-flash`, `deepseek-v4-pro`, `deepseek-chat`, `deepseek-reasoner` in CNY, and OpenCode Go models (`glm-5.2`, `deepseek-v4-flash`, `deepseek-v4-pro`, `kimi-k2.7-code`, `mimo-v2.5`, `mimo-v2.5-pro`, `qwen3.7-plus`, `qwen3.7-max`, `minimax-m2.5`, `minimax-m3`) in USD. User `pricing` entries override built-ins. For DashScope, cached tokens are charged as explicit cache reads when the upstream usage includes `cache_creation_input_tokens`; otherwise `cachedInput` is used as the implicit cache read price. For DeepSeek, `prompt_cache_hit_tokens` map to cached input and `prompt_cache_miss_tokens` map to regular input.\n- **smallModel:** Fallback model used for tool-less warmup messages (e.g., Claude Code probe requests); defaults to gpt-5-mini.\n- **contextManagement:** Controls whether the proxy adds Responses API `context_management` compaction instructions. `messages` applies when Anthropic-style `/v1/messages` requests are translated to Responses API, including `openai-responses` provider message routes, and defaults to `true`. `responses` applies to native `/v1/responses` traffic, including `provider/model` aliases and the built-in `codex` provider, and defaults to `false`. Enable `responses` only after checking that your client supports context management compaction. When enabled, the request includes `context_management` in the body and keeps only the latest compaction carrier on follow-up turns.\n- **modelResponsesApiCompactThresholds:** Per-model Responses API `compact_threshold` overrides used when the proxy adds `context_management`. These values take precedence over the fallback threshold from `resolveResponsesCompactThreshold` (`max_prompt_tokens * ratio`, or the default fallback). Defaults set `gpt-5.4` and `gpt-5.5` to `217600` (`272000 * 0.8`), and `gpt-5.6-sol`, `gpt-5.6-terra`, `gpt-5.6-luna` to `231200` (`272000 * 0.85`). Models not listed continue to use the normal fallback logic.\n- **modelReasoningEfforts:** Per-model reasoning effort applied to `/v1/messages` requests. When routed to the Copilot native Messages API it sets `output_config.effort`; when translated to the Responses API it sets `reasoning.effort`. Allowed values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. If a model isn't listed, `high` is used by default; GPT-5.3+ models fall back to `xhigh` when not explicitly configured.\n- **useMessagesApi:** When `true`, Claude-family models that support Copilot's native `/v1/messages` endpoint will use the Messages API; otherwise they fall back to `/chat/completions`. Set to `false` to disable Messages API routing and always use `/chat/completions`. Defaults to `true`.\n- **useResponsesApiWebSocket:** When `true`, Responses API requests use Copilot's websocket transport for models that advertise `ws:/responses`; models that only advertise `/responses` continue to use HTTP. Set to `false` to disable websocket routing and use HTTP `/responses` whenever the selected model supports it. Defaults to `true`.\n- **useResponsesApiWebSearch:** When `true`, the server keeps Responses API tools with `type: \"web_search\"` and forwards them upstream. Set to `false` to strip those tools from `/responses` payloads. Defaults to `true`.\n- **messageApiWebSearchModel:** Global fallback model used when a top-level Copilot `/v1/messages` request contains only the server-side `web_search` tool. Defaults to `gpt-5-mini`. If the value is a `provider/model` alias, the request is routed into that provider's Messages API path with the provider prefix stripped. For Copilot GPT models, web search runs through `/responses`. Mixed `web_search` plus custom tools are not supported and the server-side `web_search` tool is stripped.\n- **claudeTokenMultiplier:** Multiplier applied to the fallback GPT-tokenizer estimate for Claude `/v1/messages/count_tokens` requests. Defaults to `1.15`. Increase it if your client is still compacting too late. This setting is only used when the proxy is estimating Claude tokens locally; if `anthropicApiKey` is configured and Anthropic token counting succeeds, the exact Anthropic count is returned instead.\n- **anthropicApiKey:** Anthropic API key used to forward Claude `/v1/messages/count_tokens` requests to Anthropic's real token counting endpoint, which returns exact counts instead of GPT tokenizer estimates. Can also be set via the `ANTHROPIC_API_KEY` environment variable. If not set, or if the upstream call fails, token counting falls back to local GPT tokenizer estimation controlled by `claudeTokenMultiplier`.\n\nEdit this file to customize prompts or swap in your own fast model. Restart the server (or rerun the command) after changes so the cached config is refreshed.\n\n## API Authentication\n\n- **Protected non-admin routes:** All routes except `/`, `/usage-viewer`, and `/usage-viewer/` require authentication when `auth.apiKeys` is configured and non-empty.\n- **Admin routes:** All `/admin/*` routes require `auth.adminApiKey`. If it is missing, the server generates one at startup and persists it to `config.json` before serving requests.\n- **Allowed auth headers:**\n  - `x-api-key: <your_key>`\n  - `Authorization: Bearer <your_key>`\n- **CORS preflight:** `OPTIONS` requests are always allowed.\n- **When no regular keys are configured:** Non-admin routes continue to allow requests. This does not apply to `/admin/*`, which only accepts `auth.adminApiKey`.\n\nExample request for a regular protected route:\n\n```sh\ncurl http://localhost:4141/v1/models \\\n  -H \"x-api-key: your_api_key\"\n```\n\nExample request for an admin route:\n\n```sh\ncurl http://localhost:4141/admin/config/model-mappings \\\n  -H \"x-api-key: your_admin_api_key\"\n```\n\n## API Endpoints\n\nThe server exposes several OpenAI- and Anthropic-compatible endpoints. Requests can target GitHub Copilot, the built-in `codex` provider, or configured providers depending on the selected model and `provider/model` alias.\n\n### OpenAI Compatible Endpoints\n\nThese endpoints mimic the OpenAI API structure.\n\n| Endpoint                    | Method | Description                                                      |\n| --------------------------- | ------ | ---------------------------------------------------------------- |\n| `POST /v1/responses`        | `POST` | OpenAI Most advanced interface for generating model responses. Supports `provider/model` aliases for `openai-responses` providers. |\n| `POST /v1/chat/completions` | `POST` | Creates a model response for the given chat conversation. Supports `provider/model` aliases for `openai-compatible` providers and can be used without Copilot when the target provider is configured. |\n| `GET /v1/models`            | `GET`  | Lists Copilot models plus enabled provider models using `provider/model-id` IDs. Requests from Codex clients (`User-Agent` beginning with `codex`) are forwarded to the Codex Models upstream. |\n| `POST /v1/embeddings`       | `POST` | Creates an embedding vector representing the input text.         |\n\n### Codex Backend Proxy Endpoints\n\n| Endpoint             | Method | Description |\n| -------------------- | ------ | ----------- |\n| `POST /alpha/search` | `POST` | Transparently forwards the JSON body and query parameters to the Codex Alpha Search upstream. The gateway replaces client authorization and account headers with the active Codex login, forwards compatible headers such as `accept`, `content-type`, `originator`, `user-agent`, and `cookie`, and returns the upstream status, headers, and body unchanged. |\n\n### Anthropic Compatible Endpoints\n\nThese endpoints are designed to be compatible with the Anthropic Messages API.\n\n| Endpoint                         | Method | Description                                                  |\n| -------------------------------- | ------ | ------------------------------------------------------------ |\n| `POST /v1/messages`              | `POST` | Creates a model response for a given conversation. Supports `provider/model` aliases for configured providers, including translation through `openai-compatible` providers. |\n| `POST /v1/messages/count_tokens` | `POST` | Calculates the number of tokens for a given set of messages. Supports `provider/model` aliases for configured providers. |\n| `POST /:provider/v1/messages`       | `POST` | Proxies Anthropic Messages requests to the configured Anthropic provider, translates them through an OpenAI-compatible provider, or translates them through an OpenAI Responses provider. |\n| `GET /:provider/v1/models`          | `GET`  | Proxies model listing requests to the configured provider.   |\n| `POST /:provider/v1/messages/count_tokens` | `POST` | Calculates tokens locally for provider route requests. |\n\n### Usage Monitoring Endpoints\n\nNew endpoints for monitoring your Copilot usage and quotas.\n\n| Endpoint     | Method | Description                                                  |\n| ------------ | ------ | ------------------------------------------------------------ |\n| `GET /usage` | `GET`  | Get detailed Copilot usage statistics and quota information. |\n| `GET /token` | `GET`  | Get the current Copilot token being used by the API.         |\n\n### Admin / Configuration Endpoints\n\nThese endpoints are reserved for local administrative actions and only accept `auth.adminApiKey`.\n\n| Endpoint                              | Method | Description                                                                 |\n| ------------------------------------- | ------ | --------------------------------------------------------------------------- |\n| `GET /admin/config/model-mappings`    | `GET`  | Returns the current `config.json` path and the active `modelMappings` map.  |\n| `POST /admin/config/model-mappings`   | `POST` | Updates only the `modelMappings` field in `config.json` and returns it back. |\n\n## Example Usage\n\nCommon `npx` commands:\n\n```sh\n# Start the gateway\nnpx @jeffreycao/copilot-api@latest start\n\n# Start on a custom port with verbose logging\nnpx @jeffreycao/copilot-api@latest start --port 8080 --verbose\n\n# Run the auth flow\nnpx @jeffreycao/copilot-api@latest auth login\n\n# Configure a third-party provider, then run without GitHub Copilot\nnpx @jeffreycao/copilot-api@latest auth login --provider dashscope\nnpx @jeffreycao/copilot-api@latest start\n\n# Print debug information as JSON\nnpx @jeffreycao/copilot-api@latest debug --json\n\n# Run the published CLI with Bun instead of Node.js\nbunx --bun @jeffreycao/copilot-api@latest start\n```\n\nOpenAI-compatible provider examples after configuring `dashscope`:\n\n```sh\ncurl http://localhost:4141/v1/chat/completions \\\n  -H \"content-type: application/json\" \\\n  -d '{\"model\":\"dashscope/qwen3.6-plus\",\"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]}'\n\ncurl http://localhost:4141/dashscope/v1/messages \\\n  -H \"content-type: application/json\" \\\n  -d '{\"model\":\"qwen3.6-plus\",\"max_tokens\":1024,\"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]}'\n```\n\n## Usage Tips\n\n### CLAUDE.md or AGENTS.md Recommended Content\n\nTo add these reminders manually, include the following in `CLAUDE.md` for Claude Code, or `AGENTS.md` for opencode/codex:\n\n```\n- Prohibited from directly asking questions to users, MUST use question tool.\n- Once you can confirm that the task is complete, MUST use question tool to make user confirm. The user may respond with feedback if they are not satisfied with the result, which you can use to make improvements and try again, after try again, MUST use question tool to make user confirm again.\n```\n"}, "deb4347ee3433be63f66ce234d6d920de1a56c6f": {"t": 1785765562.9840446, "n": 46964, "h": "a5a49e8e454c165a", "c": "# Copilot API Proxy\n\nEnglish | [简体中文](./README.zh-CN.md)\n\n## Important Notes\n\n> [!IMPORTANT]\n> **Before using, please be aware of the following:**\n>\n> 1. **Claude Code configuration:** When using with Claude Code, please configure the model ID as `claude-opus-4-8`. Example claude `settings.json` see [Manual Configuration with `settings.json`](#manual-configuration-with-settingsjson). \n>\n> 2. **Built-in `copilot`, `codex` and third-party providers:** Run `npx @jeffreycao/copilot-api@latest auth` and choose `copilot`, `codex`, `deepseek`, `custom`, or other providers.\n>\n> 3. **Note:** See [GitHub Copilot Security Notice](./NOTICE.md#github-copilot-security-notice) for the warning removed from the README header.\n\n---\n\n## Project Overview\n\nA small AI gateway that can use GitHub Copilot, the built-in `codex` provider, or configured third-party providers such as DashScope. GitHub Copilot is optional: if no GitHub token is available, the server can still start in provider-only mode as long as at least one enabled provider is configured.\n\nThe gateway exposes OpenAI- and Anthropic-compatible APIs from one local endpoint, so tools like [Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview), OpenCode, Codex, and OpenAI-compatible clients can share the same local server.\n\nOn the GitHub Copilot path, the gateway prefers Copilot's native Anthropic-style Messages API when available, preserving more Claude-native behavior for tool-heavy workflows.\n\n## Features\n\n- **OpenAI and Anthropic compatibility**: Serve `/v1/responses`, `/v1/chat/completions`, `/v1/models`, `/v1/embeddings`, and `/v1/messages` from one local gateway.\n- **Copilot is optional**: Use GitHub Copilot when credentials are present, or run the server with only configured providers.\n- **One gateway for Copilot, `codex`, and external providers**: Route GitHub Copilot, the built-in `codex` provider, and configured third-party providers behind the same endpoint.\n- **Standalone third-party providers**: Configure providers such as DashScope, DeepSeek, OpenRouter, or a custom provider and start the gateway without a GitHub Copilot login.\n- **OpenAI-compatible providers on chat and Messages APIs**: `openai-compatible` providers can serve top-level `/v1/chat/completions` through `model: \"provider/model\"` and Anthropic-style `/v1/messages` through request/response translation.\n- **Agent-friendly Claude handling on Copilot**: Prefer native `/v1/messages` when available, preserve Claude-style tool flows, support Anthropic beta features, Claude WebSearch through Responses-capable models, and keep subagent/session markers intact.\n- **Claude Code and OpenCode integration**: Works with Claude Code and OpenCode, including direct Anthropic-compatible usage through `@ai-sdk/anthropic`.\n- **Flexible auth and deployment options**: Supports interactive login or direct tokens, individual/business/enterprise plans, GitHub Enterprise, opencode OAuth, and custom data directories.\n- **Multi-provider routing**: Expose provider-specific `/:provider/...` routes or use `model: \"provider/model\"` on the top-level API.\n\n## Prerequisites\n\n- Bun (>= 1.2.x)\n- Node.js if you plan to run the published CLI with `npx`\n- GitHub account with Copilot subscription only if you want to use the GitHub Copilot provider\n- An API key or OAuth login for at least one configured provider if you want to run without GitHub Copilot\n\n## Installation\n\nTo install dependencies, run:\n\n```sh\nbun install\n```\n\nTo start the server directly from source:\n\n```sh\nbun run start start\n```\n\n## Running from Source\n\nThe project can be run from source in several ways:\n\n### Development Mode\n\n```sh\nbun run dev start\n```\n\n### Production Mode\n\n```sh\nbun run start start\n```\n\n## Using with npx\n\nYou can run the project directly using npx:\n\n> [!IMPORTANT]\n> Token usage storage uses Node's built-in `node:sqlite` module when running with `npx`. It is enabled on Node.js >= 22.13.0. On Node.js < 22.13.0, the CLI still starts, but token usage storage is disabled.\n>\n> If you want token usage storage without upgrading Node.js, run the published CLI with Bun instead: `bunx --bun @jeffreycao/copilot-api@latest start`.\n\n```sh\nnpx @jeffreycao/copilot-api@latest start\n```\n\nWith options:\n\n```sh\nnpx @jeffreycao/copilot-api@latest start --port 8080\n```\n\nFor authentication or provider configuration only:\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth\n```\n\nTo run without GitHub Copilot, configure at least one provider first, then start the server normally:\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth login --provider dashscope\nnpx @jeffreycao/copilot-api@latest start\n```\n\n## Using with Docker\n\nBuild the image:\n\n```sh\ndocker build -t copilot-api .\n```\n\nRun the container with a bind mount so auth data survives restarts:\n\n```sh\nmkdir -p ./copilot-data\ndocker run -p 4141:4141 -v $(pwd)/copilot-data:/root/.local/share/copilot-api copilot-api\n```\n\nThis stores GitHub auth data, provider config, and other gateway state in `./copilot-data` on the host, mapped to `/root/.local/share/copilot-api` in the container.\n\nOr pass a GitHub token directly:\n\n```sh\ndocker run -p 4141:4141 -e GH_TOKEN=your_github_token_here copilot-api\n```\n\n## Electron Desktop App\n\nIf you prefer a GUI, this repository also includes an Electron desktop app in `desktop/`. It supports GitHub Copilot sign-in, OpenAI Codex OAuth, and API-key configuration for DeepSeek, DashScope, OpenRouter, or a custom provider. After authorization or provider configuration, it can start and stop the local proxy with one click and shows the local endpoint, auth header, available models, usage, and logs in the app.\n\nThe settings screen also exposes `OAuth App`, `API Home`, `Enterprise URL`, verbose logging, and minimize-to-tray. Desktop packages are published in GitHub Releases:\n\nhttps://github.com/caozhiyuan/copilot-api/releases\n\nDownload the installer for your platform, authorize or configure a provider inside the app, choose a port, start the server, then point your client at the local endpoint shown in the app. Packaged desktop builds use the bundled Electron runtime, so normal desktop usage does not require installing Node.js separately. Token usage history is enabled when that bundled runtime supports SQLite.\n\nThe desktop app's Advanced Config page reads and writes the shared model mappings through `GET/POST /admin/config/model-mappings`. The same mappings apply across `POST /v1/messages`, `POST /v1/messages/count_tokens`, `POST /v1/responses`, and `POST /v1/chat/completions` instead of being split per interface. It uses `auth.adminApiKey` instead of the regular `auth.apiKeys`, and the app reads that key directly from `config.json` after the server has generated it on startup.\n\n### Desktop App Screenshots\n\nMain dashboard, token usage breakdown in the bundled Electron app:\n\n<p align=\"center\">\n  <img src=\"./docs/screenshots/desktop-dashboard.png\" alt=\"Copilot API desktop app dashboard\" width=\"49%\" />\n  <img src=\"./docs/screenshots/desktop-token-usage.png\" alt=\"Copilot API desktop app token usage view\" width=\"49%\" />\n</p>\n\n## Using with Claude Code\n\nThis AI gateway can be used to power [Claude Code](https://docs.anthropic.com/en/claude-code), an experimental conversational AI assistant for developers from Anthropic.\n\nThere are two ways to configure Claude Code to use this AI gateway:\n\n### Interactive Setup with `--claude-code` flag\n\nTo get started, run the `start` command with the `--claude-code` flag:\n\n```sh\nnpx @jeffreycao/copilot-api@latest start --claude-code\n```\n\nYou will be prompted to select a primary model and a \"small, fast\" model for background tasks. After selecting the models, a command will be copied to your clipboard. This command sets the necessary environment variables for Claude Code to use the gateway.\n\nPaste and run this command in a new terminal to launch Claude Code.\n\n### Manual Configuration with `settings.json`\n\nAlternatively, you can configure Claude Code by creating a `.claude/settings.json` file in your project's root directory. This file should contain the environment variables needed by Claude Code. This way you don't need to run the interactive setup every time.\n\nHere is an example `.claude/settings.json` file:\n\n```json\n{\n  \"env\": {\n    \"ANTHROPIC_BASE_URL\": \"http://localhost:4141\",\n    \"ANTHROPIC_AUTH_TOKEN\": \"dummy\",\n    \"ANTHROPIC_MODEL\": \"deepseek/deepseek-v4-pro\",\n    \"ANTHROPIC_DEFAULT_SONNET_MODEL\": \"deepseek/deepseek-v4-pro\",\n    \"ANTHROPIC_DEFAULT_HAIKU_MODEL\": \"deepseek/deepseek-v4-flash\",\n    \"DISABLE_NON_ESSENTIAL_MODEL_CALLS\": \"1\",\n    \"CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC\": \"1\",\n    \"CLAUDE_CODE_ATTRIBUTION_HEADER\": \"0\",\n    \"CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION\": \"false\",\n    \"CLAUDE_CODE_DISABLE_TERMINAL_TITLE\": \"true\",\n    \"CLAUDE_CODE_ENABLE_AWAY_SUMMARY\": \"0\"\n  },\n  \"permissions\": {\n    \"deny\": [\n      \"mcp__ide__executeCode\"\n    ]\n  }\n}\n```\n\n- Replace `ANTHROPIC_MODEL`, `ANTHROPIC_DEFAULT_OPUS_MODEL`, `ANTHROPIC_DEFAULT_SONNET_MODEL`, and `ANTHROPIC_DEFAULT_HAIKU_MODEL` according to your needs. After configuration, please install the claude code plugin [Plugin Integrations](#plugin-integrations).  \n- Setting CLAUDE_CODE_ATTRIBUTION_HEADER to 0 can prevent Claude code from adding billing and version information in system prompts, thereby avoiding prompt cache invalidation.\n- Turning off CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION and CLAUDE_CODE_ENABLE_AWAY_SUMMARY can prevent quota from being consumed unnecessarily.\n- Claude Code WebSearch is supported for pure search requests. For Copilot, keep the global `messageApiWebSearchModel` set to a Responses-capable GPT model or a `provider/model` alias. For provider routes, use a native Anthropic provider or an `openai-responses` provider. Add `WebSearch` to `permissions.deny` only if you want to forbid this traffic.\n- If using a non-Claude model, do not enable ENABLE_TOOL_SEARCH. If using the Claude model, can enable ENABLE_TOOL_SEARCH. The current Claude Code uses the client tool search mode. In this mode, loading defer tools requires an additional request each time.\n- `CLAUDE_CODE_AUTO_COMPACT_WINDOW`: Set the context capacity in tokens used for auto-compaction calculations. Defaults to the model's context window: 200K for standard models or 1M for extended context models. Use a lower value like `500000` on a 1M model (e.g., `claude-opus-4-6[1m]`) to treat the window as 500K for compaction purposes. The value is capped at the model's actual context window. `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` is applied as a percentage of this value. Setting this variable decouples the compaction threshold from the status line's `used_percentage`, which always uses the model's full context window.\n\nYou can find more options here: [Claude Code settings](https://docs.anthropic.com/en/docs/claude-code/settings#environment-variables)\n\nYou can also read more about IDE integration here: [Add Claude Code to your IDE](https://docs.anthropic.com/en/docs/claude-code/ide-integrations)\n\n## Using with OpenCode\n\nOpenCode already has a direct GitHub Copilot provider. Use this section when you want OpenCode to point at this AI gateway through `@ai-sdk/anthropic` and reuse the agent behaviors described earlier in this README.\n\n### Minimal setup\n\nStart the AI gateway with the OpenCode OAuth app:\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth --oauth-app=opencode\nnpx @jeffreycao/copilot-api@latest start\n```\n\nThen point OpenCode at the gateway with `@ai-sdk/anthropic`.\n\nExample `~/.config/opencode/opencode.json`:\n\n```json\n{\n  \"$schema\": \"https://opencode.ai/config.json\",\n  \"provider\": {\n    \"local\": {\n      \"npm\": \"@ai-sdk/anthropic\",\n      \"name\": \"My Local\",\n      \"options\": {\n        \"baseURL\": \"http://localhost:4141/v1\",\n        \"apiKey\": \"dummy\"\n      },\n      \"models\": {\n        \"gpt-5.4\": {\n          \"name\": \"gpt-5.4\",\n          \"modalities\": {\n            \"input\": [\"text\", \"image\"],\n            \"output\": [\"text\"]\n          },\n          \"limit\": {\n            \"context\": 400000,\n            \"input\": 272000,\n            \"output\": 128000\n          }\n        },\n        \"claude-sonnet-4.6\": {\n          \"id\": \"claude-sonnet-4.6\",\n          \"name\": \"claude-sonnet-4.6\",\n          \"modalities\": {\n            \"input\": [\"text\", \"image\"],\n            \"output\": [\"text\"]\n          },          \n          \"limit\": {\n            \"context\": 200000,\n            \"output\": 32000\n          },\n          \"options\": {\n            \"thinking\": {\n              \"type\": \"adaptive\"\n            },\n            \"effort\": \"max\"\n          }\n        }\n      }\n    }\n  }\n}\n```\n\nWhy these fields matter:\n\n- `npm: \"@ai-sdk/anthropic\"` is the important part. OpenCode will speak Anthropic Messages semantics to this AI gateway instead of flattening everything into OpenAI Chat Completions.\n- `options.baseURL` should be `http://localhost:4141/v1`; the Anthropic SDK will append `/messages`, `/models`, and `/messages/count_tokens` automatically.\n- If you enable `auth.apiKeys` in this AI gateway, replace `dummy` with a real key. Otherwise any placeholder value is fine.\n\n## Using with Codex\n\nThis AI gateway can also power Codex.\n\n### Codex `config.toml` Reference\n\nAdd the following `[model_providers.copilot_api]` section to your Codex `~/.codex/config.toml`:\n\n```toml\nmodel_provider = \"copilot_api\"\nmodel_reasoning_summary = \"auto\"\nmodel_verbosity = \"medium\"\nmodel_context_window = 272000\nmodel_auto_compact_token_limit = 244800\n\n[model_providers.copilot_api]\nname = \"OpenAI\"\nbase_url = \"http://localhost:4141\"\nenv_key = \"GITHUB_COPILOT_API_KEY\"\nrequires_openai_auth = true\nsupports_websockets = false\nwire_api = \"responses\"\nrequest_max_retries = 3\nstream_max_retries = 1\nstream_idle_timeout_ms = 300000\n\n[features]\nremote_compaction_v2 = true\n\n[analytics]\nenabled = false\n```\n\n> [!NOTE]\n> This configuration is specific to Codex and the GitHub Copilot provider. `name` must be set to `\"OpenAI\"`. It can help mitigate Codex local compact cache miss issues. If you enable `contextManagement.responses` (Responses API context management compaction), `remote_compaction_v2` or local compact is generally not triggered, but it may still occur when tool results return a large number of tokens. Before enabling it for native Responses API traffic, check that your client supports context management compaction.\n\n## GPT Tool Search\n\nFor GPT Responses models such as `gpt-5.4+`, this AI gateway can expose Responses `tool_search` through a small MCP bridge. The same bridge can be used by Claude Code and opencode, as long as the client loads MCP servers and sends Anthropic Messages traffic through this gateway.\n\nDo not set Claude Code's native `ENABLE_TOOL_SEARCH` for GPT models. That flag enables Claude Code's own client-side tool search mode, and it may stop forwarding deferred tool definitions. This gateway needs the full tool definitions so it can keep the small always-loaded tool set eager and translate every other tool into Responses deferred namespaces.\n\nIf you install `tool-search@copilot-api-marketplace`, Claude Code receives this MCP bridge automatically and you can skip the manual Claude Code MCP setup below.\n\nAdd the tool search bridge to the MCP config used by Claude Code:\n\n```json\n{\n  \"mcpServers\": {\n    \"tool_search\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@jeffreycao/copilot-api@latest\", \"mcp\"]\n    }\n  }\n}\n```\n\nAdd the tool search bridge to the MCP config used by opencode:\n\n```json\n{\n  \"mcp\": {\n    \"tool_search\": {\n      \"type\": \"local\",\n      \"command\": [\"npx\", \"-y\", \"@jeffreycao/copilot-api@latest\", \"mcp\"]\n    }\n  }\n}\n```\n\nFor local development, use `bun` as the command and `[\"run\", \"./src/main.ts\", \"mcp\"]` as the args.\n\nInternally, the gateway now configures OpenAI Responses `tool_search` in client-executed mode. Deferred tools are still exposed as searchable namespaces, but the model is explicitly asked to return the exact deferred tool names it wants to load next.\n\nThe bridge uses direct tool selection, not query search. Its tool input is `names`, a comma-separated list of exact deferred tool names, for example `TaskList,TaskGet,mcp__fetch__fetch`.\n\n## Plugin Integrations\n\nPlugin integrations are available for Claude Code and opencode.\n\n#### Claude Code plugin integration (marketplace-based)\n\nThe Claude Code integration is packaged as two plugins:\n\n- `agent-inject` injects `__SUBAGENT_MARKER__...` on `SubagentStart`, so the gateway can infer `x-initiator: agent`.\n- `tool-search` registers the `tool_search` MCP bridge used for GPT Responses deferred tool loading.\n\n- Marketplace catalog in this repository: `.claude-plugin/marketplace.json`\n- Plugin sources in this repository: `plugin/claude/agent-inject`, `plugin/claude/tool-search`\n\nAdd the marketplace remotely:\n\n```sh\n/plugin marketplace add https://github.com/caozhiyuan/copilot-api.git\n```\n\nInstall the plugins from the marketplace:\n\n```sh\n/plugin install agent-inject@copilot-api-marketplace\n/plugin install tool-search@copilot-api-marketplace\n```\n\nAfter installation, `agent-inject` injects `__SUBAGENT_MARKER__...` on `SubagentStart`, and the gateway uses it to infer `x-initiator: agent`.\n\nThe `agent-inject` plugin also registers a `UserPromptSubmit` hook that returns `{\"continue\": true}`, and it can inject `SessionStart` reminder rules through environment variables:\n\n- `CLAUDE_PLUGIN_ENABLE_QUESTION_RULES=1` enables the two reminders about using the `question` tool automatically for Claude Code. Alternatively, you can add the same reminders manually in `CLAUDE.md`; see [CLAUDE.md or AGENTS.md Recommended Content](#claudemd-or-agentsmd-recommended-content).\n- `CLAUDE_PLUGIN_ENABLE_NO_BACKGROUND_AGENTS_RULE=1` enables the `run_in_background: true` avoidance reminder for agent hooks.\n\nThe `tool-search` plugin bundles the same MCP bridge described in [GPT Tool Search](#gpt-tool-search), so Claude Code users do not need to add the `tool_search` server manually when they install that plugin.\n\n#### Opencode plugin\n\nThe subagent marker producer is packaged as an opencode plugin located at `plugin/opencode/subagent-marker.js`.\n\n**Installation:**\n\nCopy the plugin file to your opencode plugins directory:\n\n```sh\n# Clone or download this repository, then copy the plugin\ncp plugin/opencode/subagent-marker.js ~/.config/opencode/plugins/\n```\n\nOr manually create the file at `~/.config/opencode/plugins/subagent-marker.js` with the plugin content.\n\n**Features:**\n\n- Tracks sub-sessions created by subagents\n- Automatically prepends a marker system reminder (`__SUBAGENT_MARKER__...`) to subagent chat messages\n- Sets `x-session-id` header for session tracking\n- Enables the gateway to infer `x-initiator: agent` for subagent-originated requests\n\nThe plugin hooks into `session.created`, `session.deleted`, `chat.message`, and `chat.headers` events to provide seamless subagent marker functionality.\n\n## Using the Usage Viewer\n\nAfter starting the server, a URL to the Copilot Usage Dashboard will be displayed in your console. This dashboard is a web interface for monitoring your API usage.\n\n1.  Start the server. For example, using npx:\n    ```sh\n    npx @jeffreycao/copilot-api@latest start\n    ```\n2.  The server will output a URL to the usage viewer. Copy and paste this URL into your browser. It will look something like this:\n    `http://localhost:4141/usage-viewer?endpoint=http://localhost:4141/usage`\n    - If you use the `start.bat` script on Windows, this page will open automatically.\n\nThe dashboard provides a user-friendly interface to view your Copilot usage data:\n\n> Token usage history requires Bun or Node.js >= 22.13.0. On Node.js < 22.13.0, the server runs normally but token usage storage is disabled.\n\n- **API Endpoint URL**: The dashboard is pre-configured to fetch data from your local server endpoint via a URL query parameter. You can manually switch this to any other compatible API endpoint.\n- **x-api-key Authentication**: If API Key authentication is enabled, you can provide the `x-api-key` request header. The key is persisted in the browser's local storage.\n- **Period Selector**: Choose from Day, Week, or Month time ranges. The URL query parameter updates automatically when you switch, making it easy to bookmark and share.\n- **Fetch Data**: Click the \"Refresh\" button to load or refresh the usage data. The dashboard also fetches data automatically on page load.\n- **Copilot Quotas**: View quota usage for services such as Chat and Completions via progress bars. Hover over a card to see used/remaining details.\n- **Token Usage Metric Cards**: See a summary of Total, Input, Output, Cache Read, Cache Write, Requests, and estimated cost for the current period.\n- **Trend Chart (Week / Month)**: An interactive line chart with model and metric filters. Click a data point to inspect the usage breakdown for a specific day.\n- **Model Breakdown Table**: A per-model summary of requests, input/output/cache tokens, and estimated cost for the selected period.\n- **Request Events (Paginated)**: A time-sorted list of request event records with pagination support, showing timestamps, models, request IDs, and token counts.\n- **Detailed Information**: See the full JSON response from the API for a detailed breakdown of all available usage statistics.\n- **URL-based Configuration**: You can also specify the API endpoint and period directly via `endpoint` and `period` query parameters. For example:\n  `http://localhost:4141/usage-viewer?endpoint=http://your-api-server/usage&period=week`\n\n### Usage Viewer Screenshot\n\n<p align=\"center\">\n  <img src=\"./docs/screenshots/usage-viewer.png\" alt=\"Copilot API usage viewer\" width=\"900\" />\n</p>\n\n## Command Structure\n\nCopilot API now uses a subcommand structure with these main commands:\n\n- `start`: Start the gateway server. If a GitHub token is available, the server starts with Copilot enabled. If no GitHub token is available, it starts in provider-only mode when at least one enabled provider exists; otherwise it guides you through provider setup.\n- `auth`: Run provider login or configuration without starting the server. Use it for GitHub Copilot login, Codex OAuth, or third-party provider API key setup.\n- `debug`: Display diagnostic information including version, runtime details, file paths, and authentication status. Useful for troubleshooting and support.\n\n## Command Line Options\n\n### Global Options\n\nThe following options can be used with any subcommand. When passing them before the subcommand, use the `--key=value` form:\n\n| Option            | Description                                            | Default | Alias |\n| ----------------- | ------------------------------------------------------ | ------- | ----- |\n| --api-home        | Path to the API home directory (sets COPILOT_API_HOME) | none    | none  |\n| --oauth-app       | OAuth app identifier (sets COPILOT_API_OAUTH_APP)      | none    | none  |\n| --enterprise-url  | Enterprise URL for GitHub (sets COPILOT_API_ENTERPRISE_URL) | none | none |\n\n### Start Command Options\n\nThe following command line options are available for the `start` command:\n\n| Option         | Description                                                                   | Default    | Alias |\n| -------------- | ----------------------------------------------------------------------------- | ---------- | ----- |\n| --port         | Port to listen on                                                             | 4141       | -p    |\n| --verbose      | Enable verbose logging                                                        | false      | -v    |\n| --github-token | Provide GitHub token directly (must be generated using the `auth` subcommand) | none       | -g    |\n| --claude-code  | Generate a command to launch Claude Code with Copilot API config              | false      | -c    |\n| --show-token   | Show GitHub and Copilot tokens on fetch and refresh                           | false      | none  |\n| --proxy-env    | Initialize proxy from environment variables                                   | false      | none  |\n\n### Auth Command Options\n\n| Option       | Description               | Default | Alias |\n| ------------ | ------------------------- | ------- | ----- |\n| --provider   | Provider to log in with or configure (`copilot`, `codex`, `opencode-go`, `deepseek`, `dashscope`, `openrouter`, or `custom`) | prompt | none |\n| --verbose    | Enable verbose logging    | false   | -v    |\n| --show-token | Show GitHub token on auth | false   | none  |\n\nUse `copilot-api auth login --provider copilot` only when you want to enable the GitHub Copilot provider. Copilot is not required for `codex` or third-party provider-only usage.\n\nUse `copilot-api auth login --provider deepseek`, `--provider dashscope`, `--provider openrouter`, or `--provider opencode-go` to add or update those common third-party providers from the CLI. DeepSeek prompts for masked `apiKey`, provider `type` (default `anthropic`), and `baseUrl` defaulting to `https://api.deepseek.com/anthropic`. DashScope prompts for masked `apiKey`, provider `type` (default `openai-compatible`), and prefilled `baseUrl`. OpenRouter prompts for masked `apiKey` and prefilled `baseUrl` only, and writes `type: \"anthropic\"`. OpenCode Go prompts for masked `apiKey` and prefilled `baseUrl` only, and writes `type: \"openai-compatible\"` (baseUrl `https://opencode.ai/zen/go`). After a provider is configured and enabled, `copilot-api start` can run without any GitHub token.\n\nUse `copilot-api auth login --provider custom` to add or update another third-party provider from the CLI. The command prompts for the provider name, supported type (`anthropic`, `openai-compatible`, or `openai-responses`), `baseUrl`, masked `apiKey`, and `authType`; `authType` may be left as the type default or set to `x-api-key` / `authorization`.\n\n### Debug Command Options\n\n| Option | Description               | Default | Alias |\n| ------ | ------------------------- | ------- | ----- |\n| --json | Output debug info as JSON | false   | none  |\n\n## Configuration (config.json)\n\n- **Location:** `~/.local/share/copilot-api/config.json` (Linux/macOS) or `%USERPROFILE%\\.local\\share\\copilot-api\\config.json` (Windows).\n- **Default shape:**\n  ```json\n  {\n    \"auth\": {\n      \"apiKeys\": [],\n      \"adminApiKey\": \"<auto-generated-on-startup>\"\n    },\n    \"providers\": {},\n    \"modelMappings\": {},\n    \"extraPrompts\": {\n      \"gpt-5-mini\": \"<built-in exploration prompt>\"\n    },\n    \"smallModel\": \"gpt-5-mini\",\n    \"contextManagement\": {\n      \"messages\": true,\n      \"responses\": false\n    },\n    \"modelResponsesApiCompactThresholds\": {\n      \"gpt-5.4\": 217600,\n      \"gpt-5.5\": 217600,\n      \"gpt-5.6-sol\": 231200,\n      \"gpt-5.6-terra\": 231200,\n      \"gpt-5.6-luna\": 231200\n    },\n    \"modelReasoningEfforts\": {\n      \"gpt-5-mini\": \"low\"\n    },\n    \"useMessagesApi\": true,\n    \"useResponsesApiWebSocket\": true,\n    \"useResponsesApiWebSearch\": true,\n    \"messageApiWebSearchModel\": \"gpt-5-mini\"\n  }\n  ```\n- **auth.apiKeys:** API keys used for request authentication on non-admin routes. Supports multiple keys for rotation. Requests can authenticate with either `x-api-key: <key>` or `Authorization: Bearer <key>`. If empty or omitted, authentication for non-admin routes is disabled.\n- **auth.adminApiKey:** Single admin key used only for `/admin/*` routes. If missing, the server generates a random key at startup and writes it back to `config.json`. Requests use the same `x-api-key` or `Authorization: Bearer` headers, but regular `auth.apiKeys` never grant access to `/admin/*`.\n- **modelMappings:** Exact `sourceModel -> targetModel` rewrites shared by top-level `POST /v1/messages`, `POST /v1/messages/count_tokens`, `POST /v1/responses`, and `POST /v1/chat/completions` requests. Omit it or leave it as `{}` to disable rewrites. Both the source and target must be non-empty strings. Targets can be regular model IDs or `provider/model` aliases such as `dashscope/qwen3.6-plus`, and the rewrite happens before provider alias parsing. These mappings are not split per interface. The admin endpoints `GET/POST /admin/config/model-mappings` read and update only this field.\n- **extraPrompts:** Map of `model -> prompt` appended to the first system prompt when translating Anthropic-style requests to Responses API. Use this to inject guardrails or guidance per model. Missing default entries are auto-added without overwriting your custom prompts. For GPT-5.3+ models (e.g. `gpt-5.3-codex`, `gpt-5.4`, `gpt-5.5`), a built-in commentary prompt is used as fallback when not explicitly configured. The built-in prompts enable phase-aware commentary, which lets the model emit a short user-facing progress update before tools or deeper reasoning.\n- **providers:** Global upstream provider map. Each provider key (for example `dashscope`) becomes a route prefix (`/dashscope/v1/messages`). Supports `type: \"anthropic\"`, `type: \"openai-compatible\"`, and `type: \"openai-responses\"`. Top-level clients can also use `model: \"dashscope/model-id\"` with `/v1/messages`, `/v1/messages/count_tokens`, `/v1/responses`, and `/v1/chat/completions`; the gateway strips the `dashscope/` prefix before forwarding upstream. `openai-compatible` providers support both chat and Messages flows: `/v1/chat/completions` is proxied to upstream `/v1/chat/completions`, while `/v1/messages` and `/:provider/v1/messages` are translated to upstream chat completions and translated back to Anthropic Messages responses. `GET /v1/models` aggregates enabled provider models with `provider/model-id` IDs; use `GET /dashscope/v1/models` for a single provider's raw model list.\n  - `enabled` defaults to `true` if omitted.\n  - `baseUrl` should be provider API base URL without the final endpoint. For Anthropic providers, omit `/v1/messages`; for OpenAI-compatible providers, omit `/v1/chat/completions`; for OpenAI Responses providers, omit `/v1/responses`.\n  - `apiKey` is used as the upstream credential value and is required for regular providers.\n  - `authType` (optional): Controls how `apiKey` is sent upstream. Supports `x-api-key` and `authorization` for regular providers. Anthropic providers default to `x-api-key`; OpenAI-compatible and OpenAI Responses providers default to `authorization`. When set to `authorization`, the proxy sends `Authorization: Bearer <apiKey>`. `oauth2` is reserved for the built-in `codex` provider and is written automatically by `auth login --provider codex`.\n  - `pricingCurrency` (optional): Provider-level currency used for token cost calculation, for example `USD` or `CNY`. Quick providers default to `CNY` for DashScope and DeepSeek, and `USD` for Codex/OpenRouter. Costs are grouped by currency and are not exchange-rate converted.\n  - `models` (optional): Per-model configuration map. Each key is a model ID (matching the model name in requests), and the value is:\n    - `temperature` (optional): Default temperature value used when the request does not specify one.\n    - `topP` (optional): Default top_p value used when the request does not specify one.\n    - `topK` (optional): Default top_k value used when the request does not specify one.\n    - `extraBody` (optional): Dynamic fields merged into the upstream request body for that model. Request body fields with the same name take precedence. OpenAI-compatible providers can use this for fields such as `enable_thinking`, `preserve_thinking`, `reasoning_effort`. `thinking_budget` is a special OpenAI-compatible provider override: when configured in `extraBody`, it is forced after Anthropic `thinking.budget_tokens` translation and overrides the request-derived budget. For providers whose name is `dashscope` or whose `baseUrl` contains `aliyuncs.com`, the request-derived `thinking_budget` (from Anthropic `thinking.budget_tokens`) is forwarded upstream; for other OpenAI-compatible providers the request-derived `thinking_budget` is stripped, while an `extraBody` `thinking_budget` is still honored. For DashScope providers, `preserve_thinking` defaults to `true` when not explicitly set in `extraBody` or the request body.\n    - `pricing` (optional): Per-model token prices, in the provider `pricingCurrency`, per 1M tokens. Supported fields are `input`, `output`, `cachedInput` (implicit cache read), `explicitCachedInput` (explicit cache read), and `cacheCreationInput`. Use `tiers` with `maxInputTokens` for input-size tiered pricing.\n    - `contextCache` (optional): Defaults to `true` for providers whose name is `dashscope` or whose `baseUrl` contains `aliyuncs.com`; defaults to `false` for other OpenAI-compatible providers. This enables Alibaba Cloud Model Studio/DashScope explicit context cache by injecting `cache_control: { \"type\": \"ephemeral\" }` on up to 4 content blocks using the Context Cache format. The cache breakpoint strategy matches opencode's main provider flow: the first 2 system messages plus the last 2 non-system messages. Marked string content is converted to text content part arrays for `system` / `user` / `assistant` / `tool` messages; existing array content is marked on the last part. Set this to `false` when the model already supports implicit caching, or when the upstream does not accept this explicit-cache extension field. Set this to `true` for non-DashScope providers that support the same explicit-cache extension. Applied on both `/v1/messages` and `/v1/chat/completions` routes.\n    - `supportPdf` (optional): Controls whether the model supports PDF/document content. Defaults to `false`; unsupported PDFs are converted to a text notice. Set it to `true` to send PDF/document blocks as OpenAI Chat Completions file parts.\n    - `toolContentSupportType` (optional): Tool result content capabilities for that model, as an array of `array`, `image`, and `pdf`. Provider routes default to string-only tool content when omitted. If `supportPdf` is `true` but this list does not include `pdf`, file parts in tool results are moved to user role messages. This provider default does not change the Copilot main flow, which continues to support array + image and not PDF.\n    - `type` (optional): Per-model override of the provider protocol type. Supports `anthropic`, `openai-compatible`, and `openai-responses`. When set, the provider's `/v1/messages` route uses this model's type instead of the provider-level type for request routing, auth header resolution, and upstream endpoint selection. This is useful for providers like OpenCode Go whose upstream supports both OpenAI-compatible and Anthropic Messages APIs for different models. When the type is overridden, the auth header is resolved from the overridden type's default (Anthropic defaults to `x-api-key`; OpenAI-compatible/Responses default to `authorization`).\n\n  Example DashScope model settings:\n  ```json\n  {\n    \"providers\": {\n      \"dashscope\": {\n        \"type\": \"openai-compatible\",\n        \"enabled\": true,\n        \"baseUrl\": \"https://dashscope.aliyuncs.com/compatible-mode\",\n        \"apiKey\": \"sk-your-dashscope-key\",\n        \"pricingCurrency\": \"CNY\",\n        \"models\": {\n          \"qwen3.7-plus\": {\n            \"temperature\": 1,\n            \"topP\": 0.95,\n            \"topK\": 20,\n            \"extraBody\": {\n              \"preserve_thinking\": true\n            }\n          },\n          \"glm-5.1\": {\n            \"temperature\": 0.7,\n            \"topP\": 0.95,\n            \"contextCache\": true,\n            \"pricing\": {\n              \"tiers\": [\n                {\n                  \"maxInputTokens\": 32000,\n                  \"input\": 6,\n                  \"cachedInput\": 1.2,\n                  \"explicitCachedInput\": 0.6,\n                  \"cacheCreationInput\": 7.5,\n                  \"output\": 24\n                },\n                {\n                  \"maxInputTokens\": 200000,\n                  \"input\": 8,\n                  \"cachedInput\": 1.6,\n                  \"explicitCachedInput\": 0.8,\n                  \"cacheCreationInput\": 10,\n                  \"output\": 28\n                }\n              ]\n            },\n            \"extraBody\": {\n              \"preserve_thinking\": true\n            }\n          }\n        }\n      }\n    }\n  }\n  ```\n  Built-in token prices cover Codex GPT models in USD, DashScope `qwen3.7-max`, `qwen3.7-plus`, `glm-5.1`, `glm-5.2` in CNY, DeepSeek `deepseek-v4-flash`, `deepseek-v4-pro`, `deepseek-chat`, `deepseek-reasoner` in CNY, and OpenCode Go models (`glm-5.2`, `deepseek-v4-flash`, `deepseek-v4-pro`, `kimi-k2.7-code`, `mimo-v2.5`, `mimo-v2.5-pro`, `qwen3.7-plus`, `qwen3.7-max`, `minimax-m2.5`, `minimax-m3`) in USD. User `pricing` entries override built-ins. For DashScope, cached tokens are charged as explicit cache reads when the upstream usage includes `cache_creation_input_tokens`; otherwise `cachedInput` is used as the implicit cache read price. For DeepSeek, `prompt_cache_hit_tokens` map to cached input and `prompt_cache_miss_tokens` map to regular input.\n- **smallModel:** Fallback model used for tool-less warmup messages (e.g., Claude Code probe requests); defaults to gpt-5-mini.\n- **contextManagement:** Controls whether the proxy adds Responses API `context_management` compaction instructions. `messages` applies when Anthropic-style `/v1/messages` requests are translated to Responses API, including `openai-responses` provider message routes, and defaults to `true`. `responses` applies to native `/v1/responses` traffic, including `provider/model` aliases and the built-in `codex` provider, and defaults to `false`. Enable `responses` only after checking that your client supports context management compaction. When enabled, the request includes `context_management` in the body and keeps only the latest compaction carrier on follow-up turns.\n- **modelResponsesApiCompactThresholds:** Per-model Responses API `compact_threshold` overrides used when the proxy adds `context_management`. These values take precedence over the fallback threshold from `resolveResponsesCompactThreshold` (`max_prompt_tokens * ratio`, or the default fallback). Defaults set `gpt-5.4` and `gpt-5.5` to `217600` (`272000 * 0.8`), and `gpt-5.6-sol`, `gpt-5.6-terra`, `gpt-5.6-luna` to `231200` (`272000 * 0.85`). Models not listed continue to use the normal fallback logic.\n- **modelReasoningEfforts:** Per-model reasoning effort applied to `/v1/messages` requests. When routed to the Copilot native Messages API it sets `output_config.effort`; when translated to the Responses API it sets `reasoning.effort`. Allowed values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. If a model isn't listed, `high` is used by default; GPT-5.3+ models fall back to `xhigh` when not explicitly configured.\n- **useMessagesApi:** When `true`, Claude-family models that support Copilot's native `/v1/messages` endpoint will use the Messages API; otherwise they fall back to `/chat/completions`. Set to `false` to disable Messages API routing and always use `/chat/completions`. Defaults to `true`.\n- **useResponsesApiWebSocket:** When `true`, Responses API requests use Copilot's websocket transport for models that advertise `ws:/responses`; models that only advertise `/responses` continue to use HTTP. Set to `false` to disable websocket routing and use HTTP `/responses` whenever the selected model supports it. Defaults to `true`.\n- **useResponsesApiWebSearch:** When `true`, the server keeps Responses API tools with `type: \"web_search\"` and forwards them upstream. Set to `false` to strip those tools from `/responses` payloads. Defaults to `true`.\n- **messageApiWebSearchModel:** Global fallback model used when a top-level Copilot `/v1/messages` request contains only the server-side `web_search` tool. Defaults to `gpt-5-mini`. If the value is a `provider/model` alias, the request is routed into that provider's Messages API path with the provider prefix stripped. For Copilot GPT models, web search runs through `/responses`. Mixed `web_search` plus custom tools are not supported and the server-side `web_search` tool is stripped.\n- **claudeTokenMultiplier:** Multiplier applied to the fallback GPT-tokenizer estimate for Claude `/v1/messages/count_tokens` requests. Defaults to `1.15`. Increase it if your client is still compacting too late. This setting is only used when the proxy is estimating Claude tokens locally; if `anthropicApiKey` is configured and Anthropic token counting succeeds, the exact Anthropic count is returned instead.\n- **anthropicApiKey:** Anthropic API key used to forward Claude `/v1/messages/count_tokens` requests to Anthropic's real token counting endpoint, which returns exact counts instead of GPT tokenizer estimates. Can also be set via the `ANTHROPIC_API_KEY` environment variable. If not set, or if the upstream call fails, token counting falls back to local GPT tokenizer estimation controlled by `claudeTokenMultiplier`.\n\nEdit this file to customize prompts or swap in your own fast model. Restart the server (or rerun the command) after changes so the cached config is refreshed.\n\n## API Authentication\n\n- **Protected non-admin routes:** All routes except `/`, `/usage-viewer`, and `/usage-viewer/` require authentication when `auth.apiKeys` is configured and non-empty.\n- **Admin routes:** All `/admin/*` routes require `auth.adminApiKey`. If it is missing, the server generates one at startup and persists it to `config.json` before serving requests.\n- **Allowed auth headers:**\n  - `x-api-key: <your_key>`\n  - `Authorization: Bearer <your_key>`\n- **CORS preflight:** `OPTIONS` requests are always allowed.\n- **When no regular keys are configured:** Non-admin routes continue to allow requests. This does not apply to `/admin/*`, which only accepts `auth.adminApiKey`.\n\nExample request for a regular protected route:\n\n```sh\ncurl http://localhost:4141/v1/models \\\n  -H \"x-api-key: your_api_key\"\n```\n\nExample request for an admin route:\n\n```sh\ncurl http://localhost:4141/admin/config/model-mappings \\\n  -H \"x-api-key: your_admin_api_key\"\n```\n\n## API Endpoints\n\nThe server exposes several OpenAI- and Anthropic-compatible endpoints. Requests can target GitHub Copilot, the built-in `codex` provider, or configured providers depending on the selected model and `provider/model` alias.\n\n### OpenAI Compatible Endpoints\n\nThese endpoints mimic the OpenAI API structure.\n\n| Endpoint                    | Method | Description                                                      |\n| --------------------------- | ------ | ---------------------------------------------------------------- |\n| `POST /v1/responses`        | `POST` | OpenAI Most advanced interface for generating model responses. Supports `provider/model` aliases for `openai-responses` providers. |\n| `POST /v1/chat/completions` | `POST` | Creates a model response for the given chat conversation. Supports `provider/model` aliases for `openai-compatible` providers and can be used without Copilot when the target provider is configured. |\n| `GET /v1/models`            | `GET`  | Lists Copilot models plus enabled provider models using `provider/model-id` IDs. |\n| `POST /v1/embeddings`       | `POST` | Creates an embedding vector representing the input text.         |\n\n### Anthropic Compatible Endpoints\n\nThese endpoints are designed to be compatible with the Anthropic Messages API.\n\n| Endpoint                         | Method | Description                                                  |\n| -------------------------------- | ------ | ------------------------------------------------------------ |\n| `POST /v1/messages`              | `POST` | Creates a model response for a given conversation. Supports `provider/model` aliases for configured providers, including translation through `openai-compatible` providers. |\n| `POST /v1/messages/count_tokens` | `POST` | Calculates the number of tokens for a given set of messages. Supports `provider/model` aliases for configured providers. |\n| `POST /:provider/v1/messages`       | `POST` | Proxies Anthropic Messages requests to the configured Anthropic provider, translates them through an OpenAI-compatible provider, or translates them through an OpenAI Responses provider. |\n| `GET /:provider/v1/models`          | `GET`  | Proxies model listing requests to the configured provider.   |\n| `POST /:provider/v1/messages/count_tokens` | `POST` | Calculates tokens locally for provider route requests. |\n\n### Usage Monitoring Endpoints\n\nNew endpoints for monitoring your Copilot usage and quotas.\n\n| Endpoint     | Method | Description                                                  |\n| ------------ | ------ | ------------------------------------------------------------ |\n| `GET /usage` | `GET`  | Get detailed Copilot usage statistics and quota information. |\n| `GET /token` | `GET`  | Get the current Copilot token being used by the API.         |\n\n### Admin / Configuration Endpoints\n\nThese endpoints are reserved for local administrative actions and only accept `auth.adminApiKey`.\n\n| Endpoint                              | Method | Description                                                                 |\n| ------------------------------------- | ------ | --------------------------------------------------------------------------- |\n| `GET /admin/config/model-mappings`    | `GET`  | Returns the current `config.json` path and the active `modelMappings` map.  |\n| `POST /admin/config/model-mappings`   | `POST` | Updates only the `modelMappings` field in `config.json` and returns it back. |\n\n## Example Usage\n\nCommon `npx` commands:\n\n```sh\n# Start the gateway\nnpx @jeffreycao/copilot-api@latest start\n\n# Start on a custom port with verbose logging\nnpx @jeffreycao/copilot-api@latest start --port 8080 --verbose\n\n# Run the auth flow\nnpx @jeffreycao/copilot-api@latest auth login\n\n# Configure a third-party provider, then run without GitHub Copilot\nnpx @jeffreycao/copilot-api@latest auth login --provider dashscope\nnpx @jeffreycao/copilot-api@latest start\n\n# Print debug information as JSON\nnpx @jeffreycao/copilot-api@latest debug --json\n\n# Run the published CLI with Bun instead of Node.js\nbunx --bun @jeffreycao/copilot-api@latest start\n```\n\nOpenAI-compatible provider examples after configuring `dashscope`:\n\n```sh\ncurl http://localhost:4141/v1/chat/completions \\\n  -H \"content-type: application/json\" \\\n  -d '{\"model\":\"dashscope/qwen3.6-plus\",\"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]}'\n\ncurl http://localhost:4141/dashscope/v1/messages \\\n  -H \"content-type: application/json\" \\\n  -d '{\"model\":\"qwen3.6-plus\",\"max_tokens\":1024,\"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]}'\n```\n\n## Usage Tips\n\n### CLAUDE.md or AGENTS.md Recommended Content\n\nTo add these reminders manually, include the following in `CLAUDE.md` for Claude Code, or `AGENTS.md` for opencode/codex:\n\n```\n- Prohibited from directly asking questions to users, MUST use question tool.\n- Once you can confirm that the task is complete, MUST use question tool to make user confirm. The user may respond with feedback if they are not satisfied with the result, which you can use to make improvements and try again, after try again, MUST use question tool to make user confirm again.\n```\n"}, "ecd936239220164bbfcfe6f7205a6fce726d0e18": {"t": 1785765564.6417015, "n": 46792, "h": "26a1c1190d8d22b1", "c": "# Copilot API Proxy\n\nEnglish | [简体中文](./README.zh-CN.md)\n\n## Important Notes\n\n> [!IMPORTANT]\n> **Before using, please be aware of the following:**\n>\n> 1. **Claude Code configuration:** When using with Claude Code, please configure the model ID as `claude-opus-4-8`. Example claude `settings.json` see [Manual Configuration with `settings.json`](#manual-configuration-with-settingsjson). \n>\n> 2. **Built-in `copilot`, `codex` and third-party providers:** Run `npx @jeffreycao/copilot-api@latest auth` and choose `copilot`, `codex`, `deepseek`, `custom`, or other providers.\n>\n> 3. **Note:** See [GitHub Copilot Security Notice](./NOTICE.md#github-copilot-security-notice) for the warning removed from the README header.\n\n---\n\n## Project Overview\n\nA small AI gateway that can use GitHub Copilot, the built-in `codex` provider, or configured third-party providers such as DashScope. GitHub Copilot is optional: if no GitHub token is available, the server can still start in provider-only mode as long as at least one enabled provider is configured.\n\nThe gateway exposes OpenAI- and Anthropic-compatible APIs from one local endpoint, so tools like [Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview), OpenCode, Codex, and OpenAI-compatible clients can share the same local server.\n\nOn the GitHub Copilot path, the gateway prefers Copilot's native Anthropic-style Messages API when available, preserving more Claude-native behavior for tool-heavy workflows.\n\n## Features\n\n- **OpenAI and Anthropic compatibility**: Serve `/v1/responses`, `/v1/chat/completions`, `/v1/models`, `/v1/embeddings`, and `/v1/messages` from one local gateway.\n- **Copilot is optional**: Use GitHub Copilot when credentials are present, or run the server with only configured providers.\n- **One gateway for Copilot, `codex`, and external providers**: Route GitHub Copilot, the built-in `codex` provider, and configured third-party providers behind the same endpoint.\n- **Standalone third-party providers**: Configure providers such as DashScope, DeepSeek, OpenRouter, or a custom provider and start the gateway without a GitHub Copilot login.\n- **OpenAI-compatible providers on chat and Messages APIs**: `openai-compatible` providers can serve top-level `/v1/chat/completions` through `model: \"provider/model\"` and Anthropic-style `/v1/messages` through request/response translation.\n- **Agent-friendly Claude handling on Copilot**: Prefer native `/v1/messages` when available, preserve Claude-style tool flows, support Anthropic beta features, Claude WebSearch through Responses-capable models, and keep subagent/session markers intact.\n- **Claude Code and OpenCode integration**: Works with Claude Code and OpenCode, including direct Anthropic-compatible usage through `@ai-sdk/anthropic`.\n- **Flexible auth and deployment options**: Supports interactive login or direct tokens, individual/business/enterprise plans, GitHub Enterprise, opencode OAuth, and custom data directories.\n- **Multi-provider routing**: Expose provider-specific `/:provider/...` routes or use `model: \"provider/model\"` on the top-level API.\n\n## Prerequisites\n\n- Bun (>= 1.2.x)\n- Node.js if you plan to run the published CLI with `npx`\n- GitHub account with Copilot subscription only if you want to use the GitHub Copilot provider\n- An API key or OAuth login for at least one configured provider if you want to run without GitHub Copilot\n\n## Installation\n\nTo install dependencies, run:\n\n```sh\nbun install\n```\n\nTo start the server directly from source:\n\n```sh\nbun run start start\n```\n\n## Running from Source\n\nThe project can be run from source in several ways:\n\n### Development Mode\n\n```sh\nbun run dev start\n```\n\n### Production Mode\n\n```sh\nbun run start start\n```\n\n## Using with npx\n\nYou can run the project directly using npx:\n\n> [!IMPORTANT]\n> Token usage storage uses Node's built-in `node:sqlite` module when running with `npx`. It is enabled on Node.js >= 22.13.0. On Node.js < 22.13.0, the CLI still starts, but token usage storage is disabled.\n>\n> If you want token usage storage without upgrading Node.js, run the published CLI with Bun instead: `bunx --bun @jeffreycao/copilot-api@latest start`.\n\n```sh\nnpx @jeffreycao/copilot-api@latest start\n```\n\nWith options:\n\n```sh\nnpx @jeffreycao/copilot-api@latest start --port 8080\n```\n\nFor authentication or provider configuration only:\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth\n```\n\nTo run without GitHub Copilot, configure at least one provider first, then start the server normally:\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth login --provider dashscope\nnpx @jeffreycao/copilot-api@latest start\n```\n\n## Using with Docker\n\nBuild the image:\n\n```sh\ndocker build -t copilot-api .\n```\n\nRun the container with a bind mount so auth data survives restarts:\n\n```sh\nmkdir -p ./copilot-data\ndocker run -p 4141:4141 -v $(pwd)/copilot-data:/root/.local/share/copilot-api copilot-api\n```\n\nThis stores GitHub auth data, provider config, and other gateway state in `./copilot-data` on the host, mapped to `/root/.local/share/copilot-api` in the container.\n\nOr pass a GitHub token directly:\n\n```sh\ndocker run -p 4141:4141 -e GH_TOKEN=your_github_token_here copilot-api\n```\n\n## Electron Desktop App\n\nIf you prefer a GUI, this repository also includes an Electron desktop app in `desktop/`. It supports GitHub Copilot sign-in, OpenAI Codex OAuth, and API-key configuration for DeepSeek, DashScope, OpenRouter, or a custom provider. After authorization or provider configuration, it can start and stop the local proxy with one click and shows the local endpoint, auth header, available models, usage, and logs in the app.\n\nThe settings screen also exposes `OAuth App`, `API Home`, `Enterprise URL`, verbose logging, and minimize-to-tray. Desktop packages are published in GitHub Releases:\n\nhttps://github.com/caozhiyuan/copilot-api/releases\n\nDownload the installer for your platform, authorize or configure a provider inside the app, choose a port, start the server, then point your client at the local endpoint shown in the app. Packaged desktop builds use the bundled Electron runtime, so normal desktop usage does not require installing Node.js separately. Token usage history is enabled when that bundled runtime supports SQLite.\n\nThe desktop app's Advanced Config page reads and writes the shared model mappings through `GET/POST /admin/config/model-mappings`. The same mappings apply across `POST /v1/messages`, `POST /v1/messages/count_tokens`, `POST /v1/responses`, and `POST /v1/chat/completions` instead of being split per interface. It uses `auth.adminApiKey` instead of the regular `auth.apiKeys`, and the app reads that key directly from `config.json` after the server has generated it on startup.\n\n### Desktop App Screenshots\n\nMain dashboard, token usage breakdown in the bundled Electron app:\n\n<p align=\"center\">\n  <img src=\"./docs/screenshots/desktop-dashboard.png\" alt=\"Copilot API desktop app dashboard\" width=\"49%\" />\n  <img src=\"./docs/screenshots/desktop-token-usage.png\" alt=\"Copilot API desktop app token usage view\" width=\"49%\" />\n</p>\n\n## Using with Claude Code\n\nThis AI gateway can be used to power [Claude Code](https://docs.anthropic.com/en/claude-code), an experimental conversational AI assistant for developers from Anthropic.\n\nThere are two ways to configure Claude Code to use this AI gateway:\n\n### Interactive Setup with `--claude-code` flag\n\nTo get started, run the `start` command with the `--claude-code` flag:\n\n```sh\nnpx @jeffreycao/copilot-api@latest start --claude-code\n```\n\nYou will be prompted to select a primary model and a \"small, fast\" model for background tasks. After selecting the models, a command will be copied to your clipboard. This command sets the necessary environment variables for Claude Code to use the gateway.\n\nPaste and run this command in a new terminal to launch Claude Code.\n\n### Manual Configuration with `settings.json`\n\nAlternatively, you can configure Claude Code by creating a `.claude/settings.json` file in your project's root directory. This file should contain the environment variables needed by Claude Code. This way you don't need to run the interactive setup every time.\n\nHere is an example `.claude/settings.json` file:\n\n```json\n{\n  \"env\": {\n    \"ANTHROPIC_BASE_URL\": \"http://localhost:4141\",\n    \"ANTHROPIC_AUTH_TOKEN\": \"dummy\",\n    \"ANTHROPIC_MODEL\": \"deepseek/deepseek-v4-pro\",\n    \"ANTHROPIC_DEFAULT_SONNET_MODEL\": \"deepseek/deepseek-v4-pro\",\n    \"ANTHROPIC_DEFAULT_HAIKU_MODEL\": \"deepseek/deepseek-v4-flash\",\n    \"DISABLE_NON_ESSENTIAL_MODEL_CALLS\": \"1\",\n    \"CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC\": \"1\",\n    \"CLAUDE_CODE_ATTRIBUTION_HEADER\": \"0\",\n    \"CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION\": \"false\",\n    \"CLAUDE_CODE_DISABLE_TERMINAL_TITLE\": \"true\",\n    \"CLAUDE_CODE_ENABLE_AWAY_SUMMARY\": \"0\"\n  },\n  \"permissions\": {\n    \"deny\": [\n      \"mcp__ide__executeCode\"\n    ]\n  }\n}\n```\n\n- Replace `ANTHROPIC_MODEL`, `ANTHROPIC_DEFAULT_OPUS_MODEL`, `ANTHROPIC_DEFAULT_SONNET_MODEL`, and `ANTHROPIC_DEFAULT_HAIKU_MODEL` according to your needs. After configuration, please install the claude code plugin [Plugin Integrations](#plugin-integrations).  \n- Setting CLAUDE_CODE_ATTRIBUTION_HEADER to 0 can prevent Claude code from adding billing and version information in system prompts, thereby avoiding prompt cache invalidation.\n- Turning off CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION and CLAUDE_CODE_ENABLE_AWAY_SUMMARY can prevent quota from being consumed unnecessarily.\n- Claude Code WebSearch is supported for pure search requests. For Copilot, keep the global `messageApiWebSearchModel` set to a Responses-capable GPT model or a `provider/model` alias. For provider routes, use a native Anthropic provider or an `openai-responses` provider. Add `WebSearch` to `permissions.deny` only if you want to forbid this traffic.\n- If using a non-Claude model, do not enable ENABLE_TOOL_SEARCH. If using the Claude model, can enable ENABLE_TOOL_SEARCH. The current Claude Code uses the client tool search mode. In this mode, loading defer tools requires an additional request each time.\n- `CLAUDE_CODE_AUTO_COMPACT_WINDOW`: Set the context capacity in tokens used for auto-compaction calculations. Defaults to the model's context window: 200K for standard models or 1M for extended context models. Use a lower value like `500000` on a 1M model (e.g., `claude-opus-4-6[1m]`) to treat the window as 500K for compaction purposes. The value is capped at the model's actual context window. `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` is applied as a percentage of this value. Setting this variable decouples the compaction threshold from the status line's `used_percentage`, which always uses the model's full context window.\n\nYou can find more options here: [Claude Code settings](https://docs.anthropic.com/en/docs/claude-code/settings#environment-variables)\n\nYou can also read more about IDE integration here: [Add Claude Code to your IDE](https://docs.anthropic.com/en/docs/claude-code/ide-integrations)\n\n## Using with OpenCode\n\nOpenCode already has a direct GitHub Copilot provider. Use this section when you want OpenCode to point at this AI gateway through `@ai-sdk/anthropic` and reuse the agent behaviors described earlier in this README.\n\n### Minimal setup\n\nStart the AI gateway with the OpenCode OAuth app:\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth --oauth-app=opencode\nnpx @jeffreycao/copilot-api@latest start\n```\n\nThen point OpenCode at the gateway with `@ai-sdk/anthropic`.\n\nExample `~/.config/opencode/opencode.json`:\n\n```json\n{\n  \"$schema\": \"https://opencode.ai/config.json\",\n  \"provider\": {\n    \"local\": {\n      \"npm\": \"@ai-sdk/anthropic\",\n      \"name\": \"My Local\",\n      \"options\": {\n        \"baseURL\": \"http://localhost:4141/v1\",\n        \"apiKey\": \"dummy\"\n      },\n      \"models\": {\n        \"gpt-5.4\": {\n          \"name\": \"gpt-5.4\",\n          \"modalities\": {\n            \"input\": [\"text\", \"image\"],\n            \"output\": [\"text\"]\n          },\n          \"limit\": {\n            \"context\": 400000,\n            \"input\": 272000,\n            \"output\": 128000\n          }\n        },\n        \"claude-sonnet-4.6\": {\n          \"id\": \"claude-sonnet-4.6\",\n          \"name\": \"claude-sonnet-4.6\",\n          \"modalities\": {\n            \"input\": [\"text\", \"image\"],\n            \"output\": [\"text\"]\n          },          \n          \"limit\": {\n            \"context\": 200000,\n            \"output\": 32000\n          },\n          \"options\": {\n            \"thinking\": {\n              \"type\": \"adaptive\"\n            },\n            \"effort\": \"max\"\n          }\n        }\n      }\n    }\n  }\n}\n```\n\nWhy these fields matter:\n\n- `npm: \"@ai-sdk/anthropic\"` is the important part. OpenCode will speak Anthropic Messages semantics to this AI gateway instead of flattening everything into OpenAI Chat Completions.\n- `options.baseURL` should be `http://localhost:4141/v1`; the Anthropic SDK will append `/messages`, `/models`, and `/messages/count_tokens` automatically.\n- If you enable `auth.apiKeys` in this AI gateway, replace `dummy` with a real key. Otherwise any placeholder value is fine.\n\n## Using with Codex\n\nThis AI gateway can also power Codex.\n\n### Codex `config.toml` Reference\n\nAdd the following `[model_providers.copilot_api]` section to your Codex `~/.codex/config.toml`:\n\n```toml\nmodel_provider = \"copilot_api\"\nmodel_reasoning_summary = \"auto\"\nmodel_verbosity = \"medium\"\nmodel_context_window = 272000\nmodel_auto_compact_token_limit = 244800\n\n[model_providers.copilot_api]\nname = \"OpenAI\"\nbase_url = \"http://localhost:4141\"\nenv_key = \"GITHUB_COPILOT_API_KEY\"\nrequires_openai_auth = true\nsupports_websockets = false\nwire_api = \"responses\"\nrequest_max_retries = 3\nstream_max_retries = 1\nstream_idle_timeout_ms = 300000\n\n[features]\nremote_compaction_v2 = true\n\n[analytics]\nenabled = false\n```\n\n> [!NOTE]\n> This configuration is specific to Codex and the GitHub Copilot provider. `name` must be set to `\"OpenAI\"`. It can help mitigate Codex local compact cache miss issues. If you enable `contextManagement.responses` (Responses API context management compaction), `remote_compaction_v2` or local compact is generally not triggered, but it may still occur when tool results return a large number of tokens. Before enabling it for native Responses API traffic, check that your client supports context management compaction.\n\n## GPT Tool Search\n\nFor GPT Responses models such as `gpt-5.4+`, this AI gateway can expose Responses `tool_search` through a small MCP bridge. The same bridge can be used by Claude Code and opencode, as long as the client loads MCP servers and sends Anthropic Messages traffic through this gateway.\n\nDo not set Claude Code's native `ENABLE_TOOL_SEARCH` for GPT models. That flag enables Claude Code's own client-side tool search mode, and it may stop forwarding deferred tool definitions. This gateway needs the full tool definitions so it can keep the small always-loaded tool set eager and translate every other tool into Responses deferred namespaces.\n\nIf you install `tool-search@copilot-api-marketplace`, Claude Code receives this MCP bridge automatically and you can skip the manual Claude Code MCP setup below.\n\nAdd the tool search bridge to the MCP config used by Claude Code:\n\n```json\n{\n  \"mcpServers\": {\n    \"tool_search\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@jeffreycao/copilot-api@latest\", \"mcp\"]\n    }\n  }\n}\n```\n\nAdd the tool search bridge to the MCP config used by opencode:\n\n```json\n{\n  \"mcp\": {\n    \"tool_search\": {\n      \"type\": \"local\",\n      \"command\": [\"npx\", \"-y\", \"@jeffreycao/copilot-api@latest\", \"mcp\"]\n    }\n  }\n}\n```\n\nFor local development, use `bun` as the command and `[\"run\", \"./src/main.ts\", \"mcp\"]` as the args.\n\nInternally, the gateway now configures OpenAI Responses `tool_search` in client-executed mode. Deferred tools are still exposed as searchable namespaces, but the model is explicitly asked to return the exact deferred tool names it wants to load next.\n\nThe bridge uses direct tool selection, not query search. Its tool input is `names`, a comma-separated list of exact deferred tool names, for example `TaskList,TaskGet,mcp__fetch__fetch`.\n\n## Plugin Integrations\n\nPlugin integrations are available for Claude Code and opencode.\n\n#### Claude Code plugin integration (marketplace-based)\n\nThe Claude Code integration is packaged as two plugins:\n\n- `agent-inject` injects `__SUBAGENT_MARKER__...` on `SubagentStart`, so the gateway can infer `x-initiator: agent`.\n- `tool-search` registers the `tool_search` MCP bridge used for GPT Responses deferred tool loading.\n\n- Marketplace catalog in this repository: `.claude-plugin/marketplace.json`\n- Plugin sources in this repository: `plugin/claude/agent-inject`, `plugin/claude/tool-search`\n\nAdd the marketplace remotely:\n\n```sh\n/plugin marketplace add https://github.com/caozhiyuan/copilot-api.git\n```\n\nInstall the plugins from the marketplace:\n\n```sh\n/plugin install agent-inject@copilot-api-marketplace\n/plugin install tool-search@copilot-api-marketplace\n```\n\nAfter installation, `agent-inject` injects `__SUBAGENT_MARKER__...` on `SubagentStart`, and the gateway uses it to infer `x-initiator: agent`.\n\nThe `agent-inject` plugin also registers a `UserPromptSubmit` hook that returns `{\"continue\": true}`, and it can inject `SessionStart` reminder rules through environment variables:\n\n- `CLAUDE_PLUGIN_ENABLE_QUESTION_RULES=1` enables the two reminders about using the `question` tool automatically for Claude Code. Alternatively, you can add the same reminders manually in `CLAUDE.md`; see [CLAUDE.md or AGENTS.md Recommended Content](#claudemd-or-agentsmd-recommended-content).\n- `CLAUDE_PLUGIN_ENABLE_NO_BACKGROUND_AGENTS_RULE=1` enables the `run_in_background: true` avoidance reminder for agent hooks.\n\nThe `tool-search` plugin bundles the same MCP bridge described in [GPT Tool Search](#gpt-tool-search), so Claude Code users do not need to add the `tool_search` server manually when they install that plugin.\n\n#### Opencode plugin\n\nThe subagent marker producer is packaged as an opencode plugin located at `plugin/opencode/subagent-marker.js`.\n\n**Installation:**\n\nCopy the plugin file to your opencode plugins directory:\n\n```sh\n# Clone or download this repository, then copy the plugin\ncp plugin/opencode/subagent-marker.js ~/.config/opencode/plugins/\n```\n\nOr manually create the file at `~/.config/opencode/plugins/subagent-marker.js` with the plugin content.\n\n**Features:**\n\n- Tracks sub-sessions created by subagents\n- Automatically prepends a marker system reminder (`__SUBAGENT_MARKER__...`) to subagent chat messages\n- Sets `x-session-id` header for session tracking\n- Enables the gateway to infer `x-initiator: agent` for subagent-originated requests\n\nThe plugin hooks into `session.created`, `session.deleted`, `chat.message`, and `chat.headers` events to provide seamless subagent marker functionality.\n\n## Using the Usage Viewer\n\nAfter starting the server, a URL to the Copilot Usage Dashboard will be displayed in your console. This dashboard is a web interface for monitoring your API usage.\n\n1.  Start the server. For example, using npx:\n    ```sh\n    npx @jeffreycao/copilot-api@latest start\n    ```\n2.  The server will output a URL to the usage viewer. Copy and paste this URL into your browser. It will look something like this:\n    `http://localhost:4141/usage-viewer?endpoint=http://localhost:4141/usage`\n    - If you use the `start.bat` script on Windows, this page will open automatically.\n\nThe dashboard provides a user-friendly interface to view your Copilot usage data:\n\n> Token usage history requires Bun or Node.js >= 22.13.0. On Node.js < 22.13.0, the server runs normally but token usage storage is disabled.\n\n- **API Endpoint URL**: The dashboard is pre-configured to fetch data from your local server endpoint via a URL query parameter. You can manually switch this to any other compatible API endpoint.\n- **x-api-key Authentication**: If API Key authentication is enabled, you can provide the `x-api-key` request header. The key is persisted in the browser's local storage.\n- **Period Selector**: Choose from Day, Week, or Month time ranges. The URL query parameter updates automatically when you switch, making it easy to bookmark and share.\n- **Fetch Data**: Click the \"Refresh\" button to load or refresh the usage data. The dashboard also fetches data automatically on page load.\n- **Copilot Quotas**: View quota usage for services such as Chat and Completions via progress bars. Hover over a card to see used/remaining details.\n- **Token Usage Metric Cards**: See a summary of Total, Input, Output, Cache Read, Cache Write, Requests, and estimated cost for the current period.\n- **Trend Chart (Week / Month)**: An interactive line chart with model and metric filters. Click a data point to inspect the usage breakdown for a specific day.\n- **Model Breakdown Table**: A per-model summary of requests, input/output/cache tokens, and estimated cost for the selected period.\n- **Request Events (Paginated)**: A time-sorted list of request event records with pagination support, showing timestamps, models, request IDs, and token counts.\n- **Detailed Information**: See the full JSON response from the API for a detailed breakdown of all available usage statistics.\n- **URL-based Configuration**: You can also specify the API endpoint and period directly via `endpoint` and `period` query parameters. For example:\n  `http://localhost:4141/usage-viewer?endpoint=http://your-api-server/usage&period=week`\n\n### Usage Viewer Screenshot\n\n<p align=\"center\">\n  <img src=\"./docs/screenshots/usage-viewer.png\" alt=\"Copilot API usage viewer\" width=\"900\" />\n</p>\n\n## Command Structure\n\nCopilot API now uses a subcommand structure with these main commands:\n\n- `start`: Start the gateway server. If a GitHub token is available, the server starts with Copilot enabled. If no GitHub token is available, it starts in provider-only mode when at least one enabled provider exists; otherwise it guides you through provider setup.\n- `auth`: Run provider login or configuration without starting the server. Use it for GitHub Copilot login, Codex OAuth, or third-party provider API key setup.\n- `debug`: Display diagnostic information including version, runtime details, file paths, and authentication status. Useful for troubleshooting and support.\n\n## Command Line Options\n\n### Global Options\n\nThe following options can be used with any subcommand. When passing them before the subcommand, use the `--key=value` form:\n\n| Option            | Description                                            | Default | Alias |\n| ----------------- | ------------------------------------------------------ | ------- | ----- |\n| --api-home        | Path to the API home directory (sets COPILOT_API_HOME) | none    | none  |\n| --oauth-app       | OAuth app identifier (sets COPILOT_API_OAUTH_APP)      | none    | none  |\n| --enterprise-url  | Enterprise URL for GitHub (sets COPILOT_API_ENTERPRISE_URL) | none | none |\n\n### Start Command Options\n\nThe following command line options are available for the `start` command:\n\n| Option         | Description                                                                   | Default    | Alias |\n| -------------- | ----------------------------------------------------------------------------- | ---------- | ----- |\n| --port         | Port to listen on                                                             | 4141       | -p    |\n| --verbose      | Enable verbose logging                                                        | false      | -v    |\n| --github-token | Provide GitHub token directly (must be generated using the `auth` subcommand) | none       | -g    |\n| --claude-code  | Generate a command to launch Claude Code with Copilot API config              | false      | -c    |\n| --show-token   | Show GitHub and Copilot tokens on fetch and refresh                           | false      | none  |\n| --proxy-env    | Initialize proxy from environment variables                                   | false      | none  |\n\n### Auth Command Options\n\n| Option       | Description               | Default | Alias |\n| ------------ | ------------------------- | ------- | ----- |\n| --provider   | Provider to log in with or configure (`copilot`, `codex`, `opencode-go`, `deepseek`, `dashscope`, `openrouter`, or `custom`) | prompt | none |\n| --verbose    | Enable verbose logging    | false   | -v    |\n| --show-token | Show GitHub token on auth | false   | none  |\n\nUse `copilot-api auth login --provider copilot` only when you want to enable the GitHub Copilot provider. Copilot is not required for `codex` or third-party provider-only usage.\n\nUse `copilot-api auth login --provider deepseek`, `--provider dashscope`, `--provider openrouter`, or `--provider opencode-go` to add or update those common third-party providers from the CLI. DeepSeek prompts for masked `apiKey`, provider `type` (default `anthropic`), and `baseUrl` defaulting to `https://api.deepseek.com/anthropic`. DashScope prompts for masked `apiKey`, provider `type` (default `openai-compatible`), and prefilled `baseUrl`. OpenRouter prompts for masked `apiKey` and prefilled `baseUrl` only, and writes `type: \"anthropic\"`. OpenCode Go prompts for masked `apiKey` and prefilled `baseUrl` only, and writes `type: \"openai-compatible\"` (baseUrl `https://opencode.ai/zen/go`). After a provider is configured and enabled, `copilot-api start` can run without any GitHub token.\n\nUse `copilot-api auth login --provider custom` to add or update another third-party provider from the CLI. The command prompts for the provider name, supported type (`anthropic`, `openai-compatible`, or `openai-responses`), `baseUrl`, masked `apiKey`, and `authType`; `authType` may be left as the type default or set to `x-api-key` / `authorization`.\n\n### Debug Command Options\n\n| Option | Description               | Default | Alias |\n| ------ | ------------------------- | ------- | ----- |\n| --json | Output debug info as JSON | false   | none  |\n\n## Configuration (config.json)\n\n- **Location:** `~/.local/share/copilot-api/config.json` (Linux/macOS) or `%USERPROFILE%\\.local\\share\\copilot-api\\config.json` (Windows).\n- **Default shape:**\n  ```json\n  {\n    \"auth\": {\n      \"apiKeys\": [],\n      \"adminApiKey\": \"<auto-generated-on-startup>\"\n    },\n    \"providers\": {},\n    \"modelMappings\": {},\n    \"extraPrompts\": {\n      \"gpt-5-mini\": \"<built-in exploration prompt>\"\n    },\n    \"smallModel\": \"gpt-5-mini\",\n    \"contextManagement\": {\n      \"messages\": true,\n      \"responses\": false\n    },\n    \"modelResponsesApiCompactThresholds\": {\n      \"gpt-5.4\": 217600,\n      \"gpt-5.5\": 217600\n    },\n    \"modelReasoningEfforts\": {\n      \"gpt-5-mini\": \"low\"\n    },\n    \"useMessagesApi\": true,\n    \"useResponsesApiWebSocket\": true,\n    \"useResponsesApiWebSearch\": true,\n    \"messageApiWebSearchModel\": \"gpt-5-mini\"\n  }\n  ```\n- **auth.apiKeys:** API keys used for request authentication on non-admin routes. Supports multiple keys for rotation. Requests can authenticate with either `x-api-key: <key>` or `Authorization: Bearer <key>`. If empty or omitted, authentication for non-admin routes is disabled.\n- **auth.adminApiKey:** Single admin key used only for `/admin/*` routes. If missing, the server generates a random key at startup and writes it back to `config.json`. Requests use the same `x-api-key` or `Authorization: Bearer` headers, but regular `auth.apiKeys` never grant access to `/admin/*`.\n- **modelMappings:** Exact `sourceModel -> targetModel` rewrites shared by top-level `POST /v1/messages`, `POST /v1/messages/count_tokens`, `POST /v1/responses`, and `POST /v1/chat/completions` requests. Omit it or leave it as `{}` to disable rewrites. Both the source and target must be non-empty strings. Targets can be regular model IDs or `provider/model` aliases such as `dashscope/qwen3.6-plus`, and the rewrite happens before provider alias parsing. These mappings are not split per interface. The admin endpoints `GET/POST /admin/config/model-mappings` read and update only this field.\n- **extraPrompts:** Map of `model -> prompt` appended to the first system prompt when translating Anthropic-style requests to Responses API. Use this to inject guardrails or guidance per model. Missing default entries are auto-added without overwriting your custom prompts. For GPT-5.3+ models (e.g. `gpt-5.3-codex`, `gpt-5.4`, `gpt-5.5`), a built-in commentary prompt is used as fallback when not explicitly configured. The built-in prompts enable phase-aware commentary, which lets the model emit a short user-facing progress update before tools or deeper reasoning.\n- **providers:** Global upstream provider map. Each provider key (for example `dashscope`) becomes a route prefix (`/dashscope/v1/messages`). Supports `type: \"anthropic\"`, `type: \"openai-compatible\"`, and `type: \"openai-responses\"`. Top-level clients can also use `model: \"dashscope/model-id\"` with `/v1/messages`, `/v1/messages/count_tokens`, `/v1/responses`, and `/v1/chat/completions`; the gateway strips the `dashscope/` prefix before forwarding upstream. `openai-compatible` providers support both chat and Messages flows: `/v1/chat/completions` is proxied to upstream `/v1/chat/completions`, while `/v1/messages` and `/:provider/v1/messages` are translated to upstream chat completions and translated back to Anthropic Messages responses. `GET /v1/models` aggregates enabled provider models with `provider/model-id` IDs; use `GET /dashscope/v1/models` for a single provider's raw model list.\n  - `enabled` defaults to `true` if omitted.\n  - `baseUrl` should be provider API base URL without the final endpoint. For Anthropic providers, omit `/v1/messages`; for OpenAI-compatible providers, omit `/v1/chat/completions`; for OpenAI Responses providers, omit `/v1/responses`.\n  - `apiKey` is used as the upstream credential value and is required for regular providers.\n  - `authType` (optional): Controls how `apiKey` is sent upstream. Supports `x-api-key` and `authorization` for regular providers. Anthropic providers default to `x-api-key`; OpenAI-compatible and OpenAI Responses providers default to `authorization`. When set to `authorization`, the proxy sends `Authorization: Bearer <apiKey>`. `oauth2` is reserved for the built-in `codex` provider and is written automatically by `auth login --provider codex`.\n  - `pricingCurrency` (optional): Provider-level currency used for token cost calculation, for example `USD` or `CNY`. Quick providers default to `CNY` for DashScope and DeepSeek, and `USD` for Codex/OpenRouter. Costs are grouped by currency and are not exchange-rate converted.\n  - `models` (optional): Per-model configuration map. Each key is a model ID (matching the model name in requests), and the value is:\n    - `temperature` (optional): Default temperature value used when the request does not specify one.\n    - `topP` (optional): Default top_p value used when the request does not specify one.\n    - `topK` (optional): Default top_k value used when the request does not specify one.\n    - `extraBody` (optional): Dynamic fields merged into the upstream request body for that model. Request body fields with the same name take precedence. OpenAI-compatible providers can use this for fields such as `enable_thinking`, `preserve_thinking`, `reasoning_effort`. `thinking_budget` is a special OpenAI-compatible provider override: when configured in `extraBody`, it is forced after Anthropic `thinking.budget_tokens` translation and overrides the request-derived budget. For providers whose name is `dashscope` or whose `baseUrl` contains `aliyuncs.com`, the request-derived `thinking_budget` (from Anthropic `thinking.budget_tokens`) is forwarded upstream; for other OpenAI-compatible providers the request-derived `thinking_budget` is stripped, while an `extraBody` `thinking_budget` is still honored. For DashScope providers, `preserve_thinking` defaults to `true` when not explicitly set in `extraBody` or the request body.\n    - `pricing` (optional): Per-model token prices, in the provider `pricingCurrency`, per 1M tokens. Supported fields are `input`, `output`, `cachedInput` (implicit cache read), `explicitCachedInput` (explicit cache read), and `cacheCreationInput`. Use `tiers` with `maxInputTokens` for input-size tiered pricing.\n    - `contextCache` (optional): Defaults to `true` for providers whose name is `dashscope` or whose `baseUrl` contains `aliyuncs.com`; defaults to `false` for other OpenAI-compatible providers. This enables Alibaba Cloud Model Studio/DashScope explicit context cache by injecting `cache_control: { \"type\": \"ephemeral\" }` on up to 4 content blocks using the Context Cache format. The cache breakpoint strategy matches opencode's main provider flow: the first 2 system messages plus the last 2 non-system messages. Marked string content is converted to text content part arrays for `system` / `user` / `assistant` / `tool` messages; existing array content is marked on the last part. Set this to `false` when the model already supports implicit caching, or when the upstream does not accept this explicit-cache extension field. Set this to `true` for non-DashScope providers that support the same explicit-cache extension. Applied on both `/v1/messages` and `/v1/chat/completions` routes.\n    - `supportPdf` (optional): Controls whether the model supports PDF/document content. Defaults to `false`; unsupported PDFs are converted to a text notice. Set it to `true` to send PDF/document blocks as OpenAI Chat Completions file parts.\n    - `toolContentSupportType` (optional): Tool result content capabilities for that model, as an array of `array`, `image`, and `pdf`. Provider routes default to string-only tool content when omitted. If `supportPdf` is `true` but this list does not include `pdf`, file parts in tool results are moved to user role messages. This provider default does not change the Copilot main flow, which continues to support array + image and not PDF.\n    - `type` (optional): Per-model override of the provider protocol type. Supports `anthropic`, `openai-compatible`, and `openai-responses`. When set, the provider's `/v1/messages` route uses this model's type instead of the provider-level type for request routing, auth header resolution, and upstream endpoint selection. This is useful for providers like OpenCode Go whose upstream supports both OpenAI-compatible and Anthropic Messages APIs for different models. When the type is overridden, the auth header is resolved from the overridden type's default (Anthropic defaults to `x-api-key`; OpenAI-compatible/Responses default to `authorization`).\n\n  Example DashScope model settings:\n  ```json\n  {\n    \"providers\": {\n      \"dashscope\": {\n        \"type\": \"openai-compatible\",\n        \"enabled\": true,\n        \"baseUrl\": \"https://dashscope.aliyuncs.com/compatible-mode\",\n        \"apiKey\": \"sk-your-dashscope-key\",\n        \"pricingCurrency\": \"CNY\",\n        \"models\": {\n          \"qwen3.7-plus\": {\n            \"temperature\": 1,\n            \"topP\": 0.95,\n            \"topK\": 20,\n            \"extraBody\": {\n              \"preserve_thinking\": true\n            }\n          },\n          \"glm-5.1\": {\n            \"temperature\": 0.7,\n            \"topP\": 0.95,\n            \"contextCache\": true,\n            \"pricing\": {\n              \"tiers\": [\n                {\n                  \"maxInputTokens\": 32000,\n                  \"input\": 6,\n                  \"cachedInput\": 1.2,\n                  \"explicitCachedInput\": 0.6,\n                  \"cacheCreationInput\": 7.5,\n                  \"output\": 24\n                },\n                {\n                  \"maxInputTokens\": 200000,\n                  \"input\": 8,\n                  \"cachedInput\": 1.6,\n                  \"explicitCachedInput\": 0.8,\n                  \"cacheCreationInput\": 10,\n                  \"output\": 28\n                }\n              ]\n            },\n            \"extraBody\": {\n              \"preserve_thinking\": true\n            }\n          }\n        }\n      }\n    }\n  }\n  ```\n  Built-in token prices cover Codex GPT models in USD, DashScope `qwen3.7-max`, `qwen3.7-plus`, `glm-5.1`, `glm-5.2` in CNY, DeepSeek `deepseek-v4-flash`, `deepseek-v4-pro`, `deepseek-chat`, `deepseek-reasoner` in CNY, and OpenCode Go models (`glm-5.2`, `deepseek-v4-flash`, `deepseek-v4-pro`, `kimi-k2.7-code`, `mimo-v2.5`, `mimo-v2.5-pro`, `qwen3.7-plus`, `qwen3.7-max`, `minimax-m2.5`, `minimax-m3`) in USD. User `pricing` entries override built-ins. For DashScope, cached tokens are charged as explicit cache reads when the upstream usage includes `cache_creation_input_tokens`; otherwise `cachedInput` is used as the implicit cache read price. For DeepSeek, `prompt_cache_hit_tokens` map to cached input and `prompt_cache_miss_tokens` map to regular input.\n- **smallModel:** Fallback model used for tool-less warmup messages (e.g., Claude Code probe requests); defaults to gpt-5-mini.\n- **contextManagement:** Controls whether the proxy adds Responses API `context_management` compaction instructions. `messages` applies when Anthropic-style `/v1/messages` requests are translated to Responses API, including `openai-responses` provider message routes, and defaults to `true`. `responses` applies to native `/v1/responses` traffic, including `provider/model` aliases and the built-in `codex` provider, and defaults to `false`. Enable `responses` only after checking that your client supports context management compaction. When enabled, the request includes `context_management` in the body and keeps only the latest compaction carrier on follow-up turns.\n- **modelResponsesApiCompactThresholds:** Per-model Responses API `compact_threshold` overrides used when the proxy adds `context_management`. These values take precedence over the fallback threshold from `resolveResponsesCompactThreshold` (`max_prompt_tokens * ratio`, or the default fallback). Defaults set `gpt-5.4` and `gpt-5.5` to `217600` (`272000 * 0.8`). Models not listed continue to use the normal fallback logic.\n- **modelReasoningEfforts:** Per-model reasoning effort applied to `/v1/messages` requests. When routed to the Copilot native Messages API it sets `output_config.effort`; when translated to the Responses API it sets `reasoning.effort`. Allowed values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. If a model isn't listed, `high` is used by default; GPT-5.3+ models fall back to `xhigh` when not explicitly configured.\n- **useMessagesApi:** When `true`, Claude-family models that support Copilot's native `/v1/messages` endpoint will use the Messages API; otherwise they fall back to `/chat/completions`. Set to `false` to disable Messages API routing and always use `/chat/completions`. Defaults to `true`.\n- **useResponsesApiWebSocket:** When `true`, Responses API requests use Copilot's websocket transport for models that advertise `ws:/responses`; models that only advertise `/responses` continue to use HTTP. Set to `false` to disable websocket routing and use HTTP `/responses` whenever the selected model supports it. Defaults to `true`.\n- **useResponsesApiWebSearch:** When `true`, the server keeps Responses API tools with `type: \"web_search\"` and forwards them upstream. Set to `false` to strip those tools from `/responses` payloads. Defaults to `true`.\n- **messageApiWebSearchModel:** Global fallback model used when a top-level Copilot `/v1/messages` request contains only the server-side `web_search` tool. Defaults to `gpt-5-mini`. If the value is a `provider/model` alias, the request is routed into that provider's Messages API path with the provider prefix stripped. For Copilot GPT models, web search runs through `/responses`. Mixed `web_search` plus custom tools are not supported and the server-side `web_search` tool is stripped.\n- **claudeTokenMultiplier:** Multiplier applied to the fallback GPT-tokenizer estimate for Claude `/v1/messages/count_tokens` requests. Defaults to `1.15`. Increase it if your client is still compacting too late. This setting is only used when the proxy is estimating Claude tokens locally; if `anthropicApiKey` is configured and Anthropic token counting succeeds, the exact Anthropic count is returned instead.\n- **anthropicApiKey:** Anthropic API key used to forward Claude `/v1/messages/count_tokens` requests to Anthropic's real token counting endpoint, which returns exact counts instead of GPT tokenizer estimates. Can also be set via the `ANTHROPIC_API_KEY` environment variable. If not set, or if the upstream call fails, token counting falls back to local GPT tokenizer estimation controlled by `claudeTokenMultiplier`.\n\nEdit this file to customize prompts or swap in your own fast model. Restart the server (or rerun the command) after changes so the cached config is refreshed.\n\n## API Authentication\n\n- **Protected non-admin routes:** All routes except `/`, `/usage-viewer`, and `/usage-viewer/` require authentication when `auth.apiKeys` is configured and non-empty.\n- **Admin routes:** All `/admin/*` routes require `auth.adminApiKey`. If it is missing, the server generates one at startup and persists it to `config.json` before serving requests.\n- **Allowed auth headers:**\n  - `x-api-key: <your_key>`\n  - `Authorization: Bearer <your_key>`\n- **CORS preflight:** `OPTIONS` requests are always allowed.\n- **When no regular keys are configured:** Non-admin routes continue to allow requests. This does not apply to `/admin/*`, which only accepts `auth.adminApiKey`.\n\nExample request for a regular protected route:\n\n```sh\ncurl http://localhost:4141/v1/models \\\n  -H \"x-api-key: your_api_key\"\n```\n\nExample request for an admin route:\n\n```sh\ncurl http://localhost:4141/admin/config/model-mappings \\\n  -H \"x-api-key: your_admin_api_key\"\n```\n\n## API Endpoints\n\nThe server exposes several OpenAI- and Anthropic-compatible endpoints. Requests can target GitHub Copilot, the built-in `codex` provider, or configured providers depending on the selected model and `provider/model` alias.\n\n### OpenAI Compatible Endpoints\n\nThese endpoints mimic the OpenAI API structure.\n\n| Endpoint                    | Method | Description                                                      |\n| --------------------------- | ------ | ---------------------------------------------------------------- |\n| `POST /v1/responses`        | `POST` | OpenAI Most advanced interface for generating model responses. Supports `provider/model` aliases for `openai-responses` providers. |\n| `POST /v1/chat/completions` | `POST` | Creates a model response for the given chat conversation. Supports `provider/model` aliases for `openai-compatible` providers and can be used without Copilot when the target provider is configured. |\n| `GET /v1/models`            | `GET`  | Lists Copilot models plus enabled provider models using `provider/model-id` IDs. |\n| `POST /v1/embeddings`       | `POST` | Creates an embedding vector representing the input text.         |\n\n### Anthropic Compatible Endpoints\n\nThese endpoints are designed to be compatible with the Anthropic Messages API.\n\n| Endpoint                         | Method | Description                                                  |\n| -------------------------------- | ------ | ------------------------------------------------------------ |\n| `POST /v1/messages`              | `POST` | Creates a model response for a given conversation. Supports `provider/model` aliases for configured providers, including translation through `openai-compatible` providers. |\n| `POST /v1/messages/count_tokens` | `POST` | Calculates the number of tokens for a given set of messages. Supports `provider/model` aliases for configured providers. |\n| `POST /:provider/v1/messages`       | `POST` | Proxies Anthropic Messages requests to the configured Anthropic provider, translates them through an OpenAI-compatible provider, or translates them through an OpenAI Responses provider. |\n| `GET /:provider/v1/models`          | `GET`  | Proxies model listing requests to the configured provider.   |\n| `POST /:provider/v1/messages/count_tokens` | `POST` | Calculates tokens locally for provider route requests. |\n\n### Usage Monitoring Endpoints\n\nNew endpoints for monitoring your Copilot usage and quotas.\n\n| Endpoint     | Method | Description                                                  |\n| ------------ | ------ | ------------------------------------------------------------ |\n| `GET /usage` | `GET`  | Get detailed Copilot usage statistics and quota information. |\n| `GET /token` | `GET`  | Get the current Copilot token being used by the API.         |\n\n### Admin / Configuration Endpoints\n\nThese endpoints are reserved for local administrative actions and only accept `auth.adminApiKey`.\n\n| Endpoint                              | Method | Description                                                                 |\n| ------------------------------------- | ------ | --------------------------------------------------------------------------- |\n| `GET /admin/config/model-mappings`    | `GET`  | Returns the current `config.json` path and the active `modelMappings` map.  |\n| `POST /admin/config/model-mappings`   | `POST` | Updates only the `modelMappings` field in `config.json` and returns it back. |\n\n## Example Usage\n\nCommon `npx` commands:\n\n```sh\n# Start the gateway\nnpx @jeffreycao/copilot-api@latest start\n\n# Start on a custom port with verbose logging\nnpx @jeffreycao/copilot-api@latest start --port 8080 --verbose\n\n# Run the auth flow\nnpx @jeffreycao/copilot-api@latest auth login\n\n# Configure a third-party provider, then run without GitHub Copilot\nnpx @jeffreycao/copilot-api@latest auth login --provider dashscope\nnpx @jeffreycao/copilot-api@latest start\n\n# Print debug information as JSON\nnpx @jeffreycao/copilot-api@latest debug --json\n\n# Run the published CLI with Bun instead of Node.js\nbunx --bun @jeffreycao/copilot-api@latest start\n```\n\nOpenAI-compatible provider examples after configuring `dashscope`:\n\n```sh\ncurl http://localhost:4141/v1/chat/completions \\\n  -H \"content-type: application/json\" \\\n  -d '{\"model\":\"dashscope/qwen3.6-plus\",\"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]}'\n\ncurl http://localhost:4141/dashscope/v1/messages \\\n  -H \"content-type: application/json\" \\\n  -d '{\"model\":\"qwen3.6-plus\",\"max_tokens\":1024,\"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]}'\n```\n\n## Usage Tips\n\n### CLAUDE.md or AGENTS.md Recommended Content\n\nTo add these reminders manually, include the following in `CLAUDE.md` for Claude Code, or `AGENTS.md` for opencode/codex:\n\n```\n- Prohibited from directly asking questions to users, MUST use question tool.\n- Once you can confirm that the task is complete, MUST use question tool to make user confirm. The user may respond with feedback if they are not satisfied with the result, which you can use to make improvements and try again, after try again, MUST use question tool to make user confirm again.\n```\n"}, "e4c906ff0da3d9367c09a56332e6a2e82535dfd6": {"t": 1785765566.138863, "n": 46354, "h": "43b177965cbe20ee", "c": "# Copilot API Proxy\n\nEnglish | [简体中文](./README.zh-CN.md)\n\n## Important Notes\n\n> [!IMPORTANT]\n> **Before using, please be aware of the following:**\n>\n> 1. **Claude Code configuration:** When using with Claude Code, please configure the model ID as `claude-opus-4-8`. Example claude `settings.json` see [Manual Configuration with `settings.json`](#manual-configuration-with-settingsjson). \n>\n> 2. **Built-in `copilot`, `codex` and third-party providers:** Run `npx @jeffreycao/copilot-api@latest auth` and choose `copilot`, `codex`, `deepseek`, `custom`, or other providers.\n>\n> 3. **Note:** See [GitHub Copilot Security Notice](./NOTICE.md#github-copilot-security-notice) for the warning removed from the README header.\n\n---\n\n## Project Overview\n\nA small AI gateway that can use GitHub Copilot, the built-in `codex` provider, or configured third-party providers such as DashScope. GitHub Copilot is optional: if no GitHub token is available, the server can still start in provider-only mode as long as at least one enabled provider is configured.\n\nThe gateway exposes OpenAI- and Anthropic-compatible APIs from one local endpoint, so tools like [Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview), OpenCode, Codex, and OpenAI-compatible clients can share the same local server.\n\nOn the GitHub Copilot path, the gateway prefers Copilot's native Anthropic-style Messages API when available, preserving more Claude-native behavior for tool-heavy workflows.\n\n## Features\n\n- **OpenAI and Anthropic compatibility**: Serve `/v1/responses`, `/v1/chat/completions`, `/v1/models`, `/v1/embeddings`, and `/v1/messages` from one local gateway.\n- **Copilot is optional**: Use GitHub Copilot when credentials are present, or run the server with only configured providers.\n- **One gateway for Copilot, `codex`, and external providers**: Route GitHub Copilot, the built-in `codex` provider, and configured third-party providers behind the same endpoint.\n- **Standalone third-party providers**: Configure providers such as DashScope, DeepSeek, OpenRouter, or a custom provider and start the gateway without a GitHub Copilot login.\n- **OpenAI-compatible providers on chat and Messages APIs**: `openai-compatible` providers can serve top-level `/v1/chat/completions` through `model: \"provider/model\"` and Anthropic-style `/v1/messages` through request/response translation.\n- **Agent-friendly Claude handling on Copilot**: Prefer native `/v1/messages` when available, preserve Claude-style tool flows, support Anthropic beta features, Claude WebSearch through Responses-capable models, and keep subagent/session markers intact.\n- **Claude Code and OpenCode integration**: Works with Claude Code and OpenCode, including direct Anthropic-compatible usage through `@ai-sdk/anthropic`.\n- **Flexible auth and deployment options**: Supports interactive login or direct tokens, individual/business/enterprise plans, GitHub Enterprise, opencode OAuth, and custom data directories.\n- **Multi-provider routing**: Expose provider-specific `/:provider/...` routes or use `model: \"provider/model\"` on the top-level API.\n\n## Prerequisites\n\n- Bun (>= 1.2.x)\n- Node.js if you plan to run the published CLI with `npx`\n- GitHub account with Copilot subscription only if you want to use the GitHub Copilot provider\n- An API key or OAuth login for at least one configured provider if you want to run without GitHub Copilot\n\n## Installation\n\nTo install dependencies, run:\n\n```sh\nbun install\n```\n\nTo start the server directly from source:\n\n```sh\nbun run start start\n```\n\n## Running from Source\n\nThe project can be run from source in several ways:\n\n### Development Mode\n\n```sh\nbun run dev start\n```\n\n### Production Mode\n\n```sh\nbun run start start\n```\n\n## Using with npx\n\nYou can run the project directly using npx:\n\n> [!IMPORTANT]\n> Token usage storage uses Node's built-in `node:sqlite` module when running with `npx`. It is enabled on Node.js >= 22.13.0. On Node.js < 22.13.0, the CLI still starts, but token usage storage is disabled.\n>\n> If you want token usage storage without upgrading Node.js, run the published CLI with Bun instead: `bunx --bun @jeffreycao/copilot-api@latest start`.\n\n```sh\nnpx @jeffreycao/copilot-api@latest start\n```\n\nWith options:\n\n```sh\nnpx @jeffreycao/copilot-api@latest start --port 8080\n```\n\nFor authentication or provider configuration only:\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth\n```\n\nTo run without GitHub Copilot, configure at least one provider first, then start the server normally:\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth login --provider dashscope\nnpx @jeffreycao/copilot-api@latest start\n```\n\n## Using with Docker\n\nBuild the image:\n\n```sh\ndocker build -t copilot-api .\n```\n\nRun the container with a bind mount so auth data survives restarts:\n\n```sh\nmkdir -p ./copilot-data\ndocker run -p 4141:4141 -v $(pwd)/copilot-data:/root/.local/share/copilot-api copilot-api\n```\n\nThis stores GitHub auth data, provider config, and other gateway state in `./copilot-data` on the host, mapped to `/root/.local/share/copilot-api` in the container.\n\nOr pass a GitHub token directly:\n\n```sh\ndocker run -p 4141:4141 -e GH_TOKEN=your_github_token_here copilot-api\n```\n\n## Electron Desktop App\n\nIf you prefer a GUI, this repository also includes an Electron desktop app in `desktop/`. It supports GitHub Copilot sign-in, OpenAI Codex OAuth, and API-key configuration for DeepSeek, DashScope, OpenRouter, or a custom provider. After authorization or provider configuration, it can start and stop the local proxy with one click and shows the local endpoint, auth header, available models, usage, and logs in the app.\n\nThe settings screen also exposes `OAuth App`, `API Home`, `Enterprise URL`, verbose logging, and minimize-to-tray. Desktop packages are published in GitHub Releases:\n\nhttps://github.com/caozhiyuan/copilot-api/releases\n\nDownload the installer for your platform, authorize or configure a provider inside the app, choose a port, start the server, then point your client at the local endpoint shown in the app. Packaged desktop builds use the bundled Electron runtime, so normal desktop usage does not require installing Node.js separately. Token usage history is enabled when that bundled runtime supports SQLite.\n\nThe desktop app's Advanced Config page reads and writes the shared model mappings through `GET/POST /admin/config/model-mappings`. The same mappings apply across `POST /v1/messages`, `POST /v1/messages/count_tokens`, `POST /v1/responses`, and `POST /v1/chat/completions` instead of being split per interface. It uses `auth.adminApiKey` instead of the regular `auth.apiKeys`, and the app reads that key directly from `config.json` after the server has generated it on startup.\n\n### Desktop App Screenshots\n\nMain dashboard, token usage breakdown in the bundled Electron app:\n\n<p align=\"center\">\n  <img src=\"./docs/screenshots/desktop-dashboard.png\" alt=\"Copilot API desktop app dashboard\" width=\"49%\" />\n  <img src=\"./docs/screenshots/desktop-token-usage.png\" alt=\"Copilot API desktop app token usage view\" width=\"49%\" />\n</p>\n\n## Using with Claude Code\n\nThis AI gateway can be used to power [Claude Code](https://docs.anthropic.com/en/claude-code), an experimental conversational AI assistant for developers from Anthropic.\n\nThere are two ways to configure Claude Code to use this AI gateway:\n\n### Interactive Setup with `--claude-code` flag\n\nTo get started, run the `start` command with the `--claude-code` flag:\n\n```sh\nnpx @jeffreycao/copilot-api@latest start --claude-code\n```\n\nYou will be prompted to select a primary model and a \"small, fast\" model for background tasks. After selecting the models, a command will be copied to your clipboard. This command sets the necessary environment variables for Claude Code to use the gateway.\n\nPaste and run this command in a new terminal to launch Claude Code.\n\n### Manual Configuration with `settings.json`\n\nAlternatively, you can configure Claude Code by creating a `.claude/settings.json` file in your project's root directory. This file should contain the environment variables needed by Claude Code. This way you don't need to run the interactive setup every time.\n\nHere is an example `.claude/settings.json` file:\n\n```json\n{\n  \"env\": {\n    \"ANTHROPIC_BASE_URL\": \"http://localhost:4141\",\n    \"ANTHROPIC_AUTH_TOKEN\": \"dummy\",\n    \"ANTHROPIC_MODEL\": \"deepseek/deepseek-v4-pro\",\n    \"ANTHROPIC_DEFAULT_SONNET_MODEL\": \"deepseek/deepseek-v4-pro\",\n    \"ANTHROPIC_DEFAULT_HAIKU_MODEL\": \"deepseek/deepseek-v4-flash\",\n    \"DISABLE_NON_ESSENTIAL_MODEL_CALLS\": \"1\",\n    \"CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC\": \"1\",\n    \"CLAUDE_CODE_ATTRIBUTION_HEADER\": \"0\",\n    \"CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION\": \"false\",\n    \"CLAUDE_CODE_DISABLE_TERMINAL_TITLE\": \"true\",\n    \"CLAUDE_CODE_ENABLE_AWAY_SUMMARY\": \"0\"\n  },\n  \"permissions\": {\n    \"deny\": [\n      \"mcp__ide__executeCode\"\n    ]\n  }\n}\n```\n\n- Replace `ANTHROPIC_MODEL`, `ANTHROPIC_DEFAULT_OPUS_MODEL`, `ANTHROPIC_DEFAULT_SONNET_MODEL`, and `ANTHROPIC_DEFAULT_HAIKU_MODEL` according to your needs. After configuration, please install the claude code plugin [Plugin Integrations](#plugin-integrations).  \n- Setting CLAUDE_CODE_ATTRIBUTION_HEADER to 0 can prevent Claude code from adding billing and version information in system prompts, thereby avoiding prompt cache invalidation.\n- Turning off CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION and CLAUDE_CODE_ENABLE_AWAY_SUMMARY can prevent quota from being consumed unnecessarily.\n- Claude Code WebSearch is supported for pure search requests. For Copilot, keep the global `messageApiWebSearchModel` set to a Responses-capable GPT model or a `provider/model` alias. For provider routes, use a native Anthropic provider or an `openai-responses` provider. Add `WebSearch` to `permissions.deny` only if you want to forbid this traffic.\n- If using a non-Claude model, do not enable ENABLE_TOOL_SEARCH. If using the Claude model, can enable ENABLE_TOOL_SEARCH. The current Claude Code uses the client tool search mode. In this mode, loading defer tools requires an additional request each time.\n- `CLAUDE_CODE_AUTO_COMPACT_WINDOW`: Set the context capacity in tokens used for auto-compaction calculations. Defaults to the model's context window: 200K for standard models or 1M for extended context models. Use a lower value like `500000` on a 1M model (e.g., `claude-opus-4-6[1m]`) to treat the window as 500K for compaction purposes. The value is capped at the model's actual context window. `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` is applied as a percentage of this value. Setting this variable decouples the compaction threshold from the status line's `used_percentage`, which always uses the model's full context window.\n\nYou can find more options here: [Claude Code settings](https://docs.anthropic.com/en/docs/claude-code/settings#environment-variables)\n\nYou can also read more about IDE integration here: [Add Claude Code to your IDE](https://docs.anthropic.com/en/docs/claude-code/ide-integrations)\n\n## Using with OpenCode\n\nOpenCode already has a direct GitHub Copilot provider. Use this section when you want OpenCode to point at this AI gateway through `@ai-sdk/anthropic` and reuse the agent behaviors described earlier in this README.\n\n### Minimal setup\n\nStart the AI gateway with the OpenCode OAuth app:\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth --oauth-app=opencode\nnpx @jeffreycao/copilot-api@latest start\n```\n\nThen point OpenCode at the gateway with `@ai-sdk/anthropic`.\n\nExample `~/.config/opencode/opencode.json`:\n\n```json\n{\n  \"$schema\": \"https://opencode.ai/config.json\",\n  \"provider\": {\n    \"local\": {\n      \"npm\": \"@ai-sdk/anthropic\",\n      \"name\": \"My Local\",\n      \"options\": {\n        \"baseURL\": \"http://localhost:4141/v1\",\n        \"apiKey\": \"dummy\"\n      },\n      \"models\": {\n        \"gpt-5.4\": {\n          \"name\": \"gpt-5.4\",\n          \"modalities\": {\n            \"input\": [\"text\", \"image\"],\n            \"output\": [\"text\"]\n          },\n          \"limit\": {\n            \"context\": 400000,\n            \"input\": 272000,\n            \"output\": 128000\n          }\n        },\n        \"claude-sonnet-4.6\": {\n          \"id\": \"claude-sonnet-4.6\",\n          \"name\": \"claude-sonnet-4.6\",\n          \"modalities\": {\n            \"input\": [\"text\", \"image\"],\n            \"output\": [\"text\"]\n          },          \n          \"limit\": {\n            \"context\": 200000,\n            \"output\": 32000\n          },\n          \"options\": {\n            \"thinking\": {\n              \"type\": \"adaptive\"\n            },\n            \"effort\": \"max\"\n          }\n        }\n      }\n    }\n  }\n}\n```\n\nWhy these fields matter:\n\n- `npm: \"@ai-sdk/anthropic\"` is the important part. OpenCode will speak Anthropic Messages semantics to this AI gateway instead of flattening everything into OpenAI Chat Completions.\n- `options.baseURL` should be `http://localhost:4141/v1`; the Anthropic SDK will append `/messages`, `/models`, and `/messages/count_tokens` automatically.\n- If you enable `auth.apiKeys` in this AI gateway, replace `dummy` with a real key. Otherwise any placeholder value is fine.\n\n## Using with Codex\n\nThis AI gateway can also power Codex.\n\n### Codex `config.toml` Reference\n\nAdd the following `[model_providers.copilot_api]` section to your Codex `~/.codex/config.toml`:\n\n```toml\nmodel_provider = \"copilot_api\"\nmodel_reasoning_summary = \"auto\"\nmodel_verbosity = \"medium\"\nmodel_context_window = 272000\nmodel_auto_compact_token_limit = 244800\n\n[model_providers.copilot_api]\nname = \"OpenAI\"\nbase_url = \"http://localhost:4141\"\nenv_key = \"GITHUB_COPILOT_API_KEY\"\nrequires_openai_auth = true\nsupports_websockets = false\nwire_api = \"responses\"\nrequest_max_retries = 3\nstream_max_retries = 1\nstream_idle_timeout_ms = 300000\n\n[features]\nremote_compaction_v2 = true\n\n[analytics]\nenabled = false\n```\n\n> [!NOTE]\n> This configuration is specific to Codex and the GitHub Copilot provider. `name` must be set to `\"OpenAI\"`. It can help mitigate Codex local compact cache miss issues. If you have enabled `useResponsesApiContextManagement` (Responses API context management compaction), `remote_compaction_v2` or local compact is generally not triggered, but it may still occur when tool results return a large number of tokens.\n\n## GPT Tool Search\n\nFor GPT Responses models such as `gpt-5.4+`, this AI gateway can expose Responses `tool_search` through a small MCP bridge. The same bridge can be used by Claude Code and opencode, as long as the client loads MCP servers and sends Anthropic Messages traffic through this gateway.\n\nDo not set Claude Code's native `ENABLE_TOOL_SEARCH` for GPT models. That flag enables Claude Code's own client-side tool search mode, and it may stop forwarding deferred tool definitions. This gateway needs the full tool definitions so it can keep the small always-loaded tool set eager and translate every other tool into Responses deferred namespaces.\n\nIf you install `tool-search@copilot-api-marketplace`, Claude Code receives this MCP bridge automatically and you can skip the manual Claude Code MCP setup below.\n\nAdd the tool search bridge to the MCP config used by Claude Code:\n\n```json\n{\n  \"mcpServers\": {\n    \"tool_search\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@jeffreycao/copilot-api@latest\", \"mcp\"]\n    }\n  }\n}\n```\n\nAdd the tool search bridge to the MCP config used by opencode:\n\n```json\n{\n  \"mcp\": {\n    \"tool_search\": {\n      \"type\": \"local\",\n      \"command\": [\"npx\", \"-y\", \"@jeffreycao/copilot-api@latest\", \"mcp\"]\n    }\n  }\n}\n```\n\nFor local development, use `bun` as the command and `[\"run\", \"./src/main.ts\", \"mcp\"]` as the args.\n\nInternally, the gateway now configures OpenAI Responses `tool_search` in client-executed mode. Deferred tools are still exposed as searchable namespaces, but the model is explicitly asked to return the exact deferred tool names it wants to load next.\n\nThe bridge uses direct tool selection, not query search. Its tool input is `names`, a comma-separated list of exact deferred tool names, for example `TaskList,TaskGet,mcp__fetch__fetch`.\n\n## Plugin Integrations\n\nPlugin integrations are available for Claude Code and opencode.\n\n#### Claude Code plugin integration (marketplace-based)\n\nThe Claude Code integration is packaged as two plugins:\n\n- `agent-inject` injects `__SUBAGENT_MARKER__...` on `SubagentStart`, so the gateway can infer `x-initiator: agent`.\n- `tool-search` registers the `tool_search` MCP bridge used for GPT Responses deferred tool loading.\n\n- Marketplace catalog in this repository: `.claude-plugin/marketplace.json`\n- Plugin sources in this repository: `plugin/claude/agent-inject`, `plugin/claude/tool-search`\n\nAdd the marketplace remotely:\n\n```sh\n/plugin marketplace add https://github.com/caozhiyuan/copilot-api.git\n```\n\nInstall the plugins from the marketplace:\n\n```sh\n/plugin install agent-inject@copilot-api-marketplace\n/plugin install tool-search@copilot-api-marketplace\n```\n\nAfter installation, `agent-inject` injects `__SUBAGENT_MARKER__...` on `SubagentStart`, and the gateway uses it to infer `x-initiator: agent`.\n\nThe `agent-inject` plugin also registers a `UserPromptSubmit` hook that returns `{\"continue\": true}`, and it can inject `SessionStart` reminder rules through environment variables:\n\n- `CLAUDE_PLUGIN_ENABLE_QUESTION_RULES=1` enables the two reminders about using the `question` tool automatically for Claude Code. Alternatively, you can add the same reminders manually in `CLAUDE.md`; see [CLAUDE.md or AGENTS.md Recommended Content](#claudemd-or-agentsmd-recommended-content).\n- `CLAUDE_PLUGIN_ENABLE_NO_BACKGROUND_AGENTS_RULE=1` enables the `run_in_background: true` avoidance reminder for agent hooks.\n\nThe `tool-search` plugin bundles the same MCP bridge described in [GPT Tool Search](#gpt-tool-search), so Claude Code users do not need to add the `tool_search` server manually when they install that plugin.\n\n#### Opencode plugin\n\nThe subagent marker producer is packaged as an opencode plugin located at `plugin/opencode/subagent-marker.js`.\n\n**Installation:**\n\nCopy the plugin file to your opencode plugins directory:\n\n```sh\n# Clone or download this repository, then copy the plugin\ncp plugin/opencode/subagent-marker.js ~/.config/opencode/plugins/\n```\n\nOr manually create the file at `~/.config/opencode/plugins/subagent-marker.js` with the plugin content.\n\n**Features:**\n\n- Tracks sub-sessions created by subagents\n- Automatically prepends a marker system reminder (`__SUBAGENT_MARKER__...`) to subagent chat messages\n- Sets `x-session-id` header for session tracking\n- Enables the gateway to infer `x-initiator: agent` for subagent-originated requests\n\nThe plugin hooks into `session.created`, `session.deleted`, `chat.message`, and `chat.headers` events to provide seamless subagent marker functionality.\n\n## Using the Usage Viewer\n\nAfter starting the server, a URL to the Copilot Usage Dashboard will be displayed in your console. This dashboard is a web interface for monitoring your API usage.\n\n1.  Start the server. For example, using npx:\n    ```sh\n    npx @jeffreycao/copilot-api@latest start\n    ```\n2.  The server will output a URL to the usage viewer. Copy and paste this URL into your browser. It will look something like this:\n    `http://localhost:4141/usage-viewer?endpoint=http://localhost:4141/usage`\n    - If you use the `start.bat` script on Windows, this page will open automatically.\n\nThe dashboard provides a user-friendly interface to view your Copilot usage data:\n\n> Token usage history requires Bun or Node.js >= 22.13.0. On Node.js < 22.13.0, the server runs normally but token usage storage is disabled.\n\n- **API Endpoint URL**: The dashboard is pre-configured to fetch data from your local server endpoint via a URL query parameter. You can manually switch this to any other compatible API endpoint.\n- **x-api-key Authentication**: If API Key authentication is enabled, you can provide the `x-api-key` request header. The key is persisted in the browser's local storage.\n- **Period Selector**: Choose from Day, Week, or Month time ranges. The URL query parameter updates automatically when you switch, making it easy to bookmark and share.\n- **Fetch Data**: Click the \"Refresh\" button to load or refresh the usage data. The dashboard also fetches data automatically on page load.\n- **Copilot Quotas**: View quota usage for services such as Chat and Completions via progress bars. Hover over a card to see used/remaining details.\n- **Token Usage Metric Cards**: See a summary of Total, Input, Output, Cache Read, Cache Write, Requests, and estimated cost for the current period.\n- **Trend Chart (Week / Month)**: An interactive line chart with model and metric filters. Click a data point to inspect the usage breakdown for a specific day.\n- **Model Breakdown Table**: A per-model summary of requests, input/output/cache tokens, and estimated cost for the selected period.\n- **Request Events (Paginated)**: A time-sorted list of request event records with pagination support, showing timestamps, models, request IDs, and token counts.\n- **Detailed Information**: See the full JSON response from the API for a detailed breakdown of all available usage statistics.\n- **URL-based Configuration**: You can also specify the API endpoint and period directly via `endpoint` and `period` query parameters. For example:\n  `http://localhost:4141/usage-viewer?endpoint=http://your-api-server/usage&period=week`\n\n### Usage Viewer Screenshot\n\n<p align=\"center\">\n  <img src=\"./docs/screenshots/usage-viewer.png\" alt=\"Copilot API usage viewer\" width=\"900\" />\n</p>\n\n## Command Structure\n\nCopilot API now uses a subcommand structure with these main commands:\n\n- `start`: Start the gateway server. If a GitHub token is available, the server starts with Copilot enabled. If no GitHub token is available, it starts in provider-only mode when at least one enabled provider exists; otherwise it guides you through provider setup.\n- `auth`: Run provider login or configuration without starting the server. Use it for GitHub Copilot login, Codex OAuth, or third-party provider API key setup.\n- `debug`: Display diagnostic information including version, runtime details, file paths, and authentication status. Useful for troubleshooting and support.\n\n## Command Line Options\n\n### Global Options\n\nThe following options can be used with any subcommand. When passing them before the subcommand, use the `--key=value` form:\n\n| Option            | Description                                            | Default | Alias |\n| ----------------- | ------------------------------------------------------ | ------- | ----- |\n| --api-home        | Path to the API home directory (sets COPILOT_API_HOME) | none    | none  |\n| --oauth-app       | OAuth app identifier (sets COPILOT_API_OAUTH_APP)      | none    | none  |\n| --enterprise-url  | Enterprise URL for GitHub (sets COPILOT_API_ENTERPRISE_URL) | none | none |\n\n### Start Command Options\n\nThe following command line options are available for the `start` command:\n\n| Option         | Description                                                                   | Default    | Alias |\n| -------------- | ----------------------------------------------------------------------------- | ---------- | ----- |\n| --port         | Port to listen on                                                             | 4141       | -p    |\n| --verbose      | Enable verbose logging                                                        | false      | -v    |\n| --github-token | Provide GitHub token directly (must be generated using the `auth` subcommand) | none       | -g    |\n| --claude-code  | Generate a command to launch Claude Code with Copilot API config              | false      | -c    |\n| --show-token   | Show GitHub and Copilot tokens on fetch and refresh                           | false      | none  |\n| --proxy-env    | Initialize proxy from environment variables                                   | false      | none  |\n\n### Auth Command Options\n\n| Option       | Description               | Default | Alias |\n| ------------ | ------------------------- | ------- | ----- |\n| --provider   | Provider to log in with or configure (`copilot`, `codex`, `opencode-go`, `deepseek`, `dashscope`, `openrouter`, or `custom`) | prompt | none |\n| --verbose    | Enable verbose logging    | false   | -v    |\n| --show-token | Show GitHub token on auth | false   | none  |\n\nUse `copilot-api auth login --provider copilot` only when you want to enable the GitHub Copilot provider. Copilot is not required for `codex` or third-party provider-only usage.\n\nUse `copilot-api auth login --provider deepseek`, `--provider dashscope`, `--provider openrouter`, or `--provider opencode-go` to add or update those common third-party providers from the CLI. DeepSeek prompts for masked `apiKey`, provider `type` (default `anthropic`), and `baseUrl` defaulting to `https://api.deepseek.com/anthropic`. DashScope prompts for masked `apiKey`, provider `type` (default `openai-compatible`), and prefilled `baseUrl`. OpenRouter prompts for masked `apiKey` and prefilled `baseUrl` only, and writes `type: \"anthropic\"`. OpenCode Go prompts for masked `apiKey` and prefilled `baseUrl` only, and writes `type: \"openai-compatible\"` (baseUrl `https://opencode.ai/zen/go`). After a provider is configured and enabled, `copilot-api start` can run without any GitHub token.\n\nUse `copilot-api auth login --provider custom` to add or update another third-party provider from the CLI. The command prompts for the provider name, supported type (`anthropic`, `openai-compatible`, or `openai-responses`), `baseUrl`, masked `apiKey`, and `authType`; `authType` may be left as the type default or set to `x-api-key` / `authorization`.\n\n### Debug Command Options\n\n| Option | Description               | Default | Alias |\n| ------ | ------------------------- | ------- | ----- |\n| --json | Output debug info as JSON | false   | none  |\n\n## Configuration (config.json)\n\n- **Location:** `~/.local/share/copilot-api/config.json` (Linux/macOS) or `%USERPROFILE%\\.local\\share\\copilot-api\\config.json` (Windows).\n- **Default shape:**\n  ```json\n  {\n    \"auth\": {\n      \"apiKeys\": [],\n      \"adminApiKey\": \"<auto-generated-on-startup>\"\n    },\n    \"providers\": {},\n    \"modelMappings\": {},\n    \"extraPrompts\": {\n      \"gpt-5-mini\": \"<built-in exploration prompt>\"\n    },\n    \"smallModel\": \"gpt-5-mini\",\n    \"useResponsesApiContextManagement\": true,\n    \"modelResponsesApiCompactThresholds\": {\n      \"gpt-5.4\": 217600,\n      \"gpt-5.5\": 217600\n    },\n    \"modelReasoningEfforts\": {\n      \"gpt-5-mini\": \"low\"\n    },\n    \"useMessagesApi\": true,\n    \"useResponsesApiWebSocket\": true,\n    \"useResponsesApiWebSearch\": true,\n    \"messageApiWebSearchModel\": \"gpt-5-mini\"\n  }\n  ```\n- **auth.apiKeys:** API keys used for request authentication on non-admin routes. Supports multiple keys for rotation. Requests can authenticate with either `x-api-key: <key>` or `Authorization: Bearer <key>`. If empty or omitted, authentication for non-admin routes is disabled.\n- **auth.adminApiKey:** Single admin key used only for `/admin/*` routes. If missing, the server generates a random key at startup and writes it back to `config.json`. Requests use the same `x-api-key` or `Authorization: Bearer` headers, but regular `auth.apiKeys` never grant access to `/admin/*`.\n- **modelMappings:** Exact `sourceModel -> targetModel` rewrites shared by top-level `POST /v1/messages`, `POST /v1/messages/count_tokens`, `POST /v1/responses`, and `POST /v1/chat/completions` requests. Omit it or leave it as `{}` to disable rewrites. Both the source and target must be non-empty strings. Targets can be regular model IDs or `provider/model` aliases such as `dashscope/qwen3.6-plus`, and the rewrite happens before provider alias parsing. These mappings are not split per interface. The admin endpoints `GET/POST /admin/config/model-mappings` read and update only this field.\n- **extraPrompts:** Map of `model -> prompt` appended to the first system prompt when translating Anthropic-style requests to Responses API. Use this to inject guardrails or guidance per model. Missing default entries are auto-added without overwriting your custom prompts. For GPT-5.3+ models (e.g. `gpt-5.3-codex`, `gpt-5.4`, `gpt-5.5`), a built-in commentary prompt is used as fallback when not explicitly configured. The built-in prompts enable phase-aware commentary, which lets the model emit a short user-facing progress update before tools or deeper reasoning.\n- **providers:** Global upstream provider map. Each provider key (for example `dashscope`) becomes a route prefix (`/dashscope/v1/messages`). Supports `type: \"anthropic\"`, `type: \"openai-compatible\"`, and `type: \"openai-responses\"`. Top-level clients can also use `model: \"dashscope/model-id\"` with `/v1/messages`, `/v1/messages/count_tokens`, `/v1/responses`, and `/v1/chat/completions`; the gateway strips the `dashscope/` prefix before forwarding upstream. `openai-compatible` providers support both chat and Messages flows: `/v1/chat/completions` is proxied to upstream `/v1/chat/completions`, while `/v1/messages` and `/:provider/v1/messages` are translated to upstream chat completions and translated back to Anthropic Messages responses. `GET /v1/models` aggregates enabled provider models with `provider/model-id` IDs; use `GET /dashscope/v1/models` for a single provider's raw model list.\n  - `enabled` defaults to `true` if omitted.\n  - `baseUrl` should be provider API base URL without the final endpoint. For Anthropic providers, omit `/v1/messages`; for OpenAI-compatible providers, omit `/v1/chat/completions`; for OpenAI Responses providers, omit `/v1/responses`.\n  - `apiKey` is used as the upstream credential value and is required for regular providers.\n  - `authType` (optional): Controls how `apiKey` is sent upstream. Supports `x-api-key` and `authorization` for regular providers. Anthropic providers default to `x-api-key`; OpenAI-compatible and OpenAI Responses providers default to `authorization`. When set to `authorization`, the proxy sends `Authorization: Bearer <apiKey>`. `oauth2` is reserved for the built-in `codex` provider and is written automatically by `auth login --provider codex`.\n  - `pricingCurrency` (optional): Provider-level currency used for token cost calculation, for example `USD` or `CNY`. Quick providers default to `CNY` for DashScope and DeepSeek, and `USD` for Codex/OpenRouter. Costs are grouped by currency and are not exchange-rate converted.\n  - `models` (optional): Per-model configuration map. Each key is a model ID (matching the model name in requests), and the value is:\n    - `temperature` (optional): Default temperature value used when the request does not specify one.\n    - `topP` (optional): Default top_p value used when the request does not specify one.\n    - `topK` (optional): Default top_k value used when the request does not specify one.\n    - `extraBody` (optional): Dynamic fields merged into the upstream request body for that model. Request body fields with the same name take precedence. OpenAI-compatible providers can use this for fields such as `enable_thinking`, `preserve_thinking`, `reasoning_effort`. `thinking_budget` is a special OpenAI-compatible provider override: when configured in `extraBody`, it is forced after Anthropic `thinking.budget_tokens` translation and overrides the request-derived budget. For providers whose name is `dashscope` or whose `baseUrl` contains `aliyuncs.com`, the request-derived `thinking_budget` (from Anthropic `thinking.budget_tokens`) is forwarded upstream; for other OpenAI-compatible providers the request-derived `thinking_budget` is stripped, while an `extraBody` `thinking_budget` is still honored. For DashScope providers, `preserve_thinking` defaults to `true` when not explicitly set in `extraBody` or the request body.\n    - `pricing` (optional): Per-model token prices, in the provider `pricingCurrency`, per 1M tokens. Supported fields are `input`, `output`, `cachedInput` (implicit cache read), `explicitCachedInput` (explicit cache read), and `cacheCreationInput`. Use `tiers` with `maxInputTokens` for input-size tiered pricing.\n    - `contextCache` (optional): Defaults to `true` for providers whose name is `dashscope` or whose `baseUrl` contains `aliyuncs.com`; defaults to `false` for other OpenAI-compatible providers. This enables Alibaba Cloud Model Studio/DashScope explicit context cache by injecting `cache_control: { \"type\": \"ephemeral\" }` on up to 4 content blocks using the Context Cache format. The cache breakpoint strategy matches opencode's main provider flow: the first 2 system messages plus the last 2 non-system messages. Marked string content is converted to text content part arrays for `system` / `user` / `assistant` / `tool` messages; existing array content is marked on the last part. Set this to `false` when the model already supports implicit caching, or when the upstream does not accept this explicit-cache extension field. Set this to `true` for non-DashScope providers that support the same explicit-cache extension. Applied on both `/v1/messages` and `/v1/chat/completions` routes.\n    - `supportPdf` (optional): Controls whether the model supports PDF/document content. Defaults to `false`; unsupported PDFs are converted to a text notice. Set it to `true` to send PDF/document blocks as OpenAI Chat Completions file parts.\n    - `toolContentSupportType` (optional): Tool result content capabilities for that model, as an array of `array`, `image`, and `pdf`. Provider routes default to string-only tool content when omitted. If `supportPdf` is `true` but this list does not include `pdf`, file parts in tool results are moved to user role messages. This provider default does not change the Copilot main flow, which continues to support array + image and not PDF.\n    - `type` (optional): Per-model override of the provider protocol type. Supports `anthropic`, `openai-compatible`, and `openai-responses`. When set, the provider's `/v1/messages` route uses this model's type instead of the provider-level type for request routing, auth header resolution, and upstream endpoint selection. This is useful for providers like OpenCode Go whose upstream supports both OpenAI-compatible and Anthropic Messages APIs for different models. When the type is overridden, the auth header is resolved from the overridden type's default (Anthropic defaults to `x-api-key`; OpenAI-compatible/Responses default to `authorization`).\n\n  Example DashScope model settings:\n  ```json\n  {\n    \"providers\": {\n      \"dashscope\": {\n        \"type\": \"openai-compatible\",\n        \"enabled\": true,\n        \"baseUrl\": \"https://dashscope.aliyuncs.com/compatible-mode\",\n        \"apiKey\": \"sk-your-dashscope-key\",\n        \"pricingCurrency\": \"CNY\",\n        \"models\": {\n          \"qwen3.7-plus\": {\n            \"temperature\": 1,\n            \"topP\": 0.95,\n            \"topK\": 20,\n            \"extraBody\": {\n              \"preserve_thinking\": true\n            }\n          },\n          \"glm-5.1\": {\n            \"temperature\": 0.7,\n            \"topP\": 0.95,\n            \"contextCache\": true,\n            \"pricing\": {\n              \"tiers\": [\n                {\n                  \"maxInputTokens\": 32000,\n                  \"input\": 6,\n                  \"cachedInput\": 1.2,\n                  \"explicitCachedInput\": 0.6,\n                  \"cacheCreationInput\": 7.5,\n                  \"output\": 24\n                },\n                {\n                  \"maxInputTokens\": 200000,\n                  \"input\": 8,\n                  \"cachedInput\": 1.6,\n                  \"explicitCachedInput\": 0.8,\n                  \"cacheCreationInput\": 10,\n                  \"output\": 28\n                }\n              ]\n            },\n            \"extraBody\": {\n              \"preserve_thinking\": true\n            }\n          }\n        }\n      }\n    }\n  }\n  ```\n  Built-in token prices cover Codex GPT models in USD, DashScope `qwen3.7-max`, `qwen3.7-plus`, `glm-5.1`, `glm-5.2` in CNY, DeepSeek `deepseek-v4-flash`, `deepseek-v4-pro`, `deepseek-chat`, `deepseek-reasoner` in CNY, and OpenCode Go models (`glm-5.2`, `deepseek-v4-flash`, `deepseek-v4-pro`, `kimi-k2.7-code`, `mimo-v2.5`, `mimo-v2.5-pro`, `qwen3.7-plus`, `qwen3.7-max`, `minimax-m2.5`, `minimax-m3`) in USD. User `pricing` entries override built-ins. For DashScope, cached tokens are charged as explicit cache reads when the upstream usage includes `cache_creation_input_tokens`; otherwise `cachedInput` is used as the implicit cache read price. For DeepSeek, `prompt_cache_hit_tokens` map to cached input and `prompt_cache_miss_tokens` map to regular input.\n- **smallModel:** Fallback model used for tool-less warmup messages (e.g., Claude Code probe requests); defaults to gpt-5-mini.\n- **useResponsesApiContextManagement:** When `true`, the proxy adds Responses API `context_management` compaction instructions. Defaults to `true`. Set it to `false` to disable this globally. When enabled, the request includes `context_management` in the body and keeps only the latest compaction carrier on follow-up turns. This is especially useful for long-running tasks.\n- **modelResponsesApiCompactThresholds:** Per-model Responses API `compact_threshold` overrides used when the proxy adds `context_management`. These values take precedence over the fallback threshold from `resolveResponsesCompactThreshold` (`max_prompt_tokens * ratio`, or the default fallback). Defaults set `gpt-5.4` and `gpt-5.5` to `217600` (`272000 * 0.8`). Models not listed continue to use the normal fallback logic.\n- **modelReasoningEfforts:** Per-model reasoning effort applied to `/v1/messages` requests. When routed to the Copilot native Messages API it sets `output_config.effort`; when translated to the Responses API it sets `reasoning.effort`. Allowed values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. If a model isn't listed, `high` is used by default; GPT-5.3+ models fall back to `xhigh` when not explicitly configured.\n- **useMessagesApi:** When `true`, Claude-family models that support Copilot's native `/v1/messages` endpoint will use the Messages API; otherwise they fall back to `/chat/completions`. Set to `false` to disable Messages API routing and always use `/chat/completions`. Defaults to `true`.\n- **useResponsesApiWebSocket:** When `true`, Responses API requests use Copilot's websocket transport for models that advertise `ws:/responses`; models that only advertise `/responses` continue to use HTTP. Set to `false` to disable websocket routing and use HTTP `/responses` whenever the selected model supports it. Defaults to `true`.\n- **useResponsesApiWebSearch:** When `true`, the server keeps Responses API tools with `type: \"web_search\"` and forwards them upstream. Set to `false` to strip those tools from `/responses` payloads. Defaults to `true`.\n- **messageApiWebSearchModel:** Global fallback model used when a top-level Copilot `/v1/messages` request contains only the server-side `web_search` tool. Defaults to `gpt-5-mini`. If the value is a `provider/model` alias, the request is routed into that provider's Messages API path with the provider prefix stripped. For Copilot GPT models, web search runs through `/responses`. Mixed `web_search` plus custom tools are not supported and the server-side `web_search` tool is stripped.\n- **claudeTokenMultiplier:** Multiplier applied to the fallback GPT-tokenizer estimate for Claude `/v1/messages/count_tokens` requests. Defaults to `1.15`. Increase it if your client is still compacting too late. This setting is only used when the proxy is estimating Claude tokens locally; if `anthropicApiKey` is configured and Anthropic token counting succeeds, the exact Anthropic count is returned instead.\n- **anthropicApiKey:** Anthropic API key used to forward Claude `/v1/messages/count_tokens` requests to Anthropic's real token counting endpoint, which returns exact counts instead of GPT tokenizer estimates. Can also be set via the `ANTHROPIC_API_KEY` environment variable. If not set, or if the upstream call fails, token counting falls back to local GPT tokenizer estimation controlled by `claudeTokenMultiplier`.\n\nEdit this file to customize prompts or swap in your own fast model. Restart the server (or rerun the command) after changes so the cached config is refreshed.\n\n## API Authentication\n\n- **Protected non-admin routes:** All routes except `/`, `/usage-viewer`, and `/usage-viewer/` require authentication when `auth.apiKeys` is configured and non-empty.\n- **Admin routes:** All `/admin/*` routes require `auth.adminApiKey`. If it is missing, the server generates one at startup and persists it to `config.json` before serving requests.\n- **Allowed auth headers:**\n  - `x-api-key: <your_key>`\n  - `Authorization: Bearer <your_key>`\n- **CORS preflight:** `OPTIONS` requests are always allowed.\n- **When no regular keys are configured:** Non-admin routes continue to allow requests. This does not apply to `/admin/*`, which only accepts `auth.adminApiKey`.\n\nExample request for a regular protected route:\n\n```sh\ncurl http://localhost:4141/v1/models \\\n  -H \"x-api-key: your_api_key\"\n```\n\nExample request for an admin route:\n\n```sh\ncurl http://localhost:4141/admin/config/model-mappings \\\n  -H \"x-api-key: your_admin_api_key\"\n```\n\n## API Endpoints\n\nThe server exposes several OpenAI- and Anthropic-compatible endpoints. Requests can target GitHub Copilot, the built-in `codex` provider, or configured providers depending on the selected model and `provider/model` alias.\n\n### OpenAI Compatible Endpoints\n\nThese endpoints mimic the OpenAI API structure.\n\n| Endpoint                    | Method | Description                                                      |\n| --------------------------- | ------ | ---------------------------------------------------------------- |\n| `POST /v1/responses`        | `POST` | OpenAI Most advanced interface for generating model responses. Supports `provider/model` aliases for `openai-responses` providers. |\n| `POST /v1/chat/completions` | `POST` | Creates a model response for the given chat conversation. Supports `provider/model` aliases for `openai-compatible` providers and can be used without Copilot when the target provider is configured. |\n| `GET /v1/models`            | `GET`  | Lists Copilot models plus enabled provider models using `provider/model-id` IDs. |\n| `POST /v1/embeddings`       | `POST` | Creates an embedding vector representing the input text.         |\n\n### Anthropic Compatible Endpoints\n\nThese endpoints are designed to be compatible with the Anthropic Messages API.\n\n| Endpoint                         | Method | Description                                                  |\n| -------------------------------- | ------ | ------------------------------------------------------------ |\n| `POST /v1/messages`              | `POST` | Creates a model response for a given conversation. Supports `provider/model` aliases for configured providers, including translation through `openai-compatible` providers. |\n| `POST /v1/messages/count_tokens` | `POST` | Calculates the number of tokens for a given set of messages. Supports `provider/model` aliases for configured providers. |\n| `POST /:provider/v1/messages`       | `POST` | Proxies Anthropic Messages requests to the configured Anthropic provider, translates them through an OpenAI-compatible provider, or translates them through an OpenAI Responses provider. |\n| `GET /:provider/v1/models`          | `GET`  | Proxies model listing requests to the configured provider.   |\n| `POST /:provider/v1/messages/count_tokens` | `POST` | Calculates tokens locally for provider route requests. |\n\n### Usage Monitoring Endpoints\n\nNew endpoints for monitoring your Copilot usage and quotas.\n\n| Endpoint     | Method | Description                                                  |\n| ------------ | ------ | ------------------------------------------------------------ |\n| `GET /usage` | `GET`  | Get detailed Copilot usage statistics and quota information. |\n| `GET /token` | `GET`  | Get the current Copilot token being used by the API.         |\n\n### Admin / Configuration Endpoints\n\nThese endpoints are reserved for local administrative actions and only accept `auth.adminApiKey`.\n\n| Endpoint                              | Method | Description                                                                 |\n| ------------------------------------- | ------ | --------------------------------------------------------------------------- |\n| `GET /admin/config/model-mappings`    | `GET`  | Returns the current `config.json` path and the active `modelMappings` map.  |\n| `POST /admin/config/model-mappings`   | `POST` | Updates only the `modelMappings` field in `config.json` and returns it back. |\n\n## Example Usage\n\nCommon `npx` commands:\n\n```sh\n# Start the gateway\nnpx @jeffreycao/copilot-api@latest start\n\n# Start on a custom port with verbose logging\nnpx @jeffreycao/copilot-api@latest start --port 8080 --verbose\n\n# Run the auth flow\nnpx @jeffreycao/copilot-api@latest auth login\n\n# Configure a third-party provider, then run without GitHub Copilot\nnpx @jeffreycao/copilot-api@latest auth login --provider dashscope\nnpx @jeffreycao/copilot-api@latest start\n\n# Print debug information as JSON\nnpx @jeffreycao/copilot-api@latest debug --json\n\n# Run the published CLI with Bun instead of Node.js\nbunx --bun @jeffreycao/copilot-api@latest start\n```\n\nOpenAI-compatible provider examples after configuring `dashscope`:\n\n```sh\ncurl http://localhost:4141/v1/chat/completions \\\n  -H \"content-type: application/json\" \\\n  -d '{\"model\":\"dashscope/qwen3.6-plus\",\"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]}'\n\ncurl http://localhost:4141/dashscope/v1/messages \\\n  -H \"content-type: application/json\" \\\n  -d '{\"model\":\"qwen3.6-plus\",\"max_tokens\":1024,\"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]}'\n```\n\n## Usage Tips\n\n### CLAUDE.md or AGENTS.md Recommended Content\n\nTo add these reminders manually, include the following in `CLAUDE.md` for Claude Code, or `AGENTS.md` for opencode/codex:\n\n```\n- Prohibited from directly asking questions to users, MUST use question tool.\n- Once you can confirm that the task is complete, MUST use question tool to make user confirm. The user may respond with feedback if they are not satisfied with the result, which you can use to make improvements and try again, after try again, MUST use question tool to make user confirm again.\n```\n"}, "b90e221b27c3715d1f8e023f2ff889c49f0a8498": {"t": 1785765567.74219, "n": 46325, "h": "2c63b65768e29d89", "c": "# Copilot API Proxy\n\nEnglish | [简体中文](./README.zh-CN.md)\n\n## Important Notes\n\n> [!IMPORTANT]\n> **Before using, please be aware of the following:**\n>\n> 1. **Claude Code configuration:** When using with Claude Code, please configure the model ID as `claude-opus-4-8`. Example claude `settings.json` see [Manual Configuration with `settings.json`](#manual-configuration-with-settingsjson). \n>\n> 2. **Built-in `copilot`, `codex` and third-party providers:** Run `npx @jeffreycao/copilot-api@latest auth` and choose `copilot`, `codex`, `deepseek`, `custom`, or other providers.\n>\n> 3. **Note:** See [GitHub Copilot Security Notice](./NOTICE.md#github-copilot-security-notice) for the warning removed from the README header.\n\n---\n\n## Project Overview\n\nA small AI gateway that can use GitHub Copilot, the built-in `codex` provider, or configured third-party providers such as DashScope. GitHub Copilot is optional: if no GitHub token is available, the server can still start in provider-only mode as long as at least one enabled provider is configured.\n\nThe gateway exposes OpenAI- and Anthropic-compatible APIs from one local endpoint, so tools like [Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview), OpenCode, Codex, and OpenAI-compatible clients can share the same local server.\n\nOn the GitHub Copilot path, the gateway prefers Copilot's native Anthropic-style Messages API when available, preserving more Claude-native behavior for tool-heavy workflows.\n\n## Features\n\n- **OpenAI and Anthropic compatibility**: Serve `/v1/responses`, `/v1/chat/completions`, `/v1/models`, `/v1/embeddings`, and `/v1/messages` from one local gateway.\n- **Copilot is optional**: Use GitHub Copilot when credentials are present, or run the server with only configured providers.\n- **One gateway for Copilot, `codex`, and external providers**: Route GitHub Copilot, the built-in `codex` provider, and configured third-party providers behind the same endpoint.\n- **Standalone third-party providers**: Configure providers such as DashScope, DeepSeek, OpenRouter, or a custom provider and start the gateway without a GitHub Copilot login.\n- **OpenAI-compatible providers on chat and Messages APIs**: `openai-compatible` providers can serve top-level `/v1/chat/completions` through `model: \"provider/model\"` and Anthropic-style `/v1/messages` through request/response translation.\n- **Agent-friendly Claude handling on Copilot**: Prefer native `/v1/messages` when available, preserve Claude-style tool flows, support Anthropic beta features, Claude WebSearch through Responses-capable models, and keep subagent/session markers intact.\n- **Claude Code and OpenCode integration**: Works with Claude Code and OpenCode, including direct Anthropic-compatible usage through `@ai-sdk/anthropic`.\n- **Flexible auth and deployment options**: Supports interactive login or direct tokens, individual/business/enterprise plans, GitHub Enterprise, opencode OAuth, and custom data directories.\n- **Multi-provider routing**: Expose provider-specific `/:provider/...` routes or use `model: \"provider/model\"` on the top-level API.\n\n## Prerequisites\n\n- Bun (>= 1.2.x)\n- Node.js if you plan to run the published CLI with `npx`\n- GitHub account with Copilot subscription only if you want to use the GitHub Copilot provider\n- An API key or OAuth login for at least one configured provider if you want to run without GitHub Copilot\n\n## Installation\n\nTo install dependencies, run:\n\n```sh\nbun install\n```\n\nTo start the server directly from source:\n\n```sh\nbun run start start\n```\n\n## Running from Source\n\nThe project can be run from source in several ways:\n\n### Development Mode\n\n```sh\nbun run dev start\n```\n\n### Production Mode\n\n```sh\nbun run start start\n```\n\n## Using with npx\n\nYou can run the project directly using npx:\n\n> [!IMPORTANT]\n> Token usage storage uses Node's built-in `node:sqlite` module when running with `npx`. It is enabled on Node.js >= 22.13.0. On Node.js < 22.13.0, the CLI still starts, but token usage storage is disabled.\n>\n> If you want token usage storage without upgrading Node.js, run the published CLI with Bun instead: `bunx --bun @jeffreycao/copilot-api@latest start`.\n\n```sh\nnpx @jeffreycao/copilot-api@latest start\n```\n\nWith options:\n\n```sh\nnpx @jeffreycao/copilot-api@latest start --port 8080\n```\n\nFor authentication or provider configuration only:\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth\n```\n\nTo run without GitHub Copilot, configure at least one provider first, then start the server normally:\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth login --provider dashscope\nnpx @jeffreycao/copilot-api@latest start\n```\n\n## Using with Docker\n\nBuild the image:\n\n```sh\ndocker build -t copilot-api .\n```\n\nRun the container with a bind mount so auth data survives restarts:\n\n```sh\nmkdir -p ./copilot-data\ndocker run -p 4141:4141 -v $(pwd)/copilot-data:/root/.local/share/copilot-api copilot-api\n```\n\nThis stores GitHub auth data, provider config, and other gateway state in `./copilot-data` on the host, mapped to `/root/.local/share/copilot-api` in the container.\n\nOr pass a GitHub token directly:\n\n```sh\ndocker run -p 4141:4141 -e GH_TOKEN=your_github_token_here copilot-api\n```\n\n## Electron Desktop App\n\nIf you prefer a GUI, this repository also includes an Electron desktop app in `desktop/`. It supports GitHub Copilot sign-in, OpenAI Codex OAuth, and API-key configuration for DeepSeek, DashScope, OpenRouter, or a custom provider. After authorization or provider configuration, it can start and stop the local proxy with one click and shows the local endpoint, auth header, available models, usage, and logs in the app.\n\nThe settings screen also exposes `OAuth App`, `API Home`, `Enterprise URL`, verbose logging, and minimize-to-tray. Desktop packages are published in GitHub Releases:\n\nhttps://github.com/caozhiyuan/copilot-api/releases\n\nDownload the installer for your platform, authorize or configure a provider inside the app, choose a port, start the server, then point your client at the local endpoint shown in the app. Packaged desktop builds use the bundled Electron runtime, so normal desktop usage does not require installing Node.js separately. Token usage history is enabled when that bundled runtime supports SQLite.\n\nThe desktop app's Advanced Config page reads and writes the shared model mappings through `GET/POST /admin/config/model-mappings`. The same mappings apply across `POST /v1/messages`, `POST /v1/messages/count_tokens`, `POST /v1/responses`, and `POST /v1/chat/completions` instead of being split per interface. It uses `auth.adminApiKey` instead of the regular `auth.apiKeys`, and the app reads that key directly from `config.json` after the server has generated it on startup.\n\n### Desktop App Screenshots\n\nMain dashboard, token usage breakdown in the bundled Electron app:\n\n<p align=\"center\">\n  <img src=\"./docs/screenshots/desktop-dashboard.png\" alt=\"Copilot API desktop app dashboard\" width=\"49%\" />\n  <img src=\"./docs/screenshots/desktop-token-usage.png\" alt=\"Copilot API desktop app token usage view\" width=\"49%\" />\n</p>\n\n## Using with Claude Code\n\nThis AI gateway can be used to power [Claude Code](https://docs.anthropic.com/en/claude-code), an experimental conversational AI assistant for developers from Anthropic.\n\nThere are two ways to configure Claude Code to use this AI gateway:\n\n### Interactive Setup with `--claude-code` flag\n\nTo get started, run the `start` command with the `--claude-code` flag:\n\n```sh\nnpx @jeffreycao/copilot-api@latest start --claude-code\n```\n\nYou will be prompted to select a primary model and a \"small, fast\" model for background tasks. After selecting the models, a command will be copied to your clipboard. This command sets the necessary environment variables for Claude Code to use the gateway.\n\nPaste and run this command in a new terminal to launch Claude Code.\n\n### Manual Configuration with `settings.json`\n\nAlternatively, you can configure Claude Code by creating a `.claude/settings.json` file in your project's root directory. This file should contain the environment variables needed by Claude Code. This way you don't need to run the interactive setup every time.\n\nHere is an example `.claude/settings.json` file:\n\n```json\n{\n  \"env\": {\n    \"ANTHROPIC_BASE_URL\": \"http://localhost:4141\",\n    \"ANTHROPIC_AUTH_TOKEN\": \"dummy\",\n    \"ANTHROPIC_MODEL\": \"deepseek/deepseek-v4-pro\",\n    \"ANTHROPIC_DEFAULT_SONNET_MODEL\": \"deepseek/deepseek-v4-pro\",\n    \"ANTHROPIC_DEFAULT_HAIKU_MODEL\": \"deepseek/deepseek-v4-flash\",\n    \"DISABLE_NON_ESSENTIAL_MODEL_CALLS\": \"1\",\n    \"CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC\": \"1\",\n    \"CLAUDE_CODE_ATTRIBUTION_HEADER\": \"0\",\n    \"CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION\": \"false\",\n    \"CLAUDE_CODE_DISABLE_TERMINAL_TITLE\": \"true\",\n    \"CLAUDE_CODE_ENABLE_AWAY_SUMMARY\": \"0\"\n  },\n  \"permissions\": {\n    \"deny\": [\n      \"mcp__ide__executeCode\"\n    ]\n  }\n}\n```\n\n- Replace `ANTHROPIC_MODEL`, `ANTHROPIC_DEFAULT_OPUS_MODEL`, `ANTHROPIC_DEFAULT_SONNET_MODEL`, and `ANTHROPIC_DEFAULT_HAIKU_MODEL` according to your needs. After configuration, please install the claude code plugin [Plugin Integrations](#plugin-integrations).  \n- Setting CLAUDE_CODE_ATTRIBUTION_HEADER to 0 can prevent Claude code from adding billing and version information in system prompts, thereby avoiding prompt cache invalidation.\n- Turning off CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION and CLAUDE_CODE_ENABLE_AWAY_SUMMARY can prevent quota from being consumed unnecessarily.\n- Claude Code WebSearch is supported for pure search requests. For Copilot, keep the global `messageApiWebSearchModel` set to a Responses-capable GPT model or a `provider/model` alias. For provider routes, use a native Anthropic provider or an `openai-responses` provider. Add `WebSearch` to `permissions.deny` only if you want to forbid this traffic.\n- If using a non-Claude model, do not enable ENABLE_TOOL_SEARCH. If using the Claude model, can enable ENABLE_TOOL_SEARCH. The current Claude Code uses the client tool search mode. In this mode, loading defer tools requires an additional request each time.\n- `CLAUDE_CODE_AUTO_COMPACT_WINDOW`: Set the context capacity in tokens used for auto-compaction calculations. Defaults to the model's context window: 200K for standard models or 1M for extended context models. Use a lower value like `500000` on a 1M model (e.g., `claude-opus-4-6[1m]`) to treat the window as 500K for compaction purposes. The value is capped at the model's actual context window. `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` is applied as a percentage of this value. Setting this variable decouples the compaction threshold from the status line's `used_percentage`, which always uses the model's full context window.\n\nYou can find more options here: [Claude Code settings](https://docs.anthropic.com/en/docs/claude-code/settings#environment-variables)\n\nYou can also read more about IDE integration here: [Add Claude Code to your IDE](https://docs.anthropic.com/en/docs/claude-code/ide-integrations)\n\n## Using with OpenCode\n\nOpenCode already has a direct GitHub Copilot provider. Use this section when you want OpenCode to point at this AI gateway through `@ai-sdk/anthropic` and reuse the agent behaviors described earlier in this README.\n\n### Minimal setup\n\nStart the AI gateway with the OpenCode OAuth app:\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth --oauth-app=opencode\nnpx @jeffreycao/copilot-api@latest start\n```\n\nThen point OpenCode at the gateway with `@ai-sdk/anthropic`.\n\nExample `~/.config/opencode/opencode.json`:\n\n```json\n{\n  \"$schema\": \"https://opencode.ai/config.json\",\n  \"provider\": {\n    \"local\": {\n      \"npm\": \"@ai-sdk/anthropic\",\n      \"name\": \"My Local\",\n      \"options\": {\n        \"baseURL\": \"http://localhost:4141/v1\",\n        \"apiKey\": \"dummy\"\n      },\n      \"models\": {\n        \"gpt-5.4\": {\n          \"name\": \"gpt-5.4\",\n          \"modalities\": {\n            \"input\": [\"text\", \"image\"],\n            \"output\": [\"text\"]\n          },\n          \"limit\": {\n            \"context\": 300000,\n            \"output\": 128000\n          }\n        },\n        \"claude-sonnet-4.6\": {\n          \"id\": \"claude-sonnet-4.6\",\n          \"name\": \"claude-sonnet-4.6\",\n          \"modalities\": {\n            \"input\": [\"text\", \"image\"],\n            \"output\": [\"text\"]\n          },          \n          \"limit\": {\n            \"context\": 200000,\n            \"output\": 32000\n          },\n          \"options\": {\n            \"thinking\": {\n              \"type\": \"adaptive\"\n            },\n            \"effort\": \"max\"\n          }\n        }\n      }\n    }\n  }\n}\n```\n\nWhy these fields matter:\n\n- `npm: \"@ai-sdk/anthropic\"` is the important part. OpenCode will speak Anthropic Messages semantics to this AI gateway instead of flattening everything into OpenAI Chat Completions.\n- `options.baseURL` should be `http://localhost:4141/v1`; the Anthropic SDK will append `/messages`, `/models`, and `/messages/count_tokens` automatically.\n- If you enable `auth.apiKeys` in this AI gateway, replace `dummy` with a real key. Otherwise any placeholder value is fine.\n\n## Using with Codex\n\nThis AI gateway can also power Codex.\n\n### Codex `config.toml` Reference\n\nAdd the following `[model_providers.copilot_api]` section to your Codex `~/.codex/config.toml`:\n\n```toml\nmodel_provider = \"copilot_api\"\nmodel_reasoning_summary = \"auto\"\nmodel_verbosity = \"medium\"\nmodel_context_window = 272000\nmodel_auto_compact_token_limit = 244800\n\n[model_providers.copilot_api]\nname = \"OpenAI\"\nbase_url = \"http://localhost:4141\"\nenv_key = \"GITHUB_COPILOT_API_KEY\"\nrequires_openai_auth = true\nsupports_websockets = false\nwire_api = \"responses\"\nrequest_max_retries = 3\nstream_max_retries = 1\nstream_idle_timeout_ms = 300000\n\n[features]\nremote_compaction_v2 = true\n\n[analytics]\nenabled = false\n```\n\n> [!NOTE]\n> This configuration is specific to Codex and the GitHub Copilot provider. `name` must be set to `\"OpenAI\"`. It can help mitigate Codex local compact cache miss issues. If you have enabled `useResponsesApiContextManagement` (Responses API context management compaction), `remote_compaction_v2` or local compact is generally not triggered, but it may still occur when tool results return a large number of tokens.\n\n## GPT Tool Search\n\nFor GPT Responses models such as `gpt-5.4+`, this AI gateway can expose Responses `tool_search` through a small MCP bridge. The same bridge can be used by Claude Code and opencode, as long as the client loads MCP servers and sends Anthropic Messages traffic through this gateway.\n\nDo not set Claude Code's native `ENABLE_TOOL_SEARCH` for GPT models. That flag enables Claude Code's own client-side tool search mode, and it may stop forwarding deferred tool definitions. This gateway needs the full tool definitions so it can keep the small always-loaded tool set eager and translate every other tool into Responses deferred namespaces.\n\nIf you install `tool-search@copilot-api-marketplace`, Claude Code receives this MCP bridge automatically and you can skip the manual Claude Code MCP setup below.\n\nAdd the tool search bridge to the MCP config used by Claude Code:\n\n```json\n{\n  \"mcpServers\": {\n    \"tool_search\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@jeffreycao/copilot-api@latest\", \"mcp\"]\n    }\n  }\n}\n```\n\nAdd the tool search bridge to the MCP config used by opencode:\n\n```json\n{\n  \"mcp\": {\n    \"tool_search\": {\n      \"type\": \"local\",\n      \"command\": [\"npx\", \"-y\", \"@jeffreycao/copilot-api@latest\", \"mcp\"]\n    }\n  }\n}\n```\n\nFor local development, use `bun` as the command and `[\"run\", \"./src/main.ts\", \"mcp\"]` as the args.\n\nInternally, the gateway now configures OpenAI Responses `tool_search` in client-executed mode. Deferred tools are still exposed as searchable namespaces, but the model is explicitly asked to return the exact deferred tool names it wants to load next.\n\nThe bridge uses direct tool selection, not query search. Its tool input is `names`, a comma-separated list of exact deferred tool names, for example `TaskList,TaskGet,mcp__fetch__fetch`.\n\n## Plugin Integrations\n\nPlugin integrations are available for Claude Code and opencode.\n\n#### Claude Code plugin integration (marketplace-based)\n\nThe Claude Code integration is packaged as two plugins:\n\n- `agent-inject` injects `__SUBAGENT_MARKER__...` on `SubagentStart`, so the gateway can infer `x-initiator: agent`.\n- `tool-search` registers the `tool_search` MCP bridge used for GPT Responses deferred tool loading.\n\n- Marketplace catalog in this repository: `.claude-plugin/marketplace.json`\n- Plugin sources in this repository: `plugin/claude/agent-inject`, `plugin/claude/tool-search`\n\nAdd the marketplace remotely:\n\n```sh\n/plugin marketplace add https://github.com/caozhiyuan/copilot-api.git\n```\n\nInstall the plugins from the marketplace:\n\n```sh\n/plugin install agent-inject@copilot-api-marketplace\n/plugin install tool-search@copilot-api-marketplace\n```\n\nAfter installation, `agent-inject` injects `__SUBAGENT_MARKER__...` on `SubagentStart`, and the gateway uses it to infer `x-initiator: agent`.\n\nThe `agent-inject` plugin also registers a `UserPromptSubmit` hook that returns `{\"continue\": true}`, and it can inject `SessionStart` reminder rules through environment variables:\n\n- `CLAUDE_PLUGIN_ENABLE_QUESTION_RULES=1` enables the two reminders about using the `question` tool automatically for Claude Code. Alternatively, you can add the same reminders manually in `CLAUDE.md`; see [CLAUDE.md or AGENTS.md Recommended Content](#claudemd-or-agentsmd-recommended-content).\n- `CLAUDE_PLUGIN_ENABLE_NO_BACKGROUND_AGENTS_RULE=1` enables the `run_in_background: true` avoidance reminder for agent hooks.\n\nThe `tool-search` plugin bundles the same MCP bridge described in [GPT Tool Search](#gpt-tool-search), so Claude Code users do not need to add the `tool_search` server manually when they install that plugin.\n\n#### Opencode plugin\n\nThe subagent marker producer is packaged as an opencode plugin located at `plugin/opencode/subagent-marker.js`.\n\n**Installation:**\n\nCopy the plugin file to your opencode plugins directory:\n\n```sh\n# Clone or download this repository, then copy the plugin\ncp plugin/opencode/subagent-marker.js ~/.config/opencode/plugins/\n```\n\nOr manually create the file at `~/.config/opencode/plugins/subagent-marker.js` with the plugin content.\n\n**Features:**\n\n- Tracks sub-sessions created by subagents\n- Automatically prepends a marker system reminder (`__SUBAGENT_MARKER__...`) to subagent chat messages\n- Sets `x-session-id` header for session tracking\n- Enables the gateway to infer `x-initiator: agent` for subagent-originated requests\n\nThe plugin hooks into `session.created`, `session.deleted`, `chat.message`, and `chat.headers` events to provide seamless subagent marker functionality.\n\n## Using the Usage Viewer\n\nAfter starting the server, a URL to the Copilot Usage Dashboard will be displayed in your console. This dashboard is a web interface for monitoring your API usage.\n\n1.  Start the server. For example, using npx:\n    ```sh\n    npx @jeffreycao/copilot-api@latest start\n    ```\n2.  The server will output a URL to the usage viewer. Copy and paste this URL into your browser. It will look something like this:\n    `http://localhost:4141/usage-viewer?endpoint=http://localhost:4141/usage`\n    - If you use the `start.bat` script on Windows, this page will open automatically.\n\nThe dashboard provides a user-friendly interface to view your Copilot usage data:\n\n> Token usage history requires Bun or Node.js >= 22.13.0. On Node.js < 22.13.0, the server runs normally but token usage storage is disabled.\n\n- **API Endpoint URL**: The dashboard is pre-configured to fetch data from your local server endpoint via a URL query parameter. You can manually switch this to any other compatible API endpoint.\n- **x-api-key Authentication**: If API Key authentication is enabled, you can provide the `x-api-key` request header. The key is persisted in the browser's local storage.\n- **Period Selector**: Choose from Day, Week, or Month time ranges. The URL query parameter updates automatically when you switch, making it easy to bookmark and share.\n- **Fetch Data**: Click the \"Refresh\" button to load or refresh the usage data. The dashboard also fetches data automatically on page load.\n- **Copilot Quotas**: View quota usage for services such as Chat and Completions via progress bars. Hover over a card to see used/remaining details.\n- **Token Usage Metric Cards**: See a summary of Total, Input, Output, Cache Read, Cache Write, Requests, and estimated cost for the current period.\n- **Trend Chart (Week / Month)**: An interactive line chart with model and metric filters. Click a data point to inspect the usage breakdown for a specific day.\n- **Model Breakdown Table**: A per-model summary of requests, input/output/cache tokens, and estimated cost for the selected period.\n- **Request Events (Paginated)**: A time-sorted list of request event records with pagination support, showing timestamps, models, request IDs, and token counts.\n- **Detailed Information**: See the full JSON response from the API for a detailed breakdown of all available usage statistics.\n- **URL-based Configuration**: You can also specify the API endpoint and period directly via `endpoint` and `period` query parameters. For example:\n  `http://localhost:4141/usage-viewer?endpoint=http://your-api-server/usage&period=week`\n\n### Usage Viewer Screenshot\n\n<p align=\"center\">\n  <img src=\"./docs/screenshots/usage-viewer.png\" alt=\"Copilot API usage viewer\" width=\"900\" />\n</p>\n\n## Command Structure\n\nCopilot API now uses a subcommand structure with these main commands:\n\n- `start`: Start the gateway server. If a GitHub token is available, the server starts with Copilot enabled. If no GitHub token is available, it starts in provider-only mode when at least one enabled provider exists; otherwise it guides you through provider setup.\n- `auth`: Run provider login or configuration without starting the server. Use it for GitHub Copilot login, Codex OAuth, or third-party provider API key setup.\n- `debug`: Display diagnostic information including version, runtime details, file paths, and authentication status. Useful for troubleshooting and support.\n\n## Command Line Options\n\n### Global Options\n\nThe following options can be used with any subcommand. When passing them before the subcommand, use the `--key=value` form:\n\n| Option            | Description                                            | Default | Alias |\n| ----------------- | ------------------------------------------------------ | ------- | ----- |\n| --api-home        | Path to the API home directory (sets COPILOT_API_HOME) | none    | none  |\n| --oauth-app       | OAuth app identifier (sets COPILOT_API_OAUTH_APP)      | none    | none  |\n| --enterprise-url  | Enterprise URL for GitHub (sets COPILOT_API_ENTERPRISE_URL) | none | none |\n\n### Start Command Options\n\nThe following command line options are available for the `start` command:\n\n| Option         | Description                                                                   | Default    | Alias |\n| -------------- | ----------------------------------------------------------------------------- | ---------- | ----- |\n| --port         | Port to listen on                                                             | 4141       | -p    |\n| --verbose      | Enable verbose logging                                                        | false      | -v    |\n| --github-token | Provide GitHub token directly (must be generated using the `auth` subcommand) | none       | -g    |\n| --claude-code  | Generate a command to launch Claude Code with Copilot API config              | false      | -c    |\n| --show-token   | Show GitHub and Copilot tokens on fetch and refresh                           | false      | none  |\n| --proxy-env    | Initialize proxy from environment variables                                   | false      | none  |\n\n### Auth Command Options\n\n| Option       | Description               | Default | Alias |\n| ------------ | ------------------------- | ------- | ----- |\n| --provider   | Provider to log in with or configure (`copilot`, `codex`, `opencode-go`, `deepseek`, `dashscope`, `openrouter`, or `custom`) | prompt | none |\n| --verbose    | Enable verbose logging    | false   | -v    |\n| --show-token | Show GitHub token on auth | false   | none  |\n\nUse `copilot-api auth login --provider copilot` only when you want to enable the GitHub Copilot provider. Copilot is not required for `codex` or third-party provider-only usage.\n\nUse `copilot-api auth login --provider deepseek`, `--provider dashscope`, `--provider openrouter`, or `--provider opencode-go` to add or update those common third-party providers from the CLI. DeepSeek prompts for masked `apiKey`, provider `type` (default `anthropic`), and `baseUrl` defaulting to `https://api.deepseek.com/anthropic`. DashScope prompts for masked `apiKey`, provider `type` (default `openai-compatible`), and prefilled `baseUrl`. OpenRouter prompts for masked `apiKey` and prefilled `baseUrl` only, and writes `type: \"anthropic\"`. OpenCode Go prompts for masked `apiKey` and prefilled `baseUrl` only, and writes `type: \"openai-compatible\"` (baseUrl `https://opencode.ai/zen/go`). After a provider is configured and enabled, `copilot-api start` can run without any GitHub token.\n\nUse `copilot-api auth login --provider custom` to add or update another third-party provider from the CLI. The command prompts for the provider name, supported type (`anthropic`, `openai-compatible`, or `openai-responses`), `baseUrl`, masked `apiKey`, and `authType`; `authType` may be left as the type default or set to `x-api-key` / `authorization`.\n\n### Debug Command Options\n\n| Option | Description               | Default | Alias |\n| ------ | ------------------------- | ------- | ----- |\n| --json | Output debug info as JSON | false   | none  |\n\n## Configuration (config.json)\n\n- **Location:** `~/.local/share/copilot-api/config.json` (Linux/macOS) or `%USERPROFILE%\\.local\\share\\copilot-api\\config.json` (Windows).\n- **Default shape:**\n  ```json\n  {\n    \"auth\": {\n      \"apiKeys\": [],\n      \"adminApiKey\": \"<auto-generated-on-startup>\"\n    },\n    \"providers\": {},\n    \"modelMappings\": {},\n    \"extraPrompts\": {\n      \"gpt-5-mini\": \"<built-in exploration prompt>\"\n    },\n    \"smallModel\": \"gpt-5-mini\",\n    \"useResponsesApiContextManagement\": true,\n    \"modelResponsesApiCompactThresholds\": {\n      \"gpt-5.4\": 217600,\n      \"gpt-5.5\": 217600\n    },\n    \"modelReasoningEfforts\": {\n      \"gpt-5-mini\": \"low\"\n    },\n    \"useMessagesApi\": true,\n    \"useResponsesApiWebSocket\": true,\n    \"useResponsesApiWebSearch\": true,\n    \"messageApiWebSearchModel\": \"gpt-5-mini\"\n  }\n  ```\n- **auth.apiKeys:** API keys used for request authentication on non-admin routes. Supports multiple keys for rotation. Requests can authenticate with either `x-api-key: <key>` or `Authorization: Bearer <key>`. If empty or omitted, authentication for non-admin routes is disabled.\n- **auth.adminApiKey:** Single admin key used only for `/admin/*` routes. If missing, the server generates a random key at startup and writes it back to `config.json`. Requests use the same `x-api-key` or `Authorization: Bearer` headers, but regular `auth.apiKeys` never grant access to `/admin/*`.\n- **modelMappings:** Exact `sourceModel -> targetModel` rewrites shared by top-level `POST /v1/messages`, `POST /v1/messages/count_tokens`, `POST /v1/responses`, and `POST /v1/chat/completions` requests. Omit it or leave it as `{}` to disable rewrites. Both the source and target must be non-empty strings. Targets can be regular model IDs or `provider/model` aliases such as `dashscope/qwen3.6-plus`, and the rewrite happens before provider alias parsing. These mappings are not split per interface. The admin endpoints `GET/POST /admin/config/model-mappings` read and update only this field.\n- **extraPrompts:** Map of `model -> prompt` appended to the first system prompt when translating Anthropic-style requests to Responses API. Use this to inject guardrails or guidance per model. Missing default entries are auto-added without overwriting your custom prompts. For GPT-5.3+ models (e.g. `gpt-5.3-codex`, `gpt-5.4`, `gpt-5.5`), a built-in commentary prompt is used as fallback when not explicitly configured. The built-in prompts enable phase-aware commentary, which lets the model emit a short user-facing progress update before tools or deeper reasoning.\n- **providers:** Global upstream provider map. Each provider key (for example `dashscope`) becomes a route prefix (`/dashscope/v1/messages`). Supports `type: \"anthropic\"`, `type: \"openai-compatible\"`, and `type: \"openai-responses\"`. Top-level clients can also use `model: \"dashscope/model-id\"` with `/v1/messages`, `/v1/messages/count_tokens`, `/v1/responses`, and `/v1/chat/completions`; the gateway strips the `dashscope/` prefix before forwarding upstream. `openai-compatible` providers support both chat and Messages flows: `/v1/chat/completions` is proxied to upstream `/v1/chat/completions`, while `/v1/messages` and `/:provider/v1/messages` are translated to upstream chat completions and translated back to Anthropic Messages responses. `GET /v1/models` aggregates enabled provider models with `provider/model-id` IDs; use `GET /dashscope/v1/models` for a single provider's raw model list.\n  - `enabled` defaults to `true` if omitted.\n  - `baseUrl` should be provider API base URL without the final endpoint. For Anthropic providers, omit `/v1/messages`; for OpenAI-compatible providers, omit `/v1/chat/completions`; for OpenAI Responses providers, omit `/v1/responses`.\n  - `apiKey` is used as the upstream credential value and is required for regular providers.\n  - `authType` (optional): Controls how `apiKey` is sent upstream. Supports `x-api-key` and `authorization` for regular providers. Anthropic providers default to `x-api-key`; OpenAI-compatible and OpenAI Responses providers default to `authorization`. When set to `authorization`, the proxy sends `Authorization: Bearer <apiKey>`. `oauth2` is reserved for the built-in `codex` provider and is written automatically by `auth login --provider codex`.\n  - `pricingCurrency` (optional): Provider-level currency used for token cost calculation, for example `USD` or `CNY`. Quick providers default to `CNY` for DashScope and DeepSeek, and `USD` for Codex/OpenRouter. Costs are grouped by currency and are not exchange-rate converted.\n  - `models` (optional): Per-model configuration map. Each key is a model ID (matching the model name in requests), and the value is:\n    - `temperature` (optional): Default temperature value used when the request does not specify one.\n    - `topP` (optional): Default top_p value used when the request does not specify one.\n    - `topK` (optional): Default top_k value used when the request does not specify one.\n    - `extraBody` (optional): Dynamic fields merged into the upstream request body for that model. Request body fields with the same name take precedence. OpenAI-compatible providers can use this for fields such as `enable_thinking`, `preserve_thinking`, `reasoning_effort`. `thinking_budget` is a special OpenAI-compatible provider override: when configured in `extraBody`, it is forced after Anthropic `thinking.budget_tokens` translation and overrides the request-derived budget. For providers whose name is `dashscope` or whose `baseUrl` contains `aliyuncs.com`, the request-derived `thinking_budget` (from Anthropic `thinking.budget_tokens`) is forwarded upstream; for other OpenAI-compatible providers the request-derived `thinking_budget` is stripped, while an `extraBody` `thinking_budget` is still honored. For DashScope providers, `preserve_thinking` defaults to `true` when not explicitly set in `extraBody` or the request body.\n    - `pricing` (optional): Per-model token prices, in the provider `pricingCurrency`, per 1M tokens. Supported fields are `input`, `output`, `cachedInput` (implicit cache read), `explicitCachedInput` (explicit cache read), and `cacheCreationInput`. Use `tiers` with `maxInputTokens` for input-size tiered pricing.\n    - `contextCache` (optional): Defaults to `true` for providers whose name is `dashscope` or whose `baseUrl` contains `aliyuncs.com`; defaults to `false` for other OpenAI-compatible providers. This enables Alibaba Cloud Model Studio/DashScope explicit context cache by injecting `cache_control: { \"type\": \"ephemeral\" }` on up to 4 content blocks using the Context Cache format. The cache breakpoint strategy matches opencode's main provider flow: the first 2 system messages plus the last 2 non-system messages. Marked string content is converted to text content part arrays for `system` / `user` / `assistant` / `tool` messages; existing array content is marked on the last part. Set this to `false` when the model already supports implicit caching, or when the upstream does not accept this explicit-cache extension field. Set this to `true` for non-DashScope providers that support the same explicit-cache extension. Applied on both `/v1/messages` and `/v1/chat/completions` routes.\n    - `supportPdf` (optional): Controls whether the model supports PDF/document content. Defaults to `false`; unsupported PDFs are converted to a text notice. Set it to `true` to send PDF/document blocks as OpenAI Chat Completions file parts.\n    - `toolContentSupportType` (optional): Tool result content capabilities for that model, as an array of `array`, `image`, and `pdf`. Provider routes default to string-only tool content when omitted. If `supportPdf` is `true` but this list does not include `pdf`, file parts in tool results are moved to user role messages. This provider default does not change the Copilot main flow, which continues to support array + image and not PDF.\n    - `type` (optional): Per-model override of the provider protocol type. Supports `anthropic`, `openai-compatible`, and `openai-responses`. When set, the provider's `/v1/messages` route uses this model's type instead of the provider-level type for request routing, auth header resolution, and upstream endpoint selection. This is useful for providers like OpenCode Go whose upstream supports both OpenAI-compatible and Anthropic Messages APIs for different models. When the type is overridden, the auth header is resolved from the overridden type's default (Anthropic defaults to `x-api-key`; OpenAI-compatible/Responses default to `authorization`).\n\n  Example DashScope model settings:\n  ```json\n  {\n    \"providers\": {\n      \"dashscope\": {\n        \"type\": \"openai-compatible\",\n        \"enabled\": true,\n        \"baseUrl\": \"https://dashscope.aliyuncs.com/compatible-mode\",\n        \"apiKey\": \"sk-your-dashscope-key\",\n        \"pricingCurrency\": \"CNY\",\n        \"models\": {\n          \"qwen3.7-plus\": {\n            \"temperature\": 1,\n            \"topP\": 0.95,\n            \"topK\": 20,\n            \"extraBody\": {\n              \"preserve_thinking\": true\n            }\n          },\n          \"glm-5.1\": {\n            \"temperature\": 0.7,\n            \"topP\": 0.95,\n            \"contextCache\": true,\n            \"pricing\": {\n              \"tiers\": [\n                {\n                  \"maxInputTokens\": 32000,\n                  \"input\": 6,\n                  \"cachedInput\": 1.2,\n                  \"explicitCachedInput\": 0.6,\n                  \"cacheCreationInput\": 7.5,\n                  \"output\": 24\n                },\n                {\n                  \"maxInputTokens\": 200000,\n                  \"input\": 8,\n                  \"cachedInput\": 1.6,\n                  \"explicitCachedInput\": 0.8,\n                  \"cacheCreationInput\": 10,\n                  \"output\": 28\n                }\n              ]\n            },\n            \"extraBody\": {\n              \"preserve_thinking\": true\n            }\n          }\n        }\n      }\n    }\n  }\n  ```\n  Built-in token prices cover Codex GPT models in USD, DashScope `qwen3.7-max`, `qwen3.7-plus`, `glm-5.1`, `glm-5.2` in CNY, DeepSeek `deepseek-v4-flash`, `deepseek-v4-pro`, `deepseek-chat`, `deepseek-reasoner` in CNY, and OpenCode Go models (`glm-5.2`, `deepseek-v4-flash`, `deepseek-v4-pro`, `kimi-k2.7-code`, `mimo-v2.5`, `mimo-v2.5-pro`, `qwen3.7-plus`, `qwen3.7-max`, `minimax-m2.5`, `minimax-m3`) in USD. User `pricing` entries override built-ins. For DashScope, cached tokens are charged as explicit cache reads when the upstream usage includes `cache_creation_input_tokens`; otherwise `cachedInput` is used as the implicit cache read price. For DeepSeek, `prompt_cache_hit_tokens` map to cached input and `prompt_cache_miss_tokens` map to regular input.\n- **smallModel:** Fallback model used for tool-less warmup messages (e.g., Claude Code probe requests); defaults to gpt-5-mini.\n- **useResponsesApiContextManagement:** When `true`, the proxy adds Responses API `context_management` compaction instructions. Defaults to `true`. Set it to `false` to disable this globally. When enabled, the request includes `context_management` in the body and keeps only the latest compaction carrier on follow-up turns. This is especially useful for long-running tasks.\n- **modelResponsesApiCompactThresholds:** Per-model Responses API `compact_threshold` overrides used when the proxy adds `context_management`. These values take precedence over the fallback threshold from `resolveResponsesCompactThreshold` (`max_prompt_tokens * ratio`, or the default fallback). Defaults set `gpt-5.4` and `gpt-5.5` to `217600` (`272000 * 0.8`). Models not listed continue to use the normal fallback logic.\n- **modelReasoningEfforts:** Per-model reasoning effort applied to `/v1/messages` requests. When routed to the Copilot native Messages API it sets `output_config.effort`; when translated to the Responses API it sets `reasoning.effort`. Allowed values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. If a model isn't listed, `high` is used by default; GPT-5.3+ models fall back to `xhigh` when not explicitly configured.\n- **useMessagesApi:** When `true`, Claude-family models that support Copilot's native `/v1/messages` endpoint will use the Messages API; otherwise they fall back to `/chat/completions`. Set to `false` to disable Messages API routing and always use `/chat/completions`. Defaults to `true`.\n- **useResponsesApiWebSocket:** When `true`, Responses API requests use Copilot's websocket transport for models that advertise `ws:/responses`; models that only advertise `/responses` continue to use HTTP. Set to `false` to disable websocket routing and use HTTP `/responses` whenever the selected model supports it. Defaults to `true`.\n- **useResponsesApiWebSearch:** When `true`, the server keeps Responses API tools with `type: \"web_search\"` and forwards them upstream. Set to `false` to strip those tools from `/responses` payloads. Defaults to `true`.\n- **messageApiWebSearchModel:** Global fallback model used when a top-level Copilot `/v1/messages` request contains only the server-side `web_search` tool. Defaults to `gpt-5-mini`. If the value is a `provider/model` alias, the request is routed into that provider's Messages API path with the provider prefix stripped. For Copilot GPT models, web search runs through `/responses`. Mixed `web_search` plus custom tools are not supported and the server-side `web_search` tool is stripped.\n- **claudeTokenMultiplier:** Multiplier applied to the fallback GPT-tokenizer estimate for Claude `/v1/messages/count_tokens` requests. Defaults to `1.15`. Increase it if your client is still compacting too late. This setting is only used when the proxy is estimating Claude tokens locally; if `anthropicApiKey` is configured and Anthropic token counting succeeds, the exact Anthropic count is returned instead.\n- **anthropicApiKey:** Anthropic API key used to forward Claude `/v1/messages/count_tokens` requests to Anthropic's real token counting endpoint, which returns exact counts instead of GPT tokenizer estimates. Can also be set via the `ANTHROPIC_API_KEY` environment variable. If not set, or if the upstream call fails, token counting falls back to local GPT tokenizer estimation controlled by `claudeTokenMultiplier`.\n\nEdit this file to customize prompts or swap in your own fast model. Restart the server (or rerun the command) after changes so the cached config is refreshed.\n\n## API Authentication\n\n- **Protected non-admin routes:** All routes except `/`, `/usage-viewer`, and `/usage-viewer/` require authentication when `auth.apiKeys` is configured and non-empty.\n- **Admin routes:** All `/admin/*` routes require `auth.adminApiKey`. If it is missing, the server generates one at startup and persists it to `config.json` before serving requests.\n- **Allowed auth headers:**\n  - `x-api-key: <your_key>`\n  - `Authorization: Bearer <your_key>`\n- **CORS preflight:** `OPTIONS` requests are always allowed.\n- **When no regular keys are configured:** Non-admin routes continue to allow requests. This does not apply to `/admin/*`, which only accepts `auth.adminApiKey`.\n\nExample request for a regular protected route:\n\n```sh\ncurl http://localhost:4141/v1/models \\\n  -H \"x-api-key: your_api_key\"\n```\n\nExample request for an admin route:\n\n```sh\ncurl http://localhost:4141/admin/config/model-mappings \\\n  -H \"x-api-key: your_admin_api_key\"\n```\n\n## API Endpoints\n\nThe server exposes several OpenAI- and Anthropic-compatible endpoints. Requests can target GitHub Copilot, the built-in `codex` provider, or configured providers depending on the selected model and `provider/model` alias.\n\n### OpenAI Compatible Endpoints\n\nThese endpoints mimic the OpenAI API structure.\n\n| Endpoint                    | Method | Description                                                      |\n| --------------------------- | ------ | ---------------------------------------------------------------- |\n| `POST /v1/responses`        | `POST` | OpenAI Most advanced interface for generating model responses. Supports `provider/model` aliases for `openai-responses` providers. |\n| `POST /v1/chat/completions` | `POST` | Creates a model response for the given chat conversation. Supports `provider/model` aliases for `openai-compatible` providers and can be used without Copilot when the target provider is configured. |\n| `GET /v1/models`            | `GET`  | Lists Copilot models plus enabled provider models using `provider/model-id` IDs. |\n| `POST /v1/embeddings`       | `POST` | Creates an embedding vector representing the input text.         |\n\n### Anthropic Compatible Endpoints\n\nThese endpoints are designed to be compatible with the Anthropic Messages API.\n\n| Endpoint                         | Method | Description                                                  |\n| -------------------------------- | ------ | ------------------------------------------------------------ |\n| `POST /v1/messages`              | `POST` | Creates a model response for a given conversation. Supports `provider/model` aliases for configured providers, including translation through `openai-compatible` providers. |\n| `POST /v1/messages/count_tokens` | `POST` | Calculates the number of tokens for a given set of messages. Supports `provider/model` aliases for configured providers. |\n| `POST /:provider/v1/messages`       | `POST` | Proxies Anthropic Messages requests to the configured Anthropic provider, translates them through an OpenAI-compatible provider, or translates them through an OpenAI Responses provider. |\n| `GET /:provider/v1/models`          | `GET`  | Proxies model listing requests to the configured provider.   |\n| `POST /:provider/v1/messages/count_tokens` | `POST` | Calculates tokens locally for provider route requests. |\n\n### Usage Monitoring Endpoints\n\nNew endpoints for monitoring your Copilot usage and quotas.\n\n| Endpoint     | Method | Description                                                  |\n| ------------ | ------ | ------------------------------------------------------------ |\n| `GET /usage` | `GET`  | Get detailed Copilot usage statistics and quota information. |\n| `GET /token` | `GET`  | Get the current Copilot token being used by the API.         |\n\n### Admin / Configuration Endpoints\n\nThese endpoints are reserved for local administrative actions and only accept `auth.adminApiKey`.\n\n| Endpoint                              | Method | Description                                                                 |\n| ------------------------------------- | ------ | --------------------------------------------------------------------------- |\n| `GET /admin/config/model-mappings`    | `GET`  | Returns the current `config.json` path and the active `modelMappings` map.  |\n| `POST /admin/config/model-mappings`   | `POST` | Updates only the `modelMappings` field in `config.json` and returns it back. |\n\n## Example Usage\n\nCommon `npx` commands:\n\n```sh\n# Start the gateway\nnpx @jeffreycao/copilot-api@latest start\n\n# Start on a custom port with verbose logging\nnpx @jeffreycao/copilot-api@latest start --port 8080 --verbose\n\n# Run the auth flow\nnpx @jeffreycao/copilot-api@latest auth login\n\n# Configure a third-party provider, then run without GitHub Copilot\nnpx @jeffreycao/copilot-api@latest auth login --provider dashscope\nnpx @jeffreycao/copilot-api@latest start\n\n# Print debug information as JSON\nnpx @jeffreycao/copilot-api@latest debug --json\n\n# Run the published CLI with Bun instead of Node.js\nbunx --bun @jeffreycao/copilot-api@latest start\n```\n\nOpenAI-compatible provider examples after configuring `dashscope`:\n\n```sh\ncurl http://localhost:4141/v1/chat/completions \\\n  -H \"content-type: application/json\" \\\n  -d '{\"model\":\"dashscope/qwen3.6-plus\",\"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]}'\n\ncurl http://localhost:4141/dashscope/v1/messages \\\n  -H \"content-type: application/json\" \\\n  -d '{\"model\":\"qwen3.6-plus\",\"max_tokens\":1024,\"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]}'\n```\n\n## Usage Tips\n\n### CLAUDE.md or AGENTS.md Recommended Content\n\nTo add these reminders manually, include the following in `CLAUDE.md` for Claude Code, or `AGENTS.md` for opencode/codex:\n\n```\n- Prohibited from directly asking questions to users, MUST use question tool.\n- Once you can confirm that the task is complete, MUST use question tool to make user confirm. The user may respond with feedback if they are not satisfied with the result, which you can use to make improvements and try again, after try again, MUST use question tool to make user confirm again.\n```\n"}, "2fefd36681b834113d378b87513f3b16c0c9cc47": {"t": 1785765571.4901674, "n": 46174, "h": "24fb1ed1a0808381", "c": "# Copilot API Proxy\n\nEnglish | [简体中文](./README.zh-CN.md)\n\n## Important Notes\n\n> [!IMPORTANT]\n> **Before using, please be aware of the following:**\n>\n> 1. **Claude Code configuration:** When using with Claude Code, please configure the model ID as `claude-opus-4-8`. Example claude `settings.json` see [Manual Configuration with `settings.json`](#manual-configuration-with-settingsjson). \n>\n> 2. **Built-in `copilot`, `codex` and third-party providers:** Run `npx @jeffreycao/copilot-api@latest auth` and choose `copilot`, `codex`, `deepseek`, `custom`, or other providers.\n>\n> 3. **Note:** See [GitHub Copilot Security Notice](./NOTICE.md#github-copilot-security-notice) for the warning removed from the README header.\n\n---\n\n## Project Overview\n\nA small AI gateway that can use GitHub Copilot, the built-in `codex` provider, or configured third-party providers such as DashScope. GitHub Copilot is optional: if no GitHub token is available, the server can still start in provider-only mode as long as at least one enabled provider is configured.\n\nThe gateway exposes OpenAI- and Anthropic-compatible APIs from one local endpoint, so tools like [Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview), OpenCode, Codex, and OpenAI-compatible clients can share the same local server.\n\nOn the GitHub Copilot path, the gateway prefers Copilot's native Anthropic-style Messages API when available, preserving more Claude-native behavior for tool-heavy workflows.\n\n## Features\n\n- **OpenAI and Anthropic compatibility**: Serve `/v1/responses`, `/v1/chat/completions`, `/v1/models`, `/v1/embeddings`, and `/v1/messages` from one local gateway.\n- **Copilot is optional**: Use GitHub Copilot when credentials are present, or run the server with only configured providers.\n- **One gateway for Copilot, `codex`, and external providers**: Route GitHub Copilot, the built-in `codex` provider, and configured third-party providers behind the same endpoint.\n- **Standalone third-party providers**: Configure providers such as DashScope, DeepSeek, OpenRouter, or a custom provider and start the gateway without a GitHub Copilot login.\n- **OpenAI-compatible providers on chat and Messages APIs**: `openai-compatible` providers can serve top-level `/v1/chat/completions` through `model: \"provider/model\"` and Anthropic-style `/v1/messages` through request/response translation.\n- **Agent-friendly Claude handling on Copilot**: Prefer native `/v1/messages` when available, preserve Claude-style tool flows, support Anthropic beta features, Claude WebSearch through Responses-capable models, and keep subagent/session markers intact.\n- **Claude Code and OpenCode integration**: Works with Claude Code and OpenCode, including direct Anthropic-compatible usage through `@ai-sdk/anthropic`.\n- **Flexible auth and deployment options**: Supports interactive login or direct tokens, individual/business/enterprise plans, GitHub Enterprise, opencode OAuth, and custom data directories.\n- **Multi-provider routing**: Expose provider-specific `/:provider/...` routes or use `model: \"provider/model\"` on the top-level API.\n\n## Prerequisites\n\n- Bun (>= 1.2.x)\n- Node.js if you plan to run the published CLI with `npx`\n- GitHub account with Copilot subscription only if you want to use the GitHub Copilot provider\n- An API key or OAuth login for at least one configured provider if you want to run without GitHub Copilot\n\n## Installation\n\nTo install dependencies, run:\n\n```sh\nbun install\n```\n\nTo start the server directly from source:\n\n```sh\nbun run start start\n```\n\n## Running from Source\n\nThe project can be run from source in several ways:\n\n### Development Mode\n\n```sh\nbun run dev start\n```\n\n### Production Mode\n\n```sh\nbun run start start\n```\n\n## Using with npx\n\nYou can run the project directly using npx:\n\n> [!IMPORTANT]\n> Token usage storage uses Node's built-in `node:sqlite` module when running with `npx`. It is enabled on Node.js >= 22.13.0. On Node.js < 22.13.0, the CLI still starts, but token usage storage is disabled.\n>\n> If you want token usage storage without upgrading Node.js, run the published CLI with Bun instead: `bunx --bun @jeffreycao/copilot-api@latest start`.\n\n```sh\nnpx @jeffreycao/copilot-api@latest start\n```\n\nWith options:\n\n```sh\nnpx @jeffreycao/copilot-api@latest start --port 8080\n```\n\nFor authentication or provider configuration only:\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth\n```\n\nTo run without GitHub Copilot, configure at least one provider first, then start the server normally:\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth login --provider dashscope\nnpx @jeffreycao/copilot-api@latest start\n```\n\n## Using with Docker\n\nBuild the image:\n\n```sh\ndocker build -t copilot-api .\n```\n\nRun the container with a bind mount so auth data survives restarts:\n\n```sh\nmkdir -p ./copilot-data\ndocker run -p 4141:4141 -v $(pwd)/copilot-data:/root/.local/share/copilot-api copilot-api\n```\n\nThis stores GitHub auth data, provider config, and other gateway state in `./copilot-data` on the host, mapped to `/root/.local/share/copilot-api` in the container.\n\nOr pass a GitHub token directly:\n\n```sh\ndocker run -p 4141:4141 -e GH_TOKEN=your_github_token_here copilot-api\n```\n\n## Electron Desktop App\n\nIf you prefer a GUI, this repository also includes an Electron desktop app in `desktop/`. It supports GitHub Copilot sign-in, OpenAI Codex OAuth, and API-key configuration for DeepSeek, DashScope, OpenRouter, or a custom provider. After authorization or provider configuration, it can start and stop the local proxy with one click and shows the local endpoint, auth header, available models, usage, and logs in the app.\n\nThe settings screen also exposes `OAuth App`, `API Home`, `Enterprise URL`, verbose logging, and minimize-to-tray. Desktop packages are published in GitHub Releases:\n\nhttps://github.com/caozhiyuan/copilot-api/releases\n\nDownload the installer for your platform, authorize or configure a provider inside the app, choose a port, start the server, then point your client at the local endpoint shown in the app. Packaged desktop builds use the bundled Electron runtime, so normal desktop usage does not require installing Node.js separately. Token usage history is enabled when that bundled runtime supports SQLite.\n\nThe desktop app's Advanced Config page reads and writes the shared model mappings through `GET/POST /admin/config/model-mappings`. The same mappings apply across `POST /v1/messages`, `POST /v1/messages/count_tokens`, `POST /v1/responses`, and `POST /v1/chat/completions` instead of being split per interface. It uses `auth.adminApiKey` instead of the regular `auth.apiKeys`, and the app reads that key directly from `config.json` after the server has generated it on startup.\n\n### Desktop App Screenshots\n\nMain dashboard, token usage breakdown in the bundled Electron app:\n\n<p align=\"center\">\n  <img src=\"./docs/screenshots/desktop-dashboard.png\" alt=\"Copilot API desktop app dashboard\" width=\"49%\" />\n  <img src=\"./docs/screenshots/desktop-token-usage.png\" alt=\"Copilot API desktop app token usage view\" width=\"49%\" />\n</p>\n\n## Using with Claude Code\n\nThis AI gateway can be used to power [Claude Code](https://docs.anthropic.com/en/claude-code), an experimental conversational AI assistant for developers from Anthropic.\n\nThere are two ways to configure Claude Code to use this AI gateway:\n\n### Interactive Setup with `--claude-code` flag\n\nTo get started, run the `start` command with the `--claude-code` flag:\n\n```sh\nnpx @jeffreycao/copilot-api@latest start --claude-code\n```\n\nYou will be prompted to select a primary model and a \"small, fast\" model for background tasks. After selecting the models, a command will be copied to your clipboard. This command sets the necessary environment variables for Claude Code to use the gateway.\n\nPaste and run this command in a new terminal to launch Claude Code.\n\n### Manual Configuration with `settings.json`\n\nAlternatively, you can configure Claude Code by creating a `.claude/settings.json` file in your project's root directory. This file should contain the environment variables needed by Claude Code. This way you don't need to run the interactive setup every time.\n\nHere is an example `.claude/settings.json` file:\n\n```json\n{\n  \"env\": {\n    \"ANTHROPIC_BASE_URL\": \"http://localhost:4141\",\n    \"ANTHROPIC_AUTH_TOKEN\": \"dummy\",\n    \"ANTHROPIC_MODEL\": \"deepseek/deepseek-v4-pro\",\n    \"ANTHROPIC_DEFAULT_SONNET_MODEL\": \"deepseek/deepseek-v4-pro\",\n    \"ANTHROPIC_DEFAULT_HAIKU_MODEL\": \"deepseek/deepseek-v4-flash\",\n    \"DISABLE_NON_ESSENTIAL_MODEL_CALLS\": \"1\",\n    \"CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC\": \"1\",\n    \"CLAUDE_CODE_ATTRIBUTION_HEADER\": \"0\",\n    \"CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION\": \"false\",\n    \"CLAUDE_CODE_DISABLE_TERMINAL_TITLE\": \"true\",\n    \"CLAUDE_CODE_ENABLE_AWAY_SUMMARY\": \"0\"\n  },\n  \"permissions\": {\n    \"deny\": [\n      \"mcp__ide__executeCode\"\n    ]\n  }\n}\n```\n\n- Replace `ANTHROPIC_MODEL`, `ANTHROPIC_DEFAULT_OPUS_MODEL`, `ANTHROPIC_DEFAULT_SONNET_MODEL`, and `ANTHROPIC_DEFAULT_HAIKU_MODEL` according to your needs. After configuration, please install the claude code plugin [Plugin Integrations](#plugin-integrations).  \n- Setting CLAUDE_CODE_ATTRIBUTION_HEADER to 0 can prevent Claude code from adding billing and version information in system prompts, thereby avoiding prompt cache invalidation.\n- Turning off CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION and CLAUDE_CODE_ENABLE_AWAY_SUMMARY can prevent quota from being consumed unnecessarily.\n- Claude Code WebSearch is supported for pure search requests. For Copilot, keep the global `messageApiWebSearchModel` set to a Responses-capable GPT model or a `provider/model` alias. For provider routes, use a native Anthropic provider or an `openai-responses` provider. Add `WebSearch` to `permissions.deny` only if you want to forbid this traffic.\n- If using a non-Claude model, do not enable ENABLE_TOOL_SEARCH. If using the Claude model, can enable ENABLE_TOOL_SEARCH. The current Claude Code uses the client tool search mode. In this mode, loading defer tools requires an additional request each time.\n- `CLAUDE_CODE_AUTO_COMPACT_WINDOW`: Set the context capacity in tokens used for auto-compaction calculations. Defaults to the model's context window: 200K for standard models or 1M for extended context models. Use a lower value like `500000` on a 1M model (e.g., `claude-opus-4-6[1m]`) to treat the window as 500K for compaction purposes. The value is capped at the model's actual context window. `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` is applied as a percentage of this value. Setting this variable decouples the compaction threshold from the status line's `used_percentage`, which always uses the model's full context window.\n\nYou can find more options here: [Claude Code settings](https://docs.anthropic.com/en/docs/claude-code/settings#environment-variables)\n\nYou can also read more about IDE integration here: [Add Claude Code to your IDE](https://docs.anthropic.com/en/docs/claude-code/ide-integrations)\n\n## Using with OpenCode\n\nOpenCode already has a direct GitHub Copilot provider. Use this section when you want OpenCode to point at this AI gateway through `@ai-sdk/anthropic` and reuse the agent behaviors described earlier in this README.\n\n### Minimal setup\n\nStart the AI gateway with the OpenCode OAuth app:\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth --oauth-app=opencode\nnpx @jeffreycao/copilot-api@latest start\n```\n\nThen point OpenCode at the gateway with `@ai-sdk/anthropic`.\n\nExample `~/.config/opencode/opencode.json`:\n\n```json\n{\n  \"$schema\": \"https://opencode.ai/config.json\",\n  \"provider\": {\n    \"local\": {\n      \"npm\": \"@ai-sdk/anthropic\",\n      \"name\": \"My Local\",\n      \"options\": {\n        \"baseURL\": \"http://localhost:4141/v1\",\n        \"apiKey\": \"dummy\"\n      },\n      \"models\": {\n        \"gpt-5.4\": {\n          \"name\": \"gpt-5.4\",\n          \"modalities\": {\n            \"input\": [\"text\", \"image\"],\n            \"output\": [\"text\"]\n          },\n          \"limit\": {\n            \"context\": 300000,\n            \"output\": 128000\n          }\n        },\n        \"claude-sonnet-4.6\": {\n          \"id\": \"claude-sonnet-4.6\",\n          \"name\": \"claude-sonnet-4.6\",\n          \"modalities\": {\n            \"input\": [\"text\", \"image\"],\n            \"output\": [\"text\"]\n          },          \n          \"limit\": {\n            \"context\": 200000,\n            \"output\": 32000\n          },\n          \"options\": {\n            \"thinking\": {\n              \"type\": \"adaptive\"\n            },\n            \"effort\": \"max\"\n          }\n        }\n      }\n    }\n  }\n}\n```\n\nWhy these fields matter:\n\n- `npm: \"@ai-sdk/anthropic\"` is the important part. OpenCode will speak Anthropic Messages semantics to this AI gateway instead of flattening everything into OpenAI Chat Completions.\n- `options.baseURL` should be `http://localhost:4141/v1`; the Anthropic SDK will append `/messages`, `/models`, and `/messages/count_tokens` automatically.\n- If you enable `auth.apiKeys` in this AI gateway, replace `dummy` with a real key. Otherwise any placeholder value is fine.\n\n## Using with Codex\n\nThis AI gateway can also power Codex.\n\n### Codex `config.toml` Reference\n\nAdd the following `[model_providers.copilot_api]` section to your Codex `~/.codex/config.toml`:\n\n```toml\nmodel_provider = \"copilot_api\"\nmodel_reasoning_summary = \"auto\"\nmodel_verbosity = \"medium\"\nmodel_context_window = 272000\nmodel_auto_compact_token_limit = 244800\n\n[model_providers.copilot_api]\nname = \"OpenAI\"\nbase_url = \"http://localhost:4141\"\nenv_key = \"GITHUB_COPILOT_API_KEY\"\nrequires_openai_auth = true\nsupports_websockets = false\nwire_api = \"responses\"\nrequest_max_retries = 3\nstream_max_retries = 1\nstream_idle_timeout_ms = 300000\n\n[features]\nremote_compaction_v2 = true\n\n[analytics]\nenabled = false\n```\n\n> [!NOTE]\n> This configuration is specific to Codex and the GitHub Copilot provider. `name` must be set to `\"OpenAI\"`. It can help mitigate Codex local compact cache miss issues. If you have enabled `useResponsesApiContextManagement` (Responses API context management compaction), `remote_compaction_v2` or local compact is generally not triggered, but it may still occur when tool results return a large number of tokens.\n\n## GPT Tool Search\n\nFor GPT Responses models such as `gpt-5.4+`, this AI gateway can expose Responses `tool_search` through a small MCP bridge. The same bridge can be used by Claude Code and opencode, as long as the client loads MCP servers and sends Anthropic Messages traffic through this gateway.\n\nDo not set Claude Code's native `ENABLE_TOOL_SEARCH` for GPT models. That flag enables Claude Code's own client-side tool search mode, and it may stop forwarding deferred tool definitions. This gateway needs the full tool definitions so it can keep the small always-loaded tool set eager and translate every other tool into Responses deferred namespaces.\n\nIf you install `tool-search@copilot-api-marketplace`, Claude Code receives this MCP bridge automatically and you can skip the manual Claude Code MCP setup below.\n\nAdd the tool search bridge to the MCP config used by Claude Code:\n\n```json\n{\n  \"mcpServers\": {\n    \"tool_search\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@jeffreycao/copilot-api@latest\", \"mcp\"]\n    }\n  }\n}\n```\n\nAdd the tool search bridge to the MCP config used by opencode:\n\n```json\n{\n  \"mcp\": {\n    \"tool_search\": {\n      \"type\": \"local\",\n      \"command\": [\"npx\", \"-y\", \"@jeffreycao/copilot-api@latest\", \"mcp\"]\n    }\n  }\n}\n```\n\nFor local development, use `bun` as the command and `[\"run\", \"./src/main.ts\", \"mcp\"]` as the args.\n\nInternally, the gateway now configures OpenAI Responses `tool_search` in client-executed mode. Deferred tools are still exposed as searchable namespaces, but the model is explicitly asked to return the exact deferred tool names it wants to load next.\n\nThe bridge uses direct tool selection, not query search. Its tool input is `names`, a comma-separated list of exact deferred tool names, for example `TaskList,TaskGet,mcp__fetch__fetch`.\n\n## Plugin Integrations\n\nPlugin integrations are available for Claude Code and opencode.\n\n#### Claude Code plugin integration (marketplace-based)\n\nThe Claude Code integration is packaged as two plugins:\n\n- `agent-inject` injects `__SUBAGENT_MARKER__...` on `SubagentStart`, so the gateway can infer `x-initiator: agent`.\n- `tool-search` registers the `tool_search` MCP bridge used for GPT Responses deferred tool loading.\n\n- Marketplace catalog in this repository: `.claude-plugin/marketplace.json`\n- Plugin sources in this repository: `plugin/claude/agent-inject`, `plugin/claude/tool-search`\n\nAdd the marketplace remotely:\n\n```sh\n/plugin marketplace add https://github.com/caozhiyuan/copilot-api.git\n```\n\nInstall the plugins from the marketplace:\n\n```sh\n/plugin install agent-inject@copilot-api-marketplace\n/plugin install tool-search@copilot-api-marketplace\n```\n\nAfter installation, `agent-inject` injects `__SUBAGENT_MARKER__...` on `SubagentStart`, and the gateway uses it to infer `x-initiator: agent`.\n\nThe `agent-inject` plugin also registers a `UserPromptSubmit` hook that returns `{\"continue\": true}`, and it can inject `SessionStart` reminder rules through environment variables:\n\n- `CLAUDE_PLUGIN_ENABLE_QUESTION_RULES=1` enables the two reminders about using the `question` tool automatically for Claude Code. Alternatively, you can add the same reminders manually in `CLAUDE.md`; see [CLAUDE.md or AGENTS.md Recommended Content](#claudemd-or-agentsmd-recommended-content).\n- `CLAUDE_PLUGIN_ENABLE_NO_BACKGROUND_AGENTS_RULE=1` enables the `run_in_background: true` avoidance reminder for agent hooks.\n\nThe `tool-search` plugin bundles the same MCP bridge described in [GPT Tool Search](#gpt-tool-search), so Claude Code users do not need to add the `tool_search` server manually when they install that plugin.\n\n#### Opencode plugin\n\nThe subagent marker producer is packaged as an opencode plugin located at `plugin/opencode/subagent-marker.js`.\n\n**Installation:**\n\nCopy the plugin file to your opencode plugins directory:\n\n```sh\n# Clone or download this repository, then copy the plugin\ncp plugin/opencode/subagent-marker.js ~/.config/opencode/plugins/\n```\n\nOr manually create the file at `~/.config/opencode/plugins/subagent-marker.js` with the plugin content.\n\n**Features:**\n\n- Tracks sub-sessions created by subagents\n- Automatically prepends a marker system reminder (`__SUBAGENT_MARKER__...`) to subagent chat messages\n- Sets `x-session-id` header for session tracking\n- Enables the gateway to infer `x-initiator: agent` for subagent-originated requests\n\nThe plugin hooks into `session.created`, `session.deleted`, `chat.message`, and `chat.headers` events to provide seamless subagent marker functionality.\n\n## Using the Usage Viewer\n\nAfter starting the server, a URL to the Copilot Usage Dashboard will be displayed in your console. This dashboard is a web interface for monitoring your API usage.\n\n1.  Start the server. For example, using npx:\n    ```sh\n    npx @jeffreycao/copilot-api@latest start\n    ```\n2.  The server will output a URL to the usage viewer. Copy and paste this URL into your browser. It will look something like this:\n    `http://localhost:4141/usage-viewer?endpoint=http://localhost:4141/usage`\n    - If you use the `start.bat` script on Windows, this page will open automatically.\n\nThe dashboard provides a user-friendly interface to view your Copilot usage data:\n\n> Token usage history requires Bun or Node.js >= 22.13.0. On Node.js < 22.13.0, the server runs normally but token usage storage is disabled.\n\n- **API Endpoint URL**: The dashboard is pre-configured to fetch data from your local server endpoint via a URL query parameter. You can manually switch this to any other compatible API endpoint.\n- **x-api-key Authentication**: If API Key authentication is enabled, you can provide the `x-api-key` request header. The key is persisted in the browser's local storage.\n- **Period Selector**: Choose from Day, Week, or Month time ranges. The URL query parameter updates automatically when you switch, making it easy to bookmark and share.\n- **Fetch Data**: Click the \"Refresh\" button to load or refresh the usage data. The dashboard also fetches data automatically on page load.\n- **Copilot Quotas**: View quota usage for services such as Chat and Completions via progress bars. Hover over a card to see used/remaining details.\n- **Token Usage Metric Cards**: See a summary of Total, Input, Output, Cache Read, Cache Write, Requests, and estimated cost for the current period.\n- **Trend Chart (Week / Month)**: An interactive line chart with model and metric filters. Click a data point to inspect the usage breakdown for a specific day.\n- **Model Breakdown Table**: A per-model summary of requests, input/output/cache tokens, and estimated cost for the selected period.\n- **Request Events (Paginated)**: A time-sorted list of request event records with pagination support, showing timestamps, models, request IDs, and token counts.\n- **Detailed Information**: See the full JSON response from the API for a detailed breakdown of all available usage statistics.\n- **URL-based Configuration**: You can also specify the API endpoint and period directly via `endpoint` and `period` query parameters. For example:\n  `http://localhost:4141/usage-viewer?endpoint=http://your-api-server/usage&period=week`\n\n### Usage Viewer Screenshot\n\n<p align=\"center\">\n  <img src=\"./docs/screenshots/usage-viewer.png\" alt=\"Copilot API usage viewer\" width=\"900\" />\n</p>\n\n## Command Structure\n\nCopilot API now uses a subcommand structure with these main commands:\n\n- `start`: Start the gateway server. If a GitHub token is available, the server starts with Copilot enabled. If no GitHub token is available, it starts in provider-only mode when at least one enabled provider exists; otherwise it guides you through provider setup.\n- `auth`: Run provider login or configuration without starting the server. Use it for GitHub Copilot login, Codex OAuth, or third-party provider API key setup.\n- `debug`: Display diagnostic information including version, runtime details, file paths, and authentication status. Useful for troubleshooting and support.\n\n## Command Line Options\n\n### Global Options\n\nThe following options can be used with any subcommand. When passing them before the subcommand, use the `--key=value` form:\n\n| Option            | Description                                            | Default | Alias |\n| ----------------- | ------------------------------------------------------ | ------- | ----- |\n| --api-home        | Path to the API home directory (sets COPILOT_API_HOME) | none    | none  |\n| --oauth-app       | OAuth app identifier (sets COPILOT_API_OAUTH_APP)      | none    | none  |\n| --enterprise-url  | Enterprise URL for GitHub (sets COPILOT_API_ENTERPRISE_URL) | none | none |\n\n### Start Command Options\n\nThe following command line options are available for the `start` command:\n\n| Option         | Description                                                                   | Default    | Alias |\n| -------------- | ----------------------------------------------------------------------------- | ---------- | ----- |\n| --port         | Port to listen on                                                             | 4141       | -p    |\n| --verbose      | Enable verbose logging                                                        | false      | -v    |\n| --github-token | Provide GitHub token directly (must be generated using the `auth` subcommand) | none       | -g    |\n| --claude-code  | Generate a command to launch Claude Code with Copilot API config              | false      | -c    |\n| --show-token   | Show GitHub and Copilot tokens on fetch and refresh                           | false      | none  |\n| --proxy-env    | Initialize proxy from environment variables                                   | false      | none  |\n\n### Auth Command Options\n\n| Option       | Description               | Default | Alias |\n| ------------ | ------------------------- | ------- | ----- |\n| --provider   | Provider to log in with or configure (`copilot`, `codex`, `opencode-go`, `deepseek`, `dashscope`, `openrouter`, or `custom`) | prompt | none |\n| --verbose    | Enable verbose logging    | false   | -v    |\n| --show-token | Show GitHub token on auth | false   | none  |\n\nUse `copilot-api auth login --provider copilot` only when you want to enable the GitHub Copilot provider. Copilot is not required for `codex` or third-party provider-only usage.\n\nUse `copilot-api auth login --provider deepseek`, `--provider dashscope`, `--provider openrouter`, or `--provider opencode-go` to add or update those common third-party providers from the CLI. DeepSeek prompts for masked `apiKey`, provider `type` (default `anthropic`), and `baseUrl` defaulting to `https://api.deepseek.com/anthropic`. DashScope prompts for masked `apiKey`, provider `type` (default `openai-compatible`), and prefilled `baseUrl`. OpenRouter prompts for masked `apiKey` and prefilled `baseUrl` only, and writes `type: \"anthropic\"`. OpenCode Go prompts for masked `apiKey` and prefilled `baseUrl` only, and writes `type: \"openai-compatible\"` (baseUrl `https://opencode.ai/zen/go`). After a provider is configured and enabled, `copilot-api start` can run without any GitHub token.\n\nUse `copilot-api auth login --provider custom` to add or update another third-party provider from the CLI. The command prompts for the provider name, supported type (`anthropic`, `openai-compatible`, or `openai-responses`), `baseUrl`, masked `apiKey`, and `authType`; `authType` may be left as the type default or set to `x-api-key` / `authorization`.\n\n### Debug Command Options\n\n| Option | Description               | Default | Alias |\n| ------ | ------------------------- | ------- | ----- |\n| --json | Output debug info as JSON | false   | none  |\n\n## Configuration (config.json)\n\n- **Location:** `~/.local/share/copilot-api/config.json` (Linux/macOS) or `%USERPROFILE%\\.local\\share\\copilot-api\\config.json` (Windows).\n- **Default shape:**\n  ```json\n  {\n    \"auth\": {\n      \"apiKeys\": [],\n      \"adminApiKey\": \"<auto-generated-on-startup>\"\n    },\n    \"providers\": {},\n    \"modelMappings\": {},\n    \"extraPrompts\": {\n      \"gpt-5-mini\": \"<built-in exploration prompt>\"\n    },\n    \"smallModel\": \"gpt-5-mini\",\n    \"useResponsesApiContextManagement\": true,\n    \"modelResponsesApiCompactThresholds\": {\n      \"gpt-5.4\": 217600,\n      \"gpt-5.5\": 217600\n    },\n    \"modelReasoningEfforts\": {\n      \"gpt-5-mini\": \"low\"\n    },\n    \"useMessagesApi\": true,\n    \"useResponsesApiWebSocket\": true,\n    \"useResponsesApiWebSearch\": true,\n    \"messageApiWebSearchModel\": \"gpt-5-mini\"\n  }\n  ```\n- **auth.apiKeys:** API keys used for request authentication on non-admin routes. Supports multiple keys for rotation. Requests can authenticate with either `x-api-key: <key>` or `Authorization: Bearer <key>`. If empty or omitted, authentication for non-admin routes is disabled.\n- **auth.adminApiKey:** Single admin key used only for `/admin/*` routes. If missing, the server generates a random key at startup and writes it back to `config.json`. Requests use the same `x-api-key` or `Authorization: Bearer` headers, but regular `auth.apiKeys` never grant access to `/admin/*`.\n- **modelMappings:** Exact `sourceModel -> targetModel` rewrites shared by top-level `POST /v1/messages`, `POST /v1/messages/count_tokens`, `POST /v1/responses`, and `POST /v1/chat/completions` requests. Omit it or leave it as `{}` to disable rewrites. Both the source and target must be non-empty strings. Targets can be regular model IDs or `provider/model` aliases such as `dashscope/qwen3.6-plus`, and the rewrite happens before provider alias parsing. These mappings are not split per interface. The admin endpoints `GET/POST /admin/config/model-mappings` read and update only this field.\n- **extraPrompts:** Map of `model -> prompt` appended to the first system prompt when translating Anthropic-style requests to Responses API. Use this to inject guardrails or guidance per model. Missing default entries are auto-added without overwriting your custom prompts. For GPT-5.3+ models (e.g. `gpt-5.3-codex`, `gpt-5.4`, `gpt-5.5`), a built-in commentary prompt is used as fallback when not explicitly configured. The built-in prompts enable phase-aware commentary, which lets the model emit a short user-facing progress update before tools or deeper reasoning.\n- **providers:** Global upstream provider map. Each provider key (for example `dashscope`) becomes a route prefix (`/dashscope/v1/messages`). Supports `type: \"anthropic\"`, `type: \"openai-compatible\"`, and `type: \"openai-responses\"`. Top-level clients can also use `model: \"dashscope/model-id\"` with `/v1/messages`, `/v1/messages/count_tokens`, `/v1/responses`, and `/v1/chat/completions`; the gateway strips the `dashscope/` prefix before forwarding upstream. `openai-compatible` providers support both chat and Messages flows: `/v1/chat/completions` is proxied to upstream `/v1/chat/completions`, while `/v1/messages` and `/:provider/v1/messages` are translated to upstream chat completions and translated back to Anthropic Messages responses. `GET /v1/models` aggregates enabled provider models with `provider/model-id` IDs; use `GET /dashscope/v1/models` for a single provider's raw model list.\n  - `enabled` defaults to `true` if omitted.\n  - `baseUrl` should be provider API base URL without the final endpoint. For Anthropic providers, omit `/v1/messages`; for OpenAI-compatible providers, omit `/v1/chat/completions`; for OpenAI Responses providers, omit `/v1/responses`.\n  - `apiKey` is used as the upstream credential value and is required for regular providers.\n  - `authType` (optional): Controls how `apiKey` is sent upstream. Supports `x-api-key` and `authorization` for regular providers. Anthropic providers default to `x-api-key`; OpenAI-compatible and OpenAI Responses providers default to `authorization`. When set to `authorization`, the proxy sends `Authorization: Bearer <apiKey>`. `oauth2` is reserved for the built-in `codex` provider and is written automatically by `auth login --provider codex`.\n  - `pricingCurrency` (optional): Provider-level currency used for token cost calculation, for example `USD` or `CNY`. Quick providers default to `CNY` for DashScope and DeepSeek, and `USD` for Codex/OpenRouter. Costs are grouped by currency and are not exchange-rate converted.\n  - `models` (optional): Per-model configuration map. Each key is a model ID (matching the model name in requests), and the value is:\n    - `temperature` (optional): Default temperature value used when the request does not specify one.\n    - `topP` (optional): Default top_p value used when the request does not specify one.\n    - `topK` (optional): Default top_k value used when the request does not specify one.\n    - `extraBody` (optional): Dynamic fields merged into the upstream request body for that model. Request body fields with the same name take precedence. OpenAI-compatible providers can use this for fields such as `enable_thinking`, `preserve_thinking`, `reasoning_effort`. `thinking_budget` is a special OpenAI-compatible provider override: when configured in `extraBody`, it is forced after Anthropic `thinking.budget_tokens` translation and overrides the request-derived budget. For providers whose name is `dashscope` or whose `baseUrl` contains `aliyuncs.com`, the request-derived `thinking_budget` (from Anthropic `thinking.budget_tokens`) is forwarded upstream; for other OpenAI-compatible providers the request-derived `thinking_budget` is stripped, while an `extraBody` `thinking_budget` is still honored. For DashScope providers, `preserve_thinking` defaults to `true` when not explicitly set in `extraBody` or the request body.\n    - `pricing` (optional): Per-model token prices, in the provider `pricingCurrency`, per 1M tokens. Supported fields are `input`, `output`, `cachedInput` (implicit cache read), `explicitCachedInput` (explicit cache read), and `cacheCreationInput`. Use `tiers` with `maxInputTokens` for input-size tiered pricing.\n    - `contextCache` (optional): Defaults to `true` for providers whose name is `dashscope` or whose `baseUrl` contains `aliyuncs.com`; defaults to `false` for other OpenAI-compatible providers. This enables Alibaba Cloud Model Studio/DashScope explicit context cache by injecting `cache_control: { \"type\": \"ephemeral\" }` on up to 4 content blocks using the Context Cache format. The cache breakpoint strategy matches opencode's main provider flow: the first 2 system messages plus the last 2 non-system messages. Marked string content is converted to text content part arrays for `system` / `user` / `assistant` / `tool` messages; existing array content is marked on the last part. Set this to `false` when the model already supports implicit caching, or when the upstream does not accept this explicit-cache extension field. Set this to `true` for non-DashScope providers that support the same explicit-cache extension. Applied on both `/v1/messages` and `/v1/chat/completions` routes.\n    - `supportPdf` (optional): Controls whether the model supports PDF/document content. Defaults to `false`; unsupported PDFs are converted to a text notice. Set it to `true` to send PDF/document blocks as OpenAI Chat Completions file parts.\n    - `toolContentSupportType` (optional): Tool result content capabilities for that model, as an array of `array`, `image`, and `pdf`. Provider routes default to string-only tool content when omitted. If `supportPdf` is `true` but this list does not include `pdf`, file parts in tool results are moved to user role messages. This provider default does not change the Copilot main flow, which continues to support array + image and not PDF.\n    - `type` (optional): Per-model override of the provider protocol type. Supports `anthropic`, `openai-compatible`, and `openai-responses`. When set, the provider's `/v1/messages` route uses this model's type instead of the provider-level type for request routing, auth header resolution, and upstream endpoint selection. This is useful for providers like OpenCode Go whose upstream supports both OpenAI-compatible and Anthropic Messages APIs for different models. When the type is overridden, the auth header is resolved from the overridden type's default (Anthropic defaults to `x-api-key`; OpenAI-compatible/Responses default to `authorization`).\n\n  Example DashScope model settings:\n  ```json\n  {\n    \"providers\": {\n      \"dashscope\": {\n        \"type\": \"openai-compatible\",\n        \"enabled\": true,\n        \"baseUrl\": \"https://dashscope.aliyuncs.com/compatible-mode\",\n        \"apiKey\": \"sk-your-dashscope-key\",\n        \"pricingCurrency\": \"CNY\",\n        \"models\": {\n          \"qwen3.7-plus\": {\n            \"temperature\": 1,\n            \"topP\": 0.95,\n            \"topK\": 20,\n            \"extraBody\": {\n              \"preserve_thinking\": true\n            }\n          },\n          \"glm-5.1\": {\n            \"temperature\": 0.7,\n            \"topP\": 0.95,\n            \"contextCache\": true,\n            \"pricing\": {\n              \"tiers\": [\n                {\n                  \"maxInputTokens\": 32000,\n                  \"input\": 6,\n                  \"cachedInput\": 1.2,\n                  \"explicitCachedInput\": 0.6,\n                  \"cacheCreationInput\": 7.5,\n                  \"output\": 24\n                },\n                {\n                  \"maxInputTokens\": 200000,\n                  \"input\": 8,\n                  \"cachedInput\": 1.6,\n                  \"explicitCachedInput\": 0.8,\n                  \"cacheCreationInput\": 10,\n                  \"output\": 28\n                }\n              ]\n            },\n            \"extraBody\": {\n              \"preserve_thinking\": true\n            }\n          }\n        }\n      }\n    }\n  }\n  ```\n  Built-in token prices cover Codex GPT models in USD, DashScope `qwen3.7-max`, `qwen3.7-plus`, `glm-5.1`, `glm-5.2` in CNY, DeepSeek `deepseek-v4-flash`, `deepseek-v4-pro`, `deepseek-chat`, `deepseek-reasoner` in CNY, and OpenCode Go models (`glm-5.2`, `deepseek-v4-flash`, `deepseek-v4-pro`, `kimi-k2.7-code`, `mimo-v2.5`, `mimo-v2.5-pro`, `qwen3.7-plus`, `qwen3.7-max`, `minimax-m2.5`, `minimax-m3`) in USD. User `pricing` entries override built-ins. For DashScope, cached tokens are charged as explicit cache reads when the upstream usage includes `cache_creation_input_tokens`; otherwise `cachedInput` is used as the implicit cache read price. For DeepSeek, `prompt_cache_hit_tokens` map to cached input and `prompt_cache_miss_tokens` map to regular input.\n- **smallModel:** Fallback model used for tool-less warmup messages (e.g., Claude Code probe requests); defaults to gpt-5-mini.\n- **useResponsesApiContextManagement:** When `true`, the proxy adds Responses API `context_management` compaction instructions. Defaults to `true`. Set it to `false` to disable this globally. When enabled, the request includes `context_management` in the body and keeps only the latest compaction carrier on follow-up turns. This is especially useful for long-running tasks.\n- **modelResponsesApiCompactThresholds:** Per-model Responses API `compact_threshold` overrides used when the proxy adds `context_management`. These values take precedence over the fallback threshold from `resolveResponsesCompactThreshold` (`max_prompt_tokens * ratio`, or the default fallback). Defaults set `gpt-5.4` and `gpt-5.5` to `217600` (`272000 * 0.8`). Models not listed continue to use the normal fallback logic.\n- **modelReasoningEfforts:** Per-model `reasoning.effort` sent to the Responses API. Allowed values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. If a model isn't listed, `high` is used by default; GPT-5.3+ models fall back to `xhigh` when not explicitly configured.\n- **useMessagesApi:** When `true`, Claude-family models that support Copilot's native `/v1/messages` endpoint will use the Messages API; otherwise they fall back to `/chat/completions`. Set to `false` to disable Messages API routing and always use `/chat/completions`. Defaults to `true`.\n- **useResponsesApiWebSocket:** When `true`, Responses API requests use Copilot's websocket transport for models that advertise `ws:/responses`; models that only advertise `/responses` continue to use HTTP. Set to `false` to disable websocket routing and use HTTP `/responses` whenever the selected model supports it. Defaults to `true`.\n- **useResponsesApiWebSearch:** When `true`, the server keeps Responses API tools with `type: \"web_search\"` and forwards them upstream. Set to `false` to strip those tools from `/responses` payloads. Defaults to `true`.\n- **messageApiWebSearchModel:** Global fallback model used when a top-level Copilot `/v1/messages` request contains only the server-side `web_search` tool. Defaults to `gpt-5-mini`. If the value is a `provider/model` alias, the request is routed into that provider's Messages API path with the provider prefix stripped. For Copilot GPT models, web search runs through `/responses`. Mixed `web_search` plus custom tools are not supported and the server-side `web_search` tool is stripped.\n- **claudeTokenMultiplier:** Multiplier applied to the fallback GPT-tokenizer estimate for Claude `/v1/messages/count_tokens` requests. Defaults to `1.15`. Increase it if your client is still compacting too late. This setting is only used when the proxy is estimating Claude tokens locally; if `anthropicApiKey` is configured and Anthropic token counting succeeds, the exact Anthropic count is returned instead.\n- **anthropicApiKey:** Anthropic API key used to forward Claude `/v1/messages/count_tokens` requests to Anthropic's real token counting endpoint, which returns exact counts instead of GPT tokenizer estimates. Can also be set via the `ANTHROPIC_API_KEY` environment variable. If not set, or if the upstream call fails, token counting falls back to local GPT tokenizer estimation controlled by `claudeTokenMultiplier`.\n\nEdit this file to customize prompts or swap in your own fast model. Restart the server (or rerun the command) after changes so the cached config is refreshed.\n\n## API Authentication\n\n- **Protected non-admin routes:** All routes except `/`, `/usage-viewer`, and `/usage-viewer/` require authentication when `auth.apiKeys` is configured and non-empty.\n- **Admin routes:** All `/admin/*` routes require `auth.adminApiKey`. If it is missing, the server generates one at startup and persists it to `config.json` before serving requests.\n- **Allowed auth headers:**\n  - `x-api-key: <your_key>`\n  - `Authorization: Bearer <your_key>`\n- **CORS preflight:** `OPTIONS` requests are always allowed.\n- **When no regular keys are configured:** Non-admin routes continue to allow requests. This does not apply to `/admin/*`, which only accepts `auth.adminApiKey`.\n\nExample request for a regular protected route:\n\n```sh\ncurl http://localhost:4141/v1/models \\\n  -H \"x-api-key: your_api_key\"\n```\n\nExample request for an admin route:\n\n```sh\ncurl http://localhost:4141/admin/config/model-mappings \\\n  -H \"x-api-key: your_admin_api_key\"\n```\n\n## API Endpoints\n\nThe server exposes several OpenAI- and Anthropic-compatible endpoints. Requests can target GitHub Copilot, the built-in `codex` provider, or configured providers depending on the selected model and `provider/model` alias.\n\n### OpenAI Compatible Endpoints\n\nThese endpoints mimic the OpenAI API structure.\n\n| Endpoint                    | Method | Description                                                      |\n| --------------------------- | ------ | ---------------------------------------------------------------- |\n| `POST /v1/responses`        | `POST` | OpenAI Most advanced interface for generating model responses. Supports `provider/model` aliases for `openai-responses` providers. |\n| `POST /v1/chat/completions` | `POST` | Creates a model response for the given chat conversation. Supports `provider/model` aliases for `openai-compatible` providers and can be used without Copilot when the target provider is configured. |\n| `GET /v1/models`            | `GET`  | Lists Copilot models plus enabled provider models using `provider/model-id` IDs. |\n| `POST /v1/embeddings`       | `POST` | Creates an embedding vector representing the input text.         |\n\n### Anthropic Compatible Endpoints\n\nThese endpoints are designed to be compatible with the Anthropic Messages API.\n\n| Endpoint                         | Method | Description                                                  |\n| -------------------------------- | ------ | ------------------------------------------------------------ |\n| `POST /v1/messages`              | `POST` | Creates a model response for a given conversation. Supports `provider/model` aliases for configured providers, including translation through `openai-compatible` providers. |\n| `POST /v1/messages/count_tokens` | `POST` | Calculates the number of tokens for a given set of messages. Supports `provider/model` aliases for configured providers. |\n| `POST /:provider/v1/messages`       | `POST` | Proxies Anthropic Messages requests to the configured Anthropic provider, translates them through an OpenAI-compatible provider, or translates them through an OpenAI Responses provider. |\n| `GET /:provider/v1/models`          | `GET`  | Proxies model listing requests to the configured provider.   |\n| `POST /:provider/v1/messages/count_tokens` | `POST` | Calculates tokens locally for provider route requests. |\n\n### Usage Monitoring Endpoints\n\nNew endpoints for monitoring your Copilot usage and quotas.\n\n| Endpoint     | Method | Description                                                  |\n| ------------ | ------ | ------------------------------------------------------------ |\n| `GET /usage` | `GET`  | Get detailed Copilot usage statistics and quota information. |\n| `GET /token` | `GET`  | Get the current Copilot token being used by the API.         |\n\n### Admin / Configuration Endpoints\n\nThese endpoints are reserved for local administrative actions and only accept `auth.adminApiKey`.\n\n| Endpoint                              | Method | Description                                                                 |\n| ------------------------------------- | ------ | --------------------------------------------------------------------------- |\n| `GET /admin/config/model-mappings`    | `GET`  | Returns the current `config.json` path and the active `modelMappings` map.  |\n| `POST /admin/config/model-mappings`   | `POST` | Updates only the `modelMappings` field in `config.json` and returns it back. |\n\n## Example Usage\n\nCommon `npx` commands:\n\n```sh\n# Start the gateway\nnpx @jeffreycao/copilot-api@latest start\n\n# Start on a custom port with verbose logging\nnpx @jeffreycao/copilot-api@latest start --port 8080 --verbose\n\n# Run the auth flow\nnpx @jeffreycao/copilot-api@latest auth login\n\n# Configure a third-party provider, then run without GitHub Copilot\nnpx @jeffreycao/copilot-api@latest auth login --provider dashscope\nnpx @jeffreycao/copilot-api@latest start\n\n# Print debug information as JSON\nnpx @jeffreycao/copilot-api@latest debug --json\n\n# Run the published CLI with Bun instead of Node.js\nbunx --bun @jeffreycao/copilot-api@latest start\n```\n\nOpenAI-compatible provider examples after configuring `dashscope`:\n\n```sh\ncurl http://localhost:4141/v1/chat/completions \\\n  -H \"content-type: application/json\" \\\n  -d '{\"model\":\"dashscope/qwen3.6-plus\",\"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]}'\n\ncurl http://localhost:4141/dashscope/v1/messages \\\n  -H \"content-type: application/json\" \\\n  -d '{\"model\":\"qwen3.6-plus\",\"max_tokens\":1024,\"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]}'\n```\n\n## Usage Tips\n\n### CLAUDE.md or AGENTS.md Recommended Content\n\nTo add these reminders manually, include the following in `CLAUDE.md` for Claude Code, or `AGENTS.md` for opencode/codex:\n\n```\n- Prohibited from directly asking questions to users, MUST use question tool.\n- Once you can confirm that the task is complete, MUST use question tool to make user confirm. The user may respond with feedback if they are not satisfied with the result, which you can use to make improvements and try again, after try again, MUST use question tool to make user confirm again.\n```\n"}, "46c3efbc6646393435b69af72cbed24d81ddfcfd": {"t": 1785765573.2034304, "n": 46309, "h": "e89ee9e1671c5c24", "c": "# Copilot API Proxy\n\nEnglish | [简体中文](./README.zh-CN.md)\n\n## Important Notes\n\n> [!IMPORTANT]\n> **Before using, please be aware of the following:**\n>\n> 1. **Claude Code configuration:** When using with Claude Code, please configure the model ID as `claude-opus-4-8`. Example claude `settings.json` see [Manual Configuration with `settings.json`](#manual-configuration-with-settingsjson). \n>\n> 2. **Built-in `copilot`, `codex` and third-party providers:** Run `npx @jeffreycao/copilot-api@latest auth` and choose `copilot`, `codex`, `deepseek`, `custom`, or other providers.\n>\n> 3. **Note:** See [GitHub Copilot Security Notice](./NOTICE.md#github-copilot-security-notice) for the warning removed from the README header.\n\n---\n\n## Project Overview\n\nA small AI gateway that can use GitHub Copilot, the built-in `codex` provider, or configured third-party providers such as DashScope. GitHub Copilot is optional: if no GitHub token is available, the server can still start in provider-only mode as long as at least one enabled provider is configured.\n\nThe gateway exposes OpenAI- and Anthropic-compatible APIs from one local endpoint, so tools like [Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview), OpenCode, Codex, and OpenAI-compatible clients can share the same local server.\n\nOn the GitHub Copilot path, the gateway prefers Copilot's native Anthropic-style Messages API when available, preserving more Claude-native behavior for tool-heavy workflows.\n\n## Features\n\n- **OpenAI and Anthropic compatibility**: Serve `/v1/responses`, `/v1/chat/completions`, `/v1/models`, `/v1/embeddings`, and `/v1/messages` from one local gateway.\n- **Copilot is optional**: Use GitHub Copilot when credentials are present, or run the server with only configured providers.\n- **One gateway for Copilot, `codex`, and external providers**: Route GitHub Copilot, the built-in `codex` provider, and configured third-party providers behind the same endpoint.\n- **Standalone third-party providers**: Configure providers such as DashScope, DeepSeek, OpenRouter, or a custom provider and start the gateway without a GitHub Copilot login.\n- **OpenAI-compatible providers on chat and Messages APIs**: `openai-compatible` providers can serve top-level `/v1/chat/completions` through `model: \"provider/model\"` and Anthropic-style `/v1/messages` through request/response translation.\n- **Agent-friendly Claude handling on Copilot**: Prefer native `/v1/messages` when available, preserve Claude-style tool flows, support Anthropic beta features, Claude WebSearch through Responses-capable models, and keep subagent/session markers intact.\n- **Claude Code and OpenCode integration**: Works with Claude Code and OpenCode, including direct Anthropic-compatible usage through `@ai-sdk/anthropic`.\n- **Flexible auth and deployment options**: Supports interactive login or direct tokens, individual/business/enterprise plans, GitHub Enterprise, opencode OAuth, and custom data directories.\n- **Multi-provider routing**: Expose provider-specific `/:provider/...` routes or use `model: \"provider/model\"` on the top-level API.\n\n## Prerequisites\n\n- Bun (>= 1.2.x)\n- Node.js if you plan to run the published CLI with `npx`\n- GitHub account with Copilot subscription only if you want to use the GitHub Copilot provider\n- An API key or OAuth login for at least one configured provider if you want to run without GitHub Copilot\n\n## Installation\n\nTo install dependencies, run:\n\n```sh\nbun install\n```\n\nTo start the server directly from source:\n\n```sh\nbun run start start\n```\n\n## Running from Source\n\nThe project can be run from source in several ways:\n\n### Development Mode\n\n```sh\nbun run dev start\n```\n\n### Production Mode\n\n```sh\nbun run start start\n```\n\n## Using with npx\n\nYou can run the project directly using npx:\n\n> [!IMPORTANT]\n> Token usage storage uses Node's built-in `node:sqlite` module when running with `npx`. It is enabled on Node.js >= 22.13.0. On Node.js < 22.13.0, the CLI still starts, but token usage storage is disabled.\n>\n> If you want token usage storage without upgrading Node.js, run the published CLI with Bun instead: `bunx --bun @jeffreycao/copilot-api@latest start`.\n\n```sh\nnpx @jeffreycao/copilot-api@latest start\n```\n\nWith options:\n\n```sh\nnpx @jeffreycao/copilot-api@latest start --port 8080\n```\n\nFor authentication or provider configuration only:\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth\n```\n\nTo run without GitHub Copilot, configure at least one provider first, then start the server normally:\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth login --provider dashscope\nnpx @jeffreycao/copilot-api@latest start\n```\n\n## Using with Docker\n\nBuild the image:\n\n```sh\ndocker build -t copilot-api .\n```\n\nRun the container with a bind mount so auth data survives restarts:\n\n```sh\nmkdir -p ./copilot-data\ndocker run -p 4141:4141 -v $(pwd)/copilot-data:/root/.local/share/copilot-api copilot-api\n```\n\nThis stores GitHub auth data, provider config, and other gateway state in `./copilot-data` on the host, mapped to `/root/.local/share/copilot-api` in the container.\n\nOr pass a GitHub token directly:\n\n```sh\ndocker run -p 4141:4141 -e GH_TOKEN=your_github_token_here copilot-api\n```\n\n## Electron Desktop App\n\nIf you prefer a GUI, this repository also includes an Electron desktop app in `desktop/`. It supports GitHub Copilot sign-in, OpenAI Codex OAuth, and API-key configuration for DeepSeek, DashScope, OpenRouter, or a custom provider. After authorization or provider configuration, it can start and stop the local proxy with one click and shows the local endpoint, auth header, available models, usage, and logs in the app.\n\nThe settings screen also exposes `OAuth App`, `API Home`, `Enterprise URL`, verbose logging, and minimize-to-tray. Desktop packages are published in GitHub Releases:\n\nhttps://github.com/caozhiyuan/copilot-api/releases\n\nDownload the installer for your platform, authorize or configure a provider inside the app, choose a port, start the server, then point your client at the local endpoint shown in the app. Packaged desktop builds use the bundled Electron runtime, so normal desktop usage does not require installing Node.js separately. Token usage history is enabled when that bundled runtime supports SQLite.\n\nThe desktop app's Advanced Config page reads and writes the shared model mappings through `GET/POST /admin/config/model-mappings`. The same mappings apply across `POST /v1/messages`, `POST /v1/messages/count_tokens`, `POST /v1/responses`, and `POST /v1/chat/completions` instead of being split per interface. It uses `auth.adminApiKey` instead of the regular `auth.apiKeys`, and the app reads that key directly from `config.json` after the server has generated it on startup.\n\n### Desktop App Screenshots\n\nMain dashboard, token usage breakdown in the bundled Electron app:\n\n<p align=\"center\">\n  <img src=\"./docs/screenshots/desktop-dashboard.png\" alt=\"Copilot API desktop app dashboard\" width=\"49%\" />\n  <img src=\"./docs/screenshots/desktop-token-usage.png\" alt=\"Copilot API desktop app token usage view\" width=\"49%\" />\n</p>\n\n## Using with Claude Code\n\nThis AI gateway can be used to power [Claude Code](https://docs.anthropic.com/en/claude-code), an experimental conversational AI assistant for developers from Anthropic.\n\nThere are two ways to configure Claude Code to use this AI gateway:\n\n### Interactive Setup with `--claude-code` flag\n\nTo get started, run the `start` command with the `--claude-code` flag:\n\n```sh\nnpx @jeffreycao/copilot-api@latest start --claude-code\n```\n\nYou will be prompted to select a primary model and a \"small, fast\" model for background tasks. After selecting the models, a command will be copied to your clipboard. This command sets the necessary environment variables for Claude Code to use the gateway.\n\nPaste and run this command in a new terminal to launch Claude Code.\n\n### Manual Configuration with `settings.json`\n\nAlternatively, you can configure Claude Code by creating a `.claude/settings.json` file in your project's root directory. This file should contain the environment variables needed by Claude Code. This way you don't need to run the interactive setup every time.\n\nHere is an example `.claude/settings.json` file:\n\n```json\n{\n  \"env\": {\n    \"ANTHROPIC_BASE_URL\": \"http://localhost:4141\",\n    \"ANTHROPIC_AUTH_TOKEN\": \"dummy\",\n    \"ANTHROPIC_MODEL\": \"deepseek/deepseek-v4-pro\",\n    \"ANTHROPIC_DEFAULT_SONNET_MODEL\": \"deepseek/deepseek-v4-pro\",\n    \"ANTHROPIC_DEFAULT_HAIKU_MODEL\": \"deepseek/deepseek-v4-flash\",\n    \"DISABLE_NON_ESSENTIAL_MODEL_CALLS\": \"1\",\n    \"CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC\": \"1\",\n    \"CLAUDE_CODE_ATTRIBUTION_HEADER\": \"0\",\n    \"CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION\": \"false\",\n    \"CLAUDE_CODE_DISABLE_TERMINAL_TITLE\": \"true\",\n    \"CLAUDE_CODE_ENABLE_AWAY_SUMMARY\": \"0\"\n  },\n  \"permissions\": {\n    \"deny\": [\n      \"mcp__ide__executeCode\"\n    ]\n  }\n}\n```\n\n- Replace `ANTHROPIC_MODEL`, `ANTHROPIC_DEFAULT_OPUS_MODEL`, `ANTHROPIC_DEFAULT_SONNET_MODEL`, and `ANTHROPIC_DEFAULT_HAIKU_MODEL` according to your needs. After configuration, please install the claude code plugin [Plugin Integrations](#plugin-integrations).  \n- Setting CLAUDE_CODE_ATTRIBUTION_HEADER to 0 can prevent Claude code from adding billing and version information in system prompts, thereby avoiding prompt cache invalidation.\n- Turning off CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION and CLAUDE_CODE_ENABLE_AWAY_SUMMARY can prevent quota from being consumed unnecessarily.\n- Claude Code WebSearch is supported for pure search requests. For Copilot, keep the global `messageApiWebSearchModel` set to a Responses-capable GPT model or a `provider/model` alias. For provider routes, use a native Anthropic provider or an `openai-responses` provider. Add `WebSearch` to `permissions.deny` only if you want to forbid this traffic.\n- If using a non-Claude model, do not enable ENABLE_TOOL_SEARCH. If using the Claude model, can enable ENABLE_TOOL_SEARCH. The current Claude Code uses the client tool search mode. In this mode, loading defer tools requires an additional request each time.\n- `CLAUDE_CODE_AUTO_COMPACT_WINDOW`: Set the context capacity in tokens used for auto-compaction calculations. Defaults to the model's context window: 200K for standard models or 1M for extended context models. Use a lower value like `500000` on a 1M model (e.g., `claude-opus-4-6[1m]`) to treat the window as 500K for compaction purposes. The value is capped at the model's actual context window. `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` is applied as a percentage of this value. Setting this variable decouples the compaction threshold from the status line's `used_percentage`, which always uses the model's full context window.\n\nYou can find more options here: [Claude Code settings](https://docs.anthropic.com/en/docs/claude-code/settings#environment-variables)\n\nYou can also read more about IDE integration here: [Add Claude Code to your IDE](https://docs.anthropic.com/en/docs/claude-code/ide-integrations)\n\n## Using with OpenCode\n\nOpenCode already has a direct GitHub Copilot provider. Use this section when you want OpenCode to point at this AI gateway through `@ai-sdk/anthropic` and reuse the agent behaviors described earlier in this README.\n\n### Minimal setup\n\nStart the AI gateway with the OpenCode OAuth app:\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth --oauth-app=opencode\nnpx @jeffreycao/copilot-api@latest start\n```\n\nThen point OpenCode at the gateway with `@ai-sdk/anthropic`.\n\nExample `~/.config/opencode/opencode.json`:\n\n```json\n{\n  \"$schema\": \"https://opencode.ai/config.json\",\n  \"provider\": {\n    \"local\": {\n      \"npm\": \"@ai-sdk/anthropic\",\n      \"name\": \"My Local\",\n      \"options\": {\n        \"baseURL\": \"http://localhost:4141/v1\",\n        \"apiKey\": \"dummy\"\n      },\n      \"models\": {\n        \"gpt-5.4\": {\n          \"name\": \"gpt-5.4\",\n          \"modalities\": {\n            \"input\": [\"text\", \"image\"],\n            \"output\": [\"text\"]\n          },\n          \"limit\": {\n            \"context\": 300000,\n            \"output\": 128000\n          }\n        },\n        \"claude-sonnet-4.6\": {\n          \"id\": \"claude-sonnet-4.6\",\n          \"name\": \"claude-sonnet-4.6\",\n          \"modalities\": {\n            \"input\": [\"text\", \"image\"],\n            \"output\": [\"text\"]\n          },          \n          \"limit\": {\n            \"context\": 200000,\n            \"output\": 32000\n          },\n          \"options\": {\n            \"thinking\": {\n              \"type\": \"adaptive\"\n            },\n            \"effort\": \"max\"\n          }\n        }\n      }\n    }\n  }\n}\n```\n\nWhy these fields matter:\n\n- `npm: \"@ai-sdk/anthropic\"` is the important part. OpenCode will speak Anthropic Messages semantics to this AI gateway instead of flattening everything into OpenAI Chat Completions.\n- `options.baseURL` should be `http://localhost:4141/v1`; the Anthropic SDK will append `/messages`, `/models`, and `/messages/count_tokens` automatically.\n- If you enable `auth.apiKeys` in this AI gateway, replace `dummy` with a real key. Otherwise any placeholder value is fine.\n\n## Using with Codex\n\nThis AI gateway can also power Codex.\n\n### Codex `config.toml` Reference\n\nAdd the following `[model_providers.copilot_api]` section to your Codex `~/.codex/config.toml`:\n\n```toml\nmodel_provider = \"copilot_api\"\nmodel_reasoning_summary = \"auto\"\nmodel_verbosity = \"medium\"\nmodel_context_window = 272000\nmodel_auto_compact_token_limit = 244800\n\n[model_providers.copilot_api]\nname = \"OpenAI\"\nbase_url = \"http://localhost:4141\"\nenv_key = \"GITHUB_COPILOT_API_KEY\"\nrequires_openai_auth = true\nsupports_websockets = false\nwire_api = \"responses\"\nrequest_max_retries = 3\nstream_max_retries = 1\nstream_idle_timeout_ms = 300000\n\n[features]\nremote_compaction_v2 = true\n\n[analytics]\nenabled = false\n```\n\n> [!NOTE]\n> This configuration is specific to Codex and the GitHub Copilot provider. `name` must be set to `\"OpenAI\"`. It can help mitigate Codex local compact cache miss issues. If you have enabled `useResponsesApiContextManagement` (Responses API context management compaction), `remote_compaction_v2` or local compact is generally not triggered, but it may still occur when tool results return a large number of tokens.\n\n## GPT Tool Search\n\nFor GPT Responses models such as `gpt-5.4+`, this AI gateway can expose Responses `tool_search` through a small MCP bridge. The same bridge can be used by Claude Code and opencode, as long as the client loads MCP servers and sends Anthropic Messages traffic through this gateway.\n\nDo not set Claude Code's native `ENABLE_TOOL_SEARCH` for GPT models. That flag enables Claude Code's own client-side tool search mode, and it may stop forwarding deferred tool definitions. This gateway needs the full tool definitions so it can keep the small always-loaded tool set eager and translate every other tool into Responses deferred namespaces.\n\nIf you install `tool-search@copilot-api-marketplace`, Claude Code receives this MCP bridge automatically and you can skip the manual Claude Code MCP setup below.\n\nAdd the tool search bridge to the MCP config used by Claude Code:\n\n```json\n{\n  \"mcpServers\": {\n    \"tool_search\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@jeffreycao/copilot-api@latest\", \"mcp\"]\n    }\n  }\n}\n```\n\nAdd the tool search bridge to the MCP config used by opencode:\n\n```json\n{\n  \"mcp\": {\n    \"tool_search\": {\n      \"type\": \"local\",\n      \"command\": [\"npx\", \"-y\", \"@jeffreycao/copilot-api@latest\", \"mcp\"]\n    }\n  }\n}\n```\n\nFor local development, use `bun` as the command and `[\"run\", \"./src/main.ts\", \"mcp\"]` as the args.\n\nInternally, the gateway now configures OpenAI Responses `tool_search` in client-executed mode. Deferred tools are still exposed as searchable namespaces, but the model is explicitly asked to return the exact deferred tool names it wants to load next.\n\nThe bridge uses direct tool selection, not query search. Its tool input is `names`, a comma-separated list of exact deferred tool names, for example `TaskList,TaskGet,mcp__fetch__fetch`.\n\n## Plugin Integrations\n\nPlugin integrations are available for Claude Code and opencode.\n\n#### Claude Code plugin integration (marketplace-based)\n\nThe Claude Code integration is packaged as two plugins:\n\n- `agent-inject` injects `__SUBAGENT_MARKER__...` on `SubagentStart`, so the gateway can infer `x-initiator: agent`.\n- `tool-search` registers the `tool_search` MCP bridge used for GPT Responses deferred tool loading.\n\n- Marketplace catalog in this repository: `.claude-plugin/marketplace.json`\n- Plugin sources in this repository: `plugin/claude/agent-inject`, `plugin/claude/tool-search`\n\nAdd the marketplace remotely:\n\n```sh\n/plugin marketplace add https://github.com/caozhiyuan/copilot-api.git\n```\n\nInstall the plugins from the marketplace:\n\n```sh\n/plugin install agent-inject@copilot-api-marketplace\n/plugin install tool-search@copilot-api-marketplace\n```\n\nAfter installation, `agent-inject` injects `__SUBAGENT_MARKER__...` on `SubagentStart`, and the gateway uses it to infer `x-initiator: agent`.\n\nThe `agent-inject` plugin also registers a `UserPromptSubmit` hook that returns `{\"continue\": true}`, and it can inject `SessionStart` reminder rules through environment variables:\n\n- `CLAUDE_PLUGIN_ENABLE_QUESTION_RULES=1` enables the two reminders about using the `question` tool automatically for Claude Code. Alternatively, you can add the same reminders manually in `CLAUDE.md`; see [CLAUDE.md or AGENTS.md Recommended Content](#claudemd-or-agentsmd-recommended-content).\n- `CLAUDE_PLUGIN_ENABLE_NO_BACKGROUND_AGENTS_RULE=1` enables the `run_in_background: true` avoidance reminder for agent hooks.\n\nThe `tool-search` plugin bundles the same MCP bridge described in [GPT Tool Search](#gpt-tool-search), so Claude Code users do not need to add the `tool_search` server manually when they install that plugin.\n\n#### Opencode plugin\n\nThe subagent marker producer is packaged as an opencode plugin located at `plugin/opencode/subagent-marker.js`.\n\n**Installation:**\n\nCopy the plugin file to your opencode plugins directory:\n\n```sh\n# Clone or download this repository, then copy the plugin\ncp plugin/opencode/subagent-marker.js ~/.config/opencode/plugins/\n```\n\nOr manually create the file at `~/.config/opencode/plugins/subagent-marker.js` with the plugin content.\n\n**Features:**\n\n- Tracks sub-sessions created by subagents\n- Automatically prepends a marker system reminder (`__SUBAGENT_MARKER__...`) to subagent chat messages\n- Sets `x-session-id` header for session tracking\n- Enables the gateway to infer `x-initiator: agent` for subagent-originated requests\n\nThe plugin hooks into `session.created`, `session.deleted`, `chat.message`, and `chat.headers` events to provide seamless subagent marker functionality.\n\n## Using the Usage Viewer\n\nAfter starting the server, a URL to the Copilot Usage Dashboard will be displayed in your console. This dashboard is a web interface for monitoring your API usage.\n\n1.  Start the server. For example, using npx:\n    ```sh\n    npx @jeffreycao/copilot-api@latest start\n    ```\n2.  The server will output a URL to the usage viewer. Copy and paste this URL into your browser. It will look something like this:\n    `http://localhost:4141/usage-viewer?endpoint=http://localhost:4141/usage`\n    - If you use the `start.bat` script on Windows, this page will open automatically.\n\nThe dashboard provides a user-friendly interface to view your Copilot usage data:\n\n> Token usage history requires Bun or Node.js >= 22.13.0. On Node.js < 22.13.0, the server runs normally but token usage storage is disabled.\n\n- **API Endpoint URL**: The dashboard is pre-configured to fetch data from your local server endpoint via a URL query parameter. You can manually switch this to any other compatible API endpoint.\n- **x-api-key Authentication**: If API Key authentication is enabled, you can provide the `x-api-key` request header. The key is persisted in the browser's local storage.\n- **Period Selector**: Choose from Day, Week, or Month time ranges. The URL query parameter updates automatically when you switch, making it easy to bookmark and share.\n- **Fetch Data**: Click the \"Refresh\" button to load or refresh the usage data. The dashboard also fetches data automatically on page load.\n- **Copilot Quotas**: View quota usage for services such as Chat and Completions via progress bars. Hover over a card to see used/remaining details.\n- **Token Usage Metric Cards**: See a summary of Total, Input, Output, Cache Read, Cache Write, Requests, and estimated cost for the current period.\n- **Trend Chart (Week / Month)**: An interactive line chart with model and metric filters. Click a data point to inspect the usage breakdown for a specific day.\n- **Model Breakdown Table**: A per-model summary of requests, input/output/cache tokens, and estimated cost for the selected period.\n- **Request Events (Paginated)**: A time-sorted list of request event records with pagination support, showing timestamps, models, request IDs, and token counts.\n- **Detailed Information**: See the full JSON response from the API for a detailed breakdown of all available usage statistics.\n- **URL-based Configuration**: You can also specify the API endpoint and period directly via `endpoint` and `period` query parameters. For example:\n  `http://localhost:4141/usage-viewer?endpoint=http://your-api-server/usage&period=week`\n\n### Usage Viewer Screenshot\n\n<p align=\"center\">\n  <img src=\"./docs/screenshots/usage-viewer.png\" alt=\"Copilot API usage viewer\" width=\"900\" />\n</p>\n\n## Command Structure\n\nCopilot API now uses a subcommand structure with these main commands:\n\n- `start`: Start the gateway server. If a GitHub token is available, the server starts with Copilot enabled. If no GitHub token is available, it starts in provider-only mode when at least one enabled provider exists; otherwise it guides you through provider setup.\n- `auth`: Run provider login or configuration without starting the server. Use it for GitHub Copilot login, Codex OAuth, or third-party provider API key setup.\n- `debug`: Display diagnostic information including version, runtime details, file paths, and authentication status. Useful for troubleshooting and support.\n\n## Command Line Options\n\n### Global Options\n\nThe following options can be used with any subcommand. When passing them before the subcommand, use the `--key=value` form:\n\n| Option            | Description                                            | Default | Alias |\n| ----------------- | ------------------------------------------------------ | ------- | ----- |\n| --api-home        | Path to the API home directory (sets COPILOT_API_HOME) | none    | none  |\n| --oauth-app       | OAuth app identifier (sets COPILOT_API_OAUTH_APP)      | none    | none  |\n| --enterprise-url  | Enterprise URL for GitHub (sets COPILOT_API_ENTERPRISE_URL) | none | none |\n\n### Start Command Options\n\nThe following command line options are available for the `start` command:\n\n| Option         | Description                                                                   | Default    | Alias |\n| -------------- | ----------------------------------------------------------------------------- | ---------- | ----- |\n| --port         | Port to listen on                                                             | 4141       | -p    |\n| --verbose      | Enable verbose logging                                                        | false      | -v    |\n| --github-token | Provide GitHub token directly (must be generated using the `auth` subcommand) | none       | -g    |\n| --claude-code  | Generate a command to launch Claude Code with Copilot API config              | false      | -c    |\n| --show-token   | Show GitHub and Copilot tokens on fetch and refresh                           | false      | none  |\n| --proxy-env    | Initialize proxy from environment variables                                   | false      | none  |\n\n### Auth Command Options\n\n| Option       | Description               | Default | Alias |\n| ------------ | ------------------------- | ------- | ----- |\n| --provider   | Provider to log in with or configure (`copilot`, `codex`, `opencode-go`, `deepseek`, `dashscope`, `openrouter`, or `custom`) | prompt | none |\n| --verbose    | Enable verbose logging    | false   | -v    |\n| --show-token | Show GitHub token on auth | false   | none  |\n\nUse `copilot-api auth login --provider copilot` only when you want to enable the GitHub Copilot provider. Copilot is not required for `codex` or third-party provider-only usage.\n\nUse `copilot-api auth login --provider deepseek`, `--provider dashscope`, `--provider openrouter`, or `--provider opencode-go` to add or update those common third-party providers from the CLI. DeepSeek prompts for masked `apiKey`, provider `type` (default `anthropic`), and `baseUrl` defaulting to `https://api.deepseek.com/anthropic`. DashScope prompts for masked `apiKey`, provider `type` (default `openai-compatible`), and prefilled `baseUrl`. OpenRouter prompts for masked `apiKey` and prefilled `baseUrl` only, and writes `type: \"anthropic\"`. OpenCode Go prompts for masked `apiKey` and prefilled `baseUrl` only, and writes `type: \"openai-compatible\"` (baseUrl `https://opencode.ai/zen/go`). After a provider is configured and enabled, `copilot-api start` can run without any GitHub token.\n\nUse `copilot-api auth login --provider custom` to add or update another third-party provider from the CLI. The command prompts for the provider name, supported type (`anthropic`, `openai-compatible`, or `openai-responses`), `baseUrl`, masked `apiKey`, and `authType`; `authType` may be left as the type default or set to `x-api-key` / `authorization`.\n\n### Debug Command Options\n\n| Option | Description               | Default | Alias |\n| ------ | ------------------------- | ------- | ----- |\n| --json | Output debug info as JSON | false   | none  |\n\n## Configuration (config.json)\n\n- **Location:** `~/.local/share/copilot-api/config.json` (Linux/macOS) or `%USERPROFILE%\\.local\\share\\copilot-api\\config.json` (Windows).\n- **Default shape:**\n  ```json\n  {\n    \"auth\": {\n      \"apiKeys\": [],\n      \"adminApiKey\": \"<auto-generated-on-startup>\"\n    },\n    \"providers\": {},\n    \"modelMappings\": {},\n    \"extraPrompts\": {\n      \"gpt-5-mini\": \"<built-in exploration prompt>\",\n      \"gpt-5.3-codex\": \"<built-in commentary prompt>\",\n      \"gpt-5.4-mini\": \"<built-in commentary prompt>\",\n      \"gpt-5.4\": \"<built-in commentary prompt>\",\n      \"gpt-5.5\": \"<built-in commentary prompt>\"\n    },\n    \"smallModel\": \"gpt-5-mini\",\n    \"useResponsesApiContextManagement\": true,\n    \"modelResponsesApiCompactThresholds\": {\n      \"gpt-5.4\": 217600,\n      \"gpt-5.5\": 217600\n    },\n    \"modelReasoningEfforts\": {\n      \"gpt-5-mini\": \"low\",\n      \"gpt-5.3-codex\": \"xhigh\",\n      \"gpt-5.4-mini\": \"xhigh\",\n      \"gpt-5.4\": \"xhigh\",\n      \"gpt-5.5\": \"xhigh\"\n    },\n    \"useMessagesApi\": true,\n    \"useResponsesApiWebSocket\": true,\n    \"useResponsesApiWebSearch\": true,\n    \"messageApiWebSearchModel\": \"gpt-5-mini\"\n  }\n  ```\n- **auth.apiKeys:** API keys used for request authentication on non-admin routes. Supports multiple keys for rotation. Requests can authenticate with either `x-api-key: <key>` or `Authorization: Bearer <key>`. If empty or omitted, authentication for non-admin routes is disabled.\n- **auth.adminApiKey:** Single admin key used only for `/admin/*` routes. If missing, the server generates a random key at startup and writes it back to `config.json`. Requests use the same `x-api-key` or `Authorization: Bearer` headers, but regular `auth.apiKeys` never grant access to `/admin/*`.\n- **modelMappings:** Exact `sourceModel -> targetModel` rewrites shared by top-level `POST /v1/messages`, `POST /v1/messages/count_tokens`, `POST /v1/responses`, and `POST /v1/chat/completions` requests. Omit it or leave it as `{}` to disable rewrites. Both the source and target must be non-empty strings. Targets can be regular model IDs or `provider/model` aliases such as `dashscope/qwen3.6-plus`, and the rewrite happens before provider alias parsing. These mappings are not split per interface. The admin endpoints `GET/POST /admin/config/model-mappings` read and update only this field.\n- **extraPrompts:** Map of `model -> prompt` appended to the first system prompt when translating Anthropic-style requests to Copilot. Use this to inject guardrails or guidance per model. Missing default entries are auto-added without overwriting your custom prompts. The built-in prompts for `gpt-5.3-codex` and `gpt-5.4` enable phase-aware commentary, which lets the model emit a short user-facing progress update before tools or deeper reasoning.\n- **providers:** Global upstream provider map. Each provider key (for example `dashscope`) becomes a route prefix (`/dashscope/v1/messages`). Supports `type: \"anthropic\"`, `type: \"openai-compatible\"`, and `type: \"openai-responses\"`. Top-level clients can also use `model: \"dashscope/model-id\"` with `/v1/messages`, `/v1/messages/count_tokens`, `/v1/responses`, and `/v1/chat/completions`; the gateway strips the `dashscope/` prefix before forwarding upstream. `openai-compatible` providers support both chat and Messages flows: `/v1/chat/completions` is proxied to upstream `/v1/chat/completions`, while `/v1/messages` and `/:provider/v1/messages` are translated to upstream chat completions and translated back to Anthropic Messages responses. `GET /v1/models` aggregates enabled provider models with `provider/model-id` IDs; use `GET /dashscope/v1/models` for a single provider's raw model list.\n  - `enabled` defaults to `true` if omitted.\n  - `baseUrl` should be provider API base URL without the final endpoint. For Anthropic providers, omit `/v1/messages`; for OpenAI-compatible providers, omit `/v1/chat/completions`; for OpenAI Responses providers, omit `/v1/responses`.\n  - `apiKey` is used as the upstream credential value and is required for regular providers.\n  - `authType` (optional): Controls how `apiKey` is sent upstream. Supports `x-api-key` and `authorization` for regular providers. Anthropic providers default to `x-api-key`; OpenAI-compatible and OpenAI Responses providers default to `authorization`. When set to `authorization`, the proxy sends `Authorization: Bearer <apiKey>`. `oauth2` is reserved for the built-in `codex` provider and is written automatically by `auth login --provider codex`.\n  - `pricingCurrency` (optional): Provider-level currency used for token cost calculation, for example `USD` or `CNY`. Quick providers default to `CNY` for DashScope and DeepSeek, and `USD` for Codex/OpenRouter. Costs are grouped by currency and are not exchange-rate converted.\n  - `models` (optional): Per-model configuration map. Each key is a model ID (matching the model name in requests), and the value is:\n    - `temperature` (optional): Default temperature value used when the request does not specify one.\n    - `topP` (optional): Default top_p value used when the request does not specify one.\n    - `topK` (optional): Default top_k value used when the request does not specify one.\n    - `extraBody` (optional): Dynamic fields merged into the upstream request body for that model. Request body fields with the same name take precedence. OpenAI-compatible providers can use this for fields such as `enable_thinking`, `preserve_thinking`, `reasoning_effort`. `thinking_budget` is a special OpenAI-compatible provider override: when configured in `extraBody`, it is forced after Anthropic `thinking.budget_tokens` translation and overrides the request-derived budget. For providers whose name is `dashscope` or whose `baseUrl` contains `aliyuncs.com`, the request-derived `thinking_budget` (from Anthropic `thinking.budget_tokens`) is forwarded upstream; for other OpenAI-compatible providers the request-derived `thinking_budget` is stripped, while an `extraBody` `thinking_budget` is still honored. For DashScope providers, `preserve_thinking` defaults to `true` when not explicitly set in `extraBody` or the request body.\n    - `pricing` (optional): Per-model token prices, in the provider `pricingCurrency`, per 1M tokens. Supported fields are `input`, `output`, `cachedInput` (implicit cache read), `explicitCachedInput` (explicit cache read), and `cacheCreationInput`. Use `tiers` with `maxInputTokens` for input-size tiered pricing.\n    - `contextCache` (optional): Defaults to `true` for providers whose name is `dashscope` or whose `baseUrl` contains `aliyuncs.com`; defaults to `false` for other OpenAI-compatible providers. This enables Alibaba Cloud Model Studio/DashScope explicit context cache by injecting `cache_control: { \"type\": \"ephemeral\" }` on up to 4 content blocks using the Context Cache format. The cache breakpoint strategy matches opencode's main provider flow: the first 2 system messages plus the last 2 non-system messages. Marked string content is converted to text content part arrays for `system` / `user` / `assistant` / `tool` messages; existing array content is marked on the last part. Set this to `false` when the model already supports implicit caching, or when the upstream does not accept this explicit-cache extension field. Set this to `true` for non-DashScope providers that support the same explicit-cache extension. Applied on both `/v1/messages` and `/v1/chat/completions` routes.\n    - `supportPdf` (optional): Controls whether the model supports PDF/document content. Defaults to `false`; unsupported PDFs are converted to a text notice. Set it to `true` to send PDF/document blocks as OpenAI Chat Completions file parts.\n    - `toolContentSupportType` (optional): Tool result content capabilities for that model, as an array of `array`, `image`, and `pdf`. Provider routes default to string-only tool content when omitted. If `supportPdf` is `true` but this list does not include `pdf`, file parts in tool results are moved to user role messages. This provider default does not change the Copilot main flow, which continues to support array + image and not PDF.\n    - `type` (optional): Per-model override of the provider protocol type. Supports `anthropic`, `openai-compatible`, and `openai-responses`. When set, the provider's `/v1/messages` route uses this model's type instead of the provider-level type for request routing, auth header resolution, and upstream endpoint selection. This is useful for providers like OpenCode Go whose upstream supports both OpenAI-compatible and Anthropic Messages APIs for different models. When the type is overridden, the auth header is resolved from the overridden type's default (Anthropic defaults to `x-api-key`; OpenAI-compatible/Responses default to `authorization`).\n\n  Example DashScope model settings:\n  ```json\n  {\n    \"providers\": {\n      \"dashscope\": {\n        \"type\": \"openai-compatible\",\n        \"enabled\": true,\n        \"baseUrl\": \"https://dashscope.aliyuncs.com/compatible-mode\",\n        \"apiKey\": \"sk-your-dashscope-key\",\n        \"pricingCurrency\": \"CNY\",\n        \"models\": {\n          \"qwen3.7-plus\": {\n            \"temperature\": 1,\n            \"topP\": 0.95,\n            \"topK\": 20,\n            \"extraBody\": {\n              \"preserve_thinking\": true\n            }\n          },\n          \"glm-5.1\": {\n            \"temperature\": 0.7,\n            \"topP\": 0.95,\n            \"contextCache\": true,\n            \"pricing\": {\n              \"tiers\": [\n                {\n                  \"maxInputTokens\": 32000,\n                  \"input\": 6,\n                  \"cachedInput\": 1.2,\n                  \"explicitCachedInput\": 0.6,\n                  \"cacheCreationInput\": 7.5,\n                  \"output\": 24\n                },\n                {\n                  \"maxInputTokens\": 200000,\n                  \"input\": 8,\n                  \"cachedInput\": 1.6,\n                  \"explicitCachedInput\": 0.8,\n                  \"cacheCreationInput\": 10,\n                  \"output\": 28\n                }\n              ]\n            },\n            \"extraBody\": {\n              \"preserve_thinking\": true\n            }\n          }\n        }\n      }\n    }\n  }\n  ```\n  Built-in token prices cover Codex GPT models in USD, DashScope `qwen3.7-max`, `qwen3.7-plus`, `glm-5.1`, `glm-5.2` in CNY, DeepSeek `deepseek-v4-flash`, `deepseek-v4-pro`, `deepseek-chat`, `deepseek-reasoner` in CNY, and OpenCode Go models (`glm-5.2`, `deepseek-v4-flash`, `deepseek-v4-pro`, `kimi-k2.7-code`, `mimo-v2.5`, `mimo-v2.5-pro`, `qwen3.7-plus`, `qwen3.7-max`, `minimax-m2.5`, `minimax-m3`) in USD. User `pricing` entries override built-ins. For DashScope, cached tokens are charged as explicit cache reads when the upstream usage includes `cache_creation_input_tokens`; otherwise `cachedInput` is used as the implicit cache read price. For DeepSeek, `prompt_cache_hit_tokens` map to cached input and `prompt_cache_miss_tokens` map to regular input.\n- **smallModel:** Fallback model used for tool-less warmup messages (e.g., Claude Code probe requests); defaults to gpt-5-mini.\n- **useResponsesApiContextManagement:** When `true`, the proxy adds Responses API `context_management` compaction instructions. Defaults to `true`. Set it to `false` to disable this globally. When enabled, the request includes `context_management` in the body and keeps only the latest compaction carrier on follow-up turns. This is especially useful for long-running tasks.\n- **modelResponsesApiCompactThresholds:** Per-model Responses API `compact_threshold` overrides used when the proxy adds `context_management`. These values take precedence over the fallback threshold from `resolveResponsesCompactThreshold` (`max_prompt_tokens * ratio`, or the default fallback). Defaults set `gpt-5.4` and `gpt-5.5` to `217600` (`272000 * 0.8`). Models not listed continue to use the normal fallback logic.\n- **modelReasoningEfforts:** Per-model `reasoning.effort` sent to the Copilot Responses API. Allowed values are `none`, `minimal`, `low`, `medium`, `high`, and `xhigh`. If a model isn't listed, `high` is used by default.\n- **useMessagesApi:** When `true`, Claude-family models that support Copilot's native `/v1/messages` endpoint will use the Messages API; otherwise they fall back to `/chat/completions`. Set to `false` to disable Messages API routing and always use `/chat/completions`. Defaults to `true`.\n- **useResponsesApiWebSocket:** When `true`, Responses API requests use Copilot's websocket transport for models that advertise `ws:/responses`; models that only advertise `/responses` continue to use HTTP. Set to `false` to disable websocket routing and use HTTP `/responses` whenever the selected model supports it. Defaults to `true`.\n- **useResponsesApiWebSearch:** When `true`, the server keeps Responses API tools with `type: \"web_search\"` and forwards them upstream. Set to `false` to strip those tools from `/responses` payloads. Defaults to `true`.\n- **messageApiWebSearchModel:** Global fallback model used when a top-level Copilot `/v1/messages` request contains only the server-side `web_search` tool. Defaults to `gpt-5-mini`. If the value is a `provider/model` alias, the request is routed into that provider's Messages API path with the provider prefix stripped. For Copilot GPT models, web search runs through `/responses`. Mixed `web_search` plus custom tools are not supported and the server-side `web_search` tool is stripped.\n- **claudeTokenMultiplier:** Multiplier applied to the fallback GPT-tokenizer estimate for Claude `/v1/messages/count_tokens` requests. Defaults to `1.15`. Increase it if your client is still compacting too late. This setting is only used when the proxy is estimating Claude tokens locally; if `anthropicApiKey` is configured and Anthropic token counting succeeds, the exact Anthropic count is returned instead.\n- **anthropicApiKey:** Anthropic API key used to forward Claude `/v1/messages/count_tokens` requests to Anthropic's real token counting endpoint, which returns exact counts instead of GPT tokenizer estimates. Can also be set via the `ANTHROPIC_API_KEY` environment variable. If not set, or if the upstream call fails, token counting falls back to local GPT tokenizer estimation controlled by `claudeTokenMultiplier`.\n\nEdit this file to customize prompts or swap in your own fast model. Restart the server (or rerun the command) after changes so the cached config is refreshed.\n\n## API Authentication\n\n- **Protected non-admin routes:** All routes except `/`, `/usage-viewer`, and `/usage-viewer/` require authentication when `auth.apiKeys` is configured and non-empty.\n- **Admin routes:** All `/admin/*` routes require `auth.adminApiKey`. If it is missing, the server generates one at startup and persists it to `config.json` before serving requests.\n- **Allowed auth headers:**\n  - `x-api-key: <your_key>`\n  - `Authorization: Bearer <your_key>`\n- **CORS preflight:** `OPTIONS` requests are always allowed.\n- **When no regular keys are configured:** Non-admin routes continue to allow requests. This does not apply to `/admin/*`, which only accepts `auth.adminApiKey`.\n\nExample request for a regular protected route:\n\n```sh\ncurl http://localhost:4141/v1/models \\\n  -H \"x-api-key: your_api_key\"\n```\n\nExample request for an admin route:\n\n```sh\ncurl http://localhost:4141/admin/config/model-mappings \\\n  -H \"x-api-key: your_admin_api_key\"\n```\n\n## API Endpoints\n\nThe server exposes several OpenAI- and Anthropic-compatible endpoints. Requests can target GitHub Copilot, the built-in `codex` provider, or configured providers depending on the selected model and `provider/model` alias.\n\n### OpenAI Compatible Endpoints\n\nThese endpoints mimic the OpenAI API structure.\n\n| Endpoint                    | Method | Description                                                      |\n| --------------------------- | ------ | ---------------------------------------------------------------- |\n| `POST /v1/responses`        | `POST` | OpenAI Most advanced interface for generating model responses. Supports `provider/model` aliases for `openai-responses` providers. |\n| `POST /v1/chat/completions` | `POST` | Creates a model response for the given chat conversation. Supports `provider/model` aliases for `openai-compatible` providers and can be used without Copilot when the target provider is configured. |\n| `GET /v1/models`            | `GET`  | Lists Copilot models plus enabled provider models using `provider/model-id` IDs. |\n| `POST /v1/embeddings`       | `POST` | Creates an embedding vector representing the input text.         |\n\n### Anthropic Compatible Endpoints\n\nThese endpoints are designed to be compatible with the Anthropic Messages API.\n\n| Endpoint                         | Method | Description                                                  |\n| -------------------------------- | ------ | ------------------------------------------------------------ |\n| `POST /v1/messages`              | `POST` | Creates a model response for a given conversation. Supports `provider/model` aliases for configured providers, including translation through `openai-compatible` providers. |\n| `POST /v1/messages/count_tokens` | `POST` | Calculates the number of tokens for a given set of messages. Supports `provider/model` aliases for configured providers. |\n| `POST /:provider/v1/messages`       | `POST` | Proxies Anthropic Messages requests to the configured Anthropic provider, translates them through an OpenAI-compatible provider, or translates them through an OpenAI Responses provider. |\n| `GET /:provider/v1/models`          | `GET`  | Proxies model listing requests to the configured provider.   |\n| `POST /:provider/v1/messages/count_tokens` | `POST` | Calculates tokens locally for provider route requests. |\n\n### Usage Monitoring Endpoints\n\nNew endpoints for monitoring your Copilot usage and quotas.\n\n| Endpoint     | Method | Description                                                  |\n| ------------ | ------ | ------------------------------------------------------------ |\n| `GET /usage` | `GET`  | Get detailed Copilot usage statistics and quota information. |\n| `GET /token` | `GET`  | Get the current Copilot token being used by the API.         |\n\n### Admin / Configuration Endpoints\n\nThese endpoints are reserved for local administrative actions and only accept `auth.adminApiKey`.\n\n| Endpoint                              | Method | Description                                                                 |\n| ------------------------------------- | ------ | --------------------------------------------------------------------------- |\n| `GET /admin/config/model-mappings`    | `GET`  | Returns the current `config.json` path and the active `modelMappings` map.  |\n| `POST /admin/config/model-mappings`   | `POST` | Updates only the `modelMappings` field in `config.json` and returns it back. |\n\n## Example Usage\n\nCommon `npx` commands:\n\n```sh\n# Start the gateway\nnpx @jeffreycao/copilot-api@latest start\n\n# Start on a custom port with verbose logging\nnpx @jeffreycao/copilot-api@latest start --port 8080 --verbose\n\n# Run the auth flow\nnpx @jeffreycao/copilot-api@latest auth login\n\n# Configure a third-party provider, then run without GitHub Copilot\nnpx @jeffreycao/copilot-api@latest auth login --provider dashscope\nnpx @jeffreycao/copilot-api@latest start\n\n# Print debug information as JSON\nnpx @jeffreycao/copilot-api@latest debug --json\n\n# Run the published CLI with Bun instead of Node.js\nbunx --bun @jeffreycao/copilot-api@latest start\n```\n\nOpenAI-compatible provider examples after configuring `dashscope`:\n\n```sh\ncurl http://localhost:4141/v1/chat/completions \\\n  -H \"content-type: application/json\" \\\n  -d '{\"model\":\"dashscope/qwen3.6-plus\",\"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]}'\n\ncurl http://localhost:4141/dashscope/v1/messages \\\n  -H \"content-type: application/json\" \\\n  -d '{\"model\":\"qwen3.6-plus\",\"max_tokens\":1024,\"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]}'\n```\n\n## Usage Tips\n\n### CLAUDE.md or AGENTS.md Recommended Content\n\nTo add these reminders manually, include the following in `CLAUDE.md` for Claude Code, or `AGENTS.md` for opencode/codex:\n\n```\n- Prohibited from directly asking questions to users, MUST use question tool.\n- Once you can confirm that the task is complete, MUST use question tool to make user confirm. The user may respond with feedback if they are not satisfied with the result, which you can use to make improvements and try again, after try again, MUST use question tool to make user confirm again.\n```\n"}, "35c5c25cca29308a1d33a526c3a03e2c837f6834": {"t": 1785765574.6156385, "n": 46119, "h": "6d0c2dac7d02b4d2", "c": "# Copilot API Proxy\n\nEnglish | [简体中文](./README.zh-CN.md)\n\n## Important Notes\n\n> [!IMPORTANT]\n> **Before using, please be aware of the following:**\n>\n> 1. **Claude Code configuration:** When using with Claude Code, please configure the model ID as `claude-opus-4-8`. Example claude `settings.json` see [Manual Configuration with `settings.json`](#manual-configuration-with-settingsjson). \n>\n> 2. **Built-in `copilot`, `codex` and third-party providers:** Run `npx @jeffreycao/copilot-api@latest auth` and choose `copilot`, `codex`, `deepseek`, `custom`, or other providers.\n>\n> 3. **Note:** See [GitHub Copilot Security Notice](./NOTICE.md#github-copilot-security-notice) for the warning removed from the README header.\n\n---\n\n## Project Overview\n\nA small AI gateway that can use GitHub Copilot, the built-in `codex` provider, or configured third-party providers such as DashScope. GitHub Copilot is optional: if no GitHub token is available, the server can still start in provider-only mode as long as at least one enabled provider is configured.\n\nThe gateway exposes OpenAI- and Anthropic-compatible APIs from one local endpoint, so tools like [Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview), OpenCode, Codex, and OpenAI-compatible clients can share the same local server.\n\nOn the GitHub Copilot path, the gateway prefers Copilot's native Anthropic-style Messages API when available, preserving more Claude-native behavior for tool-heavy workflows.\n\n## Features\n\n- **OpenAI and Anthropic compatibility**: Serve `/v1/responses`, `/v1/chat/completions`, `/v1/models`, `/v1/embeddings`, and `/v1/messages` from one local gateway.\n- **Copilot is optional**: Use GitHub Copilot when credentials are present, or run the server with only configured providers.\n- **One gateway for Copilot, `codex`, and external providers**: Route GitHub Copilot, the built-in `codex` provider, and configured third-party providers behind the same endpoint.\n- **Standalone third-party providers**: Configure providers such as DashScope, DeepSeek, OpenRouter, or a custom provider and start the gateway without a GitHub Copilot login.\n- **OpenAI-compatible providers on chat and Messages APIs**: `openai-compatible` providers can serve top-level `/v1/chat/completions` through `model: \"provider/model\"` and Anthropic-style `/v1/messages` through request/response translation.\n- **Agent-friendly Claude handling on Copilot**: Prefer native `/v1/messages` when available, preserve Claude-style tool flows, support Anthropic beta features, Claude WebSearch through Responses-capable models, and keep subagent/session markers intact.\n- **Claude Code and OpenCode integration**: Works with Claude Code and OpenCode, including direct Anthropic-compatible usage through `@ai-sdk/anthropic`.\n- **Flexible auth and deployment options**: Supports interactive login or direct tokens, individual/business/enterprise plans, GitHub Enterprise, opencode OAuth, and custom data directories.\n- **Multi-provider routing**: Expose provider-specific `/:provider/...` routes or use `model: \"provider/model\"` on the top-level API.\n\n## Prerequisites\n\n- Bun (>= 1.2.x)\n- Node.js if you plan to run the published CLI with `npx`\n- GitHub account with Copilot subscription only if you want to use the GitHub Copilot provider\n- An API key or OAuth login for at least one configured provider if you want to run without GitHub Copilot\n\n## Installation\n\nTo install dependencies, run:\n\n```sh\nbun install\n```\n\nTo start the server directly from source:\n\n```sh\nbun run start start\n```\n\n## Running from Source\n\nThe project can be run from source in several ways:\n\n### Development Mode\n\n```sh\nbun run dev start\n```\n\n### Production Mode\n\n```sh\nbun run start start\n```\n\n## Using with npx\n\nYou can run the project directly using npx:\n\n> [!IMPORTANT]\n> Token usage storage uses Node's built-in `node:sqlite` module when running with `npx`. It is enabled on Node.js >= 22.13.0. On Node.js < 22.13.0, the CLI still starts, but token usage storage is disabled.\n>\n> If you want token usage storage without upgrading Node.js, run the published CLI with Bun instead: `bunx --bun @jeffreycao/copilot-api@latest start`.\n\n```sh\nnpx @jeffreycao/copilot-api@latest start\n```\n\nWith options:\n\n```sh\nnpx @jeffreycao/copilot-api@latest start --port 8080\n```\n\nFor authentication or provider configuration only:\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth\n```\n\nTo run without GitHub Copilot, configure at least one provider first, then start the server normally:\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth login --provider dashscope\nnpx @jeffreycao/copilot-api@latest start\n```\n\n## Using with Docker\n\nBuild the image:\n\n```sh\ndocker build -t copilot-api .\n```\n\nRun the container with a bind mount so auth data survives restarts:\n\n```sh\nmkdir -p ./copilot-data\ndocker run -p 4141:4141 -v $(pwd)/copilot-data:/root/.local/share/copilot-api copilot-api\n```\n\nThis stores GitHub auth data, provider config, and other gateway state in `./copilot-data` on the host, mapped to `/root/.local/share/copilot-api` in the container.\n\nOr pass a GitHub token directly:\n\n```sh\ndocker run -p 4141:4141 -e GH_TOKEN=your_github_token_here copilot-api\n```\n\n## Electron Desktop App\n\nIf you prefer a GUI, this repository also includes an Electron desktop app in `desktop/`. It supports GitHub Copilot sign-in, OpenAI Codex OAuth, and API-key configuration for DeepSeek, DashScope, OpenRouter, or a custom provider. After authorization or provider configuration, it can start and stop the local proxy with one click and shows the local endpoint, auth header, available models, usage, and logs in the app.\n\nThe settings screen also exposes `OAuth App`, `API Home`, `Enterprise URL`, verbose logging, and minimize-to-tray. Desktop packages are published in GitHub Releases:\n\nhttps://github.com/caozhiyuan/copilot-api/releases\n\nDownload the installer for your platform, authorize or configure a provider inside the app, choose a port, start the server, then point your client at the local endpoint shown in the app. Packaged desktop builds use the bundled Electron runtime, so normal desktop usage does not require installing Node.js separately. Token usage history is enabled when that bundled runtime supports SQLite.\n\nThe desktop app's Advanced Config page reads and writes the shared model mappings through `GET/POST /admin/config/model-mappings`. The same mappings apply across `POST /v1/messages`, `POST /v1/messages/count_tokens`, `POST /v1/responses`, and `POST /v1/chat/completions` instead of being split per interface. It uses `auth.adminApiKey` instead of the regular `auth.apiKeys`, and the app reads that key directly from `config.json` after the server has generated it on startup.\n\n### Desktop App Screenshots\n\nMain dashboard, token usage breakdown in the bundled Electron app:\n\n<p align=\"center\">\n  <img src=\"./docs/screenshots/desktop-dashboard.png\" alt=\"Copilot API desktop app dashboard\" width=\"49%\" />\n  <img src=\"./docs/screenshots/desktop-token-usage.png\" alt=\"Copilot API desktop app token usage view\" width=\"49%\" />\n</p>\n\n## Using with Claude Code\n\nThis AI gateway can be used to power [Claude Code](https://docs.anthropic.com/en/claude-code), an experimental conversational AI assistant for developers from Anthropic.\n\nThere are two ways to configure Claude Code to use this AI gateway:\n\n### Interactive Setup with `--claude-code` flag\n\nTo get started, run the `start` command with the `--claude-code` flag:\n\n```sh\nnpx @jeffreycao/copilot-api@latest start --claude-code\n```\n\nYou will be prompted to select a primary model and a \"small, fast\" model for background tasks. After selecting the models, a command will be copied to your clipboard. This command sets the necessary environment variables for Claude Code to use the gateway.\n\nPaste and run this command in a new terminal to launch Claude Code.\n\n### Manual Configuration with `settings.json`\n\nAlternatively, you can configure Claude Code by creating a `.claude/settings.json` file in your project's root directory. This file should contain the environment variables needed by Claude Code. This way you don't need to run the interactive setup every time.\n\nHere is an example `.claude/settings.json` file:\n\n```json\n{\n  \"env\": {\n    \"ANTHROPIC_BASE_URL\": \"http://localhost:4141\",\n    \"ANTHROPIC_AUTH_TOKEN\": \"dummy\",\n    \"ANTHROPIC_MODEL\": \"deepseek/deepseek-v4-pro\",\n    \"ANTHROPIC_DEFAULT_SONNET_MODEL\": \"deepseek/deepseek-v4-pro\",\n    \"ANTHROPIC_DEFAULT_HAIKU_MODEL\": \"deepseek/deepseek-v4-flash\",\n    \"DISABLE_NON_ESSENTIAL_MODEL_CALLS\": \"1\",\n    \"CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC\": \"1\",\n    \"CLAUDE_CODE_ATTRIBUTION_HEADER\": \"0\",\n    \"CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION\": \"false\",\n    \"CLAUDE_CODE_DISABLE_TERMINAL_TITLE\": \"true\",\n    \"CLAUDE_CODE_ENABLE_AWAY_SUMMARY\": \"0\"\n  },\n  \"permissions\": {\n    \"deny\": [\n      \"mcp__ide__executeCode\"\n    ]\n  }\n}\n```\n\n- Replace `ANTHROPIC_MODEL`, `ANTHROPIC_DEFAULT_OPUS_MODEL`, `ANTHROPIC_DEFAULT_SONNET_MODEL`, and `ANTHROPIC_DEFAULT_HAIKU_MODEL` according to your needs. After configuration, please install the claude code plugin [Plugin Integrations](#plugin-integrations).  \n- Setting CLAUDE_CODE_ATTRIBUTION_HEADER to 0 can prevent Claude code from adding billing and version information in system prompts, thereby avoiding prompt cache invalidation.\n- Turning off CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION and CLAUDE_CODE_ENABLE_AWAY_SUMMARY can prevent quota from being consumed unnecessarily.\n- Claude Code WebSearch is supported for pure search requests. For Copilot, keep the global `messageApiWebSearchModel` set to a Responses-capable GPT model or a `provider/model` alias. For provider routes, use a native Anthropic provider or an `openai-responses` provider. Add `WebSearch` to `permissions.deny` only if you want to forbid this traffic.\n- If using a non-Claude model, do not enable ENABLE_TOOL_SEARCH. If using the Claude model, can enable ENABLE_TOOL_SEARCH. The current Claude Code uses the client tool search mode. In this mode, loading defer tools requires an additional request each time.\n- `CLAUDE_CODE_AUTO_COMPACT_WINDOW`: Set the context capacity in tokens used for auto-compaction calculations. Defaults to the model's context window: 200K for standard models or 1M for extended context models. Use a lower value like `500000` on a 1M model (e.g., `claude-opus-4-6[1m]`) to treat the window as 500K for compaction purposes. The value is capped at the model's actual context window. `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` is applied as a percentage of this value. Setting this variable decouples the compaction threshold from the status line's `used_percentage`, which always uses the model's full context window.\n\nYou can find more options here: [Claude Code settings](https://docs.anthropic.com/en/docs/claude-code/settings#environment-variables)\n\nYou can also read more about IDE integration here: [Add Claude Code to your IDE](https://docs.anthropic.com/en/docs/claude-code/ide-integrations)\n\n## Using with OpenCode\n\nOpenCode already has a direct GitHub Copilot provider. Use this section when you want OpenCode to point at this AI gateway through `@ai-sdk/anthropic` and reuse the agent behaviors described earlier in this README.\n\n### Minimal setup\n\nStart the AI gateway with the OpenCode OAuth app:\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth --oauth-app=opencode\nnpx @jeffreycao/copilot-api@latest start\n```\n\nThen point OpenCode at the gateway with `@ai-sdk/anthropic`.\n\nExample `~/.config/opencode/opencode.json`:\n\n```json\n{\n  \"$schema\": \"https://opencode.ai/config.json\",\n  \"provider\": {\n    \"local\": {\n      \"npm\": \"@ai-sdk/anthropic\",\n      \"name\": \"My Local\",\n      \"options\": {\n        \"baseURL\": \"http://localhost:4141/v1\",\n        \"apiKey\": \"dummy\"\n      },\n      \"models\": {\n        \"gpt-5.4\": {\n          \"name\": \"gpt-5.4\",\n          \"modalities\": {\n            \"input\": [\"text\", \"image\"],\n            \"output\": [\"text\"]\n          },\n          \"limit\": {\n            \"context\": 300000,\n            \"output\": 128000\n          }\n        },\n        \"claude-sonnet-4.6\": {\n          \"id\": \"claude-sonnet-4.6\",\n          \"name\": \"claude-sonnet-4.6\",\n          \"modalities\": {\n            \"input\": [\"text\", \"image\"],\n            \"output\": [\"text\"]\n          },          \n          \"limit\": {\n            \"context\": 200000,\n            \"output\": 32000\n          },\n          \"options\": {\n            \"thinking\": {\n              \"type\": \"adaptive\"\n            },\n            \"effort\": \"max\"\n          }\n        }\n      }\n    }\n  }\n}\n```\n\nWhy these fields matter:\n\n- `npm: \"@ai-sdk/anthropic\"` is the important part. OpenCode will speak Anthropic Messages semantics to this AI gateway instead of flattening everything into OpenAI Chat Completions.\n- `options.baseURL` should be `http://localhost:4141/v1`; the Anthropic SDK will append `/messages`, `/models`, and `/messages/count_tokens` automatically.\n- If you enable `auth.apiKeys` in this AI gateway, replace `dummy` with a real key. Otherwise any placeholder value is fine.\n\n## Using with Codex\n\nThis AI gateway can also power Codex.\n\n### Codex `config.toml` Reference\n\nAdd the following `[model_providers.copilot_api]` section to your Codex `~/.codex/config.toml`:\n\n```toml\nmodel_provider = \"copilot_api\"\nmodel_reasoning_summary = \"auto\"\nmodel_verbosity = \"medium\"\nmodel_context_window = 272000\nmodel_auto_compact_token_limit = 244800\n\n[model_providers.copilot_api]\nname = \"OpenAI\"\nbase_url = \"http://localhost:4141\"\nenv_key = \"GITHUB_COPILOT_API_KEY\"\nrequires_openai_auth = true\nsupports_websockets = false\nwire_api = \"responses\"\nrequest_max_retries = 3\nstream_max_retries = 1\nstream_idle_timeout_ms = 300000\n\n[features]\nremote_compaction_v2 = true\n\n[analytics]\nenabled = false\n```\n\n> [!NOTE]\n> This configuration is specific to Codex and the GitHub Copilot provider. `name` must be set to `\"OpenAI\"`. It can help mitigate Codex local compact cache miss issues. If you have enabled `useResponsesApiContextManagement` (Responses API context management compaction), `remote_compaction_v2` or local compact is generally not triggered, but it may still occur when tool results return a large number of tokens.\n\n## GPT Tool Search\n\nFor GPT Responses models such as `gpt-5.4+`, this AI gateway can expose Responses `tool_search` through a small MCP bridge. The same bridge can be used by Claude Code and opencode, as long as the client loads MCP servers and sends Anthropic Messages traffic through this gateway.\n\nDo not set Claude Code's native `ENABLE_TOOL_SEARCH` for GPT models. That flag enables Claude Code's own client-side tool search mode, and it may stop forwarding deferred tool definitions. This gateway needs the full tool definitions so it can keep the small always-loaded tool set eager and translate every other tool into Responses deferred namespaces.\n\nIf you install `tool-search@copilot-api-marketplace`, Claude Code receives this MCP bridge automatically and you can skip the manual Claude Code MCP setup below.\n\nAdd the tool search bridge to the MCP config used by Claude Code:\n\n```json\n{\n  \"mcpServers\": {\n    \"tool_search\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@jeffreycao/copilot-api@latest\", \"mcp\"]\n    }\n  }\n}\n```\n\nAdd the tool search bridge to the MCP config used by opencode:\n\n```json\n{\n  \"mcp\": {\n    \"tool_search\": {\n      \"type\": \"local\",\n      \"command\": [\"npx\", \"-y\", \"@jeffreycao/copilot-api@latest\", \"mcp\"]\n    }\n  }\n}\n```\n\nFor local development, use `bun` as the command and `[\"run\", \"./src/main.ts\", \"mcp\"]` as the args.\n\nInternally, the gateway now configures OpenAI Responses `tool_search` in client-executed mode. Deferred tools are still exposed as searchable namespaces, but the model is explicitly asked to return the exact deferred tool names it wants to load next.\n\nThe bridge uses direct tool selection, not query search. Its tool input is `names`, a comma-separated list of exact deferred tool names, for example `TaskList,TaskGet,mcp__fetch__fetch`.\n\n## Plugin Integrations\n\nPlugin integrations are available for Claude Code and opencode.\n\n#### Claude Code plugin integration (marketplace-based)\n\nThe Claude Code integration is packaged as two plugins:\n\n- `agent-inject` injects `__SUBAGENT_MARKER__...` on `SubagentStart`, so the gateway can infer `x-initiator: agent`.\n- `tool-search` registers the `tool_search` MCP bridge used for GPT Responses deferred tool loading.\n\n- Marketplace catalog in this repository: `.claude-plugin/marketplace.json`\n- Plugin sources in this repository: `plugin/claude/agent-inject`, `plugin/claude/tool-search`\n\nAdd the marketplace remotely:\n\n```sh\n/plugin marketplace add https://github.com/caozhiyuan/copilot-api.git\n```\n\nInstall the plugins from the marketplace:\n\n```sh\n/plugin install agent-inject@copilot-api-marketplace\n/plugin install tool-search@copilot-api-marketplace\n```\n\nAfter installation, `agent-inject` injects `__SUBAGENT_MARKER__...` on `SubagentStart`, and the gateway uses it to infer `x-initiator: agent`.\n\nThe `agent-inject` plugin also registers a `UserPromptSubmit` hook that returns `{\"continue\": true}`, and it can inject `SessionStart` reminder rules through environment variables:\n\n- `CLAUDE_PLUGIN_ENABLE_QUESTION_RULES=1` enables the two reminders about using the `question` tool automatically for Claude Code. Alternatively, you can add the same reminders manually in `CLAUDE.md`; see [CLAUDE.md or AGENTS.md Recommended Content](#claudemd-or-agentsmd-recommended-content).\n- `CLAUDE_PLUGIN_ENABLE_NO_BACKGROUND_AGENTS_RULE=1` enables the `run_in_background: true` avoidance reminder for agent hooks.\n\nThe `tool-search` plugin bundles the same MCP bridge described in [GPT Tool Search](#gpt-tool-search), so Claude Code users do not need to add the `tool_search` server manually when they install that plugin.\n\n#### Opencode plugin\n\nThe subagent marker producer is packaged as an opencode plugin located at `plugin/opencode/subagent-marker.js`.\n\n**Installation:**\n\nCopy the plugin file to your opencode plugins directory:\n\n```sh\n# Clone or download this repository, then copy the plugin\ncp plugin/opencode/subagent-marker.js ~/.config/opencode/plugins/\n```\n\nOr manually create the file at `~/.config/opencode/plugins/subagent-marker.js` with the plugin content.\n\n**Features:**\n\n- Tracks sub-sessions created by subagents\n- Automatically prepends a marker system reminder (`__SUBAGENT_MARKER__...`) to subagent chat messages\n- Sets `x-session-id` header for session tracking\n- Enables the gateway to infer `x-initiator: agent` for subagent-originated requests\n\nThe plugin hooks into `session.created`, `session.deleted`, `chat.message`, and `chat.headers` events to provide seamless subagent marker functionality.\n\n## Using the Usage Viewer\n\nAfter starting the server, a URL to the Copilot Usage Dashboard will be displayed in your console. This dashboard is a web interface for monitoring your API usage.\n\n1.  Start the server. For example, using npx:\n    ```sh\n    npx @jeffreycao/copilot-api@latest start\n    ```\n2.  The server will output a URL to the usage viewer. Copy and paste this URL into your browser. It will look something like this:\n    `http://localhost:4141/usage-viewer?endpoint=http://localhost:4141/usage`\n    - If you use the `start.bat` script on Windows, this page will open automatically.\n\nThe dashboard provides a user-friendly interface to view your Copilot usage data:\n\n> Token usage history requires Bun or Node.js >= 22.13.0. On Node.js < 22.13.0, the server runs normally but token usage storage is disabled.\n\n- **API Endpoint URL**: The dashboard is pre-configured to fetch data from your local server endpoint via a URL query parameter. You can manually switch this to any other compatible API endpoint.\n- **x-api-key Authentication**: If API Key authentication is enabled, you can provide the `x-api-key` request header. The key is persisted in the browser's local storage.\n- **Period Selector**: Choose from Day, Week, or Month time ranges. The URL query parameter updates automatically when you switch, making it easy to bookmark and share.\n- **Fetch Data**: Click the \"Refresh\" button to load or refresh the usage data. The dashboard also fetches data automatically on page load.\n- **Copilot Quotas**: View quota usage for services such as Chat and Completions via progress bars. Hover over a card to see used/remaining details.\n- **Token Usage Metric Cards**: See a summary of Total, Input, Output, Cache Read, Cache Write, Requests, and estimated cost for the current period.\n- **Trend Chart (Week / Month)**: An interactive line chart with model and metric filters. Click a data point to inspect the usage breakdown for a specific day.\n- **Model Breakdown Table**: A per-model summary of requests, input/output/cache tokens, and estimated cost for the selected period.\n- **Request Events (Paginated)**: A time-sorted list of request event records with pagination support, showing timestamps, models, request IDs, and token counts.\n- **Detailed Information**: See the full JSON response from the API for a detailed breakdown of all available usage statistics.\n- **URL-based Configuration**: You can also specify the API endpoint and period directly via `endpoint` and `period` query parameters. For example:\n  `http://localhost:4141/usage-viewer?endpoint=http://your-api-server/usage&period=week`\n\n### Usage Viewer Screenshot\n\n<p align=\"center\">\n  <img src=\"./docs/screenshots/usage-viewer.png\" alt=\"Copilot API usage viewer\" width=\"900\" />\n</p>\n\n## Command Structure\n\nCopilot API now uses a subcommand structure with these main commands:\n\n- `start`: Start the gateway server. If a GitHub token is available, the server starts with Copilot enabled. If no GitHub token is available, it starts in provider-only mode when at least one enabled provider exists; otherwise it guides you through provider setup.\n- `auth`: Run provider login or configuration without starting the server. Use it for GitHub Copilot login, Codex OAuth, or third-party provider API key setup.\n- `debug`: Display diagnostic information including version, runtime details, file paths, and authentication status. Useful for troubleshooting and support.\n\n## Command Line Options\n\n### Global Options\n\nThe following options can be used with any subcommand. When passing them before the subcommand, use the `--key=value` form:\n\n| Option            | Description                                            | Default | Alias |\n| ----------------- | ------------------------------------------------------ | ------- | ----- |\n| --api-home        | Path to the API home directory (sets COPILOT_API_HOME) | none    | none  |\n| --oauth-app       | OAuth app identifier (sets COPILOT_API_OAUTH_APP)      | none    | none  |\n| --enterprise-url  | Enterprise URL for GitHub (sets COPILOT_API_ENTERPRISE_URL) | none | none |\n\n### Start Command Options\n\nThe following command line options are available for the `start` command:\n\n| Option         | Description                                                                   | Default    | Alias |\n| -------------- | ----------------------------------------------------------------------------- | ---------- | ----- |\n| --port         | Port to listen on                                                             | 4141       | -p    |\n| --verbose      | Enable verbose logging                                                        | false      | -v    |\n| --github-token | Provide GitHub token directly (must be generated using the `auth` subcommand) | none       | -g    |\n| --claude-code  | Generate a command to launch Claude Code with Copilot API config              | false      | -c    |\n| --show-token   | Show GitHub and Copilot tokens on fetch and refresh                           | false      | none  |\n| --proxy-env    | Initialize proxy from environment variables                                   | false      | none  |\n\n### Auth Command Options\n\n| Option       | Description               | Default | Alias |\n| ------------ | ------------------------- | ------- | ----- |\n| --provider   | Provider to log in with or configure (`copilot`, `codex`, `opencode-go`, `deepseek`, `dashscope`, `openrouter`, or `custom`) | prompt | none |\n| --verbose    | Enable verbose logging    | false   | -v    |\n| --show-token | Show GitHub token on auth | false   | none  |\n\nUse `copilot-api auth login --provider copilot` only when you want to enable the GitHub Copilot provider. Copilot is not required for `codex` or third-party provider-only usage.\n\nUse `copilot-api auth login --provider deepseek`, `--provider dashscope`, `--provider openrouter`, or `--provider opencode-go` to add or update those common third-party providers from the CLI. DeepSeek prompts for masked `apiKey`, provider `type` (default `anthropic`), and `baseUrl` defaulting to `https://api.deepseek.com/anthropic`. DashScope prompts for masked `apiKey`, provider `type` (default `openai-compatible`), and prefilled `baseUrl`. OpenRouter prompts for masked `apiKey` and prefilled `baseUrl` only, and writes `type: \"anthropic\"`. OpenCode Go prompts for masked `apiKey` and prefilled `baseUrl` only, and writes `type: \"openai-compatible\"` (baseUrl `https://opencode.ai/zen/go`). After a provider is configured and enabled, `copilot-api start` can run without any GitHub token.\n\nUse `copilot-api auth login --provider custom` to add or update another third-party provider from the CLI. The command prompts for the provider name, supported type (`anthropic`, `openai-compatible`, or `openai-responses`), `baseUrl`, masked `apiKey`, and `authType`; `authType` may be left as the type default or set to `x-api-key` / `authorization`.\n\n### Debug Command Options\n\n| Option | Description               | Default | Alias |\n| ------ | ------------------------- | ------- | ----- |\n| --json | Output debug info as JSON | false   | none  |\n\n## Configuration (config.json)\n\n- **Location:** `~/.local/share/copilot-api/config.json` (Linux/macOS) or `%USERPROFILE%\\.local\\share\\copilot-api\\config.json` (Windows).\n- **Default shape:**\n  ```json\n  {\n    \"auth\": {\n      \"apiKeys\": [],\n      \"adminApiKey\": \"<auto-generated-on-startup>\"\n    },\n    \"providers\": {},\n    \"modelMappings\": {},\n    \"extraPrompts\": {\n      \"gpt-5-mini\": \"<built-in exploration prompt>\",\n      \"gpt-5.3-codex\": \"<built-in commentary prompt>\",\n      \"gpt-5.4-mini\": \"<built-in commentary prompt>\",\n      \"gpt-5.4\": \"<built-in commentary prompt>\",\n      \"gpt-5.5\": \"<built-in commentary prompt>\"\n    },\n    \"smallModel\": \"gpt-5-mini\",\n    \"useResponsesApiContextManagement\": true,\n    \"modelResponsesApiCompactThresholds\": {\n      \"gpt-5.4\": 217600,\n      \"gpt-5.5\": 217600\n    },\n    \"modelReasoningEfforts\": {\n      \"gpt-5-mini\": \"low\",\n      \"gpt-5.3-codex\": \"xhigh\",\n      \"gpt-5.4-mini\": \"xhigh\",\n      \"gpt-5.4\": \"xhigh\",\n      \"gpt-5.5\": \"xhigh\"\n    },\n    \"useMessagesApi\": true,\n    \"useResponsesApiWebSocket\": true,\n    \"useResponsesApiWebSearch\": true,\n    \"messageApiWebSearchModel\": \"gpt-5-mini\"\n  }\n  ```\n- **auth.apiKeys:** API keys used for request authentication on non-admin routes. Supports multiple keys for rotation. Requests can authenticate with either `x-api-key: <key>` or `Authorization: Bearer <key>`. If empty or omitted, authentication for non-admin routes is disabled.\n- **auth.adminApiKey:** Single admin key used only for `/admin/*` routes. If missing, the server generates a random key at startup and writes it back to `config.json`. Requests use the same `x-api-key` or `Authorization: Bearer` headers, but regular `auth.apiKeys` never grant access to `/admin/*`.\n- **modelMappings:** Exact `sourceModel -> targetModel` rewrites shared by top-level `POST /v1/messages`, `POST /v1/messages/count_tokens`, `POST /v1/responses`, and `POST /v1/chat/completions` requests. Omit it or leave it as `{}` to disable rewrites. Both the source and target must be non-empty strings. Targets can be regular model IDs or `provider/model` aliases such as `dashscope/qwen3.6-plus`, and the rewrite happens before provider alias parsing. These mappings are not split per interface. The admin endpoints `GET/POST /admin/config/model-mappings` read and update only this field.\n- **extraPrompts:** Map of `model -> prompt` appended to the first system prompt when translating Anthropic-style requests to Copilot. Use this to inject guardrails or guidance per model. Missing default entries are auto-added without overwriting your custom prompts. The built-in prompts for `gpt-5.3-codex` and `gpt-5.4` enable phase-aware commentary, which lets the model emit a short user-facing progress update before tools or deeper reasoning.\n- **providers:** Global upstream provider map. Each provider key (for example `dashscope`) becomes a route prefix (`/dashscope/v1/messages`). Supports `type: \"anthropic\"`, `type: \"openai-compatible\"`, and `type: \"openai-responses\"`. Top-level clients can also use `model: \"dashscope/model-id\"` with `/v1/messages`, `/v1/messages/count_tokens`, `/v1/responses`, and `/v1/chat/completions`; the gateway strips the `dashscope/` prefix before forwarding upstream. `openai-compatible` providers support both chat and Messages flows: `/v1/chat/completions` is proxied to upstream `/v1/chat/completions`, while `/v1/messages` and `/:provider/v1/messages` are translated to upstream chat completions and translated back to Anthropic Messages responses. `GET /v1/models` aggregates enabled provider models with `provider/model-id` IDs; use `GET /dashscope/v1/models` for a single provider's raw model list.\n  - `enabled` defaults to `true` if omitted.\n  - `baseUrl` should be provider API base URL without the final endpoint. For Anthropic providers, omit `/v1/messages`; for OpenAI-compatible providers, omit `/v1/chat/completions`; for OpenAI Responses providers, omit `/v1/responses`.\n  - `apiKey` is used as the upstream credential value and is required for regular providers.\n  - `authType` (optional): Controls how `apiKey` is sent upstream. Supports `x-api-key` and `authorization` for regular providers. Anthropic providers default to `x-api-key`; OpenAI-compatible and OpenAI Responses providers default to `authorization`. When set to `authorization`, the proxy sends `Authorization: Bearer <apiKey>`. `oauth2` is reserved for the built-in `codex` provider and is written automatically by `auth login --provider codex`.\n  - `pricingCurrency` (optional): Provider-level currency used for token cost calculation, for example `USD` or `CNY`. Quick providers default to `CNY` for DashScope and DeepSeek, and `USD` for Codex/OpenRouter. Costs are grouped by currency and are not exchange-rate converted.\n  - `models` (optional): Per-model configuration map. Each key is a model ID (matching the model name in requests), and the value is:\n    - `temperature` (optional): Default temperature value used when the request does not specify one.\n    - `topP` (optional): Default top_p value used when the request does not specify one.\n    - `topK` (optional): Default top_k value used when the request does not specify one.\n    - `extraBody` (optional): Dynamic fields merged into the upstream request body for that model. Request body fields with the same name take precedence. OpenAI-compatible providers can use this for fields such as `enable_thinking`, `preserve_thinking`, `reasoning_effort`. `thinking_budget` is a special OpenAI-compatible provider override: when configured in `extraBody`, it is forced after Anthropic `thinking.budget_tokens` translation and overrides the request-derived budget. For providers whose name is `dashscope` or whose `baseUrl` contains `aliyuncs.com`, the request-derived `thinking_budget` (from Anthropic `thinking.budget_tokens`) is forwarded upstream; for other OpenAI-compatible providers the request-derived `thinking_budget` is stripped, while an `extraBody` `thinking_budget` is still honored.\n    - `pricing` (optional): Per-model token prices, in the provider `pricingCurrency`, per 1M tokens. Supported fields are `input`, `output`, `cachedInput` (implicit cache read), `explicitCachedInput` (explicit cache read), and `cacheCreationInput`. Use `tiers` with `maxInputTokens` for input-size tiered pricing.\n    - `contextCache` (optional): Defaults to `true` for providers whose name is `dashscope` or whose `baseUrl` contains `aliyuncs.com`; defaults to `false` for other OpenAI-compatible providers. This enables Alibaba Cloud Model Studio/DashScope explicit context cache by injecting `cache_control: { \"type\": \"ephemeral\" }` on up to 4 content blocks using the Context Cache format. The cache breakpoint strategy matches opencode's main provider flow: the first 2 system messages plus the last 2 non-system messages. Marked string content is converted to text content part arrays for `system` / `user` / `assistant` / `tool` messages; existing array content is marked on the last part. Set this to `false` when the model already supports implicit caching, or when the upstream does not accept this explicit-cache extension field. Set this to `true` for non-DashScope providers that support the same explicit-cache extension.\n    - `supportPdf` (optional): Controls whether the model supports PDF/document content. Defaults to `false`; unsupported PDFs are converted to a text notice. Set it to `true` to send PDF/document blocks as OpenAI Chat Completions file parts.\n    - `toolContentSupportType` (optional): Tool result content capabilities for that model, as an array of `array`, `image`, and `pdf`. Provider routes default to string-only tool content when omitted. If `supportPdf` is `true` but this list does not include `pdf`, file parts in tool results are moved to user role messages. This provider default does not change the Copilot main flow, which continues to support array + image and not PDF.\n    - `type` (optional): Per-model override of the provider protocol type. Supports `anthropic`, `openai-compatible`, and `openai-responses`. When set, the provider's `/v1/messages` route uses this model's type instead of the provider-level type for request routing, auth header resolution, and upstream endpoint selection. This is useful for providers like OpenCode Go whose upstream supports both OpenAI-compatible and Anthropic Messages APIs for different models. When the type is overridden, the auth header is resolved from the overridden type's default (Anthropic defaults to `x-api-key`; OpenAI-compatible/Responses default to `authorization`).\n\n  Example DashScope model settings:\n  ```json\n  {\n    \"providers\": {\n      \"dashscope\": {\n        \"type\": \"openai-compatible\",\n        \"enabled\": true,\n        \"baseUrl\": \"https://dashscope.aliyuncs.com/compatible-mode\",\n        \"apiKey\": \"sk-your-dashscope-key\",\n        \"pricingCurrency\": \"CNY\",\n        \"models\": {\n          \"qwen3.7-plus\": {\n            \"temperature\": 1,\n            \"topP\": 0.95,\n            \"topK\": 20,\n            \"extraBody\": {\n              \"preserve_thinking\": true\n            }\n          },\n          \"glm-5.1\": {\n            \"temperature\": 0.7,\n            \"topP\": 0.95,\n            \"contextCache\": true,\n            \"pricing\": {\n              \"tiers\": [\n                {\n                  \"maxInputTokens\": 32000,\n                  \"input\": 6,\n                  \"cachedInput\": 1.2,\n                  \"explicitCachedInput\": 0.6,\n                  \"cacheCreationInput\": 7.5,\n                  \"output\": 24\n                },\n                {\n                  \"maxInputTokens\": 200000,\n                  \"input\": 8,\n                  \"cachedInput\": 1.6,\n                  \"explicitCachedInput\": 0.8,\n                  \"cacheCreationInput\": 10,\n                  \"output\": 28\n                }\n              ]\n            },\n            \"extraBody\": {\n              \"preserve_thinking\": true\n            }\n          }\n        }\n      }\n    }\n  }\n  ```\n  Built-in token prices cover Codex GPT models in USD, DashScope `qwen3.7-max`, `qwen3.7-plus`, `glm-5.1`, `glm-5.2` in CNY, DeepSeek `deepseek-v4-flash`, `deepseek-v4-pro`, `deepseek-chat`, `deepseek-reasoner` in CNY, and OpenCode Go models (`glm-5.2`, `deepseek-v4-flash`, `deepseek-v4-pro`, `kimi-k2.7-code`, `mimo-v2.5`, `mimo-v2.5-pro`, `qwen3.7-plus`, `qwen3.7-max`, `minimax-m2.5`, `minimax-m3`) in USD. User `pricing` entries override built-ins. For DashScope, cached tokens are charged as explicit cache reads when the upstream usage includes `cache_creation_input_tokens`; otherwise `cachedInput` is used as the implicit cache read price. For DeepSeek, `prompt_cache_hit_tokens` map to cached input and `prompt_cache_miss_tokens` map to regular input.\n- **smallModel:** Fallback model used for tool-less warmup messages (e.g., Claude Code probe requests); defaults to gpt-5-mini.\n- **useResponsesApiContextManagement:** When `true`, the proxy adds Responses API `context_management` compaction instructions. Defaults to `true`. Set it to `false` to disable this globally. When enabled, the request includes `context_management` in the body and keeps only the latest compaction carrier on follow-up turns. This is especially useful for long-running tasks.\n- **modelResponsesApiCompactThresholds:** Per-model Responses API `compact_threshold` overrides used when the proxy adds `context_management`. These values take precedence over the fallback threshold from `resolveResponsesCompactThreshold` (`max_prompt_tokens * ratio`, or the default fallback). Defaults set `gpt-5.4` and `gpt-5.5` to `217600` (`272000 * 0.8`). Models not listed continue to use the normal fallback logic.\n- **modelReasoningEfforts:** Per-model `reasoning.effort` sent to the Copilot Responses API. Allowed values are `none`, `minimal`, `low`, `medium`, `high`, and `xhigh`. If a model isn't listed, `high` is used by default.\n- **useMessagesApi:** When `true`, Claude-family models that support Copilot's native `/v1/messages` endpoint will use the Messages API; otherwise they fall back to `/chat/completions`. Set to `false` to disable Messages API routing and always use `/chat/completions`. Defaults to `true`.\n- **useResponsesApiWebSocket:** When `true`, Responses API requests use Copilot's websocket transport for models that advertise `ws:/responses`; models that only advertise `/responses` continue to use HTTP. Set to `false` to disable websocket routing and use HTTP `/responses` whenever the selected model supports it. Defaults to `true`.\n- **useResponsesApiWebSearch:** When `true`, the server keeps Responses API tools with `type: \"web_search\"` and forwards them upstream. Set to `false` to strip those tools from `/responses` payloads. Defaults to `true`.\n- **messageApiWebSearchModel:** Global fallback model used when a top-level Copilot `/v1/messages` request contains only the server-side `web_search` tool. Defaults to `gpt-5-mini`. If the value is a `provider/model` alias, the request is routed into that provider's Messages API path with the provider prefix stripped. For Copilot GPT models, web search runs through `/responses`. Mixed `web_search` plus custom tools are not supported and the server-side `web_search` tool is stripped.\n- **claudeTokenMultiplier:** Multiplier applied to the fallback GPT-tokenizer estimate for Claude `/v1/messages/count_tokens` requests. Defaults to `1.15`. Increase it if your client is still compacting too late. This setting is only used when the proxy is estimating Claude tokens locally; if `anthropicApiKey` is configured and Anthropic token counting succeeds, the exact Anthropic count is returned instead.\n- **anthropicApiKey:** Anthropic API key used to forward Claude `/v1/messages/count_tokens` requests to Anthropic's real token counting endpoint, which returns exact counts instead of GPT tokenizer estimates. Can also be set via the `ANTHROPIC_API_KEY` environment variable. If not set, or if the upstream call fails, token counting falls back to local GPT tokenizer estimation controlled by `claudeTokenMultiplier`.\n\nEdit this file to customize prompts or swap in your own fast model. Restart the server (or rerun the command) after changes so the cached config is refreshed.\n\n## API Authentication\n\n- **Protected non-admin routes:** All routes except `/`, `/usage-viewer`, and `/usage-viewer/` require authentication when `auth.apiKeys` is configured and non-empty.\n- **Admin routes:** All `/admin/*` routes require `auth.adminApiKey`. If it is missing, the server generates one at startup and persists it to `config.json` before serving requests.\n- **Allowed auth headers:**\n  - `x-api-key: <your_key>`\n  - `Authorization: Bearer <your_key>`\n- **CORS preflight:** `OPTIONS` requests are always allowed.\n- **When no regular keys are configured:** Non-admin routes continue to allow requests. This does not apply to `/admin/*`, which only accepts `auth.adminApiKey`.\n\nExample request for a regular protected route:\n\n```sh\ncurl http://localhost:4141/v1/models \\\n  -H \"x-api-key: your_api_key\"\n```\n\nExample request for an admin route:\n\n```sh\ncurl http://localhost:4141/admin/config/model-mappings \\\n  -H \"x-api-key: your_admin_api_key\"\n```\n\n## API Endpoints\n\nThe server exposes several OpenAI- and Anthropic-compatible endpoints. Requests can target GitHub Copilot, the built-in `codex` provider, or configured providers depending on the selected model and `provider/model` alias.\n\n### OpenAI Compatible Endpoints\n\nThese endpoints mimic the OpenAI API structure.\n\n| Endpoint                    | Method | Description                                                      |\n| --------------------------- | ------ | ---------------------------------------------------------------- |\n| `POST /v1/responses`        | `POST` | OpenAI Most advanced interface for generating model responses. Supports `provider/model` aliases for `openai-responses` providers. |\n| `POST /v1/chat/completions` | `POST` | Creates a model response for the given chat conversation. Supports `provider/model` aliases for `openai-compatible` providers and can be used without Copilot when the target provider is configured. |\n| `GET /v1/models`            | `GET`  | Lists Copilot models plus enabled provider models using `provider/model-id` IDs. |\n| `POST /v1/embeddings`       | `POST` | Creates an embedding vector representing the input text.         |\n\n### Anthropic Compatible Endpoints\n\nThese endpoints are designed to be compatible with the Anthropic Messages API.\n\n| Endpoint                         | Method | Description                                                  |\n| -------------------------------- | ------ | ------------------------------------------------------------ |\n| `POST /v1/messages`              | `POST` | Creates a model response for a given conversation. Supports `provider/model` aliases for configured providers, including translation through `openai-compatible` providers. |\n| `POST /v1/messages/count_tokens` | `POST` | Calculates the number of tokens for a given set of messages. Supports `provider/model` aliases for configured providers. |\n| `POST /:provider/v1/messages`       | `POST` | Proxies Anthropic Messages requests to the configured Anthropic provider, translates them through an OpenAI-compatible provider, or translates them through an OpenAI Responses provider. |\n| `GET /:provider/v1/models`          | `GET`  | Proxies model listing requests to the configured provider.   |\n| `POST /:provider/v1/messages/count_tokens` | `POST` | Calculates tokens locally for provider route requests. |\n\n### Usage Monitoring Endpoints\n\nNew endpoints for monitoring your Copilot usage and quotas.\n\n| Endpoint     | Method | Description                                                  |\n| ------------ | ------ | ------------------------------------------------------------ |\n| `GET /usage` | `GET`  | Get detailed Copilot usage statistics and quota information. |\n| `GET /token` | `GET`  | Get the current Copilot token being used by the API.         |\n\n### Admin / Configuration Endpoints\n\nThese endpoints are reserved for local administrative actions and only accept `auth.adminApiKey`.\n\n| Endpoint                              | Method | Description                                                                 |\n| ------------------------------------- | ------ | --------------------------------------------------------------------------- |\n| `GET /admin/config/model-mappings`    | `GET`  | Returns the current `config.json` path and the active `modelMappings` map.  |\n| `POST /admin/config/model-mappings`   | `POST` | Updates only the `modelMappings` field in `config.json` and returns it back. |\n\n## Example Usage\n\nCommon `npx` commands:\n\n```sh\n# Start the gateway\nnpx @jeffreycao/copilot-api@latest start\n\n# Start on a custom port with verbose logging\nnpx @jeffreycao/copilot-api@latest start --port 8080 --verbose\n\n# Run the auth flow\nnpx @jeffreycao/copilot-api@latest auth login\n\n# Configure a third-party provider, then run without GitHub Copilot\nnpx @jeffreycao/copilot-api@latest auth login --provider dashscope\nnpx @jeffreycao/copilot-api@latest start\n\n# Print debug information as JSON\nnpx @jeffreycao/copilot-api@latest debug --json\n\n# Run the published CLI with Bun instead of Node.js\nbunx --bun @jeffreycao/copilot-api@latest start\n```\n\nOpenAI-compatible provider examples after configuring `dashscope`:\n\n```sh\ncurl http://localhost:4141/v1/chat/completions \\\n  -H \"content-type: application/json\" \\\n  -d '{\"model\":\"dashscope/qwen3.6-plus\",\"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]}'\n\ncurl http://localhost:4141/dashscope/v1/messages \\\n  -H \"content-type: application/json\" \\\n  -d '{\"model\":\"qwen3.6-plus\",\"max_tokens\":1024,\"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]}'\n```\n\n## Usage Tips\n\n### CLAUDE.md or AGENTS.md Recommended Content\n\nTo add these reminders manually, include the following in `CLAUDE.md` for Claude Code, or `AGENTS.md` for opencode/codex:\n\n```\n- Prohibited from directly asking questions to users, MUST use question tool.\n- Once you can confirm that the task is complete, MUST use question tool to make user confirm. The user may respond with feedback if they are not satisfied with the result, which you can use to make improvements and try again, after try again, MUST use question tool to make user confirm again.\n```\n"}, "33e11fdbea0092509ec0062d29ec52daea7dbb1f": {"t": 1785765578.9814227, "n": 45089, "h": "5766fa1513ed4ddc", "c": "# Copilot API Proxy\n\nEnglish | [简体中文](./README.zh-CN.md)\n\n## Important Notes\n\n> [!IMPORTANT]\n> **Before using, please be aware of the following:**\n>\n> 1. **Claude Code configuration:** When using with Claude Code, please configure the model ID as `claude-opus-4-8`. Example claude `settings.json` see [Manual Configuration with `settings.json`](#manual-configuration-with-settingsjson). \n>\n> 2. **Built-in `copilot`, `codex` and third-party providers:** Run `npx @jeffreycao/copilot-api@latest auth` and choose `copilot`, `codex`, `deepseek`, `custom`, or other providers.\n>\n> 3. **Note:** See [GitHub Copilot Security Notice](./NOTICE.md#github-copilot-security-notice) for the warning removed from the README header.\n\n---\n\n## Project Overview\n\nA small AI gateway that can use GitHub Copilot, the built-in `codex` provider, or configured third-party providers such as DashScope. GitHub Copilot is optional: if no GitHub token is available, the server can still start in provider-only mode as long as at least one enabled provider is configured.\n\nThe gateway exposes OpenAI- and Anthropic-compatible APIs from one local endpoint, so tools like [Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview), OpenCode, Codex, and OpenAI-compatible clients can share the same local server.\n\nOn the GitHub Copilot path, the gateway prefers Copilot's native Anthropic-style Messages API when available, preserving more Claude-native behavior for tool-heavy workflows.\n\n## Features\n\n- **OpenAI and Anthropic compatibility**: Serve `/v1/responses`, `/v1/chat/completions`, `/v1/models`, `/v1/embeddings`, and `/v1/messages` from one local gateway.\n- **Copilot is optional**: Use GitHub Copilot when credentials are present, or run the server with only configured providers.\n- **One gateway for Copilot, `codex`, and external providers**: Route GitHub Copilot, the built-in `codex` provider, and configured third-party providers behind the same endpoint.\n- **Standalone third-party providers**: Configure providers such as DashScope, DeepSeek, OpenRouter, or a custom provider and start the gateway without a GitHub Copilot login.\n- **OpenAI-compatible providers on chat and Messages APIs**: `openai-compatible` providers can serve top-level `/v1/chat/completions` through `model: \"provider/model\"` and Anthropic-style `/v1/messages` through request/response translation.\n- **Agent-friendly Claude handling on Copilot**: Prefer native `/v1/messages` when available, preserve Claude-style tool flows, support Anthropic beta features, Claude WebSearch through Responses-capable models, and keep subagent/session markers intact.\n- **Claude Code and OpenCode integration**: Works with Claude Code and OpenCode, including direct Anthropic-compatible usage through `@ai-sdk/anthropic`.\n- **Flexible auth and deployment options**: Supports interactive login or direct tokens, individual/business/enterprise plans, GitHub Enterprise, opencode OAuth, and custom data directories.\n- **Multi-provider routing**: Expose provider-specific `/:provider/...` routes or use `model: \"provider/model\"` on the top-level API.\n\n## Prerequisites\n\n- Bun (>= 1.2.x)\n- Node.js if you plan to run the published CLI with `npx`\n- GitHub account with Copilot subscription only if you want to use the GitHub Copilot provider\n- An API key or OAuth login for at least one configured provider if you want to run without GitHub Copilot\n\n## Installation\n\nTo install dependencies, run:\n\n```sh\nbun install\n```\n\nTo start the server directly from source:\n\n```sh\nbun run start start\n```\n\n## Running from Source\n\nThe project can be run from source in several ways:\n\n### Development Mode\n\n```sh\nbun run dev start\n```\n\n### Production Mode\n\n```sh\nbun run start start\n```\n\n## Using with npx\n\nYou can run the project directly using npx:\n\n> [!IMPORTANT]\n> Token usage storage uses Node's built-in `node:sqlite` module when running with `npx`. It is enabled on Node.js >= 22.13.0. On Node.js < 22.13.0, the CLI still starts, but token usage storage is disabled.\n>\n> If you want token usage storage without upgrading Node.js, run the published CLI with Bun instead: `bunx --bun @jeffreycao/copilot-api@latest start`.\n\n```sh\nnpx @jeffreycao/copilot-api@latest start\n```\n\nWith options:\n\n```sh\nnpx @jeffreycao/copilot-api@latest start --port 8080\n```\n\nFor authentication or provider configuration only:\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth\n```\n\nTo run without GitHub Copilot, configure at least one provider first, then start the server normally:\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth login --provider dashscope\nnpx @jeffreycao/copilot-api@latest start\n```\n\n## Using with Docker\n\nBuild the image:\n\n```sh\ndocker build -t copilot-api .\n```\n\nRun the container with a bind mount so auth data survives restarts:\n\n```sh\nmkdir -p ./copilot-data\ndocker run -p 4141:4141 -v $(pwd)/copilot-data:/root/.local/share/copilot-api copilot-api\n```\n\nThis stores GitHub auth data, provider config, and other gateway state in `./copilot-data` on the host, mapped to `/root/.local/share/copilot-api` in the container.\n\nOr pass a GitHub token directly:\n\n```sh\ndocker run -p 4141:4141 -e GH_TOKEN=your_github_token_here copilot-api\n```\n\n## Electron Desktop App\n\nIf you prefer a GUI, this repository also includes an Electron desktop app in `desktop/`. It supports GitHub Copilot sign-in, OpenAI Codex OAuth, and API-key configuration for DeepSeek, DashScope, OpenRouter, or a custom provider. After authorization or provider configuration, it can start and stop the local proxy with one click and shows the local endpoint, auth header, available models, usage, and logs in the app.\n\nThe settings screen also exposes `OAuth App`, `API Home`, `Enterprise URL`, verbose logging, and minimize-to-tray. Desktop packages are published in GitHub Releases:\n\nhttps://github.com/caozhiyuan/copilot-api/releases\n\nDownload the installer for your platform, authorize or configure a provider inside the app, choose a port, start the server, then point your client at the local endpoint shown in the app. Packaged desktop builds use the bundled Electron runtime, so normal desktop usage does not require installing Node.js separately. Token usage history is enabled when that bundled runtime supports SQLite.\n\nThe desktop app's Advanced Config page reads and writes the shared model mappings through `GET/POST /admin/config/model-mappings`. The same mappings apply across `POST /v1/messages`, `POST /v1/messages/count_tokens`, `POST /v1/responses`, and `POST /v1/chat/completions` instead of being split per interface. It uses `auth.adminApiKey` instead of the regular `auth.apiKeys`, and the app reads that key directly from `config.json` after the server has generated it on startup.\n\n### Desktop App Screenshots\n\nMain dashboard, token usage breakdown in the bundled Electron app:\n\n<p align=\"center\">\n  <img src=\"./docs/screenshots/desktop-dashboard.png\" alt=\"Copilot API desktop app dashboard\" width=\"49%\" />\n  <img src=\"./docs/screenshots/desktop-token-usage.png\" alt=\"Copilot API desktop app token usage view\" width=\"49%\" />\n</p>\n\n## Using with Claude Code\n\nThis AI gateway can be used to power [Claude Code](https://docs.anthropic.com/en/claude-code), an experimental conversational AI assistant for developers from Anthropic.\n\nThere are two ways to configure Claude Code to use this AI gateway:\n\n### Interactive Setup with `--claude-code` flag\n\nTo get started, run the `start` command with the `--claude-code` flag:\n\n```sh\nnpx @jeffreycao/copilot-api@latest start --claude-code\n```\n\nYou will be prompted to select a primary model and a \"small, fast\" model for background tasks. After selecting the models, a command will be copied to your clipboard. This command sets the necessary environment variables for Claude Code to use the gateway.\n\nPaste and run this command in a new terminal to launch Claude Code.\n\n### Manual Configuration with `settings.json`\n\nAlternatively, you can configure Claude Code by creating a `.claude/settings.json` file in your project's root directory. This file should contain the environment variables needed by Claude Code. This way you don't need to run the interactive setup every time.\n\nHere is an example `.claude/settings.json` file:\n\n```json\n{\n  \"env\": {\n    \"ANTHROPIC_BASE_URL\": \"http://localhost:4141\",\n    \"ANTHROPIC_AUTH_TOKEN\": \"dummy\",\n    \"ANTHROPIC_MODEL\": \"deepseek/deepseek-v4-pro\",\n    \"ANTHROPIC_DEFAULT_SONNET_MODEL\": \"deepseek/deepseek-v4-pro\",\n    \"ANTHROPIC_DEFAULT_HAIKU_MODEL\": \"deepseek/deepseek-v4-flash\",\n    \"DISABLE_NON_ESSENTIAL_MODEL_CALLS\": \"1\",\n    \"CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC\": \"1\",\n    \"CLAUDE_CODE_ATTRIBUTION_HEADER\": \"0\",\n    \"CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION\": \"false\",\n    \"CLAUDE_CODE_DISABLE_TERMINAL_TITLE\": \"true\",\n    \"CLAUDE_CODE_ENABLE_AWAY_SUMMARY\": \"0\"\n  },\n  \"permissions\": {\n    \"deny\": [\n      \"mcp__ide__executeCode\"\n    ]\n  }\n}\n```\n\n- Replace `ANTHROPIC_MODEL`, `ANTHROPIC_DEFAULT_OPUS_MODEL`, `ANTHROPIC_DEFAULT_SONNET_MODEL`, and `ANTHROPIC_DEFAULT_HAIKU_MODEL` according to your needs. After configuration, please install the claude code plugin [Plugin Integrations](#plugin-integrations).  \n- Setting CLAUDE_CODE_ATTRIBUTION_HEADER to 0 can prevent Claude code from adding billing and version information in system prompts, thereby avoiding prompt cache invalidation.\n- Turning off CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION and CLAUDE_CODE_ENABLE_AWAY_SUMMARY can prevent quota from being consumed unnecessarily.\n- Claude Code WebSearch is supported for pure search requests. For Copilot, keep the global `messageApiWebSearchModel` set to a Responses-capable GPT model or a `provider/model` alias. For provider routes, use a native Anthropic provider or an `openai-responses` provider. Add `WebSearch` to `permissions.deny` only if you want to forbid this traffic.\n- If using a non-Claude model, do not enable ENABLE_TOOL_SEARCH. If using the Claude model, can enable ENABLE_TOOL_SEARCH. The current Claude Code uses the client tool search mode. In this mode, loading defer tools requires an additional request each time.\n- `CLAUDE_CODE_AUTO_COMPACT_WINDOW`: Set the context capacity in tokens used for auto-compaction calculations. Defaults to the model's context window: 200K for standard models or 1M for extended context models. Use a lower value like `500000` on a 1M model (e.g., `claude-opus-4-6[1m]`) to treat the window as 500K for compaction purposes. The value is capped at the model's actual context window. `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` is applied as a percentage of this value. Setting this variable decouples the compaction threshold from the status line's `used_percentage`, which always uses the model's full context window.\n\nYou can find more options here: [Claude Code settings](https://docs.anthropic.com/en/docs/claude-code/settings#environment-variables)\n\nYou can also read more about IDE integration here: [Add Claude Code to your IDE](https://docs.anthropic.com/en/docs/claude-code/ide-integrations)\n\n## Using with OpenCode\n\nOpenCode already has a direct GitHub Copilot provider. Use this section when you want OpenCode to point at this AI gateway through `@ai-sdk/anthropic` and reuse the agent behaviors described earlier in this README.\n\n### Minimal setup\n\nStart the AI gateway with the OpenCode OAuth app:\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth --oauth-app=opencode\nnpx @jeffreycao/copilot-api@latest start\n```\n\nThen point OpenCode at the gateway with `@ai-sdk/anthropic`.\n\nExample `~/.config/opencode/opencode.json`:\n\n```json\n{\n  \"$schema\": \"https://opencode.ai/config.json\",\n  \"provider\": {\n    \"local\": {\n      \"npm\": \"@ai-sdk/anthropic\",\n      \"name\": \"My Local\",\n      \"options\": {\n        \"baseURL\": \"http://localhost:4141/v1\",\n        \"apiKey\": \"dummy\"\n      },\n      \"models\": {\n        \"gpt-5.4\": {\n          \"name\": \"gpt-5.4\",\n          \"modalities\": {\n            \"input\": [\"text\", \"image\"],\n            \"output\": [\"text\"]\n          },\n          \"limit\": {\n            \"context\": 300000,\n            \"output\": 128000\n          }\n        },\n        \"claude-sonnet-4.6\": {\n          \"id\": \"claude-sonnet-4.6\",\n          \"name\": \"claude-sonnet-4.6\",\n          \"modalities\": {\n            \"input\": [\"text\", \"image\"],\n            \"output\": [\"text\"]\n          },          \n          \"limit\": {\n            \"context\": 200000,\n            \"output\": 32000\n          },\n          \"options\": {\n            \"thinking\": {\n              \"type\": \"adaptive\"\n            },\n            \"effort\": \"max\"\n          }\n        }\n      }\n    }\n  }\n}\n```\n\nWhy these fields matter:\n\n- `npm: \"@ai-sdk/anthropic\"` is the important part. OpenCode will speak Anthropic Messages semantics to this AI gateway instead of flattening everything into OpenAI Chat Completions.\n- `options.baseURL` should be `http://localhost:4141/v1`; the Anthropic SDK will append `/messages`, `/models`, and `/messages/count_tokens` automatically.\n- If you enable `auth.apiKeys` in this AI gateway, replace `dummy` with a real key. Otherwise any placeholder value is fine.\n\n## Using with Codex\n\nThis AI gateway can also power Codex.\n\n### Codex `config.toml` Reference\n\nAdd the following `[model_providers.copilot_api]` section to your Codex `~/.codex/config.toml`:\n\n```toml\nmodel_provider = \"copilot_api\"\nmodel_reasoning_summary = \"auto\"\nmodel_verbosity = \"medium\"\nmodel_context_window = 272000\nmodel_auto_compact_token_limit = 244800\n\n[model_providers.copilot_api]\nname = \"OpenAI\"\nbase_url = \"http://localhost:4141\"\nenv_key = \"GITHUB_COPILOT_API_KEY\"\nrequires_openai_auth = true\nsupports_websockets = false\nwire_api = \"responses\"\nrequest_max_retries = 3\nstream_max_retries = 1\nstream_idle_timeout_ms = 300000\n\n[features]\nremote_compaction_v2 = true\n\n[analytics]\nenabled = false\n```\n\n> [!NOTE]\n> This configuration is specific to Codex and the GitHub Copilot provider. `name` must be set to `\"OpenAI\"`. It can help mitigate Codex local compact cache miss issues. If you have enabled `useResponsesApiContextManagement` (Responses API context management compaction), `remote_compaction_v2` or local compact is generally not triggered, but it may still occur when tool results return a large number of tokens.\n\n## GPT Tool Search\n\nFor GPT Responses models such as `gpt-5.4+`, this AI gateway can expose Responses `tool_search` through a small MCP bridge. The same bridge can be used by Claude Code and opencode, as long as the client loads MCP servers and sends Anthropic Messages traffic through this gateway.\n\nDo not set Claude Code's native `ENABLE_TOOL_SEARCH` for GPT models. That flag enables Claude Code's own client-side tool search mode, and it may stop forwarding deferred tool definitions. This gateway needs the full tool definitions so it can keep the small always-loaded tool set eager and translate every other tool into Responses deferred namespaces.\n\nIf you install `tool-search@copilot-api-marketplace`, Claude Code receives this MCP bridge automatically and you can skip the manual Claude Code MCP setup below.\n\nAdd the tool search bridge to the MCP config used by Claude Code:\n\n```json\n{\n  \"mcpServers\": {\n    \"tool_search\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@jeffreycao/copilot-api@latest\", \"mcp\"]\n    }\n  }\n}\n```\n\nAdd the tool search bridge to the MCP config used by opencode:\n\n```json\n{\n  \"mcp\": {\n    \"tool_search\": {\n      \"type\": \"local\",\n      \"command\": [\"npx\", \"-y\", \"@jeffreycao/copilot-api@latest\", \"mcp\"]\n    }\n  }\n}\n```\n\nFor local development, use `bun` as the command and `[\"run\", \"./src/main.ts\", \"mcp\"]` as the args.\n\nInternally, the gateway now configures OpenAI Responses `tool_search` in client-executed mode. Deferred tools are still exposed as searchable namespaces, but the model is explicitly asked to return the exact deferred tool names it wants to load next.\n\nThe bridge uses direct tool selection, not query search. Its tool input is `names`, a comma-separated list of exact deferred tool names, for example `TaskList,TaskGet,mcp__fetch__fetch`.\n\n## Plugin Integrations\n\nPlugin integrations are available for Claude Code and opencode.\n\n#### Claude Code plugin integration (marketplace-based)\n\nThe Claude Code integration is packaged as two plugins:\n\n- `agent-inject` injects `__SUBAGENT_MARKER__...` on `SubagentStart`, so the gateway can infer `x-initiator: agent`.\n- `tool-search` registers the `tool_search` MCP bridge used for GPT Responses deferred tool loading.\n\n- Marketplace catalog in this repository: `.claude-plugin/marketplace.json`\n- Plugin sources in this repository: `plugin/claude/agent-inject`, `plugin/claude/tool-search`\n\nAdd the marketplace remotely:\n\n```sh\n/plugin marketplace add https://github.com/caozhiyuan/copilot-api.git\n```\n\nInstall the plugins from the marketplace:\n\n```sh\n/plugin install agent-inject@copilot-api-marketplace\n/plugin install tool-search@copilot-api-marketplace\n```\n\nAfter installation, `agent-inject` injects `__SUBAGENT_MARKER__...` on `SubagentStart`, and the gateway uses it to infer `x-initiator: agent`.\n\nThe `agent-inject` plugin also registers a `UserPromptSubmit` hook that returns `{\"continue\": true}`, and it can inject `SessionStart` reminder rules through environment variables:\n\n- `CLAUDE_PLUGIN_ENABLE_QUESTION_RULES=1` enables the two reminders about using the `question` tool automatically for Claude Code. Alternatively, you can add the same reminders manually in `CLAUDE.md`; see [CLAUDE.md or AGENTS.md Recommended Content](#claudemd-or-agentsmd-recommended-content).\n- `CLAUDE_PLUGIN_ENABLE_NO_BACKGROUND_AGENTS_RULE=1` enables the `run_in_background: true` avoidance reminder for agent hooks.\n\nThe `tool-search` plugin bundles the same MCP bridge described in [GPT Tool Search](#gpt-tool-search), so Claude Code users do not need to add the `tool_search` server manually when they install that plugin.\n\n#### Opencode plugin\n\nThe subagent marker producer is packaged as an opencode plugin located at `plugin/opencode/subagent-marker.js`.\n\n**Installation:**\n\nCopy the plugin file to your opencode plugins directory:\n\n```sh\n# Clone or download this repository, then copy the plugin\ncp plugin/opencode/subagent-marker.js ~/.config/opencode/plugins/\n```\n\nOr manually create the file at `~/.config/opencode/plugins/subagent-marker.js` with the plugin content.\n\n**Features:**\n\n- Tracks sub-sessions created by subagents\n- Automatically prepends a marker system reminder (`__SUBAGENT_MARKER__...`) to subagent chat messages\n- Sets `x-session-id` header for session tracking\n- Enables the gateway to infer `x-initiator: agent` for subagent-originated requests\n\nThe plugin hooks into `session.created`, `session.deleted`, `chat.message`, and `chat.headers` events to provide seamless subagent marker functionality.\n\n## Using the Usage Viewer\n\nAfter starting the server, a URL to the Copilot Usage Dashboard will be displayed in your console. This dashboard is a web interface for monitoring your API usage.\n\n1.  Start the server. For example, using npx:\n    ```sh\n    npx @jeffreycao/copilot-api@latest start\n    ```\n2.  The server will output a URL to the usage viewer. Copy and paste this URL into your browser. It will look something like this:\n    `http://localhost:4141/usage-viewer?endpoint=http://localhost:4141/usage`\n    - If you use the `start.bat` script on Windows, this page will open automatically.\n\nThe dashboard provides a user-friendly interface to view your Copilot usage data:\n\n> Token usage history requires Bun or Node.js >= 22.13.0. On Node.js < 22.13.0, the server runs normally but token usage storage is disabled.\n\n- **API Endpoint URL**: The dashboard is pre-configured to fetch data from your local server endpoint via a URL query parameter. You can manually switch this to any other compatible API endpoint.\n- **x-api-key Authentication**: If API Key authentication is enabled, you can provide the `x-api-key` request header. The key is persisted in the browser's local storage.\n- **Period Selector**: Choose from Day, Week, or Month time ranges. The URL query parameter updates automatically when you switch, making it easy to bookmark and share.\n- **Fetch Data**: Click the \"Refresh\" button to load or refresh the usage data. The dashboard also fetches data automatically on page load.\n- **Copilot Quotas**: View quota usage for services such as Chat and Completions via progress bars. Hover over a card to see used/remaining details.\n- **Token Usage Metric Cards**: See a summary of Total, Input, Output, Cache Read, Cache Write, Requests, and estimated cost for the current period.\n- **Trend Chart (Week / Month)**: An interactive line chart with model and metric filters. Click a data point to inspect the usage breakdown for a specific day.\n- **Model Breakdown Table**: A per-model summary of requests, input/output/cache tokens, and estimated cost for the selected period.\n- **Request Events (Paginated)**: A time-sorted list of request event records with pagination support, showing timestamps, models, request IDs, and token counts.\n- **Detailed Information**: See the full JSON response from the API for a detailed breakdown of all available usage statistics.\n- **URL-based Configuration**: You can also specify the API endpoint and period directly via `endpoint` and `period` query parameters. For example:\n  `http://localhost:4141/usage-viewer?endpoint=http://your-api-server/usage&period=week`\n\n### Usage Viewer Screenshot\n\n<p align=\"center\">\n  <img src=\"./docs/screenshots/usage-viewer.png\" alt=\"Copilot API usage viewer\" width=\"900\" />\n</p>\n\n## Command Structure\n\nCopilot API now uses a subcommand structure with these main commands:\n\n- `start`: Start the gateway server. If a GitHub token is available, the server starts with Copilot enabled. If no GitHub token is available, it starts in provider-only mode when at least one enabled provider exists; otherwise it guides you through provider setup.\n- `auth`: Run provider login or configuration without starting the server. Use it for GitHub Copilot login, Codex OAuth, or third-party provider API key setup.\n- `debug`: Display diagnostic information including version, runtime details, file paths, and authentication status. Useful for troubleshooting and support.\n\n## Command Line Options\n\n### Global Options\n\nThe following options can be used with any subcommand. When passing them before the subcommand, use the `--key=value` form:\n\n| Option            | Description                                            | Default | Alias |\n| ----------------- | ------------------------------------------------------ | ------- | ----- |\n| --api-home        | Path to the API home directory (sets COPILOT_API_HOME) | none    | none  |\n| --oauth-app       | OAuth app identifier (sets COPILOT_API_OAUTH_APP)      | none    | none  |\n| --enterprise-url  | Enterprise URL for GitHub (sets COPILOT_API_ENTERPRISE_URL) | none | none |\n\n### Start Command Options\n\nThe following command line options are available for the `start` command:\n\n| Option         | Description                                                                   | Default    | Alias |\n| -------------- | ----------------------------------------------------------------------------- | ---------- | ----- |\n| --port         | Port to listen on                                                             | 4141       | -p    |\n| --verbose      | Enable verbose logging                                                        | false      | -v    |\n| --github-token | Provide GitHub token directly (must be generated using the `auth` subcommand) | none       | -g    |\n| --claude-code  | Generate a command to launch Claude Code with Copilot API config              | false      | -c    |\n| --show-token   | Show GitHub and Copilot tokens on fetch and refresh                           | false      | none  |\n| --proxy-env    | Initialize proxy from environment variables                                   | false      | none  |\n\n### Auth Command Options\n\n| Option       | Description               | Default | Alias |\n| ------------ | ------------------------- | ------- | ----- |\n| --provider   | Provider to log in with or configure (`copilot`, `codex`, `deepseek`, `dashscope`, `openrouter`, or `custom`) | prompt | none |\n| --verbose    | Enable verbose logging    | false   | -v    |\n| --show-token | Show GitHub token on auth | false   | none  |\n\nUse `copilot-api auth login --provider copilot` only when you want to enable the GitHub Copilot provider. Copilot is not required for `codex` or third-party provider-only usage.\n\nUse `copilot-api auth login --provider deepseek`, `--provider dashscope`, or `--provider openrouter` to add or update those common third-party providers from the CLI. DeepSeek prompts for masked `apiKey`, provider `type` (default `anthropic`), and `baseUrl` defaulting to `https://api.deepseek.com/anthropic`. DashScope prompts for masked `apiKey`, provider `type` (default `openai-compatible`), and prefilled `baseUrl`. OpenRouter prompts for masked `apiKey` and prefilled `baseUrl` only, and writes `type: \"anthropic\"`. After a provider is configured and enabled, `copilot-api start` can run without any GitHub token.\n\nUse `copilot-api auth login --provider custom` to add or update another third-party provider from the CLI. The command prompts for the provider name, supported type (`anthropic`, `openai-compatible`, or `openai-responses`), `baseUrl`, masked `apiKey`, and `authType`; `authType` may be left as the type default or set to `x-api-key` / `authorization`.\n\n### Debug Command Options\n\n| Option | Description               | Default | Alias |\n| ------ | ------------------------- | ------- | ----- |\n| --json | Output debug info as JSON | false   | none  |\n\n## Configuration (config.json)\n\n- **Location:** `~/.local/share/copilot-api/config.json` (Linux/macOS) or `%USERPROFILE%\\.local\\share\\copilot-api\\config.json` (Windows).\n- **Default shape:**\n  ```json\n  {\n    \"auth\": {\n      \"apiKeys\": [],\n      \"adminApiKey\": \"<auto-generated-on-startup>\"\n    },\n    \"providers\": {},\n    \"modelMappings\": {},\n    \"extraPrompts\": {\n      \"gpt-5-mini\": \"<built-in exploration prompt>\",\n      \"gpt-5.3-codex\": \"<built-in commentary prompt>\",\n      \"gpt-5.4-mini\": \"<built-in commentary prompt>\",\n      \"gpt-5.4\": \"<built-in commentary prompt>\",\n      \"gpt-5.5\": \"<built-in commentary prompt>\"\n    },\n    \"smallModel\": \"gpt-5-mini\",\n    \"useResponsesApiContextManagement\": true,\n    \"modelResponsesApiCompactThresholds\": {\n      \"gpt-5.4\": 217600,\n      \"gpt-5.5\": 217600\n    },\n    \"modelReasoningEfforts\": {\n      \"gpt-5-mini\": \"low\",\n      \"gpt-5.3-codex\": \"xhigh\",\n      \"gpt-5.4-mini\": \"xhigh\",\n      \"gpt-5.4\": \"xhigh\",\n      \"gpt-5.5\": \"xhigh\"\n    },\n    \"useMessagesApi\": true,\n    \"useResponsesApiWebSocket\": true,\n    \"useResponsesApiWebSearch\": true,\n    \"messageApiWebSearchModel\": \"gpt-5-mini\"\n  }\n  ```\n- **auth.apiKeys:** API keys used for request authentication on non-admin routes. Supports multiple keys for rotation. Requests can authenticate with either `x-api-key: <key>` or `Authorization: Bearer <key>`. If empty or omitted, authentication for non-admin routes is disabled.\n- **auth.adminApiKey:** Single admin key used only for `/admin/*` routes. If missing, the server generates a random key at startup and writes it back to `config.json`. Requests use the same `x-api-key` or `Authorization: Bearer` headers, but regular `auth.apiKeys` never grant access to `/admin/*`.\n- **modelMappings:** Exact `sourceModel -> targetModel` rewrites shared by top-level `POST /v1/messages`, `POST /v1/messages/count_tokens`, `POST /v1/responses`, and `POST /v1/chat/completions` requests. Omit it or leave it as `{}` to disable rewrites. Both the source and target must be non-empty strings. Targets can be regular model IDs or `provider/model` aliases such as `dashscope/qwen3.6-plus`, and the rewrite happens before provider alias parsing. These mappings are not split per interface. The admin endpoints `GET/POST /admin/config/model-mappings` read and update only this field.\n- **extraPrompts:** Map of `model -> prompt` appended to the first system prompt when translating Anthropic-style requests to Copilot. Use this to inject guardrails or guidance per model. Missing default entries are auto-added without overwriting your custom prompts. The built-in prompts for `gpt-5.3-codex` and `gpt-5.4` enable phase-aware commentary, which lets the model emit a short user-facing progress update before tools or deeper reasoning.\n- **providers:** Global upstream provider map. Each provider key (for example `dashscope`) becomes a route prefix (`/dashscope/v1/messages`). Supports `type: \"anthropic\"`, `type: \"openai-compatible\"`, and `type: \"openai-responses\"`. Top-level clients can also use `model: \"dashscope/model-id\"` with `/v1/messages`, `/v1/messages/count_tokens`, `/v1/responses`, and `/v1/chat/completions`; the gateway strips the `dashscope/` prefix before forwarding upstream. `openai-compatible` providers support both chat and Messages flows: `/v1/chat/completions` is proxied to upstream `/v1/chat/completions`, while `/v1/messages` and `/:provider/v1/messages` are translated to upstream chat completions and translated back to Anthropic Messages responses. `GET /v1/models` aggregates enabled provider models with `provider/model-id` IDs; use `GET /dashscope/v1/models` for a single provider's raw model list.\n  - `enabled` defaults to `true` if omitted.\n  - `baseUrl` should be provider API base URL without the final endpoint. For Anthropic providers, omit `/v1/messages`; for OpenAI-compatible providers, omit `/v1/chat/completions`; for OpenAI Responses providers, omit `/v1/responses`.\n  - `apiKey` is used as the upstream credential value and is required for regular providers.\n  - `authType` (optional): Controls how `apiKey` is sent upstream. Supports `x-api-key` and `authorization` for regular providers. Anthropic providers default to `x-api-key`; OpenAI-compatible and OpenAI Responses providers default to `authorization`. When set to `authorization`, the proxy sends `Authorization: Bearer <apiKey>`. `oauth2` is reserved for the built-in `codex` provider and is written automatically by `auth login --provider codex`.\n  - `pricingCurrency` (optional): Provider-level currency used for token cost calculation, for example `USD` or `CNY`. Quick providers default to `CNY` for DashScope and DeepSeek, and `USD` for Codex/OpenRouter. Costs are grouped by currency and are not exchange-rate converted.\n  - `models` (optional): Per-model configuration map. Each key is a model ID (matching the model name in requests), and the value is:\n    - `temperature` (optional): Default temperature value used when the request does not specify one.\n    - `topP` (optional): Default top_p value used when the request does not specify one.\n    - `topK` (optional): Default top_k value used when the request does not specify one.\n    - `extraBody` (optional): Dynamic fields merged into the upstream request body for that model. Request body fields with the same name take precedence. OpenAI-compatible providers can use this for fields such as `enable_thinking`, `preserve_thinking`, `reasoning_effort`. `thinking_budget` is a special OpenAI-compatible provider override: when configured in `extraBody`, it is forced after Anthropic `thinking.budget_tokens` translation and overrides the request-derived budget. For providers whose name is `dashscope` or whose `baseUrl` contains `aliyuncs.com`, the request-derived `thinking_budget` (from Anthropic `thinking.budget_tokens`) is forwarded upstream; for other OpenAI-compatible providers the request-derived `thinking_budget` is stripped, while an `extraBody` `thinking_budget` is still honored.\n    - `pricing` (optional): Per-model token prices, in the provider `pricingCurrency`, per 1M tokens. Supported fields are `input`, `output`, `cachedInput` (implicit cache read), `explicitCachedInput` (explicit cache read), and `cacheCreationInput`. Use `tiers` with `maxInputTokens` for input-size tiered pricing.\n    - `contextCache` (optional): Defaults to `true` for providers whose name is `dashscope` or whose `baseUrl` contains `aliyuncs.com`; defaults to `false` for other OpenAI-compatible providers. This enables Alibaba Cloud Model Studio/DashScope explicit context cache by injecting `cache_control: { \"type\": \"ephemeral\" }` on up to 4 content blocks using the Context Cache format. The cache breakpoint strategy matches opencode's main provider flow: the first 2 system messages plus the last 2 non-system messages. Marked string content is converted to text content part arrays for `system` / `user` / `assistant` / `tool` messages; existing array content is marked on the last part. Set this to `false` when the model already supports implicit caching, or when the upstream does not accept this explicit-cache extension field. Set this to `true` for non-DashScope providers that support the same explicit-cache extension.\n    - `supportPdf` (optional): Controls whether the model supports PDF/document content. Defaults to `false`; unsupported PDFs are converted to a text notice. Set it to `true` to send PDF/document blocks as OpenAI Chat Completions file parts.\n    - `toolContentSupportType` (optional): Tool result content capabilities for that model, as an array of `array`, `image`, and `pdf`. Provider routes default to string-only tool content when omitted. If `supportPdf` is `true` but this list does not include `pdf`, file parts in tool results are moved to user role messages. This provider default does not change the Copilot main flow, which continues to support array + image and not PDF.\n\n  Example DashScope model settings:\n  ```json\n  {\n    \"providers\": {\n      \"dashscope\": {\n        \"type\": \"openai-compatible\",\n        \"enabled\": true,\n        \"baseUrl\": \"https://dashscope.aliyuncs.com/compatible-mode\",\n        \"apiKey\": \"sk-your-dashscope-key\",\n        \"pricingCurrency\": \"CNY\",\n        \"models\": {\n          \"qwen3.7-plus\": {\n            \"temperature\": 1,\n            \"topP\": 0.95,\n            \"topK\": 20,\n            \"extraBody\": {\n              \"preserve_thinking\": true\n            }\n          },\n          \"glm-5.1\": {\n            \"temperature\": 0.7,\n            \"topP\": 0.95,\n            \"contextCache\": true,\n            \"pricing\": {\n              \"tiers\": [\n                {\n                  \"maxInputTokens\": 32000,\n                  \"input\": 6,\n                  \"cachedInput\": 1.2,\n                  \"explicitCachedInput\": 0.6,\n                  \"cacheCreationInput\": 7.5,\n                  \"output\": 24\n                },\n                {\n                  \"maxInputTokens\": 200000,\n                  \"input\": 8,\n                  \"cachedInput\": 1.6,\n                  \"explicitCachedInput\": 0.8,\n                  \"cacheCreationInput\": 10,\n                  \"output\": 28\n                }\n              ]\n            },\n            \"extraBody\": {\n              \"preserve_thinking\": true\n            }\n          }\n        }\n      }\n    }\n  }\n  ```\n  Built-in token prices cover Codex GPT models in USD, DashScope `qwen3.7-max`, `qwen3.7-plus`, `glm-5.1`, `glm-5.2` in CNY, and DeepSeek `deepseek-v4-flash`, `deepseek-v4-pro`, `deepseek-chat`, `deepseek-reasoner` in CNY. User `pricing` entries override built-ins. For DashScope, cached tokens are charged as explicit cache reads when the upstream usage includes `cache_creation_input_tokens`; otherwise `cachedInput` is used as the implicit cache read price. For DeepSeek, `prompt_cache_hit_tokens` map to cached input and `prompt_cache_miss_tokens` map to regular input.\n- **smallModel:** Fallback model used for tool-less warmup messages (e.g., Claude Code probe requests); defaults to gpt-5-mini.\n- **useResponsesApiContextManagement:** When `true`, the proxy adds Responses API `context_management` compaction instructions. Defaults to `true`. Set it to `false` to disable this globally. When enabled, the request includes `context_management` in the body and keeps only the latest compaction carrier on follow-up turns. This is especially useful for long-running tasks.\n- **modelResponsesApiCompactThresholds:** Per-model Responses API `compact_threshold` overrides used when the proxy adds `context_management`. These values take precedence over the fallback threshold from `resolveResponsesCompactThreshold` (`max_prompt_tokens * ratio`, or the default fallback). Defaults set `gpt-5.4` and `gpt-5.5` to `217600` (`272000 * 0.8`). Models not listed continue to use the normal fallback logic.\n- **modelReasoningEfforts:** Per-model `reasoning.effort` sent to the Copilot Responses API. Allowed values are `none`, `minimal`, `low`, `medium`, `high`, and `xhigh`. If a model isn't listed, `high` is used by default.\n- **useMessagesApi:** When `true`, Claude-family models that support Copilot's native `/v1/messages` endpoint will use the Messages API; otherwise they fall back to `/chat/completions`. Set to `false` to disable Messages API routing and always use `/chat/completions`. Defaults to `true`.\n- **useResponsesApiWebSocket:** When `true`, Responses API requests use Copilot's websocket transport for models that advertise `ws:/responses`; models that only advertise `/responses` continue to use HTTP. Set to `false` to disable websocket routing and use HTTP `/responses` whenever the selected model supports it. Defaults to `true`.\n- **useResponsesApiWebSearch:** When `true`, the server keeps Responses API tools with `type: \"web_search\"` and forwards them upstream. Set to `false` to strip those tools from `/responses` payloads. Defaults to `true`.\n- **messageApiWebSearchModel:** Global fallback model used when a top-level Copilot `/v1/messages` request contains only the server-side `web_search` tool. Defaults to `gpt-5-mini`. If the value is a `provider/model` alias, the request is routed into that provider's Messages API path with the provider prefix stripped. For Copilot GPT models, web search runs through `/responses`. Mixed `web_search` plus custom tools are not supported and the server-side `web_search` tool is stripped.\n- **claudeTokenMultiplier:** Multiplier applied to the fallback GPT-tokenizer estimate for Claude `/v1/messages/count_tokens` requests. Defaults to `1.15`. Increase it if your client is still compacting too late. This setting is only used when the proxy is estimating Claude tokens locally; if `anthropicApiKey` is configured and Anthropic token counting succeeds, the exact Anthropic count is returned instead.\n- **anthropicApiKey:** Anthropic API key used to forward Claude `/v1/messages/count_tokens` requests to Anthropic's real token counting endpoint, which returns exact counts instead of GPT tokenizer estimates. Can also be set via the `ANTHROPIC_API_KEY` environment variable. If not set, or if the upstream call fails, token counting falls back to local GPT tokenizer estimation controlled by `claudeTokenMultiplier`.\n\nEdit this file to customize prompts or swap in your own fast model. Restart the server (or rerun the command) after changes so the cached config is refreshed.\n\n## API Authentication\n\n- **Protected non-admin routes:** All routes except `/`, `/usage-viewer`, and `/usage-viewer/` require authentication when `auth.apiKeys` is configured and non-empty.\n- **Admin routes:** All `/admin/*` routes require `auth.adminApiKey`. If it is missing, the server generates one at startup and persists it to `config.json` before serving requests.\n- **Allowed auth headers:**\n  - `x-api-key: <your_key>`\n  - `Authorization: Bearer <your_key>`\n- **CORS preflight:** `OPTIONS` requests are always allowed.\n- **When no regular keys are configured:** Non-admin routes continue to allow requests. This does not apply to `/admin/*`, which only accepts `auth.adminApiKey`.\n\nExample request for a regular protected route:\n\n```sh\ncurl http://localhost:4141/v1/models \\\n  -H \"x-api-key: your_api_key\"\n```\n\nExample request for an admin route:\n\n```sh\ncurl http://localhost:4141/admin/config/model-mappings \\\n  -H \"x-api-key: your_admin_api_key\"\n```\n\n## API Endpoints\n\nThe server exposes several OpenAI- and Anthropic-compatible endpoints. Requests can target GitHub Copilot, the built-in `codex` provider, or configured providers depending on the selected model and `provider/model` alias.\n\n### OpenAI Compatible Endpoints\n\nThese endpoints mimic the OpenAI API structure.\n\n| Endpoint                    | Method | Description                                                      |\n| --------------------------- | ------ | ---------------------------------------------------------------- |\n| `POST /v1/responses`        | `POST` | OpenAI Most advanced interface for generating model responses. Supports `provider/model` aliases for `openai-responses` providers. |\n| `POST /v1/chat/completions` | `POST` | Creates a model response for the given chat conversation. Supports `provider/model` aliases for `openai-compatible` providers and can be used without Copilot when the target provider is configured. |\n| `GET /v1/models`            | `GET`  | Lists Copilot models plus enabled provider models using `provider/model-id` IDs. |\n| `POST /v1/embeddings`       | `POST` | Creates an embedding vector representing the input text.         |\n\n### Anthropic Compatible Endpoints\n\nThese endpoints are designed to be compatible with the Anthropic Messages API.\n\n| Endpoint                         | Method | Description                                                  |\n| -------------------------------- | ------ | ------------------------------------------------------------ |\n| `POST /v1/messages`              | `POST` | Creates a model response for a given conversation. Supports `provider/model` aliases for configured providers, including translation through `openai-compatible` providers. |\n| `POST /v1/messages/count_tokens` | `POST` | Calculates the number of tokens for a given set of messages. Supports `provider/model` aliases for configured providers. |\n| `POST /:provider/v1/messages`       | `POST` | Proxies Anthropic Messages requests to the configured Anthropic provider, translates them through an OpenAI-compatible provider, or translates them through an OpenAI Responses provider. |\n| `GET /:provider/v1/models`          | `GET`  | Proxies model listing requests to the configured provider.   |\n| `POST /:provider/v1/messages/count_tokens` | `POST` | Calculates tokens locally for provider route requests. |\n\n### Usage Monitoring Endpoints\n\nNew endpoints for monitoring your Copilot usage and quotas.\n\n| Endpoint     | Method | Description                                                  |\n| ------------ | ------ | ------------------------------------------------------------ |\n| `GET /usage` | `GET`  | Get detailed Copilot usage statistics and quota information. |\n| `GET /token` | `GET`  | Get the current Copilot token being used by the API.         |\n\n### Admin / Configuration Endpoints\n\nThese endpoints are reserved for local administrative actions and only accept `auth.adminApiKey`.\n\n| Endpoint                              | Method | Description                                                                 |\n| ------------------------------------- | ------ | --------------------------------------------------------------------------- |\n| `GET /admin/config/model-mappings`    | `GET`  | Returns the current `config.json` path and the active `modelMappings` map.  |\n| `POST /admin/config/model-mappings`   | `POST` | Updates only the `modelMappings` field in `config.json` and returns it back. |\n\n## Example Usage\n\nCommon `npx` commands:\n\n```sh\n# Start the gateway\nnpx @jeffreycao/copilot-api@latest start\n\n# Start on a custom port with verbose logging\nnpx @jeffreycao/copilot-api@latest start --port 8080 --verbose\n\n# Run the auth flow\nnpx @jeffreycao/copilot-api@latest auth login\n\n# Configure a third-party provider, then run without GitHub Copilot\nnpx @jeffreycao/copilot-api@latest auth login --provider dashscope\nnpx @jeffreycao/copilot-api@latest start\n\n# Print debug information as JSON\nnpx @jeffreycao/copilot-api@latest debug --json\n\n# Run the published CLI with Bun instead of Node.js\nbunx --bun @jeffreycao/copilot-api@latest start\n```\n\nOpenAI-compatible provider examples after configuring `dashscope`:\n\n```sh\ncurl http://localhost:4141/v1/chat/completions \\\n  -H \"content-type: application/json\" \\\n  -d '{\"model\":\"dashscope/qwen3.6-plus\",\"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]}'\n\ncurl http://localhost:4141/dashscope/v1/messages \\\n  -H \"content-type: application/json\" \\\n  -d '{\"model\":\"qwen3.6-plus\",\"max_tokens\":1024,\"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]}'\n```\n\n## Usage Tips\n\n### CLAUDE.md or AGENTS.md Recommended Content\n\nTo add these reminders manually, include the following in `CLAUDE.md` for Claude Code, or `AGENTS.md` for opencode/codex:\n\n```\n- Prohibited from directly asking questions to users, MUST use question tool.\n- Once you can confirm that the task is complete, MUST use question tool to make user confirm. The user may respond with feedback if they are not satisfied with the result, which you can use to make improvements and try again, after try again, MUST use question tool to make user confirm again.\n```\n"}, "eaaab7b7e772ba8bad0b88cc906fb56001bbccae": {"t": 1785765580.5360377, "n": 44551, "h": "2e13dbc9d8d9d141", "c": "# Copilot API Proxy\n\nEnglish | [简体中文](./README.zh-CN.md)\n\n## Important Notes\n\n> [!IMPORTANT]\n> **Before using, please be aware of the following:**\n>\n> 1. **Claude Code configuration:** When using with Claude Code, please configure the model ID as `claude-opus-4-8`. Example claude `settings.json` see [Manual Configuration with `settings.json`](#manual-configuration-with-settingsjson). \n>\n> 2. **Built-in `copilot`, `codex` and third-party providers:** Run `npx @jeffreycao/copilot-api@latest auth` and choose `copilot`, `codex`, `deepseek`, `custom`, or other providers.\n>\n> 3. **Note:** See [GitHub Copilot Security Notice](./NOTICE.md#github-copilot-security-notice) for the warning removed from the README header.\n\n---\n\n## Project Overview\n\nA small AI gateway that can use GitHub Copilot, the built-in `codex` provider, or configured third-party providers such as DashScope. GitHub Copilot is optional: if no GitHub token is available, the server can still start in provider-only mode as long as at least one enabled provider is configured.\n\nThe gateway exposes OpenAI- and Anthropic-compatible APIs from one local endpoint, so tools like [Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview), OpenCode, Codex, and OpenAI-compatible clients can share the same local server.\n\nOn the GitHub Copilot path, the gateway prefers Copilot's native Anthropic-style Messages API when available, preserving more Claude-native behavior for tool-heavy workflows.\n\n## Features\n\n- **OpenAI and Anthropic compatibility**: Serve `/v1/responses`, `/v1/chat/completions`, `/v1/models`, `/v1/embeddings`, and `/v1/messages` from one local gateway.\n- **Copilot is optional**: Use GitHub Copilot when credentials are present, or run the server with only configured providers.\n- **One gateway for Copilot, `codex`, and external providers**: Route GitHub Copilot, the built-in `codex` provider, and configured third-party providers behind the same endpoint.\n- **Standalone third-party providers**: Configure providers such as DashScope, DeepSeek, OpenRouter, or a custom provider and start the gateway without a GitHub Copilot login.\n- **OpenAI-compatible providers on chat and Messages APIs**: `openai-compatible` providers can serve top-level `/v1/chat/completions` through `model: \"provider/model\"` and Anthropic-style `/v1/messages` through request/response translation.\n- **Agent-friendly Claude handling on Copilot**: Prefer native `/v1/messages` when available, preserve Claude-style tool flows, support Anthropic beta features, Claude WebSearch through Responses-capable models, and keep subagent/session markers intact.\n- **Claude Code and OpenCode integration**: Works with Claude Code and OpenCode, including direct Anthropic-compatible usage through `@ai-sdk/anthropic`.\n- **Flexible auth and deployment options**: Supports interactive login or direct tokens, individual/business/enterprise plans, GitHub Enterprise, opencode OAuth, and custom data directories.\n- **Multi-provider routing**: Expose provider-specific `/:provider/...` routes or use `model: \"provider/model\"` on the top-level API.\n\n## Prerequisites\n\n- Bun (>= 1.2.x)\n- Node.js if you plan to run the published CLI with `npx`\n- GitHub account with Copilot subscription only if you want to use the GitHub Copilot provider\n- An API key or OAuth login for at least one configured provider if you want to run without GitHub Copilot\n\n## Installation\n\nTo install dependencies, run:\n\n```sh\nbun install\n```\n\nTo start the server directly from source:\n\n```sh\nbun run start start\n```\n\n## Running from Source\n\nThe project can be run from source in several ways:\n\n### Development Mode\n\n```sh\nbun run dev start\n```\n\n### Production Mode\n\n```sh\nbun run start start\n```\n\n## Using with npx\n\nYou can run the project directly using npx:\n\n> [!IMPORTANT]\n> Token usage storage uses Node's built-in `node:sqlite` module when running with `npx`. It is enabled on Node.js >= 22.13.0. On Node.js < 22.13.0, the CLI still starts, but token usage storage is disabled.\n>\n> If you want token usage storage without upgrading Node.js, run the published CLI with Bun instead: `bunx --bun @jeffreycao/copilot-api@latest start`.\n\n```sh\nnpx @jeffreycao/copilot-api@latest start\n```\n\nWith options:\n\n```sh\nnpx @jeffreycao/copilot-api@latest start --port 8080\n```\n\nFor authentication or provider configuration only:\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth\n```\n\nTo run without GitHub Copilot, configure at least one provider first, then start the server normally:\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth login --provider dashscope\nnpx @jeffreycao/copilot-api@latest start\n```\n\n## Using with Docker\n\nBuild the image:\n\n```sh\ndocker build -t copilot-api .\n```\n\nRun the container with a bind mount so auth data survives restarts:\n\n```sh\nmkdir -p ./copilot-data\ndocker run -p 4141:4141 -v $(pwd)/copilot-data:/root/.local/share/copilot-api copilot-api\n```\n\nThis stores GitHub auth data, provider config, and other gateway state in `./copilot-data` on the host, mapped to `/root/.local/share/copilot-api` in the container.\n\nOr pass a GitHub token directly:\n\n```sh\ndocker run -p 4141:4141 -e GH_TOKEN=your_github_token_here copilot-api\n```\n\n## Electron Desktop App\n\nIf you prefer a GUI, this repository also includes an Electron desktop app in `desktop/`. It supports GitHub Copilot sign-in, OpenAI Codex OAuth, and API-key configuration for DeepSeek, DashScope, OpenRouter, or a custom provider. After authorization or provider configuration, it can start and stop the local proxy with one click and shows the local endpoint, auth header, available models, usage, and logs in the app.\n\nThe settings screen also exposes `OAuth App`, `API Home`, `Enterprise URL`, verbose logging, and minimize-to-tray. Desktop packages are published in GitHub Releases:\n\nhttps://github.com/caozhiyuan/copilot-api/releases\n\nDownload the installer for your platform, authorize or configure a provider inside the app, choose a port, start the server, then point your client at the local endpoint shown in the app. Packaged desktop builds use the bundled Electron runtime, so normal desktop usage does not require installing Node.js separately. Token usage history is enabled when that bundled runtime supports SQLite.\n\nThe desktop app's Advanced Config page reads and writes the shared model mappings through `GET/POST /admin/config/model-mappings`. The same mappings apply across `POST /v1/messages`, `POST /v1/messages/count_tokens`, `POST /v1/responses`, and `POST /v1/chat/completions` instead of being split per interface. It uses `auth.adminApiKey` instead of the regular `auth.apiKeys`, and the app reads that key directly from `config.json` after the server has generated it on startup.\n\n### Desktop App Screenshots\n\nMain dashboard, token usage breakdown in the bundled Electron app:\n\n<p align=\"center\">\n  <img src=\"./docs/screenshots/desktop-dashboard.png\" alt=\"Copilot API desktop app dashboard\" width=\"49%\" />\n  <img src=\"./docs/screenshots/desktop-token-usage.png\" alt=\"Copilot API desktop app token usage view\" width=\"49%\" />\n</p>\n\n## Using with Claude Code\n\nThis AI gateway can be used to power [Claude Code](https://docs.anthropic.com/en/claude-code), an experimental conversational AI assistant for developers from Anthropic.\n\nThere are two ways to configure Claude Code to use this AI gateway:\n\n### Interactive Setup with `--claude-code` flag\n\nTo get started, run the `start` command with the `--claude-code` flag:\n\n```sh\nnpx @jeffreycao/copilot-api@latest start --claude-code\n```\n\nYou will be prompted to select a primary model and a \"small, fast\" model for background tasks. After selecting the models, a command will be copied to your clipboard. This command sets the necessary environment variables for Claude Code to use the gateway.\n\nPaste and run this command in a new terminal to launch Claude Code.\n\n### Manual Configuration with `settings.json`\n\nAlternatively, you can configure Claude Code by creating a `.claude/settings.json` file in your project's root directory. This file should contain the environment variables needed by Claude Code. This way you don't need to run the interactive setup every time.\n\nHere is an example `.claude/settings.json` file:\n\n```json\n{\n  \"env\": {\n    \"ANTHROPIC_BASE_URL\": \"http://localhost:4141\",\n    \"ANTHROPIC_AUTH_TOKEN\": \"dummy\",\n    \"ANTHROPIC_MODEL\": \"deepseek/deepseek-v4-pro\",\n    \"ANTHROPIC_DEFAULT_SONNET_MODEL\": \"deepseek/deepseek-v4-pro\",\n    \"ANTHROPIC_DEFAULT_HAIKU_MODEL\": \"deepseek/deepseek-v4-flash\",\n    \"DISABLE_NON_ESSENTIAL_MODEL_CALLS\": \"1\",\n    \"CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC\": \"1\",\n    \"CLAUDE_CODE_ATTRIBUTION_HEADER\": \"0\",\n    \"CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION\": \"false\",\n    \"CLAUDE_CODE_DISABLE_TERMINAL_TITLE\": \"true\",\n    \"CLAUDE_CODE_ENABLE_AWAY_SUMMARY\": \"0\"\n  },\n  \"permissions\": {\n    \"deny\": [\n      \"mcp__ide__executeCode\"\n    ]\n  }\n}\n```\n\n- Replace `ANTHROPIC_MODEL`, `ANTHROPIC_DEFAULT_OPUS_MODEL`, `ANTHROPIC_DEFAULT_SONNET_MODEL`, and `ANTHROPIC_DEFAULT_HAIKU_MODEL` according to your needs. After configuration, please install the claude code plugin [Plugin Integrations](#plugin-integrations).  \n- Setting CLAUDE_CODE_ATTRIBUTION_HEADER to 0 can prevent Claude code from adding billing and version information in system prompts, thereby avoiding prompt cache invalidation.\n- Turning off CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION and CLAUDE_CODE_ENABLE_AWAY_SUMMARY can prevent quota from being consumed unnecessarily.\n- Claude Code WebSearch is supported for pure search requests. For Copilot, keep the global `messageApiWebSearchModel` set to a Responses-capable GPT model or a `provider/model` alias. For provider routes, use a native Anthropic provider or an `openai-responses` provider. Add `WebSearch` to `permissions.deny` only if you want to forbid this traffic.\n- If using a non-Claude model, do not enable ENABLE_TOOL_SEARCH. If using the Claude model, can enable ENABLE_TOOL_SEARCH. The current Claude Code uses the client tool search mode. In this mode, loading defer tools requires an additional request each time.\n- `CLAUDE_CODE_AUTO_COMPACT_WINDOW`: Set the context capacity in tokens used for auto-compaction calculations. Defaults to the model's context window: 200K for standard models or 1M for extended context models. Use a lower value like `500000` on a 1M model (e.g., `claude-opus-4-6[1m]`) to treat the window as 500K for compaction purposes. The value is capped at the model's actual context window. `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` is applied as a percentage of this value. Setting this variable decouples the compaction threshold from the status line's `used_percentage`, which always uses the model's full context window.\n\nYou can find more options here: [Claude Code settings](https://docs.anthropic.com/en/docs/claude-code/settings#environment-variables)\n\nYou can also read more about IDE integration here: [Add Claude Code to your IDE](https://docs.anthropic.com/en/docs/claude-code/ide-integrations)\n\n## Using with OpenCode\n\nOpenCode already has a direct GitHub Copilot provider. Use this section when you want OpenCode to point at this AI gateway through `@ai-sdk/anthropic` and reuse the agent behaviors described earlier in this README.\n\n### Minimal setup\n\nStart the AI gateway with the OpenCode OAuth app:\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth --oauth-app=opencode\nnpx @jeffreycao/copilot-api@latest start\n```\n\nThen point OpenCode at the gateway with `@ai-sdk/anthropic`.\n\nExample `~/.config/opencode/opencode.json`:\n\n```json\n{\n  \"$schema\": \"https://opencode.ai/config.json\",\n  \"provider\": {\n    \"local\": {\n      \"npm\": \"@ai-sdk/anthropic\",\n      \"name\": \"My Local\",\n      \"options\": {\n        \"baseURL\": \"http://localhost:4141/v1\",\n        \"apiKey\": \"dummy\"\n      },\n      \"models\": {\n        \"gpt-5.4\": {\n          \"name\": \"gpt-5.4\",\n          \"modalities\": {\n            \"input\": [\"text\", \"image\"],\n            \"output\": [\"text\"]\n          },\n          \"limit\": {\n            \"context\": 300000,\n            \"output\": 128000\n          }\n        },\n        \"claude-sonnet-4.6\": {\n          \"id\": \"claude-sonnet-4.6\",\n          \"name\": \"claude-sonnet-4.6\",\n          \"modalities\": {\n            \"input\": [\"text\", \"image\"],\n            \"output\": [\"text\"]\n          },          \n          \"limit\": {\n            \"context\": 200000,\n            \"output\": 32000\n          },\n          \"options\": {\n            \"thinking\": {\n              \"type\": \"adaptive\"\n            },\n            \"effort\": \"max\"\n          }\n        }\n      }\n    }\n  }\n}\n```\n\nWhy these fields matter:\n\n- `npm: \"@ai-sdk/anthropic\"` is the important part. OpenCode will speak Anthropic Messages semantics to this AI gateway instead of flattening everything into OpenAI Chat Completions.\n- `options.baseURL` should be `http://localhost:4141/v1`; the Anthropic SDK will append `/messages`, `/models`, and `/messages/count_tokens` automatically.\n- If you enable `auth.apiKeys` in this AI gateway, replace `dummy` with a real key. Otherwise any placeholder value is fine.\n\n## Using with Codex\n\nThis AI gateway can also power Codex.\n\n### Codex `config.toml` Reference\n\nAdd the following `[model_providers.copilot_api]` section to your Codex `~/.codex/config.toml`:\n\n```toml\nmodel_provider = \"copilot_api\"\nmodel_reasoning_summary = \"auto\"\nmodel_verbosity = \"medium\"\nmodel_context_window = 272000\nmodel_auto_compact_token_limit = 244800\n\n[model_providers.copilot_api]\nname = \"OpenAI\"\nbase_url = \"http://localhost:4141\"\nenv_key = \"GITHUB_COPILOT_API_KEY\"\nrequires_openai_auth = true\nsupports_websockets = false\nwire_api = \"responses\"\nrequest_max_retries = 3\nstream_max_retries = 1\nstream_idle_timeout_ms = 300000\n\n[features]\nremote_compaction_v2 = true\n\n[analytics]\nenabled = false\n```\n\n> [!NOTE]\n> This configuration is specific to Codex and the GitHub Copilot provider. `name` must be set to `\"OpenAI\"`. It can help mitigate Codex local compact cache miss issues. If you have enabled `useResponsesApiContextManagement` (Responses API context management compaction), `remote_compaction_v2` or local compact is generally not triggered, but it may still occur when tool results return a large number of tokens.\n\n## GPT Tool Search\n\nFor GPT Responses models such as `gpt-5.4+`, this AI gateway can expose Responses `tool_search` through a small MCP bridge. The same bridge can be used by Claude Code and opencode, as long as the client loads MCP servers and sends Anthropic Messages traffic through this gateway.\n\nDo not set Claude Code's native `ENABLE_TOOL_SEARCH` for GPT models. That flag enables Claude Code's own client-side tool search mode, and it may stop forwarding deferred tool definitions. This gateway needs the full tool definitions so it can keep the small always-loaded tool set eager and translate every other tool into Responses deferred namespaces.\n\nIf you install `tool-search@copilot-api-marketplace`, Claude Code receives this MCP bridge automatically and you can skip the manual Claude Code MCP setup below.\n\nAdd the tool search bridge to the MCP config used by Claude Code:\n\n```json\n{\n  \"mcpServers\": {\n    \"tool_search\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@jeffreycao/copilot-api@latest\", \"mcp\"]\n    }\n  }\n}\n```\n\nAdd the tool search bridge to the MCP config used by opencode:\n\n```json\n{\n  \"mcp\": {\n    \"tool_search\": {\n      \"type\": \"local\",\n      \"command\": [\"npx\", \"-y\", \"@jeffreycao/copilot-api@latest\", \"mcp\"]\n    }\n  }\n}\n```\n\nFor local development, use `bun` as the command and `[\"run\", \"./src/main.ts\", \"mcp\"]` as the args.\n\nInternally, the gateway now configures OpenAI Responses `tool_search` in client-executed mode. Deferred tools are still exposed as searchable namespaces, but the model is explicitly asked to return the exact deferred tool names it wants to load next.\n\nThe bridge uses direct tool selection, not query search. Its tool input is `names`, a comma-separated list of exact deferred tool names, for example `TaskList,TaskGet,mcp__fetch__fetch`.\n\n## Plugin Integrations\n\nPlugin integrations are available for Claude Code and opencode.\n\n#### Claude Code plugin integration (marketplace-based)\n\nThe Claude Code integration is packaged as two plugins:\n\n- `agent-inject` injects `__SUBAGENT_MARKER__...` on `SubagentStart`, so the gateway can infer `x-initiator: agent`.\n- `tool-search` registers the `tool_search` MCP bridge used for GPT Responses deferred tool loading.\n\n- Marketplace catalog in this repository: `.claude-plugin/marketplace.json`\n- Plugin sources in this repository: `plugin/claude/agent-inject`, `plugin/claude/tool-search`\n\nAdd the marketplace remotely:\n\n```sh\n/plugin marketplace add https://github.com/caozhiyuan/copilot-api.git\n```\n\nInstall the plugins from the marketplace:\n\n```sh\n/plugin install agent-inject@copilot-api-marketplace\n/plugin install tool-search@copilot-api-marketplace\n```\n\nAfter installation, `agent-inject` injects `__SUBAGENT_MARKER__...` on `SubagentStart`, and the gateway uses it to infer `x-initiator: agent`.\n\nThe `agent-inject` plugin also registers a `UserPromptSubmit` hook that returns `{\"continue\": true}`, and it can inject `SessionStart` reminder rules through environment variables:\n\n- `CLAUDE_PLUGIN_ENABLE_QUESTION_RULES=1` enables the two reminders about using the `question` tool automatically for Claude Code. Alternatively, you can add the same reminders manually in `CLAUDE.md`; see [CLAUDE.md or AGENTS.md Recommended Content](#claudemd-or-agentsmd-recommended-content).\n- `CLAUDE_PLUGIN_ENABLE_NO_BACKGROUND_AGENTS_RULE=1` enables the `run_in_background: true` avoidance reminder for agent hooks.\n\nThe `tool-search` plugin bundles the same MCP bridge described in [GPT Tool Search](#gpt-tool-search), so Claude Code users do not need to add the `tool_search` server manually when they install that plugin.\n\n#### Opencode plugin\n\nThe subagent marker producer is packaged as an opencode plugin located at `plugin/opencode/subagent-marker.js`.\n\n**Installation:**\n\nCopy the plugin file to your opencode plugins directory:\n\n```sh\n# Clone or download this repository, then copy the plugin\ncp plugin/opencode/subagent-marker.js ~/.config/opencode/plugins/\n```\n\nOr manually create the file at `~/.config/opencode/plugins/subagent-marker.js` with the plugin content.\n\n**Features:**\n\n- Tracks sub-sessions created by subagents\n- Automatically prepends a marker system reminder (`__SUBAGENT_MARKER__...`) to subagent chat messages\n- Sets `x-session-id` header for session tracking\n- Enables the gateway to infer `x-initiator: agent` for subagent-originated requests\n\nThe plugin hooks into `session.created`, `session.deleted`, `chat.message`, and `chat.headers` events to provide seamless subagent marker functionality.\n\n## Using the Usage Viewer\n\nAfter starting the server, a URL to the Copilot Usage Dashboard will be displayed in your console. This dashboard is a web interface for monitoring your API usage.\n\n1.  Start the server. For example, using npx:\n    ```sh\n    npx @jeffreycao/copilot-api@latest start\n    ```\n2.  The server will output a URL to the usage viewer. Copy and paste this URL into your browser. It will look something like this:\n    `http://localhost:4141/usage-viewer?endpoint=http://localhost:4141/usage`\n    - If you use the `start.bat` script on Windows, this page will open automatically.\n\nThe dashboard provides a user-friendly interface to view your Copilot usage data:\n\n> Token usage history requires Bun or Node.js >= 22.13.0. On Node.js < 22.13.0, the server runs normally but token usage storage is disabled.\n\n- **API Endpoint URL**: The dashboard is pre-configured to fetch data from your local server endpoint via a URL query parameter. You can manually switch this to any other compatible API endpoint.\n- **x-api-key Authentication**: If API Key authentication is enabled, you can provide the `x-api-key` request header. The key is persisted in the browser's local storage.\n- **Period Selector**: Choose from Day, Week, or Month time ranges. The URL query parameter updates automatically when you switch, making it easy to bookmark and share.\n- **Fetch Data**: Click the \"Refresh\" button to load or refresh the usage data. The dashboard also fetches data automatically on page load.\n- **Copilot Quotas**: View quota usage for services such as Chat and Completions via progress bars. Hover over a card to see used/remaining details.\n- **Token Usage Metric Cards**: See a summary of Total, Input, Output, Cache Read, Cache Write, Requests, and estimated cost for the current period.\n- **Trend Chart (Week / Month)**: An interactive line chart with model and metric filters. Click a data point to inspect the usage breakdown for a specific day.\n- **Model Breakdown Table**: A per-model summary of requests, input/output/cache tokens, and estimated cost for the selected period.\n- **Request Events (Paginated)**: A time-sorted list of request event records with pagination support, showing timestamps, models, request IDs, and token counts.\n- **Detailed Information**: See the full JSON response from the API for a detailed breakdown of all available usage statistics.\n- **URL-based Configuration**: You can also specify the API endpoint and period directly via `endpoint` and `period` query parameters. For example:\n  `http://localhost:4141/usage-viewer?endpoint=http://your-api-server/usage&period=week`\n\n### Usage Viewer Screenshot\n\n<p align=\"center\">\n  <img src=\"./docs/screenshots/usage-viewer.png\" alt=\"Copilot API usage viewer\" width=\"900\" />\n</p>\n\n## Command Structure\n\nCopilot API now uses a subcommand structure with these main commands:\n\n- `start`: Start the gateway server. If a GitHub token is available, the server starts with Copilot enabled. If no GitHub token is available, it starts in provider-only mode when at least one enabled provider exists; otherwise it guides you through provider setup.\n- `auth`: Run provider login or configuration without starting the server. Use it for GitHub Copilot login, Codex OAuth, or third-party provider API key setup.\n- `debug`: Display diagnostic information including version, runtime details, file paths, and authentication status. Useful for troubleshooting and support.\n\n## Command Line Options\n\n### Global Options\n\nThe following options can be used with any subcommand. When passing them before the subcommand, use the `--key=value` form:\n\n| Option            | Description                                            | Default | Alias |\n| ----------------- | ------------------------------------------------------ | ------- | ----- |\n| --api-home        | Path to the API home directory (sets COPILOT_API_HOME) | none    | none  |\n| --oauth-app       | OAuth app identifier (sets COPILOT_API_OAUTH_APP)      | none    | none  |\n| --enterprise-url  | Enterprise URL for GitHub (sets COPILOT_API_ENTERPRISE_URL) | none | none |\n\n### Start Command Options\n\nThe following command line options are available for the `start` command:\n\n| Option         | Description                                                                   | Default    | Alias |\n| -------------- | ----------------------------------------------------------------------------- | ---------- | ----- |\n| --port         | Port to listen on                                                             | 4141       | -p    |\n| --verbose      | Enable verbose logging                                                        | false      | -v    |\n| --github-token | Provide GitHub token directly (must be generated using the `auth` subcommand) | none       | -g    |\n| --claude-code  | Generate a command to launch Claude Code with Copilot API config              | false      | -c    |\n| --show-token   | Show GitHub and Copilot tokens on fetch and refresh                           | false      | none  |\n| --proxy-env    | Initialize proxy from environment variables                                   | false      | none  |\n\n### Auth Command Options\n\n| Option       | Description               | Default | Alias |\n| ------------ | ------------------------- | ------- | ----- |\n| --provider   | Provider to log in with or configure (`copilot`, `codex`, `deepseek`, `dashscope`, `openrouter`, or `custom`) | prompt | none |\n| --verbose    | Enable verbose logging    | false   | -v    |\n| --show-token | Show GitHub token on auth | false   | none  |\n\nUse `copilot-api auth login --provider copilot` only when you want to enable the GitHub Copilot provider. Copilot is not required for `codex` or third-party provider-only usage.\n\nUse `copilot-api auth login --provider deepseek`, `--provider dashscope`, or `--provider openrouter` to add or update those common third-party providers from the CLI. DeepSeek prompts for masked `apiKey`, provider `type` (default `anthropic`), and `baseUrl` defaulting to `https://api.deepseek.com/anthropic`. DashScope prompts for masked `apiKey`, provider `type` (default `openai-compatible`), and prefilled `baseUrl`. OpenRouter prompts for masked `apiKey` and prefilled `baseUrl` only, and writes `type: \"anthropic\"`. After a provider is configured and enabled, `copilot-api start` can run without any GitHub token.\n\nUse `copilot-api auth login --provider custom` to add or update another third-party provider from the CLI. The command prompts for the provider name, supported type (`anthropic`, `openai-compatible`, or `openai-responses`), `baseUrl`, masked `apiKey`, and `authType`; `authType` may be left as the type default or set to `x-api-key` / `authorization`.\n\n### Debug Command Options\n\n| Option | Description               | Default | Alias |\n| ------ | ------------------------- | ------- | ----- |\n| --json | Output debug info as JSON | false   | none  |\n\n## Configuration (config.json)\n\n- **Location:** `~/.local/share/copilot-api/config.json` (Linux/macOS) or `%USERPROFILE%\\.local\\share\\copilot-api\\config.json` (Windows).\n- **Default shape:**\n  ```json\n  {\n    \"auth\": {\n      \"apiKeys\": [],\n      \"adminApiKey\": \"<auto-generated-on-startup>\"\n    },\n    \"providers\": {},\n    \"modelMappings\": {},\n    \"extraPrompts\": {\n      \"gpt-5-mini\": \"<built-in exploration prompt>\",\n      \"gpt-5.3-codex\": \"<built-in commentary prompt>\",\n      \"gpt-5.4-mini\": \"<built-in commentary prompt>\",\n      \"gpt-5.4\": \"<built-in commentary prompt>\",\n      \"gpt-5.5\": \"<built-in commentary prompt>\"\n    },\n    \"smallModel\": \"gpt-5-mini\",\n    \"useResponsesApiContextManagement\": true,\n    \"modelResponsesApiCompactThresholds\": {\n      \"gpt-5.4\": 217600,\n      \"gpt-5.5\": 217600\n    },\n    \"modelReasoningEfforts\": {\n      \"gpt-5-mini\": \"low\",\n      \"gpt-5.3-codex\": \"xhigh\",\n      \"gpt-5.4-mini\": \"xhigh\",\n      \"gpt-5.4\": \"xhigh\",\n      \"gpt-5.5\": \"xhigh\"\n    },\n    \"useMessagesApi\": true,\n    \"useResponsesApiWebSocket\": true,\n    \"useResponsesApiWebSearch\": true,\n    \"messageApiWebSearchModel\": \"gpt-5-mini\"\n  }\n  ```\n- **auth.apiKeys:** API keys used for request authentication on non-admin routes. Supports multiple keys for rotation. Requests can authenticate with either `x-api-key: <key>` or `Authorization: Bearer <key>`. If empty or omitted, authentication for non-admin routes is disabled.\n- **auth.adminApiKey:** Single admin key used only for `/admin/*` routes. If missing, the server generates a random key at startup and writes it back to `config.json`. Requests use the same `x-api-key` or `Authorization: Bearer` headers, but regular `auth.apiKeys` never grant access to `/admin/*`.\n- **modelMappings:** Exact `sourceModel -> targetModel` rewrites shared by top-level `POST /v1/messages`, `POST /v1/messages/count_tokens`, `POST /v1/responses`, and `POST /v1/chat/completions` requests. Omit it or leave it as `{}` to disable rewrites. Both the source and target must be non-empty strings. Targets can be regular model IDs or `provider/model` aliases such as `dashscope/qwen3.6-plus`, and the rewrite happens before provider alias parsing. These mappings are not split per interface. The admin endpoints `GET/POST /admin/config/model-mappings` read and update only this field.\n- **extraPrompts:** Map of `model -> prompt` appended to the first system prompt when translating Anthropic-style requests to Copilot. Use this to inject guardrails or guidance per model. Missing default entries are auto-added without overwriting your custom prompts. The built-in prompts for `gpt-5.3-codex` and `gpt-5.4` enable phase-aware commentary, which lets the model emit a short user-facing progress update before tools or deeper reasoning.\n- **providers:** Global upstream provider map. Each provider key (for example `dashscope`) becomes a route prefix (`/dashscope/v1/messages`). Supports `type: \"anthropic\"`, `type: \"openai-compatible\"`, and `type: \"openai-responses\"`. Top-level clients can also use `model: \"dashscope/model-id\"` with `/v1/messages`, `/v1/messages/count_tokens`, `/v1/responses`, and `/v1/chat/completions`; the gateway strips the `dashscope/` prefix before forwarding upstream. `openai-compatible` providers support both chat and Messages flows: `/v1/chat/completions` is proxied to upstream `/v1/chat/completions`, while `/v1/messages` and `/:provider/v1/messages` are translated to upstream chat completions and translated back to Anthropic Messages responses. `GET /v1/models` aggregates enabled provider models with `provider/model-id` IDs; use `GET /dashscope/v1/models` for a single provider's raw model list.\n  - `enabled` defaults to `true` if omitted.\n  - `baseUrl` should be provider API base URL without the final endpoint. For Anthropic providers, omit `/v1/messages`; for OpenAI-compatible providers, omit `/v1/chat/completions`; for OpenAI Responses providers, omit `/v1/responses`.\n  - `apiKey` is used as the upstream credential value and is required for regular providers.\n  - `authType` (optional): Controls how `apiKey` is sent upstream. Supports `x-api-key` and `authorization` for regular providers. Anthropic providers default to `x-api-key`; OpenAI-compatible and OpenAI Responses providers default to `authorization`. When set to `authorization`, the proxy sends `Authorization: Bearer <apiKey>`. `oauth2` is reserved for the built-in `codex` provider and is written automatically by `auth login --provider codex`.\n  - `pricingCurrency` (optional): Provider-level currency used for token cost calculation, for example `USD` or `CNY`. Quick providers default to `CNY` for DashScope and DeepSeek, and `USD` for Codex/OpenRouter. Costs are grouped by currency and are not exchange-rate converted.\n  - `models` (optional): Per-model configuration map. Each key is a model ID (matching the model name in requests), and the value is:\n    - `temperature` (optional): Default temperature value used when the request does not specify one.\n    - `topP` (optional): Default top_p value used when the request does not specify one.\n    - `topK` (optional): Default top_k value used when the request does not specify one.\n    - `extraBody` (optional): Dynamic fields merged into the upstream request body for that model. Request body fields with the same name take precedence. OpenAI-compatible providers can use this for fields such as `enable_thinking`, `preserve_thinking`, `reasoning_effort`. `thinking_budget` is a special OpenAI-compatible provider override: when configured in `extraBody`, it is forced after Anthropic `thinking.budget_tokens` translation and overrides the request-derived budget.\n    - `pricing` (optional): Per-model token prices, in the provider `pricingCurrency`, per 1M tokens. Supported fields are `input`, `output`, `cachedInput` (implicit cache read), `explicitCachedInput` (explicit cache read), and `cacheCreationInput`. Use `tiers` with `maxInputTokens` for input-size tiered pricing.\n    - `contextCache` (optional): Defaults to `true` for OpenAI-compatible providers. This enables Alibaba Cloud Model Studio/DashScope explicit context cache by injecting `cache_control: { \"type\": \"ephemeral\" }` on up to 4 content blocks using the Context Cache format. The cache breakpoint strategy matches opencode's main provider flow: the first 2 system messages plus the last 2 non-system messages. Marked string content is converted to text content part arrays for `system` / `user` / `assistant` / `tool` messages; existing array content is marked on the last part. Set this to `false` when the model already supports implicit caching, or when the upstream does not accept this explicit-cache extension field.\n    - `supportPdf` (optional): Controls whether the model supports PDF/document content. Defaults to `false`; unsupported PDFs are converted to a text notice. Set it to `true` to send PDF/document blocks as OpenAI Chat Completions file parts.\n    - `toolContentSupportType` (optional): Tool result content capabilities for that model, as an array of `array`, `image`, and `pdf`. Provider routes default to string-only tool content when omitted. If `supportPdf` is `true` but this list does not include `pdf`, file parts in tool results are moved to user role messages. This provider default does not change the Copilot main flow, which continues to support array + image and not PDF.\n\n  Example DashScope model settings:\n  ```json\n  {\n    \"providers\": {\n      \"dashscope\": {\n        \"type\": \"openai-compatible\",\n        \"enabled\": true,\n        \"baseUrl\": \"https://dashscope.aliyuncs.com/compatible-mode\",\n        \"apiKey\": \"sk-your-dashscope-key\",\n        \"pricingCurrency\": \"CNY\",\n        \"models\": {\n          \"qwen3.7-plus\": {\n            \"temperature\": 1,\n            \"topP\": 0.95,\n            \"topK\": 20,\n            \"extraBody\": {\n              \"preserve_thinking\": true\n            }\n          },\n          \"glm-5.1\": {\n            \"temperature\": 0.7,\n            \"topP\": 0.95,\n            \"contextCache\": true,\n            \"pricing\": {\n              \"tiers\": [\n                {\n                  \"maxInputTokens\": 32000,\n                  \"input\": 6,\n                  \"cachedInput\": 1.2,\n                  \"explicitCachedInput\": 0.6,\n                  \"cacheCreationInput\": 7.5,\n                  \"output\": 24\n                },\n                {\n                  \"maxInputTokens\": 200000,\n                  \"input\": 8,\n                  \"cachedInput\": 1.6,\n                  \"explicitCachedInput\": 0.8,\n                  \"cacheCreationInput\": 10,\n                  \"output\": 28\n                }\n              ]\n            },\n            \"extraBody\": {\n              \"preserve_thinking\": true\n            }\n          }\n        }\n      }\n    }\n  }\n  ```\n  Built-in token prices cover Codex GPT models in USD, DashScope `qwen3.7-max`, `qwen3.7-plus`, `glm-5.1`, `glm-5.2` in CNY, and DeepSeek `deepseek-v4-flash`, `deepseek-v4-pro`, `deepseek-chat`, `deepseek-reasoner` in CNY. User `pricing` entries override built-ins. For DashScope, cached tokens are charged as explicit cache reads when the upstream usage includes `cache_creation_input_tokens`; otherwise `cachedInput` is used as the implicit cache read price. For DeepSeek, `prompt_cache_hit_tokens` map to cached input and `prompt_cache_miss_tokens` map to regular input.\n- **smallModel:** Fallback model used for tool-less warmup messages (e.g., Claude Code probe requests); defaults to gpt-5-mini.\n- **useResponsesApiContextManagement:** When `true`, the proxy adds Responses API `context_management` compaction instructions. Defaults to `true`. Set it to `false` to disable this globally. When enabled, the request includes `context_management` in the body and keeps only the latest compaction carrier on follow-up turns. This is especially useful for long-running tasks.\n- **modelResponsesApiCompactThresholds:** Per-model Responses API `compact_threshold` overrides used when the proxy adds `context_management`. These values take precedence over the fallback threshold from `resolveResponsesCompactThreshold` (`max_prompt_tokens * ratio`, or the default fallback). Defaults set `gpt-5.4` and `gpt-5.5` to `217600` (`272000 * 0.8`). Models not listed continue to use the normal fallback logic.\n- **modelReasoningEfforts:** Per-model `reasoning.effort` sent to the Copilot Responses API. Allowed values are `none`, `minimal`, `low`, `medium`, `high`, and `xhigh`. If a model isn't listed, `high` is used by default.\n- **useMessagesApi:** When `true`, Claude-family models that support Copilot's native `/v1/messages` endpoint will use the Messages API; otherwise they fall back to `/chat/completions`. Set to `false` to disable Messages API routing and always use `/chat/completions`. Defaults to `true`.\n- **useResponsesApiWebSocket:** When `true`, Responses API requests use Copilot's websocket transport for models that advertise `ws:/responses`; models that only advertise `/responses` continue to use HTTP. Set to `false` to disable websocket routing and use HTTP `/responses` whenever the selected model supports it. Defaults to `true`.\n- **useResponsesApiWebSearch:** When `true`, the server keeps Responses API tools with `type: \"web_search\"` and forwards them upstream. Set to `false` to strip those tools from `/responses` payloads. Defaults to `true`.\n- **messageApiWebSearchModel:** Global fallback model used when a top-level Copilot `/v1/messages` request contains only the server-side `web_search` tool. Defaults to `gpt-5-mini`. If the value is a `provider/model` alias, the request is routed into that provider's Messages API path with the provider prefix stripped. For Copilot GPT models, web search runs through `/responses`. Mixed `web_search` plus custom tools are not supported and the server-side `web_search` tool is stripped.\n- **claudeTokenMultiplier:** Multiplier applied to the fallback GPT-tokenizer estimate for Claude `/v1/messages/count_tokens` requests. Defaults to `1.15`. Increase it if your client is still compacting too late. This setting is only used when the proxy is estimating Claude tokens locally; if `anthropicApiKey` is configured and Anthropic token counting succeeds, the exact Anthropic count is returned instead.\n- **anthropicApiKey:** Anthropic API key used to forward Claude `/v1/messages/count_tokens` requests to Anthropic's real token counting endpoint, which returns exact counts instead of GPT tokenizer estimates. Can also be set via the `ANTHROPIC_API_KEY` environment variable. If not set, or if the upstream call fails, token counting falls back to local GPT tokenizer estimation controlled by `claudeTokenMultiplier`.\n\nEdit this file to customize prompts or swap in your own fast model. Restart the server (or rerun the command) after changes so the cached config is refreshed.\n\n## API Authentication\n\n- **Protected non-admin routes:** All routes except `/`, `/usage-viewer`, and `/usage-viewer/` require authentication when `auth.apiKeys` is configured and non-empty.\n- **Admin routes:** All `/admin/*` routes require `auth.adminApiKey`. If it is missing, the server generates one at startup and persists it to `config.json` before serving requests.\n- **Allowed auth headers:**\n  - `x-api-key: <your_key>`\n  - `Authorization: Bearer <your_key>`\n- **CORS preflight:** `OPTIONS` requests are always allowed.\n- **When no regular keys are configured:** Non-admin routes continue to allow requests. This does not apply to `/admin/*`, which only accepts `auth.adminApiKey`.\n\nExample request for a regular protected route:\n\n```sh\ncurl http://localhost:4141/v1/models \\\n  -H \"x-api-key: your_api_key\"\n```\n\nExample request for an admin route:\n\n```sh\ncurl http://localhost:4141/admin/config/model-mappings \\\n  -H \"x-api-key: your_admin_api_key\"\n```\n\n## API Endpoints\n\nThe server exposes several OpenAI- and Anthropic-compatible endpoints. Requests can target GitHub Copilot, the built-in `codex` provider, or configured providers depending on the selected model and `provider/model` alias.\n\n### OpenAI Compatible Endpoints\n\nThese endpoints mimic the OpenAI API structure.\n\n| Endpoint                    | Method | Description                                                      |\n| --------------------------- | ------ | ---------------------------------------------------------------- |\n| `POST /v1/responses`        | `POST` | OpenAI Most advanced interface for generating model responses. Supports `provider/model` aliases for `openai-responses` providers. |\n| `POST /v1/chat/completions` | `POST` | Creates a model response for the given chat conversation. Supports `provider/model` aliases for `openai-compatible` providers and can be used without Copilot when the target provider is configured. |\n| `GET /v1/models`            | `GET`  | Lists Copilot models plus enabled provider models using `provider/model-id` IDs. |\n| `POST /v1/embeddings`       | `POST` | Creates an embedding vector representing the input text.         |\n\n### Anthropic Compatible Endpoints\n\nThese endpoints are designed to be compatible with the Anthropic Messages API.\n\n| Endpoint                         | Method | Description                                                  |\n| -------------------------------- | ------ | ------------------------------------------------------------ |\n| `POST /v1/messages`              | `POST` | Creates a model response for a given conversation. Supports `provider/model` aliases for configured providers, including translation through `openai-compatible` providers. |\n| `POST /v1/messages/count_tokens` | `POST` | Calculates the number of tokens for a given set of messages. Supports `provider/model` aliases for configured providers. |\n| `POST /:provider/v1/messages`       | `POST` | Proxies Anthropic Messages requests to the configured Anthropic provider, translates them through an OpenAI-compatible provider, or translates them through an OpenAI Responses provider. |\n| `GET /:provider/v1/models`          | `GET`  | Proxies model listing requests to the configured provider.   |\n| `POST /:provider/v1/messages/count_tokens` | `POST` | Calculates tokens locally for provider route requests. |\n\n### Usage Monitoring Endpoints\n\nNew endpoints for monitoring your Copilot usage and quotas.\n\n| Endpoint     | Method | Description                                                  |\n| ------------ | ------ | ------------------------------------------------------------ |\n| `GET /usage` | `GET`  | Get detailed Copilot usage statistics and quota information. |\n| `GET /token` | `GET`  | Get the current Copilot token being used by the API.         |\n\n### Admin / Configuration Endpoints\n\nThese endpoints are reserved for local administrative actions and only accept `auth.adminApiKey`.\n\n| Endpoint                              | Method | Description                                                                 |\n| ------------------------------------- | ------ | --------------------------------------------------------------------------- |\n| `GET /admin/config/model-mappings`    | `GET`  | Returns the current `config.json` path and the active `modelMappings` map.  |\n| `POST /admin/config/model-mappings`   | `POST` | Updates only the `modelMappings` field in `config.json` and returns it back. |\n\n## Example Usage\n\nCommon `npx` commands:\n\n```sh\n# Start the gateway\nnpx @jeffreycao/copilot-api@latest start\n\n# Start on a custom port with verbose logging\nnpx @jeffreycao/copilot-api@latest start --port 8080 --verbose\n\n# Run the auth flow\nnpx @jeffreycao/copilot-api@latest auth login\n\n# Configure a third-party provider, then run without GitHub Copilot\nnpx @jeffreycao/copilot-api@latest auth login --provider dashscope\nnpx @jeffreycao/copilot-api@latest start\n\n# Print debug information as JSON\nnpx @jeffreycao/copilot-api@latest debug --json\n\n# Run the published CLI with Bun instead of Node.js\nbunx --bun @jeffreycao/copilot-api@latest start\n```\n\nOpenAI-compatible provider examples after configuring `dashscope`:\n\n```sh\ncurl http://localhost:4141/v1/chat/completions \\\n  -H \"content-type: application/json\" \\\n  -d '{\"model\":\"dashscope/qwen3.6-plus\",\"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]}'\n\ncurl http://localhost:4141/dashscope/v1/messages \\\n  -H \"content-type: application/json\" \\\n  -d '{\"model\":\"qwen3.6-plus\",\"max_tokens\":1024,\"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]}'\n```\n\n## Usage Tips\n\n### CLAUDE.md or AGENTS.md Recommended Content\n\nTo add these reminders manually, include the following in `CLAUDE.md` for Claude Code, or `AGENTS.md` for opencode/codex:\n\n```\n- Prohibited from directly asking questions to users, MUST use question tool.\n- Once you can confirm that the task is complete, MUST use question tool to make user confirm. The user may respond with feedback if they are not satisfied with the result, which you can use to make improvements and try again, after try again, MUST use question tool to make user confirm again.\n```\n"}, "ac60b4a65190a187bf5c6adac48733543576b18b": {"t": 1786067818.8890367, "n": 51438, "h": "0bb57ea56ad7c178", "c": "# Copilot API Proxy\n\nEnglish | [简体中文](./README.zh-CN.md)\n\n## Important Notes\n\n> [!IMPORTANT]\n> **Before using, please be aware of the following:**\n>\n> 1. **Claude Code configuration:** When using with Claude Code, please configure the model ID as `claude-opus-4-8`. Example claude `settings.json` see [Manual Configuration with `settings.json`](#manual-configuration-with-settingsjson). \n>\n> 2. **Built-in `copilot`, `codex` and third-party providers:** Run `npx @jeffreycao/copilot-api@latest auth` and choose `copilot`, `codex`, `deepseek`, `custom`, or other providers.\n>\n> 3. **Note:** See [GitHub Copilot Security Notice](./NOTICE.md#github-copilot-security-notice) for the warning removed from the README header.\n\n---\n\n## Project Overview\n\nA small AI gateway that can use GitHub Copilot, the built-in `codex` provider, or configured third-party providers such as DashScope. GitHub Copilot is optional: if no GitHub token is available, the server can still start in provider-only mode as long as at least one enabled provider is configured.\n\nThe gateway exposes OpenAI- and Anthropic-compatible APIs from one local endpoint, so tools like [Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview), OpenCode, Codex, and OpenAI-compatible clients can share the same local server.\n\nOn the GitHub Copilot path, the gateway prefers Copilot's native Anthropic-style Messages API when available, preserving more Claude-native behavior for tool-heavy workflows.\n\n## Features\n\n- **OpenAI and Anthropic compatibility**: Serve `/v1/responses`, `/v1/chat/completions`, `/v1/models`, `/v1/embeddings`, and `/v1/messages` from one local gateway.\n- **Copilot is optional**: Use GitHub Copilot when credentials are present, or run the server with only configured providers.\n- **One gateway for Copilot, `codex`, and external providers**: Route GitHub Copilot, the built-in `codex` provider, and configured third-party providers behind the same endpoint.\n- **Standalone third-party providers**: Configure providers such as DashScope, DeepSeek, OpenRouter, or a custom provider and start the gateway without a GitHub Copilot login.\n- **OpenAI-compatible providers on chat and Messages APIs**: `openai-compatible` providers can serve top-level `/v1/chat/completions` through `model: \"provider/model\"` and Anthropic-style `/v1/messages` through request/response translation.\n- **Agent-friendly Claude handling on Copilot**: Prefer native `/v1/messages` when available, preserve Claude-style tool flows, support Anthropic beta features, Claude WebSearch through Responses-capable models, and keep subagent/session markers intact.\n- **Claude Code and OpenCode integration**: Works with Claude Code and OpenCode, including direct Anthropic-compatible usage through `@ai-sdk/anthropic`.\n- **Flexible auth and deployment options**: Supports interactive login or direct tokens, individual/business/enterprise plans, GitHub Enterprise, opencode OAuth, and custom data directories.\n- **Multi-provider routing**: Expose provider-specific `/:provider/...` routes or use `model: \"provider/model\"` on the top-level API.\n\n## Prerequisites\n\n- Bun (>= 1.2.x)\n- Node.js if you plan to run the published CLI with `npx`\n- GitHub account with Copilot subscription only if you want to use the GitHub Copilot provider\n- An API key or OAuth login for at least one configured provider if you want to run without GitHub Copilot\n\n## Installation\n\nTo install dependencies, run:\n\n```sh\nbun install\n```\n\nTo start the server directly from source:\n\n```sh\nbun run start start\n```\n\n## Running from Source\n\nThe project can be run from source in several ways:\n\n### Development Mode\n\n```sh\nbun run dev start\n```\n\n### Production Mode\n\n```sh\nbun run start start\n```\n\n## Using with npx\n\nYou can run the project directly using npx:\n\n> [!IMPORTANT]\n> Token usage storage uses Node's built-in `node:sqlite` module when running with `npx`. It is enabled on Node.js >= 22.13.0. On Node.js < 22.13.0, the CLI still starts, but token usage storage is disabled.\n>\n> If you want token usage storage without upgrading Node.js, run the published CLI with Bun instead: `bunx --bun @jeffreycao/copilot-api@latest start`.\n\n```sh\nnpx @jeffreycao/copilot-api@latest start\n```\n\nWith options:\n\n```sh\nnpx @jeffreycao/copilot-api@latest start --port 8080\n```\n\nFor authentication or provider configuration only:\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth\n```\n\nTo run without GitHub Copilot, configure at least one provider first, then start the server normally:\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth login --provider dashscope\nnpx @jeffreycao/copilot-api@latest start\n```\n\n## Using with Docker\n\nBuild the image:\n\n```sh\ndocker build -t copilot-api .\n```\n\nRun the container with a bind mount so auth data survives restarts:\n\n```sh\nmkdir -p ./copilot-data\ndocker run -p 4141:4141 -v $(pwd)/copilot-data:/root/.local/share/copilot-api copilot-api\n```\n\nThis stores GitHub auth data, provider config, and other gateway state in `./copilot-data` on the host, mapped to `/root/.local/share/copilot-api` in the container.\n\nOr pass a GitHub token directly:\n\n```sh\ndocker run -p 4141:4141 -e GH_TOKEN=your_github_token_here copilot-api\n```\n\n## Electron Desktop App\n\nIf you prefer a GUI, this repository also includes an Electron desktop app in `desktop/`. It supports GitHub Copilot sign-in, OpenAI Codex OAuth, and API-key configuration for DeepSeek, DashScope, OpenRouter, or a custom provider. After authorization or provider configuration, it can start and stop the local proxy with one click and shows the local endpoint, auth header, available models, usage, and logs in the app.\n\nThe settings screen also exposes `OAuth App`, `API Home`, `Enterprise URL`, verbose logging, and minimize-to-tray. Windows x64 (`.exe`), macOS Apple Silicon (`.dmg`), and Linux x64 (`.AppImage`) packages are published in GitHub Releases:\n\nhttps://github.com/caozhiyuan/copilot-api/releases\n\nOn Linux, make the downloaded AppImage executable before launching it:\n\n```sh\nchmod +x Copilot-API-*-linux-x86_64.AppImage\n./Copilot-API-*-linux-x86_64.AppImage\n```\n\nDownload the installer for your platform, authorize or configure a provider inside the app, choose a port, start the server, then point your client at the local endpoint shown in the app. Packaged desktop builds use the bundled Electron runtime, so normal desktop usage does not require installing Node.js separately. Token usage history is enabled when that bundled runtime supports SQLite.\n\nThe desktop app's Advanced Config page reads and writes the shared model mappings through `GET/POST /admin/config/model-mappings`. The same mappings apply across `POST /v1/messages`, `POST /v1/messages/count_tokens`, `POST /v1/responses`, and `POST /v1/chat/completions` instead of being split per interface. It uses `auth.adminApiKey` instead of the regular `auth.apiKeys`, and the app reads that key directly from `config.json` after the server has generated it on startup.\n\n### Desktop App Screenshots\n\nMain dashboard, token usage breakdown in the bundled Electron app:\n\n<p align=\"center\">\n  <img src=\"./docs/screenshots/desktop-dashboard.png\" alt=\"Copilot API desktop app dashboard\" width=\"49%\" />\n  <img src=\"./docs/screenshots/desktop-token-usage.png\" alt=\"Copilot API desktop app token usage view\" width=\"49%\" />\n</p>\n\n## Using with Claude Code\n\nThis AI gateway can be used to power [Claude Code](https://docs.anthropic.com/en/claude-code), an experimental conversational AI assistant for developers from Anthropic.\n\nThere are two ways to configure Claude Code to use this AI gateway:\n\n### Interactive Setup with `--claude-code` flag\n\nTo get started, run the `start` command with the `--claude-code` flag:\n\n```sh\nnpx @jeffreycao/copilot-api@latest start --claude-code\n```\n\nYou will no longer be prompted to pick models manually. The gateway automatically detects the latest available model for each Claude Code size tier — opus maps to the newest Opus model, sonnet to the newest Sonnet model, and haiku to the newest Haiku model — and generates a command that sets `ANTHROPIC_DEFAULT_OPUS_MODEL`, `ANTHROPIC_DEFAULT_SONNET_MODEL`, and `ANTHROPIC_DEFAULT_HAIKU_MODEL` accordingly. Any tier without a matching model available is omitted. The command is copied to your clipboard and sets the environment variables needed for Claude Code to use the gateway.\n\nPaste and run this command in a new terminal to launch Claude Code.\n\n### Manual Configuration with `settings.json`\n\nAlternatively, you can configure Claude Code by creating a `.claude/settings.json` file in your project's root directory. This file should contain the environment variables needed by Claude Code. This way you don't need to run the interactive setup every time.\n\nHere is an example `.claude/settings.json` file:\n\n```json\n{\n  \"env\": {\n    \"ANTHROPIC_BASE_URL\": \"http://localhost:4141\",\n    \"ANTHROPIC_AUTH_TOKEN\": \"dummy\",\n    \"ANTHROPIC_MODEL\": \"gpt-5.6-sol[1m]\",\n    \"ANTHROPIC_DEFAULT_SONNET_MODEL\": \"gpt-5.6-sol[1m]\",\n    \"ANTHROPIC_DEFAULT_HAIKU_MODEL\": \"gpt-5.6-luna[1m]\",\n    \"CLAUDE_CODE_AUTO_COMPACT_WINDOW\": \"272000\",\n    \"CLAUDE_CODE_USE_VERTEX\": \"0\",\n    \"CLAUDE_CODE_USE_BEDROCK\": \"0\",\n    \"DISABLE_NON_ESSENTIAL_MODEL_CALLS\": \"1\",\n    \"CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC\": \"1\",\n    \"CLAUDE_CODE_ATTRIBUTION_HEADER\": \"0\",\n    \"CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION\": \"false\",\n    \"CLAUDE_CODE_DISABLE_TERMINAL_TITLE\": \"true\",\n    \"CLAUDE_CODE_ENABLE_AWAY_SUMMARY\": \"0\"\n  },\n  \"alwaysThinkingEnabled\": true,\n  \"effortLevel\": \"xhigh\",\n  \"showThinkingSummaries\": true\n}\n```\n\n- Replace `ANTHROPIC_MODEL`, `ANTHROPIC_DEFAULT_OPUS_MODEL`, `ANTHROPIC_DEFAULT_SONNET_MODEL`, and `ANTHROPIC_DEFAULT_HAIKU_MODEL` according to your needs. After configuration, please install the claude code plugin [Plugin Integrations](#plugin-integrations).  \n- If you are using the codex provider, it is recommended **not** to configure the model name in the `codex/xxx` format (e.g. `codex/gpt-5.6-sol`). Claude Code treats the `codex/` prefix as a special pattern and applies degraded behavior — for example, it strips all previously returned thinking blocks on every request. Use the plain model name (e.g. `gpt-5.6-sol`) instead, and add a `modelMappings` entry in `config.json` to route it back to the codex provider:\n  ```json\n  \"modelMappings\": {\n    \"gpt-5.6-sol\": \"codex/gpt-5.6-sol\",\n    \"gpt-5.6-terra\": \"codex/gpt-5.6-terra\",\n    \"gpt-5.6-luna\": \"codex/gpt-5.6-luna\"\n  },\n  ```\n- Setting CLAUDE_CODE_ATTRIBUTION_HEADER to 0 can prevent Claude code from adding billing and version information in system prompts, thereby avoiding prompt cache invalidation.\n- Turning off CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION and CLAUDE_CODE_ENABLE_AWAY_SUMMARY can prevent quota from being consumed unnecessarily.\n- Claude Code WebSearch is supported for pure search requests. For Copilot, keep the global `messageApiWebSearchModel` set to a Responses-capable GPT model or a `provider/model` alias. For provider routes, use a native Anthropic provider or an `openai-responses` provider. Add `WebSearch` to `permissions.deny` only if you want to forbid this traffic.\n- If using a non-Claude model, do not enable ENABLE_TOOL_SEARCH. If using the Claude model, can enable ENABLE_TOOL_SEARCH. The current Claude Code uses the client tool search mode. In this mode, loading defer tools requires an additional request each time.\n- `CLAUDE_CODE_AUTO_COMPACT_WINDOW`: Set the context capacity in tokens used for auto-compaction calculations. Defaults to the model's context window: 200K for standard models or 1M for extended context models. Use a lower value like `500000` on a 1M model (e.g., `claude-opus-4-6[1m]`) to treat the window as 500K for compaction purposes. The value is capped at the model's actual context window. `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` is applied as a percentage of this value. Setting this variable decouples the compaction threshold from the status line's `used_percentage`, which always uses the model's full context window.\n\nYou can find more options here: [Claude Code settings](https://docs.anthropic.com/en/docs/claude-code/settings#environment-variables)\n\nYou can also read more about IDE integration here: [Add Claude Code to your IDE](https://docs.anthropic.com/en/docs/claude-code/ide-integrations)\n\n## Using with OpenCode\n\nOpenCode already has a direct GitHub Copilot provider. Use this section when you want OpenCode to point at this AI gateway through `@ai-sdk/anthropic` and reuse the agent behaviors described earlier in this README.\n\n### Minimal setup\n\nStart the AI gateway with the OpenCode OAuth app:\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth --oauth-app=opencode\nnpx @jeffreycao/copilot-api@latest start\n```\n\nThen point OpenCode at the gateway with `@ai-sdk/anthropic`.\n\nExample `~/.config/opencode/opencode.json`:\n\n```json\n{\n  \"$schema\": \"https://opencode.ai/config.json\",\n  \"provider\": {\n    \"local\": {\n      \"npm\": \"@ai-sdk/anthropic\",\n      \"name\": \"My Local\",\n      \"options\": {\n        \"baseURL\": \"http://localhost:4141/v1\",\n        \"apiKey\": \"dummy\"\n      },\n      \"models\": {\n        \"gpt-5.4\": {\n          \"name\": \"gpt-5.4\",\n          \"modalities\": {\n            \"input\": [\"text\", \"image\"],\n            \"output\": [\"text\"]\n          },\n          \"limit\": {\n            \"context\": 400000,\n            \"input\": 272000,\n            \"output\": 128000\n          }\n        },\n        \"claude-sonnet-4.6\": {\n          \"id\": \"claude-sonnet-4.6\",\n          \"name\": \"claude-sonnet-4.6\",\n          \"modalities\": {\n            \"input\": [\"text\", \"image\"],\n            \"output\": [\"text\"]\n          },          \n          \"limit\": {\n            \"context\": 200000,\n            \"output\": 32000\n          },\n          \"options\": {\n            \"thinking\": {\n              \"type\": \"adaptive\"\n            },\n            \"effort\": \"max\"\n          }\n        }\n      }\n    }\n  }\n}\n```\n\nWhy these fields matter:\n\n- `npm: \"@ai-sdk/anthropic\"` is the important part. OpenCode will speak Anthropic Messages semantics to this AI gateway instead of flattening everything into OpenAI Chat Completions.\n- `options.baseURL` should be `http://localhost:4141/v1`; the Anthropic SDK will append `/messages`, `/models`, and `/messages/count_tokens` automatically.\n- If you enable `auth.apiKeys` in this AI gateway, replace `dummy` with a real key. Otherwise any placeholder value is fine.\n\n## Using with Codex\n\nThis AI gateway can also power Codex.\n\n### Codex `config.toml` Reference\n\nAdd the following `[model_providers.copilot_api]` section to your Codex `~/.codex/config.toml`:\n\n```toml\nmodel_provider = \"copilot_api\"\nmodel_reasoning_summary = \"auto\"\nmodel_context_window = 272000\nmodel_auto_compact_token_limit = 244800\n\n[model_providers.copilot_api]\nname = \"OpenAI\"\nbase_url = \"http://localhost:4141\"\nenv_key = \"GITHUB_COPILOT_API_KEY\"\nrequires_openai_auth = true\nsupports_websockets = false\nwire_api = \"responses\"\nrequest_max_retries = 3\nstream_max_retries = 1\nstream_idle_timeout_ms = 300000\n\n[features]\nremote_compaction_v2 = true\n\n[analytics]\nenabled = false\n```\n\n> [!NOTE]\n> This configuration is specific to Codex and the GitHub Copilot provider. `name` must be set to `\"OpenAI\"`. It can help mitigate Codex local compact cache miss issues.\n> If you are using the codex provider, it is recommended to set `base_url` to `\"http://localhost:4141/codex\"`.\n\n## GPT Tool Search\n\nFor GPT Responses models such as `gpt-5.4+`, this AI gateway can expose Responses `tool_search` through a small MCP bridge. The same bridge can be used by Claude Code and opencode, as long as the client loads MCP servers and sends Anthropic Messages traffic through this gateway.\n\nDo not set Claude Code's native `ENABLE_TOOL_SEARCH` for GPT models. That flag enables Claude Code's own client-side tool search mode, and it may stop forwarding deferred tool definitions. This gateway needs the full tool definitions so it can keep the small always-loaded tool set eager and translate every other tool into Responses deferred namespaces.\n\nIf you install `tool-search@copilot-api-marketplace`, Claude Code receives this MCP bridge automatically and you can skip the manual Claude Code MCP setup below.\n\nAdd the tool search bridge to the MCP config used by Claude Code:\n\n```json\n{\n  \"mcpServers\": {\n    \"tool_search\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@jeffreycao/copilot-api@latest\", \"mcp\"]\n    }\n  }\n}\n```\n\nAdd the tool search bridge to the MCP config used by opencode:\n\n```json\n{\n  \"mcp\": {\n    \"tool_search\": {\n      \"type\": \"local\",\n      \"command\": [\"npx\", \"-y\", \"@jeffreycao/copilot-api@latest\", \"mcp\"]\n    }\n  }\n}\n```\n\nFor local development, use `bun` as the command and `[\"run\", \"./src/main.ts\", \"mcp\"]` as the args.\n\nInternally, the gateway now configures OpenAI Responses `tool_search` in client-executed mode. Deferred tools are still exposed as searchable namespaces, but the model is explicitly asked to return the exact deferred tool names it wants to load next.\n\nThe bridge uses direct tool selection, not query search. Its tool input is `names`, a comma-separated list of exact deferred tool names, for example `TaskList,TaskGet,mcp__fetch__fetch`.\n\n## Plugin Integrations\n\nPlugin integrations are available for Claude Code and opencode.\n\n#### Claude Code plugin integration (marketplace-based)\n\nThe Claude Code integration is packaged as two plugins:\n\n- `agent-inject` injects `__SUBAGENT_MARKER__...` on `SubagentStart`, so the gateway can infer `x-initiator: agent`.\n- `tool-search` registers the `tool_search` MCP bridge used for GPT Responses deferred tool loading.\n\n- Marketplace catalog in this repository: `.claude-plugin/marketplace.json`\n- Plugin sources in this repository: `plugin/claude/agent-inject`, `plugin/claude/tool-search`\n\nAdd the marketplace remotely:\n\n```sh\n/plugin marketplace add https://github.com/caozhiyuan/copilot-api.git\n```\n\nInstall the plugins from the marketplace:\n\n```sh\n/plugin install agent-inject@copilot-api-marketplace\n/plugin install tool-search@copilot-api-marketplace\n```\n\nAfter installation, `agent-inject` injects `__SUBAGENT_MARKER__...` on `SubagentStart`, and the gateway uses it to infer `x-initiator: agent`.\n\nThe `agent-inject` plugin also registers a `UserPromptSubmit` hook that returns `{\"continue\": true}`, and it can inject `SessionStart` reminder rules through environment variables:\n\n- `CLAUDE_PLUGIN_ENABLE_QUESTION_RULES=1` enables the two reminders about using the `question` tool automatically for Claude Code. Alternatively, you can add the same reminders manually in `CLAUDE.md`; see [CLAUDE.md or AGENTS.md Recommended Content](#claudemd-or-agentsmd-recommended-content).\n- `CLAUDE_PLUGIN_ENABLE_NO_BACKGROUND_AGENTS_RULE=1` enables the `run_in_background: true` avoidance reminder for agent hooks.\n\nThe `tool-search` plugin bundles the same MCP bridge described in [GPT Tool Search](#gpt-tool-search), so Claude Code users do not need to add the `tool_search` server manually when they install that plugin.\n\n#### Opencode plugin\n\nThe subagent marker producer is packaged as an opencode plugin located at `plugin/opencode/subagent-marker.js`.\n\n**Installation:**\n\nCopy the plugin file to your opencode plugins directory:\n\n```sh\n# Clone or download this repository, then copy the plugin\ncp plugin/opencode/subagent-marker.js ~/.config/opencode/plugins/\n```\n\nOr manually create the file at `~/.config/opencode/plugins/subagent-marker.js` with the plugin content.\n\n**Features:**\n\n- Tracks sub-sessions created by subagents\n- Automatically prepends a marker system reminder (`__SUBAGENT_MARKER__...`) to subagent chat messages\n- Sets `x-session-id` header for session tracking\n- Enables the gateway to infer `x-initiator: agent` for subagent-originated requests\n\nThe plugin hooks into `session.created`, `session.deleted`, `chat.message`, and `chat.headers` events to provide seamless subagent marker functionality.\n\n## Using the Usage Viewer\n\nAfter starting the server, a URL to the Copilot Usage Dashboard will be displayed in your console. This dashboard is a web interface for monitoring your API usage.\n\n1.  Start the server. For example, using npx:\n    ```sh\n    npx @jeffreycao/copilot-api@latest start\n    ```\n2.  The server will output a URL to the usage viewer. Copy and paste this URL into your browser. It will look something like this:\n    `http://localhost:4141/usage-viewer?endpoint=http://localhost:4141/usage`\n    - If you use the `start.bat` script on Windows, this page will open automatically.\n\nThe dashboard provides a user-friendly interface to view your Copilot usage data:\n\n> Token usage history requires Bun or Node.js >= 22.13.0. On Node.js < 22.13.0, the server runs normally but token usage storage is disabled.\n\n- **API Endpoint URL**: The dashboard is pre-configured to fetch data from your local server endpoint via a URL query parameter. You can manually switch this to any other compatible API endpoint.\n- **x-api-key Authentication**: If API Key authentication is enabled, you can provide the `x-api-key` request header. The key is persisted in the browser's local storage.\n- **Period Selector**: Choose from Day, Week, or Month time ranges. The URL query parameter updates automatically when you switch, making it easy to bookmark and share.\n- **Fetch Data**: Click the \"Refresh\" button to load or refresh the usage data. The dashboard also fetches data automatically on page load.\n- **Copilot Quotas**: View quota usage for services such as Chat and Completions via progress bars. Hover over a card to see used/remaining details.\n- **Token Usage Metric Cards**: See a summary of Total, Input, Output, Cache Read, Cache Write, Requests, and estimated cost for the current period.\n- **Trend Chart (Week / Month)**: An interactive line chart with model and metric filters. Click a data point to inspect the usage breakdown for a specific day.\n- **Model Breakdown Table**: A per-model summary of requests, input/output/cache tokens, and estimated cost for the selected period.\n- **Request Events (Paginated)**: A time-sorted list of request event records with pagination support, showing timestamps, models, request IDs, and token counts.\n- **Detailed Information**: See the full JSON response from the API for a detailed breakdown of all available usage statistics.\n- **URL-based Configuration**: You can also specify the API endpoint and period directly via `endpoint` and `period` query parameters. For example:\n  `http://localhost:4141/usage-viewer?endpoint=http://your-api-server/usage&period=week`\n\n### Usage Viewer Screenshot\n\n<p align=\"center\">\n  <img src=\"./docs/screenshots/usage-viewer.png\" alt=\"Copilot API usage viewer\" width=\"900\" />\n</p>\n\n## Command Structure\n\nCopilot API now uses a subcommand structure with these main commands:\n\n- `start`: Start the gateway server. If a GitHub token is available, the server starts with Copilot enabled. If no GitHub token is available, it starts in provider-only mode when at least one enabled provider exists; otherwise it guides you through provider setup.\n- `auth`: Run provider login or configuration without starting the server. Use it for GitHub Copilot login, Codex OAuth, or third-party provider API key setup.\n- `debug`: Display diagnostic information including version, runtime details, file paths, and authentication status. Useful for troubleshooting and support.\n\n## Command Line Options\n\n### Global Options\n\nThe following options can be used with any subcommand. When passing them before the subcommand, use the `--key=value` form:\n\n| Option            | Description                                            | Default | Alias |\n| ----------------- | ------------------------------------------------------ | ------- | ----- |\n| --api-home        | Path to the API home directory (sets COPILOT_API_HOME) | none    | none  |\n| --oauth-app       | OAuth app identifier (sets COPILOT_API_OAUTH_APP)      | none    | none  |\n| --enterprise-url  | Enterprise URL for GitHub (sets COPILOT_API_ENTERPRISE_URL) | none | none |\n\n### Start Command Options\n\nThe following command line options are available for the `start` command:\n\n| Option         | Description                                                                   | Default    | Alias |\n| -------------- | ----------------------------------------------------------------------------- | ---------- | ----- |\n| --port         | Port to listen on                                                             | 4141       | -p    |\n| --verbose      | Enable verbose logging                                                        | false      | -v    |\n| --github-token | Provide GitHub token directly (must be generated using the `auth` subcommand) | none       | -g    |\n| --claude-code  | Generate a command to launch Claude Code with Copilot API config              | false      | -c    |\n| --show-token   | Show GitHub and Copilot tokens on fetch and refresh                           | false      | none  |\n| --proxy-env    | Initialize proxy from environment variables                                   | false      | none  |\n\n### Auth Command Options\n\n| Option       | Description               | Default | Alias |\n| ------------ | ------------------------- | ------- | ----- |\n| --provider   | Provider to log in with or configure (`copilot`, `codex`, `opencode-go`, `deepseek`, `dashscope`, `openrouter`, or `custom`) | prompt | none |\n| --verbose    | Enable verbose logging    | false   | -v    |\n| --show-token | Show GitHub token on auth | false   | none  |\n\nUse `copilot-api auth login --provider copilot` only when you want to enable the GitHub Copilot provider. Copilot is not required for `codex` or third-party provider-only usage.\n\nUse `copilot-api auth login --provider deepseek`, `--provider dashscope`, `--provider openrouter`, or `--provider opencode-go` to add or update those common third-party providers from the CLI. DeepSeek prompts for masked `apiKey`, provider `type` (default `anthropic`), and `baseUrl` defaulting to `https://api.deepseek.com/anthropic`. DashScope prompts for masked `apiKey`, provider `type` (default `openai-compatible`), and prefilled `baseUrl`. OpenRouter prompts for masked `apiKey` and prefilled `baseUrl` only, and writes `type: \"anthropic\"`. OpenCode Go prompts for masked `apiKey` and prefilled `baseUrl` only, and writes `type: \"openai-compatible\"` (baseUrl `https://opencode.ai/zen/go`). After a provider is configured and enabled, `copilot-api start` can run without any GitHub token.\n\nUse `copilot-api auth login --provider custom` to add or update another third-party provider from the CLI. The command prompts for the provider name, supported type (`anthropic`, `openai-compatible`, or `openai-responses`), `baseUrl`, masked `apiKey`, and `authType`; `authType` may be left as the type default or set to `x-api-key` / `authorization`.\n\n### Debug Command Options\n\n| Option | Description               | Default | Alias |\n| ------ | ------------------------- | ------- | ----- |\n| --json | Output debug info as JSON | false   | none  |\n\n## Configuration (config.json)\n\n- **Location:** `~/.local/share/copilot-api/config.json` (Linux/macOS) or `%USERPROFILE%\\.local\\share\\copilot-api\\config.json` (Windows).\n- **Default shape:**\n  ```json\n  {\n    \"auth\": {\n      \"apiKeys\": [],\n      \"adminApiKey\": \"<auto-generated-on-startup>\"\n    },\n    \"providers\": {},\n    \"modelMappings\": {},\n    \"extraPrompts\": {\n      \"gpt-5-mini\": \"<built-in exploration prompt>\"\n    },\n    \"smallModel\": \"gpt-5-mini\",\n    \"contextManagement\": {\n      \"messages\": true,\n      \"responses\": false\n    },\n    \"modelResponsesApiCompactThresholds\": {\n      \"gpt-5.4\": 217600,\n      \"gpt-5.5\": 217600,\n      \"gpt-5.6-sol\": 231200,\n      \"gpt-5.6-terra\": 231200,\n      \"gpt-5.6-luna\": 231200\n    },\n    \"modelReasoningEfforts\": {\n      \"gpt-5-mini\": \"low\"\n    },\n    \"useMessagesApi\": true,\n    \"useResponsesApiWebSocket\": true,\n    \"useResponsesApiWebSearch\": true,\n    \"messageApiWebSearchModel\": \"gpt-5-mini\"\n  }\n  ```\n- **auth.apiKeys:** API keys used for request authentication on non-admin routes. Supports multiple keys for rotation. Requests can authenticate with either `x-api-key: <key>` or `Authorization: Bearer <key>`. If empty or omitted, authentication for non-admin routes is disabled.\n- **auth.adminApiKey:** Single admin key used only for `/admin/*` routes. If missing, the server generates a random key at startup and writes it back to `config.json`. Requests use the same `x-api-key` or `Authorization: Bearer` headers, but regular `auth.apiKeys` never grant access to `/admin/*`.\n- **modelMappings:** Exact `sourceModel -> targetModel` rewrites shared by top-level `POST /v1/messages`, `POST /v1/messages/count_tokens`, `POST /v1/responses`, and `POST /v1/chat/completions` requests. Omit it or leave it as `{}` to disable rewrites. Both the source and target must be non-empty strings. Targets can be regular model IDs or `provider/model` aliases such as `dashscope/qwen3.6-plus`, and the rewrite happens before provider alias parsing. These mappings are not split per interface. The admin endpoints `GET/POST /admin/config/model-mappings` read and update only this field.\n- **extraPrompts:** Map of `model -> prompt` appended to the first system prompt when translating Anthropic-style requests to Responses API. Use this to inject guardrails or guidance per model. Missing default entries are auto-added without overwriting your custom prompts. For GPT-5.3+ models (e.g. `gpt-5.3-codex`, `gpt-5.4`, `gpt-5.5`), a built-in commentary prompt is used as fallback when not explicitly configured. The built-in prompts enable phase-aware commentary, which lets the model emit a short user-facing progress update before tools or deeper reasoning.\n- **providers:** Global upstream provider map. Each provider key (for example `dashscope`) becomes a route prefix (`/dashscope/v1/messages`). Supports `type: \"anthropic\"`, `type: \"openai-compatible\"`, and `type: \"openai-responses\"`. Top-level clients can also use `model: \"dashscope/model-id\"` with `/v1/messages`, `/v1/messages/count_tokens`, `/v1/responses`, and `/v1/chat/completions`; the gateway strips the `dashscope/` prefix before forwarding upstream. `openai-compatible` providers support both chat and Messages flows: `/v1/chat/completions` is proxied to upstream `/v1/chat/completions`, while `/v1/messages` and `/:provider/v1/messages` are translated to upstream chat completions and translated back to Anthropic Messages responses. `GET /v1/models` aggregates enabled provider models with `provider/model-id` IDs; use `GET /dashscope/v1/models` for a single provider's raw model list.\n  - `enabled` defaults to `true` if omitted.\n  - `baseUrl` should be provider API base URL without the final endpoint. For Anthropic providers, omit `/v1/messages`; for OpenAI-compatible providers, omit `/v1/chat/completions`; for OpenAI Responses providers, omit `/v1/responses`.\n  - `apiKey` is used as the upstream credential value and is required for regular providers.\n  - `authType` (optional): Controls how `apiKey` is sent upstream. Supports `x-api-key` and `authorization` for regular providers. Anthropic providers default to `x-api-key`; OpenAI-compatible and OpenAI Responses providers default to `authorization`. When set to `authorization`, the proxy sends `Authorization: Bearer <apiKey>`. `oauth2` is reserved for the built-in `codex` provider and is written automatically by `auth login --provider codex`.\n  - `pricingCurrency` (optional): Provider-level currency used for token cost calculation, for example `USD` or `CNY`. Quick providers default to `CNY` for DashScope and DeepSeek, and `USD` for Codex/OpenRouter. Costs are grouped by currency and are not exchange-rate converted.\n  - `models` (optional): Per-model configuration map. Each key is a model ID (matching the model name in requests), and the value is:\n    - `temperature` (optional): Default temperature value used when the request does not specify one.\n    - `topP` (optional): Default top_p value used when the request does not specify one.\n    - `topK` (optional): Default top_k value used when the request does not specify one.\n    - `extraBody` (optional): Dynamic fields merged into the upstream request body for that model. Request body fields with the same name take precedence. OpenAI-compatible providers can use this for fields such as `enable_thinking`, `preserve_thinking`, `reasoning_effort`. `thinking_budget` is a special OpenAI-compatible provider override: when configured in `extraBody`, it is forced after Anthropic `thinking.budget_tokens` translation and overrides the request-derived budget. For providers whose name is `dashscope` or whose `baseUrl` contains `aliyuncs.com`, the request-derived `thinking_budget` (from Anthropic `thinking.budget_tokens`) is forwarded upstream; for other OpenAI-compatible providers the request-derived `thinking_budget` is stripped, while an `extraBody` `thinking_budget` is still honored. For DashScope providers, `preserve_thinking` defaults to `true` when not explicitly set in `extraBody` or the request body.\n    - `pricing` (optional): Per-model token prices, in the provider `pricingCurrency`, per 1M tokens. Supported fields are `input`, `output`, `cachedInput` (implicit cache read), `explicitCachedInput` (explicit cache read), and `cacheCreationInput`. Use `tiers` with `maxInputTokens` for input-size tiered pricing.\n    - `contextCache` (optional): Defaults to `true` for providers whose name is `dashscope` or whose `baseUrl` contains `aliyuncs.com`; defaults to `false` for other OpenAI-compatible providers. This enables Alibaba Cloud Model Studio/DashScope explicit context cache by injecting `cache_control: { \"type\": \"ephemeral\" }` on up to 4 content blocks using the Context Cache format. The cache breakpoint strategy matches opencode's main provider flow: the first 2 system messages plus the last 2 non-system messages. Marked string content is converted to text content part arrays for `system` / `user` / `assistant` / `tool` messages; existing array content is marked on the last part. Set this to `false` when the model already supports implicit caching, or when the upstream does not accept this explicit-cache extension field. Set this to `true` for non-DashScope providers that support the same explicit-cache extension. Applied on both `/v1/messages` and `/v1/chat/completions` routes.\n    - `supportPdf` (optional): Controls whether the model supports PDF/document content. Defaults to `false`; unsupported PDFs are converted to a text notice. Set it to `true` to send PDF/document blocks as OpenAI Chat Completions file parts.\n    - `toolContentSupportType` (optional): Tool result content capabilities for that model, as an array of `array`, `image`, and `pdf`. Provider routes default to string-only tool content when omitted. If `supportPdf` is `true` but this list does not include `pdf`, file parts in tool results are moved to user role messages. This provider default does not change the Copilot main flow, which continues to support array + image and not PDF.\n    - `type` (optional): Per-model override of the provider protocol type. Supports `anthropic`, `openai-compatible`, and `openai-responses`. When set, the provider's `/v1/messages` route uses this model's type instead of the provider-level type for request routing, auth header resolution, and upstream endpoint selection. This is useful for providers like OpenCode Go whose upstream supports both OpenAI-compatible and Anthropic Messages APIs for different models. When the type is overridden, the auth header is resolved from the overridden type's default (Anthropic defaults to `x-api-key`; OpenAI-compatible/Responses default to `authorization`).\n\n  Example DashScope model settings:\n  ```json\n  {\n    \"providers\": {\n      \"dashscope\": {\n        \"type\": \"openai-compatible\",\n        \"enabled\": true,\n        \"baseUrl\": \"https://dashscope.aliyuncs.com/compatible-mode\",\n        \"apiKey\": \"sk-your-dashscope-key\",\n        \"pricingCurrency\": \"CNY\",\n        \"models\": {\n          \"qwen3.7-plus\": {\n            \"temperature\": 1,\n            \"topP\": 0.95,\n            \"topK\": 20,\n            \"extraBody\": {\n              \"preserve_thinking\": true\n            }\n          },\n          \"glm-5.1\": {\n            \"temperature\": 0.7,\n            \"topP\": 0.95,\n            \"contextCache\": true,\n            \"pricing\": {\n              \"tiers\": [\n                {\n                  \"maxInputTokens\": 32000,\n                  \"input\": 6,\n                  \"cachedInput\": 1.2,\n                  \"explicitCachedInput\": 0.6,\n                  \"cacheCreationInput\": 7.5,\n                  \"output\": 24\n                },\n                {\n                  \"maxInputTokens\": 200000,\n                  \"input\": 8,\n                  \"cachedInput\": 1.6,\n                  \"explicitCachedInput\": 0.8,\n                  \"cacheCreationInput\": 10,\n                  \"output\": 28\n                }\n              ]\n            },\n            \"extraBody\": {\n              \"preserve_thinking\": true\n            }\n          }\n        }\n      }\n    }\n  }\n  ```\n  Built-in token prices cover Codex GPT models in USD, DashScope `qwen3.7-max`, `qwen3.7-plus`, `glm-5.1`, `glm-5.2` in CNY, DeepSeek `deepseek-v4-flash`, `deepseek-v4-pro`, `deepseek-chat`, `deepseek-reasoner` in CNY, and OpenCode Go models (`glm-5.2`, `grok-4.5`, `deepseek-v4-flash`, `deepseek-v4-pro`, `kimi-k2.7-code`, `kimi-k3`, `mimo-v2.5`, `mimo-v2.5-pro`, `qwen3.7-plus`, `qwen3.7-max`, `minimax-m2.7`, `minimax-m3`) in USD. User `pricing` entries override built-ins. For DashScope, cached tokens are charged as explicit cache reads when the upstream usage includes `cache_creation_input_tokens`; otherwise `cachedInput` is used as the implicit cache read price. For DeepSeek, `prompt_cache_hit_tokens` map to cached input and `prompt_cache_miss_tokens` map to regular input.\n- **smallModel:** Fallback model used for tool-less warmup messages (e.g., Claude Code probe requests); defaults to gpt-5-mini. The gateway forces this small model on no-tool warmup or probe requests to avoid consuming premium requests. This behavior only applies to non-token-based-billing GitHub Copilot accounts (`token_based_billing` is false); for token-based-billing accounts the warmup small-model fallback is skipped since there is no premium-request quota to preserve.\n- **contextManagement:** Controls whether the proxy adds Responses API `context_management` compaction instructions. `messages` applies when Anthropic-style `/v1/messages` requests are translated to Responses API, including `openai-responses` provider message routes, and defaults to `true`. `responses` applies to native `/v1/responses` traffic, including `provider/model` aliases and the built-in `codex` provider, and defaults to `false`. Enable `responses` only after checking that your client supports context management compaction. When enabled, the request includes `context_management` in the body and keeps only the latest compaction carrier on follow-up turns. **Note:** Context management is forcibly disabled for GPT-5.6 and above models (e.g. `gpt-5.6-sol`, `gpt-5.6-terra`, `gpt-5.6-luna`) because enabling it breaks prompt cache hits on those models. This override takes precedence over the `contextManagement` and `modelResponsesApiCompactThresholds` settings.\n- **modelResponsesApiCompactThresholds:** Per-model Responses API `compact_threshold` overrides used when the proxy adds `context_management`. These values take precedence over the fallback threshold from `resolveResponsesCompactThreshold` (`max_prompt_tokens * ratio`, or the default fallback). Defaults set `gpt-5.4` and `gpt-5.5` to `217600` (`272000 * 0.8`), and `gpt-5.6-sol`, `gpt-5.6-terra`, `gpt-5.6-luna` to `231200` (`272000 * 0.85`). Models not listed continue to use the normal fallback logic.\n- **modelReasoningEfforts:** Per-model fallback reasoning effort for `/v1/messages` requests. It is used only when the request does not provide `output_config.effort`.\n  - **Priority:** request `output_config.effort` > `modelReasoningEfforts[model]` > built-in default (`xhigh` for GPT-5.3+ models, otherwise `high`).\n  - **Forwarding:** the resolved value remains `output_config.effort` for the Copilot native Messages API and becomes `reasoning.effort` when translated to the Responses API.\n  - **Configuration values:** `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`.\n- **useMessagesApi:** When `true`, Claude-family models that support Copilot's native `/v1/messages` endpoint will use the Messages API; otherwise they fall back to `/chat/completions`. Set to `false` to disable Messages API routing and always use `/chat/completions`. Defaults to `true`.\n- **useResponsesApiWebSocket:** When `true`, Responses API requests use Copilot's websocket transport for models that advertise `ws:/responses`; models that only advertise `/responses` continue to use HTTP. Set to `false` to disable websocket routing and use HTTP `/responses` whenever the selected model supports it. Defaults to `true`. If the Responses API WebSocket gets closed, it is usually caused by your own network. If you are using a VPN, try switching to a different node.\n- **useResponsesApiWebSearch:** When `true`, the server keeps Responses API tools with `type: \"web_search\"` and forwards them upstream. Set to `false` to strip those tools from `/responses` payloads. Defaults to `true`.\n- **messageApiWebSearchModel:** Global fallback model used when a top-level Copilot `/v1/messages` request contains only the server-side `web_search` tool. Defaults to `gpt-5-mini`. If the value is a `provider/model` alias, the request is routed into that provider's Messages API path with the provider prefix stripped. For Copilot GPT models, web search runs through `/responses`. Mixed `web_search` plus custom tools are not supported and the server-side `web_search` tool is stripped.\n- **claudeTokenMultiplier:** Multiplier applied to the fallback GPT-tokenizer estimate for Claude `/v1/messages/count_tokens` requests. Defaults to `1.15`. Increase it if your client is still compacting too late. This setting is only used when the proxy is estimating Claude tokens locally; if `anthropicApiKey` is configured and Anthropic token counting succeeds, the exact Anthropic count is returned instead.\n- **anthropicApiKey:** Anthropic API key used to forward Claude `/v1/messages/count_tokens` requests to Anthropic's real token counting endpoint, which returns exact counts instead of GPT tokenizer estimates. Can also be set via the `ANTHROPIC_API_KEY` environment variable. If not set, or if the upstream call fails, token counting falls back to local GPT tokenizer estimation controlled by `claudeTokenMultiplier`.\n\nEdit this file to customize prompts or swap in your own fast model. Restart the server (or rerun the command) after changes so the cached config is refreshed.\n\n## API Authentication\n\n- **Protected non-admin routes:** All routes except `/`, `/usage-viewer`, and `/usage-viewer/` require authentication when `auth.apiKeys` is configured and non-empty.\n- **Admin routes:** All `/admin/*` routes require `auth.adminApiKey`. If it is missing, the server generates one at startup and persists it to `config.json` before serving requests.\n- **Allowed auth headers:**\n  - `x-api-key: <your_key>`\n  - `Authorization: Bearer <your_key>`\n- **CORS preflight:** `OPTIONS` requests are always allowed.\n- **When no regular keys are configured:** Non-admin routes continue to allow requests. This does not apply to `/admin/*`, which only accepts `auth.adminApiKey`.\n\nExample request for a regular protected route:\n\n```sh\ncurl http://localhost:4141/v1/models \\\n  -H \"x-api-key: your_api_key\"\n```\n\nExample request for an admin route:\n\n```sh\ncurl http://localhost:4141/admin/config/model-mappings \\\n  -H \"x-api-key: your_admin_api_key\"\n```\n\n## API Endpoints\n\nThe server exposes several OpenAI- and Anthropic-compatible endpoints. Requests can target GitHub Copilot, the built-in `codex` provider, or configured providers depending on the selected model and `provider/model` alias.\n\n### OpenAI Compatible Endpoints\n\nThese endpoints mimic the OpenAI API structure.\n\n| Endpoint                    | Method | Description                                                      |\n| --------------------------- | ------ | ---------------------------------------------------------------- |\n| `POST /v1/responses`        | `POST` | OpenAI Most advanced interface for generating model responses. Supports `provider/model` aliases for `openai-responses` providers. |\n| `POST /v1/chat/completions` | `POST` | Creates a model response for the given chat conversation. Supports `provider/model` aliases for `openai-compatible` providers and can be used without Copilot when the target provider is configured. |\n| `GET /v1/models`            | `GET`  | Lists Copilot models plus enabled provider models using `provider/model-id` IDs. Requests from Codex clients (`User-Agent` beginning with `codex`) are forwarded to the Codex Models upstream. |\n| `POST /v1/embeddings`       | `POST` | Creates an embedding vector representing the input text.         |\n\n### Codex Backend Proxy Endpoints\n\nThese endpoints require an active Codex login. Each endpoint is available both without a version prefix and under `/v1`.\n\n| Endpoint | Method | Description |\n| --- | --- | --- |\n| `POST /alpha/search`<br>`POST /v1/alpha/search` | `POST` | Transparently forwards the JSON body and query parameters to the Codex Alpha Search upstream. |\n| `POST /images/generations`<br>`POST /v1/images/generations` | `POST` | Forwards a JSON image generation request to the Codex Images upstream. When the request omits `Content-Type`, the gateway defaults it to `application/json`. |\n| `POST /images/edits`<br>`POST /v1/images/edits` | `POST` | Forwards an image edit request to the Codex Images upstream. Send this request as `multipart/form-data` and let the HTTP client generate the `boundary`; the gateway preserves the incoming content type and streams the upload body. |\n\nFor every endpoint above, the gateway replaces client authorization and account headers with the active Codex login, preserves query parameters and compatible request headers, and returns the upstream status, headers, and body.\n\n### Anthropic Compatible Endpoints\n\nThese endpoints are designed to be compatible with the Anthropic Messages API. Provider-scoped models, Responses, alpha-search, and images routes accept both unversioned and `/v1` paths; Messages routes remain under `/v1`.\n\n| Endpoint                         | Method | Description                                                  |\n| -------------------------------- | ------ | ------------------------------------------------------------ |\n| `POST /v1/messages`              | `POST` | Creates a model response for a given conversation. Supports `provider/model` aliases for configured providers, including translation through `openai-compatible` providers. |\n| `POST /v1/messages/count_tokens` | `POST` | Calculates the number of tokens for a given set of messages. Supports `provider/model` aliases for configured providers. |\n| `POST /:provider/v1/messages`       | `POST` | Proxies Anthropic Messages requests to the configured Anthropic provider, translates them through an OpenAI-compatible provider, or translates them through an OpenAI Responses provider. |\n| `GET /:provider/models`<br>`GET /:provider/v1/models` | `GET` | Proxies model listing requests to the configured provider. For `codex`, returns the built-in catalog by default; Codex clients (`User-Agent` starting with `codex`) are forwarded to the Codex Models upstream. |\n| `POST /:provider/v1/messages/count_tokens` | `POST` | Calculates tokens locally for provider route requests. |\n| `POST /:provider/responses`<br>`POST /:provider/v1/responses` | `POST` | Proxies OpenAI Responses requests to a configured `openai-responses` provider (including `codex`). |\n| `POST /:provider/alpha/search`<br>`POST /:provider/v1/alpha/search` | `POST` | Proxies alpha-search requests. For `codex`, forwards to the Codex Alpha Search upstream; for other providers, forwards to `{baseUrl}/v1/alpha/search`. |\n| `POST /:provider/images/generations`<br>`POST /:provider/v1/images/generations` | `POST` | Proxies image generation. For `codex`, uses the Codex Images upstream; for other providers, forwards to `{baseUrl}/v1/images/generations` (15-minute timeout). |\n| `POST /:provider/images/edits`<br>`POST /:provider/v1/images/edits` | `POST` | Proxies image edits. For `codex`, uses the Codex Images upstream; for other providers, forwards multipart/streamed bodies to `{baseUrl}/v1/images/edits` (15-minute timeout). |\n\n### Usage Monitoring Endpoints\n\nNew endpoints for monitoring your Copilot usage and quotas.\n\n| Endpoint     | Method | Description                                                  |\n| ------------ | ------ | ------------------------------------------------------------ |\n| `GET /usage` | `GET`  | Get detailed Copilot usage statistics and quota information. |\n| `GET /token` | `GET`  | Get the current Copilot token being used by the API.         |\n\n### Admin / Configuration Endpoints\n\nThese endpoints are reserved for local administrative actions and only accept `auth.adminApiKey`.\n\n| Endpoint                              | Method | Description                                                                 |\n| ------------------------------------- | ------ | --------------------------------------------------------------------------- |\n| `GET /admin/config/model-mappings`    | `GET`  | Returns the current `config.json` path and the active `modelMappings` map.  |\n| `POST /admin/config/model-mappings`   | `POST` | Updates only the `modelMappings` field in `config.json` and returns it back. |\n\n## Example Usage\n\nCommon `npx` commands:\n\n```sh\n# Start the gateway\nnpx @jeffreycao/copilot-api@latest start\n\n# Start on a custom port with verbose logging\nnpx @jeffreycao/copilot-api@latest start --port 8080 --verbose\n\n# Run the auth flow\nnpx @jeffreycao/copilot-api@latest auth login\n\n# Configure a third-party provider, then run without GitHub Copilot\nnpx @jeffreycao/copilot-api@latest auth login --provider dashscope\nnpx @jeffreycao/copilot-api@latest start\n\n# Print debug information as JSON\nnpx @jeffreycao/copilot-api@latest debug --json\n\n# Run the published CLI with Bun instead of Node.js\nbunx --bun @jeffreycao/copilot-api@latest start\n```\n\nOpenAI-compatible provider examples after configuring `dashscope`:\n\n```sh\ncurl http://localhost:4141/v1/chat/completions \\\n  -H \"content-type: application/json\" \\\n  -d '{\"model\":\"dashscope/qwen3.6-plus\",\"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]}'\n\ncurl http://localhost:4141/dashscope/v1/messages \\\n  -H \"content-type: application/json\" \\\n  -d '{\"model\":\"qwen3.6-plus\",\"max_tokens\":1024,\"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]}'\n```\n\n## Usage Tips\n\n### CLAUDE.md or AGENTS.md Recommended Content\n\nTo add these reminders manually, include the following in `CLAUDE.md` for Claude Code, or `AGENTS.md` for opencode/codex:\n\n```\n- Prohibited from directly asking questions to users, MUST use question tool.\n- Once you can confirm that the task is complete, MUST use question tool to make user confirm. The user may respond with feedback if they are not satisfied with the result, which you can use to make improvements and try again, after try again, MUST use question tool to make user confirm again.\n```\n"}, "d66d4fb4afedd4462dd2bd1d041501b112d4d52e": {"t": 1786068472.6466093, "n": 52630, "h": "ce1963ce71de80af", "c": "# Copilot API Proxy\n\nEnglish | [简体中文](./README.zh-CN.md)\n\n## Important Notes\n\n> [!IMPORTANT]\n> **Before using, please be aware of the following:**\n>\n> 1. **Claude Code configuration:** When using with Claude Code, please configure the model ID as `claude-opus-4-8`. Example claude `settings.json` see [Manual Configuration with `settings.json`](#manual-configuration-with-settingsjson). \n>\n> 2. **Built-in `copilot`, `codex` and third-party providers:** Run `npx @jeffreycao/copilot-api@latest auth` and choose `copilot`, `codex`, `deepseek`, `custom`, or other providers.\n>\n> 3. **Note:** See [GitHub Copilot Security Notice](./NOTICE.md#github-copilot-security-notice) for the warning removed from the README header.\n\n---\n\n## Project Overview\n\nA small AI gateway that can use GitHub Copilot, the built-in `codex` provider, or configured third-party providers such as DashScope. GitHub Copilot is optional: if no GitHub token is available, the server can still start in provider-only mode as long as at least one enabled provider is configured.\n\nThe gateway exposes OpenAI- and Anthropic-compatible APIs from one local endpoint, so tools like [Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview), OpenCode, Codex, and OpenAI-compatible clients can share the same local server.\n\nOn the GitHub Copilot path, the gateway prefers Copilot's native Anthropic-style Messages API when available, preserving more Claude-native behavior for tool-heavy workflows.\n\n## Features\n\n- **OpenAI and Anthropic compatibility**: Serve `/v1/responses`, `/v1/chat/completions`, `/v1/models`, `/v1/embeddings`, and `/v1/messages` from one local gateway.\n- **Copilot is optional**: Use GitHub Copilot when credentials are present, or run the server with only configured providers.\n- **One gateway for Copilot, `codex`, and external providers**: Route GitHub Copilot, the built-in `codex` provider, and configured third-party providers behind the same endpoint.\n- **Standalone third-party providers**: Configure providers such as DashScope, DeepSeek, OpenRouter, or a custom provider and start the gateway without a GitHub Copilot login.\n- **OpenAI-compatible providers on chat and Messages APIs**: `openai-compatible` providers can serve top-level `/v1/chat/completions` through `model: \"provider/model\"` and Anthropic-style `/v1/messages` through request/response translation.\n- **Agent-friendly Claude handling on Copilot**: Prefer native `/v1/messages` when available, preserve Claude-style tool flows, support Anthropic beta features, Claude WebSearch through Responses-capable models, and keep subagent/session markers intact.\n- **Claude Code and OpenCode integration**: Works with Claude Code and OpenCode, including direct Anthropic-compatible usage through `@ai-sdk/anthropic`.\n- **Flexible auth and deployment options**: Supports interactive login or direct tokens, individual/business/enterprise plans, GitHub Enterprise, opencode OAuth, and custom data directories.\n- **Multi-provider routing**: Expose provider-specific `/:provider/...` routes or use `model: \"provider/model\"` on the top-level API.\n\n## Prerequisites\n\n- Bun (>= 1.2.x)\n- Node.js if you plan to run the published CLI with `npx`\n- GitHub account with Copilot subscription only if you want to use the GitHub Copilot provider\n- An API key or OAuth login for at least one configured provider if you want to run without GitHub Copilot\n\n## Installation\n\nTo install dependencies, run:\n\n```sh\nbun install\n```\n\nTo start the server directly from source:\n\n```sh\nbun run start start\n```\n\n## Running from Source\n\nThe project can be run from source in several ways:\n\n### Development Mode\n\n```sh\nbun run dev start\n```\n\n### Production Mode\n\n```sh\nbun run start start\n```\n\n## Using with npx\n\nYou can run the project directly using npx:\n\n> [!IMPORTANT]\n> Token usage storage uses Node's built-in `node:sqlite` module when running with `npx`. It is enabled on Node.js >= 22.13.0. On Node.js < 22.13.0, the CLI still starts, but token usage storage is disabled.\n>\n> If you want token usage storage without upgrading Node.js, run the published CLI with Bun instead: `bunx --bun @jeffreycao/copilot-api@latest start`.\n\n```sh\nnpx @jeffreycao/copilot-api@latest start\n```\n\nWith options:\n\n```sh\nnpx @jeffreycao/copilot-api@latest start --port 8080\n```\n\nFor authentication or provider configuration only:\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth\n```\n\nTo run without GitHub Copilot, configure at least one provider first, then start the server normally:\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth login --provider dashscope\nnpx @jeffreycao/copilot-api@latest start\n```\n\n## Using with Docker\n\nBuild the image:\n\n```sh\ndocker build -t copilot-api .\n```\n\nRun the container with a bind mount so auth data survives restarts:\n\n```sh\nmkdir -p ./copilot-data\ndocker run -p 4141:4141 -v $(pwd)/copilot-data:/root/.local/share/copilot-api copilot-api\n```\n\nThis stores GitHub auth data, provider config, and other gateway state in `./copilot-data` on the host, mapped to `/root/.local/share/copilot-api` in the container.\n\nOr pass a GitHub token directly:\n\n```sh\ndocker run -p 4141:4141 -e GH_TOKEN=your_github_token_here copilot-api\n```\n\n## Electron Desktop App\n\nIf you prefer a GUI, this repository also includes an Electron desktop app in `desktop/`. It supports GitHub Copilot sign-in, OpenAI Codex OAuth, and API-key configuration for DeepSeek, DashScope, OpenRouter, or a custom provider. After authorization or provider configuration, it can start and stop the local proxy with one click and shows the local endpoint, auth header, available models, usage, and logs in the app.\n\nThe settings screen also exposes `OAuth App`, `API Home`, `Enterprise URL`, verbose logging, and minimize-to-tray. Windows x64 (`.exe`), macOS Apple Silicon (`.dmg`), and Linux x64 (`.AppImage`) packages are published in GitHub Releases:\n\nhttps://github.com/caozhiyuan/copilot-api/releases\n\nOn Linux, make the downloaded AppImage executable before launching it:\n\n```sh\nchmod +x Copilot-API-*-linux-x86_64.AppImage\n./Copilot-API-*-linux-x86_64.AppImage\n```\n\nDownload the installer for your platform, authorize or configure a provider inside the app, choose a port, start the server, then point your client at the local endpoint shown in the app. Packaged desktop builds use the bundled Electron runtime, so normal desktop usage does not require installing Node.js separately. Token usage history is enabled when that bundled runtime supports SQLite.\n\nThe desktop app's Advanced Config page reads and writes the shared model mappings through `GET/POST /admin/config/model-mappings`. The same mappings apply across `POST /v1/messages`, `POST /v1/messages/count_tokens`, `POST /v1/responses`, and `POST /v1/chat/completions` instead of being split per interface. It uses `auth.adminApiKey` instead of the regular `auth.apiKeys`, and the app reads that key directly from `config.json` after the server has generated it on startup.\n\n### Desktop App Screenshots\n\nMain dashboard, token usage breakdown in the bundled Electron app:\n\n<p align=\"center\">\n  <img src=\"./docs/screenshots/desktop-dashboard.png\" alt=\"Copilot API desktop app dashboard\" width=\"49%\" />\n  <img src=\"./docs/screenshots/desktop-token-usage.png\" alt=\"Copilot API desktop app token usage view\" width=\"49%\" />\n</p>\n\n## Using with Claude Code\n\nThis AI gateway can be used to power [Claude Code](https://docs.anthropic.com/en/claude-code), an experimental conversational AI assistant for developers from Anthropic.\n\nThere are two ways to configure Claude Code to use this AI gateway:\n\n### Interactive Setup with `--claude-code` flag\n\nTo get started, run the `start` command with the `--claude-code` flag:\n\n```sh\nnpx @jeffreycao/copilot-api@latest start --claude-code\n```\n\nYou will no longer be prompted to pick models manually. The gateway automatically detects the latest available model for each Claude Code size tier — opus maps to the newest Opus model, sonnet to the newest Sonnet model, and haiku to the newest Haiku model — and generates a command that sets `ANTHROPIC_DEFAULT_OPUS_MODEL`, `ANTHROPIC_DEFAULT_SONNET_MODEL`, and `ANTHROPIC_DEFAULT_HAIKU_MODEL` accordingly. Any tier without a matching model available is omitted. The command is copied to your clipboard and sets the environment variables needed for Claude Code to use the gateway.\n\nPaste and run this command in a new terminal to launch Claude Code.\n\n### Manual Configuration with `settings.json`\n\nAlternatively, you can configure Claude Code by creating a `.claude/settings.json` file in your project's root directory. This file should contain the environment variables needed by Claude Code. This way you don't need to run the interactive setup every time.\n\nHere is an example `.claude/settings.json` file:\n\n```json\n{\n  \"env\": {\n    \"ANTHROPIC_BASE_URL\": \"http://localhost:4141\",\n    \"ANTHROPIC_AUTH_TOKEN\": \"dummy\",\n    \"ANTHROPIC_MODEL\": \"gpt-5.6-sol[1m]\",\n    \"ANTHROPIC_DEFAULT_OPUS_MODEL\": \"gpt-5.6-sol[1m]\",\n    \"ANTHROPIC_DEFAULT_SONNET_MODEL\": \"gpt-5.6-sol[1m]\",\n    \"ANTHROPIC_DEFAULT_HAIKU_MODEL\": \"gpt-5.6-luna[1m]\",\n    \"CLAUDE_CODE_AUTO_COMPACT_WINDOW\": \"272000\",\n    \"CLAUDE_CODE_USE_VERTEX\": \"0\",\n    \"CLAUDE_CODE_USE_BEDROCK\": \"0\",\n    \"DISABLE_NON_ESSENTIAL_MODEL_CALLS\": \"1\",\n    \"CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC\": \"1\",\n    \"CLAUDE_CODE_ATTRIBUTION_HEADER\": \"0\",\n    \"CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION\": \"false\",\n    \"CLAUDE_CODE_DISABLE_TERMINAL_TITLE\": \"true\",\n    \"CLAUDE_CODE_ENABLE_AWAY_SUMMARY\": \"0\"\n  },\n  \"alwaysThinkingEnabled\": true,\n  \"effortLevel\": \"xhigh\",\n  \"showThinkingSummaries\": true\n}\n```\n\n- Replace `ANTHROPIC_MODEL`, `ANTHROPIC_DEFAULT_OPUS_MODEL`, `ANTHROPIC_DEFAULT_SONNET_MODEL`, and `ANTHROPIC_DEFAULT_HAIKU_MODEL` according to your needs. After configuration, please install the claude code plugin [Plugin Integrations](#plugin-integrations).  \n- If you are using the codex provider, it is recommended **not** to configure the model name in the `codex/xxx` format (e.g. `codex/gpt-5.6-sol`). Claude Code treats the `codex/` prefix as a special pattern and applies degraded behavior — for example, it strips all previously returned thinking blocks on every request. Use the plain model name (e.g. `gpt-5.6-sol`) instead, and add a `modelMappings` entry in `config.json` to route it back to the codex provider:\n  ```json\n  \"modelMappings\": {\n    \"gpt-5.6-sol\": \"codex/gpt-5.6-sol\",\n    \"gpt-5.6-terra\": \"codex/gpt-5.6-terra\",\n    \"gpt-5.6-luna\": \"codex/gpt-5.6-luna\"\n  },\n  ```\n- Setting CLAUDE_CODE_ATTRIBUTION_HEADER to 0 can prevent Claude code from adding billing and version information in system prompts, thereby avoiding prompt cache invalidation.\n- Turning off CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION and CLAUDE_CODE_ENABLE_AWAY_SUMMARY can prevent quota from being consumed unnecessarily.\n- Claude Code WebSearch is supported for pure search requests. For Copilot, keep the global `messageApiWebSearchModel` set to a Responses-capable GPT model or a `provider/model` alias. For provider routes, use a native Anthropic provider or an `openai-responses` provider. Add `WebSearch` to `permissions.deny` only if you want to forbid this traffic.\n- If using a non-Claude model, do not enable ENABLE_TOOL_SEARCH. If using the Claude model, can enable ENABLE_TOOL_SEARCH. The current Claude Code uses the client tool search mode. In this mode, loading defer tools requires an additional request each time.\n- `CLAUDE_CODE_AUTO_COMPACT_WINDOW`: Set the context capacity in tokens used for auto-compaction calculations. Defaults to the model's context window: 200K for standard models or 1M for extended context models. Use a lower value like `500000` on a 1M model (e.g., `claude-opus-4-6[1m]`) to treat the window as 500K for compaction purposes. The value is capped at the model's actual context window. `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` is applied as a percentage of this value. Setting this variable decouples the compaction threshold from the status line's `used_percentage`, which always uses the model's full context window.\n\nYou can find more options here: [Claude Code settings](https://docs.anthropic.com/en/docs/claude-code/settings#environment-variables)\n\nYou can also read more about IDE integration here: [Add Claude Code to your IDE](https://docs.anthropic.com/en/docs/claude-code/ide-integrations)\n\n## Using with OpenCode\n\nOpenCode already has a direct GitHub Copilot provider. Use this section when you want OpenCode to point at this AI gateway through `@ai-sdk/anthropic` and reuse the agent behaviors described earlier in this README.\n\n### Minimal setup\n\nStart the AI gateway with the OpenCode OAuth app:\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth --oauth-app=opencode\nnpx @jeffreycao/copilot-api@latest start\n```\n\nThen point OpenCode at the gateway with `@ai-sdk/anthropic`.\n\nExample `~/.config/opencode/opencode.json`:\n\n```json\n{\n  \"$schema\": \"https://opencode.ai/config.json\",\n  \"provider\": {\n    \"local\": {\n      \"npm\": \"@ai-sdk/anthropic\",\n      \"name\": \"My Local\",\n      \"options\": {\n        \"baseURL\": \"http://localhost:4141/v1\",\n        \"apiKey\": \"dummy\"\n      },\n      \"models\": {\n        \"gpt-5.4\": {\n          \"name\": \"gpt-5.4\",\n          \"modalities\": {\n            \"input\": [\"text\", \"image\"],\n            \"output\": [\"text\"]\n          },\n          \"limit\": {\n            \"context\": 400000,\n            \"input\": 272000,\n            \"output\": 128000\n          }\n        },\n        \"claude-sonnet-4.6\": {\n          \"id\": \"claude-sonnet-4.6\",\n          \"name\": \"claude-sonnet-4.6\",\n          \"modalities\": {\n            \"input\": [\"text\", \"image\"],\n            \"output\": [\"text\"]\n          },          \n          \"limit\": {\n            \"context\": 200000,\n            \"output\": 32000\n          },\n          \"options\": {\n            \"thinking\": {\n              \"type\": \"adaptive\"\n            },\n            \"effort\": \"max\"\n          }\n        }\n      }\n    }\n  }\n}\n```\n\nWhy these fields matter:\n\n- `npm: \"@ai-sdk/anthropic\"` is the important part. OpenCode will speak Anthropic Messages semantics to this AI gateway instead of flattening everything into OpenAI Chat Completions.\n- `options.baseURL` should be `http://localhost:4141/v1`; the Anthropic SDK will append `/messages`, `/models`, and `/messages/count_tokens` automatically.\n- If you enable `auth.apiKeys` in this AI gateway, replace `dummy` with a real key. Otherwise any placeholder value is fine.\n\n## Using with Codex\n\nThis AI gateway can also power Codex.\n\n### Codex `config.toml` Reference\n\nAdd the following `[model_providers.copilot_api]` section to your Codex `~/.codex/config.toml`:\n\n```toml\nmodel_provider = \"copilot_api\"\nmodel_reasoning_summary = \"auto\"\nmodel_context_window = 272000\nmodel_auto_compact_token_limit = 244800\n\n[model_providers.copilot_api]\nname = \"OpenAI\"\nbase_url = \"http://localhost:4141\"\nenv_key = \"GITHUB_COPILOT_API_KEY\"\nrequires_openai_auth = true\nsupports_websockets = false\nwire_api = \"responses\"\nrequest_max_retries = 3\nstream_max_retries = 1\nstream_idle_timeout_ms = 300000\n\n[features]\nremote_compaction_v2 = true\n\n[analytics]\nenabled = false\n```\n\n> [!NOTE]\n> This configuration is specific to Codex and the GitHub Copilot provider. `name` must be set to `\"OpenAI\"`. It can help mitigate Codex local compact cache miss issues.\n> If you are using the codex provider, it is recommended to set `base_url` to `\"http://localhost:4141/codex\"`.\n\nWhen Codex uses the top-level GitHub Copilot route with `approvals_reviewer = \"auto_review\"`, map its internal review model to a Responses-capable Copilot model in the gateway's `config.json`:\n\n```json\n{\n  \"modelMappings\": {\n    \"codex-auto-review\": \"gpt-5.6-luna\"\n  }\n}\n```\n\nThis mapping only applies to the top-level GitHub Copilot route. Provider-scoped routes do not use `modelMappings`, so the built-in `/codex` provider continues to handle `codex-auto-review` natively.\n\n## GPT Tool Search\n\nFor GPT Responses models such as `gpt-5.4+`, this AI gateway can expose Responses `tool_search` through a small MCP bridge. The same bridge can be used by Claude Code and opencode, as long as the client loads MCP servers and sends Anthropic Messages traffic through this gateway.\n\nDo not set Claude Code's native `ENABLE_TOOL_SEARCH` for GPT models. That flag enables Claude Code's own client-side tool search mode, and it may stop forwarding deferred tool definitions. This gateway needs the full tool definitions so it can keep the small always-loaded tool set eager and translate every other tool into Responses deferred namespaces.\n\nIf you install `tool-search@copilot-api-marketplace`, Claude Code receives this MCP bridge automatically and you can skip the manual Claude Code MCP setup below.\n\nAdd the tool search bridge to the MCP config used by Claude Code:\n\n```json\n{\n  \"mcpServers\": {\n    \"tool_search\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@jeffreycao/copilot-api@latest\", \"mcp\"]\n    }\n  }\n}\n```\n\nAdd the tool search bridge to the MCP config used by opencode:\n\n```json\n{\n  \"mcp\": {\n    \"tool_search\": {\n      \"type\": \"local\",\n      \"command\": [\"npx\", \"-y\", \"@jeffreycao/copilot-api@latest\", \"mcp\"]\n    }\n  }\n}\n```\n\nFor local development, use `bun` as the command and `[\"run\", \"./src/main.ts\", \"mcp\"]` as the args.\n\nInternally, the gateway now configures OpenAI Responses `tool_search` in client-executed mode. Deferred tools are still exposed as searchable namespaces, but the model is explicitly asked to return the exact deferred tool names it wants to load next.\n\nThe bridge uses direct tool selection, not query search. Its tool input is `names`, a comma-separated list of exact deferred tool names, for example `TaskList,TaskGet,mcp__fetch__fetch`.\n\n## Plugin Integrations\n\nPlugin integrations are available for Claude Code and opencode.\n\n#### Claude Code plugin integration (marketplace-based)\n\nThe Claude Code integration is packaged as two plugins:\n\n- `agent-inject` injects `__SUBAGENT_MARKER__...` on `SubagentStart`, so the gateway can infer `x-initiator: agent`.\n- `tool-search` registers the `tool_search` MCP bridge used for GPT Responses deferred tool loading.\n\n- Marketplace catalog in this repository: `.claude-plugin/marketplace.json`\n- Plugin sources in this repository: `plugin/claude/agent-inject`, `plugin/claude/tool-search`\n\nAdd the marketplace remotely:\n\n```sh\n/plugin marketplace add https://github.com/caozhiyuan/copilot-api.git\n```\n\nInstall the plugins from the marketplace:\n\n```sh\n/plugin install agent-inject@copilot-api-marketplace\n/plugin install tool-search@copilot-api-marketplace\n```\n\nAfter installation, `agent-inject` injects `__SUBAGENT_MARKER__...` on `SubagentStart`, and the gateway uses it to infer `x-initiator: agent`.\n\nThe `agent-inject` plugin also registers a `UserPromptSubmit` hook that returns `{\"continue\": true}`, and it can inject `SessionStart` reminder rules through environment variables:\n\n- `CLAUDE_PLUGIN_ENABLE_QUESTION_RULES=1` enables the two reminders about using the `question` tool automatically for Claude Code. Alternatively, you can add the same reminders manually in `CLAUDE.md`; see [CLAUDE.md or AGENTS.md Recommended Content](#claudemd-or-agentsmd-recommended-content).\n- `CLAUDE_PLUGIN_ENABLE_NO_BACKGROUND_AGENTS_RULE=1` enables the `run_in_background: true` avoidance reminder for agent hooks.\n\nThe `tool-search` plugin bundles the same MCP bridge described in [GPT Tool Search](#gpt-tool-search), so Claude Code users do not need to add the `tool_search` server manually when they install that plugin.\n\n#### Opencode plugin\n\nThe subagent marker producer is packaged as an opencode plugin located at `plugin/opencode/subagent-marker.js`.\n\n**Installation:**\n\nCopy the plugin file to your opencode plugins directory:\n\n```sh\n# Clone or download this repository, then copy the plugin\ncp plugin/opencode/subagent-marker.js ~/.config/opencode/plugins/\n```\n\nOr manually create the file at `~/.config/opencode/plugins/subagent-marker.js` with the plugin content.\n\n**Features:**\n\n- Tracks sub-sessions created by subagents\n- Automatically prepends a marker system reminder (`__SUBAGENT_MARKER__...`) to subagent chat messages\n- Sets `x-session-id` header for session tracking\n- Enables the gateway to infer `x-initiator: agent` for subagent-originated requests\n\nThe plugin hooks into `session.created`, `session.deleted`, `chat.message`, and `chat.headers` events to provide seamless subagent marker functionality.\n\n## Using the Usage Viewer\n\nAfter starting the server, a URL to the Copilot Usage Dashboard will be displayed in your console. This dashboard is a web interface for monitoring your API usage.\n\n1.  Start the server. For example, using npx:\n    ```sh\n    npx @jeffreycao/copilot-api@latest start\n    ```\n2.  The server will output a URL to the usage viewer. Copy and paste this URL into your browser. It will look something like this:\n    `http://localhost:4141/usage-viewer?endpoint=http://localhost:4141/usage`\n    - If you use the `start.bat` script on Windows, this page will open automatically.\n\nThe dashboard provides a user-friendly interface to view your Copilot usage data:\n\n> Token usage history requires Bun or Node.js >= 22.13.0. On Node.js < 22.13.0, the server runs normally but token usage storage is disabled.\n\n- **API Endpoint URL**: The dashboard is pre-configured to fetch data from your local server endpoint via a URL query parameter. You can manually switch this to any other compatible API endpoint.\n- **x-api-key Authentication**: If API Key authentication is enabled, you can provide the `x-api-key` request header. The key is persisted in the browser's local storage.\n- **Period Selector**: Choose from Day, Week, or Month time ranges. The URL query parameter updates automatically when you switch, making it easy to bookmark and share.\n- **Fetch Data**: Click the \"Refresh\" button to load or refresh the usage data. The dashboard also fetches data automatically on page load.\n- **Copilot Quotas**: View quota usage for services such as Chat and Completions via progress bars. Hover over a card to see used/remaining details.\n- **Token Usage Metric Cards**: See a summary of Total, Input, Output, Cache Read, Cache Write, Requests, and estimated cost for the current period.\n- **Trend Chart (Week / Month)**: An interactive line chart with model and metric filters. Click a data point to inspect the usage breakdown for a specific day.\n- **Model Breakdown Table**: A per-model summary of requests, input/output/cache tokens, and estimated cost for the selected period.\n- **Request Events (Paginated)**: A time-sorted list of request event records with pagination support, showing timestamps, models, request IDs, and token counts.\n- **Detailed Information**: See the full JSON response from the API for a detailed breakdown of all available usage statistics.\n- **URL-based Configuration**: You can also specify the API endpoint and period directly via `endpoint` and `period` query parameters. For example:\n  `http://localhost:4141/usage-viewer?endpoint=http://your-api-server/usage&period=week`\n\n### Usage Viewer Screenshot\n\n<p align=\"center\">\n  <img src=\"./docs/screenshots/usage-viewer.png\" alt=\"Copilot API usage viewer\" width=\"900\" />\n</p>\n\n## Command Structure\n\nCopilot API now uses a subcommand structure with these main commands:\n\n- `start`: Start the gateway server. If a GitHub token is available, the server starts with Copilot enabled. If no GitHub token is available, it starts in provider-only mode when at least one enabled provider exists; otherwise it guides you through provider setup.\n- `auth`: Run provider login or configuration without starting the server. Use it for GitHub Copilot login, Codex OAuth, or third-party provider API key setup.\n- `debug`: Display diagnostic information including version, runtime details, file paths, and authentication status. Useful for troubleshooting and support.\n\n## Command Line Options\n\n### Global Options\n\nThe following options can be used with any subcommand. When passing them before the subcommand, use the `--key=value` form:\n\n| Option            | Description                                            | Default | Alias |\n| ----------------- | ------------------------------------------------------ | ------- | ----- |\n| --api-home        | Path to the API home directory (sets COPILOT_API_HOME) | none    | none  |\n| --oauth-app       | OAuth app identifier (sets COPILOT_API_OAUTH_APP)      | none    | none  |\n| --enterprise-url  | Enterprise URL for GitHub (sets COPILOT_API_ENTERPRISE_URL) | none | none |\n\n### Start Command Options\n\nThe following command line options are available for the `start` command:\n\n| Option         | Description                                                                   | Default    | Alias |\n| -------------- | ----------------------------------------------------------------------------- | ---------- | ----- |\n| --port         | Port to listen on                                                             | 4141       | -p    |\n| --verbose      | Enable verbose logging                                                        | false      | -v    |\n| --github-token | Provide GitHub token directly (must be generated using the `auth` subcommand) | none       | -g    |\n| --claude-code  | Generate a command to launch Claude Code with Copilot API config              | false      | -c    |\n| --show-token   | Show GitHub and Copilot tokens on fetch and refresh                           | false      | none  |\n| --proxy-env    | Initialize proxy from environment variables                                   | false      | none  |\n\n### Auth Command Options\n\n| Option       | Description               | Default | Alias |\n| ------------ | ------------------------- | ------- | ----- |\n| --provider   | Provider to log in with or configure (`copilot`, `codex`, `opencode-go`, `deepseek`, `dashscope`, `openrouter`, or `custom`) | prompt | none |\n| --verbose    | Enable verbose logging    | false   | -v    |\n| --show-token | Show GitHub token on auth | false   | none  |\n\nUse `copilot-api auth login --provider copilot` only when you want to enable the GitHub Copilot provider. Copilot is not required for `codex` or third-party provider-only usage.\n\nUse `copilot-api auth login --provider deepseek`, `--provider dashscope`, `--provider openrouter`, or `--provider opencode-go` to add or update those common third-party providers from the CLI. DeepSeek prompts for masked `apiKey`, provider `type` (default `anthropic`), and `baseUrl` defaulting to `https://api.deepseek.com/anthropic`. DashScope prompts for masked `apiKey`, provider `type` (default `openai-compatible`), and prefilled `baseUrl`. OpenRouter prompts for masked `apiKey` and prefilled `baseUrl` only, and writes `type: \"anthropic\"`. OpenCode Go prompts for masked `apiKey` and prefilled `baseUrl` only, and writes `type: \"openai-compatible\"` (baseUrl `https://opencode.ai/zen/go`). OpenCode Go additionally routes built-in `qwen*` and `minimax*` models through Anthropic Messages and `gpt*` models through OpenAI Responses; other models keep the OpenAI-compatible default. After a provider is configured and enabled, `copilot-api start` can run without any GitHub token.\n\nUse `copilot-api auth login --provider custom` to add or update another third-party provider from the CLI. The command prompts for the provider name, supported type (`anthropic`, `openai-compatible`, or `openai-responses`), `baseUrl`, masked `apiKey`, and `authType`; `authType` may be left as the type default or set to `x-api-key` / `authorization`.\n\n### Debug Command Options\n\n| Option | Description               | Default | Alias |\n| ------ | ------------------------- | ------- | ----- |\n| --json | Output debug info as JSON | false   | none  |\n\n## Configuration (config.json)\n\n- **Location:** `~/.local/share/copilot-api/config.json` (Linux/macOS) or `%USERPROFILE%\\.local\\share\\copilot-api\\config.json` (Windows).\n- **Default shape:**\n  ```json\n  {\n    \"auth\": {\n      \"apiKeys\": [],\n      \"adminApiKey\": \"<auto-generated-on-startup>\"\n    },\n    \"providers\": {},\n    \"modelMappings\": {},\n    \"extraPrompts\": {\n      \"gpt-5-mini\": \"<built-in exploration prompt>\"\n    },\n    \"smallModel\": \"gpt-5-mini\",\n    \"contextManagement\": {\n      \"messages\": true,\n      \"responses\": false\n    },\n    \"modelResponsesApiCompactThresholds\": {\n      \"gpt-5.4\": 217600,\n      \"gpt-5.5\": 217600\n    },\n    \"modelReasoningEfforts\": {\n      \"gpt-5-mini\": \"low\"\n    },\n    \"useMessagesApi\": true,\n    \"useResponsesApiWebSocket\": true,\n    \"useResponsesApiWebSearch\": true,\n    \"messageApiWebSearchModel\": \"gpt-5-mini\"\n  }\n  ```\n- **auth.apiKeys:** API keys used for request authentication on non-admin routes. Supports multiple keys for rotation. Requests can authenticate with either `x-api-key: <key>` or `Authorization: Bearer <key>`. If empty or omitted, authentication for non-admin routes is disabled.\n- **auth.adminApiKey:** Single admin key used only for `/admin/*` routes. If missing, the server generates a random key at startup and writes it back to `config.json`. Requests use the same `x-api-key` or `Authorization: Bearer` headers, but regular `auth.apiKeys` never grant access to `/admin/*`.\n- **modelMappings:** Exact `sourceModel -> targetModel` rewrites shared by top-level `POST /v1/messages`, `POST /v1/messages/count_tokens`, `POST /v1/responses`, and `POST /v1/chat/completions` requests. Omit it or leave it as `{}` to disable rewrites. Both the source and target must be non-empty strings. Targets can be regular model IDs or `provider/model` aliases such as `dashscope/qwen3.6-plus`, and the rewrite happens before provider alias parsing. These mappings are not split per interface. The admin endpoints `GET/POST /admin/config/model-mappings` read and update only this field.\n- **extraPrompts:** Map of `model -> prompt` appended to the first system prompt when translating Anthropic-style requests to Responses API. Use this to inject guardrails or guidance per model. Missing default entries are auto-added without overwriting your custom prompts. For GPT-5.3+ models (e.g. `gpt-5.3-codex`, `gpt-5.4`, `gpt-5.5`), a built-in commentary prompt is used as fallback when not explicitly configured. The built-in prompts enable phase-aware commentary, which lets the model emit a short user-facing progress update before tools or deeper reasoning.\n- **providers:** Global upstream provider map. Each provider key (for example `dashscope`) becomes a route prefix (`/dashscope/v1/messages`). Supports `type: \"anthropic\"`, `type: \"openai-compatible\"`, and `type: \"openai-responses\"`. Top-level clients can also use `model: \"dashscope/model-id\"` with `/v1/messages`, `/v1/messages/count_tokens`, `/v1/responses`, and `/v1/chat/completions`; the gateway strips the `dashscope/` prefix before forwarding upstream. `openai-compatible` providers support both chat and Messages flows: `/v1/chat/completions` is proxied to upstream `/v1/chat/completions`, while `/v1/messages` and `/:provider/v1/messages` are translated to upstream chat completions and translated back to Anthropic Messages responses. `GET /v1/models` aggregates enabled provider models with `provider/model-id` IDs; use `GET /dashscope/v1/models` for a single provider's raw model list.\n  - `enabled` defaults to `true` if omitted.\n  - `baseUrl` should be provider API base URL without the final endpoint. For Anthropic providers, omit `/v1/messages`; for OpenAI-compatible providers, omit `/v1/chat/completions`; for OpenAI Responses providers, omit `/v1/responses`.\n  - `apiKey` is used as the upstream credential value and is required for regular providers.\n  - `authType` (optional): Controls how `apiKey` is sent upstream. Supports `x-api-key` and `authorization` for regular providers. Anthropic providers default to `x-api-key`; OpenAI-compatible and OpenAI Responses providers default to `authorization`. When set to `authorization`, the proxy sends `Authorization: Bearer <apiKey>`. `oauth2` is reserved for the built-in `codex` provider and is written automatically by `auth login --provider codex`.\n  - `pricingCurrency` (optional): Provider-level currency used for token cost calculation, for example `USD` or `CNY`. Quick providers default to `CNY` for DashScope and DeepSeek, and `USD` for Codex/OpenRouter. Costs are grouped by currency and are not exchange-rate converted.\n  - `models` (optional): Per-model configuration map. Each key is a model ID (matching the model name in requests), and the value is:\n    - `temperature` (optional): Default temperature value used when the request does not specify one.\n    - `topP` (optional): Default top_p value used when the request does not specify one.\n    - `topK` (optional): Default top_k value used when the request does not specify one.\n    - `extraBody` (optional): Dynamic fields merged into the upstream request body for that model. Request body fields with the same name take precedence. OpenAI-compatible providers can use this for fields such as `enable_thinking`, `preserve_thinking`, `reasoning_effort`. `thinking_budget` is a special OpenAI-compatible provider override: when configured in `extraBody`, it is forced after Anthropic `thinking.budget_tokens` translation and overrides the request-derived budget. For providers whose name is `dashscope` or whose `baseUrl` contains `aliyuncs.com`, the request-derived `thinking_budget` (from Anthropic `thinking.budget_tokens`) is forwarded upstream; for other OpenAI-compatible providers the request-derived `thinking_budget` is stripped, while an `extraBody` `thinking_budget` is still honored. For DashScope providers, `preserve_thinking` defaults to `true` when not explicitly set in `extraBody` or the request body.\n    - `pricing` (optional): Per-model token prices, in the provider `pricingCurrency`, per 1M tokens. Supported fields are `input`, `output`, `cachedInput` (implicit cache read), `explicitCachedInput` (explicit cache read), and `cacheCreationInput`. Use `tiers` with `maxInputTokens` for input-size tiered pricing.\n    - `contextCache` (optional): Defaults to `true` for providers whose name is `dashscope` or whose `baseUrl` contains `aliyuncs.com`; defaults to `false` for other OpenAI-compatible providers. This enables Alibaba Cloud Model Studio/DashScope explicit context cache by injecting `cache_control: { \"type\": \"ephemeral\" }` on up to 4 content blocks using the Context Cache format. The cache breakpoint strategy matches opencode's main provider flow: the first 2 system messages plus the last 2 non-system messages. Marked string content is converted to text content part arrays for `system` / `user` / `assistant` / `tool` messages; existing array content is marked on the last part. Set this to `false` when the model already supports implicit caching, or when the upstream does not accept this explicit-cache extension field. Set this to `true` for non-DashScope providers that support the same explicit-cache extension. Applied on both `/v1/messages` and `/v1/chat/completions` routes.\n    - `supportPdf` (optional): Controls whether the model supports PDF/document content. Defaults to `false`; unsupported PDFs are converted to a text notice. Set it to `true` to send PDF/document blocks as OpenAI Chat Completions file parts.\n    - `toolContentSupportType` (optional): Tool result content capabilities for that model, as an array of `array`, `image`, and `pdf`. Provider routes default to string-only tool content when omitted. If `supportPdf` is `true` but this list does not include `pdf`, file parts in tool results are moved to user role messages. This provider default does not change the Copilot main flow, which continues to support array + image and not PDF.\n    - `type` (optional): Per-model override of the provider protocol type. Supports `anthropic`, `openai-compatible`, and `openai-responses`. When set, the provider's `/v1/messages` route uses this model's type instead of the provider-level type for request routing, auth header resolution, and upstream endpoint selection. This is useful for providers like OpenCode Go whose upstream supports both OpenAI-compatible and Anthropic Messages APIs for different models. When the type is overridden, the auth header is resolved from the overridden type's default (Anthropic defaults to `x-api-key`; OpenAI-compatible/Responses default to `authorization`).\n\n  Example DashScope model settings:\n  ```json\n  {\n    \"providers\": {\n      \"dashscope\": {\n        \"type\": \"openai-compatible\",\n        \"enabled\": true,\n        \"baseUrl\": \"https://dashscope.aliyuncs.com/compatible-mode\",\n        \"apiKey\": \"sk-your-dashscope-key\",\n        \"pricingCurrency\": \"CNY\",\n        \"models\": {\n          \"qwen3.7-plus\": {\n            \"temperature\": 1,\n            \"topP\": 0.95,\n            \"topK\": 20,\n            \"extraBody\": {\n              \"preserve_thinking\": true\n            }\n          },\n          \"glm-5.1\": {\n            \"temperature\": 0.7,\n            \"topP\": 0.95,\n            \"contextCache\": true,\n            \"pricing\": {\n              \"tiers\": [\n                {\n                  \"maxInputTokens\": 32000,\n                  \"input\": 6,\n                  \"cachedInput\": 1.2,\n                  \"explicitCachedInput\": 0.6,\n                  \"cacheCreationInput\": 7.5,\n                  \"output\": 24\n                },\n                {\n                  \"maxInputTokens\": 200000,\n                  \"input\": 8,\n                  \"cachedInput\": 1.6,\n                  \"explicitCachedInput\": 0.8,\n                  \"cacheCreationInput\": 10,\n                  \"output\": 28\n                }\n              ]\n            },\n            \"extraBody\": {\n              \"preserve_thinking\": true\n            }\n          }\n        }\n      }\n    }\n  }\n  ```\n  Built-in token prices cover Codex GPT models in USD, DashScope `qwen3.7-max`, `qwen3.7-plus`, `glm-5.1`, `glm-5.2` in CNY, DeepSeek `deepseek-v4-flash`, `deepseek-v4-pro`, `deepseek-chat`, `deepseek-reasoner` in CNY, and OpenCode Go models (`hy3`, `gpt-5.6-luna`, `glm-5.2`, `grok-4.5`, `deepseek-v4-flash`, `deepseek-v4-pro`, `kimi-k2.7-code`, `kimi-k3`, `mimo-v2.5`, `mimo-v2.5-pro`, `qwen3.7-plus`, `qwen3.7-max`, `minimax-m2.7`, `minimax-m3`) in USD. User `pricing` entries override built-ins. For DashScope, cached tokens are charged as explicit cache reads when the upstream usage includes `cache_creation_input_tokens`; otherwise `cachedInput` is used as the implicit cache read price. For DeepSeek, `prompt_cache_hit_tokens` map to cached input and `prompt_cache_miss_tokens` map to regular input.\n- **smallModel:** Fallback model used for tool-less warmup messages (e.g., Claude Code probe requests); defaults to gpt-5-mini. The gateway forces this small model on no-tool warmup or probe requests to avoid consuming premium requests. This behavior only applies to non-token-based-billing GitHub Copilot accounts (`token_based_billing` is false); for token-based-billing accounts the warmup small-model fallback is skipped since there is no premium-request quota to preserve.\n- **contextManagement:** Controls whether the proxy adds Responses API `context_management` compaction instructions. `messages` applies when Anthropic-style `/v1/messages` requests are translated to Responses API, including `openai-responses` provider message routes, and defaults to `true`. `responses` applies to native `/v1/responses` traffic, including `provider/model` aliases and the built-in `codex` provider, and defaults to `false`. Enable `responses` only after checking that your client supports context management compaction. When enabled, the request includes `context_management` in the body and keeps only the latest compaction carrier on follow-up turns. **Note:** Context management is forcibly disabled for GPT-5.6 and above models (e.g. `gpt-5.6-sol`, `gpt-5.6-terra`, `gpt-5.6-luna`) because enabling it breaks prompt cache hits on those models. This override takes precedence over the `contextManagement` and `modelResponsesApiCompactThresholds` settings.\n - **modelResponsesApiCompactThresholds:** Per-model Responses API `compact_threshold` overrides used when the proxy adds `context_management`. These values take precedence over the fallback threshold from `resolveResponsesCompactThreshold` (`max_prompt_tokens * ratio`, or the default fallback). Defaults set `gpt-5.4` and `gpt-5.5` to `217600` (`272000 * 0.8`). Models not listed continue to use the normal fallback logic.\n- **modelReasoningEfforts:** Per-model fallback reasoning effort for `/v1/messages` requests. It is used only when the request does not provide `output_config.effort`.\n  - **Priority:** request `output_config.effort` > `modelReasoningEfforts[model]` > built-in default (`xhigh` for GPT-5.3+ models, otherwise `high`).\n  - **Forwarding:** the resolved value remains `output_config.effort` for the Copilot native Messages API and becomes `reasoning.effort` when translated to the Responses API.\n  - **Configuration values:** `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`.\n- **useMessagesApi:** When `true`, Claude-family models that support Copilot's native `/v1/messages` endpoint will use the Messages API; otherwise they fall back to `/chat/completions`. Set to `false` to disable Messages API routing and always use `/chat/completions`. Defaults to `true`.\n- **useResponsesApiWebSocket:** When `true`, Responses API requests use Copilot's websocket transport for models that advertise `ws:/responses`; models that only advertise `/responses` continue to use HTTP. Set to `false` to disable websocket routing and use HTTP `/responses` whenever the selected model supports it. Defaults to `true`. If the Responses API WebSocket gets closed, it is usually caused by your own network. If you are using a VPN, try switching to a different node.\n- **useResponsesApiWebSearch:** When `true`, the server keeps Responses API tools with `type: \"web_search\"` and forwards them upstream. Set to `false` to strip those tools from `/responses` payloads. Defaults to `true`.\n- **messageApiWebSearchModel:** Global fallback model used when a top-level Copilot `/v1/messages` request contains only the server-side `web_search` tool. Defaults to `gpt-5-mini`. If the value is a `provider/model` alias, the request is routed into that provider's Messages API path with the provider prefix stripped. For Copilot GPT models, web search runs through `/responses`. Mixed `web_search` plus custom tools are not supported and the server-side `web_search` tool is stripped.\n- **claudeAutoModel:** Model used for Claude Code background security-monitor requests on `/v1/messages` and provider message routes. A request is treated as a security-monitor request when it carries no tools, sets `stop_sequences` to `[\"</block>\"]`, and contains a system text block starting with `You are a security monitor for autonomous AI coding agents.`; its model is then replaced with this value. For top-level requests, a `provider/model` alias is forwarded into that provider's Messages API; provider routes keep their current provider and use this configured value directly. Defaults to empty (disabled).\n- **claudeTokenMultiplier:** Multiplier applied to the fallback GPT-tokenizer estimate for Claude `/v1/messages/count_tokens` requests. Defaults to `1.15`. Increase it if your client is still compacting too late. This setting is only used when the proxy is estimating Claude tokens locally; if `anthropicApiKey` is configured and Anthropic token counting succeeds, the exact Anthropic count is returned instead.\n- **anthropicApiKey:** Anthropic API key used to forward Claude `/v1/messages/count_tokens` requests to Anthropic's real token counting endpoint, which returns exact counts instead of GPT tokenizer estimates. Can also be set via the `ANTHROPIC_API_KEY` environment variable. If not set, or if the upstream call fails, token counting falls back to local GPT tokenizer estimation controlled by `claudeTokenMultiplier`.\n\nEdit this file to customize prompts or swap in your own fast model. Restart the server (or rerun the command) after changes so the cached config is refreshed.\n\n## API Authentication\n\n- **Protected non-admin routes:** All routes except `/`, `/usage-viewer`, and `/usage-viewer/` require authentication when `auth.apiKeys` is configured and non-empty.\n- **Admin routes:** All `/admin/*` routes require `auth.adminApiKey`. If it is missing, the server generates one at startup and persists it to `config.json` before serving requests.\n- **Allowed auth headers:**\n  - `x-api-key: <your_key>`\n  - `Authorization: Bearer <your_key>`\n- **CORS preflight:** `OPTIONS` requests are always allowed.\n- **When no regular keys are configured:** Non-admin routes continue to allow requests. This does not apply to `/admin/*`, which only accepts `auth.adminApiKey`.\n\nExample request for a regular protected route:\n\n```sh\ncurl http://localhost:4141/v1/models \\\n  -H \"x-api-key: your_api_key\"\n```\n\nExample request for an admin route:\n\n```sh\ncurl http://localhost:4141/admin/config/model-mappings \\\n  -H \"x-api-key: your_admin_api_key\"\n```\n\n## API Endpoints\n\nThe server exposes several OpenAI- and Anthropic-compatible endpoints. Requests can target GitHub Copilot, the built-in `codex` provider, or configured providers depending on the selected model and `provider/model` alias.\n\n### OpenAI Compatible Endpoints\n\nThese endpoints mimic the OpenAI API structure.\n\n| Endpoint                    | Method | Description                                                      |\n| --------------------------- | ------ | ---------------------------------------------------------------- |\n| `POST /v1/responses`        | `POST` | OpenAI Most advanced interface for generating model responses. Supports `provider/model` aliases for `openai-responses` providers. |\n| `POST /v1/chat/completions` | `POST` | Creates a model response for the given chat conversation. Supports `provider/model` aliases for `openai-compatible` providers and can be used without Copilot when the target provider is configured. |\n| `GET /v1/models`            | `GET`  | Lists Copilot models plus enabled provider models using `provider/model-id` IDs. Requests from Codex clients (`User-Agent` beginning with `codex`) are forwarded to the Codex Models upstream. |\n| `POST /v1/embeddings`       | `POST` | Creates an embedding vector representing the input text.         |\n\n### Codex Backend Proxy Endpoints\n\nThese endpoints require an active Codex login. Each endpoint is available both without a version prefix and under `/v1`.\n\n| Endpoint | Method | Description |\n| --- | --- | --- |\n| `POST /alpha/search`<br>`POST /v1/alpha/search` | `POST` | Transparently forwards the JSON body and query parameters to the Codex Alpha Search upstream. |\n| `POST /images/generations`<br>`POST /v1/images/generations` | `POST` | Forwards a JSON image generation request to the Codex Images upstream. When the request omits `Content-Type`, the gateway defaults it to `application/json`. |\n| `POST /images/edits`<br>`POST /v1/images/edits` | `POST` | Forwards an image edit request to the Codex Images upstream. Send this request as `multipart/form-data` and let the HTTP client generate the `boundary`; the gateway preserves the incoming content type and streams the upload body. |\n\nFor every endpoint above, the gateway replaces client authorization and account headers with the active Codex login, preserves query parameters and compatible request headers, and returns the upstream status, headers, and body.\n\n### Anthropic Compatible Endpoints\n\nThese endpoints are designed to be compatible with the Anthropic Messages API. Provider-scoped models, Responses, alpha-search, and images routes accept both unversioned and `/v1` paths; Messages routes remain under `/v1`.\n\n| Endpoint                         | Method | Description                                                  |\n| -------------------------------- | ------ | ------------------------------------------------------------ |\n| `POST /v1/messages`              | `POST` | Creates a model response for a given conversation. Supports `provider/model` aliases for configured providers, including translation through `openai-compatible` providers. |\n| `POST /v1/messages/count_tokens` | `POST` | Calculates the number of tokens for a given set of messages. Supports `provider/model` aliases for configured providers. |\n| `POST /:provider/v1/messages`       | `POST` | Proxies Anthropic Messages requests to the configured Anthropic provider, translates them through an OpenAI-compatible provider, or translates them through an OpenAI Responses provider. |\n| `GET /:provider/models`<br>`GET /:provider/v1/models` | `GET` | Proxies model listing requests to the configured provider. For `codex`, returns the built-in catalog by default; Codex clients (`User-Agent` starting with `codex`) are forwarded to the Codex Models upstream. |\n| `POST /:provider/v1/messages/count_tokens` | `POST` | Calculates tokens locally for provider route requests. |\n| `POST /:provider/responses`<br>`POST /:provider/v1/responses` | `POST` | Proxies OpenAI Responses requests to a configured `openai-responses` provider (including `codex`). |\n| `POST /:provider/alpha/search`<br>`POST /:provider/v1/alpha/search` | `POST` | Proxies alpha-search requests. For `codex`, forwards to the Codex Alpha Search upstream; for other providers, forwards to `{baseUrl}/v1/alpha/search`. |\n| `POST /:provider/images/generations`<br>`POST /:provider/v1/images/generations` | `POST` | Proxies image generation. For `codex`, uses the Codex Images upstream; for other providers, forwards to `{baseUrl}/v1/images/generations` (15-minute timeout). |\n| `POST /:provider/images/edits`<br>`POST /:provider/v1/images/edits` | `POST` | Proxies image edits. For `codex`, uses the Codex Images upstream; for other providers, forwards multipart/streamed bodies to `{baseUrl}/v1/images/edits` (15-minute timeout). |\n\n### Usage Monitoring Endpoints\n\nNew endpoints for monitoring your Copilot usage and quotas.\n\n| Endpoint     | Method | Description                                                  |\n| ------------ | ------ | ------------------------------------------------------------ |\n| `GET /usage` | `GET`  | Get detailed Copilot usage statistics and quota information. |\n| `GET /token` | `GET`  | Get the current Copilot token being used by the API.         |\n\n### Admin / Configuration Endpoints\n\nThese endpoints are reserved for local administrative actions and only accept `auth.adminApiKey`.\n\n| Endpoint                              | Method | Description                                                                 |\n| ------------------------------------- | ------ | --------------------------------------------------------------------------- |\n| `GET /admin/config/model-mappings`    | `GET`  | Returns the current `config.json` path and the active `modelMappings` map.  |\n| `POST /admin/config/model-mappings`   | `POST` | Updates only the `modelMappings` field in `config.json` and returns it back. |\n\n## Example Usage\n\nCommon `npx` commands:\n\n```sh\n# Start the gateway\nnpx @jeffreycao/copilot-api@latest start\n\n# Start on a custom port with verbose logging\nnpx @jeffreycao/copilot-api@latest start --port 8080 --verbose\n\n# Run the auth flow\nnpx @jeffreycao/copilot-api@latest auth login\n\n# Configure a third-party provider, then run without GitHub Copilot\nnpx @jeffreycao/copilot-api@latest auth login --provider dashscope\nnpx @jeffreycao/copilot-api@latest start\n\n# Print debug information as JSON\nnpx @jeffreycao/copilot-api@latest debug --json\n\n# Run the published CLI with Bun instead of Node.js\nbunx --bun @jeffreycao/copilot-api@latest start\n```\n\nOpenAI-compatible provider examples after configuring `dashscope`:\n\n```sh\ncurl http://localhost:4141/v1/chat/completions \\\n  -H \"content-type: application/json\" \\\n  -d '{\"model\":\"dashscope/qwen3.6-plus\",\"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]}'\n\ncurl http://localhost:4141/dashscope/v1/messages \\\n  -H \"content-type: application/json\" \\\n  -d '{\"model\":\"qwen3.6-plus\",\"max_tokens\":1024,\"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]}'\n```\n\n## Usage Tips\n\n### CLAUDE.md or AGENTS.md Recommended Content\n\nTo add these reminders manually, include the following in `CLAUDE.md` for Claude Code, or `AGENTS.md` for opencode/codex:\n\n```\n- Prohibited from directly asking questions to users, MUST use question tool.\n- Once you can confirm that the task is complete, MUST use question tool to make user confirm. The user may respond with feedback if they are not satisfied with the result, which you can use to make improvements and try again, after try again, MUST use question tool to make user confirm again.\n```\n"}}, "README.zh-CN.md": {"f85b0ba46a963386713123a74ce49d0220c29fc4": {"t": 1785746549.0449321, "n": 34109, "h": "a0a88a1e61b27f60", "c": "# Copilot API Proxy\n\n[English](./README.md) | 简体中文\n\n## 重要说明\n\n> [!IMPORTANT]\n> **使用前请先注意以下几点：**\n>\n> 1. **Claude Code 配置：** 与 Claude Code 搭配使用时，请将模型 ID 配置为 `claude-opus-4-8`。示例 claude `settings.json` 见 [通过 `settings.json` 手动配置](#manual-configuration-with-settingsjson)。\n>\n> 2. **内置 `copilot`、`codex` 与第三方 provider：** 执行 `npx @jeffreycao/copilot-api@latest auth`，可选择 `copilot`、`codex`、`deepseek`、`custom` 等 provider。\n>\n> 3. **注意事项：** README 顶部移除的 GitHub Copilot warning 见 [GitHub Copilot 安全提示](./NOTICE.md#github-copilot-security-notice)。\n\n---\n\n## 项目概览\n\n这是一个小型 AI gateway，可以使用 GitHub Copilot、内置 `codex` provider，也可以使用 DashScope 等已配置的第三方 provider。GitHub Copilot 现在是可选能力：如果本地没有 GitHub token，只要至少配置了一个启用中的 provider，服务仍可按 provider-only 模式启动。\n\nAI gateway 会从同一个本地端点暴露 OpenAI / Anthropic 兼容 API，让 [Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview)、OpenCode、Codex 和 OpenAI 兼容客户端可以共用同一个本地服务。\n\n在 GitHub Copilot 路径上，AI gateway 会在可用时优先使用 Copilot 原生的 Anthropic 风格 Messages API，在重工具调用场景下保留更原生的 Claude 行为。\n\n## 功能特性\n\n- **OpenAI 与 Anthropic 双兼容**：通过 `/v1/responses`、`/v1/chat/completions`、`/v1/models`、`/v1/embeddings` 和 `/v1/messages` 对外暴露同一个本地 AI gateway。\n- **Copilot 可选**：有 GitHub 凭据时可以使用 GitHub Copilot，没有 GitHub 凭据时也可以只依赖已配置的 provider 运行。\n- **同一网关接入 Copilot、`codex` 与第三方 provider**：可统一路由 GitHub Copilot、内置 `codex` provider 和配置好的外部 provider。\n- **第三方 provider 可独立启动**：配置 DashScope、DeepSeek、OpenRouter 或自定义 provider 后，不需要 GitHub Copilot 登录即可启动 AI gateway。\n- **OpenAI 兼容 provider 同时支持 chat 和 Messages API**：`openai-compatible` provider 可通过顶层 `/v1/chat/completions` 搭配 `model: \"provider/model\"` 提供 Chat Completions，也可通过 `/v1/messages` 完成 Anthropic Messages 的请求/响应翻译。\n- **面向 Claude 的更原生 Copilot 路由**：优先使用原生 `/v1/messages`，保留 Claude 风格工具流，支持 Anthropic beta 能力、通过 Responses-capable 模型支持 Claude WebSearch，并保留 subagent / session 标记。\n- **Claude Code 与 OpenCode 集成**：兼容 Claude Code 与 OpenCode，也支持通过 `@ai-sdk/anthropic` 直接作为 Anthropic provider 使用。\n- **灵活的认证与部署选项**：支持交互式登录、直接 token、个人 / Business / Enterprise、GitHub Enterprise、opencode OAuth 和自定义数据目录。\n- **多 provider 路由**：可暴露 `/:provider/...` 路由，也可在顶层 API 上使用 `model: \"provider/model\"`。\n\n## 前置要求\n\n- Bun（>= 1.2.x）\n- 如果要通过 `npx` 运行已发布 CLI，需要 Node.js\n- 只有在使用 GitHub Copilot provider 时，才需要已订阅 Copilot 的 GitHub 账号\n- 如果不使用 GitHub Copilot，需要至少一个已配置 provider 的 API key 或 OAuth 登录\n\n## 安装\n\n安装依赖：\n\n```sh\nbun install\n```\n\n直接从源码启动服务：\n\n```sh\nbun run start start\n```\n\n## 从源码运行\n\n本项目可以通过多种方式从源码运行：\n\n### 开发模式\n\n```sh\nbun run dev start\n```\n\n### 生产模式\n\n```sh\nbun run start start\n```\n\n## 通过 npx 使用\n\n你可以直接用 npx 运行本项目：\n\n> [!IMPORTANT]\n> 通过 `npx` 运行时，token usage 存储会使用 Node 内置的 `node:sqlite` 模块。该能力会在 Node.js >= 22.13.0 时启用；Node.js < 22.13.0 时 CLI 仍可启动，但会禁用 token usage 存储。\n>\n> 如果不升级 Node.js 但仍需要 token usage 存储，可以改用 Bun 运行已发布 CLI：`bunx --bun @jeffreycao/copilot-api@latest start`。\n\n```sh\nnpx @jeffreycao/copilot-api@latest start\n```\n\n带参数示例：\n\n```sh\nnpx @jeffreycao/copilot-api@latest start --port 8080\n```\n\n如果只想做认证或 provider 配置：\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth\n```\n\n如果要不依赖 GitHub Copilot 运行，先配置至少一个 provider，然后正常启动服务：\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth login --provider dashscope\nnpx @jeffreycao/copilot-api@latest start\n```\n\n## 配合 Docker 使用\n\n构建镜像：\n\n```sh\ndocker build -t copilot-api .\n```\n\n通过 bind mount 运行容器，让认证数据在重启后保留：\n\n```sh\nmkdir -p ./copilot-data\ndocker run -p 4141:4141 -v $(pwd)/copilot-data:/root/.local/share/copilot-api copilot-api\n```\n\n这会把宿主机上的 `./copilot-data` 映射到容器内的 `/root/.local/share/copilot-api`，用于持久化 GitHub 认证数据、provider 配置和其他 gateway 状态。\n\n也可以直接通过环境变量传入 GitHub token：\n\n```sh\ndocker run -p 4141:4141 -e GH_TOKEN=your_github_token_here copilot-api\n```\n\n## Electron 桌面应用\n\n如果你更喜欢图形界面，仓库里还提供了位于 `desktop/` 的 Electron 桌面应用。它支持 GitHub Copilot 登录、OpenAI Codex OAuth，以及 DeepSeek、DashScope、OpenRouter 或自定义 provider 的 API Key 配置。授权或配置 provider 后，可以一键启动或停止本地代理，并在界面里直接查看本地端点、鉴权 Header、可用模型、额度和日志。\n\n设置页还可以配置 `OAuth App`、`API Home`、`Enterprise URL`、详细日志以及最小化到托盘。Windows x64（`.exe`）、macOS Apple Silicon（`.dmg`）和 Linux x64（`.AppImage`）安装包发布在 GitHub Releases：\n\nhttps://github.com/caozhiyuan/copilot-api/releases\n\nLinux 用户需要先为下载的 AppImage 添加执行权限：\n\n```sh\nchmod +x Copilot-API-*-linux-x86_64.AppImage\n./Copilot-API-*-linux-x86_64.AppImage\n```\n\n下载对应平台的安装包后，在应用内授权或配置 provider，选择端口并启动服务，再把你的客户端指向应用里显示的本地端点即可。发布版桌面应用使用随包内置的 Electron 运行时，正常使用不需要额外安装 Node.js；token usage 历史记录会在该内置运行时支持 SQLite 时启用。\n\n桌面应用里的高级配置页会通过 `GET/POST /admin/config/model-mappings` 读写这份共享的模型映射。同一份映射会统一作用于 `POST /v1/messages`、`POST /v1/messages/count_tokens`、`POST /v1/responses` 和 `POST /v1/chat/completions`，不再按接口区分。它使用的是 `auth.adminApiKey`，不是普通的 `auth.apiKeys`；应用会在服务启动并自动生成该 key 后，直接从 `config.json` 读取它来发起请求。\n\n### 桌面应用截图\n\n下面展示了桌面应用中的首页、Token 用量统计页面：\n\n<p align=\"center\">\n  <img src=\"./docs/screenshots/desktop-dashboard.png\" alt=\"Copilot API 桌面应用首页\" width=\"49%\" />\n  <img src=\"./docs/screenshots/desktop-token-usage.png\" alt=\"Copilot API 桌面应用 Token 用量页\" width=\"49%\" />\n</p>\n\n## 与 Claude Code 一起使用\n\n这个 AI gateway 可以为 [Claude Code](https://docs.anthropic.com/en/claude-code) 提供后端能力。Claude Code 是 Anthropic 提供的实验性面向开发者的对话式 AI 助手。\n\n有两种方式可以把 Claude Code 配置为使用这个 AI gateway：\n\n### 通过 `--claude-code` 标志进行交互式配置\n\n执行带 `--claude-code` 的 `start` 命令开始：\n\n```sh\nnpx @jeffreycao/copilot-api@latest start --claude-code\n```\n\n你不再需要手动选择模型。Gateway 会自动检测每个 Claude Code 尺寸档位对应的最新可用模型——opus 映射到最新的 Opus 模型，sonnet 映射到最新的 Sonnet 模型，haiku 映射到最新的 Haiku 模型——并生成相应设置 `ANTHROPIC_DEFAULT_OPUS_MODEL`、`ANTHROPIC_DEFAULT_SONNET_MODEL` 和 `ANTHROPIC_DEFAULT_HAIKU_MODEL` 的命令。若某个档位没有匹配的可用模型，则会被省略。该命令会被复制到剪贴板，并设置 Claude Code 使用这个 AI gateway 所需的环境变量。\n\n在新的终端中粘贴并执行这条命令，即可启动 Claude Code。\n\n<a id=\"manual-configuration-with-settingsjson\"></a>\n\n### 通过 `settings.json` 手动配置\n\n另一种方式是在项目根目录中创建 `.claude/settings.json` 文件，并写入 Claude Code 所需的环境变量。这样你就不需要每次都运行交互式配置了。\n\n下面是一个 `.claude/settings.json` 示例：\n\n```json\n{\n  \"env\": {\n    \"ANTHROPIC_BASE_URL\": \"http://localhost:4141\",\n    \"ANTHROPIC_AUTH_TOKEN\": \"dummy\",\n    \"ANTHROPIC_MODEL\": \"gpt-5.6-sol[1m]\",\n    \"ANTHROPIC_DEFAULT_OPUS_MODEL\": \"gpt-5.6-sol[1m]\",\n    \"ANTHROPIC_DEFAULT_SONNET_MODEL\": \"gpt-5.6-sol[1m]\",\n    \"ANTHROPIC_DEFAULT_HAIKU_MODEL\": \"gpt-5.6-luna[1m]\",\n    \"CLAUDE_CODE_AUTO_COMPACT_WINDOW\": \"272000\",\n    \"CLAUDE_CODE_USE_VERTEX\": \"0\",\n    \"CLAUDE_CODE_USE_BEDROCK\": \"0\",\n    \"DISABLE_NON_ESSENTIAL_MODEL_CALLS\": \"1\",\n    \"CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC\": \"1\",\n    \"CLAUDE_CODE_ATTRIBUTION_HEADER\": \"0\",\n    \"CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION\": \"false\",\n    \"CLAUDE_CODE_DISABLE_TERMINAL_TITLE\": \"true\",\n    \"CLAUDE_CODE_ENABLE_AWAY_SUMMARY\": \"0\"\n  },\n  \"alwaysThinkingEnabled\": true,\n  \"effortLevel\": \"xhigh\",\n  \"showThinkingSummaries\": true\n}\n```\n\n- 请根据需要替换 `ANTHROPIC_MODEL`、`ANTHROPIC_DEFAULT_OPUS_MODEL`、`ANTHROPIC_DEFAULT_SONNET_MODEL` 和 `ANTHROPIC_DEFAULT_HAIKU_MODEL`。配置完成后，请安装 claude code 插件，见 [插件集成](#plugin-integrations)。\n- 如果你使用的是 codex provider，建议**不要**将模型名配置成 `codex/xxx` 格式（如 `codex/gpt-5.6-sol`）。Claude Code 会针对 `codex/` 前缀做降智行为——例如每次请求时移除所有之前返回的思考块（thinking blocks）。请使用纯模型名（如 `gpt-5.6-sol`），并在 `config.json` 中配置 `modelMappings` 将其映射回 codex provider：\n  ```json\n  \"modelMappings\": {\n    \"gpt-5.6-sol\": \"codex/gpt-5.6-sol\",\n    \"gpt-5.6-terra\": \"codex/gpt-5.6-terra\",\n    \"gpt-5.6-luna\": \"codex/gpt-5.6-luna\"\n  },\n  ```\n- 将 `CLAUDE_CODE_ATTRIBUTION_HEADER` 设为 `0` 可以阻止 Claude Code 在 system prompt 中附加计费和版本信息，从而避免 prompt cache 失效。\n- 关闭 `CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION` 和 `CLAUDE_CODE_ENABLE_AWAY_SUMMARY` 可以避免不必要地消耗额度。\n- Claude Code WebSearch 已支持纯搜索请求。Copilot 路径请保持全局 `messageApiWebSearchModel` 指向 Responses-capable GPT 模型或 `provider/model` 别名；provider 路由请使用原生 Anthropic provider 或 `openai-responses` provider。只有在你明确想禁止这类流量时，才需要把 `WebSearch` 加到 `permissions.deny`。\n- 如果使用的不是 Claude 模型，请不要启用 `ENABLE_TOOL_SEARCH`。如果使用的是 Claude 模型，则可以启用 `ENABLE_TOOL_SEARCH`。当前 Claude Code 使用的是客户端 tool search 模式，在该模式下每次加载 defer tools 都需要额外请求一次。\n- `CLAUDE_CODE_AUTO_COMPACT_WINDOW`：设置用于自动压缩计算的上下文容量（以 token 为单位）。默认使用模型自身的上下文窗口：标准模型为 200K，扩展上下文模型为 1M。使用 1M 上下文模型（如 `claude-opus-4-6[1m]`）时，可设置一个较低的值（如 `500000`）将窗口视为 500K 用于压缩计算。该值受限于模型的实际上下文窗口上限。`CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` 会基于此值的百分比生效。设置此变量可将压缩阈值与状态栏的 `used_percentage` 解耦（后者始终使用模型的完整上下文窗口）。\n\n更多选项见：[Claude Code settings](https://docs.anthropic.com/en/docs/claude-code/settings#environment-variables)\n\n也可以参考 IDE 集成说明：[Add Claude Code to your IDE](https://docs.anthropic.com/en/docs/claude-code/ide-integrations)\n\n## 与 OpenCode 一起使用\n\nOpenCode 已经有直接的 GitHub Copilot provider。本节适用于你希望让 OpenCode 通过 `@ai-sdk/anthropic` 指向这个 AI gateway，并复用本 README 前面提到的 agent 行为时。\n\n### 最小配置\n\n使用 OpenCode OAuth app 启动 AI gateway：\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth --oauth-app=opencode\nnpx @jeffreycao/copilot-api@latest start\n```\n\n然后让 OpenCode 通过 `@ai-sdk/anthropic` 指向这个 AI gateway。\n\n示例 `~/.config/opencode/opencode.json`：\n\n```json\n{\n  \"$schema\": \"https://opencode.ai/config.json\",\n  \"provider\": {\n    \"local\": {\n      \"npm\": \"@ai-sdk/anthropic\",\n      \"name\": \"My Local\",\n      \"options\": {\n        \"baseURL\": \"http://localhost:4141/v1\",\n        \"apiKey\": \"dummy\"\n      },\n      \"models\": {\n        \"gpt-5.4\": {\n          \"name\": \"gpt-5.4\",\n          \"modalities\": {\n            \"input\": [\"text\", \"image\"],\n            \"output\": [\"text\"]\n          },\n          \"limit\": {\n            \"context\": 400000,\n            \"input\": 272000,\n            \"output\": 128000\n          }\n        },\n        \"claude-sonnet-4.6\": {\n          \"id\": \"claude-sonnet-4.6\",\n          \"name\": \"claude-sonnet-4.6\",\n          \"modalities\": {\n            \"input\": [\"text\", \"image\"],\n            \"output\": [\"text\"]\n          },\n          \"limit\": {\n            \"context\": 200000,\n            \"output\": 32000\n          },\n          \"options\": {\n            \"thinking\": {\n              \"type\": \"adaptive\"\n            },\n            \"effort\": \"max\"\n          }\n        }\n      }\n    }\n  }\n}\n```\n\n这些字段的重要性：\n\n- `npm: \"@ai-sdk/anthropic\"` 是关键。OpenCode 会以 Anthropic Messages 语义与这个 AI gateway 通信，而不是把一切扁平化为 OpenAI Chat Completions。\n- `options.baseURL` 应设为 `http://localhost:4141/v1`；Anthropic SDK 会自动补上 `/messages`、`/models` 和 `/messages/count_tokens`。\n- 如果你在此代理中启用了 `auth.apiKeys`，请把 `dummy` 替换为真实 key；否则任意占位值都可以。\n\n## 与 Codex 一起使用\n\n这个 AI gateway 也可以为 Codex 提供后端能力。\n\n### Codex `config.toml` 参考配置\n\n把以下 `[model_providers.copilot_api]` 段加入你的 Codex `~/.codex/config.toml`：\n\n```toml\nmodel_provider = \"copilot_api\"\nmodel_reasoning_summary = \"auto\"\nmodel_context_window = 272000\nmodel_auto_compact_token_limit = 244800\n\n[model_providers.copilot_api]\nname = \"OpenAI\"\nbase_url = \"http://localhost:4141\"\nenv_key = \"GITHUB_COPILOT_API_KEY\"\nrequires_openai_auth = true\nsupports_websockets = false\nwire_api = \"responses\"\nrequest_max_retries = 3\nstream_max_retries = 1\nstream_idle_timeout_ms = 300000\n\n[features]\nremote_compaction_v2 = true\n\n[analytics]\nenabled = false\n```\n\n> [!NOTE]\n> 此配置仅限于 Codex 与 GitHub Copilot provider。`name` 一定要配置为 `\"OpenAI\"`。它可以缓解 Codex local compact 不命中缓存的问题。\n> 如果使用 codex provider，建议将 `base_url` 配置为 `\"http://localhost:4141/codex\"`。\n\n## GPT Tool Search\n\n对于 `gpt-5.4+` 这类 GPT Responses 模型，这个 AI gateway 可以通过一个很小的 MCP bridge 暴露 Responses `tool_search`。Claude Code 和 opencode 都可以使用同一个 bridge，前提是客户端会加载 MCP server，并且 Anthropic Messages 流量会经过这个 AI gateway。\n\nGPT 模型不要设置 Claude Code 原生的 `ENABLE_TOOL_SEARCH`。这个开关启用的是 Claude Code 自己的客户端 tool search 模式，可能导致 deferred 工具定义不再转发给 AI gateway。这个 AI gateway 需要完整的工具定义，这样才能只保留那一小组常驻加载工具，其余工具统一转换为 Responses deferred namespace。\n\n如果你安装了 `tool-search@copilot-api-marketplace`，Claude Code 会自动带上这个 MCP bridge，可以跳过下面这段 Claude Code MCP 手动配置。\n\n请把 tool search bridge 加到 Claude Code 使用的 MCP 配置中：\n\n```json\n{\n  \"mcpServers\": {\n    \"tool_search\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@jeffreycao/copilot-api@latest\", \"mcp\"]\n    }\n  }\n}\n```\n\n请把 tool search bridge 加到 opencode 使用的 MCP 配置中：\n\n```json\n{\n  \"mcp\": {\n    \"tool_search\": {\n      \"type\": \"local\",\n      \"command\": [\"npx\", \"-y\", \"@jeffreycao/copilot-api@latest\", \"mcp\"]\n    }\n  }\n}\n```\n\n本地开发时可以将命令换成 `bun`，参数换成 `[\"run\", \"./src/main.ts\", \"mcp\"]`。\n\nAI gateway 内部现在会把 OpenAI Responses `tool_search` 配置成 client-executed 模式。deferred tools 仍然会作为可搜索 namespace 暴露给模型，但会明确要求模型直接返回下一步要加载的精确工具名列表。\n\n该 bridge 使用直接工具选择，不做 query 搜索。工具入参是 `names`，值为逗号分隔的精确 deferred 工具名，例如 `TaskList,TaskGet,mcp__fetch__fetch`。\n\n<a id=\"plugin-integrations\"></a>\n\n## 插件集成\n\n本项目为 Claude Code 和 opencode 提供了插件集成。\n\n#### Claude Code 插件集成（基于 marketplace）\n\nClaude Code 集成现在拆分为两个插件：\n\n- `agent-inject` 会在 `SubagentStart` 时注入 `__SUBAGENT_MARKER__...`，以便 AI gateway 推导 `x-initiator: agent`。\n- `tool-search` 会注册用于 GPT Responses deferred tool loading 的 `tool_search` MCP bridge。\n\n- 本仓库中的 marketplace catalog：`.claude-plugin/marketplace.json`\n- 本仓库中的插件源码：`plugin/claude/agent-inject`、`plugin/claude/tool-search`\n\n远程添加 marketplace：\n\n```sh\n/plugin marketplace add https://github.com/caozhiyuan/copilot-api.git\n```\n\n从 marketplace 安装插件：\n\n```sh\n/plugin install agent-inject@copilot-api-marketplace\n/plugin install tool-search@copilot-api-marketplace\n```\n\n安装后，`agent-inject` 会在 `SubagentStart` 时注入 `__SUBAGENT_MARKER__...`，AI gateway 会利用它推导 `x-initiator: agent`。\n\n`agent-inject` 还会注册一个 `UserPromptSubmit` hook，并返回 `{\"continue\": true}`；同时它也可以通过环境变量注入 `SessionStart` reminder 规则：\n\n- `CLAUDE_PLUGIN_ENABLE_QUESTION_RULES=1` 会自动为 Claude Code 启用两条关于使用 `question` 工具的提醒。你也可以把同样的提醒手动写进 `CLAUDE.md`；见 [CLAUDE.md 或 AGENTS.md 推荐内容](#claudemd-or-agentsmd-recommended-content)。\n- `CLAUDE_PLUGIN_ENABLE_NO_BACKGROUND_AGENTS_RULE=1` 会启用关于避免在 agent hooks 中使用 `run_in_background: true` 的提醒。\n\n`tool-search` 插件内置了 [GPT Tool Search](#gpt-tool-search) 一节描述的同一个 MCP bridge，因此安装该插件后，Claude Code 用户无需再手动配置 `tool_search` server。\n\n#### Opencode 插件\n\nsubagent 标记生成器被打包为一个 opencode 插件，位于 `plugin/opencode/subagent-marker.js`。\n\n**安装方式：**\n\n将插件文件复制到你的 opencode 插件目录：\n\n```sh\n# 克隆或下载本仓库后复制该插件\ncp plugin/opencode/subagent-marker.js ~/.config/opencode/plugins/\n```\n\n或者手动在 `~/.config/opencode/plugins/subagent-marker.js` 创建该文件，并填入插件内容。\n\n**功能：**\n\n- 跟踪 subagent 创建的子会话\n- 自动在 subagent 聊天消息前添加 marker system reminder（`__SUBAGENT_MARKER__...`）\n- 设置 `x-session-id` 请求头以跟踪会话\n- 让这个 AI gateway 能够把来自 subagent 的请求识别为 `x-initiator: agent`\n\n该插件会挂接到 `session.created`、`session.deleted`、`chat.message` 和 `chat.headers` 事件上，以无缝提供 subagent marker 能力。\n\n## 使用量查看器\n\n服务启动后，控制台会输出一个 Copilot 使用量看板 URL。这个看板是一个用于监控 API 用量的 Web 界面。\n\n1. 启动服务。例如使用 npx：\n   ```sh\n   npx @jeffreycao/copilot-api@latest start\n   ```\n2. 服务会输出一个 usage viewer 的 URL。将它复制到浏览器中打开，形式大致如下：\n   `http://localhost:4141/usage-viewer?endpoint=http://localhost:4141/usage`\n   - 如果你在 Windows 上使用 `start.bat` 脚本，这个页面会自动打开。\n\n看板提供了更易读的 Copilot 用量视图：\n\n> token usage 历史记录需要 Bun 或 Node.js >= 22.13.0。Node.js < 22.13.0 时服务会正常运行，但 token usage 存储会被禁用。\n\n- **API Endpoint URL**：通过 URL 查询参数指定 API endpoints，默认指向本地服务。支持手动切换为其他兼容 endpoints。\n- **x-api-key 认证**：如果启用了 API Key 认证，可填入 `x-api-key` 请求头。密钥会持久化保存在浏览器本地存储中。\n- **Period 选择器**：支持 Day / Week / Month 三种时间范围，切换时 URL 参数会自动同步，方便收藏和分享。\n- **Fetch Data**：点击 \"Refresh\" 按钮加载或刷新使用数据。页面加载时也会自动拉取数据。\n- **Copilot Quotas 额度**：通过进度条展示 Chat、Completions 等不同服务的额度使用情况，悬停可查看已用/剩余详情。\n- **Token Usage 指标卡片**：汇总当前周期的 Total、Input、Output、Cache Read、Cache Write、Requests 和预估费用。\n- **趋势图（Week / Month）**：提供按模型和指标筛选的折线趋势图，点击数据点可查看单日用量明细。\n- **Model Breakdown 表格**：按模型维度列出周期内的请求数、输入/输出/缓存 token 和预计费用。\n- **Request Events 分页列表**：按时间排序的请求事件记录，支持分页浏览，含时间戳、模型、请求 ID 和 token 用量。\n- **Detailed Information**：展示 API 返回的完整 JSON 响应，便于深入分析所有可用统计数据。\n- **URL-based Configuration**：也可通过 `endpoint` 和 `period` 查询参数直接指定 API 端点与时间范围。例如：\n  `http://localhost:4141/usage-viewer?endpoint=http://your-api-server/usage&period=week`\n\n### Usage Viewer 截图\n\n<p align=\"center\">\n  <img src=\"./docs/screenshots/usage-viewer.png\" alt=\"Copilot API Usage Viewer 页面\" width=\"900\" />\n</p>\n\n## 命令结构\n\nCopilot API 现在使用子命令结构，主要命令包括：\n\n- `start`：启动 AI gateway 服务。如果已有 GitHub token，则启用 Copilot 路径；如果没有 GitHub token，但存在至少一个启用中的 provider，则按 provider-only 模式启动；如果两者都没有，会引导你配置 provider。\n- `auth`：仅执行 provider 登录或配置流程，不启动服务。可用于 GitHub Copilot 登录、Codex OAuth，或第三方 provider API key 配置。\n- `debug`：显示诊断信息，包括版本、运行时详情、文件路径以及认证状态，便于排障与支持。\n\n## 命令行选项\n\n### 全局选项\n\n以下选项可用于任意子命令。若在子命令之前传入，请使用 `--key=value` 形式：\n\n| 选项 | 说明 | 默认值 | 别名 |\n| --- | --- | --- | --- |\n| --api-home | API home 目录路径（设置 `COPILOT_API_HOME`） | 无 | 无 |\n| --oauth-app | OAuth app 标识符（设置 `COPILOT_API_OAUTH_APP`） | 无 | 无 |\n| --enterprise-url | GitHub Enterprise URL（设置 `COPILOT_API_ENTERPRISE_URL`） | 无 | 无 |\n\n### Start 命令选项\n\n以下是 `start` 命令可用的命令行选项：\n\n| 选项 | 说明 | 默认值 | 别名 |\n| --- | --- | --- | --- |\n| --port | 监听端口 | 4141 | -p |\n| --verbose | 启用详细日志 | false | -v |\n| --github-token | 直接提供 GitHub token（必须通过 `auth` 子命令生成） | 无 | -g |\n| --claude-code | 生成一个使用 Copilot API 配置启动 Claude Code 的命令 | false | -c |\n| --show-token | 在获取和刷新时显示 GitHub 与 Copilot token | false | 无 |\n| --proxy-env | 从环境变量初始化代理 | false | 无 |\n\n### Auth 命令选项\n\n| 选项 | 说明 | 默认值 | 别名 |\n| --- | --- | --- | --- |\n| --provider | 要登录或配置的 provider（`copilot`、`codex`、`opencode-go`、`deepseek`、`dashscope`、`openrouter` 或 `custom`） | 交互选择 | 无 |\n| --verbose | 启用详细日志 | false | -v |\n| --show-token | 认证时显示 GitHub token | false | 无 |\n\n只有在需要启用 GitHub Copilot provider 时，才需要执行 `copilot-api auth login --provider copilot`。使用 `codex` 或第三方 provider-only 模式不要求配置 Copilot。\n\n使用 `copilot-api auth login --provider deepseek`、`--provider dashscope`、`--provider openrouter` 或 `--provider opencode-go` 可以通过 CLI 快速新增或更新这些常用第三方 provider。DeepSeek 会提示输入掩码显示的 `apiKey`、provider `type`（默认 `anthropic`），以及默认 `https://api.deepseek.com/anthropic` 的 `baseUrl`。DashScope 会提示输入掩码显示的 `apiKey`、provider `type`（默认 `openai-compatible`）和预填默认值的 `baseUrl`。OpenRouter 只提示输入掩码显示的 `apiKey` 和预填默认值的 `baseUrl`，并固定写入 `type: \"anthropic\"`。OpenCode Go 只提示输入掩码显示的 `apiKey` 和预填默认值的 `baseUrl`，并固定写入 `type: \"openai-compatible\"`（baseUrl `https://opencode.ai/zen/go`）。配置并启用 provider 后，`copilot-api start` 可在没有 GitHub token 的情况下启动。\n\n使用 `copilot-api auth login --provider custom` 可以通过 CLI 新增或更新其他第三方 provider。命令会依次提示输入 provider name、项目支持的 type（`anthropic`、`openai-compatible` 或 `openai-responses`）、`baseUrl`、掩码显示的 `apiKey` 和 `authType`；`authType` 可保持 type 默认值，也可选择 `x-api-key` / `authorization`。\n\n### Debug 命令选项\n\n| 选项 | 说明 | 默认值 | 别名 |\n| --- | --- | --- | --- |\n| --json | 以 JSON 输出调试信息 | false | 无 |\n\n<a id=\"configuration-configjson\"></a>\n\n## 配置（config.json）\n\n- **位置：** Linux/macOS 为 `~/.local/share/copilot-api/config.json`，Windows 为 `%USERPROFILE%\\.local\\share\\copilot-api\\config.json`。\n- **默认结构：**\n  ```json\n  {\n    \"auth\": {\n      \"apiKeys\": [],\n      \"adminApiKey\": \"<startup 自动生成>\"\n    },\n    \"providers\": {},\n    \"modelMappings\": {},\n    \"extraPrompts\": {\n      \"gpt-5-mini\": \"<built-in exploration prompt>\"\n    },\n    \"smallModel\": \"gpt-5-mini\",\n    \"contextManagement\": {\n      \"messages\": true,\n      \"responses\": false\n    },\n    \"modelResponsesApiCompactThresholds\": {\n      \"gpt-5.4\": 217600,\n      \"gpt-5.5\": 217600\n    },\n    \"modelReasoningEfforts\": {\n      \"gpt-5-mini\": \"low\"\n    },\n    \"useMessagesApi\": true,\n    \"useResponsesApiWebSocket\": true,\n    \"useResponsesApiWebSearch\": true,\n    \"messageApiWebSearchModel\": \"gpt-5-mini\"\n  }\n  ```\n- **auth.apiKeys：** 用于普通非 admin 路由的 API key。支持多个 key 轮换使用。请求可通过 `x-api-key: <key>` 或 `Authorization: Bearer <key>` 进行认证。若为空或省略，则普通路由的认证会被禁用。\n- **auth.adminApiKey：** 仅用于 `/admin/*` 路由的单个 admin key。若未配置，服务会在启动时自动生成一个随机 key，并回写到 `config.json`。它同样使用 `x-api-key` 或 `Authorization: Bearer` 这两种头，但普通 `auth.apiKeys` 不能访问 `/admin/*`。\n- **modelMappings：** 用于顶层 `POST /v1/messages`、`POST /v1/messages/count_tokens`、`POST /v1/responses` 和 `POST /v1/chat/completions` 请求的精确 `sourceModel -> targetModel` 重写映射，这几类接口共用同一份规则。省略该字段或保留为 `{}` 时，不会做模型重写。`source` 和 `target` 都必须是非空字符串。`target` 可以是普通模型 ID，也可以是 `provider/model` 形式的别名，例如 `dashscope/qwen3.6-plus`；重写发生在 provider alias 解析之前。这些映射不再按接口区分。`GET/POST /admin/config/model-mappings` 管理接口读写的也只有这个字段。\n- **extraPrompts：** `model -> prompt` 的映射。把 Anthropic 风格请求翻译为 Responses API 时，会将其附加到第一条 system prompt 后面。你可以借此为不同模型注入护栏或指引。缺失的默认项会自动补齐，但不会覆盖你自定义的 prompt。对于 GPT-5.3+ 模型（如 `gpt-5.3-codex`、`gpt-5.4`、`gpt-5.5`），未显式配置时会自动使用内置的 commentary prompt。内置 prompt 会启用带阶段感知的 commentary，让模型在工具调用或更深层推理前先发出简短的用户可见进度说明。\n- **providers：** 全局上游 provider 映射。每个 provider key（例如 `dashscope`）都会变成一个路由前缀（`/dashscope/v1/messages`）。支持 `type: \"anthropic\"`、`type: \"openai-compatible\"` 和 `type: \"openai-responses\"`。顶层客户端也可以在 `/v1/messages`、`/v1/messages/count_tokens`、`/v1/responses` 和 `/v1/chat/completions` 中使用 `model: \"dashscope/model-id\"`；AI gateway 会在转发上游前移除 `dashscope/` 前缀。`openai-compatible` provider 同时支持 chat 和 Messages 流程：`/v1/chat/completions` 会直连上游 `/v1/chat/completions`，而 `/v1/messages` 和 `/:provider/v1/messages` 会先翻译为上游 Chat Completions，再把响应翻译回 Anthropic Messages。`GET /v1/models` 会聚合已启用 provider 的模型，并以 `provider/model-id` 形式返回；单个 provider 的原始模型列表仍可使用 `GET /dashscope/v1/models`。\n  - `enabled`：可选，若省略则默认为 `true`。\n  - `baseUrl`：provider API 的基础 URL，不要带结尾的 endpoint。Anthropic provider 不要带 `/v1/messages`；OpenAI 兼容 provider 不要带 `/v1/chat/completions`；OpenAI Responses provider 不要带 `/v1/responses`。\n  - `apiKey`：作为上游凭据值使用；普通 provider 必须配置。\n  - `authType`：可选，控制 `apiKey` 如何发送到上游。普通 provider 支持 `x-api-key` 和 `authorization`。Anthropic provider 默认 `x-api-key`；OpenAI 兼容和 OpenAI Responses provider 默认 `authorization`。当设置为 `authorization` 时，代理会发送 `Authorization: Bearer <apiKey>`。`oauth2` 仅保留给内置 `codex` provider，并由 `auth login --provider codex` 自动写入。\n  - `pricingCurrency`：可选，provider 维度的 token 费用币种，例如 `USD` 或 `CNY`。快捷 provider 默认 DashScope、DeepSeek 为 `CNY`，Codex/OpenRouter 为 `USD`。费用按币种分别汇总，不做汇率换算。\n  - `models`：可选，按模型 ID 配置的映射。每个键为请求中的模型名，值支持：\n    - `temperature`：可选，当请求未指定时使用的默认温度。\n    - `topP`：可选，当请求未指定时使用的默认 `top_p`。\n    - `topK`：可选，当请求未指定时使用的默认 `top_k`。\n    - `extraBody`：可选，按模型合入上游请求体的动态字段；请求体显式同名字段优先。OpenAI 兼容 provider 可用它配置 `enable_thinking`、`preserve_thinking`、`reasoning_effort` 等字段。`thinking_budget` 是 OpenAI 兼容 provider 的特殊覆盖项：配置在 `extraBody` 后，会在 Anthropic `thinking.budget_tokens` 翻译之后强制写入，并覆盖请求派生出的预算值。对于 provider name 为 `dashscope` 或 `baseUrl` 包含 `aliyuncs.com` 的 provider，请求派生的 `thinking_budget`（来自 Anthropic `thinking.budget_tokens`）会转发给上游；其他 OpenAI 兼容 provider 会移除请求派生的 `thinking_budget`，但 `extraBody` 中的 `thinking_budget` 仍然生效。对于 DashScope provider，当 `preserve_thinking` 未在 `extraBody` 或请求体中显式设置时，默认为 `true`。\n    - `pricing`：可选，按模型配置 token 单价，币种使用 provider 的 `pricingCurrency`，单位为每 100 万 tokens。支持 `input`、`output`、`cachedInput`（隐式缓存读）、`explicitCachedInput`（显式缓存读）和 `cacheCreationInput`。如需按输入 token 总量分档，可用带 `maxInputTokens` 的 `tiers`。\n    - `contextCache`：可选，provider name 为 `dashscope` 或 `baseUrl` 包含 `aliyuncs.com` 时默认 `true`，其他 OpenAI 兼容 provider 默认 `false`。用于启用阿里云百炼/DashScope 的显式缓存（explicit context cache），会按其 Context Cache 格式在最多 4 个 content block 上注入 `cache_control: { \"type\": \"ephemeral\" }`。缓存断点策略与 opencode 主链路保持一致：前 2 条 system 消息 + 最后 2 条非 system 消息。标记字符串 content 时会把 `system` / `user` / `assistant` / `tool` 消息转换为 text content part 数组；已有数组 content 则标记最后一个 part。如果模型本身已经支持隐式缓存，或上游不支持该显式缓存扩展字段，可在模型配置中设为 `false`。支持相同显式缓存扩展的非 DashScope provider 可设为 `true`。同时适用于 `/v1/messages` 和 `/v1/chat/completions` 路由。\n    - `supportPdf`：可选，控制该模型是否支持 PDF/document content。默认 `false`，不支持时会把 PDF 转成提示文本；设为 `true` 时会把 PDF/document 转成 OpenAI Chat Completions 的 file part。\n    - `toolContentSupportType`：可选，配置该模型的 tool result content 支持能力，值为 `array`、`image`、`pdf` 的数组。provider 侧未配置时默认只发送 string tool content。若 `supportPdf` 为 `true` 但这里不包含 `pdf`，tool result 里的 file part 会被转成 user role 消息。Copilot 主链路不使用这个 provider 默认，仍按 array + image 且不支持 PDF 的能力处理。\n    - `type`：可选，按模型覆盖 provider 的协议类型。支持 `anthropic`、`openai-compatible` 和 `openai-responses`。设置后，provider 的 `/v1/messages` 路由会使用该模型的 type 替代 provider 级别的 type 进行请求路由、认证头解析和上游端点选择。适用于 OpenCode Go 等上游对不同模型同时支持 OpenAI 兼容和 Anthropic Messages API 的 provider。覆盖 type 时，认证头按覆盖后 type 的默认值解析（Anthropic 默认 `x-api-key`；OpenAI 兼容/Responses 默认 `authorization`）。\n\n  DashScope 模型配置示例：\n  ```json\n  {\n    \"providers\": {\n      \"dashscope\": {\n        \"type\": \"openai-compatible\",\n        \"enabled\": true,\n        \"baseUrl\": \"https://dashscope.aliyuncs.com/compatible-mode\",\n        \"apiKey\": \"sk-your-dashscope-key\",\n        \"pricingCurrency\": \"CNY\",\n        \"models\": {\n          \"qwen3.7-plus\": {\n            \"temperature\": 1,\n            \"topP\": 0.95,\n            \"topK\": 20,\n            \"extraBody\": {\n              \"preserve_thinking\": true\n            }\n          },\n          \"glm-5.1\": {\n            \"temperature\": 0.7,\n            \"topP\": 0.95,\n            \"contextCache\": true,\n            \"pricing\": {\n              \"tiers\": [\n                {\n                  \"maxInputTokens\": 32000,\n                  \"input\": 6,\n                  \"cachedInput\": 1.2,\n                  \"explicitCachedInput\": 0.6,\n                  \"cacheCreationInput\": 7.5,\n                  \"output\": 24\n                },\n                {\n                  \"maxInputTokens\": 200000,\n                  \"input\": 8,\n                  \"cachedInput\": 1.6,\n                  \"explicitCachedInput\": 0.8,\n                  \"cacheCreationInput\": 10,\n                  \"output\": 28\n                }\n              ]\n            },\n            \"extraBody\": {\n              \"preserve_thinking\": true\n            }\n          }\n        }\n      }\n    }\n  }\n  ```\n  内置 token 价格覆盖 Codex GPT 模型（USD）、DashScope `qwen3.7-max`、`qwen3.7-plus`、`glm-5.1`、`glm-5.2`（CNY），DeepSeek `deepseek-v4-flash`、`deepseek-v4-pro`、`deepseek-chat`、`deepseek-reasoner`（CNY），以及 OpenCode Go 模型（`hy3`、`gpt-5.6-luna`、`glm-5.2`、`grok-4.5`、`deepseek-v4-flash`、`deepseek-v4-pro`、`kimi-k2.7-code`、`kimi-k3`、`mimo-v2.5`、`mimo-v2.5-pro`、`qwen3.7-plus`、`qwen3.7-max`、`minimax-m2.7`、`minimax-m3`，USD）。用户配置的 `pricing` 优先于内置价格。DashScope 若上游 usage 中出现 `cache_creation_input_tokens` 字段，cached tokens 按显式缓存读价计费；否则 `cachedInput` 作为隐式缓存读价。DeepSeek 的 `prompt_cache_hit_tokens` 会归入 cached input，`prompt_cache_miss_tokens` 会归入普通 input。\n- **smallModel：** 无工具预热消息的回退模型（例如 Claude Code 的探测请求）；默认是 `gpt-5-mini`。网关会对无工具的预热或探测请求强制使用该小模型，以避免消耗 premium 请求。该行为仅在 GitHub Copilot 账户为非 token-based 计费时生效（`token_based_billing` 为 false）；对于 token-based 计费账户，预热小模型回退会被跳过，因为不存在需要节省的 premium 请求配额。\n- **contextManagement：** 控制代理是否为 Responses API 附加 `context_management` 压缩指令。`messages` 作用于被翻译成 Responses API 的 Anthropic 风格 `/v1/messages` 请求，包括 `openai-responses` provider 的 Messages 路由，默认值为 `true`。`responses` 作用于 native `/v1/responses` 流量，包括 `provider/model` 别名和内置 `codex` provider，默认值为 `false`。只有在确认客户端支持 context management compaction 后，才建议在 Responses API 下启用 `responses`。启用后，请求体会带上 `context_management`，并在后续轮次中仅保留最新的压缩承载内容。**注意：** 对于 GPT-5.6 及以上模型（如 `gpt-5.6-sol`、`gpt-5.6-terra`、`gpt-5.6-luna`），context management 功能会被强制禁用，因为开启后会破坏这些模型的 prompt 缓存命中。此强制覆盖优先于 `contextManagement` 和 `modelResponsesApiCompactThresholds` 配置。\n - **modelResponsesApiCompactThresholds：** 按模型覆盖 Responses API 的 `compact_threshold`，仅在代理自动附加 `context_management` 时使用。它的优先级高于 `resolveResponsesCompactThreshold` 基于 `max_prompt_tokens * ratio` 的兜底阈值。默认将 `gpt-5.4` 和 `gpt-5.5` 设为 `217600`（`272000 * 0.8`）。未列出的模型继续使用原有兜底逻辑。\n- **modelReasoningEfforts：** `/v1/messages` 请求的模型级默认推理强度。仅当请求没有传入 `output_config.effort` 时，该配置才会生效。\n  - **优先级：** 请求中的 `output_config.effort` > `modelReasoningEfforts[model]` > 内置默认值（GPT-5.3+ 模型为 `xhigh`，其他模型为 `high`）。\n  - **转发字段：** 走 Copilot 原生 Messages API 时，最终值写入 `output_config.effort`；转换为 Responses API 时，最终值写入 `reasoning.effort`。\n  - **配置可选值：** `none`、`minimal`、`low`、`medium`、`high`、`xhigh`、`max`。\n- **useMessagesApi：** 当为 `true` 时，支持 Copilot 原生 `/v1/messages` 的 Claude 系模型会走 Messages API；否则回退到 `/chat/completions`。设为 `false` 可禁用 Messages API 路由，始终使用 `/chat/completions`。默认值为 `true`。\n- **useResponsesApiWebSocket：** 当为 `true` 时，Responses API 请求会优先对声明了 `ws:/responses` 的模型使用 Copilot websocket transport；仅声明 `/responses` 的模型仍走 HTTP。设为 `false` 可禁用 websocket 路由，并在模型支持 `/responses` 时使用 HTTP `/responses`。默认值为 `true`。如果遇到 Responses API WebSocket closed，一般是自己的网络问题。如果使用了 VPN，建议切换节点。\n- **useResponsesApiWebSearch：** 当为 `true` 时，服务端会保留 Responses API 中 `type: \"web_search\"` 的工具并透传到上游。设为 `false` 则会从 `/responses` payload 中移除这些工具。默认值为 `true`。\n- **messageApiWebSearchModel：** 顶层 Copilot `/v1/messages` 请求只包含服务端 `web_search` 工具时使用的全局模型，默认值为 `gpt-5-mini`。如果该值是 `provider/model` 别名，请求会进入对应 provider 的 Messages API 路径，并在转发前移除 provider 前缀。对于 Copilot GPT 模型，web search 会通过 `/responses` 执行。混合 `web_search` 与自定义工具的场景暂不支持，服务端会移除 server-side `web_search`。\n- **claudeTokenMultiplier：** 用于 Claude `/v1/messages/count_tokens` 请求在本地走 GPT tokenizer 估算时的乘数。默认值为 `1.15`。如果你的客户端仍然过晚触发上下文压缩，可以适当调大。这个配置只会在代理本地估算 Claude token 时生效；如果已经配置 `anthropicApiKey` 且 Anthropic token counting 调用成功，则会直接返回 Anthropic 的精确计数，不会使用这个乘数。\n- **anthropicApiKey：** 用于把 Claude `/v1/messages/count_tokens` 请求转发到 Anthropic 真实 token counting 端点的 API key，这样会返回精确计数，而不是 GPT tokenizer 估算值。也可通过环境变量 `ANTHROPIC_API_KEY` 设置。若未配置，或上游调用失败，则回退到由 `claudeTokenMultiplier` 控制的本地 GPT tokenizer 估算。\n\n编辑此文件后即可自定义 prompts，或替换为你自己的快速模型。修改完成后请重启服务（或重新执行命令），让缓存中的配置刷新生效。\n\n## API 认证\n\n- **受保护的普通路由：** 当配置了 `auth.apiKeys` 且非空时，除 `/`、`/usage-viewer` 和 `/usage-viewer/` 以外的普通路由都需要认证。\n- **Admin 路由：** 所有 `/admin/*` 路由都要求 `auth.adminApiKey`。如果缺失，服务会在启动时自动生成并在开始提供服务前写回 `config.json`。\n- **允许的认证头：**\n  - `x-api-key: <your_key>`\n  - `Authorization: Bearer <your_key>`\n- **CORS 预检：** `OPTIONS` 请求始终允许。\n- **未配置普通 key 时：** 普通路由仍可直接访问；但这条规则不适用于 `/admin/*`，后者只接受 `auth.adminApiKey`。\n\n普通受保护路由的示例请求：\n\n```sh\ncurl http://localhost:4141/v1/models \\\n  -H \"x-api-key: your_api_key\"\n```\n\nAdmin 路由的示例请求：\n\n```sh\ncurl http://localhost:4141/admin/config/model-mappings \\\n  -H \"x-api-key: your_admin_api_key\"\n```\n\n## API 端点\n\n服务端提供多个 OpenAI / Anthropic 兼容端点。请求会根据所选模型和 `provider/model` 别名路由到 GitHub Copilot、内置 `codex` provider 或已配置的 provider。\n\n### OpenAI 兼容端点\n\n这些端点模拟 OpenAI API 结构。\n\n| 端点 | 方法 | 说明 |\n| --- | --- | --- |\n| `POST /v1/responses` | `POST` | OpenAI 中用于生成模型响应的高级接口。支持 `openai-responses` provider 的 `provider/model` 别名。 |\n| `POST /v1/chat/completions` | `POST` | 为给定聊天对话创建模型响应。支持 `openai-compatible` provider 的 `provider/model` 别名；目标 provider 已配置时可在没有 Copilot 的情况下使用。 |\n| `GET /v1/models` | `GET` | 列出 Copilot 模型以及已启用 provider 的 `provider/model-id` 模型。来自 Codex 客户端（`User-Agent` 以 `codex` 开头）的请求会转发到 Codex Models 上游。 |\n| `POST /v1/embeddings` | `POST` | 创建表示输入文本的向量嵌入。 |\n\n### Codex 后端代理端点\n\n这些端点要求已有可用的 Codex 登录态。每个端点同时提供无版本前缀和 `/v1` 两种路径。\n\n| 端点 | 方法 | 说明 |\n| --- | --- | --- |\n| `POST /alpha/search`<br>`POST /v1/alpha/search` | `POST` | 将 JSON 请求体和查询参数透明转发到 Codex Alpha Search 上游。 |\n| `POST /images/generations`<br>`POST /v1/images/generations` | `POST` | 将 JSON 图片生成请求转发到 Codex Images 上游。请求未携带 `Content-Type` 时，网关默认补充 `application/json`。 |\n| `POST /images/edits`<br>`POST /v1/images/edits` | `POST` | 将图片编辑请求转发到 Codex Images 上游。请使用 `multipart/form-data`，并让 HTTP 客户端自动生成 `boundary`；网关会保留传入的 content type，并以流式方式转发上传请求体。 |\n\n对于以上所有端点，网关都会使用当前 Codex 登录态覆盖客户端的 authorization 和 account header，保留查询参数及兼容的请求头，并返回上游状态码、响应头和响应体。\n\n### Anthropic 兼容端点\n\n这些端点设计为兼容 Anthropic Messages API。provider 级的 models、Responses、alpha-search 和 images 路由同时支持无版本前缀与 `/v1` 两种路径；Messages 路由仍使用 `/v1`。\n\n| 端点 | 方法 | 说明 |\n| --- | --- | --- |\n| `POST /v1/messages` | `POST` | 为给定对话创建模型响应。支持已配置 provider 的 `provider/model` 别名，包括通过 `openai-compatible` provider 做翻译。 |\n| `POST /v1/messages/count_tokens` | `POST` | 计算一组消息的 token 数。支持已配置 provider 的 `provider/model` 别名。 |\n| `POST /:provider/v1/messages` | `POST` | 将 Anthropic Messages 请求代理到已配置的 Anthropic provider，或翻译到 OpenAI 兼容 / OpenAI Responses provider。 |\n| `GET /:provider/models`<br>`GET /:provider/v1/models` | `GET` | 将模型列表请求代理到已配置的 provider。对 `codex` 默认返回内置模型目录；Codex 客户端（`User-Agent` 以 `codex` 开头）会转发到 Codex Models 上游。 |\n| `POST /:provider/v1/messages/count_tokens` | `POST` | 为 provider 路由请求在本地计算 token 数。 |\n| `POST /:provider/responses`<br>`POST /:provider/v1/responses` | `POST` | 将 OpenAI Responses 请求代理到已配置的 `openai-responses` provider（含 `codex`）。 |\n| `POST /:provider/alpha/search`<br>`POST /:provider/v1/alpha/search` | `POST` | 代理 alpha-search 请求。对 `codex` 转发到 Codex Alpha Search 上游；其他 provider 转发到 `{baseUrl}/v1/alpha/search`。 |\n| `POST /:provider/images/generations`<br>`POST /:provider/v1/images/generations` | `POST` | 代理图片生成。对 `codex` 使用 Codex Images 上游；其他 provider 转发到 `{baseUrl}/v1/images/generations`（15 分钟超时）。 |\n| `POST /:provider/images/edits`<br>`POST /:provider/v1/images/edits` | `POST` | 代理图片编辑。对 `codex` 使用 Codex Images 上游；其他 provider 以 multipart/流式方式转发到 `{baseUrl}/v1/images/edits`（15 分钟超时）。 |\n\n### 使用量监控端点\n\n用于监控 Copilot 用量与额度的新端点。\n\n| 端点 | 方法 | 说明 |\n| --- | --- | --- |\n| `GET /usage` | `GET` | 获取详细的 Copilot 使用统计与额度信息。 |\n| `GET /token` | `GET` | 获取当前 API 正在使用的 Copilot token。 |\n\n### Admin / 配置端点\n\n这些端点用于本地管理操作，只接受 `auth.adminApiKey`。\n\n| 端点 | 方法 | 说明 |\n| --- | --- | --- |\n| `GET /admin/config/model-mappings` | `GET` | 返回当前 `config.json` 路径以及生效中的 `modelMappings` 映射。 |\n| `POST /admin/config/model-mappings` | `POST` | 只更新 `config.json` 里的 `modelMappings` 字段，并回传更新后的结果。 |\n\n## 使用示例\n\n常用 `npx` 命令：\n\n```sh\n# 基础启动\nnpx @jeffreycao/copilot-api@latest start\n\n# 自定义端口并开启详细日志\nnpx @jeffreycao/copilot-api@latest start --port 8080 --verbose\n\n# 执行认证流程\nnpx @jeffreycao/copilot-api@latest auth login\n\n# 配置第三方 provider，然后不依赖 GitHub Copilot 启动\nnpx @jeffreycao/copilot-api@latest auth login --provider dashscope\nnpx @jeffreycao/copilot-api@latest start\n\n# 以 JSON 格式输出调试信息\nnpx @jeffreycao/copilot-api@latest debug --json\n\n# 用 Bun 而不是 Node.js 运行已发布 CLI\nbunx --bun @jeffreycao/copilot-api@latest start\n```\n\n配置 `dashscope` 后的 OpenAI 兼容 provider 调用示例：\n\n```sh\ncurl http://localhost:4141/v1/chat/completions \\\n  -H \"content-type: application/json\" \\\n  -d '{\"model\":\"dashscope/qwen3.6-plus\",\"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]}'\n\ncurl http://localhost:4141/dashscope/v1/messages \\\n  -H \"content-type: application/json\" \\\n  -d '{\"model\":\"qwen3.6-plus\",\"max_tokens\":1024,\"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]}'\n```\n\n## 使用建议\n\n<a id=\"claudemd-or-agentsmd-recommended-content\"></a>\n\n### CLAUDE.md 或 AGENTS.md 推荐内容\n\n如果你想手动加入这些提醒，请在 Claude Code 的 `CLAUDE.md`，或 opencode/codex 的 `AGENTS.md` 中加入以下内容：\n\n```\n- Prohibited from directly asking questions to users, MUST use question tool.\n- Once you can confirm that the task is complete, MUST use question tool to make user confirm. The user may respond with feedback if they are not satisfied with the result, which you can use to make improvements and try again, after try again, MUST use question tool to make user confirm again.\n```\n"}, "25cf6508396ef7c5ce20335ea4414a01c32a7549": {"t": 1785765526.5332565, "n": 34603, "h": "27c4c2f373c5071e", "c": "# Copilot API Proxy\n\n[English](./README.md) | 简体中文\n\n## 重要说明\n\n> [!IMPORTANT]\n> **使用前请先注意以下几点：**\n>\n> 1. **Claude Code 配置：** 与 Claude Code 搭配使用时，请将模型 ID 配置为 `claude-opus-4-8`。示例 claude `settings.json` 见 [通过 `settings.json` 手动配置](#manual-configuration-with-settingsjson)。\n>\n> 2. **内置 `copilot`、`codex` 与第三方 provider：** 执行 `npx @jeffreycao/copilot-api@latest auth`，可选择 `copilot`、`codex`、`deepseek`、`custom` 等 provider。\n>\n> 3. **注意事项：** README 顶部移除的 GitHub Copilot warning 见 [GitHub Copilot 安全提示](./NOTICE.md#github-copilot-security-notice)。\n\n---\n\n## 项目概览\n\n这是一个小型 AI gateway，可以使用 GitHub Copilot、内置 `codex` provider，也可以使用 DashScope 等已配置的第三方 provider。GitHub Copilot 现在是可选能力：如果本地没有 GitHub token，只要至少配置了一个启用中的 provider，服务仍可按 provider-only 模式启动。\n\nAI gateway 会从同一个本地端点暴露 OpenAI / Anthropic 兼容 API，让 [Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview)、OpenCode、Codex 和 OpenAI 兼容客户端可以共用同一个本地服务。\n\n在 GitHub Copilot 路径上，AI gateway 会在可用时优先使用 Copilot 原生的 Anthropic 风格 Messages API，在重工具调用场景下保留更原生的 Claude 行为。\n\n## 功能特性\n\n- **OpenAI 与 Anthropic 双兼容**：通过 `/v1/responses`、`/v1/chat/completions`、`/v1/models`、`/v1/embeddings` 和 `/v1/messages` 对外暴露同一个本地 AI gateway。\n- **Copilot 可选**：有 GitHub 凭据时可以使用 GitHub Copilot，没有 GitHub 凭据时也可以只依赖已配置的 provider 运行。\n- **同一网关接入 Copilot、`codex` 与第三方 provider**：可统一路由 GitHub Copilot、内置 `codex` provider 和配置好的外部 provider。\n- **第三方 provider 可独立启动**：配置 DashScope、DeepSeek、OpenRouter 或自定义 provider 后，不需要 GitHub Copilot 登录即可启动 AI gateway。\n- **OpenAI 兼容 provider 同时支持 chat 和 Messages API**：`openai-compatible` provider 可通过顶层 `/v1/chat/completions` 搭配 `model: \"provider/model\"` 提供 Chat Completions，也可通过 `/v1/messages` 完成 Anthropic Messages 的请求/响应翻译。\n- **面向 Claude 的更原生 Copilot 路由**：优先使用原生 `/v1/messages`，保留 Claude 风格工具流，支持 Anthropic beta 能力、通过 Responses-capable 模型支持 Claude WebSearch，并保留 subagent / session 标记。\n- **Claude Code 与 OpenCode 集成**：兼容 Claude Code 与 OpenCode，也支持通过 `@ai-sdk/anthropic` 直接作为 Anthropic provider 使用。\n- **灵活的认证与部署选项**：支持交互式登录、直接 token、个人 / Business / Enterprise、GitHub Enterprise、opencode OAuth 和自定义数据目录。\n- **多 provider 路由**：可暴露 `/:provider/...` 路由，也可在顶层 API 上使用 `model: \"provider/model\"`。\n\n## 前置要求\n\n- Bun（>= 1.2.x）\n- 如果要通过 `npx` 运行已发布 CLI，需要 Node.js\n- 只有在使用 GitHub Copilot provider 时，才需要已订阅 Copilot 的 GitHub 账号\n- 如果不使用 GitHub Copilot，需要至少一个已配置 provider 的 API key 或 OAuth 登录\n\n## 安装\n\n安装依赖：\n\n```sh\nbun install\n```\n\n直接从源码启动服务：\n\n```sh\nbun run start start\n```\n\n## 从源码运行\n\n本项目可以通过多种方式从源码运行：\n\n### 开发模式\n\n```sh\nbun run dev start\n```\n\n### 生产模式\n\n```sh\nbun run start start\n```\n\n## 通过 npx 使用\n\n你可以直接用 npx 运行本项目：\n\n> [!IMPORTANT]\n> 通过 `npx` 运行时，token usage 存储会使用 Node 内置的 `node:sqlite` 模块。该能力会在 Node.js >= 22.13.0 时启用；Node.js < 22.13.0 时 CLI 仍可启动，但会禁用 token usage 存储。\n>\n> 如果不升级 Node.js 但仍需要 token usage 存储，可以改用 Bun 运行已发布 CLI：`bunx --bun @jeffreycao/copilot-api@latest start`。\n\n```sh\nnpx @jeffreycao/copilot-api@latest start\n```\n\n带参数示例：\n\n```sh\nnpx @jeffreycao/copilot-api@latest start --port 8080\n```\n\n如果只想做认证或 provider 配置：\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth\n```\n\n如果要不依赖 GitHub Copilot 运行，先配置至少一个 provider，然后正常启动服务：\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth login --provider dashscope\nnpx @jeffreycao/copilot-api@latest start\n```\n\n## 配合 Docker 使用\n\n构建镜像：\n\n```sh\ndocker build -t copilot-api .\n```\n\n通过 bind mount 运行容器，让认证数据在重启后保留：\n\n```sh\nmkdir -p ./copilot-data\ndocker run -p 4141:4141 -v $(pwd)/copilot-data:/root/.local/share/copilot-api copilot-api\n```\n\n这会把宿主机上的 `./copilot-data` 映射到容器内的 `/root/.local/share/copilot-api`，用于持久化 GitHub 认证数据、provider 配置和其他 gateway 状态。\n\n也可以直接通过环境变量传入 GitHub token：\n\n```sh\ndocker run -p 4141:4141 -e GH_TOKEN=your_github_token_here copilot-api\n```\n\n## Electron 桌面应用\n\n如果你更喜欢图形界面，仓库里还提供了位于 `desktop/` 的 Electron 桌面应用。它支持 GitHub Copilot 登录、OpenAI Codex OAuth，以及 DeepSeek、DashScope、OpenRouter 或自定义 provider 的 API Key 配置。授权或配置 provider 后，可以一键启动或停止本地代理，并在界面里直接查看本地端点、鉴权 Header、可用模型、额度和日志。\n\n设置页还可以配置 `OAuth App`、`API Home`、`Enterprise URL`、详细日志以及最小化到托盘。Windows x64（`.exe`）、macOS Apple Silicon（`.dmg`）和 Linux x64（`.AppImage`）安装包发布在 GitHub Releases：\n\nhttps://github.com/caozhiyuan/copilot-api/releases\n\nLinux 用户需要先为下载的 AppImage 添加执行权限：\n\n```sh\nchmod +x Copilot-API-*-linux-x86_64.AppImage\n./Copilot-API-*-linux-x86_64.AppImage\n```\n\n下载对应平台的安装包后，在应用内授权或配置 provider，选择端口并启动服务，再把你的客户端指向应用里显示的本地端点即可。发布版桌面应用使用随包内置的 Electron 运行时，正常使用不需要额外安装 Node.js；token usage 历史记录会在该内置运行时支持 SQLite 时启用。\n\n桌面应用里的高级配置页会通过 `GET/POST /admin/config/model-mappings` 读写这份共享的模型映射。同一份映射会统一作用于 `POST /v1/messages`、`POST /v1/messages/count_tokens`、`POST /v1/responses` 和 `POST /v1/chat/completions`，不再按接口区分。它使用的是 `auth.adminApiKey`，不是普通的 `auth.apiKeys`；应用会在服务启动并自动生成该 key 后，直接从 `config.json` 读取它来发起请求。\n\n### 桌面应用截图\n\n下面展示了桌面应用中的首页、Token 用量统计页面：\n\n<p align=\"center\">\n  <img src=\"./docs/screenshots/desktop-dashboard.png\" alt=\"Copilot API 桌面应用首页\" width=\"49%\" />\n  <img src=\"./docs/screenshots/desktop-token-usage.png\" alt=\"Copilot API 桌面应用 Token 用量页\" width=\"49%\" />\n</p>\n\n## 与 Claude Code 一起使用\n\n这个 AI gateway 可以为 [Claude Code](https://docs.anthropic.com/en/claude-code) 提供后端能力。Claude Code 是 Anthropic 提供的实验性面向开发者的对话式 AI 助手。\n\n有两种方式可以把 Claude Code 配置为使用这个 AI gateway：\n\n### 通过 `--claude-code` 标志进行交互式配置\n\n执行带 `--claude-code` 的 `start` 命令开始：\n\n```sh\nnpx @jeffreycao/copilot-api@latest start --claude-code\n```\n\n你不再需要手动选择模型。Gateway 会自动检测每个 Claude Code 尺寸档位对应的最新可用模型——opus 映射到最新的 Opus 模型，sonnet 映射到最新的 Sonnet 模型，haiku 映射到最新的 Haiku 模型——并生成相应设置 `ANTHROPIC_DEFAULT_OPUS_MODEL`、`ANTHROPIC_DEFAULT_SONNET_MODEL` 和 `ANTHROPIC_DEFAULT_HAIKU_MODEL` 的命令。若某个档位没有匹配的可用模型，则会被省略。该命令会被复制到剪贴板，并设置 Claude Code 使用这个 AI gateway 所需的环境变量。\n\n在新的终端中粘贴并执行这条命令，即可启动 Claude Code。\n\n<a id=\"manual-configuration-with-settingsjson\"></a>\n\n### 通过 `settings.json` 手动配置\n\n另一种方式是在项目根目录中创建 `.claude/settings.json` 文件，并写入 Claude Code 所需的环境变量。这样你就不需要每次都运行交互式配置了。\n\n下面是一个 `.claude/settings.json` 示例：\n\n```json\n{\n  \"env\": {\n    \"ANTHROPIC_BASE_URL\": \"http://localhost:4141\",\n    \"ANTHROPIC_AUTH_TOKEN\": \"dummy\",\n    \"ANTHROPIC_MODEL\": \"gpt-5.6-sol[1m]\",\n    \"ANTHROPIC_DEFAULT_OPUS_MODEL\": \"gpt-5.6-sol[1m]\",\n    \"ANTHROPIC_DEFAULT_SONNET_MODEL\": \"gpt-5.6-sol[1m]\",\n    \"ANTHROPIC_DEFAULT_HAIKU_MODEL\": \"gpt-5.6-luna[1m]\",\n    \"CLAUDE_CODE_AUTO_COMPACT_WINDOW\": \"272000\",\n    \"CLAUDE_CODE_USE_VERTEX\": \"0\",\n    \"CLAUDE_CODE_USE_BEDROCK\": \"0\",\n    \"DISABLE_NON_ESSENTIAL_MODEL_CALLS\": \"1\",\n    \"CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC\": \"1\",\n    \"CLAUDE_CODE_ATTRIBUTION_HEADER\": \"0\",\n    \"CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION\": \"false\",\n    \"CLAUDE_CODE_DISABLE_TERMINAL_TITLE\": \"true\",\n    \"CLAUDE_CODE_ENABLE_AWAY_SUMMARY\": \"0\"\n  },\n  \"alwaysThinkingEnabled\": true,\n  \"effortLevel\": \"xhigh\",\n  \"showThinkingSummaries\": true\n}\n```\n\n- 请根据需要替换 `ANTHROPIC_MODEL`、`ANTHROPIC_DEFAULT_OPUS_MODEL`、`ANTHROPIC_DEFAULT_SONNET_MODEL` 和 `ANTHROPIC_DEFAULT_HAIKU_MODEL`。配置完成后，请安装 claude code 插件，见 [插件集成](#plugin-integrations)。\n- 如果你使用的是 codex provider，建议**不要**将模型名配置成 `codex/xxx` 格式（如 `codex/gpt-5.6-sol`）。Claude Code 会针对 `codex/` 前缀做降智行为——例如每次请求时移除所有之前返回的思考块（thinking blocks）。请使用纯模型名（如 `gpt-5.6-sol`），并在 `config.json` 中配置 `modelMappings` 将其映射回 codex provider：\n  ```json\n  \"modelMappings\": {\n    \"gpt-5.6-sol\": \"codex/gpt-5.6-sol\",\n    \"gpt-5.6-terra\": \"codex/gpt-5.6-terra\",\n    \"gpt-5.6-luna\": \"codex/gpt-5.6-luna\"\n  },\n  ```\n- 将 `CLAUDE_CODE_ATTRIBUTION_HEADER` 设为 `0` 可以阻止 Claude Code 在 system prompt 中附加计费和版本信息，从而避免 prompt cache 失效。\n- 关闭 `CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION` 和 `CLAUDE_CODE_ENABLE_AWAY_SUMMARY` 可以避免不必要地消耗额度。\n- Claude Code WebSearch 已支持纯搜索请求。Copilot 路径请保持全局 `messageApiWebSearchModel` 指向 Responses-capable GPT 模型或 `provider/model` 别名；provider 路由请使用原生 Anthropic provider 或 `openai-responses` provider。只有在你明确想禁止这类流量时，才需要把 `WebSearch` 加到 `permissions.deny`。\n- 如果使用的不是 Claude 模型，请不要启用 `ENABLE_TOOL_SEARCH`。如果使用的是 Claude 模型，则可以启用 `ENABLE_TOOL_SEARCH`。当前 Claude Code 使用的是客户端 tool search 模式，在该模式下每次加载 defer tools 都需要额外请求一次。\n- `CLAUDE_CODE_AUTO_COMPACT_WINDOW`：设置用于自动压缩计算的上下文容量（以 token 为单位）。默认使用模型自身的上下文窗口：标准模型为 200K，扩展上下文模型为 1M。使用 1M 上下文模型（如 `claude-opus-4-6[1m]`）时，可设置一个较低的值（如 `500000`）将窗口视为 500K 用于压缩计算。该值受限于模型的实际上下文窗口上限。`CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` 会基于此值的百分比生效。设置此变量可将压缩阈值与状态栏的 `used_percentage` 解耦（后者始终使用模型的完整上下文窗口）。\n\n更多选项见：[Claude Code settings](https://docs.anthropic.com/en/docs/claude-code/settings#environment-variables)\n\n也可以参考 IDE 集成说明：[Add Claude Code to your IDE](https://docs.anthropic.com/en/docs/claude-code/ide-integrations)\n\n## 与 OpenCode 一起使用\n\nOpenCode 已经有直接的 GitHub Copilot provider。本节适用于你希望让 OpenCode 通过 `@ai-sdk/anthropic` 指向这个 AI gateway，并复用本 README 前面提到的 agent 行为时。\n\n### 最小配置\n\n使用 OpenCode OAuth app 启动 AI gateway：\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth --oauth-app=opencode\nnpx @jeffreycao/copilot-api@latest start\n```\n\n然后让 OpenCode 通过 `@ai-sdk/anthropic` 指向这个 AI gateway。\n\n示例 `~/.config/opencode/opencode.json`：\n\n```json\n{\n  \"$schema\": \"https://opencode.ai/config.json\",\n  \"provider\": {\n    \"local\": {\n      \"npm\": \"@ai-sdk/anthropic\",\n      \"name\": \"My Local\",\n      \"options\": {\n        \"baseURL\": \"http://localhost:4141/v1\",\n        \"apiKey\": \"dummy\"\n      },\n      \"models\": {\n        \"gpt-5.4\": {\n          \"name\": \"gpt-5.4\",\n          \"modalities\": {\n            \"input\": [\"text\", \"image\"],\n            \"output\": [\"text\"]\n          },\n          \"limit\": {\n            \"context\": 400000,\n            \"input\": 272000,\n            \"output\": 128000\n          }\n        },\n        \"claude-sonnet-4.6\": {\n          \"id\": \"claude-sonnet-4.6\",\n          \"name\": \"claude-sonnet-4.6\",\n          \"modalities\": {\n            \"input\": [\"text\", \"image\"],\n            \"output\": [\"text\"]\n          },\n          \"limit\": {\n            \"context\": 200000,\n            \"output\": 32000\n          },\n          \"options\": {\n            \"thinking\": {\n              \"type\": \"adaptive\"\n            },\n            \"effort\": \"max\"\n          }\n        }\n      }\n    }\n  }\n}\n```\n\n这些字段的重要性：\n\n- `npm: \"@ai-sdk/anthropic\"` 是关键。OpenCode 会以 Anthropic Messages 语义与这个 AI gateway 通信，而不是把一切扁平化为 OpenAI Chat Completions。\n- `options.baseURL` 应设为 `http://localhost:4141/v1`；Anthropic SDK 会自动补上 `/messages`、`/models` 和 `/messages/count_tokens`。\n- 如果你在此代理中启用了 `auth.apiKeys`，请把 `dummy` 替换为真实 key；否则任意占位值都可以。\n\n## 与 Codex 一起使用\n\n这个 AI gateway 也可以为 Codex 提供后端能力。\n\n### Codex `config.toml` 参考配置\n\n把以下 `[model_providers.copilot_api]` 段加入你的 Codex `~/.codex/config.toml`：\n\n```toml\nmodel_provider = \"copilot_api\"\nmodel_reasoning_summary = \"auto\"\nmodel_context_window = 272000\nmodel_auto_compact_token_limit = 244800\n\n[model_providers.copilot_api]\nname = \"OpenAI\"\nbase_url = \"http://localhost:4141\"\nenv_key = \"GITHUB_COPILOT_API_KEY\"\nrequires_openai_auth = true\nsupports_websockets = false\nwire_api = \"responses\"\nrequest_max_retries = 3\nstream_max_retries = 1\nstream_idle_timeout_ms = 300000\n\n[features]\nremote_compaction_v2 = true\n\n[analytics]\nenabled = false\n```\n\n> [!NOTE]\n> 此配置仅限于 Codex 与 GitHub Copilot provider。`name` 一定要配置为 `\"OpenAI\"`。它可以缓解 Codex local compact 不命中缓存的问题。\n> 如果使用 codex provider，建议将 `base_url` 配置为 `\"http://localhost:4141/codex\"`。\n\n## GPT Tool Search\n\n对于 `gpt-5.4+` 这类 GPT Responses 模型，这个 AI gateway 可以通过一个很小的 MCP bridge 暴露 Responses `tool_search`。Claude Code 和 opencode 都可以使用同一个 bridge，前提是客户端会加载 MCP server，并且 Anthropic Messages 流量会经过这个 AI gateway。\n\nGPT 模型不要设置 Claude Code 原生的 `ENABLE_TOOL_SEARCH`。这个开关启用的是 Claude Code 自己的客户端 tool search 模式，可能导致 deferred 工具定义不再转发给 AI gateway。这个 AI gateway 需要完整的工具定义，这样才能只保留那一小组常驻加载工具，其余工具统一转换为 Responses deferred namespace。\n\n如果你安装了 `tool-search@copilot-api-marketplace`，Claude Code 会自动带上这个 MCP bridge，可以跳过下面这段 Claude Code MCP 手动配置。\n\n请把 tool search bridge 加到 Claude Code 使用的 MCP 配置中：\n\n```json\n{\n  \"mcpServers\": {\n    \"tool_search\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@jeffreycao/copilot-api@latest\", \"mcp\"]\n    }\n  }\n}\n```\n\n请把 tool search bridge 加到 opencode 使用的 MCP 配置中：\n\n```json\n{\n  \"mcp\": {\n    \"tool_search\": {\n      \"type\": \"local\",\n      \"command\": [\"npx\", \"-y\", \"@jeffreycao/copilot-api@latest\", \"mcp\"]\n    }\n  }\n}\n```\n\n本地开发时可以将命令换成 `bun`，参数换成 `[\"run\", \"./src/main.ts\", \"mcp\"]`。\n\nAI gateway 内部现在会把 OpenAI Responses `tool_search` 配置成 client-executed 模式。deferred tools 仍然会作为可搜索 namespace 暴露给模型，但会明确要求模型直接返回下一步要加载的精确工具名列表。\n\n该 bridge 使用直接工具选择，不做 query 搜索。工具入参是 `names`，值为逗号分隔的精确 deferred 工具名，例如 `TaskList,TaskGet,mcp__fetch__fetch`。\n\n<a id=\"plugin-integrations\"></a>\n\n## 插件集成\n\n本项目为 Claude Code 和 opencode 提供了插件集成。\n\n#### Claude Code 插件集成（基于 marketplace）\n\nClaude Code 集成现在拆分为两个插件：\n\n- `agent-inject` 会在 `SubagentStart` 时注入 `__SUBAGENT_MARKER__...`，以便 AI gateway 推导 `x-initiator: agent`。\n- `tool-search` 会注册用于 GPT Responses deferred tool loading 的 `tool_search` MCP bridge。\n\n- 本仓库中的 marketplace catalog：`.claude-plugin/marketplace.json`\n- 本仓库中的插件源码：`plugin/claude/agent-inject`、`plugin/claude/tool-search`\n\n远程添加 marketplace：\n\n```sh\n/plugin marketplace add https://github.com/caozhiyuan/copilot-api.git\n```\n\n从 marketplace 安装插件：\n\n```sh\n/plugin install agent-inject@copilot-api-marketplace\n/plugin install tool-search@copilot-api-marketplace\n```\n\n安装后，`agent-inject` 会在 `SubagentStart` 时注入 `__SUBAGENT_MARKER__...`，AI gateway 会利用它推导 `x-initiator: agent`。\n\n`agent-inject` 还会注册一个 `UserPromptSubmit` hook，并返回 `{\"continue\": true}`；同时它也可以通过环境变量注入 `SessionStart` reminder 规则：\n\n- `CLAUDE_PLUGIN_ENABLE_QUESTION_RULES=1` 会自动为 Claude Code 启用两条关于使用 `question` 工具的提醒。你也可以把同样的提醒手动写进 `CLAUDE.md`；见 [CLAUDE.md 或 AGENTS.md 推荐内容](#claudemd-or-agentsmd-recommended-content)。\n- `CLAUDE_PLUGIN_ENABLE_NO_BACKGROUND_AGENTS_RULE=1` 会启用关于避免在 agent hooks 中使用 `run_in_background: true` 的提醒。\n\n`tool-search` 插件内置了 [GPT Tool Search](#gpt-tool-search) 一节描述的同一个 MCP bridge，因此安装该插件后，Claude Code 用户无需再手动配置 `tool_search` server。\n\n#### Opencode 插件\n\nsubagent 标记生成器被打包为一个 opencode 插件，位于 `plugin/opencode/subagent-marker.js`。\n\n**安装方式：**\n\n将插件文件复制到你的 opencode 插件目录：\n\n```sh\n# 克隆或下载本仓库后复制该插件\ncp plugin/opencode/subagent-marker.js ~/.config/opencode/plugins/\n```\n\n或者手动在 `~/.config/opencode/plugins/subagent-marker.js` 创建该文件，并填入插件内容。\n\n**功能：**\n\n- 跟踪 subagent 创建的子会话\n- 自动在 subagent 聊天消息前添加 marker system reminder（`__SUBAGENT_MARKER__...`）\n- 设置 `x-session-id` 请求头以跟踪会话\n- 让这个 AI gateway 能够把来自 subagent 的请求识别为 `x-initiator: agent`\n\n该插件会挂接到 `session.created`、`session.deleted`、`chat.message` 和 `chat.headers` 事件上，以无缝提供 subagent marker 能力。\n\n## 使用量查看器\n\n服务启动后，控制台会输出一个 Copilot 使用量看板 URL。这个看板是一个用于监控 API 用量的 Web 界面。\n\n1. 启动服务。例如使用 npx：\n   ```sh\n   npx @jeffreycao/copilot-api@latest start\n   ```\n2. 服务会输出一个 usage viewer 的 URL。将它复制到浏览器中打开，形式大致如下：\n   `http://localhost:4141/usage-viewer?endpoint=http://localhost:4141/usage`\n   - 如果你在 Windows 上使用 `start.bat` 脚本，这个页面会自动打开。\n\n看板提供了更易读的 Copilot 用量视图：\n\n> token usage 历史记录需要 Bun 或 Node.js >= 22.13.0。Node.js < 22.13.0 时服务会正常运行，但 token usage 存储会被禁用。\n\n- **API Endpoint URL**：通过 URL 查询参数指定 API endpoints，默认指向本地服务。支持手动切换为其他兼容 endpoints。\n- **x-api-key 认证**：如果启用了 API Key 认证，可填入 `x-api-key` 请求头。密钥会持久化保存在浏览器本地存储中。\n- **Period 选择器**：支持 Day / Week / Month 三种时间范围，切换时 URL 参数会自动同步，方便收藏和分享。\n- **Fetch Data**：点击 \"Refresh\" 按钮加载或刷新使用数据。页面加载时也会自动拉取数据。\n- **Copilot Quotas 额度**：通过进度条展示 Chat、Completions 等不同服务的额度使用情况，悬停可查看已用/剩余详情。\n- **Token Usage 指标卡片**：汇总当前周期的 Total、Input、Output、Cache Read、Cache Write、Requests 和预估费用。\n- **趋势图（Week / Month）**：提供按模型和指标筛选的折线趋势图，点击数据点可查看单日用量明细。\n- **Model Breakdown 表格**：按模型维度列出周期内的请求数、输入/输出/缓存 token 和预计费用。\n- **Request Events 分页列表**：按时间排序的请求事件记录，支持分页浏览，含时间戳、模型、请求 ID 和 token 用量。\n- **Detailed Information**：展示 API 返回的完整 JSON 响应，便于深入分析所有可用统计数据。\n- **URL-based Configuration**：也可通过 `endpoint` 和 `period` 查询参数直接指定 API 端点与时间范围。例如：\n  `http://localhost:4141/usage-viewer?endpoint=http://your-api-server/usage&period=week`\n\n### Usage Viewer 截图\n\n<p align=\"center\">\n  <img src=\"./docs/screenshots/usage-viewer.png\" alt=\"Copilot API Usage Viewer 页面\" width=\"900\" />\n</p>\n\n## 命令结构\n\nCopilot API 现在使用子命令结构，主要命令包括：\n\n- `start`：启动 AI gateway 服务。如果已有 GitHub token，则启用 Copilot 路径；如果没有 GitHub token，但存在至少一个启用中的 provider，则按 provider-only 模式启动；如果两者都没有，会引导你配置 provider。\n- `auth`：仅执行 provider 登录或配置流程，不启动服务。可用于 GitHub Copilot 登录、Codex OAuth，或第三方 provider API key 配置。\n- `debug`：显示诊断信息，包括版本、运行时详情、文件路径以及认证状态，便于排障与支持。\n\n## 命令行选项\n\n### 全局选项\n\n以下选项可用于任意子命令。若在子命令之前传入，请使用 `--key=value` 形式：\n\n| 选项 | 说明 | 默认值 | 别名 |\n| --- | --- | --- | --- |\n| --api-home | API home 目录路径（设置 `COPILOT_API_HOME`） | 无 | 无 |\n| --oauth-app | OAuth app 标识符（设置 `COPILOT_API_OAUTH_APP`） | 无 | 无 |\n| --enterprise-url | GitHub Enterprise URL（设置 `COPILOT_API_ENTERPRISE_URL`） | 无 | 无 |\n\n### Start 命令选项\n\n以下是 `start` 命令可用的命令行选项：\n\n| 选项 | 说明 | 默认值 | 别名 |\n| --- | --- | --- | --- |\n| --port | 监听端口 | 4141 | -p |\n| --verbose | 启用详细日志 | false | -v |\n| --github-token | 直接提供 GitHub token（必须通过 `auth` 子命令生成） | 无 | -g |\n| --claude-code | 生成一个使用 Copilot API 配置启动 Claude Code 的命令 | false | -c |\n| --show-token | 在获取和刷新时显示 GitHub 与 Copilot token | false | 无 |\n| --proxy-env | 从环境变量初始化代理 | false | 无 |\n\n### Auth 命令选项\n\n| 选项 | 说明 | 默认值 | 别名 |\n| --- | --- | --- | --- |\n| --provider | 要登录或配置的 provider（`copilot`、`codex`、`opencode-go`、`deepseek`、`dashscope`、`openrouter` 或 `custom`） | 交互选择 | 无 |\n| --verbose | 启用详细日志 | false | -v |\n| --show-token | 认证时显示 GitHub token | false | 无 |\n\n只有在需要启用 GitHub Copilot provider 时，才需要执行 `copilot-api auth login --provider copilot`。使用 `codex` 或第三方 provider-only 模式不要求配置 Copilot。\n\n使用 `copilot-api auth login --provider deepseek`、`--provider dashscope`、`--provider openrouter` 或 `--provider opencode-go` 可以通过 CLI 快速新增或更新这些常用第三方 provider。DeepSeek 会提示输入掩码显示的 `apiKey`、provider `type`（默认 `anthropic`），以及默认 `https://api.deepseek.com/anthropic` 的 `baseUrl`。DashScope 会提示输入掩码显示的 `apiKey`、provider `type`（默认 `openai-compatible`）和预填默认值的 `baseUrl`。OpenRouter 只提示输入掩码显示的 `apiKey` 和预填默认值的 `baseUrl`，并固定写入 `type: \"anthropic\"`。OpenCode Go 只提示输入掩码显示的 `apiKey` 和预填默认值的 `baseUrl`，并固定写入 `type: \"openai-compatible\"`（baseUrl `https://opencode.ai/zen/go`）。此外，OpenCode Go 内置将 `qwen*` 和 `minimax*` 模型路由到 Anthropic Messages，将 `gpt*` 模型路由到 OpenAI Responses，其他模型仍默认使用 OpenAI 兼容协议。配置并启用 provider 后，`copilot-api start` 可在没有 GitHub token 的情况下启动。\n\n使用 `copilot-api auth login --provider custom` 可以通过 CLI 新增或更新其他第三方 provider。命令会依次提示输入 provider name、项目支持的 type（`anthropic`、`openai-compatible` 或 `openai-responses`）、`baseUrl`、掩码显示的 `apiKey` 和 `authType`；`authType` 可保持 type 默认值，也可选择 `x-api-key` / `authorization`。\n\n### Debug 命令选项\n\n| 选项 | 说明 | 默认值 | 别名 |\n| --- | --- | --- | --- |\n| --json | 以 JSON 输出调试信息 | false | 无 |\n\n<a id=\"configuration-configjson\"></a>\n\n## 配置（config.json）\n\n- **位置：** Linux/macOS 为 `~/.local/share/copilot-api/config.json`，Windows 为 `%USERPROFILE%\\.local\\share\\copilot-api\\config.json`。\n- **默认结构：**\n  ```json\n  {\n    \"auth\": {\n      \"apiKeys\": [],\n      \"adminApiKey\": \"<startup 自动生成>\"\n    },\n    \"providers\": {},\n    \"modelMappings\": {},\n    \"extraPrompts\": {\n      \"gpt-5-mini\": \"<built-in exploration prompt>\"\n    },\n    \"smallModel\": \"gpt-5-mini\",\n    \"contextManagement\": {\n      \"messages\": true,\n      \"responses\": false\n    },\n    \"modelResponsesApiCompactThresholds\": {\n      \"gpt-5.4\": 217600,\n      \"gpt-5.5\": 217600\n    },\n    \"modelReasoningEfforts\": {\n      \"gpt-5-mini\": \"low\"\n    },\n    \"useMessagesApi\": true,\n    \"useResponsesApiWebSocket\": true,\n    \"useResponsesApiWebSearch\": true,\n    \"messageApiWebSearchModel\": \"gpt-5-mini\"\n  }\n  ```\n- **auth.apiKeys：** 用于普通非 admin 路由的 API key。支持多个 key 轮换使用。请求可通过 `x-api-key: <key>` 或 `Authorization: Bearer <key>` 进行认证。若为空或省略，则普通路由的认证会被禁用。\n- **auth.adminApiKey：** 仅用于 `/admin/*` 路由的单个 admin key。若未配置，服务会在启动时自动生成一个随机 key，并回写到 `config.json`。它同样使用 `x-api-key` 或 `Authorization: Bearer` 这两种头，但普通 `auth.apiKeys` 不能访问 `/admin/*`。\n- **modelMappings：** 用于顶层 `POST /v1/messages`、`POST /v1/messages/count_tokens`、`POST /v1/responses` 和 `POST /v1/chat/completions` 请求的精确 `sourceModel -> targetModel` 重写映射，这几类接口共用同一份规则。省略该字段或保留为 `{}` 时，不会做模型重写。`source` 和 `target` 都必须是非空字符串。`target` 可以是普通模型 ID，也可以是 `provider/model` 形式的别名，例如 `dashscope/qwen3.6-plus`；重写发生在 provider alias 解析之前。这些映射不再按接口区分。`GET/POST /admin/config/model-mappings` 管理接口读写的也只有这个字段。\n- **extraPrompts：** `model -> prompt` 的映射。把 Anthropic 风格请求翻译为 Responses API 时，会将其附加到第一条 system prompt 后面。你可以借此为不同模型注入护栏或指引。缺失的默认项会自动补齐，但不会覆盖你自定义的 prompt。对于 GPT-5.3+ 模型（如 `gpt-5.3-codex`、`gpt-5.4`、`gpt-5.5`），未显式配置时会自动使用内置的 commentary prompt。内置 prompt 会启用带阶段感知的 commentary，让模型在工具调用或更深层推理前先发出简短的用户可见进度说明。\n- **providers：** 全局上游 provider 映射。每个 provider key（例如 `dashscope`）都会变成一个路由前缀（`/dashscope/v1/messages`）。支持 `type: \"anthropic\"`、`type: \"openai-compatible\"` 和 `type: \"openai-responses\"`。顶层客户端也可以在 `/v1/messages`、`/v1/messages/count_tokens`、`/v1/responses` 和 `/v1/chat/completions` 中使用 `model: \"dashscope/model-id\"`；AI gateway 会在转发上游前移除 `dashscope/` 前缀。`openai-compatible` provider 同时支持 chat 和 Messages 流程：`/v1/chat/completions` 会直连上游 `/v1/chat/completions`，而 `/v1/messages` 和 `/:provider/v1/messages` 会先翻译为上游 Chat Completions，再把响应翻译回 Anthropic Messages。`GET /v1/models` 会聚合已启用 provider 的模型，并以 `provider/model-id` 形式返回；单个 provider 的原始模型列表仍可使用 `GET /dashscope/v1/models`。\n  - `enabled`：可选，若省略则默认为 `true`。\n  - `baseUrl`：provider API 的基础 URL，不要带结尾的 endpoint。Anthropic provider 不要带 `/v1/messages`；OpenAI 兼容 provider 不要带 `/v1/chat/completions`；OpenAI Responses provider 不要带 `/v1/responses`。\n  - `apiKey`：作为上游凭据值使用；普通 provider 必须配置。\n  - `authType`：可选，控制 `apiKey` 如何发送到上游。普通 provider 支持 `x-api-key` 和 `authorization`。Anthropic provider 默认 `x-api-key`；OpenAI 兼容和 OpenAI Responses provider 默认 `authorization`。当设置为 `authorization` 时，代理会发送 `Authorization: Bearer <apiKey>`。`oauth2` 仅保留给内置 `codex` provider，并由 `auth login --provider codex` 自动写入。\n  - `pricingCurrency`：可选，provider 维度的 token 费用币种，例如 `USD` 或 `CNY`。快捷 provider 默认 DashScope、DeepSeek 为 `CNY`，Codex/OpenRouter 为 `USD`。费用按币种分别汇总，不做汇率换算。\n  - `models`：可选，按模型 ID 配置的映射。每个键为请求中的模型名，值支持：\n    - `temperature`：可选，当请求未指定时使用的默认温度。\n    - `topP`：可选，当请求未指定时使用的默认 `top_p`。\n    - `topK`：可选，当请求未指定时使用的默认 `top_k`。\n    - `extraBody`：可选，按模型合入上游请求体的动态字段；请求体显式同名字段优先。OpenAI 兼容 provider 可用它配置 `enable_thinking`、`preserve_thinking`、`reasoning_effort` 等字段。`thinking_budget` 是 OpenAI 兼容 provider 的特殊覆盖项：配置在 `extraBody` 后，会在 Anthropic `thinking.budget_tokens` 翻译之后强制写入，并覆盖请求派生出的预算值。对于 provider name 为 `dashscope` 或 `baseUrl` 包含 `aliyuncs.com` 的 provider，请求派生的 `thinking_budget`（来自 Anthropic `thinking.budget_tokens`）会转发给上游；其他 OpenAI 兼容 provider 会移除请求派生的 `thinking_budget`，但 `extraBody` 中的 `thinking_budget` 仍然生效。对于 DashScope provider，当 `preserve_thinking` 未在 `extraBody` 或请求体中显式设置时，默认为 `true`。\n    - `pricing`：可选，按模型配置 token 单价，币种使用 provider 的 `pricingCurrency`，单位为每 100 万 tokens。支持 `input`、`output`、`cachedInput`（隐式缓存读）、`explicitCachedInput`（显式缓存读）和 `cacheCreationInput`。如需按输入 token 总量分档，可用带 `maxInputTokens` 的 `tiers`。\n    - `contextCache`：可选，provider name 为 `dashscope` 或 `baseUrl` 包含 `aliyuncs.com` 时默认 `true`，其他 OpenAI 兼容 provider 默认 `false`。用于启用阿里云百炼/DashScope 的显式缓存（explicit context cache），会按其 Context Cache 格式在最多 4 个 content block 上注入 `cache_control: { \"type\": \"ephemeral\" }`。缓存断点策略与 opencode 主链路保持一致：前 2 条 system 消息 + 最后 2 条非 system 消息。标记字符串 content 时会把 `system` / `user` / `assistant` / `tool` 消息转换为 text content part 数组；已有数组 content 则标记最后一个 part。如果模型本身已经支持隐式缓存，或上游不支持该显式缓存扩展字段，可在模型配置中设为 `false`。支持相同显式缓存扩展的非 DashScope provider 可设为 `true`。同时适用于 `/v1/messages` 和 `/v1/chat/completions` 路由。\n    - `supportPdf`：可选，控制该模型是否支持 PDF/document content。默认 `false`，不支持时会把 PDF 转成提示文本；设为 `true` 时会把 PDF/document 转成 OpenAI Chat Completions 的 file part。\n    - `toolContentSupportType`：可选，配置该模型的 tool result content 支持能力，值为 `array`、`image`、`pdf` 的数组。provider 侧未配置时默认只发送 string tool content。若 `supportPdf` 为 `true` 但这里不包含 `pdf`，tool result 里的 file part 会被转成 user role 消息。Copilot 主链路不使用这个 provider 默认，仍按 array + image 且不支持 PDF 的能力处理。\n    - `type`：可选，按模型覆盖 provider 的协议类型。支持 `anthropic`、`openai-compatible` 和 `openai-responses`。设置后，provider 的 `/v1/messages` 路由会使用该模型的 type 替代 provider 级别的 type 进行请求路由、认证头解析和上游端点选择。适用于 OpenCode Go 等上游对不同模型同时支持 OpenAI 兼容和 Anthropic Messages API 的 provider。覆盖 type 时，认证头按覆盖后 type 的默认值解析（Anthropic 默认 `x-api-key`；OpenAI 兼容/Responses 默认 `authorization`）。\n\n  DashScope 模型配置示例：\n  ```json\n  {\n    \"providers\": {\n      \"dashscope\": {\n        \"type\": \"openai-compatible\",\n        \"enabled\": true,\n        \"baseUrl\": \"https://dashscope.aliyuncs.com/compatible-mode\",\n        \"apiKey\": \"sk-your-dashscope-key\",\n        \"pricingCurrency\": \"CNY\",\n        \"models\": {\n          \"qwen3.7-plus\": {\n            \"temperature\": 1,\n            \"topP\": 0.95,\n            \"topK\": 20,\n            \"extraBody\": {\n              \"preserve_thinking\": true\n            }\n          },\n          \"glm-5.1\": {\n            \"temperature\": 0.7,\n            \"topP\": 0.95,\n            \"contextCache\": true,\n            \"pricing\": {\n              \"tiers\": [\n                {\n                  \"maxInputTokens\": 32000,\n                  \"input\": 6,\n                  \"cachedInput\": 1.2,\n                  \"explicitCachedInput\": 0.6,\n                  \"cacheCreationInput\": 7.5,\n                  \"output\": 24\n                },\n                {\n                  \"maxInputTokens\": 200000,\n                  \"input\": 8,\n                  \"cachedInput\": 1.6,\n                  \"explicitCachedInput\": 0.8,\n                  \"cacheCreationInput\": 10,\n                  \"output\": 28\n                }\n              ]\n            },\n            \"extraBody\": {\n              \"preserve_thinking\": true\n            }\n          }\n        }\n      }\n    }\n  }\n  ```\n  内置 token 价格覆盖 Codex GPT 模型（USD）、DashScope `qwen3.7-max`、`qwen3.7-plus`、`glm-5.1`、`glm-5.2`（CNY），DeepSeek `deepseek-v4-flash`、`deepseek-v4-pro`、`deepseek-chat`、`deepseek-reasoner`（CNY），以及 OpenCode Go 模型（`hy3`、`gpt-5.6-luna`、`glm-5.2`、`grok-4.5`、`deepseek-v4-flash`、`deepseek-v4-pro`、`kimi-k2.7-code`、`kimi-k3`、`mimo-v2.5`、`mimo-v2.5-pro`、`qwen3.7-plus`、`qwen3.7-max`、`minimax-m2.7`、`minimax-m3`，USD）。用户配置的 `pricing` 优先于内置价格。DashScope 若上游 usage 中出现 `cache_creation_input_tokens` 字段，cached tokens 按显式缓存读价计费；否则 `cachedInput` 作为隐式缓存读价。DeepSeek 的 `prompt_cache_hit_tokens` 会归入 cached input，`prompt_cache_miss_tokens` 会归入普通 input。\n- **smallModel：** 无工具预热消息的回退模型（例如 Claude Code 的探测请求）；默认是 `gpt-5-mini`。网关会对无工具的预热或探测请求强制使用该小模型，以避免消耗 premium 请求。该行为仅在 GitHub Copilot 账户为非 token-based 计费时生效（`token_based_billing` 为 false）；对于 token-based 计费账户，预热小模型回退会被跳过，因为不存在需要节省的 premium 请求配额。\n- **contextManagement：** 控制代理是否为 Responses API 附加 `context_management` 压缩指令。`messages` 作用于被翻译成 Responses API 的 Anthropic 风格 `/v1/messages` 请求，包括 `openai-responses` provider 的 Messages 路由，默认值为 `true`。`responses` 作用于 native `/v1/responses` 流量，包括 `provider/model` 别名和内置 `codex` provider，默认值为 `false`。只有在确认客户端支持 context management compaction 后，才建议在 Responses API 下启用 `responses`。启用后，请求体会带上 `context_management`，并在后续轮次中仅保留最新的压缩承载内容。**注意：** 对于 GPT-5.6 及以上模型（如 `gpt-5.6-sol`、`gpt-5.6-terra`、`gpt-5.6-luna`），context management 功能会被强制禁用，因为开启后会破坏这些模型的 prompt 缓存命中。此强制覆盖优先于 `contextManagement` 和 `modelResponsesApiCompactThresholds` 配置。\n - **modelResponsesApiCompactThresholds：** 按模型覆盖 Responses API 的 `compact_threshold`，仅在代理自动附加 `context_management` 时使用。它的优先级高于 `resolveResponsesCompactThreshold` 基于 `max_prompt_tokens * ratio` 的兜底阈值。默认将 `gpt-5.4` 和 `gpt-5.5` 设为 `217600`（`272000 * 0.8`）。未列出的模型继续使用原有兜底逻辑。\n- **modelReasoningEfforts：** `/v1/messages` 请求的模型级默认推理强度。仅当请求没有传入 `output_config.effort` 时，该配置才会生效。\n  - **优先级：** 请求中的 `output_config.effort` > `modelReasoningEfforts[model]` > 内置默认值（GPT-5.3+ 模型为 `xhigh`，其他模型为 `high`）。\n  - **转发字段：** 走 Copilot 原生 Messages API 时，最终值写入 `output_config.effort`；转换为 Responses API 时，最终值写入 `reasoning.effort`。\n  - **配置可选值：** `none`、`minimal`、`low`、`medium`、`high`、`xhigh`、`max`。\n- **useMessagesApi：** 当为 `true` 时，支持 Copilot 原生 `/v1/messages` 的 Claude 系模型会走 Messages API；否则回退到 `/chat/completions`。设为 `false` 可禁用 Messages API 路由，始终使用 `/chat/completions`。默认值为 `true`。\n- **useResponsesApiWebSocket：** 当为 `true` 时，Responses API 请求会优先对声明了 `ws:/responses` 的模型使用 Copilot websocket transport；仅声明 `/responses` 的模型仍走 HTTP。设为 `false` 可禁用 websocket 路由，并在模型支持 `/responses` 时使用 HTTP `/responses`。默认值为 `true`。如果遇到 Responses API WebSocket closed，一般是自己的网络问题。如果使用了 VPN，建议切换节点。\n- **useResponsesApiWebSearch：** 当为 `true` 时，服务端会保留 Responses API 中 `type: \"web_search\"` 的工具并透传到上游。设为 `false` 则会从 `/responses` payload 中移除这些工具。默认值为 `true`。\n- **messageApiWebSearchModel：** 顶层 Copilot `/v1/messages` 请求只包含服务端 `web_search` 工具时使用的全局模型，默认值为 `gpt-5-mini`。如果该值是 `provider/model` 别名，请求会进入对应 provider 的 Messages API 路径，并在转发前移除 provider 前缀。对于 Copilot GPT 模型，web search 会通过 `/responses` 执行。混合 `web_search` 与自定义工具的场景暂不支持，服务端会移除 server-side `web_search`。\n- **claudeAutoModel：** 用于 Claude Code 后台 security-monitor 请求的模型，作用于 `/v1/messages` 和 provider Messages 路由。当请求不带任何工具、`stop_sequences` 为 `[\"</block>\"]`，且 system 文本块以 `You are a security monitor for autonomous AI coding agents.` 开头时，会被识别为 security-monitor 请求，其模型会被替换为该配置值。对于顶层请求，`provider/model` 别名会转发到对应 provider 的 Messages API；对于 provider 路由，则保持当前 provider，直接使用该配置值。默认为空（禁用）。\n- **claudeTokenMultiplier：** 用于 Claude `/v1/messages/count_tokens` 请求在本地走 GPT tokenizer 估算时的乘数。默认值为 `1.15`。如果你的客户端仍然过晚触发上下文压缩，可以适当调大。这个配置只会在代理本地估算 Claude token 时生效；如果已经配置 `anthropicApiKey` 且 Anthropic token counting 调用成功，则会直接返回 Anthropic 的精确计数，不会使用这个乘数。\n- **anthropicApiKey：** 用于把 Claude `/v1/messages/count_tokens` 请求转发到 Anthropic 真实 token counting 端点的 API key，这样会返回精确计数，而不是 GPT tokenizer 估算值。也可通过环境变量 `ANTHROPIC_API_KEY` 设置。若未配置，或上游调用失败，则回退到由 `claudeTokenMultiplier` 控制的本地 GPT tokenizer 估算。\n\n编辑此文件后即可自定义 prompts，或替换为你自己的快速模型。修改完成后请重启服务（或重新执行命令），让缓存中的配置刷新生效。\n\n## API 认证\n\n- **受保护的普通路由：** 当配置了 `auth.apiKeys` 且非空时，除 `/`、`/usage-viewer` 和 `/usage-viewer/` 以外的普通路由都需要认证。\n- **Admin 路由：** 所有 `/admin/*` 路由都要求 `auth.adminApiKey`。如果缺失，服务会在启动时自动生成并在开始提供服务前写回 `config.json`。\n- **允许的认证头：**\n  - `x-api-key: <your_key>`\n  - `Authorization: Bearer <your_key>`\n- **CORS 预检：** `OPTIONS` 请求始终允许。\n- **未配置普通 key 时：** 普通路由仍可直接访问；但这条规则不适用于 `/admin/*`，后者只接受 `auth.adminApiKey`。\n\n普通受保护路由的示例请求：\n\n```sh\ncurl http://localhost:4141/v1/models \\\n  -H \"x-api-key: your_api_key\"\n```\n\nAdmin 路由的示例请求：\n\n```sh\ncurl http://localhost:4141/admin/config/model-mappings \\\n  -H \"x-api-key: your_admin_api_key\"\n```\n\n## API 端点\n\n服务端提供多个 OpenAI / Anthropic 兼容端点。请求会根据所选模型和 `provider/model` 别名路由到 GitHub Copilot、内置 `codex` provider 或已配置的 provider。\n\n### OpenAI 兼容端点\n\n这些端点模拟 OpenAI API 结构。\n\n| 端点 | 方法 | 说明 |\n| --- | --- | --- |\n| `POST /v1/responses` | `POST` | OpenAI 中用于生成模型响应的高级接口。支持 `openai-responses` provider 的 `provider/model` 别名。 |\n| `POST /v1/chat/completions` | `POST` | 为给定聊天对话创建模型响应。支持 `openai-compatible` provider 的 `provider/model` 别名；目标 provider 已配置时可在没有 Copilot 的情况下使用。 |\n| `GET /v1/models` | `GET` | 列出 Copilot 模型以及已启用 provider 的 `provider/model-id` 模型。来自 Codex 客户端（`User-Agent` 以 `codex` 开头）的请求会转发到 Codex Models 上游。 |\n| `POST /v1/embeddings` | `POST` | 创建表示输入文本的向量嵌入。 |\n\n### Codex 后端代理端点\n\n这些端点要求已有可用的 Codex 登录态。每个端点同时提供无版本前缀和 `/v1` 两种路径。\n\n| 端点 | 方法 | 说明 |\n| --- | --- | --- |\n| `POST /alpha/search`<br>`POST /v1/alpha/search` | `POST` | 将 JSON 请求体和查询参数透明转发到 Codex Alpha Search 上游。 |\n| `POST /images/generations`<br>`POST /v1/images/generations` | `POST` | 将 JSON 图片生成请求转发到 Codex Images 上游。请求未携带 `Content-Type` 时，网关默认补充 `application/json`。 |\n| `POST /images/edits`<br>`POST /v1/images/edits` | `POST` | 将图片编辑请求转发到 Codex Images 上游。请使用 `multipart/form-data`，并让 HTTP 客户端自动生成 `boundary`；网关会保留传入的 content type，并以流式方式转发上传请求体。 |\n\n对于以上所有端点，网关都会使用当前 Codex 登录态覆盖客户端的 authorization 和 account header，保留查询参数及兼容的请求头，并返回上游状态码、响应头和响应体。\n\n### Anthropic 兼容端点\n\n这些端点设计为兼容 Anthropic Messages API。provider 级的 models、Responses、alpha-search 和 images 路由同时支持无版本前缀与 `/v1` 两种路径；Messages 路由仍使用 `/v1`。\n\n| 端点 | 方法 | 说明 |\n| --- | --- | --- |\n| `POST /v1/messages` | `POST` | 为给定对话创建模型响应。支持已配置 provider 的 `provider/model` 别名，包括通过 `openai-compatible` provider 做翻译。 |\n| `POST /v1/messages/count_tokens` | `POST` | 计算一组消息的 token 数。支持已配置 provider 的 `provider/model` 别名。 |\n| `POST /:provider/v1/messages` | `POST` | 将 Anthropic Messages 请求代理到已配置的 Anthropic provider，或翻译到 OpenAI 兼容 / OpenAI Responses provider。 |\n| `GET /:provider/models`<br>`GET /:provider/v1/models` | `GET` | 将模型列表请求代理到已配置的 provider。对 `codex` 默认返回内置模型目录；Codex 客户端（`User-Agent` 以 `codex` 开头）会转发到 Codex Models 上游。 |\n| `POST /:provider/v1/messages/count_tokens` | `POST` | 为 provider 路由请求在本地计算 token 数。 |\n| `POST /:provider/responses`<br>`POST /:provider/v1/responses` | `POST` | 将 OpenAI Responses 请求代理到已配置的 `openai-responses` provider（含 `codex`）。 |\n| `POST /:provider/alpha/search`<br>`POST /:provider/v1/alpha/search` | `POST` | 代理 alpha-search 请求。对 `codex` 转发到 Codex Alpha Search 上游；其他 provider 转发到 `{baseUrl}/v1/alpha/search`。 |\n| `POST /:provider/images/generations`<br>`POST /:provider/v1/images/generations` | `POST` | 代理图片生成。对 `codex` 使用 Codex Images 上游；其他 provider 转发到 `{baseUrl}/v1/images/generations`（15 分钟超时）。 |\n| `POST /:provider/images/edits`<br>`POST /:provider/v1/images/edits` | `POST` | 代理图片编辑。对 `codex` 使用 Codex Images 上游；其他 provider 以 multipart/流式方式转发到 `{baseUrl}/v1/images/edits`（15 分钟超时）。 |\n\n### 使用量监控端点\n\n用于监控 Copilot 用量与额度的新端点。\n\n| 端点 | 方法 | 说明 |\n| --- | --- | --- |\n| `GET /usage` | `GET` | 获取详细的 Copilot 使用统计与额度信息。 |\n| `GET /token` | `GET` | 获取当前 API 正在使用的 Copilot token。 |\n\n### Admin / 配置端点\n\n这些端点用于本地管理操作，只接受 `auth.adminApiKey`。\n\n| 端点 | 方法 | 说明 |\n| --- | --- | --- |\n| `GET /admin/config/model-mappings` | `GET` | 返回当前 `config.json` 路径以及生效中的 `modelMappings` 映射。 |\n| `POST /admin/config/model-mappings` | `POST` | 只更新 `config.json` 里的 `modelMappings` 字段，并回传更新后的结果。 |\n\n## 使用示例\n\n常用 `npx` 命令：\n\n```sh\n# 基础启动\nnpx @jeffreycao/copilot-api@latest start\n\n# 自定义端口并开启详细日志\nnpx @jeffreycao/copilot-api@latest start --port 8080 --verbose\n\n# 执行认证流程\nnpx @jeffreycao/copilot-api@latest auth login\n\n# 配置第三方 provider，然后不依赖 GitHub Copilot 启动\nnpx @jeffreycao/copilot-api@latest auth login --provider dashscope\nnpx @jeffreycao/copilot-api@latest start\n\n# 以 JSON 格式输出调试信息\nnpx @jeffreycao/copilot-api@latest debug --json\n\n# 用 Bun 而不是 Node.js 运行已发布 CLI\nbunx --bun @jeffreycao/copilot-api@latest start\n```\n\n配置 `dashscope` 后的 OpenAI 兼容 provider 调用示例：\n\n```sh\ncurl http://localhost:4141/v1/chat/completions \\\n  -H \"content-type: application/json\" \\\n  -d '{\"model\":\"dashscope/qwen3.6-plus\",\"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]}'\n\ncurl http://localhost:4141/dashscope/v1/messages \\\n  -H \"content-type: application/json\" \\\n  -d '{\"model\":\"qwen3.6-plus\",\"max_tokens\":1024,\"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]}'\n```\n\n## 使用建议\n\n<a id=\"claudemd-or-agentsmd-recommended-content\"></a>\n\n### CLAUDE.md 或 AGENTS.md 推荐内容\n\n如果你想手动加入这些提醒，请在 Claude Code 的 `CLAUDE.md`，或 opencode/codex 的 `AGENTS.md` 中加入以下内容：\n\n```\n- Prohibited from directly asking questions to users, MUST use question tool.\n- Once you can confirm that the task is complete, MUST use question tool to make user confirm. The user may respond with feedback if they are not satisfied with the result, which you can use to make improvements and try again, after try again, MUST use question tool to make user confirm again.\n```\n"}, "69601b83760614c5b3edb65a27c7a881a6e3f0e2": {"t": 1785765529.8796773, "n": 34228, "h": "6d45eec12cbf64f2", "c": "# Copilot API Proxy\n\n[English](./README.md) | 简体中文\n\n## 重要说明\n\n> [!IMPORTANT]\n> **使用前请先注意以下几点：**\n>\n> 1. **Claude Code 配置：** 与 Claude Code 搭配使用时，请将模型 ID 配置为 `claude-opus-4-8`。示例 claude `settings.json` 见 [通过 `settings.json` 手动配置](#manual-configuration-with-settingsjson)。\n>\n> 2. **内置 `copilot`、`codex` 与第三方 provider：** 执行 `npx @jeffreycao/copilot-api@latest auth`，可选择 `copilot`、`codex`、`deepseek`、`custom` 等 provider。\n>\n> 3. **注意事项：** README 顶部移除的 GitHub Copilot warning 见 [GitHub Copilot 安全提示](./NOTICE.md#github-copilot-security-notice)。\n\n---\n\n## 项目概览\n\n这是一个小型 AI gateway，可以使用 GitHub Copilot、内置 `codex` provider，也可以使用 DashScope 等已配置的第三方 provider。GitHub Copilot 现在是可选能力：如果本地没有 GitHub token，只要至少配置了一个启用中的 provider，服务仍可按 provider-only 模式启动。\n\nAI gateway 会从同一个本地端点暴露 OpenAI / Anthropic 兼容 API，让 [Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview)、OpenCode、Codex 和 OpenAI 兼容客户端可以共用同一个本地服务。\n\n在 GitHub Copilot 路径上，AI gateway 会在可用时优先使用 Copilot 原生的 Anthropic 风格 Messages API，在重工具调用场景下保留更原生的 Claude 行为。\n\n## 功能特性\n\n- **OpenAI 与 Anthropic 双兼容**：通过 `/v1/responses`、`/v1/chat/completions`、`/v1/models`、`/v1/embeddings` 和 `/v1/messages` 对外暴露同一个本地 AI gateway。\n- **Copilot 可选**：有 GitHub 凭据时可以使用 GitHub Copilot，没有 GitHub 凭据时也可以只依赖已配置的 provider 运行。\n- **同一网关接入 Copilot、`codex` 与第三方 provider**：可统一路由 GitHub Copilot、内置 `codex` provider 和配置好的外部 provider。\n- **第三方 provider 可独立启动**：配置 DashScope、DeepSeek、OpenRouter 或自定义 provider 后，不需要 GitHub Copilot 登录即可启动 AI gateway。\n- **OpenAI 兼容 provider 同时支持 chat 和 Messages API**：`openai-compatible` provider 可通过顶层 `/v1/chat/completions` 搭配 `model: \"provider/model\"` 提供 Chat Completions，也可通过 `/v1/messages` 完成 Anthropic Messages 的请求/响应翻译。\n- **面向 Claude 的更原生 Copilot 路由**：优先使用原生 `/v1/messages`，保留 Claude 风格工具流，支持 Anthropic beta 能力、通过 Responses-capable 模型支持 Claude WebSearch，并保留 subagent / session 标记。\n- **Claude Code 与 OpenCode 集成**：兼容 Claude Code 与 OpenCode，也支持通过 `@ai-sdk/anthropic` 直接作为 Anthropic provider 使用。\n- **灵活的认证与部署选项**：支持交互式登录、直接 token、个人 / Business / Enterprise、GitHub Enterprise、opencode OAuth 和自定义数据目录。\n- **多 provider 路由**：可暴露 `/:provider/...` 路由，也可在顶层 API 上使用 `model: \"provider/model\"`。\n\n## 前置要求\n\n- Bun（>= 1.2.x）\n- 如果要通过 `npx` 运行已发布 CLI，需要 Node.js\n- 只有在使用 GitHub Copilot provider 时，才需要已订阅 Copilot 的 GitHub 账号\n- 如果不使用 GitHub Copilot，需要至少一个已配置 provider 的 API key 或 OAuth 登录\n\n## 安装\n\n安装依赖：\n\n```sh\nbun install\n```\n\n直接从源码启动服务：\n\n```sh\nbun run start start\n```\n\n## 从源码运行\n\n本项目可以通过多种方式从源码运行：\n\n### 开发模式\n\n```sh\nbun run dev start\n```\n\n### 生产模式\n\n```sh\nbun run start start\n```\n\n## 通过 npx 使用\n\n你可以直接用 npx 运行本项目：\n\n> [!IMPORTANT]\n> 通过 `npx` 运行时，token usage 存储会使用 Node 内置的 `node:sqlite` 模块。该能力会在 Node.js >= 22.13.0 时启用；Node.js < 22.13.0 时 CLI 仍可启动，但会禁用 token usage 存储。\n>\n> 如果不升级 Node.js 但仍需要 token usage 存储，可以改用 Bun 运行已发布 CLI：`bunx --bun @jeffreycao/copilot-api@latest start`。\n\n```sh\nnpx @jeffreycao/copilot-api@latest start\n```\n\n带参数示例：\n\n```sh\nnpx @jeffreycao/copilot-api@latest start --port 8080\n```\n\n如果只想做认证或 provider 配置：\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth\n```\n\n如果要不依赖 GitHub Copilot 运行，先配置至少一个 provider，然后正常启动服务：\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth login --provider dashscope\nnpx @jeffreycao/copilot-api@latest start\n```\n\n## 配合 Docker 使用\n\n构建镜像：\n\n```sh\ndocker build -t copilot-api .\n```\n\n通过 bind mount 运行容器，让认证数据在重启后保留：\n\n```sh\nmkdir -p ./copilot-data\ndocker run -p 4141:4141 -v $(pwd)/copilot-data:/root/.local/share/copilot-api copilot-api\n```\n\n这会把宿主机上的 `./copilot-data` 映射到容器内的 `/root/.local/share/copilot-api`，用于持久化 GitHub 认证数据、provider 配置和其他 gateway 状态。\n\n也可以直接通过环境变量传入 GitHub token：\n\n```sh\ndocker run -p 4141:4141 -e GH_TOKEN=your_github_token_here copilot-api\n```\n\n## Electron 桌面应用\n\n如果你更喜欢图形界面，仓库里还提供了位于 `desktop/` 的 Electron 桌面应用。它支持 GitHub Copilot 登录、OpenAI Codex OAuth，以及 DeepSeek、DashScope、OpenRouter 或自定义 provider 的 API Key 配置。授权或配置 provider 后，可以一键启动或停止本地代理，并在界面里直接查看本地端点、鉴权 Header、可用模型、额度和日志。\n\n设置页还可以配置 `OAuth App`、`API Home`、`Enterprise URL`、详细日志以及最小化到托盘。Windows x64（`.exe`）、macOS Apple Silicon（`.dmg`）和 Linux x64（`.AppImage`）安装包发布在 GitHub Releases：\n\nhttps://github.com/caozhiyuan/copilot-api/releases\n\nLinux 用户需要先为下载的 AppImage 添加执行权限：\n\n```sh\nchmod +x Copilot-API-*-linux-x86_64.AppImage\n./Copilot-API-*-linux-x86_64.AppImage\n```\n\n下载对应平台的安装包后，在应用内授权或配置 provider，选择端口并启动服务，再把你的客户端指向应用里显示的本地端点即可。发布版桌面应用使用随包内置的 Electron 运行时，正常使用不需要额外安装 Node.js；token usage 历史记录会在该内置运行时支持 SQLite 时启用。\n\n桌面应用里的高级配置页会通过 `GET/POST /admin/config/model-mappings` 读写这份共享的模型映射。同一份映射会统一作用于 `POST /v1/messages`、`POST /v1/messages/count_tokens`、`POST /v1/responses` 和 `POST /v1/chat/completions`，不再按接口区分。它使用的是 `auth.adminApiKey`，不是普通的 `auth.apiKeys`；应用会在服务启动并自动生成该 key 后，直接从 `config.json` 读取它来发起请求。\n\n### 桌面应用截图\n\n下面展示了桌面应用中的首页、Token 用量统计页面：\n\n<p align=\"center\">\n  <img src=\"./docs/screenshots/desktop-dashboard.png\" alt=\"Copilot API 桌面应用首页\" width=\"49%\" />\n  <img src=\"./docs/screenshots/desktop-token-usage.png\" alt=\"Copilot API 桌面应用 Token 用量页\" width=\"49%\" />\n</p>\n\n## 与 Claude Code 一起使用\n\n这个 AI gateway 可以为 [Claude Code](https://docs.anthropic.com/en/claude-code) 提供后端能力。Claude Code 是 Anthropic 提供的实验性面向开发者的对话式 AI 助手。\n\n有两种方式可以把 Claude Code 配置为使用这个 AI gateway：\n\n### 通过 `--claude-code` 标志进行交互式配置\n\n执行带 `--claude-code` 的 `start` 命令开始：\n\n```sh\nnpx @jeffreycao/copilot-api@latest start --claude-code\n```\n\n你不再需要手动选择模型。Gateway 会自动检测每个 Claude Code 尺寸档位对应的最新可用模型——opus 映射到最新的 Opus 模型，sonnet 映射到最新的 Sonnet 模型，haiku 映射到最新的 Haiku 模型——并生成相应设置 `ANTHROPIC_DEFAULT_OPUS_MODEL`、`ANTHROPIC_DEFAULT_SONNET_MODEL` 和 `ANTHROPIC_DEFAULT_HAIKU_MODEL` 的命令。若某个档位没有匹配的可用模型，则会被省略。该命令会被复制到剪贴板，并设置 Claude Code 使用这个 AI gateway 所需的环境变量。\n\n在新的终端中粘贴并执行这条命令，即可启动 Claude Code。\n\n<a id=\"manual-configuration-with-settingsjson\"></a>\n\n### 通过 `settings.json` 手动配置\n\n另一种方式是在项目根目录中创建 `.claude/settings.json` 文件，并写入 Claude Code 所需的环境变量。这样你就不需要每次都运行交互式配置了。\n\n下面是一个 `.claude/settings.json` 示例：\n\n```json\n{\n  \"env\": {\n    \"ANTHROPIC_BASE_URL\": \"http://localhost:4141\",\n    \"ANTHROPIC_AUTH_TOKEN\": \"dummy\",\n    \"ANTHROPIC_MODEL\": \"gpt-5.6-sol[1m]\",\n    \"ANTHROPIC_DEFAULT_OPUS_MODEL\": \"gpt-5.6-sol[1m]\",\n    \"ANTHROPIC_DEFAULT_SONNET_MODEL\": \"gpt-5.6-sol[1m]\",\n    \"ANTHROPIC_DEFAULT_HAIKU_MODEL\": \"gpt-5.6-luna[1m]\",\n    \"CLAUDE_CODE_AUTO_COMPACT_WINDOW\": \"272000\",\n    \"CLAUDE_CODE_USE_VERTEX\": \"0\",\n    \"CLAUDE_CODE_USE_BEDROCK\": \"0\",\n    \"DISABLE_NON_ESSENTIAL_MODEL_CALLS\": \"1\",\n    \"CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC\": \"1\",\n    \"CLAUDE_CODE_ATTRIBUTION_HEADER\": \"0\",\n    \"CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION\": \"false\",\n    \"CLAUDE_CODE_DISABLE_TERMINAL_TITLE\": \"true\",\n    \"CLAUDE_CODE_ENABLE_AWAY_SUMMARY\": \"0\"\n  },\n  \"alwaysThinkingEnabled\": true,\n  \"effortLevel\": \"xhigh\",\n  \"showThinkingSummaries\": true\n}\n```\n\n- 请根据需要替换 `ANTHROPIC_MODEL`、`ANTHROPIC_DEFAULT_OPUS_MODEL`、`ANTHROPIC_DEFAULT_SONNET_MODEL` 和 `ANTHROPIC_DEFAULT_HAIKU_MODEL`。配置完成后，请安装 claude code 插件，见 [插件集成](#plugin-integrations)。\n- 如果你使用的是 codex provider，建议**不要**将模型名配置成 `codex/xxx` 格式（如 `codex/gpt-5.6-sol`）。Claude Code 会针对 `codex/` 前缀做降智行为——例如每次请求时移除所有之前返回的思考块（thinking blocks）。请使用纯模型名（如 `gpt-5.6-sol`），并在 `config.json` 中配置 `modelMappings` 将其映射回 codex provider：\n  ```json\n  \"modelMappings\": {\n    \"gpt-5.6-sol\": \"codex/gpt-5.6-sol\",\n    \"gpt-5.6-terra\": \"codex/gpt-5.6-terra\",\n    \"gpt-5.6-luna\": \"codex/gpt-5.6-luna\"\n  },\n  ```\n- 将 `CLAUDE_CODE_ATTRIBUTION_HEADER` 设为 `0` 可以阻止 Claude Code 在 system prompt 中附加计费和版本信息，从而避免 prompt cache 失效。\n- 关闭 `CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION` 和 `CLAUDE_CODE_ENABLE_AWAY_SUMMARY` 可以避免不必要地消耗额度。\n- Claude Code WebSearch 已支持纯搜索请求。Copilot 路径请保持全局 `messageApiWebSearchModel` 指向 Responses-capable GPT 模型或 `provider/model` 别名；provider 路由请使用原生 Anthropic provider 或 `openai-responses` provider。只有在你明确想禁止这类流量时，才需要把 `WebSearch` 加到 `permissions.deny`。\n- 如果使用的不是 Claude 模型，请不要启用 `ENABLE_TOOL_SEARCH`。如果使用的是 Claude 模型，则可以启用 `ENABLE_TOOL_SEARCH`。当前 Claude Code 使用的是客户端 tool search 模式，在该模式下每次加载 defer tools 都需要额外请求一次。\n- `CLAUDE_CODE_AUTO_COMPACT_WINDOW`：设置用于自动压缩计算的上下文容量（以 token 为单位）。默认使用模型自身的上下文窗口：标准模型为 200K，扩展上下文模型为 1M。使用 1M 上下文模型（如 `claude-opus-4-6[1m]`）时，可设置一个较低的值（如 `500000`）将窗口视为 500K 用于压缩计算。该值受限于模型的实际上下文窗口上限。`CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` 会基于此值的百分比生效。设置此变量可将压缩阈值与状态栏的 `used_percentage` 解耦（后者始终使用模型的完整上下文窗口）。\n\n更多选项见：[Claude Code settings](https://docs.anthropic.com/en/docs/claude-code/settings#environment-variables)\n\n也可以参考 IDE 集成说明：[Add Claude Code to your IDE](https://docs.anthropic.com/en/docs/claude-code/ide-integrations)\n\n## 与 OpenCode 一起使用\n\nOpenCode 已经有直接的 GitHub Copilot provider。本节适用于你希望让 OpenCode 通过 `@ai-sdk/anthropic` 指向这个 AI gateway，并复用本 README 前面提到的 agent 行为时。\n\n### 最小配置\n\n使用 OpenCode OAuth app 启动 AI gateway：\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth --oauth-app=opencode\nnpx @jeffreycao/copilot-api@latest start\n```\n\n然后让 OpenCode 通过 `@ai-sdk/anthropic` 指向这个 AI gateway。\n\n示例 `~/.config/opencode/opencode.json`：\n\n```json\n{\n  \"$schema\": \"https://opencode.ai/config.json\",\n  \"provider\": {\n    \"local\": {\n      \"npm\": \"@ai-sdk/anthropic\",\n      \"name\": \"My Local\",\n      \"options\": {\n        \"baseURL\": \"http://localhost:4141/v1\",\n        \"apiKey\": \"dummy\"\n      },\n      \"models\": {\n        \"gpt-5.4\": {\n          \"name\": \"gpt-5.4\",\n          \"modalities\": {\n            \"input\": [\"text\", \"image\"],\n            \"output\": [\"text\"]\n          },\n          \"limit\": {\n            \"context\": 400000,\n            \"input\": 272000,\n            \"output\": 128000\n          }\n        },\n        \"claude-sonnet-4.6\": {\n          \"id\": \"claude-sonnet-4.6\",\n          \"name\": \"claude-sonnet-4.6\",\n          \"modalities\": {\n            \"input\": [\"text\", \"image\"],\n            \"output\": [\"text\"]\n          },\n          \"limit\": {\n            \"context\": 200000,\n            \"output\": 32000\n          },\n          \"options\": {\n            \"thinking\": {\n              \"type\": \"adaptive\"\n            },\n            \"effort\": \"max\"\n          }\n        }\n      }\n    }\n  }\n}\n```\n\n这些字段的重要性：\n\n- `npm: \"@ai-sdk/anthropic\"` 是关键。OpenCode 会以 Anthropic Messages 语义与这个 AI gateway 通信，而不是把一切扁平化为 OpenAI Chat Completions。\n- `options.baseURL` 应设为 `http://localhost:4141/v1`；Anthropic SDK 会自动补上 `/messages`、`/models` 和 `/messages/count_tokens`。\n- 如果你在此代理中启用了 `auth.apiKeys`，请把 `dummy` 替换为真实 key；否则任意占位值都可以。\n\n## 与 Codex 一起使用\n\n这个 AI gateway 也可以为 Codex 提供后端能力。\n\n### Codex `config.toml` 参考配置\n\n把以下 `[model_providers.copilot_api]` 段加入你的 Codex `~/.codex/config.toml`：\n\n```toml\nmodel_provider = \"copilot_api\"\nmodel_reasoning_summary = \"auto\"\nmodel_context_window = 272000\nmodel_auto_compact_token_limit = 244800\n\n[model_providers.copilot_api]\nname = \"OpenAI\"\nbase_url = \"http://localhost:4141\"\nenv_key = \"GITHUB_COPILOT_API_KEY\"\nrequires_openai_auth = true\nsupports_websockets = false\nwire_api = \"responses\"\nrequest_max_retries = 3\nstream_max_retries = 1\nstream_idle_timeout_ms = 300000\n\n[features]\nremote_compaction_v2 = true\n\n[analytics]\nenabled = false\n```\n\n> [!NOTE]\n> 此配置仅限于 Codex 与 GitHub Copilot provider。`name` 一定要配置为 `\"OpenAI\"`。它可以缓解 Codex local compact 不命中缓存的问题。\n> 如果使用 codex provider，建议将 `base_url` 配置为 `\"http://localhost:4141/codex\"`。\n\n## GPT Tool Search\n\n对于 `gpt-5.4+` 这类 GPT Responses 模型，这个 AI gateway 可以通过一个很小的 MCP bridge 暴露 Responses `tool_search`。Claude Code 和 opencode 都可以使用同一个 bridge，前提是客户端会加载 MCP server，并且 Anthropic Messages 流量会经过这个 AI gateway。\n\nGPT 模型不要设置 Claude Code 原生的 `ENABLE_TOOL_SEARCH`。这个开关启用的是 Claude Code 自己的客户端 tool search 模式，可能导致 deferred 工具定义不再转发给 AI gateway。这个 AI gateway 需要完整的工具定义，这样才能只保留那一小组常驻加载工具，其余工具统一转换为 Responses deferred namespace。\n\n如果你安装了 `tool-search@copilot-api-marketplace`，Claude Code 会自动带上这个 MCP bridge，可以跳过下面这段 Claude Code MCP 手动配置。\n\n请把 tool search bridge 加到 Claude Code 使用的 MCP 配置中：\n\n```json\n{\n  \"mcpServers\": {\n    \"tool_search\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@jeffreycao/copilot-api@latest\", \"mcp\"]\n    }\n  }\n}\n```\n\n请把 tool search bridge 加到 opencode 使用的 MCP 配置中：\n\n```json\n{\n  \"mcp\": {\n    \"tool_search\": {\n      \"type\": \"local\",\n      \"command\": [\"npx\", \"-y\", \"@jeffreycao/copilot-api@latest\", \"mcp\"]\n    }\n  }\n}\n```\n\n本地开发时可以将命令换成 `bun`，参数换成 `[\"run\", \"./src/main.ts\", \"mcp\"]`。\n\nAI gateway 内部现在会把 OpenAI Responses `tool_search` 配置成 client-executed 模式。deferred tools 仍然会作为可搜索 namespace 暴露给模型，但会明确要求模型直接返回下一步要加载的精确工具名列表。\n\n该 bridge 使用直接工具选择，不做 query 搜索。工具入参是 `names`，值为逗号分隔的精确 deferred 工具名，例如 `TaskList,TaskGet,mcp__fetch__fetch`。\n\n<a id=\"plugin-integrations\"></a>\n\n## 插件集成\n\n本项目为 Claude Code 和 opencode 提供了插件集成。\n\n#### Claude Code 插件集成（基于 marketplace）\n\nClaude Code 集成现在拆分为两个插件：\n\n- `agent-inject` 会在 `SubagentStart` 时注入 `__SUBAGENT_MARKER__...`，以便 AI gateway 推导 `x-initiator: agent`。\n- `tool-search` 会注册用于 GPT Responses deferred tool loading 的 `tool_search` MCP bridge。\n\n- 本仓库中的 marketplace catalog：`.claude-plugin/marketplace.json`\n- 本仓库中的插件源码：`plugin/claude/agent-inject`、`plugin/claude/tool-search`\n\n远程添加 marketplace：\n\n```sh\n/plugin marketplace add https://github.com/caozhiyuan/copilot-api.git\n```\n\n从 marketplace 安装插件：\n\n```sh\n/plugin install agent-inject@copilot-api-marketplace\n/plugin install tool-search@copilot-api-marketplace\n```\n\n安装后，`agent-inject` 会在 `SubagentStart` 时注入 `__SUBAGENT_MARKER__...`，AI gateway 会利用它推导 `x-initiator: agent`。\n\n`agent-inject` 还会注册一个 `UserPromptSubmit` hook，并返回 `{\"continue\": true}`；同时它也可以通过环境变量注入 `SessionStart` reminder 规则：\n\n- `CLAUDE_PLUGIN_ENABLE_QUESTION_RULES=1` 会自动为 Claude Code 启用两条关于使用 `question` 工具的提醒。你也可以把同样的提醒手动写进 `CLAUDE.md`；见 [CLAUDE.md 或 AGENTS.md 推荐内容](#claudemd-or-agentsmd-recommended-content)。\n- `CLAUDE_PLUGIN_ENABLE_NO_BACKGROUND_AGENTS_RULE=1` 会启用关于避免在 agent hooks 中使用 `run_in_background: true` 的提醒。\n\n`tool-search` 插件内置了 [GPT Tool Search](#gpt-tool-search) 一节描述的同一个 MCP bridge，因此安装该插件后，Claude Code 用户无需再手动配置 `tool_search` server。\n\n#### Opencode 插件\n\nsubagent 标记生成器被打包为一个 opencode 插件，位于 `plugin/opencode/subagent-marker.js`。\n\n**安装方式：**\n\n将插件文件复制到你的 opencode 插件目录：\n\n```sh\n# 克隆或下载本仓库后复制该插件\ncp plugin/opencode/subagent-marker.js ~/.config/opencode/plugins/\n```\n\n或者手动在 `~/.config/opencode/plugins/subagent-marker.js` 创建该文件，并填入插件内容。\n\n**功能：**\n\n- 跟踪 subagent 创建的子会话\n- 自动在 subagent 聊天消息前添加 marker system reminder（`__SUBAGENT_MARKER__...`）\n- 设置 `x-session-id` 请求头以跟踪会话\n- 让这个 AI gateway 能够把来自 subagent 的请求识别为 `x-initiator: agent`\n\n该插件会挂接到 `session.created`、`session.deleted`、`chat.message` 和 `chat.headers` 事件上，以无缝提供 subagent marker 能力。\n\n## 使用量查看器\n\n服务启动后，控制台会输出一个 Copilot 使用量看板 URL。这个看板是一个用于监控 API 用量的 Web 界面。\n\n1. 启动服务。例如使用 npx：\n   ```sh\n   npx @jeffreycao/copilot-api@latest start\n   ```\n2. 服务会输出一个 usage viewer 的 URL。将它复制到浏览器中打开，形式大致如下：\n   `http://localhost:4141/usage-viewer?endpoint=http://localhost:4141/usage`\n   - 如果你在 Windows 上使用 `start.bat` 脚本，这个页面会自动打开。\n\n看板提供了更易读的 Copilot 用量视图：\n\n> token usage 历史记录需要 Bun 或 Node.js >= 22.13.0。Node.js < 22.13.0 时服务会正常运行，但 token usage 存储会被禁用。\n\n- **API Endpoint URL**：通过 URL 查询参数指定 API endpoints，默认指向本地服务。支持手动切换为其他兼容 endpoints。\n- **x-api-key 认证**：如果启用了 API Key 认证，可填入 `x-api-key` 请求头。密钥会持久化保存在浏览器本地存储中。\n- **Period 选择器**：支持 Day / Week / Month 三种时间范围，切换时 URL 参数会自动同步，方便收藏和分享。\n- **Fetch Data**：点击 \"Refresh\" 按钮加载或刷新使用数据。页面加载时也会自动拉取数据。\n- **Copilot Quotas 额度**：通过进度条展示 Chat、Completions 等不同服务的额度使用情况，悬停可查看已用/剩余详情。\n- **Token Usage 指标卡片**：汇总当前周期的 Total、Input、Output、Cache Read、Cache Write、Requests 和预估费用。\n- **趋势图（Week / Month）**：提供按模型和指标筛选的折线趋势图，点击数据点可查看单日用量明细。\n- **Model Breakdown 表格**：按模型维度列出周期内的请求数、输入/输出/缓存 token 和预计费用。\n- **Request Events 分页列表**：按时间排序的请求事件记录，支持分页浏览，含时间戳、模型、请求 ID 和 token 用量。\n- **Detailed Information**：展示 API 返回的完整 JSON 响应，便于深入分析所有可用统计数据。\n- **URL-based Configuration**：也可通过 `endpoint` 和 `period` 查询参数直接指定 API 端点与时间范围。例如：\n  `http://localhost:4141/usage-viewer?endpoint=http://your-api-server/usage&period=week`\n\n### Usage Viewer 截图\n\n<p align=\"center\">\n  <img src=\"./docs/screenshots/usage-viewer.png\" alt=\"Copilot API Usage Viewer 页面\" width=\"900\" />\n</p>\n\n## 命令结构\n\nCopilot API 现在使用子命令结构，主要命令包括：\n\n- `start`：启动 AI gateway 服务。如果已有 GitHub token，则启用 Copilot 路径；如果没有 GitHub token，但存在至少一个启用中的 provider，则按 provider-only 模式启动；如果两者都没有，会引导你配置 provider。\n- `auth`：仅执行 provider 登录或配置流程，不启动服务。可用于 GitHub Copilot 登录、Codex OAuth，或第三方 provider API key 配置。\n- `debug`：显示诊断信息，包括版本、运行时详情、文件路径以及认证状态，便于排障与支持。\n\n## 命令行选项\n\n### 全局选项\n\n以下选项可用于任意子命令。若在子命令之前传入，请使用 `--key=value` 形式：\n\n| 选项 | 说明 | 默认值 | 别名 |\n| --- | --- | --- | --- |\n| --api-home | API home 目录路径（设置 `COPILOT_API_HOME`） | 无 | 无 |\n| --oauth-app | OAuth app 标识符（设置 `COPILOT_API_OAUTH_APP`） | 无 | 无 |\n| --enterprise-url | GitHub Enterprise URL（设置 `COPILOT_API_ENTERPRISE_URL`） | 无 | 无 |\n\n### Start 命令选项\n\n以下是 `start` 命令可用的命令行选项：\n\n| 选项 | 说明 | 默认值 | 别名 |\n| --- | --- | --- | --- |\n| --port | 监听端口 | 4141 | -p |\n| --verbose | 启用详细日志 | false | -v |\n| --github-token | 直接提供 GitHub token（必须通过 `auth` 子命令生成） | 无 | -g |\n| --claude-code | 生成一个使用 Copilot API 配置启动 Claude Code 的命令 | false | -c |\n| --show-token | 在获取和刷新时显示 GitHub 与 Copilot token | false | 无 |\n| --proxy-env | 从环境变量初始化代理 | false | 无 |\n\n### Auth 命令选项\n\n| 选项 | 说明 | 默认值 | 别名 |\n| --- | --- | --- | --- |\n| --provider | 要登录或配置的 provider（`copilot`、`codex`、`opencode-go`、`deepseek`、`dashscope`、`openrouter` 或 `custom`） | 交互选择 | 无 |\n| --verbose | 启用详细日志 | false | -v |\n| --show-token | 认证时显示 GitHub token | false | 无 |\n\n只有在需要启用 GitHub Copilot provider 时，才需要执行 `copilot-api auth login --provider copilot`。使用 `codex` 或第三方 provider-only 模式不要求配置 Copilot。\n\n使用 `copilot-api auth login --provider deepseek`、`--provider dashscope`、`--provider openrouter` 或 `--provider opencode-go` 可以通过 CLI 快速新增或更新这些常用第三方 provider。DeepSeek 会提示输入掩码显示的 `apiKey`、provider `type`（默认 `anthropic`），以及默认 `https://api.deepseek.com/anthropic` 的 `baseUrl`。DashScope 会提示输入掩码显示的 `apiKey`、provider `type`（默认 `openai-compatible`）和预填默认值的 `baseUrl`。OpenRouter 只提示输入掩码显示的 `apiKey` 和预填默认值的 `baseUrl`，并固定写入 `type: \"anthropic\"`。OpenCode Go 只提示输入掩码显示的 `apiKey` 和预填默认值的 `baseUrl`，并固定写入 `type: \"openai-compatible\"`（baseUrl `https://opencode.ai/zen/go`）。此外，OpenCode Go 内置将 `qwen*` 和 `minimax*` 模型路由到 Anthropic Messages，将 `gpt*` 模型路由到 OpenAI Responses，其他模型仍默认使用 OpenAI 兼容协议。配置并启用 provider 后，`copilot-api start` 可在没有 GitHub token 的情况下启动。\n\n使用 `copilot-api auth login --provider custom` 可以通过 CLI 新增或更新其他第三方 provider。命令会依次提示输入 provider name、项目支持的 type（`anthropic`、`openai-compatible` 或 `openai-responses`）、`baseUrl`、掩码显示的 `apiKey` 和 `authType`；`authType` 可保持 type 默认值，也可选择 `x-api-key` / `authorization`。\n\n### Debug 命令选项\n\n| 选项 | 说明 | 默认值 | 别名 |\n| --- | --- | --- | --- |\n| --json | 以 JSON 输出调试信息 | false | 无 |\n\n<a id=\"configuration-configjson\"></a>\n\n## 配置（config.json）\n\n- **位置：** Linux/macOS 为 `~/.local/share/copilot-api/config.json`，Windows 为 `%USERPROFILE%\\.local\\share\\copilot-api\\config.json`。\n- **默认结构：**\n  ```json\n  {\n    \"auth\": {\n      \"apiKeys\": [],\n      \"adminApiKey\": \"<startup 自动生成>\"\n    },\n    \"providers\": {},\n    \"modelMappings\": {},\n    \"extraPrompts\": {\n      \"gpt-5-mini\": \"<built-in exploration prompt>\"\n    },\n    \"smallModel\": \"gpt-5-mini\",\n    \"contextManagement\": {\n      \"messages\": true,\n      \"responses\": false\n    },\n    \"modelResponsesApiCompactThresholds\": {\n      \"gpt-5.4\": 217600,\n      \"gpt-5.5\": 217600\n    },\n    \"modelReasoningEfforts\": {\n      \"gpt-5-mini\": \"low\"\n    },\n    \"useMessagesApi\": true,\n    \"useResponsesApiWebSocket\": true,\n    \"useResponsesApiWebSearch\": true,\n    \"messageApiWebSearchModel\": \"gpt-5-mini\"\n  }\n  ```\n- **auth.apiKeys：** 用于普通非 admin 路由的 API key。支持多个 key 轮换使用。请求可通过 `x-api-key: <key>` 或 `Authorization: Bearer <key>` 进行认证。若为空或省略，则普通路由的认证会被禁用。\n- **auth.adminApiKey：** 仅用于 `/admin/*` 路由的单个 admin key。若未配置，服务会在启动时自动生成一个随机 key，并回写到 `config.json`。它同样使用 `x-api-key` 或 `Authorization: Bearer` 这两种头，但普通 `auth.apiKeys` 不能访问 `/admin/*`。\n- **modelMappings：** 用于顶层 `POST /v1/messages`、`POST /v1/messages/count_tokens`、`POST /v1/responses` 和 `POST /v1/chat/completions` 请求的精确 `sourceModel -> targetModel` 重写映射，这几类接口共用同一份规则。省略该字段或保留为 `{}` 时，不会做模型重写。`source` 和 `target` 都必须是非空字符串。`target` 可以是普通模型 ID，也可以是 `provider/model` 形式的别名，例如 `dashscope/qwen3.6-plus`；重写发生在 provider alias 解析之前。这些映射不再按接口区分。`GET/POST /admin/config/model-mappings` 管理接口读写的也只有这个字段。\n- **extraPrompts：** `model -> prompt` 的映射。把 Anthropic 风格请求翻译为 Responses API 时，会将其附加到第一条 system prompt 后面。你可以借此为不同模型注入护栏或指引。缺失的默认项会自动补齐，但不会覆盖你自定义的 prompt。对于 GPT-5.3+ 模型（如 `gpt-5.3-codex`、`gpt-5.4`、`gpt-5.5`），未显式配置时会自动使用内置的 commentary prompt。内置 prompt 会启用带阶段感知的 commentary，让模型在工具调用或更深层推理前先发出简短的用户可见进度说明。\n- **providers：** 全局上游 provider 映射。每个 provider key（例如 `dashscope`）都会变成一个路由前缀（`/dashscope/v1/messages`）。支持 `type: \"anthropic\"`、`type: \"openai-compatible\"` 和 `type: \"openai-responses\"`。顶层客户端也可以在 `/v1/messages`、`/v1/messages/count_tokens`、`/v1/responses` 和 `/v1/chat/completions` 中使用 `model: \"dashscope/model-id\"`；AI gateway 会在转发上游前移除 `dashscope/` 前缀。`openai-compatible` provider 同时支持 chat 和 Messages 流程：`/v1/chat/completions` 会直连上游 `/v1/chat/completions`，而 `/v1/messages` 和 `/:provider/v1/messages` 会先翻译为上游 Chat Completions，再把响应翻译回 Anthropic Messages。`GET /v1/models` 会聚合已启用 provider 的模型，并以 `provider/model-id` 形式返回；单个 provider 的原始模型列表仍可使用 `GET /dashscope/v1/models`。\n  - `enabled`：可选，若省略则默认为 `true`。\n  - `baseUrl`：provider API 的基础 URL，不要带结尾的 endpoint。Anthropic provider 不要带 `/v1/messages`；OpenAI 兼容 provider 不要带 `/v1/chat/completions`；OpenAI Responses provider 不要带 `/v1/responses`。\n  - `apiKey`：作为上游凭据值使用；普通 provider 必须配置。\n  - `authType`：可选，控制 `apiKey` 如何发送到上游。普通 provider 支持 `x-api-key` 和 `authorization`。Anthropic provider 默认 `x-api-key`；OpenAI 兼容和 OpenAI Responses provider 默认 `authorization`。当设置为 `authorization` 时，代理会发送 `Authorization: Bearer <apiKey>`。`oauth2` 仅保留给内置 `codex` provider，并由 `auth login --provider codex` 自动写入。\n  - `pricingCurrency`：可选，provider 维度的 token 费用币种，例如 `USD` 或 `CNY`。快捷 provider 默认 DashScope、DeepSeek 为 `CNY`，Codex/OpenRouter 为 `USD`。费用按币种分别汇总，不做汇率换算。\n  - `models`：可选，按模型 ID 配置的映射。每个键为请求中的模型名，值支持：\n    - `temperature`：可选，当请求未指定时使用的默认温度。\n    - `topP`：可选，当请求未指定时使用的默认 `top_p`。\n    - `topK`：可选，当请求未指定时使用的默认 `top_k`。\n    - `extraBody`：可选，按模型合入上游请求体的动态字段；请求体显式同名字段优先。OpenAI 兼容 provider 可用它配置 `enable_thinking`、`preserve_thinking`、`reasoning_effort` 等字段。`thinking_budget` 是 OpenAI 兼容 provider 的特殊覆盖项：配置在 `extraBody` 后，会在 Anthropic `thinking.budget_tokens` 翻译之后强制写入，并覆盖请求派生出的预算值。对于 provider name 为 `dashscope` 或 `baseUrl` 包含 `aliyuncs.com` 的 provider，请求派生的 `thinking_budget`（来自 Anthropic `thinking.budget_tokens`）会转发给上游；其他 OpenAI 兼容 provider 会移除请求派生的 `thinking_budget`，但 `extraBody` 中的 `thinking_budget` 仍然生效。对于 DashScope provider，当 `preserve_thinking` 未在 `extraBody` 或请求体中显式设置时，默认为 `true`。\n    - `pricing`：可选，按模型配置 token 单价，币种使用 provider 的 `pricingCurrency`，单位为每 100 万 tokens。支持 `input`、`output`、`cachedInput`（隐式缓存读）、`explicitCachedInput`（显式缓存读）和 `cacheCreationInput`。如需按输入 token 总量分档，可用带 `maxInputTokens` 的 `tiers`。\n    - `contextCache`：可选，provider name 为 `dashscope` 或 `baseUrl` 包含 `aliyuncs.com` 时默认 `true`，其他 OpenAI 兼容 provider 默认 `false`。用于启用阿里云百炼/DashScope 的显式缓存（explicit context cache），会按其 Context Cache 格式在最多 4 个 content block 上注入 `cache_control: { \"type\": \"ephemeral\" }`。缓存断点策略与 opencode 主链路保持一致：前 2 条 system 消息 + 最后 2 条非 system 消息。标记字符串 content 时会把 `system` / `user` / `assistant` / `tool` 消息转换为 text content part 数组；已有数组 content 则标记最后一个 part。如果模型本身已经支持隐式缓存，或上游不支持该显式缓存扩展字段，可在模型配置中设为 `false`。支持相同显式缓存扩展的非 DashScope provider 可设为 `true`。同时适用于 `/v1/messages` 和 `/v1/chat/completions` 路由。\n    - `supportPdf`：可选，控制该模型是否支持 PDF/document content。默认 `false`，不支持时会把 PDF 转成提示文本；设为 `true` 时会把 PDF/document 转成 OpenAI Chat Completions 的 file part。\n    - `toolContentSupportType`：可选，配置该模型的 tool result content 支持能力，值为 `array`、`image`、`pdf` 的数组。provider 侧未配置时默认只发送 string tool content。若 `supportPdf` 为 `true` 但这里不包含 `pdf`，tool result 里的 file part 会被转成 user role 消息。Copilot 主链路不使用这个 provider 默认，仍按 array + image 且不支持 PDF 的能力处理。\n    - `type`：可选，按模型覆盖 provider 的协议类型。支持 `anthropic`、`openai-compatible` 和 `openai-responses`。设置后，provider 的 `/v1/messages` 路由会使用该模型的 type 替代 provider 级别的 type 进行请求路由、认证头解析和上游端点选择。适用于 OpenCode Go 等上游对不同模型同时支持 OpenAI 兼容和 Anthropic Messages API 的 provider。覆盖 type 时，认证头按覆盖后 type 的默认值解析（Anthropic 默认 `x-api-key`；OpenAI 兼容/Responses 默认 `authorization`）。\n\n  DashScope 模型配置示例：\n  ```json\n  {\n    \"providers\": {\n      \"dashscope\": {\n        \"type\": \"openai-compatible\",\n        \"enabled\": true,\n        \"baseUrl\": \"https://dashscope.aliyuncs.com/compatible-mode\",\n        \"apiKey\": \"sk-your-dashscope-key\",\n        \"pricingCurrency\": \"CNY\",\n        \"models\": {\n          \"qwen3.7-plus\": {\n            \"temperature\": 1,\n            \"topP\": 0.95,\n            \"topK\": 20,\n            \"extraBody\": {\n              \"preserve_thinking\": true\n            }\n          },\n          \"glm-5.1\": {\n            \"temperature\": 0.7,\n            \"topP\": 0.95,\n            \"contextCache\": true,\n            \"pricing\": {\n              \"tiers\": [\n                {\n                  \"maxInputTokens\": 32000,\n                  \"input\": 6,\n                  \"cachedInput\": 1.2,\n                  \"explicitCachedInput\": 0.6,\n                  \"cacheCreationInput\": 7.5,\n                  \"output\": 24\n                },\n                {\n                  \"maxInputTokens\": 200000,\n                  \"input\": 8,\n                  \"cachedInput\": 1.6,\n                  \"explicitCachedInput\": 0.8,\n                  \"cacheCreationInput\": 10,\n                  \"output\": 28\n                }\n              ]\n            },\n            \"extraBody\": {\n              \"preserve_thinking\": true\n            }\n          }\n        }\n      }\n    }\n  }\n  ```\n  内置 token 价格覆盖 Codex GPT 模型（USD）、DashScope `qwen3.7-max`、`qwen3.7-plus`、`glm-5.1`、`glm-5.2`（CNY），DeepSeek `deepseek-v4-flash`、`deepseek-v4-pro`、`deepseek-chat`、`deepseek-reasoner`（CNY），以及 OpenCode Go 模型（`hy3`、`gpt-5.6-luna`、`glm-5.2`、`grok-4.5`、`deepseek-v4-flash`、`deepseek-v4-pro`、`kimi-k2.7-code`、`kimi-k3`、`mimo-v2.5`、`mimo-v2.5-pro`、`qwen3.7-plus`、`qwen3.7-max`、`minimax-m2.7`、`minimax-m3`，USD）。用户配置的 `pricing` 优先于内置价格。DashScope 若上游 usage 中出现 `cache_creation_input_tokens` 字段，cached tokens 按显式缓存读价计费；否则 `cachedInput` 作为隐式缓存读价。DeepSeek 的 `prompt_cache_hit_tokens` 会归入 cached input，`prompt_cache_miss_tokens` 会归入普通 input。\n- **smallModel：** 无工具预热消息的回退模型（例如 Claude Code 的探测请求）；默认是 `gpt-5-mini`。网关会对无工具的预热或探测请求强制使用该小模型，以避免消耗 premium 请求。该行为仅在 GitHub Copilot 账户为非 token-based 计费时生效（`token_based_billing` 为 false）；对于 token-based 计费账户，预热小模型回退会被跳过，因为不存在需要节省的 premium 请求配额。\n- **contextManagement：** 控制代理是否为 Responses API 附加 `context_management` 压缩指令。`messages` 作用于被翻译成 Responses API 的 Anthropic 风格 `/v1/messages` 请求，包括 `openai-responses` provider 的 Messages 路由，默认值为 `true`。`responses` 作用于 native `/v1/responses` 流量，包括 `provider/model` 别名和内置 `codex` provider，默认值为 `false`。只有在确认客户端支持 context management compaction 后，才建议在 Responses API 下启用 `responses`。启用后，请求体会带上 `context_management`，并在后续轮次中仅保留最新的压缩承载内容。**注意：** 对于 GPT-5.6 及以上模型（如 `gpt-5.6-sol`、`gpt-5.6-terra`、`gpt-5.6-luna`），context management 功能会被强制禁用，因为开启后会破坏这些模型的 prompt 缓存命中。此强制覆盖优先于 `contextManagement` 和 `modelResponsesApiCompactThresholds` 配置。\n - **modelResponsesApiCompactThresholds：** 按模型覆盖 Responses API 的 `compact_threshold`，仅在代理自动附加 `context_management` 时使用。它的优先级高于 `resolveResponsesCompactThreshold` 基于 `max_prompt_tokens * ratio` 的兜底阈值。默认将 `gpt-5.4` 和 `gpt-5.5` 设为 `217600`（`272000 * 0.8`）。未列出的模型继续使用原有兜底逻辑。\n- **modelReasoningEfforts：** `/v1/messages` 请求的模型级默认推理强度。仅当请求没有传入 `output_config.effort` 时，该配置才会生效。\n  - **优先级：** 请求中的 `output_config.effort` > `modelReasoningEfforts[model]` > 内置默认值（GPT-5.3+ 模型为 `xhigh`，其他模型为 `high`）。\n  - **转发字段：** 走 Copilot 原生 Messages API 时，最终值写入 `output_config.effort`；转换为 Responses API 时，最终值写入 `reasoning.effort`。\n  - **配置可选值：** `none`、`minimal`、`low`、`medium`、`high`、`xhigh`、`max`。\n- **useMessagesApi：** 当为 `true` 时，支持 Copilot 原生 `/v1/messages` 的 Claude 系模型会走 Messages API；否则回退到 `/chat/completions`。设为 `false` 可禁用 Messages API 路由，始终使用 `/chat/completions`。默认值为 `true`。\n- **useResponsesApiWebSocket：** 当为 `true` 时，Responses API 请求会优先对声明了 `ws:/responses` 的模型使用 Copilot websocket transport；仅声明 `/responses` 的模型仍走 HTTP。设为 `false` 可禁用 websocket 路由，并在模型支持 `/responses` 时使用 HTTP `/responses`。默认值为 `true`。如果遇到 Responses API WebSocket closed，一般是自己的网络问题。如果使用了 VPN，建议切换节点。\n- **useResponsesApiWebSearch：** 当为 `true` 时，服务端会保留 Responses API 中 `type: \"web_search\"` 的工具并透传到上游。设为 `false` 则会从 `/responses` payload 中移除这些工具。默认值为 `true`。\n- **messageApiWebSearchModel：** 顶层 Copilot `/v1/messages` 请求只包含服务端 `web_search` 工具时使用的全局模型，默认值为 `gpt-5-mini`。如果该值是 `provider/model` 别名，请求会进入对应 provider 的 Messages API 路径，并在转发前移除 provider 前缀。对于 Copilot GPT 模型，web search 会通过 `/responses` 执行。混合 `web_search` 与自定义工具的场景暂不支持，服务端会移除 server-side `web_search`。\n- **claudeTokenMultiplier：** 用于 Claude `/v1/messages/count_tokens` 请求在本地走 GPT tokenizer 估算时的乘数。默认值为 `1.15`。如果你的客户端仍然过晚触发上下文压缩，可以适当调大。这个配置只会在代理本地估算 Claude token 时生效；如果已经配置 `anthropicApiKey` 且 Anthropic token counting 调用成功，则会直接返回 Anthropic 的精确计数，不会使用这个乘数。\n- **anthropicApiKey：** 用于把 Claude `/v1/messages/count_tokens` 请求转发到 Anthropic 真实 token counting 端点的 API key，这样会返回精确计数，而不是 GPT tokenizer 估算值。也可通过环境变量 `ANTHROPIC_API_KEY` 设置。若未配置，或上游调用失败，则回退到由 `claudeTokenMultiplier` 控制的本地 GPT tokenizer 估算。\n\n编辑此文件后即可自定义 prompts，或替换为你自己的快速模型。修改完成后请重启服务（或重新执行命令），让缓存中的配置刷新生效。\n\n## API 认证\n\n- **受保护的普通路由：** 当配置了 `auth.apiKeys` 且非空时，除 `/`、`/usage-viewer` 和 `/usage-viewer/` 以外的普通路由都需要认证。\n- **Admin 路由：** 所有 `/admin/*` 路由都要求 `auth.adminApiKey`。如果缺失，服务会在启动时自动生成并在开始提供服务前写回 `config.json`。\n- **允许的认证头：**\n  - `x-api-key: <your_key>`\n  - `Authorization: Bearer <your_key>`\n- **CORS 预检：** `OPTIONS` 请求始终允许。\n- **未配置普通 key 时：** 普通路由仍可直接访问；但这条规则不适用于 `/admin/*`，后者只接受 `auth.adminApiKey`。\n\n普通受保护路由的示例请求：\n\n```sh\ncurl http://localhost:4141/v1/models \\\n  -H \"x-api-key: your_api_key\"\n```\n\nAdmin 路由的示例请求：\n\n```sh\ncurl http://localhost:4141/admin/config/model-mappings \\\n  -H \"x-api-key: your_admin_api_key\"\n```\n\n## API 端点\n\n服务端提供多个 OpenAI / Anthropic 兼容端点。请求会根据所选模型和 `provider/model` 别名路由到 GitHub Copilot、内置 `codex` provider 或已配置的 provider。\n\n### OpenAI 兼容端点\n\n这些端点模拟 OpenAI API 结构。\n\n| 端点 | 方法 | 说明 |\n| --- | --- | --- |\n| `POST /v1/responses` | `POST` | OpenAI 中用于生成模型响应的高级接口。支持 `openai-responses` provider 的 `provider/model` 别名。 |\n| `POST /v1/chat/completions` | `POST` | 为给定聊天对话创建模型响应。支持 `openai-compatible` provider 的 `provider/model` 别名；目标 provider 已配置时可在没有 Copilot 的情况下使用。 |\n| `GET /v1/models` | `GET` | 列出 Copilot 模型以及已启用 provider 的 `provider/model-id` 模型。来自 Codex 客户端（`User-Agent` 以 `codex` 开头）的请求会转发到 Codex Models 上游。 |\n| `POST /v1/embeddings` | `POST` | 创建表示输入文本的向量嵌入。 |\n\n### Codex 后端代理端点\n\n这些端点要求已有可用的 Codex 登录态。每个端点同时提供无版本前缀和 `/v1` 两种路径。\n\n| 端点 | 方法 | 说明 |\n| --- | --- | --- |\n| `POST /alpha/search`<br>`POST /v1/alpha/search` | `POST` | 将 JSON 请求体和查询参数透明转发到 Codex Alpha Search 上游。 |\n| `POST /images/generations`<br>`POST /v1/images/generations` | `POST` | 将 JSON 图片生成请求转发到 Codex Images 上游。请求未携带 `Content-Type` 时，网关默认补充 `application/json`。 |\n| `POST /images/edits`<br>`POST /v1/images/edits` | `POST` | 将图片编辑请求转发到 Codex Images 上游。请使用 `multipart/form-data`，并让 HTTP 客户端自动生成 `boundary`；网关会保留传入的 content type，并以流式方式转发上传请求体。 |\n\n对于以上所有端点，网关都会使用当前 Codex 登录态覆盖客户端的 authorization 和 account header，保留查询参数及兼容的请求头，并返回上游状态码、响应头和响应体。\n\n### Anthropic 兼容端点\n\n这些端点设计为兼容 Anthropic Messages API。provider 级的 models、Responses、alpha-search 和 images 路由同时支持无版本前缀与 `/v1` 两种路径；Messages 路由仍使用 `/v1`。\n\n| 端点 | 方法 | 说明 |\n| --- | --- | --- |\n| `POST /v1/messages` | `POST` | 为给定对话创建模型响应。支持已配置 provider 的 `provider/model` 别名，包括通过 `openai-compatible` provider 做翻译。 |\n| `POST /v1/messages/count_tokens` | `POST` | 计算一组消息的 token 数。支持已配置 provider 的 `provider/model` 别名。 |\n| `POST /:provider/v1/messages` | `POST` | 将 Anthropic Messages 请求代理到已配置的 Anthropic provider，或翻译到 OpenAI 兼容 / OpenAI Responses provider。 |\n| `GET /:provider/models`<br>`GET /:provider/v1/models` | `GET` | 将模型列表请求代理到已配置的 provider。对 `codex` 默认返回内置模型目录；Codex 客户端（`User-Agent` 以 `codex` 开头）会转发到 Codex Models 上游。 |\n| `POST /:provider/v1/messages/count_tokens` | `POST` | 为 provider 路由请求在本地计算 token 数。 |\n| `POST /:provider/responses`<br>`POST /:provider/v1/responses` | `POST` | 将 OpenAI Responses 请求代理到已配置的 `openai-responses` provider（含 `codex`）。 |\n| `POST /:provider/alpha/search`<br>`POST /:provider/v1/alpha/search` | `POST` | 代理 alpha-search 请求。对 `codex` 转发到 Codex Alpha Search 上游；其他 provider 转发到 `{baseUrl}/v1/alpha/search`。 |\n| `POST /:provider/images/generations`<br>`POST /:provider/v1/images/generations` | `POST` | 代理图片生成。对 `codex` 使用 Codex Images 上游；其他 provider 转发到 `{baseUrl}/v1/images/generations`（15 分钟超时）。 |\n| `POST /:provider/images/edits`<br>`POST /:provider/v1/images/edits` | `POST` | 代理图片编辑。对 `codex` 使用 Codex Images 上游；其他 provider 以 multipart/流式方式转发到 `{baseUrl}/v1/images/edits`（15 分钟超时）。 |\n\n### 使用量监控端点\n\n用于监控 Copilot 用量与额度的新端点。\n\n| 端点 | 方法 | 说明 |\n| --- | --- | --- |\n| `GET /usage` | `GET` | 获取详细的 Copilot 使用统计与额度信息。 |\n| `GET /token` | `GET` | 获取当前 API 正在使用的 Copilot token。 |\n\n### Admin / 配置端点\n\n这些端点用于本地管理操作，只接受 `auth.adminApiKey`。\n\n| 端点 | 方法 | 说明 |\n| --- | --- | --- |\n| `GET /admin/config/model-mappings` | `GET` | 返回当前 `config.json` 路径以及生效中的 `modelMappings` 映射。 |\n| `POST /admin/config/model-mappings` | `POST` | 只更新 `config.json` 里的 `modelMappings` 字段，并回传更新后的结果。 |\n\n## 使用示例\n\n常用 `npx` 命令：\n\n```sh\n# 基础启动\nnpx @jeffreycao/copilot-api@latest start\n\n# 自定义端口并开启详细日志\nnpx @jeffreycao/copilot-api@latest start --port 8080 --verbose\n\n# 执行认证流程\nnpx @jeffreycao/copilot-api@latest auth login\n\n# 配置第三方 provider，然后不依赖 GitHub Copilot 启动\nnpx @jeffreycao/copilot-api@latest auth login --provider dashscope\nnpx @jeffreycao/copilot-api@latest start\n\n# 以 JSON 格式输出调试信息\nnpx @jeffreycao/copilot-api@latest debug --json\n\n# 用 Bun 而不是 Node.js 运行已发布 CLI\nbunx --bun @jeffreycao/copilot-api@latest start\n```\n\n配置 `dashscope` 后的 OpenAI 兼容 provider 调用示例：\n\n```sh\ncurl http://localhost:4141/v1/chat/completions \\\n  -H \"content-type: application/json\" \\\n  -d '{\"model\":\"dashscope/qwen3.6-plus\",\"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]}'\n\ncurl http://localhost:4141/dashscope/v1/messages \\\n  -H \"content-type: application/json\" \\\n  -d '{\"model\":\"qwen3.6-plus\",\"max_tokens\":1024,\"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]}'\n```\n\n## 使用建议\n\n<a id=\"claudemd-or-agentsmd-recommended-content\"></a>\n\n### CLAUDE.md 或 AGENTS.md 推荐内容\n\n如果你想手动加入这些提醒，请在 Claude Code 的 `CLAUDE.md`，或 opencode/codex 的 `AGENTS.md` 中加入以下内容：\n\n```\n- Prohibited from directly asking questions to users, MUST use question tool.\n- Once you can confirm that the task is complete, MUST use question tool to make user confirm. The user may respond with feedback if they are not satisfied with the result, which you can use to make improvements and try again, after try again, MUST use question tool to make user confirm again.\n```\n"}, "de17a027c73ef7a4f5d2703660dea2ba987c62a0": {"t": 1785765531.3581903, "n": 34054, "h": "fa5c491ac8e8a648", "c": "# Copilot API Proxy\n\n[English](./README.md) | 简体中文\n\n## 重要说明\n\n> [!IMPORTANT]\n> **使用前请先注意以下几点：**\n>\n> 1. **Claude Code 配置：** 与 Claude Code 搭配使用时，请将模型 ID 配置为 `claude-opus-4-8`。示例 claude `settings.json` 见 [通过 `settings.json` 手动配置](#manual-configuration-with-settingsjson)。\n>\n> 2. **内置 `copilot`、`codex` 与第三方 provider：** 执行 `npx @jeffreycao/copilot-api@latest auth`，可选择 `copilot`、`codex`、`deepseek`、`custom` 等 provider。\n>\n> 3. **注意事项：** README 顶部移除的 GitHub Copilot warning 见 [GitHub Copilot 安全提示](./NOTICE.md#github-copilot-security-notice)。\n\n---\n\n## 项目概览\n\n这是一个小型 AI gateway，可以使用 GitHub Copilot、内置 `codex` provider，也可以使用 DashScope 等已配置的第三方 provider。GitHub Copilot 现在是可选能力：如果本地没有 GitHub token，只要至少配置了一个启用中的 provider，服务仍可按 provider-only 模式启动。\n\nAI gateway 会从同一个本地端点暴露 OpenAI / Anthropic 兼容 API，让 [Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview)、OpenCode、Codex 和 OpenAI 兼容客户端可以共用同一个本地服务。\n\n在 GitHub Copilot 路径上，AI gateway 会在可用时优先使用 Copilot 原生的 Anthropic 风格 Messages API，在重工具调用场景下保留更原生的 Claude 行为。\n\n## 功能特性\n\n- **OpenAI 与 Anthropic 双兼容**：通过 `/v1/responses`、`/v1/chat/completions`、`/v1/models`、`/v1/embeddings` 和 `/v1/messages` 对外暴露同一个本地 AI gateway。\n- **Copilot 可选**：有 GitHub 凭据时可以使用 GitHub Copilot，没有 GitHub 凭据时也可以只依赖已配置的 provider 运行。\n- **同一网关接入 Copilot、`codex` 与第三方 provider**：可统一路由 GitHub Copilot、内置 `codex` provider 和配置好的外部 provider。\n- **第三方 provider 可独立启动**：配置 DashScope、DeepSeek、OpenRouter 或自定义 provider 后，不需要 GitHub Copilot 登录即可启动 AI gateway。\n- **OpenAI 兼容 provider 同时支持 chat 和 Messages API**：`openai-compatible` provider 可通过顶层 `/v1/chat/completions` 搭配 `model: \"provider/model\"` 提供 Chat Completions，也可通过 `/v1/messages` 完成 Anthropic Messages 的请求/响应翻译。\n- **面向 Claude 的更原生 Copilot 路由**：优先使用原生 `/v1/messages`，保留 Claude 风格工具流，支持 Anthropic beta 能力、通过 Responses-capable 模型支持 Claude WebSearch，并保留 subagent / session 标记。\n- **Claude Code 与 OpenCode 集成**：兼容 Claude Code 与 OpenCode，也支持通过 `@ai-sdk/anthropic` 直接作为 Anthropic provider 使用。\n- **灵活的认证与部署选项**：支持交互式登录、直接 token、个人 / Business / Enterprise、GitHub Enterprise、opencode OAuth 和自定义数据目录。\n- **多 provider 路由**：可暴露 `/:provider/...` 路由，也可在顶层 API 上使用 `model: \"provider/model\"`。\n\n## 前置要求\n\n- Bun（>= 1.2.x）\n- 如果要通过 `npx` 运行已发布 CLI，需要 Node.js\n- 只有在使用 GitHub Copilot provider 时，才需要已订阅 Copilot 的 GitHub 账号\n- 如果不使用 GitHub Copilot，需要至少一个已配置 provider 的 API key 或 OAuth 登录\n\n## 安装\n\n安装依赖：\n\n```sh\nbun install\n```\n\n直接从源码启动服务：\n\n```sh\nbun run start start\n```\n\n## 从源码运行\n\n本项目可以通过多种方式从源码运行：\n\n### 开发模式\n\n```sh\nbun run dev start\n```\n\n### 生产模式\n\n```sh\nbun run start start\n```\n\n## 通过 npx 使用\n\n你可以直接用 npx 运行本项目：\n\n> [!IMPORTANT]\n> 通过 `npx` 运行时，token usage 存储会使用 Node 内置的 `node:sqlite` 模块。该能力会在 Node.js >= 22.13.0 时启用；Node.js < 22.13.0 时 CLI 仍可启动，但会禁用 token usage 存储。\n>\n> 如果不升级 Node.js 但仍需要 token usage 存储，可以改用 Bun 运行已发布 CLI：`bunx --bun @jeffreycao/copilot-api@latest start`。\n\n```sh\nnpx @jeffreycao/copilot-api@latest start\n```\n\n带参数示例：\n\n```sh\nnpx @jeffreycao/copilot-api@latest start --port 8080\n```\n\n如果只想做认证或 provider 配置：\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth\n```\n\n如果要不依赖 GitHub Copilot 运行，先配置至少一个 provider，然后正常启动服务：\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth login --provider dashscope\nnpx @jeffreycao/copilot-api@latest start\n```\n\n## 配合 Docker 使用\n\n构建镜像：\n\n```sh\ndocker build -t copilot-api .\n```\n\n通过 bind mount 运行容器，让认证数据在重启后保留：\n\n```sh\nmkdir -p ./copilot-data\ndocker run -p 4141:4141 -v $(pwd)/copilot-data:/root/.local/share/copilot-api copilot-api\n```\n\n这会把宿主机上的 `./copilot-data` 映射到容器内的 `/root/.local/share/copilot-api`，用于持久化 GitHub 认证数据、provider 配置和其他 gateway 状态。\n\n也可以直接通过环境变量传入 GitHub token：\n\n```sh\ndocker run -p 4141:4141 -e GH_TOKEN=your_github_token_here copilot-api\n```\n\n## Electron 桌面应用\n\n如果你更喜欢图形界面，仓库里还提供了位于 `desktop/` 的 Electron 桌面应用。它支持 GitHub Copilot 登录、OpenAI Codex OAuth，以及 DeepSeek、DashScope、OpenRouter 或自定义 provider 的 API Key 配置。授权或配置 provider 后，可以一键启动或停止本地代理，并在界面里直接查看本地端点、鉴权 Header、可用模型、额度和日志。\n\n设置页还可以配置 `OAuth App`、`API Home`、`Enterprise URL`、详细日志以及最小化到托盘。Windows x64（`.exe`）、macOS Apple Silicon（`.dmg`）和 Linux x64（`.AppImage`）安装包发布在 GitHub Releases：\n\nhttps://github.com/caozhiyuan/copilot-api/releases\n\nLinux 用户需要先为下载的 AppImage 添加执行权限：\n\n```sh\nchmod +x Copilot-API-*-linux-x86_64.AppImage\n./Copilot-API-*-linux-x86_64.AppImage\n```\n\n下载对应平台的安装包后，在应用内授权或配置 provider，选择端口并启动服务，再把你的客户端指向应用里显示的本地端点即可。发布版桌面应用使用随包内置的 Electron 运行时，正常使用不需要额外安装 Node.js；token usage 历史记录会在该内置运行时支持 SQLite 时启用。\n\n桌面应用里的高级配置页会通过 `GET/POST /admin/config/model-mappings` 读写这份共享的模型映射。同一份映射会统一作用于 `POST /v1/messages`、`POST /v1/messages/count_tokens`、`POST /v1/responses` 和 `POST /v1/chat/completions`，不再按接口区分。它使用的是 `auth.adminApiKey`，不是普通的 `auth.apiKeys`；应用会在服务启动并自动生成该 key 后，直接从 `config.json` 读取它来发起请求。\n\n### 桌面应用截图\n\n下面展示了桌面应用中的首页、Token 用量统计页面：\n\n<p align=\"center\">\n  <img src=\"./docs/screenshots/desktop-dashboard.png\" alt=\"Copilot API 桌面应用首页\" width=\"49%\" />\n  <img src=\"./docs/screenshots/desktop-token-usage.png\" alt=\"Copilot API 桌面应用 Token 用量页\" width=\"49%\" />\n</p>\n\n## 与 Claude Code 一起使用\n\n这个 AI gateway 可以为 [Claude Code](https://docs.anthropic.com/en/claude-code) 提供后端能力。Claude Code 是 Anthropic 提供的实验性面向开发者的对话式 AI 助手。\n\n有两种方式可以把 Claude Code 配置为使用这个 AI gateway：\n\n### 通过 `--claude-code` 标志进行交互式配置\n\n执行带 `--claude-code` 的 `start` 命令开始：\n\n```sh\nnpx @jeffreycao/copilot-api@latest start --claude-code\n```\n\n你不再需要手动选择模型。Gateway 会自动检测每个 Claude Code 尺寸档位对应的最新可用模型——opus 映射到最新的 Opus 模型，sonnet 映射到最新的 Sonnet 模型，haiku 映射到最新的 Haiku 模型——并生成相应设置 `ANTHROPIC_DEFAULT_OPUS_MODEL`、`ANTHROPIC_DEFAULT_SONNET_MODEL` 和 `ANTHROPIC_DEFAULT_HAIKU_MODEL` 的命令。若某个档位没有匹配的可用模型，则会被省略。该命令会被复制到剪贴板，并设置 Claude Code 使用这个 AI gateway 所需的环境变量。\n\n在新的终端中粘贴并执行这条命令，即可启动 Claude Code。\n\n<a id=\"manual-configuration-with-settingsjson\"></a>\n\n### 通过 `settings.json` 手动配置\n\n另一种方式是在项目根目录中创建 `.claude/settings.json` 文件，并写入 Claude Code 所需的环境变量。这样你就不需要每次都运行交互式配置了。\n\n下面是一个 `.claude/settings.json` 示例：\n\n```json\n{\n  \"env\": {\n    \"ANTHROPIC_BASE_URL\": \"http://localhost:4141\",\n    \"ANTHROPIC_AUTH_TOKEN\": \"dummy\",\n    \"ANTHROPIC_MODEL\": \"gpt-5.6-sol[1m]\",\n    \"ANTHROPIC_DEFAULT_SONNET_MODEL\": \"gpt-5.6-sol[1m]\",\n    \"ANTHROPIC_DEFAULT_HAIKU_MODEL\": \"gpt-5.6-luna[1m]\",\n    \"CLAUDE_CODE_AUTO_COMPACT_WINDOW\": \"272000\",\n    \"CLAUDE_CODE_USE_VERTEX\": \"0\",\n    \"CLAUDE_CODE_USE_BEDROCK\": \"0\",\n    \"DISABLE_NON_ESSENTIAL_MODEL_CALLS\": \"1\",\n    \"CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC\": \"1\",\n    \"CLAUDE_CODE_ATTRIBUTION_HEADER\": \"0\",\n    \"CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION\": \"false\",\n    \"CLAUDE_CODE_DISABLE_TERMINAL_TITLE\": \"true\",\n    \"CLAUDE_CODE_ENABLE_AWAY_SUMMARY\": \"0\"\n  },\n  \"alwaysThinkingEnabled\": true,\n  \"effortLevel\": \"xhigh\",\n  \"showThinkingSummaries\": true\n}\n```\n\n- 请根据需要替换 `ANTHROPIC_MODEL`、`ANTHROPIC_DEFAULT_OPUS_MODEL`、`ANTHROPIC_DEFAULT_SONNET_MODEL` 和 `ANTHROPIC_DEFAULT_HAIKU_MODEL`。配置完成后，请安装 claude code 插件，见 [插件集成](#plugin-integrations)。\n- 如果你使用的是 codex provider，建议**不要**将模型名配置成 `codex/xxx` 格式（如 `codex/gpt-5.6-sol`）。Claude Code 会针对 `codex/` 前缀做降智行为——例如每次请求时移除所有之前返回的思考块（thinking blocks）。请使用纯模型名（如 `gpt-5.6-sol`），并在 `config.json` 中配置 `modelMappings` 将其映射回 codex provider：\n  ```json\n  \"modelMappings\": {\n    \"gpt-5.6-sol\": \"codex/gpt-5.6-sol\",\n    \"gpt-5.6-terra\": \"codex/gpt-5.6-terra\",\n    \"gpt-5.6-luna\": \"codex/gpt-5.6-luna\"\n  },\n  ```\n- 将 `CLAUDE_CODE_ATTRIBUTION_HEADER` 设为 `0` 可以阻止 Claude Code 在 system prompt 中附加计费和版本信息，从而避免 prompt cache 失效。\n- 关闭 `CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION` 和 `CLAUDE_CODE_ENABLE_AWAY_SUMMARY` 可以避免不必要地消耗额度。\n- Claude Code WebSearch 已支持纯搜索请求。Copilot 路径请保持全局 `messageApiWebSearchModel` 指向 Responses-capable GPT 模型或 `provider/model` 别名；provider 路由请使用原生 Anthropic provider 或 `openai-responses` provider。只有在你明确想禁止这类流量时，才需要把 `WebSearch` 加到 `permissions.deny`。\n- 如果使用的不是 Claude 模型，请不要启用 `ENABLE_TOOL_SEARCH`。如果使用的是 Claude 模型，则可以启用 `ENABLE_TOOL_SEARCH`。当前 Claude Code 使用的是客户端 tool search 模式，在该模式下每次加载 defer tools 都需要额外请求一次。\n- `CLAUDE_CODE_AUTO_COMPACT_WINDOW`：设置用于自动压缩计算的上下文容量（以 token 为单位）。默认使用模型自身的上下文窗口：标准模型为 200K，扩展上下文模型为 1M。使用 1M 上下文模型（如 `claude-opus-4-6[1m]`）时，可设置一个较低的值（如 `500000`）将窗口视为 500K 用于压缩计算。该值受限于模型的实际上下文窗口上限。`CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` 会基于此值的百分比生效。设置此变量可将压缩阈值与状态栏的 `used_percentage` 解耦（后者始终使用模型的完整上下文窗口）。\n\n更多选项见：[Claude Code settings](https://docs.anthropic.com/en/docs/claude-code/settings#environment-variables)\n\n也可以参考 IDE 集成说明：[Add Claude Code to your IDE](https://docs.anthropic.com/en/docs/claude-code/ide-integrations)\n\n## 与 OpenCode 一起使用\n\nOpenCode 已经有直接的 GitHub Copilot provider。本节适用于你希望让 OpenCode 通过 `@ai-sdk/anthropic` 指向这个 AI gateway，并复用本 README 前面提到的 agent 行为时。\n\n### 最小配置\n\n使用 OpenCode OAuth app 启动 AI gateway：\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth --oauth-app=opencode\nnpx @jeffreycao/copilot-api@latest start\n```\n\n然后让 OpenCode 通过 `@ai-sdk/anthropic` 指向这个 AI gateway。\n\n示例 `~/.config/opencode/opencode.json`：\n\n```json\n{\n  \"$schema\": \"https://opencode.ai/config.json\",\n  \"provider\": {\n    \"local\": {\n      \"npm\": \"@ai-sdk/anthropic\",\n      \"name\": \"My Local\",\n      \"options\": {\n        \"baseURL\": \"http://localhost:4141/v1\",\n        \"apiKey\": \"dummy\"\n      },\n      \"models\": {\n        \"gpt-5.4\": {\n          \"name\": \"gpt-5.4\",\n          \"modalities\": {\n            \"input\": [\"text\", \"image\"],\n            \"output\": [\"text\"]\n          },\n          \"limit\": {\n            \"context\": 400000,\n            \"input\": 272000,\n            \"output\": 128000\n          }\n        },\n        \"claude-sonnet-4.6\": {\n          \"id\": \"claude-sonnet-4.6\",\n          \"name\": \"claude-sonnet-4.6\",\n          \"modalities\": {\n            \"input\": [\"text\", \"image\"],\n            \"output\": [\"text\"]\n          },\n          \"limit\": {\n            \"context\": 200000,\n            \"output\": 32000\n          },\n          \"options\": {\n            \"thinking\": {\n              \"type\": \"adaptive\"\n            },\n            \"effort\": \"max\"\n          }\n        }\n      }\n    }\n  }\n}\n```\n\n这些字段的重要性：\n\n- `npm: \"@ai-sdk/anthropic\"` 是关键。OpenCode 会以 Anthropic Messages 语义与这个 AI gateway 通信，而不是把一切扁平化为 OpenAI Chat Completions。\n- `options.baseURL` 应设为 `http://localhost:4141/v1`；Anthropic SDK 会自动补上 `/messages`、`/models` 和 `/messages/count_tokens`。\n- 如果你在此代理中启用了 `auth.apiKeys`，请把 `dummy` 替换为真实 key；否则任意占位值都可以。\n\n## 与 Codex 一起使用\n\n这个 AI gateway 也可以为 Codex 提供后端能力。\n\n### Codex `config.toml` 参考配置\n\n把以下 `[model_providers.copilot_api]` 段加入你的 Codex `~/.codex/config.toml`：\n\n```toml\nmodel_provider = \"copilot_api\"\nmodel_reasoning_summary = \"auto\"\nmodel_context_window = 272000\nmodel_auto_compact_token_limit = 244800\n\n[model_providers.copilot_api]\nname = \"OpenAI\"\nbase_url = \"http://localhost:4141\"\nenv_key = \"GITHUB_COPILOT_API_KEY\"\nrequires_openai_auth = true\nsupports_websockets = false\nwire_api = \"responses\"\nrequest_max_retries = 3\nstream_max_retries = 1\nstream_idle_timeout_ms = 300000\n\n[features]\nremote_compaction_v2 = true\n\n[analytics]\nenabled = false\n```\n\n> [!NOTE]\n> 此配置仅限于 Codex 与 GitHub Copilot provider。`name` 一定要配置为 `\"OpenAI\"`。它可以缓解 Codex local compact 不命中缓存的问题。\n> 如果使用 codex provider，建议将 `base_url` 配置为 `\"http://localhost:4141/codex\"`。\n\n## GPT Tool Search\n\n对于 `gpt-5.4+` 这类 GPT Responses 模型，这个 AI gateway 可以通过一个很小的 MCP bridge 暴露 Responses `tool_search`。Claude Code 和 opencode 都可以使用同一个 bridge，前提是客户端会加载 MCP server，并且 Anthropic Messages 流量会经过这个 AI gateway。\n\nGPT 模型不要设置 Claude Code 原生的 `ENABLE_TOOL_SEARCH`。这个开关启用的是 Claude Code 自己的客户端 tool search 模式，可能导致 deferred 工具定义不再转发给 AI gateway。这个 AI gateway 需要完整的工具定义，这样才能只保留那一小组常驻加载工具，其余工具统一转换为 Responses deferred namespace。\n\n如果你安装了 `tool-search@copilot-api-marketplace`，Claude Code 会自动带上这个 MCP bridge，可以跳过下面这段 Claude Code MCP 手动配置。\n\n请把 tool search bridge 加到 Claude Code 使用的 MCP 配置中：\n\n```json\n{\n  \"mcpServers\": {\n    \"tool_search\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@jeffreycao/copilot-api@latest\", \"mcp\"]\n    }\n  }\n}\n```\n\n请把 tool search bridge 加到 opencode 使用的 MCP 配置中：\n\n```json\n{\n  \"mcp\": {\n    \"tool_search\": {\n      \"type\": \"local\",\n      \"command\": [\"npx\", \"-y\", \"@jeffreycao/copilot-api@latest\", \"mcp\"]\n    }\n  }\n}\n```\n\n本地开发时可以将命令换成 `bun`，参数换成 `[\"run\", \"./src/main.ts\", \"mcp\"]`。\n\nAI gateway 内部现在会把 OpenAI Responses `tool_search` 配置成 client-executed 模式。deferred tools 仍然会作为可搜索 namespace 暴露给模型，但会明确要求模型直接返回下一步要加载的精确工具名列表。\n\n该 bridge 使用直接工具选择，不做 query 搜索。工具入参是 `names`，值为逗号分隔的精确 deferred 工具名，例如 `TaskList,TaskGet,mcp__fetch__fetch`。\n\n<a id=\"plugin-integrations\"></a>\n\n## 插件集成\n\n本项目为 Claude Code 和 opencode 提供了插件集成。\n\n#### Claude Code 插件集成（基于 marketplace）\n\nClaude Code 集成现在拆分为两个插件：\n\n- `agent-inject` 会在 `SubagentStart` 时注入 `__SUBAGENT_MARKER__...`，以便 AI gateway 推导 `x-initiator: agent`。\n- `tool-search` 会注册用于 GPT Responses deferred tool loading 的 `tool_search` MCP bridge。\n\n- 本仓库中的 marketplace catalog：`.claude-plugin/marketplace.json`\n- 本仓库中的插件源码：`plugin/claude/agent-inject`、`plugin/claude/tool-search`\n\n远程添加 marketplace：\n\n```sh\n/plugin marketplace add https://github.com/caozhiyuan/copilot-api.git\n```\n\n从 marketplace 安装插件：\n\n```sh\n/plugin install agent-inject@copilot-api-marketplace\n/plugin install tool-search@copilot-api-marketplace\n```\n\n安装后，`agent-inject` 会在 `SubagentStart` 时注入 `__SUBAGENT_MARKER__...`，AI gateway 会利用它推导 `x-initiator: agent`。\n\n`agent-inject` 还会注册一个 `UserPromptSubmit` hook，并返回 `{\"continue\": true}`；同时它也可以通过环境变量注入 `SessionStart` reminder 规则：\n\n- `CLAUDE_PLUGIN_ENABLE_QUESTION_RULES=1` 会自动为 Claude Code 启用两条关于使用 `question` 工具的提醒。你也可以把同样的提醒手动写进 `CLAUDE.md`；见 [CLAUDE.md 或 AGENTS.md 推荐内容](#claudemd-or-agentsmd-recommended-content)。\n- `CLAUDE_PLUGIN_ENABLE_NO_BACKGROUND_AGENTS_RULE=1` 会启用关于避免在 agent hooks 中使用 `run_in_background: true` 的提醒。\n\n`tool-search` 插件内置了 [GPT Tool Search](#gpt-tool-search) 一节描述的同一个 MCP bridge，因此安装该插件后，Claude Code 用户无需再手动配置 `tool_search` server。\n\n#### Opencode 插件\n\nsubagent 标记生成器被打包为一个 opencode 插件，位于 `plugin/opencode/subagent-marker.js`。\n\n**安装方式：**\n\n将插件文件复制到你的 opencode 插件目录：\n\n```sh\n# 克隆或下载本仓库后复制该插件\ncp plugin/opencode/subagent-marker.js ~/.config/opencode/plugins/\n```\n\n或者手动在 `~/.config/opencode/plugins/subagent-marker.js` 创建该文件，并填入插件内容。\n\n**功能：**\n\n- 跟踪 subagent 创建的子会话\n- 自动在 subagent 聊天消息前添加 marker system reminder（`__SUBAGENT_MARKER__...`）\n- 设置 `x-session-id` 请求头以跟踪会话\n- 让这个 AI gateway 能够把来自 subagent 的请求识别为 `x-initiator: agent`\n\n该插件会挂接到 `session.created`、`session.deleted`、`chat.message` 和 `chat.headers` 事件上，以无缝提供 subagent marker 能力。\n\n## 使用量查看器\n\n服务启动后，控制台会输出一个 Copilot 使用量看板 URL。这个看板是一个用于监控 API 用量的 Web 界面。\n\n1. 启动服务。例如使用 npx：\n   ```sh\n   npx @jeffreycao/copilot-api@latest start\n   ```\n2. 服务会输出一个 usage viewer 的 URL。将它复制到浏览器中打开，形式大致如下：\n   `http://localhost:4141/usage-viewer?endpoint=http://localhost:4141/usage`\n   - 如果你在 Windows 上使用 `start.bat` 脚本，这个页面会自动打开。\n\n看板提供了更易读的 Copilot 用量视图：\n\n> token usage 历史记录需要 Bun 或 Node.js >= 22.13.0。Node.js < 22.13.0 时服务会正常运行，但 token usage 存储会被禁用。\n\n- **API Endpoint URL**：通过 URL 查询参数指定 API endpoints，默认指向本地服务。支持手动切换为其他兼容 endpoints。\n- **x-api-key 认证**：如果启用了 API Key 认证，可填入 `x-api-key` 请求头。密钥会持久化保存在浏览器本地存储中。\n- **Period 选择器**：支持 Day / Week / Month 三种时间范围，切换时 URL 参数会自动同步，方便收藏和分享。\n- **Fetch Data**：点击 \"Refresh\" 按钮加载或刷新使用数据。页面加载时也会自动拉取数据。\n- **Copilot Quotas 额度**：通过进度条展示 Chat、Completions 等不同服务的额度使用情况，悬停可查看已用/剩余详情。\n- **Token Usage 指标卡片**：汇总当前周期的 Total、Input、Output、Cache Read、Cache Write、Requests 和预估费用。\n- **趋势图（Week / Month）**：提供按模型和指标筛选的折线趋势图，点击数据点可查看单日用量明细。\n- **Model Breakdown 表格**：按模型维度列出周期内的请求数、输入/输出/缓存 token 和预计费用。\n- **Request Events 分页列表**：按时间排序的请求事件记录，支持分页浏览，含时间戳、模型、请求 ID 和 token 用量。\n- **Detailed Information**：展示 API 返回的完整 JSON 响应，便于深入分析所有可用统计数据。\n- **URL-based Configuration**：也可通过 `endpoint` 和 `period` 查询参数直接指定 API 端点与时间范围。例如：\n  `http://localhost:4141/usage-viewer?endpoint=http://your-api-server/usage&period=week`\n\n### Usage Viewer 截图\n\n<p align=\"center\">\n  <img src=\"./docs/screenshots/usage-viewer.png\" alt=\"Copilot API Usage Viewer 页面\" width=\"900\" />\n</p>\n\n## 命令结构\n\nCopilot API 现在使用子命令结构，主要命令包括：\n\n- `start`：启动 AI gateway 服务。如果已有 GitHub token，则启用 Copilot 路径；如果没有 GitHub token，但存在至少一个启用中的 provider，则按 provider-only 模式启动；如果两者都没有，会引导你配置 provider。\n- `auth`：仅执行 provider 登录或配置流程，不启动服务。可用于 GitHub Copilot 登录、Codex OAuth，或第三方 provider API key 配置。\n- `debug`：显示诊断信息，包括版本、运行时详情、文件路径以及认证状态，便于排障与支持。\n\n## 命令行选项\n\n### 全局选项\n\n以下选项可用于任意子命令。若在子命令之前传入，请使用 `--key=value` 形式：\n\n| 选项 | 说明 | 默认值 | 别名 |\n| --- | --- | --- | --- |\n| --api-home | API home 目录路径（设置 `COPILOT_API_HOME`） | 无 | 无 |\n| --oauth-app | OAuth app 标识符（设置 `COPILOT_API_OAUTH_APP`） | 无 | 无 |\n| --enterprise-url | GitHub Enterprise URL（设置 `COPILOT_API_ENTERPRISE_URL`） | 无 | 无 |\n\n### Start 命令选项\n\n以下是 `start` 命令可用的命令行选项：\n\n| 选项 | 说明 | 默认值 | 别名 |\n| --- | --- | --- | --- |\n| --port | 监听端口 | 4141 | -p |\n| --verbose | 启用详细日志 | false | -v |\n| --github-token | 直接提供 GitHub token（必须通过 `auth` 子命令生成） | 无 | -g |\n| --claude-code | 生成一个使用 Copilot API 配置启动 Claude Code 的命令 | false | -c |\n| --show-token | 在获取和刷新时显示 GitHub 与 Copilot token | false | 无 |\n| --proxy-env | 从环境变量初始化代理 | false | 无 |\n\n### Auth 命令选项\n\n| 选项 | 说明 | 默认值 | 别名 |\n| --- | --- | --- | --- |\n| --provider | 要登录或配置的 provider（`copilot`、`codex`、`opencode-go`、`deepseek`、`dashscope`、`openrouter` 或 `custom`） | 交互选择 | 无 |\n| --verbose | 启用详细日志 | false | -v |\n| --show-token | 认证时显示 GitHub token | false | 无 |\n\n只有在需要启用 GitHub Copilot provider 时，才需要执行 `copilot-api auth login --provider copilot`。使用 `codex` 或第三方 provider-only 模式不要求配置 Copilot。\n\n使用 `copilot-api auth login --provider deepseek`、`--provider dashscope`、`--provider openrouter` 或 `--provider opencode-go` 可以通过 CLI 快速新增或更新这些常用第三方 provider。DeepSeek 会提示输入掩码显示的 `apiKey`、provider `type`（默认 `anthropic`），以及默认 `https://api.deepseek.com/anthropic` 的 `baseUrl`。DashScope 会提示输入掩码显示的 `apiKey`、provider `type`（默认 `openai-compatible`）和预填默认值的 `baseUrl`。OpenRouter 只提示输入掩码显示的 `apiKey` 和预填默认值的 `baseUrl`，并固定写入 `type: \"anthropic\"`。OpenCode Go 只提示输入掩码显示的 `apiKey` 和预填默认值的 `baseUrl`，并固定写入 `type: \"openai-compatible\"`（baseUrl `https://opencode.ai/zen/go`）。配置并启用 provider 后，`copilot-api start` 可在没有 GitHub token 的情况下启动。\n\n使用 `copilot-api auth login --provider custom` 可以通过 CLI 新增或更新其他第三方 provider。命令会依次提示输入 provider name、项目支持的 type（`anthropic`、`openai-compatible` 或 `openai-responses`）、`baseUrl`、掩码显示的 `apiKey` 和 `authType`；`authType` 可保持 type 默认值，也可选择 `x-api-key` / `authorization`。\n\n### Debug 命令选项\n\n| 选项 | 说明 | 默认值 | 别名 |\n| --- | --- | --- | --- |\n| --json | 以 JSON 输出调试信息 | false | 无 |\n\n<a id=\"configuration-configjson\"></a>\n\n## 配置（config.json）\n\n- **位置：** Linux/macOS 为 `~/.local/share/copilot-api/config.json`，Windows 为 `%USERPROFILE%\\.local\\share\\copilot-api\\config.json`。\n- **默认结构：**\n  ```json\n  {\n    \"auth\": {\n      \"apiKeys\": [],\n      \"adminApiKey\": \"<startup 自动生成>\"\n    },\n    \"providers\": {},\n    \"modelMappings\": {},\n    \"extraPrompts\": {\n      \"gpt-5-mini\": \"<built-in exploration prompt>\"\n    },\n    \"smallModel\": \"gpt-5-mini\",\n    \"contextManagement\": {\n      \"messages\": true,\n      \"responses\": false\n    },\n    \"modelResponsesApiCompactThresholds\": {\n      \"gpt-5.4\": 217600,\n      \"gpt-5.5\": 217600\n    },\n    \"modelReasoningEfforts\": {\n      \"gpt-5-mini\": \"low\"\n    },\n    \"useMessagesApi\": true,\n    \"useResponsesApiWebSocket\": true,\n    \"useResponsesApiWebSearch\": true,\n    \"messageApiWebSearchModel\": \"gpt-5-mini\"\n  }\n  ```\n- **auth.apiKeys：** 用于普通非 admin 路由的 API key。支持多个 key 轮换使用。请求可通过 `x-api-key: <key>` 或 `Authorization: Bearer <key>` 进行认证。若为空或省略，则普通路由的认证会被禁用。\n- **auth.adminApiKey：** 仅用于 `/admin/*` 路由的单个 admin key。若未配置，服务会在启动时自动生成一个随机 key，并回写到 `config.json`。它同样使用 `x-api-key` 或 `Authorization: Bearer` 这两种头，但普通 `auth.apiKeys` 不能访问 `/admin/*`。\n- **modelMappings：** 用于顶层 `POST /v1/messages`、`POST /v1/messages/count_tokens`、`POST /v1/responses` 和 `POST /v1/chat/completions` 请求的精确 `sourceModel -> targetModel` 重写映射，这几类接口共用同一份规则。省略该字段或保留为 `{}` 时，不会做模型重写。`source` 和 `target` 都必须是非空字符串。`target` 可以是普通模型 ID，也可以是 `provider/model` 形式的别名，例如 `dashscope/qwen3.6-plus`；重写发生在 provider alias 解析之前。这些映射不再按接口区分。`GET/POST /admin/config/model-mappings` 管理接口读写的也只有这个字段。\n- **extraPrompts：** `model -> prompt` 的映射。把 Anthropic 风格请求翻译为 Responses API 时，会将其附加到第一条 system prompt 后面。你可以借此为不同模型注入护栏或指引。缺失的默认项会自动补齐，但不会覆盖你自定义的 prompt。对于 GPT-5.3+ 模型（如 `gpt-5.3-codex`、`gpt-5.4`、`gpt-5.5`），未显式配置时会自动使用内置的 commentary prompt。内置 prompt 会启用带阶段感知的 commentary，让模型在工具调用或更深层推理前先发出简短的用户可见进度说明。\n- **providers：** 全局上游 provider 映射。每个 provider key（例如 `dashscope`）都会变成一个路由前缀（`/dashscope/v1/messages`）。支持 `type: \"anthropic\"`、`type: \"openai-compatible\"` 和 `type: \"openai-responses\"`。顶层客户端也可以在 `/v1/messages`、`/v1/messages/count_tokens`、`/v1/responses` 和 `/v1/chat/completions` 中使用 `model: \"dashscope/model-id\"`；AI gateway 会在转发上游前移除 `dashscope/` 前缀。`openai-compatible` provider 同时支持 chat 和 Messages 流程：`/v1/chat/completions` 会直连上游 `/v1/chat/completions`，而 `/v1/messages` 和 `/:provider/v1/messages` 会先翻译为上游 Chat Completions，再把响应翻译回 Anthropic Messages。`GET /v1/models` 会聚合已启用 provider 的模型，并以 `provider/model-id` 形式返回；单个 provider 的原始模型列表仍可使用 `GET /dashscope/v1/models`。\n  - `enabled`：可选，若省略则默认为 `true`。\n  - `baseUrl`：provider API 的基础 URL，不要带结尾的 endpoint。Anthropic provider 不要带 `/v1/messages`；OpenAI 兼容 provider 不要带 `/v1/chat/completions`；OpenAI Responses provider 不要带 `/v1/responses`。\n  - `apiKey`：作为上游凭据值使用；普通 provider 必须配置。\n  - `authType`：可选，控制 `apiKey` 如何发送到上游。普通 provider 支持 `x-api-key` 和 `authorization`。Anthropic provider 默认 `x-api-key`；OpenAI 兼容和 OpenAI Responses provider 默认 `authorization`。当设置为 `authorization` 时，代理会发送 `Authorization: Bearer <apiKey>`。`oauth2` 仅保留给内置 `codex` provider，并由 `auth login --provider codex` 自动写入。\n  - `pricingCurrency`：可选，provider 维度的 token 费用币种，例如 `USD` 或 `CNY`。快捷 provider 默认 DashScope、DeepSeek 为 `CNY`，Codex/OpenRouter 为 `USD`。费用按币种分别汇总，不做汇率换算。\n  - `models`：可选，按模型 ID 配置的映射。每个键为请求中的模型名，值支持：\n    - `temperature`：可选，当请求未指定时使用的默认温度。\n    - `topP`：可选，当请求未指定时使用的默认 `top_p`。\n    - `topK`：可选，当请求未指定时使用的默认 `top_k`。\n    - `extraBody`：可选，按模型合入上游请求体的动态字段；请求体显式同名字段优先。OpenAI 兼容 provider 可用它配置 `enable_thinking`、`preserve_thinking`、`reasoning_effort` 等字段。`thinking_budget` 是 OpenAI 兼容 provider 的特殊覆盖项：配置在 `extraBody` 后，会在 Anthropic `thinking.budget_tokens` 翻译之后强制写入，并覆盖请求派生出的预算值。对于 provider name 为 `dashscope` 或 `baseUrl` 包含 `aliyuncs.com` 的 provider，请求派生的 `thinking_budget`（来自 Anthropic `thinking.budget_tokens`）会转发给上游；其他 OpenAI 兼容 provider 会移除请求派生的 `thinking_budget`，但 `extraBody` 中的 `thinking_budget` 仍然生效。对于 DashScope provider，当 `preserve_thinking` 未在 `extraBody` 或请求体中显式设置时，默认为 `true`。\n    - `pricing`：可选，按模型配置 token 单价，币种使用 provider 的 `pricingCurrency`，单位为每 100 万 tokens。支持 `input`、`output`、`cachedInput`（隐式缓存读）、`explicitCachedInput`（显式缓存读）和 `cacheCreationInput`。如需按输入 token 总量分档，可用带 `maxInputTokens` 的 `tiers`。\n    - `contextCache`：可选，provider name 为 `dashscope` 或 `baseUrl` 包含 `aliyuncs.com` 时默认 `true`，其他 OpenAI 兼容 provider 默认 `false`。用于启用阿里云百炼/DashScope 的显式缓存（explicit context cache），会按其 Context Cache 格式在最多 4 个 content block 上注入 `cache_control: { \"type\": \"ephemeral\" }`。缓存断点策略与 opencode 主链路保持一致：前 2 条 system 消息 + 最后 2 条非 system 消息。标记字符串 content 时会把 `system` / `user` / `assistant` / `tool` 消息转换为 text content part 数组；已有数组 content 则标记最后一个 part。如果模型本身已经支持隐式缓存，或上游不支持该显式缓存扩展字段，可在模型配置中设为 `false`。支持相同显式缓存扩展的非 DashScope provider 可设为 `true`。同时适用于 `/v1/messages` 和 `/v1/chat/completions` 路由。\n    - `supportPdf`：可选，控制该模型是否支持 PDF/document content。默认 `false`，不支持时会把 PDF 转成提示文本；设为 `true` 时会把 PDF/document 转成 OpenAI Chat Completions 的 file part。\n    - `toolContentSupportType`：可选，配置该模型的 tool result content 支持能力，值为 `array`、`image`、`pdf` 的数组。provider 侧未配置时默认只发送 string tool content。若 `supportPdf` 为 `true` 但这里不包含 `pdf`，tool result 里的 file part 会被转成 user role 消息。Copilot 主链路不使用这个 provider 默认，仍按 array + image 且不支持 PDF 的能力处理。\n    - `type`：可选，按模型覆盖 provider 的协议类型。支持 `anthropic`、`openai-compatible` 和 `openai-responses`。设置后，provider 的 `/v1/messages` 路由会使用该模型的 type 替代 provider 级别的 type 进行请求路由、认证头解析和上游端点选择。适用于 OpenCode Go 等上游对不同模型同时支持 OpenAI 兼容和 Anthropic Messages API 的 provider。覆盖 type 时，认证头按覆盖后 type 的默认值解析（Anthropic 默认 `x-api-key`；OpenAI 兼容/Responses 默认 `authorization`）。\n\n  DashScope 模型配置示例：\n  ```json\n  {\n    \"providers\": {\n      \"dashscope\": {\n        \"type\": \"openai-compatible\",\n        \"enabled\": true,\n        \"baseUrl\": \"https://dashscope.aliyuncs.com/compatible-mode\",\n        \"apiKey\": \"sk-your-dashscope-key\",\n        \"pricingCurrency\": \"CNY\",\n        \"models\": {\n          \"qwen3.7-plus\": {\n            \"temperature\": 1,\n            \"topP\": 0.95,\n            \"topK\": 20,\n            \"extraBody\": {\n              \"preserve_thinking\": true\n            }\n          },\n          \"glm-5.1\": {\n            \"temperature\": 0.7,\n            \"topP\": 0.95,\n            \"contextCache\": true,\n            \"pricing\": {\n              \"tiers\": [\n                {\n                  \"maxInputTokens\": 32000,\n                  \"input\": 6,\n                  \"cachedInput\": 1.2,\n                  \"explicitCachedInput\": 0.6,\n                  \"cacheCreationInput\": 7.5,\n                  \"output\": 24\n                },\n                {\n                  \"maxInputTokens\": 200000,\n                  \"input\": 8,\n                  \"cachedInput\": 1.6,\n                  \"explicitCachedInput\": 0.8,\n                  \"cacheCreationInput\": 10,\n                  \"output\": 28\n                }\n              ]\n            },\n            \"extraBody\": {\n              \"preserve_thinking\": true\n            }\n          }\n        }\n      }\n    }\n  }\n  ```\n  内置 token 价格覆盖 Codex GPT 模型（USD）、DashScope `qwen3.7-max`、`qwen3.7-plus`、`glm-5.1`、`glm-5.2`（CNY），DeepSeek `deepseek-v4-flash`、`deepseek-v4-pro`、`deepseek-chat`、`deepseek-reasoner`（CNY），以及 OpenCode Go 模型（`hy3`、`gpt-5.6-luna`、`glm-5.2`、`grok-4.5`、`deepseek-v4-flash`、`deepseek-v4-pro`、`kimi-k2.7-code`、`kimi-k3`、`mimo-v2.5`、`mimo-v2.5-pro`、`qwen3.7-plus`、`qwen3.7-max`、`minimax-m2.7`、`minimax-m3`，USD）。用户配置的 `pricing` 优先于内置价格。DashScope 若上游 usage 中出现 `cache_creation_input_tokens` 字段，cached tokens 按显式缓存读价计费；否则 `cachedInput` 作为隐式缓存读价。DeepSeek 的 `prompt_cache_hit_tokens` 会归入 cached input，`prompt_cache_miss_tokens` 会归入普通 input。\n- **smallModel：** 无工具预热消息的回退模型（例如 Claude Code 的探测请求）；默认是 `gpt-5-mini`。网关会对无工具的预热或探测请求强制使用该小模型，以避免消耗 premium 请求。该行为仅在 GitHub Copilot 账户为非 token-based 计费时生效（`token_based_billing` 为 false）；对于 token-based 计费账户，预热小模型回退会被跳过，因为不存在需要节省的 premium 请求配额。\n- **contextManagement：** 控制代理是否为 Responses API 附加 `context_management` 压缩指令。`messages` 作用于被翻译成 Responses API 的 Anthropic 风格 `/v1/messages` 请求，包括 `openai-responses` provider 的 Messages 路由，默认值为 `true`。`responses` 作用于 native `/v1/responses` 流量，包括 `provider/model` 别名和内置 `codex` provider，默认值为 `false`。只有在确认客户端支持 context management compaction 后，才建议在 Responses API 下启用 `responses`。启用后，请求体会带上 `context_management`，并在后续轮次中仅保留最新的压缩承载内容。**注意：** 对于 GPT-5.6 及以上模型（如 `gpt-5.6-sol`、`gpt-5.6-terra`、`gpt-5.6-luna`），context management 功能会被强制禁用，因为开启后会破坏这些模型的 prompt 缓存命中。此强制覆盖优先于 `contextManagement` 和 `modelResponsesApiCompactThresholds` 配置。\n - **modelResponsesApiCompactThresholds：** 按模型覆盖 Responses API 的 `compact_threshold`，仅在代理自动附加 `context_management` 时使用。它的优先级高于 `resolveResponsesCompactThreshold` 基于 `max_prompt_tokens * ratio` 的兜底阈值。默认将 `gpt-5.4` 和 `gpt-5.5` 设为 `217600`（`272000 * 0.8`）。未列出的模型继续使用原有兜底逻辑。\n- **modelReasoningEfforts：** `/v1/messages` 请求的模型级默认推理强度。仅当请求没有传入 `output_config.effort` 时，该配置才会生效。\n  - **优先级：** 请求中的 `output_config.effort` > `modelReasoningEfforts[model]` > 内置默认值（GPT-5.3+ 模型为 `xhigh`，其他模型为 `high`）。\n  - **转发字段：** 走 Copilot 原生 Messages API 时，最终值写入 `output_config.effort`；转换为 Responses API 时，最终值写入 `reasoning.effort`。\n  - **配置可选值：** `none`、`minimal`、`low`、`medium`、`high`、`xhigh`、`max`。\n- **useMessagesApi：** 当为 `true` 时，支持 Copilot 原生 `/v1/messages` 的 Claude 系模型会走 Messages API；否则回退到 `/chat/completions`。设为 `false` 可禁用 Messages API 路由，始终使用 `/chat/completions`。默认值为 `true`。\n- **useResponsesApiWebSocket：** 当为 `true` 时，Responses API 请求会优先对声明了 `ws:/responses` 的模型使用 Copilot websocket transport；仅声明 `/responses` 的模型仍走 HTTP。设为 `false` 可禁用 websocket 路由，并在模型支持 `/responses` 时使用 HTTP `/responses`。默认值为 `true`。如果遇到 Responses API WebSocket closed，一般是自己的网络问题。如果使用了 VPN，建议切换节点。\n- **useResponsesApiWebSearch：** 当为 `true` 时，服务端会保留 Responses API 中 `type: \"web_search\"` 的工具并透传到上游。设为 `false` 则会从 `/responses` payload 中移除这些工具。默认值为 `true`。\n- **messageApiWebSearchModel：** 顶层 Copilot `/v1/messages` 请求只包含服务端 `web_search` 工具时使用的全局模型，默认值为 `gpt-5-mini`。如果该值是 `provider/model` 别名，请求会进入对应 provider 的 Messages API 路径，并在转发前移除 provider 前缀。对于 Copilot GPT 模型，web search 会通过 `/responses` 执行。混合 `web_search` 与自定义工具的场景暂不支持，服务端会移除 server-side `web_search`。\n- **claudeTokenMultiplier：** 用于 Claude `/v1/messages/count_tokens` 请求在本地走 GPT tokenizer 估算时的乘数。默认值为 `1.15`。如果你的客户端仍然过晚触发上下文压缩，可以适当调大。这个配置只会在代理本地估算 Claude token 时生效；如果已经配置 `anthropicApiKey` 且 Anthropic token counting 调用成功，则会直接返回 Anthropic 的精确计数，不会使用这个乘数。\n- **anthropicApiKey：** 用于把 Claude `/v1/messages/count_tokens` 请求转发到 Anthropic 真实 token counting 端点的 API key，这样会返回精确计数，而不是 GPT tokenizer 估算值。也可通过环境变量 `ANTHROPIC_API_KEY` 设置。若未配置，或上游调用失败，则回退到由 `claudeTokenMultiplier` 控制的本地 GPT tokenizer 估算。\n\n编辑此文件后即可自定义 prompts，或替换为你自己的快速模型。修改完成后请重启服务（或重新执行命令），让缓存中的配置刷新生效。\n\n## API 认证\n\n- **受保护的普通路由：** 当配置了 `auth.apiKeys` 且非空时，除 `/`、`/usage-viewer` 和 `/usage-viewer/` 以外的普通路由都需要认证。\n- **Admin 路由：** 所有 `/admin/*` 路由都要求 `auth.adminApiKey`。如果缺失，服务会在启动时自动生成并在开始提供服务前写回 `config.json`。\n- **允许的认证头：**\n  - `x-api-key: <your_key>`\n  - `Authorization: Bearer <your_key>`\n- **CORS 预检：** `OPTIONS` 请求始终允许。\n- **未配置普通 key 时：** 普通路由仍可直接访问；但这条规则不适用于 `/admin/*`，后者只接受 `auth.adminApiKey`。\n\n普通受保护路由的示例请求：\n\n```sh\ncurl http://localhost:4141/v1/models \\\n  -H \"x-api-key: your_api_key\"\n```\n\nAdmin 路由的示例请求：\n\n```sh\ncurl http://localhost:4141/admin/config/model-mappings \\\n  -H \"x-api-key: your_admin_api_key\"\n```\n\n## API 端点\n\n服务端提供多个 OpenAI / Anthropic 兼容端点。请求会根据所选模型和 `provider/model` 别名路由到 GitHub Copilot、内置 `codex` provider 或已配置的 provider。\n\n### OpenAI 兼容端点\n\n这些端点模拟 OpenAI API 结构。\n\n| 端点 | 方法 | 说明 |\n| --- | --- | --- |\n| `POST /v1/responses` | `POST` | OpenAI 中用于生成模型响应的高级接口。支持 `openai-responses` provider 的 `provider/model` 别名。 |\n| `POST /v1/chat/completions` | `POST` | 为给定聊天对话创建模型响应。支持 `openai-compatible` provider 的 `provider/model` 别名；目标 provider 已配置时可在没有 Copilot 的情况下使用。 |\n| `GET /v1/models` | `GET` | 列出 Copilot 模型以及已启用 provider 的 `provider/model-id` 模型。来自 Codex 客户端（`User-Agent` 以 `codex` 开头）的请求会转发到 Codex Models 上游。 |\n| `POST /v1/embeddings` | `POST` | 创建表示输入文本的向量嵌入。 |\n\n### Codex 后端代理端点\n\n这些端点要求已有可用的 Codex 登录态。每个端点同时提供无版本前缀和 `/v1` 两种路径。\n\n| 端点 | 方法 | 说明 |\n| --- | --- | --- |\n| `POST /alpha/search`<br>`POST /v1/alpha/search` | `POST` | 将 JSON 请求体和查询参数透明转发到 Codex Alpha Search 上游。 |\n| `POST /images/generations`<br>`POST /v1/images/generations` | `POST` | 将 JSON 图片生成请求转发到 Codex Images 上游。请求未携带 `Content-Type` 时，网关默认补充 `application/json`。 |\n| `POST /images/edits`<br>`POST /v1/images/edits` | `POST` | 将图片编辑请求转发到 Codex Images 上游。请使用 `multipart/form-data`，并让 HTTP 客户端自动生成 `boundary`；网关会保留传入的 content type，并以流式方式转发上传请求体。 |\n\n对于以上所有端点，网关都会使用当前 Codex 登录态覆盖客户端的 authorization 和 account header，保留查询参数及兼容的请求头，并返回上游状态码、响应头和响应体。\n\n### Anthropic 兼容端点\n\n这些端点设计为兼容 Anthropic Messages API。provider 级的 models、Responses、alpha-search 和 images 路由同时支持无版本前缀与 `/v1` 两种路径；Messages 路由仍使用 `/v1`。\n\n| 端点 | 方法 | 说明 |\n| --- | --- | --- |\n| `POST /v1/messages` | `POST` | 为给定对话创建模型响应。支持已配置 provider 的 `provider/model` 别名，包括通过 `openai-compatible` provider 做翻译。 |\n| `POST /v1/messages/count_tokens` | `POST` | 计算一组消息的 token 数。支持已配置 provider 的 `provider/model` 别名。 |\n| `POST /:provider/v1/messages` | `POST` | 将 Anthropic Messages 请求代理到已配置的 Anthropic provider，或翻译到 OpenAI 兼容 / OpenAI Responses provider。 |\n| `GET /:provider/models`<br>`GET /:provider/v1/models` | `GET` | 将模型列表请求代理到已配置的 provider。对 `codex` 默认返回内置模型目录；Codex 客户端（`User-Agent` 以 `codex` 开头）会转发到 Codex Models 上游。 |\n| `POST /:provider/v1/messages/count_tokens` | `POST` | 为 provider 路由请求在本地计算 token 数。 |\n| `POST /:provider/responses`<br>`POST /:provider/v1/responses` | `POST` | 将 OpenAI Responses 请求代理到已配置的 `openai-responses` provider（含 `codex`）。 |\n| `POST /:provider/alpha/search`<br>`POST /:provider/v1/alpha/search` | `POST` | 代理 alpha-search 请求。对 `codex` 转发到 Codex Alpha Search 上游；其他 provider 转发到 `{baseUrl}/v1/alpha/search`。 |\n| `POST /:provider/images/generations`<br>`POST /:provider/v1/images/generations` | `POST` | 代理图片生成。对 `codex` 使用 Codex Images 上游；其他 provider 转发到 `{baseUrl}/v1/images/generations`（15 分钟超时）。 |\n| `POST /:provider/images/edits`<br>`POST /:provider/v1/images/edits` | `POST` | 代理图片编辑。对 `codex` 使用 Codex Images 上游；其他 provider 以 multipart/流式方式转发到 `{baseUrl}/v1/images/edits`（15 分钟超时）。 |\n\n### 使用量监控端点\n\n用于监控 Copilot 用量与额度的新端点。\n\n| 端点 | 方法 | 说明 |\n| --- | --- | --- |\n| `GET /usage` | `GET` | 获取详细的 Copilot 使用统计与额度信息。 |\n| `GET /token` | `GET` | 获取当前 API 正在使用的 Copilot token。 |\n\n### Admin / 配置端点\n\n这些端点用于本地管理操作，只接受 `auth.adminApiKey`。\n\n| 端点 | 方法 | 说明 |\n| --- | --- | --- |\n| `GET /admin/config/model-mappings` | `GET` | 返回当前 `config.json` 路径以及生效中的 `modelMappings` 映射。 |\n| `POST /admin/config/model-mappings` | `POST` | 只更新 `config.json` 里的 `modelMappings` 字段，并回传更新后的结果。 |\n\n## 使用示例\n\n常用 `npx` 命令：\n\n```sh\n# 基础启动\nnpx @jeffreycao/copilot-api@latest start\n\n# 自定义端口并开启详细日志\nnpx @jeffreycao/copilot-api@latest start --port 8080 --verbose\n\n# 执行认证流程\nnpx @jeffreycao/copilot-api@latest auth login\n\n# 配置第三方 provider，然后不依赖 GitHub Copilot 启动\nnpx @jeffreycao/copilot-api@latest auth login --provider dashscope\nnpx @jeffreycao/copilot-api@latest start\n\n# 以 JSON 格式输出调试信息\nnpx @jeffreycao/copilot-api@latest debug --json\n\n# 用 Bun 而不是 Node.js 运行已发布 CLI\nbunx --bun @jeffreycao/copilot-api@latest start\n```\n\n配置 `dashscope` 后的 OpenAI 兼容 provider 调用示例：\n\n```sh\ncurl http://localhost:4141/v1/chat/completions \\\n  -H \"content-type: application/json\" \\\n  -d '{\"model\":\"dashscope/qwen3.6-plus\",\"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]}'\n\ncurl http://localhost:4141/dashscope/v1/messages \\\n  -H \"content-type: application/json\" \\\n  -d '{\"model\":\"qwen3.6-plus\",\"max_tokens\":1024,\"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]}'\n```\n\n## 使用建议\n\n<a id=\"claudemd-or-agentsmd-recommended-content\"></a>\n\n### CLAUDE.md 或 AGENTS.md 推荐内容\n\n如果你想手动加入这些提醒，请在 Claude Code 的 `CLAUDE.md`，或 opencode/codex 的 `AGENTS.md` 中加入以下内容：\n\n```\n- Prohibited from directly asking questions to users, MUST use question tool.\n- Once you can confirm that the task is complete, MUST use question tool to make user confirm. The user may respond with feedback if they are not satisfied with the result, which you can use to make improvements and try again, after try again, MUST use question tool to make user confirm again.\n```\n"}, "bdf6879d12488b3c3c32fd9c73bc2cb71cc8eb73": {"t": 1785765532.9497478, "n": 34033, "h": "02e69212e7ca8183", "c": "# Copilot API Proxy\n\n[English](./README.md) | 简体中文\n\n## 重要说明\n\n> [!IMPORTANT]\n> **使用前请先注意以下几点：**\n>\n> 1. **Claude Code 配置：** 与 Claude Code 搭配使用时，请将模型 ID 配置为 `claude-opus-4-8`。示例 claude `settings.json` 见 [通过 `settings.json` 手动配置](#manual-configuration-with-settingsjson)。\n>\n> 2. **内置 `copilot`、`codex` 与第三方 provider：** 执行 `npx @jeffreycao/copilot-api@latest auth`，可选择 `copilot`、`codex`、`deepseek`、`custom` 等 provider。\n>\n> 3. **注意事项：** README 顶部移除的 GitHub Copilot warning 见 [GitHub Copilot 安全提示](./NOTICE.md#github-copilot-security-notice)。\n\n---\n\n## 项目概览\n\n这是一个小型 AI gateway，可以使用 GitHub Copilot、内置 `codex` provider，也可以使用 DashScope 等已配置的第三方 provider。GitHub Copilot 现在是可选能力：如果本地没有 GitHub token，只要至少配置了一个启用中的 provider，服务仍可按 provider-only 模式启动。\n\nAI gateway 会从同一个本地端点暴露 OpenAI / Anthropic 兼容 API，让 [Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview)、OpenCode、Codex 和 OpenAI 兼容客户端可以共用同一个本地服务。\n\n在 GitHub Copilot 路径上，AI gateway 会在可用时优先使用 Copilot 原生的 Anthropic 风格 Messages API，在重工具调用场景下保留更原生的 Claude 行为。\n\n## 功能特性\n\n- **OpenAI 与 Anthropic 双兼容**：通过 `/v1/responses`、`/v1/chat/completions`、`/v1/models`、`/v1/embeddings` 和 `/v1/messages` 对外暴露同一个本地 AI gateway。\n- **Copilot 可选**：有 GitHub 凭据时可以使用 GitHub Copilot，没有 GitHub 凭据时也可以只依赖已配置的 provider 运行。\n- **同一网关接入 Copilot、`codex` 与第三方 provider**：可统一路由 GitHub Copilot、内置 `codex` provider 和配置好的外部 provider。\n- **第三方 provider 可独立启动**：配置 DashScope、DeepSeek、OpenRouter 或自定义 provider 后，不需要 GitHub Copilot 登录即可启动 AI gateway。\n- **OpenAI 兼容 provider 同时支持 chat 和 Messages API**：`openai-compatible` provider 可通过顶层 `/v1/chat/completions` 搭配 `model: \"provider/model\"` 提供 Chat Completions，也可通过 `/v1/messages` 完成 Anthropic Messages 的请求/响应翻译。\n- **面向 Claude 的更原生 Copilot 路由**：优先使用原生 `/v1/messages`，保留 Claude 风格工具流，支持 Anthropic beta 能力、通过 Responses-capable 模型支持 Claude WebSearch，并保留 subagent / session 标记。\n- **Claude Code 与 OpenCode 集成**：兼容 Claude Code 与 OpenCode，也支持通过 `@ai-sdk/anthropic` 直接作为 Anthropic provider 使用。\n- **灵活的认证与部署选项**：支持交互式登录、直接 token、个人 / Business / Enterprise、GitHub Enterprise、opencode OAuth 和自定义数据目录。\n- **多 provider 路由**：可暴露 `/:provider/...` 路由，也可在顶层 API 上使用 `model: \"provider/model\"`。\n\n## 前置要求\n\n- Bun（>= 1.2.x）\n- 如果要通过 `npx` 运行已发布 CLI，需要 Node.js\n- 只有在使用 GitHub Copilot provider 时，才需要已订阅 Copilot 的 GitHub 账号\n- 如果不使用 GitHub Copilot，需要至少一个已配置 provider 的 API key 或 OAuth 登录\n\n## 安装\n\n安装依赖：\n\n```sh\nbun install\n```\n\n直接从源码启动服务：\n\n```sh\nbun run start start\n```\n\n## 从源码运行\n\n本项目可以通过多种方式从源码运行：\n\n### 开发模式\n\n```sh\nbun run dev start\n```\n\n### 生产模式\n\n```sh\nbun run start start\n```\n\n## 通过 npx 使用\n\n你可以直接用 npx 运行本项目：\n\n> [!IMPORTANT]\n> 通过 `npx` 运行时，token usage 存储会使用 Node 内置的 `node:sqlite` 模块。该能力会在 Node.js >= 22.13.0 时启用；Node.js < 22.13.0 时 CLI 仍可启动，但会禁用 token usage 存储。\n>\n> 如果不升级 Node.js 但仍需要 token usage 存储，可以改用 Bun 运行已发布 CLI：`bunx --bun @jeffreycao/copilot-api@latest start`。\n\n```sh\nnpx @jeffreycao/copilot-api@latest start\n```\n\n带参数示例：\n\n```sh\nnpx @jeffreycao/copilot-api@latest start --port 8080\n```\n\n如果只想做认证或 provider 配置：\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth\n```\n\n如果要不依赖 GitHub Copilot 运行，先配置至少一个 provider，然后正常启动服务：\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth login --provider dashscope\nnpx @jeffreycao/copilot-api@latest start\n```\n\n## 配合 Docker 使用\n\n构建镜像：\n\n```sh\ndocker build -t copilot-api .\n```\n\n通过 bind mount 运行容器，让认证数据在重启后保留：\n\n```sh\nmkdir -p ./copilot-data\ndocker run -p 4141:4141 -v $(pwd)/copilot-data:/root/.local/share/copilot-api copilot-api\n```\n\n这会把宿主机上的 `./copilot-data` 映射到容器内的 `/root/.local/share/copilot-api`，用于持久化 GitHub 认证数据、provider 配置和其他 gateway 状态。\n\n也可以直接通过环境变量传入 GitHub token：\n\n```sh\ndocker run -p 4141:4141 -e GH_TOKEN=your_github_token_here copilot-api\n```\n\n## Electron 桌面应用\n\n如果你更喜欢图形界面，仓库里还提供了位于 `desktop/` 的 Electron 桌面应用。它支持 GitHub Copilot 登录、OpenAI Codex OAuth，以及 DeepSeek、DashScope、OpenRouter 或自定义 provider 的 API Key 配置。授权或配置 provider 后，可以一键启动或停止本地代理，并在界面里直接查看本地端点、鉴权 Header、可用模型、额度和日志。\n\n设置页还可以配置 `OAuth App`、`API Home`、`Enterprise URL`、详细日志以及最小化到托盘。Windows x64（`.exe`）、macOS Apple Silicon（`.dmg`）和 Linux x64（`.AppImage`）安装包发布在 GitHub Releases：\n\nhttps://github.com/caozhiyuan/copilot-api/releases\n\nLinux 用户需要先为下载的 AppImage 添加执行权限：\n\n```sh\nchmod +x Copilot-API-*-linux-x86_64.AppImage\n./Copilot-API-*-linux-x86_64.AppImage\n```\n\n下载对应平台的安装包后，在应用内授权或配置 provider，选择端口并启动服务，再把你的客户端指向应用里显示的本地端点即可。发布版桌面应用使用随包内置的 Electron 运行时，正常使用不需要额外安装 Node.js；token usage 历史记录会在该内置运行时支持 SQLite 时启用。\n\n桌面应用里的高级配置页会通过 `GET/POST /admin/config/model-mappings` 读写这份共享的模型映射。同一份映射会统一作用于 `POST /v1/messages`、`POST /v1/messages/count_tokens`、`POST /v1/responses` 和 `POST /v1/chat/completions`，不再按接口区分。它使用的是 `auth.adminApiKey`，不是普通的 `auth.apiKeys`；应用会在服务启动并自动生成该 key 后，直接从 `config.json` 读取它来发起请求。\n\n### 桌面应用截图\n\n下面展示了桌面应用中的首页、Token 用量统计页面：\n\n<p align=\"center\">\n  <img src=\"./docs/screenshots/desktop-dashboard.png\" alt=\"Copilot API 桌面应用首页\" width=\"49%\" />\n  <img src=\"./docs/screenshots/desktop-token-usage.png\" alt=\"Copilot API 桌面应用 Token 用量页\" width=\"49%\" />\n</p>\n\n## 与 Claude Code 一起使用\n\n这个 AI gateway 可以为 [Claude Code](https://docs.anthropic.com/en/claude-code) 提供后端能力。Claude Code 是 Anthropic 提供的实验性面向开发者的对话式 AI 助手。\n\n有两种方式可以把 Claude Code 配置为使用这个 AI gateway：\n\n### 通过 `--claude-code` 标志进行交互式配置\n\n执行带 `--claude-code` 的 `start` 命令开始：\n\n```sh\nnpx @jeffreycao/copilot-api@latest start --claude-code\n```\n\n你不再需要手动选择模型。Gateway 会自动检测每个 Claude Code 尺寸档位对应的最新可用模型——opus 映射到最新的 Opus 模型，sonnet 映射到最新的 Sonnet 模型，haiku 映射到最新的 Haiku 模型——并生成相应设置 `ANTHROPIC_DEFAULT_OPUS_MODEL`、`ANTHROPIC_DEFAULT_SONNET_MODEL` 和 `ANTHROPIC_DEFAULT_HAIKU_MODEL` 的命令。若某个档位没有匹配的可用模型，则会被省略。该命令会被复制到剪贴板，并设置 Claude Code 使用这个 AI gateway 所需的环境变量。\n\n在新的终端中粘贴并执行这条命令，即可启动 Claude Code。\n\n<a id=\"manual-configuration-with-settingsjson\"></a>\n\n### 通过 `settings.json` 手动配置\n\n另一种方式是在项目根目录中创建 `.claude/settings.json` 文件，并写入 Claude Code 所需的环境变量。这样你就不需要每次都运行交互式配置了。\n\n下面是一个 `.claude/settings.json` 示例：\n\n```json\n{\n  \"env\": {\n    \"ANTHROPIC_BASE_URL\": \"http://localhost:4141\",\n    \"ANTHROPIC_AUTH_TOKEN\": \"dummy\",\n    \"ANTHROPIC_MODEL\": \"gpt-5.6-sol[1m]\",\n    \"ANTHROPIC_DEFAULT_SONNET_MODEL\": \"gpt-5.6-sol[1m]\",\n    \"ANTHROPIC_DEFAULT_HAIKU_MODEL\": \"gpt-5.6-luna[1m]\",\n    \"CLAUDE_CODE_AUTO_COMPACT_WINDOW\": \"272000\",\n    \"CLAUDE_CODE_USE_VERTEX\": \"0\",\n    \"CLAUDE_CODE_USE_BEDROCK\": \"0\",\n    \"DISABLE_NON_ESSENTIAL_MODEL_CALLS\": \"1\",\n    \"CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC\": \"1\",\n    \"CLAUDE_CODE_ATTRIBUTION_HEADER\": \"0\",\n    \"CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION\": \"false\",\n    \"CLAUDE_CODE_DISABLE_TERMINAL_TITLE\": \"true\",\n    \"CLAUDE_CODE_ENABLE_AWAY_SUMMARY\": \"0\"\n  },\n  \"alwaysThinkingEnabled\": true,\n  \"effortLevel\": \"xhigh\",\n  \"showThinkingSummaries\": true\n}\n```\n\n- 请根据需要替换 `ANTHROPIC_MODEL`、`ANTHROPIC_DEFAULT_OPUS_MODEL`、`ANTHROPIC_DEFAULT_SONNET_MODEL` 和 `ANTHROPIC_DEFAULT_HAIKU_MODEL`。配置完成后，请安装 claude code 插件，见 [插件集成](#plugin-integrations)。\n- 如果你使用的是 codex provider，建议**不要**将模型名配置成 `codex/xxx` 格式（如 `codex/gpt-5.6-sol`）。Claude Code 会针对 `codex/` 前缀做降智行为——例如每次请求时移除所有之前返回的思考块（thinking blocks）。请使用纯模型名（如 `gpt-5.6-sol`），并在 `config.json` 中配置 `modelMappings` 将其映射回 codex provider：\n  ```json\n  \"modelMappings\": {\n    \"gpt-5.6-sol\": \"codex/gpt-5.6-sol\",\n    \"gpt-5.6-terra\": \"codex/gpt-5.6-terra\",\n    \"gpt-5.6-luna\": \"codex/gpt-5.6-luna\"\n  },\n  ```\n- 将 `CLAUDE_CODE_ATTRIBUTION_HEADER` 设为 `0` 可以阻止 Claude Code 在 system prompt 中附加计费和版本信息，从而避免 prompt cache 失效。\n- 关闭 `CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION` 和 `CLAUDE_CODE_ENABLE_AWAY_SUMMARY` 可以避免不必要地消耗额度。\n- Claude Code WebSearch 已支持纯搜索请求。Copilot 路径请保持全局 `messageApiWebSearchModel` 指向 Responses-capable GPT 模型或 `provider/model` 别名；provider 路由请使用原生 Anthropic provider 或 `openai-responses` provider。只有在你明确想禁止这类流量时，才需要把 `WebSearch` 加到 `permissions.deny`。\n- 如果使用的不是 Claude 模型，请不要启用 `ENABLE_TOOL_SEARCH`。如果使用的是 Claude 模型，则可以启用 `ENABLE_TOOL_SEARCH`。当前 Claude Code 使用的是客户端 tool search 模式，在该模式下每次加载 defer tools 都需要额外请求一次。\n- `CLAUDE_CODE_AUTO_COMPACT_WINDOW`：设置用于自动压缩计算的上下文容量（以 token 为单位）。默认使用模型自身的上下文窗口：标准模型为 200K，扩展上下文模型为 1M。使用 1M 上下文模型（如 `claude-opus-4-6[1m]`）时，可设置一个较低的值（如 `500000`）将窗口视为 500K 用于压缩计算。该值受限于模型的实际上下文窗口上限。`CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` 会基于此值的百分比生效。设置此变量可将压缩阈值与状态栏的 `used_percentage` 解耦（后者始终使用模型的完整上下文窗口）。\n\n更多选项见：[Claude Code settings](https://docs.anthropic.com/en/docs/claude-code/settings#environment-variables)\n\n也可以参考 IDE 集成说明：[Add Claude Code to your IDE](https://docs.anthropic.com/en/docs/claude-code/ide-integrations)\n\n## 与 OpenCode 一起使用\n\nOpenCode 已经有直接的 GitHub Copilot provider。本节适用于你希望让 OpenCode 通过 `@ai-sdk/anthropic` 指向这个 AI gateway，并复用本 README 前面提到的 agent 行为时。\n\n### 最小配置\n\n使用 OpenCode OAuth app 启动 AI gateway：\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth --oauth-app=opencode\nnpx @jeffreycao/copilot-api@latest start\n```\n\n然后让 OpenCode 通过 `@ai-sdk/anthropic` 指向这个 AI gateway。\n\n示例 `~/.config/opencode/opencode.json`：\n\n```json\n{\n  \"$schema\": \"https://opencode.ai/config.json\",\n  \"provider\": {\n    \"local\": {\n      \"npm\": \"@ai-sdk/anthropic\",\n      \"name\": \"My Local\",\n      \"options\": {\n        \"baseURL\": \"http://localhost:4141/v1\",\n        \"apiKey\": \"dummy\"\n      },\n      \"models\": {\n        \"gpt-5.4\": {\n          \"name\": \"gpt-5.4\",\n          \"modalities\": {\n            \"input\": [\"text\", \"image\"],\n            \"output\": [\"text\"]\n          },\n          \"limit\": {\n            \"context\": 400000,\n            \"input\": 272000,\n            \"output\": 128000\n          }\n        },\n        \"claude-sonnet-4.6\": {\n          \"id\": \"claude-sonnet-4.6\",\n          \"name\": \"claude-sonnet-4.6\",\n          \"modalities\": {\n            \"input\": [\"text\", \"image\"],\n            \"output\": [\"text\"]\n          },\n          \"limit\": {\n            \"context\": 200000,\n            \"output\": 32000\n          },\n          \"options\": {\n            \"thinking\": {\n              \"type\": \"adaptive\"\n            },\n            \"effort\": \"max\"\n          }\n        }\n      }\n    }\n  }\n}\n```\n\n这些字段的重要性：\n\n- `npm: \"@ai-sdk/anthropic\"` 是关键。OpenCode 会以 Anthropic Messages 语义与这个 AI gateway 通信，而不是把一切扁平化为 OpenAI Chat Completions。\n- `options.baseURL` 应设为 `http://localhost:4141/v1`；Anthropic SDK 会自动补上 `/messages`、`/models` 和 `/messages/count_tokens`。\n- 如果你在此代理中启用了 `auth.apiKeys`，请把 `dummy` 替换为真实 key；否则任意占位值都可以。\n\n## 与 Codex 一起使用\n\n这个 AI gateway 也可以为 Codex 提供后端能力。\n\n### Codex `config.toml` 参考配置\n\n把以下 `[model_providers.copilot_api]` 段加入你的 Codex `~/.codex/config.toml`：\n\n```toml\nmodel_provider = \"copilot_api\"\nmodel_reasoning_summary = \"auto\"\nmodel_context_window = 272000\nmodel_auto_compact_token_limit = 244800\n\n[model_providers.copilot_api]\nname = \"OpenAI\"\nbase_url = \"http://localhost:4141\"\nenv_key = \"GITHUB_COPILOT_API_KEY\"\nrequires_openai_auth = true\nsupports_websockets = false\nwire_api = \"responses\"\nrequest_max_retries = 3\nstream_max_retries = 1\nstream_idle_timeout_ms = 300000\n\n[features]\nremote_compaction_v2 = true\n\n[analytics]\nenabled = false\n```\n\n> [!NOTE]\n> 此配置仅限于 Codex 与 GitHub Copilot provider。`name` 一定要配置为 `\"OpenAI\"`。它可以缓解 Codex local compact 不命中缓存的问题。\n> 如果使用 codex provider，建议将 `base_url` 配置为 `\"http://localhost:4141/codex\"`。\n\n## GPT Tool Search\n\n对于 `gpt-5.4+` 这类 GPT Responses 模型，这个 AI gateway 可以通过一个很小的 MCP bridge 暴露 Responses `tool_search`。Claude Code 和 opencode 都可以使用同一个 bridge，前提是客户端会加载 MCP server，并且 Anthropic Messages 流量会经过这个 AI gateway。\n\nGPT 模型不要设置 Claude Code 原生的 `ENABLE_TOOL_SEARCH`。这个开关启用的是 Claude Code 自己的客户端 tool search 模式，可能导致 deferred 工具定义不再转发给 AI gateway。这个 AI gateway 需要完整的工具定义，这样才能只保留那一小组常驻加载工具，其余工具统一转换为 Responses deferred namespace。\n\n如果你安装了 `tool-search@copilot-api-marketplace`，Claude Code 会自动带上这个 MCP bridge，可以跳过下面这段 Claude Code MCP 手动配置。\n\n请把 tool search bridge 加到 Claude Code 使用的 MCP 配置中：\n\n```json\n{\n  \"mcpServers\": {\n    \"tool_search\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@jeffreycao/copilot-api@latest\", \"mcp\"]\n    }\n  }\n}\n```\n\n请把 tool search bridge 加到 opencode 使用的 MCP 配置中：\n\n```json\n{\n  \"mcp\": {\n    \"tool_search\": {\n      \"type\": \"local\",\n      \"command\": [\"npx\", \"-y\", \"@jeffreycao/copilot-api@latest\", \"mcp\"]\n    }\n  }\n}\n```\n\n本地开发时可以将命令换成 `bun`，参数换成 `[\"run\", \"./src/main.ts\", \"mcp\"]`。\n\nAI gateway 内部现在会把 OpenAI Responses `tool_search` 配置成 client-executed 模式。deferred tools 仍然会作为可搜索 namespace 暴露给模型，但会明确要求模型直接返回下一步要加载的精确工具名列表。\n\n该 bridge 使用直接工具选择，不做 query 搜索。工具入参是 `names`，值为逗号分隔的精确 deferred 工具名，例如 `TaskList,TaskGet,mcp__fetch__fetch`。\n\n<a id=\"plugin-integrations\"></a>\n\n## 插件集成\n\n本项目为 Claude Code 和 opencode 提供了插件集成。\n\n#### Claude Code 插件集成（基于 marketplace）\n\nClaude Code 集成现在拆分为两个插件：\n\n- `agent-inject` 会在 `SubagentStart` 时注入 `__SUBAGENT_MARKER__...`，以便 AI gateway 推导 `x-initiator: agent`。\n- `tool-search` 会注册用于 GPT Responses deferred tool loading 的 `tool_search` MCP bridge。\n\n- 本仓库中的 marketplace catalog：`.claude-plugin/marketplace.json`\n- 本仓库中的插件源码：`plugin/claude/agent-inject`、`plugin/claude/tool-search`\n\n远程添加 marketplace：\n\n```sh\n/plugin marketplace add https://github.com/caozhiyuan/copilot-api.git\n```\n\n从 marketplace 安装插件：\n\n```sh\n/plugin install agent-inject@copilot-api-marketplace\n/plugin install tool-search@copilot-api-marketplace\n```\n\n安装后，`agent-inject` 会在 `SubagentStart` 时注入 `__SUBAGENT_MARKER__...`，AI gateway 会利用它推导 `x-initiator: agent`。\n\n`agent-inject` 还会注册一个 `UserPromptSubmit` hook，并返回 `{\"continue\": true}`；同时它也可以通过环境变量注入 `SessionStart` reminder 规则：\n\n- `CLAUDE_PLUGIN_ENABLE_QUESTION_RULES=1` 会自动为 Claude Code 启用两条关于使用 `question` 工具的提醒。你也可以把同样的提醒手动写进 `CLAUDE.md`；见 [CLAUDE.md 或 AGENTS.md 推荐内容](#claudemd-or-agentsmd-recommended-content)。\n- `CLAUDE_PLUGIN_ENABLE_NO_BACKGROUND_AGENTS_RULE=1` 会启用关于避免在 agent hooks 中使用 `run_in_background: true` 的提醒。\n\n`tool-search` 插件内置了 [GPT Tool Search](#gpt-tool-search) 一节描述的同一个 MCP bridge，因此安装该插件后，Claude Code 用户无需再手动配置 `tool_search` server。\n\n#### Opencode 插件\n\nsubagent 标记生成器被打包为一个 opencode 插件，位于 `plugin/opencode/subagent-marker.js`。\n\n**安装方式：**\n\n将插件文件复制到你的 opencode 插件目录：\n\n```sh\n# 克隆或下载本仓库后复制该插件\ncp plugin/opencode/subagent-marker.js ~/.config/opencode/plugins/\n```\n\n或者手动在 `~/.config/opencode/plugins/subagent-marker.js` 创建该文件，并填入插件内容。\n\n**功能：**\n\n- 跟踪 subagent 创建的子会话\n- 自动在 subagent 聊天消息前添加 marker system reminder（`__SUBAGENT_MARKER__...`）\n- 设置 `x-session-id` 请求头以跟踪会话\n- 让这个 AI gateway 能够把来自 subagent 的请求识别为 `x-initiator: agent`\n\n该插件会挂接到 `session.created`、`session.deleted`、`chat.message` 和 `chat.headers` 事件上，以无缝提供 subagent marker 能力。\n\n## 使用量查看器\n\n服务启动后，控制台会输出一个 Copilot 使用量看板 URL。这个看板是一个用于监控 API 用量的 Web 界面。\n\n1. 启动服务。例如使用 npx：\n   ```sh\n   npx @jeffreycao/copilot-api@latest start\n   ```\n2. 服务会输出一个 usage viewer 的 URL。将它复制到浏览器中打开，形式大致如下：\n   `http://localhost:4141/usage-viewer?endpoint=http://localhost:4141/usage`\n   - 如果你在 Windows 上使用 `start.bat` 脚本，这个页面会自动打开。\n\n看板提供了更易读的 Copilot 用量视图：\n\n> token usage 历史记录需要 Bun 或 Node.js >= 22.13.0。Node.js < 22.13.0 时服务会正常运行，但 token usage 存储会被禁用。\n\n- **API Endpoint URL**：通过 URL 查询参数指定 API endpoints，默认指向本地服务。支持手动切换为其他兼容 endpoints。\n- **x-api-key 认证**：如果启用了 API Key 认证，可填入 `x-api-key` 请求头。密钥会持久化保存在浏览器本地存储中。\n- **Period 选择器**：支持 Day / Week / Month 三种时间范围，切换时 URL 参数会自动同步，方便收藏和分享。\n- **Fetch Data**：点击 \"Refresh\" 按钮加载或刷新使用数据。页面加载时也会自动拉取数据。\n- **Copilot Quotas 额度**：通过进度条展示 Chat、Completions 等不同服务的额度使用情况，悬停可查看已用/剩余详情。\n- **Token Usage 指标卡片**：汇总当前周期的 Total、Input、Output、Cache Read、Cache Write、Requests 和预估费用。\n- **趋势图（Week / Month）**：提供按模型和指标筛选的折线趋势图，点击数据点可查看单日用量明细。\n- **Model Breakdown 表格**：按模型维度列出周期内的请求数、输入/输出/缓存 token 和预计费用。\n- **Request Events 分页列表**：按时间排序的请求事件记录，支持分页浏览，含时间戳、模型、请求 ID 和 token 用量。\n- **Detailed Information**：展示 API 返回的完整 JSON 响应，便于深入分析所有可用统计数据。\n- **URL-based Configuration**：也可通过 `endpoint` 和 `period` 查询参数直接指定 API 端点与时间范围。例如：\n  `http://localhost:4141/usage-viewer?endpoint=http://your-api-server/usage&period=week`\n\n### Usage Viewer 截图\n\n<p align=\"center\">\n  <img src=\"./docs/screenshots/usage-viewer.png\" alt=\"Copilot API Usage Viewer 页面\" width=\"900\" />\n</p>\n\n## 命令结构\n\nCopilot API 现在使用子命令结构，主要命令包括：\n\n- `start`：启动 AI gateway 服务。如果已有 GitHub token，则启用 Copilot 路径；如果没有 GitHub token，但存在至少一个启用中的 provider，则按 provider-only 模式启动；如果两者都没有，会引导你配置 provider。\n- `auth`：仅执行 provider 登录或配置流程，不启动服务。可用于 GitHub Copilot 登录、Codex OAuth，或第三方 provider API key 配置。\n- `debug`：显示诊断信息，包括版本、运行时详情、文件路径以及认证状态，便于排障与支持。\n\n## 命令行选项\n\n### 全局选项\n\n以下选项可用于任意子命令。若在子命令之前传入，请使用 `--key=value` 形式：\n\n| 选项 | 说明 | 默认值 | 别名 |\n| --- | --- | --- | --- |\n| --api-home | API home 目录路径（设置 `COPILOT_API_HOME`） | 无 | 无 |\n| --oauth-app | OAuth app 标识符（设置 `COPILOT_API_OAUTH_APP`） | 无 | 无 |\n| --enterprise-url | GitHub Enterprise URL（设置 `COPILOT_API_ENTERPRISE_URL`） | 无 | 无 |\n\n### Start 命令选项\n\n以下是 `start` 命令可用的命令行选项：\n\n| 选项 | 说明 | 默认值 | 别名 |\n| --- | --- | --- | --- |\n| --port | 监听端口 | 4141 | -p |\n| --verbose | 启用详细日志 | false | -v |\n| --github-token | 直接提供 GitHub token（必须通过 `auth` 子命令生成） | 无 | -g |\n| --claude-code | 生成一个使用 Copilot API 配置启动 Claude Code 的命令 | false | -c |\n| --show-token | 在获取和刷新时显示 GitHub 与 Copilot token | false | 无 |\n| --proxy-env | 从环境变量初始化代理 | false | 无 |\n\n### Auth 命令选项\n\n| 选项 | 说明 | 默认值 | 别名 |\n| --- | --- | --- | --- |\n| --provider | 要登录或配置的 provider（`copilot`、`codex`、`opencode-go`、`deepseek`、`dashscope`、`openrouter` 或 `custom`） | 交互选择 | 无 |\n| --verbose | 启用详细日志 | false | -v |\n| --show-token | 认证时显示 GitHub token | false | 无 |\n\n只有在需要启用 GitHub Copilot provider 时，才需要执行 `copilot-api auth login --provider copilot`。使用 `codex` 或第三方 provider-only 模式不要求配置 Copilot。\n\n使用 `copilot-api auth login --provider deepseek`、`--provider dashscope`、`--provider openrouter` 或 `--provider opencode-go` 可以通过 CLI 快速新增或更新这些常用第三方 provider。DeepSeek 会提示输入掩码显示的 `apiKey`、provider `type`（默认 `anthropic`），以及默认 `https://api.deepseek.com/anthropic` 的 `baseUrl`。DashScope 会提示输入掩码显示的 `apiKey`、provider `type`（默认 `openai-compatible`）和预填默认值的 `baseUrl`。OpenRouter 只提示输入掩码显示的 `apiKey` 和预填默认值的 `baseUrl`，并固定写入 `type: \"anthropic\"`。OpenCode Go 只提示输入掩码显示的 `apiKey` 和预填默认值的 `baseUrl`，并固定写入 `type: \"openai-compatible\"`（baseUrl `https://opencode.ai/zen/go`）。配置并启用 provider 后，`copilot-api start` 可在没有 GitHub token 的情况下启动。\n\n使用 `copilot-api auth login --provider custom` 可以通过 CLI 新增或更新其他第三方 provider。命令会依次提示输入 provider name、项目支持的 type（`anthropic`、`openai-compatible` 或 `openai-responses`）、`baseUrl`、掩码显示的 `apiKey` 和 `authType`；`authType` 可保持 type 默认值，也可选择 `x-api-key` / `authorization`。\n\n### Debug 命令选项\n\n| 选项 | 说明 | 默认值 | 别名 |\n| --- | --- | --- | --- |\n| --json | 以 JSON 输出调试信息 | false | 无 |\n\n<a id=\"configuration-configjson\"></a>\n\n## 配置（config.json）\n\n- **位置：** Linux/macOS 为 `~/.local/share/copilot-api/config.json`，Windows 为 `%USERPROFILE%\\.local\\share\\copilot-api\\config.json`。\n- **默认结构：**\n  ```json\n  {\n    \"auth\": {\n      \"apiKeys\": [],\n      \"adminApiKey\": \"<startup 自动生成>\"\n    },\n    \"providers\": {},\n    \"modelMappings\": {},\n    \"extraPrompts\": {\n      \"gpt-5-mini\": \"<built-in exploration prompt>\"\n    },\n    \"smallModel\": \"gpt-5-mini\",\n    \"contextManagement\": {\n      \"messages\": true,\n      \"responses\": false\n    },\n    \"modelResponsesApiCompactThresholds\": {\n      \"gpt-5.4\": 217600,\n      \"gpt-5.5\": 217600\n    },\n    \"modelReasoningEfforts\": {\n      \"gpt-5-mini\": \"low\"\n    },\n    \"useMessagesApi\": true,\n    \"useResponsesApiWebSocket\": true,\n    \"useResponsesApiWebSearch\": true,\n    \"messageApiWebSearchModel\": \"gpt-5-mini\"\n  }\n  ```\n- **auth.apiKeys：** 用于普通非 admin 路由的 API key。支持多个 key 轮换使用。请求可通过 `x-api-key: <key>` 或 `Authorization: Bearer <key>` 进行认证。若为空或省略，则普通路由的认证会被禁用。\n- **auth.adminApiKey：** 仅用于 `/admin/*` 路由的单个 admin key。若未配置，服务会在启动时自动生成一个随机 key，并回写到 `config.json`。它同样使用 `x-api-key` 或 `Authorization: Bearer` 这两种头，但普通 `auth.apiKeys` 不能访问 `/admin/*`。\n- **modelMappings：** 用于顶层 `POST /v1/messages`、`POST /v1/messages/count_tokens`、`POST /v1/responses` 和 `POST /v1/chat/completions` 请求的精确 `sourceModel -> targetModel` 重写映射，这几类接口共用同一份规则。省略该字段或保留为 `{}` 时，不会做模型重写。`source` 和 `target` 都必须是非空字符串。`target` 可以是普通模型 ID，也可以是 `provider/model` 形式的别名，例如 `dashscope/qwen3.6-plus`；重写发生在 provider alias 解析之前。这些映射不再按接口区分。`GET/POST /admin/config/model-mappings` 管理接口读写的也只有这个字段。\n- **extraPrompts：** `model -> prompt` 的映射。把 Anthropic 风格请求翻译为 Responses API 时，会将其附加到第一条 system prompt 后面。你可以借此为不同模型注入护栏或指引。缺失的默认项会自动补齐，但不会覆盖你自定义的 prompt。对于 GPT-5.3+ 模型（如 `gpt-5.3-codex`、`gpt-5.4`、`gpt-5.5`），未显式配置时会自动使用内置的 commentary prompt。内置 prompt 会启用带阶段感知的 commentary，让模型在工具调用或更深层推理前先发出简短的用户可见进度说明。\n- **providers：** 全局上游 provider 映射。每个 provider key（例如 `dashscope`）都会变成一个路由前缀（`/dashscope/v1/messages`）。支持 `type: \"anthropic\"`、`type: \"openai-compatible\"` 和 `type: \"openai-responses\"`。顶层客户端也可以在 `/v1/messages`、`/v1/messages/count_tokens`、`/v1/responses` 和 `/v1/chat/completions` 中使用 `model: \"dashscope/model-id\"`；AI gateway 会在转发上游前移除 `dashscope/` 前缀。`openai-compatible` provider 同时支持 chat 和 Messages 流程：`/v1/chat/completions` 会直连上游 `/v1/chat/completions`，而 `/v1/messages` 和 `/:provider/v1/messages` 会先翻译为上游 Chat Completions，再把响应翻译回 Anthropic Messages。`GET /v1/models` 会聚合已启用 provider 的模型，并以 `provider/model-id` 形式返回；单个 provider 的原始模型列表仍可使用 `GET /dashscope/v1/models`。\n  - `enabled`：可选，若省略则默认为 `true`。\n  - `baseUrl`：provider API 的基础 URL，不要带结尾的 endpoint。Anthropic provider 不要带 `/v1/messages`；OpenAI 兼容 provider 不要带 `/v1/chat/completions`；OpenAI Responses provider 不要带 `/v1/responses`。\n  - `apiKey`：作为上游凭据值使用；普通 provider 必须配置。\n  - `authType`：可选，控制 `apiKey` 如何发送到上游。普通 provider 支持 `x-api-key` 和 `authorization`。Anthropic provider 默认 `x-api-key`；OpenAI 兼容和 OpenAI Responses provider 默认 `authorization`。当设置为 `authorization` 时，代理会发送 `Authorization: Bearer <apiKey>`。`oauth2` 仅保留给内置 `codex` provider，并由 `auth login --provider codex` 自动写入。\n  - `pricingCurrency`：可选，provider 维度的 token 费用币种，例如 `USD` 或 `CNY`。快捷 provider 默认 DashScope、DeepSeek 为 `CNY`，Codex/OpenRouter 为 `USD`。费用按币种分别汇总，不做汇率换算。\n  - `models`：可选，按模型 ID 配置的映射。每个键为请求中的模型名，值支持：\n    - `temperature`：可选，当请求未指定时使用的默认温度。\n    - `topP`：可选，当请求未指定时使用的默认 `top_p`。\n    - `topK`：可选，当请求未指定时使用的默认 `top_k`。\n    - `extraBody`：可选，按模型合入上游请求体的动态字段；请求体显式同名字段优先。OpenAI 兼容 provider 可用它配置 `enable_thinking`、`preserve_thinking`、`reasoning_effort` 等字段。`thinking_budget` 是 OpenAI 兼容 provider 的特殊覆盖项：配置在 `extraBody` 后，会在 Anthropic `thinking.budget_tokens` 翻译之后强制写入，并覆盖请求派生出的预算值。对于 provider name 为 `dashscope` 或 `baseUrl` 包含 `aliyuncs.com` 的 provider，请求派生的 `thinking_budget`（来自 Anthropic `thinking.budget_tokens`）会转发给上游；其他 OpenAI 兼容 provider 会移除请求派生的 `thinking_budget`，但 `extraBody` 中的 `thinking_budget` 仍然生效。对于 DashScope provider，当 `preserve_thinking` 未在 `extraBody` 或请求体中显式设置时，默认为 `true`。\n    - `pricing`：可选，按模型配置 token 单价，币种使用 provider 的 `pricingCurrency`，单位为每 100 万 tokens。支持 `input`、`output`、`cachedInput`（隐式缓存读）、`explicitCachedInput`（显式缓存读）和 `cacheCreationInput`。如需按输入 token 总量分档，可用带 `maxInputTokens` 的 `tiers`。\n    - `contextCache`：可选，provider name 为 `dashscope` 或 `baseUrl` 包含 `aliyuncs.com` 时默认 `true`，其他 OpenAI 兼容 provider 默认 `false`。用于启用阿里云百炼/DashScope 的显式缓存（explicit context cache），会按其 Context Cache 格式在最多 4 个 content block 上注入 `cache_control: { \"type\": \"ephemeral\" }`。缓存断点策略与 opencode 主链路保持一致：前 2 条 system 消息 + 最后 2 条非 system 消息。标记字符串 content 时会把 `system` / `user` / `assistant` / `tool` 消息转换为 text content part 数组；已有数组 content 则标记最后一个 part。如果模型本身已经支持隐式缓存，或上游不支持该显式缓存扩展字段，可在模型配置中设为 `false`。支持相同显式缓存扩展的非 DashScope provider 可设为 `true`。同时适用于 `/v1/messages` 和 `/v1/chat/completions` 路由。\n    - `supportPdf`：可选，控制该模型是否支持 PDF/document content。默认 `false`，不支持时会把 PDF 转成提示文本；设为 `true` 时会把 PDF/document 转成 OpenAI Chat Completions 的 file part。\n    - `toolContentSupportType`：可选，配置该模型的 tool result content 支持能力，值为 `array`、`image`、`pdf` 的数组。provider 侧未配置时默认只发送 string tool content。若 `supportPdf` 为 `true` 但这里不包含 `pdf`，tool result 里的 file part 会被转成 user role 消息。Copilot 主链路不使用这个 provider 默认，仍按 array + image 且不支持 PDF 的能力处理。\n    - `type`：可选，按模型覆盖 provider 的协议类型。支持 `anthropic`、`openai-compatible` 和 `openai-responses`。设置后，provider 的 `/v1/messages` 路由会使用该模型的 type 替代 provider 级别的 type 进行请求路由、认证头解析和上游端点选择。适用于 OpenCode Go 等上游对不同模型同时支持 OpenAI 兼容和 Anthropic Messages API 的 provider。覆盖 type 时，认证头按覆盖后 type 的默认值解析（Anthropic 默认 `x-api-key`；OpenAI 兼容/Responses 默认 `authorization`）。\n\n  DashScope 模型配置示例：\n  ```json\n  {\n    \"providers\": {\n      \"dashscope\": {\n        \"type\": \"openai-compatible\",\n        \"enabled\": true,\n        \"baseUrl\": \"https://dashscope.aliyuncs.com/compatible-mode\",\n        \"apiKey\": \"sk-your-dashscope-key\",\n        \"pricingCurrency\": \"CNY\",\n        \"models\": {\n          \"qwen3.7-plus\": {\n            \"temperature\": 1,\n            \"topP\": 0.95,\n            \"topK\": 20,\n            \"extraBody\": {\n              \"preserve_thinking\": true\n            }\n          },\n          \"glm-5.1\": {\n            \"temperature\": 0.7,\n            \"topP\": 0.95,\n            \"contextCache\": true,\n            \"pricing\": {\n              \"tiers\": [\n                {\n                  \"maxInputTokens\": 32000,\n                  \"input\": 6,\n                  \"cachedInput\": 1.2,\n                  \"explicitCachedInput\": 0.6,\n                  \"cacheCreationInput\": 7.5,\n                  \"output\": 24\n                },\n                {\n                  \"maxInputTokens\": 200000,\n                  \"input\": 8,\n                  \"cachedInput\": 1.6,\n                  \"explicitCachedInput\": 0.8,\n                  \"cacheCreationInput\": 10,\n                  \"output\": 28\n                }\n              ]\n            },\n            \"extraBody\": {\n              \"preserve_thinking\": true\n            }\n          }\n        }\n      }\n    }\n  }\n  ```\n  内置 token 价格覆盖 Codex GPT 模型（USD）、DashScope `qwen3.7-max`、`qwen3.7-plus`、`glm-5.1`、`glm-5.2`（CNY），DeepSeek `deepseek-v4-flash`、`deepseek-v4-pro`、`deepseek-chat`、`deepseek-reasoner`（CNY），以及 OpenCode Go 模型（`glm-5.2`、`grok-4.5`、`deepseek-v4-flash`、`deepseek-v4-pro`、`kimi-k2.7-code`、`kimi-k3`、`mimo-v2.5`、`mimo-v2.5-pro`、`qwen3.7-plus`、`qwen3.7-max`、`minimax-m2.7`、`minimax-m3`，USD）。用户配置的 `pricing` 优先于内置价格。DashScope 若上游 usage 中出现 `cache_creation_input_tokens` 字段，cached tokens 按显式缓存读价计费；否则 `cachedInput` 作为隐式缓存读价。DeepSeek 的 `prompt_cache_hit_tokens` 会归入 cached input，`prompt_cache_miss_tokens` 会归入普通 input。\n- **smallModel：** 无工具预热消息的回退模型（例如 Claude Code 的探测请求）；默认是 `gpt-5-mini`。网关会对无工具的预热或探测请求强制使用该小模型，以避免消耗 premium 请求。该行为仅在 GitHub Copilot 账户为非 token-based 计费时生效（`token_based_billing` 为 false）；对于 token-based 计费账户，预热小模型回退会被跳过，因为不存在需要节省的 premium 请求配额。\n- **contextManagement：** 控制代理是否为 Responses API 附加 `context_management` 压缩指令。`messages` 作用于被翻译成 Responses API 的 Anthropic 风格 `/v1/messages` 请求，包括 `openai-responses` provider 的 Messages 路由，默认值为 `true`。`responses` 作用于 native `/v1/responses` 流量，包括 `provider/model` 别名和内置 `codex` provider，默认值为 `false`。只有在确认客户端支持 context management compaction 后，才建议在 Responses API 下启用 `responses`。启用后，请求体会带上 `context_management`，并在后续轮次中仅保留最新的压缩承载内容。**注意：** 对于 GPT-5.6 及以上模型（如 `gpt-5.6-sol`、`gpt-5.6-terra`、`gpt-5.6-luna`），context management 功能会被强制禁用，因为开启后会破坏这些模型的 prompt 缓存命中。此强制覆盖优先于 `contextManagement` 和 `modelResponsesApiCompactThresholds` 配置。\n - **modelResponsesApiCompactThresholds：** 按模型覆盖 Responses API 的 `compact_threshold`，仅在代理自动附加 `context_management` 时使用。它的优先级高于 `resolveResponsesCompactThreshold` 基于 `max_prompt_tokens * ratio` 的兜底阈值。默认将 `gpt-5.4` 和 `gpt-5.5` 设为 `217600`（`272000 * 0.8`）。未列出的模型继续使用原有兜底逻辑。\n- **modelReasoningEfforts：** `/v1/messages` 请求的模型级默认推理强度。仅当请求没有传入 `output_config.effort` 时，该配置才会生效。\n  - **优先级：** 请求中的 `output_config.effort` > `modelReasoningEfforts[model]` > 内置默认值（GPT-5.3+ 模型为 `xhigh`，其他模型为 `high`）。\n  - **转发字段：** 走 Copilot 原生 Messages API 时，最终值写入 `output_config.effort`；转换为 Responses API 时，最终值写入 `reasoning.effort`。\n  - **配置可选值：** `none`、`minimal`、`low`、`medium`、`high`、`xhigh`、`max`。\n- **useMessagesApi：** 当为 `true` 时，支持 Copilot 原生 `/v1/messages` 的 Claude 系模型会走 Messages API；否则回退到 `/chat/completions`。设为 `false` 可禁用 Messages API 路由，始终使用 `/chat/completions`。默认值为 `true`。\n- **useResponsesApiWebSocket：** 当为 `true` 时，Responses API 请求会优先对声明了 `ws:/responses` 的模型使用 Copilot websocket transport；仅声明 `/responses` 的模型仍走 HTTP。设为 `false` 可禁用 websocket 路由，并在模型支持 `/responses` 时使用 HTTP `/responses`。默认值为 `true`。如果遇到 Responses API WebSocket closed，一般是自己的网络问题。如果使用了 VPN，建议切换节点。\n- **useResponsesApiWebSearch：** 当为 `true` 时，服务端会保留 Responses API 中 `type: \"web_search\"` 的工具并透传到上游。设为 `false` 则会从 `/responses` payload 中移除这些工具。默认值为 `true`。\n- **messageApiWebSearchModel：** 顶层 Copilot `/v1/messages` 请求只包含服务端 `web_search` 工具时使用的全局模型，默认值为 `gpt-5-mini`。如果该值是 `provider/model` 别名，请求会进入对应 provider 的 Messages API 路径，并在转发前移除 provider 前缀。对于 Copilot GPT 模型，web search 会通过 `/responses` 执行。混合 `web_search` 与自定义工具的场景暂不支持，服务端会移除 server-side `web_search`。\n- **claudeTokenMultiplier：** 用于 Claude `/v1/messages/count_tokens` 请求在本地走 GPT tokenizer 估算时的乘数。默认值为 `1.15`。如果你的客户端仍然过晚触发上下文压缩，可以适当调大。这个配置只会在代理本地估算 Claude token 时生效；如果已经配置 `anthropicApiKey` 且 Anthropic token counting 调用成功，则会直接返回 Anthropic 的精确计数，不会使用这个乘数。\n- **anthropicApiKey：** 用于把 Claude `/v1/messages/count_tokens` 请求转发到 Anthropic 真实 token counting 端点的 API key，这样会返回精确计数，而不是 GPT tokenizer 估算值。也可通过环境变量 `ANTHROPIC_API_KEY` 设置。若未配置，或上游调用失败，则回退到由 `claudeTokenMultiplier` 控制的本地 GPT tokenizer 估算。\n\n编辑此文件后即可自定义 prompts，或替换为你自己的快速模型。修改完成后请重启服务（或重新执行命令），让缓存中的配置刷新生效。\n\n## API 认证\n\n- **受保护的普通路由：** 当配置了 `auth.apiKeys` 且非空时，除 `/`、`/usage-viewer` 和 `/usage-viewer/` 以外的普通路由都需要认证。\n- **Admin 路由：** 所有 `/admin/*` 路由都要求 `auth.adminApiKey`。如果缺失，服务会在启动时自动生成并在开始提供服务前写回 `config.json`。\n- **允许的认证头：**\n  - `x-api-key: <your_key>`\n  - `Authorization: Bearer <your_key>`\n- **CORS 预检：** `OPTIONS` 请求始终允许。\n- **未配置普通 key 时：** 普通路由仍可直接访问；但这条规则不适用于 `/admin/*`，后者只接受 `auth.adminApiKey`。\n\n普通受保护路由的示例请求：\n\n```sh\ncurl http://localhost:4141/v1/models \\\n  -H \"x-api-key: your_api_key\"\n```\n\nAdmin 路由的示例请求：\n\n```sh\ncurl http://localhost:4141/admin/config/model-mappings \\\n  -H \"x-api-key: your_admin_api_key\"\n```\n\n## API 端点\n\n服务端提供多个 OpenAI / Anthropic 兼容端点。请求会根据所选模型和 `provider/model` 别名路由到 GitHub Copilot、内置 `codex` provider 或已配置的 provider。\n\n### OpenAI 兼容端点\n\n这些端点模拟 OpenAI API 结构。\n\n| 端点 | 方法 | 说明 |\n| --- | --- | --- |\n| `POST /v1/responses` | `POST` | OpenAI 中用于生成模型响应的高级接口。支持 `openai-responses` provider 的 `provider/model` 别名。 |\n| `POST /v1/chat/completions` | `POST` | 为给定聊天对话创建模型响应。支持 `openai-compatible` provider 的 `provider/model` 别名；目标 provider 已配置时可在没有 Copilot 的情况下使用。 |\n| `GET /v1/models` | `GET` | 列出 Copilot 模型以及已启用 provider 的 `provider/model-id` 模型。来自 Codex 客户端（`User-Agent` 以 `codex` 开头）的请求会转发到 Codex Models 上游。 |\n| `POST /v1/embeddings` | `POST` | 创建表示输入文本的向量嵌入。 |\n\n### Codex 后端代理端点\n\n这些端点要求已有可用的 Codex 登录态。每个端点同时提供无版本前缀和 `/v1` 两种路径。\n\n| 端点 | 方法 | 说明 |\n| --- | --- | --- |\n| `POST /alpha/search`<br>`POST /v1/alpha/search` | `POST` | 将 JSON 请求体和查询参数透明转发到 Codex Alpha Search 上游。 |\n| `POST /images/generations`<br>`POST /v1/images/generations` | `POST` | 将 JSON 图片生成请求转发到 Codex Images 上游。请求未携带 `Content-Type` 时，网关默认补充 `application/json`。 |\n| `POST /images/edits`<br>`POST /v1/images/edits` | `POST` | 将图片编辑请求转发到 Codex Images 上游。请使用 `multipart/form-data`，并让 HTTP 客户端自动生成 `boundary`；网关会保留传入的 content type，并以流式方式转发上传请求体。 |\n\n对于以上所有端点，网关都会使用当前 Codex 登录态覆盖客户端的 authorization 和 account header，保留查询参数及兼容的请求头，并返回上游状态码、响应头和响应体。\n\n### Anthropic 兼容端点\n\n这些端点设计为兼容 Anthropic Messages API。provider 级的 models、Responses、alpha-search 和 images 路由同时支持无版本前缀与 `/v1` 两种路径；Messages 路由仍使用 `/v1`。\n\n| 端点 | 方法 | 说明 |\n| --- | --- | --- |\n| `POST /v1/messages` | `POST` | 为给定对话创建模型响应。支持已配置 provider 的 `provider/model` 别名，包括通过 `openai-compatible` provider 做翻译。 |\n| `POST /v1/messages/count_tokens` | `POST` | 计算一组消息的 token 数。支持已配置 provider 的 `provider/model` 别名。 |\n| `POST /:provider/v1/messages` | `POST` | 将 Anthropic Messages 请求代理到已配置的 Anthropic provider，或翻译到 OpenAI 兼容 / OpenAI Responses provider。 |\n| `GET /:provider/models`<br>`GET /:provider/v1/models` | `GET` | 将模型列表请求代理到已配置的 provider。对 `codex` 默认返回内置模型目录；Codex 客户端（`User-Agent` 以 `codex` 开头）会转发到 Codex Models 上游。 |\n| `POST /:provider/v1/messages/count_tokens` | `POST` | 为 provider 路由请求在本地计算 token 数。 |\n| `POST /:provider/responses`<br>`POST /:provider/v1/responses` | `POST` | 将 OpenAI Responses 请求代理到已配置的 `openai-responses` provider（含 `codex`）。 |\n| `POST /:provider/alpha/search`<br>`POST /:provider/v1/alpha/search` | `POST` | 代理 alpha-search 请求。对 `codex` 转发到 Codex Alpha Search 上游；其他 provider 转发到 `{baseUrl}/v1/alpha/search`。 |\n| `POST /:provider/images/generations`<br>`POST /:provider/v1/images/generations` | `POST` | 代理图片生成。对 `codex` 使用 Codex Images 上游；其他 provider 转发到 `{baseUrl}/v1/images/generations`（15 分钟超时）。 |\n| `POST /:provider/images/edits`<br>`POST /:provider/v1/images/edits` | `POST` | 代理图片编辑。对 `codex` 使用 Codex Images 上游；其他 provider 以 multipart/流式方式转发到 `{baseUrl}/v1/images/edits`（15 分钟超时）。 |\n\n### 使用量监控端点\n\n用于监控 Copilot 用量与额度的新端点。\n\n| 端点 | 方法 | 说明 |\n| --- | --- | --- |\n| `GET /usage` | `GET` | 获取详细的 Copilot 使用统计与额度信息。 |\n| `GET /token` | `GET` | 获取当前 API 正在使用的 Copilot token。 |\n\n### Admin / 配置端点\n\n这些端点用于本地管理操作，只接受 `auth.adminApiKey`。\n\n| 端点 | 方法 | 说明 |\n| --- | --- | --- |\n| `GET /admin/config/model-mappings` | `GET` | 返回当前 `config.json` 路径以及生效中的 `modelMappings` 映射。 |\n| `POST /admin/config/model-mappings` | `POST` | 只更新 `config.json` 里的 `modelMappings` 字段，并回传更新后的结果。 |\n\n## 使用示例\n\n常用 `npx` 命令：\n\n```sh\n# 基础启动\nnpx @jeffreycao/copilot-api@latest start\n\n# 自定义端口并开启详细日志\nnpx @jeffreycao/copilot-api@latest start --port 8080 --verbose\n\n# 执行认证流程\nnpx @jeffreycao/copilot-api@latest auth login\n\n# 配置第三方 provider，然后不依赖 GitHub Copilot 启动\nnpx @jeffreycao/copilot-api@latest auth login --provider dashscope\nnpx @jeffreycao/copilot-api@latest start\n\n# 以 JSON 格式输出调试信息\nnpx @jeffreycao/copilot-api@latest debug --json\n\n# 用 Bun 而不是 Node.js 运行已发布 CLI\nbunx --bun @jeffreycao/copilot-api@latest start\n```\n\n配置 `dashscope` 后的 OpenAI 兼容 provider 调用示例：\n\n```sh\ncurl http://localhost:4141/v1/chat/completions \\\n  -H \"content-type: application/json\" \\\n  -d '{\"model\":\"dashscope/qwen3.6-plus\",\"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]}'\n\ncurl http://localhost:4141/dashscope/v1/messages \\\n  -H \"content-type: application/json\" \\\n  -d '{\"model\":\"qwen3.6-plus\",\"max_tokens\":1024,\"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]}'\n```\n\n## 使用建议\n\n<a id=\"claudemd-or-agentsmd-recommended-content\"></a>\n\n### CLAUDE.md 或 AGENTS.md 推荐内容\n\n如果你想手动加入这些提醒，请在 Claude Code 的 `CLAUDE.md`，或 opencode/codex 的 `AGENTS.md` 中加入以下内容：\n\n```\n- Prohibited from directly asking questions to users, MUST use question tool.\n- Once you can confirm that the task is complete, MUST use question tool to make user confirm. The user may respond with feedback if they are not satisfied with the result, which you can use to make improvements and try again, after try again, MUST use question tool to make user confirm again.\n```\n"}, "453b0867b4291c00a08689b6dd303cee6c0544e0": {"t": 1785765534.3187299, "n": 34198, "h": "8f838c93da5f38b0", "c": "# Copilot API Proxy\n\n[English](./README.md) | 简体中文\n\n## 重要说明\n\n> [!IMPORTANT]\n> **使用前请先注意以下几点：**\n>\n> 1. **Claude Code 配置：** 与 Claude Code 搭配使用时，请将模型 ID 配置为 `claude-opus-4-8`。示例 claude `settings.json` 见 [通过 `settings.json` 手动配置](#manual-configuration-with-settingsjson)。\n>\n> 2. **内置 `copilot`、`codex` 与第三方 provider：** 执行 `npx @jeffreycao/copilot-api@latest auth`，可选择 `copilot`、`codex`、`deepseek`、`custom` 等 provider。\n>\n> 3. **注意事项：** README 顶部移除的 GitHub Copilot warning 见 [GitHub Copilot 安全提示](./NOTICE.md#github-copilot-security-notice)。\n\n---\n\n## 项目概览\n\n这是一个小型 AI gateway，可以使用 GitHub Copilot、内置 `codex` provider，也可以使用 DashScope 等已配置的第三方 provider。GitHub Copilot 现在是可选能力：如果本地没有 GitHub token，只要至少配置了一个启用中的 provider，服务仍可按 provider-only 模式启动。\n\nAI gateway 会从同一个本地端点暴露 OpenAI / Anthropic 兼容 API，让 [Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview)、OpenCode、Codex 和 OpenAI 兼容客户端可以共用同一个本地服务。\n\n在 GitHub Copilot 路径上，AI gateway 会在可用时优先使用 Copilot 原生的 Anthropic 风格 Messages API，在重工具调用场景下保留更原生的 Claude 行为。\n\n## 功能特性\n\n- **OpenAI 与 Anthropic 双兼容**：通过 `/v1/responses`、`/v1/chat/completions`、`/v1/models`、`/v1/embeddings` 和 `/v1/messages` 对外暴露同一个本地 AI gateway。\n- **Copilot 可选**：有 GitHub 凭据时可以使用 GitHub Copilot，没有 GitHub 凭据时也可以只依赖已配置的 provider 运行。\n- **同一网关接入 Copilot、`codex` 与第三方 provider**：可统一路由 GitHub Copilot、内置 `codex` provider 和配置好的外部 provider。\n- **第三方 provider 可独立启动**：配置 DashScope、DeepSeek、OpenRouter 或自定义 provider 后，不需要 GitHub Copilot 登录即可启动 AI gateway。\n- **OpenAI 兼容 provider 同时支持 chat 和 Messages API**：`openai-compatible` provider 可通过顶层 `/v1/chat/completions` 搭配 `model: \"provider/model\"` 提供 Chat Completions，也可通过 `/v1/messages` 完成 Anthropic Messages 的请求/响应翻译。\n- **面向 Claude 的更原生 Copilot 路由**：优先使用原生 `/v1/messages`，保留 Claude 风格工具流，支持 Anthropic beta 能力、通过 Responses-capable 模型支持 Claude WebSearch，并保留 subagent / session 标记。\n- **Claude Code 与 OpenCode 集成**：兼容 Claude Code 与 OpenCode，也支持通过 `@ai-sdk/anthropic` 直接作为 Anthropic provider 使用。\n- **灵活的认证与部署选项**：支持交互式登录、直接 token、个人 / Business / Enterprise、GitHub Enterprise、opencode OAuth 和自定义数据目录。\n- **多 provider 路由**：可暴露 `/:provider/...` 路由，也可在顶层 API 上使用 `model: \"provider/model\"`。\n\n## 前置要求\n\n- Bun（>= 1.2.x）\n- 如果要通过 `npx` 运行已发布 CLI，需要 Node.js\n- 只有在使用 GitHub Copilot provider 时，才需要已订阅 Copilot 的 GitHub 账号\n- 如果不使用 GitHub Copilot，需要至少一个已配置 provider 的 API key 或 OAuth 登录\n\n## 安装\n\n安装依赖：\n\n```sh\nbun install\n```\n\n直接从源码启动服务：\n\n```sh\nbun run start start\n```\n\n## 从源码运行\n\n本项目可以通过多种方式从源码运行：\n\n### 开发模式\n\n```sh\nbun run dev start\n```\n\n### 生产模式\n\n```sh\nbun run start start\n```\n\n## 通过 npx 使用\n\n你可以直接用 npx 运行本项目：\n\n> [!IMPORTANT]\n> 通过 `npx` 运行时，token usage 存储会使用 Node 内置的 `node:sqlite` 模块。该能力会在 Node.js >= 22.13.0 时启用；Node.js < 22.13.0 时 CLI 仍可启动，但会禁用 token usage 存储。\n>\n> 如果不升级 Node.js 但仍需要 token usage 存储，可以改用 Bun 运行已发布 CLI：`bunx --bun @jeffreycao/copilot-api@latest start`。\n\n```sh\nnpx @jeffreycao/copilot-api@latest start\n```\n\n带参数示例：\n\n```sh\nnpx @jeffreycao/copilot-api@latest start --port 8080\n```\n\n如果只想做认证或 provider 配置：\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth\n```\n\n如果要不依赖 GitHub Copilot 运行，先配置至少一个 provider，然后正常启动服务：\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth login --provider dashscope\nnpx @jeffreycao/copilot-api@latest start\n```\n\n## 配合 Docker 使用\n\n构建镜像：\n\n```sh\ndocker build -t copilot-api .\n```\n\n通过 bind mount 运行容器，让认证数据在重启后保留：\n\n```sh\nmkdir -p ./copilot-data\ndocker run -p 4141:4141 -v $(pwd)/copilot-data:/root/.local/share/copilot-api copilot-api\n```\n\n这会把宿主机上的 `./copilot-data` 映射到容器内的 `/root/.local/share/copilot-api`，用于持久化 GitHub 认证数据、provider 配置和其他 gateway 状态。\n\n也可以直接通过环境变量传入 GitHub token：\n\n```sh\ndocker run -p 4141:4141 -e GH_TOKEN=your_github_token_here copilot-api\n```\n\n## Electron 桌面应用\n\n如果你更喜欢图形界面，仓库里还提供了位于 `desktop/` 的 Electron 桌面应用。它支持 GitHub Copilot 登录、OpenAI Codex OAuth，以及 DeepSeek、DashScope、OpenRouter 或自定义 provider 的 API Key 配置。授权或配置 provider 后，可以一键启动或停止本地代理，并在界面里直接查看本地端点、鉴权 Header、可用模型、额度和日志。\n\n设置页还可以配置 `OAuth App`、`API Home`、`Enterprise URL`、详细日志以及最小化到托盘。Windows x64（`.exe`）、macOS Apple Silicon（`.dmg`）和 Linux x64（`.AppImage`）安装包发布在 GitHub Releases：\n\nhttps://github.com/caozhiyuan/copilot-api/releases\n\nLinux 用户需要先为下载的 AppImage 添加执行权限：\n\n```sh\nchmod +x Copilot-API-*-linux-x86_64.AppImage\n./Copilot-API-*-linux-x86_64.AppImage\n```\n\n下载对应平台的安装包后，在应用内授权或配置 provider，选择端口并启动服务，再把你的客户端指向应用里显示的本地端点即可。发布版桌面应用使用随包内置的 Electron 运行时，正常使用不需要额外安装 Node.js；token usage 历史记录会在该内置运行时支持 SQLite 时启用。\n\n桌面应用里的高级配置页会通过 `GET/POST /admin/config/model-mappings` 读写这份共享的模型映射。同一份映射会统一作用于 `POST /v1/messages`、`POST /v1/messages/count_tokens`、`POST /v1/responses` 和 `POST /v1/chat/completions`，不再按接口区分。它使用的是 `auth.adminApiKey`，不是普通的 `auth.apiKeys`；应用会在服务启动并自动生成该 key 后，直接从 `config.json` 读取它来发起请求。\n\n### 桌面应用截图\n\n下面展示了桌面应用中的首页、Token 用量统计页面：\n\n<p align=\"center\">\n  <img src=\"./docs/screenshots/desktop-dashboard.png\" alt=\"Copilot API 桌面应用首页\" width=\"49%\" />\n  <img src=\"./docs/screenshots/desktop-token-usage.png\" alt=\"Copilot API 桌面应用 Token 用量页\" width=\"49%\" />\n</p>\n\n## 与 Claude Code 一起使用\n\n这个 AI gateway 可以为 [Claude Code](https://docs.anthropic.com/en/claude-code) 提供后端能力。Claude Code 是 Anthropic 提供的实验性面向开发者的对话式 AI 助手。\n\n有两种方式可以把 Claude Code 配置为使用这个 AI gateway：\n\n### 通过 `--claude-code` 标志进行交互式配置\n\n执行带 `--claude-code` 的 `start` 命令开始：\n\n```sh\nnpx @jeffreycao/copilot-api@latest start --claude-code\n```\n\n你不再需要手动选择模型。Gateway 会自动检测每个 Claude Code 尺寸档位对应的最新可用模型——opus 映射到最新的 Opus 模型，sonnet 映射到最新的 Sonnet 模型，haiku 映射到最新的 Haiku 模型——并生成相应设置 `ANTHROPIC_DEFAULT_OPUS_MODEL`、`ANTHROPIC_DEFAULT_SONNET_MODEL` 和 `ANTHROPIC_DEFAULT_HAIKU_MODEL` 的命令。若某个档位没有匹配的可用模型，则会被省略。该命令会被复制到剪贴板，并设置 Claude Code 使用这个 AI gateway 所需的环境变量。\n\n在新的终端中粘贴并执行这条命令，即可启动 Claude Code。\n\n<a id=\"manual-configuration-with-settingsjson\"></a>\n\n### 通过 `settings.json` 手动配置\n\n另一种方式是在项目根目录中创建 `.claude/settings.json` 文件，并写入 Claude Code 所需的环境变量。这样你就不需要每次都运行交互式配置了。\n\n下面是一个 `.claude/settings.json` 示例：\n\n```json\n{\n  \"env\": {\n    \"ANTHROPIC_BASE_URL\": \"http://localhost:4141\",\n    \"ANTHROPIC_AUTH_TOKEN\": \"dummy\",\n    \"ANTHROPIC_MODEL\": \"gpt-5.6-sol[1m]\",\n    \"ANTHROPIC_DEFAULT_SONNET_MODEL\": \"gpt-5.6-sol[1m]\",\n    \"ANTHROPIC_DEFAULT_HAIKU_MODEL\": \"gpt-5.6-luna[1m]\",\n    \"CLAUDE_CODE_AUTO_COMPACT_WINDOW\": \"272000\",\n    \"CLAUDE_CODE_USE_VERTEX\": \"0\",\n    \"CLAUDE_CODE_USE_BEDROCK\": \"0\",\n    \"DISABLE_NON_ESSENTIAL_MODEL_CALLS\": \"1\",\n    \"CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC\": \"1\",\n    \"CLAUDE_CODE_ATTRIBUTION_HEADER\": \"0\",\n    \"CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION\": \"false\",\n    \"CLAUDE_CODE_DISABLE_TERMINAL_TITLE\": \"true\",\n    \"CLAUDE_CODE_ENABLE_AWAY_SUMMARY\": \"0\"\n  },\n  \"alwaysThinkingEnabled\": true,\n  \"effortLevel\": \"xhigh\",\n  \"showThinkingSummaries\": true\n}\n```\n\n- 请根据需要替换 `ANTHROPIC_MODEL`、`ANTHROPIC_DEFAULT_OPUS_MODEL`、`ANTHROPIC_DEFAULT_SONNET_MODEL` 和 `ANTHROPIC_DEFAULT_HAIKU_MODEL`。配置完成后，请安装 claude code 插件，见 [插件集成](#plugin-integrations)。\n- 如果你使用的是 codex provider，建议**不要**将模型名配置成 `codex/xxx` 格式（如 `codex/gpt-5.6-sol`）。Claude Code 会针对 `codex/` 前缀做降智行为——例如每次请求时移除所有之前返回的思考块（thinking blocks）。请使用纯模型名（如 `gpt-5.6-sol`），并在 `config.json` 中配置 `modelMappings` 将其映射回 codex provider：\n  ```json\n  \"modelMappings\": {\n    \"gpt-5.6-sol\": \"codex/gpt-5.6-sol\",\n    \"gpt-5.6-terra\": \"codex/gpt-5.6-terra\",\n    \"gpt-5.6-luna\": \"codex/gpt-5.6-luna\"\n  },\n  ```\n- 将 `CLAUDE_CODE_ATTRIBUTION_HEADER` 设为 `0` 可以阻止 Claude Code 在 system prompt 中附加计费和版本信息，从而避免 prompt cache 失效。\n- 关闭 `CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION` 和 `CLAUDE_CODE_ENABLE_AWAY_SUMMARY` 可以避免不必要地消耗额度。\n- Claude Code WebSearch 已支持纯搜索请求。Copilot 路径请保持全局 `messageApiWebSearchModel` 指向 Responses-capable GPT 模型或 `provider/model` 别名；provider 路由请使用原生 Anthropic provider 或 `openai-responses` provider。只有在你明确想禁止这类流量时，才需要把 `WebSearch` 加到 `permissions.deny`。\n- 如果使用的不是 Claude 模型，请不要启用 `ENABLE_TOOL_SEARCH`。如果使用的是 Claude 模型，则可以启用 `ENABLE_TOOL_SEARCH`。当前 Claude Code 使用的是客户端 tool search 模式，在该模式下每次加载 defer tools 都需要额外请求一次。\n- `CLAUDE_CODE_AUTO_COMPACT_WINDOW`：设置用于自动压缩计算的上下文容量（以 token 为单位）。默认使用模型自身的上下文窗口：标准模型为 200K，扩展上下文模型为 1M。使用 1M 上下文模型（如 `claude-opus-4-6[1m]`）时，可设置一个较低的值（如 `500000`）将窗口视为 500K 用于压缩计算。该值受限于模型的实际上下文窗口上限。`CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` 会基于此值的百分比生效。设置此变量可将压缩阈值与状态栏的 `used_percentage` 解耦（后者始终使用模型的完整上下文窗口）。\n\n更多选项见：[Claude Code settings](https://docs.anthropic.com/en/docs/claude-code/settings#environment-variables)\n\n也可以参考 IDE 集成说明：[Add Claude Code to your IDE](https://docs.anthropic.com/en/docs/claude-code/ide-integrations)\n\n## 与 OpenCode 一起使用\n\nOpenCode 已经有直接的 GitHub Copilot provider。本节适用于你希望让 OpenCode 通过 `@ai-sdk/anthropic` 指向这个 AI gateway，并复用本 README 前面提到的 agent 行为时。\n\n### 最小配置\n\n使用 OpenCode OAuth app 启动 AI gateway：\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth --oauth-app=opencode\nnpx @jeffreycao/copilot-api@latest start\n```\n\n然后让 OpenCode 通过 `@ai-sdk/anthropic` 指向这个 AI gateway。\n\n示例 `~/.config/opencode/opencode.json`：\n\n```json\n{\n  \"$schema\": \"https://opencode.ai/config.json\",\n  \"provider\": {\n    \"local\": {\n      \"npm\": \"@ai-sdk/anthropic\",\n      \"name\": \"My Local\",\n      \"options\": {\n        \"baseURL\": \"http://localhost:4141/v1\",\n        \"apiKey\": \"dummy\"\n      },\n      \"models\": {\n        \"gpt-5.4\": {\n          \"name\": \"gpt-5.4\",\n          \"modalities\": {\n            \"input\": [\"text\", \"image\"],\n            \"output\": [\"text\"]\n          },\n          \"limit\": {\n            \"context\": 400000,\n            \"input\": 272000,\n            \"output\": 128000\n          }\n        },\n        \"claude-sonnet-4.6\": {\n          \"id\": \"claude-sonnet-4.6\",\n          \"name\": \"claude-sonnet-4.6\",\n          \"modalities\": {\n            \"input\": [\"text\", \"image\"],\n            \"output\": [\"text\"]\n          },\n          \"limit\": {\n            \"context\": 200000,\n            \"output\": 32000\n          },\n          \"options\": {\n            \"thinking\": {\n              \"type\": \"adaptive\"\n            },\n            \"effort\": \"max\"\n          }\n        }\n      }\n    }\n  }\n}\n```\n\n这些字段的重要性：\n\n- `npm: \"@ai-sdk/anthropic\"` 是关键。OpenCode 会以 Anthropic Messages 语义与这个 AI gateway 通信，而不是把一切扁平化为 OpenAI Chat Completions。\n- `options.baseURL` 应设为 `http://localhost:4141/v1`；Anthropic SDK 会自动补上 `/messages`、`/models` 和 `/messages/count_tokens`。\n- 如果你在此代理中启用了 `auth.apiKeys`，请把 `dummy` 替换为真实 key；否则任意占位值都可以。\n\n## 与 Codex 一起使用\n\n这个 AI gateway 也可以为 Codex 提供后端能力。\n\n### Codex `config.toml` 参考配置\n\n把以下 `[model_providers.copilot_api]` 段加入你的 Codex `~/.codex/config.toml`：\n\n```toml\nmodel_provider = \"copilot_api\"\nmodel_reasoning_summary = \"auto\"\nmodel_context_window = 272000\nmodel_auto_compact_token_limit = 244800\n\n[model_providers.copilot_api]\nname = \"OpenAI\"\nbase_url = \"http://localhost:4141\"\nenv_key = \"GITHUB_COPILOT_API_KEY\"\nrequires_openai_auth = true\nsupports_websockets = false\nwire_api = \"responses\"\nrequest_max_retries = 3\nstream_max_retries = 1\nstream_idle_timeout_ms = 300000\n\n[features]\nremote_compaction_v2 = true\n\n[analytics]\nenabled = false\n```\n\n> [!NOTE]\n> 此配置仅限于 Codex 与 GitHub Copilot provider。`name` 一定要配置为 `\"OpenAI\"`。它可以缓解 Codex local compact 不命中缓存的问题。\n> 如果使用 codex provider，建议将 `base_url` 配置为 `\"http://localhost:4141/codex\"`。\n\n## GPT Tool Search\n\n对于 `gpt-5.4+` 这类 GPT Responses 模型，这个 AI gateway 可以通过一个很小的 MCP bridge 暴露 Responses `tool_search`。Claude Code 和 opencode 都可以使用同一个 bridge，前提是客户端会加载 MCP server，并且 Anthropic Messages 流量会经过这个 AI gateway。\n\nGPT 模型不要设置 Claude Code 原生的 `ENABLE_TOOL_SEARCH`。这个开关启用的是 Claude Code 自己的客户端 tool search 模式，可能导致 deferred 工具定义不再转发给 AI gateway。这个 AI gateway 需要完整的工具定义，这样才能只保留那一小组常驻加载工具，其余工具统一转换为 Responses deferred namespace。\n\n如果你安装了 `tool-search@copilot-api-marketplace`，Claude Code 会自动带上这个 MCP bridge，可以跳过下面这段 Claude Code MCP 手动配置。\n\n请把 tool search bridge 加到 Claude Code 使用的 MCP 配置中：\n\n```json\n{\n  \"mcpServers\": {\n    \"tool_search\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@jeffreycao/copilot-api@latest\", \"mcp\"]\n    }\n  }\n}\n```\n\n请把 tool search bridge 加到 opencode 使用的 MCP 配置中：\n\n```json\n{\n  \"mcp\": {\n    \"tool_search\": {\n      \"type\": \"local\",\n      \"command\": [\"npx\", \"-y\", \"@jeffreycao/copilot-api@latest\", \"mcp\"]\n    }\n  }\n}\n```\n\n本地开发时可以将命令换成 `bun`，参数换成 `[\"run\", \"./src/main.ts\", \"mcp\"]`。\n\nAI gateway 内部现在会把 OpenAI Responses `tool_search` 配置成 client-executed 模式。deferred tools 仍然会作为可搜索 namespace 暴露给模型，但会明确要求模型直接返回下一步要加载的精确工具名列表。\n\n该 bridge 使用直接工具选择，不做 query 搜索。工具入参是 `names`，值为逗号分隔的精确 deferred 工具名，例如 `TaskList,TaskGet,mcp__fetch__fetch`。\n\n<a id=\"plugin-integrations\"></a>\n\n## 插件集成\n\n本项目为 Claude Code 和 opencode 提供了插件集成。\n\n#### Claude Code 插件集成（基于 marketplace）\n\nClaude Code 集成现在拆分为两个插件：\n\n- `agent-inject` 会在 `SubagentStart` 时注入 `__SUBAGENT_MARKER__...`，以便 AI gateway 推导 `x-initiator: agent`。\n- `tool-search` 会注册用于 GPT Responses deferred tool loading 的 `tool_search` MCP bridge。\n\n- 本仓库中的 marketplace catalog：`.claude-plugin/marketplace.json`\n- 本仓库中的插件源码：`plugin/claude/agent-inject`、`plugin/claude/tool-search`\n\n远程添加 marketplace：\n\n```sh\n/plugin marketplace add https://github.com/caozhiyuan/copilot-api.git\n```\n\n从 marketplace 安装插件：\n\n```sh\n/plugin install agent-inject@copilot-api-marketplace\n/plugin install tool-search@copilot-api-marketplace\n```\n\n安装后，`agent-inject` 会在 `SubagentStart` 时注入 `__SUBAGENT_MARKER__...`，AI gateway 会利用它推导 `x-initiator: agent`。\n\n`agent-inject` 还会注册一个 `UserPromptSubmit` hook，并返回 `{\"continue\": true}`；同时它也可以通过环境变量注入 `SessionStart` reminder 规则：\n\n- `CLAUDE_PLUGIN_ENABLE_QUESTION_RULES=1` 会自动为 Claude Code 启用两条关于使用 `question` 工具的提醒。你也可以把同样的提醒手动写进 `CLAUDE.md`；见 [CLAUDE.md 或 AGENTS.md 推荐内容](#claudemd-or-agentsmd-recommended-content)。\n- `CLAUDE_PLUGIN_ENABLE_NO_BACKGROUND_AGENTS_RULE=1` 会启用关于避免在 agent hooks 中使用 `run_in_background: true` 的提醒。\n\n`tool-search` 插件内置了 [GPT Tool Search](#gpt-tool-search) 一节描述的同一个 MCP bridge，因此安装该插件后，Claude Code 用户无需再手动配置 `tool_search` server。\n\n#### Opencode 插件\n\nsubagent 标记生成器被打包为一个 opencode 插件，位于 `plugin/opencode/subagent-marker.js`。\n\n**安装方式：**\n\n将插件文件复制到你的 opencode 插件目录：\n\n```sh\n# 克隆或下载本仓库后复制该插件\ncp plugin/opencode/subagent-marker.js ~/.config/opencode/plugins/\n```\n\n或者手动在 `~/.config/opencode/plugins/subagent-marker.js` 创建该文件，并填入插件内容。\n\n**功能：**\n\n- 跟踪 subagent 创建的子会话\n- 自动在 subagent 聊天消息前添加 marker system reminder（`__SUBAGENT_MARKER__...`）\n- 设置 `x-session-id` 请求头以跟踪会话\n- 让这个 AI gateway 能够把来自 subagent 的请求识别为 `x-initiator: agent`\n\n该插件会挂接到 `session.created`、`session.deleted`、`chat.message` 和 `chat.headers` 事件上，以无缝提供 subagent marker 能力。\n\n## 使用量查看器\n\n服务启动后，控制台会输出一个 Copilot 使用量看板 URL。这个看板是一个用于监控 API 用量的 Web 界面。\n\n1. 启动服务。例如使用 npx：\n   ```sh\n   npx @jeffreycao/copilot-api@latest start\n   ```\n2. 服务会输出一个 usage viewer 的 URL。将它复制到浏览器中打开，形式大致如下：\n   `http://localhost:4141/usage-viewer?endpoint=http://localhost:4141/usage`\n   - 如果你在 Windows 上使用 `start.bat` 脚本，这个页面会自动打开。\n\n看板提供了更易读的 Copilot 用量视图：\n\n> token usage 历史记录需要 Bun 或 Node.js >= 22.13.0。Node.js < 22.13.0 时服务会正常运行，但 token usage 存储会被禁用。\n\n- **API Endpoint URL**：通过 URL 查询参数指定 API endpoints，默认指向本地服务。支持手动切换为其他兼容 endpoints。\n- **x-api-key 认证**：如果启用了 API Key 认证，可填入 `x-api-key` 请求头。密钥会持久化保存在浏览器本地存储中。\n- **Period 选择器**：支持 Day / Week / Month 三种时间范围，切换时 URL 参数会自动同步，方便收藏和分享。\n- **Fetch Data**：点击 \"Refresh\" 按钮加载或刷新使用数据。页面加载时也会自动拉取数据。\n- **Copilot Quotas 额度**：通过进度条展示 Chat、Completions 等不同服务的额度使用情况，悬停可查看已用/剩余详情。\n- **Token Usage 指标卡片**：汇总当前周期的 Total、Input、Output、Cache Read、Cache Write、Requests 和预估费用。\n- **趋势图（Week / Month）**：提供按模型和指标筛选的折线趋势图，点击数据点可查看单日用量明细。\n- **Model Breakdown 表格**：按模型维度列出周期内的请求数、输入/输出/缓存 token 和预计费用。\n- **Request Events 分页列表**：按时间排序的请求事件记录，支持分页浏览，含时间戳、模型、请求 ID 和 token 用量。\n- **Detailed Information**：展示 API 返回的完整 JSON 响应，便于深入分析所有可用统计数据。\n- **URL-based Configuration**：也可通过 `endpoint` 和 `period` 查询参数直接指定 API 端点与时间范围。例如：\n  `http://localhost:4141/usage-viewer?endpoint=http://your-api-server/usage&period=week`\n\n### Usage Viewer 截图\n\n<p align=\"center\">\n  <img src=\"./docs/screenshots/usage-viewer.png\" alt=\"Copilot API Usage Viewer 页面\" width=\"900\" />\n</p>\n\n## 命令结构\n\nCopilot API 现在使用子命令结构，主要命令包括：\n\n- `start`：启动 AI gateway 服务。如果已有 GitHub token，则启用 Copilot 路径；如果没有 GitHub token，但存在至少一个启用中的 provider，则按 provider-only 模式启动；如果两者都没有，会引导你配置 provider。\n- `auth`：仅执行 provider 登录或配置流程，不启动服务。可用于 GitHub Copilot 登录、Codex OAuth，或第三方 provider API key 配置。\n- `debug`：显示诊断信息，包括版本、运行时详情、文件路径以及认证状态，便于排障与支持。\n\n## 命令行选项\n\n### 全局选项\n\n以下选项可用于任意子命令。若在子命令之前传入，请使用 `--key=value` 形式：\n\n| 选项 | 说明 | 默认值 | 别名 |\n| --- | --- | --- | --- |\n| --api-home | API home 目录路径（设置 `COPILOT_API_HOME`） | 无 | 无 |\n| --oauth-app | OAuth app 标识符（设置 `COPILOT_API_OAUTH_APP`） | 无 | 无 |\n| --enterprise-url | GitHub Enterprise URL（设置 `COPILOT_API_ENTERPRISE_URL`） | 无 | 无 |\n\n### Start 命令选项\n\n以下是 `start` 命令可用的命令行选项：\n\n| 选项 | 说明 | 默认值 | 别名 |\n| --- | --- | --- | --- |\n| --port | 监听端口 | 4141 | -p |\n| --verbose | 启用详细日志 | false | -v |\n| --github-token | 直接提供 GitHub token（必须通过 `auth` 子命令生成） | 无 | -g |\n| --claude-code | 生成一个使用 Copilot API 配置启动 Claude Code 的命令 | false | -c |\n| --show-token | 在获取和刷新时显示 GitHub 与 Copilot token | false | 无 |\n| --proxy-env | 从环境变量初始化代理 | false | 无 |\n\n### Auth 命令选项\n\n| 选项 | 说明 | 默认值 | 别名 |\n| --- | --- | --- | --- |\n| --provider | 要登录或配置的 provider（`copilot`、`codex`、`opencode-go`、`deepseek`、`dashscope`、`openrouter` 或 `custom`） | 交互选择 | 无 |\n| --verbose | 启用详细日志 | false | -v |\n| --show-token | 认证时显示 GitHub token | false | 无 |\n\n只有在需要启用 GitHub Copilot provider 时，才需要执行 `copilot-api auth login --provider copilot`。使用 `codex` 或第三方 provider-only 模式不要求配置 Copilot。\n\n使用 `copilot-api auth login --provider deepseek`、`--provider dashscope`、`--provider openrouter` 或 `--provider opencode-go` 可以通过 CLI 快速新增或更新这些常用第三方 provider。DeepSeek 会提示输入掩码显示的 `apiKey`、provider `type`（默认 `anthropic`），以及默认 `https://api.deepseek.com/anthropic` 的 `baseUrl`。DashScope 会提示输入掩码显示的 `apiKey`、provider `type`（默认 `openai-compatible`）和预填默认值的 `baseUrl`。OpenRouter 只提示输入掩码显示的 `apiKey` 和预填默认值的 `baseUrl`，并固定写入 `type: \"anthropic\"`。OpenCode Go 只提示输入掩码显示的 `apiKey` 和预填默认值的 `baseUrl`，并固定写入 `type: \"openai-compatible\"`（baseUrl `https://opencode.ai/zen/go`）。配置并启用 provider 后，`copilot-api start` 可在没有 GitHub token 的情况下启动。\n\n使用 `copilot-api auth login --provider custom` 可以通过 CLI 新增或更新其他第三方 provider。命令会依次提示输入 provider name、项目支持的 type（`anthropic`、`openai-compatible` 或 `openai-responses`）、`baseUrl`、掩码显示的 `apiKey` 和 `authType`；`authType` 可保持 type 默认值，也可选择 `x-api-key` / `authorization`。\n\n### Debug 命令选项\n\n| 选项 | 说明 | 默认值 | 别名 |\n| --- | --- | --- | --- |\n| --json | 以 JSON 输出调试信息 | false | 无 |\n\n<a id=\"configuration-configjson\"></a>\n\n## 配置（config.json）\n\n- **位置：** Linux/macOS 为 `~/.local/share/copilot-api/config.json`，Windows 为 `%USERPROFILE%\\.local\\share\\copilot-api\\config.json`。\n- **默认结构：**\n  ```json\n  {\n    \"auth\": {\n      \"apiKeys\": [],\n      \"adminApiKey\": \"<startup 自动生成>\"\n    },\n    \"providers\": {},\n    \"modelMappings\": {},\n    \"extraPrompts\": {\n      \"gpt-5-mini\": \"<built-in exploration prompt>\"\n    },\n    \"smallModel\": \"gpt-5-mini\",\n    \"contextManagement\": {\n      \"messages\": true,\n      \"responses\": false\n    },\n    \"modelResponsesApiCompactThresholds\": {\n      \"gpt-5.4\": 217600,\n      \"gpt-5.5\": 217600,\n      \"gpt-5.6-sol\": 231200,\n      \"gpt-5.6-terra\": 231200,\n      \"gpt-5.6-luna\": 231200\n    },\n    \"modelReasoningEfforts\": {\n      \"gpt-5-mini\": \"low\"\n    },\n    \"useMessagesApi\": true,\n    \"useResponsesApiWebSocket\": true,\n    \"useResponsesApiWebSearch\": true,\n    \"messageApiWebSearchModel\": \"gpt-5-mini\"\n  }\n  ```\n- **auth.apiKeys：** 用于普通非 admin 路由的 API key。支持多个 key 轮换使用。请求可通过 `x-api-key: <key>` 或 `Authorization: Bearer <key>` 进行认证。若为空或省略，则普通路由的认证会被禁用。\n- **auth.adminApiKey：** 仅用于 `/admin/*` 路由的单个 admin key。若未配置，服务会在启动时自动生成一个随机 key，并回写到 `config.json`。它同样使用 `x-api-key` 或 `Authorization: Bearer` 这两种头，但普通 `auth.apiKeys` 不能访问 `/admin/*`。\n- **modelMappings：** 用于顶层 `POST /v1/messages`、`POST /v1/messages/count_tokens`、`POST /v1/responses` 和 `POST /v1/chat/completions` 请求的精确 `sourceModel -> targetModel` 重写映射，这几类接口共用同一份规则。省略该字段或保留为 `{}` 时，不会做模型重写。`source` 和 `target` 都必须是非空字符串。`target` 可以是普通模型 ID，也可以是 `provider/model` 形式的别名，例如 `dashscope/qwen3.6-plus`；重写发生在 provider alias 解析之前。这些映射不再按接口区分。`GET/POST /admin/config/model-mappings` 管理接口读写的也只有这个字段。\n- **extraPrompts：** `model -> prompt` 的映射。把 Anthropic 风格请求翻译为 Responses API 时，会将其附加到第一条 system prompt 后面。你可以借此为不同模型注入护栏或指引。缺失的默认项会自动补齐，但不会覆盖你自定义的 prompt。对于 GPT-5.3+ 模型（如 `gpt-5.3-codex`、`gpt-5.4`、`gpt-5.5`），未显式配置时会自动使用内置的 commentary prompt。内置 prompt 会启用带阶段感知的 commentary，让模型在工具调用或更深层推理前先发出简短的用户可见进度说明。\n- **providers：** 全局上游 provider 映射。每个 provider key（例如 `dashscope`）都会变成一个路由前缀（`/dashscope/v1/messages`）。支持 `type: \"anthropic\"`、`type: \"openai-compatible\"` 和 `type: \"openai-responses\"`。顶层客户端也可以在 `/v1/messages`、`/v1/messages/count_tokens`、`/v1/responses` 和 `/v1/chat/completions` 中使用 `model: \"dashscope/model-id\"`；AI gateway 会在转发上游前移除 `dashscope/` 前缀。`openai-compatible` provider 同时支持 chat 和 Messages 流程：`/v1/chat/completions` 会直连上游 `/v1/chat/completions`，而 `/v1/messages` 和 `/:provider/v1/messages` 会先翻译为上游 Chat Completions，再把响应翻译回 Anthropic Messages。`GET /v1/models` 会聚合已启用 provider 的模型，并以 `provider/model-id` 形式返回；单个 provider 的原始模型列表仍可使用 `GET /dashscope/v1/models`。\n  - `enabled`：可选，若省略则默认为 `true`。\n  - `baseUrl`：provider API 的基础 URL，不要带结尾的 endpoint。Anthropic provider 不要带 `/v1/messages`；OpenAI 兼容 provider 不要带 `/v1/chat/completions`；OpenAI Responses provider 不要带 `/v1/responses`。\n  - `apiKey`：作为上游凭据值使用；普通 provider 必须配置。\n  - `authType`：可选，控制 `apiKey` 如何发送到上游。普通 provider 支持 `x-api-key` 和 `authorization`。Anthropic provider 默认 `x-api-key`；OpenAI 兼容和 OpenAI Responses provider 默认 `authorization`。当设置为 `authorization` 时，代理会发送 `Authorization: Bearer <apiKey>`。`oauth2` 仅保留给内置 `codex` provider，并由 `auth login --provider codex` 自动写入。\n  - `pricingCurrency`：可选，provider 维度的 token 费用币种，例如 `USD` 或 `CNY`。快捷 provider 默认 DashScope、DeepSeek 为 `CNY`，Codex/OpenRouter 为 `USD`。费用按币种分别汇总，不做汇率换算。\n  - `models`：可选，按模型 ID 配置的映射。每个键为请求中的模型名，值支持：\n    - `temperature`：可选，当请求未指定时使用的默认温度。\n    - `topP`：可选，当请求未指定时使用的默认 `top_p`。\n    - `topK`：可选，当请求未指定时使用的默认 `top_k`。\n    - `extraBody`：可选，按模型合入上游请求体的动态字段；请求体显式同名字段优先。OpenAI 兼容 provider 可用它配置 `enable_thinking`、`preserve_thinking`、`reasoning_effort` 等字段。`thinking_budget` 是 OpenAI 兼容 provider 的特殊覆盖项：配置在 `extraBody` 后，会在 Anthropic `thinking.budget_tokens` 翻译之后强制写入，并覆盖请求派生出的预算值。对于 provider name 为 `dashscope` 或 `baseUrl` 包含 `aliyuncs.com` 的 provider，请求派生的 `thinking_budget`（来自 Anthropic `thinking.budget_tokens`）会转发给上游；其他 OpenAI 兼容 provider 会移除请求派生的 `thinking_budget`，但 `extraBody` 中的 `thinking_budget` 仍然生效。对于 DashScope provider，当 `preserve_thinking` 未在 `extraBody` 或请求体中显式设置时，默认为 `true`。\n    - `pricing`：可选，按模型配置 token 单价，币种使用 provider 的 `pricingCurrency`，单位为每 100 万 tokens。支持 `input`、`output`、`cachedInput`（隐式缓存读）、`explicitCachedInput`（显式缓存读）和 `cacheCreationInput`。如需按输入 token 总量分档，可用带 `maxInputTokens` 的 `tiers`。\n    - `contextCache`：可选，provider name 为 `dashscope` 或 `baseUrl` 包含 `aliyuncs.com` 时默认 `true`，其他 OpenAI 兼容 provider 默认 `false`。用于启用阿里云百炼/DashScope 的显式缓存（explicit context cache），会按其 Context Cache 格式在最多 4 个 content block 上注入 `cache_control: { \"type\": \"ephemeral\" }`。缓存断点策略与 opencode 主链路保持一致：前 2 条 system 消息 + 最后 2 条非 system 消息。标记字符串 content 时会把 `system` / `user` / `assistant` / `tool` 消息转换为 text content part 数组；已有数组 content 则标记最后一个 part。如果模型本身已经支持隐式缓存，或上游不支持该显式缓存扩展字段，可在模型配置中设为 `false`。支持相同显式缓存扩展的非 DashScope provider 可设为 `true`。同时适用于 `/v1/messages` 和 `/v1/chat/completions` 路由。\n    - `supportPdf`：可选，控制该模型是否支持 PDF/document content。默认 `false`，不支持时会把 PDF 转成提示文本；设为 `true` 时会把 PDF/document 转成 OpenAI Chat Completions 的 file part。\n    - `toolContentSupportType`：可选，配置该模型的 tool result content 支持能力，值为 `array`、`image`、`pdf` 的数组。provider 侧未配置时默认只发送 string tool content。若 `supportPdf` 为 `true` 但这里不包含 `pdf`，tool result 里的 file part 会被转成 user role 消息。Copilot 主链路不使用这个 provider 默认，仍按 array + image 且不支持 PDF 的能力处理。\n    - `type`：可选，按模型覆盖 provider 的协议类型。支持 `anthropic`、`openai-compatible` 和 `openai-responses`。设置后，provider 的 `/v1/messages` 路由会使用该模型的 type 替代 provider 级别的 type 进行请求路由、认证头解析和上游端点选择。适用于 OpenCode Go 等上游对不同模型同时支持 OpenAI 兼容和 Anthropic Messages API 的 provider。覆盖 type 时，认证头按覆盖后 type 的默认值解析（Anthropic 默认 `x-api-key`；OpenAI 兼容/Responses 默认 `authorization`）。\n\n  DashScope 模型配置示例：\n  ```json\n  {\n    \"providers\": {\n      \"dashscope\": {\n        \"type\": \"openai-compatible\",\n        \"enabled\": true,\n        \"baseUrl\": \"https://dashscope.aliyuncs.com/compatible-mode\",\n        \"apiKey\": \"sk-your-dashscope-key\",\n        \"pricingCurrency\": \"CNY\",\n        \"models\": {\n          \"qwen3.7-plus\": {\n            \"temperature\": 1,\n            \"topP\": 0.95,\n            \"topK\": 20,\n            \"extraBody\": {\n              \"preserve_thinking\": true\n            }\n          },\n          \"glm-5.1\": {\n            \"temperature\": 0.7,\n            \"topP\": 0.95,\n            \"contextCache\": true,\n            \"pricing\": {\n              \"tiers\": [\n                {\n                  \"maxInputTokens\": 32000,\n                  \"input\": 6,\n                  \"cachedInput\": 1.2,\n                  \"explicitCachedInput\": 0.6,\n                  \"cacheCreationInput\": 7.5,\n                  \"output\": 24\n                },\n                {\n                  \"maxInputTokens\": 200000,\n                  \"input\": 8,\n                  \"cachedInput\": 1.6,\n                  \"explicitCachedInput\": 0.8,\n                  \"cacheCreationInput\": 10,\n                  \"output\": 28\n                }\n              ]\n            },\n            \"extraBody\": {\n              \"preserve_thinking\": true\n            }\n          }\n        }\n      }\n    }\n  }\n  ```\n  内置 token 价格覆盖 Codex GPT 模型（USD）、DashScope `qwen3.7-max`、`qwen3.7-plus`、`glm-5.1`、`glm-5.2`（CNY），DeepSeek `deepseek-v4-flash`、`deepseek-v4-pro`、`deepseek-chat`、`deepseek-reasoner`（CNY），以及 OpenCode Go 模型（`glm-5.2`、`grok-4.5`、`deepseek-v4-flash`、`deepseek-v4-pro`、`kimi-k2.7-code`、`kimi-k3`、`mimo-v2.5`、`mimo-v2.5-pro`、`qwen3.7-plus`、`qwen3.7-max`、`minimax-m2.7`、`minimax-m3`，USD）。用户配置的 `pricing` 优先于内置价格。DashScope 若上游 usage 中出现 `cache_creation_input_tokens` 字段，cached tokens 按显式缓存读价计费；否则 `cachedInput` 作为隐式缓存读价。DeepSeek 的 `prompt_cache_hit_tokens` 会归入 cached input，`prompt_cache_miss_tokens` 会归入普通 input。\n- **smallModel：** 无工具预热消息的回退模型（例如 Claude Code 的探测请求）；默认是 `gpt-5-mini`。网关会对无工具的预热或探测请求强制使用该小模型，以避免消耗 premium 请求。该行为仅在 GitHub Copilot 账户为非 token-based 计费时生效（`token_based_billing` 为 false）；对于 token-based 计费账户，预热小模型回退会被跳过，因为不存在需要节省的 premium 请求配额。\n- **contextManagement：** 控制代理是否为 Responses API 附加 `context_management` 压缩指令。`messages` 作用于被翻译成 Responses API 的 Anthropic 风格 `/v1/messages` 请求，包括 `openai-responses` provider 的 Messages 路由，默认值为 `true`。`responses` 作用于 native `/v1/responses` 流量，包括 `provider/model` 别名和内置 `codex` provider，默认值为 `false`。只有在确认客户端支持 context management compaction 后，才建议在 Responses API 下启用 `responses`。启用后，请求体会带上 `context_management`，并在后续轮次中仅保留最新的压缩承载内容。**注意：** 对于 GPT-5.6 及以上模型（如 `gpt-5.6-sol`、`gpt-5.6-terra`、`gpt-5.6-luna`），context management 功能会被强制禁用，因为开启后会破坏这些模型的 prompt 缓存命中。此强制覆盖优先于 `contextManagement` 和 `modelResponsesApiCompactThresholds` 配置。\n- **modelResponsesApiCompactThresholds：** 按模型覆盖 Responses API 的 `compact_threshold`，仅在代理自动附加 `context_management` 时使用。它的优先级高于 `resolveResponsesCompactThreshold` 基于 `max_prompt_tokens * ratio` 的兜底阈值。默认将 `gpt-5.4` 和 `gpt-5.5` 设为 `217600`（`272000 * 0.8`），将 `gpt-5.6-sol`、`gpt-5.6-terra`、`gpt-5.6-luna` 设为 `231200`（`272000 * 0.85`）。未列出的模型继续使用原有兜底逻辑。\n- **modelReasoningEfforts：** `/v1/messages` 请求的模型级默认推理强度。仅当请求没有传入 `output_config.effort` 时，该配置才会生效。\n  - **优先级：** 请求中的 `output_config.effort` > `modelReasoningEfforts[model]` > 内置默认值（GPT-5.3+ 模型为 `xhigh`，其他模型为 `high`）。\n  - **转发字段：** 走 Copilot 原生 Messages API 时，最终值写入 `output_config.effort`；转换为 Responses API 时，最终值写入 `reasoning.effort`。\n  - **配置可选值：** `none`、`minimal`、`low`、`medium`、`high`、`xhigh`、`max`。\n- **useMessagesApi：** 当为 `true` 时，支持 Copilot 原生 `/v1/messages` 的 Claude 系模型会走 Messages API；否则回退到 `/chat/completions`。设为 `false` 可禁用 Messages API 路由，始终使用 `/chat/completions`。默认值为 `true`。\n- **useResponsesApiWebSocket：** 当为 `true` 时，Responses API 请求会优先对声明了 `ws:/responses` 的模型使用 Copilot websocket transport；仅声明 `/responses` 的模型仍走 HTTP。设为 `false` 可禁用 websocket 路由，并在模型支持 `/responses` 时使用 HTTP `/responses`。默认值为 `true`。如果遇到 Responses API WebSocket closed，一般是自己的网络问题。如果使用了 VPN，建议切换节点。\n- **useResponsesApiWebSearch：** 当为 `true` 时，服务端会保留 Responses API 中 `type: \"web_search\"` 的工具并透传到上游。设为 `false` 则会从 `/responses` payload 中移除这些工具。默认值为 `true`。\n- **messageApiWebSearchModel：** 顶层 Copilot `/v1/messages` 请求只包含服务端 `web_search` 工具时使用的全局模型，默认值为 `gpt-5-mini`。如果该值是 `provider/model` 别名，请求会进入对应 provider 的 Messages API 路径，并在转发前移除 provider 前缀。对于 Copilot GPT 模型，web search 会通过 `/responses` 执行。混合 `web_search` 与自定义工具的场景暂不支持，服务端会移除 server-side `web_search`。\n- **claudeTokenMultiplier：** 用于 Claude `/v1/messages/count_tokens` 请求在本地走 GPT tokenizer 估算时的乘数。默认值为 `1.15`。如果你的客户端仍然过晚触发上下文压缩，可以适当调大。这个配置只会在代理本地估算 Claude token 时生效；如果已经配置 `anthropicApiKey` 且 Anthropic token counting 调用成功，则会直接返回 Anthropic 的精确计数，不会使用这个乘数。\n- **anthropicApiKey：** 用于把 Claude `/v1/messages/count_tokens` 请求转发到 Anthropic 真实 token counting 端点的 API key，这样会返回精确计数，而不是 GPT tokenizer 估算值。也可通过环境变量 `ANTHROPIC_API_KEY` 设置。若未配置，或上游调用失败，则回退到由 `claudeTokenMultiplier` 控制的本地 GPT tokenizer 估算。\n\n编辑此文件后即可自定义 prompts，或替换为你自己的快速模型。修改完成后请重启服务（或重新执行命令），让缓存中的配置刷新生效。\n\n## API 认证\n\n- **受保护的普通路由：** 当配置了 `auth.apiKeys` 且非空时，除 `/`、`/usage-viewer` 和 `/usage-viewer/` 以外的普通路由都需要认证。\n- **Admin 路由：** 所有 `/admin/*` 路由都要求 `auth.adminApiKey`。如果缺失，服务会在启动时自动生成并在开始提供服务前写回 `config.json`。\n- **允许的认证头：**\n  - `x-api-key: <your_key>`\n  - `Authorization: Bearer <your_key>`\n- **CORS 预检：** `OPTIONS` 请求始终允许。\n- **未配置普通 key 时：** 普通路由仍可直接访问；但这条规则不适用于 `/admin/*`，后者只接受 `auth.adminApiKey`。\n\n普通受保护路由的示例请求：\n\n```sh\ncurl http://localhost:4141/v1/models \\\n  -H \"x-api-key: your_api_key\"\n```\n\nAdmin 路由的示例请求：\n\n```sh\ncurl http://localhost:4141/admin/config/model-mappings \\\n  -H \"x-api-key: your_admin_api_key\"\n```\n\n## API 端点\n\n服务端提供多个 OpenAI / Anthropic 兼容端点。请求会根据所选模型和 `provider/model` 别名路由到 GitHub Copilot、内置 `codex` provider 或已配置的 provider。\n\n### OpenAI 兼容端点\n\n这些端点模拟 OpenAI API 结构。\n\n| 端点 | 方法 | 说明 |\n| --- | --- | --- |\n| `POST /v1/responses` | `POST` | OpenAI 中用于生成模型响应的高级接口。支持 `openai-responses` provider 的 `provider/model` 别名。 |\n| `POST /v1/chat/completions` | `POST` | 为给定聊天对话创建模型响应。支持 `openai-compatible` provider 的 `provider/model` 别名；目标 provider 已配置时可在没有 Copilot 的情况下使用。 |\n| `GET /v1/models` | `GET` | 列出 Copilot 模型以及已启用 provider 的 `provider/model-id` 模型。来自 Codex 客户端（`User-Agent` 以 `codex` 开头）的请求会转发到 Codex Models 上游。 |\n| `POST /v1/embeddings` | `POST` | 创建表示输入文本的向量嵌入。 |\n\n### Codex 后端代理端点\n\n这些端点要求已有可用的 Codex 登录态。每个端点同时提供无版本前缀和 `/v1` 两种路径。\n\n| 端点 | 方法 | 说明 |\n| --- | --- | --- |\n| `POST /alpha/search`<br>`POST /v1/alpha/search` | `POST` | 将 JSON 请求体和查询参数透明转发到 Codex Alpha Search 上游。 |\n| `POST /images/generations`<br>`POST /v1/images/generations` | `POST` | 将 JSON 图片生成请求转发到 Codex Images 上游。请求未携带 `Content-Type` 时，网关默认补充 `application/json`。 |\n| `POST /images/edits`<br>`POST /v1/images/edits` | `POST` | 将图片编辑请求转发到 Codex Images 上游。请使用 `multipart/form-data`，并让 HTTP 客户端自动生成 `boundary`；网关会保留传入的 content type，并以流式方式转发上传请求体。 |\n\n对于以上所有端点，网关都会使用当前 Codex 登录态覆盖客户端的 authorization 和 account header，保留查询参数及兼容的请求头，并返回上游状态码、响应头和响应体。\n\n### Anthropic 兼容端点\n\n这些端点设计为兼容 Anthropic Messages API。provider 级的 models、Responses、alpha-search 和 images 路由同时支持无版本前缀与 `/v1` 两种路径；Messages 路由仍使用 `/v1`。\n\n| 端点 | 方法 | 说明 |\n| --- | --- | --- |\n| `POST /v1/messages` | `POST` | 为给定对话创建模型响应。支持已配置 provider 的 `provider/model` 别名，包括通过 `openai-compatible` provider 做翻译。 |\n| `POST /v1/messages/count_tokens` | `POST` | 计算一组消息的 token 数。支持已配置 provider 的 `provider/model` 别名。 |\n| `POST /:provider/v1/messages` | `POST` | 将 Anthropic Messages 请求代理到已配置的 Anthropic provider，或翻译到 OpenAI 兼容 / OpenAI Responses provider。 |\n| `GET /:provider/models`<br>`GET /:provider/v1/models` | `GET` | 将模型列表请求代理到已配置的 provider。对 `codex` 默认返回内置模型目录；Codex 客户端（`User-Agent` 以 `codex` 开头）会转发到 Codex Models 上游。 |\n| `POST /:provider/v1/messages/count_tokens` | `POST` | 为 provider 路由请求在本地计算 token 数。 |\n| `POST /:provider/responses`<br>`POST /:provider/v1/responses` | `POST` | 将 OpenAI Responses 请求代理到已配置的 `openai-responses` provider（含 `codex`）。 |\n| `POST /:provider/alpha/search`<br>`POST /:provider/v1/alpha/search` | `POST` | 代理 alpha-search 请求。对 `codex` 转发到 Codex Alpha Search 上游；其他 provider 转发到 `{baseUrl}/v1/alpha/search`。 |\n| `POST /:provider/images/generations`<br>`POST /:provider/v1/images/generations` | `POST` | 代理图片生成。对 `codex` 使用 Codex Images 上游；其他 provider 转发到 `{baseUrl}/v1/images/generations`（15 分钟超时）。 |\n| `POST /:provider/images/edits`<br>`POST /:provider/v1/images/edits` | `POST` | 代理图片编辑。对 `codex` 使用 Codex Images 上游；其他 provider 以 multipart/流式方式转发到 `{baseUrl}/v1/images/edits`（15 分钟超时）。 |\n\n### 使用量监控端点\n\n用于监控 Copilot 用量与额度的新端点。\n\n| 端点 | 方法 | 说明 |\n| --- | --- | --- |\n| `GET /usage` | `GET` | 获取详细的 Copilot 使用统计与额度信息。 |\n| `GET /token` | `GET` | 获取当前 API 正在使用的 Copilot token。 |\n\n### Admin / 配置端点\n\n这些端点用于本地管理操作，只接受 `auth.adminApiKey`。\n\n| 端点 | 方法 | 说明 |\n| --- | --- | --- |\n| `GET /admin/config/model-mappings` | `GET` | 返回当前 `config.json` 路径以及生效中的 `modelMappings` 映射。 |\n| `POST /admin/config/model-mappings` | `POST` | 只更新 `config.json` 里的 `modelMappings` 字段，并回传更新后的结果。 |\n\n## 使用示例\n\n常用 `npx` 命令：\n\n```sh\n# 基础启动\nnpx @jeffreycao/copilot-api@latest start\n\n# 自定义端口并开启详细日志\nnpx @jeffreycao/copilot-api@latest start --port 8080 --verbose\n\n# 执行认证流程\nnpx @jeffreycao/copilot-api@latest auth login\n\n# 配置第三方 provider，然后不依赖 GitHub Copilot 启动\nnpx @jeffreycao/copilot-api@latest auth login --provider dashscope\nnpx @jeffreycao/copilot-api@latest start\n\n# 以 JSON 格式输出调试信息\nnpx @jeffreycao/copilot-api@latest debug --json\n\n# 用 Bun 而不是 Node.js 运行已发布 CLI\nbunx --bun @jeffreycao/copilot-api@latest start\n```\n\n配置 `dashscope` 后的 OpenAI 兼容 provider 调用示例：\n\n```sh\ncurl http://localhost:4141/v1/chat/completions \\\n  -H \"content-type: application/json\" \\\n  -d '{\"model\":\"dashscope/qwen3.6-plus\",\"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]}'\n\ncurl http://localhost:4141/dashscope/v1/messages \\\n  -H \"content-type: application/json\" \\\n  -d '{\"model\":\"qwen3.6-plus\",\"max_tokens\":1024,\"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]}'\n```\n\n## 使用建议\n\n<a id=\"claudemd-or-agentsmd-recommended-content\"></a>\n\n### CLAUDE.md 或 AGENTS.md 推荐内容\n\n如果你想手动加入这些提醒，请在 Claude Code 的 `CLAUDE.md`，或 opencode/codex 的 `AGENTS.md` 中加入以下内容：\n\n```\n- Prohibited from directly asking questions to users, MUST use question tool.\n- Once you can confirm that the task is complete, MUST use question tool to make user confirm. The user may respond with feedback if they are not satisfied with the result, which you can use to make improvements and try again, after try again, MUST use question tool to make user confirm again.\n```\n"}, "65d5c76f68a6bdbe663df12cf6117ba479fbf509": {"t": 1785765536.8208888, "n": 34026, "h": "7e6bd4b98b62b134", "c": "# Copilot API Proxy\n\n[English](./README.md) | 简体中文\n\n## 重要说明\n\n> [!IMPORTANT]\n> **使用前请先注意以下几点：**\n>\n> 1. **Claude Code 配置：** 与 Claude Code 搭配使用时，请将模型 ID 配置为 `claude-opus-4-8`。示例 claude `settings.json` 见 [通过 `settings.json` 手动配置](#manual-configuration-with-settingsjson)。\n>\n> 2. **内置 `copilot`、`codex` 与第三方 provider：** 执行 `npx @jeffreycao/copilot-api@latest auth`，可选择 `copilot`、`codex`、`deepseek`、`custom` 等 provider。\n>\n> 3. **注意事项：** README 顶部移除的 GitHub Copilot warning 见 [GitHub Copilot 安全提示](./NOTICE.md#github-copilot-security-notice)。\n\n---\n\n## 项目概览\n\n这是一个小型 AI gateway，可以使用 GitHub Copilot、内置 `codex` provider，也可以使用 DashScope 等已配置的第三方 provider。GitHub Copilot 现在是可选能力：如果本地没有 GitHub token，只要至少配置了一个启用中的 provider，服务仍可按 provider-only 模式启动。\n\nAI gateway 会从同一个本地端点暴露 OpenAI / Anthropic 兼容 API，让 [Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview)、OpenCode、Codex 和 OpenAI 兼容客户端可以共用同一个本地服务。\n\n在 GitHub Copilot 路径上，AI gateway 会在可用时优先使用 Copilot 原生的 Anthropic 风格 Messages API，在重工具调用场景下保留更原生的 Claude 行为。\n\n## 功能特性\n\n- **OpenAI 与 Anthropic 双兼容**：通过 `/v1/responses`、`/v1/chat/completions`、`/v1/models`、`/v1/embeddings` 和 `/v1/messages` 对外暴露同一个本地 AI gateway。\n- **Copilot 可选**：有 GitHub 凭据时可以使用 GitHub Copilot，没有 GitHub 凭据时也可以只依赖已配置的 provider 运行。\n- **同一网关接入 Copilot、`codex` 与第三方 provider**：可统一路由 GitHub Copilot、内置 `codex` provider 和配置好的外部 provider。\n- **第三方 provider 可独立启动**：配置 DashScope、DeepSeek、OpenRouter 或自定义 provider 后，不需要 GitHub Copilot 登录即可启动 AI gateway。\n- **OpenAI 兼容 provider 同时支持 chat 和 Messages API**：`openai-compatible` provider 可通过顶层 `/v1/chat/completions` 搭配 `model: \"provider/model\"` 提供 Chat Completions，也可通过 `/v1/messages` 完成 Anthropic Messages 的请求/响应翻译。\n- **面向 Claude 的更原生 Copilot 路由**：优先使用原生 `/v1/messages`，保留 Claude 风格工具流，支持 Anthropic beta 能力、通过 Responses-capable 模型支持 Claude WebSearch，并保留 subagent / session 标记。\n- **Claude Code 与 OpenCode 集成**：兼容 Claude Code 与 OpenCode，也支持通过 `@ai-sdk/anthropic` 直接作为 Anthropic provider 使用。\n- **灵活的认证与部署选项**：支持交互式登录、直接 token、个人 / Business / Enterprise、GitHub Enterprise、opencode OAuth 和自定义数据目录。\n- **多 provider 路由**：可暴露 `/:provider/...` 路由，也可在顶层 API 上使用 `model: \"provider/model\"`。\n\n## 前置要求\n\n- Bun（>= 1.2.x）\n- 如果要通过 `npx` 运行已发布 CLI，需要 Node.js\n- 只有在使用 GitHub Copilot provider 时，才需要已订阅 Copilot 的 GitHub 账号\n- 如果不使用 GitHub Copilot，需要至少一个已配置 provider 的 API key 或 OAuth 登录\n\n## 安装\n\n安装依赖：\n\n```sh\nbun install\n```\n\n直接从源码启动服务：\n\n```sh\nbun run start start\n```\n\n## 从源码运行\n\n本项目可以通过多种方式从源码运行：\n\n### 开发模式\n\n```sh\nbun run dev start\n```\n\n### 生产模式\n\n```sh\nbun run start start\n```\n\n## 通过 npx 使用\n\n你可以直接用 npx 运行本项目：\n\n> [!IMPORTANT]\n> 通过 `npx` 运行时，token usage 存储会使用 Node 内置的 `node:sqlite` 模块。该能力会在 Node.js >= 22.13.0 时启用；Node.js < 22.13.0 时 CLI 仍可启动，但会禁用 token usage 存储。\n>\n> 如果不升级 Node.js 但仍需要 token usage 存储，可以改用 Bun 运行已发布 CLI：`bunx --bun @jeffreycao/copilot-api@latest start`。\n\n```sh\nnpx @jeffreycao/copilot-api@latest start\n```\n\n带参数示例：\n\n```sh\nnpx @jeffreycao/copilot-api@latest start --port 8080\n```\n\n如果只想做认证或 provider 配置：\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth\n```\n\n如果要不依赖 GitHub Copilot 运行，先配置至少一个 provider，然后正常启动服务：\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth login --provider dashscope\nnpx @jeffreycao/copilot-api@latest start\n```\n\n## 配合 Docker 使用\n\n构建镜像：\n\n```sh\ndocker build -t copilot-api .\n```\n\n通过 bind mount 运行容器，让认证数据在重启后保留：\n\n```sh\nmkdir -p ./copilot-data\ndocker run -p 4141:4141 -v $(pwd)/copilot-data:/root/.local/share/copilot-api copilot-api\n```\n\n这会把宿主机上的 `./copilot-data` 映射到容器内的 `/root/.local/share/copilot-api`，用于持久化 GitHub 认证数据、provider 配置和其他 gateway 状态。\n\n也可以直接通过环境变量传入 GitHub token：\n\n```sh\ndocker run -p 4141:4141 -e GH_TOKEN=your_github_token_here copilot-api\n```\n\n## Electron 桌面应用\n\n如果你更喜欢图形界面，仓库里还提供了位于 `desktop/` 的 Electron 桌面应用。它支持 GitHub Copilot 登录、OpenAI Codex OAuth，以及 DeepSeek、DashScope、OpenRouter 或自定义 provider 的 API Key 配置。授权或配置 provider 后，可以一键启动或停止本地代理，并在界面里直接查看本地端点、鉴权 Header、可用模型、额度和日志。\n\n设置页还可以配置 `OAuth App`、`API Home`、`Enterprise URL`、详细日志以及最小化到托盘。Windows x64（`.exe`）、macOS Apple Silicon（`.dmg`）和 Linux x64（`.AppImage`）安装包发布在 GitHub Releases：\n\nhttps://github.com/caozhiyuan/copilot-api/releases\n\nLinux 用户需要先为下载的 AppImage 添加执行权限：\n\n```sh\nchmod +x Copilot-API-*-linux-x86_64.AppImage\n./Copilot-API-*-linux-x86_64.AppImage\n```\n\n下载对应平台的安装包后，在应用内授权或配置 provider，选择端口并启动服务，再把你的客户端指向应用里显示的本地端点即可。发布版桌面应用使用随包内置的 Electron 运行时，正常使用不需要额外安装 Node.js；token usage 历史记录会在该内置运行时支持 SQLite 时启用。\n\n桌面应用里的高级配置页会通过 `GET/POST /admin/config/model-mappings` 读写这份共享的模型映射。同一份映射会统一作用于 `POST /v1/messages`、`POST /v1/messages/count_tokens`、`POST /v1/responses` 和 `POST /v1/chat/completions`，不再按接口区分。它使用的是 `auth.adminApiKey`，不是普通的 `auth.apiKeys`；应用会在服务启动并自动生成该 key 后，直接从 `config.json` 读取它来发起请求。\n\n### 桌面应用截图\n\n下面展示了桌面应用中的首页、Token 用量统计页面：\n\n<p align=\"center\">\n  <img src=\"./docs/screenshots/desktop-dashboard.png\" alt=\"Copilot API 桌面应用首页\" width=\"49%\" />\n  <img src=\"./docs/screenshots/desktop-token-usage.png\" alt=\"Copilot API 桌面应用 Token 用量页\" width=\"49%\" />\n</p>\n\n## 与 Claude Code 一起使用\n\n这个 AI gateway 可以为 [Claude Code](https://docs.anthropic.com/en/claude-code) 提供后端能力。Claude Code 是 Anthropic 提供的实验性面向开发者的对话式 AI 助手。\n\n有两种方式可以把 Claude Code 配置为使用这个 AI gateway：\n\n### 通过 `--claude-code` 标志进行交互式配置\n\n执行带 `--claude-code` 的 `start` 命令开始：\n\n```sh\nnpx @jeffreycao/copilot-api@latest start --claude-code\n```\n\n你不再需要手动选择模型。Gateway 会自动检测每个 Claude Code 尺寸档位对应的最新可用模型——opus 映射到最新的 Opus 模型，sonnet 映射到最新的 Sonnet 模型，haiku 映射到最新的 Haiku 模型——并生成相应设置 `ANTHROPIC_DEFAULT_OPUS_MODEL`、`ANTHROPIC_DEFAULT_SONNET_MODEL` 和 `ANTHROPIC_DEFAULT_HAIKU_MODEL` 的命令。若某个档位没有匹配的可用模型，则会被省略。该命令会被复制到剪贴板，并设置 Claude Code 使用这个 AI gateway 所需的环境变量。\n\n在新的终端中粘贴并执行这条命令，即可启动 Claude Code。\n\n<a id=\"manual-configuration-with-settingsjson\"></a>\n\n### 通过 `settings.json` 手动配置\n\n另一种方式是在项目根目录中创建 `.claude/settings.json` 文件，并写入 Claude Code 所需的环境变量。这样你就不需要每次都运行交互式配置了。\n\n下面是一个 `.claude/settings.json` 示例：\n\n```json\n{\n  \"env\": {\n    \"ANTHROPIC_BASE_URL\": \"http://localhost:4141\",\n    \"ANTHROPIC_AUTH_TOKEN\": \"dummy\",\n    \"ANTHROPIC_MODEL\": \"gpt-5.6-sol[1m]\",\n    \"ANTHROPIC_DEFAULT_SONNET_MODEL\": \"gpt-5.6-sol[1m]\",\n    \"ANTHROPIC_DEFAULT_HAIKU_MODEL\": \"gpt-5.6-luna[1m]\",\n    \"CLAUDE_CODE_AUTO_COMPACT_WINDOW\": \"272000\",\n    \"CLAUDE_CODE_USE_VERTEX\": \"0\",\n    \"CLAUDE_CODE_USE_BEDROCK\": \"0\",\n    \"DISABLE_NON_ESSENTIAL_MODEL_CALLS\": \"1\",\n    \"CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC\": \"1\",\n    \"CLAUDE_CODE_ATTRIBUTION_HEADER\": \"0\",\n    \"CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION\": \"false\",\n    \"CLAUDE_CODE_DISABLE_TERMINAL_TITLE\": \"true\",\n    \"CLAUDE_CODE_ENABLE_AWAY_SUMMARY\": \"0\"\n  },\n  \"alwaysThinkingEnabled\": true,\n  \"effortLevel\": \"xhigh\",\n  \"showThinkingSummaries\": true\n}\n```\n\n- 请根据需要替换 `ANTHROPIC_MODEL`、`ANTHROPIC_DEFAULT_OPUS_MODEL`、`ANTHROPIC_DEFAULT_SONNET_MODEL` 和 `ANTHROPIC_DEFAULT_HAIKU_MODEL`。配置完成后，请安装 claude code 插件，见 [插件集成](#plugin-integrations)。\n- 如果你使用的是 codex provider，建议**不要**将模型名配置成 `codex/xxx` 格式（如 `codex/gpt-5.6-sol`）。Claude Code 会针对 `codex/` 前缀做降智行为——例如每次请求时移除所有之前返回的思考块（thinking blocks）。请使用纯模型名（如 `gpt-5.6-sol`），并在 `config.json` 中配置 `modelMappings` 将其映射回 codex provider：\n  ```json\n  \"modelMappings\": {\n    \"gpt-5.6-sol\": \"codex/gpt-5.6-sol\",\n    \"gpt-5.6-terra\": \"codex/gpt-5.6-terra\",\n    \"gpt-5.6-luna\": \"codex/gpt-5.6-luna\"\n  },\n  ```\n- 将 `CLAUDE_CODE_ATTRIBUTION_HEADER` 设为 `0` 可以阻止 Claude Code 在 system prompt 中附加计费和版本信息，从而避免 prompt cache 失效。\n- 关闭 `CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION` 和 `CLAUDE_CODE_ENABLE_AWAY_SUMMARY` 可以避免不必要地消耗额度。\n- Claude Code WebSearch 已支持纯搜索请求。Copilot 路径请保持全局 `messageApiWebSearchModel` 指向 Responses-capable GPT 模型或 `provider/model` 别名；provider 路由请使用原生 Anthropic provider 或 `openai-responses` provider。只有在你明确想禁止这类流量时，才需要把 `WebSearch` 加到 `permissions.deny`。\n- 如果使用的不是 Claude 模型，请不要启用 `ENABLE_TOOL_SEARCH`。如果使用的是 Claude 模型，则可以启用 `ENABLE_TOOL_SEARCH`。当前 Claude Code 使用的是客户端 tool search 模式，在该模式下每次加载 defer tools 都需要额外请求一次。\n- `CLAUDE_CODE_AUTO_COMPACT_WINDOW`：设置用于自动压缩计算的上下文容量（以 token 为单位）。默认使用模型自身的上下文窗口：标准模型为 200K，扩展上下文模型为 1M。使用 1M 上下文模型（如 `claude-opus-4-6[1m]`）时，可设置一个较低的值（如 `500000`）将窗口视为 500K 用于压缩计算。该值受限于模型的实际上下文窗口上限。`CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` 会基于此值的百分比生效。设置此变量可将压缩阈值与状态栏的 `used_percentage` 解耦（后者始终使用模型的完整上下文窗口）。\n\n更多选项见：[Claude Code settings](https://docs.anthropic.com/en/docs/claude-code/settings#environment-variables)\n\n也可以参考 IDE 集成说明：[Add Claude Code to your IDE](https://docs.anthropic.com/en/docs/claude-code/ide-integrations)\n\n## 与 OpenCode 一起使用\n\nOpenCode 已经有直接的 GitHub Copilot provider。本节适用于你希望让 OpenCode 通过 `@ai-sdk/anthropic` 指向这个 AI gateway，并复用本 README 前面提到的 agent 行为时。\n\n### 最小配置\n\n使用 OpenCode OAuth app 启动 AI gateway：\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth --oauth-app=opencode\nnpx @jeffreycao/copilot-api@latest start\n```\n\n然后让 OpenCode 通过 `@ai-sdk/anthropic` 指向这个 AI gateway。\n\n示例 `~/.config/opencode/opencode.json`：\n\n```json\n{\n  \"$schema\": \"https://opencode.ai/config.json\",\n  \"provider\": {\n    \"local\": {\n      \"npm\": \"@ai-sdk/anthropic\",\n      \"name\": \"My Local\",\n      \"options\": {\n        \"baseURL\": \"http://localhost:4141/v1\",\n        \"apiKey\": \"dummy\"\n      },\n      \"models\": {\n        \"gpt-5.4\": {\n          \"name\": \"gpt-5.4\",\n          \"modalities\": {\n            \"input\": [\"text\", \"image\"],\n            \"output\": [\"text\"]\n          },\n          \"limit\": {\n            \"context\": 400000,\n            \"input\": 272000,\n            \"output\": 128000\n          }\n        },\n        \"claude-sonnet-4.6\": {\n          \"id\": \"claude-sonnet-4.6\",\n          \"name\": \"claude-sonnet-4.6\",\n          \"modalities\": {\n            \"input\": [\"text\", \"image\"],\n            \"output\": [\"text\"]\n          },\n          \"limit\": {\n            \"context\": 200000,\n            \"output\": 32000\n          },\n          \"options\": {\n            \"thinking\": {\n              \"type\": \"adaptive\"\n            },\n            \"effort\": \"max\"\n          }\n        }\n      }\n    }\n  }\n}\n```\n\n这些字段的重要性：\n\n- `npm: \"@ai-sdk/anthropic\"` 是关键。OpenCode 会以 Anthropic Messages 语义与这个 AI gateway 通信，而不是把一切扁平化为 OpenAI Chat Completions。\n- `options.baseURL` 应设为 `http://localhost:4141/v1`；Anthropic SDK 会自动补上 `/messages`、`/models` 和 `/messages/count_tokens`。\n- 如果你在此代理中启用了 `auth.apiKeys`，请把 `dummy` 替换为真实 key；否则任意占位值都可以。\n\n## 与 Codex 一起使用\n\n这个 AI gateway 也可以为 Codex 提供后端能力。\n\n### Codex `config.toml` 参考配置\n\n把以下 `[model_providers.copilot_api]` 段加入你的 Codex `~/.codex/config.toml`：\n\n```toml\nmodel_provider = \"copilot_api\"\nmodel_reasoning_summary = \"auto\"\nmodel_context_window = 272000\nmodel_auto_compact_token_limit = 244800\n\n[model_providers.copilot_api]\nname = \"OpenAI\"\nbase_url = \"http://localhost:4141\"\nenv_key = \"GITHUB_COPILOT_API_KEY\"\nrequires_openai_auth = true\nsupports_websockets = false\nwire_api = \"responses\"\nrequest_max_retries = 3\nstream_max_retries = 1\nstream_idle_timeout_ms = 300000\n\n[features]\nremote_compaction_v2 = true\n\n[analytics]\nenabled = false\n```\n\n> [!NOTE]\n> 此配置仅限于 Codex 与 GitHub Copilot provider。`name` 一定要配置为 `\"OpenAI\"`。它可以缓解 Codex local compact 不命中缓存的问题。\n> 如果使用 codex provider，建议将 `base_url` 配置为 `\"http://localhost:4141/codex\"`。\n\n## GPT Tool Search\n\n对于 `gpt-5.4+` 这类 GPT Responses 模型，这个 AI gateway 可以通过一个很小的 MCP bridge 暴露 Responses `tool_search`。Claude Code 和 opencode 都可以使用同一个 bridge，前提是客户端会加载 MCP server，并且 Anthropic Messages 流量会经过这个 AI gateway。\n\nGPT 模型不要设置 Claude Code 原生的 `ENABLE_TOOL_SEARCH`。这个开关启用的是 Claude Code 自己的客户端 tool search 模式，可能导致 deferred 工具定义不再转发给 AI gateway。这个 AI gateway 需要完整的工具定义，这样才能只保留那一小组常驻加载工具，其余工具统一转换为 Responses deferred namespace。\n\n如果你安装了 `tool-search@copilot-api-marketplace`，Claude Code 会自动带上这个 MCP bridge，可以跳过下面这段 Claude Code MCP 手动配置。\n\n请把 tool search bridge 加到 Claude Code 使用的 MCP 配置中：\n\n```json\n{\n  \"mcpServers\": {\n    \"tool_search\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@jeffreycao/copilot-api@latest\", \"mcp\"]\n    }\n  }\n}\n```\n\n请把 tool search bridge 加到 opencode 使用的 MCP 配置中：\n\n```json\n{\n  \"mcp\": {\n    \"tool_search\": {\n      \"type\": \"local\",\n      \"command\": [\"npx\", \"-y\", \"@jeffreycao/copilot-api@latest\", \"mcp\"]\n    }\n  }\n}\n```\n\n本地开发时可以将命令换成 `bun`，参数换成 `[\"run\", \"./src/main.ts\", \"mcp\"]`。\n\nAI gateway 内部现在会把 OpenAI Responses `tool_search` 配置成 client-executed 模式。deferred tools 仍然会作为可搜索 namespace 暴露给模型，但会明确要求模型直接返回下一步要加载的精确工具名列表。\n\n该 bridge 使用直接工具选择，不做 query 搜索。工具入参是 `names`，值为逗号分隔的精确 deferred 工具名，例如 `TaskList,TaskGet,mcp__fetch__fetch`。\n\n<a id=\"plugin-integrations\"></a>\n\n## 插件集成\n\n本项目为 Claude Code 和 opencode 提供了插件集成。\n\n#### Claude Code 插件集成（基于 marketplace）\n\nClaude Code 集成现在拆分为两个插件：\n\n- `agent-inject` 会在 `SubagentStart` 时注入 `__SUBAGENT_MARKER__...`，以便 AI gateway 推导 `x-initiator: agent`。\n- `tool-search` 会注册用于 GPT Responses deferred tool loading 的 `tool_search` MCP bridge。\n\n- 本仓库中的 marketplace catalog：`.claude-plugin/marketplace.json`\n- 本仓库中的插件源码：`plugin/claude/agent-inject`、`plugin/claude/tool-search`\n\n远程添加 marketplace：\n\n```sh\n/plugin marketplace add https://github.com/caozhiyuan/copilot-api.git\n```\n\n从 marketplace 安装插件：\n\n```sh\n/plugin install agent-inject@copilot-api-marketplace\n/plugin install tool-search@copilot-api-marketplace\n```\n\n安装后，`agent-inject` 会在 `SubagentStart` 时注入 `__SUBAGENT_MARKER__...`，AI gateway 会利用它推导 `x-initiator: agent`。\n\n`agent-inject` 还会注册一个 `UserPromptSubmit` hook，并返回 `{\"continue\": true}`；同时它也可以通过环境变量注入 `SessionStart` reminder 规则：\n\n- `CLAUDE_PLUGIN_ENABLE_QUESTION_RULES=1` 会自动为 Claude Code 启用两条关于使用 `question` 工具的提醒。你也可以把同样的提醒手动写进 `CLAUDE.md`；见 [CLAUDE.md 或 AGENTS.md 推荐内容](#claudemd-or-agentsmd-recommended-content)。\n- `CLAUDE_PLUGIN_ENABLE_NO_BACKGROUND_AGENTS_RULE=1` 会启用关于避免在 agent hooks 中使用 `run_in_background: true` 的提醒。\n\n`tool-search` 插件内置了 [GPT Tool Search](#gpt-tool-search) 一节描述的同一个 MCP bridge，因此安装该插件后，Claude Code 用户无需再手动配置 `tool_search` server。\n\n#### Opencode 插件\n\nsubagent 标记生成器被打包为一个 opencode 插件，位于 `plugin/opencode/subagent-marker.js`。\n\n**安装方式：**\n\n将插件文件复制到你的 opencode 插件目录：\n\n```sh\n# 克隆或下载本仓库后复制该插件\ncp plugin/opencode/subagent-marker.js ~/.config/opencode/plugins/\n```\n\n或者手动在 `~/.config/opencode/plugins/subagent-marker.js` 创建该文件，并填入插件内容。\n\n**功能：**\n\n- 跟踪 subagent 创建的子会话\n- 自动在 subagent 聊天消息前添加 marker system reminder（`__SUBAGENT_MARKER__...`）\n- 设置 `x-session-id` 请求头以跟踪会话\n- 让这个 AI gateway 能够把来自 subagent 的请求识别为 `x-initiator: agent`\n\n该插件会挂接到 `session.created`、`session.deleted`、`chat.message` 和 `chat.headers` 事件上，以无缝提供 subagent marker 能力。\n\n## 使用量查看器\n\n服务启动后，控制台会输出一个 Copilot 使用量看板 URL。这个看板是一个用于监控 API 用量的 Web 界面。\n\n1. 启动服务。例如使用 npx：\n   ```sh\n   npx @jeffreycao/copilot-api@latest start\n   ```\n2. 服务会输出一个 usage viewer 的 URL。将它复制到浏览器中打开，形式大致如下：\n   `http://localhost:4141/usage-viewer?endpoint=http://localhost:4141/usage`\n   - 如果你在 Windows 上使用 `start.bat` 脚本，这个页面会自动打开。\n\n看板提供了更易读的 Copilot 用量视图：\n\n> token usage 历史记录需要 Bun 或 Node.js >= 22.13.0。Node.js < 22.13.0 时服务会正常运行，但 token usage 存储会被禁用。\n\n- **API Endpoint URL**：通过 URL 查询参数指定 API endpoints，默认指向本地服务。支持手动切换为其他兼容 endpoints。\n- **x-api-key 认证**：如果启用了 API Key 认证，可填入 `x-api-key` 请求头。密钥会持久化保存在浏览器本地存储中。\n- **Period 选择器**：支持 Day / Week / Month 三种时间范围，切换时 URL 参数会自动同步，方便收藏和分享。\n- **Fetch Data**：点击 \"Refresh\" 按钮加载或刷新使用数据。页面加载时也会自动拉取数据。\n- **Copilot Quotas 额度**：通过进度条展示 Chat、Completions 等不同服务的额度使用情况，悬停可查看已用/剩余详情。\n- **Token Usage 指标卡片**：汇总当前周期的 Total、Input、Output、Cache Read、Cache Write、Requests 和预估费用。\n- **趋势图（Week / Month）**：提供按模型和指标筛选的折线趋势图，点击数据点可查看单日用量明细。\n- **Model Breakdown 表格**：按模型维度列出周期内的请求数、输入/输出/缓存 token 和预计费用。\n- **Request Events 分页列表**：按时间排序的请求事件记录，支持分页浏览，含时间戳、模型、请求 ID 和 token 用量。\n- **Detailed Information**：展示 API 返回的完整 JSON 响应，便于深入分析所有可用统计数据。\n- **URL-based Configuration**：也可通过 `endpoint` 和 `period` 查询参数直接指定 API 端点与时间范围。例如：\n  `http://localhost:4141/usage-viewer?endpoint=http://your-api-server/usage&period=week`\n\n### Usage Viewer 截图\n\n<p align=\"center\">\n  <img src=\"./docs/screenshots/usage-viewer.png\" alt=\"Copilot API Usage Viewer 页面\" width=\"900\" />\n</p>\n\n## 命令结构\n\nCopilot API 现在使用子命令结构，主要命令包括：\n\n- `start`：启动 AI gateway 服务。如果已有 GitHub token，则启用 Copilot 路径；如果没有 GitHub token，但存在至少一个启用中的 provider，则按 provider-only 模式启动；如果两者都没有，会引导你配置 provider。\n- `auth`：仅执行 provider 登录或配置流程，不启动服务。可用于 GitHub Copilot 登录、Codex OAuth，或第三方 provider API key 配置。\n- `debug`：显示诊断信息，包括版本、运行时详情、文件路径以及认证状态，便于排障与支持。\n\n## 命令行选项\n\n### 全局选项\n\n以下选项可用于任意子命令。若在子命令之前传入，请使用 `--key=value` 形式：\n\n| 选项 | 说明 | 默认值 | 别名 |\n| --- | --- | --- | --- |\n| --api-home | API home 目录路径（设置 `COPILOT_API_HOME`） | 无 | 无 |\n| --oauth-app | OAuth app 标识符（设置 `COPILOT_API_OAUTH_APP`） | 无 | 无 |\n| --enterprise-url | GitHub Enterprise URL（设置 `COPILOT_API_ENTERPRISE_URL`） | 无 | 无 |\n\n### Start 命令选项\n\n以下是 `start` 命令可用的命令行选项：\n\n| 选项 | 说明 | 默认值 | 别名 |\n| --- | --- | --- | --- |\n| --port | 监听端口 | 4141 | -p |\n| --verbose | 启用详细日志 | false | -v |\n| --github-token | 直接提供 GitHub token（必须通过 `auth` 子命令生成） | 无 | -g |\n| --claude-code | 生成一个使用 Copilot API 配置启动 Claude Code 的命令 | false | -c |\n| --show-token | 在获取和刷新时显示 GitHub 与 Copilot token | false | 无 |\n| --proxy-env | 从环境变量初始化代理 | false | 无 |\n\n### Auth 命令选项\n\n| 选项 | 说明 | 默认值 | 别名 |\n| --- | --- | --- | --- |\n| --provider | 要登录或配置的 provider（`copilot`、`codex`、`opencode-go`、`deepseek`、`dashscope`、`openrouter` 或 `custom`） | 交互选择 | 无 |\n| --verbose | 启用详细日志 | false | -v |\n| --show-token | 认证时显示 GitHub token | false | 无 |\n\n只有在需要启用 GitHub Copilot provider 时，才需要执行 `copilot-api auth login --provider copilot`。使用 `codex` 或第三方 provider-only 模式不要求配置 Copilot。\n\n使用 `copilot-api auth login --provider deepseek`、`--provider dashscope`、`--provider openrouter` 或 `--provider opencode-go` 可以通过 CLI 快速新增或更新这些常用第三方 provider。DeepSeek 会提示输入掩码显示的 `apiKey`、provider `type`（默认 `anthropic`），以及默认 `https://api.deepseek.com/anthropic` 的 `baseUrl`。DashScope 会提示输入掩码显示的 `apiKey`、provider `type`（默认 `openai-compatible`）和预填默认值的 `baseUrl`。OpenRouter 只提示输入掩码显示的 `apiKey` 和预填默认值的 `baseUrl`，并固定写入 `type: \"anthropic\"`。OpenCode Go 只提示输入掩码显示的 `apiKey` 和预填默认值的 `baseUrl`，并固定写入 `type: \"openai-compatible\"`（baseUrl `https://opencode.ai/zen/go`）。配置并启用 provider 后，`copilot-api start` 可在没有 GitHub token 的情况下启动。\n\n使用 `copilot-api auth login --provider custom` 可以通过 CLI 新增或更新其他第三方 provider。命令会依次提示输入 provider name、项目支持的 type（`anthropic`、`openai-compatible` 或 `openai-responses`）、`baseUrl`、掩码显示的 `apiKey` 和 `authType`；`authType` 可保持 type 默认值，也可选择 `x-api-key` / `authorization`。\n\n### Debug 命令选项\n\n| 选项 | 说明 | 默认值 | 别名 |\n| --- | --- | --- | --- |\n| --json | 以 JSON 输出调试信息 | false | 无 |\n\n<a id=\"configuration-configjson\"></a>\n\n## 配置（config.json）\n\n- **位置：** Linux/macOS 为 `~/.local/share/copilot-api/config.json`，Windows 为 `%USERPROFILE%\\.local\\share\\copilot-api\\config.json`。\n- **默认结构：**\n  ```json\n  {\n    \"auth\": {\n      \"apiKeys\": [],\n      \"adminApiKey\": \"<startup 自动生成>\"\n    },\n    \"providers\": {},\n    \"modelMappings\": {},\n    \"extraPrompts\": {\n      \"gpt-5-mini\": \"<built-in exploration prompt>\"\n    },\n    \"smallModel\": \"gpt-5-mini\",\n    \"contextManagement\": {\n      \"messages\": true,\n      \"responses\": false\n    },\n    \"modelResponsesApiCompactThresholds\": {\n      \"gpt-5.4\": 217600,\n      \"gpt-5.5\": 217600,\n      \"gpt-5.6-sol\": 231200,\n      \"gpt-5.6-terra\": 231200,\n      \"gpt-5.6-luna\": 231200\n    },\n    \"modelReasoningEfforts\": {\n      \"gpt-5-mini\": \"low\"\n    },\n    \"useMessagesApi\": true,\n    \"useResponsesApiWebSocket\": true,\n    \"useResponsesApiWebSearch\": true,\n    \"messageApiWebSearchModel\": \"gpt-5-mini\"\n  }\n  ```\n- **auth.apiKeys：** 用于普通非 admin 路由的 API key。支持多个 key 轮换使用。请求可通过 `x-api-key: <key>` 或 `Authorization: Bearer <key>` 进行认证。若为空或省略，则普通路由的认证会被禁用。\n- **auth.adminApiKey：** 仅用于 `/admin/*` 路由的单个 admin key。若未配置，服务会在启动时自动生成一个随机 key，并回写到 `config.json`。它同样使用 `x-api-key` 或 `Authorization: Bearer` 这两种头，但普通 `auth.apiKeys` 不能访问 `/admin/*`。\n- **modelMappings：** 用于顶层 `POST /v1/messages`、`POST /v1/messages/count_tokens`、`POST /v1/responses` 和 `POST /v1/chat/completions` 请求的精确 `sourceModel -> targetModel` 重写映射，这几类接口共用同一份规则。省略该字段或保留为 `{}` 时，不会做模型重写。`source` 和 `target` 都必须是非空字符串。`target` 可以是普通模型 ID，也可以是 `provider/model` 形式的别名，例如 `dashscope/qwen3.6-plus`；重写发生在 provider alias 解析之前。这些映射不再按接口区分。`GET/POST /admin/config/model-mappings` 管理接口读写的也只有这个字段。\n- **extraPrompts：** `model -> prompt` 的映射。把 Anthropic 风格请求翻译为 Responses API 时，会将其附加到第一条 system prompt 后面。你可以借此为不同模型注入护栏或指引。缺失的默认项会自动补齐，但不会覆盖你自定义的 prompt。对于 GPT-5.3+ 模型（如 `gpt-5.3-codex`、`gpt-5.4`、`gpt-5.5`），未显式配置时会自动使用内置的 commentary prompt。内置 prompt 会启用带阶段感知的 commentary，让模型在工具调用或更深层推理前先发出简短的用户可见进度说明。\n- **providers：** 全局上游 provider 映射。每个 provider key（例如 `dashscope`）都会变成一个路由前缀（`/dashscope/v1/messages`）。支持 `type: \"anthropic\"`、`type: \"openai-compatible\"` 和 `type: \"openai-responses\"`。顶层客户端也可以在 `/v1/messages`、`/v1/messages/count_tokens`、`/v1/responses` 和 `/v1/chat/completions` 中使用 `model: \"dashscope/model-id\"`；AI gateway 会在转发上游前移除 `dashscope/` 前缀。`openai-compatible` provider 同时支持 chat 和 Messages 流程：`/v1/chat/completions` 会直连上游 `/v1/chat/completions`，而 `/v1/messages` 和 `/:provider/v1/messages` 会先翻译为上游 Chat Completions，再把响应翻译回 Anthropic Messages。`GET /v1/models` 会聚合已启用 provider 的模型，并以 `provider/model-id` 形式返回；单个 provider 的原始模型列表仍可使用 `GET /dashscope/v1/models`。\n  - `enabled`：可选，若省略则默认为 `true`。\n  - `baseUrl`：provider API 的基础 URL，不要带结尾的 endpoint。Anthropic provider 不要带 `/v1/messages`；OpenAI 兼容 provider 不要带 `/v1/chat/completions`；OpenAI Responses provider 不要带 `/v1/responses`。\n  - `apiKey`：作为上游凭据值使用；普通 provider 必须配置。\n  - `authType`：可选，控制 `apiKey` 如何发送到上游。普通 provider 支持 `x-api-key` 和 `authorization`。Anthropic provider 默认 `x-api-key`；OpenAI 兼容和 OpenAI Responses provider 默认 `authorization`。当设置为 `authorization` 时，代理会发送 `Authorization: Bearer <apiKey>`。`oauth2` 仅保留给内置 `codex` provider，并由 `auth login --provider codex` 自动写入。\n  - `pricingCurrency`：可选，provider 维度的 token 费用币种，例如 `USD` 或 `CNY`。快捷 provider 默认 DashScope、DeepSeek 为 `CNY`，Codex/OpenRouter 为 `USD`。费用按币种分别汇总，不做汇率换算。\n  - `models`：可选，按模型 ID 配置的映射。每个键为请求中的模型名，值支持：\n    - `temperature`：可选，当请求未指定时使用的默认温度。\n    - `topP`：可选，当请求未指定时使用的默认 `top_p`。\n    - `topK`：可选，当请求未指定时使用的默认 `top_k`。\n    - `extraBody`：可选，按模型合入上游请求体的动态字段；请求体显式同名字段优先。OpenAI 兼容 provider 可用它配置 `enable_thinking`、`preserve_thinking`、`reasoning_effort` 等字段。`thinking_budget` 是 OpenAI 兼容 provider 的特殊覆盖项：配置在 `extraBody` 后，会在 Anthropic `thinking.budget_tokens` 翻译之后强制写入，并覆盖请求派生出的预算值。对于 provider name 为 `dashscope` 或 `baseUrl` 包含 `aliyuncs.com` 的 provider，请求派生的 `thinking_budget`（来自 Anthropic `thinking.budget_tokens`）会转发给上游；其他 OpenAI 兼容 provider 会移除请求派生的 `thinking_budget`，但 `extraBody` 中的 `thinking_budget` 仍然生效。对于 DashScope provider，当 `preserve_thinking` 未在 `extraBody` 或请求体中显式设置时，默认为 `true`。\n    - `pricing`：可选，按模型配置 token 单价，币种使用 provider 的 `pricingCurrency`，单位为每 100 万 tokens。支持 `input`、`output`、`cachedInput`（隐式缓存读）、`explicitCachedInput`（显式缓存读）和 `cacheCreationInput`。如需按输入 token 总量分档，可用带 `maxInputTokens` 的 `tiers`。\n    - `contextCache`：可选，provider name 为 `dashscope` 或 `baseUrl` 包含 `aliyuncs.com` 时默认 `true`，其他 OpenAI 兼容 provider 默认 `false`。用于启用阿里云百炼/DashScope 的显式缓存（explicit context cache），会按其 Context Cache 格式在最多 4 个 content block 上注入 `cache_control: { \"type\": \"ephemeral\" }`。缓存断点策略与 opencode 主链路保持一致：前 2 条 system 消息 + 最后 2 条非 system 消息。标记字符串 content 时会把 `system` / `user` / `assistant` / `tool` 消息转换为 text content part 数组；已有数组 content 则标记最后一个 part。如果模型本身已经支持隐式缓存，或上游不支持该显式缓存扩展字段，可在模型配置中设为 `false`。支持相同显式缓存扩展的非 DashScope provider 可设为 `true`。同时适用于 `/v1/messages` 和 `/v1/chat/completions` 路由。\n    - `supportPdf`：可选，控制该模型是否支持 PDF/document content。默认 `false`，不支持时会把 PDF 转成提示文本；设为 `true` 时会把 PDF/document 转成 OpenAI Chat Completions 的 file part。\n    - `toolContentSupportType`：可选，配置该模型的 tool result content 支持能力，值为 `array`、`image`、`pdf` 的数组。provider 侧未配置时默认只发送 string tool content。若 `supportPdf` 为 `true` 但这里不包含 `pdf`，tool result 里的 file part 会被转成 user role 消息。Copilot 主链路不使用这个 provider 默认，仍按 array + image 且不支持 PDF 的能力处理。\n    - `type`：可选，按模型覆盖 provider 的协议类型。支持 `anthropic`、`openai-compatible` 和 `openai-responses`。设置后，provider 的 `/v1/messages` 路由会使用该模型的 type 替代 provider 级别的 type 进行请求路由、认证头解析和上游端点选择。适用于 OpenCode Go 等上游对不同模型同时支持 OpenAI 兼容和 Anthropic Messages API 的 provider。覆盖 type 时，认证头按覆盖后 type 的默认值解析（Anthropic 默认 `x-api-key`；OpenAI 兼容/Responses 默认 `authorization`）。\n\n  DashScope 模型配置示例：\n  ```json\n  {\n    \"providers\": {\n      \"dashscope\": {\n        \"type\": \"openai-compatible\",\n        \"enabled\": true,\n        \"baseUrl\": \"https://dashscope.aliyuncs.com/compatible-mode\",\n        \"apiKey\": \"sk-your-dashscope-key\",\n        \"pricingCurrency\": \"CNY\",\n        \"models\": {\n          \"qwen3.7-plus\": {\n            \"temperature\": 1,\n            \"topP\": 0.95,\n            \"topK\": 20,\n            \"extraBody\": {\n              \"preserve_thinking\": true\n            }\n          },\n          \"glm-5.1\": {\n            \"temperature\": 0.7,\n            \"topP\": 0.95,\n            \"contextCache\": true,\n            \"pricing\": {\n              \"tiers\": [\n                {\n                  \"maxInputTokens\": 32000,\n                  \"input\": 6,\n                  \"cachedInput\": 1.2,\n                  \"explicitCachedInput\": 0.6,\n                  \"cacheCreationInput\": 7.5,\n                  \"output\": 24\n                },\n                {\n                  \"maxInputTokens\": 200000,\n                  \"input\": 8,\n                  \"cachedInput\": 1.6,\n                  \"explicitCachedInput\": 0.8,\n                  \"cacheCreationInput\": 10,\n                  \"output\": 28\n                }\n              ]\n            },\n            \"extraBody\": {\n              \"preserve_thinking\": true\n            }\n          }\n        }\n      }\n    }\n  }\n  ```\n  内置 token 价格覆盖 Codex GPT 模型（USD）、DashScope `qwen3.7-max`、`qwen3.7-plus`、`glm-5.1`、`glm-5.2`（CNY），DeepSeek `deepseek-v4-flash`、`deepseek-v4-pro`、`deepseek-chat`、`deepseek-reasoner`（CNY），以及 OpenCode Go 模型（`glm-5.2`、`grok-4.5`、`deepseek-v4-flash`、`deepseek-v4-pro`、`kimi-k2.7-code`、`kimi-k3`、`mimo-v2.5`、`mimo-v2.5-pro`、`qwen3.7-plus`、`qwen3.7-max`、`minimax-m2.7`、`minimax-m3`，USD）。用户配置的 `pricing` 优先于内置价格。DashScope 若上游 usage 中出现 `cache_creation_input_tokens` 字段，cached tokens 按显式缓存读价计费；否则 `cachedInput` 作为隐式缓存读价。DeepSeek 的 `prompt_cache_hit_tokens` 会归入 cached input，`prompt_cache_miss_tokens` 会归入普通 input。\n- **smallModel：** 无工具预热消息的回退模型（例如 Claude Code 的探测请求）；默认是 `gpt-5-mini`。\n- **contextManagement：** 控制代理是否为 Responses API 附加 `context_management` 压缩指令。`messages` 作用于被翻译成 Responses API 的 Anthropic 风格 `/v1/messages` 请求，包括 `openai-responses` provider 的 Messages 路由，默认值为 `true`。`responses` 作用于 native `/v1/responses` 流量，包括 `provider/model` 别名和内置 `codex` provider，默认值为 `false`。只有在确认客户端支持 context management compaction 后，才建议在 Responses API 下启用 `responses`。启用后，请求体会带上 `context_management`，并在后续轮次中仅保留最新的压缩承载内容。**注意：** 对于 GPT-5.6 及以上模型（如 `gpt-5.6-sol`、`gpt-5.6-terra`、`gpt-5.6-luna`），context management 功能会被强制禁用，因为开启后会破坏这些模型的 prompt 缓存命中。此强制覆盖优先于 `contextManagement` 和 `modelResponsesApiCompactThresholds` 配置。\n- **modelResponsesApiCompactThresholds：** 按模型覆盖 Responses API 的 `compact_threshold`，仅在代理自动附加 `context_management` 时使用。它的优先级高于 `resolveResponsesCompactThreshold` 基于 `max_prompt_tokens * ratio` 的兜底阈值。默认将 `gpt-5.4` 和 `gpt-5.5` 设为 `217600`（`272000 * 0.8`），将 `gpt-5.6-sol`、`gpt-5.6-terra`、`gpt-5.6-luna` 设为 `231200`（`272000 * 0.85`）。未列出的模型继续使用原有兜底逻辑。\n- **modelReasoningEfforts：** `/v1/messages` 请求的模型级默认推理强度。仅当请求没有传入 `output_config.effort` 时，该配置才会生效。\n  - **优先级：** 请求中的 `output_config.effort` > `modelReasoningEfforts[model]` > 内置默认值（GPT-5.3+ 模型为 `xhigh`，其他模型为 `high`）。\n  - **转发字段：** 走 Copilot 原生 Messages API 时，最终值写入 `output_config.effort`；转换为 Responses API 时，最终值写入 `reasoning.effort`。\n  - **配置可选值：** `none`、`minimal`、`low`、`medium`、`high`、`xhigh`、`max`。\n- **useMessagesApi：** 当为 `true` 时，支持 Copilot 原生 `/v1/messages` 的 Claude 系模型会走 Messages API；否则回退到 `/chat/completions`。设为 `false` 可禁用 Messages API 路由，始终使用 `/chat/completions`。默认值为 `true`。\n- **useResponsesApiWebSocket：** 当为 `true` 时，Responses API 请求会优先对声明了 `ws:/responses` 的模型使用 Copilot websocket transport；仅声明 `/responses` 的模型仍走 HTTP。设为 `false` 可禁用 websocket 路由，并在模型支持 `/responses` 时使用 HTTP `/responses`。默认值为 `true`。如果遇到 Responses API WebSocket closed，一般是自己的网络问题。如果使用了 VPN，建议切换节点。\n- **useResponsesApiWebSearch：** 当为 `true` 时，服务端会保留 Responses API 中 `type: \"web_search\"` 的工具并透传到上游。设为 `false` 则会从 `/responses` payload 中移除这些工具。默认值为 `true`。\n- **messageApiWebSearchModel：** 顶层 Copilot `/v1/messages` 请求只包含服务端 `web_search` 工具时使用的全局模型，默认值为 `gpt-5-mini`。如果该值是 `provider/model` 别名，请求会进入对应 provider 的 Messages API 路径，并在转发前移除 provider 前缀。对于 Copilot GPT 模型，web search 会通过 `/responses` 执行。混合 `web_search` 与自定义工具的场景暂不支持，服务端会移除 server-side `web_search`。\n- **claudeTokenMultiplier：** 用于 Claude `/v1/messages/count_tokens` 请求在本地走 GPT tokenizer 估算时的乘数。默认值为 `1.15`。如果你的客户端仍然过晚触发上下文压缩，可以适当调大。这个配置只会在代理本地估算 Claude token 时生效；如果已经配置 `anthropicApiKey` 且 Anthropic token counting 调用成功，则会直接返回 Anthropic 的精确计数，不会使用这个乘数。\n- **anthropicApiKey：** 用于把 Claude `/v1/messages/count_tokens` 请求转发到 Anthropic 真实 token counting 端点的 API key，这样会返回精确计数，而不是 GPT tokenizer 估算值。也可通过环境变量 `ANTHROPIC_API_KEY` 设置。若未配置，或上游调用失败，则回退到由 `claudeTokenMultiplier` 控制的本地 GPT tokenizer 估算。\n\n编辑此文件后即可自定义 prompts，或替换为你自己的快速模型。修改完成后请重启服务（或重新执行命令），让缓存中的配置刷新生效。\n\n## API 认证\n\n- **受保护的普通路由：** 当配置了 `auth.apiKeys` 且非空时，除 `/`、`/usage-viewer` 和 `/usage-viewer/` 以外的普通路由都需要认证。\n- **Admin 路由：** 所有 `/admin/*` 路由都要求 `auth.adminApiKey`。如果缺失，服务会在启动时自动生成并在开始提供服务前写回 `config.json`。\n- **允许的认证头：**\n  - `x-api-key: <your_key>`\n  - `Authorization: Bearer <your_key>`\n- **CORS 预检：** `OPTIONS` 请求始终允许。\n- **未配置普通 key 时：** 普通路由仍可直接访问；但这条规则不适用于 `/admin/*`，后者只接受 `auth.adminApiKey`。\n\n普通受保护路由的示例请求：\n\n```sh\ncurl http://localhost:4141/v1/models \\\n  -H \"x-api-key: your_api_key\"\n```\n\nAdmin 路由的示例请求：\n\n```sh\ncurl http://localhost:4141/admin/config/model-mappings \\\n  -H \"x-api-key: your_admin_api_key\"\n```\n\n## API 端点\n\n服务端提供多个 OpenAI / Anthropic 兼容端点。请求会根据所选模型和 `provider/model` 别名路由到 GitHub Copilot、内置 `codex` provider 或已配置的 provider。\n\n### OpenAI 兼容端点\n\n这些端点模拟 OpenAI API 结构。\n\n| 端点 | 方法 | 说明 |\n| --- | --- | --- |\n| `POST /v1/responses` | `POST` | OpenAI 中用于生成模型响应的高级接口。支持 `openai-responses` provider 的 `provider/model` 别名。 |\n| `POST /v1/chat/completions` | `POST` | 为给定聊天对话创建模型响应。支持 `openai-compatible` provider 的 `provider/model` 别名；目标 provider 已配置时可在没有 Copilot 的情况下使用。 |\n| `GET /v1/models` | `GET` | 列出 Copilot 模型以及已启用 provider 的 `provider/model-id` 模型。来自 Codex 客户端（`User-Agent` 以 `codex` 开头）的请求会转发到 Codex Models 上游。 |\n| `POST /v1/embeddings` | `POST` | 创建表示输入文本的向量嵌入。 |\n\n### Codex 后端代理端点\n\n这些端点要求已有可用的 Codex 登录态。每个端点同时提供无版本前缀和 `/v1` 两种路径。\n\n| 端点 | 方法 | 说明 |\n| --- | --- | --- |\n| `POST /alpha/search`<br>`POST /v1/alpha/search` | `POST` | 将 JSON 请求体和查询参数透明转发到 Codex Alpha Search 上游。 |\n| `POST /images/generations`<br>`POST /v1/images/generations` | `POST` | 将 JSON 图片生成请求转发到 Codex Images 上游。请求未携带 `Content-Type` 时，网关默认补充 `application/json`。 |\n| `POST /images/edits`<br>`POST /v1/images/edits` | `POST` | 将图片编辑请求转发到 Codex Images 上游。请使用 `multipart/form-data`，并让 HTTP 客户端自动生成 `boundary`；网关会保留传入的 content type，并以流式方式转发上传请求体。 |\n\n对于以上所有端点，网关都会使用当前 Codex 登录态覆盖客户端的 authorization 和 account header，保留查询参数及兼容的请求头，并返回上游状态码、响应头和响应体。\n\n### Anthropic 兼容端点\n\n这些端点设计为兼容 Anthropic Messages API。provider 级的 models、Responses、alpha-search 和 images 路由同时支持无版本前缀与 `/v1` 两种路径；Messages 路由仍使用 `/v1`。\n\n| 端点 | 方法 | 说明 |\n| --- | --- | --- |\n| `POST /v1/messages` | `POST` | 为给定对话创建模型响应。支持已配置 provider 的 `provider/model` 别名，包括通过 `openai-compatible` provider 做翻译。 |\n| `POST /v1/messages/count_tokens` | `POST` | 计算一组消息的 token 数。支持已配置 provider 的 `provider/model` 别名。 |\n| `POST /:provider/v1/messages` | `POST` | 将 Anthropic Messages 请求代理到已配置的 Anthropic provider，或翻译到 OpenAI 兼容 / OpenAI Responses provider。 |\n| `GET /:provider/models`<br>`GET /:provider/v1/models` | `GET` | 将模型列表请求代理到已配置的 provider。对 `codex` 默认返回内置模型目录；Codex 客户端（`User-Agent` 以 `codex` 开头）会转发到 Codex Models 上游。 |\n| `POST /:provider/v1/messages/count_tokens` | `POST` | 为 provider 路由请求在本地计算 token 数。 |\n| `POST /:provider/responses`<br>`POST /:provider/v1/responses` | `POST` | 将 OpenAI Responses 请求代理到已配置的 `openai-responses` provider（含 `codex`）。 |\n| `POST /:provider/alpha/search`<br>`POST /:provider/v1/alpha/search` | `POST` | 代理 alpha-search 请求。对 `codex` 转发到 Codex Alpha Search 上游；其他 provider 转发到 `{baseUrl}/v1/alpha/search`。 |\n| `POST /:provider/images/generations`<br>`POST /:provider/v1/images/generations` | `POST` | 代理图片生成。对 `codex` 使用 Codex Images 上游；其他 provider 转发到 `{baseUrl}/v1/images/generations`（15 分钟超时）。 |\n| `POST /:provider/images/edits`<br>`POST /:provider/v1/images/edits` | `POST` | 代理图片编辑。对 `codex` 使用 Codex Images 上游；其他 provider 以 multipart/流式方式转发到 `{baseUrl}/v1/images/edits`（15 分钟超时）。 |\n\n### 使用量监控端点\n\n用于监控 Copilot 用量与额度的新端点。\n\n| 端点 | 方法 | 说明 |\n| --- | --- | --- |\n| `GET /usage` | `GET` | 获取详细的 Copilot 使用统计与额度信息。 |\n| `GET /token` | `GET` | 获取当前 API 正在使用的 Copilot token。 |\n\n### Admin / 配置端点\n\n这些端点用于本地管理操作，只接受 `auth.adminApiKey`。\n\n| 端点 | 方法 | 说明 |\n| --- | --- | --- |\n| `GET /admin/config/model-mappings` | `GET` | 返回当前 `config.json` 路径以及生效中的 `modelMappings` 映射。 |\n| `POST /admin/config/model-mappings` | `POST` | 只更新 `config.json` 里的 `modelMappings` 字段，并回传更新后的结果。 |\n\n## 使用示例\n\n常用 `npx` 命令：\n\n```sh\n# 基础启动\nnpx @jeffreycao/copilot-api@latest start\n\n# 自定义端口并开启详细日志\nnpx @jeffreycao/copilot-api@latest start --port 8080 --verbose\n\n# 执行认证流程\nnpx @jeffreycao/copilot-api@latest auth login\n\n# 配置第三方 provider，然后不依赖 GitHub Copilot 启动\nnpx @jeffreycao/copilot-api@latest auth login --provider dashscope\nnpx @jeffreycao/copilot-api@latest start\n\n# 以 JSON 格式输出调试信息\nnpx @jeffreycao/copilot-api@latest debug --json\n\n# 用 Bun 而不是 Node.js 运行已发布 CLI\nbunx --bun @jeffreycao/copilot-api@latest start\n```\n\n配置 `dashscope` 后的 OpenAI 兼容 provider 调用示例：\n\n```sh\ncurl http://localhost:4141/v1/chat/completions \\\n  -H \"content-type: application/json\" \\\n  -d '{\"model\":\"dashscope/qwen3.6-plus\",\"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]}'\n\ncurl http://localhost:4141/dashscope/v1/messages \\\n  -H \"content-type: application/json\" \\\n  -d '{\"model\":\"qwen3.6-plus\",\"max_tokens\":1024,\"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]}'\n```\n\n## 使用建议\n\n<a id=\"claudemd-or-agentsmd-recommended-content\"></a>\n\n### CLAUDE.md 或 AGENTS.md 推荐内容\n\n如果你想手动加入这些提醒，请在 Claude Code 的 `CLAUDE.md`，或 opencode/codex 的 `AGENTS.md` 中加入以下内容：\n\n```\n- Prohibited from directly asking questions to users, MUST use question tool.\n- Once you can confirm that the task is complete, MUST use question tool to make user confirm. The user may respond with feedback if they are not satisfied with the result, which you can use to make improvements and try again, after try again, MUST use question tool to make user confirm again.\n```\n"}, "bc113f6a4c5909c996bb791d388dff51831459b3": {"t": 1785765538.5270956, "n": 34026, "h": "03884d8a38660bfc", "c": "# Copilot API Proxy\n\n[English](./README.md) | 简体中文\n\n## 重要说明\n\n> [!IMPORTANT]\n> **使用前请先注意以下几点：**\n>\n> 1. **Claude Code 配置：** 与 Claude Code 搭配使用时，请将模型 ID 配置为 `claude-opus-4-8`。示例 claude `settings.json` 见 [通过 `settings.json` 手动配置](#manual-configuration-with-settingsjson)。\n>\n> 2. **内置 `copilot`、`codex` 与第三方 provider：** 执行 `npx @jeffreycao/copilot-api@latest auth`，可选择 `copilot`、`codex`、`deepseek`、`custom` 等 provider。\n>\n> 3. **注意事项：** README 顶部移除的 GitHub Copilot warning 见 [GitHub Copilot 安全提示](./NOTICE.md#github-copilot-security-notice)。\n\n---\n\n## 项目概览\n\n这是一个小型 AI gateway，可以使用 GitHub Copilot、内置 `codex` provider，也可以使用 DashScope 等已配置的第三方 provider。GitHub Copilot 现在是可选能力：如果本地没有 GitHub token，只要至少配置了一个启用中的 provider，服务仍可按 provider-only 模式启动。\n\nAI gateway 会从同一个本地端点暴露 OpenAI / Anthropic 兼容 API，让 [Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview)、OpenCode、Codex 和 OpenAI 兼容客户端可以共用同一个本地服务。\n\n在 GitHub Copilot 路径上，AI gateway 会在可用时优先使用 Copilot 原生的 Anthropic 风格 Messages API，在重工具调用场景下保留更原生的 Claude 行为。\n\n## 功能特性\n\n- **OpenAI 与 Anthropic 双兼容**：通过 `/v1/responses`、`/v1/chat/completions`、`/v1/models`、`/v1/embeddings` 和 `/v1/messages` 对外暴露同一个本地 AI gateway。\n- **Copilot 可选**：有 GitHub 凭据时可以使用 GitHub Copilot，没有 GitHub 凭据时也可以只依赖已配置的 provider 运行。\n- **同一网关接入 Copilot、`codex` 与第三方 provider**：可统一路由 GitHub Copilot、内置 `codex` provider 和配置好的外部 provider。\n- **第三方 provider 可独立启动**：配置 DashScope、DeepSeek、OpenRouter 或自定义 provider 后，不需要 GitHub Copilot 登录即可启动 AI gateway。\n- **OpenAI 兼容 provider 同时支持 chat 和 Messages API**：`openai-compatible` provider 可通过顶层 `/v1/chat/completions` 搭配 `model: \"provider/model\"` 提供 Chat Completions，也可通过 `/v1/messages` 完成 Anthropic Messages 的请求/响应翻译。\n- **面向 Claude 的更原生 Copilot 路由**：优先使用原生 `/v1/messages`，保留 Claude 风格工具流，支持 Anthropic beta 能力、通过 Responses-capable 模型支持 Claude WebSearch，并保留 subagent / session 标记。\n- **Claude Code 与 OpenCode 集成**：兼容 Claude Code 与 OpenCode，也支持通过 `@ai-sdk/anthropic` 直接作为 Anthropic provider 使用。\n- **灵活的认证与部署选项**：支持交互式登录、直接 token、个人 / Business / Enterprise、GitHub Enterprise、opencode OAuth 和自定义数据目录。\n- **多 provider 路由**：可暴露 `/:provider/...` 路由，也可在顶层 API 上使用 `model: \"provider/model\"`。\n\n## 前置要求\n\n- Bun（>= 1.2.x）\n- 如果要通过 `npx` 运行已发布 CLI，需要 Node.js\n- 只有在使用 GitHub Copilot provider 时，才需要已订阅 Copilot 的 GitHub 账号\n- 如果不使用 GitHub Copilot，需要至少一个已配置 provider 的 API key 或 OAuth 登录\n\n## 安装\n\n安装依赖：\n\n```sh\nbun install\n```\n\n直接从源码启动服务：\n\n```sh\nbun run start start\n```\n\n## 从源码运行\n\n本项目可以通过多种方式从源码运行：\n\n### 开发模式\n\n```sh\nbun run dev start\n```\n\n### 生产模式\n\n```sh\nbun run start start\n```\n\n## 通过 npx 使用\n\n你可以直接用 npx 运行本项目：\n\n> [!IMPORTANT]\n> 通过 `npx` 运行时，token usage 存储会使用 Node 内置的 `node:sqlite` 模块。该能力会在 Node.js >= 22.13.0 时启用；Node.js < 22.13.0 时 CLI 仍可启动，但会禁用 token usage 存储。\n>\n> 如果不升级 Node.js 但仍需要 token usage 存储，可以改用 Bun 运行已发布 CLI：`bunx --bun @jeffreycao/copilot-api@latest start`。\n\n```sh\nnpx @jeffreycao/copilot-api@latest start\n```\n\n带参数示例：\n\n```sh\nnpx @jeffreycao/copilot-api@latest start --port 8080\n```\n\n如果只想做认证或 provider 配置：\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth\n```\n\n如果要不依赖 GitHub Copilot 运行，先配置至少一个 provider，然后正常启动服务：\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth login --provider dashscope\nnpx @jeffreycao/copilot-api@latest start\n```\n\n## 配合 Docker 使用\n\n构建镜像：\n\n```sh\ndocker build -t copilot-api .\n```\n\n通过 bind mount 运行容器，让认证数据在重启后保留：\n\n```sh\nmkdir -p ./copilot-data\ndocker run -p 4141:4141 -v $(pwd)/copilot-data:/root/.local/share/copilot-api copilot-api\n```\n\n这会把宿主机上的 `./copilot-data` 映射到容器内的 `/root/.local/share/copilot-api`，用于持久化 GitHub 认证数据、provider 配置和其他 gateway 状态。\n\n也可以直接通过环境变量传入 GitHub token：\n\n```sh\ndocker run -p 4141:4141 -e GH_TOKEN=your_github_token_here copilot-api\n```\n\n## Electron 桌面应用\n\n如果你更喜欢图形界面，仓库里还提供了位于 `desktop/` 的 Electron 桌面应用。它支持 GitHub Copilot 登录、OpenAI Codex OAuth，以及 DeepSeek、DashScope、OpenRouter 或自定义 provider 的 API Key 配置。授权或配置 provider 后，可以一键启动或停止本地代理，并在界面里直接查看本地端点、鉴权 Header、可用模型、额度和日志。\n\n设置页还可以配置 `OAuth App`、`API Home`、`Enterprise URL`、详细日志以及最小化到托盘。Windows x64（`.exe`）、macOS Apple Silicon（`.dmg`）和 Linux x64（`.AppImage`）安装包发布在 GitHub Releases：\n\nhttps://github.com/caozhiyuan/copilot-api/releases\n\nLinux 用户需要先为下载的 AppImage 添加执行权限：\n\n```sh\nchmod +x Copilot-API-*-linux-x86_64.AppImage\n./Copilot-API-*-linux-x86_64.AppImage\n```\n\n下载对应平台的安装包后，在应用内授权或配置 provider，选择端口并启动服务，再把你的客户端指向应用里显示的本地端点即可。发布版桌面应用使用随包内置的 Electron 运行时，正常使用不需要额外安装 Node.js；token usage 历史记录会在该内置运行时支持 SQLite 时启用。\n\n桌面应用里的高级配置页会通过 `GET/POST /admin/config/model-mappings` 读写这份共享的模型映射。同一份映射会统一作用于 `POST /v1/messages`、`POST /v1/messages/count_tokens`、`POST /v1/responses` 和 `POST /v1/chat/completions`，不再按接口区分。它使用的是 `auth.adminApiKey`，不是普通的 `auth.apiKeys`；应用会在服务启动并自动生成该 key 后，直接从 `config.json` 读取它来发起请求。\n\n### 桌面应用截图\n\n下面展示了桌面应用中的首页、Token 用量统计页面：\n\n<p align=\"center\">\n  <img src=\"./docs/screenshots/desktop-dashboard.png\" alt=\"Copilot API 桌面应用首页\" width=\"49%\" />\n  <img src=\"./docs/screenshots/desktop-token-usage.png\" alt=\"Copilot API 桌面应用 Token 用量页\" width=\"49%\" />\n</p>\n\n## 与 Claude Code 一起使用\n\n这个 AI gateway 可以为 [Claude Code](https://docs.anthropic.com/en/claude-code) 提供后端能力。Claude Code 是 Anthropic 提供的实验性面向开发者的对话式 AI 助手。\n\n有两种方式可以把 Claude Code 配置为使用这个 AI gateway：\n\n### 通过 `--claude-code` 标志进行交互式配置\n\n执行带 `--claude-code` 的 `start` 命令开始：\n\n```sh\nnpx @jeffreycao/copilot-api@latest start --claude-code\n```\n\n你不再需要手动选择模型。Gateway 会自动检测每个 Claude Code 尺寸档位对应的最新可用模型——opus 映射到最新的 Opus 模型，sonnet 映射到最新的 Sonnet 模型，haiku 映射到最新的 Haiku 模型——并生成相应设置 `ANTHROPIC_DEFAULT_OPUS_MODEL`、`ANTHROPIC_DEFAULT_SONNET_MODEL` 和 `ANTHROPIC_DEFAULT_HAIKU_MODEL` 的命令。若某个档位没有匹配的可用模型，则会被省略。该命令会被复制到剪贴板，并设置 Claude Code 使用这个 AI gateway 所需的环境变量。\n\n在新的终端中粘贴并执行这条命令，即可启动 Claude Code。\n\n<a id=\"manual-configuration-with-settingsjson\"></a>\n\n### 通过 `settings.json` 手动配置\n\n另一种方式是在项目根目录中创建 `.claude/settings.json` 文件，并写入 Claude Code 所需的环境变量。这样你就不需要每次都运行交互式配置了。\n\n下面是一个 `.claude/settings.json` 示例：\n\n```json\n{\n  \"env\": {\n    \"ANTHROPIC_BASE_URL\": \"http://localhost:4141\",\n    \"ANTHROPIC_AUTH_TOKEN\": \"dummy\",\n    \"ANTHROPIC_MODEL\": \"gpt-5.6-sol[1m]\",\n    \"ANTHROPIC_DEFAULT_SONNET_MODEL\": \"gpt-5.6-sol[1m]\",\n    \"ANTHROPIC_DEFAULT_HAIKU_MODEL\": \"gpt-5.6-luna[1m]\",\n    \"CLAUDE_CODE_AUTO_COMPACT_WINDOW\": \"272000\",\n    \"CLAUDE_CODE_USE_VERTEX\": \"0\",\n    \"CLAUDE_CODE_USE_BEDROCK\": \"0\",\n    \"DISABLE_NON_ESSENTIAL_MODEL_CALLS\": \"1\",\n    \"CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC\": \"1\",\n    \"CLAUDE_CODE_ATTRIBUTION_HEADER\": \"0\",\n    \"CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION\": \"false\",\n    \"CLAUDE_CODE_DISABLE_TERMINAL_TITLE\": \"true\",\n    \"CLAUDE_CODE_ENABLE_AWAY_SUMMARY\": \"0\"\n  },\n  \"alwaysThinkingEnabled\": true,\n  \"effortLevel\": \"xhigh\",\n  \"showThinkingSummaries\": true\n}\n```\n\n- 请根据需要替换 `ANTHROPIC_MODEL`、`ANTHROPIC_DEFAULT_OPUS_MODEL`、`ANTHROPIC_DEFAULT_SONNET_MODEL` 和 `ANTHROPIC_DEFAULT_HAIKU_MODEL`。配置完成后，请安装 claude code 插件，见 [插件集成](#plugin-integrations)。\n- 如果你使用的是 codex provider，建议**不要**将模型名配置成 `codex/xxx` 格式（如 `codex/gpt-5.6-sol`）。Claude Code 会针对 `codex/` 前缀做降智行为——例如每次请求时移除所有之前返回的思考块（thinking blocks）。请使用纯模型名（如 `gpt-5.6-sol`），并在 `config.json` 中配置 `modelMappings` 将其映射回 codex provider：\n  ```json\n  \"modelMappings\": {\n    \"gpt-5.6-sol\": \"codex/gpt-5.6-sol\",\n    \"gpt-5.6-terra\": \"codex/gpt-5.6-terra\",\n    \"gpt-5.6-luna\": \"codex/gpt-5.6-luna\"\n  },\n  ```\n- 将 `CLAUDE_CODE_ATTRIBUTION_HEADER` 设为 `0` 可以阻止 Claude Code 在 system prompt 中附加计费和版本信息，从而避免 prompt cache 失效。\n- 关闭 `CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION` 和 `CLAUDE_CODE_ENABLE_AWAY_SUMMARY` 可以避免不必要地消耗额度。\n- Claude Code WebSearch 已支持纯搜索请求。Copilot 路径请保持全局 `messageApiWebSearchModel` 指向 Responses-capable GPT 模型或 `provider/model` 别名；provider 路由请使用原生 Anthropic provider 或 `openai-responses` provider。只有在你明确想禁止这类流量时，才需要把 `WebSearch` 加到 `permissions.deny`。\n- 如果使用的不是 Claude 模型，请不要启用 `ENABLE_TOOL_SEARCH`。如果使用的是 Claude 模型，则可以启用 `ENABLE_TOOL_SEARCH`。当前 Claude Code 使用的是客户端 tool search 模式，在该模式下每次加载 defer tools 都需要额外请求一次。\n- `CLAUDE_CODE_AUTO_COMPACT_WINDOW`：设置用于自动压缩计算的上下文容量（以 token 为单位）。默认使用模型自身的上下文窗口：标准模型为 200K，扩展上下文模型为 1M。使用 1M 上下文模型（如 `claude-opus-4-6[1m]`）时，可设置一个较低的值（如 `500000`）将窗口视为 500K 用于压缩计算。该值受限于模型的实际上下文窗口上限。`CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` 会基于此值的百分比生效。设置此变量可将压缩阈值与状态栏的 `used_percentage` 解耦（后者始终使用模型的完整上下文窗口）。\n\n更多选项见：[Claude Code settings](https://docs.anthropic.com/en/docs/claude-code/settings#environment-variables)\n\n也可以参考 IDE 集成说明：[Add Claude Code to your IDE](https://docs.anthropic.com/en/docs/claude-code/ide-integrations)\n\n## 与 OpenCode 一起使用\n\nOpenCode 已经有直接的 GitHub Copilot provider。本节适用于你希望让 OpenCode 通过 `@ai-sdk/anthropic` 指向这个 AI gateway，并复用本 README 前面提到的 agent 行为时。\n\n### 最小配置\n\n使用 OpenCode OAuth app 启动 AI gateway：\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth --oauth-app=opencode\nnpx @jeffreycao/copilot-api@latest start\n```\n\n然后让 OpenCode 通过 `@ai-sdk/anthropic` 指向这个 AI gateway。\n\n示例 `~/.config/opencode/opencode.json`：\n\n```json\n{\n  \"$schema\": \"https://opencode.ai/config.json\",\n  \"provider\": {\n    \"local\": {\n      \"npm\": \"@ai-sdk/anthropic\",\n      \"name\": \"My Local\",\n      \"options\": {\n        \"baseURL\": \"http://localhost:4141/v1\",\n        \"apiKey\": \"dummy\"\n      },\n      \"models\": {\n        \"gpt-5.4\": {\n          \"name\": \"gpt-5.4\",\n          \"modalities\": {\n            \"input\": [\"text\", \"image\"],\n            \"output\": [\"text\"]\n          },\n          \"limit\": {\n            \"context\": 400000,\n            \"input\": 272000,\n            \"output\": 128000\n          }\n        },\n        \"claude-sonnet-4.6\": {\n          \"id\": \"claude-sonnet-4.6\",\n          \"name\": \"claude-sonnet-4.6\",\n          \"modalities\": {\n            \"input\": [\"text\", \"image\"],\n            \"output\": [\"text\"]\n          },\n          \"limit\": {\n            \"context\": 200000,\n            \"output\": 32000\n          },\n          \"options\": {\n            \"thinking\": {\n              \"type\": \"adaptive\"\n            },\n            \"effort\": \"max\"\n          }\n        }\n      }\n    }\n  }\n}\n```\n\n这些字段的重要性：\n\n- `npm: \"@ai-sdk/anthropic\"` 是关键。OpenCode 会以 Anthropic Messages 语义与这个 AI gateway 通信，而不是把一切扁平化为 OpenAI Chat Completions。\n- `options.baseURL` 应设为 `http://localhost:4141/v1`；Anthropic SDK 会自动补上 `/messages`、`/models` 和 `/messages/count_tokens`。\n- 如果你在此代理中启用了 `auth.apiKeys`，请把 `dummy` 替换为真实 key；否则任意占位值都可以。\n\n## 与 Codex 一起使用\n\n这个 AI gateway 也可以为 Codex 提供后端能力。\n\n### Codex `config.toml` 参考配置\n\n把以下 `[model_providers.copilot_api]` 段加入你的 Codex `~/.codex/config.toml`：\n\n```toml\nmodel_provider = \"copilot_api\"\nmodel_reasoning_summary = \"auto\"\nmodel_context_window = 272000\nmodel_auto_compact_token_limit = 244800\n\n[model_providers.copilot_api]\nname = \"OpenAI\"\nbase_url = \"http://localhost:4141\"\nenv_key = \"GITHUB_COPILOT_API_KEY\"\nrequires_openai_auth = true\nsupports_websockets = false\nwire_api = \"responses\"\nrequest_max_retries = 3\nstream_max_retries = 1\nstream_idle_timeout_ms = 300000\n\n[features]\nremote_compaction_v2 = true\n\n[analytics]\nenabled = false\n```\n\n> [!NOTE]\n> 此配置仅限于 Codex 与 GitHub Copilot provider。`name` 一定要配置为 `\"OpenAI\"`。它可以缓解 Codex local compact 不命中缓存的问题。\n> 如果使用 codex provider，建议将 `base_url` 配置为 `\"http://localhost:4141/codex\"`。\n\n## GPT Tool Search\n\n对于 `gpt-5.4+` 这类 GPT Responses 模型，这个 AI gateway 可以通过一个很小的 MCP bridge 暴露 Responses `tool_search`。Claude Code 和 opencode 都可以使用同一个 bridge，前提是客户端会加载 MCP server，并且 Anthropic Messages 流量会经过这个 AI gateway。\n\nGPT 模型不要设置 Claude Code 原生的 `ENABLE_TOOL_SEARCH`。这个开关启用的是 Claude Code 自己的客户端 tool search 模式，可能导致 deferred 工具定义不再转发给 AI gateway。这个 AI gateway 需要完整的工具定义，这样才能只保留那一小组常驻加载工具，其余工具统一转换为 Responses deferred namespace。\n\n如果你安装了 `tool-search@copilot-api-marketplace`，Claude Code 会自动带上这个 MCP bridge，可以跳过下面这段 Claude Code MCP 手动配置。\n\n请把 tool search bridge 加到 Claude Code 使用的 MCP 配置中：\n\n```json\n{\n  \"mcpServers\": {\n    \"tool_search\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@jeffreycao/copilot-api@latest\", \"mcp\"]\n    }\n  }\n}\n```\n\n请把 tool search bridge 加到 opencode 使用的 MCP 配置中：\n\n```json\n{\n  \"mcp\": {\n    \"tool_search\": {\n      \"type\": \"local\",\n      \"command\": [\"npx\", \"-y\", \"@jeffreycao/copilot-api@latest\", \"mcp\"]\n    }\n  }\n}\n```\n\n本地开发时可以将命令换成 `bun`，参数换成 `[\"run\", \"./src/main.ts\", \"mcp\"]`。\n\nAI gateway 内部现在会把 OpenAI Responses `tool_search` 配置成 client-executed 模式。deferred tools 仍然会作为可搜索 namespace 暴露给模型，但会明确要求模型直接返回下一步要加载的精确工具名列表。\n\n该 bridge 使用直接工具选择，不做 query 搜索。工具入参是 `names`，值为逗号分隔的精确 deferred 工具名，例如 `TaskList,TaskGet,mcp__fetch__fetch`。\n\n<a id=\"plugin-integrations\"></a>\n\n## 插件集成\n\n本项目为 Claude Code 和 opencode 提供了插件集成。\n\n#### Claude Code 插件集成（基于 marketplace）\n\nClaude Code 集成现在拆分为两个插件：\n\n- `agent-inject` 会在 `SubagentStart` 时注入 `__SUBAGENT_MARKER__...`，以便 AI gateway 推导 `x-initiator: agent`。\n- `tool-search` 会注册用于 GPT Responses deferred tool loading 的 `tool_search` MCP bridge。\n\n- 本仓库中的 marketplace catalog：`.claude-plugin/marketplace.json`\n- 本仓库中的插件源码：`plugin/claude/agent-inject`、`plugin/claude/tool-search`\n\n远程添加 marketplace：\n\n```sh\n/plugin marketplace add https://github.com/caozhiyuan/copilot-api.git\n```\n\n从 marketplace 安装插件：\n\n```sh\n/plugin install agent-inject@copilot-api-marketplace\n/plugin install tool-search@copilot-api-marketplace\n```\n\n安装后，`agent-inject` 会在 `SubagentStart` 时注入 `__SUBAGENT_MARKER__...`，AI gateway 会利用它推导 `x-initiator: agent`。\n\n`agent-inject` 还会注册一个 `UserPromptSubmit` hook，并返回 `{\"continue\": true}`；同时它也可以通过环境变量注入 `SessionStart` reminder 规则：\n\n- `CLAUDE_PLUGIN_ENABLE_QUESTION_RULES=1` 会自动为 Claude Code 启用两条关于使用 `question` 工具的提醒。你也可以把同样的提醒手动写进 `CLAUDE.md`；见 [CLAUDE.md 或 AGENTS.md 推荐内容](#claudemd-or-agentsmd-recommended-content)。\n- `CLAUDE_PLUGIN_ENABLE_NO_BACKGROUND_AGENTS_RULE=1` 会启用关于避免在 agent hooks 中使用 `run_in_background: true` 的提醒。\n\n`tool-search` 插件内置了 [GPT Tool Search](#gpt-tool-search) 一节描述的同一个 MCP bridge，因此安装该插件后，Claude Code 用户无需再手动配置 `tool_search` server。\n\n#### Opencode 插件\n\nsubagent 标记生成器被打包为一个 opencode 插件，位于 `plugin/opencode/subagent-marker.js`。\n\n**安装方式：**\n\n将插件文件复制到你的 opencode 插件目录：\n\n```sh\n# 克隆或下载本仓库后复制该插件\ncp plugin/opencode/subagent-marker.js ~/.config/opencode/plugins/\n```\n\n或者手动在 `~/.config/opencode/plugins/subagent-marker.js` 创建该文件，并填入插件内容。\n\n**功能：**\n\n- 跟踪 subagent 创建的子会话\n- 自动在 subagent 聊天消息前添加 marker system reminder（`__SUBAGENT_MARKER__...`）\n- 设置 `x-session-id` 请求头以跟踪会话\n- 让这个 AI gateway 能够把来自 subagent 的请求识别为 `x-initiator: agent`\n\n该插件会挂接到 `session.created`、`session.deleted`、`chat.message` 和 `chat.headers` 事件上，以无缝提供 subagent marker 能力。\n\n## 使用量查看器\n\n服务启动后，控制台会输出一个 Copilot 使用量看板 URL。这个看板是一个用于监控 API 用量的 Web 界面。\n\n1. 启动服务。例如使用 npx：\n   ```sh\n   npx @jeffreycao/copilot-api@latest start\n   ```\n2. 服务会输出一个 usage viewer 的 URL。将它复制到浏览器中打开，形式大致如下：\n   `http://localhost:4141/usage-viewer?endpoint=http://localhost:4141/usage`\n   - 如果你在 Windows 上使用 `start.bat` 脚本，这个页面会自动打开。\n\n看板提供了更易读的 Copilot 用量视图：\n\n> token usage 历史记录需要 Bun 或 Node.js >= 22.13.0。Node.js < 22.13.0 时服务会正常运行，但 token usage 存储会被禁用。\n\n- **API Endpoint URL**：通过 URL 查询参数指定 API endpoints，默认指向本地服务。支持手动切换为其他兼容 endpoints。\n- **x-api-key 认证**：如果启用了 API Key 认证，可填入 `x-api-key` 请求头。密钥会持久化保存在浏览器本地存储中。\n- **Period 选择器**：支持 Day / Week / Month 三种时间范围，切换时 URL 参数会自动同步，方便收藏和分享。\n- **Fetch Data**：点击 \"Refresh\" 按钮加载或刷新使用数据。页面加载时也会自动拉取数据。\n- **Copilot Quotas 额度**：通过进度条展示 Chat、Completions 等不同服务的额度使用情况，悬停可查看已用/剩余详情。\n- **Token Usage 指标卡片**：汇总当前周期的 Total、Input、Output、Cache Read、Cache Write、Requests 和预估费用。\n- **趋势图（Week / Month）**：提供按模型和指标筛选的折线趋势图，点击数据点可查看单日用量明细。\n- **Model Breakdown 表格**：按模型维度列出周期内的请求数、输入/输出/缓存 token 和预计费用。\n- **Request Events 分页列表**：按时间排序的请求事件记录，支持分页浏览，含时间戳、模型、请求 ID 和 token 用量。\n- **Detailed Information**：展示 API 返回的完整 JSON 响应，便于深入分析所有可用统计数据。\n- **URL-based Configuration**：也可通过 `endpoint` 和 `period` 查询参数直接指定 API 端点与时间范围。例如：\n  `http://localhost:4141/usage-viewer?endpoint=http://your-api-server/usage&period=week`\n\n### Usage Viewer 截图\n\n<p align=\"center\">\n  <img src=\"./docs/screenshots/usage-viewer.png\" alt=\"Copilot API Usage Viewer 页面\" width=\"900\" />\n</p>\n\n## 命令结构\n\nCopilot API 现在使用子命令结构，主要命令包括：\n\n- `start`：启动 AI gateway 服务。如果已有 GitHub token，则启用 Copilot 路径；如果没有 GitHub token，但存在至少一个启用中的 provider，则按 provider-only 模式启动；如果两者都没有，会引导你配置 provider。\n- `auth`：仅执行 provider 登录或配置流程，不启动服务。可用于 GitHub Copilot 登录、Codex OAuth，或第三方 provider API key 配置。\n- `debug`：显示诊断信息，包括版本、运行时详情、文件路径以及认证状态，便于排障与支持。\n\n## 命令行选项\n\n### 全局选项\n\n以下选项可用于任意子命令。若在子命令之前传入，请使用 `--key=value` 形式：\n\n| 选项 | 说明 | 默认值 | 别名 |\n| --- | --- | --- | --- |\n| --api-home | API home 目录路径（设置 `COPILOT_API_HOME`） | 无 | 无 |\n| --oauth-app | OAuth app 标识符（设置 `COPILOT_API_OAUTH_APP`） | 无 | 无 |\n| --enterprise-url | GitHub Enterprise URL（设置 `COPILOT_API_ENTERPRISE_URL`） | 无 | 无 |\n\n### Start 命令选项\n\n以下是 `start` 命令可用的命令行选项：\n\n| 选项 | 说明 | 默认值 | 别名 |\n| --- | --- | --- | --- |\n| --port | 监听端口 | 4141 | -p |\n| --verbose | 启用详细日志 | false | -v |\n| --github-token | 直接提供 GitHub token（必须通过 `auth` 子命令生成） | 无 | -g |\n| --claude-code | 生成一个使用 Copilot API 配置启动 Claude Code 的命令 | false | -c |\n| --show-token | 在获取和刷新时显示 GitHub 与 Copilot token | false | 无 |\n| --proxy-env | 从环境变量初始化代理 | false | 无 |\n\n### Auth 命令选项\n\n| 选项 | 说明 | 默认值 | 别名 |\n| --- | --- | --- | --- |\n| --provider | 要登录或配置的 provider（`copilot`、`codex`、`opencode-go`、`deepseek`、`dashscope`、`openrouter` 或 `custom`） | 交互选择 | 无 |\n| --verbose | 启用详细日志 | false | -v |\n| --show-token | 认证时显示 GitHub token | false | 无 |\n\n只有在需要启用 GitHub Copilot provider 时，才需要执行 `copilot-api auth login --provider copilot`。使用 `codex` 或第三方 provider-only 模式不要求配置 Copilot。\n\n使用 `copilot-api auth login --provider deepseek`、`--provider dashscope`、`--provider openrouter` 或 `--provider opencode-go` 可以通过 CLI 快速新增或更新这些常用第三方 provider。DeepSeek 会提示输入掩码显示的 `apiKey`、provider `type`（默认 `anthropic`），以及默认 `https://api.deepseek.com/anthropic` 的 `baseUrl`。DashScope 会提示输入掩码显示的 `apiKey`、provider `type`（默认 `openai-compatible`）和预填默认值的 `baseUrl`。OpenRouter 只提示输入掩码显示的 `apiKey` 和预填默认值的 `baseUrl`，并固定写入 `type: \"anthropic\"`。OpenCode Go 只提示输入掩码显示的 `apiKey` 和预填默认值的 `baseUrl`，并固定写入 `type: \"openai-compatible\"`（baseUrl `https://opencode.ai/zen/go`）。配置并启用 provider 后，`copilot-api start` 可在没有 GitHub token 的情况下启动。\n\n使用 `copilot-api auth login --provider custom` 可以通过 CLI 新增或更新其他第三方 provider。命令会依次提示输入 provider name、项目支持的 type（`anthropic`、`openai-compatible` 或 `openai-responses`）、`baseUrl`、掩码显示的 `apiKey` 和 `authType`；`authType` 可保持 type 默认值，也可选择 `x-api-key` / `authorization`。\n\n### Debug 命令选项\n\n| 选项 | 说明 | 默认值 | 别名 |\n| --- | --- | --- | --- |\n| --json | 以 JSON 输出调试信息 | false | 无 |\n\n<a id=\"configuration-configjson\"></a>\n\n## 配置（config.json）\n\n- **位置：** Linux/macOS 为 `~/.local/share/copilot-api/config.json`，Windows 为 `%USERPROFILE%\\.local\\share\\copilot-api\\config.json`。\n- **默认结构：**\n  ```json\n  {\n    \"auth\": {\n      \"apiKeys\": [],\n      \"adminApiKey\": \"<startup 自动生成>\"\n    },\n    \"providers\": {},\n    \"modelMappings\": {},\n    \"extraPrompts\": {\n      \"gpt-5-mini\": \"<built-in exploration prompt>\"\n    },\n    \"smallModel\": \"gpt-5-mini\",\n    \"contextManagement\": {\n      \"messages\": true,\n      \"responses\": false\n    },\n    \"modelResponsesApiCompactThresholds\": {\n      \"gpt-5.4\": 217600,\n      \"gpt-5.5\": 217600,\n      \"gpt-5.6-sol\": 231200,\n      \"gpt-5.6-terra\": 231200,\n      \"gpt-5.6-luna\": 231200\n    },\n    \"modelReasoningEfforts\": {\n      \"gpt-5-mini\": \"low\"\n    },\n    \"useMessagesApi\": true,\n    \"useResponsesApiWebSocket\": true,\n    \"useResponsesApiWebSearch\": true,\n    \"messageApiWebSearchModel\": \"gpt-5-mini\"\n  }\n  ```\n- **auth.apiKeys：** 用于普通非 admin 路由的 API key。支持多个 key 轮换使用。请求可通过 `x-api-key: <key>` 或 `Authorization: Bearer <key>` 进行认证。若为空或省略，则普通路由的认证会被禁用。\n- **auth.adminApiKey：** 仅用于 `/admin/*` 路由的单个 admin key。若未配置，服务会在启动时自动生成一个随机 key，并回写到 `config.json`。它同样使用 `x-api-key` 或 `Authorization: Bearer` 这两种头，但普通 `auth.apiKeys` 不能访问 `/admin/*`。\n- **modelMappings：** 用于顶层 `POST /v1/messages`、`POST /v1/messages/count_tokens`、`POST /v1/responses` 和 `POST /v1/chat/completions` 请求的精确 `sourceModel -> targetModel` 重写映射，这几类接口共用同一份规则。省略该字段或保留为 `{}` 时，不会做模型重写。`source` 和 `target` 都必须是非空字符串。`target` 可以是普通模型 ID，也可以是 `provider/model` 形式的别名，例如 `dashscope/qwen3.6-plus`；重写发生在 provider alias 解析之前。这些映射不再按接口区分。`GET/POST /admin/config/model-mappings` 管理接口读写的也只有这个字段。\n- **extraPrompts：** `model -> prompt` 的映射。把 Anthropic 风格请求翻译为 Responses API 时，会将其附加到第一条 system prompt 后面。你可以借此为不同模型注入护栏或指引。缺失的默认项会自动补齐，但不会覆盖你自定义的 prompt。对于 GPT-5.3+ 模型（如 `gpt-5.3-codex`、`gpt-5.4`、`gpt-5.5`），未显式配置时会自动使用内置的 commentary prompt。内置 prompt 会启用带阶段感知的 commentary，让模型在工具调用或更深层推理前先发出简短的用户可见进度说明。\n- **providers：** 全局上游 provider 映射。每个 provider key（例如 `dashscope`）都会变成一个路由前缀（`/dashscope/v1/messages`）。支持 `type: \"anthropic\"`、`type: \"openai-compatible\"` 和 `type: \"openai-responses\"`。顶层客户端也可以在 `/v1/messages`、`/v1/messages/count_tokens`、`/v1/responses` 和 `/v1/chat/completions` 中使用 `model: \"dashscope/model-id\"`；AI gateway 会在转发上游前移除 `dashscope/` 前缀。`openai-compatible` provider 同时支持 chat 和 Messages 流程：`/v1/chat/completions` 会直连上游 `/v1/chat/completions`，而 `/v1/messages` 和 `/:provider/v1/messages` 会先翻译为上游 Chat Completions，再把响应翻译回 Anthropic Messages。`GET /v1/models` 会聚合已启用 provider 的模型，并以 `provider/model-id` 形式返回；单个 provider 的原始模型列表仍可使用 `GET /dashscope/v1/models`。\n  - `enabled`：可选，若省略则默认为 `true`。\n  - `baseUrl`：provider API 的基础 URL，不要带结尾的 endpoint。Anthropic provider 不要带 `/v1/messages`；OpenAI 兼容 provider 不要带 `/v1/chat/completions`；OpenAI Responses provider 不要带 `/v1/responses`。\n  - `apiKey`：作为上游凭据值使用；普通 provider 必须配置。\n  - `authType`：可选，控制 `apiKey` 如何发送到上游。普通 provider 支持 `x-api-key` 和 `authorization`。Anthropic provider 默认 `x-api-key`；OpenAI 兼容和 OpenAI Responses provider 默认 `authorization`。当设置为 `authorization` 时，代理会发送 `Authorization: Bearer <apiKey>`。`oauth2` 仅保留给内置 `codex` provider，并由 `auth login --provider codex` 自动写入。\n  - `pricingCurrency`：可选，provider 维度的 token 费用币种，例如 `USD` 或 `CNY`。快捷 provider 默认 DashScope、DeepSeek 为 `CNY`，Codex/OpenRouter 为 `USD`。费用按币种分别汇总，不做汇率换算。\n  - `models`：可选，按模型 ID 配置的映射。每个键为请求中的模型名，值支持：\n    - `temperature`：可选，当请求未指定时使用的默认温度。\n    - `topP`：可选，当请求未指定时使用的默认 `top_p`。\n    - `topK`：可选，当请求未指定时使用的默认 `top_k`。\n    - `extraBody`：可选，按模型合入上游请求体的动态字段；请求体显式同名字段优先。OpenAI 兼容 provider 可用它配置 `enable_thinking`、`preserve_thinking`、`reasoning_effort` 等字段。`thinking_budget` 是 OpenAI 兼容 provider 的特殊覆盖项：配置在 `extraBody` 后，会在 Anthropic `thinking.budget_tokens` 翻译之后强制写入，并覆盖请求派生出的预算值。对于 provider name 为 `dashscope` 或 `baseUrl` 包含 `aliyuncs.com` 的 provider，请求派生的 `thinking_budget`（来自 Anthropic `thinking.budget_tokens`）会转发给上游；其他 OpenAI 兼容 provider 会移除请求派生的 `thinking_budget`，但 `extraBody` 中的 `thinking_budget` 仍然生效。对于 DashScope provider，当 `preserve_thinking` 未在 `extraBody` 或请求体中显式设置时，默认为 `true`。\n    - `pricing`：可选，按模型配置 token 单价，币种使用 provider 的 `pricingCurrency`，单位为每 100 万 tokens。支持 `input`、`output`、`cachedInput`（隐式缓存读）、`explicitCachedInput`（显式缓存读）和 `cacheCreationInput`。如需按输入 token 总量分档，可用带 `maxInputTokens` 的 `tiers`。\n    - `contextCache`：可选，provider name 为 `dashscope` 或 `baseUrl` 包含 `aliyuncs.com` 时默认 `true`，其他 OpenAI 兼容 provider 默认 `false`。用于启用阿里云百炼/DashScope 的显式缓存（explicit context cache），会按其 Context Cache 格式在最多 4 个 content block 上注入 `cache_control: { \"type\": \"ephemeral\" }`。缓存断点策略与 opencode 主链路保持一致：前 2 条 system 消息 + 最后 2 条非 system 消息。标记字符串 content 时会把 `system` / `user` / `assistant` / `tool` 消息转换为 text content part 数组；已有数组 content 则标记最后一个 part。如果模型本身已经支持隐式缓存，或上游不支持该显式缓存扩展字段，可在模型配置中设为 `false`。支持相同显式缓存扩展的非 DashScope provider 可设为 `true`。同时适用于 `/v1/messages` 和 `/v1/chat/completions` 路由。\n    - `supportPdf`：可选，控制该模型是否支持 PDF/document content。默认 `false`，不支持时会把 PDF 转成提示文本；设为 `true` 时会把 PDF/document 转成 OpenAI Chat Completions 的 file part。\n    - `toolContentSupportType`：可选，配置该模型的 tool result content 支持能力，值为 `array`、`image`、`pdf` 的数组。provider 侧未配置时默认只发送 string tool content。若 `supportPdf` 为 `true` 但这里不包含 `pdf`，tool result 里的 file part 会被转成 user role 消息。Copilot 主链路不使用这个 provider 默认，仍按 array + image 且不支持 PDF 的能力处理。\n    - `type`：可选，按模型覆盖 provider 的协议类型。支持 `anthropic`、`openai-compatible` 和 `openai-responses`。设置后，provider 的 `/v1/messages` 路由会使用该模型的 type 替代 provider 级别的 type 进行请求路由、认证头解析和上游端点选择。适用于 OpenCode Go 等上游对不同模型同时支持 OpenAI 兼容和 Anthropic Messages API 的 provider。覆盖 type 时，认证头按覆盖后 type 的默认值解析（Anthropic 默认 `x-api-key`；OpenAI 兼容/Responses 默认 `authorization`）。\n\n  DashScope 模型配置示例：\n  ```json\n  {\n    \"providers\": {\n      \"dashscope\": {\n        \"type\": \"openai-compatible\",\n        \"enabled\": true,\n        \"baseUrl\": \"https://dashscope.aliyuncs.com/compatible-mode\",\n        \"apiKey\": \"sk-your-dashscope-key\",\n        \"pricingCurrency\": \"CNY\",\n        \"models\": {\n          \"qwen3.7-plus\": {\n            \"temperature\": 1,\n            \"topP\": 0.95,\n            \"topK\": 20,\n            \"extraBody\": {\n              \"preserve_thinking\": true\n            }\n          },\n          \"glm-5.1\": {\n            \"temperature\": 0.7,\n            \"topP\": 0.95,\n            \"contextCache\": true,\n            \"pricing\": {\n              \"tiers\": [\n                {\n                  \"maxInputTokens\": 32000,\n                  \"input\": 6,\n                  \"cachedInput\": 1.2,\n                  \"explicitCachedInput\": 0.6,\n                  \"cacheCreationInput\": 7.5,\n                  \"output\": 24\n                },\n                {\n                  \"maxInputTokens\": 200000,\n                  \"input\": 8,\n                  \"cachedInput\": 1.6,\n                  \"explicitCachedInput\": 0.8,\n                  \"cacheCreationInput\": 10,\n                  \"output\": 28\n                }\n              ]\n            },\n            \"extraBody\": {\n              \"preserve_thinking\": true\n            }\n          }\n        }\n      }\n    }\n  }\n  ```\n  内置 token 价格覆盖 Codex GPT 模型（USD）、DashScope `qwen3.7-max`、`qwen3.7-plus`、`glm-5.1`、`glm-5.2`（CNY），DeepSeek `deepseek-v4-flash`、`deepseek-v4-pro`、`deepseek-chat`、`deepseek-reasoner`（CNY），以及 OpenCode Go 模型（`glm-5.2`、`grok-4.5`、`deepseek-v4-flash`、`deepseek-v4-pro`、`kimi-k2.7-code`、`kimi-k3`、`mimo-v2.5`、`mimo-v2.5-pro`、`qwen3.7-plus`、`qwen3.7-max`、`minimax-m2.5`、`minimax-m3`，USD）。用户配置的 `pricing` 优先于内置价格。DashScope 若上游 usage 中出现 `cache_creation_input_tokens` 字段，cached tokens 按显式缓存读价计费；否则 `cachedInput` 作为隐式缓存读价。DeepSeek 的 `prompt_cache_hit_tokens` 会归入 cached input，`prompt_cache_miss_tokens` 会归入普通 input。\n- **smallModel：** 无工具预热消息的回退模型（例如 Claude Code 的探测请求）；默认是 `gpt-5-mini`。\n- **contextManagement：** 控制代理是否为 Responses API 附加 `context_management` 压缩指令。`messages` 作用于被翻译成 Responses API 的 Anthropic 风格 `/v1/messages` 请求，包括 `openai-responses` provider 的 Messages 路由，默认值为 `true`。`responses` 作用于 native `/v1/responses` 流量，包括 `provider/model` 别名和内置 `codex` provider，默认值为 `false`。只有在确认客户端支持 context management compaction 后，才建议在 Responses API 下启用 `responses`。启用后，请求体会带上 `context_management`，并在后续轮次中仅保留最新的压缩承载内容。**注意：** 对于 GPT-5.6 及以上模型（如 `gpt-5.6-sol`、`gpt-5.6-terra`、`gpt-5.6-luna`），context management 功能会被强制禁用，因为开启后会破坏这些模型的 prompt 缓存命中。此强制覆盖优先于 `contextManagement` 和 `modelResponsesApiCompactThresholds` 配置。\n- **modelResponsesApiCompactThresholds：** 按模型覆盖 Responses API 的 `compact_threshold`，仅在代理自动附加 `context_management` 时使用。它的优先级高于 `resolveResponsesCompactThreshold` 基于 `max_prompt_tokens * ratio` 的兜底阈值。默认将 `gpt-5.4` 和 `gpt-5.5` 设为 `217600`（`272000 * 0.8`），将 `gpt-5.6-sol`、`gpt-5.6-terra`、`gpt-5.6-luna` 设为 `231200`（`272000 * 0.85`）。未列出的模型继续使用原有兜底逻辑。\n- **modelReasoningEfforts：** `/v1/messages` 请求的模型级默认推理强度。仅当请求没有传入 `output_config.effort` 时，该配置才会生效。\n  - **优先级：** 请求中的 `output_config.effort` > `modelReasoningEfforts[model]` > 内置默认值（GPT-5.3+ 模型为 `xhigh`，其他模型为 `high`）。\n  - **转发字段：** 走 Copilot 原生 Messages API 时，最终值写入 `output_config.effort`；转换为 Responses API 时，最终值写入 `reasoning.effort`。\n  - **配置可选值：** `none`、`minimal`、`low`、`medium`、`high`、`xhigh`、`max`。\n- **useMessagesApi：** 当为 `true` 时，支持 Copilot 原生 `/v1/messages` 的 Claude 系模型会走 Messages API；否则回退到 `/chat/completions`。设为 `false` 可禁用 Messages API 路由，始终使用 `/chat/completions`。默认值为 `true`。\n- **useResponsesApiWebSocket：** 当为 `true` 时，Responses API 请求会优先对声明了 `ws:/responses` 的模型使用 Copilot websocket transport；仅声明 `/responses` 的模型仍走 HTTP。设为 `false` 可禁用 websocket 路由，并在模型支持 `/responses` 时使用 HTTP `/responses`。默认值为 `true`。如果遇到 Responses API WebSocket closed，一般是自己的网络问题。如果使用了 VPN，建议切换节点。\n- **useResponsesApiWebSearch：** 当为 `true` 时，服务端会保留 Responses API 中 `type: \"web_search\"` 的工具并透传到上游。设为 `false` 则会从 `/responses` payload 中移除这些工具。默认值为 `true`。\n- **messageApiWebSearchModel：** 顶层 Copilot `/v1/messages` 请求只包含服务端 `web_search` 工具时使用的全局模型，默认值为 `gpt-5-mini`。如果该值是 `provider/model` 别名，请求会进入对应 provider 的 Messages API 路径，并在转发前移除 provider 前缀。对于 Copilot GPT 模型，web search 会通过 `/responses` 执行。混合 `web_search` 与自定义工具的场景暂不支持，服务端会移除 server-side `web_search`。\n- **claudeTokenMultiplier：** 用于 Claude `/v1/messages/count_tokens` 请求在本地走 GPT tokenizer 估算时的乘数。默认值为 `1.15`。如果你的客户端仍然过晚触发上下文压缩，可以适当调大。这个配置只会在代理本地估算 Claude token 时生效；如果已经配置 `anthropicApiKey` 且 Anthropic token counting 调用成功，则会直接返回 Anthropic 的精确计数，不会使用这个乘数。\n- **anthropicApiKey：** 用于把 Claude `/v1/messages/count_tokens` 请求转发到 Anthropic 真实 token counting 端点的 API key，这样会返回精确计数，而不是 GPT tokenizer 估算值。也可通过环境变量 `ANTHROPIC_API_KEY` 设置。若未配置，或上游调用失败，则回退到由 `claudeTokenMultiplier` 控制的本地 GPT tokenizer 估算。\n\n编辑此文件后即可自定义 prompts，或替换为你自己的快速模型。修改完成后请重启服务（或重新执行命令），让缓存中的配置刷新生效。\n\n## API 认证\n\n- **受保护的普通路由：** 当配置了 `auth.apiKeys` 且非空时，除 `/`、`/usage-viewer` 和 `/usage-viewer/` 以外的普通路由都需要认证。\n- **Admin 路由：** 所有 `/admin/*` 路由都要求 `auth.adminApiKey`。如果缺失，服务会在启动时自动生成并在开始提供服务前写回 `config.json`。\n- **允许的认证头：**\n  - `x-api-key: <your_key>`\n  - `Authorization: Bearer <your_key>`\n- **CORS 预检：** `OPTIONS` 请求始终允许。\n- **未配置普通 key 时：** 普通路由仍可直接访问；但这条规则不适用于 `/admin/*`，后者只接受 `auth.adminApiKey`。\n\n普通受保护路由的示例请求：\n\n```sh\ncurl http://localhost:4141/v1/models \\\n  -H \"x-api-key: your_api_key\"\n```\n\nAdmin 路由的示例请求：\n\n```sh\ncurl http://localhost:4141/admin/config/model-mappings \\\n  -H \"x-api-key: your_admin_api_key\"\n```\n\n## API 端点\n\n服务端提供多个 OpenAI / Anthropic 兼容端点。请求会根据所选模型和 `provider/model` 别名路由到 GitHub Copilot、内置 `codex` provider 或已配置的 provider。\n\n### OpenAI 兼容端点\n\n这些端点模拟 OpenAI API 结构。\n\n| 端点 | 方法 | 说明 |\n| --- | --- | --- |\n| `POST /v1/responses` | `POST` | OpenAI 中用于生成模型响应的高级接口。支持 `openai-responses` provider 的 `provider/model` 别名。 |\n| `POST /v1/chat/completions` | `POST` | 为给定聊天对话创建模型响应。支持 `openai-compatible` provider 的 `provider/model` 别名；目标 provider 已配置时可在没有 Copilot 的情况下使用。 |\n| `GET /v1/models` | `GET` | 列出 Copilot 模型以及已启用 provider 的 `provider/model-id` 模型。来自 Codex 客户端（`User-Agent` 以 `codex` 开头）的请求会转发到 Codex Models 上游。 |\n| `POST /v1/embeddings` | `POST` | 创建表示输入文本的向量嵌入。 |\n\n### Codex 后端代理端点\n\n这些端点要求已有可用的 Codex 登录态。每个端点同时提供无版本前缀和 `/v1` 两种路径。\n\n| 端点 | 方法 | 说明 |\n| --- | --- | --- |\n| `POST /alpha/search`<br>`POST /v1/alpha/search` | `POST` | 将 JSON 请求体和查询参数透明转发到 Codex Alpha Search 上游。 |\n| `POST /images/generations`<br>`POST /v1/images/generations` | `POST` | 将 JSON 图片生成请求转发到 Codex Images 上游。请求未携带 `Content-Type` 时，网关默认补充 `application/json`。 |\n| `POST /images/edits`<br>`POST /v1/images/edits` | `POST` | 将图片编辑请求转发到 Codex Images 上游。请使用 `multipart/form-data`，并让 HTTP 客户端自动生成 `boundary`；网关会保留传入的 content type，并以流式方式转发上传请求体。 |\n\n对于以上所有端点，网关都会使用当前 Codex 登录态覆盖客户端的 authorization 和 account header，保留查询参数及兼容的请求头，并返回上游状态码、响应头和响应体。\n\n### Anthropic 兼容端点\n\n这些端点设计为兼容 Anthropic Messages API。provider 级的 models、Responses、alpha-search 和 images 路由同时支持无版本前缀与 `/v1` 两种路径；Messages 路由仍使用 `/v1`。\n\n| 端点 | 方法 | 说明 |\n| --- | --- | --- |\n| `POST /v1/messages` | `POST` | 为给定对话创建模型响应。支持已配置 provider 的 `provider/model` 别名，包括通过 `openai-compatible` provider 做翻译。 |\n| `POST /v1/messages/count_tokens` | `POST` | 计算一组消息的 token 数。支持已配置 provider 的 `provider/model` 别名。 |\n| `POST /:provider/v1/messages` | `POST` | 将 Anthropic Messages 请求代理到已配置的 Anthropic provider，或翻译到 OpenAI 兼容 / OpenAI Responses provider。 |\n| `GET /:provider/models`<br>`GET /:provider/v1/models` | `GET` | 将模型列表请求代理到已配置的 provider。对 `codex` 默认返回内置模型目录；Codex 客户端（`User-Agent` 以 `codex` 开头）会转发到 Codex Models 上游。 |\n| `POST /:provider/v1/messages/count_tokens` | `POST` | 为 provider 路由请求在本地计算 token 数。 |\n| `POST /:provider/responses`<br>`POST /:provider/v1/responses` | `POST` | 将 OpenAI Responses 请求代理到已配置的 `openai-responses` provider（含 `codex`）。 |\n| `POST /:provider/alpha/search`<br>`POST /:provider/v1/alpha/search` | `POST` | 代理 alpha-search 请求。对 `codex` 转发到 Codex Alpha Search 上游；其他 provider 转发到 `{baseUrl}/v1/alpha/search`。 |\n| `POST /:provider/images/generations`<br>`POST /:provider/v1/images/generations` | `POST` | 代理图片生成。对 `codex` 使用 Codex Images 上游；其他 provider 转发到 `{baseUrl}/v1/images/generations`（15 分钟超时）。 |\n| `POST /:provider/images/edits`<br>`POST /:provider/v1/images/edits` | `POST` | 代理图片编辑。对 `codex` 使用 Codex Images 上游；其他 provider 以 multipart/流式方式转发到 `{baseUrl}/v1/images/edits`（15 分钟超时）。 |\n\n### 使用量监控端点\n\n用于监控 Copilot 用量与额度的新端点。\n\n| 端点 | 方法 | 说明 |\n| --- | --- | --- |\n| `GET /usage` | `GET` | 获取详细的 Copilot 使用统计与额度信息。 |\n| `GET /token` | `GET` | 获取当前 API 正在使用的 Copilot token。 |\n\n### Admin / 配置端点\n\n这些端点用于本地管理操作，只接受 `auth.adminApiKey`。\n\n| 端点 | 方法 | 说明 |\n| --- | --- | --- |\n| `GET /admin/config/model-mappings` | `GET` | 返回当前 `config.json` 路径以及生效中的 `modelMappings` 映射。 |\n| `POST /admin/config/model-mappings` | `POST` | 只更新 `config.json` 里的 `modelMappings` 字段，并回传更新后的结果。 |\n\n## 使用示例\n\n常用 `npx` 命令：\n\n```sh\n# 基础启动\nnpx @jeffreycao/copilot-api@latest start\n\n# 自定义端口并开启详细日志\nnpx @jeffreycao/copilot-api@latest start --port 8080 --verbose\n\n# 执行认证流程\nnpx @jeffreycao/copilot-api@latest auth login\n\n# 配置第三方 provider，然后不依赖 GitHub Copilot 启动\nnpx @jeffreycao/copilot-api@latest auth login --provider dashscope\nnpx @jeffreycao/copilot-api@latest start\n\n# 以 JSON 格式输出调试信息\nnpx @jeffreycao/copilot-api@latest debug --json\n\n# 用 Bun 而不是 Node.js 运行已发布 CLI\nbunx --bun @jeffreycao/copilot-api@latest start\n```\n\n配置 `dashscope` 后的 OpenAI 兼容 provider 调用示例：\n\n```sh\ncurl http://localhost:4141/v1/chat/completions \\\n  -H \"content-type: application/json\" \\\n  -d '{\"model\":\"dashscope/qwen3.6-plus\",\"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]}'\n\ncurl http://localhost:4141/dashscope/v1/messages \\\n  -H \"content-type: application/json\" \\\n  -d '{\"model\":\"qwen3.6-plus\",\"max_tokens\":1024,\"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]}'\n```\n\n## 使用建议\n\n<a id=\"claudemd-or-agentsmd-recommended-content\"></a>\n\n### CLAUDE.md 或 AGENTS.md 推荐内容\n\n如果你想手动加入这些提醒，请在 Claude Code 的 `CLAUDE.md`，或 opencode/codex 的 `AGENTS.md` 中加入以下内容：\n\n```\n- Prohibited from directly asking questions to users, MUST use question tool.\n- Once you can confirm that the task is complete, MUST use question tool to make user confirm. The user may respond with feedback if they are not satisfied with the result, which you can use to make improvements and try again, after try again, MUST use question tool to make user confirm again.\n```\n"}, "d5b3aa096a08d14e6f5743efbd6b44c2bce6b810": {"t": 1785765541.0555742, "n": 33829, "h": "4ae23ee1208f987d", "c": "# Copilot API Proxy\n\n[English](./README.md) | 简体中文\n\n## 重要说明\n\n> [!IMPORTANT]\n> **使用前请先注意以下几点：**\n>\n> 1. **Claude Code 配置：** 与 Claude Code 搭配使用时，请将模型 ID 配置为 `claude-opus-4-8`。示例 claude `settings.json` 见 [通过 `settings.json` 手动配置](#manual-configuration-with-settingsjson)。\n>\n> 2. **内置 `copilot`、`codex` 与第三方 provider：** 执行 `npx @jeffreycao/copilot-api@latest auth`，可选择 `copilot`、`codex`、`deepseek`、`custom` 等 provider。\n>\n> 3. **注意事项：** README 顶部移除的 GitHub Copilot warning 见 [GitHub Copilot 安全提示](./NOTICE.md#github-copilot-security-notice)。\n\n---\n\n## 项目概览\n\n这是一个小型 AI gateway，可以使用 GitHub Copilot、内置 `codex` provider，也可以使用 DashScope 等已配置的第三方 provider。GitHub Copilot 现在是可选能力：如果本地没有 GitHub token，只要至少配置了一个启用中的 provider，服务仍可按 provider-only 模式启动。\n\nAI gateway 会从同一个本地端点暴露 OpenAI / Anthropic 兼容 API，让 [Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview)、OpenCode、Codex 和 OpenAI 兼容客户端可以共用同一个本地服务。\n\n在 GitHub Copilot 路径上，AI gateway 会在可用时优先使用 Copilot 原生的 Anthropic 风格 Messages API，在重工具调用场景下保留更原生的 Claude 行为。\n\n## 功能特性\n\n- **OpenAI 与 Anthropic 双兼容**：通过 `/v1/responses`、`/v1/chat/completions`、`/v1/models`、`/v1/embeddings` 和 `/v1/messages` 对外暴露同一个本地 AI gateway。\n- **Copilot 可选**：有 GitHub 凭据时可以使用 GitHub Copilot，没有 GitHub 凭据时也可以只依赖已配置的 provider 运行。\n- **同一网关接入 Copilot、`codex` 与第三方 provider**：可统一路由 GitHub Copilot、内置 `codex` provider 和配置好的外部 provider。\n- **第三方 provider 可独立启动**：配置 DashScope、DeepSeek、OpenRouter 或自定义 provider 后，不需要 GitHub Copilot 登录即可启动 AI gateway。\n- **OpenAI 兼容 provider 同时支持 chat 和 Messages API**：`openai-compatible` provider 可通过顶层 `/v1/chat/completions` 搭配 `model: \"provider/model\"` 提供 Chat Completions，也可通过 `/v1/messages` 完成 Anthropic Messages 的请求/响应翻译。\n- **面向 Claude 的更原生 Copilot 路由**：优先使用原生 `/v1/messages`，保留 Claude 风格工具流，支持 Anthropic beta 能力、通过 Responses-capable 模型支持 Claude WebSearch，并保留 subagent / session 标记。\n- **Claude Code 与 OpenCode 集成**：兼容 Claude Code 与 OpenCode，也支持通过 `@ai-sdk/anthropic` 直接作为 Anthropic provider 使用。\n- **灵活的认证与部署选项**：支持交互式登录、直接 token、个人 / Business / Enterprise、GitHub Enterprise、opencode OAuth 和自定义数据目录。\n- **多 provider 路由**：可暴露 `/:provider/...` 路由，也可在顶层 API 上使用 `model: \"provider/model\"`。\n\n## 前置要求\n\n- Bun（>= 1.2.x）\n- 如果要通过 `npx` 运行已发布 CLI，需要 Node.js\n- 只有在使用 GitHub Copilot provider 时，才需要已订阅 Copilot 的 GitHub 账号\n- 如果不使用 GitHub Copilot，需要至少一个已配置 provider 的 API key 或 OAuth 登录\n\n## 安装\n\n安装依赖：\n\n```sh\nbun install\n```\n\n直接从源码启动服务：\n\n```sh\nbun run start start\n```\n\n## 从源码运行\n\n本项目可以通过多种方式从源码运行：\n\n### 开发模式\n\n```sh\nbun run dev start\n```\n\n### 生产模式\n\n```sh\nbun run start start\n```\n\n## 通过 npx 使用\n\n你可以直接用 npx 运行本项目：\n\n> [!IMPORTANT]\n> 通过 `npx` 运行时，token usage 存储会使用 Node 内置的 `node:sqlite` 模块。该能力会在 Node.js >= 22.13.0 时启用；Node.js < 22.13.0 时 CLI 仍可启动，但会禁用 token usage 存储。\n>\n> 如果不升级 Node.js 但仍需要 token usage 存储，可以改用 Bun 运行已发布 CLI：`bunx --bun @jeffreycao/copilot-api@latest start`。\n\n```sh\nnpx @jeffreycao/copilot-api@latest start\n```\n\n带参数示例：\n\n```sh\nnpx @jeffreycao/copilot-api@latest start --port 8080\n```\n\n如果只想做认证或 provider 配置：\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth\n```\n\n如果要不依赖 GitHub Copilot 运行，先配置至少一个 provider，然后正常启动服务：\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth login --provider dashscope\nnpx @jeffreycao/copilot-api@latest start\n```\n\n## 配合 Docker 使用\n\n构建镜像：\n\n```sh\ndocker build -t copilot-api .\n```\n\n通过 bind mount 运行容器，让认证数据在重启后保留：\n\n```sh\nmkdir -p ./copilot-data\ndocker run -p 4141:4141 -v $(pwd)/copilot-data:/root/.local/share/copilot-api copilot-api\n```\n\n这会把宿主机上的 `./copilot-data` 映射到容器内的 `/root/.local/share/copilot-api`，用于持久化 GitHub 认证数据、provider 配置和其他 gateway 状态。\n\n也可以直接通过环境变量传入 GitHub token：\n\n```sh\ndocker run -p 4141:4141 -e GH_TOKEN=your_github_token_here copilot-api\n```\n\n## Electron 桌面应用\n\n如果你更喜欢图形界面，仓库里还提供了位于 `desktop/` 的 Electron 桌面应用。它支持 GitHub Copilot 登录、OpenAI Codex OAuth，以及 DeepSeek、DashScope、OpenRouter 或自定义 provider 的 API Key 配置。授权或配置 provider 后，可以一键启动或停止本地代理，并在界面里直接查看本地端点、鉴权 Header、可用模型、额度和日志。\n\n设置页还可以配置 `OAuth App`、`API Home`、`Enterprise URL`、详细日志以及最小化到托盘。桌面安装包发布在 GitHub Releases：\n\nhttps://github.com/caozhiyuan/copilot-api/releases\n\n下载对应平台的安装包后，在应用内授权或配置 provider，选择端口并启动服务，再把你的客户端指向应用里显示的本地端点即可。发布版桌面应用使用随包内置的 Electron 运行时，正常使用不需要额外安装 Node.js；token usage 历史记录会在该内置运行时支持 SQLite 时启用。\n\n桌面应用里的高级配置页会通过 `GET/POST /admin/config/model-mappings` 读写这份共享的模型映射。同一份映射会统一作用于 `POST /v1/messages`、`POST /v1/messages/count_tokens`、`POST /v1/responses` 和 `POST /v1/chat/completions`，不再按接口区分。它使用的是 `auth.adminApiKey`，不是普通的 `auth.apiKeys`；应用会在服务启动并自动生成该 key 后，直接从 `config.json` 读取它来发起请求。\n\n### 桌面应用截图\n\n下面展示了桌面应用中的首页、Token 用量统计页面：\n\n<p align=\"center\">\n  <img src=\"./docs/screenshots/desktop-dashboard.png\" alt=\"Copilot API 桌面应用首页\" width=\"49%\" />\n  <img src=\"./docs/screenshots/desktop-token-usage.png\" alt=\"Copilot API 桌面应用 Token 用量页\" width=\"49%\" />\n</p>\n\n## 与 Claude Code 一起使用\n\n这个 AI gateway 可以为 [Claude Code](https://docs.anthropic.com/en/claude-code) 提供后端能力。Claude Code 是 Anthropic 提供的实验性面向开发者的对话式 AI 助手。\n\n有两种方式可以把 Claude Code 配置为使用这个 AI gateway：\n\n### 通过 `--claude-code` 标志进行交互式配置\n\n执行带 `--claude-code` 的 `start` 命令开始：\n\n```sh\nnpx @jeffreycao/copilot-api@latest start --claude-code\n```\n\n你不再需要手动选择模型。Gateway 会自动检测每个 Claude Code 尺寸档位对应的最新可用模型——opus 映射到最新的 Opus 模型，sonnet 映射到最新的 Sonnet 模型，haiku 映射到最新的 Haiku 模型——并生成相应设置 `ANTHROPIC_DEFAULT_OPUS_MODEL`、`ANTHROPIC_DEFAULT_SONNET_MODEL` 和 `ANTHROPIC_DEFAULT_HAIKU_MODEL` 的命令。若某个档位没有匹配的可用模型，则会被省略。该命令会被复制到剪贴板，并设置 Claude Code 使用这个 AI gateway 所需的环境变量。\n\n在新的终端中粘贴并执行这条命令，即可启动 Claude Code。\n\n<a id=\"manual-configuration-with-settingsjson\"></a>\n\n### 通过 `settings.json` 手动配置\n\n另一种方式是在项目根目录中创建 `.claude/settings.json` 文件，并写入 Claude Code 所需的环境变量。这样你就不需要每次都运行交互式配置了。\n\n下面是一个 `.claude/settings.json` 示例：\n\n```json\n{\n  \"env\": {\n    \"ANTHROPIC_BASE_URL\": \"http://localhost:4141\",\n    \"ANTHROPIC_AUTH_TOKEN\": \"dummy\",\n    \"ANTHROPIC_MODEL\": \"gpt-5.6-sol[1m]\",\n    \"ANTHROPIC_DEFAULT_SONNET_MODEL\": \"gpt-5.6-sol[1m]\",\n    \"ANTHROPIC_DEFAULT_HAIKU_MODEL\": \"gpt-5.6-luna[1m]\",\n    \"CLAUDE_CODE_AUTO_COMPACT_WINDOW\": \"272000\",\n    \"CLAUDE_CODE_USE_VERTEX\": \"0\",\n    \"CLAUDE_CODE_USE_BEDROCK\": \"0\",\n    \"DISABLE_NON_ESSENTIAL_MODEL_CALLS\": \"1\",\n    \"CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC\": \"1\",\n    \"CLAUDE_CODE_ATTRIBUTION_HEADER\": \"0\",\n    \"CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION\": \"false\",\n    \"CLAUDE_CODE_DISABLE_TERMINAL_TITLE\": \"true\",\n    \"CLAUDE_CODE_ENABLE_AWAY_SUMMARY\": \"0\"\n  },\n  \"alwaysThinkingEnabled\": true,\n  \"effortLevel\": \"xhigh\",\n  \"showThinkingSummaries\": true\n}\n```\n\n- 请根据需要替换 `ANTHROPIC_MODEL`、`ANTHROPIC_DEFAULT_OPUS_MODEL`、`ANTHROPIC_DEFAULT_SONNET_MODEL` 和 `ANTHROPIC_DEFAULT_HAIKU_MODEL`。配置完成后，请安装 claude code 插件，见 [插件集成](#plugin-integrations)。\n- 如果你使用的是 codex provider，建议**不要**将模型名配置成 `codex/xxx` 格式（如 `codex/gpt-5.6-sol`）。Claude Code 会针对 `codex/` 前缀做降智行为——例如每次请求时移除所有之前返回的思考块（thinking blocks）。请使用纯模型名（如 `gpt-5.6-sol`），并在 `config.json` 中配置 `modelMappings` 将其映射回 codex provider：\n  ```json\n  \"modelMappings\": {\n    \"gpt-5.6-sol\": \"codex/gpt-5.6-sol\",\n    \"gpt-5.6-terra\": \"codex/gpt-5.6-terra\",\n    \"gpt-5.6-luna\": \"codex/gpt-5.6-luna\"\n  },\n  ```\n- 将 `CLAUDE_CODE_ATTRIBUTION_HEADER` 设为 `0` 可以阻止 Claude Code 在 system prompt 中附加计费和版本信息，从而避免 prompt cache 失效。\n- 关闭 `CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION` 和 `CLAUDE_CODE_ENABLE_AWAY_SUMMARY` 可以避免不必要地消耗额度。\n- Claude Code WebSearch 已支持纯搜索请求。Copilot 路径请保持全局 `messageApiWebSearchModel` 指向 Responses-capable GPT 模型或 `provider/model` 别名；provider 路由请使用原生 Anthropic provider 或 `openai-responses` provider。只有在你明确想禁止这类流量时，才需要把 `WebSearch` 加到 `permissions.deny`。\n- 如果使用的不是 Claude 模型，请不要启用 `ENABLE_TOOL_SEARCH`。如果使用的是 Claude 模型，则可以启用 `ENABLE_TOOL_SEARCH`。当前 Claude Code 使用的是客户端 tool search 模式，在该模式下每次加载 defer tools 都需要额外请求一次。\n- `CLAUDE_CODE_AUTO_COMPACT_WINDOW`：设置用于自动压缩计算的上下文容量（以 token 为单位）。默认使用模型自身的上下文窗口：标准模型为 200K，扩展上下文模型为 1M。使用 1M 上下文模型（如 `claude-opus-4-6[1m]`）时，可设置一个较低的值（如 `500000`）将窗口视为 500K 用于压缩计算。该值受限于模型的实际上下文窗口上限。`CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` 会基于此值的百分比生效。设置此变量可将压缩阈值与状态栏的 `used_percentage` 解耦（后者始终使用模型的完整上下文窗口）。\n\n更多选项见：[Claude Code settings](https://docs.anthropic.com/en/docs/claude-code/settings#environment-variables)\n\n也可以参考 IDE 集成说明：[Add Claude Code to your IDE](https://docs.anthropic.com/en/docs/claude-code/ide-integrations)\n\n## 与 OpenCode 一起使用\n\nOpenCode 已经有直接的 GitHub Copilot provider。本节适用于你希望让 OpenCode 通过 `@ai-sdk/anthropic` 指向这个 AI gateway，并复用本 README 前面提到的 agent 行为时。\n\n### 最小配置\n\n使用 OpenCode OAuth app 启动 AI gateway：\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth --oauth-app=opencode\nnpx @jeffreycao/copilot-api@latest start\n```\n\n然后让 OpenCode 通过 `@ai-sdk/anthropic` 指向这个 AI gateway。\n\n示例 `~/.config/opencode/opencode.json`：\n\n```json\n{\n  \"$schema\": \"https://opencode.ai/config.json\",\n  \"provider\": {\n    \"local\": {\n      \"npm\": \"@ai-sdk/anthropic\",\n      \"name\": \"My Local\",\n      \"options\": {\n        \"baseURL\": \"http://localhost:4141/v1\",\n        \"apiKey\": \"dummy\"\n      },\n      \"models\": {\n        \"gpt-5.4\": {\n          \"name\": \"gpt-5.4\",\n          \"modalities\": {\n            \"input\": [\"text\", \"image\"],\n            \"output\": [\"text\"]\n          },\n          \"limit\": {\n            \"context\": 400000,\n            \"input\": 272000,\n            \"output\": 128000\n          }\n        },\n        \"claude-sonnet-4.6\": {\n          \"id\": \"claude-sonnet-4.6\",\n          \"name\": \"claude-sonnet-4.6\",\n          \"modalities\": {\n            \"input\": [\"text\", \"image\"],\n            \"output\": [\"text\"]\n          },\n          \"limit\": {\n            \"context\": 200000,\n            \"output\": 32000\n          },\n          \"options\": {\n            \"thinking\": {\n              \"type\": \"adaptive\"\n            },\n            \"effort\": \"max\"\n          }\n        }\n      }\n    }\n  }\n}\n```\n\n这些字段的重要性：\n\n- `npm: \"@ai-sdk/anthropic\"` 是关键。OpenCode 会以 Anthropic Messages 语义与这个 AI gateway 通信，而不是把一切扁平化为 OpenAI Chat Completions。\n- `options.baseURL` 应设为 `http://localhost:4141/v1`；Anthropic SDK 会自动补上 `/messages`、`/models` 和 `/messages/count_tokens`。\n- 如果你在此代理中启用了 `auth.apiKeys`，请把 `dummy` 替换为真实 key；否则任意占位值都可以。\n\n## 与 Codex 一起使用\n\n这个 AI gateway 也可以为 Codex 提供后端能力。\n\n### Codex `config.toml` 参考配置\n\n把以下 `[model_providers.copilot_api]` 段加入你的 Codex `~/.codex/config.toml`：\n\n```toml\nmodel_provider = \"copilot_api\"\nmodel_reasoning_summary = \"auto\"\nmodel_context_window = 272000\nmodel_auto_compact_token_limit = 244800\n\n[model_providers.copilot_api]\nname = \"OpenAI\"\nbase_url = \"http://localhost:4141\"\nenv_key = \"GITHUB_COPILOT_API_KEY\"\nrequires_openai_auth = true\nsupports_websockets = false\nwire_api = \"responses\"\nrequest_max_retries = 3\nstream_max_retries = 1\nstream_idle_timeout_ms = 300000\n\n[features]\nremote_compaction_v2 = true\n\n[analytics]\nenabled = false\n```\n\n> [!NOTE]\n> 此配置仅限于 Codex 与 GitHub Copilot provider。`name` 一定要配置为 `\"OpenAI\"`。它可以缓解 Codex local compact 不命中缓存的问题。\n> 如果使用 codex provider，建议将 `base_url` 配置为 `\"http://localhost:4141/codex\"`。\n\n## GPT Tool Search\n\n对于 `gpt-5.4+` 这类 GPT Responses 模型，这个 AI gateway 可以通过一个很小的 MCP bridge 暴露 Responses `tool_search`。Claude Code 和 opencode 都可以使用同一个 bridge，前提是客户端会加载 MCP server，并且 Anthropic Messages 流量会经过这个 AI gateway。\n\nGPT 模型不要设置 Claude Code 原生的 `ENABLE_TOOL_SEARCH`。这个开关启用的是 Claude Code 自己的客户端 tool search 模式，可能导致 deferred 工具定义不再转发给 AI gateway。这个 AI gateway 需要完整的工具定义，这样才能只保留那一小组常驻加载工具，其余工具统一转换为 Responses deferred namespace。\n\n如果你安装了 `tool-search@copilot-api-marketplace`，Claude Code 会自动带上这个 MCP bridge，可以跳过下面这段 Claude Code MCP 手动配置。\n\n请把 tool search bridge 加到 Claude Code 使用的 MCP 配置中：\n\n```json\n{\n  \"mcpServers\": {\n    \"tool_search\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@jeffreycao/copilot-api@latest\", \"mcp\"]\n    }\n  }\n}\n```\n\n请把 tool search bridge 加到 opencode 使用的 MCP 配置中：\n\n```json\n{\n  \"mcp\": {\n    \"tool_search\": {\n      \"type\": \"local\",\n      \"command\": [\"npx\", \"-y\", \"@jeffreycao/copilot-api@latest\", \"mcp\"]\n    }\n  }\n}\n```\n\n本地开发时可以将命令换成 `bun`，参数换成 `[\"run\", \"./src/main.ts\", \"mcp\"]`。\n\nAI gateway 内部现在会把 OpenAI Responses `tool_search` 配置成 client-executed 模式。deferred tools 仍然会作为可搜索 namespace 暴露给模型，但会明确要求模型直接返回下一步要加载的精确工具名列表。\n\n该 bridge 使用直接工具选择，不做 query 搜索。工具入参是 `names`，值为逗号分隔的精确 deferred 工具名，例如 `TaskList,TaskGet,mcp__fetch__fetch`。\n\n<a id=\"plugin-integrations\"></a>\n\n## 插件集成\n\n本项目为 Claude Code 和 opencode 提供了插件集成。\n\n#### Claude Code 插件集成（基于 marketplace）\n\nClaude Code 集成现在拆分为两个插件：\n\n- `agent-inject` 会在 `SubagentStart` 时注入 `__SUBAGENT_MARKER__...`，以便 AI gateway 推导 `x-initiator: agent`。\n- `tool-search` 会注册用于 GPT Responses deferred tool loading 的 `tool_search` MCP bridge。\n\n- 本仓库中的 marketplace catalog：`.claude-plugin/marketplace.json`\n- 本仓库中的插件源码：`plugin/claude/agent-inject`、`plugin/claude/tool-search`\n\n远程添加 marketplace：\n\n```sh\n/plugin marketplace add https://github.com/caozhiyuan/copilot-api.git\n```\n\n从 marketplace 安装插件：\n\n```sh\n/plugin install agent-inject@copilot-api-marketplace\n/plugin install tool-search@copilot-api-marketplace\n```\n\n安装后，`agent-inject` 会在 `SubagentStart` 时注入 `__SUBAGENT_MARKER__...`，AI gateway 会利用它推导 `x-initiator: agent`。\n\n`agent-inject` 还会注册一个 `UserPromptSubmit` hook，并返回 `{\"continue\": true}`；同时它也可以通过环境变量注入 `SessionStart` reminder 规则：\n\n- `CLAUDE_PLUGIN_ENABLE_QUESTION_RULES=1` 会自动为 Claude Code 启用两条关于使用 `question` 工具的提醒。你也可以把同样的提醒手动写进 `CLAUDE.md`；见 [CLAUDE.md 或 AGENTS.md 推荐内容](#claudemd-or-agentsmd-recommended-content)。\n- `CLAUDE_PLUGIN_ENABLE_NO_BACKGROUND_AGENTS_RULE=1` 会启用关于避免在 agent hooks 中使用 `run_in_background: true` 的提醒。\n\n`tool-search` 插件内置了 [GPT Tool Search](#gpt-tool-search) 一节描述的同一个 MCP bridge，因此安装该插件后，Claude Code 用户无需再手动配置 `tool_search` server。\n\n#### Opencode 插件\n\nsubagent 标记生成器被打包为一个 opencode 插件，位于 `plugin/opencode/subagent-marker.js`。\n\n**安装方式：**\n\n将插件文件复制到你的 opencode 插件目录：\n\n```sh\n# 克隆或下载本仓库后复制该插件\ncp plugin/opencode/subagent-marker.js ~/.config/opencode/plugins/\n```\n\n或者手动在 `~/.config/opencode/plugins/subagent-marker.js` 创建该文件，并填入插件内容。\n\n**功能：**\n\n- 跟踪 subagent 创建的子会话\n- 自动在 subagent 聊天消息前添加 marker system reminder（`__SUBAGENT_MARKER__...`）\n- 设置 `x-session-id` 请求头以跟踪会话\n- 让这个 AI gateway 能够把来自 subagent 的请求识别为 `x-initiator: agent`\n\n该插件会挂接到 `session.created`、`session.deleted`、`chat.message` 和 `chat.headers` 事件上，以无缝提供 subagent marker 能力。\n\n## 使用量查看器\n\n服务启动后，控制台会输出一个 Copilot 使用量看板 URL。这个看板是一个用于监控 API 用量的 Web 界面。\n\n1. 启动服务。例如使用 npx：\n   ```sh\n   npx @jeffreycao/copilot-api@latest start\n   ```\n2. 服务会输出一个 usage viewer 的 URL。将它复制到浏览器中打开，形式大致如下：\n   `http://localhost:4141/usage-viewer?endpoint=http://localhost:4141/usage`\n   - 如果你在 Windows 上使用 `start.bat` 脚本，这个页面会自动打开。\n\n看板提供了更易读的 Copilot 用量视图：\n\n> token usage 历史记录需要 Bun 或 Node.js >= 22.13.0。Node.js < 22.13.0 时服务会正常运行，但 token usage 存储会被禁用。\n\n- **API Endpoint URL**：通过 URL 查询参数指定 API endpoints，默认指向本地服务。支持手动切换为其他兼容 endpoints。\n- **x-api-key 认证**：如果启用了 API Key 认证，可填入 `x-api-key` 请求头。密钥会持久化保存在浏览器本地存储中。\n- **Period 选择器**：支持 Day / Week / Month 三种时间范围，切换时 URL 参数会自动同步，方便收藏和分享。\n- **Fetch Data**：点击 \"Refresh\" 按钮加载或刷新使用数据。页面加载时也会自动拉取数据。\n- **Copilot Quotas 额度**：通过进度条展示 Chat、Completions 等不同服务的额度使用情况，悬停可查看已用/剩余详情。\n- **Token Usage 指标卡片**：汇总当前周期的 Total、Input、Output、Cache Read、Cache Write、Requests 和预估费用。\n- **趋势图（Week / Month）**：提供按模型和指标筛选的折线趋势图，点击数据点可查看单日用量明细。\n- **Model Breakdown 表格**：按模型维度列出周期内的请求数、输入/输出/缓存 token 和预计费用。\n- **Request Events 分页列表**：按时间排序的请求事件记录，支持分页浏览，含时间戳、模型、请求 ID 和 token 用量。\n- **Detailed Information**：展示 API 返回的完整 JSON 响应，便于深入分析所有可用统计数据。\n- **URL-based Configuration**：也可通过 `endpoint` 和 `period` 查询参数直接指定 API 端点与时间范围。例如：\n  `http://localhost:4141/usage-viewer?endpoint=http://your-api-server/usage&period=week`\n\n### Usage Viewer 截图\n\n<p align=\"center\">\n  <img src=\"./docs/screenshots/usage-viewer.png\" alt=\"Copilot API Usage Viewer 页面\" width=\"900\" />\n</p>\n\n## 命令结构\n\nCopilot API 现在使用子命令结构，主要命令包括：\n\n- `start`：启动 AI gateway 服务。如果已有 GitHub token，则启用 Copilot 路径；如果没有 GitHub token，但存在至少一个启用中的 provider，则按 provider-only 模式启动；如果两者都没有，会引导你配置 provider。\n- `auth`：仅执行 provider 登录或配置流程，不启动服务。可用于 GitHub Copilot 登录、Codex OAuth，或第三方 provider API key 配置。\n- `debug`：显示诊断信息，包括版本、运行时详情、文件路径以及认证状态，便于排障与支持。\n\n## 命令行选项\n\n### 全局选项\n\n以下选项可用于任意子命令。若在子命令之前传入，请使用 `--key=value` 形式：\n\n| 选项 | 说明 | 默认值 | 别名 |\n| --- | --- | --- | --- |\n| --api-home | API home 目录路径（设置 `COPILOT_API_HOME`） | 无 | 无 |\n| --oauth-app | OAuth app 标识符（设置 `COPILOT_API_OAUTH_APP`） | 无 | 无 |\n| --enterprise-url | GitHub Enterprise URL（设置 `COPILOT_API_ENTERPRISE_URL`） | 无 | 无 |\n\n### Start 命令选项\n\n以下是 `start` 命令可用的命令行选项：\n\n| 选项 | 说明 | 默认值 | 别名 |\n| --- | --- | --- | --- |\n| --port | 监听端口 | 4141 | -p |\n| --verbose | 启用详细日志 | false | -v |\n| --github-token | 直接提供 GitHub token（必须通过 `auth` 子命令生成） | 无 | -g |\n| --claude-code | 生成一个使用 Copilot API 配置启动 Claude Code 的命令 | false | -c |\n| --show-token | 在获取和刷新时显示 GitHub 与 Copilot token | false | 无 |\n| --proxy-env | 从环境变量初始化代理 | false | 无 |\n\n### Auth 命令选项\n\n| 选项 | 说明 | 默认值 | 别名 |\n| --- | --- | --- | --- |\n| --provider | 要登录或配置的 provider（`copilot`、`codex`、`opencode-go`、`deepseek`、`dashscope`、`openrouter` 或 `custom`） | 交互选择 | 无 |\n| --verbose | 启用详细日志 | false | -v |\n| --show-token | 认证时显示 GitHub token | false | 无 |\n\n只有在需要启用 GitHub Copilot provider 时，才需要执行 `copilot-api auth login --provider copilot`。使用 `codex` 或第三方 provider-only 模式不要求配置 Copilot。\n\n使用 `copilot-api auth login --provider deepseek`、`--provider dashscope`、`--provider openrouter` 或 `--provider opencode-go` 可以通过 CLI 快速新增或更新这些常用第三方 provider。DeepSeek 会提示输入掩码显示的 `apiKey`、provider `type`（默认 `anthropic`），以及默认 `https://api.deepseek.com/anthropic` 的 `baseUrl`。DashScope 会提示输入掩码显示的 `apiKey`、provider `type`（默认 `openai-compatible`）和预填默认值的 `baseUrl`。OpenRouter 只提示输入掩码显示的 `apiKey` 和预填默认值的 `baseUrl`，并固定写入 `type: \"anthropic\"`。OpenCode Go 只提示输入掩码显示的 `apiKey` 和预填默认值的 `baseUrl`，并固定写入 `type: \"openai-compatible\"`（baseUrl `https://opencode.ai/zen/go`）。配置并启用 provider 后，`copilot-api start` 可在没有 GitHub token 的情况下启动。\n\n使用 `copilot-api auth login --provider custom` 可以通过 CLI 新增或更新其他第三方 provider。命令会依次提示输入 provider name、项目支持的 type（`anthropic`、`openai-compatible` 或 `openai-responses`）、`baseUrl`、掩码显示的 `apiKey` 和 `authType`；`authType` 可保持 type 默认值，也可选择 `x-api-key` / `authorization`。\n\n### Debug 命令选项\n\n| 选项 | 说明 | 默认值 | 别名 |\n| --- | --- | --- | --- |\n| --json | 以 JSON 输出调试信息 | false | 无 |\n\n<a id=\"configuration-configjson\"></a>\n\n## 配置（config.json）\n\n- **位置：** Linux/macOS 为 `~/.local/share/copilot-api/config.json`，Windows 为 `%USERPROFILE%\\.local\\share\\copilot-api\\config.json`。\n- **默认结构：**\n  ```json\n  {\n    \"auth\": {\n      \"apiKeys\": [],\n      \"adminApiKey\": \"<startup 自动生成>\"\n    },\n    \"providers\": {},\n    \"modelMappings\": {},\n    \"extraPrompts\": {\n      \"gpt-5-mini\": \"<built-in exploration prompt>\"\n    },\n    \"smallModel\": \"gpt-5-mini\",\n    \"contextManagement\": {\n      \"messages\": true,\n      \"responses\": false\n    },\n    \"modelResponsesApiCompactThresholds\": {\n      \"gpt-5.4\": 217600,\n      \"gpt-5.5\": 217600,\n      \"gpt-5.6-sol\": 231200,\n      \"gpt-5.6-terra\": 231200,\n      \"gpt-5.6-luna\": 231200\n    },\n    \"modelReasoningEfforts\": {\n      \"gpt-5-mini\": \"low\"\n    },\n    \"useMessagesApi\": true,\n    \"useResponsesApiWebSocket\": true,\n    \"useResponsesApiWebSearch\": true,\n    \"messageApiWebSearchModel\": \"gpt-5-mini\"\n  }\n  ```\n- **auth.apiKeys：** 用于普通非 admin 路由的 API key。支持多个 key 轮换使用。请求可通过 `x-api-key: <key>` 或 `Authorization: Bearer <key>` 进行认证。若为空或省略，则普通路由的认证会被禁用。\n- **auth.adminApiKey：** 仅用于 `/admin/*` 路由的单个 admin key。若未配置，服务会在启动时自动生成一个随机 key，并回写到 `config.json`。它同样使用 `x-api-key` 或 `Authorization: Bearer` 这两种头，但普通 `auth.apiKeys` 不能访问 `/admin/*`。\n- **modelMappings：** 用于顶层 `POST /v1/messages`、`POST /v1/messages/count_tokens`、`POST /v1/responses` 和 `POST /v1/chat/completions` 请求的精确 `sourceModel -> targetModel` 重写映射，这几类接口共用同一份规则。省略该字段或保留为 `{}` 时，不会做模型重写。`source` 和 `target` 都必须是非空字符串。`target` 可以是普通模型 ID，也可以是 `provider/model` 形式的别名，例如 `dashscope/qwen3.6-plus`；重写发生在 provider alias 解析之前。这些映射不再按接口区分。`GET/POST /admin/config/model-mappings` 管理接口读写的也只有这个字段。\n- **extraPrompts：** `model -> prompt` 的映射。把 Anthropic 风格请求翻译为 Responses API 时，会将其附加到第一条 system prompt 后面。你可以借此为不同模型注入护栏或指引。缺失的默认项会自动补齐，但不会覆盖你自定义的 prompt。对于 GPT-5.3+ 模型（如 `gpt-5.3-codex`、`gpt-5.4`、`gpt-5.5`），未显式配置时会自动使用内置的 commentary prompt。内置 prompt 会启用带阶段感知的 commentary，让模型在工具调用或更深层推理前先发出简短的用户可见进度说明。\n- **providers：** 全局上游 provider 映射。每个 provider key（例如 `dashscope`）都会变成一个路由前缀（`/dashscope/v1/messages`）。支持 `type: \"anthropic\"`、`type: \"openai-compatible\"` 和 `type: \"openai-responses\"`。顶层客户端也可以在 `/v1/messages`、`/v1/messages/count_tokens`、`/v1/responses` 和 `/v1/chat/completions` 中使用 `model: \"dashscope/model-id\"`；AI gateway 会在转发上游前移除 `dashscope/` 前缀。`openai-compatible` provider 同时支持 chat 和 Messages 流程：`/v1/chat/completions` 会直连上游 `/v1/chat/completions`，而 `/v1/messages` 和 `/:provider/v1/messages` 会先翻译为上游 Chat Completions，再把响应翻译回 Anthropic Messages。`GET /v1/models` 会聚合已启用 provider 的模型，并以 `provider/model-id` 形式返回；单个 provider 的原始模型列表仍可使用 `GET /dashscope/v1/models`。\n  - `enabled`：可选，若省略则默认为 `true`。\n  - `baseUrl`：provider API 的基础 URL，不要带结尾的 endpoint。Anthropic provider 不要带 `/v1/messages`；OpenAI 兼容 provider 不要带 `/v1/chat/completions`；OpenAI Responses provider 不要带 `/v1/responses`。\n  - `apiKey`：作为上游凭据值使用；普通 provider 必须配置。\n  - `authType`：可选，控制 `apiKey` 如何发送到上游。普通 provider 支持 `x-api-key` 和 `authorization`。Anthropic provider 默认 `x-api-key`；OpenAI 兼容和 OpenAI Responses provider 默认 `authorization`。当设置为 `authorization` 时，代理会发送 `Authorization: Bearer <apiKey>`。`oauth2` 仅保留给内置 `codex` provider，并由 `auth login --provider codex` 自动写入。\n  - `pricingCurrency`：可选，provider 维度的 token 费用币种，例如 `USD` 或 `CNY`。快捷 provider 默认 DashScope、DeepSeek 为 `CNY`，Codex/OpenRouter 为 `USD`。费用按币种分别汇总，不做汇率换算。\n  - `models`：可选，按模型 ID 配置的映射。每个键为请求中的模型名，值支持：\n    - `temperature`：可选，当请求未指定时使用的默认温度。\n    - `topP`：可选，当请求未指定时使用的默认 `top_p`。\n    - `topK`：可选，当请求未指定时使用的默认 `top_k`。\n    - `extraBody`：可选，按模型合入上游请求体的动态字段；请求体显式同名字段优先。OpenAI 兼容 provider 可用它配置 `enable_thinking`、`preserve_thinking`、`reasoning_effort` 等字段。`thinking_budget` 是 OpenAI 兼容 provider 的特殊覆盖项：配置在 `extraBody` 后，会在 Anthropic `thinking.budget_tokens` 翻译之后强制写入，并覆盖请求派生出的预算值。对于 provider name 为 `dashscope` 或 `baseUrl` 包含 `aliyuncs.com` 的 provider，请求派生的 `thinking_budget`（来自 Anthropic `thinking.budget_tokens`）会转发给上游；其他 OpenAI 兼容 provider 会移除请求派生的 `thinking_budget`，但 `extraBody` 中的 `thinking_budget` 仍然生效。对于 DashScope provider，当 `preserve_thinking` 未在 `extraBody` 或请求体中显式设置时，默认为 `true`。\n    - `pricing`：可选，按模型配置 token 单价，币种使用 provider 的 `pricingCurrency`，单位为每 100 万 tokens。支持 `input`、`output`、`cachedInput`（隐式缓存读）、`explicitCachedInput`（显式缓存读）和 `cacheCreationInput`。如需按输入 token 总量分档，可用带 `maxInputTokens` 的 `tiers`。\n    - `contextCache`：可选，provider name 为 `dashscope` 或 `baseUrl` 包含 `aliyuncs.com` 时默认 `true`，其他 OpenAI 兼容 provider 默认 `false`。用于启用阿里云百炼/DashScope 的显式缓存（explicit context cache），会按其 Context Cache 格式在最多 4 个 content block 上注入 `cache_control: { \"type\": \"ephemeral\" }`。缓存断点策略与 opencode 主链路保持一致：前 2 条 system 消息 + 最后 2 条非 system 消息。标记字符串 content 时会把 `system` / `user` / `assistant` / `tool` 消息转换为 text content part 数组；已有数组 content 则标记最后一个 part。如果模型本身已经支持隐式缓存，或上游不支持该显式缓存扩展字段，可在模型配置中设为 `false`。支持相同显式缓存扩展的非 DashScope provider 可设为 `true`。同时适用于 `/v1/messages` 和 `/v1/chat/completions` 路由。\n    - `supportPdf`：可选，控制该模型是否支持 PDF/document content。默认 `false`，不支持时会把 PDF 转成提示文本；设为 `true` 时会把 PDF/document 转成 OpenAI Chat Completions 的 file part。\n    - `toolContentSupportType`：可选，配置该模型的 tool result content 支持能力，值为 `array`、`image`、`pdf` 的数组。provider 侧未配置时默认只发送 string tool content。若 `supportPdf` 为 `true` 但这里不包含 `pdf`，tool result 里的 file part 会被转成 user role 消息。Copilot 主链路不使用这个 provider 默认，仍按 array + image 且不支持 PDF 的能力处理。\n    - `type`：可选，按模型覆盖 provider 的协议类型。支持 `anthropic`、`openai-compatible` 和 `openai-responses`。设置后，provider 的 `/v1/messages` 路由会使用该模型的 type 替代 provider 级别的 type 进行请求路由、认证头解析和上游端点选择。适用于 OpenCode Go 等上游对不同模型同时支持 OpenAI 兼容和 Anthropic Messages API 的 provider。覆盖 type 时，认证头按覆盖后 type 的默认值解析（Anthropic 默认 `x-api-key`；OpenAI 兼容/Responses 默认 `authorization`）。\n\n  DashScope 模型配置示例：\n  ```json\n  {\n    \"providers\": {\n      \"dashscope\": {\n        \"type\": \"openai-compatible\",\n        \"enabled\": true,\n        \"baseUrl\": \"https://dashscope.aliyuncs.com/compatible-mode\",\n        \"apiKey\": \"sk-your-dashscope-key\",\n        \"pricingCurrency\": \"CNY\",\n        \"models\": {\n          \"qwen3.7-plus\": {\n            \"temperature\": 1,\n            \"topP\": 0.95,\n            \"topK\": 20,\n            \"extraBody\": {\n              \"preserve_thinking\": true\n            }\n          },\n          \"glm-5.1\": {\n            \"temperature\": 0.7,\n            \"topP\": 0.95,\n            \"contextCache\": true,\n            \"pricing\": {\n              \"tiers\": [\n                {\n                  \"maxInputTokens\": 32000,\n                  \"input\": 6,\n                  \"cachedInput\": 1.2,\n                  \"explicitCachedInput\": 0.6,\n                  \"cacheCreationInput\": 7.5,\n                  \"output\": 24\n                },\n                {\n                  \"maxInputTokens\": 200000,\n                  \"input\": 8,\n                  \"cachedInput\": 1.6,\n                  \"explicitCachedInput\": 0.8,\n                  \"cacheCreationInput\": 10,\n                  \"output\": 28\n                }\n              ]\n            },\n            \"extraBody\": {\n              \"preserve_thinking\": true\n            }\n          }\n        }\n      }\n    }\n  }\n  ```\n  内置 token 价格覆盖 Codex GPT 模型（USD）、DashScope `qwen3.7-max`、`qwen3.7-plus`、`glm-5.1`、`glm-5.2`（CNY），DeepSeek `deepseek-v4-flash`、`deepseek-v4-pro`、`deepseek-chat`、`deepseek-reasoner`（CNY），以及 OpenCode Go 模型（`glm-5.2`、`grok-4.5`、`deepseek-v4-flash`、`deepseek-v4-pro`、`kimi-k2.7-code`、`kimi-k3`、`mimo-v2.5`、`mimo-v2.5-pro`、`qwen3.7-plus`、`qwen3.7-max`、`minimax-m2.5`、`minimax-m3`，USD）。用户配置的 `pricing` 优先于内置价格。DashScope 若上游 usage 中出现 `cache_creation_input_tokens` 字段，cached tokens 按显式缓存读价计费；否则 `cachedInput` 作为隐式缓存读价。DeepSeek 的 `prompt_cache_hit_tokens` 会归入 cached input，`prompt_cache_miss_tokens` 会归入普通 input。\n- **smallModel：** 无工具预热消息的回退模型（例如 Claude Code 的探测请求）；默认是 `gpt-5-mini`。\n- **contextManagement：** 控制代理是否为 Responses API 附加 `context_management` 压缩指令。`messages` 作用于被翻译成 Responses API 的 Anthropic 风格 `/v1/messages` 请求，包括 `openai-responses` provider 的 Messages 路由，默认值为 `true`。`responses` 作用于 native `/v1/responses` 流量，包括 `provider/model` 别名和内置 `codex` provider，默认值为 `false`。只有在确认客户端支持 context management compaction 后，才建议在 Responses API 下启用 `responses`。启用后，请求体会带上 `context_management`，并在后续轮次中仅保留最新的压缩承载内容。**注意：** 对于 GPT-5.6 及以上模型（如 `gpt-5.6-sol`、`gpt-5.6-terra`、`gpt-5.6-luna`），context management 功能会被强制禁用，因为开启后会破坏这些模型的 prompt 缓存命中。此强制覆盖优先于 `contextManagement` 和 `modelResponsesApiCompactThresholds` 配置。\n- **modelResponsesApiCompactThresholds：** 按模型覆盖 Responses API 的 `compact_threshold`，仅在代理自动附加 `context_management` 时使用。它的优先级高于 `resolveResponsesCompactThreshold` 基于 `max_prompt_tokens * ratio` 的兜底阈值。默认将 `gpt-5.4` 和 `gpt-5.5` 设为 `217600`（`272000 * 0.8`），将 `gpt-5.6-sol`、`gpt-5.6-terra`、`gpt-5.6-luna` 设为 `231200`（`272000 * 0.85`）。未列出的模型继续使用原有兜底逻辑。\n- **modelReasoningEfforts：** `/v1/messages` 请求的模型级默认推理强度。仅当请求没有传入 `output_config.effort` 时，该配置才会生效。\n  - **优先级：** 请求中的 `output_config.effort` > `modelReasoningEfforts[model]` > 内置默认值（GPT-5.3+ 模型为 `xhigh`，其他模型为 `high`）。\n  - **转发字段：** 走 Copilot 原生 Messages API 时，最终值写入 `output_config.effort`；转换为 Responses API 时，最终值写入 `reasoning.effort`。\n  - **配置可选值：** `none`、`minimal`、`low`、`medium`、`high`、`xhigh`、`max`。\n- **useMessagesApi：** 当为 `true` 时，支持 Copilot 原生 `/v1/messages` 的 Claude 系模型会走 Messages API；否则回退到 `/chat/completions`。设为 `false` 可禁用 Messages API 路由，始终使用 `/chat/completions`。默认值为 `true`。\n- **useResponsesApiWebSocket：** 当为 `true` 时，Responses API 请求会优先对声明了 `ws:/responses` 的模型使用 Copilot websocket transport；仅声明 `/responses` 的模型仍走 HTTP。设为 `false` 可禁用 websocket 路由，并在模型支持 `/responses` 时使用 HTTP `/responses`。默认值为 `true`。如果遇到 Responses API WebSocket closed，一般是自己的网络问题。如果使用了 VPN，建议切换节点。\n- **useResponsesApiWebSearch：** 当为 `true` 时，服务端会保留 Responses API 中 `type: \"web_search\"` 的工具并透传到上游。设为 `false` 则会从 `/responses` payload 中移除这些工具。默认值为 `true`。\n- **messageApiWebSearchModel：** 顶层 Copilot `/v1/messages` 请求只包含服务端 `web_search` 工具时使用的全局模型，默认值为 `gpt-5-mini`。如果该值是 `provider/model` 别名，请求会进入对应 provider 的 Messages API 路径，并在转发前移除 provider 前缀。对于 Copilot GPT 模型，web search 会通过 `/responses` 执行。混合 `web_search` 与自定义工具的场景暂不支持，服务端会移除 server-side `web_search`。\n- **claudeTokenMultiplier：** 用于 Claude `/v1/messages/count_tokens` 请求在本地走 GPT tokenizer 估算时的乘数。默认值为 `1.15`。如果你的客户端仍然过晚触发上下文压缩，可以适当调大。这个配置只会在代理本地估算 Claude token 时生效；如果已经配置 `anthropicApiKey` 且 Anthropic token counting 调用成功，则会直接返回 Anthropic 的精确计数，不会使用这个乘数。\n- **anthropicApiKey：** 用于把 Claude `/v1/messages/count_tokens` 请求转发到 Anthropic 真实 token counting 端点的 API key，这样会返回精确计数，而不是 GPT tokenizer 估算值。也可通过环境变量 `ANTHROPIC_API_KEY` 设置。若未配置，或上游调用失败，则回退到由 `claudeTokenMultiplier` 控制的本地 GPT tokenizer 估算。\n\n编辑此文件后即可自定义 prompts，或替换为你自己的快速模型。修改完成后请重启服务（或重新执行命令），让缓存中的配置刷新生效。\n\n## API 认证\n\n- **受保护的普通路由：** 当配置了 `auth.apiKeys` 且非空时，除 `/`、`/usage-viewer` 和 `/usage-viewer/` 以外的普通路由都需要认证。\n- **Admin 路由：** 所有 `/admin/*` 路由都要求 `auth.adminApiKey`。如果缺失，服务会在启动时自动生成并在开始提供服务前写回 `config.json`。\n- **允许的认证头：**\n  - `x-api-key: <your_key>`\n  - `Authorization: Bearer <your_key>`\n- **CORS 预检：** `OPTIONS` 请求始终允许。\n- **未配置普通 key 时：** 普通路由仍可直接访问；但这条规则不适用于 `/admin/*`，后者只接受 `auth.adminApiKey`。\n\n普通受保护路由的示例请求：\n\n```sh\ncurl http://localhost:4141/v1/models \\\n  -H \"x-api-key: your_api_key\"\n```\n\nAdmin 路由的示例请求：\n\n```sh\ncurl http://localhost:4141/admin/config/model-mappings \\\n  -H \"x-api-key: your_admin_api_key\"\n```\n\n## API 端点\n\n服务端提供多个 OpenAI / Anthropic 兼容端点。请求会根据所选模型和 `provider/model` 别名路由到 GitHub Copilot、内置 `codex` provider 或已配置的 provider。\n\n### OpenAI 兼容端点\n\n这些端点模拟 OpenAI API 结构。\n\n| 端点 | 方法 | 说明 |\n| --- | --- | --- |\n| `POST /v1/responses` | `POST` | OpenAI 中用于生成模型响应的高级接口。支持 `openai-responses` provider 的 `provider/model` 别名。 |\n| `POST /v1/chat/completions` | `POST` | 为给定聊天对话创建模型响应。支持 `openai-compatible` provider 的 `provider/model` 别名；目标 provider 已配置时可在没有 Copilot 的情况下使用。 |\n| `GET /v1/models` | `GET` | 列出 Copilot 模型以及已启用 provider 的 `provider/model-id` 模型。来自 Codex 客户端（`User-Agent` 以 `codex` 开头）的请求会转发到 Codex Models 上游。 |\n| `POST /v1/embeddings` | `POST` | 创建表示输入文本的向量嵌入。 |\n\n### Codex 后端代理端点\n\n这些端点要求已有可用的 Codex 登录态。每个端点同时提供无版本前缀和 `/v1` 两种路径。\n\n| 端点 | 方法 | 说明 |\n| --- | --- | --- |\n| `POST /alpha/search`<br>`POST /v1/alpha/search` | `POST` | 将 JSON 请求体和查询参数透明转发到 Codex Alpha Search 上游。 |\n| `POST /images/generations`<br>`POST /v1/images/generations` | `POST` | 将 JSON 图片生成请求转发到 Codex Images 上游。请求未携带 `Content-Type` 时，网关默认补充 `application/json`。 |\n| `POST /images/edits`<br>`POST /v1/images/edits` | `POST` | 将图片编辑请求转发到 Codex Images 上游。请使用 `multipart/form-data`，并让 HTTP 客户端自动生成 `boundary`；网关会保留传入的 content type，并以流式方式转发上传请求体。 |\n\n对于以上所有端点，网关都会使用当前 Codex 登录态覆盖客户端的 authorization 和 account header，保留查询参数及兼容的请求头，并返回上游状态码、响应头和响应体。\n\n### Anthropic 兼容端点\n\n这些端点设计为兼容 Anthropic Messages API。provider 级的 models、Responses、alpha-search 和 images 路由同时支持无版本前缀与 `/v1` 两种路径；Messages 路由仍使用 `/v1`。\n\n| 端点 | 方法 | 说明 |\n| --- | --- | --- |\n| `POST /v1/messages` | `POST` | 为给定对话创建模型响应。支持已配置 provider 的 `provider/model` 别名，包括通过 `openai-compatible` provider 做翻译。 |\n| `POST /v1/messages/count_tokens` | `POST` | 计算一组消息的 token 数。支持已配置 provider 的 `provider/model` 别名。 |\n| `POST /:provider/v1/messages` | `POST` | 将 Anthropic Messages 请求代理到已配置的 Anthropic provider，或翻译到 OpenAI 兼容 / OpenAI Responses provider。 |\n| `GET /:provider/models`<br>`GET /:provider/v1/models` | `GET` | 将模型列表请求代理到已配置的 provider。对 `codex` 默认返回内置模型目录；Codex 客户端（`User-Agent` 以 `codex` 开头）会转发到 Codex Models 上游。 |\n| `POST /:provider/v1/messages/count_tokens` | `POST` | 为 provider 路由请求在本地计算 token 数。 |\n| `POST /:provider/responses`<br>`POST /:provider/v1/responses` | `POST` | 将 OpenAI Responses 请求代理到已配置的 `openai-responses` provider（含 `codex`）。 |\n| `POST /:provider/alpha/search`<br>`POST /:provider/v1/alpha/search` | `POST` | 代理 alpha-search 请求。对 `codex` 转发到 Codex Alpha Search 上游；其他 provider 转发到 `{baseUrl}/v1/alpha/search`。 |\n| `POST /:provider/images/generations`<br>`POST /:provider/v1/images/generations` | `POST` | 代理图片生成。对 `codex` 使用 Codex Images 上游；其他 provider 转发到 `{baseUrl}/v1/images/generations`（15 分钟超时）。 |\n| `POST /:provider/images/edits`<br>`POST /:provider/v1/images/edits` | `POST` | 代理图片编辑。对 `codex` 使用 Codex Images 上游；其他 provider 以 multipart/流式方式转发到 `{baseUrl}/v1/images/edits`（15 分钟超时）。 |\n\n### 使用量监控端点\n\n用于监控 Copilot 用量与额度的新端点。\n\n| 端点 | 方法 | 说明 |\n| --- | --- | --- |\n| `GET /usage` | `GET` | 获取详细的 Copilot 使用统计与额度信息。 |\n| `GET /token` | `GET` | 获取当前 API 正在使用的 Copilot token。 |\n\n### Admin / 配置端点\n\n这些端点用于本地管理操作，只接受 `auth.adminApiKey`。\n\n| 端点 | 方法 | 说明 |\n| --- | --- | --- |\n| `GET /admin/config/model-mappings` | `GET` | 返回当前 `config.json` 路径以及生效中的 `modelMappings` 映射。 |\n| `POST /admin/config/model-mappings` | `POST` | 只更新 `config.json` 里的 `modelMappings` 字段，并回传更新后的结果。 |\n\n## 使用示例\n\n常用 `npx` 命令：\n\n```sh\n# 基础启动\nnpx @jeffreycao/copilot-api@latest start\n\n# 自定义端口并开启详细日志\nnpx @jeffreycao/copilot-api@latest start --port 8080 --verbose\n\n# 执行认证流程\nnpx @jeffreycao/copilot-api@latest auth login\n\n# 配置第三方 provider，然后不依赖 GitHub Copilot 启动\nnpx @jeffreycao/copilot-api@latest auth login --provider dashscope\nnpx @jeffreycao/copilot-api@latest start\n\n# 以 JSON 格式输出调试信息\nnpx @jeffreycao/copilot-api@latest debug --json\n\n# 用 Bun 而不是 Node.js 运行已发布 CLI\nbunx --bun @jeffreycao/copilot-api@latest start\n```\n\n配置 `dashscope` 后的 OpenAI 兼容 provider 调用示例：\n\n```sh\ncurl http://localhost:4141/v1/chat/completions \\\n  -H \"content-type: application/json\" \\\n  -d '{\"model\":\"dashscope/qwen3.6-plus\",\"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]}'\n\ncurl http://localhost:4141/dashscope/v1/messages \\\n  -H \"content-type: application/json\" \\\n  -d '{\"model\":\"qwen3.6-plus\",\"max_tokens\":1024,\"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]}'\n```\n\n## 使用建议\n\n<a id=\"claudemd-or-agentsmd-recommended-content\"></a>\n\n### CLAUDE.md 或 AGENTS.md 推荐内容\n\n如果你想手动加入这些提醒，请在 Claude Code 的 `CLAUDE.md`，或 opencode/codex 的 `AGENTS.md` 中加入以下内容：\n\n```\n- Prohibited from directly asking questions to users, MUST use question tool.\n- Once you can confirm that the task is complete, MUST use question tool to make user confirm. The user may respond with feedback if they are not satisfied with the result, which you can use to make improvements and try again, after try again, MUST use question tool to make user confirm again.\n```\n"}, "6f97faf757e5f903eb239a1047939a053a1086a9": {"t": 1785765543.3565075, "n": 33446, "h": "588d42942847c244", "c": "# Copilot API Proxy\n\n[English](./README.md) | 简体中文\n\n## 重要说明\n\n> [!IMPORTANT]\n> **使用前请先注意以下几点：**\n>\n> 1. **Claude Code 配置：** 与 Claude Code 搭配使用时，请将模型 ID 配置为 `claude-opus-4-8`。示例 claude `settings.json` 见 [通过 `settings.json` 手动配置](#manual-configuration-with-settingsjson)。\n>\n> 2. **内置 `copilot`、`codex` 与第三方 provider：** 执行 `npx @jeffreycao/copilot-api@latest auth`，可选择 `copilot`、`codex`、`deepseek`、`custom` 等 provider。\n>\n> 3. **注意事项：** README 顶部移除的 GitHub Copilot warning 见 [GitHub Copilot 安全提示](./NOTICE.md#github-copilot-security-notice)。\n\n---\n\n## 项目概览\n\n这是一个小型 AI gateway，可以使用 GitHub Copilot、内置 `codex` provider，也可以使用 DashScope 等已配置的第三方 provider。GitHub Copilot 现在是可选能力：如果本地没有 GitHub token，只要至少配置了一个启用中的 provider，服务仍可按 provider-only 模式启动。\n\nAI gateway 会从同一个本地端点暴露 OpenAI / Anthropic 兼容 API，让 [Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview)、OpenCode、Codex 和 OpenAI 兼容客户端可以共用同一个本地服务。\n\n在 GitHub Copilot 路径上，AI gateway 会在可用时优先使用 Copilot 原生的 Anthropic 风格 Messages API，在重工具调用场景下保留更原生的 Claude 行为。\n\n## 功能特性\n\n- **OpenAI 与 Anthropic 双兼容**：通过 `/v1/responses`、`/v1/chat/completions`、`/v1/models`、`/v1/embeddings` 和 `/v1/messages` 对外暴露同一个本地 AI gateway。\n- **Copilot 可选**：有 GitHub 凭据时可以使用 GitHub Copilot，没有 GitHub 凭据时也可以只依赖已配置的 provider 运行。\n- **同一网关接入 Copilot、`codex` 与第三方 provider**：可统一路由 GitHub Copilot、内置 `codex` provider 和配置好的外部 provider。\n- **第三方 provider 可独立启动**：配置 DashScope、DeepSeek、OpenRouter 或自定义 provider 后，不需要 GitHub Copilot 登录即可启动 AI gateway。\n- **OpenAI 兼容 provider 同时支持 chat 和 Messages API**：`openai-compatible` provider 可通过顶层 `/v1/chat/completions` 搭配 `model: \"provider/model\"` 提供 Chat Completions，也可通过 `/v1/messages` 完成 Anthropic Messages 的请求/响应翻译。\n- **面向 Claude 的更原生 Copilot 路由**：优先使用原生 `/v1/messages`，保留 Claude 风格工具流，支持 Anthropic beta 能力、通过 Responses-capable 模型支持 Claude WebSearch，并保留 subagent / session 标记。\n- **Claude Code 与 OpenCode 集成**：兼容 Claude Code 与 OpenCode，也支持通过 `@ai-sdk/anthropic` 直接作为 Anthropic provider 使用。\n- **灵活的认证与部署选项**：支持交互式登录、直接 token、个人 / Business / Enterprise、GitHub Enterprise、opencode OAuth 和自定义数据目录。\n- **多 provider 路由**：可暴露 `/:provider/...` 路由，也可在顶层 API 上使用 `model: \"provider/model\"`。\n\n## 前置要求\n\n- Bun（>= 1.2.x）\n- 如果要通过 `npx` 运行已发布 CLI，需要 Node.js\n- 只有在使用 GitHub Copilot provider 时，才需要已订阅 Copilot 的 GitHub 账号\n- 如果不使用 GitHub Copilot，需要至少一个已配置 provider 的 API key 或 OAuth 登录\n\n## 安装\n\n安装依赖：\n\n```sh\nbun install\n```\n\n直接从源码启动服务：\n\n```sh\nbun run start start\n```\n\n## 从源码运行\n\n本项目可以通过多种方式从源码运行：\n\n### 开发模式\n\n```sh\nbun run dev start\n```\n\n### 生产模式\n\n```sh\nbun run start start\n```\n\n## 通过 npx 使用\n\n你可以直接用 npx 运行本项目：\n\n> [!IMPORTANT]\n> 通过 `npx` 运行时，token usage 存储会使用 Node 内置的 `node:sqlite` 模块。该能力会在 Node.js >= 22.13.0 时启用；Node.js < 22.13.0 时 CLI 仍可启动，但会禁用 token usage 存储。\n>\n> 如果不升级 Node.js 但仍需要 token usage 存储，可以改用 Bun 运行已发布 CLI：`bunx --bun @jeffreycao/copilot-api@latest start`。\n\n```sh\nnpx @jeffreycao/copilot-api@latest start\n```\n\n带参数示例：\n\n```sh\nnpx @jeffreycao/copilot-api@latest start --port 8080\n```\n\n如果只想做认证或 provider 配置：\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth\n```\n\n如果要不依赖 GitHub Copilot 运行，先配置至少一个 provider，然后正常启动服务：\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth login --provider dashscope\nnpx @jeffreycao/copilot-api@latest start\n```\n\n## 配合 Docker 使用\n\n构建镜像：\n\n```sh\ndocker build -t copilot-api .\n```\n\n通过 bind mount 运行容器，让认证数据在重启后保留：\n\n```sh\nmkdir -p ./copilot-data\ndocker run -p 4141:4141 -v $(pwd)/copilot-data:/root/.local/share/copilot-api copilot-api\n```\n\n这会把宿主机上的 `./copilot-data` 映射到容器内的 `/root/.local/share/copilot-api`，用于持久化 GitHub 认证数据、provider 配置和其他 gateway 状态。\n\n也可以直接通过环境变量传入 GitHub token：\n\n```sh\ndocker run -p 4141:4141 -e GH_TOKEN=your_github_token_here copilot-api\n```\n\n## Electron 桌面应用\n\n如果你更喜欢图形界面，仓库里还提供了位于 `desktop/` 的 Electron 桌面应用。它支持 GitHub Copilot 登录、OpenAI Codex OAuth，以及 DeepSeek、DashScope、OpenRouter 或自定义 provider 的 API Key 配置。授权或配置 provider 后，可以一键启动或停止本地代理，并在界面里直接查看本地端点、鉴权 Header、可用模型、额度和日志。\n\n设置页还可以配置 `OAuth App`、`API Home`、`Enterprise URL`、详细日志以及最小化到托盘。桌面安装包发布在 GitHub Releases：\n\nhttps://github.com/caozhiyuan/copilot-api/releases\n\n下载对应平台的安装包后，在应用内授权或配置 provider，选择端口并启动服务，再把你的客户端指向应用里显示的本地端点即可。发布版桌面应用使用随包内置的 Electron 运行时，正常使用不需要额外安装 Node.js；token usage 历史记录会在该内置运行时支持 SQLite 时启用。\n\n桌面应用里的高级配置页会通过 `GET/POST /admin/config/model-mappings` 读写这份共享的模型映射。同一份映射会统一作用于 `POST /v1/messages`、`POST /v1/messages/count_tokens`、`POST /v1/responses` 和 `POST /v1/chat/completions`，不再按接口区分。它使用的是 `auth.adminApiKey`，不是普通的 `auth.apiKeys`；应用会在服务启动并自动生成该 key 后，直接从 `config.json` 读取它来发起请求。\n\n### 桌面应用截图\n\n下面展示了桌面应用中的首页、Token 用量统计页面：\n\n<p align=\"center\">\n  <img src=\"./docs/screenshots/desktop-dashboard.png\" alt=\"Copilot API 桌面应用首页\" width=\"49%\" />\n  <img src=\"./docs/screenshots/desktop-token-usage.png\" alt=\"Copilot API 桌面应用 Token 用量页\" width=\"49%\" />\n</p>\n\n## 与 Claude Code 一起使用\n\n这个 AI gateway 可以为 [Claude Code](https://docs.anthropic.com/en/claude-code) 提供后端能力。Claude Code 是 Anthropic 提供的实验性面向开发者的对话式 AI 助手。\n\n有两种方式可以把 Claude Code 配置为使用这个 AI gateway：\n\n### 通过 `--claude-code` 标志进行交互式配置\n\n执行带 `--claude-code` 的 `start` 命令开始：\n\n```sh\nnpx @jeffreycao/copilot-api@latest start --claude-code\n```\n\n你不再需要手动选择模型。Gateway 会自动检测每个 Claude Code 尺寸档位对应的最新可用模型——opus 映射到最新的 Opus 模型，sonnet 映射到最新的 Sonnet 模型，haiku 映射到最新的 Haiku 模型——并生成相应设置 `ANTHROPIC_DEFAULT_OPUS_MODEL`、`ANTHROPIC_DEFAULT_SONNET_MODEL` 和 `ANTHROPIC_DEFAULT_HAIKU_MODEL` 的命令。若某个档位没有匹配的可用模型，则会被省略。该命令会被复制到剪贴板，并设置 Claude Code 使用这个 AI gateway 所需的环境变量。\n\n在新的终端中粘贴并执行这条命令，即可启动 Claude Code。\n\n<a id=\"manual-configuration-with-settingsjson\"></a>\n\n### 通过 `settings.json` 手动配置\n\n另一种方式是在项目根目录中创建 `.claude/settings.json` 文件，并写入 Claude Code 所需的环境变量。这样你就不需要每次都运行交互式配置了。\n\n下面是一个 `.claude/settings.json` 示例：\n\n```json\n{\n  \"env\": {\n    \"ANTHROPIC_BASE_URL\": \"http://localhost:4141\",\n    \"ANTHROPIC_AUTH_TOKEN\": \"dummy\",\n    \"ANTHROPIC_MODEL\": \"codex/gpt-5.6-sol[1m]\",\n    \"ANTHROPIC_DEFAULT_SONNET_MODEL\": \"codex/gpt-5.6-sol[1m]\",\n    \"ANTHROPIC_DEFAULT_HAIKU_MODEL\": \"codex/gpt-5.6-luna[1m]\",\n    \"CLAUDE_CODE_AUTO_COMPACT_WINDOW\": \"272000\",\n    \"CLAUDE_CODE_USE_VERTEX\": \"0\",\n    \"CLAUDE_CODE_USE_BEDROCK\": \"0\",\n    \"DISABLE_NON_ESSENTIAL_MODEL_CALLS\": \"1\",\n    \"CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC\": \"1\",\n    \"CLAUDE_CODE_ATTRIBUTION_HEADER\": \"0\",\n    \"CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION\": \"false\",\n    \"CLAUDE_CODE_DISABLE_TERMINAL_TITLE\": \"true\",\n    \"CLAUDE_CODE_ENABLE_AWAY_SUMMARY\": \"0\"\n  },\n  \"alwaysThinkingEnabled\": true,\n  \"effortLevel\": \"xhigh\",\n  \"showThinkingSummaries\": true\n}\n```\n\n- 请根据需要替换 `ANTHROPIC_MODEL`、`ANTHROPIC_DEFAULT_OPUS_MODEL`、`ANTHROPIC_DEFAULT_SONNET_MODEL` 和 `ANTHROPIC_DEFAULT_HAIKU_MODEL`。配置完成后，请安装 claude code 插件，见 [插件集成](#plugin-integrations)。\n- 将 `CLAUDE_CODE_ATTRIBUTION_HEADER` 设为 `0` 可以阻止 Claude Code 在 system prompt 中附加计费和版本信息，从而避免 prompt cache 失效。\n- 关闭 `CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION` 和 `CLAUDE_CODE_ENABLE_AWAY_SUMMARY` 可以避免不必要地消耗额度。\n- Claude Code WebSearch 已支持纯搜索请求。Copilot 路径请保持全局 `messageApiWebSearchModel` 指向 Responses-capable GPT 模型或 `provider/model` 别名；provider 路由请使用原生 Anthropic provider 或 `openai-responses` provider。只有在你明确想禁止这类流量时，才需要把 `WebSearch` 加到 `permissions.deny`。\n- 如果使用的不是 Claude 模型，请不要启用 `ENABLE_TOOL_SEARCH`。如果使用的是 Claude 模型，则可以启用 `ENABLE_TOOL_SEARCH`。当前 Claude Code 使用的是客户端 tool search 模式，在该模式下每次加载 defer tools 都需要额外请求一次。\n- `CLAUDE_CODE_AUTO_COMPACT_WINDOW`：设置用于自动压缩计算的上下文容量（以 token 为单位）。默认使用模型自身的上下文窗口：标准模型为 200K，扩展上下文模型为 1M。使用 1M 上下文模型（如 `claude-opus-4-6[1m]`）时，可设置一个较低的值（如 `500000`）将窗口视为 500K 用于压缩计算。该值受限于模型的实际上下文窗口上限。`CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` 会基于此值的百分比生效。设置此变量可将压缩阈值与状态栏的 `used_percentage` 解耦（后者始终使用模型的完整上下文窗口）。\n\n更多选项见：[Claude Code settings](https://docs.anthropic.com/en/docs/claude-code/settings#environment-variables)\n\n也可以参考 IDE 集成说明：[Add Claude Code to your IDE](https://docs.anthropic.com/en/docs/claude-code/ide-integrations)\n\n## 与 OpenCode 一起使用\n\nOpenCode 已经有直接的 GitHub Copilot provider。本节适用于你希望让 OpenCode 通过 `@ai-sdk/anthropic` 指向这个 AI gateway，并复用本 README 前面提到的 agent 行为时。\n\n### 最小配置\n\n使用 OpenCode OAuth app 启动 AI gateway：\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth --oauth-app=opencode\nnpx @jeffreycao/copilot-api@latest start\n```\n\n然后让 OpenCode 通过 `@ai-sdk/anthropic` 指向这个 AI gateway。\n\n示例 `~/.config/opencode/opencode.json`：\n\n```json\n{\n  \"$schema\": \"https://opencode.ai/config.json\",\n  \"provider\": {\n    \"local\": {\n      \"npm\": \"@ai-sdk/anthropic\",\n      \"name\": \"My Local\",\n      \"options\": {\n        \"baseURL\": \"http://localhost:4141/v1\",\n        \"apiKey\": \"dummy\"\n      },\n      \"models\": {\n        \"gpt-5.4\": {\n          \"name\": \"gpt-5.4\",\n          \"modalities\": {\n            \"input\": [\"text\", \"image\"],\n            \"output\": [\"text\"]\n          },\n          \"limit\": {\n            \"context\": 400000,\n            \"input\": 272000,\n            \"output\": 128000\n          }\n        },\n        \"claude-sonnet-4.6\": {\n          \"id\": \"claude-sonnet-4.6\",\n          \"name\": \"claude-sonnet-4.6\",\n          \"modalities\": {\n            \"input\": [\"text\", \"image\"],\n            \"output\": [\"text\"]\n          },\n          \"limit\": {\n            \"context\": 200000,\n            \"output\": 32000\n          },\n          \"options\": {\n            \"thinking\": {\n              \"type\": \"adaptive\"\n            },\n            \"effort\": \"max\"\n          }\n        }\n      }\n    }\n  }\n}\n```\n\n这些字段的重要性：\n\n- `npm: \"@ai-sdk/anthropic\"` 是关键。OpenCode 会以 Anthropic Messages 语义与这个 AI gateway 通信，而不是把一切扁平化为 OpenAI Chat Completions。\n- `options.baseURL` 应设为 `http://localhost:4141/v1`；Anthropic SDK 会自动补上 `/messages`、`/models` 和 `/messages/count_tokens`。\n- 如果你在此代理中启用了 `auth.apiKeys`，请把 `dummy` 替换为真实 key；否则任意占位值都可以。\n\n## 与 Codex 一起使用\n\n这个 AI gateway 也可以为 Codex 提供后端能力。\n\n### Codex `config.toml` 参考配置\n\n把以下 `[model_providers.copilot_api]` 段加入你的 Codex `~/.codex/config.toml`：\n\n```toml\nmodel_provider = \"copilot_api\"\nmodel_reasoning_summary = \"auto\"\nmodel_context_window = 272000\nmodel_auto_compact_token_limit = 244800\n\n[model_providers.copilot_api]\nname = \"OpenAI\"\nbase_url = \"http://localhost:4141\"\nenv_key = \"GITHUB_COPILOT_API_KEY\"\nrequires_openai_auth = true\nsupports_websockets = false\nwire_api = \"responses\"\nrequest_max_retries = 3\nstream_max_retries = 1\nstream_idle_timeout_ms = 300000\n\n[features]\nremote_compaction_v2 = true\n\n[analytics]\nenabled = false\n```\n\n> [!NOTE]\n> 此配置仅限于 Codex 与 GitHub Copilot provider。`name` 一定要配置为 `\"OpenAI\"`。它可以缓解 Codex local compact 不命中缓存的问题。\n> 如果使用 codex provider，建议将 `base_url` 配置为 `\"http://localhost:4141/codex\"`。\n\n## GPT Tool Search\n\n对于 `gpt-5.4+` 这类 GPT Responses 模型，这个 AI gateway 可以通过一个很小的 MCP bridge 暴露 Responses `tool_search`。Claude Code 和 opencode 都可以使用同一个 bridge，前提是客户端会加载 MCP server，并且 Anthropic Messages 流量会经过这个 AI gateway。\n\nGPT 模型不要设置 Claude Code 原生的 `ENABLE_TOOL_SEARCH`。这个开关启用的是 Claude Code 自己的客户端 tool search 模式，可能导致 deferred 工具定义不再转发给 AI gateway。这个 AI gateway 需要完整的工具定义，这样才能只保留那一小组常驻加载工具，其余工具统一转换为 Responses deferred namespace。\n\n如果你安装了 `tool-search@copilot-api-marketplace`，Claude Code 会自动带上这个 MCP bridge，可以跳过下面这段 Claude Code MCP 手动配置。\n\n请把 tool search bridge 加到 Claude Code 使用的 MCP 配置中：\n\n```json\n{\n  \"mcpServers\": {\n    \"tool_search\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@jeffreycao/copilot-api@latest\", \"mcp\"]\n    }\n  }\n}\n```\n\n请把 tool search bridge 加到 opencode 使用的 MCP 配置中：\n\n```json\n{\n  \"mcp\": {\n    \"tool_search\": {\n      \"type\": \"local\",\n      \"command\": [\"npx\", \"-y\", \"@jeffreycao/copilot-api@latest\", \"mcp\"]\n    }\n  }\n}\n```\n\n本地开发时可以将命令换成 `bun`，参数换成 `[\"run\", \"./src/main.ts\", \"mcp\"]`。\n\nAI gateway 内部现在会把 OpenAI Responses `tool_search` 配置成 client-executed 模式。deferred tools 仍然会作为可搜索 namespace 暴露给模型，但会明确要求模型直接返回下一步要加载的精确工具名列表。\n\n该 bridge 使用直接工具选择，不做 query 搜索。工具入参是 `names`，值为逗号分隔的精确 deferred 工具名，例如 `TaskList,TaskGet,mcp__fetch__fetch`。\n\n<a id=\"plugin-integrations\"></a>\n\n## 插件集成\n\n本项目为 Claude Code 和 opencode 提供了插件集成。\n\n#### Claude Code 插件集成（基于 marketplace）\n\nClaude Code 集成现在拆分为两个插件：\n\n- `agent-inject` 会在 `SubagentStart` 时注入 `__SUBAGENT_MARKER__...`，以便 AI gateway 推导 `x-initiator: agent`。\n- `tool-search` 会注册用于 GPT Responses deferred tool loading 的 `tool_search` MCP bridge。\n\n- 本仓库中的 marketplace catalog：`.claude-plugin/marketplace.json`\n- 本仓库中的插件源码：`plugin/claude/agent-inject`、`plugin/claude/tool-search`\n\n远程添加 marketplace：\n\n```sh\n/plugin marketplace add https://github.com/caozhiyuan/copilot-api.git\n```\n\n从 marketplace 安装插件：\n\n```sh\n/plugin install agent-inject@copilot-api-marketplace\n/plugin install tool-search@copilot-api-marketplace\n```\n\n安装后，`agent-inject` 会在 `SubagentStart` 时注入 `__SUBAGENT_MARKER__...`，AI gateway 会利用它推导 `x-initiator: agent`。\n\n`agent-inject` 还会注册一个 `UserPromptSubmit` hook，并返回 `{\"continue\": true}`；同时它也可以通过环境变量注入 `SessionStart` reminder 规则：\n\n- `CLAUDE_PLUGIN_ENABLE_QUESTION_RULES=1` 会自动为 Claude Code 启用两条关于使用 `question` 工具的提醒。你也可以把同样的提醒手动写进 `CLAUDE.md`；见 [CLAUDE.md 或 AGENTS.md 推荐内容](#claudemd-or-agentsmd-recommended-content)。\n- `CLAUDE_PLUGIN_ENABLE_NO_BACKGROUND_AGENTS_RULE=1` 会启用关于避免在 agent hooks 中使用 `run_in_background: true` 的提醒。\n\n`tool-search` 插件内置了 [GPT Tool Search](#gpt-tool-search) 一节描述的同一个 MCP bridge，因此安装该插件后，Claude Code 用户无需再手动配置 `tool_search` server。\n\n#### Opencode 插件\n\nsubagent 标记生成器被打包为一个 opencode 插件，位于 `plugin/opencode/subagent-marker.js`。\n\n**安装方式：**\n\n将插件文件复制到你的 opencode 插件目录：\n\n```sh\n# 克隆或下载本仓库后复制该插件\ncp plugin/opencode/subagent-marker.js ~/.config/opencode/plugins/\n```\n\n或者手动在 `~/.config/opencode/plugins/subagent-marker.js` 创建该文件，并填入插件内容。\n\n**功能：**\n\n- 跟踪 subagent 创建的子会话\n- 自动在 subagent 聊天消息前添加 marker system reminder（`__SUBAGENT_MARKER__...`）\n- 设置 `x-session-id` 请求头以跟踪会话\n- 让这个 AI gateway 能够把来自 subagent 的请求识别为 `x-initiator: agent`\n\n该插件会挂接到 `session.created`、`session.deleted`、`chat.message` 和 `chat.headers` 事件上，以无缝提供 subagent marker 能力。\n\n## 使用量查看器\n\n服务启动后，控制台会输出一个 Copilot 使用量看板 URL。这个看板是一个用于监控 API 用量的 Web 界面。\n\n1. 启动服务。例如使用 npx：\n   ```sh\n   npx @jeffreycao/copilot-api@latest start\n   ```\n2. 服务会输出一个 usage viewer 的 URL。将它复制到浏览器中打开，形式大致如下：\n   `http://localhost:4141/usage-viewer?endpoint=http://localhost:4141/usage`\n   - 如果你在 Windows 上使用 `start.bat` 脚本，这个页面会自动打开。\n\n看板提供了更易读的 Copilot 用量视图：\n\n> token usage 历史记录需要 Bun 或 Node.js >= 22.13.0。Node.js < 22.13.0 时服务会正常运行，但 token usage 存储会被禁用。\n\n- **API Endpoint URL**：通过 URL 查询参数指定 API endpoints，默认指向本地服务。支持手动切换为其他兼容 endpoints。\n- **x-api-key 认证**：如果启用了 API Key 认证，可填入 `x-api-key` 请求头。密钥会持久化保存在浏览器本地存储中。\n- **Period 选择器**：支持 Day / Week / Month 三种时间范围，切换时 URL 参数会自动同步，方便收藏和分享。\n- **Fetch Data**：点击 \"Refresh\" 按钮加载或刷新使用数据。页面加载时也会自动拉取数据。\n- **Copilot Quotas 额度**：通过进度条展示 Chat、Completions 等不同服务的额度使用情况，悬停可查看已用/剩余详情。\n- **Token Usage 指标卡片**：汇总当前周期的 Total、Input、Output、Cache Read、Cache Write、Requests 和预估费用。\n- **趋势图（Week / Month）**：提供按模型和指标筛选的折线趋势图，点击数据点可查看单日用量明细。\n- **Model Breakdown 表格**：按模型维度列出周期内的请求数、输入/输出/缓存 token 和预计费用。\n- **Request Events 分页列表**：按时间排序的请求事件记录，支持分页浏览，含时间戳、模型、请求 ID 和 token 用量。\n- **Detailed Information**：展示 API 返回的完整 JSON 响应，便于深入分析所有可用统计数据。\n- **URL-based Configuration**：也可通过 `endpoint` 和 `period` 查询参数直接指定 API 端点与时间范围。例如：\n  `http://localhost:4141/usage-viewer?endpoint=http://your-api-server/usage&period=week`\n\n### Usage Viewer 截图\n\n<p align=\"center\">\n  <img src=\"./docs/screenshots/usage-viewer.png\" alt=\"Copilot API Usage Viewer 页面\" width=\"900\" />\n</p>\n\n## 命令结构\n\nCopilot API 现在使用子命令结构，主要命令包括：\n\n- `start`：启动 AI gateway 服务。如果已有 GitHub token，则启用 Copilot 路径；如果没有 GitHub token，但存在至少一个启用中的 provider，则按 provider-only 模式启动；如果两者都没有，会引导你配置 provider。\n- `auth`：仅执行 provider 登录或配置流程，不启动服务。可用于 GitHub Copilot 登录、Codex OAuth，或第三方 provider API key 配置。\n- `debug`：显示诊断信息，包括版本、运行时详情、文件路径以及认证状态，便于排障与支持。\n\n## 命令行选项\n\n### 全局选项\n\n以下选项可用于任意子命令。若在子命令之前传入，请使用 `--key=value` 形式：\n\n| 选项 | 说明 | 默认值 | 别名 |\n| --- | --- | --- | --- |\n| --api-home | API home 目录路径（设置 `COPILOT_API_HOME`） | 无 | 无 |\n| --oauth-app | OAuth app 标识符（设置 `COPILOT_API_OAUTH_APP`） | 无 | 无 |\n| --enterprise-url | GitHub Enterprise URL（设置 `COPILOT_API_ENTERPRISE_URL`） | 无 | 无 |\n\n### Start 命令选项\n\n以下是 `start` 命令可用的命令行选项：\n\n| 选项 | 说明 | 默认值 | 别名 |\n| --- | --- | --- | --- |\n| --port | 监听端口 | 4141 | -p |\n| --verbose | 启用详细日志 | false | -v |\n| --github-token | 直接提供 GitHub token（必须通过 `auth` 子命令生成） | 无 | -g |\n| --claude-code | 生成一个使用 Copilot API 配置启动 Claude Code 的命令 | false | -c |\n| --show-token | 在获取和刷新时显示 GitHub 与 Copilot token | false | 无 |\n| --proxy-env | 从环境变量初始化代理 | false | 无 |\n\n### Auth 命令选项\n\n| 选项 | 说明 | 默认值 | 别名 |\n| --- | --- | --- | --- |\n| --provider | 要登录或配置的 provider（`copilot`、`codex`、`opencode-go`、`deepseek`、`dashscope`、`openrouter` 或 `custom`） | 交互选择 | 无 |\n| --verbose | 启用详细日志 | false | -v |\n| --show-token | 认证时显示 GitHub token | false | 无 |\n\n只有在需要启用 GitHub Copilot provider 时，才需要执行 `copilot-api auth login --provider copilot`。使用 `codex` 或第三方 provider-only 模式不要求配置 Copilot。\n\n使用 `copilot-api auth login --provider deepseek`、`--provider dashscope`、`--provider openrouter` 或 `--provider opencode-go` 可以通过 CLI 快速新增或更新这些常用第三方 provider。DeepSeek 会提示输入掩码显示的 `apiKey`、provider `type`（默认 `anthropic`），以及默认 `https://api.deepseek.com/anthropic` 的 `baseUrl`。DashScope 会提示输入掩码显示的 `apiKey`、provider `type`（默认 `openai-compatible`）和预填默认值的 `baseUrl`。OpenRouter 只提示输入掩码显示的 `apiKey` 和预填默认值的 `baseUrl`，并固定写入 `type: \"anthropic\"`。OpenCode Go 只提示输入掩码显示的 `apiKey` 和预填默认值的 `baseUrl`，并固定写入 `type: \"openai-compatible\"`（baseUrl `https://opencode.ai/zen/go`）。配置并启用 provider 后，`copilot-api start` 可在没有 GitHub token 的情况下启动。\n\n使用 `copilot-api auth login --provider custom` 可以通过 CLI 新增或更新其他第三方 provider。命令会依次提示输入 provider name、项目支持的 type（`anthropic`、`openai-compatible` 或 `openai-responses`）、`baseUrl`、掩码显示的 `apiKey` 和 `authType`；`authType` 可保持 type 默认值，也可选择 `x-api-key` / `authorization`。\n\n### Debug 命令选项\n\n| 选项 | 说明 | 默认值 | 别名 |\n| --- | --- | --- | --- |\n| --json | 以 JSON 输出调试信息 | false | 无 |\n\n<a id=\"configuration-configjson\"></a>\n\n## 配置（config.json）\n\n- **位置：** Linux/macOS 为 `~/.local/share/copilot-api/config.json`，Windows 为 `%USERPROFILE%\\.local\\share\\copilot-api\\config.json`。\n- **默认结构：**\n  ```json\n  {\n    \"auth\": {\n      \"apiKeys\": [],\n      \"adminApiKey\": \"<startup 自动生成>\"\n    },\n    \"providers\": {},\n    \"modelMappings\": {},\n    \"extraPrompts\": {\n      \"gpt-5-mini\": \"<built-in exploration prompt>\"\n    },\n    \"smallModel\": \"gpt-5-mini\",\n    \"contextManagement\": {\n      \"messages\": true,\n      \"responses\": false\n    },\n    \"modelResponsesApiCompactThresholds\": {\n      \"gpt-5.4\": 217600,\n      \"gpt-5.5\": 217600,\n      \"gpt-5.6-sol\": 231200,\n      \"gpt-5.6-terra\": 231200,\n      \"gpt-5.6-luna\": 231200\n    },\n    \"modelReasoningEfforts\": {\n      \"gpt-5-mini\": \"low\"\n    },\n    \"useMessagesApi\": true,\n    \"useResponsesApiWebSocket\": true,\n    \"useResponsesApiWebSearch\": true,\n    \"messageApiWebSearchModel\": \"gpt-5-mini\"\n  }\n  ```\n- **auth.apiKeys：** 用于普通非 admin 路由的 API key。支持多个 key 轮换使用。请求可通过 `x-api-key: <key>` 或 `Authorization: Bearer <key>` 进行认证。若为空或省略，则普通路由的认证会被禁用。\n- **auth.adminApiKey：** 仅用于 `/admin/*` 路由的单个 admin key。若未配置，服务会在启动时自动生成一个随机 key，并回写到 `config.json`。它同样使用 `x-api-key` 或 `Authorization: Bearer` 这两种头，但普通 `auth.apiKeys` 不能访问 `/admin/*`。\n- **modelMappings：** 用于顶层 `POST /v1/messages`、`POST /v1/messages/count_tokens`、`POST /v1/responses` 和 `POST /v1/chat/completions` 请求的精确 `sourceModel -> targetModel` 重写映射，这几类接口共用同一份规则。省略该字段或保留为 `{}` 时，不会做模型重写。`source` 和 `target` 都必须是非空字符串。`target` 可以是普通模型 ID，也可以是 `provider/model` 形式的别名，例如 `dashscope/qwen3.6-plus`；重写发生在 provider alias 解析之前。这些映射不再按接口区分。`GET/POST /admin/config/model-mappings` 管理接口读写的也只有这个字段。\n- **extraPrompts：** `model -> prompt` 的映射。把 Anthropic 风格请求翻译为 Responses API 时，会将其附加到第一条 system prompt 后面。你可以借此为不同模型注入护栏或指引。缺失的默认项会自动补齐，但不会覆盖你自定义的 prompt。对于 GPT-5.3+ 模型（如 `gpt-5.3-codex`、`gpt-5.4`、`gpt-5.5`），未显式配置时会自动使用内置的 commentary prompt。内置 prompt 会启用带阶段感知的 commentary，让模型在工具调用或更深层推理前先发出简短的用户可见进度说明。\n- **providers：** 全局上游 provider 映射。每个 provider key（例如 `dashscope`）都会变成一个路由前缀（`/dashscope/v1/messages`）。支持 `type: \"anthropic\"`、`type: \"openai-compatible\"` 和 `type: \"openai-responses\"`。顶层客户端也可以在 `/v1/messages`、`/v1/messages/count_tokens`、`/v1/responses` 和 `/v1/chat/completions` 中使用 `model: \"dashscope/model-id\"`；AI gateway 会在转发上游前移除 `dashscope/` 前缀。`openai-compatible` provider 同时支持 chat 和 Messages 流程：`/v1/chat/completions` 会直连上游 `/v1/chat/completions`，而 `/v1/messages` 和 `/:provider/v1/messages` 会先翻译为上游 Chat Completions，再把响应翻译回 Anthropic Messages。`GET /v1/models` 会聚合已启用 provider 的模型，并以 `provider/model-id` 形式返回；单个 provider 的原始模型列表仍可使用 `GET /dashscope/v1/models`。\n  - `enabled`：可选，若省略则默认为 `true`。\n  - `baseUrl`：provider API 的基础 URL，不要带结尾的 endpoint。Anthropic provider 不要带 `/v1/messages`；OpenAI 兼容 provider 不要带 `/v1/chat/completions`；OpenAI Responses provider 不要带 `/v1/responses`。\n  - `apiKey`：作为上游凭据值使用；普通 provider 必须配置。\n  - `authType`：可选，控制 `apiKey` 如何发送到上游。普通 provider 支持 `x-api-key` 和 `authorization`。Anthropic provider 默认 `x-api-key`；OpenAI 兼容和 OpenAI Responses provider 默认 `authorization`。当设置为 `authorization` 时，代理会发送 `Authorization: Bearer <apiKey>`。`oauth2` 仅保留给内置 `codex` provider，并由 `auth login --provider codex` 自动写入。\n  - `pricingCurrency`：可选，provider 维度的 token 费用币种，例如 `USD` 或 `CNY`。快捷 provider 默认 DashScope、DeepSeek 为 `CNY`，Codex/OpenRouter 为 `USD`。费用按币种分别汇总，不做汇率换算。\n  - `models`：可选，按模型 ID 配置的映射。每个键为请求中的模型名，值支持：\n    - `temperature`：可选，当请求未指定时使用的默认温度。\n    - `topP`：可选，当请求未指定时使用的默认 `top_p`。\n    - `topK`：可选，当请求未指定时使用的默认 `top_k`。\n    - `extraBody`：可选，按模型合入上游请求体的动态字段；请求体显式同名字段优先。OpenAI 兼容 provider 可用它配置 `enable_thinking`、`preserve_thinking`、`reasoning_effort` 等字段。`thinking_budget` 是 OpenAI 兼容 provider 的特殊覆盖项：配置在 `extraBody` 后，会在 Anthropic `thinking.budget_tokens` 翻译之后强制写入，并覆盖请求派生出的预算值。对于 provider name 为 `dashscope` 或 `baseUrl` 包含 `aliyuncs.com` 的 provider，请求派生的 `thinking_budget`（来自 Anthropic `thinking.budget_tokens`）会转发给上游；其他 OpenAI 兼容 provider 会移除请求派生的 `thinking_budget`，但 `extraBody` 中的 `thinking_budget` 仍然生效。对于 DashScope provider，当 `preserve_thinking` 未在 `extraBody` 或请求体中显式设置时，默认为 `true`。\n    - `pricing`：可选，按模型配置 token 单价，币种使用 provider 的 `pricingCurrency`，单位为每 100 万 tokens。支持 `input`、`output`、`cachedInput`（隐式缓存读）、`explicitCachedInput`（显式缓存读）和 `cacheCreationInput`。如需按输入 token 总量分档，可用带 `maxInputTokens` 的 `tiers`。\n    - `contextCache`：可选，provider name 为 `dashscope` 或 `baseUrl` 包含 `aliyuncs.com` 时默认 `true`，其他 OpenAI 兼容 provider 默认 `false`。用于启用阿里云百炼/DashScope 的显式缓存（explicit context cache），会按其 Context Cache 格式在最多 4 个 content block 上注入 `cache_control: { \"type\": \"ephemeral\" }`。缓存断点策略与 opencode 主链路保持一致：前 2 条 system 消息 + 最后 2 条非 system 消息。标记字符串 content 时会把 `system` / `user` / `assistant` / `tool` 消息转换为 text content part 数组；已有数组 content 则标记最后一个 part。如果模型本身已经支持隐式缓存，或上游不支持该显式缓存扩展字段，可在模型配置中设为 `false`。支持相同显式缓存扩展的非 DashScope provider 可设为 `true`。同时适用于 `/v1/messages` 和 `/v1/chat/completions` 路由。\n    - `supportPdf`：可选，控制该模型是否支持 PDF/document content。默认 `false`，不支持时会把 PDF 转成提示文本；设为 `true` 时会把 PDF/document 转成 OpenAI Chat Completions 的 file part。\n    - `toolContentSupportType`：可选，配置该模型的 tool result content 支持能力，值为 `array`、`image`、`pdf` 的数组。provider 侧未配置时默认只发送 string tool content。若 `supportPdf` 为 `true` 但这里不包含 `pdf`，tool result 里的 file part 会被转成 user role 消息。Copilot 主链路不使用这个 provider 默认，仍按 array + image 且不支持 PDF 的能力处理。\n    - `type`：可选，按模型覆盖 provider 的协议类型。支持 `anthropic`、`openai-compatible` 和 `openai-responses`。设置后，provider 的 `/v1/messages` 路由会使用该模型的 type 替代 provider 级别的 type 进行请求路由、认证头解析和上游端点选择。适用于 OpenCode Go 等上游对不同模型同时支持 OpenAI 兼容和 Anthropic Messages API 的 provider。覆盖 type 时，认证头按覆盖后 type 的默认值解析（Anthropic 默认 `x-api-key`；OpenAI 兼容/Responses 默认 `authorization`）。\n\n  DashScope 模型配置示例：\n  ```json\n  {\n    \"providers\": {\n      \"dashscope\": {\n        \"type\": \"openai-compatible\",\n        \"enabled\": true,\n        \"baseUrl\": \"https://dashscope.aliyuncs.com/compatible-mode\",\n        \"apiKey\": \"sk-your-dashscope-key\",\n        \"pricingCurrency\": \"CNY\",\n        \"models\": {\n          \"qwen3.7-plus\": {\n            \"temperature\": 1,\n            \"topP\": 0.95,\n            \"topK\": 20,\n            \"extraBody\": {\n              \"preserve_thinking\": true\n            }\n          },\n          \"glm-5.1\": {\n            \"temperature\": 0.7,\n            \"topP\": 0.95,\n            \"contextCache\": true,\n            \"pricing\": {\n              \"tiers\": [\n                {\n                  \"maxInputTokens\": 32000,\n                  \"input\": 6,\n                  \"cachedInput\": 1.2,\n                  \"explicitCachedInput\": 0.6,\n                  \"cacheCreationInput\": 7.5,\n                  \"output\": 24\n                },\n                {\n                  \"maxInputTokens\": 200000,\n                  \"input\": 8,\n                  \"cachedInput\": 1.6,\n                  \"explicitCachedInput\": 0.8,\n                  \"cacheCreationInput\": 10,\n                  \"output\": 28\n                }\n              ]\n            },\n            \"extraBody\": {\n              \"preserve_thinking\": true\n            }\n          }\n        }\n      }\n    }\n  }\n  ```\n  内置 token 价格覆盖 Codex GPT 模型（USD）、DashScope `qwen3.7-max`、`qwen3.7-plus`、`glm-5.1`、`glm-5.2`（CNY），DeepSeek `deepseek-v4-flash`、`deepseek-v4-pro`、`deepseek-chat`、`deepseek-reasoner`（CNY），以及 OpenCode Go 模型（`glm-5.2`、`grok-4.5`、`deepseek-v4-flash`、`deepseek-v4-pro`、`kimi-k2.7-code`、`kimi-k3`、`mimo-v2.5`、`mimo-v2.5-pro`、`qwen3.7-plus`、`qwen3.7-max`、`minimax-m2.5`、`minimax-m3`，USD）。用户配置的 `pricing` 优先于内置价格。DashScope 若上游 usage 中出现 `cache_creation_input_tokens` 字段，cached tokens 按显式缓存读价计费；否则 `cachedInput` 作为隐式缓存读价。DeepSeek 的 `prompt_cache_hit_tokens` 会归入 cached input，`prompt_cache_miss_tokens` 会归入普通 input。\n- **smallModel：** 无工具预热消息的回退模型（例如 Claude Code 的探测请求）；默认是 `gpt-5-mini`。\n- **contextManagement：** 控制代理是否为 Responses API 附加 `context_management` 压缩指令。`messages` 作用于被翻译成 Responses API 的 Anthropic 风格 `/v1/messages` 请求，包括 `openai-responses` provider 的 Messages 路由，默认值为 `true`。`responses` 作用于 native `/v1/responses` 流量，包括 `provider/model` 别名和内置 `codex` provider，默认值为 `false`。只有在确认客户端支持 context management compaction 后，才建议在 Responses API 下启用 `responses`。启用后，请求体会带上 `context_management`，并在后续轮次中仅保留最新的压缩承载内容。**注意：** 对于 GPT-5.6 及以上模型（如 `gpt-5.6-sol`、`gpt-5.6-terra`、`gpt-5.6-luna`），context management 功能会被强制禁用，因为开启后会破坏这些模型的 prompt 缓存命中。此强制覆盖优先于 `contextManagement` 和 `modelResponsesApiCompactThresholds` 配置。\n- **modelResponsesApiCompactThresholds：** 按模型覆盖 Responses API 的 `compact_threshold`，仅在代理自动附加 `context_management` 时使用。它的优先级高于 `resolveResponsesCompactThreshold` 基于 `max_prompt_tokens * ratio` 的兜底阈值。默认将 `gpt-5.4` 和 `gpt-5.5` 设为 `217600`（`272000 * 0.8`），将 `gpt-5.6-sol`、`gpt-5.6-terra`、`gpt-5.6-luna` 设为 `231200`（`272000 * 0.85`）。未列出的模型继续使用原有兜底逻辑。\n- **modelReasoningEfforts：** `/v1/messages` 请求的模型级默认推理强度。仅当请求没有传入 `output_config.effort` 时，该配置才会生效。\n  - **优先级：** 请求中的 `output_config.effort` > `modelReasoningEfforts[model]` > 内置默认值（GPT-5.3+ 模型为 `xhigh`，其他模型为 `high`）。\n  - **转发字段：** 走 Copilot 原生 Messages API 时，最终值写入 `output_config.effort`；转换为 Responses API 时，最终值写入 `reasoning.effort`。\n  - **配置可选值：** `none`、`minimal`、`low`、`medium`、`high`、`xhigh`、`max`。\n- **useMessagesApi：** 当为 `true` 时，支持 Copilot 原生 `/v1/messages` 的 Claude 系模型会走 Messages API；否则回退到 `/chat/completions`。设为 `false` 可禁用 Messages API 路由，始终使用 `/chat/completions`。默认值为 `true`。\n- **useResponsesApiWebSocket：** 当为 `true` 时，Responses API 请求会优先对声明了 `ws:/responses` 的模型使用 Copilot websocket transport；仅声明 `/responses` 的模型仍走 HTTP。设为 `false` 可禁用 websocket 路由，并在模型支持 `/responses` 时使用 HTTP `/responses`。默认值为 `true`。如果遇到 Responses API WebSocket closed，一般是自己的网络问题。如果使用了 VPN，建议切换节点。\n- **useResponsesApiWebSearch：** 当为 `true` 时，服务端会保留 Responses API 中 `type: \"web_search\"` 的工具并透传到上游。设为 `false` 则会从 `/responses` payload 中移除这些工具。默认值为 `true`。\n- **messageApiWebSearchModel：** 顶层 Copilot `/v1/messages` 请求只包含服务端 `web_search` 工具时使用的全局模型，默认值为 `gpt-5-mini`。如果该值是 `provider/model` 别名，请求会进入对应 provider 的 Messages API 路径，并在转发前移除 provider 前缀。对于 Copilot GPT 模型，web search 会通过 `/responses` 执行。混合 `web_search` 与自定义工具的场景暂不支持，服务端会移除 server-side `web_search`。\n- **claudeTokenMultiplier：** 用于 Claude `/v1/messages/count_tokens` 请求在本地走 GPT tokenizer 估算时的乘数。默认值为 `1.15`。如果你的客户端仍然过晚触发上下文压缩，可以适当调大。这个配置只会在代理本地估算 Claude token 时生效；如果已经配置 `anthropicApiKey` 且 Anthropic token counting 调用成功，则会直接返回 Anthropic 的精确计数，不会使用这个乘数。\n- **anthropicApiKey：** 用于把 Claude `/v1/messages/count_tokens` 请求转发到 Anthropic 真实 token counting 端点的 API key，这样会返回精确计数，而不是 GPT tokenizer 估算值。也可通过环境变量 `ANTHROPIC_API_KEY` 设置。若未配置，或上游调用失败，则回退到由 `claudeTokenMultiplier` 控制的本地 GPT tokenizer 估算。\n\n编辑此文件后即可自定义 prompts，或替换为你自己的快速模型。修改完成后请重启服务（或重新执行命令），让缓存中的配置刷新生效。\n\n## API 认证\n\n- **受保护的普通路由：** 当配置了 `auth.apiKeys` 且非空时，除 `/`、`/usage-viewer` 和 `/usage-viewer/` 以外的普通路由都需要认证。\n- **Admin 路由：** 所有 `/admin/*` 路由都要求 `auth.adminApiKey`。如果缺失，服务会在启动时自动生成并在开始提供服务前写回 `config.json`。\n- **允许的认证头：**\n  - `x-api-key: <your_key>`\n  - `Authorization: Bearer <your_key>`\n- **CORS 预检：** `OPTIONS` 请求始终允许。\n- **未配置普通 key 时：** 普通路由仍可直接访问；但这条规则不适用于 `/admin/*`，后者只接受 `auth.adminApiKey`。\n\n普通受保护路由的示例请求：\n\n```sh\ncurl http://localhost:4141/v1/models \\\n  -H \"x-api-key: your_api_key\"\n```\n\nAdmin 路由的示例请求：\n\n```sh\ncurl http://localhost:4141/admin/config/model-mappings \\\n  -H \"x-api-key: your_admin_api_key\"\n```\n\n## API 端点\n\n服务端提供多个 OpenAI / Anthropic 兼容端点。请求会根据所选模型和 `provider/model` 别名路由到 GitHub Copilot、内置 `codex` provider 或已配置的 provider。\n\n### OpenAI 兼容端点\n\n这些端点模拟 OpenAI API 结构。\n\n| 端点 | 方法 | 说明 |\n| --- | --- | --- |\n| `POST /v1/responses` | `POST` | OpenAI 中用于生成模型响应的高级接口。支持 `openai-responses` provider 的 `provider/model` 别名。 |\n| `POST /v1/chat/completions` | `POST` | 为给定聊天对话创建模型响应。支持 `openai-compatible` provider 的 `provider/model` 别名；目标 provider 已配置时可在没有 Copilot 的情况下使用。 |\n| `GET /v1/models` | `GET` | 列出 Copilot 模型以及已启用 provider 的 `provider/model-id` 模型。来自 Codex 客户端（`User-Agent` 以 `codex` 开头）的请求会转发到 Codex Models 上游。 |\n| `POST /v1/embeddings` | `POST` | 创建表示输入文本的向量嵌入。 |\n\n### Codex 后端代理端点\n\n这些端点要求已有可用的 Codex 登录态。每个端点同时提供无版本前缀和 `/v1` 两种路径。\n\n| 端点 | 方法 | 说明 |\n| --- | --- | --- |\n| `POST /alpha/search`<br>`POST /v1/alpha/search` | `POST` | 将 JSON 请求体和查询参数透明转发到 Codex Alpha Search 上游。 |\n| `POST /images/generations`<br>`POST /v1/images/generations` | `POST` | 将 JSON 图片生成请求转发到 Codex Images 上游。请求未携带 `Content-Type` 时，网关默认补充 `application/json`。 |\n| `POST /images/edits`<br>`POST /v1/images/edits` | `POST` | 将图片编辑请求转发到 Codex Images 上游。请使用 `multipart/form-data`，并让 HTTP 客户端自动生成 `boundary`；网关会保留传入的 content type，并以流式方式转发上传请求体。 |\n\n对于以上所有端点，网关都会使用当前 Codex 登录态覆盖客户端的 authorization 和 account header，保留查询参数及兼容的请求头，并返回上游状态码、响应头和响应体。\n\n### Anthropic 兼容端点\n\n这些端点设计为兼容 Anthropic Messages API。provider 级的 models、Responses、alpha-search 和 images 路由同时支持无版本前缀与 `/v1` 两种路径；Messages 路由仍使用 `/v1`。\n\n| 端点 | 方法 | 说明 |\n| --- | --- | --- |\n| `POST /v1/messages` | `POST` | 为给定对话创建模型响应。支持已配置 provider 的 `provider/model` 别名，包括通过 `openai-compatible` provider 做翻译。 |\n| `POST /v1/messages/count_tokens` | `POST` | 计算一组消息的 token 数。支持已配置 provider 的 `provider/model` 别名。 |\n| `POST /:provider/v1/messages` | `POST` | 将 Anthropic Messages 请求代理到已配置的 Anthropic provider，或翻译到 OpenAI 兼容 / OpenAI Responses provider。 |\n| `GET /:provider/models`<br>`GET /:provider/v1/models` | `GET` | 将模型列表请求代理到已配置的 provider。对 `codex` 默认返回内置模型目录；Codex 客户端（`User-Agent` 以 `codex` 开头）会转发到 Codex Models 上游。 |\n| `POST /:provider/v1/messages/count_tokens` | `POST` | 为 provider 路由请求在本地计算 token 数。 |\n| `POST /:provider/responses`<br>`POST /:provider/v1/responses` | `POST` | 将 OpenAI Responses 请求代理到已配置的 `openai-responses` provider（含 `codex`）。 |\n| `POST /:provider/alpha/search`<br>`POST /:provider/v1/alpha/search` | `POST` | 代理 alpha-search 请求。对 `codex` 转发到 Codex Alpha Search 上游；其他 provider 转发到 `{baseUrl}/v1/alpha/search`。 |\n| `POST /:provider/images/generations`<br>`POST /:provider/v1/images/generations` | `POST` | 代理图片生成。对 `codex` 使用 Codex Images 上游；其他 provider 转发到 `{baseUrl}/v1/images/generations`（15 分钟超时）。 |\n| `POST /:provider/images/edits`<br>`POST /:provider/v1/images/edits` | `POST` | 代理图片编辑。对 `codex` 使用 Codex Images 上游；其他 provider 以 multipart/流式方式转发到 `{baseUrl}/v1/images/edits`（15 分钟超时）。 |\n\n### 使用量监控端点\n\n用于监控 Copilot 用量与额度的新端点。\n\n| 端点 | 方法 | 说明 |\n| --- | --- | --- |\n| `GET /usage` | `GET` | 获取详细的 Copilot 使用统计与额度信息。 |\n| `GET /token` | `GET` | 获取当前 API 正在使用的 Copilot token。 |\n\n### Admin / 配置端点\n\n这些端点用于本地管理操作，只接受 `auth.adminApiKey`。\n\n| 端点 | 方法 | 说明 |\n| --- | --- | --- |\n| `GET /admin/config/model-mappings` | `GET` | 返回当前 `config.json` 路径以及生效中的 `modelMappings` 映射。 |\n| `POST /admin/config/model-mappings` | `POST` | 只更新 `config.json` 里的 `modelMappings` 字段，并回传更新后的结果。 |\n\n## 使用示例\n\n常用 `npx` 命令：\n\n```sh\n# 基础启动\nnpx @jeffreycao/copilot-api@latest start\n\n# 自定义端口并开启详细日志\nnpx @jeffreycao/copilot-api@latest start --port 8080 --verbose\n\n# 执行认证流程\nnpx @jeffreycao/copilot-api@latest auth login\n\n# 配置第三方 provider，然后不依赖 GitHub Copilot 启动\nnpx @jeffreycao/copilot-api@latest auth login --provider dashscope\nnpx @jeffreycao/copilot-api@latest start\n\n# 以 JSON 格式输出调试信息\nnpx @jeffreycao/copilot-api@latest debug --json\n\n# 用 Bun 而不是 Node.js 运行已发布 CLI\nbunx --bun @jeffreycao/copilot-api@latest start\n```\n\n配置 `dashscope` 后的 OpenAI 兼容 provider 调用示例：\n\n```sh\ncurl http://localhost:4141/v1/chat/completions \\\n  -H \"content-type: application/json\" \\\n  -d '{\"model\":\"dashscope/qwen3.6-plus\",\"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]}'\n\ncurl http://localhost:4141/dashscope/v1/messages \\\n  -H \"content-type: application/json\" \\\n  -d '{\"model\":\"qwen3.6-plus\",\"max_tokens\":1024,\"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]}'\n```\n\n## 使用建议\n\n<a id=\"claudemd-or-agentsmd-recommended-content\"></a>\n\n### CLAUDE.md 或 AGENTS.md 推荐内容\n\n如果你想手动加入这些提醒，请在 Claude Code 的 `CLAUDE.md`，或 opencode/codex 的 `AGENTS.md` 中加入以下内容：\n\n```\n- Prohibited from directly asking questions to users, MUST use question tool.\n- Once you can confirm that the task is complete, MUST use question tool to make user confirm. The user may respond with feedback if they are not satisfied with the result, which you can use to make improvements and try again, after try again, MUST use question tool to make user confirm again.\n```\n"}, "5952198121b3da7fb798c1462720ac730dd1fa7d": {"t": 1785765544.969183, "n": 33428, "h": "67cc6f46d1e2ef09", "c": "# Copilot API Proxy\n\n[English](./README.md) | 简体中文\n\n## 重要说明\n\n> [!IMPORTANT]\n> **使用前请先注意以下几点：**\n>\n> 1. **Claude Code 配置：** 与 Claude Code 搭配使用时，请将模型 ID 配置为 `claude-opus-4-8`。示例 claude `settings.json` 见 [通过 `settings.json` 手动配置](#manual-configuration-with-settingsjson)。\n>\n> 2. **内置 `copilot`、`codex` 与第三方 provider：** 执行 `npx @jeffreycao/copilot-api@latest auth`，可选择 `copilot`、`codex`、`deepseek`、`custom` 等 provider。\n>\n> 3. **注意事项：** README 顶部移除的 GitHub Copilot warning 见 [GitHub Copilot 安全提示](./NOTICE.md#github-copilot-security-notice)。\n\n---\n\n## 项目概览\n\n这是一个小型 AI gateway，可以使用 GitHub Copilot、内置 `codex` provider，也可以使用 DashScope 等已配置的第三方 provider。GitHub Copilot 现在是可选能力：如果本地没有 GitHub token，只要至少配置了一个启用中的 provider，服务仍可按 provider-only 模式启动。\n\nAI gateway 会从同一个本地端点暴露 OpenAI / Anthropic 兼容 API，让 [Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview)、OpenCode、Codex 和 OpenAI 兼容客户端可以共用同一个本地服务。\n\n在 GitHub Copilot 路径上，AI gateway 会在可用时优先使用 Copilot 原生的 Anthropic 风格 Messages API，在重工具调用场景下保留更原生的 Claude 行为。\n\n## 功能特性\n\n- **OpenAI 与 Anthropic 双兼容**：通过 `/v1/responses`、`/v1/chat/completions`、`/v1/models`、`/v1/embeddings` 和 `/v1/messages` 对外暴露同一个本地 AI gateway。\n- **Copilot 可选**：有 GitHub 凭据时可以使用 GitHub Copilot，没有 GitHub 凭据时也可以只依赖已配置的 provider 运行。\n- **同一网关接入 Copilot、`codex` 与第三方 provider**：可统一路由 GitHub Copilot、内置 `codex` provider 和配置好的外部 provider。\n- **第三方 provider 可独立启动**：配置 DashScope、DeepSeek、OpenRouter 或自定义 provider 后，不需要 GitHub Copilot 登录即可启动 AI gateway。\n- **OpenAI 兼容 provider 同时支持 chat 和 Messages API**：`openai-compatible` provider 可通过顶层 `/v1/chat/completions` 搭配 `model: \"provider/model\"` 提供 Chat Completions，也可通过 `/v1/messages` 完成 Anthropic Messages 的请求/响应翻译。\n- **面向 Claude 的更原生 Copilot 路由**：优先使用原生 `/v1/messages`，保留 Claude 风格工具流，支持 Anthropic beta 能力、通过 Responses-capable 模型支持 Claude WebSearch，并保留 subagent / session 标记。\n- **Claude Code 与 OpenCode 集成**：兼容 Claude Code 与 OpenCode，也支持通过 `@ai-sdk/anthropic` 直接作为 Anthropic provider 使用。\n- **灵活的认证与部署选项**：支持交互式登录、直接 token、个人 / Business / Enterprise、GitHub Enterprise、opencode OAuth 和自定义数据目录。\n- **多 provider 路由**：可暴露 `/:provider/...` 路由，也可在顶层 API 上使用 `model: \"provider/model\"`。\n\n## 前置要求\n\n- Bun（>= 1.2.x）\n- 如果要通过 `npx` 运行已发布 CLI，需要 Node.js\n- 只有在使用 GitHub Copilot provider 时，才需要已订阅 Copilot 的 GitHub 账号\n- 如果不使用 GitHub Copilot，需要至少一个已配置 provider 的 API key 或 OAuth 登录\n\n## 安装\n\n安装依赖：\n\n```sh\nbun install\n```\n\n直接从源码启动服务：\n\n```sh\nbun run start start\n```\n\n## 从源码运行\n\n本项目可以通过多种方式从源码运行：\n\n### 开发模式\n\n```sh\nbun run dev start\n```\n\n### 生产模式\n\n```sh\nbun run start start\n```\n\n## 通过 npx 使用\n\n你可以直接用 npx 运行本项目：\n\n> [!IMPORTANT]\n> 通过 `npx` 运行时，token usage 存储会使用 Node 内置的 `node:sqlite` 模块。该能力会在 Node.js >= 22.13.0 时启用；Node.js < 22.13.0 时 CLI 仍可启动，但会禁用 token usage 存储。\n>\n> 如果不升级 Node.js 但仍需要 token usage 存储，可以改用 Bun 运行已发布 CLI：`bunx --bun @jeffreycao/copilot-api@latest start`。\n\n```sh\nnpx @jeffreycao/copilot-api@latest start\n```\n\n带参数示例：\n\n```sh\nnpx @jeffreycao/copilot-api@latest start --port 8080\n```\n\n如果只想做认证或 provider 配置：\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth\n```\n\n如果要不依赖 GitHub Copilot 运行，先配置至少一个 provider，然后正常启动服务：\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth login --provider dashscope\nnpx @jeffreycao/copilot-api@latest start\n```\n\n## 配合 Docker 使用\n\n构建镜像：\n\n```sh\ndocker build -t copilot-api .\n```\n\n通过 bind mount 运行容器，让认证数据在重启后保留：\n\n```sh\nmkdir -p ./copilot-data\ndocker run -p 4141:4141 -v $(pwd)/copilot-data:/root/.local/share/copilot-api copilot-api\n```\n\n这会把宿主机上的 `./copilot-data` 映射到容器内的 `/root/.local/share/copilot-api`，用于持久化 GitHub 认证数据、provider 配置和其他 gateway 状态。\n\n也可以直接通过环境变量传入 GitHub token：\n\n```sh\ndocker run -p 4141:4141 -e GH_TOKEN=your_github_token_here copilot-api\n```\n\n## Electron 桌面应用\n\n如果你更喜欢图形界面，仓库里还提供了位于 `desktop/` 的 Electron 桌面应用。它支持 GitHub Copilot 登录、OpenAI Codex OAuth，以及 DeepSeek、DashScope、OpenRouter 或自定义 provider 的 API Key 配置。授权或配置 provider 后，可以一键启动或停止本地代理，并在界面里直接查看本地端点、鉴权 Header、可用模型、额度和日志。\n\n设置页还可以配置 `OAuth App`、`API Home`、`Enterprise URL`、详细日志以及最小化到托盘。桌面安装包发布在 GitHub Releases：\n\nhttps://github.com/caozhiyuan/copilot-api/releases\n\n下载对应平台的安装包后，在应用内授权或配置 provider，选择端口并启动服务，再把你的客户端指向应用里显示的本地端点即可。发布版桌面应用使用随包内置的 Electron 运行时，正常使用不需要额外安装 Node.js；token usage 历史记录会在该内置运行时支持 SQLite 时启用。\n\n桌面应用里的高级配置页会通过 `GET/POST /admin/config/model-mappings` 读写这份共享的模型映射。同一份映射会统一作用于 `POST /v1/messages`、`POST /v1/messages/count_tokens`、`POST /v1/responses` 和 `POST /v1/chat/completions`，不再按接口区分。它使用的是 `auth.adminApiKey`，不是普通的 `auth.apiKeys`；应用会在服务启动并自动生成该 key 后，直接从 `config.json` 读取它来发起请求。\n\n### 桌面应用截图\n\n下面展示了桌面应用中的首页、Token 用量统计页面：\n\n<p align=\"center\">\n  <img src=\"./docs/screenshots/desktop-dashboard.png\" alt=\"Copilot API 桌面应用首页\" width=\"49%\" />\n  <img src=\"./docs/screenshots/desktop-token-usage.png\" alt=\"Copilot API 桌面应用 Token 用量页\" width=\"49%\" />\n</p>\n\n## 与 Claude Code 一起使用\n\n这个 AI gateway 可以为 [Claude Code](https://docs.anthropic.com/en/claude-code) 提供后端能力。Claude Code 是 Anthropic 提供的实验性面向开发者的对话式 AI 助手。\n\n有两种方式可以把 Claude Code 配置为使用这个 AI gateway：\n\n### 通过 `--claude-code` 标志进行交互式配置\n\n执行带 `--claude-code` 的 `start` 命令开始：\n\n```sh\nnpx @jeffreycao/copilot-api@latest start --claude-code\n```\n\n你不再需要手动选择模型。Gateway 会自动检测每个 Claude Code 尺寸档位对应的最新可用模型——opus 映射到最新的 Opus 模型，sonnet 映射到最新的 Sonnet 模型，haiku 映射到最新的 Haiku 模型——并生成相应设置 `ANTHROPIC_DEFAULT_OPUS_MODEL`、`ANTHROPIC_DEFAULT_SONNET_MODEL` 和 `ANTHROPIC_DEFAULT_HAIKU_MODEL` 的命令。若某个档位没有匹配的可用模型，则会被省略。该命令会被复制到剪贴板，并设置 Claude Code 使用这个 AI gateway 所需的环境变量。\n\n在新的终端中粘贴并执行这条命令，即可启动 Claude Code。\n\n<a id=\"manual-configuration-with-settingsjson\"></a>\n\n### 通过 `settings.json` 手动配置\n\n另一种方式是在项目根目录中创建 `.claude/settings.json` 文件，并写入 Claude Code 所需的环境变量。这样你就不需要每次都运行交互式配置了。\n\n下面是一个 `.claude/settings.json` 示例：\n\n```json\n{\n  \"env\": {\n    \"ANTHROPIC_BASE_URL\": \"http://localhost:4141\",\n    \"ANTHROPIC_AUTH_TOKEN\": \"dummy\",\n    \"ANTHROPIC_MODEL\": \"codex/gpt-5.6-sol[1m]\",\n    \"ANTHROPIC_DEFAULT_SONNET_MODEL\": \"codex/gpt-5.6-sol[1m]\",\n    \"ANTHROPIC_DEFAULT_HAIKU_MODEL\": \"codex/gpt-5.6-luna[1m]\",\n    \"CLAUDE_CODE_AUTO_COMPACT_WINDOW\": \"272000\",\n    \"CLAUDE_CODE_USE_VERTEX\": \"0\",\n    \"CLAUDE_CODE_USE_BEDROCK\": \"0\",\n    \"DISABLE_NON_ESSENTIAL_MODEL_CALLS\": \"1\",\n    \"CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC\": \"1\",\n    \"CLAUDE_CODE_ATTRIBUTION_HEADER\": \"0\",\n    \"CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION\": \"false\",\n    \"CLAUDE_CODE_DISABLE_TERMINAL_TITLE\": \"true\",\n    \"CLAUDE_CODE_ENABLE_AWAY_SUMMARY\": \"0\"\n  },\n  \"permissions\": {\n    \"deny\": [\n      \"mcp__ide__executeCode\"\n    ]\n  }\n}\n```\n\n- 请根据需要替换 `ANTHROPIC_MODEL`、`ANTHROPIC_DEFAULT_OPUS_MODEL`、`ANTHROPIC_DEFAULT_SONNET_MODEL` 和 `ANTHROPIC_DEFAULT_HAIKU_MODEL`。配置完成后，请安装 claude code 插件，见 [插件集成](#plugin-integrations)。\n- 将 `CLAUDE_CODE_ATTRIBUTION_HEADER` 设为 `0` 可以阻止 Claude Code 在 system prompt 中附加计费和版本信息，从而避免 prompt cache 失效。\n- 关闭 `CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION` 和 `CLAUDE_CODE_ENABLE_AWAY_SUMMARY` 可以避免不必要地消耗额度。\n- Claude Code WebSearch 已支持纯搜索请求。Copilot 路径请保持全局 `messageApiWebSearchModel` 指向 Responses-capable GPT 模型或 `provider/model` 别名；provider 路由请使用原生 Anthropic provider 或 `openai-responses` provider。只有在你明确想禁止这类流量时，才需要把 `WebSearch` 加到 `permissions.deny`。\n- 如果使用的不是 Claude 模型，请不要启用 `ENABLE_TOOL_SEARCH`。如果使用的是 Claude 模型，则可以启用 `ENABLE_TOOL_SEARCH`。当前 Claude Code 使用的是客户端 tool search 模式，在该模式下每次加载 defer tools 都需要额外请求一次。\n- `CLAUDE_CODE_AUTO_COMPACT_WINDOW`：设置用于自动压缩计算的上下文容量（以 token 为单位）。默认使用模型自身的上下文窗口：标准模型为 200K，扩展上下文模型为 1M。使用 1M 上下文模型（如 `claude-opus-4-6[1m]`）时，可设置一个较低的值（如 `500000`）将窗口视为 500K 用于压缩计算。该值受限于模型的实际上下文窗口上限。`CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` 会基于此值的百分比生效。设置此变量可将压缩阈值与状态栏的 `used_percentage` 解耦（后者始终使用模型的完整上下文窗口）。\n\n更多选项见：[Claude Code settings](https://docs.anthropic.com/en/docs/claude-code/settings#environment-variables)\n\n也可以参考 IDE 集成说明：[Add Claude Code to your IDE](https://docs.anthropic.com/en/docs/claude-code/ide-integrations)\n\n## 与 OpenCode 一起使用\n\nOpenCode 已经有直接的 GitHub Copilot provider。本节适用于你希望让 OpenCode 通过 `@ai-sdk/anthropic` 指向这个 AI gateway，并复用本 README 前面提到的 agent 行为时。\n\n### 最小配置\n\n使用 OpenCode OAuth app 启动 AI gateway：\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth --oauth-app=opencode\nnpx @jeffreycao/copilot-api@latest start\n```\n\n然后让 OpenCode 通过 `@ai-sdk/anthropic` 指向这个 AI gateway。\n\n示例 `~/.config/opencode/opencode.json`：\n\n```json\n{\n  \"$schema\": \"https://opencode.ai/config.json\",\n  \"provider\": {\n    \"local\": {\n      \"npm\": \"@ai-sdk/anthropic\",\n      \"name\": \"My Local\",\n      \"options\": {\n        \"baseURL\": \"http://localhost:4141/v1\",\n        \"apiKey\": \"dummy\"\n      },\n      \"models\": {\n        \"gpt-5.4\": {\n          \"name\": \"gpt-5.4\",\n          \"modalities\": {\n            \"input\": [\"text\", \"image\"],\n            \"output\": [\"text\"]\n          },\n          \"limit\": {\n            \"context\": 400000,\n            \"input\": 272000,\n            \"output\": 128000\n          }\n        },\n        \"claude-sonnet-4.6\": {\n          \"id\": \"claude-sonnet-4.6\",\n          \"name\": \"claude-sonnet-4.6\",\n          \"modalities\": {\n            \"input\": [\"text\", \"image\"],\n            \"output\": [\"text\"]\n          },\n          \"limit\": {\n            \"context\": 200000,\n            \"output\": 32000\n          },\n          \"options\": {\n            \"thinking\": {\n              \"type\": \"adaptive\"\n            },\n            \"effort\": \"max\"\n          }\n        }\n      }\n    }\n  }\n}\n```\n\n这些字段的重要性：\n\n- `npm: \"@ai-sdk/anthropic\"` 是关键。OpenCode 会以 Anthropic Messages 语义与这个 AI gateway 通信，而不是把一切扁平化为 OpenAI Chat Completions。\n- `options.baseURL` 应设为 `http://localhost:4141/v1`；Anthropic SDK 会自动补上 `/messages`、`/models` 和 `/messages/count_tokens`。\n- 如果你在此代理中启用了 `auth.apiKeys`，请把 `dummy` 替换为真实 key；否则任意占位值都可以。\n\n## 与 Codex 一起使用\n\n这个 AI gateway 也可以为 Codex 提供后端能力。\n\n### Codex `config.toml` 参考配置\n\n把以下 `[model_providers.copilot_api]` 段加入你的 Codex `~/.codex/config.toml`：\n\n```toml\nmodel_provider = \"copilot_api\"\nmodel_reasoning_summary = \"auto\"\nmodel_context_window = 272000\nmodel_auto_compact_token_limit = 244800\n\n[model_providers.copilot_api]\nname = \"OpenAI\"\nbase_url = \"http://localhost:4141\"\nenv_key = \"GITHUB_COPILOT_API_KEY\"\nrequires_openai_auth = true\nsupports_websockets = false\nwire_api = \"responses\"\nrequest_max_retries = 3\nstream_max_retries = 1\nstream_idle_timeout_ms = 300000\n\n[features]\nremote_compaction_v2 = true\n\n[analytics]\nenabled = false\n```\n\n> [!NOTE]\n> 此配置仅限于 Codex 与 GitHub Copilot provider。`name` 一定要配置为 `\"OpenAI\"`。它可以缓解 Codex local compact 不命中缓存的问题。\n> 如果使用 codex provider，建议将 `base_url` 配置为 `\"http://localhost:4141/codex\"`。\n\n## GPT Tool Search\n\n对于 `gpt-5.4+` 这类 GPT Responses 模型，这个 AI gateway 可以通过一个很小的 MCP bridge 暴露 Responses `tool_search`。Claude Code 和 opencode 都可以使用同一个 bridge，前提是客户端会加载 MCP server，并且 Anthropic Messages 流量会经过这个 AI gateway。\n\nGPT 模型不要设置 Claude Code 原生的 `ENABLE_TOOL_SEARCH`。这个开关启用的是 Claude Code 自己的客户端 tool search 模式，可能导致 deferred 工具定义不再转发给 AI gateway。这个 AI gateway 需要完整的工具定义，这样才能只保留那一小组常驻加载工具，其余工具统一转换为 Responses deferred namespace。\n\n如果你安装了 `tool-search@copilot-api-marketplace`，Claude Code 会自动带上这个 MCP bridge，可以跳过下面这段 Claude Code MCP 手动配置。\n\n请把 tool search bridge 加到 Claude Code 使用的 MCP 配置中：\n\n```json\n{\n  \"mcpServers\": {\n    \"tool_search\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@jeffreycao/copilot-api@latest\", \"mcp\"]\n    }\n  }\n}\n```\n\n请把 tool search bridge 加到 opencode 使用的 MCP 配置中：\n\n```json\n{\n  \"mcp\": {\n    \"tool_search\": {\n      \"type\": \"local\",\n      \"command\": [\"npx\", \"-y\", \"@jeffreycao/copilot-api@latest\", \"mcp\"]\n    }\n  }\n}\n```\n\n本地开发时可以将命令换成 `bun`，参数换成 `[\"run\", \"./src/main.ts\", \"mcp\"]`。\n\nAI gateway 内部现在会把 OpenAI Responses `tool_search` 配置成 client-executed 模式。deferred tools 仍然会作为可搜索 namespace 暴露给模型，但会明确要求模型直接返回下一步要加载的精确工具名列表。\n\n该 bridge 使用直接工具选择，不做 query 搜索。工具入参是 `names`，值为逗号分隔的精确 deferred 工具名，例如 `TaskList,TaskGet,mcp__fetch__fetch`。\n\n<a id=\"plugin-integrations\"></a>\n\n## 插件集成\n\n本项目为 Claude Code 和 opencode 提供了插件集成。\n\n#### Claude Code 插件集成（基于 marketplace）\n\nClaude Code 集成现在拆分为两个插件：\n\n- `agent-inject` 会在 `SubagentStart` 时注入 `__SUBAGENT_MARKER__...`，以便 AI gateway 推导 `x-initiator: agent`。\n- `tool-search` 会注册用于 GPT Responses deferred tool loading 的 `tool_search` MCP bridge。\n\n- 本仓库中的 marketplace catalog：`.claude-plugin/marketplace.json`\n- 本仓库中的插件源码：`plugin/claude/agent-inject`、`plugin/claude/tool-search`\n\n远程添加 marketplace：\n\n```sh\n/plugin marketplace add https://github.com/caozhiyuan/copilot-api.git\n```\n\n从 marketplace 安装插件：\n\n```sh\n/plugin install agent-inject@copilot-api-marketplace\n/plugin install tool-search@copilot-api-marketplace\n```\n\n安装后，`agent-inject` 会在 `SubagentStart` 时注入 `__SUBAGENT_MARKER__...`，AI gateway 会利用它推导 `x-initiator: agent`。\n\n`agent-inject` 还会注册一个 `UserPromptSubmit` hook，并返回 `{\"continue\": true}`；同时它也可以通过环境变量注入 `SessionStart` reminder 规则：\n\n- `CLAUDE_PLUGIN_ENABLE_QUESTION_RULES=1` 会自动为 Claude Code 启用两条关于使用 `question` 工具的提醒。你也可以把同样的提醒手动写进 `CLAUDE.md`；见 [CLAUDE.md 或 AGENTS.md 推荐内容](#claudemd-or-agentsmd-recommended-content)。\n- `CLAUDE_PLUGIN_ENABLE_NO_BACKGROUND_AGENTS_RULE=1` 会启用关于避免在 agent hooks 中使用 `run_in_background: true` 的提醒。\n\n`tool-search` 插件内置了 [GPT Tool Search](#gpt-tool-search) 一节描述的同一个 MCP bridge，因此安装该插件后，Claude Code 用户无需再手动配置 `tool_search` server。\n\n#### Opencode 插件\n\nsubagent 标记生成器被打包为一个 opencode 插件，位于 `plugin/opencode/subagent-marker.js`。\n\n**安装方式：**\n\n将插件文件复制到你的 opencode 插件目录：\n\n```sh\n# 克隆或下载本仓库后复制该插件\ncp plugin/opencode/subagent-marker.js ~/.config/opencode/plugins/\n```\n\n或者手动在 `~/.config/opencode/plugins/subagent-marker.js` 创建该文件，并填入插件内容。\n\n**功能：**\n\n- 跟踪 subagent 创建的子会话\n- 自动在 subagent 聊天消息前添加 marker system reminder（`__SUBAGENT_MARKER__...`）\n- 设置 `x-session-id` 请求头以跟踪会话\n- 让这个 AI gateway 能够把来自 subagent 的请求识别为 `x-initiator: agent`\n\n该插件会挂接到 `session.created`、`session.deleted`、`chat.message` 和 `chat.headers` 事件上，以无缝提供 subagent marker 能力。\n\n## 使用量查看器\n\n服务启动后，控制台会输出一个 Copilot 使用量看板 URL。这个看板是一个用于监控 API 用量的 Web 界面。\n\n1. 启动服务。例如使用 npx：\n   ```sh\n   npx @jeffreycao/copilot-api@latest start\n   ```\n2. 服务会输出一个 usage viewer 的 URL。将它复制到浏览器中打开，形式大致如下：\n   `http://localhost:4141/usage-viewer?endpoint=http://localhost:4141/usage`\n   - 如果你在 Windows 上使用 `start.bat` 脚本，这个页面会自动打开。\n\n看板提供了更易读的 Copilot 用量视图：\n\n> token usage 历史记录需要 Bun 或 Node.js >= 22.13.0。Node.js < 22.13.0 时服务会正常运行，但 token usage 存储会被禁用。\n\n- **API Endpoint URL**：通过 URL 查询参数指定 API endpoints，默认指向本地服务。支持手动切换为其他兼容 endpoints。\n- **x-api-key 认证**：如果启用了 API Key 认证，可填入 `x-api-key` 请求头。密钥会持久化保存在浏览器本地存储中。\n- **Period 选择器**：支持 Day / Week / Month 三种时间范围，切换时 URL 参数会自动同步，方便收藏和分享。\n- **Fetch Data**：点击 \"Refresh\" 按钮加载或刷新使用数据。页面加载时也会自动拉取数据。\n- **Copilot Quotas 额度**：通过进度条展示 Chat、Completions 等不同服务的额度使用情况，悬停可查看已用/剩余详情。\n- **Token Usage 指标卡片**：汇总当前周期的 Total、Input、Output、Cache Read、Cache Write、Requests 和预估费用。\n- **趋势图（Week / Month）**：提供按模型和指标筛选的折线趋势图，点击数据点可查看单日用量明细。\n- **Model Breakdown 表格**：按模型维度列出周期内的请求数、输入/输出/缓存 token 和预计费用。\n- **Request Events 分页列表**：按时间排序的请求事件记录，支持分页浏览，含时间戳、模型、请求 ID 和 token 用量。\n- **Detailed Information**：展示 API 返回的完整 JSON 响应，便于深入分析所有可用统计数据。\n- **URL-based Configuration**：也可通过 `endpoint` 和 `period` 查询参数直接指定 API 端点与时间范围。例如：\n  `http://localhost:4141/usage-viewer?endpoint=http://your-api-server/usage&period=week`\n\n### Usage Viewer 截图\n\n<p align=\"center\">\n  <img src=\"./docs/screenshots/usage-viewer.png\" alt=\"Copilot API Usage Viewer 页面\" width=\"900\" />\n</p>\n\n## 命令结构\n\nCopilot API 现在使用子命令结构，主要命令包括：\n\n- `start`：启动 AI gateway 服务。如果已有 GitHub token，则启用 Copilot 路径；如果没有 GitHub token，但存在至少一个启用中的 provider，则按 provider-only 模式启动；如果两者都没有，会引导你配置 provider。\n- `auth`：仅执行 provider 登录或配置流程，不启动服务。可用于 GitHub Copilot 登录、Codex OAuth，或第三方 provider API key 配置。\n- `debug`：显示诊断信息，包括版本、运行时详情、文件路径以及认证状态，便于排障与支持。\n\n## 命令行选项\n\n### 全局选项\n\n以下选项可用于任意子命令。若在子命令之前传入，请使用 `--key=value` 形式：\n\n| 选项 | 说明 | 默认值 | 别名 |\n| --- | --- | --- | --- |\n| --api-home | API home 目录路径（设置 `COPILOT_API_HOME`） | 无 | 无 |\n| --oauth-app | OAuth app 标识符（设置 `COPILOT_API_OAUTH_APP`） | 无 | 无 |\n| --enterprise-url | GitHub Enterprise URL（设置 `COPILOT_API_ENTERPRISE_URL`） | 无 | 无 |\n\n### Start 命令选项\n\n以下是 `start` 命令可用的命令行选项：\n\n| 选项 | 说明 | 默认值 | 别名 |\n| --- | --- | --- | --- |\n| --port | 监听端口 | 4141 | -p |\n| --verbose | 启用详细日志 | false | -v |\n| --github-token | 直接提供 GitHub token（必须通过 `auth` 子命令生成） | 无 | -g |\n| --claude-code | 生成一个使用 Copilot API 配置启动 Claude Code 的命令 | false | -c |\n| --show-token | 在获取和刷新时显示 GitHub 与 Copilot token | false | 无 |\n| --proxy-env | 从环境变量初始化代理 | false | 无 |\n\n### Auth 命令选项\n\n| 选项 | 说明 | 默认值 | 别名 |\n| --- | --- | --- | --- |\n| --provider | 要登录或配置的 provider（`copilot`、`codex`、`opencode-go`、`deepseek`、`dashscope`、`openrouter` 或 `custom`） | 交互选择 | 无 |\n| --verbose | 启用详细日志 | false | -v |\n| --show-token | 认证时显示 GitHub token | false | 无 |\n\n只有在需要启用 GitHub Copilot provider 时，才需要执行 `copilot-api auth login --provider copilot`。使用 `codex` 或第三方 provider-only 模式不要求配置 Copilot。\n\n使用 `copilot-api auth login --provider deepseek`、`--provider dashscope`、`--provider openrouter` 或 `--provider opencode-go` 可以通过 CLI 快速新增或更新这些常用第三方 provider。DeepSeek 会提示输入掩码显示的 `apiKey`、provider `type`（默认 `anthropic`），以及默认 `https://api.deepseek.com/anthropic` 的 `baseUrl`。DashScope 会提示输入掩码显示的 `apiKey`、provider `type`（默认 `openai-compatible`）和预填默认值的 `baseUrl`。OpenRouter 只提示输入掩码显示的 `apiKey` 和预填默认值的 `baseUrl`，并固定写入 `type: \"anthropic\"`。OpenCode Go 只提示输入掩码显示的 `apiKey` 和预填默认值的 `baseUrl`，并固定写入 `type: \"openai-compatible\"`（baseUrl `https://opencode.ai/zen/go`）。配置并启用 provider 后，`copilot-api start` 可在没有 GitHub token 的情况下启动。\n\n使用 `copilot-api auth login --provider custom` 可以通过 CLI 新增或更新其他第三方 provider。命令会依次提示输入 provider name、项目支持的 type（`anthropic`、`openai-compatible` 或 `openai-responses`）、`baseUrl`、掩码显示的 `apiKey` 和 `authType`；`authType` 可保持 type 默认值，也可选择 `x-api-key` / `authorization`。\n\n### Debug 命令选项\n\n| 选项 | 说明 | 默认值 | 别名 |\n| --- | --- | --- | --- |\n| --json | 以 JSON 输出调试信息 | false | 无 |\n\n<a id=\"configuration-configjson\"></a>\n\n## 配置（config.json）\n\n- **位置：** Linux/macOS 为 `~/.local/share/copilot-api/config.json`，Windows 为 `%USERPROFILE%\\.local\\share\\copilot-api\\config.json`。\n- **默认结构：**\n  ```json\n  {\n    \"auth\": {\n      \"apiKeys\": [],\n      \"adminApiKey\": \"<startup 自动生成>\"\n    },\n    \"providers\": {},\n    \"modelMappings\": {},\n    \"extraPrompts\": {\n      \"gpt-5-mini\": \"<built-in exploration prompt>\"\n    },\n    \"smallModel\": \"gpt-5-mini\",\n    \"contextManagement\": {\n      \"messages\": true,\n      \"responses\": false\n    },\n    \"modelResponsesApiCompactThresholds\": {\n      \"gpt-5.4\": 217600,\n      \"gpt-5.5\": 217600,\n      \"gpt-5.6-sol\": 231200,\n      \"gpt-5.6-terra\": 231200,\n      \"gpt-5.6-luna\": 231200\n    },\n    \"modelReasoningEfforts\": {\n      \"gpt-5-mini\": \"low\"\n    },\n    \"useMessagesApi\": true,\n    \"useResponsesApiWebSocket\": true,\n    \"useResponsesApiWebSearch\": true,\n    \"messageApiWebSearchModel\": \"gpt-5-mini\"\n  }\n  ```\n- **auth.apiKeys：** 用于普通非 admin 路由的 API key。支持多个 key 轮换使用。请求可通过 `x-api-key: <key>` 或 `Authorization: Bearer <key>` 进行认证。若为空或省略，则普通路由的认证会被禁用。\n- **auth.adminApiKey：** 仅用于 `/admin/*` 路由的单个 admin key。若未配置，服务会在启动时自动生成一个随机 key，并回写到 `config.json`。它同样使用 `x-api-key` 或 `Authorization: Bearer` 这两种头，但普通 `auth.apiKeys` 不能访问 `/admin/*`。\n- **modelMappings：** 用于顶层 `POST /v1/messages`、`POST /v1/messages/count_tokens`、`POST /v1/responses` 和 `POST /v1/chat/completions` 请求的精确 `sourceModel -> targetModel` 重写映射，这几类接口共用同一份规则。省略该字段或保留为 `{}` 时，不会做模型重写。`source` 和 `target` 都必须是非空字符串。`target` 可以是普通模型 ID，也可以是 `provider/model` 形式的别名，例如 `dashscope/qwen3.6-plus`；重写发生在 provider alias 解析之前。这些映射不再按接口区分。`GET/POST /admin/config/model-mappings` 管理接口读写的也只有这个字段。\n- **extraPrompts：** `model -> prompt` 的映射。把 Anthropic 风格请求翻译为 Responses API 时，会将其附加到第一条 system prompt 后面。你可以借此为不同模型注入护栏或指引。缺失的默认项会自动补齐，但不会覆盖你自定义的 prompt。对于 GPT-5.3+ 模型（如 `gpt-5.3-codex`、`gpt-5.4`、`gpt-5.5`），未显式配置时会自动使用内置的 commentary prompt。内置 prompt 会启用带阶段感知的 commentary，让模型在工具调用或更深层推理前先发出简短的用户可见进度说明。\n- **providers：** 全局上游 provider 映射。每个 provider key（例如 `dashscope`）都会变成一个路由前缀（`/dashscope/v1/messages`）。支持 `type: \"anthropic\"`、`type: \"openai-compatible\"` 和 `type: \"openai-responses\"`。顶层客户端也可以在 `/v1/messages`、`/v1/messages/count_tokens`、`/v1/responses` 和 `/v1/chat/completions` 中使用 `model: \"dashscope/model-id\"`；AI gateway 会在转发上游前移除 `dashscope/` 前缀。`openai-compatible` provider 同时支持 chat 和 Messages 流程：`/v1/chat/completions` 会直连上游 `/v1/chat/completions`，而 `/v1/messages` 和 `/:provider/v1/messages` 会先翻译为上游 Chat Completions，再把响应翻译回 Anthropic Messages。`GET /v1/models` 会聚合已启用 provider 的模型，并以 `provider/model-id` 形式返回；单个 provider 的原始模型列表仍可使用 `GET /dashscope/v1/models`。\n  - `enabled`：可选，若省略则默认为 `true`。\n  - `baseUrl`：provider API 的基础 URL，不要带结尾的 endpoint。Anthropic provider 不要带 `/v1/messages`；OpenAI 兼容 provider 不要带 `/v1/chat/completions`；OpenAI Responses provider 不要带 `/v1/responses`。\n  - `apiKey`：作为上游凭据值使用；普通 provider 必须配置。\n  - `authType`：可选，控制 `apiKey` 如何发送到上游。普通 provider 支持 `x-api-key` 和 `authorization`。Anthropic provider 默认 `x-api-key`；OpenAI 兼容和 OpenAI Responses provider 默认 `authorization`。当设置为 `authorization` 时，代理会发送 `Authorization: Bearer <apiKey>`。`oauth2` 仅保留给内置 `codex` provider，并由 `auth login --provider codex` 自动写入。\n  - `pricingCurrency`：可选，provider 维度的 token 费用币种，例如 `USD` 或 `CNY`。快捷 provider 默认 DashScope、DeepSeek 为 `CNY`，Codex/OpenRouter 为 `USD`。费用按币种分别汇总，不做汇率换算。\n  - `models`：可选，按模型 ID 配置的映射。每个键为请求中的模型名，值支持：\n    - `temperature`：可选，当请求未指定时使用的默认温度。\n    - `topP`：可选，当请求未指定时使用的默认 `top_p`。\n    - `topK`：可选，当请求未指定时使用的默认 `top_k`。\n    - `extraBody`：可选，按模型合入上游请求体的动态字段；请求体显式同名字段优先。OpenAI 兼容 provider 可用它配置 `enable_thinking`、`preserve_thinking`、`reasoning_effort` 等字段。`thinking_budget` 是 OpenAI 兼容 provider 的特殊覆盖项：配置在 `extraBody` 后，会在 Anthropic `thinking.budget_tokens` 翻译之后强制写入，并覆盖请求派生出的预算值。对于 provider name 为 `dashscope` 或 `baseUrl` 包含 `aliyuncs.com` 的 provider，请求派生的 `thinking_budget`（来自 Anthropic `thinking.budget_tokens`）会转发给上游；其他 OpenAI 兼容 provider 会移除请求派生的 `thinking_budget`，但 `extraBody` 中的 `thinking_budget` 仍然生效。对于 DashScope provider，当 `preserve_thinking` 未在 `extraBody` 或请求体中显式设置时，默认为 `true`。\n    - `pricing`：可选，按模型配置 token 单价，币种使用 provider 的 `pricingCurrency`，单位为每 100 万 tokens。支持 `input`、`output`、`cachedInput`（隐式缓存读）、`explicitCachedInput`（显式缓存读）和 `cacheCreationInput`。如需按输入 token 总量分档，可用带 `maxInputTokens` 的 `tiers`。\n    - `contextCache`：可选，provider name 为 `dashscope` 或 `baseUrl` 包含 `aliyuncs.com` 时默认 `true`，其他 OpenAI 兼容 provider 默认 `false`。用于启用阿里云百炼/DashScope 的显式缓存（explicit context cache），会按其 Context Cache 格式在最多 4 个 content block 上注入 `cache_control: { \"type\": \"ephemeral\" }`。缓存断点策略与 opencode 主链路保持一致：前 2 条 system 消息 + 最后 2 条非 system 消息。标记字符串 content 时会把 `system` / `user` / `assistant` / `tool` 消息转换为 text content part 数组；已有数组 content 则标记最后一个 part。如果模型本身已经支持隐式缓存，或上游不支持该显式缓存扩展字段，可在模型配置中设为 `false`。支持相同显式缓存扩展的非 DashScope provider 可设为 `true`。同时适用于 `/v1/messages` 和 `/v1/chat/completions` 路由。\n    - `supportPdf`：可选，控制该模型是否支持 PDF/document content。默认 `false`，不支持时会把 PDF 转成提示文本；设为 `true` 时会把 PDF/document 转成 OpenAI Chat Completions 的 file part。\n    - `toolContentSupportType`：可选，配置该模型的 tool result content 支持能力，值为 `array`、`image`、`pdf` 的数组。provider 侧未配置时默认只发送 string tool content。若 `supportPdf` 为 `true` 但这里不包含 `pdf`，tool result 里的 file part 会被转成 user role 消息。Copilot 主链路不使用这个 provider 默认，仍按 array + image 且不支持 PDF 的能力处理。\n    - `type`：可选，按模型覆盖 provider 的协议类型。支持 `anthropic`、`openai-compatible` 和 `openai-responses`。设置后，provider 的 `/v1/messages` 路由会使用该模型的 type 替代 provider 级别的 type 进行请求路由、认证头解析和上游端点选择。适用于 OpenCode Go 等上游对不同模型同时支持 OpenAI 兼容和 Anthropic Messages API 的 provider。覆盖 type 时，认证头按覆盖后 type 的默认值解析（Anthropic 默认 `x-api-key`；OpenAI 兼容/Responses 默认 `authorization`）。\n\n  DashScope 模型配置示例：\n  ```json\n  {\n    \"providers\": {\n      \"dashscope\": {\n        \"type\": \"openai-compatible\",\n        \"enabled\": true,\n        \"baseUrl\": \"https://dashscope.aliyuncs.com/compatible-mode\",\n        \"apiKey\": \"sk-your-dashscope-key\",\n        \"pricingCurrency\": \"CNY\",\n        \"models\": {\n          \"qwen3.7-plus\": {\n            \"temperature\": 1,\n            \"topP\": 0.95,\n            \"topK\": 20,\n            \"extraBody\": {\n              \"preserve_thinking\": true\n            }\n          },\n          \"glm-5.1\": {\n            \"temperature\": 0.7,\n            \"topP\": 0.95,\n            \"contextCache\": true,\n            \"pricing\": {\n              \"tiers\": [\n                {\n                  \"maxInputTokens\": 32000,\n                  \"input\": 6,\n                  \"cachedInput\": 1.2,\n                  \"explicitCachedInput\": 0.6,\n                  \"cacheCreationInput\": 7.5,\n                  \"output\": 24\n                },\n                {\n                  \"maxInputTokens\": 200000,\n                  \"input\": 8,\n                  \"cachedInput\": 1.6,\n                  \"explicitCachedInput\": 0.8,\n                  \"cacheCreationInput\": 10,\n                  \"output\": 28\n                }\n              ]\n            },\n            \"extraBody\": {\n              \"preserve_thinking\": true\n            }\n          }\n        }\n      }\n    }\n  }\n  ```\n  内置 token 价格覆盖 Codex GPT 模型（USD）、DashScope `qwen3.7-max`、`qwen3.7-plus`、`glm-5.1`、`glm-5.2`（CNY），DeepSeek `deepseek-v4-flash`、`deepseek-v4-pro`、`deepseek-chat`、`deepseek-reasoner`（CNY），以及 OpenCode Go 模型（`glm-5.2`、`grok-4.5`、`deepseek-v4-flash`、`deepseek-v4-pro`、`kimi-k2.7-code`、`kimi-k3`、`mimo-v2.5`、`mimo-v2.5-pro`、`qwen3.7-plus`、`qwen3.7-max`、`minimax-m2.5`、`minimax-m3`，USD）。用户配置的 `pricing` 优先于内置价格。DashScope 若上游 usage 中出现 `cache_creation_input_tokens` 字段，cached tokens 按显式缓存读价计费；否则 `cachedInput` 作为隐式缓存读价。DeepSeek 的 `prompt_cache_hit_tokens` 会归入 cached input，`prompt_cache_miss_tokens` 会归入普通 input。\n- **smallModel：** 无工具预热消息的回退模型（例如 Claude Code 的探测请求）；默认是 `gpt-5-mini`。\n- **contextManagement：** 控制代理是否为 Responses API 附加 `context_management` 压缩指令。`messages` 作用于被翻译成 Responses API 的 Anthropic 风格 `/v1/messages` 请求，包括 `openai-responses` provider 的 Messages 路由，默认值为 `true`。`responses` 作用于 native `/v1/responses` 流量，包括 `provider/model` 别名和内置 `codex` provider，默认值为 `false`。只有在确认客户端支持 context management compaction 后，才建议在 Responses API 下启用 `responses`。启用后，请求体会带上 `context_management`，并在后续轮次中仅保留最新的压缩承载内容。**注意：** 对于 GPT-5.6 及以上模型（如 `gpt-5.6-sol`、`gpt-5.6-terra`、`gpt-5.6-luna`），context management 功能会被强制禁用，因为开启后会破坏这些模型的 prompt 缓存命中。此强制覆盖优先于 `contextManagement` 和 `modelResponsesApiCompactThresholds` 配置。\n- **modelResponsesApiCompactThresholds：** 按模型覆盖 Responses API 的 `compact_threshold`，仅在代理自动附加 `context_management` 时使用。它的优先级高于 `resolveResponsesCompactThreshold` 基于 `max_prompt_tokens * ratio` 的兜底阈值。默认将 `gpt-5.4` 和 `gpt-5.5` 设为 `217600`（`272000 * 0.8`），将 `gpt-5.6-sol`、`gpt-5.6-terra`、`gpt-5.6-luna` 设为 `231200`（`272000 * 0.85`）。未列出的模型继续使用原有兜底逻辑。\n- **modelReasoningEfforts：** `/v1/messages` 请求的模型级默认推理强度。仅当请求没有传入 `output_config.effort` 时，该配置才会生效。\n  - **优先级：** 请求中的 `output_config.effort` > `modelReasoningEfforts[model]` > 内置默认值（GPT-5.3+ 模型为 `xhigh`，其他模型为 `high`）。\n  - **转发字段：** 走 Copilot 原生 Messages API 时，最终值写入 `output_config.effort`；转换为 Responses API 时，最终值写入 `reasoning.effort`。\n  - **配置可选值：** `none`、`minimal`、`low`、`medium`、`high`、`xhigh`、`max`。\n- **useMessagesApi：** 当为 `true` 时，支持 Copilot 原生 `/v1/messages` 的 Claude 系模型会走 Messages API；否则回退到 `/chat/completions`。设为 `false` 可禁用 Messages API 路由，始终使用 `/chat/completions`。默认值为 `true`。\n- **useResponsesApiWebSocket：** 当为 `true` 时，Responses API 请求会优先对声明了 `ws:/responses` 的模型使用 Copilot websocket transport；仅声明 `/responses` 的模型仍走 HTTP。设为 `false` 可禁用 websocket 路由，并在模型支持 `/responses` 时使用 HTTP `/responses`。默认值为 `true`。如果遇到 Responses API WebSocket closed，一般是自己的网络问题。如果使用了 VPN，建议切换节点。\n- **useResponsesApiWebSearch：** 当为 `true` 时，服务端会保留 Responses API 中 `type: \"web_search\"` 的工具并透传到上游。设为 `false` 则会从 `/responses` payload 中移除这些工具。默认值为 `true`。\n- **messageApiWebSearchModel：** 顶层 Copilot `/v1/messages` 请求只包含服务端 `web_search` 工具时使用的全局模型，默认值为 `gpt-5-mini`。如果该值是 `provider/model` 别名，请求会进入对应 provider 的 Messages API 路径，并在转发前移除 provider 前缀。对于 Copilot GPT 模型，web search 会通过 `/responses` 执行。混合 `web_search` 与自定义工具的场景暂不支持，服务端会移除 server-side `web_search`。\n- **claudeTokenMultiplier：** 用于 Claude `/v1/messages/count_tokens` 请求在本地走 GPT tokenizer 估算时的乘数。默认值为 `1.15`。如果你的客户端仍然过晚触发上下文压缩，可以适当调大。这个配置只会在代理本地估算 Claude token 时生效；如果已经配置 `anthropicApiKey` 且 Anthropic token counting 调用成功，则会直接返回 Anthropic 的精确计数，不会使用这个乘数。\n- **anthropicApiKey：** 用于把 Claude `/v1/messages/count_tokens` 请求转发到 Anthropic 真实 token counting 端点的 API key，这样会返回精确计数，而不是 GPT tokenizer 估算值。也可通过环境变量 `ANTHROPIC_API_KEY` 设置。若未配置，或上游调用失败，则回退到由 `claudeTokenMultiplier` 控制的本地 GPT tokenizer 估算。\n\n编辑此文件后即可自定义 prompts，或替换为你自己的快速模型。修改完成后请重启服务（或重新执行命令），让缓存中的配置刷新生效。\n\n## API 认证\n\n- **受保护的普通路由：** 当配置了 `auth.apiKeys` 且非空时，除 `/`、`/usage-viewer` 和 `/usage-viewer/` 以外的普通路由都需要认证。\n- **Admin 路由：** 所有 `/admin/*` 路由都要求 `auth.adminApiKey`。如果缺失，服务会在启动时自动生成并在开始提供服务前写回 `config.json`。\n- **允许的认证头：**\n  - `x-api-key: <your_key>`\n  - `Authorization: Bearer <your_key>`\n- **CORS 预检：** `OPTIONS` 请求始终允许。\n- **未配置普通 key 时：** 普通路由仍可直接访问；但这条规则不适用于 `/admin/*`，后者只接受 `auth.adminApiKey`。\n\n普通受保护路由的示例请求：\n\n```sh\ncurl http://localhost:4141/v1/models \\\n  -H \"x-api-key: your_api_key\"\n```\n\nAdmin 路由的示例请求：\n\n```sh\ncurl http://localhost:4141/admin/config/model-mappings \\\n  -H \"x-api-key: your_admin_api_key\"\n```\n\n## API 端点\n\n服务端提供多个 OpenAI / Anthropic 兼容端点。请求会根据所选模型和 `provider/model` 别名路由到 GitHub Copilot、内置 `codex` provider 或已配置的 provider。\n\n### OpenAI 兼容端点\n\n这些端点模拟 OpenAI API 结构。\n\n| 端点 | 方法 | 说明 |\n| --- | --- | --- |\n| `POST /v1/responses` | `POST` | OpenAI 中用于生成模型响应的高级接口。支持 `openai-responses` provider 的 `provider/model` 别名。 |\n| `POST /v1/chat/completions` | `POST` | 为给定聊天对话创建模型响应。支持 `openai-compatible` provider 的 `provider/model` 别名；目标 provider 已配置时可在没有 Copilot 的情况下使用。 |\n| `GET /v1/models` | `GET` | 列出 Copilot 模型以及已启用 provider 的 `provider/model-id` 模型。来自 Codex 客户端（`User-Agent` 以 `codex` 开头）的请求会转发到 Codex Models 上游。 |\n| `POST /v1/embeddings` | `POST` | 创建表示输入文本的向量嵌入。 |\n\n### Codex 后端代理端点\n\n这些端点要求已有可用的 Codex 登录态。每个端点同时提供无版本前缀和 `/v1` 两种路径。\n\n| 端点 | 方法 | 说明 |\n| --- | --- | --- |\n| `POST /alpha/search`<br>`POST /v1/alpha/search` | `POST` | 将 JSON 请求体和查询参数透明转发到 Codex Alpha Search 上游。 |\n| `POST /images/generations`<br>`POST /v1/images/generations` | `POST` | 将 JSON 图片生成请求转发到 Codex Images 上游。请求未携带 `Content-Type` 时，网关默认补充 `application/json`。 |\n| `POST /images/edits`<br>`POST /v1/images/edits` | `POST` | 将图片编辑请求转发到 Codex Images 上游。请使用 `multipart/form-data`，并让 HTTP 客户端自动生成 `boundary`；网关会保留传入的 content type，并以流式方式转发上传请求体。 |\n\n对于以上所有端点，网关都会使用当前 Codex 登录态覆盖客户端的 authorization 和 account header，保留查询参数及兼容的请求头，并返回上游状态码、响应头和响应体。\n\n### Anthropic 兼容端点\n\n这些端点设计为兼容 Anthropic Messages API。provider 级的 models、Responses、alpha-search 和 images 路由同时支持无版本前缀与 `/v1` 两种路径；Messages 路由仍使用 `/v1`。\n\n| 端点 | 方法 | 说明 |\n| --- | --- | --- |\n| `POST /v1/messages` | `POST` | 为给定对话创建模型响应。支持已配置 provider 的 `provider/model` 别名，包括通过 `openai-compatible` provider 做翻译。 |\n| `POST /v1/messages/count_tokens` | `POST` | 计算一组消息的 token 数。支持已配置 provider 的 `provider/model` 别名。 |\n| `POST /:provider/v1/messages` | `POST` | 将 Anthropic Messages 请求代理到已配置的 Anthropic provider，或翻译到 OpenAI 兼容 / OpenAI Responses provider。 |\n| `GET /:provider/models`<br>`GET /:provider/v1/models` | `GET` | 将模型列表请求代理到已配置的 provider。对 `codex` 默认返回内置模型目录；Codex 客户端（`User-Agent` 以 `codex` 开头）会转发到 Codex Models 上游。 |\n| `POST /:provider/v1/messages/count_tokens` | `POST` | 为 provider 路由请求在本地计算 token 数。 |\n| `POST /:provider/responses`<br>`POST /:provider/v1/responses` | `POST` | 将 OpenAI Responses 请求代理到已配置的 `openai-responses` provider（含 `codex`）。 |\n| `POST /:provider/alpha/search`<br>`POST /:provider/v1/alpha/search` | `POST` | 代理 alpha-search 请求。对 `codex` 转发到 Codex Alpha Search 上游；其他 provider 转发到 `{baseUrl}/v1/alpha/search`。 |\n| `POST /:provider/images/generations`<br>`POST /:provider/v1/images/generations` | `POST` | 代理图片生成。对 `codex` 使用 Codex Images 上游；其他 provider 转发到 `{baseUrl}/v1/images/generations`（15 分钟超时）。 |\n| `POST /:provider/images/edits`<br>`POST /:provider/v1/images/edits` | `POST` | 代理图片编辑。对 `codex` 使用 Codex Images 上游；其他 provider 以 multipart/流式方式转发到 `{baseUrl}/v1/images/edits`（15 分钟超时）。 |\n\n### 使用量监控端点\n\n用于监控 Copilot 用量与额度的新端点。\n\n| 端点 | 方法 | 说明 |\n| --- | --- | --- |\n| `GET /usage` | `GET` | 获取详细的 Copilot 使用统计与额度信息。 |\n| `GET /token` | `GET` | 获取当前 API 正在使用的 Copilot token。 |\n\n### Admin / 配置端点\n\n这些端点用于本地管理操作，只接受 `auth.adminApiKey`。\n\n| 端点 | 方法 | 说明 |\n| --- | --- | --- |\n| `GET /admin/config/model-mappings` | `GET` | 返回当前 `config.json` 路径以及生效中的 `modelMappings` 映射。 |\n| `POST /admin/config/model-mappings` | `POST` | 只更新 `config.json` 里的 `modelMappings` 字段，并回传更新后的结果。 |\n\n## 使用示例\n\n常用 `npx` 命令：\n\n```sh\n# 基础启动\nnpx @jeffreycao/copilot-api@latest start\n\n# 自定义端口并开启详细日志\nnpx @jeffreycao/copilot-api@latest start --port 8080 --verbose\n\n# 执行认证流程\nnpx @jeffreycao/copilot-api@latest auth login\n\n# 配置第三方 provider，然后不依赖 GitHub Copilot 启动\nnpx @jeffreycao/copilot-api@latest auth login --provider dashscope\nnpx @jeffreycao/copilot-api@latest start\n\n# 以 JSON 格式输出调试信息\nnpx @jeffreycao/copilot-api@latest debug --json\n\n# 用 Bun 而不是 Node.js 运行已发布 CLI\nbunx --bun @jeffreycao/copilot-api@latest start\n```\n\n配置 `dashscope` 后的 OpenAI 兼容 provider 调用示例：\n\n```sh\ncurl http://localhost:4141/v1/chat/completions \\\n  -H \"content-type: application/json\" \\\n  -d '{\"model\":\"dashscope/qwen3.6-plus\",\"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]}'\n\ncurl http://localhost:4141/dashscope/v1/messages \\\n  -H \"content-type: application/json\" \\\n  -d '{\"model\":\"qwen3.6-plus\",\"max_tokens\":1024,\"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]}'\n```\n\n## 使用建议\n\n<a id=\"claudemd-or-agentsmd-recommended-content\"></a>\n\n### CLAUDE.md 或 AGENTS.md 推荐内容\n\n如果你想手动加入这些提醒，请在 Claude Code 的 `CLAUDE.md`，或 opencode/codex 的 `AGENTS.md` 中加入以下内容：\n\n```\n- Prohibited from directly asking questions to users, MUST use question tool.\n- Once you can confirm that the task is complete, MUST use question tool to make user confirm. The user may respond with feedback if they are not satisfied with the result, which you can use to make improvements and try again, after try again, MUST use question tool to make user confirm again.\n```\n"}, "1043f72adafc89638932face4e837f7606e93a3e": {"t": 1785765546.387626, "n": 33389, "h": "dceb0500b96f356b", "c": "# Copilot API Proxy\n\n[English](./README.md) | 简体中文\n\n## 重要说明\n\n> [!IMPORTANT]\n> **使用前请先注意以下几点：**\n>\n> 1. **Claude Code 配置：** 与 Claude Code 搭配使用时，请将模型 ID 配置为 `claude-opus-4-8`。示例 claude `settings.json` 见 [通过 `settings.json` 手动配置](#manual-configuration-with-settingsjson)。\n>\n> 2. **内置 `copilot`、`codex` 与第三方 provider：** 执行 `npx @jeffreycao/copilot-api@latest auth`，可选择 `copilot`、`codex`、`deepseek`、`custom` 等 provider。\n>\n> 3. **注意事项：** README 顶部移除的 GitHub Copilot warning 见 [GitHub Copilot 安全提示](./NOTICE.md#github-copilot-security-notice)。\n\n---\n\n## 项目概览\n\n这是一个小型 AI gateway，可以使用 GitHub Copilot、内置 `codex` provider，也可以使用 DashScope 等已配置的第三方 provider。GitHub Copilot 现在是可选能力：如果本地没有 GitHub token，只要至少配置了一个启用中的 provider，服务仍可按 provider-only 模式启动。\n\nAI gateway 会从同一个本地端点暴露 OpenAI / Anthropic 兼容 API，让 [Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview)、OpenCode、Codex 和 OpenAI 兼容客户端可以共用同一个本地服务。\n\n在 GitHub Copilot 路径上，AI gateway 会在可用时优先使用 Copilot 原生的 Anthropic 风格 Messages API，在重工具调用场景下保留更原生的 Claude 行为。\n\n## 功能特性\n\n- **OpenAI 与 Anthropic 双兼容**：通过 `/v1/responses`、`/v1/chat/completions`、`/v1/models`、`/v1/embeddings` 和 `/v1/messages` 对外暴露同一个本地 AI gateway。\n- **Copilot 可选**：有 GitHub 凭据时可以使用 GitHub Copilot，没有 GitHub 凭据时也可以只依赖已配置的 provider 运行。\n- **同一网关接入 Copilot、`codex` 与第三方 provider**：可统一路由 GitHub Copilot、内置 `codex` provider 和配置好的外部 provider。\n- **第三方 provider 可独立启动**：配置 DashScope、DeepSeek、OpenRouter 或自定义 provider 后，不需要 GitHub Copilot 登录即可启动 AI gateway。\n- **OpenAI 兼容 provider 同时支持 chat 和 Messages API**：`openai-compatible` provider 可通过顶层 `/v1/chat/completions` 搭配 `model: \"provider/model\"` 提供 Chat Completions，也可通过 `/v1/messages` 完成 Anthropic Messages 的请求/响应翻译。\n- **面向 Claude 的更原生 Copilot 路由**：优先使用原生 `/v1/messages`，保留 Claude 风格工具流，支持 Anthropic beta 能力、通过 Responses-capable 模型支持 Claude WebSearch，并保留 subagent / session 标记。\n- **Claude Code 与 OpenCode 集成**：兼容 Claude Code 与 OpenCode，也支持通过 `@ai-sdk/anthropic` 直接作为 Anthropic provider 使用。\n- **灵活的认证与部署选项**：支持交互式登录、直接 token、个人 / Business / Enterprise、GitHub Enterprise、opencode OAuth 和自定义数据目录。\n- **多 provider 路由**：可暴露 `/:provider/...` 路由，也可在顶层 API 上使用 `model: \"provider/model\"`。\n\n## 前置要求\n\n- Bun（>= 1.2.x）\n- 如果要通过 `npx` 运行已发布 CLI，需要 Node.js\n- 只有在使用 GitHub Copilot provider 时，才需要已订阅 Copilot 的 GitHub 账号\n- 如果不使用 GitHub Copilot，需要至少一个已配置 provider 的 API key 或 OAuth 登录\n\n## 安装\n\n安装依赖：\n\n```sh\nbun install\n```\n\n直接从源码启动服务：\n\n```sh\nbun run start start\n```\n\n## 从源码运行\n\n本项目可以通过多种方式从源码运行：\n\n### 开发模式\n\n```sh\nbun run dev start\n```\n\n### 生产模式\n\n```sh\nbun run start start\n```\n\n## 通过 npx 使用\n\n你可以直接用 npx 运行本项目：\n\n> [!IMPORTANT]\n> 通过 `npx` 运行时，token usage 存储会使用 Node 内置的 `node:sqlite` 模块。该能力会在 Node.js >= 22.13.0 时启用；Node.js < 22.13.0 时 CLI 仍可启动，但会禁用 token usage 存储。\n>\n> 如果不升级 Node.js 但仍需要 token usage 存储，可以改用 Bun 运行已发布 CLI：`bunx --bun @jeffreycao/copilot-api@latest start`。\n\n```sh\nnpx @jeffreycao/copilot-api@latest start\n```\n\n带参数示例：\n\n```sh\nnpx @jeffreycao/copilot-api@latest start --port 8080\n```\n\n如果只想做认证或 provider 配置：\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth\n```\n\n如果要不依赖 GitHub Copilot 运行，先配置至少一个 provider，然后正常启动服务：\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth login --provider dashscope\nnpx @jeffreycao/copilot-api@latest start\n```\n\n## 配合 Docker 使用\n\n构建镜像：\n\n```sh\ndocker build -t copilot-api .\n```\n\n通过 bind mount 运行容器，让认证数据在重启后保留：\n\n```sh\nmkdir -p ./copilot-data\ndocker run -p 4141:4141 -v $(pwd)/copilot-data:/root/.local/share/copilot-api copilot-api\n```\n\n这会把宿主机上的 `./copilot-data` 映射到容器内的 `/root/.local/share/copilot-api`，用于持久化 GitHub 认证数据、provider 配置和其他 gateway 状态。\n\n也可以直接通过环境变量传入 GitHub token：\n\n```sh\ndocker run -p 4141:4141 -e GH_TOKEN=your_github_token_here copilot-api\n```\n\n## Electron 桌面应用\n\n如果你更喜欢图形界面，仓库里还提供了位于 `desktop/` 的 Electron 桌面应用。它支持 GitHub Copilot 登录、OpenAI Codex OAuth，以及 DeepSeek、DashScope、OpenRouter 或自定义 provider 的 API Key 配置。授权或配置 provider 后，可以一键启动或停止本地代理，并在界面里直接查看本地端点、鉴权 Header、可用模型、额度和日志。\n\n设置页还可以配置 `OAuth App`、`API Home`、`Enterprise URL`、详细日志以及最小化到托盘。桌面安装包发布在 GitHub Releases：\n\nhttps://github.com/caozhiyuan/copilot-api/releases\n\n下载对应平台的安装包后，在应用内授权或配置 provider，选择端口并启动服务，再把你的客户端指向应用里显示的本地端点即可。发布版桌面应用使用随包内置的 Electron 运行时，正常使用不需要额外安装 Node.js；token usage 历史记录会在该内置运行时支持 SQLite 时启用。\n\n桌面应用里的高级配置页会通过 `GET/POST /admin/config/model-mappings` 读写这份共享的模型映射。同一份映射会统一作用于 `POST /v1/messages`、`POST /v1/messages/count_tokens`、`POST /v1/responses` 和 `POST /v1/chat/completions`，不再按接口区分。它使用的是 `auth.adminApiKey`，不是普通的 `auth.apiKeys`；应用会在服务启动并自动生成该 key 后，直接从 `config.json` 读取它来发起请求。\n\n### 桌面应用截图\n\n下面展示了桌面应用中的首页、Token 用量统计页面：\n\n<p align=\"center\">\n  <img src=\"./docs/screenshots/desktop-dashboard.png\" alt=\"Copilot API 桌面应用首页\" width=\"49%\" />\n  <img src=\"./docs/screenshots/desktop-token-usage.png\" alt=\"Copilot API 桌面应用 Token 用量页\" width=\"49%\" />\n</p>\n\n## 与 Claude Code 一起使用\n\n这个 AI gateway 可以为 [Claude Code](https://docs.anthropic.com/en/claude-code) 提供后端能力。Claude Code 是 Anthropic 提供的实验性面向开发者的对话式 AI 助手。\n\n有两种方式可以把 Claude Code 配置为使用这个 AI gateway：\n\n### 通过 `--claude-code` 标志进行交互式配置\n\n执行带 `--claude-code` 的 `start` 命令开始：\n\n```sh\nnpx @jeffreycao/copilot-api@latest start --claude-code\n```\n\n你不再需要手动选择模型。Gateway 会自动检测每个 Claude Code 尺寸档位对应的最新可用模型——opus 映射到最新的 Opus 模型，sonnet 映射到最新的 Sonnet 模型，haiku 映射到最新的 Haiku 模型——并生成相应设置 `ANTHROPIC_DEFAULT_OPUS_MODEL`、`ANTHROPIC_DEFAULT_SONNET_MODEL` 和 `ANTHROPIC_DEFAULT_HAIKU_MODEL` 的命令。若某个档位没有匹配的可用模型，则会被省略。该命令会被复制到剪贴板，并设置 Claude Code 使用这个 AI gateway 所需的环境变量。\n\n在新的终端中粘贴并执行这条命令，即可启动 Claude Code。\n\n<a id=\"manual-configuration-with-settingsjson\"></a>\n\n### 通过 `settings.json` 手动配置\n\n另一种方式是在项目根目录中创建 `.claude/settings.json` 文件，并写入 Claude Code 所需的环境变量。这样你就不需要每次都运行交互式配置了。\n\n下面是一个 `.claude/settings.json` 示例：\n\n```json\n{\n  \"env\": {\n    \"ANTHROPIC_BASE_URL\": \"http://localhost:4141\",\n    \"ANTHROPIC_AUTH_TOKEN\": \"dummy\",\n    \"ANTHROPIC_MODEL\": \"deepseek/deepseek-v4-pro\",\n    \"ANTHROPIC_DEFAULT_SONNET_MODEL\": \"deepseek/deepseek-v4-pro\",\n    \"ANTHROPIC_DEFAULT_HAIKU_MODEL\": \"deepseek/deepseek-v4-flash\",\n    \"CLAUDE_CODE_USE_VERTEX\": \"0\",\n    \"CLAUDE_CODE_USE_BEDROCK\": \"0\",\n    \"DISABLE_NON_ESSENTIAL_MODEL_CALLS\": \"1\",\n    \"CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC\": \"1\",\n    \"CLAUDE_CODE_ATTRIBUTION_HEADER\": \"0\",\n    \"CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION\": \"false\",\n    \"CLAUDE_CODE_DISABLE_TERMINAL_TITLE\": \"true\",\n    \"CLAUDE_CODE_ENABLE_AWAY_SUMMARY\": \"0\"\n  },\n  \"permissions\": {\n    \"deny\": [\n      \"mcp__ide__executeCode\"\n    ]\n  }\n}\n```\n\n- 请根据需要替换 `ANTHROPIC_MODEL`、`ANTHROPIC_DEFAULT_OPUS_MODEL`、`ANTHROPIC_DEFAULT_SONNET_MODEL` 和 `ANTHROPIC_DEFAULT_HAIKU_MODEL`。配置完成后，请安装 claude code 插件，见 [插件集成](#plugin-integrations)。\n- 将 `CLAUDE_CODE_ATTRIBUTION_HEADER` 设为 `0` 可以阻止 Claude Code 在 system prompt 中附加计费和版本信息，从而避免 prompt cache 失效。\n- 关闭 `CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION` 和 `CLAUDE_CODE_ENABLE_AWAY_SUMMARY` 可以避免不必要地消耗额度。\n- Claude Code WebSearch 已支持纯搜索请求。Copilot 路径请保持全局 `messageApiWebSearchModel` 指向 Responses-capable GPT 模型或 `provider/model` 别名；provider 路由请使用原生 Anthropic provider 或 `openai-responses` provider。只有在你明确想禁止这类流量时，才需要把 `WebSearch` 加到 `permissions.deny`。\n- 如果使用的不是 Claude 模型，请不要启用 `ENABLE_TOOL_SEARCH`。如果使用的是 Claude 模型，则可以启用 `ENABLE_TOOL_SEARCH`。当前 Claude Code 使用的是客户端 tool search 模式，在该模式下每次加载 defer tools 都需要额外请求一次。\n- `CLAUDE_CODE_AUTO_COMPACT_WINDOW`：设置用于自动压缩计算的上下文容量（以 token 为单位）。默认使用模型自身的上下文窗口：标准模型为 200K，扩展上下文模型为 1M。使用 1M 上下文模型（如 `claude-opus-4-6[1m]`）时，可设置一个较低的值（如 `500000`）将窗口视为 500K 用于压缩计算。该值受限于模型的实际上下文窗口上限。`CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` 会基于此值的百分比生效。设置此变量可将压缩阈值与状态栏的 `used_percentage` 解耦（后者始终使用模型的完整上下文窗口）。\n\n更多选项见：[Claude Code settings](https://docs.anthropic.com/en/docs/claude-code/settings#environment-variables)\n\n也可以参考 IDE 集成说明：[Add Claude Code to your IDE](https://docs.anthropic.com/en/docs/claude-code/ide-integrations)\n\n## 与 OpenCode 一起使用\n\nOpenCode 已经有直接的 GitHub Copilot provider。本节适用于你希望让 OpenCode 通过 `@ai-sdk/anthropic` 指向这个 AI gateway，并复用本 README 前面提到的 agent 行为时。\n\n### 最小配置\n\n使用 OpenCode OAuth app 启动 AI gateway：\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth --oauth-app=opencode\nnpx @jeffreycao/copilot-api@latest start\n```\n\n然后让 OpenCode 通过 `@ai-sdk/anthropic` 指向这个 AI gateway。\n\n示例 `~/.config/opencode/opencode.json`：\n\n```json\n{\n  \"$schema\": \"https://opencode.ai/config.json\",\n  \"provider\": {\n    \"local\": {\n      \"npm\": \"@ai-sdk/anthropic\",\n      \"name\": \"My Local\",\n      \"options\": {\n        \"baseURL\": \"http://localhost:4141/v1\",\n        \"apiKey\": \"dummy\"\n      },\n      \"models\": {\n        \"gpt-5.4\": {\n          \"name\": \"gpt-5.4\",\n          \"modalities\": {\n            \"input\": [\"text\", \"image\"],\n            \"output\": [\"text\"]\n          },\n          \"limit\": {\n            \"context\": 400000,\n            \"input\": 272000,\n            \"output\": 128000\n          }\n        },\n        \"claude-sonnet-4.6\": {\n          \"id\": \"claude-sonnet-4.6\",\n          \"name\": \"claude-sonnet-4.6\",\n          \"modalities\": {\n            \"input\": [\"text\", \"image\"],\n            \"output\": [\"text\"]\n          },\n          \"limit\": {\n            \"context\": 200000,\n            \"output\": 32000\n          },\n          \"options\": {\n            \"thinking\": {\n              \"type\": \"adaptive\"\n            },\n            \"effort\": \"max\"\n          }\n        }\n      }\n    }\n  }\n}\n```\n\n这些字段的重要性：\n\n- `npm: \"@ai-sdk/anthropic\"` 是关键。OpenCode 会以 Anthropic Messages 语义与这个 AI gateway 通信，而不是把一切扁平化为 OpenAI Chat Completions。\n- `options.baseURL` 应设为 `http://localhost:4141/v1`；Anthropic SDK 会自动补上 `/messages`、`/models` 和 `/messages/count_tokens`。\n- 如果你在此代理中启用了 `auth.apiKeys`，请把 `dummy` 替换为真实 key；否则任意占位值都可以。\n\n## 与 Codex 一起使用\n\n这个 AI gateway 也可以为 Codex 提供后端能力。\n\n### Codex `config.toml` 参考配置\n\n把以下 `[model_providers.copilot_api]` 段加入你的 Codex `~/.codex/config.toml`：\n\n```toml\nmodel_provider = \"copilot_api\"\nmodel_reasoning_summary = \"auto\"\nmodel_context_window = 272000\nmodel_auto_compact_token_limit = 244800\n\n[model_providers.copilot_api]\nname = \"OpenAI\"\nbase_url = \"http://localhost:4141\"\nenv_key = \"GITHUB_COPILOT_API_KEY\"\nrequires_openai_auth = true\nsupports_websockets = false\nwire_api = \"responses\"\nrequest_max_retries = 3\nstream_max_retries = 1\nstream_idle_timeout_ms = 300000\n\n[features]\nremote_compaction_v2 = true\n\n[analytics]\nenabled = false\n```\n\n> [!NOTE]\n> 此配置仅限于 Codex 与 GitHub Copilot provider。`name` 一定要配置为 `\"OpenAI\"`。它可以缓解 Codex local compact 不命中缓存的问题。\n> 如果使用 codex provider，建议将 `base_url` 配置为 `\"http://localhost:4141/codex\"`。\n\n## GPT Tool Search\n\n对于 `gpt-5.4+` 这类 GPT Responses 模型，这个 AI gateway 可以通过一个很小的 MCP bridge 暴露 Responses `tool_search`。Claude Code 和 opencode 都可以使用同一个 bridge，前提是客户端会加载 MCP server，并且 Anthropic Messages 流量会经过这个 AI gateway。\n\nGPT 模型不要设置 Claude Code 原生的 `ENABLE_TOOL_SEARCH`。这个开关启用的是 Claude Code 自己的客户端 tool search 模式，可能导致 deferred 工具定义不再转发给 AI gateway。这个 AI gateway 需要完整的工具定义，这样才能只保留那一小组常驻加载工具，其余工具统一转换为 Responses deferred namespace。\n\n如果你安装了 `tool-search@copilot-api-marketplace`，Claude Code 会自动带上这个 MCP bridge，可以跳过下面这段 Claude Code MCP 手动配置。\n\n请把 tool search bridge 加到 Claude Code 使用的 MCP 配置中：\n\n```json\n{\n  \"mcpServers\": {\n    \"tool_search\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@jeffreycao/copilot-api@latest\", \"mcp\"]\n    }\n  }\n}\n```\n\n请把 tool search bridge 加到 opencode 使用的 MCP 配置中：\n\n```json\n{\n  \"mcp\": {\n    \"tool_search\": {\n      \"type\": \"local\",\n      \"command\": [\"npx\", \"-y\", \"@jeffreycao/copilot-api@latest\", \"mcp\"]\n    }\n  }\n}\n```\n\n本地开发时可以将命令换成 `bun`，参数换成 `[\"run\", \"./src/main.ts\", \"mcp\"]`。\n\nAI gateway 内部现在会把 OpenAI Responses `tool_search` 配置成 client-executed 模式。deferred tools 仍然会作为可搜索 namespace 暴露给模型，但会明确要求模型直接返回下一步要加载的精确工具名列表。\n\n该 bridge 使用直接工具选择，不做 query 搜索。工具入参是 `names`，值为逗号分隔的精确 deferred 工具名，例如 `TaskList,TaskGet,mcp__fetch__fetch`。\n\n<a id=\"plugin-integrations\"></a>\n\n## 插件集成\n\n本项目为 Claude Code 和 opencode 提供了插件集成。\n\n#### Claude Code 插件集成（基于 marketplace）\n\nClaude Code 集成现在拆分为两个插件：\n\n- `agent-inject` 会在 `SubagentStart` 时注入 `__SUBAGENT_MARKER__...`，以便 AI gateway 推导 `x-initiator: agent`。\n- `tool-search` 会注册用于 GPT Responses deferred tool loading 的 `tool_search` MCP bridge。\n\n- 本仓库中的 marketplace catalog：`.claude-plugin/marketplace.json`\n- 本仓库中的插件源码：`plugin/claude/agent-inject`、`plugin/claude/tool-search`\n\n远程添加 marketplace：\n\n```sh\n/plugin marketplace add https://github.com/caozhiyuan/copilot-api.git\n```\n\n从 marketplace 安装插件：\n\n```sh\n/plugin install agent-inject@copilot-api-marketplace\n/plugin install tool-search@copilot-api-marketplace\n```\n\n安装后，`agent-inject` 会在 `SubagentStart` 时注入 `__SUBAGENT_MARKER__...`，AI gateway 会利用它推导 `x-initiator: agent`。\n\n`agent-inject` 还会注册一个 `UserPromptSubmit` hook，并返回 `{\"continue\": true}`；同时它也可以通过环境变量注入 `SessionStart` reminder 规则：\n\n- `CLAUDE_PLUGIN_ENABLE_QUESTION_RULES=1` 会自动为 Claude Code 启用两条关于使用 `question` 工具的提醒。你也可以把同样的提醒手动写进 `CLAUDE.md`；见 [CLAUDE.md 或 AGENTS.md 推荐内容](#claudemd-or-agentsmd-recommended-content)。\n- `CLAUDE_PLUGIN_ENABLE_NO_BACKGROUND_AGENTS_RULE=1` 会启用关于避免在 agent hooks 中使用 `run_in_background: true` 的提醒。\n\n`tool-search` 插件内置了 [GPT Tool Search](#gpt-tool-search) 一节描述的同一个 MCP bridge，因此安装该插件后，Claude Code 用户无需再手动配置 `tool_search` server。\n\n#### Opencode 插件\n\nsubagent 标记生成器被打包为一个 opencode 插件，位于 `plugin/opencode/subagent-marker.js`。\n\n**安装方式：**\n\n将插件文件复制到你的 opencode 插件目录：\n\n```sh\n# 克隆或下载本仓库后复制该插件\ncp plugin/opencode/subagent-marker.js ~/.config/opencode/plugins/\n```\n\n或者手动在 `~/.config/opencode/plugins/subagent-marker.js` 创建该文件，并填入插件内容。\n\n**功能：**\n\n- 跟踪 subagent 创建的子会话\n- 自动在 subagent 聊天消息前添加 marker system reminder（`__SUBAGENT_MARKER__...`）\n- 设置 `x-session-id` 请求头以跟踪会话\n- 让这个 AI gateway 能够把来自 subagent 的请求识别为 `x-initiator: agent`\n\n该插件会挂接到 `session.created`、`session.deleted`、`chat.message` 和 `chat.headers` 事件上，以无缝提供 subagent marker 能力。\n\n## 使用量查看器\n\n服务启动后，控制台会输出一个 Copilot 使用量看板 URL。这个看板是一个用于监控 API 用量的 Web 界面。\n\n1. 启动服务。例如使用 npx：\n   ```sh\n   npx @jeffreycao/copilot-api@latest start\n   ```\n2. 服务会输出一个 usage viewer 的 URL。将它复制到浏览器中打开，形式大致如下：\n   `http://localhost:4141/usage-viewer?endpoint=http://localhost:4141/usage`\n   - 如果你在 Windows 上使用 `start.bat` 脚本，这个页面会自动打开。\n\n看板提供了更易读的 Copilot 用量视图：\n\n> token usage 历史记录需要 Bun 或 Node.js >= 22.13.0。Node.js < 22.13.0 时服务会正常运行，但 token usage 存储会被禁用。\n\n- **API Endpoint URL**：通过 URL 查询参数指定 API endpoints，默认指向本地服务。支持手动切换为其他兼容 endpoints。\n- **x-api-key 认证**：如果启用了 API Key 认证，可填入 `x-api-key` 请求头。密钥会持久化保存在浏览器本地存储中。\n- **Period 选择器**：支持 Day / Week / Month 三种时间范围，切换时 URL 参数会自动同步，方便收藏和分享。\n- **Fetch Data**：点击 \"Refresh\" 按钮加载或刷新使用数据。页面加载时也会自动拉取数据。\n- **Copilot Quotas 额度**：通过进度条展示 Chat、Completions 等不同服务的额度使用情况，悬停可查看已用/剩余详情。\n- **Token Usage 指标卡片**：汇总当前周期的 Total、Input、Output、Cache Read、Cache Write、Requests 和预估费用。\n- **趋势图（Week / Month）**：提供按模型和指标筛选的折线趋势图，点击数据点可查看单日用量明细。\n- **Model Breakdown 表格**：按模型维度列出周期内的请求数、输入/输出/缓存 token 和预计费用。\n- **Request Events 分页列表**：按时间排序的请求事件记录，支持分页浏览，含时间戳、模型、请求 ID 和 token 用量。\n- **Detailed Information**：展示 API 返回的完整 JSON 响应，便于深入分析所有可用统计数据。\n- **URL-based Configuration**：也可通过 `endpoint` 和 `period` 查询参数直接指定 API 端点与时间范围。例如：\n  `http://localhost:4141/usage-viewer?endpoint=http://your-api-server/usage&period=week`\n\n### Usage Viewer 截图\n\n<p align=\"center\">\n  <img src=\"./docs/screenshots/usage-viewer.png\" alt=\"Copilot API Usage Viewer 页面\" width=\"900\" />\n</p>\n\n## 命令结构\n\nCopilot API 现在使用子命令结构，主要命令包括：\n\n- `start`：启动 AI gateway 服务。如果已有 GitHub token，则启用 Copilot 路径；如果没有 GitHub token，但存在至少一个启用中的 provider，则按 provider-only 模式启动；如果两者都没有，会引导你配置 provider。\n- `auth`：仅执行 provider 登录或配置流程，不启动服务。可用于 GitHub Copilot 登录、Codex OAuth，或第三方 provider API key 配置。\n- `debug`：显示诊断信息，包括版本、运行时详情、文件路径以及认证状态，便于排障与支持。\n\n## 命令行选项\n\n### 全局选项\n\n以下选项可用于任意子命令。若在子命令之前传入，请使用 `--key=value` 形式：\n\n| 选项 | 说明 | 默认值 | 别名 |\n| --- | --- | --- | --- |\n| --api-home | API home 目录路径（设置 `COPILOT_API_HOME`） | 无 | 无 |\n| --oauth-app | OAuth app 标识符（设置 `COPILOT_API_OAUTH_APP`） | 无 | 无 |\n| --enterprise-url | GitHub Enterprise URL（设置 `COPILOT_API_ENTERPRISE_URL`） | 无 | 无 |\n\n### Start 命令选项\n\n以下是 `start` 命令可用的命令行选项：\n\n| 选项 | 说明 | 默认值 | 别名 |\n| --- | --- | --- | --- |\n| --port | 监听端口 | 4141 | -p |\n| --verbose | 启用详细日志 | false | -v |\n| --github-token | 直接提供 GitHub token（必须通过 `auth` 子命令生成） | 无 | -g |\n| --claude-code | 生成一个使用 Copilot API 配置启动 Claude Code 的命令 | false | -c |\n| --show-token | 在获取和刷新时显示 GitHub 与 Copilot token | false | 无 |\n| --proxy-env | 从环境变量初始化代理 | false | 无 |\n\n### Auth 命令选项\n\n| 选项 | 说明 | 默认值 | 别名 |\n| --- | --- | --- | --- |\n| --provider | 要登录或配置的 provider（`copilot`、`codex`、`opencode-go`、`deepseek`、`dashscope`、`openrouter` 或 `custom`） | 交互选择 | 无 |\n| --verbose | 启用详细日志 | false | -v |\n| --show-token | 认证时显示 GitHub token | false | 无 |\n\n只有在需要启用 GitHub Copilot provider 时，才需要执行 `copilot-api auth login --provider copilot`。使用 `codex` 或第三方 provider-only 模式不要求配置 Copilot。\n\n使用 `copilot-api auth login --provider deepseek`、`--provider dashscope`、`--provider openrouter` 或 `--provider opencode-go` 可以通过 CLI 快速新增或更新这些常用第三方 provider。DeepSeek 会提示输入掩码显示的 `apiKey`、provider `type`（默认 `anthropic`），以及默认 `https://api.deepseek.com/anthropic` 的 `baseUrl`。DashScope 会提示输入掩码显示的 `apiKey`、provider `type`（默认 `openai-compatible`）和预填默认值的 `baseUrl`。OpenRouter 只提示输入掩码显示的 `apiKey` 和预填默认值的 `baseUrl`，并固定写入 `type: \"anthropic\"`。OpenCode Go 只提示输入掩码显示的 `apiKey` 和预填默认值的 `baseUrl`，并固定写入 `type: \"openai-compatible\"`（baseUrl `https://opencode.ai/zen/go`）。配置并启用 provider 后，`copilot-api start` 可在没有 GitHub token 的情况下启动。\n\n使用 `copilot-api auth login --provider custom` 可以通过 CLI 新增或更新其他第三方 provider。命令会依次提示输入 provider name、项目支持的 type（`anthropic`、`openai-compatible` 或 `openai-responses`）、`baseUrl`、掩码显示的 `apiKey` 和 `authType`；`authType` 可保持 type 默认值，也可选择 `x-api-key` / `authorization`。\n\n### Debug 命令选项\n\n| 选项 | 说明 | 默认值 | 别名 |\n| --- | --- | --- | --- |\n| --json | 以 JSON 输出调试信息 | false | 无 |\n\n<a id=\"configuration-configjson\"></a>\n\n## 配置（config.json）\n\n- **位置：** Linux/macOS 为 `~/.local/share/copilot-api/config.json`，Windows 为 `%USERPROFILE%\\.local\\share\\copilot-api\\config.json`。\n- **默认结构：**\n  ```json\n  {\n    \"auth\": {\n      \"apiKeys\": [],\n      \"adminApiKey\": \"<startup 自动生成>\"\n    },\n    \"providers\": {},\n    \"modelMappings\": {},\n    \"extraPrompts\": {\n      \"gpt-5-mini\": \"<built-in exploration prompt>\"\n    },\n    \"smallModel\": \"gpt-5-mini\",\n    \"contextManagement\": {\n      \"messages\": true,\n      \"responses\": false\n    },\n    \"modelResponsesApiCompactThresholds\": {\n      \"gpt-5.4\": 217600,\n      \"gpt-5.5\": 217600,\n      \"gpt-5.6-sol\": 231200,\n      \"gpt-5.6-terra\": 231200,\n      \"gpt-5.6-luna\": 231200\n    },\n    \"modelReasoningEfforts\": {\n      \"gpt-5-mini\": \"low\"\n    },\n    \"useMessagesApi\": true,\n    \"useResponsesApiWebSocket\": true,\n    \"useResponsesApiWebSearch\": true,\n    \"messageApiWebSearchModel\": \"gpt-5-mini\"\n  }\n  ```\n- **auth.apiKeys：** 用于普通非 admin 路由的 API key。支持多个 key 轮换使用。请求可通过 `x-api-key: <key>` 或 `Authorization: Bearer <key>` 进行认证。若为空或省略，则普通路由的认证会被禁用。\n- **auth.adminApiKey：** 仅用于 `/admin/*` 路由的单个 admin key。若未配置，服务会在启动时自动生成一个随机 key，并回写到 `config.json`。它同样使用 `x-api-key` 或 `Authorization: Bearer` 这两种头，但普通 `auth.apiKeys` 不能访问 `/admin/*`。\n- **modelMappings：** 用于顶层 `POST /v1/messages`、`POST /v1/messages/count_tokens`、`POST /v1/responses` 和 `POST /v1/chat/completions` 请求的精确 `sourceModel -> targetModel` 重写映射，这几类接口共用同一份规则。省略该字段或保留为 `{}` 时，不会做模型重写。`source` 和 `target` 都必须是非空字符串。`target` 可以是普通模型 ID，也可以是 `provider/model` 形式的别名，例如 `dashscope/qwen3.6-plus`；重写发生在 provider alias 解析之前。这些映射不再按接口区分。`GET/POST /admin/config/model-mappings` 管理接口读写的也只有这个字段。\n- **extraPrompts：** `model -> prompt` 的映射。把 Anthropic 风格请求翻译为 Responses API 时，会将其附加到第一条 system prompt 后面。你可以借此为不同模型注入护栏或指引。缺失的默认项会自动补齐，但不会覆盖你自定义的 prompt。对于 GPT-5.3+ 模型（如 `gpt-5.3-codex`、`gpt-5.4`、`gpt-5.5`），未显式配置时会自动使用内置的 commentary prompt。内置 prompt 会启用带阶段感知的 commentary，让模型在工具调用或更深层推理前先发出简短的用户可见进度说明。\n- **providers：** 全局上游 provider 映射。每个 provider key（例如 `dashscope`）都会变成一个路由前缀（`/dashscope/v1/messages`）。支持 `type: \"anthropic\"`、`type: \"openai-compatible\"` 和 `type: \"openai-responses\"`。顶层客户端也可以在 `/v1/messages`、`/v1/messages/count_tokens`、`/v1/responses` 和 `/v1/chat/completions` 中使用 `model: \"dashscope/model-id\"`；AI gateway 会在转发上游前移除 `dashscope/` 前缀。`openai-compatible` provider 同时支持 chat 和 Messages 流程：`/v1/chat/completions` 会直连上游 `/v1/chat/completions`，而 `/v1/messages` 和 `/:provider/v1/messages` 会先翻译为上游 Chat Completions，再把响应翻译回 Anthropic Messages。`GET /v1/models` 会聚合已启用 provider 的模型，并以 `provider/model-id` 形式返回；单个 provider 的原始模型列表仍可使用 `GET /dashscope/v1/models`。\n  - `enabled`：可选，若省略则默认为 `true`。\n  - `baseUrl`：provider API 的基础 URL，不要带结尾的 endpoint。Anthropic provider 不要带 `/v1/messages`；OpenAI 兼容 provider 不要带 `/v1/chat/completions`；OpenAI Responses provider 不要带 `/v1/responses`。\n  - `apiKey`：作为上游凭据值使用；普通 provider 必须配置。\n  - `authType`：可选，控制 `apiKey` 如何发送到上游。普通 provider 支持 `x-api-key` 和 `authorization`。Anthropic provider 默认 `x-api-key`；OpenAI 兼容和 OpenAI Responses provider 默认 `authorization`。当设置为 `authorization` 时，代理会发送 `Authorization: Bearer <apiKey>`。`oauth2` 仅保留给内置 `codex` provider，并由 `auth login --provider codex` 自动写入。\n  - `pricingCurrency`：可选，provider 维度的 token 费用币种，例如 `USD` 或 `CNY`。快捷 provider 默认 DashScope、DeepSeek 为 `CNY`，Codex/OpenRouter 为 `USD`。费用按币种分别汇总，不做汇率换算。\n  - `models`：可选，按模型 ID 配置的映射。每个键为请求中的模型名，值支持：\n    - `temperature`：可选，当请求未指定时使用的默认温度。\n    - `topP`：可选，当请求未指定时使用的默认 `top_p`。\n    - `topK`：可选，当请求未指定时使用的默认 `top_k`。\n    - `extraBody`：可选，按模型合入上游请求体的动态字段；请求体显式同名字段优先。OpenAI 兼容 provider 可用它配置 `enable_thinking`、`preserve_thinking`、`reasoning_effort` 等字段。`thinking_budget` 是 OpenAI 兼容 provider 的特殊覆盖项：配置在 `extraBody` 后，会在 Anthropic `thinking.budget_tokens` 翻译之后强制写入，并覆盖请求派生出的预算值。对于 provider name 为 `dashscope` 或 `baseUrl` 包含 `aliyuncs.com` 的 provider，请求派生的 `thinking_budget`（来自 Anthropic `thinking.budget_tokens`）会转发给上游；其他 OpenAI 兼容 provider 会移除请求派生的 `thinking_budget`，但 `extraBody` 中的 `thinking_budget` 仍然生效。对于 DashScope provider，当 `preserve_thinking` 未在 `extraBody` 或请求体中显式设置时，默认为 `true`。\n    - `pricing`：可选，按模型配置 token 单价，币种使用 provider 的 `pricingCurrency`，单位为每 100 万 tokens。支持 `input`、`output`、`cachedInput`（隐式缓存读）、`explicitCachedInput`（显式缓存读）和 `cacheCreationInput`。如需按输入 token 总量分档，可用带 `maxInputTokens` 的 `tiers`。\n    - `contextCache`：可选，provider name 为 `dashscope` 或 `baseUrl` 包含 `aliyuncs.com` 时默认 `true`，其他 OpenAI 兼容 provider 默认 `false`。用于启用阿里云百炼/DashScope 的显式缓存（explicit context cache），会按其 Context Cache 格式在最多 4 个 content block 上注入 `cache_control: { \"type\": \"ephemeral\" }`。缓存断点策略与 opencode 主链路保持一致：前 2 条 system 消息 + 最后 2 条非 system 消息。标记字符串 content 时会把 `system` / `user` / `assistant` / `tool` 消息转换为 text content part 数组；已有数组 content 则标记最后一个 part。如果模型本身已经支持隐式缓存，或上游不支持该显式缓存扩展字段，可在模型配置中设为 `false`。支持相同显式缓存扩展的非 DashScope provider 可设为 `true`。同时适用于 `/v1/messages` 和 `/v1/chat/completions` 路由。\n    - `supportPdf`：可选，控制该模型是否支持 PDF/document content。默认 `false`，不支持时会把 PDF 转成提示文本；设为 `true` 时会把 PDF/document 转成 OpenAI Chat Completions 的 file part。\n    - `toolContentSupportType`：可选，配置该模型的 tool result content 支持能力，值为 `array`、`image`、`pdf` 的数组。provider 侧未配置时默认只发送 string tool content。若 `supportPdf` 为 `true` 但这里不包含 `pdf`，tool result 里的 file part 会被转成 user role 消息。Copilot 主链路不使用这个 provider 默认，仍按 array + image 且不支持 PDF 的能力处理。\n    - `type`：可选，按模型覆盖 provider 的协议类型。支持 `anthropic`、`openai-compatible` 和 `openai-responses`。设置后，provider 的 `/v1/messages` 路由会使用该模型的 type 替代 provider 级别的 type 进行请求路由、认证头解析和上游端点选择。适用于 OpenCode Go 等上游对不同模型同时支持 OpenAI 兼容和 Anthropic Messages API 的 provider。覆盖 type 时，认证头按覆盖后 type 的默认值解析（Anthropic 默认 `x-api-key`；OpenAI 兼容/Responses 默认 `authorization`）。\n\n  DashScope 模型配置示例：\n  ```json\n  {\n    \"providers\": {\n      \"dashscope\": {\n        \"type\": \"openai-compatible\",\n        \"enabled\": true,\n        \"baseUrl\": \"https://dashscope.aliyuncs.com/compatible-mode\",\n        \"apiKey\": \"sk-your-dashscope-key\",\n        \"pricingCurrency\": \"CNY\",\n        \"models\": {\n          \"qwen3.7-plus\": {\n            \"temperature\": 1,\n            \"topP\": 0.95,\n            \"topK\": 20,\n            \"extraBody\": {\n              \"preserve_thinking\": true\n            }\n          },\n          \"glm-5.1\": {\n            \"temperature\": 0.7,\n            \"topP\": 0.95,\n            \"contextCache\": true,\n            \"pricing\": {\n              \"tiers\": [\n                {\n                  \"maxInputTokens\": 32000,\n                  \"input\": 6,\n                  \"cachedInput\": 1.2,\n                  \"explicitCachedInput\": 0.6,\n                  \"cacheCreationInput\": 7.5,\n                  \"output\": 24\n                },\n                {\n                  \"maxInputTokens\": 200000,\n                  \"input\": 8,\n                  \"cachedInput\": 1.6,\n                  \"explicitCachedInput\": 0.8,\n                  \"cacheCreationInput\": 10,\n                  \"output\": 28\n                }\n              ]\n            },\n            \"extraBody\": {\n              \"preserve_thinking\": true\n            }\n          }\n        }\n      }\n    }\n  }\n  ```\n  内置 token 价格覆盖 Codex GPT 模型（USD）、DashScope `qwen3.7-max`、`qwen3.7-plus`、`glm-5.1`、`glm-5.2`（CNY），DeepSeek `deepseek-v4-flash`、`deepseek-v4-pro`、`deepseek-chat`、`deepseek-reasoner`（CNY），以及 OpenCode Go 模型（`glm-5.2`、`grok-4.5`、`deepseek-v4-flash`、`deepseek-v4-pro`、`kimi-k2.7-code`、`kimi-k3`、`mimo-v2.5`、`mimo-v2.5-pro`、`qwen3.7-plus`、`qwen3.7-max`、`minimax-m2.5`、`minimax-m3`，USD）。用户配置的 `pricing` 优先于内置价格。DashScope 若上游 usage 中出现 `cache_creation_input_tokens` 字段，cached tokens 按显式缓存读价计费；否则 `cachedInput` 作为隐式缓存读价。DeepSeek 的 `prompt_cache_hit_tokens` 会归入 cached input，`prompt_cache_miss_tokens` 会归入普通 input。\n- **smallModel：** 无工具预热消息的回退模型（例如 Claude Code 的探测请求）；默认是 `gpt-5-mini`。\n- **contextManagement：** 控制代理是否为 Responses API 附加 `context_management` 压缩指令。`messages` 作用于被翻译成 Responses API 的 Anthropic 风格 `/v1/messages` 请求，包括 `openai-responses` provider 的 Messages 路由，默认值为 `true`。`responses` 作用于 native `/v1/responses` 流量，包括 `provider/model` 别名和内置 `codex` provider，默认值为 `false`。只有在确认客户端支持 context management compaction 后，才建议在 Responses API 下启用 `responses`。启用后，请求体会带上 `context_management`，并在后续轮次中仅保留最新的压缩承载内容。**注意：** 对于 GPT-5.6 及以上模型（如 `gpt-5.6-sol`、`gpt-5.6-terra`、`gpt-5.6-luna`），context management 功能会被强制禁用，因为开启后会破坏这些模型的 prompt 缓存命中。此强制覆盖优先于 `contextManagement` 和 `modelResponsesApiCompactThresholds` 配置。\n- **modelResponsesApiCompactThresholds：** 按模型覆盖 Responses API 的 `compact_threshold`，仅在代理自动附加 `context_management` 时使用。它的优先级高于 `resolveResponsesCompactThreshold` 基于 `max_prompt_tokens * ratio` 的兜底阈值。默认将 `gpt-5.4` 和 `gpt-5.5` 设为 `217600`（`272000 * 0.8`），将 `gpt-5.6-sol`、`gpt-5.6-terra`、`gpt-5.6-luna` 设为 `231200`（`272000 * 0.85`）。未列出的模型继续使用原有兜底逻辑。\n- **modelReasoningEfforts：** `/v1/messages` 请求的模型级默认推理强度。仅当请求没有传入 `output_config.effort` 时，该配置才会生效。\n  - **优先级：** 请求中的 `output_config.effort` > `modelReasoningEfforts[model]` > 内置默认值（GPT-5.3+ 模型为 `xhigh`，其他模型为 `high`）。\n  - **转发字段：** 走 Copilot 原生 Messages API 时，最终值写入 `output_config.effort`；转换为 Responses API 时，最终值写入 `reasoning.effort`。\n  - **配置可选值：** `none`、`minimal`、`low`、`medium`、`high`、`xhigh`、`max`。\n- **useMessagesApi：** 当为 `true` 时，支持 Copilot 原生 `/v1/messages` 的 Claude 系模型会走 Messages API；否则回退到 `/chat/completions`。设为 `false` 可禁用 Messages API 路由，始终使用 `/chat/completions`。默认值为 `true`。\n- **useResponsesApiWebSocket：** 当为 `true` 时，Responses API 请求会优先对声明了 `ws:/responses` 的模型使用 Copilot websocket transport；仅声明 `/responses` 的模型仍走 HTTP。设为 `false` 可禁用 websocket 路由，并在模型支持 `/responses` 时使用 HTTP `/responses`。默认值为 `true`。如果遇到 Responses API WebSocket closed，一般是自己的网络问题。如果使用了 VPN，建议切换节点。\n- **useResponsesApiWebSearch：** 当为 `true` 时，服务端会保留 Responses API 中 `type: \"web_search\"` 的工具并透传到上游。设为 `false` 则会从 `/responses` payload 中移除这些工具。默认值为 `true`。\n- **messageApiWebSearchModel：** 顶层 Copilot `/v1/messages` 请求只包含服务端 `web_search` 工具时使用的全局模型，默认值为 `gpt-5-mini`。如果该值是 `provider/model` 别名，请求会进入对应 provider 的 Messages API 路径，并在转发前移除 provider 前缀。对于 Copilot GPT 模型，web search 会通过 `/responses` 执行。混合 `web_search` 与自定义工具的场景暂不支持，服务端会移除 server-side `web_search`。\n- **claudeTokenMultiplier：** 用于 Claude `/v1/messages/count_tokens` 请求在本地走 GPT tokenizer 估算时的乘数。默认值为 `1.15`。如果你的客户端仍然过晚触发上下文压缩，可以适当调大。这个配置只会在代理本地估算 Claude token 时生效；如果已经配置 `anthropicApiKey` 且 Anthropic token counting 调用成功，则会直接返回 Anthropic 的精确计数，不会使用这个乘数。\n- **anthropicApiKey：** 用于把 Claude `/v1/messages/count_tokens` 请求转发到 Anthropic 真实 token counting 端点的 API key，这样会返回精确计数，而不是 GPT tokenizer 估算值。也可通过环境变量 `ANTHROPIC_API_KEY` 设置。若未配置，或上游调用失败，则回退到由 `claudeTokenMultiplier` 控制的本地 GPT tokenizer 估算。\n\n编辑此文件后即可自定义 prompts，或替换为你自己的快速模型。修改完成后请重启服务（或重新执行命令），让缓存中的配置刷新生效。\n\n## API 认证\n\n- **受保护的普通路由：** 当配置了 `auth.apiKeys` 且非空时，除 `/`、`/usage-viewer` 和 `/usage-viewer/` 以外的普通路由都需要认证。\n- **Admin 路由：** 所有 `/admin/*` 路由都要求 `auth.adminApiKey`。如果缺失，服务会在启动时自动生成并在开始提供服务前写回 `config.json`。\n- **允许的认证头：**\n  - `x-api-key: <your_key>`\n  - `Authorization: Bearer <your_key>`\n- **CORS 预检：** `OPTIONS` 请求始终允许。\n- **未配置普通 key 时：** 普通路由仍可直接访问；但这条规则不适用于 `/admin/*`，后者只接受 `auth.adminApiKey`。\n\n普通受保护路由的示例请求：\n\n```sh\ncurl http://localhost:4141/v1/models \\\n  -H \"x-api-key: your_api_key\"\n```\n\nAdmin 路由的示例请求：\n\n```sh\ncurl http://localhost:4141/admin/config/model-mappings \\\n  -H \"x-api-key: your_admin_api_key\"\n```\n\n## API 端点\n\n服务端提供多个 OpenAI / Anthropic 兼容端点。请求会根据所选模型和 `provider/model` 别名路由到 GitHub Copilot、内置 `codex` provider 或已配置的 provider。\n\n### OpenAI 兼容端点\n\n这些端点模拟 OpenAI API 结构。\n\n| 端点 | 方法 | 说明 |\n| --- | --- | --- |\n| `POST /v1/responses` | `POST` | OpenAI 中用于生成模型响应的高级接口。支持 `openai-responses` provider 的 `provider/model` 别名。 |\n| `POST /v1/chat/completions` | `POST` | 为给定聊天对话创建模型响应。支持 `openai-compatible` provider 的 `provider/model` 别名；目标 provider 已配置时可在没有 Copilot 的情况下使用。 |\n| `GET /v1/models` | `GET` | 列出 Copilot 模型以及已启用 provider 的 `provider/model-id` 模型。来自 Codex 客户端（`User-Agent` 以 `codex` 开头）的请求会转发到 Codex Models 上游。 |\n| `POST /v1/embeddings` | `POST` | 创建表示输入文本的向量嵌入。 |\n\n### Codex 后端代理端点\n\n这些端点要求已有可用的 Codex 登录态。每个端点同时提供无版本前缀和 `/v1` 两种路径。\n\n| 端点 | 方法 | 说明 |\n| --- | --- | --- |\n| `POST /alpha/search`<br>`POST /v1/alpha/search` | `POST` | 将 JSON 请求体和查询参数透明转发到 Codex Alpha Search 上游。 |\n| `POST /images/generations`<br>`POST /v1/images/generations` | `POST` | 将 JSON 图片生成请求转发到 Codex Images 上游。请求未携带 `Content-Type` 时，网关默认补充 `application/json`。 |\n| `POST /images/edits`<br>`POST /v1/images/edits` | `POST` | 将图片编辑请求转发到 Codex Images 上游。请使用 `multipart/form-data`，并让 HTTP 客户端自动生成 `boundary`；网关会保留传入的 content type，并以流式方式转发上传请求体。 |\n\n对于以上所有端点，网关都会使用当前 Codex 登录态覆盖客户端的 authorization 和 account header，保留查询参数及兼容的请求头，并返回上游状态码、响应头和响应体。\n\n### Anthropic 兼容端点\n\n这些端点设计为兼容 Anthropic Messages API。provider 级的 models、Responses、alpha-search 和 images 路由同时支持无版本前缀与 `/v1` 两种路径；Messages 路由仍使用 `/v1`。\n\n| 端点 | 方法 | 说明 |\n| --- | --- | --- |\n| `POST /v1/messages` | `POST` | 为给定对话创建模型响应。支持已配置 provider 的 `provider/model` 别名，包括通过 `openai-compatible` provider 做翻译。 |\n| `POST /v1/messages/count_tokens` | `POST` | 计算一组消息的 token 数。支持已配置 provider 的 `provider/model` 别名。 |\n| `POST /:provider/v1/messages` | `POST` | 将 Anthropic Messages 请求代理到已配置的 Anthropic provider，或翻译到 OpenAI 兼容 / OpenAI Responses provider。 |\n| `GET /:provider/models`<br>`GET /:provider/v1/models` | `GET` | 将模型列表请求代理到已配置的 provider。对 `codex` 默认返回内置模型目录；Codex 客户端（`User-Agent` 以 `codex` 开头）会转发到 Codex Models 上游。 |\n| `POST /:provider/v1/messages/count_tokens` | `POST` | 为 provider 路由请求在本地计算 token 数。 |\n| `POST /:provider/responses`<br>`POST /:provider/v1/responses` | `POST` | 将 OpenAI Responses 请求代理到已配置的 `openai-responses` provider（含 `codex`）。 |\n| `POST /:provider/alpha/search`<br>`POST /:provider/v1/alpha/search` | `POST` | 代理 alpha-search 请求。对 `codex` 转发到 Codex Alpha Search 上游；其他 provider 转发到 `{baseUrl}/v1/alpha/search`。 |\n| `POST /:provider/images/generations`<br>`POST /:provider/v1/images/generations` | `POST` | 代理图片生成。对 `codex` 使用 Codex Images 上游；其他 provider 转发到 `{baseUrl}/v1/images/generations`（15 分钟超时）。 |\n| `POST /:provider/images/edits`<br>`POST /:provider/v1/images/edits` | `POST` | 代理图片编辑。对 `codex` 使用 Codex Images 上游；其他 provider 以 multipart/流式方式转发到 `{baseUrl}/v1/images/edits`（15 分钟超时）。 |\n\n### 使用量监控端点\n\n用于监控 Copilot 用量与额度的新端点。\n\n| 端点 | 方法 | 说明 |\n| --- | --- | --- |\n| `GET /usage` | `GET` | 获取详细的 Copilot 使用统计与额度信息。 |\n| `GET /token` | `GET` | 获取当前 API 正在使用的 Copilot token。 |\n\n### Admin / 配置端点\n\n这些端点用于本地管理操作，只接受 `auth.adminApiKey`。\n\n| 端点 | 方法 | 说明 |\n| --- | --- | --- |\n| `GET /admin/config/model-mappings` | `GET` | 返回当前 `config.json` 路径以及生效中的 `modelMappings` 映射。 |\n| `POST /admin/config/model-mappings` | `POST` | 只更新 `config.json` 里的 `modelMappings` 字段，并回传更新后的结果。 |\n\n## 使用示例\n\n常用 `npx` 命令：\n\n```sh\n# 基础启动\nnpx @jeffreycao/copilot-api@latest start\n\n# 自定义端口并开启详细日志\nnpx @jeffreycao/copilot-api@latest start --port 8080 --verbose\n\n# 执行认证流程\nnpx @jeffreycao/copilot-api@latest auth login\n\n# 配置第三方 provider，然后不依赖 GitHub Copilot 启动\nnpx @jeffreycao/copilot-api@latest auth login --provider dashscope\nnpx @jeffreycao/copilot-api@latest start\n\n# 以 JSON 格式输出调试信息\nnpx @jeffreycao/copilot-api@latest debug --json\n\n# 用 Bun 而不是 Node.js 运行已发布 CLI\nbunx --bun @jeffreycao/copilot-api@latest start\n```\n\n配置 `dashscope` 后的 OpenAI 兼容 provider 调用示例：\n\n```sh\ncurl http://localhost:4141/v1/chat/completions \\\n  -H \"content-type: application/json\" \\\n  -d '{\"model\":\"dashscope/qwen3.6-plus\",\"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]}'\n\ncurl http://localhost:4141/dashscope/v1/messages \\\n  -H \"content-type: application/json\" \\\n  -d '{\"model\":\"qwen3.6-plus\",\"max_tokens\":1024,\"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]}'\n```\n\n## 使用建议\n\n<a id=\"claudemd-or-agentsmd-recommended-content\"></a>\n\n### CLAUDE.md 或 AGENTS.md 推荐内容\n\n如果你想手动加入这些提醒，请在 Claude Code 的 `CLAUDE.md`，或 opencode/codex 的 `AGENTS.md` 中加入以下内容：\n\n```\n- Prohibited from directly asking questions to users, MUST use question tool.\n- Once you can confirm that the task is complete, MUST use question tool to make user confirm. The user may respond with feedback if they are not satisfied with the result, which you can use to make improvements and try again, after try again, MUST use question tool to make user confirm again.\n```\n"}, "201ab8f1d74eaa72deec7a1de83cbac439927561": {"t": 1785765548.9489615, "n": 33368, "h": "f2a23ae832d5ac2f", "c": "# Copilot API Proxy\n\n[English](./README.md) | 简体中文\n\n## 重要说明\n\n> [!IMPORTANT]\n> **使用前请先注意以下几点：**\n>\n> 1. **Claude Code 配置：** 与 Claude Code 搭配使用时，请将模型 ID 配置为 `claude-opus-4-8`。示例 claude `settings.json` 见 [通过 `settings.json` 手动配置](#manual-configuration-with-settingsjson)。\n>\n> 2. **内置 `copilot`、`codex` 与第三方 provider：** 执行 `npx @jeffreycao/copilot-api@latest auth`，可选择 `copilot`、`codex`、`deepseek`、`custom` 等 provider。\n>\n> 3. **注意事项：** README 顶部移除的 GitHub Copilot warning 见 [GitHub Copilot 安全提示](./NOTICE.md#github-copilot-security-notice)。\n\n---\n\n## 项目概览\n\n这是一个小型 AI gateway，可以使用 GitHub Copilot、内置 `codex` provider，也可以使用 DashScope 等已配置的第三方 provider。GitHub Copilot 现在是可选能力：如果本地没有 GitHub token，只要至少配置了一个启用中的 provider，服务仍可按 provider-only 模式启动。\n\nAI gateway 会从同一个本地端点暴露 OpenAI / Anthropic 兼容 API，让 [Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview)、OpenCode、Codex 和 OpenAI 兼容客户端可以共用同一个本地服务。\n\n在 GitHub Copilot 路径上，AI gateway 会在可用时优先使用 Copilot 原生的 Anthropic 风格 Messages API，在重工具调用场景下保留更原生的 Claude 行为。\n\n## 功能特性\n\n- **OpenAI 与 Anthropic 双兼容**：通过 `/v1/responses`、`/v1/chat/completions`、`/v1/models`、`/v1/embeddings` 和 `/v1/messages` 对外暴露同一个本地 AI gateway。\n- **Copilot 可选**：有 GitHub 凭据时可以使用 GitHub Copilot，没有 GitHub 凭据时也可以只依赖已配置的 provider 运行。\n- **同一网关接入 Copilot、`codex` 与第三方 provider**：可统一路由 GitHub Copilot、内置 `codex` provider 和配置好的外部 provider。\n- **第三方 provider 可独立启动**：配置 DashScope、DeepSeek、OpenRouter 或自定义 provider 后，不需要 GitHub Copilot 登录即可启动 AI gateway。\n- **OpenAI 兼容 provider 同时支持 chat 和 Messages API**：`openai-compatible` provider 可通过顶层 `/v1/chat/completions` 搭配 `model: \"provider/model\"` 提供 Chat Completions，也可通过 `/v1/messages` 完成 Anthropic Messages 的请求/响应翻译。\n- **面向 Claude 的更原生 Copilot 路由**：优先使用原生 `/v1/messages`，保留 Claude 风格工具流，支持 Anthropic beta 能力、通过 Responses-capable 模型支持 Claude WebSearch，并保留 subagent / session 标记。\n- **Claude Code 与 OpenCode 集成**：兼容 Claude Code 与 OpenCode，也支持通过 `@ai-sdk/anthropic` 直接作为 Anthropic provider 使用。\n- **灵活的认证与部署选项**：支持交互式登录、直接 token、个人 / Business / Enterprise、GitHub Enterprise、opencode OAuth 和自定义数据目录。\n- **多 provider 路由**：可暴露 `/:provider/...` 路由，也可在顶层 API 上使用 `model: \"provider/model\"`。\n\n## 前置要求\n\n- Bun（>= 1.2.x）\n- 如果要通过 `npx` 运行已发布 CLI，需要 Node.js\n- 只有在使用 GitHub Copilot provider 时，才需要已订阅 Copilot 的 GitHub 账号\n- 如果不使用 GitHub Copilot，需要至少一个已配置 provider 的 API key 或 OAuth 登录\n\n## 安装\n\n安装依赖：\n\n```sh\nbun install\n```\n\n直接从源码启动服务：\n\n```sh\nbun run start start\n```\n\n## 从源码运行\n\n本项目可以通过多种方式从源码运行：\n\n### 开发模式\n\n```sh\nbun run dev start\n```\n\n### 生产模式\n\n```sh\nbun run start start\n```\n\n## 通过 npx 使用\n\n你可以直接用 npx 运行本项目：\n\n> [!IMPORTANT]\n> 通过 `npx` 运行时，token usage 存储会使用 Node 内置的 `node:sqlite` 模块。该能力会在 Node.js >= 22.13.0 时启用；Node.js < 22.13.0 时 CLI 仍可启动，但会禁用 token usage 存储。\n>\n> 如果不升级 Node.js 但仍需要 token usage 存储，可以改用 Bun 运行已发布 CLI：`bunx --bun @jeffreycao/copilot-api@latest start`。\n\n```sh\nnpx @jeffreycao/copilot-api@latest start\n```\n\n带参数示例：\n\n```sh\nnpx @jeffreycao/copilot-api@latest start --port 8080\n```\n\n如果只想做认证或 provider 配置：\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth\n```\n\n如果要不依赖 GitHub Copilot 运行，先配置至少一个 provider，然后正常启动服务：\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth login --provider dashscope\nnpx @jeffreycao/copilot-api@latest start\n```\n\n## 配合 Docker 使用\n\n构建镜像：\n\n```sh\ndocker build -t copilot-api .\n```\n\n通过 bind mount 运行容器，让认证数据在重启后保留：\n\n```sh\nmkdir -p ./copilot-data\ndocker run -p 4141:4141 -v $(pwd)/copilot-data:/root/.local/share/copilot-api copilot-api\n```\n\n这会把宿主机上的 `./copilot-data` 映射到容器内的 `/root/.local/share/copilot-api`，用于持久化 GitHub 认证数据、provider 配置和其他 gateway 状态。\n\n也可以直接通过环境变量传入 GitHub token：\n\n```sh\ndocker run -p 4141:4141 -e GH_TOKEN=your_github_token_here copilot-api\n```\n\n## Electron 桌面应用\n\n如果你更喜欢图形界面，仓库里还提供了位于 `desktop/` 的 Electron 桌面应用。它支持 GitHub Copilot 登录、OpenAI Codex OAuth，以及 DeepSeek、DashScope、OpenRouter 或自定义 provider 的 API Key 配置。授权或配置 provider 后，可以一键启动或停止本地代理，并在界面里直接查看本地端点、鉴权 Header、可用模型、额度和日志。\n\n设置页还可以配置 `OAuth App`、`API Home`、`Enterprise URL`、详细日志以及最小化到托盘。桌面安装包发布在 GitHub Releases：\n\nhttps://github.com/caozhiyuan/copilot-api/releases\n\n下载对应平台的安装包后，在应用内授权或配置 provider，选择端口并启动服务，再把你的客户端指向应用里显示的本地端点即可。发布版桌面应用使用随包内置的 Electron 运行时，正常使用不需要额外安装 Node.js；token usage 历史记录会在该内置运行时支持 SQLite 时启用。\n\n桌面应用里的高级配置页会通过 `GET/POST /admin/config/model-mappings` 读写这份共享的模型映射。同一份映射会统一作用于 `POST /v1/messages`、`POST /v1/messages/count_tokens`、`POST /v1/responses` 和 `POST /v1/chat/completions`，不再按接口区分。它使用的是 `auth.adminApiKey`，不是普通的 `auth.apiKeys`；应用会在服务启动并自动生成该 key 后，直接从 `config.json` 读取它来发起请求。\n\n### 桌面应用截图\n\n下面展示了桌面应用中的首页、Token 用量统计页面：\n\n<p align=\"center\">\n  <img src=\"./docs/screenshots/desktop-dashboard.png\" alt=\"Copilot API 桌面应用首页\" width=\"49%\" />\n  <img src=\"./docs/screenshots/desktop-token-usage.png\" alt=\"Copilot API 桌面应用 Token 用量页\" width=\"49%\" />\n</p>\n\n## 与 Claude Code 一起使用\n\n这个 AI gateway 可以为 [Claude Code](https://docs.anthropic.com/en/claude-code) 提供后端能力。Claude Code 是 Anthropic 提供的实验性面向开发者的对话式 AI 助手。\n\n有两种方式可以把 Claude Code 配置为使用这个 AI gateway：\n\n### 通过 `--claude-code` 标志进行交互式配置\n\n执行带 `--claude-code` 的 `start` 命令开始：\n\n```sh\nnpx @jeffreycao/copilot-api@latest start --claude-code\n```\n\n你不再需要手动选择模型。Gateway 会自动检测每个 Claude Code 尺寸档位对应的最新可用模型——opus 映射到最新的 Opus 模型，sonnet 映射到最新的 Sonnet 模型，haiku 映射到最新的 Haiku 模型——并生成相应设置 `ANTHROPIC_DEFAULT_OPUS_MODEL`、`ANTHROPIC_DEFAULT_SONNET_MODEL` 和 `ANTHROPIC_DEFAULT_HAIKU_MODEL` 的命令。若某个档位没有匹配的可用模型，则会被省略。该命令会被复制到剪贴板，并设置 Claude Code 使用这个 AI gateway 所需的环境变量。\n\n在新的终端中粘贴并执行这条命令，即可启动 Claude Code。\n\n<a id=\"manual-configuration-with-settingsjson\"></a>\n\n### 通过 `settings.json` 手动配置\n\n另一种方式是在项目根目录中创建 `.claude/settings.json` 文件，并写入 Claude Code 所需的环境变量。这样你就不需要每次都运行交互式配置了。\n\n下面是一个 `.claude/settings.json` 示例：\n\n```json\n{\n  \"env\": {\n    \"ANTHROPIC_BASE_URL\": \"http://localhost:4141\",\n    \"ANTHROPIC_AUTH_TOKEN\": \"dummy\",\n    \"ANTHROPIC_MODEL\": \"deepseek/deepseek-v4-pro\",\n    \"ANTHROPIC_DEFAULT_SONNET_MODEL\": \"deepseek/deepseek-v4-pro\",\n    \"ANTHROPIC_DEFAULT_HAIKU_MODEL\": \"deepseek/deepseek-v4-flash\",\n    \"CLAUDE_CODE_USE_VERTEX\": \"0\",\n    \"CLAUDE_CODE_USE_BEDROCK\": \"0\",\n    \"DISABLE_NON_ESSENTIAL_MODEL_CALLS\": \"1\",\n    \"CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC\": \"1\",\n    \"CLAUDE_CODE_ATTRIBUTION_HEADER\": \"0\",\n    \"CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION\": \"false\",\n    \"CLAUDE_CODE_DISABLE_TERMINAL_TITLE\": \"true\",\n    \"CLAUDE_CODE_ENABLE_AWAY_SUMMARY\": \"0\"\n  },\n  \"permissions\": {\n    \"deny\": [\n      \"mcp__ide__executeCode\"\n    ]\n  }\n}\n```\n\n- 请根据需要替换 `ANTHROPIC_MODEL`、`ANTHROPIC_DEFAULT_OPUS_MODEL`、`ANTHROPIC_DEFAULT_SONNET_MODEL` 和 `ANTHROPIC_DEFAULT_HAIKU_MODEL`。配置完成后，请安装 claude code 插件，见 [插件集成](#plugin-integrations)。\n- 将 `CLAUDE_CODE_ATTRIBUTION_HEADER` 设为 `0` 可以阻止 Claude Code 在 system prompt 中附加计费和版本信息，从而避免 prompt cache 失效。\n- 关闭 `CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION` 和 `CLAUDE_CODE_ENABLE_AWAY_SUMMARY` 可以避免不必要地消耗额度。\n- Claude Code WebSearch 已支持纯搜索请求。Copilot 路径请保持全局 `messageApiWebSearchModel` 指向 Responses-capable GPT 模型或 `provider/model` 别名；provider 路由请使用原生 Anthropic provider 或 `openai-responses` provider。只有在你明确想禁止这类流量时，才需要把 `WebSearch` 加到 `permissions.deny`。\n- 如果使用的不是 Claude 模型，请不要启用 `ENABLE_TOOL_SEARCH`。如果使用的是 Claude 模型，则可以启用 `ENABLE_TOOL_SEARCH`。当前 Claude Code 使用的是客户端 tool search 模式，在该模式下每次加载 defer tools 都需要额外请求一次。\n- `CLAUDE_CODE_AUTO_COMPACT_WINDOW`：设置用于自动压缩计算的上下文容量（以 token 为单位）。默认使用模型自身的上下文窗口：标准模型为 200K，扩展上下文模型为 1M。使用 1M 上下文模型（如 `claude-opus-4-6[1m]`）时，可设置一个较低的值（如 `500000`）将窗口视为 500K 用于压缩计算。该值受限于模型的实际上下文窗口上限。`CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` 会基于此值的百分比生效。设置此变量可将压缩阈值与状态栏的 `used_percentage` 解耦（后者始终使用模型的完整上下文窗口）。\n\n更多选项见：[Claude Code settings](https://docs.anthropic.com/en/docs/claude-code/settings#environment-variables)\n\n也可以参考 IDE 集成说明：[Add Claude Code to your IDE](https://docs.anthropic.com/en/docs/claude-code/ide-integrations)\n\n## 与 OpenCode 一起使用\n\nOpenCode 已经有直接的 GitHub Copilot provider。本节适用于你希望让 OpenCode 通过 `@ai-sdk/anthropic` 指向这个 AI gateway，并复用本 README 前面提到的 agent 行为时。\n\n### 最小配置\n\n使用 OpenCode OAuth app 启动 AI gateway：\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth --oauth-app=opencode\nnpx @jeffreycao/copilot-api@latest start\n```\n\n然后让 OpenCode 通过 `@ai-sdk/anthropic` 指向这个 AI gateway。\n\n示例 `~/.config/opencode/opencode.json`：\n\n```json\n{\n  \"$schema\": \"https://opencode.ai/config.json\",\n  \"provider\": {\n    \"local\": {\n      \"npm\": \"@ai-sdk/anthropic\",\n      \"name\": \"My Local\",\n      \"options\": {\n        \"baseURL\": \"http://localhost:4141/v1\",\n        \"apiKey\": \"dummy\"\n      },\n      \"models\": {\n        \"gpt-5.4\": {\n          \"name\": \"gpt-5.4\",\n          \"modalities\": {\n            \"input\": [\"text\", \"image\"],\n            \"output\": [\"text\"]\n          },\n          \"limit\": {\n            \"context\": 400000,\n            \"input\": 272000,\n            \"output\": 128000\n          }\n        },\n        \"claude-sonnet-4.6\": {\n          \"id\": \"claude-sonnet-4.6\",\n          \"name\": \"claude-sonnet-4.6\",\n          \"modalities\": {\n            \"input\": [\"text\", \"image\"],\n            \"output\": [\"text\"]\n          },\n          \"limit\": {\n            \"context\": 200000,\n            \"output\": 32000\n          },\n          \"options\": {\n            \"thinking\": {\n              \"type\": \"adaptive\"\n            },\n            \"effort\": \"max\"\n          }\n        }\n      }\n    }\n  }\n}\n```\n\n这些字段的重要性：\n\n- `npm: \"@ai-sdk/anthropic\"` 是关键。OpenCode 会以 Anthropic Messages 语义与这个 AI gateway 通信，而不是把一切扁平化为 OpenAI Chat Completions。\n- `options.baseURL` 应设为 `http://localhost:4141/v1`；Anthropic SDK 会自动补上 `/messages`、`/models` 和 `/messages/count_tokens`。\n- 如果你在此代理中启用了 `auth.apiKeys`，请把 `dummy` 替换为真实 key；否则任意占位值都可以。\n\n## 与 Codex 一起使用\n\n这个 AI gateway 也可以为 Codex 提供后端能力。\n\n### Codex `config.toml` 参考配置\n\n把以下 `[model_providers.copilot_api]` 段加入你的 Codex `~/.codex/config.toml`：\n\n```toml\nmodel_provider = \"copilot_api\"\nmodel_reasoning_summary = \"auto\"\nmodel_context_window = 272000\nmodel_auto_compact_token_limit = 244800\n\n[model_providers.copilot_api]\nname = \"OpenAI\"\nbase_url = \"http://localhost:4141\"\nenv_key = \"GITHUB_COPILOT_API_KEY\"\nrequires_openai_auth = true\nsupports_websockets = false\nwire_api = \"responses\"\nrequest_max_retries = 3\nstream_max_retries = 1\nstream_idle_timeout_ms = 300000\n\n[features]\nremote_compaction_v2 = true\n\n[analytics]\nenabled = false\n```\n\n> [!NOTE]\n> 此配置仅限于 Codex 与 GitHub Copilot provider。`name` 一定要配置为 `\"OpenAI\"`。它可以缓解 Codex local compact 不命中缓存的问题。\n> 如果使用 codex provider，建议将 `base_url` 配置为 `\"http://localhost:4141/codex\"`。\n\n## GPT Tool Search\n\n对于 `gpt-5.4+` 这类 GPT Responses 模型，这个 AI gateway 可以通过一个很小的 MCP bridge 暴露 Responses `tool_search`。Claude Code 和 opencode 都可以使用同一个 bridge，前提是客户端会加载 MCP server，并且 Anthropic Messages 流量会经过这个 AI gateway。\n\nGPT 模型不要设置 Claude Code 原生的 `ENABLE_TOOL_SEARCH`。这个开关启用的是 Claude Code 自己的客户端 tool search 模式，可能导致 deferred 工具定义不再转发给 AI gateway。这个 AI gateway 需要完整的工具定义，这样才能只保留那一小组常驻加载工具，其余工具统一转换为 Responses deferred namespace。\n\n如果你安装了 `tool-search@copilot-api-marketplace`，Claude Code 会自动带上这个 MCP bridge，可以跳过下面这段 Claude Code MCP 手动配置。\n\n请把 tool search bridge 加到 Claude Code 使用的 MCP 配置中：\n\n```json\n{\n  \"mcpServers\": {\n    \"tool_search\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@jeffreycao/copilot-api@latest\", \"mcp\"]\n    }\n  }\n}\n```\n\n请把 tool search bridge 加到 opencode 使用的 MCP 配置中：\n\n```json\n{\n  \"mcp\": {\n    \"tool_search\": {\n      \"type\": \"local\",\n      \"command\": [\"npx\", \"-y\", \"@jeffreycao/copilot-api@latest\", \"mcp\"]\n    }\n  }\n}\n```\n\n本地开发时可以将命令换成 `bun`，参数换成 `[\"run\", \"./src/main.ts\", \"mcp\"]`。\n\nAI gateway 内部现在会把 OpenAI Responses `tool_search` 配置成 client-executed 模式。deferred tools 仍然会作为可搜索 namespace 暴露给模型，但会明确要求模型直接返回下一步要加载的精确工具名列表。\n\n该 bridge 使用直接工具选择，不做 query 搜索。工具入参是 `names`，值为逗号分隔的精确 deferred 工具名，例如 `TaskList,TaskGet,mcp__fetch__fetch`。\n\n<a id=\"plugin-integrations\"></a>\n\n## 插件集成\n\n本项目为 Claude Code 和 opencode 提供了插件集成。\n\n#### Claude Code 插件集成（基于 marketplace）\n\nClaude Code 集成现在拆分为两个插件：\n\n- `agent-inject` 会在 `SubagentStart` 时注入 `__SUBAGENT_MARKER__...`，以便 AI gateway 推导 `x-initiator: agent`。\n- `tool-search` 会注册用于 GPT Responses deferred tool loading 的 `tool_search` MCP bridge。\n\n- 本仓库中的 marketplace catalog：`.claude-plugin/marketplace.json`\n- 本仓库中的插件源码：`plugin/claude/agent-inject`、`plugin/claude/tool-search`\n\n远程添加 marketplace：\n\n```sh\n/plugin marketplace add https://github.com/caozhiyuan/copilot-api.git\n```\n\n从 marketplace 安装插件：\n\n```sh\n/plugin install agent-inject@copilot-api-marketplace\n/plugin install tool-search@copilot-api-marketplace\n```\n\n安装后，`agent-inject` 会在 `SubagentStart` 时注入 `__SUBAGENT_MARKER__...`，AI gateway 会利用它推导 `x-initiator: agent`。\n\n`agent-inject` 还会注册一个 `UserPromptSubmit` hook，并返回 `{\"continue\": true}`；同时它也可以通过环境变量注入 `SessionStart` reminder 规则：\n\n- `CLAUDE_PLUGIN_ENABLE_QUESTION_RULES=1` 会自动为 Claude Code 启用两条关于使用 `question` 工具的提醒。你也可以把同样的提醒手动写进 `CLAUDE.md`；见 [CLAUDE.md 或 AGENTS.md 推荐内容](#claudemd-or-agentsmd-recommended-content)。\n- `CLAUDE_PLUGIN_ENABLE_NO_BACKGROUND_AGENTS_RULE=1` 会启用关于避免在 agent hooks 中使用 `run_in_background: true` 的提醒。\n\n`tool-search` 插件内置了 [GPT Tool Search](#gpt-tool-search) 一节描述的同一个 MCP bridge，因此安装该插件后，Claude Code 用户无需再手动配置 `tool_search` server。\n\n#### Opencode 插件\n\nsubagent 标记生成器被打包为一个 opencode 插件，位于 `plugin/opencode/subagent-marker.js`。\n\n**安装方式：**\n\n将插件文件复制到你的 opencode 插件目录：\n\n```sh\n# 克隆或下载本仓库后复制该插件\ncp plugin/opencode/subagent-marker.js ~/.config/opencode/plugins/\n```\n\n或者手动在 `~/.config/opencode/plugins/subagent-marker.js` 创建该文件，并填入插件内容。\n\n**功能：**\n\n- 跟踪 subagent 创建的子会话\n- 自动在 subagent 聊天消息前添加 marker system reminder（`__SUBAGENT_MARKER__...`）\n- 设置 `x-session-id` 请求头以跟踪会话\n- 让这个 AI gateway 能够把来自 subagent 的请求识别为 `x-initiator: agent`\n\n该插件会挂接到 `session.created`、`session.deleted`、`chat.message` 和 `chat.headers` 事件上，以无缝提供 subagent marker 能力。\n\n## 使用量查看器\n\n服务启动后，控制台会输出一个 Copilot 使用量看板 URL。这个看板是一个用于监控 API 用量的 Web 界面。\n\n1. 启动服务。例如使用 npx：\n   ```sh\n   npx @jeffreycao/copilot-api@latest start\n   ```\n2. 服务会输出一个 usage viewer 的 URL。将它复制到浏览器中打开，形式大致如下：\n   `http://localhost:4141/usage-viewer?endpoint=http://localhost:4141/usage`\n   - 如果你在 Windows 上使用 `start.bat` 脚本，这个页面会自动打开。\n\n看板提供了更易读的 Copilot 用量视图：\n\n> token usage 历史记录需要 Bun 或 Node.js >= 22.13.0。Node.js < 22.13.0 时服务会正常运行，但 token usage 存储会被禁用。\n\n- **API Endpoint URL**：通过 URL 查询参数指定 API endpoints，默认指向本地服务。支持手动切换为其他兼容 endpoints。\n- **x-api-key 认证**：如果启用了 API Key 认证，可填入 `x-api-key` 请求头。密钥会持久化保存在浏览器本地存储中。\n- **Period 选择器**：支持 Day / Week / Month 三种时间范围，切换时 URL 参数会自动同步，方便收藏和分享。\n- **Fetch Data**：点击 \"Refresh\" 按钮加载或刷新使用数据。页面加载时也会自动拉取数据。\n- **Copilot Quotas 额度**：通过进度条展示 Chat、Completions 等不同服务的额度使用情况，悬停可查看已用/剩余详情。\n- **Token Usage 指标卡片**：汇总当前周期的 Total、Input、Output、Cache Read、Cache Write、Requests 和预估费用。\n- **趋势图（Week / Month）**：提供按模型和指标筛选的折线趋势图，点击数据点可查看单日用量明细。\n- **Model Breakdown 表格**：按模型维度列出周期内的请求数、输入/输出/缓存 token 和预计费用。\n- **Request Events 分页列表**：按时间排序的请求事件记录，支持分页浏览，含时间戳、模型、请求 ID 和 token 用量。\n- **Detailed Information**：展示 API 返回的完整 JSON 响应，便于深入分析所有可用统计数据。\n- **URL-based Configuration**：也可通过 `endpoint` 和 `period` 查询参数直接指定 API 端点与时间范围。例如：\n  `http://localhost:4141/usage-viewer?endpoint=http://your-api-server/usage&period=week`\n\n### Usage Viewer 截图\n\n<p align=\"center\">\n  <img src=\"./docs/screenshots/usage-viewer.png\" alt=\"Copilot API Usage Viewer 页面\" width=\"900\" />\n</p>\n\n## 命令结构\n\nCopilot API 现在使用子命令结构，主要命令包括：\n\n- `start`：启动 AI gateway 服务。如果已有 GitHub token，则启用 Copilot 路径；如果没有 GitHub token，但存在至少一个启用中的 provider，则按 provider-only 模式启动；如果两者都没有，会引导你配置 provider。\n- `auth`：仅执行 provider 登录或配置流程，不启动服务。可用于 GitHub Copilot 登录、Codex OAuth，或第三方 provider API key 配置。\n- `debug`：显示诊断信息，包括版本、运行时详情、文件路径以及认证状态，便于排障与支持。\n\n## 命令行选项\n\n### 全局选项\n\n以下选项可用于任意子命令。若在子命令之前传入，请使用 `--key=value` 形式：\n\n| 选项 | 说明 | 默认值 | 别名 |\n| --- | --- | --- | --- |\n| --api-home | API home 目录路径（设置 `COPILOT_API_HOME`） | 无 | 无 |\n| --oauth-app | OAuth app 标识符（设置 `COPILOT_API_OAUTH_APP`） | 无 | 无 |\n| --enterprise-url | GitHub Enterprise URL（设置 `COPILOT_API_ENTERPRISE_URL`） | 无 | 无 |\n\n### Start 命令选项\n\n以下是 `start` 命令可用的命令行选项：\n\n| 选项 | 说明 | 默认值 | 别名 |\n| --- | --- | --- | --- |\n| --port | 监听端口 | 4141 | -p |\n| --verbose | 启用详细日志 | false | -v |\n| --github-token | 直接提供 GitHub token（必须通过 `auth` 子命令生成） | 无 | -g |\n| --claude-code | 生成一个使用 Copilot API 配置启动 Claude Code 的命令 | false | -c |\n| --show-token | 在获取和刷新时显示 GitHub 与 Copilot token | false | 无 |\n| --proxy-env | 从环境变量初始化代理 | false | 无 |\n\n### Auth 命令选项\n\n| 选项 | 说明 | 默认值 | 别名 |\n| --- | --- | --- | --- |\n| --provider | 要登录或配置的 provider（`copilot`、`codex`、`opencode-go`、`deepseek`、`dashscope`、`openrouter` 或 `custom`） | 交互选择 | 无 |\n| --verbose | 启用详细日志 | false | -v |\n| --show-token | 认证时显示 GitHub token | false | 无 |\n\n只有在需要启用 GitHub Copilot provider 时，才需要执行 `copilot-api auth login --provider copilot`。使用 `codex` 或第三方 provider-only 模式不要求配置 Copilot。\n\n使用 `copilot-api auth login --provider deepseek`、`--provider dashscope`、`--provider openrouter` 或 `--provider opencode-go` 可以通过 CLI 快速新增或更新这些常用第三方 provider。DeepSeek 会提示输入掩码显示的 `apiKey`、provider `type`（默认 `anthropic`），以及默认 `https://api.deepseek.com/anthropic` 的 `baseUrl`。DashScope 会提示输入掩码显示的 `apiKey`、provider `type`（默认 `openai-compatible`）和预填默认值的 `baseUrl`。OpenRouter 只提示输入掩码显示的 `apiKey` 和预填默认值的 `baseUrl`，并固定写入 `type: \"anthropic\"`。OpenCode Go 只提示输入掩码显示的 `apiKey` 和预填默认值的 `baseUrl`，并固定写入 `type: \"openai-compatible\"`（baseUrl `https://opencode.ai/zen/go`）。配置并启用 provider 后，`copilot-api start` 可在没有 GitHub token 的情况下启动。\n\n使用 `copilot-api auth login --provider custom` 可以通过 CLI 新增或更新其他第三方 provider。命令会依次提示输入 provider name、项目支持的 type（`anthropic`、`openai-compatible` 或 `openai-responses`）、`baseUrl`、掩码显示的 `apiKey` 和 `authType`；`authType` 可保持 type 默认值，也可选择 `x-api-key` / `authorization`。\n\n### Debug 命令选项\n\n| 选项 | 说明 | 默认值 | 别名 |\n| --- | --- | --- | --- |\n| --json | 以 JSON 输出调试信息 | false | 无 |\n\n<a id=\"configuration-configjson\"></a>\n\n## 配置（config.json）\n\n- **位置：** Linux/macOS 为 `~/.local/share/copilot-api/config.json`，Windows 为 `%USERPROFILE%\\.local\\share\\copilot-api\\config.json`。\n- **默认结构：**\n  ```json\n  {\n    \"auth\": {\n      \"apiKeys\": [],\n      \"adminApiKey\": \"<startup 自动生成>\"\n    },\n    \"providers\": {},\n    \"modelMappings\": {},\n    \"extraPrompts\": {\n      \"gpt-5-mini\": \"<built-in exploration prompt>\"\n    },\n    \"smallModel\": \"gpt-5-mini\",\n    \"contextManagement\": {\n      \"messages\": true,\n      \"responses\": false\n    },\n    \"modelResponsesApiCompactThresholds\": {\n      \"gpt-5.4\": 217600,\n      \"gpt-5.5\": 217600,\n      \"gpt-5.6-sol\": 231200,\n      \"gpt-5.6-terra\": 231200,\n      \"gpt-5.6-luna\": 231200\n    },\n    \"modelReasoningEfforts\": {\n      \"gpt-5-mini\": \"low\"\n    },\n    \"useMessagesApi\": true,\n    \"useResponsesApiWebSocket\": true,\n    \"useResponsesApiWebSearch\": true,\n    \"messageApiWebSearchModel\": \"gpt-5-mini\"\n  }\n  ```\n- **auth.apiKeys：** 用于普通非 admin 路由的 API key。支持多个 key 轮换使用。请求可通过 `x-api-key: <key>` 或 `Authorization: Bearer <key>` 进行认证。若为空或省略，则普通路由的认证会被禁用。\n- **auth.adminApiKey：** 仅用于 `/admin/*` 路由的单个 admin key。若未配置，服务会在启动时自动生成一个随机 key，并回写到 `config.json`。它同样使用 `x-api-key` 或 `Authorization: Bearer` 这两种头，但普通 `auth.apiKeys` 不能访问 `/admin/*`。\n- **modelMappings：** 用于顶层 `POST /v1/messages`、`POST /v1/messages/count_tokens`、`POST /v1/responses` 和 `POST /v1/chat/completions` 请求的精确 `sourceModel -> targetModel` 重写映射，这几类接口共用同一份规则。省略该字段或保留为 `{}` 时，不会做模型重写。`source` 和 `target` 都必须是非空字符串。`target` 可以是普通模型 ID，也可以是 `provider/model` 形式的别名，例如 `dashscope/qwen3.6-plus`；重写发生在 provider alias 解析之前。这些映射不再按接口区分。`GET/POST /admin/config/model-mappings` 管理接口读写的也只有这个字段。\n- **extraPrompts：** `model -> prompt` 的映射。把 Anthropic 风格请求翻译为 Responses API 时，会将其附加到第一条 system prompt 后面。你可以借此为不同模型注入护栏或指引。缺失的默认项会自动补齐，但不会覆盖你自定义的 prompt。对于 GPT-5.3+ 模型（如 `gpt-5.3-codex`、`gpt-5.4`、`gpt-5.5`），未显式配置时会自动使用内置的 commentary prompt。内置 prompt 会启用带阶段感知的 commentary，让模型在工具调用或更深层推理前先发出简短的用户可见进度说明。\n- **providers：** 全局上游 provider 映射。每个 provider key（例如 `dashscope`）都会变成一个路由前缀（`/dashscope/v1/messages`）。支持 `type: \"anthropic\"`、`type: \"openai-compatible\"` 和 `type: \"openai-responses\"`。顶层客户端也可以在 `/v1/messages`、`/v1/messages/count_tokens`、`/v1/responses` 和 `/v1/chat/completions` 中使用 `model: \"dashscope/model-id\"`；AI gateway 会在转发上游前移除 `dashscope/` 前缀。`openai-compatible` provider 同时支持 chat 和 Messages 流程：`/v1/chat/completions` 会直连上游 `/v1/chat/completions`，而 `/v1/messages` 和 `/:provider/v1/messages` 会先翻译为上游 Chat Completions，再把响应翻译回 Anthropic Messages。`GET /v1/models` 会聚合已启用 provider 的模型，并以 `provider/model-id` 形式返回；单个 provider 的原始模型列表仍可使用 `GET /dashscope/v1/models`。\n  - `enabled`：可选，若省略则默认为 `true`。\n  - `baseUrl`：provider API 的基础 URL，不要带结尾的 endpoint。Anthropic provider 不要带 `/v1/messages`；OpenAI 兼容 provider 不要带 `/v1/chat/completions`；OpenAI Responses provider 不要带 `/v1/responses`。\n  - `apiKey`：作为上游凭据值使用；普通 provider 必须配置。\n  - `authType`：可选，控制 `apiKey` 如何发送到上游。普通 provider 支持 `x-api-key` 和 `authorization`。Anthropic provider 默认 `x-api-key`；OpenAI 兼容和 OpenAI Responses provider 默认 `authorization`。当设置为 `authorization` 时，代理会发送 `Authorization: Bearer <apiKey>`。`oauth2` 仅保留给内置 `codex` provider，并由 `auth login --provider codex` 自动写入。\n  - `pricingCurrency`：可选，provider 维度的 token 费用币种，例如 `USD` 或 `CNY`。快捷 provider 默认 DashScope、DeepSeek 为 `CNY`，Codex/OpenRouter 为 `USD`。费用按币种分别汇总，不做汇率换算。\n  - `models`：可选，按模型 ID 配置的映射。每个键为请求中的模型名，值支持：\n    - `temperature`：可选，当请求未指定时使用的默认温度。\n    - `topP`：可选，当请求未指定时使用的默认 `top_p`。\n    - `topK`：可选，当请求未指定时使用的默认 `top_k`。\n    - `extraBody`：可选，按模型合入上游请求体的动态字段；请求体显式同名字段优先。OpenAI 兼容 provider 可用它配置 `enable_thinking`、`preserve_thinking`、`reasoning_effort` 等字段。`thinking_budget` 是 OpenAI 兼容 provider 的特殊覆盖项：配置在 `extraBody` 后，会在 Anthropic `thinking.budget_tokens` 翻译之后强制写入，并覆盖请求派生出的预算值。对于 provider name 为 `dashscope` 或 `baseUrl` 包含 `aliyuncs.com` 的 provider，请求派生的 `thinking_budget`（来自 Anthropic `thinking.budget_tokens`）会转发给上游；其他 OpenAI 兼容 provider 会移除请求派生的 `thinking_budget`，但 `extraBody` 中的 `thinking_budget` 仍然生效。对于 DashScope provider，当 `preserve_thinking` 未在 `extraBody` 或请求体中显式设置时，默认为 `true`。\n    - `pricing`：可选，按模型配置 token 单价，币种使用 provider 的 `pricingCurrency`，单位为每 100 万 tokens。支持 `input`、`output`、`cachedInput`（隐式缓存读）、`explicitCachedInput`（显式缓存读）和 `cacheCreationInput`。如需按输入 token 总量分档，可用带 `maxInputTokens` 的 `tiers`。\n    - `contextCache`：可选，provider name 为 `dashscope` 或 `baseUrl` 包含 `aliyuncs.com` 时默认 `true`，其他 OpenAI 兼容 provider 默认 `false`。用于启用阿里云百炼/DashScope 的显式缓存（explicit context cache），会按其 Context Cache 格式在最多 4 个 content block 上注入 `cache_control: { \"type\": \"ephemeral\" }`。缓存断点策略与 opencode 主链路保持一致：前 2 条 system 消息 + 最后 2 条非 system 消息。标记字符串 content 时会把 `system` / `user` / `assistant` / `tool` 消息转换为 text content part 数组；已有数组 content 则标记最后一个 part。如果模型本身已经支持隐式缓存，或上游不支持该显式缓存扩展字段，可在模型配置中设为 `false`。支持相同显式缓存扩展的非 DashScope provider 可设为 `true`。同时适用于 `/v1/messages` 和 `/v1/chat/completions` 路由。\n    - `supportPdf`：可选，控制该模型是否支持 PDF/document content。默认 `false`，不支持时会把 PDF 转成提示文本；设为 `true` 时会把 PDF/document 转成 OpenAI Chat Completions 的 file part。\n    - `toolContentSupportType`：可选，配置该模型的 tool result content 支持能力，值为 `array`、`image`、`pdf` 的数组。provider 侧未配置时默认只发送 string tool content。若 `supportPdf` 为 `true` 但这里不包含 `pdf`，tool result 里的 file part 会被转成 user role 消息。Copilot 主链路不使用这个 provider 默认，仍按 array + image 且不支持 PDF 的能力处理。\n    - `type`：可选，按模型覆盖 provider 的协议类型。支持 `anthropic`、`openai-compatible` 和 `openai-responses`。设置后，provider 的 `/v1/messages` 路由会使用该模型的 type 替代 provider 级别的 type 进行请求路由、认证头解析和上游端点选择。适用于 OpenCode Go 等上游对不同模型同时支持 OpenAI 兼容和 Anthropic Messages API 的 provider。覆盖 type 时，认证头按覆盖后 type 的默认值解析（Anthropic 默认 `x-api-key`；OpenAI 兼容/Responses 默认 `authorization`）。\n\n  DashScope 模型配置示例：\n  ```json\n  {\n    \"providers\": {\n      \"dashscope\": {\n        \"type\": \"openai-compatible\",\n        \"enabled\": true,\n        \"baseUrl\": \"https://dashscope.aliyuncs.com/compatible-mode\",\n        \"apiKey\": \"sk-your-dashscope-key\",\n        \"pricingCurrency\": \"CNY\",\n        \"models\": {\n          \"qwen3.7-plus\": {\n            \"temperature\": 1,\n            \"topP\": 0.95,\n            \"topK\": 20,\n            \"extraBody\": {\n              \"preserve_thinking\": true\n            }\n          },\n          \"glm-5.1\": {\n            \"temperature\": 0.7,\n            \"topP\": 0.95,\n            \"contextCache\": true,\n            \"pricing\": {\n              \"tiers\": [\n                {\n                  \"maxInputTokens\": 32000,\n                  \"input\": 6,\n                  \"cachedInput\": 1.2,\n                  \"explicitCachedInput\": 0.6,\n                  \"cacheCreationInput\": 7.5,\n                  \"output\": 24\n                },\n                {\n                  \"maxInputTokens\": 200000,\n                  \"input\": 8,\n                  \"cachedInput\": 1.6,\n                  \"explicitCachedInput\": 0.8,\n                  \"cacheCreationInput\": 10,\n                  \"output\": 28\n                }\n              ]\n            },\n            \"extraBody\": {\n              \"preserve_thinking\": true\n            }\n          }\n        }\n      }\n    }\n  }\n  ```\n  内置 token 价格覆盖 Codex GPT 模型（USD）、DashScope `qwen3.7-max`、`qwen3.7-plus`、`glm-5.1`、`glm-5.2`（CNY），DeepSeek `deepseek-v4-flash`、`deepseek-v4-pro`、`deepseek-chat`、`deepseek-reasoner`（CNY），以及 OpenCode Go 模型（`glm-5.2`、`deepseek-v4-flash`、`deepseek-v4-pro`、`kimi-k2.7-code`、`mimo-v2.5`、`mimo-v2.5-pro`、`qwen3.7-plus`、`qwen3.7-max`、`minimax-m2.5`、`minimax-m3`，USD）。用户配置的 `pricing` 优先于内置价格。DashScope 若上游 usage 中出现 `cache_creation_input_tokens` 字段，cached tokens 按显式缓存读价计费；否则 `cachedInput` 作为隐式缓存读价。DeepSeek 的 `prompt_cache_hit_tokens` 会归入 cached input，`prompt_cache_miss_tokens` 会归入普通 input。\n- **smallModel：** 无工具预热消息的回退模型（例如 Claude Code 的探测请求）；默认是 `gpt-5-mini`。\n- **contextManagement：** 控制代理是否为 Responses API 附加 `context_management` 压缩指令。`messages` 作用于被翻译成 Responses API 的 Anthropic 风格 `/v1/messages` 请求，包括 `openai-responses` provider 的 Messages 路由，默认值为 `true`。`responses` 作用于 native `/v1/responses` 流量，包括 `provider/model` 别名和内置 `codex` provider，默认值为 `false`。只有在确认客户端支持 context management compaction 后，才建议在 Responses API 下启用 `responses`。启用后，请求体会带上 `context_management`，并在后续轮次中仅保留最新的压缩承载内容。**注意：** 对于 GPT-5.6 及以上模型（如 `gpt-5.6-sol`、`gpt-5.6-terra`、`gpt-5.6-luna`），context management 功能会被强制禁用，因为开启后会破坏这些模型的 prompt 缓存命中。此强制覆盖优先于 `contextManagement` 和 `modelResponsesApiCompactThresholds` 配置。\n- **modelResponsesApiCompactThresholds：** 按模型覆盖 Responses API 的 `compact_threshold`，仅在代理自动附加 `context_management` 时使用。它的优先级高于 `resolveResponsesCompactThreshold` 基于 `max_prompt_tokens * ratio` 的兜底阈值。默认将 `gpt-5.4` 和 `gpt-5.5` 设为 `217600`（`272000 * 0.8`），将 `gpt-5.6-sol`、`gpt-5.6-terra`、`gpt-5.6-luna` 设为 `231200`（`272000 * 0.85`）。未列出的模型继续使用原有兜底逻辑。\n- **modelReasoningEfforts：** `/v1/messages` 请求的模型级默认推理强度。仅当请求没有传入 `output_config.effort` 时，该配置才会生效。\n  - **优先级：** 请求中的 `output_config.effort` > `modelReasoningEfforts[model]` > 内置默认值（GPT-5.3+ 模型为 `xhigh`，其他模型为 `high`）。\n  - **转发字段：** 走 Copilot 原生 Messages API 时，最终值写入 `output_config.effort`；转换为 Responses API 时，最终值写入 `reasoning.effort`。\n  - **配置可选值：** `none`、`minimal`、`low`、`medium`、`high`、`xhigh`、`max`。\n- **useMessagesApi：** 当为 `true` 时，支持 Copilot 原生 `/v1/messages` 的 Claude 系模型会走 Messages API；否则回退到 `/chat/completions`。设为 `false` 可禁用 Messages API 路由，始终使用 `/chat/completions`。默认值为 `true`。\n- **useResponsesApiWebSocket：** 当为 `true` 时，Responses API 请求会优先对声明了 `ws:/responses` 的模型使用 Copilot websocket transport；仅声明 `/responses` 的模型仍走 HTTP。设为 `false` 可禁用 websocket 路由，并在模型支持 `/responses` 时使用 HTTP `/responses`。默认值为 `true`。如果遇到 Responses API WebSocket closed，一般是自己的网络问题。如果使用了 VPN，建议切换节点。\n- **useResponsesApiWebSearch：** 当为 `true` 时，服务端会保留 Responses API 中 `type: \"web_search\"` 的工具并透传到上游。设为 `false` 则会从 `/responses` payload 中移除这些工具。默认值为 `true`。\n- **messageApiWebSearchModel：** 顶层 Copilot `/v1/messages` 请求只包含服务端 `web_search` 工具时使用的全局模型，默认值为 `gpt-5-mini`。如果该值是 `provider/model` 别名，请求会进入对应 provider 的 Messages API 路径，并在转发前移除 provider 前缀。对于 Copilot GPT 模型，web search 会通过 `/responses` 执行。混合 `web_search` 与自定义工具的场景暂不支持，服务端会移除 server-side `web_search`。\n- **claudeTokenMultiplier：** 用于 Claude `/v1/messages/count_tokens` 请求在本地走 GPT tokenizer 估算时的乘数。默认值为 `1.15`。如果你的客户端仍然过晚触发上下文压缩，可以适当调大。这个配置只会在代理本地估算 Claude token 时生效；如果已经配置 `anthropicApiKey` 且 Anthropic token counting 调用成功，则会直接返回 Anthropic 的精确计数，不会使用这个乘数。\n- **anthropicApiKey：** 用于把 Claude `/v1/messages/count_tokens` 请求转发到 Anthropic 真实 token counting 端点的 API key，这样会返回精确计数，而不是 GPT tokenizer 估算值。也可通过环境变量 `ANTHROPIC_API_KEY` 设置。若未配置，或上游调用失败，则回退到由 `claudeTokenMultiplier` 控制的本地 GPT tokenizer 估算。\n\n编辑此文件后即可自定义 prompts，或替换为你自己的快速模型。修改完成后请重启服务（或重新执行命令），让缓存中的配置刷新生效。\n\n## API 认证\n\n- **受保护的普通路由：** 当配置了 `auth.apiKeys` 且非空时，除 `/`、`/usage-viewer` 和 `/usage-viewer/` 以外的普通路由都需要认证。\n- **Admin 路由：** 所有 `/admin/*` 路由都要求 `auth.adminApiKey`。如果缺失，服务会在启动时自动生成并在开始提供服务前写回 `config.json`。\n- **允许的认证头：**\n  - `x-api-key: <your_key>`\n  - `Authorization: Bearer <your_key>`\n- **CORS 预检：** `OPTIONS` 请求始终允许。\n- **未配置普通 key 时：** 普通路由仍可直接访问；但这条规则不适用于 `/admin/*`，后者只接受 `auth.adminApiKey`。\n\n普通受保护路由的示例请求：\n\n```sh\ncurl http://localhost:4141/v1/models \\\n  -H \"x-api-key: your_api_key\"\n```\n\nAdmin 路由的示例请求：\n\n```sh\ncurl http://localhost:4141/admin/config/model-mappings \\\n  -H \"x-api-key: your_admin_api_key\"\n```\n\n## API 端点\n\n服务端提供多个 OpenAI / Anthropic 兼容端点。请求会根据所选模型和 `provider/model` 别名路由到 GitHub Copilot、内置 `codex` provider 或已配置的 provider。\n\n### OpenAI 兼容端点\n\n这些端点模拟 OpenAI API 结构。\n\n| 端点 | 方法 | 说明 |\n| --- | --- | --- |\n| `POST /v1/responses` | `POST` | OpenAI 中用于生成模型响应的高级接口。支持 `openai-responses` provider 的 `provider/model` 别名。 |\n| `POST /v1/chat/completions` | `POST` | 为给定聊天对话创建模型响应。支持 `openai-compatible` provider 的 `provider/model` 别名；目标 provider 已配置时可在没有 Copilot 的情况下使用。 |\n| `GET /v1/models` | `GET` | 列出 Copilot 模型以及已启用 provider 的 `provider/model-id` 模型。来自 Codex 客户端（`User-Agent` 以 `codex` 开头）的请求会转发到 Codex Models 上游。 |\n| `POST /v1/embeddings` | `POST` | 创建表示输入文本的向量嵌入。 |\n\n### Codex 后端代理端点\n\n这些端点要求已有可用的 Codex 登录态。每个端点同时提供无版本前缀和 `/v1` 两种路径。\n\n| 端点 | 方法 | 说明 |\n| --- | --- | --- |\n| `POST /alpha/search`<br>`POST /v1/alpha/search` | `POST` | 将 JSON 请求体和查询参数透明转发到 Codex Alpha Search 上游。 |\n| `POST /images/generations`<br>`POST /v1/images/generations` | `POST` | 将 JSON 图片生成请求转发到 Codex Images 上游。请求未携带 `Content-Type` 时，网关默认补充 `application/json`。 |\n| `POST /images/edits`<br>`POST /v1/images/edits` | `POST` | 将图片编辑请求转发到 Codex Images 上游。请使用 `multipart/form-data`，并让 HTTP 客户端自动生成 `boundary`；网关会保留传入的 content type，并以流式方式转发上传请求体。 |\n\n对于以上所有端点，网关都会使用当前 Codex 登录态覆盖客户端的 authorization 和 account header，保留查询参数及兼容的请求头，并返回上游状态码、响应头和响应体。\n\n### Anthropic 兼容端点\n\n这些端点设计为兼容 Anthropic Messages API。provider 级的 models、Responses、alpha-search 和 images 路由同时支持无版本前缀与 `/v1` 两种路径；Messages 路由仍使用 `/v1`。\n\n| 端点 | 方法 | 说明 |\n| --- | --- | --- |\n| `POST /v1/messages` | `POST` | 为给定对话创建模型响应。支持已配置 provider 的 `provider/model` 别名，包括通过 `openai-compatible` provider 做翻译。 |\n| `POST /v1/messages/count_tokens` | `POST` | 计算一组消息的 token 数。支持已配置 provider 的 `provider/model` 别名。 |\n| `POST /:provider/v1/messages` | `POST` | 将 Anthropic Messages 请求代理到已配置的 Anthropic provider，或翻译到 OpenAI 兼容 / OpenAI Responses provider。 |\n| `GET /:provider/models`<br>`GET /:provider/v1/models` | `GET` | 将模型列表请求代理到已配置的 provider。对 `codex` 默认返回内置模型目录；Codex 客户端（`User-Agent` 以 `codex` 开头）会转发到 Codex Models 上游。 |\n| `POST /:provider/v1/messages/count_tokens` | `POST` | 为 provider 路由请求在本地计算 token 数。 |\n| `POST /:provider/responses`<br>`POST /:provider/v1/responses` | `POST` | 将 OpenAI Responses 请求代理到已配置的 `openai-responses` provider（含 `codex`）。 |\n| `POST /:provider/alpha/search`<br>`POST /:provider/v1/alpha/search` | `POST` | 代理 alpha-search 请求。对 `codex` 转发到 Codex Alpha Search 上游；其他 provider 转发到 `{baseUrl}/v1/alpha/search`。 |\n| `POST /:provider/images/generations`<br>`POST /:provider/v1/images/generations` | `POST` | 代理图片生成。对 `codex` 使用 Codex Images 上游；其他 provider 转发到 `{baseUrl}/v1/images/generations`（15 分钟超时）。 |\n| `POST /:provider/images/edits`<br>`POST /:provider/v1/images/edits` | `POST` | 代理图片编辑。对 `codex` 使用 Codex Images 上游；其他 provider 以 multipart/流式方式转发到 `{baseUrl}/v1/images/edits`（15 分钟超时）。 |\n\n### 使用量监控端点\n\n用于监控 Copilot 用量与额度的新端点。\n\n| 端点 | 方法 | 说明 |\n| --- | --- | --- |\n| `GET /usage` | `GET` | 获取详细的 Copilot 使用统计与额度信息。 |\n| `GET /token` | `GET` | 获取当前 API 正在使用的 Copilot token。 |\n\n### Admin / 配置端点\n\n这些端点用于本地管理操作，只接受 `auth.adminApiKey`。\n\n| 端点 | 方法 | 说明 |\n| --- | --- | --- |\n| `GET /admin/config/model-mappings` | `GET` | 返回当前 `config.json` 路径以及生效中的 `modelMappings` 映射。 |\n| `POST /admin/config/model-mappings` | `POST` | 只更新 `config.json` 里的 `modelMappings` 字段，并回传更新后的结果。 |\n\n## 使用示例\n\n常用 `npx` 命令：\n\n```sh\n# 基础启动\nnpx @jeffreycao/copilot-api@latest start\n\n# 自定义端口并开启详细日志\nnpx @jeffreycao/copilot-api@latest start --port 8080 --verbose\n\n# 执行认证流程\nnpx @jeffreycao/copilot-api@latest auth login\n\n# 配置第三方 provider，然后不依赖 GitHub Copilot 启动\nnpx @jeffreycao/copilot-api@latest auth login --provider dashscope\nnpx @jeffreycao/copilot-api@latest start\n\n# 以 JSON 格式输出调试信息\nnpx @jeffreycao/copilot-api@latest debug --json\n\n# 用 Bun 而不是 Node.js 运行已发布 CLI\nbunx --bun @jeffreycao/copilot-api@latest start\n```\n\n配置 `dashscope` 后的 OpenAI 兼容 provider 调用示例：\n\n```sh\ncurl http://localhost:4141/v1/chat/completions \\\n  -H \"content-type: application/json\" \\\n  -d '{\"model\":\"dashscope/qwen3.6-plus\",\"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]}'\n\ncurl http://localhost:4141/dashscope/v1/messages \\\n  -H \"content-type: application/json\" \\\n  -d '{\"model\":\"qwen3.6-plus\",\"max_tokens\":1024,\"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]}'\n```\n\n## 使用建议\n\n<a id=\"claudemd-or-agentsmd-recommended-content\"></a>\n\n### CLAUDE.md 或 AGENTS.md 推荐内容\n\n如果你想手动加入这些提醒，请在 Claude Code 的 `CLAUDE.md`，或 opencode/codex 的 `AGENTS.md` 中加入以下内容：\n\n```\n- Prohibited from directly asking questions to users, MUST use question tool.\n- Once you can confirm that the task is complete, MUST use question tool to make user confirm. The user may respond with feedback if they are not satisfied with the result, which you can use to make improvements and try again, after try again, MUST use question tool to make user confirm again.\n```\n"}, "9d7b1f8aea1fb41ea13222b47689fd2acf5b0c60": {"t": 1785765550.4456246, "n": 33169, "h": "a2dc4953534703c2", "c": "# Copilot API Proxy\n\n[English](./README.md) | 简体中文\n\n## 重要说明\n\n> [!IMPORTANT]\n> **使用前请先注意以下几点：**\n>\n> 1. **Claude Code 配置：** 与 Claude Code 搭配使用时，请将模型 ID 配置为 `claude-opus-4-8`。示例 claude `settings.json` 见 [通过 `settings.json` 手动配置](#manual-configuration-with-settingsjson)。\n>\n> 2. **内置 `copilot`、`codex` 与第三方 provider：** 执行 `npx @jeffreycao/copilot-api@latest auth`，可选择 `copilot`、`codex`、`deepseek`、`custom` 等 provider。\n>\n> 3. **注意事项：** README 顶部移除的 GitHub Copilot warning 见 [GitHub Copilot 安全提示](./NOTICE.md#github-copilot-security-notice)。\n\n---\n\n## 项目概览\n\n这是一个小型 AI gateway，可以使用 GitHub Copilot、内置 `codex` provider，也可以使用 DashScope 等已配置的第三方 provider。GitHub Copilot 现在是可选能力：如果本地没有 GitHub token，只要至少配置了一个启用中的 provider，服务仍可按 provider-only 模式启动。\n\nAI gateway 会从同一个本地端点暴露 OpenAI / Anthropic 兼容 API，让 [Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview)、OpenCode、Codex 和 OpenAI 兼容客户端可以共用同一个本地服务。\n\n在 GitHub Copilot 路径上，AI gateway 会在可用时优先使用 Copilot 原生的 Anthropic 风格 Messages API，在重工具调用场景下保留更原生的 Claude 行为。\n\n## 功能特性\n\n- **OpenAI 与 Anthropic 双兼容**：通过 `/v1/responses`、`/v1/chat/completions`、`/v1/models`、`/v1/embeddings` 和 `/v1/messages` 对外暴露同一个本地 AI gateway。\n- **Copilot 可选**：有 GitHub 凭据时可以使用 GitHub Copilot，没有 GitHub 凭据时也可以只依赖已配置的 provider 运行。\n- **同一网关接入 Copilot、`codex` 与第三方 provider**：可统一路由 GitHub Copilot、内置 `codex` provider 和配置好的外部 provider。\n- **第三方 provider 可独立启动**：配置 DashScope、DeepSeek、OpenRouter 或自定义 provider 后，不需要 GitHub Copilot 登录即可启动 AI gateway。\n- **OpenAI 兼容 provider 同时支持 chat 和 Messages API**：`openai-compatible` provider 可通过顶层 `/v1/chat/completions` 搭配 `model: \"provider/model\"` 提供 Chat Completions，也可通过 `/v1/messages` 完成 Anthropic Messages 的请求/响应翻译。\n- **面向 Claude 的更原生 Copilot 路由**：优先使用原生 `/v1/messages`，保留 Claude 风格工具流，支持 Anthropic beta 能力、通过 Responses-capable 模型支持 Claude WebSearch，并保留 subagent / session 标记。\n- **Claude Code 与 OpenCode 集成**：兼容 Claude Code 与 OpenCode，也支持通过 `@ai-sdk/anthropic` 直接作为 Anthropic provider 使用。\n- **灵活的认证与部署选项**：支持交互式登录、直接 token、个人 / Business / Enterprise、GitHub Enterprise、opencode OAuth 和自定义数据目录。\n- **多 provider 路由**：可暴露 `/:provider/...` 路由，也可在顶层 API 上使用 `model: \"provider/model\"`。\n\n## 前置要求\n\n- Bun（>= 1.2.x）\n- 如果要通过 `npx` 运行已发布 CLI，需要 Node.js\n- 只有在使用 GitHub Copilot provider 时，才需要已订阅 Copilot 的 GitHub 账号\n- 如果不使用 GitHub Copilot，需要至少一个已配置 provider 的 API key 或 OAuth 登录\n\n## 安装\n\n安装依赖：\n\n```sh\nbun install\n```\n\n直接从源码启动服务：\n\n```sh\nbun run start start\n```\n\n## 从源码运行\n\n本项目可以通过多种方式从源码运行：\n\n### 开发模式\n\n```sh\nbun run dev start\n```\n\n### 生产模式\n\n```sh\nbun run start start\n```\n\n## 通过 npx 使用\n\n你可以直接用 npx 运行本项目：\n\n> [!IMPORTANT]\n> 通过 `npx` 运行时，token usage 存储会使用 Node 内置的 `node:sqlite` 模块。该能力会在 Node.js >= 22.13.0 时启用；Node.js < 22.13.0 时 CLI 仍可启动，但会禁用 token usage 存储。\n>\n> 如果不升级 Node.js 但仍需要 token usage 存储，可以改用 Bun 运行已发布 CLI：`bunx --bun @jeffreycao/copilot-api@latest start`。\n\n```sh\nnpx @jeffreycao/copilot-api@latest start\n```\n\n带参数示例：\n\n```sh\nnpx @jeffreycao/copilot-api@latest start --port 8080\n```\n\n如果只想做认证或 provider 配置：\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth\n```\n\n如果要不依赖 GitHub Copilot 运行，先配置至少一个 provider，然后正常启动服务：\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth login --provider dashscope\nnpx @jeffreycao/copilot-api@latest start\n```\n\n## 配合 Docker 使用\n\n构建镜像：\n\n```sh\ndocker build -t copilot-api .\n```\n\n通过 bind mount 运行容器，让认证数据在重启后保留：\n\n```sh\nmkdir -p ./copilot-data\ndocker run -p 4141:4141 -v $(pwd)/copilot-data:/root/.local/share/copilot-api copilot-api\n```\n\n这会把宿主机上的 `./copilot-data` 映射到容器内的 `/root/.local/share/copilot-api`，用于持久化 GitHub 认证数据、provider 配置和其他 gateway 状态。\n\n也可以直接通过环境变量传入 GitHub token：\n\n```sh\ndocker run -p 4141:4141 -e GH_TOKEN=your_github_token_here copilot-api\n```\n\n## Electron 桌面应用\n\n如果你更喜欢图形界面，仓库里还提供了位于 `desktop/` 的 Electron 桌面应用。它支持 GitHub Copilot 登录、OpenAI Codex OAuth，以及 DeepSeek、DashScope、OpenRouter 或自定义 provider 的 API Key 配置。授权或配置 provider 后，可以一键启动或停止本地代理，并在界面里直接查看本地端点、鉴权 Header、可用模型、额度和日志。\n\n设置页还可以配置 `OAuth App`、`API Home`、`Enterprise URL`、详细日志以及最小化到托盘。桌面安装包发布在 GitHub Releases：\n\nhttps://github.com/caozhiyuan/copilot-api/releases\n\n下载对应平台的安装包后，在应用内授权或配置 provider，选择端口并启动服务，再把你的客户端指向应用里显示的本地端点即可。发布版桌面应用使用随包内置的 Electron 运行时，正常使用不需要额外安装 Node.js；token usage 历史记录会在该内置运行时支持 SQLite 时启用。\n\n桌面应用里的高级配置页会通过 `GET/POST /admin/config/model-mappings` 读写这份共享的模型映射。同一份映射会统一作用于 `POST /v1/messages`、`POST /v1/messages/count_tokens`、`POST /v1/responses` 和 `POST /v1/chat/completions`，不再按接口区分。它使用的是 `auth.adminApiKey`，不是普通的 `auth.apiKeys`；应用会在服务启动并自动生成该 key 后，直接从 `config.json` 读取它来发起请求。\n\n### 桌面应用截图\n\n下面展示了桌面应用中的首页、Token 用量统计页面：\n\n<p align=\"center\">\n  <img src=\"./docs/screenshots/desktop-dashboard.png\" alt=\"Copilot API 桌面应用首页\" width=\"49%\" />\n  <img src=\"./docs/screenshots/desktop-token-usage.png\" alt=\"Copilot API 桌面应用 Token 用量页\" width=\"49%\" />\n</p>\n\n## 与 Claude Code 一起使用\n\n这个 AI gateway 可以为 [Claude Code](https://docs.anthropic.com/en/claude-code) 提供后端能力。Claude Code 是 Anthropic 提供的实验性面向开发者的对话式 AI 助手。\n\n有两种方式可以把 Claude Code 配置为使用这个 AI gateway：\n\n### 通过 `--claude-code` 标志进行交互式配置\n\n执行带 `--claude-code` 的 `start` 命令开始：\n\n```sh\nnpx @jeffreycao/copilot-api@latest start --claude-code\n```\n\n你会被提示选择一个主模型，以及一个用于后台任务的 \"small, fast\" 模型。选择完成后，会有一条命令被复制到剪贴板中。该命令会设置 Claude Code 使用这个 AI gateway 所需的环境变量。\n\n在新的终端中粘贴并执行这条命令，即可启动 Claude Code。\n\n<a id=\"manual-configuration-with-settingsjson\"></a>\n\n### 通过 `settings.json` 手动配置\n\n另一种方式是在项目根目录中创建 `.claude/settings.json` 文件，并写入 Claude Code 所需的环境变量。这样你就不需要每次都运行交互式配置了。\n\n下面是一个 `.claude/settings.json` 示例：\n\n```json\n{\n  \"env\": {\n    \"ANTHROPIC_BASE_URL\": \"http://localhost:4141\",\n    \"ANTHROPIC_AUTH_TOKEN\": \"dummy\",\n    \"ANTHROPIC_MODEL\": \"deepseek/deepseek-v4-pro\",\n    \"ANTHROPIC_DEFAULT_SONNET_MODEL\": \"deepseek/deepseek-v4-pro\",\n    \"ANTHROPIC_DEFAULT_HAIKU_MODEL\": \"deepseek/deepseek-v4-flash\",\n    \"CLAUDE_CODE_USE_VERTEX\": \"0\",\n    \"CLAUDE_CODE_USE_BEDROCK\": \"0\",\n    \"DISABLE_NON_ESSENTIAL_MODEL_CALLS\": \"1\",\n    \"CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC\": \"1\",\n    \"CLAUDE_CODE_ATTRIBUTION_HEADER\": \"0\",\n    \"CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION\": \"false\",\n    \"CLAUDE_CODE_DISABLE_TERMINAL_TITLE\": \"true\",\n    \"CLAUDE_CODE_ENABLE_AWAY_SUMMARY\": \"0\"\n  },\n  \"permissions\": {\n    \"deny\": [\n      \"mcp__ide__executeCode\"\n    ]\n  }\n}\n```\n\n- 请根据需要替换 `ANTHROPIC_MODEL`、`ANTHROPIC_DEFAULT_OPUS_MODEL`、`ANTHROPIC_DEFAULT_SONNET_MODEL` 和 `ANTHROPIC_DEFAULT_HAIKU_MODEL`。配置完成后，请安装 claude code 插件，见 [插件集成](#plugin-integrations)。\n- 将 `CLAUDE_CODE_ATTRIBUTION_HEADER` 设为 `0` 可以阻止 Claude Code 在 system prompt 中附加计费和版本信息，从而避免 prompt cache 失效。\n- 关闭 `CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION` 和 `CLAUDE_CODE_ENABLE_AWAY_SUMMARY` 可以避免不必要地消耗额度。\n- Claude Code WebSearch 已支持纯搜索请求。Copilot 路径请保持全局 `messageApiWebSearchModel` 指向 Responses-capable GPT 模型或 `provider/model` 别名；provider 路由请使用原生 Anthropic provider 或 `openai-responses` provider。只有在你明确想禁止这类流量时，才需要把 `WebSearch` 加到 `permissions.deny`。\n- 如果使用的不是 Claude 模型，请不要启用 `ENABLE_TOOL_SEARCH`。如果使用的是 Claude 模型，则可以启用 `ENABLE_TOOL_SEARCH`。当前 Claude Code 使用的是客户端 tool search 模式，在该模式下每次加载 defer tools 都需要额外请求一次。\n- `CLAUDE_CODE_AUTO_COMPACT_WINDOW`：设置用于自动压缩计算的上下文容量（以 token 为单位）。默认使用模型自身的上下文窗口：标准模型为 200K，扩展上下文模型为 1M。使用 1M 上下文模型（如 `claude-opus-4-6[1m]`）时，可设置一个较低的值（如 `500000`）将窗口视为 500K 用于压缩计算。该值受限于模型的实际上下文窗口上限。`CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` 会基于此值的百分比生效。设置此变量可将压缩阈值与状态栏的 `used_percentage` 解耦（后者始终使用模型的完整上下文窗口）。\n\n更多选项见：[Claude Code settings](https://docs.anthropic.com/en/docs/claude-code/settings#environment-variables)\n\n也可以参考 IDE 集成说明：[Add Claude Code to your IDE](https://docs.anthropic.com/en/docs/claude-code/ide-integrations)\n\n## 与 OpenCode 一起使用\n\nOpenCode 已经有直接的 GitHub Copilot provider。本节适用于你希望让 OpenCode 通过 `@ai-sdk/anthropic` 指向这个 AI gateway，并复用本 README 前面提到的 agent 行为时。\n\n### 最小配置\n\n使用 OpenCode OAuth app 启动 AI gateway：\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth --oauth-app=opencode\nnpx @jeffreycao/copilot-api@latest start\n```\n\n然后让 OpenCode 通过 `@ai-sdk/anthropic` 指向这个 AI gateway。\n\n示例 `~/.config/opencode/opencode.json`：\n\n```json\n{\n  \"$schema\": \"https://opencode.ai/config.json\",\n  \"provider\": {\n    \"local\": {\n      \"npm\": \"@ai-sdk/anthropic\",\n      \"name\": \"My Local\",\n      \"options\": {\n        \"baseURL\": \"http://localhost:4141/v1\",\n        \"apiKey\": \"dummy\"\n      },\n      \"models\": {\n        \"gpt-5.4\": {\n          \"name\": \"gpt-5.4\",\n          \"modalities\": {\n            \"input\": [\"text\", \"image\"],\n            \"output\": [\"text\"]\n          },\n          \"limit\": {\n            \"context\": 400000,\n            \"input\": 272000,\n            \"output\": 128000\n          }\n        },\n        \"claude-sonnet-4.6\": {\n          \"id\": \"claude-sonnet-4.6\",\n          \"name\": \"claude-sonnet-4.6\",\n          \"modalities\": {\n            \"input\": [\"text\", \"image\"],\n            \"output\": [\"text\"]\n          },\n          \"limit\": {\n            \"context\": 200000,\n            \"output\": 32000\n          },\n          \"options\": {\n            \"thinking\": {\n              \"type\": \"adaptive\"\n            },\n            \"effort\": \"max\"\n          }\n        }\n      }\n    }\n  }\n}\n```\n\n这些字段的重要性：\n\n- `npm: \"@ai-sdk/anthropic\"` 是关键。OpenCode 会以 Anthropic Messages 语义与这个 AI gateway 通信，而不是把一切扁平化为 OpenAI Chat Completions。\n- `options.baseURL` 应设为 `http://localhost:4141/v1`；Anthropic SDK 会自动补上 `/messages`、`/models` 和 `/messages/count_tokens`。\n- 如果你在此代理中启用了 `auth.apiKeys`，请把 `dummy` 替换为真实 key；否则任意占位值都可以。\n\n## 与 Codex 一起使用\n\n这个 AI gateway 也可以为 Codex 提供后端能力。\n\n### Codex `config.toml` 参考配置\n\n把以下 `[model_providers.copilot_api]` 段加入你的 Codex `~/.codex/config.toml`：\n\n```toml\nmodel_provider = \"copilot_api\"\nmodel_reasoning_summary = \"auto\"\nmodel_context_window = 272000\nmodel_auto_compact_token_limit = 244800\n\n[model_providers.copilot_api]\nname = \"OpenAI\"\nbase_url = \"http://localhost:4141\"\nenv_key = \"GITHUB_COPILOT_API_KEY\"\nrequires_openai_auth = true\nsupports_websockets = false\nwire_api = \"responses\"\nrequest_max_retries = 3\nstream_max_retries = 1\nstream_idle_timeout_ms = 300000\n\n[features]\nremote_compaction_v2 = true\n\n[analytics]\nenabled = false\n```\n\n> [!NOTE]\n> 此配置仅限于 Codex 与 GitHub Copilot provider。`name` 一定要配置为 `\"OpenAI\"`。它可以缓解 Codex local compact 不命中缓存的问题。\n> 如果使用 codex provider，建议将 `base_url` 配置为 `\"http://localhost:4141/codex\"`。\n\n## GPT Tool Search\n\n对于 `gpt-5.4+` 这类 GPT Responses 模型，这个 AI gateway 可以通过一个很小的 MCP bridge 暴露 Responses `tool_search`。Claude Code 和 opencode 都可以使用同一个 bridge，前提是客户端会加载 MCP server，并且 Anthropic Messages 流量会经过这个 AI gateway。\n\nGPT 模型不要设置 Claude Code 原生的 `ENABLE_TOOL_SEARCH`。这个开关启用的是 Claude Code 自己的客户端 tool search 模式，可能导致 deferred 工具定义不再转发给 AI gateway。这个 AI gateway 需要完整的工具定义，这样才能只保留那一小组常驻加载工具，其余工具统一转换为 Responses deferred namespace。\n\n如果你安装了 `tool-search@copilot-api-marketplace`，Claude Code 会自动带上这个 MCP bridge，可以跳过下面这段 Claude Code MCP 手动配置。\n\n请把 tool search bridge 加到 Claude Code 使用的 MCP 配置中：\n\n```json\n{\n  \"mcpServers\": {\n    \"tool_search\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@jeffreycao/copilot-api@latest\", \"mcp\"]\n    }\n  }\n}\n```\n\n请把 tool search bridge 加到 opencode 使用的 MCP 配置中：\n\n```json\n{\n  \"mcp\": {\n    \"tool_search\": {\n      \"type\": \"local\",\n      \"command\": [\"npx\", \"-y\", \"@jeffreycao/copilot-api@latest\", \"mcp\"]\n    }\n  }\n}\n```\n\n本地开发时可以将命令换成 `bun`，参数换成 `[\"run\", \"./src/main.ts\", \"mcp\"]`。\n\nAI gateway 内部现在会把 OpenAI Responses `tool_search` 配置成 client-executed 模式。deferred tools 仍然会作为可搜索 namespace 暴露给模型，但会明确要求模型直接返回下一步要加载的精确工具名列表。\n\n该 bridge 使用直接工具选择，不做 query 搜索。工具入参是 `names`，值为逗号分隔的精确 deferred 工具名，例如 `TaskList,TaskGet,mcp__fetch__fetch`。\n\n<a id=\"plugin-integrations\"></a>\n\n## 插件集成\n\n本项目为 Claude Code 和 opencode 提供了插件集成。\n\n#### Claude Code 插件集成（基于 marketplace）\n\nClaude Code 集成现在拆分为两个插件：\n\n- `agent-inject` 会在 `SubagentStart` 时注入 `__SUBAGENT_MARKER__...`，以便 AI gateway 推导 `x-initiator: agent`。\n- `tool-search` 会注册用于 GPT Responses deferred tool loading 的 `tool_search` MCP bridge。\n\n- 本仓库中的 marketplace catalog：`.claude-plugin/marketplace.json`\n- 本仓库中的插件源码：`plugin/claude/agent-inject`、`plugin/claude/tool-search`\n\n远程添加 marketplace：\n\n```sh\n/plugin marketplace add https://github.com/caozhiyuan/copilot-api.git\n```\n\n从 marketplace 安装插件：\n\n```sh\n/plugin install agent-inject@copilot-api-marketplace\n/plugin install tool-search@copilot-api-marketplace\n```\n\n安装后，`agent-inject` 会在 `SubagentStart` 时注入 `__SUBAGENT_MARKER__...`，AI gateway 会利用它推导 `x-initiator: agent`。\n\n`agent-inject` 还会注册一个 `UserPromptSubmit` hook，并返回 `{\"continue\": true}`；同时它也可以通过环境变量注入 `SessionStart` reminder 规则：\n\n- `CLAUDE_PLUGIN_ENABLE_QUESTION_RULES=1` 会自动为 Claude Code 启用两条关于使用 `question` 工具的提醒。你也可以把同样的提醒手动写进 `CLAUDE.md`；见 [CLAUDE.md 或 AGENTS.md 推荐内容](#claudemd-or-agentsmd-recommended-content)。\n- `CLAUDE_PLUGIN_ENABLE_NO_BACKGROUND_AGENTS_RULE=1` 会启用关于避免在 agent hooks 中使用 `run_in_background: true` 的提醒。\n\n`tool-search` 插件内置了 [GPT Tool Search](#gpt-tool-search) 一节描述的同一个 MCP bridge，因此安装该插件后，Claude Code 用户无需再手动配置 `tool_search` server。\n\n#### Opencode 插件\n\nsubagent 标记生成器被打包为一个 opencode 插件，位于 `plugin/opencode/subagent-marker.js`。\n\n**安装方式：**\n\n将插件文件复制到你的 opencode 插件目录：\n\n```sh\n# 克隆或下载本仓库后复制该插件\ncp plugin/opencode/subagent-marker.js ~/.config/opencode/plugins/\n```\n\n或者手动在 `~/.config/opencode/plugins/subagent-marker.js` 创建该文件，并填入插件内容。\n\n**功能：**\n\n- 跟踪 subagent 创建的子会话\n- 自动在 subagent 聊天消息前添加 marker system reminder（`__SUBAGENT_MARKER__...`）\n- 设置 `x-session-id` 请求头以跟踪会话\n- 让这个 AI gateway 能够把来自 subagent 的请求识别为 `x-initiator: agent`\n\n该插件会挂接到 `session.created`、`session.deleted`、`chat.message` 和 `chat.headers` 事件上，以无缝提供 subagent marker 能力。\n\n## 使用量查看器\n\n服务启动后，控制台会输出一个 Copilot 使用量看板 URL。这个看板是一个用于监控 API 用量的 Web 界面。\n\n1. 启动服务。例如使用 npx：\n   ```sh\n   npx @jeffreycao/copilot-api@latest start\n   ```\n2. 服务会输出一个 usage viewer 的 URL。将它复制到浏览器中打开，形式大致如下：\n   `http://localhost:4141/usage-viewer?endpoint=http://localhost:4141/usage`\n   - 如果你在 Windows 上使用 `start.bat` 脚本，这个页面会自动打开。\n\n看板提供了更易读的 Copilot 用量视图：\n\n> token usage 历史记录需要 Bun 或 Node.js >= 22.13.0。Node.js < 22.13.0 时服务会正常运行，但 token usage 存储会被禁用。\n\n- **API Endpoint URL**：通过 URL 查询参数指定 API endpoints，默认指向本地服务。支持手动切换为其他兼容 endpoints。\n- **x-api-key 认证**：如果启用了 API Key 认证，可填入 `x-api-key` 请求头。密钥会持久化保存在浏览器本地存储中。\n- **Period 选择器**：支持 Day / Week / Month 三种时间范围，切换时 URL 参数会自动同步，方便收藏和分享。\n- **Fetch Data**：点击 \"Refresh\" 按钮加载或刷新使用数据。页面加载时也会自动拉取数据。\n- **Copilot Quotas 额度**：通过进度条展示 Chat、Completions 等不同服务的额度使用情况，悬停可查看已用/剩余详情。\n- **Token Usage 指标卡片**：汇总当前周期的 Total、Input、Output、Cache Read、Cache Write、Requests 和预估费用。\n- **趋势图（Week / Month）**：提供按模型和指标筛选的折线趋势图，点击数据点可查看单日用量明细。\n- **Model Breakdown 表格**：按模型维度列出周期内的请求数、输入/输出/缓存 token 和预计费用。\n- **Request Events 分页列表**：按时间排序的请求事件记录，支持分页浏览，含时间戳、模型、请求 ID 和 token 用量。\n- **Detailed Information**：展示 API 返回的完整 JSON 响应，便于深入分析所有可用统计数据。\n- **URL-based Configuration**：也可通过 `endpoint` 和 `period` 查询参数直接指定 API 端点与时间范围。例如：\n  `http://localhost:4141/usage-viewer?endpoint=http://your-api-server/usage&period=week`\n\n### Usage Viewer 截图\n\n<p align=\"center\">\n  <img src=\"./docs/screenshots/usage-viewer.png\" alt=\"Copilot API Usage Viewer 页面\" width=\"900\" />\n</p>\n\n## 命令结构\n\nCopilot API 现在使用子命令结构，主要命令包括：\n\n- `start`：启动 AI gateway 服务。如果已有 GitHub token，则启用 Copilot 路径；如果没有 GitHub token，但存在至少一个启用中的 provider，则按 provider-only 模式启动；如果两者都没有，会引导你配置 provider。\n- `auth`：仅执行 provider 登录或配置流程，不启动服务。可用于 GitHub Copilot 登录、Codex OAuth，或第三方 provider API key 配置。\n- `debug`：显示诊断信息，包括版本、运行时详情、文件路径以及认证状态，便于排障与支持。\n\n## 命令行选项\n\n### 全局选项\n\n以下选项可用于任意子命令。若在子命令之前传入，请使用 `--key=value` 形式：\n\n| 选项 | 说明 | 默认值 | 别名 |\n| --- | --- | --- | --- |\n| --api-home | API home 目录路径（设置 `COPILOT_API_HOME`） | 无 | 无 |\n| --oauth-app | OAuth app 标识符（设置 `COPILOT_API_OAUTH_APP`） | 无 | 无 |\n| --enterprise-url | GitHub Enterprise URL（设置 `COPILOT_API_ENTERPRISE_URL`） | 无 | 无 |\n\n### Start 命令选项\n\n以下是 `start` 命令可用的命令行选项：\n\n| 选项 | 说明 | 默认值 | 别名 |\n| --- | --- | --- | --- |\n| --port | 监听端口 | 4141 | -p |\n| --verbose | 启用详细日志 | false | -v |\n| --github-token | 直接提供 GitHub token（必须通过 `auth` 子命令生成） | 无 | -g |\n| --claude-code | 生成一个使用 Copilot API 配置启动 Claude Code 的命令 | false | -c |\n| --show-token | 在获取和刷新时显示 GitHub 与 Copilot token | false | 无 |\n| --proxy-env | 从环境变量初始化代理 | false | 无 |\n\n### Auth 命令选项\n\n| 选项 | 说明 | 默认值 | 别名 |\n| --- | --- | --- | --- |\n| --provider | 要登录或配置的 provider（`copilot`、`codex`、`opencode-go`、`deepseek`、`dashscope`、`openrouter` 或 `custom`） | 交互选择 | 无 |\n| --verbose | 启用详细日志 | false | -v |\n| --show-token | 认证时显示 GitHub token | false | 无 |\n\n只有在需要启用 GitHub Copilot provider 时，才需要执行 `copilot-api auth login --provider copilot`。使用 `codex` 或第三方 provider-only 模式不要求配置 Copilot。\n\n使用 `copilot-api auth login --provider deepseek`、`--provider dashscope`、`--provider openrouter` 或 `--provider opencode-go` 可以通过 CLI 快速新增或更新这些常用第三方 provider。DeepSeek 会提示输入掩码显示的 `apiKey`、provider `type`（默认 `anthropic`），以及默认 `https://api.deepseek.com/anthropic` 的 `baseUrl`。DashScope 会提示输入掩码显示的 `apiKey`、provider `type`（默认 `openai-compatible`）和预填默认值的 `baseUrl`。OpenRouter 只提示输入掩码显示的 `apiKey` 和预填默认值的 `baseUrl`，并固定写入 `type: \"anthropic\"`。OpenCode Go 只提示输入掩码显示的 `apiKey` 和预填默认值的 `baseUrl`，并固定写入 `type: \"openai-compatible\"`（baseUrl `https://opencode.ai/zen/go`）。配置并启用 provider 后，`copilot-api start` 可在没有 GitHub token 的情况下启动。\n\n使用 `copilot-api auth login --provider custom` 可以通过 CLI 新增或更新其他第三方 provider。命令会依次提示输入 provider name、项目支持的 type（`anthropic`、`openai-compatible` 或 `openai-responses`）、`baseUrl`、掩码显示的 `apiKey` 和 `authType`；`authType` 可保持 type 默认值，也可选择 `x-api-key` / `authorization`。\n\n### Debug 命令选项\n\n| 选项 | 说明 | 默认值 | 别名 |\n| --- | --- | --- | --- |\n| --json | 以 JSON 输出调试信息 | false | 无 |\n\n<a id=\"configuration-configjson\"></a>\n\n## 配置（config.json）\n\n- **位置：** Linux/macOS 为 `~/.local/share/copilot-api/config.json`，Windows 为 `%USERPROFILE%\\.local\\share\\copilot-api\\config.json`。\n- **默认结构：**\n  ```json\n  {\n    \"auth\": {\n      \"apiKeys\": [],\n      \"adminApiKey\": \"<startup 自动生成>\"\n    },\n    \"providers\": {},\n    \"modelMappings\": {},\n    \"extraPrompts\": {\n      \"gpt-5-mini\": \"<built-in exploration prompt>\"\n    },\n    \"smallModel\": \"gpt-5-mini\",\n    \"contextManagement\": {\n      \"messages\": true,\n      \"responses\": false\n    },\n    \"modelResponsesApiCompactThresholds\": {\n      \"gpt-5.4\": 217600,\n      \"gpt-5.5\": 217600,\n      \"gpt-5.6-sol\": 231200,\n      \"gpt-5.6-terra\": 231200,\n      \"gpt-5.6-luna\": 231200\n    },\n    \"modelReasoningEfforts\": {\n      \"gpt-5-mini\": \"low\"\n    },\n    \"useMessagesApi\": true,\n    \"useResponsesApiWebSocket\": true,\n    \"useResponsesApiWebSearch\": true,\n    \"messageApiWebSearchModel\": \"gpt-5-mini\"\n  }\n  ```\n- **auth.apiKeys：** 用于普通非 admin 路由的 API key。支持多个 key 轮换使用。请求可通过 `x-api-key: <key>` 或 `Authorization: Bearer <key>` 进行认证。若为空或省略，则普通路由的认证会被禁用。\n- **auth.adminApiKey：** 仅用于 `/admin/*` 路由的单个 admin key。若未配置，服务会在启动时自动生成一个随机 key，并回写到 `config.json`。它同样使用 `x-api-key` 或 `Authorization: Bearer` 这两种头，但普通 `auth.apiKeys` 不能访问 `/admin/*`。\n- **modelMappings：** 用于顶层 `POST /v1/messages`、`POST /v1/messages/count_tokens`、`POST /v1/responses` 和 `POST /v1/chat/completions` 请求的精确 `sourceModel -> targetModel` 重写映射，这几类接口共用同一份规则。省略该字段或保留为 `{}` 时，不会做模型重写。`source` 和 `target` 都必须是非空字符串。`target` 可以是普通模型 ID，也可以是 `provider/model` 形式的别名，例如 `dashscope/qwen3.6-plus`；重写发生在 provider alias 解析之前。这些映射不再按接口区分。`GET/POST /admin/config/model-mappings` 管理接口读写的也只有这个字段。\n- **extraPrompts：** `model -> prompt` 的映射。把 Anthropic 风格请求翻译为 Responses API 时，会将其附加到第一条 system prompt 后面。你可以借此为不同模型注入护栏或指引。缺失的默认项会自动补齐，但不会覆盖你自定义的 prompt。对于 GPT-5.3+ 模型（如 `gpt-5.3-codex`、`gpt-5.4`、`gpt-5.5`），未显式配置时会自动使用内置的 commentary prompt。内置 prompt 会启用带阶段感知的 commentary，让模型在工具调用或更深层推理前先发出简短的用户可见进度说明。\n- **providers：** 全局上游 provider 映射。每个 provider key（例如 `dashscope`）都会变成一个路由前缀（`/dashscope/v1/messages`）。支持 `type: \"anthropic\"`、`type: \"openai-compatible\"` 和 `type: \"openai-responses\"`。顶层客户端也可以在 `/v1/messages`、`/v1/messages/count_tokens`、`/v1/responses` 和 `/v1/chat/completions` 中使用 `model: \"dashscope/model-id\"`；AI gateway 会在转发上游前移除 `dashscope/` 前缀。`openai-compatible` provider 同时支持 chat 和 Messages 流程：`/v1/chat/completions` 会直连上游 `/v1/chat/completions`，而 `/v1/messages` 和 `/:provider/v1/messages` 会先翻译为上游 Chat Completions，再把响应翻译回 Anthropic Messages。`GET /v1/models` 会聚合已启用 provider 的模型，并以 `provider/model-id` 形式返回；单个 provider 的原始模型列表仍可使用 `GET /dashscope/v1/models`。\n  - `enabled`：可选，若省略则默认为 `true`。\n  - `baseUrl`：provider API 的基础 URL，不要带结尾的 endpoint。Anthropic provider 不要带 `/v1/messages`；OpenAI 兼容 provider 不要带 `/v1/chat/completions`；OpenAI Responses provider 不要带 `/v1/responses`。\n  - `apiKey`：作为上游凭据值使用；普通 provider 必须配置。\n  - `authType`：可选，控制 `apiKey` 如何发送到上游。普通 provider 支持 `x-api-key` 和 `authorization`。Anthropic provider 默认 `x-api-key`；OpenAI 兼容和 OpenAI Responses provider 默认 `authorization`。当设置为 `authorization` 时，代理会发送 `Authorization: Bearer <apiKey>`。`oauth2` 仅保留给内置 `codex` provider，并由 `auth login --provider codex` 自动写入。\n  - `pricingCurrency`：可选，provider 维度的 token 费用币种，例如 `USD` 或 `CNY`。快捷 provider 默认 DashScope、DeepSeek 为 `CNY`，Codex/OpenRouter 为 `USD`。费用按币种分别汇总，不做汇率换算。\n  - `models`：可选，按模型 ID 配置的映射。每个键为请求中的模型名，值支持：\n    - `temperature`：可选，当请求未指定时使用的默认温度。\n    - `topP`：可选，当请求未指定时使用的默认 `top_p`。\n    - `topK`：可选，当请求未指定时使用的默认 `top_k`。\n    - `extraBody`：可选，按模型合入上游请求体的动态字段；请求体显式同名字段优先。OpenAI 兼容 provider 可用它配置 `enable_thinking`、`preserve_thinking`、`reasoning_effort` 等字段。`thinking_budget` 是 OpenAI 兼容 provider 的特殊覆盖项：配置在 `extraBody` 后，会在 Anthropic `thinking.budget_tokens` 翻译之后强制写入，并覆盖请求派生出的预算值。对于 provider name 为 `dashscope` 或 `baseUrl` 包含 `aliyuncs.com` 的 provider，请求派生的 `thinking_budget`（来自 Anthropic `thinking.budget_tokens`）会转发给上游；其他 OpenAI 兼容 provider 会移除请求派生的 `thinking_budget`，但 `extraBody` 中的 `thinking_budget` 仍然生效。对于 DashScope provider，当 `preserve_thinking` 未在 `extraBody` 或请求体中显式设置时，默认为 `true`。\n    - `pricing`：可选，按模型配置 token 单价，币种使用 provider 的 `pricingCurrency`，单位为每 100 万 tokens。支持 `input`、`output`、`cachedInput`（隐式缓存读）、`explicitCachedInput`（显式缓存读）和 `cacheCreationInput`。如需按输入 token 总量分档，可用带 `maxInputTokens` 的 `tiers`。\n    - `contextCache`：可选，provider name 为 `dashscope` 或 `baseUrl` 包含 `aliyuncs.com` 时默认 `true`，其他 OpenAI 兼容 provider 默认 `false`。用于启用阿里云百炼/DashScope 的显式缓存（explicit context cache），会按其 Context Cache 格式在最多 4 个 content block 上注入 `cache_control: { \"type\": \"ephemeral\" }`。缓存断点策略与 opencode 主链路保持一致：前 2 条 system 消息 + 最后 2 条非 system 消息。标记字符串 content 时会把 `system` / `user` / `assistant` / `tool` 消息转换为 text content part 数组；已有数组 content 则标记最后一个 part。如果模型本身已经支持隐式缓存，或上游不支持该显式缓存扩展字段，可在模型配置中设为 `false`。支持相同显式缓存扩展的非 DashScope provider 可设为 `true`。同时适用于 `/v1/messages` 和 `/v1/chat/completions` 路由。\n    - `supportPdf`：可选，控制该模型是否支持 PDF/document content。默认 `false`，不支持时会把 PDF 转成提示文本；设为 `true` 时会把 PDF/document 转成 OpenAI Chat Completions 的 file part。\n    - `toolContentSupportType`：可选，配置该模型的 tool result content 支持能力，值为 `array`、`image`、`pdf` 的数组。provider 侧未配置时默认只发送 string tool content。若 `supportPdf` 为 `true` 但这里不包含 `pdf`，tool result 里的 file part 会被转成 user role 消息。Copilot 主链路不使用这个 provider 默认，仍按 array + image 且不支持 PDF 的能力处理。\n    - `type`：可选，按模型覆盖 provider 的协议类型。支持 `anthropic`、`openai-compatible` 和 `openai-responses`。设置后，provider 的 `/v1/messages` 路由会使用该模型的 type 替代 provider 级别的 type 进行请求路由、认证头解析和上游端点选择。适用于 OpenCode Go 等上游对不同模型同时支持 OpenAI 兼容和 Anthropic Messages API 的 provider。覆盖 type 时，认证头按覆盖后 type 的默认值解析（Anthropic 默认 `x-api-key`；OpenAI 兼容/Responses 默认 `authorization`）。\n\n  DashScope 模型配置示例：\n  ```json\n  {\n    \"providers\": {\n      \"dashscope\": {\n        \"type\": \"openai-compatible\",\n        \"enabled\": true,\n        \"baseUrl\": \"https://dashscope.aliyuncs.com/compatible-mode\",\n        \"apiKey\": \"sk-your-dashscope-key\",\n        \"pricingCurrency\": \"CNY\",\n        \"models\": {\n          \"qwen3.7-plus\": {\n            \"temperature\": 1,\n            \"topP\": 0.95,\n            \"topK\": 20,\n            \"extraBody\": {\n              \"preserve_thinking\": true\n            }\n          },\n          \"glm-5.1\": {\n            \"temperature\": 0.7,\n            \"topP\": 0.95,\n            \"contextCache\": true,\n            \"pricing\": {\n              \"tiers\": [\n                {\n                  \"maxInputTokens\": 32000,\n                  \"input\": 6,\n                  \"cachedInput\": 1.2,\n                  \"explicitCachedInput\": 0.6,\n                  \"cacheCreationInput\": 7.5,\n                  \"output\": 24\n                },\n                {\n                  \"maxInputTokens\": 200000,\n                  \"input\": 8,\n                  \"cachedInput\": 1.6,\n                  \"explicitCachedInput\": 0.8,\n                  \"cacheCreationInput\": 10,\n                  \"output\": 28\n                }\n              ]\n            },\n            \"extraBody\": {\n              \"preserve_thinking\": true\n            }\n          }\n        }\n      }\n    }\n  }\n  ```\n  内置 token 价格覆盖 Codex GPT 模型（USD）、DashScope `qwen3.7-max`、`qwen3.7-plus`、`glm-5.1`、`glm-5.2`（CNY），DeepSeek `deepseek-v4-flash`、`deepseek-v4-pro`、`deepseek-chat`、`deepseek-reasoner`（CNY），以及 OpenCode Go 模型（`glm-5.2`、`deepseek-v4-flash`、`deepseek-v4-pro`、`kimi-k2.7-code`、`mimo-v2.5`、`mimo-v2.5-pro`、`qwen3.7-plus`、`qwen3.7-max`、`minimax-m2.5`、`minimax-m3`，USD）。用户配置的 `pricing` 优先于内置价格。DashScope 若上游 usage 中出现 `cache_creation_input_tokens` 字段，cached tokens 按显式缓存读价计费；否则 `cachedInput` 作为隐式缓存读价。DeepSeek 的 `prompt_cache_hit_tokens` 会归入 cached input，`prompt_cache_miss_tokens` 会归入普通 input。\n- **smallModel：** 无工具预热消息的回退模型（例如 Claude Code 的探测请求）；默认是 `gpt-5-mini`。\n- **contextManagement：** 控制代理是否为 Responses API 附加 `context_management` 压缩指令。`messages` 作用于被翻译成 Responses API 的 Anthropic 风格 `/v1/messages` 请求，包括 `openai-responses` provider 的 Messages 路由，默认值为 `true`。`responses` 作用于 native `/v1/responses` 流量，包括 `provider/model` 别名和内置 `codex` provider，默认值为 `false`。只有在确认客户端支持 context management compaction 后，才建议在 Responses API 下启用 `responses`。启用后，请求体会带上 `context_management`，并在后续轮次中仅保留最新的压缩承载内容。**注意：** 对于 GPT-5.6 及以上模型（如 `gpt-5.6-sol`、`gpt-5.6-terra`、`gpt-5.6-luna`），context management 功能会被强制禁用，因为开启后会破坏这些模型的 prompt 缓存命中。此强制覆盖优先于 `contextManagement` 和 `modelResponsesApiCompactThresholds` 配置。\n- **modelResponsesApiCompactThresholds：** 按模型覆盖 Responses API 的 `compact_threshold`，仅在代理自动附加 `context_management` 时使用。它的优先级高于 `resolveResponsesCompactThreshold` 基于 `max_prompt_tokens * ratio` 的兜底阈值。默认将 `gpt-5.4` 和 `gpt-5.5` 设为 `217600`（`272000 * 0.8`），将 `gpt-5.6-sol`、`gpt-5.6-terra`、`gpt-5.6-luna` 设为 `231200`（`272000 * 0.85`）。未列出的模型继续使用原有兜底逻辑。\n- **modelReasoningEfforts：** `/v1/messages` 请求的模型级默认推理强度。仅当请求没有传入 `output_config.effort` 时，该配置才会生效。\n  - **优先级：** 请求中的 `output_config.effort` > `modelReasoningEfforts[model]` > 内置默认值（GPT-5.3+ 模型为 `xhigh`，其他模型为 `high`）。\n  - **转发字段：** 走 Copilot 原生 Messages API 时，最终值写入 `output_config.effort`；转换为 Responses API 时，最终值写入 `reasoning.effort`。\n  - **配置可选值：** `none`、`minimal`、`low`、`medium`、`high`、`xhigh`、`max`。\n- **useMessagesApi：** 当为 `true` 时，支持 Copilot 原生 `/v1/messages` 的 Claude 系模型会走 Messages API；否则回退到 `/chat/completions`。设为 `false` 可禁用 Messages API 路由，始终使用 `/chat/completions`。默认值为 `true`。\n- **useResponsesApiWebSocket：** 当为 `true` 时，Responses API 请求会优先对声明了 `ws:/responses` 的模型使用 Copilot websocket transport；仅声明 `/responses` 的模型仍走 HTTP。设为 `false` 可禁用 websocket 路由，并在模型支持 `/responses` 时使用 HTTP `/responses`。默认值为 `true`。如果遇到 Responses API WebSocket closed，一般是自己的网络问题。如果使用了 VPN，建议切换节点。\n- **useResponsesApiWebSearch：** 当为 `true` 时，服务端会保留 Responses API 中 `type: \"web_search\"` 的工具并透传到上游。设为 `false` 则会从 `/responses` payload 中移除这些工具。默认值为 `true`。\n- **messageApiWebSearchModel：** 顶层 Copilot `/v1/messages` 请求只包含服务端 `web_search` 工具时使用的全局模型，默认值为 `gpt-5-mini`。如果该值是 `provider/model` 别名，请求会进入对应 provider 的 Messages API 路径，并在转发前移除 provider 前缀。对于 Copilot GPT 模型，web search 会通过 `/responses` 执行。混合 `web_search` 与自定义工具的场景暂不支持，服务端会移除 server-side `web_search`。\n- **claudeTokenMultiplier：** 用于 Claude `/v1/messages/count_tokens` 请求在本地走 GPT tokenizer 估算时的乘数。默认值为 `1.15`。如果你的客户端仍然过晚触发上下文压缩，可以适当调大。这个配置只会在代理本地估算 Claude token 时生效；如果已经配置 `anthropicApiKey` 且 Anthropic token counting 调用成功，则会直接返回 Anthropic 的精确计数，不会使用这个乘数。\n- **anthropicApiKey：** 用于把 Claude `/v1/messages/count_tokens` 请求转发到 Anthropic 真实 token counting 端点的 API key，这样会返回精确计数，而不是 GPT tokenizer 估算值。也可通过环境变量 `ANTHROPIC_API_KEY` 设置。若未配置，或上游调用失败，则回退到由 `claudeTokenMultiplier` 控制的本地 GPT tokenizer 估算。\n\n编辑此文件后即可自定义 prompts，或替换为你自己的快速模型。修改完成后请重启服务（或重新执行命令），让缓存中的配置刷新生效。\n\n## API 认证\n\n- **受保护的普通路由：** 当配置了 `auth.apiKeys` 且非空时，除 `/`、`/usage-viewer` 和 `/usage-viewer/` 以外的普通路由都需要认证。\n- **Admin 路由：** 所有 `/admin/*` 路由都要求 `auth.adminApiKey`。如果缺失，服务会在启动时自动生成并在开始提供服务前写回 `config.json`。\n- **允许的认证头：**\n  - `x-api-key: <your_key>`\n  - `Authorization: Bearer <your_key>`\n- **CORS 预检：** `OPTIONS` 请求始终允许。\n- **未配置普通 key 时：** 普通路由仍可直接访问；但这条规则不适用于 `/admin/*`，后者只接受 `auth.adminApiKey`。\n\n普通受保护路由的示例请求：\n\n```sh\ncurl http://localhost:4141/v1/models \\\n  -H \"x-api-key: your_api_key\"\n```\n\nAdmin 路由的示例请求：\n\n```sh\ncurl http://localhost:4141/admin/config/model-mappings \\\n  -H \"x-api-key: your_admin_api_key\"\n```\n\n## API 端点\n\n服务端提供多个 OpenAI / Anthropic 兼容端点。请求会根据所选模型和 `provider/model` 别名路由到 GitHub Copilot、内置 `codex` provider 或已配置的 provider。\n\n### OpenAI 兼容端点\n\n这些端点模拟 OpenAI API 结构。\n\n| 端点 | 方法 | 说明 |\n| --- | --- | --- |\n| `POST /v1/responses` | `POST` | OpenAI 中用于生成模型响应的高级接口。支持 `openai-responses` provider 的 `provider/model` 别名。 |\n| `POST /v1/chat/completions` | `POST` | 为给定聊天对话创建模型响应。支持 `openai-compatible` provider 的 `provider/model` 别名；目标 provider 已配置时可在没有 Copilot 的情况下使用。 |\n| `GET /v1/models` | `GET` | 列出 Copilot 模型以及已启用 provider 的 `provider/model-id` 模型。来自 Codex 客户端（`User-Agent` 以 `codex` 开头）的请求会转发到 Codex Models 上游。 |\n| `POST /v1/embeddings` | `POST` | 创建表示输入文本的向量嵌入。 |\n\n### Codex 后端代理端点\n\n这些端点要求已有可用的 Codex 登录态。每个端点同时提供无版本前缀和 `/v1` 两种路径。\n\n| 端点 | 方法 | 说明 |\n| --- | --- | --- |\n| `POST /alpha/search`<br>`POST /v1/alpha/search` | `POST` | 将 JSON 请求体和查询参数透明转发到 Codex Alpha Search 上游。 |\n| `POST /images/generations`<br>`POST /v1/images/generations` | `POST` | 将 JSON 图片生成请求转发到 Codex Images 上游。请求未携带 `Content-Type` 时，网关默认补充 `application/json`。 |\n| `POST /images/edits`<br>`POST /v1/images/edits` | `POST` | 将图片编辑请求转发到 Codex Images 上游。请使用 `multipart/form-data`，并让 HTTP 客户端自动生成 `boundary`；网关会保留传入的 content type，并以流式方式转发上传请求体。 |\n\n对于以上所有端点，网关都会使用当前 Codex 登录态覆盖客户端的 authorization 和 account header，保留查询参数及兼容的请求头，并返回上游状态码、响应头和响应体。\n\n### Anthropic 兼容端点\n\n这些端点设计为兼容 Anthropic Messages API。provider 级的 models、Responses、alpha-search 和 images 路由同时支持无版本前缀与 `/v1` 两种路径；Messages 路由仍使用 `/v1`。\n\n| 端点 | 方法 | 说明 |\n| --- | --- | --- |\n| `POST /v1/messages` | `POST` | 为给定对话创建模型响应。支持已配置 provider 的 `provider/model` 别名，包括通过 `openai-compatible` provider 做翻译。 |\n| `POST /v1/messages/count_tokens` | `POST` | 计算一组消息的 token 数。支持已配置 provider 的 `provider/model` 别名。 |\n| `POST /:provider/v1/messages` | `POST` | 将 Anthropic Messages 请求代理到已配置的 Anthropic provider，或翻译到 OpenAI 兼容 / OpenAI Responses provider。 |\n| `GET /:provider/models`<br>`GET /:provider/v1/models` | `GET` | 将模型列表请求代理到已配置的 provider。对 `codex` 默认返回内置模型目录；Codex 客户端（`User-Agent` 以 `codex` 开头）会转发到 Codex Models 上游。 |\n| `POST /:provider/v1/messages/count_tokens` | `POST` | 为 provider 路由请求在本地计算 token 数。 |\n| `POST /:provider/responses`<br>`POST /:provider/v1/responses` | `POST` | 将 OpenAI Responses 请求代理到已配置的 `openai-responses` provider（含 `codex`）。 |\n| `POST /:provider/alpha/search`<br>`POST /:provider/v1/alpha/search` | `POST` | 代理 alpha-search 请求。对 `codex` 转发到 Codex Alpha Search 上游；其他 provider 转发到 `{baseUrl}/v1/alpha/search`。 |\n| `POST /:provider/images/generations`<br>`POST /:provider/v1/images/generations` | `POST` | 代理图片生成。对 `codex` 使用 Codex Images 上游；其他 provider 转发到 `{baseUrl}/v1/images/generations`（15 分钟超时）。 |\n| `POST /:provider/images/edits`<br>`POST /:provider/v1/images/edits` | `POST` | 代理图片编辑。对 `codex` 使用 Codex Images 上游；其他 provider 以 multipart/流式方式转发到 `{baseUrl}/v1/images/edits`（15 分钟超时）。 |\n\n### 使用量监控端点\n\n用于监控 Copilot 用量与额度的新端点。\n\n| 端点 | 方法 | 说明 |\n| --- | --- | --- |\n| `GET /usage` | `GET` | 获取详细的 Copilot 使用统计与额度信息。 |\n| `GET /token` | `GET` | 获取当前 API 正在使用的 Copilot token。 |\n\n### Admin / 配置端点\n\n这些端点用于本地管理操作，只接受 `auth.adminApiKey`。\n\n| 端点 | 方法 | 说明 |\n| --- | --- | --- |\n| `GET /admin/config/model-mappings` | `GET` | 返回当前 `config.json` 路径以及生效中的 `modelMappings` 映射。 |\n| `POST /admin/config/model-mappings` | `POST` | 只更新 `config.json` 里的 `modelMappings` 字段，并回传更新后的结果。 |\n\n## 使用示例\n\n常用 `npx` 命令：\n\n```sh\n# 基础启动\nnpx @jeffreycao/copilot-api@latest start\n\n# 自定义端口并开启详细日志\nnpx @jeffreycao/copilot-api@latest start --port 8080 --verbose\n\n# 执行认证流程\nnpx @jeffreycao/copilot-api@latest auth login\n\n# 配置第三方 provider，然后不依赖 GitHub Copilot 启动\nnpx @jeffreycao/copilot-api@latest auth login --provider dashscope\nnpx @jeffreycao/copilot-api@latest start\n\n# 以 JSON 格式输出调试信息\nnpx @jeffreycao/copilot-api@latest debug --json\n\n# 用 Bun 而不是 Node.js 运行已发布 CLI\nbunx --bun @jeffreycao/copilot-api@latest start\n```\n\n配置 `dashscope` 后的 OpenAI 兼容 provider 调用示例：\n\n```sh\ncurl http://localhost:4141/v1/chat/completions \\\n  -H \"content-type: application/json\" \\\n  -d '{\"model\":\"dashscope/qwen3.6-plus\",\"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]}'\n\ncurl http://localhost:4141/dashscope/v1/messages \\\n  -H \"content-type: application/json\" \\\n  -d '{\"model\":\"qwen3.6-plus\",\"max_tokens\":1024,\"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]}'\n```\n\n## 使用建议\n\n<a id=\"claudemd-or-agentsmd-recommended-content\"></a>\n\n### CLAUDE.md 或 AGENTS.md 推荐内容\n\n如果你想手动加入这些提醒，请在 Claude Code 的 `CLAUDE.md`，或 opencode/codex 的 `AGENTS.md` 中加入以下内容：\n\n```\n- Prohibited from directly asking questions to users, MUST use question tool.\n- Once you can confirm that the task is complete, MUST use question tool to make user confirm. The user may respond with feedback if they are not satisfied with the result, which you can use to make improvements and try again, after try again, MUST use question tool to make user confirm again.\n```\n"}, "287d2d330c299bbdf3ed213a1bc05b1739aecf03": {"t": 1785765551.9355884, "n": 33098, "h": "2fe26aca204e64ff", "c": "# Copilot API Proxy\n\n[English](./README.md) | 简体中文\n\n## 重要说明\n\n> [!IMPORTANT]\n> **使用前请先注意以下几点：**\n>\n> 1. **Claude Code 配置：** 与 Claude Code 搭配使用时，请将模型 ID 配置为 `claude-opus-4-8`。示例 claude `settings.json` 见 [通过 `settings.json` 手动配置](#manual-configuration-with-settingsjson)。\n>\n> 2. **内置 `copilot`、`codex` 与第三方 provider：** 执行 `npx @jeffreycao/copilot-api@latest auth`，可选择 `copilot`、`codex`、`deepseek`、`custom` 等 provider。\n>\n> 3. **注意事项：** README 顶部移除的 GitHub Copilot warning 见 [GitHub Copilot 安全提示](./NOTICE.md#github-copilot-security-notice)。\n\n---\n\n## 项目概览\n\n这是一个小型 AI gateway，可以使用 GitHub Copilot、内置 `codex` provider，也可以使用 DashScope 等已配置的第三方 provider。GitHub Copilot 现在是可选能力：如果本地没有 GitHub token，只要至少配置了一个启用中的 provider，服务仍可按 provider-only 模式启动。\n\nAI gateway 会从同一个本地端点暴露 OpenAI / Anthropic 兼容 API，让 [Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview)、OpenCode、Codex 和 OpenAI 兼容客户端可以共用同一个本地服务。\n\n在 GitHub Copilot 路径上，AI gateway 会在可用时优先使用 Copilot 原生的 Anthropic 风格 Messages API，在重工具调用场景下保留更原生的 Claude 行为。\n\n## 功能特性\n\n- **OpenAI 与 Anthropic 双兼容**：通过 `/v1/responses`、`/v1/chat/completions`、`/v1/models`、`/v1/embeddings` 和 `/v1/messages` 对外暴露同一个本地 AI gateway。\n- **Copilot 可选**：有 GitHub 凭据时可以使用 GitHub Copilot，没有 GitHub 凭据时也可以只依赖已配置的 provider 运行。\n- **同一网关接入 Copilot、`codex` 与第三方 provider**：可统一路由 GitHub Copilot、内置 `codex` provider 和配置好的外部 provider。\n- **第三方 provider 可独立启动**：配置 DashScope、DeepSeek、OpenRouter 或自定义 provider 后，不需要 GitHub Copilot 登录即可启动 AI gateway。\n- **OpenAI 兼容 provider 同时支持 chat 和 Messages API**：`openai-compatible` provider 可通过顶层 `/v1/chat/completions` 搭配 `model: \"provider/model\"` 提供 Chat Completions，也可通过 `/v1/messages` 完成 Anthropic Messages 的请求/响应翻译。\n- **面向 Claude 的更原生 Copilot 路由**：优先使用原生 `/v1/messages`，保留 Claude 风格工具流，支持 Anthropic beta 能力、通过 Responses-capable 模型支持 Claude WebSearch，并保留 subagent / session 标记。\n- **Claude Code 与 OpenCode 集成**：兼容 Claude Code 与 OpenCode，也支持通过 `@ai-sdk/anthropic` 直接作为 Anthropic provider 使用。\n- **灵活的认证与部署选项**：支持交互式登录、直接 token、个人 / Business / Enterprise、GitHub Enterprise、opencode OAuth 和自定义数据目录。\n- **多 provider 路由**：可暴露 `/:provider/...` 路由，也可在顶层 API 上使用 `model: \"provider/model\"`。\n\n## 前置要求\n\n- Bun（>= 1.2.x）\n- 如果要通过 `npx` 运行已发布 CLI，需要 Node.js\n- 只有在使用 GitHub Copilot provider 时，才需要已订阅 Copilot 的 GitHub 账号\n- 如果不使用 GitHub Copilot，需要至少一个已配置 provider 的 API key 或 OAuth 登录\n\n## 安装\n\n安装依赖：\n\n```sh\nbun install\n```\n\n直接从源码启动服务：\n\n```sh\nbun run start start\n```\n\n## 从源码运行\n\n本项目可以通过多种方式从源码运行：\n\n### 开发模式\n\n```sh\nbun run dev start\n```\n\n### 生产模式\n\n```sh\nbun run start start\n```\n\n## 通过 npx 使用\n\n你可以直接用 npx 运行本项目：\n\n> [!IMPORTANT]\n> 通过 `npx` 运行时，token usage 存储会使用 Node 内置的 `node:sqlite` 模块。该能力会在 Node.js >= 22.13.0 时启用；Node.js < 22.13.0 时 CLI 仍可启动，但会禁用 token usage 存储。\n>\n> 如果不升级 Node.js 但仍需要 token usage 存储，可以改用 Bun 运行已发布 CLI：`bunx --bun @jeffreycao/copilot-api@latest start`。\n\n```sh\nnpx @jeffreycao/copilot-api@latest start\n```\n\n带参数示例：\n\n```sh\nnpx @jeffreycao/copilot-api@latest start --port 8080\n```\n\n如果只想做认证或 provider 配置：\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth\n```\n\n如果要不依赖 GitHub Copilot 运行，先配置至少一个 provider，然后正常启动服务：\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth login --provider dashscope\nnpx @jeffreycao/copilot-api@latest start\n```\n\n## 配合 Docker 使用\n\n构建镜像：\n\n```sh\ndocker build -t copilot-api .\n```\n\n通过 bind mount 运行容器，让认证数据在重启后保留：\n\n```sh\nmkdir -p ./copilot-data\ndocker run -p 4141:4141 -v $(pwd)/copilot-data:/root/.local/share/copilot-api copilot-api\n```\n\n这会把宿主机上的 `./copilot-data` 映射到容器内的 `/root/.local/share/copilot-api`，用于持久化 GitHub 认证数据、provider 配置和其他 gateway 状态。\n\n也可以直接通过环境变量传入 GitHub token：\n\n```sh\ndocker run -p 4141:4141 -e GH_TOKEN=your_github_token_here copilot-api\n```\n\n## Electron 桌面应用\n\n如果你更喜欢图形界面，仓库里还提供了位于 `desktop/` 的 Electron 桌面应用。它支持 GitHub Copilot 登录、OpenAI Codex OAuth，以及 DeepSeek、DashScope、OpenRouter 或自定义 provider 的 API Key 配置。授权或配置 provider 后，可以一键启动或停止本地代理，并在界面里直接查看本地端点、鉴权 Header、可用模型、额度和日志。\n\n设置页还可以配置 `OAuth App`、`API Home`、`Enterprise URL`、详细日志以及最小化到托盘。桌面安装包发布在 GitHub Releases：\n\nhttps://github.com/caozhiyuan/copilot-api/releases\n\n下载对应平台的安装包后，在应用内授权或配置 provider，选择端口并启动服务，再把你的客户端指向应用里显示的本地端点即可。发布版桌面应用使用随包内置的 Electron 运行时，正常使用不需要额外安装 Node.js；token usage 历史记录会在该内置运行时支持 SQLite 时启用。\n\n桌面应用里的高级配置页会通过 `GET/POST /admin/config/model-mappings` 读写这份共享的模型映射。同一份映射会统一作用于 `POST /v1/messages`、`POST /v1/messages/count_tokens`、`POST /v1/responses` 和 `POST /v1/chat/completions`，不再按接口区分。它使用的是 `auth.adminApiKey`，不是普通的 `auth.apiKeys`；应用会在服务启动并自动生成该 key 后，直接从 `config.json` 读取它来发起请求。\n\n### 桌面应用截图\n\n下面展示了桌面应用中的首页、Token 用量统计页面：\n\n<p align=\"center\">\n  <img src=\"./docs/screenshots/desktop-dashboard.png\" alt=\"Copilot API 桌面应用首页\" width=\"49%\" />\n  <img src=\"./docs/screenshots/desktop-token-usage.png\" alt=\"Copilot API 桌面应用 Token 用量页\" width=\"49%\" />\n</p>\n\n## 与 Claude Code 一起使用\n\n这个 AI gateway 可以为 [Claude Code](https://docs.anthropic.com/en/claude-code) 提供后端能力。Claude Code 是 Anthropic 提供的实验性面向开发者的对话式 AI 助手。\n\n有两种方式可以把 Claude Code 配置为使用这个 AI gateway：\n\n### 通过 `--claude-code` 标志进行交互式配置\n\n执行带 `--claude-code` 的 `start` 命令开始：\n\n```sh\nnpx @jeffreycao/copilot-api@latest start --claude-code\n```\n\n你会被提示选择一个主模型，以及一个用于后台任务的 \"small, fast\" 模型。选择完成后，会有一条命令被复制到剪贴板中。该命令会设置 Claude Code 使用这个 AI gateway 所需的环境变量。\n\n在新的终端中粘贴并执行这条命令，即可启动 Claude Code。\n\n<a id=\"manual-configuration-with-settingsjson\"></a>\n\n### 通过 `settings.json` 手动配置\n\n另一种方式是在项目根目录中创建 `.claude/settings.json` 文件，并写入 Claude Code 所需的环境变量。这样你就不需要每次都运行交互式配置了。\n\n下面是一个 `.claude/settings.json` 示例：\n\n```json\n{\n  \"env\": {\n    \"ANTHROPIC_BASE_URL\": \"http://localhost:4141\",\n    \"ANTHROPIC_AUTH_TOKEN\": \"dummy\",\n    \"ANTHROPIC_MODEL\": \"deepseek/deepseek-v4-pro\",\n    \"ANTHROPIC_DEFAULT_SONNET_MODEL\": \"deepseek/deepseek-v4-pro\",\n    \"ANTHROPIC_DEFAULT_HAIKU_MODEL\": \"deepseek/deepseek-v4-flash\",\n    \"DISABLE_NON_ESSENTIAL_MODEL_CALLS\": \"1\",\n    \"CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC\": \"1\",\n    \"CLAUDE_CODE_ATTRIBUTION_HEADER\": \"0\",\n    \"CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION\": \"false\",\n    \"CLAUDE_CODE_DISABLE_TERMINAL_TITLE\": \"true\",\n    \"CLAUDE_CODE_ENABLE_AWAY_SUMMARY\": \"0\"\n  },\n  \"permissions\": {\n    \"deny\": [\n      \"mcp__ide__executeCode\"\n    ]\n  }\n}\n```\n\n- 请根据需要替换 `ANTHROPIC_MODEL`、`ANTHROPIC_DEFAULT_OPUS_MODEL`、`ANTHROPIC_DEFAULT_SONNET_MODEL` 和 `ANTHROPIC_DEFAULT_HAIKU_MODEL`。配置完成后，请安装 claude code 插件，见 [插件集成](#plugin-integrations)。\n- 将 `CLAUDE_CODE_ATTRIBUTION_HEADER` 设为 `0` 可以阻止 Claude Code 在 system prompt 中附加计费和版本信息，从而避免 prompt cache 失效。\n- 关闭 `CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION` 和 `CLAUDE_CODE_ENABLE_AWAY_SUMMARY` 可以避免不必要地消耗额度。\n- Claude Code WebSearch 已支持纯搜索请求。Copilot 路径请保持全局 `messageApiWebSearchModel` 指向 Responses-capable GPT 模型或 `provider/model` 别名；provider 路由请使用原生 Anthropic provider 或 `openai-responses` provider。只有在你明确想禁止这类流量时，才需要把 `WebSearch` 加到 `permissions.deny`。\n- 如果使用的不是 Claude 模型，请不要启用 `ENABLE_TOOL_SEARCH`。如果使用的是 Claude 模型，则可以启用 `ENABLE_TOOL_SEARCH`。当前 Claude Code 使用的是客户端 tool search 模式，在该模式下每次加载 defer tools 都需要额外请求一次。\n- `CLAUDE_CODE_AUTO_COMPACT_WINDOW`：设置用于自动压缩计算的上下文容量（以 token 为单位）。默认使用模型自身的上下文窗口：标准模型为 200K，扩展上下文模型为 1M。使用 1M 上下文模型（如 `claude-opus-4-6[1m]`）时，可设置一个较低的值（如 `500000`）将窗口视为 500K 用于压缩计算。该值受限于模型的实际上下文窗口上限。`CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` 会基于此值的百分比生效。设置此变量可将压缩阈值与状态栏的 `used_percentage` 解耦（后者始终使用模型的完整上下文窗口）。\n\n更多选项见：[Claude Code settings](https://docs.anthropic.com/en/docs/claude-code/settings#environment-variables)\n\n也可以参考 IDE 集成说明：[Add Claude Code to your IDE](https://docs.anthropic.com/en/docs/claude-code/ide-integrations)\n\n## 与 OpenCode 一起使用\n\nOpenCode 已经有直接的 GitHub Copilot provider。本节适用于你希望让 OpenCode 通过 `@ai-sdk/anthropic` 指向这个 AI gateway，并复用本 README 前面提到的 agent 行为时。\n\n### 最小配置\n\n使用 OpenCode OAuth app 启动 AI gateway：\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth --oauth-app=opencode\nnpx @jeffreycao/copilot-api@latest start\n```\n\n然后让 OpenCode 通过 `@ai-sdk/anthropic` 指向这个 AI gateway。\n\n示例 `~/.config/opencode/opencode.json`：\n\n```json\n{\n  \"$schema\": \"https://opencode.ai/config.json\",\n  \"provider\": {\n    \"local\": {\n      \"npm\": \"@ai-sdk/anthropic\",\n      \"name\": \"My Local\",\n      \"options\": {\n        \"baseURL\": \"http://localhost:4141/v1\",\n        \"apiKey\": \"dummy\"\n      },\n      \"models\": {\n        \"gpt-5.4\": {\n          \"name\": \"gpt-5.4\",\n          \"modalities\": {\n            \"input\": [\"text\", \"image\"],\n            \"output\": [\"text\"]\n          },\n          \"limit\": {\n            \"context\": 400000,\n            \"input\": 272000,\n            \"output\": 128000\n          }\n        },\n        \"claude-sonnet-4.6\": {\n          \"id\": \"claude-sonnet-4.6\",\n          \"name\": \"claude-sonnet-4.6\",\n          \"modalities\": {\n            \"input\": [\"text\", \"image\"],\n            \"output\": [\"text\"]\n          },\n          \"limit\": {\n            \"context\": 200000,\n            \"output\": 32000\n          },\n          \"options\": {\n            \"thinking\": {\n              \"type\": \"adaptive\"\n            },\n            \"effort\": \"max\"\n          }\n        }\n      }\n    }\n  }\n}\n```\n\n这些字段的重要性：\n\n- `npm: \"@ai-sdk/anthropic\"` 是关键。OpenCode 会以 Anthropic Messages 语义与这个 AI gateway 通信，而不是把一切扁平化为 OpenAI Chat Completions。\n- `options.baseURL` 应设为 `http://localhost:4141/v1`；Anthropic SDK 会自动补上 `/messages`、`/models` 和 `/messages/count_tokens`。\n- 如果你在此代理中启用了 `auth.apiKeys`，请把 `dummy` 替换为真实 key；否则任意占位值都可以。\n\n## 与 Codex 一起使用\n\n这个 AI gateway 也可以为 Codex 提供后端能力。\n\n### Codex `config.toml` 参考配置\n\n把以下 `[model_providers.copilot_api]` 段加入你的 Codex `~/.codex/config.toml`：\n\n```toml\nmodel_provider = \"copilot_api\"\nmodel_reasoning_summary = \"auto\"\nmodel_context_window = 272000\nmodel_auto_compact_token_limit = 244800\n\n[model_providers.copilot_api]\nname = \"OpenAI\"\nbase_url = \"http://localhost:4141\"\nenv_key = \"GITHUB_COPILOT_API_KEY\"\nrequires_openai_auth = true\nsupports_websockets = false\nwire_api = \"responses\"\nrequest_max_retries = 3\nstream_max_retries = 1\nstream_idle_timeout_ms = 300000\n\n[features]\nremote_compaction_v2 = true\n\n[analytics]\nenabled = false\n```\n\n> [!NOTE]\n> 此配置仅限于 Codex 与 GitHub Copilot provider。`name` 一定要配置为 `\"OpenAI\"`。它可以缓解 Codex local compact 不命中缓存的问题。\n> 如果使用 codex provider，建议将 `base_url` 配置为 `\"http://localhost:4141/codex\"`。\n\n## GPT Tool Search\n\n对于 `gpt-5.4+` 这类 GPT Responses 模型，这个 AI gateway 可以通过一个很小的 MCP bridge 暴露 Responses `tool_search`。Claude Code 和 opencode 都可以使用同一个 bridge，前提是客户端会加载 MCP server，并且 Anthropic Messages 流量会经过这个 AI gateway。\n\nGPT 模型不要设置 Claude Code 原生的 `ENABLE_TOOL_SEARCH`。这个开关启用的是 Claude Code 自己的客户端 tool search 模式，可能导致 deferred 工具定义不再转发给 AI gateway。这个 AI gateway 需要完整的工具定义，这样才能只保留那一小组常驻加载工具，其余工具统一转换为 Responses deferred namespace。\n\n如果你安装了 `tool-search@copilot-api-marketplace`，Claude Code 会自动带上这个 MCP bridge，可以跳过下面这段 Claude Code MCP 手动配置。\n\n请把 tool search bridge 加到 Claude Code 使用的 MCP 配置中：\n\n```json\n{\n  \"mcpServers\": {\n    \"tool_search\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@jeffreycao/copilot-api@latest\", \"mcp\"]\n    }\n  }\n}\n```\n\n请把 tool search bridge 加到 opencode 使用的 MCP 配置中：\n\n```json\n{\n  \"mcp\": {\n    \"tool_search\": {\n      \"type\": \"local\",\n      \"command\": [\"npx\", \"-y\", \"@jeffreycao/copilot-api@latest\", \"mcp\"]\n    }\n  }\n}\n```\n\n本地开发时可以将命令换成 `bun`，参数换成 `[\"run\", \"./src/main.ts\", \"mcp\"]`。\n\nAI gateway 内部现在会把 OpenAI Responses `tool_search` 配置成 client-executed 模式。deferred tools 仍然会作为可搜索 namespace 暴露给模型，但会明确要求模型直接返回下一步要加载的精确工具名列表。\n\n该 bridge 使用直接工具选择，不做 query 搜索。工具入参是 `names`，值为逗号分隔的精确 deferred 工具名，例如 `TaskList,TaskGet,mcp__fetch__fetch`。\n\n<a id=\"plugin-integrations\"></a>\n\n## 插件集成\n\n本项目为 Claude Code 和 opencode 提供了插件集成。\n\n#### Claude Code 插件集成（基于 marketplace）\n\nClaude Code 集成现在拆分为两个插件：\n\n- `agent-inject` 会在 `SubagentStart` 时注入 `__SUBAGENT_MARKER__...`，以便 AI gateway 推导 `x-initiator: agent`。\n- `tool-search` 会注册用于 GPT Responses deferred tool loading 的 `tool_search` MCP bridge。\n\n- 本仓库中的 marketplace catalog：`.claude-plugin/marketplace.json`\n- 本仓库中的插件源码：`plugin/claude/agent-inject`、`plugin/claude/tool-search`\n\n远程添加 marketplace：\n\n```sh\n/plugin marketplace add https://github.com/caozhiyuan/copilot-api.git\n```\n\n从 marketplace 安装插件：\n\n```sh\n/plugin install agent-inject@copilot-api-marketplace\n/plugin install tool-search@copilot-api-marketplace\n```\n\n安装后，`agent-inject` 会在 `SubagentStart` 时注入 `__SUBAGENT_MARKER__...`，AI gateway 会利用它推导 `x-initiator: agent`。\n\n`agent-inject` 还会注册一个 `UserPromptSubmit` hook，并返回 `{\"continue\": true}`；同时它也可以通过环境变量注入 `SessionStart` reminder 规则：\n\n- `CLAUDE_PLUGIN_ENABLE_QUESTION_RULES=1` 会自动为 Claude Code 启用两条关于使用 `question` 工具的提醒。你也可以把同样的提醒手动写进 `CLAUDE.md`；见 [CLAUDE.md 或 AGENTS.md 推荐内容](#claudemd-or-agentsmd-recommended-content)。\n- `CLAUDE_PLUGIN_ENABLE_NO_BACKGROUND_AGENTS_RULE=1` 会启用关于避免在 agent hooks 中使用 `run_in_background: true` 的提醒。\n\n`tool-search` 插件内置了 [GPT Tool Search](#gpt-tool-search) 一节描述的同一个 MCP bridge，因此安装该插件后，Claude Code 用户无需再手动配置 `tool_search` server。\n\n#### Opencode 插件\n\nsubagent 标记生成器被打包为一个 opencode 插件，位于 `plugin/opencode/subagent-marker.js`。\n\n**安装方式：**\n\n将插件文件复制到你的 opencode 插件目录：\n\n```sh\n# 克隆或下载本仓库后复制该插件\ncp plugin/opencode/subagent-marker.js ~/.config/opencode/plugins/\n```\n\n或者手动在 `~/.config/opencode/plugins/subagent-marker.js` 创建该文件，并填入插件内容。\n\n**功能：**\n\n- 跟踪 subagent 创建的子会话\n- 自动在 subagent 聊天消息前添加 marker system reminder（`__SUBAGENT_MARKER__...`）\n- 设置 `x-session-id` 请求头以跟踪会话\n- 让这个 AI gateway 能够把来自 subagent 的请求识别为 `x-initiator: agent`\n\n该插件会挂接到 `session.created`、`session.deleted`、`chat.message` 和 `chat.headers` 事件上，以无缝提供 subagent marker 能力。\n\n## 使用量查看器\n\n服务启动后，控制台会输出一个 Copilot 使用量看板 URL。这个看板是一个用于监控 API 用量的 Web 界面。\n\n1. 启动服务。例如使用 npx：\n   ```sh\n   npx @jeffreycao/copilot-api@latest start\n   ```\n2. 服务会输出一个 usage viewer 的 URL。将它复制到浏览器中打开，形式大致如下：\n   `http://localhost:4141/usage-viewer?endpoint=http://localhost:4141/usage`\n   - 如果你在 Windows 上使用 `start.bat` 脚本，这个页面会自动打开。\n\n看板提供了更易读的 Copilot 用量视图：\n\n> token usage 历史记录需要 Bun 或 Node.js >= 22.13.0。Node.js < 22.13.0 时服务会正常运行，但 token usage 存储会被禁用。\n\n- **API Endpoint URL**：通过 URL 查询参数指定 API endpoints，默认指向本地服务。支持手动切换为其他兼容 endpoints。\n- **x-api-key 认证**：如果启用了 API Key 认证，可填入 `x-api-key` 请求头。密钥会持久化保存在浏览器本地存储中。\n- **Period 选择器**：支持 Day / Week / Month 三种时间范围，切换时 URL 参数会自动同步，方便收藏和分享。\n- **Fetch Data**：点击 \"Refresh\" 按钮加载或刷新使用数据。页面加载时也会自动拉取数据。\n- **Copilot Quotas 额度**：通过进度条展示 Chat、Completions 等不同服务的额度使用情况，悬停可查看已用/剩余详情。\n- **Token Usage 指标卡片**：汇总当前周期的 Total、Input、Output、Cache Read、Cache Write、Requests 和预估费用。\n- **趋势图（Week / Month）**：提供按模型和指标筛选的折线趋势图，点击数据点可查看单日用量明细。\n- **Model Breakdown 表格**：按模型维度列出周期内的请求数、输入/输出/缓存 token 和预计费用。\n- **Request Events 分页列表**：按时间排序的请求事件记录，支持分页浏览，含时间戳、模型、请求 ID 和 token 用量。\n- **Detailed Information**：展示 API 返回的完整 JSON 响应，便于深入分析所有可用统计数据。\n- **URL-based Configuration**：也可通过 `endpoint` 和 `period` 查询参数直接指定 API 端点与时间范围。例如：\n  `http://localhost:4141/usage-viewer?endpoint=http://your-api-server/usage&period=week`\n\n### Usage Viewer 截图\n\n<p align=\"center\">\n  <img src=\"./docs/screenshots/usage-viewer.png\" alt=\"Copilot API Usage Viewer 页面\" width=\"900\" />\n</p>\n\n## 命令结构\n\nCopilot API 现在使用子命令结构，主要命令包括：\n\n- `start`：启动 AI gateway 服务。如果已有 GitHub token，则启用 Copilot 路径；如果没有 GitHub token，但存在至少一个启用中的 provider，则按 provider-only 模式启动；如果两者都没有，会引导你配置 provider。\n- `auth`：仅执行 provider 登录或配置流程，不启动服务。可用于 GitHub Copilot 登录、Codex OAuth，或第三方 provider API key 配置。\n- `debug`：显示诊断信息，包括版本、运行时详情、文件路径以及认证状态，便于排障与支持。\n\n## 命令行选项\n\n### 全局选项\n\n以下选项可用于任意子命令。若在子命令之前传入，请使用 `--key=value` 形式：\n\n| 选项 | 说明 | 默认值 | 别名 |\n| --- | --- | --- | --- |\n| --api-home | API home 目录路径（设置 `COPILOT_API_HOME`） | 无 | 无 |\n| --oauth-app | OAuth app 标识符（设置 `COPILOT_API_OAUTH_APP`） | 无 | 无 |\n| --enterprise-url | GitHub Enterprise URL（设置 `COPILOT_API_ENTERPRISE_URL`） | 无 | 无 |\n\n### Start 命令选项\n\n以下是 `start` 命令可用的命令行选项：\n\n| 选项 | 说明 | 默认值 | 别名 |\n| --- | --- | --- | --- |\n| --port | 监听端口 | 4141 | -p |\n| --verbose | 启用详细日志 | false | -v |\n| --github-token | 直接提供 GitHub token（必须通过 `auth` 子命令生成） | 无 | -g |\n| --claude-code | 生成一个使用 Copilot API 配置启动 Claude Code 的命令 | false | -c |\n| --show-token | 在获取和刷新时显示 GitHub 与 Copilot token | false | 无 |\n| --proxy-env | 从环境变量初始化代理 | false | 无 |\n\n### Auth 命令选项\n\n| 选项 | 说明 | 默认值 | 别名 |\n| --- | --- | --- | --- |\n| --provider | 要登录或配置的 provider（`copilot`、`codex`、`opencode-go`、`deepseek`、`dashscope`、`openrouter` 或 `custom`） | 交互选择 | 无 |\n| --verbose | 启用详细日志 | false | -v |\n| --show-token | 认证时显示 GitHub token | false | 无 |\n\n只有在需要启用 GitHub Copilot provider 时，才需要执行 `copilot-api auth login --provider copilot`。使用 `codex` 或第三方 provider-only 模式不要求配置 Copilot。\n\n使用 `copilot-api auth login --provider deepseek`、`--provider dashscope`、`--provider openrouter` 或 `--provider opencode-go` 可以通过 CLI 快速新增或更新这些常用第三方 provider。DeepSeek 会提示输入掩码显示的 `apiKey`、provider `type`（默认 `anthropic`），以及默认 `https://api.deepseek.com/anthropic` 的 `baseUrl`。DashScope 会提示输入掩码显示的 `apiKey`、provider `type`（默认 `openai-compatible`）和预填默认值的 `baseUrl`。OpenRouter 只提示输入掩码显示的 `apiKey` 和预填默认值的 `baseUrl`，并固定写入 `type: \"anthropic\"`。OpenCode Go 只提示输入掩码显示的 `apiKey` 和预填默认值的 `baseUrl`，并固定写入 `type: \"openai-compatible\"`（baseUrl `https://opencode.ai/zen/go`）。配置并启用 provider 后，`copilot-api start` 可在没有 GitHub token 的情况下启动。\n\n使用 `copilot-api auth login --provider custom` 可以通过 CLI 新增或更新其他第三方 provider。命令会依次提示输入 provider name、项目支持的 type（`anthropic`、`openai-compatible` 或 `openai-responses`）、`baseUrl`、掩码显示的 `apiKey` 和 `authType`；`authType` 可保持 type 默认值，也可选择 `x-api-key` / `authorization`。\n\n### Debug 命令选项\n\n| 选项 | 说明 | 默认值 | 别名 |\n| --- | --- | --- | --- |\n| --json | 以 JSON 输出调试信息 | false | 无 |\n\n<a id=\"configuration-configjson\"></a>\n\n## 配置（config.json）\n\n- **位置：** Linux/macOS 为 `~/.local/share/copilot-api/config.json`，Windows 为 `%USERPROFILE%\\.local\\share\\copilot-api\\config.json`。\n- **默认结构：**\n  ```json\n  {\n    \"auth\": {\n      \"apiKeys\": [],\n      \"adminApiKey\": \"<startup 自动生成>\"\n    },\n    \"providers\": {},\n    \"modelMappings\": {},\n    \"extraPrompts\": {\n      \"gpt-5-mini\": \"<built-in exploration prompt>\"\n    },\n    \"smallModel\": \"gpt-5-mini\",\n    \"contextManagement\": {\n      \"messages\": true,\n      \"responses\": false\n    },\n    \"modelResponsesApiCompactThresholds\": {\n      \"gpt-5.4\": 217600,\n      \"gpt-5.5\": 217600,\n      \"gpt-5.6-sol\": 231200,\n      \"gpt-5.6-terra\": 231200,\n      \"gpt-5.6-luna\": 231200\n    },\n    \"modelReasoningEfforts\": {\n      \"gpt-5-mini\": \"low\"\n    },\n    \"useMessagesApi\": true,\n    \"useResponsesApiWebSocket\": true,\n    \"useResponsesApiWebSearch\": true,\n    \"messageApiWebSearchModel\": \"gpt-5-mini\"\n  }\n  ```\n- **auth.apiKeys：** 用于普通非 admin 路由的 API key。支持多个 key 轮换使用。请求可通过 `x-api-key: <key>` 或 `Authorization: Bearer <key>` 进行认证。若为空或省略，则普通路由的认证会被禁用。\n- **auth.adminApiKey：** 仅用于 `/admin/*` 路由的单个 admin key。若未配置，服务会在启动时自动生成一个随机 key，并回写到 `config.json`。它同样使用 `x-api-key` 或 `Authorization: Bearer` 这两种头，但普通 `auth.apiKeys` 不能访问 `/admin/*`。\n- **modelMappings：** 用于顶层 `POST /v1/messages`、`POST /v1/messages/count_tokens`、`POST /v1/responses` 和 `POST /v1/chat/completions` 请求的精确 `sourceModel -> targetModel` 重写映射，这几类接口共用同一份规则。省略该字段或保留为 `{}` 时，不会做模型重写。`source` 和 `target` 都必须是非空字符串。`target` 可以是普通模型 ID，也可以是 `provider/model` 形式的别名，例如 `dashscope/qwen3.6-plus`；重写发生在 provider alias 解析之前。这些映射不再按接口区分。`GET/POST /admin/config/model-mappings` 管理接口读写的也只有这个字段。\n- **extraPrompts：** `model -> prompt` 的映射。把 Anthropic 风格请求翻译为 Responses API 时，会将其附加到第一条 system prompt 后面。你可以借此为不同模型注入护栏或指引。缺失的默认项会自动补齐，但不会覆盖你自定义的 prompt。对于 GPT-5.3+ 模型（如 `gpt-5.3-codex`、`gpt-5.4`、`gpt-5.5`），未显式配置时会自动使用内置的 commentary prompt。内置 prompt 会启用带阶段感知的 commentary，让模型在工具调用或更深层推理前先发出简短的用户可见进度说明。\n- **providers：** 全局上游 provider 映射。每个 provider key（例如 `dashscope`）都会变成一个路由前缀（`/dashscope/v1/messages`）。支持 `type: \"anthropic\"`、`type: \"openai-compatible\"` 和 `type: \"openai-responses\"`。顶层客户端也可以在 `/v1/messages`、`/v1/messages/count_tokens`、`/v1/responses` 和 `/v1/chat/completions` 中使用 `model: \"dashscope/model-id\"`；AI gateway 会在转发上游前移除 `dashscope/` 前缀。`openai-compatible` provider 同时支持 chat 和 Messages 流程：`/v1/chat/completions` 会直连上游 `/v1/chat/completions`，而 `/v1/messages` 和 `/:provider/v1/messages` 会先翻译为上游 Chat Completions，再把响应翻译回 Anthropic Messages。`GET /v1/models` 会聚合已启用 provider 的模型，并以 `provider/model-id` 形式返回；单个 provider 的原始模型列表仍可使用 `GET /dashscope/v1/models`。\n  - `enabled`：可选，若省略则默认为 `true`。\n  - `baseUrl`：provider API 的基础 URL，不要带结尾的 endpoint。Anthropic provider 不要带 `/v1/messages`；OpenAI 兼容 provider 不要带 `/v1/chat/completions`；OpenAI Responses provider 不要带 `/v1/responses`。\n  - `apiKey`：作为上游凭据值使用；普通 provider 必须配置。\n  - `authType`：可选，控制 `apiKey` 如何发送到上游。普通 provider 支持 `x-api-key` 和 `authorization`。Anthropic provider 默认 `x-api-key`；OpenAI 兼容和 OpenAI Responses provider 默认 `authorization`。当设置为 `authorization` 时，代理会发送 `Authorization: Bearer <apiKey>`。`oauth2` 仅保留给内置 `codex` provider，并由 `auth login --provider codex` 自动写入。\n  - `pricingCurrency`：可选，provider 维度的 token 费用币种，例如 `USD` 或 `CNY`。快捷 provider 默认 DashScope、DeepSeek 为 `CNY`，Codex/OpenRouter 为 `USD`。费用按币种分别汇总，不做汇率换算。\n  - `models`：可选，按模型 ID 配置的映射。每个键为请求中的模型名，值支持：\n    - `temperature`：可选，当请求未指定时使用的默认温度。\n    - `topP`：可选，当请求未指定时使用的默认 `top_p`。\n    - `topK`：可选，当请求未指定时使用的默认 `top_k`。\n    - `extraBody`：可选，按模型合入上游请求体的动态字段；请求体显式同名字段优先。OpenAI 兼容 provider 可用它配置 `enable_thinking`、`preserve_thinking`、`reasoning_effort` 等字段。`thinking_budget` 是 OpenAI 兼容 provider 的特殊覆盖项：配置在 `extraBody` 后，会在 Anthropic `thinking.budget_tokens` 翻译之后强制写入，并覆盖请求派生出的预算值。对于 provider name 为 `dashscope` 或 `baseUrl` 包含 `aliyuncs.com` 的 provider，请求派生的 `thinking_budget`（来自 Anthropic `thinking.budget_tokens`）会转发给上游；其他 OpenAI 兼容 provider 会移除请求派生的 `thinking_budget`，但 `extraBody` 中的 `thinking_budget` 仍然生效。对于 DashScope provider，当 `preserve_thinking` 未在 `extraBody` 或请求体中显式设置时，默认为 `true`。\n    - `pricing`：可选，按模型配置 token 单价，币种使用 provider 的 `pricingCurrency`，单位为每 100 万 tokens。支持 `input`、`output`、`cachedInput`（隐式缓存读）、`explicitCachedInput`（显式缓存读）和 `cacheCreationInput`。如需按输入 token 总量分档，可用带 `maxInputTokens` 的 `tiers`。\n    - `contextCache`：可选，provider name 为 `dashscope` 或 `baseUrl` 包含 `aliyuncs.com` 时默认 `true`，其他 OpenAI 兼容 provider 默认 `false`。用于启用阿里云百炼/DashScope 的显式缓存（explicit context cache），会按其 Context Cache 格式在最多 4 个 content block 上注入 `cache_control: { \"type\": \"ephemeral\" }`。缓存断点策略与 opencode 主链路保持一致：前 2 条 system 消息 + 最后 2 条非 system 消息。标记字符串 content 时会把 `system` / `user` / `assistant` / `tool` 消息转换为 text content part 数组；已有数组 content 则标记最后一个 part。如果模型本身已经支持隐式缓存，或上游不支持该显式缓存扩展字段，可在模型配置中设为 `false`。支持相同显式缓存扩展的非 DashScope provider 可设为 `true`。同时适用于 `/v1/messages` 和 `/v1/chat/completions` 路由。\n    - `supportPdf`：可选，控制该模型是否支持 PDF/document content。默认 `false`，不支持时会把 PDF 转成提示文本；设为 `true` 时会把 PDF/document 转成 OpenAI Chat Completions 的 file part。\n    - `toolContentSupportType`：可选，配置该模型的 tool result content 支持能力，值为 `array`、`image`、`pdf` 的数组。provider 侧未配置时默认只发送 string tool content。若 `supportPdf` 为 `true` 但这里不包含 `pdf`，tool result 里的 file part 会被转成 user role 消息。Copilot 主链路不使用这个 provider 默认，仍按 array + image 且不支持 PDF 的能力处理。\n    - `type`：可选，按模型覆盖 provider 的协议类型。支持 `anthropic`、`openai-compatible` 和 `openai-responses`。设置后，provider 的 `/v1/messages` 路由会使用该模型的 type 替代 provider 级别的 type 进行请求路由、认证头解析和上游端点选择。适用于 OpenCode Go 等上游对不同模型同时支持 OpenAI 兼容和 Anthropic Messages API 的 provider。覆盖 type 时，认证头按覆盖后 type 的默认值解析（Anthropic 默认 `x-api-key`；OpenAI 兼容/Responses 默认 `authorization`）。\n\n  DashScope 模型配置示例：\n  ```json\n  {\n    \"providers\": {\n      \"dashscope\": {\n        \"type\": \"openai-compatible\",\n        \"enabled\": true,\n        \"baseUrl\": \"https://dashscope.aliyuncs.com/compatible-mode\",\n        \"apiKey\": \"sk-your-dashscope-key\",\n        \"pricingCurrency\": \"CNY\",\n        \"models\": {\n          \"qwen3.7-plus\": {\n            \"temperature\": 1,\n            \"topP\": 0.95,\n            \"topK\": 20,\n            \"extraBody\": {\n              \"preserve_thinking\": true\n            }\n          },\n          \"glm-5.1\": {\n            \"temperature\": 0.7,\n            \"topP\": 0.95,\n            \"contextCache\": true,\n            \"pricing\": {\n              \"tiers\": [\n                {\n                  \"maxInputTokens\": 32000,\n                  \"input\": 6,\n                  \"cachedInput\": 1.2,\n                  \"explicitCachedInput\": 0.6,\n                  \"cacheCreationInput\": 7.5,\n                  \"output\": 24\n                },\n                {\n                  \"maxInputTokens\": 200000,\n                  \"input\": 8,\n                  \"cachedInput\": 1.6,\n                  \"explicitCachedInput\": 0.8,\n                  \"cacheCreationInput\": 10,\n                  \"output\": 28\n                }\n              ]\n            },\n            \"extraBody\": {\n              \"preserve_thinking\": true\n            }\n          }\n        }\n      }\n    }\n  }\n  ```\n  内置 token 价格覆盖 Codex GPT 模型（USD）、DashScope `qwen3.7-max`、`qwen3.7-plus`、`glm-5.1`、`glm-5.2`（CNY），DeepSeek `deepseek-v4-flash`、`deepseek-v4-pro`、`deepseek-chat`、`deepseek-reasoner`（CNY），以及 OpenCode Go 模型（`glm-5.2`、`deepseek-v4-flash`、`deepseek-v4-pro`、`kimi-k2.7-code`、`mimo-v2.5`、`mimo-v2.5-pro`、`qwen3.7-plus`、`qwen3.7-max`、`minimax-m2.5`、`minimax-m3`，USD）。用户配置的 `pricing` 优先于内置价格。DashScope 若上游 usage 中出现 `cache_creation_input_tokens` 字段，cached tokens 按显式缓存读价计费；否则 `cachedInput` 作为隐式缓存读价。DeepSeek 的 `prompt_cache_hit_tokens` 会归入 cached input，`prompt_cache_miss_tokens` 会归入普通 input。\n- **smallModel：** 无工具预热消息的回退模型（例如 Claude Code 的探测请求）；默认是 `gpt-5-mini`。\n- **contextManagement：** 控制代理是否为 Responses API 附加 `context_management` 压缩指令。`messages` 作用于被翻译成 Responses API 的 Anthropic 风格 `/v1/messages` 请求，包括 `openai-responses` provider 的 Messages 路由，默认值为 `true`。`responses` 作用于 native `/v1/responses` 流量，包括 `provider/model` 别名和内置 `codex` provider，默认值为 `false`。只有在确认客户端支持 context management compaction 后，才建议在 Responses API 下启用 `responses`。启用后，请求体会带上 `context_management`，并在后续轮次中仅保留最新的压缩承载内容。**注意：** 对于 GPT-5.6 及以上模型（如 `gpt-5.6-sol`、`gpt-5.6-terra`、`gpt-5.6-luna`），context management 功能会被强制禁用，因为开启后会破坏这些模型的 prompt 缓存命中。此强制覆盖优先于 `contextManagement` 和 `modelResponsesApiCompactThresholds` 配置。\n- **modelResponsesApiCompactThresholds：** 按模型覆盖 Responses API 的 `compact_threshold`，仅在代理自动附加 `context_management` 时使用。它的优先级高于 `resolveResponsesCompactThreshold` 基于 `max_prompt_tokens * ratio` 的兜底阈值。默认将 `gpt-5.4` 和 `gpt-5.5` 设为 `217600`（`272000 * 0.8`），将 `gpt-5.6-sol`、`gpt-5.6-terra`、`gpt-5.6-luna` 设为 `231200`（`272000 * 0.85`）。未列出的模型继续使用原有兜底逻辑。\n- **modelReasoningEfforts：** `/v1/messages` 请求的模型级默认推理强度。仅当请求没有传入 `output_config.effort` 时，该配置才会生效。\n  - **优先级：** 请求中的 `output_config.effort` > `modelReasoningEfforts[model]` > 内置默认值（GPT-5.3+ 模型为 `xhigh`，其他模型为 `high`）。\n  - **转发字段：** 走 Copilot 原生 Messages API 时，最终值写入 `output_config.effort`；转换为 Responses API 时，最终值写入 `reasoning.effort`。\n  - **配置可选值：** `none`、`minimal`、`low`、`medium`、`high`、`xhigh`、`max`。\n- **useMessagesApi：** 当为 `true` 时，支持 Copilot 原生 `/v1/messages` 的 Claude 系模型会走 Messages API；否则回退到 `/chat/completions`。设为 `false` 可禁用 Messages API 路由，始终使用 `/chat/completions`。默认值为 `true`。\n- **useResponsesApiWebSocket：** 当为 `true` 时，Responses API 请求会优先对声明了 `ws:/responses` 的模型使用 Copilot websocket transport；仅声明 `/responses` 的模型仍走 HTTP。设为 `false` 可禁用 websocket 路由，并在模型支持 `/responses` 时使用 HTTP `/responses`。默认值为 `true`。如果遇到 Responses API WebSocket closed，一般是自己的网络问题。如果使用了 VPN，建议切换节点。\n- **useResponsesApiWebSearch：** 当为 `true` 时，服务端会保留 Responses API 中 `type: \"web_search\"` 的工具并透传到上游。设为 `false` 则会从 `/responses` payload 中移除这些工具。默认值为 `true`。\n- **messageApiWebSearchModel：** 顶层 Copilot `/v1/messages` 请求只包含服务端 `web_search` 工具时使用的全局模型，默认值为 `gpt-5-mini`。如果该值是 `provider/model` 别名，请求会进入对应 provider 的 Messages API 路径，并在转发前移除 provider 前缀。对于 Copilot GPT 模型，web search 会通过 `/responses` 执行。混合 `web_search` 与自定义工具的场景暂不支持，服务端会移除 server-side `web_search`。\n- **claudeTokenMultiplier：** 用于 Claude `/v1/messages/count_tokens` 请求在本地走 GPT tokenizer 估算时的乘数。默认值为 `1.15`。如果你的客户端仍然过晚触发上下文压缩，可以适当调大。这个配置只会在代理本地估算 Claude token 时生效；如果已经配置 `anthropicApiKey` 且 Anthropic token counting 调用成功，则会直接返回 Anthropic 的精确计数，不会使用这个乘数。\n- **anthropicApiKey：** 用于把 Claude `/v1/messages/count_tokens` 请求转发到 Anthropic 真实 token counting 端点的 API key，这样会返回精确计数，而不是 GPT tokenizer 估算值。也可通过环境变量 `ANTHROPIC_API_KEY` 设置。若未配置，或上游调用失败，则回退到由 `claudeTokenMultiplier` 控制的本地 GPT tokenizer 估算。\n\n编辑此文件后即可自定义 prompts，或替换为你自己的快速模型。修改完成后请重启服务（或重新执行命令），让缓存中的配置刷新生效。\n\n## API 认证\n\n- **受保护的普通路由：** 当配置了 `auth.apiKeys` 且非空时，除 `/`、`/usage-viewer` 和 `/usage-viewer/` 以外的普通路由都需要认证。\n- **Admin 路由：** 所有 `/admin/*` 路由都要求 `auth.adminApiKey`。如果缺失，服务会在启动时自动生成并在开始提供服务前写回 `config.json`。\n- **允许的认证头：**\n  - `x-api-key: <your_key>`\n  - `Authorization: Bearer <your_key>`\n- **CORS 预检：** `OPTIONS` 请求始终允许。\n- **未配置普通 key 时：** 普通路由仍可直接访问；但这条规则不适用于 `/admin/*`，后者只接受 `auth.adminApiKey`。\n\n普通受保护路由的示例请求：\n\n```sh\ncurl http://localhost:4141/v1/models \\\n  -H \"x-api-key: your_api_key\"\n```\n\nAdmin 路由的示例请求：\n\n```sh\ncurl http://localhost:4141/admin/config/model-mappings \\\n  -H \"x-api-key: your_admin_api_key\"\n```\n\n## API 端点\n\n服务端提供多个 OpenAI / Anthropic 兼容端点。请求会根据所选模型和 `provider/model` 别名路由到 GitHub Copilot、内置 `codex` provider 或已配置的 provider。\n\n### OpenAI 兼容端点\n\n这些端点模拟 OpenAI API 结构。\n\n| 端点 | 方法 | 说明 |\n| --- | --- | --- |\n| `POST /v1/responses` | `POST` | OpenAI 中用于生成模型响应的高级接口。支持 `openai-responses` provider 的 `provider/model` 别名。 |\n| `POST /v1/chat/completions` | `POST` | 为给定聊天对话创建模型响应。支持 `openai-compatible` provider 的 `provider/model` 别名；目标 provider 已配置时可在没有 Copilot 的情况下使用。 |\n| `GET /v1/models` | `GET` | 列出 Copilot 模型以及已启用 provider 的 `provider/model-id` 模型。来自 Codex 客户端（`User-Agent` 以 `codex` 开头）的请求会转发到 Codex Models 上游。 |\n| `POST /v1/embeddings` | `POST` | 创建表示输入文本的向量嵌入。 |\n\n### Codex 后端代理端点\n\n这些端点要求已有可用的 Codex 登录态。每个端点同时提供无版本前缀和 `/v1` 两种路径。\n\n| 端点 | 方法 | 说明 |\n| --- | --- | --- |\n| `POST /alpha/search`<br>`POST /v1/alpha/search` | `POST` | 将 JSON 请求体和查询参数透明转发到 Codex Alpha Search 上游。 |\n| `POST /images/generations`<br>`POST /v1/images/generations` | `POST` | 将 JSON 图片生成请求转发到 Codex Images 上游。请求未携带 `Content-Type` 时，网关默认补充 `application/json`。 |\n| `POST /images/edits`<br>`POST /v1/images/edits` | `POST` | 将图片编辑请求转发到 Codex Images 上游。请使用 `multipart/form-data`，并让 HTTP 客户端自动生成 `boundary`；网关会保留传入的 content type，并以流式方式转发上传请求体。 |\n\n对于以上所有端点，网关都会使用当前 Codex 登录态覆盖客户端的 authorization 和 account header，保留查询参数及兼容的请求头，并返回上游状态码、响应头和响应体。\n\n### Anthropic 兼容端点\n\n这些端点设计为兼容 Anthropic Messages API。provider 级的 models、Responses、alpha-search 和 images 路由同时支持无版本前缀与 `/v1` 两种路径；Messages 路由仍使用 `/v1`。\n\n| 端点 | 方法 | 说明 |\n| --- | --- | --- |\n| `POST /v1/messages` | `POST` | 为给定对话创建模型响应。支持已配置 provider 的 `provider/model` 别名，包括通过 `openai-compatible` provider 做翻译。 |\n| `POST /v1/messages/count_tokens` | `POST` | 计算一组消息的 token 数。支持已配置 provider 的 `provider/model` 别名。 |\n| `POST /:provider/v1/messages` | `POST` | 将 Anthropic Messages 请求代理到已配置的 Anthropic provider，或翻译到 OpenAI 兼容 / OpenAI Responses provider。 |\n| `GET /:provider/models`<br>`GET /:provider/v1/models` | `GET` | 将模型列表请求代理到已配置的 provider。对 `codex` 默认返回内置模型目录；Codex 客户端（`User-Agent` 以 `codex` 开头）会转发到 Codex Models 上游。 |\n| `POST /:provider/v1/messages/count_tokens` | `POST` | 为 provider 路由请求在本地计算 token 数。 |\n| `POST /:provider/responses`<br>`POST /:provider/v1/responses` | `POST` | 将 OpenAI Responses 请求代理到已配置的 `openai-responses` provider（含 `codex`）。 |\n| `POST /:provider/alpha/search`<br>`POST /:provider/v1/alpha/search` | `POST` | 代理 alpha-search 请求。对 `codex` 转发到 Codex Alpha Search 上游；其他 provider 转发到 `{baseUrl}/v1/alpha/search`。 |\n| `POST /:provider/images/generations`<br>`POST /:provider/v1/images/generations` | `POST` | 代理图片生成。对 `codex` 使用 Codex Images 上游；其他 provider 转发到 `{baseUrl}/v1/images/generations`（15 分钟超时）。 |\n| `POST /:provider/images/edits`<br>`POST /:provider/v1/images/edits` | `POST` | 代理图片编辑。对 `codex` 使用 Codex Images 上游；其他 provider 以 multipart/流式方式转发到 `{baseUrl}/v1/images/edits`（15 分钟超时）。 |\n\n### 使用量监控端点\n\n用于监控 Copilot 用量与额度的新端点。\n\n| 端点 | 方法 | 说明 |\n| --- | --- | --- |\n| `GET /usage` | `GET` | 获取详细的 Copilot 使用统计与额度信息。 |\n| `GET /token` | `GET` | 获取当前 API 正在使用的 Copilot token。 |\n\n### Admin / 配置端点\n\n这些端点用于本地管理操作，只接受 `auth.adminApiKey`。\n\n| 端点 | 方法 | 说明 |\n| --- | --- | --- |\n| `GET /admin/config/model-mappings` | `GET` | 返回当前 `config.json` 路径以及生效中的 `modelMappings` 映射。 |\n| `POST /admin/config/model-mappings` | `POST` | 只更新 `config.json` 里的 `modelMappings` 字段，并回传更新后的结果。 |\n\n## 使用示例\n\n常用 `npx` 命令：\n\n```sh\n# 基础启动\nnpx @jeffreycao/copilot-api@latest start\n\n# 自定义端口并开启详细日志\nnpx @jeffreycao/copilot-api@latest start --port 8080 --verbose\n\n# 执行认证流程\nnpx @jeffreycao/copilot-api@latest auth login\n\n# 配置第三方 provider，然后不依赖 GitHub Copilot 启动\nnpx @jeffreycao/copilot-api@latest auth login --provider dashscope\nnpx @jeffreycao/copilot-api@latest start\n\n# 以 JSON 格式输出调试信息\nnpx @jeffreycao/copilot-api@latest debug --json\n\n# 用 Bun 而不是 Node.js 运行已发布 CLI\nbunx --bun @jeffreycao/copilot-api@latest start\n```\n\n配置 `dashscope` 后的 OpenAI 兼容 provider 调用示例：\n\n```sh\ncurl http://localhost:4141/v1/chat/completions \\\n  -H \"content-type: application/json\" \\\n  -d '{\"model\":\"dashscope/qwen3.6-plus\",\"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]}'\n\ncurl http://localhost:4141/dashscope/v1/messages \\\n  -H \"content-type: application/json\" \\\n  -d '{\"model\":\"qwen3.6-plus\",\"max_tokens\":1024,\"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]}'\n```\n\n## 使用建议\n\n<a id=\"claudemd-or-agentsmd-recommended-content\"></a>\n\n### CLAUDE.md 或 AGENTS.md 推荐内容\n\n如果你想手动加入这些提醒，请在 Claude Code 的 `CLAUDE.md`，或 opencode/codex 的 `AGENTS.md` 中加入以下内容：\n\n```\n- Prohibited from directly asking questions to users, MUST use question tool.\n- Once you can confirm that the task is complete, MUST use question tool to make user confirm. The user may respond with feedback if they are not satisfied with the result, which you can use to make improvements and try again, after try again, MUST use question tool to make user confirm again.\n```\n"}, "cb458e50d8a4d4db635bf3eb3ecd27c0c21ad0a1": {"t": 1785765553.7729218, "n": 32960, "h": "b5769fe86360cb80", "c": "# Copilot API Proxy\n\n[English](./README.md) | 简体中文\n\n## 重要说明\n\n> [!IMPORTANT]\n> **使用前请先注意以下几点：**\n>\n> 1. **Claude Code 配置：** 与 Claude Code 搭配使用时，请将模型 ID 配置为 `claude-opus-4-8`。示例 claude `settings.json` 见 [通过 `settings.json` 手动配置](#manual-configuration-with-settingsjson)。\n>\n> 2. **内置 `copilot`、`codex` 与第三方 provider：** 执行 `npx @jeffreycao/copilot-api@latest auth`，可选择 `copilot`、`codex`、`deepseek`、`custom` 等 provider。\n>\n> 3. **注意事项：** README 顶部移除的 GitHub Copilot warning 见 [GitHub Copilot 安全提示](./NOTICE.md#github-copilot-security-notice)。\n\n---\n\n## 项目概览\n\n这是一个小型 AI gateway，可以使用 GitHub Copilot、内置 `codex` provider，也可以使用 DashScope 等已配置的第三方 provider。GitHub Copilot 现在是可选能力：如果本地没有 GitHub token，只要至少配置了一个启用中的 provider，服务仍可按 provider-only 模式启动。\n\nAI gateway 会从同一个本地端点暴露 OpenAI / Anthropic 兼容 API，让 [Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview)、OpenCode、Codex 和 OpenAI 兼容客户端可以共用同一个本地服务。\n\n在 GitHub Copilot 路径上，AI gateway 会在可用时优先使用 Copilot 原生的 Anthropic 风格 Messages API，在重工具调用场景下保留更原生的 Claude 行为。\n\n## 功能特性\n\n- **OpenAI 与 Anthropic 双兼容**：通过 `/v1/responses`、`/v1/chat/completions`、`/v1/models`、`/v1/embeddings` 和 `/v1/messages` 对外暴露同一个本地 AI gateway。\n- **Copilot 可选**：有 GitHub 凭据时可以使用 GitHub Copilot，没有 GitHub 凭据时也可以只依赖已配置的 provider 运行。\n- **同一网关接入 Copilot、`codex` 与第三方 provider**：可统一路由 GitHub Copilot、内置 `codex` provider 和配置好的外部 provider。\n- **第三方 provider 可独立启动**：配置 DashScope、DeepSeek、OpenRouter 或自定义 provider 后，不需要 GitHub Copilot 登录即可启动 AI gateway。\n- **OpenAI 兼容 provider 同时支持 chat 和 Messages API**：`openai-compatible` provider 可通过顶层 `/v1/chat/completions` 搭配 `model: \"provider/model\"` 提供 Chat Completions，也可通过 `/v1/messages` 完成 Anthropic Messages 的请求/响应翻译。\n- **面向 Claude 的更原生 Copilot 路由**：优先使用原生 `/v1/messages`，保留 Claude 风格工具流，支持 Anthropic beta 能力、通过 Responses-capable 模型支持 Claude WebSearch，并保留 subagent / session 标记。\n- **Claude Code 与 OpenCode 集成**：兼容 Claude Code 与 OpenCode，也支持通过 `@ai-sdk/anthropic` 直接作为 Anthropic provider 使用。\n- **灵活的认证与部署选项**：支持交互式登录、直接 token、个人 / Business / Enterprise、GitHub Enterprise、opencode OAuth 和自定义数据目录。\n- **多 provider 路由**：可暴露 `/:provider/...` 路由，也可在顶层 API 上使用 `model: \"provider/model\"`。\n\n## 前置要求\n\n- Bun（>= 1.2.x）\n- 如果要通过 `npx` 运行已发布 CLI，需要 Node.js\n- 只有在使用 GitHub Copilot provider 时，才需要已订阅 Copilot 的 GitHub 账号\n- 如果不使用 GitHub Copilot，需要至少一个已配置 provider 的 API key 或 OAuth 登录\n\n## 安装\n\n安装依赖：\n\n```sh\nbun install\n```\n\n直接从源码启动服务：\n\n```sh\nbun run start start\n```\n\n## 从源码运行\n\n本项目可以通过多种方式从源码运行：\n\n### 开发模式\n\n```sh\nbun run dev start\n```\n\n### 生产模式\n\n```sh\nbun run start start\n```\n\n## 通过 npx 使用\n\n你可以直接用 npx 运行本项目：\n\n> [!IMPORTANT]\n> 通过 `npx` 运行时，token usage 存储会使用 Node 内置的 `node:sqlite` 模块。该能力会在 Node.js >= 22.13.0 时启用；Node.js < 22.13.0 时 CLI 仍可启动，但会禁用 token usage 存储。\n>\n> 如果不升级 Node.js 但仍需要 token usage 存储，可以改用 Bun 运行已发布 CLI：`bunx --bun @jeffreycao/copilot-api@latest start`。\n\n```sh\nnpx @jeffreycao/copilot-api@latest start\n```\n\n带参数示例：\n\n```sh\nnpx @jeffreycao/copilot-api@latest start --port 8080\n```\n\n如果只想做认证或 provider 配置：\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth\n```\n\n如果要不依赖 GitHub Copilot 运行，先配置至少一个 provider，然后正常启动服务：\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth login --provider dashscope\nnpx @jeffreycao/copilot-api@latest start\n```\n\n## 配合 Docker 使用\n\n构建镜像：\n\n```sh\ndocker build -t copilot-api .\n```\n\n通过 bind mount 运行容器，让认证数据在重启后保留：\n\n```sh\nmkdir -p ./copilot-data\ndocker run -p 4141:4141 -v $(pwd)/copilot-data:/root/.local/share/copilot-api copilot-api\n```\n\n这会把宿主机上的 `./copilot-data` 映射到容器内的 `/root/.local/share/copilot-api`，用于持久化 GitHub 认证数据、provider 配置和其他 gateway 状态。\n\n也可以直接通过环境变量传入 GitHub token：\n\n```sh\ndocker run -p 4141:4141 -e GH_TOKEN=your_github_token_here copilot-api\n```\n\n## Electron 桌面应用\n\n如果你更喜欢图形界面，仓库里还提供了位于 `desktop/` 的 Electron 桌面应用。它支持 GitHub Copilot 登录、OpenAI Codex OAuth，以及 DeepSeek、DashScope、OpenRouter 或自定义 provider 的 API Key 配置。授权或配置 provider 后，可以一键启动或停止本地代理，并在界面里直接查看本地端点、鉴权 Header、可用模型、额度和日志。\n\n设置页还可以配置 `OAuth App`、`API Home`、`Enterprise URL`、详细日志以及最小化到托盘。桌面安装包发布在 GitHub Releases：\n\nhttps://github.com/caozhiyuan/copilot-api/releases\n\n下载对应平台的安装包后，在应用内授权或配置 provider，选择端口并启动服务，再把你的客户端指向应用里显示的本地端点即可。发布版桌面应用使用随包内置的 Electron 运行时，正常使用不需要额外安装 Node.js；token usage 历史记录会在该内置运行时支持 SQLite 时启用。\n\n桌面应用里的高级配置页会通过 `GET/POST /admin/config/model-mappings` 读写这份共享的模型映射。同一份映射会统一作用于 `POST /v1/messages`、`POST /v1/messages/count_tokens`、`POST /v1/responses` 和 `POST /v1/chat/completions`，不再按接口区分。它使用的是 `auth.adminApiKey`，不是普通的 `auth.apiKeys`；应用会在服务启动并自动生成该 key 后，直接从 `config.json` 读取它来发起请求。\n\n### 桌面应用截图\n\n下面展示了桌面应用中的首页、Token 用量统计页面：\n\n<p align=\"center\">\n  <img src=\"./docs/screenshots/desktop-dashboard.png\" alt=\"Copilot API 桌面应用首页\" width=\"49%\" />\n  <img src=\"./docs/screenshots/desktop-token-usage.png\" alt=\"Copilot API 桌面应用 Token 用量页\" width=\"49%\" />\n</p>\n\n## 与 Claude Code 一起使用\n\n这个 AI gateway 可以为 [Claude Code](https://docs.anthropic.com/en/claude-code) 提供后端能力。Claude Code 是 Anthropic 提供的实验性面向开发者的对话式 AI 助手。\n\n有两种方式可以把 Claude Code 配置为使用这个 AI gateway：\n\n### 通过 `--claude-code` 标志进行交互式配置\n\n执行带 `--claude-code` 的 `start` 命令开始：\n\n```sh\nnpx @jeffreycao/copilot-api@latest start --claude-code\n```\n\n你会被提示选择一个主模型，以及一个用于后台任务的 \"small, fast\" 模型。选择完成后，会有一条命令被复制到剪贴板中。该命令会设置 Claude Code 使用这个 AI gateway 所需的环境变量。\n\n在新的终端中粘贴并执行这条命令，即可启动 Claude Code。\n\n<a id=\"manual-configuration-with-settingsjson\"></a>\n\n### 通过 `settings.json` 手动配置\n\n另一种方式是在项目根目录中创建 `.claude/settings.json` 文件，并写入 Claude Code 所需的环境变量。这样你就不需要每次都运行交互式配置了。\n\n下面是一个 `.claude/settings.json` 示例：\n\n```json\n{\n  \"env\": {\n    \"ANTHROPIC_BASE_URL\": \"http://localhost:4141\",\n    \"ANTHROPIC_AUTH_TOKEN\": \"dummy\",\n    \"ANTHROPIC_MODEL\": \"deepseek/deepseek-v4-pro\",\n    \"ANTHROPIC_DEFAULT_SONNET_MODEL\": \"deepseek/deepseek-v4-pro\",\n    \"ANTHROPIC_DEFAULT_HAIKU_MODEL\": \"deepseek/deepseek-v4-flash\",\n    \"DISABLE_NON_ESSENTIAL_MODEL_CALLS\": \"1\",\n    \"CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC\": \"1\",\n    \"CLAUDE_CODE_ATTRIBUTION_HEADER\": \"0\",\n    \"CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION\": \"false\",\n    \"CLAUDE_CODE_DISABLE_TERMINAL_TITLE\": \"true\",\n    \"CLAUDE_CODE_ENABLE_AWAY_SUMMARY\": \"0\"\n  },\n  \"permissions\": {\n    \"deny\": [\n      \"mcp__ide__executeCode\"\n    ]\n  }\n}\n```\n\n- 请根据需要替换 `ANTHROPIC_MODEL`、`ANTHROPIC_DEFAULT_OPUS_MODEL`、`ANTHROPIC_DEFAULT_SONNET_MODEL` 和 `ANTHROPIC_DEFAULT_HAIKU_MODEL`。配置完成后，请安装 claude code 插件，见 [插件集成](#plugin-integrations)。\n- 将 `CLAUDE_CODE_ATTRIBUTION_HEADER` 设为 `0` 可以阻止 Claude Code 在 system prompt 中附加计费和版本信息，从而避免 prompt cache 失效。\n- 关闭 `CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION` 和 `CLAUDE_CODE_ENABLE_AWAY_SUMMARY` 可以避免不必要地消耗额度。\n- Claude Code WebSearch 已支持纯搜索请求。Copilot 路径请保持全局 `messageApiWebSearchModel` 指向 Responses-capable GPT 模型或 `provider/model` 别名；provider 路由请使用原生 Anthropic provider 或 `openai-responses` provider。只有在你明确想禁止这类流量时，才需要把 `WebSearch` 加到 `permissions.deny`。\n- 如果使用的不是 Claude 模型，请不要启用 `ENABLE_TOOL_SEARCH`。如果使用的是 Claude 模型，则可以启用 `ENABLE_TOOL_SEARCH`。当前 Claude Code 使用的是客户端 tool search 模式，在该模式下每次加载 defer tools 都需要额外请求一次。\n- `CLAUDE_CODE_AUTO_COMPACT_WINDOW`：设置用于自动压缩计算的上下文容量（以 token 为单位）。默认使用模型自身的上下文窗口：标准模型为 200K，扩展上下文模型为 1M。使用 1M 上下文模型（如 `claude-opus-4-6[1m]`）时，可设置一个较低的值（如 `500000`）将窗口视为 500K 用于压缩计算。该值受限于模型的实际上下文窗口上限。`CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` 会基于此值的百分比生效。设置此变量可将压缩阈值与状态栏的 `used_percentage` 解耦（后者始终使用模型的完整上下文窗口）。\n\n更多选项见：[Claude Code settings](https://docs.anthropic.com/en/docs/claude-code/settings#environment-variables)\n\n也可以参考 IDE 集成说明：[Add Claude Code to your IDE](https://docs.anthropic.com/en/docs/claude-code/ide-integrations)\n\n## 与 OpenCode 一起使用\n\nOpenCode 已经有直接的 GitHub Copilot provider。本节适用于你希望让 OpenCode 通过 `@ai-sdk/anthropic` 指向这个 AI gateway，并复用本 README 前面提到的 agent 行为时。\n\n### 最小配置\n\n使用 OpenCode OAuth app 启动 AI gateway：\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth --oauth-app=opencode\nnpx @jeffreycao/copilot-api@latest start\n```\n\n然后让 OpenCode 通过 `@ai-sdk/anthropic` 指向这个 AI gateway。\n\n示例 `~/.config/opencode/opencode.json`：\n\n```json\n{\n  \"$schema\": \"https://opencode.ai/config.json\",\n  \"provider\": {\n    \"local\": {\n      \"npm\": \"@ai-sdk/anthropic\",\n      \"name\": \"My Local\",\n      \"options\": {\n        \"baseURL\": \"http://localhost:4141/v1\",\n        \"apiKey\": \"dummy\"\n      },\n      \"models\": {\n        \"gpt-5.4\": {\n          \"name\": \"gpt-5.4\",\n          \"modalities\": {\n            \"input\": [\"text\", \"image\"],\n            \"output\": [\"text\"]\n          },\n          \"limit\": {\n            \"context\": 400000,\n            \"input\": 272000,\n            \"output\": 128000\n          }\n        },\n        \"claude-sonnet-4.6\": {\n          \"id\": \"claude-sonnet-4.6\",\n          \"name\": \"claude-sonnet-4.6\",\n          \"modalities\": {\n            \"input\": [\"text\", \"image\"],\n            \"output\": [\"text\"]\n          },\n          \"limit\": {\n            \"context\": 200000,\n            \"output\": 32000\n          },\n          \"options\": {\n            \"thinking\": {\n              \"type\": \"adaptive\"\n            },\n            \"effort\": \"max\"\n          }\n        }\n      }\n    }\n  }\n}\n```\n\n这些字段的重要性：\n\n- `npm: \"@ai-sdk/anthropic\"` 是关键。OpenCode 会以 Anthropic Messages 语义与这个 AI gateway 通信，而不是把一切扁平化为 OpenAI Chat Completions。\n- `options.baseURL` 应设为 `http://localhost:4141/v1`；Anthropic SDK 会自动补上 `/messages`、`/models` 和 `/messages/count_tokens`。\n- 如果你在此代理中启用了 `auth.apiKeys`，请把 `dummy` 替换为真实 key；否则任意占位值都可以。\n\n## 与 Codex 一起使用\n\n这个 AI gateway 也可以为 Codex 提供后端能力。\n\n### Codex `config.toml` 参考配置\n\n把以下 `[model_providers.copilot_api]` 段加入你的 Codex `~/.codex/config.toml`：\n\n```toml\nmodel_provider = \"copilot_api\"\nmodel_reasoning_summary = \"auto\"\nmodel_context_window = 272000\nmodel_auto_compact_token_limit = 244800\n\n[model_providers.copilot_api]\nname = \"OpenAI\"\nbase_url = \"http://localhost:4141\"\nenv_key = \"GITHUB_COPILOT_API_KEY\"\nrequires_openai_auth = true\nsupports_websockets = false\nwire_api = \"responses\"\nrequest_max_retries = 3\nstream_max_retries = 1\nstream_idle_timeout_ms = 300000\n\n[features]\nremote_compaction_v2 = true\n\n[analytics]\nenabled = false\n```\n\n> [!NOTE]\n> 此配置仅限于 Codex 与 GitHub Copilot provider。`name` 一定要配置为 `\"OpenAI\"`。它可以缓解 Codex local compact 不命中缓存的问题。\n\n## GPT Tool Search\n\n对于 `gpt-5.4+` 这类 GPT Responses 模型，这个 AI gateway 可以通过一个很小的 MCP bridge 暴露 Responses `tool_search`。Claude Code 和 opencode 都可以使用同一个 bridge，前提是客户端会加载 MCP server，并且 Anthropic Messages 流量会经过这个 AI gateway。\n\nGPT 模型不要设置 Claude Code 原生的 `ENABLE_TOOL_SEARCH`。这个开关启用的是 Claude Code 自己的客户端 tool search 模式，可能导致 deferred 工具定义不再转发给 AI gateway。这个 AI gateway 需要完整的工具定义，这样才能只保留那一小组常驻加载工具，其余工具统一转换为 Responses deferred namespace。\n\n如果你安装了 `tool-search@copilot-api-marketplace`，Claude Code 会自动带上这个 MCP bridge，可以跳过下面这段 Claude Code MCP 手动配置。\n\n请把 tool search bridge 加到 Claude Code 使用的 MCP 配置中：\n\n```json\n{\n  \"mcpServers\": {\n    \"tool_search\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@jeffreycao/copilot-api@latest\", \"mcp\"]\n    }\n  }\n}\n```\n\n请把 tool search bridge 加到 opencode 使用的 MCP 配置中：\n\n```json\n{\n  \"mcp\": {\n    \"tool_search\": {\n      \"type\": \"local\",\n      \"command\": [\"npx\", \"-y\", \"@jeffreycao/copilot-api@latest\", \"mcp\"]\n    }\n  }\n}\n```\n\n本地开发时可以将命令换成 `bun`，参数换成 `[\"run\", \"./src/main.ts\", \"mcp\"]`。\n\nAI gateway 内部现在会把 OpenAI Responses `tool_search` 配置成 client-executed 模式。deferred tools 仍然会作为可搜索 namespace 暴露给模型，但会明确要求模型直接返回下一步要加载的精确工具名列表。\n\n该 bridge 使用直接工具选择，不做 query 搜索。工具入参是 `names`，值为逗号分隔的精确 deferred 工具名，例如 `TaskList,TaskGet,mcp__fetch__fetch`。\n\n<a id=\"plugin-integrations\"></a>\n\n## 插件集成\n\n本项目为 Claude Code 和 opencode 提供了插件集成。\n\n#### Claude Code 插件集成（基于 marketplace）\n\nClaude Code 集成现在拆分为两个插件：\n\n- `agent-inject` 会在 `SubagentStart` 时注入 `__SUBAGENT_MARKER__...`，以便 AI gateway 推导 `x-initiator: agent`。\n- `tool-search` 会注册用于 GPT Responses deferred tool loading 的 `tool_search` MCP bridge。\n\n- 本仓库中的 marketplace catalog：`.claude-plugin/marketplace.json`\n- 本仓库中的插件源码：`plugin/claude/agent-inject`、`plugin/claude/tool-search`\n\n远程添加 marketplace：\n\n```sh\n/plugin marketplace add https://github.com/caozhiyuan/copilot-api.git\n```\n\n从 marketplace 安装插件：\n\n```sh\n/plugin install agent-inject@copilot-api-marketplace\n/plugin install tool-search@copilot-api-marketplace\n```\n\n安装后，`agent-inject` 会在 `SubagentStart` 时注入 `__SUBAGENT_MARKER__...`，AI gateway 会利用它推导 `x-initiator: agent`。\n\n`agent-inject` 还会注册一个 `UserPromptSubmit` hook，并返回 `{\"continue\": true}`；同时它也可以通过环境变量注入 `SessionStart` reminder 规则：\n\n- `CLAUDE_PLUGIN_ENABLE_QUESTION_RULES=1` 会自动为 Claude Code 启用两条关于使用 `question` 工具的提醒。你也可以把同样的提醒手动写进 `CLAUDE.md`；见 [CLAUDE.md 或 AGENTS.md 推荐内容](#claudemd-or-agentsmd-recommended-content)。\n- `CLAUDE_PLUGIN_ENABLE_NO_BACKGROUND_AGENTS_RULE=1` 会启用关于避免在 agent hooks 中使用 `run_in_background: true` 的提醒。\n\n`tool-search` 插件内置了 [GPT Tool Search](#gpt-tool-search) 一节描述的同一个 MCP bridge，因此安装该插件后，Claude Code 用户无需再手动配置 `tool_search` server。\n\n#### Opencode 插件\n\nsubagent 标记生成器被打包为一个 opencode 插件，位于 `plugin/opencode/subagent-marker.js`。\n\n**安装方式：**\n\n将插件文件复制到你的 opencode 插件目录：\n\n```sh\n# 克隆或下载本仓库后复制该插件\ncp plugin/opencode/subagent-marker.js ~/.config/opencode/plugins/\n```\n\n或者手动在 `~/.config/opencode/plugins/subagent-marker.js` 创建该文件，并填入插件内容。\n\n**功能：**\n\n- 跟踪 subagent 创建的子会话\n- 自动在 subagent 聊天消息前添加 marker system reminder（`__SUBAGENT_MARKER__...`）\n- 设置 `x-session-id` 请求头以跟踪会话\n- 让这个 AI gateway 能够把来自 subagent 的请求识别为 `x-initiator: agent`\n\n该插件会挂接到 `session.created`、`session.deleted`、`chat.message` 和 `chat.headers` 事件上，以无缝提供 subagent marker 能力。\n\n## 使用量查看器\n\n服务启动后，控制台会输出一个 Copilot 使用量看板 URL。这个看板是一个用于监控 API 用量的 Web 界面。\n\n1. 启动服务。例如使用 npx：\n   ```sh\n   npx @jeffreycao/copilot-api@latest start\n   ```\n2. 服务会输出一个 usage viewer 的 URL。将它复制到浏览器中打开，形式大致如下：\n   `http://localhost:4141/usage-viewer?endpoint=http://localhost:4141/usage`\n   - 如果你在 Windows 上使用 `start.bat` 脚本，这个页面会自动打开。\n\n看板提供了更易读的 Copilot 用量视图：\n\n> token usage 历史记录需要 Bun 或 Node.js >= 22.13.0。Node.js < 22.13.0 时服务会正常运行，但 token usage 存储会被禁用。\n\n- **API Endpoint URL**：通过 URL 查询参数指定 API endpoints，默认指向本地服务。支持手动切换为其他兼容 endpoints。\n- **x-api-key 认证**：如果启用了 API Key 认证，可填入 `x-api-key` 请求头。密钥会持久化保存在浏览器本地存储中。\n- **Period 选择器**：支持 Day / Week / Month 三种时间范围，切换时 URL 参数会自动同步，方便收藏和分享。\n- **Fetch Data**：点击 \"Refresh\" 按钮加载或刷新使用数据。页面加载时也会自动拉取数据。\n- **Copilot Quotas 额度**：通过进度条展示 Chat、Completions 等不同服务的额度使用情况，悬停可查看已用/剩余详情。\n- **Token Usage 指标卡片**：汇总当前周期的 Total、Input、Output、Cache Read、Cache Write、Requests 和预估费用。\n- **趋势图（Week / Month）**：提供按模型和指标筛选的折线趋势图，点击数据点可查看单日用量明细。\n- **Model Breakdown 表格**：按模型维度列出周期内的请求数、输入/输出/缓存 token 和预计费用。\n- **Request Events 分页列表**：按时间排序的请求事件记录，支持分页浏览，含时间戳、模型、请求 ID 和 token 用量。\n- **Detailed Information**：展示 API 返回的完整 JSON 响应，便于深入分析所有可用统计数据。\n- **URL-based Configuration**：也可通过 `endpoint` 和 `period` 查询参数直接指定 API 端点与时间范围。例如：\n  `http://localhost:4141/usage-viewer?endpoint=http://your-api-server/usage&period=week`\n\n### Usage Viewer 截图\n\n<p align=\"center\">\n  <img src=\"./docs/screenshots/usage-viewer.png\" alt=\"Copilot API Usage Viewer 页面\" width=\"900\" />\n</p>\n\n## 命令结构\n\nCopilot API 现在使用子命令结构，主要命令包括：\n\n- `start`：启动 AI gateway 服务。如果已有 GitHub token，则启用 Copilot 路径；如果没有 GitHub token，但存在至少一个启用中的 provider，则按 provider-only 模式启动；如果两者都没有，会引导你配置 provider。\n- `auth`：仅执行 provider 登录或配置流程，不启动服务。可用于 GitHub Copilot 登录、Codex OAuth，或第三方 provider API key 配置。\n- `debug`：显示诊断信息，包括版本、运行时详情、文件路径以及认证状态，便于排障与支持。\n\n## 命令行选项\n\n### 全局选项\n\n以下选项可用于任意子命令。若在子命令之前传入，请使用 `--key=value` 形式：\n\n| 选项 | 说明 | 默认值 | 别名 |\n| --- | --- | --- | --- |\n| --api-home | API home 目录路径（设置 `COPILOT_API_HOME`） | 无 | 无 |\n| --oauth-app | OAuth app 标识符（设置 `COPILOT_API_OAUTH_APP`） | 无 | 无 |\n| --enterprise-url | GitHub Enterprise URL（设置 `COPILOT_API_ENTERPRISE_URL`） | 无 | 无 |\n\n### Start 命令选项\n\n以下是 `start` 命令可用的命令行选项：\n\n| 选项 | 说明 | 默认值 | 别名 |\n| --- | --- | --- | --- |\n| --port | 监听端口 | 4141 | -p |\n| --verbose | 启用详细日志 | false | -v |\n| --github-token | 直接提供 GitHub token（必须通过 `auth` 子命令生成） | 无 | -g |\n| --claude-code | 生成一个使用 Copilot API 配置启动 Claude Code 的命令 | false | -c |\n| --show-token | 在获取和刷新时显示 GitHub 与 Copilot token | false | 无 |\n| --proxy-env | 从环境变量初始化代理 | false | 无 |\n\n### Auth 命令选项\n\n| 选项 | 说明 | 默认值 | 别名 |\n| --- | --- | --- | --- |\n| --provider | 要登录或配置的 provider（`copilot`、`codex`、`opencode-go`、`deepseek`、`dashscope`、`openrouter` 或 `custom`） | 交互选择 | 无 |\n| --verbose | 启用详细日志 | false | -v |\n| --show-token | 认证时显示 GitHub token | false | 无 |\n\n只有在需要启用 GitHub Copilot provider 时，才需要执行 `copilot-api auth login --provider copilot`。使用 `codex` 或第三方 provider-only 模式不要求配置 Copilot。\n\n使用 `copilot-api auth login --provider deepseek`、`--provider dashscope`、`--provider openrouter` 或 `--provider opencode-go` 可以通过 CLI 快速新增或更新这些常用第三方 provider。DeepSeek 会提示输入掩码显示的 `apiKey`、provider `type`（默认 `anthropic`），以及默认 `https://api.deepseek.com/anthropic` 的 `baseUrl`。DashScope 会提示输入掩码显示的 `apiKey`、provider `type`（默认 `openai-compatible`）和预填默认值的 `baseUrl`。OpenRouter 只提示输入掩码显示的 `apiKey` 和预填默认值的 `baseUrl`，并固定写入 `type: \"anthropic\"`。OpenCode Go 只提示输入掩码显示的 `apiKey` 和预填默认值的 `baseUrl`，并固定写入 `type: \"openai-compatible\"`（baseUrl `https://opencode.ai/zen/go`）。配置并启用 provider 后，`copilot-api start` 可在没有 GitHub token 的情况下启动。\n\n使用 `copilot-api auth login --provider custom` 可以通过 CLI 新增或更新其他第三方 provider。命令会依次提示输入 provider name、项目支持的 type（`anthropic`、`openai-compatible` 或 `openai-responses`）、`baseUrl`、掩码显示的 `apiKey` 和 `authType`；`authType` 可保持 type 默认值，也可选择 `x-api-key` / `authorization`。\n\n### Debug 命令选项\n\n| 选项 | 说明 | 默认值 | 别名 |\n| --- | --- | --- | --- |\n| --json | 以 JSON 输出调试信息 | false | 无 |\n\n<a id=\"configuration-configjson\"></a>\n\n## 配置（config.json）\n\n- **位置：** Linux/macOS 为 `~/.local/share/copilot-api/config.json`，Windows 为 `%USERPROFILE%\\.local\\share\\copilot-api\\config.json`。\n- **默认结构：**\n  ```json\n  {\n    \"auth\": {\n      \"apiKeys\": [],\n      \"adminApiKey\": \"<startup 自动生成>\"\n    },\n    \"providers\": {},\n    \"modelMappings\": {},\n    \"extraPrompts\": {\n      \"gpt-5-mini\": \"<built-in exploration prompt>\"\n    },\n    \"smallModel\": \"gpt-5-mini\",\n    \"contextManagement\": {\n      \"messages\": true,\n      \"responses\": false\n    },\n    \"modelResponsesApiCompactThresholds\": {\n      \"gpt-5.4\": 217600,\n      \"gpt-5.5\": 217600,\n      \"gpt-5.6-sol\": 231200,\n      \"gpt-5.6-terra\": 231200,\n      \"gpt-5.6-luna\": 231200\n    },\n    \"modelReasoningEfforts\": {\n      \"gpt-5-mini\": \"low\"\n    },\n    \"useMessagesApi\": true,\n    \"useResponsesApiWebSocket\": true,\n    \"useResponsesApiWebSearch\": true,\n    \"messageApiWebSearchModel\": \"gpt-5-mini\"\n  }\n  ```\n- **auth.apiKeys：** 用于普通非 admin 路由的 API key。支持多个 key 轮换使用。请求可通过 `x-api-key: <key>` 或 `Authorization: Bearer <key>` 进行认证。若为空或省略，则普通路由的认证会被禁用。\n- **auth.adminApiKey：** 仅用于 `/admin/*` 路由的单个 admin key。若未配置，服务会在启动时自动生成一个随机 key，并回写到 `config.json`。它同样使用 `x-api-key` 或 `Authorization: Bearer` 这两种头，但普通 `auth.apiKeys` 不能访问 `/admin/*`。\n- **modelMappings：** 用于顶层 `POST /v1/messages`、`POST /v1/messages/count_tokens`、`POST /v1/responses` 和 `POST /v1/chat/completions` 请求的精确 `sourceModel -> targetModel` 重写映射，这几类接口共用同一份规则。省略该字段或保留为 `{}` 时，不会做模型重写。`source` 和 `target` 都必须是非空字符串。`target` 可以是普通模型 ID，也可以是 `provider/model` 形式的别名，例如 `dashscope/qwen3.6-plus`；重写发生在 provider alias 解析之前。这些映射不再按接口区分。`GET/POST /admin/config/model-mappings` 管理接口读写的也只有这个字段。\n- **extraPrompts：** `model -> prompt` 的映射。把 Anthropic 风格请求翻译为 Responses API 时，会将其附加到第一条 system prompt 后面。你可以借此为不同模型注入护栏或指引。缺失的默认项会自动补齐，但不会覆盖你自定义的 prompt。对于 GPT-5.3+ 模型（如 `gpt-5.3-codex`、`gpt-5.4`、`gpt-5.5`），未显式配置时会自动使用内置的 commentary prompt。内置 prompt 会启用带阶段感知的 commentary，让模型在工具调用或更深层推理前先发出简短的用户可见进度说明。\n- **providers：** 全局上游 provider 映射。每个 provider key（例如 `dashscope`）都会变成一个路由前缀（`/dashscope/v1/messages`）。支持 `type: \"anthropic\"`、`type: \"openai-compatible\"` 和 `type: \"openai-responses\"`。顶层客户端也可以在 `/v1/messages`、`/v1/messages/count_tokens`、`/v1/responses` 和 `/v1/chat/completions` 中使用 `model: \"dashscope/model-id\"`；AI gateway 会在转发上游前移除 `dashscope/` 前缀。`openai-compatible` provider 同时支持 chat 和 Messages 流程：`/v1/chat/completions` 会直连上游 `/v1/chat/completions`，而 `/v1/messages` 和 `/:provider/v1/messages` 会先翻译为上游 Chat Completions，再把响应翻译回 Anthropic Messages。`GET /v1/models` 会聚合已启用 provider 的模型，并以 `provider/model-id` 形式返回；单个 provider 的原始模型列表仍可使用 `GET /dashscope/v1/models`。\n  - `enabled`：可选，若省略则默认为 `true`。\n  - `baseUrl`：provider API 的基础 URL，不要带结尾的 endpoint。Anthropic provider 不要带 `/v1/messages`；OpenAI 兼容 provider 不要带 `/v1/chat/completions`；OpenAI Responses provider 不要带 `/v1/responses`。\n  - `apiKey`：作为上游凭据值使用；普通 provider 必须配置。\n  - `authType`：可选，控制 `apiKey` 如何发送到上游。普通 provider 支持 `x-api-key` 和 `authorization`。Anthropic provider 默认 `x-api-key`；OpenAI 兼容和 OpenAI Responses provider 默认 `authorization`。当设置为 `authorization` 时，代理会发送 `Authorization: Bearer <apiKey>`。`oauth2` 仅保留给内置 `codex` provider，并由 `auth login --provider codex` 自动写入。\n  - `pricingCurrency`：可选，provider 维度的 token 费用币种，例如 `USD` 或 `CNY`。快捷 provider 默认 DashScope、DeepSeek 为 `CNY`，Codex/OpenRouter 为 `USD`。费用按币种分别汇总，不做汇率换算。\n  - `models`：可选，按模型 ID 配置的映射。每个键为请求中的模型名，值支持：\n    - `temperature`：可选，当请求未指定时使用的默认温度。\n    - `topP`：可选，当请求未指定时使用的默认 `top_p`。\n    - `topK`：可选，当请求未指定时使用的默认 `top_k`。\n    - `extraBody`：可选，按模型合入上游请求体的动态字段；请求体显式同名字段优先。OpenAI 兼容 provider 可用它配置 `enable_thinking`、`preserve_thinking`、`reasoning_effort` 等字段。`thinking_budget` 是 OpenAI 兼容 provider 的特殊覆盖项：配置在 `extraBody` 后，会在 Anthropic `thinking.budget_tokens` 翻译之后强制写入，并覆盖请求派生出的预算值。对于 provider name 为 `dashscope` 或 `baseUrl` 包含 `aliyuncs.com` 的 provider，请求派生的 `thinking_budget`（来自 Anthropic `thinking.budget_tokens`）会转发给上游；其他 OpenAI 兼容 provider 会移除请求派生的 `thinking_budget`，但 `extraBody` 中的 `thinking_budget` 仍然生效。对于 DashScope provider，当 `preserve_thinking` 未在 `extraBody` 或请求体中显式设置时，默认为 `true`。\n    - `pricing`：可选，按模型配置 token 单价，币种使用 provider 的 `pricingCurrency`，单位为每 100 万 tokens。支持 `input`、`output`、`cachedInput`（隐式缓存读）、`explicitCachedInput`（显式缓存读）和 `cacheCreationInput`。如需按输入 token 总量分档，可用带 `maxInputTokens` 的 `tiers`。\n    - `contextCache`：可选，provider name 为 `dashscope` 或 `baseUrl` 包含 `aliyuncs.com` 时默认 `true`，其他 OpenAI 兼容 provider 默认 `false`。用于启用阿里云百炼/DashScope 的显式缓存（explicit context cache），会按其 Context Cache 格式在最多 4 个 content block 上注入 `cache_control: { \"type\": \"ephemeral\" }`。缓存断点策略与 opencode 主链路保持一致：前 2 条 system 消息 + 最后 2 条非 system 消息。标记字符串 content 时会把 `system` / `user` / `assistant` / `tool` 消息转换为 text content part 数组；已有数组 content 则标记最后一个 part。如果模型本身已经支持隐式缓存，或上游不支持该显式缓存扩展字段，可在模型配置中设为 `false`。支持相同显式缓存扩展的非 DashScope provider 可设为 `true`。同时适用于 `/v1/messages` 和 `/v1/chat/completions` 路由。\n    - `supportPdf`：可选，控制该模型是否支持 PDF/document content。默认 `false`，不支持时会把 PDF 转成提示文本；设为 `true` 时会把 PDF/document 转成 OpenAI Chat Completions 的 file part。\n    - `toolContentSupportType`：可选，配置该模型的 tool result content 支持能力，值为 `array`、`image`、`pdf` 的数组。provider 侧未配置时默认只发送 string tool content。若 `supportPdf` 为 `true` 但这里不包含 `pdf`，tool result 里的 file part 会被转成 user role 消息。Copilot 主链路不使用这个 provider 默认，仍按 array + image 且不支持 PDF 的能力处理。\n    - `type`：可选，按模型覆盖 provider 的协议类型。支持 `anthropic`、`openai-compatible` 和 `openai-responses`。设置后，provider 的 `/v1/messages` 路由会使用该模型的 type 替代 provider 级别的 type 进行请求路由、认证头解析和上游端点选择。适用于 OpenCode Go 等上游对不同模型同时支持 OpenAI 兼容和 Anthropic Messages API 的 provider。覆盖 type 时，认证头按覆盖后 type 的默认值解析（Anthropic 默认 `x-api-key`；OpenAI 兼容/Responses 默认 `authorization`）。\n\n  DashScope 模型配置示例：\n  ```json\n  {\n    \"providers\": {\n      \"dashscope\": {\n        \"type\": \"openai-compatible\",\n        \"enabled\": true,\n        \"baseUrl\": \"https://dashscope.aliyuncs.com/compatible-mode\",\n        \"apiKey\": \"sk-your-dashscope-key\",\n        \"pricingCurrency\": \"CNY\",\n        \"models\": {\n          \"qwen3.7-plus\": {\n            \"temperature\": 1,\n            \"topP\": 0.95,\n            \"topK\": 20,\n            \"extraBody\": {\n              \"preserve_thinking\": true\n            }\n          },\n          \"glm-5.1\": {\n            \"temperature\": 0.7,\n            \"topP\": 0.95,\n            \"contextCache\": true,\n            \"pricing\": {\n              \"tiers\": [\n                {\n                  \"maxInputTokens\": 32000,\n                  \"input\": 6,\n                  \"cachedInput\": 1.2,\n                  \"explicitCachedInput\": 0.6,\n                  \"cacheCreationInput\": 7.5,\n                  \"output\": 24\n                },\n                {\n                  \"maxInputTokens\": 200000,\n                  \"input\": 8,\n                  \"cachedInput\": 1.6,\n                  \"explicitCachedInput\": 0.8,\n                  \"cacheCreationInput\": 10,\n                  \"output\": 28\n                }\n              ]\n            },\n            \"extraBody\": {\n              \"preserve_thinking\": true\n            }\n          }\n        }\n      }\n    }\n  }\n  ```\n  内置 token 价格覆盖 Codex GPT 模型（USD）、DashScope `qwen3.7-max`、`qwen3.7-plus`、`glm-5.1`、`glm-5.2`（CNY），DeepSeek `deepseek-v4-flash`、`deepseek-v4-pro`、`deepseek-chat`、`deepseek-reasoner`（CNY），以及 OpenCode Go 模型（`glm-5.2`、`deepseek-v4-flash`、`deepseek-v4-pro`、`kimi-k2.7-code`、`mimo-v2.5`、`mimo-v2.5-pro`、`qwen3.7-plus`、`qwen3.7-max`、`minimax-m2.5`、`minimax-m3`，USD）。用户配置的 `pricing` 优先于内置价格。DashScope 若上游 usage 中出现 `cache_creation_input_tokens` 字段，cached tokens 按显式缓存读价计费；否则 `cachedInput` 作为隐式缓存读价。DeepSeek 的 `prompt_cache_hit_tokens` 会归入 cached input，`prompt_cache_miss_tokens` 会归入普通 input。\n- **smallModel：** 无工具预热消息的回退模型（例如 Claude Code 的探测请求）；默认是 `gpt-5-mini`。\n- **contextManagement：** 控制代理是否为 Responses API 附加 `context_management` 压缩指令。`messages` 作用于被翻译成 Responses API 的 Anthropic 风格 `/v1/messages` 请求，包括 `openai-responses` provider 的 Messages 路由，默认值为 `true`。`responses` 作用于 native `/v1/responses` 流量，包括 `provider/model` 别名和内置 `codex` provider，默认值为 `false`。只有在确认客户端支持 context management compaction 后，才建议在 Responses API 下启用 `responses`。启用后，请求体会带上 `context_management`，并在后续轮次中仅保留最新的压缩承载内容。**注意：** 对于 GPT-5.6 及以上模型（如 `gpt-5.6-sol`、`gpt-5.6-terra`、`gpt-5.6-luna`），context management 功能会被强制禁用，因为开启后会破坏这些模型的 prompt 缓存命中。此强制覆盖优先于 `contextManagement` 和 `modelResponsesApiCompactThresholds` 配置。\n- **modelResponsesApiCompactThresholds：** 按模型覆盖 Responses API 的 `compact_threshold`，仅在代理自动附加 `context_management` 时使用。它的优先级高于 `resolveResponsesCompactThreshold` 基于 `max_prompt_tokens * ratio` 的兜底阈值。默认将 `gpt-5.4` 和 `gpt-5.5` 设为 `217600`（`272000 * 0.8`），将 `gpt-5.6-sol`、`gpt-5.6-terra`、`gpt-5.6-luna` 设为 `231200`（`272000 * 0.85`）。未列出的模型继续使用原有兜底逻辑。\n- **modelReasoningEfforts：** `/v1/messages` 请求的模型级默认推理强度。仅当请求没有传入 `output_config.effort` 时，该配置才会生效。\n  - **优先级：** 请求中的 `output_config.effort` > `modelReasoningEfforts[model]` > 内置默认值（GPT-5.3+ 模型为 `xhigh`，其他模型为 `high`）。\n  - **转发字段：** 走 Copilot 原生 Messages API 时，最终值写入 `output_config.effort`；转换为 Responses API 时，最终值写入 `reasoning.effort`。\n  - **配置可选值：** `none`、`minimal`、`low`、`medium`、`high`、`xhigh`、`max`。\n- **useMessagesApi：** 当为 `true` 时，支持 Copilot 原生 `/v1/messages` 的 Claude 系模型会走 Messages API；否则回退到 `/chat/completions`。设为 `false` 可禁用 Messages API 路由，始终使用 `/chat/completions`。默认值为 `true`。\n- **useResponsesApiWebSocket：** 当为 `true` 时，Responses API 请求会优先对声明了 `ws:/responses` 的模型使用 Copilot websocket transport；仅声明 `/responses` 的模型仍走 HTTP。设为 `false` 可禁用 websocket 路由，并在模型支持 `/responses` 时使用 HTTP `/responses`。默认值为 `true`。\n- **useResponsesApiWebSearch：** 当为 `true` 时，服务端会保留 Responses API 中 `type: \"web_search\"` 的工具并透传到上游。设为 `false` 则会从 `/responses` payload 中移除这些工具。默认值为 `true`。\n- **messageApiWebSearchModel：** 顶层 Copilot `/v1/messages` 请求只包含服务端 `web_search` 工具时使用的全局模型，默认值为 `gpt-5-mini`。如果该值是 `provider/model` 别名，请求会进入对应 provider 的 Messages API 路径，并在转发前移除 provider 前缀。对于 Copilot GPT 模型，web search 会通过 `/responses` 执行。混合 `web_search` 与自定义工具的场景暂不支持，服务端会移除 server-side `web_search`。\n- **claudeTokenMultiplier：** 用于 Claude `/v1/messages/count_tokens` 请求在本地走 GPT tokenizer 估算时的乘数。默认值为 `1.15`。如果你的客户端仍然过晚触发上下文压缩，可以适当调大。这个配置只会在代理本地估算 Claude token 时生效；如果已经配置 `anthropicApiKey` 且 Anthropic token counting 调用成功，则会直接返回 Anthropic 的精确计数，不会使用这个乘数。\n- **anthropicApiKey：** 用于把 Claude `/v1/messages/count_tokens` 请求转发到 Anthropic 真实 token counting 端点的 API key，这样会返回精确计数，而不是 GPT tokenizer 估算值。也可通过环境变量 `ANTHROPIC_API_KEY` 设置。若未配置，或上游调用失败，则回退到由 `claudeTokenMultiplier` 控制的本地 GPT tokenizer 估算。\n\n编辑此文件后即可自定义 prompts，或替换为你自己的快速模型。修改完成后请重启服务（或重新执行命令），让缓存中的配置刷新生效。\n\n## API 认证\n\n- **受保护的普通路由：** 当配置了 `auth.apiKeys` 且非空时，除 `/`、`/usage-viewer` 和 `/usage-viewer/` 以外的普通路由都需要认证。\n- **Admin 路由：** 所有 `/admin/*` 路由都要求 `auth.adminApiKey`。如果缺失，服务会在启动时自动生成并在开始提供服务前写回 `config.json`。\n- **允许的认证头：**\n  - `x-api-key: <your_key>`\n  - `Authorization: Bearer <your_key>`\n- **CORS 预检：** `OPTIONS` 请求始终允许。\n- **未配置普通 key 时：** 普通路由仍可直接访问；但这条规则不适用于 `/admin/*`，后者只接受 `auth.adminApiKey`。\n\n普通受保护路由的示例请求：\n\n```sh\ncurl http://localhost:4141/v1/models \\\n  -H \"x-api-key: your_api_key\"\n```\n\nAdmin 路由的示例请求：\n\n```sh\ncurl http://localhost:4141/admin/config/model-mappings \\\n  -H \"x-api-key: your_admin_api_key\"\n```\n\n## API 端点\n\n服务端提供多个 OpenAI / Anthropic 兼容端点。请求会根据所选模型和 `provider/model` 别名路由到 GitHub Copilot、内置 `codex` provider 或已配置的 provider。\n\n### OpenAI 兼容端点\n\n这些端点模拟 OpenAI API 结构。\n\n| 端点 | 方法 | 说明 |\n| --- | --- | --- |\n| `POST /v1/responses` | `POST` | OpenAI 中用于生成模型响应的高级接口。支持 `openai-responses` provider 的 `provider/model` 别名。 |\n| `POST /v1/chat/completions` | `POST` | 为给定聊天对话创建模型响应。支持 `openai-compatible` provider 的 `provider/model` 别名；目标 provider 已配置时可在没有 Copilot 的情况下使用。 |\n| `GET /v1/models` | `GET` | 列出 Copilot 模型以及已启用 provider 的 `provider/model-id` 模型。来自 Codex 客户端（`User-Agent` 以 `codex` 开头）的请求会转发到 Codex Models 上游。 |\n| `POST /v1/embeddings` | `POST` | 创建表示输入文本的向量嵌入。 |\n\n### Codex 后端代理端点\n\n这些端点要求已有可用的 Codex 登录态。每个端点同时提供无版本前缀和 `/v1` 两种路径。\n\n| 端点 | 方法 | 说明 |\n| --- | --- | --- |\n| `POST /alpha/search`<br>`POST /v1/alpha/search` | `POST` | 将 JSON 请求体和查询参数透明转发到 Codex Alpha Search 上游。 |\n| `POST /images/generations`<br>`POST /v1/images/generations` | `POST` | 将 JSON 图片生成请求转发到 Codex Images 上游。请求未携带 `Content-Type` 时，网关默认补充 `application/json`。 |\n| `POST /images/edits`<br>`POST /v1/images/edits` | `POST` | 将图片编辑请求转发到 Codex Images 上游。请使用 `multipart/form-data`，并让 HTTP 客户端自动生成 `boundary`；网关会保留传入的 content type，并以流式方式转发上传请求体。 |\n\n对于以上所有端点，网关都会使用当前 Codex 登录态覆盖客户端的 authorization 和 account header，保留查询参数及兼容的请求头，并返回上游状态码、响应头和响应体。\n\n### Anthropic 兼容端点\n\n这些端点设计为兼容 Anthropic Messages API。provider 级的 models、Responses、alpha-search 和 images 路由同时支持无版本前缀与 `/v1` 两种路径；Messages 路由仍使用 `/v1`。\n\n| 端点 | 方法 | 说明 |\n| --- | --- | --- |\n| `POST /v1/messages` | `POST` | 为给定对话创建模型响应。支持已配置 provider 的 `provider/model` 别名，包括通过 `openai-compatible` provider 做翻译。 |\n| `POST /v1/messages/count_tokens` | `POST` | 计算一组消息的 token 数。支持已配置 provider 的 `provider/model` 别名。 |\n| `POST /:provider/v1/messages` | `POST` | 将 Anthropic Messages 请求代理到已配置的 Anthropic provider，或翻译到 OpenAI 兼容 / OpenAI Responses provider。 |\n| `GET /:provider/models`<br>`GET /:provider/v1/models` | `GET` | 将模型列表请求代理到已配置的 provider。对 `codex` 默认返回内置模型目录；Codex 客户端（`User-Agent` 以 `codex` 开头）会转发到 Codex Models 上游。 |\n| `POST /:provider/v1/messages/count_tokens` | `POST` | 为 provider 路由请求在本地计算 token 数。 |\n| `POST /:provider/responses`<br>`POST /:provider/v1/responses` | `POST` | 将 OpenAI Responses 请求代理到已配置的 `openai-responses` provider（含 `codex`）。 |\n| `POST /:provider/alpha/search`<br>`POST /:provider/v1/alpha/search` | `POST` | 代理 alpha-search 请求。对 `codex` 转发到 Codex Alpha Search 上游；其他 provider 转发到 `{baseUrl}/v1/alpha/search`。 |\n| `POST /:provider/images/generations`<br>`POST /:provider/v1/images/generations` | `POST` | 代理图片生成。对 `codex` 使用 Codex Images 上游；其他 provider 转发到 `{baseUrl}/v1/images/generations`（15 分钟超时）。 |\n| `POST /:provider/images/edits`<br>`POST /:provider/v1/images/edits` | `POST` | 代理图片编辑。对 `codex` 使用 Codex Images 上游；其他 provider 以 multipart/流式方式转发到 `{baseUrl}/v1/images/edits`（15 分钟超时）。 |\n\n### 使用量监控端点\n\n用于监控 Copilot 用量与额度的新端点。\n\n| 端点 | 方法 | 说明 |\n| --- | --- | --- |\n| `GET /usage` | `GET` | 获取详细的 Copilot 使用统计与额度信息。 |\n| `GET /token` | `GET` | 获取当前 API 正在使用的 Copilot token。 |\n\n### Admin / 配置端点\n\n这些端点用于本地管理操作，只接受 `auth.adminApiKey`。\n\n| 端点 | 方法 | 说明 |\n| --- | --- | --- |\n| `GET /admin/config/model-mappings` | `GET` | 返回当前 `config.json` 路径以及生效中的 `modelMappings` 映射。 |\n| `POST /admin/config/model-mappings` | `POST` | 只更新 `config.json` 里的 `modelMappings` 字段，并回传更新后的结果。 |\n\n## 使用示例\n\n常用 `npx` 命令：\n\n```sh\n# 基础启动\nnpx @jeffreycao/copilot-api@latest start\n\n# 自定义端口并开启详细日志\nnpx @jeffreycao/copilot-api@latest start --port 8080 --verbose\n\n# 执行认证流程\nnpx @jeffreycao/copilot-api@latest auth login\n\n# 配置第三方 provider，然后不依赖 GitHub Copilot 启动\nnpx @jeffreycao/copilot-api@latest auth login --provider dashscope\nnpx @jeffreycao/copilot-api@latest start\n\n# 以 JSON 格式输出调试信息\nnpx @jeffreycao/copilot-api@latest debug --json\n\n# 用 Bun 而不是 Node.js 运行已发布 CLI\nbunx --bun @jeffreycao/copilot-api@latest start\n```\n\n配置 `dashscope` 后的 OpenAI 兼容 provider 调用示例：\n\n```sh\ncurl http://localhost:4141/v1/chat/completions \\\n  -H \"content-type: application/json\" \\\n  -d '{\"model\":\"dashscope/qwen3.6-plus\",\"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]}'\n\ncurl http://localhost:4141/dashscope/v1/messages \\\n  -H \"content-type: application/json\" \\\n  -d '{\"model\":\"qwen3.6-plus\",\"max_tokens\":1024,\"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]}'\n```\n\n## 使用建议\n\n<a id=\"claudemd-or-agentsmd-recommended-content\"></a>\n\n### CLAUDE.md 或 AGENTS.md 推荐内容\n\n如果你想手动加入这些提醒，请在 Claude Code 的 `CLAUDE.md`，或 opencode/codex 的 `AGENTS.md` 中加入以下内容：\n\n```\n- Prohibited from directly asking questions to users, MUST use question tool.\n- Once you can confirm that the task is complete, MUST use question tool to make user confirm. The user may respond with feedback if they are not satisfied with the result, which you can use to make improvements and try again, after try again, MUST use question tool to make user confirm again.\n```\n"}, "4bbb57890d6fa1f5490258f417700298605e14fe": {"t": 1785765555.2085583, "n": 32698, "h": "b12b34113eb7ff27", "c": "# Copilot API Proxy\n\n[English](./README.md) | 简体中文\n\n## 重要说明\n\n> [!IMPORTANT]\n> **使用前请先注意以下几点：**\n>\n> 1. **Claude Code 配置：** 与 Claude Code 搭配使用时，请将模型 ID 配置为 `claude-opus-4-8`。示例 claude `settings.json` 见 [通过 `settings.json` 手动配置](#manual-configuration-with-settingsjson)。\n>\n> 2. **内置 `copilot`、`codex` 与第三方 provider：** 执行 `npx @jeffreycao/copilot-api@latest auth`，可选择 `copilot`、`codex`、`deepseek`、`custom` 等 provider。\n>\n> 3. **注意事项：** README 顶部移除的 GitHub Copilot warning 见 [GitHub Copilot 安全提示](./NOTICE.md#github-copilot-security-notice)。\n\n---\n\n## 项目概览\n\n这是一个小型 AI gateway，可以使用 GitHub Copilot、内置 `codex` provider，也可以使用 DashScope 等已配置的第三方 provider。GitHub Copilot 现在是可选能力：如果本地没有 GitHub token，只要至少配置了一个启用中的 provider，服务仍可按 provider-only 模式启动。\n\nAI gateway 会从同一个本地端点暴露 OpenAI / Anthropic 兼容 API，让 [Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview)、OpenCode、Codex 和 OpenAI 兼容客户端可以共用同一个本地服务。\n\n在 GitHub Copilot 路径上，AI gateway 会在可用时优先使用 Copilot 原生的 Anthropic 风格 Messages API，在重工具调用场景下保留更原生的 Claude 行为。\n\n## 功能特性\n\n- **OpenAI 与 Anthropic 双兼容**：通过 `/v1/responses`、`/v1/chat/completions`、`/v1/models`、`/v1/embeddings` 和 `/v1/messages` 对外暴露同一个本地 AI gateway。\n- **Copilot 可选**：有 GitHub 凭据时可以使用 GitHub Copilot，没有 GitHub 凭据时也可以只依赖已配置的 provider 运行。\n- **同一网关接入 Copilot、`codex` 与第三方 provider**：可统一路由 GitHub Copilot、内置 `codex` provider 和配置好的外部 provider。\n- **第三方 provider 可独立启动**：配置 DashScope、DeepSeek、OpenRouter 或自定义 provider 后，不需要 GitHub Copilot 登录即可启动 AI gateway。\n- **OpenAI 兼容 provider 同时支持 chat 和 Messages API**：`openai-compatible` provider 可通过顶层 `/v1/chat/completions` 搭配 `model: \"provider/model\"` 提供 Chat Completions，也可通过 `/v1/messages` 完成 Anthropic Messages 的请求/响应翻译。\n- **面向 Claude 的更原生 Copilot 路由**：优先使用原生 `/v1/messages`，保留 Claude 风格工具流，支持 Anthropic beta 能力、通过 Responses-capable 模型支持 Claude WebSearch，并保留 subagent / session 标记。\n- **Claude Code 与 OpenCode 集成**：兼容 Claude Code 与 OpenCode，也支持通过 `@ai-sdk/anthropic` 直接作为 Anthropic provider 使用。\n- **灵活的认证与部署选项**：支持交互式登录、直接 token、个人 / Business / Enterprise、GitHub Enterprise、opencode OAuth 和自定义数据目录。\n- **多 provider 路由**：可暴露 `/:provider/...` 路由，也可在顶层 API 上使用 `model: \"provider/model\"`。\n\n## 前置要求\n\n- Bun（>= 1.2.x）\n- 如果要通过 `npx` 运行已发布 CLI，需要 Node.js\n- 只有在使用 GitHub Copilot provider 时，才需要已订阅 Copilot 的 GitHub 账号\n- 如果不使用 GitHub Copilot，需要至少一个已配置 provider 的 API key 或 OAuth 登录\n\n## 安装\n\n安装依赖：\n\n```sh\nbun install\n```\n\n直接从源码启动服务：\n\n```sh\nbun run start start\n```\n\n## 从源码运行\n\n本项目可以通过多种方式从源码运行：\n\n### 开发模式\n\n```sh\nbun run dev start\n```\n\n### 生产模式\n\n```sh\nbun run start start\n```\n\n## 通过 npx 使用\n\n你可以直接用 npx 运行本项目：\n\n> [!IMPORTANT]\n> 通过 `npx` 运行时，token usage 存储会使用 Node 内置的 `node:sqlite` 模块。该能力会在 Node.js >= 22.13.0 时启用；Node.js < 22.13.0 时 CLI 仍可启动，但会禁用 token usage 存储。\n>\n> 如果不升级 Node.js 但仍需要 token usage 存储，可以改用 Bun 运行已发布 CLI：`bunx --bun @jeffreycao/copilot-api@latest start`。\n\n```sh\nnpx @jeffreycao/copilot-api@latest start\n```\n\n带参数示例：\n\n```sh\nnpx @jeffreycao/copilot-api@latest start --port 8080\n```\n\n如果只想做认证或 provider 配置：\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth\n```\n\n如果要不依赖 GitHub Copilot 运行，先配置至少一个 provider，然后正常启动服务：\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth login --provider dashscope\nnpx @jeffreycao/copilot-api@latest start\n```\n\n## 配合 Docker 使用\n\n构建镜像：\n\n```sh\ndocker build -t copilot-api .\n```\n\n通过 bind mount 运行容器，让认证数据在重启后保留：\n\n```sh\nmkdir -p ./copilot-data\ndocker run -p 4141:4141 -v $(pwd)/copilot-data:/root/.local/share/copilot-api copilot-api\n```\n\n这会把宿主机上的 `./copilot-data` 映射到容器内的 `/root/.local/share/copilot-api`，用于持久化 GitHub 认证数据、provider 配置和其他 gateway 状态。\n\n也可以直接通过环境变量传入 GitHub token：\n\n```sh\ndocker run -p 4141:4141 -e GH_TOKEN=your_github_token_here copilot-api\n```\n\n## Electron 桌面应用\n\n如果你更喜欢图形界面，仓库里还提供了位于 `desktop/` 的 Electron 桌面应用。它支持 GitHub Copilot 登录、OpenAI Codex OAuth，以及 DeepSeek、DashScope、OpenRouter 或自定义 provider 的 API Key 配置。授权或配置 provider 后，可以一键启动或停止本地代理，并在界面里直接查看本地端点、鉴权 Header、可用模型、额度和日志。\n\n设置页还可以配置 `OAuth App`、`API Home`、`Enterprise URL`、详细日志以及最小化到托盘。桌面安装包发布在 GitHub Releases：\n\nhttps://github.com/caozhiyuan/copilot-api/releases\n\n下载对应平台的安装包后，在应用内授权或配置 provider，选择端口并启动服务，再把你的客户端指向应用里显示的本地端点即可。发布版桌面应用使用随包内置的 Electron 运行时，正常使用不需要额外安装 Node.js；token usage 历史记录会在该内置运行时支持 SQLite 时启用。\n\n桌面应用里的高级配置页会通过 `GET/POST /admin/config/model-mappings` 读写这份共享的模型映射。同一份映射会统一作用于 `POST /v1/messages`、`POST /v1/messages/count_tokens`、`POST /v1/responses` 和 `POST /v1/chat/completions`，不再按接口区分。它使用的是 `auth.adminApiKey`，不是普通的 `auth.apiKeys`；应用会在服务启动并自动生成该 key 后，直接从 `config.json` 读取它来发起请求。\n\n### 桌面应用截图\n\n下面展示了桌面应用中的首页、Token 用量统计页面：\n\n<p align=\"center\">\n  <img src=\"./docs/screenshots/desktop-dashboard.png\" alt=\"Copilot API 桌面应用首页\" width=\"49%\" />\n  <img src=\"./docs/screenshots/desktop-token-usage.png\" alt=\"Copilot API 桌面应用 Token 用量页\" width=\"49%\" />\n</p>\n\n## 与 Claude Code 一起使用\n\n这个 AI gateway 可以为 [Claude Code](https://docs.anthropic.com/en/claude-code) 提供后端能力。Claude Code 是 Anthropic 提供的实验性面向开发者的对话式 AI 助手。\n\n有两种方式可以把 Claude Code 配置为使用这个 AI gateway：\n\n### 通过 `--claude-code` 标志进行交互式配置\n\n执行带 `--claude-code` 的 `start` 命令开始：\n\n```sh\nnpx @jeffreycao/copilot-api@latest start --claude-code\n```\n\n你会被提示选择一个主模型，以及一个用于后台任务的 \"small, fast\" 模型。选择完成后，会有一条命令被复制到剪贴板中。该命令会设置 Claude Code 使用这个 AI gateway 所需的环境变量。\n\n在新的终端中粘贴并执行这条命令，即可启动 Claude Code。\n\n<a id=\"manual-configuration-with-settingsjson\"></a>\n\n### 通过 `settings.json` 手动配置\n\n另一种方式是在项目根目录中创建 `.claude/settings.json` 文件，并写入 Claude Code 所需的环境变量。这样你就不需要每次都运行交互式配置了。\n\n下面是一个 `.claude/settings.json` 示例：\n\n```json\n{\n  \"env\": {\n    \"ANTHROPIC_BASE_URL\": \"http://localhost:4141\",\n    \"ANTHROPIC_AUTH_TOKEN\": \"dummy\",\n    \"ANTHROPIC_MODEL\": \"deepseek/deepseek-v4-pro\",\n    \"ANTHROPIC_DEFAULT_SONNET_MODEL\": \"deepseek/deepseek-v4-pro\",\n    \"ANTHROPIC_DEFAULT_HAIKU_MODEL\": \"deepseek/deepseek-v4-flash\",\n    \"DISABLE_NON_ESSENTIAL_MODEL_CALLS\": \"1\",\n    \"CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC\": \"1\",\n    \"CLAUDE_CODE_ATTRIBUTION_HEADER\": \"0\",\n    \"CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION\": \"false\",\n    \"CLAUDE_CODE_DISABLE_TERMINAL_TITLE\": \"true\",\n    \"CLAUDE_CODE_ENABLE_AWAY_SUMMARY\": \"0\"\n  },\n  \"permissions\": {\n    \"deny\": [\n      \"mcp__ide__executeCode\"\n    ]\n  }\n}\n```\n\n- 请根据需要替换 `ANTHROPIC_MODEL`、`ANTHROPIC_DEFAULT_OPUS_MODEL`、`ANTHROPIC_DEFAULT_SONNET_MODEL` 和 `ANTHROPIC_DEFAULT_HAIKU_MODEL`。配置完成后，请安装 claude code 插件，见 [插件集成](#plugin-integrations)。\n- 将 `CLAUDE_CODE_ATTRIBUTION_HEADER` 设为 `0` 可以阻止 Claude Code 在 system prompt 中附加计费和版本信息，从而避免 prompt cache 失效。\n- 关闭 `CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION` 和 `CLAUDE_CODE_ENABLE_AWAY_SUMMARY` 可以避免不必要地消耗额度。\n- Claude Code WebSearch 已支持纯搜索请求。Copilot 路径请保持全局 `messageApiWebSearchModel` 指向 Responses-capable GPT 模型或 `provider/model` 别名；provider 路由请使用原生 Anthropic provider 或 `openai-responses` provider。只有在你明确想禁止这类流量时，才需要把 `WebSearch` 加到 `permissions.deny`。\n- 如果使用的不是 Claude 模型，请不要启用 `ENABLE_TOOL_SEARCH`。如果使用的是 Claude 模型，则可以启用 `ENABLE_TOOL_SEARCH`。当前 Claude Code 使用的是客户端 tool search 模式，在该模式下每次加载 defer tools 都需要额外请求一次。\n- `CLAUDE_CODE_AUTO_COMPACT_WINDOW`：设置用于自动压缩计算的上下文容量（以 token 为单位）。默认使用模型自身的上下文窗口：标准模型为 200K，扩展上下文模型为 1M。使用 1M 上下文模型（如 `claude-opus-4-6[1m]`）时，可设置一个较低的值（如 `500000`）将窗口视为 500K 用于压缩计算。该值受限于模型的实际上下文窗口上限。`CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` 会基于此值的百分比生效。设置此变量可将压缩阈值与状态栏的 `used_percentage` 解耦（后者始终使用模型的完整上下文窗口）。\n\n更多选项见：[Claude Code settings](https://docs.anthropic.com/en/docs/claude-code/settings#environment-variables)\n\n也可以参考 IDE 集成说明：[Add Claude Code to your IDE](https://docs.anthropic.com/en/docs/claude-code/ide-integrations)\n\n## 与 OpenCode 一起使用\n\nOpenCode 已经有直接的 GitHub Copilot provider。本节适用于你希望让 OpenCode 通过 `@ai-sdk/anthropic` 指向这个 AI gateway，并复用本 README 前面提到的 agent 行为时。\n\n### 最小配置\n\n使用 OpenCode OAuth app 启动 AI gateway：\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth --oauth-app=opencode\nnpx @jeffreycao/copilot-api@latest start\n```\n\n然后让 OpenCode 通过 `@ai-sdk/anthropic` 指向这个 AI gateway。\n\n示例 `~/.config/opencode/opencode.json`：\n\n```json\n{\n  \"$schema\": \"https://opencode.ai/config.json\",\n  \"provider\": {\n    \"local\": {\n      \"npm\": \"@ai-sdk/anthropic\",\n      \"name\": \"My Local\",\n      \"options\": {\n        \"baseURL\": \"http://localhost:4141/v1\",\n        \"apiKey\": \"dummy\"\n      },\n      \"models\": {\n        \"gpt-5.4\": {\n          \"name\": \"gpt-5.4\",\n          \"modalities\": {\n            \"input\": [\"text\", \"image\"],\n            \"output\": [\"text\"]\n          },\n          \"limit\": {\n            \"context\": 400000,\n            \"input\": 272000,\n            \"output\": 128000\n          }\n        },\n        \"claude-sonnet-4.6\": {\n          \"id\": \"claude-sonnet-4.6\",\n          \"name\": \"claude-sonnet-4.6\",\n          \"modalities\": {\n            \"input\": [\"text\", \"image\"],\n            \"output\": [\"text\"]\n          },\n          \"limit\": {\n            \"context\": 200000,\n            \"output\": 32000\n          },\n          \"options\": {\n            \"thinking\": {\n              \"type\": \"adaptive\"\n            },\n            \"effort\": \"max\"\n          }\n        }\n      }\n    }\n  }\n}\n```\n\n这些字段的重要性：\n\n- `npm: \"@ai-sdk/anthropic\"` 是关键。OpenCode 会以 Anthropic Messages 语义与这个 AI gateway 通信，而不是把一切扁平化为 OpenAI Chat Completions。\n- `options.baseURL` 应设为 `http://localhost:4141/v1`；Anthropic SDK 会自动补上 `/messages`、`/models` 和 `/messages/count_tokens`。\n- 如果你在此代理中启用了 `auth.apiKeys`，请把 `dummy` 替换为真实 key；否则任意占位值都可以。\n\n## 与 Codex 一起使用\n\n这个 AI gateway 也可以为 Codex 提供后端能力。\n\n### Codex `config.toml` 参考配置\n\n把以下 `[model_providers.copilot_api]` 段加入你的 Codex `~/.codex/config.toml`：\n\n```toml\nmodel_provider = \"copilot_api\"\nmodel_reasoning_summary = \"auto\"\nmodel_context_window = 272000\nmodel_auto_compact_token_limit = 244800\n\n[model_providers.copilot_api]\nname = \"OpenAI\"\nbase_url = \"http://localhost:4141\"\nenv_key = \"GITHUB_COPILOT_API_KEY\"\nrequires_openai_auth = true\nsupports_websockets = false\nwire_api = \"responses\"\nrequest_max_retries = 3\nstream_max_retries = 1\nstream_idle_timeout_ms = 300000\n\n[features]\nremote_compaction_v2 = true\n\n[analytics]\nenabled = false\n```\n\n> [!NOTE]\n> 此配置仅限于 Codex 与 GitHub Copilot provider。`name` 一定要配置为 `\"OpenAI\"`。它可以缓解 Codex local compact 不命中缓存的问题。\n\n## GPT Tool Search\n\n对于 `gpt-5.4+` 这类 GPT Responses 模型，这个 AI gateway 可以通过一个很小的 MCP bridge 暴露 Responses `tool_search`。Claude Code 和 opencode 都可以使用同一个 bridge，前提是客户端会加载 MCP server，并且 Anthropic Messages 流量会经过这个 AI gateway。\n\nGPT 模型不要设置 Claude Code 原生的 `ENABLE_TOOL_SEARCH`。这个开关启用的是 Claude Code 自己的客户端 tool search 模式，可能导致 deferred 工具定义不再转发给 AI gateway。这个 AI gateway 需要完整的工具定义，这样才能只保留那一小组常驻加载工具，其余工具统一转换为 Responses deferred namespace。\n\n如果你安装了 `tool-search@copilot-api-marketplace`，Claude Code 会自动带上这个 MCP bridge，可以跳过下面这段 Claude Code MCP 手动配置。\n\n请把 tool search bridge 加到 Claude Code 使用的 MCP 配置中：\n\n```json\n{\n  \"mcpServers\": {\n    \"tool_search\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@jeffreycao/copilot-api@latest\", \"mcp\"]\n    }\n  }\n}\n```\n\n请把 tool search bridge 加到 opencode 使用的 MCP 配置中：\n\n```json\n{\n  \"mcp\": {\n    \"tool_search\": {\n      \"type\": \"local\",\n      \"command\": [\"npx\", \"-y\", \"@jeffreycao/copilot-api@latest\", \"mcp\"]\n    }\n  }\n}\n```\n\n本地开发时可以将命令换成 `bun`，参数换成 `[\"run\", \"./src/main.ts\", \"mcp\"]`。\n\nAI gateway 内部现在会把 OpenAI Responses `tool_search` 配置成 client-executed 模式。deferred tools 仍然会作为可搜索 namespace 暴露给模型，但会明确要求模型直接返回下一步要加载的精确工具名列表。\n\n该 bridge 使用直接工具选择，不做 query 搜索。工具入参是 `names`，值为逗号分隔的精确 deferred 工具名，例如 `TaskList,TaskGet,mcp__fetch__fetch`。\n\n<a id=\"plugin-integrations\"></a>\n\n## 插件集成\n\n本项目为 Claude Code 和 opencode 提供了插件集成。\n\n#### Claude Code 插件集成（基于 marketplace）\n\nClaude Code 集成现在拆分为两个插件：\n\n- `agent-inject` 会在 `SubagentStart` 时注入 `__SUBAGENT_MARKER__...`，以便 AI gateway 推导 `x-initiator: agent`。\n- `tool-search` 会注册用于 GPT Responses deferred tool loading 的 `tool_search` MCP bridge。\n\n- 本仓库中的 marketplace catalog：`.claude-plugin/marketplace.json`\n- 本仓库中的插件源码：`plugin/claude/agent-inject`、`plugin/claude/tool-search`\n\n远程添加 marketplace：\n\n```sh\n/plugin marketplace add https://github.com/caozhiyuan/copilot-api.git\n```\n\n从 marketplace 安装插件：\n\n```sh\n/plugin install agent-inject@copilot-api-marketplace\n/plugin install tool-search@copilot-api-marketplace\n```\n\n安装后，`agent-inject` 会在 `SubagentStart` 时注入 `__SUBAGENT_MARKER__...`，AI gateway 会利用它推导 `x-initiator: agent`。\n\n`agent-inject` 还会注册一个 `UserPromptSubmit` hook，并返回 `{\"continue\": true}`；同时它也可以通过环境变量注入 `SessionStart` reminder 规则：\n\n- `CLAUDE_PLUGIN_ENABLE_QUESTION_RULES=1` 会自动为 Claude Code 启用两条关于使用 `question` 工具的提醒。你也可以把同样的提醒手动写进 `CLAUDE.md`；见 [CLAUDE.md 或 AGENTS.md 推荐内容](#claudemd-or-agentsmd-recommended-content)。\n- `CLAUDE_PLUGIN_ENABLE_NO_BACKGROUND_AGENTS_RULE=1` 会启用关于避免在 agent hooks 中使用 `run_in_background: true` 的提醒。\n\n`tool-search` 插件内置了 [GPT Tool Search](#gpt-tool-search) 一节描述的同一个 MCP bridge，因此安装该插件后，Claude Code 用户无需再手动配置 `tool_search` server。\n\n#### Opencode 插件\n\nsubagent 标记生成器被打包为一个 opencode 插件，位于 `plugin/opencode/subagent-marker.js`。\n\n**安装方式：**\n\n将插件文件复制到你的 opencode 插件目录：\n\n```sh\n# 克隆或下载本仓库后复制该插件\ncp plugin/opencode/subagent-marker.js ~/.config/opencode/plugins/\n```\n\n或者手动在 `~/.config/opencode/plugins/subagent-marker.js` 创建该文件，并填入插件内容。\n\n**功能：**\n\n- 跟踪 subagent 创建的子会话\n- 自动在 subagent 聊天消息前添加 marker system reminder（`__SUBAGENT_MARKER__...`）\n- 设置 `x-session-id` 请求头以跟踪会话\n- 让这个 AI gateway 能够把来自 subagent 的请求识别为 `x-initiator: agent`\n\n该插件会挂接到 `session.created`、`session.deleted`、`chat.message` 和 `chat.headers` 事件上，以无缝提供 subagent marker 能力。\n\n## 使用量查看器\n\n服务启动后，控制台会输出一个 Copilot 使用量看板 URL。这个看板是一个用于监控 API 用量的 Web 界面。\n\n1. 启动服务。例如使用 npx：\n   ```sh\n   npx @jeffreycao/copilot-api@latest start\n   ```\n2. 服务会输出一个 usage viewer 的 URL。将它复制到浏览器中打开，形式大致如下：\n   `http://localhost:4141/usage-viewer?endpoint=http://localhost:4141/usage`\n   - 如果你在 Windows 上使用 `start.bat` 脚本，这个页面会自动打开。\n\n看板提供了更易读的 Copilot 用量视图：\n\n> token usage 历史记录需要 Bun 或 Node.js >= 22.13.0。Node.js < 22.13.0 时服务会正常运行，但 token usage 存储会被禁用。\n\n- **API Endpoint URL**：通过 URL 查询参数指定 API endpoints，默认指向本地服务。支持手动切换为其他兼容 endpoints。\n- **x-api-key 认证**：如果启用了 API Key 认证，可填入 `x-api-key` 请求头。密钥会持久化保存在浏览器本地存储中。\n- **Period 选择器**：支持 Day / Week / Month 三种时间范围，切换时 URL 参数会自动同步，方便收藏和分享。\n- **Fetch Data**：点击 \"Refresh\" 按钮加载或刷新使用数据。页面加载时也会自动拉取数据。\n- **Copilot Quotas 额度**：通过进度条展示 Chat、Completions 等不同服务的额度使用情况，悬停可查看已用/剩余详情。\n- **Token Usage 指标卡片**：汇总当前周期的 Total、Input、Output、Cache Read、Cache Write、Requests 和预估费用。\n- **趋势图（Week / Month）**：提供按模型和指标筛选的折线趋势图，点击数据点可查看单日用量明细。\n- **Model Breakdown 表格**：按模型维度列出周期内的请求数、输入/输出/缓存 token 和预计费用。\n- **Request Events 分页列表**：按时间排序的请求事件记录，支持分页浏览，含时间戳、模型、请求 ID 和 token 用量。\n- **Detailed Information**：展示 API 返回的完整 JSON 响应，便于深入分析所有可用统计数据。\n- **URL-based Configuration**：也可通过 `endpoint` 和 `period` 查询参数直接指定 API 端点与时间范围。例如：\n  `http://localhost:4141/usage-viewer?endpoint=http://your-api-server/usage&period=week`\n\n### Usage Viewer 截图\n\n<p align=\"center\">\n  <img src=\"./docs/screenshots/usage-viewer.png\" alt=\"Copilot API Usage Viewer 页面\" width=\"900\" />\n</p>\n\n## 命令结构\n\nCopilot API 现在使用子命令结构，主要命令包括：\n\n- `start`：启动 AI gateway 服务。如果已有 GitHub token，则启用 Copilot 路径；如果没有 GitHub token，但存在至少一个启用中的 provider，则按 provider-only 模式启动；如果两者都没有，会引导你配置 provider。\n- `auth`：仅执行 provider 登录或配置流程，不启动服务。可用于 GitHub Copilot 登录、Codex OAuth，或第三方 provider API key 配置。\n- `debug`：显示诊断信息，包括版本、运行时详情、文件路径以及认证状态，便于排障与支持。\n\n## 命令行选项\n\n### 全局选项\n\n以下选项可用于任意子命令。若在子命令之前传入，请使用 `--key=value` 形式：\n\n| 选项 | 说明 | 默认值 | 别名 |\n| --- | --- | --- | --- |\n| --api-home | API home 目录路径（设置 `COPILOT_API_HOME`） | 无 | 无 |\n| --oauth-app | OAuth app 标识符（设置 `COPILOT_API_OAUTH_APP`） | 无 | 无 |\n| --enterprise-url | GitHub Enterprise URL（设置 `COPILOT_API_ENTERPRISE_URL`） | 无 | 无 |\n\n### Start 命令选项\n\n以下是 `start` 命令可用的命令行选项：\n\n| 选项 | 说明 | 默认值 | 别名 |\n| --- | --- | --- | --- |\n| --port | 监听端口 | 4141 | -p |\n| --verbose | 启用详细日志 | false | -v |\n| --github-token | 直接提供 GitHub token（必须通过 `auth` 子命令生成） | 无 | -g |\n| --claude-code | 生成一个使用 Copilot API 配置启动 Claude Code 的命令 | false | -c |\n| --show-token | 在获取和刷新时显示 GitHub 与 Copilot token | false | 无 |\n| --proxy-env | 从环境变量初始化代理 | false | 无 |\n\n### Auth 命令选项\n\n| 选项 | 说明 | 默认值 | 别名 |\n| --- | --- | --- | --- |\n| --provider | 要登录或配置的 provider（`copilot`、`codex`、`opencode-go`、`deepseek`、`dashscope`、`openrouter` 或 `custom`） | 交互选择 | 无 |\n| --verbose | 启用详细日志 | false | -v |\n| --show-token | 认证时显示 GitHub token | false | 无 |\n\n只有在需要启用 GitHub Copilot provider 时，才需要执行 `copilot-api auth login --provider copilot`。使用 `codex` 或第三方 provider-only 模式不要求配置 Copilot。\n\n使用 `copilot-api auth login --provider deepseek`、`--provider dashscope`、`--provider openrouter` 或 `--provider opencode-go` 可以通过 CLI 快速新增或更新这些常用第三方 provider。DeepSeek 会提示输入掩码显示的 `apiKey`、provider `type`（默认 `anthropic`），以及默认 `https://api.deepseek.com/anthropic` 的 `baseUrl`。DashScope 会提示输入掩码显示的 `apiKey`、provider `type`（默认 `openai-compatible`）和预填默认值的 `baseUrl`。OpenRouter 只提示输入掩码显示的 `apiKey` 和预填默认值的 `baseUrl`，并固定写入 `type: \"anthropic\"`。OpenCode Go 只提示输入掩码显示的 `apiKey` 和预填默认值的 `baseUrl`，并固定写入 `type: \"openai-compatible\"`（baseUrl `https://opencode.ai/zen/go`）。配置并启用 provider 后，`copilot-api start` 可在没有 GitHub token 的情况下启动。\n\n使用 `copilot-api auth login --provider custom` 可以通过 CLI 新增或更新其他第三方 provider。命令会依次提示输入 provider name、项目支持的 type（`anthropic`、`openai-compatible` 或 `openai-responses`）、`baseUrl`、掩码显示的 `apiKey` 和 `authType`；`authType` 可保持 type 默认值，也可选择 `x-api-key` / `authorization`。\n\n### Debug 命令选项\n\n| 选项 | 说明 | 默认值 | 别名 |\n| --- | --- | --- | --- |\n| --json | 以 JSON 输出调试信息 | false | 无 |\n\n<a id=\"configuration-configjson\"></a>\n\n## 配置（config.json）\n\n- **位置：** Linux/macOS 为 `~/.local/share/copilot-api/config.json`，Windows 为 `%USERPROFILE%\\.local\\share\\copilot-api\\config.json`。\n- **默认结构：**\n  ```json\n  {\n    \"auth\": {\n      \"apiKeys\": [],\n      \"adminApiKey\": \"<startup 自动生成>\"\n    },\n    \"providers\": {},\n    \"modelMappings\": {},\n    \"extraPrompts\": {\n      \"gpt-5-mini\": \"<built-in exploration prompt>\"\n    },\n    \"smallModel\": \"gpt-5-mini\",\n    \"contextManagement\": {\n      \"messages\": true,\n      \"responses\": false\n    },\n    \"modelResponsesApiCompactThresholds\": {\n      \"gpt-5.4\": 217600,\n      \"gpt-5.5\": 217600,\n      \"gpt-5.6-sol\": 231200,\n      \"gpt-5.6-terra\": 231200,\n      \"gpt-5.6-luna\": 231200\n    },\n    \"modelReasoningEfforts\": {\n      \"gpt-5-mini\": \"low\"\n    },\n    \"useMessagesApi\": true,\n    \"useResponsesApiWebSocket\": true,\n    \"useResponsesApiWebSearch\": true,\n    \"messageApiWebSearchModel\": \"gpt-5-mini\"\n  }\n  ```\n- **auth.apiKeys：** 用于普通非 admin 路由的 API key。支持多个 key 轮换使用。请求可通过 `x-api-key: <key>` 或 `Authorization: Bearer <key>` 进行认证。若为空或省略，则普通路由的认证会被禁用。\n- **auth.adminApiKey：** 仅用于 `/admin/*` 路由的单个 admin key。若未配置，服务会在启动时自动生成一个随机 key，并回写到 `config.json`。它同样使用 `x-api-key` 或 `Authorization: Bearer` 这两种头，但普通 `auth.apiKeys` 不能访问 `/admin/*`。\n- **modelMappings：** 用于顶层 `POST /v1/messages`、`POST /v1/messages/count_tokens`、`POST /v1/responses` 和 `POST /v1/chat/completions` 请求的精确 `sourceModel -> targetModel` 重写映射，这几类接口共用同一份规则。省略该字段或保留为 `{}` 时，不会做模型重写。`source` 和 `target` 都必须是非空字符串。`target` 可以是普通模型 ID，也可以是 `provider/model` 形式的别名，例如 `dashscope/qwen3.6-plus`；重写发生在 provider alias 解析之前。这些映射不再按接口区分。`GET/POST /admin/config/model-mappings` 管理接口读写的也只有这个字段。\n- **extraPrompts：** `model -> prompt` 的映射。把 Anthropic 风格请求翻译为 Responses API 时，会将其附加到第一条 system prompt 后面。你可以借此为不同模型注入护栏或指引。缺失的默认项会自动补齐，但不会覆盖你自定义的 prompt。对于 GPT-5.3+ 模型（如 `gpt-5.3-codex`、`gpt-5.4`、`gpt-5.5`），未显式配置时会自动使用内置的 commentary prompt。内置 prompt 会启用带阶段感知的 commentary，让模型在工具调用或更深层推理前先发出简短的用户可见进度说明。\n- **providers：** 全局上游 provider 映射。每个 provider key（例如 `dashscope`）都会变成一个路由前缀（`/dashscope/v1/messages`）。支持 `type: \"anthropic\"`、`type: \"openai-compatible\"` 和 `type: \"openai-responses\"`。顶层客户端也可以在 `/v1/messages`、`/v1/messages/count_tokens`、`/v1/responses` 和 `/v1/chat/completions` 中使用 `model: \"dashscope/model-id\"`；AI gateway 会在转发上游前移除 `dashscope/` 前缀。`openai-compatible` provider 同时支持 chat 和 Messages 流程：`/v1/chat/completions` 会直连上游 `/v1/chat/completions`，而 `/v1/messages` 和 `/:provider/v1/messages` 会先翻译为上游 Chat Completions，再把响应翻译回 Anthropic Messages。`GET /v1/models` 会聚合已启用 provider 的模型，并以 `provider/model-id` 形式返回；单个 provider 的原始模型列表仍可使用 `GET /dashscope/v1/models`。\n  - `enabled`：可选，若省略则默认为 `true`。\n  - `baseUrl`：provider API 的基础 URL，不要带结尾的 endpoint。Anthropic provider 不要带 `/v1/messages`；OpenAI 兼容 provider 不要带 `/v1/chat/completions`；OpenAI Responses provider 不要带 `/v1/responses`。\n  - `apiKey`：作为上游凭据值使用；普通 provider 必须配置。\n  - `authType`：可选，控制 `apiKey` 如何发送到上游。普通 provider 支持 `x-api-key` 和 `authorization`。Anthropic provider 默认 `x-api-key`；OpenAI 兼容和 OpenAI Responses provider 默认 `authorization`。当设置为 `authorization` 时，代理会发送 `Authorization: Bearer <apiKey>`。`oauth2` 仅保留给内置 `codex` provider，并由 `auth login --provider codex` 自动写入。\n  - `pricingCurrency`：可选，provider 维度的 token 费用币种，例如 `USD` 或 `CNY`。快捷 provider 默认 DashScope、DeepSeek 为 `CNY`，Codex/OpenRouter 为 `USD`。费用按币种分别汇总，不做汇率换算。\n  - `models`：可选，按模型 ID 配置的映射。每个键为请求中的模型名，值支持：\n    - `temperature`：可选，当请求未指定时使用的默认温度。\n    - `topP`：可选，当请求未指定时使用的默认 `top_p`。\n    - `topK`：可选，当请求未指定时使用的默认 `top_k`。\n    - `extraBody`：可选，按模型合入上游请求体的动态字段；请求体显式同名字段优先。OpenAI 兼容 provider 可用它配置 `enable_thinking`、`preserve_thinking`、`reasoning_effort` 等字段。`thinking_budget` 是 OpenAI 兼容 provider 的特殊覆盖项：配置在 `extraBody` 后，会在 Anthropic `thinking.budget_tokens` 翻译之后强制写入，并覆盖请求派生出的预算值。对于 provider name 为 `dashscope` 或 `baseUrl` 包含 `aliyuncs.com` 的 provider，请求派生的 `thinking_budget`（来自 Anthropic `thinking.budget_tokens`）会转发给上游；其他 OpenAI 兼容 provider 会移除请求派生的 `thinking_budget`，但 `extraBody` 中的 `thinking_budget` 仍然生效。对于 DashScope provider，当 `preserve_thinking` 未在 `extraBody` 或请求体中显式设置时，默认为 `true`。\n    - `pricing`：可选，按模型配置 token 单价，币种使用 provider 的 `pricingCurrency`，单位为每 100 万 tokens。支持 `input`、`output`、`cachedInput`（隐式缓存读）、`explicitCachedInput`（显式缓存读）和 `cacheCreationInput`。如需按输入 token 总量分档，可用带 `maxInputTokens` 的 `tiers`。\n    - `contextCache`：可选，provider name 为 `dashscope` 或 `baseUrl` 包含 `aliyuncs.com` 时默认 `true`，其他 OpenAI 兼容 provider 默认 `false`。用于启用阿里云百炼/DashScope 的显式缓存（explicit context cache），会按其 Context Cache 格式在最多 4 个 content block 上注入 `cache_control: { \"type\": \"ephemeral\" }`。缓存断点策略与 opencode 主链路保持一致：前 2 条 system 消息 + 最后 2 条非 system 消息。标记字符串 content 时会把 `system` / `user` / `assistant` / `tool` 消息转换为 text content part 数组；已有数组 content 则标记最后一个 part。如果模型本身已经支持隐式缓存，或上游不支持该显式缓存扩展字段，可在模型配置中设为 `false`。支持相同显式缓存扩展的非 DashScope provider 可设为 `true`。同时适用于 `/v1/messages` 和 `/v1/chat/completions` 路由。\n    - `supportPdf`：可选，控制该模型是否支持 PDF/document content。默认 `false`，不支持时会把 PDF 转成提示文本；设为 `true` 时会把 PDF/document 转成 OpenAI Chat Completions 的 file part。\n    - `toolContentSupportType`：可选，配置该模型的 tool result content 支持能力，值为 `array`、`image`、`pdf` 的数组。provider 侧未配置时默认只发送 string tool content。若 `supportPdf` 为 `true` 但这里不包含 `pdf`，tool result 里的 file part 会被转成 user role 消息。Copilot 主链路不使用这个 provider 默认，仍按 array + image 且不支持 PDF 的能力处理。\n    - `type`：可选，按模型覆盖 provider 的协议类型。支持 `anthropic`、`openai-compatible` 和 `openai-responses`。设置后，provider 的 `/v1/messages` 路由会使用该模型的 type 替代 provider 级别的 type 进行请求路由、认证头解析和上游端点选择。适用于 OpenCode Go 等上游对不同模型同时支持 OpenAI 兼容和 Anthropic Messages API 的 provider。覆盖 type 时，认证头按覆盖后 type 的默认值解析（Anthropic 默认 `x-api-key`；OpenAI 兼容/Responses 默认 `authorization`）。\n\n  DashScope 模型配置示例：\n  ```json\n  {\n    \"providers\": {\n      \"dashscope\": {\n        \"type\": \"openai-compatible\",\n        \"enabled\": true,\n        \"baseUrl\": \"https://dashscope.aliyuncs.com/compatible-mode\",\n        \"apiKey\": \"sk-your-dashscope-key\",\n        \"pricingCurrency\": \"CNY\",\n        \"models\": {\n          \"qwen3.7-plus\": {\n            \"temperature\": 1,\n            \"topP\": 0.95,\n            \"topK\": 20,\n            \"extraBody\": {\n              \"preserve_thinking\": true\n            }\n          },\n          \"glm-5.1\": {\n            \"temperature\": 0.7,\n            \"topP\": 0.95,\n            \"contextCache\": true,\n            \"pricing\": {\n              \"tiers\": [\n                {\n                  \"maxInputTokens\": 32000,\n                  \"input\": 6,\n                  \"cachedInput\": 1.2,\n                  \"explicitCachedInput\": 0.6,\n                  \"cacheCreationInput\": 7.5,\n                  \"output\": 24\n                },\n                {\n                  \"maxInputTokens\": 200000,\n                  \"input\": 8,\n                  \"cachedInput\": 1.6,\n                  \"explicitCachedInput\": 0.8,\n                  \"cacheCreationInput\": 10,\n                  \"output\": 28\n                }\n              ]\n            },\n            \"extraBody\": {\n              \"preserve_thinking\": true\n            }\n          }\n        }\n      }\n    }\n  }\n  ```\n  内置 token 价格覆盖 Codex GPT 模型（USD）、DashScope `qwen3.7-max`、`qwen3.7-plus`、`glm-5.1`、`glm-5.2`（CNY），DeepSeek `deepseek-v4-flash`、`deepseek-v4-pro`、`deepseek-chat`、`deepseek-reasoner`（CNY），以及 OpenCode Go 模型（`glm-5.2`、`deepseek-v4-flash`、`deepseek-v4-pro`、`kimi-k2.7-code`、`mimo-v2.5`、`mimo-v2.5-pro`、`qwen3.7-plus`、`qwen3.7-max`、`minimax-m2.5`、`minimax-m3`，USD）。用户配置的 `pricing` 优先于内置价格。DashScope 若上游 usage 中出现 `cache_creation_input_tokens` 字段，cached tokens 按显式缓存读价计费；否则 `cachedInput` 作为隐式缓存读价。DeepSeek 的 `prompt_cache_hit_tokens` 会归入 cached input，`prompt_cache_miss_tokens` 会归入普通 input。\n- **smallModel：** 无工具预热消息的回退模型（例如 Claude Code 的探测请求）；默认是 `gpt-5-mini`。\n- **contextManagement：** 控制代理是否为 Responses API 附加 `context_management` 压缩指令。`messages` 作用于被翻译成 Responses API 的 Anthropic 风格 `/v1/messages` 请求，包括 `openai-responses` provider 的 Messages 路由，默认值为 `true`。`responses` 作用于 native `/v1/responses` 流量，包括 `provider/model` 别名和内置 `codex` provider，默认值为 `false`。只有在确认客户端支持 context management compaction 后，才建议在 Responses API 下启用 `responses`。启用后，请求体会带上 `context_management`，并在后续轮次中仅保留最新的压缩承载内容。**注意：** 对于 GPT-5.6 及以上模型（如 `gpt-5.6-sol`、`gpt-5.6-terra`、`gpt-5.6-luna`），context management 功能会被强制禁用，因为开启后会破坏这些模型的 prompt 缓存命中。此强制覆盖优先于 `contextManagement` 和 `modelResponsesApiCompactThresholds` 配置。\n- **modelResponsesApiCompactThresholds：** 按模型覆盖 Responses API 的 `compact_threshold`，仅在代理自动附加 `context_management` 时使用。它的优先级高于 `resolveResponsesCompactThreshold` 基于 `max_prompt_tokens * ratio` 的兜底阈值。默认将 `gpt-5.4` 和 `gpt-5.5` 设为 `217600`（`272000 * 0.8`），将 `gpt-5.6-sol`、`gpt-5.6-terra`、`gpt-5.6-luna` 设为 `231200`（`272000 * 0.85`）。未列出的模型继续使用原有兜底逻辑。\n- **modelReasoningEfforts：** `/v1/messages` 请求的模型级默认推理强度。仅当请求没有传入 `output_config.effort` 时，该配置才会生效。\n  - **优先级：** 请求中的 `output_config.effort` > `modelReasoningEfforts[model]` > 内置默认值（GPT-5.3+ 模型为 `xhigh`，其他模型为 `high`）。\n  - **转发字段：** 走 Copilot 原生 Messages API 时，最终值写入 `output_config.effort`；转换为 Responses API 时，最终值写入 `reasoning.effort`。\n  - **配置可选值：** `none`、`minimal`、`low`、`medium`、`high`、`xhigh`、`max`。\n- **useMessagesApi：** 当为 `true` 时，支持 Copilot 原生 `/v1/messages` 的 Claude 系模型会走 Messages API；否则回退到 `/chat/completions`。设为 `false` 可禁用 Messages API 路由，始终使用 `/chat/completions`。默认值为 `true`。\n- **useResponsesApiWebSocket：** 当为 `true` 时，Responses API 请求会优先对声明了 `ws:/responses` 的模型使用 Copilot websocket transport；仅声明 `/responses` 的模型仍走 HTTP。设为 `false` 可禁用 websocket 路由，并在模型支持 `/responses` 时使用 HTTP `/responses`。默认值为 `true`。\n- **useResponsesApiWebSearch：** 当为 `true` 时，服务端会保留 Responses API 中 `type: \"web_search\"` 的工具并透传到上游。设为 `false` 则会从 `/responses` payload 中移除这些工具。默认值为 `true`。\n- **messageApiWebSearchModel：** 顶层 Copilot `/v1/messages` 请求只包含服务端 `web_search` 工具时使用的全局模型，默认值为 `gpt-5-mini`。如果该值是 `provider/model` 别名，请求会进入对应 provider 的 Messages API 路径，并在转发前移除 provider 前缀。对于 Copilot GPT 模型，web search 会通过 `/responses` 执行。混合 `web_search` 与自定义工具的场景暂不支持，服务端会移除 server-side `web_search`。\n- **claudeTokenMultiplier：** 用于 Claude `/v1/messages/count_tokens` 请求在本地走 GPT tokenizer 估算时的乘数。默认值为 `1.15`。如果你的客户端仍然过晚触发上下文压缩，可以适当调大。这个配置只会在代理本地估算 Claude token 时生效；如果已经配置 `anthropicApiKey` 且 Anthropic token counting 调用成功，则会直接返回 Anthropic 的精确计数，不会使用这个乘数。\n- **anthropicApiKey：** 用于把 Claude `/v1/messages/count_tokens` 请求转发到 Anthropic 真实 token counting 端点的 API key，这样会返回精确计数，而不是 GPT tokenizer 估算值。也可通过环境变量 `ANTHROPIC_API_KEY` 设置。若未配置，或上游调用失败，则回退到由 `claudeTokenMultiplier` 控制的本地 GPT tokenizer 估算。\n\n编辑此文件后即可自定义 prompts，或替换为你自己的快速模型。修改完成后请重启服务（或重新执行命令），让缓存中的配置刷新生效。\n\n## API 认证\n\n- **受保护的普通路由：** 当配置了 `auth.apiKeys` 且非空时，除 `/`、`/usage-viewer` 和 `/usage-viewer/` 以外的普通路由都需要认证。\n- **Admin 路由：** 所有 `/admin/*` 路由都要求 `auth.adminApiKey`。如果缺失，服务会在启动时自动生成并在开始提供服务前写回 `config.json`。\n- **允许的认证头：**\n  - `x-api-key: <your_key>`\n  - `Authorization: Bearer <your_key>`\n- **CORS 预检：** `OPTIONS` 请求始终允许。\n- **未配置普通 key 时：** 普通路由仍可直接访问；但这条规则不适用于 `/admin/*`，后者只接受 `auth.adminApiKey`。\n\n普通受保护路由的示例请求：\n\n```sh\ncurl http://localhost:4141/v1/models \\\n  -H \"x-api-key: your_api_key\"\n```\n\nAdmin 路由的示例请求：\n\n```sh\ncurl http://localhost:4141/admin/config/model-mappings \\\n  -H \"x-api-key: your_admin_api_key\"\n```\n\n## API 端点\n\n服务端提供多个 OpenAI / Anthropic 兼容端点。请求会根据所选模型和 `provider/model` 别名路由到 GitHub Copilot、内置 `codex` provider 或已配置的 provider。\n\n### OpenAI 兼容端点\n\n这些端点模拟 OpenAI API 结构。\n\n| 端点 | 方法 | 说明 |\n| --- | --- | --- |\n| `POST /v1/responses` | `POST` | OpenAI 中用于生成模型响应的高级接口。支持 `openai-responses` provider 的 `provider/model` 别名。 |\n| `POST /v1/chat/completions` | `POST` | 为给定聊天对话创建模型响应。支持 `openai-compatible` provider 的 `provider/model` 别名；目标 provider 已配置时可在没有 Copilot 的情况下使用。 |\n| `GET /v1/models` | `GET` | 列出 Copilot 模型以及已启用 provider 的 `provider/model-id` 模型。来自 Codex 客户端（`User-Agent` 以 `codex` 开头）的请求会转发到 Codex Models 上游。 |\n| `POST /v1/embeddings` | `POST` | 创建表示输入文本的向量嵌入。 |\n\n### Codex 后端代理端点\n\n这些端点要求已有可用的 Codex 登录态。每个端点同时提供无版本前缀和 `/v1` 两种路径。\n\n| 端点 | 方法 | 说明 |\n| --- | --- | --- |\n| `POST /alpha/search`<br>`POST /v1/alpha/search` | `POST` | 将 JSON 请求体和查询参数透明转发到 Codex Alpha Search 上游。 |\n| `POST /images/generations`<br>`POST /v1/images/generations` | `POST` | 将 JSON 图片生成请求转发到 Codex Images 上游。请求未携带 `Content-Type` 时，网关默认补充 `application/json`。 |\n| `POST /images/edits`<br>`POST /v1/images/edits` | `POST` | 将图片编辑请求转发到 Codex Images 上游。请使用 `multipart/form-data`，并让 HTTP 客户端自动生成 `boundary`；网关会保留传入的 content type，并以流式方式转发上传请求体。 |\n\n对于以上所有端点，网关都会使用当前 Codex 登录态覆盖客户端的 authorization 和 account header，保留查询参数及兼容的请求头，并返回上游状态码、响应头和响应体。\n\n### Anthropic 兼容端点\n\n这些端点设计为兼容 Anthropic Messages API。\n\n| 端点 | 方法 | 说明 |\n| --- | --- | --- |\n| `POST /v1/messages` | `POST` | 为给定对话创建模型响应。支持已配置 provider 的 `provider/model` 别名，包括通过 `openai-compatible` provider 做翻译。 |\n| `POST /v1/messages/count_tokens` | `POST` | 计算一组消息的 token 数。支持已配置 provider 的 `provider/model` 别名。 |\n| `POST /:provider/v1/messages` | `POST` | 将 Anthropic Messages 请求代理到已配置的 Anthropic provider，或翻译到 OpenAI 兼容 / OpenAI Responses provider。 |\n| `GET /:provider/v1/models` | `GET` | 将模型列表请求代理到已配置的 provider。对 `codex` 默认返回内置模型目录；Codex 客户端（`User-Agent` 以 `codex` 开头）会转发到 Codex Models 上游。 |\n| `POST /:provider/v1/messages/count_tokens` | `POST` | 为 provider 路由请求在本地计算 token 数。 |\n| `POST /:provider/v1/responses` | `POST` | 将 OpenAI Responses 请求代理到已配置的 `openai-responses` provider（含 `codex`）。 |\n| `POST /:provider/v1/alpha/search` | `POST` | 代理 alpha-search 请求。对 `codex` 转发到 Codex Alpha Search 上游；其他 provider 转发到 `{baseUrl}/v1/alpha/search`。 |\n| `POST /:provider/v1/images/generations` | `POST` | 代理图片生成。对 `codex` 使用 Codex Images 上游；其他 provider 转发到 `{baseUrl}/v1/images/generations`（15 分钟超时）。 |\n| `POST /:provider/v1/images/edits` | `POST` | 代理图片编辑。对 `codex` 使用 Codex Images 上游；其他 provider 以 multipart/流式方式转发到 `{baseUrl}/v1/images/edits`（15 分钟超时）。 |\n\n### 使用量监控端点\n\n用于监控 Copilot 用量与额度的新端点。\n\n| 端点 | 方法 | 说明 |\n| --- | --- | --- |\n| `GET /usage` | `GET` | 获取详细的 Copilot 使用统计与额度信息。 |\n| `GET /token` | `GET` | 获取当前 API 正在使用的 Copilot token。 |\n\n### Admin / 配置端点\n\n这些端点用于本地管理操作，只接受 `auth.adminApiKey`。\n\n| 端点 | 方法 | 说明 |\n| --- | --- | --- |\n| `GET /admin/config/model-mappings` | `GET` | 返回当前 `config.json` 路径以及生效中的 `modelMappings` 映射。 |\n| `POST /admin/config/model-mappings` | `POST` | 只更新 `config.json` 里的 `modelMappings` 字段，并回传更新后的结果。 |\n\n## 使用示例\n\n常用 `npx` 命令：\n\n```sh\n# 基础启动\nnpx @jeffreycao/copilot-api@latest start\n\n# 自定义端口并开启详细日志\nnpx @jeffreycao/copilot-api@latest start --port 8080 --verbose\n\n# 执行认证流程\nnpx @jeffreycao/copilot-api@latest auth login\n\n# 配置第三方 provider，然后不依赖 GitHub Copilot 启动\nnpx @jeffreycao/copilot-api@latest auth login --provider dashscope\nnpx @jeffreycao/copilot-api@latest start\n\n# 以 JSON 格式输出调试信息\nnpx @jeffreycao/copilot-api@latest debug --json\n\n# 用 Bun 而不是 Node.js 运行已发布 CLI\nbunx --bun @jeffreycao/copilot-api@latest start\n```\n\n配置 `dashscope` 后的 OpenAI 兼容 provider 调用示例：\n\n```sh\ncurl http://localhost:4141/v1/chat/completions \\\n  -H \"content-type: application/json\" \\\n  -d '{\"model\":\"dashscope/qwen3.6-plus\",\"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]}'\n\ncurl http://localhost:4141/dashscope/v1/messages \\\n  -H \"content-type: application/json\" \\\n  -d '{\"model\":\"qwen3.6-plus\",\"max_tokens\":1024,\"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]}'\n```\n\n## 使用建议\n\n<a id=\"claudemd-or-agentsmd-recommended-content\"></a>\n\n### CLAUDE.md 或 AGENTS.md 推荐内容\n\n如果你想手动加入这些提醒，请在 Claude Code 的 `CLAUDE.md`，或 opencode/codex 的 `AGENTS.md` 中加入以下内容：\n\n```\n- Prohibited from directly asking questions to users, MUST use question tool.\n- Once you can confirm that the task is complete, MUST use question tool to make user confirm. The user may respond with feedback if they are not satisfied with the result, which you can use to make improvements and try again, after try again, MUST use question tool to make user confirm again.\n```\n"}, "c2a6d2201a264a7f9b8b544b7390fd62a9dafd03": {"t": 1785765557.1880305, "n": 32050, "h": "949e87bf7cad8a4e", "c": "# Copilot API Proxy\n\n[English](./README.md) | 简体中文\n\n## 重要说明\n\n> [!IMPORTANT]\n> **使用前请先注意以下几点：**\n>\n> 1. **Claude Code 配置：** 与 Claude Code 搭配使用时，请将模型 ID 配置为 `claude-opus-4-8`。示例 claude `settings.json` 见 [通过 `settings.json` 手动配置](#manual-configuration-with-settingsjson)。\n>\n> 2. **内置 `copilot`、`codex` 与第三方 provider：** 执行 `npx @jeffreycao/copilot-api@latest auth`，可选择 `copilot`、`codex`、`deepseek`、`custom` 等 provider。\n>\n> 3. **注意事项：** README 顶部移除的 GitHub Copilot warning 见 [GitHub Copilot 安全提示](./NOTICE.md#github-copilot-security-notice)。\n\n---\n\n## 项目概览\n\n这是一个小型 AI gateway，可以使用 GitHub Copilot、内置 `codex` provider，也可以使用 DashScope 等已配置的第三方 provider。GitHub Copilot 现在是可选能力：如果本地没有 GitHub token，只要至少配置了一个启用中的 provider，服务仍可按 provider-only 模式启动。\n\nAI gateway 会从同一个本地端点暴露 OpenAI / Anthropic 兼容 API，让 [Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview)、OpenCode、Codex 和 OpenAI 兼容客户端可以共用同一个本地服务。\n\n在 GitHub Copilot 路径上，AI gateway 会在可用时优先使用 Copilot 原生的 Anthropic 风格 Messages API，在重工具调用场景下保留更原生的 Claude 行为。\n\n## 功能特性\n\n- **OpenAI 与 Anthropic 双兼容**：通过 `/v1/responses`、`/v1/chat/completions`、`/v1/models`、`/v1/embeddings` 和 `/v1/messages` 对外暴露同一个本地 AI gateway。\n- **Copilot 可选**：有 GitHub 凭据时可以使用 GitHub Copilot，没有 GitHub 凭据时也可以只依赖已配置的 provider 运行。\n- **同一网关接入 Copilot、`codex` 与第三方 provider**：可统一路由 GitHub Copilot、内置 `codex` provider 和配置好的外部 provider。\n- **第三方 provider 可独立启动**：配置 DashScope、DeepSeek、OpenRouter 或自定义 provider 后，不需要 GitHub Copilot 登录即可启动 AI gateway。\n- **OpenAI 兼容 provider 同时支持 chat 和 Messages API**：`openai-compatible` provider 可通过顶层 `/v1/chat/completions` 搭配 `model: \"provider/model\"` 提供 Chat Completions，也可通过 `/v1/messages` 完成 Anthropic Messages 的请求/响应翻译。\n- **面向 Claude 的更原生 Copilot 路由**：优先使用原生 `/v1/messages`，保留 Claude 风格工具流，支持 Anthropic beta 能力、通过 Responses-capable 模型支持 Claude WebSearch，并保留 subagent / session 标记。\n- **Claude Code 与 OpenCode 集成**：兼容 Claude Code 与 OpenCode，也支持通过 `@ai-sdk/anthropic` 直接作为 Anthropic provider 使用。\n- **灵活的认证与部署选项**：支持交互式登录、直接 token、个人 / Business / Enterprise、GitHub Enterprise、opencode OAuth 和自定义数据目录。\n- **多 provider 路由**：可暴露 `/:provider/...` 路由，也可在顶层 API 上使用 `model: \"provider/model\"`。\n\n## 前置要求\n\n- Bun（>= 1.2.x）\n- 如果要通过 `npx` 运行已发布 CLI，需要 Node.js\n- 只有在使用 GitHub Copilot provider 时，才需要已订阅 Copilot 的 GitHub 账号\n- 如果不使用 GitHub Copilot，需要至少一个已配置 provider 的 API key 或 OAuth 登录\n\n## 安装\n\n安装依赖：\n\n```sh\nbun install\n```\n\n直接从源码启动服务：\n\n```sh\nbun run start start\n```\n\n## 从源码运行\n\n本项目可以通过多种方式从源码运行：\n\n### 开发模式\n\n```sh\nbun run dev start\n```\n\n### 生产模式\n\n```sh\nbun run start start\n```\n\n## 通过 npx 使用\n\n你可以直接用 npx 运行本项目：\n\n> [!IMPORTANT]\n> 通过 `npx` 运行时，token usage 存储会使用 Node 内置的 `node:sqlite` 模块。该能力会在 Node.js >= 22.13.0 时启用；Node.js < 22.13.0 时 CLI 仍可启动，但会禁用 token usage 存储。\n>\n> 如果不升级 Node.js 但仍需要 token usage 存储，可以改用 Bun 运行已发布 CLI：`bunx --bun @jeffreycao/copilot-api@latest start`。\n\n```sh\nnpx @jeffreycao/copilot-api@latest start\n```\n\n带参数示例：\n\n```sh\nnpx @jeffreycao/copilot-api@latest start --port 8080\n```\n\n如果只想做认证或 provider 配置：\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth\n```\n\n如果要不依赖 GitHub Copilot 运行，先配置至少一个 provider，然后正常启动服务：\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth login --provider dashscope\nnpx @jeffreycao/copilot-api@latest start\n```\n\n## 配合 Docker 使用\n\n构建镜像：\n\n```sh\ndocker build -t copilot-api .\n```\n\n通过 bind mount 运行容器，让认证数据在重启后保留：\n\n```sh\nmkdir -p ./copilot-data\ndocker run -p 4141:4141 -v $(pwd)/copilot-data:/root/.local/share/copilot-api copilot-api\n```\n\n这会把宿主机上的 `./copilot-data` 映射到容器内的 `/root/.local/share/copilot-api`，用于持久化 GitHub 认证数据、provider 配置和其他 gateway 状态。\n\n也可以直接通过环境变量传入 GitHub token：\n\n```sh\ndocker run -p 4141:4141 -e GH_TOKEN=your_github_token_here copilot-api\n```\n\n## Electron 桌面应用\n\n如果你更喜欢图形界面，仓库里还提供了位于 `desktop/` 的 Electron 桌面应用。它支持 GitHub Copilot 登录、OpenAI Codex OAuth，以及 DeepSeek、DashScope、OpenRouter 或自定义 provider 的 API Key 配置。授权或配置 provider 后，可以一键启动或停止本地代理，并在界面里直接查看本地端点、鉴权 Header、可用模型、额度和日志。\n\n设置页还可以配置 `OAuth App`、`API Home`、`Enterprise URL`、详细日志以及最小化到托盘。桌面安装包发布在 GitHub Releases：\n\nhttps://github.com/caozhiyuan/copilot-api/releases\n\n下载对应平台的安装包后，在应用内授权或配置 provider，选择端口并启动服务，再把你的客户端指向应用里显示的本地端点即可。发布版桌面应用使用随包内置的 Electron 运行时，正常使用不需要额外安装 Node.js；token usage 历史记录会在该内置运行时支持 SQLite 时启用。\n\n桌面应用里的高级配置页会通过 `GET/POST /admin/config/model-mappings` 读写这份共享的模型映射。同一份映射会统一作用于 `POST /v1/messages`、`POST /v1/messages/count_tokens`、`POST /v1/responses` 和 `POST /v1/chat/completions`，不再按接口区分。它使用的是 `auth.adminApiKey`，不是普通的 `auth.apiKeys`；应用会在服务启动并自动生成该 key 后，直接从 `config.json` 读取它来发起请求。\n\n### 桌面应用截图\n\n下面展示了桌面应用中的首页、Token 用量统计页面：\n\n<p align=\"center\">\n  <img src=\"./docs/screenshots/desktop-dashboard.png\" alt=\"Copilot API 桌面应用首页\" width=\"49%\" />\n  <img src=\"./docs/screenshots/desktop-token-usage.png\" alt=\"Copilot API 桌面应用 Token 用量页\" width=\"49%\" />\n</p>\n\n## 与 Claude Code 一起使用\n\n这个 AI gateway 可以为 [Claude Code](https://docs.anthropic.com/en/claude-code) 提供后端能力。Claude Code 是 Anthropic 提供的实验性面向开发者的对话式 AI 助手。\n\n有两种方式可以把 Claude Code 配置为使用这个 AI gateway：\n\n### 通过 `--claude-code` 标志进行交互式配置\n\n执行带 `--claude-code` 的 `start` 命令开始：\n\n```sh\nnpx @jeffreycao/copilot-api@latest start --claude-code\n```\n\n你会被提示选择一个主模型，以及一个用于后台任务的 \"small, fast\" 模型。选择完成后，会有一条命令被复制到剪贴板中。该命令会设置 Claude Code 使用这个 AI gateway 所需的环境变量。\n\n在新的终端中粘贴并执行这条命令，即可启动 Claude Code。\n\n<a id=\"manual-configuration-with-settingsjson\"></a>\n\n### 通过 `settings.json` 手动配置\n\n另一种方式是在项目根目录中创建 `.claude/settings.json` 文件，并写入 Claude Code 所需的环境变量。这样你就不需要每次都运行交互式配置了。\n\n下面是一个 `.claude/settings.json` 示例：\n\n```json\n{\n  \"env\": {\n    \"ANTHROPIC_BASE_URL\": \"http://localhost:4141\",\n    \"ANTHROPIC_AUTH_TOKEN\": \"dummy\",\n    \"ANTHROPIC_MODEL\": \"deepseek/deepseek-v4-pro\",\n    \"ANTHROPIC_DEFAULT_SONNET_MODEL\": \"deepseek/deepseek-v4-pro\",\n    \"ANTHROPIC_DEFAULT_HAIKU_MODEL\": \"deepseek/deepseek-v4-flash\",\n    \"DISABLE_NON_ESSENTIAL_MODEL_CALLS\": \"1\",\n    \"CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC\": \"1\",\n    \"CLAUDE_CODE_ATTRIBUTION_HEADER\": \"0\",\n    \"CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION\": \"false\",\n    \"CLAUDE_CODE_DISABLE_TERMINAL_TITLE\": \"true\",\n    \"CLAUDE_CODE_ENABLE_AWAY_SUMMARY\": \"0\"\n  },\n  \"permissions\": {\n    \"deny\": [\n      \"mcp__ide__executeCode\"\n    ]\n  }\n}\n```\n\n- 请根据需要替换 `ANTHROPIC_MODEL`、`ANTHROPIC_DEFAULT_OPUS_MODEL`、`ANTHROPIC_DEFAULT_SONNET_MODEL` 和 `ANTHROPIC_DEFAULT_HAIKU_MODEL`。配置完成后，请安装 claude code 插件，见 [插件集成](#plugin-integrations)。\n- 将 `CLAUDE_CODE_ATTRIBUTION_HEADER` 设为 `0` 可以阻止 Claude Code 在 system prompt 中附加计费和版本信息，从而避免 prompt cache 失效。\n- 关闭 `CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION` 和 `CLAUDE_CODE_ENABLE_AWAY_SUMMARY` 可以避免不必要地消耗额度。\n- Claude Code WebSearch 已支持纯搜索请求。Copilot 路径请保持全局 `messageApiWebSearchModel` 指向 Responses-capable GPT 模型或 `provider/model` 别名；provider 路由请使用原生 Anthropic provider 或 `openai-responses` provider。只有在你明确想禁止这类流量时，才需要把 `WebSearch` 加到 `permissions.deny`。\n- 如果使用的不是 Claude 模型，请不要启用 `ENABLE_TOOL_SEARCH`。如果使用的是 Claude 模型，则可以启用 `ENABLE_TOOL_SEARCH`。当前 Claude Code 使用的是客户端 tool search 模式，在该模式下每次加载 defer tools 都需要额外请求一次。\n- `CLAUDE_CODE_AUTO_COMPACT_WINDOW`：设置用于自动压缩计算的上下文容量（以 token 为单位）。默认使用模型自身的上下文窗口：标准模型为 200K，扩展上下文模型为 1M。使用 1M 上下文模型（如 `claude-opus-4-6[1m]`）时，可设置一个较低的值（如 `500000`）将窗口视为 500K 用于压缩计算。该值受限于模型的实际上下文窗口上限。`CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` 会基于此值的百分比生效。设置此变量可将压缩阈值与状态栏的 `used_percentage` 解耦（后者始终使用模型的完整上下文窗口）。\n\n更多选项见：[Claude Code settings](https://docs.anthropic.com/en/docs/claude-code/settings#environment-variables)\n\n也可以参考 IDE 集成说明：[Add Claude Code to your IDE](https://docs.anthropic.com/en/docs/claude-code/ide-integrations)\n\n## 与 OpenCode 一起使用\n\nOpenCode 已经有直接的 GitHub Copilot provider。本节适用于你希望让 OpenCode 通过 `@ai-sdk/anthropic` 指向这个 AI gateway，并复用本 README 前面提到的 agent 行为时。\n\n### 最小配置\n\n使用 OpenCode OAuth app 启动 AI gateway：\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth --oauth-app=opencode\nnpx @jeffreycao/copilot-api@latest start\n```\n\n然后让 OpenCode 通过 `@ai-sdk/anthropic` 指向这个 AI gateway。\n\n示例 `~/.config/opencode/opencode.json`：\n\n```json\n{\n  \"$schema\": \"https://opencode.ai/config.json\",\n  \"provider\": {\n    \"local\": {\n      \"npm\": \"@ai-sdk/anthropic\",\n      \"name\": \"My Local\",\n      \"options\": {\n        \"baseURL\": \"http://localhost:4141/v1\",\n        \"apiKey\": \"dummy\"\n      },\n      \"models\": {\n        \"gpt-5.4\": {\n          \"name\": \"gpt-5.4\",\n          \"modalities\": {\n            \"input\": [\"text\", \"image\"],\n            \"output\": [\"text\"]\n          },\n          \"limit\": {\n            \"context\": 400000,\n            \"input\": 272000,\n            \"output\": 128000\n          }\n        },\n        \"claude-sonnet-4.6\": {\n          \"id\": \"claude-sonnet-4.6\",\n          \"name\": \"claude-sonnet-4.6\",\n          \"modalities\": {\n            \"input\": [\"text\", \"image\"],\n            \"output\": [\"text\"]\n          },\n          \"limit\": {\n            \"context\": 200000,\n            \"output\": 32000\n          },\n          \"options\": {\n            \"thinking\": {\n              \"type\": \"adaptive\"\n            },\n            \"effort\": \"max\"\n          }\n        }\n      }\n    }\n  }\n}\n```\n\n这些字段的重要性：\n\n- `npm: \"@ai-sdk/anthropic\"` 是关键。OpenCode 会以 Anthropic Messages 语义与这个 AI gateway 通信，而不是把一切扁平化为 OpenAI Chat Completions。\n- `options.baseURL` 应设为 `http://localhost:4141/v1`；Anthropic SDK 会自动补上 `/messages`、`/models` 和 `/messages/count_tokens`。\n- 如果你在此代理中启用了 `auth.apiKeys`，请把 `dummy` 替换为真实 key；否则任意占位值都可以。\n\n## 与 Codex 一起使用\n\n这个 AI gateway 也可以为 Codex 提供后端能力。\n\n### Codex `config.toml` 参考配置\n\n把以下 `[model_providers.copilot_api]` 段加入你的 Codex `~/.codex/config.toml`：\n\n```toml\nmodel_provider = \"copilot_api\"\nmodel_reasoning_summary = \"auto\"\nmodel_context_window = 272000\nmodel_auto_compact_token_limit = 244800\n\n[model_providers.copilot_api]\nname = \"OpenAI\"\nbase_url = \"http://localhost:4141\"\nenv_key = \"GITHUB_COPILOT_API_KEY\"\nrequires_openai_auth = true\nsupports_websockets = false\nwire_api = \"responses\"\nrequest_max_retries = 3\nstream_max_retries = 1\nstream_idle_timeout_ms = 300000\n\n[features]\nremote_compaction_v2 = true\n\n[analytics]\nenabled = false\n```\n\n> [!NOTE]\n> 此配置仅限于 Codex 与 GitHub Copilot provider。`name` 一定要配置为 `\"OpenAI\"`。它可以缓解 Codex local compact 不命中缓存的问题。\n\n## GPT Tool Search\n\n对于 `gpt-5.4+` 这类 GPT Responses 模型，这个 AI gateway 可以通过一个很小的 MCP bridge 暴露 Responses `tool_search`。Claude Code 和 opencode 都可以使用同一个 bridge，前提是客户端会加载 MCP server，并且 Anthropic Messages 流量会经过这个 AI gateway。\n\nGPT 模型不要设置 Claude Code 原生的 `ENABLE_TOOL_SEARCH`。这个开关启用的是 Claude Code 自己的客户端 tool search 模式，可能导致 deferred 工具定义不再转发给 AI gateway。这个 AI gateway 需要完整的工具定义，这样才能只保留那一小组常驻加载工具，其余工具统一转换为 Responses deferred namespace。\n\n如果你安装了 `tool-search@copilot-api-marketplace`，Claude Code 会自动带上这个 MCP bridge，可以跳过下面这段 Claude Code MCP 手动配置。\n\n请把 tool search bridge 加到 Claude Code 使用的 MCP 配置中：\n\n```json\n{\n  \"mcpServers\": {\n    \"tool_search\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@jeffreycao/copilot-api@latest\", \"mcp\"]\n    }\n  }\n}\n```\n\n请把 tool search bridge 加到 opencode 使用的 MCP 配置中：\n\n```json\n{\n  \"mcp\": {\n    \"tool_search\": {\n      \"type\": \"local\",\n      \"command\": [\"npx\", \"-y\", \"@jeffreycao/copilot-api@latest\", \"mcp\"]\n    }\n  }\n}\n```\n\n本地开发时可以将命令换成 `bun`，参数换成 `[\"run\", \"./src/main.ts\", \"mcp\"]`。\n\nAI gateway 内部现在会把 OpenAI Responses `tool_search` 配置成 client-executed 模式。deferred tools 仍然会作为可搜索 namespace 暴露给模型，但会明确要求模型直接返回下一步要加载的精确工具名列表。\n\n该 bridge 使用直接工具选择，不做 query 搜索。工具入参是 `names`，值为逗号分隔的精确 deferred 工具名，例如 `TaskList,TaskGet,mcp__fetch__fetch`。\n\n<a id=\"plugin-integrations\"></a>\n\n## 插件集成\n\n本项目为 Claude Code 和 opencode 提供了插件集成。\n\n#### Claude Code 插件集成（基于 marketplace）\n\nClaude Code 集成现在拆分为两个插件：\n\n- `agent-inject` 会在 `SubagentStart` 时注入 `__SUBAGENT_MARKER__...`，以便 AI gateway 推导 `x-initiator: agent`。\n- `tool-search` 会注册用于 GPT Responses deferred tool loading 的 `tool_search` MCP bridge。\n\n- 本仓库中的 marketplace catalog：`.claude-plugin/marketplace.json`\n- 本仓库中的插件源码：`plugin/claude/agent-inject`、`plugin/claude/tool-search`\n\n远程添加 marketplace：\n\n```sh\n/plugin marketplace add https://github.com/caozhiyuan/copilot-api.git\n```\n\n从 marketplace 安装插件：\n\n```sh\n/plugin install agent-inject@copilot-api-marketplace\n/plugin install tool-search@copilot-api-marketplace\n```\n\n安装后，`agent-inject` 会在 `SubagentStart` 时注入 `__SUBAGENT_MARKER__...`，AI gateway 会利用它推导 `x-initiator: agent`。\n\n`agent-inject` 还会注册一个 `UserPromptSubmit` hook，并返回 `{\"continue\": true}`；同时它也可以通过环境变量注入 `SessionStart` reminder 规则：\n\n- `CLAUDE_PLUGIN_ENABLE_QUESTION_RULES=1` 会自动为 Claude Code 启用两条关于使用 `question` 工具的提醒。你也可以把同样的提醒手动写进 `CLAUDE.md`；见 [CLAUDE.md 或 AGENTS.md 推荐内容](#claudemd-or-agentsmd-recommended-content)。\n- `CLAUDE_PLUGIN_ENABLE_NO_BACKGROUND_AGENTS_RULE=1` 会启用关于避免在 agent hooks 中使用 `run_in_background: true` 的提醒。\n\n`tool-search` 插件内置了 [GPT Tool Search](#gpt-tool-search) 一节描述的同一个 MCP bridge，因此安装该插件后，Claude Code 用户无需再手动配置 `tool_search` server。\n\n#### Opencode 插件\n\nsubagent 标记生成器被打包为一个 opencode 插件，位于 `plugin/opencode/subagent-marker.js`。\n\n**安装方式：**\n\n将插件文件复制到你的 opencode 插件目录：\n\n```sh\n# 克隆或下载本仓库后复制该插件\ncp plugin/opencode/subagent-marker.js ~/.config/opencode/plugins/\n```\n\n或者手动在 `~/.config/opencode/plugins/subagent-marker.js` 创建该文件，并填入插件内容。\n\n**功能：**\n\n- 跟踪 subagent 创建的子会话\n- 自动在 subagent 聊天消息前添加 marker system reminder（`__SUBAGENT_MARKER__...`）\n- 设置 `x-session-id` 请求头以跟踪会话\n- 让这个 AI gateway 能够把来自 subagent 的请求识别为 `x-initiator: agent`\n\n该插件会挂接到 `session.created`、`session.deleted`、`chat.message` 和 `chat.headers` 事件上，以无缝提供 subagent marker 能力。\n\n## 使用量查看器\n\n服务启动后，控制台会输出一个 Copilot 使用量看板 URL。这个看板是一个用于监控 API 用量的 Web 界面。\n\n1. 启动服务。例如使用 npx：\n   ```sh\n   npx @jeffreycao/copilot-api@latest start\n   ```\n2. 服务会输出一个 usage viewer 的 URL。将它复制到浏览器中打开，形式大致如下：\n   `http://localhost:4141/usage-viewer?endpoint=http://localhost:4141/usage`\n   - 如果你在 Windows 上使用 `start.bat` 脚本，这个页面会自动打开。\n\n看板提供了更易读的 Copilot 用量视图：\n\n> token usage 历史记录需要 Bun 或 Node.js >= 22.13.0。Node.js < 22.13.0 时服务会正常运行，但 token usage 存储会被禁用。\n\n- **API Endpoint URL**：通过 URL 查询参数指定 API endpoints，默认指向本地服务。支持手动切换为其他兼容 endpoints。\n- **x-api-key 认证**：如果启用了 API Key 认证，可填入 `x-api-key` 请求头。密钥会持久化保存在浏览器本地存储中。\n- **Period 选择器**：支持 Day / Week / Month 三种时间范围，切换时 URL 参数会自动同步，方便收藏和分享。\n- **Fetch Data**：点击 \"Refresh\" 按钮加载或刷新使用数据。页面加载时也会自动拉取数据。\n- **Copilot Quotas 额度**：通过进度条展示 Chat、Completions 等不同服务的额度使用情况，悬停可查看已用/剩余详情。\n- **Token Usage 指标卡片**：汇总当前周期的 Total、Input、Output、Cache Read、Cache Write、Requests 和预估费用。\n- **趋势图（Week / Month）**：提供按模型和指标筛选的折线趋势图，点击数据点可查看单日用量明细。\n- **Model Breakdown 表格**：按模型维度列出周期内的请求数、输入/输出/缓存 token 和预计费用。\n- **Request Events 分页列表**：按时间排序的请求事件记录，支持分页浏览，含时间戳、模型、请求 ID 和 token 用量。\n- **Detailed Information**：展示 API 返回的完整 JSON 响应，便于深入分析所有可用统计数据。\n- **URL-based Configuration**：也可通过 `endpoint` 和 `period` 查询参数直接指定 API 端点与时间范围。例如：\n  `http://localhost:4141/usage-viewer?endpoint=http://your-api-server/usage&period=week`\n\n### Usage Viewer 截图\n\n<p align=\"center\">\n  <img src=\"./docs/screenshots/usage-viewer.png\" alt=\"Copilot API Usage Viewer 页面\" width=\"900\" />\n</p>\n\n## 命令结构\n\nCopilot API 现在使用子命令结构，主要命令包括：\n\n- `start`：启动 AI gateway 服务。如果已有 GitHub token，则启用 Copilot 路径；如果没有 GitHub token，但存在至少一个启用中的 provider，则按 provider-only 模式启动；如果两者都没有，会引导你配置 provider。\n- `auth`：仅执行 provider 登录或配置流程，不启动服务。可用于 GitHub Copilot 登录、Codex OAuth，或第三方 provider API key 配置。\n- `debug`：显示诊断信息，包括版本、运行时详情、文件路径以及认证状态，便于排障与支持。\n\n## 命令行选项\n\n### 全局选项\n\n以下选项可用于任意子命令。若在子命令之前传入，请使用 `--key=value` 形式：\n\n| 选项 | 说明 | 默认值 | 别名 |\n| --- | --- | --- | --- |\n| --api-home | API home 目录路径（设置 `COPILOT_API_HOME`） | 无 | 无 |\n| --oauth-app | OAuth app 标识符（设置 `COPILOT_API_OAUTH_APP`） | 无 | 无 |\n| --enterprise-url | GitHub Enterprise URL（设置 `COPILOT_API_ENTERPRISE_URL`） | 无 | 无 |\n\n### Start 命令选项\n\n以下是 `start` 命令可用的命令行选项：\n\n| 选项 | 说明 | 默认值 | 别名 |\n| --- | --- | --- | --- |\n| --port | 监听端口 | 4141 | -p |\n| --verbose | 启用详细日志 | false | -v |\n| --github-token | 直接提供 GitHub token（必须通过 `auth` 子命令生成） | 无 | -g |\n| --claude-code | 生成一个使用 Copilot API 配置启动 Claude Code 的命令 | false | -c |\n| --show-token | 在获取和刷新时显示 GitHub 与 Copilot token | false | 无 |\n| --proxy-env | 从环境变量初始化代理 | false | 无 |\n\n### Auth 命令选项\n\n| 选项 | 说明 | 默认值 | 别名 |\n| --- | --- | --- | --- |\n| --provider | 要登录或配置的 provider（`copilot`、`codex`、`opencode-go`、`deepseek`、`dashscope`、`openrouter` 或 `custom`） | 交互选择 | 无 |\n| --verbose | 启用详细日志 | false | -v |\n| --show-token | 认证时显示 GitHub token | false | 无 |\n\n只有在需要启用 GitHub Copilot provider 时，才需要执行 `copilot-api auth login --provider copilot`。使用 `codex` 或第三方 provider-only 模式不要求配置 Copilot。\n\n使用 `copilot-api auth login --provider deepseek`、`--provider dashscope`、`--provider openrouter` 或 `--provider opencode-go` 可以通过 CLI 快速新增或更新这些常用第三方 provider。DeepSeek 会提示输入掩码显示的 `apiKey`、provider `type`（默认 `anthropic`），以及默认 `https://api.deepseek.com/anthropic` 的 `baseUrl`。DashScope 会提示输入掩码显示的 `apiKey`、provider `type`（默认 `openai-compatible`）和预填默认值的 `baseUrl`。OpenRouter 只提示输入掩码显示的 `apiKey` 和预填默认值的 `baseUrl`，并固定写入 `type: \"anthropic\"`。OpenCode Go 只提示输入掩码显示的 `apiKey` 和预填默认值的 `baseUrl`，并固定写入 `type: \"openai-compatible\"`（baseUrl `https://opencode.ai/zen/go`）。配置并启用 provider 后，`copilot-api start` 可在没有 GitHub token 的情况下启动。\n\n使用 `copilot-api auth login --provider custom` 可以通过 CLI 新增或更新其他第三方 provider。命令会依次提示输入 provider name、项目支持的 type（`anthropic`、`openai-compatible` 或 `openai-responses`）、`baseUrl`、掩码显示的 `apiKey` 和 `authType`；`authType` 可保持 type 默认值，也可选择 `x-api-key` / `authorization`。\n\n### Debug 命令选项\n\n| 选项 | 说明 | 默认值 | 别名 |\n| --- | --- | --- | --- |\n| --json | 以 JSON 输出调试信息 | false | 无 |\n\n<a id=\"configuration-configjson\"></a>\n\n## 配置（config.json）\n\n- **位置：** Linux/macOS 为 `~/.local/share/copilot-api/config.json`，Windows 为 `%USERPROFILE%\\.local\\share\\copilot-api\\config.json`。\n- **默认结构：**\n  ```json\n  {\n    \"auth\": {\n      \"apiKeys\": [],\n      \"adminApiKey\": \"<startup 自动生成>\"\n    },\n    \"providers\": {},\n    \"modelMappings\": {},\n    \"extraPrompts\": {\n      \"gpt-5-mini\": \"<built-in exploration prompt>\"\n    },\n    \"smallModel\": \"gpt-5-mini\",\n    \"contextManagement\": {\n      \"messages\": true,\n      \"responses\": false\n    },\n    \"modelResponsesApiCompactThresholds\": {\n      \"gpt-5.4\": 217600,\n      \"gpt-5.5\": 217600,\n      \"gpt-5.6-sol\": 231200,\n      \"gpt-5.6-terra\": 231200,\n      \"gpt-5.6-luna\": 231200\n    },\n    \"modelReasoningEfforts\": {\n      \"gpt-5-mini\": \"low\"\n    },\n    \"useMessagesApi\": true,\n    \"useResponsesApiWebSocket\": true,\n    \"useResponsesApiWebSearch\": true,\n    \"messageApiWebSearchModel\": \"gpt-5-mini\"\n  }\n  ```\n- **auth.apiKeys：** 用于普通非 admin 路由的 API key。支持多个 key 轮换使用。请求可通过 `x-api-key: <key>` 或 `Authorization: Bearer <key>` 进行认证。若为空或省略，则普通路由的认证会被禁用。\n- **auth.adminApiKey：** 仅用于 `/admin/*` 路由的单个 admin key。若未配置，服务会在启动时自动生成一个随机 key，并回写到 `config.json`。它同样使用 `x-api-key` 或 `Authorization: Bearer` 这两种头，但普通 `auth.apiKeys` 不能访问 `/admin/*`。\n- **modelMappings：** 用于顶层 `POST /v1/messages`、`POST /v1/messages/count_tokens`、`POST /v1/responses` 和 `POST /v1/chat/completions` 请求的精确 `sourceModel -> targetModel` 重写映射，这几类接口共用同一份规则。省略该字段或保留为 `{}` 时，不会做模型重写。`source` 和 `target` 都必须是非空字符串。`target` 可以是普通模型 ID，也可以是 `provider/model` 形式的别名，例如 `dashscope/qwen3.6-plus`；重写发生在 provider alias 解析之前。这些映射不再按接口区分。`GET/POST /admin/config/model-mappings` 管理接口读写的也只有这个字段。\n- **extraPrompts：** `model -> prompt` 的映射。把 Anthropic 风格请求翻译为 Responses API 时，会将其附加到第一条 system prompt 后面。你可以借此为不同模型注入护栏或指引。缺失的默认项会自动补齐，但不会覆盖你自定义的 prompt。对于 GPT-5.3+ 模型（如 `gpt-5.3-codex`、`gpt-5.4`、`gpt-5.5`），未显式配置时会自动使用内置的 commentary prompt。内置 prompt 会启用带阶段感知的 commentary，让模型在工具调用或更深层推理前先发出简短的用户可见进度说明。\n- **providers：** 全局上游 provider 映射。每个 provider key（例如 `dashscope`）都会变成一个路由前缀（`/dashscope/v1/messages`）。支持 `type: \"anthropic\"`、`type: \"openai-compatible\"` 和 `type: \"openai-responses\"`。顶层客户端也可以在 `/v1/messages`、`/v1/messages/count_tokens`、`/v1/responses` 和 `/v1/chat/completions` 中使用 `model: \"dashscope/model-id\"`；AI gateway 会在转发上游前移除 `dashscope/` 前缀。`openai-compatible` provider 同时支持 chat 和 Messages 流程：`/v1/chat/completions` 会直连上游 `/v1/chat/completions`，而 `/v1/messages` 和 `/:provider/v1/messages` 会先翻译为上游 Chat Completions，再把响应翻译回 Anthropic Messages。`GET /v1/models` 会聚合已启用 provider 的模型，并以 `provider/model-id` 形式返回；单个 provider 的原始模型列表仍可使用 `GET /dashscope/v1/models`。\n  - `enabled`：可选，若省略则默认为 `true`。\n  - `baseUrl`：provider API 的基础 URL，不要带结尾的 endpoint。Anthropic provider 不要带 `/v1/messages`；OpenAI 兼容 provider 不要带 `/v1/chat/completions`；OpenAI Responses provider 不要带 `/v1/responses`。\n  - `apiKey`：作为上游凭据值使用；普通 provider 必须配置。\n  - `authType`：可选，控制 `apiKey` 如何发送到上游。普通 provider 支持 `x-api-key` 和 `authorization`。Anthropic provider 默认 `x-api-key`；OpenAI 兼容和 OpenAI Responses provider 默认 `authorization`。当设置为 `authorization` 时，代理会发送 `Authorization: Bearer <apiKey>`。`oauth2` 仅保留给内置 `codex` provider，并由 `auth login --provider codex` 自动写入。\n  - `pricingCurrency`：可选，provider 维度的 token 费用币种，例如 `USD` 或 `CNY`。快捷 provider 默认 DashScope、DeepSeek 为 `CNY`，Codex/OpenRouter 为 `USD`。费用按币种分别汇总，不做汇率换算。\n  - `models`：可选，按模型 ID 配置的映射。每个键为请求中的模型名，值支持：\n    - `temperature`：可选，当请求未指定时使用的默认温度。\n    - `topP`：可选，当请求未指定时使用的默认 `top_p`。\n    - `topK`：可选，当请求未指定时使用的默认 `top_k`。\n    - `extraBody`：可选，按模型合入上游请求体的动态字段；请求体显式同名字段优先。OpenAI 兼容 provider 可用它配置 `enable_thinking`、`preserve_thinking`、`reasoning_effort` 等字段。`thinking_budget` 是 OpenAI 兼容 provider 的特殊覆盖项：配置在 `extraBody` 后，会在 Anthropic `thinking.budget_tokens` 翻译之后强制写入，并覆盖请求派生出的预算值。对于 provider name 为 `dashscope` 或 `baseUrl` 包含 `aliyuncs.com` 的 provider，请求派生的 `thinking_budget`（来自 Anthropic `thinking.budget_tokens`）会转发给上游；其他 OpenAI 兼容 provider 会移除请求派生的 `thinking_budget`，但 `extraBody` 中的 `thinking_budget` 仍然生效。对于 DashScope provider，当 `preserve_thinking` 未在 `extraBody` 或请求体中显式设置时，默认为 `true`。\n    - `pricing`：可选，按模型配置 token 单价，币种使用 provider 的 `pricingCurrency`，单位为每 100 万 tokens。支持 `input`、`output`、`cachedInput`（隐式缓存读）、`explicitCachedInput`（显式缓存读）和 `cacheCreationInput`。如需按输入 token 总量分档，可用带 `maxInputTokens` 的 `tiers`。\n    - `contextCache`：可选，provider name 为 `dashscope` 或 `baseUrl` 包含 `aliyuncs.com` 时默认 `true`，其他 OpenAI 兼容 provider 默认 `false`。用于启用阿里云百炼/DashScope 的显式缓存（explicit context cache），会按其 Context Cache 格式在最多 4 个 content block 上注入 `cache_control: { \"type\": \"ephemeral\" }`。缓存断点策略与 opencode 主链路保持一致：前 2 条 system 消息 + 最后 2 条非 system 消息。标记字符串 content 时会把 `system` / `user` / `assistant` / `tool` 消息转换为 text content part 数组；已有数组 content 则标记最后一个 part。如果模型本身已经支持隐式缓存，或上游不支持该显式缓存扩展字段，可在模型配置中设为 `false`。支持相同显式缓存扩展的非 DashScope provider 可设为 `true`。同时适用于 `/v1/messages` 和 `/v1/chat/completions` 路由。\n    - `supportPdf`：可选，控制该模型是否支持 PDF/document content。默认 `false`，不支持时会把 PDF 转成提示文本；设为 `true` 时会把 PDF/document 转成 OpenAI Chat Completions 的 file part。\n    - `toolContentSupportType`：可选，配置该模型的 tool result content 支持能力，值为 `array`、`image`、`pdf` 的数组。provider 侧未配置时默认只发送 string tool content。若 `supportPdf` 为 `true` 但这里不包含 `pdf`，tool result 里的 file part 会被转成 user role 消息。Copilot 主链路不使用这个 provider 默认，仍按 array + image 且不支持 PDF 的能力处理。\n    - `type`：可选，按模型覆盖 provider 的协议类型。支持 `anthropic`、`openai-compatible` 和 `openai-responses`。设置后，provider 的 `/v1/messages` 路由会使用该模型的 type 替代 provider 级别的 type 进行请求路由、认证头解析和上游端点选择。适用于 OpenCode Go 等上游对不同模型同时支持 OpenAI 兼容和 Anthropic Messages API 的 provider。覆盖 type 时，认证头按覆盖后 type 的默认值解析（Anthropic 默认 `x-api-key`；OpenAI 兼容/Responses 默认 `authorization`）。\n\n  DashScope 模型配置示例：\n  ```json\n  {\n    \"providers\": {\n      \"dashscope\": {\n        \"type\": \"openai-compatible\",\n        \"enabled\": true,\n        \"baseUrl\": \"https://dashscope.aliyuncs.com/compatible-mode\",\n        \"apiKey\": \"sk-your-dashscope-key\",\n        \"pricingCurrency\": \"CNY\",\n        \"models\": {\n          \"qwen3.7-plus\": {\n            \"temperature\": 1,\n            \"topP\": 0.95,\n            \"topK\": 20,\n            \"extraBody\": {\n              \"preserve_thinking\": true\n            }\n          },\n          \"glm-5.1\": {\n            \"temperature\": 0.7,\n            \"topP\": 0.95,\n            \"contextCache\": true,\n            \"pricing\": {\n              \"tiers\": [\n                {\n                  \"maxInputTokens\": 32000,\n                  \"input\": 6,\n                  \"cachedInput\": 1.2,\n                  \"explicitCachedInput\": 0.6,\n                  \"cacheCreationInput\": 7.5,\n                  \"output\": 24\n                },\n                {\n                  \"maxInputTokens\": 200000,\n                  \"input\": 8,\n                  \"cachedInput\": 1.6,\n                  \"explicitCachedInput\": 0.8,\n                  \"cacheCreationInput\": 10,\n                  \"output\": 28\n                }\n              ]\n            },\n            \"extraBody\": {\n              \"preserve_thinking\": true\n            }\n          }\n        }\n      }\n    }\n  }\n  ```\n  内置 token 价格覆盖 Codex GPT 模型（USD）、DashScope `qwen3.7-max`、`qwen3.7-plus`、`glm-5.1`、`glm-5.2`（CNY），DeepSeek `deepseek-v4-flash`、`deepseek-v4-pro`、`deepseek-chat`、`deepseek-reasoner`（CNY），以及 OpenCode Go 模型（`glm-5.2`、`deepseek-v4-flash`、`deepseek-v4-pro`、`kimi-k2.7-code`、`mimo-v2.5`、`mimo-v2.5-pro`、`qwen3.7-plus`、`qwen3.7-max`、`minimax-m2.5`、`minimax-m3`，USD）。用户配置的 `pricing` 优先于内置价格。DashScope 若上游 usage 中出现 `cache_creation_input_tokens` 字段，cached tokens 按显式缓存读价计费；否则 `cachedInput` 作为隐式缓存读价。DeepSeek 的 `prompt_cache_hit_tokens` 会归入 cached input，`prompt_cache_miss_tokens` 会归入普通 input。\n- **smallModel：** 无工具预热消息的回退模型（例如 Claude Code 的探测请求）；默认是 `gpt-5-mini`。\n- **contextManagement：** 控制代理是否为 Responses API 附加 `context_management` 压缩指令。`messages` 作用于被翻译成 Responses API 的 Anthropic 风格 `/v1/messages` 请求，包括 `openai-responses` provider 的 Messages 路由，默认值为 `true`。`responses` 作用于 native `/v1/responses` 流量，包括 `provider/model` 别名和内置 `codex` provider，默认值为 `false`。只有在确认客户端支持 context management compaction 后，才建议在 Responses API 下启用 `responses`。启用后，请求体会带上 `context_management`，并在后续轮次中仅保留最新的压缩承载内容。**注意：** 对于 GPT-5.6 及以上模型（如 `gpt-5.6-sol`、`gpt-5.6-terra`、`gpt-5.6-luna`），context management 功能会被强制禁用，因为开启后会破坏这些模型的 prompt 缓存命中。此强制覆盖优先于 `contextManagement` 和 `modelResponsesApiCompactThresholds` 配置。\n- **modelResponsesApiCompactThresholds：** 按模型覆盖 Responses API 的 `compact_threshold`，仅在代理自动附加 `context_management` 时使用。它的优先级高于 `resolveResponsesCompactThreshold` 基于 `max_prompt_tokens * ratio` 的兜底阈值。默认将 `gpt-5.4` 和 `gpt-5.5` 设为 `217600`（`272000 * 0.8`），将 `gpt-5.6-sol`、`gpt-5.6-terra`、`gpt-5.6-luna` 设为 `231200`（`272000 * 0.85`）。未列出的模型继续使用原有兜底逻辑。\n- **modelReasoningEfforts：** `/v1/messages` 请求的模型级默认推理强度。仅当请求没有传入 `output_config.effort` 时，该配置才会生效。\n  - **优先级：** 请求中的 `output_config.effort` > `modelReasoningEfforts[model]` > 内置默认值（GPT-5.3+ 模型为 `xhigh`，其他模型为 `high`）。\n  - **转发字段：** 走 Copilot 原生 Messages API 时，最终值写入 `output_config.effort`；转换为 Responses API 时，最终值写入 `reasoning.effort`。\n  - **配置可选值：** `none`、`minimal`、`low`、`medium`、`high`、`xhigh`、`max`。\n- **useMessagesApi：** 当为 `true` 时，支持 Copilot 原生 `/v1/messages` 的 Claude 系模型会走 Messages API；否则回退到 `/chat/completions`。设为 `false` 可禁用 Messages API 路由，始终使用 `/chat/completions`。默认值为 `true`。\n- **useResponsesApiWebSocket：** 当为 `true` 时，Responses API 请求会优先对声明了 `ws:/responses` 的模型使用 Copilot websocket transport；仅声明 `/responses` 的模型仍走 HTTP。设为 `false` 可禁用 websocket 路由，并在模型支持 `/responses` 时使用 HTTP `/responses`。默认值为 `true`。\n- **useResponsesApiWebSearch：** 当为 `true` 时，服务端会保留 Responses API 中 `type: \"web_search\"` 的工具并透传到上游。设为 `false` 则会从 `/responses` payload 中移除这些工具。默认值为 `true`。\n- **messageApiWebSearchModel：** 顶层 Copilot `/v1/messages` 请求只包含服务端 `web_search` 工具时使用的全局模型，默认值为 `gpt-5-mini`。如果该值是 `provider/model` 别名，请求会进入对应 provider 的 Messages API 路径，并在转发前移除 provider 前缀。对于 Copilot GPT 模型，web search 会通过 `/responses` 执行。混合 `web_search` 与自定义工具的场景暂不支持，服务端会移除 server-side `web_search`。\n- **claudeTokenMultiplier：** 用于 Claude `/v1/messages/count_tokens` 请求在本地走 GPT tokenizer 估算时的乘数。默认值为 `1.15`。如果你的客户端仍然过晚触发上下文压缩，可以适当调大。这个配置只会在代理本地估算 Claude token 时生效；如果已经配置 `anthropicApiKey` 且 Anthropic token counting 调用成功，则会直接返回 Anthropic 的精确计数，不会使用这个乘数。\n- **anthropicApiKey：** 用于把 Claude `/v1/messages/count_tokens` 请求转发到 Anthropic 真实 token counting 端点的 API key，这样会返回精确计数，而不是 GPT tokenizer 估算值。也可通过环境变量 `ANTHROPIC_API_KEY` 设置。若未配置，或上游调用失败，则回退到由 `claudeTokenMultiplier` 控制的本地 GPT tokenizer 估算。\n\n编辑此文件后即可自定义 prompts，或替换为你自己的快速模型。修改完成后请重启服务（或重新执行命令），让缓存中的配置刷新生效。\n\n## API 认证\n\n- **受保护的普通路由：** 当配置了 `auth.apiKeys` 且非空时，除 `/`、`/usage-viewer` 和 `/usage-viewer/` 以外的普通路由都需要认证。\n- **Admin 路由：** 所有 `/admin/*` 路由都要求 `auth.adminApiKey`。如果缺失，服务会在启动时自动生成并在开始提供服务前写回 `config.json`。\n- **允许的认证头：**\n  - `x-api-key: <your_key>`\n  - `Authorization: Bearer <your_key>`\n- **CORS 预检：** `OPTIONS` 请求始终允许。\n- **未配置普通 key 时：** 普通路由仍可直接访问；但这条规则不适用于 `/admin/*`，后者只接受 `auth.adminApiKey`。\n\n普通受保护路由的示例请求：\n\n```sh\ncurl http://localhost:4141/v1/models \\\n  -H \"x-api-key: your_api_key\"\n```\n\nAdmin 路由的示例请求：\n\n```sh\ncurl http://localhost:4141/admin/config/model-mappings \\\n  -H \"x-api-key: your_admin_api_key\"\n```\n\n## API 端点\n\n服务端提供多个 OpenAI / Anthropic 兼容端点。请求会根据所选模型和 `provider/model` 别名路由到 GitHub Copilot、内置 `codex` provider 或已配置的 provider。\n\n### OpenAI 兼容端点\n\n这些端点模拟 OpenAI API 结构。\n\n| 端点 | 方法 | 说明 |\n| --- | --- | --- |\n| `POST /v1/responses` | `POST` | OpenAI 中用于生成模型响应的高级接口。支持 `openai-responses` provider 的 `provider/model` 别名。 |\n| `POST /v1/chat/completions` | `POST` | 为给定聊天对话创建模型响应。支持 `openai-compatible` provider 的 `provider/model` 别名；目标 provider 已配置时可在没有 Copilot 的情况下使用。 |\n| `GET /v1/models` | `GET` | 列出 Copilot 模型以及已启用 provider 的 `provider/model-id` 模型。来自 Codex 客户端（`User-Agent` 以 `codex` 开头）的请求会转发到 Codex Models 上游。 |\n| `POST /v1/embeddings` | `POST` | 创建表示输入文本的向量嵌入。 |\n\n### Codex 后端代理端点\n\n这些端点要求已有可用的 Codex 登录态。每个端点同时提供无版本前缀和 `/v1` 两种路径。\n\n| 端点 | 方法 | 说明 |\n| --- | --- | --- |\n| `POST /alpha/search`<br>`POST /v1/alpha/search` | `POST` | 将 JSON 请求体和查询参数透明转发到 Codex Alpha Search 上游。 |\n| `POST /images/generations`<br>`POST /v1/images/generations` | `POST` | 将 JSON 图片生成请求转发到 Codex Images 上游。请求未携带 `Content-Type` 时，网关默认补充 `application/json`。 |\n| `POST /images/edits`<br>`POST /v1/images/edits` | `POST` | 将图片编辑请求转发到 Codex Images 上游。请使用 `multipart/form-data`，并让 HTTP 客户端自动生成 `boundary`；网关会保留传入的 content type，并以流式方式转发上传请求体。 |\n\n对于以上所有端点，网关都会使用当前 Codex 登录态覆盖客户端的 authorization 和 account header，保留查询参数及兼容的请求头，并返回上游状态码、响应头和响应体。\n\n### Anthropic 兼容端点\n\n这些端点设计为兼容 Anthropic Messages API。\n\n| 端点 | 方法 | 说明 |\n| --- | --- | --- |\n| `POST /v1/messages` | `POST` | 为给定对话创建模型响应。支持已配置 provider 的 `provider/model` 别名，包括通过 `openai-compatible` provider 做翻译。 |\n| `POST /v1/messages/count_tokens` | `POST` | 计算一组消息的 token 数。支持已配置 provider 的 `provider/model` 别名。 |\n| `POST /:provider/v1/messages` | `POST` | 将 Anthropic Messages 请求代理到已配置的 Anthropic provider，或翻译到 OpenAI 兼容 / OpenAI Responses provider。 |\n| `GET /:provider/v1/models` | `GET` | 将模型列表请求代理到已配置的 provider。 |\n| `POST /:provider/v1/messages/count_tokens` | `POST` | 为 provider 路由请求在本地计算 token 数。 |\n\n### 使用量监控端点\n\n用于监控 Copilot 用量与额度的新端点。\n\n| 端点 | 方法 | 说明 |\n| --- | --- | --- |\n| `GET /usage` | `GET` | 获取详细的 Copilot 使用统计与额度信息。 |\n| `GET /token` | `GET` | 获取当前 API 正在使用的 Copilot token。 |\n\n### Admin / 配置端点\n\n这些端点用于本地管理操作，只接受 `auth.adminApiKey`。\n\n| 端点 | 方法 | 说明 |\n| --- | --- | --- |\n| `GET /admin/config/model-mappings` | `GET` | 返回当前 `config.json` 路径以及生效中的 `modelMappings` 映射。 |\n| `POST /admin/config/model-mappings` | `POST` | 只更新 `config.json` 里的 `modelMappings` 字段，并回传更新后的结果。 |\n\n## 使用示例\n\n常用 `npx` 命令：\n\n```sh\n# 基础启动\nnpx @jeffreycao/copilot-api@latest start\n\n# 自定义端口并开启详细日志\nnpx @jeffreycao/copilot-api@latest start --port 8080 --verbose\n\n# 执行认证流程\nnpx @jeffreycao/copilot-api@latest auth login\n\n# 配置第三方 provider，然后不依赖 GitHub Copilot 启动\nnpx @jeffreycao/copilot-api@latest auth login --provider dashscope\nnpx @jeffreycao/copilot-api@latest start\n\n# 以 JSON 格式输出调试信息\nnpx @jeffreycao/copilot-api@latest debug --json\n\n# 用 Bun 而不是 Node.js 运行已发布 CLI\nbunx --bun @jeffreycao/copilot-api@latest start\n```\n\n配置 `dashscope` 后的 OpenAI 兼容 provider 调用示例：\n\n```sh\ncurl http://localhost:4141/v1/chat/completions \\\n  -H \"content-type: application/json\" \\\n  -d '{\"model\":\"dashscope/qwen3.6-plus\",\"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]}'\n\ncurl http://localhost:4141/dashscope/v1/messages \\\n  -H \"content-type: application/json\" \\\n  -d '{\"model\":\"qwen3.6-plus\",\"max_tokens\":1024,\"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]}'\n```\n\n## 使用建议\n\n<a id=\"claudemd-or-agentsmd-recommended-content\"></a>\n\n### CLAUDE.md 或 AGENTS.md 推荐内容\n\n如果你想手动加入这些提醒，请在 Claude Code 的 `CLAUDE.md`，或 opencode/codex 的 `AGENTS.md` 中加入以下内容：\n\n```\n- Prohibited from directly asking questions to users, MUST use question tool.\n- Once you can confirm that the task is complete, MUST use question tool to make user confirm. The user may respond with feedback if they are not satisfied with the result, which you can use to make improvements and try again, after try again, MUST use question tool to make user confirm again.\n```\n"}, "c6f762a44b8b8eefe09eff16586cfc6706f5eb14": {"t": 1785765559.925609, "n": 31684, "h": "807e19f1cdf1353e", "c": "# Copilot API Proxy\n\n[English](./README.md) | 简体中文\n\n## 重要说明\n\n> [!IMPORTANT]\n> **使用前请先注意以下几点：**\n>\n> 1. **Claude Code 配置：** 与 Claude Code 搭配使用时，请将模型 ID 配置为 `claude-opus-4-8`。示例 claude `settings.json` 见 [通过 `settings.json` 手动配置](#manual-configuration-with-settingsjson)。\n>\n> 2. **内置 `copilot`、`codex` 与第三方 provider：** 执行 `npx @jeffreycao/copilot-api@latest auth`，可选择 `copilot`、`codex`、`deepseek`、`custom` 等 provider。\n>\n> 3. **注意事项：** README 顶部移除的 GitHub Copilot warning 见 [GitHub Copilot 安全提示](./NOTICE.md#github-copilot-security-notice)。\n\n---\n\n## 项目概览\n\n这是一个小型 AI gateway，可以使用 GitHub Copilot、内置 `codex` provider，也可以使用 DashScope 等已配置的第三方 provider。GitHub Copilot 现在是可选能力：如果本地没有 GitHub token，只要至少配置了一个启用中的 provider，服务仍可按 provider-only 模式启动。\n\nAI gateway 会从同一个本地端点暴露 OpenAI / Anthropic 兼容 API，让 [Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview)、OpenCode、Codex 和 OpenAI 兼容客户端可以共用同一个本地服务。\n\n在 GitHub Copilot 路径上，AI gateway 会在可用时优先使用 Copilot 原生的 Anthropic 风格 Messages API，在重工具调用场景下保留更原生的 Claude 行为。\n\n## 功能特性\n\n- **OpenAI 与 Anthropic 双兼容**：通过 `/v1/responses`、`/v1/chat/completions`、`/v1/models`、`/v1/embeddings` 和 `/v1/messages` 对外暴露同一个本地 AI gateway。\n- **Copilot 可选**：有 GitHub 凭据时可以使用 GitHub Copilot，没有 GitHub 凭据时也可以只依赖已配置的 provider 运行。\n- **同一网关接入 Copilot、`codex` 与第三方 provider**：可统一路由 GitHub Copilot、内置 `codex` provider 和配置好的外部 provider。\n- **第三方 provider 可独立启动**：配置 DashScope、DeepSeek、OpenRouter 或自定义 provider 后，不需要 GitHub Copilot 登录即可启动 AI gateway。\n- **OpenAI 兼容 provider 同时支持 chat 和 Messages API**：`openai-compatible` provider 可通过顶层 `/v1/chat/completions` 搭配 `model: \"provider/model\"` 提供 Chat Completions，也可通过 `/v1/messages` 完成 Anthropic Messages 的请求/响应翻译。\n- **面向 Claude 的更原生 Copilot 路由**：优先使用原生 `/v1/messages`，保留 Claude 风格工具流，支持 Anthropic beta 能力、通过 Responses-capable 模型支持 Claude WebSearch，并保留 subagent / session 标记。\n- **Claude Code 与 OpenCode 集成**：兼容 Claude Code 与 OpenCode，也支持通过 `@ai-sdk/anthropic` 直接作为 Anthropic provider 使用。\n- **灵活的认证与部署选项**：支持交互式登录、直接 token、个人 / Business / Enterprise、GitHub Enterprise、opencode OAuth 和自定义数据目录。\n- **多 provider 路由**：可暴露 `/:provider/...` 路由，也可在顶层 API 上使用 `model: \"provider/model\"`。\n\n## 前置要求\n\n- Bun（>= 1.2.x）\n- 如果要通过 `npx` 运行已发布 CLI，需要 Node.js\n- 只有在使用 GitHub Copilot provider 时，才需要已订阅 Copilot 的 GitHub 账号\n- 如果不使用 GitHub Copilot，需要至少一个已配置 provider 的 API key 或 OAuth 登录\n\n## 安装\n\n安装依赖：\n\n```sh\nbun install\n```\n\n直接从源码启动服务：\n\n```sh\nbun run start start\n```\n\n## 从源码运行\n\n本项目可以通过多种方式从源码运行：\n\n### 开发模式\n\n```sh\nbun run dev start\n```\n\n### 生产模式\n\n```sh\nbun run start start\n```\n\n## 通过 npx 使用\n\n你可以直接用 npx 运行本项目：\n\n> [!IMPORTANT]\n> 通过 `npx` 运行时，token usage 存储会使用 Node 内置的 `node:sqlite` 模块。该能力会在 Node.js >= 22.13.0 时启用；Node.js < 22.13.0 时 CLI 仍可启动，但会禁用 token usage 存储。\n>\n> 如果不升级 Node.js 但仍需要 token usage 存储，可以改用 Bun 运行已发布 CLI：`bunx --bun @jeffreycao/copilot-api@latest start`。\n\n```sh\nnpx @jeffreycao/copilot-api@latest start\n```\n\n带参数示例：\n\n```sh\nnpx @jeffreycao/copilot-api@latest start --port 8080\n```\n\n如果只想做认证或 provider 配置：\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth\n```\n\n如果要不依赖 GitHub Copilot 运行，先配置至少一个 provider，然后正常启动服务：\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth login --provider dashscope\nnpx @jeffreycao/copilot-api@latest start\n```\n\n## 配合 Docker 使用\n\n构建镜像：\n\n```sh\ndocker build -t copilot-api .\n```\n\n通过 bind mount 运行容器，让认证数据在重启后保留：\n\n```sh\nmkdir -p ./copilot-data\ndocker run -p 4141:4141 -v $(pwd)/copilot-data:/root/.local/share/copilot-api copilot-api\n```\n\n这会把宿主机上的 `./copilot-data` 映射到容器内的 `/root/.local/share/copilot-api`，用于持久化 GitHub 认证数据、provider 配置和其他 gateway 状态。\n\n也可以直接通过环境变量传入 GitHub token：\n\n```sh\ndocker run -p 4141:4141 -e GH_TOKEN=your_github_token_here copilot-api\n```\n\n## Electron 桌面应用\n\n如果你更喜欢图形界面，仓库里还提供了位于 `desktop/` 的 Electron 桌面应用。它支持 GitHub Copilot 登录、OpenAI Codex OAuth，以及 DeepSeek、DashScope、OpenRouter 或自定义 provider 的 API Key 配置。授权或配置 provider 后，可以一键启动或停止本地代理，并在界面里直接查看本地端点、鉴权 Header、可用模型、额度和日志。\n\n设置页还可以配置 `OAuth App`、`API Home`、`Enterprise URL`、详细日志以及最小化到托盘。桌面安装包发布在 GitHub Releases：\n\nhttps://github.com/caozhiyuan/copilot-api/releases\n\n下载对应平台的安装包后，在应用内授权或配置 provider，选择端口并启动服务，再把你的客户端指向应用里显示的本地端点即可。发布版桌面应用使用随包内置的 Electron 运行时，正常使用不需要额外安装 Node.js；token usage 历史记录会在该内置运行时支持 SQLite 时启用。\n\n桌面应用里的高级配置页会通过 `GET/POST /admin/config/model-mappings` 读写这份共享的模型映射。同一份映射会统一作用于 `POST /v1/messages`、`POST /v1/messages/count_tokens`、`POST /v1/responses` 和 `POST /v1/chat/completions`，不再按接口区分。它使用的是 `auth.adminApiKey`，不是普通的 `auth.apiKeys`；应用会在服务启动并自动生成该 key 后，直接从 `config.json` 读取它来发起请求。\n\n### 桌面应用截图\n\n下面展示了桌面应用中的首页、Token 用量统计页面：\n\n<p align=\"center\">\n  <img src=\"./docs/screenshots/desktop-dashboard.png\" alt=\"Copilot API 桌面应用首页\" width=\"49%\" />\n  <img src=\"./docs/screenshots/desktop-token-usage.png\" alt=\"Copilot API 桌面应用 Token 用量页\" width=\"49%\" />\n</p>\n\n## 与 Claude Code 一起使用\n\n这个 AI gateway 可以为 [Claude Code](https://docs.anthropic.com/en/claude-code) 提供后端能力。Claude Code 是 Anthropic 提供的实验性面向开发者的对话式 AI 助手。\n\n有两种方式可以把 Claude Code 配置为使用这个 AI gateway：\n\n### 通过 `--claude-code` 标志进行交互式配置\n\n执行带 `--claude-code` 的 `start` 命令开始：\n\n```sh\nnpx @jeffreycao/copilot-api@latest start --claude-code\n```\n\n你会被提示选择一个主模型，以及一个用于后台任务的 \"small, fast\" 模型。选择完成后，会有一条命令被复制到剪贴板中。该命令会设置 Claude Code 使用这个 AI gateway 所需的环境变量。\n\n在新的终端中粘贴并执行这条命令，即可启动 Claude Code。\n\n<a id=\"manual-configuration-with-settingsjson\"></a>\n\n### 通过 `settings.json` 手动配置\n\n另一种方式是在项目根目录中创建 `.claude/settings.json` 文件，并写入 Claude Code 所需的环境变量。这样你就不需要每次都运行交互式配置了。\n\n下面是一个 `.claude/settings.json` 示例：\n\n```json\n{\n  \"env\": {\n    \"ANTHROPIC_BASE_URL\": \"http://localhost:4141\",\n    \"ANTHROPIC_AUTH_TOKEN\": \"dummy\",\n    \"ANTHROPIC_MODEL\": \"deepseek/deepseek-v4-pro\",\n    \"ANTHROPIC_DEFAULT_SONNET_MODEL\": \"deepseek/deepseek-v4-pro\",\n    \"ANTHROPIC_DEFAULT_HAIKU_MODEL\": \"deepseek/deepseek-v4-flash\",\n    \"DISABLE_NON_ESSENTIAL_MODEL_CALLS\": \"1\",\n    \"CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC\": \"1\",\n    \"CLAUDE_CODE_ATTRIBUTION_HEADER\": \"0\",\n    \"CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION\": \"false\",\n    \"CLAUDE_CODE_DISABLE_TERMINAL_TITLE\": \"true\",\n    \"CLAUDE_CODE_ENABLE_AWAY_SUMMARY\": \"0\"\n  },\n  \"permissions\": {\n    \"deny\": [\n      \"mcp__ide__executeCode\"\n    ]\n  }\n}\n```\n\n- 请根据需要替换 `ANTHROPIC_MODEL`、`ANTHROPIC_DEFAULT_OPUS_MODEL`、`ANTHROPIC_DEFAULT_SONNET_MODEL` 和 `ANTHROPIC_DEFAULT_HAIKU_MODEL`。配置完成后，请安装 claude code 插件，见 [插件集成](#plugin-integrations)。\n- 将 `CLAUDE_CODE_ATTRIBUTION_HEADER` 设为 `0` 可以阻止 Claude Code 在 system prompt 中附加计费和版本信息，从而避免 prompt cache 失效。\n- 关闭 `CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION` 和 `CLAUDE_CODE_ENABLE_AWAY_SUMMARY` 可以避免不必要地消耗额度。\n- Claude Code WebSearch 已支持纯搜索请求。Copilot 路径请保持全局 `messageApiWebSearchModel` 指向 Responses-capable GPT 模型或 `provider/model` 别名；provider 路由请使用原生 Anthropic provider 或 `openai-responses` provider。只有在你明确想禁止这类流量时，才需要把 `WebSearch` 加到 `permissions.deny`。\n- 如果使用的不是 Claude 模型，请不要启用 `ENABLE_TOOL_SEARCH`。如果使用的是 Claude 模型，则可以启用 `ENABLE_TOOL_SEARCH`。当前 Claude Code 使用的是客户端 tool search 模式，在该模式下每次加载 defer tools 都需要额外请求一次。\n- `CLAUDE_CODE_AUTO_COMPACT_WINDOW`：设置用于自动压缩计算的上下文容量（以 token 为单位）。默认使用模型自身的上下文窗口：标准模型为 200K，扩展上下文模型为 1M。使用 1M 上下文模型（如 `claude-opus-4-6[1m]`）时，可设置一个较低的值（如 `500000`）将窗口视为 500K 用于压缩计算。该值受限于模型的实际上下文窗口上限。`CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` 会基于此值的百分比生效。设置此变量可将压缩阈值与状态栏的 `used_percentage` 解耦（后者始终使用模型的完整上下文窗口）。\n\n更多选项见：[Claude Code settings](https://docs.anthropic.com/en/docs/claude-code/settings#environment-variables)\n\n也可以参考 IDE 集成说明：[Add Claude Code to your IDE](https://docs.anthropic.com/en/docs/claude-code/ide-integrations)\n\n## 与 OpenCode 一起使用\n\nOpenCode 已经有直接的 GitHub Copilot provider。本节适用于你希望让 OpenCode 通过 `@ai-sdk/anthropic` 指向这个 AI gateway，并复用本 README 前面提到的 agent 行为时。\n\n### 最小配置\n\n使用 OpenCode OAuth app 启动 AI gateway：\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth --oauth-app=opencode\nnpx @jeffreycao/copilot-api@latest start\n```\n\n然后让 OpenCode 通过 `@ai-sdk/anthropic` 指向这个 AI gateway。\n\n示例 `~/.config/opencode/opencode.json`：\n\n```json\n{\n  \"$schema\": \"https://opencode.ai/config.json\",\n  \"provider\": {\n    \"local\": {\n      \"npm\": \"@ai-sdk/anthropic\",\n      \"name\": \"My Local\",\n      \"options\": {\n        \"baseURL\": \"http://localhost:4141/v1\",\n        \"apiKey\": \"dummy\"\n      },\n      \"models\": {\n        \"gpt-5.4\": {\n          \"name\": \"gpt-5.4\",\n          \"modalities\": {\n            \"input\": [\"text\", \"image\"],\n            \"output\": [\"text\"]\n          },\n          \"limit\": {\n            \"context\": 400000,\n            \"input\": 272000,\n            \"output\": 128000\n          }\n        },\n        \"claude-sonnet-4.6\": {\n          \"id\": \"claude-sonnet-4.6\",\n          \"name\": \"claude-sonnet-4.6\",\n          \"modalities\": {\n            \"input\": [\"text\", \"image\"],\n            \"output\": [\"text\"]\n          },\n          \"limit\": {\n            \"context\": 200000,\n            \"output\": 32000\n          },\n          \"options\": {\n            \"thinking\": {\n              \"type\": \"adaptive\"\n            },\n            \"effort\": \"max\"\n          }\n        }\n      }\n    }\n  }\n}\n```\n\n这些字段的重要性：\n\n- `npm: \"@ai-sdk/anthropic\"` 是关键。OpenCode 会以 Anthropic Messages 语义与这个 AI gateway 通信，而不是把一切扁平化为 OpenAI Chat Completions。\n- `options.baseURL` 应设为 `http://localhost:4141/v1`；Anthropic SDK 会自动补上 `/messages`、`/models` 和 `/messages/count_tokens`。\n- 如果你在此代理中启用了 `auth.apiKeys`，请把 `dummy` 替换为真实 key；否则任意占位值都可以。\n\n## 与 Codex 一起使用\n\n这个 AI gateway 也可以为 Codex 提供后端能力。\n\n### Codex `config.toml` 参考配置\n\n把以下 `[model_providers.copilot_api]` 段加入你的 Codex `~/.codex/config.toml`：\n\n```toml\nmodel_provider = \"copilot_api\"\nmodel_reasoning_summary = \"auto\"\nmodel_context_window = 272000\nmodel_auto_compact_token_limit = 244800\n\n[model_providers.copilot_api]\nname = \"OpenAI\"\nbase_url = \"http://localhost:4141\"\nenv_key = \"GITHUB_COPILOT_API_KEY\"\nrequires_openai_auth = true\nsupports_websockets = false\nwire_api = \"responses\"\nrequest_max_retries = 3\nstream_max_retries = 1\nstream_idle_timeout_ms = 300000\n\n[features]\nremote_compaction_v2 = true\n\n[analytics]\nenabled = false\n```\n\n> [!NOTE]\n> 此配置仅限于 Codex 与 GitHub Copilot provider。`name` 一定要配置为 `\"OpenAI\"`。它可以缓解 Codex local compact 不命中缓存的问题。\n\n## GPT Tool Search\n\n对于 `gpt-5.4+` 这类 GPT Responses 模型，这个 AI gateway 可以通过一个很小的 MCP bridge 暴露 Responses `tool_search`。Claude Code 和 opencode 都可以使用同一个 bridge，前提是客户端会加载 MCP server，并且 Anthropic Messages 流量会经过这个 AI gateway。\n\nGPT 模型不要设置 Claude Code 原生的 `ENABLE_TOOL_SEARCH`。这个开关启用的是 Claude Code 自己的客户端 tool search 模式，可能导致 deferred 工具定义不再转发给 AI gateway。这个 AI gateway 需要完整的工具定义，这样才能只保留那一小组常驻加载工具，其余工具统一转换为 Responses deferred namespace。\n\n如果你安装了 `tool-search@copilot-api-marketplace`，Claude Code 会自动带上这个 MCP bridge，可以跳过下面这段 Claude Code MCP 手动配置。\n\n请把 tool search bridge 加到 Claude Code 使用的 MCP 配置中：\n\n```json\n{\n  \"mcpServers\": {\n    \"tool_search\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@jeffreycao/copilot-api@latest\", \"mcp\"]\n    }\n  }\n}\n```\n\n请把 tool search bridge 加到 opencode 使用的 MCP 配置中：\n\n```json\n{\n  \"mcp\": {\n    \"tool_search\": {\n      \"type\": \"local\",\n      \"command\": [\"npx\", \"-y\", \"@jeffreycao/copilot-api@latest\", \"mcp\"]\n    }\n  }\n}\n```\n\n本地开发时可以将命令换成 `bun`，参数换成 `[\"run\", \"./src/main.ts\", \"mcp\"]`。\n\nAI gateway 内部现在会把 OpenAI Responses `tool_search` 配置成 client-executed 模式。deferred tools 仍然会作为可搜索 namespace 暴露给模型，但会明确要求模型直接返回下一步要加载的精确工具名列表。\n\n该 bridge 使用直接工具选择，不做 query 搜索。工具入参是 `names`，值为逗号分隔的精确 deferred 工具名，例如 `TaskList,TaskGet,mcp__fetch__fetch`。\n\n<a id=\"plugin-integrations\"></a>\n\n## 插件集成\n\n本项目为 Claude Code 和 opencode 提供了插件集成。\n\n#### Claude Code 插件集成（基于 marketplace）\n\nClaude Code 集成现在拆分为两个插件：\n\n- `agent-inject` 会在 `SubagentStart` 时注入 `__SUBAGENT_MARKER__...`，以便 AI gateway 推导 `x-initiator: agent`。\n- `tool-search` 会注册用于 GPT Responses deferred tool loading 的 `tool_search` MCP bridge。\n\n- 本仓库中的 marketplace catalog：`.claude-plugin/marketplace.json`\n- 本仓库中的插件源码：`plugin/claude/agent-inject`、`plugin/claude/tool-search`\n\n远程添加 marketplace：\n\n```sh\n/plugin marketplace add https://github.com/caozhiyuan/copilot-api.git\n```\n\n从 marketplace 安装插件：\n\n```sh\n/plugin install agent-inject@copilot-api-marketplace\n/plugin install tool-search@copilot-api-marketplace\n```\n\n安装后，`agent-inject` 会在 `SubagentStart` 时注入 `__SUBAGENT_MARKER__...`，AI gateway 会利用它推导 `x-initiator: agent`。\n\n`agent-inject` 还会注册一个 `UserPromptSubmit` hook，并返回 `{\"continue\": true}`；同时它也可以通过环境变量注入 `SessionStart` reminder 规则：\n\n- `CLAUDE_PLUGIN_ENABLE_QUESTION_RULES=1` 会自动为 Claude Code 启用两条关于使用 `question` 工具的提醒。你也可以把同样的提醒手动写进 `CLAUDE.md`；见 [CLAUDE.md 或 AGENTS.md 推荐内容](#claudemd-or-agentsmd-recommended-content)。\n- `CLAUDE_PLUGIN_ENABLE_NO_BACKGROUND_AGENTS_RULE=1` 会启用关于避免在 agent hooks 中使用 `run_in_background: true` 的提醒。\n\n`tool-search` 插件内置了 [GPT Tool Search](#gpt-tool-search) 一节描述的同一个 MCP bridge，因此安装该插件后，Claude Code 用户无需再手动配置 `tool_search` server。\n\n#### Opencode 插件\n\nsubagent 标记生成器被打包为一个 opencode 插件，位于 `plugin/opencode/subagent-marker.js`。\n\n**安装方式：**\n\n将插件文件复制到你的 opencode 插件目录：\n\n```sh\n# 克隆或下载本仓库后复制该插件\ncp plugin/opencode/subagent-marker.js ~/.config/opencode/plugins/\n```\n\n或者手动在 `~/.config/opencode/plugins/subagent-marker.js` 创建该文件，并填入插件内容。\n\n**功能：**\n\n- 跟踪 subagent 创建的子会话\n- 自动在 subagent 聊天消息前添加 marker system reminder（`__SUBAGENT_MARKER__...`）\n- 设置 `x-session-id` 请求头以跟踪会话\n- 让这个 AI gateway 能够把来自 subagent 的请求识别为 `x-initiator: agent`\n\n该插件会挂接到 `session.created`、`session.deleted`、`chat.message` 和 `chat.headers` 事件上，以无缝提供 subagent marker 能力。\n\n## 使用量查看器\n\n服务启动后，控制台会输出一个 Copilot 使用量看板 URL。这个看板是一个用于监控 API 用量的 Web 界面。\n\n1. 启动服务。例如使用 npx：\n   ```sh\n   npx @jeffreycao/copilot-api@latest start\n   ```\n2. 服务会输出一个 usage viewer 的 URL。将它复制到浏览器中打开，形式大致如下：\n   `http://localhost:4141/usage-viewer?endpoint=http://localhost:4141/usage`\n   - 如果你在 Windows 上使用 `start.bat` 脚本，这个页面会自动打开。\n\n看板提供了更易读的 Copilot 用量视图：\n\n> token usage 历史记录需要 Bun 或 Node.js >= 22.13.0。Node.js < 22.13.0 时服务会正常运行，但 token usage 存储会被禁用。\n\n- **API Endpoint URL**：通过 URL 查询参数指定 API endpoints，默认指向本地服务。支持手动切换为其他兼容 endpoints。\n- **x-api-key 认证**：如果启用了 API Key 认证，可填入 `x-api-key` 请求头。密钥会持久化保存在浏览器本地存储中。\n- **Period 选择器**：支持 Day / Week / Month 三种时间范围，切换时 URL 参数会自动同步，方便收藏和分享。\n- **Fetch Data**：点击 \"Refresh\" 按钮加载或刷新使用数据。页面加载时也会自动拉取数据。\n- **Copilot Quotas 额度**：通过进度条展示 Chat、Completions 等不同服务的额度使用情况，悬停可查看已用/剩余详情。\n- **Token Usage 指标卡片**：汇总当前周期的 Total、Input、Output、Cache Read、Cache Write、Requests 和预估费用。\n- **趋势图（Week / Month）**：提供按模型和指标筛选的折线趋势图，点击数据点可查看单日用量明细。\n- **Model Breakdown 表格**：按模型维度列出周期内的请求数、输入/输出/缓存 token 和预计费用。\n- **Request Events 分页列表**：按时间排序的请求事件记录，支持分页浏览，含时间戳、模型、请求 ID 和 token 用量。\n- **Detailed Information**：展示 API 返回的完整 JSON 响应，便于深入分析所有可用统计数据。\n- **URL-based Configuration**：也可通过 `endpoint` 和 `period` 查询参数直接指定 API 端点与时间范围。例如：\n  `http://localhost:4141/usage-viewer?endpoint=http://your-api-server/usage&period=week`\n\n### Usage Viewer 截图\n\n<p align=\"center\">\n  <img src=\"./docs/screenshots/usage-viewer.png\" alt=\"Copilot API Usage Viewer 页面\" width=\"900\" />\n</p>\n\n## 命令结构\n\nCopilot API 现在使用子命令结构，主要命令包括：\n\n- `start`：启动 AI gateway 服务。如果已有 GitHub token，则启用 Copilot 路径；如果没有 GitHub token，但存在至少一个启用中的 provider，则按 provider-only 模式启动；如果两者都没有，会引导你配置 provider。\n- `auth`：仅执行 provider 登录或配置流程，不启动服务。可用于 GitHub Copilot 登录、Codex OAuth，或第三方 provider API key 配置。\n- `debug`：显示诊断信息，包括版本、运行时详情、文件路径以及认证状态，便于排障与支持。\n\n## 命令行选项\n\n### 全局选项\n\n以下选项可用于任意子命令。若在子命令之前传入，请使用 `--key=value` 形式：\n\n| 选项 | 说明 | 默认值 | 别名 |\n| --- | --- | --- | --- |\n| --api-home | API home 目录路径（设置 `COPILOT_API_HOME`） | 无 | 无 |\n| --oauth-app | OAuth app 标识符（设置 `COPILOT_API_OAUTH_APP`） | 无 | 无 |\n| --enterprise-url | GitHub Enterprise URL（设置 `COPILOT_API_ENTERPRISE_URL`） | 无 | 无 |\n\n### Start 命令选项\n\n以下是 `start` 命令可用的命令行选项：\n\n| 选项 | 说明 | 默认值 | 别名 |\n| --- | --- | --- | --- |\n| --port | 监听端口 | 4141 | -p |\n| --verbose | 启用详细日志 | false | -v |\n| --github-token | 直接提供 GitHub token（必须通过 `auth` 子命令生成） | 无 | -g |\n| --claude-code | 生成一个使用 Copilot API 配置启动 Claude Code 的命令 | false | -c |\n| --show-token | 在获取和刷新时显示 GitHub 与 Copilot token | false | 无 |\n| --proxy-env | 从环境变量初始化代理 | false | 无 |\n\n### Auth 命令选项\n\n| 选项 | 说明 | 默认值 | 别名 |\n| --- | --- | --- | --- |\n| --provider | 要登录或配置的 provider（`copilot`、`codex`、`opencode-go`、`deepseek`、`dashscope`、`openrouter` 或 `custom`） | 交互选择 | 无 |\n| --verbose | 启用详细日志 | false | -v |\n| --show-token | 认证时显示 GitHub token | false | 无 |\n\n只有在需要启用 GitHub Copilot provider 时，才需要执行 `copilot-api auth login --provider copilot`。使用 `codex` 或第三方 provider-only 模式不要求配置 Copilot。\n\n使用 `copilot-api auth login --provider deepseek`、`--provider dashscope`、`--provider openrouter` 或 `--provider opencode-go` 可以通过 CLI 快速新增或更新这些常用第三方 provider。DeepSeek 会提示输入掩码显示的 `apiKey`、provider `type`（默认 `anthropic`），以及默认 `https://api.deepseek.com/anthropic` 的 `baseUrl`。DashScope 会提示输入掩码显示的 `apiKey`、provider `type`（默认 `openai-compatible`）和预填默认值的 `baseUrl`。OpenRouter 只提示输入掩码显示的 `apiKey` 和预填默认值的 `baseUrl`，并固定写入 `type: \"anthropic\"`。OpenCode Go 只提示输入掩码显示的 `apiKey` 和预填默认值的 `baseUrl`，并固定写入 `type: \"openai-compatible\"`（baseUrl `https://opencode.ai/zen/go`）。配置并启用 provider 后，`copilot-api start` 可在没有 GitHub token 的情况下启动。\n\n使用 `copilot-api auth login --provider custom` 可以通过 CLI 新增或更新其他第三方 provider。命令会依次提示输入 provider name、项目支持的 type（`anthropic`、`openai-compatible` 或 `openai-responses`）、`baseUrl`、掩码显示的 `apiKey` 和 `authType`；`authType` 可保持 type 默认值，也可选择 `x-api-key` / `authorization`。\n\n### Debug 命令选项\n\n| 选项 | 说明 | 默认值 | 别名 |\n| --- | --- | --- | --- |\n| --json | 以 JSON 输出调试信息 | false | 无 |\n\n<a id=\"configuration-configjson\"></a>\n\n## 配置（config.json）\n\n- **位置：** Linux/macOS 为 `~/.local/share/copilot-api/config.json`，Windows 为 `%USERPROFILE%\\.local\\share\\copilot-api\\config.json`。\n- **默认结构：**\n  ```json\n  {\n    \"auth\": {\n      \"apiKeys\": [],\n      \"adminApiKey\": \"<startup 自动生成>\"\n    },\n    \"providers\": {},\n    \"modelMappings\": {},\n    \"extraPrompts\": {\n      \"gpt-5-mini\": \"<built-in exploration prompt>\"\n    },\n    \"smallModel\": \"gpt-5-mini\",\n    \"contextManagement\": {\n      \"messages\": true,\n      \"responses\": false\n    },\n    \"modelResponsesApiCompactThresholds\": {\n      \"gpt-5.4\": 217600,\n      \"gpt-5.5\": 217600,\n      \"gpt-5.6-sol\": 231200,\n      \"gpt-5.6-terra\": 231200,\n      \"gpt-5.6-luna\": 231200\n    },\n    \"modelReasoningEfforts\": {\n      \"gpt-5-mini\": \"low\"\n    },\n    \"useMessagesApi\": true,\n    \"useResponsesApiWebSocket\": true,\n    \"useResponsesApiWebSearch\": true,\n    \"messageApiWebSearchModel\": \"gpt-5-mini\"\n  }\n  ```\n- **auth.apiKeys：** 用于普通非 admin 路由的 API key。支持多个 key 轮换使用。请求可通过 `x-api-key: <key>` 或 `Authorization: Bearer <key>` 进行认证。若为空或省略，则普通路由的认证会被禁用。\n- **auth.adminApiKey：** 仅用于 `/admin/*` 路由的单个 admin key。若未配置，服务会在启动时自动生成一个随机 key，并回写到 `config.json`。它同样使用 `x-api-key` 或 `Authorization: Bearer` 这两种头，但普通 `auth.apiKeys` 不能访问 `/admin/*`。\n- **modelMappings：** 用于顶层 `POST /v1/messages`、`POST /v1/messages/count_tokens`、`POST /v1/responses` 和 `POST /v1/chat/completions` 请求的精确 `sourceModel -> targetModel` 重写映射，这几类接口共用同一份规则。省略该字段或保留为 `{}` 时，不会做模型重写。`source` 和 `target` 都必须是非空字符串。`target` 可以是普通模型 ID，也可以是 `provider/model` 形式的别名，例如 `dashscope/qwen3.6-plus`；重写发生在 provider alias 解析之前。这些映射不再按接口区分。`GET/POST /admin/config/model-mappings` 管理接口读写的也只有这个字段。\n- **extraPrompts：** `model -> prompt` 的映射。把 Anthropic 风格请求翻译为 Responses API 时，会将其附加到第一条 system prompt 后面。你可以借此为不同模型注入护栏或指引。缺失的默认项会自动补齐，但不会覆盖你自定义的 prompt。对于 GPT-5.3+ 模型（如 `gpt-5.3-codex`、`gpt-5.4`、`gpt-5.5`），未显式配置时会自动使用内置的 commentary prompt。内置 prompt 会启用带阶段感知的 commentary，让模型在工具调用或更深层推理前先发出简短的用户可见进度说明。\n- **providers：** 全局上游 provider 映射。每个 provider key（例如 `dashscope`）都会变成一个路由前缀（`/dashscope/v1/messages`）。支持 `type: \"anthropic\"`、`type: \"openai-compatible\"` 和 `type: \"openai-responses\"`。顶层客户端也可以在 `/v1/messages`、`/v1/messages/count_tokens`、`/v1/responses` 和 `/v1/chat/completions` 中使用 `model: \"dashscope/model-id\"`；AI gateway 会在转发上游前移除 `dashscope/` 前缀。`openai-compatible` provider 同时支持 chat 和 Messages 流程：`/v1/chat/completions` 会直连上游 `/v1/chat/completions`，而 `/v1/messages` 和 `/:provider/v1/messages` 会先翻译为上游 Chat Completions，再把响应翻译回 Anthropic Messages。`GET /v1/models` 会聚合已启用 provider 的模型，并以 `provider/model-id` 形式返回；单个 provider 的原始模型列表仍可使用 `GET /dashscope/v1/models`。\n  - `enabled`：可选，若省略则默认为 `true`。\n  - `baseUrl`：provider API 的基础 URL，不要带结尾的 endpoint。Anthropic provider 不要带 `/v1/messages`；OpenAI 兼容 provider 不要带 `/v1/chat/completions`；OpenAI Responses provider 不要带 `/v1/responses`。\n  - `apiKey`：作为上游凭据值使用；普通 provider 必须配置。\n  - `authType`：可选，控制 `apiKey` 如何发送到上游。普通 provider 支持 `x-api-key` 和 `authorization`。Anthropic provider 默认 `x-api-key`；OpenAI 兼容和 OpenAI Responses provider 默认 `authorization`。当设置为 `authorization` 时，代理会发送 `Authorization: Bearer <apiKey>`。`oauth2` 仅保留给内置 `codex` provider，并由 `auth login --provider codex` 自动写入。\n  - `pricingCurrency`：可选，provider 维度的 token 费用币种，例如 `USD` 或 `CNY`。快捷 provider 默认 DashScope、DeepSeek 为 `CNY`，Codex/OpenRouter 为 `USD`。费用按币种分别汇总，不做汇率换算。\n  - `models`：可选，按模型 ID 配置的映射。每个键为请求中的模型名，值支持：\n    - `temperature`：可选，当请求未指定时使用的默认温度。\n    - `topP`：可选，当请求未指定时使用的默认 `top_p`。\n    - `topK`：可选，当请求未指定时使用的默认 `top_k`。\n    - `extraBody`：可选，按模型合入上游请求体的动态字段；请求体显式同名字段优先。OpenAI 兼容 provider 可用它配置 `enable_thinking`、`preserve_thinking`、`reasoning_effort` 等字段。`thinking_budget` 是 OpenAI 兼容 provider 的特殊覆盖项：配置在 `extraBody` 后，会在 Anthropic `thinking.budget_tokens` 翻译之后强制写入，并覆盖请求派生出的预算值。对于 provider name 为 `dashscope` 或 `baseUrl` 包含 `aliyuncs.com` 的 provider，请求派生的 `thinking_budget`（来自 Anthropic `thinking.budget_tokens`）会转发给上游；其他 OpenAI 兼容 provider 会移除请求派生的 `thinking_budget`，但 `extraBody` 中的 `thinking_budget` 仍然生效。对于 DashScope provider，当 `preserve_thinking` 未在 `extraBody` 或请求体中显式设置时，默认为 `true`。\n    - `pricing`：可选，按模型配置 token 单价，币种使用 provider 的 `pricingCurrency`，单位为每 100 万 tokens。支持 `input`、`output`、`cachedInput`（隐式缓存读）、`explicitCachedInput`（显式缓存读）和 `cacheCreationInput`。如需按输入 token 总量分档，可用带 `maxInputTokens` 的 `tiers`。\n    - `contextCache`：可选，provider name 为 `dashscope` 或 `baseUrl` 包含 `aliyuncs.com` 时默认 `true`，其他 OpenAI 兼容 provider 默认 `false`。用于启用阿里云百炼/DashScope 的显式缓存（explicit context cache），会按其 Context Cache 格式在最多 4 个 content block 上注入 `cache_control: { \"type\": \"ephemeral\" }`。缓存断点策略与 opencode 主链路保持一致：前 2 条 system 消息 + 最后 2 条非 system 消息。标记字符串 content 时会把 `system` / `user` / `assistant` / `tool` 消息转换为 text content part 数组；已有数组 content 则标记最后一个 part。如果模型本身已经支持隐式缓存，或上游不支持该显式缓存扩展字段，可在模型配置中设为 `false`。支持相同显式缓存扩展的非 DashScope provider 可设为 `true`。同时适用于 `/v1/messages` 和 `/v1/chat/completions` 路由。\n    - `supportPdf`：可选，控制该模型是否支持 PDF/document content。默认 `false`，不支持时会把 PDF 转成提示文本；设为 `true` 时会把 PDF/document 转成 OpenAI Chat Completions 的 file part。\n    - `toolContentSupportType`：可选，配置该模型的 tool result content 支持能力，值为 `array`、`image`、`pdf` 的数组。provider 侧未配置时默认只发送 string tool content。若 `supportPdf` 为 `true` 但这里不包含 `pdf`，tool result 里的 file part 会被转成 user role 消息。Copilot 主链路不使用这个 provider 默认，仍按 array + image 且不支持 PDF 的能力处理。\n    - `type`：可选，按模型覆盖 provider 的协议类型。支持 `anthropic`、`openai-compatible` 和 `openai-responses`。设置后，provider 的 `/v1/messages` 路由会使用该模型的 type 替代 provider 级别的 type 进行请求路由、认证头解析和上游端点选择。适用于 OpenCode Go 等上游对不同模型同时支持 OpenAI 兼容和 Anthropic Messages API 的 provider。覆盖 type 时，认证头按覆盖后 type 的默认值解析（Anthropic 默认 `x-api-key`；OpenAI 兼容/Responses 默认 `authorization`）。\n\n  DashScope 模型配置示例：\n  ```json\n  {\n    \"providers\": {\n      \"dashscope\": {\n        \"type\": \"openai-compatible\",\n        \"enabled\": true,\n        \"baseUrl\": \"https://dashscope.aliyuncs.com/compatible-mode\",\n        \"apiKey\": \"sk-your-dashscope-key\",\n        \"pricingCurrency\": \"CNY\",\n        \"models\": {\n          \"qwen3.7-plus\": {\n            \"temperature\": 1,\n            \"topP\": 0.95,\n            \"topK\": 20,\n            \"extraBody\": {\n              \"preserve_thinking\": true\n            }\n          },\n          \"glm-5.1\": {\n            \"temperature\": 0.7,\n            \"topP\": 0.95,\n            \"contextCache\": true,\n            \"pricing\": {\n              \"tiers\": [\n                {\n                  \"maxInputTokens\": 32000,\n                  \"input\": 6,\n                  \"cachedInput\": 1.2,\n                  \"explicitCachedInput\": 0.6,\n                  \"cacheCreationInput\": 7.5,\n                  \"output\": 24\n                },\n                {\n                  \"maxInputTokens\": 200000,\n                  \"input\": 8,\n                  \"cachedInput\": 1.6,\n                  \"explicitCachedInput\": 0.8,\n                  \"cacheCreationInput\": 10,\n                  \"output\": 28\n                }\n              ]\n            },\n            \"extraBody\": {\n              \"preserve_thinking\": true\n            }\n          }\n        }\n      }\n    }\n  }\n  ```\n  内置 token 价格覆盖 Codex GPT 模型（USD）、DashScope `qwen3.7-max`、`qwen3.7-plus`、`glm-5.1`、`glm-5.2`（CNY），DeepSeek `deepseek-v4-flash`、`deepseek-v4-pro`、`deepseek-chat`、`deepseek-reasoner`（CNY），以及 OpenCode Go 模型（`glm-5.2`、`deepseek-v4-flash`、`deepseek-v4-pro`、`kimi-k2.7-code`、`mimo-v2.5`、`mimo-v2.5-pro`、`qwen3.7-plus`、`qwen3.7-max`、`minimax-m2.5`、`minimax-m3`，USD）。用户配置的 `pricing` 优先于内置价格。DashScope 若上游 usage 中出现 `cache_creation_input_tokens` 字段，cached tokens 按显式缓存读价计费；否则 `cachedInput` 作为隐式缓存读价。DeepSeek 的 `prompt_cache_hit_tokens` 会归入 cached input，`prompt_cache_miss_tokens` 会归入普通 input。\n- **smallModel：** 无工具预热消息的回退模型（例如 Claude Code 的探测请求）；默认是 `gpt-5-mini`。\n- **contextManagement：** 控制代理是否为 Responses API 附加 `context_management` 压缩指令。`messages` 作用于被翻译成 Responses API 的 Anthropic 风格 `/v1/messages` 请求，包括 `openai-responses` provider 的 Messages 路由，默认值为 `true`。`responses` 作用于 native `/v1/responses` 流量，包括 `provider/model` 别名和内置 `codex` provider，默认值为 `false`。只有在确认客户端支持 context management compaction 后，才建议在 Responses API 下启用 `responses`。启用后，请求体会带上 `context_management`，并在后续轮次中仅保留最新的压缩承载内容。**注意：** 对于 GPT-5.6 及以上模型（如 `gpt-5.6-sol`、`gpt-5.6-terra`、`gpt-5.6-luna`），context management 功能会被强制禁用，因为开启后会破坏这些模型的 prompt 缓存命中。此强制覆盖优先于 `contextManagement` 和 `modelResponsesApiCompactThresholds` 配置。\n- **modelResponsesApiCompactThresholds：** 按模型覆盖 Responses API 的 `compact_threshold`，仅在代理自动附加 `context_management` 时使用。它的优先级高于 `resolveResponsesCompactThreshold` 基于 `max_prompt_tokens * ratio` 的兜底阈值。默认将 `gpt-5.4` 和 `gpt-5.5` 设为 `217600`（`272000 * 0.8`），将 `gpt-5.6-sol`、`gpt-5.6-terra`、`gpt-5.6-luna` 设为 `231200`（`272000 * 0.85`）。未列出的模型继续使用原有兜底逻辑。\n- **modelReasoningEfforts：** `/v1/messages` 请求的模型级默认推理强度。仅当请求没有传入 `output_config.effort` 时，该配置才会生效。\n  - **优先级：** 请求中的 `output_config.effort` > `modelReasoningEfforts[model]` > 内置默认值（GPT-5.3+ 模型为 `xhigh`，其他模型为 `high`）。\n  - **转发字段：** 走 Copilot 原生 Messages API 时，最终值写入 `output_config.effort`；转换为 Responses API 时，最终值写入 `reasoning.effort`。\n  - **配置可选值：** `none`、`minimal`、`low`、`medium`、`high`、`xhigh`、`max`。\n- **useMessagesApi：** 当为 `true` 时，支持 Copilot 原生 `/v1/messages` 的 Claude 系模型会走 Messages API；否则回退到 `/chat/completions`。设为 `false` 可禁用 Messages API 路由，始终使用 `/chat/completions`。默认值为 `true`。\n- **useResponsesApiWebSocket：** 当为 `true` 时，Responses API 请求会优先对声明了 `ws:/responses` 的模型使用 Copilot websocket transport；仅声明 `/responses` 的模型仍走 HTTP。设为 `false` 可禁用 websocket 路由，并在模型支持 `/responses` 时使用 HTTP `/responses`。默认值为 `true`。\n- **useResponsesApiWebSearch：** 当为 `true` 时，服务端会保留 Responses API 中 `type: \"web_search\"` 的工具并透传到上游。设为 `false` 则会从 `/responses` payload 中移除这些工具。默认值为 `true`。\n- **messageApiWebSearchModel：** 顶层 Copilot `/v1/messages` 请求只包含服务端 `web_search` 工具时使用的全局模型，默认值为 `gpt-5-mini`。如果该值是 `provider/model` 别名，请求会进入对应 provider 的 Messages API 路径，并在转发前移除 provider 前缀。对于 Copilot GPT 模型，web search 会通过 `/responses` 执行。混合 `web_search` 与自定义工具的场景暂不支持，服务端会移除 server-side `web_search`。\n- **claudeTokenMultiplier：** 用于 Claude `/v1/messages/count_tokens` 请求在本地走 GPT tokenizer 估算时的乘数。默认值为 `1.15`。如果你的客户端仍然过晚触发上下文压缩，可以适当调大。这个配置只会在代理本地估算 Claude token 时生效；如果已经配置 `anthropicApiKey` 且 Anthropic token counting 调用成功，则会直接返回 Anthropic 的精确计数，不会使用这个乘数。\n- **anthropicApiKey：** 用于把 Claude `/v1/messages/count_tokens` 请求转发到 Anthropic 真实 token counting 端点的 API key，这样会返回精确计数，而不是 GPT tokenizer 估算值。也可通过环境变量 `ANTHROPIC_API_KEY` 设置。若未配置，或上游调用失败，则回退到由 `claudeTokenMultiplier` 控制的本地 GPT tokenizer 估算。\n\n编辑此文件后即可自定义 prompts，或替换为你自己的快速模型。修改完成后请重启服务（或重新执行命令），让缓存中的配置刷新生效。\n\n## API 认证\n\n- **受保护的普通路由：** 当配置了 `auth.apiKeys` 且非空时，除 `/`、`/usage-viewer` 和 `/usage-viewer/` 以外的普通路由都需要认证。\n- **Admin 路由：** 所有 `/admin/*` 路由都要求 `auth.adminApiKey`。如果缺失，服务会在启动时自动生成并在开始提供服务前写回 `config.json`。\n- **允许的认证头：**\n  - `x-api-key: <your_key>`\n  - `Authorization: Bearer <your_key>`\n- **CORS 预检：** `OPTIONS` 请求始终允许。\n- **未配置普通 key 时：** 普通路由仍可直接访问；但这条规则不适用于 `/admin/*`，后者只接受 `auth.adminApiKey`。\n\n普通受保护路由的示例请求：\n\n```sh\ncurl http://localhost:4141/v1/models \\\n  -H \"x-api-key: your_api_key\"\n```\n\nAdmin 路由的示例请求：\n\n```sh\ncurl http://localhost:4141/admin/config/model-mappings \\\n  -H \"x-api-key: your_admin_api_key\"\n```\n\n## API 端点\n\n服务端提供多个 OpenAI / Anthropic 兼容端点。请求会根据所选模型和 `provider/model` 别名路由到 GitHub Copilot、内置 `codex` provider 或已配置的 provider。\n\n### OpenAI 兼容端点\n\n这些端点模拟 OpenAI API 结构。\n\n| 端点 | 方法 | 说明 |\n| --- | --- | --- |\n| `POST /v1/responses` | `POST` | OpenAI 中用于生成模型响应的高级接口。支持 `openai-responses` provider 的 `provider/model` 别名。 |\n| `POST /v1/chat/completions` | `POST` | 为给定聊天对话创建模型响应。支持 `openai-compatible` provider 的 `provider/model` 别名；目标 provider 已配置时可在没有 Copilot 的情况下使用。 |\n| `GET /v1/models` | `GET` | 列出 Copilot 模型以及已启用 provider 的 `provider/model-id` 模型。来自 Codex 客户端（`User-Agent` 以 `codex` 开头）的请求会转发到 Codex Models 上游。 |\n| `POST /v1/embeddings` | `POST` | 创建表示输入文本的向量嵌入。 |\n\n### Codex 后端代理端点\n\n| 端点 | 方法 | 说明 |\n| --- | --- | --- |\n| `POST /alpha/search` | `POST` | 将 JSON 请求体和查询参数透明转发到 Codex Alpha Search 上游。网关会使用当前 Codex 登录态覆盖客户端的 authorization 和 account header，透传 `accept`、`content-type`、`originator`、`user-agent`、`cookie` 等兼容 header，并原样返回上游状态码、响应头和响应体。 |\n\n### Anthropic 兼容端点\n\n这些端点设计为兼容 Anthropic Messages API。\n\n| 端点 | 方法 | 说明 |\n| --- | --- | --- |\n| `POST /v1/messages` | `POST` | 为给定对话创建模型响应。支持已配置 provider 的 `provider/model` 别名，包括通过 `openai-compatible` provider 做翻译。 |\n| `POST /v1/messages/count_tokens` | `POST` | 计算一组消息的 token 数。支持已配置 provider 的 `provider/model` 别名。 |\n| `POST /:provider/v1/messages` | `POST` | 将 Anthropic Messages 请求代理到已配置的 Anthropic provider，或翻译到 OpenAI 兼容 / OpenAI Responses provider。 |\n| `GET /:provider/v1/models` | `GET` | 将模型列表请求代理到已配置的 provider。 |\n| `POST /:provider/v1/messages/count_tokens` | `POST` | 为 provider 路由请求在本地计算 token 数。 |\n\n### 使用量监控端点\n\n用于监控 Copilot 用量与额度的新端点。\n\n| 端点 | 方法 | 说明 |\n| --- | --- | --- |\n| `GET /usage` | `GET` | 获取详细的 Copilot 使用统计与额度信息。 |\n| `GET /token` | `GET` | 获取当前 API 正在使用的 Copilot token。 |\n\n### Admin / 配置端点\n\n这些端点用于本地管理操作，只接受 `auth.adminApiKey`。\n\n| 端点 | 方法 | 说明 |\n| --- | --- | --- |\n| `GET /admin/config/model-mappings` | `GET` | 返回当前 `config.json` 路径以及生效中的 `modelMappings` 映射。 |\n| `POST /admin/config/model-mappings` | `POST` | 只更新 `config.json` 里的 `modelMappings` 字段，并回传更新后的结果。 |\n\n## 使用示例\n\n常用 `npx` 命令：\n\n```sh\n# 基础启动\nnpx @jeffreycao/copilot-api@latest start\n\n# 自定义端口并开启详细日志\nnpx @jeffreycao/copilot-api@latest start --port 8080 --verbose\n\n# 执行认证流程\nnpx @jeffreycao/copilot-api@latest auth login\n\n# 配置第三方 provider，然后不依赖 GitHub Copilot 启动\nnpx @jeffreycao/copilot-api@latest auth login --provider dashscope\nnpx @jeffreycao/copilot-api@latest start\n\n# 以 JSON 格式输出调试信息\nnpx @jeffreycao/copilot-api@latest debug --json\n\n# 用 Bun 而不是 Node.js 运行已发布 CLI\nbunx --bun @jeffreycao/copilot-api@latest start\n```\n\n配置 `dashscope` 后的 OpenAI 兼容 provider 调用示例：\n\n```sh\ncurl http://localhost:4141/v1/chat/completions \\\n  -H \"content-type: application/json\" \\\n  -d '{\"model\":\"dashscope/qwen3.6-plus\",\"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]}'\n\ncurl http://localhost:4141/dashscope/v1/messages \\\n  -H \"content-type: application/json\" \\\n  -d '{\"model\":\"qwen3.6-plus\",\"max_tokens\":1024,\"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]}'\n```\n\n## 使用建议\n\n<a id=\"claudemd-or-agentsmd-recommended-content\"></a>\n\n### CLAUDE.md 或 AGENTS.md 推荐内容\n\n如果你想手动加入这些提醒，请在 Claude Code 的 `CLAUDE.md`，或 opencode/codex 的 `AGENTS.md` 中加入以下内容：\n\n```\n- Prohibited from directly asking questions to users, MUST use question tool.\n- Once you can confirm that the task is complete, MUST use question tool to make user confirm. The user may respond with feedback if they are not satisfied with the result, which you can use to make improvements and try again, after try again, MUST use question tool to make user confirm again.\n```\n"}, "58960693803eed3dd5f44ebc2c1d98d27b024687": {"t": 1785765561.4857848, "n": 31799, "h": "817572fefa5630b3", "c": "# Copilot API Proxy\n\n[English](./README.md) | 简体中文\n\n## 重要说明\n\n> [!IMPORTANT]\n> **使用前请先注意以下几点：**\n>\n> 1. **Claude Code 配置：** 与 Claude Code 搭配使用时，请将模型 ID 配置为 `claude-opus-4-8`。示例 claude `settings.json` 见 [通过 `settings.json` 手动配置](#manual-configuration-with-settingsjson)。\n>\n> 2. **内置 `copilot`、`codex` 与第三方 provider：** 执行 `npx @jeffreycao/copilot-api@latest auth`，可选择 `copilot`、`codex`、`deepseek`、`custom` 等 provider。\n>\n> 3. **注意事项：** README 顶部移除的 GitHub Copilot warning 见 [GitHub Copilot 安全提示](./NOTICE.md#github-copilot-security-notice)。\n\n---\n\n## 项目概览\n\n这是一个小型 AI gateway，可以使用 GitHub Copilot、内置 `codex` provider，也可以使用 DashScope 等已配置的第三方 provider。GitHub Copilot 现在是可选能力：如果本地没有 GitHub token，只要至少配置了一个启用中的 provider，服务仍可按 provider-only 模式启动。\n\nAI gateway 会从同一个本地端点暴露 OpenAI / Anthropic 兼容 API，让 [Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview)、OpenCode、Codex 和 OpenAI 兼容客户端可以共用同一个本地服务。\n\n在 GitHub Copilot 路径上，AI gateway 会在可用时优先使用 Copilot 原生的 Anthropic 风格 Messages API，在重工具调用场景下保留更原生的 Claude 行为。\n\n## 功能特性\n\n- **OpenAI 与 Anthropic 双兼容**：通过 `/v1/responses`、`/v1/chat/completions`、`/v1/models`、`/v1/embeddings` 和 `/v1/messages` 对外暴露同一个本地 AI gateway。\n- **Copilot 可选**：有 GitHub 凭据时可以使用 GitHub Copilot，没有 GitHub 凭据时也可以只依赖已配置的 provider 运行。\n- **同一网关接入 Copilot、`codex` 与第三方 provider**：可统一路由 GitHub Copilot、内置 `codex` provider 和配置好的外部 provider。\n- **第三方 provider 可独立启动**：配置 DashScope、DeepSeek、OpenRouter 或自定义 provider 后，不需要 GitHub Copilot 登录即可启动 AI gateway。\n- **OpenAI 兼容 provider 同时支持 chat 和 Messages API**：`openai-compatible` provider 可通过顶层 `/v1/chat/completions` 搭配 `model: \"provider/model\"` 提供 Chat Completions，也可通过 `/v1/messages` 完成 Anthropic Messages 的请求/响应翻译。\n- **面向 Claude 的更原生 Copilot 路由**：优先使用原生 `/v1/messages`，保留 Claude 风格工具流，支持 Anthropic beta 能力、通过 Responses-capable 模型支持 Claude WebSearch，并保留 subagent / session 标记。\n- **Claude Code 与 OpenCode 集成**：兼容 Claude Code 与 OpenCode，也支持通过 `@ai-sdk/anthropic` 直接作为 Anthropic provider 使用。\n- **灵活的认证与部署选项**：支持交互式登录、直接 token、个人 / Business / Enterprise、GitHub Enterprise、opencode OAuth 和自定义数据目录。\n- **多 provider 路由**：可暴露 `/:provider/...` 路由，也可在顶层 API 上使用 `model: \"provider/model\"`。\n\n## 前置要求\n\n- Bun（>= 1.2.x）\n- 如果要通过 `npx` 运行已发布 CLI，需要 Node.js\n- 只有在使用 GitHub Copilot provider 时，才需要已订阅 Copilot 的 GitHub 账号\n- 如果不使用 GitHub Copilot，需要至少一个已配置 provider 的 API key 或 OAuth 登录\n\n## 安装\n\n安装依赖：\n\n```sh\nbun install\n```\n\n直接从源码启动服务：\n\n```sh\nbun run start start\n```\n\n## 从源码运行\n\n本项目可以通过多种方式从源码运行：\n\n### 开发模式\n\n```sh\nbun run dev start\n```\n\n### 生产模式\n\n```sh\nbun run start start\n```\n\n## 通过 npx 使用\n\n你可以直接用 npx 运行本项目：\n\n> [!IMPORTANT]\n> 通过 `npx` 运行时，token usage 存储会使用 Node 内置的 `node:sqlite` 模块。该能力会在 Node.js >= 22.13.0 时启用；Node.js < 22.13.0 时 CLI 仍可启动，但会禁用 token usage 存储。\n>\n> 如果不升级 Node.js 但仍需要 token usage 存储，可以改用 Bun 运行已发布 CLI：`bunx --bun @jeffreycao/copilot-api@latest start`。\n\n```sh\nnpx @jeffreycao/copilot-api@latest start\n```\n\n带参数示例：\n\n```sh\nnpx @jeffreycao/copilot-api@latest start --port 8080\n```\n\n如果只想做认证或 provider 配置：\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth\n```\n\n如果要不依赖 GitHub Copilot 运行，先配置至少一个 provider，然后正常启动服务：\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth login --provider dashscope\nnpx @jeffreycao/copilot-api@latest start\n```\n\n## 配合 Docker 使用\n\n构建镜像：\n\n```sh\ndocker build -t copilot-api .\n```\n\n通过 bind mount 运行容器，让认证数据在重启后保留：\n\n```sh\nmkdir -p ./copilot-data\ndocker run -p 4141:4141 -v $(pwd)/copilot-data:/root/.local/share/copilot-api copilot-api\n```\n\n这会把宿主机上的 `./copilot-data` 映射到容器内的 `/root/.local/share/copilot-api`，用于持久化 GitHub 认证数据、provider 配置和其他 gateway 状态。\n\n也可以直接通过环境变量传入 GitHub token：\n\n```sh\ndocker run -p 4141:4141 -e GH_TOKEN=your_github_token_here copilot-api\n```\n\n## Electron 桌面应用\n\n如果你更喜欢图形界面，仓库里还提供了位于 `desktop/` 的 Electron 桌面应用。它支持 GitHub Copilot 登录、OpenAI Codex OAuth，以及 DeepSeek、DashScope、OpenRouter 或自定义 provider 的 API Key 配置。授权或配置 provider 后，可以一键启动或停止本地代理，并在界面里直接查看本地端点、鉴权 Header、可用模型、额度和日志。\n\n设置页还可以配置 `OAuth App`、`API Home`、`Enterprise URL`、详细日志以及最小化到托盘。桌面安装包发布在 GitHub Releases：\n\nhttps://github.com/caozhiyuan/copilot-api/releases\n\n下载对应平台的安装包后，在应用内授权或配置 provider，选择端口并启动服务，再把你的客户端指向应用里显示的本地端点即可。发布版桌面应用使用随包内置的 Electron 运行时，正常使用不需要额外安装 Node.js；token usage 历史记录会在该内置运行时支持 SQLite 时启用。\n\n桌面应用里的高级配置页会通过 `GET/POST /admin/config/model-mappings` 读写这份共享的模型映射。同一份映射会统一作用于 `POST /v1/messages`、`POST /v1/messages/count_tokens`、`POST /v1/responses` 和 `POST /v1/chat/completions`，不再按接口区分。它使用的是 `auth.adminApiKey`，不是普通的 `auth.apiKeys`；应用会在服务启动并自动生成该 key 后，直接从 `config.json` 读取它来发起请求。\n\n### 桌面应用截图\n\n下面展示了桌面应用中的首页、Token 用量统计页面：\n\n<p align=\"center\">\n  <img src=\"./docs/screenshots/desktop-dashboard.png\" alt=\"Copilot API 桌面应用首页\" width=\"49%\" />\n  <img src=\"./docs/screenshots/desktop-token-usage.png\" alt=\"Copilot API 桌面应用 Token 用量页\" width=\"49%\" />\n</p>\n\n## 与 Claude Code 一起使用\n\n这个 AI gateway 可以为 [Claude Code](https://docs.anthropic.com/en/claude-code) 提供后端能力。Claude Code 是 Anthropic 提供的实验性面向开发者的对话式 AI 助手。\n\n有两种方式可以把 Claude Code 配置为使用这个 AI gateway：\n\n### 通过 `--claude-code` 标志进行交互式配置\n\n执行带 `--claude-code` 的 `start` 命令开始：\n\n```sh\nnpx @jeffreycao/copilot-api@latest start --claude-code\n```\n\n你会被提示选择一个主模型，以及一个用于后台任务的 \"small, fast\" 模型。选择完成后，会有一条命令被复制到剪贴板中。该命令会设置 Claude Code 使用这个 AI gateway 所需的环境变量。\n\n在新的终端中粘贴并执行这条命令，即可启动 Claude Code。\n\n<a id=\"manual-configuration-with-settingsjson\"></a>\n\n### 通过 `settings.json` 手动配置\n\n另一种方式是在项目根目录中创建 `.claude/settings.json` 文件，并写入 Claude Code 所需的环境变量。这样你就不需要每次都运行交互式配置了。\n\n下面是一个 `.claude/settings.json` 示例：\n\n```json\n{\n  \"env\": {\n    \"ANTHROPIC_BASE_URL\": \"http://localhost:4141\",\n    \"ANTHROPIC_AUTH_TOKEN\": \"dummy\",\n    \"ANTHROPIC_MODEL\": \"deepseek/deepseek-v4-pro\",\n    \"ANTHROPIC_DEFAULT_SONNET_MODEL\": \"deepseek/deepseek-v4-pro\",\n    \"ANTHROPIC_DEFAULT_HAIKU_MODEL\": \"deepseek/deepseek-v4-flash\",\n    \"DISABLE_NON_ESSENTIAL_MODEL_CALLS\": \"1\",\n    \"CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC\": \"1\",\n    \"CLAUDE_CODE_ATTRIBUTION_HEADER\": \"0\",\n    \"CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION\": \"false\",\n    \"CLAUDE_CODE_DISABLE_TERMINAL_TITLE\": \"true\",\n    \"CLAUDE_CODE_ENABLE_AWAY_SUMMARY\": \"0\"\n  },\n  \"permissions\": {\n    \"deny\": [\n      \"mcp__ide__executeCode\"\n    ]\n  }\n}\n```\n\n- 请根据需要替换 `ANTHROPIC_MODEL`、`ANTHROPIC_DEFAULT_OPUS_MODEL`、`ANTHROPIC_DEFAULT_SONNET_MODEL` 和 `ANTHROPIC_DEFAULT_HAIKU_MODEL`。配置完成后，请安装 claude code 插件，见 [插件集成](#plugin-integrations)。\n- 将 `CLAUDE_CODE_ATTRIBUTION_HEADER` 设为 `0` 可以阻止 Claude Code 在 system prompt 中附加计费和版本信息，从而避免 prompt cache 失效。\n- 关闭 `CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION` 和 `CLAUDE_CODE_ENABLE_AWAY_SUMMARY` 可以避免不必要地消耗额度。\n- Claude Code WebSearch 已支持纯搜索请求。Copilot 路径请保持全局 `messageApiWebSearchModel` 指向 Responses-capable GPT 模型或 `provider/model` 别名；provider 路由请使用原生 Anthropic provider 或 `openai-responses` provider。只有在你明确想禁止这类流量时，才需要把 `WebSearch` 加到 `permissions.deny`。\n- 如果使用的不是 Claude 模型，请不要启用 `ENABLE_TOOL_SEARCH`。如果使用的是 Claude 模型，则可以启用 `ENABLE_TOOL_SEARCH`。当前 Claude Code 使用的是客户端 tool search 模式，在该模式下每次加载 defer tools 都需要额外请求一次。\n- `CLAUDE_CODE_AUTO_COMPACT_WINDOW`：设置用于自动压缩计算的上下文容量（以 token 为单位）。默认使用模型自身的上下文窗口：标准模型为 200K，扩展上下文模型为 1M。使用 1M 上下文模型（如 `claude-opus-4-6[1m]`）时，可设置一个较低的值（如 `500000`）将窗口视为 500K 用于压缩计算。该值受限于模型的实际上下文窗口上限。`CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` 会基于此值的百分比生效。设置此变量可将压缩阈值与状态栏的 `used_percentage` 解耦（后者始终使用模型的完整上下文窗口）。\n\n更多选项见：[Claude Code settings](https://docs.anthropic.com/en/docs/claude-code/settings#environment-variables)\n\n也可以参考 IDE 集成说明：[Add Claude Code to your IDE](https://docs.anthropic.com/en/docs/claude-code/ide-integrations)\n\n## 与 OpenCode 一起使用\n\nOpenCode 已经有直接的 GitHub Copilot provider。本节适用于你希望让 OpenCode 通过 `@ai-sdk/anthropic` 指向这个 AI gateway，并复用本 README 前面提到的 agent 行为时。\n\n### 最小配置\n\n使用 OpenCode OAuth app 启动 AI gateway：\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth --oauth-app=opencode\nnpx @jeffreycao/copilot-api@latest start\n```\n\n然后让 OpenCode 通过 `@ai-sdk/anthropic` 指向这个 AI gateway。\n\n示例 `~/.config/opencode/opencode.json`：\n\n```json\n{\n  \"$schema\": \"https://opencode.ai/config.json\",\n  \"provider\": {\n    \"local\": {\n      \"npm\": \"@ai-sdk/anthropic\",\n      \"name\": \"My Local\",\n      \"options\": {\n        \"baseURL\": \"http://localhost:4141/v1\",\n        \"apiKey\": \"dummy\"\n      },\n      \"models\": {\n        \"gpt-5.4\": {\n          \"name\": \"gpt-5.4\",\n          \"modalities\": {\n            \"input\": [\"text\", \"image\"],\n            \"output\": [\"text\"]\n          },\n          \"limit\": {\n            \"context\": 400000,\n            \"input\": 272000,\n            \"output\": 128000\n          }\n        },\n        \"claude-sonnet-4.6\": {\n          \"id\": \"claude-sonnet-4.6\",\n          \"name\": \"claude-sonnet-4.6\",\n          \"modalities\": {\n            \"input\": [\"text\", \"image\"],\n            \"output\": [\"text\"]\n          },\n          \"limit\": {\n            \"context\": 200000,\n            \"output\": 32000\n          },\n          \"options\": {\n            \"thinking\": {\n              \"type\": \"adaptive\"\n            },\n            \"effort\": \"max\"\n          }\n        }\n      }\n    }\n  }\n}\n```\n\n这些字段的重要性：\n\n- `npm: \"@ai-sdk/anthropic\"` 是关键。OpenCode 会以 Anthropic Messages 语义与这个 AI gateway 通信，而不是把一切扁平化为 OpenAI Chat Completions。\n- `options.baseURL` 应设为 `http://localhost:4141/v1`；Anthropic SDK 会自动补上 `/messages`、`/models` 和 `/messages/count_tokens`。\n- 如果你在此代理中启用了 `auth.apiKeys`，请把 `dummy` 替换为真实 key；否则任意占位值都可以。\n\n## 与 Codex 一起使用\n\n这个 AI gateway 也可以为 Codex 提供后端能力。\n\n### Codex `config.toml` 参考配置\n\n把以下 `[model_providers.copilot_api]` 段加入你的 Codex `~/.codex/config.toml`：\n\n```toml\nmodel_provider = \"copilot_api\"\nmodel_reasoning_summary = \"auto\"\nmodel_verbosity = \"medium\"\nmodel_context_window = 272000\nmodel_auto_compact_token_limit = 244800\n\n[model_providers.copilot_api]\nname = \"OpenAI\"\nbase_url = \"http://localhost:4141\"\nenv_key = \"GITHUB_COPILOT_API_KEY\"\nrequires_openai_auth = true\nsupports_websockets = false\nwire_api = \"responses\"\nrequest_max_retries = 3\nstream_max_retries = 1\nstream_idle_timeout_ms = 300000\n\n[features]\nremote_compaction_v2 = true\n\n[analytics]\nenabled = false\n```\n\n> [!NOTE]\n> 此配置仅限于 Codex 与 GitHub Copilot provider。`name` 一定要配置为 `\"OpenAI\"`。它可以缓解 Codex local compact 不命中缓存的问题。如果你开启了 `contextManagement.responses`（Responses API context management 压缩），通常不会走到 `remote_compaction_v2` 或者 local compact，但如果工具返回 tokens 过大，仍有可能触发。在 native Responses API 流量下启用前，请先确认客户端支持 context management compaction。\n\n## GPT Tool Search\n\n对于 `gpt-5.4+` 这类 GPT Responses 模型，这个 AI gateway 可以通过一个很小的 MCP bridge 暴露 Responses `tool_search`。Claude Code 和 opencode 都可以使用同一个 bridge，前提是客户端会加载 MCP server，并且 Anthropic Messages 流量会经过这个 AI gateway。\n\nGPT 模型不要设置 Claude Code 原生的 `ENABLE_TOOL_SEARCH`。这个开关启用的是 Claude Code 自己的客户端 tool search 模式，可能导致 deferred 工具定义不再转发给 AI gateway。这个 AI gateway 需要完整的工具定义，这样才能只保留那一小组常驻加载工具，其余工具统一转换为 Responses deferred namespace。\n\n如果你安装了 `tool-search@copilot-api-marketplace`，Claude Code 会自动带上这个 MCP bridge，可以跳过下面这段 Claude Code MCP 手动配置。\n\n请把 tool search bridge 加到 Claude Code 使用的 MCP 配置中：\n\n```json\n{\n  \"mcpServers\": {\n    \"tool_search\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@jeffreycao/copilot-api@latest\", \"mcp\"]\n    }\n  }\n}\n```\n\n请把 tool search bridge 加到 opencode 使用的 MCP 配置中：\n\n```json\n{\n  \"mcp\": {\n    \"tool_search\": {\n      \"type\": \"local\",\n      \"command\": [\"npx\", \"-y\", \"@jeffreycao/copilot-api@latest\", \"mcp\"]\n    }\n  }\n}\n```\n\n本地开发时可以将命令换成 `bun`，参数换成 `[\"run\", \"./src/main.ts\", \"mcp\"]`。\n\nAI gateway 内部现在会把 OpenAI Responses `tool_search` 配置成 client-executed 模式。deferred tools 仍然会作为可搜索 namespace 暴露给模型，但会明确要求模型直接返回下一步要加载的精确工具名列表。\n\n该 bridge 使用直接工具选择，不做 query 搜索。工具入参是 `names`，值为逗号分隔的精确 deferred 工具名，例如 `TaskList,TaskGet,mcp__fetch__fetch`。\n\n<a id=\"plugin-integrations\"></a>\n\n## 插件集成\n\n本项目为 Claude Code 和 opencode 提供了插件集成。\n\n#### Claude Code 插件集成（基于 marketplace）\n\nClaude Code 集成现在拆分为两个插件：\n\n- `agent-inject` 会在 `SubagentStart` 时注入 `__SUBAGENT_MARKER__...`，以便 AI gateway 推导 `x-initiator: agent`。\n- `tool-search` 会注册用于 GPT Responses deferred tool loading 的 `tool_search` MCP bridge。\n\n- 本仓库中的 marketplace catalog：`.claude-plugin/marketplace.json`\n- 本仓库中的插件源码：`plugin/claude/agent-inject`、`plugin/claude/tool-search`\n\n远程添加 marketplace：\n\n```sh\n/plugin marketplace add https://github.com/caozhiyuan/copilot-api.git\n```\n\n从 marketplace 安装插件：\n\n```sh\n/plugin install agent-inject@copilot-api-marketplace\n/plugin install tool-search@copilot-api-marketplace\n```\n\n安装后，`agent-inject` 会在 `SubagentStart` 时注入 `__SUBAGENT_MARKER__...`，AI gateway 会利用它推导 `x-initiator: agent`。\n\n`agent-inject` 还会注册一个 `UserPromptSubmit` hook，并返回 `{\"continue\": true}`；同时它也可以通过环境变量注入 `SessionStart` reminder 规则：\n\n- `CLAUDE_PLUGIN_ENABLE_QUESTION_RULES=1` 会自动为 Claude Code 启用两条关于使用 `question` 工具的提醒。你也可以把同样的提醒手动写进 `CLAUDE.md`；见 [CLAUDE.md 或 AGENTS.md 推荐内容](#claudemd-or-agentsmd-recommended-content)。\n- `CLAUDE_PLUGIN_ENABLE_NO_BACKGROUND_AGENTS_RULE=1` 会启用关于避免在 agent hooks 中使用 `run_in_background: true` 的提醒。\n\n`tool-search` 插件内置了 [GPT Tool Search](#gpt-tool-search) 一节描述的同一个 MCP bridge，因此安装该插件后，Claude Code 用户无需再手动配置 `tool_search` server。\n\n#### Opencode 插件\n\nsubagent 标记生成器被打包为一个 opencode 插件，位于 `plugin/opencode/subagent-marker.js`。\n\n**安装方式：**\n\n将插件文件复制到你的 opencode 插件目录：\n\n```sh\n# 克隆或下载本仓库后复制该插件\ncp plugin/opencode/subagent-marker.js ~/.config/opencode/plugins/\n```\n\n或者手动在 `~/.config/opencode/plugins/subagent-marker.js` 创建该文件，并填入插件内容。\n\n**功能：**\n\n- 跟踪 subagent 创建的子会话\n- 自动在 subagent 聊天消息前添加 marker system reminder（`__SUBAGENT_MARKER__...`）\n- 设置 `x-session-id` 请求头以跟踪会话\n- 让这个 AI gateway 能够把来自 subagent 的请求识别为 `x-initiator: agent`\n\n该插件会挂接到 `session.created`、`session.deleted`、`chat.message` 和 `chat.headers` 事件上，以无缝提供 subagent marker 能力。\n\n## 使用量查看器\n\n服务启动后，控制台会输出一个 Copilot 使用量看板 URL。这个看板是一个用于监控 API 用量的 Web 界面。\n\n1. 启动服务。例如使用 npx：\n   ```sh\n   npx @jeffreycao/copilot-api@latest start\n   ```\n2. 服务会输出一个 usage viewer 的 URL。将它复制到浏览器中打开，形式大致如下：\n   `http://localhost:4141/usage-viewer?endpoint=http://localhost:4141/usage`\n   - 如果你在 Windows 上使用 `start.bat` 脚本，这个页面会自动打开。\n\n看板提供了更易读的 Copilot 用量视图：\n\n> token usage 历史记录需要 Bun 或 Node.js >= 22.13.0。Node.js < 22.13.0 时服务会正常运行，但 token usage 存储会被禁用。\n\n- **API Endpoint URL**：通过 URL 查询参数指定 API endpoints，默认指向本地服务。支持手动切换为其他兼容 endpoints。\n- **x-api-key 认证**：如果启用了 API Key 认证，可填入 `x-api-key` 请求头。密钥会持久化保存在浏览器本地存储中。\n- **Period 选择器**：支持 Day / Week / Month 三种时间范围，切换时 URL 参数会自动同步，方便收藏和分享。\n- **Fetch Data**：点击 \"Refresh\" 按钮加载或刷新使用数据。页面加载时也会自动拉取数据。\n- **Copilot Quotas 额度**：通过进度条展示 Chat、Completions 等不同服务的额度使用情况，悬停可查看已用/剩余详情。\n- **Token Usage 指标卡片**：汇总当前周期的 Total、Input、Output、Cache Read、Cache Write、Requests 和预估费用。\n- **趋势图（Week / Month）**：提供按模型和指标筛选的折线趋势图，点击数据点可查看单日用量明细。\n- **Model Breakdown 表格**：按模型维度列出周期内的请求数、输入/输出/缓存 token 和预计费用。\n- **Request Events 分页列表**：按时间排序的请求事件记录，支持分页浏览，含时间戳、模型、请求 ID 和 token 用量。\n- **Detailed Information**：展示 API 返回的完整 JSON 响应，便于深入分析所有可用统计数据。\n- **URL-based Configuration**：也可通过 `endpoint` 和 `period` 查询参数直接指定 API 端点与时间范围。例如：\n  `http://localhost:4141/usage-viewer?endpoint=http://your-api-server/usage&period=week`\n\n### Usage Viewer 截图\n\n<p align=\"center\">\n  <img src=\"./docs/screenshots/usage-viewer.png\" alt=\"Copilot API Usage Viewer 页面\" width=\"900\" />\n</p>\n\n## 命令结构\n\nCopilot API 现在使用子命令结构，主要命令包括：\n\n- `start`：启动 AI gateway 服务。如果已有 GitHub token，则启用 Copilot 路径；如果没有 GitHub token，但存在至少一个启用中的 provider，则按 provider-only 模式启动；如果两者都没有，会引导你配置 provider。\n- `auth`：仅执行 provider 登录或配置流程，不启动服务。可用于 GitHub Copilot 登录、Codex OAuth，或第三方 provider API key 配置。\n- `debug`：显示诊断信息，包括版本、运行时详情、文件路径以及认证状态，便于排障与支持。\n\n## 命令行选项\n\n### 全局选项\n\n以下选项可用于任意子命令。若在子命令之前传入，请使用 `--key=value` 形式：\n\n| 选项 | 说明 | 默认值 | 别名 |\n| --- | --- | --- | --- |\n| --api-home | API home 目录路径（设置 `COPILOT_API_HOME`） | 无 | 无 |\n| --oauth-app | OAuth app 标识符（设置 `COPILOT_API_OAUTH_APP`） | 无 | 无 |\n| --enterprise-url | GitHub Enterprise URL（设置 `COPILOT_API_ENTERPRISE_URL`） | 无 | 无 |\n\n### Start 命令选项\n\n以下是 `start` 命令可用的命令行选项：\n\n| 选项 | 说明 | 默认值 | 别名 |\n| --- | --- | --- | --- |\n| --port | 监听端口 | 4141 | -p |\n| --verbose | 启用详细日志 | false | -v |\n| --github-token | 直接提供 GitHub token（必须通过 `auth` 子命令生成） | 无 | -g |\n| --claude-code | 生成一个使用 Copilot API 配置启动 Claude Code 的命令 | false | -c |\n| --show-token | 在获取和刷新时显示 GitHub 与 Copilot token | false | 无 |\n| --proxy-env | 从环境变量初始化代理 | false | 无 |\n\n### Auth 命令选项\n\n| 选项 | 说明 | 默认值 | 别名 |\n| --- | --- | --- | --- |\n| --provider | 要登录或配置的 provider（`copilot`、`codex`、`opencode-go`、`deepseek`、`dashscope`、`openrouter` 或 `custom`） | 交互选择 | 无 |\n| --verbose | 启用详细日志 | false | -v |\n| --show-token | 认证时显示 GitHub token | false | 无 |\n\n只有在需要启用 GitHub Copilot provider 时，才需要执行 `copilot-api auth login --provider copilot`。使用 `codex` 或第三方 provider-only 模式不要求配置 Copilot。\n\n使用 `copilot-api auth login --provider deepseek`、`--provider dashscope`、`--provider openrouter` 或 `--provider opencode-go` 可以通过 CLI 快速新增或更新这些常用第三方 provider。DeepSeek 会提示输入掩码显示的 `apiKey`、provider `type`（默认 `anthropic`），以及默认 `https://api.deepseek.com/anthropic` 的 `baseUrl`。DashScope 会提示输入掩码显示的 `apiKey`、provider `type`（默认 `openai-compatible`）和预填默认值的 `baseUrl`。OpenRouter 只提示输入掩码显示的 `apiKey` 和预填默认值的 `baseUrl`，并固定写入 `type: \"anthropic\"`。OpenCode Go 只提示输入掩码显示的 `apiKey` 和预填默认值的 `baseUrl`，并固定写入 `type: \"openai-compatible\"`（baseUrl `https://opencode.ai/zen/go`）。配置并启用 provider 后，`copilot-api start` 可在没有 GitHub token 的情况下启动。\n\n使用 `copilot-api auth login --provider custom` 可以通过 CLI 新增或更新其他第三方 provider。命令会依次提示输入 provider name、项目支持的 type（`anthropic`、`openai-compatible` 或 `openai-responses`）、`baseUrl`、掩码显示的 `apiKey` 和 `authType`；`authType` 可保持 type 默认值，也可选择 `x-api-key` / `authorization`。\n\n### Debug 命令选项\n\n| 选项 | 说明 | 默认值 | 别名 |\n| --- | --- | --- | --- |\n| --json | 以 JSON 输出调试信息 | false | 无 |\n\n<a id=\"configuration-configjson\"></a>\n\n## 配置（config.json）\n\n- **位置：** Linux/macOS 为 `~/.local/share/copilot-api/config.json`，Windows 为 `%USERPROFILE%\\.local\\share\\copilot-api\\config.json`。\n- **默认结构：**\n  ```json\n  {\n    \"auth\": {\n      \"apiKeys\": [],\n      \"adminApiKey\": \"<startup 自动生成>\"\n    },\n    \"providers\": {},\n    \"modelMappings\": {},\n    \"extraPrompts\": {\n      \"gpt-5-mini\": \"<built-in exploration prompt>\"\n    },\n    \"smallModel\": \"gpt-5-mini\",\n    \"contextManagement\": {\n      \"messages\": true,\n      \"responses\": false\n    },\n    \"modelResponsesApiCompactThresholds\": {\n      \"gpt-5.4\": 217600,\n      \"gpt-5.5\": 217600,\n      \"gpt-5.6-sol\": 231200,\n      \"gpt-5.6-terra\": 231200,\n      \"gpt-5.6-luna\": 231200\n    },\n    \"modelReasoningEfforts\": {\n      \"gpt-5-mini\": \"low\"\n    },\n    \"useMessagesApi\": true,\n    \"useResponsesApiWebSocket\": true,\n    \"useResponsesApiWebSearch\": true,\n    \"messageApiWebSearchModel\": \"gpt-5-mini\"\n  }\n  ```\n- **auth.apiKeys：** 用于普通非 admin 路由的 API key。支持多个 key 轮换使用。请求可通过 `x-api-key: <key>` 或 `Authorization: Bearer <key>` 进行认证。若为空或省略，则普通路由的认证会被禁用。\n- **auth.adminApiKey：** 仅用于 `/admin/*` 路由的单个 admin key。若未配置，服务会在启动时自动生成一个随机 key，并回写到 `config.json`。它同样使用 `x-api-key` 或 `Authorization: Bearer` 这两种头，但普通 `auth.apiKeys` 不能访问 `/admin/*`。\n- **modelMappings：** 用于顶层 `POST /v1/messages`、`POST /v1/messages/count_tokens`、`POST /v1/responses` 和 `POST /v1/chat/completions` 请求的精确 `sourceModel -> targetModel` 重写映射，这几类接口共用同一份规则。省略该字段或保留为 `{}` 时，不会做模型重写。`source` 和 `target` 都必须是非空字符串。`target` 可以是普通模型 ID，也可以是 `provider/model` 形式的别名，例如 `dashscope/qwen3.6-plus`；重写发生在 provider alias 解析之前。这些映射不再按接口区分。`GET/POST /admin/config/model-mappings` 管理接口读写的也只有这个字段。\n- **extraPrompts：** `model -> prompt` 的映射。把 Anthropic 风格请求翻译为 Responses API 时，会将其附加到第一条 system prompt 后面。你可以借此为不同模型注入护栏或指引。缺失的默认项会自动补齐，但不会覆盖你自定义的 prompt。对于 GPT-5.3+ 模型（如 `gpt-5.3-codex`、`gpt-5.4`、`gpt-5.5`），未显式配置时会自动使用内置的 commentary prompt。内置 prompt 会启用带阶段感知的 commentary，让模型在工具调用或更深层推理前先发出简短的用户可见进度说明。\n- **providers：** 全局上游 provider 映射。每个 provider key（例如 `dashscope`）都会变成一个路由前缀（`/dashscope/v1/messages`）。支持 `type: \"anthropic\"`、`type: \"openai-compatible\"` 和 `type: \"openai-responses\"`。顶层客户端也可以在 `/v1/messages`、`/v1/messages/count_tokens`、`/v1/responses` 和 `/v1/chat/completions` 中使用 `model: \"dashscope/model-id\"`；AI gateway 会在转发上游前移除 `dashscope/` 前缀。`openai-compatible` provider 同时支持 chat 和 Messages 流程：`/v1/chat/completions` 会直连上游 `/v1/chat/completions`，而 `/v1/messages` 和 `/:provider/v1/messages` 会先翻译为上游 Chat Completions，再把响应翻译回 Anthropic Messages。`GET /v1/models` 会聚合已启用 provider 的模型，并以 `provider/model-id` 形式返回；单个 provider 的原始模型列表仍可使用 `GET /dashscope/v1/models`。\n  - `enabled`：可选，若省略则默认为 `true`。\n  - `baseUrl`：provider API 的基础 URL，不要带结尾的 endpoint。Anthropic provider 不要带 `/v1/messages`；OpenAI 兼容 provider 不要带 `/v1/chat/completions`；OpenAI Responses provider 不要带 `/v1/responses`。\n  - `apiKey`：作为上游凭据值使用；普通 provider 必须配置。\n  - `authType`：可选，控制 `apiKey` 如何发送到上游。普通 provider 支持 `x-api-key` 和 `authorization`。Anthropic provider 默认 `x-api-key`；OpenAI 兼容和 OpenAI Responses provider 默认 `authorization`。当设置为 `authorization` 时，代理会发送 `Authorization: Bearer <apiKey>`。`oauth2` 仅保留给内置 `codex` provider，并由 `auth login --provider codex` 自动写入。\n  - `pricingCurrency`：可选，provider 维度的 token 费用币种，例如 `USD` 或 `CNY`。快捷 provider 默认 DashScope、DeepSeek 为 `CNY`，Codex/OpenRouter 为 `USD`。费用按币种分别汇总，不做汇率换算。\n  - `models`：可选，按模型 ID 配置的映射。每个键为请求中的模型名，值支持：\n    - `temperature`：可选，当请求未指定时使用的默认温度。\n    - `topP`：可选，当请求未指定时使用的默认 `top_p`。\n    - `topK`：可选，当请求未指定时使用的默认 `top_k`。\n    - `extraBody`：可选，按模型合入上游请求体的动态字段；请求体显式同名字段优先。OpenAI 兼容 provider 可用它配置 `enable_thinking`、`preserve_thinking`、`reasoning_effort` 等字段。`thinking_budget` 是 OpenAI 兼容 provider 的特殊覆盖项：配置在 `extraBody` 后，会在 Anthropic `thinking.budget_tokens` 翻译之后强制写入，并覆盖请求派生出的预算值。对于 provider name 为 `dashscope` 或 `baseUrl` 包含 `aliyuncs.com` 的 provider，请求派生的 `thinking_budget`（来自 Anthropic `thinking.budget_tokens`）会转发给上游；其他 OpenAI 兼容 provider 会移除请求派生的 `thinking_budget`，但 `extraBody` 中的 `thinking_budget` 仍然生效。对于 DashScope provider，当 `preserve_thinking` 未在 `extraBody` 或请求体中显式设置时，默认为 `true`。\n    - `pricing`：可选，按模型配置 token 单价，币种使用 provider 的 `pricingCurrency`，单位为每 100 万 tokens。支持 `input`、`output`、`cachedInput`（隐式缓存读）、`explicitCachedInput`（显式缓存读）和 `cacheCreationInput`。如需按输入 token 总量分档，可用带 `maxInputTokens` 的 `tiers`。\n    - `contextCache`：可选，provider name 为 `dashscope` 或 `baseUrl` 包含 `aliyuncs.com` 时默认 `true`，其他 OpenAI 兼容 provider 默认 `false`。用于启用阿里云百炼/DashScope 的显式缓存（explicit context cache），会按其 Context Cache 格式在最多 4 个 content block 上注入 `cache_control: { \"type\": \"ephemeral\" }`。缓存断点策略与 opencode 主链路保持一致：前 2 条 system 消息 + 最后 2 条非 system 消息。标记字符串 content 时会把 `system` / `user` / `assistant` / `tool` 消息转换为 text content part 数组；已有数组 content 则标记最后一个 part。如果模型本身已经支持隐式缓存，或上游不支持该显式缓存扩展字段，可在模型配置中设为 `false`。支持相同显式缓存扩展的非 DashScope provider 可设为 `true`。同时适用于 `/v1/messages` 和 `/v1/chat/completions` 路由。\n    - `supportPdf`：可选，控制该模型是否支持 PDF/document content。默认 `false`，不支持时会把 PDF 转成提示文本；设为 `true` 时会把 PDF/document 转成 OpenAI Chat Completions 的 file part。\n    - `toolContentSupportType`：可选，配置该模型的 tool result content 支持能力，值为 `array`、`image`、`pdf` 的数组。provider 侧未配置时默认只发送 string tool content。若 `supportPdf` 为 `true` 但这里不包含 `pdf`，tool result 里的 file part 会被转成 user role 消息。Copilot 主链路不使用这个 provider 默认，仍按 array + image 且不支持 PDF 的能力处理。\n    - `type`：可选，按模型覆盖 provider 的协议类型。支持 `anthropic`、`openai-compatible` 和 `openai-responses`。设置后，provider 的 `/v1/messages` 路由会使用该模型的 type 替代 provider 级别的 type 进行请求路由、认证头解析和上游端点选择。适用于 OpenCode Go 等上游对不同模型同时支持 OpenAI 兼容和 Anthropic Messages API 的 provider。覆盖 type 时，认证头按覆盖后 type 的默认值解析（Anthropic 默认 `x-api-key`；OpenAI 兼容/Responses 默认 `authorization`）。\n\n  DashScope 模型配置示例：\n  ```json\n  {\n    \"providers\": {\n      \"dashscope\": {\n        \"type\": \"openai-compatible\",\n        \"enabled\": true,\n        \"baseUrl\": \"https://dashscope.aliyuncs.com/compatible-mode\",\n        \"apiKey\": \"sk-your-dashscope-key\",\n        \"pricingCurrency\": \"CNY\",\n        \"models\": {\n          \"qwen3.7-plus\": {\n            \"temperature\": 1,\n            \"topP\": 0.95,\n            \"topK\": 20,\n            \"extraBody\": {\n              \"preserve_thinking\": true\n            }\n          },\n          \"glm-5.1\": {\n            \"temperature\": 0.7,\n            \"topP\": 0.95,\n            \"contextCache\": true,\n            \"pricing\": {\n              \"tiers\": [\n                {\n                  \"maxInputTokens\": 32000,\n                  \"input\": 6,\n                  \"cachedInput\": 1.2,\n                  \"explicitCachedInput\": 0.6,\n                  \"cacheCreationInput\": 7.5,\n                  \"output\": 24\n                },\n                {\n                  \"maxInputTokens\": 200000,\n                  \"input\": 8,\n                  \"cachedInput\": 1.6,\n                  \"explicitCachedInput\": 0.8,\n                  \"cacheCreationInput\": 10,\n                  \"output\": 28\n                }\n              ]\n            },\n            \"extraBody\": {\n              \"preserve_thinking\": true\n            }\n          }\n        }\n      }\n    }\n  }\n  ```\n  内置 token 价格覆盖 Codex GPT 模型（USD）、DashScope `qwen3.7-max`、`qwen3.7-plus`、`glm-5.1`、`glm-5.2`（CNY），DeepSeek `deepseek-v4-flash`、`deepseek-v4-pro`、`deepseek-chat`、`deepseek-reasoner`（CNY），以及 OpenCode Go 模型（`glm-5.2`、`deepseek-v4-flash`、`deepseek-v4-pro`、`kimi-k2.7-code`、`mimo-v2.5`、`mimo-v2.5-pro`、`qwen3.7-plus`、`qwen3.7-max`、`minimax-m2.5`、`minimax-m3`，USD）。用户配置的 `pricing` 优先于内置价格。DashScope 若上游 usage 中出现 `cache_creation_input_tokens` 字段，cached tokens 按显式缓存读价计费；否则 `cachedInput` 作为隐式缓存读价。DeepSeek 的 `prompt_cache_hit_tokens` 会归入 cached input，`prompt_cache_miss_tokens` 会归入普通 input。\n- **smallModel：** 无工具预热消息的回退模型（例如 Claude Code 的探测请求）；默认是 `gpt-5-mini`。\n- **contextManagement：** 控制代理是否为 Responses API 附加 `context_management` 压缩指令。`messages` 作用于被翻译成 Responses API 的 Anthropic 风格 `/v1/messages` 请求，包括 `openai-responses` provider 的 Messages 路由，默认值为 `true`。`responses` 作用于 native `/v1/responses` 流量，包括 `provider/model` 别名和内置 `codex` provider，默认值为 `false`。只有在确认客户端支持 context management compaction 后，才建议在 Responses API 下启用 `responses`。启用后，请求体会带上 `context_management`，并在后续轮次中仅保留最新的压缩承载内容。**注意：** 对于 GPT-5.6 及以上模型（如 `gpt-5.6-sol`、`gpt-5.6-terra`、`gpt-5.6-luna`），context management 功能会被强制禁用，因为开启后会破坏这些模型的 prompt 缓存命中。此强制覆盖优先于 `contextManagement` 和 `modelResponsesApiCompactThresholds` 配置。\n- **modelResponsesApiCompactThresholds：** 按模型覆盖 Responses API 的 `compact_threshold`，仅在代理自动附加 `context_management` 时使用。它的优先级高于 `resolveResponsesCompactThreshold` 基于 `max_prompt_tokens * ratio` 的兜底阈值。默认将 `gpt-5.4` 和 `gpt-5.5` 设为 `217600`（`272000 * 0.8`），将 `gpt-5.6-sol`、`gpt-5.6-terra`、`gpt-5.6-luna` 设为 `231200`（`272000 * 0.85`）。未列出的模型继续使用原有兜底逻辑。\n- **modelReasoningEfforts：** 按模型配置的推理强度，仅作用于 `/v1/messages` 请求。当请求走 Copilot 原生 Messages API 时设置 `output_config.effort`；当请求被翻译为 Responses API 时设置 `reasoning.effort`。可选值包括 `none`、`minimal`、`low`、`medium`、`high`、`xhigh` 和 `max`。若某模型未配置，则默认使用 `high`；GPT-5.3+ 模型未显式配置时回退为 `xhigh`。\n- **useMessagesApi：** 当为 `true` 时，支持 Copilot 原生 `/v1/messages` 的 Claude 系模型会走 Messages API；否则回退到 `/chat/completions`。设为 `false` 可禁用 Messages API 路由，始终使用 `/chat/completions`。默认值为 `true`。\n- **useResponsesApiWebSocket：** 当为 `true` 时，Responses API 请求会优先对声明了 `ws:/responses` 的模型使用 Copilot websocket transport；仅声明 `/responses` 的模型仍走 HTTP。设为 `false` 可禁用 websocket 路由，并在模型支持 `/responses` 时使用 HTTP `/responses`。默认值为 `true`。\n- **useResponsesApiWebSearch：** 当为 `true` 时，服务端会保留 Responses API 中 `type: \"web_search\"` 的工具并透传到上游。设为 `false` 则会从 `/responses` payload 中移除这些工具。默认值为 `true`。\n- **messageApiWebSearchModel：** 顶层 Copilot `/v1/messages` 请求只包含服务端 `web_search` 工具时使用的全局模型，默认值为 `gpt-5-mini`。如果该值是 `provider/model` 别名，请求会进入对应 provider 的 Messages API 路径，并在转发前移除 provider 前缀。对于 Copilot GPT 模型，web search 会通过 `/responses` 执行。混合 `web_search` 与自定义工具的场景暂不支持，服务端会移除 server-side `web_search`。\n- **claudeTokenMultiplier：** 用于 Claude `/v1/messages/count_tokens` 请求在本地走 GPT tokenizer 估算时的乘数。默认值为 `1.15`。如果你的客户端仍然过晚触发上下文压缩，可以适当调大。这个配置只会在代理本地估算 Claude token 时生效；如果已经配置 `anthropicApiKey` 且 Anthropic token counting 调用成功，则会直接返回 Anthropic 的精确计数，不会使用这个乘数。\n- **anthropicApiKey：** 用于把 Claude `/v1/messages/count_tokens` 请求转发到 Anthropic 真实 token counting 端点的 API key，这样会返回精确计数，而不是 GPT tokenizer 估算值。也可通过环境变量 `ANTHROPIC_API_KEY` 设置。若未配置，或上游调用失败，则回退到由 `claudeTokenMultiplier` 控制的本地 GPT tokenizer 估算。\n\n编辑此文件后即可自定义 prompts，或替换为你自己的快速模型。修改完成后请重启服务（或重新执行命令），让缓存中的配置刷新生效。\n\n## API 认证\n\n- **受保护的普通路由：** 当配置了 `auth.apiKeys` 且非空时，除 `/`、`/usage-viewer` 和 `/usage-viewer/` 以外的普通路由都需要认证。\n- **Admin 路由：** 所有 `/admin/*` 路由都要求 `auth.adminApiKey`。如果缺失，服务会在启动时自动生成并在开始提供服务前写回 `config.json`。\n- **允许的认证头：**\n  - `x-api-key: <your_key>`\n  - `Authorization: Bearer <your_key>`\n- **CORS 预检：** `OPTIONS` 请求始终允许。\n- **未配置普通 key 时：** 普通路由仍可直接访问；但这条规则不适用于 `/admin/*`，后者只接受 `auth.adminApiKey`。\n\n普通受保护路由的示例请求：\n\n```sh\ncurl http://localhost:4141/v1/models \\\n  -H \"x-api-key: your_api_key\"\n```\n\nAdmin 路由的示例请求：\n\n```sh\ncurl http://localhost:4141/admin/config/model-mappings \\\n  -H \"x-api-key: your_admin_api_key\"\n```\n\n## API 端点\n\n服务端提供多个 OpenAI / Anthropic 兼容端点。请求会根据所选模型和 `provider/model` 别名路由到 GitHub Copilot、内置 `codex` provider 或已配置的 provider。\n\n### OpenAI 兼容端点\n\n这些端点模拟 OpenAI API 结构。\n\n| 端点 | 方法 | 说明 |\n| --- | --- | --- |\n| `POST /v1/responses` | `POST` | OpenAI 中用于生成模型响应的高级接口。支持 `openai-responses` provider 的 `provider/model` 别名。 |\n| `POST /v1/chat/completions` | `POST` | 为给定聊天对话创建模型响应。支持 `openai-compatible` provider 的 `provider/model` 别名；目标 provider 已配置时可在没有 Copilot 的情况下使用。 |\n| `GET /v1/models` | `GET` | 列出 Copilot 模型以及已启用 provider 的 `provider/model-id` 模型。来自 Codex 客户端（`User-Agent` 以 `codex` 开头）的请求会转发到 Codex Models 上游。 |\n| `POST /v1/embeddings` | `POST` | 创建表示输入文本的向量嵌入。 |\n\n### Codex 后端代理端点\n\n| 端点 | 方法 | 说明 |\n| --- | --- | --- |\n| `POST /alpha/search` | `POST` | 将 JSON 请求体和查询参数透明转发到 Codex Alpha Search 上游。网关会使用当前 Codex 登录态覆盖客户端的 authorization 和 account header，透传 `accept`、`content-type`、`originator`、`user-agent`、`cookie` 等兼容 header，并原样返回上游状态码、响应头和响应体。 |\n\n### Anthropic 兼容端点\n\n这些端点设计为兼容 Anthropic Messages API。\n\n| 端点 | 方法 | 说明 |\n| --- | --- | --- |\n| `POST /v1/messages` | `POST` | 为给定对话创建模型响应。支持已配置 provider 的 `provider/model` 别名，包括通过 `openai-compatible` provider 做翻译。 |\n| `POST /v1/messages/count_tokens` | `POST` | 计算一组消息的 token 数。支持已配置 provider 的 `provider/model` 别名。 |\n| `POST /:provider/v1/messages` | `POST` | 将 Anthropic Messages 请求代理到已配置的 Anthropic provider，或翻译到 OpenAI 兼容 / OpenAI Responses provider。 |\n| `GET /:provider/v1/models` | `GET` | 将模型列表请求代理到已配置的 provider。 |\n| `POST /:provider/v1/messages/count_tokens` | `POST` | 为 provider 路由请求在本地计算 token 数。 |\n\n### 使用量监控端点\n\n用于监控 Copilot 用量与额度的新端点。\n\n| 端点 | 方法 | 说明 |\n| --- | --- | --- |\n| `GET /usage` | `GET` | 获取详细的 Copilot 使用统计与额度信息。 |\n| `GET /token` | `GET` | 获取当前 API 正在使用的 Copilot token。 |\n\n### Admin / 配置端点\n\n这些端点用于本地管理操作，只接受 `auth.adminApiKey`。\n\n| 端点 | 方法 | 说明 |\n| --- | --- | --- |\n| `GET /admin/config/model-mappings` | `GET` | 返回当前 `config.json` 路径以及生效中的 `modelMappings` 映射。 |\n| `POST /admin/config/model-mappings` | `POST` | 只更新 `config.json` 里的 `modelMappings` 字段，并回传更新后的结果。 |\n\n## 使用示例\n\n常用 `npx` 命令：\n\n```sh\n# 基础启动\nnpx @jeffreycao/copilot-api@latest start\n\n# 自定义端口并开启详细日志\nnpx @jeffreycao/copilot-api@latest start --port 8080 --verbose\n\n# 执行认证流程\nnpx @jeffreycao/copilot-api@latest auth login\n\n# 配置第三方 provider，然后不依赖 GitHub Copilot 启动\nnpx @jeffreycao/copilot-api@latest auth login --provider dashscope\nnpx @jeffreycao/copilot-api@latest start\n\n# 以 JSON 格式输出调试信息\nnpx @jeffreycao/copilot-api@latest debug --json\n\n# 用 Bun 而不是 Node.js 运行已发布 CLI\nbunx --bun @jeffreycao/copilot-api@latest start\n```\n\n配置 `dashscope` 后的 OpenAI 兼容 provider 调用示例：\n\n```sh\ncurl http://localhost:4141/v1/chat/completions \\\n  -H \"content-type: application/json\" \\\n  -d '{\"model\":\"dashscope/qwen3.6-plus\",\"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]}'\n\ncurl http://localhost:4141/dashscope/v1/messages \\\n  -H \"content-type: application/json\" \\\n  -d '{\"model\":\"qwen3.6-plus\",\"max_tokens\":1024,\"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]}'\n```\n\n## 使用建议\n\n<a id=\"claudemd-or-agentsmd-recommended-content\"></a>\n\n### CLAUDE.md 或 AGENTS.md 推荐内容\n\n如果你想手动加入这些提醒，请在 Claude Code 的 `CLAUDE.md`，或 opencode/codex 的 `AGENTS.md` 中加入以下内容：\n\n```\n- Prohibited from directly asking questions to users, MUST use question tool.\n- Once you can confirm that the task is complete, MUST use question tool to make user confirm. The user may respond with feedback if they are not satisfied with the result, which you can use to make improvements and try again, after try again, MUST use question tool to make user confirm again.\n```\n"}, "a23edf6fd0b46cf7f2ca2034954c4a6acf1ee408": {"t": 1785765563.9903946, "n": 31601, "h": "ea6a676d189805ed", "c": "# Copilot API Proxy\n\n[English](./README.md) | 简体中文\n\n## 重要说明\n\n> [!IMPORTANT]\n> **使用前请先注意以下几点：**\n>\n> 1. **Claude Code 配置：** 与 Claude Code 搭配使用时，请将模型 ID 配置为 `claude-opus-4-8`。示例 claude `settings.json` 见 [通过 `settings.json` 手动配置](#manual-configuration-with-settingsjson)。\n>\n> 2. **内置 `copilot`、`codex` 与第三方 provider：** 执行 `npx @jeffreycao/copilot-api@latest auth`，可选择 `copilot`、`codex`、`deepseek`、`custom` 等 provider。\n>\n> 3. **注意事项：** README 顶部移除的 GitHub Copilot warning 见 [GitHub Copilot 安全提示](./NOTICE.md#github-copilot-security-notice)。\n\n---\n\n## 项目概览\n\n这是一个小型 AI gateway，可以使用 GitHub Copilot、内置 `codex` provider，也可以使用 DashScope 等已配置的第三方 provider。GitHub Copilot 现在是可选能力：如果本地没有 GitHub token，只要至少配置了一个启用中的 provider，服务仍可按 provider-only 模式启动。\n\nAI gateway 会从同一个本地端点暴露 OpenAI / Anthropic 兼容 API，让 [Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview)、OpenCode、Codex 和 OpenAI 兼容客户端可以共用同一个本地服务。\n\n在 GitHub Copilot 路径上，AI gateway 会在可用时优先使用 Copilot 原生的 Anthropic 风格 Messages API，在重工具调用场景下保留更原生的 Claude 行为。\n\n## 功能特性\n\n- **OpenAI 与 Anthropic 双兼容**：通过 `/v1/responses`、`/v1/chat/completions`、`/v1/models`、`/v1/embeddings` 和 `/v1/messages` 对外暴露同一个本地 AI gateway。\n- **Copilot 可选**：有 GitHub 凭据时可以使用 GitHub Copilot，没有 GitHub 凭据时也可以只依赖已配置的 provider 运行。\n- **同一网关接入 Copilot、`codex` 与第三方 provider**：可统一路由 GitHub Copilot、内置 `codex` provider 和配置好的外部 provider。\n- **第三方 provider 可独立启动**：配置 DashScope、DeepSeek、OpenRouter 或自定义 provider 后，不需要 GitHub Copilot 登录即可启动 AI gateway。\n- **OpenAI 兼容 provider 同时支持 chat 和 Messages API**：`openai-compatible` provider 可通过顶层 `/v1/chat/completions` 搭配 `model: \"provider/model\"` 提供 Chat Completions，也可通过 `/v1/messages` 完成 Anthropic Messages 的请求/响应翻译。\n- **面向 Claude 的更原生 Copilot 路由**：优先使用原生 `/v1/messages`，保留 Claude 风格工具流，支持 Anthropic beta 能力、通过 Responses-capable 模型支持 Claude WebSearch，并保留 subagent / session 标记。\n- **Claude Code 与 OpenCode 集成**：兼容 Claude Code 与 OpenCode，也支持通过 `@ai-sdk/anthropic` 直接作为 Anthropic provider 使用。\n- **灵活的认证与部署选项**：支持交互式登录、直接 token、个人 / Business / Enterprise、GitHub Enterprise、opencode OAuth 和自定义数据目录。\n- **多 provider 路由**：可暴露 `/:provider/...` 路由，也可在顶层 API 上使用 `model: \"provider/model\"`。\n\n## 前置要求\n\n- Bun（>= 1.2.x）\n- 如果要通过 `npx` 运行已发布 CLI，需要 Node.js\n- 只有在使用 GitHub Copilot provider 时，才需要已订阅 Copilot 的 GitHub 账号\n- 如果不使用 GitHub Copilot，需要至少一个已配置 provider 的 API key 或 OAuth 登录\n\n## 安装\n\n安装依赖：\n\n```sh\nbun install\n```\n\n直接从源码启动服务：\n\n```sh\nbun run start start\n```\n\n## 从源码运行\n\n本项目可以通过多种方式从源码运行：\n\n### 开发模式\n\n```sh\nbun run dev start\n```\n\n### 生产模式\n\n```sh\nbun run start start\n```\n\n## 通过 npx 使用\n\n你可以直接用 npx 运行本项目：\n\n> [!IMPORTANT]\n> 通过 `npx` 运行时，token usage 存储会使用 Node 内置的 `node:sqlite` 模块。该能力会在 Node.js >= 22.13.0 时启用；Node.js < 22.13.0 时 CLI 仍可启动，但会禁用 token usage 存储。\n>\n> 如果不升级 Node.js 但仍需要 token usage 存储，可以改用 Bun 运行已发布 CLI：`bunx --bun @jeffreycao/copilot-api@latest start`。\n\n```sh\nnpx @jeffreycao/copilot-api@latest start\n```\n\n带参数示例：\n\n```sh\nnpx @jeffreycao/copilot-api@latest start --port 8080\n```\n\n如果只想做认证或 provider 配置：\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth\n```\n\n如果要不依赖 GitHub Copilot 运行，先配置至少一个 provider，然后正常启动服务：\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth login --provider dashscope\nnpx @jeffreycao/copilot-api@latest start\n```\n\n## 配合 Docker 使用\n\n构建镜像：\n\n```sh\ndocker build -t copilot-api .\n```\n\n通过 bind mount 运行容器，让认证数据在重启后保留：\n\n```sh\nmkdir -p ./copilot-data\ndocker run -p 4141:4141 -v $(pwd)/copilot-data:/root/.local/share/copilot-api copilot-api\n```\n\n这会把宿主机上的 `./copilot-data` 映射到容器内的 `/root/.local/share/copilot-api`，用于持久化 GitHub 认证数据、provider 配置和其他 gateway 状态。\n\n也可以直接通过环境变量传入 GitHub token：\n\n```sh\ndocker run -p 4141:4141 -e GH_TOKEN=your_github_token_here copilot-api\n```\n\n## Electron 桌面应用\n\n如果你更喜欢图形界面，仓库里还提供了位于 `desktop/` 的 Electron 桌面应用。它支持 GitHub Copilot 登录、OpenAI Codex OAuth，以及 DeepSeek、DashScope、OpenRouter 或自定义 provider 的 API Key 配置。授权或配置 provider 后，可以一键启动或停止本地代理，并在界面里直接查看本地端点、鉴权 Header、可用模型、额度和日志。\n\n设置页还可以配置 `OAuth App`、`API Home`、`Enterprise URL`、详细日志以及最小化到托盘。桌面安装包发布在 GitHub Releases：\n\nhttps://github.com/caozhiyuan/copilot-api/releases\n\n下载对应平台的安装包后，在应用内授权或配置 provider，选择端口并启动服务，再把你的客户端指向应用里显示的本地端点即可。发布版桌面应用使用随包内置的 Electron 运行时，正常使用不需要额外安装 Node.js；token usage 历史记录会在该内置运行时支持 SQLite 时启用。\n\n桌面应用里的高级配置页会通过 `GET/POST /admin/config/model-mappings` 读写这份共享的模型映射。同一份映射会统一作用于 `POST /v1/messages`、`POST /v1/messages/count_tokens`、`POST /v1/responses` 和 `POST /v1/chat/completions`，不再按接口区分。它使用的是 `auth.adminApiKey`，不是普通的 `auth.apiKeys`；应用会在服务启动并自动生成该 key 后，直接从 `config.json` 读取它来发起请求。\n\n### 桌面应用截图\n\n下面展示了桌面应用中的首页、Token 用量统计页面：\n\n<p align=\"center\">\n  <img src=\"./docs/screenshots/desktop-dashboard.png\" alt=\"Copilot API 桌面应用首页\" width=\"49%\" />\n  <img src=\"./docs/screenshots/desktop-token-usage.png\" alt=\"Copilot API 桌面应用 Token 用量页\" width=\"49%\" />\n</p>\n\n## 与 Claude Code 一起使用\n\n这个 AI gateway 可以为 [Claude Code](https://docs.anthropic.com/en/claude-code) 提供后端能力。Claude Code 是 Anthropic 提供的实验性面向开发者的对话式 AI 助手。\n\n有两种方式可以把 Claude Code 配置为使用这个 AI gateway：\n\n### 通过 `--claude-code` 标志进行交互式配置\n\n执行带 `--claude-code` 的 `start` 命令开始：\n\n```sh\nnpx @jeffreycao/copilot-api@latest start --claude-code\n```\n\n你会被提示选择一个主模型，以及一个用于后台任务的 \"small, fast\" 模型。选择完成后，会有一条命令被复制到剪贴板中。该命令会设置 Claude Code 使用这个 AI gateway 所需的环境变量。\n\n在新的终端中粘贴并执行这条命令，即可启动 Claude Code。\n\n<a id=\"manual-configuration-with-settingsjson\"></a>\n\n### 通过 `settings.json` 手动配置\n\n另一种方式是在项目根目录中创建 `.claude/settings.json` 文件，并写入 Claude Code 所需的环境变量。这样你就不需要每次都运行交互式配置了。\n\n下面是一个 `.claude/settings.json` 示例：\n\n```json\n{\n  \"env\": {\n    \"ANTHROPIC_BASE_URL\": \"http://localhost:4141\",\n    \"ANTHROPIC_AUTH_TOKEN\": \"dummy\",\n    \"ANTHROPIC_MODEL\": \"deepseek/deepseek-v4-pro\",\n    \"ANTHROPIC_DEFAULT_SONNET_MODEL\": \"deepseek/deepseek-v4-pro\",\n    \"ANTHROPIC_DEFAULT_HAIKU_MODEL\": \"deepseek/deepseek-v4-flash\",\n    \"DISABLE_NON_ESSENTIAL_MODEL_CALLS\": \"1\",\n    \"CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC\": \"1\",\n    \"CLAUDE_CODE_ATTRIBUTION_HEADER\": \"0\",\n    \"CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION\": \"false\",\n    \"CLAUDE_CODE_DISABLE_TERMINAL_TITLE\": \"true\",\n    \"CLAUDE_CODE_ENABLE_AWAY_SUMMARY\": \"0\"\n  },\n  \"permissions\": {\n    \"deny\": [\n      \"mcp__ide__executeCode\"\n    ]\n  }\n}\n```\n\n- 请根据需要替换 `ANTHROPIC_MODEL`、`ANTHROPIC_DEFAULT_OPUS_MODEL`、`ANTHROPIC_DEFAULT_SONNET_MODEL` 和 `ANTHROPIC_DEFAULT_HAIKU_MODEL`。配置完成后，请安装 claude code 插件，见 [插件集成](#plugin-integrations)。\n- 将 `CLAUDE_CODE_ATTRIBUTION_HEADER` 设为 `0` 可以阻止 Claude Code 在 system prompt 中附加计费和版本信息，从而避免 prompt cache 失效。\n- 关闭 `CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION` 和 `CLAUDE_CODE_ENABLE_AWAY_SUMMARY` 可以避免不必要地消耗额度。\n- Claude Code WebSearch 已支持纯搜索请求。Copilot 路径请保持全局 `messageApiWebSearchModel` 指向 Responses-capable GPT 模型或 `provider/model` 别名；provider 路由请使用原生 Anthropic provider 或 `openai-responses` provider。只有在你明确想禁止这类流量时，才需要把 `WebSearch` 加到 `permissions.deny`。\n- 如果使用的不是 Claude 模型，请不要启用 `ENABLE_TOOL_SEARCH`。如果使用的是 Claude 模型，则可以启用 `ENABLE_TOOL_SEARCH`。当前 Claude Code 使用的是客户端 tool search 模式，在该模式下每次加载 defer tools 都需要额外请求一次。\n- `CLAUDE_CODE_AUTO_COMPACT_WINDOW`：设置用于自动压缩计算的上下文容量（以 token 为单位）。默认使用模型自身的上下文窗口：标准模型为 200K，扩展上下文模型为 1M。使用 1M 上下文模型（如 `claude-opus-4-6[1m]`）时，可设置一个较低的值（如 `500000`）将窗口视为 500K 用于压缩计算。该值受限于模型的实际上下文窗口上限。`CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` 会基于此值的百分比生效。设置此变量可将压缩阈值与状态栏的 `used_percentage` 解耦（后者始终使用模型的完整上下文窗口）。\n\n更多选项见：[Claude Code settings](https://docs.anthropic.com/en/docs/claude-code/settings#environment-variables)\n\n也可以参考 IDE 集成说明：[Add Claude Code to your IDE](https://docs.anthropic.com/en/docs/claude-code/ide-integrations)\n\n## 与 OpenCode 一起使用\n\nOpenCode 已经有直接的 GitHub Copilot provider。本节适用于你希望让 OpenCode 通过 `@ai-sdk/anthropic` 指向这个 AI gateway，并复用本 README 前面提到的 agent 行为时。\n\n### 最小配置\n\n使用 OpenCode OAuth app 启动 AI gateway：\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth --oauth-app=opencode\nnpx @jeffreycao/copilot-api@latest start\n```\n\n然后让 OpenCode 通过 `@ai-sdk/anthropic` 指向这个 AI gateway。\n\n示例 `~/.config/opencode/opencode.json`：\n\n```json\n{\n  \"$schema\": \"https://opencode.ai/config.json\",\n  \"provider\": {\n    \"local\": {\n      \"npm\": \"@ai-sdk/anthropic\",\n      \"name\": \"My Local\",\n      \"options\": {\n        \"baseURL\": \"http://localhost:4141/v1\",\n        \"apiKey\": \"dummy\"\n      },\n      \"models\": {\n        \"gpt-5.4\": {\n          \"name\": \"gpt-5.4\",\n          \"modalities\": {\n            \"input\": [\"text\", \"image\"],\n            \"output\": [\"text\"]\n          },\n          \"limit\": {\n            \"context\": 400000,\n            \"input\": 272000,\n            \"output\": 128000\n          }\n        },\n        \"claude-sonnet-4.6\": {\n          \"id\": \"claude-sonnet-4.6\",\n          \"name\": \"claude-sonnet-4.6\",\n          \"modalities\": {\n            \"input\": [\"text\", \"image\"],\n            \"output\": [\"text\"]\n          },\n          \"limit\": {\n            \"context\": 200000,\n            \"output\": 32000\n          },\n          \"options\": {\n            \"thinking\": {\n              \"type\": \"adaptive\"\n            },\n            \"effort\": \"max\"\n          }\n        }\n      }\n    }\n  }\n}\n```\n\n这些字段的重要性：\n\n- `npm: \"@ai-sdk/anthropic\"` 是关键。OpenCode 会以 Anthropic Messages 语义与这个 AI gateway 通信，而不是把一切扁平化为 OpenAI Chat Completions。\n- `options.baseURL` 应设为 `http://localhost:4141/v1`；Anthropic SDK 会自动补上 `/messages`、`/models` 和 `/messages/count_tokens`。\n- 如果你在此代理中启用了 `auth.apiKeys`，请把 `dummy` 替换为真实 key；否则任意占位值都可以。\n\n## 与 Codex 一起使用\n\n这个 AI gateway 也可以为 Codex 提供后端能力。\n\n### Codex `config.toml` 参考配置\n\n把以下 `[model_providers.copilot_api]` 段加入你的 Codex `~/.codex/config.toml`：\n\n```toml\nmodel_provider = \"copilot_api\"\nmodel_reasoning_summary = \"auto\"\nmodel_verbosity = \"medium\"\nmodel_context_window = 272000\nmodel_auto_compact_token_limit = 244800\n\n[model_providers.copilot_api]\nname = \"OpenAI\"\nbase_url = \"http://localhost:4141\"\nenv_key = \"GITHUB_COPILOT_API_KEY\"\nrequires_openai_auth = true\nsupports_websockets = false\nwire_api = \"responses\"\nrequest_max_retries = 3\nstream_max_retries = 1\nstream_idle_timeout_ms = 300000\n\n[features]\nremote_compaction_v2 = true\n\n[analytics]\nenabled = false\n```\n\n> [!NOTE]\n> 此配置仅限于 Codex 与 GitHub Copilot provider。`name` 一定要配置为 `\"OpenAI\"`。它可以缓解 Codex local compact 不命中缓存的问题。如果你开启了 `contextManagement.responses`（Responses API context management 压缩），通常不会走到 `remote_compaction_v2` 或者 local compact，但如果工具返回 tokens 过大，仍有可能触发。在 native Responses API 流量下启用前，请先确认客户端支持 context management compaction。\n\n## GPT Tool Search\n\n对于 `gpt-5.4+` 这类 GPT Responses 模型，这个 AI gateway 可以通过一个很小的 MCP bridge 暴露 Responses `tool_search`。Claude Code 和 opencode 都可以使用同一个 bridge，前提是客户端会加载 MCP server，并且 Anthropic Messages 流量会经过这个 AI gateway。\n\nGPT 模型不要设置 Claude Code 原生的 `ENABLE_TOOL_SEARCH`。这个开关启用的是 Claude Code 自己的客户端 tool search 模式，可能导致 deferred 工具定义不再转发给 AI gateway。这个 AI gateway 需要完整的工具定义，这样才能只保留那一小组常驻加载工具，其余工具统一转换为 Responses deferred namespace。\n\n如果你安装了 `tool-search@copilot-api-marketplace`，Claude Code 会自动带上这个 MCP bridge，可以跳过下面这段 Claude Code MCP 手动配置。\n\n请把 tool search bridge 加到 Claude Code 使用的 MCP 配置中：\n\n```json\n{\n  \"mcpServers\": {\n    \"tool_search\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@jeffreycao/copilot-api@latest\", \"mcp\"]\n    }\n  }\n}\n```\n\n请把 tool search bridge 加到 opencode 使用的 MCP 配置中：\n\n```json\n{\n  \"mcp\": {\n    \"tool_search\": {\n      \"type\": \"local\",\n      \"command\": [\"npx\", \"-y\", \"@jeffreycao/copilot-api@latest\", \"mcp\"]\n    }\n  }\n}\n```\n\n本地开发时可以将命令换成 `bun`，参数换成 `[\"run\", \"./src/main.ts\", \"mcp\"]`。\n\nAI gateway 内部现在会把 OpenAI Responses `tool_search` 配置成 client-executed 模式。deferred tools 仍然会作为可搜索 namespace 暴露给模型，但会明确要求模型直接返回下一步要加载的精确工具名列表。\n\n该 bridge 使用直接工具选择，不做 query 搜索。工具入参是 `names`，值为逗号分隔的精确 deferred 工具名，例如 `TaskList,TaskGet,mcp__fetch__fetch`。\n\n<a id=\"plugin-integrations\"></a>\n\n## 插件集成\n\n本项目为 Claude Code 和 opencode 提供了插件集成。\n\n#### Claude Code 插件集成（基于 marketplace）\n\nClaude Code 集成现在拆分为两个插件：\n\n- `agent-inject` 会在 `SubagentStart` 时注入 `__SUBAGENT_MARKER__...`，以便 AI gateway 推导 `x-initiator: agent`。\n- `tool-search` 会注册用于 GPT Responses deferred tool loading 的 `tool_search` MCP bridge。\n\n- 本仓库中的 marketplace catalog：`.claude-plugin/marketplace.json`\n- 本仓库中的插件源码：`plugin/claude/agent-inject`、`plugin/claude/tool-search`\n\n远程添加 marketplace：\n\n```sh\n/plugin marketplace add https://github.com/caozhiyuan/copilot-api.git\n```\n\n从 marketplace 安装插件：\n\n```sh\n/plugin install agent-inject@copilot-api-marketplace\n/plugin install tool-search@copilot-api-marketplace\n```\n\n安装后，`agent-inject` 会在 `SubagentStart` 时注入 `__SUBAGENT_MARKER__...`，AI gateway 会利用它推导 `x-initiator: agent`。\n\n`agent-inject` 还会注册一个 `UserPromptSubmit` hook，并返回 `{\"continue\": true}`；同时它也可以通过环境变量注入 `SessionStart` reminder 规则：\n\n- `CLAUDE_PLUGIN_ENABLE_QUESTION_RULES=1` 会自动为 Claude Code 启用两条关于使用 `question` 工具的提醒。你也可以把同样的提醒手动写进 `CLAUDE.md`；见 [CLAUDE.md 或 AGENTS.md 推荐内容](#claudemd-or-agentsmd-recommended-content)。\n- `CLAUDE_PLUGIN_ENABLE_NO_BACKGROUND_AGENTS_RULE=1` 会启用关于避免在 agent hooks 中使用 `run_in_background: true` 的提醒。\n\n`tool-search` 插件内置了 [GPT Tool Search](#gpt-tool-search) 一节描述的同一个 MCP bridge，因此安装该插件后，Claude Code 用户无需再手动配置 `tool_search` server。\n\n#### Opencode 插件\n\nsubagent 标记生成器被打包为一个 opencode 插件，位于 `plugin/opencode/subagent-marker.js`。\n\n**安装方式：**\n\n将插件文件复制到你的 opencode 插件目录：\n\n```sh\n# 克隆或下载本仓库后复制该插件\ncp plugin/opencode/subagent-marker.js ~/.config/opencode/plugins/\n```\n\n或者手动在 `~/.config/opencode/plugins/subagent-marker.js` 创建该文件，并填入插件内容。\n\n**功能：**\n\n- 跟踪 subagent 创建的子会话\n- 自动在 subagent 聊天消息前添加 marker system reminder（`__SUBAGENT_MARKER__...`）\n- 设置 `x-session-id` 请求头以跟踪会话\n- 让这个 AI gateway 能够把来自 subagent 的请求识别为 `x-initiator: agent`\n\n该插件会挂接到 `session.created`、`session.deleted`、`chat.message` 和 `chat.headers` 事件上，以无缝提供 subagent marker 能力。\n\n## 使用量查看器\n\n服务启动后，控制台会输出一个 Copilot 使用量看板 URL。这个看板是一个用于监控 API 用量的 Web 界面。\n\n1. 启动服务。例如使用 npx：\n   ```sh\n   npx @jeffreycao/copilot-api@latest start\n   ```\n2. 服务会输出一个 usage viewer 的 URL。将它复制到浏览器中打开，形式大致如下：\n   `http://localhost:4141/usage-viewer?endpoint=http://localhost:4141/usage`\n   - 如果你在 Windows 上使用 `start.bat` 脚本，这个页面会自动打开。\n\n看板提供了更易读的 Copilot 用量视图：\n\n> token usage 历史记录需要 Bun 或 Node.js >= 22.13.0。Node.js < 22.13.0 时服务会正常运行，但 token usage 存储会被禁用。\n\n- **API Endpoint URL**：通过 URL 查询参数指定 API endpoints，默认指向本地服务。支持手动切换为其他兼容 endpoints。\n- **x-api-key 认证**：如果启用了 API Key 认证，可填入 `x-api-key` 请求头。密钥会持久化保存在浏览器本地存储中。\n- **Period 选择器**：支持 Day / Week / Month 三种时间范围，切换时 URL 参数会自动同步，方便收藏和分享。\n- **Fetch Data**：点击 \"Refresh\" 按钮加载或刷新使用数据。页面加载时也会自动拉取数据。\n- **Copilot Quotas 额度**：通过进度条展示 Chat、Completions 等不同服务的额度使用情况，悬停可查看已用/剩余详情。\n- **Token Usage 指标卡片**：汇总当前周期的 Total、Input、Output、Cache Read、Cache Write、Requests 和预估费用。\n- **趋势图（Week / Month）**：提供按模型和指标筛选的折线趋势图，点击数据点可查看单日用量明细。\n- **Model Breakdown 表格**：按模型维度列出周期内的请求数、输入/输出/缓存 token 和预计费用。\n- **Request Events 分页列表**：按时间排序的请求事件记录，支持分页浏览，含时间戳、模型、请求 ID 和 token 用量。\n- **Detailed Information**：展示 API 返回的完整 JSON 响应，便于深入分析所有可用统计数据。\n- **URL-based Configuration**：也可通过 `endpoint` 和 `period` 查询参数直接指定 API 端点与时间范围。例如：\n  `http://localhost:4141/usage-viewer?endpoint=http://your-api-server/usage&period=week`\n\n### Usage Viewer 截图\n\n<p align=\"center\">\n  <img src=\"./docs/screenshots/usage-viewer.png\" alt=\"Copilot API Usage Viewer 页面\" width=\"900\" />\n</p>\n\n## 命令结构\n\nCopilot API 现在使用子命令结构，主要命令包括：\n\n- `start`：启动 AI gateway 服务。如果已有 GitHub token，则启用 Copilot 路径；如果没有 GitHub token，但存在至少一个启用中的 provider，则按 provider-only 模式启动；如果两者都没有，会引导你配置 provider。\n- `auth`：仅执行 provider 登录或配置流程，不启动服务。可用于 GitHub Copilot 登录、Codex OAuth，或第三方 provider API key 配置。\n- `debug`：显示诊断信息，包括版本、运行时详情、文件路径以及认证状态，便于排障与支持。\n\n## 命令行选项\n\n### 全局选项\n\n以下选项可用于任意子命令。若在子命令之前传入，请使用 `--key=value` 形式：\n\n| 选项 | 说明 | 默认值 | 别名 |\n| --- | --- | --- | --- |\n| --api-home | API home 目录路径（设置 `COPILOT_API_HOME`） | 无 | 无 |\n| --oauth-app | OAuth app 标识符（设置 `COPILOT_API_OAUTH_APP`） | 无 | 无 |\n| --enterprise-url | GitHub Enterprise URL（设置 `COPILOT_API_ENTERPRISE_URL`） | 无 | 无 |\n\n### Start 命令选项\n\n以下是 `start` 命令可用的命令行选项：\n\n| 选项 | 说明 | 默认值 | 别名 |\n| --- | --- | --- | --- |\n| --port | 监听端口 | 4141 | -p |\n| --verbose | 启用详细日志 | false | -v |\n| --github-token | 直接提供 GitHub token（必须通过 `auth` 子命令生成） | 无 | -g |\n| --claude-code | 生成一个使用 Copilot API 配置启动 Claude Code 的命令 | false | -c |\n| --show-token | 在获取和刷新时显示 GitHub 与 Copilot token | false | 无 |\n| --proxy-env | 从环境变量初始化代理 | false | 无 |\n\n### Auth 命令选项\n\n| 选项 | 说明 | 默认值 | 别名 |\n| --- | --- | --- | --- |\n| --provider | 要登录或配置的 provider（`copilot`、`codex`、`opencode-go`、`deepseek`、`dashscope`、`openrouter` 或 `custom`） | 交互选择 | 无 |\n| --verbose | 启用详细日志 | false | -v |\n| --show-token | 认证时显示 GitHub token | false | 无 |\n\n只有在需要启用 GitHub Copilot provider 时，才需要执行 `copilot-api auth login --provider copilot`。使用 `codex` 或第三方 provider-only 模式不要求配置 Copilot。\n\n使用 `copilot-api auth login --provider deepseek`、`--provider dashscope`、`--provider openrouter` 或 `--provider opencode-go` 可以通过 CLI 快速新增或更新这些常用第三方 provider。DeepSeek 会提示输入掩码显示的 `apiKey`、provider `type`（默认 `anthropic`），以及默认 `https://api.deepseek.com/anthropic` 的 `baseUrl`。DashScope 会提示输入掩码显示的 `apiKey`、provider `type`（默认 `openai-compatible`）和预填默认值的 `baseUrl`。OpenRouter 只提示输入掩码显示的 `apiKey` 和预填默认值的 `baseUrl`，并固定写入 `type: \"anthropic\"`。OpenCode Go 只提示输入掩码显示的 `apiKey` 和预填默认值的 `baseUrl`，并固定写入 `type: \"openai-compatible\"`（baseUrl `https://opencode.ai/zen/go`）。配置并启用 provider 后，`copilot-api start` 可在没有 GitHub token 的情况下启动。\n\n使用 `copilot-api auth login --provider custom` 可以通过 CLI 新增或更新其他第三方 provider。命令会依次提示输入 provider name、项目支持的 type（`anthropic`、`openai-compatible` 或 `openai-responses`）、`baseUrl`、掩码显示的 `apiKey` 和 `authType`；`authType` 可保持 type 默认值，也可选择 `x-api-key` / `authorization`。\n\n### Debug 命令选项\n\n| 选项 | 说明 | 默认值 | 别名 |\n| --- | --- | --- | --- |\n| --json | 以 JSON 输出调试信息 | false | 无 |\n\n<a id=\"configuration-configjson\"></a>\n\n## 配置（config.json）\n\n- **位置：** Linux/macOS 为 `~/.local/share/copilot-api/config.json`，Windows 为 `%USERPROFILE%\\.local\\share\\copilot-api\\config.json`。\n- **默认结构：**\n  ```json\n  {\n    \"auth\": {\n      \"apiKeys\": [],\n      \"adminApiKey\": \"<startup 自动生成>\"\n    },\n    \"providers\": {},\n    \"modelMappings\": {},\n    \"extraPrompts\": {\n      \"gpt-5-mini\": \"<built-in exploration prompt>\"\n    },\n    \"smallModel\": \"gpt-5-mini\",\n    \"contextManagement\": {\n      \"messages\": true,\n      \"responses\": false\n    },\n    \"modelResponsesApiCompactThresholds\": {\n      \"gpt-5.4\": 217600,\n      \"gpt-5.5\": 217600,\n      \"gpt-5.6-sol\": 231200,\n      \"gpt-5.6-terra\": 231200,\n      \"gpt-5.6-luna\": 231200\n    },\n    \"modelReasoningEfforts\": {\n      \"gpt-5-mini\": \"low\"\n    },\n    \"useMessagesApi\": true,\n    \"useResponsesApiWebSocket\": true,\n    \"useResponsesApiWebSearch\": true,\n    \"messageApiWebSearchModel\": \"gpt-5-mini\"\n  }\n  ```\n- **auth.apiKeys：** 用于普通非 admin 路由的 API key。支持多个 key 轮换使用。请求可通过 `x-api-key: <key>` 或 `Authorization: Bearer <key>` 进行认证。若为空或省略，则普通路由的认证会被禁用。\n- **auth.adminApiKey：** 仅用于 `/admin/*` 路由的单个 admin key。若未配置，服务会在启动时自动生成一个随机 key，并回写到 `config.json`。它同样使用 `x-api-key` 或 `Authorization: Bearer` 这两种头，但普通 `auth.apiKeys` 不能访问 `/admin/*`。\n- **modelMappings：** 用于顶层 `POST /v1/messages`、`POST /v1/messages/count_tokens`、`POST /v1/responses` 和 `POST /v1/chat/completions` 请求的精确 `sourceModel -> targetModel` 重写映射，这几类接口共用同一份规则。省略该字段或保留为 `{}` 时，不会做模型重写。`source` 和 `target` 都必须是非空字符串。`target` 可以是普通模型 ID，也可以是 `provider/model` 形式的别名，例如 `dashscope/qwen3.6-plus`；重写发生在 provider alias 解析之前。这些映射不再按接口区分。`GET/POST /admin/config/model-mappings` 管理接口读写的也只有这个字段。\n- **extraPrompts：** `model -> prompt` 的映射。把 Anthropic 风格请求翻译为 Responses API 时，会将其附加到第一条 system prompt 后面。你可以借此为不同模型注入护栏或指引。缺失的默认项会自动补齐，但不会覆盖你自定义的 prompt。对于 GPT-5.3+ 模型（如 `gpt-5.3-codex`、`gpt-5.4`、`gpt-5.5`），未显式配置时会自动使用内置的 commentary prompt。内置 prompt 会启用带阶段感知的 commentary，让模型在工具调用或更深层推理前先发出简短的用户可见进度说明。\n- **providers：** 全局上游 provider 映射。每个 provider key（例如 `dashscope`）都会变成一个路由前缀（`/dashscope/v1/messages`）。支持 `type: \"anthropic\"`、`type: \"openai-compatible\"` 和 `type: \"openai-responses\"`。顶层客户端也可以在 `/v1/messages`、`/v1/messages/count_tokens`、`/v1/responses` 和 `/v1/chat/completions` 中使用 `model: \"dashscope/model-id\"`；AI gateway 会在转发上游前移除 `dashscope/` 前缀。`openai-compatible` provider 同时支持 chat 和 Messages 流程：`/v1/chat/completions` 会直连上游 `/v1/chat/completions`，而 `/v1/messages` 和 `/:provider/v1/messages` 会先翻译为上游 Chat Completions，再把响应翻译回 Anthropic Messages。`GET /v1/models` 会聚合已启用 provider 的模型，并以 `provider/model-id` 形式返回；单个 provider 的原始模型列表仍可使用 `GET /dashscope/v1/models`。\n  - `enabled`：可选，若省略则默认为 `true`。\n  - `baseUrl`：provider API 的基础 URL，不要带结尾的 endpoint。Anthropic provider 不要带 `/v1/messages`；OpenAI 兼容 provider 不要带 `/v1/chat/completions`；OpenAI Responses provider 不要带 `/v1/responses`。\n  - `apiKey`：作为上游凭据值使用；普通 provider 必须配置。\n  - `authType`：可选，控制 `apiKey` 如何发送到上游。普通 provider 支持 `x-api-key` 和 `authorization`。Anthropic provider 默认 `x-api-key`；OpenAI 兼容和 OpenAI Responses provider 默认 `authorization`。当设置为 `authorization` 时，代理会发送 `Authorization: Bearer <apiKey>`。`oauth2` 仅保留给内置 `codex` provider，并由 `auth login --provider codex` 自动写入。\n  - `pricingCurrency`：可选，provider 维度的 token 费用币种，例如 `USD` 或 `CNY`。快捷 provider 默认 DashScope、DeepSeek 为 `CNY`，Codex/OpenRouter 为 `USD`。费用按币种分别汇总，不做汇率换算。\n  - `models`：可选，按模型 ID 配置的映射。每个键为请求中的模型名，值支持：\n    - `temperature`：可选，当请求未指定时使用的默认温度。\n    - `topP`：可选，当请求未指定时使用的默认 `top_p`。\n    - `topK`：可选，当请求未指定时使用的默认 `top_k`。\n    - `extraBody`：可选，按模型合入上游请求体的动态字段；请求体显式同名字段优先。OpenAI 兼容 provider 可用它配置 `enable_thinking`、`preserve_thinking`、`reasoning_effort` 等字段。`thinking_budget` 是 OpenAI 兼容 provider 的特殊覆盖项：配置在 `extraBody` 后，会在 Anthropic `thinking.budget_tokens` 翻译之后强制写入，并覆盖请求派生出的预算值。对于 provider name 为 `dashscope` 或 `baseUrl` 包含 `aliyuncs.com` 的 provider，请求派生的 `thinking_budget`（来自 Anthropic `thinking.budget_tokens`）会转发给上游；其他 OpenAI 兼容 provider 会移除请求派生的 `thinking_budget`，但 `extraBody` 中的 `thinking_budget` 仍然生效。对于 DashScope provider，当 `preserve_thinking` 未在 `extraBody` 或请求体中显式设置时，默认为 `true`。\n    - `pricing`：可选，按模型配置 token 单价，币种使用 provider 的 `pricingCurrency`，单位为每 100 万 tokens。支持 `input`、`output`、`cachedInput`（隐式缓存读）、`explicitCachedInput`（显式缓存读）和 `cacheCreationInput`。如需按输入 token 总量分档，可用带 `maxInputTokens` 的 `tiers`。\n    - `contextCache`：可选，provider name 为 `dashscope` 或 `baseUrl` 包含 `aliyuncs.com` 时默认 `true`，其他 OpenAI 兼容 provider 默认 `false`。用于启用阿里云百炼/DashScope 的显式缓存（explicit context cache），会按其 Context Cache 格式在最多 4 个 content block 上注入 `cache_control: { \"type\": \"ephemeral\" }`。缓存断点策略与 opencode 主链路保持一致：前 2 条 system 消息 + 最后 2 条非 system 消息。标记字符串 content 时会把 `system` / `user` / `assistant` / `tool` 消息转换为 text content part 数组；已有数组 content 则标记最后一个 part。如果模型本身已经支持隐式缓存，或上游不支持该显式缓存扩展字段，可在模型配置中设为 `false`。支持相同显式缓存扩展的非 DashScope provider 可设为 `true`。同时适用于 `/v1/messages` 和 `/v1/chat/completions` 路由。\n    - `supportPdf`：可选，控制该模型是否支持 PDF/document content。默认 `false`，不支持时会把 PDF 转成提示文本；设为 `true` 时会把 PDF/document 转成 OpenAI Chat Completions 的 file part。\n    - `toolContentSupportType`：可选，配置该模型的 tool result content 支持能力，值为 `array`、`image`、`pdf` 的数组。provider 侧未配置时默认只发送 string tool content。若 `supportPdf` 为 `true` 但这里不包含 `pdf`，tool result 里的 file part 会被转成 user role 消息。Copilot 主链路不使用这个 provider 默认，仍按 array + image 且不支持 PDF 的能力处理。\n    - `type`：可选，按模型覆盖 provider 的协议类型。支持 `anthropic`、`openai-compatible` 和 `openai-responses`。设置后，provider 的 `/v1/messages` 路由会使用该模型的 type 替代 provider 级别的 type 进行请求路由、认证头解析和上游端点选择。适用于 OpenCode Go 等上游对不同模型同时支持 OpenAI 兼容和 Anthropic Messages API 的 provider。覆盖 type 时，认证头按覆盖后 type 的默认值解析（Anthropic 默认 `x-api-key`；OpenAI 兼容/Responses 默认 `authorization`）。\n\n  DashScope 模型配置示例：\n  ```json\n  {\n    \"providers\": {\n      \"dashscope\": {\n        \"type\": \"openai-compatible\",\n        \"enabled\": true,\n        \"baseUrl\": \"https://dashscope.aliyuncs.com/compatible-mode\",\n        \"apiKey\": \"sk-your-dashscope-key\",\n        \"pricingCurrency\": \"CNY\",\n        \"models\": {\n          \"qwen3.7-plus\": {\n            \"temperature\": 1,\n            \"topP\": 0.95,\n            \"topK\": 20,\n            \"extraBody\": {\n              \"preserve_thinking\": true\n            }\n          },\n          \"glm-5.1\": {\n            \"temperature\": 0.7,\n            \"topP\": 0.95,\n            \"contextCache\": true,\n            \"pricing\": {\n              \"tiers\": [\n                {\n                  \"maxInputTokens\": 32000,\n                  \"input\": 6,\n                  \"cachedInput\": 1.2,\n                  \"explicitCachedInput\": 0.6,\n                  \"cacheCreationInput\": 7.5,\n                  \"output\": 24\n                },\n                {\n                  \"maxInputTokens\": 200000,\n                  \"input\": 8,\n                  \"cachedInput\": 1.6,\n                  \"explicitCachedInput\": 0.8,\n                  \"cacheCreationInput\": 10,\n                  \"output\": 28\n                }\n              ]\n            },\n            \"extraBody\": {\n              \"preserve_thinking\": true\n            }\n          }\n        }\n      }\n    }\n  }\n  ```\n  内置 token 价格覆盖 Codex GPT 模型（USD）、DashScope `qwen3.7-max`、`qwen3.7-plus`、`glm-5.1`、`glm-5.2`（CNY），DeepSeek `deepseek-v4-flash`、`deepseek-v4-pro`、`deepseek-chat`、`deepseek-reasoner`（CNY），以及 OpenCode Go 模型（`glm-5.2`、`deepseek-v4-flash`、`deepseek-v4-pro`、`kimi-k2.7-code`、`mimo-v2.5`、`mimo-v2.5-pro`、`qwen3.7-plus`、`qwen3.7-max`、`minimax-m2.5`、`minimax-m3`，USD）。用户配置的 `pricing` 优先于内置价格。DashScope 若上游 usage 中出现 `cache_creation_input_tokens` 字段，cached tokens 按显式缓存读价计费；否则 `cachedInput` 作为隐式缓存读价。DeepSeek 的 `prompt_cache_hit_tokens` 会归入 cached input，`prompt_cache_miss_tokens` 会归入普通 input。\n- **smallModel：** 无工具预热消息的回退模型（例如 Claude Code 的探测请求）；默认是 `gpt-5-mini`。\n- **contextManagement：** 控制代理是否为 Responses API 附加 `context_management` 压缩指令。`messages` 作用于被翻译成 Responses API 的 Anthropic 风格 `/v1/messages` 请求，包括 `openai-responses` provider 的 Messages 路由，默认值为 `true`。`responses` 作用于 native `/v1/responses` 流量，包括 `provider/model` 别名和内置 `codex` provider，默认值为 `false`。只有在确认客户端支持 context management compaction 后，才建议在 Responses API 下启用 `responses`。启用后，请求体会带上 `context_management`，并在后续轮次中仅保留最新的压缩承载内容。\n- **modelResponsesApiCompactThresholds：** 按模型覆盖 Responses API 的 `compact_threshold`，仅在代理自动附加 `context_management` 时使用。它的优先级高于 `resolveResponsesCompactThreshold` 基于 `max_prompt_tokens * ratio` 的兜底阈值。默认将 `gpt-5.4` 和 `gpt-5.5` 设为 `217600`（`272000 * 0.8`），将 `gpt-5.6-sol`、`gpt-5.6-terra`、`gpt-5.6-luna` 设为 `231200`（`272000 * 0.85`）。未列出的模型继续使用原有兜底逻辑。\n- **modelReasoningEfforts：** 按模型配置的推理强度，仅作用于 `/v1/messages` 请求。当请求走 Copilot 原生 Messages API 时设置 `output_config.effort`；当请求被翻译为 Responses API 时设置 `reasoning.effort`。可选值包括 `none`、`minimal`、`low`、`medium`、`high`、`xhigh` 和 `max`。若某模型未配置，则默认使用 `high`；GPT-5.3+ 模型未显式配置时回退为 `xhigh`。\n- **useMessagesApi：** 当为 `true` 时，支持 Copilot 原生 `/v1/messages` 的 Claude 系模型会走 Messages API；否则回退到 `/chat/completions`。设为 `false` 可禁用 Messages API 路由，始终使用 `/chat/completions`。默认值为 `true`。\n- **useResponsesApiWebSocket：** 当为 `true` 时，Responses API 请求会优先对声明了 `ws:/responses` 的模型使用 Copilot websocket transport；仅声明 `/responses` 的模型仍走 HTTP。设为 `false` 可禁用 websocket 路由，并在模型支持 `/responses` 时使用 HTTP `/responses`。默认值为 `true`。\n- **useResponsesApiWebSearch：** 当为 `true` 时，服务端会保留 Responses API 中 `type: \"web_search\"` 的工具并透传到上游。设为 `false` 则会从 `/responses` payload 中移除这些工具。默认值为 `true`。\n- **messageApiWebSearchModel：** 顶层 Copilot `/v1/messages` 请求只包含服务端 `web_search` 工具时使用的全局模型，默认值为 `gpt-5-mini`。如果该值是 `provider/model` 别名，请求会进入对应 provider 的 Messages API 路径，并在转发前移除 provider 前缀。对于 Copilot GPT 模型，web search 会通过 `/responses` 执行。混合 `web_search` 与自定义工具的场景暂不支持，服务端会移除 server-side `web_search`。\n- **claudeTokenMultiplier：** 用于 Claude `/v1/messages/count_tokens` 请求在本地走 GPT tokenizer 估算时的乘数。默认值为 `1.15`。如果你的客户端仍然过晚触发上下文压缩，可以适当调大。这个配置只会在代理本地估算 Claude token 时生效；如果已经配置 `anthropicApiKey` 且 Anthropic token counting 调用成功，则会直接返回 Anthropic 的精确计数，不会使用这个乘数。\n- **anthropicApiKey：** 用于把 Claude `/v1/messages/count_tokens` 请求转发到 Anthropic 真实 token counting 端点的 API key，这样会返回精确计数，而不是 GPT tokenizer 估算值。也可通过环境变量 `ANTHROPIC_API_KEY` 设置。若未配置，或上游调用失败，则回退到由 `claudeTokenMultiplier` 控制的本地 GPT tokenizer 估算。\n\n编辑此文件后即可自定义 prompts，或替换为你自己的快速模型。修改完成后请重启服务（或重新执行命令），让缓存中的配置刷新生效。\n\n## API 认证\n\n- **受保护的普通路由：** 当配置了 `auth.apiKeys` 且非空时，除 `/`、`/usage-viewer` 和 `/usage-viewer/` 以外的普通路由都需要认证。\n- **Admin 路由：** 所有 `/admin/*` 路由都要求 `auth.adminApiKey`。如果缺失，服务会在启动时自动生成并在开始提供服务前写回 `config.json`。\n- **允许的认证头：**\n  - `x-api-key: <your_key>`\n  - `Authorization: Bearer <your_key>`\n- **CORS 预检：** `OPTIONS` 请求始终允许。\n- **未配置普通 key 时：** 普通路由仍可直接访问；但这条规则不适用于 `/admin/*`，后者只接受 `auth.adminApiKey`。\n\n普通受保护路由的示例请求：\n\n```sh\ncurl http://localhost:4141/v1/models \\\n  -H \"x-api-key: your_api_key\"\n```\n\nAdmin 路由的示例请求：\n\n```sh\ncurl http://localhost:4141/admin/config/model-mappings \\\n  -H \"x-api-key: your_admin_api_key\"\n```\n\n## API 端点\n\n服务端提供多个 OpenAI / Anthropic 兼容端点。请求会根据所选模型和 `provider/model` 别名路由到 GitHub Copilot、内置 `codex` provider 或已配置的 provider。\n\n### OpenAI 兼容端点\n\n这些端点模拟 OpenAI API 结构。\n\n| 端点 | 方法 | 说明 |\n| --- | --- | --- |\n| `POST /v1/responses` | `POST` | OpenAI 中用于生成模型响应的高级接口。支持 `openai-responses` provider 的 `provider/model` 别名。 |\n| `POST /v1/chat/completions` | `POST` | 为给定聊天对话创建模型响应。支持 `openai-compatible` provider 的 `provider/model` 别名；目标 provider 已配置时可在没有 Copilot 的情况下使用。 |\n| `GET /v1/models` | `GET` | 列出 Copilot 模型以及已启用 provider 的 `provider/model-id` 模型。来自 Codex 客户端（`User-Agent` 以 `codex` 开头）的请求会转发到 Codex Models 上游。 |\n| `POST /v1/embeddings` | `POST` | 创建表示输入文本的向量嵌入。 |\n\n### Codex 后端代理端点\n\n| 端点 | 方法 | 说明 |\n| --- | --- | --- |\n| `POST /alpha/search` | `POST` | 将 JSON 请求体和查询参数透明转发到 Codex Alpha Search 上游。网关会使用当前 Codex 登录态覆盖客户端的 authorization 和 account header，透传 `accept`、`content-type`、`originator`、`user-agent`、`cookie` 等兼容 header，并原样返回上游状态码、响应头和响应体。 |\n\n### Anthropic 兼容端点\n\n这些端点设计为兼容 Anthropic Messages API。\n\n| 端点 | 方法 | 说明 |\n| --- | --- | --- |\n| `POST /v1/messages` | `POST` | 为给定对话创建模型响应。支持已配置 provider 的 `provider/model` 别名，包括通过 `openai-compatible` provider 做翻译。 |\n| `POST /v1/messages/count_tokens` | `POST` | 计算一组消息的 token 数。支持已配置 provider 的 `provider/model` 别名。 |\n| `POST /:provider/v1/messages` | `POST` | 将 Anthropic Messages 请求代理到已配置的 Anthropic provider，或翻译到 OpenAI 兼容 / OpenAI Responses provider。 |\n| `GET /:provider/v1/models` | `GET` | 将模型列表请求代理到已配置的 provider。 |\n| `POST /:provider/v1/messages/count_tokens` | `POST` | 为 provider 路由请求在本地计算 token 数。 |\n\n### 使用量监控端点\n\n用于监控 Copilot 用量与额度的新端点。\n\n| 端点 | 方法 | 说明 |\n| --- | --- | --- |\n| `GET /usage` | `GET` | 获取详细的 Copilot 使用统计与额度信息。 |\n| `GET /token` | `GET` | 获取当前 API 正在使用的 Copilot token。 |\n\n### Admin / 配置端点\n\n这些端点用于本地管理操作，只接受 `auth.adminApiKey`。\n\n| 端点 | 方法 | 说明 |\n| --- | --- | --- |\n| `GET /admin/config/model-mappings` | `GET` | 返回当前 `config.json` 路径以及生效中的 `modelMappings` 映射。 |\n| `POST /admin/config/model-mappings` | `POST` | 只更新 `config.json` 里的 `modelMappings` 字段，并回传更新后的结果。 |\n\n## 使用示例\n\n常用 `npx` 命令：\n\n```sh\n# 基础启动\nnpx @jeffreycao/copilot-api@latest start\n\n# 自定义端口并开启详细日志\nnpx @jeffreycao/copilot-api@latest start --port 8080 --verbose\n\n# 执行认证流程\nnpx @jeffreycao/copilot-api@latest auth login\n\n# 配置第三方 provider，然后不依赖 GitHub Copilot 启动\nnpx @jeffreycao/copilot-api@latest auth login --provider dashscope\nnpx @jeffreycao/copilot-api@latest start\n\n# 以 JSON 格式输出调试信息\nnpx @jeffreycao/copilot-api@latest debug --json\n\n# 用 Bun 而不是 Node.js 运行已发布 CLI\nbunx --bun @jeffreycao/copilot-api@latest start\n```\n\n配置 `dashscope` 后的 OpenAI 兼容 provider 调用示例：\n\n```sh\ncurl http://localhost:4141/v1/chat/completions \\\n  -H \"content-type: application/json\" \\\n  -d '{\"model\":\"dashscope/qwen3.6-plus\",\"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]}'\n\ncurl http://localhost:4141/dashscope/v1/messages \\\n  -H \"content-type: application/json\" \\\n  -d '{\"model\":\"qwen3.6-plus\",\"max_tokens\":1024,\"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]}'\n```\n\n## 使用建议\n\n<a id=\"claudemd-or-agentsmd-recommended-content\"></a>\n\n### CLAUDE.md 或 AGENTS.md 推荐内容\n\n如果你想手动加入这些提醒，请在 Claude Code 的 `CLAUDE.md`，或 opencode/codex 的 `AGENTS.md` 中加入以下内容：\n\n```\n- Prohibited from directly asking questions to users, MUST use question tool.\n- Once you can confirm that the task is complete, MUST use question tool to make user confirm. The user may respond with feedback if they are not satisfied with the result, which you can use to make improvements and try again, after try again, MUST use question tool to make user confirm again.\n```\n"}, "deb4347ee3433be63f66ce234d6d920de1a56c6f": {"t": 1785765565.9416816, "n": 31255, "h": "928be35bf6768830", "c": "# Copilot API Proxy\n\n[English](./README.md) | 简体中文\n\n## 重要说明\n\n> [!IMPORTANT]\n> **使用前请先注意以下几点：**\n>\n> 1. **Claude Code 配置：** 与 Claude Code 搭配使用时，请将模型 ID 配置为 `claude-opus-4-8`。示例 claude `settings.json` 见 [通过 `settings.json` 手动配置](#manual-configuration-with-settingsjson)。\n>\n> 2. **内置 `copilot`、`codex` 与第三方 provider：** 执行 `npx @jeffreycao/copilot-api@latest auth`，可选择 `copilot`、`codex`、`deepseek`、`custom` 等 provider。\n>\n> 3. **注意事项：** README 顶部移除的 GitHub Copilot warning 见 [GitHub Copilot 安全提示](./NOTICE.md#github-copilot-security-notice)。\n\n---\n\n## 项目概览\n\n这是一个小型 AI gateway，可以使用 GitHub Copilot、内置 `codex` provider，也可以使用 DashScope 等已配置的第三方 provider。GitHub Copilot 现在是可选能力：如果本地没有 GitHub token，只要至少配置了一个启用中的 provider，服务仍可按 provider-only 模式启动。\n\nAI gateway 会从同一个本地端点暴露 OpenAI / Anthropic 兼容 API，让 [Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview)、OpenCode、Codex 和 OpenAI 兼容客户端可以共用同一个本地服务。\n\n在 GitHub Copilot 路径上，AI gateway 会在可用时优先使用 Copilot 原生的 Anthropic 风格 Messages API，在重工具调用场景下保留更原生的 Claude 行为。\n\n## 功能特性\n\n- **OpenAI 与 Anthropic 双兼容**：通过 `/v1/responses`、`/v1/chat/completions`、`/v1/models`、`/v1/embeddings` 和 `/v1/messages` 对外暴露同一个本地 AI gateway。\n- **Copilot 可选**：有 GitHub 凭据时可以使用 GitHub Copilot，没有 GitHub 凭据时也可以只依赖已配置的 provider 运行。\n- **同一网关接入 Copilot、`codex` 与第三方 provider**：可统一路由 GitHub Copilot、内置 `codex` provider 和配置好的外部 provider。\n- **第三方 provider 可独立启动**：配置 DashScope、DeepSeek、OpenRouter 或自定义 provider 后，不需要 GitHub Copilot 登录即可启动 AI gateway。\n- **OpenAI 兼容 provider 同时支持 chat 和 Messages API**：`openai-compatible` provider 可通过顶层 `/v1/chat/completions` 搭配 `model: \"provider/model\"` 提供 Chat Completions，也可通过 `/v1/messages` 完成 Anthropic Messages 的请求/响应翻译。\n- **面向 Claude 的更原生 Copilot 路由**：优先使用原生 `/v1/messages`，保留 Claude 风格工具流，支持 Anthropic beta 能力、通过 Responses-capable 模型支持 Claude WebSearch，并保留 subagent / session 标记。\n- **Claude Code 与 OpenCode 集成**：兼容 Claude Code 与 OpenCode，也支持通过 `@ai-sdk/anthropic` 直接作为 Anthropic provider 使用。\n- **灵活的认证与部署选项**：支持交互式登录、直接 token、个人 / Business / Enterprise、GitHub Enterprise、opencode OAuth 和自定义数据目录。\n- **多 provider 路由**：可暴露 `/:provider/...` 路由，也可在顶层 API 上使用 `model: \"provider/model\"`。\n\n## 前置要求\n\n- Bun（>= 1.2.x）\n- 如果要通过 `npx` 运行已发布 CLI，需要 Node.js\n- 只有在使用 GitHub Copilot provider 时，才需要已订阅 Copilot 的 GitHub 账号\n- 如果不使用 GitHub Copilot，需要至少一个已配置 provider 的 API key 或 OAuth 登录\n\n## 安装\n\n安装依赖：\n\n```sh\nbun install\n```\n\n直接从源码启动服务：\n\n```sh\nbun run start start\n```\n\n## 从源码运行\n\n本项目可以通过多种方式从源码运行：\n\n### 开发模式\n\n```sh\nbun run dev start\n```\n\n### 生产模式\n\n```sh\nbun run start start\n```\n\n## 通过 npx 使用\n\n你可以直接用 npx 运行本项目：\n\n> [!IMPORTANT]\n> 通过 `npx` 运行时，token usage 存储会使用 Node 内置的 `node:sqlite` 模块。该能力会在 Node.js >= 22.13.0 时启用；Node.js < 22.13.0 时 CLI 仍可启动，但会禁用 token usage 存储。\n>\n> 如果不升级 Node.js 但仍需要 token usage 存储，可以改用 Bun 运行已发布 CLI：`bunx --bun @jeffreycao/copilot-api@latest start`。\n\n```sh\nnpx @jeffreycao/copilot-api@latest start\n```\n\n带参数示例：\n\n```sh\nnpx @jeffreycao/copilot-api@latest start --port 8080\n```\n\n如果只想做认证或 provider 配置：\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth\n```\n\n如果要不依赖 GitHub Copilot 运行，先配置至少一个 provider，然后正常启动服务：\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth login --provider dashscope\nnpx @jeffreycao/copilot-api@latest start\n```\n\n## 配合 Docker 使用\n\n构建镜像：\n\n```sh\ndocker build -t copilot-api .\n```\n\n通过 bind mount 运行容器，让认证数据在重启后保留：\n\n```sh\nmkdir -p ./copilot-data\ndocker run -p 4141:4141 -v $(pwd)/copilot-data:/root/.local/share/copilot-api copilot-api\n```\n\n这会把宿主机上的 `./copilot-data` 映射到容器内的 `/root/.local/share/copilot-api`，用于持久化 GitHub 认证数据、provider 配置和其他 gateway 状态。\n\n也可以直接通过环境变量传入 GitHub token：\n\n```sh\ndocker run -p 4141:4141 -e GH_TOKEN=your_github_token_here copilot-api\n```\n\n## Electron 桌面应用\n\n如果你更喜欢图形界面，仓库里还提供了位于 `desktop/` 的 Electron 桌面应用。它支持 GitHub Copilot 登录、OpenAI Codex OAuth，以及 DeepSeek、DashScope、OpenRouter 或自定义 provider 的 API Key 配置。授权或配置 provider 后，可以一键启动或停止本地代理，并在界面里直接查看本地端点、鉴权 Header、可用模型、额度和日志。\n\n设置页还可以配置 `OAuth App`、`API Home`、`Enterprise URL`、详细日志以及最小化到托盘。桌面安装包发布在 GitHub Releases：\n\nhttps://github.com/caozhiyuan/copilot-api/releases\n\n下载对应平台的安装包后，在应用内授权或配置 provider，选择端口并启动服务，再把你的客户端指向应用里显示的本地端点即可。发布版桌面应用使用随包内置的 Electron 运行时，正常使用不需要额外安装 Node.js；token usage 历史记录会在该内置运行时支持 SQLite 时启用。\n\n桌面应用里的高级配置页会通过 `GET/POST /admin/config/model-mappings` 读写这份共享的模型映射。同一份映射会统一作用于 `POST /v1/messages`、`POST /v1/messages/count_tokens`、`POST /v1/responses` 和 `POST /v1/chat/completions`，不再按接口区分。它使用的是 `auth.adminApiKey`，不是普通的 `auth.apiKeys`；应用会在服务启动并自动生成该 key 后，直接从 `config.json` 读取它来发起请求。\n\n### 桌面应用截图\n\n下面展示了桌面应用中的首页、Token 用量统计页面：\n\n<p align=\"center\">\n  <img src=\"./docs/screenshots/desktop-dashboard.png\" alt=\"Copilot API 桌面应用首页\" width=\"49%\" />\n  <img src=\"./docs/screenshots/desktop-token-usage.png\" alt=\"Copilot API 桌面应用 Token 用量页\" width=\"49%\" />\n</p>\n\n## 与 Claude Code 一起使用\n\n这个 AI gateway 可以为 [Claude Code](https://docs.anthropic.com/en/claude-code) 提供后端能力。Claude Code 是 Anthropic 提供的实验性面向开发者的对话式 AI 助手。\n\n有两种方式可以把 Claude Code 配置为使用这个 AI gateway：\n\n### 通过 `--claude-code` 标志进行交互式配置\n\n执行带 `--claude-code` 的 `start` 命令开始：\n\n```sh\nnpx @jeffreycao/copilot-api@latest start --claude-code\n```\n\n你会被提示选择一个主模型，以及一个用于后台任务的 \"small, fast\" 模型。选择完成后，会有一条命令被复制到剪贴板中。该命令会设置 Claude Code 使用这个 AI gateway 所需的环境变量。\n\n在新的终端中粘贴并执行这条命令，即可启动 Claude Code。\n\n<a id=\"manual-configuration-with-settingsjson\"></a>\n\n### 通过 `settings.json` 手动配置\n\n另一种方式是在项目根目录中创建 `.claude/settings.json` 文件，并写入 Claude Code 所需的环境变量。这样你就不需要每次都运行交互式配置了。\n\n下面是一个 `.claude/settings.json` 示例：\n\n```json\n{\n  \"env\": {\n    \"ANTHROPIC_BASE_URL\": \"http://localhost:4141\",\n    \"ANTHROPIC_AUTH_TOKEN\": \"dummy\",\n    \"ANTHROPIC_MODEL\": \"deepseek/deepseek-v4-pro\",\n    \"ANTHROPIC_DEFAULT_SONNET_MODEL\": \"deepseek/deepseek-v4-pro\",\n    \"ANTHROPIC_DEFAULT_HAIKU_MODEL\": \"deepseek/deepseek-v4-flash\",\n    \"DISABLE_NON_ESSENTIAL_MODEL_CALLS\": \"1\",\n    \"CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC\": \"1\",\n    \"CLAUDE_CODE_ATTRIBUTION_HEADER\": \"0\",\n    \"CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION\": \"false\",\n    \"CLAUDE_CODE_DISABLE_TERMINAL_TITLE\": \"true\",\n    \"CLAUDE_CODE_ENABLE_AWAY_SUMMARY\": \"0\"\n  },\n  \"permissions\": {\n    \"deny\": [\n      \"mcp__ide__executeCode\"\n    ]\n  }\n}\n```\n\n- 请根据需要替换 `ANTHROPIC_MODEL`、`ANTHROPIC_DEFAULT_OPUS_MODEL`、`ANTHROPIC_DEFAULT_SONNET_MODEL` 和 `ANTHROPIC_DEFAULT_HAIKU_MODEL`。配置完成后，请安装 claude code 插件，见 [插件集成](#plugin-integrations)。\n- 将 `CLAUDE_CODE_ATTRIBUTION_HEADER` 设为 `0` 可以阻止 Claude Code 在 system prompt 中附加计费和版本信息，从而避免 prompt cache 失效。\n- 关闭 `CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION` 和 `CLAUDE_CODE_ENABLE_AWAY_SUMMARY` 可以避免不必要地消耗额度。\n- Claude Code WebSearch 已支持纯搜索请求。Copilot 路径请保持全局 `messageApiWebSearchModel` 指向 Responses-capable GPT 模型或 `provider/model` 别名；provider 路由请使用原生 Anthropic provider 或 `openai-responses` provider。只有在你明确想禁止这类流量时，才需要把 `WebSearch` 加到 `permissions.deny`。\n- 如果使用的不是 Claude 模型，请不要启用 `ENABLE_TOOL_SEARCH`。如果使用的是 Claude 模型，则可以启用 `ENABLE_TOOL_SEARCH`。当前 Claude Code 使用的是客户端 tool search 模式，在该模式下每次加载 defer tools 都需要额外请求一次。\n- `CLAUDE_CODE_AUTO_COMPACT_WINDOW`：设置用于自动压缩计算的上下文容量（以 token 为单位）。默认使用模型自身的上下文窗口：标准模型为 200K，扩展上下文模型为 1M。使用 1M 上下文模型（如 `claude-opus-4-6[1m]`）时，可设置一个较低的值（如 `500000`）将窗口视为 500K 用于压缩计算。该值受限于模型的实际上下文窗口上限。`CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` 会基于此值的百分比生效。设置此变量可将压缩阈值与状态栏的 `used_percentage` 解耦（后者始终使用模型的完整上下文窗口）。\n\n更多选项见：[Claude Code settings](https://docs.anthropic.com/en/docs/claude-code/settings#environment-variables)\n\n也可以参考 IDE 集成说明：[Add Claude Code to your IDE](https://docs.anthropic.com/en/docs/claude-code/ide-integrations)\n\n## 与 OpenCode 一起使用\n\nOpenCode 已经有直接的 GitHub Copilot provider。本节适用于你希望让 OpenCode 通过 `@ai-sdk/anthropic` 指向这个 AI gateway，并复用本 README 前面提到的 agent 行为时。\n\n### 最小配置\n\n使用 OpenCode OAuth app 启动 AI gateway：\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth --oauth-app=opencode\nnpx @jeffreycao/copilot-api@latest start\n```\n\n然后让 OpenCode 通过 `@ai-sdk/anthropic` 指向这个 AI gateway。\n\n示例 `~/.config/opencode/opencode.json`：\n\n```json\n{\n  \"$schema\": \"https://opencode.ai/config.json\",\n  \"provider\": {\n    \"local\": {\n      \"npm\": \"@ai-sdk/anthropic\",\n      \"name\": \"My Local\",\n      \"options\": {\n        \"baseURL\": \"http://localhost:4141/v1\",\n        \"apiKey\": \"dummy\"\n      },\n      \"models\": {\n        \"gpt-5.4\": {\n          \"name\": \"gpt-5.4\",\n          \"modalities\": {\n            \"input\": [\"text\", \"image\"],\n            \"output\": [\"text\"]\n          },\n          \"limit\": {\n            \"context\": 400000,\n            \"input\": 272000,\n            \"output\": 128000\n          }\n        },\n        \"claude-sonnet-4.6\": {\n          \"id\": \"claude-sonnet-4.6\",\n          \"name\": \"claude-sonnet-4.6\",\n          \"modalities\": {\n            \"input\": [\"text\", \"image\"],\n            \"output\": [\"text\"]\n          },\n          \"limit\": {\n            \"context\": 200000,\n            \"output\": 32000\n          },\n          \"options\": {\n            \"thinking\": {\n              \"type\": \"adaptive\"\n            },\n            \"effort\": \"max\"\n          }\n        }\n      }\n    }\n  }\n}\n```\n\n这些字段的重要性：\n\n- `npm: \"@ai-sdk/anthropic\"` 是关键。OpenCode 会以 Anthropic Messages 语义与这个 AI gateway 通信，而不是把一切扁平化为 OpenAI Chat Completions。\n- `options.baseURL` 应设为 `http://localhost:4141/v1`；Anthropic SDK 会自动补上 `/messages`、`/models` 和 `/messages/count_tokens`。\n- 如果你在此代理中启用了 `auth.apiKeys`，请把 `dummy` 替换为真实 key；否则任意占位值都可以。\n\n## 与 Codex 一起使用\n\n这个 AI gateway 也可以为 Codex 提供后端能力。\n\n### Codex `config.toml` 参考配置\n\n把以下 `[model_providers.copilot_api]` 段加入你的 Codex `~/.codex/config.toml`：\n\n```toml\nmodel_provider = \"copilot_api\"\nmodel_reasoning_summary = \"auto\"\nmodel_verbosity = \"medium\"\nmodel_context_window = 272000\nmodel_auto_compact_token_limit = 244800\n\n[model_providers.copilot_api]\nname = \"OpenAI\"\nbase_url = \"http://localhost:4141\"\nenv_key = \"GITHUB_COPILOT_API_KEY\"\nrequires_openai_auth = true\nsupports_websockets = false\nwire_api = \"responses\"\nrequest_max_retries = 3\nstream_max_retries = 1\nstream_idle_timeout_ms = 300000\n\n[features]\nremote_compaction_v2 = true\n\n[analytics]\nenabled = false\n```\n\n> [!NOTE]\n> 此配置仅限于 Codex 与 GitHub Copilot provider。`name` 一定要配置为 `\"OpenAI\"`。它可以缓解 Codex local compact 不命中缓存的问题。如果你开启了 `contextManagement.responses`（Responses API context management 压缩），通常不会走到 `remote_compaction_v2` 或者 local compact，但如果工具返回 tokens 过大，仍有可能触发。在 native Responses API 流量下启用前，请先确认客户端支持 context management compaction。\n\n## GPT Tool Search\n\n对于 `gpt-5.4+` 这类 GPT Responses 模型，这个 AI gateway 可以通过一个很小的 MCP bridge 暴露 Responses `tool_search`。Claude Code 和 opencode 都可以使用同一个 bridge，前提是客户端会加载 MCP server，并且 Anthropic Messages 流量会经过这个 AI gateway。\n\nGPT 模型不要设置 Claude Code 原生的 `ENABLE_TOOL_SEARCH`。这个开关启用的是 Claude Code 自己的客户端 tool search 模式，可能导致 deferred 工具定义不再转发给 AI gateway。这个 AI gateway 需要完整的工具定义，这样才能只保留那一小组常驻加载工具，其余工具统一转换为 Responses deferred namespace。\n\n如果你安装了 `tool-search@copilot-api-marketplace`，Claude Code 会自动带上这个 MCP bridge，可以跳过下面这段 Claude Code MCP 手动配置。\n\n请把 tool search bridge 加到 Claude Code 使用的 MCP 配置中：\n\n```json\n{\n  \"mcpServers\": {\n    \"tool_search\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@jeffreycao/copilot-api@latest\", \"mcp\"]\n    }\n  }\n}\n```\n\n请把 tool search bridge 加到 opencode 使用的 MCP 配置中：\n\n```json\n{\n  \"mcp\": {\n    \"tool_search\": {\n      \"type\": \"local\",\n      \"command\": [\"npx\", \"-y\", \"@jeffreycao/copilot-api@latest\", \"mcp\"]\n    }\n  }\n}\n```\n\n本地开发时可以将命令换成 `bun`，参数换成 `[\"run\", \"./src/main.ts\", \"mcp\"]`。\n\nAI gateway 内部现在会把 OpenAI Responses `tool_search` 配置成 client-executed 模式。deferred tools 仍然会作为可搜索 namespace 暴露给模型，但会明确要求模型直接返回下一步要加载的精确工具名列表。\n\n该 bridge 使用直接工具选择，不做 query 搜索。工具入参是 `names`，值为逗号分隔的精确 deferred 工具名，例如 `TaskList,TaskGet,mcp__fetch__fetch`。\n\n<a id=\"plugin-integrations\"></a>\n\n## 插件集成\n\n本项目为 Claude Code 和 opencode 提供了插件集成。\n\n#### Claude Code 插件集成（基于 marketplace）\n\nClaude Code 集成现在拆分为两个插件：\n\n- `agent-inject` 会在 `SubagentStart` 时注入 `__SUBAGENT_MARKER__...`，以便 AI gateway 推导 `x-initiator: agent`。\n- `tool-search` 会注册用于 GPT Responses deferred tool loading 的 `tool_search` MCP bridge。\n\n- 本仓库中的 marketplace catalog：`.claude-plugin/marketplace.json`\n- 本仓库中的插件源码：`plugin/claude/agent-inject`、`plugin/claude/tool-search`\n\n远程添加 marketplace：\n\n```sh\n/plugin marketplace add https://github.com/caozhiyuan/copilot-api.git\n```\n\n从 marketplace 安装插件：\n\n```sh\n/plugin install agent-inject@copilot-api-marketplace\n/plugin install tool-search@copilot-api-marketplace\n```\n\n安装后，`agent-inject` 会在 `SubagentStart` 时注入 `__SUBAGENT_MARKER__...`，AI gateway 会利用它推导 `x-initiator: agent`。\n\n`agent-inject` 还会注册一个 `UserPromptSubmit` hook，并返回 `{\"continue\": true}`；同时它也可以通过环境变量注入 `SessionStart` reminder 规则：\n\n- `CLAUDE_PLUGIN_ENABLE_QUESTION_RULES=1` 会自动为 Claude Code 启用两条关于使用 `question` 工具的提醒。你也可以把同样的提醒手动写进 `CLAUDE.md`；见 [CLAUDE.md 或 AGENTS.md 推荐内容](#claudemd-or-agentsmd-recommended-content)。\n- `CLAUDE_PLUGIN_ENABLE_NO_BACKGROUND_AGENTS_RULE=1` 会启用关于避免在 agent hooks 中使用 `run_in_background: true` 的提醒。\n\n`tool-search` 插件内置了 [GPT Tool Search](#gpt-tool-search) 一节描述的同一个 MCP bridge，因此安装该插件后，Claude Code 用户无需再手动配置 `tool_search` server。\n\n#### Opencode 插件\n\nsubagent 标记生成器被打包为一个 opencode 插件，位于 `plugin/opencode/subagent-marker.js`。\n\n**安装方式：**\n\n将插件文件复制到你的 opencode 插件目录：\n\n```sh\n# 克隆或下载本仓库后复制该插件\ncp plugin/opencode/subagent-marker.js ~/.config/opencode/plugins/\n```\n\n或者手动在 `~/.config/opencode/plugins/subagent-marker.js` 创建该文件，并填入插件内容。\n\n**功能：**\n\n- 跟踪 subagent 创建的子会话\n- 自动在 subagent 聊天消息前添加 marker system reminder（`__SUBAGENT_MARKER__...`）\n- 设置 `x-session-id` 请求头以跟踪会话\n- 让这个 AI gateway 能够把来自 subagent 的请求识别为 `x-initiator: agent`\n\n该插件会挂接到 `session.created`、`session.deleted`、`chat.message` 和 `chat.headers` 事件上，以无缝提供 subagent marker 能力。\n\n## 使用量查看器\n\n服务启动后，控制台会输出一个 Copilot 使用量看板 URL。这个看板是一个用于监控 API 用量的 Web 界面。\n\n1. 启动服务。例如使用 npx：\n   ```sh\n   npx @jeffreycao/copilot-api@latest start\n   ```\n2. 服务会输出一个 usage viewer 的 URL。将它复制到浏览器中打开，形式大致如下：\n   `http://localhost:4141/usage-viewer?endpoint=http://localhost:4141/usage`\n   - 如果你在 Windows 上使用 `start.bat` 脚本，这个页面会自动打开。\n\n看板提供了更易读的 Copilot 用量视图：\n\n> token usage 历史记录需要 Bun 或 Node.js >= 22.13.0。Node.js < 22.13.0 时服务会正常运行，但 token usage 存储会被禁用。\n\n- **API Endpoint URL**：通过 URL 查询参数指定 API endpoints，默认指向本地服务。支持手动切换为其他兼容 endpoints。\n- **x-api-key 认证**：如果启用了 API Key 认证，可填入 `x-api-key` 请求头。密钥会持久化保存在浏览器本地存储中。\n- **Period 选择器**：支持 Day / Week / Month 三种时间范围，切换时 URL 参数会自动同步，方便收藏和分享。\n- **Fetch Data**：点击 \"Refresh\" 按钮加载或刷新使用数据。页面加载时也会自动拉取数据。\n- **Copilot Quotas 额度**：通过进度条展示 Chat、Completions 等不同服务的额度使用情况，悬停可查看已用/剩余详情。\n- **Token Usage 指标卡片**：汇总当前周期的 Total、Input、Output、Cache Read、Cache Write、Requests 和预估费用。\n- **趋势图（Week / Month）**：提供按模型和指标筛选的折线趋势图，点击数据点可查看单日用量明细。\n- **Model Breakdown 表格**：按模型维度列出周期内的请求数、输入/输出/缓存 token 和预计费用。\n- **Request Events 分页列表**：按时间排序的请求事件记录，支持分页浏览，含时间戳、模型、请求 ID 和 token 用量。\n- **Detailed Information**：展示 API 返回的完整 JSON 响应，便于深入分析所有可用统计数据。\n- **URL-based Configuration**：也可通过 `endpoint` 和 `period` 查询参数直接指定 API 端点与时间范围。例如：\n  `http://localhost:4141/usage-viewer?endpoint=http://your-api-server/usage&period=week`\n\n### Usage Viewer 截图\n\n<p align=\"center\">\n  <img src=\"./docs/screenshots/usage-viewer.png\" alt=\"Copilot API Usage Viewer 页面\" width=\"900\" />\n</p>\n\n## 命令结构\n\nCopilot API 现在使用子命令结构，主要命令包括：\n\n- `start`：启动 AI gateway 服务。如果已有 GitHub token，则启用 Copilot 路径；如果没有 GitHub token，但存在至少一个启用中的 provider，则按 provider-only 模式启动；如果两者都没有，会引导你配置 provider。\n- `auth`：仅执行 provider 登录或配置流程，不启动服务。可用于 GitHub Copilot 登录、Codex OAuth，或第三方 provider API key 配置。\n- `debug`：显示诊断信息，包括版本、运行时详情、文件路径以及认证状态，便于排障与支持。\n\n## 命令行选项\n\n### 全局选项\n\n以下选项可用于任意子命令。若在子命令之前传入，请使用 `--key=value` 形式：\n\n| 选项 | 说明 | 默认值 | 别名 |\n| --- | --- | --- | --- |\n| --api-home | API home 目录路径（设置 `COPILOT_API_HOME`） | 无 | 无 |\n| --oauth-app | OAuth app 标识符（设置 `COPILOT_API_OAUTH_APP`） | 无 | 无 |\n| --enterprise-url | GitHub Enterprise URL（设置 `COPILOT_API_ENTERPRISE_URL`） | 无 | 无 |\n\n### Start 命令选项\n\n以下是 `start` 命令可用的命令行选项：\n\n| 选项 | 说明 | 默认值 | 别名 |\n| --- | --- | --- | --- |\n| --port | 监听端口 | 4141 | -p |\n| --verbose | 启用详细日志 | false | -v |\n| --github-token | 直接提供 GitHub token（必须通过 `auth` 子命令生成） | 无 | -g |\n| --claude-code | 生成一个使用 Copilot API 配置启动 Claude Code 的命令 | false | -c |\n| --show-token | 在获取和刷新时显示 GitHub 与 Copilot token | false | 无 |\n| --proxy-env | 从环境变量初始化代理 | false | 无 |\n\n### Auth 命令选项\n\n| 选项 | 说明 | 默认值 | 别名 |\n| --- | --- | --- | --- |\n| --provider | 要登录或配置的 provider（`copilot`、`codex`、`opencode-go`、`deepseek`、`dashscope`、`openrouter` 或 `custom`） | 交互选择 | 无 |\n| --verbose | 启用详细日志 | false | -v |\n| --show-token | 认证时显示 GitHub token | false | 无 |\n\n只有在需要启用 GitHub Copilot provider 时，才需要执行 `copilot-api auth login --provider copilot`。使用 `codex` 或第三方 provider-only 模式不要求配置 Copilot。\n\n使用 `copilot-api auth login --provider deepseek`、`--provider dashscope`、`--provider openrouter` 或 `--provider opencode-go` 可以通过 CLI 快速新增或更新这些常用第三方 provider。DeepSeek 会提示输入掩码显示的 `apiKey`、provider `type`（默认 `anthropic`），以及默认 `https://api.deepseek.com/anthropic` 的 `baseUrl`。DashScope 会提示输入掩码显示的 `apiKey`、provider `type`（默认 `openai-compatible`）和预填默认值的 `baseUrl`。OpenRouter 只提示输入掩码显示的 `apiKey` 和预填默认值的 `baseUrl`，并固定写入 `type: \"anthropic\"`。OpenCode Go 只提示输入掩码显示的 `apiKey` 和预填默认值的 `baseUrl`，并固定写入 `type: \"openai-compatible\"`（baseUrl `https://opencode.ai/zen/go`）。配置并启用 provider 后，`copilot-api start` 可在没有 GitHub token 的情况下启动。\n\n使用 `copilot-api auth login --provider custom` 可以通过 CLI 新增或更新其他第三方 provider。命令会依次提示输入 provider name、项目支持的 type（`anthropic`、`openai-compatible` 或 `openai-responses`）、`baseUrl`、掩码显示的 `apiKey` 和 `authType`；`authType` 可保持 type 默认值，也可选择 `x-api-key` / `authorization`。\n\n### Debug 命令选项\n\n| 选项 | 说明 | 默认值 | 别名 |\n| --- | --- | --- | --- |\n| --json | 以 JSON 输出调试信息 | false | 无 |\n\n<a id=\"configuration-configjson\"></a>\n\n## 配置（config.json）\n\n- **位置：** Linux/macOS 为 `~/.local/share/copilot-api/config.json`，Windows 为 `%USERPROFILE%\\.local\\share\\copilot-api\\config.json`。\n- **默认结构：**\n  ```json\n  {\n    \"auth\": {\n      \"apiKeys\": [],\n      \"adminApiKey\": \"<startup 自动生成>\"\n    },\n    \"providers\": {},\n    \"modelMappings\": {},\n    \"extraPrompts\": {\n      \"gpt-5-mini\": \"<built-in exploration prompt>\"\n    },\n    \"smallModel\": \"gpt-5-mini\",\n    \"contextManagement\": {\n      \"messages\": true,\n      \"responses\": false\n    },\n    \"modelResponsesApiCompactThresholds\": {\n      \"gpt-5.4\": 217600,\n      \"gpt-5.5\": 217600,\n      \"gpt-5.6-sol\": 231200,\n      \"gpt-5.6-terra\": 231200,\n      \"gpt-5.6-luna\": 231200\n    },\n    \"modelReasoningEfforts\": {\n      \"gpt-5-mini\": \"low\"\n    },\n    \"useMessagesApi\": true,\n    \"useResponsesApiWebSocket\": true,\n    \"useResponsesApiWebSearch\": true,\n    \"messageApiWebSearchModel\": \"gpt-5-mini\"\n  }\n  ```\n- **auth.apiKeys：** 用于普通非 admin 路由的 API key。支持多个 key 轮换使用。请求可通过 `x-api-key: <key>` 或 `Authorization: Bearer <key>` 进行认证。若为空或省略，则普通路由的认证会被禁用。\n- **auth.adminApiKey：** 仅用于 `/admin/*` 路由的单个 admin key。若未配置，服务会在启动时自动生成一个随机 key，并回写到 `config.json`。它同样使用 `x-api-key` 或 `Authorization: Bearer` 这两种头，但普通 `auth.apiKeys` 不能访问 `/admin/*`。\n- **modelMappings：** 用于顶层 `POST /v1/messages`、`POST /v1/messages/count_tokens`、`POST /v1/responses` 和 `POST /v1/chat/completions` 请求的精确 `sourceModel -> targetModel` 重写映射，这几类接口共用同一份规则。省略该字段或保留为 `{}` 时，不会做模型重写。`source` 和 `target` 都必须是非空字符串。`target` 可以是普通模型 ID，也可以是 `provider/model` 形式的别名，例如 `dashscope/qwen3.6-plus`；重写发生在 provider alias 解析之前。这些映射不再按接口区分。`GET/POST /admin/config/model-mappings` 管理接口读写的也只有这个字段。\n- **extraPrompts：** `model -> prompt` 的映射。把 Anthropic 风格请求翻译为 Responses API 时，会将其附加到第一条 system prompt 后面。你可以借此为不同模型注入护栏或指引。缺失的默认项会自动补齐，但不会覆盖你自定义的 prompt。对于 GPT-5.3+ 模型（如 `gpt-5.3-codex`、`gpt-5.4`、`gpt-5.5`），未显式配置时会自动使用内置的 commentary prompt。内置 prompt 会启用带阶段感知的 commentary，让模型在工具调用或更深层推理前先发出简短的用户可见进度说明。\n- **providers：** 全局上游 provider 映射。每个 provider key（例如 `dashscope`）都会变成一个路由前缀（`/dashscope/v1/messages`）。支持 `type: \"anthropic\"`、`type: \"openai-compatible\"` 和 `type: \"openai-responses\"`。顶层客户端也可以在 `/v1/messages`、`/v1/messages/count_tokens`、`/v1/responses` 和 `/v1/chat/completions` 中使用 `model: \"dashscope/model-id\"`；AI gateway 会在转发上游前移除 `dashscope/` 前缀。`openai-compatible` provider 同时支持 chat 和 Messages 流程：`/v1/chat/completions` 会直连上游 `/v1/chat/completions`，而 `/v1/messages` 和 `/:provider/v1/messages` 会先翻译为上游 Chat Completions，再把响应翻译回 Anthropic Messages。`GET /v1/models` 会聚合已启用 provider 的模型，并以 `provider/model-id` 形式返回；单个 provider 的原始模型列表仍可使用 `GET /dashscope/v1/models`。\n  - `enabled`：可选，若省略则默认为 `true`。\n  - `baseUrl`：provider API 的基础 URL，不要带结尾的 endpoint。Anthropic provider 不要带 `/v1/messages`；OpenAI 兼容 provider 不要带 `/v1/chat/completions`；OpenAI Responses provider 不要带 `/v1/responses`。\n  - `apiKey`：作为上游凭据值使用；普通 provider 必须配置。\n  - `authType`：可选，控制 `apiKey` 如何发送到上游。普通 provider 支持 `x-api-key` 和 `authorization`。Anthropic provider 默认 `x-api-key`；OpenAI 兼容和 OpenAI Responses provider 默认 `authorization`。当设置为 `authorization` 时，代理会发送 `Authorization: Bearer <apiKey>`。`oauth2` 仅保留给内置 `codex` provider，并由 `auth login --provider codex` 自动写入。\n  - `pricingCurrency`：可选，provider 维度的 token 费用币种，例如 `USD` 或 `CNY`。快捷 provider 默认 DashScope、DeepSeek 为 `CNY`，Codex/OpenRouter 为 `USD`。费用按币种分别汇总，不做汇率换算。\n  - `models`：可选，按模型 ID 配置的映射。每个键为请求中的模型名，值支持：\n    - `temperature`：可选，当请求未指定时使用的默认温度。\n    - `topP`：可选，当请求未指定时使用的默认 `top_p`。\n    - `topK`：可选，当请求未指定时使用的默认 `top_k`。\n    - `extraBody`：可选，按模型合入上游请求体的动态字段；请求体显式同名字段优先。OpenAI 兼容 provider 可用它配置 `enable_thinking`、`preserve_thinking`、`reasoning_effort` 等字段。`thinking_budget` 是 OpenAI 兼容 provider 的特殊覆盖项：配置在 `extraBody` 后，会在 Anthropic `thinking.budget_tokens` 翻译之后强制写入，并覆盖请求派生出的预算值。对于 provider name 为 `dashscope` 或 `baseUrl` 包含 `aliyuncs.com` 的 provider，请求派生的 `thinking_budget`（来自 Anthropic `thinking.budget_tokens`）会转发给上游；其他 OpenAI 兼容 provider 会移除请求派生的 `thinking_budget`，但 `extraBody` 中的 `thinking_budget` 仍然生效。对于 DashScope provider，当 `preserve_thinking` 未在 `extraBody` 或请求体中显式设置时，默认为 `true`。\n    - `pricing`：可选，按模型配置 token 单价，币种使用 provider 的 `pricingCurrency`，单位为每 100 万 tokens。支持 `input`、`output`、`cachedInput`（隐式缓存读）、`explicitCachedInput`（显式缓存读）和 `cacheCreationInput`。如需按输入 token 总量分档，可用带 `maxInputTokens` 的 `tiers`。\n    - `contextCache`：可选，provider name 为 `dashscope` 或 `baseUrl` 包含 `aliyuncs.com` 时默认 `true`，其他 OpenAI 兼容 provider 默认 `false`。用于启用阿里云百炼/DashScope 的显式缓存（explicit context cache），会按其 Context Cache 格式在最多 4 个 content block 上注入 `cache_control: { \"type\": \"ephemeral\" }`。缓存断点策略与 opencode 主链路保持一致：前 2 条 system 消息 + 最后 2 条非 system 消息。标记字符串 content 时会把 `system` / `user` / `assistant` / `tool` 消息转换为 text content part 数组；已有数组 content 则标记最后一个 part。如果模型本身已经支持隐式缓存，或上游不支持该显式缓存扩展字段，可在模型配置中设为 `false`。支持相同显式缓存扩展的非 DashScope provider 可设为 `true`。同时适用于 `/v1/messages` 和 `/v1/chat/completions` 路由。\n    - `supportPdf`：可选，控制该模型是否支持 PDF/document content。默认 `false`，不支持时会把 PDF 转成提示文本；设为 `true` 时会把 PDF/document 转成 OpenAI Chat Completions 的 file part。\n    - `toolContentSupportType`：可选，配置该模型的 tool result content 支持能力，值为 `array`、`image`、`pdf` 的数组。provider 侧未配置时默认只发送 string tool content。若 `supportPdf` 为 `true` 但这里不包含 `pdf`，tool result 里的 file part 会被转成 user role 消息。Copilot 主链路不使用这个 provider 默认，仍按 array + image 且不支持 PDF 的能力处理。\n    - `type`：可选，按模型覆盖 provider 的协议类型。支持 `anthropic`、`openai-compatible` 和 `openai-responses`。设置后，provider 的 `/v1/messages` 路由会使用该模型的 type 替代 provider 级别的 type 进行请求路由、认证头解析和上游端点选择。适用于 OpenCode Go 等上游对不同模型同时支持 OpenAI 兼容和 Anthropic Messages API 的 provider。覆盖 type 时，认证头按覆盖后 type 的默认值解析（Anthropic 默认 `x-api-key`；OpenAI 兼容/Responses 默认 `authorization`）。\n\n  DashScope 模型配置示例：\n  ```json\n  {\n    \"providers\": {\n      \"dashscope\": {\n        \"type\": \"openai-compatible\",\n        \"enabled\": true,\n        \"baseUrl\": \"https://dashscope.aliyuncs.com/compatible-mode\",\n        \"apiKey\": \"sk-your-dashscope-key\",\n        \"pricingCurrency\": \"CNY\",\n        \"models\": {\n          \"qwen3.7-plus\": {\n            \"temperature\": 1,\n            \"topP\": 0.95,\n            \"topK\": 20,\n            \"extraBody\": {\n              \"preserve_thinking\": true\n            }\n          },\n          \"glm-5.1\": {\n            \"temperature\": 0.7,\n            \"topP\": 0.95,\n            \"contextCache\": true,\n            \"pricing\": {\n              \"tiers\": [\n                {\n                  \"maxInputTokens\": 32000,\n                  \"input\": 6,\n                  \"cachedInput\": 1.2,\n                  \"explicitCachedInput\": 0.6,\n                  \"cacheCreationInput\": 7.5,\n                  \"output\": 24\n                },\n                {\n                  \"maxInputTokens\": 200000,\n                  \"input\": 8,\n                  \"cachedInput\": 1.6,\n                  \"explicitCachedInput\": 0.8,\n                  \"cacheCreationInput\": 10,\n                  \"output\": 28\n                }\n              ]\n            },\n            \"extraBody\": {\n              \"preserve_thinking\": true\n            }\n          }\n        }\n      }\n    }\n  }\n  ```\n  内置 token 价格覆盖 Codex GPT 模型（USD）、DashScope `qwen3.7-max`、`qwen3.7-plus`、`glm-5.1`、`glm-5.2`（CNY），DeepSeek `deepseek-v4-flash`、`deepseek-v4-pro`、`deepseek-chat`、`deepseek-reasoner`（CNY），以及 OpenCode Go 模型（`glm-5.2`、`deepseek-v4-flash`、`deepseek-v4-pro`、`kimi-k2.7-code`、`mimo-v2.5`、`mimo-v2.5-pro`、`qwen3.7-plus`、`qwen3.7-max`、`minimax-m2.5`、`minimax-m3`，USD）。用户配置的 `pricing` 优先于内置价格。DashScope 若上游 usage 中出现 `cache_creation_input_tokens` 字段，cached tokens 按显式缓存读价计费；否则 `cachedInput` 作为隐式缓存读价。DeepSeek 的 `prompt_cache_hit_tokens` 会归入 cached input，`prompt_cache_miss_tokens` 会归入普通 input。\n- **smallModel：** 无工具预热消息的回退模型（例如 Claude Code 的探测请求）；默认是 `gpt-5-mini`。\n- **contextManagement：** 控制代理是否为 Responses API 附加 `context_management` 压缩指令。`messages` 作用于被翻译成 Responses API 的 Anthropic 风格 `/v1/messages` 请求，包括 `openai-responses` provider 的 Messages 路由，默认值为 `true`。`responses` 作用于 native `/v1/responses` 流量，包括 `provider/model` 别名和内置 `codex` provider，默认值为 `false`。只有在确认客户端支持 context management compaction 后，才建议在 Responses API 下启用 `responses`。启用后，请求体会带上 `context_management`，并在后续轮次中仅保留最新的压缩承载内容。\n- **modelResponsesApiCompactThresholds：** 按模型覆盖 Responses API 的 `compact_threshold`，仅在代理自动附加 `context_management` 时使用。它的优先级高于 `resolveResponsesCompactThreshold` 基于 `max_prompt_tokens * ratio` 的兜底阈值。默认将 `gpt-5.4` 和 `gpt-5.5` 设为 `217600`（`272000 * 0.8`），将 `gpt-5.6-sol`、`gpt-5.6-terra`、`gpt-5.6-luna` 设为 `231200`（`272000 * 0.85`）。未列出的模型继续使用原有兜底逻辑。\n- **modelReasoningEfforts：** 按模型配置的推理强度，仅作用于 `/v1/messages` 请求。当请求走 Copilot 原生 Messages API 时设置 `output_config.effort`；当请求被翻译为 Responses API 时设置 `reasoning.effort`。可选值包括 `none`、`minimal`、`low`、`medium`、`high`、`xhigh` 和 `max`。若某模型未配置，则默认使用 `high`；GPT-5.3+ 模型未显式配置时回退为 `xhigh`。\n- **useMessagesApi：** 当为 `true` 时，支持 Copilot 原生 `/v1/messages` 的 Claude 系模型会走 Messages API；否则回退到 `/chat/completions`。设为 `false` 可禁用 Messages API 路由，始终使用 `/chat/completions`。默认值为 `true`。\n- **useResponsesApiWebSocket：** 当为 `true` 时，Responses API 请求会优先对声明了 `ws:/responses` 的模型使用 Copilot websocket transport；仅声明 `/responses` 的模型仍走 HTTP。设为 `false` 可禁用 websocket 路由，并在模型支持 `/responses` 时使用 HTTP `/responses`。默认值为 `true`。\n- **useResponsesApiWebSearch：** 当为 `true` 时，服务端会保留 Responses API 中 `type: \"web_search\"` 的工具并透传到上游。设为 `false` 则会从 `/responses` payload 中移除这些工具。默认值为 `true`。\n- **messageApiWebSearchModel：** 顶层 Copilot `/v1/messages` 请求只包含服务端 `web_search` 工具时使用的全局模型，默认值为 `gpt-5-mini`。如果该值是 `provider/model` 别名，请求会进入对应 provider 的 Messages API 路径，并在转发前移除 provider 前缀。对于 Copilot GPT 模型，web search 会通过 `/responses` 执行。混合 `web_search` 与自定义工具的场景暂不支持，服务端会移除 server-side `web_search`。\n- **claudeTokenMultiplier：** 用于 Claude `/v1/messages/count_tokens` 请求在本地走 GPT tokenizer 估算时的乘数。默认值为 `1.15`。如果你的客户端仍然过晚触发上下文压缩，可以适当调大。这个配置只会在代理本地估算 Claude token 时生效；如果已经配置 `anthropicApiKey` 且 Anthropic token counting 调用成功，则会直接返回 Anthropic 的精确计数，不会使用这个乘数。\n- **anthropicApiKey：** 用于把 Claude `/v1/messages/count_tokens` 请求转发到 Anthropic 真实 token counting 端点的 API key，这样会返回精确计数，而不是 GPT tokenizer 估算值。也可通过环境变量 `ANTHROPIC_API_KEY` 设置。若未配置，或上游调用失败，则回退到由 `claudeTokenMultiplier` 控制的本地 GPT tokenizer 估算。\n\n编辑此文件后即可自定义 prompts，或替换为你自己的快速模型。修改完成后请重启服务（或重新执行命令），让缓存中的配置刷新生效。\n\n## API 认证\n\n- **受保护的普通路由：** 当配置了 `auth.apiKeys` 且非空时，除 `/`、`/usage-viewer` 和 `/usage-viewer/` 以外的普通路由都需要认证。\n- **Admin 路由：** 所有 `/admin/*` 路由都要求 `auth.adminApiKey`。如果缺失，服务会在启动时自动生成并在开始提供服务前写回 `config.json`。\n- **允许的认证头：**\n  - `x-api-key: <your_key>`\n  - `Authorization: Bearer <your_key>`\n- **CORS 预检：** `OPTIONS` 请求始终允许。\n- **未配置普通 key 时：** 普通路由仍可直接访问；但这条规则不适用于 `/admin/*`，后者只接受 `auth.adminApiKey`。\n\n普通受保护路由的示例请求：\n\n```sh\ncurl http://localhost:4141/v1/models \\\n  -H \"x-api-key: your_api_key\"\n```\n\nAdmin 路由的示例请求：\n\n```sh\ncurl http://localhost:4141/admin/config/model-mappings \\\n  -H \"x-api-key: your_admin_api_key\"\n```\n\n## API 端点\n\n服务端提供多个 OpenAI / Anthropic 兼容端点。请求会根据所选模型和 `provider/model` 别名路由到 GitHub Copilot、内置 `codex` provider 或已配置的 provider。\n\n### OpenAI 兼容端点\n\n这些端点模拟 OpenAI API 结构。\n\n| 端点 | 方法 | 说明 |\n| --- | --- | --- |\n| `POST /v1/responses` | `POST` | OpenAI 中用于生成模型响应的高级接口。支持 `openai-responses` provider 的 `provider/model` 别名。 |\n| `POST /v1/chat/completions` | `POST` | 为给定聊天对话创建模型响应。支持 `openai-compatible` provider 的 `provider/model` 别名；目标 provider 已配置时可在没有 Copilot 的情况下使用。 |\n| `GET /v1/models` | `GET` | 列出 Copilot 模型以及已启用 provider 的 `provider/model-id` 模型。 |\n| `POST /v1/embeddings` | `POST` | 创建表示输入文本的向量嵌入。 |\n\n### Anthropic 兼容端点\n\n这些端点设计为兼容 Anthropic Messages API。\n\n| 端点 | 方法 | 说明 |\n| --- | --- | --- |\n| `POST /v1/messages` | `POST` | 为给定对话创建模型响应。支持已配置 provider 的 `provider/model` 别名，包括通过 `openai-compatible` provider 做翻译。 |\n| `POST /v1/messages/count_tokens` | `POST` | 计算一组消息的 token 数。支持已配置 provider 的 `provider/model` 别名。 |\n| `POST /:provider/v1/messages` | `POST` | 将 Anthropic Messages 请求代理到已配置的 Anthropic provider，或翻译到 OpenAI 兼容 / OpenAI Responses provider。 |\n| `GET /:provider/v1/models` | `GET` | 将模型列表请求代理到已配置的 provider。 |\n| `POST /:provider/v1/messages/count_tokens` | `POST` | 为 provider 路由请求在本地计算 token 数。 |\n\n### 使用量监控端点\n\n用于监控 Copilot 用量与额度的新端点。\n\n| 端点 | 方法 | 说明 |\n| --- | --- | --- |\n| `GET /usage` | `GET` | 获取详细的 Copilot 使用统计与额度信息。 |\n| `GET /token` | `GET` | 获取当前 API 正在使用的 Copilot token。 |\n\n### Admin / 配置端点\n\n这些端点用于本地管理操作，只接受 `auth.adminApiKey`。\n\n| 端点 | 方法 | 说明 |\n| --- | --- | --- |\n| `GET /admin/config/model-mappings` | `GET` | 返回当前 `config.json` 路径以及生效中的 `modelMappings` 映射。 |\n| `POST /admin/config/model-mappings` | `POST` | 只更新 `config.json` 里的 `modelMappings` 字段，并回传更新后的结果。 |\n\n## 使用示例\n\n常用 `npx` 命令：\n\n```sh\n# 基础启动\nnpx @jeffreycao/copilot-api@latest start\n\n# 自定义端口并开启详细日志\nnpx @jeffreycao/copilot-api@latest start --port 8080 --verbose\n\n# 执行认证流程\nnpx @jeffreycao/copilot-api@latest auth login\n\n# 配置第三方 provider，然后不依赖 GitHub Copilot 启动\nnpx @jeffreycao/copilot-api@latest auth login --provider dashscope\nnpx @jeffreycao/copilot-api@latest start\n\n# 以 JSON 格式输出调试信息\nnpx @jeffreycao/copilot-api@latest debug --json\n\n# 用 Bun 而不是 Node.js 运行已发布 CLI\nbunx --bun @jeffreycao/copilot-api@latest start\n```\n\n配置 `dashscope` 后的 OpenAI 兼容 provider 调用示例：\n\n```sh\ncurl http://localhost:4141/v1/chat/completions \\\n  -H \"content-type: application/json\" \\\n  -d '{\"model\":\"dashscope/qwen3.6-plus\",\"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]}'\n\ncurl http://localhost:4141/dashscope/v1/messages \\\n  -H \"content-type: application/json\" \\\n  -d '{\"model\":\"qwen3.6-plus\",\"max_tokens\":1024,\"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]}'\n```\n\n## 使用建议\n\n<a id=\"claudemd-or-agentsmd-recommended-content\"></a>\n\n### CLAUDE.md 或 AGENTS.md 推荐内容\n\n如果你想手动加入这些提醒，请在 Claude Code 的 `CLAUDE.md`，或 opencode/codex 的 `AGENTS.md` 中加入以下内容：\n\n```\n- Prohibited from directly asking questions to users, MUST use question tool.\n- Once you can confirm that the task is complete, MUST use question tool to make user confirm. The user may respond with feedback if they are not satisfied with the result, which you can use to make improvements and try again, after try again, MUST use question tool to make user confirm again.\n```\n"}, "ecd936239220164bbfcfe6f7205a6fce726d0e18": {"t": 1785765567.3562484, "n": 31089, "h": "0fe2cf1618e379be", "c": "# Copilot API Proxy\n\n[English](./README.md) | 简体中文\n\n## 重要说明\n\n> [!IMPORTANT]\n> **使用前请先注意以下几点：**\n>\n> 1. **Claude Code 配置：** 与 Claude Code 搭配使用时，请将模型 ID 配置为 `claude-opus-4-8`。示例 claude `settings.json` 见 [通过 `settings.json` 手动配置](#manual-configuration-with-settingsjson)。\n>\n> 2. **内置 `copilot`、`codex` 与第三方 provider：** 执行 `npx @jeffreycao/copilot-api@latest auth`，可选择 `copilot`、`codex`、`deepseek`、`custom` 等 provider。\n>\n> 3. **注意事项：** README 顶部移除的 GitHub Copilot warning 见 [GitHub Copilot 安全提示](./NOTICE.md#github-copilot-security-notice)。\n\n---\n\n## 项目概览\n\n这是一个小型 AI gateway，可以使用 GitHub Copilot、内置 `codex` provider，也可以使用 DashScope 等已配置的第三方 provider。GitHub Copilot 现在是可选能力：如果本地没有 GitHub token，只要至少配置了一个启用中的 provider，服务仍可按 provider-only 模式启动。\n\nAI gateway 会从同一个本地端点暴露 OpenAI / Anthropic 兼容 API，让 [Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview)、OpenCode、Codex 和 OpenAI 兼容客户端可以共用同一个本地服务。\n\n在 GitHub Copilot 路径上，AI gateway 会在可用时优先使用 Copilot 原生的 Anthropic 风格 Messages API，在重工具调用场景下保留更原生的 Claude 行为。\n\n## 功能特性\n\n- **OpenAI 与 Anthropic 双兼容**：通过 `/v1/responses`、`/v1/chat/completions`、`/v1/models`、`/v1/embeddings` 和 `/v1/messages` 对外暴露同一个本地 AI gateway。\n- **Copilot 可选**：有 GitHub 凭据时可以使用 GitHub Copilot，没有 GitHub 凭据时也可以只依赖已配置的 provider 运行。\n- **同一网关接入 Copilot、`codex` 与第三方 provider**：可统一路由 GitHub Copilot、内置 `codex` provider 和配置好的外部 provider。\n- **第三方 provider 可独立启动**：配置 DashScope、DeepSeek、OpenRouter 或自定义 provider 后，不需要 GitHub Copilot 登录即可启动 AI gateway。\n- **OpenAI 兼容 provider 同时支持 chat 和 Messages API**：`openai-compatible` provider 可通过顶层 `/v1/chat/completions` 搭配 `model: \"provider/model\"` 提供 Chat Completions，也可通过 `/v1/messages` 完成 Anthropic Messages 的请求/响应翻译。\n- **面向 Claude 的更原生 Copilot 路由**：优先使用原生 `/v1/messages`，保留 Claude 风格工具流，支持 Anthropic beta 能力、通过 Responses-capable 模型支持 Claude WebSearch，并保留 subagent / session 标记。\n- **Claude Code 与 OpenCode 集成**：兼容 Claude Code 与 OpenCode，也支持通过 `@ai-sdk/anthropic` 直接作为 Anthropic provider 使用。\n- **灵活的认证与部署选项**：支持交互式登录、直接 token、个人 / Business / Enterprise、GitHub Enterprise、opencode OAuth 和自定义数据目录。\n- **多 provider 路由**：可暴露 `/:provider/...` 路由，也可在顶层 API 上使用 `model: \"provider/model\"`。\n\n## 前置要求\n\n- Bun（>= 1.2.x）\n- 如果要通过 `npx` 运行已发布 CLI，需要 Node.js\n- 只有在使用 GitHub Copilot provider 时，才需要已订阅 Copilot 的 GitHub 账号\n- 如果不使用 GitHub Copilot，需要至少一个已配置 provider 的 API key 或 OAuth 登录\n\n## 安装\n\n安装依赖：\n\n```sh\nbun install\n```\n\n直接从源码启动服务：\n\n```sh\nbun run start start\n```\n\n## 从源码运行\n\n本项目可以通过多种方式从源码运行：\n\n### 开发模式\n\n```sh\nbun run dev start\n```\n\n### 生产模式\n\n```sh\nbun run start start\n```\n\n## 通过 npx 使用\n\n你可以直接用 npx 运行本项目：\n\n> [!IMPORTANT]\n> 通过 `npx` 运行时，token usage 存储会使用 Node 内置的 `node:sqlite` 模块。该能力会在 Node.js >= 22.13.0 时启用；Node.js < 22.13.0 时 CLI 仍可启动，但会禁用 token usage 存储。\n>\n> 如果不升级 Node.js 但仍需要 token usage 存储，可以改用 Bun 运行已发布 CLI：`bunx --bun @jeffreycao/copilot-api@latest start`。\n\n```sh\nnpx @jeffreycao/copilot-api@latest start\n```\n\n带参数示例：\n\n```sh\nnpx @jeffreycao/copilot-api@latest start --port 8080\n```\n\n如果只想做认证或 provider 配置：\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth\n```\n\n如果要不依赖 GitHub Copilot 运行，先配置至少一个 provider，然后正常启动服务：\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth login --provider dashscope\nnpx @jeffreycao/copilot-api@latest start\n```\n\n## 配合 Docker 使用\n\n构建镜像：\n\n```sh\ndocker build -t copilot-api .\n```\n\n通过 bind mount 运行容器，让认证数据在重启后保留：\n\n```sh\nmkdir -p ./copilot-data\ndocker run -p 4141:4141 -v $(pwd)/copilot-data:/root/.local/share/copilot-api copilot-api\n```\n\n这会把宿主机上的 `./copilot-data` 映射到容器内的 `/root/.local/share/copilot-api`，用于持久化 GitHub 认证数据、provider 配置和其他 gateway 状态。\n\n也可以直接通过环境变量传入 GitHub token：\n\n```sh\ndocker run -p 4141:4141 -e GH_TOKEN=your_github_token_here copilot-api\n```\n\n## Electron 桌面应用\n\n如果你更喜欢图形界面，仓库里还提供了位于 `desktop/` 的 Electron 桌面应用。它支持 GitHub Copilot 登录、OpenAI Codex OAuth，以及 DeepSeek、DashScope、OpenRouter 或自定义 provider 的 API Key 配置。授权或配置 provider 后，可以一键启动或停止本地代理，并在界面里直接查看本地端点、鉴权 Header、可用模型、额度和日志。\n\n设置页还可以配置 `OAuth App`、`API Home`、`Enterprise URL`、详细日志以及最小化到托盘。桌面安装包发布在 GitHub Releases：\n\nhttps://github.com/caozhiyuan/copilot-api/releases\n\n下载对应平台的安装包后，在应用内授权或配置 provider，选择端口并启动服务，再把你的客户端指向应用里显示的本地端点即可。发布版桌面应用使用随包内置的 Electron 运行时，正常使用不需要额外安装 Node.js；token usage 历史记录会在该内置运行时支持 SQLite 时启用。\n\n桌面应用里的高级配置页会通过 `GET/POST /admin/config/model-mappings` 读写这份共享的模型映射。同一份映射会统一作用于 `POST /v1/messages`、`POST /v1/messages/count_tokens`、`POST /v1/responses` 和 `POST /v1/chat/completions`，不再按接口区分。它使用的是 `auth.adminApiKey`，不是普通的 `auth.apiKeys`；应用会在服务启动并自动生成该 key 后，直接从 `config.json` 读取它来发起请求。\n\n### 桌面应用截图\n\n下面展示了桌面应用中的首页、Token 用量统计页面：\n\n<p align=\"center\">\n  <img src=\"./docs/screenshots/desktop-dashboard.png\" alt=\"Copilot API 桌面应用首页\" width=\"49%\" />\n  <img src=\"./docs/screenshots/desktop-token-usage.png\" alt=\"Copilot API 桌面应用 Token 用量页\" width=\"49%\" />\n</p>\n\n## 与 Claude Code 一起使用\n\n这个 AI gateway 可以为 [Claude Code](https://docs.anthropic.com/en/claude-code) 提供后端能力。Claude Code 是 Anthropic 提供的实验性面向开发者的对话式 AI 助手。\n\n有两种方式可以把 Claude Code 配置为使用这个 AI gateway：\n\n### 通过 `--claude-code` 标志进行交互式配置\n\n执行带 `--claude-code` 的 `start` 命令开始：\n\n```sh\nnpx @jeffreycao/copilot-api@latest start --claude-code\n```\n\n你会被提示选择一个主模型，以及一个用于后台任务的 \"small, fast\" 模型。选择完成后，会有一条命令被复制到剪贴板中。该命令会设置 Claude Code 使用这个 AI gateway 所需的环境变量。\n\n在新的终端中粘贴并执行这条命令，即可启动 Claude Code。\n\n<a id=\"manual-configuration-with-settingsjson\"></a>\n\n### 通过 `settings.json` 手动配置\n\n另一种方式是在项目根目录中创建 `.claude/settings.json` 文件，并写入 Claude Code 所需的环境变量。这样你就不需要每次都运行交互式配置了。\n\n下面是一个 `.claude/settings.json` 示例：\n\n```json\n{\n  \"env\": {\n    \"ANTHROPIC_BASE_URL\": \"http://localhost:4141\",\n    \"ANTHROPIC_AUTH_TOKEN\": \"dummy\",\n    \"ANTHROPIC_MODEL\": \"deepseek/deepseek-v4-pro\",\n    \"ANTHROPIC_DEFAULT_SONNET_MODEL\": \"deepseek/deepseek-v4-pro\",\n    \"ANTHROPIC_DEFAULT_HAIKU_MODEL\": \"deepseek/deepseek-v4-flash\",\n    \"DISABLE_NON_ESSENTIAL_MODEL_CALLS\": \"1\",\n    \"CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC\": \"1\",\n    \"CLAUDE_CODE_ATTRIBUTION_HEADER\": \"0\",\n    \"CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION\": \"false\",\n    \"CLAUDE_CODE_DISABLE_TERMINAL_TITLE\": \"true\",\n    \"CLAUDE_CODE_ENABLE_AWAY_SUMMARY\": \"0\"\n  },\n  \"permissions\": {\n    \"deny\": [\n      \"mcp__ide__executeCode\"\n    ]\n  }\n}\n```\n\n- 请根据需要替换 `ANTHROPIC_MODEL`、`ANTHROPIC_DEFAULT_OPUS_MODEL`、`ANTHROPIC_DEFAULT_SONNET_MODEL` 和 `ANTHROPIC_DEFAULT_HAIKU_MODEL`。配置完成后，请安装 claude code 插件，见 [插件集成](#plugin-integrations)。\n- 将 `CLAUDE_CODE_ATTRIBUTION_HEADER` 设为 `0` 可以阻止 Claude Code 在 system prompt 中附加计费和版本信息，从而避免 prompt cache 失效。\n- 关闭 `CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION` 和 `CLAUDE_CODE_ENABLE_AWAY_SUMMARY` 可以避免不必要地消耗额度。\n- Claude Code WebSearch 已支持纯搜索请求。Copilot 路径请保持全局 `messageApiWebSearchModel` 指向 Responses-capable GPT 模型或 `provider/model` 别名；provider 路由请使用原生 Anthropic provider 或 `openai-responses` provider。只有在你明确想禁止这类流量时，才需要把 `WebSearch` 加到 `permissions.deny`。\n- 如果使用的不是 Claude 模型，请不要启用 `ENABLE_TOOL_SEARCH`。如果使用的是 Claude 模型，则可以启用 `ENABLE_TOOL_SEARCH`。当前 Claude Code 使用的是客户端 tool search 模式，在该模式下每次加载 defer tools 都需要额外请求一次。\n- `CLAUDE_CODE_AUTO_COMPACT_WINDOW`：设置用于自动压缩计算的上下文容量（以 token 为单位）。默认使用模型自身的上下文窗口：标准模型为 200K，扩展上下文模型为 1M。使用 1M 上下文模型（如 `claude-opus-4-6[1m]`）时，可设置一个较低的值（如 `500000`）将窗口视为 500K 用于压缩计算。该值受限于模型的实际上下文窗口上限。`CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` 会基于此值的百分比生效。设置此变量可将压缩阈值与状态栏的 `used_percentage` 解耦（后者始终使用模型的完整上下文窗口）。\n\n更多选项见：[Claude Code settings](https://docs.anthropic.com/en/docs/claude-code/settings#environment-variables)\n\n也可以参考 IDE 集成说明：[Add Claude Code to your IDE](https://docs.anthropic.com/en/docs/claude-code/ide-integrations)\n\n## 与 OpenCode 一起使用\n\nOpenCode 已经有直接的 GitHub Copilot provider。本节适用于你希望让 OpenCode 通过 `@ai-sdk/anthropic` 指向这个 AI gateway，并复用本 README 前面提到的 agent 行为时。\n\n### 最小配置\n\n使用 OpenCode OAuth app 启动 AI gateway：\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth --oauth-app=opencode\nnpx @jeffreycao/copilot-api@latest start\n```\n\n然后让 OpenCode 通过 `@ai-sdk/anthropic` 指向这个 AI gateway。\n\n示例 `~/.config/opencode/opencode.json`：\n\n```json\n{\n  \"$schema\": \"https://opencode.ai/config.json\",\n  \"provider\": {\n    \"local\": {\n      \"npm\": \"@ai-sdk/anthropic\",\n      \"name\": \"My Local\",\n      \"options\": {\n        \"baseURL\": \"http://localhost:4141/v1\",\n        \"apiKey\": \"dummy\"\n      },\n      \"models\": {\n        \"gpt-5.4\": {\n          \"name\": \"gpt-5.4\",\n          \"modalities\": {\n            \"input\": [\"text\", \"image\"],\n            \"output\": [\"text\"]\n          },\n          \"limit\": {\n            \"context\": 400000,\n            \"input\": 272000,\n            \"output\": 128000\n          }\n        },\n        \"claude-sonnet-4.6\": {\n          \"id\": \"claude-sonnet-4.6\",\n          \"name\": \"claude-sonnet-4.6\",\n          \"modalities\": {\n            \"input\": [\"text\", \"image\"],\n            \"output\": [\"text\"]\n          },\n          \"limit\": {\n            \"context\": 200000,\n            \"output\": 32000\n          },\n          \"options\": {\n            \"thinking\": {\n              \"type\": \"adaptive\"\n            },\n            \"effort\": \"max\"\n          }\n        }\n      }\n    }\n  }\n}\n```\n\n这些字段的重要性：\n\n- `npm: \"@ai-sdk/anthropic\"` 是关键。OpenCode 会以 Anthropic Messages 语义与这个 AI gateway 通信，而不是把一切扁平化为 OpenAI Chat Completions。\n- `options.baseURL` 应设为 `http://localhost:4141/v1`；Anthropic SDK 会自动补上 `/messages`、`/models` 和 `/messages/count_tokens`。\n- 如果你在此代理中启用了 `auth.apiKeys`，请把 `dummy` 替换为真实 key；否则任意占位值都可以。\n\n## 与 Codex 一起使用\n\n这个 AI gateway 也可以为 Codex 提供后端能力。\n\n### Codex `config.toml` 参考配置\n\n把以下 `[model_providers.copilot_api]` 段加入你的 Codex `~/.codex/config.toml`：\n\n```toml\nmodel_provider = \"copilot_api\"\nmodel_reasoning_summary = \"auto\"\nmodel_verbosity = \"medium\"\nmodel_context_window = 272000\nmodel_auto_compact_token_limit = 244800\n\n[model_providers.copilot_api]\nname = \"OpenAI\"\nbase_url = \"http://localhost:4141\"\nenv_key = \"GITHUB_COPILOT_API_KEY\"\nrequires_openai_auth = true\nsupports_websockets = false\nwire_api = \"responses\"\nrequest_max_retries = 3\nstream_max_retries = 1\nstream_idle_timeout_ms = 300000\n\n[features]\nremote_compaction_v2 = true\n\n[analytics]\nenabled = false\n```\n\n> [!NOTE]\n> 此配置仅限于 Codex 与 GitHub Copilot provider。`name` 一定要配置为 `\"OpenAI\"`。它可以缓解 Codex local compact 不命中缓存的问题。如果你开启了 `contextManagement.responses`（Responses API context management 压缩），通常不会走到 `remote_compaction_v2` 或者 local compact，但如果工具返回 tokens 过大，仍有可能触发。在 native Responses API 流量下启用前，请先确认客户端支持 context management compaction。\n\n## GPT Tool Search\n\n对于 `gpt-5.4+` 这类 GPT Responses 模型，这个 AI gateway 可以通过一个很小的 MCP bridge 暴露 Responses `tool_search`。Claude Code 和 opencode 都可以使用同一个 bridge，前提是客户端会加载 MCP server，并且 Anthropic Messages 流量会经过这个 AI gateway。\n\nGPT 模型不要设置 Claude Code 原生的 `ENABLE_TOOL_SEARCH`。这个开关启用的是 Claude Code 自己的客户端 tool search 模式，可能导致 deferred 工具定义不再转发给 AI gateway。这个 AI gateway 需要完整的工具定义，这样才能只保留那一小组常驻加载工具，其余工具统一转换为 Responses deferred namespace。\n\n如果你安装了 `tool-search@copilot-api-marketplace`，Claude Code 会自动带上这个 MCP bridge，可以跳过下面这段 Claude Code MCP 手动配置。\n\n请把 tool search bridge 加到 Claude Code 使用的 MCP 配置中：\n\n```json\n{\n  \"mcpServers\": {\n    \"tool_search\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@jeffreycao/copilot-api@latest\", \"mcp\"]\n    }\n  }\n}\n```\n\n请把 tool search bridge 加到 opencode 使用的 MCP 配置中：\n\n```json\n{\n  \"mcp\": {\n    \"tool_search\": {\n      \"type\": \"local\",\n      \"command\": [\"npx\", \"-y\", \"@jeffreycao/copilot-api@latest\", \"mcp\"]\n    }\n  }\n}\n```\n\n本地开发时可以将命令换成 `bun`，参数换成 `[\"run\", \"./src/main.ts\", \"mcp\"]`。\n\nAI gateway 内部现在会把 OpenAI Responses `tool_search` 配置成 client-executed 模式。deferred tools 仍然会作为可搜索 namespace 暴露给模型，但会明确要求模型直接返回下一步要加载的精确工具名列表。\n\n该 bridge 使用直接工具选择，不做 query 搜索。工具入参是 `names`，值为逗号分隔的精确 deferred 工具名，例如 `TaskList,TaskGet,mcp__fetch__fetch`。\n\n<a id=\"plugin-integrations\"></a>\n\n## 插件集成\n\n本项目为 Claude Code 和 opencode 提供了插件集成。\n\n#### Claude Code 插件集成（基于 marketplace）\n\nClaude Code 集成现在拆分为两个插件：\n\n- `agent-inject` 会在 `SubagentStart` 时注入 `__SUBAGENT_MARKER__...`，以便 AI gateway 推导 `x-initiator: agent`。\n- `tool-search` 会注册用于 GPT Responses deferred tool loading 的 `tool_search` MCP bridge。\n\n- 本仓库中的 marketplace catalog：`.claude-plugin/marketplace.json`\n- 本仓库中的插件源码：`plugin/claude/agent-inject`、`plugin/claude/tool-search`\n\n远程添加 marketplace：\n\n```sh\n/plugin marketplace add https://github.com/caozhiyuan/copilot-api.git\n```\n\n从 marketplace 安装插件：\n\n```sh\n/plugin install agent-inject@copilot-api-marketplace\n/plugin install tool-search@copilot-api-marketplace\n```\n\n安装后，`agent-inject` 会在 `SubagentStart` 时注入 `__SUBAGENT_MARKER__...`，AI gateway 会利用它推导 `x-initiator: agent`。\n\n`agent-inject` 还会注册一个 `UserPromptSubmit` hook，并返回 `{\"continue\": true}`；同时它也可以通过环境变量注入 `SessionStart` reminder 规则：\n\n- `CLAUDE_PLUGIN_ENABLE_QUESTION_RULES=1` 会自动为 Claude Code 启用两条关于使用 `question` 工具的提醒。你也可以把同样的提醒手动写进 `CLAUDE.md`；见 [CLAUDE.md 或 AGENTS.md 推荐内容](#claudemd-or-agentsmd-recommended-content)。\n- `CLAUDE_PLUGIN_ENABLE_NO_BACKGROUND_AGENTS_RULE=1` 会启用关于避免在 agent hooks 中使用 `run_in_background: true` 的提醒。\n\n`tool-search` 插件内置了 [GPT Tool Search](#gpt-tool-search) 一节描述的同一个 MCP bridge，因此安装该插件后，Claude Code 用户无需再手动配置 `tool_search` server。\n\n#### Opencode 插件\n\nsubagent 标记生成器被打包为一个 opencode 插件，位于 `plugin/opencode/subagent-marker.js`。\n\n**安装方式：**\n\n将插件文件复制到你的 opencode 插件目录：\n\n```sh\n# 克隆或下载本仓库后复制该插件\ncp plugin/opencode/subagent-marker.js ~/.config/opencode/plugins/\n```\n\n或者手动在 `~/.config/opencode/plugins/subagent-marker.js` 创建该文件，并填入插件内容。\n\n**功能：**\n\n- 跟踪 subagent 创建的子会话\n- 自动在 subagent 聊天消息前添加 marker system reminder（`__SUBAGENT_MARKER__...`）\n- 设置 `x-session-id` 请求头以跟踪会话\n- 让这个 AI gateway 能够把来自 subagent 的请求识别为 `x-initiator: agent`\n\n该插件会挂接到 `session.created`、`session.deleted`、`chat.message` 和 `chat.headers` 事件上，以无缝提供 subagent marker 能力。\n\n## 使用量查看器\n\n服务启动后，控制台会输出一个 Copilot 使用量看板 URL。这个看板是一个用于监控 API 用量的 Web 界面。\n\n1. 启动服务。例如使用 npx：\n   ```sh\n   npx @jeffreycao/copilot-api@latest start\n   ```\n2. 服务会输出一个 usage viewer 的 URL。将它复制到浏览器中打开，形式大致如下：\n   `http://localhost:4141/usage-viewer?endpoint=http://localhost:4141/usage`\n   - 如果你在 Windows 上使用 `start.bat` 脚本，这个页面会自动打开。\n\n看板提供了更易读的 Copilot 用量视图：\n\n> token usage 历史记录需要 Bun 或 Node.js >= 22.13.0。Node.js < 22.13.0 时服务会正常运行，但 token usage 存储会被禁用。\n\n- **API Endpoint URL**：通过 URL 查询参数指定 API endpoints，默认指向本地服务。支持手动切换为其他兼容 endpoints。\n- **x-api-key 认证**：如果启用了 API Key 认证，可填入 `x-api-key` 请求头。密钥会持久化保存在浏览器本地存储中。\n- **Period 选择器**：支持 Day / Week / Month 三种时间范围，切换时 URL 参数会自动同步，方便收藏和分享。\n- **Fetch Data**：点击 \"Refresh\" 按钮加载或刷新使用数据。页面加载时也会自动拉取数据。\n- **Copilot Quotas 额度**：通过进度条展示 Chat、Completions 等不同服务的额度使用情况，悬停可查看已用/剩余详情。\n- **Token Usage 指标卡片**：汇总当前周期的 Total、Input、Output、Cache Read、Cache Write、Requests 和预估费用。\n- **趋势图（Week / Month）**：提供按模型和指标筛选的折线趋势图，点击数据点可查看单日用量明细。\n- **Model Breakdown 表格**：按模型维度列出周期内的请求数、输入/输出/缓存 token 和预计费用。\n- **Request Events 分页列表**：按时间排序的请求事件记录，支持分页浏览，含时间戳、模型、请求 ID 和 token 用量。\n- **Detailed Information**：展示 API 返回的完整 JSON 响应，便于深入分析所有可用统计数据。\n- **URL-based Configuration**：也可通过 `endpoint` 和 `period` 查询参数直接指定 API 端点与时间范围。例如：\n  `http://localhost:4141/usage-viewer?endpoint=http://your-api-server/usage&period=week`\n\n### Usage Viewer 截图\n\n<p align=\"center\">\n  <img src=\"./docs/screenshots/usage-viewer.png\" alt=\"Copilot API Usage Viewer 页面\" width=\"900\" />\n</p>\n\n## 命令结构\n\nCopilot API 现在使用子命令结构，主要命令包括：\n\n- `start`：启动 AI gateway 服务。如果已有 GitHub token，则启用 Copilot 路径；如果没有 GitHub token，但存在至少一个启用中的 provider，则按 provider-only 模式启动；如果两者都没有，会引导你配置 provider。\n- `auth`：仅执行 provider 登录或配置流程，不启动服务。可用于 GitHub Copilot 登录、Codex OAuth，或第三方 provider API key 配置。\n- `debug`：显示诊断信息，包括版本、运行时详情、文件路径以及认证状态，便于排障与支持。\n\n## 命令行选项\n\n### 全局选项\n\n以下选项可用于任意子命令。若在子命令之前传入，请使用 `--key=value` 形式：\n\n| 选项 | 说明 | 默认值 | 别名 |\n| --- | --- | --- | --- |\n| --api-home | API home 目录路径（设置 `COPILOT_API_HOME`） | 无 | 无 |\n| --oauth-app | OAuth app 标识符（设置 `COPILOT_API_OAUTH_APP`） | 无 | 无 |\n| --enterprise-url | GitHub Enterprise URL（设置 `COPILOT_API_ENTERPRISE_URL`） | 无 | 无 |\n\n### Start 命令选项\n\n以下是 `start` 命令可用的命令行选项：\n\n| 选项 | 说明 | 默认值 | 别名 |\n| --- | --- | --- | --- |\n| --port | 监听端口 | 4141 | -p |\n| --verbose | 启用详细日志 | false | -v |\n| --github-token | 直接提供 GitHub token（必须通过 `auth` 子命令生成） | 无 | -g |\n| --claude-code | 生成一个使用 Copilot API 配置启动 Claude Code 的命令 | false | -c |\n| --show-token | 在获取和刷新时显示 GitHub 与 Copilot token | false | 无 |\n| --proxy-env | 从环境变量初始化代理 | false | 无 |\n\n### Auth 命令选项\n\n| 选项 | 说明 | 默认值 | 别名 |\n| --- | --- | --- | --- |\n| --provider | 要登录或配置的 provider（`copilot`、`codex`、`opencode-go`、`deepseek`、`dashscope`、`openrouter` 或 `custom`） | 交互选择 | 无 |\n| --verbose | 启用详细日志 | false | -v |\n| --show-token | 认证时显示 GitHub token | false | 无 |\n\n只有在需要启用 GitHub Copilot provider 时，才需要执行 `copilot-api auth login --provider copilot`。使用 `codex` 或第三方 provider-only 模式不要求配置 Copilot。\n\n使用 `copilot-api auth login --provider deepseek`、`--provider dashscope`、`--provider openrouter` 或 `--provider opencode-go` 可以通过 CLI 快速新增或更新这些常用第三方 provider。DeepSeek 会提示输入掩码显示的 `apiKey`、provider `type`（默认 `anthropic`），以及默认 `https://api.deepseek.com/anthropic` 的 `baseUrl`。DashScope 会提示输入掩码显示的 `apiKey`、provider `type`（默认 `openai-compatible`）和预填默认值的 `baseUrl`。OpenRouter 只提示输入掩码显示的 `apiKey` 和预填默认值的 `baseUrl`，并固定写入 `type: \"anthropic\"`。OpenCode Go 只提示输入掩码显示的 `apiKey` 和预填默认值的 `baseUrl`，并固定写入 `type: \"openai-compatible\"`（baseUrl `https://opencode.ai/zen/go`）。配置并启用 provider 后，`copilot-api start` 可在没有 GitHub token 的情况下启动。\n\n使用 `copilot-api auth login --provider custom` 可以通过 CLI 新增或更新其他第三方 provider。命令会依次提示输入 provider name、项目支持的 type（`anthropic`、`openai-compatible` 或 `openai-responses`）、`baseUrl`、掩码显示的 `apiKey` 和 `authType`；`authType` 可保持 type 默认值，也可选择 `x-api-key` / `authorization`。\n\n### Debug 命令选项\n\n| 选项 | 说明 | 默认值 | 别名 |\n| --- | --- | --- | --- |\n| --json | 以 JSON 输出调试信息 | false | 无 |\n\n<a id=\"configuration-configjson\"></a>\n\n## 配置（config.json）\n\n- **位置：** Linux/macOS 为 `~/.local/share/copilot-api/config.json`，Windows 为 `%USERPROFILE%\\.local\\share\\copilot-api\\config.json`。\n- **默认结构：**\n  ```json\n  {\n    \"auth\": {\n      \"apiKeys\": [],\n      \"adminApiKey\": \"<startup 自动生成>\"\n    },\n    \"providers\": {},\n    \"modelMappings\": {},\n    \"extraPrompts\": {\n      \"gpt-5-mini\": \"<built-in exploration prompt>\"\n    },\n    \"smallModel\": \"gpt-5-mini\",\n    \"contextManagement\": {\n      \"messages\": true,\n      \"responses\": false\n    },\n    \"modelResponsesApiCompactThresholds\": {\n      \"gpt-5.4\": 217600,\n      \"gpt-5.5\": 217600\n    },\n    \"modelReasoningEfforts\": {\n      \"gpt-5-mini\": \"low\"\n    },\n    \"useMessagesApi\": true,\n    \"useResponsesApiWebSocket\": true,\n    \"useResponsesApiWebSearch\": true,\n    \"messageApiWebSearchModel\": \"gpt-5-mini\"\n  }\n  ```\n- **auth.apiKeys：** 用于普通非 admin 路由的 API key。支持多个 key 轮换使用。请求可通过 `x-api-key: <key>` 或 `Authorization: Bearer <key>` 进行认证。若为空或省略，则普通路由的认证会被禁用。\n- **auth.adminApiKey：** 仅用于 `/admin/*` 路由的单个 admin key。若未配置，服务会在启动时自动生成一个随机 key，并回写到 `config.json`。它同样使用 `x-api-key` 或 `Authorization: Bearer` 这两种头，但普通 `auth.apiKeys` 不能访问 `/admin/*`。\n- **modelMappings：** 用于顶层 `POST /v1/messages`、`POST /v1/messages/count_tokens`、`POST /v1/responses` 和 `POST /v1/chat/completions` 请求的精确 `sourceModel -> targetModel` 重写映射，这几类接口共用同一份规则。省略该字段或保留为 `{}` 时，不会做模型重写。`source` 和 `target` 都必须是非空字符串。`target` 可以是普通模型 ID，也可以是 `provider/model` 形式的别名，例如 `dashscope/qwen3.6-plus`；重写发生在 provider alias 解析之前。这些映射不再按接口区分。`GET/POST /admin/config/model-mappings` 管理接口读写的也只有这个字段。\n- **extraPrompts：** `model -> prompt` 的映射。把 Anthropic 风格请求翻译为 Responses API 时，会将其附加到第一条 system prompt 后面。你可以借此为不同模型注入护栏或指引。缺失的默认项会自动补齐，但不会覆盖你自定义的 prompt。对于 GPT-5.3+ 模型（如 `gpt-5.3-codex`、`gpt-5.4`、`gpt-5.5`），未显式配置时会自动使用内置的 commentary prompt。内置 prompt 会启用带阶段感知的 commentary，让模型在工具调用或更深层推理前先发出简短的用户可见进度说明。\n- **providers：** 全局上游 provider 映射。每个 provider key（例如 `dashscope`）都会变成一个路由前缀（`/dashscope/v1/messages`）。支持 `type: \"anthropic\"`、`type: \"openai-compatible\"` 和 `type: \"openai-responses\"`。顶层客户端也可以在 `/v1/messages`、`/v1/messages/count_tokens`、`/v1/responses` 和 `/v1/chat/completions` 中使用 `model: \"dashscope/model-id\"`；AI gateway 会在转发上游前移除 `dashscope/` 前缀。`openai-compatible` provider 同时支持 chat 和 Messages 流程：`/v1/chat/completions` 会直连上游 `/v1/chat/completions`，而 `/v1/messages` 和 `/:provider/v1/messages` 会先翻译为上游 Chat Completions，再把响应翻译回 Anthropic Messages。`GET /v1/models` 会聚合已启用 provider 的模型，并以 `provider/model-id` 形式返回；单个 provider 的原始模型列表仍可使用 `GET /dashscope/v1/models`。\n  - `enabled`：可选，若省略则默认为 `true`。\n  - `baseUrl`：provider API 的基础 URL，不要带结尾的 endpoint。Anthropic provider 不要带 `/v1/messages`；OpenAI 兼容 provider 不要带 `/v1/chat/completions`；OpenAI Responses provider 不要带 `/v1/responses`。\n  - `apiKey`：作为上游凭据值使用；普通 provider 必须配置。\n  - `authType`：可选，控制 `apiKey` 如何发送到上游。普通 provider 支持 `x-api-key` 和 `authorization`。Anthropic provider 默认 `x-api-key`；OpenAI 兼容和 OpenAI Responses provider 默认 `authorization`。当设置为 `authorization` 时，代理会发送 `Authorization: Bearer <apiKey>`。`oauth2` 仅保留给内置 `codex` provider，并由 `auth login --provider codex` 自动写入。\n  - `pricingCurrency`：可选，provider 维度的 token 费用币种，例如 `USD` 或 `CNY`。快捷 provider 默认 DashScope、DeepSeek 为 `CNY`，Codex/OpenRouter 为 `USD`。费用按币种分别汇总，不做汇率换算。\n  - `models`：可选，按模型 ID 配置的映射。每个键为请求中的模型名，值支持：\n    - `temperature`：可选，当请求未指定时使用的默认温度。\n    - `topP`：可选，当请求未指定时使用的默认 `top_p`。\n    - `topK`：可选，当请求未指定时使用的默认 `top_k`。\n    - `extraBody`：可选，按模型合入上游请求体的动态字段；请求体显式同名字段优先。OpenAI 兼容 provider 可用它配置 `enable_thinking`、`preserve_thinking`、`reasoning_effort` 等字段。`thinking_budget` 是 OpenAI 兼容 provider 的特殊覆盖项：配置在 `extraBody` 后，会在 Anthropic `thinking.budget_tokens` 翻译之后强制写入，并覆盖请求派生出的预算值。对于 provider name 为 `dashscope` 或 `baseUrl` 包含 `aliyuncs.com` 的 provider，请求派生的 `thinking_budget`（来自 Anthropic `thinking.budget_tokens`）会转发给上游；其他 OpenAI 兼容 provider 会移除请求派生的 `thinking_budget`，但 `extraBody` 中的 `thinking_budget` 仍然生效。对于 DashScope provider，当 `preserve_thinking` 未在 `extraBody` 或请求体中显式设置时，默认为 `true`。\n    - `pricing`：可选，按模型配置 token 单价，币种使用 provider 的 `pricingCurrency`，单位为每 100 万 tokens。支持 `input`、`output`、`cachedInput`（隐式缓存读）、`explicitCachedInput`（显式缓存读）和 `cacheCreationInput`。如需按输入 token 总量分档，可用带 `maxInputTokens` 的 `tiers`。\n    - `contextCache`：可选，provider name 为 `dashscope` 或 `baseUrl` 包含 `aliyuncs.com` 时默认 `true`，其他 OpenAI 兼容 provider 默认 `false`。用于启用阿里云百炼/DashScope 的显式缓存（explicit context cache），会按其 Context Cache 格式在最多 4 个 content block 上注入 `cache_control: { \"type\": \"ephemeral\" }`。缓存断点策略与 opencode 主链路保持一致：前 2 条 system 消息 + 最后 2 条非 system 消息。标记字符串 content 时会把 `system` / `user` / `assistant` / `tool` 消息转换为 text content part 数组；已有数组 content 则标记最后一个 part。如果模型本身已经支持隐式缓存，或上游不支持该显式缓存扩展字段，可在模型配置中设为 `false`。支持相同显式缓存扩展的非 DashScope provider 可设为 `true`。同时适用于 `/v1/messages` 和 `/v1/chat/completions` 路由。\n    - `supportPdf`：可选，控制该模型是否支持 PDF/document content。默认 `false`，不支持时会把 PDF 转成提示文本；设为 `true` 时会把 PDF/document 转成 OpenAI Chat Completions 的 file part。\n    - `toolContentSupportType`：可选，配置该模型的 tool result content 支持能力，值为 `array`、`image`、`pdf` 的数组。provider 侧未配置时默认只发送 string tool content。若 `supportPdf` 为 `true` 但这里不包含 `pdf`，tool result 里的 file part 会被转成 user role 消息。Copilot 主链路不使用这个 provider 默认，仍按 array + image 且不支持 PDF 的能力处理。\n    - `type`：可选，按模型覆盖 provider 的协议类型。支持 `anthropic`、`openai-compatible` 和 `openai-responses`。设置后，provider 的 `/v1/messages` 路由会使用该模型的 type 替代 provider 级别的 type 进行请求路由、认证头解析和上游端点选择。适用于 OpenCode Go 等上游对不同模型同时支持 OpenAI 兼容和 Anthropic Messages API 的 provider。覆盖 type 时，认证头按覆盖后 type 的默认值解析（Anthropic 默认 `x-api-key`；OpenAI 兼容/Responses 默认 `authorization`）。\n\n  DashScope 模型配置示例：\n  ```json\n  {\n    \"providers\": {\n      \"dashscope\": {\n        \"type\": \"openai-compatible\",\n        \"enabled\": true,\n        \"baseUrl\": \"https://dashscope.aliyuncs.com/compatible-mode\",\n        \"apiKey\": \"sk-your-dashscope-key\",\n        \"pricingCurrency\": \"CNY\",\n        \"models\": {\n          \"qwen3.7-plus\": {\n            \"temperature\": 1,\n            \"topP\": 0.95,\n            \"topK\": 20,\n            \"extraBody\": {\n              \"preserve_thinking\": true\n            }\n          },\n          \"glm-5.1\": {\n            \"temperature\": 0.7,\n            \"topP\": 0.95,\n            \"contextCache\": true,\n            \"pricing\": {\n              \"tiers\": [\n                {\n                  \"maxInputTokens\": 32000,\n                  \"input\": 6,\n                  \"cachedInput\": 1.2,\n                  \"explicitCachedInput\": 0.6,\n                  \"cacheCreationInput\": 7.5,\n                  \"output\": 24\n                },\n                {\n                  \"maxInputTokens\": 200000,\n                  \"input\": 8,\n                  \"cachedInput\": 1.6,\n                  \"explicitCachedInput\": 0.8,\n                  \"cacheCreationInput\": 10,\n                  \"output\": 28\n                }\n              ]\n            },\n            \"extraBody\": {\n              \"preserve_thinking\": true\n            }\n          }\n        }\n      }\n    }\n  }\n  ```\n  内置 token 价格覆盖 Codex GPT 模型（USD）、DashScope `qwen3.7-max`、`qwen3.7-plus`、`glm-5.1`、`glm-5.2`（CNY），DeepSeek `deepseek-v4-flash`、`deepseek-v4-pro`、`deepseek-chat`、`deepseek-reasoner`（CNY），以及 OpenCode Go 模型（`glm-5.2`、`deepseek-v4-flash`、`deepseek-v4-pro`、`kimi-k2.7-code`、`mimo-v2.5`、`mimo-v2.5-pro`、`qwen3.7-plus`、`qwen3.7-max`、`minimax-m2.5`、`minimax-m3`，USD）。用户配置的 `pricing` 优先于内置价格。DashScope 若上游 usage 中出现 `cache_creation_input_tokens` 字段，cached tokens 按显式缓存读价计费；否则 `cachedInput` 作为隐式缓存读价。DeepSeek 的 `prompt_cache_hit_tokens` 会归入 cached input，`prompt_cache_miss_tokens` 会归入普通 input。\n- **smallModel：** 无工具预热消息的回退模型（例如 Claude Code 的探测请求）；默认是 `gpt-5-mini`。\n- **contextManagement：** 控制代理是否为 Responses API 附加 `context_management` 压缩指令。`messages` 作用于被翻译成 Responses API 的 Anthropic 风格 `/v1/messages` 请求，包括 `openai-responses` provider 的 Messages 路由，默认值为 `true`。`responses` 作用于 native `/v1/responses` 流量，包括 `provider/model` 别名和内置 `codex` provider，默认值为 `false`。只有在确认客户端支持 context management compaction 后，才建议在 Responses API 下启用 `responses`。启用后，请求体会带上 `context_management`，并在后续轮次中仅保留最新的压缩承载内容。\n- **modelResponsesApiCompactThresholds：** 按模型覆盖 Responses API 的 `compact_threshold`，仅在代理自动附加 `context_management` 时使用。它的优先级高于 `resolveResponsesCompactThreshold` 基于 `max_prompt_tokens * ratio` 的兜底阈值。默认将 `gpt-5.4` 和 `gpt-5.5` 设为 `217600`（`272000 * 0.8`）。未列出的模型继续使用原有兜底逻辑。\n- **modelReasoningEfforts：** 按模型配置的推理强度，仅作用于 `/v1/messages` 请求。当请求走 Copilot 原生 Messages API 时设置 `output_config.effort`；当请求被翻译为 Responses API 时设置 `reasoning.effort`。可选值包括 `none`、`minimal`、`low`、`medium`、`high`、`xhigh` 和 `max`。若某模型未配置，则默认使用 `high`；GPT-5.3+ 模型未显式配置时回退为 `xhigh`。\n- **useMessagesApi：** 当为 `true` 时，支持 Copilot 原生 `/v1/messages` 的 Claude 系模型会走 Messages API；否则回退到 `/chat/completions`。设为 `false` 可禁用 Messages API 路由，始终使用 `/chat/completions`。默认值为 `true`。\n- **useResponsesApiWebSocket：** 当为 `true` 时，Responses API 请求会优先对声明了 `ws:/responses` 的模型使用 Copilot websocket transport；仅声明 `/responses` 的模型仍走 HTTP。设为 `false` 可禁用 websocket 路由，并在模型支持 `/responses` 时使用 HTTP `/responses`。默认值为 `true`。\n- **useResponsesApiWebSearch：** 当为 `true` 时，服务端会保留 Responses API 中 `type: \"web_search\"` 的工具并透传到上游。设为 `false` 则会从 `/responses` payload 中移除这些工具。默认值为 `true`。\n- **messageApiWebSearchModel：** 顶层 Copilot `/v1/messages` 请求只包含服务端 `web_search` 工具时使用的全局模型，默认值为 `gpt-5-mini`。如果该值是 `provider/model` 别名，请求会进入对应 provider 的 Messages API 路径，并在转发前移除 provider 前缀。对于 Copilot GPT 模型，web search 会通过 `/responses` 执行。混合 `web_search` 与自定义工具的场景暂不支持，服务端会移除 server-side `web_search`。\n- **claudeTokenMultiplier：** 用于 Claude `/v1/messages/count_tokens` 请求在本地走 GPT tokenizer 估算时的乘数。默认值为 `1.15`。如果你的客户端仍然过晚触发上下文压缩，可以适当调大。这个配置只会在代理本地估算 Claude token 时生效；如果已经配置 `anthropicApiKey` 且 Anthropic token counting 调用成功，则会直接返回 Anthropic 的精确计数，不会使用这个乘数。\n- **anthropicApiKey：** 用于把 Claude `/v1/messages/count_tokens` 请求转发到 Anthropic 真实 token counting 端点的 API key，这样会返回精确计数，而不是 GPT tokenizer 估算值。也可通过环境变量 `ANTHROPIC_API_KEY` 设置。若未配置，或上游调用失败，则回退到由 `claudeTokenMultiplier` 控制的本地 GPT tokenizer 估算。\n\n编辑此文件后即可自定义 prompts，或替换为你自己的快速模型。修改完成后请重启服务（或重新执行命令），让缓存中的配置刷新生效。\n\n## API 认证\n\n- **受保护的普通路由：** 当配置了 `auth.apiKeys` 且非空时，除 `/`、`/usage-viewer` 和 `/usage-viewer/` 以外的普通路由都需要认证。\n- **Admin 路由：** 所有 `/admin/*` 路由都要求 `auth.adminApiKey`。如果缺失，服务会在启动时自动生成并在开始提供服务前写回 `config.json`。\n- **允许的认证头：**\n  - `x-api-key: <your_key>`\n  - `Authorization: Bearer <your_key>`\n- **CORS 预检：** `OPTIONS` 请求始终允许。\n- **未配置普通 key 时：** 普通路由仍可直接访问；但这条规则不适用于 `/admin/*`，后者只接受 `auth.adminApiKey`。\n\n普通受保护路由的示例请求：\n\n```sh\ncurl http://localhost:4141/v1/models \\\n  -H \"x-api-key: your_api_key\"\n```\n\nAdmin 路由的示例请求：\n\n```sh\ncurl http://localhost:4141/admin/config/model-mappings \\\n  -H \"x-api-key: your_admin_api_key\"\n```\n\n## API 端点\n\n服务端提供多个 OpenAI / Anthropic 兼容端点。请求会根据所选模型和 `provider/model` 别名路由到 GitHub Copilot、内置 `codex` provider 或已配置的 provider。\n\n### OpenAI 兼容端点\n\n这些端点模拟 OpenAI API 结构。\n\n| 端点 | 方法 | 说明 |\n| --- | --- | --- |\n| `POST /v1/responses` | `POST` | OpenAI 中用于生成模型响应的高级接口。支持 `openai-responses` provider 的 `provider/model` 别名。 |\n| `POST /v1/chat/completions` | `POST` | 为给定聊天对话创建模型响应。支持 `openai-compatible` provider 的 `provider/model` 别名；目标 provider 已配置时可在没有 Copilot 的情况下使用。 |\n| `GET /v1/models` | `GET` | 列出 Copilot 模型以及已启用 provider 的 `provider/model-id` 模型。 |\n| `POST /v1/embeddings` | `POST` | 创建表示输入文本的向量嵌入。 |\n\n### Anthropic 兼容端点\n\n这些端点设计为兼容 Anthropic Messages API。\n\n| 端点 | 方法 | 说明 |\n| --- | --- | --- |\n| `POST /v1/messages` | `POST` | 为给定对话创建模型响应。支持已配置 provider 的 `provider/model` 别名，包括通过 `openai-compatible` provider 做翻译。 |\n| `POST /v1/messages/count_tokens` | `POST` | 计算一组消息的 token 数。支持已配置 provider 的 `provider/model` 别名。 |\n| `POST /:provider/v1/messages` | `POST` | 将 Anthropic Messages 请求代理到已配置的 Anthropic provider，或翻译到 OpenAI 兼容 / OpenAI Responses provider。 |\n| `GET /:provider/v1/models` | `GET` | 将模型列表请求代理到已配置的 provider。 |\n| `POST /:provider/v1/messages/count_tokens` | `POST` | 为 provider 路由请求在本地计算 token 数。 |\n\n### 使用量监控端点\n\n用于监控 Copilot 用量与额度的新端点。\n\n| 端点 | 方法 | 说明 |\n| --- | --- | --- |\n| `GET /usage` | `GET` | 获取详细的 Copilot 使用统计与额度信息。 |\n| `GET /token` | `GET` | 获取当前 API 正在使用的 Copilot token。 |\n\n### Admin / 配置端点\n\n这些端点用于本地管理操作，只接受 `auth.adminApiKey`。\n\n| 端点 | 方法 | 说明 |\n| --- | --- | --- |\n| `GET /admin/config/model-mappings` | `GET` | 返回当前 `config.json` 路径以及生效中的 `modelMappings` 映射。 |\n| `POST /admin/config/model-mappings` | `POST` | 只更新 `config.json` 里的 `modelMappings` 字段，并回传更新后的结果。 |\n\n## 使用示例\n\n常用 `npx` 命令：\n\n```sh\n# 基础启动\nnpx @jeffreycao/copilot-api@latest start\n\n# 自定义端口并开启详细日志\nnpx @jeffreycao/copilot-api@latest start --port 8080 --verbose\n\n# 执行认证流程\nnpx @jeffreycao/copilot-api@latest auth login\n\n# 配置第三方 provider，然后不依赖 GitHub Copilot 启动\nnpx @jeffreycao/copilot-api@latest auth login --provider dashscope\nnpx @jeffreycao/copilot-api@latest start\n\n# 以 JSON 格式输出调试信息\nnpx @jeffreycao/copilot-api@latest debug --json\n\n# 用 Bun 而不是 Node.js 运行已发布 CLI\nbunx --bun @jeffreycao/copilot-api@latest start\n```\n\n配置 `dashscope` 后的 OpenAI 兼容 provider 调用示例：\n\n```sh\ncurl http://localhost:4141/v1/chat/completions \\\n  -H \"content-type: application/json\" \\\n  -d '{\"model\":\"dashscope/qwen3.6-plus\",\"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]}'\n\ncurl http://localhost:4141/dashscope/v1/messages \\\n  -H \"content-type: application/json\" \\\n  -d '{\"model\":\"qwen3.6-plus\",\"max_tokens\":1024,\"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]}'\n```\n\n## 使用建议\n\n<a id=\"claudemd-or-agentsmd-recommended-content\"></a>\n\n### CLAUDE.md 或 AGENTS.md 推荐内容\n\n如果你想手动加入这些提醒，请在 Claude Code 的 `CLAUDE.md`，或 opencode/codex 的 `AGENTS.md` 中加入以下内容：\n\n```\n- Prohibited from directly asking questions to users, MUST use question tool.\n- Once you can confirm that the task is complete, MUST use question tool to make user confirm. The user may respond with feedback if they are not satisfied with the result, which you can use to make improvements and try again, after try again, MUST use question tool to make user confirm again.\n```\n"}, "e4c906ff0da3d9367c09a56332e6a2e82535dfd6": {"t": 1785765571.6025586, "n": 30755, "h": "54668ac66e3f4132", "c": "# Copilot API Proxy\n\n[English](./README.md) | 简体中文\n\n## 重要说明\n\n> [!IMPORTANT]\n> **使用前请先注意以下几点：**\n>\n> 1. **Claude Code 配置：** 与 Claude Code 搭配使用时，请将模型 ID 配置为 `claude-opus-4-8`。示例 claude `settings.json` 见 [通过 `settings.json` 手动配置](#manual-configuration-with-settingsjson)。\n>\n> 2. **内置 `copilot`、`codex` 与第三方 provider：** 执行 `npx @jeffreycao/copilot-api@latest auth`，可选择 `copilot`、`codex`、`deepseek`、`custom` 等 provider。\n>\n> 3. **注意事项：** README 顶部移除的 GitHub Copilot warning 见 [GitHub Copilot 安全提示](./NOTICE.md#github-copilot-security-notice)。\n\n---\n\n## 项目概览\n\n这是一个小型 AI gateway，可以使用 GitHub Copilot、内置 `codex` provider，也可以使用 DashScope 等已配置的第三方 provider。GitHub Copilot 现在是可选能力：如果本地没有 GitHub token，只要至少配置了一个启用中的 provider，服务仍可按 provider-only 模式启动。\n\nAI gateway 会从同一个本地端点暴露 OpenAI / Anthropic 兼容 API，让 [Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview)、OpenCode、Codex 和 OpenAI 兼容客户端可以共用同一个本地服务。\n\n在 GitHub Copilot 路径上，AI gateway 会在可用时优先使用 Copilot 原生的 Anthropic 风格 Messages API，在重工具调用场景下保留更原生的 Claude 行为。\n\n## 功能特性\n\n- **OpenAI 与 Anthropic 双兼容**：通过 `/v1/responses`、`/v1/chat/completions`、`/v1/models`、`/v1/embeddings` 和 `/v1/messages` 对外暴露同一个本地 AI gateway。\n- **Copilot 可选**：有 GitHub 凭据时可以使用 GitHub Copilot，没有 GitHub 凭据时也可以只依赖已配置的 provider 运行。\n- **同一网关接入 Copilot、`codex` 与第三方 provider**：可统一路由 GitHub Copilot、内置 `codex` provider 和配置好的外部 provider。\n- **第三方 provider 可独立启动**：配置 DashScope、DeepSeek、OpenRouter 或自定义 provider 后，不需要 GitHub Copilot 登录即可启动 AI gateway。\n- **OpenAI 兼容 provider 同时支持 chat 和 Messages API**：`openai-compatible` provider 可通过顶层 `/v1/chat/completions` 搭配 `model: \"provider/model\"` 提供 Chat Completions，也可通过 `/v1/messages` 完成 Anthropic Messages 的请求/响应翻译。\n- **面向 Claude 的更原生 Copilot 路由**：优先使用原生 `/v1/messages`，保留 Claude 风格工具流，支持 Anthropic beta 能力、通过 Responses-capable 模型支持 Claude WebSearch，并保留 subagent / session 标记。\n- **Claude Code 与 OpenCode 集成**：兼容 Claude Code 与 OpenCode，也支持通过 `@ai-sdk/anthropic` 直接作为 Anthropic provider 使用。\n- **灵活的认证与部署选项**：支持交互式登录、直接 token、个人 / Business / Enterprise、GitHub Enterprise、opencode OAuth 和自定义数据目录。\n- **多 provider 路由**：可暴露 `/:provider/...` 路由，也可在顶层 API 上使用 `model: \"provider/model\"`。\n\n## 前置要求\n\n- Bun（>= 1.2.x）\n- 如果要通过 `npx` 运行已发布 CLI，需要 Node.js\n- 只有在使用 GitHub Copilot provider 时，才需要已订阅 Copilot 的 GitHub 账号\n- 如果不使用 GitHub Copilot，需要至少一个已配置 provider 的 API key 或 OAuth 登录\n\n## 安装\n\n安装依赖：\n\n```sh\nbun install\n```\n\n直接从源码启动服务：\n\n```sh\nbun run start start\n```\n\n## 从源码运行\n\n本项目可以通过多种方式从源码运行：\n\n### 开发模式\n\n```sh\nbun run dev start\n```\n\n### 生产模式\n\n```sh\nbun run start start\n```\n\n## 通过 npx 使用\n\n你可以直接用 npx 运行本项目：\n\n> [!IMPORTANT]\n> 通过 `npx` 运行时，token usage 存储会使用 Node 内置的 `node:sqlite` 模块。该能力会在 Node.js >= 22.13.0 时启用；Node.js < 22.13.0 时 CLI 仍可启动，但会禁用 token usage 存储。\n>\n> 如果不升级 Node.js 但仍需要 token usage 存储，可以改用 Bun 运行已发布 CLI：`bunx --bun @jeffreycao/copilot-api@latest start`。\n\n```sh\nnpx @jeffreycao/copilot-api@latest start\n```\n\n带参数示例：\n\n```sh\nnpx @jeffreycao/copilot-api@latest start --port 8080\n```\n\n如果只想做认证或 provider 配置：\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth\n```\n\n如果要不依赖 GitHub Copilot 运行，先配置至少一个 provider，然后正常启动服务：\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth login --provider dashscope\nnpx @jeffreycao/copilot-api@latest start\n```\n\n## 配合 Docker 使用\n\n构建镜像：\n\n```sh\ndocker build -t copilot-api .\n```\n\n通过 bind mount 运行容器，让认证数据在重启后保留：\n\n```sh\nmkdir -p ./copilot-data\ndocker run -p 4141:4141 -v $(pwd)/copilot-data:/root/.local/share/copilot-api copilot-api\n```\n\n这会把宿主机上的 `./copilot-data` 映射到容器内的 `/root/.local/share/copilot-api`，用于持久化 GitHub 认证数据、provider 配置和其他 gateway 状态。\n\n也可以直接通过环境变量传入 GitHub token：\n\n```sh\ndocker run -p 4141:4141 -e GH_TOKEN=your_github_token_here copilot-api\n```\n\n## Electron 桌面应用\n\n如果你更喜欢图形界面，仓库里还提供了位于 `desktop/` 的 Electron 桌面应用。它支持 GitHub Copilot 登录、OpenAI Codex OAuth，以及 DeepSeek、DashScope、OpenRouter 或自定义 provider 的 API Key 配置。授权或配置 provider 后，可以一键启动或停止本地代理，并在界面里直接查看本地端点、鉴权 Header、可用模型、额度和日志。\n\n设置页还可以配置 `OAuth App`、`API Home`、`Enterprise URL`、详细日志以及最小化到托盘。桌面安装包发布在 GitHub Releases：\n\nhttps://github.com/caozhiyuan/copilot-api/releases\n\n下载对应平台的安装包后，在应用内授权或配置 provider，选择端口并启动服务，再把你的客户端指向应用里显示的本地端点即可。发布版桌面应用使用随包内置的 Electron 运行时，正常使用不需要额外安装 Node.js；token usage 历史记录会在该内置运行时支持 SQLite 时启用。\n\n桌面应用里的高级配置页会通过 `GET/POST /admin/config/model-mappings` 读写这份共享的模型映射。同一份映射会统一作用于 `POST /v1/messages`、`POST /v1/messages/count_tokens`、`POST /v1/responses` 和 `POST /v1/chat/completions`，不再按接口区分。它使用的是 `auth.adminApiKey`，不是普通的 `auth.apiKeys`；应用会在服务启动并自动生成该 key 后，直接从 `config.json` 读取它来发起请求。\n\n### 桌面应用截图\n\n下面展示了桌面应用中的首页、Token 用量统计页面：\n\n<p align=\"center\">\n  <img src=\"./docs/screenshots/desktop-dashboard.png\" alt=\"Copilot API 桌面应用首页\" width=\"49%\" />\n  <img src=\"./docs/screenshots/desktop-token-usage.png\" alt=\"Copilot API 桌面应用 Token 用量页\" width=\"49%\" />\n</p>\n\n## 与 Claude Code 一起使用\n\n这个 AI gateway 可以为 [Claude Code](https://docs.anthropic.com/en/claude-code) 提供后端能力。Claude Code 是 Anthropic 提供的实验性面向开发者的对话式 AI 助手。\n\n有两种方式可以把 Claude Code 配置为使用这个 AI gateway：\n\n### 通过 `--claude-code` 标志进行交互式配置\n\n执行带 `--claude-code` 的 `start` 命令开始：\n\n```sh\nnpx @jeffreycao/copilot-api@latest start --claude-code\n```\n\n你会被提示选择一个主模型，以及一个用于后台任务的 \"small, fast\" 模型。选择完成后，会有一条命令被复制到剪贴板中。该命令会设置 Claude Code 使用这个 AI gateway 所需的环境变量。\n\n在新的终端中粘贴并执行这条命令，即可启动 Claude Code。\n\n<a id=\"manual-configuration-with-settingsjson\"></a>\n\n### 通过 `settings.json` 手动配置\n\n另一种方式是在项目根目录中创建 `.claude/settings.json` 文件，并写入 Claude Code 所需的环境变量。这样你就不需要每次都运行交互式配置了。\n\n下面是一个 `.claude/settings.json` 示例：\n\n```json\n{\n  \"env\": {\n    \"ANTHROPIC_BASE_URL\": \"http://localhost:4141\",\n    \"ANTHROPIC_AUTH_TOKEN\": \"dummy\",\n    \"ANTHROPIC_MODEL\": \"deepseek/deepseek-v4-pro\",\n    \"ANTHROPIC_DEFAULT_SONNET_MODEL\": \"deepseek/deepseek-v4-pro\",\n    \"ANTHROPIC_DEFAULT_HAIKU_MODEL\": \"deepseek/deepseek-v4-flash\",\n    \"DISABLE_NON_ESSENTIAL_MODEL_CALLS\": \"1\",\n    \"CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC\": \"1\",\n    \"CLAUDE_CODE_ATTRIBUTION_HEADER\": \"0\",\n    \"CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION\": \"false\",\n    \"CLAUDE_CODE_DISABLE_TERMINAL_TITLE\": \"true\",\n    \"CLAUDE_CODE_ENABLE_AWAY_SUMMARY\": \"0\"\n  },\n  \"permissions\": {\n    \"deny\": [\n      \"mcp__ide__executeCode\"\n    ]\n  }\n}\n```\n\n- 请根据需要替换 `ANTHROPIC_MODEL`、`ANTHROPIC_DEFAULT_OPUS_MODEL`、`ANTHROPIC_DEFAULT_SONNET_MODEL` 和 `ANTHROPIC_DEFAULT_HAIKU_MODEL`。配置完成后，请安装 claude code 插件，见 [插件集成](#plugin-integrations)。\n- 将 `CLAUDE_CODE_ATTRIBUTION_HEADER` 设为 `0` 可以阻止 Claude Code 在 system prompt 中附加计费和版本信息，从而避免 prompt cache 失效。\n- 关闭 `CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION` 和 `CLAUDE_CODE_ENABLE_AWAY_SUMMARY` 可以避免不必要地消耗额度。\n- Claude Code WebSearch 已支持纯搜索请求。Copilot 路径请保持全局 `messageApiWebSearchModel` 指向 Responses-capable GPT 模型或 `provider/model` 别名；provider 路由请使用原生 Anthropic provider 或 `openai-responses` provider。只有在你明确想禁止这类流量时，才需要把 `WebSearch` 加到 `permissions.deny`。\n- 如果使用的不是 Claude 模型，请不要启用 `ENABLE_TOOL_SEARCH`。如果使用的是 Claude 模型，则可以启用 `ENABLE_TOOL_SEARCH`。当前 Claude Code 使用的是客户端 tool search 模式，在该模式下每次加载 defer tools 都需要额外请求一次。\n- `CLAUDE_CODE_AUTO_COMPACT_WINDOW`：设置用于自动压缩计算的上下文容量（以 token 为单位）。默认使用模型自身的上下文窗口：标准模型为 200K，扩展上下文模型为 1M。使用 1M 上下文模型（如 `claude-opus-4-6[1m]`）时，可设置一个较低的值（如 `500000`）将窗口视为 500K 用于压缩计算。该值受限于模型的实际上下文窗口上限。`CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` 会基于此值的百分比生效。设置此变量可将压缩阈值与状态栏的 `used_percentage` 解耦（后者始终使用模型的完整上下文窗口）。\n\n更多选项见：[Claude Code settings](https://docs.anthropic.com/en/docs/claude-code/settings#environment-variables)\n\n也可以参考 IDE 集成说明：[Add Claude Code to your IDE](https://docs.anthropic.com/en/docs/claude-code/ide-integrations)\n\n## 与 OpenCode 一起使用\n\nOpenCode 已经有直接的 GitHub Copilot provider。本节适用于你希望让 OpenCode 通过 `@ai-sdk/anthropic` 指向这个 AI gateway，并复用本 README 前面提到的 agent 行为时。\n\n### 最小配置\n\n使用 OpenCode OAuth app 启动 AI gateway：\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth --oauth-app=opencode\nnpx @jeffreycao/copilot-api@latest start\n```\n\n然后让 OpenCode 通过 `@ai-sdk/anthropic` 指向这个 AI gateway。\n\n示例 `~/.config/opencode/opencode.json`：\n\n```json\n{\n  \"$schema\": \"https://opencode.ai/config.json\",\n  \"provider\": {\n    \"local\": {\n      \"npm\": \"@ai-sdk/anthropic\",\n      \"name\": \"My Local\",\n      \"options\": {\n        \"baseURL\": \"http://localhost:4141/v1\",\n        \"apiKey\": \"dummy\"\n      },\n      \"models\": {\n        \"gpt-5.4\": {\n          \"name\": \"gpt-5.4\",\n          \"modalities\": {\n            \"input\": [\"text\", \"image\"],\n            \"output\": [\"text\"]\n          },\n          \"limit\": {\n            \"context\": 400000,\n            \"input\": 272000,\n            \"output\": 128000\n          }\n        },\n        \"claude-sonnet-4.6\": {\n          \"id\": \"claude-sonnet-4.6\",\n          \"name\": \"claude-sonnet-4.6\",\n          \"modalities\": {\n            \"input\": [\"text\", \"image\"],\n            \"output\": [\"text\"]\n          },\n          \"limit\": {\n            \"context\": 200000,\n            \"output\": 32000\n          },\n          \"options\": {\n            \"thinking\": {\n              \"type\": \"adaptive\"\n            },\n            \"effort\": \"max\"\n          }\n        }\n      }\n    }\n  }\n}\n```\n\n这些字段的重要性：\n\n- `npm: \"@ai-sdk/anthropic\"` 是关键。OpenCode 会以 Anthropic Messages 语义与这个 AI gateway 通信，而不是把一切扁平化为 OpenAI Chat Completions。\n- `options.baseURL` 应设为 `http://localhost:4141/v1`；Anthropic SDK 会自动补上 `/messages`、`/models` 和 `/messages/count_tokens`。\n- 如果你在此代理中启用了 `auth.apiKeys`，请把 `dummy` 替换为真实 key；否则任意占位值都可以。\n\n## 与 Codex 一起使用\n\n这个 AI gateway 也可以为 Codex 提供后端能力。\n\n### Codex `config.toml` 参考配置\n\n把以下 `[model_providers.copilot_api]` 段加入你的 Codex `~/.codex/config.toml`：\n\n```toml\nmodel_provider = \"copilot_api\"\nmodel_reasoning_summary = \"auto\"\nmodel_verbosity = \"medium\"\nmodel_context_window = 272000\nmodel_auto_compact_token_limit = 244800\n\n[model_providers.copilot_api]\nname = \"OpenAI\"\nbase_url = \"http://localhost:4141\"\nenv_key = \"GITHUB_COPILOT_API_KEY\"\nrequires_openai_auth = true\nsupports_websockets = false\nwire_api = \"responses\"\nrequest_max_retries = 3\nstream_max_retries = 1\nstream_idle_timeout_ms = 300000\n\n[features]\nremote_compaction_v2 = true\n\n[analytics]\nenabled = false\n```\n\n> [!NOTE]\n> 此配置仅限于 Codex 与 GitHub Copilot provider。`name` 一定要配置为 `\"OpenAI\"`。它可以缓解 Codex local compact 不命中缓存的问题。如果你已开启 `useResponsesApiContextManagement`（Responses API context management 压缩），通常不会走到 `remote_compaction_v2` 或者 local compact，但如果工具返回 tokens 过大，仍有可能触发。\n\n## GPT Tool Search\n\n对于 `gpt-5.4+` 这类 GPT Responses 模型，这个 AI gateway 可以通过一个很小的 MCP bridge 暴露 Responses `tool_search`。Claude Code 和 opencode 都可以使用同一个 bridge，前提是客户端会加载 MCP server，并且 Anthropic Messages 流量会经过这个 AI gateway。\n\nGPT 模型不要设置 Claude Code 原生的 `ENABLE_TOOL_SEARCH`。这个开关启用的是 Claude Code 自己的客户端 tool search 模式，可能导致 deferred 工具定义不再转发给 AI gateway。这个 AI gateway 需要完整的工具定义，这样才能只保留那一小组常驻加载工具，其余工具统一转换为 Responses deferred namespace。\n\n如果你安装了 `tool-search@copilot-api-marketplace`，Claude Code 会自动带上这个 MCP bridge，可以跳过下面这段 Claude Code MCP 手动配置。\n\n请把 tool search bridge 加到 Claude Code 使用的 MCP 配置中：\n\n```json\n{\n  \"mcpServers\": {\n    \"tool_search\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@jeffreycao/copilot-api@latest\", \"mcp\"]\n    }\n  }\n}\n```\n\n请把 tool search bridge 加到 opencode 使用的 MCP 配置中：\n\n```json\n{\n  \"mcp\": {\n    \"tool_search\": {\n      \"type\": \"local\",\n      \"command\": [\"npx\", \"-y\", \"@jeffreycao/copilot-api@latest\", \"mcp\"]\n    }\n  }\n}\n```\n\n本地开发时可以将命令换成 `bun`，参数换成 `[\"run\", \"./src/main.ts\", \"mcp\"]`。\n\nAI gateway 内部现在会把 OpenAI Responses `tool_search` 配置成 client-executed 模式。deferred tools 仍然会作为可搜索 namespace 暴露给模型，但会明确要求模型直接返回下一步要加载的精确工具名列表。\n\n该 bridge 使用直接工具选择，不做 query 搜索。工具入参是 `names`，值为逗号分隔的精确 deferred 工具名，例如 `TaskList,TaskGet,mcp__fetch__fetch`。\n\n<a id=\"plugin-integrations\"></a>\n\n## 插件集成\n\n本项目为 Claude Code 和 opencode 提供了插件集成。\n\n#### Claude Code 插件集成（基于 marketplace）\n\nClaude Code 集成现在拆分为两个插件：\n\n- `agent-inject` 会在 `SubagentStart` 时注入 `__SUBAGENT_MARKER__...`，以便 AI gateway 推导 `x-initiator: agent`。\n- `tool-search` 会注册用于 GPT Responses deferred tool loading 的 `tool_search` MCP bridge。\n\n- 本仓库中的 marketplace catalog：`.claude-plugin/marketplace.json`\n- 本仓库中的插件源码：`plugin/claude/agent-inject`、`plugin/claude/tool-search`\n\n远程添加 marketplace：\n\n```sh\n/plugin marketplace add https://github.com/caozhiyuan/copilot-api.git\n```\n\n从 marketplace 安装插件：\n\n```sh\n/plugin install agent-inject@copilot-api-marketplace\n/plugin install tool-search@copilot-api-marketplace\n```\n\n安装后，`agent-inject` 会在 `SubagentStart` 时注入 `__SUBAGENT_MARKER__...`，AI gateway 会利用它推导 `x-initiator: agent`。\n\n`agent-inject` 还会注册一个 `UserPromptSubmit` hook，并返回 `{\"continue\": true}`；同时它也可以通过环境变量注入 `SessionStart` reminder 规则：\n\n- `CLAUDE_PLUGIN_ENABLE_QUESTION_RULES=1` 会自动为 Claude Code 启用两条关于使用 `question` 工具的提醒。你也可以把同样的提醒手动写进 `CLAUDE.md`；见 [CLAUDE.md 或 AGENTS.md 推荐内容](#claudemd-or-agentsmd-recommended-content)。\n- `CLAUDE_PLUGIN_ENABLE_NO_BACKGROUND_AGENTS_RULE=1` 会启用关于避免在 agent hooks 中使用 `run_in_background: true` 的提醒。\n\n`tool-search` 插件内置了 [GPT Tool Search](#gpt-tool-search) 一节描述的同一个 MCP bridge，因此安装该插件后，Claude Code 用户无需再手动配置 `tool_search` server。\n\n#### Opencode 插件\n\nsubagent 标记生成器被打包为一个 opencode 插件，位于 `plugin/opencode/subagent-marker.js`。\n\n**安装方式：**\n\n将插件文件复制到你的 opencode 插件目录：\n\n```sh\n# 克隆或下载本仓库后复制该插件\ncp plugin/opencode/subagent-marker.js ~/.config/opencode/plugins/\n```\n\n或者手动在 `~/.config/opencode/plugins/subagent-marker.js` 创建该文件，并填入插件内容。\n\n**功能：**\n\n- 跟踪 subagent 创建的子会话\n- 自动在 subagent 聊天消息前添加 marker system reminder（`__SUBAGENT_MARKER__...`）\n- 设置 `x-session-id` 请求头以跟踪会话\n- 让这个 AI gateway 能够把来自 subagent 的请求识别为 `x-initiator: agent`\n\n该插件会挂接到 `session.created`、`session.deleted`、`chat.message` 和 `chat.headers` 事件上，以无缝提供 subagent marker 能力。\n\n## 使用量查看器\n\n服务启动后，控制台会输出一个 Copilot 使用量看板 URL。这个看板是一个用于监控 API 用量的 Web 界面。\n\n1. 启动服务。例如使用 npx：\n   ```sh\n   npx @jeffreycao/copilot-api@latest start\n   ```\n2. 服务会输出一个 usage viewer 的 URL。将它复制到浏览器中打开，形式大致如下：\n   `http://localhost:4141/usage-viewer?endpoint=http://localhost:4141/usage`\n   - 如果你在 Windows 上使用 `start.bat` 脚本，这个页面会自动打开。\n\n看板提供了更易读的 Copilot 用量视图：\n\n> token usage 历史记录需要 Bun 或 Node.js >= 22.13.0。Node.js < 22.13.0 时服务会正常运行，但 token usage 存储会被禁用。\n\n- **API Endpoint URL**：通过 URL 查询参数指定 API endpoints，默认指向本地服务。支持手动切换为其他兼容 endpoints。\n- **x-api-key 认证**：如果启用了 API Key 认证，可填入 `x-api-key` 请求头。密钥会持久化保存在浏览器本地存储中。\n- **Period 选择器**：支持 Day / Week / Month 三种时间范围，切换时 URL 参数会自动同步，方便收藏和分享。\n- **Fetch Data**：点击 \"Refresh\" 按钮加载或刷新使用数据。页面加载时也会自动拉取数据。\n- **Copilot Quotas 额度**：通过进度条展示 Chat、Completions 等不同服务的额度使用情况，悬停可查看已用/剩余详情。\n- **Token Usage 指标卡片**：汇总当前周期的 Total、Input、Output、Cache Read、Cache Write、Requests 和预估费用。\n- **趋势图（Week / Month）**：提供按模型和指标筛选的折线趋势图，点击数据点可查看单日用量明细。\n- **Model Breakdown 表格**：按模型维度列出周期内的请求数、输入/输出/缓存 token 和预计费用。\n- **Request Events 分页列表**：按时间排序的请求事件记录，支持分页浏览，含时间戳、模型、请求 ID 和 token 用量。\n- **Detailed Information**：展示 API 返回的完整 JSON 响应，便于深入分析所有可用统计数据。\n- **URL-based Configuration**：也可通过 `endpoint` 和 `period` 查询参数直接指定 API 端点与时间范围。例如：\n  `http://localhost:4141/usage-viewer?endpoint=http://your-api-server/usage&period=week`\n\n### Usage Viewer 截图\n\n<p align=\"center\">\n  <img src=\"./docs/screenshots/usage-viewer.png\" alt=\"Copilot API Usage Viewer 页面\" width=\"900\" />\n</p>\n\n## 命令结构\n\nCopilot API 现在使用子命令结构，主要命令包括：\n\n- `start`：启动 AI gateway 服务。如果已有 GitHub token，则启用 Copilot 路径；如果没有 GitHub token，但存在至少一个启用中的 provider，则按 provider-only 模式启动；如果两者都没有，会引导你配置 provider。\n- `auth`：仅执行 provider 登录或配置流程，不启动服务。可用于 GitHub Copilot 登录、Codex OAuth，或第三方 provider API key 配置。\n- `debug`：显示诊断信息，包括版本、运行时详情、文件路径以及认证状态，便于排障与支持。\n\n## 命令行选项\n\n### 全局选项\n\n以下选项可用于任意子命令。若在子命令之前传入，请使用 `--key=value` 形式：\n\n| 选项 | 说明 | 默认值 | 别名 |\n| --- | --- | --- | --- |\n| --api-home | API home 目录路径（设置 `COPILOT_API_HOME`） | 无 | 无 |\n| --oauth-app | OAuth app 标识符（设置 `COPILOT_API_OAUTH_APP`） | 无 | 无 |\n| --enterprise-url | GitHub Enterprise URL（设置 `COPILOT_API_ENTERPRISE_URL`） | 无 | 无 |\n\n### Start 命令选项\n\n以下是 `start` 命令可用的命令行选项：\n\n| 选项 | 说明 | 默认值 | 别名 |\n| --- | --- | --- | --- |\n| --port | 监听端口 | 4141 | -p |\n| --verbose | 启用详细日志 | false | -v |\n| --github-token | 直接提供 GitHub token（必须通过 `auth` 子命令生成） | 无 | -g |\n| --claude-code | 生成一个使用 Copilot API 配置启动 Claude Code 的命令 | false | -c |\n| --show-token | 在获取和刷新时显示 GitHub 与 Copilot token | false | 无 |\n| --proxy-env | 从环境变量初始化代理 | false | 无 |\n\n### Auth 命令选项\n\n| 选项 | 说明 | 默认值 | 别名 |\n| --- | --- | --- | --- |\n| --provider | 要登录或配置的 provider（`copilot`、`codex`、`opencode-go`、`deepseek`、`dashscope`、`openrouter` 或 `custom`） | 交互选择 | 无 |\n| --verbose | 启用详细日志 | false | -v |\n| --show-token | 认证时显示 GitHub token | false | 无 |\n\n只有在需要启用 GitHub Copilot provider 时，才需要执行 `copilot-api auth login --provider copilot`。使用 `codex` 或第三方 provider-only 模式不要求配置 Copilot。\n\n使用 `copilot-api auth login --provider deepseek`、`--provider dashscope`、`--provider openrouter` 或 `--provider opencode-go` 可以通过 CLI 快速新增或更新这些常用第三方 provider。DeepSeek 会提示输入掩码显示的 `apiKey`、provider `type`（默认 `anthropic`），以及默认 `https://api.deepseek.com/anthropic` 的 `baseUrl`。DashScope 会提示输入掩码显示的 `apiKey`、provider `type`（默认 `openai-compatible`）和预填默认值的 `baseUrl`。OpenRouter 只提示输入掩码显示的 `apiKey` 和预填默认值的 `baseUrl`，并固定写入 `type: \"anthropic\"`。OpenCode Go 只提示输入掩码显示的 `apiKey` 和预填默认值的 `baseUrl`，并固定写入 `type: \"openai-compatible\"`（baseUrl `https://opencode.ai/zen/go`）。配置并启用 provider 后，`copilot-api start` 可在没有 GitHub token 的情况下启动。\n\n使用 `copilot-api auth login --provider custom` 可以通过 CLI 新增或更新其他第三方 provider。命令会依次提示输入 provider name、项目支持的 type（`anthropic`、`openai-compatible` 或 `openai-responses`）、`baseUrl`、掩码显示的 `apiKey` 和 `authType`；`authType` 可保持 type 默认值，也可选择 `x-api-key` / `authorization`。\n\n### Debug 命令选项\n\n| 选项 | 说明 | 默认值 | 别名 |\n| --- | --- | --- | --- |\n| --json | 以 JSON 输出调试信息 | false | 无 |\n\n<a id=\"configuration-configjson\"></a>\n\n## 配置（config.json）\n\n- **位置：** Linux/macOS 为 `~/.local/share/copilot-api/config.json`，Windows 为 `%USERPROFILE%\\.local\\share\\copilot-api\\config.json`。\n- **默认结构：**\n  ```json\n  {\n    \"auth\": {\n      \"apiKeys\": [],\n      \"adminApiKey\": \"<startup 自动生成>\"\n    },\n    \"providers\": {},\n    \"modelMappings\": {},\n    \"extraPrompts\": {\n      \"gpt-5-mini\": \"<built-in exploration prompt>\"\n    },\n    \"smallModel\": \"gpt-5-mini\",\n    \"useResponsesApiContextManagement\": true,\n    \"modelResponsesApiCompactThresholds\": {\n      \"gpt-5.4\": 217600,\n      \"gpt-5.5\": 217600\n    },\n    \"modelReasoningEfforts\": {\n      \"gpt-5-mini\": \"low\"\n    },\n    \"useMessagesApi\": true,\n    \"useResponsesApiWebSocket\": true,\n    \"useResponsesApiWebSearch\": true,\n    \"messageApiWebSearchModel\": \"gpt-5-mini\"\n  }\n  ```\n- **auth.apiKeys：** 用于普通非 admin 路由的 API key。支持多个 key 轮换使用。请求可通过 `x-api-key: <key>` 或 `Authorization: Bearer <key>` 进行认证。若为空或省略，则普通路由的认证会被禁用。\n- **auth.adminApiKey：** 仅用于 `/admin/*` 路由的单个 admin key。若未配置，服务会在启动时自动生成一个随机 key，并回写到 `config.json`。它同样使用 `x-api-key` 或 `Authorization: Bearer` 这两种头，但普通 `auth.apiKeys` 不能访问 `/admin/*`。\n- **modelMappings：** 用于顶层 `POST /v1/messages`、`POST /v1/messages/count_tokens`、`POST /v1/responses` 和 `POST /v1/chat/completions` 请求的精确 `sourceModel -> targetModel` 重写映射，这几类接口共用同一份规则。省略该字段或保留为 `{}` 时，不会做模型重写。`source` 和 `target` 都必须是非空字符串。`target` 可以是普通模型 ID，也可以是 `provider/model` 形式的别名，例如 `dashscope/qwen3.6-plus`；重写发生在 provider alias 解析之前。这些映射不再按接口区分。`GET/POST /admin/config/model-mappings` 管理接口读写的也只有这个字段。\n- **extraPrompts：** `model -> prompt` 的映射。把 Anthropic 风格请求翻译为 Responses API 时，会将其附加到第一条 system prompt 后面。你可以借此为不同模型注入护栏或指引。缺失的默认项会自动补齐，但不会覆盖你自定义的 prompt。对于 GPT-5.3+ 模型（如 `gpt-5.3-codex`、`gpt-5.4`、`gpt-5.5`），未显式配置时会自动使用内置的 commentary prompt。内置 prompt 会启用带阶段感知的 commentary，让模型在工具调用或更深层推理前先发出简短的用户可见进度说明。\n- **providers：** 全局上游 provider 映射。每个 provider key（例如 `dashscope`）都会变成一个路由前缀（`/dashscope/v1/messages`）。支持 `type: \"anthropic\"`、`type: \"openai-compatible\"` 和 `type: \"openai-responses\"`。顶层客户端也可以在 `/v1/messages`、`/v1/messages/count_tokens`、`/v1/responses` 和 `/v1/chat/completions` 中使用 `model: \"dashscope/model-id\"`；AI gateway 会在转发上游前移除 `dashscope/` 前缀。`openai-compatible` provider 同时支持 chat 和 Messages 流程：`/v1/chat/completions` 会直连上游 `/v1/chat/completions`，而 `/v1/messages` 和 `/:provider/v1/messages` 会先翻译为上游 Chat Completions，再把响应翻译回 Anthropic Messages。`GET /v1/models` 会聚合已启用 provider 的模型，并以 `provider/model-id` 形式返回；单个 provider 的原始模型列表仍可使用 `GET /dashscope/v1/models`。\n  - `enabled`：可选，若省略则默认为 `true`。\n  - `baseUrl`：provider API 的基础 URL，不要带结尾的 endpoint。Anthropic provider 不要带 `/v1/messages`；OpenAI 兼容 provider 不要带 `/v1/chat/completions`；OpenAI Responses provider 不要带 `/v1/responses`。\n  - `apiKey`：作为上游凭据值使用；普通 provider 必须配置。\n  - `authType`：可选，控制 `apiKey` 如何发送到上游。普通 provider 支持 `x-api-key` 和 `authorization`。Anthropic provider 默认 `x-api-key`；OpenAI 兼容和 OpenAI Responses provider 默认 `authorization`。当设置为 `authorization` 时，代理会发送 `Authorization: Bearer <apiKey>`。`oauth2` 仅保留给内置 `codex` provider，并由 `auth login --provider codex` 自动写入。\n  - `pricingCurrency`：可选，provider 维度的 token 费用币种，例如 `USD` 或 `CNY`。快捷 provider 默认 DashScope、DeepSeek 为 `CNY`，Codex/OpenRouter 为 `USD`。费用按币种分别汇总，不做汇率换算。\n  - `models`：可选，按模型 ID 配置的映射。每个键为请求中的模型名，值支持：\n    - `temperature`：可选，当请求未指定时使用的默认温度。\n    - `topP`：可选，当请求未指定时使用的默认 `top_p`。\n    - `topK`：可选，当请求未指定时使用的默认 `top_k`。\n    - `extraBody`：可选，按模型合入上游请求体的动态字段；请求体显式同名字段优先。OpenAI 兼容 provider 可用它配置 `enable_thinking`、`preserve_thinking`、`reasoning_effort` 等字段。`thinking_budget` 是 OpenAI 兼容 provider 的特殊覆盖项：配置在 `extraBody` 后，会在 Anthropic `thinking.budget_tokens` 翻译之后强制写入，并覆盖请求派生出的预算值。对于 provider name 为 `dashscope` 或 `baseUrl` 包含 `aliyuncs.com` 的 provider，请求派生的 `thinking_budget`（来自 Anthropic `thinking.budget_tokens`）会转发给上游；其他 OpenAI 兼容 provider 会移除请求派生的 `thinking_budget`，但 `extraBody` 中的 `thinking_budget` 仍然生效。对于 DashScope provider，当 `preserve_thinking` 未在 `extraBody` 或请求体中显式设置时，默认为 `true`。\n    - `pricing`：可选，按模型配置 token 单价，币种使用 provider 的 `pricingCurrency`，单位为每 100 万 tokens。支持 `input`、`output`、`cachedInput`（隐式缓存读）、`explicitCachedInput`（显式缓存读）和 `cacheCreationInput`。如需按输入 token 总量分档，可用带 `maxInputTokens` 的 `tiers`。\n    - `contextCache`：可选，provider name 为 `dashscope` 或 `baseUrl` 包含 `aliyuncs.com` 时默认 `true`，其他 OpenAI 兼容 provider 默认 `false`。用于启用阿里云百炼/DashScope 的显式缓存（explicit context cache），会按其 Context Cache 格式在最多 4 个 content block 上注入 `cache_control: { \"type\": \"ephemeral\" }`。缓存断点策略与 opencode 主链路保持一致：前 2 条 system 消息 + 最后 2 条非 system 消息。标记字符串 content 时会把 `system` / `user` / `assistant` / `tool` 消息转换为 text content part 数组；已有数组 content 则标记最后一个 part。如果模型本身已经支持隐式缓存，或上游不支持该显式缓存扩展字段，可在模型配置中设为 `false`。支持相同显式缓存扩展的非 DashScope provider 可设为 `true`。同时适用于 `/v1/messages` 和 `/v1/chat/completions` 路由。\n    - `supportPdf`：可选，控制该模型是否支持 PDF/document content。默认 `false`，不支持时会把 PDF 转成提示文本；设为 `true` 时会把 PDF/document 转成 OpenAI Chat Completions 的 file part。\n    - `toolContentSupportType`：可选，配置该模型的 tool result content 支持能力，值为 `array`、`image`、`pdf` 的数组。provider 侧未配置时默认只发送 string tool content。若 `supportPdf` 为 `true` 但这里不包含 `pdf`，tool result 里的 file part 会被转成 user role 消息。Copilot 主链路不使用这个 provider 默认，仍按 array + image 且不支持 PDF 的能力处理。\n    - `type`：可选，按模型覆盖 provider 的协议类型。支持 `anthropic`、`openai-compatible` 和 `openai-responses`。设置后，provider 的 `/v1/messages` 路由会使用该模型的 type 替代 provider 级别的 type 进行请求路由、认证头解析和上游端点选择。适用于 OpenCode Go 等上游对不同模型同时支持 OpenAI 兼容和 Anthropic Messages API 的 provider。覆盖 type 时，认证头按覆盖后 type 的默认值解析（Anthropic 默认 `x-api-key`；OpenAI 兼容/Responses 默认 `authorization`）。\n\n  DashScope 模型配置示例：\n  ```json\n  {\n    \"providers\": {\n      \"dashscope\": {\n        \"type\": \"openai-compatible\",\n        \"enabled\": true,\n        \"baseUrl\": \"https://dashscope.aliyuncs.com/compatible-mode\",\n        \"apiKey\": \"sk-your-dashscope-key\",\n        \"pricingCurrency\": \"CNY\",\n        \"models\": {\n          \"qwen3.7-plus\": {\n            \"temperature\": 1,\n            \"topP\": 0.95,\n            \"topK\": 20,\n            \"extraBody\": {\n              \"preserve_thinking\": true\n            }\n          },\n          \"glm-5.1\": {\n            \"temperature\": 0.7,\n            \"topP\": 0.95,\n            \"contextCache\": true,\n            \"pricing\": {\n              \"tiers\": [\n                {\n                  \"maxInputTokens\": 32000,\n                  \"input\": 6,\n                  \"cachedInput\": 1.2,\n                  \"explicitCachedInput\": 0.6,\n                  \"cacheCreationInput\": 7.5,\n                  \"output\": 24\n                },\n                {\n                  \"maxInputTokens\": 200000,\n                  \"input\": 8,\n                  \"cachedInput\": 1.6,\n                  \"explicitCachedInput\": 0.8,\n                  \"cacheCreationInput\": 10,\n                  \"output\": 28\n                }\n              ]\n            },\n            \"extraBody\": {\n              \"preserve_thinking\": true\n            }\n          }\n        }\n      }\n    }\n  }\n  ```\n  内置 token 价格覆盖 Codex GPT 模型（USD）、DashScope `qwen3.7-max`、`qwen3.7-plus`、`glm-5.1`、`glm-5.2`（CNY），DeepSeek `deepseek-v4-flash`、`deepseek-v4-pro`、`deepseek-chat`、`deepseek-reasoner`（CNY），以及 OpenCode Go 模型（`glm-5.2`、`deepseek-v4-flash`、`deepseek-v4-pro`、`kimi-k2.7-code`、`mimo-v2.5`、`mimo-v2.5-pro`、`qwen3.7-plus`、`qwen3.7-max`、`minimax-m2.5`、`minimax-m3`，USD）。用户配置的 `pricing` 优先于内置价格。DashScope 若上游 usage 中出现 `cache_creation_input_tokens` 字段，cached tokens 按显式缓存读价计费；否则 `cachedInput` 作为隐式缓存读价。DeepSeek 的 `prompt_cache_hit_tokens` 会归入 cached input，`prompt_cache_miss_tokens` 会归入普通 input。\n- **smallModel：** 无工具预热消息的回退模型（例如 Claude Code 的探测请求）；默认是 `gpt-5-mini`。\n- **useResponsesApiContextManagement：** 当为 `true` 时，代理会为 Responses API 附加 `context_management` 压缩指令。默认值为 `true`。如需全局关闭，可设为 `false`。启用后，请求体会带上 `context_management`，并在后续轮次中仅保留最新的压缩承载内容，因此特别适合长任务场景。\n- **modelResponsesApiCompactThresholds：** 按模型覆盖 Responses API 的 `compact_threshold`，仅在代理自动附加 `context_management` 时使用。它的优先级高于 `resolveResponsesCompactThreshold` 基于 `max_prompt_tokens * ratio` 的兜底阈值。默认将 `gpt-5.4` 和 `gpt-5.5` 设为 `217600`（`272000 * 0.8`）。未列出的模型继续使用原有兜底逻辑。\n- **modelReasoningEfforts：** 按模型配置的推理强度，仅作用于 `/v1/messages` 请求。当请求走 Copilot 原生 Messages API 时设置 `output_config.effort`；当请求被翻译为 Responses API 时设置 `reasoning.effort`。可选值包括 `none`、`minimal`、`low`、`medium`、`high`、`xhigh` 和 `max`。若某模型未配置，则默认使用 `high`；GPT-5.3+ 模型未显式配置时回退为 `xhigh`。\n- **useMessagesApi：** 当为 `true` 时，支持 Copilot 原生 `/v1/messages` 的 Claude 系模型会走 Messages API；否则回退到 `/chat/completions`。设为 `false` 可禁用 Messages API 路由，始终使用 `/chat/completions`。默认值为 `true`。\n- **useResponsesApiWebSocket：** 当为 `true` 时，Responses API 请求会优先对声明了 `ws:/responses` 的模型使用 Copilot websocket transport；仅声明 `/responses` 的模型仍走 HTTP。设为 `false` 可禁用 websocket 路由，并在模型支持 `/responses` 时使用 HTTP `/responses`。默认值为 `true`。\n- **useResponsesApiWebSearch：** 当为 `true` 时，服务端会保留 Responses API 中 `type: \"web_search\"` 的工具并透传到上游。设为 `false` 则会从 `/responses` payload 中移除这些工具。默认值为 `true`。\n- **messageApiWebSearchModel：** 顶层 Copilot `/v1/messages` 请求只包含服务端 `web_search` 工具时使用的全局模型，默认值为 `gpt-5-mini`。如果该值是 `provider/model` 别名，请求会进入对应 provider 的 Messages API 路径，并在转发前移除 provider 前缀。对于 Copilot GPT 模型，web search 会通过 `/responses` 执行。混合 `web_search` 与自定义工具的场景暂不支持，服务端会移除 server-side `web_search`。\n- **claudeTokenMultiplier：** 用于 Claude `/v1/messages/count_tokens` 请求在本地走 GPT tokenizer 估算时的乘数。默认值为 `1.15`。如果你的客户端仍然过晚触发上下文压缩，可以适当调大。这个配置只会在代理本地估算 Claude token 时生效；如果已经配置 `anthropicApiKey` 且 Anthropic token counting 调用成功，则会直接返回 Anthropic 的精确计数，不会使用这个乘数。\n- **anthropicApiKey：** 用于把 Claude `/v1/messages/count_tokens` 请求转发到 Anthropic 真实 token counting 端点的 API key，这样会返回精确计数，而不是 GPT tokenizer 估算值。也可通过环境变量 `ANTHROPIC_API_KEY` 设置。若未配置，或上游调用失败，则回退到由 `claudeTokenMultiplier` 控制的本地 GPT tokenizer 估算。\n\n编辑此文件后即可自定义 prompts，或替换为你自己的快速模型。修改完成后请重启服务（或重新执行命令），让缓存中的配置刷新生效。\n\n## API 认证\n\n- **受保护的普通路由：** 当配置了 `auth.apiKeys` 且非空时，除 `/`、`/usage-viewer` 和 `/usage-viewer/` 以外的普通路由都需要认证。\n- **Admin 路由：** 所有 `/admin/*` 路由都要求 `auth.adminApiKey`。如果缺失，服务会在启动时自动生成并在开始提供服务前写回 `config.json`。\n- **允许的认证头：**\n  - `x-api-key: <your_key>`\n  - `Authorization: Bearer <your_key>`\n- **CORS 预检：** `OPTIONS` 请求始终允许。\n- **未配置普通 key 时：** 普通路由仍可直接访问；但这条规则不适用于 `/admin/*`，后者只接受 `auth.adminApiKey`。\n\n普通受保护路由的示例请求：\n\n```sh\ncurl http://localhost:4141/v1/models \\\n  -H \"x-api-key: your_api_key\"\n```\n\nAdmin 路由的示例请求：\n\n```sh\ncurl http://localhost:4141/admin/config/model-mappings \\\n  -H \"x-api-key: your_admin_api_key\"\n```\n\n## API 端点\n\n服务端提供多个 OpenAI / Anthropic 兼容端点。请求会根据所选模型和 `provider/model` 别名路由到 GitHub Copilot、内置 `codex` provider 或已配置的 provider。\n\n### OpenAI 兼容端点\n\n这些端点模拟 OpenAI API 结构。\n\n| 端点 | 方法 | 说明 |\n| --- | --- | --- |\n| `POST /v1/responses` | `POST` | OpenAI 中用于生成模型响应的高级接口。支持 `openai-responses` provider 的 `provider/model` 别名。 |\n| `POST /v1/chat/completions` | `POST` | 为给定聊天对话创建模型响应。支持 `openai-compatible` provider 的 `provider/model` 别名；目标 provider 已配置时可在没有 Copilot 的情况下使用。 |\n| `GET /v1/models` | `GET` | 列出 Copilot 模型以及已启用 provider 的 `provider/model-id` 模型。 |\n| `POST /v1/embeddings` | `POST` | 创建表示输入文本的向量嵌入。 |\n\n### Anthropic 兼容端点\n\n这些端点设计为兼容 Anthropic Messages API。\n\n| 端点 | 方法 | 说明 |\n| --- | --- | --- |\n| `POST /v1/messages` | `POST` | 为给定对话创建模型响应。支持已配置 provider 的 `provider/model` 别名，包括通过 `openai-compatible` provider 做翻译。 |\n| `POST /v1/messages/count_tokens` | `POST` | 计算一组消息的 token 数。支持已配置 provider 的 `provider/model` 别名。 |\n| `POST /:provider/v1/messages` | `POST` | 将 Anthropic Messages 请求代理到已配置的 Anthropic provider，或翻译到 OpenAI 兼容 / OpenAI Responses provider。 |\n| `GET /:provider/v1/models` | `GET` | 将模型列表请求代理到已配置的 provider。 |\n| `POST /:provider/v1/messages/count_tokens` | `POST` | 为 provider 路由请求在本地计算 token 数。 |\n\n### 使用量监控端点\n\n用于监控 Copilot 用量与额度的新端点。\n\n| 端点 | 方法 | 说明 |\n| --- | --- | --- |\n| `GET /usage` | `GET` | 获取详细的 Copilot 使用统计与额度信息。 |\n| `GET /token` | `GET` | 获取当前 API 正在使用的 Copilot token。 |\n\n### Admin / 配置端点\n\n这些端点用于本地管理操作，只接受 `auth.adminApiKey`。\n\n| 端点 | 方法 | 说明 |\n| --- | --- | --- |\n| `GET /admin/config/model-mappings` | `GET` | 返回当前 `config.json` 路径以及生效中的 `modelMappings` 映射。 |\n| `POST /admin/config/model-mappings` | `POST` | 只更新 `config.json` 里的 `modelMappings` 字段，并回传更新后的结果。 |\n\n## 使用示例\n\n常用 `npx` 命令：\n\n```sh\n# 基础启动\nnpx @jeffreycao/copilot-api@latest start\n\n# 自定义端口并开启详细日志\nnpx @jeffreycao/copilot-api@latest start --port 8080 --verbose\n\n# 执行认证流程\nnpx @jeffreycao/copilot-api@latest auth login\n\n# 配置第三方 provider，然后不依赖 GitHub Copilot 启动\nnpx @jeffreycao/copilot-api@latest auth login --provider dashscope\nnpx @jeffreycao/copilot-api@latest start\n\n# 以 JSON 格式输出调试信息\nnpx @jeffreycao/copilot-api@latest debug --json\n\n# 用 Bun 而不是 Node.js 运行已发布 CLI\nbunx --bun @jeffreycao/copilot-api@latest start\n```\n\n配置 `dashscope` 后的 OpenAI 兼容 provider 调用示例：\n\n```sh\ncurl http://localhost:4141/v1/chat/completions \\\n  -H \"content-type: application/json\" \\\n  -d '{\"model\":\"dashscope/qwen3.6-plus\",\"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]}'\n\ncurl http://localhost:4141/dashscope/v1/messages \\\n  -H \"content-type: application/json\" \\\n  -d '{\"model\":\"qwen3.6-plus\",\"max_tokens\":1024,\"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]}'\n```\n\n## 使用建议\n\n<a id=\"claudemd-or-agentsmd-recommended-content\"></a>\n\n### CLAUDE.md 或 AGENTS.md 推荐内容\n\n如果你想手动加入这些提醒，请在 Claude Code 的 `CLAUDE.md`，或 opencode/codex 的 `AGENTS.md` 中加入以下内容：\n\n```\n- Prohibited from directly asking questions to users, MUST use question tool.\n- Once you can confirm that the task is complete, MUST use question tool to make user confirm. The user may respond with feedback if they are not satisfied with the result, which you can use to make improvements and try again, after try again, MUST use question tool to make user confirm again.\n```\n"}, "b90e221b27c3715d1f8e023f2ff889c49f0a8498": {"t": 1785765574.320597, "n": 30726, "h": "164ec2800dd31937", "c": "# Copilot API Proxy\n\n[English](./README.md) | 简体中文\n\n## 重要说明\n\n> [!IMPORTANT]\n> **使用前请先注意以下几点：**\n>\n> 1. **Claude Code 配置：** 与 Claude Code 搭配使用时，请将模型 ID 配置为 `claude-opus-4-8`。示例 claude `settings.json` 见 [通过 `settings.json` 手动配置](#manual-configuration-with-settingsjson)。\n>\n> 2. **内置 `copilot`、`codex` 与第三方 provider：** 执行 `npx @jeffreycao/copilot-api@latest auth`，可选择 `copilot`、`codex`、`deepseek`、`custom` 等 provider。\n>\n> 3. **注意事项：** README 顶部移除的 GitHub Copilot warning 见 [GitHub Copilot 安全提示](./NOTICE.md#github-copilot-security-notice)。\n\n---\n\n## 项目概览\n\n这是一个小型 AI gateway，可以使用 GitHub Copilot、内置 `codex` provider，也可以使用 DashScope 等已配置的第三方 provider。GitHub Copilot 现在是可选能力：如果本地没有 GitHub token，只要至少配置了一个启用中的 provider，服务仍可按 provider-only 模式启动。\n\nAI gateway 会从同一个本地端点暴露 OpenAI / Anthropic 兼容 API，让 [Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview)、OpenCode、Codex 和 OpenAI 兼容客户端可以共用同一个本地服务。\n\n在 GitHub Copilot 路径上，AI gateway 会在可用时优先使用 Copilot 原生的 Anthropic 风格 Messages API，在重工具调用场景下保留更原生的 Claude 行为。\n\n## 功能特性\n\n- **OpenAI 与 Anthropic 双兼容**：通过 `/v1/responses`、`/v1/chat/completions`、`/v1/models`、`/v1/embeddings` 和 `/v1/messages` 对外暴露同一个本地 AI gateway。\n- **Copilot 可选**：有 GitHub 凭据时可以使用 GitHub Copilot，没有 GitHub 凭据时也可以只依赖已配置的 provider 运行。\n- **同一网关接入 Copilot、`codex` 与第三方 provider**：可统一路由 GitHub Copilot、内置 `codex` provider 和配置好的外部 provider。\n- **第三方 provider 可独立启动**：配置 DashScope、DeepSeek、OpenRouter 或自定义 provider 后，不需要 GitHub Copilot 登录即可启动 AI gateway。\n- **OpenAI 兼容 provider 同时支持 chat 和 Messages API**：`openai-compatible` provider 可通过顶层 `/v1/chat/completions` 搭配 `model: \"provider/model\"` 提供 Chat Completions，也可通过 `/v1/messages` 完成 Anthropic Messages 的请求/响应翻译。\n- **面向 Claude 的更原生 Copilot 路由**：优先使用原生 `/v1/messages`，保留 Claude 风格工具流，支持 Anthropic beta 能力、通过 Responses-capable 模型支持 Claude WebSearch，并保留 subagent / session 标记。\n- **Claude Code 与 OpenCode 集成**：兼容 Claude Code 与 OpenCode，也支持通过 `@ai-sdk/anthropic` 直接作为 Anthropic provider 使用。\n- **灵活的认证与部署选项**：支持交互式登录、直接 token、个人 / Business / Enterprise、GitHub Enterprise、opencode OAuth 和自定义数据目录。\n- **多 provider 路由**：可暴露 `/:provider/...` 路由，也可在顶层 API 上使用 `model: \"provider/model\"`。\n\n## 前置要求\n\n- Bun（>= 1.2.x）\n- 如果要通过 `npx` 运行已发布 CLI，需要 Node.js\n- 只有在使用 GitHub Copilot provider 时，才需要已订阅 Copilot 的 GitHub 账号\n- 如果不使用 GitHub Copilot，需要至少一个已配置 provider 的 API key 或 OAuth 登录\n\n## 安装\n\n安装依赖：\n\n```sh\nbun install\n```\n\n直接从源码启动服务：\n\n```sh\nbun run start start\n```\n\n## 从源码运行\n\n本项目可以通过多种方式从源码运行：\n\n### 开发模式\n\n```sh\nbun run dev start\n```\n\n### 生产模式\n\n```sh\nbun run start start\n```\n\n## 通过 npx 使用\n\n你可以直接用 npx 运行本项目：\n\n> [!IMPORTANT]\n> 通过 `npx` 运行时，token usage 存储会使用 Node 内置的 `node:sqlite` 模块。该能力会在 Node.js >= 22.13.0 时启用；Node.js < 22.13.0 时 CLI 仍可启动，但会禁用 token usage 存储。\n>\n> 如果不升级 Node.js 但仍需要 token usage 存储，可以改用 Bun 运行已发布 CLI：`bunx --bun @jeffreycao/copilot-api@latest start`。\n\n```sh\nnpx @jeffreycao/copilot-api@latest start\n```\n\n带参数示例：\n\n```sh\nnpx @jeffreycao/copilot-api@latest start --port 8080\n```\n\n如果只想做认证或 provider 配置：\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth\n```\n\n如果要不依赖 GitHub Copilot 运行，先配置至少一个 provider，然后正常启动服务：\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth login --provider dashscope\nnpx @jeffreycao/copilot-api@latest start\n```\n\n## 配合 Docker 使用\n\n构建镜像：\n\n```sh\ndocker build -t copilot-api .\n```\n\n通过 bind mount 运行容器，让认证数据在重启后保留：\n\n```sh\nmkdir -p ./copilot-data\ndocker run -p 4141:4141 -v $(pwd)/copilot-data:/root/.local/share/copilot-api copilot-api\n```\n\n这会把宿主机上的 `./copilot-data` 映射到容器内的 `/root/.local/share/copilot-api`，用于持久化 GitHub 认证数据、provider 配置和其他 gateway 状态。\n\n也可以直接通过环境变量传入 GitHub token：\n\n```sh\ndocker run -p 4141:4141 -e GH_TOKEN=your_github_token_here copilot-api\n```\n\n## Electron 桌面应用\n\n如果你更喜欢图形界面，仓库里还提供了位于 `desktop/` 的 Electron 桌面应用。它支持 GitHub Copilot 登录、OpenAI Codex OAuth，以及 DeepSeek、DashScope、OpenRouter 或自定义 provider 的 API Key 配置。授权或配置 provider 后，可以一键启动或停止本地代理，并在界面里直接查看本地端点、鉴权 Header、可用模型、额度和日志。\n\n设置页还可以配置 `OAuth App`、`API Home`、`Enterprise URL`、详细日志以及最小化到托盘。桌面安装包发布在 GitHub Releases：\n\nhttps://github.com/caozhiyuan/copilot-api/releases\n\n下载对应平台的安装包后，在应用内授权或配置 provider，选择端口并启动服务，再把你的客户端指向应用里显示的本地端点即可。发布版桌面应用使用随包内置的 Electron 运行时，正常使用不需要额外安装 Node.js；token usage 历史记录会在该内置运行时支持 SQLite 时启用。\n\n桌面应用里的高级配置页会通过 `GET/POST /admin/config/model-mappings` 读写这份共享的模型映射。同一份映射会统一作用于 `POST /v1/messages`、`POST /v1/messages/count_tokens`、`POST /v1/responses` 和 `POST /v1/chat/completions`，不再按接口区分。它使用的是 `auth.adminApiKey`，不是普通的 `auth.apiKeys`；应用会在服务启动并自动生成该 key 后，直接从 `config.json` 读取它来发起请求。\n\n### 桌面应用截图\n\n下面展示了桌面应用中的首页、Token 用量统计页面：\n\n<p align=\"center\">\n  <img src=\"./docs/screenshots/desktop-dashboard.png\" alt=\"Copilot API 桌面应用首页\" width=\"49%\" />\n  <img src=\"./docs/screenshots/desktop-token-usage.png\" alt=\"Copilot API 桌面应用 Token 用量页\" width=\"49%\" />\n</p>\n\n## 与 Claude Code 一起使用\n\n这个 AI gateway 可以为 [Claude Code](https://docs.anthropic.com/en/claude-code) 提供后端能力。Claude Code 是 Anthropic 提供的实验性面向开发者的对话式 AI 助手。\n\n有两种方式可以把 Claude Code 配置为使用这个 AI gateway：\n\n### 通过 `--claude-code` 标志进行交互式配置\n\n执行带 `--claude-code` 的 `start` 命令开始：\n\n```sh\nnpx @jeffreycao/copilot-api@latest start --claude-code\n```\n\n你会被提示选择一个主模型，以及一个用于后台任务的 \"small, fast\" 模型。选择完成后，会有一条命令被复制到剪贴板中。该命令会设置 Claude Code 使用这个 AI gateway 所需的环境变量。\n\n在新的终端中粘贴并执行这条命令，即可启动 Claude Code。\n\n<a id=\"manual-configuration-with-settingsjson\"></a>\n\n### 通过 `settings.json` 手动配置\n\n另一种方式是在项目根目录中创建 `.claude/settings.json` 文件，并写入 Claude Code 所需的环境变量。这样你就不需要每次都运行交互式配置了。\n\n下面是一个 `.claude/settings.json` 示例：\n\n```json\n{\n  \"env\": {\n    \"ANTHROPIC_BASE_URL\": \"http://localhost:4141\",\n    \"ANTHROPIC_AUTH_TOKEN\": \"dummy\",\n    \"ANTHROPIC_MODEL\": \"deepseek/deepseek-v4-pro\",\n    \"ANTHROPIC_DEFAULT_SONNET_MODEL\": \"deepseek/deepseek-v4-pro\",\n    \"ANTHROPIC_DEFAULT_HAIKU_MODEL\": \"deepseek/deepseek-v4-flash\",\n    \"DISABLE_NON_ESSENTIAL_MODEL_CALLS\": \"1\",\n    \"CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC\": \"1\",\n    \"CLAUDE_CODE_ATTRIBUTION_HEADER\": \"0\",\n    \"CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION\": \"false\",\n    \"CLAUDE_CODE_DISABLE_TERMINAL_TITLE\": \"true\",\n    \"CLAUDE_CODE_ENABLE_AWAY_SUMMARY\": \"0\"\n  },\n  \"permissions\": {\n    \"deny\": [\n      \"mcp__ide__executeCode\"\n    ]\n  }\n}\n```\n\n- 请根据需要替换 `ANTHROPIC_MODEL`、`ANTHROPIC_DEFAULT_OPUS_MODEL`、`ANTHROPIC_DEFAULT_SONNET_MODEL` 和 `ANTHROPIC_DEFAULT_HAIKU_MODEL`。配置完成后，请安装 claude code 插件，见 [插件集成](#plugin-integrations)。\n- 将 `CLAUDE_CODE_ATTRIBUTION_HEADER` 设为 `0` 可以阻止 Claude Code 在 system prompt 中附加计费和版本信息，从而避免 prompt cache 失效。\n- 关闭 `CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION` 和 `CLAUDE_CODE_ENABLE_AWAY_SUMMARY` 可以避免不必要地消耗额度。\n- Claude Code WebSearch 已支持纯搜索请求。Copilot 路径请保持全局 `messageApiWebSearchModel` 指向 Responses-capable GPT 模型或 `provider/model` 别名；provider 路由请使用原生 Anthropic provider 或 `openai-responses` provider。只有在你明确想禁止这类流量时，才需要把 `WebSearch` 加到 `permissions.deny`。\n- 如果使用的不是 Claude 模型，请不要启用 `ENABLE_TOOL_SEARCH`。如果使用的是 Claude 模型，则可以启用 `ENABLE_TOOL_SEARCH`。当前 Claude Code 使用的是客户端 tool search 模式，在该模式下每次加载 defer tools 都需要额外请求一次。\n- `CLAUDE_CODE_AUTO_COMPACT_WINDOW`：设置用于自动压缩计算的上下文容量（以 token 为单位）。默认使用模型自身的上下文窗口：标准模型为 200K，扩展上下文模型为 1M。使用 1M 上下文模型（如 `claude-opus-4-6[1m]`）时，可设置一个较低的值（如 `500000`）将窗口视为 500K 用于压缩计算。该值受限于模型的实际上下文窗口上限。`CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` 会基于此值的百分比生效。设置此变量可将压缩阈值与状态栏的 `used_percentage` 解耦（后者始终使用模型的完整上下文窗口）。\n\n更多选项见：[Claude Code settings](https://docs.anthropic.com/en/docs/claude-code/settings#environment-variables)\n\n也可以参考 IDE 集成说明：[Add Claude Code to your IDE](https://docs.anthropic.com/en/docs/claude-code/ide-integrations)\n\n## 与 OpenCode 一起使用\n\nOpenCode 已经有直接的 GitHub Copilot provider。本节适用于你希望让 OpenCode 通过 `@ai-sdk/anthropic` 指向这个 AI gateway，并复用本 README 前面提到的 agent 行为时。\n\n### 最小配置\n\n使用 OpenCode OAuth app 启动 AI gateway：\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth --oauth-app=opencode\nnpx @jeffreycao/copilot-api@latest start\n```\n\n然后让 OpenCode 通过 `@ai-sdk/anthropic` 指向这个 AI gateway。\n\n示例 `~/.config/opencode/opencode.json`：\n\n```json\n{\n  \"$schema\": \"https://opencode.ai/config.json\",\n  \"provider\": {\n    \"local\": {\n      \"npm\": \"@ai-sdk/anthropic\",\n      \"name\": \"My Local\",\n      \"options\": {\n        \"baseURL\": \"http://localhost:4141/v1\",\n        \"apiKey\": \"dummy\"\n      },\n      \"models\": {\n        \"gpt-5.4\": {\n          \"name\": \"gpt-5.4\",\n          \"modalities\": {\n            \"input\": [\"text\", \"image\"],\n            \"output\": [\"text\"]\n          },\n          \"limit\": {\n            \"context\": 300000,\n            \"output\": 128000\n          }\n        },\n        \"claude-sonnet-4.6\": {\n          \"id\": \"claude-sonnet-4.6\",\n          \"name\": \"claude-sonnet-4.6\",\n          \"modalities\": {\n            \"input\": [\"text\", \"image\"],\n            \"output\": [\"text\"]\n          },\n          \"limit\": {\n            \"context\": 200000,\n            \"output\": 32000\n          },\n          \"options\": {\n            \"thinking\": {\n              \"type\": \"adaptive\"\n            },\n            \"effort\": \"max\"\n          }\n        }\n      }\n    }\n  }\n}\n```\n\n这些字段的重要性：\n\n- `npm: \"@ai-sdk/anthropic\"` 是关键。OpenCode 会以 Anthropic Messages 语义与这个 AI gateway 通信，而不是把一切扁平化为 OpenAI Chat Completions。\n- `options.baseURL` 应设为 `http://localhost:4141/v1`；Anthropic SDK 会自动补上 `/messages`、`/models` 和 `/messages/count_tokens`。\n- 如果你在此代理中启用了 `auth.apiKeys`，请把 `dummy` 替换为真实 key；否则任意占位值都可以。\n\n## 与 Codex 一起使用\n\n这个 AI gateway 也可以为 Codex 提供后端能力。\n\n### Codex `config.toml` 参考配置\n\n把以下 `[model_providers.copilot_api]` 段加入你的 Codex `~/.codex/config.toml`：\n\n```toml\nmodel_provider = \"copilot_api\"\nmodel_reasoning_summary = \"auto\"\nmodel_verbosity = \"medium\"\nmodel_context_window = 272000\nmodel_auto_compact_token_limit = 244800\n\n[model_providers.copilot_api]\nname = \"OpenAI\"\nbase_url = \"http://localhost:4141\"\nenv_key = \"GITHUB_COPILOT_API_KEY\"\nrequires_openai_auth = true\nsupports_websockets = false\nwire_api = \"responses\"\nrequest_max_retries = 3\nstream_max_retries = 1\nstream_idle_timeout_ms = 300000\n\n[features]\nremote_compaction_v2 = true\n\n[analytics]\nenabled = false\n```\n\n> [!NOTE]\n> 此配置仅限于 Codex 与 GitHub Copilot provider。`name` 一定要配置为 `\"OpenAI\"`。它可以缓解 Codex local compact 不命中缓存的问题。如果你已开启 `useResponsesApiContextManagement`（Responses API context management 压缩），通常不会走到 `remote_compaction_v2` 或者 local compact，但如果工具返回 tokens 过大，仍有可能触发。\n\n## GPT Tool Search\n\n对于 `gpt-5.4+` 这类 GPT Responses 模型，这个 AI gateway 可以通过一个很小的 MCP bridge 暴露 Responses `tool_search`。Claude Code 和 opencode 都可以使用同一个 bridge，前提是客户端会加载 MCP server，并且 Anthropic Messages 流量会经过这个 AI gateway。\n\nGPT 模型不要设置 Claude Code 原生的 `ENABLE_TOOL_SEARCH`。这个开关启用的是 Claude Code 自己的客户端 tool search 模式，可能导致 deferred 工具定义不再转发给 AI gateway。这个 AI gateway 需要完整的工具定义，这样才能只保留那一小组常驻加载工具，其余工具统一转换为 Responses deferred namespace。\n\n如果你安装了 `tool-search@copilot-api-marketplace`，Claude Code 会自动带上这个 MCP bridge，可以跳过下面这段 Claude Code MCP 手动配置。\n\n请把 tool search bridge 加到 Claude Code 使用的 MCP 配置中：\n\n```json\n{\n  \"mcpServers\": {\n    \"tool_search\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@jeffreycao/copilot-api@latest\", \"mcp\"]\n    }\n  }\n}\n```\n\n请把 tool search bridge 加到 opencode 使用的 MCP 配置中：\n\n```json\n{\n  \"mcp\": {\n    \"tool_search\": {\n      \"type\": \"local\",\n      \"command\": [\"npx\", \"-y\", \"@jeffreycao/copilot-api@latest\", \"mcp\"]\n    }\n  }\n}\n```\n\n本地开发时可以将命令换成 `bun`，参数换成 `[\"run\", \"./src/main.ts\", \"mcp\"]`。\n\nAI gateway 内部现在会把 OpenAI Responses `tool_search` 配置成 client-executed 模式。deferred tools 仍然会作为可搜索 namespace 暴露给模型，但会明确要求模型直接返回下一步要加载的精确工具名列表。\n\n该 bridge 使用直接工具选择，不做 query 搜索。工具入参是 `names`，值为逗号分隔的精确 deferred 工具名，例如 `TaskList,TaskGet,mcp__fetch__fetch`。\n\n<a id=\"plugin-integrations\"></a>\n\n## 插件集成\n\n本项目为 Claude Code 和 opencode 提供了插件集成。\n\n#### Claude Code 插件集成（基于 marketplace）\n\nClaude Code 集成现在拆分为两个插件：\n\n- `agent-inject` 会在 `SubagentStart` 时注入 `__SUBAGENT_MARKER__...`，以便 AI gateway 推导 `x-initiator: agent`。\n- `tool-search` 会注册用于 GPT Responses deferred tool loading 的 `tool_search` MCP bridge。\n\n- 本仓库中的 marketplace catalog：`.claude-plugin/marketplace.json`\n- 本仓库中的插件源码：`plugin/claude/agent-inject`、`plugin/claude/tool-search`\n\n远程添加 marketplace：\n\n```sh\n/plugin marketplace add https://github.com/caozhiyuan/copilot-api.git\n```\n\n从 marketplace 安装插件：\n\n```sh\n/plugin install agent-inject@copilot-api-marketplace\n/plugin install tool-search@copilot-api-marketplace\n```\n\n安装后，`agent-inject` 会在 `SubagentStart` 时注入 `__SUBAGENT_MARKER__...`，AI gateway 会利用它推导 `x-initiator: agent`。\n\n`agent-inject` 还会注册一个 `UserPromptSubmit` hook，并返回 `{\"continue\": true}`；同时它也可以通过环境变量注入 `SessionStart` reminder 规则：\n\n- `CLAUDE_PLUGIN_ENABLE_QUESTION_RULES=1` 会自动为 Claude Code 启用两条关于使用 `question` 工具的提醒。你也可以把同样的提醒手动写进 `CLAUDE.md`；见 [CLAUDE.md 或 AGENTS.md 推荐内容](#claudemd-or-agentsmd-recommended-content)。\n- `CLAUDE_PLUGIN_ENABLE_NO_BACKGROUND_AGENTS_RULE=1` 会启用关于避免在 agent hooks 中使用 `run_in_background: true` 的提醒。\n\n`tool-search` 插件内置了 [GPT Tool Search](#gpt-tool-search) 一节描述的同一个 MCP bridge，因此安装该插件后，Claude Code 用户无需再手动配置 `tool_search` server。\n\n#### Opencode 插件\n\nsubagent 标记生成器被打包为一个 opencode 插件，位于 `plugin/opencode/subagent-marker.js`。\n\n**安装方式：**\n\n将插件文件复制到你的 opencode 插件目录：\n\n```sh\n# 克隆或下载本仓库后复制该插件\ncp plugin/opencode/subagent-marker.js ~/.config/opencode/plugins/\n```\n\n或者手动在 `~/.config/opencode/plugins/subagent-marker.js` 创建该文件，并填入插件内容。\n\n**功能：**\n\n- 跟踪 subagent 创建的子会话\n- 自动在 subagent 聊天消息前添加 marker system reminder（`__SUBAGENT_MARKER__...`）\n- 设置 `x-session-id` 请求头以跟踪会话\n- 让这个 AI gateway 能够把来自 subagent 的请求识别为 `x-initiator: agent`\n\n该插件会挂接到 `session.created`、`session.deleted`、`chat.message` 和 `chat.headers` 事件上，以无缝提供 subagent marker 能力。\n\n## 使用量查看器\n\n服务启动后，控制台会输出一个 Copilot 使用量看板 URL。这个看板是一个用于监控 API 用量的 Web 界面。\n\n1. 启动服务。例如使用 npx：\n   ```sh\n   npx @jeffreycao/copilot-api@latest start\n   ```\n2. 服务会输出一个 usage viewer 的 URL。将它复制到浏览器中打开，形式大致如下：\n   `http://localhost:4141/usage-viewer?endpoint=http://localhost:4141/usage`\n   - 如果你在 Windows 上使用 `start.bat` 脚本，这个页面会自动打开。\n\n看板提供了更易读的 Copilot 用量视图：\n\n> token usage 历史记录需要 Bun 或 Node.js >= 22.13.0。Node.js < 22.13.0 时服务会正常运行，但 token usage 存储会被禁用。\n\n- **API Endpoint URL**：通过 URL 查询参数指定 API endpoints，默认指向本地服务。支持手动切换为其他兼容 endpoints。\n- **x-api-key 认证**：如果启用了 API Key 认证，可填入 `x-api-key` 请求头。密钥会持久化保存在浏览器本地存储中。\n- **Period 选择器**：支持 Day / Week / Month 三种时间范围，切换时 URL 参数会自动同步，方便收藏和分享。\n- **Fetch Data**：点击 \"Refresh\" 按钮加载或刷新使用数据。页面加载时也会自动拉取数据。\n- **Copilot Quotas 额度**：通过进度条展示 Chat、Completions 等不同服务的额度使用情况，悬停可查看已用/剩余详情。\n- **Token Usage 指标卡片**：汇总当前周期的 Total、Input、Output、Cache Read、Cache Write、Requests 和预估费用。\n- **趋势图（Week / Month）**：提供按模型和指标筛选的折线趋势图，点击数据点可查看单日用量明细。\n- **Model Breakdown 表格**：按模型维度列出周期内的请求数、输入/输出/缓存 token 和预计费用。\n- **Request Events 分页列表**：按时间排序的请求事件记录，支持分页浏览，含时间戳、模型、请求 ID 和 token 用量。\n- **Detailed Information**：展示 API 返回的完整 JSON 响应，便于深入分析所有可用统计数据。\n- **URL-based Configuration**：也可通过 `endpoint` 和 `period` 查询参数直接指定 API 端点与时间范围。例如：\n  `http://localhost:4141/usage-viewer?endpoint=http://your-api-server/usage&period=week`\n\n### Usage Viewer 截图\n\n<p align=\"center\">\n  <img src=\"./docs/screenshots/usage-viewer.png\" alt=\"Copilot API Usage Viewer 页面\" width=\"900\" />\n</p>\n\n## 命令结构\n\nCopilot API 现在使用子命令结构，主要命令包括：\n\n- `start`：启动 AI gateway 服务。如果已有 GitHub token，则启用 Copilot 路径；如果没有 GitHub token，但存在至少一个启用中的 provider，则按 provider-only 模式启动；如果两者都没有，会引导你配置 provider。\n- `auth`：仅执行 provider 登录或配置流程，不启动服务。可用于 GitHub Copilot 登录、Codex OAuth，或第三方 provider API key 配置。\n- `debug`：显示诊断信息，包括版本、运行时详情、文件路径以及认证状态，便于排障与支持。\n\n## 命令行选项\n\n### 全局选项\n\n以下选项可用于任意子命令。若在子命令之前传入，请使用 `--key=value` 形式：\n\n| 选项 | 说明 | 默认值 | 别名 |\n| --- | --- | --- | --- |\n| --api-home | API home 目录路径（设置 `COPILOT_API_HOME`） | 无 | 无 |\n| --oauth-app | OAuth app 标识符（设置 `COPILOT_API_OAUTH_APP`） | 无 | 无 |\n| --enterprise-url | GitHub Enterprise URL（设置 `COPILOT_API_ENTERPRISE_URL`） | 无 | 无 |\n\n### Start 命令选项\n\n以下是 `start` 命令可用的命令行选项：\n\n| 选项 | 说明 | 默认值 | 别名 |\n| --- | --- | --- | --- |\n| --port | 监听端口 | 4141 | -p |\n| --verbose | 启用详细日志 | false | -v |\n| --github-token | 直接提供 GitHub token（必须通过 `auth` 子命令生成） | 无 | -g |\n| --claude-code | 生成一个使用 Copilot API 配置启动 Claude Code 的命令 | false | -c |\n| --show-token | 在获取和刷新时显示 GitHub 与 Copilot token | false | 无 |\n| --proxy-env | 从环境变量初始化代理 | false | 无 |\n\n### Auth 命令选项\n\n| 选项 | 说明 | 默认值 | 别名 |\n| --- | --- | --- | --- |\n| --provider | 要登录或配置的 provider（`copilot`、`codex`、`opencode-go`、`deepseek`、`dashscope`、`openrouter` 或 `custom`） | 交互选择 | 无 |\n| --verbose | 启用详细日志 | false | -v |\n| --show-token | 认证时显示 GitHub token | false | 无 |\n\n只有在需要启用 GitHub Copilot provider 时，才需要执行 `copilot-api auth login --provider copilot`。使用 `codex` 或第三方 provider-only 模式不要求配置 Copilot。\n\n使用 `copilot-api auth login --provider deepseek`、`--provider dashscope`、`--provider openrouter` 或 `--provider opencode-go` 可以通过 CLI 快速新增或更新这些常用第三方 provider。DeepSeek 会提示输入掩码显示的 `apiKey`、provider `type`（默认 `anthropic`），以及默认 `https://api.deepseek.com/anthropic` 的 `baseUrl`。DashScope 会提示输入掩码显示的 `apiKey`、provider `type`（默认 `openai-compatible`）和预填默认值的 `baseUrl`。OpenRouter 只提示输入掩码显示的 `apiKey` 和预填默认值的 `baseUrl`，并固定写入 `type: \"anthropic\"`。OpenCode Go 只提示输入掩码显示的 `apiKey` 和预填默认值的 `baseUrl`，并固定写入 `type: \"openai-compatible\"`（baseUrl `https://opencode.ai/zen/go`）。配置并启用 provider 后，`copilot-api start` 可在没有 GitHub token 的情况下启动。\n\n使用 `copilot-api auth login --provider custom` 可以通过 CLI 新增或更新其他第三方 provider。命令会依次提示输入 provider name、项目支持的 type（`anthropic`、`openai-compatible` 或 `openai-responses`）、`baseUrl`、掩码显示的 `apiKey` 和 `authType`；`authType` 可保持 type 默认值，也可选择 `x-api-key` / `authorization`。\n\n### Debug 命令选项\n\n| 选项 | 说明 | 默认值 | 别名 |\n| --- | --- | --- | --- |\n| --json | 以 JSON 输出调试信息 | false | 无 |\n\n<a id=\"configuration-configjson\"></a>\n\n## 配置（config.json）\n\n- **位置：** Linux/macOS 为 `~/.local/share/copilot-api/config.json`，Windows 为 `%USERPROFILE%\\.local\\share\\copilot-api\\config.json`。\n- **默认结构：**\n  ```json\n  {\n    \"auth\": {\n      \"apiKeys\": [],\n      \"adminApiKey\": \"<startup 自动生成>\"\n    },\n    \"providers\": {},\n    \"modelMappings\": {},\n    \"extraPrompts\": {\n      \"gpt-5-mini\": \"<built-in exploration prompt>\"\n    },\n    \"smallModel\": \"gpt-5-mini\",\n    \"useResponsesApiContextManagement\": true,\n    \"modelResponsesApiCompactThresholds\": {\n      \"gpt-5.4\": 217600,\n      \"gpt-5.5\": 217600\n    },\n    \"modelReasoningEfforts\": {\n      \"gpt-5-mini\": \"low\"\n    },\n    \"useMessagesApi\": true,\n    \"useResponsesApiWebSocket\": true,\n    \"useResponsesApiWebSearch\": true,\n    \"messageApiWebSearchModel\": \"gpt-5-mini\"\n  }\n  ```\n- **auth.apiKeys：** 用于普通非 admin 路由的 API key。支持多个 key 轮换使用。请求可通过 `x-api-key: <key>` 或 `Authorization: Bearer <key>` 进行认证。若为空或省略，则普通路由的认证会被禁用。\n- **auth.adminApiKey：** 仅用于 `/admin/*` 路由的单个 admin key。若未配置，服务会在启动时自动生成一个随机 key，并回写到 `config.json`。它同样使用 `x-api-key` 或 `Authorization: Bearer` 这两种头，但普通 `auth.apiKeys` 不能访问 `/admin/*`。\n- **modelMappings：** 用于顶层 `POST /v1/messages`、`POST /v1/messages/count_tokens`、`POST /v1/responses` 和 `POST /v1/chat/completions` 请求的精确 `sourceModel -> targetModel` 重写映射，这几类接口共用同一份规则。省略该字段或保留为 `{}` 时，不会做模型重写。`source` 和 `target` 都必须是非空字符串。`target` 可以是普通模型 ID，也可以是 `provider/model` 形式的别名，例如 `dashscope/qwen3.6-plus`；重写发生在 provider alias 解析之前。这些映射不再按接口区分。`GET/POST /admin/config/model-mappings` 管理接口读写的也只有这个字段。\n- **extraPrompts：** `model -> prompt` 的映射。把 Anthropic 风格请求翻译为 Responses API 时，会将其附加到第一条 system prompt 后面。你可以借此为不同模型注入护栏或指引。缺失的默认项会自动补齐，但不会覆盖你自定义的 prompt。对于 GPT-5.3+ 模型（如 `gpt-5.3-codex`、`gpt-5.4`、`gpt-5.5`），未显式配置时会自动使用内置的 commentary prompt。内置 prompt 会启用带阶段感知的 commentary，让模型在工具调用或更深层推理前先发出简短的用户可见进度说明。\n- **providers：** 全局上游 provider 映射。每个 provider key（例如 `dashscope`）都会变成一个路由前缀（`/dashscope/v1/messages`）。支持 `type: \"anthropic\"`、`type: \"openai-compatible\"` 和 `type: \"openai-responses\"`。顶层客户端也可以在 `/v1/messages`、`/v1/messages/count_tokens`、`/v1/responses` 和 `/v1/chat/completions` 中使用 `model: \"dashscope/model-id\"`；AI gateway 会在转发上游前移除 `dashscope/` 前缀。`openai-compatible` provider 同时支持 chat 和 Messages 流程：`/v1/chat/completions` 会直连上游 `/v1/chat/completions`，而 `/v1/messages` 和 `/:provider/v1/messages` 会先翻译为上游 Chat Completions，再把响应翻译回 Anthropic Messages。`GET /v1/models` 会聚合已启用 provider 的模型，并以 `provider/model-id` 形式返回；单个 provider 的原始模型列表仍可使用 `GET /dashscope/v1/models`。\n  - `enabled`：可选，若省略则默认为 `true`。\n  - `baseUrl`：provider API 的基础 URL，不要带结尾的 endpoint。Anthropic provider 不要带 `/v1/messages`；OpenAI 兼容 provider 不要带 `/v1/chat/completions`；OpenAI Responses provider 不要带 `/v1/responses`。\n  - `apiKey`：作为上游凭据值使用；普通 provider 必须配置。\n  - `authType`：可选，控制 `apiKey` 如何发送到上游。普通 provider 支持 `x-api-key` 和 `authorization`。Anthropic provider 默认 `x-api-key`；OpenAI 兼容和 OpenAI Responses provider 默认 `authorization`。当设置为 `authorization` 时，代理会发送 `Authorization: Bearer <apiKey>`。`oauth2` 仅保留给内置 `codex` provider，并由 `auth login --provider codex` 自动写入。\n  - `pricingCurrency`：可选，provider 维度的 token 费用币种，例如 `USD` 或 `CNY`。快捷 provider 默认 DashScope、DeepSeek 为 `CNY`，Codex/OpenRouter 为 `USD`。费用按币种分别汇总，不做汇率换算。\n  - `models`：可选，按模型 ID 配置的映射。每个键为请求中的模型名，值支持：\n    - `temperature`：可选，当请求未指定时使用的默认温度。\n    - `topP`：可选，当请求未指定时使用的默认 `top_p`。\n    - `topK`：可选，当请求未指定时使用的默认 `top_k`。\n    - `extraBody`：可选，按模型合入上游请求体的动态字段；请求体显式同名字段优先。OpenAI 兼容 provider 可用它配置 `enable_thinking`、`preserve_thinking`、`reasoning_effort` 等字段。`thinking_budget` 是 OpenAI 兼容 provider 的特殊覆盖项：配置在 `extraBody` 后，会在 Anthropic `thinking.budget_tokens` 翻译之后强制写入，并覆盖请求派生出的预算值。对于 provider name 为 `dashscope` 或 `baseUrl` 包含 `aliyuncs.com` 的 provider，请求派生的 `thinking_budget`（来自 Anthropic `thinking.budget_tokens`）会转发给上游；其他 OpenAI 兼容 provider 会移除请求派生的 `thinking_budget`，但 `extraBody` 中的 `thinking_budget` 仍然生效。对于 DashScope provider，当 `preserve_thinking` 未在 `extraBody` 或请求体中显式设置时，默认为 `true`。\n    - `pricing`：可选，按模型配置 token 单价，币种使用 provider 的 `pricingCurrency`，单位为每 100 万 tokens。支持 `input`、`output`、`cachedInput`（隐式缓存读）、`explicitCachedInput`（显式缓存读）和 `cacheCreationInput`。如需按输入 token 总量分档，可用带 `maxInputTokens` 的 `tiers`。\n    - `contextCache`：可选，provider name 为 `dashscope` 或 `baseUrl` 包含 `aliyuncs.com` 时默认 `true`，其他 OpenAI 兼容 provider 默认 `false`。用于启用阿里云百炼/DashScope 的显式缓存（explicit context cache），会按其 Context Cache 格式在最多 4 个 content block 上注入 `cache_control: { \"type\": \"ephemeral\" }`。缓存断点策略与 opencode 主链路保持一致：前 2 条 system 消息 + 最后 2 条非 system 消息。标记字符串 content 时会把 `system` / `user` / `assistant` / `tool` 消息转换为 text content part 数组；已有数组 content 则标记最后一个 part。如果模型本身已经支持隐式缓存，或上游不支持该显式缓存扩展字段，可在模型配置中设为 `false`。支持相同显式缓存扩展的非 DashScope provider 可设为 `true`。同时适用于 `/v1/messages` 和 `/v1/chat/completions` 路由。\n    - `supportPdf`：可选，控制该模型是否支持 PDF/document content。默认 `false`，不支持时会把 PDF 转成提示文本；设为 `true` 时会把 PDF/document 转成 OpenAI Chat Completions 的 file part。\n    - `toolContentSupportType`：可选，配置该模型的 tool result content 支持能力，值为 `array`、`image`、`pdf` 的数组。provider 侧未配置时默认只发送 string tool content。若 `supportPdf` 为 `true` 但这里不包含 `pdf`，tool result 里的 file part 会被转成 user role 消息。Copilot 主链路不使用这个 provider 默认，仍按 array + image 且不支持 PDF 的能力处理。\n    - `type`：可选，按模型覆盖 provider 的协议类型。支持 `anthropic`、`openai-compatible` 和 `openai-responses`。设置后，provider 的 `/v1/messages` 路由会使用该模型的 type 替代 provider 级别的 type 进行请求路由、认证头解析和上游端点选择。适用于 OpenCode Go 等上游对不同模型同时支持 OpenAI 兼容和 Anthropic Messages API 的 provider。覆盖 type 时，认证头按覆盖后 type 的默认值解析（Anthropic 默认 `x-api-key`；OpenAI 兼容/Responses 默认 `authorization`）。\n\n  DashScope 模型配置示例：\n  ```json\n  {\n    \"providers\": {\n      \"dashscope\": {\n        \"type\": \"openai-compatible\",\n        \"enabled\": true,\n        \"baseUrl\": \"https://dashscope.aliyuncs.com/compatible-mode\",\n        \"apiKey\": \"sk-your-dashscope-key\",\n        \"pricingCurrency\": \"CNY\",\n        \"models\": {\n          \"qwen3.7-plus\": {\n            \"temperature\": 1,\n            \"topP\": 0.95,\n            \"topK\": 20,\n            \"extraBody\": {\n              \"preserve_thinking\": true\n            }\n          },\n          \"glm-5.1\": {\n            \"temperature\": 0.7,\n            \"topP\": 0.95,\n            \"contextCache\": true,\n            \"pricing\": {\n              \"tiers\": [\n                {\n                  \"maxInputTokens\": 32000,\n                  \"input\": 6,\n                  \"cachedInput\": 1.2,\n                  \"explicitCachedInput\": 0.6,\n                  \"cacheCreationInput\": 7.5,\n                  \"output\": 24\n                },\n                {\n                  \"maxInputTokens\": 200000,\n                  \"input\": 8,\n                  \"cachedInput\": 1.6,\n                  \"explicitCachedInput\": 0.8,\n                  \"cacheCreationInput\": 10,\n                  \"output\": 28\n                }\n              ]\n            },\n            \"extraBody\": {\n              \"preserve_thinking\": true\n            }\n          }\n        }\n      }\n    }\n  }\n  ```\n  内置 token 价格覆盖 Codex GPT 模型（USD）、DashScope `qwen3.7-max`、`qwen3.7-plus`、`glm-5.1`、`glm-5.2`（CNY），DeepSeek `deepseek-v4-flash`、`deepseek-v4-pro`、`deepseek-chat`、`deepseek-reasoner`（CNY），以及 OpenCode Go 模型（`glm-5.2`、`deepseek-v4-flash`、`deepseek-v4-pro`、`kimi-k2.7-code`、`mimo-v2.5`、`mimo-v2.5-pro`、`qwen3.7-plus`、`qwen3.7-max`、`minimax-m2.5`、`minimax-m3`，USD）。用户配置的 `pricing` 优先于内置价格。DashScope 若上游 usage 中出现 `cache_creation_input_tokens` 字段，cached tokens 按显式缓存读价计费；否则 `cachedInput` 作为隐式缓存读价。DeepSeek 的 `prompt_cache_hit_tokens` 会归入 cached input，`prompt_cache_miss_tokens` 会归入普通 input。\n- **smallModel：** 无工具预热消息的回退模型（例如 Claude Code 的探测请求）；默认是 `gpt-5-mini`。\n- **useResponsesApiContextManagement：** 当为 `true` 时，代理会为 Responses API 附加 `context_management` 压缩指令。默认值为 `true`。如需全局关闭，可设为 `false`。启用后，请求体会带上 `context_management`，并在后续轮次中仅保留最新的压缩承载内容，因此特别适合长任务场景。\n- **modelResponsesApiCompactThresholds：** 按模型覆盖 Responses API 的 `compact_threshold`，仅在代理自动附加 `context_management` 时使用。它的优先级高于 `resolveResponsesCompactThreshold` 基于 `max_prompt_tokens * ratio` 的兜底阈值。默认将 `gpt-5.4` 和 `gpt-5.5` 设为 `217600`（`272000 * 0.8`）。未列出的模型继续使用原有兜底逻辑。\n- **modelReasoningEfforts：** 按模型配置的推理强度，仅作用于 `/v1/messages` 请求。当请求走 Copilot 原生 Messages API 时设置 `output_config.effort`；当请求被翻译为 Responses API 时设置 `reasoning.effort`。可选值包括 `none`、`minimal`、`low`、`medium`、`high`、`xhigh` 和 `max`。若某模型未配置，则默认使用 `high`；GPT-5.3+ 模型未显式配置时回退为 `xhigh`。\n- **useMessagesApi：** 当为 `true` 时，支持 Copilot 原生 `/v1/messages` 的 Claude 系模型会走 Messages API；否则回退到 `/chat/completions`。设为 `false` 可禁用 Messages API 路由，始终使用 `/chat/completions`。默认值为 `true`。\n- **useResponsesApiWebSocket：** 当为 `true` 时，Responses API 请求会优先对声明了 `ws:/responses` 的模型使用 Copilot websocket transport；仅声明 `/responses` 的模型仍走 HTTP。设为 `false` 可禁用 websocket 路由，并在模型支持 `/responses` 时使用 HTTP `/responses`。默认值为 `true`。\n- **useResponsesApiWebSearch：** 当为 `true` 时，服务端会保留 Responses API 中 `type: \"web_search\"` 的工具并透传到上游。设为 `false` 则会从 `/responses` payload 中移除这些工具。默认值为 `true`。\n- **messageApiWebSearchModel：** 顶层 Copilot `/v1/messages` 请求只包含服务端 `web_search` 工具时使用的全局模型，默认值为 `gpt-5-mini`。如果该值是 `provider/model` 别名，请求会进入对应 provider 的 Messages API 路径，并在转发前移除 provider 前缀。对于 Copilot GPT 模型，web search 会通过 `/responses` 执行。混合 `web_search` 与自定义工具的场景暂不支持，服务端会移除 server-side `web_search`。\n- **claudeTokenMultiplier：** 用于 Claude `/v1/messages/count_tokens` 请求在本地走 GPT tokenizer 估算时的乘数。默认值为 `1.15`。如果你的客户端仍然过晚触发上下文压缩，可以适当调大。这个配置只会在代理本地估算 Claude token 时生效；如果已经配置 `anthropicApiKey` 且 Anthropic token counting 调用成功，则会直接返回 Anthropic 的精确计数，不会使用这个乘数。\n- **anthropicApiKey：** 用于把 Claude `/v1/messages/count_tokens` 请求转发到 Anthropic 真实 token counting 端点的 API key，这样会返回精确计数，而不是 GPT tokenizer 估算值。也可通过环境变量 `ANTHROPIC_API_KEY` 设置。若未配置，或上游调用失败，则回退到由 `claudeTokenMultiplier` 控制的本地 GPT tokenizer 估算。\n\n编辑此文件后即可自定义 prompts，或替换为你自己的快速模型。修改完成后请重启服务（或重新执行命令），让缓存中的配置刷新生效。\n\n## API 认证\n\n- **受保护的普通路由：** 当配置了 `auth.apiKeys` 且非空时，除 `/`、`/usage-viewer` 和 `/usage-viewer/` 以外的普通路由都需要认证。\n- **Admin 路由：** 所有 `/admin/*` 路由都要求 `auth.adminApiKey`。如果缺失，服务会在启动时自动生成并在开始提供服务前写回 `config.json`。\n- **允许的认证头：**\n  - `x-api-key: <your_key>`\n  - `Authorization: Bearer <your_key>`\n- **CORS 预检：** `OPTIONS` 请求始终允许。\n- **未配置普通 key 时：** 普通路由仍可直接访问；但这条规则不适用于 `/admin/*`，后者只接受 `auth.adminApiKey`。\n\n普通受保护路由的示例请求：\n\n```sh\ncurl http://localhost:4141/v1/models \\\n  -H \"x-api-key: your_api_key\"\n```\n\nAdmin 路由的示例请求：\n\n```sh\ncurl http://localhost:4141/admin/config/model-mappings \\\n  -H \"x-api-key: your_admin_api_key\"\n```\n\n## API 端点\n\n服务端提供多个 OpenAI / Anthropic 兼容端点。请求会根据所选模型和 `provider/model` 别名路由到 GitHub Copilot、内置 `codex` provider 或已配置的 provider。\n\n### OpenAI 兼容端点\n\n这些端点模拟 OpenAI API 结构。\n\n| 端点 | 方法 | 说明 |\n| --- | --- | --- |\n| `POST /v1/responses` | `POST` | OpenAI 中用于生成模型响应的高级接口。支持 `openai-responses` provider 的 `provider/model` 别名。 |\n| `POST /v1/chat/completions` | `POST` | 为给定聊天对话创建模型响应。支持 `openai-compatible` provider 的 `provider/model` 别名；目标 provider 已配置时可在没有 Copilot 的情况下使用。 |\n| `GET /v1/models` | `GET` | 列出 Copilot 模型以及已启用 provider 的 `provider/model-id` 模型。 |\n| `POST /v1/embeddings` | `POST` | 创建表示输入文本的向量嵌入。 |\n\n### Anthropic 兼容端点\n\n这些端点设计为兼容 Anthropic Messages API。\n\n| 端点 | 方法 | 说明 |\n| --- | --- | --- |\n| `POST /v1/messages` | `POST` | 为给定对话创建模型响应。支持已配置 provider 的 `provider/model` 别名，包括通过 `openai-compatible` provider 做翻译。 |\n| `POST /v1/messages/count_tokens` | `POST` | 计算一组消息的 token 数。支持已配置 provider 的 `provider/model` 别名。 |\n| `POST /:provider/v1/messages` | `POST` | 将 Anthropic Messages 请求代理到已配置的 Anthropic provider，或翻译到 OpenAI 兼容 / OpenAI Responses provider。 |\n| `GET /:provider/v1/models` | `GET` | 将模型列表请求代理到已配置的 provider。 |\n| `POST /:provider/v1/messages/count_tokens` | `POST` | 为 provider 路由请求在本地计算 token 数。 |\n\n### 使用量监控端点\n\n用于监控 Copilot 用量与额度的新端点。\n\n| 端点 | 方法 | 说明 |\n| --- | --- | --- |\n| `GET /usage` | `GET` | 获取详细的 Copilot 使用统计与额度信息。 |\n| `GET /token` | `GET` | 获取当前 API 正在使用的 Copilot token。 |\n\n### Admin / 配置端点\n\n这些端点用于本地管理操作，只接受 `auth.adminApiKey`。\n\n| 端点 | 方法 | 说明 |\n| --- | --- | --- |\n| `GET /admin/config/model-mappings` | `GET` | 返回当前 `config.json` 路径以及生效中的 `modelMappings` 映射。 |\n| `POST /admin/config/model-mappings` | `POST` | 只更新 `config.json` 里的 `modelMappings` 字段，并回传更新后的结果。 |\n\n## 使用示例\n\n常用 `npx` 命令：\n\n```sh\n# 基础启动\nnpx @jeffreycao/copilot-api@latest start\n\n# 自定义端口并开启详细日志\nnpx @jeffreycao/copilot-api@latest start --port 8080 --verbose\n\n# 执行认证流程\nnpx @jeffreycao/copilot-api@latest auth login\n\n# 配置第三方 provider，然后不依赖 GitHub Copilot 启动\nnpx @jeffreycao/copilot-api@latest auth login --provider dashscope\nnpx @jeffreycao/copilot-api@latest start\n\n# 以 JSON 格式输出调试信息\nnpx @jeffreycao/copilot-api@latest debug --json\n\n# 用 Bun 而不是 Node.js 运行已发布 CLI\nbunx --bun @jeffreycao/copilot-api@latest start\n```\n\n配置 `dashscope` 后的 OpenAI 兼容 provider 调用示例：\n\n```sh\ncurl http://localhost:4141/v1/chat/completions \\\n  -H \"content-type: application/json\" \\\n  -d '{\"model\":\"dashscope/qwen3.6-plus\",\"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]}'\n\ncurl http://localhost:4141/dashscope/v1/messages \\\n  -H \"content-type: application/json\" \\\n  -d '{\"model\":\"qwen3.6-plus\",\"max_tokens\":1024,\"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]}'\n```\n\n## 使用建议\n\n<a id=\"claudemd-or-agentsmd-recommended-content\"></a>\n\n### CLAUDE.md 或 AGENTS.md 推荐内容\n\n如果你想手动加入这些提醒，请在 Claude Code 的 `CLAUDE.md`，或 opencode/codex 的 `AGENTS.md` 中加入以下内容：\n\n```\n- Prohibited from directly asking questions to users, MUST use question tool.\n- Once you can confirm that the task is complete, MUST use question tool to make user confirm. The user may respond with feedback if they are not satisfied with the result, which you can use to make improvements and try again, after try again, MUST use question tool to make user confirm again.\n```\n"}, "2fefd36681b834113d378b87513f3b16c0c9cc47": {"t": 1785765577.7998166, "n": 30635, "h": "2c1eb9fe9b2a2957", "c": "# Copilot API Proxy\n\n[English](./README.md) | 简体中文\n\n## 重要说明\n\n> [!IMPORTANT]\n> **使用前请先注意以下几点：**\n>\n> 1. **Claude Code 配置：** 与 Claude Code 搭配使用时，请将模型 ID 配置为 `claude-opus-4-8`。示例 claude `settings.json` 见 [通过 `settings.json` 手动配置](#manual-configuration-with-settingsjson)。\n>\n> 2. **内置 `copilot`、`codex` 与第三方 provider：** 执行 `npx @jeffreycao/copilot-api@latest auth`，可选择 `copilot`、`codex`、`deepseek`、`custom` 等 provider。\n>\n> 3. **注意事项：** README 顶部移除的 GitHub Copilot warning 见 [GitHub Copilot 安全提示](./NOTICE.md#github-copilot-security-notice)。\n\n---\n\n## 项目概览\n\n这是一个小型 AI gateway，可以使用 GitHub Copilot、内置 `codex` provider，也可以使用 DashScope 等已配置的第三方 provider。GitHub Copilot 现在是可选能力：如果本地没有 GitHub token，只要至少配置了一个启用中的 provider，服务仍可按 provider-only 模式启动。\n\nAI gateway 会从同一个本地端点暴露 OpenAI / Anthropic 兼容 API，让 [Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview)、OpenCode、Codex 和 OpenAI 兼容客户端可以共用同一个本地服务。\n\n在 GitHub Copilot 路径上，AI gateway 会在可用时优先使用 Copilot 原生的 Anthropic 风格 Messages API，在重工具调用场景下保留更原生的 Claude 行为。\n\n## 功能特性\n\n- **OpenAI 与 Anthropic 双兼容**：通过 `/v1/responses`、`/v1/chat/completions`、`/v1/models`、`/v1/embeddings` 和 `/v1/messages` 对外暴露同一个本地 AI gateway。\n- **Copilot 可选**：有 GitHub 凭据时可以使用 GitHub Copilot，没有 GitHub 凭据时也可以只依赖已配置的 provider 运行。\n- **同一网关接入 Copilot、`codex` 与第三方 provider**：可统一路由 GitHub Copilot、内置 `codex` provider 和配置好的外部 provider。\n- **第三方 provider 可独立启动**：配置 DashScope、DeepSeek、OpenRouter 或自定义 provider 后，不需要 GitHub Copilot 登录即可启动 AI gateway。\n- **OpenAI 兼容 provider 同时支持 chat 和 Messages API**：`openai-compatible` provider 可通过顶层 `/v1/chat/completions` 搭配 `model: \"provider/model\"` 提供 Chat Completions，也可通过 `/v1/messages` 完成 Anthropic Messages 的请求/响应翻译。\n- **面向 Claude 的更原生 Copilot 路由**：优先使用原生 `/v1/messages`，保留 Claude 风格工具流，支持 Anthropic beta 能力、通过 Responses-capable 模型支持 Claude WebSearch，并保留 subagent / session 标记。\n- **Claude Code 与 OpenCode 集成**：兼容 Claude Code 与 OpenCode，也支持通过 `@ai-sdk/anthropic` 直接作为 Anthropic provider 使用。\n- **灵活的认证与部署选项**：支持交互式登录、直接 token、个人 / Business / Enterprise、GitHub Enterprise、opencode OAuth 和自定义数据目录。\n- **多 provider 路由**：可暴露 `/:provider/...` 路由，也可在顶层 API 上使用 `model: \"provider/model\"`。\n\n## 前置要求\n\n- Bun（>= 1.2.x）\n- 如果要通过 `npx` 运行已发布 CLI，需要 Node.js\n- 只有在使用 GitHub Copilot provider 时，才需要已订阅 Copilot 的 GitHub 账号\n- 如果不使用 GitHub Copilot，需要至少一个已配置 provider 的 API key 或 OAuth 登录\n\n## 安装\n\n安装依赖：\n\n```sh\nbun install\n```\n\n直接从源码启动服务：\n\n```sh\nbun run start start\n```\n\n## 从源码运行\n\n本项目可以通过多种方式从源码运行：\n\n### 开发模式\n\n```sh\nbun run dev start\n```\n\n### 生产模式\n\n```sh\nbun run start start\n```\n\n## 通过 npx 使用\n\n你可以直接用 npx 运行本项目：\n\n> [!IMPORTANT]\n> 通过 `npx` 运行时，token usage 存储会使用 Node 内置的 `node:sqlite` 模块。该能力会在 Node.js >= 22.13.0 时启用；Node.js < 22.13.0 时 CLI 仍可启动，但会禁用 token usage 存储。\n>\n> 如果不升级 Node.js 但仍需要 token usage 存储，可以改用 Bun 运行已发布 CLI：`bunx --bun @jeffreycao/copilot-api@latest start`。\n\n```sh\nnpx @jeffreycao/copilot-api@latest start\n```\n\n带参数示例：\n\n```sh\nnpx @jeffreycao/copilot-api@latest start --port 8080\n```\n\n如果只想做认证或 provider 配置：\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth\n```\n\n如果要不依赖 GitHub Copilot 运行，先配置至少一个 provider，然后正常启动服务：\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth login --provider dashscope\nnpx @jeffreycao/copilot-api@latest start\n```\n\n## 配合 Docker 使用\n\n构建镜像：\n\n```sh\ndocker build -t copilot-api .\n```\n\n通过 bind mount 运行容器，让认证数据在重启后保留：\n\n```sh\nmkdir -p ./copilot-data\ndocker run -p 4141:4141 -v $(pwd)/copilot-data:/root/.local/share/copilot-api copilot-api\n```\n\n这会把宿主机上的 `./copilot-data` 映射到容器内的 `/root/.local/share/copilot-api`，用于持久化 GitHub 认证数据、provider 配置和其他 gateway 状态。\n\n也可以直接通过环境变量传入 GitHub token：\n\n```sh\ndocker run -p 4141:4141 -e GH_TOKEN=your_github_token_here copilot-api\n```\n\n## Electron 桌面应用\n\n如果你更喜欢图形界面，仓库里还提供了位于 `desktop/` 的 Electron 桌面应用。它支持 GitHub Copilot 登录、OpenAI Codex OAuth，以及 DeepSeek、DashScope、OpenRouter 或自定义 provider 的 API Key 配置。授权或配置 provider 后，可以一键启动或停止本地代理，并在界面里直接查看本地端点、鉴权 Header、可用模型、额度和日志。\n\n设置页还可以配置 `OAuth App`、`API Home`、`Enterprise URL`、详细日志以及最小化到托盘。桌面安装包发布在 GitHub Releases：\n\nhttps://github.com/caozhiyuan/copilot-api/releases\n\n下载对应平台的安装包后，在应用内授权或配置 provider，选择端口并启动服务，再把你的客户端指向应用里显示的本地端点即可。发布版桌面应用使用随包内置的 Electron 运行时，正常使用不需要额外安装 Node.js；token usage 历史记录会在该内置运行时支持 SQLite 时启用。\n\n桌面应用里的高级配置页会通过 `GET/POST /admin/config/model-mappings` 读写这份共享的模型映射。同一份映射会统一作用于 `POST /v1/messages`、`POST /v1/messages/count_tokens`、`POST /v1/responses` 和 `POST /v1/chat/completions`，不再按接口区分。它使用的是 `auth.adminApiKey`，不是普通的 `auth.apiKeys`；应用会在服务启动并自动生成该 key 后，直接从 `config.json` 读取它来发起请求。\n\n### 桌面应用截图\n\n下面展示了桌面应用中的首页、Token 用量统计页面：\n\n<p align=\"center\">\n  <img src=\"./docs/screenshots/desktop-dashboard.png\" alt=\"Copilot API 桌面应用首页\" width=\"49%\" />\n  <img src=\"./docs/screenshots/desktop-token-usage.png\" alt=\"Copilot API 桌面应用 Token 用量页\" width=\"49%\" />\n</p>\n\n## 与 Claude Code 一起使用\n\n这个 AI gateway 可以为 [Claude Code](https://docs.anthropic.com/en/claude-code) 提供后端能力。Claude Code 是 Anthropic 提供的实验性面向开发者的对话式 AI 助手。\n\n有两种方式可以把 Claude Code 配置为使用这个 AI gateway：\n\n### 通过 `--claude-code` 标志进行交互式配置\n\n执行带 `--claude-code` 的 `start` 命令开始：\n\n```sh\nnpx @jeffreycao/copilot-api@latest start --claude-code\n```\n\n你会被提示选择一个主模型，以及一个用于后台任务的 \"small, fast\" 模型。选择完成后，会有一条命令被复制到剪贴板中。该命令会设置 Claude Code 使用这个 AI gateway 所需的环境变量。\n\n在新的终端中粘贴并执行这条命令，即可启动 Claude Code。\n\n<a id=\"manual-configuration-with-settingsjson\"></a>\n\n### 通过 `settings.json` 手动配置\n\n另一种方式是在项目根目录中创建 `.claude/settings.json` 文件，并写入 Claude Code 所需的环境变量。这样你就不需要每次都运行交互式配置了。\n\n下面是一个 `.claude/settings.json` 示例：\n\n```json\n{\n  \"env\": {\n    \"ANTHROPIC_BASE_URL\": \"http://localhost:4141\",\n    \"ANTHROPIC_AUTH_TOKEN\": \"dummy\",\n    \"ANTHROPIC_MODEL\": \"deepseek/deepseek-v4-pro\",\n    \"ANTHROPIC_DEFAULT_SONNET_MODEL\": \"deepseek/deepseek-v4-pro\",\n    \"ANTHROPIC_DEFAULT_HAIKU_MODEL\": \"deepseek/deepseek-v4-flash\",\n    \"DISABLE_NON_ESSENTIAL_MODEL_CALLS\": \"1\",\n    \"CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC\": \"1\",\n    \"CLAUDE_CODE_ATTRIBUTION_HEADER\": \"0\",\n    \"CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION\": \"false\",\n    \"CLAUDE_CODE_DISABLE_TERMINAL_TITLE\": \"true\",\n    \"CLAUDE_CODE_ENABLE_AWAY_SUMMARY\": \"0\"\n  },\n  \"permissions\": {\n    \"deny\": [\n      \"mcp__ide__executeCode\"\n    ]\n  }\n}\n```\n\n- 请根据需要替换 `ANTHROPIC_MODEL`、`ANTHROPIC_DEFAULT_OPUS_MODEL`、`ANTHROPIC_DEFAULT_SONNET_MODEL` 和 `ANTHROPIC_DEFAULT_HAIKU_MODEL`。配置完成后，请安装 claude code 插件，见 [插件集成](#plugin-integrations)。\n- 将 `CLAUDE_CODE_ATTRIBUTION_HEADER` 设为 `0` 可以阻止 Claude Code 在 system prompt 中附加计费和版本信息，从而避免 prompt cache 失效。\n- 关闭 `CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION` 和 `CLAUDE_CODE_ENABLE_AWAY_SUMMARY` 可以避免不必要地消耗额度。\n- Claude Code WebSearch 已支持纯搜索请求。Copilot 路径请保持全局 `messageApiWebSearchModel` 指向 Responses-capable GPT 模型或 `provider/model` 别名；provider 路由请使用原生 Anthropic provider 或 `openai-responses` provider。只有在你明确想禁止这类流量时，才需要把 `WebSearch` 加到 `permissions.deny`。\n- 如果使用的不是 Claude 模型，请不要启用 `ENABLE_TOOL_SEARCH`。如果使用的是 Claude 模型，则可以启用 `ENABLE_TOOL_SEARCH`。当前 Claude Code 使用的是客户端 tool search 模式，在该模式下每次加载 defer tools 都需要额外请求一次。\n- `CLAUDE_CODE_AUTO_COMPACT_WINDOW`：设置用于自动压缩计算的上下文容量（以 token 为单位）。默认使用模型自身的上下文窗口：标准模型为 200K，扩展上下文模型为 1M。使用 1M 上下文模型（如 `claude-opus-4-6[1m]`）时，可设置一个较低的值（如 `500000`）将窗口视为 500K 用于压缩计算。该值受限于模型的实际上下文窗口上限。`CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` 会基于此值的百分比生效。设置此变量可将压缩阈值与状态栏的 `used_percentage` 解耦（后者始终使用模型的完整上下文窗口）。\n\n更多选项见：[Claude Code settings](https://docs.anthropic.com/en/docs/claude-code/settings#environment-variables)\n\n也可以参考 IDE 集成说明：[Add Claude Code to your IDE](https://docs.anthropic.com/en/docs/claude-code/ide-integrations)\n\n## 与 OpenCode 一起使用\n\nOpenCode 已经有直接的 GitHub Copilot provider。本节适用于你希望让 OpenCode 通过 `@ai-sdk/anthropic` 指向这个 AI gateway，并复用本 README 前面提到的 agent 行为时。\n\n### 最小配置\n\n使用 OpenCode OAuth app 启动 AI gateway：\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth --oauth-app=opencode\nnpx @jeffreycao/copilot-api@latest start\n```\n\n然后让 OpenCode 通过 `@ai-sdk/anthropic` 指向这个 AI gateway。\n\n示例 `~/.config/opencode/opencode.json`：\n\n```json\n{\n  \"$schema\": \"https://opencode.ai/config.json\",\n  \"provider\": {\n    \"local\": {\n      \"npm\": \"@ai-sdk/anthropic\",\n      \"name\": \"My Local\",\n      \"options\": {\n        \"baseURL\": \"http://localhost:4141/v1\",\n        \"apiKey\": \"dummy\"\n      },\n      \"models\": {\n        \"gpt-5.4\": {\n          \"name\": \"gpt-5.4\",\n          \"modalities\": {\n            \"input\": [\"text\", \"image\"],\n            \"output\": [\"text\"]\n          },\n          \"limit\": {\n            \"context\": 300000,\n            \"output\": 128000\n          }\n        },\n        \"claude-sonnet-4.6\": {\n          \"id\": \"claude-sonnet-4.6\",\n          \"name\": \"claude-sonnet-4.6\",\n          \"modalities\": {\n            \"input\": [\"text\", \"image\"],\n            \"output\": [\"text\"]\n          },\n          \"limit\": {\n            \"context\": 200000,\n            \"output\": 32000\n          },\n          \"options\": {\n            \"thinking\": {\n              \"type\": \"adaptive\"\n            },\n            \"effort\": \"max\"\n          }\n        }\n      }\n    }\n  }\n}\n```\n\n这些字段的重要性：\n\n- `npm: \"@ai-sdk/anthropic\"` 是关键。OpenCode 会以 Anthropic Messages 语义与这个 AI gateway 通信，而不是把一切扁平化为 OpenAI Chat Completions。\n- `options.baseURL` 应设为 `http://localhost:4141/v1`；Anthropic SDK 会自动补上 `/messages`、`/models` 和 `/messages/count_tokens`。\n- 如果你在此代理中启用了 `auth.apiKeys`，请把 `dummy` 替换为真实 key；否则任意占位值都可以。\n\n## 与 Codex 一起使用\n\n这个 AI gateway 也可以为 Codex 提供后端能力。\n\n### Codex `config.toml` 参考配置\n\n把以下 `[model_providers.copilot_api]` 段加入你的 Codex `~/.codex/config.toml`：\n\n```toml\nmodel_provider = \"copilot_api\"\nmodel_reasoning_summary = \"auto\"\nmodel_verbosity = \"medium\"\nmodel_context_window = 272000\nmodel_auto_compact_token_limit = 244800\n\n[model_providers.copilot_api]\nname = \"OpenAI\"\nbase_url = \"http://localhost:4141\"\nenv_key = \"GITHUB_COPILOT_API_KEY\"\nrequires_openai_auth = true\nsupports_websockets = false\nwire_api = \"responses\"\nrequest_max_retries = 3\nstream_max_retries = 1\nstream_idle_timeout_ms = 300000\n\n[features]\nremote_compaction_v2 = true\n\n[analytics]\nenabled = false\n```\n\n> [!NOTE]\n> 此配置仅限于 Codex 与 GitHub Copilot provider。`name` 一定要配置为 `\"OpenAI\"`。它可以缓解 Codex local compact 不命中缓存的问题。如果你已开启 `useResponsesApiContextManagement`（Responses API context management 压缩），通常不会走到 `remote_compaction_v2` 或者 local compact，但如果工具返回 tokens 过大，仍有可能触发。\n\n## GPT Tool Search\n\n对于 `gpt-5.4+` 这类 GPT Responses 模型，这个 AI gateway 可以通过一个很小的 MCP bridge 暴露 Responses `tool_search`。Claude Code 和 opencode 都可以使用同一个 bridge，前提是客户端会加载 MCP server，并且 Anthropic Messages 流量会经过这个 AI gateway。\n\nGPT 模型不要设置 Claude Code 原生的 `ENABLE_TOOL_SEARCH`。这个开关启用的是 Claude Code 自己的客户端 tool search 模式，可能导致 deferred 工具定义不再转发给 AI gateway。这个 AI gateway 需要完整的工具定义，这样才能只保留那一小组常驻加载工具，其余工具统一转换为 Responses deferred namespace。\n\n如果你安装了 `tool-search@copilot-api-marketplace`，Claude Code 会自动带上这个 MCP bridge，可以跳过下面这段 Claude Code MCP 手动配置。\n\n请把 tool search bridge 加到 Claude Code 使用的 MCP 配置中：\n\n```json\n{\n  \"mcpServers\": {\n    \"tool_search\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@jeffreycao/copilot-api@latest\", \"mcp\"]\n    }\n  }\n}\n```\n\n请把 tool search bridge 加到 opencode 使用的 MCP 配置中：\n\n```json\n{\n  \"mcp\": {\n    \"tool_search\": {\n      \"type\": \"local\",\n      \"command\": [\"npx\", \"-y\", \"@jeffreycao/copilot-api@latest\", \"mcp\"]\n    }\n  }\n}\n```\n\n本地开发时可以将命令换成 `bun`，参数换成 `[\"run\", \"./src/main.ts\", \"mcp\"]`。\n\nAI gateway 内部现在会把 OpenAI Responses `tool_search` 配置成 client-executed 模式。deferred tools 仍然会作为可搜索 namespace 暴露给模型，但会明确要求模型直接返回下一步要加载的精确工具名列表。\n\n该 bridge 使用直接工具选择，不做 query 搜索。工具入参是 `names`，值为逗号分隔的精确 deferred 工具名，例如 `TaskList,TaskGet,mcp__fetch__fetch`。\n\n<a id=\"plugin-integrations\"></a>\n\n## 插件集成\n\n本项目为 Claude Code 和 opencode 提供了插件集成。\n\n#### Claude Code 插件集成（基于 marketplace）\n\nClaude Code 集成现在拆分为两个插件：\n\n- `agent-inject` 会在 `SubagentStart` 时注入 `__SUBAGENT_MARKER__...`，以便 AI gateway 推导 `x-initiator: agent`。\n- `tool-search` 会注册用于 GPT Responses deferred tool loading 的 `tool_search` MCP bridge。\n\n- 本仓库中的 marketplace catalog：`.claude-plugin/marketplace.json`\n- 本仓库中的插件源码：`plugin/claude/agent-inject`、`plugin/claude/tool-search`\n\n远程添加 marketplace：\n\n```sh\n/plugin marketplace add https://github.com/caozhiyuan/copilot-api.git\n```\n\n从 marketplace 安装插件：\n\n```sh\n/plugin install agent-inject@copilot-api-marketplace\n/plugin install tool-search@copilot-api-marketplace\n```\n\n安装后，`agent-inject` 会在 `SubagentStart` 时注入 `__SUBAGENT_MARKER__...`，AI gateway 会利用它推导 `x-initiator: agent`。\n\n`agent-inject` 还会注册一个 `UserPromptSubmit` hook，并返回 `{\"continue\": true}`；同时它也可以通过环境变量注入 `SessionStart` reminder 规则：\n\n- `CLAUDE_PLUGIN_ENABLE_QUESTION_RULES=1` 会自动为 Claude Code 启用两条关于使用 `question` 工具的提醒。你也可以把同样的提醒手动写进 `CLAUDE.md`；见 [CLAUDE.md 或 AGENTS.md 推荐内容](#claudemd-or-agentsmd-recommended-content)。\n- `CLAUDE_PLUGIN_ENABLE_NO_BACKGROUND_AGENTS_RULE=1` 会启用关于避免在 agent hooks 中使用 `run_in_background: true` 的提醒。\n\n`tool-search` 插件内置了 [GPT Tool Search](#gpt-tool-search) 一节描述的同一个 MCP bridge，因此安装该插件后，Claude Code 用户无需再手动配置 `tool_search` server。\n\n#### Opencode 插件\n\nsubagent 标记生成器被打包为一个 opencode 插件，位于 `plugin/opencode/subagent-marker.js`。\n\n**安装方式：**\n\n将插件文件复制到你的 opencode 插件目录：\n\n```sh\n# 克隆或下载本仓库后复制该插件\ncp plugin/opencode/subagent-marker.js ~/.config/opencode/plugins/\n```\n\n或者手动在 `~/.config/opencode/plugins/subagent-marker.js` 创建该文件，并填入插件内容。\n\n**功能：**\n\n- 跟踪 subagent 创建的子会话\n- 自动在 subagent 聊天消息前添加 marker system reminder（`__SUBAGENT_MARKER__...`）\n- 设置 `x-session-id` 请求头以跟踪会话\n- 让这个 AI gateway 能够把来自 subagent 的请求识别为 `x-initiator: agent`\n\n该插件会挂接到 `session.created`、`session.deleted`、`chat.message` 和 `chat.headers` 事件上，以无缝提供 subagent marker 能力。\n\n## 使用量查看器\n\n服务启动后，控制台会输出一个 Copilot 使用量看板 URL。这个看板是一个用于监控 API 用量的 Web 界面。\n\n1. 启动服务。例如使用 npx：\n   ```sh\n   npx @jeffreycao/copilot-api@latest start\n   ```\n2. 服务会输出一个 usage viewer 的 URL。将它复制到浏览器中打开，形式大致如下：\n   `http://localhost:4141/usage-viewer?endpoint=http://localhost:4141/usage`\n   - 如果你在 Windows 上使用 `start.bat` 脚本，这个页面会自动打开。\n\n看板提供了更易读的 Copilot 用量视图：\n\n> token usage 历史记录需要 Bun 或 Node.js >= 22.13.0。Node.js < 22.13.0 时服务会正常运行，但 token usage 存储会被禁用。\n\n- **API Endpoint URL**：通过 URL 查询参数指定 API endpoints，默认指向本地服务。支持手动切换为其他兼容 endpoints。\n- **x-api-key 认证**：如果启用了 API Key 认证，可填入 `x-api-key` 请求头。密钥会持久化保存在浏览器本地存储中。\n- **Period 选择器**：支持 Day / Week / Month 三种时间范围，切换时 URL 参数会自动同步，方便收藏和分享。\n- **Fetch Data**：点击 \"Refresh\" 按钮加载或刷新使用数据。页面加载时也会自动拉取数据。\n- **Copilot Quotas 额度**：通过进度条展示 Chat、Completions 等不同服务的额度使用情况，悬停可查看已用/剩余详情。\n- **Token Usage 指标卡片**：汇总当前周期的 Total、Input、Output、Cache Read、Cache Write、Requests 和预估费用。\n- **趋势图（Week / Month）**：提供按模型和指标筛选的折线趋势图，点击数据点可查看单日用量明细。\n- **Model Breakdown 表格**：按模型维度列出周期内的请求数、输入/输出/缓存 token 和预计费用。\n- **Request Events 分页列表**：按时间排序的请求事件记录，支持分页浏览，含时间戳、模型、请求 ID 和 token 用量。\n- **Detailed Information**：展示 API 返回的完整 JSON 响应，便于深入分析所有可用统计数据。\n- **URL-based Configuration**：也可通过 `endpoint` 和 `period` 查询参数直接指定 API 端点与时间范围。例如：\n  `http://localhost:4141/usage-viewer?endpoint=http://your-api-server/usage&period=week`\n\n### Usage Viewer 截图\n\n<p align=\"center\">\n  <img src=\"./docs/screenshots/usage-viewer.png\" alt=\"Copilot API Usage Viewer 页面\" width=\"900\" />\n</p>\n\n## 命令结构\n\nCopilot API 现在使用子命令结构，主要命令包括：\n\n- `start`：启动 AI gateway 服务。如果已有 GitHub token，则启用 Copilot 路径；如果没有 GitHub token，但存在至少一个启用中的 provider，则按 provider-only 模式启动；如果两者都没有，会引导你配置 provider。\n- `auth`：仅执行 provider 登录或配置流程，不启动服务。可用于 GitHub Copilot 登录、Codex OAuth，或第三方 provider API key 配置。\n- `debug`：显示诊断信息，包括版本、运行时详情、文件路径以及认证状态，便于排障与支持。\n\n## 命令行选项\n\n### 全局选项\n\n以下选项可用于任意子命令。若在子命令之前传入，请使用 `--key=value` 形式：\n\n| 选项 | 说明 | 默认值 | 别名 |\n| --- | --- | --- | --- |\n| --api-home | API home 目录路径（设置 `COPILOT_API_HOME`） | 无 | 无 |\n| --oauth-app | OAuth app 标识符（设置 `COPILOT_API_OAUTH_APP`） | 无 | 无 |\n| --enterprise-url | GitHub Enterprise URL（设置 `COPILOT_API_ENTERPRISE_URL`） | 无 | 无 |\n\n### Start 命令选项\n\n以下是 `start` 命令可用的命令行选项：\n\n| 选项 | 说明 | 默认值 | 别名 |\n| --- | --- | --- | --- |\n| --port | 监听端口 | 4141 | -p |\n| --verbose | 启用详细日志 | false | -v |\n| --github-token | 直接提供 GitHub token（必须通过 `auth` 子命令生成） | 无 | -g |\n| --claude-code | 生成一个使用 Copilot API 配置启动 Claude Code 的命令 | false | -c |\n| --show-token | 在获取和刷新时显示 GitHub 与 Copilot token | false | 无 |\n| --proxy-env | 从环境变量初始化代理 | false | 无 |\n\n### Auth 命令选项\n\n| 选项 | 说明 | 默认值 | 别名 |\n| --- | --- | --- | --- |\n| --provider | 要登录或配置的 provider（`copilot`、`codex`、`opencode-go`、`deepseek`、`dashscope`、`openrouter` 或 `custom`） | 交互选择 | 无 |\n| --verbose | 启用详细日志 | false | -v |\n| --show-token | 认证时显示 GitHub token | false | 无 |\n\n只有在需要启用 GitHub Copilot provider 时，才需要执行 `copilot-api auth login --provider copilot`。使用 `codex` 或第三方 provider-only 模式不要求配置 Copilot。\n\n使用 `copilot-api auth login --provider deepseek`、`--provider dashscope`、`--provider openrouter` 或 `--provider opencode-go` 可以通过 CLI 快速新增或更新这些常用第三方 provider。DeepSeek 会提示输入掩码显示的 `apiKey`、provider `type`（默认 `anthropic`），以及默认 `https://api.deepseek.com/anthropic` 的 `baseUrl`。DashScope 会提示输入掩码显示的 `apiKey`、provider `type`（默认 `openai-compatible`）和预填默认值的 `baseUrl`。OpenRouter 只提示输入掩码显示的 `apiKey` 和预填默认值的 `baseUrl`，并固定写入 `type: \"anthropic\"`。OpenCode Go 只提示输入掩码显示的 `apiKey` 和预填默认值的 `baseUrl`，并固定写入 `type: \"openai-compatible\"`（baseUrl `https://opencode.ai/zen/go`）。配置并启用 provider 后，`copilot-api start` 可在没有 GitHub token 的情况下启动。\n\n使用 `copilot-api auth login --provider custom` 可以通过 CLI 新增或更新其他第三方 provider。命令会依次提示输入 provider name、项目支持的 type（`anthropic`、`openai-compatible` 或 `openai-responses`）、`baseUrl`、掩码显示的 `apiKey` 和 `authType`；`authType` 可保持 type 默认值，也可选择 `x-api-key` / `authorization`。\n\n### Debug 命令选项\n\n| 选项 | 说明 | 默认值 | 别名 |\n| --- | --- | --- | --- |\n| --json | 以 JSON 输出调试信息 | false | 无 |\n\n<a id=\"configuration-configjson\"></a>\n\n## 配置（config.json）\n\n- **位置：** Linux/macOS 为 `~/.local/share/copilot-api/config.json`，Windows 为 `%USERPROFILE%\\.local\\share\\copilot-api\\config.json`。\n- **默认结构：**\n  ```json\n  {\n    \"auth\": {\n      \"apiKeys\": [],\n      \"adminApiKey\": \"<startup 自动生成>\"\n    },\n    \"providers\": {},\n    \"modelMappings\": {},\n    \"extraPrompts\": {\n      \"gpt-5-mini\": \"<built-in exploration prompt>\"\n    },\n    \"smallModel\": \"gpt-5-mini\",\n    \"useResponsesApiContextManagement\": true,\n    \"modelResponsesApiCompactThresholds\": {\n      \"gpt-5.4\": 217600,\n      \"gpt-5.5\": 217600\n    },\n    \"modelReasoningEfforts\": {\n      \"gpt-5-mini\": \"low\"\n    },\n    \"useMessagesApi\": true,\n    \"useResponsesApiWebSocket\": true,\n    \"useResponsesApiWebSearch\": true,\n    \"messageApiWebSearchModel\": \"gpt-5-mini\"\n  }\n  ```\n- **auth.apiKeys：** 用于普通非 admin 路由的 API key。支持多个 key 轮换使用。请求可通过 `x-api-key: <key>` 或 `Authorization: Bearer <key>` 进行认证。若为空或省略，则普通路由的认证会被禁用。\n- **auth.adminApiKey：** 仅用于 `/admin/*` 路由的单个 admin key。若未配置，服务会在启动时自动生成一个随机 key，并回写到 `config.json`。它同样使用 `x-api-key` 或 `Authorization: Bearer` 这两种头，但普通 `auth.apiKeys` 不能访问 `/admin/*`。\n- **modelMappings：** 用于顶层 `POST /v1/messages`、`POST /v1/messages/count_tokens`、`POST /v1/responses` 和 `POST /v1/chat/completions` 请求的精确 `sourceModel -> targetModel` 重写映射，这几类接口共用同一份规则。省略该字段或保留为 `{}` 时，不会做模型重写。`source` 和 `target` 都必须是非空字符串。`target` 可以是普通模型 ID，也可以是 `provider/model` 形式的别名，例如 `dashscope/qwen3.6-plus`；重写发生在 provider alias 解析之前。这些映射不再按接口区分。`GET/POST /admin/config/model-mappings` 管理接口读写的也只有这个字段。\n- **extraPrompts：** `model -> prompt` 的映射。把 Anthropic 风格请求翻译为 Responses API 时，会将其附加到第一条 system prompt 后面。你可以借此为不同模型注入护栏或指引。缺失的默认项会自动补齐，但不会覆盖你自定义的 prompt。对于 GPT-5.3+ 模型（如 `gpt-5.3-codex`、`gpt-5.4`、`gpt-5.5`），未显式配置时会自动使用内置的 commentary prompt。内置 prompt 会启用带阶段感知的 commentary，让模型在工具调用或更深层推理前先发出简短的用户可见进度说明。\n- **providers：** 全局上游 provider 映射。每个 provider key（例如 `dashscope`）都会变成一个路由前缀（`/dashscope/v1/messages`）。支持 `type: \"anthropic\"`、`type: \"openai-compatible\"` 和 `type: \"openai-responses\"`。顶层客户端也可以在 `/v1/messages`、`/v1/messages/count_tokens`、`/v1/responses` 和 `/v1/chat/completions` 中使用 `model: \"dashscope/model-id\"`；AI gateway 会在转发上游前移除 `dashscope/` 前缀。`openai-compatible` provider 同时支持 chat 和 Messages 流程：`/v1/chat/completions` 会直连上游 `/v1/chat/completions`，而 `/v1/messages` 和 `/:provider/v1/messages` 会先翻译为上游 Chat Completions，再把响应翻译回 Anthropic Messages。`GET /v1/models` 会聚合已启用 provider 的模型，并以 `provider/model-id` 形式返回；单个 provider 的原始模型列表仍可使用 `GET /dashscope/v1/models`。\n  - `enabled`：可选，若省略则默认为 `true`。\n  - `baseUrl`：provider API 的基础 URL，不要带结尾的 endpoint。Anthropic provider 不要带 `/v1/messages`；OpenAI 兼容 provider 不要带 `/v1/chat/completions`；OpenAI Responses provider 不要带 `/v1/responses`。\n  - `apiKey`：作为上游凭据值使用；普通 provider 必须配置。\n  - `authType`：可选，控制 `apiKey` 如何发送到上游。普通 provider 支持 `x-api-key` 和 `authorization`。Anthropic provider 默认 `x-api-key`；OpenAI 兼容和 OpenAI Responses provider 默认 `authorization`。当设置为 `authorization` 时，代理会发送 `Authorization: Bearer <apiKey>`。`oauth2` 仅保留给内置 `codex` provider，并由 `auth login --provider codex` 自动写入。\n  - `pricingCurrency`：可选，provider 维度的 token 费用币种，例如 `USD` 或 `CNY`。快捷 provider 默认 DashScope、DeepSeek 为 `CNY`，Codex/OpenRouter 为 `USD`。费用按币种分别汇总，不做汇率换算。\n  - `models`：可选，按模型 ID 配置的映射。每个键为请求中的模型名，值支持：\n    - `temperature`：可选，当请求未指定时使用的默认温度。\n    - `topP`：可选，当请求未指定时使用的默认 `top_p`。\n    - `topK`：可选，当请求未指定时使用的默认 `top_k`。\n    - `extraBody`：可选，按模型合入上游请求体的动态字段；请求体显式同名字段优先。OpenAI 兼容 provider 可用它配置 `enable_thinking`、`preserve_thinking`、`reasoning_effort` 等字段。`thinking_budget` 是 OpenAI 兼容 provider 的特殊覆盖项：配置在 `extraBody` 后，会在 Anthropic `thinking.budget_tokens` 翻译之后强制写入，并覆盖请求派生出的预算值。对于 provider name 为 `dashscope` 或 `baseUrl` 包含 `aliyuncs.com` 的 provider，请求派生的 `thinking_budget`（来自 Anthropic `thinking.budget_tokens`）会转发给上游；其他 OpenAI 兼容 provider 会移除请求派生的 `thinking_budget`，但 `extraBody` 中的 `thinking_budget` 仍然生效。对于 DashScope provider，当 `preserve_thinking` 未在 `extraBody` 或请求体中显式设置时，默认为 `true`。\n    - `pricing`：可选，按模型配置 token 单价，币种使用 provider 的 `pricingCurrency`，单位为每 100 万 tokens。支持 `input`、`output`、`cachedInput`（隐式缓存读）、`explicitCachedInput`（显式缓存读）和 `cacheCreationInput`。如需按输入 token 总量分档，可用带 `maxInputTokens` 的 `tiers`。\n    - `contextCache`：可选，provider name 为 `dashscope` 或 `baseUrl` 包含 `aliyuncs.com` 时默认 `true`，其他 OpenAI 兼容 provider 默认 `false`。用于启用阿里云百炼/DashScope 的显式缓存（explicit context cache），会按其 Context Cache 格式在最多 4 个 content block 上注入 `cache_control: { \"type\": \"ephemeral\" }`。缓存断点策略与 opencode 主链路保持一致：前 2 条 system 消息 + 最后 2 条非 system 消息。标记字符串 content 时会把 `system` / `user` / `assistant` / `tool` 消息转换为 text content part 数组；已有数组 content 则标记最后一个 part。如果模型本身已经支持隐式缓存，或上游不支持该显式缓存扩展字段，可在模型配置中设为 `false`。支持相同显式缓存扩展的非 DashScope provider 可设为 `true`。同时适用于 `/v1/messages` 和 `/v1/chat/completions` 路由。\n    - `supportPdf`：可选，控制该模型是否支持 PDF/document content。默认 `false`，不支持时会把 PDF 转成提示文本；设为 `true` 时会把 PDF/document 转成 OpenAI Chat Completions 的 file part。\n    - `toolContentSupportType`：可选，配置该模型的 tool result content 支持能力，值为 `array`、`image`、`pdf` 的数组。provider 侧未配置时默认只发送 string tool content。若 `supportPdf` 为 `true` 但这里不包含 `pdf`，tool result 里的 file part 会被转成 user role 消息。Copilot 主链路不使用这个 provider 默认，仍按 array + image 且不支持 PDF 的能力处理。\n    - `type`：可选，按模型覆盖 provider 的协议类型。支持 `anthropic`、`openai-compatible` 和 `openai-responses`。设置后，provider 的 `/v1/messages` 路由会使用该模型的 type 替代 provider 级别的 type 进行请求路由、认证头解析和上游端点选择。适用于 OpenCode Go 等上游对不同模型同时支持 OpenAI 兼容和 Anthropic Messages API 的 provider。覆盖 type 时，认证头按覆盖后 type 的默认值解析（Anthropic 默认 `x-api-key`；OpenAI 兼容/Responses 默认 `authorization`）。\n\n  DashScope 模型配置示例：\n  ```json\n  {\n    \"providers\": {\n      \"dashscope\": {\n        \"type\": \"openai-compatible\",\n        \"enabled\": true,\n        \"baseUrl\": \"https://dashscope.aliyuncs.com/compatible-mode\",\n        \"apiKey\": \"sk-your-dashscope-key\",\n        \"pricingCurrency\": \"CNY\",\n        \"models\": {\n          \"qwen3.7-plus\": {\n            \"temperature\": 1,\n            \"topP\": 0.95,\n            \"topK\": 20,\n            \"extraBody\": {\n              \"preserve_thinking\": true\n            }\n          },\n          \"glm-5.1\": {\n            \"temperature\": 0.7,\n            \"topP\": 0.95,\n            \"contextCache\": true,\n            \"pricing\": {\n              \"tiers\": [\n                {\n                  \"maxInputTokens\": 32000,\n                  \"input\": 6,\n                  \"cachedInput\": 1.2,\n                  \"explicitCachedInput\": 0.6,\n                  \"cacheCreationInput\": 7.5,\n                  \"output\": 24\n                },\n                {\n                  \"maxInputTokens\": 200000,\n                  \"input\": 8,\n                  \"cachedInput\": 1.6,\n                  \"explicitCachedInput\": 0.8,\n                  \"cacheCreationInput\": 10,\n                  \"output\": 28\n                }\n              ]\n            },\n            \"extraBody\": {\n              \"preserve_thinking\": true\n            }\n          }\n        }\n      }\n    }\n  }\n  ```\n  内置 token 价格覆盖 Codex GPT 模型（USD）、DashScope `qwen3.7-max`、`qwen3.7-plus`、`glm-5.1`、`glm-5.2`（CNY），DeepSeek `deepseek-v4-flash`、`deepseek-v4-pro`、`deepseek-chat`、`deepseek-reasoner`（CNY），以及 OpenCode Go 模型（`glm-5.2`、`deepseek-v4-flash`、`deepseek-v4-pro`、`kimi-k2.7-code`、`mimo-v2.5`、`mimo-v2.5-pro`、`qwen3.7-plus`、`qwen3.7-max`、`minimax-m2.5`、`minimax-m3`，USD）。用户配置的 `pricing` 优先于内置价格。DashScope 若上游 usage 中出现 `cache_creation_input_tokens` 字段，cached tokens 按显式缓存读价计费；否则 `cachedInput` 作为隐式缓存读价。DeepSeek 的 `prompt_cache_hit_tokens` 会归入 cached input，`prompt_cache_miss_tokens` 会归入普通 input。\n- **smallModel：** 无工具预热消息的回退模型（例如 Claude Code 的探测请求）；默认是 `gpt-5-mini`。\n- **useResponsesApiContextManagement：** 当为 `true` 时，代理会为 Responses API 附加 `context_management` 压缩指令。默认值为 `true`。如需全局关闭，可设为 `false`。启用后，请求体会带上 `context_management`，并在后续轮次中仅保留最新的压缩承载内容，因此特别适合长任务场景。\n- **modelResponsesApiCompactThresholds：** 按模型覆盖 Responses API 的 `compact_threshold`，仅在代理自动附加 `context_management` 时使用。它的优先级高于 `resolveResponsesCompactThreshold` 基于 `max_prompt_tokens * ratio` 的兜底阈值。默认将 `gpt-5.4` 和 `gpt-5.5` 设为 `217600`（`272000 * 0.8`）。未列出的模型继续使用原有兜底逻辑。\n- **modelReasoningEfforts：** 按模型配置发送到 Responses API 的 `reasoning.effort`。可选值包括 `none`、`minimal`、`low`、`medium`、`high`、`xhigh` 和 `max`。若某模型未配置，则默认使用 `high`；GPT-5.3+ 模型未显式配置时回退为 `xhigh`。\n- **useMessagesApi：** 当为 `true` 时，支持 Copilot 原生 `/v1/messages` 的 Claude 系模型会走 Messages API；否则回退到 `/chat/completions`。设为 `false` 可禁用 Messages API 路由，始终使用 `/chat/completions`。默认值为 `true`。\n- **useResponsesApiWebSocket：** 当为 `true` 时，Responses API 请求会优先对声明了 `ws:/responses` 的模型使用 Copilot websocket transport；仅声明 `/responses` 的模型仍走 HTTP。设为 `false` 可禁用 websocket 路由，并在模型支持 `/responses` 时使用 HTTP `/responses`。默认值为 `true`。\n- **useResponsesApiWebSearch：** 当为 `true` 时，服务端会保留 Responses API 中 `type: \"web_search\"` 的工具并透传到上游。设为 `false` 则会从 `/responses` payload 中移除这些工具。默认值为 `true`。\n- **messageApiWebSearchModel：** 顶层 Copilot `/v1/messages` 请求只包含服务端 `web_search` 工具时使用的全局模型，默认值为 `gpt-5-mini`。如果该值是 `provider/model` 别名，请求会进入对应 provider 的 Messages API 路径，并在转发前移除 provider 前缀。对于 Copilot GPT 模型，web search 会通过 `/responses` 执行。混合 `web_search` 与自定义工具的场景暂不支持，服务端会移除 server-side `web_search`。\n- **claudeTokenMultiplier：** 用于 Claude `/v1/messages/count_tokens` 请求在本地走 GPT tokenizer 估算时的乘数。默认值为 `1.15`。如果你的客户端仍然过晚触发上下文压缩，可以适当调大。这个配置只会在代理本地估算 Claude token 时生效；如果已经配置 `anthropicApiKey` 且 Anthropic token counting 调用成功，则会直接返回 Anthropic 的精确计数，不会使用这个乘数。\n- **anthropicApiKey：** 用于把 Claude `/v1/messages/count_tokens` 请求转发到 Anthropic 真实 token counting 端点的 API key，这样会返回精确计数，而不是 GPT tokenizer 估算值。也可通过环境变量 `ANTHROPIC_API_KEY` 设置。若未配置，或上游调用失败，则回退到由 `claudeTokenMultiplier` 控制的本地 GPT tokenizer 估算。\n\n编辑此文件后即可自定义 prompts，或替换为你自己的快速模型。修改完成后请重启服务（或重新执行命令），让缓存中的配置刷新生效。\n\n## API 认证\n\n- **受保护的普通路由：** 当配置了 `auth.apiKeys` 且非空时，除 `/`、`/usage-viewer` 和 `/usage-viewer/` 以外的普通路由都需要认证。\n- **Admin 路由：** 所有 `/admin/*` 路由都要求 `auth.adminApiKey`。如果缺失，服务会在启动时自动生成并在开始提供服务前写回 `config.json`。\n- **允许的认证头：**\n  - `x-api-key: <your_key>`\n  - `Authorization: Bearer <your_key>`\n- **CORS 预检：** `OPTIONS` 请求始终允许。\n- **未配置普通 key 时：** 普通路由仍可直接访问；但这条规则不适用于 `/admin/*`，后者只接受 `auth.adminApiKey`。\n\n普通受保护路由的示例请求：\n\n```sh\ncurl http://localhost:4141/v1/models \\\n  -H \"x-api-key: your_api_key\"\n```\n\nAdmin 路由的示例请求：\n\n```sh\ncurl http://localhost:4141/admin/config/model-mappings \\\n  -H \"x-api-key: your_admin_api_key\"\n```\n\n## API 端点\n\n服务端提供多个 OpenAI / Anthropic 兼容端点。请求会根据所选模型和 `provider/model` 别名路由到 GitHub Copilot、内置 `codex` provider 或已配置的 provider。\n\n### OpenAI 兼容端点\n\n这些端点模拟 OpenAI API 结构。\n\n| 端点 | 方法 | 说明 |\n| --- | --- | --- |\n| `POST /v1/responses` | `POST` | OpenAI 中用于生成模型响应的高级接口。支持 `openai-responses` provider 的 `provider/model` 别名。 |\n| `POST /v1/chat/completions` | `POST` | 为给定聊天对话创建模型响应。支持 `openai-compatible` provider 的 `provider/model` 别名；目标 provider 已配置时可在没有 Copilot 的情况下使用。 |\n| `GET /v1/models` | `GET` | 列出 Copilot 模型以及已启用 provider 的 `provider/model-id` 模型。 |\n| `POST /v1/embeddings` | `POST` | 创建表示输入文本的向量嵌入。 |\n\n### Anthropic 兼容端点\n\n这些端点设计为兼容 Anthropic Messages API。\n\n| 端点 | 方法 | 说明 |\n| --- | --- | --- |\n| `POST /v1/messages` | `POST` | 为给定对话创建模型响应。支持已配置 provider 的 `provider/model` 别名，包括通过 `openai-compatible` provider 做翻译。 |\n| `POST /v1/messages/count_tokens` | `POST` | 计算一组消息的 token 数。支持已配置 provider 的 `provider/model` 别名。 |\n| `POST /:provider/v1/messages` | `POST` | 将 Anthropic Messages 请求代理到已配置的 Anthropic provider，或翻译到 OpenAI 兼容 / OpenAI Responses provider。 |\n| `GET /:provider/v1/models` | `GET` | 将模型列表请求代理到已配置的 provider。 |\n| `POST /:provider/v1/messages/count_tokens` | `POST` | 为 provider 路由请求在本地计算 token 数。 |\n\n### 使用量监控端点\n\n用于监控 Copilot 用量与额度的新端点。\n\n| 端点 | 方法 | 说明 |\n| --- | --- | --- |\n| `GET /usage` | `GET` | 获取详细的 Copilot 使用统计与额度信息。 |\n| `GET /token` | `GET` | 获取当前 API 正在使用的 Copilot token。 |\n\n### Admin / 配置端点\n\n这些端点用于本地管理操作，只接受 `auth.adminApiKey`。\n\n| 端点 | 方法 | 说明 |\n| --- | --- | --- |\n| `GET /admin/config/model-mappings` | `GET` | 返回当前 `config.json` 路径以及生效中的 `modelMappings` 映射。 |\n| `POST /admin/config/model-mappings` | `POST` | 只更新 `config.json` 里的 `modelMappings` 字段，并回传更新后的结果。 |\n\n## 使用示例\n\n常用 `npx` 命令：\n\n```sh\n# 基础启动\nnpx @jeffreycao/copilot-api@latest start\n\n# 自定义端口并开启详细日志\nnpx @jeffreycao/copilot-api@latest start --port 8080 --verbose\n\n# 执行认证流程\nnpx @jeffreycao/copilot-api@latest auth login\n\n# 配置第三方 provider，然后不依赖 GitHub Copilot 启动\nnpx @jeffreycao/copilot-api@latest auth login --provider dashscope\nnpx @jeffreycao/copilot-api@latest start\n\n# 以 JSON 格式输出调试信息\nnpx @jeffreycao/copilot-api@latest debug --json\n\n# 用 Bun 而不是 Node.js 运行已发布 CLI\nbunx --bun @jeffreycao/copilot-api@latest start\n```\n\n配置 `dashscope` 后的 OpenAI 兼容 provider 调用示例：\n\n```sh\ncurl http://localhost:4141/v1/chat/completions \\\n  -H \"content-type: application/json\" \\\n  -d '{\"model\":\"dashscope/qwen3.6-plus\",\"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]}'\n\ncurl http://localhost:4141/dashscope/v1/messages \\\n  -H \"content-type: application/json\" \\\n  -d '{\"model\":\"qwen3.6-plus\",\"max_tokens\":1024,\"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]}'\n```\n\n## 使用建议\n\n<a id=\"claudemd-or-agentsmd-recommended-content\"></a>\n\n### CLAUDE.md 或 AGENTS.md 推荐内容\n\n如果你想手动加入这些提醒，请在 Claude Code 的 `CLAUDE.md`，或 opencode/codex 的 `AGENTS.md` 中加入以下内容：\n\n```\n- Prohibited from directly asking questions to users, MUST use question tool.\n- Once you can confirm that the task is complete, MUST use question tool to make user confirm. The user may respond with feedback if they are not satisfied with the result, which you can use to make improvements and try again, after try again, MUST use question tool to make user confirm again.\n```\n"}, "46c3efbc6646393435b69af72cbed24d81ddfcfd": {"t": 1785765579.6807253, "n": 30866, "h": "8eb58328cada2ece", "c": "# Copilot API Proxy\n\n[English](./README.md) | 简体中文\n\n## 重要说明\n\n> [!IMPORTANT]\n> **使用前请先注意以下几点：**\n>\n> 1. **Claude Code 配置：** 与 Claude Code 搭配使用时，请将模型 ID 配置为 `claude-opus-4-8`。示例 claude `settings.json` 见 [通过 `settings.json` 手动配置](#manual-configuration-with-settingsjson)。\n>\n> 2. **内置 `copilot`、`codex` 与第三方 provider：** 执行 `npx @jeffreycao/copilot-api@latest auth`，可选择 `copilot`、`codex`、`deepseek`、`custom` 等 provider。\n>\n> 3. **注意事项：** README 顶部移除的 GitHub Copilot warning 见 [GitHub Copilot 安全提示](./NOTICE.md#github-copilot-security-notice)。\n\n---\n\n## 项目概览\n\n这是一个小型 AI gateway，可以使用 GitHub Copilot、内置 `codex` provider，也可以使用 DashScope 等已配置的第三方 provider。GitHub Copilot 现在是可选能力：如果本地没有 GitHub token，只要至少配置了一个启用中的 provider，服务仍可按 provider-only 模式启动。\n\nAI gateway 会从同一个本地端点暴露 OpenAI / Anthropic 兼容 API，让 [Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview)、OpenCode、Codex 和 OpenAI 兼容客户端可以共用同一个本地服务。\n\n在 GitHub Copilot 路径上，AI gateway 会在可用时优先使用 Copilot 原生的 Anthropic 风格 Messages API，在重工具调用场景下保留更原生的 Claude 行为。\n\n## 功能特性\n\n- **OpenAI 与 Anthropic 双兼容**：通过 `/v1/responses`、`/v1/chat/completions`、`/v1/models`、`/v1/embeddings` 和 `/v1/messages` 对外暴露同一个本地 AI gateway。\n- **Copilot 可选**：有 GitHub 凭据时可以使用 GitHub Copilot，没有 GitHub 凭据时也可以只依赖已配置的 provider 运行。\n- **同一网关接入 Copilot、`codex` 与第三方 provider**：可统一路由 GitHub Copilot、内置 `codex` provider 和配置好的外部 provider。\n- **第三方 provider 可独立启动**：配置 DashScope、DeepSeek、OpenRouter 或自定义 provider 后，不需要 GitHub Copilot 登录即可启动 AI gateway。\n- **OpenAI 兼容 provider 同时支持 chat 和 Messages API**：`openai-compatible` provider 可通过顶层 `/v1/chat/completions` 搭配 `model: \"provider/model\"` 提供 Chat Completions，也可通过 `/v1/messages` 完成 Anthropic Messages 的请求/响应翻译。\n- **面向 Claude 的更原生 Copilot 路由**：优先使用原生 `/v1/messages`，保留 Claude 风格工具流，支持 Anthropic beta 能力、通过 Responses-capable 模型支持 Claude WebSearch，并保留 subagent / session 标记。\n- **Claude Code 与 OpenCode 集成**：兼容 Claude Code 与 OpenCode，也支持通过 `@ai-sdk/anthropic` 直接作为 Anthropic provider 使用。\n- **灵活的认证与部署选项**：支持交互式登录、直接 token、个人 / Business / Enterprise、GitHub Enterprise、opencode OAuth 和自定义数据目录。\n- **多 provider 路由**：可暴露 `/:provider/...` 路由，也可在顶层 API 上使用 `model: \"provider/model\"`。\n\n## 前置要求\n\n- Bun（>= 1.2.x）\n- 如果要通过 `npx` 运行已发布 CLI，需要 Node.js\n- 只有在使用 GitHub Copilot provider 时，才需要已订阅 Copilot 的 GitHub 账号\n- 如果不使用 GitHub Copilot，需要至少一个已配置 provider 的 API key 或 OAuth 登录\n\n## 安装\n\n安装依赖：\n\n```sh\nbun install\n```\n\n直接从源码启动服务：\n\n```sh\nbun run start start\n```\n\n## 从源码运行\n\n本项目可以通过多种方式从源码运行：\n\n### 开发模式\n\n```sh\nbun run dev start\n```\n\n### 生产模式\n\n```sh\nbun run start start\n```\n\n## 通过 npx 使用\n\n你可以直接用 npx 运行本项目：\n\n> [!IMPORTANT]\n> 通过 `npx` 运行时，token usage 存储会使用 Node 内置的 `node:sqlite` 模块。该能力会在 Node.js >= 22.13.0 时启用；Node.js < 22.13.0 时 CLI 仍可启动，但会禁用 token usage 存储。\n>\n> 如果不升级 Node.js 但仍需要 token usage 存储，可以改用 Bun 运行已发布 CLI：`bunx --bun @jeffreycao/copilot-api@latest start`。\n\n```sh\nnpx @jeffreycao/copilot-api@latest start\n```\n\n带参数示例：\n\n```sh\nnpx @jeffreycao/copilot-api@latest start --port 8080\n```\n\n如果只想做认证或 provider 配置：\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth\n```\n\n如果要不依赖 GitHub Copilot 运行，先配置至少一个 provider，然后正常启动服务：\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth login --provider dashscope\nnpx @jeffreycao/copilot-api@latest start\n```\n\n## 配合 Docker 使用\n\n构建镜像：\n\n```sh\ndocker build -t copilot-api .\n```\n\n通过 bind mount 运行容器，让认证数据在重启后保留：\n\n```sh\nmkdir -p ./copilot-data\ndocker run -p 4141:4141 -v $(pwd)/copilot-data:/root/.local/share/copilot-api copilot-api\n```\n\n这会把宿主机上的 `./copilot-data` 映射到容器内的 `/root/.local/share/copilot-api`，用于持久化 GitHub 认证数据、provider 配置和其他 gateway 状态。\n\n也可以直接通过环境变量传入 GitHub token：\n\n```sh\ndocker run -p 4141:4141 -e GH_TOKEN=your_github_token_here copilot-api\n```\n\n## Electron 桌面应用\n\n如果你更喜欢图形界面，仓库里还提供了位于 `desktop/` 的 Electron 桌面应用。它支持 GitHub Copilot 登录、OpenAI Codex OAuth，以及 DeepSeek、DashScope、OpenRouter 或自定义 provider 的 API Key 配置。授权或配置 provider 后，可以一键启动或停止本地代理，并在界面里直接查看本地端点、鉴权 Header、可用模型、额度和日志。\n\n设置页还可以配置 `OAuth App`、`API Home`、`Enterprise URL`、详细日志以及最小化到托盘。桌面安装包发布在 GitHub Releases：\n\nhttps://github.com/caozhiyuan/copilot-api/releases\n\n下载对应平台的安装包后，在应用内授权或配置 provider，选择端口并启动服务，再把你的客户端指向应用里显示的本地端点即可。发布版桌面应用使用随包内置的 Electron 运行时，正常使用不需要额外安装 Node.js；token usage 历史记录会在该内置运行时支持 SQLite 时启用。\n\n桌面应用里的高级配置页会通过 `GET/POST /admin/config/model-mappings` 读写这份共享的模型映射。同一份映射会统一作用于 `POST /v1/messages`、`POST /v1/messages/count_tokens`、`POST /v1/responses` 和 `POST /v1/chat/completions`，不再按接口区分。它使用的是 `auth.adminApiKey`，不是普通的 `auth.apiKeys`；应用会在服务启动并自动生成该 key 后，直接从 `config.json` 读取它来发起请求。\n\n### 桌面应用截图\n\n下面展示了桌面应用中的首页、Token 用量统计页面：\n\n<p align=\"center\">\n  <img src=\"./docs/screenshots/desktop-dashboard.png\" alt=\"Copilot API 桌面应用首页\" width=\"49%\" />\n  <img src=\"./docs/screenshots/desktop-token-usage.png\" alt=\"Copilot API 桌面应用 Token 用量页\" width=\"49%\" />\n</p>\n\n## 与 Claude Code 一起使用\n\n这个 AI gateway 可以为 [Claude Code](https://docs.anthropic.com/en/claude-code) 提供后端能力。Claude Code 是 Anthropic 提供的实验性面向开发者的对话式 AI 助手。\n\n有两种方式可以把 Claude Code 配置为使用这个 AI gateway：\n\n### 通过 `--claude-code` 标志进行交互式配置\n\n执行带 `--claude-code` 的 `start` 命令开始：\n\n```sh\nnpx @jeffreycao/copilot-api@latest start --claude-code\n```\n\n你会被提示选择一个主模型，以及一个用于后台任务的 \"small, fast\" 模型。选择完成后，会有一条命令被复制到剪贴板中。该命令会设置 Claude Code 使用这个 AI gateway 所需的环境变量。\n\n在新的终端中粘贴并执行这条命令，即可启动 Claude Code。\n\n<a id=\"manual-configuration-with-settingsjson\"></a>\n\n### 通过 `settings.json` 手动配置\n\n另一种方式是在项目根目录中创建 `.claude/settings.json` 文件，并写入 Claude Code 所需的环境变量。这样你就不需要每次都运行交互式配置了。\n\n下面是一个 `.claude/settings.json` 示例：\n\n```json\n{\n  \"env\": {\n    \"ANTHROPIC_BASE_URL\": \"http://localhost:4141\",\n    \"ANTHROPIC_AUTH_TOKEN\": \"dummy\",\n    \"ANTHROPIC_MODEL\": \"deepseek/deepseek-v4-pro\",\n    \"ANTHROPIC_DEFAULT_SONNET_MODEL\": \"deepseek/deepseek-v4-pro\",\n    \"ANTHROPIC_DEFAULT_HAIKU_MODEL\": \"deepseek/deepseek-v4-flash\",\n    \"DISABLE_NON_ESSENTIAL_MODEL_CALLS\": \"1\",\n    \"CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC\": \"1\",\n    \"CLAUDE_CODE_ATTRIBUTION_HEADER\": \"0\",\n    \"CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION\": \"false\",\n    \"CLAUDE_CODE_DISABLE_TERMINAL_TITLE\": \"true\",\n    \"CLAUDE_CODE_ENABLE_AWAY_SUMMARY\": \"0\"\n  },\n  \"permissions\": {\n    \"deny\": [\n      \"mcp__ide__executeCode\"\n    ]\n  }\n}\n```\n\n- 请根据需要替换 `ANTHROPIC_MODEL`、`ANTHROPIC_DEFAULT_OPUS_MODEL`、`ANTHROPIC_DEFAULT_SONNET_MODEL` 和 `ANTHROPIC_DEFAULT_HAIKU_MODEL`。配置完成后，请安装 claude code 插件，见 [插件集成](#plugin-integrations)。\n- 将 `CLAUDE_CODE_ATTRIBUTION_HEADER` 设为 `0` 可以阻止 Claude Code 在 system prompt 中附加计费和版本信息，从而避免 prompt cache 失效。\n- 关闭 `CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION` 和 `CLAUDE_CODE_ENABLE_AWAY_SUMMARY` 可以避免不必要地消耗额度。\n- Claude Code WebSearch 已支持纯搜索请求。Copilot 路径请保持全局 `messageApiWebSearchModel` 指向 Responses-capable GPT 模型或 `provider/model` 别名；provider 路由请使用原生 Anthropic provider 或 `openai-responses` provider。只有在你明确想禁止这类流量时，才需要把 `WebSearch` 加到 `permissions.deny`。\n- 如果使用的不是 Claude 模型，请不要启用 `ENABLE_TOOL_SEARCH`。如果使用的是 Claude 模型，则可以启用 `ENABLE_TOOL_SEARCH`。当前 Claude Code 使用的是客户端 tool search 模式，在该模式下每次加载 defer tools 都需要额外请求一次。\n- `CLAUDE_CODE_AUTO_COMPACT_WINDOW`：设置用于自动压缩计算的上下文容量（以 token 为单位）。默认使用模型自身的上下文窗口：标准模型为 200K，扩展上下文模型为 1M。使用 1M 上下文模型（如 `claude-opus-4-6[1m]`）时，可设置一个较低的值（如 `500000`）将窗口视为 500K 用于压缩计算。该值受限于模型的实际上下文窗口上限。`CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` 会基于此值的百分比生效。设置此变量可将压缩阈值与状态栏的 `used_percentage` 解耦（后者始终使用模型的完整上下文窗口）。\n\n更多选项见：[Claude Code settings](https://docs.anthropic.com/en/docs/claude-code/settings#environment-variables)\n\n也可以参考 IDE 集成说明：[Add Claude Code to your IDE](https://docs.anthropic.com/en/docs/claude-code/ide-integrations)\n\n## 与 OpenCode 一起使用\n\nOpenCode 已经有直接的 GitHub Copilot provider。本节适用于你希望让 OpenCode 通过 `@ai-sdk/anthropic` 指向这个 AI gateway，并复用本 README 前面提到的 agent 行为时。\n\n### 最小配置\n\n使用 OpenCode OAuth app 启动 AI gateway：\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth --oauth-app=opencode\nnpx @jeffreycao/copilot-api@latest start\n```\n\n然后让 OpenCode 通过 `@ai-sdk/anthropic` 指向这个 AI gateway。\n\n示例 `~/.config/opencode/opencode.json`：\n\n```json\n{\n  \"$schema\": \"https://opencode.ai/config.json\",\n  \"provider\": {\n    \"local\": {\n      \"npm\": \"@ai-sdk/anthropic\",\n      \"name\": \"My Local\",\n      \"options\": {\n        \"baseURL\": \"http://localhost:4141/v1\",\n        \"apiKey\": \"dummy\"\n      },\n      \"models\": {\n        \"gpt-5.4\": {\n          \"name\": \"gpt-5.4\",\n          \"modalities\": {\n            \"input\": [\"text\", \"image\"],\n            \"output\": [\"text\"]\n          },\n          \"limit\": {\n            \"context\": 300000,\n            \"output\": 128000\n          }\n        },\n        \"claude-sonnet-4.6\": {\n          \"id\": \"claude-sonnet-4.6\",\n          \"name\": \"claude-sonnet-4.6\",\n          \"modalities\": {\n            \"input\": [\"text\", \"image\"],\n            \"output\": [\"text\"]\n          },\n          \"limit\": {\n            \"context\": 200000,\n            \"output\": 32000\n          },\n          \"options\": {\n            \"thinking\": {\n              \"type\": \"adaptive\"\n            },\n            \"effort\": \"max\"\n          }\n        }\n      }\n    }\n  }\n}\n```\n\n这些字段的重要性：\n\n- `npm: \"@ai-sdk/anthropic\"` 是关键。OpenCode 会以 Anthropic Messages 语义与这个 AI gateway 通信，而不是把一切扁平化为 OpenAI Chat Completions。\n- `options.baseURL` 应设为 `http://localhost:4141/v1`；Anthropic SDK 会自动补上 `/messages`、`/models` 和 `/messages/count_tokens`。\n- 如果你在此代理中启用了 `auth.apiKeys`，请把 `dummy` 替换为真实 key；否则任意占位值都可以。\n\n## 与 Codex 一起使用\n\n这个 AI gateway 也可以为 Codex 提供后端能力。\n\n### Codex `config.toml` 参考配置\n\n把以下 `[model_providers.copilot_api]` 段加入你的 Codex `~/.codex/config.toml`：\n\n```toml\nmodel_provider = \"copilot_api\"\nmodel_reasoning_summary = \"auto\"\nmodel_verbosity = \"medium\"\nmodel_context_window = 272000\nmodel_auto_compact_token_limit = 244800\n\n[model_providers.copilot_api]\nname = \"OpenAI\"\nbase_url = \"http://localhost:4141\"\nenv_key = \"GITHUB_COPILOT_API_KEY\"\nrequires_openai_auth = true\nsupports_websockets = false\nwire_api = \"responses\"\nrequest_max_retries = 3\nstream_max_retries = 1\nstream_idle_timeout_ms = 300000\n\n[features]\nremote_compaction_v2 = true\n\n[analytics]\nenabled = false\n```\n\n> [!NOTE]\n> 此配置仅限于 Codex 与 GitHub Copilot provider。`name` 一定要配置为 `\"OpenAI\"`。它可以缓解 Codex local compact 不命中缓存的问题。如果你已开启 `useResponsesApiContextManagement`（Responses API context management 压缩），通常不会走到 `remote_compaction_v2` 或者 local compact，但如果工具返回 tokens 过大，仍有可能触发。\n\n## GPT Tool Search\n\n对于 `gpt-5.4+` 这类 GPT Responses 模型，这个 AI gateway 可以通过一个很小的 MCP bridge 暴露 Responses `tool_search`。Claude Code 和 opencode 都可以使用同一个 bridge，前提是客户端会加载 MCP server，并且 Anthropic Messages 流量会经过这个 AI gateway。\n\nGPT 模型不要设置 Claude Code 原生的 `ENABLE_TOOL_SEARCH`。这个开关启用的是 Claude Code 自己的客户端 tool search 模式，可能导致 deferred 工具定义不再转发给 AI gateway。这个 AI gateway 需要完整的工具定义，这样才能只保留那一小组常驻加载工具，其余工具统一转换为 Responses deferred namespace。\n\n如果你安装了 `tool-search@copilot-api-marketplace`，Claude Code 会自动带上这个 MCP bridge，可以跳过下面这段 Claude Code MCP 手动配置。\n\n请把 tool search bridge 加到 Claude Code 使用的 MCP 配置中：\n\n```json\n{\n  \"mcpServers\": {\n    \"tool_search\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@jeffreycao/copilot-api@latest\", \"mcp\"]\n    }\n  }\n}\n```\n\n请把 tool search bridge 加到 opencode 使用的 MCP 配置中：\n\n```json\n{\n  \"mcp\": {\n    \"tool_search\": {\n      \"type\": \"local\",\n      \"command\": [\"npx\", \"-y\", \"@jeffreycao/copilot-api@latest\", \"mcp\"]\n    }\n  }\n}\n```\n\n本地开发时可以将命令换成 `bun`，参数换成 `[\"run\", \"./src/main.ts\", \"mcp\"]`。\n\nAI gateway 内部现在会把 OpenAI Responses `tool_search` 配置成 client-executed 模式。deferred tools 仍然会作为可搜索 namespace 暴露给模型，但会明确要求模型直接返回下一步要加载的精确工具名列表。\n\n该 bridge 使用直接工具选择，不做 query 搜索。工具入参是 `names`，值为逗号分隔的精确 deferred 工具名，例如 `TaskList,TaskGet,mcp__fetch__fetch`。\n\n<a id=\"plugin-integrations\"></a>\n\n## 插件集成\n\n本项目为 Claude Code 和 opencode 提供了插件集成。\n\n#### Claude Code 插件集成（基于 marketplace）\n\nClaude Code 集成现在拆分为两个插件：\n\n- `agent-inject` 会在 `SubagentStart` 时注入 `__SUBAGENT_MARKER__...`，以便 AI gateway 推导 `x-initiator: agent`。\n- `tool-search` 会注册用于 GPT Responses deferred tool loading 的 `tool_search` MCP bridge。\n\n- 本仓库中的 marketplace catalog：`.claude-plugin/marketplace.json`\n- 本仓库中的插件源码：`plugin/claude/agent-inject`、`plugin/claude/tool-search`\n\n远程添加 marketplace：\n\n```sh\n/plugin marketplace add https://github.com/caozhiyuan/copilot-api.git\n```\n\n从 marketplace 安装插件：\n\n```sh\n/plugin install agent-inject@copilot-api-marketplace\n/plugin install tool-search@copilot-api-marketplace\n```\n\n安装后，`agent-inject` 会在 `SubagentStart` 时注入 `__SUBAGENT_MARKER__...`，AI gateway 会利用它推导 `x-initiator: agent`。\n\n`agent-inject` 还会注册一个 `UserPromptSubmit` hook，并返回 `{\"continue\": true}`；同时它也可以通过环境变量注入 `SessionStart` reminder 规则：\n\n- `CLAUDE_PLUGIN_ENABLE_QUESTION_RULES=1` 会自动为 Claude Code 启用两条关于使用 `question` 工具的提醒。你也可以把同样的提醒手动写进 `CLAUDE.md`；见 [CLAUDE.md 或 AGENTS.md 推荐内容](#claudemd-or-agentsmd-recommended-content)。\n- `CLAUDE_PLUGIN_ENABLE_NO_BACKGROUND_AGENTS_RULE=1` 会启用关于避免在 agent hooks 中使用 `run_in_background: true` 的提醒。\n\n`tool-search` 插件内置了 [GPT Tool Search](#gpt-tool-search) 一节描述的同一个 MCP bridge，因此安装该插件后，Claude Code 用户无需再手动配置 `tool_search` server。\n\n#### Opencode 插件\n\nsubagent 标记生成器被打包为一个 opencode 插件，位于 `plugin/opencode/subagent-marker.js`。\n\n**安装方式：**\n\n将插件文件复制到你的 opencode 插件目录：\n\n```sh\n# 克隆或下载本仓库后复制该插件\ncp plugin/opencode/subagent-marker.js ~/.config/opencode/plugins/\n```\n\n或者手动在 `~/.config/opencode/plugins/subagent-marker.js` 创建该文件，并填入插件内容。\n\n**功能：**\n\n- 跟踪 subagent 创建的子会话\n- 自动在 subagent 聊天消息前添加 marker system reminder（`__SUBAGENT_MARKER__...`）\n- 设置 `x-session-id` 请求头以跟踪会话\n- 让这个 AI gateway 能够把来自 subagent 的请求识别为 `x-initiator: agent`\n\n该插件会挂接到 `session.created`、`session.deleted`、`chat.message` 和 `chat.headers` 事件上，以无缝提供 subagent marker 能力。\n\n## 使用量查看器\n\n服务启动后，控制台会输出一个 Copilot 使用量看板 URL。这个看板是一个用于监控 API 用量的 Web 界面。\n\n1. 启动服务。例如使用 npx：\n   ```sh\n   npx @jeffreycao/copilot-api@latest start\n   ```\n2. 服务会输出一个 usage viewer 的 URL。将它复制到浏览器中打开，形式大致如下：\n   `http://localhost:4141/usage-viewer?endpoint=http://localhost:4141/usage`\n   - 如果你在 Windows 上使用 `start.bat` 脚本，这个页面会自动打开。\n\n看板提供了更易读的 Copilot 用量视图：\n\n> token usage 历史记录需要 Bun 或 Node.js >= 22.13.0。Node.js < 22.13.0 时服务会正常运行，但 token usage 存储会被禁用。\n\n- **API Endpoint URL**：通过 URL 查询参数指定 API endpoints，默认指向本地服务。支持手动切换为其他兼容 endpoints。\n- **x-api-key 认证**：如果启用了 API Key 认证，可填入 `x-api-key` 请求头。密钥会持久化保存在浏览器本地存储中。\n- **Period 选择器**：支持 Day / Week / Month 三种时间范围，切换时 URL 参数会自动同步，方便收藏和分享。\n- **Fetch Data**：点击 \"Refresh\" 按钮加载或刷新使用数据。页面加载时也会自动拉取数据。\n- **Copilot Quotas 额度**：通过进度条展示 Chat、Completions 等不同服务的额度使用情况，悬停可查看已用/剩余详情。\n- **Token Usage 指标卡片**：汇总当前周期的 Total、Input、Output、Cache Read、Cache Write、Requests 和预估费用。\n- **趋势图（Week / Month）**：提供按模型和指标筛选的折线趋势图，点击数据点可查看单日用量明细。\n- **Model Breakdown 表格**：按模型维度列出周期内的请求数、输入/输出/缓存 token 和预计费用。\n- **Request Events 分页列表**：按时间排序的请求事件记录，支持分页浏览，含时间戳、模型、请求 ID 和 token 用量。\n- **Detailed Information**：展示 API 返回的完整 JSON 响应，便于深入分析所有可用统计数据。\n- **URL-based Configuration**：也可通过 `endpoint` 和 `period` 查询参数直接指定 API 端点与时间范围。例如：\n  `http://localhost:4141/usage-viewer?endpoint=http://your-api-server/usage&period=week`\n\n### Usage Viewer 截图\n\n<p align=\"center\">\n  <img src=\"./docs/screenshots/usage-viewer.png\" alt=\"Copilot API Usage Viewer 页面\" width=\"900\" />\n</p>\n\n## 命令结构\n\nCopilot API 现在使用子命令结构，主要命令包括：\n\n- `start`：启动 AI gateway 服务。如果已有 GitHub token，则启用 Copilot 路径；如果没有 GitHub token，但存在至少一个启用中的 provider，则按 provider-only 模式启动；如果两者都没有，会引导你配置 provider。\n- `auth`：仅执行 provider 登录或配置流程，不启动服务。可用于 GitHub Copilot 登录、Codex OAuth，或第三方 provider API key 配置。\n- `debug`：显示诊断信息，包括版本、运行时详情、文件路径以及认证状态，便于排障与支持。\n\n## 命令行选项\n\n### 全局选项\n\n以下选项可用于任意子命令。若在子命令之前传入，请使用 `--key=value` 形式：\n\n| 选项 | 说明 | 默认值 | 别名 |\n| --- | --- | --- | --- |\n| --api-home | API home 目录路径（设置 `COPILOT_API_HOME`） | 无 | 无 |\n| --oauth-app | OAuth app 标识符（设置 `COPILOT_API_OAUTH_APP`） | 无 | 无 |\n| --enterprise-url | GitHub Enterprise URL（设置 `COPILOT_API_ENTERPRISE_URL`） | 无 | 无 |\n\n### Start 命令选项\n\n以下是 `start` 命令可用的命令行选项：\n\n| 选项 | 说明 | 默认值 | 别名 |\n| --- | --- | --- | --- |\n| --port | 监听端口 | 4141 | -p |\n| --verbose | 启用详细日志 | false | -v |\n| --github-token | 直接提供 GitHub token（必须通过 `auth` 子命令生成） | 无 | -g |\n| --claude-code | 生成一个使用 Copilot API 配置启动 Claude Code 的命令 | false | -c |\n| --show-token | 在获取和刷新时显示 GitHub 与 Copilot token | false | 无 |\n| --proxy-env | 从环境变量初始化代理 | false | 无 |\n\n### Auth 命令选项\n\n| 选项 | 说明 | 默认值 | 别名 |\n| --- | --- | --- | --- |\n| --provider | 要登录或配置的 provider（`copilot`、`codex`、`opencode-go`、`deepseek`、`dashscope`、`openrouter` 或 `custom`） | 交互选择 | 无 |\n| --verbose | 启用详细日志 | false | -v |\n| --show-token | 认证时显示 GitHub token | false | 无 |\n\n只有在需要启用 GitHub Copilot provider 时，才需要执行 `copilot-api auth login --provider copilot`。使用 `codex` 或第三方 provider-only 模式不要求配置 Copilot。\n\n使用 `copilot-api auth login --provider deepseek`、`--provider dashscope`、`--provider openrouter` 或 `--provider opencode-go` 可以通过 CLI 快速新增或更新这些常用第三方 provider。DeepSeek 会提示输入掩码显示的 `apiKey`、provider `type`（默认 `anthropic`），以及默认 `https://api.deepseek.com/anthropic` 的 `baseUrl`。DashScope 会提示输入掩码显示的 `apiKey`、provider `type`（默认 `openai-compatible`）和预填默认值的 `baseUrl`。OpenRouter 只提示输入掩码显示的 `apiKey` 和预填默认值的 `baseUrl`，并固定写入 `type: \"anthropic\"`。OpenCode Go 只提示输入掩码显示的 `apiKey` 和预填默认值的 `baseUrl`，并固定写入 `type: \"openai-compatible\"`（baseUrl `https://opencode.ai/zen/go`）。配置并启用 provider 后，`copilot-api start` 可在没有 GitHub token 的情况下启动。\n\n使用 `copilot-api auth login --provider custom` 可以通过 CLI 新增或更新其他第三方 provider。命令会依次提示输入 provider name、项目支持的 type（`anthropic`、`openai-compatible` 或 `openai-responses`）、`baseUrl`、掩码显示的 `apiKey` 和 `authType`；`authType` 可保持 type 默认值，也可选择 `x-api-key` / `authorization`。\n\n### Debug 命令选项\n\n| 选项 | 说明 | 默认值 | 别名 |\n| --- | --- | --- | --- |\n| --json | 以 JSON 输出调试信息 | false | 无 |\n\n<a id=\"configuration-configjson\"></a>\n\n## 配置（config.json）\n\n- **位置：** Linux/macOS 为 `~/.local/share/copilot-api/config.json`，Windows 为 `%USERPROFILE%\\.local\\share\\copilot-api\\config.json`。\n- **默认结构：**\n  ```json\n  {\n    \"auth\": {\n      \"apiKeys\": [],\n      \"adminApiKey\": \"<startup 自动生成>\"\n    },\n    \"providers\": {},\n    \"modelMappings\": {},\n    \"extraPrompts\": {\n      \"gpt-5-mini\": \"<built-in exploration prompt>\",\n      \"gpt-5.3-codex\": \"<built-in commentary prompt>\",\n      \"gpt-5.4-mini\": \"<built-in commentary prompt>\",\n      \"gpt-5.4\": \"<built-in commentary prompt>\",\n      \"gpt-5.5\": \"<built-in commentary prompt>\"\n    },\n    \"smallModel\": \"gpt-5-mini\",\n    \"useResponsesApiContextManagement\": true,\n    \"modelResponsesApiCompactThresholds\": {\n      \"gpt-5.4\": 217600,\n      \"gpt-5.5\": 217600\n    },\n    \"modelReasoningEfforts\": {\n      \"gpt-5-mini\": \"low\",\n      \"gpt-5.3-codex\": \"xhigh\",\n      \"gpt-5.4-mini\": \"xhigh\",\n      \"gpt-5.4\": \"xhigh\",\n      \"gpt-5.5\": \"xhigh\"\n    },\n    \"useMessagesApi\": true,\n    \"useResponsesApiWebSocket\": true,\n    \"useResponsesApiWebSearch\": true,\n    \"messageApiWebSearchModel\": \"gpt-5-mini\"\n  }\n  ```\n- **auth.apiKeys：** 用于普通非 admin 路由的 API key。支持多个 key 轮换使用。请求可通过 `x-api-key: <key>` 或 `Authorization: Bearer <key>` 进行认证。若为空或省略，则普通路由的认证会被禁用。\n- **auth.adminApiKey：** 仅用于 `/admin/*` 路由的单个 admin key。若未配置，服务会在启动时自动生成一个随机 key，并回写到 `config.json`。它同样使用 `x-api-key` 或 `Authorization: Bearer` 这两种头，但普通 `auth.apiKeys` 不能访问 `/admin/*`。\n- **modelMappings：** 用于顶层 `POST /v1/messages`、`POST /v1/messages/count_tokens`、`POST /v1/responses` 和 `POST /v1/chat/completions` 请求的精确 `sourceModel -> targetModel` 重写映射，这几类接口共用同一份规则。省略该字段或保留为 `{}` 时，不会做模型重写。`source` 和 `target` 都必须是非空字符串。`target` 可以是普通模型 ID，也可以是 `provider/model` 形式的别名，例如 `dashscope/qwen3.6-plus`；重写发生在 provider alias 解析之前。这些映射不再按接口区分。`GET/POST /admin/config/model-mappings` 管理接口读写的也只有这个字段。\n- **extraPrompts：** `model -> prompt` 的映射。把 Anthropic 风格请求翻译给 Copilot 时，会将其附加到第一条 system prompt 后面。你可以借此为不同模型注入护栏或指引。缺失的默认项会自动补齐，但不会覆盖你自定义的 prompt。内置的 `gpt-5.3-codex` 和 `gpt-5.4` prompt 会启用带阶段感知的 commentary，让模型在工具调用或更深层推理前先发出简短的用户可见进度说明。\n- **providers：** 全局上游 provider 映射。每个 provider key（例如 `dashscope`）都会变成一个路由前缀（`/dashscope/v1/messages`）。支持 `type: \"anthropic\"`、`type: \"openai-compatible\"` 和 `type: \"openai-responses\"`。顶层客户端也可以在 `/v1/messages`、`/v1/messages/count_tokens`、`/v1/responses` 和 `/v1/chat/completions` 中使用 `model: \"dashscope/model-id\"`；AI gateway 会在转发上游前移除 `dashscope/` 前缀。`openai-compatible` provider 同时支持 chat 和 Messages 流程：`/v1/chat/completions` 会直连上游 `/v1/chat/completions`，而 `/v1/messages` 和 `/:provider/v1/messages` 会先翻译为上游 Chat Completions，再把响应翻译回 Anthropic Messages。`GET /v1/models` 会聚合已启用 provider 的模型，并以 `provider/model-id` 形式返回；单个 provider 的原始模型列表仍可使用 `GET /dashscope/v1/models`。\n  - `enabled`：可选，若省略则默认为 `true`。\n  - `baseUrl`：provider API 的基础 URL，不要带结尾的 endpoint。Anthropic provider 不要带 `/v1/messages`；OpenAI 兼容 provider 不要带 `/v1/chat/completions`；OpenAI Responses provider 不要带 `/v1/responses`。\n  - `apiKey`：作为上游凭据值使用；普通 provider 必须配置。\n  - `authType`：可选，控制 `apiKey` 如何发送到上游。普通 provider 支持 `x-api-key` 和 `authorization`。Anthropic provider 默认 `x-api-key`；OpenAI 兼容和 OpenAI Responses provider 默认 `authorization`。当设置为 `authorization` 时，代理会发送 `Authorization: Bearer <apiKey>`。`oauth2` 仅保留给内置 `codex` provider，并由 `auth login --provider codex` 自动写入。\n  - `pricingCurrency`：可选，provider 维度的 token 费用币种，例如 `USD` 或 `CNY`。快捷 provider 默认 DashScope、DeepSeek 为 `CNY`，Codex/OpenRouter 为 `USD`。费用按币种分别汇总，不做汇率换算。\n  - `models`：可选，按模型 ID 配置的映射。每个键为请求中的模型名，值支持：\n    - `temperature`：可选，当请求未指定时使用的默认温度。\n    - `topP`：可选，当请求未指定时使用的默认 `top_p`。\n    - `topK`：可选，当请求未指定时使用的默认 `top_k`。\n    - `extraBody`：可选，按模型合入上游请求体的动态字段；请求体显式同名字段优先。OpenAI 兼容 provider 可用它配置 `enable_thinking`、`preserve_thinking`、`reasoning_effort` 等字段。`thinking_budget` 是 OpenAI 兼容 provider 的特殊覆盖项：配置在 `extraBody` 后，会在 Anthropic `thinking.budget_tokens` 翻译之后强制写入，并覆盖请求派生出的预算值。对于 provider name 为 `dashscope` 或 `baseUrl` 包含 `aliyuncs.com` 的 provider，请求派生的 `thinking_budget`（来自 Anthropic `thinking.budget_tokens`）会转发给上游；其他 OpenAI 兼容 provider 会移除请求派生的 `thinking_budget`，但 `extraBody` 中的 `thinking_budget` 仍然生效。对于 DashScope provider，当 `preserve_thinking` 未在 `extraBody` 或请求体中显式设置时，默认为 `true`。\n    - `pricing`：可选，按模型配置 token 单价，币种使用 provider 的 `pricingCurrency`，单位为每 100 万 tokens。支持 `input`、`output`、`cachedInput`（隐式缓存读）、`explicitCachedInput`（显式缓存读）和 `cacheCreationInput`。如需按输入 token 总量分档，可用带 `maxInputTokens` 的 `tiers`。\n    - `contextCache`：可选，provider name 为 `dashscope` 或 `baseUrl` 包含 `aliyuncs.com` 时默认 `true`，其他 OpenAI 兼容 provider 默认 `false`。用于启用阿里云百炼/DashScope 的显式缓存（explicit context cache），会按其 Context Cache 格式在最多 4 个 content block 上注入 `cache_control: { \"type\": \"ephemeral\" }`。缓存断点策略与 opencode 主链路保持一致：前 2 条 system 消息 + 最后 2 条非 system 消息。标记字符串 content 时会把 `system` / `user` / `assistant` / `tool` 消息转换为 text content part 数组；已有数组 content 则标记最后一个 part。如果模型本身已经支持隐式缓存，或上游不支持该显式缓存扩展字段，可在模型配置中设为 `false`。支持相同显式缓存扩展的非 DashScope provider 可设为 `true`。同时适用于 `/v1/messages` 和 `/v1/chat/completions` 路由。\n    - `supportPdf`：可选，控制该模型是否支持 PDF/document content。默认 `false`，不支持时会把 PDF 转成提示文本；设为 `true` 时会把 PDF/document 转成 OpenAI Chat Completions 的 file part。\n    - `toolContentSupportType`：可选，配置该模型的 tool result content 支持能力，值为 `array`、`image`、`pdf` 的数组。provider 侧未配置时默认只发送 string tool content。若 `supportPdf` 为 `true` 但这里不包含 `pdf`，tool result 里的 file part 会被转成 user role 消息。Copilot 主链路不使用这个 provider 默认，仍按 array + image 且不支持 PDF 的能力处理。\n    - `type`：可选，按模型覆盖 provider 的协议类型。支持 `anthropic`、`openai-compatible` 和 `openai-responses`。设置后，provider 的 `/v1/messages` 路由会使用该模型的 type 替代 provider 级别的 type 进行请求路由、认证头解析和上游端点选择。适用于 OpenCode Go 等上游对不同模型同时支持 OpenAI 兼容和 Anthropic Messages API 的 provider。覆盖 type 时，认证头按覆盖后 type 的默认值解析（Anthropic 默认 `x-api-key`；OpenAI 兼容/Responses 默认 `authorization`）。\n\n  DashScope 模型配置示例：\n  ```json\n  {\n    \"providers\": {\n      \"dashscope\": {\n        \"type\": \"openai-compatible\",\n        \"enabled\": true,\n        \"baseUrl\": \"https://dashscope.aliyuncs.com/compatible-mode\",\n        \"apiKey\": \"sk-your-dashscope-key\",\n        \"pricingCurrency\": \"CNY\",\n        \"models\": {\n          \"qwen3.7-plus\": {\n            \"temperature\": 1,\n            \"topP\": 0.95,\n            \"topK\": 20,\n            \"extraBody\": {\n              \"preserve_thinking\": true\n            }\n          },\n          \"glm-5.1\": {\n            \"temperature\": 0.7,\n            \"topP\": 0.95,\n            \"contextCache\": true,\n            \"pricing\": {\n              \"tiers\": [\n                {\n                  \"maxInputTokens\": 32000,\n                  \"input\": 6,\n                  \"cachedInput\": 1.2,\n                  \"explicitCachedInput\": 0.6,\n                  \"cacheCreationInput\": 7.5,\n                  \"output\": 24\n                },\n                {\n                  \"maxInputTokens\": 200000,\n                  \"input\": 8,\n                  \"cachedInput\": 1.6,\n                  \"explicitCachedInput\": 0.8,\n                  \"cacheCreationInput\": 10,\n                  \"output\": 28\n                }\n              ]\n            },\n            \"extraBody\": {\n              \"preserve_thinking\": true\n            }\n          }\n        }\n      }\n    }\n  }\n  ```\n  内置 token 价格覆盖 Codex GPT 模型（USD）、DashScope `qwen3.7-max`、`qwen3.7-plus`、`glm-5.1`、`glm-5.2`（CNY），DeepSeek `deepseek-v4-flash`、`deepseek-v4-pro`、`deepseek-chat`、`deepseek-reasoner`（CNY），以及 OpenCode Go 模型（`glm-5.2`、`deepseek-v4-flash`、`deepseek-v4-pro`、`kimi-k2.7-code`、`mimo-v2.5`、`mimo-v2.5-pro`、`qwen3.7-plus`、`qwen3.7-max`、`minimax-m2.5`、`minimax-m3`，USD）。用户配置的 `pricing` 优先于内置价格。DashScope 若上游 usage 中出现 `cache_creation_input_tokens` 字段，cached tokens 按显式缓存读价计费；否则 `cachedInput` 作为隐式缓存读价。DeepSeek 的 `prompt_cache_hit_tokens` 会归入 cached input，`prompt_cache_miss_tokens` 会归入普通 input。\n- **smallModel：** 无工具预热消息的回退模型（例如 Claude Code 的探测请求）；默认是 `gpt-5-mini`。\n- **useResponsesApiContextManagement：** 当为 `true` 时，代理会为 Responses API 附加 `context_management` 压缩指令。默认值为 `true`。如需全局关闭，可设为 `false`。启用后，请求体会带上 `context_management`，并在后续轮次中仅保留最新的压缩承载内容，因此特别适合长任务场景。\n- **modelResponsesApiCompactThresholds：** 按模型覆盖 Responses API 的 `compact_threshold`，仅在代理自动附加 `context_management` 时使用。它的优先级高于 `resolveResponsesCompactThreshold` 基于 `max_prompt_tokens * ratio` 的兜底阈值。默认将 `gpt-5.4` 和 `gpt-5.5` 设为 `217600`（`272000 * 0.8`）。未列出的模型继续使用原有兜底逻辑。\n- **modelReasoningEfforts：** 按模型配置发送到 Copilot Responses API 的 `reasoning.effort`。可选值包括 `none`、`minimal`、`low`、`medium`、`high` 和 `xhigh`。若某模型未配置，则默认使用 `high`。\n- **useMessagesApi：** 当为 `true` 时，支持 Copilot 原生 `/v1/messages` 的 Claude 系模型会走 Messages API；否则回退到 `/chat/completions`。设为 `false` 可禁用 Messages API 路由，始终使用 `/chat/completions`。默认值为 `true`。\n- **useResponsesApiWebSocket：** 当为 `true` 时，Responses API 请求会优先对声明了 `ws:/responses` 的模型使用 Copilot websocket transport；仅声明 `/responses` 的模型仍走 HTTP。设为 `false` 可禁用 websocket 路由，并在模型支持 `/responses` 时使用 HTTP `/responses`。默认值为 `true`。\n- **useResponsesApiWebSearch：** 当为 `true` 时，服务端会保留 Responses API 中 `type: \"web_search\"` 的工具并透传到上游。设为 `false` 则会从 `/responses` payload 中移除这些工具。默认值为 `true`。\n- **messageApiWebSearchModel：** 顶层 Copilot `/v1/messages` 请求只包含服务端 `web_search` 工具时使用的全局模型，默认值为 `gpt-5-mini`。如果该值是 `provider/model` 别名，请求会进入对应 provider 的 Messages API 路径，并在转发前移除 provider 前缀。对于 Copilot GPT 模型，web search 会通过 `/responses` 执行。混合 `web_search` 与自定义工具的场景暂不支持，服务端会移除 server-side `web_search`。\n- **claudeTokenMultiplier：** 用于 Claude `/v1/messages/count_tokens` 请求在本地走 GPT tokenizer 估算时的乘数。默认值为 `1.15`。如果你的客户端仍然过晚触发上下文压缩，可以适当调大。这个配置只会在代理本地估算 Claude token 时生效；如果已经配置 `anthropicApiKey` 且 Anthropic token counting 调用成功，则会直接返回 Anthropic 的精确计数，不会使用这个乘数。\n- **anthropicApiKey：** 用于把 Claude `/v1/messages/count_tokens` 请求转发到 Anthropic 真实 token counting 端点的 API key，这样会返回精确计数，而不是 GPT tokenizer 估算值。也可通过环境变量 `ANTHROPIC_API_KEY` 设置。若未配置，或上游调用失败，则回退到由 `claudeTokenMultiplier` 控制的本地 GPT tokenizer 估算。\n\n编辑此文件后即可自定义 prompts，或替换为你自己的快速模型。修改完成后请重启服务（或重新执行命令），让缓存中的配置刷新生效。\n\n## API 认证\n\n- **受保护的普通路由：** 当配置了 `auth.apiKeys` 且非空时，除 `/`、`/usage-viewer` 和 `/usage-viewer/` 以外的普通路由都需要认证。\n- **Admin 路由：** 所有 `/admin/*` 路由都要求 `auth.adminApiKey`。如果缺失，服务会在启动时自动生成并在开始提供服务前写回 `config.json`。\n- **允许的认证头：**\n  - `x-api-key: <your_key>`\n  - `Authorization: Bearer <your_key>`\n- **CORS 预检：** `OPTIONS` 请求始终允许。\n- **未配置普通 key 时：** 普通路由仍可直接访问；但这条规则不适用于 `/admin/*`，后者只接受 `auth.adminApiKey`。\n\n普通受保护路由的示例请求：\n\n```sh\ncurl http://localhost:4141/v1/models \\\n  -H \"x-api-key: your_api_key\"\n```\n\nAdmin 路由的示例请求：\n\n```sh\ncurl http://localhost:4141/admin/config/model-mappings \\\n  -H \"x-api-key: your_admin_api_key\"\n```\n\n## API 端点\n\n服务端提供多个 OpenAI / Anthropic 兼容端点。请求会根据所选模型和 `provider/model` 别名路由到 GitHub Copilot、内置 `codex` provider 或已配置的 provider。\n\n### OpenAI 兼容端点\n\n这些端点模拟 OpenAI API 结构。\n\n| 端点 | 方法 | 说明 |\n| --- | --- | --- |\n| `POST /v1/responses` | `POST` | OpenAI 中用于生成模型响应的高级接口。支持 `openai-responses` provider 的 `provider/model` 别名。 |\n| `POST /v1/chat/completions` | `POST` | 为给定聊天对话创建模型响应。支持 `openai-compatible` provider 的 `provider/model` 别名；目标 provider 已配置时可在没有 Copilot 的情况下使用。 |\n| `GET /v1/models` | `GET` | 列出 Copilot 模型以及已启用 provider 的 `provider/model-id` 模型。 |\n| `POST /v1/embeddings` | `POST` | 创建表示输入文本的向量嵌入。 |\n\n### Anthropic 兼容端点\n\n这些端点设计为兼容 Anthropic Messages API。\n\n| 端点 | 方法 | 说明 |\n| --- | --- | --- |\n| `POST /v1/messages` | `POST` | 为给定对话创建模型响应。支持已配置 provider 的 `provider/model` 别名，包括通过 `openai-compatible` provider 做翻译。 |\n| `POST /v1/messages/count_tokens` | `POST` | 计算一组消息的 token 数。支持已配置 provider 的 `provider/model` 别名。 |\n| `POST /:provider/v1/messages` | `POST` | 将 Anthropic Messages 请求代理到已配置的 Anthropic provider，或翻译到 OpenAI 兼容 / OpenAI Responses provider。 |\n| `GET /:provider/v1/models` | `GET` | 将模型列表请求代理到已配置的 provider。 |\n| `POST /:provider/v1/messages/count_tokens` | `POST` | 为 provider 路由请求在本地计算 token 数。 |\n\n### 使用量监控端点\n\n用于监控 Copilot 用量与额度的新端点。\n\n| 端点 | 方法 | 说明 |\n| --- | --- | --- |\n| `GET /usage` | `GET` | 获取详细的 Copilot 使用统计与额度信息。 |\n| `GET /token` | `GET` | 获取当前 API 正在使用的 Copilot token。 |\n\n### Admin / 配置端点\n\n这些端点用于本地管理操作，只接受 `auth.adminApiKey`。\n\n| 端点 | 方法 | 说明 |\n| --- | --- | --- |\n| `GET /admin/config/model-mappings` | `GET` | 返回当前 `config.json` 路径以及生效中的 `modelMappings` 映射。 |\n| `POST /admin/config/model-mappings` | `POST` | 只更新 `config.json` 里的 `modelMappings` 字段，并回传更新后的结果。 |\n\n## 使用示例\n\n常用 `npx` 命令：\n\n```sh\n# 基础启动\nnpx @jeffreycao/copilot-api@latest start\n\n# 自定义端口并开启详细日志\nnpx @jeffreycao/copilot-api@latest start --port 8080 --verbose\n\n# 执行认证流程\nnpx @jeffreycao/copilot-api@latest auth login\n\n# 配置第三方 provider，然后不依赖 GitHub Copilot 启动\nnpx @jeffreycao/copilot-api@latest auth login --provider dashscope\nnpx @jeffreycao/copilot-api@latest start\n\n# 以 JSON 格式输出调试信息\nnpx @jeffreycao/copilot-api@latest debug --json\n\n# 用 Bun 而不是 Node.js 运行已发布 CLI\nbunx --bun @jeffreycao/copilot-api@latest start\n```\n\n配置 `dashscope` 后的 OpenAI 兼容 provider 调用示例：\n\n```sh\ncurl http://localhost:4141/v1/chat/completions \\\n  -H \"content-type: application/json\" \\\n  -d '{\"model\":\"dashscope/qwen3.6-plus\",\"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]}'\n\ncurl http://localhost:4141/dashscope/v1/messages \\\n  -H \"content-type: application/json\" \\\n  -d '{\"model\":\"qwen3.6-plus\",\"max_tokens\":1024,\"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]}'\n```\n\n## 使用建议\n\n<a id=\"claudemd-or-agentsmd-recommended-content\"></a>\n\n### CLAUDE.md 或 AGENTS.md 推荐内容\n\n如果你想手动加入这些提醒，请在 Claude Code 的 `CLAUDE.md`，或 opencode/codex 的 `AGENTS.md` 中加入以下内容：\n\n```\n- Prohibited from directly asking questions to users, MUST use question tool.\n- Once you can confirm that the task is complete, MUST use question tool to make user confirm. The user may respond with feedback if they are not satisfied with the result, which you can use to make improvements and try again, after try again, MUST use question tool to make user confirm again.\n```\n"}, "35c5c25cca29308a1d33a526c3a03e2c837f6834": {"t": 1785765581.4554236, "n": 30736, "h": "a5f4099a54d79fc0", "c": "# Copilot API Proxy\n\n[English](./README.md) | 简体中文\n\n## 重要说明\n\n> [!IMPORTANT]\n> **使用前请先注意以下几点：**\n>\n> 1. **Claude Code 配置：** 与 Claude Code 搭配使用时，请将模型 ID 配置为 `claude-opus-4-8`。示例 claude `settings.json` 见 [通过 `settings.json` 手动配置](#manual-configuration-with-settingsjson)。\n>\n> 2. **内置 `copilot`、`codex` 与第三方 provider：** 执行 `npx @jeffreycao/copilot-api@latest auth`，可选择 `copilot`、`codex`、`deepseek`、`custom` 等 provider。\n>\n> 3. **注意事项：** README 顶部移除的 GitHub Copilot warning 见 [GitHub Copilot 安全提示](./NOTICE.md#github-copilot-security-notice)。\n\n---\n\n## 项目概览\n\n这是一个小型 AI gateway，可以使用 GitHub Copilot、内置 `codex` provider，也可以使用 DashScope 等已配置的第三方 provider。GitHub Copilot 现在是可选能力：如果本地没有 GitHub token，只要至少配置了一个启用中的 provider，服务仍可按 provider-only 模式启动。\n\nAI gateway 会从同一个本地端点暴露 OpenAI / Anthropic 兼容 API，让 [Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview)、OpenCode、Codex 和 OpenAI 兼容客户端可以共用同一个本地服务。\n\n在 GitHub Copilot 路径上，AI gateway 会在可用时优先使用 Copilot 原生的 Anthropic 风格 Messages API，在重工具调用场景下保留更原生的 Claude 行为。\n\n## 功能特性\n\n- **OpenAI 与 Anthropic 双兼容**：通过 `/v1/responses`、`/v1/chat/completions`、`/v1/models`、`/v1/embeddings` 和 `/v1/messages` 对外暴露同一个本地 AI gateway。\n- **Copilot 可选**：有 GitHub 凭据时可以使用 GitHub Copilot，没有 GitHub 凭据时也可以只依赖已配置的 provider 运行。\n- **同一网关接入 Copilot、`codex` 与第三方 provider**：可统一路由 GitHub Copilot、内置 `codex` provider 和配置好的外部 provider。\n- **第三方 provider 可独立启动**：配置 DashScope、DeepSeek、OpenRouter 或自定义 provider 后，不需要 GitHub Copilot 登录即可启动 AI gateway。\n- **OpenAI 兼容 provider 同时支持 chat 和 Messages API**：`openai-compatible` provider 可通过顶层 `/v1/chat/completions` 搭配 `model: \"provider/model\"` 提供 Chat Completions，也可通过 `/v1/messages` 完成 Anthropic Messages 的请求/响应翻译。\n- **面向 Claude 的更原生 Copilot 路由**：优先使用原生 `/v1/messages`，保留 Claude 风格工具流，支持 Anthropic beta 能力、通过 Responses-capable 模型支持 Claude WebSearch，并保留 subagent / session 标记。\n- **Claude Code 与 OpenCode 集成**：兼容 Claude Code 与 OpenCode，也支持通过 `@ai-sdk/anthropic` 直接作为 Anthropic provider 使用。\n- **灵活的认证与部署选项**：支持交互式登录、直接 token、个人 / Business / Enterprise、GitHub Enterprise、opencode OAuth 和自定义数据目录。\n- **多 provider 路由**：可暴露 `/:provider/...` 路由，也可在顶层 API 上使用 `model: \"provider/model\"`。\n\n## 前置要求\n\n- Bun（>= 1.2.x）\n- 如果要通过 `npx` 运行已发布 CLI，需要 Node.js\n- 只有在使用 GitHub Copilot provider 时，才需要已订阅 Copilot 的 GitHub 账号\n- 如果不使用 GitHub Copilot，需要至少一个已配置 provider 的 API key 或 OAuth 登录\n\n## 安装\n\n安装依赖：\n\n```sh\nbun install\n```\n\n直接从源码启动服务：\n\n```sh\nbun run start start\n```\n\n## 从源码运行\n\n本项目可以通过多种方式从源码运行：\n\n### 开发模式\n\n```sh\nbun run dev start\n```\n\n### 生产模式\n\n```sh\nbun run start start\n```\n\n## 通过 npx 使用\n\n你可以直接用 npx 运行本项目：\n\n> [!IMPORTANT]\n> 通过 `npx` 运行时，token usage 存储会使用 Node 内置的 `node:sqlite` 模块。该能力会在 Node.js >= 22.13.0 时启用；Node.js < 22.13.0 时 CLI 仍可启动，但会禁用 token usage 存储。\n>\n> 如果不升级 Node.js 但仍需要 token usage 存储，可以改用 Bun 运行已发布 CLI：`bunx --bun @jeffreycao/copilot-api@latest start`。\n\n```sh\nnpx @jeffreycao/copilot-api@latest start\n```\n\n带参数示例：\n\n```sh\nnpx @jeffreycao/copilot-api@latest start --port 8080\n```\n\n如果只想做认证或 provider 配置：\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth\n```\n\n如果要不依赖 GitHub Copilot 运行，先配置至少一个 provider，然后正常启动服务：\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth login --provider dashscope\nnpx @jeffreycao/copilot-api@latest start\n```\n\n## 配合 Docker 使用\n\n构建镜像：\n\n```sh\ndocker build -t copilot-api .\n```\n\n通过 bind mount 运行容器，让认证数据在重启后保留：\n\n```sh\nmkdir -p ./copilot-data\ndocker run -p 4141:4141 -v $(pwd)/copilot-data:/root/.local/share/copilot-api copilot-api\n```\n\n这会把宿主机上的 `./copilot-data` 映射到容器内的 `/root/.local/share/copilot-api`，用于持久化 GitHub 认证数据、provider 配置和其他 gateway 状态。\n\n也可以直接通过环境变量传入 GitHub token：\n\n```sh\ndocker run -p 4141:4141 -e GH_TOKEN=your_github_token_here copilot-api\n```\n\n## Electron 桌面应用\n\n如果你更喜欢图形界面，仓库里还提供了位于 `desktop/` 的 Electron 桌面应用。它支持 GitHub Copilot 登录、OpenAI Codex OAuth，以及 DeepSeek、DashScope、OpenRouter 或自定义 provider 的 API Key 配置。授权或配置 provider 后，可以一键启动或停止本地代理，并在界面里直接查看本地端点、鉴权 Header、可用模型、额度和日志。\n\n设置页还可以配置 `OAuth App`、`API Home`、`Enterprise URL`、详细日志以及最小化到托盘。桌面安装包发布在 GitHub Releases：\n\nhttps://github.com/caozhiyuan/copilot-api/releases\n\n下载对应平台的安装包后，在应用内授权或配置 provider，选择端口并启动服务，再把你的客户端指向应用里显示的本地端点即可。发布版桌面应用使用随包内置的 Electron 运行时，正常使用不需要额外安装 Node.js；token usage 历史记录会在该内置运行时支持 SQLite 时启用。\n\n桌面应用里的高级配置页会通过 `GET/POST /admin/config/model-mappings` 读写这份共享的模型映射。同一份映射会统一作用于 `POST /v1/messages`、`POST /v1/messages/count_tokens`、`POST /v1/responses` 和 `POST /v1/chat/completions`，不再按接口区分。它使用的是 `auth.adminApiKey`，不是普通的 `auth.apiKeys`；应用会在服务启动并自动生成该 key 后，直接从 `config.json` 读取它来发起请求。\n\n### 桌面应用截图\n\n下面展示了桌面应用中的首页、Token 用量统计页面：\n\n<p align=\"center\">\n  <img src=\"./docs/screenshots/desktop-dashboard.png\" alt=\"Copilot API 桌面应用首页\" width=\"49%\" />\n  <img src=\"./docs/screenshots/desktop-token-usage.png\" alt=\"Copilot API 桌面应用 Token 用量页\" width=\"49%\" />\n</p>\n\n## 与 Claude Code 一起使用\n\n这个 AI gateway 可以为 [Claude Code](https://docs.anthropic.com/en/claude-code) 提供后端能力。Claude Code 是 Anthropic 提供的实验性面向开发者的对话式 AI 助手。\n\n有两种方式可以把 Claude Code 配置为使用这个 AI gateway：\n\n### 通过 `--claude-code` 标志进行交互式配置\n\n执行带 `--claude-code` 的 `start` 命令开始：\n\n```sh\nnpx @jeffreycao/copilot-api@latest start --claude-code\n```\n\n你会被提示选择一个主模型，以及一个用于后台任务的 \"small, fast\" 模型。选择完成后，会有一条命令被复制到剪贴板中。该命令会设置 Claude Code 使用这个 AI gateway 所需的环境变量。\n\n在新的终端中粘贴并执行这条命令，即可启动 Claude Code。\n\n<a id=\"manual-configuration-with-settingsjson\"></a>\n\n### 通过 `settings.json` 手动配置\n\n另一种方式是在项目根目录中创建 `.claude/settings.json` 文件，并写入 Claude Code 所需的环境变量。这样你就不需要每次都运行交互式配置了。\n\n下面是一个 `.claude/settings.json` 示例：\n\n```json\n{\n  \"env\": {\n    \"ANTHROPIC_BASE_URL\": \"http://localhost:4141\",\n    \"ANTHROPIC_AUTH_TOKEN\": \"dummy\",\n    \"ANTHROPIC_MODEL\": \"deepseek/deepseek-v4-pro\",\n    \"ANTHROPIC_DEFAULT_SONNET_MODEL\": \"deepseek/deepseek-v4-pro\",\n    \"ANTHROPIC_DEFAULT_HAIKU_MODEL\": \"deepseek/deepseek-v4-flash\",\n    \"DISABLE_NON_ESSENTIAL_MODEL_CALLS\": \"1\",\n    \"CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC\": \"1\",\n    \"CLAUDE_CODE_ATTRIBUTION_HEADER\": \"0\",\n    \"CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION\": \"false\",\n    \"CLAUDE_CODE_DISABLE_TERMINAL_TITLE\": \"true\",\n    \"CLAUDE_CODE_ENABLE_AWAY_SUMMARY\": \"0\"\n  },\n  \"permissions\": {\n    \"deny\": [\n      \"mcp__ide__executeCode\"\n    ]\n  }\n}\n```\n\n- 请根据需要替换 `ANTHROPIC_MODEL`、`ANTHROPIC_DEFAULT_OPUS_MODEL`、`ANTHROPIC_DEFAULT_SONNET_MODEL` 和 `ANTHROPIC_DEFAULT_HAIKU_MODEL`。配置完成后，请安装 claude code 插件，见 [插件集成](#plugin-integrations)。\n- 将 `CLAUDE_CODE_ATTRIBUTION_HEADER` 设为 `0` 可以阻止 Claude Code 在 system prompt 中附加计费和版本信息，从而避免 prompt cache 失效。\n- 关闭 `CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION` 和 `CLAUDE_CODE_ENABLE_AWAY_SUMMARY` 可以避免不必要地消耗额度。\n- Claude Code WebSearch 已支持纯搜索请求。Copilot 路径请保持全局 `messageApiWebSearchModel` 指向 Responses-capable GPT 模型或 `provider/model` 别名；provider 路由请使用原生 Anthropic provider 或 `openai-responses` provider。只有在你明确想禁止这类流量时，才需要把 `WebSearch` 加到 `permissions.deny`。\n- 如果使用的不是 Claude 模型，请不要启用 `ENABLE_TOOL_SEARCH`。如果使用的是 Claude 模型，则可以启用 `ENABLE_TOOL_SEARCH`。当前 Claude Code 使用的是客户端 tool search 模式，在该模式下每次加载 defer tools 都需要额外请求一次。\n- `CLAUDE_CODE_AUTO_COMPACT_WINDOW`：设置用于自动压缩计算的上下文容量（以 token 为单位）。默认使用模型自身的上下文窗口：标准模型为 200K，扩展上下文模型为 1M。使用 1M 上下文模型（如 `claude-opus-4-6[1m]`）时，可设置一个较低的值（如 `500000`）将窗口视为 500K 用于压缩计算。该值受限于模型的实际上下文窗口上限。`CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` 会基于此值的百分比生效。设置此变量可将压缩阈值与状态栏的 `used_percentage` 解耦（后者始终使用模型的完整上下文窗口）。\n\n更多选项见：[Claude Code settings](https://docs.anthropic.com/en/docs/claude-code/settings#environment-variables)\n\n也可以参考 IDE 集成说明：[Add Claude Code to your IDE](https://docs.anthropic.com/en/docs/claude-code/ide-integrations)\n\n## 与 OpenCode 一起使用\n\nOpenCode 已经有直接的 GitHub Copilot provider。本节适用于你希望让 OpenCode 通过 `@ai-sdk/anthropic` 指向这个 AI gateway，并复用本 README 前面提到的 agent 行为时。\n\n### 最小配置\n\n使用 OpenCode OAuth app 启动 AI gateway：\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth --oauth-app=opencode\nnpx @jeffreycao/copilot-api@latest start\n```\n\n然后让 OpenCode 通过 `@ai-sdk/anthropic` 指向这个 AI gateway。\n\n示例 `~/.config/opencode/opencode.json`：\n\n```json\n{\n  \"$schema\": \"https://opencode.ai/config.json\",\n  \"provider\": {\n    \"local\": {\n      \"npm\": \"@ai-sdk/anthropic\",\n      \"name\": \"My Local\",\n      \"options\": {\n        \"baseURL\": \"http://localhost:4141/v1\",\n        \"apiKey\": \"dummy\"\n      },\n      \"models\": {\n        \"gpt-5.4\": {\n          \"name\": \"gpt-5.4\",\n          \"modalities\": {\n            \"input\": [\"text\", \"image\"],\n            \"output\": [\"text\"]\n          },\n          \"limit\": {\n            \"context\": 300000,\n            \"output\": 128000\n          }\n        },\n        \"claude-sonnet-4.6\": {\n          \"id\": \"claude-sonnet-4.6\",\n          \"name\": \"claude-sonnet-4.6\",\n          \"modalities\": {\n            \"input\": [\"text\", \"image\"],\n            \"output\": [\"text\"]\n          },\n          \"limit\": {\n            \"context\": 200000,\n            \"output\": 32000\n          },\n          \"options\": {\n            \"thinking\": {\n              \"type\": \"adaptive\"\n            },\n            \"effort\": \"max\"\n          }\n        }\n      }\n    }\n  }\n}\n```\n\n这些字段的重要性：\n\n- `npm: \"@ai-sdk/anthropic\"` 是关键。OpenCode 会以 Anthropic Messages 语义与这个 AI gateway 通信，而不是把一切扁平化为 OpenAI Chat Completions。\n- `options.baseURL` 应设为 `http://localhost:4141/v1`；Anthropic SDK 会自动补上 `/messages`、`/models` 和 `/messages/count_tokens`。\n- 如果你在此代理中启用了 `auth.apiKeys`，请把 `dummy` 替换为真实 key；否则任意占位值都可以。\n\n## 与 Codex 一起使用\n\n这个 AI gateway 也可以为 Codex 提供后端能力。\n\n### Codex `config.toml` 参考配置\n\n把以下 `[model_providers.copilot_api]` 段加入你的 Codex `~/.codex/config.toml`：\n\n```toml\nmodel_provider = \"copilot_api\"\nmodel_reasoning_summary = \"auto\"\nmodel_verbosity = \"medium\"\nmodel_context_window = 272000\nmodel_auto_compact_token_limit = 244800\n\n[model_providers.copilot_api]\nname = \"OpenAI\"\nbase_url = \"http://localhost:4141\"\nenv_key = \"GITHUB_COPILOT_API_KEY\"\nrequires_openai_auth = true\nsupports_websockets = false\nwire_api = \"responses\"\nrequest_max_retries = 3\nstream_max_retries = 1\nstream_idle_timeout_ms = 300000\n\n[features]\nremote_compaction_v2 = true\n\n[analytics]\nenabled = false\n```\n\n> [!NOTE]\n> 此配置仅限于 Codex 与 GitHub Copilot provider。`name` 一定要配置为 `\"OpenAI\"`。它可以缓解 Codex local compact 不命中缓存的问题。如果你已开启 `useResponsesApiContextManagement`（Responses API context management 压缩），通常不会走到 `remote_compaction_v2` 或者 local compact，但如果工具返回 tokens 过大，仍有可能触发。\n\n## GPT Tool Search\n\n对于 `gpt-5.4+` 这类 GPT Responses 模型，这个 AI gateway 可以通过一个很小的 MCP bridge 暴露 Responses `tool_search`。Claude Code 和 opencode 都可以使用同一个 bridge，前提是客户端会加载 MCP server，并且 Anthropic Messages 流量会经过这个 AI gateway。\n\nGPT 模型不要设置 Claude Code 原生的 `ENABLE_TOOL_SEARCH`。这个开关启用的是 Claude Code 自己的客户端 tool search 模式，可能导致 deferred 工具定义不再转发给 AI gateway。这个 AI gateway 需要完整的工具定义，这样才能只保留那一小组常驻加载工具，其余工具统一转换为 Responses deferred namespace。\n\n如果你安装了 `tool-search@copilot-api-marketplace`，Claude Code 会自动带上这个 MCP bridge，可以跳过下面这段 Claude Code MCP 手动配置。\n\n请把 tool search bridge 加到 Claude Code 使用的 MCP 配置中：\n\n```json\n{\n  \"mcpServers\": {\n    \"tool_search\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@jeffreycao/copilot-api@latest\", \"mcp\"]\n    }\n  }\n}\n```\n\n请把 tool search bridge 加到 opencode 使用的 MCP 配置中：\n\n```json\n{\n  \"mcp\": {\n    \"tool_search\": {\n      \"type\": \"local\",\n      \"command\": [\"npx\", \"-y\", \"@jeffreycao/copilot-api@latest\", \"mcp\"]\n    }\n  }\n}\n```\n\n本地开发时可以将命令换成 `bun`，参数换成 `[\"run\", \"./src/main.ts\", \"mcp\"]`。\n\nAI gateway 内部现在会把 OpenAI Responses `tool_search` 配置成 client-executed 模式。deferred tools 仍然会作为可搜索 namespace 暴露给模型，但会明确要求模型直接返回下一步要加载的精确工具名列表。\n\n该 bridge 使用直接工具选择，不做 query 搜索。工具入参是 `names`，值为逗号分隔的精确 deferred 工具名，例如 `TaskList,TaskGet,mcp__fetch__fetch`。\n\n<a id=\"plugin-integrations\"></a>\n\n## 插件集成\n\n本项目为 Claude Code 和 opencode 提供了插件集成。\n\n#### Claude Code 插件集成（基于 marketplace）\n\nClaude Code 集成现在拆分为两个插件：\n\n- `agent-inject` 会在 `SubagentStart` 时注入 `__SUBAGENT_MARKER__...`，以便 AI gateway 推导 `x-initiator: agent`。\n- `tool-search` 会注册用于 GPT Responses deferred tool loading 的 `tool_search` MCP bridge。\n\n- 本仓库中的 marketplace catalog：`.claude-plugin/marketplace.json`\n- 本仓库中的插件源码：`plugin/claude/agent-inject`、`plugin/claude/tool-search`\n\n远程添加 marketplace：\n\n```sh\n/plugin marketplace add https://github.com/caozhiyuan/copilot-api.git\n```\n\n从 marketplace 安装插件：\n\n```sh\n/plugin install agent-inject@copilot-api-marketplace\n/plugin install tool-search@copilot-api-marketplace\n```\n\n安装后，`agent-inject` 会在 `SubagentStart` 时注入 `__SUBAGENT_MARKER__...`，AI gateway 会利用它推导 `x-initiator: agent`。\n\n`agent-inject` 还会注册一个 `UserPromptSubmit` hook，并返回 `{\"continue\": true}`；同时它也可以通过环境变量注入 `SessionStart` reminder 规则：\n\n- `CLAUDE_PLUGIN_ENABLE_QUESTION_RULES=1` 会自动为 Claude Code 启用两条关于使用 `question` 工具的提醒。你也可以把同样的提醒手动写进 `CLAUDE.md`；见 [CLAUDE.md 或 AGENTS.md 推荐内容](#claudemd-or-agentsmd-recommended-content)。\n- `CLAUDE_PLUGIN_ENABLE_NO_BACKGROUND_AGENTS_RULE=1` 会启用关于避免在 agent hooks 中使用 `run_in_background: true` 的提醒。\n\n`tool-search` 插件内置了 [GPT Tool Search](#gpt-tool-search) 一节描述的同一个 MCP bridge，因此安装该插件后，Claude Code 用户无需再手动配置 `tool_search` server。\n\n#### Opencode 插件\n\nsubagent 标记生成器被打包为一个 opencode 插件，位于 `plugin/opencode/subagent-marker.js`。\n\n**安装方式：**\n\n将插件文件复制到你的 opencode 插件目录：\n\n```sh\n# 克隆或下载本仓库后复制该插件\ncp plugin/opencode/subagent-marker.js ~/.config/opencode/plugins/\n```\n\n或者手动在 `~/.config/opencode/plugins/subagent-marker.js` 创建该文件，并填入插件内容。\n\n**功能：**\n\n- 跟踪 subagent 创建的子会话\n- 自动在 subagent 聊天消息前添加 marker system reminder（`__SUBAGENT_MARKER__...`）\n- 设置 `x-session-id` 请求头以跟踪会话\n- 让这个 AI gateway 能够把来自 subagent 的请求识别为 `x-initiator: agent`\n\n该插件会挂接到 `session.created`、`session.deleted`、`chat.message` 和 `chat.headers` 事件上，以无缝提供 subagent marker 能力。\n\n## 使用量查看器\n\n服务启动后，控制台会输出一个 Copilot 使用量看板 URL。这个看板是一个用于监控 API 用量的 Web 界面。\n\n1. 启动服务。例如使用 npx：\n   ```sh\n   npx @jeffreycao/copilot-api@latest start\n   ```\n2. 服务会输出一个 usage viewer 的 URL。将它复制到浏览器中打开，形式大致如下：\n   `http://localhost:4141/usage-viewer?endpoint=http://localhost:4141/usage`\n   - 如果你在 Windows 上使用 `start.bat` 脚本，这个页面会自动打开。\n\n看板提供了更易读的 Copilot 用量视图：\n\n> token usage 历史记录需要 Bun 或 Node.js >= 22.13.0。Node.js < 22.13.0 时服务会正常运行，但 token usage 存储会被禁用。\n\n- **API Endpoint URL**：通过 URL 查询参数指定 API endpoints，默认指向本地服务。支持手动切换为其他兼容 endpoints。\n- **x-api-key 认证**：如果启用了 API Key 认证，可填入 `x-api-key` 请求头。密钥会持久化保存在浏览器本地存储中。\n- **Period 选择器**：支持 Day / Week / Month 三种时间范围，切换时 URL 参数会自动同步，方便收藏和分享。\n- **Fetch Data**：点击 \"Refresh\" 按钮加载或刷新使用数据。页面加载时也会自动拉取数据。\n- **Copilot Quotas 额度**：通过进度条展示 Chat、Completions 等不同服务的额度使用情况，悬停可查看已用/剩余详情。\n- **Token Usage 指标卡片**：汇总当前周期的 Total、Input、Output、Cache Read、Cache Write、Requests 和预估费用。\n- **趋势图（Week / Month）**：提供按模型和指标筛选的折线趋势图，点击数据点可查看单日用量明细。\n- **Model Breakdown 表格**：按模型维度列出周期内的请求数、输入/输出/缓存 token 和预计费用。\n- **Request Events 分页列表**：按时间排序的请求事件记录，支持分页浏览，含时间戳、模型、请求 ID 和 token 用量。\n- **Detailed Information**：展示 API 返回的完整 JSON 响应，便于深入分析所有可用统计数据。\n- **URL-based Configuration**：也可通过 `endpoint` 和 `period` 查询参数直接指定 API 端点与时间范围。例如：\n  `http://localhost:4141/usage-viewer?endpoint=http://your-api-server/usage&period=week`\n\n### Usage Viewer 截图\n\n<p align=\"center\">\n  <img src=\"./docs/screenshots/usage-viewer.png\" alt=\"Copilot API Usage Viewer 页面\" width=\"900\" />\n</p>\n\n## 命令结构\n\nCopilot API 现在使用子命令结构，主要命令包括：\n\n- `start`：启动 AI gateway 服务。如果已有 GitHub token，则启用 Copilot 路径；如果没有 GitHub token，但存在至少一个启用中的 provider，则按 provider-only 模式启动；如果两者都没有，会引导你配置 provider。\n- `auth`：仅执行 provider 登录或配置流程，不启动服务。可用于 GitHub Copilot 登录、Codex OAuth，或第三方 provider API key 配置。\n- `debug`：显示诊断信息，包括版本、运行时详情、文件路径以及认证状态，便于排障与支持。\n\n## 命令行选项\n\n### 全局选项\n\n以下选项可用于任意子命令。若在子命令之前传入，请使用 `--key=value` 形式：\n\n| 选项 | 说明 | 默认值 | 别名 |\n| --- | --- | --- | --- |\n| --api-home | API home 目录路径（设置 `COPILOT_API_HOME`） | 无 | 无 |\n| --oauth-app | OAuth app 标识符（设置 `COPILOT_API_OAUTH_APP`） | 无 | 无 |\n| --enterprise-url | GitHub Enterprise URL（设置 `COPILOT_API_ENTERPRISE_URL`） | 无 | 无 |\n\n### Start 命令选项\n\n以下是 `start` 命令可用的命令行选项：\n\n| 选项 | 说明 | 默认值 | 别名 |\n| --- | --- | --- | --- |\n| --port | 监听端口 | 4141 | -p |\n| --verbose | 启用详细日志 | false | -v |\n| --github-token | 直接提供 GitHub token（必须通过 `auth` 子命令生成） | 无 | -g |\n| --claude-code | 生成一个使用 Copilot API 配置启动 Claude Code 的命令 | false | -c |\n| --show-token | 在获取和刷新时显示 GitHub 与 Copilot token | false | 无 |\n| --proxy-env | 从环境变量初始化代理 | false | 无 |\n\n### Auth 命令选项\n\n| 选项 | 说明 | 默认值 | 别名 |\n| --- | --- | --- | --- |\n| --provider | 要登录或配置的 provider（`copilot`、`codex`、`opencode-go`、`deepseek`、`dashscope`、`openrouter` 或 `custom`） | 交互选择 | 无 |\n| --verbose | 启用详细日志 | false | -v |\n| --show-token | 认证时显示 GitHub token | false | 无 |\n\n只有在需要启用 GitHub Copilot provider 时，才需要执行 `copilot-api auth login --provider copilot`。使用 `codex` 或第三方 provider-only 模式不要求配置 Copilot。\n\n使用 `copilot-api auth login --provider deepseek`、`--provider dashscope`、`--provider openrouter` 或 `--provider opencode-go` 可以通过 CLI 快速新增或更新这些常用第三方 provider。DeepSeek 会提示输入掩码显示的 `apiKey`、provider `type`（默认 `anthropic`），以及默认 `https://api.deepseek.com/anthropic` 的 `baseUrl`。DashScope 会提示输入掩码显示的 `apiKey`、provider `type`（默认 `openai-compatible`）和预填默认值的 `baseUrl`。OpenRouter 只提示输入掩码显示的 `apiKey` 和预填默认值的 `baseUrl`，并固定写入 `type: \"anthropic\"`。OpenCode Go 只提示输入掩码显示的 `apiKey` 和预填默认值的 `baseUrl`，并固定写入 `type: \"openai-compatible\"`（baseUrl `https://opencode.ai/zen/go`）。配置并启用 provider 后，`copilot-api start` 可在没有 GitHub token 的情况下启动。\n\n使用 `copilot-api auth login --provider custom` 可以通过 CLI 新增或更新其他第三方 provider。命令会依次提示输入 provider name、项目支持的 type（`anthropic`、`openai-compatible` 或 `openai-responses`）、`baseUrl`、掩码显示的 `apiKey` 和 `authType`；`authType` 可保持 type 默认值，也可选择 `x-api-key` / `authorization`。\n\n### Debug 命令选项\n\n| 选项 | 说明 | 默认值 | 别名 |\n| --- | --- | --- | --- |\n| --json | 以 JSON 输出调试信息 | false | 无 |\n\n<a id=\"configuration-configjson\"></a>\n\n## 配置（config.json）\n\n- **位置：** Linux/macOS 为 `~/.local/share/copilot-api/config.json`，Windows 为 `%USERPROFILE%\\.local\\share\\copilot-api\\config.json`。\n- **默认结构：**\n  ```json\n  {\n    \"auth\": {\n      \"apiKeys\": [],\n      \"adminApiKey\": \"<startup 自动生成>\"\n    },\n    \"providers\": {},\n    \"modelMappings\": {},\n    \"extraPrompts\": {\n      \"gpt-5-mini\": \"<built-in exploration prompt>\",\n      \"gpt-5.3-codex\": \"<built-in commentary prompt>\",\n      \"gpt-5.4-mini\": \"<built-in commentary prompt>\",\n      \"gpt-5.4\": \"<built-in commentary prompt>\",\n      \"gpt-5.5\": \"<built-in commentary prompt>\"\n    },\n    \"smallModel\": \"gpt-5-mini\",\n    \"useResponsesApiContextManagement\": true,\n    \"modelResponsesApiCompactThresholds\": {\n      \"gpt-5.4\": 217600,\n      \"gpt-5.5\": 217600\n    },\n    \"modelReasoningEfforts\": {\n      \"gpt-5-mini\": \"low\",\n      \"gpt-5.3-codex\": \"xhigh\",\n      \"gpt-5.4-mini\": \"xhigh\",\n      \"gpt-5.4\": \"xhigh\",\n      \"gpt-5.5\": \"xhigh\"\n    },\n    \"useMessagesApi\": true,\n    \"useResponsesApiWebSocket\": true,\n    \"useResponsesApiWebSearch\": true,\n    \"messageApiWebSearchModel\": \"gpt-5-mini\"\n  }\n  ```\n- **auth.apiKeys：** 用于普通非 admin 路由的 API key。支持多个 key 轮换使用。请求可通过 `x-api-key: <key>` 或 `Authorization: Bearer <key>` 进行认证。若为空或省略，则普通路由的认证会被禁用。\n- **auth.adminApiKey：** 仅用于 `/admin/*` 路由的单个 admin key。若未配置，服务会在启动时自动生成一个随机 key，并回写到 `config.json`。它同样使用 `x-api-key` 或 `Authorization: Bearer` 这两种头，但普通 `auth.apiKeys` 不能访问 `/admin/*`。\n- **modelMappings：** 用于顶层 `POST /v1/messages`、`POST /v1/messages/count_tokens`、`POST /v1/responses` 和 `POST /v1/chat/completions` 请求的精确 `sourceModel -> targetModel` 重写映射，这几类接口共用同一份规则。省略该字段或保留为 `{}` 时，不会做模型重写。`source` 和 `target` 都必须是非空字符串。`target` 可以是普通模型 ID，也可以是 `provider/model` 形式的别名，例如 `dashscope/qwen3.6-plus`；重写发生在 provider alias 解析之前。这些映射不再按接口区分。`GET/POST /admin/config/model-mappings` 管理接口读写的也只有这个字段。\n- **extraPrompts：** `model -> prompt` 的映射。把 Anthropic 风格请求翻译给 Copilot 时，会将其附加到第一条 system prompt 后面。你可以借此为不同模型注入护栏或指引。缺失的默认项会自动补齐，但不会覆盖你自定义的 prompt。内置的 `gpt-5.3-codex` 和 `gpt-5.4` prompt 会启用带阶段感知的 commentary，让模型在工具调用或更深层推理前先发出简短的用户可见进度说明。\n- **providers：** 全局上游 provider 映射。每个 provider key（例如 `dashscope`）都会变成一个路由前缀（`/dashscope/v1/messages`）。支持 `type: \"anthropic\"`、`type: \"openai-compatible\"` 和 `type: \"openai-responses\"`。顶层客户端也可以在 `/v1/messages`、`/v1/messages/count_tokens`、`/v1/responses` 和 `/v1/chat/completions` 中使用 `model: \"dashscope/model-id\"`；AI gateway 会在转发上游前移除 `dashscope/` 前缀。`openai-compatible` provider 同时支持 chat 和 Messages 流程：`/v1/chat/completions` 会直连上游 `/v1/chat/completions`，而 `/v1/messages` 和 `/:provider/v1/messages` 会先翻译为上游 Chat Completions，再把响应翻译回 Anthropic Messages。`GET /v1/models` 会聚合已启用 provider 的模型，并以 `provider/model-id` 形式返回；单个 provider 的原始模型列表仍可使用 `GET /dashscope/v1/models`。\n  - `enabled`：可选，若省略则默认为 `true`。\n  - `baseUrl`：provider API 的基础 URL，不要带结尾的 endpoint。Anthropic provider 不要带 `/v1/messages`；OpenAI 兼容 provider 不要带 `/v1/chat/completions`；OpenAI Responses provider 不要带 `/v1/responses`。\n  - `apiKey`：作为上游凭据值使用；普通 provider 必须配置。\n  - `authType`：可选，控制 `apiKey` 如何发送到上游。普通 provider 支持 `x-api-key` 和 `authorization`。Anthropic provider 默认 `x-api-key`；OpenAI 兼容和 OpenAI Responses provider 默认 `authorization`。当设置为 `authorization` 时，代理会发送 `Authorization: Bearer <apiKey>`。`oauth2` 仅保留给内置 `codex` provider，并由 `auth login --provider codex` 自动写入。\n  - `pricingCurrency`：可选，provider 维度的 token 费用币种，例如 `USD` 或 `CNY`。快捷 provider 默认 DashScope、DeepSeek 为 `CNY`，Codex/OpenRouter 为 `USD`。费用按币种分别汇总，不做汇率换算。\n  - `models`：可选，按模型 ID 配置的映射。每个键为请求中的模型名，值支持：\n    - `temperature`：可选，当请求未指定时使用的默认温度。\n    - `topP`：可选，当请求未指定时使用的默认 `top_p`。\n    - `topK`：可选，当请求未指定时使用的默认 `top_k`。\n    - `extraBody`：可选，按模型合入上游请求体的动态字段；请求体显式同名字段优先。OpenAI 兼容 provider 可用它配置 `enable_thinking`、`preserve_thinking`、`reasoning_effort` 等字段。`thinking_budget` 是 OpenAI 兼容 provider 的特殊覆盖项：配置在 `extraBody` 后，会在 Anthropic `thinking.budget_tokens` 翻译之后强制写入，并覆盖请求派生出的预算值。对于 provider name 为 `dashscope` 或 `baseUrl` 包含 `aliyuncs.com` 的 provider，请求派生的 `thinking_budget`（来自 Anthropic `thinking.budget_tokens`）会转发给上游；其他 OpenAI 兼容 provider 会移除请求派生的 `thinking_budget`，但 `extraBody` 中的 `thinking_budget` 仍然生效。\n    - `pricing`：可选，按模型配置 token 单价，币种使用 provider 的 `pricingCurrency`，单位为每 100 万 tokens。支持 `input`、`output`、`cachedInput`（隐式缓存读）、`explicitCachedInput`（显式缓存读）和 `cacheCreationInput`。如需按输入 token 总量分档，可用带 `maxInputTokens` 的 `tiers`。\n    - `contextCache`：可选，provider name 为 `dashscope` 或 `baseUrl` 包含 `aliyuncs.com` 时默认 `true`，其他 OpenAI 兼容 provider 默认 `false`。用于启用阿里云百炼/DashScope 的显式缓存（explicit context cache），会按其 Context Cache 格式在最多 4 个 content block 上注入 `cache_control: { \"type\": \"ephemeral\" }`。缓存断点策略与 opencode 主链路保持一致：前 2 条 system 消息 + 最后 2 条非 system 消息。标记字符串 content 时会把 `system` / `user` / `assistant` / `tool` 消息转换为 text content part 数组；已有数组 content 则标记最后一个 part。如果模型本身已经支持隐式缓存，或上游不支持该显式缓存扩展字段，可在模型配置中设为 `false`。支持相同显式缓存扩展的非 DashScope provider 可设为 `true`。\n    - `supportPdf`：可选，控制该模型是否支持 PDF/document content。默认 `false`，不支持时会把 PDF 转成提示文本；设为 `true` 时会把 PDF/document 转成 OpenAI Chat Completions 的 file part。\n    - `toolContentSupportType`：可选，配置该模型的 tool result content 支持能力，值为 `array`、`image`、`pdf` 的数组。provider 侧未配置时默认只发送 string tool content。若 `supportPdf` 为 `true` 但这里不包含 `pdf`，tool result 里的 file part 会被转成 user role 消息。Copilot 主链路不使用这个 provider 默认，仍按 array + image 且不支持 PDF 的能力处理。\n    - `type`：可选，按模型覆盖 provider 的协议类型。支持 `anthropic`、`openai-compatible` 和 `openai-responses`。设置后，provider 的 `/v1/messages` 路由会使用该模型的 type 替代 provider 级别的 type 进行请求路由、认证头解析和上游端点选择。适用于 OpenCode Go 等上游对不同模型同时支持 OpenAI 兼容和 Anthropic Messages API 的 provider。覆盖 type 时，认证头按覆盖后 type 的默认值解析（Anthropic 默认 `x-api-key`；OpenAI 兼容/Responses 默认 `authorization`）。\n\n  DashScope 模型配置示例：\n  ```json\n  {\n    \"providers\": {\n      \"dashscope\": {\n        \"type\": \"openai-compatible\",\n        \"enabled\": true,\n        \"baseUrl\": \"https://dashscope.aliyuncs.com/compatible-mode\",\n        \"apiKey\": \"sk-your-dashscope-key\",\n        \"pricingCurrency\": \"CNY\",\n        \"models\": {\n          \"qwen3.7-plus\": {\n            \"temperature\": 1,\n            \"topP\": 0.95,\n            \"topK\": 20,\n            \"extraBody\": {\n              \"preserve_thinking\": true\n            }\n          },\n          \"glm-5.1\": {\n            \"temperature\": 0.7,\n            \"topP\": 0.95,\n            \"contextCache\": true,\n            \"pricing\": {\n              \"tiers\": [\n                {\n                  \"maxInputTokens\": 32000,\n                  \"input\": 6,\n                  \"cachedInput\": 1.2,\n                  \"explicitCachedInput\": 0.6,\n                  \"cacheCreationInput\": 7.5,\n                  \"output\": 24\n                },\n                {\n                  \"maxInputTokens\": 200000,\n                  \"input\": 8,\n                  \"cachedInput\": 1.6,\n                  \"explicitCachedInput\": 0.8,\n                  \"cacheCreationInput\": 10,\n                  \"output\": 28\n                }\n              ]\n            },\n            \"extraBody\": {\n              \"preserve_thinking\": true\n            }\n          }\n        }\n      }\n    }\n  }\n  ```\n  内置 token 价格覆盖 Codex GPT 模型（USD）、DashScope `qwen3.7-max`、`qwen3.7-plus`、`glm-5.1`、`glm-5.2`（CNY），DeepSeek `deepseek-v4-flash`、`deepseek-v4-pro`、`deepseek-chat`、`deepseek-reasoner`（CNY），以及 OpenCode Go 模型（`glm-5.2`、`deepseek-v4-flash`、`deepseek-v4-pro`、`kimi-k2.7-code`、`mimo-v2.5`、`mimo-v2.5-pro`、`qwen3.7-plus`、`qwen3.7-max`、`minimax-m2.5`、`minimax-m3`，USD）。用户配置的 `pricing` 优先于内置价格。DashScope 若上游 usage 中出现 `cache_creation_input_tokens` 字段，cached tokens 按显式缓存读价计费；否则 `cachedInput` 作为隐式缓存读价。DeepSeek 的 `prompt_cache_hit_tokens` 会归入 cached input，`prompt_cache_miss_tokens` 会归入普通 input。\n- **smallModel：** 无工具预热消息的回退模型（例如 Claude Code 的探测请求）；默认是 `gpt-5-mini`。\n- **useResponsesApiContextManagement：** 当为 `true` 时，代理会为 Responses API 附加 `context_management` 压缩指令。默认值为 `true`。如需全局关闭，可设为 `false`。启用后，请求体会带上 `context_management`，并在后续轮次中仅保留最新的压缩承载内容，因此特别适合长任务场景。\n- **modelResponsesApiCompactThresholds：** 按模型覆盖 Responses API 的 `compact_threshold`，仅在代理自动附加 `context_management` 时使用。它的优先级高于 `resolveResponsesCompactThreshold` 基于 `max_prompt_tokens * ratio` 的兜底阈值。默认将 `gpt-5.4` 和 `gpt-5.5` 设为 `217600`（`272000 * 0.8`）。未列出的模型继续使用原有兜底逻辑。\n- **modelReasoningEfforts：** 按模型配置发送到 Copilot Responses API 的 `reasoning.effort`。可选值包括 `none`、`minimal`、`low`、`medium`、`high` 和 `xhigh`。若某模型未配置，则默认使用 `high`。\n- **useMessagesApi：** 当为 `true` 时，支持 Copilot 原生 `/v1/messages` 的 Claude 系模型会走 Messages API；否则回退到 `/chat/completions`。设为 `false` 可禁用 Messages API 路由，始终使用 `/chat/completions`。默认值为 `true`。\n- **useResponsesApiWebSocket：** 当为 `true` 时，Responses API 请求会优先对声明了 `ws:/responses` 的模型使用 Copilot websocket transport；仅声明 `/responses` 的模型仍走 HTTP。设为 `false` 可禁用 websocket 路由，并在模型支持 `/responses` 时使用 HTTP `/responses`。默认值为 `true`。\n- **useResponsesApiWebSearch：** 当为 `true` 时，服务端会保留 Responses API 中 `type: \"web_search\"` 的工具并透传到上游。设为 `false` 则会从 `/responses` payload 中移除这些工具。默认值为 `true`。\n- **messageApiWebSearchModel：** 顶层 Copilot `/v1/messages` 请求只包含服务端 `web_search` 工具时使用的全局模型，默认值为 `gpt-5-mini`。如果该值是 `provider/model` 别名，请求会进入对应 provider 的 Messages API 路径，并在转发前移除 provider 前缀。对于 Copilot GPT 模型，web search 会通过 `/responses` 执行。混合 `web_search` 与自定义工具的场景暂不支持，服务端会移除 server-side `web_search`。\n- **claudeTokenMultiplier：** 用于 Claude `/v1/messages/count_tokens` 请求在本地走 GPT tokenizer 估算时的乘数。默认值为 `1.15`。如果你的客户端仍然过晚触发上下文压缩，可以适当调大。这个配置只会在代理本地估算 Claude token 时生效；如果已经配置 `anthropicApiKey` 且 Anthropic token counting 调用成功，则会直接返回 Anthropic 的精确计数，不会使用这个乘数。\n- **anthropicApiKey：** 用于把 Claude `/v1/messages/count_tokens` 请求转发到 Anthropic 真实 token counting 端点的 API key，这样会返回精确计数，而不是 GPT tokenizer 估算值。也可通过环境变量 `ANTHROPIC_API_KEY` 设置。若未配置，或上游调用失败，则回退到由 `claudeTokenMultiplier` 控制的本地 GPT tokenizer 估算。\n\n编辑此文件后即可自定义 prompts，或替换为你自己的快速模型。修改完成后请重启服务（或重新执行命令），让缓存中的配置刷新生效。\n\n## API 认证\n\n- **受保护的普通路由：** 当配置了 `auth.apiKeys` 且非空时，除 `/`、`/usage-viewer` 和 `/usage-viewer/` 以外的普通路由都需要认证。\n- **Admin 路由：** 所有 `/admin/*` 路由都要求 `auth.adminApiKey`。如果缺失，服务会在启动时自动生成并在开始提供服务前写回 `config.json`。\n- **允许的认证头：**\n  - `x-api-key: <your_key>`\n  - `Authorization: Bearer <your_key>`\n- **CORS 预检：** `OPTIONS` 请求始终允许。\n- **未配置普通 key 时：** 普通路由仍可直接访问；但这条规则不适用于 `/admin/*`，后者只接受 `auth.adminApiKey`。\n\n普通受保护路由的示例请求：\n\n```sh\ncurl http://localhost:4141/v1/models \\\n  -H \"x-api-key: your_api_key\"\n```\n\nAdmin 路由的示例请求：\n\n```sh\ncurl http://localhost:4141/admin/config/model-mappings \\\n  -H \"x-api-key: your_admin_api_key\"\n```\n\n## API 端点\n\n服务端提供多个 OpenAI / Anthropic 兼容端点。请求会根据所选模型和 `provider/model` 别名路由到 GitHub Copilot、内置 `codex` provider 或已配置的 provider。\n\n### OpenAI 兼容端点\n\n这些端点模拟 OpenAI API 结构。\n\n| 端点 | 方法 | 说明 |\n| --- | --- | --- |\n| `POST /v1/responses` | `POST` | OpenAI 中用于生成模型响应的高级接口。支持 `openai-responses` provider 的 `provider/model` 别名。 |\n| `POST /v1/chat/completions` | `POST` | 为给定聊天对话创建模型响应。支持 `openai-compatible` provider 的 `provider/model` 别名；目标 provider 已配置时可在没有 Copilot 的情况下使用。 |\n| `GET /v1/models` | `GET` | 列出 Copilot 模型以及已启用 provider 的 `provider/model-id` 模型。 |\n| `POST /v1/embeddings` | `POST` | 创建表示输入文本的向量嵌入。 |\n\n### Anthropic 兼容端点\n\n这些端点设计为兼容 Anthropic Messages API。\n\n| 端点 | 方法 | 说明 |\n| --- | --- | --- |\n| `POST /v1/messages` | `POST` | 为给定对话创建模型响应。支持已配置 provider 的 `provider/model` 别名，包括通过 `openai-compatible` provider 做翻译。 |\n| `POST /v1/messages/count_tokens` | `POST` | 计算一组消息的 token 数。支持已配置 provider 的 `provider/model` 别名。 |\n| `POST /:provider/v1/messages` | `POST` | 将 Anthropic Messages 请求代理到已配置的 Anthropic provider，或翻译到 OpenAI 兼容 / OpenAI Responses provider。 |\n| `GET /:provider/v1/models` | `GET` | 将模型列表请求代理到已配置的 provider。 |\n| `POST /:provider/v1/messages/count_tokens` | `POST` | 为 provider 路由请求在本地计算 token 数。 |\n\n### 使用量监控端点\n\n用于监控 Copilot 用量与额度的新端点。\n\n| 端点 | 方法 | 说明 |\n| --- | --- | --- |\n| `GET /usage` | `GET` | 获取详细的 Copilot 使用统计与额度信息。 |\n| `GET /token` | `GET` | 获取当前 API 正在使用的 Copilot token。 |\n\n### Admin / 配置端点\n\n这些端点用于本地管理操作，只接受 `auth.adminApiKey`。\n\n| 端点 | 方法 | 说明 |\n| --- | --- | --- |\n| `GET /admin/config/model-mappings` | `GET` | 返回当前 `config.json` 路径以及生效中的 `modelMappings` 映射。 |\n| `POST /admin/config/model-mappings` | `POST` | 只更新 `config.json` 里的 `modelMappings` 字段，并回传更新后的结果。 |\n\n## 使用示例\n\n常用 `npx` 命令：\n\n```sh\n# 基础启动\nnpx @jeffreycao/copilot-api@latest start\n\n# 自定义端口并开启详细日志\nnpx @jeffreycao/copilot-api@latest start --port 8080 --verbose\n\n# 执行认证流程\nnpx @jeffreycao/copilot-api@latest auth login\n\n# 配置第三方 provider，然后不依赖 GitHub Copilot 启动\nnpx @jeffreycao/copilot-api@latest auth login --provider dashscope\nnpx @jeffreycao/copilot-api@latest start\n\n# 以 JSON 格式输出调试信息\nnpx @jeffreycao/copilot-api@latest debug --json\n\n# 用 Bun 而不是 Node.js 运行已发布 CLI\nbunx --bun @jeffreycao/copilot-api@latest start\n```\n\n配置 `dashscope` 后的 OpenAI 兼容 provider 调用示例：\n\n```sh\ncurl http://localhost:4141/v1/chat/completions \\\n  -H \"content-type: application/json\" \\\n  -d '{\"model\":\"dashscope/qwen3.6-plus\",\"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]}'\n\ncurl http://localhost:4141/dashscope/v1/messages \\\n  -H \"content-type: application/json\" \\\n  -d '{\"model\":\"qwen3.6-plus\",\"max_tokens\":1024,\"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]}'\n```\n\n## 使用建议\n\n<a id=\"claudemd-or-agentsmd-recommended-content\"></a>\n\n### CLAUDE.md 或 AGENTS.md 推荐内容\n\n如果你想手动加入这些提醒，请在 Claude Code 的 `CLAUDE.md`，或 opencode/codex 的 `AGENTS.md` 中加入以下内容：\n\n```\n- Prohibited from directly asking questions to users, MUST use question tool.\n- Once you can confirm that the task is complete, MUST use question tool to make user confirm. The user may respond with feedback if they are not satisfied with the result, which you can use to make improvements and try again, after try again, MUST use question tool to make user confirm again.\n```\n"}, "33e11fdbea0092509ec0062d29ec52daea7dbb1f": {"t": 1785765583.385947, "n": 30056, "h": "410cc1d4cdedcde2", "c": "# Copilot API Proxy\n\n[English](./README.md) | 简体中文\n\n## 重要说明\n\n> [!IMPORTANT]\n> **使用前请先注意以下几点：**\n>\n> 1. **Claude Code 配置：** 与 Claude Code 搭配使用时，请将模型 ID 配置为 `claude-opus-4-8`。示例 claude `settings.json` 见 [通过 `settings.json` 手动配置](#manual-configuration-with-settingsjson)。\n>\n> 2. **内置 `copilot`、`codex` 与第三方 provider：** 执行 `npx @jeffreycao/copilot-api@latest auth`，可选择 `copilot`、`codex`、`deepseek`、`custom` 等 provider。\n>\n> 3. **注意事项：** README 顶部移除的 GitHub Copilot warning 见 [GitHub Copilot 安全提示](./NOTICE.md#github-copilot-security-notice)。\n\n---\n\n## 项目概览\n\n这是一个小型 AI gateway，可以使用 GitHub Copilot、内置 `codex` provider，也可以使用 DashScope 等已配置的第三方 provider。GitHub Copilot 现在是可选能力：如果本地没有 GitHub token，只要至少配置了一个启用中的 provider，服务仍可按 provider-only 模式启动。\n\nAI gateway 会从同一个本地端点暴露 OpenAI / Anthropic 兼容 API，让 [Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview)、OpenCode、Codex 和 OpenAI 兼容客户端可以共用同一个本地服务。\n\n在 GitHub Copilot 路径上，AI gateway 会在可用时优先使用 Copilot 原生的 Anthropic 风格 Messages API，在重工具调用场景下保留更原生的 Claude 行为。\n\n## 功能特性\n\n- **OpenAI 与 Anthropic 双兼容**：通过 `/v1/responses`、`/v1/chat/completions`、`/v1/models`、`/v1/embeddings` 和 `/v1/messages` 对外暴露同一个本地 AI gateway。\n- **Copilot 可选**：有 GitHub 凭据时可以使用 GitHub Copilot，没有 GitHub 凭据时也可以只依赖已配置的 provider 运行。\n- **同一网关接入 Copilot、`codex` 与第三方 provider**：可统一路由 GitHub Copilot、内置 `codex` provider 和配置好的外部 provider。\n- **第三方 provider 可独立启动**：配置 DashScope、DeepSeek、OpenRouter 或自定义 provider 后，不需要 GitHub Copilot 登录即可启动 AI gateway。\n- **OpenAI 兼容 provider 同时支持 chat 和 Messages API**：`openai-compatible` provider 可通过顶层 `/v1/chat/completions` 搭配 `model: \"provider/model\"` 提供 Chat Completions，也可通过 `/v1/messages` 完成 Anthropic Messages 的请求/响应翻译。\n- **面向 Claude 的更原生 Copilot 路由**：优先使用原生 `/v1/messages`，保留 Claude 风格工具流，支持 Anthropic beta 能力、通过 Responses-capable 模型支持 Claude WebSearch，并保留 subagent / session 标记。\n- **Claude Code 与 OpenCode 集成**：兼容 Claude Code 与 OpenCode，也支持通过 `@ai-sdk/anthropic` 直接作为 Anthropic provider 使用。\n- **灵活的认证与部署选项**：支持交互式登录、直接 token、个人 / Business / Enterprise、GitHub Enterprise、opencode OAuth 和自定义数据目录。\n- **多 provider 路由**：可暴露 `/:provider/...` 路由，也可在顶层 API 上使用 `model: \"provider/model\"`。\n\n## 前置要求\n\n- Bun（>= 1.2.x）\n- 如果要通过 `npx` 运行已发布 CLI，需要 Node.js\n- 只有在使用 GitHub Copilot provider 时，才需要已订阅 Copilot 的 GitHub 账号\n- 如果不使用 GitHub Copilot，需要至少一个已配置 provider 的 API key 或 OAuth 登录\n\n## 安装\n\n安装依赖：\n\n```sh\nbun install\n```\n\n直接从源码启动服务：\n\n```sh\nbun run start start\n```\n\n## 从源码运行\n\n本项目可以通过多种方式从源码运行：\n\n### 开发模式\n\n```sh\nbun run dev start\n```\n\n### 生产模式\n\n```sh\nbun run start start\n```\n\n## 通过 npx 使用\n\n你可以直接用 npx 运行本项目：\n\n> [!IMPORTANT]\n> 通过 `npx` 运行时，token usage 存储会使用 Node 内置的 `node:sqlite` 模块。该能力会在 Node.js >= 22.13.0 时启用；Node.js < 22.13.0 时 CLI 仍可启动，但会禁用 token usage 存储。\n>\n> 如果不升级 Node.js 但仍需要 token usage 存储，可以改用 Bun 运行已发布 CLI：`bunx --bun @jeffreycao/copilot-api@latest start`。\n\n```sh\nnpx @jeffreycao/copilot-api@latest start\n```\n\n带参数示例：\n\n```sh\nnpx @jeffreycao/copilot-api@latest start --port 8080\n```\n\n如果只想做认证或 provider 配置：\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth\n```\n\n如果要不依赖 GitHub Copilot 运行，先配置至少一个 provider，然后正常启动服务：\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth login --provider dashscope\nnpx @jeffreycao/copilot-api@latest start\n```\n\n## 配合 Docker 使用\n\n构建镜像：\n\n```sh\ndocker build -t copilot-api .\n```\n\n通过 bind mount 运行容器，让认证数据在重启后保留：\n\n```sh\nmkdir -p ./copilot-data\ndocker run -p 4141:4141 -v $(pwd)/copilot-data:/root/.local/share/copilot-api copilot-api\n```\n\n这会把宿主机上的 `./copilot-data` 映射到容器内的 `/root/.local/share/copilot-api`，用于持久化 GitHub 认证数据、provider 配置和其他 gateway 状态。\n\n也可以直接通过环境变量传入 GitHub token：\n\n```sh\ndocker run -p 4141:4141 -e GH_TOKEN=your_github_token_here copilot-api\n```\n\n## Electron 桌面应用\n\n如果你更喜欢图形界面，仓库里还提供了位于 `desktop/` 的 Electron 桌面应用。它支持 GitHub Copilot 登录、OpenAI Codex OAuth，以及 DeepSeek、DashScope、OpenRouter 或自定义 provider 的 API Key 配置。授权或配置 provider 后，可以一键启动或停止本地代理，并在界面里直接查看本地端点、鉴权 Header、可用模型、额度和日志。\n\n设置页还可以配置 `OAuth App`、`API Home`、`Enterprise URL`、详细日志以及最小化到托盘。桌面安装包发布在 GitHub Releases：\n\nhttps://github.com/caozhiyuan/copilot-api/releases\n\n下载对应平台的安装包后，在应用内授权或配置 provider，选择端口并启动服务，再把你的客户端指向应用里显示的本地端点即可。发布版桌面应用使用随包内置的 Electron 运行时，正常使用不需要额外安装 Node.js；token usage 历史记录会在该内置运行时支持 SQLite 时启用。\n\n桌面应用里的高级配置页会通过 `GET/POST /admin/config/model-mappings` 读写这份共享的模型映射。同一份映射会统一作用于 `POST /v1/messages`、`POST /v1/messages/count_tokens`、`POST /v1/responses` 和 `POST /v1/chat/completions`，不再按接口区分。它使用的是 `auth.adminApiKey`，不是普通的 `auth.apiKeys`；应用会在服务启动并自动生成该 key 后，直接从 `config.json` 读取它来发起请求。\n\n### 桌面应用截图\n\n下面展示了桌面应用中的首页、Token 用量统计页面：\n\n<p align=\"center\">\n  <img src=\"./docs/screenshots/desktop-dashboard.png\" alt=\"Copilot API 桌面应用首页\" width=\"49%\" />\n  <img src=\"./docs/screenshots/desktop-token-usage.png\" alt=\"Copilot API 桌面应用 Token 用量页\" width=\"49%\" />\n</p>\n\n## 与 Claude Code 一起使用\n\n这个 AI gateway 可以为 [Claude Code](https://docs.anthropic.com/en/claude-code) 提供后端能力。Claude Code 是 Anthropic 提供的实验性面向开发者的对话式 AI 助手。\n\n有两种方式可以把 Claude Code 配置为使用这个 AI gateway：\n\n### 通过 `--claude-code` 标志进行交互式配置\n\n执行带 `--claude-code` 的 `start` 命令开始：\n\n```sh\nnpx @jeffreycao/copilot-api@latest start --claude-code\n```\n\n你会被提示选择一个主模型，以及一个用于后台任务的 \"small, fast\" 模型。选择完成后，会有一条命令被复制到剪贴板中。该命令会设置 Claude Code 使用这个 AI gateway 所需的环境变量。\n\n在新的终端中粘贴并执行这条命令，即可启动 Claude Code。\n\n<a id=\"manual-configuration-with-settingsjson\"></a>\n\n### 通过 `settings.json` 手动配置\n\n另一种方式是在项目根目录中创建 `.claude/settings.json` 文件，并写入 Claude Code 所需的环境变量。这样你就不需要每次都运行交互式配置了。\n\n下面是一个 `.claude/settings.json` 示例：\n\n```json\n{\n  \"env\": {\n    \"ANTHROPIC_BASE_URL\": \"http://localhost:4141\",\n    \"ANTHROPIC_AUTH_TOKEN\": \"dummy\",\n    \"ANTHROPIC_MODEL\": \"deepseek/deepseek-v4-pro\",\n    \"ANTHROPIC_DEFAULT_SONNET_MODEL\": \"deepseek/deepseek-v4-pro\",\n    \"ANTHROPIC_DEFAULT_HAIKU_MODEL\": \"deepseek/deepseek-v4-flash\",\n    \"DISABLE_NON_ESSENTIAL_MODEL_CALLS\": \"1\",\n    \"CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC\": \"1\",\n    \"CLAUDE_CODE_ATTRIBUTION_HEADER\": \"0\",\n    \"CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION\": \"false\",\n    \"CLAUDE_CODE_DISABLE_TERMINAL_TITLE\": \"true\",\n    \"CLAUDE_CODE_ENABLE_AWAY_SUMMARY\": \"0\"\n  },\n  \"permissions\": {\n    \"deny\": [\n      \"mcp__ide__executeCode\"\n    ]\n  }\n}\n```\n\n- 请根据需要替换 `ANTHROPIC_MODEL`、`ANTHROPIC_DEFAULT_OPUS_MODEL`、`ANTHROPIC_DEFAULT_SONNET_MODEL` 和 `ANTHROPIC_DEFAULT_HAIKU_MODEL`。配置完成后，请安装 claude code 插件，见 [插件集成](#plugin-integrations)。\n- 将 `CLAUDE_CODE_ATTRIBUTION_HEADER` 设为 `0` 可以阻止 Claude Code 在 system prompt 中附加计费和版本信息，从而避免 prompt cache 失效。\n- 关闭 `CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION` 和 `CLAUDE_CODE_ENABLE_AWAY_SUMMARY` 可以避免不必要地消耗额度。\n- Claude Code WebSearch 已支持纯搜索请求。Copilot 路径请保持全局 `messageApiWebSearchModel` 指向 Responses-capable GPT 模型或 `provider/model` 别名；provider 路由请使用原生 Anthropic provider 或 `openai-responses` provider。只有在你明确想禁止这类流量时，才需要把 `WebSearch` 加到 `permissions.deny`。\n- 如果使用的不是 Claude 模型，请不要启用 `ENABLE_TOOL_SEARCH`。如果使用的是 Claude 模型，则可以启用 `ENABLE_TOOL_SEARCH`。当前 Claude Code 使用的是客户端 tool search 模式，在该模式下每次加载 defer tools 都需要额外请求一次。\n- `CLAUDE_CODE_AUTO_COMPACT_WINDOW`：设置用于自动压缩计算的上下文容量（以 token 为单位）。默认使用模型自身的上下文窗口：标准模型为 200K，扩展上下文模型为 1M。使用 1M 上下文模型（如 `claude-opus-4-6[1m]`）时，可设置一个较低的值（如 `500000`）将窗口视为 500K 用于压缩计算。该值受限于模型的实际上下文窗口上限。`CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` 会基于此值的百分比生效。设置此变量可将压缩阈值与状态栏的 `used_percentage` 解耦（后者始终使用模型的完整上下文窗口）。\n\n更多选项见：[Claude Code settings](https://docs.anthropic.com/en/docs/claude-code/settings#environment-variables)\n\n也可以参考 IDE 集成说明：[Add Claude Code to your IDE](https://docs.anthropic.com/en/docs/claude-code/ide-integrations)\n\n## 与 OpenCode 一起使用\n\nOpenCode 已经有直接的 GitHub Copilot provider。本节适用于你希望让 OpenCode 通过 `@ai-sdk/anthropic` 指向这个 AI gateway，并复用本 README 前面提到的 agent 行为时。\n\n### 最小配置\n\n使用 OpenCode OAuth app 启动 AI gateway：\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth --oauth-app=opencode\nnpx @jeffreycao/copilot-api@latest start\n```\n\n然后让 OpenCode 通过 `@ai-sdk/anthropic` 指向这个 AI gateway。\n\n示例 `~/.config/opencode/opencode.json`：\n\n```json\n{\n  \"$schema\": \"https://opencode.ai/config.json\",\n  \"provider\": {\n    \"local\": {\n      \"npm\": \"@ai-sdk/anthropic\",\n      \"name\": \"My Local\",\n      \"options\": {\n        \"baseURL\": \"http://localhost:4141/v1\",\n        \"apiKey\": \"dummy\"\n      },\n      \"models\": {\n        \"gpt-5.4\": {\n          \"name\": \"gpt-5.4\",\n          \"modalities\": {\n            \"input\": [\"text\", \"image\"],\n            \"output\": [\"text\"]\n          },\n          \"limit\": {\n            \"context\": 300000,\n            \"output\": 128000\n          }\n        },\n        \"claude-sonnet-4.6\": {\n          \"id\": \"claude-sonnet-4.6\",\n          \"name\": \"claude-sonnet-4.6\",\n          \"modalities\": {\n            \"input\": [\"text\", \"image\"],\n            \"output\": [\"text\"]\n          },\n          \"limit\": {\n            \"context\": 200000,\n            \"output\": 32000\n          },\n          \"options\": {\n            \"thinking\": {\n              \"type\": \"adaptive\"\n            },\n            \"effort\": \"max\"\n          }\n        }\n      }\n    }\n  }\n}\n```\n\n这些字段的重要性：\n\n- `npm: \"@ai-sdk/anthropic\"` 是关键。OpenCode 会以 Anthropic Messages 语义与这个 AI gateway 通信，而不是把一切扁平化为 OpenAI Chat Completions。\n- `options.baseURL` 应设为 `http://localhost:4141/v1`；Anthropic SDK 会自动补上 `/messages`、`/models` 和 `/messages/count_tokens`。\n- 如果你在此代理中启用了 `auth.apiKeys`，请把 `dummy` 替换为真实 key；否则任意占位值都可以。\n\n## 与 Codex 一起使用\n\n这个 AI gateway 也可以为 Codex 提供后端能力。\n\n### Codex `config.toml` 参考配置\n\n把以下 `[model_providers.copilot_api]` 段加入你的 Codex `~/.codex/config.toml`：\n\n```toml\nmodel_provider = \"copilot_api\"\nmodel_reasoning_summary = \"auto\"\nmodel_verbosity = \"medium\"\nmodel_context_window = 272000\nmodel_auto_compact_token_limit = 244800\n\n[model_providers.copilot_api]\nname = \"OpenAI\"\nbase_url = \"http://localhost:4141\"\nenv_key = \"GITHUB_COPILOT_API_KEY\"\nrequires_openai_auth = true\nsupports_websockets = false\nwire_api = \"responses\"\nrequest_max_retries = 3\nstream_max_retries = 1\nstream_idle_timeout_ms = 300000\n\n[features]\nremote_compaction_v2 = true\n\n[analytics]\nenabled = false\n```\n\n> [!NOTE]\n> 此配置仅限于 Codex 与 GitHub Copilot provider。`name` 一定要配置为 `\"OpenAI\"`。它可以缓解 Codex local compact 不命中缓存的问题。如果你已开启 `useResponsesApiContextManagement`（Responses API context management 压缩），通常不会走到 `remote_compaction_v2` 或者 local compact，但如果工具返回 tokens 过大，仍有可能触发。\n\n## GPT Tool Search\n\n对于 `gpt-5.4+` 这类 GPT Responses 模型，这个 AI gateway 可以通过一个很小的 MCP bridge 暴露 Responses `tool_search`。Claude Code 和 opencode 都可以使用同一个 bridge，前提是客户端会加载 MCP server，并且 Anthropic Messages 流量会经过这个 AI gateway。\n\nGPT 模型不要设置 Claude Code 原生的 `ENABLE_TOOL_SEARCH`。这个开关启用的是 Claude Code 自己的客户端 tool search 模式，可能导致 deferred 工具定义不再转发给 AI gateway。这个 AI gateway 需要完整的工具定义，这样才能只保留那一小组常驻加载工具，其余工具统一转换为 Responses deferred namespace。\n\n如果你安装了 `tool-search@copilot-api-marketplace`，Claude Code 会自动带上这个 MCP bridge，可以跳过下面这段 Claude Code MCP 手动配置。\n\n请把 tool search bridge 加到 Claude Code 使用的 MCP 配置中：\n\n```json\n{\n  \"mcpServers\": {\n    \"tool_search\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@jeffreycao/copilot-api@latest\", \"mcp\"]\n    }\n  }\n}\n```\n\n请把 tool search bridge 加到 opencode 使用的 MCP 配置中：\n\n```json\n{\n  \"mcp\": {\n    \"tool_search\": {\n      \"type\": \"local\",\n      \"command\": [\"npx\", \"-y\", \"@jeffreycao/copilot-api@latest\", \"mcp\"]\n    }\n  }\n}\n```\n\n本地开发时可以将命令换成 `bun`，参数换成 `[\"run\", \"./src/main.ts\", \"mcp\"]`。\n\nAI gateway 内部现在会把 OpenAI Responses `tool_search` 配置成 client-executed 模式。deferred tools 仍然会作为可搜索 namespace 暴露给模型，但会明确要求模型直接返回下一步要加载的精确工具名列表。\n\n该 bridge 使用直接工具选择，不做 query 搜索。工具入参是 `names`，值为逗号分隔的精确 deferred 工具名，例如 `TaskList,TaskGet,mcp__fetch__fetch`。\n\n<a id=\"plugin-integrations\"></a>\n\n## 插件集成\n\n本项目为 Claude Code 和 opencode 提供了插件集成。\n\n#### Claude Code 插件集成（基于 marketplace）\n\nClaude Code 集成现在拆分为两个插件：\n\n- `agent-inject` 会在 `SubagentStart` 时注入 `__SUBAGENT_MARKER__...`，以便 AI gateway 推导 `x-initiator: agent`。\n- `tool-search` 会注册用于 GPT Responses deferred tool loading 的 `tool_search` MCP bridge。\n\n- 本仓库中的 marketplace catalog：`.claude-plugin/marketplace.json`\n- 本仓库中的插件源码：`plugin/claude/agent-inject`、`plugin/claude/tool-search`\n\n远程添加 marketplace：\n\n```sh\n/plugin marketplace add https://github.com/caozhiyuan/copilot-api.git\n```\n\n从 marketplace 安装插件：\n\n```sh\n/plugin install agent-inject@copilot-api-marketplace\n/plugin install tool-search@copilot-api-marketplace\n```\n\n安装后，`agent-inject` 会在 `SubagentStart` 时注入 `__SUBAGENT_MARKER__...`，AI gateway 会利用它推导 `x-initiator: agent`。\n\n`agent-inject` 还会注册一个 `UserPromptSubmit` hook，并返回 `{\"continue\": true}`；同时它也可以通过环境变量注入 `SessionStart` reminder 规则：\n\n- `CLAUDE_PLUGIN_ENABLE_QUESTION_RULES=1` 会自动为 Claude Code 启用两条关于使用 `question` 工具的提醒。你也可以把同样的提醒手动写进 `CLAUDE.md`；见 [CLAUDE.md 或 AGENTS.md 推荐内容](#claudemd-or-agentsmd-recommended-content)。\n- `CLAUDE_PLUGIN_ENABLE_NO_BACKGROUND_AGENTS_RULE=1` 会启用关于避免在 agent hooks 中使用 `run_in_background: true` 的提醒。\n\n`tool-search` 插件内置了 [GPT Tool Search](#gpt-tool-search) 一节描述的同一个 MCP bridge，因此安装该插件后，Claude Code 用户无需再手动配置 `tool_search` server。\n\n#### Opencode 插件\n\nsubagent 标记生成器被打包为一个 opencode 插件，位于 `plugin/opencode/subagent-marker.js`。\n\n**安装方式：**\n\n将插件文件复制到你的 opencode 插件目录：\n\n```sh\n# 克隆或下载本仓库后复制该插件\ncp plugin/opencode/subagent-marker.js ~/.config/opencode/plugins/\n```\n\n或者手动在 `~/.config/opencode/plugins/subagent-marker.js` 创建该文件，并填入插件内容。\n\n**功能：**\n\n- 跟踪 subagent 创建的子会话\n- 自动在 subagent 聊天消息前添加 marker system reminder（`__SUBAGENT_MARKER__...`）\n- 设置 `x-session-id` 请求头以跟踪会话\n- 让这个 AI gateway 能够把来自 subagent 的请求识别为 `x-initiator: agent`\n\n该插件会挂接到 `session.created`、`session.deleted`、`chat.message` 和 `chat.headers` 事件上，以无缝提供 subagent marker 能力。\n\n## 使用量查看器\n\n服务启动后，控制台会输出一个 Copilot 使用量看板 URL。这个看板是一个用于监控 API 用量的 Web 界面。\n\n1. 启动服务。例如使用 npx：\n   ```sh\n   npx @jeffreycao/copilot-api@latest start\n   ```\n2. 服务会输出一个 usage viewer 的 URL。将它复制到浏览器中打开，形式大致如下：\n   `http://localhost:4141/usage-viewer?endpoint=http://localhost:4141/usage`\n   - 如果你在 Windows 上使用 `start.bat` 脚本，这个页面会自动打开。\n\n看板提供了更易读的 Copilot 用量视图：\n\n> token usage 历史记录需要 Bun 或 Node.js >= 22.13.0。Node.js < 22.13.0 时服务会正常运行，但 token usage 存储会被禁用。\n\n- **API Endpoint URL**：通过 URL 查询参数指定 API endpoints，默认指向本地服务。支持手动切换为其他兼容 endpoints。\n- **x-api-key 认证**：如果启用了 API Key 认证，可填入 `x-api-key` 请求头。密钥会持久化保存在浏览器本地存储中。\n- **Period 选择器**：支持 Day / Week / Month 三种时间范围，切换时 URL 参数会自动同步，方便收藏和分享。\n- **Fetch Data**：点击 \"Refresh\" 按钮加载或刷新使用数据。页面加载时也会自动拉取数据。\n- **Copilot Quotas 额度**：通过进度条展示 Chat、Completions 等不同服务的额度使用情况，悬停可查看已用/剩余详情。\n- **Token Usage 指标卡片**：汇总当前周期的 Total、Input、Output、Cache Read、Cache Write、Requests 和预估费用。\n- **趋势图（Week / Month）**：提供按模型和指标筛选的折线趋势图，点击数据点可查看单日用量明细。\n- **Model Breakdown 表格**：按模型维度列出周期内的请求数、输入/输出/缓存 token 和预计费用。\n- **Request Events 分页列表**：按时间排序的请求事件记录，支持分页浏览，含时间戳、模型、请求 ID 和 token 用量。\n- **Detailed Information**：展示 API 返回的完整 JSON 响应，便于深入分析所有可用统计数据。\n- **URL-based Configuration**：也可通过 `endpoint` 和 `period` 查询参数直接指定 API 端点与时间范围。例如：\n  `http://localhost:4141/usage-viewer?endpoint=http://your-api-server/usage&period=week`\n\n### Usage Viewer 截图\n\n<p align=\"center\">\n  <img src=\"./docs/screenshots/usage-viewer.png\" alt=\"Copilot API Usage Viewer 页面\" width=\"900\" />\n</p>\n\n## 命令结构\n\nCopilot API 现在使用子命令结构，主要命令包括：\n\n- `start`：启动 AI gateway 服务。如果已有 GitHub token，则启用 Copilot 路径；如果没有 GitHub token，但存在至少一个启用中的 provider，则按 provider-only 模式启动；如果两者都没有，会引导你配置 provider。\n- `auth`：仅执行 provider 登录或配置流程，不启动服务。可用于 GitHub Copilot 登录、Codex OAuth，或第三方 provider API key 配置。\n- `debug`：显示诊断信息，包括版本、运行时详情、文件路径以及认证状态，便于排障与支持。\n\n## 命令行选项\n\n### 全局选项\n\n以下选项可用于任意子命令。若在子命令之前传入，请使用 `--key=value` 形式：\n\n| 选项 | 说明 | 默认值 | 别名 |\n| --- | --- | --- | --- |\n| --api-home | API home 目录路径（设置 `COPILOT_API_HOME`） | 无 | 无 |\n| --oauth-app | OAuth app 标识符（设置 `COPILOT_API_OAUTH_APP`） | 无 | 无 |\n| --enterprise-url | GitHub Enterprise URL（设置 `COPILOT_API_ENTERPRISE_URL`） | 无 | 无 |\n\n### Start 命令选项\n\n以下是 `start` 命令可用的命令行选项：\n\n| 选项 | 说明 | 默认值 | 别名 |\n| --- | --- | --- | --- |\n| --port | 监听端口 | 4141 | -p |\n| --verbose | 启用详细日志 | false | -v |\n| --github-token | 直接提供 GitHub token（必须通过 `auth` 子命令生成） | 无 | -g |\n| --claude-code | 生成一个使用 Copilot API 配置启动 Claude Code 的命令 | false | -c |\n| --show-token | 在获取和刷新时显示 GitHub 与 Copilot token | false | 无 |\n| --proxy-env | 从环境变量初始化代理 | false | 无 |\n\n### Auth 命令选项\n\n| 选项 | 说明 | 默认值 | 别名 |\n| --- | --- | --- | --- |\n| --provider | 要登录或配置的 provider（`copilot`、`codex`、`deepseek`、`dashscope`、`openrouter` 或 `custom`） | 交互选择 | 无 |\n| --verbose | 启用详细日志 | false | -v |\n| --show-token | 认证时显示 GitHub token | false | 无 |\n\n只有在需要启用 GitHub Copilot provider 时，才需要执行 `copilot-api auth login --provider copilot`。使用 `codex` 或第三方 provider-only 模式不要求配置 Copilot。\n\n使用 `copilot-api auth login --provider deepseek`、`--provider dashscope` 或 `--provider openrouter` 可以通过 CLI 快速新增或更新这些常用第三方 provider。DeepSeek 会提示输入掩码显示的 `apiKey`、provider `type`（默认 `anthropic`），以及默认 `https://api.deepseek.com/anthropic` 的 `baseUrl`。DashScope 会提示输入掩码显示的 `apiKey`、provider `type`（默认 `openai-compatible`）和预填默认值的 `baseUrl`。OpenRouter 只提示输入掩码显示的 `apiKey` 和预填默认值的 `baseUrl`，并固定写入 `type: \"anthropic\"`。配置并启用 provider 后，`copilot-api start` 可在没有 GitHub token 的情况下启动。\n\n使用 `copilot-api auth login --provider custom` 可以通过 CLI 新增或更新其他第三方 provider。命令会依次提示输入 provider name、项目支持的 type（`anthropic`、`openai-compatible` 或 `openai-responses`）、`baseUrl`、掩码显示的 `apiKey` 和 `authType`；`authType` 可保持 type 默认值，也可选择 `x-api-key` / `authorization`。\n\n### Debug 命令选项\n\n| 选项 | 说明 | 默认值 | 别名 |\n| --- | --- | --- | --- |\n| --json | 以 JSON 输出调试信息 | false | 无 |\n\n<a id=\"configuration-configjson\"></a>\n\n## 配置（config.json）\n\n- **位置：** Linux/macOS 为 `~/.local/share/copilot-api/config.json`，Windows 为 `%USERPROFILE%\\.local\\share\\copilot-api\\config.json`。\n- **默认结构：**\n  ```json\n  {\n    \"auth\": {\n      \"apiKeys\": [],\n      \"adminApiKey\": \"<startup 自动生成>\"\n    },\n    \"providers\": {},\n    \"modelMappings\": {},\n    \"extraPrompts\": {\n      \"gpt-5-mini\": \"<built-in exploration prompt>\",\n      \"gpt-5.3-codex\": \"<built-in commentary prompt>\",\n      \"gpt-5.4-mini\": \"<built-in commentary prompt>\",\n      \"gpt-5.4\": \"<built-in commentary prompt>\",\n      \"gpt-5.5\": \"<built-in commentary prompt>\"\n    },\n    \"smallModel\": \"gpt-5-mini\",\n    \"useResponsesApiContextManagement\": true,\n    \"modelResponsesApiCompactThresholds\": {\n      \"gpt-5.4\": 217600,\n      \"gpt-5.5\": 217600\n    },\n    \"modelReasoningEfforts\": {\n      \"gpt-5-mini\": \"low\",\n      \"gpt-5.3-codex\": \"xhigh\",\n      \"gpt-5.4-mini\": \"xhigh\",\n      \"gpt-5.4\": \"xhigh\",\n      \"gpt-5.5\": \"xhigh\"\n    },\n    \"useMessagesApi\": true,\n    \"useResponsesApiWebSocket\": true,\n    \"useResponsesApiWebSearch\": true,\n    \"messageApiWebSearchModel\": \"gpt-5-mini\"\n  }\n  ```\n- **auth.apiKeys：** 用于普通非 admin 路由的 API key。支持多个 key 轮换使用。请求可通过 `x-api-key: <key>` 或 `Authorization: Bearer <key>` 进行认证。若为空或省略，则普通路由的认证会被禁用。\n- **auth.adminApiKey：** 仅用于 `/admin/*` 路由的单个 admin key。若未配置，服务会在启动时自动生成一个随机 key，并回写到 `config.json`。它同样使用 `x-api-key` 或 `Authorization: Bearer` 这两种头，但普通 `auth.apiKeys` 不能访问 `/admin/*`。\n- **modelMappings：** 用于顶层 `POST /v1/messages`、`POST /v1/messages/count_tokens`、`POST /v1/responses` 和 `POST /v1/chat/completions` 请求的精确 `sourceModel -> targetModel` 重写映射，这几类接口共用同一份规则。省略该字段或保留为 `{}` 时，不会做模型重写。`source` 和 `target` 都必须是非空字符串。`target` 可以是普通模型 ID，也可以是 `provider/model` 形式的别名，例如 `dashscope/qwen3.6-plus`；重写发生在 provider alias 解析之前。这些映射不再按接口区分。`GET/POST /admin/config/model-mappings` 管理接口读写的也只有这个字段。\n- **extraPrompts：** `model -> prompt` 的映射。把 Anthropic 风格请求翻译给 Copilot 时，会将其附加到第一条 system prompt 后面。你可以借此为不同模型注入护栏或指引。缺失的默认项会自动补齐，但不会覆盖你自定义的 prompt。内置的 `gpt-5.3-codex` 和 `gpt-5.4` prompt 会启用带阶段感知的 commentary，让模型在工具调用或更深层推理前先发出简短的用户可见进度说明。\n- **providers：** 全局上游 provider 映射。每个 provider key（例如 `dashscope`）都会变成一个路由前缀（`/dashscope/v1/messages`）。支持 `type: \"anthropic\"`、`type: \"openai-compatible\"` 和 `type: \"openai-responses\"`。顶层客户端也可以在 `/v1/messages`、`/v1/messages/count_tokens`、`/v1/responses` 和 `/v1/chat/completions` 中使用 `model: \"dashscope/model-id\"`；AI gateway 会在转发上游前移除 `dashscope/` 前缀。`openai-compatible` provider 同时支持 chat 和 Messages 流程：`/v1/chat/completions` 会直连上游 `/v1/chat/completions`，而 `/v1/messages` 和 `/:provider/v1/messages` 会先翻译为上游 Chat Completions，再把响应翻译回 Anthropic Messages。`GET /v1/models` 会聚合已启用 provider 的模型，并以 `provider/model-id` 形式返回；单个 provider 的原始模型列表仍可使用 `GET /dashscope/v1/models`。\n  - `enabled`：可选，若省略则默认为 `true`。\n  - `baseUrl`：provider API 的基础 URL，不要带结尾的 endpoint。Anthropic provider 不要带 `/v1/messages`；OpenAI 兼容 provider 不要带 `/v1/chat/completions`；OpenAI Responses provider 不要带 `/v1/responses`。\n  - `apiKey`：作为上游凭据值使用；普通 provider 必须配置。\n  - `authType`：可选，控制 `apiKey` 如何发送到上游。普通 provider 支持 `x-api-key` 和 `authorization`。Anthropic provider 默认 `x-api-key`；OpenAI 兼容和 OpenAI Responses provider 默认 `authorization`。当设置为 `authorization` 时，代理会发送 `Authorization: Bearer <apiKey>`。`oauth2` 仅保留给内置 `codex` provider，并由 `auth login --provider codex` 自动写入。\n  - `pricingCurrency`：可选，provider 维度的 token 费用币种，例如 `USD` 或 `CNY`。快捷 provider 默认 DashScope、DeepSeek 为 `CNY`，Codex/OpenRouter 为 `USD`。费用按币种分别汇总，不做汇率换算。\n  - `models`：可选，按模型 ID 配置的映射。每个键为请求中的模型名，值支持：\n    - `temperature`：可选，当请求未指定时使用的默认温度。\n    - `topP`：可选，当请求未指定时使用的默认 `top_p`。\n    - `topK`：可选，当请求未指定时使用的默认 `top_k`。\n    - `extraBody`：可选，按模型合入上游请求体的动态字段；请求体显式同名字段优先。OpenAI 兼容 provider 可用它配置 `enable_thinking`、`preserve_thinking`、`reasoning_effort` 等字段。`thinking_budget` 是 OpenAI 兼容 provider 的特殊覆盖项：配置在 `extraBody` 后，会在 Anthropic `thinking.budget_tokens` 翻译之后强制写入，并覆盖请求派生出的预算值。对于 provider name 为 `dashscope` 或 `baseUrl` 包含 `aliyuncs.com` 的 provider，请求派生的 `thinking_budget`（来自 Anthropic `thinking.budget_tokens`）会转发给上游；其他 OpenAI 兼容 provider 会移除请求派生的 `thinking_budget`，但 `extraBody` 中的 `thinking_budget` 仍然生效。\n    - `pricing`：可选，按模型配置 token 单价，币种使用 provider 的 `pricingCurrency`，单位为每 100 万 tokens。支持 `input`、`output`、`cachedInput`（隐式缓存读）、`explicitCachedInput`（显式缓存读）和 `cacheCreationInput`。如需按输入 token 总量分档，可用带 `maxInputTokens` 的 `tiers`。\n    - `contextCache`：可选，provider name 为 `dashscope` 或 `baseUrl` 包含 `aliyuncs.com` 时默认 `true`，其他 OpenAI 兼容 provider 默认 `false`。用于启用阿里云百炼/DashScope 的显式缓存（explicit context cache），会按其 Context Cache 格式在最多 4 个 content block 上注入 `cache_control: { \"type\": \"ephemeral\" }`。缓存断点策略与 opencode 主链路保持一致：前 2 条 system 消息 + 最后 2 条非 system 消息。标记字符串 content 时会把 `system` / `user` / `assistant` / `tool` 消息转换为 text content part 数组；已有数组 content 则标记最后一个 part。如果模型本身已经支持隐式缓存，或上游不支持该显式缓存扩展字段，可在模型配置中设为 `false`。支持相同显式缓存扩展的非 DashScope provider 可设为 `true`。\n    - `supportPdf`：可选，控制该模型是否支持 PDF/document content。默认 `false`，不支持时会把 PDF 转成提示文本；设为 `true` 时会把 PDF/document 转成 OpenAI Chat Completions 的 file part。\n    - `toolContentSupportType`：可选，配置该模型的 tool result content 支持能力，值为 `array`、`image`、`pdf` 的数组。provider 侧未配置时默认只发送 string tool content。若 `supportPdf` 为 `true` 但这里不包含 `pdf`，tool result 里的 file part 会被转成 user role 消息。Copilot 主链路不使用这个 provider 默认，仍按 array + image 且不支持 PDF 的能力处理。\n\n  DashScope 模型配置示例：\n  ```json\n  {\n    \"providers\": {\n      \"dashscope\": {\n        \"type\": \"openai-compatible\",\n        \"enabled\": true,\n        \"baseUrl\": \"https://dashscope.aliyuncs.com/compatible-mode\",\n        \"apiKey\": \"sk-your-dashscope-key\",\n        \"pricingCurrency\": \"CNY\",\n        \"models\": {\n          \"qwen3.7-plus\": {\n            \"temperature\": 1,\n            \"topP\": 0.95,\n            \"topK\": 20,\n            \"extraBody\": {\n              \"preserve_thinking\": true\n            }\n          },\n          \"glm-5.1\": {\n            \"temperature\": 0.7,\n            \"topP\": 0.95,\n            \"contextCache\": true,\n            \"pricing\": {\n              \"tiers\": [\n                {\n                  \"maxInputTokens\": 32000,\n                  \"input\": 6,\n                  \"cachedInput\": 1.2,\n                  \"explicitCachedInput\": 0.6,\n                  \"cacheCreationInput\": 7.5,\n                  \"output\": 24\n                },\n                {\n                  \"maxInputTokens\": 200000,\n                  \"input\": 8,\n                  \"cachedInput\": 1.6,\n                  \"explicitCachedInput\": 0.8,\n                  \"cacheCreationInput\": 10,\n                  \"output\": 28\n                }\n              ]\n            },\n            \"extraBody\": {\n              \"preserve_thinking\": true\n            }\n          }\n        }\n      }\n    }\n  }\n  ```\n  内置 token 价格覆盖 Codex GPT 模型（USD）、DashScope `qwen3.7-max`、`qwen3.7-plus`、`glm-5.1`、`glm-5.2`（CNY），以及 DeepSeek `deepseek-v4-flash`、`deepseek-v4-pro`、`deepseek-chat`、`deepseek-reasoner`（CNY）。用户配置的 `pricing` 优先于内置价格。DashScope 若上游 usage 中出现 `cache_creation_input_tokens` 字段，cached tokens 按显式缓存读价计费；否则 `cachedInput` 作为隐式缓存读价。DeepSeek 的 `prompt_cache_hit_tokens` 会归入 cached input，`prompt_cache_miss_tokens` 会归入普通 input。\n- **smallModel：** 无工具预热消息的回退模型（例如 Claude Code 的探测请求）；默认是 `gpt-5-mini`。\n- **useResponsesApiContextManagement：** 当为 `true` 时，代理会为 Responses API 附加 `context_management` 压缩指令。默认值为 `true`。如需全局关闭，可设为 `false`。启用后，请求体会带上 `context_management`，并在后续轮次中仅保留最新的压缩承载内容，因此特别适合长任务场景。\n- **modelResponsesApiCompactThresholds：** 按模型覆盖 Responses API 的 `compact_threshold`，仅在代理自动附加 `context_management` 时使用。它的优先级高于 `resolveResponsesCompactThreshold` 基于 `max_prompt_tokens * ratio` 的兜底阈值。默认将 `gpt-5.4` 和 `gpt-5.5` 设为 `217600`（`272000 * 0.8`）。未列出的模型继续使用原有兜底逻辑。\n- **modelReasoningEfforts：** 按模型配置发送到 Copilot Responses API 的 `reasoning.effort`。可选值包括 `none`、`minimal`、`low`、`medium`、`high` 和 `xhigh`。若某模型未配置，则默认使用 `high`。\n- **useMessagesApi：** 当为 `true` 时，支持 Copilot 原生 `/v1/messages` 的 Claude 系模型会走 Messages API；否则回退到 `/chat/completions`。设为 `false` 可禁用 Messages API 路由，始终使用 `/chat/completions`。默认值为 `true`。\n- **useResponsesApiWebSocket：** 当为 `true` 时，Responses API 请求会优先对声明了 `ws:/responses` 的模型使用 Copilot websocket transport；仅声明 `/responses` 的模型仍走 HTTP。设为 `false` 可禁用 websocket 路由，并在模型支持 `/responses` 时使用 HTTP `/responses`。默认值为 `true`。\n- **useResponsesApiWebSearch：** 当为 `true` 时，服务端会保留 Responses API 中 `type: \"web_search\"` 的工具并透传到上游。设为 `false` 则会从 `/responses` payload 中移除这些工具。默认值为 `true`。\n- **messageApiWebSearchModel：** 顶层 Copilot `/v1/messages` 请求只包含服务端 `web_search` 工具时使用的全局模型，默认值为 `gpt-5-mini`。如果该值是 `provider/model` 别名，请求会进入对应 provider 的 Messages API 路径，并在转发前移除 provider 前缀。对于 Copilot GPT 模型，web search 会通过 `/responses` 执行。混合 `web_search` 与自定义工具的场景暂不支持，服务端会移除 server-side `web_search`。\n- **claudeTokenMultiplier：** 用于 Claude `/v1/messages/count_tokens` 请求在本地走 GPT tokenizer 估算时的乘数。默认值为 `1.15`。如果你的客户端仍然过晚触发上下文压缩，可以适当调大。这个配置只会在代理本地估算 Claude token 时生效；如果已经配置 `anthropicApiKey` 且 Anthropic token counting 调用成功，则会直接返回 Anthropic 的精确计数，不会使用这个乘数。\n- **anthropicApiKey：** 用于把 Claude `/v1/messages/count_tokens` 请求转发到 Anthropic 真实 token counting 端点的 API key，这样会返回精确计数，而不是 GPT tokenizer 估算值。也可通过环境变量 `ANTHROPIC_API_KEY` 设置。若未配置，或上游调用失败，则回退到由 `claudeTokenMultiplier` 控制的本地 GPT tokenizer 估算。\n\n编辑此文件后即可自定义 prompts，或替换为你自己的快速模型。修改完成后请重启服务（或重新执行命令），让缓存中的配置刷新生效。\n\n## API 认证\n\n- **受保护的普通路由：** 当配置了 `auth.apiKeys` 且非空时，除 `/`、`/usage-viewer` 和 `/usage-viewer/` 以外的普通路由都需要认证。\n- **Admin 路由：** 所有 `/admin/*` 路由都要求 `auth.adminApiKey`。如果缺失，服务会在启动时自动生成并在开始提供服务前写回 `config.json`。\n- **允许的认证头：**\n  - `x-api-key: <your_key>`\n  - `Authorization: Bearer <your_key>`\n- **CORS 预检：** `OPTIONS` 请求始终允许。\n- **未配置普通 key 时：** 普通路由仍可直接访问；但这条规则不适用于 `/admin/*`，后者只接受 `auth.adminApiKey`。\n\n普通受保护路由的示例请求：\n\n```sh\ncurl http://localhost:4141/v1/models \\\n  -H \"x-api-key: your_api_key\"\n```\n\nAdmin 路由的示例请求：\n\n```sh\ncurl http://localhost:4141/admin/config/model-mappings \\\n  -H \"x-api-key: your_admin_api_key\"\n```\n\n## API 端点\n\n服务端提供多个 OpenAI / Anthropic 兼容端点。请求会根据所选模型和 `provider/model` 别名路由到 GitHub Copilot、内置 `codex` provider 或已配置的 provider。\n\n### OpenAI 兼容端点\n\n这些端点模拟 OpenAI API 结构。\n\n| 端点 | 方法 | 说明 |\n| --- | --- | --- |\n| `POST /v1/responses` | `POST` | OpenAI 中用于生成模型响应的高级接口。支持 `openai-responses` provider 的 `provider/model` 别名。 |\n| `POST /v1/chat/completions` | `POST` | 为给定聊天对话创建模型响应。支持 `openai-compatible` provider 的 `provider/model` 别名；目标 provider 已配置时可在没有 Copilot 的情况下使用。 |\n| `GET /v1/models` | `GET` | 列出 Copilot 模型以及已启用 provider 的 `provider/model-id` 模型。 |\n| `POST /v1/embeddings` | `POST` | 创建表示输入文本的向量嵌入。 |\n\n### Anthropic 兼容端点\n\n这些端点设计为兼容 Anthropic Messages API。\n\n| 端点 | 方法 | 说明 |\n| --- | --- | --- |\n| `POST /v1/messages` | `POST` | 为给定对话创建模型响应。支持已配置 provider 的 `provider/model` 别名，包括通过 `openai-compatible` provider 做翻译。 |\n| `POST /v1/messages/count_tokens` | `POST` | 计算一组消息的 token 数。支持已配置 provider 的 `provider/model` 别名。 |\n| `POST /:provider/v1/messages` | `POST` | 将 Anthropic Messages 请求代理到已配置的 Anthropic provider，或翻译到 OpenAI 兼容 / OpenAI Responses provider。 |\n| `GET /:provider/v1/models` | `GET` | 将模型列表请求代理到已配置的 provider。 |\n| `POST /:provider/v1/messages/count_tokens` | `POST` | 为 provider 路由请求在本地计算 token 数。 |\n\n### 使用量监控端点\n\n用于监控 Copilot 用量与额度的新端点。\n\n| 端点 | 方法 | 说明 |\n| --- | --- | --- |\n| `GET /usage` | `GET` | 获取详细的 Copilot 使用统计与额度信息。 |\n| `GET /token` | `GET` | 获取当前 API 正在使用的 Copilot token。 |\n\n### Admin / 配置端点\n\n这些端点用于本地管理操作，只接受 `auth.adminApiKey`。\n\n| 端点 | 方法 | 说明 |\n| --- | --- | --- |\n| `GET /admin/config/model-mappings` | `GET` | 返回当前 `config.json` 路径以及生效中的 `modelMappings` 映射。 |\n| `POST /admin/config/model-mappings` | `POST` | 只更新 `config.json` 里的 `modelMappings` 字段，并回传更新后的结果。 |\n\n## 使用示例\n\n常用 `npx` 命令：\n\n```sh\n# 基础启动\nnpx @jeffreycao/copilot-api@latest start\n\n# 自定义端口并开启详细日志\nnpx @jeffreycao/copilot-api@latest start --port 8080 --verbose\n\n# 执行认证流程\nnpx @jeffreycao/copilot-api@latest auth login\n\n# 配置第三方 provider，然后不依赖 GitHub Copilot 启动\nnpx @jeffreycao/copilot-api@latest auth login --provider dashscope\nnpx @jeffreycao/copilot-api@latest start\n\n# 以 JSON 格式输出调试信息\nnpx @jeffreycao/copilot-api@latest debug --json\n\n# 用 Bun 而不是 Node.js 运行已发布 CLI\nbunx --bun @jeffreycao/copilot-api@latest start\n```\n\n配置 `dashscope` 后的 OpenAI 兼容 provider 调用示例：\n\n```sh\ncurl http://localhost:4141/v1/chat/completions \\\n  -H \"content-type: application/json\" \\\n  -d '{\"model\":\"dashscope/qwen3.6-plus\",\"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]}'\n\ncurl http://localhost:4141/dashscope/v1/messages \\\n  -H \"content-type: application/json\" \\\n  -d '{\"model\":\"qwen3.6-plus\",\"max_tokens\":1024,\"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]}'\n```\n\n## 使用建议\n\n<a id=\"claudemd-or-agentsmd-recommended-content\"></a>\n\n### CLAUDE.md 或 AGENTS.md 推荐内容\n\n如果你想手动加入这些提醒，请在 Claude Code 的 `CLAUDE.md`，或 opencode/codex 的 `AGENTS.md` 中加入以下内容：\n\n```\n- Prohibited from directly asking questions to users, MUST use question tool.\n- Once you can confirm that the task is complete, MUST use question tool to make user confirm. The user may respond with feedback if they are not satisfied with the result, which you can use to make improvements and try again, after try again, MUST use question tool to make user confirm again.\n```\n"}, "eaaab7b7e772ba8bad0b88cc906fb56001bbccae": {"t": 1785765584.8735738, "n": 29710, "h": "2c82fc35c8352d2e", "c": "# Copilot API Proxy\n\n[English](./README.md) | 简体中文\n\n## 重要说明\n\n> [!IMPORTANT]\n> **使用前请先注意以下几点：**\n>\n> 1. **Claude Code 配置：** 与 Claude Code 搭配使用时，请将模型 ID 配置为 `claude-opus-4-8`。示例 claude `settings.json` 见 [通过 `settings.json` 手动配置](#manual-configuration-with-settingsjson)。\n>\n> 2. **内置 `copilot`、`codex` 与第三方 provider：** 执行 `npx @jeffreycao/copilot-api@latest auth`，可选择 `copilot`、`codex`、`deepseek`、`custom` 等 provider。\n>\n> 3. **注意事项：** README 顶部移除的 GitHub Copilot warning 见 [GitHub Copilot 安全提示](./NOTICE.md#github-copilot-security-notice)。\n\n---\n\n## 项目概览\n\n这是一个小型 AI gateway，可以使用 GitHub Copilot、内置 `codex` provider，也可以使用 DashScope 等已配置的第三方 provider。GitHub Copilot 现在是可选能力：如果本地没有 GitHub token，只要至少配置了一个启用中的 provider，服务仍可按 provider-only 模式启动。\n\nAI gateway 会从同一个本地端点暴露 OpenAI / Anthropic 兼容 API，让 [Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview)、OpenCode、Codex 和 OpenAI 兼容客户端可以共用同一个本地服务。\n\n在 GitHub Copilot 路径上，AI gateway 会在可用时优先使用 Copilot 原生的 Anthropic 风格 Messages API，在重工具调用场景下保留更原生的 Claude 行为。\n\n## 功能特性\n\n- **OpenAI 与 Anthropic 双兼容**：通过 `/v1/responses`、`/v1/chat/completions`、`/v1/models`、`/v1/embeddings` 和 `/v1/messages` 对外暴露同一个本地 AI gateway。\n- **Copilot 可选**：有 GitHub 凭据时可以使用 GitHub Copilot，没有 GitHub 凭据时也可以只依赖已配置的 provider 运行。\n- **同一网关接入 Copilot、`codex` 与第三方 provider**：可统一路由 GitHub Copilot、内置 `codex` provider 和配置好的外部 provider。\n- **第三方 provider 可独立启动**：配置 DashScope、DeepSeek、OpenRouter 或自定义 provider 后，不需要 GitHub Copilot 登录即可启动 AI gateway。\n- **OpenAI 兼容 provider 同时支持 chat 和 Messages API**：`openai-compatible` provider 可通过顶层 `/v1/chat/completions` 搭配 `model: \"provider/model\"` 提供 Chat Completions，也可通过 `/v1/messages` 完成 Anthropic Messages 的请求/响应翻译。\n- **面向 Claude 的更原生 Copilot 路由**：优先使用原生 `/v1/messages`，保留 Claude 风格工具流，支持 Anthropic beta 能力、通过 Responses-capable 模型支持 Claude WebSearch，并保留 subagent / session 标记。\n- **Claude Code 与 OpenCode 集成**：兼容 Claude Code 与 OpenCode，也支持通过 `@ai-sdk/anthropic` 直接作为 Anthropic provider 使用。\n- **灵活的认证与部署选项**：支持交互式登录、直接 token、个人 / Business / Enterprise、GitHub Enterprise、opencode OAuth 和自定义数据目录。\n- **多 provider 路由**：可暴露 `/:provider/...` 路由，也可在顶层 API 上使用 `model: \"provider/model\"`。\n\n## 前置要求\n\n- Bun（>= 1.2.x）\n- 如果要通过 `npx` 运行已发布 CLI，需要 Node.js\n- 只有在使用 GitHub Copilot provider 时，才需要已订阅 Copilot 的 GitHub 账号\n- 如果不使用 GitHub Copilot，需要至少一个已配置 provider 的 API key 或 OAuth 登录\n\n## 安装\n\n安装依赖：\n\n```sh\nbun install\n```\n\n直接从源码启动服务：\n\n```sh\nbun run start start\n```\n\n## 从源码运行\n\n本项目可以通过多种方式从源码运行：\n\n### 开发模式\n\n```sh\nbun run dev start\n```\n\n### 生产模式\n\n```sh\nbun run start start\n```\n\n## 通过 npx 使用\n\n你可以直接用 npx 运行本项目：\n\n> [!IMPORTANT]\n> 通过 `npx` 运行时，token usage 存储会使用 Node 内置的 `node:sqlite` 模块。该能力会在 Node.js >= 22.13.0 时启用；Node.js < 22.13.0 时 CLI 仍可启动，但会禁用 token usage 存储。\n>\n> 如果不升级 Node.js 但仍需要 token usage 存储，可以改用 Bun 运行已发布 CLI：`bunx --bun @jeffreycao/copilot-api@latest start`。\n\n```sh\nnpx @jeffreycao/copilot-api@latest start\n```\n\n带参数示例：\n\n```sh\nnpx @jeffreycao/copilot-api@latest start --port 8080\n```\n\n如果只想做认证或 provider 配置：\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth\n```\n\n如果要不依赖 GitHub Copilot 运行，先配置至少一个 provider，然后正常启动服务：\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth login --provider dashscope\nnpx @jeffreycao/copilot-api@latest start\n```\n\n## 配合 Docker 使用\n\n构建镜像：\n\n```sh\ndocker build -t copilot-api .\n```\n\n通过 bind mount 运行容器，让认证数据在重启后保留：\n\n```sh\nmkdir -p ./copilot-data\ndocker run -p 4141:4141 -v $(pwd)/copilot-data:/root/.local/share/copilot-api copilot-api\n```\n\n这会把宿主机上的 `./copilot-data` 映射到容器内的 `/root/.local/share/copilot-api`，用于持久化 GitHub 认证数据、provider 配置和其他 gateway 状态。\n\n也可以直接通过环境变量传入 GitHub token：\n\n```sh\ndocker run -p 4141:4141 -e GH_TOKEN=your_github_token_here copilot-api\n```\n\n## Electron 桌面应用\n\n如果你更喜欢图形界面，仓库里还提供了位于 `desktop/` 的 Electron 桌面应用。它支持 GitHub Copilot 登录、OpenAI Codex OAuth，以及 DeepSeek、DashScope、OpenRouter 或自定义 provider 的 API Key 配置。授权或配置 provider 后，可以一键启动或停止本地代理，并在界面里直接查看本地端点、鉴权 Header、可用模型、额度和日志。\n\n设置页还可以配置 `OAuth App`、`API Home`、`Enterprise URL`、详细日志以及最小化到托盘。桌面安装包发布在 GitHub Releases：\n\nhttps://github.com/caozhiyuan/copilot-api/releases\n\n下载对应平台的安装包后，在应用内授权或配置 provider，选择端口并启动服务，再把你的客户端指向应用里显示的本地端点即可。发布版桌面应用使用随包内置的 Electron 运行时，正常使用不需要额外安装 Node.js；token usage 历史记录会在该内置运行时支持 SQLite 时启用。\n\n桌面应用里的高级配置页会通过 `GET/POST /admin/config/model-mappings` 读写这份共享的模型映射。同一份映射会统一作用于 `POST /v1/messages`、`POST /v1/messages/count_tokens`、`POST /v1/responses` 和 `POST /v1/chat/completions`，不再按接口区分。它使用的是 `auth.adminApiKey`，不是普通的 `auth.apiKeys`；应用会在服务启动并自动生成该 key 后，直接从 `config.json` 读取它来发起请求。\n\n### 桌面应用截图\n\n下面展示了桌面应用中的首页、Token 用量统计页面：\n\n<p align=\"center\">\n  <img src=\"./docs/screenshots/desktop-dashboard.png\" alt=\"Copilot API 桌面应用首页\" width=\"49%\" />\n  <img src=\"./docs/screenshots/desktop-token-usage.png\" alt=\"Copilot API 桌面应用 Token 用量页\" width=\"49%\" />\n</p>\n\n## 与 Claude Code 一起使用\n\n这个 AI gateway 可以为 [Claude Code](https://docs.anthropic.com/en/claude-code) 提供后端能力。Claude Code 是 Anthropic 提供的实验性面向开发者的对话式 AI 助手。\n\n有两种方式可以把 Claude Code 配置为使用这个 AI gateway：\n\n### 通过 `--claude-code` 标志进行交互式配置\n\n执行带 `--claude-code` 的 `start` 命令开始：\n\n```sh\nnpx @jeffreycao/copilot-api@latest start --claude-code\n```\n\n你会被提示选择一个主模型，以及一个用于后台任务的 \"small, fast\" 模型。选择完成后，会有一条命令被复制到剪贴板中。该命令会设置 Claude Code 使用这个 AI gateway 所需的环境变量。\n\n在新的终端中粘贴并执行这条命令，即可启动 Claude Code。\n\n<a id=\"manual-configuration-with-settingsjson\"></a>\n\n### 通过 `settings.json` 手动配置\n\n另一种方式是在项目根目录中创建 `.claude/settings.json` 文件，并写入 Claude Code 所需的环境变量。这样你就不需要每次都运行交互式配置了。\n\n下面是一个 `.claude/settings.json` 示例：\n\n```json\n{\n  \"env\": {\n    \"ANTHROPIC_BASE_URL\": \"http://localhost:4141\",\n    \"ANTHROPIC_AUTH_TOKEN\": \"dummy\",\n    \"ANTHROPIC_MODEL\": \"deepseek/deepseek-v4-pro\",\n    \"ANTHROPIC_DEFAULT_SONNET_MODEL\": \"deepseek/deepseek-v4-pro\",\n    \"ANTHROPIC_DEFAULT_HAIKU_MODEL\": \"deepseek/deepseek-v4-flash\",\n    \"DISABLE_NON_ESSENTIAL_MODEL_CALLS\": \"1\",\n    \"CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC\": \"1\",\n    \"CLAUDE_CODE_ATTRIBUTION_HEADER\": \"0\",\n    \"CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION\": \"false\",\n    \"CLAUDE_CODE_DISABLE_TERMINAL_TITLE\": \"true\",\n    \"CLAUDE_CODE_ENABLE_AWAY_SUMMARY\": \"0\"\n  },\n  \"permissions\": {\n    \"deny\": [\n      \"mcp__ide__executeCode\"\n    ]\n  }\n}\n```\n\n- 请根据需要替换 `ANTHROPIC_MODEL`、`ANTHROPIC_DEFAULT_OPUS_MODEL`、`ANTHROPIC_DEFAULT_SONNET_MODEL` 和 `ANTHROPIC_DEFAULT_HAIKU_MODEL`。配置完成后，请安装 claude code 插件，见 [插件集成](#plugin-integrations)。\n- 将 `CLAUDE_CODE_ATTRIBUTION_HEADER` 设为 `0` 可以阻止 Claude Code 在 system prompt 中附加计费和版本信息，从而避免 prompt cache 失效。\n- 关闭 `CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION` 和 `CLAUDE_CODE_ENABLE_AWAY_SUMMARY` 可以避免不必要地消耗额度。\n- Claude Code WebSearch 已支持纯搜索请求。Copilot 路径请保持全局 `messageApiWebSearchModel` 指向 Responses-capable GPT 模型或 `provider/model` 别名；provider 路由请使用原生 Anthropic provider 或 `openai-responses` provider。只有在你明确想禁止这类流量时，才需要把 `WebSearch` 加到 `permissions.deny`。\n- 如果使用的不是 Claude 模型，请不要启用 `ENABLE_TOOL_SEARCH`。如果使用的是 Claude 模型，则可以启用 `ENABLE_TOOL_SEARCH`。当前 Claude Code 使用的是客户端 tool search 模式，在该模式下每次加载 defer tools 都需要额外请求一次。\n- `CLAUDE_CODE_AUTO_COMPACT_WINDOW`：设置用于自动压缩计算的上下文容量（以 token 为单位）。默认使用模型自身的上下文窗口：标准模型为 200K，扩展上下文模型为 1M。使用 1M 上下文模型（如 `claude-opus-4-6[1m]`）时，可设置一个较低的值（如 `500000`）将窗口视为 500K 用于压缩计算。该值受限于模型的实际上下文窗口上限。`CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` 会基于此值的百分比生效。设置此变量可将压缩阈值与状态栏的 `used_percentage` 解耦（后者始终使用模型的完整上下文窗口）。\n\n更多选项见：[Claude Code settings](https://docs.anthropic.com/en/docs/claude-code/settings#environment-variables)\n\n也可以参考 IDE 集成说明：[Add Claude Code to your IDE](https://docs.anthropic.com/en/docs/claude-code/ide-integrations)\n\n## 与 OpenCode 一起使用\n\nOpenCode 已经有直接的 GitHub Copilot provider。本节适用于你希望让 OpenCode 通过 `@ai-sdk/anthropic` 指向这个 AI gateway，并复用本 README 前面提到的 agent 行为时。\n\n### 最小配置\n\n使用 OpenCode OAuth app 启动 AI gateway：\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth --oauth-app=opencode\nnpx @jeffreycao/copilot-api@latest start\n```\n\n然后让 OpenCode 通过 `@ai-sdk/anthropic` 指向这个 AI gateway。\n\n示例 `~/.config/opencode/opencode.json`：\n\n```json\n{\n  \"$schema\": \"https://opencode.ai/config.json\",\n  \"provider\": {\n    \"local\": {\n      \"npm\": \"@ai-sdk/anthropic\",\n      \"name\": \"My Local\",\n      \"options\": {\n        \"baseURL\": \"http://localhost:4141/v1\",\n        \"apiKey\": \"dummy\"\n      },\n      \"models\": {\n        \"gpt-5.4\": {\n          \"name\": \"gpt-5.4\",\n          \"modalities\": {\n            \"input\": [\"text\", \"image\"],\n            \"output\": [\"text\"]\n          },\n          \"limit\": {\n            \"context\": 300000,\n            \"output\": 128000\n          }\n        },\n        \"claude-sonnet-4.6\": {\n          \"id\": \"claude-sonnet-4.6\",\n          \"name\": \"claude-sonnet-4.6\",\n          \"modalities\": {\n            \"input\": [\"text\", \"image\"],\n            \"output\": [\"text\"]\n          },\n          \"limit\": {\n            \"context\": 200000,\n            \"output\": 32000\n          },\n          \"options\": {\n            \"thinking\": {\n              \"type\": \"adaptive\"\n            },\n            \"effort\": \"max\"\n          }\n        }\n      }\n    }\n  }\n}\n```\n\n这些字段的重要性：\n\n- `npm: \"@ai-sdk/anthropic\"` 是关键。OpenCode 会以 Anthropic Messages 语义与这个 AI gateway 通信，而不是把一切扁平化为 OpenAI Chat Completions。\n- `options.baseURL` 应设为 `http://localhost:4141/v1`；Anthropic SDK 会自动补上 `/messages`、`/models` 和 `/messages/count_tokens`。\n- 如果你在此代理中启用了 `auth.apiKeys`，请把 `dummy` 替换为真实 key；否则任意占位值都可以。\n\n## 与 Codex 一起使用\n\n这个 AI gateway 也可以为 Codex 提供后端能力。\n\n### Codex `config.toml` 参考配置\n\n把以下 `[model_providers.copilot_api]` 段加入你的 Codex `~/.codex/config.toml`：\n\n```toml\nmodel_provider = \"copilot_api\"\nmodel_reasoning_summary = \"auto\"\nmodel_verbosity = \"medium\"\nmodel_context_window = 272000\nmodel_auto_compact_token_limit = 244800\n\n[model_providers.copilot_api]\nname = \"OpenAI\"\nbase_url = \"http://localhost:4141\"\nenv_key = \"GITHUB_COPILOT_API_KEY\"\nrequires_openai_auth = true\nsupports_websockets = false\nwire_api = \"responses\"\nrequest_max_retries = 3\nstream_max_retries = 1\nstream_idle_timeout_ms = 300000\n\n[features]\nremote_compaction_v2 = true\n\n[analytics]\nenabled = false\n```\n\n> [!NOTE]\n> 此配置仅限于 Codex 与 GitHub Copilot provider。`name` 一定要配置为 `\"OpenAI\"`。它可以缓解 Codex local compact 不命中缓存的问题。如果你已开启 `useResponsesApiContextManagement`（Responses API context management 压缩），通常不会走到 `remote_compaction_v2` 或者 local compact，但如果工具返回 tokens 过大，仍有可能触发。\n\n## GPT Tool Search\n\n对于 `gpt-5.4+` 这类 GPT Responses 模型，这个 AI gateway 可以通过一个很小的 MCP bridge 暴露 Responses `tool_search`。Claude Code 和 opencode 都可以使用同一个 bridge，前提是客户端会加载 MCP server，并且 Anthropic Messages 流量会经过这个 AI gateway。\n\nGPT 模型不要设置 Claude Code 原生的 `ENABLE_TOOL_SEARCH`。这个开关启用的是 Claude Code 自己的客户端 tool search 模式，可能导致 deferred 工具定义不再转发给 AI gateway。这个 AI gateway 需要完整的工具定义，这样才能只保留那一小组常驻加载工具，其余工具统一转换为 Responses deferred namespace。\n\n如果你安装了 `tool-search@copilot-api-marketplace`，Claude Code 会自动带上这个 MCP bridge，可以跳过下面这段 Claude Code MCP 手动配置。\n\n请把 tool search bridge 加到 Claude Code 使用的 MCP 配置中：\n\n```json\n{\n  \"mcpServers\": {\n    \"tool_search\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@jeffreycao/copilot-api@latest\", \"mcp\"]\n    }\n  }\n}\n```\n\n请把 tool search bridge 加到 opencode 使用的 MCP 配置中：\n\n```json\n{\n  \"mcp\": {\n    \"tool_search\": {\n      \"type\": \"local\",\n      \"command\": [\"npx\", \"-y\", \"@jeffreycao/copilot-api@latest\", \"mcp\"]\n    }\n  }\n}\n```\n\n本地开发时可以将命令换成 `bun`，参数换成 `[\"run\", \"./src/main.ts\", \"mcp\"]`。\n\nAI gateway 内部现在会把 OpenAI Responses `tool_search` 配置成 client-executed 模式。deferred tools 仍然会作为可搜索 namespace 暴露给模型，但会明确要求模型直接返回下一步要加载的精确工具名列表。\n\n该 bridge 使用直接工具选择，不做 query 搜索。工具入参是 `names`，值为逗号分隔的精确 deferred 工具名，例如 `TaskList,TaskGet,mcp__fetch__fetch`。\n\n<a id=\"plugin-integrations\"></a>\n\n## 插件集成\n\n本项目为 Claude Code 和 opencode 提供了插件集成。\n\n#### Claude Code 插件集成（基于 marketplace）\n\nClaude Code 集成现在拆分为两个插件：\n\n- `agent-inject` 会在 `SubagentStart` 时注入 `__SUBAGENT_MARKER__...`，以便 AI gateway 推导 `x-initiator: agent`。\n- `tool-search` 会注册用于 GPT Responses deferred tool loading 的 `tool_search` MCP bridge。\n\n- 本仓库中的 marketplace catalog：`.claude-plugin/marketplace.json`\n- 本仓库中的插件源码：`plugin/claude/agent-inject`、`plugin/claude/tool-search`\n\n远程添加 marketplace：\n\n```sh\n/plugin marketplace add https://github.com/caozhiyuan/copilot-api.git\n```\n\n从 marketplace 安装插件：\n\n```sh\n/plugin install agent-inject@copilot-api-marketplace\n/plugin install tool-search@copilot-api-marketplace\n```\n\n安装后，`agent-inject` 会在 `SubagentStart` 时注入 `__SUBAGENT_MARKER__...`，AI gateway 会利用它推导 `x-initiator: agent`。\n\n`agent-inject` 还会注册一个 `UserPromptSubmit` hook，并返回 `{\"continue\": true}`；同时它也可以通过环境变量注入 `SessionStart` reminder 规则：\n\n- `CLAUDE_PLUGIN_ENABLE_QUESTION_RULES=1` 会自动为 Claude Code 启用两条关于使用 `question` 工具的提醒。你也可以把同样的提醒手动写进 `CLAUDE.md`；见 [CLAUDE.md 或 AGENTS.md 推荐内容](#claudemd-or-agentsmd-recommended-content)。\n- `CLAUDE_PLUGIN_ENABLE_NO_BACKGROUND_AGENTS_RULE=1` 会启用关于避免在 agent hooks 中使用 `run_in_background: true` 的提醒。\n\n`tool-search` 插件内置了 [GPT Tool Search](#gpt-tool-search) 一节描述的同一个 MCP bridge，因此安装该插件后，Claude Code 用户无需再手动配置 `tool_search` server。\n\n#### Opencode 插件\n\nsubagent 标记生成器被打包为一个 opencode 插件，位于 `plugin/opencode/subagent-marker.js`。\n\n**安装方式：**\n\n将插件文件复制到你的 opencode 插件目录：\n\n```sh\n# 克隆或下载本仓库后复制该插件\ncp plugin/opencode/subagent-marker.js ~/.config/opencode/plugins/\n```\n\n或者手动在 `~/.config/opencode/plugins/subagent-marker.js` 创建该文件，并填入插件内容。\n\n**功能：**\n\n- 跟踪 subagent 创建的子会话\n- 自动在 subagent 聊天消息前添加 marker system reminder（`__SUBAGENT_MARKER__...`）\n- 设置 `x-session-id` 请求头以跟踪会话\n- 让这个 AI gateway 能够把来自 subagent 的请求识别为 `x-initiator: agent`\n\n该插件会挂接到 `session.created`、`session.deleted`、`chat.message` 和 `chat.headers` 事件上，以无缝提供 subagent marker 能力。\n\n## 使用量查看器\n\n服务启动后，控制台会输出一个 Copilot 使用量看板 URL。这个看板是一个用于监控 API 用量的 Web 界面。\n\n1. 启动服务。例如使用 npx：\n   ```sh\n   npx @jeffreycao/copilot-api@latest start\n   ```\n2. 服务会输出一个 usage viewer 的 URL。将它复制到浏览器中打开，形式大致如下：\n   `http://localhost:4141/usage-viewer?endpoint=http://localhost:4141/usage`\n   - 如果你在 Windows 上使用 `start.bat` 脚本，这个页面会自动打开。\n\n看板提供了更易读的 Copilot 用量视图：\n\n> token usage 历史记录需要 Bun 或 Node.js >= 22.13.0。Node.js < 22.13.0 时服务会正常运行，但 token usage 存储会被禁用。\n\n- **API Endpoint URL**：通过 URL 查询参数指定 API endpoints，默认指向本地服务。支持手动切换为其他兼容 endpoints。\n- **x-api-key 认证**：如果启用了 API Key 认证，可填入 `x-api-key` 请求头。密钥会持久化保存在浏览器本地存储中。\n- **Period 选择器**：支持 Day / Week / Month 三种时间范围，切换时 URL 参数会自动同步，方便收藏和分享。\n- **Fetch Data**：点击 \"Refresh\" 按钮加载或刷新使用数据。页面加载时也会自动拉取数据。\n- **Copilot Quotas 额度**：通过进度条展示 Chat、Completions 等不同服务的额度使用情况，悬停可查看已用/剩余详情。\n- **Token Usage 指标卡片**：汇总当前周期的 Total、Input、Output、Cache Read、Cache Write、Requests 和预估费用。\n- **趋势图（Week / Month）**：提供按模型和指标筛选的折线趋势图，点击数据点可查看单日用量明细。\n- **Model Breakdown 表格**：按模型维度列出周期内的请求数、输入/输出/缓存 token 和预计费用。\n- **Request Events 分页列表**：按时间排序的请求事件记录，支持分页浏览，含时间戳、模型、请求 ID 和 token 用量。\n- **Detailed Information**：展示 API 返回的完整 JSON 响应，便于深入分析所有可用统计数据。\n- **URL-based Configuration**：也可通过 `endpoint` 和 `period` 查询参数直接指定 API 端点与时间范围。例如：\n  `http://localhost:4141/usage-viewer?endpoint=http://your-api-server/usage&period=week`\n\n### Usage Viewer 截图\n\n<p align=\"center\">\n  <img src=\"./docs/screenshots/usage-viewer.png\" alt=\"Copilot API Usage Viewer 页面\" width=\"900\" />\n</p>\n\n## 命令结构\n\nCopilot API 现在使用子命令结构，主要命令包括：\n\n- `start`：启动 AI gateway 服务。如果已有 GitHub token，则启用 Copilot 路径；如果没有 GitHub token，但存在至少一个启用中的 provider，则按 provider-only 模式启动；如果两者都没有，会引导你配置 provider。\n- `auth`：仅执行 provider 登录或配置流程，不启动服务。可用于 GitHub Copilot 登录、Codex OAuth，或第三方 provider API key 配置。\n- `debug`：显示诊断信息，包括版本、运行时详情、文件路径以及认证状态，便于排障与支持。\n\n## 命令行选项\n\n### 全局选项\n\n以下选项可用于任意子命令。若在子命令之前传入，请使用 `--key=value` 形式：\n\n| 选项 | 说明 | 默认值 | 别名 |\n| --- | --- | --- | --- |\n| --api-home | API home 目录路径（设置 `COPILOT_API_HOME`） | 无 | 无 |\n| --oauth-app | OAuth app 标识符（设置 `COPILOT_API_OAUTH_APP`） | 无 | 无 |\n| --enterprise-url | GitHub Enterprise URL（设置 `COPILOT_API_ENTERPRISE_URL`） | 无 | 无 |\n\n### Start 命令选项\n\n以下是 `start` 命令可用的命令行选项：\n\n| 选项 | 说明 | 默认值 | 别名 |\n| --- | --- | --- | --- |\n| --port | 监听端口 | 4141 | -p |\n| --verbose | 启用详细日志 | false | -v |\n| --github-token | 直接提供 GitHub token（必须通过 `auth` 子命令生成） | 无 | -g |\n| --claude-code | 生成一个使用 Copilot API 配置启动 Claude Code 的命令 | false | -c |\n| --show-token | 在获取和刷新时显示 GitHub 与 Copilot token | false | 无 |\n| --proxy-env | 从环境变量初始化代理 | false | 无 |\n\n### Auth 命令选项\n\n| 选项 | 说明 | 默认值 | 别名 |\n| --- | --- | --- | --- |\n| --provider | 要登录或配置的 provider（`copilot`、`codex`、`deepseek`、`dashscope`、`openrouter` 或 `custom`） | 交互选择 | 无 |\n| --verbose | 启用详细日志 | false | -v |\n| --show-token | 认证时显示 GitHub token | false | 无 |\n\n只有在需要启用 GitHub Copilot provider 时，才需要执行 `copilot-api auth login --provider copilot`。使用 `codex` 或第三方 provider-only 模式不要求配置 Copilot。\n\n使用 `copilot-api auth login --provider deepseek`、`--provider dashscope` 或 `--provider openrouter` 可以通过 CLI 快速新增或更新这些常用第三方 provider。DeepSeek 会提示输入掩码显示的 `apiKey`、provider `type`（默认 `anthropic`），以及默认 `https://api.deepseek.com/anthropic` 的 `baseUrl`。DashScope 会提示输入掩码显示的 `apiKey`、provider `type`（默认 `openai-compatible`）和预填默认值的 `baseUrl`。OpenRouter 只提示输入掩码显示的 `apiKey` 和预填默认值的 `baseUrl`，并固定写入 `type: \"anthropic\"`。配置并启用 provider 后，`copilot-api start` 可在没有 GitHub token 的情况下启动。\n\n使用 `copilot-api auth login --provider custom` 可以通过 CLI 新增或更新其他第三方 provider。命令会依次提示输入 provider name、项目支持的 type（`anthropic`、`openai-compatible` 或 `openai-responses`）、`baseUrl`、掩码显示的 `apiKey` 和 `authType`；`authType` 可保持 type 默认值，也可选择 `x-api-key` / `authorization`。\n\n### Debug 命令选项\n\n| 选项 | 说明 | 默认值 | 别名 |\n| --- | --- | --- | --- |\n| --json | 以 JSON 输出调试信息 | false | 无 |\n\n<a id=\"configuration-configjson\"></a>\n\n## 配置（config.json）\n\n- **位置：** Linux/macOS 为 `~/.local/share/copilot-api/config.json`，Windows 为 `%USERPROFILE%\\.local\\share\\copilot-api\\config.json`。\n- **默认结构：**\n  ```json\n  {\n    \"auth\": {\n      \"apiKeys\": [],\n      \"adminApiKey\": \"<startup 自动生成>\"\n    },\n    \"providers\": {},\n    \"modelMappings\": {},\n    \"extraPrompts\": {\n      \"gpt-5-mini\": \"<built-in exploration prompt>\",\n      \"gpt-5.3-codex\": \"<built-in commentary prompt>\",\n      \"gpt-5.4-mini\": \"<built-in commentary prompt>\",\n      \"gpt-5.4\": \"<built-in commentary prompt>\",\n      \"gpt-5.5\": \"<built-in commentary prompt>\"\n    },\n    \"smallModel\": \"gpt-5-mini\",\n    \"useResponsesApiContextManagement\": true,\n    \"modelResponsesApiCompactThresholds\": {\n      \"gpt-5.4\": 217600,\n      \"gpt-5.5\": 217600\n    },\n    \"modelReasoningEfforts\": {\n      \"gpt-5-mini\": \"low\",\n      \"gpt-5.3-codex\": \"xhigh\",\n      \"gpt-5.4-mini\": \"xhigh\",\n      \"gpt-5.4\": \"xhigh\",\n      \"gpt-5.5\": \"xhigh\"\n    },\n    \"useMessagesApi\": true,\n    \"useResponsesApiWebSocket\": true,\n    \"useResponsesApiWebSearch\": true,\n    \"messageApiWebSearchModel\": \"gpt-5-mini\"\n  }\n  ```\n- **auth.apiKeys：** 用于普通非 admin 路由的 API key。支持多个 key 轮换使用。请求可通过 `x-api-key: <key>` 或 `Authorization: Bearer <key>` 进行认证。若为空或省略，则普通路由的认证会被禁用。\n- **auth.adminApiKey：** 仅用于 `/admin/*` 路由的单个 admin key。若未配置，服务会在启动时自动生成一个随机 key，并回写到 `config.json`。它同样使用 `x-api-key` 或 `Authorization: Bearer` 这两种头，但普通 `auth.apiKeys` 不能访问 `/admin/*`。\n- **modelMappings：** 用于顶层 `POST /v1/messages`、`POST /v1/messages/count_tokens`、`POST /v1/responses` 和 `POST /v1/chat/completions` 请求的精确 `sourceModel -> targetModel` 重写映射，这几类接口共用同一份规则。省略该字段或保留为 `{}` 时，不会做模型重写。`source` 和 `target` 都必须是非空字符串。`target` 可以是普通模型 ID，也可以是 `provider/model` 形式的别名，例如 `dashscope/qwen3.6-plus`；重写发生在 provider alias 解析之前。这些映射不再按接口区分。`GET/POST /admin/config/model-mappings` 管理接口读写的也只有这个字段。\n- **extraPrompts：** `model -> prompt` 的映射。把 Anthropic 风格请求翻译给 Copilot 时，会将其附加到第一条 system prompt 后面。你可以借此为不同模型注入护栏或指引。缺失的默认项会自动补齐，但不会覆盖你自定义的 prompt。内置的 `gpt-5.3-codex` 和 `gpt-5.4` prompt 会启用带阶段感知的 commentary，让模型在工具调用或更深层推理前先发出简短的用户可见进度说明。\n- **providers：** 全局上游 provider 映射。每个 provider key（例如 `dashscope`）都会变成一个路由前缀（`/dashscope/v1/messages`）。支持 `type: \"anthropic\"`、`type: \"openai-compatible\"` 和 `type: \"openai-responses\"`。顶层客户端也可以在 `/v1/messages`、`/v1/messages/count_tokens`、`/v1/responses` 和 `/v1/chat/completions` 中使用 `model: \"dashscope/model-id\"`；AI gateway 会在转发上游前移除 `dashscope/` 前缀。`openai-compatible` provider 同时支持 chat 和 Messages 流程：`/v1/chat/completions` 会直连上游 `/v1/chat/completions`，而 `/v1/messages` 和 `/:provider/v1/messages` 会先翻译为上游 Chat Completions，再把响应翻译回 Anthropic Messages。`GET /v1/models` 会聚合已启用 provider 的模型，并以 `provider/model-id` 形式返回；单个 provider 的原始模型列表仍可使用 `GET /dashscope/v1/models`。\n  - `enabled`：可选，若省略则默认为 `true`。\n  - `baseUrl`：provider API 的基础 URL，不要带结尾的 endpoint。Anthropic provider 不要带 `/v1/messages`；OpenAI 兼容 provider 不要带 `/v1/chat/completions`；OpenAI Responses provider 不要带 `/v1/responses`。\n  - `apiKey`：作为上游凭据值使用；普通 provider 必须配置。\n  - `authType`：可选，控制 `apiKey` 如何发送到上游。普通 provider 支持 `x-api-key` 和 `authorization`。Anthropic provider 默认 `x-api-key`；OpenAI 兼容和 OpenAI Responses provider 默认 `authorization`。当设置为 `authorization` 时，代理会发送 `Authorization: Bearer <apiKey>`。`oauth2` 仅保留给内置 `codex` provider，并由 `auth login --provider codex` 自动写入。\n  - `pricingCurrency`：可选，provider 维度的 token 费用币种，例如 `USD` 或 `CNY`。快捷 provider 默认 DashScope、DeepSeek 为 `CNY`，Codex/OpenRouter 为 `USD`。费用按币种分别汇总，不做汇率换算。\n  - `models`：可选，按模型 ID 配置的映射。每个键为请求中的模型名，值支持：\n    - `temperature`：可选，当请求未指定时使用的默认温度。\n    - `topP`：可选，当请求未指定时使用的默认 `top_p`。\n    - `topK`：可选，当请求未指定时使用的默认 `top_k`。\n    - `extraBody`：可选，按模型合入上游请求体的动态字段；请求体显式同名字段优先。OpenAI 兼容 provider 可用它配置 `enable_thinking`、`preserve_thinking`、`reasoning_effort` 等字段。`thinking_budget` 是 OpenAI 兼容 provider 的特殊覆盖项：配置在 `extraBody` 后，会在 Anthropic `thinking.budget_tokens` 翻译之后强制写入，并覆盖请求派生出的预算值。\n    - `pricing`：可选，按模型配置 token 单价，币种使用 provider 的 `pricingCurrency`，单位为每 100 万 tokens。支持 `input`、`output`、`cachedInput`（隐式缓存读）、`explicitCachedInput`（显式缓存读）和 `cacheCreationInput`。如需按输入 token 总量分档，可用带 `maxInputTokens` 的 `tiers`。\n    - `contextCache`：可选，OpenAI 兼容 provider 默认 `true`，用于启用阿里云百炼/DashScope 的显式缓存（explicit context cache），会按其 Context Cache 格式在最多 4 个 content block 上注入 `cache_control: { \"type\": \"ephemeral\" }`。缓存断点策略与 opencode 主链路保持一致：前 2 条 system 消息 + 最后 2 条非 system 消息。标记字符串 content 时会把 `system` / `user` / `assistant` / `tool` 消息转换为 text content part 数组；已有数组 content 则标记最后一个 part。如果模型本身已经支持隐式缓存，或上游不支持该显式缓存扩展字段，可在模型配置中设为 `false`。\n    - `supportPdf`：可选，控制该模型是否支持 PDF/document content。默认 `false`，不支持时会把 PDF 转成提示文本；设为 `true` 时会把 PDF/document 转成 OpenAI Chat Completions 的 file part。\n    - `toolContentSupportType`：可选，配置该模型的 tool result content 支持能力，值为 `array`、`image`、`pdf` 的数组。provider 侧未配置时默认只发送 string tool content。若 `supportPdf` 为 `true` 但这里不包含 `pdf`，tool result 里的 file part 会被转成 user role 消息。Copilot 主链路不使用这个 provider 默认，仍按 array + image 且不支持 PDF 的能力处理。\n\n  DashScope 模型配置示例：\n  ```json\n  {\n    \"providers\": {\n      \"dashscope\": {\n        \"type\": \"openai-compatible\",\n        \"enabled\": true,\n        \"baseUrl\": \"https://dashscope.aliyuncs.com/compatible-mode\",\n        \"apiKey\": \"sk-your-dashscope-key\",\n        \"pricingCurrency\": \"CNY\",\n        \"models\": {\n          \"qwen3.7-plus\": {\n            \"temperature\": 1,\n            \"topP\": 0.95,\n            \"topK\": 20,\n            \"extraBody\": {\n              \"preserve_thinking\": true\n            }\n          },\n          \"glm-5.1\": {\n            \"temperature\": 0.7,\n            \"topP\": 0.95,\n            \"contextCache\": true,\n            \"pricing\": {\n              \"tiers\": [\n                {\n                  \"maxInputTokens\": 32000,\n                  \"input\": 6,\n                  \"cachedInput\": 1.2,\n                  \"explicitCachedInput\": 0.6,\n                  \"cacheCreationInput\": 7.5,\n                  \"output\": 24\n                },\n                {\n                  \"maxInputTokens\": 200000,\n                  \"input\": 8,\n                  \"cachedInput\": 1.6,\n                  \"explicitCachedInput\": 0.8,\n                  \"cacheCreationInput\": 10,\n                  \"output\": 28\n                }\n              ]\n            },\n            \"extraBody\": {\n              \"preserve_thinking\": true\n            }\n          }\n        }\n      }\n    }\n  }\n  ```\n  内置 token 价格覆盖 Codex GPT 模型（USD）、DashScope `qwen3.7-max`、`qwen3.7-plus`、`glm-5.1`、`glm-5.2`（CNY），以及 DeepSeek `deepseek-v4-flash`、`deepseek-v4-pro`、`deepseek-chat`、`deepseek-reasoner`（CNY）。用户配置的 `pricing` 优先于内置价格。DashScope 若上游 usage 中出现 `cache_creation_input_tokens` 字段，cached tokens 按显式缓存读价计费；否则 `cachedInput` 作为隐式缓存读价。DeepSeek 的 `prompt_cache_hit_tokens` 会归入 cached input，`prompt_cache_miss_tokens` 会归入普通 input。\n- **smallModel：** 无工具预热消息的回退模型（例如 Claude Code 的探测请求）；默认是 `gpt-5-mini`。\n- **useResponsesApiContextManagement：** 当为 `true` 时，代理会为 Responses API 附加 `context_management` 压缩指令。默认值为 `true`。如需全局关闭，可设为 `false`。启用后，请求体会带上 `context_management`，并在后续轮次中仅保留最新的压缩承载内容，因此特别适合长任务场景。\n- **modelResponsesApiCompactThresholds：** 按模型覆盖 Responses API 的 `compact_threshold`，仅在代理自动附加 `context_management` 时使用。它的优先级高于 `resolveResponsesCompactThreshold` 基于 `max_prompt_tokens * ratio` 的兜底阈值。默认将 `gpt-5.4` 和 `gpt-5.5` 设为 `217600`（`272000 * 0.8`）。未列出的模型继续使用原有兜底逻辑。\n- **modelReasoningEfforts：** 按模型配置发送到 Copilot Responses API 的 `reasoning.effort`。可选值包括 `none`、`minimal`、`low`、`medium`、`high` 和 `xhigh`。若某模型未配置，则默认使用 `high`。\n- **useMessagesApi：** 当为 `true` 时，支持 Copilot 原生 `/v1/messages` 的 Claude 系模型会走 Messages API；否则回退到 `/chat/completions`。设为 `false` 可禁用 Messages API 路由，始终使用 `/chat/completions`。默认值为 `true`。\n- **useResponsesApiWebSocket：** 当为 `true` 时，Responses API 请求会优先对声明了 `ws:/responses` 的模型使用 Copilot websocket transport；仅声明 `/responses` 的模型仍走 HTTP。设为 `false` 可禁用 websocket 路由，并在模型支持 `/responses` 时使用 HTTP `/responses`。默认值为 `true`。\n- **useResponsesApiWebSearch：** 当为 `true` 时，服务端会保留 Responses API 中 `type: \"web_search\"` 的工具并透传到上游。设为 `false` 则会从 `/responses` payload 中移除这些工具。默认值为 `true`。\n- **messageApiWebSearchModel：** 顶层 Copilot `/v1/messages` 请求只包含服务端 `web_search` 工具时使用的全局模型，默认值为 `gpt-5-mini`。如果该值是 `provider/model` 别名，请求会进入对应 provider 的 Messages API 路径，并在转发前移除 provider 前缀。对于 Copilot GPT 模型，web search 会通过 `/responses` 执行。混合 `web_search` 与自定义工具的场景暂不支持，服务端会移除 server-side `web_search`。\n- **claudeTokenMultiplier：** 用于 Claude `/v1/messages/count_tokens` 请求在本地走 GPT tokenizer 估算时的乘数。默认值为 `1.15`。如果你的客户端仍然过晚触发上下文压缩，可以适当调大。这个配置只会在代理本地估算 Claude token 时生效；如果已经配置 `anthropicApiKey` 且 Anthropic token counting 调用成功，则会直接返回 Anthropic 的精确计数，不会使用这个乘数。\n- **anthropicApiKey：** 用于把 Claude `/v1/messages/count_tokens` 请求转发到 Anthropic 真实 token counting 端点的 API key，这样会返回精确计数，而不是 GPT tokenizer 估算值。也可通过环境变量 `ANTHROPIC_API_KEY` 设置。若未配置，或上游调用失败，则回退到由 `claudeTokenMultiplier` 控制的本地 GPT tokenizer 估算。\n\n编辑此文件后即可自定义 prompts，或替换为你自己的快速模型。修改完成后请重启服务（或重新执行命令），让缓存中的配置刷新生效。\n\n## API 认证\n\n- **受保护的普通路由：** 当配置了 `auth.apiKeys` 且非空时，除 `/`、`/usage-viewer` 和 `/usage-viewer/` 以外的普通路由都需要认证。\n- **Admin 路由：** 所有 `/admin/*` 路由都要求 `auth.adminApiKey`。如果缺失，服务会在启动时自动生成并在开始提供服务前写回 `config.json`。\n- **允许的认证头：**\n  - `x-api-key: <your_key>`\n  - `Authorization: Bearer <your_key>`\n- **CORS 预检：** `OPTIONS` 请求始终允许。\n- **未配置普通 key 时：** 普通路由仍可直接访问；但这条规则不适用于 `/admin/*`，后者只接受 `auth.adminApiKey`。\n\n普通受保护路由的示例请求：\n\n```sh\ncurl http://localhost:4141/v1/models \\\n  -H \"x-api-key: your_api_key\"\n```\n\nAdmin 路由的示例请求：\n\n```sh\ncurl http://localhost:4141/admin/config/model-mappings \\\n  -H \"x-api-key: your_admin_api_key\"\n```\n\n## API 端点\n\n服务端提供多个 OpenAI / Anthropic 兼容端点。请求会根据所选模型和 `provider/model` 别名路由到 GitHub Copilot、内置 `codex` provider 或已配置的 provider。\n\n### OpenAI 兼容端点\n\n这些端点模拟 OpenAI API 结构。\n\n| 端点 | 方法 | 说明 |\n| --- | --- | --- |\n| `POST /v1/responses` | `POST` | OpenAI 中用于生成模型响应的高级接口。支持 `openai-responses` provider 的 `provider/model` 别名。 |\n| `POST /v1/chat/completions` | `POST` | 为给定聊天对话创建模型响应。支持 `openai-compatible` provider 的 `provider/model` 别名；目标 provider 已配置时可在没有 Copilot 的情况下使用。 |\n| `GET /v1/models` | `GET` | 列出 Copilot 模型以及已启用 provider 的 `provider/model-id` 模型。 |\n| `POST /v1/embeddings` | `POST` | 创建表示输入文本的向量嵌入。 |\n\n### Anthropic 兼容端点\n\n这些端点设计为兼容 Anthropic Messages API。\n\n| 端点 | 方法 | 说明 |\n| --- | --- | --- |\n| `POST /v1/messages` | `POST` | 为给定对话创建模型响应。支持已配置 provider 的 `provider/model` 别名，包括通过 `openai-compatible` provider 做翻译。 |\n| `POST /v1/messages/count_tokens` | `POST` | 计算一组消息的 token 数。支持已配置 provider 的 `provider/model` 别名。 |\n| `POST /:provider/v1/messages` | `POST` | 将 Anthropic Messages 请求代理到已配置的 Anthropic provider，或翻译到 OpenAI 兼容 / OpenAI Responses provider。 |\n| `GET /:provider/v1/models` | `GET` | 将模型列表请求代理到已配置的 provider。 |\n| `POST /:provider/v1/messages/count_tokens` | `POST` | 为 provider 路由请求在本地计算 token 数。 |\n\n### 使用量监控端点\n\n用于监控 Copilot 用量与额度的新端点。\n\n| 端点 | 方法 | 说明 |\n| --- | --- | --- |\n| `GET /usage` | `GET` | 获取详细的 Copilot 使用统计与额度信息。 |\n| `GET /token` | `GET` | 获取当前 API 正在使用的 Copilot token。 |\n\n### Admin / 配置端点\n\n这些端点用于本地管理操作，只接受 `auth.adminApiKey`。\n\n| 端点 | 方法 | 说明 |\n| --- | --- | --- |\n| `GET /admin/config/model-mappings` | `GET` | 返回当前 `config.json` 路径以及生效中的 `modelMappings` 映射。 |\n| `POST /admin/config/model-mappings` | `POST` | 只更新 `config.json` 里的 `modelMappings` 字段，并回传更新后的结果。 |\n\n## 使用示例\n\n常用 `npx` 命令：\n\n```sh\n# 基础启动\nnpx @jeffreycao/copilot-api@latest start\n\n# 自定义端口并开启详细日志\nnpx @jeffreycao/copilot-api@latest start --port 8080 --verbose\n\n# 执行认证流程\nnpx @jeffreycao/copilot-api@latest auth login\n\n# 配置第三方 provider，然后不依赖 GitHub Copilot 启动\nnpx @jeffreycao/copilot-api@latest auth login --provider dashscope\nnpx @jeffreycao/copilot-api@latest start\n\n# 以 JSON 格式输出调试信息\nnpx @jeffreycao/copilot-api@latest debug --json\n\n# 用 Bun 而不是 Node.js 运行已发布 CLI\nbunx --bun @jeffreycao/copilot-api@latest start\n```\n\n配置 `dashscope` 后的 OpenAI 兼容 provider 调用示例：\n\n```sh\ncurl http://localhost:4141/v1/chat/completions \\\n  -H \"content-type: application/json\" \\\n  -d '{\"model\":\"dashscope/qwen3.6-plus\",\"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]}'\n\ncurl http://localhost:4141/dashscope/v1/messages \\\n  -H \"content-type: application/json\" \\\n  -d '{\"model\":\"qwen3.6-plus\",\"max_tokens\":1024,\"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]}'\n```\n\n## 使用建议\n\n<a id=\"claudemd-or-agentsmd-recommended-content\"></a>\n\n### CLAUDE.md 或 AGENTS.md 推荐内容\n\n如果你想手动加入这些提醒，请在 Claude Code 的 `CLAUDE.md`，或 opencode/codex 的 `AGENTS.md` 中加入以下内容：\n\n```\n- Prohibited from directly asking questions to users, MUST use question tool.\n- Once you can confirm that the task is complete, MUST use question tool to make user confirm. The user may respond with feedback if they are not satisfied with the result, which you can use to make improvements and try again, after try again, MUST use question tool to make user confirm again.\n```\n"}, "ac60b4a65190a187bf5c6adac48733543576b18b": {"t": 1786067819.0276897, "n": 34198, "h": "8f838c93da5f38b0", "c": "# Copilot API Proxy\n\n[English](./README.md) | 简体中文\n\n## 重要说明\n\n> [!IMPORTANT]\n> **使用前请先注意以下几点：**\n>\n> 1. **Claude Code 配置：** 与 Claude Code 搭配使用时，请将模型 ID 配置为 `claude-opus-4-8`。示例 claude `settings.json` 见 [通过 `settings.json` 手动配置](#manual-configuration-with-settingsjson)。\n>\n> 2. **内置 `copilot`、`codex` 与第三方 provider：** 执行 `npx @jeffreycao/copilot-api@latest auth`，可选择 `copilot`、`codex`、`deepseek`、`custom` 等 provider。\n>\n> 3. **注意事项：** README 顶部移除的 GitHub Copilot warning 见 [GitHub Copilot 安全提示](./NOTICE.md#github-copilot-security-notice)。\n\n---\n\n## 项目概览\n\n这是一个小型 AI gateway，可以使用 GitHub Copilot、内置 `codex` provider，也可以使用 DashScope 等已配置的第三方 provider。GitHub Copilot 现在是可选能力：如果本地没有 GitHub token，只要至少配置了一个启用中的 provider，服务仍可按 provider-only 模式启动。\n\nAI gateway 会从同一个本地端点暴露 OpenAI / Anthropic 兼容 API，让 [Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview)、OpenCode、Codex 和 OpenAI 兼容客户端可以共用同一个本地服务。\n\n在 GitHub Copilot 路径上，AI gateway 会在可用时优先使用 Copilot 原生的 Anthropic 风格 Messages API，在重工具调用场景下保留更原生的 Claude 行为。\n\n## 功能特性\n\n- **OpenAI 与 Anthropic 双兼容**：通过 `/v1/responses`、`/v1/chat/completions`、`/v1/models`、`/v1/embeddings` 和 `/v1/messages` 对外暴露同一个本地 AI gateway。\n- **Copilot 可选**：有 GitHub 凭据时可以使用 GitHub Copilot，没有 GitHub 凭据时也可以只依赖已配置的 provider 运行。\n- **同一网关接入 Copilot、`codex` 与第三方 provider**：可统一路由 GitHub Copilot、内置 `codex` provider 和配置好的外部 provider。\n- **第三方 provider 可独立启动**：配置 DashScope、DeepSeek、OpenRouter 或自定义 provider 后，不需要 GitHub Copilot 登录即可启动 AI gateway。\n- **OpenAI 兼容 provider 同时支持 chat 和 Messages API**：`openai-compatible` provider 可通过顶层 `/v1/chat/completions` 搭配 `model: \"provider/model\"` 提供 Chat Completions，也可通过 `/v1/messages` 完成 Anthropic Messages 的请求/响应翻译。\n- **面向 Claude 的更原生 Copilot 路由**：优先使用原生 `/v1/messages`，保留 Claude 风格工具流，支持 Anthropic beta 能力、通过 Responses-capable 模型支持 Claude WebSearch，并保留 subagent / session 标记。\n- **Claude Code 与 OpenCode 集成**：兼容 Claude Code 与 OpenCode，也支持通过 `@ai-sdk/anthropic` 直接作为 Anthropic provider 使用。\n- **灵活的认证与部署选项**：支持交互式登录、直接 token、个人 / Business / Enterprise、GitHub Enterprise、opencode OAuth 和自定义数据目录。\n- **多 provider 路由**：可暴露 `/:provider/...` 路由，也可在顶层 API 上使用 `model: \"provider/model\"`。\n\n## 前置要求\n\n- Bun（>= 1.2.x）\n- 如果要通过 `npx` 运行已发布 CLI，需要 Node.js\n- 只有在使用 GitHub Copilot provider 时，才需要已订阅 Copilot 的 GitHub 账号\n- 如果不使用 GitHub Copilot，需要至少一个已配置 provider 的 API key 或 OAuth 登录\n\n## 安装\n\n安装依赖：\n\n```sh\nbun install\n```\n\n直接从源码启动服务：\n\n```sh\nbun run start start\n```\n\n## 从源码运行\n\n本项目可以通过多种方式从源码运行：\n\n### 开发模式\n\n```sh\nbun run dev start\n```\n\n### 生产模式\n\n```sh\nbun run start start\n```\n\n## 通过 npx 使用\n\n你可以直接用 npx 运行本项目：\n\n> [!IMPORTANT]\n> 通过 `npx` 运行时，token usage 存储会使用 Node 内置的 `node:sqlite` 模块。该能力会在 Node.js >= 22.13.0 时启用；Node.js < 22.13.0 时 CLI 仍可启动，但会禁用 token usage 存储。\n>\n> 如果不升级 Node.js 但仍需要 token usage 存储，可以改用 Bun 运行已发布 CLI：`bunx --bun @jeffreycao/copilot-api@latest start`。\n\n```sh\nnpx @jeffreycao/copilot-api@latest start\n```\n\n带参数示例：\n\n```sh\nnpx @jeffreycao/copilot-api@latest start --port 8080\n```\n\n如果只想做认证或 provider 配置：\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth\n```\n\n如果要不依赖 GitHub Copilot 运行，先配置至少一个 provider，然后正常启动服务：\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth login --provider dashscope\nnpx @jeffreycao/copilot-api@latest start\n```\n\n## 配合 Docker 使用\n\n构建镜像：\n\n```sh\ndocker build -t copilot-api .\n```\n\n通过 bind mount 运行容器，让认证数据在重启后保留：\n\n```sh\nmkdir -p ./copilot-data\ndocker run -p 4141:4141 -v $(pwd)/copilot-data:/root/.local/share/copilot-api copilot-api\n```\n\n这会把宿主机上的 `./copilot-data` 映射到容器内的 `/root/.local/share/copilot-api`，用于持久化 GitHub 认证数据、provider 配置和其他 gateway 状态。\n\n也可以直接通过环境变量传入 GitHub token：\n\n```sh\ndocker run -p 4141:4141 -e GH_TOKEN=your_github_token_here copilot-api\n```\n\n## Electron 桌面应用\n\n如果你更喜欢图形界面，仓库里还提供了位于 `desktop/` 的 Electron 桌面应用。它支持 GitHub Copilot 登录、OpenAI Codex OAuth，以及 DeepSeek、DashScope、OpenRouter 或自定义 provider 的 API Key 配置。授权或配置 provider 后，可以一键启动或停止本地代理，并在界面里直接查看本地端点、鉴权 Header、可用模型、额度和日志。\n\n设置页还可以配置 `OAuth App`、`API Home`、`Enterprise URL`、详细日志以及最小化到托盘。Windows x64（`.exe`）、macOS Apple Silicon（`.dmg`）和 Linux x64（`.AppImage`）安装包发布在 GitHub Releases：\n\nhttps://github.com/caozhiyuan/copilot-api/releases\n\nLinux 用户需要先为下载的 AppImage 添加执行权限：\n\n```sh\nchmod +x Copilot-API-*-linux-x86_64.AppImage\n./Copilot-API-*-linux-x86_64.AppImage\n```\n\n下载对应平台的安装包后，在应用内授权或配置 provider，选择端口并启动服务，再把你的客户端指向应用里显示的本地端点即可。发布版桌面应用使用随包内置的 Electron 运行时，正常使用不需要额外安装 Node.js；token usage 历史记录会在该内置运行时支持 SQLite 时启用。\n\n桌面应用里的高级配置页会通过 `GET/POST /admin/config/model-mappings` 读写这份共享的模型映射。同一份映射会统一作用于 `POST /v1/messages`、`POST /v1/messages/count_tokens`、`POST /v1/responses` 和 `POST /v1/chat/completions`，不再按接口区分。它使用的是 `auth.adminApiKey`，不是普通的 `auth.apiKeys`；应用会在服务启动并自动生成该 key 后，直接从 `config.json` 读取它来发起请求。\n\n### 桌面应用截图\n\n下面展示了桌面应用中的首页、Token 用量统计页面：\n\n<p align=\"center\">\n  <img src=\"./docs/screenshots/desktop-dashboard.png\" alt=\"Copilot API 桌面应用首页\" width=\"49%\" />\n  <img src=\"./docs/screenshots/desktop-token-usage.png\" alt=\"Copilot API 桌面应用 Token 用量页\" width=\"49%\" />\n</p>\n\n## 与 Claude Code 一起使用\n\n这个 AI gateway 可以为 [Claude Code](https://docs.anthropic.com/en/claude-code) 提供后端能力。Claude Code 是 Anthropic 提供的实验性面向开发者的对话式 AI 助手。\n\n有两种方式可以把 Claude Code 配置为使用这个 AI gateway：\n\n### 通过 `--claude-code` 标志进行交互式配置\n\n执行带 `--claude-code` 的 `start` 命令开始：\n\n```sh\nnpx @jeffreycao/copilot-api@latest start --claude-code\n```\n\n你不再需要手动选择模型。Gateway 会自动检测每个 Claude Code 尺寸档位对应的最新可用模型——opus 映射到最新的 Opus 模型，sonnet 映射到最新的 Sonnet 模型，haiku 映射到最新的 Haiku 模型——并生成相应设置 `ANTHROPIC_DEFAULT_OPUS_MODEL`、`ANTHROPIC_DEFAULT_SONNET_MODEL` 和 `ANTHROPIC_DEFAULT_HAIKU_MODEL` 的命令。若某个档位没有匹配的可用模型，则会被省略。该命令会被复制到剪贴板，并设置 Claude Code 使用这个 AI gateway 所需的环境变量。\n\n在新的终端中粘贴并执行这条命令，即可启动 Claude Code。\n\n<a id=\"manual-configuration-with-settingsjson\"></a>\n\n### 通过 `settings.json` 手动配置\n\n另一种方式是在项目根目录中创建 `.claude/settings.json` 文件，并写入 Claude Code 所需的环境变量。这样你就不需要每次都运行交互式配置了。\n\n下面是一个 `.claude/settings.json` 示例：\n\n```json\n{\n  \"env\": {\n    \"ANTHROPIC_BASE_URL\": \"http://localhost:4141\",\n    \"ANTHROPIC_AUTH_TOKEN\": \"dummy\",\n    \"ANTHROPIC_MODEL\": \"gpt-5.6-sol[1m]\",\n    \"ANTHROPIC_DEFAULT_SONNET_MODEL\": \"gpt-5.6-sol[1m]\",\n    \"ANTHROPIC_DEFAULT_HAIKU_MODEL\": \"gpt-5.6-luna[1m]\",\n    \"CLAUDE_CODE_AUTO_COMPACT_WINDOW\": \"272000\",\n    \"CLAUDE_CODE_USE_VERTEX\": \"0\",\n    \"CLAUDE_CODE_USE_BEDROCK\": \"0\",\n    \"DISABLE_NON_ESSENTIAL_MODEL_CALLS\": \"1\",\n    \"CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC\": \"1\",\n    \"CLAUDE_CODE_ATTRIBUTION_HEADER\": \"0\",\n    \"CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION\": \"false\",\n    \"CLAUDE_CODE_DISABLE_TERMINAL_TITLE\": \"true\",\n    \"CLAUDE_CODE_ENABLE_AWAY_SUMMARY\": \"0\"\n  },\n  \"alwaysThinkingEnabled\": true,\n  \"effortLevel\": \"xhigh\",\n  \"showThinkingSummaries\": true\n}\n```\n\n- 请根据需要替换 `ANTHROPIC_MODEL`、`ANTHROPIC_DEFAULT_OPUS_MODEL`、`ANTHROPIC_DEFAULT_SONNET_MODEL` 和 `ANTHROPIC_DEFAULT_HAIKU_MODEL`。配置完成后，请安装 claude code 插件，见 [插件集成](#plugin-integrations)。\n- 如果你使用的是 codex provider，建议**不要**将模型名配置成 `codex/xxx` 格式（如 `codex/gpt-5.6-sol`）。Claude Code 会针对 `codex/` 前缀做降智行为——例如每次请求时移除所有之前返回的思考块（thinking blocks）。请使用纯模型名（如 `gpt-5.6-sol`），并在 `config.json` 中配置 `modelMappings` 将其映射回 codex provider：\n  ```json\n  \"modelMappings\": {\n    \"gpt-5.6-sol\": \"codex/gpt-5.6-sol\",\n    \"gpt-5.6-terra\": \"codex/gpt-5.6-terra\",\n    \"gpt-5.6-luna\": \"codex/gpt-5.6-luna\"\n  },\n  ```\n- 将 `CLAUDE_CODE_ATTRIBUTION_HEADER` 设为 `0` 可以阻止 Claude Code 在 system prompt 中附加计费和版本信息，从而避免 prompt cache 失效。\n- 关闭 `CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION` 和 `CLAUDE_CODE_ENABLE_AWAY_SUMMARY` 可以避免不必要地消耗额度。\n- Claude Code WebSearch 已支持纯搜索请求。Copilot 路径请保持全局 `messageApiWebSearchModel` 指向 Responses-capable GPT 模型或 `provider/model` 别名；provider 路由请使用原生 Anthropic provider 或 `openai-responses` provider。只有在你明确想禁止这类流量时，才需要把 `WebSearch` 加到 `permissions.deny`。\n- 如果使用的不是 Claude 模型，请不要启用 `ENABLE_TOOL_SEARCH`。如果使用的是 Claude 模型，则可以启用 `ENABLE_TOOL_SEARCH`。当前 Claude Code 使用的是客户端 tool search 模式，在该模式下每次加载 defer tools 都需要额外请求一次。\n- `CLAUDE_CODE_AUTO_COMPACT_WINDOW`：设置用于自动压缩计算的上下文容量（以 token 为单位）。默认使用模型自身的上下文窗口：标准模型为 200K，扩展上下文模型为 1M。使用 1M 上下文模型（如 `claude-opus-4-6[1m]`）时，可设置一个较低的值（如 `500000`）将窗口视为 500K 用于压缩计算。该值受限于模型的实际上下文窗口上限。`CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` 会基于此值的百分比生效。设置此变量可将压缩阈值与状态栏的 `used_percentage` 解耦（后者始终使用模型的完整上下文窗口）。\n\n更多选项见：[Claude Code settings](https://docs.anthropic.com/en/docs/claude-code/settings#environment-variables)\n\n也可以参考 IDE 集成说明：[Add Claude Code to your IDE](https://docs.anthropic.com/en/docs/claude-code/ide-integrations)\n\n## 与 OpenCode 一起使用\n\nOpenCode 已经有直接的 GitHub Copilot provider。本节适用于你希望让 OpenCode 通过 `@ai-sdk/anthropic` 指向这个 AI gateway，并复用本 README 前面提到的 agent 行为时。\n\n### 最小配置\n\n使用 OpenCode OAuth app 启动 AI gateway：\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth --oauth-app=opencode\nnpx @jeffreycao/copilot-api@latest start\n```\n\n然后让 OpenCode 通过 `@ai-sdk/anthropic` 指向这个 AI gateway。\n\n示例 `~/.config/opencode/opencode.json`：\n\n```json\n{\n  \"$schema\": \"https://opencode.ai/config.json\",\n  \"provider\": {\n    \"local\": {\n      \"npm\": \"@ai-sdk/anthropic\",\n      \"name\": \"My Local\",\n      \"options\": {\n        \"baseURL\": \"http://localhost:4141/v1\",\n        \"apiKey\": \"dummy\"\n      },\n      \"models\": {\n        \"gpt-5.4\": {\n          \"name\": \"gpt-5.4\",\n          \"modalities\": {\n            \"input\": [\"text\", \"image\"],\n            \"output\": [\"text\"]\n          },\n          \"limit\": {\n            \"context\": 400000,\n            \"input\": 272000,\n            \"output\": 128000\n          }\n        },\n        \"claude-sonnet-4.6\": {\n          \"id\": \"claude-sonnet-4.6\",\n          \"name\": \"claude-sonnet-4.6\",\n          \"modalities\": {\n            \"input\": [\"text\", \"image\"],\n            \"output\": [\"text\"]\n          },\n          \"limit\": {\n            \"context\": 200000,\n            \"output\": 32000\n          },\n          \"options\": {\n            \"thinking\": {\n              \"type\": \"adaptive\"\n            },\n            \"effort\": \"max\"\n          }\n        }\n      }\n    }\n  }\n}\n```\n\n这些字段的重要性：\n\n- `npm: \"@ai-sdk/anthropic\"` 是关键。OpenCode 会以 Anthropic Messages 语义与这个 AI gateway 通信，而不是把一切扁平化为 OpenAI Chat Completions。\n- `options.baseURL` 应设为 `http://localhost:4141/v1`；Anthropic SDK 会自动补上 `/messages`、`/models` 和 `/messages/count_tokens`。\n- 如果你在此代理中启用了 `auth.apiKeys`，请把 `dummy` 替换为真实 key；否则任意占位值都可以。\n\n## 与 Codex 一起使用\n\n这个 AI gateway 也可以为 Codex 提供后端能力。\n\n### Codex `config.toml` 参考配置\n\n把以下 `[model_providers.copilot_api]` 段加入你的 Codex `~/.codex/config.toml`：\n\n```toml\nmodel_provider = \"copilot_api\"\nmodel_reasoning_summary = \"auto\"\nmodel_context_window = 272000\nmodel_auto_compact_token_limit = 244800\n\n[model_providers.copilot_api]\nname = \"OpenAI\"\nbase_url = \"http://localhost:4141\"\nenv_key = \"GITHUB_COPILOT_API_KEY\"\nrequires_openai_auth = true\nsupports_websockets = false\nwire_api = \"responses\"\nrequest_max_retries = 3\nstream_max_retries = 1\nstream_idle_timeout_ms = 300000\n\n[features]\nremote_compaction_v2 = true\n\n[analytics]\nenabled = false\n```\n\n> [!NOTE]\n> 此配置仅限于 Codex 与 GitHub Copilot provider。`name` 一定要配置为 `\"OpenAI\"`。它可以缓解 Codex local compact 不命中缓存的问题。\n> 如果使用 codex provider，建议将 `base_url` 配置为 `\"http://localhost:4141/codex\"`。\n\n## GPT Tool Search\n\n对于 `gpt-5.4+` 这类 GPT Responses 模型，这个 AI gateway 可以通过一个很小的 MCP bridge 暴露 Responses `tool_search`。Claude Code 和 opencode 都可以使用同一个 bridge，前提是客户端会加载 MCP server，并且 Anthropic Messages 流量会经过这个 AI gateway。\n\nGPT 模型不要设置 Claude Code 原生的 `ENABLE_TOOL_SEARCH`。这个开关启用的是 Claude Code 自己的客户端 tool search 模式，可能导致 deferred 工具定义不再转发给 AI gateway。这个 AI gateway 需要完整的工具定义，这样才能只保留那一小组常驻加载工具，其余工具统一转换为 Responses deferred namespace。\n\n如果你安装了 `tool-search@copilot-api-marketplace`，Claude Code 会自动带上这个 MCP bridge，可以跳过下面这段 Claude Code MCP 手动配置。\n\n请把 tool search bridge 加到 Claude Code 使用的 MCP 配置中：\n\n```json\n{\n  \"mcpServers\": {\n    \"tool_search\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@jeffreycao/copilot-api@latest\", \"mcp\"]\n    }\n  }\n}\n```\n\n请把 tool search bridge 加到 opencode 使用的 MCP 配置中：\n\n```json\n{\n  \"mcp\": {\n    \"tool_search\": {\n      \"type\": \"local\",\n      \"command\": [\"npx\", \"-y\", \"@jeffreycao/copilot-api@latest\", \"mcp\"]\n    }\n  }\n}\n```\n\n本地开发时可以将命令换成 `bun`，参数换成 `[\"run\", \"./src/main.ts\", \"mcp\"]`。\n\nAI gateway 内部现在会把 OpenAI Responses `tool_search` 配置成 client-executed 模式。deferred tools 仍然会作为可搜索 namespace 暴露给模型，但会明确要求模型直接返回下一步要加载的精确工具名列表。\n\n该 bridge 使用直接工具选择，不做 query 搜索。工具入参是 `names`，值为逗号分隔的精确 deferred 工具名，例如 `TaskList,TaskGet,mcp__fetch__fetch`。\n\n<a id=\"plugin-integrations\"></a>\n\n## 插件集成\n\n本项目为 Claude Code 和 opencode 提供了插件集成。\n\n#### Claude Code 插件集成（基于 marketplace）\n\nClaude Code 集成现在拆分为两个插件：\n\n- `agent-inject` 会在 `SubagentStart` 时注入 `__SUBAGENT_MARKER__...`，以便 AI gateway 推导 `x-initiator: agent`。\n- `tool-search` 会注册用于 GPT Responses deferred tool loading 的 `tool_search` MCP bridge。\n\n- 本仓库中的 marketplace catalog：`.claude-plugin/marketplace.json`\n- 本仓库中的插件源码：`plugin/claude/agent-inject`、`plugin/claude/tool-search`\n\n远程添加 marketplace：\n\n```sh\n/plugin marketplace add https://github.com/caozhiyuan/copilot-api.git\n```\n\n从 marketplace 安装插件：\n\n```sh\n/plugin install agent-inject@copilot-api-marketplace\n/plugin install tool-search@copilot-api-marketplace\n```\n\n安装后，`agent-inject` 会在 `SubagentStart` 时注入 `__SUBAGENT_MARKER__...`，AI gateway 会利用它推导 `x-initiator: agent`。\n\n`agent-inject` 还会注册一个 `UserPromptSubmit` hook，并返回 `{\"continue\": true}`；同时它也可以通过环境变量注入 `SessionStart` reminder 规则：\n\n- `CLAUDE_PLUGIN_ENABLE_QUESTION_RULES=1` 会自动为 Claude Code 启用两条关于使用 `question` 工具的提醒。你也可以把同样的提醒手动写进 `CLAUDE.md`；见 [CLAUDE.md 或 AGENTS.md 推荐内容](#claudemd-or-agentsmd-recommended-content)。\n- `CLAUDE_PLUGIN_ENABLE_NO_BACKGROUND_AGENTS_RULE=1` 会启用关于避免在 agent hooks 中使用 `run_in_background: true` 的提醒。\n\n`tool-search` 插件内置了 [GPT Tool Search](#gpt-tool-search) 一节描述的同一个 MCP bridge，因此安装该插件后，Claude Code 用户无需再手动配置 `tool_search` server。\n\n#### Opencode 插件\n\nsubagent 标记生成器被打包为一个 opencode 插件，位于 `plugin/opencode/subagent-marker.js`。\n\n**安装方式：**\n\n将插件文件复制到你的 opencode 插件目录：\n\n```sh\n# 克隆或下载本仓库后复制该插件\ncp plugin/opencode/subagent-marker.js ~/.config/opencode/plugins/\n```\n\n或者手动在 `~/.config/opencode/plugins/subagent-marker.js` 创建该文件，并填入插件内容。\n\n**功能：**\n\n- 跟踪 subagent 创建的子会话\n- 自动在 subagent 聊天消息前添加 marker system reminder（`__SUBAGENT_MARKER__...`）\n- 设置 `x-session-id` 请求头以跟踪会话\n- 让这个 AI gateway 能够把来自 subagent 的请求识别为 `x-initiator: agent`\n\n该插件会挂接到 `session.created`、`session.deleted`、`chat.message` 和 `chat.headers` 事件上，以无缝提供 subagent marker 能力。\n\n## 使用量查看器\n\n服务启动后，控制台会输出一个 Copilot 使用量看板 URL。这个看板是一个用于监控 API 用量的 Web 界面。\n\n1. 启动服务。例如使用 npx：\n   ```sh\n   npx @jeffreycao/copilot-api@latest start\n   ```\n2. 服务会输出一个 usage viewer 的 URL。将它复制到浏览器中打开，形式大致如下：\n   `http://localhost:4141/usage-viewer?endpoint=http://localhost:4141/usage`\n   - 如果你在 Windows 上使用 `start.bat` 脚本，这个页面会自动打开。\n\n看板提供了更易读的 Copilot 用量视图：\n\n> token usage 历史记录需要 Bun 或 Node.js >= 22.13.0。Node.js < 22.13.0 时服务会正常运行，但 token usage 存储会被禁用。\n\n- **API Endpoint URL**：通过 URL 查询参数指定 API endpoints，默认指向本地服务。支持手动切换为其他兼容 endpoints。\n- **x-api-key 认证**：如果启用了 API Key 认证，可填入 `x-api-key` 请求头。密钥会持久化保存在浏览器本地存储中。\n- **Period 选择器**：支持 Day / Week / Month 三种时间范围，切换时 URL 参数会自动同步，方便收藏和分享。\n- **Fetch Data**：点击 \"Refresh\" 按钮加载或刷新使用数据。页面加载时也会自动拉取数据。\n- **Copilot Quotas 额度**：通过进度条展示 Chat、Completions 等不同服务的额度使用情况，悬停可查看已用/剩余详情。\n- **Token Usage 指标卡片**：汇总当前周期的 Total、Input、Output、Cache Read、Cache Write、Requests 和预估费用。\n- **趋势图（Week / Month）**：提供按模型和指标筛选的折线趋势图，点击数据点可查看单日用量明细。\n- **Model Breakdown 表格**：按模型维度列出周期内的请求数、输入/输出/缓存 token 和预计费用。\n- **Request Events 分页列表**：按时间排序的请求事件记录，支持分页浏览，含时间戳、模型、请求 ID 和 token 用量。\n- **Detailed Information**：展示 API 返回的完整 JSON 响应，便于深入分析所有可用统计数据。\n- **URL-based Configuration**：也可通过 `endpoint` 和 `period` 查询参数直接指定 API 端点与时间范围。例如：\n  `http://localhost:4141/usage-viewer?endpoint=http://your-api-server/usage&period=week`\n\n### Usage Viewer 截图\n\n<p align=\"center\">\n  <img src=\"./docs/screenshots/usage-viewer.png\" alt=\"Copilot API Usage Viewer 页面\" width=\"900\" />\n</p>\n\n## 命令结构\n\nCopilot API 现在使用子命令结构，主要命令包括：\n\n- `start`：启动 AI gateway 服务。如果已有 GitHub token，则启用 Copilot 路径；如果没有 GitHub token，但存在至少一个启用中的 provider，则按 provider-only 模式启动；如果两者都没有，会引导你配置 provider。\n- `auth`：仅执行 provider 登录或配置流程，不启动服务。可用于 GitHub Copilot 登录、Codex OAuth，或第三方 provider API key 配置。\n- `debug`：显示诊断信息，包括版本、运行时详情、文件路径以及认证状态，便于排障与支持。\n\n## 命令行选项\n\n### 全局选项\n\n以下选项可用于任意子命令。若在子命令之前传入，请使用 `--key=value` 形式：\n\n| 选项 | 说明 | 默认值 | 别名 |\n| --- | --- | --- | --- |\n| --api-home | API home 目录路径（设置 `COPILOT_API_HOME`） | 无 | 无 |\n| --oauth-app | OAuth app 标识符（设置 `COPILOT_API_OAUTH_APP`） | 无 | 无 |\n| --enterprise-url | GitHub Enterprise URL（设置 `COPILOT_API_ENTERPRISE_URL`） | 无 | 无 |\n\n### Start 命令选项\n\n以下是 `start` 命令可用的命令行选项：\n\n| 选项 | 说明 | 默认值 | 别名 |\n| --- | --- | --- | --- |\n| --port | 监听端口 | 4141 | -p |\n| --verbose | 启用详细日志 | false | -v |\n| --github-token | 直接提供 GitHub token（必须通过 `auth` 子命令生成） | 无 | -g |\n| --claude-code | 生成一个使用 Copilot API 配置启动 Claude Code 的命令 | false | -c |\n| --show-token | 在获取和刷新时显示 GitHub 与 Copilot token | false | 无 |\n| --proxy-env | 从环境变量初始化代理 | false | 无 |\n\n### Auth 命令选项\n\n| 选项 | 说明 | 默认值 | 别名 |\n| --- | --- | --- | --- |\n| --provider | 要登录或配置的 provider（`copilot`、`codex`、`opencode-go`、`deepseek`、`dashscope`、`openrouter` 或 `custom`） | 交互选择 | 无 |\n| --verbose | 启用详细日志 | false | -v |\n| --show-token | 认证时显示 GitHub token | false | 无 |\n\n只有在需要启用 GitHub Copilot provider 时，才需要执行 `copilot-api auth login --provider copilot`。使用 `codex` 或第三方 provider-only 模式不要求配置 Copilot。\n\n使用 `copilot-api auth login --provider deepseek`、`--provider dashscope`、`--provider openrouter` 或 `--provider opencode-go` 可以通过 CLI 快速新增或更新这些常用第三方 provider。DeepSeek 会提示输入掩码显示的 `apiKey`、provider `type`（默认 `anthropic`），以及默认 `https://api.deepseek.com/anthropic` 的 `baseUrl`。DashScope 会提示输入掩码显示的 `apiKey`、provider `type`（默认 `openai-compatible`）和预填默认值的 `baseUrl`。OpenRouter 只提示输入掩码显示的 `apiKey` 和预填默认值的 `baseUrl`，并固定写入 `type: \"anthropic\"`。OpenCode Go 只提示输入掩码显示的 `apiKey` 和预填默认值的 `baseUrl`，并固定写入 `type: \"openai-compatible\"`（baseUrl `https://opencode.ai/zen/go`）。配置并启用 provider 后，`copilot-api start` 可在没有 GitHub token 的情况下启动。\n\n使用 `copilot-api auth login --provider custom` 可以通过 CLI 新增或更新其他第三方 provider。命令会依次提示输入 provider name、项目支持的 type（`anthropic`、`openai-compatible` 或 `openai-responses`）、`baseUrl`、掩码显示的 `apiKey` 和 `authType`；`authType` 可保持 type 默认值，也可选择 `x-api-key` / `authorization`。\n\n### Debug 命令选项\n\n| 选项 | 说明 | 默认值 | 别名 |\n| --- | --- | --- | --- |\n| --json | 以 JSON 输出调试信息 | false | 无 |\n\n<a id=\"configuration-configjson\"></a>\n\n## 配置（config.json）\n\n- **位置：** Linux/macOS 为 `~/.local/share/copilot-api/config.json`，Windows 为 `%USERPROFILE%\\.local\\share\\copilot-api\\config.json`。\n- **默认结构：**\n  ```json\n  {\n    \"auth\": {\n      \"apiKeys\": [],\n      \"adminApiKey\": \"<startup 自动生成>\"\n    },\n    \"providers\": {},\n    \"modelMappings\": {},\n    \"extraPrompts\": {\n      \"gpt-5-mini\": \"<built-in exploration prompt>\"\n    },\n    \"smallModel\": \"gpt-5-mini\",\n    \"contextManagement\": {\n      \"messages\": true,\n      \"responses\": false\n    },\n    \"modelResponsesApiCompactThresholds\": {\n      \"gpt-5.4\": 217600,\n      \"gpt-5.5\": 217600,\n      \"gpt-5.6-sol\": 231200,\n      \"gpt-5.6-terra\": 231200,\n      \"gpt-5.6-luna\": 231200\n    },\n    \"modelReasoningEfforts\": {\n      \"gpt-5-mini\": \"low\"\n    },\n    \"useMessagesApi\": true,\n    \"useResponsesApiWebSocket\": true,\n    \"useResponsesApiWebSearch\": true,\n    \"messageApiWebSearchModel\": \"gpt-5-mini\"\n  }\n  ```\n- **auth.apiKeys：** 用于普通非 admin 路由的 API key。支持多个 key 轮换使用。请求可通过 `x-api-key: <key>` 或 `Authorization: Bearer <key>` 进行认证。若为空或省略，则普通路由的认证会被禁用。\n- **auth.adminApiKey：** 仅用于 `/admin/*` 路由的单个 admin key。若未配置，服务会在启动时自动生成一个随机 key，并回写到 `config.json`。它同样使用 `x-api-key` 或 `Authorization: Bearer` 这两种头，但普通 `auth.apiKeys` 不能访问 `/admin/*`。\n- **modelMappings：** 用于顶层 `POST /v1/messages`、`POST /v1/messages/count_tokens`、`POST /v1/responses` 和 `POST /v1/chat/completions` 请求的精确 `sourceModel -> targetModel` 重写映射，这几类接口共用同一份规则。省略该字段或保留为 `{}` 时，不会做模型重写。`source` 和 `target` 都必须是非空字符串。`target` 可以是普通模型 ID，也可以是 `provider/model` 形式的别名，例如 `dashscope/qwen3.6-plus`；重写发生在 provider alias 解析之前。这些映射不再按接口区分。`GET/POST /admin/config/model-mappings` 管理接口读写的也只有这个字段。\n- **extraPrompts：** `model -> prompt` 的映射。把 Anthropic 风格请求翻译为 Responses API 时，会将其附加到第一条 system prompt 后面。你可以借此为不同模型注入护栏或指引。缺失的默认项会自动补齐，但不会覆盖你自定义的 prompt。对于 GPT-5.3+ 模型（如 `gpt-5.3-codex`、`gpt-5.4`、`gpt-5.5`），未显式配置时会自动使用内置的 commentary prompt。内置 prompt 会启用带阶段感知的 commentary，让模型在工具调用或更深层推理前先发出简短的用户可见进度说明。\n- **providers：** 全局上游 provider 映射。每个 provider key（例如 `dashscope`）都会变成一个路由前缀（`/dashscope/v1/messages`）。支持 `type: \"anthropic\"`、`type: \"openai-compatible\"` 和 `type: \"openai-responses\"`。顶层客户端也可以在 `/v1/messages`、`/v1/messages/count_tokens`、`/v1/responses` 和 `/v1/chat/completions` 中使用 `model: \"dashscope/model-id\"`；AI gateway 会在转发上游前移除 `dashscope/` 前缀。`openai-compatible` provider 同时支持 chat 和 Messages 流程：`/v1/chat/completions` 会直连上游 `/v1/chat/completions`，而 `/v1/messages` 和 `/:provider/v1/messages` 会先翻译为上游 Chat Completions，再把响应翻译回 Anthropic Messages。`GET /v1/models` 会聚合已启用 provider 的模型，并以 `provider/model-id` 形式返回；单个 provider 的原始模型列表仍可使用 `GET /dashscope/v1/models`。\n  - `enabled`：可选，若省略则默认为 `true`。\n  - `baseUrl`：provider API 的基础 URL，不要带结尾的 endpoint。Anthropic provider 不要带 `/v1/messages`；OpenAI 兼容 provider 不要带 `/v1/chat/completions`；OpenAI Responses provider 不要带 `/v1/responses`。\n  - `apiKey`：作为上游凭据值使用；普通 provider 必须配置。\n  - `authType`：可选，控制 `apiKey` 如何发送到上游。普通 provider 支持 `x-api-key` 和 `authorization`。Anthropic provider 默认 `x-api-key`；OpenAI 兼容和 OpenAI Responses provider 默认 `authorization`。当设置为 `authorization` 时，代理会发送 `Authorization: Bearer <apiKey>`。`oauth2` 仅保留给内置 `codex` provider，并由 `auth login --provider codex` 自动写入。\n  - `pricingCurrency`：可选，provider 维度的 token 费用币种，例如 `USD` 或 `CNY`。快捷 provider 默认 DashScope、DeepSeek 为 `CNY`，Codex/OpenRouter 为 `USD`。费用按币种分别汇总，不做汇率换算。\n  - `models`：可选，按模型 ID 配置的映射。每个键为请求中的模型名，值支持：\n    - `temperature`：可选，当请求未指定时使用的默认温度。\n    - `topP`：可选，当请求未指定时使用的默认 `top_p`。\n    - `topK`：可选，当请求未指定时使用的默认 `top_k`。\n    - `extraBody`：可选，按模型合入上游请求体的动态字段；请求体显式同名字段优先。OpenAI 兼容 provider 可用它配置 `enable_thinking`、`preserve_thinking`、`reasoning_effort` 等字段。`thinking_budget` 是 OpenAI 兼容 provider 的特殊覆盖项：配置在 `extraBody` 后，会在 Anthropic `thinking.budget_tokens` 翻译之后强制写入，并覆盖请求派生出的预算值。对于 provider name 为 `dashscope` 或 `baseUrl` 包含 `aliyuncs.com` 的 provider，请求派生的 `thinking_budget`（来自 Anthropic `thinking.budget_tokens`）会转发给上游；其他 OpenAI 兼容 provider 会移除请求派生的 `thinking_budget`，但 `extraBody` 中的 `thinking_budget` 仍然生效。对于 DashScope provider，当 `preserve_thinking` 未在 `extraBody` 或请求体中显式设置时，默认为 `true`。\n    - `pricing`：可选，按模型配置 token 单价，币种使用 provider 的 `pricingCurrency`，单位为每 100 万 tokens。支持 `input`、`output`、`cachedInput`（隐式缓存读）、`explicitCachedInput`（显式缓存读）和 `cacheCreationInput`。如需按输入 token 总量分档，可用带 `maxInputTokens` 的 `tiers`。\n    - `contextCache`：可选，provider name 为 `dashscope` 或 `baseUrl` 包含 `aliyuncs.com` 时默认 `true`，其他 OpenAI 兼容 provider 默认 `false`。用于启用阿里云百炼/DashScope 的显式缓存（explicit context cache），会按其 Context Cache 格式在最多 4 个 content block 上注入 `cache_control: { \"type\": \"ephemeral\" }`。缓存断点策略与 opencode 主链路保持一致：前 2 条 system 消息 + 最后 2 条非 system 消息。标记字符串 content 时会把 `system` / `user` / `assistant` / `tool` 消息转换为 text content part 数组；已有数组 content 则标记最后一个 part。如果模型本身已经支持隐式缓存，或上游不支持该显式缓存扩展字段，可在模型配置中设为 `false`。支持相同显式缓存扩展的非 DashScope provider 可设为 `true`。同时适用于 `/v1/messages` 和 `/v1/chat/completions` 路由。\n    - `supportPdf`：可选，控制该模型是否支持 PDF/document content。默认 `false`，不支持时会把 PDF 转成提示文本；设为 `true` 时会把 PDF/document 转成 OpenAI Chat Completions 的 file part。\n    - `toolContentSupportType`：可选，配置该模型的 tool result content 支持能力，值为 `array`、`image`、`pdf` 的数组。provider 侧未配置时默认只发送 string tool content。若 `supportPdf` 为 `true` 但这里不包含 `pdf`，tool result 里的 file part 会被转成 user role 消息。Copilot 主链路不使用这个 provider 默认，仍按 array + image 且不支持 PDF 的能力处理。\n    - `type`：可选，按模型覆盖 provider 的协议类型。支持 `anthropic`、`openai-compatible` 和 `openai-responses`。设置后，provider 的 `/v1/messages` 路由会使用该模型的 type 替代 provider 级别的 type 进行请求路由、认证头解析和上游端点选择。适用于 OpenCode Go 等上游对不同模型同时支持 OpenAI 兼容和 Anthropic Messages API 的 provider。覆盖 type 时，认证头按覆盖后 type 的默认值解析（Anthropic 默认 `x-api-key`；OpenAI 兼容/Responses 默认 `authorization`）。\n\n  DashScope 模型配置示例：\n  ```json\n  {\n    \"providers\": {\n      \"dashscope\": {\n        \"type\": \"openai-compatible\",\n        \"enabled\": true,\n        \"baseUrl\": \"https://dashscope.aliyuncs.com/compatible-mode\",\n        \"apiKey\": \"sk-your-dashscope-key\",\n        \"pricingCurrency\": \"CNY\",\n        \"models\": {\n          \"qwen3.7-plus\": {\n            \"temperature\": 1,\n            \"topP\": 0.95,\n            \"topK\": 20,\n            \"extraBody\": {\n              \"preserve_thinking\": true\n            }\n          },\n          \"glm-5.1\": {\n            \"temperature\": 0.7,\n            \"topP\": 0.95,\n            \"contextCache\": true,\n            \"pricing\": {\n              \"tiers\": [\n                {\n                  \"maxInputTokens\": 32000,\n                  \"input\": 6,\n                  \"cachedInput\": 1.2,\n                  \"explicitCachedInput\": 0.6,\n                  \"cacheCreationInput\": 7.5,\n                  \"output\": 24\n                },\n                {\n                  \"maxInputTokens\": 200000,\n                  \"input\": 8,\n                  \"cachedInput\": 1.6,\n                  \"explicitCachedInput\": 0.8,\n                  \"cacheCreationInput\": 10,\n                  \"output\": 28\n                }\n              ]\n            },\n            \"extraBody\": {\n              \"preserve_thinking\": true\n            }\n          }\n        }\n      }\n    }\n  }\n  ```\n  内置 token 价格覆盖 Codex GPT 模型（USD）、DashScope `qwen3.7-max`、`qwen3.7-plus`、`glm-5.1`、`glm-5.2`（CNY），DeepSeek `deepseek-v4-flash`、`deepseek-v4-pro`、`deepseek-chat`、`deepseek-reasoner`（CNY），以及 OpenCode Go 模型（`glm-5.2`、`grok-4.5`、`deepseek-v4-flash`、`deepseek-v4-pro`、`kimi-k2.7-code`、`kimi-k3`、`mimo-v2.5`、`mimo-v2.5-pro`、`qwen3.7-plus`、`qwen3.7-max`、`minimax-m2.7`、`minimax-m3`，USD）。用户配置的 `pricing` 优先于内置价格。DashScope 若上游 usage 中出现 `cache_creation_input_tokens` 字段，cached tokens 按显式缓存读价计费；否则 `cachedInput` 作为隐式缓存读价。DeepSeek 的 `prompt_cache_hit_tokens` 会归入 cached input，`prompt_cache_miss_tokens` 会归入普通 input。\n- **smallModel：** 无工具预热消息的回退模型（例如 Claude Code 的探测请求）；默认是 `gpt-5-mini`。网关会对无工具的预热或探测请求强制使用该小模型，以避免消耗 premium 请求。该行为仅在 GitHub Copilot 账户为非 token-based 计费时生效（`token_based_billing` 为 false）；对于 token-based 计费账户，预热小模型回退会被跳过，因为不存在需要节省的 premium 请求配额。\n- **contextManagement：** 控制代理是否为 Responses API 附加 `context_management` 压缩指令。`messages` 作用于被翻译成 Responses API 的 Anthropic 风格 `/v1/messages` 请求，包括 `openai-responses` provider 的 Messages 路由，默认值为 `true`。`responses` 作用于 native `/v1/responses` 流量，包括 `provider/model` 别名和内置 `codex` provider，默认值为 `false`。只有在确认客户端支持 context management compaction 后，才建议在 Responses API 下启用 `responses`。启用后，请求体会带上 `context_management`，并在后续轮次中仅保留最新的压缩承载内容。**注意：** 对于 GPT-5.6 及以上模型（如 `gpt-5.6-sol`、`gpt-5.6-terra`、`gpt-5.6-luna`），context management 功能会被强制禁用，因为开启后会破坏这些模型的 prompt 缓存命中。此强制覆盖优先于 `contextManagement` 和 `modelResponsesApiCompactThresholds` 配置。\n- **modelResponsesApiCompactThresholds：** 按模型覆盖 Responses API 的 `compact_threshold`，仅在代理自动附加 `context_management` 时使用。它的优先级高于 `resolveResponsesCompactThreshold` 基于 `max_prompt_tokens * ratio` 的兜底阈值。默认将 `gpt-5.4` 和 `gpt-5.5` 设为 `217600`（`272000 * 0.8`），将 `gpt-5.6-sol`、`gpt-5.6-terra`、`gpt-5.6-luna` 设为 `231200`（`272000 * 0.85`）。未列出的模型继续使用原有兜底逻辑。\n- **modelReasoningEfforts：** `/v1/messages` 请求的模型级默认推理强度。仅当请求没有传入 `output_config.effort` 时，该配置才会生效。\n  - **优先级：** 请求中的 `output_config.effort` > `modelReasoningEfforts[model]` > 内置默认值（GPT-5.3+ 模型为 `xhigh`，其他模型为 `high`）。\n  - **转发字段：** 走 Copilot 原生 Messages API 时，最终值写入 `output_config.effort`；转换为 Responses API 时，最终值写入 `reasoning.effort`。\n  - **配置可选值：** `none`、`minimal`、`low`、`medium`、`high`、`xhigh`、`max`。\n- **useMessagesApi：** 当为 `true` 时，支持 Copilot 原生 `/v1/messages` 的 Claude 系模型会走 Messages API；否则回退到 `/chat/completions`。设为 `false` 可禁用 Messages API 路由，始终使用 `/chat/completions`。默认值为 `true`。\n- **useResponsesApiWebSocket：** 当为 `true` 时，Responses API 请求会优先对声明了 `ws:/responses` 的模型使用 Copilot websocket transport；仅声明 `/responses` 的模型仍走 HTTP。设为 `false` 可禁用 websocket 路由，并在模型支持 `/responses` 时使用 HTTP `/responses`。默认值为 `true`。如果遇到 Responses API WebSocket closed，一般是自己的网络问题。如果使用了 VPN，建议切换节点。\n- **useResponsesApiWebSearch：** 当为 `true` 时，服务端会保留 Responses API 中 `type: \"web_search\"` 的工具并透传到上游。设为 `false` 则会从 `/responses` payload 中移除这些工具。默认值为 `true`。\n- **messageApiWebSearchModel：** 顶层 Copilot `/v1/messages` 请求只包含服务端 `web_search` 工具时使用的全局模型，默认值为 `gpt-5-mini`。如果该值是 `provider/model` 别名，请求会进入对应 provider 的 Messages API 路径，并在转发前移除 provider 前缀。对于 Copilot GPT 模型，web search 会通过 `/responses` 执行。混合 `web_search` 与自定义工具的场景暂不支持，服务端会移除 server-side `web_search`。\n- **claudeTokenMultiplier：** 用于 Claude `/v1/messages/count_tokens` 请求在本地走 GPT tokenizer 估算时的乘数。默认值为 `1.15`。如果你的客户端仍然过晚触发上下文压缩，可以适当调大。这个配置只会在代理本地估算 Claude token 时生效；如果已经配置 `anthropicApiKey` 且 Anthropic token counting 调用成功，则会直接返回 Anthropic 的精确计数，不会使用这个乘数。\n- **anthropicApiKey：** 用于把 Claude `/v1/messages/count_tokens` 请求转发到 Anthropic 真实 token counting 端点的 API key，这样会返回精确计数，而不是 GPT tokenizer 估算值。也可通过环境变量 `ANTHROPIC_API_KEY` 设置。若未配置，或上游调用失败，则回退到由 `claudeTokenMultiplier` 控制的本地 GPT tokenizer 估算。\n\n编辑此文件后即可自定义 prompts，或替换为你自己的快速模型。修改完成后请重启服务（或重新执行命令），让缓存中的配置刷新生效。\n\n## API 认证\n\n- **受保护的普通路由：** 当配置了 `auth.apiKeys` 且非空时，除 `/`、`/usage-viewer` 和 `/usage-viewer/` 以外的普通路由都需要认证。\n- **Admin 路由：** 所有 `/admin/*` 路由都要求 `auth.adminApiKey`。如果缺失，服务会在启动时自动生成并在开始提供服务前写回 `config.json`。\n- **允许的认证头：**\n  - `x-api-key: <your_key>`\n  - `Authorization: Bearer <your_key>`\n- **CORS 预检：** `OPTIONS` 请求始终允许。\n- **未配置普通 key 时：** 普通路由仍可直接访问；但这条规则不适用于 `/admin/*`，后者只接受 `auth.adminApiKey`。\n\n普通受保护路由的示例请求：\n\n```sh\ncurl http://localhost:4141/v1/models \\\n  -H \"x-api-key: your_api_key\"\n```\n\nAdmin 路由的示例请求：\n\n```sh\ncurl http://localhost:4141/admin/config/model-mappings \\\n  -H \"x-api-key: your_admin_api_key\"\n```\n\n## API 端点\n\n服务端提供多个 OpenAI / Anthropic 兼容端点。请求会根据所选模型和 `provider/model` 别名路由到 GitHub Copilot、内置 `codex` provider 或已配置的 provider。\n\n### OpenAI 兼容端点\n\n这些端点模拟 OpenAI API 结构。\n\n| 端点 | 方法 | 说明 |\n| --- | --- | --- |\n| `POST /v1/responses` | `POST` | OpenAI 中用于生成模型响应的高级接口。支持 `openai-responses` provider 的 `provider/model` 别名。 |\n| `POST /v1/chat/completions` | `POST` | 为给定聊天对话创建模型响应。支持 `openai-compatible` provider 的 `provider/model` 别名；目标 provider 已配置时可在没有 Copilot 的情况下使用。 |\n| `GET /v1/models` | `GET` | 列出 Copilot 模型以及已启用 provider 的 `provider/model-id` 模型。来自 Codex 客户端（`User-Agent` 以 `codex` 开头）的请求会转发到 Codex Models 上游。 |\n| `POST /v1/embeddings` | `POST` | 创建表示输入文本的向量嵌入。 |\n\n### Codex 后端代理端点\n\n这些端点要求已有可用的 Codex 登录态。每个端点同时提供无版本前缀和 `/v1` 两种路径。\n\n| 端点 | 方法 | 说明 |\n| --- | --- | --- |\n| `POST /alpha/search`<br>`POST /v1/alpha/search` | `POST` | 将 JSON 请求体和查询参数透明转发到 Codex Alpha Search 上游。 |\n| `POST /images/generations`<br>`POST /v1/images/generations` | `POST` | 将 JSON 图片生成请求转发到 Codex Images 上游。请求未携带 `Content-Type` 时，网关默认补充 `application/json`。 |\n| `POST /images/edits`<br>`POST /v1/images/edits` | `POST` | 将图片编辑请求转发到 Codex Images 上游。请使用 `multipart/form-data`，并让 HTTP 客户端自动生成 `boundary`；网关会保留传入的 content type，并以流式方式转发上传请求体。 |\n\n对于以上所有端点，网关都会使用当前 Codex 登录态覆盖客户端的 authorization 和 account header，保留查询参数及兼容的请求头，并返回上游状态码、响应头和响应体。\n\n### Anthropic 兼容端点\n\n这些端点设计为兼容 Anthropic Messages API。provider 级的 models、Responses、alpha-search 和 images 路由同时支持无版本前缀与 `/v1` 两种路径；Messages 路由仍使用 `/v1`。\n\n| 端点 | 方法 | 说明 |\n| --- | --- | --- |\n| `POST /v1/messages` | `POST` | 为给定对话创建模型响应。支持已配置 provider 的 `provider/model` 别名，包括通过 `openai-compatible` provider 做翻译。 |\n| `POST /v1/messages/count_tokens` | `POST` | 计算一组消息的 token 数。支持已配置 provider 的 `provider/model` 别名。 |\n| `POST /:provider/v1/messages` | `POST` | 将 Anthropic Messages 请求代理到已配置的 Anthropic provider，或翻译到 OpenAI 兼容 / OpenAI Responses provider。 |\n| `GET /:provider/models`<br>`GET /:provider/v1/models` | `GET` | 将模型列表请求代理到已配置的 provider。对 `codex` 默认返回内置模型目录；Codex 客户端（`User-Agent` 以 `codex` 开头）会转发到 Codex Models 上游。 |\n| `POST /:provider/v1/messages/count_tokens` | `POST` | 为 provider 路由请求在本地计算 token 数。 |\n| `POST /:provider/responses`<br>`POST /:provider/v1/responses` | `POST` | 将 OpenAI Responses 请求代理到已配置的 `openai-responses` provider（含 `codex`）。 |\n| `POST /:provider/alpha/search`<br>`POST /:provider/v1/alpha/search` | `POST` | 代理 alpha-search 请求。对 `codex` 转发到 Codex Alpha Search 上游；其他 provider 转发到 `{baseUrl}/v1/alpha/search`。 |\n| `POST /:provider/images/generations`<br>`POST /:provider/v1/images/generations` | `POST` | 代理图片生成。对 `codex` 使用 Codex Images 上游；其他 provider 转发到 `{baseUrl}/v1/images/generations`（15 分钟超时）。 |\n| `POST /:provider/images/edits`<br>`POST /:provider/v1/images/edits` | `POST` | 代理图片编辑。对 `codex` 使用 Codex Images 上游；其他 provider 以 multipart/流式方式转发到 `{baseUrl}/v1/images/edits`（15 分钟超时）。 |\n\n### 使用量监控端点\n\n用于监控 Copilot 用量与额度的新端点。\n\n| 端点 | 方法 | 说明 |\n| --- | --- | --- |\n| `GET /usage` | `GET` | 获取详细的 Copilot 使用统计与额度信息。 |\n| `GET /token` | `GET` | 获取当前 API 正在使用的 Copilot token。 |\n\n### Admin / 配置端点\n\n这些端点用于本地管理操作，只接受 `auth.adminApiKey`。\n\n| 端点 | 方法 | 说明 |\n| --- | --- | --- |\n| `GET /admin/config/model-mappings` | `GET` | 返回当前 `config.json` 路径以及生效中的 `modelMappings` 映射。 |\n| `POST /admin/config/model-mappings` | `POST` | 只更新 `config.json` 里的 `modelMappings` 字段，并回传更新后的结果。 |\n\n## 使用示例\n\n常用 `npx` 命令：\n\n```sh\n# 基础启动\nnpx @jeffreycao/copilot-api@latest start\n\n# 自定义端口并开启详细日志\nnpx @jeffreycao/copilot-api@latest start --port 8080 --verbose\n\n# 执行认证流程\nnpx @jeffreycao/copilot-api@latest auth login\n\n# 配置第三方 provider，然后不依赖 GitHub Copilot 启动\nnpx @jeffreycao/copilot-api@latest auth login --provider dashscope\nnpx @jeffreycao/copilot-api@latest start\n\n# 以 JSON 格式输出调试信息\nnpx @jeffreycao/copilot-api@latest debug --json\n\n# 用 Bun 而不是 Node.js 运行已发布 CLI\nbunx --bun @jeffreycao/copilot-api@latest start\n```\n\n配置 `dashscope` 后的 OpenAI 兼容 provider 调用示例：\n\n```sh\ncurl http://localhost:4141/v1/chat/completions \\\n  -H \"content-type: application/json\" \\\n  -d '{\"model\":\"dashscope/qwen3.6-plus\",\"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]}'\n\ncurl http://localhost:4141/dashscope/v1/messages \\\n  -H \"content-type: application/json\" \\\n  -d '{\"model\":\"qwen3.6-plus\",\"max_tokens\":1024,\"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]}'\n```\n\n## 使用建议\n\n<a id=\"claudemd-or-agentsmd-recommended-content\"></a>\n\n### CLAUDE.md 或 AGENTS.md 推荐内容\n\n如果你想手动加入这些提醒，请在 Claude Code 的 `CLAUDE.md`，或 opencode/codex 的 `AGENTS.md` 中加入以下内容：\n\n```\n- Prohibited from directly asking questions to users, MUST use question tool.\n- Once you can confirm that the task is complete, MUST use question tool to make user confirm. The user may respond with feedback if they are not satisfied with the result, which you can use to make improvements and try again, after try again, MUST use question tool to make user confirm again.\n```\n"}, "d66d4fb4afedd4462dd2bd1d041501b112d4d52e": {"t": 1786068438.9324892, "n": 34942, "h": "df3359991bc63abc", "c": "# Copilot API Proxy\n\n[English](./README.md) | 简体中文\n\n## 重要说明\n\n> [!IMPORTANT]\n> **使用前请先注意以下几点：**\n>\n> 1. **Claude Code 配置：** 与 Claude Code 搭配使用时，请将模型 ID 配置为 `claude-opus-4-8`。示例 claude `settings.json` 见 [通过 `settings.json` 手动配置](#manual-configuration-with-settingsjson)。\n>\n> 2. **内置 `copilot`、`codex` 与第三方 provider：** 执行 `npx @jeffreycao/copilot-api@latest auth`，可选择 `copilot`、`codex`、`deepseek`、`custom` 等 provider。\n>\n> 3. **注意事项：** README 顶部移除的 GitHub Copilot warning 见 [GitHub Copilot 安全提示](./NOTICE.md#github-copilot-security-notice)。\n\n---\n\n## 项目概览\n\n这是一个小型 AI gateway，可以使用 GitHub Copilot、内置 `codex` provider，也可以使用 DashScope 等已配置的第三方 provider。GitHub Copilot 现在是可选能力：如果本地没有 GitHub token，只要至少配置了一个启用中的 provider，服务仍可按 provider-only 模式启动。\n\nAI gateway 会从同一个本地端点暴露 OpenAI / Anthropic 兼容 API，让 [Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview)、OpenCode、Codex 和 OpenAI 兼容客户端可以共用同一个本地服务。\n\n在 GitHub Copilot 路径上，AI gateway 会在可用时优先使用 Copilot 原生的 Anthropic 风格 Messages API，在重工具调用场景下保留更原生的 Claude 行为。\n\n## 功能特性\n\n- **OpenAI 与 Anthropic 双兼容**：通过 `/v1/responses`、`/v1/chat/completions`、`/v1/models`、`/v1/embeddings` 和 `/v1/messages` 对外暴露同一个本地 AI gateway。\n- **Copilot 可选**：有 GitHub 凭据时可以使用 GitHub Copilot，没有 GitHub 凭据时也可以只依赖已配置的 provider 运行。\n- **同一网关接入 Copilot、`codex` 与第三方 provider**：可统一路由 GitHub Copilot、内置 `codex` provider 和配置好的外部 provider。\n- **第三方 provider 可独立启动**：配置 DashScope、DeepSeek、OpenRouter 或自定义 provider 后，不需要 GitHub Copilot 登录即可启动 AI gateway。\n- **OpenAI 兼容 provider 同时支持 chat 和 Messages API**：`openai-compatible` provider 可通过顶层 `/v1/chat/completions` 搭配 `model: \"provider/model\"` 提供 Chat Completions，也可通过 `/v1/messages` 完成 Anthropic Messages 的请求/响应翻译。\n- **面向 Claude 的更原生 Copilot 路由**：优先使用原生 `/v1/messages`，保留 Claude 风格工具流，支持 Anthropic beta 能力、通过 Responses-capable 模型支持 Claude WebSearch，并保留 subagent / session 标记。\n- **Claude Code 与 OpenCode 集成**：兼容 Claude Code 与 OpenCode，也支持通过 `@ai-sdk/anthropic` 直接作为 Anthropic provider 使用。\n- **灵活的认证与部署选项**：支持交互式登录、直接 token、个人 / Business / Enterprise、GitHub Enterprise、opencode OAuth 和自定义数据目录。\n- **多 provider 路由**：可暴露 `/:provider/...` 路由，也可在顶层 API 上使用 `model: \"provider/model\"`。\n\n## 前置要求\n\n- Bun（>= 1.2.x）\n- 如果要通过 `npx` 运行已发布 CLI，需要 Node.js\n- 只有在使用 GitHub Copilot provider 时，才需要已订阅 Copilot 的 GitHub 账号\n- 如果不使用 GitHub Copilot，需要至少一个已配置 provider 的 API key 或 OAuth 登录\n\n## 安装\n\n安装依赖：\n\n```sh\nbun install\n```\n\n直接从源码启动服务：\n\n```sh\nbun run start start\n```\n\n## 从源码运行\n\n本项目可以通过多种方式从源码运行：\n\n### 开发模式\n\n```sh\nbun run dev start\n```\n\n### 生产模式\n\n```sh\nbun run start start\n```\n\n## 通过 npx 使用\n\n你可以直接用 npx 运行本项目：\n\n> [!IMPORTANT]\n> 通过 `npx` 运行时，token usage 存储会使用 Node 内置的 `node:sqlite` 模块。该能力会在 Node.js >= 22.13.0 时启用；Node.js < 22.13.0 时 CLI 仍可启动，但会禁用 token usage 存储。\n>\n> 如果不升级 Node.js 但仍需要 token usage 存储，可以改用 Bun 运行已发布 CLI：`bunx --bun @jeffreycao/copilot-api@latest start`。\n\n```sh\nnpx @jeffreycao/copilot-api@latest start\n```\n\n带参数示例：\n\n```sh\nnpx @jeffreycao/copilot-api@latest start --port 8080\n```\n\n如果只想做认证或 provider 配置：\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth\n```\n\n如果要不依赖 GitHub Copilot 运行，先配置至少一个 provider，然后正常启动服务：\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth login --provider dashscope\nnpx @jeffreycao/copilot-api@latest start\n```\n\n## 配合 Docker 使用\n\n构建镜像：\n\n```sh\ndocker build -t copilot-api .\n```\n\n通过 bind mount 运行容器，让认证数据在重启后保留：\n\n```sh\nmkdir -p ./copilot-data\ndocker run -p 4141:4141 -v $(pwd)/copilot-data:/root/.local/share/copilot-api copilot-api\n```\n\n这会把宿主机上的 `./copilot-data` 映射到容器内的 `/root/.local/share/copilot-api`，用于持久化 GitHub 认证数据、provider 配置和其他 gateway 状态。\n\n也可以直接通过环境变量传入 GitHub token：\n\n```sh\ndocker run -p 4141:4141 -e GH_TOKEN=your_github_token_here copilot-api\n```\n\n## Electron 桌面应用\n\n如果你更喜欢图形界面，仓库里还提供了位于 `desktop/` 的 Electron 桌面应用。它支持 GitHub Copilot 登录、OpenAI Codex OAuth，以及 DeepSeek、DashScope、OpenRouter 或自定义 provider 的 API Key 配置。授权或配置 provider 后，可以一键启动或停止本地代理，并在界面里直接查看本地端点、鉴权 Header、可用模型、额度和日志。\n\n设置页还可以配置 `OAuth App`、`API Home`、`Enterprise URL`、详细日志以及最小化到托盘。Windows x64（`.exe`）、macOS Apple Silicon（`.dmg`）和 Linux x64（`.AppImage`）安装包发布在 GitHub Releases：\n\nhttps://github.com/caozhiyuan/copilot-api/releases\n\nLinux 用户需要先为下载的 AppImage 添加执行权限：\n\n```sh\nchmod +x Copilot-API-*-linux-x86_64.AppImage\n./Copilot-API-*-linux-x86_64.AppImage\n```\n\n下载对应平台的安装包后，在应用内授权或配置 provider，选择端口并启动服务，再把你的客户端指向应用里显示的本地端点即可。发布版桌面应用使用随包内置的 Electron 运行时，正常使用不需要额外安装 Node.js；token usage 历史记录会在该内置运行时支持 SQLite 时启用。\n\n桌面应用里的高级配置页会通过 `GET/POST /admin/config/model-mappings` 读写这份共享的模型映射。同一份映射会统一作用于 `POST /v1/messages`、`POST /v1/messages/count_tokens`、`POST /v1/responses` 和 `POST /v1/chat/completions`，不再按接口区分。它使用的是 `auth.adminApiKey`，不是普通的 `auth.apiKeys`；应用会在服务启动并自动生成该 key 后，直接从 `config.json` 读取它来发起请求。\n\n### 桌面应用截图\n\n下面展示了桌面应用中的首页、Token 用量统计页面：\n\n<p align=\"center\">\n  <img src=\"./docs/screenshots/desktop-dashboard.png\" alt=\"Copilot API 桌面应用首页\" width=\"49%\" />\n  <img src=\"./docs/screenshots/desktop-token-usage.png\" alt=\"Copilot API 桌面应用 Token 用量页\" width=\"49%\" />\n</p>\n\n## 与 Claude Code 一起使用\n\n这个 AI gateway 可以为 [Claude Code](https://docs.anthropic.com/en/claude-code) 提供后端能力。Claude Code 是 Anthropic 提供的实验性面向开发者的对话式 AI 助手。\n\n有两种方式可以把 Claude Code 配置为使用这个 AI gateway：\n\n### 通过 `--claude-code` 标志进行交互式配置\n\n执行带 `--claude-code` 的 `start` 命令开始：\n\n```sh\nnpx @jeffreycao/copilot-api@latest start --claude-code\n```\n\n你不再需要手动选择模型。Gateway 会自动检测每个 Claude Code 尺寸档位对应的最新可用模型——opus 映射到最新的 Opus 模型，sonnet 映射到最新的 Sonnet 模型，haiku 映射到最新的 Haiku 模型——并生成相应设置 `ANTHROPIC_DEFAULT_OPUS_MODEL`、`ANTHROPIC_DEFAULT_SONNET_MODEL` 和 `ANTHROPIC_DEFAULT_HAIKU_MODEL` 的命令。若某个档位没有匹配的可用模型，则会被省略。该命令会被复制到剪贴板，并设置 Claude Code 使用这个 AI gateway 所需的环境变量。\n\n在新的终端中粘贴并执行这条命令，即可启动 Claude Code。\n\n<a id=\"manual-configuration-with-settingsjson\"></a>\n\n### 通过 `settings.json` 手动配置\n\n另一种方式是在项目根目录中创建 `.claude/settings.json` 文件，并写入 Claude Code 所需的环境变量。这样你就不需要每次都运行交互式配置了。\n\n下面是一个 `.claude/settings.json` 示例：\n\n```json\n{\n  \"env\": {\n    \"ANTHROPIC_BASE_URL\": \"http://localhost:4141\",\n    \"ANTHROPIC_AUTH_TOKEN\": \"dummy\",\n    \"ANTHROPIC_MODEL\": \"gpt-5.6-sol[1m]\",\n    \"ANTHROPIC_DEFAULT_OPUS_MODEL\": \"gpt-5.6-sol[1m]\",\n    \"ANTHROPIC_DEFAULT_SONNET_MODEL\": \"gpt-5.6-sol[1m]\",\n    \"ANTHROPIC_DEFAULT_HAIKU_MODEL\": \"gpt-5.6-luna[1m]\",\n    \"CLAUDE_CODE_AUTO_COMPACT_WINDOW\": \"272000\",\n    \"CLAUDE_CODE_USE_VERTEX\": \"0\",\n    \"CLAUDE_CODE_USE_BEDROCK\": \"0\",\n    \"DISABLE_NON_ESSENTIAL_MODEL_CALLS\": \"1\",\n    \"CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC\": \"1\",\n    \"CLAUDE_CODE_ATTRIBUTION_HEADER\": \"0\",\n    \"CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION\": \"false\",\n    \"CLAUDE_CODE_DISABLE_TERMINAL_TITLE\": \"true\",\n    \"CLAUDE_CODE_ENABLE_AWAY_SUMMARY\": \"0\"\n  },\n  \"alwaysThinkingEnabled\": true,\n  \"effortLevel\": \"xhigh\",\n  \"showThinkingSummaries\": true\n}\n```\n\n- 请根据需要替换 `ANTHROPIC_MODEL`、`ANTHROPIC_DEFAULT_OPUS_MODEL`、`ANTHROPIC_DEFAULT_SONNET_MODEL` 和 `ANTHROPIC_DEFAULT_HAIKU_MODEL`。配置完成后，请安装 claude code 插件，见 [插件集成](#plugin-integrations)。\n- 如果你使用的是 codex provider，建议**不要**将模型名配置成 `codex/xxx` 格式（如 `codex/gpt-5.6-sol`）。Claude Code 会针对 `codex/` 前缀做降智行为——例如每次请求时移除所有之前返回的思考块（thinking blocks）。请使用纯模型名（如 `gpt-5.6-sol`），并在 `config.json` 中配置 `modelMappings` 将其映射回 codex provider：\n  ```json\n  \"modelMappings\": {\n    \"gpt-5.6-sol\": \"codex/gpt-5.6-sol\",\n    \"gpt-5.6-terra\": \"codex/gpt-5.6-terra\",\n    \"gpt-5.6-luna\": \"codex/gpt-5.6-luna\"\n  },\n  ```\n- 将 `CLAUDE_CODE_ATTRIBUTION_HEADER` 设为 `0` 可以阻止 Claude Code 在 system prompt 中附加计费和版本信息，从而避免 prompt cache 失效。\n- 关闭 `CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION` 和 `CLAUDE_CODE_ENABLE_AWAY_SUMMARY` 可以避免不必要地消耗额度。\n- Claude Code WebSearch 已支持纯搜索请求。Copilot 路径请保持全局 `messageApiWebSearchModel` 指向 Responses-capable GPT 模型或 `provider/model` 别名；provider 路由请使用原生 Anthropic provider 或 `openai-responses` provider。只有在你明确想禁止这类流量时，才需要把 `WebSearch` 加到 `permissions.deny`。\n- 如果使用的不是 Claude 模型，请不要启用 `ENABLE_TOOL_SEARCH`。如果使用的是 Claude 模型，则可以启用 `ENABLE_TOOL_SEARCH`。当前 Claude Code 使用的是客户端 tool search 模式，在该模式下每次加载 defer tools 都需要额外请求一次。\n- `CLAUDE_CODE_AUTO_COMPACT_WINDOW`：设置用于自动压缩计算的上下文容量（以 token 为单位）。默认使用模型自身的上下文窗口：标准模型为 200K，扩展上下文模型为 1M。使用 1M 上下文模型（如 `claude-opus-4-6[1m]`）时，可设置一个较低的值（如 `500000`）将窗口视为 500K 用于压缩计算。该值受限于模型的实际上下文窗口上限。`CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` 会基于此值的百分比生效。设置此变量可将压缩阈值与状态栏的 `used_percentage` 解耦（后者始终使用模型的完整上下文窗口）。\n\n更多选项见：[Claude Code settings](https://docs.anthropic.com/en/docs/claude-code/settings#environment-variables)\n\n也可以参考 IDE 集成说明：[Add Claude Code to your IDE](https://docs.anthropic.com/en/docs/claude-code/ide-integrations)\n\n## 与 OpenCode 一起使用\n\nOpenCode 已经有直接的 GitHub Copilot provider。本节适用于你希望让 OpenCode 通过 `@ai-sdk/anthropic` 指向这个 AI gateway，并复用本 README 前面提到的 agent 行为时。\n\n### 最小配置\n\n使用 OpenCode OAuth app 启动 AI gateway：\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth --oauth-app=opencode\nnpx @jeffreycao/copilot-api@latest start\n```\n\n然后让 OpenCode 通过 `@ai-sdk/anthropic` 指向这个 AI gateway。\n\n示例 `~/.config/opencode/opencode.json`：\n\n```json\n{\n  \"$schema\": \"https://opencode.ai/config.json\",\n  \"provider\": {\n    \"local\": {\n      \"npm\": \"@ai-sdk/anthropic\",\n      \"name\": \"My Local\",\n      \"options\": {\n        \"baseURL\": \"http://localhost:4141/v1\",\n        \"apiKey\": \"dummy\"\n      },\n      \"models\": {\n        \"gpt-5.4\": {\n          \"name\": \"gpt-5.4\",\n          \"modalities\": {\n            \"input\": [\"text\", \"image\"],\n            \"output\": [\"text\"]\n          },\n          \"limit\": {\n            \"context\": 400000,\n            \"input\": 272000,\n            \"output\": 128000\n          }\n        },\n        \"claude-sonnet-4.6\": {\n          \"id\": \"claude-sonnet-4.6\",\n          \"name\": \"claude-sonnet-4.6\",\n          \"modalities\": {\n            \"input\": [\"text\", \"image\"],\n            \"output\": [\"text\"]\n          },\n          \"limit\": {\n            \"context\": 200000,\n            \"output\": 32000\n          },\n          \"options\": {\n            \"thinking\": {\n              \"type\": \"adaptive\"\n            },\n            \"effort\": \"max\"\n          }\n        }\n      }\n    }\n  }\n}\n```\n\n这些字段的重要性：\n\n- `npm: \"@ai-sdk/anthropic\"` 是关键。OpenCode 会以 Anthropic Messages 语义与这个 AI gateway 通信，而不是把一切扁平化为 OpenAI Chat Completions。\n- `options.baseURL` 应设为 `http://localhost:4141/v1`；Anthropic SDK 会自动补上 `/messages`、`/models` 和 `/messages/count_tokens`。\n- 如果你在此代理中启用了 `auth.apiKeys`，请把 `dummy` 替换为真实 key；否则任意占位值都可以。\n\n## 与 Codex 一起使用\n\n这个 AI gateway 也可以为 Codex 提供后端能力。\n\n### Codex `config.toml` 参考配置\n\n把以下 `[model_providers.copilot_api]` 段加入你的 Codex `~/.codex/config.toml`：\n\n```toml\nmodel_provider = \"copilot_api\"\nmodel_reasoning_summary = \"auto\"\nmodel_context_window = 272000\nmodel_auto_compact_token_limit = 244800\n\n[model_providers.copilot_api]\nname = \"OpenAI\"\nbase_url = \"http://localhost:4141\"\nenv_key = \"GITHUB_COPILOT_API_KEY\"\nrequires_openai_auth = true\nsupports_websockets = false\nwire_api = \"responses\"\nrequest_max_retries = 3\nstream_max_retries = 1\nstream_idle_timeout_ms = 300000\n\n[features]\nremote_compaction_v2 = true\n\n[analytics]\nenabled = false\n```\n\n> [!NOTE]\n> 此配置仅限于 Codex 与 GitHub Copilot provider。`name` 一定要配置为 `\"OpenAI\"`。它可以缓解 Codex local compact 不命中缓存的问题。\n> 如果使用 codex provider，建议将 `base_url` 配置为 `\"http://localhost:4141/codex\"`。\n\n当 Codex 通过顶层 GitHub Copilot 路由并设置 `approvals_reviewer = \"auto_review\"` 时，可在网关的 `config.json` 中将内部审核模型映射到一个支持 Responses API 的 Copilot 模型：\n\n```json\n{\n  \"modelMappings\": {\n    \"codex-auto-review\": \"gpt-5.6-luna\"\n  }\n}\n```\n\n该映射只作用于顶层 GitHub Copilot 路由。provider-scoped 路由不会使用 `modelMappings`，因此内置 `/codex` provider 仍会原生处理 `codex-auto-review`。\n\n## GPT Tool Search\n\n对于 `gpt-5.4+` 这类 GPT Responses 模型，这个 AI gateway 可以通过一个很小的 MCP bridge 暴露 Responses `tool_search`。Claude Code 和 opencode 都可以使用同一个 bridge，前提是客户端会加载 MCP server，并且 Anthropic Messages 流量会经过这个 AI gateway。\n\nGPT 模型不要设置 Claude Code 原生的 `ENABLE_TOOL_SEARCH`。这个开关启用的是 Claude Code 自己的客户端 tool search 模式，可能导致 deferred 工具定义不再转发给 AI gateway。这个 AI gateway 需要完整的工具定义，这样才能只保留那一小组常驻加载工具，其余工具统一转换为 Responses deferred namespace。\n\n如果你安装了 `tool-search@copilot-api-marketplace`，Claude Code 会自动带上这个 MCP bridge，可以跳过下面这段 Claude Code MCP 手动配置。\n\n请把 tool search bridge 加到 Claude Code 使用的 MCP 配置中：\n\n```json\n{\n  \"mcpServers\": {\n    \"tool_search\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@jeffreycao/copilot-api@latest\", \"mcp\"]\n    }\n  }\n}\n```\n\n请把 tool search bridge 加到 opencode 使用的 MCP 配置中：\n\n```json\n{\n  \"mcp\": {\n    \"tool_search\": {\n      \"type\": \"local\",\n      \"command\": [\"npx\", \"-y\", \"@jeffreycao/copilot-api@latest\", \"mcp\"]\n    }\n  }\n}\n```\n\n本地开发时可以将命令换成 `bun`，参数换成 `[\"run\", \"./src/main.ts\", \"mcp\"]`。\n\nAI gateway 内部现在会把 OpenAI Responses `tool_search` 配置成 client-executed 模式。deferred tools 仍然会作为可搜索 namespace 暴露给模型，但会明确要求模型直接返回下一步要加载的精确工具名列表。\n\n该 bridge 使用直接工具选择，不做 query 搜索。工具入参是 `names`，值为逗号分隔的精确 deferred 工具名，例如 `TaskList,TaskGet,mcp__fetch__fetch`。\n\n<a id=\"plugin-integrations\"></a>\n\n## 插件集成\n\n本项目为 Claude Code 和 opencode 提供了插件集成。\n\n#### Claude Code 插件集成（基于 marketplace）\n\nClaude Code 集成现在拆分为两个插件：\n\n- `agent-inject` 会在 `SubagentStart` 时注入 `__SUBAGENT_MARKER__...`，以便 AI gateway 推导 `x-initiator: agent`。\n- `tool-search` 会注册用于 GPT Responses deferred tool loading 的 `tool_search` MCP bridge。\n\n- 本仓库中的 marketplace catalog：`.claude-plugin/marketplace.json`\n- 本仓库中的插件源码：`plugin/claude/agent-inject`、`plugin/claude/tool-search`\n\n远程添加 marketplace：\n\n```sh\n/plugin marketplace add https://github.com/caozhiyuan/copilot-api.git\n```\n\n从 marketplace 安装插件：\n\n```sh\n/plugin install agent-inject@copilot-api-marketplace\n/plugin install tool-search@copilot-api-marketplace\n```\n\n安装后，`agent-inject` 会在 `SubagentStart` 时注入 `__SUBAGENT_MARKER__...`，AI gateway 会利用它推导 `x-initiator: agent`。\n\n`agent-inject` 还会注册一个 `UserPromptSubmit` hook，并返回 `{\"continue\": true}`；同时它也可以通过环境变量注入 `SessionStart` reminder 规则：\n\n- `CLAUDE_PLUGIN_ENABLE_QUESTION_RULES=1` 会自动为 Claude Code 启用两条关于使用 `question` 工具的提醒。你也可以把同样的提醒手动写进 `CLAUDE.md`；见 [CLAUDE.md 或 AGENTS.md 推荐内容](#claudemd-or-agentsmd-recommended-content)。\n- `CLAUDE_PLUGIN_ENABLE_NO_BACKGROUND_AGENTS_RULE=1` 会启用关于避免在 agent hooks 中使用 `run_in_background: true` 的提醒。\n\n`tool-search` 插件内置了 [GPT Tool Search](#gpt-tool-search) 一节描述的同一个 MCP bridge，因此安装该插件后，Claude Code 用户无需再手动配置 `tool_search` server。\n\n#### Opencode 插件\n\nsubagent 标记生成器被打包为一个 opencode 插件，位于 `plugin/opencode/subagent-marker.js`。\n\n**安装方式：**\n\n将插件文件复制到你的 opencode 插件目录：\n\n```sh\n# 克隆或下载本仓库后复制该插件\ncp plugin/opencode/subagent-marker.js ~/.config/opencode/plugins/\n```\n\n或者手动在 `~/.config/opencode/plugins/subagent-marker.js` 创建该文件，并填入插件内容。\n\n**功能：**\n\n- 跟踪 subagent 创建的子会话\n- 自动在 subagent 聊天消息前添加 marker system reminder（`__SUBAGENT_MARKER__...`）\n- 设置 `x-session-id` 请求头以跟踪会话\n- 让这个 AI gateway 能够把来自 subagent 的请求识别为 `x-initiator: agent`\n\n该插件会挂接到 `session.created`、`session.deleted`、`chat.message` 和 `chat.headers` 事件上，以无缝提供 subagent marker 能力。\n\n## 使用量查看器\n\n服务启动后，控制台会输出一个 Copilot 使用量看板 URL。这个看板是一个用于监控 API 用量的 Web 界面。\n\n1. 启动服务。例如使用 npx：\n   ```sh\n   npx @jeffreycao/copilot-api@latest start\n   ```\n2. 服务会输出一个 usage viewer 的 URL。将它复制到浏览器中打开，形式大致如下：\n   `http://localhost:4141/usage-viewer?endpoint=http://localhost:4141/usage`\n   - 如果你在 Windows 上使用 `start.bat` 脚本，这个页面会自动打开。\n\n看板提供了更易读的 Copilot 用量视图：\n\n> token usage 历史记录需要 Bun 或 Node.js >= 22.13.0。Node.js < 22.13.0 时服务会正常运行，但 token usage 存储会被禁用。\n\n- **API Endpoint URL**：通过 URL 查询参数指定 API endpoints，默认指向本地服务。支持手动切换为其他兼容 endpoints。\n- **x-api-key 认证**：如果启用了 API Key 认证，可填入 `x-api-key` 请求头。密钥会持久化保存在浏览器本地存储中。\n- **Period 选择器**：支持 Day / Week / Month 三种时间范围，切换时 URL 参数会自动同步，方便收藏和分享。\n- **Fetch Data**：点击 \"Refresh\" 按钮加载或刷新使用数据。页面加载时也会自动拉取数据。\n- **Copilot Quotas 额度**：通过进度条展示 Chat、Completions 等不同服务的额度使用情况，悬停可查看已用/剩余详情。\n- **Token Usage 指标卡片**：汇总当前周期的 Total、Input、Output、Cache Read、Cache Write、Requests 和预估费用。\n- **趋势图（Week / Month）**：提供按模型和指标筛选的折线趋势图，点击数据点可查看单日用量明细。\n- **Model Breakdown 表格**：按模型维度列出周期内的请求数、输入/输出/缓存 token 和预计费用。\n- **Request Events 分页列表**：按时间排序的请求事件记录，支持分页浏览，含时间戳、模型、请求 ID 和 token 用量。\n- **Detailed Information**：展示 API 返回的完整 JSON 响应，便于深入分析所有可用统计数据。\n- **URL-based Configuration**：也可通过 `endpoint` 和 `period` 查询参数直接指定 API 端点与时间范围。例如：\n  `http://localhost:4141/usage-viewer?endpoint=http://your-api-server/usage&period=week`\n\n### Usage Viewer 截图\n\n<p align=\"center\">\n  <img src=\"./docs/screenshots/usage-viewer.png\" alt=\"Copilot API Usage Viewer 页面\" width=\"900\" />\n</p>\n\n## 命令结构\n\nCopilot API 现在使用子命令结构，主要命令包括：\n\n- `start`：启动 AI gateway 服务。如果已有 GitHub token，则启用 Copilot 路径；如果没有 GitHub token，但存在至少一个启用中的 provider，则按 provider-only 模式启动；如果两者都没有，会引导你配置 provider。\n- `auth`：仅执行 provider 登录或配置流程，不启动服务。可用于 GitHub Copilot 登录、Codex OAuth，或第三方 provider API key 配置。\n- `debug`：显示诊断信息，包括版本、运行时详情、文件路径以及认证状态，便于排障与支持。\n\n## 命令行选项\n\n### 全局选项\n\n以下选项可用于任意子命令。若在子命令之前传入，请使用 `--key=value` 形式：\n\n| 选项 | 说明 | 默认值 | 别名 |\n| --- | --- | --- | --- |\n| --api-home | API home 目录路径（设置 `COPILOT_API_HOME`） | 无 | 无 |\n| --oauth-app | OAuth app 标识符（设置 `COPILOT_API_OAUTH_APP`） | 无 | 无 |\n| --enterprise-url | GitHub Enterprise URL（设置 `COPILOT_API_ENTERPRISE_URL`） | 无 | 无 |\n\n### Start 命令选项\n\n以下是 `start` 命令可用的命令行选项：\n\n| 选项 | 说明 | 默认值 | 别名 |\n| --- | --- | --- | --- |\n| --port | 监听端口 | 4141 | -p |\n| --verbose | 启用详细日志 | false | -v |\n| --github-token | 直接提供 GitHub token（必须通过 `auth` 子命令生成） | 无 | -g |\n| --claude-code | 生成一个使用 Copilot API 配置启动 Claude Code 的命令 | false | -c |\n| --show-token | 在获取和刷新时显示 GitHub 与 Copilot token | false | 无 |\n| --proxy-env | 从环境变量初始化代理 | false | 无 |\n\n### Auth 命令选项\n\n| 选项 | 说明 | 默认值 | 别名 |\n| --- | --- | --- | --- |\n| --provider | 要登录或配置的 provider（`copilot`、`codex`、`opencode-go`、`deepseek`、`dashscope`、`openrouter` 或 `custom`） | 交互选择 | 无 |\n| --verbose | 启用详细日志 | false | -v |\n| --show-token | 认证时显示 GitHub token | false | 无 |\n\n只有在需要启用 GitHub Copilot provider 时，才需要执行 `copilot-api auth login --provider copilot`。使用 `codex` 或第三方 provider-only 模式不要求配置 Copilot。\n\n使用 `copilot-api auth login --provider deepseek`、`--provider dashscope`、`--provider openrouter` 或 `--provider opencode-go` 可以通过 CLI 快速新增或更新这些常用第三方 provider。DeepSeek 会提示输入掩码显示的 `apiKey`、provider `type`（默认 `anthropic`），以及默认 `https://api.deepseek.com/anthropic` 的 `baseUrl`。DashScope 会提示输入掩码显示的 `apiKey`、provider `type`（默认 `openai-compatible`）和预填默认值的 `baseUrl`。OpenRouter 只提示输入掩码显示的 `apiKey` 和预填默认值的 `baseUrl`，并固定写入 `type: \"anthropic\"`。OpenCode Go 只提示输入掩码显示的 `apiKey` 和预填默认值的 `baseUrl`，并固定写入 `type: \"openai-compatible\"`（baseUrl `https://opencode.ai/zen/go`）。此外，OpenCode Go 内置将 `qwen*` 和 `minimax*` 模型路由到 Anthropic Messages，将 `gpt*` 模型路由到 OpenAI Responses，其他模型仍默认使用 OpenAI 兼容协议。配置并启用 provider 后，`copilot-api start` 可在没有 GitHub token 的情况下启动。\n\n使用 `copilot-api auth login --provider custom` 可以通过 CLI 新增或更新其他第三方 provider。命令会依次提示输入 provider name、项目支持的 type（`anthropic`、`openai-compatible` 或 `openai-responses`）、`baseUrl`、掩码显示的 `apiKey` 和 `authType`；`authType` 可保持 type 默认值，也可选择 `x-api-key` / `authorization`。\n\n### Debug 命令选项\n\n| 选项 | 说明 | 默认值 | 别名 |\n| --- | --- | --- | --- |\n| --json | 以 JSON 输出调试信息 | false | 无 |\n\n<a id=\"configuration-configjson\"></a>\n\n## 配置（config.json）\n\n- **位置：** Linux/macOS 为 `~/.local/share/copilot-api/config.json`，Windows 为 `%USERPROFILE%\\.local\\share\\copilot-api\\config.json`。\n- **默认结构：**\n  ```json\n  {\n    \"auth\": {\n      \"apiKeys\": [],\n      \"adminApiKey\": \"<startup 自动生成>\"\n    },\n    \"providers\": {},\n    \"modelMappings\": {},\n    \"extraPrompts\": {\n      \"gpt-5-mini\": \"<built-in exploration prompt>\"\n    },\n    \"smallModel\": \"gpt-5-mini\",\n    \"contextManagement\": {\n      \"messages\": true,\n      \"responses\": false\n    },\n    \"modelResponsesApiCompactThresholds\": {\n      \"gpt-5.4\": 217600,\n      \"gpt-5.5\": 217600\n    },\n    \"modelReasoningEfforts\": {\n      \"gpt-5-mini\": \"low\"\n    },\n    \"useMessagesApi\": true,\n    \"useResponsesApiWebSocket\": true,\n    \"useResponsesApiWebSearch\": true,\n    \"messageApiWebSearchModel\": \"gpt-5-mini\"\n  }\n  ```\n- **auth.apiKeys：** 用于普通非 admin 路由的 API key。支持多个 key 轮换使用。请求可通过 `x-api-key: <key>` 或 `Authorization: Bearer <key>` 进行认证。若为空或省略，则普通路由的认证会被禁用。\n- **auth.adminApiKey：** 仅用于 `/admin/*` 路由的单个 admin key。若未配置，服务会在启动时自动生成一个随机 key，并回写到 `config.json`。它同样使用 `x-api-key` 或 `Authorization: Bearer` 这两种头，但普通 `auth.apiKeys` 不能访问 `/admin/*`。\n- **modelMappings：** 用于顶层 `POST /v1/messages`、`POST /v1/messages/count_tokens`、`POST /v1/responses` 和 `POST /v1/chat/completions` 请求的精确 `sourceModel -> targetModel` 重写映射，这几类接口共用同一份规则。省略该字段或保留为 `{}` 时，不会做模型重写。`source` 和 `target` 都必须是非空字符串。`target` 可以是普通模型 ID，也可以是 `provider/model` 形式的别名，例如 `dashscope/qwen3.6-plus`；重写发生在 provider alias 解析之前。这些映射不再按接口区分。`GET/POST /admin/config/model-mappings` 管理接口读写的也只有这个字段。\n- **extraPrompts：** `model -> prompt` 的映射。把 Anthropic 风格请求翻译为 Responses API 时，会将其附加到第一条 system prompt 后面。你可以借此为不同模型注入护栏或指引。缺失的默认项会自动补齐，但不会覆盖你自定义的 prompt。对于 GPT-5.3+ 模型（如 `gpt-5.3-codex`、`gpt-5.4`、`gpt-5.5`），未显式配置时会自动使用内置的 commentary prompt。内置 prompt 会启用带阶段感知的 commentary，让模型在工具调用或更深层推理前先发出简短的用户可见进度说明。\n- **providers：** 全局上游 provider 映射。每个 provider key（例如 `dashscope`）都会变成一个路由前缀（`/dashscope/v1/messages`）。支持 `type: \"anthropic\"`、`type: \"openai-compatible\"` 和 `type: \"openai-responses\"`。顶层客户端也可以在 `/v1/messages`、`/v1/messages/count_tokens`、`/v1/responses` 和 `/v1/chat/completions` 中使用 `model: \"dashscope/model-id\"`；AI gateway 会在转发上游前移除 `dashscope/` 前缀。`openai-compatible` provider 同时支持 chat 和 Messages 流程：`/v1/chat/completions` 会直连上游 `/v1/chat/completions`，而 `/v1/messages` 和 `/:provider/v1/messages` 会先翻译为上游 Chat Completions，再把响应翻译回 Anthropic Messages。`GET /v1/models` 会聚合已启用 provider 的模型，并以 `provider/model-id` 形式返回；单个 provider 的原始模型列表仍可使用 `GET /dashscope/v1/models`。\n  - `enabled`：可选，若省略则默认为 `true`。\n  - `baseUrl`：provider API 的基础 URL，不要带结尾的 endpoint。Anthropic provider 不要带 `/v1/messages`；OpenAI 兼容 provider 不要带 `/v1/chat/completions`；OpenAI Responses provider 不要带 `/v1/responses`。\n  - `apiKey`：作为上游凭据值使用；普通 provider 必须配置。\n  - `authType`：可选，控制 `apiKey` 如何发送到上游。普通 provider 支持 `x-api-key` 和 `authorization`。Anthropic provider 默认 `x-api-key`；OpenAI 兼容和 OpenAI Responses provider 默认 `authorization`。当设置为 `authorization` 时，代理会发送 `Authorization: Bearer <apiKey>`。`oauth2` 仅保留给内置 `codex` provider，并由 `auth login --provider codex` 自动写入。\n  - `pricingCurrency`：可选，provider 维度的 token 费用币种，例如 `USD` 或 `CNY`。快捷 provider 默认 DashScope、DeepSeek 为 `CNY`，Codex/OpenRouter 为 `USD`。费用按币种分别汇总，不做汇率换算。\n  - `models`：可选，按模型 ID 配置的映射。每个键为请求中的模型名，值支持：\n    - `temperature`：可选，当请求未指定时使用的默认温度。\n    - `topP`：可选，当请求未指定时使用的默认 `top_p`。\n    - `topK`：可选，当请求未指定时使用的默认 `top_k`。\n    - `extraBody`：可选，按模型合入上游请求体的动态字段；请求体显式同名字段优先。OpenAI 兼容 provider 可用它配置 `enable_thinking`、`preserve_thinking`、`reasoning_effort` 等字段。`thinking_budget` 是 OpenAI 兼容 provider 的特殊覆盖项：配置在 `extraBody` 后，会在 Anthropic `thinking.budget_tokens` 翻译之后强制写入，并覆盖请求派生出的预算值。对于 provider name 为 `dashscope` 或 `baseUrl` 包含 `aliyuncs.com` 的 provider，请求派生的 `thinking_budget`（来自 Anthropic `thinking.budget_tokens`）会转发给上游；其他 OpenAI 兼容 provider 会移除请求派生的 `thinking_budget`，但 `extraBody` 中的 `thinking_budget` 仍然生效。对于 DashScope provider，当 `preserve_thinking` 未在 `extraBody` 或请求体中显式设置时，默认为 `true`。\n    - `pricing`：可选，按模型配置 token 单价，币种使用 provider 的 `pricingCurrency`，单位为每 100 万 tokens。支持 `input`、`output`、`cachedInput`（隐式缓存读）、`explicitCachedInput`（显式缓存读）和 `cacheCreationInput`。如需按输入 token 总量分档，可用带 `maxInputTokens` 的 `tiers`。\n    - `contextCache`：可选，provider name 为 `dashscope` 或 `baseUrl` 包含 `aliyuncs.com` 时默认 `true`，其他 OpenAI 兼容 provider 默认 `false`。用于启用阿里云百炼/DashScope 的显式缓存（explicit context cache），会按其 Context Cache 格式在最多 4 个 content block 上注入 `cache_control: { \"type\": \"ephemeral\" }`。缓存断点策略与 opencode 主链路保持一致：前 2 条 system 消息 + 最后 2 条非 system 消息。标记字符串 content 时会把 `system` / `user` / `assistant` / `tool` 消息转换为 text content part 数组；已有数组 content 则标记最后一个 part。如果模型本身已经支持隐式缓存，或上游不支持该显式缓存扩展字段，可在模型配置中设为 `false`。支持相同显式缓存扩展的非 DashScope provider 可设为 `true`。同时适用于 `/v1/messages` 和 `/v1/chat/completions` 路由。\n    - `supportPdf`：可选，控制该模型是否支持 PDF/document content。默认 `false`，不支持时会把 PDF 转成提示文本；设为 `true` 时会把 PDF/document 转成 OpenAI Chat Completions 的 file part。\n    - `toolContentSupportType`：可选，配置该模型的 tool result content 支持能力，值为 `array`、`image`、`pdf` 的数组。provider 侧未配置时默认只发送 string tool content。若 `supportPdf` 为 `true` 但这里不包含 `pdf`，tool result 里的 file part 会被转成 user role 消息。Copilot 主链路不使用这个 provider 默认，仍按 array + image 且不支持 PDF 的能力处理。\n    - `type`：可选，按模型覆盖 provider 的协议类型。支持 `anthropic`、`openai-compatible` 和 `openai-responses`。设置后，provider 的 `/v1/messages` 路由会使用该模型的 type 替代 provider 级别的 type 进行请求路由、认证头解析和上游端点选择。适用于 OpenCode Go 等上游对不同模型同时支持 OpenAI 兼容和 Anthropic Messages API 的 provider。覆盖 type 时，认证头按覆盖后 type 的默认值解析（Anthropic 默认 `x-api-key`；OpenAI 兼容/Responses 默认 `authorization`）。\n\n  DashScope 模型配置示例：\n  ```json\n  {\n    \"providers\": {\n      \"dashscope\": {\n        \"type\": \"openai-compatible\",\n        \"enabled\": true,\n        \"baseUrl\": \"https://dashscope.aliyuncs.com/compatible-mode\",\n        \"apiKey\": \"sk-your-dashscope-key\",\n        \"pricingCurrency\": \"CNY\",\n        \"models\": {\n          \"qwen3.7-plus\": {\n            \"temperature\": 1,\n            \"topP\": 0.95,\n            \"topK\": 20,\n            \"extraBody\": {\n              \"preserve_thinking\": true\n            }\n          },\n          \"glm-5.1\": {\n            \"temperature\": 0.7,\n            \"topP\": 0.95,\n            \"contextCache\": true,\n            \"pricing\": {\n              \"tiers\": [\n                {\n                  \"maxInputTokens\": 32000,\n                  \"input\": 6,\n                  \"cachedInput\": 1.2,\n                  \"explicitCachedInput\": 0.6,\n                  \"cacheCreationInput\": 7.5,\n                  \"output\": 24\n                },\n                {\n                  \"maxInputTokens\": 200000,\n                  \"input\": 8,\n                  \"cachedInput\": 1.6,\n                  \"explicitCachedInput\": 0.8,\n                  \"cacheCreationInput\": 10,\n                  \"output\": 28\n                }\n              ]\n            },\n            \"extraBody\": {\n              \"preserve_thinking\": true\n            }\n          }\n        }\n      }\n    }\n  }\n  ```\n  内置 token 价格覆盖 Codex GPT 模型（USD）、DashScope `qwen3.7-max`、`qwen3.7-plus`、`glm-5.1`、`glm-5.2`（CNY），DeepSeek `deepseek-v4-flash`、`deepseek-v4-pro`、`deepseek-chat`、`deepseek-reasoner`（CNY），以及 OpenCode Go 模型（`hy3`、`gpt-5.6-luna`、`glm-5.2`、`grok-4.5`、`deepseek-v4-flash`、`deepseek-v4-pro`、`kimi-k2.7-code`、`kimi-k3`、`mimo-v2.5`、`mimo-v2.5-pro`、`qwen3.7-plus`、`qwen3.7-max`、`minimax-m2.7`、`minimax-m3`，USD）。用户配置的 `pricing` 优先于内置价格。DashScope 若上游 usage 中出现 `cache_creation_input_tokens` 字段，cached tokens 按显式缓存读价计费；否则 `cachedInput` 作为隐式缓存读价。DeepSeek 的 `prompt_cache_hit_tokens` 会归入 cached input，`prompt_cache_miss_tokens` 会归入普通 input。\n- **smallModel：** 无工具预热消息的回退模型（例如 Claude Code 的探测请求）；默认是 `gpt-5-mini`。网关会对无工具的预热或探测请求强制使用该小模型，以避免消耗 premium 请求。该行为仅在 GitHub Copilot 账户为非 token-based 计费时生效（`token_based_billing` 为 false）；对于 token-based 计费账户，预热小模型回退会被跳过，因为不存在需要节省的 premium 请求配额。\n- **contextManagement：** 控制代理是否为 Responses API 附加 `context_management` 压缩指令。`messages` 作用于被翻译成 Responses API 的 Anthropic 风格 `/v1/messages` 请求，包括 `openai-responses` provider 的 Messages 路由，默认值为 `true`。`responses` 作用于 native `/v1/responses` 流量，包括 `provider/model` 别名和内置 `codex` provider，默认值为 `false`。只有在确认客户端支持 context management compaction 后，才建议在 Responses API 下启用 `responses`。启用后，请求体会带上 `context_management`，并在后续轮次中仅保留最新的压缩承载内容。**注意：** 对于 GPT-5.6 及以上模型（如 `gpt-5.6-sol`、`gpt-5.6-terra`、`gpt-5.6-luna`），context management 功能会被强制禁用，因为开启后会破坏这些模型的 prompt 缓存命中。此强制覆盖优先于 `contextManagement` 和 `modelResponsesApiCompactThresholds` 配置。\n - **modelResponsesApiCompactThresholds：** 按模型覆盖 Responses API 的 `compact_threshold`，仅在代理自动附加 `context_management` 时使用。它的优先级高于 `resolveResponsesCompactThreshold` 基于 `max_prompt_tokens * ratio` 的兜底阈值。默认将 `gpt-5.4` 和 `gpt-5.5` 设为 `217600`（`272000 * 0.8`）。未列出的模型继续使用原有兜底逻辑。\n- **modelReasoningEfforts：** `/v1/messages` 请求的模型级默认推理强度。仅当请求没有传入 `output_config.effort` 时，该配置才会生效。\n  - **优先级：** 请求中的 `output_config.effort` > `modelReasoningEfforts[model]` > 内置默认值（GPT-5.3+ 模型为 `xhigh`，其他模型为 `high`）。\n  - **转发字段：** 走 Copilot 原生 Messages API 时，最终值写入 `output_config.effort`；转换为 Responses API 时，最终值写入 `reasoning.effort`。\n  - **配置可选值：** `none`、`minimal`、`low`、`medium`、`high`、`xhigh`、`max`。\n- **useMessagesApi：** 当为 `true` 时，支持 Copilot 原生 `/v1/messages` 的 Claude 系模型会走 Messages API；否则回退到 `/chat/completions`。设为 `false` 可禁用 Messages API 路由，始终使用 `/chat/completions`。默认值为 `true`。\n- **useResponsesApiWebSocket：** 当为 `true` 时，Responses API 请求会优先对声明了 `ws:/responses` 的模型使用 Copilot websocket transport；仅声明 `/responses` 的模型仍走 HTTP。设为 `false` 可禁用 websocket 路由，并在模型支持 `/responses` 时使用 HTTP `/responses`。默认值为 `true`。如果遇到 Responses API WebSocket closed，一般是自己的网络问题。如果使用了 VPN，建议切换节点。\n- **useResponsesApiWebSearch：** 当为 `true` 时，服务端会保留 Responses API 中 `type: \"web_search\"` 的工具并透传到上游。设为 `false` 则会从 `/responses` payload 中移除这些工具。默认值为 `true`。\n- **messageApiWebSearchModel：** 顶层 Copilot `/v1/messages` 请求只包含服务端 `web_search` 工具时使用的全局模型，默认值为 `gpt-5-mini`。如果该值是 `provider/model` 别名，请求会进入对应 provider 的 Messages API 路径，并在转发前移除 provider 前缀。对于 Copilot GPT 模型，web search 会通过 `/responses` 执行。混合 `web_search` 与自定义工具的场景暂不支持，服务端会移除 server-side `web_search`。\n- **claudeAutoModel：** 用于 Claude Code 后台 security-monitor 请求的模型，作用于 `/v1/messages` 和 provider Messages 路由。当请求不带任何工具、`stop_sequences` 为 `[\"</block>\"]`，且 system 文本块以 `You are a security monitor for autonomous AI coding agents.` 开头时，会被识别为 security-monitor 请求，其模型会被替换为该配置值。对于顶层请求，`provider/model` 别名会转发到对应 provider 的 Messages API；对于 provider 路由，则保持当前 provider，直接使用该配置值。默认为空（禁用）。\n- **claudeTokenMultiplier：** 用于 Claude `/v1/messages/count_tokens` 请求在本地走 GPT tokenizer 估算时的乘数。默认值为 `1.15`。如果你的客户端仍然过晚触发上下文压缩，可以适当调大。这个配置只会在代理本地估算 Claude token 时生效；如果已经配置 `anthropicApiKey` 且 Anthropic token counting 调用成功，则会直接返回 Anthropic 的精确计数，不会使用这个乘数。\n- **anthropicApiKey：** 用于把 Claude `/v1/messages/count_tokens` 请求转发到 Anthropic 真实 token counting 端点的 API key，这样会返回精确计数，而不是 GPT tokenizer 估算值。也可通过环境变量 `ANTHROPIC_API_KEY` 设置。若未配置，或上游调用失败，则回退到由 `claudeTokenMultiplier` 控制的本地 GPT tokenizer 估算。\n\n编辑此文件后即可自定义 prompts，或替换为你自己的快速模型。修改完成后请重启服务（或重新执行命令），让缓存中的配置刷新生效。\n\n## API 认证\n\n- **受保护的普通路由：** 当配置了 `auth.apiKeys` 且非空时，除 `/`、`/usage-viewer` 和 `/usage-viewer/` 以外的普通路由都需要认证。\n- **Admin 路由：** 所有 `/admin/*` 路由都要求 `auth.adminApiKey`。如果缺失，服务会在启动时自动生成并在开始提供服务前写回 `config.json`。\n- **允许的认证头：**\n  - `x-api-key: <your_key>`\n  - `Authorization: Bearer <your_key>`\n- **CORS 预检：** `OPTIONS` 请求始终允许。\n- **未配置普通 key 时：** 普通路由仍可直接访问；但这条规则不适用于 `/admin/*`，后者只接受 `auth.adminApiKey`。\n\n普通受保护路由的示例请求：\n\n```sh\ncurl http://localhost:4141/v1/models \\\n  -H \"x-api-key: your_api_key\"\n```\n\nAdmin 路由的示例请求：\n\n```sh\ncurl http://localhost:4141/admin/config/model-mappings \\\n  -H \"x-api-key: your_admin_api_key\"\n```\n\n## API 端点\n\n服务端提供多个 OpenAI / Anthropic 兼容端点。请求会根据所选模型和 `provider/model` 别名路由到 GitHub Copilot、内置 `codex` provider 或已配置的 provider。\n\n### OpenAI 兼容端点\n\n这些端点模拟 OpenAI API 结构。\n\n| 端点 | 方法 | 说明 |\n| --- | --- | --- |\n| `POST /v1/responses` | `POST` | OpenAI 中用于生成模型响应的高级接口。支持 `openai-responses` provider 的 `provider/model` 别名。 |\n| `POST /v1/chat/completions` | `POST` | 为给定聊天对话创建模型响应。支持 `openai-compatible` provider 的 `provider/model` 别名；目标 provider 已配置时可在没有 Copilot 的情况下使用。 |\n| `GET /v1/models` | `GET` | 列出 Copilot 模型以及已启用 provider 的 `provider/model-id` 模型。来自 Codex 客户端（`User-Agent` 以 `codex` 开头）的请求会转发到 Codex Models 上游。 |\n| `POST /v1/embeddings` | `POST` | 创建表示输入文本的向量嵌入。 |\n\n### Codex 后端代理端点\n\n这些端点要求已有可用的 Codex 登录态。每个端点同时提供无版本前缀和 `/v1` 两种路径。\n\n| 端点 | 方法 | 说明 |\n| --- | --- | --- |\n| `POST /alpha/search`<br>`POST /v1/alpha/search` | `POST` | 将 JSON 请求体和查询参数透明转发到 Codex Alpha Search 上游。 |\n| `POST /images/generations`<br>`POST /v1/images/generations` | `POST` | 将 JSON 图片生成请求转发到 Codex Images 上游。请求未携带 `Content-Type` 时，网关默认补充 `application/json`。 |\n| `POST /images/edits`<br>`POST /v1/images/edits` | `POST` | 将图片编辑请求转发到 Codex Images 上游。请使用 `multipart/form-data`，并让 HTTP 客户端自动生成 `boundary`；网关会保留传入的 content type，并以流式方式转发上传请求体。 |\n\n对于以上所有端点，网关都会使用当前 Codex 登录态覆盖客户端的 authorization 和 account header，保留查询参数及兼容的请求头，并返回上游状态码、响应头和响应体。\n\n### Anthropic 兼容端点\n\n这些端点设计为兼容 Anthropic Messages API。provider 级的 models、Responses、alpha-search 和 images 路由同时支持无版本前缀与 `/v1` 两种路径；Messages 路由仍使用 `/v1`。\n\n| 端点 | 方法 | 说明 |\n| --- | --- | --- |\n| `POST /v1/messages` | `POST` | 为给定对话创建模型响应。支持已配置 provider 的 `provider/model` 别名，包括通过 `openai-compatible` provider 做翻译。 |\n| `POST /v1/messages/count_tokens` | `POST` | 计算一组消息的 token 数。支持已配置 provider 的 `provider/model` 别名。 |\n| `POST /:provider/v1/messages` | `POST` | 将 Anthropic Messages 请求代理到已配置的 Anthropic provider，或翻译到 OpenAI 兼容 / OpenAI Responses provider。 |\n| `GET /:provider/models`<br>`GET /:provider/v1/models` | `GET` | 将模型列表请求代理到已配置的 provider。对 `codex` 默认返回内置模型目录；Codex 客户端（`User-Agent` 以 `codex` 开头）会转发到 Codex Models 上游。 |\n| `POST /:provider/v1/messages/count_tokens` | `POST` | 为 provider 路由请求在本地计算 token 数。 |\n| `POST /:provider/responses`<br>`POST /:provider/v1/responses` | `POST` | 将 OpenAI Responses 请求代理到已配置的 `openai-responses` provider（含 `codex`）。 |\n| `POST /:provider/alpha/search`<br>`POST /:provider/v1/alpha/search` | `POST` | 代理 alpha-search 请求。对 `codex` 转发到 Codex Alpha Search 上游；其他 provider 转发到 `{baseUrl}/v1/alpha/search`。 |\n| `POST /:provider/images/generations`<br>`POST /:provider/v1/images/generations` | `POST` | 代理图片生成。对 `codex` 使用 Codex Images 上游；其他 provider 转发到 `{baseUrl}/v1/images/generations`（15 分钟超时）。 |\n| `POST /:provider/images/edits`<br>`POST /:provider/v1/images/edits` | `POST` | 代理图片编辑。对 `codex` 使用 Codex Images 上游；其他 provider 以 multipart/流式方式转发到 `{baseUrl}/v1/images/edits`（15 分钟超时）。 |\n\n### 使用量监控端点\n\n用于监控 Copilot 用量与额度的新端点。\n\n| 端点 | 方法 | 说明 |\n| --- | --- | --- |\n| `GET /usage` | `GET` | 获取详细的 Copilot 使用统计与额度信息。 |\n| `GET /token` | `GET` | 获取当前 API 正在使用的 Copilot token。 |\n\n### Admin / 配置端点\n\n这些端点用于本地管理操作，只接受 `auth.adminApiKey`。\n\n| 端点 | 方法 | 说明 |\n| --- | --- | --- |\n| `GET /admin/config/model-mappings` | `GET` | 返回当前 `config.json` 路径以及生效中的 `modelMappings` 映射。 |\n| `POST /admin/config/model-mappings` | `POST` | 只更新 `config.json` 里的 `modelMappings` 字段，并回传更新后的结果。 |\n\n## 使用示例\n\n常用 `npx` 命令：\n\n```sh\n# 基础启动\nnpx @jeffreycao/copilot-api@latest start\n\n# 自定义端口并开启详细日志\nnpx @jeffreycao/copilot-api@latest start --port 8080 --verbose\n\n# 执行认证流程\nnpx @jeffreycao/copilot-api@latest auth login\n\n# 配置第三方 provider，然后不依赖 GitHub Copilot 启动\nnpx @jeffreycao/copilot-api@latest auth login --provider dashscope\nnpx @jeffreycao/copilot-api@latest start\n\n# 以 JSON 格式输出调试信息\nnpx @jeffreycao/copilot-api@latest debug --json\n\n# 用 Bun 而不是 Node.js 运行已发布 CLI\nbunx --bun @jeffreycao/copilot-api@latest start\n```\n\n配置 `dashscope` 后的 OpenAI 兼容 provider 调用示例：\n\n```sh\ncurl http://localhost:4141/v1/chat/completions \\\n  -H \"content-type: application/json\" \\\n  -d '{\"model\":\"dashscope/qwen3.6-plus\",\"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]}'\n\ncurl http://localhost:4141/dashscope/v1/messages \\\n  -H \"content-type: application/json\" \\\n  -d '{\"model\":\"qwen3.6-plus\",\"max_tokens\":1024,\"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]}'\n```\n\n## 使用建议\n\n<a id=\"claudemd-or-agentsmd-recommended-content\"></a>\n\n### CLAUDE.md 或 AGENTS.md 推荐内容\n\n如果你想手动加入这些提醒，请在 Claude Code 的 `CLAUDE.md`，或 opencode/codex 的 `AGENTS.md` 中加入以下内容：\n\n```\n- Prohibited from directly asking questions to users, MUST use question tool.\n- Once you can confirm that the task is complete, MUST use question tool to make user confirm. The user may respond with feedback if they are not satisfied with the result, which you can use to make improvements and try again, after try again, MUST use question tool to make user confirm again.\n```\n"}}, "tests/auth-login.test.ts": {"d66d4fb4afedd4462dd2bd1d041501b112d4d52e": {"t": 1786068367.4949315, "n": 19969, "h": "39689ebf63aea681", "c": "import { afterEach, describe, expect, test } from \"bun:test\"\nimport fs from \"node:fs\"\nimport os from \"node:os\"\nimport path from \"node:path\"\nimport { fileURLToPath } from \"node:url\"\n\ninterface ConfigFileShape {\n  providers?: Record<\n    string,\n    {\n      apiKey?: string\n      authType?: string\n      baseUrl?: string\n      enabled?: boolean\n      models?: Record<string, unknown>\n      pricingCurrency?: string\n      type?: string\n    }\n  >\n}\n\ninterface PromptCall {\n  message: string\n  options: {\n    default?: string\n    initial?: string\n    type?: string\n  }\n}\n\nconst cwd = fileURLToPath(new URL(\"../\", import.meta.url))\nconst decoder = new TextDecoder()\nconst tempDirs: Array<string> = []\n\nfunction createTempDir(): string {\n  const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), \"copilot-api-auth-\"))\n  tempDirs.push(tempDir)\n  return tempDir\n}\n\nfunction writeConfigFile(tempDir: string, config: ConfigFileShape): void {\n  fs.writeFileSync(\n    path.join(tempDir, \"config.json\"),\n    `${JSON.stringify(config, null, 2)}\\n`,\n    \"utf8\",\n  )\n}\n\nfunction readConfigFile(tempDir: string): ConfigFileShape {\n  return JSON.parse(\n    fs.readFileSync(path.join(tempDir, \"config.json\"), \"utf8\"),\n  ) as ConfigFileShape\n}\n\nfunction runScript(tempDir: string, script: string): string {\n  const result = Bun.spawnSync({\n    cmd: [process.execPath, \"--eval\", script],\n    cwd,\n    env: {\n      ...process.env,\n      COPILOT_API_HOME: tempDir,\n      COPILOT_API_OAUTH_APP: \"\",\n      COPILOT_API_ENTERPRISE_URL: \"\",\n    },\n  })\n\n  if (result.exitCode !== 0) {\n    throw new Error(\n      `Script failed with exit code ${result.exitCode}\\nstdout:\\n${decoder.decode(result.stdout)}\\nstderr:\\n${decoder.decode(result.stderr)}`,\n    )\n  }\n\n  return decoder.decode(result.stdout).trim()\n}\n\nafterEach(() => {\n  while (tempDirs.length > 0) {\n    fs.rmSync(tempDirs.pop()!, { recursive: true, force: true })\n  }\n})\n\ndescribe(\"auth login validation\", () => {\n  test(\"rejects an unknown provider name before starting a login flow\", () => {\n    const tempDir = createTempDir()\n    writeConfigFile(tempDir, {})\n\n    const output = runScript(\n      tempDir,\n      'const { runAuthLogin } = await import(\"./src/auth\"); try { await runAuthLogin({ provider: \"unknown\", verbose: false, showToken: false }); console.log(\"unexpected-success\"); } catch (error) { console.log((error instanceof Error ? error.message : String(error)).trim()); }',\n    )\n\n    expect(output).toBe(\n      \"Unknown provider 'unknown'. Expected one of: copilot, codex, opencode-go, deepseek, dashscope, openrouter, custom\",\n    )\n  })\n\n  test(\"configures deepseek from the quick provider template with defaults\", () => {\n    const tempDir = createTempDir()\n    writeConfigFile(tempDir, {})\n\n    const output = runScript(\n      tempDir,\n      `\n      const consolaModule = await import(\"consola\");\n      const consola = consolaModule.default ?? consolaModule;\n      const answers = [\"deepseek-key\", \"__default__\", \"\"];\n      const promptCalls = [];\n      consola.prompt = async (message, options) => {\n        promptCalls.push({ message, options });\n        return answers.shift();\n      };\n      consola.info = () => {};\n      consola.success = () => {};\n      const { runAuthLogin } = await import(\"./src/auth\");\n      await runAuthLogin({ provider: \"deepseek\", verbose: false, showToken: false });\n      console.log(JSON.stringify(promptCalls));\n      `,\n    )\n\n    const promptCalls = JSON.parse(output) as Array<PromptCall>\n    expect(promptCalls[2]).toMatchObject({\n      message:\n        \"Enter provider baseUrl (default: https://api.deepseek.com/anthropic)\",\n      options: {\n        default: \"https://api.deepseek.com/anthropic\",\n        initial: \"https://api.deepseek.com/anthropic\",\n        type: \"text\",\n      },\n    })\n    expect(readConfigFile(tempDir).providers?.deepseek).toEqual({\n      apiKey: \"deepseek-key\",\n      baseUrl: \"https://api.deepseek.com/anthropic\",\n      enabled: true,\n      pricingCurrency: \"CNY\",\n      type: \"anthropic\",\n    })\n  })\n\n  test(\"masks quick provider apiKey input in an interactive terminal\", () => {\n    const tempDir = createTempDir()\n    writeConfigFile(tempDir, {})\n\n    const output = runScript(\n      tempDir,\n      `\n      const consolaModule = await import(\"consola\");\n      const consola = consolaModule.default ?? consolaModule;\n      const answers = [\"__default__\", \"\"];\n      const writes = [];\n      const rawModes = [];\n      const originalWrite = process.stdout.write.bind(process.stdout);\n      Object.defineProperty(process.stdin, \"isTTY\", { value: true, configurable: true });\n      Object.defineProperty(process.stdout, \"isTTY\", { value: true, configurable: true });\n      process.stdin.setRawMode = (enabled) => {\n        rawModes.push(enabled);\n        return process.stdin;\n      };\n      process.stdin.resume = () => {\n        queueMicrotask(() => process.stdin.emit(\"data\", Buffer.from(\"masked-key\\\\r\")));\n        return process.stdin;\n      };\n      process.stdin.pause = () => process.stdin;\n      process.stdout.write = (chunk, encoding, callback) => {\n        writes.push(String(chunk));\n        if (typeof encoding === \"function\") encoding();\n        if (typeof callback === \"function\") callback();\n        return true;\n      };\n      consola.prompt = async () => answers.shift();\n      consola.info = () => {};\n      consola.success = () => {};\n      const { runAuthLogin } = await import(\"./src/auth\");\n      await runAuthLogin({ provider: \"deepseek\", verbose: false, showToken: false });\n      process.stdout.write = originalWrite;\n      console.log(JSON.stringify({ rawModes, writes: writes.join(\"\") }));\n      `,\n    )\n\n    const maskedPromptOutput = JSON.parse(output) as {\n      rawModes: Array<boolean>\n      writes: string\n    }\n\n    expect(maskedPromptOutput.rawModes).toEqual([true, false])\n    expect(maskedPromptOutput.writes).toContain(\n      \"Enter deepseek apiKey: **********\\n\",\n    )\n    expect(maskedPromptOutput.writes).not.toContain(\"masked-key\")\n    expect(readConfigFile(tempDir).providers?.deepseek).toEqual({\n      apiKey: \"masked-key\",\n      baseUrl: \"https://api.deepseek.com/anthropic\",\n      enabled: true,\n      pricingCurrency: \"CNY\",\n      type: \"anthropic\",\n    })\n  })\n\n  test(\"configures deepseek with custom quick provider type and baseUrl\", () => {\n    const tempDir = createTempDir()\n    writeConfigFile(tempDir, {})\n\n    runScript(\n      tempDir,\n      `\n      const consolaModule = await import(\"consola\");\n      const consola = consolaModule.default ?? consolaModule;\n      const answers = [\"deepseek-key\", \"anthropic\", \"https://deepseek.example///\"];\n      consola.prompt = async () => answers.shift();\n      consola.info = () => {};\n      consola.success = () => {};\n      const { runAuthLogin } = await import(\"./src/auth\");\n      await runAuthLogin({ provider: \"deepseek\", verbose: false, showToken: false });\n      `,\n    )\n\n    expect(readConfigFile(tempDir).providers?.deepseek).toEqual({\n      apiKey: \"deepseek-key\",\n      baseUrl: \"https://deepseek.example\",\n      enabled: true,\n      pricingCurrency: \"CNY\",\n      type: \"anthropic\",\n    })\n  })\n\n  test(\"configures dashscope from the quick provider template with defaults\", () => {\n    const tempDir = createTempDir()\n    writeConfigFile(tempDir, {})\n\n    runScript(\n      tempDir,\n      `\n      const consolaModule = await import(\"consola\");\n      const consola = consolaModule.default ?? consolaModule;\n      const answers = [\"dashscope-key\", \"__default__\", \"\"];\n      consola.prompt = async () => answers.shift();\n      consola.info = () => {};\n      consola.success = () => {};\n      const { runAuthLogin } = await import(\"./src/auth\");\n      await runAuthLogin({ provider: \"dashscope\", verbose: false, showToken: false });\n      `,\n    )\n\n    expect(readConfigFile(tempDir).providers?.dashscope).toEqual({\n      apiKey: \"dashscope-key\",\n      baseUrl: \"https://dashscope.aliyuncs.com/compatible-mode\",\n      enabled: true,\n      pricingCurrency: \"CNY\",\n      type: \"openai-compatible\",\n    })\n  })\n\n  test(\"configures dashscope with custom quick provider type and baseUrl\", () => {\n    const tempDir = createTempDir()\n    writeConfigFile(tempDir, {})\n\n    runScript(\n      tempDir,\n      `\n      const consolaModule = await import(\"consola\");\n      const consola = consolaModule.default ?? consolaModule;\n      const answers = [\"dashscope-key\", \"openai-responses\", \"https://dashscope.example/api///\"];\n      consola.prompt = async () => answers.shift();\n      consola.info = () => {};\n      consola.success = () => {};\n      const { runAuthLogin } = await import(\"./src/auth\");\n      await runAuthLogin({ provider: \"dashscope\", verbose: false, showToken: false });\n      `,\n    )\n\n    expect(readConfigFile(tempDir).providers?.dashscope).toEqual({\n      apiKey: \"dashscope-key\",\n      baseUrl: \"https://dashscope.example/api\",\n      enabled: true,\n      pricingCurrency: \"CNY\",\n      type: \"openai-responses\",\n    })\n  })\n\n  test(\"configures openrouter as an anthropic quick provider\", () => {\n    const tempDir = createTempDir()\n    writeConfigFile(tempDir, {})\n\n    runScript(\n      tempDir,\n      `\n      const consolaModule = await import(\"consola\");\n      const consola = consolaModule.default ?? consolaModule;\n      const answers = [\"openrouter-key\", \"\"];\n      consola.prompt = async () => answers.shift();\n      consola.info = () => {};\n      consola.success = () => {};\n      const { runAuthLogin } = await import(\"./src/auth\");\n      await runAuthLogin({ provider: \"openrouter\", verbose: false, showToken: false });\n      `,\n    )\n\n    expect(readConfigFile(tempDir).providers?.openrouter).toEqual({\n      apiKey: \"openrouter-key\",\n      baseUrl: \"https://openrouter.ai/api\",\n      enabled: true,\n      pricingCurrency: \"USD\",\n      type: \"anthropic\",\n    })\n  })\n\n  test(\"configures openrouter with a custom baseUrl but fixed anthropic type\", () => {\n    const tempDir = createTempDir()\n    writeConfigFile(tempDir, {})\n\n    runScript(\n      tempDir,\n      `\n      const consolaModule = await import(\"consola\");\n      const consola = consolaModule.default ?? consolaModule;\n      const answers = [\"openrouter-key\", \"https://openrouter.example/api///\"];\n      consola.prompt = async () => answers.shift();\n      consola.info = () => {};\n      consola.success = () => {};\n      const { runAuthLogin } = await import(\"./src/auth\");\n      await runAuthLogin({ provider: \"openrouter\", verbose: false, showToken: false });\n      `,\n    )\n\n    expect(readConfigFile(tempDir).providers?.openrouter).toEqual({\n      apiKey: \"openrouter-key\",\n      baseUrl: \"https://openrouter.example/api\",\n      enabled: true,\n      pricingCurrency: \"USD\",\n      type: \"anthropic\",\n    })\n  })\n\n  test(\"configures opencode-go as a fixed openai-compatible quick provider\", () => {\n    const tempDir = createTempDir()\n    writeConfigFile(tempDir, {})\n\n    runScript(\n      tempDir,\n      `\n      const consolaModule = await import(\"consola\");\n      const consola = consolaModule.default ?? consolaModule;\n      const answers = [\"opencode-key\", \"\"];\n      consola.prompt = async () => answers.shift();\n      consola.info = () => {};\n      consola.success = () => {};\n      const { runAuthLogin } = await import(\"./src/auth\");\n      await runAuthLogin({ provider: \"opencode-go\", verbose: false, showToken: false });\n      `,\n    )\n\n    expect(readConfigFile(tempDir).providers?.[\"opencode-go\"]).toEqual({\n      apiKey: \"opencode-key\",\n      baseUrl: \"https://opencode.ai/zen/go\",\n      enabled: true,\n      pricingCurrency: \"USD\",\n      type: \"openai-compatible\",\n    })\n  })\n\n  test(\"configures opencode-go with a custom baseUrl but fixed openai-compatible type\", () => {\n    const tempDir = createTempDir()\n    writeConfigFile(tempDir, {})\n\n    runScript(\n      tempDir,\n      `\n      const consolaModule = await import(\"consola\");\n      const consola = consolaModule.default ?? consolaModule;\n      const answers = [\"opencode-key\", \"https://opencode.example/zen/go///\"];\n      consola.prompt = async () => answers.shift();\n      consola.info = () => {};\n      consola.success = () => {};\n      const { runAuthLogin } = await import(\"./src/auth\");\n      await runAuthLogin({ provider: \"opencode-go\", verbose: false, showToken: false });\n      `,\n    )\n\n    expect(readConfigFile(tempDir).providers?.[\"opencode-go\"]).toEqual({\n      apiKey: \"opencode-key\",\n      baseUrl: \"https://opencode.example/zen/go\",\n      enabled: true,\n      pricingCurrency: \"USD\",\n      type: \"openai-compatible\",\n    })\n  })\n\n  test(\"preserves quick provider model settings when reconfiguring credentials\", () => {\n    const tempDir = createTempDir()\n    writeConfigFile(tempDir, {\n      providers: {\n        dashscope: {\n          apiKey: \"old-key\",\n          baseUrl: \"https://old.example\",\n          enabled: true,\n          models: {\n            \"qwen-plus\": {\n              temperature: 0.2,\n            },\n          },\n          type: \"openai-compatible\",\n        },\n      },\n    })\n\n    runScript(\n      tempDir,\n      `\n      const consolaModule = await import(\"consola\");\n      const consola = consolaModule.default ?? consolaModule;\n      const answers = [\"new-key\", \"__default__\", \"\"];\n      consola.prompt = async () => answers.shift();\n      consola.info = () => {};\n      consola.success = () => {};\n      const { runAuthLogin } = await import(\"./src/auth\");\n      await runAuthLogin({ provider: \"dashscope\", verbose: false, showToken: false });\n      `,\n    )\n\n    expect(readConfigFile(tempDir).providers?.dashscope).toEqual({\n      apiKey: \"new-key\",\n      baseUrl: \"https://dashscope.aliyuncs.com/compatible-mode\",\n      enabled: true,\n      models: {\n        \"qwen-plus\": {\n          temperature: 0.2,\n        },\n      },\n      pricingCurrency: \"CNY\",\n      type: \"openai-compatible\",\n    })\n  })\n\n  test(\"configures a custom provider with the default auth type\", () => {\n    const tempDir = createTempDir()\n    writeConfigFile(tempDir, {})\n\n    runScript(\n      tempDir,\n      `\n      const consolaModule = await import(\"consola\");\n      const consola = consolaModule.default ?? consolaModule;\n      const answers = [\"dash\", \"openai-compatible\", \"https://dashscope.example///\", \"provider-key\", \"__default__\"];\n      consola.prompt = async () => answers.shift();\n      consola.info = () => {};\n      consola.success = () => {};\n      const { runAuthLogin } = await import(\"./src/auth\");\n      await runAuthLogin({ provider: \"custom\", verbose: false, showToken: false });\n      `,\n    )\n\n    expect(readConfigFile(tempDir).providers?.dash).toEqual({\n      apiKey: \"provider-key\",\n      baseUrl: \"https://dashscope.example\",\n      enabled: true,\n      type: \"openai-compatible\",\n    })\n  })\n\n  test(\"configures a custom provider selected from the provider prompt\", () => {\n    const tempDir = createTempDir()\n    writeConfigFile(tempDir, {})\n\n    runScript(\n      tempDir,\n      `\n      const consolaModule = await import(\"consola\");\n      const consola = consolaModule.default ?? consolaModule;\n      const answers = [\"custom\", \"claude\", \"anthropic\", \"https://api.anthropic.example\", \"provider-key\", \"x-api-key\"];\n      consola.prompt = async () => answers.shift();\n      consola.info = () => {};\n      consola.success = () => {};\n      const { runAuthLogin } = await import(\"./src/auth\");\n      await runAuthLogin({ provider: undefined, verbose: false, showToken: false });\n      `,\n    )\n\n    expect(readConfigFile(tempDir).providers?.claude).toEqual({\n      apiKey: \"provider-key\",\n      authType: \"x-api-key\",\n      baseUrl: \"https://api.anthropic.example\",\n      enabled: true,\n      type: \"anthropic\",\n    })\n  })\n\n  test(\"writes the selected authorization auth type\", () => {\n    const tempDir = createTempDir()\n    writeConfigFile(tempDir, {})\n\n    runScript(\n      tempDir,\n      `\n      const consolaModule = await import(\"consola\");\n      const consola = consolaModule.default ?? consolaModule;\n      const answers = [\"responses\", \"openai-responses\", \"https://responses.example\", \"provider-key\", \"authorization\"];\n      consola.prompt = async () => answers.shift();\n      consola.info = () => {};\n      consola.success = () => {};\n      const { runAuthLogin } = await import(\"./src/auth\");\n      await runAuthLogin({ provider: \"custom\", verbose: false, showToken: false });\n      `,\n    )\n\n    expect(readConfigFile(tempDir).providers?.responses).toEqual({\n      apiKey: \"provider-key\",\n      authType: \"authorization\",\n      baseUrl: \"https://responses.example\",\n      enabled: true,\n      type: \"openai-responses\",\n    })\n  })\n\n  test(\"preserves custom provider model settings when reconfiguring credentials\", () => {\n    const tempDir = createTempDir()\n    writeConfigFile(tempDir, {\n      providers: {\n        dash: {\n          apiKey: \"old-key\",\n          authType: \"x-api-key\",\n          baseUrl: \"https://old.example\",\n          enabled: true,\n          models: {\n            \"qwen-plus\": {\n              temperature: 0.2,\n            },\n          },\n          type: \"anthropic\",\n        },\n      },\n    })\n\n    runScript(\n      tempDir,\n      `\n      const consolaModule = await import(\"consola\");\n      const consola = consolaModule.default ?? consolaModule;\n      const answers = [\"dash\", \"openai-compatible\", \"https://new.example\", \"new-key\", \"__default__\"];\n      consola.prompt = async () => answers.shift();\n      consola.info = () => {};\n      consola.success = () => {};\n      const { runAuthLogin } = await import(\"./src/auth\");\n      await runAuthLogin({ provider: \"custom\", verbose: false, showToken: false });\n      `,\n    )\n\n    expect(readConfigFile(tempDir).providers?.dash).toEqual({\n      apiKey: \"new-key\",\n      baseUrl: \"https://new.example\",\n      enabled: true,\n      models: {\n        \"qwen-plus\": {\n          temperature: 0.2,\n        },\n      },\n      type: \"openai-compatible\",\n    })\n  })\n\n  test(\"rejects invalid custom provider inputs without writing provider config\", () => {\n    const cases: Array<{ answers: Array<string>; message: string }> = [\n      {\n        answers: [\"copilot\"],\n        message: \"Provider name 'copilot' is reserved for a builtin provider\",\n      },\n      {\n        answers: [\"codex\"],\n        message: \"Provider name 'codex' is reserved for a builtin provider\",\n      },\n      {\n        answers: [\"bad/name\"],\n        message:\n          \"Provider name must start with a letter or number and contain only letters, numbers, underscores, or hyphens\",\n      },\n      {\n        answers: [\"dash\", \"unsupported\"],\n        message: \"No provider type selected\",\n      },\n      {\n        answers: [\"dash\", \"anthropic\", \"   \"],\n        message: \"baseUrl must be a non-empty string\",\n      },\n      {\n        answers: [\"dash\", \"anthropic\", \"https://example.com\", \"   \"],\n        message: \"apiKey must be a non-empty string\",\n      },\n      {\n        answers: [\n          \"dash\",\n          \"anthropic\",\n          \"https://example.com\",\n          \"provider-key\",\n          \"oauth2\",\n        ],\n        message: \"No provider auth type selected\",\n      },\n    ]\n\n    for (const item of cases) {\n      const tempDir = createTempDir()\n      writeConfigFile(tempDir, {})\n\n      const output = runScript(\n        tempDir,\n        `\n        const consolaModule = await import(\"consola\");\n        const consola = consolaModule.default ?? consolaModule;\n        const answers = ${JSON.stringify(item.answers)};\n        consola.prompt = async () => answers.shift();\n        consola.info = () => {};\n        consola.success = () => {};\n        const { runAuthLogin } = await import(\"./src/auth\");\n        try {\n          await runAuthLogin({ provider: \"custom\", verbose: false, showToken: false });\n          console.log(\"unexpected-success\");\n        } catch (error) {\n          console.log((error instanceof Error ? error.message : String(error)).trim());\n        }\n        `,\n      )\n\n      expect(output).toBe(item.message)\n      expect(readConfigFile(tempDir).providers).toBeUndefined()\n    }\n  })\n})\n"}}}}