> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# 从 Hermes Agent 迁移到 Octop

一条命令把 Hermes Agent 的模型、人设与记忆、你自己安装的技能、MCP 服务器和聊天通道读进 Octop 的一位专家。命令只读取原来的目录，不会修改或删除其中的文件，迁移后两边可以并存。适用于 Octop 1.0.3b5 及以上。

步骤和 [OpenClaw](/guide/migrate/openclaw.md) 相同，把命令里的 `openclaw` 换成 `hermes`。这一页只写 Hermes 自己的路径、凭证和差异。LightClaw 走备份恢复，见[从 LightClaw 迁移](/guide/migrate/lightclaw.md)。

## 会迁移什么

| 类别      | Hermes Agent 里的位置                                                             | 迁到 Octop 之后                                     |
| ------- | ----------------------------------------------------------------------------- | ----------------------------------------------- |
| 模型      | `config.yaml` 的 `model`、`providers`（或旧版 `custom_providers`）。API Key 取自 `.env` | 模型供应商。Octop 还没有默认模型时，原来的主模型成为默认模型               |
| 人设与记忆   | `SOUL.md`，以及 `memories/MEMORY.md`、`memories/USER.md`                          | 专家工作区根目录里的同名文件                                  |
| 技能      | `~/.hermes/skills` 里你自己安装的技能                                                  | 这位专家的技能，迁移后即启用                                  |
| MCP 服务器 | `config.yaml` 的 `mcp_servers`                                                 | 你的自定义连接器。请求头里的 `${env:变量名}` 会先用 `.env` 里的值替换再保存 |
| 聊天通道    | `~/.hermes/.env` 里下表这些平台的凭证                                                   | 专家的通道，默认不启用。没有设置的平台不迁入                          |

| 通道       | `.env` 中的变量                                   |
| -------- | --------------------------------------------- |
| Telegram | `TELEGRAM_BOT_TOKEN`                          |
| Discord  | `DISCORD_BOT_TOKEN`                           |
| 飞书       | `FEISHU_APP_ID`、`FEISHU_APP_SECRET`           |
| 钉钉       | `DINGTALK_CLIENT_ID`、`DINGTALK_CLIENT_SECRET` |
| 企业微信     | `WECOM_BOT_ID`、`WECOM_SECRET`                 |
| QQ       | `QQ_APP_ID`、`QQ_CLIENT_SECRET`                |

不会迁入的内容出现在结果末尾：

- Hermes 自带的技能。记录在 `skills/.bundled_manifest` 里的技能会跳过，只迁你自己装的。
- 定时任务。在 **自动化** 里新建，或用 `octop cron create`。见[定时任务](/guide/guides/cron-jobs.md)。
- 使用 SSE 传输的 MCP 服务器。换成 Streamable HTTP 地址后，在 **连接器** 里手动添加。
- 只能用 OAuth 登录的模型账号，以及 Octop 里没有对应类型的模型供应商。
- Octop 暂不支持的通道，例如 Slack、Matrix、Mattermost。

## 开始之前

在装有 Hermes Agent 的那台机器上安装并初始化 Octop。

默认读取 `~/.hermes`，也认 `HERMES_HOME`。目录在别处时加上 `--from`。

准备一位接收内容的专家。在 **专家** 页点 **新建专家**，或运行 `octop agent create assistant`。记下卡片名字下面的 **专家 ID**。下文示例用 `1S3N3P`。


> **提示**
> 
> 迁移时不必停掉 Hermes Agent。只有在启用聊天通道之前，才需要先停掉原来的机器人。
> 


## 预演并执行

```bash
octop migrate hermes --agent 1S3N3P --dry-run
octop migrate hermes --agent 1S3N3P
```


![Hermes Agent 预演结果](/images/migrate/zh/hermes-dry-run.png "预演结果")


![Hermes Agent 迁移完成](/images/migrate/zh/hermes-done.png "迁移完成")

预演不写入任何内容。状态分为「将迁移 / 已迁移」「已跳过」和「失败」。**说明**列写了跳过或失败的原因。


> **说明**
> 
> Octop 正在运行时需要重启，新的模型供应商和通道才会加载。用系统服务运行时执行 `octop service restart`。在终端里用 `octop run` 运行的，按 Ctrl+C 停止后重新运行。
> 


## 在页面上核对

- **模型** — 打开 **管理 → 模型配置**。某一项的说明是「未找到 API Key」时，在这里补上密钥。
- **人设与记忆** — 在专家卡片上点 **编辑工作区**。`SOUL.md`、`MEMORY.md` 和 `USER.md` 在工作区根目录。
- **技能** — 打开 **个性化 → 技能**。迁过来的技能已经安装并启用。自带技能不在这里。
- **MCP** — 打开 **连接器 → 已启用连接器**。点卡片可以查看或修改命令、地址和请求头。


![迁移过来的模型供应商](/images/migrate/zh/models.png "模型配置")


![迁移过来的技能](/images/migrate/zh/skills.png "技能")


![迁移过来的 MCP 服务器](/images/migrate/zh/connectors.png "连接器")

## 启用聊天通道


> **注意**
> 
> 同一个机器人如果同时被 Hermes Agent 和 Octop 接管，一条消息会被回复两次，或者两边互相抢消息。所以迁过来的通道默认不启用。
> 



![迁移过来的通道默认不启用](/images/migrate/zh/channels.png "通道")


### 停掉原来的机器人

停掉 Hermes Agent 的网关或服务，确认它已经不再回复。

### 核对凭证

打开 **个性化 → 通道**。点通道卡片，确认 Token、App ID 等凭证已经带过来，点 **检测连接**。

### 启用

打开 **启用频道** 并保存。给机器人发一条消息试试。


![通道设置里已经带上原来的凭证](/images/migrate/zh/channel-telegram.png "通道设置")

## 命令选项

| 选项            | 作用                                                              |
| ------------- | --------------------------------------------------------------- |
| `--agent`     | 迁到哪位专家。不填时用 `octop agent use` 设置的默认专家                           |
| `--from`      | 原来的目录不在 `~/.hermes` 或 `HERMES_HOME` 时，指定那个目录                    |
| `--skip`      | 跳过一类内容，可写多次：`models`、`files`、`skills`、`mcp`、`channels`          |
| `--overwrite` | 覆盖已存在的工作区文件、技能和默认模型                                             |
| `--dry-run`   | 只预演，不写入                                                         |
| `--user`      | 管理员替其他用户迁移时，指定 MCP 连接器归属的用户                                     |
| `--json`      | 写在 `migrate` 前面，例如 `octop --json migrate hermes --agent 1S3N3P` |

可以重复运行。已经存在的内容会跳过。`--overwrite` 只覆盖工作区文件、技能和默认模型。模型供应商、MCP 连接器和通道不会被覆盖。要重新迁入它们，先在页面里删掉对应条目，再运行一次。

## 常见问题

**提示「未找到 Hermes 的安装目录」。** 用 `--from` 指定目录，例如 `--from /srv/hermes`。

**提示 `--agent is required`。** 加上 `--agent`，或先运行 `octop agent use`。

**有一项显示「失败」。** 看 **说明** 列，修正后再运行一次。已经成功的内容会跳过。有失败项时退出码为 1。

**迁完后对话里选不到模型。** 确认已经重启 Octop，并在 **管理 → 模型配置** 里检查供应商的 API Key 和地址。

**还想把 OpenClaw 迁进同一位专家。** 可以。后运行的那条遇到同名的人设文件、技能或已经设置的默认模型会跳过。希望两边分开时，各建一位专家。
