OpenClaw（大龙虾）技术学习分享

本文对开源个人 AI 助手 OpenClaw（社区俗称「大龙虾」）做技术拆解与学习汇总，涵盖背景与定位、架构总览、核心技术点、源码解读、场景推荐、迁移建议、相关技术/项目对比、安全与权限、局限与延伸，并附完整参考文献，便于读者按引用核实与延伸阅读。全文以官方文档与仓库为准，社区说法均标明来源。

章	内容
[1. 背景与定位](#章内容 1. 背景与定位项目由来、命名、目标用户、与只说不做机器人的差异 2. 架构总览 Gateway 控制面、客户端与节点、数据流与协议 3. 核心技术点多通道、工具与执行、会话与工作区、记忆与压缩 4. 源码解读仓库结构、Gateway、Agent 循环、工具与沙箱 5. 场景推荐适合与不适合的场景、能力边界 6. 迁移与落地建议从零接入、从现有 Agent 迁移 7. 相关技术与项目对比与其它 Agent/助手的对比 8. 安全与权限威胁模型、加固建议、审计 9. 局限与延伸不足、延伸阅读参考文献按引用顺序的完整来源列表)	项目由来、命名、目标用户、与只说不做机器人的差异
[2. 架构总览](#章内容 1. 背景与定位项目由来、命名、目标用户、与只说不做机器人的差异 2. 架构总览 Gateway 控制面、客户端与节点、数据流与协议 3. 核心技术点多通道、工具与执行、会话与工作区、记忆与压缩 4. 源码解读仓库结构、Gateway、Agent 循环、工具与沙箱 5. 场景推荐适合与不适合的场景、能力边界 6. 迁移与落地建议从零接入、从现有 Agent 迁移 7. 相关技术与项目对比与其它 Agent/助手的对比 8. 安全与权限威胁模型、加固建议、审计 9. 局限与延伸不足、延伸阅读参考文献按引用顺序的完整来源列表)	Gateway 控制面、客户端与节点、数据流与协议
[3. 核心技术点](#章内容 1. 背景与定位项目由来、命名、目标用户、与只说不做机器人的差异 2. 架构总览 Gateway 控制面、客户端与节点、数据流与协议 3. 核心技术点多通道、工具与执行、会话与工作区、记忆与压缩 4. 源码解读仓库结构、Gateway、Agent 循环、工具与沙箱 5. 场景推荐适合与不适合的场景、能力边界 6. 迁移与落地建议从零接入、从现有 Agent 迁移 7. 相关技术与项目对比与其它 Agent/助手的对比 8. 安全与权限威胁模型、加固建议、审计 9. 局限与延伸不足、延伸阅读参考文献按引用顺序的完整来源列表)	多通道、工具与执行、会话与工作区、记忆与压缩
[4. 源码解读](#章内容 1. 背景与定位项目由来、命名、目标用户、与只说不做机器人的差异 2. 架构总览 Gateway 控制面、客户端与节点、数据流与协议 3. 核心技术点多通道、工具与执行、会话与工作区、记忆与压缩 4. 源码解读仓库结构、Gateway、Agent 循环、工具与沙箱 5. 场景推荐适合与不适合的场景、能力边界 6. 迁移与落地建议从零接入、从现有 Agent 迁移 7. 相关技术与项目对比与其它 Agent/助手的对比 8. 安全与权限威胁模型、加固建议、审计 9. 局限与延伸不足、延伸阅读参考文献按引用顺序的完整来源列表)	仓库结构、Gateway、Agent 循环、工具与沙箱
[5. 场景推荐](#章内容 1. 背景与定位项目由来、命名、目标用户、与只说不做机器人的差异 2. 架构总览 Gateway 控制面、客户端与节点、数据流与协议 3. 核心技术点多通道、工具与执行、会话与工作区、记忆与压缩 4. 源码解读仓库结构、Gateway、Agent 循环、工具与沙箱 5. 场景推荐适合与不适合的场景、能力边界 6. 迁移与落地建议从零接入、从现有 Agent 迁移 7. 相关技术与项目对比与其它 Agent/助手的对比 8. 安全与权限威胁模型、加固建议、审计 9. 局限与延伸不足、延伸阅读参考文献按引用顺序的完整来源列表)	适合与不适合的场景、能力边界
[6. 迁移与落地建议](#章内容 1. 背景与定位项目由来、命名、目标用户、与只说不做机器人的差异 2. 架构总览 Gateway 控制面、客户端与节点、数据流与协议 3. 核心技术点多通道、工具与执行、会话与工作区、记忆与压缩 4. 源码解读仓库结构、Gateway、Agent 循环、工具与沙箱 5. 场景推荐适合与不适合的场景、能力边界 6. 迁移与落地建议从零接入、从现有 Agent 迁移 7. 相关技术与项目对比与其它 Agent/助手的对比 8. 安全与权限威胁模型、加固建议、审计 9. 局限与延伸不足、延伸阅读参考文献按引用顺序的完整来源列表)	从零接入、从现有 Agent 迁移
[7. 相关技术与项目对比](#章内容 1. 背景与定位项目由来、命名、目标用户、与只说不做机器人的差异 2. 架构总览 Gateway 控制面、客户端与节点、数据流与协议 3. 核心技术点多通道、工具与执行、会话与工作区、记忆与压缩 4. 源码解读仓库结构、Gateway、Agent 循环、工具与沙箱 5. 场景推荐适合与不适合的场景、能力边界 6. 迁移与落地建议从零接入、从现有 Agent 迁移 7. 相关技术与项目对比与其它 Agent/助手的对比 8. 安全与权限威胁模型、加固建议、审计 9. 局限与延伸不足、延伸阅读参考文献按引用顺序的完整来源列表)	与其它 Agent/助手的对比
[8. 安全与权限](#章内容 1. 背景与定位项目由来、命名、目标用户、与只说不做机器人的差异 2. 架构总览 Gateway 控制面、客户端与节点、数据流与协议 3. 核心技术点多通道、工具与执行、会话与工作区、记忆与压缩 4. 源码解读仓库结构、Gateway、Agent 循环、工具与沙箱 5. 场景推荐适合与不适合的场景、能力边界 6. 迁移与落地建议从零接入、从现有 Agent 迁移 7. 相关技术与项目对比与其它 Agent/助手的对比 8. 安全与权限威胁模型、加固建议、审计 9. 局限与延伸不足、延伸阅读参考文献按引用顺序的完整来源列表)	威胁模型、加固建议、审计
[9. 局限与延伸](#章内容 1. 背景与定位项目由来、命名、目标用户、与只说不做机器人的差异 2. 架构总览 Gateway 控制面、客户端与节点、数据流与协议 3. 核心技术点多通道、工具与执行、会话与工作区、记忆与压缩 4. 源码解读仓库结构、Gateway、Agent 循环、工具与沙箱 5. 场景推荐适合与不适合的场景、能力边界 6. 迁移与落地建议从零接入、从现有 Agent 迁移 7. 相关技术与项目对比与其它 Agent/助手的对比 8. 安全与权限威胁模型、加固建议、审计 9. 局限与延伸不足、延伸阅读参考文献按引用顺序的完整来源列表)	不足、延伸阅读
[参考文献](#章内容 1. 背景与定位项目由来、命名、目标用户、与只说不做机器人的差异 2. 架构总览 Gateway 控制面、客户端与节点、数据流与协议 3. 核心技术点多通道、工具与执行、会话与工作区、记忆与压缩 4. 源码解读仓库结构、Gateway、Agent 循环、工具与沙箱 5. 场景推荐适合与不适合的场景、能力边界 6. 迁移与落地建议从零接入、从现有 Agent 迁移 7. 相关技术与项目对比与其它 Agent/助手的对比 8. 安全与权限威胁模型、加固建议、审计 9. 局限与延伸不足、延伸阅读参考文献按引用顺序的完整来源列表)	按引用顺序的完整来源列表

1. 背景与定位

1.1 项目是什么

OpenClaw 是一款自托管的个人 AI 助手 ，即本地安装 ：运行在你自己的机器或自控服务器上，数据与执行均在己控环境（工作区、会话转录、凭证均在 ~/.openclaw 等本地路径）[1][3]。它与「云端 Agent」（推理/执行在厂商或自建云）、「纯端侧 Agent」（推理与执行均在手机/设备本地）并列为三种常见部署形态；跨形态的对比与迁移借鉴见本文第 6、7 节。

通过你已在使用的渠道（WhatsApp、Telegram、Slack、Discord、Google Chat、Signal、iMessage、BlueBubbles、Microsoft Teams、WebChat 等）与你对话，并能执行文件、终端、浏览器、消息发送等操作 [1]。官方标语为 "Your own personal AI assistant. Any OS. Any Platform. The lobster way. 🦞" [1]。

与「只回答问题、不执行动作」的聊天机器人不同，OpenClaw 的定位是可执行任务的助手 ：在用户授权下整理邮件、管理日程、通过消息应用接收指令、填表、处理文件、执行代码、串联工作流等 [2]。社区中常将其类比为「有手的 Claude」------即具备与 Claude 相近的对话与推理能力，同时具备真实执行能力（文件、终端、浏览器、多通道消息）[2]。

1.2 命名与由来

据社区与第三方报道，该项目曾以 Clawdbot 名称发布，后因商标等原因更名为 Moltbot ，再确定为 OpenClaw ；据 [10] 等社区文章，项目曾在一周内三次更名（Clawdbot → Moltbot → OpenClaw），引发大量讨论。当前仓库与文档均以 OpenClaw 为准，采用 MIT 许可证，保持本地优先与开源 [2][8]。本文统一使用 OpenClaw，在涉及历史或社区习惯时保留「大龙虾」「Moltbot」等称呼并注明来源。

1.3 目标用户与典型用法

目标用户是希望拥有个人化、单用户、本地优先、常驻助手的用户 [1]。典型用法包括：

在已有即时通讯渠道（如 WhatsApp、Telegram）中与助手对话并下发任务；
通过 CLI（openclaw agent --message "..."）或 Control UI（Web 控制台）与助手交互；
在 macOS/iOS/Android 上使用配套应用（菜单栏、Voice Wake、Talk Mode、Canvas 等）[1]。

官方推荐运行 Node ≥22，通过 openclaw onboard --install-daemon 完成向导配置并安装 Gateway 守护进程，使助手常驻运行 [1][5]。本地优先在架构上的体现是：推理可走你配置的 API，但会话状态、工作区文件、工具执行（文件、终端、浏览器等）都发生在你控制的主机或沙箱内，不依赖厂商云端存储或执行 [1][3]。

1.4 为什么叫「有手的 Claude」

「有手的 Claude」是社区对 OpenClaw 的通俗概括 [2]：Claude 以长上下文与强推理见长，但传统上仅限对话与 API 调用；OpenClaw 在保留类似对话与推理体验的同时，为助手接上了真实执行层------文件系统读写、Shell 命令、浏览器自动化、多通道消息发送、定时任务与 Webhook 等 [1][6][7]。因此「手」指的是这些可执行工具；数据与推理可在本地或你指定的 API 上完成，执行也在你控制的设备上，形成「能想又能做」的个人助手 [1][2]。

1.5 与「只说不做」聊天机器人的差异

维度	只说不做（纯聊天/问答）	OpenClaw（可执行助手）
输出	文本/卡片/建议	文本 + 真实动作（改文件、发消息、跑命令、开浏览器）
数据与执行位置	多为云端 API	本地/自托管，工作区与执行均在己控环境 [1][3]
多通道	多为单应用或 Web	同一助手接入 WhatsApp/Telegram/Slack/... 等多通道收件箱 [1]
工具与权限	无或仅只读	文件、终端、浏览器、Nodes、cron 等，需授权与沙箱策略 [3][6]

因此若你需要的不仅是「问一句答一句」，而是「让它帮我执行一整套任务」，OpenClaw 的定位更接近后者 [1][2]。

2. 架构总览

2.1 总体模型：单 Gateway 控制面

OpenClaw 采用单主机单 Gateway 的架构：一台主机上只运行一个 Gateway 进程，由它统一持有所有消息通道连接（如 WhatsApp、Telegram、Slack、Discord 等）并对外提供 WebSocket 控制面 [1][2]。Gateway 默认监听 127.0.0.1:18789（仅本机），HTTP 同端口上还提供 Control UI、Canvas 等 [2]。

为什么是单 Gateway？ [2]

好处：集中鉴权、单点审计、简化多通道状态同步。
代价：单点故障与横向扩展需多实例（每台主机一个 Gateway）。
相似技术点：其它 Agent 或消息编排系统里常见的「单控制面 / central broker / orchestrator」思路与之类似（如部分 ChatOps 框架、Bot 网关）。
平替方案：若需要更高可用或多租户隔离，可考虑多 Gateway 多实例（每实例独立配置）、网关前置负载均衡、或按通道拆成独立进程；多实例适合多租户或高可用，单实例适合个人/单用户。

WhatsApp / Telegram / Slack / Discord / ... / WebChat
│
▼
┌─────────────────────────────────────┐
│ Gateway │
│ (control plane) │
│ ws://127.0.0.1:18789 │
└──────────────────┬──────────────────┘
│
├─ Pi agent (RPC)
├─ CLI (openclaw ...)
├─ WebChat UI
├─ macOS app
└─ iOS / Android nodes

（图来源：根据 [1] README 中 "How it works (short)" 整理。）

架构数据流可概括为以下 Mermaid 图（基于 [2] 文档整理）：
Agent Layer
Control Clients
CLI
macOS App
Control UI
Gateway
WebSocket API
Events
Channel Handlers
Channels
WhatsApp
Telegram
Slack
WebChat
Pi Agent
Tools

对算法/模型工程师：整条链路的 token 流向为「通道消息 + 系统提示 + bootstrap + 会话历史 → 模型推理 → 工具调用结果回填 → 再推理」，单轮闭环便于做上下文预算与压缩策略设计 [4]。

对算法/架构师 ：OpenClaw 的架构对设计「多入口、可执行」的 Agent 平台有多处可借鉴。(1) 单控制面取舍 ：单 Gateway 集中鉴权与审计、简化多通道状态同步，代价是单点与横向扩展需多实例；若你做多租户或高可用，可参考平替方案（多实例、负载均衡、按通道拆进程）[2]。(2) 协议与分层 ：通道 → Gateway（WebSocket 类型化 API）→ 控制面客户端 / Pi Agent → 工具，控制面与执行面 清晰分离；协议由 TypeBox/schema 驱动，便于多端生成与校验 [2]。(3) 扩展点 ：多通道通过「通道适配器 + 统一入站」接入、Nodes 以 role: node 声明能力、Skills 与插件可扩展能力，架构师可关注「哪里可插接、哪里需保持单点」[1][2]。

2.2 组件与角色

Gateway（守护进程） ：校验入站帧（JSON Schema）、暴露类型化 WebSocket API（请求/响应/服务端推送）、维护与各通道的连接、发布 agent、chat、presence、health、heartbeat、cron 等事件 [2]。
控制面客户端 （macOS 应用、CLI、Web 管理端）：通过 WebSocket 连接 Gateway，订阅事件（如 tick、agent、presence、shutdown），发送请求（如 health、status、send、agent、system-presence）；每个客户端一个 WS 连接 [2]。
Nodes （macOS/iOS/Android/无头节点）：以 role: node 连接同一 WebSocket 服务，声明能力与命令（如 canvas.*、camera.*、screen.record、location.get），提供设备身份；配对与授权存储在设备配对库中 [2]。
WebChat：静态前端，通过 Gateway 的 WebSocket API 获取历史并发送消息；在远程部署时通过 SSH 隧道或 Tailscale 与其它客户端共用同一入口 [2]。

2.3 连接与认证

据 [2]：

首帧必须是 connect；之后为 JSON 文本帧的请求/响应与事件。
若配置了 OPENCLAW_GATEWAY_TOKEN 或 --token，则 connect.params.auth.token 必须匹配，否则连接关闭。
本地连接（loopback 或本机 tailnet 地址）可被自动批准；非本地连接需对 connect.challenge 签名并经过显式批准，新设备 ID 需配对批准后由 Gateway 颁发设备 token。详见 [2] Architecture 中的 Pairing 与 [3] Security。

2.4 远程访问

默认仅绑定本机；远程访问推荐 Tailscale 或 SSH 隧道 [2]。例如：ssh -N -L 18789:127.0.0.1:18789 user@host [2]。远程环境下可启用 TLS 与可选 pinning，握手与 auth token 规则不变 [2]。

实战：用 CLI 验证 Gateway 与远程访问

安装并执行 openclaw onboard --install-daemon 后，执行 openclaw gateway status 检查服务；若正常，会看到 Gateway 运行状态（具体输出依版本而定，通常包含端口与健康信息）[5]。再执行 openclaw dashboard 或在浏览器打开 http://127.0.0.1:18789/，应看到 Control UI 登录/控制界面 [5]。
若 Gateway 跑在远程主机上，在本地执行端口转发后即可在本地浏览器访问远程 Gateway：
bash 复制代码
```
ssh -N -L 18789:127.0.0.1:18789 user@远程主机
```
保持该终端不关闭，在本地浏览器访问 http://127.0.0.1:18789 即访问远程 Gateway 的 Control UI；需确保远程已配置 token 或密码且你在本地使用相同凭证 [2]。

实战：最小协议示例（用于脚本/调试）

据 [2] Gateway architecture，连接后首帧必须为 connect，之后可发请求。以下为概念性 JSON 示例（具体 schema 以 Gateway protocol 为准）：

首帧 connect（若配置了 token，需在 params.auth.token 中带上）：

json 复制代码

{"type":"req","id":"1","method":"connect","params":{"auth":{"token":"YOUR_TOKEN"},"device":{}}}

收到成功响应后，可发 health 请求：
json 复制代码
```
{"type":"req","id":"2","method":"health","params":{}}
```
响应形如 {"type":"res","id":"2","ok":true,"payload":{...}}。实际字段与枚举以官方 TypeBox/JSON Schema 生成文档为准 [2]。

2.5 协议与事件类型摘要

据 [2] Gateway architecture：

典型请求 ：health、status、send、agent、agent.wait、system-presence 等。
响应格式 ：{ type: "response", id, ok, payload|error }。
服务端推送事件 ：agent（Agent 运行与流式输出）、chat（消息与历史）、presence、health、heartbeat、cron、tick、shutdown 等；控制面客户端通过订阅这些事件保持与 Gateway 状态同步。

具体 schema 与字段以官方 Gateway protocol 文档为准。

3. 核心技术点

3.1 多通道收件箱

OpenClaw 支持在同一 Gateway 下接入多种消息渠道 [1]：

类型	示例
即时通讯	WhatsApp（Baileys）、Telegram（grammY）、Slack（Bolt）、Discord（discord.js）、Google Chat、Signal（signal-cli）、Microsoft Teams
苹果生态	BlueBubbles（iMessage，推荐）、iMessage（legacy imsg）
扩展/其他	Matrix、Zalo、Zalo Personal、WebChat

以下为加固基线 的简化示例（格式为 JSON5/JSON，实际键以 [3] Security 为准），放在 ~/.openclaw/openclaw.json（或 OPENCLAW_CONFIG_PATH 指向的文件）中：

json5 复制代码

{
  "gateway": {
    "bind": "loopback",
    "auth": { "mode": "token", "token": "替换为长随机 token" },
  },
  "session": { "dmScope": "per-channel-peer" },
  "agents": {
    "defaults": {
      "workspace": "~/.openclaw/workspace",
      "sandbox": { "mode": "non-main" }
    }
  },
  "tools": {
    "profile": "messaging",
    "deny": ["group:automation", "group:runtime", "group:fs", "sessions_spawn", "sessions_send", "gateway", "cron"],
    "exec": { "security": "deny", "ask": "always" },
  },
  "channels": {
    "whatsapp": { "dmPolicy": "pairing", "groups": { "*": { "requireMention": true } } },
  },
}

配置项说明 [3]：

gateway.bind: "loopback"：仅本机可连；gateway.auth：必须 token 或 password，避免未认证暴露。
agents.defaults.sandbox.mode: "non-main"：非主会话（如群组）在沙箱中执行，减少影响范围。
tools.deny：对不可信代理拒绝 gateway、cron、sessions_spawn、sessions_send 等控制面/运行时工具；tools.profile: "messaging" 可进一步收紧默认工具集。生效范围为全局，主会话若需更多工具可在 agent 级覆盖（谨慎）。

4. 源码解读

4.1 仓库结构（基于 [1]）

OpenClaw 仓库 [1] 主要目录与文件包括：

路径	说明
`apps/`	应用层
`packages/`	核心包
`src/`	源码入口与共享逻辑
`docs/`	文档
`skills/`	技能定义
`extensions/`	扩展/插件
`AGENTS.md`	Agent 相关说明
`README.md`	项目说明与快速开始
`SECURITY.md`	安全说明
`VISION.md`	愿景与方向
`openclaw.mjs`	入口脚本
`docker-compose.yml`、`Dockerfile*`	容器化与沙箱相关

Gateway、Pi agent、CLI、各通道适配器及工具实现分布在 packages/ 与 src/ 下；具体模块边界与调用关系以仓库当前分支为准，阅读时建议从 openclaw.mjs 与 package.json 的 scripts 入手，再进入 packages/ 中 gateway、agent、tools 相关子包 [1]。

可读源码入口 （以 GitHub openclaw/openclaw main 为准）：

入口 openclaw.mjs；核心包 packages/（含 gateway、agent、pi、cli、tools、channels 等）；文档 docs/；技能 skills/；扩展 extensions/。
若要理解 connect 握手与协议 ：在 packages/ 内搜索 connect、首帧校验、TypeBox schema。
若要理解 Agent 循环与 runEmbeddedPiAgent ：在 packages/ 内搜索 runEmbeddedPiAgent、agentCommand、会话队列。
若要理解 Exec 与 host 分支 ：在 packages/ 内搜索 exec、host、sandbox、gateway、node，对照 [6] 文档。
典型代码路径示例 （以 GitHub openclaw/openclaw main 为准）：Gateway 的 connect 握手与首帧校验通常在 packages/ 下 gateway 相关包内；Agent 循环入口与 runEmbeddedPiAgent 在 agent/pi 相关包；Exec 工具与 host 分支在 tools 相关包。具体文件名与路径以仓库当前结构为准，上述关键词可快速定位 [2][4][6]。

架构师读源码时可重点看 ：(1) 协议与边界 ------Gateway 的 TypeBox schema、首帧 connect、请求/响应/事件格式，以及 Gateway 与 Pi Agent 的 RPC 边界；(2) 通道适配器 ------各 channel 如何接入、如何归一为统一入站与路由；(3) 会话与队列 ------runEmbeddedPiAgent、会话写锁、每会话队列的实现，便于对照「串行与背压」设计；(4) 钩子与插件 ------before_compaction、before_prompt_build、bootstrap 注入的挂接点，便于设计可扩展生命周期 [2][4]。

实际文件名以仓库当前结构为准 [2][4][6]。社区/博客常用「OpenClaw = Gateway + Agents + Tools + Sessions」概括核心组件（如 [10]），与官方架构描述一致 [2]。

4.2 Gateway 与协议

Gateway 作为单一控制面 ，对外提供类型化 WebSocket API；协议由 TypeBox 等 schema 定义，并用于生成 Swift 模型与 JSON Schema [2]。协议概要 [2]：
- 首帧必须为 connect；之后为 { type, id, method, params } 请求与 { type, id, ok, payload|error } 响应，以及 { type, event, payload, seq?, stateVersion? } 事件。
- 带副作用的操作（如 send、agent）需要幂等键，服务端维护短期去重缓存。
上述行为与 [2] Gateway architecture 一致；实现细节见仓库内 Gateway 相关包及 Gateway protocol 文档 [2]。

据 [10]，OpenClaw 未采用 MCP（Model Context Protocol），而使用自定义协议；创始人曾在播客中表达对 MCP 的批评。此为社区/播客观点，以仓库实现为准。

4.3 Agent 循环与 Pi 运行时

Agent 循环的权威描述见 [4]：由 agentCommand 驱动，解析模型与 thinking/verbose 默认值、加载 skills 快照、调用 runEmbeddedPiAgent，并桥接 Pi 事件到 OpenClaw 的 agent 流（tool / assistant / lifecycle）[4]。
会话写锁、SessionManager、工作区解析、沙箱工作区重定向等均在「Session + workspace preparation」阶段完成；bootstrap 与系统提示在此时参与组装 [4]。钩子（hooks） [4]：文档中提到的钩子包括 before_compaction、after_compaction、before_prompt_build 等。若你要在 compaction 前将关键结论写回 MEMORY ，应挂 before_compaction；在仓库中搜索 before_compaction、compaction、hook 注册或插件钩子列表即可定位实现位置，具体 API 以 [4] 与官方 Memory/Compaction 文档为准。算法/模型工程师若要做自定义摘要或 compaction 前写回记忆，可在仓库中定位上述钩子并挂接自己的摘要器或记忆写入逻辑 [4]。

4.4 工具与沙箱

Exec ：文档 [6] 指出 exec 工具支持 sandbox / gateway / node 三种宿主；沙箱关闭时，即使配置为 host=sandbox 也会回退到主机执行，因此若需隔离必须正确开启 sandbox 并配置 Docker 等 [3][6]。配置项包括 tools.exec.*（超时、安全二进制、审批门控等）[6]。阅读源码时可在仓库中搜索 exec、host、sandbox、gateway、node 等，结合 packages/ 下 tools 相关实现与 [6] 文档对照。
Browser ：由 OpenClaw 管理的 Chrome/Chromium，支持多配置（如 openclaw 与 chrome），通过本地控制服务与 CDP 与 Agent 交互 [7]。实现通常位于与 browser 工具相关的包内，可搜索 browser、CDP、puppeteer 等。
沙箱：非主会话可使用每会话 Docker 容器，通过 agents.defaults.sandbox.mode: "non-main" 等开启；沙箱内默认允许的工具集与拒绝集在 [3] 中有说明（如允许 bash、process、read、write、edit、sessions_*，拒绝 browser、canvas、nodes、cron、discord、gateway）[3]。源码中沙箱创建、工作区挂载与工具路由需在仓库内搜索 sandbox、exec、host、Docker 等关键词对照文档阅读。

4.5 关键逻辑与可借鉴点（基于文档的归纳）

单点控制面：将「多通道 + 多客户端 + Agent」统一到一个 Gateway 进程与一个 WebSocket 端口，便于权限与审计集中处理；若你设计多入口 Agent 系统，可借鉴「通道适配器 → Gateway → Agent」的分层 [2]。
会话串行与队列：Agent 按会话串行执行，避免并发写同一会话状态；compaction 与重试在循环内显式建模，便于长对话稳定 [4]。
工具宿主分离：Exec 的 sandbox/gateway/node 三分法适合「可信主机 + 不可信会话」场景；拒绝集（如 gateway、cron）对控制面保护很重要 [3][6]。
上下文与 compaction 实现：系统提示组装、bootstrap 截断、compaction 触发与重试的代码路径集中在 Agent/Pi 相关包；算法工程师阅读时可结合 [4] 与 [12] 对照「上下文预算 → 压缩 → 重试」的闭环。
架构师可借鉴的完整图景 ：单点控制面 （多通道 + 多客户端 + Agent 统一到一进程一端口）→ 会话串行与队列 （按会话执行、compaction 与重试在循环内）→ 工具宿主分离 （sandbox/gateway/node 三分法 + 拒绝集保护控制面）→ 钩子与插件 （compaction、prompt、bootstrap 可插接）→ 上下文管线（预算 → 压缩 → 重试闭环）。若你设计「可扩展、可运维」的 Agent 平台，可把上述几点作为架构 checklist，再按需做多实例、多租户或替换协议 [2][3][4][6]。

实战：最小 Skill 与会话转录

最小 SKILL.md [1]：在工作区下创建技能目录并放入 SKILL.md，例如 ~/.openclaw/workspace/skills/my-skill/SKILL.md，内容可为几行说明与可选规则，例如：
markdown 复制代码
```
# my-skill
When the user asks about X, prefer doing Y. Do not Z.
```
技能可通过 skills watcher 在下次 Agent 轮次或刷新时加载；部分安装型技能需通过 openclaw 或 Control UI 的 skill install 流程，以官方 Skills 文档为准。
会话转录 [3][4]：~/.openclaw/agents/<agent>/sessions/*.jsonl 中每行通常为一条 JSON 记录（消息、工具调用、助手回复等），用于会话连续性与记忆索引。格式上每行一个 JSON 对象，常见键可包含 type、role、content 或 tool_call、tool_result 等（以仓库与 [4] 文档为准）。调试时可直接打开某会话的 .jsonl 文件查看结构（注意脱敏），便于理解「Agent 看到了什么、调用了哪些工具」。

5. 场景推荐

5.1 适合的场景

个人助理：单用户、多设备、多通道（如 WhatsApp + Telegram + WebChat），希望助手在授权下执行整理邮件、日程、文件与简单自动化 [1][2]。例如：在 Telegram 里发「把本周会议纪要整理成 Markdown 发到我邮箱」，助手在工作区内整理后通过配置的邮件或消息通道反馈。
本地优先、数据可控 ：所有状态与会话存于本机（或自控服务器），适合对隐私与数据主权有要求的用户 [1][3]。凭证与配置在 ~/.openclaw，工作区在 ~/.openclaw/workspace，不依赖厂商云端存储。
多通道统一入口：已有大量沟通在即时通讯中完成，希望在不离开现有应用的前提下下发任务并接收结果 [1]。同一助手可同时在 WhatsApp、Slack、WebChat 上响应，按会话与路由规则区分。
可扩展工具与技能：通过 Skills 与插件扩展能力，适合愿意自定义工作流与集成内部工具的用户 [1]。例如：自定义 SKILL.md 注入领域知识，或通过 Webhook/Cron 与内部系统对接。

5.2 不适合或需谨慎的场景

强实时、低延迟：Agent 循环含模型推理与工具执行，延迟高于纯聊天；不适合对响应时间有极高要求的实时控制场景 [4]。
多租户/高合规审计：官方明确不推荐在单 Gateway 上为多互不信任方服务；若需严格审计与租户隔离，应分 Gateway 或分主机/用户 [3]。
无本地部署条件：OpenClaw 设计为自托管；若只能使用纯云端 SaaS，需考虑其他产品或自行部署到云主机并通过 Tailscale/SSH 访问 [1][2]。

5.3 能力边界简述

执行能力 ：取决于已配置的工具与权限（文件、终端、浏览器、节点、cron 等）；默认主会话在主机上具备完整工具访问，非主会话建议沙箱隔离 [1][3]。据 [10]，OpenClaw 能做什么完全取决于可调用的工具组合 ；复杂自动化（如某些网站注册、高防爬场景）还受现实限制；与「给现有 AI Agent 更大权限」在使用体验上可接近，但底层架构仍有差异。未配置的通道（如未登录的 WhatsApp）无法收发；Nodes 能力依赖实际连接的设备与声明。
模型能力 ：取决于所配置的 LLM（如 Claude、GPT 等）；官方推荐 Anthropic Pro/Max（100/200）与 Opus 4.6 以兼顾长上下文与抗提示注入 [1][3]。长对话多步任务 ：中间步骤在 compaction 后可能被压缩为摘要，模型可能遗忘细节；可配合记忆写入或手动 /compact 时附说明（如「保留决策与待办」）[4]。算法侧可通过优化摘要策略、或在 compaction 前将关键决策写回 MEMORY/长期记忆，减轻长对话遗忘 [4][8]。
可用性与运维 ：单 Gateway 单点；若主机或进程故障，需自行做进程管理与恢复；远程访问依赖 Tailscale/SSH 或自建反向代理 [2]。架构师评估边界时：单点与横向扩展（多实例、每实例一 Gateway）、信任边界（多互不信任方不推荐共用一个 Gateway [3]）、以及平台与依赖（Docker 沙箱、Nodes 依赖设备端）会直接影响你做高可用或多租户方案时的选型与改造量 [1][2][3]。

实战：一条龙示例（文件 + 终端）

用 CLI 发一条让助手在工作区创建文件并写入日期的任务，可验证「五只手」中的文件与终端：

可复制命令与预期 [1][6]：

bash 复制代码

openclaw agent --message "在工作区创建一个名为 hello.txt 的文件，并在其中写入今天的日期（YYYY-MM-DD），然后告诉我路径。"

预期：Agent 会调用写文件类工具（如 write 或通过 exec 执行 echo ... > hello.txt），工作区 ~/.openclaw/workspace/ 下应出现 hello.txt，内容为当日日期；回复中会给出文件路径。
若未出现 ：检查工作区路径配置与工具权限（主会话默认有文件与 exec 权限）；可运行 openclaw gateway status 与 openclaw security audit 排查 [3][5]。

6. 迁移与落地建议

6.1 从零接入（推荐路径）

环境：Node ≥22 [1][5]。
安装：npm install -g openclaw@latest 或使用官方安装脚本（如 curl -fsSL https://openclaw.ai/install.sh | bash）[1][5]。
配置：运行 openclaw onboard --install-daemon 完成向导（鉴权、Gateway、可选通道与技能）；向导会安装 Gateway 守护进程（launchd/systemd）[1][5]。
验证：openclaw gateway status 检查服务；openclaw dashboard 打开 Control UI，或直接访问 http://127.0.0.1:18789/ [5]。
首次对话 ：在 Control UI 中发送消息，或执行 openclaw agent --message "Ship checklist" --thinking high [1]。

Demo：从零到首次对话的完整 CLI 序列 [1][5]（复制到终端按顺序执行，Windows 用户可用 WSL 或 PowerShell 等价命令）：

bash 复制代码

# 1. 安装（需 Node ≥22）
npm install -g openclaw@latest

# 2. 运行向导并安装 daemon（会引导鉴权、通道、技能）
openclaw onboard --install-daemon

# 3. 检查 Gateway 是否在跑
openclaw gateway status

# 4. 打开 Control UI（或浏览器访问 http://127.0.0.1:18789/）
openclaw dashboard

# 5. 用 CLI 发一条测试消息（在另一终端或向导完成后）
openclaw agent --message "列出今天要做的事" --thinking high

Demo：最小可运行配置 [1]：若仅想指定模型、其余用默认，可在 ~/.openclaw/openclaw.json 中只保留（具体键名如 agent.model / agent.model.primary 以官方文档为准）：

json 复制代码

{
  "agent": {
    "model": "anthropic/claude-opus-4-6"
  }
}

完整配置键见 Configuration 与 Configuration reference；首次使用建议仍走 openclaw onboard 以配置鉴权与通道。

完整入门见 [5] Getting Started 与 [1] 中 Quick start、From source 等小节。

6.1.1 部署与运行要点

环境：Node ≥22；若从源码构建，需满足仓库 package.json 与文档中的依赖要求 [1][5]。
安装方式 ：全局安装 npm install -g openclaw@latest，或克隆仓库后 pnpm install 与 pnpm build，再通过 node openclaw.mjs 或 scripts 启动 [1]。
配置文件位置 [5]：主配置默认在 ~/.openclaw/openclaw.json；可通过环境变量 OPENCLAW_CONFIG_PATH 覆盖配置文件路径、OPENCLAW_STATE_DIR 覆盖状态目录、OPENCLAW_HOME 覆盖内部路径解析的 home。修改配置后需重启 Gateway 或由 daemon 自动重载（以文档为准）。
常见报错与排查 ：见下「常见报错与排查」小节；另可运行 openclaw security audit 发现配置与暴露面问题 [3]。

常见报错与排查 [5][3]

现象	可能原因	建议操作
端口 18789 已被占用	其他进程占用或重复启动 Gateway	检查 `lsof -i :18789`（或 Windows 等价）；关闭重复进程或修改 `gateway.port` / `OPENCLAW_GATEWAY_PORT`
Gateway 连接被拒绝 / token 不匹配	未配置或填错 `gateway.auth.token` / `OPENCLAW_GATEWAY_TOKEN`	在 `openclaw.json` 中设置 `gateway.auth: { mode: "token", token: "..." }`；或运行 `openclaw doctor --generate-gateway-token` 生成
通道登录失败（如 Telegram/WhatsApp）	Bot token 错误、网络或凭证过期	检查 `channels.telegram.botToken` 或 `TELEGRAM_BOT_TOKEN`；WhatsApp 需 `openclaw channels login` 重新链接；参考 Channels troubleshooting
Agent 无响应或超时	模型未配置、API 密钥无效、会话/工作区路径错误	检查模型配置与 auth profiles（`~/.openclaw/agents/<agent>/auth-profiles.json`）；确认工作区存在且可读；查看 Gateway 日志

单通道最小配置示例：Telegram [1]

在 BotFather 获取 Bot Token，设置环境变量 TELEGRAM_BOT_TOKEN 或在 openclaw.json 中配置：
json 复制代码
```
"channels": { "telegram": { "botToken": "YOUR_BOT_TOKEN" } }
```
运行 openclaw onboard --install-daemon 时在向导中选择启用 Telegram；或直接编辑 openclaw.json 添加上述 channels.telegram。
首次在 Telegram 中向该 Bot 发消息后，若启用了 DM pairing，需执行 openclaw pairing list telegram 与 openclaw pairing approve telegram <code> 批准自己，再发消息即可收到助手回复。群组需配置 channels.telegram.groups 与 requireMention 等 [1]。

Demo：配对批准流程 （以 Telegram 为例；其他通道将 telegram 换为对应通道名）[1]：

bash 复制代码

# 查看当前待批准的配对请求（会显示 channel 与 code）
openclaw pairing list telegram

# 批准指定 code 的请求（将 <code> 替换为 list 中显示的配对码）
openclaw pairing approve telegram <code>

6.2 从现有 Agent 迁移时的借鉴点

控制面与执行分离：若现有系统是「单进程全包」，可借鉴 Gateway 与 Agent 分离、工具在 Gateway 侧调度、Agent 仅负责推理与调用的模式 [2][4]。
记忆与持久化 ：可引入「会话转录落盘 + 可选记忆索引」；若采用 Markdown 记忆文件，可参考社区讨论的 MEMORY.md + 按日流水 + 混合检索思路，并与官方 openclaw memory 能力对照 [8][9]。
工具与沙箱 ：为执行类工具划分 sandbox / gateway / node 等宿主，非主会话使用独立沙箱（如 Docker），并通过配置 allowlist/denylist 控制工具暴露 [3][6]。
多通道：若需多入口，可抽象「通道适配器 + 统一入站路由」类似 [1] 的 Channels 设计，再与现有会话与权限模型对接。
推理与上下文管线 ：自研 Agent 时可借鉴其系统提示分层 （固定区块 + bootstrap + 每轮覆盖）、bootstrap 字符上限与按需检索分离 、以及 compaction 与重试的显式建模，便于做 token 预算与长对话稳定性 [4][12]。
架构师迁移时可重点借鉴 ：(1) 单控制面与协议 ------单 Gateway、类型化 WebSocket API、connect/agent/事件模型，便于多端统一接入；(2) 通道适配器与统一入站 ------多通道归一为同一收件箱与路由，再进入会话与 Agent；(3) 会话串行与每会话队列 ------避免并发写会话、compaction 与重试在循环内；(4) 工具宿主三分法与沙箱 ------sandbox/gateway/node、非主会话默认沙箱、工具 allow/deny 与 profile；(5) 钩子与插件 ------compaction、prompt、bootstrap、记忆的可插接点；(6) 安全分层------身份 → 范围（工具/沙箱）→ 模型，控制面工具（gateway、cron）默认拒绝不可信代理 [2][3][4][6]。

迁移步骤建议（从现有 Agent 到类 OpenClaw 能力）：先确定「执行层」范围（文件/终端/浏览器/消息），为每种执行定义工具接口与宿主（本机/沙箱/节点）；再引入会话持久化（转录落盘）与可选记忆索引（官方 memory 或自建 MEMORY.md + 检索）；然后接入 1～2 个通道做收件箱统一；最后按威胁模型配置工具 allow/deny 与沙箱，并运行安全审计 [3][6]。

6.3 部署形态与跨形态迁移借鉴

OpenClaw 是本地安装（自托管） ；与云端 Agent （推理/执行在厂商或自建云）、纯端侧 Agent （推理与执行均在手机/设备本地）形成三种常见部署形态。按部署形态的对比表见第 7 节；此处仅写可迁移借鉴点，便于在本地、云端、端侧之间做设计迁移或选型参考。

从 OpenClaw 设计可迁移到云端/端侧 [1][2]：

单控制面与协议分离（Gateway 式 WebSocket API）→ 在云端可对应为 API 网关 + 工具编排、多租户下的会话与执行隔离。
工具层抽象（sandbox/gateway/node）→ 在端侧可对应为本地运行时 + 受限工具集。
记忆层与会话转录分离、多通道收件箱与统一入站路由、SKILL.md 式技能注入，在云端可做统一入站与技能市场，在端侧可做本地技能包与同步策略。

以上为通用架构思路，非 OpenClaw 独有。

从云端/端侧到本地可借鉴：

云端常见做法：弹性伸缩与多实例、托管更新与灰度、多租户隔离与审计日志。
端侧常见做法：离线优先与同步策略、端侧小模型与低延迟、隐私不出设备。

若做「本地为主、可选云端协同」或「本地 + 端侧节点」，可参考上述思路做混合架构；属业界常见实践，具体实现依项目而定。

对算法/架构师 ：本地 / 云端 / 端侧三种形态在架构上可做清晰映射------单控制面在云端对应 API 网关 + 工具编排、在端侧对应本地运行时 + 受限工具集；会话与记忆的分离、多通道收件箱、SKILL 式技能注入均可平移。选型或做混合架构时，可把「控制面与协议」「执行层抽象」「记忆与转录分离」作为跨形态复用的设计单元 [1][2]。

7. 相关技术与项目对比

7.1 与其它开源 Agent / 助手的对比（表述基于公开信息，数据以各项目为准）

维度	OpenClaw	典型 AutoGPT/LangChain Agent	说明
定位	个人、单用户、本地优先、常驻助手	多偏任务型/脚本型 Agent	OpenClaw 强调「你的个人助手」与多通道收件箱 [1]
执行环境	主机 + 可选 Docker 沙箱、Nodes	多为本地 Python/Node 进程	OpenClaw 有明确沙箱与 exec host 配置 [3][6]
通道	WhatsApp/Telegram/Slack/.../WebChat 等	多为 API/CLI/自定义	[1] 内置多通道
记忆	会话落盘 + memory 插件（索引/检索）	多为向量库或自定义	[9] 及社区 [8]
开源协议	MIT	各异	[1]
安全与沙箱	明确沙箱/工具 profile/审计命令	多数无统一沙箱或需自建	[3][6]
多通道	内置多 IM + WebChat	多为单入口或需自集成	[1]

（上表为概念性对比，具体功能与版本以各项目 README 与文档为准；数据来源：各项目官方 README 与文档。）

算法/模型工程师选型时可额外关注：上下文管理方式（如 compaction 策略、摘要由谁生成）、工具与模型接口（function calling 与 schema 体积）、以及系统提示与记忆注入的分离程度，便于与自研推理管线对齐 [4][12]。

算法/架构师选型时可额外关注 ：(1) 控制面与协议 ------单 Gateway、WebSocket 类型化 API、与 MCP 等标准的取舍（OpenClaw 采用自定义协议 [10]）；(2) 扩展与单点 ------单实例 vs 多实例、通道适配器与统一入站、钩子与插件体系；(3) 安全架构 ------身份 → 范围 → 模型的分层、控制面工具（gateway、cron）与数据面分离、工具 profile 与 deny 的配置化；(4) 部署形态------本地自托管 vs 云端 vs 端侧时的架构映射（见 6.3、7.2），便于做混合或迁移 [2][3][4][10]。

若你的目标是 X，在 OpenClaw 里对应做 Y [2][3]：

目标	做法
多通道收件箱	用内置 Channels 并配置各通道的 `channels.*`
执行隔离	用 `agents.defaults.sandbox.mode: "non-main"` 与 `tools.deny`
仅消息能力	设 `tools.profile: "messaging"` 并 deny 其他组
远程访问	Tailscale Serve 或 SSH 隧道

7.2 按部署形态对比（本地 vs 云端 vs 端侧）

维度	本地自托管（OpenClaw）	云端 Agent	纯端侧 Agent
部署位置	用户机器或自控服务器	厂商/自建云	手机/设备本地
数据与执行	均在己控环境（~/.openclaw）	多在云端，部分可边缘	均在设备本地
扩展性	单机单 Gateway，扩展靠多实例	弹性伸缩、多租户	受设备资源限制
离线能力	依赖本机与模型 API 可用性	通常需联网	可完全离线（端侧模型）
延迟与隐私	可控，数据不出己控	网络延迟，数据在云	低延迟，隐私不出设备
典型代表	OpenClaw [1]	各类云端 Copilot/助手	设备厂商或 on-device 方案

（上表为概念性对比，典型代表与能力以公开资料为准；与第 6.3 节「部署形态与跨形态迁移借鉴」呼应。）

部署形态关系可简化为（概念图）[1][2]：
纯端侧
设备本地
云端 Agent
厂商 API
云端数据
本地自托管
Gateway
Workspace
用户
用户
用户

7.3 与闭源 Copilot / Assistant 的差异

OpenClaw：自托管、数据在己、可审计与改代码、需自行维护与部署 [1][3]。
闭源助手：多为云端、数据与模型由厂商控制、无需运维但定制与隐私受限。选择取决于对数据主权、定制与运维成本的权衡。

实战：想体验「主机 exec vs 沙箱 exec」的差异，可在开启 agents.defaults.sandbox.mode: "non-main" 后，在群组会话中让助手执行一条简单命令（如 echo test），再在主会话中执行同一条；对比工作区路径与进程归属（如 ps 或任务管理器），可直观理解 host 与沙箱隔离 [3][6]。

8. 安全与权限

8.1 威胁模型（据 [3]）

助手可做：向任意人发消息（若授予 WhatsApp 等）、访问网络、读写文件、执行任意 Shell 命令 [3]。
联系人可做：探测基础设施、社会工程、诱导助手执行不当操作 [3]。
核心原则 ：先做身份与访问控制，再谈智能；假设模型可被操纵，通过工具策略、执行审批、沙箱与通道 allowlist 限制影响范围 [3]。从算法/对齐视角 ：系统提示中的 Safety 仅为建议，真正约束依赖身份与工具策略；设计自研 Agent 时宜将「模型侧 guardrail」与「系统侧硬约束」分离，避免仅靠提示防注入或越权 [3][4]。从架构师视角 ：身份 → 范围 → 模型 是典型的分层防御------身份层决定「谁可连、谁可 DM」；范围层决定「在哪里执行、哪些工具可用」（沙箱、allow/deny、profile）；模型层仅作最后一道建议。控制面 （gateway、cron、config.apply、update.run）与数据面/执行面（文件、exec、browser、消息）分离，对不可信代理默认拒绝控制面工具，便于最小权限与审计边界；设计自研平台时可将「控制面操作」单独建模与鉴权 [3][6]。

安全控制的分层可概括为（据 [3]）：身份优先 → 范围（工具/沙箱）→ 模型最后。
谁可连、谁可 DM
哪里执行、哪些工具
抗注入、指令遵循
Identity 身份
Scope 范围
Model 模型
限制影响

8.2 加固建议摘要

运行 openclaw security audit （及 --deep / --fix / --json），定期检查暴露面与错误配置 [3]。
默认收紧 ：gateway.bind: "loopback"、gateway.auth.mode: "token" 或 password；非主会话 sandbox.mode: "non-main"；工具 profile 使用 messaging 或更严，对非信任代理拒绝 gateway、cron、sessions_spawn、sessions_send 等 [3]。
DM ：保持 dmPolicy: "pairing" 或严格 allowlist；多用户时使用 session.dmScope: "per-channel-peer" 隔离会话 [3]。
文件与网络 ：~/.openclaw 权限收紧（如 700/600）；不将 Gateway 无认证暴露于 0.0.0.0；远程访问用 Tailscale 或 SSH 隧道 [3]。
提示注入：限制高风险工具（exec、browser、web_fetch、web_search）到可信代理或显式 allowlist；对不可信输入使用只读或禁用工具的「阅读」代理再转交给主 Agent [3]。

授权与确认模型 ：OpenClaw 将「谁可以触发哪些操作」交给配置与配对解决------主会话（DM）默认具备完整工具；非主会话建议沙箱与工具限制；高风险操作（如 gateway、cron、sessions_spawn）应对不可信代理默认拒绝 [3]。若需「每次执行前人工确认」，需通过自定义工具或审批门控（如 tools.exec 的审批）实现，详见 [3][6]。

审计与日志 ：openclaw security audit 用于检查配置与暴露面；会话转录与 Agent 运行状态存储在 ~/.openclaw/agents/<agent>/sessions/ [3][4]。若需合规审计日志，需结合系统日志与自定义钩子或扩展记录关键操作；官方文档见 [3] Security。

实战：审计输出解读 [3]

运行 openclaw security audit（或 --deep）后，典型 checkId 与处理建议示例：

checkId	含义	建议
`gateway.bind_no_auth`	非 loopback 绑定且未配置认证	设置 `gateway.bind: "loopback"` 或配置 `gateway.auth.mode` + token/password
`gateway.loopback_no_auth`	反向代理后 loopback 可能无认证	配置 `gateway.auth.*` 并确保代理正确传递身份
`tools.exec.host_sandbox_no_sandbox_defaults`	配置了 host=sandbox 但沙箱未开，实际在主机执行	开启 `agents.defaults.sandbox.mode` 或改为 `host=gateway` 并配审批
`fs.state_dir.perms_world_writable`	`~/.openclaw` 权限过松	收紧为 700；`openclaw security audit --fix` 可自动修复部分项

完整清单与 Primary fix key 见 [3] Security 的 Security audit glossary。

Demo：安全审计与自动修复 [3]：

bash 复制代码

# 常规检查（暴露面、配置、权限等）
openclaw security audit

# 深度检查（含对 Gateway 的探测）
openclaw security audit --deep

# 自动修复可修复项（如目录权限）
openclaw security audit --fix

# JSON 输出便于脚本处理
openclaw security audit --json

社区与第三方提醒 [10]：据 [10] 等分析，高权限 Agent 存在文件与配置相关风险，建议在独立设备或隔离环境中尝鲜；与 [3] 官方加固建议一致（最小权限、审计、隔离）。

实战：收紧非主会话（群组/频道） [3]

主会话不受以下限制；仅对新消息/群组会话生效。在 openclaw.json 中示例：

json5 复制代码

{
  "agents": { "defaults": { "sandbox": { "mode": "non-main" } } },
  "tools": {
    "deny": ["gateway", "cron", "sessions_spawn", "sessions_send"],
    "profile": "messaging"
  }
}

可根据需要再增加 group:fs、group:runtime 等；主会话（DM）仍使用默认工具集，除非在 agent 级覆盖。

8.3 控制面工具风险

cron 、gateway （含 config.apply、config.patch、update.run）会持久改变控制面；对处理不可信内容的代理应默认拒绝 [3]。引用原句：「For any agent/surface that handles untrusted content, deny these by default」[3]。

9. 局限与延伸

9.1 当前局限（基于文档与常见需求）

单 Gateway 单主机：一个主机只跑一个 Gateway，横向扩展需多实例或分层架构，官方未提供多 Gateway 集群方案 [1][2]。
信任边界：Gateway 与配置目录被视作可信；多互不信任方共用同一 Gateway 不被推荐 [3]。
记忆与检索：当前官方提供 memory 插件与 CLI；若你依赖社区所述的 MEMORY.md + 混合检索，需自行对照仓库与文档确认与当前版本一致 [8][9]。
延迟与实时性：Agent 循环含模型推理与工具执行，不适合毫秒级或强实时控制；流式输出可改善体感，但整体延迟高于纯聊天 [4]。
平台与依赖：部分能力依赖平台（如 iMessage 依赖 BlueBubbles 或 imsg；Nodes 依赖 macOS/iOS/Android 应用）；Docker 沙箱需宿主机支持 Docker [1][3]。

9.2 延伸阅读与参考

官方文档入口：https://docs.openclaw.ai [1]。
架构与协议：Architecture、Gateway protocol、Agent Loop [2][4]。
安全与运维：Security、Gateway runbook、Troubleshooting [3]。
仓库：https://github.com/openclaw/openclaw [1]。

社区与生态：OpenClaw 为开源项目，星数、贡献与插件动态以 GitHub 仓库与官方博客/公告为准；第三方教程与讨论（如记忆方案、命名历史）引用时已标明「社区」或「据 xxx」[8]。后续可关注官方 Skills、extensions 与 Gateway 协议演进，便于集成与二次开发。

其他技术博客与社区：如 [10] 腾讯云开发者社区（能力边界、安全与 MCP）、[11] getopenclaw.ai（第三方，记忆与 ChatGPT 对比）；阅读时注意区分官方文档与第三方解读，以 [1]--[9] 及 [12] 为准。

若你是 AI/大模型算法工程师 ：本文中与推理、上下文和 Agent 架构最直接相关的部分包括：(1) 3.4 Agent 循环与上下文 及 面向算法/模型工程师的要点 ------系统提示结构、bootstrap 注入与 token 上限、compaction 与重试、Safety 与硬约束的分离；(2) 3.5 记忆与持久化 、3.6 Compaction ------长程记忆、检索注入时机与上下文压缩策略，可类比到自研 RAG/记忆管线；(3) 8 安全与权限 ------提示注入与模型鲁棒性、工具滥用与沙箱，对「模型可被操纵」下的系统设计有参考价值。若你负责自研 Agent 的上下文组装、长对话压缩或工具编排 ，可重点阅读上述小节并在仓库中对照 system prompt、bootstrap、compaction 相关实现 [4]。

若你是 AI/算法架构师 ：本文对设计或评审「多入口、可执行、可扩展」的 Agent 平台有多处可直接借鉴。(1) 第 2 章架构总览 ------单 Gateway 控制面的取舍与平替、协议与分层（通道 → Gateway → Agent → 工具）、控制面与执行面分离、扩展点（通道适配器、Nodes、Skills）；(2) 3.2 工具与执行 、3.4 Agent 循环与上下文 及 面向算法/架构师的要点 ------工具宿主（sandbox/gateway/node）抽象、Agent 循环与每会话队列、RPC 与流式、钩子与可扩展性、上下文管线与 compaction 的架构意义；(3) 3.5 记忆 、3.7 控制与隔离 ------记忆插件与会话转录的存储分离、身份→范围→模型与工具 profile 的配置化策略；(4) 第 4 章源码解读 ------架构师读源码时的关注点（协议与边界、通道适配器、会话与队列、钩子与插件）、4.5 关键逻辑与可借鉴的完整图景；(5) 第 6 章迁移与落地 ------架构师迁移时的六点借鉴、6.3 部署形态与跨形态的架构映射；(6) 第 7 章对比 ------算法/架构师选型时关注的维度（控制面与协议、扩展与单点、安全架构、部署形态）；(7) 第 8 章安全与权限 ------分层防御、控制面与数据面分离、控制面工具风险。若你负责系统架构、协议设计、扩展点与安全分层 ，可把上述章节作为 checklist，并在仓库中对照 Gateway 协议、runEmbeddedPiAgent、钩子与工具宿主实现 [2][3][4][6]。

9.3 术语速查

术语	含义
Gateway	单机控制面进程，持有通道连接与 WebSocket API，默认 127.0.0.1:18789；端口可由 `gateway.port` 或 `OPENCLAW_GATEWAY_PORT` 覆盖 [2][5]
Pi agent	OpenClaw 内嵌的 Agent 运行时，执行推理与工具调用 [4]
主会话（main）	与用户直接 DM 的会话，默认具备完整工具权限 [3]
工作区（workspace）	默认 `~/.openclaw/workspace`，对应配置项 `agents.defaults.workspace`；注入 AGENTS.md/SOUL.md/TOOLS.md 与 skills [1]
MEMORY.md	社区讨论中的 Markdown 长期记忆文件；当前官方以 memory 插件与 CLI 为准 [8][9]
Compaction	上下文过长时的压缩与重试机制，见 [4] 与 Compaction 文档；配置在 `agents.defaults.compaction`
沙箱（sandbox）	非主会话可选每会话 Docker 隔离，或 Exec 的 host=sandbox [3][6]
Node	以 role: node 连接 Gateway 的设备，提供 camera、screen、location 等能力 [2]
openclaw.json	主配置文件，默认 `~/.openclaw/openclaw.json`，可由 `OPENCLAW_CONFIG_PATH` 覆盖 [5]

参考文献

编号	标题 / 说明	URL	备注
[1]	OpenClaw 仓库 README	https://github.com/openclaw/openclaw	项目介绍、安装、通道、工具、安全概要、How it works 图
[2]	Gateway architecture	https://docs.openclaw.ai/concepts/architecture	架构、组件、协议、连接与认证、远程访问
[3]	Security	https://docs.openclaw.ai/gateway/security	威胁模型、加固、审计、DM、沙箱、控制面工具风险
[4]	Agent Loop	https://docs.openclaw.ai/concepts/agent-loop	Agent 循环、入口、队列、会话与工作区、compaction、钩子
[5]	Getting Started	https://docs.openclaw.ai/start/getting-started	安装、向导、Gateway 状态、Control UI、环境变量
[6]	Exec Tool	https://docs.openclaw.ai/tools/exec	exec 工具宿主、超时、安全与审批
[7]	Browser (OpenClaw-managed)	https://docs.openclaw.ai/tools/browser	浏览器配置、多配置、CDP
[8]	社区/第三方：记忆与命名	见正文 1.2、3.5 节	MEMORY.md、混合检索、Clawdbot/Moltbot 命名历史等以社区与第三方报道为准，正文已标明
[9]	Memory CLI / 记忆能力	https://docs.openclaw.ai	`openclaw memory` 与 memory 插件；memory 相关页面见文档索引
[10]	腾讯云开发者社区，南泉青年，《扒开OpenClaw的源代码，我们说点真话》	https://cloud.tencent.com/developer/article/2627425	能力边界、Gateway+Agents+Tools+Sessions、安全与 MCP；检索于 2026-02
[11]	getopenclaw.ai（第三方），《AI Assistant with Memory: How It Works and Why It Matters》	https://www.getopenclaw.ai/blog/ai-assistant-with-memory	记忆分层与 ChatGPT 对比、本地隐私；第三方解读，以官方 [9] 为准；检索于 2026-02
[12]	System Prompt	https://docs.openclaw.ai/concepts/system-prompt	系统提示结构、bootstrap 注入、promptMode、token 与截断、Safety

说明：上述 URL 与描述以写作时官方文档与仓库为准；若链接失效或路径变更，请以 https://github.com/openclaw/openclaw 与 https://docs.openclaw.ai 为入口查找最新文档。建议引用时注明访问日期或版本（如「访问于 2026-02」或「main 分支」）以便追溯。编号 [10][11] 为技术博客或社区文章，非官方文档；[12] 为官方文档；内容与官方不一致时以官方为准。