腾讯云选择:https://curl.qcloud.com/OkEzl83D

阿里云选择:访问阿里云OpenClaw一键部署专题页面

OpenClaw 完整安装搭建指南 📚

在这里插入图片描述

这是一份详细的 OpenClaw 安装步骤记录。每一步都包含操作说明可能遇到的问题解决方法

概述:

网络上的 OpenClaw 安装教程五花八门,哪些是官方正统,哪些是第三方魔改?直接复制粘贴命令,小心踩坑!
本文深度盘点了市面上流传最广的六种 OpenClaw 搭建方案,不仅告诉你 “怎么装”,更帮你理清
“怎么选”。我们拨开了“中文优化版”、“工业场景版”的迷雾,直击官方最推荐的部署路径。想在安装 OpenClaw
时一步到位、避免返工?这篇避坑指南就是为你准备的

✅ 搭建方式大盘点:OpenClaw 主流搭建方式对比

为了让你看得更清楚,我把这六种方式整理成了一个对比表格,你可以直观地看到它们的区别和适用场景。

方案名称 核心命令 / 方式 优缺点 / 适用场景 准确性说明
方案一:官方推荐 npm install -g openclaw@latest + openclaw onboard 适合已安装Node.js (22+)的用户,手动管理,干净标准。 ✅ 正确。这是官方文档明确列出的标准安装方式之一。绝大多数新手和普通用户。想在本地 (macOS/Linux/Win) 或 WSL2 环境下快速、稳定地部署和使用。
方案二:中文社区优化版 npm install -g openclaw-cn@latest 适合对中文界面有强需求的国内用户,但需注意是否为第三方非官方版本,可能存在更新延迟或未知风险。 ⚠️ 方向对。存在此类社区版,但并非官方出品**,国内用户,尤其是对英文界面不熟悉、或遇到官方源网络问题的用户。
方案三:克隆稳定版 git clone + pnpm install 适合开发者进行二次开发或体验最新提交的代码,操作最复杂。 ✅ 正确。这是官方认可的开发者安装方式(源码安装)。
方案四:一键脚本安装 iwr -useb https://open-claw.org.cn/install-cn.ps1 macOS/Linux/Windows:你提供的命令与官方文档不符。官方脚本能自动处理Node.js依赖,对新手最友好。 ⚠️ 方向对,但链接有误。一键脚本是官方最推荐的方式。但你的链接是第三方地址,请认准官方源https://openclaw.ai/install.ps1
方案五:工业物联网部署 场景描述(Java, MySQL等) 适合工业物联网边缘计算场景,涉及硬件选型、系统定制和协议转换。 需要将 AI 能力与现有业务系统(如工业数据库、老旧 Java 应用)对接的开发者和企业。但这通常是企业级解决方案,与个人部署方式不同。
方案六:云服务器一键部署 在云厂商控制台使用OpenClaw镜像 最省心,免去了环境配置的麻烦,服务器能7x24小时运行。适合不希望折腾本地的用户。 ✅ 正确。这是主流云厂商(如阿里云)提供的官方或第三方集成方案。
🔍 如何选择?
  • 想省心、稳定、体验完整功能:首选 方式一(官方推荐)。这是官方背书的最佳路径,onboard 向导能极大降低配置门槛 。
  • 人在国内,想获得更顺畅的安装体验和中文界面:选 方式二(中文社区优化版)。它解决了网络问题和语言障碍,体验更友好 。
  • 是开发者,想研究源码、贡献代码或尝试最新未发布功能:选 方式三(克隆稳定版)。源码在手,调试和修改都方便 。
  • 目标是让 AI 助手操作你的数据库或调用公司内部 Java 服务方式五(工业物联网场景) 描述了这种集成需求。你需要先通过前三种任一方式装好 OpenClaw,然后开发或安装特定的 Skill 来实现与这些系统的交互 。

