本文作者：阿里云无影技术专家 吴晓
一、OpenClaw 主要解决什么问题？
OpenClaw 是一个 开源自托管 的 AI 助手体系，核心目标可以概括为四点（也是它与「又一个 Chat 客户端」的本质区别）：
- 多平台统一接入 将 WhatsApp、Telegram、Discord、Slack、iMessage、WebChat 等不同聊天渠道，接到 同一套 AI 能力 上，避免为每个渠道重复写对接逻辑。
- 消息与会话的统一抽象 各渠道消息被归一成 平台无关 的格式，再交给配置好的 Agent 处理；Agent 只关心「消息内容 + 会话」，不关心消息来自哪个 App。
- 自托管与数据可控 设计上强调 自己部署、自己运行，数据和流量留在企业可控环境，而非依赖封闭 SaaS。
- 可配置的智能体与会话 通过 Binding 等规则，把「哪个渠道、哪个会话」路由到「哪个 Agent、哪个 Session」，支持 多 Agent、多会话编排。
理解了这四点，再看「为什么要在云沙箱里跑 OpenClaw」：企业要的往往不是多装一个二进制，而是 可审计的执行环境 + 可复现的网关与配置 + 与现有 IM / 业务系统的安全对接。
二、为什么用云沙箱跑 OpenClaw？
在本地或一台固定 ECS 上直接跑 OpenClaw 当然可行，但引入 AgentBay 云沙箱 后，典型收益包括：
维度 |
说明 |
安全可控 |
计算与文件系统在隔离沙箱内执行，网关与敏感配置可通过策略与网络边界管理；适合对「AI 能访问什么、跑在哪里」有合规要求的团队。 |
弹性自适应 |
按会话创建 / 销毁 / 休眠（如 Cookbook 提供的休眠与恢复能力）使用资源，避免长期占满固定机器；峰值可扩展、闲时可降本。 |
运维一致 |
镜像内已集成 OpenClaw 运行环境，与 AgentBay SDK、沙箱持久化、外链能力同一套 API 模型，减少「每台机器装一遍」的漂移。 |
一句话：OpenClaw 负责「智能体与渠道」的产品语义，AgentBay 负责「算力与环境」的工程语义；Cookbook 则是把两者粘成可演示、可二次开发的最小完整产品。
三、AgentBay OpenClaw Cookbook
针对 OpenClaw 这类「自托管 AI 助手 + 云沙箱桌面」的落地场景，AgentBay 开源 SDK 在 wuying-agentbay-sdk 仓库中提供了 Cookbook 最佳实践，帮助企业 快速实现「云养龙虾」：在隔离沙箱里拉起 OpenClaw、打通 HTTPS/WSS 外链、沙箱内数据与目录的持久化与 IM 侧一键配置等，而不必从零拼装会话生命周期、网关代理与接入层。当前参考实现以 Python FastAPI + React 呈现，可克隆、可改写。
Cookbook 路径：cookbook/openclaw/python（`main` 分支）。它是 SDK 之上的官方示例与集成范式，而非另一套独立产品：业务侧始终通过 AgentBay SDK（创建会话、get_link、持久化目录挂载与同步等）与平台交互；Cookbook 将对话代理、IM 页、钉钉/飞书配置流程等诉求沉淀为可运行的代码与页面。
与沙箱能力的关系：下文 第四部分「能力地图」 中的能力——钉钉/飞书一键配置、Gateway 与 WSS、/chat 自建聊天页与流式体验、沙箱持久化、会话休眠/恢复等——均依赖 AgentBay 沙箱与 SDK（隔离桌面/会话生命周期、外网端口与 get_link、云端持久化卷与目录同步策略等）。SDK 提供统一 API；沙箱提供运行与网络边界；Cookbook 展示如何组合为 可交付的企业侧 OpenClaw 场景。
更详细的 API 表、端口与白名单说明（如 Pro/Ultra 默认 30100–30199）见 Cookbook 内 README.md。
四、能力地图：从「能连上」到「能定制、能持久、能流式」
1. 钉钉 / 飞书机器人一键配置
业界较早的探索中，有无影 AgentBay 的客户在基于 OpenClaw 沙箱的一键配置 IM 机器人场景里，采用了 自研浏览器插件 + 后台服务 的架构：插件与页面交互、再与后台通信，由后台驱动完成开放平台内的登录、建应用与凭证获取。该路径可行，但企业侧需要 单独维护插件的分发、更新与多端兼容，并与自有后台长期耦合。
在 AgentBay 上，同一类「沙箱里跑浏览器、自动完成钉钉/飞书开放平台流程」的需求，可以直接依托 AgentBay SDK 提供的自动化能力实现：Playwright 与 Page Use Agent（及 Browser Use Agent 等编排能力） 在隔离沙箱内的浏览器中完成扫码登录、创建应用、拉取 Client ID / Secret 并写回 OpenClaw 配置——无需自建浏览器插件，自动化逻辑与会话、桌面同属一套 SDK 与沙箱边界，运维与安全面更收敛。这是 AgentBay SDK + 云沙箱 相较「插件 + 外部后台」集成方式的典型优势。
演示视频：https://cloud.video.taobao.com/vod/oZ90NuAo2NPJDSGupLgGsahEmMqegl9YJdftsjnsno0.mp4
会话创建成功后，本 Cookbook 管理页提供「一键配置钉钉机器人」「一键配置飞书机器人」：左侧为会话与一键入口，右侧为沙箱内桌面与浏览器实况，在沙箱内完成 扫码登录 → 创建应用 → 提取凭证 → 回填 OpenClaw 配置，降低手工复制凭证的出错率。后端对钉钉提供了多种自动化实现入口（含 Playwright 等），飞书侧亦有对应流程与状态查询 API（详见 README 中的 API 表）。
2. Gateway 外网暴露：get_link（HTTPS / WSS）与接入层建议
沙箱内的 OpenClaw Gateway 需要被外部访问时，AgentBay SDK 通过 get_link 等能力，将网关对应端口映射到 公网可达的地址：既可暴露 HTTPS（例如访问 Control UI、静态页面），也可暴露 WSS（与 Gateway 的 长连接、对话与订阅）。也就是说，HTTPS 与 WSS 两条协议都由平台侧提供「沙箱内 Gateway → 公网」的链路能力，供集成方在服务端使用。
企业集成时的安全建议：接入 AgentBay SDK 时，宜自建一层接入层（应用网关、反向代理或专用转发服务），由该层在受控环境内调用 SDK 拿到 get_link 返回的地址，再代理 HTTPS / WSS 的转发与鉴权；尽量避免将沙箱映射得到的 公网 URL 直接暴露给终端浏览器或外部业务系统（例如不要把原始外链当作前端配置下发）。接入层可统一做认证、限流、审计与域名证书，安全边界最清晰。
本 Cookbook 中的 同源 WebSocket 代理即是接入层的一种参考实现：不替代 get_link，浏览器只连接本服务的固定路径，由服务端使用 get_link 得到的 WSS 与 Gateway 建链并完成 OpenClaw 协议 v3 握手（如 connect.challenge → 带 auth.token 的 connect），再 双向透传：
- 终端连接：
ws(s)://本服务/api/sessions/{sessionId}/openclaw-wss（与业务站点同域） - 数据路径：终端 → 企业接入层（本示例为 FastAPI） →
get_link公网 WSS → 沙箱内 Gateway
3. 企业自建聊天页与流式体验
任意持有合法 sessionId 的 Web / 客户端，都可连接上述代理路径，自行实现 UI（消息列表、Markdown、流式增量、打字机效果等）。本仓库的 /chat?sessionId= 页面是 IM 风格参考实现：深色主题、气泡、自动滚底、流式光标与打字机展示等，解析 chat.delta / chat.done 等事件即可对齐官方 Control UI 的体验方向。
下图为本 Cookbook 内置独立对话页示例：顶部展示返回与 已连接 状态，对话区为用户气泡与助手
（OC）回复，底部为输入框与「新会话 / 发送」操作，便于企业对照实现自有聊天页与流式体验。
4. 沙箱内数据持久化与 openclaw.json
沙箱内可挂载目录、并与云端持久化存储同步，是 AgentBay 沙箱的核心竞争力之一：区别于仅提供「算力 / 机器按时长计费」的 资源型云产品（会话结束即环境归零），AgentBay 把 用户数据与运行环境解耦——桌面与会话可销毁、回收，但 工作目录与配置可长期保留、跨会话复用，更适合 OpenClaw 这类需要「养环境、养数据」的场景，形成差异化优势。
AgentBay 沙箱支持将指定目录与 云端持久化存储绑定：创建会话时按 用户名 分配独立命名空间（如 openclaw-{用户名}），把 /home/wuying/.openclaw 挂载进沙箱，并采用 ARCHIVE 压缩同步 等策略，使 OpenClaw 配置、openclaw.json、Skills、插件与工作区数据在 会话销毁后仍可拉回。README 中亦说明了销毁会话时如何 等待持久化上传完成、必要时如何 显式触发目录与云端的双向同步，避免「新会话读不到旧数据」。
5. 会话生命周期与成本
AgentBay 在 SDK 中提供 完整的沙箱生命周期管理：创建、查询、销毁，以及 休眠、唤醒（恢复） 等能力，使企业可按业务节奏 灵活启停环境，在「暂时不用但需保留会话句柄」等场景下 压低资源占用与成本，需要时再一键拉回运行态。本 Cookbook 将休眠 / 恢复等能力暴露为管理页操作，便于演示与二次集成。
外部 HTTPS 与 WSS 能力仍受套餐与端口策略约束，具体以官方文档或支持渠道为准。
持久化与生命周期协同：上述能力可 组合使用——企业可通过 休眠、销毁 等手段及时释放或压缩在线资源，控制成本；同时依托 沙箱目录与云端持久化，在环境暂停或会话结束后 仍保留 OpenClaw 数据与配置。用户再次 新建会话或唤醒 沙箱时，可 接续既有环境与数据，减少重复配置与冷启动摩擦。二者配合，有助于在 降低企业使用成本 的同时 提升用户体验。
五、架构一瞥（逻辑链路）
六、如何上手与延伸阅读
- 准备 AgentBay API Key 与（按需）百炼 / DashScope 等模型 Key。
- Clone 或进入 cookbook/openclaw/python 目录，安装依赖并执行
python main.py，默认 **http://localhost:8080\**。 - 阅读 README.md：快速开始、项目结构、WSS 专章、沙箱持久化与目录挂载、常见问题（保活、同步、自定义镜像等）。
- 二次开发时：后端重点在
session_manager.py、app.py；前端参考OpenClawChatPage.tsx与OpenClawChatPanel.tsx。
七、结语
OpenClaw 解决的是 「多渠道、多会话、自托管智能体」 的产品层问题；AgentBay 解决的是 「隔离执行、外链、持久化、弹性」 的基础设施问题。本 Cookbook 将二者串成一条可运行、可扩展的演示链路：钉钉/飞书一键接入、WSS 代理定制聊天页、沙箱持久化养住你的「数字龙虾」。若你正在评估企业内落地 OpenClaw，不妨从这套沙箱方案开始，把安全边界与集成路径一次摸透。
参考与代码位置（GitHub 已发布）：
