免费 AI IDE
OpenClaw 接入 OpenCode 时，应先确认使用 Zen 还是 Go，再选择对应的认证入口和模型前缀。模型列表里能看到某个名称，不代表你的账户已经拥有该模型的调用权限。
你已经填了密钥，模型也能被选中，但发送消息仍然报错。这时继续换提示词通常没有帮助：问题可能在服务选错、订阅权限、模型标识或凭据实际读取位置。本文把接入过程拆成一条可以逐项验证的路径，不提供过期模型名的固定清单，也不让你把真实密钥粘进命令历史。编程狮这次讨论的是当前官方内置的 OpenCode 提供商接入，不是任意兼容接口的通用代理配置。
一、Zen 与 Go 不是同一个模型前缀
截至本文核对官方文档时，OpenCode Zen 在 OpenClaw 中使用 opencode 前缀，OpenCode Go 使用 opencode-go 前缀。二者同属 OpenCode 服务体系，但目录、套餐和权限不能因此视作完全相同。
官方文档说明两者使用 OPENCODE_API_KEY，也接受 OPENCODE_ZEN_API_KEY 作为兼容别名；Go 还需要对应的付费订阅。共享密钥变量的名字，并不意味着一份账户权限可以覆盖所有服务。排错时应该先看自己实际开通的服务，再核对模型所在的命名空间。
也不要把 OpenCode 的命令行编程客户端与模型提供商混为一谈。你在这里要完成的是 OpenClaw 到模型服务的连接，不一定需要先运行另一套编程客户端。有关整体结构，可先阅读 OpenClaw 教程，把代理、模型与工具分开理解。
| 服务 | OpenClaw 模型前缀 | 配置前先确认 |
|---|---|---|
| OpenCode Zen | opencode/ | 账户凭据与目标模型可用性 |
| OpenCode Go | opencode-go/ | Go 订阅及模型调用权限 |
这里没有列固定模型名，是因为模型目录可能更新。复制一篇旧文章中的模型后缀，往往会把原本正常的凭据带进另一类错误。下一步用本机当前版本列出目录，再根据实际结果选择。
二、先检查本机版本，再走对应认证入口
先执行版本命令，记录当前 OpenClaw 版本。若是长期未升级的环境，对照该版本支持的提供商；当前官方文档已经把 Go 列为随程序提供的内置能力，不应先假设必须另外安装第三方插件。
openclaw --version
openclaw onboard --help下面两个认证入口只选择与你的服务一致的一个，不要为了“都试一遍”连续覆盖现有设置：
# 使用 Zen 的账户选择这一条
openclaw onboard --auth-choice opencode-zen
# 使用 Go 的账户选择这一条
openclaw onboard --auth-choice opencode-go交互流程可能涉及不止一项本地配置。在已有可用环境中，先备份当前配置，阅读每一步选项，再确认修改。密钥在受控的交互输入处提供，不要照搬带真实密钥的命令行示例，也不要把终端完整录屏公开。
如果程序提示不认识 auth-choice 的值，先检查版本与帮助，不要立即转向手工伪造提供商对象。旧版本与当前文档不一致属于环境问题。升级也应先看变更说明并保留回退方式，不能在业务使用中盲目覆盖。
如果你选择通过环境变量管理凭据，还要确认运行代理的进程确实能读取它。在一个终端临时设置的变量，不必然传给已经运行的后台进程。不要通过打印密钥全文来证明它存在，只检查变量是否设置，并在修改后按实际部署方式重新加载相关进程。
三、从实际目录选择模型，再做一次最小请求
认证后列出对应提供商的模型。以下以 Go 为例；如果使用 Zen，把提供商参数换成 opencode：
openclaw models list --provider opencode-go
$selectedModel = Read-Host "从上方列表复制完整的 opencode-go/模型标识"
if ($selectedModel -notmatch '^opencode-go/\S+$') {
throw "模型标识必须属于 opencode-go，且不能包含空格"
}
openclaw config set agents.defaults.model.primary $selectedModel这段检查只验证前缀与基本形状，并不证明标识确实在目录中；你仍需从上一条命令的实际输出复制。不要把模型的展示名称当成完整标识，也不要把斜杠前的提供商省略。
设置的是默认主模型。如果某个代理或当前会话另有覆盖配置，它可能继续使用旧模型。遇到“明明改过，日志仍是旧服务”，先看实际请求记录中的提供商与模型，而不是反复写默认值。
然后通过你平时使用的聊天入口发出一次无工具、无附件、无敏感信息的小请求，例如要求只回复“连接正常”。记录实际模型、是否返回文本以及错误摘要。这一步可能产生服务用量，确认账户计费和授权后再做；不要用大文件或长对话作为首次探测。
更细的 Go 接入说明可对照 OpenCode Go 提供商配置。模型目录可见仅证明程序知道这个模型，最小请求成功才证明当次账户、路由和模型组合能完成推理，两项证据不可互相替代。
四、按错误类别排查，不要把所有失败都归因于密钥
认证相关错误首先检查凭据是否缺失、过期、属于预期账户，以及实际运行进程是否读到了正确配置。常见的 401 倾向认证问题，403 倾向权限或策略限制，但最终仍应以服务端错误正文为准，不能只看状态码猜结论。
模型不存在或路由错误时，核对完整模型标识、服务前缀和是否错误添加了自定义地址。内置提供商已有相应路由，照抄另一家兼容接口的地址可能制造新的错误。404 也可能来自路径不匹配，并不直接证明账户不可用。
遇到 429，先区分额度、速率限制和并发限制。停止高频重试，按响应提示等待，必要时采用带上限的指数退避。连续重复同一个失败请求只会增加噪声，有时还会延长恢复时间。网络超时则另查代理、DNS 和服务连通性，不应先重置所有凭据。
排错记录至少保留时间、程序版本、提供商前缀、完整模型标识、请求是否带工具和脱敏错误摘要。不要记录 Authorization 请求头。若需要求助，提供这一组证据比只发“不能用”的截图更容易定位。
本文的配置事实核对自 OpenClaw OpenCode 文档 和 Go 提供商文档。由于实际调用取决于个人账户，文中的命令是接入与排查步骤，不代表已经替你完成订阅验证或付费推理测试。
总结
OpenClaw 接入 OpenCode 的关键顺序是：确认服务与权益，走匹配的认证入口，从实际目录选择完整模型标识，再用最小请求验收。不要把“配置被保存”“模型在列表中”“模型真正返回结果”合并成一句成功。
保持内置配置尽量简单，一次只改变一个变量。默认模型、会话覆盖与后台环境分别检查，通常比同时重装程序、换密钥和改地址更容易得到可解释的结果。
延伸学习
- 阅读 OpenClaw 技能教程，区分模型服务与代理技能。
- 用 JSON 教程 熟悉配置文件的语法与数据结构。
- 参考 OpenClaw 安全防护笔记，补充凭据与权限方面的检查。
常见问题
Q：同一份密钥能看到模型，为什么仍不能调用？
A：目录信息不等于账户权益。继续核对所选服务、订阅、额度和错误正文，再执行一次符合权限的小请求。
Q：Go 接入一定要额外安装插件吗？
A：当前官方文档将它列为内置提供商能力。老版本可能不支持，应先核对版本，而不是默认安装来历不明的扩展。
Q：改默认模型后，已有会话为什么没变？
A：可能存在会话或代理级覆盖，也可能运行进程没有读取新配置。先查实际请求使用的模型，再按部署方式处理重载。
