Copilot桥接

Install & run

1. Download the archive for your OS from the Releases page — .zip for Windows, .tar.gz for Linux/macOS, plus an unsigned .pkg installer for macOS. Extract it, keeping copilot-bridge(.exe) and appsettings.json together — the bridge loads its config from its own folder. > macOS only: the binary is unsigned, so the first run is blocked by > Gatekeeper. Clear the quarantine flag once: > xattr -dr com.apple.quarantine ./copilot-bridge (or the install directory > for the .pkg), then run normally. 2. Start it — just double-click copilot-bridge.exe (or run it from a terminal). It starts the server on port 8765. On the first run it prints a GitHub device-code URL and a code:

   To authorize, open https://github.com/login/device and enter code: ABCD-1234
   

To isolate logins under another public OAuth App, use the prominent top-level section in appsettings.json:

   "Authentication": {
     "UseCustomAppId": true,
     "CustomAppId": "Ov23liSD97ZYGfIEHAZE"
   }
   

The stock switch is false and the shown custom ID is prefilled. A custom App must have GitHub Device Flow enabled; Marketplace publication is not required. The client ID is public, not a client secret. Do not put the official Copilot Plugin client ID in CustomAppId; leave UseCustomAppId false to use that provider. If Device Flow is disabled, login reports GitHub's device_flow_disabled error. After changing it, restart and run copilot-bridge auth login: the new version-4 credential goes directly to https://api.githubcopilot.com and never enters the internal token-exchange endpoint. Its CAPI requests use GitHub Copilot SDK's copilot-developer-cli integration identity; older credential versions retain vscode-chat. The setting controls only the next login; it never silently rewrites an existing encrypted credential.

The bridge saves one encrypted, versioned github_credentials.dat beside the executable. On upgrade it migrates the richer github_credentials.v2.dat or, when that cannot be read, github_token.dat; it verifies the new file before deleting both old files. A migrated version-1 Copilot Plugin credential keeps working and refreshing without login until GitHub genuinely rejects it. The next explicit auth login replaces it with the provider selected above: version 3 for the default official App, or refreshable direct version 4 for a custom App. Existing version-2 gho_ direct credentials remain supported. (On Windows, double-clicking opens a console window that shows the URL and live log.) 3. Leave it running. Now point your CLI at it.

Build from source

