1. 为什么要在 Ubuntu 上折腾 OpenClaw 飞书OpenClaw 是一个跑在本地、能接管终端与文件系统的 AI Agent 网关飞书则是国内团队最顺手的移动端入口。把两者接起来你就能在手机飞书里给电脑上的 OpenClaw 发消息让它读代码、跑命令、查日志等于把 Ubuntu 主机装进了口袋。这套组合最适合三类人一是手里有台常开的 Ubuntu 机器或 WSL 环境想远程指挥的开发二是团队里已经在用飞书协作希望把 AI 能力塞进现有工作流的人三是想学 Agent 网关原理、准备自己写 skill 的进阶玩家。真正卡人的地方不在 OpenClaw 本身而在三块Ubuntu 下 Node.js 版本与全局包路径、飞书开放平台那一长串权限与事件订阅、以及模型通道怎么统一管理。前两块是体力活第三块如果每个模型都单独配 Key后面换模型、加渠道会非常乱。我这次的做法是让 OpenClaw 的模型请求统一走 TaoToken 的 API 通道一个 Key 覆盖多家模型配置只写一份后面换模型只改一个字段。下面按「环境准备 → TaoToken 接入 → 可复制配置 → 验证 → 排障」的顺序走一遍命令都可以直接粘。2. 前置准备Ubuntu 环境与 TaoToken 统一 Key2.1 Ubuntu 基础环境不管你用的是原生 Ubuntu 还是 WSL 里的 Ubuntu先确认系统信息并装齐基础工具sudo apt update sudo apt upgrade -y sudo apt install -y curl git build-essential uname -aWSL 用户额外确认一下 Windows 盘挂载是否正常方便后面在 Windows 侧访问 Linux 文件ls -l /mnt/c/然后在 Windows 文件资源管理器地址栏输入\\wsl$\Ubuntu\home\你的用户名能进去就说明互通没问题。2.2 安装 Node.js 22.xOpenClaw 对 Node 版本有要求直接用 NodeSource 源装 22.xcurl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash - sudo apt install -y nodejs node -v npm -vnode -v输出v22.x即可。如果之前装过旧版本先sudo apt remove nodejs清掉再装避免 npm 全局路径错乱。2.3 安装 OpenClaw 并初始化工作区npm install -g openclaw mkdir -p ~/openclaw-workspace cd ~/openclaw-workspace openclaw initopenclaw init会在当前目录生成配置骨架。启动网关验证一下openclaw gateway start看到Gateway listening on http://localhost:18789就说明本体跑起来了。如果 Windows 浏览器访问http://localhost:18789异常把绑定模式改成 lanopenclaw config set gateway.bindMode lan systemctl --user restart openclaw-gateway.service之后用http://你的局域网IP:18789访问。2.4 拿 TaoToken 统一 KeyTaoToken 在这里的角色是「模型请求的统一出口」OpenClaw 不直接对接各家模型而是把 base URL 指向 TaoToken 的 API 地址Key 也只填一个。这样后面无论用哪个模型都只改模型名不动通道配置。先去控制台创建 API Key控制台入口https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite在 API Keys 页面新建一个 Key复制保存。接入文档在这里遇到参数疑问可以对照接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewriteAPI 基础地址统一用https://taotoken.net/api注意这个地址不带 UTM 参数配置里照写即可。3. 可复制配置config.toml 与 settings.json 骨架OpenClaw 的配置分两层网关级用config.toml频道与模型相关用settings.json。下面两份骨架可以直接改。3.1 config.toml 骨架在~/openclaw-workspace下创建或编辑config.toml[gateway] host 0.0.0.0 port 18789 bindMode lan [agent] name openclaw-agent workspace /home/你的用户名/openclaw-workspace model claude-sonnet-4-20250514 provider taotoken [agent.model.provider.taotoken] baseUrl https://taotoken.net/api apiKey ${TAOTOKEN_API_KEY} timeout 120 [log] level info follow true关键点baseUrl指向 TaoToken 的 API 地址apiKey用环境变量占位不要把明文 Key 写进文件。3.2 settings.json 骨架频道配置放在settings.json飞书相关字段如下{ channels: { feishu: { enabled: true, appId: cli_xxxxxxxxxxxx, appSecret: ${FEISHU_APP_SECRET}, domain: china, groupPolicy: allowlist, privatePolicy: pairing, eventMode: long_connection } }, plugins: { feishu: { path: ~/.openclaw/plugins/openclaw/feishu } } }privatePolicy建议先用pairing配对模式更安全陌生人发消息不会直接触发 Agent。3.3 环境变量把敏感信息写进~/.bashrc或单独的 env 文件export TAOTOKEN_API_KEYsk-你的TaoTokenKey export FEISHU_APP_IDcli_xxxxxxxxxxxx export FEISHU_APP_SECRET你的飞书AppSecret执行source ~/.bashrc生效。验证一下echo $TAOTOKEN_API_KEY | head -c 8能打印出 Key 前缀就说明环境变量读到了。4. 飞书侧配置与 OpenClaw 频道接入4.1 飞书开放平台建应用访问飞书开放平台扫码登录后点「创建企业自建应用」填名称和描述。进入「凭证与基础信息」复制 App IDcli_开头和 App Secret对应填到上面的环境变量里。接着「添加应用能力」→ 选「机器人」→ 添加。4.2 批量导入权限进入「权限管理」→「批量导入/导出权限」粘贴以下 JSON{ scopes: { tenant: [ aily:file:read, aily:file:write, application:application:self_manage, application:bot.menu:write, cardkit:card:write, contact:user.employee_id:readonly, docs:document.content:read, event:ip_list, im:chat, im:chat.access_event.bot_p2p_chat:read, im:chat.members:bot_access, im:message, im:message.group_at_msg:readonly, im:message.group_msg, im:message.p2p_msg:readonly, im:message:readonly, im:message:send_as_bot, im:resource, sheets:spreadsheet, wiki:wiki:readonly ], user: [ aily:file:read, aily:file:write, im:chat.access_event.bot_p2p_chat:read ] } }再单独搜contact勾选contact:contact.base:readonly获取用户基本信息确认添加后点「批量开通」。4.3 事件订阅进入「事件与回调」→ 订阅方式选「使用长连接接收事件」→ 保存。点「添加事件」→ 搜im.message.receive_v1接收消息→ 确认添加。长连接模式不需要公网回调地址这也是它能跑在家庭宽带 Ubuntu 上的原因。最后进「版本管理与发布」→ 创建版本 → 填版本号 → 保存并提交审核企业自建应用一般自动通过。4.4 OpenClaw 侧装插件与配频道openclaw plugins install openclaw/feishu openclaw channels add openclaw configureopenclaw configure会走交互式向导是否配置聊天渠道选 Yes → 渠道类型选 Feishu → 粘贴 App ID → 粘贴 App Secret → 域名选 China → 群聊策略选 Allowlist → 私聊策略选 Pairing。如果插件装完openclaw plugins list里看不到手动拷到用户插件目录mkdir -p ~/.openclaw/plugins cp -r /usr/lib/node_modules/openclaw/feishu ~/.openclaw/plugins/ openclaw gateway restart openclaw plugins list重启网关并看日志openclaw gateway restart openclaw gateway status openclaw logs --follow日志里出现飞书长连接建立成功的记录就说明频道通了。5. 验证请求手机飞书发消息与模型通道确认5.1 完成配对在手机飞书里找到刚发布的机器人应用发送任意消息比如Hello。机器人会回复一个配对码形如123456。回到 Ubuntu 终端执行openclaw pairing approve feishu 123456配对成功后再发一条消息机器人就会正常回复。5.2 验证模型通道走的是 TaoToken在飞书里发一句需要模型回答的话比如「用一句话解释什么是网关」。同时观察 Ubuntu 终端日志openclaw logs --follow日志里应该能看到请求发往https://taotoken.net/api并返回模型响应。如果日志显示的是其他 base URL说明config.toml里的baseUrl没生效检查是否被settings.json覆盖。想单独验证模型通道是否可用可以用模型对话页面直接测模型对话https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentchatutm_campaignrewrite在页面里选同一个模型发一条消息能正常返回就说明 Key 和通道没问题问题只可能在 OpenClaw 配置层。5.3 手机侧成功标志手机飞书里机器人能连续对话、能响应「帮我看看当前目录有什么文件」这类需要执行本地命令的请求且 Ubuntu 终端日志有对应的工具调用记录就算全链路打通了。6. 本篇常见错排查6.1 网关启动报端口占用Gateway listening没出现报EADDRINUSE。先查占用sudo lsof -i :18789杀掉旧进程或改config.toml里的port然后openclaw gateway restart。6.2 飞书机器人不回复按顺序查三处一是openclaw logs --follow里有没有收到im.message.receive_v1事件没有就是事件订阅或长连接没配好二是有事件但报权限错误回飞书开放平台确认im:message系列权限已开通三是配对没完成私聊策略是pairing时未配对的用户消息会被拦。6.3 模型请求 401 或超时401 基本是 Key 问题确认TAOTOKEN_API_KEY已source生效且config.toml里写的是${TAOTOKEN_API_KEY}而不是明文。超时则把timeout从 120 调大或检查 Ubuntu 出网是否正常curl -I https://taotoken.net/api6.4 插件装了但频道里选不到 Feishu多半是全局 npm 路径和 OpenClaw 查找路径不一致。用npm root -g看全局包位置再按 4.4 的方式手动拷到~/.openclaw/plugins/重启网关后openclaw plugins list确认。6.5 WSL 下 Windows 访问不了网关bindMode设成lan后仍访问不了检查 Windows 防火墙是否拦了 18789 端口以及 WSL 的网络模式。用ip addr拿到 WSL 的 IP在 Windows 侧用这个 IP 访问而不是localhost。7. 后续统一 Key 的长期价值与 Coding Plan这套配置跑通后最省心的是模型通道只维护一份。以后想换模型只改config.toml里的model字段Key 和 base URL 都不动。如果你打算把 OpenClaw 长期挂在机器上跑编码任务、写 skill、做 Agent 实验可以了解一下 Coding Plan它更适合高频、长期的编码场景Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite需要新建或轮换 Key 时回到 API Keys 页面操作即可API Keyshttps://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite配置过程中如果卡在某个报错先看openclaw logs --follow的实时输出九成问题都能从日志里定位到具体环节。