OpenClaw 本地部署讲解教程：用 TaoToken 统一 Key 打通飞书机器人

1. OpenClaw 本地部署到底在解决什么问题OpenClaw 是一个可以跑在自己电脑上的 AI 网关与机器人框架它能把你常用的聊天工具比如飞书和背后的大模型服务连起来让机器人在群里或私聊里自动回复、查资料、跑任务。很多人第一次听到「本地部署」会以为要买服务器、配域名其实 OpenClaw 的设计目标就是让开发者在自己的笔记本上先把链路跑通确认消息能收发、模型能调用再考虑搬到长期在线的环境。这篇教程面向的是这样一类开发者手上有一台 macOS、Linux 或者装了 WSL2 的 Windows 机器想用 Node.js 环境把 OpenClaw 跑起来并且接入飞书机器人做一次真实的消息收发验证。整个过程中最容易卡住的不是 OpenClaw 本身而是三件事Node.js 版本不够、飞书应用的权限没配对、以及模型服务的 Key 管理混乱。前两个问题我会给出可复制的命令和配置片段第三个问题用 TaoToken 统一 Key 来解决——你只需要在 TaoToken 控制台创建一个 Key然后在 OpenClaw 里配置一次后面切换模型、换服务商都不用改代码。先明确一下 OpenClaw 本地部署能做什么。它启动后会在本机监听一个网关端口默认 18789提供一个 Web 控制台你可以在这个控制台里看到哪些客户端连进来了、哪些会话在对话、记忆文件里存了什么。飞书机器人通过长连接或回调把消息推给这个网关网关再调用你配置的模型服务生成回复最后通过飞书 API 把回复发回去。整条链路都在你自己的机器上消息内容不经过第三方中转适合做内部工具或者个人助理。适合跟做的读者画像会一点命令行能看懂 JSON 配置知道什么是环境变量。不需要你懂 Kubernetes也不需要你有公网 IP。飞书这边用「企业自建应用」的方式创建机器人个人账号也能建只是部分权限可能受限教程里会说明哪些权限是必须的。我试过在一台 16G 内存的 MacBook 上跑这套流程从零到收到第一条机器人回复大概花了四十分钟其中一半时间花在飞书后台找权限入口。所以下面的步骤我会把飞书后台的路径写清楚避免你来回翻菜单。Node.js 版本这块OpenClaw 要求 22 及以上如果你本机是 18 或者 20需要先升级Windows 用户建议用 nvm-windows 管理版本macOS 和 Linux 用 nvm 或者直接装官方包都行。还有一个容易被忽略的点OpenClaw 的网关令牌。安装完成后日志里会给一个带#token的链接这个令牌是访问 Web 控制台和让飞书插件回连的凭证必须复制保存。很多人装完直接把终端关了后面配置飞书插件时找不到令牌只能重装。所以第一步安装完成后先把令牌记到安全的地方。2. TaoToken 前置准备与统一 Key 配置在配置 OpenClaw 的模型服务之前先把 TaoToken 这边的 Key 准备好。TaoToken 的作用是提供一个统一的 API 入口你拿一个 Key 就能调用多种模型不用为每个模型服务商单独注册、单独管理额度。对于 OpenClaw 这种需要频繁切换模型做测试的场景统一 Key 能省掉大量重复配置。打开 TaoToken 官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注册并登录后进入控制台。控制台里找到 API Keys 页面创建一个新的 Key。创建时建议给 Key 起一个能识别的名字比如openclaw-local这样以后在多个项目里用不同 Key 时不会搞混。创建完成后把 Key 复制下来它通常以sk-开头只显示一次丢了只能重建。TaoToken 的 API 地址是 https://taotoken.net/api 这个地址在 OpenClaw 的配置里会用到。注意 API 地址不带任何查询参数直接填这个基础地址即可。模型 ID 方面你可以在 TaoToken 的模型列表里选一个适合日常对话的比如kimi-k2.5或者qwen系列具体可用的模型 ID 以控制台展示为准。选模型的原则是先选一个便宜的做链路验证确认消息能通之后再换成效果更好的。为什么要在 OpenClaw 里用 TaoToken 而不是直接填某个模型厂商的 Key三个原因。第一OpenClaw 的配置文件里模型服务是一段 JSON如果你直接填厂商地址以后换模型要改配置、重启网关用 TaoToken 只需要改模型 ID 这一个字段。第二TaoToken 的 Key 权限和额度是集中管理的你可以在控制台看到每个 Key 的调用情况方便排查是 Key 失效还是网络问题。第三本地部署经常需要反复测试统一 Key 能避免你在多个厂商后台之间来回切换。配置的时候有一个细节要注意OpenClaw 的模型配置支持 OpenAI 兼容格式TaoToken 的 API 也是兼容格式所以 Base URL 填https://taotoken.net/apiAPI Key 填你刚创建的那个Model ID 填你在控制台选的模型。这三件套Base URL、Key、Model ID在后面的配置文件片段里会完整出现你直接复制替换即可。如果你还没有 TaoToken 账号建议先注册再继续往下看因为后面的验证步骤需要真实 Key 才能跑通。注册过程不复杂邮箱验证后就能进控制台。创建 Key 的时候注意选择正确的项目或分组有些账号下会有多个项目Key 是绑定到具体项目的选错了会导致调用时提示无权限。另外提醒一句Key 不要直接写在会提交到 Git 的配置文件里。OpenClaw 支持从环境变量读取 Key推荐的做法是把 Key 放到.env文件或者系统的环境变量里配置文件里用占位符引用。这样即使配置文件被分享出去Key 也不会泄露。下面的配置片段我会同时给出直接写和用环境变量两种方式你根据自己的习惯选。3. 可复制的 OpenClaw 配置文件与飞书接入片段这一节是整篇教程的核心我会给出完整的配置文件片段和命令你按顺序执行即可。先确认 Node.js 版本再装 OpenClaw然后写配置最后启动网关。第一步检查 Node.js 版本。打开终端执行node -v如果输出是v22.x.x或更高跳过升级。如果是 18 或 20需要升级。macOS 和 Linux 用户可以用 nvmcurl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash source ~/.bashrc nvm install 22 nvm use 22Windows 用户下载 nvm-windows 的nvm-setup.exe安装后在 PowerShell 里执行nvm install 22 nvm use 22 node -v第二步安装 OpenClaw。推荐用 npm 全局安装npm install -g openclawlatest如果 npm 安装慢可以换 pnpmpnpm add -g openclawlatest安装完成后执行初始化openclaw onboard --install-daemon初始化过程中会问几个问题模型选择那一步先随便选一个后面我们会用配置文件覆盖。安装完成后终端会输出一个带#token的链接格式类似http://127.0.0.1:18789/#tokenxxxxx把#token后面的字符串复制保存这就是网关令牌。第三步写配置文件。OpenClaw 的配置文件默认在~/.openclaw/config.jsonWindows 在%USERPROFILE%\.openclaw\config.json。用编辑器打开填入以下内容{ gateway: { port: 18789, token: 你的网关令牌 }, models: { default: { baseUrl: https://taotoken.net/api, apiKey: sk-你的TaoTokenKey, model: kimi-k2.5 } }, channels: { feishu: { enabled: true, appId: cli_你的AppID, appSecret: 你的AppSecret, streaming: true } } }如果你不想把 Key 写在文件里可以把apiKey改成${TAOTOKEN_API_KEY}然后在启动前设置环境变量export TAOTOKEN_API_KEYsk-你的TaoTokenKeyWindows PowerShell 用$env:TAOTOKEN_API_KEYsk-你的TaoTokenKey第四步安装飞书插件。在终端执行npx -y larksuite/openclaw-lark-tools install这个命令会自动安装飞书相关的依赖过程中如果提示权限不足Linux 和 macOS 前面加sudo。安装完成后设置流式输出openclaw config set channels.feishu.streaming true第五步启动网关openclaw gateway启动后打开浏览器访问http://127.0.0.1:18789/把之前保存的令牌填进去就能看到 Web 控制台。控制台里会显示网关状态、已连接的客户端、会话列表。飞书这边的配置需要在飞书开放平台完成。访问 open.feishu.cn登录后创建「企业自建应用」。在应用功能里找到「机器人」点击启用。然后在「凭证与基础信息」页面拿到 App ID 和 App Secret填到上面的配置文件里。权限方面至少需要开启im:message、im:message:send_as_bot、im:chat:read这几个批量导入权限的 JSON 可以在飞书后台的「权限管理」里粘贴。配置完成后发布应用版本企业内部使用通常不需要审核。这里有一个关键点飞书机器人的回调地址或者长连接配置。OpenClaw 的飞书插件默认使用长连接模式不需要你填公网回调地址这也是本地部署能跑通的原因。你只需要确保网关在运行插件会自动和飞书建立连接。如果飞书后台要求填请求地址选择「使用长连接接收事件」即可。4. 验证消息收发与成功结果确认配置写完后怎么确认整条链路是通的分三步验证网关能启动、模型能调用、飞书能收发。先看网关启动日志。执行openclaw gateway后终端应该输出类似下面的内容[gateway] listening on 127.0.0.1:18789 [feishu] connecting with app_idcli_xxxxx [feishu] connected [models] default model loaded: kimi-k2.5如果看到[feishu] connected说明飞书插件已经和飞书服务器建立了长连接。如果卡在connecting检查 App ID 和 App Secret 是否正确以及飞书应用是否已经发布。然后测试模型调用。在 Web 控制台里找到「模型对话」或者直接打开 TaoToken 的模型对话页面 https://taotoken.net/api 对应的控制台入口发一条测试消息比如「你好请回复 OK」。如果模型返回了内容说明 TaoToken 的 Key 和模型 ID 配置正确。这一步能排除 Key 失效、模型 ID 写错、额度不足等问题。最后测试飞书收发。在飞书里找到你创建的机器人发一条私聊消息比如「测试」。机器人应该会回复。如果没回复看网关日志里有没有收到消息事件。正常情况下日志会显示[feishu] received message from user: 测试 [models] calling model kimi-k2.5 [models] response received [feishu] message sent如果日志里没有received message说明飞书的事件订阅没配好。回到飞书后台检查「事件订阅」里是否添加了im.message.receive_v1这个事件。如果日志里有received但没有response说明模型调用失败检查 TaoToken 的 Key 和网络。成功的结果是你在飞书里发消息几秒内收到机器人的回复同时 Web 控制台的会话列表里能看到这次对话记录。到这一步本地部署链路就完全打通了。验证的时候建议用一条稍微复杂一点的消息比如「帮我总结一下今天的工作重点」这样能确认模型不是只返回固定内容而是真的在生成。如果回复内容合理说明整条链路包括模型推理都是正常的。还有一个验证技巧在 Web 控制台里查看记忆文件。OpenClaw 会把对话历史存到本地文件里你可以在控制台的「记忆文件」页面看到刚才的对话内容。这能确认消息不仅发出去了还被正确存储了。如果记忆文件是空的说明网关的存储路径配置有问题检查~/.openclaw/目录的写权限。5. 本篇常见错误排查这一节列出本地部署 OpenClaw 接入飞书时最常遇到的报错和解决方法。每个报错都给出真实日志片段和排查步骤。报错一Error: listen EADDRINUSE: address already in use 127.0.0.1:18789这个报错说明 18789 端口被占用了。可能是之前启动的 OpenClaw 进程没关干净或者别的程序占了这个端口。解决方法先找到占用进程macOS 和 Linux 用lsof -i :18789Windows 用netstat -ano | findstr 18789然后 kill 掉对应进程。或者改配置文件里的gateway.port换一个端口比如 18790。报错二401 Unauthorized或invalid api key这个报错来自模型调用说明 TaoToken 的 Key 不对。检查三件事Key 是否复制完整有没有漏掉字符、Key 是否被删除或禁用、配置文件里的apiKey字段有没有写错。如果用的是环境变量方式确认环境变量在当前终端会话里生效了可以用echo $TAOTOKEN_API_KEY检查。报错三local proxy failed或connect ECONNREFUSED这个报错说明 OpenClaw 连不上 TaoToken 的 API 地址。检查baseUrl是否写成https://taotoken.net/api注意不要多写斜杠或者路径。如果本机有网络限制确认能正常访问外网。这个报错和 Key 无关纯粹是网络连通性问题。报错四reading choices或Cannot read property choices of undefined这个报错说明模型返回的响应格式和 OpenClaw 预期的不一致。常见原因是模型 ID 写错了TaoToken 返回了一个错误信息而不是正常的对话响应。检查配置文件里的model字段确认这个模型 ID 在 TaoToken 控制台里是存在的。另外确认baseUrl没有写成其他路径。报错五飞书机器人不回复日志无received message这是飞书事件订阅的问题。检查飞书后台的「事件订阅」页面确认添加了im.message.receive_v1。另外确认应用已经发布未发布的应用事件不会推送到本地。如果用的是长连接模式确认网关进程在运行且日志里有[feishu] connected。报错六OAuth相关错误或app not found这个报错说明飞书的 App ID 或 App Secret 不对。回到飞书后台的「凭证与基础信息」页面重新复制。注意 App Secret 需要点击「显示」才能看到完整值直接复制可能拿到的是掩码。另外确认应用类型是「企业自建应用」不是「商店应用」。报错七openclaw: command not found安装完成后命令找不到说明 npm 全局 bin 目录不在 PATH 里。macOS 和 Linux 检查npm config get prefix把输出的bin目录加到 PATH。Windows 检查 npm 全局目录是否在系统环境变量里。或者直接用npx openclaw代替openclaw。排查的时候有一个通用方法把网关日志的详细级别调高。在配置文件里加logLevel: debug重启网关后能看到更详细的请求和响应内容。这能帮你快速定位是配置问题还是网络问题。6. 长期使用与 Key 管理建议链路跑通之后接下来要考虑的是怎么长期稳定地用。本地部署的一个优势是你可以随时改配置、加功能但也要注意几个维护点。第一网关进程的管理。openclaw gateway是前台运行的关掉终端就停了。如果你希望它一直在后台跑可以用openclaw gateway --daemon或者配合 systemd、pm2 这类进程管理工具。macOS 用户可以用 launchdWindows 用户可以用任务计划程序。长期运行的话建议把日志输出到文件方便出问题时回溯。第二TaoToken Key 的轮换。不要一个 Key 用到底建议定期在控制台创建新 Key、删除旧 Key。OpenClaw 的配置文件支持环境变量所以轮换时只需要改环境变量然后重启网关不用改配置文件。如果你有多个项目共用 TaoToken给每个项目单独建 Key这样某个 Key 出问题不会影响其他项目。第三模型切换。用 TaoToken 的好处是切换模型只需要改配置文件里的model字段。比如你平时用便宜的模型做日常对话遇到复杂任务时临时换成能力更强的模型。改完配置后重启网关即可生效。如果你经常切换可以写一个小脚本用openclaw config set models.default.model 模型ID来改不用手动编辑 JSON。第四飞书权限的最小化。教程里给的权限列表比较全但实际使用时建议按需开启。比如你只需要机器人收发消息就只开im:message相关的权限不要开文档、表格那些。权限越少安全风险越小。飞书后台可以随时调整权限调整后需要重新发布版本。第五本地数据备份。OpenClaw 的记忆文件、会话记录都在~/.openclaw/目录下定期备份这个目录能防止数据丢失。如果你换了机器把这个目录复制过去配置和记忆都能保留。如果你后面想把 OpenClaw 用到团队协作或者长期在线的场景可以考虑把网关部署到一台常开的机器上配置不变只是运行环境从笔记本换成了服务器。TaoToken 的 Key 和模型配置可以直接复用不需要重新申请。需要看更多接入细节的话TaoToken 的接入文档在 https://taotoken.net/api 对应的控制台里有说明API Keys 页面可以管理所有 Key。最后说一个实际经验本地部署最容易出问题的不是 OpenClaw 本身而是环境版本和权限配置。Node.js 版本不对、飞书权限没开全、Key 复制不完整这三个问题占了报错的大多数。把这三件事确认好剩下的就是顺水推舟。跑通之后你可以在这个基础上加自己的技能插件比如让机器人查天气、读本地文件、调内部 APIOpenClaw 的插件机制支持这些扩展。