2  使用AI写代码：Codex

Modified

2026-05-08

2.1 背景

学会在Cherry Studio里和AI聊天后，大毛很兴奋，马上让AI帮自己写了一个差异分析脚本。可现实很快泼了冷水：他把手动把代码从AI复制到编辑器里，报错；他又把错误信息复制AI，AI给出新的代码，复制回去还是报错。来来回回的手动复制粘贴，让大毛觉得自己只是个无能的工具人，心情十分无奈。

有一天，大毛看到师兄直接在终端里让AI进入项目、读取文件、修改代码、顺手修 bug，整个过程几乎不用来回复制粘贴。他这才明白，真正高效的AI写代码，不是“让AI给你一段代码”，而是“让AI走进你的项目里帮你干活”。那么，这种工具该怎么配、怎么用？

2.2 简介

使用AI写代码有这么几种方式：

  • 复制粘贴法：直接将代码片段复制到网页或本地软件的对话界面中，让AI帮忙修改或生成代码。
    • 优点：操作简单，适合小段代码的处理。
    • 缺点：来回复制粘贴较为繁琐；AI无法获取项目的整体上下文信息，可能导致生成的代码不符合预期。
  • 集成开发环境（IDE）插件法：在常用的IDE中安装AI插件，例如VSCode的RooCode、GitHub Copilot等，直接在编写代码时获得AI的帮助。
    • 优点：无缝集成到开发流程中，提高效率；可以根据上下文生成更符合需求的代码。
    • 缺点：固定在特定的IDE中使用；部分插件在操作过程中有明显延迟。
  • 命令行（CLI）工具法：使用命令行工具调用AI服务，例如使用OpenAI的Codex、Anthropic的Claude Code等，通过命令行与AI进行交互。
    • 优点：效果在这三种方法里最佳；适合喜欢使用命令行的开发者；可以灵活地集成到各种开发流程中。
    • 缺点：需要一定的命令行操作基础；可能需要额外的配置工作。

目前比较强的 CLI AI 编码工具，主流还是 OpenAI 的 Codex 和 Anthropic 的 Claude Code。两者都很强，但 Codex 的官方生态目前更完整：既有 CLI，也有 IDE 扩展、Cloud task、MCP、Skills 和 Subagents。并且根据最新官方定价，ChatGPT Free、Go、Plus、Pro、Business、Edu、Enterprise 都已经包含 Codex，只是可用额度和功能范围不同；如果要做自动化，也可以直接使用 API key。因此，下面我们将以 Codex 为例，介绍如何用命令行工具来调用 AI 写代码。

2.3 获取Codex服务

查看 Section 3.5.2 中的说明。按最新官方文档，普通个人用户优先考虑 ChatGPT Plus / Pro；团队场景可以考虑 Business / Enterprise / Edu；如果是脚本、CI 或中转代理场景，则优先使用 API key。

2.4 安装Codex命令行工具

Codex CLI 官方推荐的安装方式是：

npm i -g @openai/codex

如果您已经在使用 Chapter 6 中介绍的 Pixi，也可以继续用 Pixi 来管理它：

pixi global install codex

Codex CLI 目前对 macOS 和 Linux 的支持最好；Windows 仍属于实验阶段，更推荐在 WSL2 中使用。

如果您使用 VSCode，也可以同时安装官方的 Codex IDE 扩展。CLI 和 IDE 扩展共用同一套 ~/.codex/config.toml 配置，因此配一次通常就够了。

2.5 配置并启动Codex

根据最新官方文档，Codex CLI 和 IDE 扩展都支持两种登录方式：

  • 用 ChatGPT 账号登录：适合个人日常使用，也是默认方式。
  • 用 API key 登录：更适合脚本、CI 或中转服务。

如果您使用的是官方订阅，最简单的方式就是直接运行：

codex

随后按提示在浏览器中登录即可。

如果您使用的是中转商或代理服务，更推荐使用自定义 provider + 环境变量，而不是手动往 auth.json 里写第三方 key。现在 auth.json 主要用于 Codex 自己缓存登录凭据；第三方 provider 的密钥，最好放在环境变量里。

假设中转商给您的信息如下：

API地址：https://api.example.com/v1
API密钥：sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

那么可以在 ~/.codex/config.toml 中这样配置：

model = "gpt-5.4"
model_provider = "relay"

[model_providers.relay]
name = "My relay"
base_url = "https://api.example.com/v1"
wire_api = "responses"
env_key = "RELAY_API_KEY"

然后在 shell 环境中设置密钥：

