跳转到主要内容

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.

本文档中的功能需要 PPClaw v1.8.0 及以上版本，请先升级 CLI：macOS / Linux：
curl -fsSL https://ppclaw.ppio.com/install.sh | bash
Windows (PowerShell)：
irm https://ppclaw.ppio.com/install.ps1 | iex
或通过 pipx：
pipx install ppclaw
还没部署过 OpenClaw？请先阅读新手快速部署完成首次安装和启动。

​
On-Demand 模式

On-Demand 是一种按需运行的沙箱模式——空闲时自动暂停以节省资源，有请求时自动恢复。适合低频使用的 AI 助手、Webhook 类 IM 集成和定时任务场景。

​
启动 On-Demand 沙箱

# 默认空闲超时 300 秒
ppclaw launch --api-key <你的 API Key> --type on-demand

# 自定义空闲超时（60–86400 秒）
ppclaw launch --api-key <你的 API Key> --type on-demand --idle-timeout 600
On-Demand 模式不支持 --mode node，两者不可组合使用。

​
手动暂停与恢复

# 暂停沙箱（暂停期间零计费）
ppclaw pause <sandbox_id>

# 恢复沙箱（约 1 秒恢复至暂停前状态）
ppclaw resume <sandbox_id>

​
运行时修改配置

沙箱创建后，仍可动态调整超时参数，变更即时生效： 
# 修改空闲超时（60–86400 秒）
ppclaw config set <sandbox_id> idle-timeout 600

# 修改沙箱生命周期超时（300–2592000 秒）
ppclaw config set <sandbox_id> timeout 3600

​
查看沙箱状态

# 查看沙箱状态（paused 状态下不会触发恢复）
ppclaw status <sandbox_id>

# 列表中显示 sandbox_type 和 state
ppclaw list --api-key <你的 API Key>
暂停状态下 status 命令仍返回完整的 URL 信息（从数据库读取，不连接沙箱），方便脚本保存地址。

​
工作原理

On-Demand 模式通过以下机制实现自动暂停与恢复：
  1. 空闲检测 — 沙箱内 agent 守护进程定期检查 OpenClaw 会话活跃状态，写入 /tmp/.ppclaw-status.json
  2. 自动暂停 — 服务端 idle monitor 读取 agent 状态，连续 2 次检测到空闲后自动暂停沙箱
  3. 自动恢复 — Webhook 请求或 Web UI 访问时，沙箱自动恢复
  4. Cron 预唤醒 — 调度器扫描已暂停沙箱的 cron 计划，在定时任务触发前约 120 秒自动恢复沙箱，确保 cron job 准时执行

​
飞书机器人集成

PPClaw 支持将 OpenClaw 实例连接到飞书机器人，实现在飞书中直接与 AI 助手对话。支持两种连接模式：Webhook（HTTP 推送） 和 Event（WebSocket 长连接）。

​
前置准备：创建飞书应用

  1. 打开飞书开放平台，登录后点击创建企业自建应用
  2. 在凭证与基础信息页面复制以下信息：
    • App ID（格式：cli_xxx）
    • App Secret
  3. 进入权限管理，点击批量导入，粘贴以下权限： 
{
  "scopes": {
    "tenant": [
      "im:message", "im:message:send_as_bot", "im:message:readonly",
      "im:message.p2p_msg:readonly", "im:message.group_at_msg:readonly",
      "im:resource", "im:chat.access_event.bot_p2p_chat:read",
      "im:chat.members:bot_access"
    ],
    "user": ["im:chat.access_event.bot_p2p_chat:read"]
  }
}
  1. 进入应用能力 > 机器人，开启机器人能力
  2. 创建版本并发布应用

​
模式一：Webhook 模式（推荐）

Webhook 模式通过 HTTP 推送接收飞书消息。On-Demand 沙箱推荐使用此模式——Webhook 请求会自动触发暂停沙箱恢复，不会丢失消息。 额外获取凭证：在飞书开放平台，进入开发配置 > 事件与回调 > 加密策略，复制：
  • Verification Token
  • Encrypt Key
ppclaw pair feishu <sandbox_id> \
  --app-id cli_xxx \
  --app-secret secret_xxx \
  --mode webhook \
  --verification-token tok_xxx \
  --encrypt-key key_xxx
在飞书开放平台事件订阅页面：
  1. 选择请求地址配置
  2. 填入 Webhook URL — 通过 ppclaw status 获取： 
    ppclaw status <sandbox_id> --json | jq -r '.feishu_webhook_url'
  3. 添加事件：im.message.receive_v1

​
Webhook 可选参数

参数默认值说明
--webhook-host0.0.0.0Webhook 服务器绑定地址
--webhook-port3000Webhook 监听端口
--webhook-path/feishu/eventsWebhook URL 路径

​
模式二：Event 模式

Event 模式通过飞书 WebSocket 长连接接收消息，无需公网 URL，配置最简单： 
ppclaw pair feishu <sandbox_id> \
  --app-id cli_xxx \
  --app-secret secret_xxx
配置完成后，在飞书开放平台事件订阅页面：
  1. 选择使用长连接接收事件
  2. 添加事件：im.message.receive_v1
保存前确保 gateway 已在运行（ppclaw status <sandbox_id>），否则飞书可能无法保存长连接配置。
Event 模式不建议用于 On-Demand 类型的沙箱。沙箱被自动暂停后，飞书的 WebSocket 长连接会断开，消息将丢失且无法触发自动恢复。如需使用 On-Demand 沙箱，请选择 Webhook 模式。

​
两种模式对比

Webhook 模式（推荐）Event 模式
连接方式HTTP 推送（入站）WebSocket 长连接（出站）
公网端口需要（默认 3000）不需要
配置复杂度中（额外需要 Token + Key）低（只需 App ID + Secret）
On-Demand 自动恢复支持（Webhook 触发自动恢复）不支持（长连接在暂停时断开）
推荐场景On-Demand 沙箱、生产 IM 集成Always-on 沙箱、开发调试

​
配对流程

飞书默认使用 pairing 策略：首次对话时机器人会回复一个配对码，需要在 CLI 中批准： 
# 查看待配对请求
ppclaw pair list <sandbox_id> feishu

# 批准配对
ppclaw pair approve <sandbox_id> feishu <CODE>
配对完成后即可在飞书中正常对话。

​
命令速查

命令说明
ppclaw launch --type on-demand启动 On-Demand 沙箱
ppclaw launch --idle-timeout <秒>指定空闲超时（仅 On-Demand）
ppclaw pause <id>暂停沙箱（零计费）
ppclaw resume <id>恢复暂停的沙箱
ppclaw config set <id> idle-timeout <秒>修改空闲超时
ppclaw config set <id> timeout <秒>修改生命周期超时
ppclaw pair feishu <id> --app-id ... --app-secret ...配对飞书（Event 模式）
ppclaw pair feishu <id> --mode webhook ...配对飞书（Webhook 模式）
ppclaw pair list <id> feishu查看待配对请求
ppclaw pair approve <id> feishu <CODE>批准配对