Requires the .NET 10 SDK plus a C/C++ toolchain for the AOT linker on the OS you're building for (Windows: Visual Studio C++ Build Tools; Linux: clang + zlib1g-dev; macOS: Xcode Command Line Tools). Native AOT cannot cross-compile across operating systems — you build for the OS you're on. ```pwsh

JIT build + run (no native toolchain needed) — the fast dev loop

dotnet run --project src/CopilotBridge.Cli -- serve --port 18765

Debug build of the whole solution

dotnet build CopilotBridge.slnx

Configuration (`appsettings.json`)

The file next to the executable. Everything below has a sensible default — you only touch it to tune. Each detector row is toggled by its own Enabled flag (default true); set Enabled: false to turn that detector off entirely. Changes take effect on restart. <div class="rdm-tbl-wrap"><table class="rdm-tbl"><thead><tr><th>Key</th><th>Default</th><th>What it does</th></tr></thead><tbody><tr><td>Server.Port</td><td>8765</td><td>Listen port. Change it and update base_url in your CLI config to match.</td></tr><tr><td>Server.MaxRequestBodySizeBytes</td><td>104857600 (100 MiB)</td><td>Maximum inbound request body for every bridge endpoint. The finite default gives image-heavy Codex conversations room beyond Kestrel's 30 MB default. Raising it increases worst-case per-request memory use and does not compact client history; restart after changing it.</td></tr><tr><td>Codex.ModelCatalog.Enabled</td><td>true</td><td>Map Codex-native GET /codex/models discovery so command-auth Codex can learn reviewed live Copilot context limits. Set false to remove only the metadata route and fall back to Codex's bundled catalog; /codex/responses inference remains available.</td></tr><tr><td>Codex.ModelCatalog.LiveOverlayFailureCooldownSeconds</td><td>300</td><td>Exact process-local delay after a failed live Copilot /models overlay refresh. During it, catalog polls serve the reviewed baseline or stale last-known-good overlay without another upstream call or warning; at expiry one shared retry is allowed. Range 1–3600. This metadata control never delays or disables /codex/responses inference, and restart permits an immediate retry.</td></tr><tr><td>Codex.ModelCatalog.SourceTtlHours</td><td>24</td><td>How often an exact-version official Codex catalog is checked for source changes. Microsoft HybridCache supplies the process-memory level and per-version request coalescing; the validated file remains available stale when GitHub is unavailable. Range 1–168.</td></tr><tr><td>Codex.ModelCatalog.CacheDirectory</td><td>OS per-user cache</td><td>Optional absolute persistent-cache override. Records are keyed by the complete stable/prerelease client version, bounded by RetentionDays (90) and MaxRetainedVersions (32).</td></tr><tr><td>Codex.ModelCatalog.SourceTimeoutSeconds / MaxSourceBytes</td><td>10 / 4194304</td><td>Bound anonymous exact-tag GitHub raw downloads. A cold failure affects only /codex/models; inference remains available and Codex keeps its bundled catalog.</td></tr></tbody></table></div> | AutoUpdate.EnableAutoUpdate | true | Check GitHub Releases once, synchronously, before binding the port; prompts Install this update now? [y/N] and installs only on an interactive y. Offline/non-interactive just logs and starts current. Set AllowBetaUpdates to true (default false) to also consider prereleases. Maintenance commands and *-dev builds never check. → docs/auto-update.md | | Codex.ModelCatalog.BuiltinFallbackEnabled | true | OpenAI ships Codex clients before tagging the matching release, so a brand-new client's exact tag can legitimately 404 (desktop reported 0.147.0 while rust-v0.147.0 did not exist). When on, that confirmed absence is answered from a catalog snapshot bundled into the bridge at build time — still uplifted with live Copilot limits — instead of a metadata error. Only a definitive 404 qualifies: timeouts, throttling, and server errors still fail closed. The snapshot is never cached and never outranks a validated entry, so a tag published later always wins. Set false for strict exact-version-only behavior. | | Codex.ModelCatalog.AbsenceTtlHours | 6 | How long one confirmed 404 is trusted before re-checking whether that tag has been published. Must be ≥ 1; it is clamped to SourceTtlHours when that is lower, so an existing shorter source TTL keeps working untouched. Lower adopts a newly published tag sooner at the cost of more requests; higher keeps a client on the bundled snapshot longer after its real catalog goes live. | | Tracing.Enabled | false | Dump every request/response as JSON under request-traces/. Contains full prompts — turn back off after debugging. | | Pipeline:Detectors:ResponseLeakGuard | on | Auto-repairs a leaked tool call / Claude Code control envelope by forcing a clean retry. Turn off individual Signatures (Invoke, TaskNotification, TeammateMessage, Channel, CrossSessionMessage, Tick, SystemReminder) to clear a false positive — the retry error names the exact switch. Signal (OverloadedError/ApiError) picks the retry error surface. BufferScannableBlocks: true withholds each text/thinking block until scanned so a leak in one never reaches the client (tool_use blocks still stream live; default relays until detection). | | Pipeline:Detectors:RunawayGuard | on | Circuit-breaker for degenerate output; forces a retryable overloaded_error. Thresholds: MaxDeltaBytes (12 MiB), MaxDeltaCount (20000), RepetitionWindow/RepetitionMinUniqueRatio (500 / 0.05), RepetitionMaxConsecutiveRepeat (50). Fix a false trip by raising the threshold, not disabling. | | Pipeline:UpstreamTimeout | on | Exact independent bridge values: FirstByteTimeoutSeconds (240) bounds response headers per send; StreamIdleTimeoutSeconds (240) bounds each parsed upstream SSE event gap; KeepAliveIntervalSeconds (15) schedules downstream pings after the first upstream event. <= 0 disables that timer. No margin, clamp, fallback, coarse HTTP cap, or client-config rewrite is applied. StreamIdleAction (Retry/Truncate) and StreamIdleSignal (OverloadedError/ApiError) govern mid-stream surfacing. See Long-thinking timeouts. | | Pipeline:Detectors:ToolInputValidation | observe-only | Validates tool_use input against the tool schema and flags tool_input_invalid=true, but does not abort — Claude Code self-heals. Set MalformedJsonAction / SchemaViolationAction to AbortOverloaded/AbortApiError only for a backend that doesn't; PreserveStream then picks delta-before-error (true) vs buffer-for-a-real-HTTP-error (false). | | Routing.Locations | gpt-5.6-sol → gpt-6-astra | nginx-style per-request model/header rewrites. Fresh installs use Astra for the flagship Codex identity and map legacy none/minimal effort to low; upgraded installations retain their existing whole array. See below. |

Catalog resolution is visible in the always-on bridge log as one structured line containing the exact version, cache=memory|disk|source-200|source-304|stale, freshness, source/validation outcome, elapsed time, and abbreviated digest/ETag. Catalog bodies and GitHub/Copilot authorization values are never logged. Routing.Locations on a fresh install routes the exact flagship client identity to Astra. OpenAI's migration guide and live Copilot agree that Astra rejects none/minimal, so both map to low; the other accepted efforts pass unchanged:

{
  "When": { "Model": "gpt-5.6-sol" },
  "Use":  {
    "Model": "gpt-6-astra",
    "EffortMap": { "none": "low", "minimal": "low" }
  }
}

Luna, Terra, and Sol Fast remain direct. Update config migration preserves the existing complete Locations array, so an upgraded installation with [] must add this block explicitly. The alternative disabled _Locations_disabled example still shows Claude Code → GPT routing; replace the active array or merge that entry if you want both. Full syntax is in docs/routing.md.

References

• docs/pipeline-design.md — pipeline architecture spec
• docs/routing.md — Routing.Locations config reference
• docs/timeout-chain.md — timeouts along the Claude Code → bridge → Copilot chain
• docs/copilot-api-research.md — Copilot API protocol notes
• docs/codex-implementation-design.md — Codex inference + model-metadata paths
• docs/token-storage.md — token-at-rest threat model
• docs/design.md — original design doc

Everything except the live-Copilot integration harness

dotnet test --filter "Category!=Integration"

Integration harness — hits live Copilot; run `auth login` first

dotnet test tests/CopilotBridge.Playground ``` Playground tests carry [Trait("Category","Integration")] so CI skips them. See docs/routing.md for the routing config reference and tests/harness/README.md for the end-to-end harness.

