Windows 11 安装 OpenClaw 完整教程

在这里插入图片描述

本教程基于 Windows 11，从环境准备到进阶配置，手把手教你在本地部署 OpenClaw，实现本地 AI 助手（对话、文件操作、代码执行、多渠道接入等）。本教程示例以 GLM（智谱）等云端模型为主；若机器性能一般，本地 Ollama 不必期望太高，建议直接使用云端模型即可。

智谱 GLM 邀请福利（推荐先注册再配置）：笔者在智谱大模型开放平台 BigModel.cn 上打造 AI 应用。智谱新一代旗舰模型 GLM-4.7 已上线，在推理、代码、智能体综合能力上达到开源模型 SOTA 水平。通过下方邀请链接注册即可获得 2000 万 Tokens 大礼包，便于在 OpenClaw 中畅享 GLM 能力。

GLM 邀请链接（注册即得 2000 万 Tokens）：https://www.bigmodel.cn/invite?icode=Ssx3UdmC76nwa7bdO5B1F0jPr3uHog9F4g5tjuOUqno%3D
平台：智谱大模型开放平台 BigModel.cn

OpenClaw 是一款开源智能体 AI 助手，打破传统 AI「只对话不行动」的局限：

核心能力：自然语言交互、本地文件操作、代码执行、命令行控制
多模型支持：可对接 GLM（智谱）、Qwen、OpenAI 等云端大模型，或本地用 Ollama 运行模型（机器性能不足时效果有限，建议以云端为主）。使用 GLM 时建议通过 GLM 邀请链接 注册 BigModel.cn，可获 2000 万 Tokens 礼包：https://www.bigmodel.cn/invite?icode=Ssx3UdmC76nwa7bdO5B1F0jPr3uHog9F4g5tjuOUqno%3D
多渠道交互：支持 Telegram、WhatsApp、钉钉、飞书等
本地化运行：网关与数据在本地，模型可选用云端或本地

（一）系统要求

操作系统：Windows 10 及以上（推荐 Windows 11）
硬件要求：
- 内存 ≥ 4GiB（推荐 8GiB 以上）
- 磁盘预留 ≥ 10GiB（存储依赖与运行日志）
- GPU：非必需（本地运行大模型需额外配置）

（二）核心依赖检查

1. 检查 Node.js 版本

打开 PowerShell，输入：

要求：版本 ≥ v22

当前系统状态：

如果版本过低，需先升级 Node.js：

访问 https://nodejs.org/ 下载最新 LTS 版本（建议 v22 或 v24）
运行安装程序，保持默认设置即可
安装后重启终端验证版本

2. 检查 PowerShell 执行权限

Windows 默认禁止运行脚本，需手动开启：

当前系统状态：

3. 检查 Ollama 安装（可选）

Ollama 是本地运行大模型的工具，OpenClaw 可通过它使用本地模型。本教程以 GLM 等云端模型为主；若本机配置一般，不必强求本地 Ollama，直接用云端模型即可。

检查 Ollama 是否已安装：

预期输出（显示版本号）：

如果未安装，请访问 https://ollama.com/ 下载并安装。

4. 检查已安装的 Ollama 模型

查看本地已安装的模型：

预期输出：

如果没有安装模型，可以运行以下命令下载：

常用模型推荐：

5. 可选工具准备

浏览器：Chrome 或 Edge（访问 OpenClaw Web 管理界面）
文本编辑器：Notepad++ 或 VS Code（修改配置文件）

方法一：官方一键安装脚本（推荐）

打开普通权限的 PowerShell（无需管理员），执行：

安装说明：

该命令会自动从官方服务器下载 OpenClaw 并配置环境变量
若长时间无进展（超过 5 分钟），按回车键刷新终端
看到 “installed openclaw 部署 successfully” 提示即表示安装完成

方法二：通过 npm 安装

注意事项：

安装过程可能需要 5-10 分钟，请耐心等待
如果遇到网络超时，可多次重试
安装完成后重启 PowerShell 终端
如果遇到文件被占用错误（EBUSY/ENOTEMPTY），重启电脑后重试

方法三：通过 pnpm 安装（官方推荐）

pnpm 是 OpenClaw 官方推荐的包管理器，安装速度更快且更节省磁盘空间。

1. 安装 pnpm

2. 配置 pnpm 环境

重要：执行后，必须关闭当前 PowerShell 窗口，打开新的 PowerShell 才能使配置生效。

如果提示环境变量未找到，可以手动设置：

设置完成后同样需要关闭并重新打开 PowerShell。

3. 安装 OpenClaw

在新 PowerShell 窗口中运行：

4. 验证安装

预期输出：

如果显示版本号，说明安装成功。

当前安装状态记录

在本次安装过程中，遇到以下情况：

官方脚本超时：执行时超时
npm 安装文件被占用：执行时遇到 EBUSY/ENOTEMPTY 错误
原因：可能有之前的安装进程还在运行
解决方案：重启电脑后重试
使用 pnpm 成功安装：
- 安装 pnpm： ✓ 成功
- 配置 pnpm： ✓ 成功
- 安装 OpenClaw： ✓ 成功
- 验证版本：显示 ✓ 成功

推荐安装方式：使用 pnpm（官方推荐，速度更快）

安装完成后，需运行初始化向导配置基础参数：

配置向导步骤

运行模式（Mode）
- 选择：QuickStart（快速启动，跳过复杂配置）
模型提供商（Provider）
- 推荐：选择 Zai（智谱 GLM）等云端模型，在控制台或中配置 API Key 后即可使用。GLM API Key 在 BigModel.cn 获取，GLM 邀请链接（注册即得 2000 万 Tokens）：https://www.bigmodel.cn/invite?icode=Ssx3UdmC76nwa7bdO5B1F0jPr3uHog9F4g5tjuOUqno%3D
- 若要用本地模型：选择 Ollama，并配置本地地址 http://localhost:11434（机器性能一般时不要对本地 Ollama 期望太高）。
默认模型（Default model）
- 使用 GLM 时：如或。
- 使用 Ollama 时：如。
交互渠道（Channels）
- 选择：Skip for now（暂不配置远程渠道）
基础技能（Skills）
- 选择：Yes（启用文件操作、命令执行等核心技能）
技能安装工具（Skill install）
- 选择：npm
技能扩展依赖（Skill Dependencies）
- 选择：Skip for now
其他配置
- GOOGLE_PLACES_API_KEY：No
- Hooks：Skip for now

完成标志：终端显示 “Gateway service installed”

1. 检查网关服务

预期输出：Gateway is running

如果显示 “Gateway is stopped”，执行：

等待 10 秒后再次验证。

2. 访问 Web 管理界面

打开浏览器，访问：

首次访问需要令牌：

找到配置文件：
用记事本打开，搜索 “token”：
复制引号内的令牌字符串
在浏览器”未授权”页面粘贴令牌并确认

说明：本教程以 GLM（智谱）等云端模型 为主。若机器性能一般（内存不足、无独显或算力有限），不必对本地 Ollama 期望太高——响应慢、效果一般属正常，建议直接使用云端模型。本节供希望尝试本地部署的读者参考。

1. Ollama 模型选择指南

Ollama 提供多种开源大模型，可根据硬件与需求选择（机器一般时建议仍以云端为主）：

