文档中心

火山方舟

调用

接入三方工具

方舟 API 兼容 OpenAI 和 Anthropic 接口协议，支持在三方工具中使用，可参考本文进行配置及使用。

说明

本文详细介绍 Claude Code、Codex 等三方工具的接入配置。若要按标准三阶段流程把方舟模型接入生产环境（参数配置、联通性核验、突发流量爬坡、上线监控），请参考模型接入指南（LLM） - 标准流程。

个人开发场景推荐订阅 Agent Plan 套餐（套餐优惠定价、token 单价更低），接入教程参见快速开始。

方舟 Agent Plan VS 方舟 API 调用

生态兼容

为了满足开发者对 OpenAI API 和 Anthropic API 生态的使用需求，方舟 API 新增了对两类接口格式的适配支持，全面兼容主流大模型接口规范及相关工具生态。开发者无需修改核心代码，仅需切换 Base URL 与 API Key，即可实现跨平台模型调用与工具集成。

在配置三方工具时，需要配置的 Base URL 信息见下表。

接口协议	Base URL	适用工具
兼容 Anthropic 接口协议	https://ark.cn-beijing.volces.com/api/compatible	Claude Code
兼容 OpenAI 接口协议	https://ark.cn-beijing.volces.com/api/v3	Chatbox、Cherry Studio、OpenClaw（原 Clawdbot）、TRAE、Cline、Cursor、Kilo Code、Roo Code、OpenCode、Codex CLI 等。

说明

在配置工具前，需要开通所需的模型服务。

接入 Chatbox

安装步骤

通过 Chatbox 官网下载并安装合适的版本，或直接启动网页版。

配置工具

打开 Chatbox 进入 Settings 页面。

在 Model Provider 中单击添加提供商，其中 API Mode 选择 OpenAI API Compatible。

提供商添加成功后，配置以下信息。

API Key：获取API Key

API Host：https://ark.cn-beijing.volces.com/api/v3

API Path：/chat/completions

Model：选择模型并获取 Model ID

配置完成后，就可以在输入框中输入需求，与模型进行交互。

接入 Cherry Studio

安装步骤

通过 Cherry Studio 官网下载并安装 Cherry Studio 客户端。

配置工具

打开 Cherry Studio 客户端，进入设置页面。

在模型服务中点击添加提供商，其中提供商类型选择 OpenAI。

提供商添加成功后，配置以下信息。

API 密钥：获取API Key

API 地址：https://ark.cn-beijing.volces.com/api/v3

模型：点击添加模型，填写要使用的模型 ID

配置完成后，就可以在输入框中输入需求，与模型进行交互。

接入 Codex CLI

注意

对于个人开发场景，推荐订阅 Agent Plan 套餐，接入教程参见快速开始。

安装步骤

说明

Coding Plan 支持 Responses API，可以使用最新版 Codex CLI。

前提条件：安装 Node.js 18 或更新版本。

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

npm i -g @openai/codex

安装结束后，执行以下命令检查版本。

codex --version

配置工具

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

macOS/Linux

Windows

macOS/Linux 系统 Codex 配置文件路径：~/.codex/config.toml。

如果在主目录下没有.codex目录，执行以下命令创建目录。

mkdir -p ~/.codex

创建并打开配置文件。

nano ~/.codex/config.toml

编辑 config.toml，需关注的配置信息如下：

<Model ID>：按需选择模型并获取 Model ID。

env_key：设置的是环境变量名称，请不要直接修改 ARK_API_KEY，您需要在下一步设置该环境变量的值。

model = "<Model ID>"
model_provider = "volcengine"

[model_providers.volcengine]
name = "volcengine"
base_url = "https://ark.cn-beijing.volces.com/api/v3"
env_key = "ARK_API_KEY"
wire_api = "responses"

注意

model_supports_reasoning_summaries = true：开启推理能力。

model_reasoning_effort：控制思考长度，可以设置为 low、medium、high。

minimax-m2.7、kimi-k2.6、kimi-k2.7-code 不支持设置 model_supports_reasoning_summaries = true。

配置环境变量，需要将 ARK_API_KEY 环境变量设置为 API Key。

macOS / Linux
Windows
查看 Shell 类型。

echo $SHELL

