OpenClaw 下载安装与 API 配接教程（Windows）

本教程基于 OpenClaw 官方文档整理，面向 Windows 原生环境（含 WSL2 说明）。
内容涵盖：环境要求、两种安装路径、首次配置、常用 API（DeepSeek / Qwen / OpenAI 兼容）配接，以及常见问题排查。

一、OpenClaw 是什么
二、安装前的准备
三、方式一：Windows 原生安装（推荐快速上手）
[先装 Node.js（手动方式）](#0.先装 node.js (手动方式))
四、方式二：WSL2 + Ubuntu 安装（更稳定，推荐进阶）
五、首次配置（onboard）
六、API 配接（让 OpenClaw 接入大模型）
七、配置文件 openclaw.json 详解
八、常用命令速查
九、常见问题排查
十、卸载与更新

一、OpenClaw 是什么

OpenClaw 是一个开源的 AI 助手网关（Gateway）与 Agent 运行时。它连接大模型（LLM）、各种聊天渠道（飞书、微信/WhatsApp/Telegram/Discord 等）和本机工具，让你拥有一个能主动干活、跨平台的个人 AI 助理。

核心组成：

Gateway：常驻后台服务，负责路由消息、加载配置、管理会话。
CLI：命令行工具（openclaw ...），用于安装、配置、监控。
Channels：渠道（如飞书 Feishu），让机器人接入聊天平台。
Providers：模型供应商（DeepSeek、Qwen、OpenAI、Anthropic 等）。

二、安装前的准备

系统要求

项目	要求
操作系统	macOS / Linux / Windows（原生 + WSL2 均支持）
Node.js	Node 24（推荐）或 Node 22.19+；安装脚本可自动安装
磁盘	约 1–2 GB（不含模型缓存）
网络	能访问 GitHub / npm（大模型 API 需各自可访问）

提前准备

一个可用的模型 API Key（如 DeepSeek、OpenAI、Qwen、或兼容接口），后续配接用。
（可选）若走 WSL2 方案，先开启 Windows 的 WSL 功能。
用 PowerShell 作为终端（原生 Windows 推荐）。

💡 原生 Windows vs WSL2 怎么选？

原生 Windows：安装简单、启动快，适合 CLI 与 Gateway 日常使用和快速体验。

WSL2（Linux 子系统）：官方更推荐，整体更稳定，适合需要完整工具链、长期部署的场景。

新手建议：先原生安装快速跑通，需要稳定部署再迁 WSL2。

三、方式一：Windows 原生安装（推荐快速上手）

三条路径：手动装 Node.js（本教程下文）→ 之后可选用官方安装脚本装 OpenClaw；或用包里已带 Node 的一键脚本直接跑。新手若想最快跑通，可直接看下面的「一键安装脚本」；想一步步看清每一步、或遇到网络/包管理器问题时，先手动装好 Node。

0. 先装 Node.js（手动方式）

OpenClaw 需要 Node 22.19+，推荐 Node 24（LTS）。下面给出手动安装（不依赖 winget / Chocolatey）的方法。

方式 A：下载官方安装包（.msi）

打开 Node.js 官网：https://nodejs.org/en/download
- 选 LTS 版本（当前即 Node 24.x，最稳，官方推荐）。
- 点 Windows Installer (.msi) → 64 位，下载到本地（如 D:\downloads）。
双击 .msi 开始安装。
安装向导关键选项：
- Destination Folder：默认 C:\Program Files\nodejs 即可。
- ⚠️ 在 Custom Setup 页，确保 Add to PATH 被勾选（多数情况默认勾选）。这是 openclaw 命令能被找到的关键。
- 其余全部默认即可，一路 Next → Install。
安装完成后，重开一个 PowerShell 窗口（让 PATH 生效），验证：

node -v      # 应输出 v24.x.x（或 v22.19+）
npm -v       # 应输出 npm 版本号

若 node -v 提示找不到命令，说明 PATH 没配上：到「系统设置 → 系统 → 关于 → 高级系统设置 → 环境变量 → 用户变量 → Path」里确认包含 C:\Program Files\nodejs\，没有就新增，然后重开终端。

方式 B：官方便携版（zip，无需安装、可离线）

适合没有管理员权限、或想完全免安装/便携的场景：

在官网下载 Windows Binary (.zip)（64 位）。
解压到指定目录，例如：

Expand-Archive node-v24.x.x-win-x64.zip -DestinationPath D:\tools\node

把解压出的 node-v24.x.x-win-x64 目录手动加入 PATH（同上一步骤），验证后再继续。

💡 OpenClaw 官方 install.ps1 在没有任何包管理器时，其实也会自动下载便携 Node 到 %LOCALAPPDATA%\OpenClaw\deps\portable-node 并配 PATH。手动方式 B 与其原理一致，适合想自己掌控安装位置的情况。

✅ 装好 Node 并验证通过后，即可继续下一步安装 OpenClaw（下一节的「一键脚本」或 WSL 方式都可）。

1. 一键安装脚本

以管理员身份打开 PowerShell，运行官方安装脚本：

iwr -useb https://clawd.org.cn/install.ps1 | iex

脚本会自动：

检测系统、按需安装 Node.js
安装 OpenClaw 本体
启动首次配置向导（onboarding）

若只想安装、暂不进入交互配置：

& ([scriptblock]::Create((iwr -useb https://clawd.org.cn/install.ps1))) -NoOnboard

2. 验证安装

安装完成后，在 PowerShell 中执行：

openclaw --version        # 确认 CLI 可用
openclaw doctor           # 检查配置是否有问题
openclaw gateway status   # 查看 Gateway 是否在运行

能看到版本号即安装成功。

3. 设置开机自启（可选）

原生 Windows 下，用以下命令把 Gateway 注册为开机自动启动（优先用计划任务，被拒绝则降级为启动文件夹）：

openclaw gateway install
openclaw gateway status --json

四、方式二：WSL2 + Ubuntu 安装（更稳定，推荐进阶）

1. 安装 WSL2 + Ubuntu

以管理员身份打开 PowerShell：

wsl --install
# 或指定发行版
wsl --list --online
wsl --install -d Ubuntu-24.04

如系统要求，重启电脑。重启后在开始菜单打开 Ubuntu 终端。

2. 开启 systemd（Gateway 服务必需）

在 WSL 终端里创建配置并重启 WSL：

sudo tee /etc/wsl.conf >/dev/null <<'EOF'
[boot]
systemd=true
EOF

回到 PowerShell 执行 wsl --shutdown，再重新打开 Ubuntu，验证：

systemctl --user status

3. 安装 OpenClaw（在 WSL 内）

推荐从源码安装（开发/完整体验）：

git clone https://github.com/openclaw/openclaw.git
cd openclaw
pnpm install
pnpm build
pnpm ui:build
pnpm openclaw onboard --install-daemon

若网络访问 GitHub 超时，可换网络 / 开代理，或用 npm 全局安装（见下方备选）。

备选：WSL 内用 npm 全局安装

npm install -g openclaw@latest
openclaw onboard --install-daemon

4. Windows 开机自动启动 WSL（可选）

在管理员 PowerShell 中创建计划任务，让 Windows 开机即启动 WSL：

schtasks /create /tn "WSL Boot" /tr "wsl.exe -d Ubuntu --exec /bin/true" /sc onstart /ru SYSTEM

（把 Ubuntu 换成 wsl --list --verbose 里你的发行版名。）

五、首次配置（onboard）

无论哪种安装方式，首次都通过 openclaw onboard 完成基础配置：

openclaw onboard

交互式向导会引导你：

选择运行模式（本地 / 托管）
选择模型提供商（Provider）
输入对应的 API Key
选择要不要安装开机自启的服务

只改配置、不重跑完整向导，也可以用：

openclaw configure       # 配置向导

六、API 配接（让 OpenClaw 接入大模型）

OpenClaw 支持非常多的模型供应商。核心步骤只有两步：

认证（告诉 OpenClaw 你的 API Key）
设默认模型（指定 provider/model）

下面给出几种常见配接方式。

配接前：API Key 放哪？

两种方式任选，推荐放配置文件里的 env，或写进 ~/.openclaw/.env（供守护进程读取）：

openclaw config set env.DEEPSEEK_API_KEY "sk-你的key"

1. DeepSeek（OpenAI 兼容）

属性	值
Provider	`deepseek`
环境变量	`DEEPSEEK_API_KEY`
Base URL	`https://api.deepseek.com`

获取 Key：https://platform.deepseek.com/api_keys

交互式配接：

openclaw onboard --auth-choice deepseek-api-key

自动配接（脚本/无人值守）：

openclaw onboard --non-interactive `
  --mode local `
  --auth-choice deepseek-api-key `
  --deepseek-api-key "sk-你的key" `
  --skip-health `
  --accept-risk

查看 DeepSeek 可用模型：

openclaw models list --provider deepseek

常用模型：

模型引用	说明
`deepseek/deepseek-v4-flash`	默认、快速、思考能力强、100 万上下文
`deepseek/deepseek-v4-pro`	更强但更贵/更慢
`deepseek/deepseek-chat`	V3.2 非思考版
`deepseek/deepseek-reasoner`	V3.2 推理版

配置文件示例：

// ~/.openclaw/openclaw.json
{
  env: { DEEPSEEK_API_KEY: "sk-..." },
  agents: {
    defaults: {
      model: { primary: "deepseek/deepseek-v4-flash" },
    },
  },
}

2. Qwen（通义千问，阿里云）

Qwen 官方提供多种接入方式（API Key / OAuth）。

Provider：qwen
详见官方文档：/providers/qwen、/providers/qwen-oauth

交互式：

openclaw onboard --auth-choice qwen-api-key

若你有阿里云百炼（Bailian）环境，也可在 openclaw.json 里新增自定义 provider（见第七节"自定义兼容接口"）。

3. OpenAI 及任意 OpenAI 兼容接口（OpenRouter、中转站等）

Provider：openai，环境变量 OPENAI_API_KEY。

openclaw onboard --auth-choice openai-api-key

大量国内中转站 / 聚合 API（如各类 NewAPI 中转）都提供 OpenAI 兼容 端点。你可以在 openclaw.json 里把它们配成自定义 provider（最灵活的配接方式，见下节）。

七、配置文件 openclaw.json 详解

配置文件位于 ~/.openclaw/openclaw.json（Windows 下即 C:\Users\你的用户名\.openclaw\openclaw.json），使用 JSON5 格式（支持注释和尾逗号）。

⚠️ 严格校验：OpenClaw 只接受完全符合 schema 的配置。任何未知键、类型错误、非法值都会导致 Gateway 拒绝启动。改完用 openclaw doctor 检查。

自定义 / 中转 API 的配置方式

很多第三方便携 API 走 OpenAI 兼容协议，可这样加入 openclaw.json：

// ~/.openclaw/openclaw.json
{
  env: {
    DEEPSEEK_API_KEY: "sk-...",
    OPENAI_API_KEY: "sk-...",
  },

  agents: {
    defaults: {
      workspace: "~/.openclaw/workspace",
      model: { primary: "deepseek/deepseek-v4-flash" },
      // 备用模型（primary 失败时自动切换）
      // fallbacks: ["qwen/qwen-max"],
    },
  },

  // 渠道示例：飞书（需按飞书官方文档配置 App ID/Secret）
  channels: {
    feishu: {
      // appId / appSecret 等由飞书开放平台提供
      allowFrom: ["ou_xxxxxxxxxxxxxxxxxxxxxx"],
    },
  },
}

model.primary 的取值是 provider/model 形式，例如 deepseek/deepseek-v4-flash、qwen/qwen-max、openai/gpt-4o。

常用 CLI 配置命令

openclaw config get agents.defaults.workspace          # 读取
openclaw config set agents.defaults.heartbeat.every "2h"  # 设置
openclaw config unset plugins.entries.xxx.apiKey       # 删除
openclaw config schema                                 # 查看完整 schema

修改后生效方式

直接编辑 openclaw.json 保存后，Gateway 会热加载自动生效；若失败，重启 Gateway：

openclaw gateway restart

八、常用命令速查

命令	作用
`openclaw --version`	查看版本
`openclaw doctor`	诊断并修复配置问题（`--fix` 自动修复）
`openclaw onboard`	首次交互配置
`openclaw configure`	配置向导
`openclaw gateway status`	Gateway 运行状态（`--json` 输出 JSON）
`openclaw gateway restart`	重启 Gateway
`openclaw gateway install`	注册开机自启服务
`openclaw models list --provider X`	查看某供应商模型
`openclaw config get/set/unset`	读写配置
`openclaw plugins list --json`	查看已装插件

九、常见问题排查

Q1：openclaw 命令找不到？

node -v          # Node 装了没？
npm prefix -g    # 全局包在哪个目录
echo $env:PATH   # 全局 bin 在 PATH 里吗？

若 $(npm prefix -g) 不在 PATH，把它加进用户环境变量，重开终端。

Q2：Gateway 启动失败 / 拒绝启动？
多半是 openclaw.json 校验不过。运行：

openclaw doctor --fix

Q3：模型报错 / 无响应？

确认 API Key 正确、账户有额度。
确认 Gateway 守护进程能读到 Key（写在 ~/.openclaw/.env 或配置 env 里）。
用 openclaw models list --provider X 确认模型在目录中。

Q4：想让中转站 / 聚合 API 生效？

确认其提供 OpenAI 兼容端点与 Base URL。
在 openclaw.json 的 env 中配置对应 Key，并把 model.primary 指向该 provider/model。

Q5：WSL 内 Gateway 开机不自动启动？

确认 systemd 已开启（第四节步骤 2）。
确认已执行 openclaw gateway install 并开启用户服务常驻（WSL 内需 sudo loginctl enable-linger "$(whoami)"）。

十、卸载与更新

更新

openclaw update --channel stable   # 稳定版
openclaw update --channel dev      # 开发版

卸载

参考官方的 openclaw uninstall 流程（先停服务再删文件）：

openclaw gateway stop
# 再按官方 uninstall 指引删除安装与配置目录

配置与数据默认在 ~/.openclaw/，如需彻底清除请一并删除（备份需先行）。

附：参考链接

OpenClaw 文档镜像：https://docs.openclaw.ai
安装总览：install/index | Windows：platforms/windows
Provider 目录：providers/index | DeepSeek：providers/deepseek
配置参考：gateway/configuration、gateway/configuration-reference
飞书渠道：channels/feishu

⚠️ 本教程为本地整理版，具体字段与命令请以你系统上 openclaw doctor / openclaw config schema 的实际输出为准，并优先查阅官网最新文档。

OpenClaw下载与API配接（Windows）