BoundedRelay

BoundedRelay 让 Claude Code 通过 MCP 将范围明确的任务交给本地安装的 Codex CLI。调用会立即返回一个任务句柄。随后 Claude 可以展示工作器正在做什么、高效等待下一个真实更新、获取结果或取消任务。

Claude Code  ── local MCP/stdio ──>  BoundedRelay  ── codex exec --json ──>  Codex
                                             │
                                             ├─ policy and resource limits
                                             ├─ deterministic SDD routing
                                             ├─ content-addressed dual review
                                             ├─ sanitized live activity
                                             └─ isolated proposal clone

受支持的 v0.1 拓扑刻意设计为单向：Claude Code → BoundedRelay → Codex。BoundedRelay 不提供 Codex 到 Claude 的返回路由，工作器也绝不会将生成的更改应用到源仓库。

[!IMPORTANT] BoundedRelay 是一个独立的社区项目。它与 Anthropic 或 OpenAI 无关联，未获得其认可，也不由其维护。Claude、Claude Code、Codex 和 OpenAI 分别是其各自所有者的商标。

0.1.0 版本是本地开发版。npm 包尚未发布，v0.1 没有远程服务、守护进程、数据库、持久化任务存储或审计账本。

为什么选择 BoundedRelay

• 可见而非冻结： 安全的活动标签、事件计数器、已用时间、距上次更新的时间、队列位置和修订感知的轮询。

• 默认只读： 分析始终请求 Codex 的 read-only 沙箱。

• 受限的权限： 服务器拥有工作区根目录、模型覆盖、环境转发、超时、并发、输出和补丁限制的控制权。

• 变更前审查： 提案模式在一次性克隆中工作，验证生成的补丁，并且绝不将其应用到源工作树。

• 自适应工作划分： 可选的 SDD 路由器首先选择最佳版本化的任务类型/通道匹配，仅在匹配平局后才使用偏好和中立份额，并发出依赖安全的波次，每波最多一个写入者。

• 带检查点的执行： 可选的 Spec Kit 包将已验证的路由转换为 execution.json，一次运行一个精确的依赖波，并要求每个写入者检查点是一个直接以活动基线为父提交的非合并提交。

• 独立的严格审查： 在分离的只读克隆中进行全新的、受模式约束的 Codex 审查之前，Claude 主机证据会被冻结，并且两个批准必须匹配同一个当前内容寻址的封印。

• 没有虚假进度： BoundedRelay 报告观察到的生命周期活动。它不会凭空捏造完成百分比或 ETA。

• 明确的公开接口： 专注于能力发现、工作区检查、路由、审查、提交、状态、结果、取消和历史的 MCP 工具。

Codex 工作时 Claude 可以显示什么

codex_worker_status 返回如下经过净化的快照：

{
  "status": "running",
  "revision": 14,
  "progress": {
    "phase": "working",
    "activity": "running_command",
    "activityLabel": "Codex is running a sandboxed command",
    "eventCount": 8,
    "commandCount": 2,
    "messageCount": 0,
    "lastEventType": "item.started",
    "updatedAt": "2026-08-27T18:30:00.000Z",
    "elapsedMs": 12420,
    "sinceLastUpdateMs": 180
  }
}

状态接口暴露的是固定的、由服务器拥有的活动词汇表。它不会暴露思维链、命令文本、工具参数、事件中的仓库文件路径或任意的 Codex 事件负载。

Related MCP server: Claude Code Bridge

适用场景

对于一般的 Claude Code 到 Codex 委派，请首先评估 OpenAI 官方的 openai/codex-plugin-cc。当你特别需要在 Codex 子进程周围设置本地 MCP 策略边界时，请使用 BoundedRelay。

请参阅详细的官方插件对比以及更广泛、不排名的生态系统对比。

先决条件

• Node.js >=22.13.0 和 npm；

• Git 在 PATH 中可用；

• 为当前操作系统用户安装并认证 Codex CLI；

• 支持本地 stdio MCP 的 Claude Code；

• 每个委派任务对应一个 Git 仓库。

BoundedRelay 使用受支持的 codex exec --json 非交互式接口。它没有凭据输入，也没有凭据存储。已保存的 Codex 认证通过正常的用户环境使用；直接转发 API 令牌是单独的选入项。

从源码快速开始

该包尚未发布到 npm。克隆或下载此仓库并在本地运行。

1. 安装、验证并检查本地环境

git clone https://github.com/mohammad19974/bounded-relay.git
cd bounded-relay
npm ci
npm run check
node dist/cli.js doctor

doctor 在不进行模型调用的情况下检查面向 Node 的依赖、Codex 命令兼容性、Git 和 Codex 登录状态。

