Skip to main content
已有 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. 输入下面这行命令，按回车：
  • 如果显示 Python 3.9 或更高版本，说明已经装好了，直接跳到下一步
  • 如果版本太低或没装，使用 Homebrew 安装：brew install python

​
Linux（Ubuntu）用户

打开终端，输入：

​
第二步：获取你的 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 用户输入：
Windows 用户在 PowerShell 中输入：
也可以通过 pip 安装：
安装完成后，输入下面的命令验证一下：
如果看到类似下面这样的输出，就表示安装成功了：
macOS 用户如果碰到 command not found 报错，把下面两行加到 shell 配置里就好：

​
配置 API Key

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

​
启动你的 Hermes Agent

输入下面这行命令：
等大约 60 秒，看到类似下面的输出就说明创建好了：
其中几个关键信息：
  • 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 一键导入配置文件。

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

不希望沙箱 7x24 在线烧钱？加上 --type on-demand，沙箱空闲 10 分钟后自动暂停，下次有飞书消息进来或 cron 任务即将触发时自动恢复：
也可以自定义空闲阈值（最少 60 秒）：
自动暂停的判定综合了 Hermes 内部的 state.db（最后消息时间戳）、WAL 文件 mtime、processes.json（后台任务）和 cron/jobs.json（即将触发的定时任务），所以长工具调用、运行中的后台进程、临近的 cron 都不会被误判为空闲。沙箱被暂停后状态完整保留，自动恢复 ~1 秒。如果你的工作流里有超过 10 分钟的长工具调用（大模型训练、大型构建、大文件下载），把 --idle-timeout 调高到对应的预期值，或者直接用默认的 always-on 模式。

​
暂停 vs 停止

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

​
常用命令速查

所有命令都支持 --json / -j，方便脚本和 AI Agent 调用：
如果网络比较慢，创建过程超时了，可以加大等待时间：
升级 PPHermes 到最新版本：重新跑一次安装脚本即可（pip 安装的话用 pip install -U pphermes）：

​
进阶：接入飞书 / Lark

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

​
WebSocket 长连接（推荐）

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

​
Webhook 回调

Gateway 在沙箱内启动 HTTP 服务（端口 8765）接收回调：
命令成功后会直接输出回调地址，长这样：
把这一行 URL 复制粘贴到飞书开放平台 → 事件订阅 → 请求地址，保存即可。脚本调用时加 --json 可以直接拿到 feishu_webhook_url 字段：
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 输入框直接用自然语言操作：
Agent 会自动获取文档、安装 PPHermes CLI、配置 API Key 并启动沙箱。 也可以直接调用 REST API（基础地址 https://pphermes.ppio.com/api，交互式文档在 /api/docs），所有端点用 Authorization: Bearer <PPIO_API_KEY> 鉴权。

​
常见问题

遇到问题别着急，先对照下面的表格排查一下：
最后修改于 2026年4月29日