核心概念

本章将深入介绍 OpenClaw 的核心概念和架构设计，帮助你理解 AI Agent 的工作原理。

架构概览

OpenClaw 采用中心化网关架构，Gateway 是整个系统的核心：

WhatsApp / Telegram / Slack / Discord / 飞书 / 微信 / WebChat
               │
               ▼
┌───────────────────────────────┐
│            Gateway            │
│       (控制平面)               │
│     ws://127.0.0.1:18789      │
└──────────────┬────────────────┘
               │
               ├─ Pi agent (RPC)
               ├─ CLI (openclaw …)
               ├─ WebChat UI
               ├─ macOS app
               └─ iOS / Android nodes

核心设计原则

单一 Gateway：一个主机运行一个 Gateway，它拥有所有消息渠道的连接
WebSocket 通信：所有客户端通过 WebSocket 连接到 Gateway
本地优先：数据存储在本地，无需依赖云服务
自托管：运行在你的硬件上，你的规则

Gateway（网关）

Gateway 是 OpenClaw 的核心组件，是一个长期运行的守护进程。所有渠道连接、会话管理和 Agent 调度都通过 Gateway 处理。

Gateway 的职责

职责	说明
渠道连接	维护 WhatsApp、Telegram、Slack 等渠道的连接
WebSocket 服务	提供控制平面 API，供客户端连接
会话管理	管理 Agent 会话、聊天历史
工具协调	协调工具调用和任务执行
事件推送	向客户端推送事件（消息、状态变化等）

启动 Gateway

# 前台运行
openclaw gateway

# 安装为系统服务
openclaw gateway install

# 启动服务
openclaw gateway start

# 查看状态
openclaw gateway status

# 指定端口
openclaw gateway --port 18789

# 详细日志
openclaw gateway --verbose

访问控制

默认情况下，Gateway 监听 127.0.0.1:18789。可以配置访问控制：

{
  "gateway": {
    "auth": {
      "token": "your-secret-token"
    }
  }
}

或使用环境变量：

export OPENCLAW_GATEWAY_TOKEN="your-secret-token"

配置热加载

Gateway 支持配置热加载，大部分配置更改无需重启：

安全更改会自动热加载
关键更改会自动重启 Gateway
可以通过 gateway.reload 配置调整行为

Agent（智能体）

Agent 是执行任务的 AI"大脑"。每个 Agent 是一个完全独立的作用域。

Agent 的组成

一个 Agent 拥有独立的三要素：

组件	说明	默认位置
工作空间	文件操作目录、配置文件、记忆文件	`~/.openclaw/workspace`
状态目录	认证配置、模型注册、会话数据	`~/.openclaw/agents/main/agent`
会话存储	聊天历史、路由状态	`~/.openclaw/agents/main/sessions`

单 Agent 模式（默认）

默认情况下，OpenClaw 运行单个 Agent：

agentId 默认为 main
会话标识为 agent:main:<mainKey>
工作空间默认为 ~/.openclaw/workspace

工作空间文件

工作空间中包含重要的配置文件：

文件	说明
`AGENTS.md`	Agent 能力说明（自动注入到系统提示词）
`SOUL.md`	Agent 人格定义
`MEMORY.md`	Agent 记忆
`TOOLS.md`	工具配置说明
`USER.md`	用户档案
`IDENTITY.md`	Agent 身份
`HEARTBEAT.md`	心跳任务上下文
`skills/`	自定义技能目录

重要说明

每个 Agent 的工作空间是其默认工作目录，而非硬性沙箱。相对路径会解析到工作空间内，但绝对路径可以访问主机其他位置（除非启用了沙箱）。

模型配置

Agent 使用模型引用来配置 LLM：

格式：provider/model

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "anthropic/claude-sonnet-4"
      }
    }
  }
}

模型引用解析规则：

使用 provider/model 格式配置模型
如果模型 ID 本身包含 /（如 OpenRouter 风格），需要包含提供商前缀
- 例如：openrouter/moonshotai/kimi-k2
如果省略提供商，OpenClaw 会将其视为别名或默认提供商的模型

内置别名：

别名	模型
`opus`	`anthropic/claude-opus-4-6`
`sonnet`	`anthropic/claude-sonnet-4-6`
`gpt`	`openai/gpt-5.2`
`gemini`	`google/gemini-2.5-pro`

注意：别名可在 agents.defaults.models 中自定义配置。如果模型 ID 本身包含 /（如 OpenRouter 风格），必须包含提供商前缀，例如 openrouter/moonshotai/kimi-k2。

模型回退

