OpenClaw小龙虾搭建与重启流程全平台指南本文档涵盖 OpenClaw 在 Windows、macOS、Linux含 WSL2三大平台的安装部署、启动停止、重启及开机自启配置全流程。 目录一、快速开始二、安装前准备三、Windows 平台搭建四、macOS 平台搭建五、Linux 平台搭建六、初始化配置七、服务管理启动/停止/重启八、开机自启配置九、常见问题排查十、更新与卸载一、快速开始OpenClaw 是什么OpenClaw昵称小龙虾是一个开源的本地 AI 智能体框架能够通过自然语言指令自动执行文件操作、系统命令、网页自动化等任务。核心特性✅本地优先数据存储在本地隐私可控✅多平台支持Windows、macOS、Linux 全覆盖✅技能扩展通过 ClawHub 技能市场扩展功能✅多模型接入支持 OpenAI、Claude、阿里云百炼、本地模型等最小配置要求项目最低要求推荐配置操作系统Win10 / macOS 12 / Ubuntu 20.04Win11 / macOS 14 / Ubuntu 22.04内存4GB8GB磁盘空间2GB10GBNode.jsv22v24 LTS二、安装前准备2.1 系统要求确认WindowsWindows 10 64位版本 2004 及以上或 Windows 11强烈建议使用 WSL2官方推荐更稳定macOSmacOS 12.0Monterey 及以上支持 Intel 和 Apple SiliconM1/M2/M3全系列LinuxUbuntu 20.04、Debian 11、CentOS 8 等主流发行版2.2 核心依赖准备必需依赖Node.js ≥ v22OpenClaw 使用了 Node.js 22 的新特性低版本会导致安装失败。安装 Node.jsWindows# 使用 winget 安装推荐winget install OpenJS.NodeJS.LTS# 或从官网下载安装包# https://nodejs.orgmacOS# 使用 Homebrewbrewinstallnode22# 或使用 nvm推荐用于版本管理curl-o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh|bashnvminstall22nvm use22Linux# Ubuntu/Debiancurl-fsSLhttps://deb.nodesource.com/setup_22.x|sudo-Ebash-sudoapt-getinstall-ynodejs# CentOS/RHELcurl-fsSLhttps://rpm.nodesource.com/setup_22.x|sudobash-sudoyuminstall-ynodejs验证安装node-v# 应显示 v22.x.x 或更高npm-v# 应显示 10.x.x 或更高其他依赖可选Git用于克隆代码仓库和安装技能Python 3.9部分技能需要FFmpeg视频处理技能需要三、Windows 平台搭建3.1 方案一WSL2 Ubuntu官方推荐最稳定步骤 1安装 WSL2# 以管理员身份打开 PowerShellwsl--install# 重启电脑按提示设置 Ubuntu 用户名和密码步骤 2进入 WSL2 环境# 打开 Ubuntu 终端wsl步骤 3在 WSL2 中安装 OpenClaw# 更新系统sudoaptupdatesudoaptupgrade-y# 安装 Node.js如果未安装curl-fsSLhttps://deb.nodesource.com/setup_22.x|sudo-Ebash-sudoaptinstall-ynodejs# 验证版本node-v# 应 ≥ v22.0.0# 执行官方安装脚本curl-fsSLhttps://openclaw.ai/install.sh|bash# 国内用户加速版curl-fsSLhttps://open-claw.org.cn/install-cn.sh|bash步骤 4验证安装openclaw--version# 应显示 OpenClaw CLI 版本号3.2 方案二PowerShell 一键安装原生 Windows步骤 1解锁 PowerShell 脚本执行权限# 以管理员身份打开 PowerShellSet-ExecutionPolicy-ExecutionPolicy RemoteSigned-Scope CurrentUser# 输入 Y 确认步骤 2执行安装脚本# 官方脚本iwr-useb https://openclaw.ai/install.ps1|iex# 国内加速脚本网络不佳时使用iwr-useb https://open-claw.org.cn/install-cn.ps1|iex步骤 3等待安装完成耗时约 3-8 分钟取决于网速出现 “OpenClaw installed successfully” 即成功步骤 4验证安装openclaw--version3.3 方案三npm 手动安装适合已有 Node.js 环境# 配置 npm 镜像国内用户推荐npm configsetregistry https://registry.npmmirror.com# 全局安装npm install-g openclawlatest# 验证openclaw--version四、macOS 平台搭建4.1 方案一一键脚本安装推荐5分钟搞定# 打开终端Terminal# 官方脚本curl-fsSLhttps://openclaw.ai/install.sh|bash# 国内加速脚本curl-fsSLhttps://open-claw.org.cn/install-cn.sh|bash# 重新加载 shell 配置source~/.zshrc# Zsh 默认# 或source~/.bashrc# Bash 用户# 验证安装openclaw--version4.2 方案二npm 手动安装# 使用 Homebrew 安装 Node.js如果未安装brewinstallnode22# 配置 npm 镜像国内用户npmconfigsetregistry https://registry.npmmirror.com# 全局安装npminstall-gopenclawlatest# 验证openclaw--version4.3 特殊情况处理Sharp 编译报错如果你系统全局安装了 libvips通过 Homebrew可能导致 sharp 编译失败# 强制使用预编译二进制SHARP_IGNORE_GLOBAL_LIBVIPS1npminstall-gopenclawlatest五、Linux 平台搭建5.1 方案一一键脚本安装推荐# Ubuntu/Debian/CentOS 通用# 官方脚本curl-fsSLhttps://openclaw.ai/install.sh|bash# 国内加速脚本curl-fsSLhttps://open-claw.org.cn/install-cn.sh|bash# 验证openclaw--version5.2 方案二npm 手动安装# 更新系统sudoaptupdatesudoaptupgrade-y# Ubuntu/Debian# 或sudoyum update-y# CentOS/RHEL# 安装 Node.js 22curl-fsSLhttps://deb.nodesource.com/setup_22.x|sudo-Ebash-# Ubuntu/Debiansudoaptinstall-ynodejs# 或curl-fsSLhttps://rpm.nodesource.com/setup_22.x|sudobash-# CentOS/RHELsudoyuminstall-ynodejs# 配置 npm 镜像国内用户npmconfigsetregistry https://registry.npmmirror.com# 全局安装sudonpminstall-gopenclawlatest# 验证openclaw--version5.3 方案三Docker 部署服务器/隔离环境首选# 确保已安装 Docker# 拉取镜像dockerpull openclaw/openclaw:latest# 启动容器dockerrun-d\--nameopenclaw\-p18789:18789\-v~/openclaw-data:/root/.openclaw\--restartalways\openclaw/openclaw:latest# 进入容器完成初始化dockerexec-itopenclaw openclaw onboard六、初始化配置安装完成后必须运行初始化向导完成配置。6.1 启动配置向导openclaw onboard6.2 配置流程按提示操作步骤选项说明1安全确认输入Yes继续2配置模式选QuickStart新手推荐或Manual3模型提供商选择 AI 模型服务4API Key输入对应模型的 API 密钥5聊天平台选择接入的平台可跳过6技能安装选择是否安装基础技能6.3 推荐配置国内用户模型提供商阿里云百炼、智谱 AI、硅基流动聊天平台飞书、钉钉海外用户模型提供商OpenAI GPT、Anthropic Claude聊天平台Telegram、WhatsApp6.4 配置文件位置配置完成后配置文件位于macOS/Linux:~/.openclaw/openclaw.jsonWindows:%USERPROFILE%\.openclaw\openclaw.json七、服务管理启动/停止/重启这是日常使用中最核心的操作。7.1 基础命令全平台通用操作命令说明启动服务openclaw gateway start启动网关后台服务停止服务openclaw gateway stop停止网关服务重启服务openclaw gateway restart重启服务修改配置后必做查看状态openclaw gateway status查看运行状态打开控制台openclaw dashboard在浏览器打开 Web 界面7.2 启动与访问步骤 1启动网关服务# macOS/Linux/WSL2openclaw gateway start# Windows PowerShellopenclaw gateway start步骤 2验证服务状态openclaw gateway status# 正常输出示例# Gateway: bindloopback (127.0.0.1), port18789# Dashboard: http://127.0.0.1:18789/# RPC probe: success步骤 3访问 Web 控制台在浏览器中打开http://127.0.0.1:18789 # 或 http://localhost:187897.3 常用启动参数# 指定端口启动避免端口冲突openclaw gateway start--port19000# 绑定到局域网允许其他设备访问openclaw gateway start--bindlan# 前台运行调试模式查看实时日志openclaw gateway run# 强制启动杀死占用端口的进程openclaw gateway start--force7.4 重启场景以下情况需要重启服务✅ 修改配置文件后openclaw.json✅ 切换 AI 模型或更改 API Key✅ 启用/禁用插件或技能✅ 修改端口或其他网络设置✅ 服务卡死或异常时八、开机自启配置8.1 Windows 开机自启方案一安装为系统服务推荐# 以管理员身份运行 PowerShell# 安装为 Windows 计划任务实现开机自启openclaw gateway install# 启动服务openclaw gatewaystart# 验证状态openclaw gateway status# 应显示 Service: Scheduled Task (registered)方案二WSL2 Windows 任务计划# 以管理员身份打开 PowerShell# 创建开机自启任务$actionNew-ScheduledTaskAction-Executewsl.exe-Argument-d Ubuntu --bash -lc systemctl --user start openclaw-gateway$triggerNew-ScheduledTaskTrigger-AtLogOn$settingsNew-ScheduledTaskSettingsSet-ExecutionTimeLimit(New-TimeSpan-Hours 0)-RestartCount 3-RestartInterval(New-TimeSpan-Minutes 1)Register-ScheduledTask-TaskNameOpenClaw_AutoStart-Action$action-Trigger$trigger-Settings$settings-RunLevel Highest-Force# 验证Get-ScheduledTask-TaskNameOpenClaw_AutoStart8.2 macOS 开机自启方案一使用 LaunchAgent推荐# 安装服务openclaw gatewayinstall# 加载服务将配置文件注册到 launchctlopenclaw gateway bootstrap# 启动服务openclaw gateway start# 验证openclaw gateway status开机自启已自动配置无需额外操作。方案二使用 systemdLinux/macOS 通用# 创建 systemd 服务文件sudotee/etc/systemd/system/openclaw.serviceEOF [Unit] DescriptionOpenClaw AI Assistant Afternetwork.target [Service] Typesimple User$USERExecStart/usr/local/bin/openclaw gateway start Restartalways RestartSec5 [Install] WantedBymulti-user.target EOF# 重载并启用服务sudosystemctl daemon-reloadsudosystemctlenableopenclawsudosystemctl start openclaw# 验证sudosystemctl status openclaw8.3 Linux 开机自启systemd 服务配置推荐# 创建用户级服务文件mkdir-p~/.config/systemd/usercat~/.config/systemd/user/openclaw-gateway.serviceEOF [Unit] DescriptionOpenClaw Gateway Afternetwork.target [Service] Typesimple ExecStart$(whichopenclaw)gateway start Restartalways RestartSec5 [Install] WantedBydefault.target EOF# 启用并启动服务systemctl--userdaemon-reload systemctl--userenableopenclaw-gateway systemctl--userstart openclaw-gateway# 开启 linger防止 SSH 退出后服务被回收sudologinctl enable-linger$(whoami)# 验证systemctl--userstatus openclaw-gateway8.4 验证开机自启重启电脑后运行以下命令验证服务是否自动启动# 查看服务状态openclaw gateway status# 访问控制台验证# 浏览器打开 http://127.0.0.1:18789九、常见问题排查9.1 服务无法启动问题浏览器访问http://127.0.0.1:18789拒绝连接排查步骤# 1. 检查服务状态openclaw gateway status# 2. 检查端口占用# Linux/macOSlsof-i:18789# Windowsnetstat-ano|findstr :18789# 3. 强制启动openclaw gateway start--force# 4. 健康检查openclaw doctor--fix9.2 命令找不到问题执行openclaw命令提示不是内部或外部命令解决方法# macOS/Linux: 重新加载 shell 配置source~/.zshrc# 或 source ~/.bashrc# Windows: 关闭当前 PowerShell重新以管理员身份打开如果仍然无效手动添加环境变量Windows PowerShell# 添加 npm 全局路径到 PATH[Environment]::SetEnvironmentVariable(Path,$env:Path;C:\Users\$env:USERNAME\AppData\Roaming\npm,User)macOS/Linux# 添加到 shell 配置文件echoexport PATH$(npm prefix -g)/bin:$PATH~/.zshrcsource~/.zshrc9.3 Node.js 版本过低问题提示 “Node.js version must be 22”解决方法使用 nvm 管理 Node.js 版本# 安装 nvmcurl-o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh|bash# 重新加载source~/.zshrc# 或 source ~/.bashrc# 安装并使用 Node.js 22nvminstall22nvm use22nvmaliasdefault22# 验证node-v9.4 端口被占用问题提示 “Port 18789 is already in use”解决方法# 方法 1更换端口启动openclaw gateway start--port19000# 方法 2杀死占用进程# Linux/macOSlsof-i:18789# 查看占用进程的 PIDkill-9PID# 杀死进程# Windowsnetstat-ano|findstr :18789# 查看占用进程的 PIDtaskkill /F /PIDPID# 杀死进程9.5 网络连接失败问题模型调用失败、依赖下载卡住解决方法# 1. 配置 npm 镜像npmconfigsetregistry https://registry.npmmirror.com# 2. 使用代理如果需要exporthttps_proxyhttp://127.0.0.1:7890exporthttp_proxyhttp://127.0.0.1:7890# 3. 重启服务openclaw gateway restart9.6 查看实时日志# 查看实时日志openclaw logs--follow# 或直接查看日志文件# macOS/Linuxtail-f~/.openclaw/logs/gateway.log# WindowsGet-Content-Path$env:USERPROFILE\.openclaw\logs\gateway.log-Wait-Tail50十、更新与卸载10.1 更新 OpenClaw# 更新 CLI 到最新版本npminstall-gopenclawlatest# 或使用内置更新命令openclaw update# 重启服务openclaw gateway restart# 验证版本openclaw--version10.2 完全卸载Windows# 停止并卸载服务openclaw gateway stop openclaw gateway uninstall# 卸载全局包npm uninstall-g openclaw# 清理配置文件可选rm-r ~/.openclaw# WSL2 内部macOS/Linux# 停止服务openclaw gateway stop# 卸载服务systemctl--userdisable openclaw-gateway# Linuxopenclaw gateway uninstall# macOS# 卸载全局包npmuninstall-gopenclaw# 清理配置文件可选rm-rf~/.openclaw附录常用命令速查表服务管理# 启动openclaw gateway start# 停止openclaw gateway stop# 重启最常用openclaw gateway restart# 状态openclaw gateway status# 打开控制台openclaw dashboard诊断工具# 健康检查openclaw doctor# 自动修复openclaw doctor--fix# 查看版本openclaw--version# 查看日志openclaw logs--follow配置管理# 初始化配置openclaw onboard# 重新配置openclaw configure# 查看配置openclaw config getkey# 设置配置openclaw configsetkeyvalue模型管理# 列出模型openclaw models list# 查看模型状态openclaw models status# 设置默认模型openclaw modelssetprovider/model结语OpenClaw 是一款强大的本地 AI 智能体正确安装和配置后它将成为你工作和生活中的得力助手。核心要点回顾✅ Node.js 版本必须 ≥ v22✅ 修改配置后必须重启服务✅ 遇到问题优先运行openclaw doctor --fix✅ 查看日志定位具体错误✅ 生产环境建议配置开机自启官方资源官方文档https://openclaws.io/docsGitHub 仓库https://github.com/openclaw/openclaw技能市场ClawHubhttps://clawdhub.com祝你使用愉快
OpenClaw_搭建与重启流程_全平台指南
OpenClaw小龙虾搭建与重启流程全平台指南本文档涵盖 OpenClaw 在 Windows、macOS、Linux含 WSL2三大平台的安装部署、启动停止、重启及开机自启配置全流程。 目录一、快速开始二、安装前准备三、Windows 平台搭建四、macOS 平台搭建五、Linux 平台搭建六、初始化配置七、服务管理启动/停止/重启八、开机自启配置九、常见问题排查十、更新与卸载一、快速开始OpenClaw 是什么OpenClaw昵称小龙虾是一个开源的本地 AI 智能体框架能够通过自然语言指令自动执行文件操作、系统命令、网页自动化等任务。核心特性✅本地优先数据存储在本地隐私可控✅多平台支持Windows、macOS、Linux 全覆盖✅技能扩展通过 ClawHub 技能市场扩展功能✅多模型接入支持 OpenAI、Claude、阿里云百炼、本地模型等最小配置要求项目最低要求推荐配置操作系统Win10 / macOS 12 / Ubuntu 20.04Win11 / macOS 14 / Ubuntu 22.04内存4GB8GB磁盘空间2GB10GBNode.jsv22v24 LTS二、安装前准备2.1 系统要求确认WindowsWindows 10 64位版本 2004 及以上或 Windows 11强烈建议使用 WSL2官方推荐更稳定macOSmacOS 12.0Monterey 及以上支持 Intel 和 Apple SiliconM1/M2/M3全系列LinuxUbuntu 20.04、Debian 11、CentOS 8 等主流发行版2.2 核心依赖准备必需依赖Node.js ≥ v22OpenClaw 使用了 Node.js 22 的新特性低版本会导致安装失败。安装 Node.jsWindows# 使用 winget 安装推荐winget install OpenJS.NodeJS.LTS# 或从官网下载安装包# https://nodejs.orgmacOS# 使用 Homebrewbrewinstallnode22# 或使用 nvm推荐用于版本管理curl-o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh|bashnvminstall22nvm use22Linux# Ubuntu/Debiancurl-fsSLhttps://deb.nodesource.com/setup_22.x|sudo-Ebash-sudoapt-getinstall-ynodejs# CentOS/RHELcurl-fsSLhttps://rpm.nodesource.com/setup_22.x|sudobash-sudoyuminstall-ynodejs验证安装node-v# 应显示 v22.x.x 或更高npm-v# 应显示 10.x.x 或更高其他依赖可选Git用于克隆代码仓库和安装技能Python 3.9部分技能需要FFmpeg视频处理技能需要三、Windows 平台搭建3.1 方案一WSL2 Ubuntu官方推荐最稳定步骤 1安装 WSL2# 以管理员身份打开 PowerShellwsl--install# 重启电脑按提示设置 Ubuntu 用户名和密码步骤 2进入 WSL2 环境# 打开 Ubuntu 终端wsl步骤 3在 WSL2 中安装 OpenClaw# 更新系统sudoaptupdatesudoaptupgrade-y# 安装 Node.js如果未安装curl-fsSLhttps://deb.nodesource.com/setup_22.x|sudo-Ebash-sudoaptinstall-ynodejs# 验证版本node-v# 应 ≥ v22.0.0# 执行官方安装脚本curl-fsSLhttps://openclaw.ai/install.sh|bash# 国内用户加速版curl-fsSLhttps://open-claw.org.cn/install-cn.sh|bash步骤 4验证安装openclaw--version# 应显示 OpenClaw CLI 版本号3.2 方案二PowerShell 一键安装原生 Windows步骤 1解锁 PowerShell 脚本执行权限# 以管理员身份打开 PowerShellSet-ExecutionPolicy-ExecutionPolicy RemoteSigned-Scope CurrentUser# 输入 Y 确认步骤 2执行安装脚本# 官方脚本iwr-useb https://openclaw.ai/install.ps1|iex# 国内加速脚本网络不佳时使用iwr-useb https://open-claw.org.cn/install-cn.ps1|iex步骤 3等待安装完成耗时约 3-8 分钟取决于网速出现 “OpenClaw installed successfully” 即成功步骤 4验证安装openclaw--version3.3 方案三npm 手动安装适合已有 Node.js 环境# 配置 npm 镜像国内用户推荐npm configsetregistry https://registry.npmmirror.com# 全局安装npm install-g openclawlatest# 验证openclaw--version四、macOS 平台搭建4.1 方案一一键脚本安装推荐5分钟搞定# 打开终端Terminal# 官方脚本curl-fsSLhttps://openclaw.ai/install.sh|bash# 国内加速脚本curl-fsSLhttps://open-claw.org.cn/install-cn.sh|bash# 重新加载 shell 配置source~/.zshrc# Zsh 默认# 或source~/.bashrc# Bash 用户# 验证安装openclaw--version4.2 方案二npm 手动安装# 使用 Homebrew 安装 Node.js如果未安装brewinstallnode22# 配置 npm 镜像国内用户npmconfigsetregistry https://registry.npmmirror.com# 全局安装npminstall-gopenclawlatest# 验证openclaw--version4.3 特殊情况处理Sharp 编译报错如果你系统全局安装了 libvips通过 Homebrew可能导致 sharp 编译失败# 强制使用预编译二进制SHARP_IGNORE_GLOBAL_LIBVIPS1npminstall-gopenclawlatest五、Linux 平台搭建5.1 方案一一键脚本安装推荐# Ubuntu/Debian/CentOS 通用# 官方脚本curl-fsSLhttps://openclaw.ai/install.sh|bash# 国内加速脚本curl-fsSLhttps://open-claw.org.cn/install-cn.sh|bash# 验证openclaw--version5.2 方案二npm 手动安装# 更新系统sudoaptupdatesudoaptupgrade-y# Ubuntu/Debian# 或sudoyum update-y# CentOS/RHEL# 安装 Node.js 22curl-fsSLhttps://deb.nodesource.com/setup_22.x|sudo-Ebash-# Ubuntu/Debiansudoaptinstall-ynodejs# 或curl-fsSLhttps://rpm.nodesource.com/setup_22.x|sudobash-# CentOS/RHELsudoyuminstall-ynodejs# 配置 npm 镜像国内用户npmconfigsetregistry https://registry.npmmirror.com# 全局安装sudonpminstall-gopenclawlatest# 验证openclaw--version5.3 方案三Docker 部署服务器/隔离环境首选# 确保已安装 Docker# 拉取镜像dockerpull openclaw/openclaw:latest# 启动容器dockerrun-d\--nameopenclaw\-p18789:18789\-v~/openclaw-data:/root/.openclaw\--restartalways\openclaw/openclaw:latest# 进入容器完成初始化dockerexec-itopenclaw openclaw onboard六、初始化配置安装完成后必须运行初始化向导完成配置。6.1 启动配置向导openclaw onboard6.2 配置流程按提示操作步骤选项说明1安全确认输入Yes继续2配置模式选QuickStart新手推荐或Manual3模型提供商选择 AI 模型服务4API Key输入对应模型的 API 密钥5聊天平台选择接入的平台可跳过6技能安装选择是否安装基础技能6.3 推荐配置国内用户模型提供商阿里云百炼、智谱 AI、硅基流动聊天平台飞书、钉钉海外用户模型提供商OpenAI GPT、Anthropic Claude聊天平台Telegram、WhatsApp6.4 配置文件位置配置完成后配置文件位于macOS/Linux:~/.openclaw/openclaw.jsonWindows:%USERPROFILE%\.openclaw\openclaw.json七、服务管理启动/停止/重启这是日常使用中最核心的操作。7.1 基础命令全平台通用操作命令说明启动服务openclaw gateway start启动网关后台服务停止服务openclaw gateway stop停止网关服务重启服务openclaw gateway restart重启服务修改配置后必做查看状态openclaw gateway status查看运行状态打开控制台openclaw dashboard在浏览器打开 Web 界面7.2 启动与访问步骤 1启动网关服务# macOS/Linux/WSL2openclaw gateway start# Windows PowerShellopenclaw gateway start步骤 2验证服务状态openclaw gateway status# 正常输出示例# Gateway: bindloopback (127.0.0.1), port18789# Dashboard: http://127.0.0.1:18789/# RPC probe: success步骤 3访问 Web 控制台在浏览器中打开http://127.0.0.1:18789 # 或 http://localhost:187897.3 常用启动参数# 指定端口启动避免端口冲突openclaw gateway start--port19000# 绑定到局域网允许其他设备访问openclaw gateway start--bindlan# 前台运行调试模式查看实时日志openclaw gateway run# 强制启动杀死占用端口的进程openclaw gateway start--force7.4 重启场景以下情况需要重启服务✅ 修改配置文件后openclaw.json✅ 切换 AI 模型或更改 API Key✅ 启用/禁用插件或技能✅ 修改端口或其他网络设置✅ 服务卡死或异常时八、开机自启配置8.1 Windows 开机自启方案一安装为系统服务推荐# 以管理员身份运行 PowerShell# 安装为 Windows 计划任务实现开机自启openclaw gateway install# 启动服务openclaw gatewaystart# 验证状态openclaw gateway status# 应显示 Service: Scheduled Task (registered)方案二WSL2 Windows 任务计划# 以管理员身份打开 PowerShell# 创建开机自启任务$actionNew-ScheduledTaskAction-Executewsl.exe-Argument-d Ubuntu --bash -lc systemctl --user start openclaw-gateway$triggerNew-ScheduledTaskTrigger-AtLogOn$settingsNew-ScheduledTaskSettingsSet-ExecutionTimeLimit(New-TimeSpan-Hours 0)-RestartCount 3-RestartInterval(New-TimeSpan-Minutes 1)Register-ScheduledTask-TaskNameOpenClaw_AutoStart-Action$action-Trigger$trigger-Settings$settings-RunLevel Highest-Force# 验证Get-ScheduledTask-TaskNameOpenClaw_AutoStart8.2 macOS 开机自启方案一使用 LaunchAgent推荐# 安装服务openclaw gatewayinstall# 加载服务将配置文件注册到 launchctlopenclaw gateway bootstrap# 启动服务openclaw gateway start# 验证openclaw gateway status开机自启已自动配置无需额外操作。方案二使用 systemdLinux/macOS 通用# 创建 systemd 服务文件sudotee/etc/systemd/system/openclaw.serviceEOF [Unit] DescriptionOpenClaw AI Assistant Afternetwork.target [Service] Typesimple User$USERExecStart/usr/local/bin/openclaw gateway start Restartalways RestartSec5 [Install] WantedBymulti-user.target EOF# 重载并启用服务sudosystemctl daemon-reloadsudosystemctlenableopenclawsudosystemctl start openclaw# 验证sudosystemctl status openclaw8.3 Linux 开机自启systemd 服务配置推荐# 创建用户级服务文件mkdir-p~/.config/systemd/usercat~/.config/systemd/user/openclaw-gateway.serviceEOF [Unit] DescriptionOpenClaw Gateway Afternetwork.target [Service] Typesimple ExecStart$(whichopenclaw)gateway start Restartalways RestartSec5 [Install] WantedBydefault.target EOF# 启用并启动服务systemctl--userdaemon-reload systemctl--userenableopenclaw-gateway systemctl--userstart openclaw-gateway# 开启 linger防止 SSH 退出后服务被回收sudologinctl enable-linger$(whoami)# 验证systemctl--userstatus openclaw-gateway8.4 验证开机自启重启电脑后运行以下命令验证服务是否自动启动# 查看服务状态openclaw gateway status# 访问控制台验证# 浏览器打开 http://127.0.0.1:18789九、常见问题排查9.1 服务无法启动问题浏览器访问http://127.0.0.1:18789拒绝连接排查步骤# 1. 检查服务状态openclaw gateway status# 2. 检查端口占用# Linux/macOSlsof-i:18789# Windowsnetstat-ano|findstr :18789# 3. 强制启动openclaw gateway start--force# 4. 健康检查openclaw doctor--fix9.2 命令找不到问题执行openclaw命令提示不是内部或外部命令解决方法# macOS/Linux: 重新加载 shell 配置source~/.zshrc# 或 source ~/.bashrc# Windows: 关闭当前 PowerShell重新以管理员身份打开如果仍然无效手动添加环境变量Windows PowerShell# 添加 npm 全局路径到 PATH[Environment]::SetEnvironmentVariable(Path,$env:Path;C:\Users\$env:USERNAME\AppData\Roaming\npm,User)macOS/Linux# 添加到 shell 配置文件echoexport PATH$(npm prefix -g)/bin:$PATH~/.zshrcsource~/.zshrc9.3 Node.js 版本过低问题提示 “Node.js version must be 22”解决方法使用 nvm 管理 Node.js 版本# 安装 nvmcurl-o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh|bash# 重新加载source~/.zshrc# 或 source ~/.bashrc# 安装并使用 Node.js 22nvminstall22nvm use22nvmaliasdefault22# 验证node-v9.4 端口被占用问题提示 “Port 18789 is already in use”解决方法# 方法 1更换端口启动openclaw gateway start--port19000# 方法 2杀死占用进程# Linux/macOSlsof-i:18789# 查看占用进程的 PIDkill-9PID# 杀死进程# Windowsnetstat-ano|findstr :18789# 查看占用进程的 PIDtaskkill /F /PIDPID# 杀死进程9.5 网络连接失败问题模型调用失败、依赖下载卡住解决方法# 1. 配置 npm 镜像npmconfigsetregistry https://registry.npmmirror.com# 2. 使用代理如果需要exporthttps_proxyhttp://127.0.0.1:7890exporthttp_proxyhttp://127.0.0.1:7890# 3. 重启服务openclaw gateway restart9.6 查看实时日志# 查看实时日志openclaw logs--follow# 或直接查看日志文件# macOS/Linuxtail-f~/.openclaw/logs/gateway.log# WindowsGet-Content-Path$env:USERPROFILE\.openclaw\logs\gateway.log-Wait-Tail50十、更新与卸载10.1 更新 OpenClaw# 更新 CLI 到最新版本npminstall-gopenclawlatest# 或使用内置更新命令openclaw update# 重启服务openclaw gateway restart# 验证版本openclaw--version10.2 完全卸载Windows# 停止并卸载服务openclaw gateway stop openclaw gateway uninstall# 卸载全局包npm uninstall-g openclaw# 清理配置文件可选rm-r ~/.openclaw# WSL2 内部macOS/Linux# 停止服务openclaw gateway stop# 卸载服务systemctl--userdisable openclaw-gateway# Linuxopenclaw gateway uninstall# macOS# 卸载全局包npmuninstall-gopenclaw# 清理配置文件可选rm-rf~/.openclaw附录常用命令速查表服务管理# 启动openclaw gateway start# 停止openclaw gateway stop# 重启最常用openclaw gateway restart# 状态openclaw gateway status# 打开控制台openclaw dashboard诊断工具# 健康检查openclaw doctor# 自动修复openclaw doctor--fix# 查看版本openclaw--version# 查看日志openclaw logs--follow配置管理# 初始化配置openclaw onboard# 重新配置openclaw configure# 查看配置openclaw config getkey# 设置配置openclaw configsetkeyvalue模型管理# 列出模型openclaw models list# 查看模型状态openclaw models status# 设置默认模型openclaw modelssetprovider/model结语OpenClaw 是一款强大的本地 AI 智能体正确安装和配置后它将成为你工作和生活中的得力助手。核心要点回顾✅ Node.js 版本必须 ≥ v22✅ 修改配置后必须重启服务✅ 遇到问题优先运行openclaw doctor --fix✅ 查看日志定位具体错误✅ 生产环境建议配置开机自启官方资源官方文档https://openclaws.io/docsGitHub 仓库https://github.com/openclaw/openclaw技能市场ClawHubhttps://clawdhub.com祝你使用愉快
