Windows 11 安装 OpenClaw 完整教程

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

hzether

12511人浏览 · 2026-02-05 08:28:10

hzether · 2026-02-05 08:28:10 发布

Windows 11 安装 OpenClaw 完整教程

在这里插入图片描述

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 简介

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，输入：

node -v

要求：版本 ≥ v22

当前系统状态：

✓ Node.js v22.19.0
✓ npm 8.19.4

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

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

2. 检查 PowerShell 执行权限

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

# 以管理员身份运行 PowerShell
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
# 出现提示时输入 Y 并回车

当前系统状态：

✓ RemoteSigned（已启用）

3. 检查 Ollama 安装（可选）

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

检查 Ollama 是否已安装：

ollama --version

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

ollama version is 0.1.x

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

4. 检查已安装的 Ollama 模型

查看本地已安装的模型：

ollama list

预期输出：

NAME           ID              SIZE      MODIFIED
llama3:8b      a80c4f17acd5    4.7 GB    2 hours ago

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

常用模型推荐：

# Llama 3 8B（推荐，平衡性能和速度）
ollama pull llama3:8b

# Llama 3 8B 量化版（更快，但精度略低）
ollama pull llama3:8b-q4

# Qwen 2.5 7B（中文优化）
ollama pull qwen2.5:7b

# Mistral 7B（优秀的开源模型）
ollama pull mistral:7b

5. 可选工具准备

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

三、安装 OpenClaw 主程序

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

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

iwr -useb https://clawd.bot/install.ps1 | iex

安装说明：

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

方法二：通过 npm 安装

npm install -g openclaw@latest

注意事项：

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

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

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

1. 安装 pnpm

npm install -g pnpm

2. 配置 pnpm 环境

pnpm setup

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

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

[Environment]::SetEnvironmentVariable("PNPM_HOME", "$env:LOCALAPPDATA\pnpm", "User")

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

3. 安装 OpenClaw

在新 PowerShell 窗口中运行：

pnpm add -g openclaw@latest

4. 验证安装

openclaw --version

预期输出：

2026.2.1

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

当前安装状态记录

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

官方脚本超时：执行 iwr -useb https://clawd.bot/install.ps1 | iex 时超时

npm 安装文件被占用：执行 npm install -g openclaw@latest 时遇到 EBUSY/ENOTEMPTY 错误

npm WARN cleanup Failed to remove some directories [
  'C:\\Users\\Administrator\\AppData\\Roaming\\npm\\node_modules\\openclaw',
  [Error: EBUSY: resource busy or locked, rmdir 'C:\Users\Administrator\AppData\Roaming\npm\node_modules\openclaw']
]

原因：可能有之前的安装进程还在运行
解决方案：重启电脑后重试

使用 pnpm 成功安装：
- 安装 pnpm：npm install -g pnpm ✓ 成功
- 配置 pnpm：pnpm setup ✓ 成功
- 安装 OpenClaw：pnpm add -g openclaw@latest ✓ 成功
- 验证版本：openclaw --version 显示 2026.2.1 ✓ 成功

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

四、初始化配置

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

openclaw onboard

配置向导步骤

运行模式（Mode）
- 选择：QuickStart（快速启动，跳过复杂配置）
模型提供商（Provider）
- 推荐：选择 Zai（智谱 GLM）等云端模型，在控制台或 openclaw configure 中配置 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 时：如 zai/glm-4.7 或 zai/glm-4.7-flash。
- 使用 Ollama 时：如 ollama/llama3:8b。
交互渠道（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. 检查网关服务

openclaw gateway status

预期输出：Gateway is running

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

openclaw gateway start

等待 10 秒后再次验证。

2. 访问 Web 管理界面

打开浏览器，访问：

http://localhost:18789

首次访问需要令牌：

找到配置文件：

C:\Users\你的用户名\.openclaw\openclaw.json

用记事本打开，搜索 “token”：
```
"token": "c25bbh909c7xxxxxxxxxx"
```
复制引号内的令牌字符串
在浏览器"未授权"页面粘贴令牌并确认

六、配置本地 Ollama 模型（可选）

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

1. Ollama 模型选择指南

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

