codex 使用指南

AI 工具的使用大势所趋，充分地利用能有效提升学习的效率。

安装 codex。

1
npm install -g @openai/codex

然后配置基本的模型，在 ~/.codex/config.toml。

1
2
3
4
5
6
7
8
9
10
11
12
model_provider = "codex"
model = "gpt-5.4"
model_reasoning_effort = "high"
disable_response_storage = true
approvals_reviewer = "user"


[model_providers.codex]
name = "codex"
base_url = "<url>"
wire_api = "responses"
requires_openai_auth = true

uvx 安装。

1
curl -LsSf https://astral.sh/uv/install.sh | sh

1 基本用法

1
2
codex [OPTIONS] [PROMPT]
codex [OPTIONS] <COMMAND> [ARGS]

2 子命令

  • exec / e: 非交互执行任务，适合脚本化调用
  • review: 非交互代码审查
  • login: 登录管理
  • logout: 删除本地登录凭据
  • mcp: 管理外部 MCP 服务器
  • mcp-server: 把 Codex 作为 MCP server 启动，走 stdio
  • app-server: 实验功能，运行 app server 或相关工具
  • completion: 生成 shell 自动补全脚本
  • sandbox: 在 Codex 提供的沙箱里运行命令
  • debug: 调试工具
  • apply / a: 把最近一次 agent 生成的 diff 应用到本地 git 工作区
  • resume: 恢复之前的交互会话，默认弹选择器；–last 继续最近一次
  • fork: 基于之前的会话分叉一个新会话，默认弹选择器；–last 分叉最近一次
  • cloud: 实验功能，浏览 Codex Cloud 任务并把改动应用到本地
  • exec-server: 实验功能，运行独立的 exec-server
  • features: 查看 feature flags
  • help: 查看帮助

3 顶层选项

  • -c, –config <key=value>: 覆盖配置项，等价于临时改 ~/.codex/config.toml
    • 例子: 
      1
      2
      codex -c model=\"o3\"
      codex -c 'sandbox_permissions=[\"disk-full-read-access\"]'
  • –enable : 启用某个 feature，可重复写多个
  • –disable : 禁用某个 feature，可重复写多个
  • –remote : 连接远程 app server 的 websocket 地址
    • 例子: 
      1
      codex --remote ws://127.0.0.1:3000
  • –remote-auth-token-env : 指定一个环境变量名，从里面读取远程连接用的 bearer token
  • -i, –image …: 给初始 prompt 附加图片，可传多个
    • 例子： 
      1
      codex -i a.png -i b.jpg "分析这两张图"
  • -m, –model : 指定模型
    • 例子： 
      1
      codex -m gpt-5.4
  • –oss: 使用本地开源模型提供方，相当于设置 model_provider=oss，会检查本地 LM Studio 或 Ollama
  • –local-provider : 指定本地 provider：lmstudio 或 ollama
  • -p, –profile : 使用 config.toml 里的某个 profile
  • -s, –sandbox : 设置命令执行沙箱模式
    • 可选值: 
      1
      2
      3
      read-only：只读
      workspace-write：可写当前工作区
      danger-full-access：完全访问
  • -a, –ask-for-approval : 设置什么时候需要人工批准
    • 可选值: 
      1
      2
      3
      4
      untrusted：只有“可信命令”直接执行，其他都先问你
      on-failure：已弃用；先执行，失败后再请求升级权限
      on-request：模型自行判断何时请求批准
      never：永不请求批准，失败直接返回给模型
  • –full-auto: 便捷模式，等价于 -a on-request --sandbox workspace-write
  • –dangerously-bypass-approvals-and-sandbox: 跳过审批并关闭沙箱，直接执行。
  • -C, –cd <DIR>: 指定工作目录
    • 例子: codex -C /path/to/project
  • –search: 开启联网搜索能力，模型可直接使用 web_search 工具
  • –add-dir <DIR>: 给当前主工作区之外，再额外增加可写目录
  • –no-alt-screen: 关闭备用屏幕模式，保留终端滚动历史。像 zellij/tmux 这类场景里比较有用
  • -h, –help: 查看帮助
  • -V, –version: 查看版本

