# OpenCode 接入指南

https://omnimodel.me/apps/opencode?lang=zh

> 开源终端编程代理，在配置文件里加一个 OpenAI 兼容供应商即可。

## 适用场景

适合在终端里让开源代理读项目、改文件、跑测试。OpenCode 通过 `@ai-sdk/openai-compatible` 接入 OpenAI 兼容端点，配置可以放在全局，也可以只放在某个项目里。

## 使用建议

编程代理一次任务会连续发出很多请求，输入也长，建议选上下文较长、支持工具调用的模型，并给密钥设置每日消费上限。

## 推理档位

发不发推理档位取决于你在配置里给模型设的推理参数（Chat 接口的 `reasoning_effort`）。平台按模型实际走的线路能接受的档位处理：上游不收请求的档位时改用更高一档，高过最高档时取最高档；模型不能关闭思考时，要求关闭会返回 422 `model.reasoning_off_unsupported`。每个模型的对照表见[模型目录](/catalog)里该模型的「推理档位」一节；发生改写的调用，用量明细里会显示「推理档位改写」。

## 连不通时检查

1. API 地址填 `https://omnimodel.me/v1`，不要多写 `/chat/completions`。
2. 密钥以 `key_` 开头且没有被暂停或撤销，错误码 `auth.invalid_key` 表示密钥不可用。
3. 模型 ID 与[模型目录](/catalog)一致，并且在这把密钥的可用模型里。
4. 余额不足会返回 `billing.insufficient_credit`，更多错误见[常见错误](/docs/errors)。

## 配置步骤

1. 安装：npm install -g opencode-ai。
2. 把下面这段写进 ~/.config/opencode/opencode.json，只对某个项目生效时放在项目根目录的 opencode.json。
3. 在项目目录执行 opencode，用 /models 确认选中 A2Agent 下的模型。

## 配置参数

- API 地址：`https://omnimodel.me/v1`
- API 密钥：`YOUR_API_KEY`
- 模型：`MODEL_ID`

> 这份配置按 OpenCode 官方文档整理，平台尚未实测，遇到问题请提交工单并附上请求 ID。

```json
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "a2agent": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "A2Agent",
      "options": {
        "baseURL": "https://omnimodel.me/v1",
        "apiKey": "YOUR_API_KEY"
      },
      "models": {
        "MODEL_ID": {}
      }
    }
  },
  "model": "a2agent/MODEL_ID"
}
```

## 常见问题

### 配置文件里的密钥会不会被提交到仓库？

项目根目录的 opencode.json 可能被提交。apiKey 可以改写成 {env:A2AGENT_API_KEY}，再在 shell 里导出这个变量。

### 想用多个模型怎么办？

在 models 里再加几个模型 ID，然后用 /models 切换。