1. 先搞清楚Codex 和“Agent 工具包”分别是什么Codex 是 OpenAI 推出的终端智能体工具装好之后你在终端里输入自然语言指令它能自己读代码、改文件、执行命令、循环排查直到把任务做完。很多人把它理解成“命令行版 ChatGPT”这个说法不算错但会错过它真正值钱的地方——它是运行在你自己项目环境里的 Agent能看到你的目录结构、能调用你的本地工具、能按你的项目规则干活而不只是生成一段文字让你自己复制粘贴。那“Agent 工具包”是啥通俗点说它是一套提前写好的“技能包”。Codex 有一个技能Skill机制你可以在指定目录下放一些 Markdown 描述文件每个文件就是一条能力规则。比如你写一个“Python 项目代码审查”技能Codex 在遇到相关任务时就会自动把技能里的检查清单、命名规范、禁止事项加载进来然后按你的规矩去执行。这相当于给 Agent 装了一本“行业手册”或者“团队工作流手册”。这套机制的价值在于模型再聪明它也不知道你们团队的 Git 提交规范、不知道你的项目目录结构约定、不知道哪些命令在你的机器上不能用。技能包就是把模型训练数据里没有的这部分“现场知识”提前交给 Agent让它每次干活都按照你的标准来。我在实际使用中最大的感受就是不装技能包之前Codex 像个能力很强但毫无纪律的新人装了技能包之后它才真正像是熟悉你项目的老同事。这篇教程适合三类人一是第一次装 Codex 的零基础用户照着抄就能跑通二是已经装了 Codex 但觉得它“不听话”、想深入了解技能系统的开发者三是想在团队里统一 Agent 行为的工程负责人。看完你不仅能装好工具包还会明白它的目录结构、配置文件里容易踩的坑、以及遇到报错时怎么一步步排查。2. 安装前的准备环境、凭据和一个干净的项目目录2.1 Node.js 和 npm 环境检查Codex CLI 目前主要通过 npm 分发所以第一步不是去网站下载 exe而是先确认你机器上的 Node.js 环境是正常的。打开终端依次执行node -v npm -v如果两条命令都能输出版本号说明 Node 环境没问题。Codex 对 Node 版本有最低要求建议使用 18 或者更高的 LTS 版本。旧版本会出现各种莫名其妙的报错不要在这里省事直接装新版最省心。如果你还没装 Node我建议用官方 LTS 安装包或者用 nvm 这类版本管理器来装。装完之后最好重新开一个终端窗口确保 PATH 生效。我见过不少人在 macOS 上装完 nvm 之后不重启终端导致npm命令一直找不到折腾了半天。2.2 登录认证的三种方式Codex 装好之后必须先完成认证才能调用模型。它支持三种方式你可以根据自己的情况选一种ChatGPT 账号登录终端执行codex login会弹出浏览器窗口让你授权适合日常个人使用。API Key 认证执行codex login --api-key然后粘贴你在平台申请的 API Key。这种方式适合脚本环境、CI 流程也适合你自己有 API 额度的情况。环境变量认证设置OPENAI_API_KEY环境变量Codex 会优先读它。适合临时容器、服务器等不方便存配置文件的场景。认证成功后Codex 会把你登录信息写到~/.codex/auth.json里。这个文件很关键后面排查“auth token is unavailable”这类报错时第一件事就是看它。这里多说一句无论用哪种方式都要确认你当前账号有可用的模型访问权限。很多人卡在第一步不是因为操作错误而是账号本身没有开通对应模型的访问资格。这种情况安装步骤再怎么重来都没用得先去确认账号权限。2.3 准备一个专门的项目目录我强烈建议你建一个干净的实验目录来跑安装和验证不要一上来就在公司主干项目里折腾。技能包需要在项目上下文里被触发一个空目录最容易验证“到底装没装成功”。mkdir codex-demo cd codex-demo后面装技能包、改配置、做验证都在这个目录里进行。跑通了再考虑搬到真实项目里这样能把变量控制到最少。3. 保姆级安装步骤从零到能用3.1 安装 Codex CLI环境没问题之后安装本身其实只有一条命令npm install -g openai/codex装完执行codex --version能输出版本号就说明 CLI 本体装好了。Windows 用户要注意npm 全局命令的安装目录不一定在 PATH 里如果codex命令找不到去查一下 npm 全局 bin 路径npm config get prefix并手动加到 PATH这一步是 Windows 上最常见的安装失败原因。macOS 和 Linux 上还有另一种用法不全局安装直接用npx codex临时跑。但我个人建议还是全局安装因为后面你会经常用到codex命令而且技能包的调试、exec 无头执行都依赖命令本身。3.2 获取 Agent 工具包Codex 本体只是一个底座Agent 工具包才是让 Agent 变“懂行”的关键。工具包的本质是一个技能仓库里面每个子目录对应一个技能。你可以从官方公开仓库获取基础技能集也可以从团队内部维护的 Git 仓库拉取甚至可以自己手工创建。git clone https://github.com/openai/agent-skills.git执行完你会得到一个agent-skills目录里面通常是一批按领域组织的技能目录比如代码审查、Git 协作、测试编写等。如果你所在团队已经有沉淀好的技能包那你 clone 的应该是内部仓库结构是类似的。这里有个关键点需要理解工具包不是“安装到 Codex 程序里”而是“放到 Codex 会扫描的 skills 目录下”。技能是纯 Markdown 加少量元数据文件不需要编译不需要依赖安装本质上就是复制目录。3.3 把技能放到正确的位置Codex 会扫描两个位置的 skills 目录全局位置~/.codex/skills/对所有项目生效适合放通用技能、团队规范类技能。项目位置项目根目录/.codex/skills/只对当前项目生效适合放项目专属的知识比如某个服务的架构说明、某个模块的命名约定。我推荐把通用技能放全局把项目相关的技能放在项目里。举个实际的例子团队统一的分支命名规范、代码审查清单放全局而“支付模块改动时必须要同步更新哪些文件”这种知识放在对应项目的.codex/skills里更有价值不会污染其他项目。复制技能很简单以全局位置为例mkdir -p ~/.codex/skills cp -r agent-skills/skills/* ~/.codex/skills/复制完之后每个技能目录里至少会有两个文件SKILL.md和AGENTS.json。SKILL.md是技能的核心正文里面写的是具体的行为规则和操作步骤用 Markdown 写模型会把它作为上下文的一部分来读AGENTS.json是技能的元数据包含技能名称、描述、适用场景when_to_use、触发关键词等信息。Agent 决定要不要用某个技能主要就看AGENTS.json里的描述和当前任务是否匹配。一个典型技能目录长这样~/.codex/skills/ └── code-review/ ├── AGENTS.json ├── SKILL.md └── scripts/ └── check_comments.pyscripts/不是必须的但当你需要在技能里跑一段固定的检查脚本时放在技能自己的目录里是最干净的做法。3.4 验证技能是否生效装完之后别急着干大活先用一个小任务验证技能确实被加载了。最简单的办法是写一个非常明显的技能然后让 Codex 执行相关任务看它有没有采用技能里的规则。比如我在~/.codex/skills/demo/下放了一个测试技能SKILL.md只有一句话“所有文件的文件名中必须把空格替换为下划线”然后新建一个不含空格的文件再让 Codex 创建一个文件名含空格的文件。如果它主动用下划线替代就说明技能生效了。用无头模式验证更省时间codex exec 创建一个名为 my demo file.txt 的文件然后看生成的文件名是不是my_demo_file.txt。如果是技能加载链路已经打通。这一步很重要因为很多人装完技能包之后从来没有验证过后面项目里出了奇怪行为才怀疑是技能的问题——但往往到头来发现技能文件里有个 JSON 语法错误Agent 悄悄把整个技能忽略了。4. 核心配置解析config.toml 里的关键参数4.1 配置文件在哪里、如何合并Codex 的配置文件叫config.toml同样分全局和项目两层全局路径是~/.codex/config.toml项目路径是项目/.codex/config.toml。两边的配置会合并项目层优先。如果你在某些目录下感觉 Codex 行为不一样多半是项目配置文件在起作用。这个文件的格式是 TOML写起来很直观。我用过之后最大的体会是不要一上来就堆一堆高深配置先把最基础的model、approval_policy这两项搞清楚后面再按需扩展。配置文件写错了Codex 启动时会有提示但不会阻止运行这点很多人不知道容易漏掉隐患。4.2 模型配置与 “model is not supported” 报错配置里最常见的键是model它决定 Codex 默认使用什么模型model gpt-5.4很多人在网上看到别人贴了一段配置里面写着某个具体的模型名直接复制过来用结果启动时遇到the gpt-5.6-sol model is not supported when using codex with a...这类报错。这类报错的本质通常是你正在用的认证方式比如 API Key所关联的账号没有这个模型的访问权限或者这个模型名只在特定订阅计划下可用。也就是说模型名本身没错错误的是“你当前的认证方式撑不起这个模型”。遇到这个问题先确认自己的账号类型和使用场景再回到文档里查哪个模型是当前认证方式可用的。不要盲目去改模型名也不要试图绕过权限校验——正确做法是选一个账号确实能用的模型或者在认证方式上做调整。改完配置记得重新打开终端或重启 Codex 会话配置才会重新加载。4.3 “unrecognized configuration setting” 的处理Codex 新版会对配置项做校验如果发现某个键它不认识会在终端里给你一条警告类似codex is ignoring 1 unrecognized configuration setting. check for typos or d...。这句话的意思是配置里有个键名写错了或者根本不存在Codex 忽略了它继续正常启动。这算是一个“善意提醒”但很多人把它当噪音忽略结果后来发现某个设置一直没生效比如组织 ID、审批策略配了没反应。排查方法很直接把配置文件里的自定义键逐个注释掉启动一次看看警告是否消失。通常问题出在键名的拼写上或者你把别的工具的配置项错误地抄进了 Codex 配置里。比如org_id、approval_policy这类键在不同版本里大小写略有差异改起来多对照官方配置样例。4.4 组织设置与多账号场景如果你用的是组织账号配置里需要体现组织关系。热词里有一条“codex无法加载组织设置”多半是下面几种情况配置里没写组织 IDCodex 默认按个人身份处理。写了组织 ID但当前登录的账号不在该组织成员列表里。认证信息过期导致组织信息拉取失败。在config.toml里可以这样指定组织org_id org-xxxxxxxxxxxx如果配了之后仍然提示加载失败先去网页端确认自己的账号确实在这个组织里、权限正常再检查~/.codex/auth.json是否正常。很多时候“无法加载组织设置”不是配置问题而是这个账号根本没有组织访问权限只是在终端里报了一个模糊的错误。另外如果你的机器系统时间不准会导致令牌校验失败这种脏坑我也踩过时间不同步时先对一下时间再折腾其他配置。4.5 接入第三方模型服务的配置思路Codex 支持通过model_providers配置自定义模型服务商这也就是热词里“codex接入deepseek”这类问题出现的场景。思路是在配置里声明一个自定义 provider指定它的接口地址、请求格式和 API Key 来源然后把默认模型切换成该 provider 的模型名。[model_providers.thirdparty] name thirdparty base_url https://example.com/v1 wire_api responses api_key_env_var THIRDPARTY_API_KEY model thirdparty/your-model-name这里有个容易被忽略的坑不同服务商的接口协议不一定和 Codex 兼容。Codex 支持wire_api的响应式responses和聊天补全式chat两种协议接第三方服务时先搞清楚对方支持哪种配错了会直接报 4xx 或者解析失败。我试过多次之后总结的经验是先拿 curl 手工调一次第三方服务的接口确认请求格式和响应结构是正常的再把它配进 Codex否则你很难区分是 Codex 的问题还是服务商接口的问题。5. 常见报错与排查实录5.1 auth token is unavailable这是新用户问得最多的问题之一报错信息很像codex auth token is unavailable。字面意思是认证令牌不可用。排查顺序如下看~/.codex/auth.json是否存在而且文件里确实有有效令牌。没有的话重新执行codex login。确认你确实用的是登录后生成的令牌而不是随手填进去的假字符串。有人手动改过这个文件格式坏了也会报这个错。检查环境变量是否污染了认证过程比如OPENAI_API_KEY设置了一个无效的 Key会让 Codex 放弃文件里的登录令牌。我遇到过一次特别隐蔽的情况终端里 export 过旧的OPENAI_API_KEYCodex 优先读了环境变量导致一直报令牌不可用。删掉环境变量之后一切正常。所以看到这个报错先别急着重新登录先自查环境变量。5.2 登录不上 / 无法加载组织设置这类问题通常是认证链路中间的某个环节断了。我做过的有效排查动作清掉旧的认证状态重新走一遍完整登录流程。确认系统时间准确。时间偏差过大会导致令牌签名校验失败登录成功但后续请求全部失败。如果用了组织账号去网页端确认组织 ID 和成员角色再回头对照配置里的org_id。登录报错经常是间歇性的第一次失败未必是配置问题。多试一两次如果仍然失败重点检查上面三条而不是盲目重装。5.3 Windows 环境设置未完成Windows 上的报错里有一条很典型可以概括为“设置未完成”。我排查过不少 Windows 用户的问题真正原因通常是这几种npm 全局 bin 目录没有加入 PATHcodex命令找不到。终端执行策略限制PowerShell 不允许运行 npm 的脚本文件需要放宽执行策略或者改用 CMD 测试。Codex 在某些功能上依赖系统组件比如需要确认 Windows 版本和更新满足要求。Windows 用户建议优先用 PowerShell 或者 Windows Terminal不要用旧版 CMD。装完 Node 之后打开新的终端窗口先跑codex --version这是最直接的验证。如果你需要长效使用还可以配置 Codex 桌面版桌面版和 CLI 共用同一套技能目录换端不影响已经装好的技能包。5.4 技能包不生效怎么排技能包放好了、看着也没报错但 Codex 就是不按技能来。这种问题我遇到过太多次排查顺序固定如下确认技能放在被扫描的路径下全局~/.codex/skills或项目.codex/skills。确认每个技能目录都有SKILL.md和AGENTS.json且AGENTS.json是合法 JSON。语法错误会让整个技能被静默忽略。确认AGENTS.json里的描述写得足够明确。描述写得含糊Agent 可能认为当前任务不匹配技能就不会被加载。技能更新之后重新启动 Codex 会话或者用codex exec跑一次无头任务来验证。我用一个表格把常见情况和对应处理方式整理一下方便你直接对照查现象可能原因处理方式技能完全没触发技能目录放错了位置检查全局和项目两个 skills 路径技能没触发但不报错AGENTS.json 语法错误检查 JSON 格式必要时用解析器验证技能触发了但行为不对SKILL.md 规则写得模糊把规则写成明确的“必须做/禁止做”句式改了技能没效果会话缓存了旧上下文重启 Codex 会话再用codex exec验证只有部分技能生效全局和项目技能冲突调整目录层级项目层优先级更高5.5 模型不可用类报错速查除了前面提到的model is not supported我顺手整理几个模型相关的常见问题报错或现象常见原因处理建议模型名提示不支持认证方式没有该模型权限换认证方式或换可用模型请求返回 404provider 配错了接口路径用 curl 验证 provider 接口响应解析失败wire_api 协议不匹配改成响应式或聊天补全式重试模型太慢选了超大参数模型换轻量模型处理简单任务6. 实操心得让技能包真正好用技术链路通了之后真正的功夫在写技能和用技能上。我把自己常用的几条心得分享给你这些是官方文档里通常不会写的东西。第一技能的触发描述AGENTS.json里的描述是灵魂。Agent 是拿这段描述去匹配用户任务的写得太专业、太少人懂技能就永远触发不了。我习惯写“什么时候该用这个技能”的场景描述而不是“这个技能有什么功能”的功能描述。比如代码审查技能的描述写成“当用户要求检查代码质量、发现潜在缺陷或者评审变更时使用”触发率明显比“提供代码审查能力”高得多。第二一个技能只干一件事。把十条规则塞进一个 SKILL.md表面看很省事实际上 Agent 面对一个具体任务时很难知道该用哪几条。拆成多个小技能让描述变得具体触发会更精准。技能文件可以共用公共规则但触发粒度要小。第三更新技能后一定要验证。我吃过一次亏改了一个提交规范技能以为没问题结果团队伙伴使用时报错排查半天发现是技能里的 Markdown 代码块没有闭合。从那之后我养成了习惯任何技能改动都先用codex exec跑一个最小用例验证再让其他人用。第四技能包要纳入版本管理。既然技能包决定 Agent 的行为那它和代码库一样需要被版本化、评审、发布。我建议团队把技能包单独放一个仓库变更走 Merge Request有人在里面夹带私货的变更一眼就能在评审里看出来。第五配置和技能一样需要“渐进式”扩展。不要第一次用就追求把所有参数配满。先把模型、认证、一个最小技能跑通再逐步加组织配置、自定义 provider、项目级技能。每个改动都做一次验证出了问题才能快速定位。最后说点我个人的总体感受。Codex 这类终端 Agent 的价值不是在于它能替你写多少代码而在于它能不能按照你的标准持续地产出。技能包的本质就是把你脑子里那些“老手才懂”的规则显性化成文件交给 Agent 去执行。装起来很简单但真正让它发挥威力的是你愿意花多少精力去打磨技能描述、丰富技能覆盖的场景。我第一次把团队规范整理成技能包之后Codex 产出的代码风格、提交信息、注释规范一下子统一了很多这种体验是装任何插件都给不了的。你先照着上面的流程把安装和验证跑通然后挑一个自己最熟悉的场景写一个最小技能试试。技能内容不用复杂一句话的规则也行关键是体会“你写规则、Agent 执行规则”这条链路。链路通了后面所有高级玩法都只是往这个框架里添砖加瓦而已。