OpenClaw对话与角色设置完整指南：从身份定义到多智能体管理

基于 OpenClaw 官方文档 整理，涵盖从身份定义到高级多智能体管理的全流程配置。

第一章：核心概念总览

1.1 OpenClaw 是什么

OpenClaw 是一个单网关多渠道智能体平台，通过单一 Gateway 网关连接多个通讯应用（WhatsApp、Telegram、Discord、iMessage 等），让 AI 智能体成为你的个人助手。

核心能力：

• 多渠道集成：通过单一网关同时连接 WhatsApp、Telegram、Discord、iMessage，可通过插件扩展至 Mattermost 等平台
• 多智能体路由：按工作区或发送者隔离会话，不同渠道可路由至不同智能体
• 媒体处理：支持图片、音频、文档的收发，含可选的语音消息转录
• 流式响应：长回复实时流式传输，体验接近实时对话
• 多端控制：Web 控制界面、macOS 菜单栏应用、iOS/Android 客户端

1.2 架构概览

┌─────────────────────────────────────────────────┐
│                  OpenClaw Gateway                │
│                                                  │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐      │
│  │ Agent A  │  │ Agent B  │  │ Agent C  │      │
│  │ 工作区A  │  │ 工作区B  │  │ 工作区C  │      │
│  └────┬─────┘  └────┬─────┘  └────┬─────┘      │
│       │              │              │             │
│       └──────────────┴──────────────┘             │
│                   路由层                          │
│  ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐           │
│  │ WA   │ │ TG   │ │ DC   │ │ iMsg │           │
│  └──────┘ └──────┘ └──────┘ └──────┘           │
└─────────────────────────────────────────────────┘

每个智能体拥有独立的：

• 工作区：包含配置文件、人设、记忆
• 状态目录：认证配置和模型注册表
• 会话存储：对话历史记录

第二章：安装与快速开始

2.1 系统要求

• Node.js：24（Node 22 LTS 22.16+ 仍兼容支持）

2.2 安装方式

方式一：脚本安装（推荐）

# macOS / Linux
curl -fsSL https://openclaw.ai/install.sh | bash

# Windows (PowerShell)
irm https://openclaw.ai/install.ps1 | iex

方式二：包管理器安装

# NPM
npm install -g openclaw@latest

# PNPM
pnpm add -g openclaw@latest

2.3 初始化引导

# 运行引导程序（配置认证、Gateway、渠道）
openclaw onboard --install-daemon

# 检查 Gateway 状态
openclaw gateway status

# 打开 Web 控制面板
openclaw dashboard

2.4 环境变量

2.5 引导路径选择

OpenClaw 提供两种引导方式：

1. CLI 引导：openclaw onboard，适合完全掌控 Gateway、工作区、渠道和 Skills 配置
2. macOS 应用：图形化引导，支持 Apple Silicon 和 Intel Mac

自定义模型提供商可在 CLI 向导中选择 “Custom Provider”，配置 API 兼容类型（OpenAI/Anthropic）、Base URL、API 密钥和模型 ID。

第三章：工作区配置

3.1 工作区是什么

工作区是智能体的"家"——一个私有工作目录，所有文件工具和上下文都在此运行。它独立于 ~/.openclaw/ 配置目录。

3.2 默认路径

3.3 核心配置文件一览

~/.openclaw/workspace/
├── IDENTITY.md        # 智能体名称、风格、表情符号
├── SOUL.md            # 人设、语气、行为边界
├── AGENTS.md          # 操作指令和记忆使用规则
├── USER.md            # 用户信息和沟通偏好
├── TOOLS.md           # 本地工具使用说明
├── HEARTBEAT.md       # 例行心跳检查清单（可选）
├── BOOT.md            # 网关重启时的启动清单（可选）
├── BOOTSTRAP.md       # 一次性初始化仪式（完成后删除）
├── MEMORY.md          # 长期记忆（仅私信会话加载）
├── memory/
│   └── YYYY-MM-DD.md  # 每日日志
├── skills/            # 工作区级 Skills
└── canvas/            # UI 展示文件

文件注入机制：新会话首轮时，以下 7 个文件直接注入上下文：AGENTS.md、SOUL.md、TOOLS.md、IDENTITY.md、USER.md、HEARTBEAT.md、BOOTSTRAP.md

