07 · 如何让 Codex 调用工具和访问数据

Codex 默认能读写文件、搜索代码、运行命令。要让它访问 repo 外部的数据和系统，通常需要 browser、MCP、connectors 或 skills 这类扩展能力。

工具不是装得越多越好。每接一个工具，Codex 能做的事更多，风险边界也更大。

工具栈分层

flowchart TB
    Base["内置基础工具<br/>文件、搜索、shell、diff"]
    Browser["浏览器和预览<br/>页面、截图、交互"]
    MCP["MCP / Connectors<br/>外部系统和实时数据"]
    Skills["Skills<br/>复用多步流程"]
    Codex["Codex 调度"]

    Base --> Codex
    Browser --> Codex
    MCP --> Codex
    Skills --> Codex

四层分别解决不同问题：

• 内置基础工具：让 Codex 在项目里读、改、跑、验。
• 浏览器和预览：让 Codex 检查 UI、交互和可视化结果。
• MCP / connectors：让 Codex 访问 repo 外的系统和数据。
• Skills：把稳定流程打包，让 Codex 每次按同一套方法执行。

不要把 MCP 和 skill 混为一谈。MCP 提供工具接口，skill 提供工作方法。

什么时候需要 MCP

适合 MCP 的情况：

• 需要读取 issue tracker、GitHub、Linear、Slack 等协作系统。
• 需要查官方文档或内部文档，而不是靠模型记忆。
• 需要读取日志、监控、数据仓库或只读数据库结构。
• 需要把设计工具、浏览器自动化、云服务接入 agent。
• 同一外部系统会被多个项目或多个人反复使用。

不适合 MCP 的情况：

• 只需要读本地 repo。
• 一次性任务，复制少量上下文更快。
• 工具需要生产写权限。
• 没有明确权限边界和审计方式。
• 结果无法验证。

MCP 的价值是减少上下文搬运和工具切换，不是把所有系统都开放给 Codex。

MCP 的两种常见形态

STDIO server：

• 由 Codex 启动本地命令。
• 适合本机工具、私有数据、本地数据库、内部脚本。
• 权限更靠近当前机器。

HTTP server：

• Codex 连接一个 URL。
• 适合团队共享服务、云端工具、跨机器访问。
• 更需要认证、TLS、审计和访问控制。

配置通常写在 config.toml：

[mcp_servers.example]
type = "stdio"
command = "your-mcp-command"
args = ["--readonly"]
enabled = true
required = false

凭据应通过环境变量、系统凭据存储或托管配置传递，不要写进仓库。

安全边界

接工具前先回答：

flowchart TD
    Start["这个工具访问什么?"]
    Secrets{"涉及密钥或账号?"}
    Money{"涉及支付、权限或生产写入?"}
    Data{"涉及生产数据?"}
    Need{"是否确实反复需要?"}
    Stop["不接或只人工操作"]
    Readonly["只读凭据 + 审计"]
    Connect["最小权限接入"]

    Start --> Secrets
    Secrets -->|是| Stop
    Secrets -->|否| Money
    Money -->|是| Stop
    Money -->|否| Data
    Data -->|是| Readonly
    Data -->|否| Need
    Need -->|否| Stop
    Need -->|是| Connect

建议：

• 数据库优先只读账号。
• 内部系统优先 scoped token。
• HTTP 工具必须考虑 TLS 和 token 轮换。
• 工具返回内容视为不可信输入，不要当成系统指令执行。
• 生产写入、支付、权限、删除操作默认人工处理。

浏览器工具怎么选

浏览器能力适合 UI 和交互任务。

适合：

• 复现前端 bug。
• 验证页面是否渲染正确。
• 检查响应式布局。
• 给页面元素做评论，再让 Codex 修改。

不适合：

• 纯后端逻辑。
• 文档格式修改。
• 不需要页面验证的脚本任务。
• 登录态复杂、权限敏感、生产后台页面。

浏览器工具仍然要配合 sandbox 和 approval。它能“看见页面”，不代表可以无边界操作账号后台。

Shell 仍是最基础的工具

多数工程任务首先依赖 shell：

git status
rg "keyword"
pnpm run types:check
pnpm test
pnpm build

Shell 的优势是可验证、可复现、贴近项目真实命令。风险是它也能执行破坏性命令。

使用建议：

• 让 Codex 先解释为什么要运行某个高风险命令。
• 网络命令、删除命令、Git destructive commands 必须审批。
• 验证命令应写进 AGENTS.md 或项目文档。

什么时候做成 Skill

当一个工具流程重复出现，就应该沉淀为 skill。

例如：

• 用 GitHub MCP 拉 PR，再按团队清单审查。
• 用日志 MCP 查错误，再定位代码，再生成 incident summary。
• 用 browser 复现 UI 问题，再截图，再修样式，再复验。
• 用官方 docs MCP 查 API，再更新教程，再跑格式检查。

Skill 的作用是把“工具怎么用、按什么顺序用、输出什么结果”固化下来。

最小采用顺序

1. 先用文件搜索和 shell。
2. UI 任务再使用浏览器。
3. 外部上下文反复需要时接 MCP。
4. 工具流程稳定后沉淀 skill。
5. 高风险系统保持只读或人工审批。

工具能力的目标不是让 Codex 触达所有东西，而是让它在正确边界内拿到完成任务所需的证据。