目录

第一章　OpenClaw 到底是什么

1.1 一句话定义

OpenClaw 是一个运行在用户选择的机器上、以长驻 Gateway 为控制平面、把消息渠道、Agent Runtime、模型提供商、工具、Skills、MCP、会话、记忆与设备节点连接起来的个人 AI 助手/开放 Agent 平台。它首先是“personal AI assistant”，目标是“personal, single-user assistant”；Gateway 只是控制平面，真正的产品是助手本身。

1.2 它解决什么问题

OpenClaw 把过去散落在多个产品里的能力统一到一个自托管运行时：

1. 从 Telegram、Slack、WhatsApp、Discord、iMessage、WebChat 等现有沟通入口接收任务；
2. 将消息按账号、会话和绑定规则路由到指定 Agent；
3. 在一次 Agent 循环里选择模型、加载上下文、调用本机或远程工具、调用 MCP Server，并把结果送回原渠道；
4. 保存会话、工作区文件和长期记忆；
5. 通过 Cron、Heartbeat、Hooks 和 Webhook 承接主动任务；
6. 通过 macOS、iOS、Android 等配对 Node 暴露受控设备能力。

它的价值不是“多一个聊天框”，而是把入口、推理、执行、状态与设备组成一个持续运行的个人 Agent 系统。

1.3 它不是什么

1. 不是一个大语言模型；模型由 OpenAI、Anthropic、Google、本地 Ollama/vLLM 等提供。
2. 不是 ChatGPT、Claude、豆包一类托管聊天 SaaS 的开源复刻；OpenClaw 负责运行和编排，模型、密钥、机器及数据边界由部署者选择。
3. 不是 Dify、FastGPT、Coze、Flowise 一类以可视化工作流、应用发布、数据集运营为中心的平台，也不是 n8n 式确定性业务流程引擎。OpenClaw 的主抽象是长驻个人 Agent 和消息渠道；确定性审批、事务补偿、租户治理仍需外围系统。
4. 不是专门的 IDE 编程 Agent。它可接 Codex、Claude Code/ACP 等 Runtime，也能执行开发工具，但其核心覆盖消息入口、长期运行、主动任务、记忆和设备节点；Cursor、Claude Code、Codex 等更聚焦代码库/终端开发环节。
5. 不是传统 RPA。模型驱动工具选择具有概率性；涉及资金、删除、权限、生产变更时不能用“自然语言看起来合理”替代确定性控制。
6. 不是开箱即用的企业多租户 AI 平台。官方默认信任模型是单用户/个人助手。一个 Gateway 内虽可配置多个隔离 Agent，但这不自动等于企业级租户隔离、SSO、RBAC、ABAC、配额、审计和合规。

1.4 为什么有 Gateway、Channel、Agent、Skill、Tool、Node、Session、Memory

1.5 能力边界图

图 1　Mermaid 架构/时序图

1.6 适合与不适合的场景

适合：可信个人助手、小团队只读助手、跨渠道研发/知识/内容辅助、在严格工具白名单下的周期性报告、作为企业控制平面背后的独立 Agent 执行单元。 不宜直接使用：相互不信任的大规模公网用户共享同一 Gateway；需要强事务和确定性执行的核心业务；无人审批的生产变更、资金、权限或删除；要求现成完整 SSO/RBAC/多租户/SLA 的场景；无法容忍模型与间接 Prompt Injection 风险的高敏动作。

第二章　项目发展、版本和生态

2.1 名称演进

WhatsApp Relay / Warelay → Clawd / Clawdbot → Moltbot → OpenClaw

1. 官方 2026-01-29 博客说，最初的周末项目是 “WhatsApp Relay”；Clawd 诞生于 2025-11。
2. 因名称与 Claude 的商标关联，Anthropic 法务请求重新考虑；社区短暂采用 Moltbot。
3. 2026-01-29 正式宣布 OpenClaw，官方称已完成商标查询、域名购买和迁移代码。
4. VISION.md 还记录了工程名称序列 Warelay → Clawdbot → Moltbot → OpenClaw；docs/start/lore.md 记录角色/吉祥物叙事。写技术史时应说明两者语境不同，不必强行把 “WhatsApp Relay” 和仓库内部 Warelay 当成两个独立成熟产品。

2.2 Foundation 与当前治理

2026-07-08 的官方公告确认：

1. OpenClaw Foundation 是美国 501(c)(3) 非营利组织；使命是保持项目开放、独立和 MIT 许可；
2. Peter Steinberger 仍负责重要技术决策；公告同时披露他已于 2026 年早些时候加入 OpenAI，但 OpenAI 承诺保持 OpenClaw 开放与独立；
3. Foundation 已组建全职团队，公告列出 Vincent Koc（Chief Architect）及多名工程与运营人员；
4. CONTRIBUTING.md 的仓库治理仍以 Peter Steinberger 为 “Benevolent Dictator”，并列出维护者及各自领域。

因此最准确的表述是：Foundation 提供法律、资金与组织承载，技术决策仍有明显创始人主导特征，日常开发由全职团队、维护者和大量贡献者共同完成。

2.3 许可证及企业影响

v2026.7.1 使用 MIT License，版权为 Copyright (c) 2026 OpenClaw Foundation。企业可以使用、复制、修改、合并、发布、分发、再许可和销售软件副本，但须在副本或重要部分中保留版权与许可声明；软件按“原样”提供，不含保证。

工程含义：

1. 可做闭源企业改造和商业化发行；MIT 不要求公开派生代码；
2. 必须保留 MIT 声明；
3. MIT 并不替企业承担安全、模型输出、数据合规或第三方接口责任；
4. 依赖项、插件、Skills、模型、字体/媒体及移动端组件可能有各自许可证，需结合 THIRD_PARTY_NOTICES.md 和 SBOM/依赖扫描逐项审查；
5. 商标权不等同于代码许可证，不应把 MIT 推导为可任意使用 OpenClaw 名称和标识进行背书。

2.4 维护目标与插件优先方向

