做 AI 代理本地部署这件事最大的问题从来不是“模型跑不起来”而是把模型、工具、IM 入口这些零零散散的模块串成一条完整的链路。OpenClaw 是少有的、能把本地大模型调度、工具调用、多渠道消息接入统一到一个进程里的开源代理框架配上 Ollama 这类本地模型引擎再接入飞书机器人就能搭出一套数据不出内网、随时通过飞书对话调用的个人或团队 AI 助理。这个方案特别适合两类人一类是刚开始玩本地大模型、想找个真实落地场景练手的技术爱好者另一类是团队想上可控、可扩展的内部 AI 助手又不想被云 API 和外部平台绑死的开发者。接下来这篇指南会从环境准备、OpenClaw 安装、飞书应用创建一直讲到消息调试和排障记录把完整链路的所有关键节点都过一遍。我会把每步为什么要这么做讲清楚也会把实际部署中容易踩的坑直接摆出来你可以把它当成一份可直接照着操作的部署手册。1. 这个项目到底解决了什么问题1.1 OpenClaw 不只是“聊天机器人”很多人在本地装一个模型之后只能对着终端黑框问问题用完就关了很难形成持续可用的服务。OpenClaw 做的事情是把“AI 能力”从命令行里解放出来变成一个常驻后台、可以随时被调用的代理进程。它在架构上把三件事解耦了大模型负责理解和生成工具层负责执行比如读写文件、跑命令、查数据库、调内部 API消息通道负责连接人——飞书、微信、Slack 这类 IM 都可以作为入口。这样拆开之后你在飞书里发一句“帮我看下今天服务器负载”OpenClaw 收到消息后会自己判断要不要调用工具、调用哪个工具、怎么把结果整理成一段人能看懂的话回给你。它本质上是一个“数字员工”而不是一个聊天机器人。这里有个很容易混淆的点OpenClaw 本身不包含大模型它依赖外部模型服务。最常见的组合是 Ollama 拉本地模型、OpenAI 兼容 API、或者内网部署的其他推理服务。因为模型是本地的数据不需要发到外部服务这也是很多人选择它的核心原因。1.2 本地部署到底图什么选择本地部署无非是几个原因。数据隐私是第一位。企业内部的工单、报表、代码片段这些敏感信息直接发给外部大模型 API 是有合规风险的。本地部署意味着所有消息、上下文、工具调用的结果都留在自己的机器或内网服务器上这一点对很多团队来说是硬性要求。其次是成本可控。外部 API 按 token 计费团队用多了账单会非常难看。本地部署是典型的“一次算力投入持续使用”用 Ollama 跑一个 7B 或 14B 的量化模型日常问答和工具调用场景完全够用电费相比 API 费用几乎可以忽略。还有一点是自由度。本地部署不受外部服务限流、版本升级、接口变更的影响。你想换模型就换模型想改提示词就改提示词想加工具就加工具。这种“完全掌控”的感觉用过云端方案的应该都懂。1.3 为什么消息入口首选飞书消息入口这件事可选方案挺多但我综合测下来飞书是最省心的一条路。飞书开放平台的机器人机制很成熟应用凭证、事件订阅、长连接模式、权限管理都很清晰。尤其是长连接模式不需要公网回调地址这对本地部署来说太关键了。你想本地机器没有公网 IP如果用 Webhook 回调还得做内网穿透麻烦不说还有安全风险。飞书的长连接模式是主动往飞书服务器建立 WebSocket 连接OpenClaw 作为客户端接收事件这样本地服务不需要暴露任何端口。另外飞书对机器人的权限划分得很细可以做到只授予必要权限不给你不相关的能力。这一点在企业场景里很重要安全审计也容易做。如果你团队已经在用飞书办公那这个方案几乎是天然契合的。成员不用装新工具直接在飞书里和机器人对话学习成本为零。2. 部署前的准备软硬件评估清单2.1 硬件建议与模型选型思路OpenClaw 本身只是一个代理框架内存和 CPU 占用都不高真正的资源大头在本地模型上。所以硬件规划的核心其实是给模型选一个合适的规格。从我的实际经验来说日常跑 Ollama 模型可以按下面的参考来配模型规模量化精度显存需求内存需求适合场景7B~8B 模型Q4_K_M6GB 左右16GB日常问答、简单工具调用13B~14B 模型Q4_K_M10GB 左右32GB复杂推理、代码生成32B 模型Q4_K_M20GB 以上64GB高质量助手、复杂多步骤任务这里要重点说一下量化。量化简单理解就是给模型“瘦身”把参数的精度降低从而减少显存占用。Q4_K_M 是 Ollama 里很推荐的一个量化档位它在体积和效果之间取得了比较好的平衡。同一个模型FP16 原始版可能占 14GBQ4 量化后只要 5GB 左右效果损失在可接受范围内。如果你的显卡只有 8GB 显存跑 7B 量化模型是最稳妥的选择。没有 NVIDIA 显卡的同学也不用灰心纯 CPU 跑 7B 量化模型是可以的只是速度比较慢。我在一台老笔记本上试过CPU 跑 Qwen2.5 7B生成速度大概每秒 5~10 个 token慢是慢了点但做异步问答、定时任务这种场景其实够用。关键是把预期放对位置。内存方面我建议至少 16GB。因为除了模型推理操作系统、OpenClaw 进程、日志这些都要占内存。如果你打算跑 14B 模型32GB 内存会更从容。2.2 安装基础依赖不同系统的基础依赖略有差别但核心就三样Git、Node.js、以及可选的 Docker。Git 用来拉取 OpenClaw 的源码仓库和后续更新这个没什么好说的确认一下git --version有输出就行。Node.js 是 OpenClaw 运行时的核心依赖建议安装 18 或 20 以上的 LTS 版本。我见过不少因为 Node 版本太老导致启动报错的情况所以建议直接用 nvm 装最新 LTS省得后面折腾。装完跑一下node -v确认输出。Windows 用户这里要特别注意OpenClaw 的官方脚本对 WSL2 环境有强校验。如果你用的是旧版 WSL1或者没有手动配置过内核安装时会报类似 “could not safely verify the WSL2 environment” 的错误。这个我在后面的常见问题章节会详细讲但前置建议是Windows 上用 WSL2 跑 Ubuntu然后在 Ubuntu 里装 OpenClaw这是最省心的路径。Docker 是可选项。如果你想彻底隔离环境或者后续要搭配 Vector 数据库、消息队列这类中间件Docker 会方便很多。OpenClaw 官方也提供了容器化的部署方式但我个人建议第一次跑通链路先不用 Docker直接宿主机安装排查问题更直观。2.3 先跑通本地大模型在碰 OpenClaw 之前先把模型服务跑通。这步做好后面所有排障都会轻松很多因为你可以快速区分问题是出在模型层还是出在代理框架层。推荐用 Ollama它是最省事的本地模型管理工具。安装很简单官方脚本一行命令装完默认监听 11434 端口提供 OpenAI 兼容的 API 格式。也就是说OpenClaw 可以通过一个标准接口连到 Ollama以后就算你把模型换成 vLLM、llama.cpp 之类的推理服务只要 API 格式兼容OpenClaw 侧几乎不用改。拉模型也简单直接用命令ollama pull qwen2.5:7b拉完之后验证一下模型能不能正常对话ollama run qwen2.5:7b 你好用一句话介绍你自己能看到正常的中文回复说明模型服务就绪。这里我强烈建议选一个中英文能力都靠谱的基座模型。Qwen2.5 系列是我实测下来比较稳的选择中文理解好、工具调用能力也达标。想更轻量的话可以选 qwen2.5:3b但复杂指令的理解能力会明显下降飞书机器人这种场景里容易出现“答非所问”。我最终的长期方案是 7B 作为主力3B 只用来做链路连通性测试。3. OpenClaw 本地部署实操3.1 获取安装包与目录结构OpenClaw 的安装方式我建议按照官方仓库的 README 来整体流程就是拉代码、装依赖、初始化配置文件。假设你用的是 Ubuntu 环境可以这样操作git clone https://github.com/你的仓库地址/openclaw.git cd openclaw npm install安装依赖的过程中如果网络条件一般npm 有时候会卡住。我的经验是把 npm registry 换成国内镜像不用全局换项目目录下配一个.npmrc就行registryhttps://registry.npmmirror.com装完依赖之后你会看到一个config目录里面是各类配置文件的模板。这是 OpenClaw 设计得比较舒服的地方模型连接、消息通道、工具权限都是分开配置的互不干扰。目录结构大致是config/ config.yaml # 总配置模型、通道、工具的入口 channels/ # 消息通道配置飞书、微信等 tools/ # 工具调用能力开关 agents/ # 智能体行为参数第一次看到这么多配置文件不用慌核心就一个config.yaml其他都是按需修改。保持默认配置我们先把它跑起来。3.2 配置文件把模型和通道串起来这是整个部署里最关键的一步。OpenClaw 的好用程度很大程度取决于你配置文件写得是否清晰。打开config.yaml核心要确认两块一块是模型连接另一块是通道启用。模型连接的配置思路是告诉 OpenClaw “你去哪里调用大模型”。因为 Ollama 提供了 OpenAI 兼容接口所以可以这样写model: provider: openai-compatible base_url: http://127.0.0.1:11434/v1 model_name: qwen2.5:7b api_key: ollama temperature: 0.7 max_tokens: 2048这里有个细节base_url 一定要带上/v1后缀很多 OpenAI 兼容服务实际的 API 地址是在这个路径下的。api_key 字段在 Ollama 下不需要真实校验填任意字符串占位即可但字段本身不能省略。通道配置在channels/feishu.yaml里核心就是填飞书应用的凭证信息。你先不急着填真实值把结构看懂就行。常见配置项大概是这样的channel: feishu enabled: true mode: websocket app_id: cli_xxxxxxxxxxxx app_secret: xxxxxxxxxxxxxxxxxxxxxxxx做消息通道接入时我一般会先把模型配好、用命令行确认能对话再配飞书。优先级顺序永远是“先确认内核跑通再连接入口”不然你排错的时候根本不知道问题出在哪一段。3.3 首次启动与命令行验证配置填好之后先不急着连飞书用命令行模式验证 OpenClaw 本身是否正常工作。启动命令我习惯放在后台跑这样即使终端关了进程也不断npm start如果是在后台运行日志会写到项目里的logs/目录我建议时刻开着日志观察。首次启动顺利的话日志里会看到模型连接成功、工具加载完成、通道注册成功这几类信息。然后打开另一个终端用 CLI 模式直接向 OpenClaw 发一条消息node openclaw cli 早上好现在几点了如果它能调用系统时间工具并合理回复你说明模型层、工具层、代理调度层这一整条链已经通了。这个时候再接入飞书就只剩下“事件通道”这一件事需要处理排查范围会小很多。4. 飞书接入从零创建一个企业机器人4.1 在飞书开放平台创建应用飞书的机器人接入要先在开放平台建一个应用这不是代码工作但很多人卡在这一步因为界面选项比较多。打开飞书开放平台登录后进入“开发者后台”选择“企业自建应用”点击创建。应用名称可以叫“智能助理”之类的内部识别名描述随便填。创建完成后你会进入应用详情页第一件事是拿到两个凭证App ID 和 App Secret。这两个凭证相当于机器人的账号密码会出现在应用详情的“凭证与基础信息”页里。App ID 形如cli_开头的一串字符App Secret 是一段更长的密钥。把这两个值复制好后面要填进 OpenClaw 的飞书配置里。然后在“应用能力”这里打开“机器人”开关。这一步很容易被漏掉不加机器人能力后面所有消息收发都是空的。4.2 配置权限与事件订阅机器人要收发消息必须配好权限和事件订阅。权限的作用是“允许机器人做什么”事件订阅的作用是“告诉飞书服务器哪些事情发生了要通知机器人”。我梳理了一份最小权限清单照着勾选就行权限代码作用im:message:read读取单聊消息im:message:send_as_bot以机器人身份发送消息im:message:receive接收消息事件contact:user.base:readonly读取用户基础信息用于显示用户名权限很多不用全选给少不给多是安全原则。我见过有人图省事直接勾了一堆权限后面安全审计很麻烦也没什么必要。事件订阅这里有两条路。一条是长连接模式WebSocketOpenClaw 主动连飞书服务器收事件另一条是 Webhook 回调需要你的服务有一个公网可访问的 HTTPS 地址。本地部署的场景下我强烈建议用长连接。原因前面说过本地机器没有公网 IPWebhook 回调需要额外做内网穿透不仅多一层风险还容易不稳定。选择长连接模式时飞书平台会给你一个加密的 verification token这个也要一并保存。OpenClaw 侧在长连接模式下会自动处理事件的解密和回执不需要自己写回调服务。事件订阅这里要订阅的消息事件最常见的是im.message.receive_v1也就是“收到新消息”。订阅完成后把事件状态设为“已启用”否则机器人不会收到任何消息推送。4.3 把飞书参数填进 OpenClaw现在可以回到 OpenClaw 的飞书通道配置文件把之前拿到的三个关键参数填进去App ID、App Secret、verification token。channel: feishu enabled: true mode: websocket app_id: cli_xxxxxxxxxxxx app_secret: xxxxxxxxxxxxxxxxxxxxxxxx verification_token: xxxxxxxxxxxxxxxxxxxxxxxx reply_prefix: 保存配置后重启 OpenClaw 让它重新加载配置。这里多说一句很多配置变更不会热更新改完配置文件一定要重启进程这是新手最常踩的坑。日志里如果出现类似“feishu channel connected”或者“websocket established”的信息说明通道已经建立成功。有个小细节version token 和 app_secret 很容易搞混。app_secret 在“凭证与基础信息”页verification token 在“事件与回调”配置区域不是一个东西。填反了连接时通常不会立刻报错但消息事件收不到排查起来会绕弯路。4.4 端到端测试配置完成、通道连接成功后就可以做真正有价值的上线验证了。打开飞书找到你创建的应用对应的机器人在单聊窗口发一条消息比如“在吗介绍一下你的能力”。正常情况下几秒钟内机器人就会通过飞书回一条消息。如果回复正常恭喜你整条链路已经打通。接下来可以多试几种类型的指令让它算一道数学题、读取一个本地文件的内容、执行一条终端命令。通过这些测试你不仅能确认消息通道稳定还能验证工具调用能力有没有被正确配置。如果消息发出去没有回复不要慌按后面章节的排查顺序一步步来。5. 常见问题速查部署与接入排障实录5.1 WSL2 环境验证失败这类环境问题怎么破很多 Windows 用户在安装阶段就会卡住报错信息里最常见的就是could not safely verify the WSL2 environment。这个报错的意思是安装脚本检测到当前不是安全的 WSL2 环境直接中止了安装。从几个方向的排查记录来看这个问题基本是下面三种原因导致的可能原因解决方案WSL 版本还是 1.x执行wsl --set-version 发行版名 2升级到 WSL2未安装 WSL2 内核更新包到官方下载并安装适用于 x64 的 WSL2 Linux 内核更新包然后重启在 WSL2 中执行了 Windows 路径的脚本所有操作都在 WSL2 的 Linux 文件系统下进行路径类似/home/user/projects/openclaw大多数情况下升级内核、把仓库放到 Linux 文件系统下重试就能解决问题。如果你实在不想折腾 WSL2也可以用 Docker Desktop 跑容器版 OpenClaw前提是 Docker Desktop 要开启 WSL2 后端这本质上还是绕不开 WSL2。5.2 消息发出去但机器人不回的排查顺序飞书消息发出去没有回复是最常见也最让人无奈的故障。我的建议是按下面顺序排查每一步都有明确目的不会白费功夫。一是确认通道是否是真的连上了。打开 OpenClaw 日志搜一下 feishu channel看有没有报错或断连记录。很多时候根本问题是通道没建立成功只是启动日志被刷过去了你没注意。二是确认事件订阅是否生效。飞书开放平台的事件订阅配置保存后要确认状态是“已启用”而且事件列表里有im.message.receive_v1。这一步出了问题飞书服务器压根不会把消息推给机器人。三是确认权限是否覆盖。权限配置在飞书开放平台修改后需要等待几分钟生效。有些权限还要重新发布应用版本才真正生效而开发环境下的应用需要在“版本管理与发布”里创建一个可用版本。四是确认配置参数是否填反或漏填。重点检查 app_secret 和 verification token 是否对应双端配置是否一致。最长见的情况是换了应用但旧配置没更新或者复制时不小心带了空格。最后一条经验给 OpenClaw 打开详细日志输出让它把接收到的每一条飞书事件都记录下来。这个开关在配置里通常是debug: true之类的字段。有了明细日志几乎所有的“没回复”问题都能在几分钟内定位到是事件没到、模型报错、还是回复消息发送失败。5.3 性能与资源占用优化本地部署最现实的问题就是资源不够。跑过一阵之后你会明显感觉到模型推理速度直接影响用户体验。首当其冲的是显存。如果你跑的是 7B Q4 模型但机器还有别的程序占显存推理时大概率会爆显存。解决办法要么关掉不必要的程序要么换更小的模型。另外可以把 Ollama 的OLLAMA_MAX_LOADED_MODELS环境变量设为 1确保同一时间只加载一个模型省下重复加载浪费的显存。还有上下文长度的问题。默认配置下模型一次能带的历史消息数量有限如果对话一长就容易触发超出上下文窗口的报错。我通常把max_tokens设成 2048对话轮次设计上避免让代理记住太多历史。长任务靠工具调用而不是上下文死记这是代理设计的基本原则。如果你的模型在 CPU 上跑建议在 Ollama 配置里开启内存映射同时把系统 swap 空间调大一些。实际测试中纯 CPU 环境下10B 模型的生成速度虽然不快但只要不超时消息最终还是能稳定回出来的。真要追求体验还是加一块支持 CUDA 的显卡切换到 GPU 推理速度完全不是一个量级。5.4 其他高频报错对照表我把实际操作中遇到的高频报错整理成了一张表方便你快速对照报错现象可能原因解决建议启动时提示模型连接超时Ollama 服务没启动或 base_url 端口不对确认curl 127.0.0.1:11434有响应飞书通道连接后马上断开App ID / App Secret 凭据错误重新复制凭证检查末尾空格发送“在吗”得到空回复模型被卡在长上下文或工具调用超时重启 OpenClaw缩短上下 TTS设置更短的请求超时持久化会话不生效存储目录路径权限不正确给配置目录写入权限或调整存储路径日志刷大量 429 限流单次请求频率过高触发了飞书接口限流在通道配置里增加发送间隔限制每秒消息数这些报错大多不是代码 bug而是环境配置和数据格式问题。我的心得是碰到报错先别慌打开日志从下往上读找到第一个 Error 的时间点十次里有七次问题就暴露在日志里了。6. 从“能跑”到“好用”我的几点实操体会先把链路跑通再谈优化这是我一直坚持的做事方式。OpenClaw 加飞书这套组合最大的价值在于它让本地模型从“玩具”变成了“工具”。我用它在内部做过不少事定时抓取数据生成报表、帮同事查技术文档、维护一个简单的工单登记流程全部通过飞书完成。同事不需要知道模型在哪部署、底层用的是什么框架他们只需要把机器人当成一个靠谱的同事。最后再分享一个从实践中得来的小技巧刚开始用的时候不要一上来就配一堆工具权限先把基础问答跑稳再逐步开放文件读取、命令执行这些能力。每开放一个工具就专门测试一轮。这样即使出了问题你也能很清楚地知道是哪一步引入的。我在最初搭建时就吃过亏一次性全开结果某个工具配置有误导致机器人频繁报错排查花了大半夜。如果重来一次我会严格按照“问答 → 单工具 → 多工具 → 消息通道”这个顺序来搭。这套系统后续还可以往很多方向扩展比如对接团队内部的知识库、接入数据库查询、增加定时触发任务、甚至做成多 Agent 协作的形态。对我来说本地 AI 最迷人的地方就在于它就是你手中的一块乐高积木你想拼什么完全由你决定。