codex-mcp

一个独立的、只读的质量门禁，用于 QA 工件。

codex-mcp 是一个独立的 MCP 服务器，它在作者代理撰写最终报告之前，将 Codex 作为对抗性第二评审者运行，对候选测试用例和缺陷发现进行审查。Codex 自行检查仓库，形成自己关于应该覆盖什么或缺陷是否真实存在的观点，然后才将其与给定的候选内容进行比较。

它返回一个评审差异。它从不写入你的工件。

Authoring agent (Claude, or any MCP client)
        │  gathers the requirement, reads the code, drafts candidates
        ▼
  candidate result — in memory, not yet written
        │
        ▼  codex_qualify
   codex-mcp ──► Codex (read-only sandbox, rooted at your repo)
        │           ├─ reads the code, the diff, the existing tests
        │           ├─ reads blast-radius / test-charter if present
        │           └─ reads Jira / DB / other MCPs if configured, read-only
        ▼
  review delta: accept · modify · remove · missing · evidence · limitations
        │
        ▼
Authoring agent reconciles, then writes the FINAL artifact

目录 · 安装 · 连接到项目 · 使用 · 配置 · 证据连接器 · 权限边界 · API 契约 · 故障排除 · 测试

为什么需要第二个模型，以及为什么只读

这里要解决的失败模式不是“代理无法编写测试用例”。而是代理在给自己的作品打分时会与自己意见一致。一个与作者共享上下文的评审者会继承作者的盲点。

因此，两个属性是承重的：

独立性。 Codex 被提示在仔细查看候选内容之前推导出预期的覆盖范围，并尝试反驳每个缺陷声明，而不是确认它。如果先以候选内容为锚点，会产生一个更随和的评审者，但用处也更小。

只读。 评审者在 Codex 的 read-only 沙箱中运行，它能到达的每个下游系统都通过一个策略层进行过滤，该策略层对每个工具进行分类，并拒绝任何会改变状态的操作。一个不能安全地指向实时仓库的质量门禁，是没有人会运行的质量门禁。

两个模型都不是权威的。源证据是：

requirement / runtime / code / DB / external evidence  >  model opinion

Related MCP server: tenth-man-mcp

安装

需要 Node 20+。每台机器只需执行四条命令。

# 1. The Codex CLI. codex-mcp drives it, and it owns your credentials.
npm install -g @openai/codex@latest

# 2. codex-mcp itself.
git clone <this-repo> codex-mcp && cd codex-mcp
npm install && npm run build && npm link

# 3. Sign in. A browser opens once; that is the whole flow.
codex-mcp login

# 4. Write a config, detecting any MCP servers already on this machine.
codex-mcp init --model gpt-5.6-sol

然后在信任它之前确认：

codex-mcp doctor

每一行都应显示 ok。doctor 是只读的，并且对实时项目是安全的——有关每个失败的含义，请参阅 故障排除。

npm 名称 codex-mcp 属于一个无关的包。请按上述方式从源码安装，或在你自己的作用域下发布。

init 的作用

它写入 ~/.config/codex-mcp/codex-mcp.yaml，如果它在常规位置发现了下游 MCP 服务器，还会在旁边写入一个 .env：

$ codex-mcp init --dry-run
Would write into /home/you/.config/codex-mcp
  codex-mcp.yaml  (new)
  .env            (new)

Detected:
  jira-mcp (jira) -> /home/you/jira-mcp/src/index.js
  db-mcp (database) -> /home/you/db-mcp/dist/index.js

检测到的服务器被写为你可以启用的连接器条目，其路径保留在 .env 中，以便 YAML 在不同机器之间保持可移植。--force 会覆盖；没有它，现有文件会被保留。

init 是唯一写入任何内容的命令，并且它在任何评审存在之前运行。评审本身严格是只读的。

更喜欢自己编写配置？将 codex-mcp.example.yaml 复制到 ~/.config/codex-mcp/codex-mcp.yaml——其中的每个值都有注释，并且除非其注释另有说明，否则都是内置默认值。

身份验证

每台机器一条命令：

codex-mcp login          # browser opens; sign in to ChatGPT
codex-mcp auth-status    # confirm

凭据会进入 Codex CLI 自己的存储（~/.codex/auth.json，模式 0600），并由它刷新。它们会在重启和终端之间持久存在——你不需要为每个项目或每个会话重新登录。

