# Hermes Agent
> 全部文档的索引见 [llms.txt](https://ark.volcengine.com/llms.txt)；在任一文档页面地址后追加 `.md` 可获取该页的 Markdown 版本。
本文介绍如何在 Hermes Agent 中配置并使用方舟 Agent Plan 企业版。
# 前提条件
* 需由管理员账号完成以下前置操作后，子账号方可配置并使用 Hermes Agent：
1. 购买方舟 Agent Plan 企业版套餐：[一、购买 Agent Plan 企业版](/docs/agent-plan-enterprise-get-started#purchase-plan)。
2. 为子账号分配席位：[二、分配席位](/docs/agent-plan-enterprise-get-started#assign-seats)。
* 支持在 macOS、Linux 和 Windows 系统中安装 Hermes Agent。
# 安装 Hermes Agent
根据操作系统执行以下命令安装 Hermes Agent，安装过程中会检测并安装 uv、Python、Node.js、ripgrep、ffmpeg 等依赖，安装完成后重新加载 Shell 或终端。更多安装说明参见 [Hermes Agent 官方文档](https://hermes-agent.nousresearch.com/docs/getting-started/installation)。
**选项：macOS / Linux**
1. 执行以下 cURL 命令安装：
```Bash
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
```
2. 安装完成后重新加载 Shell。
```Bash
source ~/.bashrc # or: source ~/.zshrc
```
**选项：Windows**
1. 在 PowerShell 中执行以下命令安装：
```PowerShell
iex (irm https://hermes-agent.nousresearch.com/install.ps1)
```
2. 安装完成后重新打开 PowerShell 窗口，或执行 `. $PROFILE` 刷新环境变量。
# 配置 Hermes Agent
## 需配置的信息
如您对 Hermes Agent 熟悉，或本地已有配置，可获取以下信息直接配置。
* **Base URL**：`https://ark.cn-beijing.volces.com/api/plan/v3`。
* **API Key**：[获取专属 API Key](https://ark.volcengine.com/region:cn-beijing/subscription/agent-plan-enterprise/mine)。
* **Model**：配置文本生成模型。可配置 `ark-code-latest` 或 Model Name，模型信息参见[支持模型及 Harness](/docs/agent-plan-enterprise-plan-overview#supported-models-harness)。
## 方式 1：一键配置（推荐）
Ark CLI 是火山方舟平台官方命令行工具，支持在本地终端快速完成认证与资源管理，并可将能力安装到常用 AI Agent 中，降低手动配置的时间成本和出错风险。
1. 安装 Ark CLI
环境要求：Node.js 18 或更新版本。支持 macOS、Linux、Windows。
```Bash
npm install -g @volcengine/ark-cli@latest
arkcli --version
```
2. 登录 Ark CLI
根据界面提示选择登录方式，推荐选择 **火山 SSO (浏览器登录)**，在浏览器中完成授权即可。
```Bash
arkcli auth login
```
3. 一键配置 Hermes Agent
```Bash
arkcli helper
```
运行 ArkCLI Helper，根据界面提示完成配置。
* **选择 Profile**：`agent-plan-team_cn-beijing_team`。
* **选择默认 model**：按需选择。
* **选择 AI Agent**：`Hermes Agent`。
支持配置 Harness 能力，根据界面提示按需选择`配置`或者`跳过`。
配置完成后，Hermes Agent 会自动识别配置的模型。启动 Hermes Agent 即可使用。
## 方式 2：手动配置
Agent Plan 企业版兼容 OpenAI 接口协议，支持 Responses API、Chat API。推荐使用 Responses API 的配置，推理效果更好。
**选项：Responses API**
> 使用 Responses API，需要配置 `api_mode: codex_responses`。
执行以下命令配置 Hermes Agent，其中需要将 `` 替换为您自己的 [专属 API Key](https://ark.volcengine.com/region:cn-beijing/subscription/agent-plan-enterprise/mine)，可用的模型参见[支持模型及 Harness](/docs/agent-plan-enterprise-plan-overview#supported-models-harness)。
```Bash
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
hermes config set model.default ark-code-latest
hermes config set model.api_mode codex_responses
```
配置完成后，配置文件 `~/.hermes/config.yaml` 内容如下。您也可以直接编辑该配置文件。
```YAML
model:
default: ark-code-latest
provider: custom
base_url: https://ark.cn-beijing.volces.com/api/plan/v3
api_key:
api_mode: codex_responses
```
**选项：Chat API**
> 使用 Chat API，需要配置 `api_mode: chat_completions`。
执行以下命令配置 Hermes Agent，其中需要将 `` 替换为您自己的 [专属 API Key](https://ark.volcengine.com/region:cn-beijing/subscription/agent-plan-enterprise/mine)，可用的模型参见[支持模型及 Harness](/docs/agent-plan-enterprise-plan-overview#supported-models-harness)。
```Bash
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
hermes config set model.default ark-code-latest
hermes config set model.api_mode chat_completions
```
配置完成后，配置文件 `~/.hermes/config.yaml` 内容如下。您也可以直接编辑该配置文件。
```YAML
model:
default: ark-code-latest
provider: custom
base_url: https://ark.cn-beijing.volces.com/api/plan/v3
api_key:
api_mode: chat_completions
```
> **说明**
>
> * 如需使用 1M 上下文，直接选择支持 1M 上下文的模型，Hermes Agent 会自动完成调整，无需手动配置。
> * 若模型本身支持 1M 上下文，但 Hermes Agent 未正确识别，可在 `~/.hermes/config.yaml` 中手动添加或修改相应模型的 `context_length` 字段：`context_length: 1048576`。
# 使用 Hermes Agent
1. 执行以下命令开启 Hermes Agent。
```Bash
hermes
```
2. 开始使用 Hermes Agent，支持的 CLI Interface 参见 [官方文档](https://hermes-agent.nousresearch.com/docs/user-guide/cli)。
# 其他操作
## 添加图片生成/视频生成能力
方舟 Agent Plan 企业版 Team Medium 及以上套餐提供图片生成模型配额，Team Large 及以上套餐提供视频生成模型配额。方舟提供 Skill 帮助 AI 工具快速接入并使用。具体配置方法请参见 [配置视觉模型](/docs/agent-plan-enterprise-visual-models)。
> **注意**
>
> * 不同的套餐支持的视觉模型有所不同，具体参见[支持模型及 Harness](/docs/agent-plan-enterprise-plan-overview#supported-models-harness)。
> * 视觉模型不支持通过 Auto 及控制台切换使用。
## 切换模型
你可以随时根据需求切换**文本生成模型**。
|配置方式 |通过控制台 |修改配置文件 |
|---|---|---|
|切换模型操作 |1. 参考[配置 Hermes Agent](/docs/agent-plan-enterprise-hermes-agent#14207659)，将 `model.default` 配置为 `ark-code-latest`。 |1. 参考[配置 Hermes Agent](/docs/agent-plan-enterprise-hermes-agent#14207659)，将 `model.default` 配置为需要使用的 Model Name。 | \
| |2. 在 [订阅页面](https://ark.volcengine.com/region:cn-beijing/subscription/agent-plan-enterprise?agentMode=close)，选择**我的** - **使用配置**，选择要使用的模型，切换后 3-5 分钟即可生效。 |2. 重新启动 Hermes Agent 后生效。 |
## 接入飞书机器人
> **注意**
>
> 本文档基于 Hermes Agent v0.8.0（2026.4.8）编写，工具迭代演进过程配置步骤可能会有差异，可参考以下内容配置关键信息。
1. 单击 [链接](https://open.larkoffice.com/page/openclaw?form=multiAgent) 快速创建飞书机器人。
2. 在终端执行以下命令配置信息平台。
```Bash
hermes gateway setup
```
* **Select a platform to configure**：选择 `Feishu / Lark`
* **How would you like to set up Feishu / Lark**：选择 `Scan QR code to create a new bot automatically (recommended)`，通过飞书客户端扫描二维码后，创建飞书机器人。
* **How should direct messages be authorized**：选择 `Use DM pairing approval`
* **How should group chats be handled**：选择`Respond only when @mentioned in groups`
* **Home chat ID**：暂不配置
* 选择 **done** 后， **Install the gateway as a launchd service**：选择 `Y`
* **Start the service now**：选择 `Y`
3. 在飞书打开刚创建的飞书机器人，发送任意消息获取配对码。
4. 在终端执行以下命令对飞书进行配置，其中``需替换为获取的配对码。
```Bash
hermes pairing approve feishu
```
5. 在飞书中发送`/sethome`命令将飞书会话设置为主会话，然后即可正常在飞书中使用 Hermes Agent。
