Use GitHub Copilot as a local OpenAI/Anthropic-compatible API, so Codex CLI, Codex App, Claude Code and Continue can talk to Copilot with minimal configuration.

[!CAUTION] This is an unofficial bridge for the GitHub Copilot API and may break if the upstream API changes.

Contents

• Demo
• Why this bridge?
• Install & run
• Configure Codex CLI or Codex App
• Configure Claude Code
• Web Search
• Start flags
• Environment overrides
• Supported models
• Development
• Acknowledgements
• License

Demo

Codex CLI

Codex App

Claude Code

Why this bridge?

copilot-bridge is more than a raw HTTP proxy:

1. Codex CLI, Codex App, and Claude support. Exposes Codex /v1/responses, Claude Code /v1/messages, and OpenAI-compatible chat, embeddings, and models routes.
2. Tool call compatibility. Adapts MCP tool names and tool call payloads to each upstream model's constraints, then restores the original tool identity for the client. This keeps real Claude Code and Codex CLI agent workflows working when MCP plugins expose long or model-incompatible tool names.
3. Web search support. Model-selected web search can be executed by the bridge and fed back into a final model pass.
4. End-to-end reasoning support. Normalizes model aliases and reasoning_effort, routes through the right upstream API, and preserves returned reasoning_text / reasoning_content in streaming and non-streaming responses.

Install & run

# one-time GitHub device login
npx betahi-copilot-bridge@latest auth

# start the bridge on 127.0.0.1:4142
npx betahi-copilot-bridge@latest start

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 interactions) read from GET /usage.

The bridge exposes both adapter-style endpoints (/v1/responses, /v1/messages) and the raw OpenAI-compatible surface (/v1/chat/completions, /v1/embeddings, /v1/models) so tools like LiteLLM, Continue, Cline and Aider work out of the box. CORS is enabled globally for browser-based clients.

Configure Codex CLI or Codex App

Codex CLI and Codex App use the same provider config in ~/.codex/config.toml. start writes a managed block into that file. You don't edit between the markers; the bridge regenerates that block on every start. To pin the default model for Codex clients, add your top-level keys above the managed block:

# 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

[model_providers.bridge]
name = "Copilot Bridge"
base_url = "http://127.0.0.1:4142/v1"
wire_api = "responses"
prefer_websockets = false
requires_openai_auth = false
# <<< copilot-bridge managed block — edits outside this block are preserved <<<

Use --no-codex-setup to skip this writer if you manage ~/.codex/config.toml yourself.

The managed config also keeps Codex CLI's /status context-window display in sync with Copilot model metadata. For example, GPT-5.5 shows a 1.05M context window through the bridge:

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.

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

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:

{
  "env": {
    "ANTHROPIC_BASE_URL": "http://127.0.0.1:4142",
    "ANTHROPIC_AUTH_TOKEN": "dummy",
    "ANTHROPIC_MODEL": "claude-opus-4.7",
    "MODEL_REASONING_EFFORT": "medium"
  }
}

For Claude Code 1M context, use the -[1m] display form in ANTHROPIC_MODEL. Claude Code shows a 1M context window for this form, and the bridge maps it to the matching upstream Copilot model:

{
  "env": {
    "ANTHROPIC_MODEL": "claude-opus-4.8-[1m]"
  }
}

Slot-specific overrides:

{
  "env": {
    "ANTHROPIC_BASE_URL": "http://127.0.0.1:4142",
    "ANTHROPIC_AUTH_TOKEN": "dummy",
    "ANTHROPIC_MODEL": "claude-opus-4.7",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-sonnet-4.6",
    "ANTHROPIC_SMALL_FAST_MODEL": "claude-haiku-4.5",
    "MODEL_REASONING_EFFORT": "medium"
  }
}

MODEL_REASONING_EFFORT (case-insensitive key lookup) is also read from the 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. Bridge-managed web search is enabled only when COPILOT_WEB_SEARCH_BACKEND is present and points to a supported backend. If the setting is missing, empty, or names an unsupported backend, the bridge treats web search as unsupported and passes the model response through normally.

For Claude Code, configure web search in the user-level ~/.claude/settings.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:

COPILOT_WEB_SEARCH_BACKEND = "gpt-5.5"

| Value | Search path | Requirement | | ----- | ----------- | ----------- | | Copilot model id, for example gpt-5.6-luna | Copilot HTTP /responses + web_search_preview | Recommended: gpt-5.6-luna, gpt-5.6-sol, gpt-5.6-terra, gpt-5.5, gpt-5.4, gpt-5.4-mini, gpt-5.3-codex. | | searxng, use "COPILOT_WEB_SEARCH_BACKEND": "searxng" | Local SearXNG at http://localhost:8080 | Start SearXNG yourself. Setup guide: https://github.com/betaHi/openclaw-searxng-search. | | copilot-cli or copilot, use "COPILOT_WEB_SEARCH_BACKEND": "copilot-cli" | GitHub Copilot CLI web_search tool, using the current request model | Install and sign in to GitHub Copilot CLI yourself. |