模型名称	参数量	磁盘占用	内存需求	适用场景
llama3:8b	8B	~4.7 GB	≥8 GB	通用场景，平衡性能和速度
llama3:8b-q4	8B（量化）	~5 GB	≥6 GB	速度优先，适合测试
llama3:70b	70B	~40 GB	≥32 GB	高质量推理，需要大内存
qwen2.5:7b	7B	~4.3 GB	≥8 GB	中文优化，适合中文场景
qwen2.5:14b	14B	~8.5 GB	≥16 GB	中文场景，质量更高
mistral:7b	7B	~4.1 GB	≥8 GB	开源优秀模型，通用性好
gemma2:9b	9B	~5.4 GB	≥8 GB	Google 开源模型

下载模型

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

# 下载 Llama 3 8B（推荐）
ollama pull llama3:8b

# 下载 Llama 3 8B 量化版
ollama pull llama3:8b-q4

# 下载 Qwen 2.5 7B（中文优化）
ollama pull qwen2.5:7b

# 下载 Mistral 7B
ollama pull mistral:7b

下载提示：若下载较慢，可配置镜像源或使用代理；下载完成后模型会保存在 C:\Users\你的用户名\.ollama\models。

2. 确保 Ollama 服务运行

检查 Ollama 服务状态：

ollama list

预期输出：

NAME           ID              SIZE      MODIFIED
llama3:8b      a80c4f17acd5    4.7 GB    2 hours ago

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

ollama serve

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

3. 测试 Ollama 模型

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

ollama run llama3:8b "你好"

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

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

4. 配置 OpenClaw 连接 Ollama

在 OpenClaw Web 界面中：

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

在配置文件中添加模型（可选）：

编辑配置文件 C:\Users\你的用户名\.openclaw\openclaw.json：

{
  "agent": {
    "model": "ollama/llama3:8b"
  },
  "models": {
    "providers": {
      "ollama": {
        "baseUrl": "http://localhost:11434"
      }
    }
  }
}

5. 测试 OpenClaw + Ollama 集成

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

方法一：通过命令行测试

openclaw agent --message "你好，介绍一下你自己"

方法二：通过 Web 界面测试

打开 http://localhost:18789

在对话框输入：

使用本地 llama3 模型回答：你好，介绍一下你自己

预期结果：

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

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

6. 多模型配置（可选）

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

在对话中指定模型：

使用 qwen2.5 模型回答：今天天气怎么样？

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

{
  "agent": {
    "model": "ollama/qwen2.5:7b"
  }
}

查看所有可用模型：

ollama list

7. 常见问题

问题 1：模型响应非常慢

可能原因：

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

解决方案：

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

问题 2：OpenClaw 无法连接到 Ollama

排查步骤：

检查 Ollama 服务是否运行：
```
ollama list
```
检查端口是否被占用：
```
netstat -ano | findstr :11434
```
测试 Ollama API：
```
curl http://localhost:11434/api/tags
```

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

解决方案：

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

七、功能验证测试

1. 基础对话

输入：

介绍一下你自己

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

2. 文件读取

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

读取 C:\Users\你的用户名\Desktop\test.txt 文件内容

3. 命令执行

输入：

查看当前磁盘 C 的占用情况

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

八、常见问题排查

问题 1：“openclaw” 命令失效

现象：提示"无法识别"

解决方案：

重启 PowerShell
使用 npx openclaw 临时执行
手动配置环境变量：
- 将 C:\Users\你的用户名\AppData\Roaming\npm 或 %LOCALAPPDATA%\pnpm 添加到系统 PATH
- 重启终端
检查 pnpm 环境：
```
pnpm setup
```
然后关闭并重新打开 PowerShell

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

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

日志输出：

[ws] unauthorized conn=xxx remote=127.0.0.1 client=openclaw-control-ui webchat vdev reason=token_missing
[ws] closed before connect conn=xxx code=4008 reason=connect failed

解决方案：

查找令牌：

Get-Content C:\Users\你的用户名\.openclaw\openclaw.json | Select-String 'token'

预期输出：

"token": "d055c9a4221dd22e1edfe84c3c00a0c12045ccbc49fb4a91"

在浏览器中输入令牌：
- 打开 http://localhost:18789
- 在"未授权"页面输入令牌
- 或者直接访问带令牌的 URL：
```
http://localhost:18789?token=d055c9a4221dd22e1edfe84c3c00a0c12045ccbc49fb4a91
```
刷新页面，应该能看到管理界面

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

{
  "gateway": {
    "auth": {
      "mode": "disabled"
    }
  }
}

问题 3：Web 界面无法访问

排查步骤：

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

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

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

解决方案：

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

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

现象：

Gateway service missing.
Start with: openclaw gateway install

尝试安装时报错：

