OpenClaw

一、安装

Windwos & Linux & macOS:

npm install -g openclaw@latest

# 安装
npm install -g openclaw-cn@latest

# 运行安装向导
openclaw-cn onboard --install-daemon

# 启动网关
openclaw-cn gateway --port 18789 --verbose

# 模型列表
openclaw models list

# 
openclaw plugins list
# 方式 A：使用 onboard 命令
openclaw onboard

# 方式 B：直接配置 channels 部分
openclaw configure --section channels

二、新手向导

openclaw onboard --install-daemon

提示什么协议，键入 y 下一步 或 n 拒绝。

你将选择：

• 本地 vs 远程 Gateway 网关

• 认证：OpenAI Code (Codex) 订阅（OAuth）或 API 密钥。对于 Anthropic 我们推荐 API 密钥；也支持 claude setup-token。

• 提供商：WhatsApp QR 登录、Telegram/Discord 机器人令牌、Mattermost 插件令牌等。

• Skills：第三方应用的技能。

• 守护进程：后台安装（launchd/systemd；WSL2 使用 systemd）

  • 运行时：Node（推荐；WhatsApp/Telegram 必需）。不推荐 Bun。

• Gateway 网关令牌：向导默认生成一个（即使在 loopback 上）并存储在 gateway.auth.token。

向导文档：向导

{ agent: { skipBootstrap: true } }

三、频道

openclaw plugins list

私信会话隔离

私信访问模型（配对/白名单/开放/禁用）

所有当前支持私信的渠道都支持私信策略（dmPolicy 或 *.dm.policy），在消息处理之前对入站私信进行门控：

• pairing（默认）：未知发送者会收到一个短配对码，机器人会忽略他们的消息直到获得批准。配对码在 1 小时后过期；重复的私信不会重新发送配对码，直到创建新的请求。待处理请求默认每个渠道上限为 3 个。
• allowlist：未知发送者被阻止（没有配对握手）。
• open：允许任何人发私信（公开）。需要渠道白名单包含 "*"（显式选择加入）。
• disabled：完全忽略入站私信。

通过 CLI 批准：

openclaw pairing list <channel>
openclaw pairing approve <channel> <code>

详情 + 磁盘上的文件：配对

私信会话隔离（多用户模式）

默认情况下，OpenClaw 将所有私信路由到主会话，以便你的助手在设备和渠道之间保持连续性。如果多人可以给机器人发私信（开放私信或多人白名单），请考虑隔离私信会话：

{
  session: { dmScope: "per-channel-peer" },
}

这可以防止跨用户上下文泄露，同时保持群聊隔离。如果你在同一渠道上运行多个账户，请改用 per-account-channel-peer。如果同一个人通过多个渠道联系你，请使用 session.identityLinks 将这些私信会话合并为一个规范身份。参见 会话管理 和 配置 。

DingTalk (钉钉)

参考：

• github仓库 地址：soimy/dingtalk
• npm仓库 地址：@soimy/dingtalk - npm
• OpenClaw 钉钉对接教程-阿里云开发者社区

A 通过 npm 包安装 (推荐)

手动通过 npm 包名安装：

openclaw plugins install @soimy/dingtalk

B 通过本地源码安装

如果你想对插件进行二次开发，可以先克隆仓库：

# 1. 克隆仓库
git clone https://github.com/soimy/openclaw-channel-dingtalk.git
cd openclaw-channel-dingtalk

# 2. 安装依赖 (必需)
npm install

# 3. 以链接模式安装 (方便修改代码后实时生效)
openclaw plugins install -l .

C 手动安装

1. 将上方仓库目录下载到 ~/.openclaw/extensions/dingtalk。
2. 确保包含 index.ts, openclaw.plugin.json 和 package.json。
3. 运行 openclaw plugins list 确认 dingtalk 已显示在列表中。

SSS 通过“钉钉官方”仓库进行安装

官网对接文档：OpenClaw和钉钉机器人打通-钉钉开放平台

github仓库：DingTalk-Real-AI/dingtalk-openclaw-connector

npm仓库：@dingtalk-real-ai/dingtalk-connector - npm

# 通过 npm 安装（推荐）
openclaw plugins install @dingtalk-real-ai/dingtalk-connector

# 或通过 Git 安装
openclaw plugins install https://github.com/DingTalk-Real-AI/dingtalk-openclaw-connector.git

# 升级插件
openclaw plugins update dingtalk-connector

# 或本地开发模式
git clone https://github.com/DingTalk-Real-AI/dingtalk-openclaw-connector.git
cd dingtalk-openclaw-connector
npm install
openclaw plugins install -l .

配置

安装后必做：配置插件信任白名单（ plugins.allow ）

从 OpenClaw 新版本开始，如果发现了非内置插件且 plugins.allow 为空，会提示：

[plugins] plugins.allow is empty; discovered non-bundled plugins may auto-load ...

1. 确认插件 id

   本插件 id 固定为：dingtalk（定义于 openclaw.plugin.json）。

   也可用下面命令查看已发现插件：

   openclaw plugins list
   

2. 在 ~/.openclaw/openclaw.json 添加 plugins.allow

   {
     "plugins": {
       "enabled": true,
       "allow": ["dingtalk"]
     }
   }
   

   如果你还有其他已安装且需要启用的插件，请一并加入，例如：

   {
     "plugins": {
       "allow": ["dingtalk", "telegram", "voice-call"]
     }
   }
   

3. 重启 Gateway

   openclaw gateway restart
   

A 交互式配置（推荐）

使用 OpenClaw 命令行向导式配置插件参数：

# 方式 A：使用 onboard 命令
openclaw onboard

# 方式 B：直接配置 channels 部分
openclaw configure --section channels

交互式配置流程：

1. 选择插件 — 在插件列表中选择 dingtalk 或 DingTalk (钉钉)

2. Client ID — 输入钉钉应用的 AppKey

3. Client Secret — 输入钉钉应用的 AppSecret

4. 完整配置 — 可选配置 Robot Code、Corp ID、Agent ID（推荐）

5. 卡片模式

   — 可选启用 AI 互动卡片模式

   • 如启用，需输入 Card Template ID 和 Card Template Key

6. 私聊策略 — 选择 open（开放）或 allowlist（白名单）

7. 群聊策略 — 选择 open（开放）或 allowlist（白名单）

配置完成后会自动保存并重启 Gateway。

钉钉开发者平台配置指南

B 手动配置文件

在 ~/.openclaw/openclaw.json 中添加（仅作参考，交互式配置会自动生成）：

{
  "plugins": {
    "enabled": true,
    "allow": ["dingtalk"]
  },
  // ...
  "channels": {
    "telegram": { ... },

    "dingtalk": {
      "enabled": true,
      "clientId": "dingxxxxxx",
      "clientSecret": "your-app-secret",
      "robotCode": "dingxxxxxx",
      "corpId": "dingxxxxxx",
      "agentId": "123456789",
      "dmPolicy": "open",
      "groupPolicy": "open",
      "debug": false,
      "messageType": "markdown", // 或 "card"
      // 仅card需要配置
      "cardTemplateId": "你复制的模板ID",
      "cardTemplateKey": "你模板的内容变量"
    }
  },
  ...
}

最后重启 Gateway

openclaw gateway restart

SSS 手动配置文件

在 ~/.openclaw/openclaw.json 中添加：

{
  // 1. 如果没有这个属性，则添加（首次安装的openclaw大概没有这个属性），如果有就把 `dingtalk-connector` 追加到已有节点下
  "channels": {
    "dingtalk-connector": {
      "enabled": true,
      "clientId": "dingxxxxxxxxx",
      "clientSecret": "your_secret_here",
      "gatewayToken": "openclaw.json配置中 gateway.auth.token 的值"
    }
  },
  // 2. gateway 本来就是已有的节点，配置时注意只把 `http` 部分追加到已有节点下
  "gateway": {
    "http": {
      "endpoints": {
        "chatCompletions": {
          "enabled": true
        }
      }
    }
  }
}

最后重启 Gateway

openclaw gateway restart

验证

openclaw channels status

Feishu/Lark (飞书)

openclaw 2026.3.2 及之前，推荐使用方式 "X"。

openclaw 2026.3.7 有bug，不要装。

