我见过太多人把 Codex 用得像个玩具——拿它改两行报错、问几句 syntax，然后关掉窗口。说实话，这只是在浪费它真正值钱的那部分能力。Codex 真正拉开差距的地方，是它那个经常被人忽略的Skill（技能）机制：你可以在本地给它装各种"技能包"，让它在处理某类任务时自动切换思维模板、调用脚本、按固定流程办事。如果再顺手把 Jev 这类第三方模型服务接进来，整个 CLI 的实用性会往上跳一大截。
这篇文章我会用一套真实跑过的流程，讲清楚三件事：Skill 在 Codex 里到底是什么、怎么装、怎么写；Jev 这类 OpenAI 兼容模型服务怎么挂进 Codex；以及我实际跑了一周之后踩到的那些坑和完整的排查链路。适合正在用 Codex、或者正准备从聊天式 AI 编码工具转向"工作台式"用法的朋友。
1. 先搞清楚：Skill 到底在 Codex 里扮演什么角色
1.1 它不是传统插件，是一套"可复用的指令上下文"
很多人一听到 Skill，第一反应是"像 VS Code 插件一样的东西"，这个类比其实会误导你。Skill 更像你给新同事准备的那本《入职手册》：它不是一段随时驻留在内存里的代码，而是一份精心组织的文本（加上可选的脚本和资源），告诉模型"当你遇到这类请求时，你应该按什么流程、用什么标准、输出什么格式"。
Codex 加载 Skill 的机制是描述匹配。每个 Skill 文件夹里都有一个核心文件，通常叫SKILL.md，文件头部写清楚这个技能的名字和用途描述。当你输入的问题跟这个描述命中时，模型就会把这个文件的内容读进上下文，然后按照里面的步骤执行。换句话说，Skill 不是"装了就生效"，而是"被触发才生效"，这决定了你编写时要在描述上多花心思。
1.2 Skill 和 Agent 的区别，一句话讲透
热搜词里一直有人问"skill 和 agent 的区别"。我自己的理解很简单：Agent 一个会自己决定"下一步干什么"的调度器，Skill 是一份"遇到某类事就照着做"的规范手册。Agent 可以主动拆解目标、调用工具、循环验证；Skill 本身没有执行能力，它只是给模型提供高质量的约束和指令。实际工程里两者常常配合：Agent 负责规划，Skill 负责把某个具体环节的流程标准化。你在 Codex 场景下把 Skill 理解为"给模型喂的高质量指令包"就够了。
1.3 官方和第三方 Skill 的生态现状
目前官方提供了一些示例技能，社区里 GitHub 上也能搜到大量第三方 Skill 仓库，名字五花八门，有的封装代码评审，有的封装数学建模，甚至有人把一些专业课程的知识体系做成了 Skill。这里要提醒一句：装第三方 Skill 之前一定先看目录结构。一个规范的 Skill 至少要有完整的SKILL.md和清晰的描述；如果只有一个 README 扔进去，基本不顶用。我自己踩过这个坑，后面会细说。
2. 装 CLI 和 Skill 前，先把这几个环境细节准备好
2.1 安装方式：npm 全局装、官方安装包、Windows 桌面版
Codex 的安装路径现在比较杂，最常见的三种方式：
| 安装方式 | 适用场景 | 备注 |
|---|---|---|
| npm 全局安装 | macOS / Linux 开发者 | npm install -g @openai/codex，需要 Node.js 环境 |
| 官网下载安装包 | 不想碰命令行的用户 | 图形化安装，装完自带 CLI |
| Windows 桌面版 | Windows 用户 | 有独立客户端，但底层用的还是同一套 CLI |
建议统一用 npm 方式装命令行版本，因为 Skill 配置的调试大多在命令行里完成。装完之后先跑一次codex --version确认能正常输出版本号。
2.2 认证问题的真相："codex auth token is unavailable" 怎么处理
这个报错我见过太多次了，很多人的第一反应是重新安装，其实不用。这条报错的本质是 Codex 找不到一个有效的身份凭证。排查顺序就三步：
- 执行
codex login走一遍浏览器授权，确认账号状态正常。 - 检查环境变量里有没有残留的
OPENAI_API_KEY。如果你之前接其他工具时设置过它，而它的值又失效了，Codex 会优先读它，导致登录态被绕过。 - 如果上面两招都没用，再看
~/.codex/auth.json是不是损坏或者权限不对。
这里面最容易翻车的是第 2 步。很多人明明codex login成功了，但codex auth token is unavailable还是冒出来，十有八九就是那个环境变量在作怪。解决方式很简单：打开 shell 配置文件，把残留的OPENAI_API_KEY注释掉，重新开一个终端窗口再试。
2.3 Skill 目录：全局和项目级，别放错位置
Skill 的存放位置分两种：全局目录和项目级目录。全局目录是~/.codex/skills/，里面的技能对所有项目生效；项目级目录是.codex/skills/或者.codex/skill/（具体看版本），只对当前项目生效。
同一个 Skill 如果两边都放了，项目级会覆盖全局级。这个优先级规则我之前不知道，调试了很久，最后才发现是两边同名打架。
3. 手写一个最小可用 Skill：目录结构与 SKILL.md 的写法
3.1 最标准的目录长这样
拿一个代码评审技能举例，目录结构如下：
~/.codex/skills/code-review/ ├── SKILL.md └── scripts/ └── review.pySKILL.md是必有的，scripts/目录是可选的，用来放你想让模型调用的脚本。技能名用短横线连接（如code-review），里面不要带空格。
3.2 SKILL.md 的 frontmatter 与正文怎么写
SKILL.md的开头是 YAML 格式的前置信息，至少要有name和description，重点在 description，因为它决定了技能什么时候被触发：
--- name: code-review description: 当用户要求进行代码评审、代码审查、review PR 或检查代码质量时使用本技能。 --- # 代码评审流程 ## 目标 对给定代码进行系统性评审，输出可落地的修改建议。 ## 约束 - 只评审，不直接重写整段代码。 - 每个问题必须标注文件路径、行号和严重程度。 - 优先指出会导致错误、安全风险、性能退化的问题。 ## 执行步骤 1. 通读代码，梳理主流程。 2. 对照约束逐项检查。 3. 输出评审报告，格式为：问题描述 / 影响 / 修改建议。正文的核心原则是：目标、约束、执行步骤、输出格式，四样缺一不可。你越把模型当新员工带，它给出的结果越稳定。很多人的 Skill 不生效，不是因为 Codex 不支持，而是 SKILL.md 里全是废话，模型根本没提取到有效指令。
3.3 一个能直接用的 review.py 示例
脚本不是必须的，但如果你的 Skill 需要做文件操作、统计分析这类事情，写一个小脚本能省大量 token。下面这个review.py只做一件事：找出代码里超过指定长度的函数，作为评审材料的一部分。
import ast import sys from pathlib import Path THRESHOLD = int(sys.argv[1]) if len(sys.argv) > 1 else 80 def find_long_functions(filepath): tree = ast.parse(Path(filepath).read_text(encoding="utf-8")) for node in ast.walk(tree): if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)): length = node.end_lineno - node.lineno + 1 if length > THRESHOLD: yield f"{filepath}:{node.lineno} 函数 {node.name} 共 {length} 行" if __name__ == "__main__": for result in find_long_functions(sys.argv[2]): print(result)大家熟悉后可以逐渐给技能加更复杂的脚本，比如统计代码圈复杂度、提取 TODO 清单等，思路完全一样。
4. 把 Jev 这类第三方模型服务挂进 Codex：OpenAI 兼容接口的接入思路
4.1 为什么会有这种需求
Codex 默认用的是官方模型，但很多时候你想试试社区里口碑很好的第三方模型，比如 Jev。Jev 在社区里讨论最多的是两件事：一是它在部分推理任务上表现确实能打，二是它到底开不开放模型权重。对使用者来说，开源与否其实不关键，关键问题只有一个——它提供不提供 OpenAI 兼容接口。只要提供，理论上就能接入。
4.2 接入流程：申请密钥、配置环境变量、验证
整个接入过程不复杂，重点在配置细节。假设你已经申请到了 Jev 的 API Key（社区里常说的"jev密钥"），接下来这样做：
- 确认 Jev 服务方提供的接口地址，通常是
https://api.xxx.com/v1这样的格式。 - 在 shell 配置文件（
~/.zshrc或~/.bashrc）里写入：
export OPENAI_BASE_URL="你的 Jev 接口地址" export OPENAI_API_KEY="你的 Jev 密钥"- 重开终端，执行
codex，随便问一个问题，看模型是用 Jev 的接口响应的。
这里最关键的点是：Codex 正是通过OPENAI_BASE_URL这个环境变量把请求路由到第三方服务的。官方设计上留了这个口子，社区里接 DeepSeek、Qwen 走的也都是同一条路。
4.3 用同样的思路接 DeepSeek、Qwen 等模型服务
我把几个常见服务的接入要点整理成了表，方便参考：
| 服务 | 接口地址类型 | 密钥类型 | 接入注意点 |
|---|---|---|---|
| Jev | 需找服务方确认 | API Key | 确认路由路径带不带/v1 |
| DeepSeek | 官方文档获取 | API Key | 地址末尾斜杠不能乱加 |
| Qwen（通义千问） | DashScope 兼容端点 | API Key | 部分区域可能要单独开权限 |
不管接谁，验证方式都一样：改完环境变量，执行codex，观察回复，如果你输入的内容能正常得到响应，说明路由已经通了。
4.4 一个容易忽略的细节：密钥别写进全局配置再提交
很多人习惯把密钥直接写死在~/.zshrc里，这没问题，但不能把这个文件拖进 git 仓库。更稳妥的做法是单独维护一个.env文件，运行时加载：
set -a source ~/.codex/env set +a用 Jev 这类第三方服务时，密钥安全比官方场景更敏感，因为它相当于把你的账户凭证暴露在本地环境变量里。我的习惯是：只在当前终端会话里export，不写入全局配置，用完就关。
5. 跑了几天之后，我总结的这些坑和排查链路
5.1 "cc switch local proxy failed"：十有八九是本地转发服务的残留配置
有段时间我一打开 Codex 就报这条错，完整报文大致是cc switch local proxy failed while handling codex endpoint /responses。第一次遇到时我以为是 Codex 本身的问题，重装了一遍没解决。后来静下心排查，发现根因完全不在 Codex 上。
我的完整排查链路分享出来，照着走就行：
- 先看完整报错，不要只看第一行。终端里往上翻，找到它实际想请求的地址。
- 检查环境变量。执行
env | grep -i -E "proxy|base_url|http"，看看有没有以前配置其他工具时留下的转发服务变量（比如为调试本地服务设置的网关指向）。我那次就是变量指向了一个早已不存在的本地地址。 - 确认端口占用。如果变量指向
127.0.0.1:xxxx，用lsof -i :xxxx看一下这个端口还有没有服务在监听，没有就说明配置失效了。 - 清理残留配置。把对应变量注释或删除，重新开终端，报错消失。
这条报错我强调一下：它不是网络问题，更不是需要额外装什么工具的问题，百分之百是本地配置层的事。如果你也遇到，别在 Codex 配置里浪费时间，先排查环境变量。
5.2 "codex auth token is unavailable" 的二次排查
前面说了这套报错主要是认证失效，但还有一种更隐蔽的情况：你同时设置过OPENAI_API_KEY和通过codex login登录过，Codex 会优先读环境变量。而在接 Jev 这类第三方服务时，OPENAI_API_KEY会被改成 Jev 的密钥，这时候原本的官方登录态就相当于被"屏蔽"了。
这不是 bug，而是环境变量的优先级设计。如果你想在官方模型和第三方模型之间来回切换，最干净的做法是准备两套 shell 配置文件或者两个函数，切换时一次性替换两个变量，不要手动改一半留一半。我因为手动改漏过很多次，每次都费半天时间。
5.3 SKILL.md 太长导致上下文爆炸
Skill 文件不是越长越好。我最早写的评审技能有 300 多行，里面塞了各种边界情况。实际使用时发现，模型一命中技能就把整份文件读进去，还没开始干活，上下文就占了一大截，回答质量反而下降。
最佳实践是把 SKILL.md 控制在 100 行以内，把详细规则拆到scripts/或单独的参考文档里，需要时让模型按需读取。这与"给新员工手册"是同一个逻辑——手册应该精炼，细节留在附录。
5.4 同名 Skill 的覆盖问题
全局目录~/.codex/skills/code-review和项目目录.codex/skills/code-review同名时，项目目录优先级更高。有一阵我改了全局技能没生效，就是因为项目里躺着一个旧版本。排查办法很简单：执行codex skills list（部分版本叫codex skill list）查看当前生效的技能列表和路径，一目了然。
6. 从"用 Skill"到"写 Skill"：几组值得收藏的进阶玩法
6.1 把重复工作流封装成 Skill
很多人装完别人分享的 Skill 就满足了，但真正让 Codex 变得"顺手"的，是你把自己每周都在重复的流程固化成 Skill。随便举几个我身边的真实例子：
- 数学建模技能：把建模题的标准流程（问题抽象、假设、建模、求解、灵敏度分析）写进 SKILL.md，遇到竞赛题直接触发，输出结构非常稳定。
- 周报技能：要求模型根据本周 commit 记录和 PR 记录，按"做了什么 / 有什么问题 / 下周计划"三段式输出周报草稿。
- 技术方案评审技能：规定评审维度（架构合理性、数据一致性、异常处理、可运维性），每次评审都按这个框子走。
社区里还有各种奇怪名字的 Skill，有的叫book-to-skill，作用是把一本书的知识结构自动拆成技能笔记；有的把特定领域课程做成技能包。这些玩法本质上都一样：把你的方法论文本化，喂给模型。
6.2 带脚本的 Skill：让模型能真正执行动作
前面code-review里的review.py是纯文本辅助脚本，更进阶的玩法是让模型通过脚本和外部系统交互。比如封装一个"批量检测重复代码"的技能，其中放一个 Python 脚本，模型识别到场景后就执行脚本，再把结果整理成报告输出。
这里有个重要的安全约束，习惯要提前养成：
注意：凡是带执行脚本的 Skill，必须在 SKILL.md 里写明"执行前需用户确认"，并把危险的命令（删除文件、覆盖数据、发请求）明确列为禁止项。模型对脚本的执行不像人那么有分寸，约束必须写在技能文件里。
6.3 Skill 的迭代思路：先小后大
我自己的迭代流程是：先拿一两个真实任务跑，看输出离预期差多远；然后修改 SKILL.md 里的约束或步骤，再跑，一次只改一个变量。千万不要一上来追求"全都考虑到"，那样写出来的 Skill 基本不可用。
个人建议给首个自写 Skill 选一个你最有把握、重复频率最高的场景——比如代码提交信息生成。领域足够窄，你能立刻看出来它有没有用，也方便对比改进。等这个跑通了，你自然会理解 Skill 的设计哲学，再写复杂的就轻车熟路了。
最后再分享一个我实际用下来很有效的小技巧：在 SKILL.md 正文第一行写一句"遇到本技能描述范围内的请求时，必须严格按以下流程执行，不要跳过任何一步"。这句话看着简单，但它在模型逻辑里相当于一个强触发信号，能让技能被命中的概率和稳定性都提升不少。装好 Skill、接好模型之后，Codex 就不再是那个"问一句答一句"的聊天框了，你会明显感觉到它在往"半自动工作台"的方向变化。这种体验，值得你花一下午折腾。
