文档中心

火山方舟

调用

接入三方工具

方舟 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 等。

说明

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

方舟 API 已内置 Web Search 等工具，开通后即可在 Claude Code、Codex CLI 等三方工具中直接使用，推荐优先使用。若您的使用场景未被内置工具覆盖，也可以在三方工具中自行接入二方、三方的 MCP Server 与 Skill，扩展模型可用的能力，各工具的接入方式见下文对应章节。

获取 MCP Server

二方：访问智能体工具商店，获取火山引擎生态内的 MCP 工具（如巨量千川、知识库等），在 MCP 详情页获取服务地址与鉴权信息。

三方：接入其他 MCP 市场提供的 MCP Server，或自行部署开源 MCP Server。

注意

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

接入 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。

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

配置工具

创建并打开 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 中使用 Web Search 工具

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

计费说明

参见支持的工具。

开通插件

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

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

使用方法

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

注意

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

接入二方/三方 MCP Server

若内置工具未覆盖您的使用场景，可在 Codex CLI 中接入二方、三方 MCP Server（获取方式参见获取 MCP Server）。

编辑 ~/.codex/config.toml（Windows 为 %USERPROFILE%\.codex\config.toml），添加 MCP Server 配置。

配置完成后重启 Codex CLI 生效。

接入 Claude Code

注意

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

安装步骤

前提条件：

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

Windows 用户需安装 Git for Windows。

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

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

配置工具

完成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 为例，配置如下：

注意

推荐使用完整模型配置，并按任务复杂度选择模型：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

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

使用 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。

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

在 Claude Code 中使用 Web Search 工具

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

计费说明

参见支持的工具。

开通插件

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

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

使用方法

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

注意

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

接入二方/三方 MCP Server 与 Skill

若内置工具未覆盖您的使用场景，可在 Claude Code 中接入二方、三方 MCP Server 与 Skill（MCP Server 获取方式参见获取 MCP Server）。

接入 MCP Server：执行以下命令添加（以 stdio 类型为例）。

claude mcp add <MCP名称> -- <启动命令> <启动参数>

添加完成后，可执行 claude mcp list 查看已接入的 MCP Server。更多说明（如 HTTP/SSE 类型、作用域管理）参考 Claude Code 官方文档。

接入 Skill：将 Skill 目录放入 ~/.claude/skills/（个人全局）或项目下的 .claude/skills/ 目录即可，详情参考 Claude Code Skills 说明。

接入 OpenCode

注意

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

安装步骤

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

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

配置工具

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

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

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

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

说明

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

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

开始使用

启动OpenCode：

opencode

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

接入二方/三方 MCP Server

若内置工具未覆盖您的使用场景，OpenCode 支持在设置中配置二方、三方 MCP Server（获取方式参见获取 MCP Server），具体操作参考 OpenCode 官方文档。

接入 OpenClaw（原 Clawdbot）

注意

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

安装步骤

执行以下命令安装 OpenClaw。

macOS

Windows

根据提示信息完成 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。

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

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

apiKey：获取API Key

models：选择模型并获取 Model ID

注意

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

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

开始使用

打开 TUI，并查看 Gateway 状态。

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

接入 Skill

若内置工具未覆盖您的使用场景，OpenClaw 支持 Skill 配置：在安装向导中选择 Configure skills now，或后续在设置中配置，具体操作参考 OpenClaw 官方文档。

接入 TRAE

安装 TRAE CN

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

配置工具

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

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

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

服务商：火山引擎

模型：

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

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

API 密钥：获取API Key

切换模型

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

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

接入二方/三方 MCP Server

若内置工具未覆盖您的使用场景，TRAE 支持在设置中配置二方、三方 MCP Server（获取方式参见获取 MCP Server），具体操作参考 TRAE 官方文档。

接入 DeepSeek Harness

安装步骤

访问 DeepSeek Harness官网并安装对应操作系统的版本。

配置工具

方式一：通过 Web UI 手动配置

在终端执行以下命令启动 DeepSeek Harness 的 Web UI，在浏览器打开命令输出的访问地址，默认地址为 http://127.0.0.1:3080/。

npx @deepseek-ai/dsh web

在 DeepSeek Harness Web UI 中，单击左下角账号头像，点击设置。

在左侧导航栏单击模型，根据界面信息进行配置。

您可以按下面任一方式，在方舟平台接入 DeepSeek Harness。

方式1：配置 DeepSeek 卡片

在 DeepSeek 卡片，选择自定义设置，按下面信息填写并保存。

API 密钥：获取 API key

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

添加模型：按需添加模型，模型列表参见模型列表，获取 Model ID。

方式2：添加自定义提供方

单击添加模型提供商->自定义模型API，按下面信息填写完成提供方的创建。

Provider ID：自定义设置，后续如需重命名则需要添加新的提供方，并删除旧的提供方。

显式名称：自定义设置。

API 地址、API 协议：支持的 API 地址、API 协议及对应关系如下，不要配置错误。

API 协议	API 地址
openai-completions	https://ark.cn-beijing.volces.com/api/v3
openai-responses	https://ark.cn-beijing.volces.com/api/v3
anthropic-messages	https://ark.cn-beijing.volces.com/api/compatible

API 密钥：获取 API key

添加模型：按需添加模型，模型列表参见模型列表，获取 Model ID。

(可选) 如果需要给模型配置支持图片输入，则需要在配置文件中进行配置。在模型配置页面单击打开配置文件（路径$DSH_HOME/settings.yaml），在支持的模型配置部分加上 input: [text, image]。

配置示例如下：

方式二：通过火山方舟插件配置

方舟提供 DeepSeek Harness 官方插件 dsh-volcengine-plugin。安装并启用插件后，可以在火山方舟插件中配置模型的接入方式，按量付费方式需要选择接入方式为 PayGo。

启动 DeepSeek Harness。

在终端执行以下命令启动 DeepSeek Harness 的 Web UI，在浏览器打开命令输出的访问地址，默认地址为 http://127.0.0.1:3080/。

npx @deepseek-ai/dsh web

安装并启用火山方舟插件。

在 DeepSeek Harness Web UI 中，单击左侧导航插件进入插件添加入口。

输入插件包名 dsh-volcengine-plugin，单击安装。

插件安装完成后，单击立即启用。

配置火山方舟插件。

单击火山方舟插件卡片，进入插件配置页面。

在连接配置区域，选择接入方式 PayGO。

填写 API Key，单击保存。

（可选）如需调整调用协议或服务地址，展开自定义配置，按实际接入环境修改调用协议和 Base URL。

配置模型。

单击保存模型配置。

完成上述操作后，回到对话页，在输入框右下角的模型下拉菜单中选择配置的模型，即可开始使用。

接入 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

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

接入二方/三方 MCP Server

若内置工具未覆盖您的使用场景，Cline 支持在设置中配置二方、三方 MCP Server（获取方式参见获取 MCP Server），具体操作参考 Cline 官方文档。

接入 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

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

接入二方/三方 MCP Server

若内置工具未覆盖您的使用场景，Roo Code 支持在设置中配置二方、三方 MCP Server（获取方式参见获取 MCP Server），具体操作参考 Roo Code 官方文档。

接入 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

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

接入二方/三方 MCP Server

若内置工具未覆盖您的使用场景，Kilo Code 支持在设置中配置二方、三方 MCP Server（获取方式参见获取 MCP Server），具体操作参考 Kilo Code 官方文档。

最近更新时间：2026.10.29 17:35:41

这个页面对您有帮助吗？

有用

无用

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