如果你是纯新手,最推荐从方式四(官方一键安装脚本) 开始。如果想长期、稳定地在本地使用,方式一(官方推荐)方式二(中文版) 是很好的基础。而方式六(云服务器一键部署) 则是获得“永不掉线”的 AI 助手的最快捷径。
你是打算在本地电脑长期使用,还是部署在云服务器上?告诉我你的具体场景,我可以帮你推荐最合适的那一种。

💡 总结:到底该怎么选?

看完表格,你可能对如何选择更清晰了。这里我再给你几条直接的路径建议:

  1. 如果你想快速、无痛地体验 OpenClaw,尤其是在 Windows 上:首选方案四,但请务必使用官方脚本。打开 PowerShell,运行以下命令即可:

    iwr -useb https://openclaw.ai/install.ps1 | iex
    
  2. 如果你在 Linux/macOS 环境下,也想省事地安装:同样选择官方的一键脚本,这是官方文档中最推荐的、对新手最友好的方式:

    curl -fsSL https://openclaw.ai/install.sh | bash
    
  3. 如果你希望服务7x24小时在线,不想占用自己电脑的资源方案六(云服务器一键部署) 是你的不二之选。可以去阿里云、腾讯云等平台搜索 “OpenClaw” 镜像,直接创建实例。

  4. 如果你是开发者,想基于 OpenClaw 做二次开发:那就直接选择方案三(克隆源码),这才是正确的开发者姿势。

  5. 关于方案五(工业物联网):这并非一个通用的安装命令,而是一套复杂的硬件+软件的整体解决方案。如果你是在寻找一种安装方式,那它可能不适合你;如果你是在规划一个工业级的边缘计算项目,那么可以进一步去了解相关的硬件方案。

希望这份梳理能帮你找到最适合自己的路径。如果你对其中某种方式(比如云服务器部署或工业场景)有更深入的兴趣,我们可以继续探讨。


疑问?

1. 是否可以不配置模型 API Key ?

🔍 OpenClaw 的基本工作原理

OpenClaw 是一个AI 代理框架/平台,它的设计模式是:

  • AI 大脑 = 大语言模型(如 Claude、GPT 等),负责“思考和决策”
  • 执行器 = OpenClaw 软件本身,负责“执行命令和操作”

简单说,OpenClaw 自身只是一个“能接收指令的手脚”,而“思考该做什么指令”的大脑需要外接的 LLM 来完成。
即使不配置模型 API Key,OpenClaw 也几乎无法运行任何实质性功能。它本身是一个"AI智能体执行网关",核心工作原理是:接收您的自然语言指令 → 发送给 AI 模型理解 → 执行对应操作。

没有 API Key 时 OpenClaw 的实际状态
功能模块 能否使用 原因
理解您的指令 ❌ 不能 需要 AI 模型将"打开记事本"翻译成可执行命令
执行系统命令 ❌ 不能 即使您直接输入命令,也需要 AI 来解析和决定调用哪个工具
文件操作 ❌ 不能 同上
浏览器自动化 ❌ 不能 同上
任何自动化任务 ❌ 不能 全部依赖 AI 理解能力

是的,必须配置大模型 API Key 才能使用 OpenClaw 的核心功能。


📊 不配置 API Key 的后果

功能类型 是否可用 原因说明
基础启动/界面 ✅ 可启动 软件能打开界面,但初始化后会立即报错(如你遇到的“No API key found…”),然后卡在无法交互的状态。
AI 决策功能 ❌ 完全不可用 所有需要“智能规划、决策、理解意图”的功能(如“帮我发微信”、“总结文档”)都会失败,因为大脑缺失。
本地自动化操作 ❌ 间接不可用 即使是“打开微信”、“打开文件夹”这类简单操作,也需要由 AI 大脑先理解你的指令,然后生成操作指令。没有大脑,就没人能告诉“手脚”要做什么。
手动执行模式 ⚠️ 理论上存在但通常不可用 除非软件特别设计了“手动命令模式”(如命令行直接输入操作指令),但这违背了 AI 代理的初衷,通常不被支持。

🎯 核心结论

