OpenClaw DeepWiki 通俗版

Overview

这章在讲什么

这章是 OpenClaw 项目的整体技术概览，帮你快速理解它的架构、核心模块和工作方式。适合刚接手或想参与开发的工程师，先搞清楚"这系统到底是干啥的"、"代码怎么组织的"。

核心要点

OpenClaw 是一个自托管的 AI 代理网关，能把 WhatsApp、Telegram、Discord 等聊天平台连到 AI 编程代理上。
整个系统靠一个叫 gateway 的主进程运行，管理会话、路由消息、执行工具。
配置文件是 ~/.openclaw/openclaw.json，用 JSON5 格式，支持注释和引用，结构清晰。
支持插件扩展（比如加新聊天平台），也支持多 AI 模型、沙箱执行、热重载配置。
移动端（iOS/Android）和桌面端（macOS）都有原生客户端，通过 WebSocket 连接主服务。

你可以怎么理解

想象你有个"AI 助手中枢"，它同时挂着微信、Telegram、Slack 几个账号。有人发消息过来，它自动判断该用哪个 AI 模型处理，调用代码生成、浏览器操作等工具，再把结果发回去------OpenClaw 就是这个中枢。

它的配置像搭积木：agents 定义用哪个 AI 代理，channels 配连哪些聊天软件，models 指定用 OpenAI 还是 Anthropic，tools 控制能执行什么操作。改完配置后，可以用 openclaw gateway restart 重启服务，或者设 gateway.reload.mode=hot 实现热更新。

开发时用 pnpm gateway:watch 启动，代码改了自动重载。移动端用 pnpm ios:build 或 pnpm android:assemble 打包。CLI 命令像 openclaw agent list、openclaw channels status，方便日常操作。

简单说：一个配置文件 + 一个主进程 + 多端接入 + 插件扩展 = OpenClaw 的核心工作模式。

Getting Started

这章在讲什么

这章是 OpenClaw 的入门指南，教你从零开始安装、配置并验证一个能跑起来的 Gateway。核心流程包括：环境准备、安装命令、使用 onboard 向导完成初始化设置、用 doctor 命令检查和修复问题，最后通过几个命令确认系统正常运行。

核心要点

必须用 Node.js 22+，推荐 pnpm 安装，Windows 用户建议用 WSL2。
推荐使用安装脚本 curl -fsSL https://openclaw.ai/install.sh | bash，它会自动处理 Node、安装和初始化。
openclaw onboard 是交互式配置向导，帮你设置模型认证、网络端口、通信渠道等。
openclaw doctor 是健康检查工具，能自动发现并修复配置、权限、服务等问题。
验证安装是否成功，依次运行 gateway status、status、doctor 和 dashboard。

你可以怎么理解

你可以把整个过程想象成"装一台智能机器人主机"：

先看硬件要求：Node.js 就是运行环境，像操作系统一样必须达标（Node 22+，512MB+ 内存）。
一键安装：用官方脚本安装最省心，它会自动装依赖、配置环境变量，甚至直接启动设置向导。
向导配置（onboard） ：运行 openclaw onboard --install-daemon，它会一步步问你：
- 用哪个大模型（OpenAI、Anthropic 等）？
- API key 怎么填？
- 服务跑在本地还是远程？
- 要接 Telegram 或 WhatsApp 吗？它还会自动把服务注册成系统后台进程（macOS 的 launchd 或 Linux 的 systemd），开机自启。
健康检查（doctor） ：装完或升级后，跑 openclaw doctor，它就像个医生，检查配置对不对、token 有没有、服务是否正常，还能自动修复很多问题。
验证运行 ：最后用 openclaw status 和 openclaw dashboard 打开网页控制台，看到界面就说明成功了。

配置文件默认在 ~/.openclaw/openclaw.json，所有设置最终都写在这里。如果出问题，先 openclaw doctor，再看日志 openclaw logs --follow。

Core Concepts

这章在讲什么

这章讲的是 OpenClaw 的核心架构设计，帮你理解它怎么把 AI 代理、聊天渠道、设备节点这些模块串在一起工作。适合想搞清楚系统"怎么跑起来"的工程师。

核心要点

Gateway 是中枢，所有消息都经过它路由，默认跑在 18789 端口。
Agents 是独立的 AI 实例，每个有自己的 workspace 和模型配置。
Channels 接入 WhatsApp、Telegram 等平台，支持细粒度访问控制。
Sessions 管理对话上下文，支持按用户、群组隔离。
Nodes 是配对的手机/电脑，能让 Agent 调用摄像头、通知等本地能力。
Skills 是插件式功能，通过 SKILL.md 注入提示词或工具。
Bindings 定义路由规则，比如"某人的 WhatsApp 消息走 work 代理"。
配置文件是 ~/.openclaw/openclaw.json（支持注释的 JSON5），支持热重载。

你可以怎么理解

可以把 OpenClaw 想成一个"AI 消息调度中心"：

外部消息（比如 Telegram）进来 → Gateway 根据 bindings 决定交给哪个 Agent → Agent 在自己的 workspace 里运行，调用 tools 或 skills → 回复通过 Gateway 发回去。

Session 用 agent:main:whatsapp:dm:xxx 这种结构区分上下文，推荐用 per-channel-peer 避免串对话。

Node 是你的手机或 Mac，配对后 Agent 就能发 camera.snap 拍照、system.notify 弹通知。

改配置时，gateway.reload.mode 控制是否重启------开发时用 hybrid 最省事。

Gateway

这章在讲什么

这章讲的是 OpenClaw 的核心组件------Gateway（网关）。你可以把它理解成整个系统的"大脑"和"通信中心"。它负责管理所有客户端（比如 CLI、控制台、手机 App）、消息渠道（Telegram、WhatsApp 等）和智能代理（Agents）之间的通信，统一处理配置、会话、认证和远程调用（RPC）。

核心要点

Gateway 是一个常驻后台的服务（macOS 用 launchd，Linux 用 systemd），通过 WebSocket（v3 协议）和 HTTP 对外提供接口。
它使用 openclaw.json 配置文件，支持热重载（部分配置改了不用重启）。
所有通信基于三种消息帧：request（请求）、response（响应）、event（事件推送）。
支持 token 或密码认证，并通过角色（operator、node、user）控制权限。
配置里敏感信息可以用 SecretRef 引用环境变量、文件等，避免明文。
会话（Session）通过 sessionKey 路由，支持按用户、渠道隔离。
提供 openclaw gateway 命令管理服务生命周期，doctor 命令诊断问题。

你可以怎么理解

想象 Gateway 就像一个"总机接线员"：

所有来电（客户端连接）都先打给它；
它根据你的权限（角色）决定你能做什么；
你发个 request 想发消息，它转给对应的 agent 处理，再把结果 response 回你；
如果有新消息进来，它主动用 event 推给你；
配置改了，它能自动 reload，除非改了端口这类"硬配置"才需要重启；
你用 openclaw gateway start/stop/status 控制它，就像管理一个系统服务。

简单说：所有事都得经过 Gateway，它是 OpenClaw 的中枢神经。

WebSocket Protocol & RPC

这章在讲什么

这章讲的是 OpenClaw 网关（Gateway）用的 WebSocket 通信协议和远程过程调用（RPC）机制。它定义了客户端和服务器之间怎么建立连接、发请求、收响应、接收服务端推送事件，以及权限控制、错误处理等核心逻辑。简单说，就是"两个程序怎么安全、可靠地聊天"。

核心要点

通信走 ws://127.0.0.1:18789，消息全是 JSON 文本帧。
连接前要完成握手：服务器发 connect.challenge 带 nonce，客户端回 connect 请求，带上协议版本、身份信息和认证数据。
每个请求带唯一 id，服务器回相同 id 的响应，支持成功/失败两种结果。
所有 RPC 方法都要鉴权，分 operator（操作员）和 node（节点）两种角色，operator 还要按 scopes 控制权限（比如 operator.read 只能读）。
服务端会主动推事件（如 tick 心跳、agent 事件），客户端靠 seq 序号检测丢包。
写操作（如改配置）有频率限制：3次/60秒。
协议版本不匹配、认证失败等会触发特定 WebSocket 关闭码（如 1002 协议错误，4000 心跳超时）。

