你有没有过这种经历团队用Teams、公司用飞书、自己习惯微信想让同一个AI助手同时出现在这些地方还得各自对接API光适配就能写两周。我在2026年第一次接触OpenClaw社区里还叫Clawdbot时本来也只打算装个Demo看看结果从下载到把bot拉进飞书群掐表9分出头就跑通了。如果你手里有台能跑Docker的机器或者只是想在Windows上快速体验这篇教程应该能帮你节省不少时间。文章会按照我实际操作的顺序来写包括安装、渠道接入、模型配置、常见报错以及几个只有用一段时间才能感受到的细节。1. 先搞明白OpenClaw到底替你做了什么1.1 它是消息网关、Agent运行时还是两者都是OpenClaw是一个自托管的AI Agent网关它把“模型能力”和“聊天渠道”解耦。你可以把它理解成一个中间层左边接不同的大模型云端API或本地GGUF右边接Teams、飞书、钉钉、Slack等渠道中间是支持工具调用、记忆、多轮会话的agent运行时。Clawdbot是社区早期对这套东西的叫法现在仓库统一叫OpenClaw但配置文件里有时还能看到clawdbot字样本质是一回事。第一次看到这个项目时我的第一反应是“又一个Bot框架”。但细看文档才发现它的核心不是帮你写机器人逻辑而是把“渠道接入”这件事抽象成了标准配置。你在OpenClaw里定义一个agent它不关心消息来自飞书还是Teams因为渠道只会把用户输入转发给agentagent再把结果返回给渠道。这个抽象让我省掉了大量重复的Webhook回调处理和消息格式转换工作。1.2 为什么不是直接用各平台的官方Bot API如果只是给一个平台做一个机器人官方API就够。但现实往往是你有多个渠道、多种模型、多套配置希望同一套prompt、同一份会话历史在任意入口都能继续。OpenClaw做的就是把会话状态、模型路由、权限控制统一到一个进程里之后无论从飞书还是Teams提问接的都是同一个agent。它不像WorkBuddy那种偏向复杂任务编排的重型框架更像一个轻量、务实的消息入口聚合器。这一点在选型时可以按需判断。我自己在选型时对比过几类方案直接用官方SDK要维护多个进程用云厂商的Bot服务又没法接本地模型WorkBuddy那类工具更偏自动化和工作流而OpenClaw的角色更像“统一的对话入口”。如果你只是想要一个随时能聊、能呼出命令、能接入自己知识的助手它确实比从零搭省太多事。1.3 我在什么场景下决定用它我这里有个实际案例一台跑ESXi的家里服务器上面有几个虚拟机其中一个是无界面Linux我希望通过飞书远程查状态、跑一些命令同时公司Teams里讨论技术方案时也想让同一套知识库来回答。如果分开做两个机器人维护成本直接翻倍。OpenClaw在十分钟内把一个agent同时绑到了两个channel上后面的成本就是改配置而已。这个场景应该能代表大部分想折腾的人不是要做多复杂的AI应用而是想让现有的聊天工具变成AI的入口。如果你也有类似的需求下面的安装流程可以直接照抄。2. 9分钟倒计时开始环境准备与两种安装姿势2.1 顺手的环境检查清单安装之前先过一遍一台x86_64或ARM64机器树莓派也行内存至少2G跑轻量模型4G以上跑7B量化模型操作系统不限但Docker方式最省心命令行能联网。如果你在Windows上玩推荐直接下载WindowsHub安装包它本质上是个桌面壳内置OpenClaw服务并提供一个本地管理界面装完后在开始菜单里点一下就能启动。以下命令都以Linux/macOS为例。很多人会忽略磁盘空间。OpenClaw本体不大但如果你要拉本地GGUF模型一个7B模型Q4量化版本大约4GB加上Compose镜像和日志建议预留10GB以上。我一开始只分了5GB跑一个模型就满了后面迁移数据相当痛苦。2.2 姿势A二进制一键安装跑通核心功能以Linux为例执行官方脚本下面地址是示意请以仓库readme为准curl -fsSL https://get.openclaw.sh | bash脚本会检查依赖、下载对应平台的二进制、初始化~/.openclaw目录和默认配置。装完后执行openclaw doctor它会告诉你缺什么比如没装git、端口占用之类。这一步我很推荐它会直接输出当前系统的体检结果省得后面瞎猜。如果你在macOS上同样是一条命令只是脚本内部会去拉对应arch的包。注意有一些系统自带python如果版本太老脚本可能提示你装个新的。不过OpenClaw本身不依赖Python这个提示通常只是它的环境预检。2.3 姿势BDocker Compose本地一键部署如果你想长期把OpenClaw当成常驻服务来跑Compose是更稳的方式。我的做法是新建一个目录mkdir openclaw cd openclaw curl -fsSL https://get.openclaw.sh/compose.yml -o compose.yml docker compose up -dcompose文件里挂载了./data目录存放配置、会话、模型索引端口默认8180。起来之后docker compose ps看到healthy状态说明服务正常。这样在飞牛这种NAS上也能跑以后升级只需要docker compose pull docker compose up -d。数据都在本机不会因为容器重建而丢失。记住一点不要把data目录随便放在一个会被清理的临时路径下。会话文件、插件、模型索引都在那里删了等于失忆。我给Compose服务配了restart: unless-stopped这样机器重启后服务会自动起来不用手动干预。2.4 初始化第一个agent和它的身份启动后浏览器打开http://localhost:8180进入控制台。首次引导会让你创建一个agent并设置名字比如default。agent在这里不是一个抽象概念它是真正会和你对话的执行单元拥有独立的system prompt、模型路由和记忆空间。创建完成后控制台会给一个agent id后面所有命令都可以用--agent default来指代它。我之前在这里卡过一次因为不知道agent和channel是两个维度agent是“谁来回答”channel是“从哪提问”。两者不是绑死的关系而是可以自由组合。想清楚这一点后面配置就不会乱。3. 把agent接到Teams和飞书channel配置的完整操作3.1 channel是OpenClaw的“接入插口”channel就是渠道适配器。一个agent可以同时挂多个channel一个channel也可以被多个agent共用比如同一个飞书机器人按群分流到不同agent。这个设计是OpenClaw的精华把“谁在说话”和“谁来回答”分开。如果你在后台看到“openclaw agent怎么选择channel”之类的问题本质是在问怎么把agent bind到某个channel上。我建议先用命令行理解这个概念。openclaw channel list能看到所有已配置的渠道openclaw agent link --agent default --channel teams建立绑定关系。翻译成人话就是让default这个agent开始接收Teams的消息。3.2 Teams接入注册Bot和两个关键参数Teams bot需要一个Azure Bot Service应用拿到App ID和App Password还要在Teams的Channel里配置Messaging endpoint。在OpenClaw侧只需要一行命令openclaw channel add teams \ --type teams \ --app-id 你的AppID \ --app-password 你的密钥 \ --endpoint https://你的openclaw地址/teams然后到Azure门户把同样的endpoint填到Bot的Messaging endpoint里。这里有个经验endpoint填成http://localhost是不行的Teams要求公网HTTPS。如果你没有公网IP可以用云厂商的负载均衡或云端服务先顶着不建议在生产环境用临时隧道因为地址不稳定会频繁触发握手失败。3.3 飞书接入长文本输出容易截断飞书应用创建流程开放平台建应用开启事件订阅拿到App ID/Secret和Encrypt Key。OpenClaw命令openclaw channel add feishu \ --type feishu \ --app-id xxx \ --app-secret xxx \ --encrypt-key xxx飞书比较特别的一点机器人回复长文很容易被截断这是渠道侧限制不是模型的内容短。解决方案在配置文件里channels: feishu: split_long_message: true max_segment_chars: 1200这样长回答会按段拆成多条消息发送。我建议max_segment_chars设置在1000到1500之间太小会刷屏太大会继续打回截断。飞书新版还支持使用WebSocket长连接接收事件配置文件里feishu.use_websocket: true可以解决服务不在公网的问题。我知道很多人在这一步卡了很久包括我。3.4 验证bot是否真的能说话配置完别急着写花活。先在控制台的channel列表里看到状态是“connected”然后分别到Teams和飞书里给机器人发一条“你好”。如果看到回复说明agent和channel的绑定关系已经生效。如果没回复优先看日志见后面第5章。这里有个容易忽略的点飞书的事件订阅如果没配置“长连接”模式而你的服务不在公网事件根本推不进来。验证消息时我建议用最简单的英文“hi”不要用长句或带特殊符号的内容。因为长句可能触发分段逻辑特殊符号可能被渠道转义容易干扰你的判断。等基础对话正常了再慢慢试复杂prompt。4. 模型接入一边连千问一边跑本地GGUF4.1 模型配置的本质是provider抽象OpenClaw不内置任何大模型它只负责定义模型来源。配置里每个模型都需要一个provider可以是云厂商兼容接口也可以是本地llama运行时。这样同一个agent可以按任务切换模型简单问答用轻量模型复杂代码用更强模型。这个“模型路由”能力是我最终坚定使用它的原因。配置模型前先理解provider不是模型名称。一个provider是“怎么访问模型服务”一个model是“用哪个具体模型”。比如OpenAI兼容接口就是一个provider里面可以挂qwen-plus、qwen-max、gpt-4o-mini等多个model。OpenClaw配置冗余度很低照着结构写就行。4.2 三行配置接上千问Qwen阿里云百炼/DashScope提供OpenAI兼容接口OpenClaw直接复用models: qwen-plus: provider: openai base_url: https://dashscope.aliyuncs.com/compatible-mode/v1 api_key: ${DASHSCOPE_API_KEY} model_name: qwen-plus在environment变量里放好DASHSCOPE_API_KEY然后执行openclaw model reload。这一点我专门单独讲不要在配置文件里写明文key因为~/.openclaw/下通常是644权限同机的其他用户都能看到。养成用环境变量引用key的习惯后面把配置同步到其他机器时也安全。接完千问后建议先跑一条“你的支持哪些模型”的指令让agent报告当前可用模型列表。这一步能验证配置是否被正确加载也能确认模型路由表没有类型错误。4.3 本地GGUF模型完全离线的Agent底座如果你追求私密或没稳定的云APIOpenClaw能把llama.cpp编译进运行时直接加载GGUF文件。配置如下models: qwen-local: provider: llama model_path: /data/models/qwen2.5-7b-instruct-q4_k_m.gguf context_size: 8192 gpu_layers: 32gpu_layers在有显卡时可以全部接入GPU纯CPU机器建议30层以内或调低。实测7B Q4在2核4G机器上大约每秒3到5个token勉强能聊真要顺畅建议12G内存或加显卡。加载后渠道收到的消息就路由到本地模型了。如果你想在安卓App里直接使用AI功能与其在端侧集成GGUF不如把OpenClaw当成一个内网服务手机App通过HTTP调用这样省电也省包体。本地模型一个隐藏好处是离线可用。有一次我家的公网连接不稳定云端API超时本地模型依然能正常回复。对于追求可靠性的用户这个兜底价值非常大。4.4 模型路由与切换的小技巧控制台里可以给agent设置“默认模型”和“备用模型”。我的习惯是Teams渠道的agent默认用千问快速版命令类任务给它一个!model qwen-local的指令随时切本地。在配置里agents: default: default_model: qwen-plus fallback_model: qwen-local这样云API挂了也不会让机器人变哑巴。备用模型触发时OpenClaw会在日志里打一条warning你可以借此顺便监控云API的可用率。不要把所有重担都压在一个模型上尤其是你依赖免费额度或者临时key的时候。5. 跑通之后最常见的坑session file locked和沉默的agent5.1 “agent failed before reply: session file locked (timeout 60000ms)”的完整排查链路这个报错短时间内高频出现尤其是你开了多个服务进程或者Docker和宿主机各跑了一个实例。原因是OpenClaw会把每个agent的会话状态写到磁盘文件并加文件锁防止并发写。两个进程同时读同一个session第二个会等待等超过60秒就直接报错。排查步骤先看有没有重复进程pgrep -af openclaw如果看到两个或以上保留你确实想留的那个其余杀掉pkill -f openclaw serve删除残留锁文件rm -f ~/.openclaw/sessions/*.lock重启服务openclaw serve 裸机或docker compose restart openclaw还不行就把OPENCLAW_SESSION_LOCK_TIMEOUT临时调小帮助快速失败进一步暴露底下的锁是哪来的。这个链路是我实际遇到过三次以后才总结成的固定流程。第一次我以为只是偶发重启就好第二次发现是systemd和手动进程并存第三次才知道锁文件没清理。排查要领是不要急着杀进程先看锁文件的时间戳和进程PID能直接看出谁还在占着。5.2 agent进程活着却不回复先查channel事件是否送达如果进程正常日志也没有error但bot不回复。最可能的原因是渠道事件根本没到OpenClaw。以飞书为例打开飞书开放平台的调试工具往应用发消息时看“事件接收”是否触发。如果事件收到了但agent route没匹配上多半是channel没有bind到agent。检查命令openclaw channel list openclaw agent list openclaw agent link --agent default --channel feishu没有bind就补一行。这个错误提示不会出现在日志里光看服务本身完全健康。我遇到过最隐蔽的一次channel列表显示connected但绑定的是另一个agent所以消息进了老agent的上下文导致看起来像“没回复”。5.3 多个渠道重复回复的真相一个常见的抱怨“我在飞书发消息Teams里也收到同样的回答。”这不是bug而是你把同一个channel bind到了多个agent或者同一个agent bind到了多个channel但每个channel都配置了自动接受所有消息。OpenClaw默认是所有channel共享同一个agent的回复如果你需要不同渠道分别触发不同agent在管理后台把channel的“auto-reply”关掉或者用路由关键词。合理设置后各渠道可以完全隔离。我用过一个简单办法每个渠道前缀不同。飞书机器人叫“助理”Teams机器人叫“小O”用户感知上就是两个不同人格但底层可能是同一个agent在不同system prompt下的变体。这个思路很适合团队共用一个服务。5.4 日志里比“error”更需要注意的字段OpenClaw的日志不是普通工具那种错误堆积它有分层。openclaw logs --follow能看到每个请求从channel到model的完整链路。重点看msg_typeevent和msg_typeagent_reply两行是否配对。如果event有但reply没有问题在agent或模型如果event都没有问题在channel或网络。这一招能把排查时间缩短一半。日志中还有一个容易被忽略的字段ttfb表示从收到消息到第一次回复的耗时。如果你发现某条消息ttfb特别长但最终正常那多半是模型在长上下文或者本地推理。这个字段能帮你判断是性能问题还是配置问题。6. 从“能说话”到“会做事”再往深走一点6.1 用定时任务把被动问答变成主动通知OpenClaw内置了简单的cron调度可以在配置里写schedules: morning-report: cron: 0 8 * * * agent: default channel: feishu prompt: 给我一份今天的技术晨报包括关注的repo更新和重要会议提醒这样每天早上8点飞书会准时收到agent主动推送的消息。定时任务和普通问答最大的区别在于触发源是时钟而不是用户排查时看openclaw logs里triggerschedule。我测试时会把cron临时调成每分钟一次确认稳定后再改回正常频次不然等一次要等很久。6.2 写自己的插件从日志收集到命令执行OpenClaw的插件目录在~/.openclaw/plugins每个插件其实就是一组工具函数。如果你以前写过Logstash自定义插件会发现思路很像定义一个名字、一组输入参数、一个执行函数然后agent可以按需调用。我这里不展开具体代码但建议先实现一个“回显服务器状态”的插件比如读取/proc/loadavg返回给agent拼进回复。这样agent就不再是只会聊天的Bot而是一个能帮你执行只读命令的接口。写插件时注意定义好函数的schema描述。一个大模型能不能正确调用你的插件很大程度取决于你写的description是否清晰。不要写“获取服务器负载”要写“获取当前系统的1/5/15分钟平均负载返回格式为字符串适合在资源告警时使用”。描述越具体调用准确率越高。6.3 和CI/CD跑在一起python持续集成部署新版本后自动通知很多团队会问怎么把AI机器人接进研发流程。我的做法是在GitLab CI或GitHub Actions里加一步curl -X POST http://openclaw:8180/v1/message \ -H Authorization: Bearer $OPENCLAW_TOKEN \ -d {channel:feishu,agent:default,text:部署完成}OpenClaw暴露了HTTP API等于你可以把任何自动化任务的输出变成一条IM消息。Python持续集成部署时在脚本末尾调这个接口团队就能在群里收到结果。这里的关键是给该接口配置一个只读token不要把admin token暴露到CI里。我见过不少团队把webhook地址直接写在仓库变量里权限开成全部channel可写结果谁都能往公司群里发消息。最基本的安全习惯是CI用的token只允许访问指定channel不允许读会话历史也不允许操作配置。6.4 我用了两个月后的配置习惯最后分享几个小经验配置一律放config.yaml并纳入版本管理敏感字段用环境变量每个channel都设置一个独立的会话前缀避免上下文串味模型默认不追求最强够用就行把强模型留给!model手动切换。OpenClaw的更新频率相当快我会定期docker compose pull并看changelog因为很多新channel适配和bugfix都很及时。如果你也想省心地维护一个随时可用的AI入口这套配置值得一试。