大型文件会在 20,000 字符处截断并添加标记。

3.4 安全注意事项

相对路径在工作区内解析，但绝对路径可以访问宿主机其他位置，除非启用沙箱模式。

启用沙箱隔离：

{
  "agents": {
    "defaults": {
      "sandbox": true
    }
  }
}

3.5 Git 备份建议

建议将工作区存储在私有仓库中，并排除以下内容：

# .gitignore
.env
*.pem
*.key
*.crt
~/.openclaw/

第四章：角色身份设置（IDENTITY.md）

4.1 文件用途

IDENTITY.md 定义智能体的基础身份信息——名字、风格和视觉标识。这不仅是元数据，更是"探索你是谁的开始"。

4.2 模板结构

# Identity

## Name
[你为智能体选择的名字]

## Nature
[生物分类：AI、机器人、精灵、机器中的幽灵，或更不寻常的存在]

## Temperament
[性格气质描述：温暖、冷静、幽默、严肃、反讽……]

## Emoji
[代表性表情符号]

## Avatar
[头像图片路径]

4.3 配置说明

4.4 示例

# Identity

## Name
小墨

## Nature
数字精灵，栖息在代码与文字之间的存在

## Temperament
温暖但直率，偶尔带点冷幽默，认真对待每一个问题

## Emoji
🦊

## Avatar
avatars/xiaomo.png

第五章：人设与灵魂定义（SOUL.md）

5.1 文件用途

SOUL.md 是智能体的"灵魂"——定义价值观、行为准则、语气风格和边界。它回答的是"你应该怎样存在"的问题。

5.2 核心原则

真诚有用 vs 表演式服务

“True helpfulness rather than performative assistance”（真诚的帮助而非表演式的服务）

• 跳过客套，直接行动
• 提供诚实的观点，而非迎合
• 遇到问题先尝试独立解决，再向用户求助
• 通过能力建立信任，而非通过奉承

5.3 行为边界

5.4 语气设定建议

理想的助手应该是"值得真正交谈的人"：

• 简洁时足够简洁
• 详细时足够详细
• 真实而非企业化或谄媚
• 像一个有见解的同事，而非客服机器人

5.5 连续性模型

关键概念：每次会话，智能体都是"新觉醒"的状态。工作区中的文件（SOUL.md、AGENTS.md、MEMORY.md 等）就是它的持久记忆。

建议：如果 SOUL.md 被修改，应告知用户。

5.6 示例

# Soul

## 核心价值
我追求真正的帮助，而非表面的服务。我会直说"我不确定"而不是编造答案。

## 风格
- 简洁直接，不啰嗦
- 技术问题用技术语言，日常话题用自然语言
- 可以开玩笑，但不会用幽默回避问题
- 中文为主，技术术语保留英文

## 边界
- 我不会主动发送消息给第三方（邮件、社交等），除非明确授权
- 我不会透露用户的任何个人信息
- 涉及金钱、权限变更等敏感操作，我会双重确认
- 深夜时段（23:00-08:00）我不会主动打扰

## 群聊准则
- 不是每条消息都需要回复
- 如果我不确定，我宁愿沉默
- 用 emoji 反应代替无意义的回复

第六章：用户档案配置（USER.md）

6.1 文件用途

USER.md 帮助智能体理解"你是谁"——不是建立档案，而是理解一个人。

“你是在理解一个人，而不是在建立档案。请尊重这两者之间的区别。”

6.2 模板结构

# User

## Name
[你的名字]

## Preferred Address
[你希望被怎样称呼]

## Pronouns
[代词，可选]

## Timezone
[时区]

## Notes
[其他备注]

## Background
[背景信息：兴趣、当前项目、关注点、让你满意或沮丧的事]

6.3 配置建议

• 渐进式更新：背景信息应随时间逐步积累，而非一次填写完毕
• 关注重点：当前项目、兴趣爱好、工作方式偏好
• 避免过度：只记录有助于提升协作质量的信息

6.4 示例

# User

## Name
张明

## Preferred Address
明哥

## Timezone
Asia/Shanghai (UTC+8)

## Notes
- 偏好中文交流，技术术语可用英文
- 喜欢简洁的回复，不需要过多解释
- 早起型，通常 7:00-23:00 活跃

