Mac 本地部署 OpenClaw从零到钉钉机器人完整部署（2026最新）

适用：Apple Silicon（ARM）macOS 12+（Monterey 及以上）

目标：本地跑通 Ollama（qwen3:8b）+ OpenClaw 网关 + 钉钉机器人私聊/群聊@回复，全程 ARM 原生适配、国内镜像加速，无 Intel 兼容坑，所有命令可直接复制执行。

一、安装 Homebrew（M 系列专属路径 /opt/homebrew）

1.1 安装 Xcode 命令行工具（必须前置步骤）

bash
xcode-select --install

执行命令后，弹出系统安装窗口，点击「安装」，等待安装完成（无需手动操作，全程自动）。若弹出“已安装”提示，直接跳过此步骤，进入下一步。

1.2 国内镜像安装 Homebrew（推荐，解决官方源下载慢问题）

bash
/bin/zsh -c "$(curl -fsSL https://gitee.com/cunkai/HomebrewCN/raw/master/Homebrew.sh)"

执行后按以下提示操作：

• 出现镜像列表时，输入「2」选择清华源，或输入「5」选择阿里源（两者均可，优先选阿里源，适配国内网络）；

• 提示输入开机密码时，直接输入（输入过程中无字符回显，属于正常现象），输入完成后回车；

• 安装完成后，会提示一条「source」开头的命令（如 source ~/.zshrc 或 source ~/.bash_profile），复制该命令并执行，确保 Homebrew 生效；

• 若执行过程中提示“权限不足”，无需修改权限，按终端提示输入「y」确认继续即可。

1.3 验证 Homebrew 安装成功

bash
brew --version
which brew

正确输出：前者显示 Homebrew 版本号，后者显示路径为 /opt/homebrew/bin/brew（M 系列专属正确路径，若显示其他路径则安装异常）。若提示“command not found”，重新执行步骤 1.2 末尾的「source」命令即可。

二、安装 Node.js 22.x（ARM 原生）+ Git

2.1 一键安装 Node.js 22.x 和 Git

bash
brew install node@22 git

等待安装完成，全程自动，无需手动干预。若提示“已安装其他版本 Node.js”，按终端提示输入「y」确认覆盖安装，或执行 brew uninstall node 卸载旧版本后再重新安装。

2.2 配置环境变量（M 系列必须操作，否则 Node 无法全局使用）

bash
echo 'export PATH="/opt/homebrew/opt/node@22/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

两条命令依次执行，执行完成后环境变量立即生效。若你的终端是 bash 模式（而非 zsh），将命令中的 ~/.zshrc 替换为 ~/.bash_profile 再执行。

2.3 验证安装成功

bash
node -v
npm -v
git --version

正确输出：三条命令均显示对应版本号，无报错（Node 版本需为 22.x 系列，否则后续 OpenClaw 可能报错）。若 Node 版本不符，重新执行步骤 2.1 安装。

2.4 配置 npm 国内镜像（必做，避免 OpenClaw 安装超时）

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

执行后无需验证，直接进入下一步即可。若后续安装插件仍超时，可再次执行该命令，确保镜像配置生效。

三、安装 Ollama + qwen3:8b（本地大模型，钉钉机器人调用的核心）

3.1 安装 Ollama（ARM 原生版本，适配 M 系列芯片）

bash
curl https://ollama.com/install.sh | sh

一键安装，全程自动，安装完成后 Ollama 会自动注册为系统服务。若提示“权限不足”，在命令前添加 sudo（即 sudo curl https://ollama.com/install.sh | sh），输入开机密码后继续。

3.2 下载并后台启动 qwen3:8b 模型

bash
ollama run qwen3:8b

补充说明：

• 首次执行会自动下载 qwen3:8b 模型，大小约 5-10GB，下载速度取决于网络，不要中断下载；

• 命令末尾的「&」表示后台运行，不会占用终端，关闭终端后模型仍会常驻后台；

• 下载完成后，会自动启动模型，无需额外执行启动命令；