Project-local Claude settings do not enable bridge-managed web search. Claude Code reads this setting only from the user-level ~/.claude/settings.json; Codex CLI reads it only from the top level of ~/.codex/config.toml.

When a supported backend is configured, the bridge executes web search only after the model requests the WebSearch tool. It then sends the search context through a final model pass, so Claude Code and Codex CLI receive the WebSearch call plus the model's final reasoning/text response instead of raw search output alone.

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. | | --auto | Acquire a Copilot Auto session and attach its session token only to upstream /chat/completions and /responses requests. Codex model selection is limited to Auto-available models. | | --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 | | -------------------------- | ---------------------------------------------------- | | COPILOT_TOKEN | Pre-issued Copilot bearer token (skip device login). | | COPILOT_ACCOUNT_TYPE | individual | business | enterprise. | | COPILOT_BASE_URL | Override the upstream Copilot base URL. | | COPILOT_VSCODE_VERSION | Override the VS Code version sent upstream. | | MODEL_REASONING_EFFORT | Claude-side reasoning effort override. | | HTTP_PROXY / HTTPS_PROXY | Route outbound GitHub/Copilot requests through an HTTP proxy. | | NO_PROXY | Hosts that should bypass HTTP_PROXY / HTTPS_PROXY. |

Proxy example:

HTTPS_PROXY=http://127.0.0.1:7890 npx betahi-copilot-bridge@latest start

Supported models

The bridge resolves aliases and clamps reasoning effort to what each model accepts upstream.

GPT-5 family — native Responses passthrough

| Model | Reasoning efforts | | --------------- | ---------------------------------------- | | gpt-5.6-luna | none, low, medium, high, xhigh | | gpt-5.6-sol | none, low, medium, high, xhigh | | gpt-5.6-terra | none, low, medium, high, xhigh | | gpt-5.5 | none, low, medium, high, xhigh | | gpt-5.4 | low, medium, high, xhigh | | gpt-5.4-mini | none, low, medium | | gpt-5.3-codex | low, medium, high, xhigh | | gpt-5-mini | low, medium, high |

Claude family — translated to chat completions

| Model | Reasoning efforts | Notes | | -------------------------------- | --------------------------------------- | -------------------------------------- | | claude-opus-4.8 | low, medium, high, xhigh, max | | | claude-opus-4.8-1m | low, medium, high, xhigh, max | 1M-token context window, prefer use claude-opus-4.8-[1m] in config. | | claude-opus-4.7 | low, medium, high, xhigh, max | Effort sent as output_config.effort. | | claude-opus-4.7-1m | low, medium, high, xhigh, max | 1M-token context window, prefer use claude-opus-4.7-[1m] in config. | | claude-opus-4.6 | low, medium, high, max | | | claude-opus-4.6-1m | low, medium, high, max | 1M-token context window, prefer use claude-opus-4.6-[1m] in config | | claude-sonnet-5 | low, medium, high, xhigh, max | | | claude-sonnet-4.6 | low, medium, high, max | | | claude-opus-4.5 | — | Reasoning not accepted upstream. | | claude-sonnet-4.5 | — | Reasoning not accepted upstream. | | claude-haiku-4.5 | — | Reasoning not accepted upstream. |

For Claude Code settings, prefer claude-opus-4.8-[1m], claude-opus-4.7-[1m], or claude-opus-4.6-[1m] when you want the CLI /context UI and the upstream model to both use 1M context. Direct API clients can use the corresponding model ids listed in the table.

Gemini family — translated to chat completions

| Model | Aliases | | ------------------------ | ---------------- | | gemini-3.1-pro-preview | gemini-3.1-pro | | gemini-3-flash-preview | gemini-3-flash | | gemini-2.5-pro | — |

Legacy

gpt-4.1, gpt-4o — chat-only upstream, no reasoning parameter.

Reasoning effort

For OpenAI-compatible clients, unsupported reasoning values are clamped to the model capability table instead of being forwarded upstream. If a request omits reasoning effort, the bridge leaves it omitted rather than inferring a default. Claude-side reasoning can be set globally via MODEL_REASONING_EFFORT (env, or env in ~/.claude/settings.json); invalid Claude-side values are ignored, and per-request reasoning_effort takes precedence. Codex CLI does not accept max in model_reasoning_effort; when Codex config contains max, the bridge writes xhigh and clamps it to the closest upstream effort accepted by the selected model.

Development

Requires Bun ≥ 1.2.

bun install
bun run dev          # watch mode against src/main.ts
bun test             # run all tests (bun test runner)
bun run typecheck    # tsc --noEmit
bun run build        # produce dist/main.js with tsdown

# run directly from source (no build, no npx); --port specifies the port
bun run ./src/main.ts start --host 127.0.0.1 --port 4141 --no-prompt

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. Respect.

License

MIT — see LICENSE.