codex-mcp 从不处理凭据本身。 它没有 OAuth 客户端、没有回调监听器、没有令牌存储。它调用 codex login status 并读取是/否。这里没有任何东西可以在评审期间打开浏览器：未认证的调用会快速失败，而不是继续。

{ "code": "CODEX_AUTH_REQUIRED", "message": "Codex is not authenticated. Run `codex-mcp login`." }

改用 API 密钥

codex-mcp login --mode api                    # hidden prompt
printenv OPENAI_API_KEY | codex-mcp login --mode api

密钥从 --api-key、然后是 OPENAI_API_KEY、然后是隐藏提示中读取，并通过 stdin 管道传递给 codex login --with-api-key——绝不是 argv 元素，因此它不会出现在你的进程表或 shell 历史中。Codex CLI 存储它；codex-mcp 不存储。

在你的配置中设置 auth.mode 以匹配。如果 CLI 的认证模式与配置声明的不一致，评审会以清晰的错误失败，而不是静默地向错误的账户收费。

连接到项目

选择一个。注册两次是最常见的设置错误——请参阅下面的警告。

选项 A — 一个项目，已提交

在项目根目录创建 .mcp.json——而不是 .claude/，后者包含一组不同的文件，并且会忽略它：

{
  "mcpServers": {
    "codex-mcp": { "command": "codex-mcp", "args": ["start"] }
  }
}

提交它。每个已运行 安装 的队友现在都拥有了门禁，使用他们自己配置中的模型选择。

选项 B — 所有项目，不提交

claude mcp add codex-mcp -- codex-mcp start

这会写入 ~/.claude.json，并在你工作的任何地方生效。

只在一个地方注册。 claude mcp add 以 本地作用域 写入，它优先于 .mcp.json。如果两者都存在，项目文件——包括其中的任何 env——会被静默忽略。如果你要切换到 .mcp.json，请运行 claude mcp remove codex-mcp。

重启 Claude Code。/mcp 现在应该列出 codex-mcp 及其三个工具。如果没有，请参阅 故障排除。

其他 MCP 客户端使用相同的两个字段——command: codex-mcp、args: ["start"]——无论它们使用什么配置文件。

使用

使其自动化

在项目的 CLAUDE.md 中添加一条规则。这是整个集成表面——任何地方都没有项目特定的 Codex 逻辑：

## Independent QA qualification

Before finalizing test cases or bug reports, send the complete candidate result,
project root, task/requirement context, and any available blast-radius or
test-charter to codex-mcp for independent qualification.

Reconciling means verifying each objection against the evidence it cites — not
accepting it. Apply what the evidence supports. Reject what it does not, and note
why. codex-mcp is a second opinion, not an approver.

One pass is normal. Run a second only if the first forced substantial high-risk
changes.

有了这个，你只需正常请求，门禁就会自动运行：

为 DEV-2951 创建测试用例。

代理收集需求、阅读代码、起草候选、调用 codex_qualify、协调，然后撰写报告。

显式请求

当没有规则时，或者你想对已起草的内容使用它时：

在撰写报告之前，将这些测试用例发送给 codex-mcp，设置 project.root 为 /path/to/repo，task.id 为 DEV-2951。向我展示它反对什么，以及你是否同意，然后撰写最终版本。

将你刚刚编写的缺陷发现通过 codex_qualify 运行，使用 reviewType: "bugs"。对于它称为误报的内容，在删除发现之前检查它引用的代码。

针对 codex-mcp 对这些进行资格评估，但只报告引用的证据实际成立时的反对意见。告诉我你拒绝了哪些以及为什么。

有用的变体：

阅读返回的内容

要求你的代理展示这些，而不是静默地处理它们：

• missing — 它说你的覆盖缺失。检查引用的 file:line 是否真实。

• modify — 你的期望与代码矛盾。通常是最尖锐的发现。

• remove — 冗余。验证它说取代你的东西确实如此。

• limitations — 它无法验证的内容。一个自信的评审如果限制列表很长，那就是一个狭窄的评审；在信任其余部分之前先阅读这个。

• disagreements — 它和你的代理对相同证据有不同的解读。这些需要你，而不是任何一个模型。

一个好的后续提示：

对于每个反对意见，告诉我它引用的证据以及你是否自己验证了。列出你拒绝的任何内容以及原因。

