文档中心

火山方舟

接入 AI 工具

Hermes Agent

本文介绍如何配置方舟 Agent Plan 到 Hermes Agent 中使用。

一、前提条件

您已按需订阅 Agent Plan 套餐。如未，请访问开通管理-Agent Plan 页面订阅套餐。

支持在 macOS、Linux 和 Windows 系统中安装 Hermes Agent

二、安装 Hermes Agent

根据操作系统执行以下命令安装 Hermes Agent，安装过程中会检测并安装 uv、Python、Node.js、ripgrep、ffmpeg 等依赖，安装完成后重新加载 Shell 或终端。更多安装说明参见 Hermes Agent 官方文档。

macOS / Linux

Windows

执行以下 cURL 命令安装：

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

安装完成后重新加载 Shell。

source ~/.bashrc # or: source ~/.zshrc

三、配置 Hermes Agent

方式 1：自动化助手（推荐）

ArkCLI Helper 是一个编码工具助手，支持快速配置选择的工具接入 Agent Plan。安装并运行该助手，根据界面提示操作可自动完成工具配置，降低手动配置的时间成本和出错风险。

注意

ArkCLI Helper 是基于 Ark Helper 升级演进的工具配置服务，相关能力将持续在 ArkCLI Helper 上迭代更新。建议优先使用 ArkCLI Helper 完成工具配置。

ArkCLI Helper 支持 macOS、Linux、Windows 系统。

安装 Ark CLI。

# 1. 通过 NPM 安装
npm install -g @volcengine/ark-cli@latest

# 2. 验证安装
arkcli --version

arkcli auth login

根据界面提示选择登录方式。若之前已登录过 arkcli，会沿用上次选择的配置；如需重新选择，请先执行 arkcli config reset 后再运行 arkcli auth login。首次登录时，按提示完成以下配置：

选择项目（Project）：可按需选择，或默认选择账号全部资源。

选择消费模式（Type）：选择 agent-plan。

运行 ArkCLI Helper，根据界面提示完成 Hermes Agent 的配置。

在命令行界面输入 arkcli helper 命令，启动 ArkCLI Helper。

选择要配置的 Plan profile：agent-plan_cn-beijing_personal (Agent Plan)。

选择默认 model：按需选择。

选择要配置的 AI Agent：Hermes Agent。

当前支持的 Harness 包括：豆包搜索、专业数据集、Agent 记忆（OpenViking）、AI Native 应用开发底座，根据界面提示按需选择配置或者跳过。

完成上述操作后，将自动完成 Hermes Agent 的基础配置，并按选择结果自动安装对应的 Harness 工具，无需手动安装。

方式 2：手动配置

Agent Plan 兼容 OpenAI 接口协议，支持 Responses API、Chat API。推荐使用 Responses API 的配置，推理效果更好。

Responses API

Chat API

注意

使用 Responses API，需要配置 api_mode: codex_responses。

执行以下命令配置 Hermes Agent，其中需要将 <ARK_API_KEY> 替换为您自己的专属 API Key，可用的模型参见支持模型及 Harness。

hermes config set model.provider custom​
hermes config set model.base_url https://ark.cn-beijing.volces.com/api/plan/v3​
hermes config set model.api_key <ARK_API_KEY>​
hermes config set model.default ark-code-latest​
hermes config set model.api_mode codex_responses​

配置完成后，配置文件 ~/.hermes/config.yaml 内容如下。您也可以直接编辑该配置文件。

model:​
  default: ark-code-latest​
  provider: custom​
  base_url: https://ark.cn-beijing.volces.com/api/plan/v3​
  api_key: <ARK_API_KEY>​
  api_mode: codex_responses​

说明

如需使用 1MB 上下文，直接选择支持 1M 上下文的模型，Hermes Agent 会自动完成调整，无需手动配置。

若模型本身支持 1M 上下文，但 Hermes Agent 未正确识别，可在 ~/.hermes/config.yaml 中手动添加或修改相应模型的 context_length 字段：context_length: 1048576。

四、启动并使用 Hermes Agent

执行以下命令开启 Hermes Agent。

hermes

开始使用 Hermes Agent，支持的 CLI Interface 参见官方文档。

其他操作

添加图片生成/视频生成能力

方舟 Agent Plan Medium 及以上套餐提供图片生成模型配额，Large 及以上套餐提供视频生成模型配额。方舟提供 Skill 帮助 AI 工具快速接入并使用。具体配置方法请参见：配置视觉模型。

注意

不同的套餐支持的视觉模型有所不同，具体参见支持模型及 Harness。

视觉模型不支持通过 Auto 及控制台切换使用。

切换模型

你可以随时根据需求切换文本生成模型。

配置方式	通过控制台	修改配置文件
切换模型操作	参考三、配置 Hermes Agent配置模型名称为ark-code-latest。在开通管理页面选择要使用的模型，切换后3-5分钟即可生效。	参考三、配置 Hermes Agent配置模型名称为您需要的模型。