你可以怎么理解

想象你写了个客户端，要连上 OpenClaw 网关。第一步，连上 WebSocket 后，服务器立刻甩给你一个 connect.challenge 消息，里面有个一次性 nonce。你得把这个 nonce 塞进你的 connect 请求里，同时填上 minProtocol/maxProtocol 版本号、你是谁（client.id）、角色（role: "operator"）、想要什么权限（scopes）等。

连上了，你就能调 RPC 方法了，比如 sessions.list 查会话。发的是 RequestFrame，收的是 ResponseFrame，靠 id 对账。如果没权限，直接返回 INVALID_REQUEST。

服务端还会主动发事件，比如每 30 秒一个 tick 心跳。客户端得盯着，太久没收到就自己断开（close code 4000），防假死。

所有接口和事件在代码里用 TypeBox 定义，还会自动生成 Swift 模型（GatewayModels.swift），保证前后端类型一致。

总之，这套协议就像一套"对话规则"：先打招呼，再按格式说话，听对方广播，谁也不能乱来。

Authentication & Device Pairing

这章在讲什么

这章讲的是 OpenClaw 网关（Gateway）怎么验证客户端身份、如何安全地配对新设备，以及权限控制机制。核心是：谁可以连上来？有什么权限？怎么防止被冒充？

核心要点

网关支持多种认证方式：token、password、通过反向代理传身份（如 Tailscale）、甚至无认证（仅限本地开发）。
每个设备有自己唯一的 Ed25519 密钥对，用公钥做设备 ID，签名防伪造。
首次连接要走"握手流程"：服务器发 nonce，客户端签名证明身份，并完成配对。
配对分"静默自动"和"手动审批"：本地 CLI 或 Control UI 可自动通过；升级权限或跨设备需人工确认。
权限靠 role + scopes 控制：operator 是管理员，node 是能力提供者（如手机）；scopes 细粒度控制能做什么。
iOS/macOS 客户端会开两个连接：一个当 node（提供摄像头等能力），一个当 operator（聊天、配置）。

你可以怎么理解

想象你要让手机连上家里的服务器。第一步，手机得证明"我是我"------它用自己的私钥签名一段数据（含时间戳、nonce），服务器用公钥验证。这就是设备身份。

接着是配对：第一次连，服务器说"不认识你，请审批"。如果你在本地连（比如电脑直连），系统自动批准；如果是远程，就得通过 Telegram 输入 /pair approve 手动点同意。

一旦配对成功，服务器会发一个设备令牌（deviceToken），下次连接可以直接用这个 token，不用再走完整流程。

权限方面，比如你的手机想发消息、读配置，就得申请 operator.write 和 operator.read 这些 scopes，而且这些必须在签名时就定好，不能临时加，防止提权。

Tailscale 用户更方便：登录了 Tailscale，网关直接信任你，跳过配对。

整个流程像"带钥匙进门 + 登记备案 + 领门禁卡"，既安全又灵活。

Configuration System

这章在讲什么

这章讲的是 OpenClaw 网关的配置系统，它负责加载、验证、热更新和管理整个系统的配置。配置文件是 ~/.openclaw/openclaw.json（用 JSON5 格式），系统会自动处理密钥、文件包含、旧格式迁移，并支持运行时动态更新。

核心要点

配置通过多阶段流水线加载：解析 → 合并 $include → 迁移旧字段 → Zod 校验 → 解密 SecretRef
支持热重载（hot/hybrid 模式），部分修改无需重启
用 { $ref: "env:KEY" } 引用环境变量或文件，避免明文写密钥
可用 $include 把大配置拆成多个文件
支持通过 WebSocket RPC 动态更新配置（如 config.patch）
自动迁移老版本配置字段（比如 dm.policy → dmPolicy）

你可以怎么理解

你可以把配置系统当成一个"智能配置中心"。它不只是读个文件那么简单，而是：

安全：敏感字段用 SecretRef 指向环境变量或文件，不会泄露。
灵活：大配置可以用 $include 拆分，比如把 agents 单独放一个文件。
可靠：改配置后，系统自动判断能不能热更新------比如改了 gateway.port 得重启，但改 agents 就能立刻生效。
可维护 ：如果用了旧字段，启动时会自动迁移；出错了还能用 openclaw doctor --fix 修复。
可编程 ：前端或脚本可以通过 config.patch API 动态改配置，就像调接口一样。

简单说：写配置更安全、更模块化，改配置不用总重启，还能用工具自动管理。

Configuration Reference

这章在讲什么

这章是 OpenClaw 的配置文件 ~/.openclaw/openclaw.json5 的完整说明书。它告诉你这个配置文件长什么样、有哪些字段、怎么用，尤其是 gateway、channels、agents、tools 这些核心模块的设置。你可以把它当成一本字典，需要改什么功能就来查对应的 key。

核心要点

配置文件用的是 JSON5 格式，支持注释和尾随逗号，比纯 JSON 更友好。
所有字段都是可选的，不写的会用默认值。
配置加载流程：读文件 → 解析 JSON5 → 用 Zod 校验 → 解密密钥（比如 ${SECRET}）→ 生效。
核心配置项：
- gateway：控制 API 端口、认证（token/密码）、TLS、远程连接等。
- channels：配置 Telegram、Discord、Slack 等聊天渠道，支持多账号和精细权限控制。
- agents：定义 AI 代理的行为，比如用什么模型、工作区路径、工具权限。
- tools：全局开关，控制 web 搜索、代码执行、媒体理解等功能是否开启。

你可以怎么理解

想象你在搭一个自动化机器人系统。gateway 就是它的"总控室"，决定它开在哪个端口、要不要密码、能不能被外网访问。channels 是它的"社交账号"，比如一个 Telegram 机器人和一个 Discord 机器人，你可以分别设置它们的 token、谁可以私聊它、进群要 @ 吗。agents 是它的"员工"，比如一个叫 research 的员工专门负责搜索，用 claude-sonnet 模型，工作区在 ~/research。tools 就是"工具箱"，你在这里决定员工们能不能上网搜资料、能不能运行代码。整个配置就是一份详细的"岗位说明书"，告诉系统每个部分该怎么干活。

Session Management

这章在讲什么

这章讲的是 OpenClaw 里"会话"（Session）是怎么管理的。简单说，就是每次你和机器人聊天，系统怎么记住你是谁、聊过什么、状态如何，同时保证多人并发时不会乱套。

核心要点

每个会话由一个 Session Key 唯一标识，格式是 provider:account:chat:dmScope，比如 telegram:bot1:user123:dm。
会话数据存在两个地方：sessions.json 存元信息（SessionEntry），聊天记录存为 session-*.jsonl 文件。
用 文件锁 （.lock 文件）防止多个请求同时写同一个会话，避免数据错乱。
聊天太长会自动 压缩历史（compaction），用 AI 总结旧消息，腾出上下文空间。
支持通过 RPC 调用管理会话：查看、重置、删除、手动压缩等。

你可以怎么理解

可以把 Session 想成一个聊天的"档案袋"。每个用户、每个群聊都有自己的袋子（Session Key 区分），里面装着聊天记录（JSONL 文件）和档案卡（SessionEntry）。每次机器人回复前，先拿锁（acquireSessionWriteLock），避免两人同时改一个文件。

如果聊得太长，系统会自动把前面的内容总结成一段话，保持文件不会无限膨胀。

你还能通过 API 查看会话列表（sessions.list）、预览最近消息（sessions.preview），甚至重置对话（sessions.reset）------就像重启一次新对话，但保留原来的"身份"。

整个机制既保证了数据安全，又支持高并发和长期记忆，是 OpenClaw 聊天稳定的核心基础。

Cron Service

这章在讲什么

