聚水潭
118.20M · 2026-03-13
这章是 OpenClaw 项目的整体技术概览，帮你快速理解它的架构、核心模块和工作方式。适合刚接手或想参与开发的工程师，先搞清楚“这系统到底是干啥的”、“代码怎么组织的”。
gateway 的主进程运行，管理会话、路由消息、执行工具。~/.openclaw/openclaw.json，用 JSON5 格式，支持注释和引用，结构清晰。想象你有个“AI 助手中枢”，它同时挂着微信、T@elegrimm、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 的核心工作模式。
这章是 OpenClaw 的入门指南，教你从零开始安装、配置并验证一个能跑起来的 Gateway。核心流程包括：环境准备、安装命令、使用 onboard 向导完成初始化设置、用 doctor 命令检查和修复问题，最后通过几个命令确认系统正常运行。
curl -fsSL | bash，它会自动处理 Node、安装和初始化。openclaw onboard 是交互式配置向导，帮你设置模型认证、网络端口、通信渠道等。openclaw doctor 是健康检查工具，能自动发现并修复配置、权限、服务等问题。gateway status、status、doctor 和 dashboard。你可以把整个过程想象成“装一台智能机器人主机”：
openclaw onboard --install-daemon，它会一步步问你：
openclaw doctor，它就像个医生，检查配置对不对、token 有没有、服务是否正常，还能自动修复很多问题。openclaw status 和 openclaw dashboard 打开网页控制台，看到界面就说明成功了。配置文件默认在 ~/.openclaw/openclaw.json，所有设置最终都写在这里。如果出问题，先 openclaw doctor，再看日志 openclaw logs --follow。
这章讲的是 OpenClaw 的核心架构设计，帮你理解它怎么把 AI 代理、聊天渠道、设备节点这些模块串在一起工作。适合想搞清楚系统“怎么跑起来”的工程师。
18789 端口。SKILL.md 注入提示词或工具。~/.openclaw/openclaw.json（支持注释的 JSON5），支持热重载。可以把 OpenClaw 想成一个“AI 消息调度中心”：
外部消息（比如 T@elegrimm）进来 → 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 最省事。
这章讲的是 OpenClaw 的核心组件——Gateway（网关）。你可以把它理解成整个系统的“大脑”和“通信中心”。它负责管理所有客户端（比如 CLI、控制台、手机 App）、消息渠道（T@elegrimm、WhatsApp 等）和智能代理（Agents）之间的通信，统一处理配置、会话、认证和远程调用（RPC）。
openclaw.json 配置文件，支持热重载（部分配置改了不用重启）。request（请求）、response（响应）、event（事件推送）。operator、node、user）控制权限。SecretRef 引用环境变量、文件等，避免明文。sessionKey 路由，支持按用户、渠道隔离。openclaw gateway 命令管理服务生命周期，doctor 命令诊断问题。想象 Gateway 就像一个“总机接线员”：
request 想发消息，它转给对应的 agent 处理，再把结果 response 回你；event 推给你；openclaw gateway start/stop/status 控制它，就像管理一个系统服务。简单说：所有事都得经过 Gateway，它是 OpenClaw 的中枢神经。
这章讲的是 OpenClaw 网关（Gateway）用的 WebSocket 通信协议和远程过程调用（RPC）机制。它定义了客户端和服务器之间怎么建立连接、发请求、收响应、接收服务端推送事件，以及权限控制、错误处理等核心逻辑。简单说，就是“两个程序怎么安全、可靠地聊天”。
ws://127.0.0.1:18789，消息全是 JSON 文本帧。connect.challenge 带 nonce，客户端回 connect 请求，带上协议版本、身份信息和认证数据。id，服务器回相同 id 的响应，支持成功/失败两种结果。operator（操作员）和 node（节点）两种角色，operator 还要按 scopes 控制权限（比如 operator.read 只能读）。tick 心跳、agent 事件），客户端靠 seq 序号检测丢包。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），保证前后端类型一致。
总之，这套协议就像一套“对话规则”：先打招呼，再按格式说话，听对方广播，谁也不能乱来。
这章讲的是 OpenClaw 网关（Gateway）怎么验证客户端身份、如何安全地配对新设备，以及权限控制机制。核心是：谁可以连上来？有什么权限？怎么防止被冒充？
token、password、通过反向代理传身份（如 Tailscale）、甚至无认证（仅限本地开发）。nonce，客户端签名证明身份，并完成配对。operator 是管理员，node 是能力提供者（如手机）；scopes 细粒度控制能做什么。node（提供摄像头等能力），一个当 operator（聊天、配置）。想象你要让手机连上家里的服务器。第一步，手机得证明“我是我”——它用自己的私钥签名一段数据（含时间戳、nonce），服务器用公钥验证。这就是设备身份。
接着是配对：第一次连，服务器说“不认识你，请审批”。如果你在本地连（比如电脑直连），系统自动批准；如果是远程，就得通过 T@elegrimm 输入 /pair approve 手动点同意。
一旦配对成功，服务器会发一个设备令牌（deviceToken），下次连接可以直接用这个 token，不用再走完整流程。
权限方面，比如你的手机想发消息、读配置，就得申请 operator.write 和 operator.read 这些 scopes，而且这些必须在签名时就定好，不能临时加，防止提权。
Tailscale 用户更方便：登录了 Tailscale，网关直接信任你，跳过配对。
整个流程像“带钥匙进门 + 登记备案 + 领门禁卡”，既安全又灵活。
这章讲的是 OpenClaw 网关的配置系统，它负责加载、验证、热更新和管理整个系统的配置。配置文件是 ~/.openclaw/openclaw.json（用 JSON5 格式），系统会自动处理密钥、文件包含、旧格式迁移，并支持运行时动态更新。
$include → 迁移旧字段 → Zod 校验 → 解密 SecretRefhot/hybrid 模式），部分修改无需重启{ $ref: "env:KEY" } 引用环境变量或文件，避免明文写密钥$include 把大配置拆成多个文件config.patch）dm.policy → dmPolicy）你可以把配置系统当成一个“智能配置中心”。它不只是读个文件那么简单，而是：
SecretRef 指向环境变量或文件，不会泄露。$include 拆分，比如把 agents 单独放一个文件。gateway.port 得重启，但改 agents 就能立刻生效。openclaw doctor --fix 修复。config.patch API 动态改配置，就像调接口一样。简单说：写配置更安全、更模块化，改配置不用总重启，还能用工具自动管理。
这章是 OpenClaw 的配置文件 ~/.openclaw/openclaw.json5 的完整说明书。它告诉你这个配置文件长什么样、有哪些字段、怎么用，尤其是 gateway、channels、agents、tools 这些核心模块的设置。你可以把它当成一本字典，需要改什么功能就来查对应的 key。
${SECRET}）→ 生效。gateway：控制 API 端口、认证（token/密码）、TLS、远程连接等。channels：配置 T@elegrimm、Discord、Slack 等聊天渠道，支持多账号和精细权限控制。agents：定义 AI 代理的行为，比如用什么模型、工作区路径、工具权限。tools：全局开关，控制 web 搜索、代码执行、媒体理解等功能是否开启。想象你在搭一个自动化机器人系统。gateway 就是它的“总控室”，决定它开在哪个端口、要不要密码、能不能被外网访问。channels 是它的“社交账号”，比如一个 T@elegrimm 机器人和一个 Discord 机器人，你可以分别设置它们的 token、谁可以私聊它、进群要 @ 吗。agents 是它的“员工”，比如一个叫 research 的员工专门负责搜索，用 claude-sonnet 模型，工作区在 ~/research。tools 就是“工具箱”，你在这里决定员工们能不能上网搜资料、能不能运行代码。整个配置就是一份详细的“岗位说明书”，告诉系统每个部分该怎么干活。
这章讲的是 OpenClaw 里“会话”（Session）是怎么管理的。简单说，就是每次你和机器人聊天，系统怎么记住你是谁、聊过什么、状态如何，同时保证多人并发时不会乱套。
provider:account:ch@t:dmScope，比如 telegram:bot1:user123:dm。sessions.json 存元信息（SessionEntry），聊天记录存为 session-*.jsonl 文件。.lock 文件）防止多个请求同时写同一个会话，避免数据错乱。可以把 Session 想成一个聊天的“档案袋”。每个用户、每个群聊都有自己的袋子（Session Key 区分），里面装着聊天记录（JSONL 文件）和档案卡（SessionEntry）。每次机器人回复前，先拿锁（acquireSessionWriteLock），避免两人同时改一个文件。
如果聊得太长，系统会自动把前面的内容总结成一段话，保持文件不会无限膨胀。
你还能通过 API 查看会话列表（sessions.list）、预览最近消息（sessions.preview），甚至重置对话（sessions.reset）——就像重启一次新对话，但保留原来的“身份”。
整个机制既保证了数据安全，又支持高并发和长期记忆，是 OpenClaw 聊天稳定的核心基础。
这章讲的是 OpenClaw Gateway 内置的一个定时任务系统（Cron Service），它能按计划自动执行一些操作，比如定时发消息、触发 Agent 任务等。你可以把它理解成系统里的“闹钟服务”。
at）和周期性（every、cron 表达式）任务。main）或独立运行（isolated）。cron.* 的 WebSocket RPC 接口暴露，方便外部控制。想象你在写一个机器人，想让它每天早上 8 点自动发一句“早安”。这个功能就是靠 Cron Service 实现的。
你定义一个 CronJob，设置 schedule 为 cron 表达式 "0 0 8 * * *"，payload 是要发送的内容，sessionTarget: "main" 表示直接塞进主流程处理。如果想让它独立运行（比如跑个完整推理），就设成 "isolated"。
任务执行后，结果会写进 ~/.openclaw/cron/runs/<jobId>.jsonl 的日志文件。你还能配置 delivery 把结果发到 T@elegrimm 或打个 Webhook。
系统很稳：即使某个任务卡住，其他定时检查最多等 60 秒也会触发；失败了会指数退避（30秒、1分钟、5分钟…）；并发数也能限制，避免资源耗尽。
你可以用 cron.add、cron.list 等 RPC 命令动态管理这些任务，就像操作一个轻量级的定时任务调度器。
这章讲的是 OpenClaw 里的 Agent（智能体） 是什么，它是怎么被配置和运行的。简单说，Agent 就是一个有独立身份和能力的 AI 助手实例，能处理消息、调工具、读写文件，每个都有自己的工作空间和模型配置。
openclaw.json 的 agents 下定义），"default" 是默认兜底。.jsonl 格式）你可以把 Agent 想成一个“AI员工”，它有自己的工位（workspace）、工牌（API key）、工具包（tools），还有一本工作日志（session transcript）。每次有人发消息，系统就给这个“员工”派个活儿。
关键流程是这样的：
resolveSessionAgentIds）buildAgentSystemPrompt），包括注入 AGENTS.md、MEMORY.md 等上下文文件compactEmbeddedPiSessionDirect 压缩历史，再重试特殊场景：
promptMode: "minimal"，少一堆功能，更轻量整个流程像一条流水线，从 runReplyAgent 开始，层层调用，直到 SDK 实际和模型交互。
这章讲的是一个用户消息从进入系统，到 AI 模型生成回复，再到最终回复返回给用户的完整流程。重点是背后这一连串函数调用、错误重试、权限切换、上下文压缩等机制，确保每次对话都能稳定执行。
runReplyAgent → runAgentTurnWithFallback → runEmbeddedPiAgent → runEmbeddedAttempt，最后通过 subscribeEmbeddedPiSession 流式接收模型输出。<thinking> 等标签过滤，避免中间思考暴露给用户。typingMode 控制“正在输入…”提示的显示时机。可以把整个流程想象成一个快递处理中心：
runReplyAgent：检查包裹（消息）是否要丢弃、排队，或者立刻处理；还会贴上“正在处理”标签（typing indicator）。runAgentTurnWithFallback：如果送货失败（比如地址太远=上下文超限），就尝试压缩包裹再送，或者换条路（重试/降级）。runEmbeddedPiAgent：决定用哪家快递公司（model），哪个司机（auth profile），并确保同一收件人不同时发多个快递（lane 串行）。runEmbeddedAttempt：真正打包发货前的准备，比如整理工具、读取客户档案、构建提示词。subscribeEmbeddedPiSession：边打包边直播进度，把内容分块发出去，过滤掉内部备注（如 <thinking>），只让用户看到最终回复。整个过程高度容错，哪怕 API 限流、密钥失效、上下文爆炸，系统都会自动兜底，尽量不让用户感知到失败。
这章讲的是 OpenClaw 如何为每个 agent 构造 system prompt——也就是模型运行时看到的“系统指令”。这个 prompt 不是固定的，而是每次动态拼出来的，包含了工具列表、安全规则、工作区信息、启动文件内容等，并且会根据场景（比如主 agent 或子 agent）调整详细程度。
buildAgentSystemPrompt() 函数动态生成，不是硬编码或直接用默认模板。SOUL.md、AGENTS.md）。full（完整）、minimal（子 agent 用，精简）、none（几乎为空）。你可以把 system prompt 想成 agent 的“开机 BIOS”——它一启动就看到这段话，知道“我是谁、能干什么、有哪些规则”。OpenClaw 完全掌控这个 prompt，不会依赖外部默认设置。
拼接过程像流水线：先收集各种信息块（工具、内存、文档等），再根据 promptMode 决定保留哪些（比如子 agent 用 minimal，就不需要消息格式、心跳这些）；最后把 bootstrap 文件（比如 SOUL.md 定义的人设）也塞进去，形成最终 prompt。
特别注意：
SOUL.md 被识别后，会提示 agent “你要模仿这个 persona”。read、write 在前），并且会根据是否在 sandbox 中调整描述（比如禁用 ACP 相关功能）。session_status 工具去查。整个机制很灵活，通过配置参数（如 toolNames、contextFiles、promptMode）可以精细控制每个 agent 的上下文环境。
这章讲的是 OpenClaw 是怎么管理 AI 模型的配置和认证的，比如你怎么告诉它用哪个模型（比如 Claude、GPT）、怎么存 API Key 或 OAuth 凭证，以及运行时怎么选模型、失败了怎么切换备用方案。
auth-profiles.json 里，支持 api_key、oauth、token 三种类型。--secret-input-mode ref 存引用。openclaw.json）和“隐式”（有密钥就自动注册）。/model sonnet）和白名单控制。你可以把 OpenClaw 的模型系统想象成一个“多账号多平台”的打车 App。你存了好几个平台的账号（Anthropic、OpenAI 等），每个账号有不同凭证（API Key 或登录态）。系统会优先用你设的“主司机”（primary model），如果他接不了单（401/限流），就自动换下一个（fallback）。
凭证管理很灵活：你可以直接贴 API Key，也可以用 OAuth 登录（比如 GitHub Copilot），甚至让系统自动从环境变量里读。像 Ollama 这种本地服务，只要开着，OpenClaw 就能自动发现可用模型。
命令行 openclaw models 是你的遥控器：查状态、切模型、设别名、管 fallback，都不用手改 JSON。整个流程既适合手动配置，也支持自动化部署。
这章讲的是 OpenClaw 里“工具系统”的完整流程：每次 AI 代理（agent）要执行动作前，怎么动态组装它能用的工具列表，怎么通过多层策略过滤、保护文件系统，以及最后怎么包装和发送给模型。整个过程像是一个“工具流水线”。
createOpenClawCodingTools，它会整合基础工具和 OpenClaw 自研工具。workspaceRoot。exec 和 process 工具支持后台执行和中断信号，apply_patch 只在 OpenAI 类模型中启用。想象你在给一个程序员 AI 配“工具箱”。每次它要干活前，系统都会：
web_search、sessions_spawn）里凑出一份清单。coding profile 包含 fs 和 runtime 工具），再看 agent、provider、sandbox 限制，最后连“只有主人才能用的工具”也会被单独过滤。workspaceOnly，所有文件操作都会被包装，防止跳出项目目录。minLength 这类不兼容字段，OpenAI 才能用 apply_patch。AbortSignal 中断。最终这个“工具箱”被塞进 system prompt，交给模型决定怎么用。整个过程高度可配，安全优先。
这章讲的是 OpenClaw 里怎么执行命令和管理后台任务。简单说，exec 用来跑 shell 命令，process 用来管那些跑在后台的长期任务，比如构建、服务启动等。
exec 工具执行命令，可以设置超时、是否后台运行、是否用 PTY（比如需要交互式输入时）。yieldMs）或明确设了 background: true，它会返回一个 sessionId，表示任务已后台化。process 工具通过 sessionId 来管理这些后台任务：轮询输出、发 stdin 输入、查状态、杀进程等。scopeKey 隔离（通常是每个会话独立），避免互相看到。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 控制任务记录保留多久。
这章讲的是 OpenClaw 里让 AI 代理“记住”信息的工具和机制，重点是两个核心功能：memory_search（语义搜索记忆文件）和 memory_get（读取指定记忆文件）。它覆盖了底层实现、配置方式和命令行操作，帮你搞清楚 AI 是怎么查找和使用历史记忆的。
memory_search 做语义搜索，memory_get 读具体文件。builtin），或调用外部 qmd 工具（qmd）。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 能高效、安全地访问长期记忆，而且可扩展、可调试。
这章讲的是 OpenClaw 里的“子代理”（subagents）机制——也就是主 Agent 在运行时临时起一个独立小任务，让它在隔离环境中干活，干完把结果送回来。适合做并行、后台任务，避免卡住主线。
sessions_spawn 工具或 /subagents spawn 命令触发。agent:<id>:subagent:<uuid>），隔离上下文和可用工具。maxSpawnDepth 控制。mode: "session" + thread: true），目前仅 Discord 支持线程绑定。你可以把 subagent 想成“派出去的小分队”：主 Agent 接到任务后，说“这事儿我外包一下”，然后调用 sessions_spawn 起一个独立会话，让小分队去查资料、跑脚本。这个小分队有自己的上下文和权限（比如不能随便再派下级小分队），干完活自动汇报结果到原聊天窗口。
结果发送走的是 announce 流程，会优先发到线程/频道绑定的位置，如果发不出去会重试几次（最多3次，指数退避）。整个过程不阻塞主线，还能控制最多嵌套几层（比如最多 A 派 B，B 不能再派 C）。
配置都在 agents.defaults.subagents 下，比如默认超时、模型、最大深度。调用时传参可覆盖。简单说：异步、隔离、可控、可追溯。
这章讲的是 OpenClaw 里命令和自动回复系统的工作机制：怎么识别用户输入的 /status、/think high 这类指令，怎么处理它们，以及在群聊里什么时候该回复、什么时候该闭嘴。
简单说，就是“你发一条消息，系统怎么决定是当普通聊天走模型，还是当成命令直接处理”。
/status）走“快路径”，不进 AI 模型队列；带指令的普通消息（如“说点啥 /think high”）会提取指令后，剩余内容交给 AI。commands-registry.data.ts，支持别名、参数、跨平台适配（比如 Discord 不能用 /tts，就改成 /voice）。/think high 控制思考等级，但只有授权用户才生效。mention 模式），可用 /activation always 改成有消息就回。/send on|off 可开关回复发送，用于调试或静音。想象你在群里发了条消息：
系统会先扫一遍有没有 / 或 ! 开头的内容。发现 /status，就把它拎出来处理——生成状态卡片回复你。剩下的“今天过得咋样”继续交给 AI 处理。
如果你是管理员，发个 /think high 单独一行，系统会记住你接下来的对话都用“高思考模式”；但如果不是你发的，这条就直接忽略。
命令能不能用，取决于配置和权限。比如 /bash 默认关着，得在 config 里手动打开。群聊里回不回复，看的是 activation 设置和有没有被 @。
整个流程像一个过滤器管道：消息进来 → 检查是不是命令 → 是就快处理，不是就提指令 → 最后决定走不走 AI。干净利落，不拖泥带水。
这章讲的是 OpenClaw 是怎么对接各种聊天平台（比如 T@elegrimm、Discord、Slack 等）的。核心是“通道（Channels）”系统，它让机器人能收发消息、控制权限、处理会话，而且对不同平台做了统一抽象，方便扩展。
dmPolicy 控私聊，groupPolicy 控群聊，支持白名单和配对机制。channels.<platform> 下，支持多账号、分账号配置，还能合并默认值。你可以把每个聊天平台当成一个“插件”，它们都遵循同一个模式：启动一个 monitor 长连接，收到原始消息后，先标准化成统一格式（envelope），然后走一套通用处理流水线。
比如你发一条 T@elegrimm 消息，系统会：
会话靠 session key 区分，比如私聊是 agent:xxx:main，群聊是 agent:xxx:telegram:group:12345，这样同一个机器人在不同群聊能保持独立上下文。
配置上，你可以为不同账号设不同 token 和权限，比如一个 T@elegrimm 账号只接受特定用户，另一个专门收告警。还支持 allowFrom: ["*"] 开放访问，或者用 pairing 模式让新用户先输验证码。
总之，这套设计让你能用一套逻辑对接多个平台，同时保持灵活性和安全性。
这章讲的是 OpenClaw 是怎么对接各种聊天平台（比如 T@elegrimm、Discord）的。核心是一个叫 monitor 的长驻进程，负责连接平台、收消息、做权限检查，然后把消息统一格式后交给机器人处理。回复时再通过 monitor 发回去。插件开发者可以用 openclaw/plugin-sdk 这个包来写自己的频道插件，不用碰内部代码。
dispatchInboundMessage 把消息推给 agent。src/ 下，插件频道（如 Feishu）在 extensions/ 下，后者必须用 openclaw/plugin-sdk。ChannelPlugin 接口定义了插件能力，通过一堆 Adapter 实现，比如发消息、处理命令、群组管理等。PluginRuntime 提供插件可用的运行时能力，比如发消息、读配置、操作会话数据。想象每个聊天平台都有一个“代理”（monitor），它一直连着平台服务器，收到消息后先看一眼“能不能处理”（access control），比如是不是白名单用户、有没有被 @。然后把消息标准化成统一格式（InboundContext），扔给机器人引擎处理。机器人回复时，monitor 负责把 ReplyPayload 拆成合适大小的文本块（chunkTextForOutbound），加上 typing 指示器（createTypingCallbacks），再发回去。插件开发者只需要实现 ChannelPlugin 里的各个 Adapter，比如用 ChannelMessagingAdapter 实现 sendMessage，用 ChannelCommandAdapter 注册 /help 这样的命令就行。配置用 Zod 校验，敏感字段自动脱敏。整个流程清晰，插件隔离，安全又灵活。
这章讲的是 OpenClaw 是怎么接入 T@elegrimm 的——从机器人启动、消息怎么进来、权限怎么控制，到回复怎么发出去，整个流程是怎么设计的。适合想搞清楚 T@elegrimm 模块工作原理的开发者。
createT@elegrimmBot 初始化。你可以把 T@elegrimm 集成想象成一个“消息流水线工厂”：
T@elegrimmMessageContext，包含发件人、会话 ID、是否带附件、是否回复某条消息等信息。过程中会检查你有没有权限发消息（比如 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 都在 T@elegrimmAccountSchema 里定义，支持多账号管理。简单说：收消息 → 过安检 → 拆包裹 → 交给 AI → 流式发回复，每一步都可配置。
这章讲的是 OpenClaw 如何集成 Discord，包括机器人启动流程、消息权限控制、线程绑定、执行审批、Slash 命令部署等核心机制。适合想搞懂 OpenClaw 在 Discord 里怎么跑的工程师。
@buape/carbon 库通过 WebSocket 连接 Discord Gateway。preflightDiscordMessage 检查权限，支持 DM、频道、线程不同策略。partial/block 模式），默认只发最终回复。你可以把 monitorDiscordProvider 当作 Discord 集成的“主入口”，它负责：
guilds、channels，把 slug 转成 ID；/skill）；权限控制是分层的：先看是不是 DM，是的话走 dmPolicy；不是就查 guild 和 channel 的 allowlist，还能配 requireMention 强制要 @ 机器人才响应。
session key 是隔离会话的关键，比如：
agent:<id>:discord:channel:<channelId>agent:<id>:discord:slash:<userId>配置里注意：ID 都得写成字符串，dangerouslyAllowNameMatching 开了才能用用户名匹配（不推荐）。Streaming 默认关，想实时出字就得开 partial。
这一章讲的是 OpenClaw 支持的除 T@elegrimm 和 Discord 之外的其他消息渠道（如 Slack、Signal、WhatsApp 等）的配置和集成方式。它区分了“核心渠道”（内置）和“扩展渠道”（独立插件），并说明了它们的架构、配置字段和通用模式。
src/config/，坚控逻辑在对应 src/<channel>/ 目录。openclaw/plugin-sdk 实现统一接口。dmPolicy 控制私聊权限，groupPolicy 控制群组访问，支持多账号、历史上下文、媒体限制等。可以把这些消息渠道看作“不同聊天软件的适配器”。OpenClaw 用统一的内部机制处理消息流转，但每个平台（比如 Slack 或 WhatsApp）有自己的 API 和规则，所以需要不同的接入方式。
核心渠道是“自带司机的车”，开箱即用；扩展渠道是“第三方租车”，得自己装 SDK 插件。但无论哪种，都遵循同样的控制逻辑：谁可以发消息（allowFrom）、是否要 @ 才响应（requireMention）、回复要不要带表情（ackReaction）等等。
像 Slack 的 mode=socket 或 http，其实是两种连接方式：WebSocket 长连接 vs Webhook 回调。Signal 则依赖外部 signal-cli 服务做中转。而 Feishu、Zalo 这类扩展渠道，虽然代码不在主仓库，但通过 plugin-sdk 提供的工具（如权限校验、历史管理）保持行为一致。
总之，不管渠道怎么变，OpenClaw 都用一套标准流程处理：收消息 → 校验权限 → 调用 agent → 发回复。
这章讲的是 OpenClaw 的网页控制台（Control UI）——一个运行在浏览器里的单页应用（SPA），用来坚控和操作 OpenClaw Gateway。它通过 WebSocket 和后端通信，提供了界面布局、状态管理、路由跳转、主题切换等核心功能。
GatewayBrowserClient 用 WebSocket 连接 Gateway。OpenClawApp 组件中，用 @state() 管理，按功能模块分组（如 ch@t、agents、cron 等）。localStorage 里，键是 openclaw.control.settings.v1。dark、light、system，会根据系统偏好自动切换。?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。
这章讲的是 OpenClaw 里的“原生客户端”——也就是运行在手机或电脑上的 App（比如 iOS、Android、macOS），它们通过 WebSocket 连接到 OpenClaw Gateway，被称为 nodes。这些 nodes 能执行本地设备操作，比如拍照、录屏、发通知等，相当于给 AI Agent 提供了“动手能力”。
node.list 和 node.describe 告诉 Gateway 自己能干啥。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 能快速排查。
这章讲的是 OpenClaw 的 iOS 客户端（叫 Clawdis）是怎么工作的。它不是一个普通 App，而是一个“能力节点”——把自己设备的摄像头、麦克风、位置等硬件能力注册到 OpenClaw Gateway，让远程的 AI Agent 能调用这些功能。
node 角色：接收来自 Agent 的指令（比如“拍张照”）operator 角色：主动发消息（比如语音识别结果、聊天内容）NodeAppModel，它管理连接、语音、屏幕、设备能力路由等所有状态。TalkModeManager 负责语音对话（STT/TTS），VoiceWakeManager 负责“唤醒词”检测。NodeCapabilityRouter 统一调度，支持后台限制和权限控制。想象这个 iOS App 是你手机的“数字分身”。它连上本地网关后，就等于把你的手机变成一个可远程操控的智能终端。Agent 想拍照？发个 camera.snap 指令，App 就调用 CameraController 拍照回传。想语音聊天？TalkModeManager 用系统 STT 实时转文字，TTS 音频从网关流式返回。
整个架构很清晰：NodeAppModel 是大脑，两条 WebSocket 是神经通路，各种 Service 是手脚。安全上也考虑周到——TLS 指纹锁定、权限按需申请、后台自动降频保活。
开发上，SwiftUI + @Observable 驱动 UI，WKWebView 承载主界面（Canvas），所有交互都能透传给 Agent。调试时看 SettingsTab 里的日志和连接状态，基本就能定位问题。
这个 macOS 客户端（OpenClaw.app）是个常驻菜单栏的小工具，既是控制中心，也是功能节点。它让你能用语音唤醒、快捷通话、弹出对话界面，还能远程管理 Gateway，甚至当其他设备（比如手机）要配对时，它来弹窗审批。
silent: true，会通过 SSH 连通性自动验证并批准，否则弹窗让你手动选。openclaw-mac：可命令行调用 Gateway，适合脚本或自动化。OpenClawIPC 让 CLI 或子进程和主 App 直接对话，不走网络。system.run、screen.capture、camera.* 等 node.invoke 操作，依赖系统权限（如录屏、麦克风）。想象它是个“中枢管家”：
openclaw-mac call sessions.list，它能自动发现本地 Gateway 并返回结果，背后用的是 Bonjour（mDNS）发现。.plist 配置、Swift 包管理，结构清晰，扩展性强。这章讲的是 OpenClaw 的 Android 客户端（ai.openclaw.android）是怎么工作的。它不是一个简单的聊天 App，而是作为整个系统里的一个“智能设备节点”，通过 WebSocket 连接到 OpenClaw 的 Gateway，能执行相机拍照、读通知、展示网页交互界面等操作。
node 角色：上报设备能力（比如摄像头、通知），接收并执行远程指令（node.invoke）。operator 角色：负责聊天、配置同步和 A2UI 界面控制。camera、device、notifications、canvas（A2UI）。JpegSizeLimiter 压缩，防止大图压垮连接。你可以把这个 Android App 想成“带 UI 的智能终端代理”。它不只是被动收消息，而是能让远端系统主动调用它的硬件能力。比如：远程拍张照、列出当前通知、甚至在 WebView 里跑交互式网页应用（A2UI）。两个连接分工明确：node 管“我能做什么”，operator 管“我现在说什么”。配对流程像 HomeKit 那种扫码绑定，安全又方便。开发时可以用 pnpm run android:run 一键安装调试，集成测试还能跑真实设备上的能力验证。
这章讲的是 OpenClaw 的安全设计，核心目标是：即使消息来自不可信用户，系统也能安全运行。它覆盖了权限控制、认证机制、沙箱隔离、密钥管理、网络防护等关键环节，整体采用“纵深防御”策略，层层设防。
exec 可用，但 browser、nodes 等高危工具默认禁用。SecretRef 模式引用密钥（如 { $ref: "env/KEY" }），避免明文写在配置里；密钥文件权限设为 0600。openclaw doctor 可检查安全配置，依赖库已修复已知漏洞。你可以把 OpenClaw 想成一个“带门卫的智能办公室”：
openclaw doctor 定期检查配置是否安全，比如密钥权限、认证是否开启等。总之，OpenClaw 的设计是“默认安全”，你不需要一步到位配好所有策略，但上线前一定要检查认证、沙箱和密钥管理。
这章讲的是 OpenClaw 的 security audit 安全检查功能，包括命令行怎么用、检查了哪些项目、内部是怎么工作的，以及发现风险后能怎么自动修复。核心是帮你发现配置中的安全隐患，比如权限太松、暴露在公网、用了危险的 Docker 设置等。
openclaw security audit 命令运行检查，加 --deep 可探测正在运行的服务，加 --fix 能自动修复部分问题。--fix 只做安全的自动修复，比如收紧文件权限、关闭开放群组策略，但不会改密码或网络配置。你可以把 security audit 当成一个“安全体检工具”。它不光看你的配置文件（比如 openclaw.json），还能结合系统环境和运行状态，找出潜在风险。比如：
network=host 或挂载了 /etc？→ 危险，必须警告。它的检查逻辑很细，比如“暴露在公网”不仅看 gateway.bind，还看 Tailscale 是否开了 funnel 模式。很多 warn 会在暴露时升级成 critical。
自动修复 --fix 很克制：只改配置中的 groupPolicy、日志脱敏设置，以及收紧关键文件（如 config、session 文件）的权限，绝不碰密码或 token。
优先处理建议是：先封住入口（认证、访问控制），再修文件权限，最后看模型和插件是否可信。总之，这个命令是你上线前必跑的一环。
这章讲的是 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 网络策略一起用，更安全。
这章是给 OpenClaw 贡献代码的工程师看的开发手册，讲清楚了项目结构、本地开发流程、编码规范、测试和提交 PR 的标准做法。相当于一份“怎么正确参与这个项目”的实操指南。
src/，插件在 extensions/，客户端在 apps/。pnpm install 装依赖，pnpm dev 启动 CLI，pnpm check 检查格式和类型，pnpm test 跑测试。scripts/committer 脚本，保证只提交相关文件。你可以把 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。
如果你要加个新渠道（比如 T@elegrimm），除了写代码，还得去 .github/labeler.yml 加规则，更新文档，确保 UI 和配置都能对上。
总之：结构清晰，工具链统一，提交规范严格——适合团队协作，避免“我本地好好的”这种问题。
这章讲的是 OpenClaw 项目的 CI/CD 流水线设计，重点是如何通过智能判断代码变更范围，跳过不必要的构建和测试任务，从而加快开发反馈速度。它不是简单地“每次提交都跑全套流程”，而是有一套聪明的“该跑哪些任务”的决策机制。
.github/workflows/ci.yml，触发于每次 main 分支推送或 PR。docs-scope），如果不是再分析具体改了哪些模块（changed-scope）。macos、android、windows、skills-python 等平台相关任务。build-artifacts），产物共享给后续任务。detect-secrets、zizmor）独立运行，不被范围检测跳过。你可以把这套 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 既快又稳。
这章讲的是 OpenClaw 项目怎么发版：从版本号怎么定、发版前要检查啥，到怎么打包、发布到 npm、GitHub 和各个应用商店，再到用户怎么更新。核心是确保多平台（macOS、iOS、Android）版本一致、流程自动化、更新可靠。
YYYY.M.D，比如 2026.3.3，beta 版是 2026.3.3-beta.1package.json 里的版本为准，自动推导 Android/iOS/macOS 的构建号npm run release:check 检查版本、changelog、git 状态你可以把 OpenClaw 的发版想象成一条流水线：
先统一版本号，改 package.json，其他平台（Android 的 versionCode、iOS 的 CFBundleVersion）会自动算出来。然后更新 CHANGELOG.md，写清楚这次发版改了啥，尤其是破坏性变更要提醒用户怎么升级。
接着跑 release:check 脚本，确保代码干净、版本对得上、changelog 有写。再本地构建测试一遍，没问题就打 tag 推上去：
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 自动化，减少人为出错。
