> ## 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.

# OpenClaw 部署与集成指南

> 本文档详细介绍如何在派欧云(PPIO) Agent沙箱环境中使用 PPClaw CLI 工具。提供从安装、配置到一键部署OpenClaw的完整教程，助您快速构建稳定安全的AI应用。

export const SetupApiKeyGuide = () => {
  if (typeof document === "undefined") {
    return null;
  } else {
    return <>
                如果您之前没有 PPIO 账号，请先 <Link href="https://ppio.com/user/register" target="_blank">注册 PPIO 平台账号</Link>，详情请参考 <Link href="/support/quickstart">新手指引</Link>。注册完成后，通过 <Link href="https://ppio.com/settings/key-management" target="_blank">PPIO API 密钥管理</Link> 页面，您可以创建 API 密钥并保存好用于后续步骤。
            </>;
  }
};

<Tip>
  首次使用且不熟悉命令行操作？推荐先阅读[新手快速部署](/sandbox/openclaw-quickstart)，包含从零开始的环境安装步骤。
</Tip>

通过 PPClaw 在 PPIO Agent Sandbox 上一键部署 [OpenClaw](https://github.com/nicepkg/openclaw) 云端 AI 助手。

## 快速开始

### 1. 获取 PPIO API 密钥

<SetupApiKeyGuide />

### 2. 安装 PPClaw

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

```bash theme={null}
pip install ppclaw
```

验证安装：

```bash theme={null}
ppclaw --version
```

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

  ```bash theme={null}
  echo 'export PATH="$HOME/Library/Python/3.9/bin:$PATH"' >> ~/.zshrc
  source ~/.zshrc
  ```
</Tip>

### 3. 配置 API Key

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

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

配置文件格式：

```yaml theme={null}
ppio:
  api_key: sk_your_api_key
```

### 4. 创建并使用沙箱

```bash theme={null}
# 创建沙箱（约 50 秒）
ppclaw launch --api-key sk_your_api_key
```

创建成功后输出：

```text theme={null}
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](https://github.com/tsl0922/ttyd) 的浏览器终端（端口 7681），可直接在沙箱内执行命令
* **File Manager** — 基于 [gohttpserver](https://github.com/codeskyblue/gohttpserver) 的网页文件管理器（端口 7682），支持上传 / 下载 / 删除文件
* **Services User / Password** — Web Terminal 和 File Manager 使用 HTTP Basic Auth，每次 launch 自动生成随机密码

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

```bash theme={null}
ppclaw stop <SANDBOX_ID> --api-key sk_your_api_key
```

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

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

```bash theme={null}
ppclaw services setup <SANDBOX_ID> --api-key sk_your_api_key
```

该命令会：

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

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

## 命令参考

### launch

创建沙箱环境。

```bash theme={null}
ppclaw launch [--api-key KEY] [--timeout 60]
```

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

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

### list

列出所有沙箱。

```bash theme={null}
ppclaw list [--api-key KEY] [--quiet/-q]
```

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

输出示例：

```text theme={null}
Sandbox ID:   abc123def456-fb47b43e
State:        running
CPU:          4
Memory (MB):  8192
Started At:   2026-02-28 11:38:46
```

精简模式（`-q`）输出：

```text theme={null}
abc123def456-fb47b43e
xyz789ghi012-a1b2c3d4
```

### status

查看沙箱状态。

```bash theme={null}
ppclaw status <SANDBOX_ID> [--api-key KEY]
```

### stop

停止沙箱。

```bash theme={null}
ppclaw stop <SANDBOX_ID> [--api-key KEY]
```

### services setup

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

```bash theme={null}
ppclaw services setup <SANDBOX_ID> [--api-key KEY]
```

### update

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

```bash theme={null}
ppclaw update
```

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

### JSON 输出

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

```bash theme={null}
ppclaw --json launch --api-key sk_xxx
```

```json theme={null}
{
  "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 模型](/model/llm)。

**操作步骤：**

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

**第一步：注册模型**

在 `models.providers.ppio.models` 数组中添加：

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

**第二步：设置主/备用模型**

更新 `agents.defaults.model`：

```json theme={null}
"agents": {
  "defaults": {
    "model": {
      "primary": "ppio/model-id",
      "fallbacks": [
        "ppio/fallback-model-id"
      ]
    }
  }
}
```

4. 点击 **Update** 保存

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

## 集成到服务

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

### 启用 HTTP API

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

```json theme={null}
{
  "gateway": {
    "http": {
      "endpoints": {
        "chatCompletions": { "enabled": true },
        "responses": { "enabled": true }
      }
    }
  }
}
```

点击 **Update** 保存。

### 认证方式

使用 Gateway Token 进行 Bearer 认证：

```bash theme={null}
Authorization: Bearer <GATEWAY_TOKEN>
```

Gateway Token 在 `ppclaw launch` 输出中获取。

### API 端点

#### OpenAI Chat Completions API

兼容 OpenAI 格式，适合已有 OpenAI 集成的应用快速接入。

**端点**：`POST /v1/chat/completions`

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

**流式输出**：

```bash theme={null}
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`

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

**流式输出**：

```bash theme={null}
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：

```json theme={null}
{
  "model": "openclaw:agentId"
}
```

或使用请求头：

```bash theme={null}
x-openclaw-agent-id: <agentId>
```

默认使用 `main` Agent。

### 会话管理

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

```json theme={null}
{
  "model": "openclaw",
  "user": "user-123",
  "input": "继续上次的话题"
}
```

### 相关链接

* [OpenAI Chat Completions API 文档](https://docs.openclaw.ai/gateway/openai-http-api)
* [OpenResponses API 文档](https://docs.openclaw.ai/gateway/openresponses-http-api)

## MCP 协议支持

PPClaw 现已支持 [Model Context Protocol (MCP)](https://modelcontextprotocol.io/)，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 中接入

```bash theme={null}
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 输入框中直接用自然语言操作：

```text theme={null}
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 输入框中输入：

```text theme={null}
Read https://ppclaw.ppio.com/skill.md and follow the onboarding instructions
```

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

## 常见问题

<AccordionGroup>
  <Accordion title="提示 &#x22;PPIO API key is required&#x22;">
    按照「配置 API Key」章节设置即可。
  </Accordion>

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

  <Accordion title="实例保活时间">
    默认 7×24 小时。
  </Accordion>
</AccordionGroup>