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

⏱️ 预计阅读 13 分钟 ｜ 🎯 目标：把 Codex 从"只会读项目文件"变成"能用工具去外部世界查、做、验证"

上一篇讲 4 个入口怎么选。这一篇讲 Codex 在每个入口里能调用哪些工具 —— 文件系统、shell、浏览器、外部 API、数据库……都通过同一套机制接进来：MCP（Model Context Protocol，模型上下文协议）。

🎬 没有工具的 Codex 能干什么？

任务："给我看下 Stripe 的最新 API，按它写一个支付接入"。

💡 工具决定 Codex 能触达的世界有多大。 没工具 = 它只能在自己脑子里写代码；有工具 = 它能像你一样跑测试、查文档、点页面、读数据库。

🧱 Codex 工具栈：4 层能力

按"接的是什么"分四层：

flowchart TB
    subgraph L1["1️⃣ 内置基础层 —— Codex 自带"]
        File[📁 文件读写]
        Shell[🖥️ Shell 命令]
        Search[🔎 代码搜索]
    end

    subgraph L2["2️⃣ 浏览器层 —— App / IDE 内置"]
        Browser[🌐 内置浏览器<br/>开页面、点击、截图]
    end

    subgraph L3["3️⃣ MCP 层 —— 接外部工具的标准协议"]
        Stripe[💳 Stripe MCP]
        GitHub[🐙 GitHub MCP]
        DB[🗄️ Database MCP]
        Figma[🎨 Figma MCP]
    end

    subgraph L4["4️⃣ Skills 层 —— 把多步流程打包成一个动作"]
        Skill1[🔧 PR Review Skill]
        Skill2[📝 文档生成 Skill]
    end

    L1 --> L2 --> L3 --> L4 --> Codex[🤖 Codex 调度]

    style L1 fill:#dcfce7,stroke:#22c55e
    style L2 fill:#dbeafe,stroke:#3b82f6
    style L3 fill:#fef3c7,stroke:#f59e0b
    style L4 fill:#f3e8ff,stroke:#a855f7

🎯 加工具不是"装得越多越好"：先把 1-2 层用熟（默认就在），再按真实需求往 3-4 层加。

🔌 MCP 是什么？为什么它最重要

MCP（Model Context Protocol）= AI 工具的 USB 接口。

sequenceDiagram
    participant Codex
    participant MCP as 🔌 MCP 层
    participant Stripe as 💳 Stripe MCP Server
    participant API as 🌐 Stripe API

    Codex->>MCP: 问 最新支付接入文档
    MCP->>Stripe: 转发请求
    Stripe->>API: 调真实 Stripe Docs API
    API-->>Stripe: 返回最新文档
    Stripe-->>MCP: 结构化响应
    MCP-->>Codex: 你想要的最新文档

为什么不直接让 Codex 调 API？

📖 来源：OpenAI Codex · Model Context Protocol

MCP 服务器两种类型

配置在哪？

config.toml 里加 [mcp_servers.{名字}]：

# ~/.codex/config.toml （全局） 或 .codex/config.toml （项目级）

[mcp_servers.github]
type = "http"
url = "https://api.github.com/mcp"
bearer_token_env_var = "GITHUB_TOKEN"   # 从环境变量读 token

[mcp_servers.local-db]
type = "stdio"
command = "uvx"
args = ["mcp-postgres", "--db-url", "postgres://localhost/mydb"]
startup_timeout_sec = 10                # 默认 10 秒
tool_timeout_sec = 60                   # 默认 60 秒
enabled = true                          # 临时关掉就 false
required = false                        # true = 启动失败就报错

💡 CLI 和 IDE 扩展共享同一份 config.toml —— 配一次两边都能用。

🎯 怎么挑一个 MCP 服务器？3 步法

第 1 步 · 看你的痛点

第 2 步 · 看安全边界

flowchart TD
    A["🤔 这个 MCP 要访问什么"]
    A --> Q1{涉及生产数据吗}
    Q1 -->|是| Read["✅ 用 read-only 凭据"]
    Q1 -->|否| Q2{涉及钱 / 权限}
    Q2 -->|是| Manual["🛑 不接 MCP 人工操作"]
    Q2 -->|否| Free["✅ 可接"]

    style Manual fill:#fee2e2,stroke:#ef4444
    style Read fill:#fef3c7,stroke:#f59e0b

第 3 步 · 配最小权限

✅ 所有 token 走环境变量（bearer_token_env_var），不直接写 config.toml ✅ 数据库连 read-only 只读账号 ✅ required = false：MCP 挂了别让 Codex 整个跑不起来

🌐 浏览器工具：让 Codex 真的"看"页面

典型场景：

• 🐛 复现 bug：让 Codex 自己点几下页面，截图说明 bug 长什么样
• ✅ UI 验收：改完组件后，让它去页面上看渲染对不对
• 📱 响应式检查：375px 看一遍 + 1440px 看一遍
• 🔑 登录态测试：用测试账号登入后跑场景

何时用浏览器工具，何时不用：

🛠️ Shell 工具：让 Codex 跑命令

Codex 自带跑 shell 命令的能力（在 sandbox 里），这是最朴素也最强的工具。

典型用法：

让 Codex 跑：
- pnpm test          运行测试
- pnpm typecheck     类型检查
- pnpm build         构建
- git diff           看改动
- curl ...           调 API
- python script.py   跑脚本

⚠️ 回顾上篇：shell 命令在 sandbox 里跑，受 workspace-write / network=off 限制。要联网或动 workspace 外的文件，触发 approval。

📊 4 类工具的真实对比

🎯 判断口诀：默认靠文件 + Shell；UI 任务才开浏览器；接外部系统才上 MCP；流程重复 5+ 次才做 Skill。

🚫 常见误解 → ✅ 正确理解

🔍 想再深一层（点击展开）

# ~/.codex/config.toml

# === 公共 HTTP MCP（GitHub）===
[mcp_servers.github]
type = "http"
url = "https://api.github.com/mcp"
bearer_token_env_var = "GITHUB_TOKEN"
http_headers = { "X-API-Version" = "2026-01-01" }
startup_timeout_sec = 15      # 慢网络下加大
tool_timeout_sec = 60
required = false              # 挂了不影响 Codex 启动

# === 私有 STDIO MCP（本地数据库）===
[mcp_servers.prod-db]
type = "stdio"
command = "uvx"
args = ["mcp-postgres", "--db-url-env", "PROD_DB_URL"]
enabled = true

# === 临时禁用某个 MCP（不删配置）===
[mcp_servers.figma]
type = "http"
url = "..."
enabled = false               # 暂时关

你的主 Agent (Claude / Cursor / 别的)
  ↓ 通过 MCP 调
Codex (作为 MCP server)
  ↓ 干编程任务
返回结果

codex mcp serve

📝 本章自检

✅ 过关标准：能用一句话说清 —— "工具决定 Codex 能触达的世界有多大；MCP 是接外部工具的标准接口。"

📚 下一篇

• ➡️ 08 · Skills、Subagents、Hooks 解决什么问题 —— 复用 / 分工 / 自动检查的边界
• 📖 接入 MCP 工具和上下文
• 🛠️ 让 Codex 能调用你的命令行工具
• 📊 用 Codex 查询表格数据
• 🌐 用内置浏览器验收页面