Windows 部署OpenCode指南v4.9

# Windows 环境下部署 OpenClaw 指南V2.0
该软件不必要在公司环境安装，上传仅供学习！
请不要在云电脑安装该项目，经测试会卡顿




Windows 上装 OpenClaw 有两种方式，云电脑不支持再虚拟化，需要用第一种。本地电脑有需要可用第二种，简单直接。

**原生 Windows（PowerShell 直接装）**——不用装虚拟化，装完就在 Windows 环境里跑。如果你想让 OpenClaw 操作 Windows 桌面上的东西（比如浏览器、文件管理器），得选这个。代价是环境坑多。

**WSL2（在 Windows 里跑个 Linux）**——OpenClaw 官方文档也推荐这种。装完跟 Linux 一模一样，基本不踩坑。但多了一层虚拟化，而且 WSL2 默认吃 1-2GB 内存，8GB 以下的机器可能有点紧。

------

## 一、  准备工作

### 1.1  环境准备

- Windows 10（1903 以上）或 Windows 11，64 位
- 至少 2GB 磁盘空间
- 网络能访问 npm 和 GitHub
- 一个大模型的 API Key

### 1.2  下载必要软件

+ ####  Node.js 下载地址

官网下载地址：https://nodejs.org/zh-cn/download

内网下载地址：

建议选择 LTS 版本（长期支持版），更适合生产环境使用。OpenClaw 要求 Node.js 22 或更高。

+ #### Git 下载地址

官网下载地址：https://registry.npmmirror.com/binary.html?path=git-for-windows

内网下载地址：

国内用户推荐使用 NPM Mirror 提供的镜像源，下载速度更快。

+ #### C++ 编译工具（可选安装）

OpenClaw 有些依赖要编译原生模块（sharp 做图像处理、node-pty 做终端模拟），没有 C++ 编译环境会报 `node-gyp rebuild failed`。

