上周技术群里有人贴了一张截图自家配置的智能体在飞书群里自动把几十条未读消息分门别类归纳成待办清单还顺手拉了一个项目排期表。评论区一半人问这是什么工具另一半人直接开催教程。答案就是今天要聊的 OpenClaw很多地方也叫 Clawdbot或者干脆叫“Claw”。OpenClaw 本质上是一个开源的智能体运行框架你可以把它理解成一个“能自己思考、自己调用工具、自己对接聊天软件”的数字助理。它和那些只能聊天的对话机器人最大的区别在于它可以同时挂载多个聊天渠道统称 Channel比如飞书、Microsoft Teams、控制台等也能接入不同的底层大模型从云端 API 到本地开源模型都行。你现在网上刷到的“自动写周报”“自动处理消息”“定时巡检任务”大部分都是基于这类框架搭出来的。我花了差不多两周时间从零开始摸完了安装、配渠道、接模型、踩坑修复的完整链路。这篇教程按我的实际经验来写尽量做到“喂饭级”——你跟着一步步操作就行。不管你是 Windows 用户、Linux 服务器玩家、手上只有一台 Docker 机器还是用飞牛fnOS这类 NAS 当主力环境我都尽量覆盖到。1. 开始前想清楚的 3 件事硬件、模型 Key 与落地预期1.1 硬件要求其实没那么高很多人一听说“智能体框架”就以为要准备高性能显卡或者是大内存服务器其实 OpenClaw 的定位是“中间协调层”它本身不做推理真正干活的是背后的大模型 API。所以它对硬件的要求主要集中在能不能稳定联网、能不能长时间运行、磁盘能不能扛住日志这几件事上。我自己最开始用一台 4 核 8G 的老笔记本跑系统里还挂着微信、浏览器和一堆开发工具OpenClaw 照样没卡过。它的内存占用大头其实是各类 Channel 的长连接缓存和会话状态正常小规模使用下不会超过 300M。不过有两样东西建议还是别省固态硬盘目录里有大量 session 状态文件和日志机械盘在频繁小文件读写时会拖慢响应。稳定性这东西一旦跑起来就建议别频繁关机。实在不行就用进程守护工具或者 Docker 的 restart 策略兜底。如果你的使用场景是“挂机自动处理消息”那把它部署在云服务器或 NAS 上比放在自己笔记本里靠谱得多。笔记本一锁屏、一休眠你的智能体就“断气了”别人发消息它只能假装没看见。1.2 API Key 准备哪些必须哪些可以后补新手最容易懵的就是“到底要准备多少个 Key”。根据我自己部署的经验分开三类说必配的一组大模型推理 API。这是整个智能体的“大脑”。你可以选择 OpenAI 兼容接口的各类服务商也可以选择阿里的通义千问DashScope或者用 Ollama 之类方案拉本地开源模型。这一组的 Key 是无论如何都要先搞定。按需配置的一组Channel 平台的机器人凭证。比如你要接入飞书就去飞书开放平台建一个自建应用拿到 App ID 和 App Secret要接入 Microsoft Teams就得在 Teams 那边注册机器人并配置回调地址。如果只是先玩一下不接任何聊天软件那这组可以先不配后面随时补。可后补的一组工具类服务的 API。比如联网搜索、代码执行、图片生成等。大多数工具在 OpenClaw 里都是以插件形式存在你完全可以等核心流程跑通再慢慢加。这里有个经验不要一开始就把所有 Key 全填进去。每多一个服务就多一个出问题的环节。我第一轮部署时就因为提前配了一个用不上的服务导致启动时疯狂报错最后只能一个个排查白白浪费了半个小时。1.3 对“3 分钟集成”的合理预期标题里写了“3 分钟”这句话我不打算收回但它有一个前提只针对最简路径。也就是“下载安装 控制台对话 接一个模型”这三步。如果涉及飞书回调、Teams 应用审核、内网穿透那 3 分钟肯定不够可能需要 20 到 60 分钟不等。我的建议是分两步走第一轮先用默认配置跑通“本地控制台 云模型”感受一下它到底怎么工作然后再添加具体渠道。这样出问题时你能清楚知道是 OpenClaw 本身的问题还是渠道接入的问题。2. 3 分钟安装Windows、Linux、Docker 与飞牛四个场景实测我实际在 Windows、Linux 虚拟机和一台飞牛 NAS 上都跑过安装路径不完全一样。下面按场景分别说。2.1 Windows一行命令解决Windows 的安装核心思路就是“下载启动器 初始化配置”。我推荐的方式是打开 PowerShell以管理员身份执行官方脚本iwr -useb https://openclaw.io/dist/install.ps1 | iex脚本会自动完成依赖检测、目录创建、默认配置生成。装完之后启动器会提示你选择“快速命令模式”还是“交互式引导模式”。新手直接选交互式引导它会像向导一样问你模型提供商和 Key 填哪个位置。装完后的关键路径在%USERPROFILE%\.openclaw\下配置文件和 session 数据都在这里。Windows 下常用命令openclaw start # 前台启动 openclaw doctor # 环境自检强烈推荐跑一下这里我踩过一个坑Windows Defencer 的安全中心偶尔会拦截脚本生成的可执行文件。如果你的环境提示“操作已被阻止”按路径手动添加白名单后再安装即可不是什么大问题。2.2 Linux脚本安装与手动安装Linux 是 OpenClaw 的主场安装方式也更灵活。最省事的是脚本方式curl -fsSL https://openclaw.io/dist/install.sh | bash脚本执行完可以用openclaw --version看是否安装成功。如果你想把数据目录放到独立位置比如放到自己的数据盘可以设置环境变量export OPENCLAW_HOME/data/openclaw openclaw start我自己的服务器装的是精简版 Debian脚本安装时唯一缺的是curl和ca-certificates其他依赖都会自动搞定。如果你的发行版是 CentOS 或 UOS 这类缺依赖时直接apt install curl ca-certificates -y或者yum install curl ca-certificates -y补上就可以了。2.3 Docker最稳的部署方式如果你不想让运行环境弄乱宿主机Docker 是目前最干净的方式。我自己跑生产环境也用的是 Docker升级、回滚都很方便。docker run -d \ --name openclaw \ --restart unless-stopped \ -p 127.0.0.1:3883:3883 \ -v openclaw-data:/root/.openclaw \ openclaw/clawd:latest端口 3883 是 OpenClaw 的本地控制台端口。这里我特意把端口绑定在127.0.0.1意思是只允许本机访问防止外部网络直接扫到你未鉴权的管理面板。如果你要用它对接飞书或 Teams需要回调的时候再另行调整。容器启动后查看日志用docker logs -f openclaw2.4 飞牛 NAS图形化界面照样能跑现在已经有不少人是拿飞牛私有云fnOS当家庭服务器的。飞牛自带 Docker 应用中心你不需要敲命令也能安装。操作步骤大致如下在飞牛的“应用中心”里找到 Docker打开 Docker 管理界面。镜像仓库中搜索openclaw/clawd拉取最新版本。创建容器时按刚才 Docker 命令的参数填写端口映射和存储卷。数据目录建议映射到一个独立存储空间比如某磁盘/下载/OpenClaw。启动后打开飞牛的终端或者直接用 Docker 详情页的日志功能查看初始化输出。飞牛上唯一要注意的是网络模式和端口冲突。如果你的 NAS 上已经跑着其他服务占用了 3883 端口把映射端口改成一个冷门端口例如 13883然后自己记住这个端口就行。2.5 装完先别急跑一下自检无论哪个平台安装完都建议执行一次openclaw doctor。它会检查环境依赖、配置格式、网络连通性、Key 是否有效。新手看到一堆“OK”的绿色输出心里就有底了。如果有标红的项目顺着提示修就行大部分都是 Key 填错或者端口被占用。3. Channel 通道Console、Teams 与飞书各自的接入差异OpenClaw 里把“和智能体对话的入口”统一抽象为Channel。我建议新手先理解清楚这个概念——它就是解决“智能体在哪里跟你说话”的问题。不同 Channel 的接入方式差异很大但配好之后多个渠道会共享同一个智能体记忆和会话上下文。3.1 Console最低成本的体验通道Console 就是终端里的对话窗口。装完 OpenClaw 后什么都不用额外配置直接跑到终端输入openclaw chat就能开始聊天。这个模式最适合测试模型配置是否正确比如你刚接上千问让它自我介绍一下看看回复质量如何。Console 模式有几点体验不如聊天软件没有富文本排版、图片只能给链接、消息历史滚动不方便。所以它只是调试用的真实长期使用还是建议挂到飞书或 Teams。3.2 接入 Microsoft Teams一套标准的 Bot 流程Teams 的接入流程相对重一点但 OpenClaw 有现成的 Teams Channel 适配模块不需要从零写代码。大致三步在 Azure 门户或 Teams 管理后台注册一个机器人 Bot拿到 Bot ID 和 Bot Password。在 OpenClaw 配置文件的channel.teams段填上这些凭证以及回调地址。由于 Teams 需要公网 HTTPS 回调你还要把本地 3883 端口对公网开放或者用内网穿透工具把回调地址暴露出去。这一步是 Teams 和飞书接入时最容易被卡住的地方。我在调试 Teams 时遇到的问题是回调地址没配对Teams 后台一直提示“验证失败”。后来把回调 URI 改成https://你的域名/api/channel/teams/callback在配置文件的public_base_url里也填上对应域名问题就解决了。3.3 接入飞书自建应用的两分钟路径飞书接入算是我体验下来最顺畅的。你只需要在飞书开放平台建一个“企业自建应用”把 App ID 和 App Secret 填进配置[channel.feishu] app_id cli_xxxxxxxxxxxx app_secret vE8yxxxxxxxxxxxxxxxxxx encrypt_key 填完重启 OpenClaw它会自动注册事件订阅地址。如果飞书后台要求填写“事件接收 URL”就用/api/channel/feishu/callback这个路径配合你已经暴露的公网地址。有一个细节是新手的重灾区飞书的“长文本输出容易被截断”。这不是 OpenClaw 独有的问题而是飞书消息卡片本身有长度限制。解决办法有两种在智能体指令里加上“回答尽量分点、精简控制在 1500 字以内”在配置里开启长文本分片发送超出部分自动拆成多条消息。我实际测试下来两条路叠加最稳。只靠分片不控制上下文用户体验会很差——消息一串十几条根本没人想看。3.4 Channel 数量的心理预期同一个人可能会同时接 4、5 个渠道。我不建议这么做。原因是每个渠道都会占用一份长连接和事件处理资源如果你用的云模型 API 是按时长计费多渠道还容易把预算打爆。先固定一个主力渠道跑顺了再加其他渠道这才是最务实的路线。4. 模型配置以千问Qwen为例的 API 接入全解OpenClaw 本身不内置大模型它通过标准接口调用外部模型。你可以选择市面上大多数兼容 OpenAI 接口的模型服务也可以选择本地模型。4.1 先理解 OpenAI 兼容接口现在国内的模型服务商很多都提供 OpenAI 兼容接口。这意味着只需要两个信息就能接Base URL和API Key。OpenClaw 实际上是把自己当成一个 OpenAI 客户端的角色。你在配置文件里把 Base URL 指向某个模型的网关地址把 API Key 填上它就能完成“把智能体指令变成自然语言请求、再把模型回复解析回频道”的整个链路。4.2 千问Qwen接入的配置示例以阿里云百炼平台的通义千问为例它的 OpenAI 兼容地址是Base URL: https://dashscope.aliyuncs.com/compatible-mode/v1 模型名: qwen-plus 或 qwen-max在 OpenClaw 配置里这样填[llm] provider openai-compatible base_url https://dashscope.aliyuncs.com/compatible-mode/v1 api_key sk-xxxxxxxxxxxxxxxx model qwen-plus填完后重启Console 里随便发一句“你是哪位”能模型正常自我介绍就算通了。我测试下来《qwen-plus》在中文内容处理和工具调用上表现比较均衡对于普通办公自动化任务完全够用看重推理能力时再用qwen-max费用也会高一些。4.3 本地模型怎么接如果你对数据隐私要求高或者想离网运行可以部署 Ollama 这类本地推理服务。OpenClaw 同样支持[llm] provider ollama base_url http://127.0.0.1:11434 model qwen2.5:14b注意本地模型对机器配置的要求立刻上来了。14B 参数规模的量化模型至少要 16G 内存追求流畅体验的话需要独立显卡或者统一内存比较大的设备。我的个人观点是除非你有明确隐私诉求否则前期先用云 API 调试流程后面再平滑切到本地模型也不迟。4.4 模型 Key 的位置很多教程会教你把 Key 直接写在配置文件里。这在本地自用环境没问题但如果机器有被别人登录的风险建议用环境变量方式export OPENCLAW_LLM_API_KEYsk-xxxx配置里写api_key ${OPENCLAW_LLM_API_KEY}就行。这样 Key 不落在明文文件里配置被截图发群里也不会泄漏。5. 报错复盘“session file locked (timeout 60000ms)”的定位与修复这个报错几乎每个 OpenClaw 用户都会碰到也是搜索热词里的高频问题。我遇到时回复给我的完整信息是agent failed before reply: session file locked (timeout 60000ms)下面把定位思路完整讲一遍而不是直接给你一个“万能命令”。5.1 这个错误到底在说什么OpenClaw 在处理对话时会为每个会话生成一个状态文件。为了保证同一个会话的消息不会交错写入它给文件加了一把锁。正常情况下一条消息处理完就解锁下一个请求继续。“timeout 60000ms”的意思是某个会话文件等了 60 秒还拿不到锁系统直接判定处理失败。最常见的原因有三个上一次对话的进程没有正常结束比如你强制关掉了终端或容器session 锁文件残留在磁盘上并发对话数超了负载多个渠道同时向同一个 session 发消息互相等锁某个工具调用卡死了比如智能体在调用外部 API 时一直没返回session 被占住不放。5.2 我的完整排查链路我第一次遇到时第一反应是重启。重启后好了几分钟再发消息又复现。这就基本排除了“一次性残留锁”的可能。接着我看日志发现报错集中在某个特定 session 上其他 session 正常。于是我去数据目录找到对应文件ls ~/.openclaw/sessions/果然看到两个进程状态文件的时间戳很旧明显是之前测试时留下的僵尸锁。清理办法是把对应会话的锁文件移除# 先确认没有进程正在使用该会话 openclaw stop rm ~/.openclaw/sessions/*.lock openclaw start这样处理后问题还剩一半为什么同一个 session 会被持续占住我检查配置后发现多个 Channel 用了同一个默认 session 名而我的飞书和 Teams 同时在收消息相当于两拨人在抢同一把锁。把 session 按渠道拆分后再没出现过这个报错。5.3 防复发的配置建议我目前在生产环境用的配置是每个渠道独立 session[channel.feishu] session_prefix feishu [channel.teams] session_prefix teams [console] session_prefix local这样不同来源的对话不会互相抢锁。同时我还做了一个兜底计划在进程守护工具里配置了“检测到长时间无响应就自动重启”相当于给 OpenClaw 加了安全网。如果你用了 Docker还可以在容器启动参数里加--stop-timeout 20强制停止容器时给它的清理流程留时间减少锁文件残留的概率。6. 和 WorkBuddy 对比谁适合你很多人问“OpenClaw 和 WorkBuddy 哪个好”这个问题没法一句话回答因为它俩定位就不完全一样。WorkBuddy 更像预包装的“个人助理模板”下载下来就能用功能边界相对固定OpenClaw 是“半成品框架”可配置性、可扩展性都强但需要你自己调。我从几个角度做了对比对比维度OpenClawWorkBuddy开源性开源社区版免费封闭生态收费档位分明渠道接入支持飞书、Teams、Console等配置灵活渠道相对固定模型接入云 API、本地模型、多模型切换都方便默认绑定自家/主推模型适合人群愿意折腾、有定制需求的技术型用户想开箱即用、较少自定义的人运行时开销轻量可跑在 NAS 或小服务器上一般需要更完整的运行环境进程排障开源日志清晰问题可定位黑盒程度高问题难归因我的结论是想深度集成到自己的飞书或 Teams 工作流中且有基础查日志能力的人选 OpenClaw 更合适。完全不想碰配置只想“双击打开就能用”的朋友可以先用 WorkBuddy 试试跑了兴趣再回来折腾 OpenClaw 也不迟。7. 稳定运行半个月后我想提前告诉你的几只“坑”7.1 会话记忆的边界很多人觉得 OpenClaw 是“无限记忆”的其实不是。它对会话上下文的保留长度受底层模型的上下文窗口限制。如果你的对话特别长早期信息会被截断遗忘。我现在的做法是在关键任务里让它“每一步把完成的结论写进一张固定便签”这样哪怕上下文丢了还能从便签里捞回关键信息。7.2 别把敏感内容全交给智能体接入飞书和 Teams 后智能体就拥有了读消息的权限。这里强烈建议在机器人权限里只勾选它完成任务需要的最小范围不要顺手全部开成“可读所有消息”。我见过有人图省事把权限拉满结果某个调试失误导致智能体把逻辑混乱的内容发到了大群里场面一度十分尴尬。7.3 升级别手快先看 changelogOpenClaw 迭代速度很快但动不动就升级到最新版并不一定是好事。我中途有一次升级后旧配置里的某个字段被弃用了启动直接失败。后来习惯了先看版本更新说明再决定要不要升级。备份配置文件和 session 目录是升级前最基本的操作没有之一。7.4 我目前觉得最稳的“起手式”如果你完全没思路可以先照我现在的稳定组合跑一遍一台廉价的 Linux 服务器或飞牛 NASDocker 跑 OpenClaw接入飞书模型先用千问 qwen-plus。这套组合成本低中文生态支持好排查资料也容易搜到。等跑通了再往里面加工具、加渠道、换模型一切都来得及。