# OpenCode 配置

OpenCode GUI 客户端走 OpenAI-compatible `chat/completions` 协议。把自定义 provider 指到 4AICode 后，可以在 OpenCode 里使用 `gpt-6-astra`、`gpt-5.6-sol`、`gpt-5.5`、`gpt-5.4`、`gpt-5.4-mini`、`gpt-5.3-codex` 等模型。

## 准备

- 4AICode token：在 [仪表盘 → 管理 Tokens](https://4aicode.com/tokens) 创建，格式是 `sk-4ai-...`
- Provider ID：`4aicode`
- Base URL：`https://relay.4aicode.net/v1`
- 默认模型：`gpt-5.4`
- 代码模型：`gpt-5.3-codex`

## GUI 客户端配置

打开左下角齿轮设置，进入 Provider / Models 配置页，新增一个 OpenAI-compatible 或 Custom provider。

按界面字段填写：

| 字段 | 填写 |
|---|---|
| Provider / Type | `OpenAI Compatible` 或 `Custom` |
| Name / Display name | `4AICode` |
| Provider ID | `4aicode` |
| Base URL / API Base URL | `https://relay.4aicode.net/v1` |
| API Key | `sk-4ai-xxxxxxxxxxxxxxxx` |
| Model ID | `gpt-5.4` |
| Small model ID | `gpt-5.4-mini` |
| Timeout / Request timeout | `600000` ms 或 `600` s |
| Chunk timeout / Stream timeout | `120000` ms 或 `120` s |

保存后回到主界面，在底部模型选择器里选：

```text
4AICode / GPT-5.4
```

然后新建会话，发一句：

```text
你好
```

能正常回复就表示 GUI 配置完成。

## GUI 截图里的超时错误

看到下面这类错误时，重点检查 GUI 里的 timeout 字段：

```text
Provider response headers timed out after 10000ms
```

这是 OpenCode GUI 等待 provider 响应头超时。Codex 上游首包偶尔超过 10 秒，把 GUI 高级设置里的 timeout 调高：

| 字段 | 推荐值 |
|---|---|
| Request timeout / Timeout | `600000` ms |
| Chunk timeout / Stream timeout | `120000` ms |

GUI 没有 timeout 输入框时，用下方 `opencode.json` 方式补齐。

## 配置文件方式

适合 GUI 无法直接填写 timeout 的版本。创建或编辑：

```text
~/.config/opencode/opencode.json
```

写入：

```json
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "4aicode": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "4AICode",
      "options": {
        "baseURL": "https://relay.4aicode.net/v1",
        "apiKey": "sk-4ai-xxxxxxxxxxxxxxxx",
        "timeout": 600000,
        "chunkTimeout": 120000
      },
      "models": {
        "gpt-6-astra": {
          "name": "GPT-6 Astra"
        },
        "gpt-5.6-sol": {
          "name": "GPT-5.6 Sol"
        },
        "gpt-5.6-terra": {
          "name": "GPT-5.6 Terra"
        },
        "gpt-5.6-luna": {
          "name": "GPT-5.6 Luna"
        },
        "gpt-5.5": {
          "name": "GPT-5.5"
        },
        "gpt-5.4": {
          "name": "GPT-5.4"
        },
        "gpt-5.4-mini": {
          "name": "GPT-5.4 Mini"
        },
        "gpt-5.3-codex": {
          "name": "GPT-5.3 Codex"
        }
      }
    }
  },
  "model": "4aicode/gpt-5.4",
  "small_model": "4aicode/gpt-5.4-mini"
}
```

重启 OpenCode GUI 后，在模型选择器里选择 `4AICode / GPT-5.4`。

## 交互式添加凭据

进入项目目录，启动 OpenCode：

```bash
opencode
```

在 OpenCode 里运行：

```text
/connect
```

按提示选择并填写：

```text
Provider: Other
Provider ID: 4aicode
API key: sk-4ai-xxxxxxxxxxxxxxxx
```

然后创建或编辑项目根目录的 `opencode.json`，内容参考上方“配置文件方式”。

回到 OpenCode 后运行：

```text
/models
```

选择 `4AICode` 下的模型。

## 环境变量方式

把 token 放到环境变量里，适合团队共享 `opencode.json`。

```bash
export FOURAICODE_API_KEY="sk-4ai-xxxxxxxxxxxxxxxx"
```

`opencode.json`：

```json
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "4aicode": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "4AICode",
      "options": {
        "baseURL": "https://relay.4aicode.net/v1",
        "apiKey": "{env:FOURAICODE_API_KEY}",
        "timeout": 600000,
        "chunkTimeout": 120000
      },
      "models": {
        "gpt-6-astra": {
          "name": "GPT-6 Astra"
        },
        "gpt-5.6-sol": {
          "name": "GPT-5.6 Sol"
        },
        "gpt-5.6-terra": {
          "name": "GPT-5.6 Terra"
        },
        "gpt-5.6-luna": {
          "name": "GPT-5.6 Luna"
        },
        "gpt-5.5": {
          "name": "GPT-5.5"
        },
        "gpt-5.4": {
          "name": "GPT-5.4"
        },
        "gpt-5.4-mini": {
          "name": "GPT-5.4 Mini"
        },
        "gpt-5.3-codex": {
          "name": "GPT-5.3 Codex"
        }
      }
    }
  },
  "model": "4aicode/gpt-5.4",
  "small_model": "4aicode/gpt-5.4-mini"
}
```

## 全局配置路径

用户级配置放这里：

```text
~/.config/opencode/opencode.json
```

项目级配置放项目根目录：

```text
opencode.json
```

项目级配置优先级更高，适合给单个代码仓库固定 provider 和模型。

## 可用模型

| 模型 | OpenCode model 写法 | 适用场景 |
|---|---|---|
| `gpt-6-astra` | `4aicode/gpt-6-astra` | 新一代旗舰，按官方价 1.5 折计费 |
| `gpt-5.6-sol` | `4aicode/gpt-5.6-sol` | 旗舰，复杂编码、长任务、多文件重构 |
| `gpt-5.6-terra` | `4aicode/gpt-5.6-terra` | 均衡档，性价比高 |
| `gpt-5.6-luna` | `4aicode/gpt-5.6-luna` | 轻量任务，更便宜更快 |
| `gpt-5.5` | `4aicode/gpt-5.5` | 上一代旗舰 |
| `gpt-5.4` | `4aicode/gpt-5.4` | 推荐默认选择，通用任务更稳 |
| `gpt-5.4-mini` | `4aicode/gpt-5.4-mini` | 轻量任务、快速验证、成本敏感场景 |
| `gpt-5.3-codex` | `4aicode/gpt-5.3-codex` | 代码优化、Codex 风格任务 |

模型字段使用 OpenCode 的完整写法，例如 `4aicode/gpt-5.3-codex`。界面展示名可以写成 `GPT-5.3 Codex`。

## 常见问题

### Provider response headers timed out after 10000ms

这是 OpenCode GUI 等待 provider 响应头超时。Codex 上游首包偶尔超过 10 秒，配置里把 `timeout` 和 `chunkTimeout` 调高：

```json
{
  "provider": {
    "4aicode": {
      "options": {
        "baseURL": "https://relay.4aicode.net/v1",
        "timeout": 600000,
        "chunkTimeout": 120000
      }
    }
  }
}
```

然后用 `gpt-5.4-mini` 发一句 `你好` 做快速连通性测试。连通后再切回 `gpt-5.4` 或 `gpt-5.3-codex`。

### 401 Unauthorized

API key 已失效或复制错误。到 [仪表盘 → 管理 Tokens](https://4aicode.com/tokens) 重新创建 token，并更新 `/connect` 凭据或环境变量。

### 400 模型不支持

模型名使用表格里的字面 ID。常用选择是 `4aicode/gpt-5.4` 和 `4aicode/gpt-5.3-codex`。

### 配置后模型列表没出现

检查三项：

- `/connect` 里填写的 Provider ID 是 `4aicode`
- `opencode.json` 里的 provider key 是 `"4aicode"`
- `model` 使用 `4aicode/gpt-5.4` 这种完整写法

## 参考

- [OpenCode Providers](https://opencode.ai/docs/providers/)
- [OpenCode Config](https://opencode.ai/docs/config/)