OpenClaw 系统架构说明文档

第一章 系统概述

OpenClaw 是一个创新的分布式 AI Agent 运行框架，采用「本地优先（Local-First）」的设计理念。它通过集中式 Gateway 与多渠道集成的混合架构，实现了对多平台 AI 智能体的高效管理与调度。

本文档详细阐述 OpenClaw 的系统架构设计，涵盖 Gateway 核心组件、工具系统、会话管理、配置系统、安全与权限模型等核心模块。所有技术描述均基于官方文档和实际实现，确保技术准确性。

📌 文档说明：本文档旨在为技术架构师、开发人员和运维工程师提供全面的技术参考，帮助理解 OpenClaw 的设计理念、架构组成和最佳实践。

第二章 整体架构

2.1 架构概览

OpenClaw 采用分层架构设计，主要包含以下核心组件：

2.2 Gateway 核心地位

Gateway 是 OpenClaw 的核心中枢，负责：

• 消息路由
  ：将来自不同渠道的消息路由到正确的会话
• 会话管理
  ：维护会话状态、历史记录和上下文
• 工具调度
  ：管理工具调用权限和执行策略
• 配置管理
  ：支持热重载配置变更
• 认证授权
  ：处理客户端认证和权限控制

Gateway 默认运行在端口 18789，支持 WebSocket 和 HTTP API 两种访问方式。

第三章 Gateway 核心组件

3.1 生命周期管理

Gateway 支持多种运行模式和管理命令：

# 启动 Gatewayopenclaw gateway --port 18789# 查看详细状态openclaw gateway status --deep# 重启 Gatewayopenclaw gateway restart# 查看日志openclaw logs --follow

热重载模式：

• off
   - 不重载配置
• hot
   - 仅应用安全变更
• restart
   - 需要重启时自动重启
• hybrid
  （默认）- 安全变更热应用，其他情况重启

3.2 认证机制

Gateway 默认需要认证，支持两种认证方式：

• Token 认证
  ：通过 gateway.auth.token 或 OPENCLAW_GATEWAY_TOKEN 配置
• 密码认证
  ：通过 gateway.auth.password 或 OPENCLAW_GATEWAY_PASSWORD 配置

⚠️ 安全提示：远程访问 Gateway 时，建议使用 Tailscale/VPN 或 SSH 隧道，避免直接暴露公网。

3.3 会话存储

Gateway 使用两层持久化存储管理会话：

1. 会话存储（sessions.json）

• 位置：~/.openclaw/agents/<agentId>/sessions/sessions.json
• 存储会话元数据：sessionKey、最后活动时间、Token 计数等
• 支持手动编辑和清理

2. 对话记录（*.jsonl）

• 位置：~/.openclaw/agents/<agentId>/sessions/<sessionId>.jsonl
• 追加式记录完整对话历史和工具调用
• 支持树状结构（父子消息关系）

第四章 工具系统

4.1 工具概览

OpenClaw 提供第一类 Agent 工具，替代了旧的 openclaw-* 技能。工具是类型化的，无需 shell 调用，Agent 应直接使用这些工具。

核心工具列表：

4.2 工具配置文件

OpenClaw 支持通过工具配置文件限制可用工具：