不配置 API Key,OpenClaw 只是一个“空壳”。它无法独立运行任何自动化操作,因为没有 AI 大脑来理解和规划任务。你需要把它理解为一辆没有方向盘的汽车——有轮子但没人能驾驶。


💡 如果你不想付费配置 Claude/OpenAI

可以尝试以下替代方案:

  1. 使用免费/开源模型

    • 检查 OpenClaw 是否支持配置本地部署的开源模型(如 Llama、Qwen 等),这需要你有较强的本地部署能力。
    • 在终端运行 openclaw models list 查看支持的模型提供商列表,看是否有“local”或开源模型的选项。
  2. 切换到其他集成工具

    • 如果你只需要基础的自动化操作(如打开软件、点击按钮),而不需要 AI 智能决策,可以考虑使用更传统的自动化工具
      • Windows 自带:PowerShell 脚本、任务计划程序
      • 第三方:AutoHotkey(键鼠自动化)、n8n(工作流自动化)
  3. 尝试免费 API 额度

    • 一些大模型提供新用户免费额度(如 OpenAI 在注册后通常有 $5 免费额度),可以用于体验。

一句话总结:OpenClaw 的核心就是“AI 大脑”+“执行器”的架构,不配大脑(API Key)就无法工作。如果你的需求只是机械化的本地操作,传统自动化工具可能更合适。

本质原因:OpenClaw 本身没有"思考能力"。它是一个为 AI 模型装上"手脚"的工具,而不是一个能独立运行的程序。您看到的错误"Agent failed before reply: No API key found"正是这个原因——它连第一步"理解您想做什么"都做不到。

💡 但您有完全免费的替代方案!

方案一:使用免费模型提供商(零成本)

不需要花钱,只需要注册一个免费账号获取 API Key:

提供商 免费额度 获取方式
Google Gemini 15次/分钟,1500次/天 aistudio.google.com 免费注册
OpenRouter 多个免费模型(Llama、Gemma等) openrouter.ai 免费注册
Groq 30次/分钟,14400次/天 console.groq.com 免费注册
Mistral AI 免费 API 额度 console.mistral.ai 注册
Cohere 免费 API 额度 dashboard.cohere.com 注册

配置方法(以 OpenRouter 为例):

# 1. 注册获取 API Key
# 2. 配置 OpenClaw
openclaw config set OPENAI_API_BASE https://openrouter.ai/api/v1
openclaw config set OPENAI_API_KEY "你的密钥"
openclaw config set MODEL "meta-llama/llama-3.2-3b-instruct:free"
方案二:使用本地模型(完全离线免费)

安装 Ollama,在您自己电脑上运行模型,零成本、零 API 调用、数据完全本地

# 1. 安装 Ollama(Windows/Mac/Linux)
# 下载地址:https://ollama.com

# 2. 下载轻量级模型(适合您的需求)
ollama pull llama3.2  # 3B参数,日常任务足够
# 或
ollama pull phi3      # 微软小模型,速度快

# 3. Ollama 自动提供本地 API(http://localhost:11434)

# 4. OpenClaw 会自动检测到本地 Ollama,或手动配置
openclaw config set model "ollama/llama3.2"

优势:完全免费、无限使用、数据隐私、无需网络。

方案三:使用 EasyClaw(免配置版)

猎豹移动推出的 EasyClaw 是基于 OpenClaw 的改进版,无需手动申请 API Key,开箱即用

  • 一键安装,双击即可使用
  • 厂家代付费,无需自己配置模型
  • 真正的零配置,适合只想用功能不想折腾的用户
列如您真的只想要"打开软件"

完全不需要 OpenClaw! 直接用系统命令即可:

# Windows
start notepad.exe
# 或
notepad.exe

# 创建批处理文件(双击运行)
echo start notepad.exe > 打开记事本.bat
# 以后双击这个 .bat 文件即可
总结建议
您的需求 推荐方案
体验 OpenClaw,但不想付费 方案一:注册免费 API(Google Gemini/OpenRouter)
完全不想用 API,注重隐私 方案二:Ollama 本地模型
不想任何配置,开箱即用 方案三:EasyClaw
只是偶尔打开软件 方案四:直接用系统命令