• 若下载中断，重新执行该命令即可继续下载，无需重新下载全部内容；

• 若提示“模型不存在”，执行 ollama pull qwen3:8b 手动下载，下载完成后再执行 ollama run qwen3:8b &。

3.3 验证模型安装并启动成功

bash
ollama ps

正确输出：显示 qwen3:8b 相关进程信息（包括进程 ID、启动时间），说明模型正常运行。若显示“no running models”，重新执行步骤 3.2 启动模型即可。

四、安装 OpenClaw（AI 网关，对接钉钉与 Ollama，重点：每一步精确到选择/输入）

4.1 官方一键安装 OpenClaw

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

等待安装完成，出现「Installed successfully」提示，即为安装成功，无需手动操作。若安装超时，检查 npm 国内镜像是否配置（步骤 2.4），或切换网络后重新执行。

4.2 初始化配置向导（onboard）—— 严格按以下步骤操作，每一步均明确选择/输入

首先执行初始化命令（新手直接复制粘贴到终端，按回车键执行即可）：

bash
openclaw onboard

执行后，终端会依次出现以下屏幕提示，新手无需理解含义，严格按照下面每一步“屏幕显示+操作”执行，全程不跳步、不修改，每一步操作后均按回车键确认，100%能走完，具体步骤如下：

【第 1 步】安全提示

终端屏幕显示：

plaintext
◇ I understand this is personal-by-default... Continue?
│ Yes

你的操作：选中 Yes，按回车键确认。

【第 2 步】选择配置模式

终端屏幕显示：

plaintext
◇ Setup mode
│ QuickStart (recommended)

你的操作：直接按回车键（默认选中推荐的 QuickStart）。

【第 3 步】检测到现有配置

终端屏幕显示：

plaintext
◇ Config handling
│ Keep current values

你的操作：直接按回车键（默认保留当前配置）。

【第 4 步】QuickStart 确认

终端屏幕显示：

plaintext
◇ QuickStart

你的操作：直接按回车键确认。

【第 5 步】模型/认证提供商（关键第一步）

终端屏幕显示：

plaintext
◇ Model/auth provider
│ More…

你的操作：选中 More…，按回车键确认。

【第 6 步】模型/认证提供商（关键第二步）

终端屏幕显示：

plaintext
◇ Model/auth provider
│ Custom Provider

你的操作：选中 Custom Provider，按回车键确认。

【第 7 步】API Base URL（最重要！必须带 /v1）

终端屏幕显示：

plaintext
◇ API Base URL
│ http://localhost:11434

你的操作：将默认地址修改为 http://localhost:11434/v1，输入完成后按回车键确认（✅ 必须带 /v1，否则无法对接模型）。

【第 8 步】如何提供 API Key

终端屏幕显示：

plaintext
◇ How do you want to provide this API key?
│ Paste API key now

你的操作：直接按回车键（默认选中 Paste API key now）。

【第 9 步】API Key（无需填写）

终端屏幕显示：

plaintext
◇ API Key (leave blank if not required)

你的操作：什么都不输入，直接按回车键。

【第 10 步】接口兼容模式

终端屏幕显示：

plaintext
◇ Endpoint compatibility
│ OpenAI-compatible

你的操作：直接按回车键（默认选中 OpenAI-compatible，无需修改）。

【第 11 步】模型 ID（必须正确）

终端屏幕显示：

plaintext
◇ Model ID

你的操作：输入 qwen3:8b（全部小写，无空格、无多余字符），输入完成后按回车键确认。

【第 12 步】启用钩子？

终端屏幕显示：

plaintext
◇ Enable hooks?
│ Skip for now

你的操作：直接按回车键（默认跳过，新手无需启用）。

【第 13 步】网关服务已安装

终端屏幕显示：

plaintext
◇ Gateway service already installed?
│ Restart

你的操作：直接按回车键（默认重启网关，确保配置生效）。

【第 14 步】网关端口

终端屏幕显示：

plaintext
◇ Gateway port [18789]

