OpenClaw 安装总结：从 Node.js 到 Gateway 的飞书接入实践

1. 为什么我建议你先搞清 OpenClaw 的安装链路OpenClaw 是一个 AI 个人助手框架能接入飞书、Telegram、Discord 等渠道帮你做日程管理、消息转发、浏览器操控甚至执行代码。它本身不绑定某个大模型而是通过 Gateway 这个守护进程把「渠道消息」和「模型能力」串起来。适合谁适合想在自己机器上跑一个可控助手、又不想从零写消息路由的开发者。我实测下来整条链路最容易被卡住的不是 OpenClaw 本身而是 Node.js 版本、npm 全局权限、Gateway 端口占用以及飞书回调地址这四件事。这篇按「Node.js → npm 全局安装 → 初始化工作区 → 启动 Gateway → 飞书接入 → 验证收发」的顺序走一遍每一步都给可复制的命令和配置片段。你跟着做本地跑通消息收发大概 20 分钟。核心检索词先记住OpenClaw 安装、Node.js 环境、npm 全局包、Gateway 启动、飞书接入配置。下面从环境准备开始把每个坑都摊开讲。2. 前置环境Node.js 与 npm 版本怎么选才不返工OpenClaw 要求 Node.js v18 或以上、npm v8 或以上。别用系统自带的旧版本Ubuntu 22.04 默认可能是 v12直接装会报engine不匹配。我推荐用 nvm 管理版本切换干净。# 安装 nvm脚本方式 curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash # 让当前 shell 生效 export NVM_DIR$HOME/.nvm [ -s $NVM_DIR/nvm.sh ] \. $NVM_DIR/nvm.sh # 安装并锁定 Node.js 18 nvm install 18 nvm use 18 nvm alias default 18验证node -v # 期望 v18.x.x npm -v # 期望 8.x 或更高如果你在 Windows 上建议走 WSL2操作和 Linux 完全一致。WSL2 里如果 npm 拉包慢可以换国内镜像源但注意别把镜像源和后面的模型 API 地址搞混npm config set registry https://registry.npmmirror.com这一步做完环境就算齐了。很多人跳过 nvm 直接用apt install nodejs结果 npm 全局目录权限出问题后面装 OpenClaw 报EACCES回头再修更费时间。3. 安装 OpenClaw 并初始化工作区含 npm 权限修复全局安装 OpenClawnpm install -g openclaw openclaw --version如果报EACCES: permission denied别急着sudo把 npm 全局目录挪到用户目录更安全mkdir -p ~/.npm-global npm config set prefix ~/.npm-global echo export PATH~/.npm-global/bin:$PATH ~/.bashrc source ~/.bashrc npm install -g openclaw装完初始化工作区openclaw init它会在~/.openclaw/workspace下生成SOUL.md、USER.md等配置文件。SOUL.md定义助手人格USER.md描述你的偏好后面调教助手主要改这两个。接下来是 Gateway 配置。Gateway 是消息路由核心配置文件在~/.openclaw/config.yaml。这里给你一份可复制的片段注意把模型接入部分换成你自己的地址和 Key# ~/.openclaw/config.yaml gateway: host: 127.0.0.1 port: 18789 logLevel: info model: provider: openai-compatible baseUrl: https://taotoken.net/api apiKey: sk-你的Key modelId: claude-sonnet-4-20250514 channels: feishu: appId: cli_xxxxxxxx appSecret: your_app_secret verificationToken: your_verification_token encryptKey: your_encrypt_key这里有个关键点OpenClaw 走的是 OpenAI 兼容协议所以baseUrl填https://taotoken.net/apimodelId填你要用的模型 ID。Key 在控制台生成地址是https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content生成后填进apiKey。如果你还没决定用哪个模型可以先在模型对话页试一下https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content。配置写完后启动 Gatewayopenclaw gateway start openclaw gateway statusstatus显示running就说明守护进程起来了。如果起不来先看日志openclaw gateway logs4. 飞书接入配置与回调验证把消息真正跑通飞书接入分两步飞书开放平台建应用OpenClaw 填凭证。先去飞书开放平台创建企业自建应用拿到App ID和App Secret然后在「事件订阅」里配置Verification Token和Encrypt Key。这三个值对应上面config.yaml里的字段。飞书要求回调地址可访问。本地调试可以用内网穿透工具把127.0.0.1:18789暴露出去回调路径填https://你的域名/feishu/events在飞书后台「事件订阅」里填这个地址飞书会发一个challenge验证请求。OpenClaw 的 Gateway 会自动响应验证通过后订阅im.message.receive_v1事件。配置完重启 Gatewayopenclaw gateway restart openclaw gateway logs日志里看到feishu channel connected就说明渠道通了。然后在飞书里给机器人发一条消息比如「你好」观察日志是否出现message received和model response sent。如果消息发出去了但没回复八成是模型那一段的baseUrl或apiKey有问题。验证模型请求是否正常可以单独发一条 curlcurl https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer sk-你的Key \ -H Content-Type: application/json \ -d { model: claude-sonnet-4-20250514, messages: [{role: user, content: ping}] }返回里有choices字段就说明模型侧通了。这一步能帮你把「飞书问题」和「模型问题」分开定位。5. 常见报错排查401、local proxy failed、reading choices、OAuth401 UnauthorizedKey 错了或没带Bearer前缀。检查config.yaml里apiKey是否完整以及baseUrl是不是https://taotoken.net/api注意不要多加/v1OpenClaw 会自己拼。local proxy failedGateway 端口被占用或 host 写错。用lsof -i :18789看谁占了改config.yaml里的port再重启。reading choices 报错模型返回体里没有choices通常是modelId写错或模型不支持该协议。去模型对话页确认模型 ID 拼写再回填。OAuth 相关报错如果你用的是需要 OAuth 的渠道比如某些企业应用检查appId/appSecret是否和飞书后台一致以及应用是否发布了版本。飞书自建应用要「创建版本并发布」后事件才生效。npm 装完命令找不到~/.npm-global/bin没进 PATH重新source ~/.bashrc或新开终端。WSL2 下回调不通WSL2 的网络和 Windows 宿主是隔离的内网穿透工具要跑在能访问 WSL2 的那一侧或者直接在 WSL2 里跑穿透客户端。排查顺序建议先 curl 模型接口 → 再看 Gateway 日志 → 最后查飞书后台事件订阅状态。这样能快速定位是模型、Gateway 还是渠道的问题。6. 跑通之后把 OpenClaw 接进你的日常编码流消息收发跑通只是起点。OpenClaw 的 Gateway 支持多渠道路由你可以同时接飞书和 Telegram用同一套模型配置。如果你打算长期用它做编码助手或 Agent 任务建议把模型接入换成 Coding Plan额度和稳定性更适合持续调用https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content。接入文档里有完整的渠道配置示例和事件说明遇到新渠道不会配时直接查https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content。Key 管理在控制台https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content。最后给一个实用技巧把~/.openclaw/workspace用 git 管起来SOUL.md和USER.md的每次调整都留 commit换机器时直接 clone 回来Gateway 配置单独用.env注入敏感字段别把 Key 写进版本库。这样你的 OpenClaw 助手就能稳定跟着你走而不是每次重装都从零调教。