Codex 入门到进阶教程：用 AGENTS.md 与 Skills 搭建可复用的 Project 工作流

1. 为什么你的 Codex 总是“不懂你”刚接触 Codex 的开发者十有八九会遇到同一个困惑明明装好了、登录了、也能对话但每次让它干活产出都像第一次见面——格式不对、目录乱放、风格飘忽改完下次又忘。问题不在模型而在于你没有给它一份稳定的“工作手册”。Codex 可以理解成装在你电脑里的 AI Agent。它不只是给建议在获得权限后能读写本地文件、生成文档和网站、操作浏览器、创建定时任务把重复工作直接做完。如果只想聊天问问题普通 Chat 就够了但只要任务会产生文件、要整理资料、要写代码、要做网页就应该放进 Codex 的 Project 里完成。这篇教程面向刚上手 Codex 的开发者按“从零配置到多 Project 协作”的顺序讲清楚三件事AGENTS.md 怎么写、Skills 目录怎么组织、Plugins 怎么启用最后用一次完整任务把流程跑通。核心检索词先记住Codex 是执行者AGENTS.md 是规则Skills 是流程Plugins 是连接外部工具的通行证Project 是这一切的落地文件夹。我试过把同一套规则文件在三个 Project 之间复用最大的感受是规则写得越具体Codex 越像“老员工”规则空着它每次都像“第一天上班”。下面从环境准备开始一步步搭起来。2. 前置准备TaoToken 与 Codex 的接入关系在动手写规则之前先把“模型从哪来”这件事理清楚。Codex 本身是客户端形态的 Agent 工具它需要调用大模型来完成推理和工具调用。你可以用官方账号登录也可以走 API 方式接入兼容的模型服务。对于需要长期跑编码任务、Agent 任务、批量任务的开发者用 API Key 接入往往更灵活也方便在多个 Project 之间统一管理额度。TaoToken 在这里扮演的是模型接入层它提供统一的 API 入口你拿到 Key 之后把它配置到 Codex 或相关工具里就能让 Codex 的推理请求走这条通道。官网地址是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 入口是 https://taotoken.net/api 这个地址不加 UTM 参数。需要先明确一点TaoToken 不是编辑器也不替代 Codex 本身。它解决的是“模型调用通道”的问题Codex 解决的是“在本地执行任务”的问题两者是配合关系。你可以把它类比成Codex 是施工队TaoToken 是材料供应通道AGENTS.md 是施工图纸。适合走这条路线的人需要长期做编码/Agent 任务、希望额度集中管理、要在多个 Project 里复用同一套模型配置的开发者。如果你只是偶尔问几个问题先用账号登录体验也完全没问题等任务量上来了再切到 API Key 方式。拿到 Key 的入口在控制台的 API Keys 页面具体地址是 https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 配置时遇到字段不确定优先查这份文档。注意API Key 属于敏感凭证不要写进 AGENTS.md也不要提交到 Git 仓库。建议放在本地环境变量或独立的配置文件里并在 .gitignore 中排除。3. 可复制配置AGENTS.md 骨架与 Skills 目录结构这一节是全文的核心给出可以直接复制使用的配置片段。先讲 AGENTS.md再讲 Skills 目录最后讲 Plugins 启用。3.1 AGENTS.md 骨架AGENTS.md 是 Codex 在项目里开工前会读取的规则文件相当于一份工作手册。它告诉 AI你是谁、要什么风格、文件怎么放、哪些事不能做。很多人觉得 AI 不懂自己常见原因就是没写这份文件。在项目根目录新建 AGENTS.md把下面这份骨架复制进去按你的实际情况替换方括号内容# AGENTS.md — 项目工作手册 ## 1. 我是谁 - 身份[例独立开发者 / 后端工程师] - 主要业务[例做 SaaS 工具主语言 TypeScript] - 目标受众[例中小团队的技术负责人] ## 2. 输出要求 - 语言简体中文 - 文风直接、干脆不堆术语 - 文件命名日期_主题_版本例0610_codex教程_v1.md - 所有产出文件存到对应子目录不要散落在根目录 ## 3. 目录约定 - /src — 源码 - /docs — 文档与说明 - /scripts — 脚本与自动化任务 - /memory — 工作记录、复盘笔记 - 发现目录结构混乱时先整理再开工 ## 4. 工作原则 1. 接到任务先列计划确认后再执行 2. 改文件前先说明要改什么、为什么 3. 任务完成后报告生成/修改了哪些文件放在哪里 4. 不确定的事直接问我不要自己猜着做 5. 我纠正过的做法记进第 6 节 ## 5. 安全红线 - 永远不删除文件只移动到 /trash 目录 - 不碰本项目文件夹以外的任何文件 - 涉及发布、发送、花钱的操作必须先经我确认 ## 6. 我的偏好积累持续更新 - [例函数必须带类型注解] - [例报告先给结论再给过程]第 6 节最关键。每次你纠正 Codex比如“命名用下划线不用驼峰”“日志要带时间戳”都让它把这条规则写进第 6 节。下次做同类任务时它会先读规则再执行产出会越来越贴近你的习惯。不想手动写可以直接在 Codex 里说“帮我在项目里创建 AGENTS.md根据以下信息填写我的身份是……输出要求是……工作习惯是……”让它先生成你再检查修改。3.2 Skills 目录结构Skill 规定“怎么做”本质是一套写成文档的流程。你可以把固定步骤、格式要求、注意事项写进去之后每次调用它Codex 就按这套流程执行。适合沉淀成 Skill 的任务包括接口文档生成、周报整理、代码审查清单、部署脚本、测试用例模板。推荐的目录结构如下放在项目根目录的.codex/skills/下.codex/ └── skills/ ├── api-doc/ │ ├── SKILL.md │ └── template.md ├── code-review/ │ ├── SKILL.md │ └── checklist.md └── deploy/ ├── SKILL.md └── steps.md每个 Skill 目录下的 SKILL.md 是入口写清楚触发条件、执行步骤、输出格式。以 code-review 为例# SKILL: code-review ## 触发条件 当我说“审查这段代码”或“review 这个 PR”时启用。 ## 执行步骤 1. 读取目标文件列出改动范围 2. 按 checklist.md 逐项检查 3. 按严重程度分级阻断 / 建议 / 提示 4. 每条问题给出文件、行号、修改建议 ## 输出格式 - 先给结论是否可合并 - 再列问题清单按级别排序 - 最后给一条整体建议创建 Skill 时可以直接对 Codex 说“用 Skill Creator 帮我建一个 Skill生成接口文档要求包含请求参数、响应字段、错误码三部分输出 Markdown。”调用方式有两种输入/后选择 Skill 名称或用自然语言说“调用 code-review Skill 帮我审查这段代码”。3.3 Plugins 启用配置Plugin 决定“能连接什么”更像外部工具的通行证。安装后 Codex 可以连接 GitHub、Vercel、文档工具等服务。启用流程通常是打开 Plugins 面板搜索插件点击安装按提示授权回到项目中调用。常用插件按用途选择类别插件用途开发部署GitHub / Vercel代码托管、网站上线文档Document / Spreadsheet生成 Word、Excel浏览器Browser Use操作浏览器界面综合流程Superpowers规划、测试、产出不建议一次装太多。先装高频使用的其他用到再装插件太多会增加 AI 读取信息的负担。调用时在对话里输入选择指定插件例如document 帮我把这份分析整理成 Word 文档。4. 验证请求跑通一次完整任务配置写完必须验证。下面用“生成一份接口文档并审查”这个任务把 AGENTS.md、Skills、Plugins 串起来跑一遍。4.1 配置模型接入先在环境变量里配置 TaoToken 的 API Key 和入口地址。以 macOS/Linux 为例export TAOTOKEN_API_KEY你的Key export TAOTOKEN_BASE_URLhttps://taotoken.net/apiWindows PowerShell$env:TAOTOKEN_API_KEY你的Key $env:TAOTOKEN_BASE_URLhttps://taotoken.net/api配置完成后在 Codex 的设置里选择 API 方式接入填入上面的 Key 和地址。如果字段名称不确定对照接入文档逐项核对。4.2 发起验证请求在项目里新开一个对话输入任务读取 /src/api/user.ts用 api-doc Skill 生成接口文档 输出到 /docs/user-api.md完成后告诉我生成了哪些文件。预期行为Codex 先读 AGENTS.md确认目录约定和输出要求再调用 api-doc Skill按模板生成文档最后按工作原则第 3 条报告文件位置。4.3 检查成功结果任务完成后检查三件事第一文件是否落在/docs/user-api.md而不是根目录。第二文档是否包含请求参数、响应字段、错误码三部分。第三Codex 是否给出了文件清单报告。如果三项都符合说明 AGENTS.md 的目录约定和 Skill 的流程都生效了。接着追加一句用 code-review Skill 审查 /src/api/user.ts按阻断/建议/提示分级。这一步验证 Skill 的复用能力。两次任务都能按规则执行说明你的 Project 工作流已经跑通。4.4 多 Project 协作验证再建一个 Project把同一份 AGENTS.md 复制过去只改第 1 节的身份信息。然后在新 Project 里重复上面的任务。如果行为一致说明规则文件是可迁移的你可以在多个 Project 之间共享同一套工作流。5. 本篇常见错排查配置过程中最容易踩的坑集中在下面几类逐条对照排查。5.1 AGENTS.md 不生效现象Codex 依然乱放文件、不按格式输出。排查顺序确认文件名是 AGENTS.md大小写敏感确认放在项目根目录不是子目录确认没有多个同名文件冲突新开对话再试旧对话可能还带着旧上下文。5.2 Skill 调用不到现象输入/看不到自定义 Skill。排查确认目录是.codex/skills/不是skills/确认每个 Skill 有 SKILL.md 入口文件确认 SKILL.md 里的触发条件写清楚了重启 Codex 让它重新扫描目录。5.3 API Key 报错现象请求返回鉴权失败。排查确认 Key 没有多余空格确认 Base URL 是https://taotoken.net/api不要多加路径确认环境变量在当前终端会话里已生效可以用echo $TAOTOKEN_API_KEY检查如果刚创建 Key稍等片刻再试。5.4 上下文跑偏现象聊久了 Codex 开始忘记规则。原因是上下文快满了。建议在上下文接近 80% 时手动压缩输入/选择精简上下文。大项目把规划和执行分成两个对话第一个只讨论方案并输出方案文件第二个新对话只负责执行把方案文件路径丢进去。5.5 权限给太高现象Codex 动了项目文件夹以外的文件。排查把权限调回“请求批准”或“替我审批”在 AGENTS.md 第 5 节明确写“不碰本项目文件夹以外的任何文件”涉及删除、发布、付款的动作要求它先说明计划再执行。注意新项目、新插件先用低权限跑一段时间确认工作方式稳定后再考虑提高权限。6. 把规则养在本地接入日常开发到这里你已经有了 AGENTS.md 骨架、Skills 目录结构、Plugins 启用配置也跑通了一次完整任务。接下来要做的是让这套东西真正进入日常。第一件事把每周重复做的任务沉淀成 Skill。先让它完成任务对结果提修改意见满意后说“把我以上提出的所有修改意见收敛成一个 Skill命名为 XXX下次做同类任务直接照这个执行。”这套方法可以概括为个人化 → 系统化 → 自动化。第二件事把规则养在本地方便以后迁移。不同工具读取的规则文件名不同Codex 读 AGENTS.md其他工具可能读别的名字。如果每个文件单独维护时间久了容易不一致。解决方法是只维护一份核心规则文件其他文件用符号链接指向它。macOS/Linux 下ln -s CORE_RULES.md AGENTS.mdWindows PowerShellNew-Item -ItemType SymbolicLink -Path AGENTS.md -Target CORE_RULES.md验收方法在 CORE_RULES.md 里新增一行规则并保存再打开 AGENTS.md确认新增内容同步出现。注意这里要的是符号链接不是右键菜单里的“创建快捷方式”后者生成的是 .lnk 文件AI 不一定能正确读取。第三件事需要长期跑编码和 Agent 任务时把模型接入通道固定下来。TaoToken 的 Coding Plan 适合长期编码场景入口在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 想先验证模型效果可以用模型对话页面 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 快速试一轮接入配置和排障对照文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite Key 管理在 https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。如果你用 Claude Code 这类工具接入说明在 https://taotoken.net/claude-code-anthropic?utm_sourcetaotoken_aicg_blog_endutm_contentclaude-code-anthropicutm_campaignrewrite 。最后给一个实用技巧不要一次把所有功能都学完。先完成三步——建好第一个 Project 并写好 AGENTS.md、把每周重复的一个任务沉淀成 Skill、把模型接入通道固定下来。后续再逐步增加插件、定时任务和自动化流程。Codex 的价值不在于一次会多少功能而在于把重复工作持续沉淀下来让每个新 Project 都能复用同一套规则。