OpenClaw（龙虾）部署手册：Windows 与 Linux 系统指南
一、部署前通用准备（必看，两大系统都需要）
1.1 硬件要求（普通电脑即可满足）
- 最低配置：2 核 CPU、4GB 内存、50GB 空闲硬盘（仅运行基础功能，不加载本地大模型）；
- 推荐配置：4 核 CPU、8GB+ 内存、100GB SSD（流畅运行多任务，加载轻量本地模型无压力）；
- 特殊说明：若需离线使用、加载本地大模型（如 Qwen、Llama），需 16GB+ 内存，优先选择 NVIDIA 显卡（RTX 3060 及以上），提升运行速度。
1.2 必备工具与账号（提前准备，避免中途卡壳）
- 网络：保证网络通畅，能正常访问 GitHub（拉取依赖必备）；若使用云端大模型，需确保网络能对接对应 API（国内用户优先选国内模型，无需特殊配置）；
- 模型 API Key：部署后需要用大模型驱动龙虾，新手推荐使用智谱 GLM-4.7（中文友好、免费额度充足），获取方法：打开智谱开放平台（open.bigmodel.cn）→ 注册登录 → 进入控制台 → 找到'API Keys'→ 创建并复制 Key（一串以 sk-开头的密钥），存到记事本备用（重要，别泄露）；
- 基础工具：两大系统均需安装 Node.js（核心依赖）和 Git（源码拉取工具），下文会分系统详细说明安装步骤，全程默认下一步即可。
1.3 注意事项
- 所有安装路径、文件夹名称，全程不要有中文、空格、特殊符号（比如'D:\Tools\OpenClaw'是正确的）；
- 安装过程中，若弹出'权限请求''是否允许'，一律点击'允许''确定'；
- 遇到报错不要慌，先看本文'常见问题排查'部分，90% 的问题都能解决；
- API Key 是核心密钥，不要分享给他人，避免被恶意调用产生额外费用。
二、Windows 系统（Win10/11）部署步骤（小白首选，最易操作）
Windows 系统推荐'一键脚本部署'，零代码、自动化完成，5 分钟即可搞定，新手无需尝试复杂方式。
步骤 1：安装基础工具（Node.js + Git）
1.1 安装 Node.js（核心依赖）
- 打开 Node.js 官方网站（https://nodejs.org/），官网会自动推荐适配 Windows 系统的版本，优先选择LTS 长期支持版（如 v22 LTS），稳定性更高；
- 下载完成后，双击安装包，全程点击'下一步'，重点步骤：在「Tools」环节，务必勾选「Automatically install the necessary tools…」（自动安装必要工具）；
- 安装完成后，关闭所有已打开的终端（命令提示符、PowerShell），重新打开一个，输入命令
node -v，按回车，若出现类似'v22.0.0'的版本号，说明安装成功。
1.2 安装 Git（源码拉取工具）
- 打开 Git 官方网站（https://git-scm.com/），点击「Click here to download for Windows」获取安装包；
- 双击安装包，全程点击'下一步'，无需额外设置，安装完成后，输入命令
git -v，按回车，出现版本号即安装成功。
1.3 配置国内加速镜像（可选，推荐）
国内用户直接下载依赖可能速度较慢，建议配置淘宝 npm 镜像，大幅提升下载速度：
- 按下 Win + R 组合键，输入'PowerShell'并回车，打开 PowerShell 终端；
- 复制粘贴以下命令，回车执行：
npm config set registry https://registry.npmmirror.com，执行完成后无需额外操作。
步骤 2：一键部署 OpenClaw（核心步骤，零代码）
- 打开管理员模式 PowerShell：按下 Win + X 组合键，选择「Windows PowerShell (管理员)」（Windows 11 显示为「终端 (管理员)」），若弹出权限提示，点击'确定'；
- 解锁脚本执行权限：复制粘贴以下命令，回车执行（仅首次部署需要），无需修改任何内容：
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser -Force； - 执行一键安装脚本：复制粘贴以下命令，回车后耐心等待（约 3-10 分钟，取决于网络速度），脚本会自动下载龙虾 AI 源码、配置运行环境，无需手动操作：
iwr -useb https://openclaw.ai/install.ps1 | iex； - 当终端出现「OpenClaw installed successfully」（龙虾 AI 安装成功）的提示时，即表示部署完成，此时龙虾已自动启动后台服务。
步骤 3：初始化配置（跟着向导走，简单易懂）
安装完成后，会自动进入交互式配置界面，用键盘上下键移动光标，回车键确认选择，全程按以下提示操作：
- 风险告知：显示法律条款，问你是否知晓 Agent 操作电脑的风险，选「Yes」（后续可限制权限，无需担心）；
- 启动模式：选「Quick Start（快速开始）」，新手别碰'高级模式'，容易迷路；
- 选择模型服务商：在服务商列表里，找到「ZhipuAI」（有时显示为 Z.AI），选中它；
- 选择具体模型：选「GLM-4.7」（或其他你已开通的模型）；
- 输入 API Key：把之前复制的智谱 API Key 粘贴进去（Windows 终端里 Ctrl+V 可能无效，直接鼠标右键粘贴即可，记得检查首尾有没有多余空格）；
- 额外功能：问你是否安装 Skills（技能插件）或配置 IM（即时通讯），统统选「No」，这些等进入图形界面再配更直观；
- 访问方式：最后选择「Open the Web UI」，系统会自动启动浏览器，跳转到 OpenClaw 的可视化面板；若未自动打开，手动在浏览器输入「http://localhost:3000」即可。
步骤 4：验证部署成功（简单两步，确认能用）
- 测试模型连接：左侧导航点击'对话'，随便发一句'你好，大龙虾！'，若能正常回复，说明'脑子'（大模型）已接上；
- 测试 Agent 能力：输入指令'请在 C 盘创建一个名为'abc'的文件夹'，几秒钟后，打开 C 盘，若能看到'abc'文件夹，说明部署成功，龙虾已获得文件系统权限。
三、Linux 系统（Ubuntu 22.04 为例）部署步骤（小白也能上手）
Linux 系统推荐'一键脚本部署'，操作和 Windows 类似，全程在终端执行命令，复制粘贴即可，无需手动输入复杂指令。
步骤 1：准备工作（确保系统正常）
- 打开 Linux 终端（快捷键 Ctrl+Alt+T），先更新系统软件包，输入命令：
sudo apt update && sudo apt upgrade -y，按回车，输入电脑开机密码（输入时不显示密码，正常输入即可），等待更新完成； - 确保系统是 Ubuntu 22.04（其他 Linux 版本步骤类似，略有差异），输入命令：
lsb_release -a，能看到'22.04'字样即可。
步骤 2：安装基础工具（Node.js + Git）
1.1 安装 Node.js
- 验证安装：输入命令
node -v，出现版本号即安装成功。
在终端输入以下命令，依次执行（复制粘贴，每输完一条按回车）：
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash && sudo apt install -y nodejs
1.2 安装 Git
- 输入命令：
sudo apt install -y git，按回车，等待安装完成； - 验证安装：输入命令
git -v，出现版本号即安装成功。
步骤 3：一键部署 OpenClaw（核心步骤）
- 在终端输入以下一键安装命令，复制粘贴后按回车，耐心等待（约 3-10 分钟，取决于网络速度）：
curl -fsSL https://openclaw.ai/install.sh | bash； - 脚本会自动安装 Node.js、OpenClaw 并启动配置向导，中途若提示输入密码，输入电脑开机密码即可；
- 当终端出现「OpenClaw installed successfully」的提示时，即表示核心程序安装完成。
步骤 4：初始化配置（和 Windows 一致，跟着向导走）
配置向导启动后，操作和 Windows 系统完全相同，用键盘上下键选择，回车键确认，具体步骤参考 Windows'步骤 3'，重点注意：
- 模型服务商选「ZhipuAI」，模型选「GLM-4.7」，粘贴之前获取的 API Key；
- 额外功能选「No」，访问方式选「Open the Web UI」；
- 若未自动打开浏览器，手动输入「http://localhost:3000」，即可进入可视化面板。
步骤 5：验证部署成功（和 Windows 一致）
- 在可视化面板'对话'栏发送消息，测试模型连接；
- 输入指令'请在/home 目录创建一个名为'abc'的文件夹'，之后输入命令
ls /home，若能看到'abc'文件夹，说明部署成功。
四、常见问题排查
问题 1：API Key 粘贴后无效，报错'Invalid API Key'
原因：复制时包含了多余空格，或 API Key 不完整；
解决：把 API Key 粘贴到记事本，检查首尾有没有空白，确认无误后再复制到配置界面，避免直接从网页复制时带多余字符。
问题 2：关闭终端后，无法访问 Web UI（localhost:3000 报错）
原因：OpenClaw 后台服务被终止；
解决：重新打开终端，先按 Ctrl+C 结束当前进程（若有），然后依次输入以下两条命令，回车执行，再刷新浏览器即可：
openclaw gateway openclaw dashboard
问题 3：部署时报错'Config invalid'（2026 年 2 月后版本常见）
原因：新版本把 API Key 挪到了独立文件，旧教程的配置方法失效；
解决（Windows）：打开路径「C:\Users\你的用户名.openclaw\agents\main\agent\」，新建文件「auth-profiles.json」，输入以下内容（替换成你的 API Key）：
{ "zai:default": { "secret":"sk-你的 API Key" } }
保存后重启 OpenClaw；
解决（Linux）：打开终端，输入命令 nano ~/.openclaw/agents/main/agent/auth-profiles.json，粘贴上述内容，按 Ctrl+O 保存，Ctrl+X 退出，重启 OpenClaw 即可。
问题 4：安装依赖速度极慢，甚至卡住
原因：默认下载源为国外服务器，国内网络访问不畅；
解决：Windows 按'步骤 1.3'配置国内镜像；Linux 输入命令 npm config set registry https://registry.npmmirror.com，配置完成后重新执行安装命令。
问题 5：Windows 系统报错'命令不存在'
原因：Node.js 或 Git 安装时，未配置环境变量（PATH）；
解决：重启终端，若仍无效，卸载 Node.js 和 Git，重新安装，安装时务必勾选'Add to PATH'相关选项。
问题 6：Linux 系统报错'权限不足'
原因：未使用 sudo 权限执行命令；
解决：在报错的命令前加上「sudo」，例如 sudo npm install -g openclaw，输入密码后重新执行。
五、后续使用建议
- 安全提醒：龙虾能操作电脑，建议在可视化面板'设置'中限制工作目录（比如只允许访问 D:\Workspace 或/home/你的用户名），避免误删重要文件；
- 开机自启：执行命令
openclaw onboard --install-daemon，即可设置开机自动启动后台服务，无需每次手动启动； - 版本更新：打开终端，输入命令
npm update -g openclaw，即可更新到最新版本； - 新手建议：先从简单指令开始测试（如创建文件夹、打开文档），熟悉后再尝试复杂任务，避免一开始操作过于复杂导致报错。
六、总结
OpenClaw（龙虾）部署其实很简单，核心就是'装基础工具→一键部署→简单配置→验证使用'，无论是 Windows 还是 Linux 系统，只要跟着本文步骤，复制粘贴命令、按提示选择，就能顺利完成部署。
如果遇到本文未提及的报错，可截图报错信息，搜索报错内容，或参考 OpenClaw 官方文档，大部分问题都能快速解决。
