📑 目录

• 第一章 系统概述
• 第二章 整体架构
• 第三章 Gateway 核心组件
• 第四章 工具系统
• 第五章 会话管理
• 第六章 配置系统
• 第七章 安全与权限
• 第八章 与传统工具对比
• 第九章 Agent 工作空间

第一章 系统概述

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

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

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

第二章 整体架构

2.1 架构概览

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

层级	组件	职责
用户交互层	Channels	WhatsApp、Telegram、Discord、iMessage 等渠道集成
路由层	Gateway	消息路由、会话管理、工具调度
Agent 层	Agent Runtime	LLM 推理、工具调用、任务执行
工具层	Tools	文件操作、命令执行、浏览器控制等
扩展层	Skills & Plugins	自定义技能和插件扩展
资源层	Workspace & Memory	工作空间、记忆文件、配置存储

2.2 Gateway 核心地位

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

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

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

第三章 Gateway 核心组件

3.1 生命周期管理

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

# 启动 Gateway
openclaw gateway --port 18789

# 查看详细状态
openclaw gateway status --deep

# 重启 Gateway
openclaw 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 应直接使用这些工具。

核心工具列表：

工具组	工具名称	用途
文件系统	read	读取文件内容
	write	创建或覆盖文件
	edit	精确编辑文件内容
	apply_patch	应用代码补丁
运行时	exec	执行 Shell 命令
	process	管理后台进程
会话管理	sessions_list	列出会话
	sessions_history	获取会话历史
	sessions_send	发送消息到会话
	sessions_spawn	创建子 Agent 会话
	session_status	查看会话状态
记忆	memory_search	语义搜索记忆
	memory_get	获取记忆片段
Web	web_fetch	获取网页内容
	web_search	网络搜索
UI 自动化	browser	浏览器控制
画布	canvas	画布渲染与控制
节点	nodes	控制配对节点设备
消息	message	发送消息和频道操作
定时任务	cron	管理定时任务和提醒

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	payload.kind	说明
main	systemEvent	在主会话中运行，通过心跳提示触发
isolated	agentTurn	在隔离会话中运行，独立执行

// 主会话提醒
{
  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_token}",
      password: "${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"]
    }
  }
}

第八章 与传统工具对比

功能	OpenClaw	传统 CLI 工具
交互方式	自然语言对话	命令行语法
上下文理解	多轮对话记忆	无状态执行
错误处理	自动诊断修复	手动排查
多渠道支持	WhatsApp/Telegram/Discord 等	终端单一界面
任务编排	自动拆解多步骤任务	手动编写脚本
学习记忆	MEMORY.md 长期记忆	无记忆能力
扩展能力	Skills/Plugins 生态系统	手动编写工具

第九章 Agent 工作空间

9.1 工作空间位置

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

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

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

9.2 工作空间文件

文件	用途	加载时机
AGENTS.md	Agent 操作指令和记忆使用规则	每会话
SOUL.md	角色设定、语气和边界	每会话
USER.md	用户信息和称呼方式	每会话
IDENTITY.md	Agent 名称、风格和 emoji	每会话
TOOLS.md	本地工具和约定说明	每会话
HEARTBEAT.md	心跳任务检查清单	心跳时
MEMORY.md	长期记忆（主会话）	主会话
BOOTSTRAP.md	首次运行仪式（仅新建时）	首次运行

9.3 记忆系统

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

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

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

2. 长期记忆（MEMORY.md）

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

附录：快速参考

常用命令

# Gateway 管理
openclaw gateway status
openclaw gateway restart
openclaw gateway stop

# 日志查看
openclaw logs --follow
openclaw logs --level debug

# 渠道管理
openclaw channels status
openclaw channels login

# 会话管理
openclaw sessions list
openclaw sessions cleanup --dry-run

# 健康检查
openclaw doctor

会话控制命令

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