windows下部署openclaw详细方法及错误处理办法

木梓辛铭2026-03-18 16:12

快速开始

  • windows下如何部署openclaw详细方法
  • [🎯 核心信息：OpenClaw官网入口](#🎯 核心信息：OpenClaw官网入口)
  • 本地部署
    • 基础环境准备
    • [1，换 HTTPS 拉取](#1，换 HTTPS 拉取)
    • [2，如果还是不行，用淘宝镜像强制绕过 git](#2，如果还是不行，用淘宝镜像强制绕过 git)
    • 3，我们直接用源码编译：
    • [⚠️ 备注](#⚠️ 备注)
    • 第一种
      • [📦 第一步：安装 WSL2 + Ubuntu](#📦 第一步：安装 WSL2 + Ubuntu)
        • [1.1 以管理员身份打开 PowerShell](#1.1 以管理员身份打开 PowerShell)
        • [1.2 安装 WSL2 和 Ubuntu](#1.2 安装 WSL2 和 Ubuntu)
        • [1.3 重启电脑](#1.3 重启电脑)
      • [1.4 首次启动 Ubuntu](#1.4 首次启动 Ubuntu)
      • [1.5 更新 Ubuntu 系统](#1.5 更新 Ubuntu 系统)
      • [⚙️ 第二步：在 Ubuntu 中安装编译依赖](#⚙️ 第二步：在 Ubuntu 中安装编译依赖)
      • [🧬 第三步：从源码编译 OpenClaw](#🧬 第三步：从源码编译 OpenClaw)
        • [3.1 克隆官方仓库](#3.1 克隆官方仓库)
        • [3.2 安装项目依赖](#3.2 安装项目依赖)
        • [3.3 构建 UI 界面](#3.3 构建 UI 界面)
        • [3.4 编译核心代码](#3.4 编译核心代码)
      • [# 3.5 链接 CLI 命令（全局可用）](# 3.5 链接 CLI 命令（全局可用）)
      • [🚀 最后：初始化配置（Onboarding）](#🚀 最后：初始化配置（Onboarding）)
    • 第二种
        • [第1步：安装 Git for Windows](#第1步：安装 Git for Windows)
        • [第2步：用 Git Bash 运行命令](#第2步：用 Git Bash 运行命令)
  • 配置向导逐项指引
      • [1️⃣ Install daemon?](#1️⃣ Install daemon?)
      • [2️⃣ Onboarding mode](#2️⃣ Onboarding mode)
      • [3️⃣ Model/auth provider](#3️⃣ Model/auth provider)
      • 配置通道（Channel）
      • 其他问题
      • [💡 建议](#💡 建议)
    • [🚀 配置完成后的核心命令](#🚀 配置完成后的核心命令)
    • [💡 常用命令](#💡 常用命令)
  • 模型配置
      • 这里以云百练为例：
      • [🚀 **第一步：获取百炼的 API Key**](#🚀 第一步：获取百炼的 API Key)
      • [⚙️ **第二步：在 OpenClaw 里添加阿里云百炼**](#⚙️ 第二步：在 OpenClaw 里添加阿里云百炼)
      • [✅ **第三步：重启 OpenClaw**](#✅ 第三步：重启 OpenClaw)
      • [✅ **第4步：验证**](#✅ 第4步：验证)
      • [✅ **最后**](#✅ 最后)
    • [🆓 大模型API：免费额度怎么拿？](#🆓 大模型API：免费额度怎么拿？)

windows下如何部署openclaw详细方法

🎯 核心信息：OpenClaw官网入口

资源 地址 说明
官网 https://openclaw.ai/ 认准这个，差一个字都可能是假冒网站
GitHub github.com/openclaw/openclaw 源码仓库，147k+星
文档 docs.openclaw.ai 官方部署指南
  • 安全提醒 ：OpenClaw近期有假冒网站和盗刷事件，务必认准官网，不要从第三方下载。

本地部署

基础环境准备

安装部署openclaw 之前首先要确认，有没有Git和node.js >= 22.16.0,如果已经安装可以跳过这个步骤。

Windows系统（管理员PowerShell）：

复制代码 
# 查看node版本
where node

# 安装Node.js 22.x（核心依赖）
iwr -useb https://npmmirror.com/mirrors/node/v22.10.0/node-v22.10.0-x64.msi -OutFile node-install.msi
Start-Process .\node-install.msi -Wait

# 安装Git
winget install Git.Git

# 配置国内镜像（加速）
npm config set registry https://registry.npmmirror.com

# 验证安装
node --version  # 应显示 v22.x.x 注意：OpenClaw 需要>=22.16.0

配置国内镜像（加速npm下载）

bash 复制代码 
npm config set registry https://registry.npmmirror.com

尝试 全局安装 OpenClaw

bash 复制代码 
npm install -g openclaw@latest

ps:如果出现下面这种情况，说明SSH 权限报错了，国内 Windows 用户装 OpenClaw的常见问题

复制代码 
C:\Users\****>npm install -g openclaw@latest
npm error code 128
npm error An unknown git error occurred
npm error command git --no-replace-objects ls-remote ssh://git@github.com/whiskeysockets/libsignal-node.git
npm error git@github.com: Permission denied (publickey).
npm error fatal: Could not read from remote repository.
npm error
npm error Please make sure you have the correct access rights
npm error and the repository exists.
npm error A complete log of this run can be found in: D:\1A_Vscode\Tools\nodejs\node_cache\_logs\2026-03-14T18_42_39_631Z-debug-0.log

C:\Users\****>

遇到这种情况，有3种方式可以解决：

1，换 HTTPS 拉取

bash 复制代码 
git config --global url."https://github.com/".insteadOf git@github.com:
# 重新拉取
npm install -g openclaw@latest

2，如果还是不行，用淘宝镜像强制绕过 git

bash 复制代码 
npm install -g openclaw@latest --registry=https://registry.npmmirror.com --disturl=https://npmmirror.com/mirrors/node

如果下面这种报错，看方案3.

复制代码 
C:\Users\****>npm install -g openclaw@latest --registry=https://registry.npmmirror.com --disturl=https://npmmirror.com/mirrors/node
npm warn Unknown cli config "--disturl". This will stop working in the next major version of npm.
npm error code 128
npm error An unknown git error occurred
npm error command git --no-replace-objects ls-remote ssh://git@github.com/whiskeysockets/libsignal-node.git
npm error git@github.com: Permission denied (publickey).
npm error fatal: Could not read from remote repository.
npm error
npm error Please make sure you have the correct access rights
npm error and the repository exists.
npm error A complete log of this run can be found in: D:\1A_Vscode\Tools\nodejs\node_cache\_logs\2026-03-14T18_47_28_850Z-debug-0.log

C:\Users\****>

最终解决方案

3，我们直接用源码编译：

如果上面两种都报错，可以用预编译包：由于GitHub 上最新的版本没有提供预编译的 Windows 二进制包，只有源码。OpenClaw 官方默认让用户从源码编译（或者用 npm 安装）。

⚠️ 备注

如果你在Windows原生环境，有两种解决办法

怕麻烦可以直接看 第二种

第一种

Windows + WSL2 源码编译

📦 第一步：安装 WSL2 + Ubuntu

1.1 以管理员身份打开 PowerShell

按 Win + X → 选择 "Windows PowerShell (管理员)" 或 "终端 (管理员)"

1.2 安装 WSL2 和 Ubuntu
powershell 复制代码 
# 安装 WSL 和默认 Ubuntu
wsl --install

# 如果已经装过，确保版本是 WSL2
wsl --set-default-version 2
1.3 重启电脑

安装完成后系统会提示重启，必须重启。

1.4 首次启动 Ubuntu

  • 开始菜单搜索 "Ubuntu" 打开
  • 第一次启动会要求设置用户名和密码（记住这个密码，sudo 要用）
  • 输入密码时屏幕不会显示字符，这是正常的

1.5 更新 Ubuntu 系统

bash 复制代码 
sudo apt update && sudo apt upgrade -y

⚙️ 第二步：在 Ubuntu 中安装编译依赖

在 Ubuntu 终端中执行：

bash 复制代码 
# 安装基础编译工具
sudo apt install -y git nodejs npm python3 python3-pip python3-venv build-essential curl wget

# 安装 pnpm（OpenClaw 官方推荐）
curl -fsSL https://get.pnpm.io/install.sh | sh -

# 重新加载环境变量
source ~/.bashrc

# 验证版本
node --version  # 应 ≥ v22.16.0
pnpm --version

注意：如果 Node 版本低于 22.16.0，用 nvm 升级：

bash 复制代码 
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
source ~/.bashrc
nvm install 22
nvm use 22

🧬 第三步：从源码编译 OpenClaw

3.1 克隆官方仓库
bash 复制代码 
git clone https://github.com/openclaw/openclaw.git
cd openclaw
3.2 安装项目依赖
bash 复制代码 
# 安装 Node.js 依赖（这一步会下载所有包，走 HTTPS 不走 git）
pnpm install

这一步会解决之前的问题 ：pnpm install 直接从 npm registry 下载，完全绕过 git 协议和 SSH 权限问题。

3.3 构建 UI 界面
bash 复制代码 
pnpm ui:build
3.4 编译核心代码
bash 复制代码 
pnpm build

编译完成后会生成 dist 目录，包含所有可执行文件。

# 3.5 链接 CLI 命令（全局可用）

bash 复制代码 
pnpm link --global

🚀 最后：初始化配置（Onboarding）

bash 复制代码 
openclaw onboard --install-daemon

完成后直接看第二部分 配置向导逐项指引

第二种

在 Windows 上安装 Bash（替代方案，较快但可能仍有兼容问题）

第1步：安装 Git for Windows
第2步：用 Git Bash 运行命令
  • 选一个你要放openclaw源码的文件夹进入右键 → 选择 "Git Bash Here"
  • 在弹出的 Bash 窗口中执行：
bash 复制代码 
# 克隆官方仓库
git clone https://github.com/openclaw/openclaw.git
# 进入对应的项目目录
cd openclaw
#安装项目依赖
#安装 Node.js 依赖（这一步会下载所有包，走 HTTPS 不走 git）
pnpm install
# 构建UI
pnpm ui:build
# 编译
pnpm build
# 添加全局
pnpm link --global
# 验证
openclaw --version
# ps: 如果没有显示版本，看下面这个

# 直接用 Node 运行 entry.js
node dist/entry.js --version
# 应该会输出版本号。
# 设置别名（方便使用）
echo 'alias openclaw="node /f/openclaw/openclaw/dist/entry.js"' >> ~/.bashrc
source ~/.bashrc
# 验证别名
openclaw --version
# 最后启动配置向导
openclaw onboard --install-daemon

配置向导逐项指引

1️⃣ Install daemon?

复制代码 
? Would you like to install the OpenClaw daemon? (Y/n)

输入 ：y（回车）

安装后台服务，这样 OpenClaw 可以开机自启，不用每次手动启动。

2️⃣ Onboarding mode

复制代码 
? Onboarding mode (Use arrow keys)
  QuickStart
  Custom

用上下箭头选择 ：QuickStart（回车）

快速开始，适合个人使用。

3️⃣ Model/auth provider

复制代码 
? Choose a model/auth provider (Use arrow keys)
  OpenAI
  Anthropic
  Azure
  Google AI
  Alibaba Cloud (Bailian)
  ... (其他)
  None (I'll configure later)

根据你情况选：

  • 如果你有 API Key（比如 OpenAI、阿里云百炼等），就选对应的
  • 如果暂时没有 ，选 None (I'll configure later)（回车）

这一步最关键，没有 API Key 也可以先选 None，以后随时可以配置。

配置通道（Channel）

复制代码 
? Which channels would you like to enable? (Space to select, Enter to continue)
  [ ] Web UI (Dashboard)
  [ ] Command Line
  [ ] Slack
  [ ] Discord
  ...

至少选上 Web UI（空格键选中，回车继续）

其他问题

  • 是否启用 Tailscale 远程访问 → 选 No（先本地用）
  • 是否安装系统服务 → 选 Yes（开机自启）

全部选完后，会回到命令行提示符。

复制代码 
*  Select channel (QuickStart)
|  > Telegram (Bot API) (recommended · newcomer-friendly)
|    WhatsApp (QR link)
|    Discord (Bot API)
|    IRC (Server + Nick)
|    Google Chat (Chat API)
|    Slack (Socket Mode)
|    Signal (signal-cli)
|    iMessage (imsg)
|    LINE (Messaging API)
|    Feishu/Lark (飞书)
|    Nostr (NIP-04 DMs)
|    Microsoft Teams (Bot Framework)
|    Mattermost (plugin)
|    Nextcloud Talk (self-hosted)
|    Matrix (plugin)
|    BlueBubbles (macOS app)
|    Zalo (Bot API)
|    Zalo (Personal Account)
|    Synology Chat (Webhook)
|    Tlon (Urbit)
|    Skip for now

这一步是让你选择用什么方式与OpenClaw对话 。直接选最后一项 Skip for now，然后回车。

复制代码 
o  Select channel (QuickStart)
|  Skip for now
Updated ~\.openclaw\openclaw.json
Workspace OK: ~\.openclaw\workspace
Sessions OK: ~\.openclaw\agents\main\sessions
|
o  Web search ----------------------------------------+
|                                                     |
|  Web search lets your agent look things up online.  |
|  Choose a provider and paste your API key.          |
|  Docs: https://docs.openclaw.ai/tools/web           |
|                                                     |
+-----------------------------------------------------+
|
*  Search provider
|  > Brave Search (Structured results · country/language/time filters)
|    Gemini (Google Search)
|    Grok (xAI)
|    Kimi (Moonshot)
|    Perplexity Search
|    Skip for now
---

这个是 OpenClaw 配置向导的最后一步------设置联网搜索功能。

  • 如果需要 ：比如你想做紧跟热点的漫剧，需要让AI分析最新的抖音/红果热榜、追踪流行梗，或者查找特定资料，那么联网搜索就很有用。
  • 如果暂时不需要：如果你只想让AI基于已有的知识和你的本地模型（GLM-4.7-Flash能力很强）来创作，或者主要做非时效性的内容，那完全可以跳过，以后随时可以开启。

意思就是你是否要让你的 AI 智能体（运行在 OpenClaw 里的模型）具备联网搜索能力。这样，当它需要查找实时信息、最新资讯或验证某些事实时，就可以上网查询。

然后下面的选项是OpenClaw 的 技能（Skills）。你可以把它们想象成是给 AI 智能体安装的各种"App"或"插件"。装上某个技能，你的 AI 就能干对应的那件事了。

复制代码 
*  Install missing skill dependencies
|  [•] Skip for now (Continue without installing dependencies)
|  [ ] � 1password
|  [ ] � blogwatcher
|  [ ] � blucli
|  [ ] � camsnap
|  [ ] � clawhub
|  [ ] � eightctl
|  [ ] ✨ gemini
|  [ ] � gifgrep
|  [ ] � github
|  [ ] � gog
|  [ ] � goplaces
|  [ ] � himalaya
|  [ ] � mcporter
|  [ ] � nano-banana-pro
|  [ ] � nano-pdf
|  [ ] � obsidian
|  [ ] � openai-whisper
|  [ ] � openhue
|  [ ] � oracle
|  [ ] � ordercli
|  [ ] � sag
|  [ ] � songsee
|  [ ] � sonoscli
|  [ ] � summarize
|  [ ] � wacli
|  [ ] � xurl
---  Please select at least one option.
   Press  space  to select,  enter  to submit

ps: 如果你选择了以后回车没响应，直接可以Ctrl + C退出，这一步无所谓，到现在基本引导操作已经完了，可以直接启动了

bash 复制代码 
# 安装网关服务
openclaw gateway install
# 启动网关
openclaw gateway start
# 启动界面
openclaw dashboard

浏览器打开 http://localhost:18789，就能看到界面了。

技能讲解：

技能名称 功能简述 适合安装的人群/场景
1password 从 1Password 密码管理器中读取密码和密钥。 有 1Password 会员、需要AI管理高安全凭证的用户。
blogwatcher 监控你关注的博客或 RSS 源，有新内容时通知你。 内容创作者、需要追踪特定网站更新的研究者。
blucli OpenClaw 官方的技能市场命令行客户端，用来搜索和安装新技能。 所有用户，这是获取更多技能的入口。
camsnap 连接并抓取电脑摄像头的画面或视频流。 有家庭监控、拍照自动化需求的用户。
clawhub 功能类似 blucli，也是用来管理和安装技能的"技能市场"。 所有用户。
eightctl 控制 Eight Sleep 智能床垫（调节温度、查看睡眠数据等）。 拥有 Eight Sleep 床垫的智能家居用户。
gemini 允许你的AI调用 Google 的 Gemini 大模型来完成任务。 想用 Google Gemini 模型能力的开发者。
gifgrep 根据关键词搜索并下载GIF动图。 内容创作者、聊天机器人制作者。
github 操作 GitHub，比如创建 Issue、发起 PR、查看代码仓库等。 开发者、技术产品经理必备。
gog 集成 GOG 游戏平台，可能用于自动化游戏下载或更新。 GOG 游戏平台的重度用户。
goplaces 获取 Google 地图上地点的详细信息（评分、评论、地址等）。 开发地图相关应用或有本地生活服务需求的用户。
himalaya 一个终端邮件客户端，让 AI 能帮你读、写、搜索邮件。 喜欢在终端处理邮件、想用 AI 辅助管理邮件的用户。
mcporter 可能与 《我的世界》 游戏服务器端口转发或管理有关。 《我的世界》游戏服务器管理员。
nano-banana-pro 一个名字有点搞笑的技能，可能用于图像生成或编辑。 对图像生成有需求的创作者（需配合其他AI模型）。
nano-pdf 处理 PDF 文档，比如提取文字、合并、转换格式等。 经常需要阅读或处理文档的知识工作者。
obsidian 与 Obsidian 笔记软件深度集成，实现笔记的查询、自动整理、生成知识大纲。 Obsidian 的重度用户，想要打造"第二大脑"的知识管理者。
openai-whisper 使用 OpenAI 的 Whisper 模型（本地运行，免费）将语音转为文字。 有语音输入、会议记录需求的用户。
openhue 控制飞利浦 Hue 系列智能灯泡（开关、调色、调亮度）。 家里有飞利浦 Hue 智能照明系统的用户。
oracle 连接并查询 Oracle 数据库。 数据库管理员或需要与 Oracle 数据库交互的开发者。
ordercli 点外卖用的（好像是集成 Foodora 平台）。 想体验用 AI 点外卖的用户（国内可能用不了）。
sag 名称比较模糊，可能是某个私有项目或实验性功能的缩写。 普通用户不建议安装。
songsee 音频频谱可视化工具，可以把声音变成动态图像。 音乐爱好者、视频创作者（制作音频可视化效果）。
sonoscli 控制 Sonos 无线音响系统（播放音乐、调节音量、切换歌曲）。 家里有 Sonos 音响的用户。
summarize 自动提取网页、PDF、视频、播客等内容的文字摘要。 所有用户，信息提炼神器，大幅提升效率。
wacli 通过命令行发送和管理 WhatsApp 消息。 日常工作需要大量使用 WhatsApp 进行沟通的用户。
xurl 一个非常轻量的 HTTP 请求工具，可以用命令行发送网络请求。 开发者或需要调试API的用户（功能独立，影响小）。

💡 建议

  1. 核心必备 ：clawhub 或 blucli（技能市场）和 summarize（总结神器）是非常值得装的。
  2. 按需选择 ：其他技能，等你确实有明确需求时（比如"我想让AI帮我管理GitHub"），再用 clawhub install <技能名> 单独安装就行。现在不用一次性全装。
  3. 注意避坑 ：有些技能配置复杂，新手容易搞崩环境。例如 browser、shell、file_system 相关的技能需要谨慎。你列表里暂时没有这些高危技能，但以后安装时可以参考的建议。

🚀 配置完成后的核心命令

命令 作用
openclaw gateway start 启动服务
openclaw gateway stop 停止服务
openclaw gateway status 查看服务状态
openclaw dashboard 打开 Web 界面
openclaw config set model <模型名> 切换默认模型
openclaw skill install <技能名> 安装别人开发的技能
openclaw skill create 创建自己的技能

💡 常用命令

命令 作用
openclaw gateway status 查看网关状态
openclaw gateway stop 停止网关
openclaw gateway start 启动网关
openclaw dashboard 打开 Web 界面
clawhub search <关键词> 搜索技能
clawhub install <技能名> 安装技能

模型配置

这里以云百练为例：

🚀 第一步：获取百炼的 API Key

  1. 登录 阿里云百炼控制台。
  2. 在左侧菜单栏找到 "API-KEY 管理"。
  3. 点击 "创建 API-KEY" ，创建好后把它复制下来（一串 sk- 开头的字符）。这就是 OpenClaw 连接云端大模型的"钥匙"。

⚙️ 第二步：在 OpenClaw 里添加阿里云百炼

  1. 用记事本打开 OpenClaw 的配置文件（在 Git Bash 里运行这个命令）：

    bash 复制代码 
    notepad ~/.openclaw/openclaw.json

  2. 在打开的 openclaw.json 文件里，找到 "models" 这一大块，然后在它的 "providers" 里面，添加一个阿里云的配置。你可以直接把下面这段代码复制进去（记得把 "apiKey" 后面的内容换成你自己的）：

    json 复制代码 
    "aliyun_bailian": {
    "baseUrl": "https://dashscope.aliyuncs.com/compatible-mode/v1",
    "apiKey": "sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", // 换成你真正的API Key
    "api": "openai-completions",
    "models": [
        { "id": "deepseek-v3", "name": "DeepSeek-V3" }
        // 如果你以后还想用通义千问，可以继续加，比如：
        // { "id": "qwen-max", "name": "通义千问-Max" }
    ]
}

  3. 修改默认模型 ，把你刚才添加的阿里云模型设为默认。在文件里找到 "agents" -> "defaults" -> "model" -> "primary" 这一行，把它的值改成 "aliyun_bailian/模型名称"。修改后看起来像这样：

    json 复制代码 
    "model": {
    "primary": "aliyun_bailian/模型名称"
}

  4. 保存文件（Ctrl+S），然后关闭记事本。

✅ 第三步：重启 OpenClaw

bash 复制代码 
openclaw gateway restart

✅ 第4步：验证

bash 复制代码 
openclaw models list

✅ 最后

bash 复制代码 
openclaw gateway start

🆓 大模型API：免费额度怎么拿？

OpenClaw需要大模型驱动，阿里云百炼给新用户90天免费额度。

步骤 操作
1 访问 阿里云百炼控制台
2 开通服务，完成实名认证
3 进入「密钥管理」→「创建Access Key」
4 复制保存Access Key ID和Secret
5 进入「费用管理」→「消费限额」，设置每月最大消费额度

最后：养虾很费米,大家注意自己的钱包。

如果对你有帮助，点个赞支持一下吧！

相关推荐
John_ToDebug2 小时前
死锁案例：UI 线程阻塞等待跨进程 COM 注入
c++·windows·笔记
Aurorar0rua3 小时前
CS50 x 2024 Notes Scratch - 07
学习方法
oscar9994 小时前
Memurai：Redis官方认可的Windows原生解决方案
数据库·windows·redis
暖阳常伴6 小时前
Windows安装MongoDB
数据库·windows·mongodb
星辰引路-Lefan6 小时前
全平台 Docker 部署 CPA(CLIProxyAPI Plus) 灵活定制指南 (Linux/Windows)——接入Codex
linux·windows·docker·ai·ai编程
June bug7 小时前
ISTQB CT-GenAI v1.0 K1/K2/K3 考点清单
经验分享·职场和发展·学习方法
YQ_018 小时前
Windows + Ubuntu 双系统安装：不使用 GRUB，直接在开机时选择系统
linux·windows·ubuntu
小王不爱笑1328 小时前
Java List 集合全面解析：ArrayList、LinkedList 与 Vector 的深度对比
java·windows·list
※※冰馨※※8 小时前
【QT】System error #1455: 页面文件太小，无法完成操作
开发语言·windows·qt
热门推荐
01GitHub 镜像站点02Qwen3.5 开源全解析：从 0.8B 到 397B，代际升级 + 全场景选型指南03OpenClaw 使用和管理 MCP 完全指南04UV安装并设置国内源05OpenClaw Control UI安全上下文访问配置06Claude Code + GLM4.7 避坑指南：解决 Unable to connect to Anthropic services07OpenClaw macOS 完整安装与本地模型配置教程（实战版）08本地部署 OpenClaw + DeepSeek-R1 完全指南09小黑课堂计算机二级WPSoffice题库软件下载安装教程（2026年3月最新版）10AI 编程三剑客：Spec-Kit、OpenSpec、Superpowers 深度对比与实战指南