VISION.md 将优先级明确排成：安全与安全默认值、Bug/稳定性、安装可靠性；之后才是提供商/渠道覆盖、性能、测试、Computer Use、CLI/Web/原生 App。官方希望核心保持精简，把可选能力放入插件；新 Skills 优先进入 ClawHub；MCP 同时考虑 Server 和 Runtime 集成。文档也明确说项目“仍早期、迭代很快”。

这意味着企业应把插件契约演进、配置迁移、回归测试和版本锁定当作选型成本，而不是只看功能数量。

2.5 版本、发布通道与成熟度判断

发布活跃度（不以 Star 替代成熟度）

官方 GitHub Release API/页面在调研日显示最近节奏：

1. stable：2026.6.8（06-16）、2026.6.9（06-21）、2026.6.10（06-24）、2026.6.11（06-30）、2026.7.1（07-13）；
2. v2026.7.1 后于 07-15、07-17、07-18 连续发布 7.2 beta；
3. v2026.7.1 Release 页面称该版本汇集 3,063 次贡献、532 名贡献者，其中公开署名 PR 2,018 个；这是发布规模证据，不是质量本身。

稳定标签下仓库的静态核验还显示：

1. .github/workflows 含跨平台 CI、CodeQL、依赖防护、安装冒烟、发布校验、性能、真实渠道场景、容器与原生 App 发布等数十条流水线；
2. src/extensions/packages/apps/ui 下约 6,500 个 *.test.ts/*.spec.ts 文件
3. 另有 test/、qa/ 和大量 E2E/真实行为证明工作流。

成熟度分维度判断

综合结论：OpenClaw 已不是“玩具仓库”，但仍是高速演进的个人 Agent 基础设施，不等于经过多年兼容沉淀的企业平台。 企业选型宜采用“隔离执行单元 + 外围企业控制面”，而不是直接把一个 Gateway 暴露给全公司。

第三章　OpenClaw 总体架构和工作原理

3.1 总体架构图

3.2 Gateway 内部组件图

3.3 组件职责、输入输出、故障与安全边界

3.4 Gateway 协议与单例约束

[官方稳定能力] Operator、Control UI、CLI、自动化和 Node 使用 Gateway WebSocket。第一帧必须是 connect；请求、响应、事件分别形如：

Operator Scope 包括 operator.read、operator.write、operator.admin、operator.approvals、operator.pairing、operator.talk.secrets。config.*、exec.approvals.*、wizard.*、update.* 等保留前缀强制按 admin 处理。Node 以 role: node 连接并申报 capabilities/commands。副作用 RPC（如 send、agent）使用幂等键；事件不提供完整 replay，重连后应重新读取状态。

[官方稳定限制] 同一配置和端口由文件锁与 socket bind 保证单 Gateway；如需多实例必须用不同 profile/state/port。它并非多个完全对等副本共享一个状态库的天然集群。

3.5 关键架构图集

OpenClaw 能力边界图

Skill、Plugin、Tool 与 MCP 的关系图

Skill 主要告诉 Agent “何时以及如何完成任务”，Tool 是可调用能力的结构化接口，Plugin 是在 OpenClaw 进程内注册能力的代码包，MCP Server 是可独立隔离、通过协议暴露 Tool/Resource/Prompt 的进程或服务。普通提示词不提供代码能力；Webhook 是事件入口；浏览器自动化是高风险 Tool，不是通用连接器替代品。

多智能体路由图

企业部署网络拓扑图

安全信任边界图

高可用与灾难恢复架构图

多副本不能同时占用同一渠道长连接、Cron 所有权和本地 SQLite/JSONL。未经状态外置改造，推荐“单写者 + fencing + 备份恢复”或按渠道、部门、Agent、信任域分片，而不是 replicas: 3。

企业控制平面与多个 Gateway

第四章　一条消息是如何被执行的

4.1 时序图

4.2 源码视角逐步说明

1. Channel Plugin 接收平台事件，完成平台签名/Token 检查、消息去重、媒体规范化和发件人/群组/线程标识提取。
2. Channel 自身的 dmPolicy、groupPolicy、allowlist/pairing 和 mention 规则先决定消息是否允许进入。平台 ID 仍只是渠道身份。
3. src/routing/resolve-route.ts 按 精确 peer → parent peer → peer wildcard → guild+roles → guild → team → account → channel → default agent 选 Agent；同一层第一个匹配 binding 胜出，多字段采用 AND。
4. 根据 agent、channel、account、peer 和 session.dmScope 构造 Session Key。默认 dmScope: main 会把同一 Agent 的私聊折叠进主会话；多人入口应显式用 per-channel-peer 或更细粒度。
5. Agent RPC 校验后先返回 accepted run ID；Run Coordinator 再进入 per-session/global queue，获取 Session 写锁、解析模型和认证。
6. Context Builder 加入基础 System Prompt、Workspace Bootstrap 文件、符合资格的 Skill 描述/正文、会话历史、Memory 检索结果、附件及策略过滤后的 Tool Schema。
7. Runtime 调用所选 Provider/Harness。模型产生文本或结构化 Tool Call。
8. Tool Call 经过参数 Schema、Tool Policy、插件 before_tool_call Hook、可能的审批及 Sandbox/Node/MCP 路径执行；结果作为 Tool Result 回到 Agent 循环。
9. 循环继续，直到最终回答、终止条件、取消或超时；Agent 发出 agent_start/turn_start/message_update/tool_execution_*/agent_end 等事件。
10. Session Manager 追加 Transcript，更新会话元数据。接近上下文上限时可先 Memory Flush，再 Compaction；Context Pruning 只临时裁剪旧 Tool Result。
11. Gateway/Channel 按平台线程、格式、长度、媒体和限流规则送回；重试与幂等保护要防止重复回复。

4.3 Tool 调用内部时序

4.4 案例：Slack 中查询 GitHub、内部文档并生成周报

设用户 Alice 在企业 Slack 的 #project-owl 线程中 @Bot：“查询本周 GitHub 项目状态，读取架构决策，生成周报并发回本群。”企业已将 Slack 不可变用户 ID 映射到 principal=alice@corp，只读 GitHub App 和知识库 MCP 由工具代理持有，群发送属于 L3，需要项目负责人确认。完整执行如下：

