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

$1$ 中明确列出：多通道收件箱（Multi-channel inbox）使助手可在上述渠道接收与回复；群组路由支持 @ 提及、回复标签、按渠道分块与路由；具体规则见官方 Channels 文档 $1$ 。

3.2 工具与执行能力

助手具备「第一方工具」能力 $1$ ，主要包括：

浏览器：由 OpenClaw 管理的 Chrome/Chromium，CDP 控制，支持快照、操作、多配置 $1$ $7$ 。
Canvas：Agent 可驱动的可视化工作区，支持 A2UI 推送与交互 $1$ 。
Nodes ：相机、录屏、location.get、通知等；macOS 上还有 system.run、system.notify $1$ 。
Cron + Webhooks：定时任务与 Webhook 触发 $1$ 。
Skills 平台 ：捆绑/托管/工作区技能，通过 SKILL.md 与安装门控管理 $1$ 。

Exec 工具（Shell/命令执行） $6$ ：

支持在工作区内执行 Shell，可选前台/后台、超时（默认 1800s）、PTY、环境与工作目录控制。
执行宿主可选：sandbox（默认）、gateway、node；沙箱默认关闭，需通过 agents.defaults.sandbox.mode 或 host=gateway 与审批机制配合使用 $3$ $6$ 。
未开沙箱时的具体表现 ：当沙箱未开启时，即使配置为 host=sandbox，Exec 也会回退到主机 执行------命令实际在 Gateway 所在主机运行、工作区路径为主机上的 ~/.openclaw/workspace（或该会话对应工作区）；审计会给出 tools.exec.host_sandbox_no_sandbox_defaults 等告警 $3$ $6$ 。要真正隔离，必须开启沙箱（如 agents.defaults.sandbox.mode: "non-main" 配 Docker）。
平替方案 ：若不想用主机 Exec，可 (1) 使用 host=gateway 并配合审批门控（每次执行需批准）；(2) 使用 host=node 在已配对节点上执行；(3) 对不可信会话直接禁用 exec（tools.deny 或 tools.exec.security: "deny"），仅保留只读工具 $3$ $6$ 。

安全策略 ：非主会话（如群组、频道）建议通过 agents.defaults.sandbox.mode: "non-main" 在每会话 Docker 沙箱中执行，以限制影响范围 $1$ $3$ 。详见本文第 8 节及 $3$ Security。

「五只手」概括（便于记忆）：执行层可归纳为五类能力 $1$ $6$ $7$ ，每类均可通过配置与工具 profile 做 allow/deny 控制 $3$ 。

类别	说明
文件	工作区内读写、编辑
终端	Exec 工具在 sandbox / gateway / node 上跑 Shell
浏览器	OpenClaw 管理的 Chrome、CDP 快照与操作
消息平台	多通道收件箱的发送与回复
API/扩展	Webhook、Cron、Nodes 能力（相机、录屏、位置等）及 Skills

执行路径可简化为：用户/通道 → Gateway → Pi Agent → 按需调用具体工具（文件/终端/浏览器/消息/API）；工具结果回填上下文后继续推理或结束轮次。从模型接口 角度，工具以 function calling 形式暴露给 LLM，工具列表与 schema 会占用系统提示 token；算法侧可关注工具数量与描述长度对上下文与调用准确率的影响 $4$ 。从架构角度，工具宿主（sandbox / gateway / node）的抽象把「在哪里执行」与「执行什么」解耦，便于做执行层扩展、隔离边界与多端（本机/沙箱/设备节点）统一编排；allow/deny 与工具 profile 的配置化策略也便于按会话/身份做策略分叉 $3$ $6$ 。下图概括数据流 $1$ $2$ $4$ ：
用户或通道
Gateway
Pi Agent
文件
终端 Exec
浏览器
消息平台
API或Skills

3.3 会话与工作区

