一、OpenClaw 项目简介OpenClaw 是一款开源的 AI 智能体数字员工运行框架主打低代码、高扩展性支持对接主流大模型OpenAI、Anthropic、国内通义千问 / 文心一言等、本地 Ollama 模型内置终端控制、浏览器自动化、文件操作、插件扩展等能力可快速实现自动化办公、AI 任务执行、自定义工作流等场景。官方仓库全球官方https://github.com/openclaw/openclaw国内镜像https://gitee.com/openclaw/openclaw中国社区文档https://open-claw.org.cn/二、前置环境与系统要求2.1 核心系统要求表格系统类型最低要求推荐配置特殊说明WindowsWindows 10 21H2Windows 11 WSL2原生 PowerShell 支持但坑较多官方强烈推荐使用 WSL2 UbuntumacOSmacOS 12.0macOS 14.0Intel/Apple Silicon 芯片均支持M 系列芯片本地模型性能更优LinuxUbuntu 20.04 / Debian 11Ubuntu 22.04/24.04 LTS需基础编译工具链2.2 核心依赖要求Node.js必须 v22.0.0官方推荐 v24 稳定版版本过低会直接导致安装 / 编译失败包管理器pnpm官方强制推荐npm 处理依赖树易出现卡死 / 兼容问题可选依赖Git源码编译必需、Python 3.10部分工具 / 本地模型依赖、Docker容器化部署三、全平台 3 种部署方案按需选择方案一一键脚本部署新手首选5 分钟搞定该方案全程自动化自动完成环境检测、依赖安装、程序配置无需手动处理环境变量新手零门槛全平台通用。3.1.1 国内用户加速版优先推荐解决网络超时问题Windows 平台PowerShell右键开始菜单选择终端 (管理员)/Windows PowerShell (管理员)必须以管理员身份运行首次运行需先设置执行策略避免脚本被拦截执行后输入y回车确认powershellset-executionpolicy -executionpolicy remotesigned -scope currentuser执行国内一键安装命令powershelliwr -useb https://open-claw.org.cn/install-cn.ps1 | iex等待 2-5 分钟出现openclaw installed successfully即安装完成自动进入初始化引导。macOS / Linux / WSL2 平台打开终端macOS 按Command空格搜索 TerminalWSL2 打开 Ubuntu 终端执行国内一键安装命令需要 sudo 权限输入系统密码时不显示字符正常输入回车即可curl -fsSL https://open-claw.org.cn/install-cn.sh | bash等待安装完成自动进入初始化配置向导。3.1.2 官方原版脚本海外用户适用Windows PowerShell管理员powershelliwr -useb https://openclaw.ai/install.ps1 | iexmacOS / Linux / WSL2curl -fsSL https://openclaw.ai/install.sh | bash方案二npm/pnpm 全局安装进阶用户首选可控性强该方案适合有 Node.js 基础的用户手动管理环境安装速度快支持灵活切换版本。3.2.1 第一步安装前置环境Windows 平台安装 Node.js 22/24官网下载 https://nodejs.cn/ 选择 LTS 版本一键安装全程默认下一步即可安装完成后打开管理员 PowerShell验证版本powershellnode -v npm -v安装 pnpmpowershellnpm install -g pnpm # 验证 pnpm -v国内用户配置镜像加速必做否则下载超时powershellpnpm config set registry https://registry.npmmirror.com/ npm config set registry https://registry.npmmirror.com/macOS 平台推荐使用 nvm 管理 Node.js 版本避免权限问题安装 Homebrew已安装可跳过/bin/bash -c $(curl -fsSL https://gitee.com/ineo6/homebrew-install/raw/master/install.sh)安装 nvmbrew install nvm # 配置环境变量zsh echo export NVM_DIR$HOME/.nvm ~/.zshrc echo [ -s /usr/local/opt/nvm/nvm.sh ] . /usr/local/opt/nvm/nvm.sh ~/.zshrc source ~/.zshrc安装 Node.js 24 LTS 并切换nvm install 24 nvm use 24 # 验证 node -v安装 pnpm 并配置镜像npm install -g pnpm pnpm config set registry https://registry.npmmirror.com/LinuxUbuntu/Debian平台更新系统并安装基础工具sudo apt update sudo apt upgrade -y sudo apt install -y curl git wget build-essential安装 Node.js 24 LTScurl -fsSL https://deb.nodesource.com/setup_24.x | sudo bash - sudo apt install -y nodejs # 验证 node -v npm -v安装 pnpm 并配置镜像sudo npm install -g pnpm pnpm config set registry https://registry.npmmirror.com/3.2.2 第二步全局安装 OpenClaw全平台通用命令执行后自动安装最新稳定版# pnpm安装推荐 pnpm add -g openclawlatest # 或npm安装 npm install -g openclawlatest3.2.3 第三步验证安装# 查看版本输出版本号即安装成功 openclaw --version方案三源码编译部署开发者 / 二次开发首选该方案适合想要修改源码、参与贡献、使用最新开发版功能的用户完整覆盖从源码拉取到编译构建的全流程。3.3.1 前置环境准备必须提前安装好Node.js 22.0.0、pnpm、Git安装步骤参考方案二的前置环境安装。3.3.2 第一步克隆源码仓库# 官方仓库海外用户 git clone https://github.com/openclaw/openclaw.git # 国内Gitee镜像国内用户优先速度更快 git clone https://gitee.com/openclaw/openclaw.git # 进入项目根目录后续所有命令都必须在该目录下执行 cd openclaw可选切换到指定稳定分支避免开发版不稳定# 查看所有远程分支 git branch -r # 切换到最新稳定分支示例以实际最新分支为准 git checkout release/2026.3.x3.3.3 第二步安装项目全量依赖# 国内用户先执行镜像配置必做 pnpm config set registry https://registry.npmmirror.com/ # 安装全量依赖 pnpm install等待安装完成无报错即可进入下一步若出现网络超时重新执行命令即可。3.3.4 第三步全量编译构建# 一键完整构建前端UI 核心服务 官方插件 pnpm build也可以分步构建方便排查问题# 1. 构建前端Web UI界面 pnpm ui:build # 2. 构建核心框架 pnpm build:core # 3. 构建官方插件 pnpm build:plugins3.3.5 第四步全局链接使系统可识别 openclaw 命令# 全局链接 pnpm link --global # 验证链接是否成功 openclaw --version输出版本号即编译部署完成。四、初始化配置与服务启动无论哪种安装方式安装完成后都需要完成初始化配置才能正常使用 OpenClaw 的全部功能。4.1 启动初始化引导向导执行以下命令进入交互式配置引导# 完整初始化引导同时安装后台守护进程 openclaw onboard --install-daemon若安装完成后自动进入了引导无需重复执行该命令。4.2 核心配置步骤详解风险确认提示 AI 操作的安全风险输入Yes回车继续配置模式选择新手直接选择QuickStart快速模式进阶用户可选择Custom自定义模式AI 模型提供商配置在线模型选择 OpenAI、通义千问、文心一言等输入对应的 API Key 和 API 地址即可本地模型选择Ollama提前安装好 Ollama 并启动服务配置对应的模型名称即可消息渠道配置新手先选择QuickStart后续可在 Web 面板中配置微信、飞书、钉钉等渠道权限与工具配置选择工具权限集新手选择full全量权限否则会出现终端、浏览器等功能无法使用的问题守护进程安装确认安装后台守护进程实现开机自启、后台常驻运行4.3 启动核心网关服务# 前台启动网关调试用关闭终端服务停止 openclaw gateway start # 后台守护进程启动推荐关闭终端不影响 openclaw daemon start4.4 访问 Web 管理面板网关启动成功后默认访问地址http://127.0.0.1:18789登录需要的 Token可通过以下命令获取openclaw config get gateway.auth.token浏览器打开地址输入 Token即可进入 OpenClaw 的 Web 管理界面。五、部署成功验证完成以上步骤后执行以下操作确认部署完全成功5.1 基础状态检查# 检查全局配置健康状态 openclaw health # 检查网关服务运行状态 openclaw gateway status # 检查守护进程状态 openclaw daemon status所有项均显示healthy/running即服务正常运行。5.2 功能测试在 Web 面板中发送测试消息你好介绍一下自己AI 正常回复即对话功能正常测试工具调用发送帮我查看当前系统的CPU占用情况能正常执行终端命令并返回结果即工具权限配置正常测试插件功能在插件市场安装一个简单插件验证插件加载和运行正常。六、进阶配置与玩法6.1 常用配置修改# 修改网关默认端口解决18789端口占用问题 openclaw config set gateway.port 8080 # 开启/关闭网关鉴权 openclaw config set gateway.auth.enabled false # 配置模型默认参数 openclaw config set model.default.provider openai openclaw config set model.default.model gpt-4o修改配置后需要重启网关服务生效openclaw gateway restart6.2 后台常驻与开机自启通过守护进程实现执行以下命令即可# 安装守护进程并设置开机自启 openclaw daemon install # 重启守护进程 openclaw daemon restart # 查看守护进程日志 openclaw daemon logs6.3 插件安装与管理# 查看官方插件市场 openclaw plugin list # 安装官方插件 openclaw plugin install 插件名称 # 卸载插件 openclaw plugin uninstall 插件名称 # 查看已安装插件 openclaw plugin installed6.4 本地 Ollama 模型对接提前安装 Ollamahttps://ollama.com/并启动服务拉取想要使用的模型例如ollama pull qwen2.5:7b在 OpenClaw 中配置 Ollama 提供商地址默认http://127.0.0.1:11434模型名称填写拉取的模型名即可配置完成后即可在对话中使用本地大模型无需联网。七、全平台常见问题与解决方案踩坑全解7.1 安装阶段常见问题问题 1一键脚本执行报错提示 Node.js not found原因脚本自动安装 Node 失败或系统路径未配置。解决方案手动去 Node.js 官网下载安装 v22 版本安装完成后重启终端执行node -v确认版本正常再重新执行安装脚本或直接使用 npm 全局安装方式。问题 2安装完成后执行 openclaw 提示 “命令不存在 / 不是内部或外部命令”原因Node.js 的全局包目录没有加入系统环境变量。解决方案Windows找到 Node 的全局安装目录默认C:\Users\你的用户名\AppData\Roaming\npm手动添加到系统环境变量Path中重启终端即可macOS/Linux执行以下命令将全局目录加入环境变量同时写入配置文件永久生效# zsh用户macOS默认 echo export PATH$PATH:~/.npm-global/bin ~/.zshrc source ~/.zshrc # bash用户 echo export PATH$PATH:~/.npm-global/bin ~/.bashrc source ~/.bashrc问题 3pnpm install 下载依赖超时 / 失败原因网络问题默认源访问速度慢。解决方案必须配置国内镜像源执行pnpm config set registry https://registry.npmmirror.com/配置完成后重新执行安装命令即可。问题 4源码编译报错提示 node-gyp / 构建工具相关错误原因系统缺少 C 编译工具链。解决方案Windows安装 Visual Studio 2022 生成工具勾选 “C 桌面开发”或执行powershellnpm install -g windows-build-toolsmacOS执行xcode-select --install安装命令行工具Ubuntu/Debian执行sudo apt install -y build-essential python37.2 运行阶段常见问题问题 1启动网关报错提示listen EADDRINUSE :::18789原因默认端口 18789 被其他程序占用。解决方案要么终止占用端口的进程要么修改 OpenClaw 的网关端口修改端口命令openclaw config set gateway.port 8080重启网关即可问题 2Web 面板能登录但只能聊天终端 / 浏览器 / 文件操作等功能用不了原因工具权限配置被限制默认是最小权限集。解决方案执行openclaw config edit打开配置文件找到tools配置项将profile的值从basic改成full保存文件重启网关服务openclaw gateway restart功能即可正常使用注意修改配置前必须先关闭 OpenClaw 服务否则配置会被自动还原。问题 3配置了 API Key但模型调用失败 / 超时原因API 地址配置错误、API Key 无效、网络无法访问模型服务商接口。解决方案核对 API Key 和 API Endpoint 是否正确国内模型需要配置对应的代理地址检查网络是否能访问模型接口比如 OpenAI 需要代理可配置全局代理或使用国内可直连的模型服务商执行openclaw health检查模型配置的健康状态根据报错信息调整。问题 4守护进程启动失败服务无法后台运行原因权限不足或初始化时未正确安装守护进程。解决方案Windows 必须以管理员身份运行终端macOS/Linux 需要 sudo 权限重新执行openclaw daemon install安装守护进程再执行openclaw daemon start启动查看日志openclaw daemon logs根据具体报错排查问题。7.3 平台特有问题Windows 平台原生 PowerShell 安装后很多功能异常原因OpenClaw 官方对 Windows 原生环境支持有限很多 Linux 工具和命令无法兼容。解决方案官方强烈推荐使用 WSL2 Ubuntu 环境部署可获得和 Linux 一致的兼容性和稳定性。WSL2 安装步骤管理员 PowerShell 执行powershellwsl --install重启电脑打开 Ubuntu 设置用户名和密码进入 Ubuntu 终端按照 Linux 方案执行安装即可。macOS Apple Silicon 芯片安装后提示架构不兼容原因Node.js 安装了 x86 版本通过 Rosetta 转译导致兼容问题。解决方案使用 nvm 安装原生 arm64 版本的 Node.js执行node -p process.arch确认输出arm64而非x64重新安装 OpenClaw 即可。八、总结与拓展本文完整覆盖了 OpenClaw 从新手一键安装到开发者源码编译的全流程同时提供了完整的配置、验证和踩坑解决方案按照步骤操作即可完成全平台部署。后续拓展方向自定义插件开发扩展 OpenClaw 的能力对接企业微信、飞书、钉钉等渠道实现 AI 助手在办公软件中使用结合自动化脚本实现办公场景的全流程自动化容器化部署使用 Docker 将 OpenClaw 部署到服务器实现公网访问和多端使用如果本文对你有帮助欢迎点赞、收藏、评论有问题可以在评论区留言我会一一解答。
超详细 OpenClaw 全平台部署教程
一、OpenClaw 项目简介OpenClaw 是一款开源的 AI 智能体数字员工运行框架主打低代码、高扩展性支持对接主流大模型OpenAI、Anthropic、国内通义千问 / 文心一言等、本地 Ollama 模型内置终端控制、浏览器自动化、文件操作、插件扩展等能力可快速实现自动化办公、AI 任务执行、自定义工作流等场景。官方仓库全球官方https://github.com/openclaw/openclaw国内镜像https://gitee.com/openclaw/openclaw中国社区文档https://open-claw.org.cn/二、前置环境与系统要求2.1 核心系统要求表格系统类型最低要求推荐配置特殊说明WindowsWindows 10 21H2Windows 11 WSL2原生 PowerShell 支持但坑较多官方强烈推荐使用 WSL2 UbuntumacOSmacOS 12.0macOS 14.0Intel/Apple Silicon 芯片均支持M 系列芯片本地模型性能更优LinuxUbuntu 20.04 / Debian 11Ubuntu 22.04/24.04 LTS需基础编译工具链2.2 核心依赖要求Node.js必须 v22.0.0官方推荐 v24 稳定版版本过低会直接导致安装 / 编译失败包管理器pnpm官方强制推荐npm 处理依赖树易出现卡死 / 兼容问题可选依赖Git源码编译必需、Python 3.10部分工具 / 本地模型依赖、Docker容器化部署三、全平台 3 种部署方案按需选择方案一一键脚本部署新手首选5 分钟搞定该方案全程自动化自动完成环境检测、依赖安装、程序配置无需手动处理环境变量新手零门槛全平台通用。3.1.1 国内用户加速版优先推荐解决网络超时问题Windows 平台PowerShell右键开始菜单选择终端 (管理员)/Windows PowerShell (管理员)必须以管理员身份运行首次运行需先设置执行策略避免脚本被拦截执行后输入y回车确认powershellset-executionpolicy -executionpolicy remotesigned -scope currentuser执行国内一键安装命令powershelliwr -useb https://open-claw.org.cn/install-cn.ps1 | iex等待 2-5 分钟出现openclaw installed successfully即安装完成自动进入初始化引导。macOS / Linux / WSL2 平台打开终端macOS 按Command空格搜索 TerminalWSL2 打开 Ubuntu 终端执行国内一键安装命令需要 sudo 权限输入系统密码时不显示字符正常输入回车即可curl -fsSL https://open-claw.org.cn/install-cn.sh | bash等待安装完成自动进入初始化配置向导。3.1.2 官方原版脚本海外用户适用Windows PowerShell管理员powershelliwr -useb https://openclaw.ai/install.ps1 | iexmacOS / Linux / WSL2curl -fsSL https://openclaw.ai/install.sh | bash方案二npm/pnpm 全局安装进阶用户首选可控性强该方案适合有 Node.js 基础的用户手动管理环境安装速度快支持灵活切换版本。3.2.1 第一步安装前置环境Windows 平台安装 Node.js 22/24官网下载 https://nodejs.cn/ 选择 LTS 版本一键安装全程默认下一步即可安装完成后打开管理员 PowerShell验证版本powershellnode -v npm -v安装 pnpmpowershellnpm install -g pnpm # 验证 pnpm -v国内用户配置镜像加速必做否则下载超时powershellpnpm config set registry https://registry.npmmirror.com/ npm config set registry https://registry.npmmirror.com/macOS 平台推荐使用 nvm 管理 Node.js 版本避免权限问题安装 Homebrew已安装可跳过/bin/bash -c $(curl -fsSL https://gitee.com/ineo6/homebrew-install/raw/master/install.sh)安装 nvmbrew install nvm # 配置环境变量zsh echo export NVM_DIR$HOME/.nvm ~/.zshrc echo [ -s /usr/local/opt/nvm/nvm.sh ] . /usr/local/opt/nvm/nvm.sh ~/.zshrc source ~/.zshrc安装 Node.js 24 LTS 并切换nvm install 24 nvm use 24 # 验证 node -v安装 pnpm 并配置镜像npm install -g pnpm pnpm config set registry https://registry.npmmirror.com/LinuxUbuntu/Debian平台更新系统并安装基础工具sudo apt update sudo apt upgrade -y sudo apt install -y curl git wget build-essential安装 Node.js 24 LTScurl -fsSL https://deb.nodesource.com/setup_24.x | sudo bash - sudo apt install -y nodejs # 验证 node -v npm -v安装 pnpm 并配置镜像sudo npm install -g pnpm pnpm config set registry https://registry.npmmirror.com/3.2.2 第二步全局安装 OpenClaw全平台通用命令执行后自动安装最新稳定版# pnpm安装推荐 pnpm add -g openclawlatest # 或npm安装 npm install -g openclawlatest3.2.3 第三步验证安装# 查看版本输出版本号即安装成功 openclaw --version方案三源码编译部署开发者 / 二次开发首选该方案适合想要修改源码、参与贡献、使用最新开发版功能的用户完整覆盖从源码拉取到编译构建的全流程。3.3.1 前置环境准备必须提前安装好Node.js 22.0.0、pnpm、Git安装步骤参考方案二的前置环境安装。3.3.2 第一步克隆源码仓库# 官方仓库海外用户 git clone https://github.com/openclaw/openclaw.git # 国内Gitee镜像国内用户优先速度更快 git clone https://gitee.com/openclaw/openclaw.git # 进入项目根目录后续所有命令都必须在该目录下执行 cd openclaw可选切换到指定稳定分支避免开发版不稳定# 查看所有远程分支 git branch -r # 切换到最新稳定分支示例以实际最新分支为准 git checkout release/2026.3.x3.3.3 第二步安装项目全量依赖# 国内用户先执行镜像配置必做 pnpm config set registry https://registry.npmmirror.com/ # 安装全量依赖 pnpm install等待安装完成无报错即可进入下一步若出现网络超时重新执行命令即可。3.3.4 第三步全量编译构建# 一键完整构建前端UI 核心服务 官方插件 pnpm build也可以分步构建方便排查问题# 1. 构建前端Web UI界面 pnpm ui:build # 2. 构建核心框架 pnpm build:core # 3. 构建官方插件 pnpm build:plugins3.3.5 第四步全局链接使系统可识别 openclaw 命令# 全局链接 pnpm link --global # 验证链接是否成功 openclaw --version输出版本号即编译部署完成。四、初始化配置与服务启动无论哪种安装方式安装完成后都需要完成初始化配置才能正常使用 OpenClaw 的全部功能。4.1 启动初始化引导向导执行以下命令进入交互式配置引导# 完整初始化引导同时安装后台守护进程 openclaw onboard --install-daemon若安装完成后自动进入了引导无需重复执行该命令。4.2 核心配置步骤详解风险确认提示 AI 操作的安全风险输入Yes回车继续配置模式选择新手直接选择QuickStart快速模式进阶用户可选择Custom自定义模式AI 模型提供商配置在线模型选择 OpenAI、通义千问、文心一言等输入对应的 API Key 和 API 地址即可本地模型选择Ollama提前安装好 Ollama 并启动服务配置对应的模型名称即可消息渠道配置新手先选择QuickStart后续可在 Web 面板中配置微信、飞书、钉钉等渠道权限与工具配置选择工具权限集新手选择full全量权限否则会出现终端、浏览器等功能无法使用的问题守护进程安装确认安装后台守护进程实现开机自启、后台常驻运行4.3 启动核心网关服务# 前台启动网关调试用关闭终端服务停止 openclaw gateway start # 后台守护进程启动推荐关闭终端不影响 openclaw daemon start4.4 访问 Web 管理面板网关启动成功后默认访问地址http://127.0.0.1:18789登录需要的 Token可通过以下命令获取openclaw config get gateway.auth.token浏览器打开地址输入 Token即可进入 OpenClaw 的 Web 管理界面。五、部署成功验证完成以上步骤后执行以下操作确认部署完全成功5.1 基础状态检查# 检查全局配置健康状态 openclaw health # 检查网关服务运行状态 openclaw gateway status # 检查守护进程状态 openclaw daemon status所有项均显示healthy/running即服务正常运行。5.2 功能测试在 Web 面板中发送测试消息你好介绍一下自己AI 正常回复即对话功能正常测试工具调用发送帮我查看当前系统的CPU占用情况能正常执行终端命令并返回结果即工具权限配置正常测试插件功能在插件市场安装一个简单插件验证插件加载和运行正常。六、进阶配置与玩法6.1 常用配置修改# 修改网关默认端口解决18789端口占用问题 openclaw config set gateway.port 8080 # 开启/关闭网关鉴权 openclaw config set gateway.auth.enabled false # 配置模型默认参数 openclaw config set model.default.provider openai openclaw config set model.default.model gpt-4o修改配置后需要重启网关服务生效openclaw gateway restart6.2 后台常驻与开机自启通过守护进程实现执行以下命令即可# 安装守护进程并设置开机自启 openclaw daemon install # 重启守护进程 openclaw daemon restart # 查看守护进程日志 openclaw daemon logs6.3 插件安装与管理# 查看官方插件市场 openclaw plugin list # 安装官方插件 openclaw plugin install 插件名称 # 卸载插件 openclaw plugin uninstall 插件名称 # 查看已安装插件 openclaw plugin installed6.4 本地 Ollama 模型对接提前安装 Ollamahttps://ollama.com/并启动服务拉取想要使用的模型例如ollama pull qwen2.5:7b在 OpenClaw 中配置 Ollama 提供商地址默认http://127.0.0.1:11434模型名称填写拉取的模型名即可配置完成后即可在对话中使用本地大模型无需联网。七、全平台常见问题与解决方案踩坑全解7.1 安装阶段常见问题问题 1一键脚本执行报错提示 Node.js not found原因脚本自动安装 Node 失败或系统路径未配置。解决方案手动去 Node.js 官网下载安装 v22 版本安装完成后重启终端执行node -v确认版本正常再重新执行安装脚本或直接使用 npm 全局安装方式。问题 2安装完成后执行 openclaw 提示 “命令不存在 / 不是内部或外部命令”原因Node.js 的全局包目录没有加入系统环境变量。解决方案Windows找到 Node 的全局安装目录默认C:\Users\你的用户名\AppData\Roaming\npm手动添加到系统环境变量Path中重启终端即可macOS/Linux执行以下命令将全局目录加入环境变量同时写入配置文件永久生效# zsh用户macOS默认 echo export PATH$PATH:~/.npm-global/bin ~/.zshrc source ~/.zshrc # bash用户 echo export PATH$PATH:~/.npm-global/bin ~/.bashrc source ~/.bashrc问题 3pnpm install 下载依赖超时 / 失败原因网络问题默认源访问速度慢。解决方案必须配置国内镜像源执行pnpm config set registry https://registry.npmmirror.com/配置完成后重新执行安装命令即可。问题 4源码编译报错提示 node-gyp / 构建工具相关错误原因系统缺少 C 编译工具链。解决方案Windows安装 Visual Studio 2022 生成工具勾选 “C 桌面开发”或执行powershellnpm install -g windows-build-toolsmacOS执行xcode-select --install安装命令行工具Ubuntu/Debian执行sudo apt install -y build-essential python37.2 运行阶段常见问题问题 1启动网关报错提示listen EADDRINUSE :::18789原因默认端口 18789 被其他程序占用。解决方案要么终止占用端口的进程要么修改 OpenClaw 的网关端口修改端口命令openclaw config set gateway.port 8080重启网关即可问题 2Web 面板能登录但只能聊天终端 / 浏览器 / 文件操作等功能用不了原因工具权限配置被限制默认是最小权限集。解决方案执行openclaw config edit打开配置文件找到tools配置项将profile的值从basic改成full保存文件重启网关服务openclaw gateway restart功能即可正常使用注意修改配置前必须先关闭 OpenClaw 服务否则配置会被自动还原。问题 3配置了 API Key但模型调用失败 / 超时原因API 地址配置错误、API Key 无效、网络无法访问模型服务商接口。解决方案核对 API Key 和 API Endpoint 是否正确国内模型需要配置对应的代理地址检查网络是否能访问模型接口比如 OpenAI 需要代理可配置全局代理或使用国内可直连的模型服务商执行openclaw health检查模型配置的健康状态根据报错信息调整。问题 4守护进程启动失败服务无法后台运行原因权限不足或初始化时未正确安装守护进程。解决方案Windows 必须以管理员身份运行终端macOS/Linux 需要 sudo 权限重新执行openclaw daemon install安装守护进程再执行openclaw daemon start启动查看日志openclaw daemon logs根据具体报错排查问题。7.3 平台特有问题Windows 平台原生 PowerShell 安装后很多功能异常原因OpenClaw 官方对 Windows 原生环境支持有限很多 Linux 工具和命令无法兼容。解决方案官方强烈推荐使用 WSL2 Ubuntu 环境部署可获得和 Linux 一致的兼容性和稳定性。WSL2 安装步骤管理员 PowerShell 执行powershellwsl --install重启电脑打开 Ubuntu 设置用户名和密码进入 Ubuntu 终端按照 Linux 方案执行安装即可。macOS Apple Silicon 芯片安装后提示架构不兼容原因Node.js 安装了 x86 版本通过 Rosetta 转译导致兼容问题。解决方案使用 nvm 安装原生 arm64 版本的 Node.js执行node -p process.arch确认输出arm64而非x64重新安装 OpenClaw 即可。八、总结与拓展本文完整覆盖了 OpenClaw 从新手一键安装到开发者源码编译的全流程同时提供了完整的配置、验证和踩坑解决方案按照步骤操作即可完成全平台部署。后续拓展方向自定义插件开发扩展 OpenClaw 的能力对接企业微信、飞书、钉钉等渠道实现 AI 助手在办公软件中使用结合自动化脚本实现办公场景的全流程自动化容器化部署使用 Docker 将 OpenClaw 部署到服务器实现公网访问和多端使用如果本文对你有帮助欢迎点赞、收藏、评论有问题可以在评论区留言我会一一解答。
