OpenClaw 在中文社区里经常被描述成“个人 AI 助理网关”实际部署时会牵扯到模型供应商、消息渠道权限、开放平台回调、命令执行审批等多层配置。它不是一个装完就能直接用的单机聊天脚本而是一套把大模型能力接到飞书、钉钉、企业微信、QQ 等办公和社交入口的运行时框架。很多人卡在安装后的第一步不是因为安装包有问题而是因为“模型名写错、机器人未发布、渠道只支持发送不支持接收”这三类问题互相混淆。这篇文章会从环境准备开始走通一个最小安装闭环再分别说明飞书、钉钉、企微、QQ 和小红书的接入边界最后给出模型配置、skill 扩展示例、命令执行审批提示和排错清单。适合已经会使用 Linux、能看懂 YAML/环境变量但没有完整部署过 Agent 网关的开发者。如果只是想在本地命令行里跑通一次对话预计需要三十到五十分钟再接入一个办公 IM通常还要额外留出半小时到一小时因为渠道侧的应用创建和权限审核时间不可控。1. 先理解 OpenClaw 的定位和“全接入”的真实含义1.1 OpenClaw 本质上是模型、工具和渠道之间的中转层可以把 OpenClaw 拆成三层来看模型层负责调用大模型比如 DeepSeek、OpenAI 兼容接口、NVIDIA NIM 上的模型等。工具与 Skill 层负责给模型提供可调用的工具例如执行命令、读取文件、请求接口、运行一段脚本。渠道接入层负责接收飞书、钉钉、企业微信、QQ 等渠道发来的消息把消息转成统一事件交给模型处理再把模型的回复发回原渠道。这三层缺一不可。很多人只关心“渠道能不能接入”却忽略了模型层没有配置正确时即使渠道打通也会在回复前报错。一个容易被误解的点是OpenClaw 并不是要替你在每个平台重新注册账号。它更像一个消息网关每个渠道都要先在对应开放平台创建机器人应用再把应用的凭证填进 OpenClaw 配置。不同渠道对机器人能力的限制完全不同因此“全接入”并不等于“一套配置到处通用”。1.2 办公 IM 的“能收消息”和“能发消息”不是同一件事在对接飞书、钉钉、企微之前要先分清渠道能力渠道常见接入形态能否接收用户消息主要限制飞书企业自建应用机器人可以通过事件订阅或长连接应用需要发布权限点要开通钉钉企业内部应用机器人 / Stream Mode可以使用消息接收 Stream 模式自定义机器人只能发消息不能接收对话企业微信群机器人 Webhook / 自建应用群机器人只能发送自建应用可接收回调回调 URL 需要公网可达或使用云函数中转QQ官方机器人平台可以在沙箱或开放场景中测试审核链路较长个人号方案风险极高小红书没有稳定开放的私信机器人 API通常不能作为会话渠道更适合做文案、选题、素材生成这里的核心判断是如果你的目标是让 OpenClaw 在群里“被 后自动回复”那必须走支持接收消息的应用机器人方案。如果只是让 OpenClaw 把告警或通知推送到群里用 Webhook 发送就够了。文章标题里常见的“飞书/钉钉/企微/QQ/小红书全接入”更多是指不同场景下能分别接入不代表每个渠道都支持双向私聊。1.3 “2026 最强版”这类版本名要先做核实中文社区里类似“2026 最强版”“小龙虾 OpenClaw”的叫法很可能是某个安装包作者或社群对分支版本的命名而不是官方版本号。安装前建议先确认四类信息版本号是v1.x、v2.x还是具体 commit。运行环境Linux x64、ARM64 还是 Windows。安装方式源码运行、二进制包、Docker 还是包管理器。配置目录是~/.openclaw、/root/.openclaw还是/etc/openclaw。不要看到“最新版”就直接拿网盘压缩包覆盖到生产服务器。版本名越夸张越要先看下载来源和校验信息。如果安装包来自第三方至少要检查它的安装脚本是否包含高危命令例如直接修改~/.bashrc、关闭防火墙、写入 root 免密等。开源项目优先使用官方 README 中给出的仓库地址或安装命令。2. 安装前的环境准备先避免最常见的三类失败2.1 系统与资源建议从部署成本角度OpenClaw 的资源占用通常由两部分决定一部分是 Node.js 运行时本身的常驻内存另一部分是模型上下文、工具执行、日志输出和可能存在的浏览器自动化任务。如果是纯文本对话、文档总结、消息转发这类场景2 核 4G 内存的 Linux 服务器足够用来做技术验证。如果会频繁调用长文档解析、网页抓取、图片理解或本地代码执行建议提高到 4 核 8G并配置 2G 以上 swap。磁盘方面安装依赖和日志增长后预留 20G 比较稳妥。推荐环境可以按下表准备项目最低要求建议配置操作系统Ubuntu 20.04 / Debian 11Ubuntu 22.04 / 24.04 LTSCPU1 核2 核及以上内存2G4G 及以上磁盘10G20G 以上运行用户可选专用非 root 用户网络能访问模型 API服务器出口稳定避免频繁超时如果官方文档明确要求某个 Node.js 版本以官方为准。在不确定时优先使用当前 LTS 版本例如 Node.js 20 或 22。不要因为服务器上已经装了一个旧版本 Node 就直接安装版本过旧会导致依赖安装阶段报大量语法错误。2.2 基础依赖安装命令以 Debian/Ubuntu 为例先安装基础工具sudo apt update sudo apt install -y curl git jq unzip如果 OpenClaw 以源码方式运行需要安装 Node.js 和包管理器。下面是一个常见的 Node.js 22 安装示例curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash - sudo apt install -y nodejs node -v npm -v如果项目使用 pnpm可以再启用 corepacksudo corepack enable pnpm -v实际项目中安装命令会随 OpenClaw 版本变化。如果你使用的是官方二进制包或安装脚本就不要照抄源码安装步骤而是先在 README 的Install段落中确认安装方式。安装脚本通常只做“把文件放到指定目录并建立软链”这件事真正决定能否启动的是运行时版本、配置目录和 API 凭证。注意不要把 OpenClaw 直接跑在 root 账号下。Agent 类工具需要执行命令或读写文件如果用 root 运行一旦某个 skill 或指令异常影响范围会扩大到整个系统。建议创建专用用户。2.3 建议用专用用户运行生产环境尽量使用独立用户隔离文件路径sudo useradd -r -m -d /opt/openclaw openclaw sudo mkdir -p /opt/openclaw/.openclaw sudo chown -R openclaw:openclaw /opt/openclaw后续所有 OpenClaw 文件和配置都放在该用户目录下。这样即使某条 prompt 触发了命令执行默认权限也限制在/opt/openclaw范围内不会直接改动系统级目录。3. 最小安装闭环从拉取源码到命令行对话3.1 拉取项目并安装依赖下面以源码运行方式为例。实际操作时请把OpenClaw官方仓库地址替换成官方 README 中的仓库地址不要使用搜索引擎里来源不明的镜像地址。git clone --depth1 OpenClaw官方仓库地址 /opt/openclaw/source cd /opt/openclaw/source pnpm install pnpm build完成后用以下命令确认版本node ./bin/openclaw --version如果命令行中已经存在openclaw命令也可以直接执行openclaw --version openclaw --help这里的关键是先确认命令存在再继续初始化配置。很多人跳过--help直接尝试启动最后报错也不知道是安装失败还是启动参数错误。3.2 初始化配置目录和模型变量第一次启动前先初始化默认配置openclaw init执行后会自动生成配置目录。常见路径是~/.openclaw/里面通常包含~/.openclaw/ config.yaml exec-approvals.json skills/ logs/ workspace/如果当前用户是 root路径可能就是/root/.openclaw/。这也是后续看到legacy exec approvals exist at /root/.openclaw/exec-approvals.json提示的来源。模型相关配置建议放在.env文件里避免密钥进入版本库。以 DeepSeek 为例OPENCLAW_MODEL_PROVIDERdeepseek OPENCLAW_MODEL_NAMEdeepseek-chat OPENCLAW_MODEL_API_KEY你的DeepSeek密钥 OPENCLAW_EXEC_APPROVALtrue注意deepseek是供应商名称deepseek-chat才是模型 ID。如果只写deepseek后续可能出现unknown model: deepseek这类报错。3.3 先在 console 渠道验证再接入 IM不要一开始就配置飞书或钉钉。先用 OpenClaw 自带的 console 渠道跑通“模型能说话”这一步。openclaw start --channel console然后在另一个终端连接会话openclaw chat输入一句“你好请用一句话介绍你自己”。正常情况下模型会返回一段文本。若出现类似下面这种错误agent failed before reply: unknown model: deepseek说明模型配置里的 model 名称没有被供应商识别。把deepseek改成deepseek-chat或改成供应商文档中明确给出的模型 ID。这一步是整个安装流程的“最小闭环”。只有命令行对话框能正常回复再接 IM 渠道才有排查意义。很多渠道接入失败最后查下来不是因为渠道配置而是模型层根本没有成功握手。3.4 用 systemd 守护 OpenClaw 进程验证通过后建议用 systemd 管理 OpenClaw 进程避免 SSH 断开后进程退出。创建文件/etc/systemd/system/openclaw.service[Unit] DescriptionOpenClaw Agent Gateway Afternetwork-online.target Wantsnetwork-online.target [Service] Useropenclaw Groupopenclaw WorkingDirectory/opt/openclaw EnvironmentFile/etc/openclaw/openclaw.env ExecStart/usr/bin/openclaw start Restarton-failure RestartSec5 NoNewPrivilegestrue [Install] WantedBymulti-user.target然后执行sudo systemctl daemon-reload sudo systemctl enable --now openclaw sudo systemctl status openclaw这里需要注意EnvironmentFile和WorkingDirectory必须和实际安装路径一致。不要直接复制这段配置到生产环境先确认which openclaw的输出再把ExecStart改成实际命令路径。4. 模型配置详解unknown model 是怎么产生的4.1 provider、baseURL、modelName 三者不能混为一谈OpenClaw 发出模型请求时通常需要三个关键信息配置项含义错误表现provider模型供应商或协议类型unknown providerbaseURL兼容 API 的请求地址connection error、404、403modelName请求体中的模型 IDunknown model、model not foundapiKey供应商密钥401、invalid api key很多人只配了 provider 和 apiKey却忽略了 modelName 必须精确匹配供应商的模型 ID。例如 DeepSeek 开放平台里模型 ID 一般是deepseek-chat和deepseek-reasoner。如果你在配置里写deepseek服务端收到请求后找不到这个 ID就会在 agent 真正回复前直接失败。4.2 DeepSeek 配置示例常见写法之一OPENCLAW_MODEL_PROVIDERdeepseek OPENCLAW_MODEL_NAMEdeepseek-chat OPENCLAW_MODEL_API_KEY${DEEPSEEK_API_KEY}如果 OpenClaw 支持 OpenAI 兼容协议也可以写成OPENCLAW_MODEL_PROVIDERopenai OPENCLAW_MODEL_BASE_URLhttps://api.deepseek.com/v1 OPENCLAW_MODEL_NAMEdeepseek-chat OPENCLAW_MODEL_API_KEY${DEEPSEEK_API_KEY}这两种方式的目标都是让请求最终落到https://api.deepseek.com/v1/chat/completions同时请求体里的modeldeepseek-chat。区别只是 OpenClaw 内部用哪个协议解析器。具体支持哪一种需要在安装后执行openclaw models list或查看版本帮助确认。遇到agent failed before reply: unknown model: deepsee这类报错时排查顺序是检查 .env 里的 modelName 是否拼写正确。检查是否有多余空格或被 shell 截断。去模型供应商控制台确认实际模型 ID。把 modelName 改为完整 ID 后重启 OpenClaw。4.3 NVIDIA NIM 配置示例如果使用 NIM 提供的 OpenAI 兼容端点baseURL 和 modelName 是关键。OPENCLAW_MODEL_PROVIDERopenai OPENCLAW_MODEL_BASE_URLhttps://integrate.api.nvidia.com/v1 OPENCLAW_MODEL_NAMEnvidia/llama-3.3-70b-instruct OPENCLAW_MODEL_API_KEY${NVIDIA_API_KEY}NIM 页面中显示的模型名通常是带命名空间的例如nvidia/...或deepseek-ai/...。不要只填llama-3.3-70b-instruct这种短名称否则会返回模型不存在。由于 NIM 的模型目录会持续变化部署前以 NIM 控制台页面给出的模型 ID 为准。5. 飞书、钉钉与企微的接入步骤与配置模板5.1 三个平台都需要先创建“应用”接入办公 IM 时最容易搞混的是“开放平台后台的应用”和“OpenClaw 配置里的 channel”。两件事必须分开处理平台侧创建应用/机器人开通机器人能力配置权限发布版本。OpenClaw 侧填写应用凭证启用 channel重启服务。绝大多数接入失败发生在平台侧。比如飞书应用没有发布钉钉机器人没有订阅消息事件企业微信自建应用没有配置回调地址。OpenClaw 侧只是把消息转给模型如果平台侧根本收不到消息或没有权限发消息改 OpenClaw 配置没有意义。5.2 飞书接入的完整路径飞书接入建议用“企业自建应用”因为它支持机器人收发消息和事件订阅。创建应用后需要记录以下信息字段含义App ID应用唯一标识形如cli_xxxApp Secret调用 API 的密钥Encrypt Key事件加密密钥可选但建议开启Verification Token验证回调合法性配置示例channels: feishu: enabled: true appId: cli_xxxxxxxx appSecret: xxxxxxxx encryptKey: xxxxxxxx verificationToken: xxxxxxxx需要在飞书开放平台完成的操作创建企业自建应用。在“添加应用能力”中启用机器人。在权限管理中开通消息读取和发送相关权限。在事件订阅中订阅“接收消息”事件例如im.message.receive_v1。发布应用版本并在测试范围内添加自己。如果使用长连接模式可以避免配置公网回调地址。如果使用 Webhook 模式就需要让 OpenClaw 的 callback 地址可以被飞书服务器访问。不同版本 OpenClaw 的 callback 路径可能不同启动后看日志里的监听地址即可确定。飞书侧返回错误码时不要急着调 OpenClaw 参数。例如遇到 2700002 这类平台业务错误先检查应用是否发布、权限点是否生效、事件订阅是否启用。这类问题通常只需要在开放平台后台调整。5.3 钉钉接入的两种模式钉钉要区分“自定义机器人”和“企业内部应用机器人”。很多教程直接给了一个自定义机器人 Webhook让用户填到 OpenClaw 里。这种方式只能把消息推送到群里无法接收用户发来的消息。如果目标是让 OpenClaw 在钉钉群里做问答需要创建企业内部应用并启用机器人能力再使用消息接收 Stream Mode。这样不用暴露公网回调地址OpenClaw 可以通过长连接接收消息。企业内部应用方式的字段通常是 AppKey、AppSecret、AgentId。示例如下channels: dingtalk: enabled: true mode: app appKey: dingxxxxxxxx appSecret: xxxxxxxx agentId: 123456789 streamMode: true而自定义机器人方式只适合通知推送channels: dingtalk: enabled: true mode: robot webhook: https://oapi.dingtalk.com/robot/send?access_tokenxxx secret: SECxxx在钉钉后台添加自定义机器人时如果启用了“加签”必须把密钥填到配置或环境变量中否则发送时会报签名错误。5.4 企业微信群机器人和自建应用企业微信最简单的接入方式是群机器人 Webhook。在群聊中添加一个群机器人后会得到一个带keyxxx的 Webhook 地址。OpenClaw 可以通过它发送主动通知但不能接收群内消息。如果要在企业微信中做“员工提问、OpenClaw 回复”的客服或内部知识助手需要走自建应用。需要准备字段含义Corp ID企业 IDAgentId自建应用 Agent IDSecret应用密钥Token / EncodingAESKey回调验证与消息加解密群机器人发送的简化配置channels: wecom: enabled: true mode: group-robot webhook: https://qyapi.weixin.qq.com/cgi-bin/webhook/send?keyxxx自建应用接收消息的配置通常还要包含corpId、secret和回调地址。企业微信回调会对消息体做 AES 加密因此 Token 和 EncodingAESKey 必须和后台完全一致。遇到signature error或invalid encoding时优先检查这三项是否复制完整。5.5 配置完渠道后按这个顺序自测接入多个渠道时建议按照下面的顺序逐层验证不要一次性打开所有 channel先用 console channel 确认模型可以回复。单独开启一个目标渠道例如只开飞书。在飞书私聊中给机器人发送“你好”。在群里 机器人测试群聊场景。观察 OpenClaw 日志是否出现对应事件。确认回复成功后再开启下一个渠道。查看日志的命令journalctl -u openclaw -n 100 --no-pager或查看配置目录下的日志文件tail -f ~/.openclaw/logs/openclaw.log日志里如果出现了渠道事件但没有模型回复问题很可能在模型层如果连渠道事件都没有出现问题在开放平台的事件订阅或应用发布状态。6. QQ 与小红书的接入边界先说清楚再动手6.1 QQ 官方机器人可以试但不要碰个人号协议QQ 的接入通常指官方机器人平台。开发者需要注册机器人拿到 AppID、AppSecret 和 Token并在沙箱环境中测试。OpenClaw 如果支持 QQ 官方机器人 channel配置字段通常和飞书/钉钉类似channels: qq: enabled: false appId: 102xxxxxx appSecret: xxxxxxxx token: xxxxxxxx真正阻碍 QQ 接入的往往不是 OpenClaw 配置而是 QQ 开放平台的审核和场景限制。不同版本的 QQ 机器人支持的群聊、频道、私信能力不同需要以官方文档为准。这里要特别提醒不要为了“接入 QQ”去使用非官方个人 QQ 号协议例如 hook 客户端、模拟协议库、网页协议操作等。这类方案不仅容易导致账号受限还存在严重的安全和合规风险。作为技术博客只推荐使用官方开放平台的机器人能力。6.2 小红书没有稳定的全自动对话 API小红书的开放能力和飞书、钉钉完全不同。到目前为止并不存在一个标准的“小红书私信机器人 API”可以让 OpenClaw 自由收发所有私信。很多宣传中的“小红书全自动接入”实际上只是在客户端侧的半自动操作或内容生成辅助不稳定且有账号风险。在合规场景中比较可靠的做法是用 OpenClaw 做内容侧工作流