CoS Codex Bridge

CoS Codex Bridge

你的幕僚长现在也负责 Codex。

这是一个本地 MCP 服务，可让幕僚长客户端查找 Codex 任务、创建项目工作、发送完整提示词、跟进进度并继续同一段对话。同一 MCP 中还提供可选的 Claude Code CLI 路由，可通过本地项目文件夹和已保存的 CLI 会话完成这些操作。核心功能遵循 MIT 许可证且免费。无需订阅或结账即可使用 Bridge。实际执行需要你已有的 Codex 或 Claude Code 访问权限。

选择你的发布版本： npm 上的稳定版 0.1.4 仅支持 Codex 路由（@latest）。0.2.0-beta.1 在同一 MCP 中加入了 Claude Code CLI 支持（@beta）。在本地安装并连接客户端，然后使用 bridge_* 工具。无需安装守护进程或 Desktop 所有者适配器。Codex 核心工作流以及 Grok Bot → Claude Code CLI 的交接流程已通过所有者在 macOS 上的实地测试。桌面端所有者暂停队列的恢复仍是已知的 Codex 限制。尚未认证较新版本 Codex Desktop 中侧边栏的呈现效果；依赖该功能前，请先查看兼容性表。排队回执绝不能证明工作已经开始。

Bridge 已收录于官方 MCP 注册表和 Glama。这些是用于发现服务的目录；Bridge 仍需在本地安装和运行。

你的幕僚长可以做什么

• 将研究成果或产品构想转化为新的 Codex 项目和任务。
• 发送完整提示词和附加文本，无需手动复制粘贴。
• 查找现有 Codex 任务、读取其进度，并继续同一段对话。
• 使用持久化回执跟踪交付情况，而不是假定已接受的提示词已经运行。
• 在获准的项目范围内重命名、分配、置顶和取消工作。
• 将本地项目访问权限限制在明确列入允许列表的目录中。

示例：“为这个构想创建一个项目，把我的研究资料发送给 Codex，监控构建进度，然后在同一任务中跟进审查发现。”

Claude Code 路由（测试版）

现在，同一个 MCP 也可以启动并继续 Claude Code CLI 工作。向 bridge_projects、bridge_sessions 和 bridge_submit 传入 provider:"claude-code"；现有的 Codex 路由仍是默认路由。本地文件夹是 Claude Code 的项目上下文。桥接器会在该文件夹中创建一个已保存的 CLI 会话，返回持久回执，读取结果，并在同一会话中继续跟进。我们已在本地使用 Claude Code 2.1.269 进行测试，包括在临时文件夹中实际编辑文件。

在一次所有者现场测试中，Grok Bot Chief of Staff 使用已安装的 MCP 创建了一个允许列表中的文件夹，向 Claude Code 发送提示词，读取其完成结果，并在同一个已保存的会话中继续跟进。我们检查了两个桥接回执以及 Claude Code 的原生会话历史。这证明的是本地 CLI 交接，而不是 Claude Desktop 或账号 Project 控制。

Claude 账号 Projects、普通聊天、Cowork/Dispatch 和由 Desktop 管理的会话是彼此独立的界面。此路由不会创建或控制它们，而且 CLI 会话不会自动出现在 Claude Desktop 侧边栏中。Claude 设置、确切工作流程和限制。

查看交接过程

该动画展示了本地交接过程。它不使用任何私有 Desktop 数据或项目截图。

试用安全演示

初次使用？从无需账号的快速入门开始。 它使用稳定版 npm 包，无需克隆 Git 仓库，并展示已完成回执的样子。报告安装结果，并说明你使用的是哪个本地 MCP 客户端。

此演示会在本地运行 MCP 工作流，无需 Codex 账号、模型调用或更改项目：

此克隆使用 GitHub main，目前对应 Claude Code CLI 预览版（0.2.0-beta.1）。若要改为演示稳定版、仅支持 Codex 的源代码，请在 cd cos-codex-bridge 之后、npm ci 之前运行 git checkout v0.1.4。

git clone https://github.com/AV-Labs-Co/cos-codex-bridge.git
cd cos-codex-bridge
npm ci
npm run demo

演示会输出已完成的回执、载荷哈希和任务元数据，让你在授予真实项目访问权限前了解桥接契约。

最简单的设置方式：将此链接交给你的本地助手

打开仓库和安装说明。拥有本地终端访问权限的助手可以为你安装。仅限浏览器或仅限云端的聊天无法在你的电脑上安装软件。

将以下安装请求复制给你的 Chief of Staff：