这章讲的是 OpenClaw Gateway 内置的一个定时任务系统（Cron Service），它能按计划自动执行一些操作，比如定时发消息、触发 Agent 任务等。你可以把它理解成系统里的"闹钟服务"。

核心要点

支持一次性（at）和周期性（every、cron 表达式）任务。
任务可以注入到主会话（main）或独立运行（isolated）。
执行结果可选记录日志、发到消息通道（如 Telegram）、或调用 Webhook。
有错误重试退避机制，避免频繁失败打爆服务。
所有操作都通过 cron.* 的 WebSocket RPC 接口暴露，方便外部控制。

你可以怎么理解

想象你在写一个机器人，想让它每天早上 8 点自动发一句"早安"。这个功能就是靠 Cron Service 实现的。

你定义一个 CronJob，设置 schedule 为 cron 表达式 "0 0 8 * * *"，payload 是要发送的内容，sessionTarget: "main" 表示直接塞进主流程处理。如果想让它独立运行（比如跑个完整推理），就设成 "isolated"。

任务执行后，结果会写进 ~/.openclaw/cron/runs/<jobId>.jsonl 的日志文件。你还能配置 delivery 把结果发到 Telegram 或打个 Webhook。

系统很稳：即使某个任务卡住，其他定时检查最多等 60 秒也会触发；失败了会指数退避（30秒、1分钟、5分钟...）；并发数也能限制，避免资源耗尽。

你可以用 cron.add、cron.list 等 RPC 命令动态管理这些任务，就像操作一个轻量级的定时任务调度器。

Agents

这章在讲什么

这章讲的是 OpenClaw 里的 Agent（智能体） 是什么，它是怎么被配置和运行的。简单说，Agent 就是一个有独立身份和能力的 AI 助手实例，能处理消息、调工具、读写文件，每个都有自己的工作空间和模型配置。

核心要点

每个 Agent 有唯一 ID（在 openclaw.json 的 agents 下定义），"default" 是默认兜底。
Agent 不等于会话（session）：一个 Agent 可以服务多个会话（比如不同 Telegram 聊天），会话之间完全隔离。
每个会话有自己的：
- 历史记录文件（.jsonl 格式）
- 工作目录（workspace）
- 执行队列（避免并发混乱）
主要运行引擎是 embedded runner，它一步步组装系统提示、加载工具、调用模型，并处理上下文溢出时的自动压缩（compaction）。

你可以怎么理解

你可以把 Agent 想成一个"AI员工"，它有自己的工位（workspace）、工牌（API key）、工具包（tools），还有一本工作日志（session transcript）。每次有人发消息，系统就给这个"员工"派个活儿。

关键流程是这样的：

根据会话 key 确定用哪个 Agent（resolveSessionAgentIds）
锁定会话文件，防止并发写冲突
拼装系统提示（buildAgentSystemPrompt），包括注入 AGENTS.md、MEMORY.md 等上下文文件
加载工具集（如 bash、文件操作），按策略过滤
调用模型，流式接收结果
如果上下文太长（context overflow），自动触发 compactEmbeddedPiSessionDirect 压缩历史，再重试

特殊场景：

子 Agent（subagent）用 promptMode: "minimal"，少一堆功能，更轻量
Docker 沙箱模式下，host 和 container 路径分开，安全隔离

整个流程像一条流水线，从 runReplyAgent 开始，层层调用，直到 SDK 实际和模型交互。

Agent Execution Pipeline

这章在讲什么

这章讲的是一个用户消息从进入系统，到 AI 模型生成回复，再到最终回复返回给用户的完整流程。重点是背后这一连串函数调用、错误重试、权限切换、上下文压缩等机制，确保每次对话都能稳定执行。

核心要点

整个流程分四层函数：runReplyAgent → runAgentTurnWithFallback → runEmbeddedPiAgent → runEmbeddedAttempt，最后通过 subscribeEmbeddedPiSession 流式接收模型输出。
每层负责不同任务：排队控制、失败重试、模型/权限选择、执行环境搭建、流式传输等。
关键机制包括：
- 队列控制：防止同一会话并发冲突（session lane）和全局并发过多（global lane）。
- 失败重试：遇到上下文溢出、限流、认证失败时自动重试，比如压缩历史或换 API 密钥。
- Auth Profile Failover：一个密钥不行就换下一个，支持自动降级和冷却机制。
- 上下文压缩（Compaction）：当对话太长导致 context overflow，会启动专用流程压缩历史。
- 流式输出 ：边生成边返回，支持 <thinking> 等标签过滤，避免中间思考暴露给用户。
- Typing 指示器 ：根据 typingMode 控制"正在输入..."提示的显示时机。

你可以怎么理解

可以把整个流程想象成一个快递处理中心：

第一站 runReplyAgent：检查包裹（消息）是否要丢弃、排队，或者立刻处理；还会贴上"正在处理"标签（typing indicator）。
第二站 runAgentTurnWithFallback：如果送货失败（比如地址太远=上下文超限），就尝试压缩包裹再送，或者换条路（重试/降级）。
第三站 runEmbeddedPiAgent：决定用哪家快递公司（model），哪个司机（auth profile），并确保同一收件人不同时发多个快递（lane 串行）。
第四站 runEmbeddedAttempt：真正打包发货前的准备，比如整理工具、读取客户档案、构建提示词。
最后 subscribeEmbeddedPiSession ：边打包边直播进度，把内容分块发出去，过滤掉内部备注（如 <thinking>），只让用户看到最终回复。

整个过程高度容错，哪怕 API 限流、密钥失效、上下文爆炸，系统都会自动兜底，尽量不让用户感知到失败。

System Prompt & Context

这章在讲什么

这章讲的是 OpenClaw 如何为每个 agent 构造 system prompt------也就是模型运行时看到的"系统指令"。这个 prompt 不是固定的，而是每次动态拼出来的，包含了工具列表、安全规则、工作区信息、启动文件内容等，并且会根据场景（比如主 agent 或子 agent）调整详细程度。

核心要点

system prompt 由 buildAgentSystemPrompt() 函数动态生成，不是硬编码或直接用默认模板。
内容包括：工具说明、安全守则、运行时信息（model、host 等）、注入的 bootstrap 文件（如 SOUL.md、AGENTS.md）。
支持三种模式：full（完整）、minimal（子 agent 用，精简）、none（几乎为空）。
bootstrap 文件会被自动读取并插入 prompt，但有单文件和总长度限制（默认 2万/15万字符）。
时间信息只放时区，不放具体时间，是为了保持 prompt 稳定，利于缓存。

你可以怎么理解

你可以把 system prompt 想成 agent 的"开机 BIOS"------它一启动就看到这段话，知道"我是谁、能干什么、有哪些规则"。OpenClaw 完全掌控这个 prompt，不会依赖外部默认设置。

拼接过程像流水线：先收集各种信息块（工具、内存、文档等），再根据 promptMode 决定保留哪些（比如子 agent 用 minimal，就不需要消息格式、心跳这些）；最后把 bootstrap 文件（比如 SOUL.md 定义的人设）也塞进去，形成最终 prompt。

特别注意：

SOUL.md 被识别后，会提示 agent "你要模仿这个 persona"。
工具列表是按优先级排序的（比如 read、write 在前），并且会根据是否在 sandbox 中调整描述（比如禁用 ACP 相关功能）。
实际时间不能直接写进 prompt（会破坏缓存），所以提示 agent 用 session_status 工具去查。

整个机制很灵活，通过配置参数（如 toolNames、contextFiles、promptMode）可以精细控制每个 agent 的上下文环境。

Model Configuration & Authentication

这章在讲什么

这章讲的是 OpenClaw 是怎么管理 AI 模型的配置和认证的，比如你怎么告诉它用哪个模型（比如 Claude、GPT）、怎么存 API Key 或 OAuth 凭证，以及运行时怎么选模型、失败了怎么切换备用方案。

核心要点

