1. 为什么 Windows 用户要在 WSL 里跑 OpenCodeOpenCode 是一个跑在终端里的 AI 编码助手能读你当前目录的代码、改文件、执行命令适合习惯命令行工作流的开发者。它官方推荐在 Linux 环境下安装Windows 原生支持一直不算完善。对 Windows 用户来说最省事的方案不是装双系统也不是开虚拟机而是用 WSLWindows Subsystem for Linux——Windows 自带的 Linux 兼容层硬件资源直接透传启动只要几秒。我先把两个容易混的概念讲清楚。WSL 是 Windows 的一个功能开关相当于一条高速通道Ubuntu 是跑在这条通道里的具体 Linux 发行版自带 apt、bash、git 这些工具。你从微软商店装的「Ubuntu」就是给 WSL 配了一个能干活的操作系统。理解这一层后面所有命令你都不会觉得突兀。为什么非要 Linux 环境因为 OpenCode 是 Rust 编译的独立二进制程序安装脚本、路径处理、权限模型都按 Unix 习惯设计。在 Windows 的 PowerShell 里硬跑会遇到路径分隔符、可执行权限、shell 脚本兼容等一堆问题。放进 WSL 的 Ubuntu 里这些摩擦全部消失。还有一个关键点项目文件必须放在 WSL 内部文件系统也就是~主目录下不要放在/mnt/c这种 Windows 盘挂载点。实测同一块 SSDWSL 原生文件系统的大文件读写能到 1GB/s 以上而通过/mnt/c访问只有约 100MB/s小文件随机读写差距也在数倍。项目一旦放在 Windows 盘OpenCode 扫描代码、Git 状态检查都会明显变慢。这篇教程的链路是WSL Ubuntu 环境 → 安装 OpenCode → 配置 Git 与 GitHub 认证 → 把 API 端点统一到 TaoToken → 逐条验证跑通。每一步都给可复制的命令和预期输出遇到报错直接对照第 5 节排查。适合从没碰过 WSL 的 Windows 用户也适合装过但卡在认证环节的人。2. 前置准备WSL、Ubuntu 与 TaoToken Key 通道这一节把环境搭好同时把后面要用的 API Key 通道准备好。顺序上建议先装 WSL 和 Ubuntu因为下载和导入镜像耗时较长可以边等边去申请 Key。2.1 启用 Windows 功能并安装 Ubuntu打开「启用或关闭 Windows 功能」勾选「适用于 Linux 的 Windows 子系统」和「虚拟机平台」两项重启电脑。这两步只是给 WSL 运行资格和虚拟化能力还缺内核组件下一步补上。以管理员身份打开 PowerShell执行在线安装wsl --install -d Ubuntu --location D:\WSL注意--location路径末尾不要加反斜杠。写成D:\WSL\会报ERROR_INVALID_NAME去掉末尾的\即可。安装过程会下载 WSL 2 内核更新包约 15 到 20MB这步不能跳过——前面勾选的功能只是空房间内核包才是真正的 Linux 内核和 GPU 加速支持。如果在线安装一直超时报WININET_E_TIMEOUT改用离线导入。到 Ubuntu WSL 官方发布页下载.wsl镜像文件比如ubuntu-24.04.4-wsl-amd64.wsl放到D:\WSL\然后执行wsl --import Ubuntu-24.04 D:\WSL\Ubuntu-24.04 D:\WSL\ubuntu-24.04.4-wsl-amd64.wsl --version 2参数含义Ubuntu-24.04是发行版名字后面wsl -d会用到D:\WSL\Ubuntu-24.04是实际存放位置--version 2指定 WSL 2 架构性能更好。首次启动用wsl -d Ubuntu-24.04进入。默认是 root 用户如果这个环境只用来跑 OpenCode直接用 root 操作可以省去每次 sudo 的麻烦专用环境这样用没问题。想建普通用户就执行adduser opencode和usermod -aG sudo opencode。2.2 配置默认进入主目录默认情况下在 Windows 地址栏输入wsl进入会停在/mnt/c/Users/你的用户名每次都要手动cd ~。配置一下让它直接进主目录echo -e [user]\ndefault$(whoami)\n\n[automount]\noptions \metadata,umask22\ | tee /etc/wsl.conf echo cd ~ ~/.bashrc source ~/.bashrc第一行写入/etc/wsl.conf设定默认用户和挂载选项第二行在.bashrc末尾追加cd ~打开终端时自动跳回主目录。然后回 PowerShell 重启 WSL 让配置生效wsl --terminate Ubuntu-24.04 wsl之后无论从地址栏还是终端敲wsl都会直接进主目录。2.3 准备 TaoToken 的 API KeyOpenCode 支持自定义 API 端点把请求统一走 TaoToken 的 Key 通道好处是一个 Key 管多个模型切换模型不用改一堆环境变量。先去控制台创建 Key控制台入口https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteAPI Key 管理https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite创建后复制那串以sk-开头的 Key先存到记事本第 3 节配置 OpenCode 时要用。API 基础地址是https://taotoken.net/api注意这个地址不带任何查询参数配置时原样填入即可。如果你还没想好用什么模型可以先到模型对话页面试一下效果确认通道可用再往下配模型对话https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite这一步不阻塞安装但建议先做因为后面 OpenCode 首次启动就要填 Key手边有现成的能少一次中断。3. 安装 OpenCode 并接入 TaoToken 的可复制配置环境就绪后安装 OpenCode 本身只要一行命令。这一节的重点是把配置文件写对让 OpenCode 走 TaoToken 的端点。3.1 一行命令安装 OpenCode在 WSL 的 Ubuntu 终端里执行curl -fsSL https://opencode.ai/install | bash安装成功的标志有两个终端打印出 OpenCode 的 ASCII Logo提示Successfully added opencode to $PATH in /root/.bashrc。为什么用curl | bash而不是npm install因为 OpenCode 是 Rust 编译的独立二进制程序不是 Node.js 包。npm 管的是 Node 生态这里用不上。curl ... | bash直接下载预编译二进制不需要先装 Node最干净。安装完验证版本opencode --version如果提示command not found别慌这是正常的。安装脚本把路径写进了/root/.bashrc但只对下次登录或手动加载生效当前终端还是旧状态。执行source ~/.bashrc即可之后opencode就能正常启动。3.2 写 OpenCode 配置文件OpenCode 的配置放在~/.config/opencode/opencode.json。先建目录再写文件mkdir -p ~/.config/opencode然后用你顺手的编辑器创建opencode.json内容如下{ $schema: https://opencode.ai/config.json, provider: { taotoken: { npm: ai-sdk/openai-compatible, name: TaoToken, options: { baseURL: https://taotoken.net/api, apiKey: sk-你的Key粘贴到这里 }, models: { claude-sonnet-4-5: { name: Claude Sonnet 4.5 }, gpt-4o: { name: GPT-4o } } } }, model: taotoken/claude-sonnet-4-5 }几个字段说明baseURL固定填https://taotoken.net/api不要加斜杠结尾apiKey填你在控制台创建的那串 Keymodels里列的是你想用的模型 ID按需增删最后的model是默认模型格式是provider名/模型ID。如果你更习惯用环境变量而不是写死在配置里可以改成{ $schema: https://opencode.ai/config.json, provider: { taotoken: { npm: ai-sdk/openai-compatible, name: TaoToken, options: { baseURL: https://taotoken.net/api, apiKey: {env:TAOTOKEN_API_KEY} }, models: { claude-sonnet-4-5: { name: Claude Sonnet 4.5 } } } }, model: taotoken/claude-sonnet-4-5 }然后在~/.bashrc末尾加一行export TAOTOKEN_API_KEYsk-你的Key执行source ~/.bashrc生效。这样 Key 不进配置文件换机器时更安全。3.3 配置 Git 与 GitHub 认证OpenCode 生成代码后要用 Git 提交到 GitHub。Ubuntu 24.04 默认预装了 Gitgit --version能验证不用额外装。先配全局信息git config --global user.name 你的名字 git config --global user.email 你的邮箱认证方式推荐 SSH。原因是 HTTPS Token 需要交互式弹输入框WSL 非交互环境下弹不出来容易卡住SSH 配好一次以后 push/pull 都无感。如果你 Windows 上已经配好 GitHub SSH最省事的是把私钥复制到 WSLcp /mnt/c/Users/你的Windows用户名/.ssh/id_ed25519 ~/.ssh/ chmod 600 ~/.ssh/id_ed25519chmod 600这步不能省。从 Windows 复制过来的文件权限是宽松的SSH 出于安全会拒绝读取权限过宽的私钥不 chmod 会报Permissions are too open。测试连接ssh -T gitgithub.com看到Hi 你的用户名! Youve successfully authenticated就成功了。4. 验证请求从启动到一次完整对话配置写完不代表跑通这一节用几条命令逐层验证确保 OpenCode 真的能通过 TaoToken 拿到模型响应。4.1 启动 OpenCode 并确认工作目录先进 WSL 内部的项目目录再启动mkdir -p ~/opencode-projects/demo cd ~/opencode-projects/demo opencodeOpenCode 进入的是你执行命令时所在的目录。在~下执行工作目录就是~在/mnt/c/Users/xxx执行工作目录就是 Windows 盘性能差不推荐。养成先进项目目录再启动的习惯。启动后界面会显示当前模型如果配置正确应该显示taotoken/claude-sonnet-4-5或你设的默认模型。如果显示的是别的 provider说明配置文件没被读到检查路径是不是~/.config/opencode/opencode.json。4.2 发一条测试请求在 OpenCode 界面里输入一句简单的话比如「用 Python 写一个读取 CSV 并打印前五行的脚本」。正常情况几秒内会开始流式输出代码。这一步验证的是整条链路OpenCode → TaoToken 端点 → 模型 → 返回。如果卡住不动先按CtrlC退出用 curl 单独测端点是否通curl -s https://taotoken.net/api/v1/models \ -H Authorization: Bearer sk-你的Key | head -c 500返回一段 JSON 模型列表说明 Key 和端点都没问题问题在 OpenCode 配置如果返回 401说明 Key 不对或没带上如果连接超时检查网络。4.3 验证 Git 提交链路在 OpenCode 里让它生成一个文件然后手动走一遍 Git 流程git init git add . git commit -m feat: init demo git remote add origin gitgithub.com:你的用户名/demo.git git push -u origin mainpush 成功说明 SSH 认证链路通了。这一步和 OpenCode 无关但它是完整工作流的一环——AI 生成代码只是前半段提交到 GitHub 才算闭环。4.4 用 IDE 远程连接查看文件日常开发建议用 IDE 远程连接 WSL界面在 Windows 显示文件操作全在 WSL 内部完成零权限问题。在项目目录执行code .VS Code 会以客户端-服务端架构启动UI 在 Windows后端跑在 WSL 里。Trae、Cursor 同理装好 Remote 扩展后在项目目录执行对应命令即可。这样你改文件、跑 OpenCode、提交 Git 都在同一个环境里不会出现 Windows 和 WSL 两边文件不同步的问题。5. 本篇常见报错排查401、command not found 与权限问题这一节按真实报错整理遇到问题直接对照。每条都给出原因和解决动作。5.1 401 Unauthorized 或 invalid api key现象OpenCode 启动后发请求报 401或 curl 测试返回{error:{message:invalid api key}}。原因通常是三种Key 复制时带了空格或换行配置文件里apiKey字段拼写错误用了环境变量写法但没source ~/.bashrc。排查顺序先echo $TAOTOKEN_API_KEY看环境变量是否为空再打开~/.config/opencode/opencode.json确认apiKey那行的值最后用 4.2 节的 curl 命令单独测。curl 通而 OpenCode 不通就是配置文件路径或格式问题注意 JSON 不能有尾逗号。5.2 local proxy failed 或连接被拒绝现象请求报local proxy failed、ECONNREFUSED或一直转圈。这类多半是本机网络环境问题不是 Key 的问题。先确认baseURL填的是https://taotoken.net/api没有多余斜杠或路径。然后在 WSL 里执行curl -I https://taotoken.net/api看能否建立连接。如果 WSL 里 curl 不通但 Windows 浏览器能打开检查 WSL 的 DNS 配置可以尝试在/etc/wsl.conf里加[network]\ngenerateResolvConf false后重启 WSL或直接wsl --shutdown再进。5.3 reading choices 相关报错现象返回体解析失败提示reading choices或Cannot read properties of undefined。这通常是端点返回了非预期格式比如把baseURL填成了网页地址而不是 API 地址或者模型 ID 写错导致返回错误对象。确认baseURL是https://taotoken.net/api模型 ID 用配置里列出的那些。如果换了模型后出现先换回默认模型验证再逐个试。5.4 OAuth 或登录态相关报错现象提示需要 OAuth 登录、token 过期。OpenCode 走自定义 provider 时不需要 OAuth出现这类提示说明它没读到你的 provider 配置回退到了内置的登录流程。检查~/.config/opencode/opencode.json是否存在、JSON 是否合法可以用python3 -m json.tool ~/.config/opencode/opencode.json验证以及model字段是否指向了你配置的taotoken/前缀。5.5 command not found 与权限报错opencode: command not found执行source ~/.bashrc或新开一个终端窗口。Permissions are too openchmod 600 ~/.ssh/id_ed25519。Permission denied跑脚本文件从 Windows 复制过来丢了可执行权限chmod x 脚本名。ERROR_INVALID_NAMEwsl --install的--location末尾多了反斜杠去掉。WININET_E_TIMEOUT在线安装超时改用 2.1 节的离线导入方案。5.6 项目跑得慢如果 OpenCode 扫描或 Git 操作明显慢检查项目是不是放在/mnt/c下。移到 WSL 内部~目录即可速度差距能到十倍。用pwd确认当前路径mv过去后重新git init或重新 clone。6. 把 Key 通道固定下来日常使用与后续扩展环境跑通后日常流程其实很短Windows 终端敲wsl进主目录cd到项目opencode启动IDE 远程连接改文件git push提交。多台电脑之间通过 GitHub 中转另一台git clone就能拿到最新代码OpenCode 配置复制一份opencode.json过去即可。把 API 端点统一到 TaoToken 的好处在长期使用里会越来越明显一个 Key 管多个模型换模型只改配置里的model字段不用重新申请和切换各家凭证。如果你后面要跑更长的编码任务或 Agent 工作流可以了解下 Coding Plan额度模型更适合持续调用Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite接入细节和参数说明都在文档里遇到配置字段不确定时对照查接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite如果你用的是 Claude Code 这类工具配置思路一样把 Base URL 指向https://taotoken.net/api、填同一个 Key、指定 Model ID 三件套即可具体步骤在文档的对应章节。最后留一个实用习惯把opencode.json和~/.bashrc里的环境变量一起备份到你的 dotfiles 仓库换机器时 clone 下来改一下 Key 就能用。踩过的坑大多集中在权限和路径上配置一次写对后面基本不用再动。