拾忆🍂

外观

OpenClaw

约 15409 字大约 51 分钟

2026-02-25

一、安装

注意

Node Version >= 22

Windwos & Linux & macOS:

npm install -g openclaw@latest
对于 报错 llama-cpp 报错的

安装 Visual Studio 2022 构建工具

  1. 下载 Visual Studio 2022 Build Tools
  2. 运行安装程序，在"工作负载"中勾选：
    • ✅ 使用 C++ 的桌面开发
    • ✅ Windows 10/11 SDK (会自动包含)
  3. 在"单个组件"中确保勾选：
    • ✅ CMake 工具
    • ✅ MSVC v143 - VS 2022 C++ x64/x86 构建工具
对于 git 报错的

官网：openclaw-cn 社区

# 安装
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

重要

这一步执行完了，打开Web端之后，不管配不配频道，先按照 这里 修改修改配置，以开启 OpenClaw 读写文件 的能力。

这一步执行完了，打开Web端之后，不管配不配频道，先按照 这里 修改修改配置，以开启 OpenClaw 读写文件 的能力。

这一步执行完了，打开Web端之后，不管配不配频道，先按照 这里 修改修改配置，以开启 OpenClaw 读写文件 的能力。

提示什么协议，键入 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。

向导文档：向导

提示

如果你在新手引导期间安装了服务，Gateway 网关应该已经在运行，然后提示是否开启 Web UI 或者 TUI。

  • 通过 openclaw gateway status 查看运行状态。

在 agents.defaults.workspace 内，OpenClaw 有以下用户可编辑的文件：

  • AGENTS.md — 操作指令 + “记忆”
  • SOUL.md — 人设、边界、语气
  • TOOLS.md — 用户维护的工具说明（例如 imsg、sag、约定）
  • BOOTSTRAP.md — 一次性首次运行仪式（完成后删除）
  • IDENTITY.md — 智能体名称/风格/表情
  • USER.md — 用户档案 + 偏好称呼

在新会话的第一轮，OpenClaw 将这些文件的内容直接注入智能体上下文。空文件会被跳过。大文件会被修剪和截断并添加标记，以保持提示词精简（阅读文件获取完整内容）。如果文件缺失，OpenClaw 会注入一行”文件缺失”标记（openclaw setup 将创建安全的默认模板）。BOOTSTRAP.md 仅在全新工作区（没有其他引导文件存在）时创建。如果你在完成仪式后删除它，后续重启不应重新创建。要完全禁用引导文件创建（用于预置工作区），请设置：

{ 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 (钉钉)

重要

机器人发布之后搜索不到，一定要应用也发布之后才可以。

参考：

A 通过 npm 包安装 (推荐)

注意

如果nvm安装路径包含空格，则使用此方式会报错。推荐使用本地源码方式安装。

手动通过 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 .

配置

注意

重新使用 交互式配置 之后，就可以替换已经绑定的dingtalk配置。

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

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

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

重要

这是一条安全告警（不是安装失败），建议显式写入你信任的插件 id。

  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

提示

如果你之前已经配置过 plugins.allow，但没有 dingtalk，那么插件不会被加载。请把 dingtalk 加入该列表。

A 交互式配置（推荐）

重要

SSS “钉钉官方” 插件只能使用 SSS-手动配置文件 。

使用 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。


钉钉开发者平台配置指南
1. 创建钉钉应用
  1. 访问 钉钉开发者后台
  2. 进入 应用开发 → 企业内部开发 → 创建应用
  3. 添加「机器人」能力
  4. 打开机器人配置开关，填写必要信息后，最底部消息接收模式配置为 Stream 模式
  5. 发布应用，记录 clientId 和 clientSecret

2. 配置权限管理
  1. 进入应用 → 权限管理
  2. 搜索「Card」相关权限
    • ✅ Card.Instance.Write：和投放互动卡片实例
    • ✅ Card.Streaming.Write：AI卡片流式更新权限
    • （默认已选择）qyapi_robot_sendmsg：主动发送消息
    • 如需使用文档 API 功能，还需开通文档相关权限
  3. 勾选上述两个权限
  4. 保存权限配置

3. 建立卡片模板(可选)

步骤：

  1. 访问 钉钉卡片平台
  2. 进入「我的模板」
  3. 点击「创建模板」
  4. 卡片模板场景选择 「AI 卡片」
  5. 按需设计卡片排版,点击保存并发布
  6. 记下模板中定义的内容字段名称
  7. 复制模板 ID（格式如：xxxxx-xxxxx-xxxxx.schema）
  8. 将 templateId 配置到 openclaw.json 的 cardTemplateId 字段
  9. 或在OpenClaw控制台的Channel标签->Dingtalk配置面板-> Card Template Id填入
  10. 将记下的内容字段变量名配置到 openclaw.json 的 cardTemplateKey 字段
  11. 或在OpenClaw控制台的Channel标签->Dingtalk配置面板-> Card Template Key填入

说明：

  • 使用 DingTalk 官方 AI 卡片模板时，cardTemplateKey 默认为 'msgContent'，无需修改
  • 如果您创建自定义卡片模板，需要确保模板中包含相应的内容字段，并将 cardTemplateKey 配置为该字段名称

4. 获取凭证

从开发者后台获取：

  • Client ID (AppKey)
  • Client Secret (AppSecret)
  • Robot Code (与 Client ID 相同)
  • Corp ID (企业 ID)
  • Agent ID (应用 ID)

B 手动配置文件

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

提示

至少包含 plugins.allow 和 channels.dingtalk 两部分，内容参考上文钉钉开发者配置指南。

{
  "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

重要

使用交互式配置时，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
        }
      }
    }
  }
}
配置项环境变量说明
clientIdDINGTALK_CLIENT_ID钉钉 AppKey
clientSecretDINGTALK_CLIENT_SECRET钉钉 AppSecret
gatewayTokenOPENCLAW_GATEWAY_TOKENGateway 认证 token, openclaw.json配置中 gateway.auth.token 的值
gatewayPassword—可选：Gateway 认证 password（与 token 二选一）
sessionTimeout—可选：会话超时(ms)，默认 1800000 = 30分钟；
asyncMode—可选：异步模式，立即回执用户消息，后台处理并推送结果（默认：false）
ackText—可选：异步模式下的回执消息文本（默认：'🫡 任务已接收，处理中...'）