凭证存在 auth-profiles.json 里，支持 api_key、oauth、token 三种类型。
可以通过环境变量或直接写在配置里存密钥，推荐用 --secret-input-mode ref 存引用。
支持自动发现 Ollama、vLLM 这类本地模型服务，只要它们在运行就能扫出来。
模型配置分"显式"（写在 openclaw.json）和"隐式"（有密钥就自动注册）。
能设置主模型和 fallback 模型，出问题自动降级；还支持别名（比如 /model sonnet）和白名单控制。

你可以怎么理解

你可以把 OpenClaw 的模型系统想象成一个"多账号多平台"的打车 App。你存了好几个平台的账号（Anthropic、OpenAI 等），每个账号有不同凭证（API Key 或登录态）。系统会优先用你设的"主司机"（primary model），如果他接不了单（401/限流），就自动换下一个（fallback）。

凭证管理很灵活：你可以直接贴 API Key，也可以用 OAuth 登录（比如 GitHub Copilot），甚至让系统自动从环境变量里读。像 Ollama 这种本地服务，只要开着，OpenClaw 就能自动发现可用模型。

命令行 openclaw models 是你的遥控器：查状态、切模型、设别名、管 fallback，都不用手改 JSON。整个流程既适合手动配置，也支持自动化部署。

Tools

这章在讲什么

这章讲的是 OpenClaw 里"工具系统"的完整流程：每次 AI 代理（agent）要执行动作前，怎么动态组装它能用的工具列表，怎么通过多层策略过滤、保护文件系统，以及最后怎么包装和发送给模型。整个过程像是一个"工具流水线"。

核心要点

工具组装入口是 createOpenClawCodingTools，它会整合基础工具和 OpenClaw 自研工具。
工具经过策略管道（policy pipeline）层层过滤，比如按 profile、agent、sandbox 等维度控制权限，deny 优先于 allow。
文件操作（read/write/edit）会被加上路径守卫，确保不越界访问 workspaceRoot。
exec 和 process 工具支持后台执行和中断信号，apply_patch 只在 OpenAI 类模型中启用。
所有工具最终会做 schema 标准化（适配 Gemini/OpenAI 差异），并加上调用前钩子（如循环检测）和中断支持。

你可以怎么理解

想象你在给一个程序员 AI 配"工具箱"。每次它要干活前，系统都会：

拼装工具包 ：从基础工具（比如读写文件）和 OpenClaw 特有工具（比如 web_search、sessions_spawn）里凑出一份清单。
层层安检 ：按配置走策略流水线------先看 profile（比如 coding profile 包含 fs 和 runtime 工具），再看 agent、provider、sandbox 限制，最后连"只有主人才能用的工具"也会被单独过滤。
加安全锁 ：如果启用了 workspaceOnly，所有文件操作都会被包装，防止跳出项目目录。
适配模型 ：对 Gemini 去掉 minLength 这类不兼容字段，OpenAI 才能用 apply_patch。
加监控和中断 ：每个工具调用前会检查是否陷入循环（比如反复执行同一命令），并支持通过 AbortSignal 中断。

最终这个"工具箱"被塞进 system prompt，交给模型决定怎么用。整个过程高度可配，安全优先。

Exec Tool & Background Processes

这章在讲什么

这章讲的是 OpenClaw 里怎么执行命令和管理后台任务。简单说，exec 用来跑 shell 命令，process 用来管那些跑在后台的长期任务，比如构建、服务启动等。

核心要点

exec 工具执行命令，可以设置超时、是否后台运行、是否用 PTY（比如需要交互式输入时）。
如果命令运行太久（超过 yieldMs）或明确设了 background: true，它会返回一个 sessionId，表示任务已后台化。
process 工具通过 sessionId 来管理这些后台任务：轮询输出、发 stdin 输入、查状态、杀进程等。
所有后台任务存在内存里，按 scopeKey 隔离（通常是每个会话独立），避免互相看到。
任务结束后会保留一段时间（默认 30 分钟），之后自动清理，防止内存爆掉。
可配置 notifyOnExit，让系统在后台任务结束时主动通知 agent，不用你不停轮询。

你可以怎么理解

想象你在写一个自动化脚本，用 exec 跑 npm run build，这命令可能要几十秒。你不想卡住等着，就加个 "background": true，exec 立刻返回一个 sessionId，告诉你："我放后台了，拿好 ID，回头查。"

然后你用 process 工具，比如 action: "poll" 去查这个 sessionId 的输出，或者用 action: "write" 给它发输入（比如确认提示）。任务结束时，如果开了 notifyOnExit，系统会主动"推"消息给你，告诉你"建完了"。

整个机制就像一个轻量级的"进程管理器"：exec 负责起进程，process 负责管它，所有状态存在内存里，按会话隔离，安全又高效。配置项都在 tools.exec.* 下，比如 tools.exec.timeoutSec 控制超时时间，jobTtlMs 控制任务记录保留多久。

Memory Tools

这章在讲什么

这章讲的是 OpenClaw 里让 AI 代理"记住"信息的工具和机制，重点是两个核心功能：memory_search（语义搜索记忆文件）和 memory_get（读取指定记忆文件）。它覆盖了底层实现、配置方式和命令行操作，帮你搞清楚 AI 是怎么查找和使用历史记忆的。

核心要点

两个关键工具：memory_search 做语义搜索，memory_get 读具体文件。
支持两种后端：内置的 SQLite + 向量搜索（builtin），或调用外部 qmd 工具（qmd）。
搜索支持混合模式：结合关键词（BM25）和向量（embedding）结果，可配置权重。
配置灵活：可选 embedding 提供商（OpenAI、Gemini 等），自动 fallback，支持本地模型。
提供 CLI 命令：openclaw memory status、index、search，方便调试和管理。

你可以怎么理解