Gateway install failed: Error: schtasks create failed: spawn EPERM

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

解决方案：

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

# 以管理员身份打开 PowerShell，然后运行
openclaw gateway install

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

# 直接启动网关，不安装为服务
openclaw gateway --port 18789

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

方法 3：后台运行网关

# 在新窗口启动网关
Start-Process powershell -ArgumentList "-NoExit", "-Command", "openclaw gateway --port 18789"

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

schtasks /Create /TN "OpenClaw Gateway" /TR "openclaw gateway --port 18789" /SC ONLOGON /RU Administrator /RL HIGHEST

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

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

现象：

ERROR: Cannot read "68deb2d5-dfe0-4294-992c-cf16faa214a8.png" (this model does not support image input). Inform the user.

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

解决方案：

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

# 下载 LLaVA（推荐）
ollama pull llava:latest

# 或者下载 MiniCPM-V（中文优化）
ollama pull minicpm-v:latest

# 或者下载 LLaVA-NeXT（更强大）
ollama pull llava-llama3:latest

下载过程：

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

步骤 2：验证模型下载

ollama list

预期输出：

NAME           ID              SIZE      MODIFIED
llama3:8b      a80c4f17acd5    4.7 GB    2 hours ago
llava:latest    xxxxxxxxxxxxxx   4.7 GB    just now

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

通过命令行测试：

ollama run llava:latest "描述一下这张图片"

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

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

使用 llava 模型查看并分析这张图片：68deb2d5-dfe0-4294-992c-cf16faa214a8.png

方法 B：修改默认模型

编辑配置文件 C:\Users\你的用户名\.openclaw\openclaw.json：

{
  "agent": {
    "model": "ollama/llava:latest"
  }
}

保存后重启网关：

openclaw gateway restart

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

openclaw agent --model ollama/llava:latest --message "查看这张图片：test.png"

推荐模型对比：

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

提示：

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

九、优化建议

安全防护

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

性能优化

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

使用 npm 更新：

npm update -g openclaw

或使用 pnpm 更新（推荐）：

pnpm update -g openclaw

更新前备份配置文件 openclaw.json 或 ~/.openclaw/openclaw.json

十、进阶配置（可选）

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

本教程示例已采用 GLM（智谱），在 openclaw.json 的 auth.profiles 与 agents.defaults.model 中配置 zai/glm-4.7 等即可。若机器性能一般，不必强求本地 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 的 auth.profiles 或 Web 界面 Config → Authentication。

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

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

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

钉钉配置示例：

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

飞书配置示例：

登录飞书开放平台（https://open.feishu.cn/），创建企业自建应用
获取 App ID、App Secret，并开通「机器人」能力与消息权限
在 OpenClaw Web 界面或 openclaw.json 的 channels.feishu 中配置飞书渠道（含 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，填写应用名称（如 OpenClaw）。
- 创建成功后，在应用详情页会显示 API Key（一长串字符）。
- 点击 Copy 或手动复制，保存到本地（不要泄露或写进公开文档）。
填入 openclaw.json
将复制的 API Key 填入下方配置中的 apiKey 字段。

在 openclaw.json 中配置：

文件位置：Windows 下为 C:\Users\你的用户名\.openclaw\openclaw.json。
在根节点下增加（或合并到已有）tools 段，将 apiKey 换成你的 Key：

"tools": {
  "web": {
    "search": {
      "provider": "brave",
      "apiKey": "你的Brave_Search_API_Key",
      "maxResults": 5,
      "timeoutSeconds": 30
    }
  }
}

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

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

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

目前 OpenClaw 官方文档中，web_search 主要支持 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：官方脚本安装

iwr -useb https://clawd.bot/install.ps1 | iex

结果：超时失败

尝试 2：npm 安装

npm install -g openclaw@latest

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

npm WARN cleanup Failed to remove some directories
[Error: EBUSY: resource busy or locked]

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

尝试 3：pnpm 安装（成功）

# 安装 pnpm
npm install -g pnpm

# 配置 pnpm 环境
pnpm setup

# 安装 OpenClaw
pnpm add -g openclaw@latest

# 验证安装
openclaw --version
# 输出：2026.2.1 ✓

2. 网关服务启动问题

2.1 首次启动网关

尝试 1：启动网关

openclaw gateway start

错误信息：

Gateway service missing.
Start with: openclaw gateway install

尝试 2：安装网关服务

openclaw gateway install

错误信息：

