OpenClaw 自托管 AI 助手
本专题共 51 篇，依据
官方仓库 docs/ 下的安装、网关、渠道、自动化、概念与插件文档整理。
该项目迭代很快，请以仓库最新内容为准。
OpenClaw 架构总览：网关、Agent、渠道、节点、插件五层各管什么，出问题该往哪查
按官方文档梳理 OpenClaw 的分层边界——一台主机一个网关、所有客户端与节点走同一个 WebSocket 端口、渠道基本都是插件、Agent 运行按会话串行。文中给出一次消息从进入到回复的完整数据流，以及一张按症状定位到层的排查对照表，帮你在报错时先判断该看哪一层的日志。
安装与部署：先选对方式，再谈别的
官方安装页并排摆着安装脚本、本地前缀脚本、npm/pnpm/bun、源码 checkout、Docker，选错的代价不在安装当天而在半年后升级时。这一组还包括 doctor 输出怎么读、树莓派与 Windows/macOS 各自的前置条件，以及更新中断后的分层回滚。
OpenClaw 该用哪种方式装：脚本、npm、Bun、Docker 的前置条件与升级路径对照
OpenClaw 官方文档给了安装脚本、本地前缀脚本、npm/pnpm/bun、源码 checkout、Docker 五条路。这篇按官方文档把每条路的 Node 版本门槛、包管理器的拦路参数、状态目录落点和后续升级方式排成对照表，重点讲清哪些选择会在升级那一步反噬你，帮你第一次就选对，不用装完再拆。
OpenClaw 装不上或装完命令找不到：按官方文档走一遍安装失败排查路径
安装脚本跑完不等于装成功。这篇按 OpenClaw 官方的 troubleshooting 页和安装器内部文档，把安装失败拆成 PATH、npm 权限、Git 缺失、Node 版本、装后自检、插件被拦六类，给出每一类的判断命令、官方日志原文和对应处置，并说明哪些情况官方明确说了不是 OpenClaw 的问题。
openclaw doctor 体检输出怎么读：五种姿态、findings 字段与退出码对号入座
openclaw doctor 一条命令能查网关、渠道、插件、技能、模型路由和配置迁移，但输出很长，第一次看容易不知道从哪下手。这篇按官方文档把 doctor 的五种运行姿态、lint findings 的字段结构、三个退出码的含义拆开讲，再把高频提示逐条对到官方给的修复命令上，最后说清哪些问题 doctor 本来就不负责。
OpenClaw 用 Docker 部署：镜像怎么选、状态存在哪、升级卡住怎么救
按官方文档梳理 OpenClaw 的 Docker 部署链路——setup.sh 与预构建镜像的取舍、离线加载、无人值守 onboarding、bind 模式与 host.docker.internal、必须持久化的目录清单、镜像升级后容器反复重启时的 doctor --fix 救援步骤，以及 ClawDock 辅助命令。
树莓派部署 OpenClaw：型号怎么选、swap 怎么加、SD 卡为什么是最大隐患
OpenClaw 官方文档给树莓派单列了一页部署指南。本文按文档梳理清楚哪些 Pi 型号能跑哪些不建议、为什么必须用 64 位系统、2 GB 以下机器怎么加 swap、如何让网关在退出 SSH 后继续运行，以及编译缓存、状态目录、ARM64 二进制和官方那份故障排查清单分别对应什么问题。
在 Windows 上跑 OpenClaw：Hub、原生 CLI 与 WSL2 三条路怎么选、怎么避坑
按官方 Windows 平台文档梳理三种运行方式的差别：Windows Hub companion 应用装了什么、节点模式与本地 MCP 模式的四种组合、原生 CLI 用计划任务加 vbs 包装启动网关的机制，以及 WSL2 网关在无人登录时自启的两处关键改动、把 WSL 服务转发到局域网的写法和官方给出的排障入口。
OpenClaw macOS 应用要哪些系统权限：屏幕、麦克风、语音、自动化、辅助功能逐项对照
按官方 macOS 文档梳理 OpenClaw 菜单栏应用会向系统申请的五类权限、授权入口在首次运行流程的哪一步、除权限提示外还会弹出的 Keychain 与 Touch ID 场景，以及本地网关与远程网关在权限面上的差别，附一份能力与权限的对照清单。
OpenClaw 更新失败怎么救、回滚分几层、卸载要清掉哪些目录
按官方文档梳理 OpenClaw 的更新中断恢复路径（重跑安装器、EACCES 场景、pnpm 全局组）、代码与状态两层回滚的分界、备份归档能覆盖和覆盖不到的东西，以及卸载时四个 scope、手动删除步骤和三个平台的残留服务清理命令。
网关运行期：起不来、连不上、重启后不对劲
Gateway 是这套系统的中枢，绝大多数「昨天还好好的」都落在这一层：锁文件与端口、health 与 heartbeat 两套检查的区别、重启恢复会保留什么、远程访问的三条路，以及密钥凭据存在哪。
OpenClaw 网关起不来怎么办：锁文件、端口占用与后台进程的三层排查
网关启动失败通常卡在三个地方——状态目录锁、配置锁、端口绑定。本文按官方文档把三层守卫的顺序、各自的报错原文、锁文件存放位置、EADDRINUSE 的重试策略讲清楚，再给出服务托管下 exit 78 的含义、restart 卡住时后台会话的影响，以及一份可以照着敲的命令阶梯。
OpenClaw 网关出问题先开哪个开关：日志级别、--verbose 与诊断导出包的分工
把 OpenClaw 网关的三套可观测手段拆开讲清楚：文件日志由 logging.level 控制、--verbose 只管控制台和 WS 日志、诊断导出与稳定性记录器是另一条线。给出日志文件位置与轮转规则、--ws-log 三档、stability 命令、diagnostics export 的完整参数表，以及导出包里保留和抹掉的字段清单。
OpenClaw 的 health 与 heartbeat 是两回事：一个查网关状态，一个按周期跑 Agent
OpenClaw 文档里 health 和 heartbeat 都能译成「健康检查／心跳」，但一个是只读的探针和快照（不花 token），另一个是定期跑一次完整 Agent 轮次（花 token）。本文按官方文档把两套机制的命令、HTTP 探针、配置字段、响应契约和成本开关分开列清楚，并给出容易混淆的几个判断点。
OpenClaw 网关重启后会话还在不在？哪些状态能自动恢复、哪些直接消失
重启 OpenClaw 网关，正在跑的 Agent 回合会不会丢？官方文档给出的答案是分层的：会话记录、子代理、后台任务、待发消息都落在 SQLite 里能恢复，终端 PTY 一定没了。本文按文档梳理排空预算、中断标记的三个时机、三次续跑预算与墓碑机制，以及崩溃循环断路器为什么会让网关活着但渠道不上线。
OpenClaw 远程访问三条路：SSH 隧道、Tailscale Serve 与直连绑定该怎么选
网关默认只监听回环地址，想从笔记本、手机或另一台机器连上去，官方文档给的是三条路：SSH 端口转发、Tailscale Serve 出一个稳定 wss 地址、以及在可信内网/Tailnet 上直连绑定。这篇把三条路的配置项、凭据取值顺序、安全边界和验证命令一次讲清楚，也讲清楚 Serve 地址本机能开、别的设备超时是怎么回事。
OpenClaw 的密钥与凭据怎么存：SecretRef 四种来源、审计迁移与哨兵机制拆解
把 API Key 从 openclaw.json 里挪走没那么简单。这篇按官方文档梳理 SecretRef 的 env/file/exec/store 四种来源与校验规则、secrets audit/configure/apply 三步迁移门、模型凭据的哨兵注入、共享密钥库的覆盖边界、默认关闭的出口代理，以及 1Password 的两条接入路径，并说清哪些凭据类别根本不在这套机制里。
OpenClaw 一台机器跑多个网关：profile 隔离、端口派生与多租户 cell
同一台主机上开第二个 OpenClaw Gateway，要隔离的不只是端口。本文按官方文档梳理 profile 隔离的五项必唯一配置、base port 派生 browser/CDP 端口的规则、救援机器人的具体命令，以及给互不信任的租户做隔离时为什么必须用 fleet 的 cell 而不是共享一个网关。
渠道接入：微信、企业微信、飞书、QQ、元宝
中文用户最关心的一块。接入的通用流程与配对机制先看第一篇，具体平台各有各的前置条件与文档留白；机器人在群里互相刷屏是独立的一类问题，单独一篇讲三道闸怎么判。
OpenClaw 渠道接入的通用套路：插件安装、配置段落、DM 策略与配对码怎么串起来
把 OpenClaw 官方文档里分散在 channels、pairing、config-channels 三处的接入流程拼成一条线：哪些渠道要装插件、配置段落存在就自动启动是什么意思、dmPolicy 四种取值分别放行谁、配对码 8 位 1 小时过期的规则、Control UI 与 CLI 两条批准路径的差别，以及配对状态落在哪个 SQLite 表里。
OpenClaw 渠道连上了却不回消息：官方排查表按渠道逐条拆解
OpenClaw 官方渠道排查页给的不是泛泛建议，而是一套命令阶梯加八个渠道的故障特征表。本文把这页拆开：先跑哪五条命令、健康基线长什么样、更新后渠道消失该怎么修，以及 WhatsApp、Telegram、Discord、Slack、iMessage、Signal、QQ 机器人、Matrix 各自的症状与对应处理动作。
OpenClaw 接微信：openclaw-weixin 插件的安装、扫码登录与版本对应关系
OpenClaw 的微信能力不在核心仓里，而是靠腾讯维护的外部渠道插件 @tencent-weixin/openclaw-weixin 提供。这篇按官方文档拆开讲：插件是怎么被网关加载的、两种安装方式、扫码登录与多账号会话隔离、配对放行、插件版本与 OpenClaw 版本的对应表，以及几类启动报错的处理动作。
OpenClaw 企业微信渠道怎么配：官方只给三条命令，其余归外部插件管
OpenClaw 的 WeCom（企业微信）官方文档短得反常，只有安装、重启、查状态三条命令，凭据和回调一律指向外部插件包。这篇把这种「薄文档」拆开讲：三条命令各自做了什么、外部插件在网关里的加载与启用链路、装完能自己核实的几个检查点、升级时文档版本怎么对齐，以及连不上时该按哪个顺序排查。
OpenClaw 飞书渠道怎么配：从登录向导到群策略、流式卡片与会话隔离
按官方文档梳理 OpenClaw 接入飞书/Lark 的完整链路：channels login 向导的两条路、dmPolicy 与配对、groupPolicy 与 @ 提及的默认值联动、事件收不到的六步核对、流式卡片与配额开关、群会话作用域，以及每用户独立 Agent 的边界。
OpenClaw 接入 QQ 机器人渠道：从 AppSecret 配置到群聊激活与排查
按官方文档梳理 OpenClaw 的 QQ Bot 渠道怎么落地——插件安装、AppID/AppSecret 的三种存法、群聊 groups 配置项与 commandLevel 分级、allowFrom 与斜杠命令的授权关系、流式回复与语音配置，以及重启后消息会不会丢的入站持久化机制，最后附官方给出的五条排查项。
OpenClaw 元宝渠道怎么配：凭据、私聊策略、群聊 @ 提及与出站队列全解
按官方文档梳理 OpenClaw 接入腾讯元宝机器人的完整配置面：appKey/appSecret 两种录入方式、dm.policy 四种私聊策略与配对审批、requireMention 群聊门槛、merge-text 出站缓冲的三个阈值、多账号与 bindings 多 Agent 路由，以及四类常见故障的官方排查顺序和一张完整配置项默认值表。
OpenClaw 群里两个机器人互相刷屏：bot loop 保护与群消息准入怎么配
两个 bot 在同一个群里你一句我一句停不下来，光靠"别让它说话"是治不好的。这篇按 OpenClaw 官方文档梳理 bot loop 保护的滑动窗口与冷却机制、五级覆盖优先级、支持该守卫的渠道清单，再往上一层讲群消息的三道闸门（groupPolicy、群名单、mention 门控）、mentionPatterns 的误伤范围与作用域收窄写法，以及 visibleReplies 让模型自己决定说不说话的做法。
自动化：定时任务、webhook、hooks 与常驻指令
「为什么到点没跑」是这一块的高频问题。cron 与 heartbeat 的分工、webhook 的入站与出站两条链路、hooks 的 15 个事件键，以及常驻指令的适用边界，都按官方文档逐条对齐。
OpenClaw 定时任务不触发怎么查：从网关进程、时区到被自动禁用的排查路径
定时任务到点没动静，可能压根不是任务写错了。本文按官方 automations 文档梳理一条排查顺序：先分清「没触发」和「触发了但没送达」，再依次核对调度器开关、网关进程、时区、cron 表达式的日/星期或逻辑、整点错峰、连续失败自动禁用、本地模型端点预检导致的 skipped，以及会话归档带来的连带禁用，并给出对应命令。
OpenClaw 定时任务和 heartbeat 到底选哪个：官方五维对照表逐行拆解
同样是「每隔一段时间干点活」，OpenClaw 里 Automations（原 cron）和 Heartbeat 是两套东西：一个精确到点、跑在隔离会话、必留任务记录，一个大约每 30 分钟、跑在主会话、不留任何记录。本文按官方文档的对照表逐行讲清差别，以及 heartbeat 会被自动延后的几种情况和常见的混用分工。
OpenClaw webhook 收不到消息：先分清三条链路，再按注册、鉴权、载荷逐段定位
OpenClaw 文档里有三个东西都叫 webhook——Gateway 的 hooks 入站端点、automations 的出站投递、webhooks 插件的 TaskFlow 入口。它们的配置块、请求头名、失败表现都不一样。这篇按官方文档梳理三条链路各自的注册方式、鉴权头、载荷字段和状态码含义，给出「收不到」时该看哪个配置项、哪条命令。
OpenClaw hooks 怎么用：事件清单、目录结构与"装了不跑"的三种原因
按官方文档梳理 OpenClaw 内部 hooks 的完整用法——十五个事件键分别在什么时候触发、HOOK.md 与 handler 的目录约定、event.messages 为什么大多数事件收不到回复、四个发现来源的覆盖优先级，以及网关默认不加载内部 hook 这个最容易踩的开关，附五个内置 hook 的作用与排查命令。
OpenClaw 常驻指令怎么写：把「每次都要提醒」换成一份带边界的长期授权
拆解 OpenClaw 官方文档里的 standing orders（常驻指令）：四个必填要素、该放在 AGENTS.md 还是单独文件、和 automations 定时任务怎么配合、Execute-Verify-Report 执行纪律、多程序如何分线，以及官方给出的三个完整示例。顺带说清 poll 文档搬到哪去了，别再在自动化目录里找。
机制解读：架构、会话、记忆、模型与插件
排查到最后总要回到机制：Agent 主循环怎么转、会话状态存了什么、三层记忆架构与上下文压缩的关系、多 Agent 与多用户怎么隔离、模型故障转移的判定，以及沙箱与工具策略的边界。
海外三家怎么比？Slack、Telegram、Discord 在两边的接入方式并列
Slack、Telegram、Discord 是两边都支持的三个海外渠道。WorkBuddy 各有独立官方指南（Slack 走 Socket Mode 且要发配对码、Discord 要开三个 Intents）；OpenClaw 把它们列在核心渠道里。本文并列双方官方写明的机制。
接入渠道谁覆盖得广？WorkBuddy 九个平台，OpenClaw 一长串外加插件生态
WorkBuddy 官方支持九个即时通讯平台；OpenClaw 文档列出的渠道更多，还能通过渠道插件扩展。本文并列双方官方文档写明的渠道清单、各自独有的部分、以及接入方式的机制差异，不做优劣判断。
开源自托管还是商业订阅？按四个问题判断你该选哪种形态
WorkBuddy 是商业闭源桌面产品，OpenClaw 是 MIT 开源的自托管网关。本文不比谁更好，而是把两种形态在数据、成本、运维、支持四个维度上的官方事实并列出来，帮你按自己的约束条件判断。
腾讯元宝在两边都能接，但一个是内置集成一个是渠道插件
WorkBuddy 的元宝派接入是产品内置的双向流程，要回 App 点「我已操作」确认；OpenClaw 的腾讯元宝在中文区渠道分组里，走渠道插件路径。本文并列双方官方写明的机制与容易漏的步骤。
微信接入怎么比？WorkBuddy 扫码即用，OpenClaw 走腾讯维护的外部插件
WorkBuddy 的微信助理官方明确无需任何开发凭证、只需扫码；OpenClaw 的微信渠道通过腾讯微信团队维护的外部插件 @tencent-weixin/openclaw-weixin 实现，需要装插件、重启网关、命令行登录。本文并列双方官方文档写明的机制与限制。
OpenClaw 插件体系拆解：能力注册、加载四层与所有权边界，附最小插件从写到装的完整路径
按官方文档讲清 OpenClaw 插件的三件事——插件靠 registerXxx 注册能力、加载分清单发现/启用校验/运行时装载/表面消费四层、一个插件是一家厂商或一个功能的所有权边界。后半段给出 Control UI 与 CLI 两条安装路径、六种安装源的取舍，以及最小工具插件的 package.json、清单、入口代码和 npm-pack 验证步骤。
OpenClaw 的 Agent 循环怎么转：从 agent RPC 到落盘的一整条链路
一条消息进 OpenClaw 之后，要经过 agent RPC 受理、runEmbeddedAgent 排队、工作区与提示词装配、模型推理、工具执行、流式回传、回复整形、写入转录这一串环节。本文按官方文档把每一步拆开，讲清 runId 与 lifecycle 的关系、写入者认领怎么防脏写、四类超时各管什么，以及会话卡住时诊断标签怎么读。
OpenClaw 的队列、插话（steering）与重试：消息挤在一起时它到底怎么排
用户连着发三条消息、Agent 正在跑工具的时候，OpenClaw 不是简单排队等着。本文按官方文档梳理 steer/followup/collect/interrupt 四种队列模式的差别、插话为什么不打断已经启动的工具调用、cap 和 drop 满了丢哪条，以及和队列容易混为一谈的另一层机制——对外请求的重试与退避默认值。
OpenClaw 多 Agent 与专家分线：一个网关跑几个人格，消息怎么路由到对的那个
拆解 OpenClaw 官方文档里的多 Agent 机制——一个 agent 的边界到底包含哪些目录、bindings 按什么优先级选中 agent、agentDir 复用会引发什么凭据事故，以及为什么官方把"专家分线"定义成资源争抢问题而不是"多开几个 agent"。附路径对照表、绑定规则清单与分线契约模板。
OpenClaw 多用户模式与 USER.md 用户模型：共用一个 agent 时谁能看到谁的会话
团队共用一台 OpenClaw 网关，会话归属、在线状态、草稿、轮次归属分别能做到什么，官方为什么反复强调这些都不是安全边界；以及 USER.md 怎么把稳定偏好写成指令、偏好变了怎么就地取代，和 MEMORY.md、日常记忆的分工怎么划。
OpenClaw 会话模型讲清楚：消息落到哪个 session、主会话汇进来什么、状态怎么不串
按官方文档梳理 OpenClaw 会话三层：消息路由（私聊、群、cron 各落到哪个 session）、主会话汇聚了什么、状态感知的信号日志与 watcher 通知。附 dmScope、groupScope、reset、maintenance 配置对照表与排查命令。
OpenClaw 活跃记忆与上下文引擎：每一轮到底往上下文里塞了什么
同一套记忆库，为什么有的回复能想起旧事、有的想不起？答案在活跃记忆（active-memory）和上下文引擎（contextEngine）这两层。本文按官方文档梳理 escalate 触发条件、四个装配生命周期点、queryMode 与 promptStyle 的取舍、模型解析链、冷启动超时，以及哪些场景根本不会跑。
OpenClaw 记忆架构拆解：分层文件、来源标记与两条召回通道各自负责什么
把 OpenClaw 官方文档里的记忆机制按「写在哪、谁能写、什么时候被塞进上下文」三条线拆开讲清楚：四个记忆文件与五层 tier 的分工、SQLite 里的来源标记为什么无法被正文伪造、dreaming 作为唯一晋升入口串起来的两道闸、零模型调用的一号召回通道与升级子代理的二号通道、项目作用域标注，以及内置 SQLite 引擎的检索组成与它明确不做的那几件事。
OpenClaw 里工具被拦住了：沙箱、工具策略、elevated 三者的边界怎么分
同样是「工具用不了」，在 OpenClaw 里可能是沙箱模式、工具 allow/deny 策略、elevated 提权三套机制中的任意一套在起作用，改错配置键就白折腾。本文按官方文档梳理三者各管什么、默认值是多少、配置键分别在哪，并转述文档自己声明的边界与不保证之处。
OpenClaw 模型供应商怎么接、挂了怎么自动转移：从 provider/model 到 fallback 链
把 OpenClaw 官方文档里模型供应商接入与故障转移这条线拆开讲：模型引用格式与配置键、官方插件供应商与自定义 models.providers 的分工、API key 轮换触发条件、鉴权档案轮换与模型 fallback 的两级顺序、冷却与计费禁用的时长规则，以及哪些报错会推进 fallback、哪些不会。
OpenClaw 上下文压缩与会话修剪：compaction 和 pruning 到底谁在动你的历史
长会话撞上下文上限，OpenClaw 有两套机制在收拾场面：compaction 摘要旧对话并写进 transcript，pruning 只在内存里裁工具结果。本文按官方文档拆开两者的触发条件、切分点规则、safeguard 质量校验、摘要模型覆盖、记忆 flush、字节守卫，以及 Anthropic 自动默认值表。
Paperclip 接 OpenClaw 当执行层：邀请提示词、网关 preflight 与两次批准
按 Paperclip 官方的 OpenClaw onboarding 检查表和 Docker 指南，梳理这条对接链路到底分几步：怎么用受控端点生成邀请提示词、创建出来的 agent 为什么必须是 openclaw_gateway、tokenLen 和 devicePrivateKeyPem 要核对成什么样、首跑报 pairing required 该去哪批准，以及容器里 127.0.0.1 指向自己带来的回调坑。
QQ 接入怎么比？WorkBuddy 要实名且 AppSecret 只有一次机会
两边都能接 QQ，但 WorkBuddy 侧有两条硬约束——QQ 开放平台要求账号实名认证，且官方明确 AppSecret 不支持明文保存、二次查看将强制重置。本文并列双方官方写明的机制与前提。
WorkBuddy 的自动化和 OpenClaw 的 Cron 怎么比？一个图形配置，一个网关调度器
WorkBuddy 的自动化是客户端里的表单配置、按订阅档位限数量；OpenClaw 的 Cron 是 Gateway 网关的内置调度器，任务持久化到 SQLite、用命令行创建。本文并列双方官方文档写明的机制，不做优劣判断。
WorkBuddy 和 OpenClaw 能互相替代吗？先看你用的是哪几项能力
两者形态不同，能不能替代取决于你实际依赖哪些能力。本文把常见的十项使用需求逐条对照双方官方文档写明的支持情况，给出可以按图索骥的判断表，不做整体优劣判断。
WorkBuddy 和 OpenClaw 是一类东西吗？两边官方文档的定位、部署方式与费用结构并列看
WorkBuddy 是腾讯云 CodeBuddy 团队的商业桌面 AI 工作台，OpenClaw 是 MIT 许可的自托管 Gateway 网关。两者常被放在一起讨论，但形态前提完全不同。本文只并列双方官方文档写明的定位、系统要求、安装方式、渠道覆盖与费用结构，各标来源与核对日，不做优劣判断。
WorkBuddy 免部署装了就用，OpenClaw 要自己跑一个网关——两种运维负担并列
WorkBuddy 官方产品页写的是「免部署·安装即用」；OpenClaw 官方文档列了 Ansible、Docker、Kubernetes 以及十余种云托管方式。本文并列双方官方文档写明的安装、部署与运维要求，帮你判断你愿意承担哪一种。
想把 AI Agent 真正接进日常工作流？
从工具部署到工程化落地，站内有成体系的 AI Agent 学习路线。