从 https://github.com/AV-Labs-Co/cos-codex-bridge 安装 CoS Codex Bridge。请先阅读 README 和 SECURITY.md。仅使用我批准的项目文件夹，保留只读默认设置，并保留现有客户端配置。按照安装程序说明操作，运行 doctor，并将生成的 stdio MCP 条目连接到我的本地客户端。告诉我哪些步骤已通过，以及还需要进行哪些设置。在我提交第一个任务之前，请等待。不要发布或部署任何内容。

你也可以从 Releases 下载源代码压缩包，解压后按照以下步骤操作。克隆 Git 仓库更便于日后更新。我们还提供公开的 npm 包，但无需托管端点。

安装

需要 Node.js 22+、npm、本地已认证的 Codex CLI（用于 Codex 工作）和/或 Claude Code CLI（用于 Claude 工作），以及支持 stdio MCP 的本地客户端。注册 Codex Desktop 还需要在 macOS 上安装 Codex Desktop。

下面的 Git 克隆会安装当前的 main 分支，也就是 Claude Code CLI 预览版（0.2.0-beta.1）。如需稳定版、仅支持 Codex 的源代码，请在 cd cos-codex-bridge 后、运行 npm ci 前立即执行 git checkout v0.1.4。下面固定版本的 npm @0.1.4 命令是稳定版安装方式。

git clone https://github.com/AV-Labs-Co/cos-codex-bridge.git
cd cos-codex-bridge
npm ci
npm test
node scripts/install.mjs --root /absolute/path/to/your/projects

安装程序会在 ~/.local/share/cos-codex-bridge 下写入私有配置、启动器和 MCP 片段。请保留检出目录。默认执行为只读；仅在获准修改项目时使用 --write。请选择具体的项目根目录，切勿选择整个主目录。如果任一 CLI 不在 MCP 客户端的 PATH 中，请添加 --codex /absolute/path/to/codex 或 --claude /absolute/path/to/claude。请参阅安装程序和升级步骤。

如果你更倾向于使用 npm 而不是 Git，可以将固定版本安装到专用目录，然后运行同一安装程序。稳定版、仅支持 Codex 时使用 @0.1.4，Codex 加 Claude Code CLI 预览版时使用 @0.2.0-beta.1：

mkdir -p "$HOME/.local/share/cos-codex-bridge-package"
npm install --prefix "$HOME/.local/share/cos-codex-bridge-package" [email protected]
node "$HOME/.local/share/cos-codex-bridge-package/node_modules/cos-codex-bridge/scripts/install.mjs" --root "/absolute/path/to/your/projects"

请保留该 npm 包目录：生成的启动器会指向它。npm 安装方式已通过全新稳定版和测试版安装、隔离的演示配置以及 doctor 检查。安装程序不会替你修改任何 MCP 客户端设置。

~/.local/share/cos-codex-bridge/cos-codex-bridge doctor

检查 codexAvailable、claudeCodeAvailable、claudeCodeAuthenticated、mode、sandbox 和 roots。Claude 登录状态检查是在 MCP 主机进程中进行的，结果可能与沙盒终端不同；doctor 不会验证 Desktop 侧边栏的显示效果。如需无模型演示，请使用 --demo 安装到单独的前缀目录。

将生成的 mcp-client.json 粘贴到客户端的 MCP 配置中。等效结构如下：

{"mcpServers":{"cos-codex-bridge":{"command":"/absolute/path/to/node","args":["/absolute/path/to/cos-codex-bridge/dist/cli.js","--config","/absolute/path/to/config.json","mcp"]}}}

完整交接流程

告诉你的幕僚长：“找到我的应用项目，把这份完整的实施简报交给 Codex，监控进度，然后根据审核结果继续同一项任务。”

1. 使用 bridge_projects 和 bridge_sessions 确认确切的项目和任务。
2. 如有需要，创建目录，然后注册它。仅有目录并不代表它就是 Desktop 项目。
3. 调用 bridge_submit，传入 project、完整的 prompt 和稳定的 requestId。后续跟进时请包含 threadId。
4. 轮询 bridge_receipt。验证哈希、任务 ID 和最终完成状态。需要澄清时，使用 bridge_answer。
5. 使用 bridge_session_manage 重命名、分配或固定任务。已存储的元数据和 Desktop 中的可见显示效果是两项独立的证明。

模型成功完成任务，并不能单独证明生成的代码可正常运行。请审核并测试结果。

十种工具、十二项功能和一个已知限制