将环境变量写入 Shell 配置文件，使其在新开终端时自动生效。
Zsh

# 需要将 YOUR_API_KEY 替换为 API Key。
echo 'export ARK_API_KEY="YOUR_API_KEY"' >> ~/.zshrc
source ~/.zshrc

Bash

# 需要将 YOUR_API_KEY 替换为 API Key。
echo 'export ARK_API_KEY="YOUR_API_KEY"' >> ~/.bashrc
source ~/.bashrc
CMD：环境变量设置完成后，新开 CMD 窗口生效。

# 需要将 YOUR_API_KEY 替换为 API Key。
setx ARK_API_KEY "YOUR_API_KEY"
# 新开窗口，检查环境变量是否生效
echo %ARK_API_KEY%

PowerShell：环境变量设置完成后，新开 PowerShell 窗口生效。

# 需要将 YOUR_API_KEY 替换为 API Key。
[Environment]::SetEnvironmentVariable("ARK_API_KEY", "YOUR_API_KEY", [EnvironmentVariableTarget]::User)
# 新开窗口，检查环境变量是否生效
echo $env:ARK_API_KEY

开始使用

执行以下命令启动 Codex CLI。

codex

在 Codex 中使用 Web Search 工具

在 codex 中调用方舟大模型服务时，您现在可以使用基于豆包搜索 Custom 版的 Web Search 工具。

计费说明

参见支持的工具。

开通插件

登录方舟控制台，并打开应用组件库 > 豆包搜索标签页。

在豆包搜索 Custom 版的操作列中点击开通服务。

使用方法

Codex 通过兼容 OpenAI Responses API 接口协议的服务调用豆包搜索能力。完成接入配置后，在 Codex 中对话时，如果模型判断您的问题需要通过搜索功能才能回答，那么模型会调用 Web Search 工具进行搜索。

注意

调用 Web Search 工具时，大模型可能会发起额外的 API 请求来总结搜索结果，因此会消耗额外的 token。

接入 Claude Code

注意

对于个人开发场景，推荐订阅 Agent Plan 套餐，接入教程参见快速开始。

安装步骤

前提条件：

安装 Node.js 18 或更新版本环境。

Windows 用户需安装 Git for Windows。

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

npm install -g @anthropic-ai/claude-code

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

claude --version

配置工具

完成Claude Code安装后，配置以下信息。

ANTHROPIC_BASE_URL：https://ark.cn-beijing.volces.com/api/compatible

ANTHROPIC_AUTH_TOKEN：获取API Key

ANTHROPIC_MODEL：选择模型并获取 Model ID

配置步骤如下：

编辑或新增 settings.json 文件，需要替换配置信息中的以下信息：

<ARK_API_KEY>：替换为 API Key。

<Model_Name>：替换为要使用的模型 ID。

说明

不同系统配置文件路径不同，具体如下：

macOS & Linux：~/.claude/settings.json

Windows：C:\Users\<用户名>\.claude\settings.json

下面以 doubao-seed-2-1-pro-260628 为例，配置如下：

{​
    "env": {​
        "ANTHROPIC_AUTH_TOKEN": "<ARK_API_KEY>",​
        "ANTHROPIC_BASE_URL": "https://ark.cn-beijing.volces.com/api/compatible",​
        "ANTHROPIC_MODEL": "doubao-seed-2-1-pro-260628",​
        "ANTHROPIC_DEFAULT_HAIKU_MODEL": "doubao-seed-2-0-lite-260428",​
        "ANTHROPIC_DEFAULT_SONNET_MODEL": "doubao-seed-2-1-pro-260628",​
        "ANTHROPIC_DEFAULT_OPUS_MODEL": "doubao-seed-2-1-pro-260628",​
        "CLAUDE_CODE_SUBAGENT_MODEL": "doubao-seed-2-1-pro-260628"​
    }​
}​

注意

推荐使用完整模型配置，并按任务复杂度选择模型：Haiku（轻量）、Sonnet（日常）、Opus（复杂）。

CLAUDE_CODE_SUBAGENT_MODEL 建议与主模型保持一致。

ANTHROPIC_DEFAULT_HAIKU_MODEL 建议设置为小尺寸模型，例如 doubao-seed-2-0-lite-250428，通常不会影响整体使用效果。

