Agent 入门手册 beginner / 01

CODEX FIELD GUIDE · 2026

先理解 Agent，
再把任务交给 Agent。

Codex 不是“会写代码的聊天框”。它会读取规则、检查环境、调用工具、观察结果，再决定继续还是结束。你要做的，是给它清晰的目标和可靠的边界。

从心智模型开始 直接看示例
AGENT 目标仍未完成？

不是一次回答而是可观察、可纠正的执行循环

00 / 心智模型

一次可靠执行，需要四样东西

01

目标

你最终想得到什么结果，而不只是“帮我看看”。

02

上下文

仓库、文件、现状、错误和已有约定。

03

边界

什么不能改、哪些操作需确认、范围到哪里。

04

验收

测试、截图、命令输出，或明确的完成条件。

好任务=目标+上下文+边界+验收

01 / 指令层

全局与仓库 AGENTS.md

把它理解为“每次开工前，Agent 必须先读的工程约定”。离当前目录越近的规则，优先级通常越高。

GLOBAL
~/.codex/AGENTS.md

个人跨仓库习惯：语言、提交格式、安全边界、默认验证方式。

基础层
REPO
project/AGENTS.md

团队共享约定：技术栈、目录职责、构建命令、测试与发布规则。

项目层
LOCAL
project/api/AGENTS.override.md

局部例外：只适用于当前子目录，覆盖上层冲突规则。

最高层

02 / 执行层

Agent Loop 原理

模型不会“一次性生成整个工程”。每次工具结果都会成为下一步判断的新输入，这就是 Agent 与普通文本生成的关键区别。

01

理解

读取请求、指令层与完成条件。

02

检查

查看代码、环境、工具和当前状态。

03

决定

选择下一项最小且有效的动作。

04

执行

编辑文件、运行命令或调用外部工具。

05

观察

读取输出，识别成功、错误与新事实。

06

验证

测试结果；未完成就回到下一轮。

你不需要提供 Agent 的“思维过程”。你需要提供的是可检查的事实、明确约束和验证方法。

读取 → 决定 → 工具调用 → 结果 → 再决定

03 / 长任务

Goal 模式：让任务跨轮次持续推进

Goal 是部分 Codex 客户端提供的长任务机制。它保存一个明确目标及其状态，让 Agent 在自动续跑时继续围绕同一结果工作。

普通任务

一轮对话内完成

  • 修一个明确的 bug
  • 解释一个模块
  • 改一处页面样式

范围窄、上下文稳定、一次验证即可收尾。

Goal 模式

围绕结果持续迭代

  • 迁移整个项目
  • 完成多阶段部署
  • 长期排查复杂故障

适合需要多轮执行、阶段验证和中断后恢复的任务。

active 持续推进 complete 验收完成 或 blocked 确认无法继续

Goal 不是“放宽要求”，也不是简单待办清单。完成标准、验证和安全边界仍然有效；具体可用性与界面以当前 Codex 客户端为准。

04 / APP 命令台

输入一个 /，快速切换工作方式

在 Codex App 的输入框键入 / 会打开命令列表。继续输入可筛选命令，选择后再按界面提示完成设置。

Codex App · Composer ⌘ K / command menu
›/plan
/plan先讨论并整理多步骤方案↵
/goal把确认后的目标设为持续任务
/review检查未提交变更或对比分支
01

规划与持续执行

/plan
切换 Plan 模式。复杂任务先在这里澄清范围、步骤与验收。
/goal
设置或管理持续目标。适合已明确、需要跨轮次推进的工作。
/side
开启临时侧聊，在不打断主任务的情况下确认一个问题。
02

项目与隔离环境

/project
为新对话选择本地项目。
/local
把当前对话放到所选本地项目中运行。
/worktree
在新 Git worktree 中运行，隔离并行改动。
/cloud
可用时，把对话切换到云端执行。
03

模型与上下文

/model
选择当前对话使用的模型。
/reasoning
调整当前对话的推理强度。
/status
查看对话 ID、上下文使用量与速率限制。
/compact
压缩当前对话上下文，为后续工作腾出空间。
04

检查与扩展

/review
审查未提交改动，或与指定基础分支比较。
/mcp
打开 MCP 状态，查看已连接的服务器。
/init
为当前项目生成一个 AGENTS.md 初始模板。
/fork
把本地对话复制到新的对话或 worktree。

复杂任务的推荐组合

  1. /plan把模糊需求整理清楚
  2. /goal确认后持续执行
  3. /status检查上下文与限制
  4. /review在交付前审查变更
查看官方 Slash commands 参考

命令会随 App 版本、当前模型和已启用功能变化；如果列表里没有某条命令，以输入框实际显示为准。

05 / 能力层

Skills：可复用的专业工作流

