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然后记住这个位置。之后你再敲opencodebash 直接走哈希表不再查PATH。问题就出在这里。假设你后来用普通用户重装了 opencode新路径是/home/developer/.nvm/versions/node/v18.19.1/bin/opencodePATH也更新了。但当前这个 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 的作用是把模型调用统一到一个入口你只需要维护一份 Keyopencode 里配置一次就能用。官网入口在这里https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_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 或 fishhash -r是 bash 的写法zsh 用rehashfish 用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 节的四步走一遍基本五分钟内能定位。