export RELAY_API_KEY="sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
codex

如果您只是想改 OpenAI 官方 provider 的地址，比如切换到某个地区入口或企业代理，那么优先使用顶层的 openai_base_url，不必额外新建 provider：

openai_base_url = "https://us.api.openai.com/v1"
NoteNote

旧教程里常见的做法是：既设置 env_key，又设置 requires_openai_auth = true。根据最新文档，这两者不应同时使用；如果设置了 requires_openai_auth = true，env_key 会被忽略。

如果您担心本机凭据安全，可以考虑在配置中加入：

cli_auth_credentials_store = "keyring"

这样 Codex 会优先使用操作系统的凭据存储，而不是明文文件。

2.6 常用的Codex命令和快捷操作

2.6.1 常用命令

  • codex：启动交互式终端界面。
  • codex resume：恢复历史会话。
  • codex exec "<prompt>"：以非交互方式运行，适合脚本和批处理。
  • codex mcp list：查看已配置的 MCP 服务。
  • codex features list：查看 feature flags。

2.6.2 常用 slash commands

在 Codex 的交互界面里，输入 / 可以看到很多内置命令。比较常用的有：

  • /model：切换模型。
  • /permissions：调整权限和审批策略。
  • /status：查看当前模型、权限、上下文使用情况等。
  • /review：让 Codex 审查当前工作区改动。
  • /compact：压缩上下文，适合长会话。
  • /mcp：查看当前可用的 MCP 工具。
  • /init：生成项目的 AGENTS.md 草稿。
  • /theme：切换终端主题。
  • /agent：查看或切换到某个子代理线程。

2.6.3 常用快捷操作

  • Ctrl + c 或 /exit：退出 Codex。
  • Ctrl + l：清空终端显示，但不会开始新会话。
  • Ctrl + g：调用外部编辑器来写长 prompt。
  • 空输入框时连按两次 Esc：编辑上一条用户消息；继续按 Esc 可以回到更早的节点，再按 Enter 从该点分叉。
  • 输入 @：模糊搜索并插入文件路径。
  • 输入 !：执行本地 shell 命令。
  • 当 Codex 正在工作时按 Enter：插入新的补充指令；按 Tab：把下一条要求排队到本轮之后。

2.7 配置AGENTS.md

AGENTS.md 可以理解为 Codex 的“长期说明书”。它会在会话开始时被读取，用来告诉 Codex：这个项目的背景是什么、有哪些规则、改代码时应该注意什么。

根据最新官方文档，Codex 会按层级读取这些文件：

  1. 全局层：~/.codex/AGENTS.md；如果同目录下有 AGENTS.override.md，则优先使用 override 文件。
  2. 项目层：从仓库根目录一路走到当前工作目录；每一层最多取一个说明文件，越靠近当前目录的说明优先级越高。
  3. 可选回退文件名：如果您在 config.toml 里设置了 project_doc_fallback_filenames，Codex 也会尝试这些备选文件名。

因此，最常见的做法是：

  • 在 ~/.codex/AGENTS.md 放个人通用偏好；
  • 在项目根目录 AGENTS.md 放项目规范；
  • 在某个子目录放更细的 AGENTS.md 或 AGENTS.override.md，只约束该子模块。

下面是一个更符合当前文档的全局 AGENTS.md 示例。注意：AGENTS.md 本身不需要 skill 那样的 YAML 元数据头。

AGENTS.md 全局示例（点击展开/收起） 
# ~/.codex/AGENTS.md

## Working agreements

- Prefer Pixi for environment management when possible.
- Ask before adding new runtime dependencies.
- Prefer reproducible pipelines over ad-hoc notebooks.
- Keep code changes small and easy to review.
- After editing code, propose the shortest useful validation command first.

## Bioinformatics defaults

- Prefer standard file formats: FASTQ, BAM/CRAM, VCF/BCF, GTF/GFF, BED, TSV/CSV.
- Preserve sample IDs exactly as provided.
- Avoid machine-specific absolute paths.
- Put tunable parameters into config files instead of hard-coding them.
- For heavy jobs, prefer batch systems such as SLURM instead of long local runs.

而项目级 AGENTS.md 更适合写这些信息：

  • 该项目的数据类型（bulk RNA-seq、scRNA-seq、ATAC-seq…）
  • 主要编程语言（Python、R、Nextflow、Snakemake…）
  • 目录结构（src/、data/、results/、notebooks/…）
  • 验证方式（例如运行哪个脚本、哪个测试命令）
  • 不应触碰的文件或目录

