PPIO OpenClaw 集成指南 - 使用 PPClaw CLI 一键部署

首次使用且不熟悉命令行操作？推荐先阅读新手快速部署，包含从零开始的环境安装步骤。

通过 PPClaw 在 PPIO Agent Sandbox 上一键部署 OpenClaw 云端 AI 助手。

快速开始

1. 获取 PPIO API 密钥

2. 安装 PPClaw

请确保机器上已安装 Python >= 3.9 的稳定版本。

pip install ppclaw

验证安装：

ppclaw --version

若提示 command not found，需将 Python bin 目录加入 PATH：

echo 'export PATH="$HOME/Library/Python/3.9/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

3. 配置 API Key

支持以下方式（优先级从高到低）：

方式	示例	适用场景
命令行参数	`ppclaw launch --api-key sk_xxx`	临时使用
环境变量	`export PPIO_API_KEY=sk_xxx`	当前会话
配置文件	`~/.config/ppclaw/config.yaml`	长期使用

配置文件格式：

ppio:
  api_key: sk_your_api_key

4. 创建并使用沙箱

# 创建沙箱（约 50 秒）
ppclaw launch --api-key sk_your_api_key

创建成功后输出：

PPClaw Sandbox Ready

  Sandbox ID:         abc123def456-fb47b43e
  Keep Alive:         604800s

  Gateway WS:         wss://18789-xxx.sandbox.ppio.cn
  Gateway Token:      xYz1234abcd
  Web Terminal:       https://7681-xxx.sandbox.ppio.cn
  File Manager:       https://7682-xxx.sandbox.ppio.cn
  Services User:      admin
  Services Password:  <随机生成>

  ▶ Web UI: https://18789-xxx.sandbox.ppio.cn#token=xYz1234abcd

Web UI — Token 已自动附在链接中，浏览器打开即完成认证，无需手动输入
Web Terminal — 基于 ttyd 的浏览器终端（端口 7681），可直接在沙箱内执行命令
File Manager — 基于 gohttpserver 的网页文件管理器（端口 7682），支持上传 / 下载 / 删除文件
Services User / Password — Web Terminal 和 File Manager 使用 HTTP Basic Auth，每次 launch 自动生成随机密码

浏览器打开输出的 Web UI 链接即可使用。用完后停止沙箱：

ppclaw stop <SANDBOX_ID> --api-key sk_your_api_key

为旧沙箱添加 Web Terminal 和 File Manager

v1.3.0 之前创建的沙箱不包含 Web Terminal 和 File Manager 服务，ppclaw status 的输出中也不会显示对应地址。可通过以下命令一键补装：

ppclaw services setup <SANDBOX_ID> --api-key sk_your_api_key

该命令会：

自动下载并安装 ttyd 和 gohttpserver
生成登录凭据（HTTP Basic Auth）并启动服务
输出访问地址和凭据信息

若沙箱已完成过服务配置，命令会直接返回现有凭据，不会重复安装。

命令参考

launch

创建沙箱环境。

ppclaw launch [--api-key KEY] [--timeout 60]

参数	说明
`--api-key`	PPIO API Key
`--timeout`	创建超时时间，单位秒（默认 60）

Gateway Token 由系统自动生成，无需手动指定。仅 launch 命令会生成新的 Token，gateway restart 和 gateway update 不会重新生成。

list

列出所有沙箱。

ppclaw list [--api-key KEY] [--quiet/-q]

参数	说明
`--quiet` / `-q`	仅输出沙箱 ID，每行一个，方便脚本调用和管道操作

输出示例：

Sandbox ID:   abc123def456-fb47b43e
State:        running
CPU:          4
Memory (MB):  8192
Started At:   2026-02-28 11:38:46

精简模式（-q）输出：

abc123def456-fb47b43e
xyz789ghi012-a1b2c3d4

status

查看沙箱状态。

ppclaw status <SANDBOX_ID> [--api-key KEY]

stop

停止沙箱。

ppclaw stop <SANDBOX_ID> [--api-key KEY]

services setup

为沙箱安装并启动 Web Terminal（ttyd）和 File Manager（gohttpserver）。适用于 v1.3.0 之前创建的旧沙箱，新沙箱在 launch 时已自动配置。

