1. 多 Repo 多 CLI 场景下，OpenClaw 为什么总走错路

如果你同时维护三五个本地仓库，又装了 Claude Code、Codex、OpenCode、Cursor 里的两三个，那你大概率经历过这种场面：明明知道这个 auth bug 该在 api 仓库里改，却要先翻终端历史找路径；明明记得某个项目里写过 build_and_test 这个 skill，却想不起来它挂在哪个 CLI 的目录下；你想把 OpenClaw 当成统一入口，结果真正执行时还是得手动切到对应的 CLI。

问题的根子不在模型能力，而在入口碎片化。OpenClaw 本身是个很好的对话入口，但它默认并不知道你的 api 别名指向哪个绝对路径，也不知道那个仓库里已经沉淀了哪些 project-level skill 和 agent。于是每次任务都要靠你在对话里补全上下文，补得越细越像在写工单，补得越粗就越容易路由到错误的仓库。

ClawRouter 要解决的就是这一层。它不替代 OpenClaw，也不重造 Claude Code、Codex、Cursor、OpenCode，而是作为一个 OpenClaw 原生 skill 落在~/.openclaw/skills/router/，在真正调用原生 CLI 之前，先把「这个任务属于哪个 repo、这个 repo 有没有现成 skill 或 agent、这个场景更适合哪个 CLI」这三件事定下来。一句话概括就是：OpenClaw 管入口，ClawRouter 管路由，原生 CLI 管执行。

它和那些重型 orchestration 平台的定位完全不同。有的项目擅长并行 fan-out 让多个模型同时 review，有的擅长 worktree、PR 生命周期和 CI 自动修复，有的擅长看板和长期任务流转。这些都很强，但心智负担也重。ClawRouter 反过来，先把最高频、最影响效率的那层导航问题解决掉，不引入额外后台调度服务，不要求你先建看板配 worktree 生命周期。

判断你的项目要不要引入路由层，可以问自己三个问题：你是不是已经把 OpenClaw 当主要入口？你是不是同时用两个以上 AI coding CLI？你是不是有多个本地 repo 且经常在它们之间切换？三个里中两个，路由层带来的收益就会明显大于配置成本。反过来，如果你只需要同一个任务并行跑三五个 CLI 做结果共识，或者要全自动的 PR/CI 生命周期，那 ClawRouter 更适合放在前面做入口和路由，后面再接别的重型项目。

2. TaoToken 前置：给 ClawRouter 一个稳定的模型出口

ClawRouter 负责把请求路由到正确的 repo、skill 和 CLI，但路由决策本身、以及后续 CLI 里的模型调用，都需要一个稳定的模型出口。这一步我用 TaoToken 来做，原因是它把多模型调用收敛成一个 Base URL 加一个 Key，配置一次就能被 OpenClaw 和各个原生 CLI 复用，不用在每个工具里各配一套。

先把 Key 拿到。打开 https://taotoken.net/api-keys ，登录后创建一个 API Key，复制出来先存到临时文件里，后面配置要用。注意这个 Key 只在创建时完整显示一次，页面刷新后就看不到了，所以别急着关标签页。

然后确认你要用的模型 ID。打开 https://taotoken.net/models 可以看到当前可用的模型列表，把你要在 ClawRouter 和 CLI 里用的那个 Model ID 记下来，比如常见的对话模型或编码模型。Model ID 是大小写敏感的，复制的时候别手抖。

TaoToken 的 API 入口是 https://taotoken.net/api ，这个地址在下面所有配置里都会用到。它兼容 OpenAI 风格的接口，所以 OpenClaw、Claude Code、Codex、Cline 这类工具基本都能直接填 Base URL 加 Key 的方式接进来。

如果你只是想先验证模型通不通，不用装任何 CLI，直接打开 https://taotoken.net/model-chat 在网页里发一条消息，能正常返回就说明 Key 和模型都没问题。这一步能帮你把「Key 错了」和「CLI 配置错了」两类问题提前分开，省掉后面很多来回排查。

如果你打算长期用 OpenClaw 做编码和 Agent 任务，而不是临时试一下，那更划算的做法是直接上 Coding Plan，把额度固定下来，避免每次任务跑到一半因为额度问题中断。入口在 https://taotoken.net/coding-plan ，具体档位按你的日常任务量选就行。

配置文档在 https://taotoken.net/doc ，里面有针对不同工具的接入说明，遇到字段名对不上的时候可以对照着看。下面第三节我会给出可直接复制的配置片段，你照着填自己的 Key 和 Model ID 即可。