这些完全可以让 Codex 帮您先生成。您只需要在项目目录中打开 Codex，然后输入 /init，它就会为当前目录生成一个初稿。

如果您修改了 AGENTS.md，最稳妥的做法是开启一个新会话，这样 Codex 会重新读取最新的说明。

2.8 配置Skills

您可以把 skill 理解成“按需加载的工作流模板”或“可复用的任务说明包”。Skill和MCP的区别是，skill只会按需加载，这样一来就大大节省了token。

2.8.1 查找和安装 skill

如果您还不确定该装哪个 skill，最简单的做法是先搜索，再安装。常用方法有三种：

  • 直接让 Codex 使用 find-skills skill 帮您查找合适的 skill。
  • 在终端运行 npx skills find <query>，按关键词搜索。
  • 直接访问 https://skills.sh 浏览现成的 skill。

例如，您想找和代码审查有关的 skill，可以这样搜索：

npx skills find code review

找到合适的 skill 后，再安装它：

npx skills add <owner/repo@skill>

如果您希望安装到用户级，并跳过确认提示，也可以用：

npx skills add <owner/repo@skill> -g -y

这种方式很适合先复用社区里已有的工作流，再决定是否自己写一个新的 skill。

2.8.2 创建 skill

官方推荐先用内置的 skill 创建器：

$skill-creator

它会一步步询问：

  • 这个 skill 是干什么的；
  • 什么时候触发；
  • 只需要说明，还是还要配脚本。

2.8.3 Skill 怎么触发

Codex 可以用两种方式使用 skill：

  • 显式触发：在 CLI / IDE 中使用 /skills，或者输入 $ 来选择某个 skill。
  • 隐式触发：当用户任务和 skill 的 description 匹配时，Codex 会自动选择它。

所以 skill 的 description 要写得足够清楚，明确“什么时候该触发、什么时候不该触发”。

2.8.4 Skill 放在哪里

Codex 会从多个位置发现 skills。对普通用户最重要的是这三个：

  • 仓库内：.agents/skills/
  • 用户级：~/.agents/skills/
  • 系统级：/etc/codex/skills/

如果您在 Git 仓库里工作，Codex 会从当前目录一路往上扫描到仓库根目录的 .agents/skills/，因此 skill 既可以写在仓库根，也可以只写在某个子模块里。

2.9 Codex的深入配置

model = "gpt-5.4"
approval_policy = "on-request"
sandbox_mode = "workspace-write"
web_search = "cached"
personality = "pragmatic"
cli_auth_credentials_store = "auto"

[sandbox_workspace_write]
network_access = true

[tui]
notifications = true
alternate_screen = "auto"

[features]
shell_snapshot = true
unified_exec = true

上面几个选项的意思分别是：

  • approval_policy = "on-request"：让 Codex 在必要时主动请求授权。
  • sandbox_mode = "workspace-write"：允许修改当前工作区文件。
  • web_search = "cached"：启用官方内置网页搜索，并优先走缓存索引；需要最新内容时可改成 "live"。
  • personality = "pragmatic"：让回答更偏务实风格。
  • cli_auth_credentials_store = "auto"：优先用系统凭据存储，失败时再退回文件。
  • shell_snapshot：加快重复 shell 调用。
  • unified_exec：使用当前稳定的统一执行工具链。

另外，最新文档里还有几个很实用的点：

  • 项目级配置：除了 ~/.codex/config.toml 之外，您还可以在项目里放 .codex/config.toml。不过只有在 Codex 信任该项目时，它才会生效。
  • 配置优先级：命令行参数和 --config key=value 的优先级最高，其次是 profile，然后是项目级配置，最后才是用户级配置。
  • Profiles：可以在 config.toml 里定义 [profiles.<name>]，然后用 codex --profile <name> 切换。需要注意的是，profiles 目前仍偏实验性质，而且 IDE 扩展暂不支持。

例如：

[profiles.deep-review]
model = "gpt-5-pro"
model_reasoning_effort = "high"
approval_policy = "never"

使用时：

codex --profile deep-review

Codex 更新很快，建议优先查看官方开发者文档，而不是只参考旧版 GitHub 页面。比较常用的入口有：

2.10 添加MCP

MCP（Model Context Protocol）是一种让 AI 模型与外部工具、数据源进行安全、标准化交互的通用协议。简单来说，MCP 让 AI 拥有“插件系统”，并且可以统一、可控地访问数据库、API、文件系统、开发工具等资源。

