OpenClaw 钉钉机器人配置指南（macOS）

第一步：安装 Node.js

OpenClaw 需要 Node.js 22 或更高版本。推荐使用 nvm 安装：

安装 nvm

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash
source ~/.zshrc

安装 Node.js LTS 版本

nvm install 22
node -v # 验证

第二步：安装 OpenClaw

使用 npm 全局安装：

npm install -g openclaw@latest

如果网络慢，可先配置国内镜像源：

npm config set registry https://registry.npmmirror.com

第三步：运行配置向导（onboard）

执行初始化向导，建议选择 Manual 模式，以便后续手动控制：

openclaw onboard --install-daemon

在向导中：

确认个人使用提示 → Yes
选择 Manual 模式
选择 Local gateway（本机）
接受默认工作空间路径
模型提供商：选择 Qwen（通义千问），并完成 OAuth 或输入 API Key
默认模型：保持 qwen-portal/coder-model
网关端口：默认 18789
网关绑定：Loopback (127.0.0.1)（仅本机访问）
网关认证：Token（自动生成）
配置聊天频道：选择 No（稍后手动配置钉钉）
配置技能：选择 No（稍后根据需要安装）
启用钩子：选择 Skip for now
网关服务已安装：选择 Restart
孵化机器人：选择 Do this later（稍后可通过 openclaw dashboard 或 openclaw tui 启动）

完成后，OpenClaw 核心服务已运行。

第四步：安装钉钉插件

使用官方推荐的钉钉插件包（由社区维护）：

openclaw plugins install @soimy/dingtalk

如果遇到权限错误（EACCES），修复 npm 缓存所有权：

sudo chown -R 501:20 ~/.npm

如果安装过程中依赖安装失败（如 dingtalk-stream 缺失），可手动进入插件目录安装：

cd ~/.openclaw/extensions/dingtalk
npm install

第五步：将钉钉插件加入信任白名单

编辑配置文件 ~/.openclaw/openclaw.json，在 plugins 部分添加：

{
  "plugins": {
    "allow": ["dingtalk"]
  }
}

或者通过命令设置：

openclaw config set plugins.allow '["dingtalk"]'

第六步：配置钉钉频道认证信息

在 ~/.openclaw/openclaw.json 中添加 channels 部分：

{
  "channels": {
    "dingtalk": {
      "enabled": true,
      "clientId": "你的钉钉 AppKey",
      "clientSecret": "你的钉钉 AppSecret"
    }
  }
}

注意：确保 JSON 格式正确，使用英文双引号，无多余逗号。避免使用中文标点导致解析错误。

第七步：重启网关

openclaw gateway restart

第八步：验证钉钉频道状态

openclaw channels list

应显示 DingTalk default: configured, enabled。

第九步：测试钉钉机器人

在钉钉中向机器人发送消息（例如'你好'），同时观察日志：

openclaw logs --follow

如能收到回复，说明配置成功。

第十步（可选）：安装文件管理/浏览器自动化技能

如果你需要让 AI 读写文件或操作网页，可以安装相关技能（以浏览器自动化为首）：

搜索可用的技能

openclaw plugins search agent-browser

安装（例如 @openclaw/agent-browser，实际包名以搜索结果为准）

openclaw plugins install @openclaw/agent-browser

安装后重启网关，即可在钉钉中指令 AI 执行文件读取、网页抓取等任务。

常见问题及解决方案

以下是在安装和配置过程中可能遇到的典型问题及处理方法，供你日后排查参考：

错误现象	可能原因	解决方法
zsh: command not found: node	Node.js 未安装	安装 Node.js（见第一步）
EACCES: permission denied	npm 缓存文件权限问题	sudo chown -R 501:20 ~/.npm
JSON5 parse failed: invalid character '，'	配置文件中混入了中文标点	用英文标点替换，如，→ ,，' → "
unknown channel id: dingtalk	钉钉插件未安装或未加载	安装 @soimy/dingtalk，并加入 plugins.allow，重启网关
Cannot find module 'dingtalk-stream'	插件依赖未自动安装	cd ~/.openclaw/extensions/dingtalk && npm install
duplicate plugin id detected	插件文件夹有多个副本或配置重复	检查 ~/.openclaw/extensions/，只保留一个 feishu 或 dingtalk 文件夹；同时检查配置文件中 plugins.entries 是否有重复条目
plugins.allow is empty 警告	未设置插件白名单	设置 plugins.allow 为 ["dingtalk", "其他插件 ID"]
Package not found on npm: @soimy/xxx	插件包名不存在或错误	查阅官方插件文档获取正确包名，或尝试搜索 openclaw plugins search <关键词>
openclaw skills install file-manager 报错	skills 命令用法错误或技能不存在	技能通常通过插件安装，应使用 openclaw plugins install；如需文件操作，可安装浏览器自动化插件或创建自定义技能
钉钉机器人无响应	钉钉后台未发布应用、事件订阅未配置或 Stream 模式未选	登录钉钉开发者后台，确认已添加 im.message.receive_v1 事件，选择'使用长连接接收事件'，并发布最新版本
网关启动超时（port 18789 free）	配置文件错误（如未知频道 ID）或插件加载卡死	运行 openclaw doctor --fix 尝试修复，或检查日志 openclaw logs --follow 定位具体错误

补充建议

备份配置文件：在修改前建议备份 ~/.openclaw/openclaw.json。
善用 openclaw doctor：遇到问题先运行此命令，它会给出许多有用的修复建议。
飞书插件 vs 钉钉插件：虽然飞书插件（feishu）能安装，但钉钉机器人必须使用 @soimy/dingtalk，频道 ID 是 dingtalk。
安全第一：对于高危操作（如文件读写、命令执行），ClawBands 会请求授权，请确认后批准。