#Codex 基础入门

本章带你各完成一个可验证的小任务：先用桌面应用（推荐起点），再用 CLI。两条路用的是同一套 Agent，挑你顺手的开始。

#A. 用桌面应用完成第一个任务

#1. 准备一个 Git 项目

cd your-project
git checkout -b feat/health-endpoint   # 给 Agent 一个独立分支

#2. 在 App 中添加项目并选预设

• 侧边栏 Add project → 选择该目录
• 输入框下方设为：Default permissions（工作区可写 + 越界询问）、模型 GPT-5.5

#3. 发起任务

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

#4. 审批与审查

• 跑测试/装依赖等越界操作时，App 会弹出审批，确认后继续
• 完成后在右侧 Diff 面板逐行审查
• 满意则点 Commit；不满意点 Undo 撤销本轮

#5. 收尾

git diff
npm test

#B. 用 CLI 完成第一个任务

#启动交互式会话（TUI）

cd your-project
codex

进入 TUI 后用自然语言描述任务，例如：

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

#推荐的安全预设

本地开发建议显式带上沙箱与审批：

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

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

#常用 TUI 斜杠命令

完整列表见 斜杠命令。

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

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

1. 创建分支

   git checkout -b feat/health-endpoint

2. 在仓库根加一份最小 AGENTS.md

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

3. 发起任务（App 或 CLI 均可）

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

4. 人工审查

   git diff
   npm test

#与 Git 配合的好习惯

Codex 会直接改文件，建议：

• 任务前：新建分支（App 也可让任务跑在独立 worktree）
• 任务后：git diff + 测试 + 人工 commit
• App 中可用 Undo 撤销本轮改动；CLI 善用 git stash

#非交互一行流（脚本/CI）

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

详见 自动化与 CI/CD 与 命令行工具。

#下一步

• 核心概念：理解指令链与工具循环
• AGENTS.md：把团队规范固化下来
• 提示词最佳实践：写出更高命中率的指令