{  tools: {    profile: "coding",  // 基础配置    deny: ["group:runtime"],  // 拒绝运行时工具    byProvider: {      "google-antigravity": { profile: "minimal" }    }  }}

预定义配置文件：

• minimal
   - 仅 session_status
• coding
   - 文件系统 + 运行时 + 会话 + 记忆 + 图像工具
• messaging
   - 消息工具组
• full
   - 无限制（默认）

工具组缩写：

• group:runtime
   - exec, bash, process
• group:fs
   - read, write, edit, apply_patch
• group:sessions
   - sessions_*
• group:memory
   - memory_search, memory_get
• group:web
   - web_search, web_fetch
• group:ui
   - browser, canvas

第五章 会话管理

5.1 会话路由

OpenClaw 使用 sessionKey 唯一标识每个会话。会话路由策略由 session.scope 配置：

• per-sender
  （默认）- 每个发送者一个会话
• per-channel
   - 每个频道一个会话
• global
   - 全局单一会话

会话重置触发器可通过 session.resetTriggers 配置，例如 ["/new", "/reset"]。

5.2 上下文压缩

当对话历史超过模型上下文窗口时，OpenClaw 自动进行压缩：

• 自动压缩
  ：当 Token 数接近限制时触发
• 手动压缩
  ：通过 /compact 命令触发
• 压缩策略
  ：保留最近消息，压缩早期对话为摘要

5.3 定时任务会话

Cron 任务支持两种会话目标：

// 主会话提醒{  sessionTarget: "main",  payload: { kind: "systemEvent", text: "提醒文本" }}// 隔离会话任务{  sessionTarget: "isolated",  payload: {     kind: "agentTurn",    message: "执行任务",    model: "anthropic/claude-opus-4-6",    thinking: "high"  }}

第六章 配置系统

6.1 配置文件位置

OpenClaw 配置文件采用分层优先级：

1. 环境变量：OPENCLAW_*
2. 命令行参数：--config, --token
3. Agent 级配置：~/.openclaw/agents/<id>/agent.json
4. 用户级配置：~/.openclaw/openclaw.json
5. 系统级配置：/etc/openclaw/openclaw.json
6. 默认值：内置默认配置

6.2 核心配置项

{  logging: { level: "info" },  agent: {    model: "anthropic/claude-opus-4-6",    workspace: "~/.openclaw/workspace",    thinkingDefault: "high",    timeoutSeconds: 1800,    heartbeat: { every: "30m" },    skipBootstrap: false  },  channels: {    whatsapp: {      allowFrom: ["+15555550123"],      groups: {        "*": { requireMention: true }      }    }  },  routing: {    groupChat: {      mentionPatterns: ["@openclaw", "openclaw"]    }  },  session: {    scope: "per-sender",    resetTriggers: ["/new", "/reset"],    reset: {      mode: "daily",      atHour: 4,      idleMinutes: 10080    }  },  tools: {    profile: "coding",    deny: ["group:runtime"]  },  gateway: {    port: 18789,    bind: "loopback",    reload: { mode: "hybrid" },    auth: {      token: "{SECRET:gateway_password}"    }  }}

6.3 Thinking 级别

OpenClaw 支持控制模型推理深度：

• low
   - 快速响应，适合简单任务
• medium
   - 平衡速度与深度
• high
   - 深度推理，适合复杂任务

可通过 thinkingDefault 配置默认级别，或在对话中使用 /thinking high 临时切换。

第七章 安全与权限

7.1 命令执行安全

OpenClaw 提供多层命令执行安全控制：

执行模式（exec.ask）：

• off
   - 不询问，直接执行（需配合 allowlist）
• on-miss
   - allowlist 未命中时询问
• always
   - 每次执行都询问

允许列表（exec.allowlist）：

{  exec: {    ask: "on-miss",    allowlist: [      "ls*",      "cat*",      "npm install",      "git status"    ]  }}

⚠️ 安全建议：生产环境建议使用 ask: "always" 或严格的 allowlist，避免意外执行危险命令。

7.2 沙箱隔离

OpenClaw 支持沙箱模式限制 Agent 访问范围：

{  agents: {    defaults: {      sandbox: "inherit"  // 或 "require"    }  }}

• inherit
   - 继承父进程权限
• require
   - 强制沙箱隔离

沙箱启用时，工具操作限制在 ~/.openclaw/sandboxes 目录下，除非 workspaceAccess 配置为 "rw"。

7.3 渠道安全

渠道级别的安全控制：

• allowFrom
   - 允许的消息发送者列表
• requireMention
   - 群聊中需要 @ 提及才响应
• mentionPatterns
   - 自定义提及模式

{  channels: {    whatsapp: {      allowFrom: ["+15555550123"],      groups: {        "*": { requireMention: true }      }    }  },  routing: {    groupChat: {      mentionPatterns: ["@openclaw", "openclaw"]    }  }}

第八章 与传统工具对比

第九章 Agent 工作空间

9.1 工作空间位置

工作空间是 Agent 的家目录，用于文件操作和上下文记忆：

• 默认位置
  ：~/.openclaw/workspace
• 环境变量
  ：OPENCLAW_PROFILE 可设置不同配置档
• 配置覆盖
  ：agent.workspace 可自定义路径

💡 建议：将工作空间初始化为 Git 仓库（建议私有），备份 AGENTS.md 和记忆文件。

9.2 工作空间文件

9.3 记忆系统

OpenClaw 的记忆系统包含两个层次：

1. 每日记录（memory/YYYY-MM-DD.md）

• 记录当天的原始活动日志
• 自动创建，无需手动管理

2. 长期记忆（MEMORY.md）

• 存储重要决策、经验教训
• 仅在主会话（与用户直接对话）加载
• 群聊/共享会话不加载（安全考虑）

附录：快速参考

常用命令

# Gateway 管理openclaw gateway statusopenclaw gateway restartopenclaw gateway stop# 日志查看openclaw logs --followopenclaw logs --level debug# 渠道管理openclaw channels statusopenclaw channels login# 会话管理openclaw sessions listopenclaw sessions cleanup --dry-run# 健康检查openclaw doctor

会话控制命令

/new          - 新建会话/reset        - 重置当前会话/compact      - 手动压缩上下文/model        - 切换模型/thinking     - 设置推理级别/status       - 查看会话状态