根据最新官方文档，配置 MCP 有两种常见方式：

  1. 直接编辑 ~/.codex/config.toml；
  2. 使用 codex mcp 命令添加。

例如，如果您想快速添加 Context7，可以直接运行：

codex mcp add context7 -- npx -y @upstash/context7-mcp

如果您需要更细的控制，比如限制工具、设置 header、调整超时，再回到 ~/.codex/config.toml 手动修改会更方便。

下面是配置文件中的基本写法。

STDIO服务：

# The top-level table name must be `mcp_servers`
# The sub-table name (`server-name` in this example) can be anything you would like.
[mcp_servers.server_name]
command = "npx"
# Optional
args = ["-y", "mcp-server"]
# Optional: set environment variables for the MCP server.
env = { "API_KEY" = "value" }
# Optional: forward additional variables from your current shell.
env_vars = ["ANOTHER_ENV_VAR"]
# Optional: working directory of the MCP server.
cwd = "/path/to/project"
# Optional: startup timeout and tool timeout.
startup_timeout_sec = 20
tool_timeout_sec = 60

StreamableHTTP服务：

[mcp_servers.figma]
url = "https://mcp.figma.com/mcp"
# Optional environment variable containing a bearer token to use for auth
bearer_token_env_var = "ENV_VAR"
# Optional map of headers with hard-coded values.
http_headers = { "HEADER_NAME" = "HEADER_VALUE" }
# Optional map of headers whose values will be replaced with the environment variable.
env_http_headers = { "HEADER_NAME" = "ENV_VAR" }

部署一个MCP服务通常有STDIO或StreamableHTTP两种方式。STDIO需要本地安装Node.js或Python环境，而StreamableHTTP通常不需要本地运行环境，但需要稳定的网络连接。对于纯托管服务，优先使用StreamableHTTP会更省心；而像 grok-tavily、ace-tool、context-mode 这类需要本地启动的工具，则通常要使用STDIO方式。

2.10.1 推荐的MCP服务

下面是我目前常用且推荐的一些MCP服务。它们各有分工，不必一次性全装；先装2-3个最常用的即可。

  • Tavily：轻量级联网搜索 MCP，适合“快速查一下”“找一个网页或官方链接”这类任务。它是托管的 StreamableHTTP 服务，配置简单，响应通常也比较快。
  • Grok-tavily（GrokSearch）：参考 GuDaStudio/GrokSearch 的 grok-with-tavily 分支。它采用双引擎设计：Grok 负责 AI 驱动的实时搜索，Tavily 负责网页抓取与站点映射，必要时还可以配合 Firecrawl 兜底。因此它比单独的 Tavily 更适合“先搜索、再抓取网页、再继续追溯来源”的复杂任务。不过它属于 STDIO MCP，需要本地安装 uv。
  • Context7：用于查询最新官方文档。AI 写代码时经常因为训练数据过旧而给出过时接口，而 Context7 可以直接补上“最新文档”这块短板。
  • ace-tool：用于语义级代码库检索。它比普通关键词搜索更擅长回答“这个功能由哪些文件负责”“某个流程大概在哪实现”这类问题。不过它通常需要单独的 relay 地址和 token；如果您暂时没有，可以先跳过这一项。
  • context-mode：用于处理长日志、测试输出、命令结果和大段网页内容。它的重点不是“多一个工具”，而是“避免一次把几万字输出塞进上下文”，因此在分析构建报错、测试失败、依赖树时很实用。

下面是我目前使用的这组 MCP 的 Codex 配置示例，您可以复制到~/.codex/config.toml中。注意把...替换成您自己的 token / API key，不要把真实密钥提交到公开仓库。

[mcp_servers.context7]
url = "https://mcp.context7.com/mcp"
http_headers = { "CONTEXT7_API_KEY" = "..." }

[mcp_servers."ace-tool"]
command = "npx"
args = [
  "-y",
  "ace-tool-rs",
  "--base-url",
  "https://acemcp.heroman.wtf/relay/",
  "--token",
  "..."
]

[mcp_servers."grok-tavily"]
command = "uvx"
args = [
  "--from",
  "git+https://github.com/GuDaStudio/GrokSearch@grok-with-tavily",
  "grok-search"
]
env = {
  "GROK_API_URL" = "https://your-openai-compatible-grok-endpoint.example.com/v1",
  "GROK_API_KEY" = "...",
  "TAVILY_API_KEY" = "...",
  "FIRECRAWL_API_KEY" = "...",
  "GROK_MODEL" = "grok-4.20-beta"
}