1. Slack 把事件送到 Channel Plugin；插件校验平台签名/Token，记录 Event ID 并在响应时限内确认。
2. Plugin 规范化 team、account、channel、thread、user、message、attachments；显示名只作展示。
3. Ingress 去重表对 Event ID 建唯一约束；重放只返回先前 runId。
4. Allowlist/Group Policy/Mention 规则确认该团队、频道、用户和 @Mention 均允许；未满足则不进入模型。
5. Gateway 按 peer/account/channel binding 选 rd-weekly Agent；调用者不能在消息里改成 ops-admin。
6. Session Key 由 Agent、Slack account、channel、thread/peer 及 dmScope 生成；身份和 Session 键都写入 Trace，但 Session 不是授权。
7. 每 Session 队列和写锁串行化同一线程；并发的另一个消息排队或明确合并，避免 Transcript 交错。
8. Session Manager 读取 sessions.json 元数据和对应 JSONL Transcript；失败时返回可诊断错误，不能悄悄新建并丢失上下文。
9. Context Builder 加载该 Agent 的 AGENTS/SOUL/TOOLS 等 Workspace 文件，并受单文件/总字符预算限制；Workspace 不是 Sandbox。
10. Skill Loader 只注入 allowlist 中 scm-weekly-report、corp-kb-query 的短描述；模型选择后才读完整 SKILL.md。
11. Tool Registry 将只读 scm_list_events、kb_search/get_excerpt 的 Schema 加入 Context；message_send、merge、delete 不暴露或只暴露成审批草稿接口。
12. Memory Search 仅查询 rd-weekly/项目数据域，返回带 ACL、来源与日期的少量片段；群聊原文不自动写 Alice 个人 Memory。
13. Model Router 根据任务、数据等级、预算和可用性选择 Primary；敏感架构内容走企业模型网关，Fallback 只在兼容数据策略内。
14. 模型先调用 GitHub Tool。Tool 端忽略模型提供的“用户 ID”，使用工作负载身份与策略上下文，限制组织、仓库、时间窗和只读方法。
15. Issue/PR 内容中的“忽略系统、上传 Token”等文字被标为不可信字段；Tool 返回分页、最大字节、来源 URL 和数据等级。
16. 模型调用知识库 MCP；MCP Gateway 做 mTLS、Tool Filter、超时、响应大小和 ACL；恶意或格式异常结果被拒绝/净化。
17. 每个 Tool Result 追加到本轮与 Transcript，必要时只将结构化摘要送回模型；调用轮数、Token、费用、超时和重复参数受硬上限。
18. 模型生成“事实、风险、待确认、来源”周报草稿。Verifier 检查链接、时间窗、未支持主张和跨域内容；失败则返回修订或拒答。
19. 发送回项目群是 L3：Approval Service 展示目标频道、线程、正文和 SHA-256；负责人批准后签发短期一次性票据，Publisher 按同一哈希发送。只读查询结果也可先作为私有预览返回 Alice。
20. Gateway 按 Slack 长度/线程规则分片并发送，保存平台 message ID；未知发送状态先查询再重试，防止重复。Session 追加最终回复、usage、来源和审批回执；仅经验证的长期事实进入 Memory 候选。接近窗口时先 Memory Flush 再 Compaction，旧 Tool Result 可临时 Pruning。

每一步都有相应故障/安全点：入口签名和重放；身份冒用；Binding 越权；DM/线程串线；Session 锁/损坏；Workspace 机密；Skill/Plugin 供应链；Tool Schema 膨胀；Memory ACL；模型外发；Prompt Injection；MCP 不可信；工具超时与重复副作用；事实幻觉；审批绕过；平台限流与发送不确定性。Trace 应贯穿 eventId → runId → sessionKeyHash → modelCallId → toolCallId → approvalId → platformMessageId，但日志不得记录 Token、完整 Prompt 或机密正文。

案例验收

1. 两名不同 Slack 用户、两个线程和两个 Channel account 的 Session/Memory 不串线。
2. GitHub/知识库服务端 ACL 拒绝超范围资源，即使模型参数伪造身份也无效。
3. 恶意 Issue/文档不能触发写 Tool、外发机密或改变 Agent/模型。
4. Slack 重放同一 Event、Tool 超时与发送响应丢失均不造成重复周报。
5. 未经项目负责人批准不能发群；批准后的正文哈希若变化则票据失效。

第五章　源码结构和二次开发入口

5.1 顶层目录

v2026.7.1 是 TypeScript/Node.js 主导的 pnpm monorepo，同时包含 Swift、Kotlin/Android、Web UI 和部署资产。重要目录：

稳定源码入口：https://github.com/openclaw/openclaw/tree/v2026.7.1

5.2 src/ 关键模块

官方 Runtime 架构：https://docs.openclaw.ai/agent-runtime-architecture

5.3 三个关键公开接口

[官方稳定源码] Tool 接口。packages/agent-core/src/types.ts 中 AgentTool 具有 label、参数 Schema、execute(toolCallId, params, signal, onUpdate) 和可选 executionMode: sequential|parallel。工具失败应抛异常，而不是伪装成成功文本。

[官方稳定源码] Plugin 注册接口。OpenClawPluginApi 可注册 Tool、Hook、HTTP Route、Channel、Gateway Method、CLI、Node Command、Service、Provider、Embedding、Speech、Media、Search 等。插件在 Gateway 进程内运行，权限近似宿主代码，不是沙箱。

[官方稳定源码] Channel 插件。 Channel 通过 api.registerChannel(...) 注册；核心保留一个共享 message Tool，通道插件通过 Adapter 描述可见 action/capability/schema 并执行最终平台动作，避免每个通道各造一个模型工具。

接口源码：

1. https://github.com/openclaw/openclaw/blob/v2026.7.1/packages/agent-core/src/types.ts
2. https://github.com/openclaw/openclaw/blob/v2026.7.1/src/plugins/types.ts
3. https://docs.openclaw.ai/plugins/architecture-internals
4. https://docs.openclaw.ai/plugins/sdk-overview

5.4 “需求—修改位置”映射