可以配置模型回退链：

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "anthropic/claude-sonnet-4-6",
        "fallbacks": ["openai/gpt-4o", "google/gemini-2.5-pro"]
      }
    }
  }
}

会话管理

会话标识

会话使用以下格式标识：

agent:<agentId>:<mainKey>

agentId：Agent 标识符
mainKey：会话主键，取决于渠道类型

会话存储

会话记录以 JSONL 格式存储：

~/.openclaw/agents/<agentId>/sessions/<sessionId>.jsonl

流式响应（Steering）

当队列模式为 steer 时，入站消息会被注入到当前运行中：

排队的 steering 消息会在当前助手回合完成工具调用后、下一个 LLM 调用之前发送
Steering 不会跳过当前助手消息的剩余工具调用

当队列模式为 followup 或 collect 时：

入站消息会被保持到当前回合结束
然后用排队的消息开始新的 Agent 回合

块流式输出（Block Streaming）

块流式输出在块完成时立即发送已完成的助手块：

默认关闭：agents.defaults.blockStreamingDefault: "off"
通过 agents.defaults.blockStreamingBreak 调整边界（text_end 或 message_end）
使用 agents.defaults.blockStreamingChunk 控制软块分块（默认 800-1200 字符）
使用 agents.defaults.blockStreamingCoalesce 合并流式块以减少单行消息

注意：非 Telegram 渠道需要显式配置 *.blockStreaming: true 才能启用块回复。

打字指示器

打字指示器的默认行为：

直接聊天/提及：instant（即时）
未提及的群聊：message（消息级别）

可以按会话覆盖：

session.typingMode
session.typingIntervalSeconds

Memory（记忆）

OpenClaw 通过本地 Markdown 文件实现记忆持久化。模型只"记住"被保存到磁盘的内容——没有隐藏状态。

记忆文件

Agent 有两个地方存储记忆：

文件	说明
`MEMORY.md`	持久记忆，存储重要事实和偏好
`memory/YYYY-MM-DD.md`	按日期组织的日记式记忆

记忆工具

Agent 使用以下工具操作记忆：

memory_search - 搜索记忆内容
memory_get - 获取特定记忆

记忆搜索

当配置了嵌入向量提供商时，memory_search 使用混合搜索——结合向量相似度（语义含义）和关键词匹配（精确术语如 ID 和代码符号）。

OpenClaw 会自动检测嵌入向量提供商。如果你配置了 OpenAI、Gemini、Voyage 或 Mistral 的 API Key，记忆搜索会自动启用。

自动记忆刷新

在压缩对话之前，OpenClaw 会运行一个静默回合，提醒 Agent 将重要上下文保存到记忆文件。这是默认启用，无需配置。

详细的记忆系统配置请参阅 Memory 记忆系统。

Channels（渠道）

Channels 是 OpenClaw 与用户交互的通道。

支持的渠道

渠道	特点	配置方式
WhatsApp	使用 Baileys 库	`channels.whatsapp`
Telegram	使用 grammY 框架	`channels.telegram`
Slack	使用 Bolt 框架	`channels.slack`
Discord	使用 discord.js	`channels.discord`
飞书	企业级，中文友好	`channels.feishu`
微信	官方腾讯插件	插件安装
WebChat	内置 Web 界面	默认启用
Signal	通过 signal-cli	`channels.signal`
iMessage	macOS 专用	`channels.imessage`
Matrix	开源协议	`channels.matrix`

渠道配置

渠道配置位于 openclaw.json 中：

{
  "channels": {
    "telegram": {
      "enabled": true,
      "accounts": {
        "default": {
          "botToken": "YOUR_BOT_TOKEN"
        }
      }
    }
  }
}

DM 访问策略

所有渠道都支持私聊策略：

策略	行为
`pairing`（默认）	未知发送者获得一次性配对码，需要所有者批准
`allowlist`	只允许 `allowFrom` 列表中的发送者
`open`	允许所有入站私聊（需要 `allowFrom: ["*"]`）
`disabled`	忽略所有入站私聊

群聊提及门控

群聊消息默认需要提及才会触发 Agent 响应：

元数据提及：原生平台 @-提及
文本模式：agents.list[].groupChat.mentionPatterns 中的安全正则表达式

消息路由

Gateway 将入站消息路由到对应的 Agent。路由规则包括：

按 Agent ID 绑定
按 Peer（私聊/群聊）绑定
按 Guild/Team（Discord/Slack）绑定

Nodes（节点）

Nodes 是连接到 Gateway 的设备客户端，提供设备级能力。