最后重启 Gateway

重要

使用交互式配置时，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 修改配置（推荐）

注意

openclaw2026.3.7 版本的首次安装不适用此方法！

  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 & B 方法安装之后，日志会一直提示检测到 重复 的 feishu 插件：/node_modules/openclaw/extensions/feishu/index.ts（官方自带的feishu插件文件夹）。重复的插件位置在 ~/.openclaw/openclaw.json 文件内 plugins.installs.feishu 键值对中，根据以下两种不同方法，键值对的值为：

  • A 方法 会在 ~/.openclaw/extensions/ 文件夹内下载一个 feishu 插件，表现为文件夹。值为 该文件夹绝对路径。
  • B 方法 值为 本地源码的 feishu 文件夹绝对路径。

这样即使 配对授权 之后，用户再次发送消息之后依然提示要求配对。只要删掉 plugins.installs.feishu 之后插件才可以正常使用，所以猜测由于官方插件库包含feishu并且已经在 node_modules 中存在，其实只差了在 plugins 中启用 feishu 而已。经测试，正是如此。所以推荐使用上面的修改配置方法。


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 .
或者

本地 checkout（在 openclaw 的 本地仓库内运行）：

openclaw plugins install ./extensions/feishu

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


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

openclaw plugins install @larksuiteoapi/feishu-openclaw-plugin

重要

上一条成功之后，openclaw 2026.3.7 版本及之前必须要执行这条（否则日志会报错）

npm install -g @larksuiteoapi/node-sdk

提示

一些命令，详情查看npm仓库中的README.md文件。直接从飞书APP聊天框中发出：

  1. /feishu start：确认是否安装成功；返回了版本号，则代表成功
  2. /feishu doctor：可检查配置是否正常
  3. /feishu auth：可批量授权用户权限
  4. /feishu help：显示此帮助

配置

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

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

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

重要

这是一条安全告警（不是安装失败），建议显式写入你信任的插件 id。

  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

提示

如果你之前已经配置过 plugins.allow，但没有 feishu，那么插件不会被加载。请把 feishu 加入该列表。

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 2026.3.8 版本有了一个新BUG：

使用“飞书官方”版（SSS）插件时，在配置了 APP ID 和 APP Secret 之后，系统会自动启用自带的 feishu 插件，需要 手动禁用 一下。否则使用 /feishu auth 获取授权命令报错：❌ 无法获取用户身份，请在飞书对话中使用此命令

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"

Lark（国际版）域名