Gateway install failed: Error: schtasks create failed: spawn EPERM

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

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

最终方案：

# 直接启动网关（不安装为服务）
openclaw gateway --port 18789

结果：成功启动

网关启动日志：

🦞 OpenClaw 2026.2.1 (ed4529e) — Meta wishes they shipped this fast.
[ws] Server listening on http://127.0.0.1:18789
[hooks] loaded 3 internal hook handlers

3. Web 界面访问问题

3.1 令牌认证失败

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

错误日志：

[ws] unauthorized conn=cc6c62ce-b55d-4d92-afb5-ec58e74a2fb6 remote=127.0.0.1 client=openclaw-control-ui webchat vdev reason=token_missing
[ws] closed before connect conn=cc6c62ce-b55d-4d92-afb5-ec58e74a2fb6 code=4008 reason=connect failed

3.2 获取令牌

查找令牌：

Get-Content C:\Users\Administrator\.openclaw\openclaw.json | Select-String 'token'

输出：

"token": "d055c9a4221dd22e1edfe84c3c00a0c12045ccbc49fb4a91"

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

访问带令牌的 URL：

http://localhost:18789?token=d055c9a4221dd22e1edfe84c3c00a0c12045ccbc49fb4a91

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

4. 模型图片输入问题

4.1 问题描述

错误信息：

ERROR: Cannot read "68deb2d5-dfe0-4294-992c-cf16faa214a8.png" (this model does not support image input). Inform the user.

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

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

下载 LLaVA 模型：

ollama pull llava:latest

下载过程：

pulling manifest
pulling 170370233dd5: 100% ▕██████████████████▏ 4.1 GB
pulling 72d6f08a42f6: 100% ▕██████████████████▏ 624 MB
verifying sha256 digest
writing manifest
success

验证模型：

ollama list

输出：

NAME           ID              SIZE      MODIFIED
llama3:8b      a80c4f17acd5    4.7 GB    2 hours ago
llava:latest    xxxxxxxxxxxxxx   4.7 GB    just now

4.3 测试图片识别

通过 Ollama 测试：

ollama run llava:latest "描述一下这张图片"

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

4.4 在 OpenClaw 中使用

方法 1：在对话中指定

使用 llava 模型查看并分析这张图片：test.png

方法 2：修改配置文件

编辑 C:\Users\Administrator\.openclaw\openclaw.json：

{
  "agent": {
    "model": "ollama/llava:latest"
  }
}

重启网关：

openclaw gateway restart

5. 调试经验总结

5.1 关键问题

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

5.2 推荐安装流程

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

# 1. 安装 pnpm（官方推荐）
npm install -g pnpm
pnpm setup

# 2. 安装 OpenClaw
pnpm add -g openclaw@latest

# 3. 验证安装
openclaw --version

# 4. 启动网关（直接启动，无需安装服务）
openclaw gateway --port 18789

# 5. 获取令牌
Get-Content $env:USERPROFILE\.openclaw\openclaw.json | Select-String 'token'

# 6. 访问 Web 界面（替换 YOUR_TOKEN 为实际令牌）
# http://localhost:18789?token=YOUR_TOKEN

5.3 配置 Ollama 多模态模型

# 下载 LLaVA 多模态模型
ollama pull llava:latest

# 验证模型
ollama list

# 测试图片识别
ollama run llava:latest "描述图片"

# 在 OpenClaw 中使用（可选：修改默认模型）
# 编辑 C:\Users\你的用户名\.openclaw\openclaw.json
# 设置 "agent.model": "ollama/llava:latest"

5.4 注意事项

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

5.5 故障排查清单

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

检查安装
```
openclaw --version
```
检查网关状态
```
openclaw gateway status
```
检查 Ollama 服务
```
ollama list
```

检查端口占用

netstat -ano | findstr :18789
netstat -ano | findstr :11434

检查配置文件

Get-Content $env:USERPROFILE\.openclaw\openclaw.json

查看日志

# 网关日志在运行时的 PowerShell 窗口显示
# 也可以查看日志文件
Get-Content $env:USERPROFILE\.openclaw\logs\gateway.log -Tail 50

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 agent --message "你好"
图片识别：openclaw agent --model ollama/llava:latest --message "查看图片：test.png"

十二、总结

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 --version
# 输出：2026.2.1

下一步操作：

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

OpenClaw 命令帮助速查

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

全局选项：

-V, --version：输出版本号
--dev：开发配置（独立状态、网关端口 19001）
--profile <name>：使用命名配置
-h, --help：显示帮助

