为什么 OpenClaw 值得 Node.js 开发者关注
说实话，当我第一次看到 OpenClaw 的 package.json，就知道这个项目的工程化水平不一般。一个完整的 AI Agent 框架，底层跑在 Node.js 上，用 npm 生态串起了从安装到运行的全链路——这对我们前端工程师来说太友好了。
本文把部署 OpenClaw 的过程拆解成一个个依赖管理和工程化的步骤，帮你在本地稳稳跑通。
第一步：Node.js 环境——版本管理是基本功
OpenClaw 要求 Node.js >= 22。如果你还在手动从官网下 .pkg 安装，是时候切到 nvm 了。nvm 管理多版本 Node.js 就像 package.json 管理依赖一样优雅。
# 安装 nvm（如果还没装过）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
source ~/.zshrc # 或 source ~/.bashrc
# 拉取 Node.js 22 并设为默认
nvm install 22
nvm alias default 22
确认一下版本：
node -v # v22.x.x
npm -v # 11.x.x
插一句：如果你团队统一用 pnpm，后续
npm install -g openclaw可以换成pnpm add -g openclaw，效果一样，还能享受 pnpm 的硬链接去重。yarn 的全局安装命令是yarn global add openclaw。
第二步：安装 OpenClaw——两种包管理策略
策略一：全局安装（快速上手）
npm install -g openclaw
全局包的 bin 会被 link 到 $(npm bin -g) 目录。如果你发现终端找不到 openclaw 命令，八成是这个路径没在 $PATH 里。解决办法：
# 查看全局 bin 路径
npm bin -g
# 追加到 shell 配置
echo 'export PATH="$(npm bin -g):$PATH"' >> ~/.zshrc
source ~/.zshrc
策略二：从源码构建（适合想看内部依赖树的人）
git clone https://github.com/openclaw/openclaw.git
cd openclaw
# 看看依赖树长什么样
npm ls --depth=0
# 安装依赖并构建
npm install
npm run build
npm link # 把本地构建产物 link 到全局
npm link 是个被低估的命令。它在全局 node_modules 里创建一个符号链接指向你的本地项目，这样你既能用 openclaw 全局命令，又能随时改源码、rebuild。
验证安装：openclaw --version
第三步：初始化——onboard 的背后发生了什么
openclaw onboard --install-daemon
这条命令做了几件事：
- 创建
~/.openclaw/配置目录 - 生成
openclaw.json核心配置文件 - 在 Mac 上注册 LaunchAgent（
~/Library/LaunchAgents/ai.openclaw.gateway.plist），Windows 上则是 systemd 服务 - 启动交互式配置向导
向导里的关键选项：
- Security: Yes
- Onboarding mode: Manual（推荐，控制力更强）
- Setup: Local gateway
- Model provider: 按你手头的 API Key 选
第四步：模型配置——JSON 就是你的 .env
编辑 ~/.openclaw/openclaw.json。以通义千问为例：
{
"gateway": {
"mode": "local",
"port": 18789,
"auth": { "token": "${OPENCLAW_GATEWAY_TOKEN}" }
},
"models": {
"mode": "merge",
"providers": {
"dashscope": {
"baseUrl": "https://dashscope.aliyuncs.com/compatible-mode/v1",
"apiKey": "sk-你的API_KEY",
"api": "openai-completions",
"models": [
{ "id": "qwen-turbo", "name": "Qwen Turbo" },
{ "id": "qwen-max-latest", "name": "Qwen Max Latest" }
]
}
}
},
"agents": {
"defaults": {
"model": { "primary": "dashscope/qwen-turbo" },
"workspace": "~/.openclaw/workspace"
}
}
}
重点提醒：apiKey 要直接写死在 JSON 里，不要用 ${ENV_VAR} 语法。原因很简单——Mac 的 LaunchAgent 启动的进程，拿不到你在 Terminal session 里 export 的环境变量。这跟 Node.js 里 process.env 能读到 .env 文件是两码事，LaunchAgent 的运行环境完全独立。
所有兼容 OpenAI Chat Completions 协议的模型都能接入：DeepSeek、智谱 GLM 等，改 baseUrl 和 apiKey 就行。
第五步：飞书插件——npm 生态的渠道扩展
npm install -g @openclaw/feishu
openclaw configure
选择 Channels → Feishu/Lark，填入飞书应用的 App ID 和 App Secret。
飞书开放平台侧需要：
- 开启机器人能力
- 事件订阅选长连接模式
- 权限：
im:message、im:chat、contact:user.base:readonly
注意：OpenClaw 新版内置了飞书插件，再全局装
@openclaw/feishu会触发duplicate plugin id detected警告。遇到这个直接npm uninstall -g @openclaw/feishu就好，不影响功能。
第六步：启动网关
openclaw gateway --port 18789
控制台输出 listening on ws://127.0.0.1:18789 就算成功。openclaw dashboard 打开 Web UI。
常见问题排查
端口冲突
网关没正常退出时，重启会报 gateway already running：
lsof -i :18789 # 找出占用进程
kill -9 <PID> # 终止
rm -f /tmp/openclaw/gateway.lock # 清锁文件
openclaw gateway --port 18789 # 重启
模型切换后缓存残留
openclaw sessions cleanup
rm -f ~/.openclaw/agents/main/agent/auth-profiles.json
openclaw gateway stop && openclaw gateway --port 18789
配置文件 schema 升级
OpenClaw 版本迭代后 JSON 结构可能变化。常见的是 models 必须用 models.providers 嵌套，agents 要用 agents.list 数组。跑不通时先对照官方文档或本文示例核对结构。
LaunchAgent 管理
launchctl list | grep openclaw # 查状态
launchctl bootout gui/$(id -u) ~/Library/LaunchAgents/ai.openclaw.gateway.plist # 停
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/ai.openclaw.gateway.plist # 启
小结
OpenClaw 的工程化做得相当扎实：npm 全局安装一步到位，npm link 支持本地开发，LaunchAgent 做守护进程，JSON 配置文件结构清晰。对于熟悉 Node.js 生态的开发者来说，这套部署流程几乎零学习成本。
真正需要花精力的，是后续的 skills 配置和 agents 编排——但那就是另一篇的内容了。