openclaw 2026.3.8 ，仅推荐使用方式 "SSS"。

使用上述配置的同时，切记一定要配置 工具权限 为 full：工具使用权限-重要!!!

X 修改配置（推荐）

1. 在文件的末尾添加上 plugins 块。（具体这么配置的原因，见下方caution警告块）

   警告

   在添加之前确认文件中不包含 plugins 块。如果把 feishu 添加进去即可。

   {
     "channels": {},
     // 把 plugins 添加进去
     "plugins": {
       "entries": {
         "feishu": {
           "enabled": true
         }
       }
     }
   }
   

   重要

   openclaw2026.3.7 版本之后，如果添加了配置还是提示 Download from npm (@openclaw/feishu) ，就执行一下：

   npm install -g @larksuiteoapi/node-sdk
   

   （自用：如果还不行，就下载插件，然后看日志中报错有什么）

2. 重启网关服务：

   openclaw gateway restart
   

3. 配置 Channels：

   openclaw configure --section channels
   

A 交互式安装

使用 OpenClaw 命令行向导式配置插件参数：

# 方式 A：使用 onboard 命令
openclaw onboard

# 方式 B：直接配置 channels 部分（推荐）
openclaw configure --section channels

1. 选择： Feishu/Lark (飞书)

2. 选择：Download from npm (@openclaw/feishu)

B 通过本地源码安装

# 1. 克隆仓库
git clone https://github.com/openclaw/openclaw.git
cd openclaw/extensions/feishu

# 2. 安装依赖 (必需)
npm install

# 3. 以链接模式安装 (方便修改代码后实时生效)
openclaw plugins install -l .

openclaw plugins install ./extensions/feishu

SSS 通过"飞书官方"仓库进行安装

• 飞书官网中的帖子：OpenClaw-飞书官方插件上线
• npm仓库：@larksuiteoapi/feishu-openclaw-plugin - npm

这里不使用“官方帖子”里的方法（非要下载你自己的那个破烂包管理工具），使用openclaw官方的 openclaw plugins 命令进行安装：

openclaw plugins install @larksuiteoapi/feishu-openclaw-plugin

npm install -g @larksuiteoapi/node-sdk

配置

安装后必做：配置插件信任白名单（ plugins.allow ）

从 OpenClaw 新版本开始，如果发现了非内置插件且 plugins.allow 为空，会提示：

[plugins] plugins.allow is empty; discovered non-bundled plugins may auto-load ...

1. 确认插件 id

   本插件 id 固定为：feishu（定义于 openclaw.plugin.json）。

   也可用下面命令查看已发现插件：

   openclaw plugins list
   

2. 在 ~/.openclaw/openclaw.json 添加 plugins.allow

   {
     "plugins": {
       "enabled": true,
       "allow": ["feishu"]
     }
   }
   

   如果你还有其他已安装且需要启用的插件，请一并加入，例如：

   {
     "plugins": {
       "allow": ["feishu", "telegram", "voice-call"]
     }
   }
   

3. 重启 Gateway

   openclaw gateway restart
   

A 交互式配置（推荐）

使用 OpenClaw 命令行向导式配置插件参数：

# 方式 A：使用 onboard 命令
openclaw onboard

# 方式 B：直接配置 channels 部分
openclaw configure --section channels

选择 ● Feishu/Lark (飞书) (configured) ，不要选错 成括号里面(plugin · install)这个

• Enter Feishu APP Secret

• Enter Feishu APP ID

openclaw plugins disable feishu

openclaw config set channels.feishu.streaming true

飞书开发者平台配置指南

• 官网：飞书开放平台

1. 创建企业自建应用

2. 添加机器人

3. 在应用的 凭证与基础信息 页面，复制：

   • App ID（格式如 cli_xxx）
   • App Secret

   ❗ 重要：请妥善保管 App Secret，不要分享给他人。

4. 配置应用权限-批量导入

   {
     "scopes": {
       "tenant": [
         "contact:contact.base:readonly",
         "docx:document:readonly",
         "im:chat:read",
         "im:chat:update",
         "im:message.group_at_msg:readonly",
         "im:message.p2p_msg:readonly",
         "im:message.pins:read",
         "im:message.pins:write_only",
         "im:message.reactions:read",
         "im:message.reactions:write_only",
         "im:message:readonly",
         "im:message:recall",
         "im:message:send_as_bot",
         "im:message:send_multi_users",
         "im:message:send_sys_msg",
         "im:message:update",
         "im:resource",
         "application:application:self_manage",
         "cardkit:card:write",
         "cardkit:card:read",
         "aily:file:read",
         "aily:file:write",
         "application:application.app_message_stats.overview:readonly",
         "application:bot.menu:write",
         "corehr:file:download",
         "docs:document.content:read",
         "event:ip_list",
         "im:chat",
         "im:chat.access_event.bot_p2p_chat:read",
         "im:chat.members:bot_access",
         "im:message.group_msg",
         "sheets:spreadsheet",
         "wiki:wiki:readonly"
       ],
       "user": [
         "contact:user.employee_id:readonly",
         "offline_access",
         "base:app:copy",
         "base:field:create",
         "base:field:delete",
         "base:field:read",
         "base:field:update",
         "base:record:create",
         "base:record:delete",
         "base:record:retrieve",
         "base:record:update",
         "base:table:create",
         "base:table:delete",
         "base:table:read",
         "base:table:update",
         "base:view:read",
         "base:view:write_only",
         "base:app:create",
         "base:app:update",
         "base:app:read",
         "board:whiteboard:node:create",
         "board:whiteboard:node:read",
         "calendar:calendar:read",
         "calendar:calendar.event:create",
         "calendar:calendar.event:delete",
         "calendar:calendar.event:read",
         "calendar:calendar.event:reply",
         "calendar:calendar.event:update",
         "calendar:calendar.free_busy:read",
         "contact:contact.base:readonly",
         "contact:user.base:readonly",
         "contact:user:search",
         "docs:document.comment:create",
         "docs:document.comment:read",
         "docs:document.comment:update",
         "docs:document.media:download",
         "docs:document:copy",
         "docx:document:create",
         "docx:document:readonly",
         "docx:document:write_only",
         "drive:drive.metadata:readonly",
         "drive:file:download",
         "drive:file:upload",
         "im:chat.members:read",
         "im:chat:read",
         "im:message",
         "im:message.group_msg:get_as_user",
         "im:message.p2p_msg:get_as_user",
         "im:message.send_as_user",
         "im:message:readonly",
         "search:docs:read",
         "search:message",
         "space:document:delete",
         "space:document:move",
         "space:document:retrieve",
         "task:comment:read",
         "task:comment:write",
         "task:task:read",
         "task:task:write",
         "task:task:writeonly",
         "task:tasklist:read",
         "task:tasklist:write",
         "wiki:node:copy",
         "wiki:node:create",
         "wiki:node:move",
         "wiki:node:read",
         "wiki:node:retrieve",
         "wiki:space:read",
         "wiki:space:retrieve",
         "wiki:space:write_only",
         "aily:file:read",
         "aily:file:write",
         "im:chat.access_event.bot_p2p_chat:read"
       ]
     }
   }
   

5. 启用机器人能力：应用能力 > 机器人

6. 配置事件订阅

   重要

   先不用这个

   ⚠️ 重要提醒：在配置事件订阅前，请务必确保已完成以下步骤：

   1. 运行 openclaw channels add 添加了 Feishu 渠道
   2. 网关处于启动状态（可通过 openclaw gateway status 检查状态）

   
   

   只关注这个

   在 事件订阅 页面：

   1. 选择 使用长连接接收事件（WebSocket 模式）
   2. 添加事件：im.message.receive_v1（接收消息）

   
   

   ⚠️ 注意：如果网关未启动或渠道未添加，长连接设置将保存失败。

B 手动配置文件

编辑 ~/.openclaw/openclaw.json：

{
  "channels": {
    "feishu": {
      "enabled": true,
      "dmPolicy": "pairing",
      "accounts": {
        "main": {
          "appId": "cli_xxx",
          "appSecret": "xxx",
          "botName": "我的AI助手",
        },
      },
    },
  },
}

export FEISHU_APP_ID="cli_xxx"
export FEISHU_APP_SECRET="xxx"