它不会做什么

它从不编辑文件、提交、推送、写入 Jira 或数据库，或撰写你的报告。如果你的代理声称 codex-mcp 更改了某些内容，它没有——请检查 git status。

协调——关键部分

codex-mcp 从不告诉你接受 Codex。每个响应都带有：

{
  "reconciliation": {
    "instruction": "This is an independent second opinion, not a verdict...",
    "codexIsNotAuthoritative": true
  }
}

Codex objection
      │
      ▼
Author verifies the cited evidence
      │
      ├─ evidence supports it   → apply
      ├─ evidence does not      → reject, and record why
      └─ unclear                → investigate

然后你撰写最终工件。

循环保护

review.maxPasses（默认 2）限制循环。第 1 轮是正常情况；第 2 轮用于强制进行重大高风险更改的评审。超过限制的请求会被拒绝，meta.furtherPassesAllowed 会告诉你预算何时用完。迭代直到两个模型一致不是目标——一致是廉价的，达到一致通常意味着其中一个停止了思考。

配置

设置位于 ~/.config/codex-mcp/codex-mcp.yaml。这是唯一需要编辑的文件。codex-mcp.example.yaml 是带注释的版本，包含当前的 Codex 模型 ID。

缺少配置文件是完全支持的——服务器以默认值启动，这些默认值是安全的。你失去的是模型固定和所有连接器，因为连接器只能在 YAML 中定义。

模型放在哪里

review:
  model: gpt-5.6-sol
  requireModel: true

三个层可以设置它。最高优先级获胜：

将模型保持在一个层中。在两个地方设置的键会使较低副本失效——编辑它似乎没有效果。当模型在两个地方设置且两者不一致时，doctor 会发出警告。

要为整个团队固定一个项目，请从 选项 A 向 .mcp.json 添加 env：

{
  "mcpServers": {
    "codex-mcp": {
      "command": "codex-mcp",
      "args": ["start"],
      "env": { "CODEX_MODEL": "gpt-5.6-sol", "CODEX_REASONING_EFFORT": "high" }
    }
  }
}

这保证了每个人都得到相同的评审者，这在跨团队比较发现时非常有价值。代价是：队友的 Codex CLI 太旧而无法使用该模型时，会收到一个硬性的 CODEX_MODEL_NOT_AVAILABLE，告诉他们运行 codex update。这个失败是故意的——否则他们会静默地得到一个较弱的评审者，并信任其裁决。

选择哪个模型。 优先选择前沿模型。这里的全部价值在于捕捉作者代理遗漏的内容，而较便宜的评审者大多同意它所看到的内容。在共享门禁上设置 requireModel: true，这样对 Codex 默认值的更改就不会静默地改变评审质量。不可用的模型会引发 CODEX_MODEL_NOT_AVAILABLE；codex-mcp 不会回退到另一个模型。

每个设置及其环境变量

优先级：环境 > codex-mcp.yaml > 默认值。 这些变量用于在不编辑文件的情况下覆盖一个 YAML 值——在 .mcp.json 的 env 中固定项目，或在 shell 中用于一次性操作。

连接器设置反转了上述优先级：YAML 优先，因为它是针对每个连接器的显式意图，而这些变量只是在没有 YAML 另行规定时的粗略回退。

这些开关匹配连接器的名称，而非其类型——名为 jira-mcp 和 db-mcp 的连接器既不匹配 jira 也不匹配 database，因此两者都归入 CUSTOM_MCPS_ENABLED。在 YAML 中设置 enabled: 可以完全避免这个问题。

有两个变量没有对应的 YAML 设置，因为它们在定位任何配置文件之前就被读取：CODEX_MCP_CONFIG（配置文件的路径）和 XDG_CONFIG_HOME（在其中查找 ~/.config/codex-mcp/ 的目录）。

配置文件的位置

先命中者优先：

--config <path>  →  $CODEX_MCP_CONFIG  →  ./codex-mcp.yaml  →  ~/.config/codex-mcp/codex-mcp.yaml

doctor 会打印它加载了哪一个。如果所选文件旁边存在 .env，则会被读取；没有任何文件是必需的。它只值得存放因机器而异的数值——YAML 中以 ${JIRA_MCP_PATH} 引用的连接器路径——即使这些路径也可以携带 ${VAR:-fallback} 默认值。

