1. OpenClaw 大龙虾机器人到底能做什么为什么值得折腾OpenClaw 大龙虾机器人是一个可以跑在自己电脑或服务器上的开源智能体框架它最大的特点是把大模型的推理能力和本地系统操作、聊天软件消息收发串在了一起。你可以把它理解成一个「住在你终端里的助理」它通过 Gateway 网关服务监听消息收到指令后调用你配置的模型 API 做理解再决定是回复一段文字还是真的去执行 shell 命令、整理文件、发邮件。对于想把 AI 从网页对话框里解放出来、让它真正接触自己工作流的人来说这个方向很有吸引力。它适合谁我观察下来主要是三类人。第一类是开发者想拿它当本地 Agent 的实验底座改源码、加插件、接自己的工具链第二类是效率工具爱好者希望用飞书、钉钉这类日常办公软件直接指挥机器人干活比如整理日程、归档文件第三类是想学习智能体架构的学生或转行者OpenClaw 的插件机制和渠道抽象是很好的阅读材料。它不太适合完全不想碰命令行的人因为安装、配置、排障都绕不开终端。飞书场景为什么单独拎出来讲因为在国内办公环境里飞书的开放平台文档清晰、机器人能力完整、长连接模式不需要你暴露公网回调地址对个人和小团队非常友好。你不需要买域名、不需要配内网穿透只要在开放平台建个企业自建应用把事件订阅设成长连接本地 Gateway 就能直接收到消息。这个闭环一旦跑通后面接钉钉、企业微信的逻辑是相通的。这篇教程的目标很明确从 Node.js 和 npm 环境准备开始一步步走到飞书里给机器人发消息、收到回复为止。中间会给出可复制的环境变量、配置文件片段、权限 JSON以及启动后的验证命令。模型调用这一层我会用 TaoToken 的兼容接口来演示因为它对 OpenAI 风格的 API 兼容做得比较顺配置项少适合作为第一个跑通的模型通道。你跟着做完应该能独立完成一次从零到可用的部署。需要提前说清楚的是OpenClaw 这类工具权限很大它能执行 shell 命令、读写文件。所以强烈建议不要在你装着重要商业数据的主力机上裸跑用一台闲置设备、虚拟机或者云端实例更稳妥。下面进入正题。2. 环境准备与 TaoToken 模型通道前置配置2.1 Node.js 与 npm 环境怎么装才不踩坑OpenClaw 的核心依赖是 Node.js官方要求 18.0 以上我建议直接上 Node.js 22 LTS兼容性和性能都更稳。macOS 和 Linux 用户可以用 nvm 管理版本Windows 用户同样推荐 nvm-windows避免不同项目之间版本打架。macOS/Linux 安装 nvm 和 Nodecurl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash source ~/.bashrc nvm install 22 nvm use 22 node -v npm -vWindows 用管理员权限打开 PowerShelliwr -useb https://raw.githubusercontent.com/coreybutler/nvm-windows/master/nvm-setup.exe | iex nvm install 22 nvm use 22.22.0 node -v装完 Node 之后把 npm 镜像换成国内源依赖下载会快很多这一步不是必须但强烈建议npm config set registry https://registry.npmmirror.com npm config get registry如果后面遇到 node-gyp rebuild 卡住多半是缺编译工具链。macOS 执行xcode-select --installUbuntu 执行sudo apt install build-essential python3Windows 需要装 Visual Studio Build Tools 和 CMake。这个坑我在第一次装的时候也踩过提前装好能省不少时间。2.2 为什么模型通道选 TaoTokenKey 怎么拿OpenClaw 本身不带模型它需要你提供一个兼容 OpenAI API 的模型服务。TaoToken 在这里扮演的就是「模型通道」的角色它对外暴露标准的/v1/chat/completions接口你只要填 Base URL、API Key、Model ID 三个东西OpenClaw 就能把请求发出去。相比自己去对接各家模型平台统一走一个兼容层配置项少切换模型也方便。拿 Key 的流程不复杂。先访问官网了解服务范围然后进控制台创建 API Key。地址我放在这里方便你直接跳官网入口https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content控制台创建 Keyhttps://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentconsoleAPI Keys 管理页https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentapi-keys创建好之后你会拿到一串以sk-开头的密钥先复制到安全的地方。注意这个 Key 只显示一次丢了只能重建。API 的基础地址是https://taotoken.net/api注意这个地址不带任何查询参数配置时原样填入即可。如果你还没想好具体用哪个模型可以先去模型对话页面试试效果确认响应速度和输出质量符合预期再写进配置模型对话体验https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentchat2.3 安装 OpenClaw 本体环境齐了之后装 OpenClaw。macOS/Linux 可以用官方脚本也可以用 npm 全局安装我倾向 npm 方式版本可控npm install -g openclawlatest openclaw --versionWindows 原生支持偏弱建议在 WSL2 里操作或者用 PowerShell 脚本iwr -useb https://openclaw.ai/install.ps1 | iex openclaw --version如果 PowerShell 报执行策略错误先放开当前用户策略再重试Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser想改源码的开发者可以走 Git 克隆路线git clone https://github.com/openclaw/openclaw.git cd openclaw pnpm install pnpm run build pnpm run openclaw onboard装完执行openclaw --version能看到版本号就说明本体没问题了。接下来是初始化这一步会引导你填模型信息也是接入 TaoToken 的关键节点。3. 可复制配置把 TaoToken 和飞书接进 OpenClaw3.1 初始化向导里怎么填模型参数执行初始化命令openclaw onboard首次会出现风险确认提示选择 Yes 继续。到了选择模型提供方这一步选「兼容 OpenAI API」或自定义 OpenAI 兼容端点然后依次填入三件套配置项填写内容Base URLhttps://taotoken.net/apiAPI Key你在控制台创建的sk-开头密钥Model ID你在模型对话页确认可用的模型标识如果你更习惯直接改配置文件OpenClaw 的模型配置一般落在~/.openclaw/config.json或项目根目录的.env里。下面给一份.env片段字段名以你实际版本为准核心是这三项# TaoToken 模型通道配置 MODEL_PROVIDERopenai-compatible OPENAI_BASE_URLhttps://taotoken.net/api OPENAI_API_KEYsk-你的密钥 OPENAI_MODEL你的模型ID对应的config.json结构大致是这样注意 JSON 不能有注释实际使用时把说明文字删掉{ model: { provider: openai-compatible, baseUrl: https://taotoken.net/api, apiKey: sk-你的密钥, model: 你的模型ID }, gateway: { port: 18789 } }填完之后向导会问技能包和记忆功能。新手技能包直接选 No记忆功能建议勾上session-memory这样多轮对话不会失忆。配置结束Gateway 会自动在 18789 端口启动浏览器打开http://127.0.0.1:18789就能看到本地控制台首次进入需要输入初始化生成的配置 Token记得保存好。3.2 飞书插件安装与依赖补齐OpenClaw 通过插件对接飞书先装插件openclaw plugins install m1heng-clawd/feishu cd /root/.openclaw/extensions/feishu/ npm install --verbose注意插件目录路径在不同系统下不一样macOS 通常在~/.openclaw/extensions/feishu/Windows 在用户目录下的.openclaw里。装完用openclaw plugins list确认插件在列。3.3 飞书开放平台建应用、配权限、订阅事件访问飞书开放平台https://open.feishu.cn/app/登录后创建企业自建应用填名称比如「大龙虾AI助手」选图标创建。进入应用管理页点「添加应用能力」选择机器人并添加。然后是权限。进入「权限管理」点「批量导入权限」粘贴下面这段 JSON{ scopes: { tenant: [ contact:user.base:readonly, im:chat, im:message, im:message:send_as_bot, im:resource ], user: [] } }导入后确认。接着配事件订阅进入「事件与回调」事件配置方式选「长连接」保存。点「添加事件」在消息与群组里勾选im.message.receive_v1订阅方式同样选长连接。长连接的好处是不用填回调地址本地服务直接收消息。最后一步别忘进入「版本管理与发布」新建版本填版本号和描述保存并发布。没发布的应用配置不生效机器人收不到消息。3.4 把飞书应用凭证绑到 OpenClaw回到终端执行渠道添加命令openclaw channels add按提示选择飞书输入 App ID 和 App Secret这两个在飞书开放平台「凭证基础信息」里复制。填完重启网关openclaw gateway restart openclaw status看到Gateway running就说明绑定成功。到这里模型通道和消息通道都通了可以进入验证环节。4. 启动验证从发一条消息到收到回复4.1 先用命令行确认模型通道是通的在动飞书之前我建议先单独验证 TaoToken 这条模型通道避免出问题时分不清是模型还是飞书的问题。OpenClaw 一般提供直接对话命令或者你可以用 curl 打一发curl https://taotoken.net/api/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer sk-你的密钥 \ -d { model: 你的模型ID, messages: [{role: user, content: 你好回复一句话确认连通}] }如果返回里能看到choices数组和正常的content说明 Base URL、Key、Model ID 三件套都对。这一步过了再去看飞书。4.2 飞书端发消息测试打开飞书 App进工作台找到你创建的「大龙虾AI助手」点进私聊窗口。发一句「你好」或者更具体一点「帮我列一下今天的三件待办」。正常情况下几秒内会收到机器人回复。如果没回复先看网关状态openclaw status确认 Gateway 在跑。然后看日志日志是排障的核心openclaw gateway --verbose日志里会打印收到的事件、模型请求、返回结果。常见的情况是事件收到了但模型请求失败那问题在模型配置如果连事件都没收到问题在飞书长连接或应用发布状态。4.3 验证成功后的几个实用指令跑通之后可以试试这些自然语言指令感受一下它的能力边界「帮我整理上周的未读邮件提取会议纪要」「把桌面上的 PDF 按日期归档到文档文件夹」「执行 shell 命令查看当前 CPU 使用率」「每天早上 9 点提醒我今日待办」常用终端命令也整理一下方便你日常维护功能命令查看版本openclaw --version查看状态openclaw status启动/停止/重启openclaw start/stop/restart重新初始化openclaw onboard重启网关openclaw gateway restart查看插件openclaw plugins list安装插件openclaw plugins install 插件名卸载插件openclaw plugins uninstall 插件名到这里从 Node.js 环境到飞书接入的闭环就算完成了。下面把我在过程中遇到过的报错集中讲一下。5. 常见报错排查401、长连接失败、choices 读不到5.1 模型请求返回 401 Unauthorized这是最常见的报错日志里通常长这样Error: 401 Unauthorized - invalid api key原因基本是 Key 填错、Key 过期、或者 Base URL 写成了带路径的地址。排查顺序先确认OPENAI_API_KEY是完整的sk-开头字符串没有多余空格再确认 Base URL 是https://taotoken.net/api不要自己加/v1兼容层通常会自动补最后去控制台看这个 Key 是否被禁用或额度耗尽。改完配置记得openclaw gateway restart不然读的还是旧值。5.2 报错里出现 local proxy failedError: local proxy failed to connect upstream这个报错指向网络层。可能是本机网络策略拦截了对taotoken.net的访问也可能是你本地配了某个代理但没生效。先在终端直接 curl 一下 API 地址看能不能通curl -I https://taotoken.net/api如果 curl 也不通问题在网络环境检查防火墙和 DNS。如果 curl 通但 OpenClaw 不通检查 OpenClaw 是否读取了系统代理设置或者配置文件里有没有残留的旧代理地址。把无关的代理配置清掉重启网关再试。5.3 日志里 reading choices 相关报错TypeError: Cannot read properties of undefined (reading choices)这个报错的意思是代码期望响应里有choices字段但实际拿到的响应结构不对。常见原因有三个。第一Base URL 填错请求打到了某个返回 HTML 的地址解析 JSON 失败第二Model ID 写错服务端返回了错误对象而不是正常补全结果第三请求体格式和兼容层期望的不一致。排查方法还是先用 curl 手动打一发看返回的原始 JSON 长什么样。如果 curl 返回正常但 OpenClaw 报这个错检查 OpenClaw 的模型 provider 配置是不是选成了非兼容模式。5.4 飞书提示未建立长连接飞书开放平台保存长连接配置时提示失败或者 OpenClaw 日志里看不到飞书事件。排查确认 App ID 和 App Secret 没填反长连接配置保存后等 1 到 2 分钟再试有时候是平台侧延迟执行openclaw gateway restart重启网关确认应用已经发布未发布的应用长连接不生效。如果还是不行把飞书插件卸载重装一遍依赖没装全也会导致长连接起不来。5.5 消息发出去了但机器人不回按这个顺序排查openclaw status看网关是否 running飞书事件订阅里是否勾了im.message.receive_v1应用是否已发布openclaw gateway --verbose看日志里有没有收到事件。如果事件收到了但没回复多半是模型请求失败回到 5.1 和 5.3 排查模型通道。如果事件压根没收到问题在飞书侧重点查长连接和应用发布状态。5.6 安装阶段 node-gyp rebuild 卡死前面提过这是缺编译工具。Windows 装 Visual Studio Build Tools 和 CMakemacOS 执行xcode-select --installUbuntu 执行sudo apt install build-essential python3。装完清理缓存重来npm cache clean --force npm install -g openclawlatest5.7 Windows 提示系统找不到指定的路径多半是 WSL 没启用或 Git 没装。装 Git 后重启启用 WSL2wsl --install然后清理 npm 缓存重装 OpenClaw。Windows 上如果反复出问题直接切到 WSL2 里操作会省心很多。6. 长期跑起来保活、安全与后续接入建议6.1 让 Gateway 在后台稳定运行本地部署有个现实问题关掉终端Gateway 就停了。想让它 7×24 小时在线可以用 pm2 做进程保活npm install -g pm2 pm2 start openclaw --name openclaw-gateway -- gateway pm2 save pm2 startup这样即使你退出终端服务也在后台跑。如果你有云端实例Docker 部署更干净git clone https://github.com/openclaw/openclaw.git cd openclaw docker compose up -d openclaw-gateway6.2 权限收紧别让机器人乱执行OpenClaw 能执行 shell 命令这是能力也是风险。建议在config.json里设置命令白名单和黑名单{ security: { allowed_commands: [ls, cat, df, free], denied_commands: [rm, shutdown, mkfs, dd] } }把危险命令挡在外面日常查询类命令放开。另外别在装着重要商业数据的机器上裸跑用闲置设备或独立实例更稳妥。6.3 后续可以怎么扩展飞书跑通之后接钉钉、企业微信的逻辑类似都是装插件、建应用、配事件、填凭证。模型侧如果想换改.env里的三件套重启即可不用动业务代码。想深入玩 Agent 的可以研究 OpenClaw 的插件机制自己写工具函数挂进去让它调用你的内部系统。如果你打算长期用它做编码辅助或跑 Agent 任务可以了解一下 Coding Plan按长期使用场景配置会更划算Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentcoding-plan配置过程中遇到接口层面的问题接入文档里有更细的参数说明接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentdoc最后提醒一句版本问题。OpenClaw 更新比较频繁新手别追最新版装一个确认稳定的版本等社区反馈没问题再升。我自己的习惯是先在小号环境验证确认没问题再迁到日常用的实例上。把 Gateway 保活、权限收紧、版本锁定这三件事做好这套东西就能长期稳定地跑下去。