腾讯OpenClaw搭建教程（新手零门槛，避坑完整版）
OpenClaw是一款开源、自托管的AI智能体执行网关，核心价值是连接AI大脑与本地设备，实现指令落地（如文件处理、自动化工作流、多渠道交互等），支持对接多种云模型与本地模型，所有数据默认本地存储，隐私安全可控。本教程覆盖Windows、macOS、Linux三大系统，提供「快速安装」（新手首选）和「源码安装」（开发者/进阶用户）两种方案，全程附带避坑提醒，确保零基础也能顺利搭建。
一、前期准备（必看，避免踩坑）
1.1 系统要求
-
系统版本：macOS、Linux（推荐Ubuntu 20.04 LTS），Windows需通过WSL2（推荐Ubuntu子系统），原生Windows未经充分测试，问题较多，不建议使用。
-
核心依赖：Node.js ≥ 22.0.0（低版本会导致安装失败、服务闪退，90%新手栽在此处）。
-
辅助工具：Git（用于源码下载，脚本安装需提前配置）、包管理器（推荐pnpm，npm处理依赖时易卡死）。
-
硬件要求：至少2GB内存（推荐4GB+），5GB以上可用磁盘空间，网络可正常访问国内镜像仓库（避免下载超时）。
1.2 提前安装必备工具
1.2.1 安装Node.js（全系统通用）
1. 访问Node.js官方下载页（https://nodejs.org/zh-cn/download/current/），下载对应系统的Node.js v22+版本（LTS版优先，稳定性更高）。
2. 安装完成后，打开终端（Windows打开WSL2终端/PowerShell，macOS/Linux打开终端），输入以下命令验证安装成功：
node -v npm -v
若分别显示v22.x.x和9.x.x以上版本，说明安装成功。
避坑提醒：Linux/macOS用户可通过nvm管理Node版本，避免权限问题，命令如下：
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash source ~/.bashrc nvm install 22 nvm use 22 nvm alias default 22
1.2.2 安装Git（全系统通用）
-
Windows：下载Git for Windows（https://git-scm.com/download/win），安装时勾选「Add Git to PATH」，重启终端后输入
git --version验证。 -
Linux：终端输入
sudo apt install git（Ubuntu/Debian）或sudo yum install git（CentOS），安装后验证。 -
macOS：若未安装，终端输入
xcode-select --install安装CLT，或通过Homebrew安装brew install git。
1.2.3 安装pnpm（推荐，全系统通用）
终端输入以下命令，全局安装pnpm（用于源码安装，下载依赖速度更快，避免npm卡死问题）：
npm install -g pnpm
安装完成后，输入
pnpm -v验证，显示版本号即成功。二、快速安装（新手首选，一键部署）
快速安装通过官方脚本自动完成依赖配置、CLI安装和新手引导，无需手动操作，适合零基础用户，支持macOS、Linux、WSL2三大环境，Windows原生环境需额外手动安装Git。
2.1 macOS、Linux、WSL2环境（推荐）
1. 打开终端，输入以下命令，执行官方国内安装脚本（自动适配系统，无需手动配置）：
curl -fsSL https://open-claw.org.cn/install-cn.sh | bash
2. 脚本执行过程中，会自动检查Node.js版本、安装缺失依赖、配置环境变量，无需手动干预，耐心等待即可（国内镜像，下载速度较快）。
3. 脚本执行完成后，自动启动新手引导，按提示完成初始化即可（后续步骤见「四、初始化配置」）。
2.2 Windows原生环境（不推荐，仅作参考）
Windows原生环境兼容性较差，建议优先使用WSL2，若需直接安装，步骤如下：
1. 提前手动安装Git（见1.2.2），否则脚本执行会报错。
2. 以管理员身份打开PowerShell，输入以下命令执行安装脚本：
iwr -useb https://open-claw.org.cn/install-cn.ps1 | iex
3. 脚本执行完成后，按提示启动新手引导，完成初始化。
避坑提醒：Windows原生环境可能出现命令识别失败、网关启动异常等问题，若遇到报错，优先切换到WSL2环境重新安装。
三、源码安装（开发者/进阶用户，支持二次开发）
源码安装适合需要修改代码、二次开发或体验最新功能的用户，步骤稍复杂，但可灵活配置，全程基于国内镜像仓库，避免网络超时。
3.1 克隆源码（国内镜像，速度更快）
1. 打开终端，输入以下命令，从Gitee镜像仓库克隆源码（避免GitHub国内访问缓慢）：
git clone https://gitee.com/OpenClaw-CN/openclaw-cn.git cd openclaw-cn
2. 切换到最新稳定版分支（确保体验稳定，避免开发版bug）：
git checkout stable
3.2 配置国内加速（关键，避免依赖下载超时）
安装依赖前，必须设置pnpm镜像源，否则会出现network timeout报错，终端输入：
pnpm config set registry https://registry.npmmirror.com/
3.3 安装依赖与构建项目
OpenClaw是全栈应用，首次运行需编译前端UI和后端核心，终端依次输入以下命令：
# 安装项目依赖（pnpm速度更快，避免npm卡死） pnpm install # 构建前端界面（首次运行自动安装UI依赖） pnpm ui:build # 构建后端核心服务 pnpm build
避坑提醒：若出现依赖安装失败，可删除node_modules文件夹，重新执行
pnpm install；若前端构建报错，检查Node.js版本是否≥22.0.0。3.4 启动初始化向导
依赖构建完成后，执行交互式初始化工具，一键配置DeepSeek（无需手动填写复杂参数）：
pnpm openclaw onboard –install-daemon
向导执行过程中，在「Select Provider」步骤，直接选择「DeepSeek」，系统会自动完成所有配置，无需额外操作。
四、初始化配置与服务启动（全安装方式通用）
4.1 完成新手引导
无论是快速安装还是源码安装，初始化向导启动后，按以下步骤完成配置：
-
身份验证：向导会自动配置DeepSeek，无需手动输入API Key，直接下一步即可。
-
Gateway设置：默认端口为18789，无需修改（若端口被占用，后续可调整），确认后下一步。
-
系统服务安装：选择「安装系统服务」，实现开机自动启动，避免每次手动启动网关。
-
完成配置：向导提示「初始化成功」后，自动启动Gateway服务。
4.2 启动/停止Gateway服务
初始化完成后，可通过以下命令管理Gateway服务（源码安装需在项目根目录执行，快速安装可全局执行）：
# 查看网关状态 openclaw gateway status # 启动网关（若未自动启动） openclaw gateway start # 停止网关 openclaw gateway stop # 重启网关 openclaw gateway restart
4.3 访问控制面板
1. 网关启动成功后，终端输入以下命令，自动在浏览器打开控制面板：
openclaw dashboard
2. 也可手动访问地址：
http://127.0.0.1:18789/，若提示「gateway token missing」，执行以下命令提取Token，粘贴到控制台即可：TOKEN=$(grep -oP ‘”token”: “\K(^”)+’ ~/.openclaw/openclaw.json) echo $TOKEN
五、常见问题与避坑指南（90%用户会遇到）
5.1 基础环境类报错
-
报错1：unsupported node.js version（Node版本不兼容） 解决方案：卸载旧版Node，安装v22+版本，Linux/macOS用户用nvm切换版本（见1.2.1）。
-
报错2：git: command not found（Git未安装） 解决方案：按1.2.2步骤安装Git，重启终端后重新执行命令。
-
报错3：network timeout（依赖下载超时） 解决方案：设置pnpm/npm国内镜像（见3.2），关闭代理，确保网络正常。
5.2 网关与端口类报错
-
报错1：listen EADDRINUSE :::18789（端口被占用） 解决方案：Windows执行
netstat -ano | findstr :18789找到进程号，再执行taskkill /PID 进程号 /F关闭进程；Linux/macOS执行lsof -ti:18789 | xargs kill -9，或修改端口：openclaw config set gateway.port 自定义端口。 -
报错2：WSL2宿主机无法访问网关（WSL内启动正常，Windows浏览器无法访问） 解决方案：将网关绑定0.0.0.0，Windows防火墙放行18789端口，用
localhost:18789访问。
5.3 权限与命令类报错
-
报错1：EPERM: operation not permitted（权限不足） 解决方案：Windows不要用管理员CMD，用普通权限执行；Linux/macOS修复npm权限（见2.2避坑提醒）。
-
报错2：openclaw command not found（命令无法识别） 解决方案：查看npm全局路径
npm config get prefix，将该路径添加到系统环境变量，重启终端后验证。
5.4 模型与配置类报错
-
报错1：all models failed（模型调用失败） 解决方案：检查API Key格式（以sk-开头，无多余空格），确保账户余额充足、API权限开通，关闭代理。
-
报错2：context window too small（上下文窗口过小） 解决方案：修改配置文件
vim ~/.openclaw/openclaw.json，将对应模型的contextWindow改为65536。
六、后续操作（入门必备）
6.1 健康检查
搭建完成后，执行以下命令，检查配置是否正确、修复常见问题：
openclaw doctor
6.2 智能体管理
1. 进入控制面板，点击「智能体管理」，可创建、编辑、启动/停止智能体。
2. 新手可先创建基础智能体，选择DeepSeek模型，开启「文件操作」「消息提醒」等内置技能，无需额外配置即可使用。
6.3 日志查看（排查问题）
若服务异常，可查看实时日志排查问题：
openclaw logs –follow
七、总结
新手优先选择「快速安装」，一键完成部署，全程无需手动配置；开发者可选择「源码安装」，支持二次开发和自定义配置。搭建过程中，核心避坑点是「Node.js版本≥22」「配置国内镜像」「避免端口占用」，若遇到其他问题，可查看官方帮助文档（https://open-claw.org.cn/guide/getting-started）或执行
openclaw doctor修复。© 版权声明
文章版权归作者所有，未经允许请勿转载。
相关文章
暂无评论...