切勿将凭据放入 .env 或 YAML 中。 CHATGPT_TOKEN、SESSION_TOKEN、ACCESS_TOKEN 和 REFRESH_TOKEN 会被直接忽略，并且它们的存在会被报告为配置警告。Codex 身份验证属于 Codex CLI 和你的操作系统凭据存储。

证据连接器

Codex 从不直接与 Jira 或你的数据库通信。它连接到 codex-mcp 证据代理，这是一个独立的只读进程，负责发现每个下游服务器的工具、对其进行分类，并且只转发通过策略的工具——在每次调用时重新检查，而不仅仅是在发现时。

# ~/.config/codex-mcp/codex-mcp.yaml
connectors:
  jira-mcp:
    enabled: true
    kind: jira
    approval: once
    transport: stdio
    command: node
    args: ['/path/to/jira-mcp/src/index.js']
    cwd: /path/to/jira-mcp

  db-mcp:
    enabled: true
    kind: database
    approval: once
    transport: stdio
    command: node
    args: ['/path/to/db-mcp/dist/index.js']
    cwd: /path/to/db-mcp
    allowTools: ['execute_query']
    denyTools: ['update_query']
    maxRows: 500
    timeoutMs: 10000

kind 驱动归一化到稳定的词汇表——requirement.read、database.query_readonly、testmanagement.search、external_file.read——这样审查提示就可以要求“需求”，而无需知道你的连接器是将其称为 getJiraIssue 还是 get_jira_ticket。未映射的工具仍会以其自身名称暴露；添加新的面向读取的 MCP 无需修改代码。

下游服务器只接收 PATH、HOME 以及其自身配置声明的 env——绝不会接收 codex-mcp 进程的环境。

无法访问的连接器将审查降级为记录在案的限制，而不是使审查失败。缺失的证据是审查的一个事实，响应会明确说明这一点。

添加连接器后运行 codex-mcp doctor。每个连接器行都会报告暴露了多少工具以及因策略被扣留了多少工具：

[  ok  ] Connector: jira-mcp
           4 read-only tool(s) exposed, 0 withheld by policy.
[  ok  ] Connector: db-mcp
           6 read-only tool(s) exposed, 1 withheld by policy.

请求许可——approval 字段

读取交给你的项目不需要许可：你提供了 project.root，因此读取它本身就是请求。访问项目之外的内容——工单跟踪器、生产数据库、文件服务器——是另一个独立的决定，而数周前写入配置文件中的 enabled: true 并不是对今天审查的知情同意。

提示通过 MCP elicitation 传递，因此它会到达你的 MCP 客户端中的人类。如果你的客户端无法显示提示，连接器将被跳过并记录在 limitations 中——而不是被静默允许。没有人能看到的提示不是同意。对已经审查过的连接器设置 approval: trusted。

需求

当配置了 jira 类型的连接器且设置了 task.id 时，Codex 会自行读取工单，并将你传递的任何需求文本视为编写代理的解释——一个需要调和的声明，而不是来源。如果没有连接器，它会回退到你提供的文本，并记录无法独立验证该文本。

数据库

仅在可能改变裁决结果时才会被查阅：持久性、关系、租户所有权、状态转换、迁移、数据完整性、验证报告的缺陷。提示中会明确说明这一点，策略层会强制执行其余部分。

使用只读数据库账户。codex-mcp 会拒绝所有变更语句，但只读授权才是不依赖此服务器正确性的边界。

权限边界

核心规则：Codex 可以广泛检查，但绝不修改任何内容。

请按字面意思理解“广泛”——在将其指向一台存有你关心的秘密的机器之前，请先阅读下面的 读取范围比项目更广。

强制执行，分层进行：

1. Codex 自身的 read-only 沙箱——主要边界。

2. 命令策略——基于 argv，默认拒绝。未知二进制文件被拒绝；shell 包装器被拒绝，因为其载荷无法分类。

3. SQL 策略——在关键字扫描之前剥离注释和字符串字面量，因此变更操作无法隐藏在带引号的值中。每次调用一条语句，当查询没有行数上限时注入行数上限。

4. 工具策略——每个下游 MCP 工具都被分类为 read / write / destructive / unknown；只有 read 被暴露。unknown 被拒绝，除非被显式加入允许列表，并且任何允许列表都无法拯救变更工具——一个你可以通过争论绕过的边界不是边界。

