乐悠厨房2026年还在折腾个人AI机器人接入的兄弟姐妹，应该都注意到了OpenClaw（社区里也有人叫它Clawdbot）这名字最近出镜率有多高。简单说，它就是一个把大模型能力打包成可交互的IM机器人中间件：部署好之后，钉钉、飞书、QQ里直接发消息召唤Agent，让它查资料、跑任务、调工具、写回复，底层模型随便换，Docker一键拉起来就能跑。我自己从第一版OpenClaw开始就在跟踪这个项目，中途踩过不少部署和接入的坑，这篇文章就是把实际跑通OpenClaw的步骤、钉钉/飞书/QQ三条通道的接法，以及几个高概率翻车点一次讲清楚。文章里的方案都是按照常见实践整理出来的，适合刚入门的同学照着操作，也能给已经跑起来但想优化的人提供一些参考。
1. 部署前必须想清楚的三件事
1.1 OpenClaw到底扮演什么角色
很多人第一次接触OpenClaw，第一反应是“这不就是个机器人框架吗”。对，也不全对。OpenClaw的定位其实更接近一个Agent运行容器，它不只是把消息转发给大模型然后返回结果，还负责工具调用、记忆管理、多轮对话上下文维护，以及IM平台事件回调的解析。换句话说，钉钉、飞书、QQ这些平台只是“入口”，真正干活的是OpenClaw里配置的模型和Skill。
所以部署前先想清楚一个问题：你打算拿它干什么。是纯粹做个聊天机器人，还是想让它调用API帮你查天气、操作数据库、跑定时任务？这个决定直接影响你后续要装哪些依赖、配哪些权限、给哪些平台账号开接口。我见过太多人一上来就照着别人教程把容器跑起来了，结果发现自己只需要最简单的单轮问答，却配了一大堆没用的Skill，维护成本反而上去了。
从架构上看，OpenClaw可以分为三个部分：接入层、Agent核心层、模型层。接入层负责对接钉钉、飞书、QQ等IM平台，接收事件、发送消息；Agent核心层维护会话状态、决定调用哪个工具、组织回复；模型层则是真正做推理和生成的地方，可以是OpenAI兼容接口、DeepSeek、Ollama本地模型等。三者相互独立，换模型不用动接入配置，换平台不用重新配模型，这也是我推荐通过Docker部署的原因——这种模块化结构本身就是为了容器化准备的。
1.2 为什么要优先选Docker部署
OpenClaw的官方仓库提供两种部署方式：直接拉源码跑、用Docker跑。源码跑的好处是改代码方便，适合二次开发；坏处是依赖管理容易出问题，Python版本、Node版本、系统库缺一不可。2026年这个时间点，OpenClaw的依赖树已经相当庞大了，直接在一台新机器上跑源码，光处理依赖冲突就能耗掉半天。
Docker方案把环境差异直接抹平了。官方镜像打好了所有运行时依赖，你只需要保证宿主机有Docker和Docker Compose，剩下的就是配置文件和网络问题。我的建议是，除非你要改OpenClaw源码本身，否则一律用Docker Compose部署，后续升级也方便，改一下镜像版本号重新up就行。
还有一点容易被忽略：OpenClaw的Control UI（控制面板）和Agent进程会分别占用端口，源码方式跑容易因为端口冲突或者日志目录没权限导致半死不活的状态，而容器化部署天然隔离了这些进程级的问题。后面我会专门讲到Control UI启动失败的排查，这个问题在源码部署里出现概率非常高，但Docker下基本消掉了。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 环境要求与镜像准备
2.1 机器配置建议和系统选择
OpenClaw本身不算吃资源，真正的资源消耗主要看底层模型。如果你用的是云端API（DeepSeek、Kimi、MiniMax这类），OpenClaw进程占用的内存大概在500MB到1GB之间，CPU要求也不高，树莓派或者早期双核小主机都能跑。但如果你计划接Ollama跑本地模型，那就要看模型规模了：7B量化模型至少要8GB内存，14B起步16GB，还得有一块能用的GPU或者NPU才舒服。
操作系统方面，Ubuntu 22.04/24.04是最省心的选择，Debian 12、CentOS Stream 9、Rocky Linux 9也都兼容。Windows用户建议直接用WSL2，但要注意WSL2的网络模式和文件系统性能问题，有些坑后面会说到。容器环境我建议Docker Engine 24以上，Docker Compose Plugin版本2.20以上，太低的话Compose文件里的一些字段不兼容。
服务器网络方面，如果机器在国内，拉取镜像会遇到加速问题，建议先配置好国内可用的镜像加速器，避免首次拉取超时。后续接入平台回调时，如果用到Webhook模式，还需要公网能访问到你的服务，这个在接入钉钉和飞书时尤其重要。
2.2 获取镜像和版本选择策略
OpenClaw的镜像发布在GitHub Container Registry和Docker Hub上，社区常用的是ghcr.io/openclaw/openclaw这个路径。拉取命令很简单：
bash复制docker pull ghcr.io/openclaw/openclaw:latest
但我不建议生产环境直接用latest标签，因为OpenClaw的迭代速度很快，两次拉取可能行为都不一样。更稳妥的做法是先拉latest，跑起来确认功能正常后再换个具体版本号固定住。查看已运行容器的镜像版本可以这样：
bash复制docker inspect $(docker ps -q) --format='{{.Config.Image}}'
选择版本时还有一个技巧：看官方Release说明里是否提到“breaking change”。如果某个版本重构了配置文件结构或者改了Skill目录规范，就不要急着升级。我自己的做法是每个大版本单独建一个目录，比如openclaw-v1.5、openclaw-v2.0，切换时改一下Compose的镜像版本和挂载目录就能回滚，互不干扰。
3. OpenClaw核心服务安装与启动
3.1 编写Docker Compose文件
部署OpenClaw的Compose文件不算复杂，但有几个细节值得注意。下面是我当前正在用的配置，你可以直接按需修改：
yaml复制version: "3.8"
services:
openclaw:
image: ghcr.io/openclaw/openclaw:latest
container_name: openclaw
restart: unless-stopped
ports:
- "8080:8080" # Control UI端口
environment:
- TZ=Asia/Shanghai
- OPENCLAW_CONFIG_DIR=/app/config
- OPENCLAW_SKILLS_DIR=/app/skills
- OPENCLAW_DATA_DIR=/app/data
- OPENCLAW_LOG_LEVEL=info
volumes:
- ./config:/app/config
- ./skills:/app/skills
- ./data:/app/data
- ./logs:/app/logs
extra_hosts:
- "host.docker.internal:host-gateway"
配置文件、Skill目录、数据目录都通过卷挂载出来，这样升级容器镜像不会丢数据。extra_hosts那段是给需要连宿主机本地服务的场景准备的，比如你要让OpenClaw访问宿主机上另一个端口的服务，没有这个映射就没法用localhost直接访问。
如果你要接Ollama本地模型，在Compose里可以加一段：
yaml复制 networks:
- ollama_net
networks:
ollama_net:
external: true
前提是Ollama容器也挂在这个网络里，或者直接让OpenClaw容器使用host网络模式。不过host模式在macOS和Windows上兼容性一般，Linux下用起来倒是简单粗暴。
3.2 初始化配置和目录结构
启动之前建议先把配置目录的结构建好。我第一次部署时直接创建空目录就启动，结果OpenClaw虽然会自动生成默认配置，但目录层级不够完整，后面加Skill时总找不到文件。按官方常见做法和社区习惯，我建议至少手动创建以下目录：
text复制openclaw/
├── config/
│ ├── settings.yaml
│ └── channels/
├── skills/
├── data/
└── logs/
settings.yaml是核心配置文件。第一次启动后如果没有这个文件，OpenClaw会生成一份默认的，但初始内容可能没有包含所有平台接入的示例片段，建议自己手动补全。一份最简配置大概长这样：
yaml复制agent:
name: clawd-bot
model:
provider: openai-compatible
base_url: http://host.docker.internal:11434/v1
api_key: ollama
model: qwen2.5:7b
server:
control_ui:
enabled: true
port: 8080
token: your-control-token
channels:
enabled: []
先不启用任何IM通道，只把模型接好，用Control UI测试Agent响应是否正常，确认没问题之后再逐个接入钉钉、飞书、QQ。这样排查问题时能快速区分是“模型配置问题”还是“平台接入问题”。
3.3 启动、验证Control UI
配置写好后，直接：
bash复制docker compose up -d
看日志：
bash复制docker compose logs -f
看到类似“Control UI started on port 8080”的日志，说明服务已经起来了。在浏览器打开http://服务器IP:8080就能进入管理界面。
这里有个常见的坑：很多人反馈“OpenClaw Control UI did not start”，大概率不是服务没起来，而是端口没放行或者token没配置。如果浏览器提示无法访问，先在服务器上执行：
bash复制curl http://localhost:8080/api/health
如果有正常JSON返回，说明服务是好的，那就是防火墙/安全组的问题；如果连接拒绝，再去查容器日志。
进入Control UI后用你配置的token登录，在聊天测试框里发一条消息，看看Agent是否正常回复。这一步跑通，后面的IM接入就纯粹是回调配置问题了。
4. 钉钉接入：推荐Stream模式，别折腾Webhook
4.1 两种接入方式对比
钉钉接入有两种主流方式：Webhook模式和Stream模式。Webhook模式需要你有公网地址或域名，钉钉服务器把事件POST到你的接口上；Stream模式则是钉钉平台主动建立一个长连接，你的服务端只需要主动发起连接，不需要公网入口。
我的建议是能用Stream就用Stream。原因很简单：内网环境无需暴露公网端口，安全性更高；省去配置域名证书的麻烦；网络稳定性反而更好，因为长连接重连机制是钉钉SDK内置的。Webhook模式多见于老项目或者需要多应用复用一个回调地址的场景，如果你有现成的公网网关倒也可以用，但首次部署不值得在这上面浪费时间。
4.2 在钉钉开放平台创建机器人
钉钉接入前，需要去钉钉开放平台创建一个企业内部应用，这一步有几个关键点容易填错：
- 应用类型选择“企业内部应用”，而不是“第三方个人应用”。
- 添加机器人能力时，消息接收模式选“Stream模式”。
- Security设置里会生成AppKey和AppSecret，这个AppSecret只显示一次，记得保存。
- 机器人回调的Encrypt Key和Token，Stream模式下也会生成，同样需要保存下来。
创建完成后，在应用的“权限管理”里给机器人添加必要的权限点，比如“联系人读取权限”“消息发送权限”“接收消息权限”。钉钉的权限审核很严格，没权限或者权限范围不够，机器人收不到消息或者发不出去消息，但日志里往往只显示通用的错误码，排查起来很费劲。
4.3 OpenClaw侧配置钉钉通道
在OpenClaw的settings.yaml中，把钉钉通道启起来：
yaml复制channels:
enabled:
- dingtalk
dingtalk:
mode: stream
app_key: "your-dingtalk-appkey"
app_secret: "your-dingtalk-appsecret"
aes_key: "your-encrypt-key"
aes_token: "your-token"
这里有几个细节需要注意：
- aes_key即加解密密钥，钉钉那个密钥是43位Base64编码的，配置时不要丢失任何字符。
- app_key和app_secret要和钉钉开放平台的“AppKey/AppSecret”对应，注意区分AppSecret和机器人Code，二者不是一回事。
保存配置后重启容器：
bash复制docker compose restart openclaw
观察日志，看到类似“dingtalk stream connected”的提示就说明通道建立成功了。然后在钉钉群里@机器人发一条消息，正常情况下几秒内就能收到Agent的回复。
4.4 钉钉接入的常见问题
钉钉这儿踩坑最多的就是“机器人收不到消息”和“能收到消息但回复失败”。前者基本是权限问题或Stream连接断了；后者则要看是不是发给群聊时机器人没有被添加到群、或者机器人没有在群里@报名的权限。调试时在Control UI的日志页面同时开着钉钉端操作，可以看到事件是否进入Agent流程以及错误卡在哪一步。
第2个常见问题是“重复回复”。钉钉的Stream协议在某些情况下会重投消息，OpenClaw侧如果启用了自动去重，问题不大；如果没启用，你会在群里看到同一条回复出现两次。这个在OpenClaw的通道配置里有个deduplicate开关，默认开启，但不要手贱关掉。
5. 飞书接入：长连接优先，事件订阅要细心
5.1 飞书开放平台创建应用和机器人
飞书的接入流程和钉钉很像，但细节上略有差异。去飞书开放平台创建企业自建应用，然后在“添加应用能力”里选“机器人”，给应用加上机器人能力。
创建完成后，你需要在“凭证与基础信息”页面拿到App ID和App Secret。在“事件订阅”页面，飞书提供了两种接收方式：长连接（WebSocket）和Webhook。WebSocket方式不需要公网地址，和钉钉Stream类似；Webhook方式会要求你在平台上填回调URL。
我的建议和钉钉一样，优先用长连接模式。需要特别注意飞书事件订阅的“订阅方式”要选“使用长连接接收事件”，然后在下行事件里添加需要订阅的事件类型，至少要把im.message.receive_v1（接收消息）和im.message.reaction_v1（消息表情回应）选上，否则消息事件根本推不到OpenClaw。
5.2 配置Encrypt Key和Verification Token
飞书在事件订阅里会让你配置一个Encrypt Key和一个Verification Token。这两个值在验证事件回调时特别容易出问题：如果没有正确配置Encrypt Key，飞书发过来的事件内容是加密的，OpenClaw解不开就会报错；Verification Token用于验证事件来源，飞书在首次配置Webhook时会发一个“URL验证”请求，只有正确返回Challenge字段才验证通过。长连接模式下这个验证过程由OpenClaw自动完成，但你仍然要把Encrypt Key和Verification Token配置到OpenClaw中。
设置好权限后，在“权限管理”页面添加以下权限：im:message:send_as_bot（以机器人身份发送消息）、im:message:receive（接收消息）、im:chat:readonly（读取群信息）。其中im:message:send_as_bot这个权限特别容易漏掉，漏掉之后机器人能收消息但完全无法回复，日志里会提示权限不足。
5.3 OpenClaw侧飞书通道配置
飞书的配置长这样：
yaml复制channels:
enabled:
- lark
lark:
app_id: "your-lark-app-id"
app_secret: "your-lark-app-secret"
encrypt_key: "your-encrypt-key"
verification_token: "your-verification-token"
mode: websocket
这里注意通道名称是lark而不是feishu，OpenClaw内部用的是Lark SDK，很多人在这一步对着文档找了半天找不到feishu这个命名，实际上是叫lark。
配置完成后同样重启服务，看到日志里出现“lark websocket connected”就说明长连接建好了。接着在飞书群里@机器人发一条“你好”，正常的回复流程是：飞书长连接收到事件 → OpenClaw解析消息 → 调用模型 → 组装回复 → 通过开放接口发送消息到群里。每一步都有日志，出问题时从日志定位是哪一环断了。
5.4 飞书接入的典型翻车点
飞书最常见的坑是“事件订阅的权限范围没有发布”。你加了权限不代表应用生效，需要在“版本管理与发布”里创建一个应用版本并发布，发布的版本至少要有“企业自建应用”的可见范围。新创建的应用如果不发布，所有权限都停留在草稿状态，机器人能创建但无法实际使用。
另一个问题是飞书机器人只支持在企业内部群使用，不支持单聊或者只有你可见的测试群。我在调试时就吃过这个亏，以为配置错了，实际上只是测试环境不对。
6. QQ接入：官方机器人与OneBot协议两条路
6.1 QQ接入的两种主要方案
QQ接入比钉钉和飞书都要复杂一些，原因是QQ的开放生态相对封闭。常见的方案有两类：一是通过QQ官方开放的机器人平台（q.qq.com）创建QQ机器人，走官方API；二是通过OneBot协议（比如NapCat、Lagrange、go-cqhttp等实现）将你的个人QQ号或小号变成机器人。
官方机器人的优点是稳定、合规，不用担心中间号被风控；缺点是能力受限，很多权限需要平台审核，而且只能发布成公开机器人或指定群可用，个人小号临时拉群这种玩法基本不支持。
OneBot方案的优点是灵活、功能全，你的QQ号可以像普通用户一样收发消息，支持私聊、群聊、临时会话；缺点是需要遵守平台规则，使用第三方协议存在于一定的风控风险，建议用专门的小号，不要用主力号。OpenClaw社区里常见做法是官方机器人优先，OneBot作为补充方案接入。
6.2 QQ官方机器人接入配置
如果你走官方机器人通道，去q.qq.com注册开发者账号，创建机器人应用，拿到AppID和AppSecret。官方机器人还需要一个“沙箱配置”，在沙箱配置里添加测试群或测试用户，只有添加过的群和用户才能和机器人交互，这也是一个新号最容易懵的地方。
OpenClaw这边的配置：
yaml复制channels:
enabled:
- qq_official
qq_official:
app_id: "your-qq-appid"
app_secret: "your-qq-appsecret"
官方机器人开通后还有一个“事件订阅”步骤，需要勾选你要监听的事件类型，至少包括GROUP_AT_MESSAGE_CREATE（群内@消息）和C2C_MESSAGE_CREATE（私聊消息）。如果不勾选对应事件，消息根本到不了OpenClaw。
6.3 OneBot协议接入配置
OneBot方案需要先跑一个OneBot实现。我试过比较多的是NapCat，部署简单，支持Docker和Windows直接运行。启动NapCat时选择“反向WebSocket”连接方式，让NapCat主动连接OpenClaw的WebSocket服务端。
OpenClaw这边启用OneBot通道：
yaml复制channels:
enabled:
- onebot
onebot:
type: websocket_server
host: 0.0.0.0
port: 6700
access_token: "your-onebot-token"
然后在NapCat的WebSocket客户端配置里填上OpenClaw的地址和端口。如果OpenClaw和NapCat不在同一台机器，注意地址要填OpenClaw所在机器的内网IP，端口记得在防火墙放行。
OneBot模式的配置关键是access_token要一致，否则三条握手消息都会失败，日志里会反复出现“unauthorized”或“access token mismatch”。
6.4 QQ接入的注意事项
不管走官方还是OneBot，QQ接入时有两点需要特别注意：
一是QQ的登录态问题。OneBot类方案需要扫码登录QQ，二维码过期很快，建议在部署机器上直接打开一个终端窗口扫码。云服务器没有图形界面时可以用手机端保存登录态的方式，但需要看你选的Framework版本是否支持。
二是消息频率限制。QQ对单个机器人发送消息有频率阈值，如果Agent回复频率太高，会触发错误码或直接被禁言。应对方案是在OpenClaw的Skill层加一个“长回复合并”“多轮对话缓存”的策略，减少批量无意义回复。
7. 多通道同时启用与统一管理
7.1 一个Agent到底能不能同时接三个平台
能，而且同一套模型和Skill配置可以直接复用到三个平台。OpenClaw的Channel抽象层本身就是干这个的：钉钉、飞书、QQ都是通道，每条消息进来后统一转换成内部消息格式，Agent核心逻辑并不关心消息是从哪个平台来的。
但同时启用三个通道会带来两个问题：一是事件回调并发量变大，需要确认服务器带宽和内存是否足够；二是调试时消息来源不好区分。我的做法是在Control UI的会话列表里给它加上通道标签，或者在Agent回复里带上来源标记，比如“来自钉钉”“来自飞书”，方便定位问题。
配置多通道时，channels.enabled列表里写多个值即可：
yaml复制channels:
enabled:
- dingtalk
- lark
- onebot
启动后通过日志观察三个通道是否都连接成功。如果有通道连接失败，不会影响其他通道，这是通道隔离设计带来的好处。
7.2 权限控制和可见性设计
如果你这个机器人会被多人使用，建议在OpenClaw里配置权限策略。最简单的做法是维护一个允许使用机器人的用户白名单，群聊里则限制一个群内的指定角色才能触发Agent。
yaml复制security:
acl:
enabled: true
allow_users:
- "dingtalk:userid_123"
- "lark:ou_456"
- "qq:123456789"
ACL功能在不同版本里配置结构可能不一样，最新版已经支持按通道加用户ID前缀了。不要偷懒省略这一步，等群里有陌生人调你的Agent、消耗你的API额度、或者套取一些不该说的内容时，再回头补权限就晚了。
7.3 Skill的管理：让Agent会干活
如果只是做聊天机器人，Skill可以完全忽略。但OpenClaw的真正价值在于可以给Agent挂不同的工具，让它在收到特定指令时调用外部API。比如我挂了一个天气查询Skill、一个RSS推送Skill、一个数据库查询Skill，这样在钉钉群里发“查一下今天的天气”，Agent会直接调用天气API返回结果，而不是去模型里瞎编。
Skill目录的结构一般是每个Skill一个文件夹，里面包含一个Skill描述文件和一段执行脚本。具体规范不同版本有差异，建议先跑一个自带示例Skill，再照着写自己的。Skill执行出错时会回滚调用栈，日志里会留下trace信息，调试相对友好。
8. 高频问题排查与解决实录
8.1 服务起不来或一直重启
容器一直重启，最常见的三个原因：
- 端口被占用，8080被其他服务占了。
- 配置文件格式错了，YAML缩进不对，OpenClaw启动时解析失败。
- 挂载目录的权限不对，容器内用户没有写权限。
排查顺序：先看日志，docker logs openclaw，有没有语法错误或IOException；再用docker port openclaw看端口映射情况；最后检查目录权限，chmod -R 755或777，注意数据目录权限不要偷懒只给当前用户。
8.2 Control UI打不开
前面提到过Control UI启动问题，其实有另一种情况：UI服务启动失败但Agent主体正常。这时你会看到日志里Agent正常运行，但8080端口没监听。2026年新版本把Control UI拆成了可选组件，如果配置文件里server.control_ui.enabled没设成true，或者没设置token，UI就不会启动。还有一种情况是旧版本升级后UI缓存没清理，浏览器里打开的是旧版静态文件导致白屏，清一下浏览器缓存或者用无痕模式试试。
8.3 钉钉、飞书都收不到消息
三个平台都收不到消息或都收不到回复，优先怀疑两件事：模型接口配置错误，以及Agent核心处理线程堵塞。
模型接口错误体现在日志里会有明确的401/403或connection refused，这时先用最简单的方式测试模型接口是否可用，比如curl直接请求一下你配置的base_url。Agent核心线程堵塞一般是因为某个Skill阻塞了事件循环，日志里出现超时或看门狗重启记录。处理方法是把Skill脚本改成异步执行，或者检查是否有死循环。
8.4 单平台消息有延迟
飞书或钉钉偶尔几秒才回复，一般不是OpenClaw的问题，而是IM平台侧的排队策略。钉钉串行处理时，单条消息的响应时间有时会飙到5秒以上。解决方案是在IM侧关闭“消息已读回执”，减少不必要的回调，同时确认自己的Agent回复里没有加“延迟回复”之类的Skill逻辑。
8.5 配置文件修改后没生效
改了settings.yaml但重启容器后配置没变，先确认挂载路径是否写对了。很多人把配置文件放在宿主机上但Compose里挂载的是相对目录，导致容器读的是镜像内部的默认配置。一条命令验证：
bash复制docker exec openclaw cat /app/config/settings.yaml
如果内容不是你改的文件，说明卷挂载路径对不上。
9. 一点部署后的建议
OpenClaw部署完之后，有几件事建议在正式投入使用前都做一遍。
一是升级策略要想好。OpenClaw版本迭代快，每次升级前先备份config目录和data目录，升级后注意检查配置文件里是否有新的必填字段。我习惯每次升级前用docker cp把容器内数据拷一份出来，防止Compose卷覆盖导致的数据丢失。
二是日志要定期清理。日志目录如果不控制大小，跑两三个月能吃掉好几个GB。用logrotate或者在Compose里给日志加个max-size限制，避免日志把磁盘撑满。
三是模型接口的配额监控。如果你的Agent绑定的是计费API，建议加一个每日调用次数的限制，或者给OpenClaw配一个预算告警Webhook。这个纯属个人经验——我第一版部署OpenClaw时没有配额控制，一周跑下来API账单惊艳到我了。
最后再分享一个小技巧。部署完成后，先在钉钉、飞书、QQ里各建一个只有自己的测试群，把机器人拉进去，然后分别发一遍“你是谁”“现在几点”“调用一下天气Skill查今天的天气”这几条标准测试消息。等三端全通过后再开放给别人用，能省下后面一大半的运维时间。