下载模型

选择模型后，运行以下命令下载：

下载提示：若下载较慢，可配置镜像源或使用代理；下载完成后模型会保存在。

2. 确保 Ollama 服务运行

检查 Ollama 服务状态：

预期输出：

如果服务未运行，手动启动 Ollama：

保持这个窗口打开，或者在后台运行 Ollama 服务。

3. 测试 Ollama 模型

在命令行测试模型是否正常工作：

预期输出：模型会返回中文回复。

如果能够正常响应，说明 Ollama 模型运行正常。

4. 配置 OpenClaw 连接 Ollama

在 OpenClaw Web 界面中：

启动 OpenClaw 网关服务：
打开浏览器访问：http://localhost:18789
左侧菜单点击 “Config > Models”
选择 “Add Provider”（添加提供商）
填写配置信息：
- Provider Name：Ollama（自定义名称）
- Base URL：http://localhost:11434
- Model：输入模型名称（如）
保存配置
在配置文件中添加模型（可选）：
编辑配置文件：

5. 测试 OpenClaw + Ollama 集成

在 OpenClaw 对话框或命令行中测试：

方法一：通过命令行测试

方法二：通过 Web 界面测试

打开 http://localhost:18789
在对话框输入：

预期结果：

模型能够正常响应
响应速度取决于你的硬件性能（通常 3-10 秒）
内容应包含自我介绍

如果能够正常响应，说明本地模型配置成功！

6. 多模型配置（可选）

如果你下载了多个模型，可以在 OpenClaw 中切换使用：

在对话中指定模型：

在配置文件中设置默认模型：

查看所有可用模型：

7. 常见问题

问题 1：模型响应非常慢

可能原因：

CPU 运行，没有 GPU 加速
内存不足，频繁使用虚拟内存
模型参数量太大

解决方案：

使用更小的模型（如而非）
使用量化版本（如）
关闭其他应用程序释放内存
考虑使用 GPU 加速（需要安装 CUDA）

问题 2：OpenClaw 无法连接到 Ollama

排查步骤：

检查 Ollama 服务是否运行：
检查端口是否被占用：
测试 Ollama API：

问题 3：模型中文效果不佳

解决方案：

使用 Qwen 系列模型（或），这些模型对中文优化更好
在提示词中明确要求用中文回答

1. 基础对话

输入：

预期响应包含：“本地AI助手”、”文件操作”等关键词。

2. 文件读取

在桌面创建测试文件，写入一些内容，然后输入：

3. 命令执行

输入：

预期返回类似：“已用空间：XX GB，剩余空间：XX GB”。

问题 1：“openclaw” 命令失效

现象：提示”无法识别”

解决方案：

重启 PowerShell
使用临时执行
手动配置环境变量：
- 将或添加到系统 PATH
- 重启终端
检查 pnpm 环境：
然后关闭并重新打开 PowerShell

问题 2：网关未授权（令牌缺失）

现象：访问 http://localhost:18789 显示”未授权：网关令牌缺失”

日志输出：

解决方案：

查找令牌：
预期输出：
在浏览器中输入令牌：
- 打开 http://localhost:18789
- 在”未授权”页面输入令牌
- 或者直接访问带令牌的 URL：
刷新页面，应该能看到管理界面

备用方法：若无法在浏览器中输入令牌，可在配置文件中临时关闭令牌验证（仅限测试环境）：

问题 3：Web 界面无法访问

排查步骤：

检查网关服务：
验证端口是否被占用：
若端口被占用，可在配置文件中修改端口（如改为 18790）后重启网关。
重启网关：
临时关闭防火墙测试（测试通过后请重新开启）：
- 打开「Windows Defender 防火墙」→ 暂时关闭 → 测试通过后再开启。

问题 4：本地模型响应缓慢

原因：llama3:8b 模型较大（4.7GB），需要足够的内存和计算资源

解决方案：

关闭不必要的应用程序释放内存
升级硬件（增加内存）
使用量化模型（如 llama3:8b-q4）
对接云端模型作为备选方案

问题 5：网关服务安装失败

现象：

尝试安装时报错：

原因：权限不足，无法创建 Windows 任务计划程序

解决方案：

方法 1：以管理员权限运行

方法 2：直接启动网关（推荐，最简单）

保持 PowerShell 窗口打开，网关就会持续运行。

方法 3：后台运行网关

方法 4：手动创建任务计划（高级）

推荐：使用方法 1 或方法 2，最简单直接。

问题 6：模型不支持图片输入

现象：

原因：当前使用的模型（如 llama3:8b）是纯文本模型，不支持图片输入

解决方案：

步骤 1：下载支持图片的多模态模型

下载过程：

LLaVA 模型大小约 4.1 GB
下载时间取决于网络速度

步骤 2：验证模型下载

预期输出：

步骤 3：测试图片识别功能

通过命令行测试：

步骤 4：在 OpenClaw 中使用多模态模型

方法 A：在对话中指定模型

方法 B：修改默认模型

编辑配置文件：

保存后重启网关：

方法 C：使用命令行指定模型

推荐模型对比：

模型特点适用场景 llava:latest 成熟稳定，图片理解准确通用图片识别 llava-llama3:latest 基于 Llama 3，质量更高高质量图片分析 minicpm-v:latest 中文优化，轻量级中文场景图片描述 bakllava:latest 速度快，性能平衡快速图片识别

提示：

多模态模型通常比纯文本模型慢一些
建议根据使用场景选择合适的模型
可以同时保留多个模型，按需切换使用

安全防护

保护令牌：
- 勿分享令牌给他人
- 定期在 “Config > Security” 中刷新令牌
限制文件权限：
- 在 “Config > Permissions” 中，仅开放必要文件夹
- 禁止”全盘访问”

性能优化

关闭不必要的技能：
- 在 “Skills” 页面取消勾选无需使用的技能
- 如”语音识别”、”图像处理”等
清理日志：
- 定期删除日志文件：
更新版本：

使用 npm 更新：

或使用 pnpm 更新（推荐）：

更新前备份配置文件或

1. 对接云端大模型（本教程以 GLM 为主）

本教程示例已采用 GLM（智谱），在的与中配置等即可。若机器性能一般，不必强求本地 Ollama，直接用 GLM 等云端模型即可。

智谱 GLM 注册与 Tokens 礼包（建议优先完成）：智谱旗舰模型 GLM-4.7 已在 BigModel.cn 上线，推理、代码、智能体能力达开源 SOTA。通过邀请链接注册即可获得 2000 万 Tokens 大礼包，便于在 OpenClaw 中长期使用 GLM。

GLM 邀请链接（注册即得 2000 万 Tokens）：https://www.bigmodel.cn/invite?icode=Ssx3UdmC76nwa7bdO5B1F0jPr3uHog9F4g5tjuOUqno%3D
在 BigModel.cn 注册/登录后，在控制台创建 API Key，填入 OpenClaw 的或 Web 界面 Config → Authentication。

如需其他云端能力，可对接阿里云百炼等：

登录阿里云百炼控制台创建 API-Key
在 OpenClaw Web 界面添加对应 Provider
填写 API-Key 和 baseUrl
使用时在对话中指定模型（如「使用百炼模型回答」）

2. 绑定钉钉/飞书/Telegram 交互渠道