分类器刻意不对称：任何变更的迹象都胜过任何读取的迹象，并且工具必须看起来明确是只读的才能被暴露。一个听起来不安全但实际上安全的工具只会让你多花一行配置；一个听起来安全但实际上不安全的工具会让你付出数据的代价。

tests/security/ 断言了所有这些，包括被拒绝的调用永远不会到达下游服务器，以及审查后夹具仓库字节完全相同。

读取范围比项目更宽

Codex 的 read-only 沙箱限制的是写入，而不是读取。在沙箱内，Codex 可以读取你的用户账户可以读取的任何文件——不仅仅是 project.root 下的文件。直接验证：

$ codex exec --sandbox read-only -C ./proj   "read ../outside.txt"
exec  sed -n '1,$p' ../outside.txt   in .../proj
      succeeded: SECRET_OUTSIDE=canary-9f3a2b

Codex CLI 不提供缩小读取范围的选项；sandbox_permissions 只会授予更多访问权限。因此，保证的诚实表述是：

任何地方都不会被修改。读取范围受你的操作系统文件权限限制，而不是 project.root。

project.root 引导审查者查看的位置——它是工作目录和提示的主题——但它不是读取监狱。

这在实践中意味着什么：

• 你的用户可读取的任何位置的 .env、私钥或凭据文件都可能被审查者访问，并且其内容可能作为模型上下文的一部分发送给 OpenAI。

• codex-mcp 自身的工件路径包含（assertArtifactPathAllowed）阻止 codex-mcp 将项目之外的文件读取到提示中。它不能且无法限制 Codex 在其自身沙箱内读取的内容。

• 发现结果在记录之前会被编辑，但那是日志控制，而不是包含控制。

如果这对你的环境很重要，请在容器或虚拟机中运行 codex-mcp，并且只挂载项目。这是目前唯一可靠的限制读取范围的方法。

审查者按设计读取的内容

在项目根目录内，它读取所有内容，包括点目录。将 .claude、.cursor、.github 或团队自己的 .qa 隐藏起来不让审查者看到，会导致它忽略项目为其写下的规则。已知的工具缓存（.venv、.pytest_cache、.next 等）仍会被列出，但不会被推荐为阅读材料。

约定文件——CLAUDE.md、AGENTS.md、CONTRIBUTING.md、TESTING.md、.cursorrules、CODEOWNERS——会被呈现到提示词中，作为“先读这些”。

契约

codex_qualify

必需：reviewType、project.root 以及匹配审查类型的候选集。其他一切都是可选的，并且绝不会阻止审查。

{
  "reviewType": "test-design",

  "project": { "root": "/absolute/path/to/project", "branch": "feature/DEV-123" },

  "task": {
    "id": "DEV-123",
    "source": "jira",
    "title": "Archive a resource",
    "description": "A user may archive a resource belonging to their own tenant.",
    "acceptanceCriteria": ["Archiving an active resource sets status to archived."]
  },

  "artifacts": {
    "blastRadiusPath": "docs/blast-radius.md",
    "testCharterPath": "docs/test-charter.md"
  },

  "candidate": {
    "testCases": [{ "id": "TC-001", "title": "Archive an active resource", "priority": "high" }],
    "bugs": []
  },

  "options": { "useJira": true, "useDatabase": true, "useExternalMcps": true }
}

候选集在载荷中传递。它们尚未被写入任何地方，要求临时报告文件会违背目的。

工件路径在 project.root 内解析；逃逸该路径的路径会被拒绝。

审查类型

测试设计结果

{
  "status": "CHANGES_REQUIRED",
  "summary": { "accepted": 18, "modify": 2, "remove": 1, "missing": 3 },
  "accepted": ["TC-001", "TC-002"],
  "modify": [{
    "candidateId": "TC-014",
    "reason": "Expected state contradicts persistence logic.",
    "evidence": [{ "source": "code", "location": "src/session/service.ts:143" }],
    "recommendation": "Queue should remain persisted after this transition."
  }],
  "remove": [{ "candidateId": "TC-022", "reason": "Duplicates TC-018.", "supersededBy": "TC-018" }],
  "missing": [{
    "title": "Verify cross-tenant access is rejected",
    "priority": "high",
    "dimension": "authorization",
    "reason": "Target lookup accepts an externally supplied identifier.",
    "evidence": [{ "source": "code", "location": "src/resource/controller.ts:82" }]
  }],
  "disagreements": [],
  "limitations": []
}

