On-Demand 模式

本文档中的功能需要 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 是一种按需运行的沙箱模式——空闲时自动暂停以节省资源，有请求时自动恢复。适合低频使用的 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 模式通过以下机制实现自动暂停与恢复：

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

飞书机器人集成

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

前置准备：创建飞书应用

打开飞书开放平台，登录后点击创建企业自建应用
在凭证与基础信息页面复制以下信息：
- App ID（格式：cli_xxx）
- App Secret
进入权限管理，点击批量导入，粘贴以下权限：

{
  "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"]
  }
}

进入应用能力 > 机器人，开启机器人能力
创建版本并发布应用

模式一：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

在飞书开放平台事件订阅页面：

选择请求地址配置

填入 Webhook URL — 通过 ppclaw status 获取：

ppclaw status <sandbox_id> --json | jq -r '.feishu_webhook_url'

添加事件：im.message.receive_v1

Webhook 可选参数

参数	默认值	说明
`--webhook-host`	`0.0.0.0`	Webhook 服务器绑定地址
`--webhook-port`	`3000`	Webhook 监听端口
`--webhook-path`	`/feishu/events`	Webhook URL 路径

模式二：Event 模式

Event 模式通过飞书 WebSocket 长连接接收消息，无需公网 URL，配置最简单：

ppclaw pair feishu <sandbox_id> \
  --app-id cli_xxx \
  --app-secret secret_xxx

配置完成后，在飞书开放平台事件订阅页面：

选择使用长连接接收事件
添加事件：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>`	批准配对

产品简介

开始使用

入门教程

已接入工具

常见问题

On-Demand 模式

On-Demand 模式

启动 On-Demand 沙箱

手动暂停与恢复

运行时修改配置

查看沙箱状态

工作原理

飞书机器人集成

前置准备：创建飞书应用

模式一：Webhook 模式（推荐）

Webhook 可选参数

模式二：Event 模式

两种模式对比

配对流程

命令速查

​On-Demand 模式

​启动 On-Demand 沙箱

​手动暂停与恢复

​运行时修改配置

​查看沙箱状态

​工作原理

​飞书机器人集成

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

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

​Webhook 可选参数

​模式二：Event 模式

​两种模式对比

​配对流程

​命令速查

On-Demand 模式

启动 On-Demand 沙箱

手动暂停与恢复

运行时修改配置

查看沙箱状态

工作原理

飞书机器人集成

前置准备：创建飞书应用

模式一：Webhook 模式（推荐）

Webhook 可选参数

模式二：Event 模式

两种模式对比

配对流程

命令速查