codex 使用

1. 购买apikey

sub.zhengmi.org进入中转平台，购买套餐

2. 安装codex&配置密钥

npm i -g @openai/codex

codex

~/.codex/config.toml
model_provider = "sub2api"
model = "gpt-5.2-codex"
model_reasoning_effort = "high"
network_access = "enabled"
disable_response_storage = true
windows_wsl_setup_acknowledged = true
model_verbosity = "high"

[model_providers.sub2api]
name = "sub2api"
base_url = "https://sub.zhengmi.org"
wire_api = "responses"
requires_openai_auth = true

~/.codex/auth.json
{
  "OPENAI_API_KEY": "sk-xxx"
}

3. 常用命令

3.1 启动方式

3.1.1 交互模式（默认：TUI 会话）

codex
进入交互式 TUI，会话里你持续提需求，它持续读/改/跑。
你也可以带一个初始任务：
codex "先解释这个仓库的结构，然后帮我找出最可能的入口文件"

3.1.2 非交互模式（一次性执行）：codex exec

1
2
3

codex exec "跑测试并修复失败用例，直到通过"
适合脚本、CI、自动化批处理。
也可以从 stdin 读 prompt（用 - 或直接 pipe）。

3.1.3 只做代码审查（非交互）：codex review

1	codex review "重点检查安全风险和边界条件"

3.2 全局通用参数

小节	参数	作用	典型值/说明	示例
目录与工作区	`-C, --cd <DIR>`	指定工作根目录（强烈推荐脚本里用，避免在错误目录运行）	`<DIR>` 通常是仓库根目录或子目录	`codex -C /path/to/repo "修复 lint"`；`codex exec -C /path/to/repo "运行测试"`
目录与工作区	`--add-dir <DIR>`	额外允许写入的目录（除主工作区外）	用于多仓库/mono repo 跨目录改动	`codex -C apps/frontend --add-dir ../shared "同时修改前端与共享包"`
模型选择	`-m, --model <MODEL>`	指定模型	模型 ID 取决于账号/环境可用列表	`codex -m "gpt-5.3-codex" "重构这段代码"`
沙箱	`-s, --sandbox <SANDBOX_MODE>`	执行“模型生成的 shell 命令”时的沙箱策略	`read-only` / `workspace-write` / `danger-full-access`	`codex exec -s workspace-write "安装依赖并运行测试"`
批准策略	`-a, --ask-for-approval <APPROVAL_POLICY>`	何时需要你批准命令执行	`untrusted` / `on-request` / `never`（`on-failure` 已废弃）	`codex -a untrusted "先分析问题，任何危险命令都先问我"`
便捷组合	`--full-auto`	低摩擦自动执行（便捷别名）	等价：`-a on-request --sandbox workspace-write`	`codex exec --full-auto "修复测试直到通过"`
极危险	`--dangerously-bypass-approvals-and-sandbox`	跳过所有确认 + 不沙箱执行	官方标注 EXTREMELY DANGEROUS	（不建议示例；只在外部强沙箱环境使用）
配置覆盖	`-c, --config <key=value>`	运行时覆盖 `~/.codex/config.toml` 配置	`value` 会按 TOML 解析；失败则按字符串	`codex -c 'model="o3"' "解释这个仓库"`；`codex -c 'sandbox_permissions=["disk-full-read-access"]' "扫描所有日志文件"`
Feature flags	`--enable <FEATURE>` / `--disable <FEATURE>`	开关 feature	等价于 `-c features.<name>=true/false`	`codex --enable unified_exec`
图片输入	`-i, --image <FILE>...`	初始 prompt 附带图片	可重复；常见 PNG/JPG	`codex -i design.png "按这张设计图实现页面"`
Web Search	`--search`	启用实时网络搜索	开启后模型可用 web_search 工具	`codex --search "查一下这个库的最新用法并改代码"`
交互界面	`--no-alt-screen`	禁用 alternate screen（保留终端滚动历史）	对 tmux/zellij 常有用	`codex --no-alt-screen`

3.3 `codex exec` 详解

codex exec 用于“一条命令把事干完”，并可输出结构化结果。

3.3.1 用法

1	codex exec [OPTIONS] [PROMPT]

如果 PROMPT 省略或传 -，会从 stdin 读取。

3.3.2 `codex exec` 关键参数

--skip-git-repo-check：允许在非 git 仓库目录运行
--ephemeral：不把 session 文件持久化到磁盘
--output-schema <FILE>：指定 JSON Schema，让最终输出符合某种结构
--json：把事件以 JSONL 打到 stdout（便于你写脚本解析）
-o, --output-last-message <FILE>：把 agent 最后一条消息写入文件（很适合 CI 产物）
--color <always|never|auto>：输出颜色策略

3.3.3 常见组合示例

让它安静地跑，并把最后总结写到文件：

1	codex exec --json -o codex_last.txt "修复测试并输出你做了哪些改动"

1	codex exec -C . --full-auto "安装依赖并运行测试，直到通过"

代码理解/梳理（不改代码也能用）

1
2
3

codex exec -C . "用 15 行总结这个仓库做什么、入口在哪、核心模块有哪些"

codex exec -C . "画一份模块依赖关系（用 markdown 列表即可），并指出最容易出 bug 的边界"

跑测试 + 修复（常用）

codex exec -C . --full-auto "运行测试并修复失败用例，直到全部通过；最后总结改了哪些文件"

更保守一点（只读沙箱，让它先给方案）：

codex exec -C . -s read-only "先定位为什么测试失败，给出修复方案和具体改动点（不要改文件）"

Lint/格式化/构建修复

1
2
3

codex exec -C . --full-auto "运行 lint，修复所有 lint errors；最后再跑一遍 lint 确认"

