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

# OpenCode

> 配置 OpenCode 以使用 TokenLab API

## 概述

<Note>
  **类型**: 编码工具

  **主要路径**: OpenAI 兼容

  **支持级别**: 支持路径
</Note>

OpenCode 是一个在终端中运行的开源 AI 编码助手。它支持多个 LLM 提供方，并且可以配置为使用 TokenLab 的 API，以访问数百个模型。

## 安装

<Tabs>
  <Tab title="安装脚本">
    ```bash theme={null}
    curl -fsSL https://opencode.ai/install | bash
    ```
  </Tab>

  <Tab title="Homebrew">
    ```bash theme={null}
    brew install opencode-ai/tap/opencode
    ```

    或使用社区 tap（更新更频繁）：

    ```bash theme={null}
    brew install anomalyco/tap/opencode
    ```
  </Tab>

  <Tab title="Go">
    ```bash theme={null}
    go install github.com/opencode-ai/opencode@latest
    ```
  </Tab>
</Tabs>

验证安装：

```bash theme={null}
opencode --version
```

## 配置

### 第 1 步：设置环境变量

```bash theme={null}
export OPENAI_API_KEY="sk-your-tokenlab-key"
```

如需永久配置，请添加到 `~/.bashrc` 或 `~/.zshrc`：

```bash theme={null}
echo 'export OPENAI_API_KEY="sk-your-tokenlab-key"' >> ~/.zshrc
source ~/.zshrc
```

### 第 2 步：配置 OpenCode

OpenCode 当前文档建议通过 `opencode.json` 或 `opencode.jsonc` 配置提供方。对于 TokenLab，请使用自定义提供方，而不是复用内置的 `openai` 提供方：

```jsonc theme={null}
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "tokenlab": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "TokenLab",
      "options": {
        "baseURL": "https://api.tokenlab.sh/v1",
        "apiKey": "{env:OPENAI_API_KEY}"
      },
      "models": {
        "gpt-5.4": {
          "name": "GPT-5.4"
        },
        "gpt-5-mini": {
          "name": "GPT-5 Mini"
        }
      }
    }
  },
  "model": "tokenlab/gpt-5.4"
}
```

<Note>
  使用 `@ai-sdk/openai-compatible` 以获得 chat-completions 风格的兼容性。如果你明确需要基于 `/v1/responses` 构建的提供方路径，OpenCode 文档建议将 package 切换为 `@ai-sdk/openai`。
</Note>

## 基本用法

**启动交互模式：**

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

**使用 prompt 运行：**

```bash theme={null}
opencode "Explain this codebase"
```

**指定模型：**

```bash theme={null}
opencode --model tokenlab/gpt-5.4 "Fix the bugs in main.py"
```

## 可用模型

| 模型                  | 最适合       |
| ------------------- | --------- |
| `gpt-5.4`           | 复杂任务、代码架构 |
| `gpt-5-mini`        | 快速修复、简单查询 |
| `claude-sonnet-4-6` | 代码审查、文档编写 |
| `claude-opus-4-6`   | 复杂推理      |
| `gemini-3.5-flash`  | 快速响应      |
| `deepseek-r1`       | 算法设计      |

## 常用命令

**分析代码：**

```bash theme={null}
opencode "What does this function do?" < src/utils.ts
```

**生成代码：**

```bash theme={null}
opencode "Create a REST API with Express"
```

**审查变更：**

```bash theme={null}
git diff | opencode "Review these changes"
```

**修复错误：**

```bash theme={null}
opencode "Fix the TypeScript errors in this project"
```

## 交互命令

| Command         | 描述          |
| --------------- | ----------- |
| `/help`         | 显示可用命令      |
| `/model <name>` | 切换到其他模型     |
| `/clear`        | 清除对话历史      |
| `/exit`         | 退出 OpenCode |

## 故障排查

<AccordionGroup>
  <Accordion title="连接错误">
    * 验证 `options.baseURL` 是否设置为 `https://api.tokenlab.sh/v1`
    * 检查网络连接
    * 尝试使用 `curl https://api.tokenlab.sh/v1/models` 进行测试
  </Accordion>

  <Accordion title="身份验证失败">
    * 验证是否已设置 `OPENAI_API_KEY` 环境变量
    * 验证 `options.apiKey` 是否引用了 `{env:OPENAI_API_KEY}` 或其他有效的 secret 来源
    * 检查 key 是否以 `sk-` 开头
    * 确保该 key 在 TokenLab 控制台中处于激活状态
  </Accordion>

  <Accordion title="未找到模型">
    * 检查配置中的模型名称是否完全匹配
    * 在 [tokenlab.sh/en/models](https://tokenlab.sh/zh/models) 验证模型可用性
  </Accordion>
</AccordionGroup>

## 最佳实践

<AccordionGroup>
  <Accordion title="使用项目上下文">
    从项目根目录运行 OpenCode，以便更好地理解你的代码库。
  </Accordion>

  <Accordion title="选择合适的模型">
    对简单任务使用更快的模型（`gpt-5-mini`），对复杂任务使用更强的模型（`gpt-5.4`、`claude-sonnet-4-6`）。
  </Accordion>

  <Accordion title="审查生成的代码">
    在将 AI 生成的代码应用到项目之前，务必先进行审查。
  </Accordion>
</AccordionGroup>