要在不安装或修改使用者仓库的情况下检查打包的 Spec Kit 和 Claude Code 集成：

node dist/cli.js sdd validate
node dist/cli.js sdd path

验证器检查打包的文件和 JSON 清单。它不会调用或认证 Claude Code；单独的主机端验证步骤请参阅集成指南。

2. 向 Claude Code 注册构建好的工作器

在 BoundedRelay 目录中运行此命令，以便 shell 记录绝对路径。用户范围是推荐的个人默认值，因为当 Claude Code 打开其他项目时，同一安装仍然可用：

WORKER_ENTRY="$(pwd)/dist/cli.js"

claude mcp add \
  --transport stdio \
  --scope user \
  bounded-relay \
  -- node "$WORKER_ENTRY" serve

--scope user 仅属于你的操作系统账户，不会提交到仓库。若要将注册仅保留在单个项目中，请在运行命令前切换到目标 Git 仓库并使用 --scope local；本地范围属于执行命令的项目。

然后验证：

claude mcp list

在 Claude Code 中运行 /mcp。bounded-relay 应显示为已连接。

3. 运行第一次只读委派

在 Git 仓库中打开 Claude Code 并询问：

Use bounded-relay to inspect this workspace and start a read-only architecture review.
Poll codex_worker_status with afterRevision so you show each new activity without spam.
When the job completes, retrieve the result and summarize only high-confidence findings.

Claude 应使用 codex_worker_workspace、codex_worker_analyze、codex_worker_status 和 codex_worker_result。

关于 macOS、Linux、Windows PowerShell、项目范围配置、移除、升级和常见设置失败，请阅读完整的安装和首次运行指南。

MCP 工具

稳定的 v0.1 协议/配置命名空间仍然是 codex_worker_* 和 CCW_*。公开品牌是 BoundedRelay；在契约稳定之前保留这些明确的命名空间可以避免不必要的破坏性迁移。

阅读完整的工具参考，包括每个活动状态、输入、输出和失败代码。

安全契约

分析模式 — 默认

• 在规范允许的 Git 仓库中请求 Codex 的 read-only 沙箱。

• 拒绝仅用于提案的字段，如 writePaths 和 expectedRevision。

• 返回 Codex 的最终分析以及观察到的使用情况元数据。

自适应 SDD 路由 — 无模型

• 在不读取文件或调用模型的情况下，验证并规范化有界的任务 DAG。

• 首先使用硬性通道资格，然后使用版本化的任务类型匹配。

• 仅将符合条件的偏好应用于精确的基础匹配平局，然后参考中立的努力/任务数量份额。它绝不强制 50/50。

• 返回策略版本、通道匹配证据、决策阶段、原因、偏差、安全波次和内容指纹。

• 绝不授予直接写入权限；每波最多一个写入者。

结构化 SDD 审查 — 只读

• 在启动 Codex 之前冻结规范化的 Claude 主机证据，同时将其结论排除在 Codex 提示词之外。

• 严格模式要求干净的完整修订，封印精确的工件字节，并在经证明与封印匹配的、无 origin 的分离克隆中以只读方式运行 Codex。

• 在 Codex 之后重新检查源，并且仅当两个独立审查都批准同一个当前严格封印时才通过。

• 草稿模式和通用分析仅供参考，不能满足严格门禁。

提案模式 — 默认禁用

• 仅在服务器以 CCW_ENABLE_PROPOSALS=true 启动时注册。

• 要求干净的源树、精确的完整 Git 对象 ID 和明确的仓库相对写入路径。

• 在固定的修订处创建干净的一次性克隆。

• 仅在该克隆内运行 workspace-write。

• 拒绝更改的引用、更改的 HEAD、范围外的文件、受保护的路径、符号链接更改、过大的补丁和过多的更改文件数量。

• 返回经过验证的全索引二进制补丁和 SHA-256 摘要，然后删除克隆。

• 绝不将补丁应用到源、提交、推送、发布或部署。

仅在只读模式正常工作后才启用它：

claude mcp remove bounded-relay --scope user

claude mcp add \
  --env CCW_ENABLE_PROPOSALS=true \
  --transport stdio \
  --scope user \
  bounded-relay \
  -- node /absolute/path/to/bounded-relay/dist/cli.js serve

codex_worker_result 默认省略补丁文本。调用方必须请求 includePatch=true，验证返回的摘要，审查内容，并单独决定是否应用。在启用提案之前，请阅读完整的安全模型。

架构

