The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Codex Bridge listing page.
简体中文 | English
Codex Bridge 是一个面向个人自托管场景的原生 macOS App 与后台 Service。它把 ChatGPT 网页版、Qwen Studio 和本机工作台连接到已授权的本地项目,并在同一套任务、审批、对话和持久化系统中运行 Codex、OpenCode、DeepSeek Harness 与 Antigravity。
Bridge 不依赖开发者自建的云端中转、账号系统或远程数据库。通过 ChatGPT、模型 API 或 Provider 执行任务时,请求内容仍会发送给你主动选择和配置的对应服务;“本地优先”不等于所有数据永远不离开 Mac。
| 层级 | 当前实现 |
|---|---|
| ChatGPT 网页版 | OpenAI Secure MCP Tunnel;Tunnel Helper 随正式 App 打包并由 Service 管理 |
| Qwen Studio | 本机回环 Streamable HTTP /mcp;App 一键复制带认证 Header 的 JSON |
| Codex | 默认 Provider;codex app-server --stdio、Thread/Turn、实时 steer、interrupt、审批与 Supervisor |
| OpenCode | ACP stdio;Plan/Build、动态模型与 effort、permission 回传、同 Session 排队继续 |
| DeepSeek Harness | 固定版本 ACP 适配;外部 cordis.yml、模型/effort、Web/工具/子代理、执行证据与逐次本机审批 |
| Antigravity | agy CLI stream-json;Plan/Accept Edits、原生 sandbox、CLI 权限规则、会话继续与 queued steer |
| Direct Workspace | 受控读写、revision 校验、Patch、结构化命令、进程会话和本地 Git 提交 |
| Skills | 安全发现 SKILL.md,只执行显式声明的 Action |
外部 Agent 必须由用户明确登记、Probe、启用并在任务中显式选择;没有 provider_id 的 submit_task 始终使用 Codex。
生产 Service 只使用一个 SQLite 数据库保存项目、设置、任务、消息和展示事件。App 负责配置、查看和本机授权,不持有 Provider、MCP、Tunnel 或 Supervisor 的进程生命周期。
完整首次配置请直接阅读 详细使用指南。以下步骤用于快速建立正确顺序。
arm64 与 x86_64 分开提供;请选择与 Mac 一致的架构。设置 → 后台运行与远程 Agent 授权 中的“退出 App 后保持后台服务运行”决定按 ⌘Q 后是否继续,默认开启。从源码构建:
普通 Debug 构建可能没有打包 OpenAI tunnel-client,因此可以使用本地 MCP,但未必能连接 ChatGPT Secure Tunnel。ChatGPT 接入请使用“连接”页面显示 Helper 就绪的正式构建。
项目 → 添加,选择允许 Bridge 访问的项目根目录。Bridge 只接受已登记项目。项目硬策略优先于 Workbench 默认和单任务请求;项目禁止写入时,任何 Provider 的写模式都会被收窄。
打开 工作台:
Read Only 或 Write。远程请求省略 project_id 时使用这里选中的项目。若显式传入 project_id,它必须来自 MCP list_projects,不能填写项目显示名。远程客户端通常应省略权限覆盖字段,使用 Workbench 的统一默认值。
设置 → Codex 执行默认偏好 选择模型、effort、访问权限和 Fast 模式。Bridge 不读取 Codex 认证文件。连接 → 本机 Agent 引擎连接 → 登记 Agent → OpenCode,选择真实 opencode 可执行文件并 Probe。详见 OpenCode 连接指南。dsh-v0.1.1-rc.2 构建出的 packages/examples/acp-demo/lib/bin.js,再选择 DSH 源码树之外的 cordis.yml;为隔离凭据,建议 Profile 也位于任务项目和 Bridge 仓库之外。.env 与 cordis.yml 同目录,由 Harness 自己读取。详见 DeepSeek Harness 接入指南。command -v agy 找到真实 CLI,在目标项目中交互登录,并通过 /settings、/permissions 配置 headless 所需的命令、URL 与 MCP 规则;不要登记 Desktop App。详见 Antigravity / AGY 连接与权限指南。外部 Provider 登记成功后还要打开“启用”,然后到 设置 中刷新该 Provider 的模型目录并保存默认模型/effort。模型 ID 以当前 Provider 实际返回值为准,不要跨 Provider 猜别名。
Read Only / Write 由工作台决定;Provider 设置页中的访问权限只是后备默认。approval.policy: ask,运行中在工作台对每个 session/request_permission 选择“仅本次允许”或拒绝。full-access 和自动批准任务启动都不会跳过该步骤。agy 的 /settings 中确认 Tool Permission = proceed-in-sandbox(沙箱内终端命令自动执行),再用 Project 作用域的 /permissions 添加窄 allow 规则。Bridge 已强制传入 --sandbox。network_access=true,真实网络仍由 AGY/DSH 原生配置和工具权限负责。Read 与 Use。连接 → 远程 AI 客户端 (OpenAI Secure Tunnel) 填入 Tunnel ID 和 Runtime API Key,点击“保存并启动连接”。Runtime Key 只保存在 macOS Keychain。Runtime API Key 只填在 Bridge,不填进 ChatGPT 对话或 MCP App;ChatGPT Tunnel 配置也不填写 127.0.0.1、/mcp 或 Bridge 为 ChatGPT profile 单独生成的本地 Header Secret。账号权限、当前页面入口和完整步骤见 ChatGPT Developer Mode 接入指南。
连接 → 本地 MCP 客户端通道。JSON 中包含本地认证 Header,不要提交到 Git、公开文档或聊天群。重新生成凭证后,旧 JSON 会立即失效,需要重新复制。
远程 Provider 任务的正常状态流:
workspace-write 任务;只读任务可并行。get_task 的终态是任务成败权威。按其 wait_policy 等待;暂时没有活动或更新时间不变不代表失败。get_task 读取 result_summary、failure_code、changed_files 和 Provider 绑定。当前 MCP 工具目录没有 get_final_report;wait_policy.next_action=read_final_report 只是提示字符串,不是可调用工具。| 边界 | 行为 |
|---|---|
| 已登记项目 | MCP 只接受不透明项目 ID;文件路径必须位于项目根内且通过身份校验 |
| 敏感文件 | 拒绝 .env*、私钥、认证文件、浏览器数据等敏感路径 |
| 写入并发 | 同一项目只有一个活动写任务;Direct 与 Provider 共享工作区门禁 |
| Provider 授权 | 远程启动、Provider 执行期 permission 与 Direct 操作是不同审批层级 |
| 凭据 | Tunnel Runtime Key 与按客户端 profile 分离的本地 MCP Secret 存入 Keychain;Bridge 不读取 Provider 的账号凭据或 DSH .env |
| 网络 | Codex/Direct 受项目策略约束;外部 Provider 记录明确任务意图并使用原生网络策略,项目选择器不是逐包防火墙 |
| Git | direct_git_commit 只创建受控本地提交,不允许 push、amend、reset 或历史改写 |
Xcode/Swift 命令统一经 Scripts/with-xcode.sh 选择工具链。App 打包、安装和签名只能证明本地产物状态;真实 ChatGPT、Qwen 与各 Provider 登录、联网、工具和审批体验仍需要使用对应账号手动验收。
项目基于 Apache License 2.0 开源,第三方声明见 NOTICE。隐私与漏洞报告方式见 PRIVACY.md 与 SECURITY.md。请勿在 Issue、日志或截图中公开 API Key、Token、Cookie、.env 或敏感项目源码。