常用子命令：

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

查看某子命令的详细帮助：openclaw <命令> --help，例如：

openclaw gateway --help
openclaw plugins --help
openclaw channels --help

文档：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

十三、OpenClaw 接入钉钉与飞书（本地机器配置）

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

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

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

钉钉插件（DingTalk Channel for OpenClaw）：

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

openclaw plugins install https://github.com/soimy/openclaw-channel-dingtalk.git

或 openclaw plugins install https://github.com/soimy/clawdbot-channel-dingtalk.git

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

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

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

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

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

直接执行：openclaw plugins install feishu
若报错，可改用 CMD 执行同一命令，或执行：cmd /c "openclaw plugins install feishu"

安装完成后执行 openclaw plugins list，确认已启用的渠道（如 feishu、dingtalk）状态为 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 中执行（任选一个仓库地址即可）：

openclaw plugins install https://github.com/soimy/openclaw-channel-dingtalk.git

或：

openclaw plugins install https://github.com/soimy/clawdbot-channel-dingtalk.git

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

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

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

git clone https://github.com/soimy/openclaw-channel-dingtalk.git
cd openclaw-channel-dingtalk
npm install
openclaw plugins install -l .

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

git clone https://github.com/soimy/openclaw-channel-dingtalk.git C:\Users\你的用户名\.openclaw\extensions\dingtalk
cd C:\Users\你的用户名\.openclaw\extensions\dingtalk
npm install

方法 C：手动安装

从 https://github.com/soimy/openclaw-channel-dingtalk 下载 ZIP 或复制整个仓库到本地。
将解压/克隆后的目录整体放入 ~/.openclaw/extensions/dingtalk（Windows：C:\Users\你的用户名\.openclaw\extensions\dingtalk），确保该目录下包含 index.ts、openclaw.plugin.json 和 package.json。
在 extensions\dingtalk 目录下执行 npm install 安装依赖。
执行 openclaw plugins list 确认列表中出现 dingtalk | loaded。

更新插件：

openclaw plugins update dingtalk

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

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

OpenClaw 配置（openclaw.json）

在 ~/.openclaw/openclaw.json（Windows：C:\Users\你的用户名\.openclaw\openclaw.json）的 channels 下只添加 dingtalk 段，其他现有渠道保留不变：

"channels": {
  "dingtalk": {
    "enabled": true,
    "clientId": "dingxxxxxx",
    "clientSecret": "your-app-secret",
    "robotCode": "dingxxxxxx",
    "corpId": "dingxxxxxx",
    "agentId": "123456789",
    "dmPolicy": "open",
    "groupPolicy": "open",
    "messageType": "markdown",
    "cardTemplateId": "你复制的模板ID",
    "debug": false
  }
}

clientId / clientSecret / robotCode / corpId / agentId：从钉钉后台获取并替换。
messageType：markdown（默认）或 card（AI 互动卡片，需配置 cardTemplateId）。
dmPolicy：私聊策略 — open / pairing / allowlist。
groupPolicy：群聊策略 — open / allowlist。

保存后执行：

openclaw gateway restart

配置选项速查

选项	类型	默认值	说明
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	调试日志

故障排除

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

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

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

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

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

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

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

Windows：C:\Users\你的用户名\.openclaw\openclaw.json
macOS / Linux：~/.openclaw/openclaw.json

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