ppclaw services setup <SANDBOX_ID> [--api-key KEY]

update

检查并升级到 PyPI 最新版本。

ppclaw update

支持 --json 模式输出升级结果。PPClaw 还会在每天首次启动时自动检查新版本（后台非阻塞），退出时提示更新。

JSON 输出

所有命令支持 --json 参数，适合脚本集成：

ppclaw --json launch --api-key sk_xxx

{
  "status": "ok",
  "sandbox_id": "abc123def456-fb47b43e",
  "webui": "https://18789-xxx.sandbox.ppio.cn#token=xYz1234",
  "gateway_ws": "wss://18789-xxx.sandbox.ppio.cn",
  "gateway_token": "xYz1234",
  "web_terminal": "https://7681-xxx.sandbox.ppio.cn",
  "file_manager": "https://7682-xxx.sandbox.ppio.cn",
  "services_user": "admin",
  "services_password": "<随机生成>"
}

模型配置

默认模型

沙箱预装以下模型（按量付费）：

模型 ID	名称	用途
`minimax/minimax-m2.5-highspeed`	Minimax M2.5 Highspeed	默认主模型

切换模型

支持切换至 PPIO 平台所有 LLM 模型。 操作步骤：

打开 Web UI → Settings → Config
切换到 Raw JSON 视图
修改以下两处配置：

第一步：注册模型 在 models.providers.ppio.models 数组中添加：

"models": [
  {
    "id": "model-id",
    "name": "display name",
    "reasoning": true,
    "input": ["text"],
    "contextWindow": 200000,
    "maxTokens": 8192
  }
]

第二步：设置主/备用模型 更新 agents.defaults.model：

"agents": {
  "defaults": {
    "model": {
      "primary": "ppio/model-id",
      "fallbacks": [
        "ppio/fallback-model-id"
      ]
    }
  }
}

点击 Update 保存

也支持第三方模型提供商，自带 LLM 只需支付沙箱运行时费用。

集成到服务

通过 HTTP API 将 OpenClaw 集成到你的应用服务中。

启用 HTTP API

在 Web UI 中打开 Settings → Config → Raw JSON，添加以下配置：

{
  "gateway": {
    "http": {
      "endpoints": {
        "chatCompletions": { "enabled": true },
        "responses": { "enabled": true }
      }
    }
  }
}

点击 Update 保存。

认证方式

使用 Gateway Token 进行 Bearer 认证：

Authorization: Bearer <GATEWAY_TOKEN>

Gateway Token 在 ppclaw launch 输出中获取。

API 端点

OpenAI Chat Completions API

兼容 OpenAI 格式，适合已有 OpenAI 集成的应用快速接入。端点：POST /v1/chat/completions

curl https://<SANDBOX_URL>/v1/chat/completions \
  -H "Authorization: Bearer <GATEWAY_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openclaw",
    "messages": [
      {"role": "user", "content": "你好"}
    ]
  }'

流式输出：

curl -N https://<SANDBOX_URL>/v1/chat/completions \
  -H "Authorization: Bearer <GATEWAY_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openclaw",
    "stream": true,
    "messages": [
      {"role": "user", "content": "你好"}
    ]
  }'

OpenResponses API

OpenClaw 原生 API，支持更多高级功能。端点：POST /v1/responses

curl https://<SANDBOX_URL>/v1/responses \
  -H "Authorization: Bearer <GATEWAY_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openclaw",
    "input": "你好"
  }'

流式输出：

curl -N https://<SANDBOX_URL>/v1/responses \
  -H "Authorization: Bearer <GATEWAY_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openclaw",
    "stream": true,
    "input": "你好"
  }'

指定 Agent

通过 model 字段指定目标 Agent：

{
  "model": "openclaw:agentId"
}

或使用请求头：

x-openclaw-agent-id: <agentId>

默认使用 main Agent。

会话管理

默认每次请求创建新会话。添加 user 字段可保持会话连续：

{
  "model": "openclaw",
  "user": "user-123",
  "input": "继续上次的话题"
}

MCP 协议支持

PPClaw 现已支持 Model Context Protocol (MCP)，AI 应用可通过标准协议直接管理沙箱。

