最近折腾了一个周末总算在 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.11openclaw-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 PYTHONIOENCODINGutf-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 PYTHONIOENCODINGutf-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别直接重启服务先观察配置文件加载日志确认它真的读到了你修改后的内容再进入下一步联调能省掉不少改了没生效的怀疑时间。