会话模型 $1$ ：存在 main 会话（直接私聊）、群组隔离、按会话的激活模式与队列模式等；群组规则见 Groups。
工作区 $1$ ：默认根目录为 ~/.openclaw/workspace（可由 agents.defaults.workspace 配置）。注入到提示的配置文件包括 AGENTS.md、SOUL.md、TOOLS.md；技能位于 ~/.openclaw/workspace/skills/<skill>/SKILL.md $1$ 。

工作区与磁盘布局（实战可改什么） $1$ $3$ $5$ ：

路径/配置	说明
`~/.openclaw/`	状态根目录，可由 `OPENCLAW_STATE_DIR` 覆盖；建议权限 700 $3$
`~/.openclaw/openclaw.json`	主配置文件，可由 `OPENCLAW_CONFIG_PATH` 覆盖；建议权限 600 $3$ $5$
`~/.openclaw/workspace`	工作区根目录，对应 `agents.defaults.workspace`；Agent 读写文件默认在此 $1$
`~/.openclaw/workspace/AGENTS.md`、`SOUL.md`、`TOOLS.md`	注入到系统提示的配置；改这些会直接影响 Agent 行为；这些文件每轮参与 bootstrap 注入（见 3.4），体积过大会提前占满上下文并触发 compaction，算法侧调优时可控制篇幅或依赖按需加载 $1$ $12$
`~/.openclaw/workspace/skills/<name>/SKILL.md`	技能定义；修改后可通过 skills watcher 或下一轮对话生效 $1$
`~/.openclaw/agents/<agent>/sessions/*.jsonl`	会话转录；用于连续性与记忆索引，敏感内容注意权限 $3$ $4$
`~/.openclaw/credentials/`	凭证（如 WhatsApp creds、allowFrom 等） $3$

使用建议 $3$ ：改「Agent 能看到什么、能做什么」时，优先看工作区内的 AGENTS.md/SOUL.md/TOOLS.md 与 skills/；改「谁可以连、用什么鉴权」看 openclaw.json 的 gateway.auth、channels.*.dmPolicy 等。

3.4 Agent 循环与上下文

据 $4$ Agent Loop 文档，单次 Agent 运行是「intake → 上下文组装 → 模型推理 → 工具执行 → 流式回复 → 持久化」的完整闭环；按会话串行执行，避免并发写会话状态。流程可概括为：
Agent 单轮循环
Intake 入站
上下文组装
模型推理
工具执行
流式回复
持久化

入口：CLI 的 agent 命令、Gateway RPC 的 agent 与 agent.wait $4$ 。
流程概要 ：agent RPC 校验参数、解析会话、持久化会话元数据后立即返回 { runId, acceptedAt }；实际运行由 runEmbeddedPiAgent（Pi agent 运行时）在每会话队列中执行，包含：解析模型与鉴权、加载 skills 快照、构建系统提示、执行工具、流式输出、compaction 与重试等 $4$ 。
系统提示 ：由 OpenClaw 基础提示、技能提示、bootstrap 上下文与每轮覆盖组成；模型限制与 compaction 预留 token 会被遵守 $4$ 。详见 System prompt。

面向算法/模型工程师的要点（据 $12$ System prompt 与 $4$ 整理，便于迁移到自研推理与上下文管线）：