工具	用途
bridge_projects	列出别名、创建文件夹、注册／打开或检查 Desktop 项目
bridge_sessions	查找并读取现有的获准任务，包括由外部创建的任务
bridge_submit	开始任务或跟进；支持稳定的请求 ID 和完整的 UTF-8 载荷
bridge_receipt	提供持久化进度、哈希、有界输出和明确的不确定性
bridge_steer	重试恢复现有的桥接队列项，而不重新发送
bridge_answer	回答待处理的澄清问题；绝不批准扩大权限
bridge_cancel	请求取消由桥接管理的直接任务
bridge_artifact	读取／写入带版本的文本资源，不覆盖现有内容
bridge_session_manage	重命名、固定／取消固定，并分配到已注册的项目
bridge_doctor	报告模式、Codex 版本、作用范围和实际能力限制

已知限制（不常见）： 如果某个会话已有正在执行的写入任务，此时发送引导提示词，该提示词会等到任务自然暂停或停止。对于长时间自主运行的任务，遇到这种情况时，只需人工点击 Steer。

请参阅 v1 能力契约 和 验证矩阵。

忙碌任务、引导和中断恢复

当其他写入任务占用任务时，直接提交默认返回 SESSION_BUSY。若要采用现有的 Desktop 执行策略，请使用 onBusy:"queue" 和 acceptDesktopPolicy:true。delivery:"desktop-queue" 会明确将任务加入现有任务的队列。这些路径使用 Codex 的一方队列 API，相当于 codex queue，并保留单独的文本输入和稳定的客户端消息 ID。

回执会区分 busy、queued、steered、delivered、completed、blocked 和 uncertain。当写入任务可用时，thread/queue/start 恢复已通过本地实时测试。Desktop 管理的暂停任务恢复已延期到 v0.1；可能需要人工点击 Steer。 当写入任务可用时，bridge_steer 会重试完全相同的已保存队列项，包括通过队列 ID 接管的现有 CLI 创建项。bridge_sessions 搭配 includeQueue:true 会显示待处理 ID 和推断出的需引导状态。它绝不会静默分叉，也不会将队列消失视为已送达。请参阅队列语义。

安全默认设置

预览版源代码，未包含在 npm 0.1.4 或 0.2.0-beta.1 中： 直接提交现在支持为每次交接设置 writeIntent。只读交接会收紧允许写入的配置；写入交接不能扩大已配置的权限。Desktop 队列会拒绝明确指定的单次交接意图，因为此路径无法缩小现有权限。契约和示例。

默认拒绝的 realpath 允许列表、只读直接执行、私有本地回执、有界 UTF-8 输入、明确的项目／任务匹配，以及不隐式指定云端点。为确保回执完整性，提示词和资源会以明文存储在本地；请勿将其视为加密存储。

直接工作进程会禁用继承的连接器，并拒绝权限审批。Desktop 队列是单独且明确的策略边界：它使用现有任务的权限和工具。桥接无法在该已运行任务内部强制执行更严格的沙箱。未经授权，不得自动提交到商店、发布社交内容或发布内容。请参阅 SECURITY.md。

客户端矩阵

环境	依据
机主 Mac 上的 Grok Bot / CoS	Codex 编排和 Claude Code CLI 已通过实地测试：创建 → 完成 → 在同一会话中跟进；集成方式因安装而异
标准 stdio MCP 客户端	已在 macOS 和 Ubuntu 上自动测试协议握手、架构、错误、安装程序和演示
Codex Desktop macOS / CLI 0.153.4	机主已测试注册、分配、固定、连续性和队列交付
Codex Desktop 0.155.0-alpha.9.2	已在实地观察到原生元数据；侧边栏渲染未经认证；旧版适配器已禁用
其他 MCP 客户端	预计兼容协议；未逐一进行实地认证
Claude Code CLI 2.1.269	已验证本地创建、完成、读取和同一会话跟进；已在临时文件夹中验证受限文件写入
Claude Desktop/Claude 账户 Projects	不宣称支持创建、侧边栏注册、固定或控制实时会话；可能可以读取已保存的本地转录，但无法通过此途径恢复会话
Windows 运行时 / Linux Desktop 集成	未验证；不宣称与 macOS Desktop 相同
普通 ChatGPT 聊天	不支持
托管服务 / Composio 云端	不提供，也未列出

通过已安装的实验性 App Server API 支持原生项目分配。可选的、按版本启用的旧版 Desktop 分配适配器带有备份和竞态检查；默认关闭，且仍处于实验阶段。

社区

本项目专注于可靠的幕僚长交接，而非宣称普遍优越。其他 Codex MCP 项目也解决了有用的相关工作流。我们不宣称“最先进”、能够控制所有账户或具备全面自主能力。

在 GitHub Discussions 中提出安装问题或分享客户端配置。请使用 Issues 提交可复现的错误，并提供已脱敏的版本、状态和错误详情。切勿发布完整的私人提示词或凭据。

点 Star 关注开发进展，也可以 Fork 以适配你的客户端。MIT 许可证。