跳转到主要内容
已有 Python 开发经验？可以直接看部署与集成指南，有更完整的命令参考和 API 集成说明。
这篇教程带你从零开始，一步步在云端部署属于你自己的 OpenClaw AI 助手。不需要任何编程基础，跟着做就行。

​
第一步：给电脑装上 Python

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

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

  1. 点击这里下载 Python 安装包
  2. 双击打开安装包
务必勾选底部的 Add Python to PATH。这是新手最容易漏掉的地方，不勾选的话后面所有命令都会报错。
  1. 点击 Install Now，等到看到 Setup was successful 就可以关掉了

​
macOS 用户

  1. 按 Command + 空格，搜索”终端”（Terminal）并打开
  2. 输入下面这行命令，按回车：
python3 --version
  • 如果显示 Python 3.x.x，说明已经装好了，直接跳到下一步
  • 如果弹出下面这样的提示，点安装，等几分钟就好
macOS 命令行开发者工具安装提示

​
Linux（Ubuntu）用户

打开终端，输入： 
sudo apt update && sudo apt install python3 python3-pip -y

​
第二步：获取你的 API Key

你需要一个 API Key（可以理解为”通行密钥”）来连接 PPIO 的云端 AI 环境。
  1. 打开 PPIO Key Management 页面并注册登录
  2. 点击**「创建 API Key」**
  3. 你会看到一串以 sk_ 开头的字符串，复制下来找个地方存好
API Key 只在创建时显示一次，关掉页面就看不到了，记得及时复制保存。

​
第三步：安装并启动

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

​
安装 PPClaw

Windows 用户输入： 
pip install ppclaw
macOS / Linux 用户输入： 
sudo pip3 install ppclaw
sudo 会要求你输入开机密码。输密码的时候屏幕上不会显示任何字符，这是正常的，输完直接按回车就行。
安装完成后，输入下面的命令验证一下： 
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>
它会自动完成以下操作：
  1. 下载并安装 ttyd 和 gohttpserver
  2. 生成登录凭据并启动服务
  3. 输出访问地址和凭据信息
如果沙箱已经配置过这两个服务，命令会直接显示现有的凭据信息，不会重复安装。
用完之后记得停掉沙箱，释放资源： 
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 Managerppclaw 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 提示 InvalidKey 可能复制不完整，或者前后多了空格回到控制台重新复制一遍，注意 sk_ 前后不要有多余空格
macOS 上 pip install 提示命令找不到macOS 为了区分版本，把安装工具叫做 pip3把命令里的 pip 换成 pip3 就行
停止沙箱没有反应停止会清空沙箱里所有内容，需要你手动再确认一次在终端里输入 y 然后按回车