系统提示结构 ：OpenClaw 每轮为 Agent 组装固定区块 的系统提示，包含但不限于：Reasoning 可见性、Runtime（host/OS/node/model/repo、thinking level）、Heartbeats、Reply Tags、Current Date & Time、Sandbox 说明（若开启）、Workspace Files 注入说明、Documentation 路径、Workspace 目录、OpenClaw 自更新说明、Skills 列表（按需加载 SKILL.md）、Safety 简短提醒、Tooling 列表与简短描述。子 Agent 可使用 promptMode=minimal（省略 Skills/Memory/Heartbeats 等）或 none（仅基础身份），以节省上下文 $4$ $12$ 。
Bootstrap 注入与 token 预算 ：每轮会将工作区内多份文件拼接后注入 到上下文，例如 MEMORY.md、BOOTSTRAP.md、HEARTBEAT.md、USER.md、IDENTITY.md、TOOLS.md、SOUL.md、AGENTS.md 等；单文件最大字符数由 agents.defaults.bootstrapMaxChars（默认 20000）控制，所有 bootstrap 总字符数由 agents.defaults.bootstrapTotalMaxChars（默认 150000）封顶，超出部分会截断并打标记。MEMORY.md 若过大 会直接占用大量 token，导致更早触发 compaction；memory/*.md 按日文件不自动注入，而是通过 memory_search / memory_get 按需读取，不占固定上下文 $4$ 。对自研 Agent 的借鉴：将「固定注入」与「按需检索」分离，并给 bootstrap 设上限，可避免长上下文被静态内容占满。
Context 调试 ：会话中可使用 /context list 或 /context detail 查看各注入文件的实际占用（原始 vs 注入后、截断情况、工具 schema 开销），便于做上下文与 token 预算调优 $4$ 。
Compaction 与模型行为 ：上下文接近或超过模型 context window 时触发自动 compaction，旧对话被摘要后再重试当轮请求；因此模型看到的是一段「摘要 + 近期完整消息」，若摘要丢失关键细节，后续推理可能偏离。算法侧可关注：摘要策略（谁生成、保留什么）、重试次数、以及是否在 compaction 前通过钩子将关键信息写回 MEMORY 或长期记忆 $4$ $8$ 。
Safety 与硬约束 ：系统提示中的 Safety 是建议性 （advisory），不强制模型行为；真正限制行为的是工具策略（allow/deny）、执行审批、沙箱与通道 allowlist。若你做对齐或安全研究，应把「提示内 guardrail」与「工具/沙箱/身份」分开设计 $3$ $4$ 。

面向算法/架构师的要点（便于迁移到自研 Agent 平台与系统设计）：

Agent 循环与队列模型 ：agent RPC 先返回 { runId, acceptedAt }，实际运行在每会话串行队列中执行，避免并发写同一会话；compaction 与重试在循环内显式建模。架构师设计多会话、多租户 Agent 时可借鉴「请求接受与执行解耦 + 按会话队列」的模式，便于背压、取消与可观测性 $4$ 。
控制面与执行分离：Gateway 负责协议、鉴权、通道与事件；Pi Agent 负责推理与工具调用；工具在 Gateway 侧调度（如 exec 的 host=sandbox/gateway/node）。自研时可将「谁握有连接与状态」与「谁执行推理与工具」分开，便于水平扩展或替换执行后端 $2$ $4$ 。
钩子与可扩展性 ：before_compaction、after_compaction、before_prompt_build、agent:bootstrap 等钩子把「上下文组装」「压缩」「bootstrap 注入」变成可插接点；记忆、摘要、自定义策略均可挂接。设计平台时预留类似生命周期钩子，便于在不改核心循环的前提下扩展行为 $4$ $12$ 。
协议与类型化 API ：WebSocket 上请求/响应/事件统一、首帧 connect、幂等键与去重，便于多端（CLI、Web、移动端、Nodes）共用同一协议；TypeBox/schema 驱动可生成多语言类型与校验。架构师在选型「自研 vs MCP/其他标准」时可对照协议复杂度与生态 $2$ $10$ 。
上下文管线与 compaction 的架构意义：从「入站 → 组装上下文 → 推理 → 工具 → 流式 → 持久化 → 必要时压缩重试」形成闭环；长对话的稳定性依赖「上下文预算 + 压缩策略 + 可选记忆写回」的配合。设计长对话或多轮 Agent 系统时，宜把「上下文边界、压缩触发、重试与记忆」作为一等公民建模 $4$ $8$ 。

3.5 记忆与持久化

会话与持久化 ：会话转录存储在磁盘 ~/.openclaw/agents/<agent>/sessions/*.jsonl，用于会话连续性与（可选）会话记忆索引 $3$ $4$ 。工具结果在写入转录前可经插件钩子处理 $4$ 。
记忆插件与 CLI ：官方提供与记忆相关的能力，通过 openclaw memory 命令管理（如 openclaw memory status、openclaw memory index、openclaw memory search），由当前启用的 memory 插件（如默认的 memory-core）提供；支持按 agent 作用域、向量与嵌入可用性检查及重新索引 $9$ 。记忆与对话数据在每次 Agent 循环结束后写入工作区 $9$ 。
相似技术点：其它方案中的长期记忆与检索与之类似------如 Mem0、LangChain 的 memory 层、各类向量库 + 检索（如 Chroma、Pinecone）用于语义回忆；OpenClaw 的 memory 插件可提供向量索引与会话作用域 $8$ $9$ 。
平替方案 ：官方 memory 插件（默认）vs 社区讨论的 MEMORY.md + 按日流水（如 memory/YYYY-MM-DD.md）vs 向量 + BM25 混合检索 （语义 + 关键词）vs 外部记忆服务；当前实现以官方 Memory 与 openclaw memory CLI 为准，社区 $8$ 与官方 $9$ 表述不一致时以文档为准。
算法侧可关注：检索触发时机（每轮前 vs 按需）、召回条数与 token 预算、以及 embedding 与向量索引的更新策略，便于在自研 RAG/记忆管线中做对比 $9$ 。
架构师可关注 ：记忆以插件形式存在（如默认 memory-core），与会话转录（sessions/*.jsonl）存储分离------转录保证连续性，记忆插件负责索引与检索；可替换为自建 MEMORY.md + 混合检索或外部记忆服务。设计 Agent 平台时可将「会话存储」与「长期记忆/检索」拆成可插拔层，便于换实现或做多租户隔离 $8$ $9$ 。
社区与历史方案：早期/社区讨论中常出现 MEMORY.md、混合检索、compaction 前将重要信息写回记忆等设计 $8$ ；实现上可依赖钩子或自定义插件，以仓库与官方文档为准。
第三方博客中的记忆描述：据 $11$ getopenclaw.ai 等第三方博客，有文章将记忆分为会话存储、实体抽取、向量嵌入与上下文注入等层，并与 ChatGPT Memory 对比（如事实条数、本地存储与隐私）；此类表述为第三方解读，具体实现以官方 $9$ 与 memory 文档为准。

实战：记忆 CLI 用法 $9$ ：

openclaw memory status：查看当前启用的 memory 插件、按 agent 的作用域与向量/嵌入可用性。
openclaw memory index：触发（重新）索引，将持久化会话或工作区内容纳入记忆检索；索引后插件可能写入或更新 ~/.openclaw 下与 memory 相关的数据（具体路径依插件而定，见官方 Memory 文档）。
openclaw memory search "关键词"：在已索引记忆中检索，用于验证索引是否生效或调试召回。

若官方有示例输出，可在文档中对照字段含义；索引为异步或按需时，可能需等待一次 Agent 轮次或手动执行 index 后再 search。

Demo：记忆 CLI 连续操作 $9$ （按顺序执行即可验证）：

bash 复制代码

# 查看当前记忆插件与作用域
openclaw memory status

# 触发索引（将已有会话/工作区纳入检索）
openclaw memory index

# 在已索引记忆中搜索（替换为你想查的关键词）
openclaw memory search "项目名称"

记忆与压缩的流程关系可简化为（据 $4$ $9$ 与文档整理）：
Agent 轮次结束
写入会话转录
记忆插件索引/更新
下次请求时检索
组装上下文
模型推理
Compaction 若超长
重试或继续

3.6 Compaction（压缩）

据 Compaction 与 $4$ ：

实际行为 ：当会话接近或超出模型上下文上限时，OpenClaw 将较早的对话压缩成一条摘要 并保留最近消息完整；摘要写入会话的 JSONL 历史，后续请求使用「摘要 + 近期消息」。自动 compaction 会触发流事件（如 🧹 Compaction、🧹 Auto-compaction complete），并可能重试原请求 以使用压缩后的上下文。配置通过 agents.defaults.compaction 在 openclaw.json 中设置（mode、target tokens 等）；也可用 /compact 手动触发。
相似技术点：与 LangChain 等框架中的 context 压缩、滑动窗口或「保留最近 N + 摘要」策略类似；目的都是控制上下文长度同时保留关键信息 $4$ 。
平替方案 ：若不想用内置 compaction，可考虑滑动窗口（只保留最近 N 条）、外部 summarizer 在写入前先摘要、或更频繁地 /new//reset 开新会话；长对话多步任务时，压缩后模型可能遗忘中间细节，需在提示或记忆侧补足 $4$ $8$ 。
算法工程师可调 ：agents.defaults.compaction 中的 target tokens、mode；若自研摘要逻辑，可对接 before_compaction / after_compaction 钩子（见 4.3）替换或增强摘要策略 $4$ 。

3.7 控制与隔离思路小结

权限：通过 tools.allow / tools.deny、工具 profile（如 messaging）、以及 gateway/cron/sessions_* 等高风险工具的默认拒绝，限制不同会话/代理的能力 $3$ 。
沙箱：非主会话使用每会话 Docker，工作区与执行环境隔离；Exec 的 host=sandbox 需正确开启沙箱才生效，否则会回退到主机 $3$ $6$ 。
DM 与配对：新设备与不可信联系人通过配对或 allowlist 控制，避免未授权访问 $3$ 。

对算法/架构师 ：权限与隔离的设计是分层、配置化 的------身份（谁可连、谁可 DM）→ 范围（工具 allow/deny、沙箱 mode、工具 profile）→ 模型（提示内 Safety 仅建议）。架构师设计多租户或多场景 Agent 时，可借鉴「身份 → 范围 → 模型」的次序，以及工具 profile（如 messaging）、deny 列表（gateway、cron、sessions_*）的默认收紧策略；控制面工具（gateway、cron）与数据面/执行面分离，便于做最小权限与审计边界 $3$ $6$ 。

实战：最小 Gateway 相关配置与工具权限示例 $3$

以下为加固基线 的简化示例（格式为 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$ 为官方文档；内容与官方不一致时以官方为准。

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

目录

1. 背景与定位

1.1 项目是什么

1.2 命名与由来

1.3 目标用户与典型用法

1.4 为什么叫「有手的 Claude」

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

2. 架构总览

2.1 总体模型：单 Gateway 控制面

2.2 组件与角色

2.3 连接与认证

2.4 远程访问

2.5 协议与事件类型摘要

3. 核心技术点

3.1 多通道收件箱

3.2 工具与执行能力

3.3 会话与工作区

3.4 Agent 循环与上下文

3.5 记忆与持久化

3.6 Compaction（压缩）

3.7 控制与隔离思路小结

4. 源码解读

4.1 仓库结构（基于 1）

4.2 Gateway 与协议

4.3 Agent 循环与 Pi 运行时

4.4 工具与沙箱

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

5. 场景推荐

5.1 适合的场景

5.2 不适合或需谨慎的场景

5.3 能力边界简述

6. 迁移与落地建议

6.1 从零接入（推荐路径）

6.1.1 部署与运行要点

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

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

7. 相关技术与项目对比

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

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

7.3 与闭源 Copilot / Assistant 的差异

8. 安全与权限

8.1 威胁模型（据 3）

8.2 加固建议摘要

8.3 控制面工具风险

9. 局限与延伸

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

9.2 延伸阅读与参考

9.3 术语速查

参考文献

4.1 仓库结构（基于 $1$ ）

8.1 威胁模型（据 $3$ ）