跳转到主要内容
已有 Python 开发经验？可以直接看 PPHermes 命令参考，里面有完整的 CLI、REST API 和飞书集成说明。
这篇教程带你从零开始，一步步在云端部署属于你自己的 Hermes Agent（由 Nous Research 开发的自进化 AI Agent）。不需要任何编程基础，跟着做就行。

​
第一步：给电脑装上 Python

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

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

  1. 点击这里下载 Python 安装包
  2. 双击打开安装包
务必勾选底部的 Add Python to PATH。这是新手最容易漏掉的地方，不勾选的话后面所有命令都会报错。
  1. 点击 Install Now，等到看到 Setup was successful 就可以关掉了

​
macOS 用户

  1. 按 Command + 空格，搜索”终端”（Terminal）并打开
  2. 输入下面这行命令，按回车：
python3 --version
  • 如果显示 Python 3.9 或更高版本，说明已经装好了，直接跳到下一步
  • 如果版本太低或没装，使用 Homebrew 安装：brew install python

​
Linux（Ubuntu）用户

打开终端，输入： 
sudo apt update && sudo apt install python3 python3-venv python3-pip -y

​
第二步：获取你的 API Key

你需要一个 PPIO API Key（可以理解为”通行密钥”）来连接 PPIO 的云端 Agent 沙箱。
  1. 打开 PPIO 控制台 并注册登录
  2. 进入 API Key 管理页面
  3. 点击**「创建 API Key」**
  4. 你会看到一串以 sk_ 开头的字符串，复制下来找个地方存好
API Key 只在创建时显示一次，关掉页面就看不到了，记得及时复制保存。

​
第三步：安装并启动

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

​
安装 PPHermes

macOS / Linux 用户输入： 
curl -fsSL https://pphermes.ppio.com/install.sh | bash
Windows 用户在 PowerShell 中输入： 
irm https://pphermes.ppio.com/install.ps1 | iex
也可以通过 pip 安装： 
pip install pphermes
安装完成后，输入下面的命令验证一下： 
pphermes --help
如果看到类似下面这样的输出，就表示安装成功了： 
Usage: pphermes [OPTIONS] COMMAND [ARGS]...

  PPHermes - One-click launch of Hermes Agent on PPIO Agent Sandbox.

Options:
  --version       Show the version and exit.
  --json / -j     Output as JSON (for programmatic use).
  --help          Show this message and exit.

Commands:
  launch    Create and start a new Hermes sandbox
  list      List all running Hermes sandboxes
  status    Show sandbox status
  pause     Pause a sandbox (preserves state, no charges)
  resume    Resume a paused sandbox
  stop      Stop and destroy a sandbox
  doctor    Diagnose gateway health
  gateway   Manage Hermes gateway (update / restart / config)
  pair      Pair external channels (Feishu / Lark)
  update    Check for updates and upgrade to the latest version
macOS 用户如果碰到 command not found 报错，把下面两行加到 shell 配置里就好：
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

​
配置 API Key

把 API Key 设置成环境变量，后续命令就不用每次手动传了： 
export PPIO_API_KEY=sk_xxx
也可以每次执行命令时通过 --api-key sk_xxx 显式传入。

​
启动你的 Hermes Agent

输入下面这行命令： 
pphermes launch
等大约 60 秒，看到类似下面的输出就说明创建好了： 
+------------------- 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 对话了。
PPHermes 启动后会自动配置好默认模型（PPIO 提供的 minimax/minimax-m2.5-highspeed），并预置 context compression、vision、web_extract 等辅助 LLM 能力，开箱即用，无需任何额外设置。如需切换模型或自定义 provider，可在沙箱内通过 hermes setup 或编辑 ~/.hermes/config.yaml，也可以用 pphermes gateway config-import 一键导入配置文件。

​
暂停 vs 停止

用完之后建议优先用 pause，状态会被保留下来，且不产生费用： 
pphermes pause <Sandbox ID>
下次需要时秒级恢复： 
pphermes resume <Sandbox ID>
如果确认不再使用，再用 stop 彻底销毁（不可逆）： 
pphermes stop <Sandbox ID>

​
常用命令速查

命令干什么用怎么写
pphermes launch创建一个新的 Hermes Agent 沙箱pphermes launch
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 并重启 Gatewaypphermes 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 update检查并升级 PPHermes 到最新版本pphermes update
所有命令都支持 --json / -j，方便脚本和 AI Agent 调用：
pphermes launch --json
pphermes list -j
如果网络比较慢，创建过程超时了，可以加大等待时间：
pphermes launch --timeout 300

​
进阶：接入飞书 / Lark

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

​
WebSocket 长连接（推荐）

无需公网回调地址，Gateway 主动连接飞书服务端： 
pphermes pair feishu <sandbox-id> \
  --app-id cli_xxx \
  --app-secret secret_xxx \
  --mode websocket

​
Webhook 回调

Gateway 在沙箱内启动 HTTP 服务（端口 8765）接收回调： 
pphermes pair feishu <sandbox-id> \
  --app-id cli_xxx \
  --app-secret secret_xxx \
  --mode webhook \
  --verification-token <TOKEN>
配置完成后，到飞书开放平台把回调地址设置为： 
https://8765-<sandbox-id>.sandbox.ppio.cn/feishu/webhook
Webhook 模式不支持飞书的 Encrypt Key（Hermes Gateway 不解密加密 payload），飞书开放平台的 Encrypt Key 必须留空。
如果用的是 Lark（飞书海外版），把 --domain feishu 换成 --domain lark 即可。

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

PPHermes 也提供了一份专为 AI Agent 设计的 Skill 文档（https://pphermes.ppio.com/skill.md），无需任何配置，在 Claude Code、Cursor、Windsurf 等 Agent 输入框直接用自然语言操作： 
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 Keyexport PPIO_API_KEY=sk_xxx，或每次命令显式带上 --api-key sk_xxx
提示 SANDBOX_TIMEOUT网络慢，60 秒内没创建完成加大超时：pphermes launch --timeout 300
提示 GATEWAY_TIMEOUTGateway 健康检查失败用 pphermes doctor <sandbox-id> 诊断，或 pphermes gateway restart 重启
飞书 Webhook 收不到消息飞书开放平台填了 Encrypt Key把 Encrypt Key 留空，仅保留 Verification Token
stop 误删了沙箱想恢复stop 不可逆重新 pphermes launch 创建新沙箱；下次记得用 pause 代替