{
  channels: {
    feishu: {
      domain: "lark",
      accounts: {
        main: {
          appId: "cli_xxx",
          appSecret: "xxx",
        },
      },
    },
  },
}

SSS 手动配置文件

{
  "channels": {
    // 1. 新增这里（如果之前配过自带的feishu，则什么都不用动）
    "feishu": {
      "enabled": true,
      "appId": "cli_a915bbbdfb78dcbb",
      "appSecret": "jB3OlC8IGBb0XMcO6yjFff7dzlkjjwrE",
      "connectionMode": "websocket",
      "domain": "feishu",
      "groupPolicy": "open",
      "streaming": true,
      "dmPolicy": "pairing"
    }
  },
  "plugins": {
    "allow": [
      "feishu-openclaw-plugin"
    ],
    "entries": {
      "feishu": {
        // 2. 确保这里改为 false
        "enabled": false
      },
      // 下面就是插件安装好就自动生成的了
      "feishu-openclaw-plugin": {
        "enabled": true
      }
    },
    "installs": {
      "feishu-openclaw-plugin": {
        "source": "npm",
        "spec": "@larksuiteoapi/feishu-openclaw-plugin",
        "installPath": "C:\\Users\\pc\\.openclaw\\extensions\\feishu-openclaw-plugin",
        "version": "2026.3.8",
        "resolvedName": "@larksuiteoapi/feishu-openclaw-plugin",
        "resolvedVersion": "2026.3.8",
        "resolvedSpec": "@larksuiteoapi/feishu-openclaw-plugin@2026.3.8",
        "integrity": "sha512-77PzCEESdPgqL9jgoV8I3difKOuC/iRiECYLUT+2rLRD1Oy+CHtTXuYwHwztHvbY2sWitev/5rN/TseDHo2FVg==",
        "shasum": "d4acc5a0433aaf77b0d87a028fa627b38efdb4cd",
        "resolvedAt": "2026-03-08T15:37:09.603Z",
        "installedAt": "2026-03-08T15:37:13.195Z"
      }
    }
  }
}

验证

1. 启动网关

   openclaw gateway
   

2. 发送测试消息

   在飞书中找到您创建的机器人，发送一条消息。

3. 配对授权

   默认情况下，机器人会回复一个 配对码。您需要批准此代码：

   openclaw pairing approve feishu <配对码>
   

批准后即可正常对话。

openclaw pairing list feishu

机器人权限

# 直接将下行文本通过 飞书APP内的聊天框 发送给openclaw，接下来会提示你拥有哪些权限，有几个未授权使用。
/feishu auth

点击这里查看其他几个 指令 。

QQ

github：https://github.com/sliverp/qqbot

QQ开放平台：快速注册创建 OpenClaw 机器人

A 通过 npm 包安装（推荐）

安装OpenClaw开源社区QQBot插件

openclaw plugins install @sliverp/qqbot@latest

B 通过本地源码安装

git clone https://github.com/sliverp/qqbot.git && cd qqbot
openclaw plugins install .

配置

1. 配置绑定当前QQ机器人

   # 一行命令 直接配置
   openclaw channels add --channel qqbot --token "<app-id>:<app-secret>"
   
   # 交互式方式 配置
   openclaw configure --section channels
   

2. 重启本地OpenClaw服务

   openclaw gateway restart
   

"plugins": {
  "entries": {
    "qqbot": {
      "enabled": true
    }
  },
  "installs": {
    "qqbot": {
      "source": "npm",
      "spec": "@sliverp/qqbot@latest",
      "installPath": "/home/enlin/.openclaw/extensions/qqbot",
      "version": "1.5.3",
      "resolvedName": "@sliverp/qqbot",
      "resolvedVersion": "1.5.3",
      "resolvedSpec": "@sliverp/qqbot@1.5.3",
      "integrity": "sha512-32g2LLjdGrZEOmw5umel0DuWfRyw2HYX3P6lafFapt/98CF+2LsyAXCYBhkpTS0gN9j/pvQpLYcPilO9mWAScA==",
      "shasum": "8bc609f0a01315ab2c958915ccbff54e3881b868",
      "resolvedAt": "2026-03-08T09:15:20.404Z",
      "installedAt": "2026-03-08T09:15:30.636Z"
    }
  }
}

openclaw plugins upgrade @sliverp/qqbot@latest

验证

在 QQ开放平台 中扫码进行聊天。

启动

openclaw gateway status

# Linux
systemctl --user status openclaw-gateway.service

启动网关服务

后台：

openclaw gateway start

前台（本终端内）：

openclaw gateway
# 或
openclaw gateway --port 18789 --verbose

• --port: 端口号

openclaw gateway run

启动 Control UI

官网：控制 UI - OpenClaw

openclaw dashboard
# 或（要确保该浏览器已经使用 `?token=...` 方式打开过这个网页；原理是 Control UI 将令牌存储在浏览器 localStorage 中）
http://127.0.0.1:18789

# 不自动打开浏览器，仅获取包含token的url
openclaw dashboard --no-open

# 如果没有 token，使用一下命令生成 token
openclaw doctor --generate-gateway-token

设备配对（首次连接）

当你从新浏览器或设备连接到控制 UI 时，Gateway 网关需要一次性配对批准 — 即使你在同一个 Tailnet 上且 gateway.auth.allowTailscale: true。这是防止未授权访问的安全措施。

你会看到： “disconnected (1008): pairing required”批准设备：

# 列出待处理的请求
openclaw devices list

# 按请求 ID 批准
openclaw devices approve <requestId>

一旦批准，设备会被记住，除非你使用 openclaw devices revoke --device <id> --role <role> 撤销它，否则不需要重新批准。参见 Devices CLI 了解 token 轮换和撤销。注意：

• 本地连接（127.0.0.1）会自动批准。
• 远程连接（LAN、Tailnet 等）需要显式批准。
• 每个浏览器配置文件生成唯一的设备 ID，因此切换浏览器或清除浏览器数据将需要重新配对。

启动 TUI

官网：TUI - OpenClaw

openclaw tui
# 或
openclaw tui --mode tui --url <Gateway_URL> --token <Your_Token>

# 远程 Gateway 网关
openclaw tui --url ws://<host>:<port> --token <gateway-token>
## 如果你的 Gateway 网关使用密码认证，请使用 --password。

# 直接键入文字进行对话；键入 `/` 输入命令；`/commands` 查看命令；

你看到的内容

• 标题栏：连接 URL、当前智能体、当前会话。
• 聊天日志：用户消息、助手回复、系统通知、工具卡片。
• 状态行：连接/运行状态（连接中、运行中、流式传输中、空闲、错误）。
• 页脚：连接状态 + 智能体 + 会话 + 模型 + think/verbose/reasoning + token 计数 + 投递状态。
• 输入：带自动完成的文本编辑器。
• Ctrl+O 切换tools输出为 折叠/展开视图 。

开机自启

# 禁用自启
## `Win` + `R`: `taskschd.msc`
`OpenClaw Gateway` 定时任务的 `触发器` 设置为：`禁用`

# 停止服务
openclaw gateway stop

# 启动服务
openclaw gateway start

# 重启服务
openclaw gateway restart

# 查看服务状态
systemctl --user status openclaw-gateway.service
systemctl --user list-units --all | grep -i openclaw

# 查看自启状态
systemctl list-unit-files | grep -i openclaw
UNIT FILE                 STATE           PRESET         
openclaw-gateway.service  enabled         disabled
# 第二列 `enabled` 即为已经是自启状态

# 停止服务
systemctl --user stop openclaw-gateway.service
## 或使用 openclaw 本身的命令
openclaw gateway stop

# 禁用服务的自启
systemctl --user disable openclaw-gateway.service

## 启用自启
systemctl --user enable openclaw-gateway.service
# 启动服务
systemctl --user start openclaw-gateway.service

# 查看服务状态
launchctl list | grep -i ai.openclaw.gateway

# 停止服务
launchctl unload ~/Library/LaunchAgents/ai.openclaw.gateway.plist
## 或使用 openclaw 本身的命令
openclaw gateway stop

# 禁用服务的自启
rm ~/Library/LaunchAgents/ai.openclaw.gateway.plist