codex exec -C . --full-auto "如果项目有 format 脚本就运行并修复格式问题；否则给出建议配置"

单文件定向任务（更精准）

1
2
3

codex exec -C . "只修改 src/app.ts：把这个函数提取成独立模块，并补充类型定义"

codex exec -C . "为 src/utils/date.ts 写单测（按项目现有测试框架），并跑通"

批量重构/批量替换（适合 exec）

1
2
3

codex exec -C . --full-auto "把所有 import 的相对路径改为项目约定的 alias（按现有 tsconfig/vite 配置推断）并跑测试"

codex exec -C . --full-auto "把仓库里所有 *.jpeg 重命名为 *.jpg（用 git mv），更新引用，并跑测试"

生成结构化输出（配合 --output-schema）
适合“我希望最后输出必须是 JSON，方便下游程序用”。例如你写一个 schema 文件 schema.json 后：
1
codex exec -C . --output-schema schema.json "扫描仓库 TODO，并按 {file, line, text, priority} 输出"

用 --json 输出事件流（方便 tee / jq）

codex exec -C . --json "解释这个仓库" | tee codex.jsonl

只提取最后一条消息（不同事件字段名可能因版本不同，思路是用 jq 过滤）：

codex exec -C . --json "总结这个仓库" | jq -r 'select(.type=="message") | .text' | tail -n 1

把最后总结落盘（CI 常见）

1
2
3

codex exec -C . -o codex_last.txt "修复构建并总结你做了什么"

cat codex_last.txt

非 git 目录也跑（临时脚本目录/新项目）

1	codex exec -C /tmp/demo --skip-git-repo-check "生成一个最小可运行的 Python http server，并给出运行命令"

“续跑”上一次 exec（exec 子命令 resume）

codex exec resume --last "继续把刚才没做完的重构做完，并跑测试"

指定某次 session id：

codex exec resume 7f9f9a2e-xxxx-xxxx-xxxx-xxxxxxxxxxxx "继续实现上一轮计划的第 2 步"

3.4 `codex review` 详解

1	codex review [OPTIONS] [PROMPT]

常用参数：

--uncommitted：审查当前未提交的变更（staged/unstaged/untracked）
--base <BRANCH>：以某分支为基准做 diff 审查
--commit <SHA>：审查某个提交引入的变更
--title <TITLE>：给审查摘要一个标题

示例：

1	codex review --uncommitted "请按：安全性 > 可维护性 > 性能的顺序给出问题清单和修复建议"

3.5 `codex resume` 恢复会话

1	codex resume [SESSION_ID] [PROMPT]

--last：继续最近一次会话（不弹 picker）
--all：显示所有会话（取消 cwd 过滤，并显示 CWD 列）

示例：

1 2	codex resume --last codex resume <session-uuid> "继续完成刚才的重构"

3.6 `codex apply`（把 Cloud/任务 diff 应用到本地）

1	codex apply <TASK_ID>

它会把 Codex agent 产生的最新 diff 用 git apply 方式打到你的 working tree。

3.6 `codex login/logout`（鉴权相关）

查看登录状态（在 codex login 子命令里）：

1	codex login status

用 API Key 登录（从 stdin 读 key）：

1	printenv OPENAI_API_KEY \| codex login --with-api-key

退出/清理凭证：

1	codex logout

3.7 `codex completion`（命令补全）

1 2	codex completion bash codex completion zsh

支持：bash|elvish|fish|powershell|zsh。

3.8 `codex sandbox`（把任意命令放进 Codex 沙箱跑）

1	codex sandbox <COMMAND>

子命令按系统区分：

codex sandbox macos ...（Seatbelt）
codex sandbox linux ...（Landlock+seccomp）
codex sandbox windows ...（restricted token）

用途：你想让某个命令“强制在受限环境跑”，但不一定要让 agent 决策。

3.9 交互会话里面的斜杠命令

命令	作用	什么时候用	备注
`/model`	会话中途切换模型（部分版本可同时选 reasoning effort）	想在同一任务里换更强/更快模型，或调整推理强度时	切完建议用 `/status` 确认是否生效
`/status`	查看当前会话配置（模型、权限/批准策略、可写目录、token/context 等）	不确定当前模型/权限/目录是否正确，或排查“为什么不让跑命令/不让写文件”时	常用来做自检
`/permissions`	调整“它能做什么/何时需要你批准”（动态切换 approval preset）	任务前期用保守策略（只读/多确认），后期放开让它自动跑测试/改文件时	相当于运行中改权限档位
`/init`	在当前目录生成 `AGENTS.md` 脚手架（项目级长期指令/约定）	想把仓库规范、代码风格、目录说明沉淀下来，让后续会话更一致时	生成后建议手动补充并提交到仓库
`/new`	在同一个 CLI 里开一个“新对话”（清空当前上下文，但目录不变）	同一仓库里换一个完全不同任务，不想带上上一段对话的上下文时	适合“重开一轮”但不退出 CLI
`/review`	对当前 working tree 做一次 review	改完代码后，让它当“第二双眼睛”找风险、边界条件、缺测试等	常配合 `/diff` 使用
`/diff`	在 CLI 里直接看 git diff（含未跟踪文件）	想快速审阅它改了什么、是否要保留时	相当于在 Codex 里内置 diff 视图
`/compact`	把当前可见长对话压缩成摘要（节省上下文）	对话太长，担心上下文/成本，或想“保留要点但丢掉细节”时	压缩后细节可能丢失，谨慎使用
`/fork`	把当前对话 fork 出新线程（保留原线程不动）	想并行探索另一条方案/另一个实现，但又不想污染当前对话时	类似“分支”思路：原线程继续可追溯
`/exit` / `/quit`	退出交互会话	做完了要离开 Codex CLI 时	退出前记得 commit 或保存重要改动