接入 OpenCode

OpenCode 是 SST 出品的开源 Claude Code 替代方案。它可以通过 OpenAI Chat Completions 协议 或 Anthropic Messages 协议 与 xmAI 对接 — 根据你要使用的模型任选其一。

前置要求

• 已在 XmAI 控制台 注册账号并充值 / 拥有免费额度
• 已在 API Keys 页面创建一把 API Key（形如 sk-xxx...）
• 已安装 OpenCode（brew install sst/tap/opencode，或参考上游文档）

配置方式

OpenCode 读取全局配置 ~/.config/opencode/opencode.json，并可选读取项目根目录的 opencode.json（两者同 schema，项目级优先）。

版本提示

OpenCode 迭代较快，下方 provider 块结构以 opencode.ai/docs/providers 当前 schema 为准；若你本地版本字段不同，以上游文档为准。

方式 A：OpenAI 兼容模式（推荐，用于 GPT / Gemini / 混合模型）

使用 @ai-sdk/openai-compatible 适配器，指向 https://api.xmai.sg/v1：

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "xmai": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "xmAI",
      "options": {
        "baseURL": "https://api.xmai.sg/v1",
        "apiKey": "{env:XMAI_API_KEY}"
      },
      "models": {
        "gpt-4o": { "name": "GPT-4o" },
        "gpt-4o-mini": { "name": "GPT-4o mini" },
        "claude-sonnet-4-6": { "name": "Claude Sonnet 4.6（经 xmAI）" },
        "gemini-2.5-pro": { "name": "Gemini 2.5 Pro" }
      }
    }
  },
  "model": "xmai/gpt-4o"
}

在 Shell 中导出 API Key，使 {env:XMAI_API_KEY} 能被解析：

macOS / Linux / Git Bash

export XMAI_API_KEY="sk-your-xmai-key"

Windows PowerShell

$env:XMAI_API_KEY = "sk-your-xmai-key"

Windows CMD

set XMAI_API_KEY=sk-your-xmai-key
:: 仅当前会话。持久化请使用：setx XMAI_API_KEY "sk-your-xmai-key"

然后运行 opencode，状态栏应显示 xmAI / gpt-4o。Windows 下建议使用 setx 或在系统属性 → 环境变量面板中设置用户变量，以便重启 Shell 后仍然可用。

方式 B：Anthropic 兼容模式（用 /v1/messages 原生跑 Claude 模型）

使用 @ai-sdk/anthropic 适配器，指向 xmAI 根地址（不带 /v1 — Anthropic SDK 会自动拼接）：

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "xmai-anthropic": {
      "npm": "@ai-sdk/anthropic",
      "name": "xmAI（Anthropic 模式）",
      "options": {
        "baseURL": "https://api.xmai.sg",
        "apiKey": "{env:XMAI_API_KEY}"
      },
      "models": {
        "claude-opus-4-6": { "name": "Claude Opus 4.6（1M beta）" },
        "claude-sonnet-4-6": { "name": "Claude Sonnet 4.6（1M beta）" },
        "claude-3-5-sonnet-20241022": { "name": "Claude Sonnet 3.5 v2" },
        "claude-3-5-haiku-20241022": { "name": "Claude Haiku 3.5" }
      }
    }
  },
  "model": "xmai-anthropic/claude-sonnet-4-6"
}

两种模式可并存 — 同时定义两个 provider，通过 OpenCode 内的 /model 命令即时切换。

模型路由

xmAI 在同一把 Key 下聚合了多家供应商的模型，下表为快照，运行时请以 /v1/models 或 模型列表 页面为准。

xmAI model ID	供应商	典型用途
gpt-4o	OpenAI	通用 / 多模态
gpt-4o-mini	OpenAI	快速 / 低成本
claude-opus-4-6	Anthropic	最高质量（1M beta）
claude-sonnet-4-6	Anthropic	质量/成本平衡（1M beta）
claude-3-5-sonnet-20241022	Anthropic	旧版 Sonnet 3.5 v2
claude-3-5-haiku-20241022	Anthropic	快速 / 低成本
gemini-2.5-pro	Google	长上下文推理
gemini-2.5-flash	Google	快速 / 低成本

/v1/models 为权威来源。若某个 model ID 报 404 model not found，先对照模型列表。

验证接入

启动 OpenCode 后发任意一条消息，或运行 /help。然后：

1. 登录 XmAI 控制台 → 请求日志，查看是否有新记录
2. 或在 Dashboard 的 本日消费 卡片观察 credits 变化

看到新请求即接入成功。

常见问题

连接失败 / 证书错误

系统代理干扰： 若设置了 http_proxy / https_proxy，代理可能拦截 xmAI 流量。排除 xmAI 域名：

export NO_PROXY="api.xmai.sg"

自签名证书： 企业内网若走了自有证书链，导入 CA：

export NODE_EXTRA_CA_CERTS=/path/to/your-ca-chain.pem

认证失败（401 / 403）

• 确认 Key 未被禁用 / 过期：API Keys 页面检查状态
• 确认 XMAI_API_KEY 确实已在运行 opencode 的 Shell 中导出（OpenCode 会 fork 新 Shell，需确保 .zshrc / .bashrc 自动生效；Windows 下可在系统环境变量面板中设置）
• Anthropic 模式下：确认 baseURL 不带 尾随 /v1，SDK 会自动拼接 /v1/messages

模型不存在（404）

• /v1/models 是权威来源，删除未列出的 model ID
• 不要使用 anthropic/claude-3-5-sonnet 这样的前缀 — 直接用 claude-3-5-sonnet-20241022

账户余额不足（402）

xmAI 按 token 实时扣费，余额不足会返回 402 或 insufficient_balance。前往 钱包页面 补充额度，或开启自动充值。

切回原始上游

将 "model" 改回默认 OpenAI / Anthropic provider 的模型，或直接从 opencode.json 中删除 xmai / xmai-anthropic 块。

相关链接

• Chat Completions API — OpenAI 兼容底层 API
• Messages API — Anthropic 兼容底层 API
• 模型列表 — 所有可用模型与价格
• 错误码 — 错误处理指南
• Claude Code — Anthropic 原生替代
• OpenAI 兼容工具 — 其他工具的通用指南