1. Codex 0.118.0 移除 Custom Prompt 后Slash Prompt Router 到底解决了什么问题如果你最近把 Codex CLI 升到了 0.118.0然后习惯性地敲下/handover或者/git:commit-push大概率会看到一段让人心里一凉的提示找不到对应的 prompt。这不是你的配置写错了而是 Codex 0.118.0 在 PR #16115 里正式移除了对 Custom Prompt 的发现与罗列支持。换句话说你放在~/.codex/prompts/目录下那些精心打磨的 Markdown 提示词官方核心流程不再主动扫描、不再自动注册成斜杠命令了。这件事对谁影响最大三类人首当其冲。第一类是重度依赖自定义工作流的 Codex CLI 用户他们过去把架构分析、代码简化、错误排查、会话交接这些高频动作全部沉淀成了 prompt 文件靠一个斜杠命令触发。第二类是 AI Agent 开发者他们的编排逻辑里假设了 prompt 会被自动发现现在这个假设不成立了。第三类是团队里负责工程效率的工程师他们维护着一套共享的 prompt 库升级后整条链路断掉。Slash Prompt Router 就是在这个背景下出现的。它不是一个官方补丁而是基于 Codex 现有的 Skill 机制孵化出来的一个路由层。核心思路很直接既然官方不再扫描~/.codex/prompts/*.md那就由 Skill 自己来扫描、自己来匹配、自己来加载执行。它把「资产盘点、意图匹配、加载执行」这三件事重新接管回来让那些变成孤岛的本地提示词重新可用。我实测下来它比原来的原生支持还多了一层能力语义推荐。以前你必须精确记住命令名现在你可以说「我想梳理前端的 API 调用链」Router 会扫描目录、打分排序、给出候选列表。这对记不住命令名的场景非常友好。这篇文章面向的是已经升级到 0.118.0、正在寻找迁移路径的开发者。我会先讲清楚架构变化再给出可复制的路由配置片段、Skill 注册示例最后用真实的报错场景带你走一遍回滚验证。整个过程的每一步都可以直接跟做。需要说明的是Router 本身是一个本地 Skill它调用模型能力时需要一个稳定的 API 入口。我在配置里用的是 TaoToken 的 API 地址这样 Router 在做意图匹配和参数解析时不会因为网络问题卡住。下面会给出完整的配置片段。2. Slash Prompt Router 的架构拆解与 Skill 注册前置准备要理解 Router 为什么能平替原生功能得先看清楚 Codex 0.118.0 到底改了什么。在旧版本里Codex 启动时会扫描~/.codex/prompts/目录把每个.md文件解析成一个斜杠命令命令名来自文件名参数占位符$ARGUMENTS、$1到$9由核心流程负责替换。0.118.0 之后这套发现逻辑被移除了核心不再维护日益臃肿的 prompt 发现代码把扩展能力下放给了 Skill 系统。这个变化从架构上看是减负但对用户来说是断轴。Router 的定位就是补上这个断层。它的工作流分三步资产盘点阶段动态扫描并解析~/.codex/prompts/*.md提取文件名、标题、描述等元信息意图匹配阶段当用户提出模糊需求时用一套轻量评分策略推荐候选加载执行阶段接管参数解析把选定的 prompt 作为当前任务的执行纲领。意图匹配这块值得展开说。Router 没有引入向量数据库而是用混合文本评分。英文侧用正则[a-z0-9][a-z0-9:-]*提取技术词汇比如git、commit。中文侧用 CJK 字符检测加双字 N-Gram 分块「分析架构」会被切成「分析」「析架」「架构」这样不依赖外部中文分词库也能保证召回。评分维度有三档命名命中加 30 分标题命中加 15 分描述命中加 5 分。粗排能在几百毫秒内从几十个 prompt 里筛出 Top 5再交给决策流做精细选择。参数绑定是另一个关键。$ARGUMENTS会把用户输入的整段任务描述作为完整字符串注入适合/ui-engineer这种需要大段背景的工作流。位置参数$1到$9用于精确场景比如/kill-port 3000会自动映射第一个参数。如果参数缺失Agent 会主动询问补齐。这实际上是把 Markdown 编译成了动态执行计划。在动手之前你需要准备三样东西。第一是 Codex CLI 0.118.0 或更高版本用codex --version确认。第二是~/.codex/prompts/目录下至少有一个.md提示词文件如果没有可以先建一个测试用的。第三是一个可用的模型 API 入口Router 在匹配和解析时需要调用模型。我用的配置里 Base URL 指向https://taotoken.net/apiKey 在控制台生成Model ID 按你实际使用的填。这里要强调一个容易踩的坑Router 是 Skill不是 Codex 核心的一部分所以它的注册方式和普通 prompt 不同。你需要把 Router 的 Skill 定义放到 Codex 能识别的位置通常是~/.codex/skills/目录。注册时三件套必须齐全Base URL、API Key、Model ID。缺任何一个Router 在调用模型做意图匹配时都会失败。下面一节我会给出完整的可复制配置。3. 可复制的 Slash Prompt Router 配置与 Skill 注册片段这一节是全文最核心的部分所有片段都可以直接复制到你的环境里。先给目录结构再给配置文件最后给 Skill 注册示例。目录结构建议这样组织~/.codex/ ├── prompts/ │ ├── handover.md │ ├── git:commit-push.md │ └── api-flow-analyzer.md ├── skills/ │ └── slash-prompt-router/ │ ├── SKILL.md │ └── catalog_prompts.py └── config.tomlconfig.toml是 Codex 的主配置Router 需要的模型入口在这里声明。注意路径和字段名要和你的实际环境一致# ~/.codex/config.toml model your-model-id model_provider taotoken [model_providers.taotoken] name TaoToken base_url https://taotoken.net/api env_key TAOTOKEN_API_KEY [skills] enabled true skill_dirs [~/.codex/skills]API Key 不要硬编码在配置文件里用环境变量注入export TAOTOKEN_API_KEYsk-你的实际Key如果你用的是 Codex 的auth.json方式管理凭据对应片段如下注意 Base URL 和 Model ID 要和上面保持一致{ providers: { taotoken: { base_url: https://taotoken.net/api, api_key_env: TAOTOKEN_API_KEY, model: your-model-id } } }接下来是 Skill 注册。SKILL.md是 Router 的入口定义它告诉 Codex 这个 Skill 叫什么、什么时候触发、需要哪些参数--- name: slash-prompt-router description: 扫描本地 prompts 目录根据用户意图推荐并加载最合适的提示词 trigger: 当用户输入斜杠命令或提出模糊的 prompt 需求时 --- # Slash Prompt Router ## 能力 - 扫描 ~/.codex/prompts/*.md - 对用户查询做混合文本评分 - 返回 Top 5 候选并加载执行 ## 参数 - query: 用户的原始输入 - top_k: 返回候选数量默认 5catalog_prompts.py是评分引擎的核心下面是一个可运行的精简版本保留了命名命中、标题命中、描述命中三档评分import os import re from pathlib import Path PROMPT_DIR Path.home() / .codex / prompts def extract_tokens(text): en_tokens re.findall(r[a-z0-9][a-z0-9:-]*, text.lower()) cjk_chars re.findall(r[\u4e00-\u9fff], text) bigrams [cjk_chars[i] cjk_chars[i1] for i in range(len(cjk_chars)-1)] return set(en_tokens bigrams) def score_prompt(query_tokens, name, title, desc): score 0 name_tokens extract_tokens(name) title_tokens extract_tokens(title) desc_tokens extract_tokens(desc) if query_tokens name_tokens: score 30 if query_tokens title_tokens: score 15 if query_tokens desc_tokens: score 5 return score def catalog(query, top_k5): query_tokens extract_tokens(query) results [] for md in PROMPT_DIR.glob(*.md): content md.read_text(encodingutf-8) title content.splitlines()[0] if content else desc content[:200] s score_prompt(query_tokens, md.stem, title, desc) if s 0: results.append((s, md.stem)) results.sort(reverseTrue) return results[:top_k] if __name__ __main__: import sys q sys.argv[1] if len(sys.argv) 1 else for s, name in catalog(q): print(f{s}\t/{name})这个脚本可以直接用python catalog_prompts.py 梳理前端 API 调用链测试。如果输出里出现了/api-flow-analyzer且分数最高说明评分逻辑工作正常。参数绑定部分Router 在执行时会拦截$ARGUMENTS和$1到$9。你可以在 prompt 文件里这样写# git:commit-push 请把以下修改提交并推送$ARGUMENTS 如果用户指定了分支使用 $1 作为目标分支。当用户输入/git:commit-push 把刚才的修改提交了Router 会把「把刚才的修改提交了」注入$ARGUMENTS然后接管后续流程。配置完成后用codex skills list确认 Router 已被识别。如果列表里没有检查skill_dirs路径是否写对以及SKILL.md的 frontmatter 格式是否正确。这一步做完就可以进入验证环节了。4. 验证请求与成功结果从模糊查询到精确执行配置写完不代表能用必须跑一遍验证。我建议按三个场景依次测每个场景都有明确的预期结果方便你判断哪一环出了问题。场景一模糊探索。在 Codex 对话框里输入我想梳理前端的 API 调用链推荐几个合适的 prompt预期行为是 Router 扫描~/.codex/prompts/识别到api-flow-analyzer和analyze-complexity由于前者的描述高度匹配作为首选推荐并列出所需参数。如果 Router 返回了候选列表但排序不对说明评分权重需要调整可以先把命名命中的 30 分调高到 40 分试试。场景二精确制导。输入直接用 /git:commit-push 帮我把刚才的修改提交了预期行为是 Router 跳过推荐环节直接加载该 prompt把「把刚才的修改提交了」解析为$ARGUMENTS注入随后接管提交流程。这一步验证的是参数绑定是否生效。如果提交时提示参数为空检查 prompt 文件里$ARGUMENTS的拼写注意是全大写。场景三无缝交接。输入/handover预期行为是读取handover.md执行内部定义的生成交接文档指令最终在根目录输出HANDOVER.md。这一步验证的是文件加载和执行链路。如果你想在命令行层面验证 Router 的评分引擎可以直接跑python ~/.codex/skills/slash-prompt-router/catalog_prompts.py handover成功输出类似30 handover 15 git:commit-push分数在前、命令名在后用 Tab 分隔。如果输出为空说明PROMPT_DIR路径不对或者你的 prompt 文件里没有任何 token 和查询匹配。验证模型调用是否通畅可以用一个最小请求测 API 入口curl -s https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d { model: your-model-id, messages: [{role: user, content: ping}] }返回里能看到choices字段就说明 API 入口正常。如果这里就失败了Router 的意图匹配一定也会失败先解决这一层。三个场景都通过后你的 Router 就算迁移完成了。但实际使用中还会遇到一些报错下一节我把常见的几个列出来对照排查。5. 常见报错排查401、local proxy failed、reading choices 与 OAuth这一节按真实报错来组织每个报错给出原因和修复步骤。这些是我在迁移过程中实际遇到过的你可以对照自己的日志定位。第一个401 Unauthorized。这是最常见的通常出现在 Router 调用模型做意图匹配时。原因有三个可能API Key 没设置、Key 过期、或者环境变量名和配置文件里的env_key不一致。排查步骤是先确认环境变量存在echo $TAOTOKEN_API_KEY如果输出为空说明没导出。如果输出有值但仍然是 401检查config.toml里env_key写的是不是TAOTOKEN_API_KEY大小写要完全一致。还有一种情况是你用了auth.json方式但api_key_env指向的变量名和实际导出的不一样。第二个local proxy failed。这个报错说明 Codex 尝试走本地代理但连接失败。注意这里说的代理是 Codex 自身的网络配置不是让你去配置任何外部网络工具。排查方向是检查config.toml里有没有残留的 proxy 配置项如果有就删掉让请求直连base_url。另外确认base_url写的是https://taotoken.net/api不要多加或少加路径段。第三个reading choices 相关报错典型形式是cannot read property choices of undefined或者reading choices。这说明 API 返回的结构和预期不符通常是返回了一个错误对象而不是正常的 completion 响应。排查步骤是先用上一节的 curl 命令直接测 API看返回体里有没有choices。如果没有看返回体里的error字段通常是模型 ID 写错了。确认model字段和你在控制台看到的 Model ID 完全一致。第四个OAuth 相关报错。如果你之前用 OAuth 方式登录过 Codex升级后可能残留了旧的凭据缓存导致 Router 在调用时走了错误的认证路径。修复方式是清理旧的凭据缓存改用 API Key 方式。具体操作是找到 Codex 的凭据存储位置通常在~/.codex/下把旧的 OAuth token 文件移走或删除然后重新用TAOTOKEN_API_KEY环境变量认证。这里要特别提醒Router 注册时三件套必须齐全Base URL、API Key、Model ID 缺一不可。很多报错追根溯源都是这三样里有一个没配对。我建议在排查任何问题之前先把这三样对照一遍。如果遇到 Skill 没有被识别的情况报错可能是skill not found或unknown command。检查~/.codex/skills/slash-prompt-router/SKILL.md是否存在frontmatter 里的name字段是否和你在对话里调用的名字一致。另外确认config.toml里skills.enabled是true。回滚验证也是排查的一部分。如果你怀疑是 Router 本身的问题可以临时禁用 Skill看原生行为是否恢复[skills] enabled false禁用后重启 Codex如果斜杠命令仍然不可用说明问题不在 Router而在 Codex 0.118.0 本身的移除行为。这时候重新启用 Skill回到 Router 方案。排查完这些你的调用链路应该就稳定了。最后说一下长期使用的建议。6. 把 Slash Prompt Router 接入日常编码与 Agent 编排迁移完成后Router 不只是一个临时补丁它可以成为你 Agent 编排的稳定底座。我自己的用法是把高频工作流全部沉淀成 prompt 文件然后用 Router 做统一入口。这样即使 Codex 后续再有破坏性更新只要 Skill 机制还在我的工作流就不会断。对于长期编码和 Agent 场景我建议把模型调用统一走一个稳定的入口。TaoToken 的 Coding Plan 适合这种持续调用的场景模型对话入口可以用来单独验证某个 prompt 的效果接入文档里有完整的参数说明。如果你需要生成和管理 API Key控制台里可以操作。Claude Code 相关的接入也有对应的文档可以参考。具体到日常使用我推荐几个对话范式。模糊探索时直接描述需求让 Router 推荐候选比如「我想找一个能分析代码复杂度的 prompt」。精确执行时直接用斜杠命令加参数比如/kill-port 3000。会话交接时用/handoverRouter 会生成交接文档下次接着干。一个实用技巧是定期清理~/.codex/prompts/目录。prompt 文件多了之后评分引擎的粗排虽然快但候选质量会下降。我一般保持目录里不超过 30 个文件过期的就归档到子目录Router 只扫描顶层。另一个技巧是给 prompt 文件写清晰的标题和描述。评分策略里标题命中加 15 分、描述命中加 5 分这两个字段直接影响推荐准确率。标题写成人能看懂的一句话描述写清楚适用场景和需要的参数。如果你在团队里共享 prompt 库可以把~/.codex/prompts/做成 git 仓库每个人拉取后 Router 自动扫描。这样团队的工作流就统一了新人入职拉一下仓库就能用上全套斜杠命令。最后一步验证你的 Router 在真实任务里能跑通。找一个你平时常用的 prompt用模糊查询触发它确认 Router 推荐正确、参数注入正确、执行结果正确。这三步都过了你的迁移就算彻底完成。整个过程的核心就是官方关了一扇门Skill 机制开了一扇窗Router 就是那个把窗变成门的东西。