#快速上手

#启动交互式会话

在项目根目录打开终端：

cd your-project
codex

进入 TUI（Terminal UI） 后，可直接用自然语言描述任务，例如：

阅读 src/auth 目录，总结认证流程，并列出三个潜在安全风险。

常用 TUI 命令：

#推荐的首个安全预设

本地开发建议显式带上沙箱与审批（也可写入 config.toml）：

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

这样 Codex 可在工作区内自由修改与跑测试，越界操作会暂停询问。

#非交互：codex exec

适合脚本、CI、一次性任务：

codex exec "运行 npm test 并修复失败用例，不要改 package.json"

CI 友好组合：

codex exec \
  --sandbox workspace-write \
  --ask-for-approval never \
  --json \
  --output-last-message \
  "根据 PR diff 生成 changelog 条目"

在 CI 中使用 never 审批时，务必配合严格沙箱与只读 checkout，避免误改仓库。

#指定工作目录

codex --cd services/api "列出该服务的公开 API 路由"

Codex 会加载从仓库根到 services/api 路径上的 AGENTS.md 链。

#附带图片

CLI 支持附加截图或设计稿（具体标志以 codex --help 为准），例如 UI 还原任务：

codex "根据附件截图实现 Settings 页面的布局，使用现有 Tailwind 约定"

#第一个完整小项目：添加健康检查端点

目标： 在现有 Web 服务中添加 /health，并补测试。

1. （可选）创建 Git 检查点

git checkout -b feat/health-endpoint

2. 在仓库根添加最小 AGENTS.md

# AGENTS.md

## 测试
- 运行 `npm test` 验证变更
- 不要提交 node_modules

3. 启动 Codex

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

4. Prompt 示例

添加 GET /health 返回 { "status": "ok" }。
遵循现有路由注册方式，并添加对应单元测试。
完成后运行测试并汇报结果。

5. 人工审查

git diff
npm test

#与 Git Checkpoint 配合

Codex 会直接改文件。建议：

• 任务前：git stash 或新分支
• 任务后：git diff + 测试 + 人工 commit
• App / IDE 中也可使用内置 checkpoint 概念（视版本而定）

#下一步

• 架构与运行机制：理解指令链与工具循环
• AGENTS.md 项目指令：固化团队规范
• 实战案例：更复杂的端到端流程