{
  "meta": {
    "lastTouchedVersion": "2026.2.1",
    "lastTouchedAt": "2026-02-04T15:18:01.336Z"
  },
  "wizard": { "lastRunAt": "...", "lastRunVersion": "2026.2.1", "lastRunCommand": "onboard", "lastRunMode": "local" },
  "auth": {
    "profiles": {
      "zai:default": {
        "provider": "zai",
        "mode": "api_key"
      }
    }
  },
  "agents": {
    "defaults": {
      "model": { "primary": "zai/glm-4.7" },
      "models": {
        "zai/glm-4.7": { "alias": "GLM" },
        "zai/glm-4.7-flash": {}
      },
      "workspace": "C:\\Users\\你的用户名\\.openclaw\\workspace",
      "compaction": { "mode": "safeguard" },
      "maxConcurrent": 4,
      "subagents": { "maxConcurrent": 8 }
    }
  },
  "messages": { "ackReactionScope": "group-mentions" },
  "commands": { "native": "auto", "nativeSkills": "auto" },
  "hooks": {
    "internal": {
      "enabled": true,
      "entries": {
        "boot-md": { "enabled": true },
        "command-logger": { "enabled": true },
        "session-memory": { "enabled": true }
      }
    }
  },
  "channels": {
    "dingtalk": {
      "enabled": true,
      "clientId": "你的钉钉AppKey",
      "clientSecret": "你的钉钉AppSecret",
      "robotCode": "你的钉钉RobotCode（通常与AppKey相同）",
      "corpId": "你的企业CorpId",
      "agentId": "你的应用AgentId",
      "dmPolicy": "open",
      "groupPolicy": "open",
      "messageType": "markdown",
      "debug": false
    }
  },
  "gateway": {
    "port": 18789,
    "mode": "local",
    "bind": "loopback",
    "trustedProxies": ["127.0.0.1", "::1"],
    "auth": {
      "mode": "token",
      "token": "你的网关Token（从 openclaw 控制台或首次 setup 生成）"
    },
    "tailscale": { "mode": "off", "resetOnExit": false }
  },
  "tools": {
    "web": {
      "search": {
        "provider": "brave",
        "apiKey": "你的Brave_Search_API_Key（从 https://brave.com/search/api/ 申请，选 Data for Search）",
        "maxResults": 5,
        "timeoutSeconds": 30
      }
    }
  },
  "skills": { "install": { "nodeManager": "pnpm" } },
  "plugins": {
    "entries": {
      "dingtalk": { "enabled": true }
    }
  }
}

说明：

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

一、基础准备

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

1.1 核心凭证准备

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

1.2 服务状态确认

OpenClaw 网关已启动：

openclaw gateway status
# 预期输出：Gateway is running

钉钉/飞书插件已安装并加载：
```
openclaw plugins list
# 若已安装飞书插件，列表中会出现 feishu | loaded；钉钉需有对应插件才会出现 dingtalk | loaded
```
若未安装飞书，请先执行「零、安装钉钉与飞书插件」中飞书相关步骤。钉钉目前无官方 plugins install dingtalk，需用社区插件或 AppFlow 等方式。

1.3 本地机器特殊要求

仅用钉钉且采用 Stream 模式：不需要透传、不需要公网 IP，安装插件并配置好 openclaw.json 即可在本地使用钉钉。
要用飞书，或用 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：启动端口转发

# 转发 OpenClaw 网关端口（18789）
ngrok http 18789

预期输出：

ngrok by @inconshreveble

Session Status                online
Account                       xxxxx (Plan: Free)
Version                       3.x.x
Region                        Asia (ap)
Forwarding                    https://xxxxx.ngrok-free.app -> http://localhost:18789

重要：复制 https://xxxxx.ngrok-free.app 这个 URL，这就是你的公网地址。

步骤 3：保持 ngrok 运行

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

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

步骤 1：安装 Tailscale

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

步骤 2：登录 Tailscale

tailscale login
# 浏览器会打开授权页面，确认登录

步骤 3：启用 Tailscale Funnel

# 启用 Tailscale Funnel
tailscale funnel 18789

预期输出：

Funnel on:
  https://your-tailnet-name.ts.net

重要：复制 https://your-tailnet-name.ts.net 这个 URL。

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

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

步骤 1：下载并安装 cpolar

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

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

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

cd "C:\Program Files\cpolar"
.\cpolar.exe authtoken 你的authtoken

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

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

在 PowerShell 或 CMD 中执行（若未将 cpolar 加入 Path，需先 cd "C:\Program Files\cpolar"）：

.\cpolar.exe http 18789

预期输出（示例）：

Forwarding from:
  https://xxxxx.cpolar.cn -> http://localhost:18789
  或
  http://xxxxx.r11.cpolar.top -> http://localhost:18789

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

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

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

https://你的公网域名?token=你的token

或聊天页：https://你的公网域名/chat?session=main&token=你的token。
若仍出现 WebSocket 断开，建议改用本机访问：http://localhost:18789?token=你的token。

2.4 验证端口转发

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

# 访问带令牌的 URL
https://xxxxx.ngrok-free.app?token=你的token

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

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

三、创建钉钉应用

3.1 登录钉钉开放平台

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

3.2 创建应用

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

3.3 获取凭证

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

Client ID (AppKey):      xxxxxxxxxxxxxxxxx
Client Secret (AppSecret): xxxxxxxxxxxxxxxxxxxxxxxxxx

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

四、配置钉钉机器人

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

4.1 发布应用（关键步骤）

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

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

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

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

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