你可以把 memory_search 想成一个"智能搜索框"------你输入一个问题，它会在 MEMORY.md 和 memory/*.md 里找最相关的段落，返回带分数的片段。背后用的是 SQLite 数据库，把文件切块（chunk），用 embedding 做向量索引（sqlite-vec），同时建了 FTS5 关键词索引，支持 hybrid 搜索。

memory_get 就简单多了，像 cat 命令，按路径读文件，还能指定行号范围。

系统默认用内置后端（builtin），数据存在 ~/.openclaw/memory/<agentId>.sqlite。你也可以切到 qmd 后端，它会调外部 qmd 命令行工具，更适合复杂场景。

配置上，memorySearch.provider: "auto" 会自动选 embedding 服务（本地 > OpenAI > Gemini...）。搜索结果默认最多 6 条，分数低于 0.35 的过滤掉。

CLI 命令很实用：status 看状态，index 强制重建索引，search 直接查。所有操作都通过 getMemorySearchManager 统一入口，自动路由到对应后端。

总之，这套机制让 AI 能高效、安全地访问长期记忆，而且可扩展、可调试。

Subagents

这章在讲什么

这章讲的是 OpenClaw 里的"子代理"（subagents）机制------也就是主 Agent 在运行时临时起一个独立小任务，让它在隔离环境中干活，干完把结果送回来。适合做并行、后台任务，避免卡住主线。

核心要点

子代理通过 sessions_spawn 工具或 /subagents spawn 命令触发。
每个子代理有独立 session（agent:<id>:subagent:<uuid>），隔离上下文和可用工具。
支持设置超时、模型、嵌套深度限制（防无限递归）。
完成后通过"announce 流程"把结果发回原聊天上下文，支持重试。
子代理默认工具更少，防止乱 spawn 新子代理；深度由配置 maxSpawnDepth 控制。
可配置是否保留 session（mode: "session" + thread: true），目前仅 Discord 支持线程绑定。

你可以怎么理解

你可以把 subagent 想成"派出去的小分队"：主 Agent 接到任务后，说"这事儿我外包一下"，然后调用 sessions_spawn 起一个独立会话，让小分队去查资料、跑脚本。这个小分队有自己的上下文和权限（比如不能随便再派下级小分队），干完活自动汇报结果到原聊天窗口。

结果发送走的是 announce 流程，会优先发到线程/频道绑定的位置，如果发不出去会重试几次（最多3次，指数退避）。整个过程不阻塞主线，还能控制最多嵌套几层（比如最多 A 派 B，B 不能再派 C）。

配置都在 agents.defaults.subagents 下，比如默认超时、模型、最大深度。调用时传参可覆盖。简单说：异步、隔离、可控、可追溯。

Commands & Auto-Reply

这章在讲什么

这章讲的是 OpenClaw 里命令和自动回复系统的工作机制：怎么识别用户输入的 /status、/think high 这类指令，怎么处理它们，以及在群聊里什么时候该回复、什么时候该闭嘴。

简单说，就是"你发一条消息，系统怎么决定是当普通聊天走模型，还是当成命令直接处理"。

核心要点

命令分两种 ：纯命令（如 /status）走"快路径"，不进 AI 模型队列；带指令的普通消息（如"说点啥 /think high"）会提取指令后，剩余内容交给 AI。
所有命令定义在 commands-registry.data.ts，支持别名、参数、跨平台适配（比如 Discord 不能用 /tts，就改成 /voice）。
指令（directives）可以嵌在普通消息里，比如 /think high 控制思考等级，但只有授权用户才生效。
群聊中默认要 @ 机器人才回复（mention 模式），可用 /activation always 改成有消息就回。
/send on|off 可开关回复发送，用于调试或静音。

你可以怎么理解

想象你在群里发了条消息：

"嘿 /status，今天过得咋样？"

系统会先扫一遍有没有 / 或 ! 开头的内容。发现 /status，就把它拎出来处理------生成状态卡片回复你。剩下的"今天过得咋样"继续交给 AI 处理。

如果你是管理员，发个 /think high 单独一行，系统会记住你接下来的对话都用"高思考模式"；但如果不是你发的，这条就直接忽略。

命令能不能用，取决于配置和权限。比如 /bash 默认关着，得在 config 里手动打开。群聊里回不回复，看的是 activation 设置和有没有被 @。

整个流程像一个过滤器管道：消息进来 → 检查是不是命令 → 是就快处理，不是就提指令 → 最后决定走不走 AI。干净利落，不拖泥带水。

Channels

这章在讲什么

这章讲的是 OpenClaw 是怎么对接各种聊天平台（比如 Telegram、Discord、Slack 等）的。核心是"通道（Channels）"系统，它让机器人能收发消息、控制权限、处理会话，而且对不同平台做了统一抽象，方便扩展。

核心要点

每个平台（如 Telegram）都有一个独立的 monitor 进程，负责连接、收消息、发回复。
消息进来后会经过一套标准流程：去重 → 权限检查（DM/群组）→ 提取内容 → 派发给 Agent。
回复时支持打字中提示、分段发送、媒体上传，并自动清理"已收到"表情。
权限控制分两种：dmPolicy 控私聊，groupPolicy 控群聊，支持白名单和配对机制。
配置在 channels.<platform> 下，支持多账号、分账号配置，还能合并默认值。

你可以怎么理解

你可以把每个聊天平台当成一个"插件"，它们都遵循同一个模式：启动一个 monitor 长连接，收到原始消息后，先标准化成统一格式（envelope），然后走一套通用处理流水线。

比如你发一条 Telegram 消息，系统会：

判断是不是重复消息；
看你有没有权限（比如是否在白名单，或是否完成配对）；
如果是群聊，还会看你有没有 @ 机器人；
然后打包成一个标准消息，交给 Agent 处理；
Agent 回复时，系统会自动发"打字中"，分段发送长文本，最后删掉"已收到"表情。

会话靠 session key 区分，比如私聊是 agent:xxx:main，群聊是 agent:xxx:telegram:group:12345，这样同一个机器人在不同群聊能保持独立上下文。

配置上，你可以为不同账号设不同 token 和权限，比如一个 Telegram 账号只接受特定用户，另一个专门收告警。还支持 allowFrom: ["*"] 开放访问，或者用 pairing 模式让新用户先输验证码。

总之，这套设计让你能用一套逻辑对接多个平台，同时保持灵活性和安全性。

Channel Architecture & Plugin SDK

这章在讲什么

这章讲的是 OpenClaw 是怎么对接各种聊天平台（比如 Telegram、Discord）的。核心是一个叫 monitor 的长驻进程，负责连接平台、收消息、做权限检查，然后把消息统一格式后交给机器人处理。回复时再通过 monitor 发回去。插件开发者可以用 openclaw/plugin-sdk 这个包来写自己的频道插件，不用碰内部代码。

核心要点

所有频道都用 monitor 模式 ：长期运行，监听平台事件，调 dispatchInboundMessage 把消息推给 agent。
内建频道（如 Telegram）在 src/ 下，插件频道（如 Feishu）在 extensions/ 下，后者必须用 openclaw/plugin-sdk。
消息进来先过 preflight 检查：DM 策略、群组白名单、是否 @ 了机器人等。
ChannelPlugin 接口定义了插件能力，通过一堆 Adapter 实现，比如发消息、处理命令、群组管理等。
PluginRuntime 提供插件可用的运行时能力，比如发消息、读配置、操作会话数据。

你可以怎么理解

想象每个聊天平台都有一个"代理"（monitor），它一直连着平台服务器，收到消息后先看一眼"能不能处理"（access control），比如是不是白名单用户、有没有被 @。然后把消息标准化成统一格式（InboundContext），扔给机器人引擎处理。机器人回复时，monitor 负责把 ReplyPayload 拆成合适大小的文本块（chunkTextForOutbound），加上 typing 指示器（createTypingCallbacks），再发回去。插件开发者只需要实现 ChannelPlugin 里的各个 Adapter，比如用 ChannelMessagingAdapter 实现 sendMessage，用 ChannelCommandAdapter 注册 /help 这样的命令就行。配置用 Zod 校验，敏感字段自动脱敏。整个流程清晰，插件隔离，安全又灵活。

Telegram Integration

这章在讲什么

这章讲的是 OpenClaw 是怎么接入 Telegram 的------从机器人启动、消息怎么进来、权限怎么控制，到回复怎么发出去，整个流程是怎么设计的。适合想搞清楚 Telegram 模块工作原理的开发者。

核心要点

用 grammY 库做 Bot，通过 createTelegramBot 初始化。
消息进来会走一套处理流水线：去重 → 排序 → 构建上下文 → 权限检查 → 分发给 Agent。
支持 DM 和群组的精细权限控制（allowlist、pairing 验证、mention 触发等）。
回复支持流式输出（streaming），在 DM 用草稿更新，群组用编辑消息实现"打字效果"。
配置灵活，支持多账号、自定义命令、媒体处理、话题线程隔离等。

你可以怎么理解

你可以把 Telegram 集成想象成一个"消息流水线工厂"：

入口：Bot 启动后轮询 Telegram API，收到消息先去重、按聊天分队列排队（避免乱序）。
处理：消息被包装成 TelegramMessageContext，包含发件人、会话 ID、是否带附件、是否回复某条消息等信息。过程中会检查你有没有权限发消息（比如 DM 需要先配对）。
权限：DM 支持 pairing 模式，陌生人发消息会收到一个验证码，你用 CLI 输入 openclaw pairing approve telegram <CODE> 才能通过。群组则看 channels.telegram.groups 配置，支持按话题（topic）单独设权限或指定 agent。
执行：如果是 /help 这类命令，会走 native command 流程；普通消息则交给 runReplyAgent 处理。
发回复 ：回复通过 deliverReplies 发出去，文本太长会自动分段，支持 inline 按钮。流式输出时，DM 用 sendMessageDraft 更新草稿，群组先发一条"正在输入..."再不断编辑。
配置：关键配置如 botToken、dmPolicy、streaming 模式、customCommands 都在 TelegramAccountSchema 里定义，支持多账号管理。

简单说：收消息 → 过安检 → 拆包裹 → 交给 AI → 流式发回复，每一步都可配置。

Discord

这章在讲什么

这章讲的是 OpenClaw 如何集成 Discord，包括机器人启动流程、消息权限控制、线程绑定、执行审批、Slash 命令部署等核心机制。适合想搞懂 OpenClaw 在 Discord 里怎么跑的工程师。

核心要点

用 @buape/carbon 库通过 WebSocket 连接 Discord Gateway。
消息进来先过 preflightDiscordMessage 检查权限，支持 DM、频道、线程不同策略。
支持基于 guild/channel/user/role 的 allowlist 控制。
Slash 命令在启动时自动部署，最多 100 个，超了会自动裁剪。
可开启 exec approval 功能，通过按钮审批敏感操作。
线程绑定（thread bindings）让 agent 能在 thread 里持续交互。
输出支持流式发送（partial/block 模式），默认只发最终回复。

你可以怎么理解

你可以把 monitorDiscordProvider 当作 Discord 集成的"主入口"，它负责：

拿 token 启动 bot；
解析配置里的 guilds、channels，把 slug 转成 ID；
部署 Slash 命令（比如 /skill）；
注册各种监听器（消息、反应、上线等）；
启动线程绑定和 exec approval 系统。

权限控制是分层的：先看是不是 DM，是的话走 dmPolicy；不是就查 guild 和 channel 的 allowlist，还能配 requireMention 强制要 @ 机器人才响应。

session key 是隔离会话的关键，比如：

普通频道：agent:<id>:discord:channel:<channelId>
线程：用 threadId
Slash 命令：按用户隔离 agent:<id>:discord:slash:<userId>

配置里注意：ID 都得写成字符串，dangerouslyAllowNameMatching 开了才能用用户名匹配（不推荐）。Streaming 默认关，想实时出字就得开 partial。

Other Channels

这章在讲什么

这一章讲的是 OpenClaw 支持的除 Telegram 和 Discord 之外的其他消息渠道（如 Slack、Signal、WhatsApp 等）的配置和集成方式。它区分了"核心渠道"（内置）和"扩展渠道"（独立插件），并说明了它们的架构、配置字段和通用模式。

核心要点

核心渠道 ：Slack、Signal、iMessage 等直接内置在主项目中，配置在 src/config/，监控逻辑在对应 src/<channel>/ 目录。
扩展渠道 ：Matrix、Feishu、Mattermost 等是独立 npm 包，依赖 openclaw/plugin-sdk 实现统一接口。
所有渠道共享通用配置逻辑：dmPolicy 控制私聊权限，groupPolicy 控制群组访问，支持多账号、历史上下文、媒体限制等。
每个渠道有特定配置项，比如 Slack 支持 socket/http 模式，Signal 需要连接 signal-cli，WhatsApp 基于 Baileys 协议。

你可以怎么理解

可以把这些消息渠道看作"不同聊天软件的适配器"。OpenClaw 用统一的内部机制处理消息流转，但每个平台（比如 Slack 或 WhatsApp）有自己的 API 和规则，所以需要不同的接入方式。

核心渠道是"自带司机的车"，开箱即用；扩展渠道是"第三方租车"，得自己装 SDK 插件。但无论哪种，都遵循同样的控制逻辑：谁可以发消息（allowFrom）、是否要 @ 才响应（requireMention）、回复要不要带表情（ackReaction）等等。

像 Slack 的 mode=socket 或 http，其实是两种连接方式：WebSocket 长连接 vs Webhook 回调。Signal 则依赖外部 signal-cli 服务做中转。而 Feishu、Zalo 这类扩展渠道，虽然代码不在主仓库，但通过 plugin-sdk 提供的工具（如权限校验、历史管理）保持行为一致。

总之，不管渠道怎么变，OpenClaw 都用一套标准流程处理：收消息 → 校验权限 → 调用 agent → 发回复。

Control UI

这章在讲什么

这章讲的是 OpenClaw 的网页控制台（Control UI）------一个运行在浏览器里的单页应用（SPA），用来监控和操作 OpenClaw Gateway。它通过 WebSocket 和后端通信，提供了界面布局、状态管理、路由跳转、主题切换等核心功能。

核心要点

UI 是基于 LitElement 的 SPA，通过 GatewayBrowserClient 用 WebSocket 连接 Gateway。
所有状态集中在 OpenClawApp 组件中，用 @state() 管理，按功能模块分组（如 chat、agents、cron 等）。
页面设置（如主题、连接地址、token）存在 localStorage 里，键是 openclaw.control.settings.v1。
路由靠 URL 路径驱动，切换 tab 时自动加载对应数据。
支持三种主题：dark、light、system，会根据系统偏好自动切换。
支持通过 URL 参数注入配置，比如 ?token=xxx&gatewayUrl=ws://...，方便一键连接。

你可以怎么理解

你可以把它当成一个"前端工程结构速览"。整个控制台就是一个浏览器页面，启动时从 URL 或本地存储读取连接信息，然后连上 Gateway 的 WebSocket（ws://127.0.0.1:18789）。连接成功后，UI 会收发 RPC 消息，实时更新状态。

页面结构是标准的三栏布局：顶部栏 + 左侧导航 + 主内容区。导航按 tab 分页，每个 tab 对应一个 renderXxx() 函数，切换时会触发数据加载（比如进"cron"页就拉任务列表）。

状态全在 OpenClawApp 里，不搞复杂的状态库，简单直接。事件来了（比如 agent 输出了内容），就走 handleGatewayEvent() 分发处理，更新对应 state，页面自动刷新。

主题、布局比例、折叠状态这些用户偏好都存 localStorage，刷新不丢。还支持"设备认证"------浏览器生成密钥对，用 ECDSA 签名登录，比 token 更安全。

总之，这是一个典型的现代前端小项目：轻量、模块化、状态集中、通信靠 WebSocket。

Native Clients (Nodes)

这章在讲什么

这章讲的是 OpenClaw 里的"原生客户端"------也就是运行在手机或电脑上的 App（比如 iOS、Android、macOS），它们通过 WebSocket 连接到 OpenClaw Gateway，被称为 nodes。这些 nodes 能执行本地设备操作，比如拍照、录屏、发通知等，相当于给 AI Agent 提供了"动手能力"。

核心要点

Node = 本地执行器：不是用来传消息的（那是 channels 的事），而是让 Agent 能调用设备功能。
能力可发现 ：通过 node.list 和 node.describe 告诉 Gateway 自己能干啥。
安全配对：首次连接要走 pairing 流程，用挑战签名认证设备身份。
权限控制：严格遵循系统权限（iOS/macOS 的 TCC，Android 的 runtime permissions）。
多平台支持 ：iOS、Android、macOS 功能略有差异，比如 system.run 只有 macOS 支持。

你可以怎么理解

想象你的 Mac 或手机是一个"工具箱"，node 就是这个工具箱的联网接口。它连上 Gateway 后会说："我能拍照、能录屏、能发通知"。当你在 Agent 里说"帮我拍张照"，Gateway 就通过 node.invoke camera.snap 找到对应的设备去执行。

连接方式很灵活：局域网用 Bonjour 自动发现，远程可以用 Tailscale 或手动填 URL。即使 Gateway 跑在 VPS 上，node 依然能在本地设备执行命令（比如远程触发手机拍照）。

配对过程像"设备实名认证"：Gateway 发个验证码，App 提交后你用 CLI 输入 openclaw pairing approve 确认，之后就能长期信任。

常见问题基本就三类：连不上（检查防火墙/发现机制）、权限被拒（去系统设置开权限）、配对失败（确认验证码对不对）。用 openclaw nodes 和 node.describe 能快速排查。

iOS Client

这章在讲什么

这章讲的是 OpenClaw 的 iOS 客户端（叫 Clawdis）是怎么工作的。它不是一个普通 App，而是一个"能力节点"------把自己设备的摄像头、麦克风、位置等硬件能力注册到 OpenClaw Gateway，让远程的 AI Agent 能调用这些功能。

核心要点

iOS 客户端会同时建立两条 WebSocket 连接：
- node 角色：接收来自 Agent 的指令（比如"拍张照"）
- operator 角色：主动发消息（比如语音识别结果、聊天内容）
核心是 NodeAppModel，它管理连接、语音、屏幕、设备能力路由等所有状态。
连接时用 mDNS 发现网关，首次连接会弹出 TLS 证书指纹确认（TOFU 模型），之后自动信任。
语音功能分两块：TalkModeManager 负责语音对话（STT/TTS），VoiceWakeManager 负责"唤醒词"检测。
所有设备能力（拍照、录屏、定位等）通过 NodeCapabilityRouter 统一调度，支持后台限制和权限控制。
App 有完整的前后台生命周期管理，后台时会释放麦克风，可选保留语音监听。

你可以怎么理解

想象这个 iOS App 是你手机的"数字分身"。它连上本地网关后，就等于把你的手机变成一个可远程操控的智能终端。Agent 想拍照？发个 camera.snap 指令，App 就调用 CameraController 拍照回传。想语音聊天？TalkModeManager 用系统 STT 实时转文字，TTS 音频从网关流式返回。

整个架构很清晰：NodeAppModel 是大脑，两条 WebSocket 是神经通路，各种 Service 是手脚。安全上也考虑周到------TLS 指纹锁定、权限按需申请、后台自动降频保活。

开发上，SwiftUI + @Observable 驱动 UI，WKWebView 承载主界面（Canvas），所有交互都能透传给 Agent。调试时看 SettingsTab 里的日志和连接状态，基本就能定位问题。

macOS Client

这章在讲什么

这个 macOS 客户端（OpenClaw.app）是个常驻菜单栏的小工具，既是控制中心，也是功能节点。它让你能用语音唤醒、快捷通话、弹出对话界面，还能远程管理 Gateway，甚至当其他设备（比如手机）要配对时，它来弹窗审批。

核心要点

双角色运行：作为 node 上报能力（如截图、执行命令），作为 operator 控制聊天和配置。
支持静默配对：如果配对请求带 silent: true，会通过 SSH 连通性自动验证并批准，否则弹窗让你手动选。
内置 CLI 工具 openclaw-mac：可命令行调用 Gateway，适合脚本或自动化。
本地 IPC 通信：通过 OpenClawIPC 让 CLI 或子进程和主 App 直接对话，不走网络。
能力丰富：支持 system.run、screen.capture、camera.* 等 node.invoke 操作，依赖系统权限（如录屏、麦克风）。
自动更新靠 Sparkle，发布流程见文档。

你可以怎么理解

想象它是个"中枢管家"：

菜单栏一点，就能看会话、切 Agent、开语音、进 WebChat。
手机连 Gateway 时，它弹窗问"要不要信任这台设备？"------如果是在你家内网且 SSH 能通，甚至不用你点，自动通过。
你写个脚本跑 openclaw-mac call sessions.list，它能自动发现本地 Gateway 并返回结果，背后用的是 Bonjour（mDNS）发现。
它还能起 SSH 隧道，让远程 Gateway 像在本地一样被访问。
所有功能都靠 .plist 配置、Swift 包管理，结构清晰，扩展性强。
说白了，这是个"既好用又可编程"的 macOS 本地入口。

Android Client

这章在讲什么

这章讲的是 OpenClaw 的 Android 客户端（ai.openclaw.android）是怎么工作的。它不是一个简单的聊天 App，而是作为整个系统里的一个"智能设备节点"，通过 WebSocket 连接到 OpenClaw 的 Gateway，能执行相机拍照、读通知、展示网页交互界面等操作。

核心要点

Android 客户端启动时会建立两个 WebSocket 连接：
- node 角色：上报设备能力（比如摄像头、通知），接收并执行远程指令（node.invoke）。
- operator 角色：负责聊天、配置同步和 A2UI 界面控制。
首次连接需要配对（pairing），通过 QR 码扫描完成，安全认证基于密钥对（keypair）和加密存储。
支持四大能力模块：camera、device、notifications、canvas（A2UI）。
图像传输前会用 JpegSizeLimiter 压缩，防止大图压垮连接。
聊天界面用 Jetpack Compose 写，支持 Markdown 渲染（表格、删除线等 GFM 特性）。
构建基于 Gradle Kotlin DSL，最低支持 Android 12（API 31）。

你可以怎么理解

你可以把这个 Android App 想成"带 UI 的智能终端代理"。它不只是被动收消息，而是能让远端系统主动调用它的硬件能力。比如：远程拍张照、列出当前通知、甚至在 WebView 里跑交互式网页应用（A2UI）。两个连接分工明确：node 管"我能做什么"，operator 管"我现在说什么"。配对流程像 HomeKit 那种扫码绑定，安全又方便。开发时可以用 pnpm run android:run 一键安装调试，集成测试还能跑真实设备上的能力验证。

Security

这章在讲什么

这章讲的是 OpenClaw 的安全设计，核心目标是：即使消息来自不可信用户，系统也能安全运行。它覆盖了权限控制、认证机制、沙箱隔离、密钥管理、网络防护等关键环节，整体采用"纵深防御"策略，层层设防。

核心要点

访问控制：DM（私聊）和群组消息都有策略控制，支持配对（pairing）、白名单（allowlist）等模式，默认需配对才能交互。
认证机制：网关（gateway）支持 token 或密码认证；手机/电脑客户端通过 device pairing 认证；模型 API 密钥用 auth profiles 管理。
沙箱隔离 ：可通过 Docker 隔离非主会话（如群聊），限制工具对主机的访问，比如 exec 可用，但 browser、nodes 等高危工具默认禁用。
密钥管理 ：用 SecretRef 模式引用密钥（如 { $ref: "env/KEY" }），避免明文写在配置里；密钥文件权限设为 0600。
网络防护：网关默认只监听本地（loopback），若暴露公网必须开启认证；支持 Tailscale 安全远程访问。
工具权限：工具调用受多层策略过滤（全局、代理、群组、沙箱等），敏感命令（如重启、改配置）仅限所有者使用。
审计与合规 ：日志自动脱敏（如 API key），openclaw doctor 可检查安全配置，依赖库已修复已知漏洞。

你可以怎么理解

你可以把 OpenClaw 想成一个"带门卫的智能办公室"：

门卫（Access Control）：陌生人私聊会收到一个一次性验证码，你得手动批准才能进；群聊也只允许特定群。
员工卡（Authentication）：内部系统访问要刷卡（token），手机/电脑连上来要先"配对"认证。
隔离工位（Sandbox）：外部人员只能在沙箱里操作，不能碰主机，就像访客用临时电脑。
保险柜存钥匙（Secret Management）：API 密钥不放明面，而是存在加密文件或环境变量里，配置里只写引用。
网络防火墙：服务器默认只对本地开放，要远程访问就得走 Tailscale 或加密码。
权限分级（Tool Policy）：不同场景能用的工具不同，比如群聊里不能执行 shell 命令，沙箱里也禁用浏览器。
安全巡检 ：用 openclaw doctor 定期检查配置是否安全，比如密钥权限、认证是否开启等。

总之，OpenClaw 的设计是"默认安全"，你不需要一步到位配好所有策略，但上线前一定要检查认证、沙箱和密钥管理。

Security Audit

这章在讲什么

这章讲的是 OpenClaw 的 security audit 安全检查功能，包括命令行怎么用、检查了哪些项目、内部是怎么工作的，以及发现风险后能怎么自动修复。核心是帮你发现配置中的安全隐患，比如权限太松、暴露在公网、用了危险的 Docker 设置等。

核心要点

用 openclaw security audit 命令运行检查，加 --deep 可探测正在运行的服务，加 --fix 能自动修复部分问题。
检查项分很多类：网关配置、文件权限、沙箱设置、工具权限、插件安全等，每项有 info/warn/critical 三个等级。
--fix 只做安全的自动修复，比如收紧文件权限、关闭开放群组策略，但不会改密码或网络配置。
检查结果结构清晰，包含 summary 和具体 findings，支持 JSON 输出方便自动化处理。

你可以怎么理解

你可以把 security audit 当成一个"安全体检工具"。它不光看你的配置文件（比如 openclaw.json），还能结合系统环境和运行状态，找出潜在风险。比如：

你的配置文件是不是被设成所有人可读？→ 会报 critical。
网关绑在公网但没开认证？→ 直接标为 critical。
沙箱用了 network=host 或挂载了 /etc？→ 危险，必须警告。

它的检查逻辑很细，比如"暴露在公网"不仅看 gateway.bind，还看 Tailscale 是否开了 funnel 模式。很多 warn 会在暴露时升级成 critical。

自动修复 --fix 很克制：只改配置中的 groupPolicy、日志脱敏设置，以及收紧关键文件（如 config、session 文件）的权限，绝不碰密码或 token。

优先处理建议是：先封住入口（认证、访问控制），再修文件权限，最后看模型和插件是否可信。总之，这个命令是你上线前必跑的一环。

Sandboxing

这章在讲什么

这章讲的是 OpenClaw 如何用 Docker 隔离不信任的代码执行，防止代理（agent）直接操作你的主机系统。特别适合群聊、Webhook 这类外部输入场景，避免恶意或出错的代码搞崩主机。

核心要点

沙箱通过 agents.defaults.sandbox 配置，支持三种模式：off（关闭）、non-main（仅隔离非主会话）、all（全部隔离）。
隔离粒度由 scope 控制：session（每会话一个容器）、agent（每个 agent 共享容器）、shared（所有沙箱共用一个容器）。
沙箱里只能用安全工具，比如 exec、read、write；像 browser、cron、discord 这种需要主机权限的会被自动禁用。
必须先运行 scripts/sandbox-setup.sh 构建 openclaw-sandbox 镜像才能启用沙箱。
提供 openclaw sandbox list/recreate/explain 等 CLI 命令管理容器。

你可以怎么理解

你可以把 sandbox 想成一个"安全操作间"------当 agent 要执行命令时，OpenClaw 会把它丢进一个临时的 Docker 容器里运行，里面只能访问自己的文件和网络，碰不到你本机的数据。

比如你在群里让 bot 写代码、跑脚本，默认是不隔离的，有点危险。但你设成 mode: non-main 后，群聊就自动进沙箱了，它就算想删你文件也做不到。

而且 agent 自己也知道在沙箱里（系统提示里会写明），就不会傻乎乎地去调 browser 这种用不了的工具。

不过注意：沙箱防不了网络外传（默认能上网）、也防不了 prompt 注入，所以建议配合工具白名单 + Docker 网络策略一起用，更安全。

Development Guide

这章在讲什么

这章是给 OpenClaw 贡献代码的工程师看的开发手册，讲清楚了项目结构、本地开发流程、编码规范、测试和提交 PR 的标准做法。相当于一份"怎么正确参与这个项目"的实操指南。

核心要点

项目是 pnpm 管理的 TypeScript 单体仓库（monorepo），核心代码在 src/，插件在 extensions/，客户端在 apps/。
开发用 Node.js 22+、pnpm 10.23+，推荐用 Bun 跑测试和 CLI。
本地命令：pnpm install 装依赖，pnpm dev 启动 CLI，pnpm check 检查格式和类型，pnpm test 跑测试。
提交必须用 scripts/committer 脚本，保证只提交相关文件。
新增功能（比如新渠道）要同步更新 label、文档和配置界面。

你可以怎么理解

你可以把 OpenClaw 项目想象成一个模块化的大工具箱：

src/ 是主工具包，放核心逻辑（比如 CLI、网关、代理）；
extensions/ 是插件区，每个插件自己管自己的依赖；
apps/ 是各个平台的客户端（iOS、Android、macOS），用原生语言写；
ui/ 是前端控制台。

开发时，先 pnpm install 装好依赖，然后用 pnpm dev 跑起来调试。改完代码，跑 pnpm check 和 pnpm test 确保没 break。提交前用 scripts/committer "fix: something" 提交，它会帮你精准提交改动文件，避免误提交。

测试用 Vitest，覆盖率要求 70% 以上。CI 会自动跑 pnpm check 和测试，所以本地过不了的代码别 push。

如果你要加个新渠道（比如 Telegram），除了写代码，还得去 .github/labeler.yml 加规则，更新文档，确保 UI 和配置都能对上。

总之：结构清晰，工具链统一，提交规范严格------适合团队协作，避免"我本地好好的"这种问题。

CI/CD Pipeline

这章在讲什么

这章讲的是 OpenClaw 项目的 CI/CD 流水线设计，重点是如何通过智能判断代码变更范围，跳过不必要的构建和测试任务，从而加快开发反馈速度。它不是简单地"每次提交都跑全套流程"，而是有一套聪明的"该跑哪些任务"的决策机制。

核心要点

流水线定义在 .github/workflows/ci.yml，触发于每次 main 分支推送或 PR。
使用两阶段"变更范围检测"：先看是不是只改了文档（docs-scope），如果不是再分析具体改了哪些模块（changed-scope）。
根据变更路径自动决定是否运行 macos、android、windows、skills-python 等平台相关任务。
所有构建只做一次（build-artifacts），产物共享给后续任务。
安全扫描（如 detect-secrets、zizmor）独立运行，不被范围检测跳过。
Windows 测试做了 6 分片并行，macOS 任务合并为一个防止超出 GitHub 并发限制。

你可以怎么理解

你可以把这套 CI 想象成一个"聪明的流水线调度员"。

当你提个 PR，它先快速看一眼：是不是只改了 .md 文档？ 是的话，直接跳过所有耗时构建和测试，只跑文档检查，几十秒搞定。

如果改了代码，它就调用 scripts/ci-changed-scope.mjs 分析你改的文件路径：

改了 src/ 或 packages/？→ 跑 Node 相关测试。
改了 apps/macos/？→ 跑 macOS 构建和测试。
改了 skills/？→ 跑 Python 技能检查。
改了 .github/workflows/？→ 跑 GitHub Actions 安全审计（zizmor）。

这种"按需执行"大幅减少了非必要任务，但又保证 main 分支每次全量跑，确保质量。再加上 pnpm 缓存、sticky disk、子模块重试等细节优化，整个 CI 既快又稳。

Release Process

这章在讲什么

这章讲的是 OpenClaw 项目怎么发版：从版本号怎么定、发版前要检查啥，到怎么打包、发布到 npm、GitHub 和各个应用商店，再到用户怎么更新。核心是确保多平台（macOS、iOS、Android）版本一致、流程自动化、更新可靠。

核心要点

版本号用日期格式：YYYY.M.D，比如 2026.3.3，beta 版是 2026.3.3-beta.1
所有平台版本以 package.json 里的版本为准，自动推导 Android/iOS/macOS 的构建号
发版前必须跑 npm run release:check 检查版本、changelog、git 状态
CHANGELOG 要结构化写清楚：新功能、破坏性变更、修复，还得带上 PR 和贡献者
发版靠 Git Tag 触发 CI，自动构建、发 npm、GitHub Release、Sparkle 更新 feed
macOS 用 Sparkle 实现自动更新，iOS/Android 分别走 App Store 和 Play Store

你可以怎么理解

你可以把 OpenClaw 的发版想象成一条流水线：

先统一版本号，改 package.json，其他平台（Android 的 versionCode、iOS 的 CFBundleVersion）会自动算出来。然后更新 CHANGELOG.md，写清楚这次发版改了啥，尤其是破坏性变更要提醒用户怎么升级。

接着跑 release:check 脚本，确保代码干净、版本对得上、changelog 有写。再本地构建测试一遍，没问题就打 tag 推上去：

bash 复制代码

git tag v2026.3.3
git push origin v2026.3.3

CI 会自动跑：构建所有平台包，发到 npm（latest tag）、GitHub Release 附上安装包，macOS 还会生成 Sparkle 的 appcast.xml 实现自动更新。

iOS 和 Android 包也会生成，但上传商店是手动的。最后记得更新文档、发个 announcement。整个过程靠 CI/CD 自动化，减少人为出错。