> ## Documentation Index
> Fetch the complete documentation index at: https://ppio.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 10 分钟部署你的 Hermes Agent

> 零基础新手教程：从安装 Python 到用 PPHermes 一键部署 Hermes Agent，10 分钟完成。

<Tip>
  已有 Python 开发经验？可以直接看 [PPHermes 命令参考](https://github.com/NousResearch/hermes-agent)，里面有完整的 CLI、REST API 和飞书集成说明。
</Tip>

这篇教程带你从零开始，一步步在云端部署属于你自己的 [Hermes Agent](https://github.com/NousResearch/hermes-agent)（由 Nous Research 开发的自进化 AI Agent）。不需要任何编程基础，跟着做就行。

## 第一步：给电脑装上 Python

PPHermes 是一个基于 Python 的小工具（要求 Python 3.9+），所以需要先在电脑上装好 Python。

### Windows 用户（最关键的一步）

1. [点击这里下载 Python 安装包](https://www.python.org/downloads/)
2. 双击打开安装包

<Warning>
  **务必勾选底部的** `Add Python to PATH`。这是新手最容易漏掉的地方，不勾选的话后面所有命令都会报错。
</Warning>

3. 点击 `Install Now`，等到看到 `Setup was successful` 就可以关掉了

### macOS 用户

1. 按 `Command + 空格`，搜索"终端"（Terminal）并打开
2. 输入下面这行命令，按回车：

```bash theme={null}
python3 --version
```

* 如果显示 `Python 3.9` 或更高版本，说明已经装好了，直接跳到下一步
* 如果版本太低或没装，使用 Homebrew 安装：`brew install python`

### Linux（Ubuntu）用户

打开终端，输入：

```bash theme={null}
sudo apt update && sudo apt install python3 python3-venv python3-pip -y
```

## 第二步：获取你的 API Key

你需要一个 PPIO API Key（可以理解为"通行密钥"）来连接 PPIO 的云端 Agent 沙箱。

1. 打开 [PPIO 控制台](https://ppio.com/user/login) 并注册登录
2. 进入 [API Key 管理页面](https://ppio.com/settings/key-management)
3. 点击\*\*「创建 API Key」\*\*
4. 你会看到一串以 `sk_` 开头的字符串，复制下来找个地方存好

<Note>
  API Key 只在创建时显示一次，关掉页面就看不到了，记得及时复制保存。
</Note>

## 第三步：安装并启动

打开你的终端窗口（Windows 叫 **PowerShell**，macOS 叫**终端**）。

### 安装 PPHermes

macOS / Linux 用户输入：

```bash theme={null}
curl -fsSL https://pphermes.ppio.com/install.sh | bash
```

Windows 用户在 PowerShell 中输入：

```powershell theme={null}
irm https://pphermes.ppio.com/install.ps1 | iex
```

也可以通过 pip 安装：

```bash theme={null}
pip install pphermes
```

安装完成后，输入下面的命令验证一下：

```bash theme={null}
pphermes --help
```

如果看到类似下面这样的输出，就表示安装成功了：

```text theme={null}
Usage: pphermes [OPTIONS] COMMAND [ARGS]...

  PPHermes — Launch and manage Hermes Agent sandboxes on PPIO.

Options:
  -j, --json  Output in JSON format
  --version   Show the version and exit.
  --help      Show this message and exit.

Commands:
  doctor   Health check for Hermes gateway.
  gateway  Manage Hermes gateway in a sandbox.
  launch   Launch a new Hermes Agent sandbox.
  list     List all Hermes Agent sandboxes.
  migrate  Migrate an OpenClaw state into a Hermes sandbox.
  pair     Configure IM channels for Hermes Agent.
  pause    Pause a running Hermes Agent sandbox.
  resume   Resume a paused Hermes Agent sandbox.
  status   Get status of a Hermes Agent sandbox.
  stop     Stop and terminate a Hermes Agent sandbox.
```

<Tip>
  macOS 用户如果碰到 `command not found` 报错，把下面两行加到 shell 配置里就好：

  ```bash theme={null}
  echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
  source ~/.zshrc
  ```
</Tip>

### 配置 API Key

把 API Key 设置成环境变量，后续命令就不用每次手动传了：

```bash theme={null}
export PPIO_API_KEY=sk_xxx
```

也可以每次执行命令时通过 `--api-key sk_xxx` 显式传入。

### 启动你的 Hermes Agent

输入下面这行命令：

```bash theme={null}
pphermes launch
```

等大约 60 秒，看到类似下面的输出就说明创建好了：

```text theme={null}
+------------------- PPHermes Sandbox Ready -------------------+
| Sandbox ID:         hermes-abc123-fb47b43e                   |
| State:              running                                  |
|                                                              |
| Hermes Web UI:      https://9119-xxx.sandbox.ppio.cn         |
| Web Terminal:       https://7681-xxx.sandbox.ppio.cn         |
| File Manager:       https://7682-xxx.sandbox.ppio.cn         |
| Services User:      admin                                    |
| Services Password:  <随机生成>                                |
+--------------------------------------------------------------+
```

其中几个关键信息：

* **Sandbox ID** — 沙箱的唯一编号，后续管理（查看状态、暂停、停止）时会用到
* **Hermes Web UI** — Hermes Agent 的交互界面，复制到浏览器打开就能用
* **Web Terminal** — 浏览器里的终端，可以直接进入沙箱执行命令、查看日志
* **File Manager** — 网页文件管理器，支持上传 / 下载 / 删除沙箱内的文件
* **Services User / Password** — Web Terminal 和 File Manager 的登录凭据（每次 launch 自动生成随机密码）

复制 `Hermes Web UI` 那一行的链接地址，粘贴到浏览器里打开，就能开始和你的 Hermes Agent 对话了。

<Note>
  PPHermes 启动后会自动配置好默认模型（PPIO 提供的 `minimax/minimax-m2.5-highspeed`），并预置 context compression、vision、web\_extract 等辅助 LLM 能力，开箱即用，无需任何额外设置。

  如需切换模型或自定义 provider，可在沙箱内通过 `hermes setup` 或编辑 `~/.hermes/config.yaml`，也可以用 `pphermes gateway config-import` 一键导入配置文件。
</Note>

### 自动省钱：on-demand 模式（按需运行）

不希望沙箱 7x24 在线烧钱？加上 `--type on-demand`，沙箱**空闲 10 分钟后自动暂停**，下次有飞书消息进来或 cron 任务即将触发时**自动恢复**：

```bash theme={null}
pphermes launch --type on-demand
```

也可以自定义空闲阈值（最少 60 秒）：

```bash theme={null}
# 30 分钟没活动才暂停
pphermes launch --type on-demand --idle-timeout 1800
```

<Note>
  自动暂停的判定综合了 Hermes 内部的 `state.db`（最后消息时间戳）、WAL 文件 mtime、`processes.json`（后台任务）和 `cron/jobs.json`（即将触发的定时任务），所以**长工具调用、运行中的后台进程、临近的 cron 都不会被误判为空闲**。沙箱被暂停后状态完整保留，自动恢复 \~1 秒。

  如果你的工作流里有超过 10 分钟的长工具调用（大模型训练、大型构建、大文件下载），把 `--idle-timeout` 调高到对应的预期值，或者直接用默认的 `always-on` 模式。
</Note>

### 暂停 vs 停止

用完之后建议**优先用 `pause`**，状态会被保留下来，且不产生费用：

```bash theme={null}
pphermes pause <Sandbox ID>
```

下次需要时秒级恢复：

```bash theme={null}
pphermes resume <Sandbox ID>
```

如果确认不再使用，再用 `stop` 彻底销毁（**不可逆**）：

```bash theme={null}
pphermes stop <Sandbox ID>
```

## 常用命令速查

| 命令                                 | 干什么用                                                                            | 怎么写                                                               |
| ---------------------------------- | ------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
| `pphermes launch`                  | 创建一个新的 Hermes Agent 沙箱                                                          | `pphermes launch`                                                 |
| `pphermes launch --type on-demand` | 创建按需沙箱（空闲自动暂停、消息自动恢复）                                                           | `pphermes launch --type on-demand --idle-timeout 600`             |
| `pphermes list`                    | 查看所有正在运行的沙箱                                                                     | `pphermes list`                                                   |
| `pphermes status`                  | 查看某个沙箱的运行状态和地址                                                                  | `pphermes status <sandbox-id>`                                    |
| `pphermes pause`                   | 暂停沙箱（保留状态、不计费）                                                                  | `pphermes pause <sandbox-id>`                                     |
| `pphermes resume`                  | 恢复已暂停的沙箱                                                                        | `pphermes resume <sandbox-id>`                                    |
| `pphermes stop`                    | 销毁沙箱（**不可逆**）                                                                   | `pphermes stop <sandbox-id>`                                      |
| `pphermes doctor`                  | 诊断 Hermes Gateway 健康状态                                                          | `pphermes doctor <sandbox-id>`                                    |
| `pphermes gateway update`          | 升级 Hermes Agent 并重启 Gateway                                                     | `pphermes gateway update <sandbox-id>`                            |
| `pphermes gateway restart`         | 重启 Gateway（不升级）                                                                 | `pphermes gateway restart <sandbox-id>`                           |
| `pphermes gateway config-export`   | 导出当前 Hermes 配置                                                                  | `pphermes gateway config-export <sandbox-id> -o config.yaml`      |
| `pphermes gateway config-import`   | 导入 Hermes 配置（默认重启 Gateway）                                                      | `pphermes gateway config-import <sandbox-id> config.yaml`         |
| `pphermes migrate`                 | 把 OpenClaw 状态迁移到 Hermes 沙箱（[详细说明](/sandbox/hermes-agent/migrate-from-openclaw)） | `pphermes migrate <sandbox-id> --from <openclaw-id>`              |
| `pphermes pair feishu`             | 把 Hermes Agent 接到飞书 / Lark                                                      | `pphermes pair feishu <sandbox-id> --app-id ... --app-secret ...` |

<Tip>
  所有命令都支持 `--json / -j`，方便脚本和 AI Agent 调用：

  ```bash theme={null}
  pphermes launch --json
  pphermes list -j
  ```

  如果网络比较慢，创建过程超时了，可以加大等待时间：

  ```bash theme={null}
  pphermes launch --timeout 300
  ```

  **升级 PPHermes** 到最新版本：重新跑一次安装脚本即可（pip 安装的话用 `pip install -U pphermes`）：

  ```bash theme={null}
  # macOS / Linux
  curl -fsSL https://pphermes.ppio.com/install.sh | bash
  # Windows PowerShell
  irm https://pphermes.ppio.com/install.ps1 | iex
  # 或 pip
  pip install -U pphermes
  ```
</Tip>

## 进阶：接入飞书 / Lark

PPHermes 内置 `pair feishu` 子命令，一行命令把 Hermes Agent 变成飞书机器人。

### WebSocket 长连接（推荐）

无需公网回调地址，Gateway 主动连接飞书服务端：

```bash theme={null}
pphermes pair feishu <sandbox-id> \
  --app-id cli_xxx \
  --app-secret secret_xxx \
  --mode websocket
```

### Webhook 回调

Gateway 在沙箱内启动 HTTP 服务（端口 8765）接收回调：

```bash theme={null}
pphermes pair feishu <sandbox-id> \
  --app-id cli_xxx \
  --app-secret secret_xxx \
  --mode webhook \
  --verification-token <TOKEN>
```

命令成功后会**直接输出回调地址**，长这样：

```text theme={null}
+------------------------- Feishu / Lark -------------------------+
| Feishu configured!                                              |
|                                                                 |
| Sandbox: <sandbox-id>                                           |
| Domain: feishu                                                  |
| Mode: webhook                                                   |
|                                                                 |
| Webhook URL (set in Feishu Open Platform):                      |
|   https://8765-<sandbox-id>.sandbox.ppio.cn/feishu/webhook      |
+-----------------------------------------------------------------+
```

把这一行 URL 复制粘贴到飞书开放平台 → 事件订阅 → 请求地址，保存即可。脚本调用时加 `--json` 可以直接拿到 `feishu_webhook_url` 字段：

```bash theme={null}
pphermes pair feishu <sandbox-id> \
  --app-id cli_xxx --app-secret secret_xxx \
  --mode webhook --verification-token <TOKEN> --json \
  | jq -r .feishu_webhook_url
```

<Warning>
  Webhook 模式不支持飞书的 **Encrypt Key**（Hermes Gateway 不解密加密 payload），飞书开放平台的 Encrypt Key 必须留空。
</Warning>

如果用的是 Lark（飞书海外版），把 `--domain feishu` 换成 `--domain lark` 即可。

## 进阶：用 AI Agent 直接管理沙箱

PPHermes 也提供了一份专为 AI Agent 设计的 Skill 文档（`https://pphermes.ppio.com/skill.md`），无需任何配置，在 Claude Code、Cursor、Windsurf 等 Agent 输入框直接用自然语言操作：

```text theme={null}
Read https://pphermes.ppio.com/skill.md and follow the onboarding instructions
```

Agent 会自动获取文档、安装 PPHermes CLI、配置 API Key 并启动沙箱。

也可以直接调用 REST API（基础地址 `https://pphermes.ppio.com/api`，交互式文档在 `/api/docs`），所有端点用 `Authorization: Bearer <PPIO_API_KEY>` 鉴权。

## 常见问题

遇到问题别着急，先对照下面的表格排查一下：

| 遇到什么问题                 | 为什么会这样                             | 怎么办                                                                 |
| ---------------------- | ---------------------------------- | ------------------------------------------------------------------- |
| 提示"不是内部或外部命令"          | 装 Python 时没勾选 `Add Python to PATH` | 卸载 Python 重新装一遍，**记得勾选底部的勾**                                        |
| 提示 `Permission Denied` | 权限不足                               | Windows：右键选择"以管理员身份运行"；macOS / Linux：命令前面加上 `sudo`                  |
| 提示 `MISSING_API_KEY`   | 没有设置 API Key                       | `export PPIO_API_KEY=sk_xxx`，或每次命令显式带上 `--api-key sk_xxx`           |
| 提示 `SANDBOX_TIMEOUT`   | 网络慢，60 秒内没创建完成                     | 加大超时：`pphermes launch --timeout 300`                                |
| 提示 `GATEWAY_TIMEOUT`   | Gateway 健康检查失败                     | 用 `pphermes doctor <sandbox-id>` 诊断，或 `pphermes gateway restart` 重启 |
| 飞书 Webhook 收不到消息       | 飞书开放平台填了 Encrypt Key               | 把 Encrypt Key 留空，仅保留 Verification Token                             |
| `stop` 误删了沙箱想恢复        | `stop` 不可逆                         | 重新 `pphermes launch` 创建新沙箱；下次记得用 `pause` 代替                         |