3. 可复制配置：repo_mappings.json 与 CLI 三件套

这一节是全文最需要动手的部分。ClawRouter 的路由能力，一半来自它自己的匹配逻辑，一半来自你给它的结构化 repo 目录。核心文件是~/.openclaw/skills/router/references/repo_mappings.json，安装后先打开看一眼，然后按你的实际情况补全。

先看这个文件的结构。它不再是简单的路径列表，而是一个可导航的 repo catalog，每个条目包含 name、path、aliases、skills、agents 四类信息。下面是一份可以直接改的示例：

{ "repos": [ { "name": "api-service", "path": "/Users/you/work/api-service", "aliases": ["api", "backend", "auth-svc"], "skills": ["build_and_test", "db_migrate"], "agents": ["bugfix", "reviewer"] }, { "name": "admin-web", "path": "/Users/you/work/admin-web", "aliases": ["admin", "console"], "skills": ["build_and_test"], "agents": ["ui-fix"] }, { "name": "docs-site", "path": "/Users/you/work/docs-site", "aliases": ["docs", "doc"], "skills": [], "agents": [] } ], "cli_priority": ["claude-code", "codex", "opencode", "cursor"], "fallback_repo": "api-service" }

几个字段的用法说明一下。aliases 是你平时在对话里会随口说的简称，比如你说「fix the auth bug in the api project」，Router 就是靠api这个 alias 命中 api-service 的。skills 和 agents 是自动检测出来的摘要，安装器会扫描各 CLI 的原生目录，但检测结果不一定完全符合你的项目实际，所以建议手动核对一遍。cli_priority 决定当多个 CLI 都能执行时按什么顺序选，fallback_repo 是当 alias 和 repo 名都没命中时的兜底。

ClawRouter 的匹配顺序是：先看 repo 是否命中，再看 alias 是否命中，然后看该 repo 是否检测到项目级 skill，再看是否检测到项目级 agent，只有这些都不够可靠时才走全局和 fallback。这个顺序让行为更可预测，也更接近真实团队项目的工作方式——和 repo 强绑定的资产，优先级本来就该高于全局通用 helper。

接下来是 CLI 三件套。不管你用哪个 CLI，接入 TaoToken 都是 Base URL、Key、Model ID 这三样。以 Claude Code 为例，配置文件在~/.claude/settings.json，写入：

{ "env": { "ANTHROPIC_BASE_URL": "https://taotoken.net/api", "ANTHROPIC_AUTH_TOKEN": "sk-你的Key", "ANTHROPIC_MODEL": "你的ModelID" } }

Codex 的配置在~/.codex/auth.json和~/.codex/config.toml，auth.json 里放 Key：

{ "OPENAI_API_KEY": "sk-你的Key" }

config.toml 里放 Base URL 和 Model ID：

model_provider = "taotoken" model = "你的ModelID" [model_providers.taotoken] name = "TaoToken" base_url = "https://taotoken.net/api" wire_api = "chat"

Cline 这类 VS Code 插件则在设置面板里选 OpenAI Compatible，Base URL 填https://taotoken.net/api，API Key 填你的 Key，Model ID 填你记下的那个。三件套填齐，CLI 才能正常发起请求，缺任何一个都会在验证阶段报错。

4. 验证请求：一次命中 Repo、Skill 与 CLI

配置写完，别急着上真实任务，先用一个最小请求验证路由链路。打开 OpenClaw，输入这样一句话：

fix the auth bug in the api project, use the repo's build_and_test skill

预期行为是这样的：Router 先通过api命中 api-service 这个 repo alias，然后在 repo_mappings.json 的对应条目里看到已检测的build_and_testskill，接着看到该 repo 下还存在bugfixagent，最后根据 cli_priority 选中最合适的执行路径，调用原生 CLI 执行。整个过程你只发了一句话，导航动作全部收进了这一次对话里。

验证的时候重点看三件事。第一，Router 有没有正确解析出 repo。如果它回问「你说的 api 是指哪个仓库」，说明 alias 没配好或者拼写不一致。第二，它有没有识别到 project-level skill。如果它忽略了 build_and_test 直接走通用流程，说明 skills 字段没填对，或者自动检测的结果和实际不符。第三，最终调用的是不是你期望的 CLI。如果顺序不对，调整 cli_priority 即可。