flowchart TB
    Human[Human developer] <--> Host["Claude Code<br/>host orchestrator<br/>user-selected Claude model"]
    Host --> Plan["Spec Kit plan, committed tasks manifest,<br/>reviews, and human gates"]
    Plan --> Route["Verified adaptive route<br/>exact pending-ID coverage"]
    Route --> Ledger["execution.json<br/>dependency-ordered waves"]

    subgraph Relay["BoundedRelay MCP policy boundary"]
        Router["Deterministic router"]
        Review["Codex read-only lane<br/>analysis or detached strict review"]
        Proposal["Codex proposal<br/>revision-pinned disposable clone"]
    end

    Route <--> Router
    Ledger -->|Codex read-only task| Review
    Ledger -->|Codex write task| Proposal
    Ledger -->|claude-host task| Host
    Proposal -->|patch bytes + digest;<br/>never integrated by BoundedRelay| Host
    Host -->|inspect and integrate one writer| Checkpoint["Tested Git tree + exactly one<br/>non-merge checkpoint commit"]
    Checkpoint -->|next exact wave| Ledger
    Checkpoint -->|freeze host findings| Host
    Host -->|fresh strict review request| Review
    Host -->|frozen host evidence| Dual["Same-seal dual-review<br/>verification"]
    Review -->|strict sealed Codex evidence| Dual
    Dual --> Converge["Fail-closed convergence audit<br/>no direct implementation"]
    Converge -->|no new work| Proof["Revalidated proof pack<br/>isolated recheck + atomic handoff"]
    Converge -->|new pending tasks| Restart["Abort stale chain<br/>fresh routed run"]
    Restart --> Plan
    Proof --> Human

Claude Code 是唯一的主机编排器。Opus、Sonnet 和其他 Claude 模型是用户可选的主机模型，而不是此图中的独立代理。BoundedRelay 从不启动 Claude，也不会将这些模型选择变成三模型编排系统。

编排器 指 Claude Code 宿主协调命令、工件、门禁、提供商调用以及已获授权的集成。它不是第三个模型、模型选择器或自动合并器。BoundedRelay 是本地 编排边界 和 Codex worker 控制平面；称其为对称的 Claude/Codex 编排器会夸大其权限。

参见 架构 和 架构决策记录。

计划、执行与审查：使用 BoundedRelay 之前 vs. 之后

这是对工作流架构的定性比较，而非基准测试。实际正确性、速度、token 使用量和成本取决于任务、模型、提示词、仓库和账户；不保证任何改进或节省。任何示例工作量点数或提供商份额都只是说明性的规划元数据，并非实测用量、质量评分或基准结果。

受治理的路径在其信任边界处刻意采用顺序执行：

flowchart LR
    S[Specify] --> P[Plan]
    P --> PR[Independent<br/>dual plan review]
    PR --> R[Quality-first<br/>task routing]
    R --> X[Verified execution.json]
    X --> W[Do-while waves<br/>one writer + checkpoint]
    W --> IR[Routing-base-to-HEAD<br/>dual implementation review]
    IR --> V[Fail-closed convergence audit<br/>no direct implementation]
    V -->|no new work| CR[Fresh no-delta<br/>dual review]
    V -->|new pending tasks| NR[Fresh routed run]
    CR --> E[Revalidated proof pack<br/>isolated recheck + atomic handoff]

可选的 Spec Kit 工作流

此源仓库使用 .specify/ 来管理其自身的重大变更，但 Spec Kit 有意不是 BoundedRelay 的运行时依赖。npm 包在 integrations/ 下包含一个原创的可选 Spec Kit 工作流/扩展和 Claude Code 插件；它不会自动安装其中任何一个。

该工作流在全新的 Codex 审查之前冻结 Claude 的宿主审查，通过 codex_worker_sdd_route 路由已批准的任务，验证 routing.json，然后创建 execution.json。Spec Kit 的 do-while 按顺序执行规范的依赖波次。每个波次都从先前已验证的干净提交开始，在其唯一可能的 writer 之前处理就绪的只读任务，并且必须记录已接受的结果和检查回执，之后人工检查点才能推进它。默认的 5,000 基点 Codex 份额是中性元数据，而非配额。资格和适配性可以合理地产生任何实际份额，包括所有实施任务都在同一条通道上。

路由是根据其修订版本上精确提交的 tasks.md 准备的。其标准复选框任务 ID（T### 或更长）构成一个内容寻址清单，且分配必须恰好覆盖每个未完成的 ID 一次，不得路由已完成的或虚构的 ID。已批准的计划审查修订版本必须是该任务检查点的祖先；spec.md 和 plan.md 必须保持不变，并且在路由继续之前，完整的严格计划证据会重新验证。

检查回执是经过脱敏的、由协调者证明的摘要记录，涵盖命令、输出、工作目录、零退出状态、时间戳以及所测试的确切 Git 树。Writer 回执必须与该波次的检查点树匹配；收敛回执必须与其封存的审查树匹配。它们不是签名的 CI 证明，不包含原始输出，也无法独立证明协调者运行了所声称的命令。