钉钉配置示例：

登录钉钉开放平台，创建企业内部机器人
获取 Bot Token（AppKey、AppSecret）
在 OpenClaw Web 界面或的中配置钉钉渠道
在钉钉群中添加机器人并测试

飞书配置示例：

登录飞书开放平台（https://open.feishu.cn/），创建企业自建应用
获取 App ID、App Secret，并开通「机器人」能力与消息权限
在 OpenClaw Web 界面或的中配置飞书渠道（含 webhook 地址、App ID、App Secret、Verification Token 等）
在飞书群中添加机器人并测试

钉钉：若采用 Stream 模式（推荐，见第十三章钉钉 Channel 插件），不需要透传/端口转发，本地机器即可直接使用钉钉。飞书或通过 Webhook/AppFlow 方式对接钉钉时，才需要先做端口转发并将公网地址填到开放平台，详见第十三章。

3. 配置 web_search（获取实时股价、搜索等）

当 Agent 提示「搜索服务未配置，无法使用 web_search」或「无法获取实时股票价格等动态数据」时，可配置 Brave Search API 启用网页搜索（查股价、新闻等）。

如何申请 Brave Search API Key

打开官网
浏览器访问：https://brave.com/search/api/
注册/登录
- 点击页面的 Sign up 或 Get started，用邮箱或 Google/GitHub 注册并登录。
- 若已有账号，直接 Log in。
选择计划
- 在控制台或定价页中选择 「Data for Search」（网页搜索数据）。
- 不要选 “Data for AI”，该计划与 OpenClaw 的 web_search 不兼容。
- 免费档一般为 2000 次/月，足够个人或测试使用。
创建应用并生成 Key
- 在控制台里找到 Create application 或 New app，填写应用名称（如）。
- 创建成功后，在应用详情页会显示 API Key（一长串字符）。
- 点击 Copy 或手动复制，保存到本地（不要泄露或写进公开文档）。
填入 openclaw.json
将复制的 API Key 填入下方配置中的字段。

在 openclaw.json 中配置：

文件位置：Windows 下为。
在根节点下增加（或合并到已有）段，将换成你的 Key：

重启网关
在运行的终端中按 Ctrl+C 停止后重新执行；若网关已安装为系统服务，则执行。

配置生效后，Agent 即可使用 web_search 查询实时股价、新闻等。Brave 免费档约 2000 次/月，详见 Brave Search API 文档。

国内用户：能否换成国内 API？

目前 OpenClaw 官方文档中，主要支持 Brave Search 和 Perplexity Sonar，尚未列出百度、搜狗、阿里云等国内搜索 API 的现成 provider。Brave Search API 在国内多数网络下可访问，免费约 2000 次/月、无需备案，可作为默认选择。若希望使用国内服务，可关注官方 Tools 文档与 Brave Search 说明的更新，或留意社区是否提供 MCP、插件等集成方式；另一种官方支持的搜索能力是 Perplexity Sonar（需自行配置 API）。结论：当前最稳妥的做法仍是配置 Brave Search API（国内可用）；若必须使用国内厂商的搜索 API，需等待官方或社区提供对应 provider 或集成方式。

4. 启用自动化任务

OpenClaw 支持多种自动化任务：

监控文件夹：新增文件自动备份
定时执行：每天生成邮件摘要
跨平台同步：钉钉日程与本地日历联动

本章记录在实际安装与配置 OpenClaw 时遇到的问题及解决方案，便于对照排查。

1. 安装过程记录

1.1 OpenClaw 安装

尝试 1：官方脚本安装

结果：超时失败

尝试 2：npm 安装

结果：遇到文件被占用错误

原因：之前的安装进程未完全退出

尝试 3：pnpm 安装（成功）

2. 网关服务启动问题

2.1 首次启动网关

尝试 1：启动网关

错误信息：

尝试 2：安装网关服务

错误信息：

原因：权限不足，无法创建 Windows 任务计划程序

2.2 解决方案：直接启动网关

最终方案：

结果：成功启动

网关启动日志：

3. Web 界面访问问题

3.1 令牌认证失败

尝试访问：http://localhost:18789

错误日志：

3.2 获取令牌

查找令牌：

输出：

3.3 解决方案：通过 URL 添加令牌

访问带令牌的 URL：

结果：成功访问 Web 管理界面

4. 模型图片输入问题

4.1 问题描述

错误信息：

原因：当前使用的 llama3:8b 模型不支持图片输入

4.2 解决方案：下载多模态模型

下载 LLaVA 模型：

下载过程：

验证模型：

输出：

4.3 测试图片识别

通过 Ollama 测试：

结果：模型能够正确识别和描述图片

4.4 在 OpenClaw 中使用

方法 1：在对话中指定

方法 2：修改配置文件

编辑：

重启网关：

5. 调试经验总结

5.1 关键问题

问题原因解决方案安装失败文件被占用使用 pnpm 安装或重启电脑网关安装失败权限不足直接启动网关而非安装为服务 Web 界面无法访问令牌缺失从配置文件获取令牌并通过 URL 传递模型不支持图片使用纯文本模型下载并配置多模态模型（LLaVA）

5.2 推荐安装流程

本教程以 GLM（智谱）等云端模型 为主；机器性能一般时不必强求本地 Ollama。基于实际调试经验，推荐的完整安装流程：

5.3 配置 Ollama 多模态模型

5.4 注意事项

pnpm 配置后需要重启终端
- 运行后，必须关闭并重新打开 PowerShell
网关启动方式
- 首次安装建议直接启动（）
- 不需要安装为 Windows 服务，避免权限问题
令牌管理
- 令牌存储在
- 可以通过 URL 参数传递：
- 也可以临时禁用令牌验证（仅测试用）
模型选择
- 纯文本任务：、
- 图片识别任务：、
- 可以同时下载多个模型，按需切换

5.5 故障排查清单

遇到问题时，按以下顺序排查：

检查安装
检查网关状态
检查 Ollama 服务
检查端口占用
检查配置文件
查看日志

6. 最终配置状态

经过调试，系统最终配置如下：

环境信息：

操作系统：Windows 11
Node.js：v22.19.0
npm：8.19.4
pnpm：已安装并配置

已安装组件：

OpenClaw：v2026.2.1
模型：GLM（智谱）等云端模型已配置；可选 Ollama + llama3:8b（文本）、llava:latest（多模态，机器一般时不必期望太高）

运行状态：

网关服务：运行中（端口 18789）
Ollama 服务：运行中（端口 11434）
Web 界面：可访问（需要令牌）

访问方式：

Web 管理：http://localhost:18789
命令行：
图片识别：

OpenClaw 在 Windows 11 上的部署流程可概括为：

关键要点：

确保 Node.js 版本 ≥ v22
开启 PowerShell 脚本执行权限
本教程以 GLM 等云端模型为主；机器性能一般时不必强求本地 Ollama
注意令牌管理和文件权限设置
定期清理日志和更新版本

本系统当前状态（示例）：

✓ Node.js v22.19.0
✓ npm 8.19.4 / pnpm 已安装并配置
✓ PowerShell 脚本执行权限已启用
✓ 模型：GLM（智谱）等云端模型已配置；可选 Ollama + llama3:8b / llava（机器不行时不必期望太高）
✓ OpenClaw v2026.2.1 已安装成功
✓ 网关服务运行中（直接启动，未安装为服务）
✓ Web 界面可访问（令牌认证）

