你们要的 OpenClaw 教程来了。这次我不写空话，直接上实测结果：我在 Windows 11 上把 OpenClaw 2026.4.2 完整跑通了一遍，从大模型 API 接入到 QQ 机器人上线，前后折腾了大半天，最终版配置亲测可用。如果你也想做一个放在 QQ 群里随叫随到的 AI 助手，或者想把不同的大模型接口统一收编到一个入口里管理，这篇正好可以当成作业抄。
这套东西能做什么？简单说，OpenClaw 是一个开源的个人智能体/自动化助手框架。你给它接上大模型 API，再配上 QQ、飞书这类消息通道，就能用自然语言指挥它干活——写邮件、查资料、定时提醒、自动整理群消息，甚至让它自己写段脚本并执行。它适合三类人：想给个人或小团队搭 AI 助手的开发者、想研究智能体框架的爱好者、以及需要把多个大模型 API 统一接入可控场景的产品同学。
1. 先盘清楚：OpenClaw 2026.4.2 到底解决什么问题
1.1 它是什么，又不是什么
先给结论：OpenClaw 不是一个聊天插件，也不是“又一个 ChatGPT 壳子”，它是一个把自己定位成自动化助手的开源智能体框架。和普通聊天机器人最大的区别在于，它不只会“说”，还会“做”。给它配好权限之后，它可以调用工具、执行命令、读写文件、调用技能，再通过消息通道把结果返回给你。
我用的版本是 2026.4.2，实测下来这个版本在 Windows 上的安装体验比早期版本平滑很多。早期版本的安装脚本基本默认面向 Linux/macOS，Windows 用户基本要靠手动折腾；2026.4.2 在官网上已经提供 Windows 便携包，解压即用，也可以走 PowerShell 安装脚本。官方对稳定版和开发版也做了更新通道区分，日常使用建议固定在 stable 通道上。
有朋友把 OpenClaw 和 Clawhub 搞混。这里顺带说清楚：OpenClaw 是主程序，Clawhub 是技能/插件市场，类似 VS Code 和扩展市场的关系。主程序负责调度模型、连接通道、执行动作，Clawhub 里的东西是各种现成技能包，装到本地就能用。这个关系后面讲技能时会再展开。
1.2 为什么值得在 2026 年重提这件事
现在大模型 API 遍地开花，DeepSeek、Kimi、智谱、通义、豆包，随便一个都能聊。但问题是：你的 API 是散的，场景也是散的。今天想在 QQ 里用 A 模型，明天想在命令行里用 B 模型，后天想用本地 Ollama 跑离线模型，如果每个都要单独写代码对接，工作量就上来了。
OpenClaw 这类框架解决的核心问题，就是把“模型能力”和“消息触达”解耦。你只需要在配置里写清楚用哪个模型、哪个通道，它负责中间所有调度。换模型改三行配置，加通道改一个段落，不用动业务逻辑。这种“模型路由 + 通道适配 + 技能执行”的架构，才是它真正值钱的地方。
1.3 适合用来做什么，不适合做什么
适合的场景很多：QQ 群里的 AI 助手、个人知识库的问答入口、定时任务触发器、Webhook 接收器和响应器、甚至简单的工作流自动化。我见过有人把 OpenClaw 接到 Obsidian 里做项目管理——让它把群聊里的结论自动归档成 Markdown 笔记，效果很香。
不适合做什么？如果你只想要一个网页聊天界面，那直接用官方 Web 就行，不需要上这套框架。如果你想做大规模商用客服、批量群发营销，我劝你放弃。一方面这违反平台规则，另一方面智能体自动执行命令本身有风险，不是拿来搞灰产的。它更适合个人和小团队内部提效。
2. 架构拆解：模型 API、网关、通道、技能是怎么协作的
2.1 四层结构一次看懂
我把 OpenClaw 的运行结构拆成四层，这样后面配置的时候你就知道自己正在动哪一层：
- 模型层：负责理解和生成。可以是云厂商的在线 API，也可以是本地 Ollama，只要是 OpenAI 兼容接口就能接入。
- 核心层：OpenClaw 本体，负责调度、上下文管理、权限控制、工具调用。你所有的配置和审批逻辑都在这层。
- 通道层：消息接入层，QQ、飞书、Telegram、Web 等都算。这个层决定了用户从哪里跟你对话。
- 能力层：技能和工具。比如“总结网页”“生成表格”“执行 Python 脚本”，这类可复用的功能就是 Skill。
用人话说，核心层是你雇的调度主管，模型层是外脑，通道层是电话线，能力层是工具箱。四者各管一摊，互不打扰。
2.2 为什么“OpenAI 兼容接口”这么重要
你可能注意到，现在几乎每个大模型厂商都提供“OpenAI 兼容接口”。这不是巧合，它已经是事实上的行业标准。OpenClaw 也默认支持这套协议，意味着换模型时只需要改三个参数：base_url、api_key、model，配置结构完全不用动。
我用一个类比说明：这就像所有设备统一用 Type-C 接口。以前每个模型厂商有自己的 SDK、自己的鉴权方式、自己的请求格式，接入一个模型要写一套适配代码。现在大家都按 OpenAI 的格式来，OpenClaw 只需要实现一遍协议，就能接所有模型。这也是它能支持那么多模型供应商的根本原因。
2.3 QQ 机器人为什么需要中转：OneBot 协议与 NapCat
有人会问，QQ 机器人为什么不直接像微信公众号那样有官方 API？这个问题比较现实：个人开发者拿不到 QQ 官方的机器人接口，门槛很高，所以社区走的是另一条路——用本地协议服务中转。
目前最主流的方案是 NapCat。它做的事情是，把 QQ 账号的消息转成 OneBot 11 标准协议，再通过 WebSocket 或 HTTP 提供给其他程序使用。OpenClaw 要连 QQ，就是作为 OneBot 协议的客户端，连上 NapCat 开出来的 WebSocket 服务，然后收发消息。
打个比方：QQ 本身没开“门”，NapCat 相当于在窗户上装了一个对讲机，把外面的消息转成统一门禁协议，OpenClaw 只需要学会这个门禁协议就能和 QQ 用户对话。这就是为什么教程里一定会有 NapCat 这一环。注意，我只建议用全新小号做功能测试，不要拿主号去跑，更不要做群发、自动加好友这类动作。这类方案的合规问题自己要心里有数。
2.4 模型供应商怎么选：在线、本地、免费 API 的取舍
我实测下来，模型供应商的选择直接决定体验。这里把常见选项拉一张表，方便你对照：
| 类型 | 代表 | 优点 | 缺点 | 适合场景 |
|---|---|---|---|---|
| 商业在线 API | DeepSeek、Kimi、智谱、通义、豆包 | 稳定、延迟低、能力强 | 按量付费 | 生产环境、日常主力 |
| 本地模型 | Ollama + Llama/Qwen 等 | 免费、隐私好、可离线 | 吃硬件，速度和效果看设备 | 学习调试、隐私数据 |
| 免费/限时 API | NVIDIA NIM、硅基流动免费额度 | 不花钱，适合测试 | 限流、模型可能不稳定、Key 易失效 | 功能验证、Demo |
| 第三方“转售”服务 | 来源不明的中转站 | 价格低 | Key 泄露风险高、随时跑路 | 不建议使用 |
我个人的建议是：测试阶段用免费额度或者本地 Ollama，确认链路通了再切付费 API。这样即使配置有问题，也不会白白烧钱。另外，我特别不建议买来路不明的“大模型 API 转售”服务，看起来便宜，实际上 Key 安全和稳定性都没有保障，出问题你连找谁都不知道。
3. 完整实操：Windows 11 从零配置大模型 API 和 QQ 机器人
3.1 环境准备：Windows 下需要装的东西
在动手之前，先把基础环境装齐。我说的是我实际在 Windows 11 上验证过的组合，照着来就行：
- Node.js 18 或更高版本：部分技能和执行组件依赖，直接去官网下 LTS 版。
- Git：不是必须，但如果你想从 Clawhub 拉技能包，或者用 Git 管理配置，建议装。
- PowerShell：Windows 自带，但建议升级到 PowerShell 7，兼容性更好。
- Python 3.10+：部分技能脚本需要，非纯聊天场景必备。
- Docker（可选）：如果你打算用容器跑 NapCat 或者其他附属服务，可以装一个。
提示：Node.js 和 Python 的安装路径都不要带中文，后续某些组件编译会出问题。这个坑我踩过。
3.2 安装 OpenClaw：便携包和 PowerShell 两种方式
我推荐便携包方式，理由很简单：目录自己可控，升级时直接替换压缩包内容，出问题还能快速回滚。
便携包安装步骤：
- 到 OpenClaw 官网下载
openclaw-2026.4.2-windows-x64.zip。 - 解压到
D:\Tools\openclaw，不要放系统盘 C 盘，避免权限问题。 - 将
D:\Tools\openclaw加入系统 PATH 环境变量。 - 重新打开一个终端，输入
openclaw --version，能输出版本号就算成功。
PowerShell 脚本安装是另一种做法，执行官方文档里给出的安装命令。但有几个朋友问过我“PowerShell 安装能指定目录吗”，实测下来脚本默认安装到用户目录下，想指定目录不太方便。如果你对目录有明确要求，直接用便携包，别折腾脚本。
3.3 配置大模型 API：在线、本地、NVIDIA NIM 三套模板
这一步是整个配置的核心。OpenClaw 的主配置文件在~/.openclaw/openclaw.json，第一次启动时会自动生成。你不需要从零写，用交互式openclaw configure引导即可，也可以直接编辑 JSON。
我整理了三套最常用的配置模板：
模板一：在线 OpenAI 兼容 API（以 DeepSeek 为例）
model_providers: default: base_url: https://api.deepseek.com/v1 api_key: sk-你的key model: deepseek-chat模板二：本地 Ollama
model_providers: default: base_url: http://localhost:11434/v1 api_key: ollama model: llama3.1:8b模板三：NVIDIA NIM 免费 API
model_providers: default: base_url: https://integrate.api.nvidia.com/v1 api_key: nvapi-你的key model: meta/llama-3.1-8b-instruct配置完后，先不要急着接 QQ，用一行命令验证模型层：openclaw talk "1+1等于几"，如果能正常回答，说明模型链路已经通了。这个“最小验证”习惯非常重要，它能帮你把问题范围缩小，避免后面连着通道一起排查时头大。
3.4 搭建 QQ 机器人通道：NapCat + OneBot 实操
模型层通了，接下来才是重头戏：让机器人真正跑在 QQ 里。
第一步，准备一个全新 QQ 小号，扫码登录 NapCat。NapCat 启动后，在设置里开启 WebSocket 服务端，端口默认 3001。这一步的作用是让 NapCat 成为消息中转站。
第二步，在 OpenClaw 配置文件里增加通道配置：
channels: qq: protocol: onebot11 ws: enabled: true url: ws://127.0.0.1:3001注意这里的ws://127.0.0.1:3001要和 NapCat 里监听的端口保持一致。如果 NapCat 装在其他机器上，就改成那台机器的 IP 和端口。
第三步，保存配置，启动 OpenClaw。观察启动日志，看到channel connected或类似的字样，说明通道已经建立。
3.5 启动验证与第一个对话
启动命令很简单：openclaw run。如果需要指定只跑 QQ 通道，可以加参数--channel qq。
验证顺序我建议这样：先在终端里用openclaw talk确认模型通，再在 QQ 里私聊机器人发一句“你好”，看它是否回复。如果私聊通了，再拉个测试群，把机器人拉进群，在群里 @ 它发消息。
我在实操中遇到的第一个群聊问题是：机器人不响应 @ 消息。后来发现是配置里没有开启群消息解码功能，需要在通道配置里增加group: true。这个不同版本字段名略有差异，自己看文档时留意一下。跑通后，你可以在群里让它“总结一下今天群里的讨论”“生成一份会议纪要”，逐步加需求。
4. 配置细节与常用指令：从配置目录到权限机制
4.1 配置目录结构解析
OpenClaw 的默认数据目录在用户主目录下的.openclaw文件夹，Windows 上就是C:\Users\你的用户名\.openclaw。里面几个关键路径你需要知道：
openclaw.json：主配置文件，模型、通道、技能都在这。exec-approvals.json：命令执行审批记录。workspace：工作目录，智能体默认在这里读写文件。claws：已安装的技能和插件。
有一次我在 Windows 上看到的日志里写着workspace: c:\users\administrator\.openclaw\workspace，这就是当前工作目录。很多用户会遇到“文件写到哪了”的困惑，答案就是这里。建议定期备份整个.openclaw目录，升级版本前尤其重要。
4.2 常用命令速查
我把自己常用的命令整理成一份清单，放在终端里随时翻：
| 命令 | 作用 | 备注 |
|---|---|---|
openclaw --version | 查看版本 | 安装验证 |
openclaw configure | 交互式配置引导 | 适合新手 |
openclaw run | 启动主程序 | 前台运行 |
openclaw talk "问题" | 命令行直接对话 | 验证模型链路 |
openclaw update --channel stable | 更新到稳定版 | 日常推荐 |
openclaw update --channel dev | 更新到开发版 | 尝鲜用 |
关于关闭和进程管理：Windows 下前台运行直接按Ctrl+C结束。如果是后台跑，需要tasklist | findstr openclaw查到进程号，再用taskkill /PID 进程号 /F。Linux 上则是ps aux | grep -i openclaw。这套命令在排查“端口被占用”或“启动失败”时非常有用。
4.3 exec-approvals.json 权限机制，千万别忽略
这个是新手最容易忽视、老手最容易翻车的地方。OpenClaw 作为一个能执行命令的智能体，默认带了一套命令审批机制。当它要执行 shell 命令、写文件、装软件这类敏感操作时，会把操作记录写入exec-approvals.json，等待你确认。
你在启动时可能会看到类似这样的话：
legacy exec approvals exist at /root/.openclaw/exec-approvals.json. run
openclaw exec-approvals migrateto migrate them
意思是有旧版本的审批记录需要迁移。我之前一直忽略，结果导致某些技能无法自动执行。处理方法很简单：运行迁移命令，或者在交互式确认时逐条同意。
这里我要强调：不要在配置里把审批机制全部关掉。虽然会省事，但智能体一旦在复杂对话中产生幻觉，可能执行不可控的命令。保留审批机制其实是一条安全底线，尤其当你接的模型能力比较强时。
4.4 Skills 技能和 Clawhub 插件从哪找
Skills 是 OpenClaw 最灵活的部分。一个 Skill 本质上是一个文件夹，里面有指令描述和工具定义，告诉智能体“你可以用哪些能力、怎么用”。在配置里声明启用哪个技能之后，模型会自动判断什么时候该调用。
Clawhub 就是找技能的地方。可以理解成手机应用商店，上面有社区贡献的现成技能包，比如“读取网页并总结”“生成数据图表”“调用图片识别 API”等。安装命令类似openclaw claw install 技能名。
自己写一个 Skill 也不难。先建一个文件夹，写一个描述用途的说明文件，再定义一个工具函数，最后在主配置文件里启用即可。配合本地 Ollama 模型，你可以做出一个完全离线的私人助理，不花一分钱 API 费用。
4.5 扩展玩法：飞书、微信、Obsidian 项目管理
通道不只 QQ。OpenClaw 官方和社区已经适配了飞书、Telegram、微信等通道。比如飞书通道，配置方式类似，主要是 Webhook 地址和 App ID 的差异。微信插件也有人在维护，不过稳定性不如 QQ 和飞书，需要自己去社区找。
我最近比较推荐的一个玩法是把 OpenClaw 接到 Obsidian 做项目管理：让它在每次对话后把结论、待办、链接自动整理成 Markdown 笔记，存到workspace里，然后 Obsidian 直接读取这个目录。这样群聊里讨论的碎片信息，会自动沉淀成结构化笔记，效果很香。
5. 老鸟踩坑记录：常见问题与排查实录
5.1 安装后openclaw命令无法识别
这是问得最多的一个问题。报错通常是：
openclaw : 无法将“openclaw”项识别为 cmdlet、函数、脚本文件或可运行程序的名称
原因很简单：可执行文件不在系统 PATH 里，或者你修改 PATH 后没有重新打开终端。处理办法：如果是便携包，把解压目录加入 PATH；如果是脚本安装，确认安装路径后手动加入 PATH，然后新开一个终端窗口。如果还是不行，直接切到解压目录下运行.\openclaw.exe --version验证文件本身是否正常。
5.2 一直卡在“网关启动中”
这个现象通常和网络端口有关，不是程序卡死。OpenClaw 启动时会启动一个本地网关服务，如果默认端口被占用或者监听地址配置不对，就会一直卡住。
排查步骤：Windows 下先查端口占用情况，netstat -ano | findstr 3001（换成你配置的端口），如果看到占用进程，判断是不是别的程序，是的话就改配置端口。另外检查 Windows 防火墙，确认放行了 OpenClaw 的入站规则。最后看日志，通常卡住时日志里会有明确提示。
5.3 模型 API 返回 401、超时、余额不足
这三个问题基本是配置参数或账号状态导致的：
- 401：api_key 错了，或者 key 前后有空格。检查配置项时可以把 key 复制到记事本里看下字符。
- 超时：base_url 填错、网络不通、或者模型服务本身负载高。先用
curl测试下接口连通性。 - 余额不足：这个只能去对应平台充值或换 Key。
另外要注意 base_url 的路径格式。有些平台需要/v1，有些不带，务必以平台文档为准。填错一个斜杠，可能就会浪费你半小时。
5.4 QQ 机器人收不到消息或发了不回复
这是通道配置里最容易出问题的地方，我按顺序排查：
- NapCat 是否成功登录？打开 NapCat 管理界面，确认账号在线。
- WebSocket 服务是否开启？端口是否正确？
- OpenClaw 日志里有没有
channel connected？没有就是没连上。 - 群里 @ 不回复的话，检查通道配置里是否开启了群消息支持。
还有一个常见原因：账号被平台临时限制了消息收发权限。所以我才反复强调，用全新小号测试，不要拿主号冒险。
5.5 Docker + Ollama + OpenClaw 混合部署
如果你在 Windows 上装了 Docker，又用 Ollama 跑本地模型，OpenClaw 跑在宿主机上，配置很直接：base_url填http://localhost:11434/v1。但如果 OpenClaw 跑在 Docker 容器里，Ollama 在宿主机上，需要把地址改成http://host.docker.internal:11434/v1。反过来，如果你在 NAS（比如飞牛）上部署，注意容器的网络模式要选 host 或者正确配置端口映射，否则容器之间互相访问不到。
5.6 免费 API 的隐藏坑
免费 API 不是不能用，但要有预期管理：限流严重、高峰期排队、模型可能临时下线。我见过有人拿 NVIDIA NIM 的免费额度跑生产任务，结果高峰时段 50% 请求超时，体验很差。免费 API 适合验证功能、做 Demo、学习调试，不适合生产环境。想稳定，还是老老实实付费。
另外，我发现很多人分不清“免费额度”和“免费 API”的区别：前者是你的账号有一定量的免费调用次数，用完即止；后者是服务商本来就提供免费档位，但能力往往受限。配置前先看清文档，别把额度用完了还疑惑为什么不回消息。
5.7 workspace 目录越用越乱怎么办
智能体每次写文件都会落在 workspace 里，时间久了会非常乱。我的习惯是：按项目建子目录，并在提示词里告诉智能体“所有新文件统一放到对应子目录”。另外，定期清理临时文件和旧版本产物。如果你在 workspace 里放了敏感文件，注意不要让它被模型随意读取，配置里可以限制工作目录的访问范围。
5.8 升级版本的正确姿势
升级 OpenClaw 本身不难，难的是升级之后配置不兼容。我踩过一次坑：从旧版升级到 2026.4.2 后，原来能跑的技能突然失效，后来发现是版本号升级后个别配置字段变了。
所以升级前一定要备份.openclaw目录。备份后，用openclaw update --channel stable升级。如果升级后出问题，停掉服务，恢复备份，回滚版本。千万不要盲目追 dev 版，除非你明确知道新版本改动内容，并且有时间折腾。
6. 最后再分享一点我的使用习惯
整套配置跑通之后，我个人的体会是：OpenClaw 这类框架的上限，取决于你愿意花多少精力打磨细节。它不像普通聊天机器人开箱即用，需要你像养一个实习生一样，告诉它你的偏好、你的规则、你的工作目录结构。我的建议是三步走：先用免费 API 跑通链路，再逐步加技能和权限，最后结合本地模型做私有化部署，把 API 成本降到最低。
再分享一个小技巧：每次升级前，我都会把openclaw.json和exec-approvals.json这两个文件单独复制一份，标记好日期。这个习惯已经帮我避开了两次“升级后配置损坏”的大坑，你也可以试试。
最后还是那句话：这类接 QQ 通道的玩法，仅限个人学习和小范围测试，务必遵守平台规则和社区规范，别拿去搞群发、营销、自动加好友之类的操作。把能力用在正道上，它就是你最顺手的数字助理；用歪了，风险全得自己扛。
