发布日期：2026-10-22 ｜ 数据截至 2026-10-21，来源为 opencode 官方文档与 GitHub issue #58032

opencode 报错"This API key has expired. Create a new API key in OpenCode Console and replace it in your client or secret store. Signing in again will not renew this key."的根本原因是：旧 Key 已在服务端标记失效，重新登录无法续期，必须在 OpenCode Console 手动生成新 Key 并替换到本地。完整修复分三步：进入 opencode.ai 控制台吊销旧 Key → 创建新 Key → 在终端执行 /connect 粘贴新 Key；凭证写入 ~/.local/share/opencode/auth.json，不需要改任何配置文件。对于同时出现 ECONNREFUSED 127.0.0.1:8080（本地代理未启动）和"model not available in your country"（地区限制）的情况，三条报错来源各不相同，需逐一排查。如果不想再被单一 Provider 的 Key 失效打断工作，可以在 opencode.json 里接入一个兼容 OpenAI 协议的统一 API 端点，把多家模型的调用收归一个 Key 管理。

报错原文和它真正在说什么

完整错误提示：

This API key has expired.
Create a new API key in OpenCode Console and replace it in your client or secret store.
Signing in again will not renew this key.

这三句话说了三件重要的事：

  1. 已过期：Key 在服务端被标记为失效，不是网络问题，不是密码错误

  2. 需要新建：必须去控制台重新生成，没有"续期"操作

  3. 重新登录没用：OAuth 重新授权走的是不同通道，不会刷新这个 Key

三步修复

第一步：吊销旧 Key

打开浏览器访问 opencode.ai，登录后进入 OpenCode Console，找到已过期的 Key，点击吊销（Revoke）。这一步不是必须的，但能防止旧 Key 被别人拿去继续尝试。

第二步：创建新 Key

在同一个控制台页面点击 Create new API key，复制生成的 Key 字符串，不要关掉页面，因为大多数平台只显示一次完整 Key。

第三步：在 opencode 里替换

打开终端，在任意目录启动 opencode，执行：

/connect

在弹出的提供商列表里选择 OpenCode（即 OpenCode Zen），粘贴新 Key，回车确认。

opencode 会把凭证写入：

~/.local/share/opencode/auth.json   # Linux / macOS
%APPDATA%\opencode\auth.json        # Windows

写入成功后可以用 /models 命令验证是否能正常列出可用模型。

如果同时出现其他报错

在 GitHub issue #58032（opencode v2.1.2，Windows 11）里，用户在同一时间遇到了三条报错：

报错

真正原因

对应操作

This API key has expired

Key 服务端失效

按上文三步换 Key

This model is not available in your country

所选模型有地区限制

用 /models 切换其他模型

ECONNREFUSED 127.0.0.1:8080

本地代理/VPN 客户端没开，或配置文件里写了错误的 baseURL

检查本地代理状态，或清理 opencode.json 里的 baseURL 配置

这三条报错来源各不相同，混在一起很容易让人以为是同一个问题，逐一排查效率更高。

为什么 Key 会过期

opencode 的 Key 失效有几种常见来源：

1. 账单欠费自动吊销：OpenCode Zen 是后付费模式，账单逾期后平台会自动让 Key 失效。检查 opencode.ai 后台是否有未付账单。

2. 手动轮换：安全规范要求定期轮换凭证时，旧 Key 被主动吊销。

3. 安全事件后批量失效：opencode 近期发生过一次安全事件（参考 GitHub issue 中的讨论），平台对受影响账户的 Key 做了批量吊销。如果你没有手动操作过，但 Key 突然失效，可以去控制台检查是否有安全提醒。

4. Key 本身有有效期：部分平台在创建 Key 时可以设置过期时间，到期自动失效。

换成自定义 Provider，以后不怕单点失效

如果你同时使用多家模型，或者不想每次都通过 OpenCode Zen 中转，可以在 opencode.json 里直接接入兼容 OpenAI 协议的第三方端点。

配置文件位置：

~/.config/opencode/opencode.json   # Linux / macOS
%APPDATA%\opencode\opencode.json   # Windows

添加一个自定义提供商的最小配置：

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "myprovider": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "我的统一端点",
      "options": {
        "baseURL": "https://api.example.com/v1"
      },
      "models": {
        "model-id": {
          "name": "模型显示名"
        }
      }
    }
  }
}

baseURL 填入支持 /v1/chat/completions 的端点地址，api_key 通过 /connect 命令写入 auth.json，不写在配置文件里，避免 Key 明文泄露。

国内可以直接调用的统一 API 端点（同时覆盖 DeepSeek、Kimi、GLM 等多款主流模型），可以参考七牛云 Token Plan 的接入文档，一个 Key 管理多家模型调用，Key 过期只需要换一处。

换完还是报错怎么办

替换 Key 之后如果仍然报相同错误，按以下顺序排查：

  1. 确认 auth.json 已更新：用文本编辑器打开 auth.json，检查 Key 字段是否是新值

  2. 检查是否有多个 opencode 进程：旧进程可能仍在使用内存中缓存的旧 Key，重启 opencode

  3. 确认新 Key 在控制台状态为 Active：Console 里 Key 列表显示 Active 才算有效

  4. 检查网络：curl -s https://opencode.ai 返回正常再排除网络问题

总结

"This API key has expired"报错的唯一出路是：去 OpenCode Console 生成新 Key，回到终端用 /connect 替换，重新登录解决不了这个问题。如果同时出现 ECONNREFUSED 或地区限制报错，说明是三条独立问题叠在一起，分开处理。本文操作步骤来自 opencode 官方文档（opencode.ai/docs/providers）及 GitHub issue #58032，如果 Console 入口有变动以官网实际页面为准。

延伸阅读

  • opencode 官方提供商配置文档：opencode.ai/docs/providers

  • opencode GitHub issue #58032（API key expired 讨论）：github.com/anomalyco/opencode/issues/58032

  • 七牛云 Token Plan（多模型统一 API Key）：：https://www.qiniu.com/ai/models