安装成功验证：

下一步操作：

✅ OpenClaw 已安装
✅ 网关服务已启动
配置 GLM（智谱）：在 BigModel.cn 注册并获取 API Key（GLM 邀请链接，注册即得 2000 万 Tokens：https://www.bigmodel.cn/invite?icode=Ssx3UdmC76nwa7bdO5B1F0jPr3uHog9F4g5tjuOUqno%3D），填入 OpenClaw；或可选安装 Ollama + 模型（机器一般时不必强求）
运行初始化向导（可选）：
测试基础功能：
- 文本对话：（使用默认模型，如 GLM）
- 若用本地多模态：
根据需求配置进阶功能（钉钉/飞书、web_search 等）

OpenClaw 命令帮助速查

在终端执行可查看完整用法，以下为常用命令摘要（版本 2026.2.1）。

全局选项：

：输出版本号
：开发配置（独立状态、网关端口 19001）
：使用命名配置
：显示帮助

常用子命令：

命令说明初始化 ~/.openclaw/openclaw.json 与工作区交互式向导：网关、工作区、技能 / 配置凭证、设备与 agent 默认项网关与渠道健康检查与修复用当前 token 打开控制台 UI 网关控制（启动/停止/状态）插件管理（安装/列表等）渠道管理发送消息与渠道操作通过网关执行 agent 回合技能管理网关日志获取运行中网关健康状态会话列表渠道健康与最近会话

查看某子命令的详细帮助：，例如：

文档：https://docs.openclaw.ai/cli

参考资源：

OpenClaw 官方文档
智谱 GLM（本教程推荐）：智谱大模型开放平台 BigModel.cn；GLM 邀请链接（注册即得 2000 万 Tokens）：https://www.bigmodel.cn/invite?icode=Ssx3UdmC76nwa7bdO5B1F0jPr3uHog9F4g5tjuOUqno%3D（GLM-4.7 已上线，推理/代码/智能体达开源 SOTA）
Ollama 官方网站：https://ollama.com/
Node.js 官方网站：https://nodejs.org/
阿里云百炼控制台：https://bailian.console.aliyun.com/

版本信息：

教程日期：2026-02-03
OpenClaw 版本：最新版
Node.js 版本：v22.19.0
Windows 版本：Windows 11

重要说明：本章针对本地 Windows 机器。钉钉推荐使用 DingTalk Channel 插件（Stream 模式）：不需要透传、不需要公网 IP、不需要端口转发，本地即可直接接入钉钉。飞书或通过 Webhook/AppFlow 对接钉钉时，才需要端口转发。下文先给出钉钉 Channel 插件的完整说明，再说明飞书与端口转发。

零、安装钉钉与飞书插件（必须先执行）

配置钉钉/飞书前，须先安装并加载对应渠道插件，否则中的 / 会报「unknown channel id」等错误。

钉钉插件（DingTalk Channel for OpenClaw）：

推荐使用社区插件 openclaw-channel-dingtalk，采用 Stream 模式：不需要透传、不需要公网 IP、不需要 Webhook，本地机器即可直接使用钉钉。安装命令（任选其一）：

或

若在 Windows 下报，可改用 CMD 执行，或使用下方「方法 C：手动安装」。安装完成后执行确认出现。完整安装与配置见下方「钉钉 Channel 插件（Stream 模式）完整说明」。

安装飞书插件（须先安装再配置）：

OpenClaw 当前仅支持，没有子命令。推荐顺序如下。

先用 npm 安装飞书（在任意目录执行）：
把已安装的 feishu 放到 OpenClaw 扩展目录，让网关能加载到：
- 打开目录：
- 若没有或文件夹，请新建
- 将你执行所在目录下的整个文件夹复制到（即最终路径为，其下包含 package.json 等文件）
重启网关后执行：
若列表中出现，说明飞书插件已生效。

若你更倾向用 CLI 安装（可能遇到 Windows 下）：

直接执行：
若报错，可改用 CMD 执行同一命令，或执行：

安装完成后执行，确认已启用的渠道（如、）状态为 loaded。

钉钉 Channel 插件（DingTalk Channel for OpenClaw）完整说明

插件仓库：https://github.com/soimy/openclaw-channel-dingtalk（钉钉企业内部机器人 Channel，Stream 模式：不需要透传、不需要公网 IP、不需要 Webhook，本地即可用钉钉；同作者另有 clawdbot-channel-dingtalk，CLI 安装时可能使用其一，二者兼容。）

功能特性

Stream 模式 — WebSocket 长连接，无需透传/公网 IP/Webhook，本地即可用钉钉
私聊 / 群聊支持，多种消息类型（文本、图片、语音、视频、文件）
Markdown 回复、互动卡片（流式更新，适合 AI 实时输出）
完整接入 OpenClaw 消息处理管道

安装方式（来源：openclaw-channel-dingtalk 官方 README）

方法 A：通过远程仓库安装（推荐）

在 PowerShell 或 CMD 中执行（任选一个仓库地址即可）：

或：

若在 Windows 下报，请改用下方方法 B 或方法 C。

方法 B：通过本地源码安装（便于二次开发）

从 openclaw-channel-dingtalk 克隆到本地并安装依赖后，以链接模式注册插件：

若需将插件固定到 OpenClaw 扩展目录（无需），可克隆到扩展目录后再执行验证：

方法 C：手动安装

从 https://github.com/soimy/openclaw-channel-dingtalk 下载 ZIP 或复制整个仓库到本地。
将解压/克隆后的目录整体放入（Windows：），确保该目录下包含、和。
在目录下执行安装依赖。
执行确认列表中出现。

更新插件：

钉钉后台配置（使用本插件时）

创建钉钉应用
访问钉钉开发者后台，创建企业内部应用，添加「机器人」能力，消息接收模式选择 Stream 模式，并发布应用。
权限管理
在应用 → 权限管理中开启：
- — 创建和投放卡片实例
- — 对卡片进行流式更新
建立卡片模板（可选，用于 AI 互动卡片）
访问钉钉卡片平台，创建模板，场景选择「AI 卡片」，不选预设模板直接保存，复制模板 ID（如），填到下方。
获取凭证
从开发者后台获取：Client ID (AppKey)、Client Secret (AppSecret)、Robot Code（与 Client ID 相同）、Corp ID（企业 ID）、Agent ID（应用 ID）。

OpenClaw 配置（openclaw.json）

在（Windows：）的下只添加 段，其他现有渠道保留不变：

/ / / / ：从钉钉后台获取并替换。
：（默认）或（AI 互动卡片，需配置）。
：私聊策略 — / / 。
：群聊策略 — / 。

保存后执行：

配置选项速查

选项类型默认值说明 enabled boolean true 是否启用 clientId string 必填 AppKey clientSecret string 必填 AppSecret robotCode string – 机器人代码 corpId string – 企业 ID agentId string – 应用 ID dmPolicy string “open” 私聊：open / pairing / allowlist groupPolicy string “open” 群聊：open / allowlist messageType string “markdown” markdown / card cardTemplateId string – AI 卡片模板 ID（messageType 为 card 时） debug boolean false 调试日志

