最近我把 OpenClaw 在本地完整部署了一遍同时把飞书机器人接了进来整个链路从“能跑”到“好用”折腾了大概一个周末。今天这篇就把整套流程包括 Windows 下的 WSL2 环境、模型通道配置、飞书开放平台的机器人接入、回调地址处理以及我踩过的几个典型坑一次性写清楚。先说结论OpenClaw 是一个开源的个人 AI 助手网关/调度框架你可以把它理解成一个“大脑的接线员”——后面接任意大模型Ollama、OpenAI 兼容接口、魔搭推理服务等前面接任意消息渠道飞书、微信、Telegram、终端、Web中间还能挂工具调用、定时任务、文件处理这些能力。这篇指南适合三类人想用本地大模型做个真正能聊天的飞书机器人的人、被openclaw could not safely verify the wsl2 environment这类报错卡住的人、以及正在纠结“本地部署到底怎么选模型、怎么配回调”的开发者。1. OpenClaw 到底能干什么先搞清楚再动手动手部署之前我强烈建议你先理解 OpenClaw 在整套系统里扮演什么角色。否则你很容易把它当成“又一个聊天机器人项目”然后部署完发现它怎么连个界面都没有直接懵。1.1 一个“AI 助手调度中枢”的定位你可以把 OpenClaw 想成公司里的总机接线员。它自己不产生回答也不存知识它只干三件事接收消息、调度大脑、把结果送回消息渠道。消息端飞书、微信、Telegram、命令行甚至是 Webhook都是它的“电话线”。大脑端本地 Ollama、OpenAI 兼容接口、魔搭 ModelScope 推理服务谁在线就用谁。工具端定时任务、文件读写、命令执行、外部 API 调用这些都是它“手里的分机”。这种设计最大的好处是解耦。你换模型不用动消息渠道换消息渠道不用动模型配置。我一开始只接了 Ollama 跑本地模型后来想试试云端接口改一个配置文件里的 provider 就行完全没有动飞书那边的任何东西。1.2 本地部署的意义数据、成本、可控我知道很多人会问飞书本身不是有 AI 机器人吗为什么还要自己本地部署一套核心差异在于三点。第一是数据私密性。走飞书官方 AI 或者云端大模型接口你的对话内容会经过第三方服务。本地部署意味着所有聊天记录和模型推理都发生在你自己的机器上对内部沟通、代码片段、敏感信息这类场景非常重要。第二是成本可控。本地模型跑起来之后调用次数基本不花钱只有电费。我用一块 16G 显存的卡跑 14B 模型日常问答完全够用一个月电费也就是几十块。如果走云端 API按 token 计费团队里几个人高频用一天下来就是不小的数目。第三是可控性。OpenClaw 是开源框架你可以改它的调度逻辑、加自定义工具、调整系统提示词。官方机器人能给什么功能、不能给什么功能那是别人说了算的自己部署所有边界都是自己定义。1.3 典型使用场景从热词里能看到现在大家最常玩的是这几个方向在飞书群里直接问本地模型比如“总结一下这个群今天的讨论”“帮我写一段 Python 脚本”——这是最基础、也是我自己用得最多的场景。让机器人主动干活比如每天早上定时推送天气、待办、代码仓库动态这个后面进阶部分细讲。把 Codex CLI 这类编程代理接到飞书群——群里有同事发任务Agent 在后台执行执行完把结果贴回群里。这就是典型的“人机协作”玩法。2. 部署前必须想清楚的四件事我开始部署的时候就是吃了没提前规划环境的亏装到一半发现 Python 版本不对换完 Python 又发现 WSL2 内核没更新。所以这篇我特意把环境准备放在最前面你照着走可以少走很多弯路。2.1 跑在哪个环境Windows、macOS 还是 Linux这三个平台我都试过体验差异非常大。Linux 是最省心的Ubuntu 22.04 或者 Debian 12 都可以依赖一装就能跑OpenClaw 的设计思路也是以 Linux 为第一优先级的。如果你的主力机是 Linux直接跳到 2.2 节。macOS 也能跑Apple Silicon 机型用 Ollama 跑 7B/8B 模型效果不错但显存统一内存有限跑 14B 以上模型会比较吃力。部署本身没什么大坑就是注意 Python 要用 3.10 以上版本别用系统自带的旧 Python。Windows 是最折腾的官方推荐通过 WSL2 来跑因为 OpenClaw 内部很多进程管理和网络通信逻辑在原生 Windows 环境下会出现奇奇怪怪的问题。我在 Windows 11 上部署时遇到的最典型报错是openclaw could not safely verify the wsl2 environment.这个问题第 5 节我会专门讲怎么排查。现在你只需要知道Windows 用户先确认 WSL2 环境是好的再装 OpenClaw顺序不能反。2.2 大模型后端怎么选OpenClaw 本身不打包模型你需要自己提供一个“模型来源”。我的建议是先想清楚你的硬件条件再决定用哪种后端。有 N 卡且显存 ≥ 8G 的直接用 Ollama 拉本地模型这是性价比最高的方案。显存 16G 可以跑 14B 模型32G 以上可以尝试 32B 模型。卡不行的就别硬撑配一个 OpenAI 兼容接口把 base_url 指到云端服务商一样能玩。我自己的配置是 Ollama qwen2.5:14b日常问答和代码生成都够用。如果你需要更强的推理能力可以接 DeepSeek 系列或者用魔搭 ModelScope 的推理服务OpenClaw 支持配置第三方兼容接口魔搭上很多模型可以直接用 OpenAI 兼容模式调用。这里给你一个简单的模型选型参考表硬件条件推荐模型适用场景8G 显存7B/8B 量化模型日常问答、简单代码16G 显存14B 量化模型综合能力较强兼顾质量和速度32G 以上显存32B 量化模型复杂推理、长文本处理无独立显卡云端 API 接口任何场景按需付费2.3 依赖组件清单部署前把依赖装齐能省掉一半的排查时间。我的经验是把下面这些东西都准备好再动手Python 3.10 以上版本最好用 3.11 或者 3.12。Git从源码安装时要用。WSL2仅 Windows 用户需要并且确认默认发行版是 Ubuntu 或者 Debian。Docker可选如果你不想污染本机环境可以直接用镜像跑。一个内网穿透工具比如 cloudflared、ngrok 或者 frp。接飞书回调时必须有一个公网可访问的 HTTPS 地址这个后面细说。Redis可选如果 OpenClaw 版本用到了任务队列或者缓存Redis 会是依赖项之一具体看官方文档。2.4 API 密钥和凭证提前备齐部署过程中最大的卡点其实是各种凭证没提前准备好。Ollama 本地模型不需要密钥这部分最省事。如果你要用 OpenAI 兼容接口需要去对应服务商的后台生成 API Key注意很多平台的 Key 只显示一次要立刻保存。魔搭 ModelScope 的推理服务也需要在控制台获取 API Key。飞书那边需要准备的东西更多企业自建应用的 App ID、App Secret、事件订阅的 Encrypt Key 和 Verification Token。这些不是部署 OpenClaw 时就能生成的必须先到飞书开放平台创建应用、开通机器人能力、配置事件订阅才能拿到完整凭证。第 4 节我会一步步带你配。注意API 密钥和 Secret 一定不要提交到 Git 仓库也不要写在 Dockerfile 里。我见过有人把 App Secret 直接写在配置文件里推到 GitHub 公开仓库结果被爬虫扫到机器人直接被别人接管了。3. 本地部署完整实操从零到跑通环境想清楚之后下面就开始正式部署。我先说 Windows WSL2 的路径因为这条路径坑最多讲透它其他平台基本都能举一反三。3.1 Windows 下 WSL2 环境准备与“could not safely verify”报错在 Windows 上部署 OpenClaw第一步不是装 Python而是把 WSL2 准备好。我用的是 Windows 11安装命令非常简单wsl --install装完之后把默认版本设置成 2wsl --set-default-version 2然后确认一下当前发行版的版本wsl -l -v输出里 NAME 列应该显示你的发行版名称VERSION 列必须显示 2。如果显示的是 1说明你的 WSL 内核版本不够需要更新wsl --update更新完再执行wsl -l -v确认。这一步做完再进入 WSL 环境安装 OpenClawopenclaw could not safely verify the wsl2 environment这个报错基本就不会再出现了。这个报错本质上是 OpenClaw 启动时检测不到一个“安全可信”的 WSL2 运行环境。它检测的内容大概包括WSL 内核版本、默认版本是否设置为 2、是否有可用的默认发行版。任何一项不满足它都会拒绝继续执行。我第一次遇到这个报错时就是 WSL 装了但内核版本太老wsl --update之后立刻就好了。3.2 安装主程序与初始化配置进入 WSL 环境后推荐用 pip 安装pip install openclaw如果你想用最新开发版也可以从源码装git clone https://github.com/openclaw/openclaw.git cd openclaw pip install -e .装完之后初始化配置目录openclaw init这个命令会在~/.openclaw/下生成配置文件默认是config.yaml。打开这个文件你会看到它已经预留了平台platforms和模型llm两大块配置接下来要做的就是往里面填内容。3.3 模型通道配置以 Ollama 为例我先把 Ollama 装好并拉取模型curl -fsSL https://ollama.com/install.sh | sh ollama pull qwen2.5:14b然后编辑~/.openclaw/config.yaml里的模型部分llm: provider: ollama base_url: http://localhost:11434/v1 model: qwen2.5:14b temperature: 0.7 max_tokens: 2048如果你用的是 OpenAI 兼容接口改成这样llm: provider: openai base_url: https://your-api-endpoint.com/v1 api_key: sk-xxxx model: deepseek-chat魔搭 ModelScope 同理只要服务商提供 OpenAI 兼容端点就改base_url和api_key即可。这个设计非常方便切换模型后端像换插头一样。3.4 跑起来的第一条消息控制台自测配置文件填好之后先别急着接飞书先在命令行验证整个链路是通的openclaw chat然后输入“你好”看模型是否能正常返回。这一步能帮你把“模型配置问题”和“平台接入问题”切分开来。如果控制台自测都失败先排查模型配置如果控制台正常但飞书不回复再排查飞书回调。我第一次部署时就是跳过了这步直接接飞书结果机器人在群里怎么都不回消息。排查了半天最后发现是 Ollama 服务没启动。如果先做控制台自测这个问题一分钟就能定位。4. 飞书接入从零创建一个能聊天的机器人飞书接入是整套系统里最有成就感、也最容易出问题的一环。难点不在于 OpenClaw 的配置而在于飞书开放平台那些“你必须自己点出来的按钮”。4.1 飞书开放平台建应用开通机器人权限打开飞书开放平台登录后进入开发者后台点击“创建企业自建应用”。名字随便起比如“本地 AI 助手”。创建完成后你会进入应用详情页。第一步是开通机器人能力。在“应用能力”里找到“机器人”点击开启。这个能力不开启你的应用就没有“机器人”这个身份群里也就搜不到它。第二步是配置权限。在“权限管理”里搜索并开通以下权限im:message读取和发送消息。im:message:send_as_bot以机器人身份发送消息。im:chat:readonly读取群信息如果有群管理需求再开。权限开完之后关键一步是发布版本。在“版本管理与发布”里创建一个版本填上版本号提交发布。如果只是自己用审核会很快如果是在企业组织里需要管理员审批。不发布版本的话权限是不会生效的这一点很多人会漏掉。4.2 事件订阅与回调地址内网穿透怎么选机器人要能“收到消息”必须让飞书知道“有新消息时往哪里推”。这个推送地址就是事件订阅的回调地址。在“事件与回调”里添加事件选择im.message.receive_v1也就是“接收消息”事件。飞书要求这个回调地址必须是公网可访问的 HTTPS 地址。本地开发环境没有公网地址怎么办用内网穿透工具。我试过两种方案体验上 cloudflared 的免费额度更舒服ngrok 胜在配置简单。用 cloudflared 启动一个临时隧道cloudflared tunnel --url http://localhost:8080它会生成一个https://xxx.trycloudflare.com的地址把这个地址填到飞书回调配置里再在 OpenClaw 里配置对应的回调路径就能打通。注意飞书回调地址要求路径和你本地服务路由一致比如https://xxx.trycloudflare.com/openclaw/feishu/callback这里有一个容易踩的坑飞书会验证回调地址的可用性验证机制是向你的回调地址发送一个 POST 请求里面带challenge字段要求原样返回。OpenClaw 会自动处理这个验证逻辑你不需要自己写但前提是你的 OpenClaw 服务必须在公网隧道里能访问到。如果你启动隧道之后飞书还是报“回调地址验证失败”先 curl 一下你的公网地址确认服务真的通。4.3 OpenClaw 里的飞书配置项逐一说明打开~/.openclaw/config.yaml在 platforms 下加飞书配置platforms: feishu: app_id: cli_xxxxxxxx app_secret: xxxxxxxx encrypt_key: xxxxxxxx verification_token: xxxxxxxx callback_path: /openclaw/feishu/callbackapp_id和app_secret在飞书开放平台应用的“凭证与基础信息”里可以找到。encrypt_key和verification_token在“事件与回调”页面里如果开启了“加密策略”飞书会给你 Encrypt KeyVerification Token 是明文校验用的建议都填上多一层校验多一层安全。callback_path要和你在飞书填的回调 URL 路径一致。关于加密策略我建议开启。飞书支持对回调事件进行 AES 加密开启后即使回调地址被泄露攻击者没有 Encrypt Key 也解不开事件内容。OpenClaw 会自动处理解密你只需要把 Encrypt Key 填进配置。4.4 联调测试在飞书里 机器人配置全部填好后启动 OpenClaw 服务openclaw serve看到日志里输出“feishu platform started”之类的信息就说明平台接入成功了。然后打开飞书搜索你的应用名称找到机器人拉到一个群里输入“你好”并 它。正常的链路应该是这样的飞书收到消息POST 到你的公网回调地址。OpenClaw 的飞书平台模块接收到事件解析消息内容。OpenClaw 把消息交给 LLM 模块调用本地模型生成回答。回答通过飞书 API 发送回群聊。我在联调时最容易出问题的点是第 4 步——“机器人没有发消息权限”。明明前面开了im:message:send_as_bot也发布了版本但机器人还是发不出消息。后来发现是发布版本后没有等待生效重新发布一次就好了。5. 常见问题与排查技巧实录这一节是我最想写的内容。前面那些步骤网上都能搜到但真正部署过程中踩的坑很多是文档里不会写的。5.1 “OpenClaw 能发消息微信但微信发消息没回复”怎么排查热搜词里有“openclaw能发消息微信.但微信发消息没回复”这确实是个高频问题。先说结论这个问题的根源几乎都在“消息回调链路”而不是模型。OpenClaw 能发消息说明它已经拿到了微信侧的发送凭证但微信发消息没回复说明 OpenClaw 根本没有收到“新消息”这个事件。常规的排查顺序是这样看 OpenClaw 日志你给机器人发消息后日志里有没有“receive message”之类的输出。如果有说明回调正常问题在后续处理链路。如果有日志但没回复重点查模型状态手动在控制台跑一次openclaw chat看模型能不能正常返回。如果完全没日志说明回调根本没进来。检查微信侧的“接收消息”回调配置确认回调地址是否填写正确、是否公网可达。这里我也要提醒一句个人微信的自动化接入本身就存在账号风控风险官方并不支持这种用法长期挂机很容易被限制登录。如果是团队场景我更推荐用飞书或者企业微信这类提供官方开放平台的渠道稳定性完全不是一个量级。5.2 “could not safely verify the wsl2 environment”完整处理流程这个报错我在第 3.1 节提过这里把完整处理流程整理成速查表处理步骤命令/操作验证方法升级 WSL 内核wsl --update无报错即成功设置默认版本为 2wsl --set-default-version 2输出提示操作完成检查发行版版本wsl -l -vVERSION 列显示 2重启 WSLwsl --shutdown重新进入正常进入发行版重启 Windows必要时重启后再进 WSL环境恢复正常需要注意的是这个报错还有一种隐藏可能性杀毒软件拦截了 OpenClaw 对 WSL 环境的检测。如果你系统里装了安全软件而且以上步骤都正常但报错依旧可以临时退出安全软件试试能跑通了再考虑加白名单。5.3 飞书机器人不回消息的排查顺序飞书接入后不回消息原因比微信那边更集中一些基本逃不出这四个位置第一回调没到服务器。看 OpenClaw 日志如果有请求进来但校验失败日志里会带错误信息。第二加密策略配置不一致。飞书侧开启加密后OpenClaw 侧必须填对 Encrypt Key否则解密失败消息会被静默丢弃。第三模型响应超时。本地模型推理慢飞书对回调响应有超时要求如果模型超过时间没返回飞书会认为回调失败并重试重试堆积会导致更多超时。第四发送权限不足。机器人没有send_as_bot权限或者应用版本未发布都会导致“能收到你的消息但发不出回复”。我分享一个自己的经验如果你发现飞书机器人偶尔回、偶尔不回多半是模型超时而不是配置问题。把模型换成更小的量化版本或者调低max_tokens症状会明显缓解。5.4 模型回答慢或总是超时本地部署最影响体验的就是速度。我实测下来同一个 14B 模型在 16G 显存下不量化大概每秒只能生成十几个 token对话还行但稍微长一点的回答就会感觉到明显等待。解决办法有三个方向降模型规模日常聊天用 7B/8B 就够14B 留给复杂任务。用量化版本Ollama 标签里的q4_k_m这类量化格式能显著降低显存占用提升速度。控制上下文长度在 OpenClaw 配置里把max_tokens调低同时在飞书侧设置合适的回调超时时间避免生成长文本时被判定超时。5.5 卸载和重装如果你配置改坏了想重新来过卸载过程也很简单pip uninstall openclaw rm -rf ~/.openclawDocker 部署的话把容器和 volume 删掉即可docker rm -f openclaw docker volume rm openclaw_data网上热词里有“openclaw本地一键部署”部分版本确实提供了一键安装脚本但我建议你至少手动走一遍init流程因为你只有在手动配置的过程中才会真正理解每个配置项是干什么的。我之前就是图省事用一键脚本结果模型配置错了都不知道该改哪里。6. 部署完之后的进阶玩法基础链路通了之后整个系统才算真正属于你了。这一节分享几个我部署完之后的进阶玩法全部亲测有效。6.1 让机器人主动干活定时任务OpenClaw 支持定时任务调度。你可以让机器人每天早上 9 点自动在群里推送“今日待办”也可以让它定时抓取某个网页的更新。配置方式是在config.yaml里增加 tasks 段落指定 cron 表达式和要执行的 prompttasks: - name: daily_report schedule: 0 9 * * * prompt: 根据最近 24 小时的群消息整理一份工作日报包括关键进展和待办事项。 channel: feishu target: oc_群ID这个功能的价值在于机器人从一个“被动问答工具”变成了“主动执行的工作助理”体验完全不一样。6.2 多模型路由贵模型干粗活便宜模型干杂活本地部署最怕的就是“一个模型打天下”。我现在的配置是双模型路由日常闲聊、简单问答走 7B 量化模型速度快、不心疼算力。代码生成、复杂推理、长文档总结走 14B 模型质量优先。在 OpenClaw 里可以配置不同会话类型走不同模型或者通过特定指令触发切换。这有点像一个团队里既有初级工程师又有高级工程师任务分派下去谁合适谁干资源利用率能提高一个层次。6.3 把 Codex CLI 这类编程 Agent 接入飞书群很多人问“codex cli 接入飞书”怎么玩。其实思路很简单Codex CLI 是一个可以在本地执行的编程代理OpenClaw 本身没有编程能力但它可以调用外部工具。你只需要把 Codex CLI 封装成一个可被 OpenClaw 调用的命令工具然后在飞书群里发任务OpenClaw 解析任务后调用 Codex CLI 执行把执行结果贴回群里。我这里给一个最小的封装思路# /usr/local/bin/codex-run codex exec --prompt $1 --output /tmp/codex_result.md cat /tmp/codex_result.md然后在 OpenClaw 的工具配置里注册这个命令设定好调用权限和参数说明即可。这个玩法非常实用等于把“人机协作”的入口搬到了即时通讯工具里。6.4 Termux 移动端部署无 proot 的轻量玩法热搜里有“在安卓termux原生部署openclaw:无proot轻”这个我也试过。Termux 是一个 Android 上的终端模拟器OpenClaw 可以直接在里面跑不需要 proot相对轻量。操作步骤大致是在 Termux 里安装 Python、Git用 pip 安装 OpenClaw然后通过 cloudflared 隧道把服务暴露出去。手机端部署的意义在于你可以把一台旧 Android 手机变成常驻的 AI 助手服务器成本极低而且不占桌面空间。当然性能有限跑大模型还是得靠远端接口但作为“消息转发中枢”完全够用。6.5 安全加固别让你的机器人裸奔最后提醒一点安全建议。因为你的 OpenClaw 服务是暴露在公网上的为了接飞书回调所以你至少要确认以下几点飞书回调路径之外的页面不要对外暴露最好在应用层面加一层鉴权中间件。配置文件里所有密钥不要用明文写死可以通过环境变量注入比如app_secret: ${FEISHU_APP_SECRET}。如果部署在云服务器上防火墙只放行必要端口飞书回调一般只走 443/8080其他端口能关就关。定期关注 OpenClaw 上游版本更新有安全修复就及时升级。我个人在实际操作中最深刻的体会是部署这种自托管项目前 20% 的时间花在“跑通”后 80% 的时间花在“稳定”和“安全”。不要把精力全放在炫酷的功能上先把基础链路打磨稳再慢慢加花样。最后再分享一个实用小技巧接完飞书后先在本地日志里确认回调进来的消息格式再决定要不要开加密策略。如果刚开始调试建议先不开加密等消息链路完全稳定了再开启加密并配好 Encrypt Key这样能少踩一个变量引发的坑。我的机器人到现在已经稳定跑了一个多月每天早上自动推送日报群里随叫随到这个投入产出比我个人非常满意。 
长河君 · 2026/9/20 3:00:45 · 阅读 1.2k OpenClaw本地部署+飞书机器人接入：从环境配置到踩坑排查全指南
最近我把 OpenClaw 在本地完整部署了一遍同时把飞书机器人接了进来整个链路从“能跑”到“好用”折腾了大概一个周末。今天这篇就把整套流程包括 Windows 下的 WSL2 环境、模型通道配置、飞书开放平台的机器人接入、回调地址处理以及我踩过的几个典型坑一次性写清楚。先说结论OpenClaw 是一个开源的个人 AI 助手网关/调度框架你可以把它理解成一个“大脑的接线员”——后面接任意大模型Ollama、OpenAI 兼容接口、魔搭推理服务等前面接任意消息渠道飞书、微信、Telegram、终端、Web中间还能挂工具调用、定时任务、文件处理这些能力。这篇指南适合三类人想用本地大模型做个真正能聊天的飞书机器人的人、被openclaw could not safely verify the wsl2 environment这类报错卡住的人、以及正在纠结“本地部署到底怎么选模型、怎么配回调”的开发者。1. OpenClaw 到底能干什么先搞清楚再动手动手部署之前我强烈建议你先理解 OpenClaw 在整套系统里扮演什么角色。否则你很容易把它当成“又一个聊天机器人项目”然后部署完发现它怎么连个界面都没有直接懵。1.1 一个“AI 助手调度中枢”的定位你可以把 OpenClaw 想成公司里的总机接线员。它自己不产生回答也不存知识它只干三件事接收消息、调度大脑、把结果送回消息渠道。消息端飞书、微信、Telegram、命令行甚至是 Webhook都是它的“电话线”。大脑端本地 Ollama、OpenAI 兼容接口、魔搭 ModelScope 推理服务谁在线就用谁。工具端定时任务、文件读写、命令执行、外部 API 调用这些都是它“手里的分机”。这种设计最大的好处是解耦。你换模型不用动消息渠道换消息渠道不用动模型配置。我一开始只接了 Ollama 跑本地模型后来想试试云端接口改一个配置文件里的 provider 就行完全没有动飞书那边的任何东西。1.2 本地部署的意义数据、成本、可控我知道很多人会问飞书本身不是有 AI 机器人吗为什么还要自己本地部署一套核心差异在于三点。第一是数据私密性。走飞书官方 AI 或者云端大模型接口你的对话内容会经过第三方服务。本地部署意味着所有聊天记录和模型推理都发生在你自己的机器上对内部沟通、代码片段、敏感信息这类场景非常重要。第二是成本可控。本地模型跑起来之后调用次数基本不花钱只有电费。我用一块 16G 显存的卡跑 14B 模型日常问答完全够用一个月电费也就是几十块。如果走云端 API按 token 计费团队里几个人高频用一天下来就是不小的数目。第三是可控性。OpenClaw 是开源框架你可以改它的调度逻辑、加自定义工具、调整系统提示词。官方机器人能给什么功能、不能给什么功能那是别人说了算的自己部署所有边界都是自己定义。1.3 典型使用场景从热词里能看到现在大家最常玩的是这几个方向在飞书群里直接问本地模型比如“总结一下这个群今天的讨论”“帮我写一段 Python 脚本”——这是最基础、也是我自己用得最多的场景。让机器人主动干活比如每天早上定时推送天气、待办、代码仓库动态这个后面进阶部分细讲。把 Codex CLI 这类编程代理接到飞书群——群里有同事发任务Agent 在后台执行执行完把结果贴回群里。这就是典型的“人机协作”玩法。2. 部署前必须想清楚的四件事我开始部署的时候就是吃了没提前规划环境的亏装到一半发现 Python 版本不对换完 Python 又发现 WSL2 内核没更新。所以这篇我特意把环境准备放在最前面你照着走可以少走很多弯路。2.1 跑在哪个环境Windows、macOS 还是 Linux这三个平台我都试过体验差异非常大。Linux 是最省心的Ubuntu 22.04 或者 Debian 12 都可以依赖一装就能跑OpenClaw 的设计思路也是以 Linux 为第一优先级的。如果你的主力机是 Linux直接跳到 2.2 节。macOS 也能跑Apple Silicon 机型用 Ollama 跑 7B/8B 模型效果不错但显存统一内存有限跑 14B 以上模型会比较吃力。部署本身没什么大坑就是注意 Python 要用 3.10 以上版本别用系统自带的旧 Python。Windows 是最折腾的官方推荐通过 WSL2 来跑因为 OpenClaw 内部很多进程管理和网络通信逻辑在原生 Windows 环境下会出现奇奇怪怪的问题。我在 Windows 11 上部署时遇到的最典型报错是openclaw could not safely verify the wsl2 environment.这个问题第 5 节我会专门讲怎么排查。现在你只需要知道Windows 用户先确认 WSL2 环境是好的再装 OpenClaw顺序不能反。2.2 大模型后端怎么选OpenClaw 本身不打包模型你需要自己提供一个“模型来源”。我的建议是先想清楚你的硬件条件再决定用哪种后端。有 N 卡且显存 ≥ 8G 的直接用 Ollama 拉本地模型这是性价比最高的方案。显存 16G 可以跑 14B 模型32G 以上可以尝试 32B 模型。卡不行的就别硬撑配一个 OpenAI 兼容接口把 base_url 指到云端服务商一样能玩。我自己的配置是 Ollama qwen2.5:14b日常问答和代码生成都够用。如果你需要更强的推理能力可以接 DeepSeek 系列或者用魔搭 ModelScope 的推理服务OpenClaw 支持配置第三方兼容接口魔搭上很多模型可以直接用 OpenAI 兼容模式调用。这里给你一个简单的模型选型参考表硬件条件推荐模型适用场景8G 显存7B/8B 量化模型日常问答、简单代码16G 显存14B 量化模型综合能力较强兼顾质量和速度32G 以上显存32B 量化模型复杂推理、长文本处理无独立显卡云端 API 接口任何场景按需付费2.3 依赖组件清单部署前把依赖装齐能省掉一半的排查时间。我的经验是把下面这些东西都准备好再动手Python 3.10 以上版本最好用 3.11 或者 3.12。Git从源码安装时要用。WSL2仅 Windows 用户需要并且确认默认发行版是 Ubuntu 或者 Debian。Docker可选如果你不想污染本机环境可以直接用镜像跑。一个内网穿透工具比如 cloudflared、ngrok 或者 frp。接飞书回调时必须有一个公网可访问的 HTTPS 地址这个后面细说。Redis可选如果 OpenClaw 版本用到了任务队列或者缓存Redis 会是依赖项之一具体看官方文档。2.4 API 密钥和凭证提前备齐部署过程中最大的卡点其实是各种凭证没提前准备好。Ollama 本地模型不需要密钥这部分最省事。如果你要用 OpenAI 兼容接口需要去对应服务商的后台生成 API Key注意很多平台的 Key 只显示一次要立刻保存。魔搭 ModelScope 的推理服务也需要在控制台获取 API Key。飞书那边需要准备的东西更多企业自建应用的 App ID、App Secret、事件订阅的 Encrypt Key 和 Verification Token。这些不是部署 OpenClaw 时就能生成的必须先到飞书开放平台创建应用、开通机器人能力、配置事件订阅才能拿到完整凭证。第 4 节我会一步步带你配。注意API 密钥和 Secret 一定不要提交到 Git 仓库也不要写在 Dockerfile 里。我见过有人把 App Secret 直接写在配置文件里推到 GitHub 公开仓库结果被爬虫扫到机器人直接被别人接管了。3. 本地部署完整实操从零到跑通环境想清楚之后下面就开始正式部署。我先说 Windows WSL2 的路径因为这条路径坑最多讲透它其他平台基本都能举一反三。3.1 Windows 下 WSL2 环境准备与“could not safely verify”报错在 Windows 上部署 OpenClaw第一步不是装 Python而是把 WSL2 准备好。我用的是 Windows 11安装命令非常简单wsl --install装完之后把默认版本设置成 2wsl --set-default-version 2然后确认一下当前发行版的版本wsl -l -v输出里 NAME 列应该显示你的发行版名称VERSION 列必须显示 2。如果显示的是 1说明你的 WSL 内核版本不够需要更新wsl --update更新完再执行wsl -l -v确认。这一步做完再进入 WSL 环境安装 OpenClawopenclaw could not safely verify the wsl2 environment这个报错基本就不会再出现了。这个报错本质上是 OpenClaw 启动时检测不到一个“安全可信”的 WSL2 运行环境。它检测的内容大概包括WSL 内核版本、默认版本是否设置为 2、是否有可用的默认发行版。任何一项不满足它都会拒绝继续执行。我第一次遇到这个报错时就是 WSL 装了但内核版本太老wsl --update之后立刻就好了。3.2 安装主程序与初始化配置进入 WSL 环境后推荐用 pip 安装pip install openclaw如果你想用最新开发版也可以从源码装git clone https://github.com/openclaw/openclaw.git cd openclaw pip install -e .装完之后初始化配置目录openclaw init这个命令会在~/.openclaw/下生成配置文件默认是config.yaml。打开这个文件你会看到它已经预留了平台platforms和模型llm两大块配置接下来要做的就是往里面填内容。3.3 模型通道配置以 Ollama 为例我先把 Ollama 装好并拉取模型curl -fsSL https://ollama.com/install.sh | sh ollama pull qwen2.5:14b然后编辑~/.openclaw/config.yaml里的模型部分llm: provider: ollama base_url: http://localhost:11434/v1 model: qwen2.5:14b temperature: 0.7 max_tokens: 2048如果你用的是 OpenAI 兼容接口改成这样llm: provider: openai base_url: https://your-api-endpoint.com/v1 api_key: sk-xxxx model: deepseek-chat魔搭 ModelScope 同理只要服务商提供 OpenAI 兼容端点就改base_url和api_key即可。这个设计非常方便切换模型后端像换插头一样。3.4 跑起来的第一条消息控制台自测配置文件填好之后先别急着接飞书先在命令行验证整个链路是通的openclaw chat然后输入“你好”看模型是否能正常返回。这一步能帮你把“模型配置问题”和“平台接入问题”切分开来。如果控制台自测都失败先排查模型配置如果控制台正常但飞书不回复再排查飞书回调。我第一次部署时就是跳过了这步直接接飞书结果机器人在群里怎么都不回消息。排查了半天最后发现是 Ollama 服务没启动。如果先做控制台自测这个问题一分钟就能定位。4. 飞书接入从零创建一个能聊天的机器人飞书接入是整套系统里最有成就感、也最容易出问题的一环。难点不在于 OpenClaw 的配置而在于飞书开放平台那些“你必须自己点出来的按钮”。4.1 飞书开放平台建应用开通机器人权限打开飞书开放平台登录后进入开发者后台点击“创建企业自建应用”。名字随便起比如“本地 AI 助手”。创建完成后你会进入应用详情页。第一步是开通机器人能力。在“应用能力”里找到“机器人”点击开启。这个能力不开启你的应用就没有“机器人”这个身份群里也就搜不到它。第二步是配置权限。在“权限管理”里搜索并开通以下权限im:message读取和发送消息。im:message:send_as_bot以机器人身份发送消息。im:chat:readonly读取群信息如果有群管理需求再开。权限开完之后关键一步是发布版本。在“版本管理与发布”里创建一个版本填上版本号提交发布。如果只是自己用审核会很快如果是在企业组织里需要管理员审批。不发布版本的话权限是不会生效的这一点很多人会漏掉。4.2 事件订阅与回调地址内网穿透怎么选机器人要能“收到消息”必须让飞书知道“有新消息时往哪里推”。这个推送地址就是事件订阅的回调地址。在“事件与回调”里添加事件选择im.message.receive_v1也就是“接收消息”事件。飞书要求这个回调地址必须是公网可访问的 HTTPS 地址。本地开发环境没有公网地址怎么办用内网穿透工具。我试过两种方案体验上 cloudflared 的免费额度更舒服ngrok 胜在配置简单。用 cloudflared 启动一个临时隧道cloudflared tunnel --url http://localhost:8080它会生成一个https://xxx.trycloudflare.com的地址把这个地址填到飞书回调配置里再在 OpenClaw 里配置对应的回调路径就能打通。注意飞书回调地址要求路径和你本地服务路由一致比如https://xxx.trycloudflare.com/openclaw/feishu/callback这里有一个容易踩的坑飞书会验证回调地址的可用性验证机制是向你的回调地址发送一个 POST 请求里面带challenge字段要求原样返回。OpenClaw 会自动处理这个验证逻辑你不需要自己写但前提是你的 OpenClaw 服务必须在公网隧道里能访问到。如果你启动隧道之后飞书还是报“回调地址验证失败”先 curl 一下你的公网地址确认服务真的通。4.3 OpenClaw 里的飞书配置项逐一说明打开~/.openclaw/config.yaml在 platforms 下加飞书配置platforms: feishu: app_id: cli_xxxxxxxx app_secret: xxxxxxxx encrypt_key: xxxxxxxx verification_token: xxxxxxxx callback_path: /openclaw/feishu/callbackapp_id和app_secret在飞书开放平台应用的“凭证与基础信息”里可以找到。encrypt_key和verification_token在“事件与回调”页面里如果开启了“加密策略”飞书会给你 Encrypt KeyVerification Token 是明文校验用的建议都填上多一层校验多一层安全。callback_path要和你在飞书填的回调 URL 路径一致。关于加密策略我建议开启。飞书支持对回调事件进行 AES 加密开启后即使回调地址被泄露攻击者没有 Encrypt Key 也解不开事件内容。OpenClaw 会自动处理解密你只需要把 Encrypt Key 填进配置。4.4 联调测试在飞书里 机器人配置全部填好后启动 OpenClaw 服务openclaw serve看到日志里输出“feishu platform started”之类的信息就说明平台接入成功了。然后打开飞书搜索你的应用名称找到机器人拉到一个群里输入“你好”并 它。正常的链路应该是这样的飞书收到消息POST 到你的公网回调地址。OpenClaw 的飞书平台模块接收到事件解析消息内容。OpenClaw 把消息交给 LLM 模块调用本地模型生成回答。回答通过飞书 API 发送回群聊。我在联调时最容易出问题的点是第 4 步——“机器人没有发消息权限”。明明前面开了im:message:send_as_bot也发布了版本但机器人还是发不出消息。后来发现是发布版本后没有等待生效重新发布一次就好了。5. 常见问题与排查技巧实录这一节是我最想写的内容。前面那些步骤网上都能搜到但真正部署过程中踩的坑很多是文档里不会写的。5.1 “OpenClaw 能发消息微信但微信发消息没回复”怎么排查热搜词里有“openclaw能发消息微信.但微信发消息没回复”这确实是个高频问题。先说结论这个问题的根源几乎都在“消息回调链路”而不是模型。OpenClaw 能发消息说明它已经拿到了微信侧的发送凭证但微信发消息没回复说明 OpenClaw 根本没有收到“新消息”这个事件。常规的排查顺序是这样看 OpenClaw 日志你给机器人发消息后日志里有没有“receive message”之类的输出。如果有说明回调正常问题在后续处理链路。如果有日志但没回复重点查模型状态手动在控制台跑一次openclaw chat看模型能不能正常返回。如果完全没日志说明回调根本没进来。检查微信侧的“接收消息”回调配置确认回调地址是否填写正确、是否公网可达。这里我也要提醒一句个人微信的自动化接入本身就存在账号风控风险官方并不支持这种用法长期挂机很容易被限制登录。如果是团队场景我更推荐用飞书或者企业微信这类提供官方开放平台的渠道稳定性完全不是一个量级。5.2 “could not safely verify the wsl2 environment”完整处理流程这个报错我在第 3.1 节提过这里把完整处理流程整理成速查表处理步骤命令/操作验证方法升级 WSL 内核wsl --update无报错即成功设置默认版本为 2wsl --set-default-version 2输出提示操作完成检查发行版版本wsl -l -vVERSION 列显示 2重启 WSLwsl --shutdown重新进入正常进入发行版重启 Windows必要时重启后再进 WSL环境恢复正常需要注意的是这个报错还有一种隐藏可能性杀毒软件拦截了 OpenClaw 对 WSL 环境的检测。如果你系统里装了安全软件而且以上步骤都正常但报错依旧可以临时退出安全软件试试能跑通了再考虑加白名单。5.3 飞书机器人不回消息的排查顺序飞书接入后不回消息原因比微信那边更集中一些基本逃不出这四个位置第一回调没到服务器。看 OpenClaw 日志如果有请求进来但校验失败日志里会带错误信息。第二加密策略配置不一致。飞书侧开启加密后OpenClaw 侧必须填对 Encrypt Key否则解密失败消息会被静默丢弃。第三模型响应超时。本地模型推理慢飞书对回调响应有超时要求如果模型超过时间没返回飞书会认为回调失败并重试重试堆积会导致更多超时。第四发送权限不足。机器人没有send_as_bot权限或者应用版本未发布都会导致“能收到你的消息但发不出回复”。我分享一个自己的经验如果你发现飞书机器人偶尔回、偶尔不回多半是模型超时而不是配置问题。把模型换成更小的量化版本或者调低max_tokens症状会明显缓解。5.4 模型回答慢或总是超时本地部署最影响体验的就是速度。我实测下来同一个 14B 模型在 16G 显存下不量化大概每秒只能生成十几个 token对话还行但稍微长一点的回答就会感觉到明显等待。解决办法有三个方向降模型规模日常聊天用 7B/8B 就够14B 留给复杂任务。用量化版本Ollama 标签里的q4_k_m这类量化格式能显著降低显存占用提升速度。控制上下文长度在 OpenClaw 配置里把max_tokens调低同时在飞书侧设置合适的回调超时时间避免生成长文本时被判定超时。5.5 卸载和重装如果你配置改坏了想重新来过卸载过程也很简单pip uninstall openclaw rm -rf ~/.openclawDocker 部署的话把容器和 volume 删掉即可docker rm -f openclaw docker volume rm openclaw_data网上热词里有“openclaw本地一键部署”部分版本确实提供了一键安装脚本但我建议你至少手动走一遍init流程因为你只有在手动配置的过程中才会真正理解每个配置项是干什么的。我之前就是图省事用一键脚本结果模型配置错了都不知道该改哪里。6. 部署完之后的进阶玩法基础链路通了之后整个系统才算真正属于你了。这一节分享几个我部署完之后的进阶玩法全部亲测有效。6.1 让机器人主动干活定时任务OpenClaw 支持定时任务调度。你可以让机器人每天早上 9 点自动在群里推送“今日待办”也可以让它定时抓取某个网页的更新。配置方式是在config.yaml里增加 tasks 段落指定 cron 表达式和要执行的 prompttasks: - name: daily_report schedule: 0 9 * * * prompt: 根据最近 24 小时的群消息整理一份工作日报包括关键进展和待办事项。 channel: feishu target: oc_群ID这个功能的价值在于机器人从一个“被动问答工具”变成了“主动执行的工作助理”体验完全不一样。6.2 多模型路由贵模型干粗活便宜模型干杂活本地部署最怕的就是“一个模型打天下”。我现在的配置是双模型路由日常闲聊、简单问答走 7B 量化模型速度快、不心疼算力。代码生成、复杂推理、长文档总结走 14B 模型质量优先。在 OpenClaw 里可以配置不同会话类型走不同模型或者通过特定指令触发切换。这有点像一个团队里既有初级工程师又有高级工程师任务分派下去谁合适谁干资源利用率能提高一个层次。6.3 把 Codex CLI 这类编程 Agent 接入飞书群很多人问“codex cli 接入飞书”怎么玩。其实思路很简单Codex CLI 是一个可以在本地执行的编程代理OpenClaw 本身没有编程能力但它可以调用外部工具。你只需要把 Codex CLI 封装成一个可被 OpenClaw 调用的命令工具然后在飞书群里发任务OpenClaw 解析任务后调用 Codex CLI 执行把执行结果贴回群里。我这里给一个最小的封装思路# /usr/local/bin/codex-run codex exec --prompt $1 --output /tmp/codex_result.md cat /tmp/codex_result.md然后在 OpenClaw 的工具配置里注册这个命令设定好调用权限和参数说明即可。这个玩法非常实用等于把“人机协作”的入口搬到了即时通讯工具里。6.4 Termux 移动端部署无 proot 的轻量玩法热搜里有“在安卓termux原生部署openclaw:无proot轻”这个我也试过。Termux 是一个 Android 上的终端模拟器OpenClaw 可以直接在里面跑不需要 proot相对轻量。操作步骤大致是在 Termux 里安装 Python、Git用 pip 安装 OpenClaw然后通过 cloudflared 隧道把服务暴露出去。手机端部署的意义在于你可以把一台旧 Android 手机变成常驻的 AI 助手服务器成本极低而且不占桌面空间。当然性能有限跑大模型还是得靠远端接口但作为“消息转发中枢”完全够用。6.5 安全加固别让你的机器人裸奔最后提醒一点安全建议。因为你的 OpenClaw 服务是暴露在公网上的为了接飞书回调所以你至少要确认以下几点飞书回调路径之外的页面不要对外暴露最好在应用层面加一层鉴权中间件。配置文件里所有密钥不要用明文写死可以通过环境变量注入比如app_secret: ${FEISHU_APP_SECRET}。如果部署在云服务器上防火墙只放行必要端口飞书回调一般只走 443/8080其他端口能关就关。定期关注 OpenClaw 上游版本更新有安全修复就及时升级。我个人在实际操作中最深刻的体会是部署这种自托管项目前 20% 的时间花在“跑通”后 80% 的时间花在“稳定”和“安全”。不要把精力全放在炫酷的功能上先把基础链路打磨稳再慢慢加花样。最后再分享一个实用小技巧接完飞书后先在本地日志里确认回调进来的消息格式再决定要不要开加密策略。如果刚开始调试建议先不开加密等消息链路完全稳定了再开启加密并配好 Encrypt Key这样能少踩一个变量引发的坑。我的机器人到现在已经稳定跑了一个多月每天早上自动推送日报群里随叫随到这个投入产出比我个人非常满意。