4 codex 快捷设置

  • /permissions：改 Codex 的权限策略，比如自动执行、只读、需要审批等。
  • /ide：把当前 IDE 的打开文件、选区、编辑器上下文带进下一条对话。
  • /keymap：查看或修改 TUI 快捷键绑定，并可保存到配置里。
  • /vim：开关 Vim 编辑模式。
  • /sandbox-add-read-dir：给沙箱额外添加一个可读目录。仅 Windows 提供。
  • /agent：切换当前活动的 agent 线程，查看或继续子 agent 的工作。
  • /apps：浏览可连接的 apps/connectors，并把它们插入当前提示词。
  • /plugins：浏览、安装、管理插件。
  • /hooks：查看和管理生命周期 hooks。
  • /clear：清空终端显示并开始一段新的聊天。
  • /archive：归档当前会话并退出 Codex。
  • /compact：把当前长对话压缩总结，节省上下文 token。
  • /copy：复制最近一条已完成的回答。
  • /diff：显示当前工作区的 Git diff，包括未跟踪文件。
  • /exit：退出 CLI，和 /quit 基本等价。
  • /experimental：开关实验功能。
  • /approve：对最近一次被自动审查拒绝的动作，批准重试一次。
  • /memories：配置记忆功能，决定是否读取或生成 memories。
  • /skills：浏览并启用技能，让下一步按某个 skill 的流程工作。
  • /feedback：提交反馈，并可附带日志。
  • /init：在当前目录生成 AGENTS.md 模板。
  • /logout：退出当前 Codex 账号登录状态。
  • /mcp：查看已配置的 MCP 工具或服务器状态。
  • /mention：把文件或目录附加到当前对话，提示 Codex 优先看它们。
  • /model：切换当前使用的模型；某些环境还能同时选 reasoning effort。
  • /fast：开关 Fast 服务层。只在当前模型支持时显示。
  • /plan：切到 plan mode，先做规划再执行。
  • /goal：设置、查看、暂停、恢复或清除一个持续目标。
  • /personality：切换回答风格，比如更简洁、更务实、更友好。仅支持时显示。
  • /ps：查看实验性的后台终端任务及最近输出。
  • /stop：停止当前会话启动的后台终端任务。
  • /fork：把当前对话分叉成一个新线程，方便尝试另一条思路。
  • /side：开一个临时的旁支对话，不打乱主线程。
  • /btw：和 /side 同义，也是临时旁支对话。
  • /raw：切换原始滚动输出模式，方便复制和查看长终端文本。
  • /resume：从已保存的会话列表里恢复一个旧会话。
  • /new：在同一个 CLI 会话里开一段全新的对话。
  • /quit：退出 CLI，和 /exit 基本等价。
  • /review：让 Codex 审查当前工作区改动。
  • /status：显示当前会话状态，比如模型、权限、token 使用、上下文容量等。
  • /debug-config：打印配置来源和优先级，用来排查配置为什么生效或没生效。
  • /statusline：配置底部状态栏显示哪些项目、顺序如何。
  • /title：配置终端窗口标题显示哪些信息。
  • /theme：切换终端语法高亮主题。

5 MCP

MCP 全称 Model Context Protocol。它是一个把模型连接到“外部工具和上下文”的协议，让 Codex 不只会聊天，还能调用第三方能力，比如查文档、连 Figma、控制浏览器、读Sentry、做 GitHub 操作。Codex 在 CLI 和 IDE 扩展里都支持 MCP。

5.1 MCP 配置

全局配置。

1
~/.codex/config.toml

项目级配置。

1
.codex/config.toml

通过 config.toml 配置的 MCP server 有三种类型。

  • STDIO 类型：

    • command：启动命令，必填
    • args：参数
    • env：直接设置环境变量
    • env_vars：把本机环境变量透传进去
    • cwd：工作目录

  • HTTP 类型：

    • url：服务地址，必填
    • bearer_token_env_var：认证 token 来自哪个环境变量
    • http_headers / env_http_headers：附加请求头