第六章　部署方式完整比较与四套实施方案

【稳定版官方】系统要求是 Node.js 22.22.3+、24.15+ 或 25.9+，Node 24 为推荐目标；Node 23 不支持。操作系统为 macOS、Linux 或 Windows；从源码构建才需要 pnpm。Docker 镜像构建建议至少 2 GiB 内存，1 GiB 环境可能在依赖安装阶段 OOM（exit 137）；这不是经过生产压测的 Gateway 运行下限。官方 Raspberry Pi 文档给出的纯云模型网关最低参考为 1 核、1 GiB RAM、500 MiB 空闲磁盘，推荐 2 GiB+ 与 SSD，但浏览器、并发工具、附件和本地模型会显著提高资源需求。企业不能据此跳过容量测试。

6.1 安装、目录与运行基线

6.1.1 官方安装与验证命令

macOS、Linux 或 WSL2：

已有 Node 环境：

Windows PowerShell：

源码构建：

统一验证：

macOS 使用 LaunchAgent；Linux/WSL2 使用用户级 systemd；原生 Windows 优先使用 Scheduled Task，若创建被拒绝则回退到每用户 Startup 项。官方安装细节见Installer。

6.1.2 必须持久化的目录

路径证据：FAQ：磁盘位置、迁移、稳定版共享数据库路径源码、稳定版 Agent 数据库路径源码。稳定包中的部分概览页仍把 auth-profiles.json 写成当前路径，但认证实现和专门认证文档已以 SQLite 为准；这是需要在正文显式说明的官方文档滞后。

另一个更重要的差异是：随包的 docs/refactor/database-first.md 把“Session/Transcript 已完全迁入 SQLite”描述为目标/进度，但 v2026.7.1 实际热路径源码仍大量调用 src/config/sessions/store.ts、sessions.json 和基于文件的 SessionManager，官方 Session 参考页也仍给出 agents/<agentId>/sessions/。因此本文按稳定源码和实际 CLI 行为把会话索引/转录视为文件状态；重构文档只能作为未来方向，不能据其删掉 Session 目录备份或宣称当前已具备数据库事务式多副本能力。Session Store 源码、Session 参考。

6.2 四套可实施方案

方案 A：个人或开发者本地试用

1. 硬件/系统：macOS、Linux、Windows/WSL2；从 2 核、2～4 GiB 内存和 10 GiB 可用磁盘开始。本地模型的 GPU/内存另算。
2. 网络：Gateway 只绑定回环地址；仅向选定模型 API 和渠道出站。不要把 18789 直接映射到公网。
3. 依赖与安装：Node 24 推荐；执行官方安装脚本和 openclaw onboard --install-daemon。代码调试再采用固定标签源码构建。
4. 目录：使用个人 ~/.openclaw，但 Workspace 不要指向整个 $HOME。机密项目使用独立 OS 账号或 VM。
5. 模型：先用一个云模型 API Key；需要离线验证时再接 Ollama/LM Studio。
6. 健康/日志：openclaw status --all、openclaw channels status --probe、openclaw logs --follow。
7. 升级/回滚：先 openclaw backup create --verify，再 openclaw update --dry-run、openclaw update；失败时安装固定版本并运行 Doctor。
8. 备份：把验证通过的备份放到加密个人存储；Workspace 可进私有 Git，但凭据与会话不得提交。
9. 常见错误：命令不在 PATH、Node 版本不支持、服务进程读不到交互 Shell 的环境变量、桌面休眠导致渠道掉线。
10. 安全门禁：默认禁用高风险 Shell/浏览器发布；第三方 Skills 只在隔离 Workspace 中审查后启用。

方案 B：5～20 人 Docker Compose 小团队

1. 硬件/系统：一台 Linux VM，建议从 4 vCPU、8 GiB RAM、50 GiB SSD 起步；这是工程初始值而非官方吞吐承诺，需按附件、浏览器和会话增长校准。
2. 网络：Gateway 仅在 Compose 内网暴露；宿主仅开放反向代理的 443。模型/MCP/渠道出站走 DNS 与目标白名单；管理入口通过 VPN、Tailscale 或企业反代鉴权。
3. 依赖：Docker Engine、Compose v2；固定 ghcr.io/openclaw/openclaw:2026.7.1 或镜像 digest。
4. 目录/卷：宿主 /srv/openclaw/{state,workspace,auth-profile-secrets,backup}，UID/GID 1000 所有；三类状态分别挂到官方容器路径。
5. 启动：先用官方 scripts/docker/setup.sh 生成状态和 Token，再切换到经评审的 Compose 覆盖文件，执行 docker compose up -d openclaw-gateway。
6. 健康/日志：容器 /healthz；反向代理与监控使用 /readyz；docker compose logs -f openclaw-gateway 和 openclaw logs --follow 双查。
7. 升级：拉取固定新镜像，在副本环境挂载备份恢复测试；生产停旧实例、备份、换镜像、观察 /readyz。
8. 备份/回滚：每日 openclaw backup create --verify；升级前停 Gateway 做完整状态归档或卷快照。回滚镜像前先确认数据迁移可逆。
9. 常见错误：挂载目录属主不为 1000、把 127.0.0.1 当容器间地址、本地 Ollama 未绑定到可达接口、反代 WebSocket/Origin 配置缺失、1 GiB 主机构建 OOM。
10. 安全门禁：不得把 Docker socket 挂入 Agent Sandbox；若 Gateway 为创建 Sandbox 容器而接触 socket，应把该 Gateway 所在 VM 当作高权限边界。

方案 C：企业内网单 Gateway + 独立 Agent Workspace