Bug 结果

{
  "status": "CHANGES_REQUIRED",
  "summary": { "verified": 1, "falsePositive": 1, "needsMoreEvidence": 0, "other": 0 },
  "findings": [{
    "candidateId": "BUG-003",
    "verdict": "FALSE_POSITIVE",
    "confidence": "high",
    "severityAssessment": null,
    "reason": "Ownership validation occurs in router-level middleware.",
    "evidence": [
      { "source": "code", "location": "src/routes/users.ts:42" },
      { "source": "code", "location": "src/middleware/access.ts:91" }
    ],
    "recommendation": "Remove the finding unless runtime evidence contradicts the middleware."
  }],
  "limitations": []
}

status：PASS · CHANGES_REQUIRED · INCONCLUSIVE · ERROR

verdict：VERIFIED · FALSE_POSITIVE · NEEDS_MORE_EVIDENCE · SEVERITY_DISAGREEMENT · DUPLICATE_OR_ALREADY_COVERED · INCONCLUSIVE

信封保证的内容

codex-mcp 在返回审查结果之前会对其输出进行规范化，因为模型在给列表评分时有时会偏离：

• 审查者编造的 id 会被丢弃，并附上说明——你无法对不存在的测试用例引用采取行动；

• 审查者从未提及的候选者会被记录为未审查，绝不会被提升为已接受，因为沉默不等于认可；

• 没有 verdict 的 bug 会变成明确的 INCONCLUSIVE；

• summary 计数会根据数组重新计算；

• status 是根据增量推导出来的，而不是根据审查者的自我评估。

meta.evidence 报告审查实际基于什么——git、blast-radius、test-charter 和 requirement 访问是否可用，以及哪些连接器可达。项目路径本身永远不会被记录或返回；meta.evidence.projectRootId 是一个哈希值。

codex_auth_status

Codex 是否已认证、以何种模式认证，以及这是否与你配置的 auth.mode 匹配。绝不返回凭据。

codex_capabilities

诊断信息。此实例可以访问哪些证据、哪些下游工具被扣留及原因，以及审查者被明确禁止做什么的列表。

CLI

codex-mcp init         # write ~/.config/codex-mcp/, detecting local MCP servers
codex-mcp start        # run the MCP server on stdio (what a client launches)
codex-mcp login        # authenticate (--mode chatgpt|api)
codex-mcp auth-status  # report auth state, never credentials
codex-mcp doctor       # diagnose everything; mutates nothing

init 接受 --model <id>、--force 和 --dry-run。start 和 doctor 接受 --config <path>。doctor 还接受 --project <path> 和 --json。

codex-mcp broker 是内部命令——即 Codex 启动的证据代理。你不应手动运行它。

故障排查

doctor 报告的每一项要么是 ok、warn（可用，但比应有的更宽松），要么是 FAIL（审查无法工作）。

错误

稳定的错误码，可以安全地用于分支判断。负载在离开进程之前会被脱敏。

CODEX_AUTH_REQUIRED              CODEX_NOT_INSTALLED
CODEX_MODEL_NOT_CONFIGURED       CODEX_MODEL_NOT_AVAILABLE
INVALID_PROJECT_ROOT             PROJECT_ACCESS_DENIED
INVALID_REVIEW_REQUEST           INVALID_REVIEW_TYPE
DOWNSTREAM_MCP_UNAVAILABLE       DOWNSTREAM_MCP_PERMISSION_DENIED
DB_QUERY_DENIED                  DB_QUERY_TIMEOUT
CODEX_EXECUTION_FAILED           CODEX_OUTPUT_INVALID
REVIEW_TIMEOUT                   INTERNAL_ERROR

如果 Codex 返回的输出不符合 schema，codex-mcp 会重试一次，并附上禁止重新分析的明确修正。如果仍然失败，则返回 CODEX_OUTPUT_INVALID。它不会返回部分解析的审查结果——因为你会基于它采取行动。

可观测性

结构化 JSON 输出到 stderr（stdout 属于 MCP 传输层）。记录的内容：审查 id 和类型、项目 id 哈希、模型、耗时、连接器可用性、候选者数量、Codex 退出状态、schema 验证状态。