如果您的租户在 Lark（国际版），请设置域名为 lark（或完整域名），可配置 channels.feishu.domain 或 channels.feishu.accounts.<id>.domain：

{
  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 <配对码>

批准后即可正常对话。

提示

查看配对请求列表，其中包含用户的 Open ID：

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
插件相关配置（如果需要）
~/.openclaw/openclaw.json
"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 install 安装的版本。

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输出为 折叠/展开视图 。

开机自启

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

# 停止服务
openclaw gateway stop

# 启动服务
openclaw gateway start

# 重启服务
openclaw gateway restart

访问

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

局域网

注意

目前不使用，因为不管怎么配置，局域网内不允许 http 请求。

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
}

配置

提示

配置文件都在：~/.openclaw/openclaw.json

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

在CLI中重新配置 openclaw onboard 中的某些部分，也可以使用：

openclaw configure
# 或 2026.3.2 版本之后
openclaw config

配置的查看和设置可以使用命令：

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

注意

官网：工具 - OpenClaw

所有新安装好的机器，都应该更改配置文件中的 tools.profile = full 。其余两个属性可以不用管。

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

重新配置

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

笔记

保留记忆？

备份一下 ~/.openclaw/workspace 文件夹，之后再覆盖回来？还没试过。

工具使用权限-(重要)

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 并读不到，所以这里提供三种系统的自启应用也能读到环境变量的配置方法。

重要

Windows直接在系统环境变量里设置即可，如果 linux/macOS 想使用简单的方法（下面的方法太复杂），这里官方提供了一种应用级环境变量用法：

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

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

系统环境变量 GUI：

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

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

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

PowerShell：

# 设置用户环境变量（重启后生效）
[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 set-environment当前 session❌ 重启失效中
~/.config/systemd/user.conf当前用户✅ 永久生效低
/etc/systemd/user.conf所有用户✅ 永久生效最低
服务文件中的 Environment=特定服务✅ 永久生效最高

跨频道发送消息

问：如何从 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

提示

官方支持的 skills 管理工具包。

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"

命令

我目前支持这些命令：

会话管理

  • /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直接去“系统环境变量”里配置。

不需要 clawhub 验证的一次性使用方法（不推荐）

注意

不推荐！不是官方工具，且只能安装到公共skills目录（ ~/.openclaw/skills/ ），多agent情况下不能指定 workspace 位置。

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>

注意

大多数api厂商的coding plan和预付费是api的 baseURL 不同：

  • openclaw onboard 中模型列表中基本默认都是各家 coding plan 的 baseURL。
  • 预付费api一般都是选择 兼容OpenAI格式 的选项，手动配置 baseURL 和 模型名称（model ID）。

以 MiniMax 为例：

场景一：如果你订阅了 Coding Plan

{
  "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" 
  }
}

场景二：如果你使用普通按量付费 API Key

{
  "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" 
  }
}

命令

提示

在终端输入 openclaw tui ，进入 TUI 界面，使用以下命令。

/commands：

ℹ️ 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 字段为目标模型。请参考 修改配置文件 。

{
    "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

参考：

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

重要

注：contextWindow 和 maxTokens 默认都是 4096，OpenClaw 要求 contextWindow 至少 16000 。记得手动修改！

笔记

这是我自己的配置好之后的效果：

{
    "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的常用命令：

操作目的命令示例说明
创建新Agentopenclaw agents add [name]基础创建命令。
指定工作空间openclaw agents add [name] --workspace [path]强烈推荐，实现数据隔离的关键。
指定模型openclaw agents add [name] --model [model-id]让不同Agent使用不同模型。
设置身份openclaw agents set-identity --agent [name] --name "[昵称]" --emoji "[表情]"让Agent在界面上更好认。
查看所有Agentopenclaw agents list验证创建结果。
编辑Agent灵魂vim ~/.openclaw/workspace-[name]/SOUL.md核心步骤，用编辑器编写个性化人格。

创建完这些各具特色的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）。

总结建议

您的场景推荐配置理由
您有多个业务账户 (如两个WhatsApp号)per-account-channel-peer严格隔离不同业务账户下的对话，防止上下文混淆。这是官方推荐方案。
用户有多个账号 (如两个Telegram号)per-channel-peer + identityLinks首先按渠道和发送者隔离，再通过identityLinks将同一个人的多个ID“链接”起来，实现跨账号的连续对话。

希望以上解释和配置建议能帮助您更好地理解和使用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

「 Enlin的文档♪(^∇^*) - 使用 VuePress 构建🥳 」