Skill 是一个包含 SKILL.md 的目录，可附带脚本、参考资料和模板。它告诉 Codex 某类任务应该按什么流程完成。

常驻上下文

名称 + 描述 + 路径

用很少的上下文告诉 Codex“有哪些能力可用”。

按需加载

完整 SKILL.md

只有匹配任务时才读取完整流程，称为渐进式披露。

深层资源

scripts/ + references/

再按步骤调用脚本或读取具体参考文件。

deploy-service/
├── SKILL.md       # 必需：触发条件与流程
├── scripts/       # 可执行工具
├── references/    # 按需读取的知识
└── assets/        # 模板与静态资源

什么时候该写 Skill？

同一类任务反复出现，而且需要稳定步骤、专用工具或领域知识时。

一句判断：规则讲“始终怎么做”，Skill 讲“遇到这类任务时怎么做”。

06 / 插件生态

Plugins：一次安装，获得一组协作能力

Skill 只描述可复用流程；Plugin 是可安装、可分发的能力包，还能同时携带连接器、MCP、浏览器扩展、Hooks 与定时任务模板。

PLUGIN能力包
Skills工作步骤与领域知识
Connectors连接 Gmail、Drive、Slack 等服务
MCP结构化工具与外部数据
Hooks生命周期自动动作
OPENAI / COMMON TOOLKIT

常见官方能力插件

实际可见项取决于 App 版本、账号、平台与工作区策略。

Browser

控制 App 内置浏览器，打开页面、读取界面、点击操作，并验证本地 Web 应用。

@Browser 检查这个页面的移动端布局

Chrome

使用已有 Chrome 标签页、登录状态与扩展，适合必须依赖个人浏览器环境的任务。

@Chrome 查看我已登录的管理后台

Computer Use

操作本机 macOS 应用界面。只有缺少更直接的 API、CLI 或连接器时才优先使用。

在本机应用中完成这项设置

Record & Replay

录制一次人工操作，把事件流整理成可重复执行的 Skill，适合固定桌面流程。

记录我接下来的操作并生成 Skill

Visualize

在对话中创建图表、对比、模拟器和交互式探索工具，帮助理解数据与系统行为。

@Visualize 做一个可调参数的延迟图

Documents

创建、编辑、批注和审阅 Word 文档，并通过渲染结果检查最终版式。

把这份说明整理成正式 DOCX

Spreadsheets

创建、分析和验证 XLSX、CSV、TSV；需要时也可连接当前 Excel 会话。

分析这份表格并生成汇总工作表

Presentations & PDF

制作演示文稿，或读取、合并、OCR、填写和导出 PDF 文件。

把报告改成 10 页演示文稿

安装与调用

  1. 01

    在 Codex App 打开 Plugins，从 OpenAI 标签选择插件并点击加号。

  2. 02

    插件需要连接器时，按提示登录并确认服务权限。

  3. 03

    安装后开启新对话；直接描述结果，或键入 @ 明确选择插件/Skill。

  4. 04

    在 Codex CLI 输入 /plugins 浏览、安装、卸载或启停插件。

安装 ≠ 自动信任

Codex 主机的沙箱与审批策略仍然生效。外部连接器使用各自的身份验证和权限；启用 Hooks 前应先检查其行为。卸载插件也不会自动断开已授权连接器。

官方 Plugins 文档

07 / 机制选择

这条信息应该放哪里？

选择你正在解决的问题，查看最小且合适的 Codex 机制。

DURABLE INSTRUCTIONS

使用 AGENTS.md

适合语言规范、代码约定、验证命令、禁止事项与仓库边界。保持短小、稳定，并放在需要生效的目录层级。

project/AGENTS.md

08 / 起步模板

从两个短文件开始

示例故意保持精简。把真正稳定的约定写进去，而不是复制一份庞大的通用规则。

~/.codex/AGENTS.md全局
# Personal defaults

- Reply in Chinese.
- Read files before editing.
- Keep changes scoped to the request.
- Run focused verification after changes.
- Ask before irreversible operations.
project/AGENTS.md仓库
# Project guide

- Install: `pnpm install`
- Dev: `pnpm dev`
- Test: `pnpm test`
- Reuse components from `src/ui`.
- Do not edit generated files in `dist/`.
- Verify desktop and mobile layouts.

第一条高质量任务可以这样写：

“修复登录页在 390px 宽度下按钮溢出的问题。复用现有组件，不改其他页面。完成后运行前端测试，并用桌面和移动端截图验证。”
目标明确范围清楚约束可执行验收可验证

READY / CHECK

交给 Agent 前，检查这五件事

  1. 01目标是否能用一句话说清？
  2. 02Agent 是否能找到相关文件与现状？
  3. 03不能做什么，是否明确写出？
  4. 04完成后要运行什么验证？
  5. 05重复规则是否应该沉淀到 AGENTS.md 或 Skill？