## 启用自启（相当于 Linux 下的 enable + start）
launchctl load ~/Library/LaunchAgents/ai.openclaw.gateway.plist

# 启动服务
launchctl start ai.openclaw.gateway
# 停止服务
launchctl stop ai.openclaw.gateway

ls -la ~/Library/LaunchAgents/ | grep -i openclaw

# 输出
文件权限    硬连接数  所属用户    所属组   文件大小 最后修改日期 最*时间  文件名
-rw-r--r--    1    enlin      staff   2111    Mar  4     22:45   ai.openclaw.gateway.plist

cat ~/Library/LaunchAgents/ai.openclaw.gateway.plist

# 输出一大堆东西，只需关注其中的：
## 这是最重要的标志！表示用户登录时自动启动
<key>RunAtLoad</key><true/>

## 程序退出后会自动重启（类似 Linux systemd 的 Restart=always）
<key>KeepAlive</key><true/>

## 正确的文件位置，`~` 下目录确保用户登录时加载
~/Library/LaunchAgents/ 

访问

Windows: http://127.0.0.1:18789

Windows SSH 连接部署了 OpenClaw 的 Linux，Windwos 中执行：

# 通过ssh隧道将本地的18789端口转发到远程的127.0.0.1:18789
## 如果提示 cannot listen to port: 18789，请先检测端口占用。
ssh -N -L 18789:127.0.0.1:18789 用户名@服务器IP
# 回车之后提示输入密码：
用户名@服务器IP's password: 

## 保持命令行窗口开启，在 Windows中访问
http://127.0.0.1:18789

• -N：不执行远程命令，只做端口转发
• -L 18789:127.0.0.1:18789：将本地的 18789 端口转发到远程的 127.0.0.1:18789
• enlin@192.168.3.15：连接到虚拟机（<username>@<ip>）

日志

日志默认位于 /tmp/openclaw/openclaw-YYYY-MM-DD.log 。

可以通过 logging.file 设置稳定路径。文件日志级别由 logging.level 控制。控制台详细度由 --verbose 和 logging.consoleLevel 控制。最快的日志跟踪：

openclaw logs --follow

服务/supervisor 日志（当 Gateway 网关通过 launchd/systemd 运行时）：

• macOS：$OPENCLAW_STATE_DIR/logs/gateway.log 和 gateway.err.log（默认：~/.openclaw/logs/...；配置文件使用 ~/.openclaw-<profile>/logs/...）
• Linux：journalctl --user -u openclaw-gateway[-<profile>].service -n 200 --no-pager
• Windows：schtasks /Query /TN "OpenClaw Gateway 网关 (<profile>)" /V /FO LIST

局域网

gateway.bind 改为 lan

gateway.controlUi.allowedOrigins 新增 需要连接的域名及端口

gateway.controlUi.allowInsecureAuth

"gateway": {
  "port": 18789,
  "mode": "local",
  "bind": "lan",
  "controlUi": {
    "allowedOrigins": [
      "http://localhost:18789",
      "http://127.0.0.1:18789",
      // 填本机ip。因为客户端的浏览器，WebSocket URL 为 ws://<本机ip><:本机端口>
      "http://192.168.3.15:18789"
    ],
    "allowInsecureAuth": true
  },
  "auth": {
    "mode": "token",
    "token": "4a5dd90ef0ce70f3c270bc894c7f6726714b6674a1e31541"
  },
  "allowInsecureAuth": true
}

配置

# 也可以使用命令 版本需 >= `2026.3.1`
openclaw config file

openclaw configure
# 或 2026.3.2 版本之后
openclaw config

# 可以继续往后 `.`, 例如 `plugins.installs`
openclaw config get plugins.installs

{
  // 2026.3.2 及之后就存在了 `tools` 属性，将其中的值该为下面即可。
  "tools": {
    // ai 能力：全部开放
    "profile": "full",
    // 多agent，会话可见
    "sessions": {
      "visibility": "all"
    },
    // agent间通信
    "agentToAgent": {
      "enabled": true
    }
  }
}

# Win + R 之后
%userprofile%/.openclaw/openclaw.json

# 查看
less -N ~/.openclaw/openclaw.json

# 编辑
vim ~/.openclaw/openclaw.json

重新配置

删掉 ~/.openclaw 文件夹之后，重新运行 新手向导 命令。

工具使用权限-(重要)

openclaw 2026.3.1 版本之后，~/.openclaw/openclaw.json 配置文件内多了一个 tools 属性，默认值为 messaging ，这会导致在openclaw中只允许消息相关的工具，而不允许 read / write / exec 等。需要将属性值改为 full ：

"tools": {
  "profile": "full"
},

环境变量

例如 tavily搜索 环境变量问题，linux(systemd) / macOS(launchd) 的 用户自启应用 不依赖用户shell环境，所以这些应用可能读取不到用户shell里的配置。所以配置到 ~/.bashrc / ~/.zshrc 里 openclaw 并读不到，所以这里提供三种系统的自启应用也能读到环境变量的配置方法。

# 创建应用级环境变量文件
touch ~/.openclaw/.env

# 编辑自己的环境变量键值对
TEST_KEY="test_value"

# 方式1：# `Win` + `Q` 搜索“系统环境”关键字

# 方式2：`Win` + `R` 运行命令
sysdm.cpl

# 方式3：通过 PowerShell 打开
start control sysdm.cpl

# 设置用户环境变量（重启后生效）
[Environment]::SetEnvironmentVariable("MY_VAR", "test value", "User")

# 设置系统环境变量（需要管理员权限）
[Environment]::SetEnvironmentVariable("MY_VAR", "test value", "Machine")

# 设置当前会话的环境变量（立即生效，重启失效）
$env:MY_VAR = "test value"

# 查看环境变量
[Environment]::GetEnvironmentVariable("MY_VAR", "User")
[Environment]::GetEnvironmentVariable("MY_VAR", "Machine")
Get-ChildItem Env:MY_VAR

# 删除环境变量
[Environment]::SetEnvironmentVariable("MY_VAR", $null, "User")

# 查看当前用户服务的环境变量
systemctl --user show-environment [|grep -i 关键字]

# 立即生效，但仅对之后启动的用户服务有效
## systemctl --user restart <service-name> 服务重启也会获得新变量
systemctl --user set-environment KEY="VALUE"

# 仅影响 systemd --user 管理的服务
## 不影响通过 terminal 启动的普通进程

# 取消环境变量
systemctl --user unset-environment <KEY>

# 查看 launchd 的默认环境
launchctl export [| grep -i 关键字]

# 设置环境变量（立即生效，但重启后失效）
launchctl setenv MY_VAR "test value"
launchctl setenv ANOTHER_VAR "another value"

# 查看已设置的环境变量
launchctl getenv MY_VAR

# 删除环境变量
launchctl unsetenv MY_VAR

# 编辑 launchd 配置文件
sudo vim /etc/launchd.conf

# 添加
setenv MY_VAR test value

# 重启 launchd（谨慎操作）
sudo launchctl reboot

# 先卸载服务
launchctl unload ~/Library/LaunchAgents/your-service.plist
# 然后重新加载服务
launchctl load ~/Library/LaunchAgents/your-service.plist

# 方法2：使用 -w 选项（强制重新加载）
launchctl load -w ~/Library/LaunchAgents/your-service.plist

# 如果需要手动启动
launchctl start your-service

总结：

跨频道发送消息

问：如何从 Telegram 发送 Discord 消息？（“Cross-context messaging denied”）

答：OpenClaw 默认阻止跨提供商消息。如果工具调用绑定到 Telegram，除非你明确允许，否则不会发送到 Discord。为智能体启用跨提供商消息：

{
  agents: {
    defaults: {
      tools: {
        message: {
          crossContext: {
            allowAcrossProviders: true,
            marker: { enabled: true, prefix: "[from {channel}] " },
          },
        },
      },
    },
  },
}

编辑配置后重启 Gateway 网关。如果你只想为单个智能体设置，将其放在 agents.list[].tools.message 下。

Skills

OpenClaw 从三个位置加载 Skills（名称冲突时工作区优先）：

• 内置 Skills：随安装包一起发布（npm 包或 OpenClaw.app）
• 托管/本地：~/.openclaw/skills
• 工作区：<workspace>/skills