绝不记录：令牌、密码、数据库凭据、cookie、源代码中发现的机密。脱敏在每个级别都执行，包括 debug 级别。

测试

五层，从最便宜的做起。逐层向下——某一层失败会使下一层的结果失去意义。

1. 自动化测试套件——免费、离线、约 7 秒

npm install
npm run build
npm test
npm run typecheck

400+ 个测试，针对一个模拟的 Codex CLI 和一个故意敌对的模拟 MCP 服务器。无需网络、无需模型调用、确定性执行。这是你在每次变更和 CI 中运行的测试。

tests/security/ 是值得阅读的部分：它断言文件编辑、提交、推送、issue 写入和数据库变更都会被拒绝——并且被拒绝的调用永远不会到达下游服务器。

2. doctor——此安装是否正确接线

codex-mcp doctor
codex-mcp doctor --project /path/to/repo

只读，可安全地针对实时项目运行。检查 Node、Codex CLI、认证、认证模式一致性、模型、沙箱、配置文件以及每个已配置的连接器。

3. codex_capabilities——它实际能访问哪些证据

doctor 给出数量；这个给出每个工具的明细，包括每个被扣留工具被扣留的原因。从你的 MCP 客户端调用它，或者：

node -e "
import('./dist/src/config/config.js').then(async ({loadConfig}) => {
  const {CodexMcpServer} = await import('./dist/src/server.js');
  const {Logger} = await import('./dist/src/util/logger.js');
  const s = new CodexMcpServer({config: loadConfig(), logger: new Logger('error', {}, {write(){}})});
  console.log(JSON.stringify(await s.callToolForTesting('codex_capabilities', {}), null, 2));
  process.exit(0);
});"

检查你期望的工具是否在 allowedTools 中，并且 deniedTools 中的每个条目都是你希望被拒绝的。名称不寻常的只读工具会以 unknown 身份进入 deniedTools——将其添加到该连接器的 allowTools 中。

4. npm run try——真实审查、真实模型、真实成本

这是唯一消耗预算的层。它验证了完整路径：认证、模型、沙箱、证据收集、连接器、提示词、结构化输出。

npm run try -- --project /path/to/repo
npm run try -- --project /path/to/repo --type bugs
npm run try -- --project /path/to/repo --type combined --task DEV-123
npm run try -- --project /path/to/repo --candidates ./candidates.json --json

不带 --candidates 时，它会发送一组包含已知缺陷的种子数据——两个重复项、一个与代码矛盾的断言，以及几个明显的缺口。这正是重点：你在测试审查者，所以要使用你已知正确答案的输入。

从以下方面评判：

• 它是否将重复项放入了 remove？

• 它是否将被反驳的断言放入了 modify，并引用了代码？

• 每个 missing 条目是否都有真实的 file:line，而不是模糊的区域？

• 之后仓库是否保持不变（git status）？

种子数据集上的 PASS 意味着出了问题，而不是你的代码是干净的。

使用你自己的 JSON 提供 --candidates 来演练真实工作流：

{ "testCases": [{ "id": "TC-1", "title": "..." }], "bugs": [] }

5. 端到端夹具——可选加入

CODEX_MCP_E2E=1 npm test -- tests/e2e

构建一个包含真实覆盖率缺口（幂等性）和一个已被路由中间件反驳的 bug 报告的夹具仓库，针对真实的 Codex CLI 运行完整的资格验证，并断言夹具之后逐字节相同。需要几分钟。

作为 MCP 服务器驱动它

一旦上述各层通过，就按照客户端的方式驱动它：

printf '%s\n%s\n%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"smoke","version":"1"}}}' \
  '{"jsonrpc":"2.0","method":"notifications/initialized"}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
  | codex-mcp start

然后在 Claude Code 中注册它，并在真实工单上使用它。

开发

src/
  config/      resolution, precedence, validation
  auth/        Codex CLI delegation for both auth modes
  codex/       process spawning, argv construction, output parsing
  review/      orchestration, per-type reviewers, output normalization
  evidence/    repository, git, artifacts, requirement, database, external
  mcp-broker/  downstream clients, discovery, classification, the broker server
  policy/      command, SQL, MCP-tool, permission, and consent decisions
  prompts/     base reviewer, test-design, bug-review
  schemas/     public request and result contracts
  tools/       the three MCP tools

许可证

MIT