1. 为什么要在 WSL 里跑 opencode如果你在 Windows 上直接装 opencode大概率会遇到两类问题一是路径分隔符和权限模型跟 Linux 不一致脚本执行时经常报EACCES或路径找不到二是某些依赖在 Windows 原生环境下编译失败尤其是涉及 node-gyp 的包。我试过在 PowerShell 里硬扛最后还是回到 WSL2 Ubuntu 的组合体验顺畅很多。opencode 是一个跑在终端里的 AI 编码助手能读你当前项目的文件、执行命令、按你的指令改代码。它适合习惯命令行、想让 AI 直接操作本地仓库的开发者。而 WSL2 是 Windows 自带的 Linux 子系统相当于在 Windows 里开了一个轻量级 Linux 虚拟机文件系统隔离、内核完整跑 opencode 这类工具比原生 Windows 稳。这篇教程的完整链路是启用 WSL2 → 装 Ubuntu → 装 Node.js 22 → 全局装 opencode → 用 TaoToken 统一 Key 接入模型通道 → 写 settings.json 骨架 → 启动验证。每一步都给可复制的命令和配置最后附常见报错排查路径。你不需要提前懂 Linux跟着敲就行。2. TaoToken 前置拿统一 Key 和 API 通道opencode 本身不绑定某一家模型它通过配置里的 provider 去请求模型接口。TaoToken 在这里的角色是提供一个统一的 API 通道和 Key你不需要分别去各家平台注册、分别管理密钥一个 Key 就能在 opencode 里切换不同模型。你需要先拿到两样东西API Key 和请求地址。操作路径是登录 TaoToken 控制台在 API Keys 页面创建一个新 Key复制保存好页面只显示一次。请求地址用https://taotoken.net/api这个地址在配置里会作为 baseURL 使用。注意Key 不要直接写进会提交到 Git 的配置文件里。后面我会给一个把 Key 放在环境变量、settings.json 只引用变量名的骨架这样即使配置被同步也不会泄露。如果你还没创建 Key可以先去控制台操作https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentconsole 。创建完 Key 后接入文档里有各客户端的配置示例opencode 的写法在下面第三节直接给全。3. 可复制配置从 WSL 到 settings.json3.1 启用 WSL2 并安装 Ubuntu以管理员身份打开 PowerShell 或 Windows Terminal执行wsl --install这条命令会自动启用虚拟机平台、安装 WSL2 内核并默认装一个 Ubuntu 发行版。执行完重启电脑。重启后 Ubuntu 会要求你设置用户名和密码这个用户名后面配置里会用到。如果你已经装过 WSL 但版本是 1可以手动升级wsl --set-default-version 2 wsl --list --verbose确认 Ubuntu 那一行的 VERSION 是 2。如果还是 1执行wsl --set-version Ubuntu 2。3.2 在 Ubuntu 里装 Node.js 22启动 Ubuntu开始菜单里搜 Ubuntu 或终端里输wsl依次执行sudo apt update sudo apt install -y curl curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash - sudo apt install -y nodejs验证node -v npm -v正常会输出v22.x.x和对应的 npm 版本。如果 node 版本不对检查是不是系统里已有旧版 node用which node看路径。3.3 全局安装 opencodesudo npm install -g opencode-ai装完验证opencode --version能输出版本号就说明二进制已就位。如果提示 command not found检查 npm 全局 bin 目录是否在 PATH 里执行npm config get prefix看路径通常/usr或/usr/local下的 bin 默认已在 PATH。3.4 settings.json 骨架opencode 的配置文件放在用户目录下的.config/opencode/settings.json。先建目录mkdir -p ~/.config/opencode然后用编辑器创建文件nano ~/.config/opencode/settings.json写入以下骨架把YOUR_TAOTOKEN_KEY换成你的实际 Key或者用环境变量引用{ provider: { taotoken: { type: openai, baseURL: https://taotoken.net/api, apiKey: {env:TAOTOKEN_API_KEY}, models: { claude-sonnet: { name: claude-sonnet-4-20250514 }, gpt-4o: { name: gpt-4o } } } }, model: taotoken/claude-sonnet, theme: default }这里apiKey用了{env:TAOTOKEN_API_KEY}的写法opencode 启动时会从环境变量读取。你需要在~/.bashrc里加一行echo export TAOTOKEN_API_KEY你的Key ~/.bashrc source ~/.bashrc这样 Key 不落在 settings.json 里配置文件可以安全备份。model字段指定默认用哪个模型格式是provider名/模型别名。models里可以列多个启动后用/model命令切换。提示baseURL 末尾不要加/v1opencode 会按 provider 类型自动补全路径。如果你填了/v1导致 404去掉即可。4. 验证请求启动 opencode 确认通道生效配置写好后在任意项目目录下启动cd ~/your-project opencode进入交互界面后先确认模型列表加载正常。输入/model如果配置正确会列出taotoken/claude-sonnet和taotoken/gpt-4o两个选项。选中一个后直接输入一句测试指令比如帮我看看当前目录下有哪些文件并解释 package.json 的作用opencode 会读取当前目录、调用模型、返回结果。如果能看到它列出文件并给出解释说明 TaoToken 的 API 通道已经生效请求正常返回。你也可以用非交互模式快速验证opencode run 用一句话说明这个项目是做什么的这条命令会直接输出模型回复适合脚本里做连通性检查。如果返回内容正常说明 Key、baseURL、模型名三者都对上了。想单独验证模型通道是否通也可以去模型对话页面发一条消息对比返回https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentmodels 。如果那边正常、opencode 这边报错问题就在本地配置。5. 本篇常见错排查5.1 401 Unauthorized最常见的原因是 Key 没读到。检查环境变量是否生效echo $TAOTOKEN_API_KEY如果输出为空说明~/.bashrc没 source 或者写错了。重新执行source ~/.bashrc再启动 opencode。如果输出有值但仍报 401去控制台确认 Key 是否被禁用或删除重新创建一个。5.2 404 Not FoundbaseURL 写错。确认是https://taotoken.net/api不要带/v1、不要带尾部斜杠。另外检查type字段是不是openaiopencode 会按这个类型拼接请求路径。5.3 模型名不识别models里的name字段必须是接口实际支持的模型标识。如果你填了一个不存在的名字请求会返回 model not found。先用/model看列表里有没有你配的别名再确认name跟接入文档里列的一致。5.4 opencode 启动报 EACCES通常是全局安装时权限没给对。重新装一次sudo npm install -g opencode-ai如果还不行检查~/.config/opencode目录权限确保当前用户可读写ls -la ~/.config/opencode chmod 700 ~/.config/opencode5.5 WSL 里网络请求超时先确认 WSL 能访问外网curl -I https://taotoken.net/api如果这条超时说明 WSL 的网络配置有问题。执行wsl --shutdown后重新进入或者检查 Windows 防火墙是否拦截了 WSL 的流量。如果 curl 正常但 opencode 超时检查 settings.json 里 baseURL 有没有拼写错误。5.6 配置文件不生效opencode 读取的是~/.config/opencode/settings.json注意是用户目录下的.config不是/etc。如果你在项目目录里放了 settings.jsonopencode 不会自动读。确认路径cat ~/.config/opencode/settings.jsonJSON 格式错误也会导致静默失败用python3 -m json.tool ~/.config/opencode/settings.json校验一下语法。6. 长期编码与 Agent 场景的接入建议如果你只是偶尔用 opencode 问几个问题上面的配置就够了。但如果你打算把它当成日常编码助手频繁调用模型、跑 Agent 任务建议把 Key 管理做得更规范一些。比如给不同项目分配不同的 Key方便在控制台看用量和排查问题或者用 Coding Plan 这类长期方案来覆盖高频调用。opencode 的 Agent 模式会连续读文件、执行命令、改代码对通道稳定性要求比单次问答高。配置里可以把超时和重试参数加上{ provider: { taotoken: { type: openai, baseURL: https://taotoken.net/api, apiKey: {env:TAOTOKEN_API_KEY}, timeout: 60000, maxRetries: 3 } } }timeout单位是毫秒Agent 任务链路长给 60 秒比较稳妥。maxRetries在网络抖动时自动重试避免一次超时就中断整个任务。另外WSL 默认会把 Windows 所有盘挂到/mnt/c、/mnt/dopencode 在 Agent 模式下有可能扫到这些目录。如果你只想让它操作项目目录可以在项目根目录启动 opencode它默认以当前工作目录为边界。更严格的做法是在/etc/wsl.conf里关掉 automount只挂载需要的目录这样 AI 能看到的文件范围就收窄了。配置改完后用opencode run跑一条真实任务验证比如让它读一个文件并总结确认返回正常再投入日常使用。遇到报错先看终端输出的 HTTP 状态码401 查 Key、404 查 baseURL、超时查网络按第 5 节的路径逐项排除即可。