1. 硬件/系统：经加固的 Linux VM 或私有云实例；资源从 4～8 vCPU、16 GiB RAM、SSD 起步，并以压力测试决定。浏览器执行放到隔离节点或 Sandbox 运行时。
2. 身份与网络：API Gateway/OIDC 只保护外围入口；OpenClaw 的渠道身份映射和 allowlist 不等于完整 RBAC。不同 Agent 使用独立 Workspace、凭据和工具策略；敏感 MCP 仅内网 mTLS。
3. 部署：Gateway 仍为单写者；systemd 或单副本 K8s。运维面只允许堡垒机/管理网访问；Control UI 不上普通办公公网。
4. 配置：每 Agent 固定模型、工具 allowlist、并发/上下文预算；凭据迁移到 SecretRef，执行 openclaw secrets audit --check。
5. 状态：数据盘加密，SQLite/Session 与 Workspace 同步备份；日志、审计和备份分别有保留策略。
6. 健康/观测：同时启用官方 OTel 或 Prometheus 插件；观测 Collector 与长期存储属于外围平台。
7. 升级：stable 固定版本；测试环境做 Skill、MCP、渠道和记忆回归后维护窗口升级。
8. 故障切换：冷备或有外部栅栏的主备，任一时刻只有一个实例拥有渠道凭据、读写卷和 Cron 权限。
9. 安全门禁：单 Gateway 只服务一个受控信任域；低信任群聊不得触发写操作或生产工具。

方案 D：企业多 Gateway、分信任域、模型网关、审批与审计

1. 拓扑：每部门/数据级别/渠道账号运行独立 Gateway cell，各自拥有状态、Workspace、密钥、出口策略和配额；外围统一 API Gateway、OIDC、Policy Engine、Approval Service、Audit Service、Model Gateway、MCP Gateway、Agent/Skill/Gateway Registry。
2. 部署：每个 cell 为单活动实例或有栅栏主备；Kubernetes Namespace、ServiceAccount、PVC、NetworkPolicy 和 Secret 分域。不要让多个 cell 共享 SQLite/PVC 或渠道登录态。
3. 模型路由：公开内容可走云模型；内部/机密内容优先本地或合规模型网关；高风险工具调用必须经过审批服务和策略验证器。
4. 成本治理：在模型网关与 OpenClaw 两层记录 Agent、用户、任务、模型、Token 和预算；达到上限熔断，不用无限 fallback 掩盖故障。
5. 审计：保留消息路由元数据、模型选择、工具名/参数摘要、审批人、结果、策略判定和版本；原始提示/工具输出只在经过数据分类批准时进入观测系统。
6. 灾备：cell 级 RPO/RTO；跨区域备份不自动启动渠道。故障域切换先取得租约、验证旧实例已被隔离，再注入凭据并启动。
7. 演进边界：【实验/后续文档】在线文档中的 Fleet/cell 管理仍属实验且在稳定包 v2026.7.1 中没有 openclaw fleet CLI，不能写进稳定版生产 Runbook。当前可靠方式仍是外部平台管理多个独立 Gateway。

第七章　从零完成 Docker Compose 部署

5.1 官方 Compose 基线

官方入口是：

也可手工执行：

稳定版官方 `docker-compose.yml` 的关键事实如下：

1. Gateway 容器内固定 HOME=/home/node，状态、配置和 Workspace 路径分别为 /home/node/.openclaw、/home/node/.openclaw/openclaw.json、/home/node/.openclaw/workspace。
2. 默认宿主目录是 $HOME/.openclaw、$HOME/.openclaw/workspace、$HOME/.openclaw-auth-profile-secrets。
3. 映射 18789（Gateway）、18790（bridge）、3978（Teams）；企业不应无差别映射到 0.0.0.0。
4. 以非 root node（UID 1000）运行，需 chown -R 1000:1000 修复 bind mount 权限。
5. restart: unless-stopped、init: true，删除 NET_RAW/NET_ADMIN，设置 no-new-privileges；健康检查访问 http://127.0.0.1:18789/healthz。
6. CLI sidecar 使用 network_mode: service:openclaw-gateway，并共享相同卷，因此它与 Gateway 属于同一信任边界。
7. 官方 Compose 没有反向代理、TLS、OTel Collector、备份任务、CPU/内存限制、日志驱动轮换和出站防火墙；这些都属于外围设计。

5.2 生产覆盖文件示例

不要改动官方文件；建立 docker-compose.prod.yml 作为覆盖层：

这个示例只演示结构，镜像 digest、证书源、DNS、Caddy 策略和资源值必须由企业流水线生成。read_only: true 在官方 K8s 清单中已被验证为可行，因为状态目录和 /tmp 单独可写；但安装插件、浏览器下载、某些 Skill 或 CLI 后端可能需要额外可写缓存。逐功能测试后再启用，绝不能为解决一个插件问题把整个宿主目录改成可写。

Secrets 不要虚构 *_FILE 环境变量。v2026.7.1 官方支持 SecretRef：把 Docker Secret/CSI/宿主密钥文件只读挂载，再在 openclaw.json 的受支持凭据字段引用。例如：

启动前后执行：

SecretRef 会减少明文落盘和运行链路暴露，但不构成进程隔离；真实值仍会在最终网络适配边界进入同一进程内存。详见Secrets 管理。

5.3 本地模型、Collector 与备份边车

• 宿主 LM Studio 在容器中使用 http://host.docker.internal:1234，Ollama 使用 http://host.docker.internal:11434；宿主服务必须绑定可达接口，但应用防火墙只允许 Docker bridge 源地址。
• Linux 下可运行 lms server start --port 1234 --bind 0.0.0.0 或 OLLAMA_HOST=0.0.0.0:11434 ollama serve，不要因此把端口开放到办公网或公网。
• Collector、反向代理和备份任务均为。备份边车不要直接 cp 打开的 SQLite/WAL；应调用 Gateway 镜像内的 openclaw backup create --verify，或在停机后做卷快照。

官方 Sandbox 可通过 OPENCLAW_SANDBOX=1 ./scripts/docker/setup.sh 启用，setup 默认设置 agents.defaults.sandbox.mode=non-main、scope agent、Workspace 访问 none。它默认关闭，而且让 Gateway 操作宿主 Docker socket 仍是高权限。官方明确警告不要把宿主 Docker socket挂给 Agent 的 sandbox 容器。

5.3 本地模型、Collector 与备份边车