再补一个验证模型出口的步骤。在 OpenClaw 里直接发一条普通对话，或者在对应 CLI 里跑一个最小任务，看请求能不能正常返回。如果返回正常，说明 TaoToken 的 Base URL、Key、Model ID 三件套都通了。如果这一步就失败，那问题在模型出口，不在路由层，先按第五节排查。

实测下来，最容易出问题的不是 Router 的匹配逻辑，而是 repo_mappings.json 里的路径写错。比如 path 写成了相对路径，或者 aliases 里用了中文简称，都会导致命中失败。建议每次改完这个文件，都用上面那句测试请求跑一遍，确认命中结果符合预期再上真实任务。

5. 本篇常见错排查：401、local proxy failed 与 reading choices

配置过程中最常见的几类报错，我按出现频率排一下，对照着查能省不少时间。

第一类是 401 Unauthorized。这个基本可以锁定在 Key 上。检查三件事：Key 是不是复制完整了，有没有多复制了空格或换行；Key 有没有过期或被删除；auth.json 或 settings.json 里的字段名是不是写对了，比如 Claude Code 用的是ANTHROPIC_AUTH_TOKEN而不是OPENAI_API_KEY。如果 Key 确认没问题还是 401，去 https://taotoken.net/api-keys 重新生成一个再试。

第二类是 local proxy failed 或连接被拒绝。这类报错通常出现在 Base URL 上。确认你填的是https://taotoken.net/api，注意结尾不要多加/v1之类的路径，也不要漏掉https。有些工具会自动在 Base URL 后面拼/chat/completions，如果你手动填了完整路径就会拼成双份，导致 404 或连接失败。另外检查一下本地网络有没有拦截，公司网络环境下有时候需要确认出口策略。

第三类是 reading choices 相关的报错，比如返回体里找不到 choices 字段。这通常是 Model ID 写错了，或者用了当前账号没有权限的模型。去 https://taotoken.net/models 核对一下 Model ID 的拼写，注意大小写。如果 Model ID 没问题，检查一下 wire_api 的配置，Codex 的 config.toml 里要写wire_api = "chat"，写成别的值可能导致响应格式对不上。

第四类是 OAuth 相关的报错。如果你之前用官方账号登录过某个 CLI，它可能缓存了旧的凭证，导致新配置不生效。这时候需要清掉旧的登录态，比如 Claude Code 可以重新走一次配置流程覆盖 settings.json，Codex 检查 auth.json 有没有被旧内容覆盖。清完之后重启 CLI 再试。

第五类是 Router 命中错误但没有任何报错。这种最隐蔽，表现是任务跑完了但改错了仓库。排查方法是打开~/.openclaw/skills/router/references/repo_mappings.json，确认 aliases 里没有重复的简称指向不同 repo，path 都是绝对路径且真实存在。如果两个 repo 的 alias 撞了，Router 会按文件里的顺序取第一个，这往往不是你想要的。

排查顺序建议从模型出口往路由层走：先用网页对话确认 Key 和模型通，再在 CLI 里跑最小任务确认三件套通，最后用测试请求确认路由命中正确。这样每一层的问题都能被单独隔离出来，不用在一堆报错里猜。

6. 把路由层接进你的日常编码流

ClawRouter 的价值不在于它有多重，而在于它正好卡在一个很多人已经开始痛、但还没被很好填平的位置上。你不需要先建复杂看板，不需要配一堆 worktree 生命周期，也不需要接入 PR 机器人，只要把 repo_mappings.json 里的 alias、skills、agents 补准，OpenClaw 就能在真正执行前自动导航到最合适的路径。

安装和配置的入口我放在这里，方便你直接跟做。模型对话验证用 https://taotoken.net/model-chat ，API Key 在 https://taotoken.net/api-keys ，接入文档在 https://taotoken.net/doc ，长期编码和 Agent 任务走 https://taotoken.net/coding-plan 。Claude Code 相关的接入说明在 https://taotoken.net/ClaudeCodeAnthropic ，控制台在 https://taotoken.net/console 。

最后给一个实用建议：先把 repo_mappings.json 里最常用的两三个 repo 配好，alias 用你平时说话时最自然的简称，别为了「规范」硬造一套你自己都记不住的命名。配完跑一遍第四节那句测试请求，确认命中结果符合直觉，再逐步把剩下的 repo 补进来。路由层这东西，配得越贴近你的真实说话习惯，用起来越顺手。