这一章先回答三个问题：Codex CLI 是什么、怎么启动、它能做什么和不能做什么。基础阶段最重要的不是记住所有命令，而是建立正确的使用边界。

1.1 Codex CLI 是什么

Codex CLI 是运行在终端里的 AI 编程助手。它可以读取当前项目、解释代码、修改文件、运行命令、做代码审查、补测试、写文档，也可以在权限允许时调用网络、MCP 工具、插件和外部服务。

它和普通聊天机器人的区别在于：Codex CLI 是“在项目目录里工作”的。它不是只根据你粘贴的片段回答，而是可以自己查看文件、理解目录结构、运行测试并修改文件。

适合 Codex CLI 的任务：

阅读陌生项目，梳理入口、模块、数据流和测试方式。
实现边界明确的新功能。
修复可复现 bug。
补测试、补类型、补文档。
做本地 diff 审查。
把重复流程沉淀为 AGENTS.md、Skill 或自动化。

不适合直接交给 Codex CLI 的任务：

没有边界的“整体优化一下”。
不允许验证的线上改动。
含真实密钥、生产数据、敏感凭证的排查。
大规模破坏性操作，例如批量删除、重置 Git 历史、直接改生产配置。

1.2 启动方式

最常用入口：

codex

这会打开交互式 TUI。你可以持续对话、批准命令、查看 diff、切换权限、继续修改。

带初始提示词启动：

codex "Explain this codebase to me"

适合快速让 Codex 阅读当前目录并给出总结。

指定工作目录：

codex --cd /path/to/project

适合从任意目录启动，但让 Codex 在指定项目里工作。

显式设置权限：

codex --sandbox workspace-write --ask-for-approval on-request

这是适合本地开发的低摩擦模式：允许 Codex 在工作区内读写和运行常规命令，越界时再请求确认。

诊断本地环境：

codex doctor

当登录、配置、终端、Git、运行时或会话状态异常时，先用这个命令生成诊断报告。

1.3 非交互模式

如果你想在脚本或流水线里调用 Codex，用 codex exec：

codex exec "summarize the repository structure and list the top 5 risky areas"

codex exec 默认更保守，官方手册说明它默认在只读沙箱中运行。需要写文件时要显式授权：

codex exec --sandbox workspace-write "fix the failing test"

需要机器可读输出时：

codex exec --json "review this change and output findings"

实践建议：

用 codex 做交互式开发。
用 codex exec 做自动化、流水线、批量摘要、结构化审查。
自动化里尽量不要使用 danger-full-access。
如果必须给高权限，放在隔离容器、临时分支或专用 CI runner 里。

1.4 权限模型

Codex 的安全控制主要分两层。

第一层是 sandbox mode，决定技术边界：

read-only：只能读，适合咨询、阅读、方案设计。
workspace-write：可以在工作区内读写并运行常规命令，适合日常开发。
danger-full-access：取消沙箱边界，只有在隔离、可信、可回滚环境里才考虑。

第二层是 approval policy，决定什么时候停下来问你：

untrusted：对不在可信集合里的命令更谨慎。
on-request：在沙箱内自动执行，越界或需要网络时请求确认。
never：不弹出审批，适合经过隔离的自动化，不适合普通本地仓库。

新手建议：

codex --sandbox workspace-write --ask-for-approval on-request

如果只是想让 Codex 读项目，不希望它改文件：

codex --sandbox read-only --ask-for-approval on-request

1.5 网络访问

官方手册说明，Codex 本地命令默认没有网络访问。也就是说，安装依赖、访问外部 API、拉取网页、调用某些包管理器命令，都可能需要额外授权或配置。

这点很重要，因为网络访问会扩大风险面：

外部网页可能包含 prompt injection。
安装脚本可能执行不可信代码。
命令可能把本地信息发送出去。
私有网络或本机服务可能被误访问。

最佳实践：

能用项目已有依赖就不要临时安装。
需要联网时，让 Codex 说明原因和目标域名。
对包管理器安装、curl 脚本、远程 shell 命令保持警惕。
不要让 Codex 在高权限模式下随意 live web search。

1.6 常用斜杠命令

在交互式 CLI 中输入 / 可以打开命令菜单。

入门阶段必须熟悉这些：

/permissions：调整权限模式。
/status：查看模型、权限、工作区、上下文等状态。
/diff：查看当前修改，包括未跟踪文件。
/review：让 Codex 审查当前变更。
/plan：进入计划模式，适合复杂任务先做方案。
/model：切换模型。
/compact：压缩长会话上下文。
/resume：恢复历史会话。
/mcp：查看 MCP 工具。
/skills：查看和使用 Skills。
/agent：查看或切换 subagent 线程。
/clear：清空当前会话并开始新对话。
/exit 或 /quit：退出 CLI。

使用口诀：

先 /status 确认环境
复杂任务先 /plan
改完先 /diff
合并前跑 /review
长会话用 /compact
中断后用 resume

1.7 第一次使用的推荐流程

在一个新项目里，不要直接说“帮我开发功能”。先让 Codex 建立上下文：

先不要修改文件。请阅读当前项目结构、README、配置文件和测试入口，说明：
1. 这个项目的主要目录职责。
2. 如何运行、测试、构建。
3. 如果我要新增一个功能，通常应该改哪些层。
4. 当前项目有哪些明显风险或缺失说明。

确认它理解对了，再进入开发：

基于上面的理解，实现 <具体功能>。要求：
1. 保持现有风格。
2. 只改必要文件。
3. 补充或更新相关测试。
4. 最后运行最小相关验证。
5. 总结改动和剩余风险。

这比“帮我写代码”稳定得多。

1. 基础功能与安全边界