@jeffreycao/copilot-api 1.15.2 → 1.16.1

package/README.md

@@ -1,13 +1,69 @@
 # Copilot API Proxy
 
+<p align="center">
+  <a href="https://www.npmjs.com/package/@jeffreycao/copilot-api"><img src="https://img.shields.io/npm/v/@jeffreycao/copilot-api.svg" alt="npm version"></a>
+  <a href="https://github.com/caozhiyuan/copilot-api/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License"></a>
+  <a href="https://github.com/caozhiyuan/copilot-api/stargazers"><img src="https://img.shields.io/github/stars/caozhiyuan/copilot-api.svg" alt="GitHub stars"></a>
+  <a href="https://bun.sh"><img src="https://img.shields.io/badge/Bun-%3E%3D1.2.x-orange.svg" alt="Bun >= 1.2.x"></a>
+  <a href="https://nodejs.org"><img src="https://img.shields.io/badge/Node-%3E%3D22.13.0-green.svg" alt="Node >= 22.13.0"></a>
+</p>
+
 English | [简体中文](./README.zh-CN.md)
 
+## Table of Contents
+
+- [Copilot API Proxy](#copilot-api-proxy)
+  - [Table of Contents](#table-of-contents)
+  - [Important Notes](#important-notes)
+  - [Project Overview](#project-overview)
+  - [Quick Start](#quick-start)
+  - [Features](#features)
+  - [Prerequisites](#prerequisites)
+  - [Installation](#installation)
+  - [Running from Source](#running-from-source)
+    - [Development Mode](#development-mode)
+    - [Production Mode](#production-mode)
+  - [Using with npx](#using-with-npx)
+  - [Using with Docker](#using-with-docker)
+  - [Electron Desktop App](#electron-desktop-app)
+    - [Desktop App Screenshots](#desktop-app-screenshots)
+  - [Using with Claude Code](#using-with-claude-code)
+    - [Interactive Setup with `--claude-code` flag](#interactive-setup-with---claude-code-flag)
+    - [Manual Configuration with `settings.json`](#manual-configuration-with-settingsjson)
+  - [Using with OpenCode](#using-with-opencode)
+    - [Minimal setup](#minimal-setup)
+  - [Using with Codex](#using-with-codex)
+    - [Codex `config.toml` Reference](#codex-configtoml-reference)
+  - [GPT Tool Search](#gpt-tool-search)
+  - [Plugin Integrations](#plugin-integrations)
+    - [Claude Code plugin integration (marketplace-based)](#claude-code-plugin-integration-marketplace-based)
+    - [Opencode plugin](#opencode-plugin)
+  - [Using the Usage Viewer](#using-the-usage-viewer)
+    - [Usage Viewer Screenshot](#usage-viewer-screenshot)
+  - [Command Structure](#command-structure)
+  - [Command Line Options](#command-line-options)
+    - [Global Options](#global-options)
+    - [Start Command Options](#start-command-options)
+    - [Auth Command Options](#auth-command-options)
+    - [Debug Command Options](#debug-command-options)
+  - [Configuration (config.json)](#configuration-configjson)
+  - [API Authentication](#api-authentication)
+  - [API Endpoints](#api-endpoints)
+    - [OpenAI Compatible Endpoints](#openai-compatible-endpoints)
+    - [Codex Backend Proxy Endpoints](#codex-backend-proxy-endpoints)
+    - [Anthropic Compatible Endpoints](#anthropic-compatible-endpoints)
+    - [Usage Monitoring Endpoints](#usage-monitoring-endpoints)
+    - [Admin / Configuration Endpoints](#admin--configuration-endpoints)
+  - [Example Usage](#example-usage)
+  - [Usage Tips](#usage-tips)
+    - [CLAUDE.md or AGENTS.md Recommended Content](#claudemd-or-agentsmd-recommended-content)
+
 ## Important Notes
 
 > [!IMPORTANT]
 > **Before using, please be aware of the following:**
 >
-> 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). 
+> 1. **Claude Code configuration:** When using with Claude Code, please configure the model ID as `claude-opus-4-8[1m]`. Example claude `settings.json` see [Manual Configuration with `settings.json`](#manual-configuration-with-settingsjson). 
 >
 > 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.
 >
@@ -23,6 +79,31 @@ The gateway exposes OpenAI- and Anthropic-compatible APIs from one local endpoin
 
 On 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.
 
+## Quick Start
+
+The fastest way to get a working gateway:
+
+```sh
+npx @jeffreycao/copilot-api@latest start
+```
+
+The server listens on `http://localhost:4141` by default. Optionally authenticate with GitHub Copilot or configure a third-party provider first:
+
+```sh
+npx @jeffreycao/copilot-api@latest auth login
+```
+
+Verify the gateway is up:
+
+```sh
+curl http://localhost:4141/v1/models
+```
+
+> [!NOTE]
+> Token usage storage requires Node.js >= 22.13.0 or Bun. See [Using with npx](#using-with-npx) for details.
+
+From here, jump to the guide for your client: [Claude Code](#using-with-claude-code), [OpenCode](#using-with-opencode), [Codex](#using-with-codex), or run it with [Docker](#using-with-docker).
+
 ## Features
 
 - **OpenAI and Anthropic compatibility**: Serve `/v1/responses`, `/v1/chat/completions`, `/v1/models`, `/v1/embeddings`, and `/v1/messages` from one local gateway.
@@ -50,12 +131,6 @@ To install dependencies, run:
 bun install
 ```
 
-To start the server directly from source:
-
-```sh
-bun run start start
-```
-
 ## Running from Source
 
 The project can be run from source in several ways:
@@ -72,6 +147,8 @@ bun run dev start
 bun run start start
 ```
 
+> The trailing `start` is the CLI subcommand passed to `src/main.ts`, not a typo: `bun run dev start` runs watch mode, `bun run start start` runs production.
+
 ## Using with npx
 
 You can run the project directly using npx:
@@ -307,6 +384,7 @@ model_provider = "copilot_api"
 model_reasoning_summary = "auto"
 model_context_window = 272000
 model_auto_compact_token_limit = 244800
+web_search = "live"
 
 [model_providers.copilot_api]
 name = "OpenAI"
@@ -387,7 +465,7 @@ The bridge uses direct tool selection, not query search. Its tool input is `name
 
 Plugin integrations are available for Claude Code and opencode.
 
-#### Claude Code plugin integration (marketplace-based)
+### Claude Code plugin integration (marketplace-based)
 
 The Claude Code integration is packaged as two plugins:
 
@@ -419,7 +497,7 @@ The `agent-inject` plugin also registers a `UserPromptSubmit` hook that returns
 
 The `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.
 
-#### Opencode plugin
+### Opencode plugin
 
 The subagent marker producer is packaged as an opencode plugin located at `plugin/opencode/subagent-marker.js`.
 
@@ -585,60 +663,6 @@ Use `copilot-api auth login --provider custom` to add or update another third-pa
     - `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.
     - `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.
     - `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`).
-
-  Example DashScope model settings:
-  ```json
-  {
-    "providers": {
-      "dashscope": {
-        "type": "openai-compatible",
-        "enabled": true,
-        "baseUrl": "https://dashscope.aliyuncs.com/compatible-mode",
-        "apiKey": "sk-your-dashscope-key",
-        "pricingCurrency": "CNY",
-        "models": {
-          "qwen3.7-plus": {
-            "temperature": 1,
-            "topP": 0.95,
-            "topK": 20,
-            "extraBody": {
-              "preserve_thinking": true
-            }
-          },
-          "glm-5.1": {
-            "temperature": 0.7,
-            "topP": 0.95,
-            "contextCache": true,
-            "pricing": {
-              "tiers": [
-                {
-                  "maxInputTokens": 32000,
-                  "input": 6,
-                  "cachedInput": 1.2,
-                  "explicitCachedInput": 0.6,
-                  "cacheCreationInput": 7.5,
-                  "output": 24
-                },
-                {
-                  "maxInputTokens": 200000,
-                  "input": 8,
-                  "cachedInput": 1.6,
-                  "explicitCachedInput": 0.8,
-                  "cacheCreationInput": 10,
-                  "output": 28
-                }
-              ]
-            },
-            "extraBody": {
-              "preserve_thinking": true
-            }
-          }
-        }
-      }
-    }
-  }
-  ```
-  Built-in token prices cover Codex GPT models in USD, DashScope `qwen3.7-max`, `qwen3.7-plus`, `glm-5.1`, `glm-5.2`, and `kimi/kimi-k3` in CNY, DeepSeek `deepseek-v4-flash` and `deepseek-v4-pro` in CNY, 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, and Kimi `k3` and `k3-256k` models 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.
 - **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.
 - **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.
  - **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.
@@ -700,9 +724,9 @@ These endpoints mimic the OpenAI API structure.
 
 These endpoints require an active Codex login. Each endpoint is available both without a version prefix and under `/v1`.
 
-| Endpoint | Method | Description |
-| --- | --- | --- |
-| `POST /alpha/search`<br>`POST /v1/alpha/search` | `POST` | Transparently forwards the JSON body and query parameters to the Codex Alpha Search upstream. |
+| Endpoint                                                       | Method | Description                                                     |
+| -------------------------------------------------------------- | ------ | --------------------------------------------------------------- |
+| `POST /alpha/search`<br>`POST /v1/alpha/search`                | `POST` | Transparently forwards the JSON body and query parameters to the Codex Alpha Search upstream. |
 | `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`. |
 | `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. |
 
@@ -783,7 +807,7 @@ curl http://localhost:4141/dashscope/v1/messages \
 
 ### CLAUDE.md or AGENTS.md Recommended Content
 
-To add these reminders manually, include the following in `CLAUDE.md` for Claude Code, or `AGENTS.md` for opencode/codex:
+Same reminders as `CLAUDE_PLUGIN_ENABLE_QUESTION_RULES=1` in the `agent-inject` plugin, for when you don't use that plugin. Add to `CLAUDE.md` (Claude Code) or `AGENTS.md` (opencode/codex):
 
 ```
 - Prohibited from directly asking questions to users, MUST use question tool.