如果 Skills 名称冲突，优先级为：<workspace>/skills（最高）→ ~/.openclaw/skills → 内置 Skills（最低）此外，你可以通过 ~/.openclaw/openclaw.json 中的 skills.load.extraDirs 配置额外的 Skills 文件夹（最低优先级）。

clawhub

github登录认证（可能需要，有的网络环境可能不需要）

# 安装clawhub
npm install -g clawhub

# 登录（需github账号），图形化系统会直接弹出浏览器打开认证url
# 或者执行后浏览器打开 https://clawhub.ai/cli/auth 登录并通过回环回调完成
clawhub login
## 对于没有图形化的linux服务器环境，stdout会输出一个链接，从其他地方打开，认证之后网页会给出一个 `token`，之后自动联网认证
clawhub login --token <token>

下载skill示例：

clawhub install <skill-name> [--workdir <workspace-absolute-path>]
# 示例
clawhub install tavily-search --workdir ~/.openclaw/workspace-web-search/

# 验证。检查对应 `~/.openclaw/workspace-*/skills` 文件夹内是否存在。或者使用 `/skill` 指令。
clawhub list

• --workdir: 目标工作区的路径。要默认安装到 workspace 工作区内，则不用填写。
• --dir: skill安装目录（默认工作区下的 ./skills ）

Examples:

clawhub search "postgres backups"
clawhub install my-skill-pack
clawhub update --all
clawhub update --all --no-input --force
clawhub publish ./my-skill-pack --slug my-skill-pack --name "My Skill Pack" --version 1.2.0 --changelog "Fixes + docs"

• 其他选项参阅 clawhub-cli 。

命令

我目前支持这些命令：

会话管理

• /new 或 /reset - 开始新会话（清空上下文）
• /status - 查看当前状态（模型、使用情况等）
• /reasoning - 切换推理模式（显示/隐藏思考过程）
• /verbose - 切换详细模式（显示/隐藏工具调用）

文件操作

• /read <路径> - 读取文件
• /write <路径> <内容> - 写入文件
• /edit <路径> <旧文本> <新文本> - 编辑文件

工具相关

• /exec <命令> - 执行shell命令
• /browser <动作> - 控制浏览器
• /tts <文本> - 文本转语音

代理管理

• /spawn <任务> - 创建子代理执行任务
• /agents - 列出可用代理
• /sessions - 列出当前会话

其他

• /help - 显示帮助信息

openclaw status          # 本地状态（凭证、会话、排队事件）
openclaw status --all    # 完整诊断（只读，可粘贴）
openclaw status --deep   # 添加 Gateway 网关健康探测（Telegram + Discord）
openclaw health --json   # Gateway 网关健康快照（WS）

日志位于 /tmp/openclaw/（默认：openclaw-YYYY-MM-DD.log）。

终止对话中的任务

发送以下任一内容作为独立消息（不带斜杠）：

stop
abort
esc
wait 
exit
interrupt

这些是中止触发器（不是斜杠命令）。对于后台进程（来自 exec 工具），你可以要求智能体运行：

process action:kill sessionId:XXX

Brave 联网搜索

apikey（需要梯子）: https://api-dashboard.search.brave.com/

免费额度：1000/月

openclaw configure --section web

tavily

apikey（不需要梯子）: https://app.tavily.com/home

（ https://docs.tavily.com/welcome ）

免费额度：1000/月

1. 去上述网站注册获取 API Key

2. 安装 skill（需先安装 clawhub ）

   # 下载 tavily-search
   clawhub install tavily-search
   
   # 验证。检查对应 `~/.openclaw/workspace-*/skills` 文件夹内是否存在。或者使用 `/skill` 指令。
   clawhub list
   

   提示

   如果创建了agent，需要安装到agent的workspace的skills里，则需要指定workspace目录，示例：

   clawhub install tavily-search --workdir ~/.openclaw/workspace-web-search/
   

3. 设置环境变量：

   警告

   警告：此方法仅在每次使用 shell 启动 openclaw 服务的时候生效，如果需要 用户自启服务 也能读到环境变量，请查阅 环境变量 版块。

   export TAVILY_API_KEY="tvly-xxxxx"
   # 永久生效 linux（旧款macOS）
   echo 'export TAVILY_API_KEY="tvly-xxxxx"' >> ~/.bashrc
   # 永久生效 macOS
   echo 'export TAVILY_API_KEY="tvly-xxxxx"' >> ~/.zshrc
   
   # 或者配置到 OpenClaw 启动脚本的环境变量里
   vim ~/.openclaw/gateway.* 
   

   Windows直接去“系统环境变量”里配置。

npx playbooks add skill openclaw/skills --skill tavily
# 或者：
npx playbooks add skill openclaw/skills --skill tavily-search

export TAVILY_API_KEY="tvly-xxxxx"或者配置到 OpenClaw 的环境变量里。（`~/.openclaw/gateway.*` 启动文件里）

空白上下文首次使用时，要使用关键字 tavily 引导使用搜索，例如：使用tavily搜索今日新闻。

模型

openclaw models list

# 模型配置状态（可以查看当前默认模型、图像模型、OAuth/token 状态）
openclaw models status

openclaw models set <model-name>

# 图像模型
openclaw models set-image <model-name>

{
  "provider": "minimax-coding",
  "base_url": "https://api.minimax.io/anthropic", // 国内用户请用 https://api.minimaxi.com/anthropic
  "api": "anthropic-messages",
  "api_key": "你的Coding Plan专用API Key",
  "model": { 
    "id": "MiniMax-M2.5", // Coding Plan 通常对应 M2.5 模型
    "name": "MiniMax M2.5" 
  }
}

{
  "provider": "minimax-payg",
  "base_url": "https://api.minimax.io/v1", // 国内用户请用 https://api.minimaxi.com/v1
  "api": "openai-completions",
  "api_key": "你的通用API Key",
  "model": { 
    "id": "MiniMax-M2.1", // 或者 "MiniMax-M2.1-lightning"
    "name": "MiniMax M2.1" 
  }
}

命令

ℹ️ Slash commands

 Session
   /session - Manage session-level settings (for example /session idle).
   /stop - Stop the current run.
   /reset - Reset the current session.
   /new - Start a new session.
   /compact - Compact the session context.

 Options
   /usage - Usage footer or cost summary.
   /think:<level> (/thinking, /t) - Set thinking level.(off | minimal | low | medium | high | xhigh)（仅 GPT-5.2 + Codex 模型）
   /verbose (/v) - Toggle verbose mode.
   /reasoning (/reason) - Toggle reasoning visibility.
   /elevated (/elev) - Toggle elevated mode.
   /exec - Set exec defaults for this session.
   /model - Show or set the model.
   /models - List model providers or provider models.
   /queue - Adjust queue settings.

 Status
   /help - Show available commands.
   /commands - List all slash commands.
   /status - Show current status.
   /context - Explain how context is built and used.
   /export-session (/export) - Export current session to HTML file with full system prompt.
   /whoami (/id) - Show your sender id.

 Management
   /allowlist [text] - List/add/remove allowlist entries.
   /approve - Approve or deny exec requests.
   /subagents - List, kill, log, spawn, or steer subagent runs for this session.
   /acp - Manage ACP sessions and runtime options.
   /focus - Bind this Discord thread (or a new one) to a session target.
   /unfocus - Remove the current Discord thread binding.
   /agents - List thread-bound agents for this session.
   /kill - Kill a running subagent (or all).
   /steer (/tell) - Send guidance to a running subagent.
   /activation - Set group activation mode.
   /send - Set send policy.

 Media
   /tts - Control text-to-speech (TTS).

 Tools
   /skill - Run a skill by name.
   /restart - Restart OpenClaw.

 Docks
   /dock_telegram (/dock-telegram) - Switch to telegram for replies.
   /dock_discord (/dock-discord) - Switch to discord for replies.
   /dock_slack (/dock-slack) - Switch to slack for replies.

 Plugins
   /pair (device-pair) - Generate setup codes and approve device pairing requests.
   /phone (phone-control) - Arm/disarm high-risk phone node commands (camera/screen/writes).
   /voice (talk-voice) - List/set ElevenLabs Talk voice (affects iOS Talk playback).

文本 + 原生（启用时）：

