OpenClaw 架构深度解析 (Architecture Deep Dive)

本文将深入 OpenClaw 的运行时架构，解析其核心组件、通信协议、状态管理以及沙箱隔离机制。

1. 核心架构总览 (Core Architecture)

OpenClaw 是一个基于 Node.js 的模块化 Agent 运行时环境，其设计核心是 Gateway-Session-Skill 三层架构。

1.1 运行时模型 (Runtime Model)

OpenClaw 并非单一的大型应用，而是一组松耦合的服务组件：

• Gateway (Daemon): 守护进程，负责网络通信、认证、以及 Skill 进程管理。它是一个无状态的 WebSocket 服务器。
• Session (Stateful Context): 每一个对话、每一个 Agent 实例都是一个独立的 Session。Session 维护了上下文窗口 (Context Window)、短期记忆以及当前的执行状态。
• Skill (Capabilities): 独立加载的功能模块。每个 Skill 可以包含多个 Tool。
• Sandbox (Security): 所有 Tool 的执行都在受限的沙箱环境中运行，防止越权操作。

graph TD
    User[Client / Telegram] -->|WebSocket / API| Gateway
    Gateway -->|Spawn| SessionManager
    SessionManager -->|Context| LLM[Model Provider]
    SessionManager -->|Call| SkillLoader
    SkillLoader -->|Load| Sandbox[Secure Sandbox]
    Sandbox -->|Exec| Tool[Custom Tool]

1.2 通信协议 (Communication Protocol)

OpenClaw 使用基于 WebSocket 的 JSON-RPC 2.0 变体进行内部通信。

• Upstream (Client -> Gateway): 指令发送 (Command)、心跳 (Heartbeat)、配置更新 (Config Patch)。
• Downstream (Gateway -> Client): 实时回复 (Streaming Token)、工具调用日志 (Tool Logs)、状态变更 (Status Update)。
• Inter-Process (Gateway <-> Agent): 使用 Node.js 的 child_process 或 worker_threads 进行通信，保证主进程稳定。

---

2. 网关与认证 (Gateway & Auth)

2.1 网关服务 (Gateway Service)

Gateway 是 OpenClaw 的神经中枢，默认监听 18789 端口。

• mDNS Discovery: 支持 Bonjour/Zeroconf 协议，局域网内的客户端（如 iOS App）可自动发现 Gateway。
• HTTP/WebSocket: 同时支持 REST API (用于简单控制) 和 WebSocket (用于实时流)。

2.2 安全认证 (Security)

OpenClaw 采用 Bearer Token 认证机制。

• Token 生成: 首次启动时自动生成随机 Token，存储在 ~/.openclaw/openclaw.json 中。
• 权限控制: Gateway 对外暴露的 API 受到严格的权限控制。未授权的连接会被立即断开。
• Localhost 绑定: 默认情况下，Gateway 仅绑定在 127.0.0.1，防止外网扫描。生产环境建议配合 Caddy/Nginx 反向代理 + Tailscale VPN 使用。

---

3. 会话管理 (Session Management)

3.1 上下文窗口管理 (Context Window)

LLM 的上下文窗口是昂贵且有限的资源。OpenClaw 实现了智能的 Context Pruning (上下文剪枝) 策略：

1. Sliding Window (滑动窗口): 保留最近 N 轮对话，丢弃旧对话。
2. Summary Compression (摘要压缩): 定期将旧对话总结为摘要，保留核心信息，释放 Token。
3. Tool Output Truncation (工具输出截断): 如果 read_file 读取了 10MB 的日志，OpenClaw 会自动截断中间部分，只保留头部和尾部，防止撑爆 Context。

3.2 状态持久化 (Persistence)

• Hot State: 活跃 Session 存储在内存中，保证极速响应。
• Cold Storage: 空闲 Session 会被序列化为 JSONL 文件，存储在 workspace/sessions/ 目录下。
• Recovery: Gateway 重启后，会自动从磁盘加载最近活跃的 Session，实现“无感重启”。

---

4. 技能与沙箱 (Skills & Sandbox)

4.1 技能加载机制 (Skill Loader)

OpenClaw 的 Skill 系统基于文件系统路由：

• Discovery: 扫描 /skills 目录下的所有子目录。
• Validation: 检查 SKILL.md (描述文件) 和 package.json (依赖声明)。
• Hot Reload: 支持热重载。修改 Skill 代码后，无需重启 Gateway，通过 openclaw reload 即可生效。

4.2 沙箱隔离 (Sandbox Isolation)

为了防止恶意 Skill 破坏系统，OpenClaw 提供了多级沙箱：

1. Level 1 (Process): 独立的 Node.js 进程，Crash 不影响主 Gateway。
2. Level 2 (VM): 使用 Node.js vm 模块隔离全局变量 (Global Scope)。
3. Level 3 (Permission):
   • Network: 白名单控制可访问的域名。
   • Filesystem: 限制只能读写 workspace 目录，禁止访问 /etc 或 /var。
   • Command: 禁止执行危险命令 (如 rm -rf /)，除非显式配置 Allowlist。

---

👉 下一步：生产环境部署指南