开启「消息接收」
设置「消息接收地址」：
```
https://你的ngrok地址.ngrok-free.app/dingtalk/webhook
```
- 使用你的透传公网 URL 替换
- 路径固定为 /dingtalk/webhook
勾选"加签验证"（可选，增加安全性）

4.3 配置机器人信息

设置机器人基本信息：

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

4.4 设置权限

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

contact:contact.base:readonly（查看联系人）
contact:contact.base:add（添加联系人）
im:chat（发送消息）
im:conversation（会话权限）

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

5.1 编辑配置文件

打开 OpenClaw 配置文件：

C:\Users\你的用户名\.openclaw\openclaw.json

5.2 添加钉钉配置

若使用「钉钉 Channel 插件（Stream 模式）」（推荐）：请直接按本章「钉钉 Channel 插件（DingTalk Channel for OpenClaw）完整说明」中的 openclaw.json 示例配置，字段为 clientId、clientSecret、robotCode、corpId、agentId、dmPolicy、groupPolicy、messageType、cardTemplateId 等，无需 webhookUrl。

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

"dingtalk": {
  "enabled": true,
  "webhookUrl": "https://你的公网地址/dingtalk/webhook",
  "appKey": "你的钉钉AppKey",
  "appSecret": "你的钉钉AppSecret",
  "robotCode": "机器人编码"
}

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

5.2.1 飞书配置（可选）

前提：已按本章「零、安装钉钉与飞书插件」完成飞书安装（npm install feishu 并将 node_modules\feishu 复制到 .openclaw\extensions\feishu，或使用 openclaw plugins install feishu），并在 openclaw plugins list 中看到 feishu | loaded。

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

"channels": {
  "dingtalk": { ... },
  "feishu": {
    "enabled": true,
    "webhookUrl": "http://你的cpolar域名/feishu/webhook",
    "appId": "你的飞书App ID",
    "appSecret": "你的飞书App Secret",
    "verificationToken": "你的飞书Verification Token"
  }
}

飞书开放平台：https://open.feishu.cn/
路径：事件订阅/消息接收地址填 https或http://你的公网域名/feishu/webhook（与 webhookUrl 一致）。

5.3 保存并重启网关

# 重启 OpenClaw 网关
openclaw gateway restart

# 等待 10 秒
Start-Sleep -Seconds 10

# 验证网关状态
openclaw gateway status

六、创建测试群并测试

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

钉钉：

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

飞书：

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

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

6.2 测试机器人

在钉钉或飞书测试群中：

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

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

七、常见问题排查

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

现象：

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

原因排查：

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

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

现象：

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

原因排查：

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

问题 3：报错"Connection refused"

现象：

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

原因排查：

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

问题 4：AppFlow 执行日志报错

常见报错及解决方案：

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

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

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

8.1 创建连接流

登录阿里云 AppFlow 工作台
创建新连接流
选择"HTTP 请求"触发器

配置 webhook URL：

https://你的ngrok地址.ngrok-free.app/dingtalk/webhook

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 模式 → 在 openclaw.json 的 channels.dingtalk 中配置 clientId、clientSecret 等 → 重启网关 → 在钉钉中加群/单聊测试。

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

1. 安装并配置端口转发工具（ngrok/Tailscale/cpolar）
2. 获取公网地址并验证可访问
3. 在钉钉/飞书开放平台创建应用并发布
4. 配置机器人信息、权限和消息接收 URL（webhook）
5. 在 openclaw.json 的 channels 中配置 dingtalk / feishu
6. 创建测试群并测试

关键要点：

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

推荐配置：

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

参考资源：

钉钉开放平台：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/

十四、OpenClaw 接入钉钉/飞书全场景踩坑解决方案

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

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

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

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

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

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

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

现象：

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

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

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

解决方案：

检查并发布钉钉应用：
- 登录钉钉开放平台 → 目标应用 →「版本管理与发布」
- 点击「创建新版本」，填写版本号（如 1.0.1）和描述
- 选择可见范围（测试阶段选「仅自己可见」）→「保存 → 直接发布」，等待 5–10 秒生效
核对消息接收地址 URL：
- AppFlow 对接：URL 必须为 https://xxxxx.appflow.aliyunnest.com/webhook/xxxxxxxxx（从 AppFlow 连接流详情页复制）
- 直连模式：URL 为 http://公网IP:18789/wecom（端口固定 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，在 models.providers 节点核对 apiKey，修改后 Save → Update
重启 OpenClaw 网关：openclaw gateway restart，等待约 10 秒后 openclaw gateway status 确认 running
修正连接流模型配置：模型名称格式为 alibaba-cloud/模型Code（如 alibaba-cloud/qwen3-max-2026-01-23），模型 Code 在阿里云百炼模型广场查询，选择支持流式调用的版本

