OpenClaw 全局概览

> 你的第二个大脑——只不过这个真的记得东西放哪儿了。

OpenClaw 是一个本地优先的 AI Agent 运行时。它通过一个长期运行的 Gateway 进程，把大模型、消息渠道、工具执行、会话管理和自动化调度串在一起，让 Agent 能在你选择的任何平台上（Telegram、WhatsApp、Discord、Signal、WebChat……）持续工作。

一、架构总览

┌─────────────────────────────────────────────────┐
│                  Gateway (守护进程)                │
│                                                   │
│  ┌──────────┐  ┌──────────┐  ┌───────────────┐   │
│  │ 消息渠道  │  │ Agent 运行 │  │  工具执行层   │   │
│  │ 连接管理  │  │ 时 (会话)  │  │ exec/browser  │   │
│  │ WhatsApp  │  │           │  │ canvas/nodes  │   │
│  │ Telegram  │  │ 模型调用   │  │ cron/memory   │   │
│  │ Discord   │  │ 上下文管理  │  │ message/web   │   │
│  │ Signal    │  │ 压缩/截断  │  │               │   │
│  │ WebChat   │  │           │  │               │   │
│  └──────────┘  └──────────┘  └───────────────┘   │
│                                                   │
│  WebSocket API (ws://host:18789)                  │
└──────────┬──────────────────────┬─────────────────┘
           │                      │
    ┌──────▼──────┐       ┌──────▼──────┐
    │  客户端      │       │  节点设备    │
    │ macOS App   │       │ iOS/Android │
    │ CLI         │       │ headless    │
    │ Web UI      │       │ (配对后连接) │
    └─────────────┘       └─────────────┘

核心原则：Gateway 是唯一的真相来源。 所有会话状态、token 计数、消息路由都由 Gateway 掌控。客户端只做展示。

二、核心概念

Agent（智能体）

一个 Agent 拥有独立的：

• 工作区（~/.openclaw/workspace）— 文件、AGENTS.md、SOUL.md、USER.md
• 状态目录（~/.openclaw/agents//agent）— 认证、模型注册
• 会话存储（~/.openclaw/agents//sessions/）— 聊天历史

默认是单 Agent 模式（agentId = main）。支持多 Agent 隔离路由。

Session（会话）

• 私聊合并到主会话 agent:main:main
• 群聊/频道独立隔离
• 存储为 JSONL 文件：~/.openclaw/agents//sessions/.jsonl
• session.dmScope 控制私聊隔离策略：main / per-peer / per-channel-peer

Model（模型）

选择优先级：

1. agents.defaults.model.primary — 主模型
2. agents.defaults.model.fallbacks — 降级链
3. Provider 内认证故障转移

支持多 Provider 配置：OpenAI、Anthropic、小米 MiMo、Ollama、OpenRouter 等。

Compaction（上下文压缩）

当会话接近模型 context window 上限时，自动触发压缩：

• 模式：safeguard（默认，保守压缩）/ auto / off
• 原理：摘要旧消息，保留近期消息
• 可配置专用压缩模型：agents.defaults.compaction.model

Skills（技能）

Agent 的能力扩展机制。三个加载位置（优先级从高到低）：

1. /skills/ — 工作区专属
2. ~/.openclaw/skills/ — 全局共享
3. 内置技能（随安装包分发）

每个 Skill 是一个包含 SKILL.md 的目录。通过 YAML frontmatter 声明元数据。

Nodes（节点设备）

iOS/Android/树莓派等设备配对后连接到 Gateway，提供：

• 相机拍照/录像
• 屏幕录制
• 位置获取
• 语音唤醒
• 通知读取

三、工具体系

OpenClaw 为 Agent 提供一等公民工具（非 shell 调用）：

工具策略：通过 tools.profile（minimal / coding / messaging / full）和 tools.allow / tools.deny 控制可用范围。

四、目录布局

~/.openclaw/
├── openclaw.json              # 主配置文件
├── agents/
│   └── main/
│       ├── agent/
│       │   └── auth-profiles.json   # 认证配置
│       └── sessions/
│           ├── sessions.json        # 会话索引
│           └── *.jsonl              # 会话记录
├── skills/                    # 全局 Skill
├── cron/
│   └── jobs.json              # 定时任务
├── memory/                    # 记忆存储
├── workspace/                 # Agent 工作区
│   ├── AGENTS.md              # 操作指令
│   ├── SOUL.md                # 人格与边界
│   ├── USER.md                # 用户档案
│   ├── TOOLS.md               # 工具备注
│   ├── IDENTITY.md            # Agent 身份
│   ├── HEARTBEAT.md           # 心跳任务
│   └── BOOTSTRAP.md           # 首次引导（用完删除）
├── logs/                      # 日志
├── browser/                   # 浏览器数据
└── extensions/                # 扩展插件

五、消息渠道

支持的渠道（每个 Gateway 可同时连接多个）：

路由规则：

• 私聊 → 按 dmScope 策略路由到对应会话
• 群聊 → 需 @mention 或关键词触发（可配置）
• channel-routing.md 控制细粒度路由

六、自动化

Heartbeat（心跳）

Gateway 定期唤醒 Agent 执行 HEARTBEAT.md 中的任务。适合批量检查（邮件、日历、天气等）。

• 默认间隔：30 分钟
• 配置：gateway.heartbeat

Cron Jobs（定时任务）

精确时间调度，支持两种负载：

• systemEvent — 注入到主会话
• agentTurn — 创建隔离会话执行
• 管理命令：openclaw cron list/add/remove/run

Hooks（钩子）

事件驱动执行：消息到达、会话创建、Agent 完成回复等时机触发自定义脚本。

七、CLI 命令速查

# 状态与诊断
openclaw status              # 系统状态概览
openclaw doctor              # 健康检查
openclaw logs                # 查看日志

# 配置
openclaw configure           # 交互式配置向导
openclaw config get/set      # 读写配置

# Agent 管理
openclaw agents list         # 列出 Agent
openclaw agents add <id>     # 添加新 Agent

# 会话
openclaw sessions list       # 列出会话

# 模型
openclaw models list         # 可用模型
openclaw models set          # 设置主模型

# 渠道
openclaw channels list       # 已连接渠道
openclaw channels add        # 添加渠道

# Cron
openclaw cron list           # 定时任务列表
openclaw cron add            # 添加任务
openclaw cron run <id>       # 立即执行

# Skills
openclaw skills list         # 已加载技能

# Gateway 服务
openclaw gateway start/stop/restart
openclaw gateway status

# 更新
openclaw update              # 检查并更新

# 备份
openclaw backup create       # 创建备份

八、配置速查

主配置文件：~/.openclaw/openclaw.json（JSON5 格式）

{
  // 模型
  models: {
    providers: {
      xiaomi: { baseUrl: "...", apiKey: "...", models: [...] },
      openai: { apiKey: "...", models: [...] },
    }
  },
  // Agent 默认值
  agents: {
    defaults: {
      model: { primary: "xiaomi/mimo-v2-pro", fallbacks: [...] },
      workspace: "~/.openclaw/workspace",
      compaction: { mode: "safeguard" },
    }
  },
  // Gateway
  gateway: {
    port: 18789,
    mode: "local",        // local | remote
    bind: "lan",          // lan | tailscale
    heartbeat: { enabled: true, intervalMs: 1800000 },
  },
  // 会话
  session: {
    dmScope: "per-channel-peer",  // main | per-peer | per-channel-peer
  },
  // 工具策略
  tools: {
    profile: "full",              // minimal | coding | messaging | full
    deny: ["tts"],
    exec: { security: "allowlist" },
  },
}

九、安全模型

• Exec 安全：tools.exec.security 控制命令执行策略（allowlist / full）
• 沙箱：agents.defaults.sandbox 隔离非主会话的工作区
• 设备配对：所有节点设备需人工审批配对
• Token 认证：Gateway 默认要求 WS 连接携带 auth token
• Skill 隔离：第三方 Skill 视为不受信任代码，读取前审阅

十、文档位置

本地文档根目录：/usr/lib/node_modules/openclaw/docs/

在线文档：https://docs.openclaw.ai