1. 先别急着重装，opencode 启动失败多半是 PATH 和 hash 缓存在打架
hash -r是 bash 里一个很不起眼但特别关键的内建命令，它的作用是清空当前 shell 的命令路径缓存表。你敲下hash -r之后，bash 会丢掉之前记住的所有命令绝对路径，下一次执行命令时重新去PATH里逐个目录查找。这个机制本来是为了加速命令查找，但在你重装 opencode、切换 Node 版本、或者从 root 换到普通用户之后，它反而会变成"明明装好了却启动不了"的元凶。
这篇内容适合三类人：一是刚用 npm 或安装脚本装完 opencode，执行opencode --version却报 command not found 或直接卡住的人；二是切换过用户身份（比如从 root 切到 developer）后发现命令行为不一致的人；三是想把 opencode 接到统一 Key 网关、需要一份可复制配置骨架的人。核心检索词就是 hash -r、bash、opencode、PATH，我会从命令缓存机制讲起，给出 config.toml 和 settings.json 的骨架，再带上 TaoToken 统一 Key 的接入步骤，最后用hash -r后的验证动作收尾。
先说结论：opencode 启动失败，九成不是二进制坏了，而是 bash 的 hash 表里还留着旧路径，或者PATH里压根没有新装的 bin 目录。重装能解决一部分，但如果你不搞清楚 hash 表和 PATH 的优先级关系，下次换 Node 版本还会再踩一遍。
2. 命令缓存机制：bash 为什么"记仇"
bash 为了少做磁盘查找，会把已经执行过的命令的完整路径存进一张哈希表。你第一次敲opencode，它去PATH里找到/root/.opencode/bin/opencode，然后记住这个位置。之后你再敲opencode，bash 直接走哈希表，不再查PATH。
问题就出在这里。假设你后来用普通用户重装了 opencode，新路径是/home/developer/.nvm/versions/node/v18.19.1/bin/opencode，PATH也更新了。但当前这个 shell 的哈希表里还存着 root 时代的旧路径。bash 优先用哈希表，于是它去执行一个已经不存在或权限不对的文件，结果就是启动失败、报错、或者干脆没反应。
你可以用hash命令直接看当前缓存了什么：
hash输出里如果出现/root/.opencode/bin/opencode这类旧路径，基本就确诊了。hash -r就是清空这张表的开关，执行后 bash 会重新按PATH顺序查找。
注意：
hash -r只影响当前 shell 会话。你新开一个终端，哈希表本来就是空的，所以"新终端能用、当前终端不能用"是这类问题的典型特征。
3. TaoToken 前置：统一 Key 与接入地址
在动手改配置之前，先把 Key 和接入地址准备好，这样后面写 config.toml 和 settings.json 时不会来回翻文档。TaoToken 的作用是把模型调用统一到一个入口，你只需要维护一份 Key，opencode 里配置一次就能用。
官网入口在这里：https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，注册后在控制台生成 API Key。API 基础地址是 https://taotoken.net/api ，注意这个地址不带任何查询参数，直接作为 base_url 使用。
如果你只是想让 opencode 能对话、验证模型通不通，用模型对话页面就够了；如果你打算长期跑编码任务、接 Agent 工作流，建议直接看 Coding Plan，配额和调用方式更适合持续使用。Key 的生成和管理在 API Keys 页面，接入细节在接入文档里，这两个页面建议开着对照操作。
拿到 Key 之后，先别急着写进配置文件，用一条 curl 验证 Key 本身是通的：
curl https://taotoken.net/api/v1/models \ -H "Authorization: Bearer 你的_API_KEY"返回模型列表就说明 Key 和网络都没问题，接下来才是 opencode 的配置问题。这一步能帮你把"Key 错"和"PATH 错"两类故障分开，省得混在一起排查。
4. 可复制配置：config.toml 与 settings.json 骨架
opencode 的配置分两层：一层是工具本身的 config.toml，管模型提供方和默认行为；一层是 settings.json，管编辑器或运行时的偏好。下面这份骨架你可以直接复制，把 Key 和路径替换成自己的。
先看 config.toml：
# ~/.config/opencode/config.toml model = "claude-sonnet-4-20250514" provider = "taotoken" [providers.taotoken] base_url = "https://taotoken.net/api" api_key = "你的_API_KEY" api_type = "openai" [providers.taotoken.models] claude-sonnet-4-20250514 = { name = "Claude Sonnet 4" }再看 settings.json：
{ "opencode": { "provider": "taotoken", "baseUrl": "https://taotoken.net/api", "apiKey": "你的_API_KEY", "model": "claude-sonnet-4-20250514", "timeout": 60000 }, "editor": { "autoSave": true, "formatOnSave": true } }两个文件里的 base_url 和 baseUrl 都指向 https://taotoken.net/api ，不要加/v1后缀之外的路径，也不要带 UTM 参数，否则部分客户端会拼接出错误地址。Key 建议用环境变量注入，避免明文写死在文件里：
export TAOTOKEN_API_KEY="你的_API_KEY"然后在 config.toml 里写api_key = "${TAOTOKEN_API_KEY}"，opencode 支持这种占位符读取方式。这样你换 Key 的时候只改环境变量，配置文件不用动。
5. 验证请求：hash -r 后重新定位可执行文件
配置写完了，回到最开始的问题：怎么确认 opencode 真的能被找到、能启动。按下面顺序走一遍。
第一步，清空哈希表并重新查找：
hash -r which opencodewhich opencode应该输出类似/home/developer/.nvm/versions/node/v18.19.1/bin/opencode的路径。如果输出为空，说明PATH里没有这个目录，问题不在 hash 表，而在PATH本身。
第二步，检查 PATH 是否包含 opencode 的 bin 目录：
echo $PATH | tr ':' '\n' | grep -i opencode没有输出的话，把对应目录加进去：
export PATH="$HOME/.nvm/versions/node/v18.19.1/bin:$PATH"第三步，确认版本号：
opencode --version能打印版本号，说明命令定位成功。第四步，发一个真实请求验证 Key 和模型链路：
opencode run "用一句话说明 hash -r 的作用"如果返回了模型输出，整条链路就通了。如果这一步报鉴权错误，回到第 3 节用 curl 再验一次 Key；如果报连接超时，检查 base_url 是否写成了带 UTM 的地址。
提示：每次切换 Node 版本（比如 nvm use 18 换到 nvm use 20）之后，都建议执行一次
hash -r，因为 bin 目录路径变了，旧哈希表会指向失效路径。
6. 本篇常见错排查
报错一：bash: opencode: command not found，但which能找到。这是最典型的哈希表残留。执行hash -r后重试即可。如果还不行，检查当前 shell 是不是 zsh 或 fish，hash -r是 bash 的写法，zsh 用rehash，fish 用hash -r也支持但机制略有不同。
报错二：Permission denied。旧路径指向 root 安装的二进制，普通用户没有执行权限。hash -r清掉旧路径后，确保PATH里优先出现的是当前用户的 bin 目录。用ls -l $(which opencode)看权限位。
报错三：opencode 启动了但模型调用 401。这跟 PATH 无关，是 Key 或 base_url 的问题。确认 config.toml 里的 base_url 是 https://taotoken.net/api ，Key 没有多余空格，环境变量已经 export 到当前会话。
报错四：改了 config.toml 不生效。opencode 可能缓存了配置，重启进程或新开终端。另外确认配置文件路径正确，~/.config/opencode/config.toml是常见位置，但部分安装方式会读当前目录下的 config.toml，用opencode config path确认实际读取路径。
报错五：hash -r执行了还是找不到。说明PATH里确实没有 opencode 的 bin 目录，回到第 5 节第二步，把目录加进PATH并写进~/.bashrc持久化。
7. 把 Key 和路径一次理顺
排查到这一步，你应该已经能分清两类问题了：一类是 bash 哈希表残留导致的路径错乱，用hash -r加which验证就能定位；另一类是 Key 和 base_url 配置错误，用 curl 加opencode run就能验证。这两类问题经常同时出现，所以建议按"先 PATH 后 Key"的顺序排查，不要一上来就重装。
长期跑编码任务的话，把 Key 统一到 TaoToken 管理，config.toml 里只留一份 provider 配置，换模型只改 model 字段。需要生成或轮换 Key 的时候去 API Keys 页面，接入参数对照接入文档，模型验证用模型对话页面快速试，持续编码和 Agent 场景直接上 Coding Plan。这样你的 opencode 配置骨架就稳定了，下次再遇到hash -r之后启动失败，按第 5 节的四步走一遍，基本五分钟内能定位。