节点类型

节点	能力
macOS 应用	Canvas、相机、屏幕录制、系统命令、通知
iOS 应用	Canvas、相机、屏幕录制、语音唤醒
Android 应用	Canvas、相机、屏幕录制、通知、位置、短信

节点命令

节点暴露的命令包括：

canvas.* - Canvas 画布操作
camera.* - 相机操作
screen.record - 屏幕录制
location.get - 获取位置
system.run - 执行本地命令（macOS）
system.notify - 发送通知（macOS）

设备配对

节点连接 Gateway 时需要进行设备配对：

节点发送 connect 消息，声明 role: node
Gateway 要求配对确认
用户通过 CLI 批准配对
Gateway 颁发设备 Token
后续连接使用 Token 认证

Skills（技能）

Skills 是 Agent 的能力扩展模块。

技能类型

类型	说明	位置
内置技能	OpenClaw 自带	核心代码
托管技能	从 ClawHub 安装	`~/.openclaw/skills/`
工作空间技能	项目专用	`workspace/skills/`

技能结构

一个技能包含：

SKILL.md - 技能说明（注入到 Agent 提示词）
技能逻辑代码（如果有）

技能加载顺序

OpenClaw 从三个位置加载技能（工作空间优先于名称冲突）：

内置（随安装附带）
托管/本地：~/.openclaw/skills
工作空间：<workspace>/skills

技能安全

技能安装可能需要审批：

{
  "skills": {
    "installPolicy": "approve"
  }
}

详细的技能系统请参阅 Skills 技能系统。

Cron（定时任务）

OpenClaw 支持 Cron 定时任务，可以定时触发 Agent 执行任务。

Cron 配置

{
  "cron": {
    "enabled": true,
    "tasks": [
      {
        "name": "daily-report",
        "schedule": "0 9 * * *",
        "prompt": "生成昨日工作总结"
      }
    ]
  }
}

详细的定时任务配置请参阅定时任务。

系统提示词（System Prompt）

每次 Agent 运行时，OpenClaw 会动态构建一个系统提示词。这个提示词不是静态的，而是根据当前会话、加载的技能、工具配置等动态生成。

提示词结构

系统提示词采用固定分节结构，紧凑且高效：

章节	说明	内容来源
Tooling	工具列表和简短描述	内置工具 + 插件工具
Safety	安全护栏提醒	防止越权行为的简短警告
Skills	技能加载指引	可用时注入技能列表
OpenClaw Self-Update	自更新指令	如何运行 `config.apply` 和 `update.run`
Workspace	工作目录	`agents.defaults.workspace` 配置
Documentation	文档路径	本地 OpenClaw 文档位置
Workspace Files	引导文件注入	表示下方包含引导文件内容
Sandbox	沙箱信息	沙箱模式、路径、权限等
Current Date & Time	当前时间	用户时区信息
Reply Tags	回复标签	支持的提供商回复标签语法
Heartbeats	心跳提示	心跳行为和确认
Runtime	运行时信息	主机、OS、Node、模型等
Reasoning	推理可见性	当前可见性级别和切换提示

提示词模式

OpenClaw 支持不同的提示词模式，用于不同场景：

模式	使用场景	包含内容
`full`（默认）	主 Agent 运行	所有章节
`minimal`	子 Agent 运行	精简内容，省略 Skills、Memory、User Identity 等
`none`	特殊场景	仅基础身份行

子 Agent 使用 minimal 模式可以显著减少 Token 消耗。

引导文件注入

工作空间中的引导文件会被自动注入到系统提示词的 Project Context 区域：

自动注入的文件：

文件	说明	注入条件
`AGENTS.md`	操作指令 + 记忆	始终注入
`SOUL.md`	人格定义	始终注入
`TOOLS.md`	工具使用约定	始终注入
`IDENTITY.md`	Agent 身份	始终注入
`USER.md`	用户档案	始终注入
`HEARTBEAT.md`	心跳上下文	始终注入
`BOOTSTRAP.md`	首次运行引导	仅新工作空间
`MEMORY.md`	记忆内容	存在时注入

重要说明：

