🦞 OpenClaw (龙虾) Windows 安装完全指南

📌 重要说明

• 所有操作均在 C:\Users\czd17 目录下执行（你的用户主目录）
• 最终稳定版本：Node.js v22.14.0
• 避免在 C:\WINDOWS\system32 下执行任何命令

---

一、环境准备

1. 安装 nvm-windows (Node版本管理器)

下载地址：https://github.com/coreybutler/nvm-windows/releases
下载文件：nvm-setup.exe
安装方式：双击安装，全部默认选项

2. 安装 Node.js v22.14.0

# 安装指定版本
nvm install 22.14.0

# 切换到该版本
nvm use 22.14.0

# 验证版本
node -v   # 应显示 v22.14.0
npm -v    # 应显示 10.x

⚠️ 踩坑提醒：

• 最初尝试 Node.js v20.18.0 失败，OpenClaw 强制要求 Node.js ≥22.12.0
• 如果 nvm install 下载慢，可用淘宝镜像手动下载 ZIP 放入 nvm 目录

3. 配置 npm 国内镜像（解决网络问题）

npm config set registry https://registry.npmmirror.com/

---

二、安装 OpenClaw

方法一：一键安装脚本（推荐）

iwr -useb https://openclaw.ai/install.ps1 | iex

⚠️ 踩坑提醒：

• 如果报错 无法加载文件...禁止运行脚本，先执行：

  Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
  

方法二：手动 npm 安装（如果脚本失败）

# 设置环境变量跳过本地模型编译
$env:NODE_LLAMA_CPP_SKIP_BINARY_DOWNLOAD="true"
$env:NODE_LLAMA_CPP_FORCE_NO_GPU="true"

# 安装（忽略编译脚本）
npm install -g openclaw@latest --registry=https://registry.npmmirror.com/ --ignore-scripts

⚠️ 踩坑提醒：

• node-llama-cpp 在 Windows 上编译容易失败，用 --ignore-scripts 跳过
• 跳过不影响使用云端 API（如阿里云、DeepSeek）

---

三、配置与启动

1. 安装网关服务（只需一次）

openclaw gateway install

2. 设置网关模式

openclaw config set gateway.mode local
openclaw config set gateway.port 18789

⚠️ 踩坑提醒：

• 命令格式是 openclaw config set key value，不是 --key --value
• 如果命令报错，可以直接修改配置文件：

  notepad C:\Users\czd17\.openclaw\openclaw.json
  

  添加或修改为：

  {
    "gateway": {
      "mode": "local",
      "port": 18789
    }
  }
  

3. 启动网关

openclaw gateway start

4. 查看访问地址和令牌

openclaw dashboard

浏览器访问显示的 URL，例如：

http://127.0.0.1:18789/?token=

---

四、常用命令速查

功能	命令
启动网关	openclaw gateway start
停止网关	openclaw gateway stop
重启网关	openclaw gateway restart
查看状态	openclaw doctor
查看实时日志	openclaw logs follow
查看配置	openclaw config list
设置配置	openclaw config set key value
获取配置	openclaw config get key
删除配置	openclaw config delete key
更新版本	npm update -g openclaw@latest
前台运行（调试）	openclaw gateway start --foreground

---

五、验证成功运行的标志

执行 openclaw gateway start --foreground 后看到类似日志：

11:15:26 [gateway] listening on ws://127.0.0.1:18789
11:15:26 [browser/server] Browser control listening on http://127.0.0.1:18791/

浏览器能正常打开 dashboard 显示的 URL，且界面可交互。

---

六、常见问题与解决方案

❌ 错误：Cannot find module 'openclaw.mjs'

原因：在错误目录执行命令（如 C:\WINDOWS\system32）
解决：切换到用户目录 cd C:\Users\czd17

❌ 错误：Node.js v22.12+ is required (current: v20.18.0)

原因：Node.js 版本过低
解决：nvm install 22.14.0 并 nvm use 22.14.0

❌ 错误：npm error code 3221225477（node-llama-cpp 崩溃）

原因：本地模型编译失败
解决：npm install -g openclaw@latest --ignore-scripts

❌ 错误：git@github.com: Permission denied

原因：依赖包尝试用 SSH 克隆
解决：

git config --global url."https://github.com/".insteadOf git@github.com:
git config --global url."https://".insteadOf git://

