1. Opencode 启动失败与命令找不到从环境变量到 PowerShell 执行策略的完整排查Opencode 是一个跑在终端里的 AI 编码助手能读项目文件、改代码、执行命令适合习惯命令行工作流的开发者。它的安装方式主要是通过 npm 全局包所以绝大多数“启动失败”并不是 Opencode 本身的问题而是 Node.js 环境、PATH 变量、PowerShell 执行策略这三层里有一层没打通。我按实际排障顺序把每一层的检查命令和修复动作拆开你可以对着自己的终端一步步比对。1.1 先确认 Node.js 与 npm 是否真的可用很多人遇到opencode报“不是内部或外部命令”第一反应是重装 Opencode其实应该先看 Node 环境。打开一个新的命令提示符或 PowerShell分别执行node -v npm -v正常情况会输出类似v22.14.0和10.9.2。如果这两条命令本身都报“不是内部或外部命令”说明 Node.js 没装好或者装了但没进 PATH。Opencode 强制要求 Node.js v22.0.0 及以上低于这个版本安装过程会直接失败所以版本号也要看清楚。如果确认装过 Node.js 但命令不可用去“此电脑 → 属性 → 高级系统设置 → 环境变量”检查用户变量和系统变量里的Path是否包含 Node.js 安装目录常见是C:\Program Files\nodejs\。最省事的做法是卸载后重新安装 LTS 版本安装向导里务必勾选 “Add to PATH”。改完 PATH 后要关掉所有旧终端重新开一个再测旧窗口不会自动刷新环境变量。1.2 安装慢或失败时换镜像源并清缓存默认 npm 源在境外国内下载 Opencode 这种带依赖的包很容易卡住或超时。安装时直接指定镜像npm install -g opencode-ai --registryhttps://registry.npmmirror.com如果之前装到一半失败过缓存里可能留下损坏的分片先清再装npm cache clean --force npm install -g opencode-ai --registryhttps://registry.npmmirror.comWindows 上全局安装还可能因为权限不足失败。用管理员身份打开 PowerShell 再执行安装或者把 npm 全局目录改到用户目录下npm config set prefix C:\Users\你的用户名\AppData\Roaming\npm改完 prefix 后这个路径必须同步加进 PATH否则装完还是找不到命令。这一点和下一节的 PATH 排查是连着的。1.3 安装成功但 opencode 命令找不到npm install -g opencode-ai显示成功输入opencode却提示找不到本质是 npm 全局可执行文件目录没进 PATH。先查出这个目录在哪npm config get prefixWindows 下通常输出C:\Users\你的用户名\AppData\Roaming\npm。把这个路径加到用户变量Path里保存后重开终端再验证opencode --version能打印版本号就说明通了。如果你用 nvm 切换过 Node 版本每个版本对应的全局目录不同切版本后 PATH 可能指向旧目录需要重新确认。临时用一下也可以走 npxnpx opencode-ai但 npx 每次都要重新解析包频繁使用还是把 PATH 修好更省事。1.4 PowerShell 禁止运行脚本导致命令被拦在 PowerShell 里执行 npm 或 opencode 时可能遇到“无法加载文件……因为在此系统上禁止运行脚本”。这是 PowerShell 默认执行策略Restricted拦住了.ps1脚本。以管理员身份打开 PowerShell改成RemoteSignedSet-ExecutionPolicy RemoteSigned Get-ExecutionPolicy确认输出为RemoteSigned后关掉重开一个普通 PowerShell 再测npm -v。如果没有管理员权限可以只改当前用户Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser只想临时调试可以在当前窗口用进程级绕过关窗即恢复Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass这三档按权限从高到低选优先用RemoteSigned不要长期挂在Unrestricted上。1.5 ENAMETOOLONG 与 uv_spawn 报错的清理路径执行 Opencode 读写文件时如果报Error: ENAMETOOLONG: name too long, uv_spawn多半是 npx 缓存膨胀或项目路径太深。先清 npm 缓存npm cache clean --force不够彻底就手动删 npx 缓存目录Windows 下在C:\Users\你的用户名\AppData\Local\npx-cache删掉整个文件夹再重试。项目路径过深也会触发把工程挪到D:\projects\my-app这种浅目录。Windows 还可以开启长路径支持在组策略里启用 Win32 长路径或把注册表HKLM\SYSTEM\CurrentControlSet\Control\FileSystem下的LongPathsEnabled设为 1重启生效。如果只在某个项目里报错删掉该项目的node_modules和package-lock.json重装通常能解决。2. TaoToken 前置配置给 Opencode 接上稳定的模型调用通道Opencode 本身只是客户端真正干活的是背后调用的模型。默认走官方通道时国内网络下经常出现超时、连接重置、响应中断表现就是 Opencode 里发出去没反应或者报网络错误。把模型调用切到 TaoToken 的兼容接口能明显减少这类抖动。这一节先把 Key 和 Base URL 准备好下一节再写进 Opencode 的配置文件。2.1 注册并创建 API Key打开官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注册登录后进入控制台。在 API Keys 页面创建一个新的 Key复制出来先存到安全的地方。这个 Key 就是后面配置文件里的apiKey字段泄露了要立刻在控制台吊销重建。创建 Key 的直达入口是 https://taotoken.net/console/api-keys 登录后点新建即可。注意 Key 只在创建时完整显示一次关掉弹窗就看不到了所以复制动作要当场完成。2.2 确认 Base URL 与模型 IDTaoToken 提供 OpenAI 兼容接口Base URL 是https://taotoken.net/api注意这个地址后面不加 UTM 参数配置里写干净的这一条就行。模型 ID 按你实际要用的填比如claude-sonnet-4-5、gpt-4o这类具体以控制台模型列表里显示的为准。Opencode 的配置里需要同时写对 Base URL、API Key、Model ID 这三件套缺一个都会导致调用失败。如果你还没决定用哪个模型可以先到模型对话页面试一下https://taotoken.net/model-chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite 在网页里发几条消息确认通道正常再写进 Opencode 配置能少走弯路。2.3 长期编码场景选 Coding Plan如果你打算把 Opencode 当日常主力编码工具频繁调用模型可以看一下 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 。它面向长期编码和 Agent 类高频场景比按次调用更适合持续使用的开发者。选之前先估算自己每天的请求量再决定用哪种方式。2.4 把 Key 写进环境变量而不是硬编码不管后面配置写在哪都建议把 Key 放进环境变量而不是直接写死在文件里。Windows 下可以setx TAOTOKEN_API_KEY 你的KeymacOS / Linux 写进~/.zshrc或~/.bashrcexport TAOTOKEN_API_KEY你的Key改完重开终端。这样配置文件里引用变量名即可换 Key 时只改一处也不容易在分享配置时把 Key 带出去。3. 可复制配置Opencode 接入 TaoToken 的完整 settings 片段这一节给出可以直接粘贴的配置。Opencode 的配置目录在用户目录下的.config/opencodeWindows 是C:\Users\你的用户名\.config\opencodemacOS / Linux 是~/.config/opencode。目录不存在就手动建。下面分两部分模型通道配置和中文交互配置。3.1 模型通道配置片段在配置目录下创建或编辑opencode.json部分版本用config.json以你安装版本的文档为准写入{ provider: { taotoken: { type: openai, baseURL: https://taotoken.net/api, apiKey: {env:TAOTOKEN_API_KEY}, models: { claude-sonnet-4-5: { name: Claude Sonnet 4.5 }, gpt-4o: { name: GPT-4o } } } }, model: taotoken/claude-sonnet-4-5 }这里baseURL写的是不带 UTM 的干净地址apiKey用{env:TAOTOKEN_API_KEY}引用环境变量避免明文。model字段指定默认使用的模型格式是provider/model。如果你用 TOML 风格配置等价写法是[provider.taotoken] type openai baseURL https://taotoken.net/api apiKey {env:TAOTOKEN_API_KEY} [provider.taotoken.models.claude-sonnet-4-5] name Claude Sonnet 4.5 [provider.taotoken.models.gpt-4o] name GPT-4o model taotoken/claude-sonnet-4-5两种格式选一种不要混用。保存后重启 Opencode 让配置生效。3.2 中文交互配置 AGENTS.mdOpencode 默认用英文思考和回答想切成中文在同一个配置目录下建AGENTS.md## 交互要求 1. 你在处理所有问题时全程思考过程必须使用中文包括需求分析、逻辑拆解、方案选择、步骤推导等所有内部推理环节 2. 最终输出的所有回答内容包括文字解释、代码注释、步骤说明等必须全部使用中文仅代码语法本身的英文关键词除外。保存后重启会话。如果只想让某个项目用中文把这个文件放到项目根目录效果一样。想恢复英文删掉或改名即可。3.3 验证配置是否被正确加载配置写完后先别急着跑复杂任务。在 Opencode 里发一句简单的中文提问比如“用一句话说明这个项目是做什么的”。如果回答是中文说明AGENTS.md生效如果报模型连接错误说明opencode.json里的 Base URL 或 Key 有问题。也可以直接看启动日志Opencode 启动时会打印加载的 provider 和 skills 数量对照一下你配的 provider 名字有没有出现。4. 验证请求与成功结果从一次真实调用看配置是否打通配置写完必须验证否则后面出问题分不清是配置错还是网络错。这一节用一次完整的调用过程把每一步的预期结果写清楚你照着比对就能判断卡在哪。4.1 用 curl 先验证通道本身在写进 Opencode 之前先用 curl 直接打 TaoToken 的接口排除 Opencode 配置层的干扰curl https://taotoken.net/api/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -d { model: claude-sonnet-4-5, messages: [{role: user, content: 回复两个字正常}] }预期返回是一段 JSONchoices[0].message.content里能看到“正常”。如果返回 401说明 Key 不对或没带上如果连接超时说明网络层有问题如果返回模型不存在说明 model ID 写错了。这一步通了再进 Opencode 验证。4.2 在 Opencode 里发起一次真实编码请求打开一个测试项目目录启动 Opencodecd D:\projects\demo opencode在交互界面里输入“读取当前目录的 package.json告诉我项目名称和依赖数量。” 预期结果是 Opencode 调用模型读取文件然后用中文回答出项目名和依赖数。这个过程同时验证了三件事模型通道通、文件读取权限正常、中文配置生效。4.3 观察响应时间与中断情况正常调用下简单请求几秒内返回复杂任务按 token 量递增。如果频繁出现响应到一半中断或者长时间无输出后报连接错误多半是通道不稳定。这时候回到 4.1 的 curl 多打几次看是否稳定复现。如果 curl 稳定而 Opencode 不稳定检查 Opencode 是否配了额外的超时参数或代理设置。4.4 成功结果的判断标准一次成功的调用应该满足curl 返回 200 且内容正确Opencode 能读取项目文件并给出中文回答连续发三条请求都不中断。三条都过说明配置和通道都没问题可以进入日常使用。任何一条不过按下一节的报错对照表定位。5. 本篇常见错排查401、local proxy failed、reading choices 与 OAuth 逐项对照这一节把实际排障中最高频的几类报错列出来每条给出触发原因和修复动作。你遇到报错时直接对号入座。5.1 401 Unauthorized报错长这样Error: 401 Unauthorized {error:{message:Invalid API key provided}}原因通常是 Key 写错、Key 已吊销、或者环境变量没被读到。先确认环境变量在当前终端可见echo $TAOTOKEN_API_KEYWindows PowerShell 用echo $env:TAOTOKEN_API_KEY。如果输出为空说明环境变量没生效重开终端或重新setx。如果输出正常但 Opencode 仍报 401检查配置文件里apiKey字段是不是写成了字面量{env:TAOTOKEN_API_KEY}而没被解析部分版本需要确认环境变量插值语法。最后去控制台确认这个 Key 还在有效状态。5.2 local proxy failed报错类似Error: local proxy failed: connect ECONNREFUSED 127.0.0.1:7890这是本地配了代理但代理没启动或者代理端口变了。检查 npm 和系统的代理设置npm config get proxy npm config get https-proxy如果输出了代理地址但你并不需要直接删掉npm config delete proxy npm config delete https-proxy同时检查系统环境变量里的HTTP_PROXY/HTTPS_PROXY不需要就清掉。清完重开终端再试。5.3 reading choices 报错报错类似TypeError: Cannot read properties of undefined (reading choices)这是接口返回结构不符合预期代码去读choices时拿到 undefined。常见原因是 Base URL 写错比如漏了/v1或写成了网页地址。确认配置里是https://taotoken.net/api请求路径由客户端自动拼/v1/chat/completions。如果 Base URL 多写了/v1拼出来就重复了。另外模型 ID 不存在时部分接口返回的错误结构里没有choices也会触发这个报错对照控制台模型列表核对 ID。5.4 OAuth 相关报错如果 Opencode 某些功能走 OAuth 登录报错类似Error: OAuth token expired or invalid这类问题通常和模型通道无关是客户端登录态过期。按提示重新登录即可。如果你只用 API Key 方式接入 TaoToken不涉及 OAuth可以忽略这类报错确认自己没误开需要登录的功能模块。5.5 配置三件套自查表出现任何调用类报错先按这张表核对检查项正确值常见错误Base URLhttps://taotoken.net/api多写/v1、写成网页地址API Key环境变量引用或控制台复制的 Key明文写错、Key 已吊销Model ID控制台模型列表里的 ID拼写错误、用了不存在的模型三件套都对还报错再回到第 4 节的 curl 验证通道本身。6. 继续接入与验证按场景选对入口排障和配置都通了之后日常使用中还会遇到需要查文档、换模型、或者升级到长期方案的情况。按你的实际场景选对应入口能少翻很多无关内容。如果你在排查接入问题需要重新生成 Key 或核对配置字段走 API Keys 页面https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 配合接入文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 对照字段说明。如果你只是想验证某个模型在当前通道下能不能正常回答用模型对话页面最快https://taotoken.net/model-chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite 不用改任何本地配置就能测。如果你已经把 Opencode 当主力工具每天大量调用考虑 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 它更适合长期编码和 Agent 场景。最后补一个实际经验Opencode 的配置改完后一定要重启会话很多“改了没生效”的情况只是旧进程还在用旧配置。另外把opencode.json和AGENTS.md一起纳入项目的版本管理Key 用环境变量引用不要提交明文换机器时直接拉下来就能用比每次重新配省事得多。