这些文件每次 Agent 运行都会注入到上下文窗口
内容会消耗 Token，保持简洁很重要
memory/*.md 日期文件不会自动注入，通过 memory_search 按需访问
子 Agent 会话只注入 AGENTS.md 和 TOOLS.md

文件大小限制

为防止提示词过长，OpenClaw 会对引导文件进行截断：

单文件最大字符数：agents.defaults.bootstrapMaxChars（默认 20000）
所有文件总字符数：agents.defaults.bootstrapTotalMaxChars（默认 150000）

如果文件超过限制，内容会被截断并添加提示说明。

配置截断警告：

{
  "agents": {
    "defaults": {
      "bootstrapPromptTruncationWarning": "once"
    }
  }
}

可选值：off（关闭）、once（仅一次，默认）、always（始终显示）。

查看上下文使用

使用 /context 命令查看注入内容的详细信息：

# 列出上下文组成
openclaw agent -m "/context list"

# 详细信息
openclaw agent -m "/context detail"

这会显示每个注入文件的原始大小、注入后大小、截断情况以及工具 Schema 开销。

Token 影响优化

优化建议：

精简 MEMORY.md：只保留重要信息，将详细内容移到 memory/ 目录
定期清理：删除过时或重复的内容
使用记忆搜索：让 Agent 按需检索而不是全部注入
合理使用子 Agent：利用 minimal 模式减少 Token 消耗

时间处理

系统提示词包含时区信息（不包含动态时钟，以保持缓存稳定）：

配置：agents.defaults.userTimezone
时间格式：agents.defaults.timeFormat（auto|12|24）

当 Agent 需要当前时间时，会使用 session_status 工具获取。

技能注入

当存在符合条件的技能时，OpenClaw 注入一个紧凑的技能列表：

格式：XML 列表，包含名称、描述、文件路径
指令：告诉模型使用 read 工具按需加载 SKILL.md
无技能时：Skills 章节省略

Token 成本估算：

基础开销（至少一个技能时）：约 195 字符
每个技能：约 97 字符 + 名称、描述、路径长度
粗略估算：约 24 tokens/技能（不含字段内容）

文档引用

系统提示词包含 Documentation 章节，指向：

本地 OpenClaw 文档目录（仓库 docs/ 或 npm 包文档）
公共镜像、源码仓库、社区 Discord、ClawHub

Agent 会在需要时查阅本地文档，优先于询问用户。

工具策略（Tool Policy）

OpenClaw 提供细粒度的工具控制，可以限制 Agent 能使用哪些工具。

工具过滤层级

工具过滤按以下顺序应用（后层只能进一步限制，不能放宽）：

工具配置文件（tools.profile 或 agents.list[].tools.profile）
提供商工具配置文件（tools.byProvider[provider].profile）
全局工具策略（tools.allow / tools.deny）
提供商工具策略（tools.byProvider[provider].allow/deny）
Agent 特定工具策略（agents.list[].tools.allow/deny）
沙箱工具策略（tools.sandbox.tools）
子代理工具策略（tools.subagents.tools）

工具组简写

工具策略支持 group:* 简写，扩展为多个工具：

简写	包含的工具
`group:fs`	文件系统相关工具
`group:exec`	执行相关工具
`group:web`	网络相关工具

配置示例

只允许读取文件：

{
  "agents": {
    "list": [
      {
        "id": "readonly",
        "tools": {
          "allow": ["read", "glob", "grep"]
        }
      }
    ]
  }
}

禁止执行命令：

{
  "tools": {
    "deny": ["exec"]
  }
}

按提供商限制：

{
  "tools": {
    "byProvider": {
      "openai": {
        "profile": "coding"
      },
      "anthropic": {
        "profile": "full"
      }
    }
  }
}

配置热加载

Gateway 会监控 ~/.openclaw/openclaw.json 文件变化，自动应用配置更改，大多数情况下无需手动重启。

热加载模式

通过 gateway.reload 配置热加载行为：

模式	行为
`hybrid`（默认）	安全更改即时热加载，关键更改自动重启
`hot`	只热加载安全更改，需要重启时输出警告
`restart`	任何更改都重启 Gateway
`off`	禁用文件监控，更改需手动重启

热加载 vs 需要重启

类别	配置项	是否需要重启
渠道	`channels.*`	否
Agent 和模型	`agent`, `agents`, `models`, `routing`	否
自动化	`hooks`, `cron`, `agent.heartbeat`	否
会话和消息	`session`, `messages`	否
工具和媒体	`tools`, `browser`, `skills`, `audio`	否
Gateway 服务器	`gateway.*`（端口、绑定、认证等）	是
基础设施	`discovery`, `canvasHost`, `plugins`	是

心跳（Heartbeat）

心跳是周期性运行的 Agent 回合，用于保持 Agent 活跃和执行定期任务。

配置心跳

{
  "agents": {
    "defaults": {
      "heartbeat": {
        "every": "30m",
        "suppressToolErrorWarnings": true,
        "isolatedSession": true,
        "lightContext": true
      }
    }
  }
}

参数说明：

every：心跳间隔（API Key 认证默认 30 分钟，OAuth 认证默认 1 小时）
suppressToolErrorWarnings：抑制心跳运行期间的工具错误警告
isolatedSession：每次心跳在独立会话中运行，无历史记录
lightContext：使用轻量级引导上下文，只保留 HEARTBEAT.md

注意事项

心跳会运行完整的 Agent 回合，较短的间隔会消耗更多 Token
设置 every: "0m" 可禁用心跳
可以为每个 Agent 单独配置心跳

上下文压缩（Compaction）

当对话历史过长时，OpenClaw 会自动压缩上下文。

压缩模式

模式	说明
`default`	标准压缩
`safeguard`	分块摘要，适用于长历史

配置压缩

{
  "agents": {
    "defaults": {
      "compaction": {
        "mode": "default",
        "timeoutSeconds": 900,
        "memoryFlush": true,
        "notifyUser": false,
        "postCompactionSections": ["Session Startup", "Red Lines"]
      }
    }
  }
}

参数说明：

mode：压缩模式
timeoutSeconds：压缩操作最大时间（默认 900 秒）
memoryFlush：压缩前静默运行记忆保存
notifyUser：压缩开始时通知用户
postCompactionSections：压缩后重新注入的 AGENTS.md 章节名称

配置优先级

OpenClaw 的配置优先级从高到低：

命令行参数
环境变量
openclaw.json 配置文件
默认值

配置文件位置

文件	说明
`~/.openclaw/openclaw.json`	主配置文件
`OPENCLAW_CONFIG_PATH`	环境变量指定配置路径
`OPENCLAW_STATE_DIR`	环境变量指定状态目录

下一步

Skills 技能系统 - 安装和开发自定义技能
Memory 记忆系统 - 配置和管理记忆
多 Agent 协作 - 多 Agent 架构

架构概览​

核心设计原则​

Gateway（网关）​

Gateway 的职责​

启动 Gateway​

访问控制​

配置热加载​

Agent（智能体）​

Agent 的组成​

单 Agent 模式（默认）​

工作空间文件​

重要说明​

模型配置​

模型回退​

会话管理​

会话标识​

会话存储​

流式响应（Steering）​

块流式输出（Block Streaming）​

打字指示器​

Memory（记忆）​

记忆文件​

记忆工具​

记忆搜索​

自动记忆刷新​

Channels（渠道）​

支持的渠道​

渠道配置​

DM 访问策略​

群聊提及门控​

消息路由​

Nodes（节点）​

节点类型​

节点命令​

设备配对​

Skills（技能）​

技能类型​

技能结构​

技能加载顺序​

技能安全​

Cron（定时任务）​

Cron 配置​

系统提示词（System Prompt）​

提示词结构​

提示词模式​

引导文件注入​

文件大小限制​

查看上下文使用​

Token 影响优化​

时间处理​

技能注入​

文档引用​

工具策略（Tool Policy）​

工具过滤层级​

工具组简写​

配置示例​

配置热加载​

热加载模式​

热加载 vs 需要重启​

心跳（Heartbeat）​

配置心跳​

注意事项​

上下文压缩（Compaction）​

压缩模式​

配置压缩​

配置优先级​

配置文件位置​

下一步​

架构概览

核心设计原则

Gateway（网关）

Gateway 的职责

启动 Gateway

访问控制

配置热加载

Agent（智能体）

Agent 的组成

单 Agent 模式（默认）

工作空间文件

重要说明

模型配置

模型回退

会话管理

会话标识

会话存储

流式响应（Steering）

块流式输出（Block Streaming）

打字指示器

Memory（记忆）

记忆文件

记忆工具

记忆搜索

自动记忆刷新

Channels（渠道）

支持的渠道

渠道配置

DM 访问策略

群聊提及门控

消息路由

Nodes（节点）

节点类型

节点命令

设备配对

Skills（技能）

技能类型

技能结构

技能加载顺序

技能安全

Cron（定时任务）

Cron 配置

系统提示词（System Prompt）

提示词结构

提示词模式

引导文件注入

文件大小限制

查看上下文使用

Token 影响优化

时间处理

技能注入

文档引用

工具策略（Tool Policy）

工具过滤层级

工具组简写

配置示例

配置热加载

热加载模式

热加载 vs 需要重启

心跳（Heartbeat）

配置心跳

注意事项

上下文压缩（Compaction）

压缩模式

配置压缩

配置优先级

配置文件位置

下一步