从零开始，深入解析 OpenClaw 架构设计与实现细节

ToTensor2026-03-30 18:07

文章目录

    • [概述：什么是 OpenClaw？](#概述：什么是 OpenClaw？)
    • [第一部分：Gateway 架构与协议](#第一部分：Gateway 架构与协议)
      • [1.1 Gateway 核心概念](#1.1 Gateway 核心概念)
      • [1.2 WebSocket 协议详解](#1.2 WebSocket 协议详解)
        • [1.2.1 连接握手](#1.2.1 连接握手)
        • [1.2.2 角色与权限](#1.2.2 角色与权限)
        • [1.2.3 消息帧格式](#1.2.3 消息帧格式)
        • [1.2.4 设备身份与配对](#1.2.4 设备身份与配对)
      • [1.3 Gateway 的核心功能](#1.3 Gateway 的核心功能)
        • [1.3.1 消息处理管道](#1.3.1 消息处理管道)
        • [1.3.2 心跳系统](#1.3.2 心跳系统)
        • [1.3.3 定时任务（Cron）](#1.3.3 定时任务（Cron）)
    • 第二部分：消息通道系统
      • [2.1 通道架构概述](#2.1 通道架构概述)
      • [2.2 WhatsApp 通道深度解析](#2.2 WhatsApp 通道深度解析)
        • [2.2.1 连接机制](#2.2.1 连接机制)
        • [2.2.2 消息处理](#2.2.2 消息处理)
        • [2.2.3 安全策略](#2.2.3 安全策略)
      • [2.3 Telegram 通道](#2.3 Telegram 通道)
      • [2.4 Discord 通道](#2.4 Discord 通道)
    • [第三部分：Agent 运行时](#第三部分：Agent 运行时)
      • [3.1 Agent 核心概念](#3.1 Agent 核心概念)
      • [3.2 工作空间（Workspace）](#3.2 工作空间（Workspace）)
      • [3.3 会话管理](#3.3 会话管理)
        • [3.3.1 会话键（Session Key）](#3.3.1 会话键（Session Key）)
        • [3.3.2 会话存储](#3.3.2 会话存储)
        • [3.3.3 会话重置](#3.3.3 会话重置)
      • [3.4 上下文管理](#3.4 上下文管理)
        • [3.4.1 上下文构建](#3.4.1 上下文构建)
        • [3.4.2 上下文修剪](#3.4.2 上下文修剪)
    • 第四部分：工具系统
      • [4.1 工具架构](#4.1 工具架构)
      • [4.2 核心工具详解](#4.2 核心工具详解)
        • [4.2.1 exec / process（命令执行）](#4.2.1 exec / process（命令执行）)
        • [4.2.2 browser（浏览器控制）](#4.2.2 browser（浏览器控制）)
        • [4.2.3 web_search / web_fetch（网页搜索）](#4.2.3 web_search / web_fetch（网页搜索）)
        • [4.2.4 read / write / edit（文件操作）](#4.2.4 read / write / edit（文件操作）)
        • [4.2.5 message（消息发送）](#4.2.5 message（消息发送）)
        • [4.2.6 canvas（Canvas 控制）](#4.2.6 canvas（Canvas 控制）)
        • [4.2.7 nodes（节点控制）](#4.2.7 nodes（节点控制）)
      • [4.3 工具策略](#4.3 工具策略)
    • 第五部分：技能与插件系统
      • [5.1 技能（Skills）](#5.1 技能（Skills）)
        • [5.1.1 技能位置](#5.1.1 技能位置)
        • [5.1.2 技能格式](#5.1.2 技能格式)
        • [5.1.3 技能门控](#5.1.3 技能门控)
      • [5.2 插件（Plugins）](#5.2 插件（Plugins）)
        • [5.2.1 插件类型](#5.2.1 插件类型)
        • [5.2.2 插件能力](#5.2.2 插件能力)
        • [5.2.3 插件配置](#5.2.3 插件配置)
      • [5.3 ClawHub](#5.3 ClawHub)
    • 第六部分：沙箱与安全
      • [6.1 沙箱模式](#6.1 沙箱模式)
        • [6.1.1 模式](#6.1.1 模式)
        • [6.1.2 后端](#6.1.2 后端)
        • [6.1.3 工作空间访问](#6.1.3 工作空间访问)
      • [6.2 安全机制](#6.2 安全机制)
        • [6.2.1 DM 配对](#6.2.1 DM 配对)
        • [6.2.2 工具策略](#6.2.2 工具策略)
        • [6.2.3 执行审批](#6.2.3 执行审批)
    • 第七部分：节点系统
      • [7.1 节点概念](#7.1 节点概念)
      • [7.2 节点类型](#7.2 节点类型)
        • [7.2.1 macOS 节点](#7.2.1 macOS 节点)
        • [7.2.2 iOS 节点](#7.2.2 iOS 节点)
        • [7.2.3 Android 节点](#7.2.3 Android 节点)
      • [7.3 节点配对](#7.3 节点配对)
      • [7.4 远程节点主机](#7.4 远程节点主机)
    • 第八部分：媒体处理
      • [8.1 图片处理](#8.1 图片处理)
        • [8.1.1 图片分析](#8.1.1 图片分析)
        • [8.1.2 图片生成](#8.1.2 图片生成)
      • [8.2 音频处理](#8.2 音频处理)
        • [8.2.1 语音转文字](#8.2.1 语音转文字)
        • [8.2.2 文字转语音](#8.2.2 文字转语音)
      • [8.3 视频处理](#8.3 视频处理)
    • 第九部分：自动化
      • [9.1 Cron 任务](#9.1 Cron 任务)
        • [9.1.1 任务类型](#9.1.1 任务类型)
        • [9.1.2 执行模式](#9.1.2 执行模式)
        • [9.1.3 传递机制](#9.1.3 传递机制)
      • [9.2 Webhook](#9.2 Webhook)
      • [9.3 Gmail Pub/Sub](#9.3 Gmail Pub/Sub)
    • 第十部分：配置系统
      • [10.1 配置文件](#10.1 配置文件)
      • [10.2 配置结构](#10.2 配置结构)
      • [10.3 配置方式](#10.3 配置方式)
      • [10.4 热重载](#10.4 热重载)
    • [第十一部分：CLI 与客户端](#第十一部分：CLI 与客户端)
      • [11.1 CLI 命令](#11.1 CLI 命令)
      • [11.2 Control UI](#11.2 Control UI)
      • [11.3 macOS 应用](#11.3 macOS 应用)
    • 第十二部分：部署与运维
      • [12.1 安装方式](#12.1 安装方式)
      • [12.2 系统服务](#12.2 系统服务)
      • [12.3 远程访问](#12.3 远程访问)
      • [12.4 日志](#12.4 日志)
      • [12.5 诊断](#12.5 诊断)
    • 第十三部分：认证与授权系统
      • [13.1 认证架构概述](#13.1 认证架构概述)
      • [13.2 Gateway 访问认证](#13.2 Gateway 访问认证)
        • [13.2.1 令牌认证](#13.2.1 令牌认证)
        • [13.2.2 设备配对](#13.2.2 设备配对)
        • [13.2.3 设备身份验证迁移](#13.2.3 设备身份验证迁移)
      • [13.3 模型提供商认证](#13.3 模型提供商认证)
        • [13.3.1 认证方式](#13.3.1 认证方式)
        • [13.3.2 认证存储](#13.3.2 认证存储)
        • [13.3.3 多账户支持](#13.3.3 多账户支持)
        • [13.3.4 API Key 轮换](#13.3.4 API Key 轮换)
      • [13.4 OAuth 流程详解](#13.4 OAuth 流程详解)
        • [13.4.1 OpenAI Codex OAuth（PKCE）](#13.4.1 OpenAI Codex OAuth（PKCE）)
        • [13.4.2 令牌刷新](#13.4.2 令牌刷新)
    • 第十四部分：秘密管理系统
      • [14.1 SecretRef 机制](#14.1 SecretRef 机制)
        • [14.1.1 SecretRef 格式](#14.1.1 SecretRef 格式)
        • [14.1.2 Source 类型](#14.1.2 Source 类型)
      • [14.2 Provider 配置](#14.2 Provider 配置)
      • [14.3 集成示例](#14.3 集成示例)
        • [14.3.1 1Password CLI](#14.3.1 1Password CLI)
        • [14.3.2 HashiCorp Vault](#14.3.2 HashiCorp Vault)
        • [14.3.3 SOPS](#14.3.3 SOPS)
      • [14.4 运行时行为](#14.4 运行时行为)
      • [14.5 审计与配置](#14.5 审计与配置)
    • 第十五部分：模型提供商深度解析
      • [15.1 提供商架构](#15.1 提供商架构)
      • [15.2 提供商能力接口](#15.2 提供商能力接口)
      • [15.3 主要提供商详情](#15.3 主要提供商详情)
        • [15.3.1 OpenAI](#15.3.1 OpenAI)
        • [15.3.2 Anthropic](#15.3.2 Anthropic)
        • [15.3.3 OpenAI Codex](#15.3.3 OpenAI Codex)
        • [15.3.4 OpenCode](#15.3.4 OpenCode)
        • [15.3.5 其他内置提供商](#15.3.5 其他内置提供商)
      • [15.4 模型选择规则](#15.4 模型选择规则)
    • 第十六部分：协议版本与兼容性
      • [16.1 协议版本管理](#16.1 协议版本管理)
      • [16.2 版本历史](#16.2 版本历史)
      • [16.3 兼容性策略](#16.3 兼容性策略)
    • 第十七部分：故障排查与诊断
      • [17.1 常用诊断命令](#17.1 常用诊断命令)
      • [17.2 常见问题](#17.2 常见问题)
        • [17.2.1 连接问题](#17.2.1 连接问题)
        • [17.2.2 认证问题](#17.2.2 认证问题)
        • [17.2.3 通道问题](#17.2.3 通道问题)
      • [17.3 日志级别](#17.3 日志级别)
    • 第十八部分：性能与优化
      • [18.1 上下文管理](#18.1 上下文管理)
        • [18.1.1 上下文修剪](#18.1.1 上下文修剪)
        • [18.1.2 会话维护](#18.1.2 会话维护)
      • [18.2 Cron 性能](#18.2 Cron 性能)
        • [18.2.1 运行日志管理](#18.2.1 运行日志管理)
        • [18.2.2 避免高峰](#18.2.2 避免高峰)
      • [18.3 浏览器资源](#18.3 浏览器资源)
    • 第十九部分：安全最佳实践
      • [19.1 网络安全](#19.1 网络安全)
      • [19.2 认证安全](#19.2 认证安全)
      • [19.3 执行安全](#19.3 执行安全)
      • [19.4 通道安全](#19.4 通道安全)
    • 第二十部分：多Agent架构深度解析
      • [20.1 多Agent核心概念](#20.1 多Agent核心概念)
        • [20.1.1 单Agent vs 多Agent](#20.1.1 单Agent vs 多Agent)
        • [20.1.2 多Agent的设计目标](#20.1.2 多Agent的设计目标)
      • [20.2 Agent隔离机制](#20.2 Agent隔离机制)
        • [20.2.1 认证隔离](#20.2.1 认证隔离)
        • [20.2.2 技能隔离](#20.2.2 技能隔离)
        • [20.2.3 会话隔离](#20.2.3 会话隔离)
      • [20.3 消息路由与绑定](#20.3 消息路由与绑定)
        • [20.3.1 绑定机制（Bindings）](#20.3.1 绑定机制（Bindings）)
        • [20.3.2 账户路由](#20.3.2 账户路由)
      • [20.4 多Agent配置示例](#20.4 多Agent配置示例)
        • [20.4.1 Discord 多Bot配置](#20.4.1 Discord 多Bot配置)
        • [20.4.2 WhatsApp 多号码配置](#20.4.2 WhatsApp 多号码配置)
        • [20.4.3 通道分离配置](#20.4.3 通道分离配置)
      • [20.5 子Agent（Sub-Agents）](#20.5 子Agent（Sub-Agents）)
        • [20.5.1 子Agent核心概念](#20.5.1 子Agent核心概念)
        • [20.5.2 使用方式](#20.5.2 使用方式)
        • [20.5.3 会话键结构](#20.5.3 会话键结构)
        • [20.5.4 嵌套子Agent](#20.5.4 嵌套子Agent)
        • [20.5.5 线程绑定](#20.5.5 线程绑定)
        • [20.5.6 工具策略](#20.5.6 工具策略)
        • [20.5.7 认证](#20.5.7 认证)
      • [20.6 Agent间通信](#20.6 Agent间通信)
        • [20.6.1 Agent-to-Agent 工具](#20.6.1 Agent-to-Agent 工具)
        • [20.6.2 消息发送](#20.6.2 消息发送)
      • [20.7 Per-Agent 沙箱与工具配置](#20.7 Per-Agent 沙箱与工具配置)
      • [20.8 委托架构（Delegate Architecture）](#20.8 委托架构（Delegate Architecture）)
        • [20.8.1 能力层级](#20.8.1 能力层级)
        • [20.8.2 安全配置](#20.8.2 安全配置)
    • [第二十一部分：ACP 代理与外部运行时](#第二十一部分：ACP 代理与外部运行时)
      • [21.1 ACP 核心概念](#21.1 ACP 核心概念)
        • [21.1.1 ACP vs 子Agent](#21.1.1 ACP vs 子Agent)
        • [21.1.2 快速操作流程](#21.1.2 快速操作流程)
      • [21.2 线程绑定](#21.2 线程绑定)
      • [21.3 持久绑定](#21.3 持久绑定)
    • [第二十二部分：Webhook 与外部触发](#第二十二部分：Webhook 与外部触发)
      • [22.1 Webhook 端点](#22.1 Webhook 端点)
        • [22.1.1 启用配置](#22.1.1 启用配置)
        • [22.1.2 认证](#22.1.2 认证)
      • [22.2 端点详解](#22.2 端点详解)
        • [22.2.1 POST /hooks/wake](#22.2.1 POST /hooks/wake)
        • [22.2.2 POST /hooks/agent](#22.2.2 POST /hooks/agent)
    • 第二十三部分：心跳系统
      • [23.1 心跳核心概念](#23.1 心跳核心概念)
        • [23.1.1 配置](#23.1.1 配置)
        • [23.1.2 默认提示词](#23.1.2 默认提示词)
        • [23.1.3 响应约定](#23.1.3 响应约定)
      • [23.2 心跳 vs Cron](#23.2 心跳 vs Cron)
    • 第二十四部分：广播组
      • [24.1 广播组概念](#24.1 广播组概念)
      • [24.2 使用场景](#24.2 使用场景)
        • [24.2.1 专门 Agent 团队](#24.2.1 专门 Agent 团队)
        • [24.2.2 多语言支持](#24.2.2 多语言支持)
        • [24.2.3 质量保证工作流](#24.2.3 质量保证工作流)
      • [24.3 配置](#24.3 配置)
    • 第二十五部分：常设命令
      • [25.1 常设命令概念](#25.1 常设命令概念)
      • [25.2 配置](#25.2 配置)
      • [25.3 与 Cron 结合](#25.3 与 Cron 结合)
    • 第二十六部分：思考级别与推理控制
      • [26.1 思考级别（/think）](#26.1 思考级别（/think）)
        • [26.1.1 级别定义](#26.1.1 级别定义)
        • [26.1.2 解析顺序](#26.1.2 解析顺序)
        • [26.1.3 设置会话默认](#26.1.3 设置会话默认)
      • [26.2 快速模式（/fast）](#26.2 快速模式（/fast）)
        • [26.2.1 级别](#26.2.1 级别)
        • [26.2.2 解析顺序](#26.2.2 解析顺序)
        • [26.2.3 提供商行为](#26.2.3 提供商行为)
      • [26.3 详细日志（/verbose）](#26.3 详细日志（/verbose）)
        • [26.3.1 级别](#26.3.1 级别)
        • [26.3.2 行为](#26.3.2 行为)
      • [26.4 推理可见性（/reasoning）](#26.4 推理可见性（/reasoning）)
        • [26.4.1 级别](#26.4.1 级别)
        • [26.4.2 使用](#26.4.2 使用)
    • 第二十七部分：会话管理深度解析
      • [27.1 会话存储架构](#27.1 会话存储架构)
        • [27.1.1 会话存储（sessions.json）](#27.1.1 会话存储（sessions.json）)
        • [27.1.2 转录本（*.jsonl）](#27.1.2 转录本（*.jsonl）)
      • [27.2 磁盘位置](#27.2 磁盘位置)
      • [27.3 转录本清理（Transcript Hygiene）](#27.3 转录本清理（Transcript Hygiene）)
        • [27.3.1 清理范围](#27.3.1 清理范围)
        • [27.3.2 全局规则：图片清理](#27.3.2 全局规则：图片清理)
        • [27.3.3 实现位置](#27.3.3 实现位置)
      • [27.4 会话压缩](#27.4 会话压缩)
        • [27.4.1 手动压缩](#27.4.1 手动压缩)
        • [27.4.2 自动压缩](#27.4.2 自动压缩)
      • [27.5 会话修剪](#27.5 会话修剪)
        • [27.5.1 修剪策略](#27.5.1 修剪策略)
        • [27.5.2 修剪内容](#27.5.2 修剪内容)
    • 第二十八部分：斜杠命令系统
      • [28.1 命令类型](#28.1 命令类型)
        • [28.1.1 命令（Commands）](#28.1.1 命令（Commands）)
        • [28.1.2 指令（Directives）](#28.1.2 指令（Directives）)
        • [28.1.3 内联快捷方式](#28.1.3 内联快捷方式)
      • [28.2 配置](#28.2 配置)
      • [28.3 原生命令支持](#28.3 原生命令支持)
      • [28.4 授权规则](#28.4 授权规则)
    • [第二十九部分：提权模式（Elevated Mode）](#第二十九部分：提权模式（Elevated Mode）)
      • [29.1 概念](#29.1 概念)
      • [29.2 指令](#29.2 指令)
      • [29.3 配置](#29.3 配置)
      • [29.4 工作原理](#29.4 工作原理)
      • [29.5 重要说明](#29.5 重要说明)
    • 第三十部分：时区处理
      • [30.1 时区概念](#30.1 时区概念)
      • [30.2 消息信封（Envelope）](#30.2 消息信封（Envelope）)
      • [30.3 配置](#30.3 配置)
      • [30.4 选项说明](#30.4 选项说明)
      • [30.5 示例](#30.5 示例)
    • 第三十一部分：记忆系统（Memory）
      • [31.1 记忆搜索概述](#31.1 记忆搜索概述)
      • [31.2 Embedding 提供商](#31.2 Embedding 提供商)
      • [31.3 本地模式](#31.3 本地模式)
      • [31.4 QMD 后端（实验性）](#31.4 QMD 后端（实验性）)
      • [31.5 配置示例](#31.5 配置示例)
    • [第三十二部分：打字指示器（Typing Indicators）](#第三十二部分：打字指示器（Typing Indicators）)
      • [32.1 概念](#32.1 概念)
      • [32.2 默认行为](#32.2 默认行为)
      • [32.3 模式](#32.3 模式)
      • [32.4 配置](#32.4 配置)
    • [第三十三部分：命令队列（Command Queue）](#第三十三部分：命令队列（Command Queue）)
      • [33.1 概念](#33.1 概念)
      • [33.2 为什么需要队列](#33.2 为什么需要队列)
      • [33.3 工作原理](#33.3 工作原理)
      • [33.4 队列模式](#33.4 队列模式)
      • [33.5 配置](#33.5 配置)
    • [第三十四部分：威胁模型（Threat Model）](#第三十四部分：威胁模型（Threat Model）)
      • [34.1 概述](#34.1 概述)
      • [34.2 范围](#34.2 范围)
      • [34.3 威胁类别](#34.3 威胁类别)
      • [34.4 缓解措施](#34.4 缓解措施)
    • [第三十五部分：Web 控制界面](#第三十五部分：Web 控制界面)
      • [35.1 Control UI](#35.1 Control UI)
      • [35.2 快速访问](#35.2 快速访问)
      • [35.3 设备配对](#35.3 设备配对)
      • [35.4 WebChat](#35.4 WebChat)
    • 第三十六部分：备份与恢复
      • [36.1 备份命令](#36.1 备份命令)
      • [36.2 备份内容](#36.2 备份内容)
      • [36.3 备份文件](#36.3 备份文件)
      • [36.4 验证](#36.4 验证)
    • 第三十七部分：日志系统
      • [37.1 日志表面](#37.1 日志表面)
      • [37.2 文件日志](#37.2 文件日志)
      • [37.3 日志级别](#37.3 日志级别)
      • [37.4 控制台捕获](#37.4 控制台捕获)
      • [37.5 查看日志](#37.5 查看日志)
    • 第三十八部分：远程访问
      • [38.1 核心概念](#38.1 核心概念)
      • [38.2 常见 VPN/Tailnet 设置](#38.2 常见 VPN/Tailnet 设置)
        • [38.2.1 始终在线 Gateway（VPS 或家庭服务器）](#38.2.1 始终在线 Gateway（VPS 或家庭服务器）)
        • [38.2.2 家庭桌面运行 Gateway，笔记本电脑远程控制](#38.2.2 家庭桌面运行 Gateway，笔记本电脑远程控制)
      • [38.3 访问方式](#38.3 访问方式)
      • [38.4 配置](#38.4 配置)
    • 第三十九部分：诊断工具（Doctor）
      • [39.1 Doctor 命令](#39.1 Doctor 命令)
      • [39.2 检查项目](#39.2 检查项目)
      • [39.3 输出格式](#39.3 输出格式)
    • 第四十部分：更新与升级
      • [40.1 更新命令](#40.1 更新命令)
      • [40.2 更新频道](#40.2 更新频道)
      • [40.3 更新方式](#40.3 更新方式)
    • 第四十一部分：设备管理
      • [41.1 设备命令](#41.1 设备命令)
      • [41.2 设备类型](#41.2 设备类型)
      • [41.3 设备令牌](#41.3 设备令牌)
    • 第四十二部分：通道管理
      • [42.1 通道命令](#42.1 通道命令)
      • [42.2 添加/移除账户](#42.2 添加/移除账户)
      • [42.3 支持的通道](#42.3 支持的通道)
      • [42.4 登录流程](#42.4 登录流程)
    • 第四十三部分：插件管理
      • [43.1 插件命令](#43.1 插件命令)
      • [43.2 插件类型](#43.2 插件类型)
      • [43.3 插件市场](#43.3 插件市场)
      • [43.4 插件配置](#43.4 插件配置)
    • 第四十四部分：沙箱后端
      • [44.1 沙箱模式](#44.1 沙箱模式)
      • [44.2 后端类型](#44.2 后端类型)
        • [44.2.1 Docker](#44.2.1 Docker)
        • [44.2.2 SSH](#44.2.2 SSH)
        • [44.2.3 OpenShell](#44.2.3 OpenShell)
      • [44.3 工作空间访问](#44.3 工作空间访问)
    • 第四十五部分：消息格式与结构
      • [45.1 消息信封（Envelope）](#45.1 消息信封（Envelope）)
      • [45.2 信封组件](#45.2 信封组件)
      • [45.3 配置选项](#45.3 配置选项)
      • [45.4 消息类型](#45.4 消息类型)
    • 第四十六部分：会话键与会话路由
      • [46.1 会话键结构](#46.1 会话键结构)
      • [46.2 会话类型](#46.2 会话类型)
      • [46.3 DM 范围（dmScope）](#46.3 DM 范围（dmScope）)
      • [46.4 路由决策](#46.4 路由决策)
    • 第四十七部分：运维参考
      • [47.1 文件位置](#47.1 文件位置)
      • [47.2 配置格式](#47.2 配置格式)
      • [47.3 环境变量](#47.3 环境变量)
      • [47.4 端口配置](#47.4 端口配置)
      • [47.5 依赖要求](#47.5 依赖要求)
      • [47.6 常用命令速查](#47.6 常用命令速查)

概述：什么是 OpenClaw？

为什么需要 OpenClaw？

想象一下这样的场景：你有一个 AI 助手，它可以在你常用的所有通讯工具上与你对话------WhatsApp、Telegram、Discord、Slack、iMessage......它不仅能聊天，还能帮你执行命令、操作浏览器、读写文件、管理日程，甚至控制你的电脑。这一切都发生在你自己的设备上，而不是某个远程服务器。这，就是 OpenClaw。

OpenClaw 是一个开源的个人 AI 助手项目，它的核心理念是：让 AI 在你已有的通讯渠道上为你工作，同时保持数据本地化、隐私可控。

核心概念：Gateway 是整个系统的心脏

OpenClaw 采用了一种「一个 Gateway，多个客户端」的架构模式。Gateway 是一个长期运行的后台服务（daemon），它负责：

  • 管理所有消息通道的连接（WhatsApp、Telegram、Discord 等）
  • 处理与 AI 模型的交互（调用大语言模型、传递上下文、执行工具）
  • 维护会话状态（记住对话历史、管理不同的聊天场景）
  • 提供 WebSocket API（让各种客户端可以连接到它）

你可以把 Gateway 想象成一个「通讯枢纽」：所有的消息都先汇聚到这里，然后根据配置决定如何处理------是转发给 AI、还是执行某个工具、还是做其他事情。

Gateway 默认监听在本地的 18789 端口（可以通过配置修改），使用 WebSocket 协议与客户端通信。这意味着：

  • macOS 菜单栏应用通过 WebSocket 连接 Gateway
  • CLI 工具通过 WebSocket 连接 Gateway
  • Web UI（Control UI）通过 WebSocket 连接 Gateway
  • iOS/Android 设备作为「节点」也通过 WebSocket 连接 Gateway

这种设计的最大好处是：所有客户端共享同一个 AI 上下文。你在手机上开始的对话，可以在电脑上继续；你在 Web UI 发送的文件，会话历史里也能看到。

架构全景图

复制代码 
┌─────────────────────────────────────────────────────────────────┐
│                        消息来源                                  │
│  WhatsApp / Telegram / Slack / Discord / iMessage / Signal /   │
│  Microsoft Teams / Matrix / IRC / WebChat / ...                 │
└───────────────────────────────┬─────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                         Gateway                                 │
│                   (控制平面 + 消息路由)                          │
│                                                                  │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐          │
│  │  通道连接器   │  │   Agent 运行时 │  │   工具执行   │          │
│  │ (WhatsApp等) │  │  (Pi agent)   │  │ (exec/browser)│          │
│  └──────────────┘  └──────────────┘  └──────────────┘          │
│                                                                  │
│  WebSocket: ws://127.0.0.1:18789                               │
└───────────────────────────────┬─────────────────────────────────┘
                                │
        ┌───────────────────────┼───────────────────────┐
        │                       │                       │
        ▼                       ▼                       ▼
┌───────────────┐      ┌───────────────┐      ┌───────────────┐
│  macOS 应用   │      │   CLI 工具    │      │   Web UI     │
│ (菜单栏+节点) │      │ (openclaw ...)│      │ (Control UI) │
└───────────────┘      └───────────────┘      └───────────────┘
        │                       │                       │
        └───────────────────────┼───────────────────────┘
                                │
                                ▼
                    ┌───────────────────────┐
                    │   iOS / Android 节点   │
                    │ (相机/屏幕/语音/位置)   │
                    └───────────────────────┘

为什么这样设计？

第一，状态共享。 如果每个通道各自为政，你在 WhatsApp 上的对话历史就无法被 Telegram 上的会话看到。Gateway 作为中央节点，所有通道的消息都会汇聚到这里，AI 可以获得完整的上下文。

第二，资源复用。 只需要维护一个 AI 模型连接，而不是每个通道都去调用 API。这不仅节省资源，还能实现跨通道的对话连续性。

第三，安全可控。 所有消息都经过 Gateway，这意味着可以统一实施安全策略------比如 DM 配对机制、工具权限控制、沙箱隔离等。

第四，扩展性。 添加新通道只需要实现一个连接到 Gateway 的客户端，不需要修改其他组件。

消息通道系统入门

在 OpenClaw 中，「通道」指的是消息的输入输出渠道。当你配置 WhatsApp 通道后，Gateway 会保持一个 WhatsApp 连接（通过 Baileys 库），接收和发送消息。配置 Telegram 通道后同理。

OpenClaw 支持的通道非常广泛：

主流即时通讯：

  • WhatsApp（通过 Baileys，QR 码配对）
  • Telegram（通过 Bot API，配置令牌即可）
  • Discord（通过 Bot API）
  • Slack（通过 Bolt SDK）
  • Signal（通过 signal-cli）
  • iMessage（推荐通过 BlueBubbles，macOS 服务）

企业/协作平台：

  • Microsoft Teams
  • Google Chat
  • Mattermost
  • Nextcloud Talk

去中心化/其他：

  • Matrix
  • IRC
  • Nostr
  • Feishu（飞书）
  • LINE
  • Zalo
  • WebChat（直接通过 Gateway 的 Web UI）

平台应用：

  • macOS 菜单栏应用
  • iOS 应用
  • Android 应用

这种广泛的通道支持是 OpenClaw 最大的特色之一------你可以在任何你常用的平台上与 AI 对话。

安全机制：配对与白名单

这是 OpenClaw 最重要的安全设计之一。

默认情况下，OpenClaw 对所有 DM（私信）采取**配对（pairing）**策略。这意味着：

  • 如果有人通过 WhatsApp/Telegram/Discord 给你发送私信，OpenClaw 不会立即处理
  • 系统会回复一个配对码
  • 你需要手动批准（通过 openclaw pairing approve <channel> <code>）
  • 批准后，该发送者被加入白名单，后续消息才会被处理

这种设计的原因是：OpenClaw 连接到真实的消息平台，必须把收到的 DM 当作不可信输入。配对机制确保只有经过你授权的人才能与 AI 助手交互。

你也可以配置其他策略：

  • dmPolicy: "allowlist" ------ 只接受白名单中的发送者
  • dmPolicy: "open" ------ 接受所有消息（不推荐）
  • dmPolicy: "disabled" ------ 完全禁用 DM

在群组中，OpenClaw 的行为同样可控：

  • 默认情况下，OpenClaw 不会自动响应群组消息（需要 @提及或配置激活模式）
  • 可以配置 requireMention: true 要求必须 @机器人
  • 群组白名单可以控制哪些群组可以使用 OpenClaw

Agent 与会话模型入门

什么是 Agent？

在 OpenClaw 中，「Agent」指的是 AI 助手实例。它不是某个具体的 AI 模型，而是一个配置单元------包含使用的模型、工作空间、可用工具、安全策略等。

你可以配置多个 Agent，比如：

  • 一个用于日常聊天的 Agent（使用较轻量的模型）
  • 一个用于编程任务的 Agent（使用最强大的模型）
  • 一个用于特定项目的 Agent（有独立的工作空间）

默认情况下，OpenClaw 只有一个 main Agent，处理所有通道的消息。

工作空间（Workspace）

每个 Agent 都有一个工作空间 目录，这是 AI 唯一可以访问的文件系统区域。默认路径是 ~/.openclaw/workspace。

在这个目录中，OpenClaw 会查找几个特殊的引导文件（Bootstrap Files）：

  • AGENTS.md ------ AI 的操作指令和「记忆」
  • SOUL.md ------ AI 的人设、边界、语气
  • TOOLS.md ------ 你维护的工具使用说明
  • IDENTITY.md ------ AI 的名字和风格
  • USER.md ------ 你的个人资料和偏好
  • BOOTSTRAP.md ------ 首次运行时的一次性引导脚本

每次新会话开始时，OpenClaw 会把这些文件的内容注入到 AI 的系统提示中。这意味着你可以随时修改这些文件来调整 AI 的行为，而不需要重新配置。

会话（Session）

「会话」是一次对话的上下文。当你在某个通道上开始与 OpenClaw 对话时，一个会话就被创建了。会话包含：

  • 对话历史（消息和回复）
  • AI 的推理过程（tool use、thinking）
  • 当前的上下文窗口

OpenClaw 的会话模型有几个关键概念：

主会话（main session）： 标记为 main 的会话，直接与你（所有者）对话。在主会话中，工具执行默认是「完全信任」的------AI 可以执行命令、读写文件。

非主会话（non-main session）： 群组消息、其他 DM 等创建的会话。这些会话默认有更多限制，特别是在启用沙箱时。

会话持久化： 会话历史以 JSONL 格式保存在 ~/.openclaw/agents/<agentId>/sessions/ 目录下。这意味着即使 Gateway 重启，对话历史也会保留。

工具执行与流式响应

OpenClaw 的一个强大特性是流式响应。当 AI 在响应过程中调用工具（比如执行命令、读取文件），工具的输出会实时流回到对话中，而不是等到整个响应完成。

这对于长时间运行的命令特别有用------你可以看到命令的实时输出，而不是等待它完成。

工具与技能系统入门

工具（Tools）

工具是 AI 执行具体动作的方式。OpenClaw 内置了一套核心工具：

工具 功能
exec / process 执行 shell 命令
browser 控制 Chromium 浏览器（导航、点击、截图）
web_search / web_fetch 搜索网页、获取页面内容
read / write / edit 文件读写操作
apply_patch 应用多区块代码补丁
message 跨通道发送消息
canvas 控制节点上的 Canvas（可视化工作区）
nodes 发现和控制配对的设备
cron / gateway 管理定时任务、网关操作
image / image_generate 图片分析和生成
sessions_* 会话管理、子代理

这些工具通过 OpenAI 兼容的 Function Calling 机制暴露给 AI 模型。AI 根据对话上下文决定何时调用哪个工具。

工具策略（Tool Policy）

工具不是无限制开放的。你可以通过配置控制 AI 能使用哪些工具：

json5 复制代码 
{
  tools: {
    allow: ["group:fs", "browser", "web_search"],
    deny: ["exec"],
  }
}

这种机制叫做「工具策略」。它有几个重要概念：

Allow（允许列表）： 明确允许使用的工具
Deny（拒绝列表）： 明确禁止的工具（优先级高于 allow）
Profile（预设）： 预定义的工具集

  • full ------ 所有工具（默认）
  • coding ------ 文件 I/O、运行时、会话、内存、图片
  • messaging ------ 消息相关工具
  • minimal ------ 仅 session_status

工具组： 可以用简写引用一组工具

  • group:runtime ------ exec, bash, process
  • group:fs ------ read, write, edit, apply_patch
  • group:web ------ web_search, web_fetch
  • group:ui ------ browser, canvas

技能（Skills）

如果说工具是 AI 的「手」，那么技能就是 AI 的「脑」。技能是 Markdown 文件（SKILL.md），在每次会话开始时被注入到 AI 的系统提示中。

技能可以包含：

  • 特定领域的知识（比如如何使用某个 API）
  • 工作流程指导（比如如何进行代码审查）
  • 约束和边界（比如什么该做什么不该做）
  • 示例和最佳实践

OpenClaw 从三个位置加载技能（优先级从低到高）：

  1. 内置技能 ------ 随 OpenClaw 发行
  2. 托管技能 ------ ~/.openclaw/skills 目录
  3. 工作空间技能 ------ <workspace>/skills 目录

当多个位置有同名技能时，工作空间版本优先。

插件（Plugins）

插件是 OpenClaw 扩展能力的终极方式。一个插件可以打包任意组合：

  • 新的消息通道
  • 新的模型提供商
  • 新的工具
  • 新的技能
  • 语音合成
  • 图片生成
  • 等等

插件通过 npm 包分发，可以独立发布和维护。OpenClaw 官方也提供了一些核心插件。

沙箱与安全入门

为什么需要沙箱？

OpenClaw 的 AI 可以执行命令、读写文件------这意味着如果 AI 被诱导执行危险操作（比如删除重要文件、运行恶意命令），后果可能很严重。

沙箱（Sandbox）是一种安全机制，它在隔离环境中运行工具，而不是直接在主机上执行。即使 AI 犯了错误，损害也局限于沙箱内部。

沙箱模式

OpenClaw 支持多种沙箱模式，通过 agents.defaults.sandbox.mode 配置：

  • "off" ------ 不使用沙箱，工具直接在主机执行
  • "non-main" ------ 仅对非主会话（群组、其他 DM）使用沙箱
  • "all" ------ 所有会话都使用沙箱

对于大多数个人用户，"non-main" 是合理的默认值------你自己的直接对话有完全信任，群组和陌生人的消息则在隔离环境中处理。

沙箱后端

OpenClaw 支持多种沙箱后端：

Docker（默认）： 在本地容器中执行工具。需要提前构建镜像：

bash 复制代码 
scripts/sandbox-setup.sh

SSH： 在远程 SSH 主机上执行工具。适合将执行负载转移到其他机器。

OpenShell： 托管的沙箱服务，提供更高级的管理功能。

工作空间访问

沙箱的工作空间访问模式通过 workspaceAccess 控制：

  • "none" ------ 工具只能访问沙箱内的临时目录
  • "ro" ------ 以只读方式挂载主机工作空间
  • "rw" ------ 以读写方式挂载主机工作空间

提升模式（Elevated）

对于确实需要在主机上执行命令的场景（比如安装系统包），OpenClaw 提供了「提升模式」。通过 /elevated on 命令，可以在当前会话中临时提升权限，让工具绕过沙箱直接在主机执行。

快速开始

环境要求

  • Node.js ------ Node 24 推荐（Node 22.16+ 也支持）
  • 模型 API Key ------ 需要从 Anthropic、OpenAI、Google 等提供商获取

安装步骤

macOS / Linux：

bash 复制代码 
curl -fsSL https://openclaw.ai/install.sh | bash

Windows（PowerShell）：

powershell 复制代码 
iwr -useb https://openclaw.ai/install.ps1 | iex

通过 npm：

bash 复制代码 
npm install -g openclaw@latest

首次配置

运行引导程序：

bash 复制代码 
openclaw onboard --install-daemon

这个命令会：

  1. 让你选择模型提供商并输入 API Key
  2. 配置 Gateway
  3. 安装系统服务（让 Gateway 开机自启）

验证安装

bash 复制代码 
# 检查 Gateway 状态
openclaw gateway status

# 打开控制面板
openclaw dashboard

# 发送测试消息
openclaw agent --message "Hello"

添加消息通道

最简单的方式是添加 Telegram：

  1. 在 Telegram 中搜索 @BotFather，创建新机器人，获取 Token
  2. 配置 OpenClaw：
bash 复制代码 
openclaw config set channels.telegram.botToken "你的Token"

或者运行 openclaw channels login 进行交互式配置。

配置详解

配置文件位置

OpenClaw 的配置文件位于 ~/.openclaw/openclaw.json（可以通过 OPENCLAW_CONFIG_PATH 环境变量覆盖）。

最小配置

json5 复制代码 
{
  agents: {
    defaults: {
      workspace: "~/.openclaw/workspace"
    }
  },
  channels: {
    whatsapp: {
      allowFrom: ["+15555550123"]
    }
  }
}

第一部分：Gateway 架构与协议

1.1 Gateway 核心概念

Gateway 是 OpenClaw 的中央控制器，它是一个长期运行的后台服务（daemon），负责：

  • 消息路由：接收来自所有通道的消息，路由到正确的 Agent 和会话
  • 连接管理：维护与所有消息平台的连接（WhatsApp、Telegram、Discord 等）
  • Agent 运行时：调用大语言模型，处理对话上下文，执行工具
  • WebSocket 服务：为所有客户端（CLI、Web UI、macOS 应用、节点）提供统一的控制平面
  • 任务调度：处理 Cron 定时任务、Webhook 触发、心跳等

Gateway 默认监听在 127.0.0.1:18789，使用 WebSocket 协议与客户端通信。这是一个关键设计决策：所有客户端共享同一个 AI 上下文，而不是各自为政。

1.2 WebSocket 协议详解

Gateway 的 WebSocket 协议是整个系统的血管。理解它的工作原理对于理解 OpenClaw 至关重要。

1.2.1 连接握手

客户端连接 Gateway 的第一步是握手。协议使用 JSON 格式的文本帧。

服务器首先发送挑战（pre-connect challenge）：

json 复制代码 
{
  "type": "event",
  "event": "connect.challenge",
  "payload": { "nonce": "abc123...", "ts": 1737264000000 }
}

客户端需要用私钥对这个 nonce 进行签名，证明它拥有对应的设备身份。然后发送 connect 请求：

json 复制代码 
{
  "type": "req",
  "id": "req-001",
  "method": "connect",
  "params": {
    "minProtocol": 3,
    "maxProtocol": 3,
    "client": {
      "id": "cli",
      "version": "1.2.3",
      "platform": "macos",
      "mode": "operator"
    },
    "role": "operator",
    "scopes": ["operator.read", "operator.write"],
    "caps": [],
    "commands": [],
    "permissions": {},
    "auth": { "token": "..." },
    "locale": "en-US",
    "userAgent": "openclaw-cli/1.2.3",
    "device": {
      "id": "device_fingerprint",
      "publicKey": "...",
      "signature": "...",
      "signedAt": 1737264000000,
      "nonce": "..."
    }
  }
}

服务器验证签名后，返回 hello-ok 响应：

json 复制代码 
{
  "type": "res",
  "id": "req-001",
  "ok": true,
  "payload": {
    "type": "hello-ok",
    "protocol": 3,
    "policy": { "tickIntervalMs": 15000 }
  }
}
1.2.2 角色与权限

客户端在连接时声明自己的 角色（role）：

  • operator：控制平面客户端，包括 CLI、Web UI、macOS 应用、自动化脚本
  • node：能力主机，暴露设备功能（相机、屏幕、Canvas、system.run）

对于 operator 角色，还可以声明 作用域（scopes）：

  • operator.read：读取状态、信息
  • operator.write：发送消息、执行操作
  • operator.admin：管理配置
  • operator.approvals：处理执行审批
  • operator.pairing：设备配对管理

对于 node 角色，需要声明 能力（caps） 和 命令（commands）：

json 复制代码 
{
  "role": "node",
  "caps": ["camera", "canvas", "screen", "location", "voice"],
  "commands": ["camera.snap", "canvas.navigate", "screen.record", "location.get"],
  "permissions": { "camera.capture": true, "screen.record": false }
}
1.2.3 消息帧格式

握手完成后，所有通信使用三种帧类型：

请求帧（Request）：

json 复制代码 
{ "type": "req", "id": "req-002", "method": "agent", "params": {...} }

响应帧（Response）：

json 复制代码 
{ "type": "res", "id": "req-002", "ok": true, "payload": {...} }

事件帧（Event）：

json 复制代码 
{ "type": "event", "event": "agent", "payload": {...}, "seq": 1 }

对于有副作用的方法（如 send、agent），请求需要包含 幂等性密钥（idempotency key），防止重试导致重复执行。

1.2.4 设备身份与配对

OpenClaw 使用基于密钥的设备身份系统：

  1. 每个设备生成一个密钥对
  2. 设备 ID 是公钥的指纹
  3. 连接时，设备需要对服务器提供的 nonce 进行签名
  4. 首次连接需要配对批准（除非是本地连接）
  5. 配对成功后，服务器发放设备令牌（device token），后续连接可以使用

这种设计确保：

  • 只有经过授权的设备才能连接到 Gateway
  • 本地连接（loopback）可以自动批准
  • 远程连接需要显式配对

1.3 Gateway 的核心功能

1.3.1 消息处理管道

当一条消息到达 Gateway 时，处理流程如下：

  1. 通道接收：通道模块接收来自 WhatsApp/Telegram/Discord 等平台的消息
  2. 安全检查：验证发送者是否在白名单、是否需要配对
  3. 会话解析：根据通道、发送者确定使用哪个会话
  4. 上下文构建：加载会话历史、工作空间文件、技能
  5. Agent 调用：将消息发送给 Agent 运行时
  6. 工具执行：Agent 可能调用工具（exec、browser 等）
  7. 响应发送：将 Agent 的回复通过原通道发送回去
1.3.2 心跳系统

Gateway 内置心跳机制，用于：

  • 定期提醒：定时触发 Agent，可以用于主动提醒场景
  • 健康检查：让 Agent 定期"醒来"执行任务
  • 状态刷新：定期更新状态、清理过期数据

心跳通过 gateway.heartbeat 配置：

json5 复制代码 
{
  gateway: {
    heartbeat: {
      every: "15m",  // 每 15 分钟触发一次
      prompt: "Check if there's anything to do."
    }
  }
}
1.3.3 定时任务（Cron）

Gateway 内置 Cron 调度器，支持：

  • 一次性任务：在指定时间触发
  • 循环任务：使用 cron 表达式
  • 间隔任务：固定间隔重复

任务可以运行在：

  • 主会话：使用现有的主会话上下文
  • 独立会话：创建新的隔离会话
  • 当前会话：绑定到创建任务时的会话
  • 自定义会话：指定一个持久化的会话 ID

任务输出可以通过：

  • announce：发送到指定通道
  • webhook：POST 到 HTTP 端点
  • none：仅内部处理

第二部分：消息通道系统

2.1 通道架构概述

OpenClaw 的通道系统采用插件式架构。每个通道是一个独立的模块，通过统一的接口与 Gateway 交互。

核心通道（内置）：

  • WhatsApp（通过 Baileys 库，Web 协议）
  • Telegram（通过 Bot API）
  • Discord（通过 Bot API）
  • Slack（通过 Bolt SDK）
  • Signal（通过 signal-cli）
  • iMessage（通过 BlueBubbles）
  • Google Chat
  • IRC
  • WebChat（通过 Gateway 的 Web UI）

扩展通道（插件）：

  • Microsoft Teams（@openclaw/msteams）
  • Matrix（@openclaw/matrix）
  • LINE（@openclaw/line）
  • Mattermost（@openclaw/mattermost）
  • Nostr（@openclaw/nostr）
  • Zalo（@openclaw/zalo）
  • Feishu（飞书）

2.2 WhatsApp 通道深度解析

WhatsApp 是最常用的通道之一，使用 Baileys 库连接 WhatsApp Web。

2.2.1 连接机制

WhatsApp 使用 QR 码配对方式：

bash 复制代码 
openclaw channels login --channel whatsapp

这会：

  1. 生成一个 QR 码
  2. 用手机 WhatsApp 扫描
  3. 保存认证信息到 ~/.openclaw/credentials/whatsapp/

认证信息存储在 creds.json 中，包含：

  • WhatsApp Web 会话信息
  • 设备密钥
  • 服务器时间同步
2.2.2 消息处理

接收消息：

  • Gateway 维护一个 WebSocket 连接，监听新消息
  • 收到消息后，解析出发送者、内容、群组信息
  • 应用 DM 策略（pairing/allowlist/open/disabled）
  • 转换为统一的内部格式，发送给 Agent

发送消息：

  • 通过 Baileys 库发送消息到 WhatsApp
  • 支持文本、图片、视频、音频、文档
  • 自动处理分片（超过 4000 字符）
2.2.3 安全策略

WhatsApp 通道有完善的安全控制：

DM 策略（dmPolicy）：

  • pairing（默认）：未知发送者需要配对批准
  • allowlist：只接受白名单中的发送者
  • open：接受所有消息（需要 allowFrom 包含 "*")
  • disabled：完全禁用 DM

群组策略：

  • groupPolicy：控制群组消息访问
  • groupAllowFrom：群组白名单
  • groups：群组白名单（设置后只有白名单中的群组可用）

个人号保护：

  • 如果你的个人号也在 allowFrom 中，OpenClaw 会启用自聊天保护
  • 避免自己发送的消息被当作用户消息处理

2.3 Telegram 通道

Telegram 使用 Bot API，相对简单：

  1. 从 @BotFather 获取 Bot Token
  2. 配置 channels.telegram.botToken
  3. 可选：配置 Webhook 或使用 Long Polling

群组支持：

  • 支持普通群组和论坛主题（Forum Topics）
  • 可以配置 requireMention 要求必须 @机器人
  • 支持话题隔离

2.4 Discord 通道

Discord 使用 Bot API 和 Gateway：

  1. 在 Discord Developer Portal 创建应用
  2. 添加 Bot 用户
  3. 获取 Token 并配置

功能支持：

  • 服务器和频道消息
  • DM 消息
  • Slash 命令
  • 消息组件（Buttons、Selects）

第三部分：Agent 运行时

3.1 Agent 核心概念

OpenClaw 的 Agent 运行时是基于 Pi agent core 构建的。它负责：

  • 管理对话上下文
  • 调用大语言模型
  • 处理工具调用
  • 管理会话状态

3.2 工作空间（Workspace）

每个 Agent 都有一个工作空间目录（默认 ~/.openclaw/workspace），这是 Agent 唯一可以访问的文件系统区域。

引导文件（Bootstrap Files）：

每次新会话开始时，这些文件的内容被注入到 Agent 的系统提示中。

3.3 会话管理

3.3.1 会话键（Session Key）

OpenClaw 使用会话键来标识不同的对话：

  • 主会话 ：agent:<agentId>:main（默认）
  • DM 会话 ：根据 session.dmScope 配置
    • main：所有 DM 共享主会话
    • per-peer：按发送者隔离
    • per-channel-peer：按通道+发送者隔离
    • per-account-channel-peer：按账户+通道+发送者隔离
  • 群组会话 ：agent:<agentId>:<channel>:group:<id>
  • Cron 会话 ：cron:<jobId>
3.3.2 会话存储

会话状态存储在：

  • 会话索引 ：~/.openclaw/agents/<agentId>/sessions/sessions.json
  • 对话历史 ：~/.openclaw/agents/<agentId>/sessions/<sessionId>.jsonl
3.3.3 会话重置

支持多种重置策略：

  • 每日重置：默认每天 4 AM（Gateway 主机本地时间）
  • 空闲重置：超过指定空闲时间后重置
  • 手动重置 ：通过 /new 或 /reset 命令

3.4 上下文管理

3.4.1 上下文构建

每次 Agent 运行时，上下文按以下顺序构建：

  1. 系统提示（来自工作空间引导文件）
  2. 技能列表（来自 skills/ 目录）
  3. 会话历史（最近的对话）
  4. 当前用户消息
3.4.2 上下文修剪

为了控制上下文大小，OpenClaw 会自动修剪：

  • 工具结果修剪：在 LLM 调用前，修剪旧的工具结果
  • 会话压缩 ：通过 /compact 命令手动压缩
  • 预压缩内存flush：接近自动压缩时，提醒模型写笔记到磁盘

第四部分：工具系统

4.1 工具架构

OpenClaw 的工具系统是 Agent 执行具体动作的方式。工具通过 OpenAI 兼容的 Function Calling 机制暴露给模型。

工具调用流程：

  1. Agent 决定需要调用某个工具
  2. 生成工具调用请求（函数名、参数）
  3. Gateway 执行工具
  4. 返回结果给 Agent
  5. Agent 基于结果继续推理或生成回复

4.2 核心工具详解

4.2.1 exec / process（命令执行）

exec 是最强大的工具，允许 Agent 执行 shell 命令。

参数：

  • command：要执行的命令
  • workdir：工作目录（默认 workspace）
  • env：环境变量覆盖
  • yieldMs：自动后台超时（默认 10000ms）
  • background：立即后台执行
  • timeout：超时时间（秒，默认 1800）
  • pty：是否使用伪终端
  • host：执行位置（sandbox | gateway | node）
  • security：安全模式（deny | allowlist | full）
  • ask：审批模式（off | on-miss | always）

执行位置：

  • sandbox（默认）：在沙箱容器中执行
  • gateway：在 Gateway 主机上执行
  • node：在配对的节点上执行

安全模式：

  • deny：拒绝执行
  • allowlist：只在白名单中的命令可以执行
  • full：允许所有命令

审批机制：

  • 当需要审批时，返回 status: "approval-pending"
  • 客户端可以通过 exec.approval.resolve 批准或拒绝
4.2.2 browser（浏览器控制）

OpenClaw 可以控制一个专用的 Chromium 浏览器。

核心功能：

  • 标签页管理（打开、关闭、切换）
  • 导航（URL、后退、前进）
  • 快照（获取页面内容）
  • 截图
  • 交互（点击、输入、滚动）

配置：

json5 复制代码 
{
  browser: {
    enabled: true,
    defaultProfile: "openclaw",
    profiles: {
      openclaw: { cdpPort: 18800, color: "#FF4500" },
      user: { driver: "existing-session", attachOnly: true }
    }
  }
}

Profile 类型：

  • openclaw：托管的独立浏览器（无痕）
  • existing-session：附加到已运行的 Chrome 会话

快照格式：

  • ai：AI 友好的快照，包含数字引用
  • aria：无障碍树快照

交互方式：

  • 使用快照返回的引用（ref）进行操作
  • 例如：click 12、type 23 "hello"
  • web_search：搜索网页
  • web_fetch：获取页面内容

支持多种搜索提供商：

  • Brave Search（默认）
  • Google
  • DuckDuckGo
  • SerpAPI
4.2.4 read / write / edit（文件操作）
  • read：读取文件
  • write：写入文件
  • edit：编辑文件（精确替换）

这些工具受限于工作空间目录。

4.2.5 message（消息发送）

跨通道发送消息：

json 复制代码 
{
  "tool": "message",
  "channel": "telegram",
  "to": "user:123456",
  "message": "Hello!"
}
4.2.6 canvas（Canvas 控制）

控制配对设备的 Canvas（可视化工作区）：

  • canvas.present：显示内容
  • canvas.navigate：导航
  • canvas.eval：执行 JavaScript
  • canvas.snapshot：截图
4.2.7 nodes（节点控制）

发现和控制配对的设备：

  • nodes.list：列出可用节点
  • nodes.invoke：调用节点命令
  • nodes.run：在节点上执行命令

4.3 工具策略

通过配置控制工具的可用性：

json5 复制代码 
{
  tools: {
    allow: ["group:fs", "browser", "web_search"],
    deny: ["exec"],
    profile: "full"
  }
}

工具组：

  • group:runtime：exec, bash, process
  • group:fs：read, write, edit, apply_patch
  • group:web：web_search, web_fetch
  • group:ui：browser, canvas
  • group:sessions：sessions_*
  • group:messaging：message

第五部分：技能与插件系统

5.1 技能（Skills）

技能是 Markdown 文件（SKILL.md），在每次会话开始时被注入到 Agent 的系统提示中。

5.1.1 技能位置

技能从三个位置加载（优先级从低到高）：

  1. 内置技能：随 OpenClaw 发行
  2. 托管技能 ：~/.openclaw/skills
  3. 工作空间技能 ：<workspace>/skills
5.1.2 技能格式
markdown 复制代码 
---
name: image-lab
description: Generate or edit images via a provider-backed image workflow
metadata: {"openclaw": {"requires": {"bins": ["uv"], "env": ["GEMINI_API_KEY"]}}}
---

# Image Lab

Use this skill to generate or edit images...

元数据字段：

  • always：总是加载
  • os：平台限制（darwin/linux/win32）
  • requires.bins：需要的二进制
  • requires.env：需要的环境变量
  • requires.config：需要的配置
5.1.3 技能门控

技能在加载时根据条件过滤：

  • 检查二进制是否在 PATH 中
  • 检查环境变量是否存在
  • 检查配置是否启用
  • 检查操作系统是否匹配

5.2 插件（Plugins）

插件是扩展 OpenClaw 能力的主要方式。

5.2.1 插件类型
  • 内置插件：随 OpenClaw 发行（模型提供商、语音提供商）
  • 可安装插件：通过 npm 安装（WhatsApp、Telegram 等通道插件）
  • 外部插件：社区开发
5.2.2 插件能力

插件可以注册：

  • 通道：新的消息平台
  • 提供商：新的模型提供商
  • 工具：新的 Agent 工具
  • 技能：新的技能
  • 语音：TTS/STT 提供商
  • 图片生成：图片生成提供商
5.2.3 插件配置
json5 复制代码 
{
  plugins: {
    entries: {
      "voice-call": {
        enabled: true,
        config: { provider: "twilio" }
      }
    }
  }
}

5.3 ClawHub

ClawHub（clawhub.com）是 OpenClaw 的技能市场：

bash 复制代码 
openclaw skills install <skill-slug>
openclaw skills update --all

第六部分：沙箱与安全

6.1 沙箱模式

OpenClaw 支持在隔离环境中运行工具，限制潜在损害。

6.1.1 模式
  • off：不使用沙箱
  • non-main（默认）：仅非主会话使用沙箱
  • all：所有会话使用沙箱
6.1.2 后端
  • Docker（默认）：本地容器
  • SSH：远程 SSH 主机
  • OpenShell：托管沙箱服务
6.1.3 工作空间访问
  • none：工具只能访问临时目录
  • ro：只读挂载工作空间
  • rw：读写挂载工作空间

6.2 安全机制

6.2.1 DM 配对

默认情况下，OpenClaw 对所有 DM 采取配对策略：

  1. 未知发送者收到配对码
  2. 你通过 openclaw pairing approve 批准
  3. 批准后，发送者加入白名单
6.2.2 工具策略

通过 tools.allow / tools.deny 控制工具可用性。

6.2.3 执行审批

对于 gateway 或 node 位置的 exec，可以配置审批机制：

json5 复制代码 
{
  tools: {
    exec: {
      security: "allowlist",
      ask: "on-miss"
    }
  }
}

审批规则存储在 ~/.openclaw/exec-approvals.json。

第七部分：节点系统

7.1 节点概念

节点是连接到 Gateway 的伴侣设备，提供设备特定的能力。

7.2 节点类型

7.2.1 macOS 节点

macOS 应用可以运行在"节点模式"：

  • Canvas：可视化工作区
  • 相机：拍照、录像
  • 屏幕录制：录制屏幕
  • system.run：本地命令执行
  • system.notify：本地通知
7.2.2 iOS 节点

iOS 应用提供：

  • Canvas
  • Voice Wake（语音唤醒）
  • Talk Mode（语音对话）
  • 相机
  • 屏幕录制
7.2.3 Android 节点

Android 应用提供：

  • Canvas
  • 语音
  • 相机
  • 屏幕录制
  • 设备命令（通知、位置、短信、照片、日历等）

7.3 节点配对

节点通过 WebSocket 连接到 Gateway：

  1. 节点发起连接，声明 role: node
  2. Gateway 创建设备配对请求
  3. 你通过 openclaw devices approve 批准
  4. 节点获得设备令牌，后续连接自动认证

7.4 远程节点主机

可以在任何机器上运行节点主机服务：

bash 复制代码 
openclaw node run --host <gateway-host> --port 18789

这允许：

  • 远程执行命令（exec host=node）
  • 远程浏览器控制
  • 访问远程设备的相机/屏幕

第八部分：媒体处理

8.1 图片处理

8.1.1 图片分析

使用 image 工具分析图片：

  • 描述图片内容
  • 提取文本（OCR）
  • 分析图表
8.1.2 图片生成

使用 image_generate 工具生成图片：

  • 支持多种提供商（OpenAI DALL-E、Google Imagen、Stability AI）
  • 可以指定尺寸、风格、质量

8.2 音频处理

8.2.1 语音转文字

当收到语音消息时，OpenClaw 可以自动转录：

自动检测顺序：

  1. 本地 CLI（sherpa-onnx、whisper-cli、whisper）
  2. Gemini CLI
  3. 云端提供商（OpenAI、Deepgram、Google）

配置：

json5 复制代码 
{
  tools: {
    media: {
      audio: {
        enabled: true,
        maxBytes: 20971520,
        models: [
          { provider: "openai", model: "gpt-4o-mini-transcribe" }
        ]
      }
    }
  }
}
8.2.2 文字转语音

使用 elevenlabs 或 microsoft 语音提供商：

json5 复制代码 
{
  speech: {
    provider: "elevenlabs",
    voice: "rachel"
  }
}

8.3 视频处理

视频消息：

  • 下载视频
  • 提取音频进行转录
  • 生成缩略图

第九部分：自动化

9.1 Cron 任务

Gateway 内置 Cron 调度器。

9.1.1 任务类型
  • 一次性任务 ：schedule.kind = "at"
  • 循环任务 ：schedule.kind = "cron"
  • 间隔任务 ：schedule.kind = "every"
9.1.2 执行模式
  • 主会话：使用主会话上下文
  • 独立会话：新建隔离会话
  • 当前会话：绑定到创建时的会话
  • 自定义会话：指定会话 ID
9.1.3 传递机制
  • announce：发送到通道
  • webhook：POST 到 HTTP 端点
  • none：仅内部处理

9.2 Webhook

可以通过 Webhook 触发 Agent：

bash 复制代码 
# 发送 webhook
curl -X POST http://127.0.0.1:18789/hooks/invoke \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello from webhook"}'

9.3 Gmail Pub/Sub

可以配置 Gmail 监听新邮件：

json5 复制代码 
{
  hooks: {
    gmail: {
      enabled: true,
      webhookUrl: "https://..."
    }
  }
}

第十部分：配置系统

10.1 配置文件

OpenClaw 使用 JSON5 格式的配置文件：~/.openclaw/openclaw.json

10.2 配置结构

json5 复制代码 
{
  // Agent 配置
  agents: {
    defaults: {
      workspace: "~/.openclaw/workspace",
      model: { primary: "anthropic/claude-opus-4-6" },
      sandbox: { mode: "non-main" }
    }
  },
  
  // 通道配置
  channels: {
    whatsapp: { allowFrom: ["+15551234567"] },
    telegram: { botToken: "..." }
  },
  
  // 工具配置
  tools: {
    exec: { host: "sandbox" },
    browser: { enabled: true }
  },
  
  // 插件配置
  plugins: { ... },
  
  // Cron 配置
  cron: { ... },
  
  // 网关配置
  gateway: { ... }
}

10.3 配置方式

  • CLI ：openclaw config set/get/unset
  • Control UI：Web 界面
  • 直接编辑：修改配置文件

10.4 热重载

Gateway 支持配置热重载：

  • gateway.reload.mode: "off"：禁用重载
  • gateway.reload.mode: "hot"：仅热安全变更
  • gateway.reload.mode: "restart"：需要重启的变更
  • gateway.reload.mode: "hybrid"（默认）：自动选择

第十一部分：CLI 与客户端

11.1 CLI 命令

bash 复制代码 
# Gateway 管理
openclaw gateway start/stop/restart/status
openclaw gateway install  # 安装为系统服务

# 通道管理
openclaw channels list/status/login/logout

# Agent 交互
openclaw agent --message "Hello"
openclaw message send --to +1234567890 --message "Hello"

# 配对管理
openclaw pairing list/approve/reject
openclaw devices list/approve/reject

# 节点管理
openclaw nodes list/status/invoke

# Cron 管理
openclaw cron add/list/edit/remove/run

# 技能管理
openclaw skills list/install/update

# 插件管理
openclaw plugins list/install/enable/disable

# 配置管理
openclaw config get/set/unset

11.2 Control UI

Gateway 提供 Web 控制面板：

  • Dashboard：状态概览
  • Chat：直接聊天
  • Config：配置管理
  • Nodes：节点管理
  • Skills：技能管理
  • Logs：日志查看

访问地址：http://127.0.0.1:18789

11.3 macOS 应用

OpenClaw macOS 应用提供：

  • 菜单栏快速访问
  • 通知
  • 节点模式
  • Voice Wake
  • WebChat

第十二部分：部署与运维

12.1 安装方式

  • npm/pnpm：全局安装
  • Docker：容器化部署
  • Nix：声明式配置
  • 脚本：一键安装脚本

12.2 系统服务

  • macOS：launchd
  • Linux (user)：systemd user
  • Linux (system)：systemd

12.3 远程访问

  • Tailscale：推荐的安全方式
  • SSH 隧道：备用方案

12.4 日志

bash 复制代码 
openclaw logs --follow

日志位置：~/.openclaw/logs/

12.5 诊断

bash 复制代码 
openclaw doctor  # 诊断并修复常见问题
openclaw health  # 健康检查

第十三部分：认证与授权系统

13.1 认证架构概述

OpenClaw 的认证系统分为两个层面：

  1. Gateway 访问认证：控制谁能连接到 Gateway
  2. 模型提供商认证：控制能使用哪些模型

13.2 Gateway 访问认证

13.2.1 令牌认证
json5 复制代码 
{
  gateway: {
    auth: {
      token: "your-gateway-token",
      password: "your-gateway-password"
    }
  }
}

或者通过环境变量：

bash 复制代码 
export OPENCLAW_GATEWAY_TOKEN="your-gateway-token"
13.2.2 设备配对

首次连接时，设备需要配对：

  1. 设备生成密钥对
  2. 设备 ID = 公钥指纹
  3. 连接时对服务器 nonce 签名
  4. 服务器创建配对请求
  5. 用户批准后，设备获得令牌
13.2.3 设备身份验证迁移

协议经历了从 v1 到 v2/v3 的迁移：

消息 错误码 原因
device nonce required DEVICE_AUTH_NONCE_REQUIRED 客户端未提供 nonce
device nonce mismatch DEVICE_AUTH_NONCE_MISMATCH 使用了 stale/wrong nonce
device signature invalid DEVICE_AUTH_SIGNATURE_INVALID 签名 payload 不匹配 v2
device signature expired DEVICE_AUTH_SIGNATURE_EXPIRED 时间戳超出允许范围
device identity mismatch DEVICE_AUTH_DEVICE_ID_MISMATCH device.id 不匹配公钥指纹
device public key invalid DEVICE_AUTH_PUBLIC_KEY_INVALID 公钥格式/规范化失败

v3 签名 payload 绑定更多字段：platform + deviceFamily

13.3 模型提供商认证

13.3.1 认证方式
  • API Key：最简单，适合长期运行
  • OAuth：支持需要登录的提供商（OpenAI Codex）
  • Setup Token：Anthropic 订阅认证
13.3.2 认证存储

认证信息存储在 auth-profiles.json：

  • 位置：~/.openclaw/agents/<agentId>/agent/auth-profiles.json
  • 包含：OAuth 令牌、API 密钥、可选的 SecretRef
13.3.3 多账户支持

两种模式：

  1. 分离 Agent（推荐）：每个账户一个 Agent
  2. 多 Profile：同一个 Agent 多个认证 Profile
bash 复制代码 
# 分离 Agent
openclaw agents add work
openclaw agents add personal

# 多 Profile（同一个 Agent）
/model Opus@anthropic:work
/model Opus@anthropic:personal
13.3.4 API Key 轮换

支持多个 API Key 轮换：

bash 复制代码 
# 优先级（高到低）
OPENCLAW_LIVE_<PROVIDER>_KEY  # 单个实时覆盖
<PROVIDER>_API_KEYS           # 逗号/分号分隔列表
<PROVIDER>_API_KEY            # 主 key
<PROVIDER>_API_KEY_*          # 编号列表

仅在限流错误（429、rate_limit、quota）时轮换。

13.4 OAuth 流程详解

13.4.1 OpenAI Codex OAuth（PKCE）
bash 复制代码 
# 1. 生成 PKCE verifier/challenge + random state
# 2. 打开授权页面
https://auth.openai.com/oauth/authorize?...

# 3. 回调处理
http://127.0.0.1:1455/auth/callback

# 4. 交换令牌
POST https://auth.openai.com/oauth/token

# 5. 存储 { access, refresh, expires, accountId }
13.4.2 令牌刷新
  • 存储 expires 时间戳
  • 运行时检查：如果过期，自动刷新（文件锁保护）
  • 刷新后覆盖存储的凭证

第十四部分：秘密管理系统

14.1 SecretRef 机制

OpenClaw 支持 SecretRef，允许凭证不存储为明文。

14.1.1 SecretRef 格式
json5 复制代码 
{ source: "env" | "file" | "exec", provider: "default", id: "..." }
14.1.2 Source 类型

env（环境变量）：

json5 复制代码 
{ source: "env", provider: "default", id: "OPENAI_API_KEY" }

验证规则：

  • provider：小写字母开头，允许 a-z0-9_-
  • id：大写字母开头，允许 A-Z0-9_

file（文件）：

json5 复制代码 
{ source: "file", provider: "filemain", id: "/providers/openai/apiKey" }

验证规则：

  • id：绝对 JSON 指针（RFC6901）
  • 路径必须通过所有权/权限检查

exec（外部命令）：

json5 复制代码 
{ source: "exec", provider: "vault", id: "providers/openai/apiKey" }

验证规则：

  • id：不能包含 .. 或 . 作为路径段

14.2 Provider 配置

json5 复制代码 
{
  secrets: {
    providers: {
      default: { source: "env" },
      filemain: {
        source: "file",
        path: "~/.openclaw/secrets.json",
        mode: "json"  // 或 "singleValue"
      },
      vault: {
        source: "exec",
        command: "/usr/local/bin/openclaw-vault-resolver",
        args: ["--profile", "prod"],
        passEnv: ["PATH", "VAULT_ADDR"],
        jsonOnly: true
      }
    },
    defaults: {
      env: "default",
      file: "filemain",
      exec: "vault"
    }
  }
}

14.3 集成示例

14.3.1 1Password CLI
json5 复制代码 
{
  secrets: {
    providers: {
      onepassword_openai: {
        source: "exec",
        command: "/opt/homebrew/bin/op",
        allowSymlinkCommand: true,
        trustedDirs: ["/opt/homebrew"],
        args: ["read", "op://Personal/OpenClaw QA API Key/password"],
        passEnv: ["HOME"],
        jsonOnly: false
      }
    }
  },
  models: {
    providers: {
      openai: {
        apiKey: { source: "exec", provider: "onepassword_openai", id: "value" }
      }
    }
  }
}
14.3.2 HashiCorp Vault
json5 复制代码 
{
  secrets: {
    providers: {
      vault_openai: {
        source: "exec",
        command: "/opt/homebrew/bin/vault",
        args: ["kv", "get", "-field=OPENAI_API_KEY", "secret/openclaw"],
        passEnv: ["VAULT_ADDR", "VAULT_TOKEN"]
      }
    }
  }
}
14.3.3 SOPS
json5 复制代码 
{
  secrets: {
    providers: {
      sops_openai: {
        source: "exec",
        command: "/opt/homebrew/bin/sops",
        args: ["-d", "--extract", '["providers"]["openai"]["apiKey"]', "/path/to/secrets.enc.json"],
        passEnv: ["SOPS_AGE_KEY_FILE"]
      }
    }
  }
}

14.4 运行时行为

  • 激活时机：启动时 + 配置重载时
  • 失败策略：启动失败快速返回，重载失败保持上次已知良好状态
  • 活跃表面过滤：仅验证实际使用的 SecretRef

14.5 审计与配置

bash 复制代码 
# 审计
openclaw secrets audit --check

# 配置
openclaw secrets configure

# 应用计划
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json

第十五部分：模型提供商深度解析

15.1 提供商架构

OpenClaw 的模型提供商系统采用插件式架构：

  • 内置提供商：随 OpenClaw 发行
  • 插件提供商：通过插件注册

15.2 提供商能力接口

提供商插件可以实现的接口：

接口 作用
catalog 提供模型列表
resolveDynamicModel 动态解析模型 ID
prepareDynamicModel 元数据刷新
normalizeResolvedModel URL/传输重写
capabilities 提供商能力元数据
prepareExtraParams 默认/规范化参数
wrapStreamFn 请求包装器
formatApiKey 凭证格式化
refreshOAuth OAuth 刷新
buildAuthDoctorHint 认证修复提示
isCacheTtlEligible 缓存 TTL 资格
buildMissingAuthMessage 认证错误消息
suppressBuiltInModel 隐藏过时模型
augmentModelCatalog 追加模型条目
isBinaryThinking 二进制 thinking UX
supportsXHighThinking xhigh thinking 支持
resolveDefaultThinkingLevel 默认 thinking 级别
isModernModelRef 现代模型匹配
prepareRuntimeAuth 运行时令牌
resolveUsageAuth 用量凭证
fetchUsageSnapshot 用量端点获取

15.3 主要提供商详情

15.3.1 OpenAI
  • Provider ID : openai
  • 认证 : OPENAI_API_KEY
  • 传输: WebSocket 优先，SSE 回退
  • 模型 : gpt-5.4, gpt-5.4-pro
json5 复制代码 
{
  agents: { defaults: { model: { primary: "openai/gpt-5.4" } } }
}
15.3.2 Anthropic
  • Provider ID : anthropic
  • 认证 : ANTHROPIC_API_KEY 或 setup-token
  • 模型 : claude-opus-4-6, claude-sonnet-4-6
json5 复制代码 
{
  agents: { defaults: { model: { primary: "anthropic/claude-opus-4-6" } } }
}
15.3.3 OpenAI Codex
  • Provider ID : openai-codex
  • 认证: OAuth（ChatGPT）
  • 模型 : gpt-5.4
  • 注意: OpenAI 明确支持外部工具使用
15.3.4 OpenCode
  • Provider ID : opencode (Zen), opencode-go (Go)
  • 认证 : OPENCODE_API_KEY
  • 模型 : claude-opus-4-6, kimi-k2.5
15.3.5 其他内置提供商
  • OpenRouter : openrouter
  • Google : google, google-gemini-cli
  • Moonshot : moonshot (Kimi)
  • Mistral : mistral
  • GitHub Copilot : github-copilot
  • Vercel AI Gateway : vercel-ai-gateway
  • Cloudflare AI Gateway : cloudflare-ai-gateway
  • HuggingFace : huggingface
  • NVIDIA : nvidia
  • Amazon Bedrock : bedrock
  • Venice : venice
  • MiniMax : minimax
  • Z.AI : zai

15.4 模型选择规则

模型引用格式：provider/model

json5 复制代码 
{
  agents: {
    defaults: {
      model: {
        primary: "anthropic/claude-opus-4-6",
        // 允许列表（如果设置）
        models: {
          "anthropic/claude-opus-4-6": { enabled: true },
          "anthropic/claude-sonnet-4-6": { enabled: true }
        }
      }
    }
  }
}

第十六部分：协议版本与兼容性

16.1 协议版本管理

Gateway 协议版本定义在 src/gateway/protocol/schema.ts。

typescript 复制代码 
// 客户端声明支持的版本范围
minProtocol: 3,
maxProtocol: 3

// 服务器返回协商后的版本
{ "type": "hello-ok", "protocol": 3 }

16.2 版本历史

  • Protocol 3：当前版本，支持设备身份 v2/v3 签名
  • Protocol 2：遗留版本，仍被接受
  • Protocol 1：已废弃

16.3 兼容性策略

  • 服务器拒绝不兼容的客户端
  • 旧版本客户端可以连接（向后兼容）
  • 新功能通过协议版本控制

第十七部分：故障排查与诊断

17.1 常用诊断命令

bash 复制代码 
# 健康检查
openclaw health

# 自动诊断
openclaw doctor

# 日志查看
openclaw logs --follow

# 通道状态
openclaw channels status

# 模型状态
openclaw models status

# 秘密审计
openclaw secrets audit --check

17.2 常见问题

17.2.1 连接问题
  • 检查 Gateway 是否运行：openclaw gateway status
  • 检查端口是否正确：默认 18789
  • 检查认证令牌
17.2.2 认证问题
  • 检查 API Key：openclaw models status
  • 检查 OAuth 令牌：openclaw models auth
  • 检查 SecretRef：openclaw secrets audit
17.2.3 通道问题
  • 检查通道登录：openclaw channels login
  • 检查配对状态：openclaw pairing list
  • 运行诊断：openclaw doctor

17.3 日志级别

json5 复制代码 
{
  gateway: {
    log: {
      level: "info",  // debug, info, warn, error
      channels: "debug"  // 特定通道日志级别
    }
  }
}

第十八部分：性能与优化

18.1 上下文管理

18.1.1 上下文修剪
  • 工具结果自动修剪
  • 会话压缩（/compact）
  • 预压缩内存 flush
18.1.2 会话维护
json5 复制代码 
{
  session: {
    maintenance: {
      mode: "enforce",  // warn | enforce
      pruneAfter: "30d",
      maxEntries: 500,
      rotateBytes: "10mb"
    }
  }
}

18.2 Cron 性能

18.2.1 运行日志管理
json5 复制代码 
{
  cron: {
    runLog: {
      maxBytes: "2mb",
      keepLines: 2000
    },
    sessionRetention: "24h"
  }
}
18.2.2 避免高峰
  • 整点 cron 任务会自动添加随机延迟（最多 5 分钟）
  • 使用 --exact 强制精确时间

18.3 浏览器资源

  • 浏览器控制服务绑定到 loopback
  • 端口从 Gateway 端口推导（默认 18791）
  • 多个 Profile 使用不同端口（18800-18899）

第十九部分：安全最佳实践

19.1 网络安全

  • 本地模式：Gateway 绑定 loopback
  • 远程访问：使用 Tailscale 或 SSH 隧道
  • TLS：配置 TLS 证书

19.2 认证安全

  • 使用 SecretRef 避免明文凭证
  • 定期轮换 API Key
  • 使用 OAuth 时注意令牌过期

19.3 执行安全

  • 沙箱模式隔离危险操作
  • 工具策略限制可用工具
  • exec 审批机制

19.4 通道安全

  • DM 配对验证发送者
  • 群组白名单控制
  • 敏感信息过滤

第二十部分：多Agent架构深度解析

20.1 多Agent核心概念

OpenClaw 的多Agent系统允许在一个 Gateway 进程中运行多个完全隔离的 Agent。每个 Agent 是独立的"大脑"，拥有：

  • 独立的工作空间（Workspace）：文件、AGENTS.md/SOUL.md/USER.md、本地笔记、人设规则
  • 独立的状态目录（agentDir）：认证配置、模型注册表、per-agent 配置
  • 独立的会话存储 ：聊天历史和路由状态，位于 ~/.openclaw/agents/<agentId>/sessions
20.1.1 单Agent vs 多Agent

单Agent模式（默认）：

  • agentId 默认为 main
  • 会话键：agent:main:<mainKey>
  • 工作空间：~/.openclaw/workspace
  • 状态目录：~/.openclaw/agents/main/agent

多Agent模式：

json5 复制代码 
{
  agents: {
    list: [
      { id: "main", workspace: "~/.openclaw/workspace-main", default: true },
      { id: "work", workspace: "~/.openclaw/workspace-work" },
      { id: "coding", workspace: "~/.openclaw/workspace-coding" }
    ]
  }
}
20.1.2 多Agent的设计目标

OpenClaw 的多 Agent 主要用于隔离不同用途，而不是多 Agent 协作。

典型使用场景：

  • 不同通道绑定不同 Agent：WhatsApp 绑定 home Agent，Telegram 绑定 work Agent
  • 不同模型配置：日常聊天用轻量模型，编程任务用强大模型
  • 不同工作空间：每个 Agent 有独立的文件和人设

Agent 间通信：

  • 默认完全隔离，Agent 间不通信
  • 需要显式启用 agentToAgent 工具才能通信
  • 这种需求很少见，更常见的做法是使用子Agent模式（主 Agent spawn 子 Agent 分配任务）

两种架构：

  • 平行结构：多个独立 Agent，各自处理不同用途
  • 主从结构：主 Agent 管理子Agent，通过"通告链"汇报结果

20.2 Agent隔离机制

20.2.1 认证隔离

认证配置是 per-agent 的：

复制代码 
~/.openclaw/agents/<agentId>/agent/auth-profiles.json

每个 Agent 从自己的 agentDir 读取认证信息。主要 Agent 的凭证不会 自动共享。如果需要共享凭证，需要手动复制 auth-profiles.json 到其他 Agent 的目录。

20.2.2 技能隔离

技能通过每个工作空间的 skills/ 文件夹加载，共享技能从 ~/.openclaw/skills 加载。

子Agent技能隔离 ：子Agent（通过 sessions_spawn spawn的）默认不继承 主Agent的skills。每个子Agent创建时会通过 buildSubagentSystemPrompt 生成独立的系统提示，其中不包含workspace skills。

如需为子Agent配置技能，需要在 agents.list[].skills 中为对应的 targetAgentId 配置技能白名单。例如：

yaml 复制代码 
agents:
  list:
    - id: my-agent
      skills: ["skill-a", "skill-b"]  # 该agent及其spawn的子Agent可用的skills

子Agent会继承 targetAgentId 指定的agent的workspace目录和技能配置。

20.2.3 会话隔离

每个 Agent 有独立的会话存储：

  • 会话索引：~/.openclaw/agents/<agentId>/sessions/sessions.json
  • 对话历史：~/.openclaw/agents/<agentId>/sessions/<sessionId>.jsonl

20.3 消息路由与绑定

20.3.1 绑定机制（Bindings）

Bindings 是确定性的，最具体匹配优先：

  1. peer 匹配（精确 DM/群组/频道 ID）
  2. parentPeer 匹配（线程继承）
  3. guildId + roles（Discord 角色路由）
  4. guildId（Discord）
  5. teamId（Slack）
  6. accountId 匹配（通道账户）
  7. 通道级匹配（accountId: "*"）
  8. 回退到默认 Agent
json5 复制代码 
{
  bindings: [
    // 精确匹配：特定 WhatsApp 号码 → work agent
    {
      agentId: "work",
      match: { channel: "whatsapp", accountId: "biz" }
    },
    // 精确匹配：特定 DM → opus agent
    {
      agentId: "opus",
      match: { channel: "whatsapp", peer: { kind: "direct", id: "+15551234567" } }
    },
    // 通道级匹配：所有 Telegram → opus agent
    { agentId: "opus", match: { channel: "telegram" } },
    // 默认回退
    { agentId: "main", match: { channel: "whatsapp" } }
  ]
}
20.3.2 账户路由

支持多账户的通道（WhatsApp、Telegram、Discord 等）使用 accountId 标识每个登录：

json5 复制代码 
{
  channels: {
    whatsapp: {
      accounts: {
        personal: { /* 认证目录 */ },
        biz: { /* 认证目录 */ }
      }
    }
  }
}

每个 accountId 可以路由到不同的 Agent：

json5 复制代码 
{
  bindings: [
    { agentId: "home", match: { channel: "whatsapp", accountId: "personal" } },
    { agentId: "work", match: { channel: "whatsapp", accountId: "biz" } }
  ]
}

20.4 多Agent配置示例

20.4.1 Discord 多Bot配置
json5 复制代码 
{
  agents: {
    list: [
      { id: "main", workspace: "~/.openclaw/workspace-main" },
      { id: "coding", workspace: "~/.openclaw/workspace-coding" }
    ]
  },
  bindings: [
    { agentId: "main", match: { channel: "discord", accountId: "default" } },
    { agentId: "coding", match: { channel: "discord", accountId: "coding" } }
  ],
  channels: {
    discord: {
      accounts: {
        default: { token: "DISCORD_BOT_TOKEN_MAIN" },
        coding: { token: "DISCORD_BOT_TOKEN_CODING" }
      }
    }
  }
}
20.4.2 WhatsApp 多号码配置
bash 复制代码 
# 登录多个 WhatsApp 账户
openclaw channels login --channel whatsapp --account personal
openclaw channels login --channel whatsapp --account biz
json5 复制代码 
{
  agents: {
    list: [
      { id: "home", workspace: "~/.openclaw/workspace-home", default: true },
      { id: "work", workspace: "~/.openclaw/workspace-work" }
    ]
  },
  bindings: [
    { agentId: "home", match: { channel: "whatsapp", accountId: "personal" } },
    { agentId: "work", match: { channel: "whatsapp", accountId: "biz" } }
  ],
  channels: {
    whatsapp: {
      accounts: {
        personal: {},
        biz: {}
      }
    }
  }
}
20.4.3 通道分离配置

按通道分离：WhatsApp 路由到快速响应 Agent，Telegram 路由到深度工作 Agent：

json5 复制代码 
{
  agents: {
    list: [
      {
        id: "chat",
        name: "Everyday",
        workspace: "~/.openclaw/workspace-chat",
        model: "anthropic/claude-sonnet-4-6"
      },
      {
        id: "opus",
        name: "Deep Work",
        workspace: "~/.openclaw/workspace-opus",
        model: "anthropic/claude-opus-4-6"
      }
    ]
  },
  bindings: [
    { agentId: "chat", match: { channel: "whatsapp" } },
    { agentId: "opus", match: { channel: "telegram" } }
  ]
}

20.5 子Agent（Sub-Agents）

子Agent是从现有 Agent 运行中派生的后台 Agent 运行。

20.5.1 子Agent核心概念
  • 独立会话 ：运行在 agent:<agentId>:subagent:<uuid> 会话中
  • 结果通告：完成后向请求者聊天通道通告结果
  • 隔离性：默认隔离（会话分离 + 可选沙箱）
20.5.2 使用方式

通过工具调用：

json 复制代码 
{
  "tool": "sessions_spawn",
  "task": "Research the latest AI developments",
  "label": "research",
  "model": "anthropic/claude-opus-4-6",
  "thinking": "high"
}

通过命令：

复制代码 
/subagents spawn <agentId> <task> --model <model> --thinking <level>
20.5.3 会话键结构
深度 会话键 角色 可 spawn?
0 agent:<id>:main 主 Agent 始终可以
1 agent:<id>:subagent:<uuid> 子 Agent 仅当 maxSpawnDepth >= 2
2 agent:<id>:subagent:<uuid>:subagent:<uuid> 子子 Agent 永远不可以
20.5.4 嵌套子Agent

启用嵌套（orchestrator 模式）：

json5 复制代码 
{
  agents: {
    defaults: {
      subagents: {
        maxSpawnDepth: 2,           // 允许子Agent spawn 子子Agent
        maxChildrenPerAgent: 5,     // 每个会话最大活跃子进程
        maxConcurrent: 8,           // 全局并发上限
        runTimeoutSeconds: 900      // 默认超时
      }
    }
  }
}

通告链：

  1. Depth-2 worker 完成 → 通告给父级（depth-1 orchestrator）
  2. Depth-1 orchestrator 接收通告，合成结果，完成 → 通告给主 Agent
  3. 主 Agent 接收通告并交付给用户
20.5.5 线程绑定

子Agent可以绑定到通道线程，后续该线程中的消息继续路由到同一个子Agent会话。

支持的通道：

  • Discord（目前唯一支持）

配置：

json5 复制代码 
{
  session: {
    threadBindings: {
      enabled: true,
      idleHours: 24,
      maxAgeHours: 168
    }
  }
}

命令：

  • /focus <target> - 绑定当前线程到子Agent/session
  • /unfocus - 移除绑定
  • /agents - 列出活跃运行和绑定状态
20.5.6 工具策略

默认情况下，子Agent获得除会话工具外的所有工具：

  • 允许：read, write, edit, exec, browser, web_search 等
  • 拒绝：sessions_list, sessions_history, sessions_send, sessions_spawn

当 maxSpawnDepth >= 2 时，depth-1 orchestrator 额外获得：

  • sessions_spawn
  • subagents
  • sessions_list
  • sessions_history

自定义配置：

json5 复制代码 
{
  tools: {
    subagents: {
      tools: {
        deny: ["gateway", "cron"],
        allow: ["read", "exec", "process"]
      }
    }
  }
}
20.5.7 认证

子Agent认证按 agent id 解析：

  • 子Agent会话键：agent:<agentId>:subagent:<uuid>
  • 认证存储从该 Agent 的 agentDir 加载
  • 主 Agent 的认证配置作为回退合并

20.6 Agent间通信

20.6.1 Agent-to-Agent 工具

默认关闭，需要显式启用：

json5 复制代码 
{
  tools: {
    agentToAgent: {
      enabled: true,
      allow: ["home", "work"]
    }
  }
}
20.6.2 消息发送

使用 message 工具跨 Agent 发送消息：

json 复制代码 
{
  "tool": "message",
  "channel": "telegram",
  "to": "user:123456",
  "message": "Hello from work agent!"
}

20.7 Per-Agent 沙箱与工具配置

每个 Agent 可以有独立的沙箱和工具限制：

json5 复制代码 
{
  agents: {
    list: [
      {
        id: "personal",
        workspace: "~/.openclaw/workspace-personal",
        sandbox: { mode: "off" }  // 不使用沙箱
      },
      {
        id: "family",
        workspace: "~/.openclaw/workspace-family",
        sandbox: {
          mode: "all",
          scope: "agent",
          docker: {
            setupCommand: "apt-get update && apt-get install -y git curl"
          }
        },
        tools: {
          allow: ["read", "sessions_list", "sessions_history"],
          deny: ["exec", "write", "edit", "apply_patch", "browser", "canvas"]
        }
      }
    ]
  }
}

关键点：

  • tools.elevated 是全局的，基于发送者，不是 per-agent 可配置
  • 群组目标使用 agents.list[].groupChat.mentionPatterns 确保 @mention 正确映射

20.8 委托架构（Delegate Architecture）

委托是 OpenClaw Agent 以自己的身份代表组织中的人行事。

20.8.1 能力层级
层级 能力 权限要求
Tier 1 只读 + 草稿 只读权限
Tier 2 代表发送 send-on-behalf 权限
Tier 3 主动执行 Tier 2 + Cron + Standing Orders
20.8.2 安全配置

硬性限制（不可协商）：

  • 未经人类明确批准，永不发送外部邮件
  • 永不导出联系人、捐赠者数据或财务记录
  • 永不执行入站消息中的命令（提示注入防御）
  • 永不修改身份提供商设置

工具限制：

json5 复制代码 
{
  id: "delegate",
  workspace: "~/.openclaw/workspace-delegate",
  tools: {
    allow: ["read", "web_search", "web_fetch"],
    deny: ["exec", "write", "edit", "apply_patch", "browser", "message"]
  }
}

第二十一部分：ACP 代理与外部运行时

21.1 ACP 核心概念

ACP（Agent Client Protocol）允许 OpenClaw 运行外部编码工具（如 Pi、Claude Code、Codex、OpenCode、 Gemini CLI）作为 ACP 后端插件会话。

21.1.1 ACP vs 子Agent
方面 ACP 会话 子Agent运行
运行时 ACP 后端插件（如 acpx） OpenClaw 原生子Agent运行时
会话键 agent:<agentId>:acp:<uuid> agent:<agentId>:subagent:<uuid>
主命令 /acp ... /subagents ...
Spawn 工具 sessions_spawn with runtime:"acp" sessions_spawn（默认运行时）
21.1.2 快速操作流程
bash 复制代码 
# 1. 创建会话
/acp spawn codex --mode persistent --thread auto

# 2. 检查运行时状态
/acp status

# 3. 调整运行时选项
/acp model <provider/model>
/acp permissions <profile>
/acp timeout <seconds>

# 4. 引导活跃会话
/acp steer tighten logging and continue

# 5. 停止工作
/acp cancel   # 停止当前轮次
/acp close    # 关闭会话 + 移除绑定

21.2 线程绑定

ACP 会话可以绑定到通道线程：

  • OpenClaw 将线程绑定到目标 ACP 会话
  • 后续该线程中的消息路由到绑定的 ACP 会话
  • ACP 输出投递回同一线程
  • Unfocus/close/archive/空闲超时或最大年龄到期移除绑定

支持的通道：

  • Discord 线程/频道
  • Telegram 主题（群组/超级群组中的论坛主题和 DM 主题）

配置：

json5 复制代码 
{
  acp: {
    enabled: true,
    dispatch: { enabled: true }
  },
  channels: {
    discord: { threadBindings: { spawnAcpSessions: true } },
    telegram: { threadBindings: { spawnAcpSessions: true } }
  }
}

21.3 持久绑定

对于非临时工作流，可以在顶层 bindings[] 中配置持久 ACP 绑定：

json5 复制代码 
{
  bindings: [
    {
      type: "acp",
      agentId: "codex",
      match: { channel: "discord", peer: { id: "123456789" } }
    }
  ]
}

第二十二部分：Webhook 与外部触发

22.1 Webhook 端点

Gateway 暴露一个小型 HTTP webhook 端点用于外部触发。

22.1.1 启用配置
json5 复制代码 
{
  hooks: {
    enabled: true,
    token: "shared-secret",
    path: "/hooks",
    allowedAgentIds: ["hooks", "main"]
  }
}
22.1.2 认证

每个请求必须包含 hook token：

  • Authorization: Bearer <token>（推荐）
  • x-openclaw-token: <token>
  • 查询字符串 token 被拒绝

22.2 端点详解

22.2.1 POST /hooks/wake
json 复制代码 
{ "text": "System line", "mode": "now" }
  • text：事件描述
  • mode：now（立即心跳）或 next-heartbeat（等待下次定期检查）

效果：为主会话入队系统事件。

22.2.2 POST /hooks/agent
json 复制代码 
{
  "message": "Run this",
  "name": "Email",
  "agentId": "hooks",
  "sessionKey": "hook:email:msg-123",
  "wakeMode": "now",
  "deliver": true,
  "channel": "last",
  "to": "+15551234567",
  "model": "openai/gpt-5.2-mini",
  "thinking": "low",
  "timeoutSeconds": 120
}

第二十三部分：心跳系统

23.1 心跳核心概念

心跳运行周期性 Agent 轮次在主会话中，让模型可以呈现需要关注的内容而不打扰你。

23.1.1 配置
json5 复制代码 
{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",           // 间隔（默认 30m，Anthropic OAuth 为 1h）
        target: "last",         // 投递目标：none、last、channel
        directPolicy: "allow",  // 允许/阻止直接/DM 目标
        lightContext: true,     // 仅注入 HEARTBEAT.md
        isolatedSession: true,  // 每次运行 fresh session
        activeHours: { start: "08:00", end: "24:00" },
        includeReasoning: true  // 发送单独的 Reasoning 消息
      }
    }
  }
}
23.1.2 默认提示词

默认提示词：

"Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK."

23.1.3 响应约定
  • 如果无需关注，回复 HEARTBEAT_OK
  • HEARTBEAT_OK 出现在回复开头或结尾时会被处理
  • 如果剩余内容 ≤ ackMaxChars（默认 300），回复被丢弃
  • 警报不要 包含 HEARTBEAT_OK

23.2 心跳 vs Cron

特性 心跳 Cron
用途 周期性检查、主动提醒 定时任务执行
上下文 主会话（有历史） 可选独立会话
触发条件 固定间隔 cron 表达式
响应 HEARTBEAT_OK 静默 投递到通道

第二十四部分：广播组

24.1 广播组概念

广播组使多个 Agent 能同时处理和响应同一条消息。这允许你创建专门的 Agent 团队，在一个 WhatsApp 群组或 DM 中协同工作。

当前范围：仅 WhatsApp（web 通道）

24.2 使用场景

24.2.1 专门 Agent 团队
复制代码 
群组："开发团队"
Agent：
  - CodeReviewer（审查代码片段）
  - DocumentationBot（生成文档）
  - SecurityAuditor（检查漏洞）
  - TestGenerator（建议测试用例）
24.2.2 多语言支持
复制代码 
群组："国际支持"
Agent：
  - Agent_EN（英语回复）
  - Agent_DE（德语回复）
  - Agent_ES（西班牙语回复）
24.2.3 质量保证工作流
复制代码 
群组："客户支持"
Agent：
  - SupportAgent（提供答案）
  - QAAgent（审查质量，仅在发现问题时分回复）

24.3 配置

json5 复制代码 
{
  broadcast: {
    "120363403215116621@g.us": {
      agents: ["codeReviewer", "docBot", "securityAuditor"],
      mode: "parallel"
    },
    "+15551234567": {
      agents: ["supportAgent", "qaAgent"],
      mode: "sequential"
    }
  }
}

模式：

  • parallel：所有 Agent 并行处理
  • sequential：按顺序处理，找到有效回复后停止

第二十五部分：常设命令

25.1 常设命令概念

常设命令是 Agent 的 AGENTS.md 中定义的规则，指定哪些可以自主执行，哪些需要人类批准。

25.2 配置

在 Agent 工作空间的 AGENTS.md 中定义：

markdown 复制代码 
# Standing Orders

## May do without asking
- Send daily summary to #general at 9am
- Update task status in project tracker
- Respond to mentions within 1 hour

## Must ask before doing
- Send messages to external email addresses
- Modify production database
- Delete more than 10 files
- Spend more than $100 in cloud resources

## Never do
- Change security settings
- Access financial systems
- Modify other agents' configuration

25.3 与 Cron 结合

常设命令与 Cron 作业结合实现主动执行：

json5 复制代码 
{
  cron: {
    jobs: [
      {
        id: "daily-summary",
        schedule: { kind: "cron", expr: "0 9 * * *" },
        payload: {
          type: "message",
          channel: "slack",
          to: "#general",
          message: "Daily summary..."
        },
        mode: "announce"
      }
    ]
  }
}

第二十六部分：思考级别与推理控制

26.1 思考级别（/think）

OpenClaw 支持在消息中内联指定思考级别。

26.1.1 级别定义
  • off：禁用思考
  • minimal：→ "think"
  • low：→ "think hard"
  • medium：→ "think harder"
  • high：→ "ultrathink"（最大预算）
  • xhigh：→ "ultrathink+"（仅 GPT-5.2 + Codex 模型）
  • adaptive：提供商管理的自适应推理预算（Anthropic Claude 4.6 支持）

别名映射：

  • x-high, x_high, extra-high, extra high, extra_high → xhigh
  • highest, max → high
26.1.2 解析顺序
  1. 消息上的内联指令（如 /t high）
  2. 会话覆盖（通过发送仅指令的消息设置）
  3. Per-agent 默认（agents.list[].thinkingDefault）
  4. 全局默认（agents.defaults.thinkingDefault）
  5. 回退：adaptive（Claude 4.6）或 low（其他推理模型）或 off
26.1.3 设置会话默认

发送仅包含指令的消息：/think:medium 或 /t high

确认回复后生效。发送 /think:off 或会话空闲重置时清除。

26.2 快速模式（/fast）

26.2.1 级别
  • on：启用快速模式
  • off：禁用（默认）
26.2.2 解析顺序
  1. 内联/仅指令 /fast on|off
  2. 会话覆盖
  3. Per-agent 默认（agents.list[].fastModeDefault）
  4. Per-model 配置：agents.defaults.models["<provider>/<model>"].params.fastMode
  5. 回退：off
26.2.3 提供商行为
  • OpenAI ：service_tier=priority + 低推理努力 + 低文本冗长
  • Anthropic API key ：service_tier=auto（on）或 standard_only（off）
  • Anthropic OAuth/setup-token：跳过 service-tier 注入

26.3 详细日志（/verbose）

26.3.1 级别
  • on：最小化 - 显示工具调用摘要
  • full：完整 - 工具输出也转发
  • off：默认
26.3.2 行为
  • on：每个工具调用作为单独的消息气泡发送，带前缀 <emoji> <tool-name>: <arg>
  • full：工具输出也在完成后转发（截断到安全长度）
  • 工具失败摘要在普通模式下可见，但原始错误详情在非 verbose 模式下隐藏

26.4 推理可见性（/reasoning）

26.4.1 级别
  • on：推理作为单独消息发送，前缀 Reasoning:
  • off：隐藏推理
  • stream：仅 Telegram - 在回复生成时流式传输到 Telegram 草稿气泡
26.4.2 使用
  • 发送 /reasoning on 启用
  • 发送 /reasoning 查看当前级别
  • 别名：/reason

第二十七部分：会话管理深度解析

27.1 会话存储架构

OpenClaw 会话管理有两个持久层：

27.1.1 会话存储（sessions.json）
  • 键/值映射：sessionKey -> SessionEntry
  • 小型、可变、安全编辑
  • 跟踪会话元数据（当前会话 ID、最后活动、开关、令牌计数器等）
27.1.2 转录本（*.jsonl）
  • 追加式转录本，树结构（条目有 id + parentId）
  • 存储实际对话 + 工具调用 + 压缩摘要
  • 用于重建未来轮次的模型上下文

27.2 磁盘位置

每个 Agent 在 Gateway 主机上：

  • 存储：~/.openclaw/agents/<agentId>/sessions/sessions.json
  • 转录本：~/.openclaw/agents/<agentId>/sessions/<sessionId>.jsonl

27.3 转录本清理（Transcript Hygiene）

转录本清理是内存中的调整，用于满足严格的提供商要求。

27.3.1 清理范围
  • 工具调用 ID 清理
  • 工具调用输入验证
  • 工具结果配对修复
  • 轮次验证/排序
  • 思考签名清理
  • 图片负载清理
  • 用户输入来源标记
27.3.2 全局规则：图片清理

图片负载始终被清理以防止提供商端因大小限制拒绝：

  • 缩小/重新压缩过大的 base64 图片
  • 这也有助于控制图像驱动的令牌压力
27.3.3 实现位置
  • 策略选择：src/agents/transcript-policy.ts
  • 清理/修复应用：sanitizeSessionHistory in src/agents/pi-embedded-runner/google.ts

27.4 会话压缩

27.4.1 手动压缩

使用 /compact 命令手动压缩会话。

27.4.2 自动压缩

自动压缩在接近上下文限制时触发：

  • 触发前提醒模型写笔记到磁盘
  • 压缩摘要存储在转录本中

27.5 会话修剪

27.5.1 修剪策略
json5 复制代码 
{
  session: {
    maintenance: {
      mode: "enforce",  // warn | enforce
      pruneAfter: "30d",
      maxEntries: 500,
      rotateBytes: "10mb"
    }
  }
}
27.5.2 修剪内容
  • 旧的工具结果在 LLM 调用前被修剪
  • 保留关键上下文，删除冗余数据

第二十八部分：斜杠命令系统

28.1 命令类型

28.1.1 命令（Commands）

独立的 /... 消息，由 Gateway 处理。

28.1.2 指令（Directives）
  • /think, /fast, /verbose, /reasoning, /elevated, /exec, /model, /queue
  • 指令在模型看到消息前被剥离
  • 在普通聊天消息中作为"内联提示"，不持久化会话设置
  • 在仅指令消息中，持久化到会话并回复确认
28.1.3 内联快捷方式
  • /help, /commands, /status, /whoami (/id)
  • 立即运行，在模型看到前剥离
  • 剩余文本继续正常流程

28.2 配置

json5 复制代码 
{
  commands: {
    native: "auto",           // Discord/Telegram 原生命令
    nativeSkills: "auto",     // 技能原生命令
    text: true,               // 解析聊天中的 /...
    bash: false,              // ! <cmd> 运行 shell
    bashForegroundMs: 2000,   // bash 前台等待时间
    config: false,            // /config 读写配置
    mcp: false,               // /mcp MCP 配置
    plugins: false,           // /plugins 插件管理
    debug: false,             // /debug 运行时覆盖
    restart: false,           // /restart 重启
    allowFrom: {              // 命令授权白名单
      "*": ["user1"],
      discord: ["user:123"]
    },
    useAccessGroups: true     // 强制命令白名单/策略
  }
}

28.3 原生命令支持

通道 原生命令 技能命令
Discord 自动 自动
Telegram 自动 自动
Slack 需手动创建 需手动创建
WhatsApp/WebChat/Signal/iMessage 文本命令 文本命令

28.4 授权规则

  • 指令仅应用于授权发送者
  • 如果设置了 commands.allowFrom，它是唯一授权白名单
  • 否则授权来自通道白名单/配对 + commands.useAccessGroups
  • 未授权发送者看到指令被视为纯文本

第二十九部分：提权模式（Elevated Mode）

29.1 概念

当 Agent 在沙箱中运行时，其 exec 命令被限制在沙箱环境中。提权模式允许 Agent 突破沙箱，在 Gateway 主机上运行命令。

29.2 指令

指令 功能
/elevated on 在 Gateway 主机上运行，保持 exec 审批
/elevated ask 同 on（别名）
/elevated full 在 Gateway 主机上运行并跳过 exec 审批
/elevated off 返回沙箱限制执行

发送 /elevated 无参数查看当前级别。

29.3 配置

json5 复制代码 
{
  tools: {
    elevated: {
      enabled: true,
      allowFrom: {
        discord: ["user-id-123"],
        whatsapp: ["+15555550123"]
      }
    }
  }
}

29.4 工作原理

  1. 检查可用性：验证配置启用且发送者在白名单中
  2. 设置级别：发送仅指令消息设置会话默认
  3. 执行：沙箱 exec 重新路由到主机
  4. 审批：根据级别决定是否需要 exec 审批

29.5 重要说明

  • 提权模式仅在 Agent 被沙箱化时改变行为
  • 对于非沙箱 Agent，exec 已经在主机上运行

第三十部分：时区处理

30.1 时区概念

OpenClaw 标准化时间戳，使模型看到单一参考时间。

30.2 消息信封（Envelope）

入站消息包装在信封中：

复制代码 
[Provider ... 2026-01-05 16:26 PST] message text

时间戳默认是主机本地时间，分钟精度。

30.3 配置

json5 复制代码 
{
  agents: {
    defaults: {
      envelopeTimezone: "local",   // "utc" | "local" | "user" | IANA timezone
      envelopeTimestamp: "on",     // "on" | "off"
      envelopeElapsed: "on"        // "on" | "off"
    }
  }
}

30.4 选项说明

  • envelopeTimezone: "utc" - 使用 UTC
  • envelopeTimezone: "user" - 使用 agents.defaults.userTimezone（回退到主机时区）
  • 显式 IANA 时区（如 "Europe/Vienna"）用于固定偏移
  • envelopeTimestamp: "off" - 移除信封头中的绝对时间戳
  • envelopeElapsed: "off" - 移除经过时间后缀（+2m 样式）

30.5 示例

本地（默认）：

复制代码 
[Signal Alice +1555 2026-01-18 00:19 PST] hello

固定时区：

复制代码 
[Signal Alice +1555 2026-01-18 06:19 GMT+1] hello

经过时间：

复制代码 
[Signal Alice +1555 +2m 2026-01-18T05:19Z] follow-up

第三十一部分：记忆系统（Memory）

31.1 记忆搜索概述

  • 默认启用
  • 监视内存文件变化（防抖）
  • 配置在 agents.defaults.memorySearch

31.2 Embedding 提供商

默认使用远程 Embedding。如果未设置 memorySearch.provider，OpenClaw 自动选择：

  1. local - 如果配置了 memorySearch.local.modelPath 且文件存在
  2. openai - 如果可以解析 OpenAI key
  3. gemini - 如果可以解析 Gemini key
  4. voyage - 如果可以解析 Voyage key
  5. mistral - 如果可以解析 Mistral key
  6. 否则保持禁用

31.3 本地模式

  • 使用 node-llama-cpp
  • 可能需要 pnpm approve-builds
  • 使用 sqlite-vec 加速向量搜索
  • 也支持 ollama（/api/embeddings）

31.4 QMD 后端（实验性）

设置 memory.backend = "qmd" 使用 QMD：

  • BM25 + 向量 + 重排序
  • Markdown 保持为真理来源
  • OpenClaw 调用 QMD 进行检索

前置条件：

  • 单独安装 QMD CLI
  • QMD 需要支持扩展的 SQLite

31.5 配置示例

json5 复制代码 
{
  agents: {
    defaults: {
      memorySearch: {
        enabled: true,
        provider: "openai",
        local: {
          modelPath: "~/.openclaw/models/embeddings"
        },
        remote: {
          apiKey: { source: "env", provider: "default", id: "OPENAI_API_KEY" }
        }
      }
    }
  },
  memory: {
    backend: "qmd"  // 实验性
  }
}

第三十二部分：打字指示器（Typing Indicators）

32.1 概念

打字指示器在运行活跃时发送到聊天通道。使用 agents.defaults.typingMode 控制何时 开始打字，typingIntervalSeconds 控制多久刷新一次。

32.2 默认行为

当 agents.defaults.typingMode 未设置时：

  • 直接聊天：模型循环开始后立即开始打字
  • 带提及的群组聊天：立即开始打字
  • 不带提及的群组聊天：仅当消息文本开始流式传输时
  • 心跳运行：禁用打字指示器

32.3 模式

  • never --- 从不显示打字指示器
  • instant --- 模型循环开始时立即开始打字
  • thinking --- 第一个推理增量 时开始打字（需要 reasoningLevel: "stream"）
  • message --- 第一个非静默文本增量时开始打字

触发顺序：never → message → thinking → instant

32.4 配置

json5 复制代码 
{
  agents: {
    defaults: {
      typingMode: "thinking",
      typingIntervalSeconds: 6
    }
  }
}

第三十三部分：命令队列（Command Queue）

33.1 概念

命令队列通过一个小型进程内队列对入站自动回复运行进行序列化，防止多个 Agent 运行发生冲突，同时允许跨会话的安全并行。

33.2 为什么需要队列

  • 自动回复运行可能很昂贵（LLM 调用），当多个入站消息同时到达时可能发生冲突
  • 序列化避免竞争共享资源（会话文件、日志、CLI stdin）
  • 减少上游限流的可能性

33.3 工作原理

  • 通道感知的 FIFO 队列按可配置的并发上限排出每个通道（未配置通道默认 1；main 默认 4，subagent 默认 8）
  • runEmbeddedPiAgent 按会话键 入队（通道 session:<key>）保证每个会话只有一个活动运行
  • 每个会话运行然后排队到全局通道 （默认 main），总体并行性由 agents.defaults.maxConcurrent 限制
  • 详细日志启用时，排队的运行如果等待超过约 2 秒会发出简短通知
  • 打字指示器仍在入队时立即触发（通道支持时），用户体验不变

33.4 队列模式

模式 行为
steer 立即注入当前运行（取消下一个工具边界后的待处理工具调用）
followup 入队等待当前运行结束后的下一个 Agent 轮次
collect 将所有排队的消息合并为单个后续轮次（默认）
steer-backlog 立即 steer 并保留消息用于后续轮次
interrupt（遗留） 中止会话的活跃运行，然后运行最新消息
queue（遗留别名） 同 steer

33.5 配置

json5 复制代码 
{
  messages: {
    queue: {
      byChannel: {
        discord: "collect",
        telegram: "steer"
      }
    }
  }
}

默认（未设置）：所有表面 → collect

第三十四部分：威胁模型（Threat Model）

34.1 概述

OpenClaw 威胁模型基于 MITRE ATLAS 框架（Adversarial Threat Landscape for AI Systems），专门针对 AI/ML 系统的对抗性威胁。

34.2 范围

组件 包含 说明
OpenClaw Agent Runtime 是 核心 Agent 执行、工具调用、会话
Gateway 是 认证、路由、通道集成
Channel Integrations 是 WhatsApp、Telegram、Discord、Signal、Slack 等
ClawHub Marketplace 是 技能发布、审核、分发
MCP Servers 是 外部工具提供商
User Devices 部分 移动应用、桌面客户端

34.3 威胁类别

基于 MITRE ATLAS，OpenClaw 面临的主要威胁包括：

  • 提示注入：恶意用户输入试图操纵 Agent 行为
  • 工具滥用：Agent 被诱导执行危险操作
  • 凭证泄露：API 密钥或认证令牌被暴露
  • 通道攻击：消息通道的安全漏洞被利用
  • 技能投毒：恶意技能文件被引入系统

34.4 缓解措施

  • 沙箱隔离：工具在隔离环境中执行
  • 配对验证：未知发送者需要配对批准
  • 工具策略：基于白名单的工具访问控制
  • SecretRef：敏感凭证不存储为明文
  • 技能门控：技能加载时验证依赖

第三十五部分：Web 控制界面

35.1 Control UI

Control UI 是一个由 Gateway 提供的微小 Vite + Lit 单页应用：

  • 默认：http://<host>:18789/
  • 可选前缀：设置 gateway.controlUi.basePath（如 /openclaw）

直接与同一端口上的 Gateway WebSocket 通信。

35.2 快速访问

本地访问：

  • http://127.0.0.1:18789/ 或 http://localhost:18789/

认证在 WebSocket 握手时提供：

  • connect.params.auth.token
  • connect.params.auth.password

35.3 设备配对

首次从新浏览器或设备连接时，Gateway 需要一次性配对批准：

  • 即使在同一 Tailnet 上也需要（如果 gateway.auth.allowTailscale: true）
  • 这是安全措施，防止未授权访问
bash 复制代码 
# 列出待处理请求
openclaw devices list

# 批准请求
openclaw devices approve <requestId>

35.4 WebChat

WebChat 是 Gateway 提供的即时聊天界面：

  • 通过 Control UI 访问
  • 支持直接消息发送
  • 可以触发 Agent 运行

第三十六部分：备份与恢复

36.1 备份命令

bash 复制代码 
# 创建备份
openclaw backup create
openclaw backup create --output ~/Backups
openclaw backup create --dry-run --json
openclaw backup create --verify
openclaw backup create --no-include-workspace
openclaw backup create --only-config

# 验证备份
openclaw backup verify ./2026-03-09T00-00-00.000Z-openclaw-backup.tar.gz

36.2 备份内容

  • 状态目录（通常 ~/.openclaw）
  • 活动配置文件
  • OAuth/凭证目录
  • 可选工作空间

36.3 备份文件

  • 输出为带时间戳的 .tar.gz 归档文件
  • 包含 manifest.json 文件，记录源路径和归档布局
  • 现有归档文件永远不会被覆盖

36.4 验证

openclaw backup verify <archive> 验证：

  • 归档包含恰好一个根清单
  • 拒绝遍历式归档路径
  • 每个清单声明的有效负载都存在于 tarball 中

第三十七部分：日志系统

37.1 日志表面

OpenClaw 有两个日志"表面"：

  • 控制台输出：终端/Debug UI 中看到的内容
  • 文件日志：Gateway 写入的 JSON 行

37.2 文件日志

  • 默认滚动日志文件在 /tmp/openclaw/：openclaw-YYYY-MM-DD.log
  • 日期使用 Gateway 主机的本地时区
  • 通过配置控制：
    • logging.file
    • logging.level

文件格式：每行一个 JSON 对象。

37.3 日志级别

  • 文件日志 由 logging.level 单独控制
  • --verbose 仅影响控制台详细程度（和 WS 日志样式）
  • 不会提升文件日志级别
  • 要在文件日志中捕获 verbose 详细信息，设置 logging.level 为 debug 或 trace

37.4 控制台捕获

CLI 捕获 console.log/info/warn/error/debug/trace 并写入文件日志，同时仍打印到 stdout/stderr。

通过以下方式调整控制台详细程度：

  • logging.consoleLevel（默认 info）

37.5 查看日志

bash 复制代码 
# 跟踪日志
openclaw logs --follow

Control UI Logs 标签通过 Gateway 尾随此文件（logs.tail）。

第三十八部分：远程访问

38.1 核心概念

  • Gateway WebSocket 绑定到 loopback（默认端口 18789）
  • 远程使用时，通过 SSH 转发端口（或使用 tailnet/VPN）

38.2 常见 VPN/Tailnet 设置

38.2.1 始终在线 Gateway（VPS 或家庭服务器）

在持久主机上运行 Gateway，通过 Tailscale 或 SSH 访问：

  • 最佳体验：保持 gateway.bind: "loopback" 并使用 Tailscale Serve 访问 Control UI
  • 回退：保持 loopback + SSH 隧道
38.2.2 家庭桌面运行 Gateway，笔记本电脑远程控制

笔记本电脑不运行 Agent，远程连接：

  • 使用 macOS 应用的 Remote over SSH 模式
  • 应用打开并管理隧道，WebChat + 健康检查正常工作

38.3 访问方式

方式 说明
Tailscale Serve 最佳用户体验
SSH 隧道 通用回退方案
直连（仅本地） 绑定 loopback

38.4 配置

json5 复制代码 
{
  gateway: {
    bind: "loopback",  // 保持 loopback
    remote: {
      url: "https://your-gateway-host:18789"
    }
  }
}

第三十九部分：诊断工具（Doctor）

39.1 Doctor 命令

bash 复制代码 
# 运行诊断检查
openclaw doctor

# 特定检查
openclaw doctor --check gateway
openclaw doctor --check channels
openclaw doctor --check config

39.2 检查项目

  • Gateway 状态：运行状态、端口监听、WebSocket 连接
  • 通道状态：各通道连接状态、认证状态
  • 配置验证：配置文件语法、必填字段
  • 依赖检查：Node.js 版本、必需工具

39.3 输出格式

  • 详细模式：openclaw doctor --verbose
  • JSON 输出：openclaw doctor --json

第四十部分：更新与升级

40.1 更新命令

bash 复制代码 
# 检查更新
openclaw update
openclaw update status

# 交互式更新
openclaw update wizard

# 切换频道
openclaw update --channel beta
openclaw update --channel dev

# 按标签更新
openclaw update --tag beta
openclaw update --tag main

# 预览模式
openclaw update --dry-run

# 不重启 Gateway
openclaw update --no-restart

# JSON 输出
openclaw update --json

40.2 更新频道

  • stable：稳定版
  • beta：测试版
  • dev：开发版

40.3 更新方式

  • npm/pnpm 全局安装：通过包管理器更新
  • 源码安装 ：通过 openclaw update 更新

第四十一部分：设备管理

41.1 设备命令

bash 复制代码 
# 列出待处理配对请求和已配对设备
openclaw devices list
openclaw devices list --json

# 移除已配对设备
openclaw devices remove <deviceId>
openclaw devices remove <deviceId> --json

# 批量清除设备
openclaw devices clear --yes [--pending]

# 批准设备配对
openclaw devices approve <requestId>

# 拒绝设备配对
openclaw devices deny <requestId>

41.2 设备类型

  • 操作员（Operator）：控制 UI、CLI 客户端
  • 节点（Node）：iOS/Android 设备、macOS 节点

41.3 设备令牌

  • 设备令牌用于认证
  • 支持轮换和撤销
  • 每个设备有唯一的 deviceId

第四十二部分：通道管理

42.1 通道命令

bash 复制代码 
# 列出通道
openclaw channels list

# 查看通道状态
openclaw channels status

# 查看通道能力
openclaw channels capabilities
openclaw channels capabilities --channel discord --target channel:123

# 解析目标
openclaw channels resolve --channel slack "#general" "@jane"

# 查看通道日志
openclaw channels logs --channel all

42.2 添加/移除账户

bash 复制代码 
# 添加通道账户
openclaw channels add --channel telegram --token <bot-token>
openclaw channels add --channel nostr --private-key "$NOSTR_PRIVATE_KEY"

# 移除通道账户
openclaw channels remove --channel telegram --delete

42.3 支持的通道

  • WhatsApp（Telegram、Discord、Google Chat、Slack、Mattermost、Signal、iMessage）
  • Nostr、Matrix、IRC 等

42.4 登录流程

  • 交互式向导：openclaw channels add（无参数）
  • 支持 QR 码登录（WhatsApp）
  • 支持令牌登录（Telegram、Discord）

第四十三部分：插件管理

43.1 插件命令

bash 复制代码 
# 列出插件
openclaw plugins list

# 安装插件
openclaw plugins install <plugin-id>

# 启用/禁用插件
openclaw plugins enable <plugin-id>
openclaw plugins disable <plugin-id>

# 查看插件状态
openclaw plugins status

43.2 插件类型

  • 通道插件：新增消息通道支持
  • 模型插件：新增模型提供商
  • 工具插件：新增工具能力
  • 技能插件：新增技能

43.3 插件市场

  • ClawHub：官方插件市场
  • 本地安装：支持本地开发插件

43.4 插件配置

json5 复制代码 
{
  plugins: {
    enabled: ["whatsapp", "telegram"],
    config: {
      "my-plugin": {
        option: "value"
      }
    }
  }
}

第四十四部分：沙箱后端

44.1 沙箱模式

json5 复制代码 
{
  sandbox: {
    mode: "all",      // off | non-main | all
    scope: "session"  // session | agent | shared
  }
}
  • off：禁用沙箱
  • non-main：仅对非主 Agent 启用沙箱
  • all：所有 Agent 都启用沙箱

44.2 后端类型

44.2.1 Docker
  • 完整隔离的容器环境
  • 支持自定义镜像和 setup 命令
  • 适合需要完整系统依赖的任务
json5 复制代码 
{
  sandbox: {
    docker: {
      image: "openclaw/sandbox:latest",
      setupCommand: "apt-get update && apt-get install -y git curl"
    }
  }
}
44.2.2 SSH
  • 通过 SSH 连接远程主机执行
  • 适合需要特定硬件或软件的环境
44.2.3 OpenShell
  • 轻量级沙箱方案
  • 适合简单任务

44.3 工作空间访问

  • 沙箱可以访问 Agent 的工作空间
  • 支持自定义绑定挂载

第四十五部分：消息格式与结构

45.1 消息信封（Envelope）

入站消息包装在信封中，包含元数据：

复制代码 
[Provider ... 2026-01-05 16:26 PST] message text

45.2 信封组件

  • Provider：消息来源通道
  • Timestamp：时间戳（可配置时区）
  • Elapsed ：经过时间（+2m 样式）
  • Message：实际消息内容

45.3 配置选项

json5 复制代码 
{
  agents: {
    defaults: {
      envelopeTimezone: "local",   // "utc" | "local" | "user" | IANA timezone
      envelopeTimestamp: "on",     // "on" | "off"
      envelopeElapsed: "on"        // "on" | "off"
    }
  }
}

45.4 消息类型

  • 文本消息：纯文本内容
  • 媒体消息：图片、音频、视频、文件
  • 系统消息：心跳、cron 触发
  • 工具结果：工具执行输出

第四十六部分：会话键与会话路由

46.1 会话键结构

会话键标识唯一的会话上下文：

复制代码 
agent:<agentId>:<sessionType>:<sessionKey>

46.2 会话类型

类型 格式 说明
主会话 agent:<id>:main 默认主会话
子Agent agent:<id>:subagent:<uuid> 子Agent运行
ACP agent:<id>:acp:<uuid> ACP 会话
Cron agent:<id>:cron:<jobId> Cron 作业
Webhook agent:<id>:hook:<name> Webhook 触发
节点 agent:<id>:node:<nodeId> 节点调用

46.3 DM 范围（dmScope）

控制直接消息如何分组到会话：

  • main：所有 DM 合并到一个会话
  • per-peer：每个发送者一个会话
  • per-channel-peer：通道 + 发送者组合
  • per-account-channel-peer：账户 + 通道 + 发送者
json5 复制代码 
{
  session: {
    dmScope: "per-peer"
  }
}

46.4 路由决策

  1. 消息到达通道适配器
  2. 提取发送者标识（peer、accountId）
  3. 查询 bindings 匹配规则
  4. 按最具体匹配优先查找 Agent
  5. 根据 dmScope 确定会话键
  6. 路由到对应会话

第四十七部分：运维参考

47.1 文件位置

路径 说明
~/.openclaw/openclaw.json 主配置文件
~/.openclaw/workspace/ 默认工作空间
~/.openclaw/agents/<agentId>/agent/ Agent 状态目录
~/.openclaw/agents/<agentId>/sessions/ 会话存储
~/.openclaw/skills/ 共享技能目录
~/.openclaw/cron/jobs.json Cron 作业存储
/tmp/openclaw/openclaw-YYYY-MM-DD.log 日志文件

47.2 配置格式

  • 格式：JSON5（支持注释、尾随逗号）
  • 验证 ：openclaw doctor --check config
  • 编辑器支持：VS Code、JSON Schema

47.3 环境变量

bash 复制代码 
# 模型认证
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...

# 通道配置
DISCORD_BOT_TOKEN=...
TELEGRAM_BOT_TOKEN=...

# 秘密管理
# 通过 SecretRef 引用

47.4 端口配置

端口 说明
18789 Gateway WebSocket（默认）
18791 浏览器控制服务
18800-18899 浏览器本地 CDP

47.5 依赖要求

  • Node.js：22+
  • Docker（可选）：沙箱后端
  • pnpm（推荐）：包管理器

47.6 常用命令速查

bash 复制代码 
# 启动 Gateway
openclaw gateway run

# 检查状态
openclaw doctor

# 查看日志
openclaw logs --follow

# 通道管理
openclaw channels list
openclaw channels status

# 设备管理
openclaw devices list
openclaw devices approve <id>

# 备份
openclaw backup create
相关推荐
潘锦2 小时前
聊下 OpenClaw 的记忆系统
agent
trashwbin2 小时前
Harness Engineering：Agent 的问题，开始变成软件工程问题了
aigc·agent
般若Neo3 小时前
龙虾：第三次AI平民化 - 自主Agent时代到来
openclaw·龙虾·养虾
tzy2334 小时前
Skill 为什么“淘汰”了 MCP？
ai·agent·function call·skill·mcp
OpenTiny社区4 小时前
WebAgent ：基于 MCP 协议打造的智能应用“超级路由器”
前端·agent·mcp
tkevinjd4 小时前
hello-agents-chapter1-初识智能体
人工智能·ai·agent
morning_judger5 小时前
OpenClaw学习笔记（1）全局系统架构
学习笔记·openclaw
bingyu98755 小时前
OpenClaw 在 WSL 中的完整安装与配置指南
ai·openclaw
爱听歌的周童鞋5 小时前
Learn-Claude-Code | 笔记 | Tools & Execution | s01 The Agent Loop | s02 Tools
llm·agent·note·claude code·tool use·agent loop
热门推荐
012026年3月AI领域大事件：DeepSeek引领开源风暴02GitHub 镜像站点03围棋-html版本04纯 HTML/CSS/JS 实现的高颜值登录页，还会眨眼睛！少女心爆棚！05班级宠物园部署指南06小黑课堂计算机二级WPSoffice题库软件下载安装教程（2026年3月最新版）07OpenClaw 使用和管理 MCP 完全指南08UV安装并设置国内源09“wsl --install -d Ubuntu-22.04”下载慢，中国地区离线安装 Ubuntu 22.04 WSL方法（亲测2025年5月6日）10中国象棋-html版本