• /help
• /commands
• /skill <name> [input]（按名称运行 Skill）
• /status（显示当前状态；在可用时包含当前模型提供商的提供商使用量/配额）
• /allowlist（列出/添加/删除白名单条目）
• /approve <id> allow-once|allow-always|deny（解决 exec 审批提示）
• /context [list|detail|json]（解释”上下文”；detail 显示每个文件 + 每个工具 + 每个 Skill + 系统提示词大小）
• /whoami（显示你的发送者 ID；别名：/id）
• /subagents list|kill|log|info|send|steer|spawn（检查、控制或创建当前会话的子智能体运行）
• /config show|get|set|unset（将配置持久化到磁盘，仅所有者；需要 commands.config: true）
• /debug show|set|unset|reset（运行时覆盖，仅所有者；需要 commands.debug: true）
• /usage off|tokens|full|cost（每响应使用量页脚或本地成本摘要）
• /tts off|always|inbound|tagged|status|provider|limit|summary|audio （控制 TTS；参见 /tts ）
  • Discord：原生命令是 /voice（Discord 保留了 /tts）；文本 /tts 仍然有效。
• /stop
• /restart
• /dock-telegram（别名：/dock_telegram）（将回复切换到 Telegram）
• /dock-discord（别名：/dock_discord）（将回复切换到 Discord）
• /dock-slack（别名：/dock_slack）（将回复切换到 Slack）
• /activation mention|always（仅限群组）
• /send on|off|inherit（仅所有者）
• /reset 或 /new [model]（可选模型提示；其余部分传递）
• /think <off|minimal|low|medium|high|xhigh>（按模型/提供商动态选择；别名：/thinking、/t）
• /verbose on|full|off（别名：/v）
• /reasoning on|off|stream（别名：/reason；启用时，发送带有 Reasoning: 前缀的单独消息；stream = 仅 Telegram 草稿）
• /elevated on|off|ask|full（别名：/elev；full 跳过 exec 审批）
• /exec host=<sandbox|gateway|node> security=<deny|allowlist|full> ask=<off|on-miss|always> node=<id>（发送 /exec 显示当前设置）
• /model <name>（别名：/models；或 agents.defaults.models.*.alias 中的 /<alias>）
• /queue <mode>（加上选项如 debounce:2s cap:25 drop:summarize；发送 /queue 查看当前设置）
• /bash <command>（仅主机；! <command> 的别名；需要 commands.bash: true + tools.elevated 白名单）

仅文本：

• /compact [instructions]（参见 /concepts/compaction）
• ! <command>（仅主机；一次一个；对长时间运行的任务使用 !poll + !stop）
• !poll（检查输出/状态；接受可选的 sessionId；/bash poll 也可用）
• !stop（停止正在运行的 bash 任务；接受可选的 sessionId；/bash stop 也可用）

注意事项：

• 命令接受命令和参数之间的可选 :（例如 /think: high、/send: on、/help:）。

• /new <model> 接受模型别名、provider/model 或提供商名称（模糊匹配）；如果没有匹配，文本被视为消息正文。

• 要获取完整的提供商使用量分解，使用 openclaw status --usage。

• /allowlist add|remove 需要 commands.config=true 并遵循渠道 configWrites。

• /usage 控制每响应使用量页脚；/usage cost 从 OpenClaw 会话日志打印本地成本摘要。

• /restart 默认禁用；设置 commands.restart: true 启用它。

• /verbose 用于调试和额外可见性；在正常使用中保持关闭。

• /reasoning（和 /verbose）在群组设置中有风险：它们可能会暴露你不打算公开的内部推理或工具输出。最好保持关闭，尤其是在群聊中。

• 快速路径： 来自白名单发送者的仅命令消息会立即处理（绕过队列 + 模型）。

• 群组提及门控： 来自白名单发送者的仅命令消息绕过提及要求。

• 内联快捷方式（仅限白名单发送者）：

  某些命令在嵌入普通消息时也能工作，并在模型看到剩余文本之前被剥离。

  • 示例：hey /status 触发状态回复，剩余文本继续通过正常流程。

• 目前：/help、/commands、/status、/whoami（/id）。

• 未授权的仅命令消息被静默忽略，内联 /... 令牌被视为纯文本。

• Skill 命令：user-invocable Skills 作为斜杠命令公开。名称被清理为 a-z0-9_（最多 32 个字符）；冲突获得数字后缀（例如 _2 ）。

  • /skill <name> [input] 按名称运行 Skill（当原生命令限制阻止每个 Skill 命令时有用）。
  • 默认情况下，Skill 命令作为普通请求转发给模型。
  • Skills 可以选择声明 command-dispatch: tool 将命令直接路由到工具（确定性，无模型）。
  • 示例：/prose（OpenProse 插件）— 参见 OpenProse。

• 原生命令参数： Discord 使用自动完成进行动态选项（以及当你省略必需参数时的按钮菜单）。当命令支持选择且你省略参数时，Telegram 和 Slack 显示按钮菜单。

使用量显示

• 提供商使用量/配额（示例：“Claude 80% left”）在启用使用量跟踪时显示在 /status 中，针对当前模型提供商。
• 每响应令牌/成本由 /usage off|tokens|full 控制（附加到普通回复）。
• /model status 是关于模型/认证/端点的，不是使用量。

模型选择（/model）

使用 /model <模型名称> 切换模型。示例：

/model
/model list
/model 3
/model openai/gpt-5.2
/model opus@anthropic:default
/model status

注意事项：

• /model 和 /model list 显示紧凑的编号选择器（模型系列 + 可用提供商）。
• /model <#> 从该选择器中选择（并在可能时优先选择当前提供商）。
• /model status 显示详细视图，包括在可用时配置的提供商端点（baseUrl）和 API 模式（api）。

{
    "agents": {
       "defaults": {
         "model": {
           "primary": "bailian/qwen3.5-plus"
         }
       }
    }
}

调试覆盖

/debug 让你设置仅运行时的配置覆盖（内存，不写磁盘）。仅所有者。默认禁用；使用 commands.debug: true 启用。示例：

/debug show
/debug set messages.responsePrefix="[openclaw]"
/debug set channels.whatsapp.allowFrom=["+1555","+4477"]
/debug unset messages.responsePrefix
/debug reset

注意事项：

• 覆盖立即应用于新的配置读取，但不会写入 openclaw.json。
• 使用 /debug reset 清除所有覆盖并返回到磁盘上的配置。

配置更新

/config 写入你的磁盘配置（openclaw.json）。仅所有者。默认禁用；使用 commands.config: true 启用。示例：

/config show
/config show messages.responsePrefix
/config get messages.responsePrefix
/config set messages.responsePrefix="[openclaw]"
/config unset messages.responsePrefix

注意事项：

• 配置在写入前会验证；无效更改会被拒绝。
• /config 更新在重启后持久化。

平台注意事项

• 文本命令在普通聊天会话中运行（私信共享 main，群组有自己的会话）。

• 原生命令

  使用隔离的会话：

  • Discord：agent:<agentId>:discord:slash:<userId>
  • Slack：agent:<agentId>:slack:slash:<userId>（前缀可通过 channels.slack.slashCommand.sessionPrefix 配置）
  • Telegram：telegram:slash:<userId>（通过 CommandTargetSessionKey 定向到聊天会话）

• /stop 定向到活动聊天会话，因此可以中止当前运行。

• Slack： channels.slack.slashCommand 仍然支持单个 /openclaw 风格的命令。如果你启用 commands.native，你必须为每个内置命令创建一个 Slack 斜杠命令（与 /help 相同的名称）。Slack 的命令参数菜单以临时 Block Kit 按钮形式发送。

使用 DeepSeek

参考：

• 配置 DeepSeek | OpenClaw CN

openclaw onboard

Model/auth provider 选择 Custom Provider(Any OpenAI or Anthropic compatible endpoint)：

依次填写：

• API Base URL: https://api.deepseek.com/v1

• API key

• API 兼容模式: OpenAI-compatible

• Model ID: deepseek-chat

• Endpoint ID: deepseek

• Model alias: deepseek-chat