场景 3：控制面板返回 `{"success":true}`，无法访问 Web UI

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

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

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

找到并编辑 monitor.ts：
- Windows：C:\Users\你的用户名\.openclaw\extensions\dingtalk\src\monitor.ts
- macOS/Linux：~/.openclaw/extensions/dingtalk/src/monitor.ts
修改 handleDingTalkWebhookRequest 函数开头：在函数最顶部增加「仅处理钉钉专属请求」的判断，其余代码不变：

export async function handleDingTalkWebhookRequest(
  req: import('node:http').IncomingMessage,
  res: import('node:http').ServerResponse
): Promise<boolean> {
  // 仅处理钉钉专属路径的 POST 请求，放行其他请求（如 Web UI）
  const url = req.url || '';
  const isDingTalkPath = url.includes('/dingtalk') || url.includes('/webhook');
  if (req.method !== 'POST' || !isDingTalkPath) {
    return false;
  }
  // 以下为原有代码，无需修改
  console.log(`[dingtalk] HTTP request received: ${req.method} ${req.url}`);
  // ...
}

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

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

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

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

解决方案：

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

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

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

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

解决方案：

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

场景 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」
保存后执行 openclaw gateway restart

场景 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）
第三步	重启验证：`openclaw gateway restart`，可选 `openclaw plugins reload dingtalk`

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

「发布」是核心：钉钉应用、连接流、AI 卡片均需「发布」，仅创建不发布会导致无响应
格式别错：公网地址不带协议头（如 47.11.XX.XX:18789），模型名称带 alibaba-cloud/ 前缀
模板要空白：钉钉 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

龙虾开发者社区

小龙虾开发者社区是 CSDN 旗下专注 OpenClaw 生态的官方阵地，聚焦技能开发、插件实践与部署教程，为开发者提供可直接落地的方案、工具与交流平台，助力高效构建与落地 AI 应用

更多推荐

OpenClaw+GLM-4.7-Flash语音交互：对接Whisper实现语音控制

本文介绍了如何在星图GPU平台上自动化部署【ollama】GLM-4.7-Flash镜像，构建语音交互系统。该系统结合Whisper语音识别与GLM-4.7-Flash的指令理解能力，实现智能家居控制等场景的语音操作，提升日常任务执行效率。

龙虾开发者社区

学生党福音：OpenClaw+nanobot搭建学习监督助手

本文介绍了如何在星图GPU平台上自动化部署🐈 nanobot：超轻量级OpenClaw镜像，构建智能学习监督助手。该方案利用轻量级模型实现网课进度跟踪、自动生成练习题和错题整理功能，特别适合学生群体通过QQ机器人实现移动端学习管理，显著提升学习效率。

龙虾开发者社区

OpenClaw创意工坊：用nanobot镜像生成技术海报文案

本文介绍了如何在星图GPU平台上自动化部署🐈 nanobot：超轻量级OpenClaw镜像，快速生成技术海报文案。该镜像基于Qwen3-4B模型，能将复杂技术术语转化为通俗表达，适用于技术活动宣传、社交媒体推广等场景，显著提升内容创作效率。

龙虾开发者社区

所有评论(0)

查看更多评论

hzether

@hzether

已为社区贡献1条内容

Windows 11 安装 OpenClaw 完整教程

hzether

Windows 11 安装 OpenClaw 完整教程

Windows 11 安装 OpenClaw 完整教程

一、OpenClaw 简介

二、安装前准备

（一）系统要求

（二）核心依赖检查

1. 检查 Node.js 版本

2. 检查 PowerShell 执行权限

3. 检查 Ollama 安装（可选）

4. 检查已安装的 Ollama 模型

5. 可选工具准备

三、安装 OpenClaw 主程序

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

方法二：通过 npm 安装

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

1. 安装 pnpm

2. 配置 pnpm 环境

3. 安装 OpenClaw

4. 验证安装

当前安装状态记录

四、初始化配置

配置向导步骤

五、验证服务启动状态

1. 检查网关服务

2. 访问 Web 管理界面

六、配置本地 Ollama 模型（可选）

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 多模态模型

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