ppclaw-cli 0.5.1

One-click launch of OpenClaw sandbox environment powered by PPIO Agent Sandbox

PPClaw

一键启动安装有 OpenClaw 的云端沙箱环境，基于 PPIO Agent Sandbox。

安装

pip install ppclaw-cli

配置

1. 获取 PPIO API Key

前往 PPIO Key Management 获取你的 API Key。该 Key 同时用于：

• 创建和管理 PPIO 沙箱实例
• 作为 PPClaw 的 LLM 推理 API Key

2. 配置 API Key

可以通过以下任一方式配置：

# 方式一：直接传参
ppclaw-cli launch --api-key sk_your_api_key

# 方式二：设置当前命令的环境变量
PPIO_API_KEY=sk_your_api_key ppclaw-cli launch

# 方式三：导出到当前终端会话
export PPIO_API_KEY=sk_your_api_key

# 方式四：写入 shell 配置文件（永久生效）
echo 'export PPIO_API_KEY=sk_your_api_key' >> ~/.zshrc

使用

所有命令支持 --json / -j 全局选项，输出结构化 JSON（适合 AI Agent 或脚本调用）。如果你是 AI Agent，请始终使用 --json 参数 以获得稳定的机器可解析输出：

ppclaw-cli --json launch    # {"status":"ok","sandbox_id":"...","webui":"...","gateway_ws":"...","gateway_token":"..."}
ppclaw-cli --json list      # {"status":"ok","sandboxes":[...]}
ppclaw-cli --json status <id>  # {"status":"ok","sandbox_id":"...","state":"...","webui":"...","gateway_ws":"...","gateway_token":"..."}
ppclaw-cli --json stop <id>    # {"status":"ok","sandbox_id":"...","message":"..."}
ppclaw-cli --json doctor <id>  # {"status":"ok","sandbox_id":"...","output":"..."}

启动沙箱

ppclaw-cli launch

建议通过 --gateway-token 指定一个安全的自定义 Token，用于 OpenClaw 访问鉴权。如果不设置，会自动生成一个随机 Token：

ppclaw-cli launch --gateway-token <your-token>

启动成功后会输出：

• Sandbox ID — 用于后续管理
• Web UI 地址 — 在浏览器中打开即可使用 PPClaw（Token 已附在 URL 中，自动认证）
• Gateway WebSocket 地址 — 用于 TUI 或 API 连接
• Gateway Token — 连接时需要的认证令牌

完整参数：

参数	说明	默认值
--api-key	PPIO API Key	读取 PPIO_API_KEY 环境变量
--gateway-token	Gateway 认证令牌（建议设置安全的自定义 Token）	自动生成随机 Token
--timeout	沙箱创建超时（秒）	60

查看沙箱列表

ppclaw-cli list

查看沙箱状态

ppclaw-cli status <sandbox-id>

通过 TUI 连接

ppclaw-cli tui <sandbox-id> --token <gateway-token>

需要本地安装 OpenClaw CLI：npm install -g openclaw

首次连接时会触发 Device Pairing，沙箱内的自动审批服务会在约 3 秒内完成配对，请稍等片刻。

诊断与修复

在沙箱内运行 OpenClaw doctor，检查配置完整性、权限、Gateway 健康状态、插件/技能状态等：

ppclaw-cli doctor <sandbox-id>

自动修复发现的问题：

ppclaw-cli doctor <sandbox-id> --fix           # 应用推荐修复
ppclaw-cli doctor <sandbox-id> --fix --force   # 包含激进修复（会覆盖自定义配置）
ppclaw-cli doctor <sandbox-id> --deep          # 深度扫描系统服务

停止沙箱

ppclaw-cli stop <sandbox-id>

安全说明

Gateway Token 用于保护你的 PPClaw 实例不被未授权访问。当沙箱绑定到公网地址时：

• 妥善保管 Token — 可通过 ppclaw-cli status <id> 随时查看
• 及时停止不用的沙箱 — 避免不必要的资源消耗和安全风险

相关文档

• OpenClaw 安装使用文档
• PPIO Agent Sandbox 文档
• PPIO API Key 获取