疑难排查 · opencode
opencode API 密钥未生效——auth 与 {env} 占位符解决方法
opencode 通过 options.apiKey（通常是 {env:...} 占位符）认证自定义提供商。为什么变量会悄悄解析为空、请求以 401 失败。
你看到的报错
opencode 401 unauthorized为什么会发生
- {env:NAME} 占位符指向的变量在启动 opencode 的环境里没有设置——它解析为空，提供商收不到任何密钥。
- 变量在一个 shell 里导出，但 opencode 从另一个地方启动：桌面启动器、另一个终端、复用器面板。
- 密钥被直接粘贴进 opencode.json 且带了前后空白，或者它属于与 baseURL 不同的端点。
如何解决
- 在同一个 shell 里导出占位符指名的那个变量，然后从该 shell 启动 opencode。
- 用 curl 验证这一对配置：配置里的 baseURL 加变量里的密钥，必须先在 opencode 之外成功。
- 优先用 {env:...} 形式而不是把密钥粘进文件——它让密钥远离 dotfiles 和版本控制。
密钥走环境变量，不进文件
export APITOKEN_API_KEY="sk-pool-•••"
opencode
# opencode.json references it as:
# "apiKey": "{env:APITOKEN_API_KEY}"相关搜索
opencode api key not workingopencode auth error custom provider
常见问题
opencode.json 里明明写了密钥，为什么 opencode 不发送任何 API 密钥？+
{env:NAME} 占位符在启动时从 opencode 自己的环境解析。如果那个 shell 从未导出该变量，密钥就是空的。
把密钥直接粘贴进 opencode.json 安全吗？+
能用，但 env 占位符是更好的习惯：配置文件会进入备份和代码仓库，粘贴的密钥会跟着一起走。
如何判断坏的是密钥还是 URL？+
手动用 curl 拿密钥请求 baseURL。401 说明是密钥/端点配对的问题；连接错误说明是 URL 或网络。