Codex 使用指南

01Codex 是什么

一句话：把"要做的事"说清楚，剩下的读代码、写代码、跑测试、看报错，它自己循环完成，然后请你验收。

它和代码补全不一样。补全工具猜你下一行想写什么；Codex 接受的是一个任务——"把支付回调的重复逻辑抽出来并补测试"——并自己决定读哪些文件、改哪些地方、跑什么命令来证明改对了。每一次改动都留在 Git 里，以 diff 的形式等你确认。

02快速开始

从零到第一条任务，五步。

1. 安装

   通过 npm 全局安装命令行版本，或者安装桌面应用（codex app 在缺失时会打开安装程序）。

   shell复制

   npm install -g @openai/codex

2. 登录

   用 codex login 按提示完成授权，凭据保存在本机 Codex 目录下；退出用 codex logout。

   shell复制

   codex login

3. 在项目里启动

   切到仓库目录再启动，Codex 就以它为工作根目录。也可以用 -C 指定目录、用 --add-dir 额外开放可写目录。

   shell复制

   # 进入仓库后启动（macOS / Linux）
   cd ~/code/my-project
   codex
   
   # 或一步指定目录
   codex -C ~/code/my-project
   
   # Windows 下把路径换成 D:\my-project

4. 说清第一个目标

   上来先让它做一件小事：摸清仓库、跑通测试、解释一处逻辑。这比一上来丢一个大需求更容易建立信任。

   prompt复制

   先浏览这个仓库的结构，告诉我它是做什么的、怎么跑测试，
   然后跑一遍测试并把失败项摘要给我。

   也可以把任务直接写在启动命令后面：codex "把 README 里的安装步骤按当前脚本更新一遍"。

5. 审阅并确认

   需要执行敏感命令时它会先征求同意；改完代码它会给出 diff。你逐处看过、确认无误，再决定是否提交。

   shell复制

   # 在仓库里查看改动
   git diff
   
   # 满意就提交
   git add -p
   git commit -m "refactor: 抽取支付回调重复逻辑"

03一次典型的协作循环

理解这五步，就知道什么时候该说话、什么时候该放手。

• 随时可以打断。它在跑的时候你也能补一句"先别改测试""顺便把日志级别统一一下"，它会带着新要求继续。
• 一轮别塞太多事。大需求拆成几步，每步都能验证，出问题时定位范围小得多。
• 要它拿证据说话。让它跑测试、跑构建、复现原始报错，而不是只说"已修复"。
• 不满意就直说。指出具体哪一处不对、期望是什么样，比"再优化下"有效得多。

04权限与沙箱：它能动到哪一步

两个开关决定"它能碰什么"和"什么时候必须问你"。默认组合是能在工作区里自由干活，出圈要打招呼。

沙箱模式 -s, --sandbox

审批策略 -a, --ask-for-approval

想少被打断，从这三个方向调

05命令速查

以下命令与说明取自本机 codex-cli 0.162.1 的帮助输出。输入关键词可以过滤。

06会话内的斜杠指令

进入交互式会话后，以 / 开头的短指令用来控制会话本身，而不是干活的指令。直接敲一个 / 就能看到当前版本支持的完整列表，下面是高频项。

07非交互模式与自动化

codex exec 把 Codex 当成一条普通命令来用：给任务、等结果、拿输出。这是把它接进脚本、CI、定时任务的方式。

# 一条命令跑完一个任务
codex exec "为 src/utils/date.ts 里的公开函数补齐注释和单测，跑通测试"

# 从标准输入接手任务描述
cat spec.md | codex exec -

# 机器可读输出，并把最终消息写进文件
codex exec --json -o result.txt "跑测试并总结失败原因"

Windows PowerShell 里把 cat spec.md 换成 Get-Content spec.md 即可，管道后的命令不变。

常用配套选项

放进流水线

- name: 自动审查本次改动
  run: |
    codex exec \
      --skip-git-repo-check \
      --color never \
      -s read-only \
      -o review.md \
      "审查本次改动，按严重程度列出问题，不要改动文件"

- name: 与基线分支比对审查
  run: codex review --base main

08配置与扩展：让它更懂你的项目

大部分不确定来自"它不知道你的规矩"。把规矩沉淀到下面这些地方，就不用每次在对话里重复交代。

一个 config.toml 的样子

# ~/.codex/config.toml
model = "你的账号可用的模型"
model_reasoning_effort = "high"
approval_policy = "on-request"
sandbox_mode = "workspace-write"

# 接入一个 MCP 服务器
[mcp_servers.example]
command = "npx"
args = ["-y", "some-mcp-server"]

09怎么提问更有效

同一件事，说法不同返工次数能差好几倍。把这几样说清楚就够了：做什么、在哪做、别碰什么、怎么算完成。

几个立刻能用上的习惯

• 大任务先要计划。"先别改代码，列出你打算改哪些文件、怎么验证，我确认后再动手。"
• 让它分清确定与猜测。"不确定的地方单独列出来问我，不要替我假设。"
• 要证据。"跑一遍测试并把输出贴出来"，比"确保没问题"可靠得多。
• 给它上下文。相关文件、接口文档、线上日志、界面截图都可以直接给它（命令行用 -i 附图片，或用管道把文档喂进去）。
• 长会话及时收口。任务切换时开新会话，或先 /compact 再继续，避免旧上下文干扰当前判断。
• 不满意就具体化。"第 2 个测试的断言改错了，应该判断 401 而不是抛异常"远比"再改改"有效。

10实践原则

11实战连载：九篇，按顺序读

指南把概念、命令和权限边界讲清楚；《Codex 教程》九篇记录的是同一套工具在真实项目里的用法——发布、迁机、收信、值守。前三篇打好基本盘，后六篇各解决一类具体问题。

12常见问题

13资料与版本说明

codex --version        # 版本
codex --help           # 子命令与全局参数
codex exec --help      # 非交互模式的全部选项
codex doctor           # 环境体检