CLI 与终端参考
Codex CLI 终端使用、启动参数、exec、resume、app-server、远程连接、诊断、JSONL 和 stdin 管道的进阶参考。
命令大全 是速查表。本页补充 CLI 工作方式、终端会话、非交互输出、远程 app-server 和常见诊断方式。
#启动位置
Codex 的工作边界从当前目录开始。日常建议在项目根目录启动:
cd /path/to/project
codex临时指定目录:
codex -C /path/to/project
codex --cd /path/to/project "解释这个项目"如果任务需要跨多个目录,优先用 git worktree、monorepo 根目录或 --add-dir,不要直接开全盘权限。
#常用启动组合
| 场景 | 命令 |
|---|---|
| 默认交互 | codex |
| 带初始任务 | codex "修复这个报错" |
| 只读研究 | codex --sandbox read-only --ask-for-approval on-request |
| 可信项目小步实现 | codex --sandbox workspace-write --ask-for-approval on-request |
| 指定模型 | codex --model gpt-5.6-sol |
| 临时启用 live search | codex --search |
| 严格配置检查 | codex --strict-config |
--dangerously-bypass-approvals-and-sandbox 只适合隔离环境、临时 worktree、可恢复目录。不要在生产目录或含密钥目录里作为默认启动方式。
#交互式会话习惯
| 动作 | 推荐做法 |
|---|---|
| 引用文件 | 输入 @ 或用 /mention |
| 复杂任务 | 先 /plan,再执行 |
| 长任务 | 用 /goal 写清完成条件 |
| 看当前状态 | /status |
| 看 diff | /diff |
| 做 review | /review |
| 切权限 | /permissions |
| 压缩上下文 | /compact |
| 恢复历史 | /resume 或 codex resume --last |
Codex 线程可以继续、fork、归档或删除。不要让两个线程同时改同一批文件,除非每个线程都在独立 worktree 里。
#非交互 exec
codex exec 适合脚本、CI 和一次性批处理:
codex exec "review the current diff and list P0/P1 risks"继续上一段非交互会话:
codex exec "review the change for race conditions"
codex exec resume --last "fix the race conditions you found"指定 session:
codex exec resume <SESSION_ID> "continue with the same constraints"非交互模式默认要求在 Git 仓库里运行,这是为了降低破坏性改动风险。确实需要在非 Git 目录跑时,再考虑 --skip-git-repo-check。
#stdin 管道
当另一个命令产生上下文时,用 prompt + stdin:
npm test 2>&1 \
| codex exec "summarize the failing tests and propose the smallest likely fix"日志排查:
tail -n 200 app.log \
| codex exec "identify the likely root cause and next three debugging steps"CI 更新:
gh run view 123456 --log \
| codex exec "write a concise PR comment explaining the CI failure"#输出与自动化
| 需求 | 做法 |
|---|---|
| 机器读取结果 | 使用 JSON / JSONL 输出参数,并让 prompt 要求固定结构 |
| 多阶段 pipeline | 用 codex exec resume |
| 保留最后回复 | 重定向 stdout 到文件 |
| 保留完整 diff | git diff --binary HEAD > codex.patch |
| 限定模型和权限 | 传 --model、--sandbox、--ask-for-approval |
如果要做 GitHub Actions,优先看 非交互、CI 与 SDK。
#app-server 与远程连接
codex app-server 是 Codex App / IDE 等富客户端背后的协议入口,适合做深度集成或调试,不是普通 CI 的首选。
常见启动:
codex app-server
codex app-server --listen ws://127.0.0.1:4500
codex app-server --listen unix://连接远程 app-server:
codex --remote ws://127.0.0.1:4500WebSocket 远程监听仍应只放在 localhost 或 SSH tunnel 后面。需要暴露给远程客户端时,必须配置认证 token,不要裸露在公网或局域网。
#诊断
codex doctor
codex debug models
codex features
codex mcp listTUI 内:
/debug-config
/mcp
/status
/usage
/feedback日志:
RUST_LOG=debug codex -c log_dir=./.codex-log
tail -F ./.codex-log/codex-tui.logcodex-login.log 用于登录排错。非交互 codex exec 通常把诊断信息直接输出在命令结果里。
#shell completion
Codex CLI 支持生成 shell completion。具体参数随版本变化,先看:
codex completion --help如果找不到某个子命令,先升级 CLI 或用 codex --help / codex <subcommand> --help 查看当前版本支持的命令。
#官方参考
Support / 支持
Need help? / 需要帮助？
接入、计费与模型异常可邮件联系；服务可用性以状态页为准。
For setup, billing, or model issues, email us. Check the status page for uptime.
也可使用右下角微信 / QQ 客服 · WeChat / QQ support is available at the bottom right