故障排除

：钉钉 Stream 连接被拒，最常见原因是应用未切到 Stream 模式。请到钉钉开发者后台（见下）→ 你的应用 → 机器人与消息推送 → 机器人配置 里将 消息接收模式/连接方式 改为 Stream（不是 HTTP/Webhook），保存后重新发布应用，再重启网关。
后台找不到 Stream 选项：请确认使用的是 钉钉开发者后台 https://open-dev.dingtalk.com（不是 open.dingtalk.com）。入口：应用开发 → 进入你的应用 → 左侧 「机器人与消息推送」 → 打开 机器人配置，在表单里找「消息接收模式」或「连接方式」，选 Stream。若仍只有 HTTP/Webhook，可能是企业/应用类型或地区限制，可尝试新建一个「企业内部应用」再添加机器人看是否出现 Stream；若始终没有，则需改用 Webhook + 公网（cpolar）+ 钉钉消息接收 URL 或阿里云 AppFlow 方式对接。
收不到消息：确认应用已发布、消息接收模式为 Stream；查看日志：。
群消息无响应：确认机器人已加群、在群里正确 @ 机器人名称、群为企业内部群。
连接失败：检查 / 是否正确，确认本机网络可访问钉钉 API。

更多细节与开发指南见仓库：soimy/openclaw-channel-dingtalk。

钉钉接入实战配置过程（摘要）

按以下顺序操作即可完成从零到打通钉钉回复的全过程；所有密钥、Token、AppSecret 等均不在文档中写出，请从钉钉开放平台与 OpenClaw 控制台自行获取并填入。

安装钉钉插件（若 CLI 报 spawn EINVAL 则用手动安装）
- 插件仓库：https://github.com/soimy/openclaw-channel-dingtalk
- 在 PowerShell 中执行：
- 进入目录：
- 安装依赖：
- 重启网关后执行，确认出现。
钉钉开发者后台配置
- 打开 https://open-dev.dingtalk.com ，进入你的应用（或新建企业内部应用并添加机器人）。
- 机器人与消息推送 → 机器人配置 → 消息接收模式选择 Stream 模式，保存并发布应用。
- 权限管理：勾选、。
- 在应用信息/凭证页复制：Client ID（AppKey）、Client Secret（AppSecret）、Agent ID、企业 Corp ID（若需）。Robot Code 与 Client ID 相同即可。
编辑 openclaw.json
- 文件位置见下一小节。在下添加或修改段，填入上一步的 Client ID、Client Secret、Robot Code、Corp ID、Agent ID（不要将真实密钥写入公开文档）。
- 若通过 cpolar 等代理访问控制台，可在下配置（见下方示例）。
- 保存文件。
重启网关并验证
- 执行：
- 查看日志：，确认出现且无。
- 在钉钉单聊或群聊中 @ 机器人发一条消息，确认能收到 OpenClaw 的回复。
若无回复
- 先本机测试 agent：，确认大模型能正常返回。
- 确认 OpenClaw 的鉴权与模型配置（如 zai API Key）已在控制台或中正确配置。

openclaw.json 文件位置与完整示例（敏感信息已脱敏）

文件位置（请勿在公开场合泄露该文件内容）：

Windows：
macOS / Linux：

以下为与钉钉接入相关的结构示例，所有密钥、Token、AppSecret、API Key 等均用占位符表示，实际使用时请替换为你在钉钉开放平台与 OpenClaw 中获取的真实值，切勿将真实凭证写入本安装指南或对外分享的文档。

说明：

GLM（智谱）API Key：在智谱大模型开放平台 BigModel.cn 获取。GLM 邀请链接（注册即得 2000 万 Tokens 礼包）：https://www.bigmodel.cn/invite?icode=Ssx3UdmC76nwa7bdO5B1F0jPr3uHog9F4g5tjuOUqno%3D。注册后在控制台创建 API Key，填入或 OpenClaw Web 界面 Config → Authentication。
中的 API Key 等敏感信息通常在 OpenClaw 控制台或中配置，不一定要写在 JSON 里；若写在 JSON 中，请勿提交到公开文档。
的 / / / / 均需从钉钉开发者后台对应应用获取并替换占位符。
用于控制台与 API 鉴权，请勿使用示例中的占位符作为真实 Token。
：用于启用 web_search（实时搜索、股价等）。需在 Brave Search API 申请 Key，选择 Data for Search 计划，将替换为实际 Key；未配置时 Agent 会提示「搜索服务未配置」。若希望使用国内 API，见第十章「3. 配置 web_search」中的「国内用户：能否换成国内 API？」。

一、基础准备

在接入钉钉/飞书之前，先确认以下核心前提：

1.1 核心凭证准备

钉钉企业账号：拥有钉钉企业管理员权限，或自建测试企业
钉钉应用凭证：
- Client ID（即 AppKey）
- Client Secret（即 AppSecret）
OpenClaw Token：从配置文件获取
大模型 API Key：如果使用云端模型（如阿里云百炼）

1.2 服务状态确认

OpenClaw 网关已启动：
钉钉/飞书插件已安装并加载：
若未安装飞书，请先执行「零、安装钉钉与飞书插件」中飞书相关步骤。钉钉目前无官方，需用社区插件或 AppFlow 等方式。

1.3 本地机器特殊要求

仅用钉钉且采用 Stream 模式：不需要透传、不需要公网 IP，安装插件并配置好即可在本地使用钉钉。
要用飞书，或用 Webhook/AppFlow 方式对接钉钉：本地机器需做端口转发，并准备：
- 端口转发工具：ngrok、Tailscale、frp、cpolar（免费版域名为临时，重启后会变）等任选其一
- 公网域名/IP：由上述透传工具获得，并填到飞书/钉钉开放平台的「消息接收 URL」

二、端口转发（透传）配置（仅飞书 / Webhook 钉钉时需要）

说明：钉钉使用 Stream 模式时不需要透传，本地直接可用。以下透传仅在你需要飞书、或通过 阿里云 AppFlow / Webhook 对接钉钉、或从外网访问 OpenClaw 控制台时才需要。

透传指将本机端口通过公网域名暴露，使外网能访问本地 OpenClaw 网关（如 18789）。常用工具有 cpolar、ngrok、Tailscale 等。下文以 cpolar 为例说明安装与使用；cpolar 免费版域名为临时域名，重启后会变化，需在钉钉/飞书等配置中同步更新 URL。

2.1 使用 ngrok（推荐新手）

步骤 1：下载并安装 ngrok

访问 https://ngrok.com/ 注册账号，下载 Windows 版本。

步骤 2：启动端口转发

预期输出：

重要：复制这个 URL，这就是你的公网地址。

步骤 3：保持 ngrok 运行

ngrok 必须保持运行，否则公网地址会失效
建议：
- 使用新的 PowerShell 窗口运行 ngrok
- 或者后台运行

2.2 使用 Tailscale（推荐长期使用）

步骤 1：安装 Tailscale

访问 https://tailscale.com/ 下载 Windows 客户端并安装。

步骤 2：登录 Tailscale

步骤 3：启用 Tailscale Funnel

预期输出：

重要：复制这个 URL。

2.3 使用 cpolar 做透传（免费方案，域名临时）

