排查 | RouteMux

RouteMux Agent Skills 常见问题的解决办法 —— 看不到 key、需要先充值、权限提示、skill 重复 —— 以及怎么更新和卸载。

skill 出错时会把原因打印出来。在下面找到对应的提示就行。

常见报错

你看到的	意思	怎么办
`ROUTEMUX_API_KEY is not set`	agent 看不到你的 key	见 agent 看不到 key
`AUTH_INVALID_API_KEY`	RouteMux 不认这把 key	检查 key；或者新建一把，更新 `ROUTEMUX_API_KEY`
`RMX-MODEL-3018` / `MODEL_REQUIRES_TOPUP`	出图和视频模型要在账号首次充值后才解锁	充值任意金额，再说一遍
`RMX-BILLING-5001`	余额不够这次请求	充值。视频也可以改短一点或用 `768P`，花得更少
`RMX-LIMIT-4004`	这把 key 今天的出图张数用完了	等 UTC 00:00 重置。之前重试也会再失败
`RMX-LIMIT-4005`	全平台暂停了出图	稍后再试 —— 最晚 UTC 00:00 自动恢复。视频和对话不受影响
Codex 请你批准联网	skill 要用 `curl` 调 RouteMux API	批准即可。见 Codex
Claude Code 问能否执行 Bash 命令	skill 要跑一个小脚本	允许即可
Claude Code 里每个 skill 都出现两遍	插件和 npx 都装了	见 skill 重复

skill 只从环境变量 ROUTEMUX_API_KEY 读 key。

先确认终端里有它（这条命令不会把 key 打印出来）：
```
[ -n "$ROUTEMUX_API_KEY" ] && echo set || echo missing
```
如果输出 missing，把下面这行加到 ~/.zshrc（zsh）或 ~/.bashrc（bash），再新开一个终端：
```
export ROUTEMUX_API_KEY='sk-...'
```
从这个终端启动 agent。从这里启动的 agent 会继承这把 key。

从程序坞（Dock）或桌面启动器打开的 agent 不读你的 shell 配置文件，所以可能看不到 key。改从终端启动就好；如果 agent 还是看不到 key，就把它写进 agent 自己的配置，然后重启 agent：

Claude Code —— 加到 ~/.claude/settings.json 的 env 里：

{
  "env": {
    "ROUTEMUX_API_KEY": "sk-..."
  }
}

Codex —— 加到 ~/.codex/config.toml 的 [shell_environment_policy] 下：

[shell_environment_policy]
set = { ROUTEMUX_API_KEY = "sk-..." }

这样 key 就以明文存在这个文件里，和写在 shell 配置文件里一样。

skills 放在哪。 Codex 从 ~/.agents/skills 读用户级 skills，不读 ~/.codex/skills。 npx 命令和安装脚本都会装到这里。如果你是手动复制的，挪到 ~/.agents/skills。
装完要重启。 Codex 启动时才加载新的 skills。
怎么调用。 输入 $routemux-images 或 $routemux-video，或者直接用大白话说。
批准联网。 skill 第一次跑 curl 时，Codex 可能请你批准联网。点批准；或者在 ~/.codex/config.toml 里一次性放开：
```
[sandbox_workspace_write]
network_access = true
```

如果 Claude Code 里每个 skill 都出现两遍，说明你既装了插件，又用 npx（或脚本）装过一遍。留一种就行：

npx： 再跑一遍安装命令 —— npx skills add https://routemux.com -g
安装脚本： 再跑一遍 —— curl -fsSL https://routemux.com/.well-known/agent-skills/install.sh | sh
Claude Code 插件： 运行 /plugin marketplace update routemux，或者在 /plugin 里给这个 marketplace 打开自动更新。
手动下载： 从清单重新下载 zip。

Claude Code 插件： /plugin uninstall routemux@routemux
其他方式： 删掉 agent 的 skills 目录里的 routemux-* 文件夹。用 npx 装的，~/.agents/skills 里的也要删 —— npx 把文件放在那里，再链接到其他 agent 的目录。

如果这台机器上不再需要 key，把 shell 配置文件里那行 export ROUTEMUX_API_KEY=... 也删掉。