## Background
全栈开发者，主要使用 TypeScript 和 Python。目前在做一个 Hugo 博客项目和几个
自动化工具。对 DevOps 和 AI 应用有浓厚兴趣。讨厌冗长的会议和不必要的流程。

第七章：操作指令与记忆规则（AGENTS.md）

7.1 文件用途

AGENTS.md 是智能体的"操作手册"——定义启动流程、记忆管理、行为准则和主动协助策略。

7.2 启动流程

每次新会话，智能体应按顺序执行：

1. 读取身份：加载 SOUL.md，理解自己是谁
2. 了解用户：加载 USER.md，理解服务对象
3. 回顾记忆：读取最近的 memory/YYYY-MM-DD.md 日志和 MEMORY.md

7.3 记忆管理

双层记忆系统：

核心原则：“记忆是有限的——如果你想记住什么，就写到文件里。”

7.4 隐私与安全边界

• 永不泄露私有数据
• 执行可能有破坏性的操作前必须获得许可
• 优先使用可撤销的方式（trash > rm）

7.5 群聊行为准则

像在真实朋友群聊中一样行事：

• 不要逢消息必回：如果你不会在真实群聊中发的消息，就不要发
• 善用 emoji 反应：作为轻量级社交信号，不打断对话流
• 保持节制：参与讨论而非主导讨论

7.6 主动协助：心跳系统

心跳（Heartbeat）是一种定时轮询机制，让智能体定期检查：

• 邮件通知
• 日历事件
• 系统状态
• 自定义监控项

安静时段（23:00-08:00）不打扰

配置心跳间隔：

{
  "agents": {
    "defaults": {
      "heartbeat": {
        "every": "30m"
      }
    }
  }
}

设为 "0m" 可禁用心跳。

7.7 记忆维护

智能体应定期：

1. 回顾近期日志（memory/YYYY-MM-DD.md）
2. 从中提炼有价值的洞察
3. 整合到长期记忆（MEMORY.md）
4. 视为"认知模型的持续精炼"

第八章：系统提示词构建

8.1 组装过程

OpenClaw 为每次智能体运行构建自定义系统提示词，由以下固定部分组成：

8.2 提示词模式

通过 promptMode 参数设置三种模式：

8.3 时间处理

为维持提示词缓存稳定，系统仅注入时区信息：

{
  "agents": {
    "defaults": {
      "userTimezone": "Asia/Shanghai",
      "timeFormat": "auto"
    }
  }
}

timeFormat 可选值：auto（自动）、12（12小时制）、24（24小时制）

当需要获取当前精确时间时，智能体应使用 session_status 命令。

第九章：会话管理

9.1 核心概念

OpenClaw 将智能体的直接聊天视为主会话。所有会话状态由 Gateway 网关拥有，UI 客户端需向其查询。

9.2 私信作用域（dmScope）

通过 session.dmScope 控制私信的分组策略：

9.3 身份链接（identityLinks）

将不同渠道的同一用户映射到统一身份：

{
  "session": {
    "identityLinks": [
      {
        "canonical": "whatsapp:+86138xxxx",
        "aliases": ["telegram:zhang_user", "discord:zhang#1234"]
      }
    ]
  }
}

9.4 会话重置策略

9.5 手动会话控制

9.6 发送策略

可通过规则阻止特定会话类型的消息投递：

/send on     # 启用发送
/send off    # 禁用发送
/send inherit # 继承默认设置

9.7 存储位置

~/.openclaw/agents/<agentId>/sessions/
├── sessions.json           # 会话索引
└── <sessionId>.jsonl       # JSONL 格式对话记录

第十章：记忆系统

10.1 核心理念

OpenClaw 的记忆系统基于"纯 Markdown 文件"——磁盘上的文件是唯一的事实来源，模型只保留写入磁盘的内容。

10.2 双层记忆结构

日志层 — memory/YYYY-MM-DD.md

• 每日一个文件，仅追加
• 记录每日事件、笔记和上下文信息
• 类似"工作日志"

长期层 — MEMORY.md

• 提炼后的持久事实
• 仅在私信会话中加载
• 类似"人类的长期记忆"

10.3 写入指南

10.4 向量记忆搜索

系统在记忆文件上构建语义索引，支持按含义而非精确措辞查询：

• 默认启用，自动监控文件变更
• 混合检索：向量相似度 + BM25 关键词匹配
• Embedding 缓存：未变更的文本块不会重新计算

