> ## Documentation Index
> Fetch the complete documentation index at: https://docs.siflow.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# OpenCode

> 了解如何在 OpenCode 的 opencode.json 中添加 custom OpenAI-compatible provider，接入 siflow endpoint，让终端、桌面端和 IDE extension 使用算秩模型。

[OpenCode](https://opencode.ai) 是一个开源 AI coding agent，提供 terminal-based interface、desktop app 和 IDE extension。它们都由同一个 `opencode.json` 驱动，因此下面的 provider 配置适用于所有形态。OpenCode 支持 custom OpenAI-compatible providers，所以可以将 siflow endpoint 添加为 provider。

## 配置

### 1. 安装 OpenCode

<CodeGroup>
  ```bash macOS/Linux (install script) theme={null}
  curl -fsSL https://opencode.ai/install | bash
  ```

  ```bash npm theme={null}
  npm install -g opencode-ai
  ```

  ```bash macOS (Homebrew) theme={null}
  brew install anomalyco/tap/opencode
  ```
</CodeGroup>

Arch、Docker 和其他安装方式请参考 [官方文档](https://opencode.ai/docs/)。Install script 和 Homebrew 会提供 standalone binary，不需要 Node.js；npm 方式需要先安装 Node。

### 2. 配置 provider

在 [API 密钥](https://console.siflow.cn/model-inference/api_keys) 页面创建 API Key，然后编辑 `~/.config/opencode/opencode.json`，或项目级的 `opencode.json`。

Project config 会覆盖 global config，两者会合并。如果是新机器，请先创建目录：

```bash theme={null}
mkdir -p ~/.config/opencode
```

```json theme={null}
{
  "$schema": "https://opencode.ai/config.json",
  "model": "siflow/glm-5.2",
  "provider": {
    "siflow": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "siflow",
      "options": {
        "baseURL": "https://api.siflow.cn/model-api/v1",
        "apiKey": "{env:SIFLOW_API_KEY}"
      },
      "models": {
        "glm-5.2": {
          "name": "siflow glm-5.2",
          "limit": { "context": 131072, "output": 8192 }
        }
      }
    }
  }
}
```

导出 key 并启动 OpenCode：

```bash theme={null}
export SIFLOW_API_KEY="<Your API Key>"
opencode
```

<Warning>
  `export` 只在当前 shell session 中有效。新的终端中变量会消失，`{env:...}` 会静默解析为空字符串，导致请求因认证错误失败。若需长期生效，请将 export 行添加到 `~/.bashrc` 或 `~/.zshrc`。在 CI 或 containers 中，请以 secret 注入。
</Warning>

| 字段                                | 说明                                                                                                                      |
| --------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `model`                           | 默认模型，格式为 `provider/model`。这样可以固定使用算秩，而无需每次会话手动选择。                                                                       |
| `provider.siflow.npm`             | 对于算秩这类 chat-completions APIs，使用 `@ai-sdk/openai-compatible`。                                                            |
| `provider.siflow.options.baseURL` | siflow OpenAI-compatible endpoint：`https://api.siflow.cn/model-api/v1`。                                                 |
| `provider.siflow.options.apiKey`  | 从 `SIFLOW_API_KEY` 环境变量读取。                                                                                              |
| `provider.siflow.models`          | 要暴露的模型 ID，例如 `glm-5.2`。                                                                                                 |
| `models.*.limit`                  | Context/output token budgets。Built-in providers 会从 models.dev 自动获取这些信息，但 custom providers 必须手动设置，否则 OpenCode 无法跟踪剩余上下文。 |

<Warning>
  请使用原生支持 tool calling 的模型。OpenCode 的核心工作流依赖它执行文件和命令操作。
</Warning>

## 验证

先运行快速配置检查：

```bash theme={null}
opencode models siflow
```

它应该列出 `glm-5.2`。

然后运行非交互 one-shot 任务：

```bash theme={null}
opencode run -m siflow/glm-5.2 "introduce this project in one sentence"
```

也可以交互式启动 `opencode`，运行 `/models`，选择 **siflow / glm-5.2**，然后给它一个编码任务，确认 tool calls 和 streaming output 正常工作。

## 其他界面

* **IDE extension**：在 VS Code、Cursor、Windsurf 或 VSCodium 中，OpenCode extension 会在第一次从 integrated terminal 运行 `opencode` 时自动安装。也可以从 marketplace 安装 **OpenCode**。快捷启动键为 `Cmd+Esc` / `Ctrl+Esc`。它运行的是同一个 OpenCode，并使用同一份配置。
* **Web UI**：`opencode web` 会启动本地 server 并打开浏览器 UI。它与 TUI 共享 sessions 和 state。

## 常见问题

* 如果 provider 没有显示，请检查 JSON 语法。`opencode.json` 也可以放在项目根目录，支持 `.jsonc`，并且 `OPENCODE_CONFIG` 可以指向自定义路径。
* 如果认证失败，请确认 `SIFLOW_API_KEY` 已在启动 `opencode` 的 shell 中 export。未设置的环境变量会静默变成空字符串。