最近折腾了一个周末，总算在 Win10 台式机上把 openclaw-cn 装好，并且成功接上了飞书机器人。整个过程逻辑上并不复杂，但每一步几乎都有 Windows 特有的坑等着你。如果你也想在本机跑一个属于自己的智能助手，这篇文章应该能帮你省下不少弯路。
openclaw-cn 本质上是一个消息网关：它负责接收飞书里发给机器人的消息，转给大模型处理，再把回复发回去。它不生产智能，只负责把"聊天软件"和"模型服务"这两头接起来。适合没有云服务器、只有一台 Windows 电脑的同学，尤其是想让办公群里的机器人具备对话能力，又不想在服务器上折腾的人。
我用 Win10 跑通之后，整理了一份从零开始的完整记录，包含环境准备、飞书后台配置、项目初始化、配置项解释、联调测试，以及几个 Windows 上才会遇到的坑。跟着做，半小时内就能跑通。
1. 先搞清楚它是干什么的，再动手
1.1 三个组件怎么配合
openclaw-cn 本身不内置大模型，它只是一个中间层。整个系统由三部分组成：
- 飞书机器人：用户在飞书里看到的那个"联系人"，负责收发消息。
- openclaw-cn 服务：运行在你电脑上的本地进程，监听飞书推送过来的事件，把消息内容提取出来。
- 模型服务：一个可以对话的大模型 API 接口，openclaw-cn 把消息拼成请求发过去，再把返回文本送回飞书。
用一个生活类比来说，飞书机器人是前台接待，openclaw-cn 是接线员，大模型是后面坐着的专家。前台收到问题，交给接线员，接线员转述给专家，再把专家的话原样传回前台。
这个拆法最大的好处是：你可以在不修改项目代码的前提下，随时换模型服务商，或者同时接多个对话入口。openclaw-cn 把协议转换、事件校验、消息重试这些脏活都做了，你只需要填配置。
1.2 为什么用 openclaw-cn 而不是自己写
如果你只是想在飞书里做个"收到关键字就回复固定文本"的机器人，那确实不用上这个项目。但一旦涉及大模型对话，事情就会变复杂：
- 飞书的事件回调带有签名和时间戳校验，自己实现容易漏。
- 用户连续提问时，你要维护会话上下文，不能每次都是独立请求。
- 模型响应可能很长，需要分段发送、处理超时。
- 飞书推送事件可能重复，你需要做幂等处理。
openclaw-cn 把这些都封装好了。我一开始也考虑过用脚本直接调模型 API 再调用飞书发送接口，做到一半发现事件订阅校验、长连接保持这些逻辑远比想象中麻烦，最后才切到 openclaw-cn。如果你不是非要纯手工造轮子，建议直接用它。
1.3 我为什么选 Win10 当运行环境
我手头有一台闲置的 Win10 台式机，配置不高但 24 小时开机没什么压力。家里没有公网 IP，如果走传统的飞书回调 URL 模式，还得额外配内网穿透，麻烦。后来发现 openclaw-cn 支持飞书的长连接模式，机器人直接主动跟飞书服务器建立 WebSocket 通道，不需要公网地址，这就让 Win10 本机部署变得非常现实。
所以这篇文章不是"硬要在 Windows 上装服务"，而是 Windows 确实能满足这个场景的需求。你只要保证电脑不常关机，机器人就能持续在线。
2. Win10 环境准备：能省两小时的三个选择
2.1 Python 版本我只推荐 3.11
openclaw-cn 基于 Python 开发，第一步自然是装 Python。这里第一个坑就出现了：别装最新版，装 3.11 就好。
我一开始装了当时最新的 Python 3.12，结果项目里几个依赖库还没有对应版本的预编译包，pip 安装时只能现场编译，Windows 上没有编译工具链就直接报错。后来卸载换成 3.11，所有依赖秒装完。
原因在于，这个项目生态比较年轻，依赖锁定文件里的版本列表往往只针对特定 Python 版本做过完整测试。3.11 属于被验证得比较充分的版本，配套轮子齐全。
安装时还有一个关键动作：在安装向导第一屏务必勾选Add Python to PATH。很多人忽略这一步，装完发现命令行输入python完全没反应。如果已经装完但没勾，可以手动把安装目录和Scripts子目录加到系统环境变量里。
2.2 目录和路径别用中文
这个建议听起来老生常谈，但我在实际使用中是真的吃过亏。项目克隆到一个D:\软件\机器人目录后，初始化向导一切正常，但一跑起来就报编码错误，原因是配置文件里的中文字符在 Windows 默认编码下被读乱了。
解决办法很简单，把项目放在纯英文路径下，比如D:\tools\openclaw-cn。这不算项目本身的 bug，而是 Windows 对 UTF-8 的处理不如 Linux 干净，我们没必要在工具链上跟它较劲。
2.3 顺手开启 Windows 开发者模式
在"设置 - 系统 - 开发者选项"里打开开发者模式。这一步并不直接参与项目运行，但它会放宽 Windows 对符号链接和长路径的限制，后续装某些依赖、创建虚拟环境时，能少遇到莫名其妙的权限报错。
另外，建议顺手在"区域设置"里勾选"Beta：使用 Unicode UTF-8 提供全球语言支持"。如果嫌改动太大，至少要把控制台代码页改成 UTF-8，否则后面启动服务时，中文日志基本没法看（这一节在第 7 部分会细说）。
3. 飞书那边先建好机器人
3.1 创建企业自建应用
飞书这边的操作全部在开放平台后台完成。登录飞书开放平台，进入开发者后台，选择"企业自建应用"，创建一个新应用。应用名称可以随便起，比如"本地助手"。
这一步需要注意的只有一件事：如果你是企业管理员，直接用管理员账号登录创建；如果你是普通成员，需要确认企业允许成员创建应用，否则会看到权限不足的提示。个人开发的话，飞书也提供了测试企业环境，可以创建一个用于测试的组织。
3.2 开启机器人能力
创建完应用后，在应用能力列表里找到"机器人"，点击启用。启用后，这个应用就相当于拥有一个机器人身份。
接着要配置权限。在"权限管理"里至少需要开通这几类权限：
- 读取用户发给机器人的单聊消息
- 以机器人身份发送消息
- 上传图片或文件（如果需要发图）
- 读取群聊信息（如果要接入群）
权限名称各家版本会有调整，你按"消息读取""消息发送""机器人"这几个关键词搜就行。关键点是：权限修改后要重新发布应用版本才会生效。我一开始改完权限没发布，结果测试时消息根本收不到，白白怀疑了半天配置。
3.3 拿到三组关键凭证
在"凭证与基础信息"页面，记下两个值：
- App ID：应用的唯一标识，类似
cli_xxxx。 - App Secret：应用密钥，用于签名校验，相当于机器人的密码。
在"事件订阅"页面设置回调方式时，还会需要：
- Encrypt Key：消息加密密钥，可选但建议开启。
- Verification Token：验证令牌，用于回调验证。
这四个值在后面的配置文件里都会用到。保管好 App Secret 和 Encrypt Key，不要提交到 Git 仓库或发到群里。
3.4 事件订阅选择长连接模式
事件订阅是飞书推送消息给机器人的通道，这里有两种模式：
- 短连接（回调 URL）：飞书把事件 POST 到你提供的公网 URL 上，要求这个 URL 能公网访问，且经过签名验证。
- 长连接（WebSocket）：机器人主动连接飞书的网关服务器，维持一条双向通道，不要求公网入口。
Win10 家用场景下，长连接是绝对的首选。没有独立公网 IP 的话，短连接模式需要你额外搭建内网穿透服务，还要处理 HTTPS 证书，复杂度高很多。而长连接模式只需要在事件订阅里选择"使用长连接接收事件"，系统会自动分配一个 WebSocket 接入点，openclaw-cn 启动后会自己连上去。
选好长连接模式后，记得在事件订阅列表里添加事件接收消息（对应im.message.receive_v1）。这个是核心事件，不加的话机器人永远收不到用户消息。
4. 安装 openclaw-cn 与初始化
4.1 获取项目代码
openclaw-cn 的代码通常托管在开源社区，你可以在项目主页找到仓库地址。我当时的做法是直接用 Git 克隆到D:\tools\openclaw-cn目录下：
git clone https://你的项目仓库地址/openclaw-cn.git如果网络环境不理想，也可以直接在项目页面下载压缩包解压，效果一样。这里强调一下：下载后先看一下 release 版本或 README 里的版本说明，尽量选最新的发布版本，而不是默认主干分支。主干分支可能包含正在开发的实验功能，配置格式会有变动。
4.2 创建虚拟环境并安装依赖
为了不污染系统 Python 环境，我建议先建虚拟环境：
cd D:\tools\openclaw-cn python -m venv venv venv\Scripts\activate看到命令行前面出现(venv)前缀，说明虚拟环境已激活。然后安装依赖：
pip install -r requirements.txt如果requirements.txt不存在，可以看 README 里是否有pyproject.toml或setup.py，用：
pip install -e .安装过程如果遇到某个包编译报错，优先检查 Python 版本是不是 3.11。另一个常见原因是 pip 源访问慢甚至超时，可以临时切换国内镜像源：
pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple4.3 运行初始化向导
安装依赖完成后，不要急着直接启动。openclaw-cn 一般自带一个初始化向导，用来生成默认配置，命令行大概是：
python main.py --init也有可能叫别的名字，比如python start.py init之类，具体看 README。向导会问你：
- 平台类型（这里选飞书）
- App ID 和 App Secret
- 加密方式（建议选加密，然后填 Encrypt Key）
- 模型服务商的接口地址和 API Key
- 默认的系统提示词
回答完这些问题，项目目录下会生成一个config.yaml配置文件。把向导当成一个"填表程序"即可，后面任何参数都可以直接编辑配置文件修改。
5. config.yaml 逐项填明白
5.1 飞书相关配置
配置文件的核心是飞书接入部分，各字段含义如下：
feishu: app_id: "cli_xxxxxxxx" app_secret: "xxxxxxxxxxxxxxxx" encrypt_key: "xxxxxxxxxxxxxxxx" verification_token: "xxxxxxxx" mode: "websocket" # websocket 长连接 / webhook 回调mode必须和飞书后台事件订阅选择一致：后台选了长连接，这里就填websocket；后台选了回调 URL，这里填webhook并配置回调端口。encrypt_key如果后台开启了加密，必须填写；没开启就不填，留空。- 使用长连接时，
verification_token其实用不上，因为我实测发现长连接的校验主要靠 App Secret 签名，但留着无妨。
5.2 模型服务配置
模型配置是另一端的关键：
llm: provider: "openai_compatible" base_url: "https://你的模型服务地址/v1" api_key: "sk-xxxxxxxxxxxxxxxx" model: "你的模型名称" temperature: 0.7 max_tokens: 2048provider字段用于适配不同服务商，openclaw-cn 通常支持通用 OpenAI 兼容格式。无论你用的是哪家大模型提供的兼容接口，只要把base_url和api_key填对就能通。
在真实使用中，我建议把max_tokens先设得小一点，比如 1024。跑通之后再调大，避免一开始测试时等待时间过长。同时设置合理的请求超时时间，防止模型接口卡住时机器人一直不回复。
5.3 对话与系统设定
对话相关配置决定机器人的"性格"和记忆方式：
chat: system_prompt: "你是一个乐于助人的助手，回答简洁、准确。" history_max_turns: 20 enable_context: truesystem_prompt是模型的基础人设，你想让机器人说话严谨还是活泼，都在这里调。history_max_turns控制保留多少轮聊天记录。设得太大，消耗的 token 多也容易超出模型上下文窗口；设得太小，对话会显得健忘。20 轮在大多数场景下都比较合适。enable_context决定是否维护多轮上下文。单轮问答任务可以关掉，省 token。
5.4 一个可参考的最小配置
综合以上，一个能跑起来的最小配置大概长这样：
feishu: app_id: "cli_demo123" app_secret: "secret_demo123" encrypt_key: "" verification_token: "" mode: "websocket" llm: provider: "openai_compatible" base_url: "https://your-model-endpoint.example.com/v1" api_key: "sk-demo-key" model: "your-model-name" temperature: 0.7 max_tokens: 1024 chat: system_prompt: "你是一个乐于助人的助手，回答简洁、准确。" history_max_turns: 20 enable_context: true server: log_level: "info"保存配置文件后，运行python main.py启动服务。只要没有报错，日志里会出现类似"已连接到飞书长连接网关"的信息，这时机器人就正式上线了。
6. 联调：跑通第一条消息
6.1 第一次启动时日志怎么才算正常
我第一次启动时，看到终端刷了一堆日志，不知道哪些是正常现象，哪些是报错。跑通之后总结起来，只需要关注几个关键输出：
- 配置加载成功，没有出现
config error或key not found。 - 成功注册事件处理器。
- 成功建立 WebSocket 连接并完成飞书网关握手。
出现连接成功或gateway connected类似字样后，服务就算起来了。如果卡在连接阶段，大概率是 App ID 或 App Secret 填错，或者网络无法访问飞书服务器。
6.2 给机器人发一条测试消息
在飞书里找到你的应用机器人（可以直接在搜索框搜应用名），发送一条"你好"。
正常的链路是：消息先到飞书服务器，再通过长连接推送到本机进程，openclaw-cn 调用模型接口拿到回答，再通过飞书发送 API 把回复发回对话里。整个过程一般 2 到 5 秒，取决于模型响应速度。
如果机器人没有回复，先看本地终端有没有收到事件日志：
- 如果本地完全没日志，说明长连接没建立或事件订阅有问题，回到飞书后台检查事件订阅列表。
- 如果日志显示收到消息但报错，把报错信息贴出来逐行看。
- 如果日志正常但没有发出回复，多半是模型接口调用失败，检查 API Key 和网络连通性。
6.3 常见启动失败对照表
我把联调过程中可能遇到的问题整理成一个速查表，方便对照排查：
| 现象 | 大概率原因 | 处理方式 |
|---|---|---|
| 启动即报配置错误 | YAML 缩进不对或字段名错误 | 用文本编辑器检查缩进，字段名与官方示例对照 |
| 一直卡在连接网关 | App ID / Secret 填错 | 回后台复制正确值，注意别带空格 |
| 收到消息但没回复 | 模型接口超时或 Key 无效 | 先单独用 curl 测试模型接口，确认可用 |
| 回复提示"发送失败" | 机器人权限不足或未发布版本 | 回到开放平台检查权限并发布新版本 |
| 偶尔重复回复 | 飞书事件重试机制 | 这是正常重试，确认本地是否处理了重复事件 |
提示：飞书的事件推送自带重试机制。如果你本机处理超时，飞书会重新推送同一事件。openclaw-cn 内部一般会做幂等处理，但你手动改代码时要格外注意这个特性。
7. Windows 上才会遇到的坑
7.1 控制台中文乱码
这个坑几乎必踩。Windows 默认控制台代码页是 GBK，而 openclaw-cn 的日志输出是 UTF-8，结果就是终端里出现一堆乱码，根本没办法看日志。
解决办法是在启动命令之前临时设置环境变量：
set PYTHONIOENCODING=utf-8 python main.py如果你想一劳永逸，建议使用 Windows Terminal 作为终端，并把默认代码页设为 UTF-8。前面提到的系统区域设置里勾选 UTF-8 支持也是办法，但影响范围较大，根据自己情况选择。
7.2 防火墙拦截导致长连接失败
长连接模式下，openclaw-cn 需要主动访问外网，如果 Windows 防火墙弹窗提示"是否允许 Python 访问网络"，一定要点允许。
我遇到过一种隐蔽情况：第一次启动时我点了"取消"，进程看起来正常，但 WebSocket 一直连不上。后来才发现是防火墙规则把 Python 拦截了。处理方式是在"防火墙 - 允许应用通过防火墙"里手动找到 Python，勾选"专用"和"公用"两个网络类型。
7.3 开机自启和后台运行
命令行窗口一关，机器人就没了。如果想让机器人长期挂在后台，建议写一个启动脚本：
@echo off cd /d D:\tools\openclaw-cn call venv\Scripts\activate.bat set PYTHONIOENCODING=utf-8 python main.py然后利用任务计划程序创建基本任务：触发器选择"计算机启动时"，操作选择"启动程序"，指向这个 bat 文件。
还有一个细节：如果你手动关掉了终端窗口，Python 进程可能还残留在后台，导致下次启动时报"端口被占用"或"已有实例在运行"。遇到这种情况，打开任务管理器找到残留的 python 进程结束掉再启动，或者用一条命令做清理：
taskkill /F /IM python.exe注意：这条命令会把所有 Python 进程都关掉，如果有其他项目正在运行，先保存好数据再用。
7.4 自动更新和休眠设置
这是两个很容易被忽略的系统级配置。Win10 默认的自动更新偶尔会安排重启，重启后机器人自然就断了。我建议在组策略或设置里把活跃时间调高，或者干脆手动控制更新安装时段，确保机器人运行期间不会自动重启。
电源设置里还要把"睡眠"改为"从不"。别笑，真的有人折腾半天发现机器人一断网就恢复不了，最后发现是电脑半夜自动休眠了。插着电源时通常默认性能模式不会睡眠，但部分台式机 BIOS 设置或电源计划里确实有定时休眠的选项，检查一次最省心。
8. 之后还可以怎么玩
跑通基础对话之后，可以继续扩展几个方向，都不需要改太多代码：
一是接入多个群聊。在飞书后台把机器人添加到不同群，然后在配置里设置允许响应的群列表，就可以做到只在一个群里应答，避免无关群聊打扰。
二是做指令白名单。比如把!clear映射为清空上下文，把!system加上管理员才能触发的系统指令。这些逻辑在 openclaw-cn 里通常通过监听消息前缀实现，为项目增加一层操作入口。
三是换一个更合适的模型。不同模型在"指令遵循""中文表达""响应速度"上的表现差异很明显，建议同一个问题拿不同模型分别试几轮，再定下最终配置。openclaw-cn 的好处是换模型只需改config.yaml里的base_url和model两个字段，不用改代码。
我个人在实际使用中的体会是：openclaw-cn 的价值不在于功能有多炫，而在于它把消息平台和模型之间的兼容逻辑收敛到一个文件里，让我可以专注在"机器人该说什么"而不是"消息怎么送达"。如果你也打算在 Windows 机器上长期跑一个飞书机器人，按照文章中这几步来，基本不会遇到超出预期的幺蛾子。最后再分享一个小技巧：每次改完config.yaml，别直接重启服务，先观察配置文件加载日志，确认它真的读到了你修改后的内容，再进入下一步联调，能省掉不少"改了没生效"的怀疑时间。