编辑或新增 .claude.json 文件，修改或新增 hasCompletedOnboarding 字段值为 true。

说明

不同系统配置文件路径不同，具体如下：

macOS & Linux：~/.claude.json

Windows：C:\Users\<用户名>\.claude.json

{​
  "hasCompletedOnboarding": true​
}​

保存配置文件后，在新的终端窗口执行后续命令。

使用 CC Switch

CC Switch 是一款跨平台桌面应用，专为使用 AI 编程工具的开发者设计。它帮助你统一管理 Claude Code、Claude Desktop、Codex、Gemini CLI、OpenCode、OpenClaw 和 Hermes 等受管应用的配置。

支持的平台

Windows 10 及以上

macOS 12 (Monterey) 及以上

Linux Ubuntu 22.04+ / Debian 11+ / Fedora 34+（x64 / ARM64）

安装

更多安装方式和详细说明请参考 CC Switch 官方文档。

macOS

Linux

Windows

Homebrew（推荐）：

brew tap farion1231/ccswitch
brew install --cask cc-switch

手动下载：从 Releases 页面下载 .dmg。

添加供应商

在 CC Switch 中添加供应商：

在主界面顶部图标栏选中 Claude Code 图标，点击右上角 + 进入添加新供应商。

选择自定义配置，填写以下信息：

API Key：替换为您的 API Key

请求地址： https://ark.cn-beijing.volces.com/api/compatible

展开高级选项，根据当前支持的模型范围，分别配置 Sonnet、Opus、Fable、Haiku 模型，可配置的模型见选择模型并获取 Model ID。

注意

建议 Haiku 设置为小尺寸模型。

选择右下角添加，完成供应商配置。

回到首页，点击右侧启用按钮，新开一个 Claude Code 会话使配置生效。

使用 Claude Code

启动Claude Code：进入项目目录，执行claude命令，即可开始使用Claude Code。

cd my-project
claude

模型状态验证：输入/status确认模型状态。

使用 Claude Code IDE 插件

安装 Claude Code 并配置好环境变量，具体参考接入Claude Code。

Claude Code IDE 插件依赖 Claude Code CLI 工具，需先完成 Claude Code的安装及配置。

2. 安装并使用 IDE 插件。

因 IDE 插件会迭代演进，以下内容仅供参考，具体的安装及使用可参考 Visual Studio Code、JetBrains IDEs。

Claude Code VSCode 插件

Claude Code Jetbrains 插件

说明

Claude Code VSCode 插件支持在 VSCode 及基于 VSCode 的 IDE（如 Cursor、Trae 等）中使用。

安装插件

打开 VSCode，在扩展市场搜索claude code进行安装。

配置环境变量

安装完成后，点击 VSCode 右上角的 Claude Code 图标，进入 Claude Code 页面。

在对话框中输入 /config回车进入 settings 配置页面。

在 Claude Code: Environment Variables 区域单击 Edit in settings.json，修改claudeCode.environmentVariables、claudeCode.selectedModel。

说明

需要替换配置信息中的以下信息：

<ARK_API_KEY>：替换为 API Key。

<Model_Name>：替换为上述支持的模型名称，如 doubao-seed-evolving。

```JSON​
...​
"claudeCode.environmentVariables": [​
    {​
        "name": "ANTHROPIC_BASE_URL",​
        "value": "https://ark.cn-beijing.volces.com/api/compatible"​
    },​
    {​
        "name": "ANTHROPIC_AUTH_TOKEN",​
        "value": "<ARK_API_KEY>"​
    },​
    {​
        "name": "ANTHROPIC_MODEL",​
        "value": "<Model_Name>"​
    }​
],​
"claudeCode.selectedModel": "<Model_Name>",​
...​
```​

保存配置信息后，即可开始使用 Claude Code。

在 Claude Code 中使用 Web Search 工具

在 Claude Code 中调用方舟大模型服务时，您现在可以使用基于豆包搜索 Custom 版的 Web Search 工具。

计费说明

参见支持的工具。

开通插件

登录方舟控制台，并打开应用组件库 > 豆包搜索标签页。

在豆包搜索 Custom 版的操作列中点击开通服务。

使用方法