{
    "models": {
       "mode": "merge",
       "providers": {
         "deepseek": {
           "baseUrl": "https://api.deepseek.com/v1",
           "apiKey": "sk-765eaa7b7d9241fd9f4bb5d1896873bb",
           "api": "openai-completions",
           "models": [
             {
               "id": "deepseek-chat",
               "name": "deepseek-chat (Custom Provider)",
               "reasoning": false,
               "input": [
                 "text"
               ],
               "cost": {
                 "input": 0,
                 "output": 0,
                 "cacheRead": 0,
                 "cacheWrite": 0
               },
               "contextWindow": 131072,
               "maxTokens": 8192
             }
           ]
         }
       }
    },
    "agents": {
       "defaults": {
         "model": {
           "primary": "deepseek/deepseek-chat"
         },
         "models": {
           "deepseek/deepseek-chat": {
             "alias": "deepseek-chat"
           }
         },
         "workspace": "/home/enlin/.openclaw/workspace",
         "compaction": {
           "mode": "safeguard"
         },
         "maxConcurrent": 4,
         "subagents": {
           "maxConcurrent": 8
         }
       }
    },
    "plugins": {
       "allow": [
         "dingtalk",
         "feishu"
       ],
       "load": {
         "paths": [
           "D:\\WorkSpace\\AI\\openclaw-channel-dingtalk"
         ]
       },
       "entries": {
         "dingtalk": {
           "enabled": true
         },
         "feishu": {
           "enabled": true
         }
       },
       "installs": {
         "dingtalk": {
           "source": "path",
           "sourcePath": "D:\\WorkSpace\\AI\\openclaw-channel-dingtalk",
           "installPath": "D:\\WorkSpace\\AI\\openclaw-channel-dingtalk",
           "version": "3.1.1",
           "installedAt": "2026-02-25T12:27:11.582Z"
         }
       }
    }
}

多 Agent

官网：多智能体路由 - OpenClaw

多个Agent = 多个人、多种人格，每个 agentId 成为一个完全隔离的人格，每个Agent可以配置不同的model和channels：

• 不同的电话号码/账户（每渠道 accountId）。
• 不同的人格（每智能体工作区文件如 AGENTS.md 和 SOUL.md）。
• 独立的认证 + 会话（除非明确启用，否则无交叉通信）。

这让多个人共享一个 Gateway 网关服务器，同时保持他们的 AI”大脑”和数据隔离。

创建多个Agent是搭建你专属"AI团队"的关键一步。整个过程非常直观，主要通过命令行完成。你可以为每个Agent分配独立的身份、工作空间，甚至绑定不同的大模型，让它们各司其职。

下面是创建多个Agent的核心步骤和最佳实践，帮你快速上手。

🛠️ 核心步骤：从创建到赋予人格

1. 创建Agent并分配工作空间

使用 openclaw agents add 命令来创建新Agent。关键在于通过 --workspace 参数为每个Agent指定一个独立的目录，这是实现它们之间"物理隔离"的基础。

# 创建一个负责创意的Agent
openclaw agents add brainstorm \
  --model zai/glm-4.5-air \
  --workspace ~/.openclaw/workspace-brainstorm

# 创建一个负责写作的Agent
openclaw agents add writer \
  --model deepseek-chat \
  --workspace ~/.openclaw/workspace-writer

# 创建一个负责任务调度的主Agent
openclaw agents add coordinator \
  --model zai/glm-4.5-air \
  --workspace ~/.openclaw/workspace-coordinator

• 命令中的 --model 、--workspace 参数是可选的，你可以根据任务特点为不同Agent配置最合适的大模型以及工作空间。

  openclaw agents add <agent-name>
  
  # 验证
  openclaw agents list --bindings
  

2. 设置身份标识

为了让Agent在交互界面中更容易被识别，可以通过以下命令为它们设置显示名称和表情符号：

openclaw agents set-identity --agent brainstorm --name "脑暴搭子" --emoji "💡"
openclaw agents set-identity --agent writer --name "写作助手" --emoji "✍️"
openclaw agents set-identity --agent coordinator --name "协调官" --emoji "🎯"

3. 赋予Agent"灵魂"：编写SOUL.md

这是最关键的一步。进入每个Agent独立的 workspace 目录，创建并编辑 SOUL.md 文件。这个文件定义了Agent的性格、职责和行为准则，是决定Agent是否好用的核心。

脑暴搭子 (~/.openclaw/workspace-brainstorm/SOUL.md)

# SOUL.md - 脑暴搭子

## 角色定位
你是用户的创意伙伴，擅长发散思维，而不是直接给答案。

## 思维方式
- **先扩散，再收敛**：面对问题，优先给出3-5个不同方向的思路。
- **多提问题**：如果需求不清晰，通过提问来帮助用户理清思路。
- **鼓励反直觉**：敢于提出跨领域的、反常规的想法，激发灵感。

写作助手 (~/.openclaw/workspace-writer/SOUL.md)

# SOUL.md - 写作助手

## 角色定位
你是一名资深的公众号文章写手，擅长将复杂概念用通俗易懂的语言表达。

## 写作风格
- **开头抓人**：用一个小故事或反直觉的观点开头。
- **段落短小**：确保手机阅读体验流畅。
- **善用类比**：用生活中的例子解释专业概念。
- **结尾有力**：结尾要有明确的行动号召或总结。

协调官 (~/.openclaw/workspace-coordinator/SOUL.md)

# SOUL.md - 协调官

## 角色定位
你是AI团队的"项目经理"，负责接单、派单和质量把控，不直接执行具体任务。

## 调度规则
- **创意需求** (如"想几个点子") → 交给 @脑暴搭子
- **写作任务** (如"写一篇文章") → 交给 @写作助手
- **简单问答** (如"今天天气") → 自己回答

💡 进阶技巧：让Agent们协同工作

创建好Agent只是第一步。想让它们像一个真正的团队一样协作，还需要进行一些配置。

1. 开启会话可见性：这是Agent间协作的基础。需要在主配置文件 ~/.openclaw/openclaw.json 中修改，让它们能"看见"彼此：

   {
     "tools": {
       // 关键配置：允许所有会话互相可见
       "sessions": {
         "visibility": "all"
       }
     }
   }
   

2. 配置Agent间通信：在同一个配置文件中，添加以下内容来开启并授权Agent间的相互通信能力：

   {
     "tools": {
       // 开启通信功能，明确允许通信的Agent
       "agentToAgent": {
         "enabled": true,  
         "allow": ["coordinator", "brainstorm", "writer"] 
       }
     }
   }
   

完成以上步骤后，你就可以在 coordinator 的聊天窗口中输入类似"帮我策划并写一篇关于人工智能的科普文章"，然后观察它如何自动调度 brainstorm 和 writer 来协同完成工作了。

📝 帮你理一理

简单总结一下创建和管理多Agent的常用命令：

创建完这些各具特色的Agent后，你打算怎么用它们？比如写周报、做翻译还是处理邮件？告诉我你的具体场景，我可以帮你针对性地优化它们的 SOUL.md 人格设定。

频道多账户

飞书

使用 多 Agent 创建agent。

{
  "agents": {
    // agent 列表
    "list": [
      {
        "id": "main"
      },
      {
        "id": "web-search",
        "name": "web-search",
        "workspace": "/home/enlin/.openclaw/workspace-web-search",
        "agentDir": "/home/enlin/.openclaw/agents/web-search/agent"
      },
      {
        "id": "doc-helper",
        "name": "doc-helper",
        "workspace": "/home/enlin/.openclaw/workspace-doc-helper",
        "agentDir": "/home/enlin/.openclaw/agents/doc-helper/agent"
      },
      {
        "id": "openclaw-helper",
        "name": "openclaw-helper",
        "workspace": "/home/enlin/.openclaw/workspace-openclaw-helper",
        "agentDir": "/home/enlin/.openclaw/agents/openclaw-helper/agent"
      }
    ]
  },
  "tools": {
    "profile": "full",
    "sessions": {
      "visibility": "all"
    },
    "agentToAgent": {
      "enabled": true
    }
  },
  // agents 与 channels 的绑定
  // https://docs.openclaw.ai/zh-CN/concepts/multi-agent
  "bindings": [
    {
      "type": "route",
      "agentId": "main",
      "match": {
        "channel": "feishu",
        "accountId": "main"
      }
    },
    {
      "type": "route",
      "agentId": "web-search",
      "match": {
        "channel": "feishu",
        "accountId": "web"
      }
    }
  ],
  "session": {
    // https://docs.openclaw.ai/zh-CN/concepts/session
    "dmScope": "per-channel-peer"
  },
  "channels": {
    // https://docs.openclaw.ai/zh-CN/channels/feishu
    "feishu": {
      "enabled": true,
      "domain": "feishu",
      // 出站未显式指定 accountId 时使用的账号
      "defaultAccount": "main",
      "accounts": {
        // 自定义飞书账户id,每一个id对应一个飞书机器人配置
        "main": {
          "appId": "cli_a928711055799bb6",
          "appSecret": "fF2jp5akpN4qmsfj5jyFjgd34qebb6bg",
          "domain": "feishu"
        },
        "web": {
          "appId": "cli_a938cbfbebb99cc9",
          "appSecret": "ugOdnqAc24ECigHf38oKsa3GIwfDZKIq",
          "domain": "feishu"
        }
      },
      "groupPolicy": "open",
      "streaming": true
    }
  }
}