cpolar 可将本机端口透传到公网，使外网通过生成的域名访问你的 OpenClaw 网关。注意：cpolar 免费版分配的域名是临时的，每次重启 cpolar 或过期后会变化，需在钉钉/飞书/AppFlow 等配置中同步更新「消息接收地址」或「事件请求 URL」。

步骤 1：下载并安装 cpolar

访问 https://www.cpolar.com/download 或 https://cpolar.com/，注册账号并下载 Windows 版本安装包。
运行安装程序，按提示完成安装（默认会安装到）。
（可选）将加入系统环境变量 Path，以便在任意目录执行；未添加时需在该目录下用执行。

步骤 2：认证（首次使用必须执行一次）

登录 cpolar 官网控制台，在「隧道」或「认证」页面获取你的 authtoken。
打开 PowerShell 或 CMD，进入 cpolar 安装目录并执行认证（将下面的替换为实际 token）：

看到 “Authtoken saved to configuration file” 即表示认证成功。

步骤 3：启动透传（将本机 18789 透传到公网）

在 PowerShell 或 CMD 中执行（若未将 cpolar 加入 Path，需先）：

预期输出（示例）：

重要：复制终端里显示的 公网地址（如或），即为当前透传域名。
域名是临时的：免费版下该域名在 cpolar 重启或过期后会变，变更后需到钉钉/飞书/OpenClaw 等配置里更新为新的地址（例如钉钉消息接收地址改为）。
透传期间请保持该终端窗口不关闭，关闭后透传会断开，外网无法访问。

步骤 4：访问 OpenClaw 控制台（若通过透传访问）

在浏览器中访问（将换为步骤 3 中复制的地址，换为 openclaw 网关 token）：

2.4 验证端口转发

在浏览器中访问你的公网地址：

如果能看到 OpenClaw 管理界面：端口转发成功 ✓
如果无法访问：

检查 ngrok/Tailscale/cpolar 是否运行
检查端口 18789 是否正确
尝试访问 http://localhost:18789 确认本地服务正常

三、创建钉钉应用

3.1 登录钉钉开放平台

访问：https://open-dev.dingtalk.com/

3.2 创建应用

点击”创建应用”
选择”企业内部机器人”
填写基本信息：
- 应用名称：如”OpenClaw 本地助手”
- 应用描述：如”基于 OpenClaw 的本地 AI 助手”
- 应用图标：上传机器人头像

3.3 获取凭证

进入应用详情页，复制以下信息：

重要：妥善保管这两个凭证，不要泄露。

四、配置钉钉机器人

若使用钉钉 Channel 插件（Stream 模式）（推荐）：无需配置「消息接收地址」、无需透传，按本章「钉钉 Channel 插件完整说明」在钉钉后台选 Stream 模式 并填好即可。以下 4.1～4.4 为 Webhook 方式 或通用步骤参考。

4.1 发布应用（关键步骤）

重要：仅创建应用是不够的，必须发布！

进入应用的”版本管理与发布”
点击”创建新版本”
填写版本信息：
- 版本号：如
- 版本描述：如”测试 OpenClaw 连接”
选择可见范围：
- 测试阶段：选择”仅自己可见”
点击”保存→直接发布”
等待 5-10 秒生效

4.2 配置消息接收地址（仅 Webhook 方式需要）

Stream 模式不需要此项（不填消息接收地址、不需透传）。以下仅在使用 Webhook / AppFlow 方式对接钉钉时需要：

在应用详情页，找到「机器人」部分：

开启「消息接收」
设置「消息接收地址」：
- 使用你的透传公网 URL 替换
- 路径固定为
勾选”加签验证”（可选，增加安全性）

4.3 配置机器人信息

设置机器人基本信息：

机器人名称：OpenClaw
机器人描述：本地 AI 助手
机器人头像：上传图片

4.4 设置权限

进入”权限管理”，添加以下权限：

（查看联系人）
（添加联系人）
（发送消息）
（会话权限）

五、配置 OpenClaw 钉钉/飞书插件

5.1 编辑配置文件

打开 OpenClaw 配置文件：

5.2 添加钉钉配置

若使用「钉钉 Channel 插件（Stream 模式）」（推荐）：请直接按本章「钉钉 Channel 插件（DingTalk Channel for OpenClaw）完整说明」中的示例配置，字段为、、、、、、、、等，无需。

若使用 Webhook / AppFlow 方式对接钉钉（需公网与端口转发），则在中使用 webhook 类配置（具体字段以所用插件文档为准），例如：

请勿在同一个中混用 Stream 插件字段与 Webhook 字段；二选一即可。

5.2.1 飞书配置（可选）

前提：已按本章「零、安装钉钉与飞书插件」完成飞书安装（并将复制到，或使用），并在中看到。

若同时接入飞书，在的中增加节点。飞书需先在飞书开放平台创建自建应用并获取 App ID、App Secret、Verification Token（事件订阅验证用），将「事件请求地址」设为你的公网地址 + 飞书 webhook 路径（如）。配置示例：

飞书开放平台：https://open.feishu.cn/
路径：事件订阅/消息接收地址填（与一致）。

5.3 保存并重启网关

六、创建测试群并测试

6.1 创建测试群（钉钉 / 飞书）

钉钉：

在钉钉中手动创建一个新群
仅添加你自己和机器人
进入「群设置 → 群机器人 → 添加机器人」
选择你的 OpenClaw 应用

飞书：

在飞书中创建新群聊，进入「群设置 → 群机器人 → 添加机器人」
选择你已创建的自建应用（OpenClaw）
确认应用已发布并启用机器人能力

重要：钉钉不要使用默认测试群；飞书需确保应用已发布到测试环境或企业内。

6.2 测试机器人

在钉钉或飞书测试群中：

@机器人发送：「你好」
观察机器人是否响应

如果机器人回复：配置成功 ✓
如果机器人无响应：继续排查（见下方常见问题）

七、常见问题排查

问题 1：机器人完全无响应

现象：

@机器人无任何反应
既无回复，也无”处理中”提示

原因排查：

应用未发布
- 检查：进入钉钉开放平台→应用详情→版本管理
- 解决：创建新版本并发布（见 4.1）
端口转发工具未运行
- 检查：ngrok/Tailscale/cpolar 窗口是否打开
- 解决：重新启动端口转发工具
webhook URL 错误
- 检查：URL 格式是否为
- 解决：修正 URL 格式
使用默认测试群
- 检查：是否在钉钉默认测试群测试
- 解决：创建新测试群（见 6.1）

问题 2：机器人显示”处理中”但无结果

现象：

钉钉显示”处理中”
AppFlow 有日志但无错误

原因排查：

OpenClaw 配置错误
- 检查：中的钉钉配置是否正确
- 解决：核对 appKey、appSecret、webhookUrl
端口转发地址变化
- 检查：ngrok/Tailscale/cpolar 地址是否变化
- 解决：更新 webhookUrl 并重启网关
模型未配置
- 检查：OpenClaw 是否配置了模型
- 解决：配置 Ollama 或云端模型

问题 3：报错”Connection refused”

现象：

执行日志报错”连接被拒绝”
机器人无响应

原因排查：

