# OpenClaw 线上知识库

**版本**: 1.0.0
**最后更新**: 2026-03-12
**目的**: 为 ZClaw 项目提供全面、结构化的 OpenClaw 抷术参考

---

## 目录

1. [核心概念](#核心概念)
2. [系统架构](#系统架构)
3. [Gateway 协议](#gateway-协议)
4. [配置系统](#配置系统)
5. [Skills 与 Tools](#skills-与-tools)
6. [插件开发](#插件开发)
7. [多 Agent 路由](#多-agent-路由)
8. [安全与沙箱](#安全与沙箱)
9. [Heartbeat 机制](#heartbeat-机制)
10. [Channels 通道系统](#channels-通道系统)
11. [最佳实践](#最佳实践)

12. [ZClaw 映射指南](#zclaw-映射指南)

---

## 核心概念

### OpenClaw 是什么？

OpenClaw 是一个 **自托管的 AI Agent 硴关**，不是简单的"聊天 UI + 模型接入器"。

**核心定位**：
- **自托管**: 运行在你自己的硬件上，你的规则
- **多通道**: 一个 Gateway 同时服务 WhatsApp、Telegram、Discord、飞书等多个渠道
- **Agent 原生**: 为编码 Agent 构建，支持工具调用、会话、记忆、多 Agent 路由
- **开源**: MIT 许可，社区驱动

**关键洞察**： OpenClaw 的核心价值是 **执行 + 持续性 + 可控性**：
- **执行**: 能真正读写文件、跑命令、控浏览器、发消息
- **持续性**: 不只是一次性问答，而是可长期运转的 Agent
- **可控性**: 用户能看到配置、文本指令、工作区与约束，而不是黑盒

### Agent 的真正含义

在 OpenClaw 中，一个 Agent 包含：
- 一个 `agentId`
- 一个独立 workspace / agentDir
- 一组 bootstrap 文件 (`AGENTS.md`、`SOUL.md`、`USER.md`、`IDENTITY.md`)
- 一套工具与 sandbox 规则
- 一套 session 历史
- 一组可能的 channel bindings
- 一种人格 / 工作方式 / 角色定位

### Bootstrap 文件职责

| 文件 | 职责 | 内容示例 |
|------|------|----------|
| `AGENTS.md` | 操作规范与行为准则 | 会话启动 checklist、安全规范、工具使用规则 |
| `SOUL.md` | 身份、气质、边界 | Core Truths、Boundaries、Vibe、Continuity |
| `USER.md` | 关于用户的信息 | 用户习惯、上下文、沟通偏好、时区 |
| `IDENTITY.md` | Agent 外显身份 | Name、Emoji、Avatar、Vibe |
| `HEARTBEAT.md` | 心跳任务指令 | 定时检查任务、触发条件、投递目标 |

---

## 系统架构

### 四层架构

```
┌─────────────────────────────────────────────────────────────┐
│                     应用层 (Application)                      │
│  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐        │
│  │WhatsApp │  │Telegram │  │ Discord │  │  飞书   │        │
│  └────┬────┘  └────┬────┘  └────┬────┘  └────┬────┘        │
│       │            │            │            │               │
│       └────────────┴────────────┴────────────┘               │
│                          │                                   │
│                          ▼                                   │
│  ┌───────────────────────────────────────────────────────┐  │
│  │                   Gateway (中枢)                        │  │
│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐    │  │
│  │  │  WebSocket  │  │   HTTP API  │  │   Config    │    │  │
│  │  │   Server    │  │   Server    │  │   Manager   │    │  │
│  │  └─────────────┘  └─────────────┘  └─────────────┘    │  │
│  └───────────────────────────────────────────────────────┘  │
│                          │                                   │
│                          ▼                                   │
│  ┌───────────────────────────────────────────────────────┐  │
│  │                  Agent Runtime                          │  │
│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐    │  │
│  │  │   Skills    │  │   Tools     │  │   Memory    │    │  │
│  │  └─────────────┘  └─────────────┘  └─────────────┘    │  │
│  └───────────────────────────────────────────────────────┘  │
│                          │                                   │
│                          ▼                                   │
│  ┌───────────────────────────────────────────────────────┐  │
│  │                   LLM Providers                         │  │
│  │  ┌────────┐  ┌────────┐  ┌────────┐  ┌────────┐       │  │
│  │  │ Claude │  │  GPT-4  │  │  GLM   │  │ Qwen   │       │  │
│  │  └────────┘  └────────┘  └────────┘  └────────┘       │  │
│  └───────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘
```

### Gateway 职责

Gateway 是 OpenClaw 的真正控制面板：

- WebSocket 协议握手与会话维持
- Agent 运行时管理
- Session/stream 事件分发
- Channels 消息收发
- 配置热加载与配置 RPC
- Skills / Tools / Plugins / Heartbeat 协调
- Device auth / pairing / scopes

### Workspace 结构

```
~/.openclaw/
├── openclaw.json          # 主配置文件
├── .env                   # 环境变量
├── workspace/             # 默认工作区
│   ├── AGENTS.md
│   ├── SOUL.md
│   ├── USER.md
│   ├── IDENTITY.md
│   ├── memory.md
│   └── memory/
│       └── YYYY-MM-DD.md
├── agents/                # 多 Agent 状态目录
│   └── <agentId>/
│       ├── agent/
│       │   └── auth-profiles.json
│       └── sessions/
│           └── <sessionKey>.jsonl
└── skills/                # 托管技能目录
```

---

## Gateway 协议

### WebSocket 帧类型

```typescript
// 请求帧
interface GatewayRequest {
  type: 'req';
  id: string;
  method: string;
  params?: Record<string, any>;
}

// 响应帧
interface GatewayResponse {
  type: 'res';
  id: string;
  ok: boolean;
  payload?: any;
  error?: any;
}

// 事件帧
interface GatewayEvent {
  type: 'event';
  event: string;
  payload?: any;
  seq?: number;
}
```

### 握手流程

```
客户端                          Gateway
  │                               │
  │────── WebSocket Connect ────▶│
  │                               │
  │◀───── connect.challenge ─────│  (包含 nonce)
  │                               │
  │────── connect request ──────▶│  (包含 device 签名)
  │                               │
  │◀───── connect response ──────│  (成功/失败)
  │                               │
  │◀═══════ 事件流 ═══════════════│  (agent, chat, etc.)
  │                               │
```

### Device 认证

```typescript
// 签名载荷格式 (v2)
const payload = [
  'v2',
  deviceId,
  clientId,
  clientMode,
  role,
  scopes.join(','),
  String(signedAt),
  token || '',
  nonce,
].join('|');

// 使用 Ed25519 签名
const signature = nacl.sign.detached(messageBytes, secretKey);
```

### 连接参数

```typescript
interface ConnectParams {
  minProtocol: 3;
  maxProtocol: 3;
  client: {
    id: string;        // 客户端标识
    version: string;   // 客户端版本
    platform: string;  // Win32/Darwin/Linux
    mode: 'operator' | 'node';
  };
  role: 'operator' | 'node';
  scopes: string[];    // ['operator.read', 'operator.write']
  auth?: { token?: string };
  device: {
    id: string;        // 设备 ID (公钥指纹)
    publicKey: string; // Base64 编码的公钥
    signature: string; // 签名
    signedAt: number;  // 签名时间戳
    nonce: string;     // 服务器提供的 nonce
  };
}
```

### 核心 RPC 方法

| 方法 | 描述 | 参数 |
|------|------|------|
| `agent` | 发送消息给 Agent | `message`, `sessionKey?`, `model?` |
| `health` | 获取健康状态 | - |
| `status` | 获取 Gateway 状态 | - |
| `config.get` | 获取配置 | `path` |
| `config.patch` | 更新配置 | `path`, `value` |
| `send` | 通过渠道发送消息 | `channel`, `chatId`, `text` |

### Agent 流事件

```typescript
interface AgentStreamEvent {
  stream: 'assistant' | 'tool' | 'lifecycle';
  delta?: string;          // 增量文本
  content?: string;        // 完整内容
  tool?: string;           // 工具名称
  phase?: 'start' | 'end' | 'error';
  runId?: string;          // 运行 ID
  error?: string;          // 错误信息
}
```

---

## 配置系统

### 配置文件位置

```
~/.openclaw/openclaw.json   # 主配置
~/.openclaw/.env            # 环境变量
```

### 配置层级与优先级

```
agents.defaults.*           # 全局默认
    ↓ 覆盖
agents.list[].*             # 每个 Agent 的覆盖
    ↓ 覆盖
channels.defaults.*         # 全渠道默认
    ↓ 覆盖
channels.<channel>.*        # 单渠道覆盖
    ↓ 覆盖
channels.<channel>.accounts.<id>.*  # 账号级覆盖
```

### 热加载模式

| 模式 | 行为 |
|------|------|
| `hybrid` (默认) | 安全更改即时生效，关键更改自动重启 |
| `hot` | 只热应用安全更改，需重启时记录警告 |
| `restart` | 任何更改都重启 Gateway |
| `off` | 禁用文件监控，手动重启生效 |

### CLI 配置命令

```bash
# 查看配置
openclaw config get agents.defaults.workspace

# 设置配置
openclaw config set agents.defaults.heartbeat.every "2h"

# 删除配置
openclaw config unset tools.web.search.apiKey

# 配置向导
openclaw configure

# 完整设置向导
openclaw onboard
```

### 环境变量引用

```json
{
  "gateway": {
    "auth": {
      "token": "${OPENCLAW_GATEWAY_TOKEN}"
    }
  },
  "models": {
    "providers": {
      "openai": {
        "apiKey": "${OPENAI_API_KEY}"
      }
    }
  }
}
```

---

## Skills 与 Tools

### Skills 加载位置与优先级

1. **Bundled skills**: 安装包自带
2. **Managed/local skills**: `~/.openclaw/skills`
3. **Workspace skills**: `<workspace>/skills`
4. **Extra dirs**: `skills.load.extraDirs` 配置

**优先级**: workspace > managed > bundled > extraDirs

### SKILL.md 格式

```markdown
---
name: my-skill
description: 技能描述
homepage: https://example.com
user-invocable: true
disable-model-invocation: false
---

# 技能标题

技能说明内容...

Use {baseDir} to reference skill folder path.
```

### Skills vs Tools 区别

| 概念 | 描述 | 示例 |
|------|------|------|
| **Skills** | 任务说明 + 规则 + 可选脚本的组合 | 代码审查、文档生成 |
| **Tools** | 类型化的可执行能力 | `exec`, `read`, `write`, `browser` |

### 内置 Tools

```json
{
  "tools": {
    "exec": { "shell": true },
    "web": {
      "search": { "enabled": true }
    },
    "browser": { "enabled": true },
    "read": {},
    "write": {},
    "edit": {}
  }
}
```

### MCP 支持

OpenClaw 原生支持 MCP (Model Context Protocol):
- 给 Agent 扩展新的上下文来源与工具面
- 让技能可以调用标准化外部能力
- 让模型在不写死工具的情况下复用第三方协议能力

---

## 插件开发

### 插件结构

```
my-plugin/
├── openclaw.plugin.json   # 必需: 插件清单
├── index.ts              # 入口文件
├── package.json
└── dist/
```

### openclaw.plugin.json

```json
{
  "id": "my-plugin",
  "name": "My Plugin",
  "version": "1.0.0",
  "description": "Plugin description",
  "main": "dist/index.js",
  "skills": ["./skills"],
  "config": {
    "enabled": {
      "type": "boolean",
      "default": true
    }
  }
}
```

### 插件 API

```typescript
interface PluginAPI {
  config: Record<string, any>;

  // 注册 Gateway RPC 方法
  registerGatewayMethod(
    method: string,
    handler: (ctx: RpcContext) => void
  ): void;

  // 注册钩子
  registerHook(
    event: string,
    handler: (...args: any[]) => any,
    meta?: Record<string, any>
  ): void;
}

interface RpcContext {
  params: Record<string, any>;
  respond(ok: boolean, payload: any): void;
}
```

### ZClaw 插件示例

```typescript
// plugins/zclaw-ui/index.ts
export default function register(api: PluginAPI) {
  // 注册自定义 RPC 方法
  api.registerGatewayMethod('zclaw.clones.list', ({ respond }) => {
    const data = readZclawData();
    respond(true, { clones: data.clones });
  });

  // 注册启动钩子
  api.registerHook('gateway:startup', async () => {
    console.log('[ZCLAW] Plugin loaded');
  });
}
```

---

## 多 Agent 路由

### 路由规则 (按优先级)

1. `peer` 精确匹配 (DM/group/channel id)
2. `parentPeer` 继承匹配 (thread 继承)
3. `guildId + roles` (Discord 角色路由)
4. `guildId` (Discord)
5. `teamId` (Slack)
6. `accountId` 规则
7. channel-level 匹配 (`accountId: "*"`)
8. fallback 到默认 Agent

### Binding 配置

```json
{
  "bindings": [
    {
      "agentId": "work",
      "match": {
        "channel": "whatsapp",
        "accountId": "personal",
        "peer": { "kind": "direct", "id": "+15551234567" }
      }
    },
    {
      "agentId": "main",
      "match": { "channel": "whatsapp" }
    }
  ]
}
```

### 多 Agent 配置示例

```json
{
  "agents": {
    "list": [
      {
        "id": "home",
        "default": true,
        "workspace": "~/.openclaw/workspace-home"
      },
      {
        "id": "work",
        "workspace": "~/.openclaw/workspace-work",
        "model": "anthropic/claude-opus-4-6"
      }
    ]
  },
  "bindings": [
    { "agentId": "home", "match": { "channel": "whatsapp", "accountId": "personal" } },
    { "agentId": "work", "match": { "channel": "whatsapp", "accountId": "biz" } }
  ]
}
```

---

## 安全与沙箱

### 沙箱模式

| 模式 | 描述 |
|------|------|
| `off` | 无沙箱，直接执行 |
| `write` | 只沙箱写操作 |
| `all` | 所有操作都在沙箱中执行 |

### 工具策略

```json
{
  "agents": {
    "list": [
      {
        "id": "family",
        "sandbox": { "mode": "all" },
        "tools": {
          "allow": ["read", "exec"],
          "deny": ["write", "browser"]
        }
      }
    ]
  }
}
```

### 安全检查清单

- [ ] 无硬编码密钥 (使用 env 引用)
- [ ] DM 访问控制已配置
- [ ] 群聊 mention 规则已设置
- [ ] 工具权限最小化
- [ ] 沙箱模式适当
- [ ] Gateway 端口不对外暴露

---

## Heartbeat 机制

### 概念

Heartbeat 不是简单的 cron，而是 **定期触发一个完整 Agent turn**：
- 默认读取 `HEARTBEAT.md`
- 如果没事做，返回 `HEARTBEAT_OK`
- 可以配置投递目标 (`none`、`last` 或具体渠道)
- 可以设置 active hours
- 支持 per-agent 覆盖

### 配置

```json
{
  "agents": {
    "defaults": {
      "heartbeat": {
        "every": "1h",
        "activeHours": { "start": "09:00", "end": "18:00" },
        "deliverTo": "last"
      }
    }
  }
}
```

### HEARTBEAT.md 示例

```markdown
# 心跳任务

每小时检查:
1. 是否有待处理的提醒
2. 是否需要发送日报
3. 日历事件提醒

如果无事可做，回复 HEARTBEAT_OK
```

---

## Channels 通道系统

### 支持的通道

| 通道 | 多账号 | 描述 |
|------|--------|------|
| WhatsApp | ✅ | 通过 Web WhatsApp |
| Telegram | ✅ | Bot API |
| Discord | ✅ | Bot + Guild |
| 飞书 | ✅ | 企业自建应用 |
| Slack | ✅ | Bot + Workspace |
| iMessage | ❌ | macOS only |
| Signal | ✅ | 通过 signald |

### 通道配置结构

```json
{
  "channels": {
    "whatsapp": {
      "enabled": true,
      "dmPolicy": "pairing",
      "allowFrom": ["+15555550123"],
      "accounts": {
        "personal": {
          "authDir": "~/.openclaw/credentials/whatsapp/personal"
        },
        "biz": {
          "authDir": "~/.openclaw/credentials/whatsapp/biz"
        }
      }
    }
  }
}
```

### 访问控制

```json
{
  "channels": {
    "whatsapp": {
      "dmPolicy": "allowlist",
      "allowFrom": ["+15555550123"],
      "groups": {
        "*": { "requireMention": true }
      }
    }
  },
  "messages": {
    "groupChat": {
      "mentionPatterns": ["@openclaw", "小龙虾"]
    }
  }
}
```

---

## 最佳实践

### 1. 配置管理

```bash
# 使用 CLI 而非直接编辑 JSON
openclaw config set agents.defaults.model "anthropic/claude-sonnet-4-6"

# 验证配置
openclaw doctor

# 查看日志
openclaw logs --follow
```

### 2. Agent 隔离

- 每个 Agent 使用独立 workspace
- 不共享 `agentDir` (会导致 auth/session 冲突)
- 敏感 Agent 启用沙箱

### 3. 密钥管理

```json
// 使用环境变量引用
{
  "models": {
    "providers": {
      "openai": {
        "apiKey": "${OPENAI_API_KEY}"
      }
    }
  }
}
```

### 4. 错误处理

- Gateway 连接是协议适配工程，不是简单的 ws 连接
- 实现指数退避重连
- 正确处理 `connect.challenge`

---

## ZClaw 映射指南

### 设置页面对应关系

| ZClaw 页面 | OpenClaw 子系统 | 真实目标 |
|-----------|-----------------|----------|
| 通用 | 系统级设置 | 控制连接状态、系统级行为开关 |
| 模型与 API | providers / model defaults | 管理 provider 配置、主模型与 fallback |
| MCP 服务 | Tools / MCP | 定义 Agent 可接入的外部能力 |
| 技能 | Skills | 管理 Agent 可调用的工作流知识库 |
| IM 频道 | Channels | 管理消息来源和路由规则 |
| 工作区 | Workspace / Sandbox | 确定 Agent 执行边界 |
| 数据与隐私 | Data / Telemetry | 明确数据存储位置和隐私设置 |
| 分身/快速配置 | Agents / Bindings | 创建/配置新的 Agent 实例 |

### ZClaw 自定义 RPC 方法

```typescript
// plugins/zclaw-ui 注册的方法
client.listClones()          // zclaw.clones.list
client.createClone(opts)     // zclaw.clones.create
client.updateClone(id, opts) // zclaw.clones.update
client.deleteClone(id)       // zclaw.clones.delete
client.getUsageStats()       // zclaw.stats.usage
client.getSessionStats()     // zclaw.stats.sessions
client.getWorkspaceInfo()    // zclaw.workspace.info
client.getPluginStatus()     // zclaw.plugins.status
client.getQuickConfig()      // zclaw.config.quick
client.listSkills()          // zclaw.skills.list
```

### 分身 (Clone) = Agent 实例

```typescript
interface CloneConfig {
  id: string;
  name: string;
  role?: string;
  nickname?: string;
  scenarios?: string[];
  model?: string;
  workspaceDir?: string;
  workspaceResolvedPath?: string;
  restrictFiles?: boolean;
  privacyOptIn?: boolean;
  userName?: string;
  userRole?: string;
  bootstrapReady?: boolean;
  bootstrapFiles?: Array<{ name: string; path: string; exists: boolean }>;
}
```

### 判断标准

> 如果一个页面改动之后，没有改变 OpenClaw Runtime 的真实行为、真实配置、真实路由、真实工作区或真实 Agent 上下文，那它大概率还只是"演示 UI"，不是系统能力。

---

## ZCLAW 桌面 Gateway 握手排障案例（2026-03）

### 症状演进

1. 初始表现为桌面端长时间停留在“握手中...”
2. 修正握手客户端身份后，错误表象变成 `WebSocket connection failed`
3. 修复候选地址 fallback 的错误覆盖后，暴露出真实错误 `origin not allowed`
4. 自动补齐 `gateway.controlUi.allowedOrigins` 后，错误继续推进为 `pairing required`

### 已确认的排查结论

- `gateway.auth.token` 已正确从 `openclaw.json` 读取并注入桌面端连接
- Tauri 调试版实际运行的是 `target/debug/resources/openclaw-runtime`
- Gateway WebSocket 握手客户端身份需满足当前 schema：
  - `client.id=cli`
  - `client.mode=cli`
  - `role=operator`
- 浏览器 / WebView 环境与 Node 探针的关键差异是会附带 `Origin`
- Tauri WebView 需要被加入：
  - `gateway.controlUi.allowedOrigins`
  - `http://tauri.localhost`
  - `tauri://localhost`
- 当 `origin not allowed` 被解决后，Gateway 会继续要求对当前设备完成 pairing

### 有效的排障方法

#### 1. 先分离“网络失败”和“协议失败”

如果 UI 只显示 `WebSocket connection failed`，先检查连接代码是否在多个候选地址之间 fallback，并把更早的握手错误覆盖掉。  
ZCLAW 的处理方式是：

- 仅对以下错误继续尝试下一个候选地址：
  - `WebSocket connection failed`
  - `Gateway handshake timed out`
  - `WebSocket closed before handshake completed`
- 对握手 / 鉴权 / schema 错误立即停止 fallback，原样暴露给 UI

#### 2. 用独立协议探针验证 Gateway 真正接受的握手参数

在本案例中，Node 探针证明了：

- `cli/cli/operator` 是可接受的客户端身份
- 设备 `deviceId` 必须和 `publicKey` 的派生规则一致
- 仅靠终端探针成功并不能证明 Tauri WebView 一定能连通，因为 WebView 会额外带 `Origin`

#### 3. 优先检查本地 Gateway 的 pending / paired devices

可用命令：

```powershell
openclaw devices list --json
```

本案例中，`pairing required` 发生时，`devices list` 已能看到当前桌面端的 pending 请求，说明：

- 连接已到达 Gateway
- 当前缺的是“批准这台设备”，不是 token 或网络

### ZCLAW 当前修复策略

#### A. 连接前自动准备本地 Gateway

桌面端在 Tauri 运行时连接前，先调用本地准备逻辑：

- 确保 `gateway.controlUi.allowedOrigins` 包含：
  - `http://tauri.localhost`
  - `tauri://localhost`
- 如果配置被修改且 Gateway 正在运行，自动重启 Gateway 使配置生效

#### B. 握手遇到 `pairing required` 时自动批准本机桌面设备

当前策略只在**本地 loopback Gateway** 下启用：

- 仅匹配 `ws://127.0.0.1:*` 或 `ws://localhost:*`
- 前端读取当前桌面端持久化的 `deviceId/publicKey`
- Tauri 侧调用：

```powershell
openclaw devices list --json
openclaw devices approve <requestId> --json --token <token> --url <url>
```

- 只批准同时匹配以下条件的 pending request：
  - `deviceId`
  - `publicKey`
- 批准成功后立即重试连接

### 后续遇到同类问题时的最短排障顺序

1. 确认当前运行的是目标 `desktop.exe`
2. 确认 `openclaw.json` 中有 `gateway.auth.token`
3. 确认 WebView localStorage 已持久化 `zclaw_gateway_url` / `zclaw_gateway_token`
4. 把握手错误原样暴露，不要让 fallback 覆盖
5. 若报 `origin not allowed`：
   - 检查 `gateway.controlUi.allowedOrigins`
6. 若报 `pairing required`：
   - 检查 `openclaw devices list --json`
   - 看当前桌面设备是否进入 `pending`
7. 如果 pending 存在，优先做“只批准本机当前设备”的自动化，而不是直接放宽所有设备

---

## ZCLAW 桌面聊天 / 模型配置协议错配案例（2026-03）

### 症状

- 桌面端显示 Gateway 已连接，但发送消息立即失败
- 常见错误文案为：
  - `invalid agent params: must have required property 'idempotencyKey'`
  - `invalid agent params: must NOT have additional properties: model`
- 模型与 API 页面可以切换本地显示值，但不会改变 Gateway 的真实默认模型

### 根因

- ZCLAW 桌面端此前仍按旧协议调用 `agent`：
  - 发送了顶层 `model`
  - 没有发送必填 `idempotencyKey`
- 当前 OpenClaw runtime 的 `agent` schema 已变更为：
  - `message` 必填
  - `idempotencyKey` 必填
  - `model` 不是允许的顶层字段
- 桌面端“模型切换”之前只是本地 Zustand 状态，没有写回 Gateway 配置，因此不会影响真实运行时行为

### 有效排查方法

1. 不要只看仓库里的旧 client 封装，要直接核对当前实际 runtime 的 schema
2. 如果仓库源码里搜不到新字段（如 `idempotencyKey`），优先检查打包后的 `openclaw-runtime`
3. 在本案例中，真实约束来自 runtime 中的 `AgentParamsSchema`：
   - `message: NonEmptyString`
   - `idempotencyKey: NonEmptyString`
   - `agentId/sessionKey/...` 可选
   - `additionalProperties: false`
4. 对模型配置，不要只改前端本地状态；应优先确认 runtime 是否已暴露：
   - `models.list`
   - `config.get`
   - `config.apply`

### ZCLAW 当前修复策略

- `desktop/src/lib/gateway-client.ts`
  - `chat()` 改为发送 `idempotencyKey`
  - 停止发送非法顶层 `model`
  - 新增 `models.list` / `config.get` / `config.apply` 客户端接口
- `desktop/src/store/chatStore.ts`
  - 发送消息时不再把本地 `clone_*` 直接当作 runtime `agentId`
  - 继续保留前端会话与分身关联信息，避免 UI 上下文丢失
- `desktop/src/components/Settings/ModelsAPI.tsx`
  - 改为基于真实 Gateway 配置读写默认模型与中文模型插件 Provider 配置
- `desktop/src/components/ChatArea.tsx`
  - 聊天输入区模型下拉改为通过 `config.apply` 更新 Gateway 默认模型，而不是只切本地显示

### 当前结论

- 如果错误同时出现 `missing idempotencyKey` 和 `unexpected property model`，优先判断为“桌面端协议版本落后于当前 runtime”
- 如果模型切换只改变 UI 文案、不会改变新会话的实际模型，说明它仍是“演示态”，应改为落到 `config.get/config.apply`

---

## 参考资料

### 官方文档

- [OpenClaw 官方文档](https://docs.openclaw.ai/)
- [Gateway 配置参考](https://docs.openclaw.ai/gateway/configuration)
- [Multi-Agent 路由](https://docs.openclaw.ai/concepts/multi-agent)
- [Skills 文档](https://docs.openclaw.ai/tools/skills)
- [Heartbeat 文档](https://docs.openclaw.ai/gateway/heartbeat)

### 社区资源

- [OpenClaw 中文指南](https://yeasy.gitbook.io/openclaw_guide/)
- [awesome-openclaw-skills](https://github.com/VoltAgent/awesome-openclaw-skills)
- [OpenClaw 源码解析](https://www.ququ123.top/2026/03/openclaw-gateway-startup/)

### ZClaw 内部参考

- `docs/openclaw-deep-dive.md` - 深度分析
- `config/openclaw.default.json` - 默认配置
- `plugins/zclaw-ui/index.ts` - 插件实现
- `desktop/src/lib/gateway-client.ts` - 客户端实现