你的操作：直接按回车键（使用默认端口 18789，不要修改）。

【第 15 步】认证模式

终端屏幕显示：

plaintext
◇ Auth mode
│ Token

你的操作：直接按回车键（默认启用 Token 认证，系统自动生成）。

【第 16 步】Tailscale 暴露网关

终端屏幕显示：

plaintext
◇ Tailscale expose gateway?
│ No

你的操作：直接按回车键（默认关闭，新手无需开启）。

【第 17 步】现在设置聊天渠道？

终端屏幕显示：

plaintext
◇ Set up chat channels now?
│ No

你的操作：直接按回车键（默认跳过，后续单独配置钉钉渠道）。

【第 18 步】网页搜索提供商

终端屏幕显示：

plaintext
◇ Web search provider
│ Skip for now

你的操作：直接按回车键（默认跳过，新手无需配置）。

【第 19 步】现在安装技能？

终端屏幕显示：

plaintext
◇ Install skills now?
│ Yes

你的操作：直接按回车键（默认安装基础技能，确保机器人正常响应）。

【第 20 步】Node 包管理器

终端屏幕显示：

plaintext
◇ Node package manager
│ npm

你的操作：直接按回车键（与之前安装的 Node.js 对应，无需修改）。

【第 21 步】确认保存配置

终端屏幕显示：

plaintext
◇ Confirm save all config? (Y/n)

你的操作：输入 Y（大写、小写均可），按回车键确认（必须保存，否则配置失效）。

【第 22 步】现在启动代理？

终端屏幕显示：

plaintext
◇ Hatch your agent now?
│ Hatch later

你的操作：直接按回车键（默认跳过，后续配置完钉钉再启动）。

【第 23 步】安装开机自启服务

终端屏幕显示：

plaintext
◇ Install LaunchAgent (macOS daemon)
│ Yes

你的操作：直接按回车键（默认安装，实现开机自动启动网关）。

【最终完成】

终端屏幕显示：

plaintext
✅ All done!

你的操作：无需任何操作，终端自动返回正常命令界面，此时 OpenClaw 初始化配置全部完成，进入下一步安装钉钉连接器插件即可。

新手必看提醒：每一步严格对照“屏幕显示”操作，尤其是第7步 API Base URL 必须添加 /v1，第11步模型 ID 必须是 qwen3:8b，不能多空格、不能改大小写，否则会导致后续对接失败。

4.3 安装钉钉连接器插件（必做，实现 OpenClaw 与钉钉对接）

bash
openclaw plugins install @dingtalk-real-ai/dingtalk-connector

等待安装完成，出现「Installed plugin: dingtalk-connector」提示，即为插件安装成功，插件会自动加载到 OpenClaw 配置中。若安装失败，检查 npm 镜像配置（步骤 2.4），或执行 npm install -g @dingtalk-real-ai/dingtalk-connector 后再重新执行该命令。

4.4 验证 OpenClaw 网关状态

bash
openclaw gateway status

正确输出：显示「Runtime: running」，说明 OpenClaw 网关已正常启动；若显示「stopped」，重新执行「openclaw gateway restart」即可。

五、钉钉开放平台配置（获取 Client ID / Client Secret，对接 OpenClaw 必需）

5.1 登录钉钉开放平台

打开浏览器，访问地址：open-dev.dingtalk.com，使用钉钉企业管理员账号扫码登录（普通员工账号无创建应用权限）。若没有企业管理员账号，需先创建钉钉企业（免费），再登录开放平台。

5.2 创建企业内部应用

1. 登录后，点击顶部「应用开发」→ 左侧「企业内部应用」→ 点击「创建应用」；

2. 应用类型选择「企业内部应用」，填写应用名称（建议填写「OpenClaw AI」，便于后续搜索），应用描述可随意填写，其他信息可默认，点击「创建」；

3. 创建完成后，自动进入应用详情页，无需额外操作，继续下一步。

5.3 开启机器人并设置 Stream 模式（关键，否则会出现 403 报错）