[mcp_servers.tavily]
url = "https://mcp.tavily.com/mcp/?tavilyApiKey=..."

[mcp_servers."context-mode"]
command = "context-mode"

如果uvx在启动 grok-tavily 时遇到证书问题，可以在 args 最前面加上 --native-tls。如果您使用的是 GuDa 提供的聚合服务，也可以参考上面链接中的说明，改用 GUDA_API_KEY 做统一配置。

另外，Tavily 与 Grok-tavily 的功能有一定重叠：前者更轻、更简单，后者更适合需要“搜索 + 抓取 + 追溯来源”的复杂任务。

2.10.2 MCP的使用技巧

  • 大部分MCP是自动触发的，AI会根据任务的需要自动调用相应的MCP服务。
  • 有时候需要手动触发MCP服务，比如在您需要AI获取最新文档或联网搜索信息时，可以明确告诉AI使用相应的MCP服务。例如，您可以说 Use grok-tavily for search and context7 for docs，或者 Use tavily to find the official page first。
  • Tavily 与 Grok-tavily 有一定功能重叠：前者更轻量，后者更强大。新手可以先装 Tavily；等您确实需要更复杂的联网搜索和网页抓取能力时，再加上 Grok-tavily。
  • 若您加载了较多的MCP服务，可能导致Codex在启动时出现略微的延迟，因此建议只加载必要的MCP服务。还有另一种方法是，如果您使用服务器，也可以通过pm2等进程管理工具来预先启动MCP服务，这样Codex在启动时就不需要等待MCP服务启动，从而减少延迟。

2.11 Codex的使用技巧

很多人在使用AI写代码时，总是感觉AI生成的代码不符合预期，或者无法解决复杂的问题。下面是一些使用Codex的技巧，能帮助您更好地利用AI写代码。

  • 明确任务：在与Codex交互时，尽量明确地描述您的需求和预期结果（如生成某种图或某表格、保存到哪），并提供背景信息（如使用的包、方法、参数、参考网页等）。下面是一个例子： I have a dataframe df with columns gene, condition, and expression. I want to create a boxplot showing the distribution of expression for each condition, grouped by gene. Please use seaborn for plotting and save the figure as boxplot.png. 这个例子中包含的元素有：
    • 输入对象是df，df中有三列，分别是gene、condition和expression。
    • 需要生成的图是箱线图（boxplot），展示expression在不同condition下的分布情况，并且按gene进行分组。
    • 使用的绘图库是seaborn。
    • 生成的图保存为boxplot.png文件。
  • 使用英语：目前的证据表明，AI在处理英语时的表现通常优于其他语言，因此建议您尽量使用英语与Codex进行交互。
  • 分步进行：对于复杂的任务，建议将任务拆分为多个小步骤，逐步与Codex进行交互。以RNA-seq数据分析为例，您可以先让Codex帮您进行数据预处理，当您对结果满意后，就可以结束当前会话，使用Git存档（见 Chapter 7 ），然后开启一个新的会话，再继续进行差异分析。
CautionCaution

虽然现代大语言模型（如Claude、GPT-5等）拥有很长的上下文窗口（从数万到数百万tokens），但这并不意味着模型能够对所有上下文信息保持同等的注意力。研究表明，当上下文较长时，模型的注意力会分散，可能会遗漏中间部分的关键信息（“lost in the middle”现象），并且会开始编造不存在函数/参数。Chroma Context Rot测试表明，仅仅在达到50%的上下文窗口时，GPT系列模型的准确率就能下降20-60%。因此，即使技术上可以在一个会话中处理大量信息，分步进行、适时开启新会话仍然是推荐的最佳实践，这样可以确保AI对当前任务保持高质量的注意力和理解。

  • 适时提醒AI搜索最新文档：如果您将要使用的包比较小众，或者AI生成的代码在2-3次迭代后仍然错误，可以适时提醒AI去搜索最新的官方文档，以获取正确的用法。例如使用我们下一章介绍的tavily和context7工具。
  • 适时结束并开启新会话：每个不同的任务（如质量控制、差异分析等）应当在新的会话中进行，以避免上下文混淆，并且避免浪费上下文窗口。
  • 适时压缩上下文：当上下文过长时，而当前的任务还没有完成时，可以使用/compact来压缩Codex的上下文，从而腾出更多的空间。Codex的左下角会显示当前上下文的使用情况。
TipTip

您给AI提供的信息越多，AI就越能理解您的意图，它为了完成任务而猜测的成分就越少，生成的代码也就越符合您的预期！