OpenAI Codex CLI（v0.116+）是一个开源 AI 编程代理，可直接在终端中读取、修改并运行代码。参见官方文档。
$ npm install -g @openai/codex
$ npm install -g @openai/codex@latest # 升级$ brew install codex$ codex # 启动交互式 TUI
$ codex "Explain this codebase" # 带初始提示首次运行时会提示你通过 ChatGPT 账号或 API key 登录。
# Zsh - 添加到 ~/.zshrc
$ eval "$(codex completion zsh)"
# Bash - 添加到 ~/.bashrc
$ eval "$(codex completion bash)"
# Fish
$ codex completion fish | source| 平台 | 状态 |
|---|---|
| macOS | 稳定 |
| Linux | 稳定 |
| Windows (WSL) | 推荐 |
| Windows（原生） | 实验性 |
$ codex login # ChatGPT OAuth
$ codex login --device-auth # 设备码登录流程从环境变量管道传入 API key
$ printenv OPENAI_API_KEY | codex login --with-api-key
$ codex login status # 检查登录状态
$ codex logout # 移除凭据| 命令 | 别名 | 状态 | 说明 |
|---|---|---|---|
codex |
稳定 | 启动交互式 TUI | |
codex exec |
codex e |
稳定 | 以非交互模式运行（脚本化） |
codex review |
稳定 | 非交互代码审查 | |
codex resume |
稳定 | 恢复历史会话 | |
codex fork |
稳定 | 分叉会话到新线程 | |
codex apply |
codex a |
稳定 | 将 Cloud 任务 diff 应用到本地 |
codex login |
稳定 | 登录 Codex | |
codex logout |
稳定 | 删除已保存凭据 | |
codex completion |
稳定 | 生成 shell 自动补全 | |
codex features |
稳定 | 管理特性开关 | |
codex app |
稳定 | 启动 Codex 桌面应用 | |
codex mcp |
实验性 | 管理 MCP 服务器 | |
codex mcp-server |
实验性 | 将 Codex 作为 MCP 服务器运行 | |
codex cloud |
实验性 | 浏览并执行 Cloud 任务 | |
codex sandbox |
实验性 | 在沙箱中运行命令 | |
codex debug |
实验性 | 调试工具 |
# 基础非交互运行
$ codex exec "Fix the race condition"
$ codex e "Add unit tests for utils"从 stdin 读取提示词
$ echo "Explain main.go" | codex exec -Prompt-plus-stdin（0.118+）：既传入管道数据，也传入提示词
$ cat error.log | codex exec "Diagnose this log" -输出选项
$ codex exec --json "Audit security"
$ codex exec -o last.txt "Summarize"恢复之前的 exec 会话
$ codex exec resume --last "Fix the bugs"
$ codex exec resume <SESSION_ID> "Implement"| 参数 | 取值 | 说明 |
|---|---|---|
-m, --model |
string | 覆盖模型（例如 gpt-5.4） |
-s, --sandbox |
见下文 | 沙箱策略 |
-a, --ask-for-approval |
见下文 | 审批策略 |
--full-auto |
flag | workspace-write + on-request |
--yolo |
flag | 跳过全部审批和沙箱 |
-i, --image |
path | 给初始提示附加图片 |
-c, --config |
key=val |
覆盖配置项 |
-C, --cd |
path | Agent 工作目录 |
-p, --profile |
string | 配置档名称 |
--search |
flag | 启用实时网页搜索 |
--add-dir |
path | 追加可写目录权限 |
--oss |
flag | 使用本地 OSS provider |
--local-provider |
lmstudio/ollama | 指定 OSS provider |
--enable |
feature | 启用特性开关 |
--disable |
feature | 禁用特性开关 |
--no-alt-screen |
flag | 内联 TUI 模式（禁用 alt screen） |
--remote |
ws://host:port | 连接远程 app server |
--remote-auth-token-env |
ENV_VAR | 远程 WS 的 Bearer Token 环境变量 |
-V, --version |
输出版本 | |
-h, --help |
输出帮助 |
# 指定模型
$ codex -m gpt-5.4 "Refactor the auth module"
# 自动模式（低摩擦）
$ codex --full-auto "Run tests and fix failures"
# 附加截图
$ codex -i mockup.png "Implement this UI"
# 命令行临时覆盖配置
$ codex -c model="gpt-5.4-mini" "Quick scan"
# 实时网页搜索
$ codex --search "Find the latest async syntax"
# 设置工作目录
$ codex -C ~/projects/api "Review this codebase"| 模式 | 说明 |
|---|---|
read-only |
仅查看，不经批准不修改 |
workspace-write |
可改工作区并运行本地命令 |
danger-full-access |
无限制（仅建议在强化隔离环境中使用） |
| 策略 | 说明 |
|---|---|
untrusted |
所有非可信命令执行前都询问 |
on-request |
超出沙箱边界时询问 |
never |
从不询问；所有命令自动执行 |
| 预设 | 等价设置 |
|---|---|
--full-auto |
workspace-write + on-request |
--yolo |
无沙箱 + 无审批 |
可在 TUI 中使用 /permissions 在会话中途切换模式。
| 命令 | 说明 |
|---|---|
/model |
切换模型/推理强度 |
/fast |
切换 GPT-5.4 Fast 模式 |
/permissions |
调整审批模式 |
/personality |
设置响应风格 |
/plan |
进入计划模式 |
/status |
显示模型、tokens、配置 |
/compact |
压缩总结以释放上下文 |
/clear |
清空聊天并重新开始 |
/new |
新建聊天，保留 CLI 会话 |
/fork |
分叉当前会话 |
/resume |
恢复已保存会话 |
/exit / /quit |
退出 CLI |
| 命令 | 说明 |
|---|---|
/review |
启动代码审查 |
/diff |
显示 Git diff |
/copy |
复制最新 Codex 输出 |
/mention |
向会话附加文件 |
/init |
生成 AGENTS.md 模板 |
| 命令 | 说明 |
|---|---|
/agent |
切换当前 agent 线程 |
/mcp |
列出 MCP 工具 |
/apps |
浏览连接器应用 |
/experimental |
切换实验性特性 |
/statusline |
配置 TUI 底栏 |
/ps |
显示后台终端 |
/sandbox-add-read-dir |
添加可读目录（Windows） |
/feedback |
向维护者发送日志 |
/plugins |
浏览并管理插件 |
/title |
为当前会话设置终端标题 |
/debug-config |
输出配置诊断信息 |
/logout |
退出 Codex 登录 |
| 模型 | 速度 | 适用场景 |
|---|---|---|
gpt-5.4 |
★★★ | 默认：编码 + 推理 + 工作流 |
gpt-5.4-mini |
★★★★★ | 子代理、轻量任务、更高配额 |
gpt-5.3-codex |
★★★★ | 复杂软件工程任务 |
gpt-5.3-codex-spark |
★★★★★ | 近实时迭代（仅 Pro） |
$ codex -m gpt-5.4 "Your prompt"
$ codex -m gpt-5.4-mini "Quick task"
$ codex --oss # local Ollama / LM Studio
# 会话中途可在 TUI 输入 /model# ~/.codex/config.toml
# 模型设置
model = "gpt-5.4"
model_provider = "openai"
model_reasoning_effort = "medium" # low | medium | high
# 沙箱与审批
sandbox_mode = "workspace-write"
approval_policy = "on-request"
# 网页搜索：cached | live | disabled
web_search = "cached"
# 审查模型覆盖
review_model = "gpt-5.4"
# TUI 外观
[tui]
theme = "dark"
alternate_screen = true
# 配置档示例
[profile.ci]
model = "gpt-5.4-mini"
approval_policy = "never"
sandbox_mode = "workspace-write"使用 -p ci 启用该配置档。
$ codex features list
$ codex features enable unified_exec
$ codex features disable shell_snapshot
# 仅当前会话生效（不持久化）
$ codex --enable unified_exec
$ codex --disable shell_snapshot| 文件 | 用途 |
|---|---|
~/.codex/config.toml |
全局默认配置 |
~/.codex/AGENTS.md |
个人指令 |
~/.agents/skills/ |
个人技能 |
.agents/skills/ |
仓库级技能 |
AGENTS.md |
仓库指令 |
可随代码一同提交的仓库级持久指令：
## 构建与测试命令
- 安装：`npm install`
- 测试：`npm test`
- Lint：`npm run lint`
## 约定
- TypeScript 严格模式
- 日志中不得包含 PII
- 所有路由都需鉴权中间件
## 审查准则
- 标记未处理的 Promise rejection建议添加规则的场景：
- Agent 重复犯错
- PR 审查反馈反复出现
- 在 GitHub 使用
@codex add to AGENTS.md标签
可复用工作流可打包为 SKILL.md：
my-skill/
SKILL.md ← 元数据 + 指令
scripts/ ← 可选辅助脚本
references/ ← 可选文档
assets/ ← 可选模板
SKILL.md 示例：
---
name: commit
description: 按语义分组暂存并提交变更。
---
1. 按逻辑分组暂存文件。
2. 分组顺序：feat → test → docs → chore
3. 编写简洁的提交信息。# 添加 stdio 服务器
$ codex mcp add myserver -- npx my-mcp-server
# 添加 HTTP 服务器
$ codex mcp add myserver \
--url https://api.example.com/mcp
# 带认证 token
$ codex mcp add myserver \
--url https://api.example.com/mcp \
--bearer-token-env-var MY_TOKEN
# 列出 / 删除
$ codex mcp list
$ codex mcp remove myserver
# 将 Codex 自身作为 MCP 服务器运行
$ codex mcp-server$ codex resume # 会话选择器
$ codex resume --last # 最近一次会话
$ codex resume --all # 跨目录查找
$ codex resume <ID> "Continue fixing tests"会话保存在 ~/.codex/sessions/
$ codex fork # 从选择器分叉
$ codex fork --last # 分叉最近一次
$ codex fork <SESSION_ID> "New direction"分叉会保留原始会话记录，并开启一条新分支。
# 单张图片
$ codex -i screenshot.png "Fix this error"
# 多张图片
$ codex --image img1.png,img2.jpg "Compare"
# 或将图片直接拖入 TUI 输入框支持 PNG、JPEG 等常见格式。
# 浏览 Cloud 环境
$ codex cloud
# 提交 Cloud 任务
$ codex cloud exec --env <ENV_ID> "Fix bug"
# 多次尝试（best-of-N）
$ codex cloud exec --env <ENV_ID> \
--attempts 3 "Write failing tests"
# 列出最近任务
$ codex cloud list
# 查看任务状态
$ codex cloud status <TASK_ID>
# 查看任务 diff
$ codex cloud diff <TASK_ID>
# 将 diff 应用到本地工作树
$ codex apply <TASK_ID># 在 PR 评论中触发代码审查：
@codex review
# 自定义关注点：
@codex review for security regressions
# 基于 PR 上下文委派任意任务：
@codex fix the CI failures
@codex add tests for the new endpoint在 Codex Settings → Code review → 你的仓库中启用；开启 Automatic reviews 后，可自动审查每个新 PR。
将噪声任务分发给并行代理，以避免上下文污染和上下文老化：
codex "Review this branch with parallel agents.
Spawn one for security risks, one for test gaps,
and one for maintainability. Wait for all three,
then summarize findings with file references."
- 适用于：探索、测试、分诊、日志分析
- 避免并行执行大量写入任务（易冲突）
- 每个子代理都会额外消耗 tokens
子代理模型建议：
| 角色 | 模型 | 推理强度 |
|---|---|---|
| 主协调代理 | gpt-5.4 |
medium |
| 快速探索代理 | gpt-5.4-mini |
low |
| 安全/逻辑审查代理 | gpt-5.4 |
high |
| 等级 | 适用场景 |
|---|---|
high |
复杂逻辑、安全审计 |
medium |
通用任务（默认） |
low |
简单任务或对速度敏感的任务 |
可在 config.toml 中设置：
model_reasoning_effort = "medium"也可命令行临时指定：-c model_reasoning_effort="high"
- Codex 官方文档 (developers.openai.com)
- Codex CLI GitHub (github.com)
- Codex 计费说明 (developers.openai.com)
- 自定义指南 (developers.openai.com)
- 提示词最佳实践 (developers.openai.com)
- 工作流与示例 (developers.openai.com)