Authentication troubleshooting

Run these in order while the failure is present:

copilot-bridge auth status
copilot-bridge auth whoami
copilot-bridge auth copilot-status
copilot-bridge debug list-models --all

- auth status reports the single authoritative encrypted file, credential version, direct/exchanged mode, refreshability, generation, and deadlines—never token bytes. - auth whoami validates (and when possible refreshes) the stored GitHub OAuth credential. - auth copilot-status prints direct/exchanged mode, known deadlines, CAPI integration ID, and the API URL. Copilot Plugin credentials are exchanged for a short-lived bearer; an existing version-2 GitHub CLI OAuth credential and custom version-4 OAuth credential are direct CAPI bearers. - debug list-models --all proves the resulting Copilot lease can reach CAPI and shows which models the current account/policy actually exposes.

Version 1 means a migrated Copilot Plugin credential and retains its full refresh state. Version 2 means a GitHub CLI OAuth direct credential and has no separately minted bearer deadline. Version 3 means a newly issued Copilot Plugin credential with an explicit oauth_client_id. Version 4 means a configured custom OAuth App credential used directly at CAPI; when GitHub token expiration is enabled it preserves and rotates the eight-hour access token and refresh token using its recorded App ID. A non-refreshable version 1 or 3 with unknown access expiry remains valid until GitHub actually rejects it; its short-lived Copilot bearer still refreshes in memory.

A first CAPI 403 is not treated as definitive account policy. The bridge rejects only the bearer/endpoint generation used, obtains an already-newer or fresh lease, and replays the same request once. Only a second 403 is classified as terminal policy/entitlement; mixed 401/403 sequences still get one replay total. This is why restarting could repair the reported forbidden incident: restart discarded the stale process-local bearer. A catalog warning saying capacity is degraded refers to /codex/models metadata only; the endpoint serves a safe baseline/stale overlay during its configured cooldown, and inference remains independent.

If whoami and the token exchange/direct CAPI both report GitHub 401 Bad credentials, the failure occurs before model inference and therefore is not specific to gpt-5.6 or any request body. A refreshable persisted OAuth credential is rotated once automatically; if its refresh token is missing, expired, or rejected, GitHub requires a new interactive authorization. Check the account security log for oauth_access.destroy; explanation=max_for_app means another login exceeded GitHub's ten-token user/application/scope limit and evicted this credential. Then run:

copilot-bridge auth login

If GitHub auth succeeds but a gpt-5.6 id is absent from /models, check the Copilot plan and organization model policy instead. Sol and Sol Fast require Pro+/Max or an enabled Business/Enterprise policy; Terra requires a paid plan, while current metadata also exposes Luna to Free and Edu accounts. Business and Enterprise administrators must explicitly enable the new-model policy during rollout.