ARTICLE · 1149221
火出圈的龙虾��背后技术是什么,待我用 OpenClaw 技术慢慢讲来
1. 文档目标
本文系统介绍 OpenClaw 的设计、运行机制和生产实践。读完后应能够：
• 理解 Gateway、Agent Runtime、Channel、Session、Tool、Skill、Memory 与 Node； • 完成安装、模型接入、Channel 配置和多 Agent 路由； • 理解系统 Prompt、Context、Compaction、Queue 与 Agent Loop； • 使用 Browser、Exec、Web、MCP、Automations 和 Session Tools； • 设计 Sandbox、Tool Policy、Pairing、Allowlist 和多信任域部署； • 开发 Skill、Tool Plugin、Channel Plugin 和 Provider Plugin； • 建立备份、升级、观测、故障处理和安全审计体系； • 阅读仓库源码并定位核心调用链。
2. OpenClaw 是什么
OpenClaw 是开源、自托管、面向个人与互信团队的 AI Agent 平台。它将模型和 Agent 能力接入用户已有的消息渠道与设备：
• WhatsApp、Telegram、Slack、Discord、Signal、iMessage； • Google Chat、Microsoft Teams、Matrix、IRC、LINE、Zalo 等； • WebChat、Control UI、CLI、TUI； • macOS、iOS、Android、Windows、Linux Companion/Node； • Browser、文件、Shell、Web、MCP 和插件工具。
其核心不是聊天 UI，而是由 Gateway 管理的持久 Agent 控制平面。
3. OpenClaw 不是什么
OpenClaw 不是：
• 大语言模型； • 无需配置即可安全暴露公网的聊天机器人； • 面向互相敌对租户的强多租户隔离平台； • 默认启用的容器沙箱； • 传统业务权限系统； • 让模型直接拥有宿主机全部权限的理由； • 所有 Coding Agent 的替代品。
它连接模型与真实工具，能力越强，权限设计越重要。
4. 适用场景
• 在多个聊天平台中使用同一个私人助手； • 从手机触发本地或远程研发任务； • 管理具有独立人格、workspace 和工具权限的 Agent； • 通过浏览器、Shell、文件、设备节点完成真实任务； • 使用定时任务主动生成提醒、报告或巡检； • 将 Codex、Claude Code 等外部 Agent Runtime 纳入统一入口； • 为互信团队提供受控共享助手。
强对抗性 SaaS 多租户应拆分 Gateway、OS 用户或主机。
5. 核心架构
Messaging Channels / Control UI / CLI / Companion Apps | WebSocket / Events | OpenClaw Gateway ┌─────────────────┼─────────────────┐ | | | Channel Layer Agent Runtime Control Plane | Model + Tool Loop Config/Sessions/Jobs | | | Workspace / Memory / Skills | | ├──────── Tools / Plugins / MCP ────────┐ | | External APIs Nodes / Browser / Host6. Gateway
Gateway 是单一长驻进程，负责：
• 维护 Channel 连接； • 接收入站消息并做身份、配对和路由； • 管理 Agent、Session 和队列； • 构造模型上下文并运行 Agent Loop； • 调度 Tool、Plugin、Node 和 Browser； • 向 UI/CLI 提供 WebSocket 控制面； • 执行 Automations、Heartbeat 和维护任务； • 持久化配置、状态和会话。
默认绑定 127.0.0.1:18789，不应无认证直接暴露公网。
7. 单 Gateway 原则
同一个状态目录只能由一个 Gateway 或本地 Agent 进程拥有。Gateway 使用状态目录锁和 SQLite 写入队列协调状态。
错误做法是在同一 OPENCLAW_STATE_DIR 上启动多个 Gateway 争用数据库。需要多个实例时应使用独立 Profile、端口、配置和状态目录。
8. 控制平面客户端
客户端包括：
• Control UI； • CLI/TUI； • macOS/Windows/Linux Companion； • 自动化和系统管理工具； • OpenAI-compatible API Client。
客户端不直接成为状态权威；会话、路由和运行状态由 Gateway 持有。
9. Channel 数据平面
Channel Plugin 将各平台事件转换为统一消息语义，并负责：
• 账户登录/Token； • Sender、DM、群组、Thread 映射； • Pairing/Allowlist； • Mention Gate； • 消息分片与格式； • 图片、音频、文件； • Reaction、Typing、Button 等能力； • 出站发送与错误恢复。
模型不选择回复 Channel；宿主根据入站路由确定性回复。
10. Agent
一个 Agent 是完整隔离的角色范围，通常拥有：
• agentId 与身份； • Workspace； • Bootstrap 文件； • Session Store； • Auth Profile 和 Model Registry； • Tool Policy； • Sandbox Policy； • Skills； • Memory； • Channel Bindings。
多 Agent 不只是多个 System Prompt，而是多个状态与权限主体。
11. Embedded Agent Runtime
OpenClaw 内置 Agent Runtime，负责：
1. 解析 Agent、Model 与 Auth Profile； 2. 准备 Workspace 和 Session； 3. 构造 System Prompt 与 Context； 4. 调用模型； 5. 处理原生 Tool Call； 6. 流式发布文本和工具事件； 7. 执行循环、超时与取消； 8. 保存消息、诊断和 Usage； 9. 返回最终结果。
12. 外部 Agent Runtime
Agent Runtime 与 Model Provider 是不同概念：
• Provider：提供模型推理 API； • Runtime：掌握一次完整 Agent Turn 的模型循环和工具行为。
OpenClaw 可以接入 Codex 等外部 Runtime Surface，由外部 Harness 管理特定 Turn，再由 Gateway 统一连接 Channel、Session 和 Control Plane。
13. Agent Loop
Inbound Message -> Session Resolution -> Queue Admission -> Context Assembly -> Model Request -> Assistant Text or Tool Call -> Policy / Approval / Sandbox -> Tool Execution -> Tool Result -> Model Continues -> Finalize / Timeout / Abort -> Persist + DeliverTool Call 是模型建议；确定性策略和执行层决定是否真正执行。
14. Run Queue
OpenClaw 对同一 Session 的 Run 做序列化，并通过全局队列控制资源。这样可以避免：
• 同一会话并发修改历史； • Tool 输出顺序混乱； • 多个回复同时发送； • Compaction 与新消息竞态； • SQLite 写入冲突。
不同 Session 可以在全局限制内并发。
15. Steering Queue
默认 steer 模式下，Agent 运行期间到达的新消息可尝试注入活跃 Runtime，包括 Tool 执行阶段。适合用户补充条件或纠正方向。
工程注意：
• Runtime 是否支持 Steering； • 新消息是否会改变危险操作； • Tool 已执行的副作用无法撤销； • Steering 和普通排队语义要对用户透明； • 高风险写操作前应重新确认最新状态。
16. Stop、Abort 与 Timeout
一次 Run 可能因以下原因结束：
• 模型正常结束； • 用户停止； • Runtime Abort； • 总运行超时； • Provider 错误； • Tool 错误； • Context Overflow； • Gateway 关闭； • 外部 Runtime 终态。
不能仅以“长时间没有文本”判断 Turn 已结束。
17. 安装要求
当前官方要求 Node.js 24.16+ 或 26.1+，推荐 Node 26。还需要：
• 支持的操作系统； • 至少一个模型 Provider 凭证或本地模型； • 可写的配置、状态与 Workspace； • 使用 Sandbox/Browser 时可用 Docker 或 Podman； • 对应 Channel 的账号和凭证。
18. 推荐安装
curl -fsSL --proto '=https' --tlsv1.2 \ https://openclaw.ai/install.sh | bash安全敏感环境应先下载、审查和校验安装脚本，再执行。安装器会检查运行时并启动引导流程。
19. 从源码安装
git clone https://github.com/openclaw/openclaw.gitcd openclawpnpm installpnpm buildpnpm ui:buildpnpm openclaw onboard源码开发需使用仓库锁定的 pnpm/Node 组合。不要用未锁定依赖替代项目 lockfile。
20. Gateway 服务
openclaw gateway installopenclaw gateway statusopenclaw gateway restartopenclaw gateway stop前台调试可使用 Gateway run/foreground 命令；后台服务在 macOS 通常由 launchd、Linux 由 systemd user service 管理。
21. Dashboard
openclaw dashboardDashboard/Control UI 用于：
• 聊天； • Agent、Session 与 Node 管理； • 配置； • Plugin 与 Skill； • Tool 权限和审批； • 模型、Channel 和状态检查。
远程访问必须使用安全隧道、Tailscale 或正确配置的反向代理与认证。
22. 目录布局
~/.openclaw/ openclaw.json 主配置 state/ 共享状态与 SQLite agents/<agentId>/agent/ Agent 状态、Auth、模型等 workspace/ 默认 Agent Workspace sandboxes/ Sandbox Workspace/状态 ...~/.openclaw/workspace/ AGENTS.md SOUL.md IDENTITY.md USER.md MEMORY.md DREAMS.md memory/ skills/实际目录受 Profile 和环境变量影响。
23. Config、State 与 Workspace 边界
openclaw.json | ||
不要只备份 Workspace 而遗漏状态，也不要把状态目录提交 Git。
24. 配置文件
默认配置文件：
~/.openclaw/openclaw.json格式支持 JSON5，可包含注释和尾逗号。可用 OPENCLAW_CONFIG_PATH 指定其他位置。根级配置保存基础设施和跨 Agent 默认值；agents.defaults 保存 Agent Loop 默认行为。
25. 最小配置
{ agents: { defaults: { workspace: "~/.openclaw/workspace", model: { primary: "anthropic/claude-sonnet-4-6" }, }, entries: { main: { identity: { name: "Clawd", theme: "helpful technical assistant", emoji: "🦞", }, }, }, },}模型 ID 只是示例，须替换为当前账号实际可用模型。
26. Profile
Profile 用于在同一主机运行独立配置实例。非默认 Profile 通常拥有独立的：
• State Directory； • Workspace 默认路径； • Gateway Service； • 端口； • 配置与日志； • Agent/Session。
适合分离开发、生产或不同信任域，但高风险隔离仍优先使用独立 OS 用户/主机。
27. 配置热加载
部分配置可由运行中的 Gateway 重新加载，另一些涉及进程、Channel、Runtime 或环境变量的设置需要重启。修改后执行：
openclaw doctoropenclaw status --all不要假设文件保存成功就代表运行时已经采用新配置。
28. Doctor
openclaw doctor 用于：
• 校验配置； • 迁移旧 Schema； • 检查 State 与 Workspace； • 发现无效 Allowlist/Policy； • 修复部分已知问题； • 验证服务和依赖。
升级后建议运行 openclaw doctor --fix，但先备份并审查变更。
29. Workspace
Workspace 是 Agent 的“家”：
• 文件工具默认工作目录； • Persona 与操作规则来源； • 长期 Memory； • 自定义 Skill； • 任务工作文件。
重要：Workspace 只是默认 cwd，不是安全沙箱。未开启 Sandbox 时，绝对路径和 Shell 仍可能访问主机其他位置。
30. AGENTS.md
AGENTS.md 通常描述：
• 操作规则； • 工作流程； • 项目约定； • 工具使用要求； • 验证标准； • Memory 写入规则； • 禁止事项。
它会进入 Project Context，应简洁、稳定、可版本化。
31. SOUL.md
SOUL.md 描述 Agent 人格、价值边界、语气和互动风格。它不应该承担真实权限控制。
例如“不要删除文件”写在 SOUL 中只能影响模型倾向；真正限制必须通过 Tool Policy、Sandbox 和审批完成。
32. IDENTITY.md
IDENTITY.md 保存 Agent 名称、身份定位和对外呈现。身份与权限分离：一个被命名为“管理员”的 Agent 不应自动获得管理权限。
33. USER.md
USER.md 保存稳定的用户偏好和协作方式。推荐记录：
• 偏好语言； • 沟通风格； • 时区； • 已确认的长期偏好； • 当前项目上下文。
不要保存密码、Token、身份证和不必要的敏感画像。
34. BOOTSTRAP.md
新 Workspace 可包含一次性 BOOTSTRAP.md，引导 Agent 与用户完成首次身份和偏好设置。完成后删除，后续重启不应反复执行。
对于预置 Workspace，可配置跳过 Bootstrap 文件自动创建。
35. MEMORY.md
MEMORY.md 是精炼的长期记忆：
• 长期决定； • 稳定事实； • 项目关键约束； • 需要每次会话都可见的摘要。
它不是原始聊天记录。过大会被注入预算截断，应将细节转移到 memory/*.md。
36. Daily Memory
memory/YYYY-MM-DD.mdmemory/YYYY-MM-DD-<slug>.mdDaily Note 保存近期观察、会话摘要和暂时上下文，可由 memory_search/memory_get 检索。裸 /new 或 /reset 会自动加载今天与昨天的相关笔记。
37. DREAMS.md 与 Consolidation
可选 DREAMS.md 用于记录后台 Memory Consolidation/Dreaming 的总结供人审查。长期流程：
Session Details -> Daily Notes -> Consolidation -> MEMORY.md模型写入的记忆仍可能错误，应允许用户查看、纠正和删除。
38. Memory Flush
自动 Compaction 前，系统可运行静默 Turn，提醒 Agent 将重要信息写入持久 Memory。这样可以在压缩会话前保存关键事实。
Memory Flush 不是事务：如果写入失败或模型判断错误，信息仍可能丢失，因此关键业务事实应保存在业务系统。
39. Memory 与业务数据
不要让 Markdown Memory 成为业务事实唯一来源。
40. System Prompt Assembly
系统上下文通常组合：
• OpenClaw 核心规则； • 时间、运行环境和 Agent 身份； • Tool Schema； • Skill Catalog； • Workspace Bootstrap 文件； • 用户/Session/Channel 上下文； • Sandbox 和 Runtime 信息； • 当前请求与附件。
可用 /context 相关命令查看组成和大小，而非泄露完整内部 Prompt。
41. Context 与 Memory 的区别
• Context：当前模型调用实际看到的 token； • Memory：磁盘或插件存储中可供未来检索的信息； • Session History：当前会话的持久消息； • Workspace：更广泛的文件与指令环境。
保存到 Memory 不代表每次都完整进入 Context。
42. Context Budget
Context Window 被以下内容共同占用：
System Prompt+ Tool Schemas+ Bootstrap Files+ Conversation History+ Tool Results+ Attachments+ Pending Input+ Output Reserve大 Tool 输出应写文件并返回摘要/路径，避免把几 MB 内容写入会话。
43. Compaction
当会话接近模型 Context Limit 或 Provider 返回溢出时，OpenClaw 自动压缩较旧历史并保留近期内容。
新配置默认采用更严格的 safeguard 模式，强调摘要质量校验、未完成事项和精确标识符保留。
44. Compaction 风险
• 细节丢失； • ID、数字和路径被改写； • 未完成任务被误判完成； • Tool 错误原因丢失； • 用户修正被旧摘要覆盖； • Prompt Injection 被写入摘要。
关键值应进入结构化 State、Memory 或业务系统，不只存在聊天历史。
45. Session
Gateway 根据消息来源解析 Session。Session 保存：
• 消息历史； • Tool Call/Result； • Agent 与 Channel 上下文； • Runtime 诊断； • Usage； • Compaction 结果； • 运行和投递状态。
所有 Session 状态由 Gateway 管理，UI 通过 Gateway 查询。
46. Session Key
Session Key 由 Agent、Channel、Account、Peer、Thread/Topic 和配置的 DM Scope 等共同决定。设计目标是确保相同对话进入相同 Session，不同安全主体不能意外共享上下文。
更改 Session Scope 前必须评估历史兼容和跨用户泄漏。
47. DM Scope
默认策略可能让不同 Channel 的同一 Agent 私聊汇聚到主 Session，便于跨端连续对话。共享/多用户场景应选择按 Sender/Channel 隔离的 Scope。
若多个互不信任用户共享主 Session，他们可能看到彼此上下文，这是部署错误。
48. Group Session
群组通常按 Channel、Account、Group、Thread/Topic 隔离。应配置：
• 群组 Allowlist； • 是否 Require Mention； • 谁可以触发 Command； • 历史注入范围； • 回复可见性； • Tool 权限； • 跨会话发送限制。
49. Session Tools
Agent 可通过 Session Tools：
• 列出 Session； • 查看历史和状态； • 搜索 Session； • 向其他 Session 发送消息； • 创建子 Agent/子 Session； • 等待或协同结果。
这些工具可能跨用户读取内容，必须限制 visibility 和 agent-to-agent policy。
50. Session Visibility
常见范围思想：
• self：仅当前 Session；• tree：当前 Session 与其子 Session；• agent：同 Agent 所有 Session；• all：Gateway 全部 Session。
共享部署不要保留宽松的 all 默认行为；根据业务缩小到 self 或 tree。
51. 多 Agent 路由
Inbound Message -> Channel Account -> Peer/Group/Role/Binding Match -> agentId -> Agent Workspace + Session + PolicyBindings 按确定性配置选择 Agent，不应让模型决定消息属于哪个安全主体。
52. 多 Agent 配置
{ agents: { ownership: "explicit", entries: { personal: { workspace: "~/.openclaw/workspace-personal", sandbox: { mode: "off" }, }, family: { workspace: "~/.openclaw/workspace-family", sandbox: { mode: "all", scope: "agent" }, tools: { allow: ["read", "message"], deny: ["exec", "write", "edit", "apply_patch", "process", "browser"], }, }, }, },}共享 Agent 应默认 Sandbox 和最小 Tool 权限。
53. Binding
Binding 根据 Channel、Account、Peer、Group、Role 等匹配 Agent。规则设计：
• 更具体规则优先； • 最后设置受控 fallback； • 不应出现敏感群组落入高权限主 Agent； • 删除 Agent 后重新检查 Binding； • 用真实入站事件测试路由。
54. Agent Auth 隔离
每个 Agent 有独立 Auth Store，不能复用同一个 agentDir。静态 API Key 可以在明确评估后复制；OAuth Refresh Token 不应简单克隆到其他 Agent。
共享默认 Agent Auth 的继承行为需要配合最小权限和供应商账户隔离。
55. Model Provider
OpenClaw 可接入多个云模型、本地模型和 OpenAI-compatible Endpoint。Provider 配置描述：
• baseUrl/API； • Auth Profile； • Model Catalog； • 输入模态； • Context/Output Token； • Reasoning 能力； • Tool 支持； • Cost； • Compatibility Flags。
56. 模型配置
{ agents: { defaults: { model: { primary: "anthropic/claude-sonnet-4-6", fallbacks: ["openai/gpt-5.4"], }, }, },}模型 ID 仅用于说明结构。实际可用模型必须通过 openclaw models status 验证。
57. Auth Profile
Auth Profile 将 Provider 凭证和认证方式从普通模型配置中分离。安全原则：
• 使用 Secret 管理； • 区分个人、工作和自动化账户； • 定期轮换； • 最小额度和权限； • 不写 Workspace； • 不进入 Session/日志； • 每 Agent 明确继承关系。
58. Model Failover
Failover 可在认证、配额或 Provider 故障时选择备用 Model/Auth Profile。需要预先评测：
• Tool Call Schema； • 上下文长度； • 安全策略； • 结构化输出； • 成本和延迟； • 多模态； • Prompt 行为。
备用模型不是等价替换。
59. 自定义 Provider
{ models: { mode: "merge", providers: { "internal-proxy": { baseUrl: "https://llm-gateway.example.com/v1", apiKey: "INTERNAL_LLM_KEY", api: "openai-responses", models: [ { id: "approved-model", name: "Approved Model", reasoning: true, input: ["text"], contextWindow: 128000, maxTokens: 16000, }, ], }, }, },}baseUrl 同时是网络信任决策，只配置受信 Origin。
60. OpenAI-compatible API
Gateway 可提供兼容接口，例如：
• /v1/models；• /v1/embeddings；• /v1/chat/completions；• /v1/responses。
模型列表以 Agent 为中心，可包含 openclaw/default 和 openclaw/<agentId>。对外暴露时必须配置认证、网络限制和速率控制。
61. Tool 系统
Tool 是 Agent 可请求的真实能力，包括：
• 文件读写与 Patch； • Exec/Process； • Web Search/Fetch； • Browser； • Message/Channel； • Session/Subagent； • Memory； • Cron/Automation； • Image/Audio/Video； • MCP； • Plugin Tools； • Node/Device Actions。
62. Tool Policy 层次
一次 Tool Call 是否允许，通常由多层共同决定：
Tool Catalog -> tools.profile -> allow / deny / groups -> per-agent override -> provider/model restrictions -> sender/owner policy -> sandbox tool gate -> execution permission / approval -> runtime validationTool 在列表中可见不代表当前调用已授权。
63. Tool Profile
minimal | |
coding | |
messaging | |
full |
Profile 只是基础选择，仍受 Allow/Deny、Sandbox 和审批限制。
64. Allow 与 Deny
{ tools: { profile: "coding", deny: ["browser", "message", "gateway"], allow: ["read", "write", "edit", "apply_patch", "exec"], },}Deny 应优先用于明确禁止危险面。配置后使用状态/Doctor 查看最终有效策略。
65. Exec Tool
Exec 可以运行 Shell 命令，并可通过 Process 管理后台任务。它是高风险、可变更工具：
• 能创建、修改和删除文件； • 能访问网络和凭证； • 能启动持久进程； • 能绕过禁用的 write/edit 工具直接写文件； • 权限取决于 Host/Sandbox OS 能力。
禁用文件工具不等于 Exec 只读。
66. Exec 安全
• 非可信用户禁用 Exec； • 使用容器 Sandbox； • Workspace 设置只读或无访问； • 限制网络； • 设置超时和输出上限； • 高风险命令审批； • 不以 root 运行； • Secret 使用最小作用域； • 记录命令和结果摘要； • 防止命令注入。
67. Apply Patch
Apply Patch 适合受控代码修改，比任意 Shell 拼接更易审计。但仍能修改允许范围内文件，应结合：
• Workspace 根约束； • 模型 Allowlist； • Diff 预览； • Git 状态检查； • 测试； • 人工批准； • 禁止修改 Secret 与基础设施关键文件。
68. Loop Detection
Tool Loop Detection 可识别重复 Tool Call 或无进展循环。生产 Agent 应同时设置：
• 检测开关； • 最大 Agent Step； • 总运行时间； • Tool 调用预算； • 重复参数阈值； • 连续失败熔断； • 人工接管。
69. Web Search 与 Fetch
• web_search：使用配置 Provider 返回规范化搜索结果；• web_fetch：轻量抓取 URL；• x_search：按配置搜索 X 内容；• 搜索结果可缓存。
必须限制重定向、响应大小、超时、私网地址和敏感 URL。
70. Browser Tool
OpenClaw 管理独立 Browser Profile，用于：
• 页面导航； • Snapshot； • 元素定位与交互； • 表单； • 下载； • 登录后的自动化； • 视觉验证。
默认应使用独立 openclaw Profile，而不是日常浏览器 Profile。
71. Browser 的 Snapshot 模式
稳健自动化流程：
open/navigate -> snapshot -> choose stable element reference -> click/type -> wait -> snapshot again -> verify outcome页面变化后旧元素引用可能失效，应重新 Snapshot，而不是盲目重复点击。
72. Browser 登录
登录策略：
• 优先在隔离 Profile 中手动登录； • 不把密码交给模型； • MFA/验证码由用户处理； • 避免自动化银行、身份和高风险后台； • 使用最小权限账户； • 定期清理 Cookie； • 登录状态视为 Secret。
73. Browser SSRF 与数据泄漏
浏览器可以访问内网和已登录站点，攻击者可通过网页内容诱导 Agent 外传数据。防护：
• 网络 Egress Policy； • 私网/元数据地址阻断； • 独立 Profile； • 限制下载和上传； • 不共享宿主剪贴板/目录； • Tool 调用审批； • 不可信页面与系统指令隔离。
74. Media Tool
OpenClaw 可理解或生成图片、音频和视频，可能通过 Provider 或本地 CLI。治理要点：
• 文件大小和类型； • 恶意文件扫描； • 模型和成本路由； • EXIF/PII； • 内容审核； • 临时文件清理； • 发送前授权； • 生成内容溯源。
75. Message Tool
Message Tool 可向 Channel/Conversation 发送内容，是对外副作用。应限制：
• 当前 Conversation； • Provider 内跨上下文； • 跨 Provider； • 允许收件人； • 群发数量； • 内容类型； • 发送审批； • 幂等与撤回能力。
76. MCP
配置的 MCP Server 可向 Agent 提供 Tool/Resource。安全要求：
• Server 来源可信； • 工具命名空间； • 参数与返回大小限制； • 超时和取消； • Secret 由宿主注入； • 远程网络 Allowlist； • 高风险动作审批； • 不把 MCP 发现当作授权。
77. Sandbox
Sandbox 将 Agent Tool 执行放入 Docker/Podman 等隔离环境。它与 Gateway 是否运行在容器内是两个独立问题：
• Gateway 可在 Host，Tool 在 Sandbox； • Gateway 可在容器，Sandbox 仍需独立配置； • Sandbox 默认不开启； • 每 Agent 可覆盖策略。
78. Sandbox Mode 与 Scope
常见设计维度：
• mode：关闭、只隔离部分会话、全部隔离； • scope：共享、每 Agent 或更细粒度； • workspaceAccess： rw、ro、none；• workspaceRoot； • Browser Sandbox； • Image 与资源限制； • 网络策略。
实际枚举值以当前配置 Schema 为准。
79. Workspace Access
• rw：Sandbox 可读写映射 Workspace；• ro：只读源码，写入 Sandbox 临时目录；• none：不向 Sandbox 暴露 Host Workspace。
对陌生用户触发的 Agent，优先 none 或最小只读副本。
80. Sandbox 不是绝对安全
仍需防范：
• Docker Socket 暴露； • 特权容器； • Host Mount； • 内核漏洞； • 网络访问； • Secret 环境变量； • 镜像供应链； • 资源耗尽； • Sandbox Escape。
不要把 /var/run/docker.sock 无限制交给 Agent 容器。
81. Sandbox 镜像
生产镜像应：
• 固定 Digest； • 非 root； • 最小软件； • 只包含允许的 CLI； • 定期扫描； • 只读根文件系统； • 限制 Capability； • 配置 CPU/内存/PID； • 无 Secret 烘焙； • 可复现构建。
需要的二进制应构建进镜像，不能依赖容器启动后临时安装。
82. Skills
Skill 是包含 SKILL.md 的目录，通过 Markdown 指令告诉 Agent：
• 何时使用； • 使用哪些 Tool； • 操作步骤； • 输入输出； • 安全限制； • 参考资料和脚本。
Skill 不等于可执行权限，它依赖当前 Tool Policy 和环境。
83. Skill 结构
skills/my-skill/ SKILL.md scripts/ references/ assets/SKILL.md 包含 YAML Frontmatter 和正文。脚本、Reference 和 Asset 只在任务需要时加载，避免把全部内容注入 Context。
84. Skill 加载与优先级
OpenClaw 加载内置 Skill、已安装 Skill 和 Workspace 本地 Skill，并依据：
• 配置； • 环境变量； • 二进制是否存在； • 平台； • Allowlist/Gating； • 本地覆盖优先级。
同名覆盖应有明确来源，升级后检查是否遮蔽新版本。
85. Skill 安全
Skill 是 Prompt 供应链的一部分，恶意 Skill 可诱导 Agent：
• 读取 Secret； • 运行危险命令； • 上传数据； • 修改权限； • 安装持久化程序； • 绕过审批。
安装前审查 SKILL.md、脚本、依赖、网络目标和更新来源。
86. ClawHub
ClawHub/插件市场提升发现和安装效率，也引入供应链风险。治理建议：
• 允许来源清单； • 固定版本和哈希； • 安装前静态扫描； • 在隔离环境试运行； • 检查维护者和发布历史； • 避免自动更新高权限 Skill； • 记录安装审计。
87. Plugin
Plugin 可扩展：
• Tool； • Channel； • Model Provider； • Agent Runtime； • Hook； • Service； • Setup/Onboarding； • Control UI。
当前官方明确 Plugin SDK 全部属于实验性 API，必须锁定兼容 OpenClaw 版本。
88. Plugin Manifest
外部 Plugin 需要 Manifest 描述：
• ID、名称、版本； • 主类别； • Runtime 入口； • Tool/Channel/Provider Contract； • 配置 Schema； • 兼容版本； • 安装和启动信息。
Manifest 让 Gateway 在不加载 Runtime Code 时完成发现和策略判断。
89. Tool Plugin
Tool-only Plugin 应：
• 使用官方 defineToolPlugin等 SDK 入口；• 提供 TypeBox Schema； • 发布 ESM 构建产物； • 在 Contract 中声明 Tool； • 支持 AbortSignal； • 返回有限、结构化结果； • 做确定性鉴权； • 清理后台任务。
90. Tool Plugin 伪代码
import { Type } from"@sinclair/typebox";import { defineToolPlugin } from"openclaw/plugin-sdk/tool-plugin";exportdefaultdefineToolPlugin({id: "example-status",tools: {get_status: {description: "Read a status value from an approved service",inputSchema: Type.Object({resourceId: Type.String({ minLength: 1 }), }),asyncexecute(input, context) { context.signal.throwIfAborted();return { resourceId: input.resourceId, status: "ok" }; }, }, },});该代码用于解释结构，具体 Contract 名称和返回形态应以锁定版本 SDK 为准。
91. Channel Plugin
Channel Plugin 需要处理：
• Account 配置与登录； • 入站事件验证； • Sender/Peer/Thread 规范化； • Pairing、DM Policy、AllowFrom； • Group/Mention； • 出站消息、附件和限制； • Capability Discovery； • Doctor 与迁移； • Rate Limit 和断线重连。
访问控制必须复用官方解析 Helper，避免 Runtime 和 Doctor 语义不同。
92. Provider Plugin
Provider Plugin 发布模型目录、认证选择和传输适配。需明确：
• API 类型； • 模型能力； • Tool/Reasoning/多模态； • Context 和 Output 限制； • Usage 与 Cost； • Stream 事件； • Auth/SecretRef； • Compatibility； • 错误分类和重试。
93. Hooks
Plugin Hook 可观察或控制安装、Gateway 生命周期、Cron、消息、Run、Tool 等事件。设计要求：
• 不依赖未声明的 Hook 顺序； • 幂等； • 有超时； • Fail-open/Fail-closed 明确； • 不阻塞关键路径； • 支持取消； • 不泄漏敏感 Payload； • 生命周期关闭时清理资源。
94. Install Policy
安全安装策略可对 Plugin/Skill 安装做 allow、warn 或 block，并在策略不可用时选择 Fail Closed。企业环境应：
• 禁止未知 npm/ClawHub 包； • 验证签名、版本和来源； • 记录请求人和审批； • 扫描 Manifest/脚本； • 限制 postinstall； • 固定依赖。
95. Channels
不同 Channel 的安全和行为不同：
• Bot Token 与 OAuth； • 用户 ID 稳定性； • DM/群组； • Thread/Topic； • Mention； • 文件限制； • 命令； • Interactive Components； • 消息编辑/删除； • 平台速率限制。
必须阅读目标 Channel 专属文档。
96. Pairing
默认 Pairing 流程：
Unknown Sender sends DM -> OpenClaw returns short pairing code -> Original message is not processed -> Operator reviews pending request -> Operator approves -> Future messages allowedPairing 是入站身份准入，不是 Tool 管理权限。
97. DM Policy
常见策略：
• pairing：未知用户需批准；• allowlist：仅指定 Sender；• open：公开，但通常要求明确*；• disabled：忽略 DM。
互联网暴露的 Agent 不应随意使用 open，尤其不能配合高权限 Tool。
98. Access Group
Access Group 将跨 Channel 的可信 Sender 列表集中定义并在 Allowlist 中引用。Group 本身不自动授权，必须被 Channel Policy 显式引用。
用户离职、账号变化和 Channel ID 迁移时应同步更新并审计。
99. Mention Gate
群聊中设置 requireMention 可避免 Agent 处理所有消息。仍需注意：
• 引用回复是否算 Mention； • Thread 行为； • Bot 别名； • 管理命令权限； • 非 Mention 消息是否进入 Room Context； • 恶意群成员是否可诱导高权限 Tool。
100. Telegram 配置流程
典型流程：
1. 创建 Bot 并获取 Token； 2. 将 Token 放入 Secret/Config； 3. 启动 Gateway； 4. openclaw channels status --probe；5. 给 Bot 发首条 DM； 6. 查看并批准 Pairing； 7. 测试文本、文件和停止命令； 8. 配置群组 Allowlist/Mention。
101. WhatsApp 注意事项
WhatsApp 通常以 Linked Device 方式连接。建议使用独立号码，而不是关键个人主号码。需要考虑：
• 扫码身份； • Session 持久化和备份； • 平台风控； • Self-chat 限制； • 群组 ID； • 断线重连； • 联系人隐私。
102. Discord/Slack/Teams
企业协作 Channel 重点：
• Workspace/Guild/Tenant Allowlist； • Role Routing； • Mention Gate； • Thread 与 Forum； • Interactive Approval； • Slash Command； • Bot Scope； • 消息历史； • 文件与链接预览； • 审计和数据驻留。
103. Automations
OpenClaw 内置 Scheduler 可持久化 Job，在指定时间唤醒 Agent，并将结果发送到：
• Chat Channel； • Webhook； • 无外部投递，仅更新状态。
openclaw automations --help# openclaw cron 是兼容别名104. Automation 设计
定时任务需定义：
• 时区； • 计划与错过执行策略； • 目标 Agent/Session； • Input； • Delivery； • Tool 权限； • 超时和预算； • 幂等键； • 失败通知； • 暂停与删除。
105. Automation 风险
无人值守任务尤其需要：
• 禁止或审批写 Tool； • Standing Grant 生命周期； • 输出接收人 Allowlist； • 防止 Prompt/数据源注入； • 费用配额； • 重复执行保护； • 外部 Webhook 签名； • 完整审计。
106. Heartbeat
Heartbeat 用于周期性唤醒、状态检查或主动提醒。应限制活跃时间和可见性，避免：
• 夜间骚扰； • 空任务持续消耗； • 每次读取全部 Memory； • 重复告警； • 自动执行危险动作。
复杂日程应使用独立 Automation Job。
107. Nodes
Node 将其他设备或工作机连接到 Gateway，可提供：
• Worker Session Hosting； • 本地模型推理； • MCP Server 和 Skill； • 文件传输； • Camera、Screen、Canvas、Voice； • 设备本地动作； • Codex/Claude/OpenCode/Pi Session Catalog。
Node 是新的执行信任边界。
108. Node 安全
• Pairing 和设备身份； • TLS/私网； • Capability Allowlist； • 文件目录根限制； • Session Placement； • Container Isolation； • 设备锁屏和本地用户； • 远程撤销； • 软件更新； • 节点丢失响应。
109. Session Placement
将任务放到 Node 时需要考虑：
• OS/架构； • 必需二进制； • GPU/CPU/内存； • 数据位置； • Workspace/Repo； • 网络； • Sandbox； • 并发容量； • 节点离线恢复。
调度不能把敏感任务放到不可信个人设备。
110. Remote Access
优先方案：
• SSH Tunnel； • Tailscale/私网； • 受控反向代理； • Gateway Auth； • 防火墙 Allowlist。
绝对不要将无认证的 0.0.0.0:18789 直接暴露公网。
111. Docker 部署
Docker 是可选安装方式，适合隔离、临时环境或服务器。注意：
• 容器内 loopback只对容器自身；• 即使使用 lanbind，也要让宿主发布端口保持私有；• Config 单文件 Bind Mount 替换可能让容器继续读取旧 inode； • State 和 Workspace 使用持久卷； • 所需 CLI 构建进镜像； • Sandbox Docker Socket 单独治理。
112. Ansible 部署
官方 Ansible 路线适合生产服务器自动化，价值包括：
• 可重复安装； • 安全基线； • Service 管理； • 配置模板； • 更新； • 主机防火墙与依赖。
应审查 Playbook 版本并在 Staging 验证。
113. 反向代理
代理需正确处理：
• WebSocket Upgrade； • 长连接超时； • TLS； • 身份认证； • Origin； • Real IP 信任链； • 请求大小； • Rate Limit； • 日志脱敏。
错误信任 X-Forwarded-For 等头可能导致身份/限流绕过。
114. 一个 Gateway 一个信任边界
官方安全模型假定同一 Gateway 的 Operator 或团队成员互相信任。若存在：
• 客户与客户； • 员工与外部访客； • 家庭与公开社区； • 生产与不可信测试；
应拆分 Gateway、凭证，最好使用独立 OS 用户或主机。
115. Threat Model
主要攻击面：
1. Channel 冒充和未授权入站； 2. Direct/Indirect Prompt Injection； 3. Tool 滥用； 4. Browser 会话和 Cookie 泄漏； 5. Exec/文件越界； 6. 恶意 Skill/Plugin/MCP； 7. Session 跨用户读取； 8. Secret 和日志泄漏； 9. Node 被攻陷； 10. 资源耗尽和费用攻击。
116. Prompt Injection
不可信输入可来自：
• Chat 用户； • 群消息； • 网页； • 邮件与文档； • Tool/MCP 返回； • 图片 OCR； • Skill/Plugin 指令； • Memory。
攻击目标通常是诱导 Agent 读取 Secret、调用 Tool 或跨会话发送数据。
117. Injection 防护
• 最小 Tool Profile； • Tool 端确定性鉴权； • Sandbox； • Message 跨上下文限制； • Session Visibility 最小化； • Browser 网络限制； • 高风险审批； • Memory 写入审查； • Skill/Plugin 供应链治理； • 安全评测和 Trace。
System Prompt 不能独立解决 Injection。
118. Secrets
Secret 可能存在于：
• Auth SQLite Store； • 环境变量； • SecretRef； • Channel Credential； • Browser Cookie； • Node Token； • Plugin 配置； • Shell 环境。
不要把 Secret 写进 Workspace、Prompt、Memory、Git 或诊断报告。
119. Logs 与 Transcripts
日志和会话可能包含：
• 用户消息； • 文件内容； • Tool 参数/结果； • 路径和命令； • Provider 错误； • Model Usage； • Channel/用户 ID。
需要访问控制、脱敏、轮转、保留和删除策略。
120. Security Audit
openclaw security audit审计应关注：
• Gateway 暴露； • DM/Group Policy； • Tool 权限； • Sandbox； • Browser； • Proxy/Real IP； • Plugin/Skill； • 文件权限； • Credential； • 版本和已知风险。
Audit 通过不代表在所有威胁模型下绝对安全。
121. Hardened Baseline
公开或共享 Agent 的最低建议：
• Gateway 仅本地/私网； • DM 使用 Pairing/Allowlist； • Group Allowlist + Mention； • 独立低权限 Agent； • Sandbox mode all； • Workspace ro/none；• 禁用 Exec/Process/Browser/跨会话消息； • Session Visibility self/tree；• Provider/Tool 额度； • 定期 Security Audit。
122. 备份
需要一致备份：
• Config； • State Directory/SQLite； • 每个 Agent Directory； • Workspace 与 Memory； • 自定义 Skill/Plugin； • Automation； • Browser Profile（仅在确有需要且加密）； • 部署和版本信息。
备份包含高敏凭证，必须加密并限制访问。
123. 恢复演练
恢复步骤应在隔离主机验证：
1. 安装匹配版本； 2. 停止 Gateway； 3. 恢复 Config、State、Agent 和 Workspace； 4. 修复文件 Owner/Mode； 5. 运行 Doctor； 6. 启动并检查 Model/Channel； 7. 验证 Session/Memory； 8. 撤销测试发送； 9. 记录 RTO/RPO。
124. 更新策略
OpenClaw 发布很快，生产应：
• 固定版本而不是永久跟随 latest；• 阅读 Release Notes； • 备份； • Staging 升级； • 运行 Doctor； • 验证 Channel、Model、Tool、Plugin、Session； • Canary； • 保留可回退包和数据库备份； • Plugin SDK 逐版本兼容测试。
125. Extended-stable 与 Release Channel
若团队需要更低变更频率，应评估官方 Extended-stable/LTS 等效发布线。稳定线仍需安全更新，不代表配置、Plugin 或自定义集成永远兼容。
126. 源码仓库概览
当前仓库是以 TypeScript/Node.js 为核心的多包项目，主要目录可按职责理解：
src/ Gateway、CLI、Agent、Channel、Tool 等核心实现packages/ 可复用包与 SDKapps/ 原生/平台应用extensions/ Plugin 与外部能力skills/ 内置 Skillui/ Control UIcrates/ Rust 等原生组件deploy/ 部署资产docs/ 官方文档源test/ qa/ 测试和质量体系scripts/ 构建、发布和维护脚本以实际 v2026.9.8 Tag 树为准。
127. 源码阅读路线
推荐顺序：
1. README.md、VISION.md、AGENTS.md；2. package.json与 pnpm workspace；3. CLI Entry； 4. Gateway 启动与 WebSocket； 5. Config Loader/Schema； 6. Channel Registry 与 Routing； 7. Session Store； 8. Embedded Agent Runtime/Loop； 9. Tool Registry/Policy； 10. Plugin SDK； 11. UI 与 Apps； 12. Tests。
128. Gateway 启动调用链
源码分析时寻找：
CLI parse -> resolve profile/config/state -> acquire state lock -> open/migrate SQLite -> load config + secrets -> discover plugins/skills/providers -> build registries -> start WebSocket/HTTP control plane -> connect channels -> start scheduler/maintenance -> publish health关注失败时清理和部分启动状态。
129. 入站消息调用链
Channel Adapter receives event -> verify platform event -> normalize sender/peer/thread/media -> DM/group access policy -> pairing/mention/command gate -> deterministic agent binding -> session key resolution -> queue admission -> embedded/external runtime -> delivery to originating channel安全审查应在每个箭头查找信任边界。
130. Tool 调用链
Model emits tool call -> schema validation -> resolve tool owner/plugin -> effective policy -> sender/owner authorization -> execution permission/approval -> sandbox/host/node placement -> AbortSignal + timeout -> execute -> normalize result -> persist event -> return to modelTool 描述不能承担上述确定性控制。
131. State 与 SQLite
SQLite 持有共享状态、Session、Agent Auth/模型等不同范围的数据。源码审查关注：
• DB 文件划分； • WAL 和锁； • Migration； • Writer Queue； • Transaction Boundary； • Index； • Retention； • Crash Recovery； • 跨版本兼容。
不要在 Gateway 运行时直接手工修改数据库。
132. 配置迁移
OpenClaw 使用 Doctor/Updater 将旧配置迁移到新 Schema，例如旧 Agent List 到 keyed entries。迁移原则：
• 先备份； • 使用版本自带工具； • 审查 Diff； • 不手工猜字段； • Config 和 DB State 一致迁移； • 验证路由与权限； • 保留回滚点。
133. 测试体系
源码贡献至少包含：
• Unit Test； • Config Schema/Migration Test； • Channel Contract Test； • Agent Loop/Queue Test； • Tool Policy/Sandbox Test； • Session/SQLite Test； • Plugin Compatibility Test； • UI Test； • Docker/System Test； • Security Regression。
134. 本地源码验证
pnpm installpnpm buildpnpm ui:buildpnpm test具体脚本以目标 Tag 的 package.json 和贡献文档为准。提交前还应运行格式、Lint、Typecheck 和相关定向测试。
135. 可观测性
至少监控：
• Gateway Up/Restart； • WebSocket Client； • Channel Connection/Delivery； • Session Queue Depth； • Agent Run 数、成功率和时长； • Provider 延迟、429/5xx； • token 与费用； • Tool 成功率和审批； • SQLite 延迟/WAL/磁盘； • Sandbox 创建和失败； • Automation 延迟和积压。
136. 日志命令
openclaw logs --followopenclaw statusopenclaw status --allopenclaw status --deepopenclaw gateway statusopenclaw health --verbose对外分享报告前确认 Token、路径、用户标识和消息内容已脱敏。
137. 首分钟排障
openclaw triageopenclaw statusopenclaw status --allopenclaw gateway probeopenclaw gateway statusopenclaw doctoropenclaw channels status --probeopenclaw logs --follow按顺序执行可快速区分 Gateway、配置、模型、Channel 和投递问题。
138. Gateway 无法启动
检查：
• Node 版本和 SQLite 链接； • 端口占用； • State Lock； • Config Schema； • 文件权限； • Plugin 加载； • DB Migration； • 环境变量； • Service 与手工进程是否重复； • 日志首个根因而非后续连锁错误。
139. Gateway 正常但不回复
openclaw models statusopenclaw channels status --probeopenclaw logs --follow常见原因：模型 Auth 未加载、Sender 未 Pair、Allowlist/Mention 阻止、Delivery 关闭、Session Run 卡住或 UI Token 错误。
140. Agent 缺少 Tool
检查：
• tools.profile；• 全局 Allow/Deny； • per-agent override； • Plugin 是否安装/启用； • Sandbox Gate； • Execution Permission； • Provider 是否支持 Tool； • Skill 是否因缺少二进制被过滤； • 当前 Sender 是否 Owner。
141. Context Overflow
处理：
• 查看 /context list/detail；• 检查大 Tool Result； • 精简 Workspace Bootstrap； • 清理重复历史； • 使用 Compaction safeguard； • 把大输出写文件； • 降低 Skill Catalog/Tool Schema； • 新建 Session； • 选择更大 Context Model。
142. Memory 不生效
检查：
• Agent 是否使用预期 Workspace； • 文件名和路径； • MEMORY.md 是否超预算被截断； • Daily Note 是否被索引； • Memory Plugin； • Session 是否 /new/reset；• 文件权限； • Agent 是否实际执行了写入； • 多 Agent 是否写错 Workspace。
143. Browser 失效
• Browser Plugin/Profile 是否启用； • Chromium 是否可用； • 是否引用 stale element ref； • 重新 Snapshot； • 页面是否出现 CAPTCHA/MFA； • Sandbox Browser Image 是否过期； • 网络/Proxy； • 下载目录权限； • 站点反自动化。
验证码等人工阻断应交给用户，而不是尝试绕过。
144. Channel 断线
• Token/OAuth/Linked Device； • Provider 状态； • DNS/TLS/Proxy； • Rate Limit； • Channel Plugin 版本； • Gateway Restart； • Account 被踢下线； • Webhook/Socket 模式； • 平台权限变化。
先使用 channels status --probe，再看 Channel 专属日志。
145. SQLite/State 故障
• 立即停止重复 Gateway； • 备份 DB/WAL/SHM； • 检查磁盘空间和权限； • 使用官方 Doctor/恢复流程； • 不用文本编辑器修改 DB； • 若需恢复，先复制到隔离环境； • 验证 Session、Auth 和 Automation 完整性； • 轮换可能损坏/泄漏的凭证。
146. 性能优化
• 使用推荐 Node 版本； • 限制并发 Agent Run； • 控制 Session 历史和 Tool 输出； • 精简 Bootstrap/Skill； • 监控 SQLite 和磁盘； • 为模型设置合理 Context； • 使用 Provider Cache； • 浏览器任务按需启动； • Sandbox 镜像预热； • 分离高负载 Node。
147. 成本控制
• Agent/租户模型 Allowlist； • 主/备用模型路由； • Context 预算； • 最大 Tool/Agent Step； • Automation 配额； • Web/媒体生成限制； • Usage 监控； • 费用告警； • 避免重复会话和无进展循环； • 对公开 Channel 限流。
148. 生产部署架构
Private Network ├── Reverse Proxy / Tailscale ├── OpenClaw Gateway（non-root） │ ├── State/SQLite encrypted volume │ ├── Private workspaces │ └── Plugin/Skill allowlist ├── Sandbox Engine │ └── restricted images + egress ├── Worker Nodes ├── Model Gateway / Providers └── Monitoring + Backup + AuditExternal Channels -> pairing / allowlists / mention gates149. 家庭部署建议
• 主人 Agent 与家庭 Agent 分离； • 家庭 Agent 只读/消息工具； • 禁用 Exec、Browser 和跨 Provider 发送； • 每个成员按 Sender 隔离 Session； • 群聊 Require Mention； • 不共享个人 Browser Cookie； • 财务、门锁和购买操作必须审批； • 家庭成员知晓数据保留方式。
150. 企业团队部署建议
• 一个互信团队一个 Gateway，跨部门进一步隔离； • 企业 SSO/私网； • 工作和个人 Provider 账号分离； • Repo/Tool 最小权限； • 生产环境 Tool 默认只读； • Plugin/Skill 供应链审批； • Session Retention 和 DLP； • 变更、发送和执行审计； • 定期红队和恢复演练。
151. Coding Agent 使用建议
• 独立 Workspace/Repo clone； • Sandbox rw仅映射目标 Repo；• 不挂载 SSH 主目录； • Git Credential 最小化； • 网络按域名允许； • 写前检查 dirty tree； • Patch 后编译测试； • 禁止自动 push/merge，除非明确授权； • 最终展示 Diff 和测试结果。
152. 常见反模式
• Gateway 无认证暴露公网； • 互不信任用户共享一个主 Session； • 把 Workspace 当沙箱； • 禁用 write 却保留无限制 Exec； • 公开 Channel 使用 full Tool Profile； • Agent-to-Agent 和 Session Visibility 保持全开放； • 使用日常 Browser Profile 自动化不可信网页； • 自动安装 ClawHub Skill； • 所有 Agent 复用 agentDir/Auth； • 永久跟随 latest 且无 Staging； • 只备份 Memory、不备份 State； • 把 Prompt 规则当权限系统。
153. 安全上线检查清单
Gateway 与网络
• [ ] 仅 loopback/私网绑定； • [ ] 远程访问有隧道、TLS 和认证； • [ ] 防火墙和代理信任链正确； • [ ] 每个敌对信任域使用独立 Gateway/OS 用户。
Channel 与 Session
• [ ] DM 使用 Pairing/Allowlist； • [ ] Group Allowlist + Mention； • [ ] Session Scope 不跨用户； • [ ] Session Visibility 最小化； • [ ] 跨 Agent/Provider 消息受限。
Tool 与执行
• [ ] 最小 Tool Profile； • [ ] Exec、Browser、Message、Gateway 权限已审查； • [ ] 非可信 Agent 使用 Sandbox； • [ ] 写操作审批、幂等和审计； • [ ] Tool 有超时、输出和循环限制。
数据与供应链
• [ ] Secret 不进入 Workspace/日志； • [ ] Plugin/Skill/MCP 来源受控； • [ ] State/Workspace 备份加密； • [ ] Session/Memory 有保留删除策略； • [ ] 运行 openclaw security audit。
154. 运维上线检查清单
• [ ] Node/OpenClaw/Plugin 版本锁定； • [ ] Gateway 由 Supervisor 管理； • [ ] 健康检查、日志和告警； • [ ] Model/Channel Probe； • [ ] SQLite 磁盘和备份监控； • [ ] Automation 失败通知； • [ ] Provider 费用和限流告警； • [ ] Staging、Canary 和回滚； • [ ] 灾难恢复演练； • [ ] Runbook 和 Owner 明确。
155. 学习路线
1. 本地安装并只使用 Control UI； 2. 理解 Config、State、Workspace； 3. 配置一个模型和 Telegram Pairing； 4. 学习 Session、Context、Memory； 5. 使用 coding Profile 和受控文件工具； 6. 开启 Sandbox； 7. 配置 Browser/Web； 8. 创建自定义 Skill； 9. 多 Agent Binding； 10. Plugin/Node/Automation； 11. 安全加固和生产运维； 12. 阅读源码调用链。
156. 核心结论
1. Gateway 是 OpenClaw 的状态权威与控制平面，统一管理 Channel、Session、Agent、Tool 和任务。 2. Agent 是 Workspace、Memory、Auth、Session 和权限的完整作用域，而非仅一段 Persona。 3. Workspace 是默认工作目录，不是沙箱；Exec 可绕过普通文件工具限制。 4. Tool Policy、Sandbox、审批和业务鉴权必须同时存在，Prompt 不能替代任何一层。 5. 一个 Gateway 只适合一个互信边界；敌对租户应拆分 Gateway、凭证和主机身份。 6. Channel 路由和安全身份由宿主确定性控制，不由模型选择。 7. Session、Context、Memory 和 Workspace 是四个不同概念，必须正确分层。 8. Skill、Plugin、MCP 和 Browser 都是供应链与数据外传攻击面。 9. OpenClaw 更新快，生产必须锁定版本、备份、Staging、Doctor、Canary 和回滚。
157. 官方资料
• 官方文档：https://docs.openclaw.ai/ • 官方仓库：https://github.com/openclaw/openclaw • Releases：https://github.com/openclaw/openclaw/releases • Architecture：https://docs.openclaw.ai/concepts/architecture • Agent Runtime：https://docs.openclaw.ai/concepts/agent • Agent Loop：https://docs.openclaw.ai/concepts/agent-loop • Workspace：https://docs.openclaw.ai/concepts/agent-workspace • Context：https://docs.openclaw.ai/concepts/context • Compaction：https://docs.openclaw.ai/concepts/compaction • Sessions：https://docs.openclaw.ai/concepts/session • Memory：https://docs.openclaw.ai/concepts/memory • Multi-agent：https://docs.openclaw.ai/concepts/multi-agent • Skills：https://docs.openclaw.ai/tools/skills • Browser：https://docs.openclaw.ai/tools/browser • Exec：https://docs.openclaw.ai/tools/exec • Web Tools：https://docs.openclaw.ai/tools/web • Nodes：https://docs.openclaw.ai/nodes • Channels：https://docs.openclaw.ai/channels • Pairing：https://docs.openclaw.ai/channels/pairing • Automations：https://docs.openclaw.ai/automation/cron-jobs • Plugin SDK：https://docs.openclaw.ai/plugins/sdk-overview • Security：https://docs.openclaw.ai/gateway/security • Threat Model：https://docs.openclaw.ai/security/THREAT-MODEL-ATLAS • Docker：https://docs.openclaw.ai/install/docker • Troubleshooting：https://docs.openclaw.ai/help/troubleshooting
附录 A：最小安全个人配置
{ agents: { defaults: { workspace: "~/.openclaw/workspace", model: { primary: "your-provider/your-model" }, sandbox: { mode: "all", scope: "agent", workspaceAccess: "rw", }, }, entries: { main: { identity: { name: "MyClaw", theme: "private technical assistant", emoji: "🦞", }, }, }, }, tools: { profile: "coding", deny: ["message", "gateway"], loopDetection: { enabled: true }, },}首次只在本机 Control UI 使用；确认 Sandbox、Tool 和日志后再连接外部 Channel。
附录 B：共享只读 Agent 配置思路
{ agents: { ownership: "explicit", entries: { public_help: { workspace: "~/.openclaw/workspace-public-help", sandbox: { mode: "all", scope: "agent", workspaceAccess: "ro", }, tools: { allow: ["read", "web_search", "web_fetch"], deny: [ "exec", "process", "write", "edit", "apply_patch", "browser", "message", "gateway" ], }, }, }, }, tools: { sessions: { visibility: "self" }, agentToAgent: { enabled: false }, },}字段应通过目标版本 Doctor 校验，Channel 还需单独配置 Pairing/Allowlist。
附录 C：故障报告模板
OpenClaw Version：Node Version：OS/Architecture：Install Method：npm / git / Docker / AnsibleProfile：Gateway Mode：foreground / serviceChannel：Agent ID：Model Route：现象：首次发生时间：可否复现：最近变更：openclaw status --all：openclaw gateway status：openclaw doctor：openclaw channels status --probe：相关日志（已脱敏）：预期行为：实际行为：已尝试操作：附录 D：安全事件响应模板
事件：未授权消息 / Tool 滥用 / Secret 泄漏 / 跨 Session / 恶意 Plugin发现时间：Gateway/Profile/Agent：影响 Channel/User/Session：立即措施：1. 停止 Gateway 或禁用相关 Channel/Tool2. 撤销 Pairing/Token/Credential3. 隔离 Host/Node/Sandbox4. 保存日志和状态副本调查：- 入站来源- Session/Tool 轨迹- Plugin/Skill/MCP- 文件和网络访问- 数据外传范围修复：- 配置/代码/权限- 凭证轮换- 数据通知和删除- 新增安全测试- 恢复与复盘附录 E：源码审查清单
[ ] Config Schema 与迁移[ ] State Lock、SQLite Transaction、WAL[ ] Channel Event 验证[ ] Pairing/Allowlist/Mention[ ] Binding 与 Session Key[ ] Queue、Steering、Abort、Timeout[ ] System Prompt 与 Context Assembly[ ] Compaction 与 Memory Flush[ ] Tool Schema、Policy、Approval[ ] Sandbox/Host/Node Execution[ ] Plugin Discovery 与生命周期[ ] SecretRef 与日志脱敏[ ] WebSocket Auth 与代理信任[ ] Update、Backup、Recovery