Claude Code 通过兼容 Anthropic Messages 接口协议的服务调用豆包搜索能力。完成接入配置后，在 Claude Code 中对话时，如果模型判断您的问题需要通过搜索功能才能回答，那么模型会调用 Web Search 工具进行搜索。

注意

调用 Web Search 工具时，大模型可能会发起额外的 API 请求来总结搜索结果，因此会消耗额外的 token。

接入 OpenCode

注意

对于个人开发场景，推荐订阅 Agent Plan 套餐，接入教程参见快速开始。

安装步骤

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

npm install -g opencode-ai

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

opencode --version

配置工具

编辑OpenCode的配置文件，路径如下：

macOS / Linux：~/.config/opencode/opencode.json

Windows：C:\Users\您的用户名.config\opencode\opencode.json

以配置模型doubao-seed-evolving为例，配置信息如下。

说明

替换配置信息中的 <ARK_API_KEY>。

按需选择模型并获取 Model ID。

    {​
      "$schema": "https://opencode.ai/config.json",​
      "provider": {​
        "myprovider": {​
          "npm": "@ai-sdk/openai-compatible",​
          "name": "volcengine",​
          "options": {​
            "baseURL": "https://ark.cn-beijing.volces.com/api/v3",​
            "apiKey": "<ARK_API_KEY>"​
          },​
          "models": {​
        "doubao-seed-evolving": { ​
          "name": "doubao-seed-evolving"​
        }​
          }​
        }​
      }​
    }​

开始使用

启动OpenCode：

opencode

输入/models，选择配置的doubao-seed-evolving模型并在 OpenCode 中使用。

接入 OpenClaw（原 Clawdbot）

注意

对于个人开发场景，推荐订阅 Agent Plan 套餐，接入教程参见快速开始。

安装步骤

执行以下命令安装 OpenClaw。

macOS

Windows

curl -fsSL https://openclaw.ai/install.sh | bash

根据提示信息完成 OpenClaw 配置，配置信息如下。

注意

OpenClaw 在不断迭代，如果实际使用与以下配置存在差异，可以选择 "Skip" 或默认选项完成配置流程，后续可以参考文档配置并使用 Agent Plan。

提示信息	配置
I understand this is personal-by-default and shared/multi-user use requires lock-down. Continue?	选择 "Yes"
Setup mode	选择 “QuickStart”
Model/auth provider	选择 "Skip for now"，后续可以配置。
Default model	选择 "Keep current"
Select channel (QuickStart)	选择 “Skip for now”，后续可以配置。
Search provider	选择 “Skip for now”
Configure skills now? (recommended)	选择 “No”，后续可以配置。
Enable hooks?	选择 "Skip for now"。选择方式：按空格键选中选项，按回车键进入下一步。
How do you want to hatch your bot?	选择 "Hatch in Terminal"。

配置工具

注意

glm-5.2、deepseek-v4-flash、deepseek-v4-pro 支持 1M 上下文窗口用于包含大型代码库的长会话，可以通过 contextWindow 字段显式指定窗口大小。

Web UI 方式

终端方式

执行以下命令打开 Web UI。

openclaw dashboard

在左侧菜单栏选择配置 - Settings - Advanced，单击 Open 查看并修改配置信息。具体配置信息如下，其中需要修改的核心配置信息如下：

baseUrl：https://ark.cn-beijing.volces.com/api/v3

apiKey：获取API Key

models：选择模型并获取 Model ID

注意

如果已经配置过 OpenClaw，请勿直接覆盖原有配置，建议根据提供的配置更新models、agents 和 gateway 节点信息。其中models节点包含支持的模型列表。

```JSON​
{​
  "models": {​
    "providers": {​
      "volcengine": {​
        "baseUrl": "https://ark.cn-beijing.volces.com/api/v3",​
        "apiKey": "<ARK_API_KEY>",​
        "api": "openai-completions",​
        "models": [​
          {​
            "id": "doubao-seed-1-8-251228",​
            "name": "doubao-seed-1-8-251228"​
          }​
        ]​
      }​
    }​
  },​
  "agents": {​
    "defaults": {​
      "model": {​
        "primary": "volcengine/doubao-seed-1-8-251228"​
      },​
      "models": {​
        "volcengine/doubao-seed-1-8-251228": {}​
      }​
    }​
  },​
  "gateway": {​
    "mode": "local"​
  }​
}​
```​