session

问：1. session.identityLinks 怎么使用？ 2. 如果我是同一个用户的同一个渠道的多个账户 配置哪一个比较合适

答：我们来详细解答您关于OpenClaw会话管理的两个问题。

1. session.identityLinks 怎么使用？

session.identityLinks 的核心作用是将同一个自然人在不同聊天渠道上的多个账号ID“链接”起来，让AI代理识别出这是同一个人，从而为他们提供跨渠道的连续对话体验。

通俗解释：
假设用户“爱丽丝”既通过Telegram也与您对话，也通过Discord与您对话。如果不做任何设置，在per-channel-peer模式下，AI代理会认为这是两个完全不同的用户，会创建两个独立的会话。爱丽丝在Telegram上聊完天，转到Discord上继续说，AI就会“失忆”，不记得之前的聊天内容。
而session.identityLinks就是用来解决这个问题的。您可以在配置文件中告诉OpenClaw：“Telegram上的账号123和Discord上的账号987，其实都是同一个人‘爱丽丝’。” 这样，无论爱丽丝从哪个渠道发消息来，AI都能认出她，并沿用同一个对话历史。

具体配置步骤：

1. 前提条件：session.dmScope 必须设置为 per-peer、per-channel-peer 或 per-account-channel-peer 中的任意一个，因为identityLinks在这些模式下才会生效。

2. 找到用户的“带提供商前缀的对等 ID”：您需要先获取用户在各个平台上的唯一ID。这个ID的格式通常是 提供商:用户ID。

   • 例如，Telegram用户ID 123456789 会表示为 telegram:123456789。
   • Discord用户ID 987654321012345678 会表示为 discord:987654321012345678。

3. 编辑OpenClaw配置文件：打开 ~/.openclaw/openclaw.json 文件，在 session 节点下添加 identityLinks 字段。

4. 创建映射关系：在 identityLinks 对象中，您需要定义一个“规范身份”（即您给这个用户起的内部名字），然后将该用户在各个平台上的ID（带前缀的格式）以数组形式列出。

配置示例：

{
  "session": {
    // 必须设置为非main的值
    "dmScope": "per-channel-peer",
    // 定义身份链接
    "identityLinks": {
      // 规范身份 "alice" 对应两个平台的ID
      "alice": [
        "telegram:123456789",
        "discord:987654321012345678",
        "feishu:ou_xxxxxxxxxxxxxxxxxxx"
      ],
      // 规范身份 "bob" 只对应一个平台ID，但也可以这样定义，方便管理
      "bob": [
        "whatsapp:+15551234567"
      ]
    }
  }
}

在这个例子之后，当ID为 telegram:123456789 或 discord:987654321012345678 的用户发来消息时，OpenClaw都会将其路由到以 alice 为标识的同一个会话中。

2. “同一个用户的同一个渠道的多个账户” 配置哪一个比较合适？

您提到的场景“同一个用户的同一个渠道的多个账户”，通常指的是同一个用户在不同平台上的账号（如一个用户在Telegram和Discord上都有账号），但您的描述强调了“同一个渠道”，所以更可能指的是您自己（作为服务提供方）在同一个聊天渠道（如WhatsApp）上配置了多个不同的号码或账户，而同一个用户可能通过不同的号码与您联系。或者是指同一个用户本身在同一个渠道有多个账号。

针对这两种可能性，我们分别来看：

场景A：您（服务提供方）在同一个渠道有多个账户

这是最常见的情况。例如，您为了业务需要，在WhatsApp上注册了两个号码：一个用于个人(personal)，一个用于商务(biz)。同一个用户“爱丽丝”可能有时通过您的个人号码与您聊天，有时通过您的商务号码与您聊天。

推荐配置：per-account-channel-peer

• 为什么？
  • 精确隔离：这个模式会按 账户(accountId) + 渠道(channel) + 发送者(peer) 来创建会话键。这意味着，即使用户是同一个人（爱丽丝），但因为她通过您不同的业务账户（personal vs biz）联系您，OpenClaw会创建两个独立的会话。
  • 符合逻辑：在大多数业务场景下，通过您不同业务号码进来的对话，其意图和上下文应该是隔离的。比如，通过商务号码聊的是工作订单，通过个人号码聊的是私人朋友寒暄，两者不应该混淆。per-account-channel-peer 正好满足了这种隔离需求。
  • 官方推荐：OpenClaw官方文档明确指出，对于“同一渠道上的多账户收件箱”，首选 (prefer) per-account-channel-peer。

场景B：用户（单个自然人）在同一个渠道有多个账号

这是另一种可能性，但相对少见。例如，同一个用户“爱丽丝”在Telegram上有两个账号（一个工作号、一个私人号），并用这两个账号分别与您的代理聊天。

• 分析：这种情况下，虽然背后是同一个人，但在OpenClaw看来，这是两个完全不同的发送者ID（peerId）。如果您希望将这两个账号的对话合并，让代理认出是同一个“爱丽丝”，可以使用 identityLinks。
• 推荐配置：
  1. 将 dmScope 设置为 per-peer 或 per-channel-peer。
  2. 在 identityLinks 中，将爱丽丝的两个Telegram账号ID（如 telegram:工作号ID 和 telegram:私人号ID）映射到同一个规范身份（如 alice）。

总结建议

希望以上解释和配置建议能帮助您更好地理解和使用OpenClaw的会话管理功能。如果您在配置过程中遇到其他具体问题，随时可以再问我。

安全

网关

官网：网关安全性 - OpenClaw

定期运行此命令（尤其是在更改配置或暴露网络接口之后）：

openclaw security audit
openclaw security audit --deep
openclaw security audit --fix

它会标记常见的安全隐患（Gateway 网关认证暴露、浏览器控制暴露、提权白名单、文件系统权限）。--fix 会应用安全防护措施：

• 将常见渠道的 groupPolicy="open" 收紧为 groupPolicy="allowlist"（以及单账户变体）。
• 将 logging.redactSensitive="off" 恢复为 "tools"。
• 收紧本地权限（~/.openclaw → 700，配置文件 → 600，以及常见状态文件如 credentials/*.json、agents/*/agent/auth-profiles.json 和 agents/*/sessions/sessions.json）。

在你的机器上运行具有 shell 访问权限的 AI 智能体是……有风险的。

网络暴露（绑定 + 端口 + 防火墙）

Gateway 网关在单个端口上复用 WebSocket + HTTP：

• 默认：18789
• 配置/标志/环境变量：gateway.port、--port、OPENCLAW_GATEWAY_PORT

绑定模式控制 Gateway 网关在哪里监听：

• gateway.bind: "loopback"（默认）：只有本地客户端可以连接。
• 非回环绑定（"lan"、"tailnet"、"custom"）扩大了攻击面。只有在使用共享令牌/密码和真正的防火墙时才使用它们。

经验法则：

• 优先使用 Tailscale Serve 而不是局域网绑定（Serve 保持 Gateway 网关在回环上，Tailscale 处理访问）。
• 如果你必须绑定到局域网，将端口防火墙到严格的源 IP 白名单；不要广泛地进行端口转发。
• 永远不要在 0.0.0.0 上暴露未经认证的 Gateway 网关。

远程网关

官网：远程 Gateway 网关设置 - OpenClaw