AiCodeCat Docs

主题

Codex CLI 使用指南（实战版） ​

适用人群：希望用命令行驱动 AI 自动改代码、跑测试、整理资料的工程师与团队。

1. Codex CLI 是什么 ​

Codex CLI 是一种“终端里的编程智能体”。你只需要描述任务，它会在你的工程里读取代码、执行命令、修改文件并回报结果，完成从“需求 → 计划 → 执行 → 反馈”的闭环。

核心特征：

  • 可执行：能跑命令、读写文件，而不是只会写建议。
  • 可控：通过“审批策略 + 沙箱模式”限定权限和风险。
  • 可协作：适合多轮对话式修复、重构、写测试等任务。

2. 发展时间线（流程图还原） ​

mermaid
flowchart LR
  A["2021-08-10<br/>OpenAI 发布 Codex API"] --> B["2025-04-16<br/>Codex CLI 首次发布"] --> C["2025-05-16<br/>基于 o3 的 Codex Agent 预览版"] --> D["2025-08-07<br/>GPT-5 正式发布"] --> E["2025-09-15<br/>Codex 升级说明"] --> F["2025-09-16<br/>GPT-5 Codex 公布"]

3. 关键概念速读 ​

  • 终端 / 控制台：输入命令、读取文本输出的窗口。
  • 命令：例如 git, ls, pwd 等指令。
  • CLI：命令行界面（Command Line Interface）。
  • Agent 架构：感知 → 记忆 → 决策 → 执行 → 反馈 的闭环系统。
mermaid
flowchart TD
  External[外部事件<br/>日志/接口/传感器] --> Perception[感知层<br/>解析输入]
  Perception --> Memory[状态记忆<br/>上下文/历史]
  Perception --> Decision[决策引擎<br/>规则/LLM/规划]
  Memory --> Decision
  Decision --> Executor[执行器<br/>命令/API/任务流]
  Executor --> Observe[结果观测<br/>日志/指标/测试]
  Observe --> Memory
  Observe --> Perception

4. 与 Claude Code 的差异（简化版） ​

  • Codex CLI：指令遵循更强、改动更精准，但速度慢、功能偏简。
  • Claude Code：生成速度快、功能丰富，但容易“输出过多”和引入无效代码。

结论：

  • 需要“稳、准、可控”时优先 Codex。
  • 需要“快速搭框架/大规模生成”时再考虑 Claude Code。

5. 安装与启动 ​

  1. 先安装 Node.js。
  2. 安装 CLI：
bash
npm install -g @openai/codex
  1. 启动交互式会话：
bash
codex

6. 常用命令与模式 ​

6.1 交互式模式（持续对话） ​

bash
codex

适合逐步调试、反复确认与迭代。

6.2 非交互式模式（一次性任务） ​

bash
codex e "整理这个目录的 Markdown 并生成目录"

适合批量任务或脚本式调用。

6.3 恢复历史会话 ​

bash
codex resume --last

会列出最近会话，可直接继续。

6.4 推荐用 /init + AGENTS.md 固化项目规则 ​

当你准备在一个新项目里长期使用 Codex，建议先：

  1. 在项目根目录补充 AGENTS.md（项目规范与约束）
  2. 进入会话后执行 /init 让 Codex 读取并固化这些规则

这样做的价值：

  • 减少反复沟通：不用每次都重复“技术栈/目录结构/禁改范围”。
  • 更稳的执行决策：Codex 会把 AGENTS.md 作为执行边界。
  • 提升团队一致性：多人协作时，AI 的行为更可控、更一致。

示例流程：

# 1) 进入项目根目录
cd your-project

# 2) 启动 Codex
codex

# 3) 在会话中执行
/init

小提示：

  • AGENTS.md 适合写“必须/禁止/验证命令”。
  • 规则变更后，重新 /init 一次即可生效。

7. 审批策略 + 沙箱模式（流程图还原） ​

审批策略决定“何时需要人工确认”，沙箱模式决定“能访问哪些资源”。

mermaid
flowchart TD
  Start[选择审批策略] --> Check{命令执行是否成功?}
  Check -- 是 --> Sandbox[遵循既定沙箱权限]
  Check -- 否 --> Policy[审批策略判断]
  Policy -->|untrusted| Human[请求人工批准后再执行]
  Policy -->|on-failure| Retry[失败时请求人工批准]
  Policy -->|on-request| Model[模型按需触发审批]
  Policy -->|never| Reject[直接返回错误信息]
  Human --> Sandbox
  Retry --> Sandbox
  Model --> Sandbox
  Reject --> Sandbox

常见沙箱模式：

  • read-only：只读，不写文件。
  • workspace-write：仅允许写当前工程目录。
  • danger-full-access：无隔离，风险最大。

风险提示： 不要在生产环境使用 danger-full-access 或跳过审批。

8. 常用快捷键与 Transcript ​

常见快捷键（以终端提示为准）：

  • Enter：发送提示
  • Ctrl+J：换行
  • Ctrl+T：打开/关闭 Transcript Overlay
  • Ctrl+C：退出
mermaid
flowchart LR
  A[终端对话] -- Ctrl+T --> B[Transcript Overlay]
  B -- Ctrl+T / q / Esc / Ctrl+C --> A

9. 配置文件与 AGENTS.md ​

  • 配置文件通常位于：~/.codex/config.toml
  • AGENTS.md 用于对 Codex 下达固定指令偏好

建议先阅读：Codex 使用配置分享001（站长精选中已有）。

10. 进阶示例：电子书转 Markdown ​

一个常见的高效用法是：把 EPUB 自动转换为 Markdown 并整理目录。

mermaid
flowchart LR
  A[下载 EPUB] --> B[pandoc 转 Markdown]
  B --> C[抽取图片到 media/]
  C --> D[可选：生成 TOC / README]

典型输出：

  • docs/books/xxx.md
  • docs/books/media/

11. 用手机访问 Codex 会话 ​

可以用 ttyd + tmux 把会话暴露到局域网端口，手机浏览器直接访问。

常见做法：

  • 使用脚本启动 ttyd
  • 设置端口、用户名、可选鉴权
  • 手机访问 http://<局域网IP>:<port>

注意安全：请仅在可信局域网使用，并避免开放到公网。

12. 使用建议与习惯 ​

  • 长任务先让 Codex 写计划再执行。
  • 使用 “小步确认”，避免一次性大改动。
  • 尽量让 Codex 在已受控的目录里工作。
  • 关键节点人工复审（特别是写文件/跑测试）。

补充说明： 本文为公开资料改写的工程化版本，内容做了结构化重组与实践化整理，便于在本项目文档体系中快速检索与复用。