OpenClaw 确实需要 AI 模型才能工作,但这不意味着必须花钱——免费模型和本地模型都能完美驱动它!您选择哪个方案?我可以帮您具体配置。


💡 win11 - 采用方案二,搭建开始,按步骤操作:

实现“安装到指定目录”并“手动按需启动”。针对你的需求,我整理了两种方案:


方案一:非全局安装 + 手动启动(推荐)

这种方式将 OpenClaw 完全安装在自定义目录,不污染全局环境,需要时手动运行脚本启动。

1. 创建项目目录

# 示例:在 D 盘创建项目目录(可根据需要修改路径)
mkdir D:\OpenClaw
cd /d D:\OpenClaw

2. 本地安装 OpenClaw

# 本地安装(不加 -g 参数)
npm install openclaw-cn@latest

安装完成后,OpenClaw 会被安装在 D:\OpenClaw\node_modules\openclaw-cn 目录下。

3. 设置数据目录(可选)

为了避免配置数据混杂在程序目录,可以设置独立的数据目录:

# 创建数据目录
mkdir D:\OpenClawData

# 设置环境变量(临时生效)
set OPENCLAW_HOME=D:\OpenClawData
set OPENCLAW_STATE_DIR=D:\OpenClawData

如需永久生效,可通过「系统属性 → 环境变量」添加上述变量。

4. 创建启动脚本(按需启动)

D:\OpenClaw 目录下创建 start.bat 文件:

@echo off
echo 正在启动 OpenClaw-CN...
echo.

REM 设置数据目录(与步骤3保持一致)
set OPENCLAW_HOME=D:\OpenClawData
set OPENCLAW_STATE_DIR=D:\OpenClawData

REM 进入程序目录
cd /d D:\OpenClaw

REM 启动网关(不加 --install-daemon 就不会安装为服务)
call node_modules\.bin\openclaw-cn gateway --port 18789

pause

需要启动时,双击 start.bat 即可。关闭窗口服务即停止,完全手动控制。

5. 初始化配置(仅首次需要)

# 进入程序目录
cd /d D:\OpenClaw

# 运行配置向导(不加 --install-daemon 就不会安装守护进程)
node_modules\.bin\openclaw-cn onboard

根据中文提示完成模型、渠道等基础配置即可。

方案二:全局安装 + 手动启动

如果希望命令行更简洁,但依然手动控制启动:

1. 修改 npm 全局安装路径(自定义目录)

# 查看当前全局路径
npm prefix -g

# 设置自定义全局路径(例如 D:\npm-global)
npm config set prefix "D:\npm-global"

2. 配置环境变量

D:\npm-globalD:\npm-global\node_modules 添加到系统 PATH 环境变量中。

3. 安装 OpenClaw

npm install -g openclaw-cn@latest

此时 OpenClaw 会安装在 D:\npm-global\node_modules\openclaw-cn

4. 手动启动

# 直接运行(不加 --install-daemon)
openclaw-cn gateway

需要时在命令行执行此命令,按 Ctrl+C 停止服务。

两种方案对比

特点 方案一(本地安装) 方案二(全局安装)
安装位置 项目目录内 自定义全局目录
启动方式 双击start.bat openclaw-cn gateway
环境隔离 ✅ 完全隔离 ⚠️ 全局可用
多版本管理 ✅ 支持 ❌ 单一版本
配置复杂度 低(脚本封装) 中(需配环境变量)

推荐方案一,更符合“安装到指定目录”且“按需启动”的需求,也方便后续迁移或卸载。

验证安装结果

启动后访问 http://localhost:18789,能看到 Web 界面即表示成功。如需停止,直接关闭命令行窗口即可。


如果你不知道怎么运行,请继续往下看