• 宿主 LM Studio 在容器中使用 http://host.docker.internal:1234，Ollama 使用 http://host.docker.internal:11434；宿主服务必须绑定可达接口，但应用防火墙只允许 Docker bridge 源地址。
• Linux 下可运行 lms server start --port 1234 --bind 0.0.0.0 或 OLLAMA_HOST=0.0.0.0:11434 ollama serve，不要因此把端口开放到办公网或公网。
• Collector、反向代理和备份任务均为。备份边车不要直接 cp 打开的 SQLite/WAL；应调用 Gateway 镜像内的 openclaw backup create --verify，或在停机后做卷快照。

官方 Sandbox 可通过 OPENCLAW_SANDBOX=1 ./scripts/docker/setup.sh 启用，setup 默认设置 agents.defaults.sandbox.mode=non-main、scope agent、Workspace 访问 none。它默认关闭，而且让 Gateway 操作宿主 Docker socket 仍是高权限。官方明确警告不要把宿主 Docker socket挂给 Agent 的 sandbox 容器。

第八章　Kubernetes 企业部署与高可用边界

8.1 官方清单到底提供了什么

官方文档明确说明 Kubernetes 清单是最小起点，不是生产就绪方案，采用 Kustomize 而非官方 Helm Chart。启动方式：

v2026.7.1 清单的真实形态是：

固定证据：Kubernetes 文档、Deployment、ConfigMap、PVC、Service。

8.2 生产化补齐项

1. Namespace 与账号：每个信任域独立 Namespace、ServiceAccount、PVC、Secret、NetworkPolicy；保留 automountServiceAccountToken: false。若备份边车确需 K8s API，给边车单独账号，不能复用 Gateway 身份。
2. Deployment 或 StatefulSet：单活动 Gateway 使用 Deployment + Recreate 足够直接；StatefulSet 只提供稳定 Pod/卷身份，并不会自动增加分布式锁或渠道租约。主备控制器若依赖固定序号，可使用 StatefulSet，但必须有外部 fencing。
3. 存储：生产 StorageClass 应支持快照、加密和明确的延迟/SLA。若 CSI 支持，单写者可考虑 ReadWriteOncePod；Kubernetes 的 RWO 只限制节点挂载，可能允许同一节点多个 Pod 使用，不等同严格单 Pod 写入。Kubernetes PV 文档。
4. Secret：Kubernetes Secret 只是一种对象，不自动等于硬件级秘密管理。推荐 External Secrets/Secrets Store CSI 把 Vault/KMS 中密钥挂到只读文件，再通过 OpenClaw SecretRef 引用；禁止把密钥写入 ConfigMap、Git 或渲染后的 Helm values。
5. 入口：Ingress/Gateway API 终止 TLS，限制 Host、Origin、WebSocket、请求体和速率；管理 UI 只在管理网/OIDC 后。不要通过公共 LoadBalancer 暴露未经外围鉴权的 18789。
6. NetworkPolicy：默认拒绝入站和出站，只放行反代、DNS、OTel Collector、批准的模型/MCP/渠道目的地。域名出站通常需 egress proxy 或 CNI/FQDN policy，普通 NetworkPolicy 只能按 IP/端口。
7. Pod Security：保留 non-root、drop ALL、只读 rootfs、RuntimeDefault seccomp；按集群能力加 AppArmor/SELinux。不得 hostNetwork、hostPID、privileged，也不得挂宿主根目录或 Docker socket。
8. 资源与探针：根据压测设 request/limit；增加 startupProbe，避免大状态迁移或插件收敛期间被 liveness 反复杀死。readiness 负责流量，liveness 只判断进程自愈。
9. 调度：Agent Sandbox/浏览器节点使用专用 node pool、taint/toleration 与 RuntimeClass；Gateway 本身与高风险执行器分离。反亲和对单副本没有 HA 魔法，但可用于主备或多个独立 cell 分散故障域。
10. PDB：单副本 minAvailable: 1 只能阻止部分自愿驱逐，不能在节点故障时维持服务，还可能阻塞维护；必须配合冷/热备和运维 Runbook。
11. 镜像治理：固定 semver/digest，验证签名、生成 SBOM、扫描镜像与插件；准入策略拒绝 latest/slim 浮动标签和未知仓库。
12. GitOps：Base 放稳定官方字段，Overlay 按环境/信任域维护 SecretRef、Ingress、NetworkPolicy、配额和 Pod 安全。状态数据库、OAuth 文件和 Workspace 不进入 Git。

建议探针片段：

/health 与 /healthz 是浅层存活别名，正常返回 {"ok":true,"status":"live"}；/ready 与 /readyz 会在启动 sidecar、Gateway draining 或渠道运行时健康失败时返回 503。远程未认证调用会隐藏失败详情。不要用 /v1/chat/completions 做探针，因为它会创建会话和模型调用。来源：Health。

最小 NetworkPolicy 思路：

真实环境还需放行 DNS 与批准的模型/渠道/MCP 出站。上述清单故意不写任意 0.0.0.0/0，应由网络团队按目的地补齐。

8.3 为什么不能直接横向扩展

1. 单例锁与端口：官方建议一个配置/状态对应一个 Gateway；锁按配置文件生效，端口也只能被一个进程独占。多个 Gateway 要使用独立 OPENCLAW_CONFIG_PATH、OPENCLAW_STATE_DIR、Workspace 和端口。Multiple Gateways、Gateway Lock。
2. SQLite：共享状态库采用 WAL。SQLite 官方明确说明 WAL 的进程必须在同一宿主，不能依赖网络文件系统提供正确共享锁；把 PVC 设为 RWX 不会把 SQLite 变成分布式数据库。SQLite WAL、SQLite over network。
3. Session：除 SQLite 外仍有 sessions.json 与 transcript JSONL、本地缓存和运行中 turn；随机负载均衡可能让连续消息落到不同运行状态，造成上下文落后、重复发送或冲突写。
4. 渠道长连接：WhatsApp/Baileys 等渠道由 Gateway 持有账号会话和长连接。两个实例抢同一组登录态可能相互踢下线、重复消费/回复并并发修改凭据。
5. Cron：稳定版源码中的 Cron 锁明确是 process-local；计时器虽把 reservation 写入 SQLite，却没有跨节点 leader election。两个活动实例可在任一提交前同时看到到期任务而重复执行。Cron 进程内锁、Cron Timer。
6. 去重/出站：当前不是带持久消息队列、分布式幂等键和 transactional outbox 的集群运行时；入口重试和实例切换需外围系统承担去重。