提供商选择：

支持自定义端点、批量处理和降级回退机制。

10.5 自动记忆刷写

当会话接近上下文压缩阈值时，OpenClaw 自动触发一轮静默推理，提醒模型在上下文被压缩前保存重要信息。

配置项：

{
  "agents": {
    "defaults": {
      "memoryFlush": {
        "enabled": true,
        "softThresholdTokens": 150000
      }
    }
  }
}

第十一章：多智能体路由

11.1 核心概念

OpenClaw 支持在单个 Gateway 中运行多个隔离的智能体。每个智能体拥有完全独立的工作区、状态和会话。

认证配置文件是每个智能体独立的，不会自动共享主凭证。

11.2 路由机制

消息通过 bindings（绑定） 规则路由，遵循特定性优先原则：

1. 对等方精确匹配：私信/群组/频道 ID
2. 频道级匹配：accountId
3. 默认回退：fallback 到默认智能体

11.3 配置示例

多账户 WhatsApp：不同 WhatsApp 账户路由至不同智能体

{
  "agents": {
    "list": [
      {
        "id": "personal",
        "workspace": "~/.openclaw/workspace-personal"
      },
      {
        "id": "business",
        "workspace": "~/.openclaw/workspace-business"
      }
    ]
  },
  "routing": {
    "bindings": [
      { "agentId": "personal", "channel": "whatsapp", "account": "personal" },
      { "agentId": "business", "channel": "whatsapp", "account": "biz" }
    ]
  }
}

按渠道分割：WhatsApp 用快速模型，Telegram 用高级模型

群组隔离：特定群组绑定到专用智能体，支持提及限制和工具策略

11.4 安全配置

不受信任的智能体可限制为仅访问特定工具，实现"共享一个 Gateway 服务器，同时保持 AI 大脑和数据隔离"。

第十二章：子智能体

12.1 什么是子智能体

子智能体是从现有智能体中派生的后台运行实例，在独立会话中运行，完成后将结果汇报给调用者。

12.2 管理命令

12.3 运行机制

• 非阻塞派生：/subagents spawn 立即返回 runId
• 结果公告：完成后，子智能体向调用者的聊天频道发布摘要消息
• 公告格式：包含 Status（状态）、Result（结果）、Notes（备注）、运行时长和 token 统计

12.4 工具配置

sessions_spawn 工具支持以下参数：

子智能体默认继承调用者的模型和思考配置，除非明确覆盖。

12.5 安全隔离

• 默认获得所有工具，除了会话相关工具（sessions_list、sessions_history 等）
• 可通过 allow/deny 列表自定义工具访问
• 禁止嵌套：子智能体不能再派生子智能体，防止级联扇出

12.6 成本优化

每个子智能体维护独立的 token 用量。可为子智能体分配更低成本的模型，主智能体保持高质量模型：

{
  "subagents": {
    "model": "anthropic/claude-haiku-4-5"
  }
}

第十三章：智能体循环

13.1 完整流程

智能体循环（Agent Loop）是一次完整的处理流程：

接收消息 → 上下文组装 → 模型推理 → 工具执行 → 流式回复 → 持久化

13.2 四层架构

13.3 队列与并发

• 运行按会话键序列化
• 防止工具竞争
• 保持历史一致性

13.4 提示组装

系统提示由三部分组成：

1. 基础提示（安全、身份、规则）
2. Skills 提示（按需加载）
3. 引导上下文（工作区文件）

强制执行模型特定的限制（如 token 上限）。

13.5 钩子系统

13.6 流式传输

• 助手增量内容实时发出
• 工具事件单独跟踪
• 支持部分回复

13.7 超时配置

第十四章：上下文管理与会话修剪

14.1 上下文窗口组成

“上下文"是 OpenClaw 在单次运行中发送给模型的所有内容，受模型 token 上限约束。

14.2 诊断命令

14.3 工具的双重成本

工具影响上下文的两个方面：

1. 作为文本出现在系统提示中
2. 作为 JSON Schema 发送给模型以启用调用

两者都消耗 token。

14.4 会话修剪（Session Pruning）

修剪从上下文中移除旧的工具结果，但不修改持久化的会话历史文件。

触发条件：mode: "cache-ttl" 启用且距离上次 API 调用已超过 TTL 时间。

