10 分钟部署你的 AI 助手

已有 Python 开发经验？可以直接看部署与集成指南，有更完整的命令参考和 API 集成说明。

这篇教程带你从零开始，一步步在云端部署属于你自己的 OpenClaw AI 助手。不需要任何编程基础，跟着做就行。

第一步：给电脑装上 Python

PPClaw 是一个基于 Python 的小工具，所以需要先在电脑上装好 Python。

Windows 用户（最关键的一步）

点击这里下载 Python 安装包
双击打开安装包

务必勾选底部的 Add Python to PATH。这是新手最容易漏掉的地方，不勾选的话后面所有命令都会报错。

点击 Install Now，等到看到 Setup was successful 就可以关掉了

macOS 用户

按 Command + 空格，搜索”终端”（Terminal）并打开
输入下面这行命令，按回车：

python3 --version

如果显示 Python 3.x.x，说明已经装好了，直接跳到下一步
如果弹出下面这样的提示，点安装，等几分钟就好

Linux（Ubuntu）用户

打开终端，输入：

sudo apt update && sudo apt install python3 python3-pip -y

第二步：获取你的 API Key

你需要一个 API Key（可以理解为”通行密钥”）来连接 PPIO 的云端 AI 环境。

打开 PPIO Key Management 页面并注册登录
点击**「创建 API Key」**
你会看到一串以 sk_ 开头的字符串，复制下来找个地方存好

API Key 只在创建时显示一次，关掉页面就看不到了，记得及时复制保存。

第三步：安装并启动

打开你的终端窗口（Windows 叫 PowerShell，macOS 叫终端）。

安装 PPClaw

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

安装完成后，输入下面的命令验证一下：

ppclaw --help

如果看到类似下面这样的输出，就表示安装成功了：

Usage: ppclaw [OPTIONS] COMMAND [ARGS]...

  PPClaw - One-click launch of OpenClaw on PPIO Agent Sandbox.

Options:
  --version       Show the version and exit.
  --json / -j     Output as JSON (for programmatic use).
  --help          Show this message and exit.

Commands:
  doctor   Diagnose and fix sandbox issues
  launch   Create and start a new sandbox
  list     List all running sandboxes
  status   Show sandbox status
  stop     Stop and remove a sandbox
  update   Check for updates and upgrade to the latest version

看到 Commands 下面列出了 launch、list 这些命令，说明一切就绪。

macOS 用户如果碰到 command not found 报错，说明需要配置一下环境变量。按顺序运行下面两行命令：

echo 'export PATH="'$(python3 -m site --user-base)'/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

运行完再试一次 ppclaw --help 就好了。

启动你的 AI 助手

输入下面这行命令，把 <你的 API Key> 替换成你刚才保存的那串密钥：

ppclaw launch --api-key <你的 API Key>

等大约 50 秒，看到类似下面的输出就说明创建好了：

+-------------------- 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

其中几个关键信息：

Sandbox ID — 沙箱的唯一编号，后续管理（查看状态、停止）时会用到
Web UI — 这就是你的 AI 助手地址，复制到浏览器打开就能用。Token 已自动附在链接里，打开即完成认证
Web Terminal — 浏览器里的终端，可以直接在沙箱内执行命令
File Manager — 网页文件管理器，支持上传 / 下载 / 删除沙箱内的文件
Services User / Password — Web Terminal 和 File Manager 的登录凭据（每次 launch 自动生成随机密码）

复制 Web UI 那一行后面的链接地址，粘贴到浏览器里打开，就能开始和你的 AI 助手对话了。

为旧沙箱添加 Web Terminal 和 File Manager

如果你的沙箱是在 v1.3.0 之前创建的，运行 ppclaw status 时不会看到 Web Terminal 和 File Manager 的地址——这是因为旧版模板没有预装这两个服务。只需一行命令即可补装：

ppclaw services setup <Sandbox ID> --api-key <你的 API Key>

它会自动完成以下操作：

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

如果沙箱已经配置过这两个服务，命令会直接显示现有的凭据信息，不会重复安装。

用完之后记得停掉沙箱，释放资源：

