Appearance

Codex CLI 备忘清单 ​

OpenAI Codex CLI（v0.116+）是一个开源 AI 编程代理，可直接在终端中读取、修改并运行代码。参见官方文档。

快速开始 ​

安装与运行 ​

npm（推荐） ​

bash
$ npm install -g @openai/codex
$ npm install -g @openai/codex@latest   # 升级

Homebrew（macOS） ​

bash
$ brew install codex

首次运行 ​

bash
$ codex                          # 启动交互式 TUI
$ codex "Explain this codebase"  # 带初始提示

首次运行时会提示你通过 ChatGPT 账号或 API key 登录。

Shell 自动补全 ​

bash
# Zsh - 添加到 ~/.zshrc
$ eval "$(codex completion zsh)"

# Bash - 添加到 ~/.bashrc
$ eval "$(codex completion bash)"

# Fish
$ codex completion fish | source

平台支持 ​

平台状态
macOS稳定
Linux稳定
Windows (WSL)推荐
Windows（原生）实验性

身份认证 ​

bash
$ codex login                # ChatGPT OAuth
$ codex login --device-auth  # 设备码登录流程

从环境变量管道传入 API key

bash
$ printenv OPENAI_API_KEY | codex login --with-api-key
$ codex login status         # 检查登录状态
$ codex logout               # 移除凭据

子命令 ​

命令参考 ​

命令别名状态说明
codex稳定启动交互式 TUI
codex execcodex e稳定以非交互模式运行（脚本化）
codex review稳定非交互代码审查
codex resume稳定恢复历史会话
codex fork稳定分叉会话到新线程
codex applycodex 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实验性调试工具

Exec（非交互） ​

bash
# 基础非交互运行
$ codex exec "Fix the race condition"
$ codex e "Add unit tests for utils"

从 stdin 读取提示词

bash
$ echo "Explain main.go" | codex exec -

Prompt-plus-stdin（0.118+）：既传入管道数据，也传入提示词

bash
$ cat error.log | codex exec "Diagnose this log" -

输出选项

bash
$ codex exec --json "Audit security"
$ codex exec -o last.txt "Summarize"

恢复之前的 exec 会话

bash
$ codex exec resume --last "Fix the bugs"
$ codex exec resume  "Implement"

全局选项 ​

全部参数 ​

参数取值说明
-m, --modelstring覆盖模型（例如 gpt-5.4）
-s, --sandbox见下文沙箱策略
-a, --ask-for-approval见下文审批策略
--full-autoflagworkspace-write + on-request
--yoloflag跳过全部审批和沙箱
-i, --imagepath给初始提示附加图片
-c, --configkey=val覆盖配置项
-C, --cdpathAgent 工作目录
-p, --profilestring配置档名称
--searchflag启用实时网页搜索
--add-dirpath追加可写目录权限
--ossflag使用本地 OSS provider
--local-providerlmstudio/ollama指定 OSS provider
--enablefeature启用特性开关
--disablefeature禁用特性开关
--no-alt-screenflag内联 TUI 模式（禁用 alt screen）
--remotews://host:port连接远程 app server
--remote-auth-token-envENV_VAR远程 WS 的 Bearer Token 环境变量
-V, --version输出版本
-h, --help输出帮助

使用示例 ​

bash
# 指定模型
$ 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-autoworkspace-write + on-request
--yolo无沙箱 + 无审批

可在 TUI 中使用 /permissions 在会话中途切换模式。

Slash 命令 ​

会话控制 ​

命令说明
/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）

选择模型 ​

bash
$ codex -m gpt-5.4 "Your prompt"
$ codex -m gpt-5.4-mini "Quick task"
$ codex --oss    # local Ollama / LM Studio
# 会话中途可在 TUI 输入 /model

配置 ​

config.toml 关键项 ​

toml
# ~/.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 启用该配置档。

特性开关 ​

bash
$ 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仓库指令

自定义 ​

AGENTS.md ​

可随代码一同提交的仓库级持久指令：

markdown
## 构建与测试命令

- 安装：`npm install`
- 测试：`npm test`
- Lint：`npm run lint`

## 约定

- TypeScript 严格模式
- 日志中不得包含 PII
- 所有路由都需鉴权中间件

## 审查准则

- 标记未处理的 Promise rejection

建议添加规则的场景：

  • Agent 重复犯错
  • PR 审查反馈反复出现
  • 在 GitHub 使用 @codex add to AGENTS.md 标签

Skills ​

可复用工作流可打包为 SKILL.md：

my-skill/
  SKILL.md      ← 元数据 + 指令
  scripts/      ← 可选辅助脚本
  references/   ← 可选文档
  assets/       ← 可选模板

SKILL.md 示例：

markdown
---
name: commit
description: 按语义分组暂存并提交变更。
---

1. 按逻辑分组暂存文件。
2. 分组顺序：feat → test → docs → chore
3. 编写简洁的提交信息。

MCP Servers ​

bash
# 添加 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

会话管理 ​

恢复会话 ​

bash
$ codex resume        # 会话选择器
$ codex resume --last # 最近一次会话
$ codex resume --all  # 跨目录查找
$ codex resume  "Continue fixing tests"

会话保存在 ~/.codex/sessions/

分叉会话 ​

bash
$ codex fork             # 从选择器分叉
$ codex fork --last      # 分叉最近一次
$ codex fork  "New direction"

分叉会保留原始会话记录，并开启一条新分支。

图片输入 ​

bash
# 单张图片
$ codex -i screenshot.png "Fix this error"

# 多张图片
$ codex --image img1.png,img2.jpg "Compare"

# 或将图片直接拖入 TUI 输入框

支持 PNG、JPEG 等常见格式。

Cloud 与 GitHub ​

Cloud 任务 ​

bash
# 浏览 Cloud 环境
$ codex cloud

# 提交 Cloud 任务
$ codex cloud exec --env  "Fix bug"

# 多次尝试（best-of-N）
$ codex cloud exec --env  \
    --attempts 3 "Write failing tests"

# 列出最近任务
$ codex cloud list

# 查看任务状态
$ codex cloud status 

# 查看任务 diff
$ codex cloud diff 

# 将 diff 应用到本地工作树
$ codex apply

GitHub 集成 ​

bash
# 在 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.4medium
快速探索代理gpt-5.4-minilow
安全/逻辑审查代理gpt-5.4high

推理强度 ​

等级适用场景
high复杂逻辑、安全审计
medium通用任务（默认）
low简单任务或对速度敏感的任务

可在 config.toml 中设置：

toml
model_reasoning_effort = "medium"

也可命令行临时指定：-c model_reasoning_effort="high"

延伸阅读 ​

Copyright © 2026 小弥渡

Copyright © 2026 小弥渡
本网站由 Netlify 部署并提供全球 CDN 边缘网络加速