1. Windows 装 OpenCode 前先把 TaoToken Key 写进环境最近在 Windows 上折腾 OpenCode最容易卡住的不是安装包本身而是模型 provider 的鉴权链路终端里opencode能启动但一选模型就抛ProviderModelNotFoundError或者 API Key 读取为空。后来把顺序调整了一下先到 TaoToken 官网 获取 Key再把TAOTOKEN_API_KEY写进 Windows 环境变量最后把 Base URL 固定成https://taotoken.net/api写进 OpenCode 的 provider 配置整个链路才稳定下来。这个顺序很重要。很多教程会让你先装 OpenCode、再进 TUI、再临时填 Key但在 Windows 上PowerShell、CMD、WSL、VS Code 集成终端的环境变量作用域并不完全一致。如果 Key 只在一个终端窗口里set过换一个终端就失效OpenCode 读不到变量就会表现为“配置写对了但模型列表为空”。所以本篇不按“先装工具再配模型”的常规顺序写而是先处理 TaoToken Key 与 Base URL再安装 OpenCode最后做启动验证对照。这样即便你中途换终端、换 shell、换项目目录配置也不会丢。先明确三个固定值项目值TaoToken KeyYOUR_API_KEY在控制台创建后替换Base URLhttps://taotoken.net/apiOpenCode 模型调用格式provider/modelId例如taotoken/你的模型IDTaoToken 的 Key 创建入口在控制台建议直接访问 API Keys 页面 生成复制后不要提交到 Git也不要写进项目里的opencode.json明文。下面先从 Windows 环境变量开始。在 PowerShell 当前会话中临时设置$env:TAOTOKEN_API_KEYYOUR_API_KEY $env:TAOTOKEN_BASE_URLhttps://taotoken.net/api验证当前会话是否读到echo $env:TAOTOKEN_API_KEY echo $env:TAOTOKEN_BASE_URL如果只想临时测试这样已经够用。但 OpenCode、VS Code、Windows Terminal、CMD 可能是不同进程临时变量不会自动继承。更稳妥的方式是写入用户级环境变量setx TAOTOKEN_API_KEY YOUR_API_KEY setx TAOTOKEN_BASE_URL https://taotoken.net/api执行setx后当前窗口不会立刻生效需要关闭并重新打开终端。重新打开后验证[Environment]::GetEnvironmentVariable(TAOTOKEN_API_KEY,User) [Environment]::GetEnvironmentVariable(TAOTOKEN_BASE_URL,User)如果你习惯 CMD也可以用set TAOTOKEN_API_KEYYOUR_API_KEY setx TAOTOKEN_API_KEY YOUR_API_KEY echo %TAOTOKEN_API_KEY%这里有一个容易忽略的细节setx写入的是用户级变量不会影响已经运行的进程。很多“我明明设置了 KeyOpenCode 还说没权限”的问题都是因为设置完没有重开终端。建议每次改完环境变量先用echo或[Environment]::GetEnvironmentVariable确认再启动 OpenCode。更多控制台与模型入口可以从 TaoToken 官网 进入按需查看模型对话、Coding Plan 和 API Keys。2. Windows 安装 OpenCode 的三条可复现路径npm、scoop、chocoOpenCode 在 Windows 上的安装方式不止一种但核心原则是不要用 macOS / Linux 的curl | bash命令硬套 Windows。你在 PowerShell 里执行类似管道脚本大概率会报语法错误或路径异常。Windows 优先选 npm、scoop、choco 三类包管理器。前置条件先检查node -v npm -vNode.js 版本建议 ≥ 18.0。如果机器上装过 0.1.x 旧版 OpenCode先卸载避免新旧路径冲突npm uninstall -g opencode-ai npm uninstall -g opencode然后任选一种安装方式。方式一npm 全局安装适合大多数 Windows 开发者。npm install -g opencode-ai安装完成后验证opencode --version where.exe opencodewhere.exe用来确认实际调用的是哪个路径。如果你的机器上同时存在多个 Node 版本或者以前手动配置过 PATH这里可能出现两个opencode路径。保留当前 Node 版本对应路径删除旧路径否则会出现“版本号对不上”“装完还是旧版”的问题。方式二scoop 安装适合喜欢 Windows 包管理器的用户。scoop search opencode scoop install opencode如果搜不到先更新 bucketscoop update scoop bucket known方式三choco 安装适合企业内已统一使用 Chocolatey 的环境。choco search opencode choco install opencode安装完统一验证opencode --version opencode --help如果你在 VS Code 里单独安装 OpenCode 插件发现插件无法工作通常不是插件问题而是本机没有全局安装opencode-ai。OpenCode 的 IDE 形态更像前端入口底层仍需要本机服务或 CLI 存在。所以顺序应当是先全局安装 CLI再装 IDE 插件最后配置 provider。安装阶段如果遇到opencode : 无法将“opencode”项识别为 cmdlet、函数、脚本文件或可运行程序的名称优先检查三件事npm config get prefix输出的目录是否在 PATH 中是否刚setx过 PATH 但没有重开终端是否存在多个 Node 版本导致全局包装到了另一个版本目录。可以这样查看 npm 全局目录npm config get prefix npm root -g把npm config get prefix的路径加入用户 PATH重开终端再执行where.exe opencode。如果你希望从官网统一查看入口和模型能力也可以先到 TaoToken 官网 确认 Base URL 与 Key 的对应关系再回到 OpenCode 配置。3. 把 TaoToken 写进 OpenCode 的 provideropencode.json 配置与模型 IDOpenCode 支持多 provider关键是把 TaoToken 当成一个 OpenAI 兼容 provider 接进去。配置文件通常放在用户目录%USERPROFILE%\.config\opencode\opencode.json也可以放在项目根目录作为项目级配置你的项目\opencode.json用户级配置适合放通用 provider 和 Key 读取方式项目级配置适合放权限沙盒、模型偏好、项目规则。下面是一个可复制的opencode.json示例{ $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: { your-model-id: { name: TaoToken 模型 } } } }, model: taotoken/your-model-id }这段配置有三个要点第一baseURL必须是https://taotoken.net/api不要在后面多写/v1或斜杠除非官方文档明确要求。Base URL 不加 UTM保持纯净。第二apiKey推荐写成{env:TAOTOKEN_API_KEY}让 OpenCode 从环境变量读取。这样配置文件可以提交到仓库Key 不会泄露。第三模型格式必须是provider/modelId。你在model字段写的是taotoken/your-model-id在对话里切换模型时也要保持这个格式。只写your-model-id或者写成taotoken:your-model-id都可能触发ProviderModelNotFoundError。模型 ID 从哪里来可以到 TaoToken 的 模型对话页面 查看当前可用模型把实际模型 ID 替换掉your-model-id。如果你准备长期在 OpenCode 里跑编码任务也可以先了解 Coding Plan再决定模型组合。配置写完后不要急着进 TUI先在终端验证配置是否被解析opencode models如果模型列表为空优先检查opencode.json是否有 JSON 语法错误是否出现了旧版本残留的未知 keyTAOTOKEN_API_KEY是否在当前终端可见baseURL是否写成了https://taotoken.net/api模型字段是否满足provider/modelId。权限沙盒也可以在同一个配置文件里控制。OpenCode 的权限粒度包括文件编辑、Shell 命令、外部目录访问等。一个保守的示例{ permission: { edit: ask, bash: { *: ask, git status: allow, git diff: allow, npm test: allow }, webfetch: ask } }这段配置的含义是默认编辑和命令都先询问只放行只读 Git 命令和测试命令。真实项目里不要直接给allow全开尤其是涉及删除、部署、数据库连接的命令。所有 SQL 和危险命令都应当由你在本地终端确认后执行不要让 Agent 直接连生产库。4. Windows 环境变量持久化与启动验证对照PowerShell / CMD / WSLWindows 上最容易出问题的环节是“你以为设置了环境变量但当前进程没有读到”。下面给出一张对照表覆盖 PowerShell、CMD、WSL 三种常见终端。终端临时设置持久化设置验证命令PowerShell$env:TAOTOKEN_API_KEYYOUR_API_KEYsetx TAOTOKEN_API_KEY YOUR_API_KEYecho $env:TAOTOKEN_API_KEYCMDset TAOTOKEN_API_KEYYOUR_API_KEYsetx TAOTOKEN_API_KEY YOUR_API_KEYecho %TAOTOKEN_API_KEY%WSLexport TAOTOKEN_API_KEYYOUR_API_KEY写入~/.bashrc或~/.zshrcecho $TAOTOKEN_API_KEY注意WSL 和 Windows 主机不是同一套环境变量。你在 PowerShell 里setx的变量WSL 默认读不到反过来也一样。如果你在 WSL 里运行 OpenCode要在 WSL 的 shell 配置文件里设置或者用export临时注入。PowerShell 持久化推荐用用户级变量setx TAOTOKEN_API_KEY YOUR_API_KEY setx TAOTOKEN_BASE_URL https://taotoken.net/api设置后关闭所有终端重新打开再验证if ([string]::IsNullOrWhiteSpace($env:TAOTOKEN_API_KEY)) { Write-Host TAOTOKEN_API_KEY 未读取到 } else { Write-Host TAOTOKEN_API_KEY 已读取 } if ($env:TAOTOKEN_BASE_URL -eq https://taotoken.net/api) { Write-Host Base URL 正确 } else { Write-Host Base URL 不正确 }确认环境变量后进入项目目录启动 OpenCodecd D:\workspace\your-project opencode启动后先看 TUI 是否能正常进入。OpenCode 里有两种核心模式用 Tab 切换Plan偏只读适合先分析代码库、梳理方案、评估影响范围Build可编辑文件、执行命令、跑测试适合方案确认后落地。推荐流程是Plan 模式分析项目 - 人工审核方案 - Build 模式执行修改 - 本地测试 - Git diff 审查常用交互符号引用文件例如src/auth/index.ts!执行本地 Shell 命令例如!git status/打开斜杠命令例如/undo、/help。非交互式运行适合脚本或 CI 场景opencode run 扫描当前项目测试失败原因只输出修复建议不修改文件如果你要在 CI 里用建议把模型、权限、超时都固定并让 OpenCode 只输出报告不直接改代码。需要人工确认的命令仍然由读者在本地执行。5. 同一把 TaoToken Key 复用Claude Code settings.json、Codex config.toml、CC Switch 三件套你已经在 OpenCode 里配好了 TaoToken接下来同一把 Key 还可以复用到其他编码工具。但要注意不同工具的配置格式完全不同不要把 Claude Code 的ANTHROPIC_*变量套到 Codex 上。Claude Code 使用settings.json常见路径是用户目录下的.claude/settings.json。示例{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_AUTH_TOKEN: YOUR_API_KEY } }这里用的是ANTHROPIC_BASE_URL和ANTHROPIC_AUTH_TOKEN只适用于 Claude Code 生态。Key 也可以不写明文改成从环境变量读取{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_AUTH_TOKEN: ${TAOTOKEN_API_KEY} } }Codex 使用config.toml常见路径是%USERPROFILE%\.codex\config.toml。示例model_provider taotoken model your-model-id [model_providers.taotoken] name TaoToken base_url https://taotoken.net/api env_key TAOTOKEN_API_KEY [profiles.taotoken] model_provider taotoken model your-model-id wire_api chatCodex 不要写ANTHROPIC_BASE_URL那是 Claude Code 的变量。Codex 读取的是env_key指定的环境变量也就是你前面设置的TAOTOKEN_API_KEY。如果你使用 CC Switch 这类切换工具可以把配置归纳成“三件套”三件套值Base URLhttps://taotoken.net/apiAPI KeyYOUR_API_KEY或环境变量TAOTOKEN_API_KEYModel按控制台模型 ID 填写保持provider/modelId格式CC Switch 的作用是帮你切换不同供应商配置但底层仍然依赖这三项。无论切到 Claude Code、Codex 还是 OpenCode都先确认 Base URL 是https://taotoken.net/apiKey 来自同一个控制台模型 ID 与工具要求的格式一致。需要查看 Claude Code 的完整接入方式可以到 Claude Code 文档 对照配置。6. 高频报错排查ProviderModelNotFoundError、PATH 错乱、权限拒绝Windows 上装 OpenCode 并接入 TaoToken常见问题集中在下面几类。第一类ProviderModelNotFoundError。原因通常是模型 ID 格式不对。OpenCode 要求provider/modelId例如taotoken/your-model-id。如果你在配置里只写了模型名或者 provider 名字与provider字段不一致就会找不到。排查步骤opencode models确认列表里有taotoken/前缀的模型。如果没有检查opencode.json的provider键名是否与model前缀一致。第二类opencode命令找不到。在 PowerShell 里输入where.exe opencode npm config get prefix如果where.exe没有输出说明全局安装目录不在 PATH。把npm config get prefix的路径加入用户 PATH重开终端。如果输出多个路径删除旧版本路径避免 0.1.x 与新版冲突。第三类API Key 读取为空。验证echo $env:TAOTOKEN_API_KEY [Environment]::GetEnvironmentVariable(TAOTOKEN_API_KEY,User)如果第一条为空、第二条有值说明当前终端没有继承新变量重开终端即可。如果两条都为空重新执行setx并确认没有写错变量名。第四类.env文件被拒绝读取。OpenCode 默认会保护.env、.env.*这类敏感文件。这是正常安全策略。如果你确实需要让 Agent 读取某个配置文件不要直接放开全部权限而是单独在permission里配置。生产密钥、数据库连接串、云厂商凭证不要放进被 Agent 读取的目录。第五类网页端无密码暴露。OpenCode 有客户端-服务器架构网页端可以连接本机服务。默认OPENCODE_SERVER_PASSWORD为空时局域网内可能不需要密码就能访问。如果你要在局域网使用务必配置密码setx OPENCODE_SERVER_PASSWORD 一个足够强的密码重开终端后再启动服务。不要把无密码的本机服务暴露在公共网络。第六类升级后模型列表为空。新版本对配置键更严格。如果旧配置里有未知 key可能导致解析失败。把opencode.json备份后删除不认识的字段只保留provider、model、permission等明确支持的键重启 OpenCode。第七类Plan 模式不等于绝对安全。Plan 默认只读但权限仍然可以被手动放开。不要把 Plan 当成不可逾越的沙盒。真正重要的是权限配置和人工审查。涉及删除、部署、数据库、云资源的命令必须由你在本地终端确认后执行。7. 从 Plan 到 BuildWindows 上的 OpenCode 工作流与 CTA在 Windows 上把 OpenCode 跑起来后建议固定一套工作流而不是一上来就让 Agent 大改代码。第一步进入项目目录确认 Git 状态干净cd D:\workspace\your-project git status第二步启动 OpenCode先用 Plan 模式opencode在 TUI 里输入类似任务tests 分析当前测试失败链路列出可能受影响的 fixture 和依赖不要修改文件。第三步人工审核方案。确认范围后再按 Tab 切到 Build 模式让 Agent 修改文件、执行测试。每一步都保留 Git diffgit diff第四步用/undo回滚。注意/undo依赖 Git 快照非 Git 仓库不会回滚文件。所以项目必须是 Git 仓库重要修改前先 commit 或 stash。第五步把项目规则沉淀到AGENTS.md或项目级配置里让 Agent 理解技术栈、测试命令、代码规范。这样不同成员复用同一套规则输出更稳定。适合使用 OpenCode TaoToken 的场景对代码隐私敏感希望模型调用走自己可控的 Base URL需要在 Windows 终端、WSL、VS Code 之间切换想自由切换模型而不是锁定单一厂商接手陌生仓库需要先 Plan 分析再 Build 修复希望把 Key 放在环境变量里避免明文写进项目配置。不太适合的场景只想用 Tab 自动补全完全不想接触终端不愿意配置环境变量和权限沙盒希望所有工具开箱即用不接受命令行工作流。最后给一个最小可复现清单。先到 TaoToken 官网 获取 Key然后按顺序执行setx TAOTOKEN_API_KEY YOUR_API_KEY setx TAOTOKEN_BASE_URL https://taotoken.net/api npm install -g opencode-ai opencode --version cd D:\workspace\your-project opencode models opencode如果模型列表正常、TUI 能进入、能读取文件、!git status能执行就说明 Windows 安装命令、环境变量设置和启动验证这条链路已经打通。需要进一步选择模型可以先去 模型对话 确认模型 ID准备长期用于编码任务可以查看 Coding PlanKey 管理与轮换在 API Keys如果你同时使用 Claude Code可以对照 Claude Code 文档 完成 settings.json 配置。把 Key 先写进环境再让 OpenCode 读环境变量是 Windows 上最稳的接入方式。