如果装 Node.js 的时候勾了自动安装工具，这步跳过。没勾的话，去装 [Visual Studio Build Tools](https://visualstudio.microsoft.com/visual-cpp-build-tools/?ref=tbbbk.com)，安装的时候选这三个：

- "使用 C++ 的桌面开发"工作负载
- MSVC v143 编译器
- Windows 10/11 SDK

安装包 2-3GB，要等一会。

### 1.3  设置 PowerShell 执行策略

Windows 默认会阻止脚本执行，需要先修改执行策略：

```
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser -Force
```

**说明**: `RemoteSigned` 允许本地执行的脚本，对于远程下载的脚本需要签名。这是平衡安全性和可用性的最佳选择。

------



## 二、  环境安装

### 2.1  安装 Node.js

运行下载好的 Node.js 安装包，一路点击 “Next” 即可完成安装。

安装完成后，验证安装是否成功：

```
node --version
npm --version
```

应该能输出类似：

```
v24.x.x
11.x.x
```

### 2.2  安装 Git

运行 Git 安装包，使用默认配置即可。安装完成后验证：

```
git --version
```

------



## 三、  指定工作区目录（可选）

> 💡 **重要**：此处步骤是更改OpenClaw安装目录，如不做环境变量配置，默认安装在C盘，建议更改到D盘
>
> 💡 **重要**：所有环境变量的值按你自己喜好来定

首先在 D 盘创建 OpenClaw 的工作区目录：

```
#手动或者通过mkdir命令都可以，这个目录是用户自定义的 OpenClaw 的工作空间，指定后会自动在这里存储数据。
mkdir D:\openclaw\workspace
```

### 3.1  配置环境变量

在安装 OpenClaw 之前，**配置环境变量**目的是确保 OpenClaw 能按用户指定的目录生成相关的配置文件和数据目录。

### 3.2  打开系统环境变量设置

1. 按 `Win + R` 键，输入 `sysdm.cpl` 并回车
2. 点击 **高级** 选项卡
3. 点击 **环境变量** 按钮

### 3.3  添加用户环境变量

在 **用户变量** 区域点击 **新建**，添加以下四个环境变量：

**变量 1：OPENCLAW_HOME**

| 项     | 值              |
| ------ | --------------- |
| 变量名 | `OPENCLAW_HOME` |
| 变量值 | `D:\openclaw`   |

**变量 2：OPENCLAW_WORKSPACE**

| 项     | 值                      |
| ------ | ----------------------- |
| 变量名 | `OPENCLAW_WORKSPACE`    |
| 变量值 | `D:\openclaw\workspace` |

**变量 3：OPENCLAW_CONFIG_PATH**

| 项     | 值                          |
| ------ | --------------------------- |
| 变量名 | `OPENCLAW_CONFIG_PATH`      |
| 变量值 | `D:\openclaw\openclaw.json` |

**变量 4：OPENCLAW_STATE_DIR**

| 项     | 值                   |
| ------ | -------------------- |
| 变量名 | `OPENCLAW_STATE_DIR` |
| 变量值 | `D:\openclaw`        |

### 3.4  验证环境变量

点击 **确定** 保存所有设置。

关闭并重新打开 Git Bash，验证环境变量是否生效：

```
echo $OPENCLAW_HOME
echo $OPENCLAW_WORKSPACE
echo $OPENCLAW_CONFIG_PATH
echo $OPENCLAW_STATE_DIR
```



## 四、  OpenClaw 安装

### 4.1  标准安装方式

在 Git Bash 或 PowerShell 中执行：

```
npm install -g openclaw@latest
```

安装过程耗时较久，无报错，可无视提醒。

```shell
PS D:\openclaw\workspace> npm install -g openclaw@latest
npm warn deprecated inflight@1.0.6: This module is not supported, and leaks memory. Do not use it. Check out lru-cache if you want a good and tested way to coalesce async requests by a key value, which is much more comprehensive and powerful.
npm warn deprecated node-domexception@1.0.0: Use your platform's native DOMException instead
npm warn deprecated gauge@3.0.2: This package is no longer supported.
npm warn deprecated are-we-there-yet@2.0.0: This package is no longer supported.
npm warn deprecated rimraf@3.0.2: Rimraf versions prior to v4 are no longer supported
npm warn deprecated glob@7.2.3: Old versions of glob are not supported, and contain widely publicized security vulnerabilities, which have been fixed in the current version. Please update. Support for old versions may be purchased (at exorbitant rates) by contacting i@izs.me
npm warn deprecated npmlog@5.0.1: This package is no longer supported.
npm warn deprecated tar@6.2.1: Old versions of tar are not supported, and contain widely publicized security vulnerabilities, which have been fixed in the current version. Please update. Support for old versions may be purchased (at exorbitant rates) by contacting i@izs.me

added 673 packages in 16m

101 packages are looking for funding
  run `npm fund` for details
```

### 4.2  跳过编译安装（可选）

如果遇到编译错误，可以使用以下命令跳过编译步骤：

```
npm install -g openclaw@latest --ignore-scripts --no-optional --force
```

**参数说明**:

- `--ignore-scripts`: 跳过安装脚本
- `--no-optional`: 不安装可选依赖
- `--force`: 强制安装

### 4.3  验证安装

```
openclaw --version
```

------

## 五、  运行配置向导



### 5.1  初始化 OpenClaw

使用 `openclaw onboard` 命令启动交互式配置向导：

```
openclaw onboard --install-daemon
```

> 💡 **参数说明**：
>
> - `--install-daemon`: 安装为系统服务
> - 如未配置环境变量，可使用`--workspace D:\software\openclaw\workspace` 参数指定工作空间目录

### 5.2  确认安装

向导启动后，第一个配置界面默认选择 **Yes**，直接按回车继续。

```shell
*  I understand this is personal-by-default and shared/multi-user use requires lock-down. Continue?
|    Yes / > No
```

### 5.3  选择配置模式

选择 **QuickStart** 快速开始模式，按回车继续。

```
*  Setup mode
|  > QuickStart (Configure details later via openclaw configure.)
|    Manual
```

### 5.4  选择AI模型

选择底层AI模型，这里选择自定义提供商（任何兼容 OpenAI 或 Anthropic 的端点）

```
 Model/auth provider
|    Anthropic
|    Arcee AI
|    BytePlus
|    Chutes
|    Cloudflare AI Gateway
|    Copilot Proxy
|  > Custom Provider (Any OpenAI or Anthropic compatible endpoint)
|    DeepSeek
|    Fireworks
|    Gemini CLI OAuth
|    GitHub Copilot
|    Google
|    Hugging Face
|    Kilo Gateway
|    LiteLLM
|    LM Studio
|    Microsoft Foundry
|    MiniMax
|    Mistral AI
|    Moonshot AI (Kimi K2.5)
|    Ollama
|    OpenAI
|    OpenAI Codex
|    OpenCode
|    OpenRouter
|    Qianfan
|    Qwen Cloud
|    SGLang
|    StepFun
|    Synthetic
|    Together AI
|    Venice AI
|    Vercel AI Gateway
|    vLLM
|    Volcano Engine
|    xAI (Grok)
|    Xiaomi
|    Z.AI
|    Skip for now
```

### 5.5  配置自定义的模型信息

+ 输入API Base URL：`https://api.aiguoguo199.com/v1`，

+ 回车，进入下一步，复制粘贴后续提供的API Key，

+ 回车，根据选定的模型，确定模型兼容性的选择，默认选择 > OpenAI-compatible (Uses /chat/completions)

> **选择「兼容 OpenAI」的情况：**
>
> - 如果你使用的是 **Ollama**（默认地址通常就是你刚才填的 `11434`）。
> - 如果你使用的是 **DeepSeek**、**月之暗面 (Kimi)**、**通义千问**、**LocalAI**、**LM Studio**。
> - 如果你使用的是真正的 **OpenAI (ChatGPT)**。
> - *大多数国产大模型和本地推理工具都支持这个格式。*
>
> **选择「兼容 Anthropic」的情况：**
>
> - 如果你直接使用 **Claude** 的官方 API（地址通常是 `https://api.anthropic.com`）。
> - 如果你使用的转发服务明确说明只支持 Claude 原生数据格式。

+ 回车，输入模型ID，默认可以选择填写`gpt-5.4`
+ 回车，输入Endpoint ID，此处可以默认

> 这里的Endpoint ID
>
> **是你自定义的：** 你可以输入任何好记的字符串，比如 `ollama-local`、`my-deepseek` 或 `work-gpt4`。
>
> **引用标识：** 在你后续使用 OpenClaw 聊天或在配置文件中指定某个特定模型时，你需要输入这个 ID 而不是一长串 API 地址。
>
> **唯一性：** 如果你配置了多个后端，每个后端的 ID 必须是唯一的。
>
> **格式要求：** 尽量使用**小写字母、数字和连字符（-）**，不要包含空格或特殊字符，以防在 Windows 命令行环境下解析出错。

+ 回车，输入Model alias (optional)，此处可以输入gpt5.4

> **Model Alias**（模型别名）是给你的 AI 模型起的一个“绰号”或“简写”。
>
> 它的核心作用是**简化指令**。当你以后在命令行或应用中调用 OpenClaw 时，不需要输入长串的模型全名，只需要输入这个简单的别名。
>
> 在 AI 领域，模型的正式名称通常很长且难以记忆，例如：
>
> - **正式名称：** `llama3.1:8b-instruct-q8_0` 或 `gpt-4-turbo-2024-04-09`
> - **别名：** `llama3` 或 `gpt4`
>
> 通过设置别名，你只需要对着 OpenClaw 说“用 **llama3** 帮我写段代码”，而不是输入那一串复杂的版本号。

```
o  Model/auth provider
|  Custom Provider
|
o  API Base URL
|  https://api.aiguoguo199.com/v1
|
*  How do you want to provide this API key?
|  > Paste API key now (Stores the key directly in OpenClaw config)
|    Use external secret provider
|
o  API Key (leave blank if not required)
|  sk-k7lxa1Ygwy7RwPEn0N71oJS15A9NbD3El6qsvqYwaasHNQml
|
*  Endpoint compatibility
|  > OpenAI-compatible (Uses /chat/completions)
|    Anthropic-compatible
|    Unknown (detect automatically)
—
o  Model ID
|  gpt-5.4
|
o  Verification successful.
|
o  Endpoint ID
|  custom-api-aiguoguo199-com
|
o  Model alias (optional)
|  gpt5.4
Configured custom provider: custom-api-aiguoguo199-com/gpt-5.4
```

### 5.6  选择聊天平台

因本地部署使用，不需要经过平台，直接选择 Skip for now (You can add channels later via `openclaw channels add`)

```
*  Select channel (QuickStart)
|    Feishu/Lark (飞书)
|    Google Chat (Chat API)
|    Nostr
|    Microsoft Teams (Bot Framework)
|    Mattermost (plugin)
|    Nextcloud Talk (self-hosted)
|    Matrix (plugin)
|    BlueBubbles (macOS app)
|    LINE (Messaging API)
|    Zalo (Bot API)
|    Zalo (Personal Account)
|    Synology Chat (Webhook)
|    Tlon (Urbit)
|    Discord (Bot API)
|    iMessage (imsg)
|    IRC (Server + Nick)
|    QQ Bot
|    Signal (signal-cli)
|    Slack
|    Telegram (Bot API)
|    Twitch (Chat)
|    WhatsApp (QR link)
|  > Skip for now (You can add channels later via `openclaw channels add`)
```

### 5.7  配置web搜索（可选）

可以先跳过，选择`Skip for now (Configure later with openclaw configure --section web)`，后续如有需要，可注册 Tavily Search账号，每月有免费额度

```
|
o  Web search -----------------------------------------------------------------+
|                                                                              |
|  Web search lets your agent look things up online.                           |
|  Choose a provider. Some providers need an API key, and some work key-free.  |
|  Docs: https://docs.openclaw.ai/tools/web                                    |
|                                                                              |
+------------------------------------------------------------------------------+
|
*  Search provider
|    Brave Search
|    Exa Search
|    Firecrawl Search
|    Gemini (Google Search)
|    Grok (xAI)
|    Kimi (Moonshot)
|    Ollama Web Search
|    Perplexity Search
|    SearXNG Search
|    Tavily Search
|  > Skip for now (Configure later with openclaw configure --section web)
```

### 5.8  配置Skills（可选）

配置可选的技能插件，可根据需要选择，默认选择跳过

> 技能随时可以在安装完成后，通过修改配置文件或后续命令单独开启
>
> 每一个小图标代表一个功能模块：
>
> - **`🐙 github` / `🧩 gh-issues`**: 帮你管理代码仓库、查 issue。
> - **`💎 obsidian`**: 操作你的本地 Obsidian 笔记。
> - **`🎤 openai-whisper`**: 把语音转换成文字。
> - **`📜 session-logs`**: 自动整理你的对话记录。
> - **`🎬 video-frames`**: 处理视频帧数据。
> - ........具体可自行搜索

```
o  Skills status -------------+
|                             |
|  Eligible: 6                |
|  Missing requirements: 38   |
|  Unsupported on this OS: 8  |
|  Blocked by allowlist: 0    |
|                             |
+-----------------------------+
|
o  Configure skills now? (recommended)
|  Yes
|
*  Install missing skill dependencies
|  [•] Skip for now (Continue without installing dependencies)
|  [ ] 🔐 1password
|  [ ] 📰 blogwatcher
|  [ ] 🫐 blucli
|  [ ] 📸 camsnap
|  [ ] 🧩 clawhub
|  [ ] 🛌 eightctl
|  [ ] ✨ gemini
|  [ ] 🧩 gh-issues
|  [ ] 🧲 gifgrep
|  [ ] 🐙 github
|  [ ] 🎮 gog
|  [ ] 📍 goplaces
|  [ ] 📧 himalaya
|  [ ] 📦 mcporter
|  [ ] 📄 nano-pdf
|  [ ] 💎 obsidian
|  [ ] 🎤 openai-whisper
|  [ ] 💡 openhue
|  [ ] 🧿 oracle
|  [ ] 🛵 ordercli
|  [ ] 🔊 sag
|  [ ] 📜 session-logs
|  [ ] 🌊 songsee
|  [ ] 🔊 sonoscli
|  [ ] 🧾 summarize
|  [ ] 📋 trello
|  [ ] 🎬 video-frames
|  [ ] 📱 wacli
|  [ ] 🐦 xurl
```

### 5.9  其他API配置（可选）

其他可选的API配置，默认全部选择NO跳过，按回车继续

> - **goplaces**: 让 AI 能查 **Google 地图**（找餐厅、看地址）。
> - **notion**: 让 AI 能读写你的 **Notion 笔记**。
> - **openai-whisper**: 让 AI 能把**语音转成文字**。
> - **sag (ElevenLabs)**: 让 AI 用超真实的声音**开口说话**。
>
> 均需额外付费获取API key

```
o  Set GOOGLE_PLACES_API_KEY for goplaces?
|  No
|
o  Set NOTION_API_KEY for notion?
|  No
|
o  Set OPENAI_API_KEY for openai-whisper-api?
|  No
|
o  Set ELEVENLABS_API_KEY for sag?
|  No
```

### 5.10  配置HOOK（钩子）

默认选择 command-logger，session-memory，继续按回车完成剩余配置步骤

> - **`boot-md`**: 启动时自动生成一份关于系统状态的 Markdown 文档。
> - **`bootstrap-extra-files`**: 启动时自动检查并补齐缺少的辅助文件。
> - **`command-logger`**: **（常用）** 记录你在 OpenClaw 里执行过的所有命令，方便以后复盘。
> - **`session-memory`**: **（推荐）** 让 AI 更好地“记住”你们之前的对话上下文，防止它聊着聊着就忘了前面的事。

```
*  Enable hooks?
|  [ ] Skip for now
|  [ ] 🚀 boot-md
|  [ ] 📎 bootstrap-extra-files
|  [+] 📝 command-logger (Log all command events to a centralized audit file)
|  [+] 💾 session-memory (Save session context to memory when /new or /reset command is issued)
```

### 5.11  网关配置

此时，主要服务均已完成设置，等待网关检查后选择重启，完成安装

如有提示Windows Defender 防火墙阻止部分功能，需要**点击允许访问**



## 六、  验证安装

### 6.1  验证安装，检查版本

```
openclaw --version
```

6.2  网页版访问

安装完成后，获取访问 Dashboard 的地址和 Token：

```
openclaw dashboard --no-open
```

这个命令会输出包含 Token 的访问地址，可复制到浏览器内打开

------

## 高级配置

### 1. 启动服务

#### 重启服务

```
openclaw gateway restart
```

#### 以调试模式启动

```
openclaw gateway --port 18789 --verbose
```

**参数说明**:

- `--port`: 指定服务端口（默认为 18789）
- `--verbose`: 启用详细日志输出

### 2. 配置文件位置

编辑 OpenClaw 配置文件：

```
openclaw config
```

或者手动编辑配置文件（通常位于 `~/.openclaw/config.json`）。

### 3. 配置工具权限

在配置文件中添加以下权限设置， granting 所有工具的完全访问权限：

```
{
  "tools": {
    "profile": "full",
    "allow": [
      "group:all"
    ]
  }
}
```

------

## 系统维护

### 检查与修复

如果遇到问题，可以使用诊断工具：

```
openclaw doctor --fix
```

这个命令会自动检测常见问题并提供修复建议。

### 查看状态

```
openclaw status
```

------

## 故障排查

### 问题 1: 全局安装目录问题

如果遇到安装错误或权限问题，可以尝试切换全局安装目录：

```
# 创建新的全局模块目录
mkdir C:\node-modules

# 设置全局模块路径
npm config set prefix C:\node-modules

# 设置全局缓存路径
npm config set cache C:\node-cache

# 添加到环境变量
$env:Path += ";C:\node-modules\node_modules\bin"
```

**注意**: 修改后需要重新打开 PowerShell 窗口使环境变量生效。

### 问题 2: 编译错误

如果在安装过程中遇到编译相关的错误（如缺少 C++ 编译器等），需要：

1. **安装 Visual Studio**:

   - 下载 Visual Studio Community（免费）
   - 安装时勾选 “C++桌面开发” 工作负载

2. **安装 Windows Build Tools**:

   ```
   npm install -g windows-build-tools
   ```

### 问题 3: 端口被占用

如果 18789 端口被占用，可以更换其他端口：

```
openclaw gateway --port 18790 --verbose
```

### 问题 4: 服务无法启动

尝试以下步骤：

1. 检查防火墙设置，确保相应端口已开放
2. 查看日志文件获取详细错误信息
3. 使用 `openclaw doctor --fix` 自动修复
4. 重启服务：`openclaw gateway restart`

------

## 常见问题 FAQ

### Q: 为什么安装这么慢？

A: 建议配置国内镜像源，或使用 `--ignore-scripts` 选项跳过编译。

### Q: Dashboard 打不开？

A: 检查服务是否在运行，确认端口正确，查看防火墙设置。

### Q: 如何卸载 OpenClaw？

A: 运行 `npm uninstall -g openclaw` 即可卸载。

### Q: 如何升级 OpenClaw？

A: 运行 `npm install -g openclaw@latest` 升级到最新版本。

------

## 总结

恭喜！你已经完成了 OpenClaw 的安装和基础配置。接下来可以：

1. 访问 Dashboard 开始使用
2. 配置更多的集成和插件
3. 探索 OpenClaw 的高级功能

如有问题，请使用 `openclaw doctor --help` 获取更多帮助。

Windows 环境下部署 Open Code完整指南V4.9

一、前言

Windows 环境下部署 OpenClaw 指南V2.0