{"id":48431395,"url":"https://github.com/caozhiyuan/copilot-api","last_synced_at":"2026-05-23T14:02:10.910Z","repository":{"id":316680871,"uuid":"1041202099","full_name":"caozhiyuan/copilot-api","owner":"caozhiyuan","description":"OpenAI and Anthropic-compatible gateway for GitHub Copilot or third-party providers. Please read README.md completely before use!","archived":false,"fork":false,"pushed_at":"2026-05-19T02:56:06.000Z","size":1995,"stargazers_count":793,"open_issues_count":0,"forks_count":164,"subscribers_count":9,"default_branch":"dev","last_synced_at":"2026-05-19T04:59:00.272Z","etag":null,"topics":["github-copilot"],"latest_commit_sha":null,"homepage":"https://caozhiyuan.github.io/copilot-api/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"ericc-ch/copilot-api","license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/caozhiyuan.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":"NOTICE.md","maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null},"funding":{"github":null,"patreon":null,"open_collective":null,"ko_fi":"ericc_ch","tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"lfx_crowdfunding":null,"polar":null,"buy_me_a_coffee":null,"thanks_dev":null,"custom":null}},"created_at":"2025-08-20T06:18:02.000Z","updated_at":"2026-05-19T02:55:42.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/caozhiyuan/copilot-api","commit_stats":null,"previous_names":["caozhiyuan/copilot-api"],"tags_count":94,"template":false,"template_full_name":null,"purl":"pkg:github/caozhiyuan/copilot-api","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/caozhiyuan%2Fcopilot-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/caozhiyuan%2Fcopilot-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/caozhiyuan%2Fcopilot-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/caozhiyuan%2Fcopilot-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/caozhiyuan","download_url":"https://codeload.github.com/caozhiyuan/copilot-api/tar.gz/refs/heads/dev","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/caozhiyuan%2Fcopilot-api/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33398391,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-23T04:15:53.637Z","status":"ssl_error","status_checked_at":"2026-05-23T04:15:53.242Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["github-copilot"],"created_at":"2026-04-06T11:01:13.159Z","updated_at":"2026-05-23T14:02:10.902Z","avatar_url":"https://github.com/caozhiyuan.png","language":"TypeScript","funding_links":["https://ko-fi.com/ericc_ch"],"categories":["The latest additions 🎉"],"sub_categories":[],"readme":"# Copilot API Proxy\n\nEnglish | [简体中文](./README.zh-CN.md)\n\n## Important Notes\n\n\u003e [!IMPORTANT]\n\u003e **Before using, please be aware of the following:**\n\u003e\n\u003e 1. **Claude Code configuration:** When using with Claude Code, please configure the model ID as `claude-opus-4-6` or `claude-opus-4.6` (without the `[1m]` suffix, exceeding GitHub Copilot's context window limit too much may lead to being banned). Example claude `settings.json` see [Manual Configuration with `settings.json`](#manual-configuration-with-settingsjson). \n\u003e\n\u003e 2. **Recommend for Opencode:** For opencode, prefer the opencode OAuth app. It matches opencode's built-in GitHub Copilot provider and avoids Terms of Service risk:\n\u003e    ```sh\n\u003e    npx @jeffreycao/copilot-api@latest --oauth-app=opencode start\n\u003e    ```\n\u003e\n\u003e 3. **Built-in `codex` provider:** Run `npx @jeffreycao/copilot-api@latest auth login --provider codex` once and the gateway will persist and refresh Codex OAuth credentials automatically.\n\u003e\n\u003e 4. **Disable multi agent when using codex:** If you're using codex via GitHub Copilot, disable multi agent. Copilot currently charges codex traffic based on whether the last message is a user role, and that billing logic has not been adjusted.\n\u003e\n\u003e 5. **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 reverse-engineered GitHub Copilot integration that also works as a small AI gateway. Besides Copilot, it can route the built-in `codex` provider and configured third-party providers such as DashScope behind OpenAI- and Anthropic-compatible APIs, so tools like [Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview) can use one local endpoint.\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- **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- **Agent-friendly Claude handling on Copilot**: Prefer native `/v1/messages` when available, preserve Claude-style tool flows, support Anthropic beta features, 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- **Local control and visibility**: Includes a usage dashboard, rate limiting, manual approval, and optional token visibility for debugging.\n- **Multi-provider routing**: Expose provider-specific `/:provider/...` routes or use `model: \"provider/model\"` on the top-level API.\n- **Better token and context management**: Supports exact Claude token counting and configurable GPT context compaction for long-running conversations.\n\n## Prerequisites\n\n- Bun (\u003e= 1.2.x)\n- Node.js if you plan to run the published CLI with `npx`\n- GitHub account with Copilot subscription (individual, business, or enterprise)\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## Using with npx\n\nYou can run the project directly using npx:\n\n\u003e [!IMPORTANT]\n\u003e Token usage storage uses Node's built-in `node:sqlite` module when running with `npx`. It is enabled on Node.js \u003e= 22.13.0. On Node.js \u003c 22.13.0, the CLI still starts, but token usage storage is disabled.\n\u003e\n\u003e 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 only:\n\n```sh\nnpx @jeffreycao/copilot-api@latest auth\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 or manual token entry, 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, sign in 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 model mappings through `GET/POST /admin/config/model-mappings`. 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\u003cp align=\"center\"\u003e\n  \u003cimg src=\"./docs/screenshots/desktop-dashboard.png\" alt=\"Copilot API desktop app dashboard\" width=\"49%\" /\u003e\n  \u003cimg src=\"./docs/screenshots/desktop-token-usage.png\" alt=\"Copilot API desktop app token usage view\" width=\"49%\" /\u003e\n\u003c/p\u003e\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 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## Command Structure\n\nCopilot API now uses a subcommand structure with these main commands:\n\n- `start`: Start the Copilot API server. This command will also handle authentication if needed.\n- `auth`: Run GitHub authentication flow without starting the server. This is typically used if you need to generate a token for use with the `--github-token` option, especially in non-interactive environments.\n- `check-usage`: Show your current GitHub Copilot usage and quota information directly in the terminal (no server required).\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| --account-type | Account type to use (individual, business, enterprise)                        | individual | -a    |\n| --manual       | Enable manual request approval                                                | false      | none  |\n| --rate-limit   | Rate limit in seconds between requests                                        | none       | -r    |\n| --wait         | Wait instead of error when rate limit is hit                                  | false      | -w    |\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| --verbose    | Enable verbose logging    | false   | -v    |\n| --show-token | Show GitHub token on auth | false   | none  |\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\": \"\u003cauto-generated-on-startup\u003e\"\n    },\n    \"providers\": {\n      \"custom\": {\n        \"type\": \"anthropic\",\n        \"enabled\": true,\n        \"baseUrl\": \"your-base-url\",\n        \"apiKey\": \"sk-your-provider-key\",\n        \"authType\": \"x-api-key\",\n        \"adjustInputTokens\": false,\n        \"models\": {\n          \"kimi-k2.5\": {\n            \"temperature\": 1,\n            \"topP\": 0.95\n          }\n        }\n      },\n      \"dashscope\": {\n        \"type\": \"openai-compatible\",\n        \"enabled\": true,\n        \"baseUrl\": \"https://dashscope.aliyuncs.com/compatible-mode\",\n        \"apiKey\": \"sk-your-dashscope-key\",\n        \"models\": {\n          \"qwen3.6-plus\": {\n            \"temperature\": 1,\n            \"topP\": 0.95,\n            \"topK\": 20,\n            \"extraBody\": {\n              \"preserve_thinking\": true\n            },\n            \"contextCache\": true\n          },\n          \"glm-5.1\": {\n            \"temperature\": 0.7,\n            \"topP\": 0.95,\n            \"contextCache\": true,\n            \"extraBody\": {\n              \"preserve_thinking\": true\n            }\n          }\n        }\n      }\n    },\n    \"modelMappings\": {},\n    \"extraPrompts\": {\n      \"gpt-5-mini\": \"\u003cbuilt-in exploration prompt\u003e\",\n      \"gpt-5.3-codex\": \"\u003cbuilt-in commentary prompt\u003e\",\n      \"gpt-5.4-mini\": \"\u003cbuilt-in commentary prompt\u003e\",\n      \"gpt-5.4\": \"\u003cbuilt-in commentary prompt\u003e\"\n    },\n    \"smallModel\": \"gpt-5-mini\",\n    \"responsesApiContextManagementModels\": [],\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    },\n    \"useMessagesApi\": true,\n    \"useResponsesApiWebSocket\": true,\n    \"useResponsesApiWebSearch\": true\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: \u003ckey\u003e` or `Authorization: Bearer \u003ckey\u003e`. 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 -\u003e targetModel` rewrites for top-level `POST /v1/messages` and `POST /v1/messages/count_tokens` 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. The admin endpoints `GET/POST /admin/config/model-mappings` read and update only this field.\n- **extraPrompts:** Map of `model -\u003e 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`, and `/v1/responses`; the gateway strips the `dashscope/` prefix before forwarding upstream. `GET /v1/models` does not aggregate provider models; use `GET /dashscope/v1/models` for provider model lists.\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 \u003capiKey\u003e`. `oauth2` is reserved for the built-in `codex` provider and is written automatically by `auth login --provider codex`.\n  - `adjustInputTokens` (optional): When `true`, the proxy will adjust the `input_tokens` in the usage response by subtracting `cache_read_input_tokens` and `cache_creation_input_tokens`. \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    - `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- **smallModel:** Fallback model used for tool-less warmup messages (e.g., Claude Code probe requests); defaults to gpt-5-mini.\n- **responsesApiContextManagementModels:** List of GPT model IDs that should receive Responses API `context_management` compaction instructions. This defaults to `[]`, so you need to opt in explicitly. A good starting point is `[\"gpt-5-mini\", \"gpt-5.3-codex\", \"gpt-5.4-mini\", \"gpt-5.4\"]`. When enabled, the request includes `context_management` in the body and keeps only the latest compaction carrier on follow-up turns. The actual compaction is handled server-side and appears to begin when usage approaches roughly 90% of the model's `maxPromptTokens`, which makes it especially useful for long-running tasks. In practice, the effective `compact_threshold` also appears to be fixed on the server side, so changing it in this project does not currently alter compaction behavior. At the moment, this optimization is intended for GPT-family models only.\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- **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: \u003cyour_key\u003e`\n  - `Authorization: Bearer \u003cyour_key\u003e`\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 endpoints to interact with the Copilot API. It provides OpenAI-compatible endpoints and now also includes support for Anthropic-compatible endpoints, allowing for greater flexibility with different tools and services.\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.        |\n| `GET /v1/models`            | `GET`  | Lists the currently available models.                            |\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. |\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, OpenAI-compatible, or 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# Check Copilot usage without starting the server\nnpx @jeffreycao/copilot-api@latest check-usage\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\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\": \"gpt-5.4\",\n    \"ANTHROPIC_DEFAULT_SONNET_MODEL\": \"gpt-5.4\",\n    \"ANTHROPIC_DEFAULT_HAIKU_MODEL\": \"gpt-5-mini\",\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    \"CLAUDE_PLUGIN_ENABLE_QUESTION_RULES\": \"true\"\n  },\n  \"permissions\": {\n    \"deny\": [\n      \"WebSearch\", \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). If configuring the claude model, it is recommended to set all model configurations the same, so as to remain consistent with github-copilot claude agent behavior. \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- Permissions deny WebSearch because the GitHub Copilot API does not support natie websearch (some gpt models support websearch, but the current project has not adapted websearch); it is recommended to install the mcp mcp_server_fetch tool or other search tools as alternatives..\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\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## 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## 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 --oauth-app=opencode 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  \"model\": \"local/gpt-5.4\",\n  \"small_model\": \"local/gpt-5-mini\",\n  \"agent\": {\n    \"build\": {\n      \"model\": \"local/gpt-5.4\"\n    },\n    \"plan\": {\n      \"model\": \"local/gpt-5.4\"\n    },\n    \"explore\": {\n      \"model\": \"local/gpt-5-mini\"\n    }\n  },\n  \"provider\": {\n    \"local\": {\n      \"npm\": \"@ai-sdk/anthropic\",\n      \"name\": \"Copilot API Proxy\",\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\": 272000,\n            \"output\": 128000\n          }\n        },\n        \"gpt-5-mini\": {\n          \"name\": \"gpt-5-mini\",\n          \"limit\": {\n            \"context\": 128000,\n            \"output\": 64000\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\": 128000,\n            \"output\": 32000\n          },\n          \"options\": {\n            \"thinking\": {\n              \"type\": \"enabled\",\n              \"budgetTokens\": 31999\n            }\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- `model`, `small_model`, and `agent.*.model` let you keep `gpt-5.4` for build/plan work while routing exploration and background work to `gpt-5-mini`.\n- If you enable `auth.apiKeys` in this AI gateway, replace `dummy` with a real key. Otherwise any placeholder value is fine.\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\u003e Token usage history requires Bun or Node.js \u003e= 22.13.0. On Node.js \u003c 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 the URL query parameter. You can change this URL to point to any other compatible API endpoint.\n- **Fetch Data**: Click the \"Fetch\" button to load or refresh the usage data. The dashboard will automatically fetch data on load.\n- **Usage Quotas**: View a summary of your usage quotas for different services like Chat and Completions, displayed with progress bars for a quick overview.\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 directly in the URL using a query parameter. This is useful for bookmarks or sharing links. For example:\n  `http://localhost:4141/usage-viewer?endpoint=http://your-api-server/usage`\n\n### Usage Viewer Screenshot\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"./docs/screenshots/usage-viewer.png\" alt=\"Copilot API usage viewer\" width=\"900\" /\u003e\n\u003c/p\u003e\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## Usage Tips\n\n- To avoid hitting GitHub Copilot's rate limits, you can use the following flags:\n  - `--manual`: Enables manual approval for each request, giving you full control over when requests are sent.\n  - `--rate-limit \u003cseconds\u003e`: Enforces a minimum time interval between requests. For example, `copilot-api start --rate-limit 30` will ensure there's at least a 30-second gap between requests.\n  - `--wait`: Use this with `--rate-limit`. It makes the server wait for the cooldown period to end instead of rejecting the request with an error. This is useful for clients that don't automatically retry on rate limit errors.\n- If you have a GitHub business or enterprise plan account with Copilot, use the `--account-type` flag (e.g., `--account-type business`). See the [official documentation](https://docs.github.com/en/enterprise-cloud@latest/copilot/managing-copilot/managing-github-copilot-in-your-organization/managing-access-to-github-copilot-in-your-organization/managing-github-copilot-access-to-your-organizations-network#configuring-copilot-subscription-based-network-routing-for-your-enterprise-or-organization) for more details.\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","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcaozhiyuan%2Fcopilot-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcaozhiyuan%2Fcopilot-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcaozhiyuan%2Fcopilot-api/lists"}