配置完成后，先保存配置文件，然后单击 Update 更新配置，配置更新完成后需要重新连接服务进入 Web UI。

开始使用

打开 TUI，并查看 Gateway 状态。

openclaw tui​
/status​

打开 Web UI，在 Chat 页面进行交互。

openclaw dashboard

接入 TRAE

安装 TRAE CN

访问 TRAE 官网下载并安装对应操作系统的版本。

配置工具

选择个人用户入口登录后，点击界面右上角的设置图标，进入设置中心。

在左侧导航栏中，选择模型，在模型管理页面进行配置。

点击 + 添加模型按钮，界面上显示添加模型窗口，在窗口中配置以下信息。

服务商：火山引擎

模型：

直接从列表中选择 TRAE 预置的模型（均为默认版本）。

若希望使用其他模型，单击使用其他模型，然后在输入框中填写模型 ID 配置信息。

API 密钥：获取API Key

切换模型

在 AI 对话输入框的右下角，单击当前模型名称，在模型列表中，选择配置的模型。

选定模型后，即可使用 TRAE 进行开发任务了。

接入 Cline

注意

对于个人开发场景，推荐订阅 Agent Plan 套餐，接入教程参见快速开始。

安装步骤

打开 VSCode，在扩展市场搜索Cline安装。

配置工具

Cline插件安装完成后，您需要配置以下信息。

API Provider：OpenAI Compatible（Agent Plan 接口兼容 OpenAI 标准）

Base URL：https://ark.cn-beijing.volces.com/api/v3

API Key：获取API Key

Model ID：按需选择模型并获取 Model ID

配置完成后，就可以在输入框中输入需求，与模型进行交互。

接入 Cursor

注意

对于个人开发场景，推荐订阅 Agent Plan 套餐，接入教程参见快速开始。

安装步骤

官网下载安装包：通过 Cursor官网下载并安装Cursor。

配置工具

说明

由于 Cursor 的限制，只有订阅了 Cursor Pro 及以上套餐的用户才支持自定义配置模型。

Cursor安装完成后，Models 模块的具体配置如下：

OpenAI API Key：获取API Key

Override OpenAI Base URL：https://ark.cn-beijing.volces.com/api/v3

Add Custom Model：按需选择模型并获取 Model ID

配置完成后，即可在聊天面板中选择配置的模型进行交互。

接入 Roo Code

注意

对于个人开发场景，推荐订阅 Agent Plan 套餐，接入教程参见快速开始。

安装步骤

打开 VSCode，在扩展市场搜索Roo Code进行安装，安装完成后选择信任发布者。

配置工具

安装完成后，配置以下信息。

API Provider：OpenAI Compatible（Agent Plan 接口兼容 OpenAI 标准）

Base URL：https://ark.cn-beijing.volces.com/api/v3

API Key：获取API Key

Model：按需选择模型并获取 Model ID

配置完成后，就可以在输入框中输入需求，与模型进行交互。

接入 Kilo Code

注意

对于个人开发场景，推荐订阅 Agent Plan 套餐，接入教程参见快速开始。

安装步骤

打开 VSCode，在扩展市场搜索kilo code进行安装，安装完成后选择信任发布者。

配置工具

选择Use your own API key，然后配置以下信息。

API Provider：OpenAI Compatible（Agent Plan 接口兼容 OpenAI 标准）

Base URL：https://ark.cn-beijing.volces.com/api/v3

API Key：获取API Key

Model：按需选择模型并获取 Model ID

配置完成后，就可以在输入框中输入需求，与模型进行交互。

最近更新时间：2026.09.13 21:16:06

这个页面对您有帮助吗？

有用

无用

对比项	方舟 Agent Plan	方舟 API 调用
计费方式	预付费：订阅 Agent Plan 套餐（套餐优惠定价，token 单价更低），详见套餐概览。	后付费：按 token 用量结算。
支持模型	支持模型及 Harness	文本生成能力，可按需选择。
API Key	专属 API Key	API Key
Base URL	> 兼容 Anthropic 接口协议	> 兼容 Anthropic 接口协议