Codex 写入切片仍然是隔离的提案。其确切的补丁字节仅保存在被忽略的、运行本地的 patches/<task-id>.patch 中；执行验证器重新计算摘要，将这些字节应用到活动基线处的临时 Git 索引，并要求生成的树等于检查点树。每个 writer 检查点必须恰好是一个非合并提交，其唯一父提交是活动基线。Claude Code 或人工协调者检查并集成补丁——BoundedRelay 从不这样做。被拒绝的门禁会中止该证据链。修正工件或代码并开始一次全新的运行；不要重用被拒绝的路由、执行账本、审查或证明包。

每个 Codex 执行结果都会记录 model 和 reasoningEffort（当路由使用服务器默认值时包括 null），并且两者都必须与路由策略完全匹配。关键的 Claude-host 任务会强制后续 Codex 交叉审查策略使用明确列入允许列表的 gpt-5.6-sol / ultra 配置；不可用时则失败关闭。宿主模型仍然是用户在 Claude Code 中选择的模型。

实施审查会比较已批准的路由基础修订版本与最终 HEAD，并拒绝超过 256 个变更路径的范围。收敛是失败关闭的：它只审计，从不直接实施。如果它追加了新的待处理任务，当前证据链将停止，这些任务需要一次全新的路由和波次运行；只有无变更结果才能基于已批准的实施修订版本进入无增量审查。对于实施和收敛，冻结的宿主审查 ID 绑定运行、阶段、nonce、封存修订版本、源证据摘要、检查摘要和准备好的 Codex 审查策略。最终的仅摘要 proof-pack.json 静态地重新验证完整的路由投影、确切的执行到实施再到收敛的源链、历史波次检查点、严格证据以及当前的收敛新鲜度。它索引摘要和已接受的标识符，而不复制提示词或原始提供商输出。

证明批准后，Claude 只写入一个运行本地的 handoff-draft.md。验证者将最终修订版本和运行证据复制到一个隔离的 Git 克隆中，在那里重新验证证明，检查草稿的确切绑定标记，并原子地发布 .specify/agents/HANDOFF.md。使用同一有效草稿重复验证是幂等的；它不会重新运行提供商工作。

claude-host 始终指在 Claude Code 中选择的模型。BoundedRelay 不启动 Claude、不选择 Opus/Sonnet，也不验证宿主声明的模型标签。每个关键路由都需要一条明确列入允许列表的 gpt-5.6-sol / ultra Codex 通道：当 Codex 拥有该任务时用于执行，当 claude-host 拥有该任务时用于交叉审查。不可用的配置会失败，而不是静默回退。

有关本地加载、工作流证据、严格门禁规则、恢复和移除，请参阅 完整的 Spec Kit 集成指南。

配置

安全默认值无需任何项目配置。

在转发机密或启用提案之前，请阅读 配置。

BoundedRelay 不声称什么

• 它不选择客观上“最佳”的模型。可选的模型和推理值仍然是明确的、由服务器列入允许列表的选择。

• 它不保证更好的代码、更低的 token 使用量或更低的成本。

• 它不会将本地检查回执、模型元数据或补丁到树的相等性转化为签名的 CI/提供商证明或正确性证明。

• 确切的清单覆盖仅证明记录的待处理 ID 已被路由，而不证明 tasks.md 是完整的或其任务设计良好。

• 高/严重阻塞适用于记录的结构化发现；它无法检测审查者的遗漏。

• 隔离的交接重新验证和原子重命名不会签署交接，也不能防止无关进程之后更改它。

• 它不会将私有的思维链作为进度公开。

• 它不会在 stdio 服务器进程退出后保持作业存活。

• 它不会阻止手动或由无关工具进行的写入。

• 它不会使 Codex 离线，也不会更改提供商的保留策略。

• 它不会自动应用、提交、推送、发布、部署或变更远程状态。

文档

• 入门

• 文档索引

• 架构

• 安全模型

• 实时状态与 MCP 工具

• 配置

• 兼容性

• Spec Kit 集成

• 生态系统对比

• 故障排除

• 开发

• 路线图

• 配方

• 品牌资产与生成说明

项目状态

0.1.0 有意处于预稳定状态。在 1.0.0 之前，契约可能会发生变化。升级前请查看 CHANGELOG.md 和 兼容性说明。

贡献、安全与支持

• 在开启 pull request 之前，请阅读 CONTRIBUTING.md。

• 通过 SECURITY.md 私下报告漏洞。

• 有关支持边界和诊断详情，请使用 SUPPORT.md。

许可证

MIT