我的目录结构!程序安装在 `H:\url\OpenClaw\002``。这是关键问题!

正确的 start.bat(针对你的目录)

@echo off
title OpenClaw-CN 启动器
echo ========================================
echo     正在启动 OpenClaw-CN...
echo ========================================
echo.

REM 程序安装目录(node_modules所在位置)
set PROG_DIR=H:\url\OpenClaw\002

REM 设置数据目录(建议独立出来)
set DATA_DIR=H:\url\OpenClaw\OpenClawData

REM 设置环境变量指向数据目录
set OPENCLAW_HOME=%DATA_DIR%
set OPENCLAW_STATE_DIR=%DATA_DIR%

echo 程序目录:%PROG_DIR%
echo 数据目录:%DATA_DIR%
echo.

REM 进入程序目录
cd /d %PROG_DIR%

REM 检查 node_modules 是否存在
if not exist "%PROG_DIR%\node_modules\" (
    echo [错误] 未找到 node_modules 目录!
    echo 请先在 %PROG_DIR% 目录下运行安装命令
    pause
    exit /b 1
)

echo [信息] 找到 openclaw-cn,准备启动...
echo [信息] 按 Ctrl+C 可停止服务
echo [信息] 关闭本窗口服务即停止
echo.
echo 启动中,请稍候...
echo.

REM 启动网关
call node_modules\.bin\openclaw-cn gateway --port 18789

echo.
echo 服务已停止
pause

保存位置

将这个 start.bat 保存在 H:\url\OpenClaw 目录下(和 002 文件夹同级),这样目录结构应该是:

H:\url\OpenClaw\
├── 002\               # 程序安装目录
│   ├── node_modules\
│   ├── package.json
│   └── package-lock.json
├── OpenClawData\       # 数据目录(自动创建)
└── start.bat           # 启动脚本

首次启动前的准备

  1. 创建数据目录(首次运行前):
# 在命令行中执行
mkdir H:\url\OpenClaw\OpenClawData
  1. 运行初始化配置(仅首次需要):
# 进入程序目录
cd /d H:\url\OpenClaw\002

# 运行配置向导
node_modules\.bin\openclaw-cn onboard

验证是否能调用

在命令行中测试:

# 进入程序目录
cd /d H:\url\OpenClaw\002

# 测试命令是否可用
node_modules\.bin\openclaw-cn --version

如果看到版本号,说明调用没问题。

简化版 start.bat(如果不需要数据目录独立)

@echo off
echo 正在启动 OpenClaw-CN...
echo.

REM 直接进入程序目录
cd /d H:\url\OpenClaw\002

REM 启动网关
call node_modules\.bin\openclaw-cn gateway --port 18789

pause

保存后双击 start.bat 就能启动了!有问题随时告诉我。


🚀 首次运行安装引导

# 如果在此前未打开引导,请启动安装引导程序
node_modules\.bin\openclaw-cn setup
# 或直接运行 openclaw-cn(如果有全局安装)

安装引导界面会依次询问:

第一步:安全警告确认
安全警告 - 请阅读。
OpenClaw 是一个业余项目,仍处于测试阶段...
我理解这很强大且本质上存在风险。继续吗?
> Yes

操作:选择 Yes,回车

第二步:安装引导模式
安装引导模式
> 快速开始(稍后通过 openclaw-cn configure 配置详细信息)
  手动

操作:选择 快速开始,回车


第三步:🤖 AI 模型配置

3.1 选择模型提供商

模型/认证提供商
> OpenAI (Codex OAuth + API key)
  Anthropic
  MiniMax
  Moonshot AI (Kimi K2.5)
  Ollama (本地)
  自定义模型
  ...
  Skip for now

两种选择:

方案A:跳过(推荐新手)
> Skip for now

操作:选择 Skip for now,回车

方案B:立即配置(如果有 API Key)

选择具体提供商,如 DeepSeek硅基流动 (SiliconFlow)

3.2 按提供商筛选模型(跳过后的界面)

按提供商筛选模型
> All providers
  amazon-bedrock
  anthropic
  deepseek
  ...

操作:保持 All providers,回车

3.3 选择默认模型

* 默认模型
> 保持当前(默认:anthropic/claude-opus-4-6)
  手动输入模型
  [模型列表...]

操作:选择 保持当前,回车


第四步:💬聊天平台配置

4.1 选择通道(聊天平台)

选择通道(快速开始)
> Telegram (Bot API)
  WhatsApp (QR link)
  Discord (Bot API)
  钉钉(官方连接器)
  飞书(Lark开放平台)
  QQ(社区版)
  Slack(Socket Mode)
  暂时跳过

推荐新手选择:Telegram (Bot API)

4.2 Telegram 机器人注册步骤

  1. 打开 Telegram,搜索 @BotFather
  2. 发送 /newbot
  3. 按提示
    • 输入机器人名字(如 My OpenClaw Bot
    • 输入机器人用户名(如 my_openclaw_bot,必须以 bot 结尾)
  4. 获取 Token(类似:1234567890:ABCdefGHIjklMNOpqrsTUVwxyz
  5. 在安装界面填入 Token

第五步: 🔧 技能配置

5.1 配置技能

o 现在配置技能?(推荐)
|  Yes

操作:选择 Yes,回车

5.2 选择包管理器

* 技能安装的首选节点管理器
|  > npm
|    pnpm
|    bun

操作:选择 npm(新手推荐),回车

等待技能自动下载安装(约 1-5 分钟)


第六步:🪝 钩子配置

6.1 启用钩子

启用钩子?
[ ] 暂时跳过
[ ] boot-md
[ ] command-logger
[ ] session-memory

操作

  • 按空格键选中:
    • [x] boot-md
    • [x] command-logger
    • [x] session-memory
  • 确保 暂时跳过 不选
  • 回车确认

第七步:🌐 网关服务

7.1 配置文件更新

Config overwrite: H:\url\OpenClaw\OpenClawData\openclaw.json
backup=H:\url\OpenClaw\OpenClawData\openclaw.json.bak

(自动完成,无需操作)

7.2 网关服务操作

Gateway service runtime
快速开始为网关服务使用Node(稳定+支持)。

网关服务已安装
> 重启
  重新安装
  跳过

操作:选择 重启,回车

7.3 健康检查提示

Health check failed: gateway closed...
Gateway target: ws://127.0.0.1:18789

(这是正常现象,不影响使用)


第八步: 🎉 安装完成

8.1 成功界面

仪表盘就绪
仪表盘链接(带令牌):http://127.0.0.1:18789/?token=xxx
已在浏览器中打开。保留该标签页以控制Clawdbot。

安装引导完成。仪表盘已使用您的令牌打开;
保留该标签页以控制Clawdbot。

第九步:🔄后续配置

9.1 配置 AI 模型(如果之前跳过了)

openclaw-cn configure

按提示选择提供商并填写 API Key

9.2 配置网络搜索(可选)

openclaw-cn configure --section web

申请 Brave Search API Key 并填入


第十步:🚦日常启动

10.1 创建启动脚本
创建 start.bat

@echo off
chcp 65001 > nul
title OpenClaw-CN 启动器
cd /d H:\url\OpenClaw\002
node_modules\.bin\openclaw-cn gateway --port 18789
pause

10.2 启动服务

# 方法1:双击 start.bat
# 方法2:命令行运行
cd H:\url\OpenClaw\002
node_modules\.bin\openclaw-cn gateway --port 18789

10.3 访问控制界面

http://127.0.0.1:18789/

如有需要,加上令牌参数


🐛 附录:常见问题解决
问题1:‘openclaw-cn’ 不是内部或外部命令

解决:使用完整路径

H:\url\OpenClaw\002\node_modules\.bin\openclaw-cn
问题2:启动乱码

解决:运行前执行

chcp 65001
问题3:网关健康检查失败

解决:不影响使用,可忽略

问题4:Telegram 机器人无响应

解决:检查是否已配置 AI 模型

openclaw-cn configure

完活

Logo

小龙虾开发者社区是 CSDN 旗下专注 OpenClaw 生态的官方阵地,聚焦技能开发、插件实践与部署教程,为开发者提供可直接落地的方案、工具与交流平台,助力高效构建与落地 AI 应用

更多推荐