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
   

Open that URL in your browser, enter the code, and approve. The bridge saves an encrypted token next to the executable, so every later start is silent — no login prompt. (On Windows, double-clicking opens a console window that shows the URL and the live log.)

1. 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. A few keys worth knowing:

- Server.Port — the port the bridge listens on (default 8765). If you change it, update the base_url in your CLI config to match. - Tracing.Enabled — per-request audit logging, off by default. Turn it on to dump every request/response as JSON under request-traces/ when debugging — but note the files contain your full prompts, so turn it back off afterward. - Pipeline:Detectors:ToolLeakGuard — the tool-call-leak auto-repair (Enabled, Signal). On by default; leave it unless you want to tune the retry signal. - Routing.Locations — optional nginx-style rules to remap a model or tweak headers per request. For example, the shipped rule:

  {
    "When": { "Model": "gpt-5.5-1m" },
    "Use":  { "Model": "gpt-5.5" }
  }
  

rewrites a request for gpt-5.5-1m to the real gpt-5.5 (Codex uses the -1m alias to unlock the 1M window client-side; the bridge maps it back). See docs/routing.md for the full match/rewrite syntax.

References

• docs/pipeline-design.md — pipeline architecture spec
• docs/routing.md — Routing.Locations config reference
• docs/copilot-api-research.md — Copilot API protocol notes
• docs/codex-implementation-design.md — Codex /responses path
• 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.