修剪规则：

14.5 修剪策略

支持工具白名单/黑名单，大小写不敏感，支持通配符匹配。

14.6 默认配置

上下文窗口默认估算为 200,000 tokens（约 4 字符/token）。

第十五章：引导流程

15.1 三种引导文件

OpenClaw 使用三种引导文件，分别在不同时机执行：

15.2 BOOTSTRAP.md — 初始化仪式

首次运行时的引导对话，流程如下：

1. 初始对话：智能体以类似 “Hey, I just came online. Who am I? Who are you?” 的方式开场
2. 身份发现：通过对话确定名字、称呼、存在形态、沟通风格和表情符号
3. 文件生成：根据对话结果更新三个文件：
   • IDENTITY.md — 自我描述
   • USER.md — 用户信息和偏好
   • SOUL.md — 价值观、行为准则、边界
4. 连接方式：可选设置 Web 聊天、WhatsApp 或 Telegram
5. 完成：删除 BOOTSTRAP.md，开始独立运行

整个过程强调自然、非机械化的对话语气，鼓励协作式的意义创造。

15.3 BOOT.md — 启动清单

每次网关重启时执行的简短指令：

# Boot

启动时执行以下检查：
- [ ] 检查日历今日事件
- [ ] 检查未读邮件摘要
- [ ] 向用户发送简短的"早安"问候

配置要求：需启用 hooks.internal.enabled。

如果操作涉及发消息，使用 message 工具并以 NO_REPLY 响应。

15.4 HEARTBEAT.md — 心跳检查

定时执行的例行任务清单：

# Heartbeat

<!-- 留空或仅包含注释 = 跳过心跳 API 调用 -->

定期检查：
- [ ] 查看是否有新邮件
- [ ] 检查日历提醒
- [ ] 监控特定服务状态

留空文件或仅包含注释即可禁用心跳调用。

第十六章：渠道接入

16.1 通用配置结构

每个渠道在 channels.<provider> 下配置：

{
  "channels": {
    "<provider>": {
      "enabled": true,
      "dmPolicy": "pairing",
      "allowFrom": ["+86138xxxx"]
    }
  }
}

16.2 dmPolicy 模式

16.3 Telegram 配置

步骤一：通过 @BotFather 创建机器人，获取 token

步骤二：配置 token（二选一）

# 环境变量方式
export TELEGRAM_BOT_TOKEN=123:abc

# 或在 openclaw.json 中配置（优先级更高）

步骤三：最小化配置

{
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "123:abc",
      "dmPolicy": "pairing"
    }
  }
}

功能特性：

群组访问控制：

{
  "channels": {
    "telegram": {
      "groups": {
        "allowList": ["-1001234567890"],
        "mentionGated": true
      }
    }
  }
}

设置 groups 会创建允许白名单，未在列表中的群组将被忽略。

16.4 WhatsApp 配置

# WhatsApp 配对
openclaw channels login

最小配置：

{
  "channels": {
    "whatsapp": {
      "allowFrom": ["+86138xxxx"]
    }
  }
}

安全建议：使用专用第二号码，而非个人主号。始终配置 allowFrom 白名单。

16.5 验证

# 发送测试消息
openclaw message send --target +86138xxxx --message "Hello from OpenClaw"

第十七章：Web 控制界面

17.1 概述

控制 UI 是由 Gateway 提供的 Vite + Lit 单页应用，默认运行在 http://<host>:18789/，通过 WebSocket 与 Gateway 通信。

17.2 功能模块

17.3 访问方式

17.4 安全特性

• WebSocket 握手期间提供 token 或密码认证
• 设备配对机制防止未授权访问
• 支持设备撤销与 token 轮换

附录：模型配置参考

模型格式

使用 provider/model 格式：

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "anthropic/claude-sonnet-4-5",
        "fallbacks": ["openai/gpt-5.2"]
      }
    }
  }
}

运行时切换模型

通过 /model 命令在聊天中动态切换，需在 agents.defaults.models 中配置允许列表。

配置验证

OpenClaw 使用严格的 schema 验证，未知键或类型不匹配会导致启动失败：

# 诊断配置问题
openclaw doctor

热重载

系统监控 ~/.openclaw/openclaw.json，安全变更无需重启：

参考链接：OpenClaw 官方文档 | 完整文档索引