betahi-copilot-bridge 0.20.2 → 0.20.4

package/README.md

@@ -1,34 +1,28 @@
 <h1 align="center">copilot-bridge</h1>
 
 <p align="center">
-  <a href="https://www.npmjs.com/package/betahi-copilot-bridge"><img src="https://img.shields.io/npm/v/betahi-copilot-bridge.svg?v=0.20.2" alt="npm version"></a>
+  <a href="https://www.npmjs.com/package/betahi-copilot-bridge"><img src="https://img.shields.io/npm/v/betahi-copilot-bridge.svg?v=0.20.4" alt="npm version"></a>
   <a href="https://github.com/betahi/copilot-bridge/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/betahi-copilot-bridge.svg" alt="license"></a>
 </p>
 
 > Use GitHub Copilot as a local OpenAI/Anthropic-compatible API, so [Codex CLI](https://developers.openai.com/codex/cli), [Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview) and Continue can talk to Copilot with minimal configuration.
 
-> [!WARNING]
-> This is a reverse-engineered bridge for the GitHub Copilot API. It is not
-> supported by GitHub, and may break unexpectedly. Use at your own risk.
-
-> [!WARNING]
-> **GitHub Security Notice:**
-> Excessive automated or scripted use of Copilot (including rapid or bulk
-> requests, such as via automated tools) may trigger GitHub's abuse-detection
-> systems. You may receive a warning from GitHub Security, and further
-> anomalous activity could result in temporary suspension of your Copilot
-> access.
->
-> GitHub prohibits use of their servers for excessive automated bulk activity
-> or any activity that places undue burden on their infrastructure.
->
-> Please review:
->
-> - [GitHub Acceptable Use Policies](https://docs.github.com/site-policy/acceptable-use-policies/github-acceptable-use-policies#4-spam-and-inauthentic-activity-on-github)
-> - [GitHub Copilot Terms](https://docs.github.com/site-policy/github-terms/github-terms-for-additional-products-and-features#github-copilot)
->
-> Use this bridge responsibly to avoid account restrictions. The
-> `--rate-limit <seconds>` flag is provided to help throttle upstream traffic.
+> [!CAUTION]
+> This is an unofficial bridge for the GitHub Copilot API and may break if the
+> upstream API changes.
+
+## Contents
+- [Demo](#demo)
+- [Install & run](#install--run)
+- [Configure Codex CLI](#configure-codex-cli)
+- [Configure Claude Code](#configure-claude-code)
+- [Web Search](#web-search)
+- [Start flags](#start-flags)
+- [Environment overrides](#environment-overrides)
+- [Supported models](#supported-models)
+- [Development](#development)
+- [Acknowledgements](#acknowledgements)
+- [License](#license)
 
 ## Demo
 
@@ -50,10 +44,6 @@ npx betahi-copilot-bridge@latest auth
 npx betahi-copilot-bridge@latest start
 ```
 
-`start` flags: `--host`, `--port`, `--show-token`, `--debug`,
-`--no-codex-setup`, `--select-model`, `--no-prompt`,
-`--rate-limit <seconds>`, `--wait`.
-
 After startup the banner prints a **Usage Viewer** link of the form
 `https://betahi.github.io/copilot-bridge?endpoint=http://127.0.0.1:4142/usage`,
 which renders the Copilot quota snapshot (chat / completions / premium
@@ -65,22 +55,18 @@ The bridge exposes both adapter-style endpoints (`/v1/responses`,
 LiteLLM, Continue, Cline and Aider work out of the box. CORS is enabled
 globally for browser-based clients.
 
-`--rate-limit N` enforces a minimum of N seconds between upstream
-requests (anti–abuse-detection throttle). Add `--wait` to block instead
-of returning HTTP 429 when the window has not elapsed.
-
-`--debug` enables extra upstream error diagnostics in console logs.
-- Includes: token limits, stream mode, tool count, invalid tool names, and suspicious tool-schema paths.
-- Does not include: request messages, prompt text, bearer tokens, tool descriptions, or the full request body.
-
-**Review or redact debug logs before sharing them publicly.**
-
 ## Configure Codex CLI
 
 `start` writes a managed block into **`~/.codex/config.toml`**. You don't edit
-this block; the bridge regenerates it on every start.
+between the markers; the bridge regenerates that block on every start. To pin
+the **default model** for `codex` (without passing `-m` every time), add your
+top-level keys above the managed block:
 
 ```toml
+# User defaults; edit these freely.
+model = "gpt-5.3-codex"
+model_reasoning_effort = "high"
+
 # >>> copilot-bridge managed block — auto-generated, do not edit between markers >>>
 model_provider = "bridge"
 model_supports_reasoning_summaries = true
@@ -94,37 +80,21 @@ requires_openai_auth = false
 # <<< copilot-bridge managed block — edits outside this block are preserved <<<
 ```
 
-To pin the **default model** for `codex` (without passing `-m` every time),
-edit the **top of the same file** — outside the markers. The bridge preserves
-these keys across rewrites:
-
-```toml
-model = "gpt-5.3-codex"
-model_reasoning_effort = "high"
-```
-
-That's it — `codex exec '...'` will now route through the bridge to Copilot.
-
-Use `--no-codex-setup` to skip the managed-block writer entirely (e.g. if you
-manage `~/.codex/config.toml` yourself).
+Use `--no-codex-setup` to skip this writer if you manage
+`~/.codex/config.toml` yourself.
 
 ### Codex warning: "Model metadata ... not found"
 
-This is a Codex client-side metadata warning, not a bridge routing failure.
-Requests can still complete through the bridge.
+This is a Codex client-side metadata warning, not a bridge routing failure, requests can still complete through the bridge.
 
-For 1m model, upstream still enforces a 1,000,000-token prompt
+For 1M models, upstream still enforces a 1,000,000-token prompt
 limit (about 900k succeeds; around 1,000,046 is rejected as too long).
 
 ## Configure Claude Code
 
-Bridge endpoints: `POST /v1/messages`, `POST /v1/messages/count_tokens`.
-
-`copilot-bridge start` automatically writes `ANTHROPIC_BASE_URL` (and a dummy
-`ANTHROPIC_AUTH_TOKEN` if absent) into **`~/.claude/settings.json`**, so
-`claude` works the moment the bridge is listening — even on a different host
-or port. Pass `--no-claude-setup` to skip this. All other keys in your
-settings file (model overrides, plugins, marketplaces) are preserved.
+`copilot-bridge start` writes `ANTHROPIC_BASE_URL` and a dummy
+`ANTHROPIC_AUTH_TOKEN` into **`~/.claude/settings.json`**. Other settings are
+preserved; use `--no-claude-setup` to skip this writer.
 
 Minimal recommended config is:
 
@@ -146,12 +116,12 @@ the bridge maps it to the real Copilot `-1m` model upstream:
 ```json
 {
   "env": {
-    "ANTHROPIC_MODEL": "claude-opus-4.7-[1m]",
+    "ANTHROPIC_MODEL": "claude-opus-4.7-[1m]"
   }
 }
 ```
 
-Optional slot-specific:
+Slot-specific overrides:
 
 ```json
 {
@@ -171,6 +141,76 @@ project-local `.claude/settings.json` and `.claude/settings.local.json` and
 applied to Claude requests only when the model supports reasoning. If it is not
 configured, Claude requests do not infer or attach a reasoning effort.
 
+## Web Search
+
+Not every Copilot model can run web search. If web search is not configured or
+the selected backend cannot search, the bridge tells the client how to configure
+`COPILOT_WEB_SEARCH_BACKEND` and does not switch models automatically.
+
+For Claude Code, configure web search in the user-level
+`~/.claude/settings.json`:
+
+```json
+{
+  "env": {
+    "COPILOT_WEB_SEARCH_BACKEND": "gpt-5.5"
+  }
+}
+```
+
+For Codex CLI, configure the same backend as a top-level key in
+`~/.codex/config.toml`:
+
+```toml
+COPILOT_WEB_SEARCH_BACKEND = "gpt-5.5"
+```
+
+| Value | Search path | Requirement |
+| ----- | ----------- | ----------- |
+| Copilot model id, for example `gpt-5.5` | Copilot HTTP `/responses` + `web_search_preview` | The model must support Copilot Responses web search. |
+| `searxng` | Local SearXNG at `http://localhost:8080` | Start SearXNG yourself. Setup guide: https://github.com/betaHi/openclaw-searxng-search. |
+| `copilot-cli` or `copilot` | GitHub Copilot CLI `web_search` tool, using the current request model | Install and sign in to GitHub Copilot CLI yourself. |
+
+The bridge never installs Docker, SearXNG, or Copilot CLI automatically.
+
+## Start flags
+
+Common:
+
+| Flag | Purpose |
+| ---- | ------- |
+| `--host <host>` | Bind address. Defaults to `127.0.0.1`. |
+| `--port <port>` | Listen port. Overrides `$PORT` and the port inferred from Claude settings. |
+| `--model <model>` | Override the request model for this bridge process only; does not edit config files. |
+| `--rate-limit <seconds>` | Enforce a minimum delay between upstream requests. |
+| `--wait` | With `--rate-limit`, wait instead of returning HTTP 429. |
+
+Codex:
+
+| Flag | Purpose |
+| ---- | ------- |
+| `--no-codex-setup` | Skip writing the managed block into `~/.codex/config.toml`. |
+| `--no-prompt` | Never prompt for a Codex default model. |
+
+Claude:
+
+| Flag | Purpose |
+| ---- | ------- |
+| `--no-claude-setup` | Skip writing `ANTHROPIC_BASE_URL` into `~/.claude/settings.json`. |
+
+Diagnostics:
+
+| Flag | Purpose |
+| ---- | ------- |
+| `--debug` | Print extra upstream error diagnostics. |
+| `--show-token` | Print GitHub and Copilot tokens during startup. Sensitive; use only for local debugging. |
+
+`--debug` enables extra upstream error diagnostics in console logs.
+- Includes: token limits, stream mode, tool count, invalid tool names, and suspicious tool-schema paths.
+- Does not include: request messages, prompt text, bearer tokens, tool descriptions, or the full request body.
+
+**Review or redact debug logs before sharing them publicly.**
+
 ## Environment overrides
 
 | Variable                   | Purpose                                              |
@@ -181,8 +221,6 @@ configured, Claude requests do not infer or attach a reasoning effort.
 | `COPILOT_VSCODE_VERSION`   | Override the VS Code version sent upstream.          |
 | `MODEL_REASONING_EFFORT`   | Claude-side reasoning effort override.              |
 
-
-
 ## Supported models
 
 The bridge resolves aliases and clamps reasoning effort to what each model
@@ -265,6 +303,11 @@ Adding another CLI: drop a new translator under `src/bridges/<client>/`,
 reuse `src/services/copilot/` for upstream calls, register routes in
 `src/server.ts`, and add tests under `tests/`.
 
+## Acknowledgements
+
+Claude Code bridge notes inspired by
+[ericc-ch/copilot-api](https://github.com/ericc-ch/copilot-api). Respect.
+
 ## License
 
 MIT — see [LICENSE](./LICENSE).