使用命令。

1
codex mcp add <名称> ...

5.1.1 MCP 服务器

基于 typescript 的服务器可以直接使用 npx。

1
npx -y @modelcontextprotocol/server-memory

基于 python 的服务器可以直接使用 uvx。

1
2
3
4
5
6
# Using uvx
uvx mcp-server-git

# Using pip
pip install mcp-server-git
python -m mcp_server_git

5.1.2 MCP 配置实例

假设我们接入一个叫 context7 的 MCP server。

1
2
3
# codex mcp add context7：给 Codex 新增一个名叫 context7 的 MCP server
# -- 后面表示启动这个 server 要运行的命令
codex mcp add context7 -- npx -y @upstash/context7-mcp

或者在 ~/.codex/config.toml 加入。

1
2
3
[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]

观察，添加 MCP server 前后。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
/mcp

🔌  MCP Tools

  • No MCP servers configured.
    See the MCP docs to configure them.

/mcp

🔌  MCP Tools

  • No MCP tools available.

  • context7
    • Auth: Unsupported
    • Tools: (none)

发现貌似启动不了，这里改成 HTTP 类型。

1
2
[mcp_servers.context7]
url = "https://mcp.context7.com/mcp"

结果如下。

1
2
3
4
5
6
7
/mcp

🔌  MCP Tools

  • context7
    • Auth: Not logged in
    • Tools: query-docs, resolve-library-id

怎么禁用对应的 MCP?

在对应的 config.toml 当中设置成为 enabled = false。

怎么删除对应的 MCP?

1
codex mcp remove context7

6 常用模板

6.1 优化类

记录上下文。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
每次在当前工作目录执行任务时，都同步维护 `process.md`：

1. 如果 `process.md` 不存在，则创建它。
2. 如果已存在，则在末尾追加新记录，不覆盖旧内容。
3. 记录本次用户提示词原文。
4. 记录本次工作的过程摘要，包括：
    - 我检查了哪些文件/命令
    - 我做了什么判断
    - 我修改了哪些内容
    - 我验证了什么结果
    - 如果没完成，记录阻塞原因
5. 每次记录都带上时间戳和任务标题。
6. 记录应简洁、可追溯，不要求输出完整内部推理。

再固定一个格式：

## 2026-06-16 14:30 Task: 修复 IMX6ULL 启动脚本

### User Prompt
...

### Actions
- ...
- ...

### Reasoning Summary
- ...
- ...

### Changes
- ...
- ...

### Verification
- ...

6.2 科研类

6.3 工程类

功能开发。

1
2
3
4
5
6
7
8
9
在 [模块路径] 添加 [功能名称] 功能

要求：
- 使用 [技术/库]
- 兼容 [现有系统]
- 包含 [边界处理]
- 返回 [响应格式]

参考：[现有类似功能路径]

Bug 修复。

1
2
3
4
5
6
7
8
9
10
问题描述：[Bug 表现]

触发条件：[什么情况下出现]

错误信息：
[完整错误堆栈]

期望行为：[正确结果应该是什么]

请分析原因并修复，不要影响其他功能。

快速问题分析。

1
2
3
4
5
6
7
8
9
10
11
12
13
# 提供完整错误
运行测试时出现错误：

AssertionError: Expected status 200 but got 500
  at test_login.py:45
  in test_successful_login
  Full traceback:
  ...

分析原因并修复

# 截图辅助
附加错误截图，Codex 可以直接查看

代码审查。

1
2
3
4
5
/review [范围] for [重点]

# 示例
/review src/auth/ for security issues
/review HEAD~5..HEAD for performance regressions

References

  1. codex 最佳实践: https://www.runoob.com/codex/codex-prompting.html
  2. codex 快捷设置: https://developers.openai.com/codex/cli/slash-commands
  3. codex MCP 配置: https://developers.openai.com/codex/mcp