端点地址：https://ppclaw.ppio.com/mcp（Streamable HTTP）
认证方式：Authorization: Bearer <PPIO_API_KEY>
10 个工具，覆盖完整沙箱生命周期：launch、stop、list_sandboxes、status、doctor、gateway_update、gateway_restart、services_setup、pair_list、pair_approve

在 Claude Code 中接入

claude mcp add --transport http ppclaw https://ppclaw.ppio.com/mcp \
  -H "Authorization: Bearer <YOUR_PPIO_API_KEY>"

在 Cursor / Windsurf 等客户端中配置

在支持 MCP 的 IDE 或 AI 客户端中，添加 MCP Server 配置：

配置项	值
Transport	HTTP (Streamable HTTP)
URL	`https://ppclaw.ppio.com/mcp`
Header	`Authorization: Bearer <YOUR_PPIO_API_KEY>`

配置完成后，在 Agent 输入框中直接用自然语言操作：

Launch a new OpenClaw sandbox and give me the Web UI URL

Skill.md — AI Agent 使用指南

PPClaw 提供 GET /skill.md 端点（https://ppclaw.ppio.com/skill.md），为 AI Agent 提供结构化的 PPClaw 使用文档，包含：

Onboarding 引导 — 从安装、获取 API Key 到启动第一个沙箱
CLI 命令参考 — 所有命令及 JSON 输出格式
REST API 参考 — 全部 14 个端点及其与 CLI 的对应关系
错误码一览 — 方便 Agent 自动诊断和恢复
Gotchas — 常见踩坑点（超时、不可逆操作、幂等性等）
常用 Recipes — 完整生命周期、网关修复等典型工作流

无需任何配置，在任意 AI Agent 输入框中输入：

Read https://ppclaw.ppio.com/skill.md and follow the onboarding instructions

Agent 会自动获取文档、安装 PPClaw CLI、配置 API Key 并启动沙箱。

常见问题

提示 "PPIO API key is required"

按照「配置 API Key」章节设置即可。

Gateway 启动超时

Gateway 首次启动需要 30-60 秒初始化。超时后可用 ppclaw status 检查状态，或重新创建。

实例保活时间

默认 7×24 小时。

产品简介

开始使用

入门教程

已接入工具

OpenClaw 部署与集成指南

快速开始

1. 获取 PPIO API 密钥

2. 安装 PPClaw

3. 配置 API Key

4. 创建并使用沙箱

为旧沙箱添加 Web Terminal 和 File Manager

命令参考

launch

list

status

stop

services setup

update

JSON 输出

模型配置

默认模型

切换模型

集成到服务

启用 HTTP API

认证方式

API 端点

OpenAI Chat Completions API

OpenResponses API

指定 Agent

会话管理

相关链接

MCP 协议支持

在 Claude Code 中接入

在 Cursor / Windsurf 等客户端中配置

Skill.md — AI Agent 使用指南

常见问题

产品简介

开始使用

入门教程

已接入工具

​快速开始

​1. 获取 PPIO API 密钥

​2. 安装 PPClaw

​3. 配置 API Key

​4. 创建并使用沙箱

​为旧沙箱添加 Web Terminal 和 File Manager

​命令参考

​launch

​list

​status

​stop

​services setup

​update

​JSON 输出

​模型配置

​默认模型

​切换模型

​集成到服务

​启用 HTTP API

​认证方式

​API 端点

​OpenAI Chat Completions API

​OpenResponses API

​指定 Agent

​会话管理

​相关链接

​MCP 协议支持

​在 Claude Code 中接入

​在 Cursor / Windsurf 等客户端中配置

​Skill.md — AI Agent 使用指南

​常见问题

快速开始

1. 获取 PPIO API 密钥

2. 安装 PPClaw

3. 配置 API Key

4. 创建并使用沙箱

为旧沙箱添加 Web Terminal 和 File Manager

命令参考

launch

list

status

stop

services setup

update

JSON 输出

模型配置

默认模型

切换模型

集成到服务

启用 HTTP API

认证方式

API 端点

OpenAI Chat Completions API

OpenResponses API

指定 Agent

会话管理

相关链接

MCP 协议支持

在 Claude Code 中接入

在 Cursor / Windsurf 等客户端中配置

Skill.md — AI Agent 使用指南

常见问题