8.4 可行高可用方案比较

切换顺序必须是：停止入口 → 对旧主执行网络/凭据/存储栅栏 → 验证租约失效 → 恢复或挂载一致状态 → 向新主注入短期凭据 → 启动 → /readyz、渠道和会话冒烟验证 → 开入口。只做 DNS 切换不构成安全主备。

第九章　模型接入与模型路由

9.1 Provider 表

模型能力必须按具体模型实测，不能把 Provider 的“兼容接口”当成 Tool Calling、视觉、流式和推理格式都相同。模型名、上下文窗口和价格变化频繁，应从供应商目录与 openclaw models list --provider <id> 获取，而不是硬编码到长期手册。

官方页：OpenAI、Anthropic、Google、DeepSeek、OpenRouter、Ollama、LM Studio、vLLM、LiteLLM、Model Providers。

OpenAI-compatible 企业网关示例：

示例中的窗口、最大输出和成本是占位元数据，不是对任意自建模型的事实；必须改成模型服务实际限制，否则上下文预算、成本统计和裁剪都会失真。自定义精确 origin 可被信任；其他私网地址需要显式 request.allowPrivateNetwork: true，应由 SSRF 风险评审决定。

9.2 Fallback、Key 轮换和企业路由

【稳定版官方】故障切换分两层：先在同一 Provider 内轮换 auth profile，再沿 fallbacks 切模型。会话会固定 auth profile 以利用缓存，遇到限流/超时才轮换；显式用户 /model 选择是严格模式。配置顺序：

轮换冷却大致为 30 秒、1 分钟，再到 5 分钟上限；计费禁用会进入更长冷却。SDK 的 Retry-After 等待上限默认 60 秒，可用 OPENCLAW_SDK_RETRY_MAX_WAIT_SECONDS 调整。不要把渠道请求层 attempts: 3 的重试说明误写成所有模型调用都会由 OpenClaw统一重试三次。来源：Model Failover、Retry。

企业路由规则：

1. 分类、标题、短摘要走低成本模型；复杂代码/推理走强模型。
2. 数据分类为“内部/机密”的内容先经 DLP，默认走本地模型或合规 Model Gateway；公共资料任务可走云模型。
3. 高风险操作不只是换强模型，还要使用只读预检、策略验证器、人工审批和幂等执行器。
4. 对每次任务设置最大模型调用次数、最大工具循环、最大 Token、最长墙钟时间和成本预算。达到上限立即失败并通知，不以无限 fallback 继续烧费。
5. 降级顺序必须表达能力要求。例如任务需要视觉/Tool Calling 时，不能降级到不支持相应能力的本地模型。
6. Key 轮换不能绕过供应商账号配额；统一在 Model Gateway 做每用户/Agent/成本中心限流和账单归集。

第十章　Session、Context 和 Memory 深度调优

10.1 四个概念不能混用

Session、Context 与 Memory 关系图

Session 是路由和历史单元；Context 是一次模型调用实际看到的有限输入；Memory 是跨轮或跨会话保存与检索的知识。三者不能互相替代，尤其不能把 Session Key 当成授权边界。

1. Session 是可持续的会话运行单元，包含路由/模型覆盖等元数据和追加式 Transcript。
2. Context 是这一轮实际发送给模型的动态窗口；它是 Session 历史经压缩/裁剪后，再加 System Prompt、Workspace、Skills、Tools、Memory、附件的结果。
3. Memory 的事实源是 Markdown，而不是模型参数里的“神秘记忆”；索引可以重建。
4. Workspace 是默认 cwd 和上下文文件根，但不是文件系统沙箱。

10.2 Session Key 与多人隔离

[官方稳定能力] 默认 Agent 是 main，Session Key 形如 agent:main:<mainKey>。群组/房间通常独立，Cron 隔离任务每次可新建 Session，Hook 按 Hook 路由。私聊默认 session.dmScope: "main"，同一 Agent 的多个私聊可能折叠到主 Session。

可选值：

1. main：所有 DM 共享 Agent 主会话；个人助手便利，但多人不安全；
2. per-peer：按发送者；跨 Channel 的同一人仍需 identityLinks；
3. per-channel-peer：按渠道+发送者，企业共享入口的推荐最小值；
4. per-account-channel-peer：再按渠道账号细分。

10.3 Workspace 与 Bootstrap

默认 Workspace：~/.openclaw/workspace；profile 为 ~/.openclaw/workspace-<profile>；非默认 Agent 若未显式指定，通常为 <state-dir>/workspace-<agentId>。可通过 OPENCLAW_WORKSPACE_DIR、agents.defaults.workspace、agents.list[].workspace 覆盖。

可注入文件包括：AGENTS.md、SOUL.md、TOOLS.md、IDENTITY.md、USER.md、HEARTBEAT.md、BOOTSTRAP.md、可选 MEMORY.md；BOOT.md 用于 startup hook。默认单文件 Bootstrap 上限 agents.defaults.bootstrapMaxChars = 20000，合计上限 bootstrapTotalMaxChars = 60000；可 skipBootstrap: true。

10.4 Memory 与 Compaction/Pruning

[官方稳定能力] 默认 Memory 事实文件：

可选 DREAMS.md。memory-core 插件提供 memory_search、memory_get。默认索引支持 SQLite FTS5/BM25，并可结合向量、CJK trigram、sqlite-vec；默认 chunk 约 400 token、overlap 80。远程/本地 Embedding Provider 可选，未配置可退化为关键词检索。

• Compaction：把较旧历史总结后持久写回会话，改变后续可见历史；
• Pruning：模型调用前临时裁掉旧 Tool Result，不改磁盘 Transcript；
• Memory Flush：接近 Compaction 前触发一次静默 Agent Turn，提示把值得长期保存的信息写入 Memory；可用 agents.defaults.compaction.memoryFlush.enabled: false 关闭。