❌ 浏览器访问显示“拒绝连接”

原因：网关服务未运行
解决：openclaw gateway start 或 openclaw gateway start --foreground 查看错误

❌ 配置文件修改不生效

解决：直接编辑 C:\Users\czd17\.openclaw\openclaw.json 后重启网关

---

📝 最终确认清单

• Node.js 版本：v22.14.0
• npm 镜像：https://registry.npmmirror.com/
• OpenClaw 安装：npm list -g openclaw
• 网关服务：openclaw gateway status
• Web 访问：浏览器打开 dashboard URL

---

💡 提示：首次使用需要在网页左下角设置中添加 AI 模型 API Key（如阿里云百炼、DeepSeek 等），之后就可以让“龙虾”帮你干活啦！

OpenClaw 配置过程总结 📝

一、问题诊断阶段 🔍

初始错误

⚠️ Agent failed before reply: No API key found for provider "anthropic"

• 系统找不到 Anthropic API 密钥
• 默认在寻找 main agent 的配置

查看现有 agents

openclaw agents list

结果显示只有 main agent，之前配置的 czdzl 没有成功创建。

二、创建新 Agent 🆕

1. 创建名为 czdzl 的 agent

openclaw agents add czdzl

2. 配置认证方式

出现选项：Z.AI auth method

• 选择：Coding-Plan-Global（全球版）
• 或其他选项根据地域选择

3. 配置 API 密钥

出现提示：How do you want to provide this API key?

• 选择：Paste API key now（直接粘贴）
• 粘贴 Z.AI API 密钥

4. 配置完成确认

Model configured ----------------------------------+
|                                                     |
|  Default model set to zai/glm-5 for agent "czdzl".  |
|                                                     |
+-----------------------------------------------------+

三、聊天通道配置 💬

出现提示：Configure chat channels now?

• 选项：Yes / No
• 选择：No（跳过，后续可随时配置）

聊天通道选项列表：

• ✅ Telegram (Bot API) - 新手推荐
• ✅ WhatsApp (QR link)
• ✅ Discord (Bot API)
• ✅ 飞书 (Feishu/Lark)
• 以及其他20+平台

四、Web 界面访问 🌐

启动成功后显示的地址：

1. 主控制界面：http://127.0.0.1:18789/
2. Canvas画板：http://127.0.0.1:18789/__openclaw__/canvas/
3. 浏览器控制：http://127.0.0.1:18791/（需token）

五、切换 Agent 使用 🔄

方法1：切换默认 agent

openclaw agents use czdzl

方法2：直接指定 agent 运行

openclaw --agent czdzl ask "你好"

六、配置文件路径 📂

主配置目录：C:\Users\czd17\.openclaw\agents\
- main agent：C:\Users\czd17\.openclaw\agents\main\agent\
- czdzl agent：C:\Users\czd17\.openclaw\agents\czdzl\agent\
- 认证文件：auth-profiles.json

七、常见问题及解决 ❓

问题1：Agent failed before reply

错误：No API key found for provider "zai"
解决：复制配置或重新添加agent

copy C:\Users\czd17\.openclaw\agents\czdzl\agent\auth-profiles.json C:\Users\czd17\.openclaw\agents\main\agent\

问题2：切换agent不生效

# 直接指定agent运行
openclaw --agent czdzl ask "问题"

问题3：配置中断

# 重新配置
openclaw agents add czdzl
# 或按 Ctrl+C 退出，不影响已有配置

八、最终验证 ✅

命令行测试

openclaw --agent czdzl ask "你好"

Web界面测试

1. 打开 http://127.0.0.1:18789/
2. 输入消息测试对话

九、关键命令速查 📋

功能	命令
查看agents	openclaw agents list
添加agent	openclaw agents add <名称>
切换agent	openclaw agents use <名称>
指定agent运行	openclaw --agent <名称> ask "问题"
查看日志	openclaw logs --follow
查看版本	openclaw --version

十、注意事项 ⚠️

1. API密钥安全：不要分享给他人
2. 配置文件：在 .openclaw 目录下
3. 聊天通道：可后续随时配置，不影响基本使用
4. Web界面：只能本地访问（127.0.0.1）
5. agent切换：如果 use 不生效，直接用 --agent 参数

---

配置完成！现在可以通过命令行或Web界面正常使用 OpenClaw 了！ 🎉