ppclaw stop --api-key <你的 API Key> <Sandbox ID>

常用命令速查

命令	干什么用	怎么写
`ppclaw launch`	创建一个新的 AI 助手	`ppclaw launch --api-key sk_xxx`
`ppclaw list`	看看你有哪些正在运行的助手	`ppclaw list --api-key sk_xxx`
`ppclaw list -q`	只输出沙箱 ID（方便脚本使用）	`ppclaw list --api-key sk_xxx -q`
`ppclaw status`	查看某个助手的运行状态	`ppclaw status --api-key sk_xxx <sandbox-id>`
`ppclaw stop`	停掉并删除某个助手	`ppclaw stop --api-key sk_xxx <sandbox-id>`
`ppclaw doctor`	助手出问题了，用它来诊断修复	`ppclaw doctor --api-key sk_xxx <sandbox-id>`
`ppclaw services setup`	为旧沙箱补装 Web Terminal 和 File Manager	`ppclaw services setup --api-key sk_xxx <sandbox-id>`
`ppclaw update`	检查并升级到最新版本	`ppclaw update`

如果网络比较慢，创建过程超时了，可以加大等待时间试试：

ppclaw launch --api-key sk_xxx --timeout 120

进阶：用 AI Agent 直接管理沙箱

除了在终端手动输入命令，PPClaw 还支持两种方式让 AI Agent 替你操作沙箱。

方式一：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 的客户端中配置使用。配置完成后，在 Agent 输入框中直接用自然语言操作：

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

方式二：让 AI 读取 Skill.md 自动操作

PPClaw 提供了一个专为 AI Agent 设计的使用指南：https://ppclaw.ppio.com/skill.md，包含完整的安装、配置和操作说明。无需任何配置，在任意 AI Agent 输入框中输入：

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

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

常见问题

遇到问题别着急，先对照下面的表格排查一下：

遇到什么问题	为什么会这样	怎么办
提示”不是内部或外部命令”	装 Python 时没勾选 `Add Python to PATH`	卸载 Python 重新装一遍，记得勾选底部的勾
提示 `Permission Denied`	权限不足	Windows：右键选择”以管理员身份运行”；macOS / Linux：命令前面加上 `sudo`
API Key 提示 Invalid	Key 可能复制不完整，或者前后多了空格	回到控制台重新复制一遍，注意 `sk_` 前后不要有多余空格
macOS 上 `pip install` 提示命令找不到	macOS 为了区分版本，把安装工具叫做 `pip3`	把命令里的 `pip` 换成 `pip3` 就行
停止沙箱没有反应	停止会清空沙箱里所有内容，需要你手动再确认一次	在终端里输入 `y` 然后按回车

产品简介

开始使用

入门教程

已接入工具

常见问题

第一步：给电脑装上 Python

Windows 用户（最关键的一步）

macOS 用户

Linux（Ubuntu）用户

第二步：获取你的 API Key

第三步：安装并启动

安装 PPClaw

启动你的 AI 助手

为旧沙箱添加 Web Terminal 和 File Manager

常用命令速查

进阶：用 AI Agent 直接管理沙箱

方式一：MCP 协议接入

方式二：让 AI 读取 Skill.md 自动操作

常见问题

​第一步：给电脑装上 Python

​Windows 用户（最关键的一步）

​macOS 用户

​Linux（Ubuntu）用户

​第二步：获取你的 API Key

​第三步：安装并启动

​安装 PPClaw

​启动你的 AI 助手

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

​常用命令速查

​进阶：用 AI Agent 直接管理沙箱

​方式一：MCP 协议接入

​方式二：让 AI 读取 Skill.md 自动操作

​常见问题

第一步：给电脑装上 Python

Windows 用户（最关键的一步）

macOS 用户

Linux（Ubuntu）用户

第二步：获取你的 API Key

第三步：安装并启动

安装 PPClaw

启动你的 AI 助手

为旧沙箱添加 Web Terminal 和 File Manager

常用命令速查

进阶：用 AI Agent 直接管理沙箱

方式一：MCP 协议接入

方式二：让 AI 读取 Skill.md 自动操作

常见问题