1. 在应用详情页左侧菜单，找到「应用能力」→ 点击「机器人」；

2. 点击「开启机器人」开关（默认关闭，开启后变为蓝色）；

3. 「消息接收模式」必须选择「Stream（长连接）」（不要选择 HTTP 模式，否则无法对接本地 OpenClaw）；

4. 填写机器人名称（与应用名称一致即可）、上传头像（可选），点击「保存」，机器人设置完成。若保存失败，刷新页面后重新操作。

5.4 开通核心权限（缺一不可，否则钉钉无法正常调用模型）

1. 在应用详情页左侧菜单，点击「权限管理」；

2. 在搜索框中分别搜索以下 3 个权限，找到后点击「开通」，开通后无需额外配置：

￮ im:message（消息相关权限）

￮ im:chat（聊天相关权限）

￮ qyapi_robot_sendmsg（机器人发消息权限）

3. 若搜索不到对应权限，检查应用类型是否为「企业内部应用」，非此类型无相关权限，需重新创建应用。

5.5 发布应用（不发布无法在钉钉中搜到机器人）

1. 在应用详情页左侧菜单，点击「版本管理与发布」；

2. 点击「创建版本」，版本号可默认（如 1.0.0），无需填写更新说明，点击「提交发布」；

3. 「可见范围」选择「全部员工」或「仅自己」（根据需求选择，至少包含自己的账号），点击「确认发布」；

4. 发布后，等待 1-2 分钟（系统同步需要时间），再进行后续操作。若发布失败，检查应用信息是否填写完整，补充后重新发布。

5.6 复制凭证（保存好，后续 OpenClaw 配置需要用到，不可出错）

1. 在应用详情页左侧菜单，点击「凭证与基础信息」；

2. 找到「Client ID（AppKey）」和「Client Secret（AppSecret）」，分别点击「复制」，保存到记事本或备忘录中；

3. 注意：复制时不要包含任何空格、换行，否则会导致后续对接失败；建议复制后粘贴到记事本，检查无多余字符后再保存。

六、OpenClaw 对接钉钉（channels add 逐字操作，每一步明确选择/输入）

首先执行渠道添加命令：

bash
openclaw channels add

执行后，终端会依次出现以下提示，新手无需理解含义，严格按照下面每一步“屏幕显示+操作”执行，全程不跳步、不修改，每一步操作后均按回车键确认，确保钉钉渠道对接成功，具体步骤如下：

【第 1 步】确认配置聊天渠道

终端屏幕显示：

plaintext
◇ Set up a chat channel now?
│ Yes

你的操作：直接按回车键（默认选中 Yes，开始配置聊天渠道）。

【第 2 步】选择聊天渠道类型

终端屏幕显示：

plaintext
◇ Select a chat channel type
│ DingTalk (钉钉)
WeChat Work (企业微信)
Slack
Discord
...（其他选项）

你的操作：用键盘方向键移动光标，选中「DingTalk (钉钉)」，按回车键确认。

【第 3 步】钉钉一键扫码授权选择

终端屏幕显示：

plaintext
◇ Use DingTalk one-click QR auth? (recommended)
│ No
Yes

你的操作：直接按回车键（默认选中 No，我们手动填写之前获取的 Client ID 和 Client Secret，避免扫码授权的复杂操作）。

【第 4 步】输入钉钉 Client ID（AppKey）

终端屏幕显示：

plaintext
◇ Enter DingTalk Client ID (AppKey)
│ [光标闪烁，等待输入]

你的操作：打开之前保存的记事本/备忘录，复制「Client ID（AppKey）」（确保无空格、无换行），粘贴到终端光标闪烁处，粘贴完成后按回车键确认。若粘贴失败，手动输入 Client ID（注意大小写一致）。

【第 5 步】选择 Client Secret 提供方式

终端屏幕显示：

plaintext
◇ How to provide Client Secret (AppSecret)
│ Enter Client Secret
Load from file
Use environment variable