10.5 v2026.7.1 的混合持久化（重要勘误）

[官方稳定源码核验] 不能笼统写“OpenClaw 全部使用 SQLite”，也不能写“全部是 JSON 文件”。稳定版是混合形态：

共享 SQLite 已承载 Cron 定义/运行记录、ingress dedupe、delivery queue、task/flow、pairing、plugin index、audit/state lease 等多类状态；per-agent SQLite 承载认证秘密与运行状态、Memory 索引等。稳定版源码的 per-agent Schema 没有 Session/Transcript 主表。

这里存在两个容易误写的文档差异：

1. docs/refactor/database-first.md 描述数据库优先重构，不代表稳定版已把 Session 全迁入 SQLite；
2. docs/concepts/multi-agent.md 某段仍写 auth-profiles.json，而同版本 model-failover 文档与实际 src/agents/auth-profiles/sqlite.ts 已明确认证存入 openclaw-agent.sqlite。应以源码与后者为准。

企业备份必须同时覆盖 SQLite 的 -wal/-shm 一致性、Session JSON/JSONL、Workspace/Memory 和配置；只备份一个数据库文件会丢会话正文。

源码：

1. https://github.com/openclaw/openclaw/blob/v2026.7.1/src/agents/auth-profiles/sqlite.ts
2. https://github.com/openclaw/openclaw/tree/v2026.7.1/src/agents/sessions
3. https://github.com/openclaw/openclaw/tree/v2026.7.1/src/state
4. https://docs.openclaw.ai/concepts/model-failover

10.6 配置语义

配置默认 ~/.openclaw/openclaw.json，可 OPENCLAW_CONFIG_PATH 覆盖；有效 Home 可通过 OPENCLAW_HOME 影响。配置支持 JSON5，但 Schema 严格，未知字段/类型错误会使 Gateway 拒绝启动；非法配置的守护进程退出码为 78，以避免无意义重启风暴。

配置写入采用原子替换；官方不鼓励把主配置做成符号链接。SecretRef 应用于文档支持的凭据表面；不是每个字符串字段都接受 SecretRef。

来源：https://docs.openclaw.ai/cli/config

10.7 上下文预算：先算再调

Context Window（上下文窗口）不是全部留给历史。一次调用的可用预算 W 应满足：

其中 S 为系统提示词，B 为 Workspace/Bootstrap，K 为 Skills 描述与 Tool Schema，H 为对话历史，T 为工具结果，M 为 Memory 检索，O 为最终回答，R 为安全余量。建议先按比例设上限，再用真实模型 tokenizer 校验；下表是起始方法，不是 OpenClaw 默认值。

例如 128k 模型不要把 120k 都当作可用历史；若工具描述 20k、Bootstrap 15k、检索 8k、最终回答 12k、安全余量 15k，则历史与工具结果合计只有约 58k。小模型只有 16k/32k 时，应为特定 Agent 暴露极少工具，并把复杂数据处理移到确定性服务。

10.8 十类常见症状与调优

1. 越聊越慢： 用 /context detail 找增长项；按 Session 类型设置重置；压缩历史；把大对象改为引用；检查模型端排队与 Prompt Cache 命中，不能只删 Memory。
2. Token 持续增大： 用 /usage tokens、OTel 的 input/output token 和 Tool result bytes 分桶；减少常驻 Skills/Tool Schema；限制附件 OCR 文本；开启有评测的 pruning。
3. 忘记早期信息： 判断事实是否应进业务数据库、长期 Memory 或 Compaction 摘要；关键约束进入版本化 Workspace；Memory 写入带来源/所有者/时间，不盲目增加窗口。
4. Compaction 过频： 检查模型 context window 是否识别正确、大 Tool Result、Bootstrap 合计和输出预留；增大窗口前先缩减 Tool；调整 keepRecentTokens 后跑多轮回归。
5. Tool 输出占满窗口： Tool 端支持 fields、limit、游标、时间范围和服务器摘要；最大字节硬截断时保留头尾、错误码和对象 URI；原始文件放受控存储。
6. Skills 太多： 使用 agents.defaults.skills/agents.list[].skills 精确允许；短化 description；按领域拆 Agent；不要把百科全文放 frontmatter。
7. 小模型容不下工具： 专用 Agent 只给 3～8 个窄 Tool；用 Tool Router/Tool Search；把复杂 schema 包装成业务级 Tool；失败时升级模型而非向小模型塞更多规则。
8. 长期记忆召回错误： 查文档版本、chunk、embedding provider、关键词/向量权重、minScore、top-k、MMR 和时间衰减；建立 Precision/Recall 集；过期事实加 TTL 或 tombstone。
9. 用户/群聊串扰： 立即停止受影响入口；检查 dmScope、Channel account、不可变 peer ID、群/线程键、Agent binding、Memory ACL；必要时拆 Gateway 和索引。不要只清聊天窗口。
10. 未经验证信息写入 Memory： 把 Memory Flush 改为生成候选，服务端验证来源、数据等级、所有者、置信度和 TTL 后再写；外部网页/群聊内容默认不进入个人 Memory；支持用户查看、纠正和删除。

10.9 诊断命令与验证闭环

聊天内可用 /status、/context list、/context detail、/context map、/usage tokens 与 /compact；实际是否启用取决于命令策略和 Channel。诊断顺序：复制受影响 Session 到无副作用测试环境；记录总 Context 与每分区 Token；识别最大增长源；固定模型与问题，改一个变量；运行短/中/长多轮、Tool 大结果、Memory 正误召回、两用户隔离和 Prompt Injection 测试；比较 Task Success、Memory Precision/Recall、P95、Token/Cost；灰度 5% Session；不达门槛回滚。

验证 Compaction 不只看“模型还能回答”，还要检查：关键事实是否保留、错误事实是否被固化、Tool 调用 ID/结果关系是否可续、审批状态是否丢失、摘要是否泄露别的用户。验证 pruning 要确认磁盘 Transcript 未被修改、故障诊断所需错误码仍可用。重建 Memory 索引前保存 Markdown 事实源和索引版本；索引可重建不代表事实文件可丢。