1. 为什么 OpenCode 安装总在第一步卡住OpenCode 是一款跑在终端里的开源 AI 编程代理它不绑定编辑器支持接入 75 种以上模型用 Plan 和 Build 双模式帮你先规划再写代码。适合谁适合那些习惯在命令行里干活、又不想被某一家模型厂商锁死的开发者。但很多人第一次装它卡住的不是功能而是安装本身——Windows 上脚本跑不动macOS 上 brew 装完版本对不上Linux 上权限和 PATH 折腾半天。我自己在三个系统上都装过一遍踩的坑基本集中在三处一是网络拉取二进制失败二是 PATH 没配好导致opencode命令找不到三是装完不知道怎么把模型通道切到统一的 Key 上。这篇就把 Windows、macOS、Linux 三端的四种安装路径拆开讲每种都给可复制的命令最后演示怎么把 API endpoint 改到 TaoToken 的统一通道并验证模型调用真的通了。先明确一个前提OpenCode 本身不带模型你装的是一个 Agent 框架。所以安装分两步——先把 CLI 装进系统再配置模型接入。很多人只做了第一步就以为完事了结果运行起来发现没有模型可用。下面四种方式覆盖包管理器、脚本、二进制、容器你可以按自己的系统挑一种。2. TaoToken 前置准备与统一 Key 获取在动手装 OpenCode 之前先把模型通道准备好这样装完就能直接验证不用来回切换。TaoToken 提供统一的 API 通道一个 Key 可以调用多种模型省去你在 OpenCode 里逐个配置 provider 的麻烦。第一步打开官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注册账号。注册流程很常规邮箱加密码收个验证邮件就完事。第二步进控制台创建 API Key。地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 在 API Keys 页面点新建复制那串以sk-开头的 Key。注意这个 Key 只显示一次先存到安全的地方。第三步记下两个关键信息Base URL 是https://taotoken.net/apiModel ID 用你打算调用的模型名比如claude-sonnet-4-5或gpt-4o。这三个东西——Base URL、Key、Model ID——就是后面配置 OpenCode 的三件套缺一不可。如果你还没想好用什么模型可以先到模型对话页面 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite 试几个看看哪个响应风格合你胃口再决定写进配置里。这一步花两分钟能省掉后面反复改配置的时间。3. 四种安装方式的可复制配置3.1 一键脚本安装macOS / Linux / WSL 首选官方推荐的方式一条命令搞定curl -fsSL https://opencode.ai/install | bash脚本会自动检测系统和架构下载对应二进制解压后配置 PATH。安装目录按优先级选择$OPENCODE_INSTALL_DIR、$XDG_BIN_DIR、$HOME/bin、$HOME/.opencode/bin。装完执行opencode --version能看到版本号就说明成功了。如果你在 Windows 上强烈建议先装 WSL然后在 WSL 终端里跑这条命令体验和 Linux 完全一致。原生 PowerShell 跑这个脚本兼容性差一截。3.2 包管理器安装各平台原生macOS 用 Homebrew官方 Tap 更新最快brew install anomalyco/tap/opencodeWindows 用 Scoop 或 Chocolateyscoop install opencode choco install opencodeArch Linux 用 pacman 或 AURsudo pacman -S opencode paru -S opencode-bin包管理器的好处是卸载干净、依赖自动处理缺点是源更新可能滞后。急着用最新功能的话脚本或 npm 更快。3.3 npm 安装Node.js 开发者已经有 Node.js 18 环境的话这条最顺手npm install -g opencode-ailatest升级也简单npm update -g opencode-ai就行。如果提示npm: command not found说明 Node.js 没装或没进 PATH先去 nodejs.org 装一个。3.4 容器方式隔离环境不想污染本机环境可以用 Docker 跑docker run -it --rm -v $(pwd):/workspace -w /workspace ghcr.io/opencode-ai/opencode:latest容器方式适合临时试用或 CI 环境但要注意把工作目录挂载进去否则 Agent 看不到你的项目文件。装完 CLI 后配置模型接入。OpenCode 的配置文件在~/.config/opencode/config.json写入以下内容{ provider: { taotoken: { type: openai, baseURL: https://taotoken.net/api, apiKey: sk-你的Key, models: { claude-sonnet-4-5: {}, gpt-4o: {} } } }, model: taotoken/claude-sonnet-4-5 }这里type填openai是因为 TaoToken 的接口兼容 OpenAI 格式baseURL指向https://taotoken.net/apiapiKey填你刚才复制的 Keymodel指定默认使用的模型。三件套齐了OpenCode 就知道去哪调模型。4. 验证请求与成功结果配置写完进项目目录跑一次验证。先确认版本opencode --version然后启动交互模式opencode进去后输入一句测试指令比如「帮我看看当前目录有哪些文件」。如果配置正确你会看到模型返回的文件列表分析。这时候说明 Base URL、Key、Model ID 三件套都生效了。想更直接地验证 API 通道可以用 curl 单独测一次curl https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer sk-你的Key \ -H Content-Type: application/json \ -d {model:claude-sonnet-4-5,messages:[{role:user,content:ping}]}返回里有choices字段和模型回复内容就说明通道通了。这一步能帮你区分是 OpenCode 配置问题还是 Key 本身的问题。成功的结果长这样OpenCode 启动后显示当前模型名你输入指令后几秒内返回结果没有报错弹窗。如果卡住不动多半是网络或 Key 的问题往下看排障部分。5. 本篇常见错误排查报错一401 Unauthorized最常见。原因通常是 Key 填错、Key 过期、或者baseURL写成了带/v1的路径。检查配置里baseURL是不是https://taotoken.net/api不要多加/v1。Key 确认是sk-开头且没有多余空格。报错二local proxy failed / connection refused说明 OpenCode 尝试连本地代理但失败了。检查你的环境变量里有没有HTTP_PROXY或HTTPS_PROXY指向一个没启动的本地端口。有的话先清掉或者确认代理服务在跑。报错三reading choices: unexpected end of JSON input这个通常是 API 返回了非 JSON 内容比如 HTML 错误页。原因可能是baseURL写错导致请求打到了错误地址或者 Key 无效被网关拦截返回了 HTML。用上面的 curl 命令单独测一次看返回的原始内容是什么。报错四OAuth 相关错误如果你之前配过其他 provider 的 OAuth残留的 token 可能干扰。检查~/.config/opencode/下有没有旧的 auth 文件清掉后重新用 Key 方式配置。报错五opencode: command not foundPATH 没配好。脚本安装的话确认$HOME/.opencode/bin或$HOME/bin在 PATH 里。npm 安装的话确认 npm 全局 bin 目录在 PATH 里。临时解决可以export PATH$HOME/.opencode/bin:$PATH永久解决写进.bashrc或.zshrc。排查顺序建议先 curl 测 Key再查配置文件最后看环境变量。这样能快速定位是通道问题还是本地问题。6. 装完之后怎么用得更顺安装只是起点。装完第一件事是进项目目录跑/init让 OpenCode 生成AGENTS.md把项目的构建命令、目录结构、技术约定记下来。不跑这一步Agent 对你的项目一无所知回答会很泛。第二件事是版本管理。OpenCode 迭代快遇到莫名其妙的 bug 先opencode --version看版本必要时降级。我试过新版和某些插件不兼容降一个版本就正常了。第三件事如果你打算长期在编码和 Agent 场景里用可以了解下 Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 它针对高频调用做了额度优化。日常排障和接入文档在 API Keys https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 和接入文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里都能找到。最后留个实操建议装完后别急着上大项目先拿一个小仓库跑通「读文件、改代码、跑测试」的完整闭环确认模型调用稳定了再放大。这样出问题的时候变量少好定位。