端口转发工具故障
- 检查：ngrok/Tailscale/cpolar 是否正常运行
- 解决：重新启动端口转发工具
OpenClaw 网关未启动
- 检查：
- 解决：
Windows 防火墙拦截
- 检查：Windows Defender 防火墙是否拦截 18789 端口
- 解决：添加入站规则允许 18789 端口

问题 4：AppFlow 执行日志报错

常见报错及解决方案：

报错信息原因解决方案参数格式错误检查 webhook URL 格式是否正确 AI 卡片模板错误重新创建空白 AI 卡片网关无法访问检查端口转发工具和网关状态 HTTP 方法不支持启用 HTTP Methods Support

八、使用阿里云 AppFlow 对接（可选）

如果你想通过阿里云 AppFlow 对接钉钉：

8.1 创建连接流

登录阿里云 AppFlow 工作台
创建新连接流
选择”HTTP 请求”触发器
配置 webhook URL：

8.2 配置执行动作

选择”发送钉钉机器人消息”动作，配置：

机器人编码：从钉钉应用详情页获取
消息类型：文本
消息内容：使用变量

8.3 发布连接流

点击”发布”，等待生效。

九、端口转发工具对比

工具优点缺点适用场景下载/官网 ngrok 简单易用，快速上手免费版域名会变化测试、临时使用 https://ngrok.com/download Tailscale 稳定、安全、持久需要学习成本长期使用、生产环境 https://tailscale.com/download cpolar 免费、中文友好免费版有速度限制；域名为临时，重启后变化个人学习、测试、透传 https://www.cpolar.com/download frp 可控性强、稳定需要自建服务器进阶用户、企业使用 https://github.com/fatedier/frp/releases

十、本地机器钉钉/飞书接入总结

钉钉（Stream 模式）：不需要透传。关键步骤为：安装钉钉 Channel 插件 → 钉钉后台创建应用并选 Stream 模式 → 在的中配置 clientId、clientSecret 等 → 重启网关 → 在钉钉中加群/单聊测试。

飞书或 Webhook 方式对接钉钉：需要透传，步骤概括为：

关键要点：

钉钉用 Stream 时不需要透传：无需公网 IP、无需端口转发，本地即可使用钉钉。
飞书或 Webhook 钉钉才需要透传：端口转发工具须保持运行；ngrok/cpolar 免费版域名为临时，变更后需更新开放平台中的 URL。
应用必须发布：仅创建应用不够，必须发布才能生效。
创建新测试群：不要使用钉钉默认测试群。
妥善保管凭证：AppKey、AppSecret、OpenClaw Token 都要保密。

推荐配置：

钉钉：Stream 模式，无需透传。
飞书 / Webhook 钉钉：端口转发可用 Tailscale（稳定）；OpenClaw 网关端口 18789；飞书事件请求地址填。

参考资源：

钉钉开放平台：https://open-dev.dingtalk.com/
飞书开放平台：https://open.feishu.cn/
ngrok 官方网站：https://ngrok.com/
Tailscale 官方网站：https://tailscale.com/
cpolar 官方网站：https://cpolar.com/
阿里云 AppFlow 工作台：https://appflow.aliyun.com/

本章基于阿里云官方文档与开发者社区实践，按问题类型整理「现象 → 原因 → 解决步骤」，覆盖从配置到验证的全流程，适用于本地机器与云服务器（如阿里云轻量）。以下以钉钉为主，飞书接入思路类似（应用发布、webhook URL、端口放行等），可对照参考。

一、基础准备：先确认这 3 件事（避免 80% 基础错误）

提醒：钉钉使用 Stream 模式（钉钉 Channel 插件）时，不需要透传、不需要公网 IP，本地即可使用；以下排查同时适用于 Stream 与 Webhook/AppFlow 方式。

在排查具体问题前，先核对以下核心前提，多数「莫名报错」源于基础配置缺失：

检查项说明 服务器与权限 云服务器建议内存 ≥ 2GiB；拥有钉钉企业管理员权限或自建测试企业 核心凭证正确 已获取钉钉 Client ID（AppKey）、Client Secret（AppSecret），且未泄露、未过期 服务状态正常 OpenClaw 网关已启动（显示 running）；若使用插件渠道，需在中看到对应 channel（如 feishu/dingtalk）为 loaded（钉钉推荐用社区 Stream 插件，无需透传）

二、高频踩坑场景与解决方案

场景 1：钉钉机器人「无任何响应」（最常见）

现象：

在钉钉私聊/群聊 @ 机器人发送消息，机器人完全没反应，既无文字回复，也无「处理中」提示
阿里云 AppFlow「执行日志」页面无任何日志记录

核心原因（按排查优先级）：

钉钉应用未发布最新版本：仅发布「机器人」无效，需同步发布「钉钉应用」
消息接收地址 URL 格式错误：HTTP/HTTPS、域名/IP 端口不匹配
使用钉钉默认测试群：测试群存在环境限制，导致消息无法触达
连接流未配置或未发布：AppFlow 中未创建对接 OpenClaw 的连接流，或配置后未发布

解决方案：

检查并发布钉钉应用：
- 登录钉钉开放平台 → 目标应用 →「版本管理与发布」
- 点击「创建新版本」，填写版本号（如 1.0.1）和描述
- 选择可见范围（测试阶段选「仅自己可见」）→「保存 → 直接发布」，等待 5–10 秒生效
核对消息接收地址 URL：
- AppFlow 对接：URL 必须为（从 AppFlow 连接流详情页复制）
- 直连模式：URL 为（端口固定 18789，勿加 https）
自建测试群：在钉钉手动创建新群（仅自己和机器人），在「群设置 → 群机器人 → 添加机器人」中选择目标应用，在新群 @ 机器人发「你好」测试
检查 AppFlow 连接流：在阿里云 AppFlow 工作台通过 Webhook URL 定位连接流，确认 OpenClaw 凭证、钉钉 Client ID/Secret、公网地址（IP:18789）正确后点击「发布」

场景 2：机器人仅显示「处理中」，不输出内容

现象：发送消息后钉钉显示「处理中」，长时间无结果；AppFlow 执行日志有记录但无报错或报错「模型调用失败」。

核心原因：大模型 API Key 错误/过期；OpenClaw 网关异常；连接流模型名称格式错误或选了不支持的模型。

解决方案：

验证并更新大模型 API Key：打开 OpenClaw Web UI → Settings → Config → Authentication → Raw，在节点核对 apiKey，修改后 Save → Update
重启 OpenClaw 网关：，等待约 10 秒后确认 running
修正连接流模型配置：模型名称格式为（如），模型 Code 在阿里云百炼模型广场查询，选择支持流式调用的版本

场景 3：控制面板返回，无法访问 Web UI

现象：访问 OpenClaw Web UI（如或公网地址）时页面不显示，仅返回 JSON ；钉钉机器人功能正常但无法配置 OpenClaw。

核心原因：钉钉插件的 webhook 处理逻辑拦截了所有 HTTP 请求，对非钉钉请求也返回，导致 Web UI 被拦截。

解决方案（已验证有效）：

找到并编辑 ：
- Windows：
- macOS/Linux：
修改函数开头：在函数最顶部增加「仅处理钉钉专属请求」的判断，其余代码不变：

重启网关生效：执行，再次访问 Web UI 即可正常显示控制面板。

场景 4：报错「Connect to xxx failed: Connection refused」