你的操作：直接按回车键（默认选中 Enter Client Secret，手动输入/粘贴 Client Secret）。

【第 6 步】输入钉钉 Client Secret（AppSecret）

终端屏幕显示：

plaintext
◇ Enter DingTalk Client Secret (AppSecret)
│ [光标闪烁，等待输入]

你的操作：复制记事本/备忘录中的「Client Secret（AppSecret）」（确保无空格、无换行），粘贴到终端光标闪烁处，粘贴完成后按回车键确认。若粘贴失败，手动输入 Client Secret（注意大小写一致）。

【第 7 步】设置 Gateway Token

终端屏幕显示：

plaintext
◇ Gateway Token (custom, e.g., 123456)
│ [光标闪烁，等待输入]

你的操作：输入自定义的 Gateway Token（推荐输入「123456」，简单易记，无需复杂字符），输入完成后按回车键确认。

【第 8 步】设置群聊响应策略

终端屏幕显示：

plaintext
◇ Group chat policy (how to respond in groups)
│ Open - respond in all groups (requires mention)
Restricted - respond only in selected groups
Disabled - do not respond in groups

你的操作：直接按回车键（默认选中 Open - respond in all groups (requires mention)，即群聊中@机器人才能响应，适合新手）。

【第 9 步】完成渠道配置

终端屏幕显示：

plaintext
◇ Select an option
│ Finished
Add another channel
Cancel

你的操作：用方向键选中「Finished」，按回车键确认（完成钉钉渠道配置）。

【第 10 步】配置私聊权限策略

终端屏幕显示：

plaintext
◇ Configure DM access policies now? (direct message)
│ No
Yes

你的操作：直接按回车键（默认选中 No，私聊权限默认开启，无需额外配置）。

【第 11 步】渠道账号命名选择

终端屏幕显示：

plaintext
◇ Name these channel accounts now?
│ No
Yes

你的操作：直接按回车键（默认选中 No，无需给渠道账号命名，不影响使用）。

【第 12 步】渠道账号路由配置

终端屏幕显示：

plaintext
◇ Route these channel accounts to agents now?
│ No
Yes

你的操作：直接按回车键（默认选中 No，后续无需额外路由配置，默认对接本地 qwen3:8b 模型）。

【第 13 步】渠道配置完成

终端屏幕显示：

plaintext
✅ Channels updated successfully!

你的操作：无需任何操作，渠道添加完成，终端自动返回正常命令界面。

6.1 重启网关加载钉钉配置（必做）

渠道添加完成后，必须重启 OpenClaw 网关，才能让钉钉配置生效，执行以下命令：

bash
openclaw gateway restart

执行后，终端显示「Restarted LaunchAgent successfully」，即为重启成功。若重启失败，执行 sudo openclaw gateway restart，输入开机密码后重新尝试。

6.2 验证钉钉渠道是否加载成功

执行以下命令，检查钉钉连接器插件和渠道是否正常加载：

bash
openclaw plugins list
openclaw channels list

正确输出：

• 第一条命令显示「dingtalk-connector」（钉钉连接器插件已加载）；

• 第二条命令显示「dingtalk」相关渠道信息（钉钉渠道已添加成功）。

新手必看提醒：粘贴 Client ID 和 Client Secret 时，务必确保无空格、无换行，否则会出现 403 对接失败；渠道添加完成后，必须重启网关，否则配置不生效。

七、钉钉机器人测试（必做，验证部署成功）

部署完成后，测试机器人是否能正常响应，避免后续排查麻烦，具体步骤如下：

7.1 私聊测试

1. 打开钉钉 APP，在搜索框中搜索「OpenClaw AI」（与钉钉应用名称一致）；

2. 进入机器人聊天窗口，发送任意消息（如“你好”）；

3. 正确结果：机器人会在 1-3 秒内回复消息，说明私聊功能正常。

7.2 群聊测试

1. 创建一个钉钉群（或进入已有群聊）；

2. 群设置 → 群机器人 → 添加机器人 → 选择「OpenClaw AI」，完成添加；

