# OpenCode

> 全部文档的索引见 [llms.txt](https://ark.volcengine.com/llms.txt)；在任一文档页面地址后追加 `.md` 可获取该页的 Markdown 版本。

本文介绍如何在 OpenCode 中配置并使用方舟按量计费模型服务。

<span id="prerequisites"></span>
# 前提条件

在配置工具前，需要 [开通所需的模型服务](https://ark.volcengine.com/region:cn-beijing/openManagement?LLM=%7B%7D&OpenTokenDrawer=false)。

<span id="install-opencode"></span>
# 安装 OpenCode

前提条件：安装 [Node.js 18 或更新版本](https://nodejs.org/en/download/)。

在命令行界面，执行以下命令安装 OpenCode。

```Bash
npm install -g opencode-ai
```

安装结束后，执行以下命令查看安装结果，若显示版本号则安装成功。

```Bash
opencode --version
```

<span id="c807cb71"></span>
# 配置 OpenCode

<span id="configuration-information"></span>
## 需配置的信息

如您对 OpenCode 熟悉，或本地已有配置，可获取以下信息直接配置。

* **Base URL**：`https://ark.cn-beijing.volces.com/api/v3`。
* **API Key**：[获取API Key](https://ark.volcengine.com/region:cn-beijing/apikey)。
* **Model**：按需选择模型并获取 Model ID。可用模型参见[模型列表](/docs/model-list)。

<span id="method-2-manual"></span>
## 手动配置

1. 创建并打开 OpenCode 的配置文件。文件路径因系统而异，具体操作如下：

    **选项：macOS/Linux**

    macOS/Linux 系统 OpenCode 配置文件路径：`~/.config/opencode/opencode.json`。
    1. 如果在主目录下没有`.config/opencode`目录，执行以下命令创建目录。

        ```Bash
        mkdir -p ~/.config/opencode
        ```

    2. 创建并打开配置文件。

        ```Bash
        nano ~/.config/opencode/opencode.json
        ```

    **选项：Windows**

    Windows 系统 OpenCode 配置文件路径：`%USERPROFILE%\.config\opencode\opencode.json`。以 CMD 命令行方式为例，操作如下。
    1. 如果当前用户目录下没有`.config\opencode`目录，执行以下命令创建目录。

        ```Bash
        if not exist "%USERPROFILE%\.config\opencode" mkdir "%USERPROFILE%\.config\opencode"
        ```

    2. 创建并打开配置文件。

        ```Bash
        notepad "%USERPROFILE%\.config\opencode\opencode.json"
        ```

2. 编辑 `opencode.json`，需关注的配置信息如下：

    * `<ARK_API_KEY>`：替换为您自己的 [API Key](https://ark.volcengine.com/region:cn-beijing/apikey)。
    * `model`：按需选择模型并获取 Model ID。可用模型参见[模型列表](/docs/model-list)。

    按量计费模型服务兼容 OpenAI 接口协议，支持 Responses API、Chat API。推荐使用 Responses API 的配置，推理效果更好。

    支持的两类 API 仅在 npm 配置上不同：
    * Responses API 配置：`"npm": "@ai-sdk/openai"`
    * Chat API 配置：`"npm": "@ai-sdk/openai-compatible"`

    以配置 `doubao-seed-evolving` 为例，具体信息如下。

**选项：Responses API**

> **说明**
>
> npm 必须使用 `@ai-sdk/openai`，模型才会使用 Responses API，在 `baseURL` 的基础上自动拼接 `/responses`。

```JSON
{
  "$schema": "https://opencode.ai/config.json",
  "model": "volcengine/doubao-seed-evolving",
  "provider": {
    "volcengine": {
      "npm": "@ai-sdk/openai",
      "name": "Volcano Engine（Responses API）",
      "options": {
        "baseURL": "https://ark.cn-beijing.volces.com/api/v3",
        "apiKey": "<ARK_API_KEY>"
      },
      "models": {
        "doubao-seed-evolving": {
          "name": "doubao-seed-evolving"
        }
      }
    }
  }
}
```

**选项：Chat API**

> **说明**
>
> npm 必须使用 `@ai-sdk/openai-compatible`，模型才会使用 Chat API，在 `baseURL` 的基础上自动拼接 `/chat/completions`。

```JSON
{
  "$schema": "https://opencode.ai/config.json",
  "model": "volcengine/doubao-seed-evolving",
  "provider": {
    "volcengine": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Volcano Engine（Chat API）",
      "options": {
        "baseURL": "https://ark.cn-beijing.volces.com/api/v3",
        "apiKey": "<ARK_API_KEY>"
      },
      "models": {
        "doubao-seed-evolving": {
          "name": "doubao-seed-evolving"
        }
      }
    }
  }
}
```

<span id="30a7ef0d"></span>
# 使用 OpenCode

1. 启动 OpenCode：

    ```Bash
    opencode
    ```

2. 输入`/models`，选择配置的模型并在 OpenCode 中使用。

<span id="other-operations"></span>
# 其他操作

<span id="mcp-server"></span>
## 接入 MCP Server

若内置工具未覆盖您的使用场景，可在 OpenCode 中接入二方、三方 MCP Server，扩展模型可用的能力。

### 获取 MCP Server

* **二方**：访问 [智能体工具商店](https://www.volcengine.com/mcp-marketplace)，获取火山引擎生态内的 MCP 工具（如巨量千川、知识库等），在 MCP 详情页获取服务地址与鉴权信息。
* **三方**：接入其他 MCP 市场提供的 MCP Server，或自行部署开源 MCP Server。

> **注意**
>
> 请从可信来源获取 MCP Server，其安全性与稳定性由提供方负责，接入前请确认其权限范围符合您的预期。

### 配置 MCP Server

OpenCode 支持在设置中配置二方、三方 MCP Server，具体操作参考 OpenCode 官方文档。