现象：执行日志报错「连接被拒绝」或机器人无响应；本地可访问 Web UI 但钉钉无法触达。

核心原因：公网地址未带端口 18789；服务器安全组/防火墙未放行 18789；未添加钉钉 IP 白名单。

解决方案：

公网地址格式：正确格式为（如），勿加或
配置服务器安全组（阿里云）：轻量应用服务器 → 防火墙 → 添加规则，端口 18789，授权对象中需包含钉钉官方 IP：
云防火墙：若开启阿里云云防火墙，需在「访问控制 → 入站规则」中放行上述 IP 与 18789 端口

场景 5：报错「The provided parameter ‘input’ is invalid」

现象：钉钉测试或 AppFlow「运行一次」时执行日志报「输入参数无效」。

核心原因：误用 AppFlow「运行一次」功能（仅用于调试连接流，不支持钉钉实际消息）；连接流输入参数（如公网地址、模板 ID）为空或格式错误。

解决方案：

不要使用「运行一次」，直接在自建测试群 @ 机器人发送消息触发真实请求
核对连接流：公网地址带 18789 端口；模板 ID 从钉钉「卡片平台」新建空白 AI 卡片获取；模型名称为格式

场景 6：报错「Method Not Allowed http response」

现象：执行日志报「ClawdBot Method Not Allowed」；钉钉消息无法触达 OpenClaw。

核心原因：OpenClaw 网关未开启对钉钉所用 HTTP 方法的支持。

解决方案：

打开 Web UI → Settings → Config → Gateway
在「Gateway Server Settings」中启用「HTTP Methods Support」（勾选 GET、POST）
若使用大模型流式调用，启用「OpenAI Chat Completions Endpoint」
保存后执行

场景 7：钉钉最后节点报错「unknown error」

现象：执行日志显示「钉钉节点 unknown error」；机器人「处理中」后无结果或直接报错。

核心原因：钉钉 AI 卡片模板使用预设模板或未关联应用，导致消息无法正常渲染。

解决方案：

钉钉开放平台 → 卡片平台 → 新建模板：类型选「消息卡片」，场景选「AI 卡片」，关联目标应用；勿用预设模板，保存后发布
复制新 AI 卡片的「模板 ID」，在 AppFlow 连接流详情页「执行动作配置」中替换模板 ID，发布后重新在钉钉测试

三、排查优先级：3 步定位问题

遇到未明确分类的问题时，按以下顺序可快速缩小范围：

步骤操作 第一步 查 AppFlow「执行日志」：无日志 → 优先查应用发布、URL、测试群（场景 1）；有日志 → 看报错关键词（Connection refused → 场景 4，input invalid → 场景 5） 第二步 核对接入要素：凭证（钉钉 Client ID/Secret、OpenClaw Token、大模型 API Key）；网络（公网地址 IP:18789、18789 放行、钉钉 IP 白名单）；模式（AppFlow 用 HTTP 模式，直连可用 Stream） 第三步 重启验证：，可选

四、总结：关键避坑点（新手必看）

「发布」是核心：钉钉应用、连接流、AI 卡片均需「发布」，仅创建不发布会导致无响应
格式别错：公网地址不带协议头（如），模型名称带前缀
模板要空白：钉钉 AI 卡片必须新建空白模板，使用预设模板易报「unknown error」
日志是关键：所有问题先查 AppFlow 执行日志；无日志查配置，有日志查关键词

按本节步骤排查，可解决 OpenClaw 接入钉钉绝大多数常见问题。若仍有异常，可参考 OpenClaw 官方文档或阿里云开发者社区，提交问题时附执行日志截图（隐去凭证）便于定位。

智谱 GLM 邀请福利（文末再次提醒）：本教程推荐使用智谱 GLM-4.7（BigModel.cn）。通过下方邀请链接注册即可获得 2000 万 Tokens 大礼包，便于在 OpenClaw 中畅享 GLM 能力。

GLM 邀请链接（注册即得 2000 万 Tokens）：https://www.bigmodel.cn/invite?icode=Ssx3UdmC76nwa7bdO5B1F0jPr3uHog9F4g5tjuOUqno%3D
平台：智谱大模型开放平台 BigModel.cn

发布者：Ai探索者，转载请注明出处：https://javaforall.net/253629.html原文链接：https://javaforall.net

Windows 11 安装 OpenClaw 完整教程

（一）系统要求

（二）核心依赖检查

1. 检查 Node.js 版本

2. 检查 PowerShell 执行权限

3. 检查 Ollama 安装（可选）

4. 检查已安装的 Ollama 模型

5. 可选工具准备

方法一：官方一键安装脚本（推荐）

方法二：通过 npm 安装

方法三：通过 pnpm 安装（官方推荐）

1. 安装 pnpm

2. 配置 pnpm 环境

3. 安装 OpenClaw

4. 验证安装

当前安装状态记录

配置向导步骤

1. 检查网关服务

2. 访问 Web 管理界面

1. Ollama 模型选择指南

推荐模型列表

下载模型

2. 确保 Ollama 服务运行

3. 测试 Ollama 模型

4. 配置 OpenClaw 连接 Ollama

5. 测试 OpenClaw + Ollama 集成

6. 多模型配置（可选）

7. 常见问题

问题 1：模型响应非常慢

问题 2：OpenClaw 无法连接到 Ollama

问题 3：模型中文效果不佳

1. 基础对话

2. 文件读取

3. 命令执行

问题 1：“openclaw” 命令失效

问题 2：网关未授权（令牌缺失）

问题 3：Web 界面无法访问

问题 4：本地模型响应缓慢

问题 5：网关服务安装失败

问题 6：模型不支持图片输入

安全防护

性能优化

1. 对接云端大模型（本教程以 GLM 为主）

2. 绑定钉钉/飞书/Telegram 交互渠道

3. 配置 web_search（获取实时股价、搜索等）

如何申请 Brave Search API Key

国内用户：能否换成国内 API？

4. 启用自动化任务

1. 安装过程记录

1.1 OpenClaw 安装

2. 网关服务启动问题

2.1 首次启动网关

2.2 解决方案：直接启动网关

3. Web 界面访问问题

3.1 令牌认证失败

3.2 获取令牌

3.3 解决方案：通过 URL 添加令牌

4. 模型图片输入问题

4.1 问题描述

4.2 解决方案：下载多模态模型

4.3 测试图片识别

4.4 在 OpenClaw 中使用

5. 调试经验总结

5.1 关键问题

5.2 推荐安装流程

5.3 配置 Ollama 多模态模型

5.4 注意事项

5.5 故障排查清单

6. 最终配置状态

OpenClaw 命令帮助速查

零、安装钉钉与飞书插件（必须先执行）

钉钉 Channel 插件（DingTalk Channel for OpenClaw）完整说明

功能特性

安装方式（来源：openclaw-channel-dingtalk 官方 README）

钉钉后台配置（使用本插件时）

OpenClaw 配置（openclaw.json）

配置选项速查

故障排除

钉钉接入实战配置过程（摘要）

openclaw.json 文件位置与完整示例（敏感信息已脱敏）

二、端口转发（透传）配置（仅飞书 / Webhook 钉钉时需要）

场景 3：控制面板返回，无法访问 Web UI