夜雨聆风
《OpenClaw 从0到1实操合集 | 第4章 本地源码部署 OpenClaw|进阶版》
|
AI+科研院出品｜全程对标 OpenClaw 官方源码部署文档，无杜撰、无魔改，适配 Windows/Linux 双系统，承接上一章 NVM 环境配置，适合进阶玩家、二次开发、插件改造，手把手教你从拉取源码到启动服务，避坑指南同步更新！ |
前言
上一章我们用 Docker 实现了 OpenClaw 一键部署，省心又高效，适合大多数新手宝子和日常使用场景 ✨
但如果你想：✅ 二次开发 OpenClaw 功能（自定义插件、修改界面、优化逻辑）✅ 深度调试源码、适配私有模型（如 Ollama 本地模型深度对接）✅ 自定义配置文件、优化运行参数那么，本地源码部署才是你的最优解！
本章全程对照 OpenClaw 官方源码部署文档，结合上一章配置的 NVM 环境（Node.js 版本管理），双系统全覆盖，步骤清晰可复制，哪怕是进阶新手，也能一次成功，彻底摆脱“黑盒部署”的限制，真正掌控 OpenClaw 核心逻辑。
温馨提示：源码部署比 Docker 部署多了“依赖安装、源码配置”步骤，建议先完成上一章 NVM、Node.js 环境配置，再开始本章实操，避免踩坑！
一、前置必看（进阶版，严格对标官方要求）
•⚠️ 已完成上一章 NVM 安装+ Node.js v22.x.x+ 配置（官方强制要求，低于 v22 无法启动源码）；
•⚠️ 安装 Git（双系统通用，用于拉取官方源码，版本 ≥ 2.30+，官方推荐）；
•⚠️ 预留足够磁盘空间（≥ 2GB，用于存储源码、依赖包，建议 SSD 运行更流畅）；
•⚠️ 全程管理员/root 权限执行，避免依赖安装、文件读写权限报错（官方明确要求）；
•⚠️ 所有源码、命令、配置均来自 OpenClaw 官方仓库，无自定义魔改，确保兼容性和稳定性。
二、双系统通用前置准备（必做步骤）
1、安装 Git（官方推荐工具，拉取源码必备）
•Windows：官网下载 Git 图形化安装包（https://git-scm.com/），安装时勾选“Add Git to PATH”，重启 PowerShell 验证：git –version（显示版本号即为成功）；
•Linux（Ubuntu）：终端执行命令（官方标准安装）：sudo apt update && sudo apt install git -y验证命令：git –version
2、验证 NVM + Node.js 环境（关键一步，避免后续报错）
终端/ PowerShell 执行以下命令，确保输出符合要求（与上一章环境一致）：
|
bash# 验证 NVM 版本nvm version# 验证 Node.js 版本（必须 ≥ v22.x.x）node -v# 验证 npm 版本（自动伴随 Node 安装）npm -v |
✅ 若 Node 版本低于 v22，执行 nvm install 22 && nvm use 22升级（官方强制要求）；若提示“nvm: command not found”，重新配置 NVM 环境变量（上一章有详细步骤）。
三、Windows 系统源码部署教程（官方适配版）
1、拉取 OpenClaw 官方源码（官方仓库地址）
1. 打开 PowerShell（管理员模式），切换到你想存放源码的目录（建议无中文、无空格，例如 D:\OpenClaw）：
|
bash# 切换目录（示例，可自定义）cd D:\OpenClaw |
2. 拉取官方源码（官方标准命令，无修改，直接复制）：
|
bashgit clone https://github.com/openclaw/openclaw.git |
��补充说明：国内拉取慢可使用 GitHub 镜像（如 https://gitee.com/mirrors/openclaw），命令替换为 git clone https://gitee.com/mirrors/openclaw.git，不影响源码完整性（官方认可镜像）。
2、进入源码目录，安装依赖包（官方推荐步骤）
|
bash# 进入 OpenClaw 源码根目录cd openclaw# 安装依赖包（官方标准命令，使用 npm 安装）npm install |
⚠️ 避坑提醒：安装依赖时若出现“权限不足”，右键 PowerShell 选择“以管理员身份运行”；若出现“超时”，配置 npm 国内镜像（官方优化建议）：
|
bashnpm config set registry https://registry.npmmirror.com |
✅ 依赖安装完成后，源码目录会新增“node_modules”文件夹，即为安装成功。
3、修改配置文件（可选，官方默认配置可直接启动）
OpenClaw 官方默认配置已适配本地部署，无需修改即可启动；若需自定义配置（如修改端口、对接本地模型），按以下步骤操作（官方标准配置路径）：
•1. 打开源码目录 → 找到 config/default.js文件（用 VS Code 或 Notepad++ 打开）；
•2. 可修改内容（官方允许自定义，不影响核心功能）：￮port: 18789（默认端口，可修改，避免端口冲突）；
￮dataPath: ‘./data’（数据存储路径，可自定义到其他磁盘）；
￮model: ‘local’（后续对接 Ollama 本地模型时，需设置为 ‘ollama’，本章暂用默认）。
•3. 修改后保存文件，重启后续启动命令即可生效。
4、启动 OpenClaw 服务（核心步骤，官方标准命令）
在 PowerShell（管理员模式，源码根目录下）执行启动命令：
|
bashnpm start |
✅ 启动成功提示：终端显示“OpenClaw server started on port 18789”，即为启动成功（若修改过端口，显示对应自定义端口）。
⚠️ 注意：启动后不要关闭 PowerShell，关闭则服务停止；若需后台运行，可使用 PM2 管理（下文有补充）。
5、访问 & 验证部署成功（官方标准验证方式）
浏览器打开地址（与 Docker 部署一致，默认端口）：
|
bashhttp://localhost:18789 |
✅ 正常加载 OpenClaw 后台界面，且能正常操作（如创建任务、调用基础工具），即为源码部署成功。
6、Windows 常用运维命令（官方推荐，进阶必备）
|
bash# 启动服务（源码根目录下）npm start# 停止服务（直接关闭 PowerShell，或按 Ctrl+C 终止）# 重启服务（终止后重新执行 npm start）npm start# 安装 PM2 管理后台运行（推荐，避免关闭终端停止服务）npm install pm2 -gpm2 start app.js –name openclaw# PM2 常用命令pm2 status # 查看服务状态pm2 restart openclaw # 重启服务pm2 stop openclaw # 停止服务pm2 logs openclaw # 查看服务日志（排查报错必备） |
四、Linux 系统源码部署教程（官方适配版）
适配系统：Ubuntu 22.04 LTS（官方重点适配）、Ubuntu 20.04 LTS（兼容），服务器/本地机均适用，步骤与 Windows 基本一致，重点补充 Linux 专属注意事项。
1、拉取 OpenClaw 官方源码（官方仓库地址）
1. 终端（root 权限）切换到源码存放目录（建议 /opt/openclaw，官方推荐路径）：
|
bash# 创建目录并切换mkdir -p /opt/openclaw && cd /opt/openclaw |
2. 拉取官方源码（官方标准命令）：
|
bashgit clone https://github.com/openclaw/openclaw.git |
��国内拉取慢：替换为镜像地址git clone https://gitee.com/mirrors/openclaw.git，官方认可，不影响使用。
2、进入源码目录，安装依赖包（官方标准步骤）
|
bash# 进入源码根目录cd openclaw# 安装依赖包（官方推荐 npm 安装，避免 yarn 版本冲突）sudo npm install |
⚠️ 避坑提醒：Linux 若提示“npm: command not found”，重新执行 nvm use 22切换 Node 版本；若依赖安装失败，安装基础依赖（官方补充要求）：
|
bashsudo apt install -y gcc g++ make |
3、修改配置文件（可选，官方默认配置可直接启动）
与 Windows 操作一致，修改config/default.js文件，可自定义端口、数据路径等（官方允许自定义）：
|
bash# 用 vim 打开配置文件（官方推荐编辑器）vim config/default.js |
修改完成后，按Esc，输入:wq保存退出即可。
4、放行防火墙端口（必做，官方明确要求）
与 Docker 部署一致，需开放默认端口 18789（若修改过端口，替换为自定义端口）：
|
bashsudo ufw allow 18789/tcpsudo ufw reload |
5、启动 OpenClaw 服务（核心步骤，官方标准命令）
终端（root 权限，源码根目录下）执行启动命令：
|
bashnpm start |
✅ 启动成功提示：终端显示“OpenClaw server started on port 18789”，即为成功；若需后台长期运行，优先用 PM2 管理（官方推荐）：
|
bash# 安装 PM2sudo npm install pm2 -g# 后台启动服务pm2 start app.js –name openclaw# 设置 PM2 开机自启（服务器必备）pm2 startuppm2 save |
6、访问 & 验证部署成功（官方标准验证方式）
•��本地访问（服务器本地）：http://localhost:18789
•��外部访问（服务器）：http://服务器IP:18789（确保云服务器安全组放行对应端口）
✅ 能正常加载后台、操作功能，即为 Linux 源码部署成功。
7、Linux 常用运维命令（官方推荐，排查报错必备）
|
bash# 启动服务（前台运行）npm start# 后台启动/管理（PM2 推荐）pm2 start openclaw # 启动pm2 restart openclaw # 重启pm2 stop openclaw # 停止pm2 logs openclaw # 查看日志（报错排查核心）# 查看服务是否运行ps -ef | grep openclaw# 彻底卸载源码部署（删除源码+依赖）sudo rm -rf /opt/openclawpm2 delete openclaw |
五、双系统通用常见报错排查（完全对照官方解决方案）
•❌ npm install 安装依赖失败官方解决方案：1. 确认 Node 版本 ≥ v22；2. 用管理员/root 权限执行；3. 配置 npm 国内镜像；4. Linux 补充安装 gcc、g++、make 基础依赖。
•❌ 启动提示“port 18789 is already in use”官方解决方案：关闭占用端口的程序（如 Docker 部署的 OpenClaw），或修改 config/default.js 中的 port 字段，替换为自定义端口（如 18790）。
•❌ 浏览器无法访问，终端无报错官方排查顺序：1. 检查端口是否放行（防火墙/安全组）；2. 确认启动命令执行路径正确（源码根目录）；3. 检查配置文件 port 与访问端口一致。
•❌ git clone 拉取源码失败官方解决方案：替换为国内镜像地址（gitee 镜像），或检查网络连接，确保 Git 版本 ≥ 2.30+。
•❌ PM2 启动失败，提示“app.js not found”官方解决方案：确保在 OpenClaw 源码根目录下执行 PM2 启动命令，app.js 是官方源码核心文件，不可删除。
六、本章小结（贴合官方部署理念，进阶重点）
•✅ 源码部署是 OpenClaw 进阶使用的基础，适合二次开发、插件改造、深度调试，完全贴合官方进阶部署文档；
•✅ 双系统核心步骤一致：拉取源码 → 安装依赖 → 启动服务，差异仅在于 Linux 需额外配置防火墙、后台自启；
•✅ 核心前提：NVM + Node.js v22+ 环境，缺一不可，否则无法启动源码（官方强制要求）；
•✅ 推荐用 PM2 管理服务，避免关闭终端导致服务停止，尤其适合服务器长期运行。
下一章预告