3. 在群内 @OpenClaw AI + 发送问题（如“@OpenClaw AI 你好”）；

4. 正确结果：机器人会回复该消息，说明群聊@响应功能正常。

7.3 测试失败排查

若测试无响应，按以下顺序排查：

• 检查 Ollama 模型是否正常运行：执行 ollama ps，确保 qwen3:8b 进程存在，不存在则执行 ollama run qwen3:8b & 重启；

• 检查 OpenClaw 网关是否正常运行：执行 openclaw gateway status，确保显示「running」，否则执行 openclaw gateway restart；

• 检查钉钉渠道配置：执行 openclaw channels list，确保 dingtalk 渠道存在，不存在则重新执行 openclaw channels add 配置；

• 检查钉钉应用配置：确认机器人消息接收模式为 Stream，权限已开通，应用已发布，Client ID/Secret 无错误。

八、常见报错与修复（补充完整，新手必备）

8.1 403 钉钉连接失败

• 报错原因：机器人消息接收模式不是 Stream、权限未开全、应用未发布、Client ID/Secret 有空格/错误；

• 修复步骤：

a. 进入钉钉开放平台 → 应用详情 → 机器人 → 确认消息接收模式为「Stream（长连接）」；

b. 检查权限管理，确保 3 个核心权限已开通；

c. 确认应用已发布，可见范围包含自己的账号；

d. 重新复制 Client ID/Secret，确保无空格、无换行，重新执行 openclaw channels add 重新配置渠道；

e. 修复后重启网关：openclaw gateway restart。

8.2 openclaw: command not found

• 报错原因：OpenClaw 安装失败、环境变量未生效；

• 修复步骤：

a. 重新安装 OpenClaw：curl -fsSL https://openclaw.ai/install.sh | bash；

b. 执行 source ~/.zshrc（bash 终端执行source ~/.bash_profile）；

c. 若仍报错，重启终端后再尝试。

8.3 钉钉搜不到机器人

• 报错原因：应用未发布、可见范围未包含自己的账号、机器人开关未开启；

• 修复步骤：

a. 进入钉钉开放平台 → 版本管理与发布 → 确认应用已发布；

b. 检查可见范围，确保包含自己的账号；

c. 进入应用详情 → 机器人 → 确认机器人开关已开启；

d. 等待 1-2 分钟，重新在钉钉搜索机器人。

8.4 Ollama 模型无法启动

• 报错原因：模型下载中断、模型名称错误；

• 修复步骤：

a. 执行 ollama pull qwen3:8b 重新下载模型；

b. 下载完成后，执行 ollama run qwen3:8b & 启动模型；

c. 若仍失败，执行 ollama rm qwen3:8b 删除模型，重新下载。

九、注意事项（汇总，新手必看）

• M 系列芯片必须使用 /opt/homebrew 路径，不可混用 Intel 路径（如 /usr/local），否则会导致安装失败；

• Node.js 必须安装 22.x LTS 版本，其他版本（如 20.x、18.x）易导致 OpenClaw 安装或运行报错；

• Ollama 模型首次下载必须等待完成，不可中断，中断后需重新下载；

• 钉钉机器人必须选择 Stream 模式，HTTP 模式无法对接本地 OpenClaw，会出现 403 报错；

• 所有凭证（Client ID、Client Secret）复制时，必须确保无空格、无换行，否则会导致对接失败；

• 国内网络必须配置 npm 镜像，否则 OpenClaw 安装、插件安装会超时；

• 启动顺序：先启动 Ollama 模型（ollama run qwen3:8b &），后启动 OpenClaw 网关（openclaw gateway start）；

• 终止进程：若需关闭服务，执行 pkill ollama 关闭模型，openclaw gateway stop 关闭网关，避免残留进程影响后续启动；

• 全程命令建议直接复制粘贴，避免手动输入时出现拼写错误（尤其是模型名、命令参数）。

作者声明本文无利益相关，欢迎值友理性交流，和谐讨论～