OpenClaw 本地化部署指南（全平台）

OpenClaw 本地化部署指南全平台目录一、环境要求二、依赖安装按平台三、部署 OpenClaw四、外部渠道连接五、部署验证六、常用维护命令七、常见问题排查八、参考资源一、环境要求1.1 硬件要求项目最低要求推荐配置CPUx86_64 双核4 核及以上内存4GB 可用8GB磁盘2GB 可用10GB网络可访问模型 API 端点宽带连接未搜索到 OpenClaw 官方硬件要求文档以上基于实际部署经验。1.2 软件要求要求版本说明Node.js≥ v22.19.0推荐 v24.x核心运行时npm≥ 10.x包管理器随 Node 安装终端各平台推荐终端见下浏览器Chrome / Edge 最新版访问 Control UI1.3 各平台终端推荐平台推荐终端检查命令WindowsPowerShell 7 / Windows Terminalpwsh --versionLinuxbash / zshecho $SHELLmacOSzsh默认 / bashecho $SHELLWSLbash默认 / zshecho $SHELL1.4 通用环境检查# 操作系统uname-a# Linux / macOS / WSLwinver# Windows运行对话框运行# Node.jsnode--version# 需要 v22.19.0# npmnpm--version# 建议 10.x# 内存free-h# Linux / WSL / macOSsysteminfo|findstr物理内存# Windows# 磁盘df-h/# Linux / WSL / macOSwmic logicaldisk get size,freespace,caption# Windows二、依赖安装按平台2.1 Windows方案 A官方安装包推荐访问 nodejs.org 下载 LTS 版运行安装程序全程默认选项重启终端后验证node--version npm--version方案 Bwingetwinget install OpenJS.NodeJS.LTS方案 Cfnm推荐开发人员使用winget install fnm fnm install 24 fnm use 24 fnm default 242.2 LinuxUbuntu / Debian方案 ANodeSource 官方源# 安装 Node.js 24.xcurl-fsSLhttps://deb.nodesource.com/setup_24.x|sudo-Ebash-sudoapt-getinstall-ynodejs# 验证node--versionnpm--version方案 Bnvm推荐# 安装 nvmcurl-o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.4/install.sh|bash# 重新加载 shellsource~/.bashrc# 安装并使用 Node.js 24nvminstall24nvm use24nvmaliasdefault24配置 npm 全局安装路径避免 sudomkdir-p~/.npm-globalnpmconfigsetprefix ~/.npm-globalechoexport PATH$HOME/.npm-global/bin:$PATH~/.bashrcsource~/.bashrc2.3 macOS方案 AHomebrew推荐# 安装 Homebrew如未安装/bin/bash-c$(curl-fsSLhttps://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)# 安装 Node.js 24brewinstallnode24 brewlink--overwritenode24# 验证node--versionnpm--version方案 Bnvmcurl-o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.4/install.sh|bashsource~/.zshrc# macOS 默认 zshnvminstall24nvm use24nvmaliasdefault242.4 WSLWindows Subsystem for LinuxWSL 中的安装方法同 2.2 Linux 章节NodeSource 或 nvm。WSL 环境特殊配置# 确保 npm 全局安装路径在 PATH 中exportPATH$HOME/.npm-global/bin:$PATH# 并写入 .bashrc 持久化echoexport PATH$HOME/.npm-global/bin:$PATH~/.bashrc⚠️注意Windows 的 npm 路径/mnt/c/Users/.../npm可能影响 WSL 中命令解析。确保 WSL 原生安装路径在 PATH 中排在更前面。三、部署 OpenClaw3.1 安装# 所有平台通用npminstall-gopenclaw# 验证openclaw--version# 输出示例OpenClaw 2026.6.8 (844f405)国内网络加速npmconfigsetregistry https://registry.npmmirror.com3.2 首次配置引导式openclaw onboard引导流程依次询问步骤说明建议值运行模式本地运行还是远程连接local个人使用模型提供商选择 API 提供商DeepSeek / Qwen / OpenAI 等API Key输入密钥从对应平台获取Gateway 端口服务监听端口18789认证方式访问控制token推荐Agent 名称给你的智能体命名自定义API Key 获取地址提供商控制台地址DeepSeekhttps://platform.deepseek.com/api_keys通义千问/Qwenhttps://bailian.console.aliyun.com/OpenAIhttps://platform.openai.com/api-keys3.3 快速配置非交互式# Linux / macOS / WSLopenclaw onboard --non-interactive--modelocal\--auth-choice deepseek-api-key\--deepseek-api-keysk-你的API_KEY\--skip-health --accept-risk# Windows PowerShell反引号换行openclaw onboard --non-interactive--modelocal--auth-choice deepseek-api-key--deepseek-api-keysk-你的API_KEY --skip-health --accept-risk3.4 配置文件参考路径~/.openclaw/openclaw.jsonJSON5 格式支持注释{ agents: { defaults: { workspace: ~/.openclaw/workspace, // Linux/WSL/macOS // workspace: D:\\AI\\Openclaw\\workspace, // Windows model: { primary: deepseek/deepseek-v4-flash }, models: { deepseek/deepseek-v4-flash: { alias: DeepSeek }, qwen/qwen3.5-plus: { alias: Qwen } } } }, gateway: { mode: local, port: 18789, bind: loopback, // loopback仅本机, lan局域网 auth: { mode: token, token: 你的token }, controlUi: { allowInsecureAuth: true } } }与 Docker Desktop 共用 WSL 时注意如果你的 WSL 中同时运行着 Docker Desktop 和 OpenClaw可能遇到端口占用或 WSL 引擎崩溃问题。已知处理# Docker Desktop 重启后 WSL 引擎容易崩wsl--shutdown# Windows PowerShell 中执行# 然后重新启动 Docker Desktop# 再启动 OpenClaw Gateway3.5 启动 Gateway# 通用启动openclaw gateway start# 指定端口openclaw gateway start--port18789# 局域网可访问openclaw gateway start--bindlan# 查看实时日志openclaw logs--follow--bind可选值值说明适用场景loopback仅本地 127.0.0.1默认安全lan局域网可访问需要从其他设备访问tailnetTailscale 网络通过 Tailscale 远程访问auto自动选择通用custom自定义高级用户3.6 各平台开机自启WindowsStartup 文件夹$shortcut$env:APPDATA\Microsoft\Windows\Start Menu\Programs\Startup\OpenClaw.lnk$wshellNew-Object-ComObject WScript.Shell$link$wshell.CreateShortcut($shortcut)$link.TargetPath cmd.exe$link.Arguments /c openclaw gateway start$link.WindowStyle 7$link.Save()⚠️ 注意Windows 计划任务启动可能有延迟Startup 文件夹更可靠。Linux / macOSsystemd 用户服务# 如果系统支持 systemd多数 Linux 发行版openclaw gateway start# 自动创建 systemd 用户服务# 检查服务状态systemctl--userstatus openclaw-gateway.service# macOS使用 launchd# OpenClaw 自动处理 macOS 的 launchd 配置WSL.bashrc / .profile# 在 ~/.bashrc 末尾添加if!pgrep-fgateway --port/dev/null21;thennohupopenclaw gateway start/dev/null21fi四、外部渠道连接4.1 飞书 / Lark飞书是 OpenClaw内置支持的渠道需版本 ≥ 2026.5.29。前置条件在 飞书开放平台 创建应用获取 App ID 和 App Secret。配置# 运行设置向导openclaw channels login--channelfeishu# 选择手动模式输入 App ID App Secret# 或选择二维码模式自动创建机器人# 重启 Gatewayopenclaw gateway restart访问控制# 私聊策略openclaw configsetchannels.feishu.dmPolicy pairing# 群聊策略openclaw configsetchannels.feishu.groupPolicy allowlist# 要求 提及openclaw configsetchannels.feishu.requireMentiontrue# 批准配对openclaw pairing list feishu openclaw pairing approve feishuCODE参考https://docs.openclaw.ai/channels/feishu4.2 个人微信通过腾讯外部插件tencent-weixin/openclaw-weixin连接。安装# 方式一推荐npx-ytencent-weixin/openclaw-weixin-cliinstall# 方式二手动安装openclaw pluginsinstalltencent-weixin/openclaw-weixinopenclaw configsetplugins.entries.openclaw-weixin.enabledtrueopenclaw gateway restart登录openclaw channels login--channelopenclaw-weixin# 用手机微信扫描终端二维码兼容性插件版本OpenClaw 版本npm 标签2.x 2026.3.22latest1.x 2026.1.0, 2026.3.22legacy参考https://docs.openclaw.ai/channels/wechat4.3 钉钉❌未发现 OpenClaw 官方钉钉频道支持。替代方案钉钉群机器人 webhook 中间服务转发到 OpenClaw API参照 Channel Plugin SDK 开发自定义插件4.4 企业微信❌未发现 OpenClaw 官方企业微信频道支持。替代方案企业微信群机器人 webhook 转发自定义渠道插件企业微信与个人微信的账号体系不互通openclaw-weixin插件不能用于企业微信。五、部署验证5.1 服务状态# 通用检查openclaw status openclaw config validate openclaw models status openclaw doctor5.2 Web UI浏览器打开http://localhost:18789应看到 OpenClaw Control UI 登录页面用配置的 token 或密码登录5.3 模型测试# 终端测试openclaw chat--message你好能正常交流吗--modeldeepseek/deepseek-v4-flash# 或在 Web UI 中直接发送消息六、常用维护命令6.1 Gateway 生命周期openclaw gateway start# 启动openclaw gateway stop# 停止openclaw gateway restart# 重启openclaw gateway status# 状态openclaw logs--follow# 实时日志6.2 模型管理openclaw modelssetprovider/model# 切换默认模型openclaw models status# 查看当前openclaw models list# 列出所有openclaw models fallbacksaddmodel# 添加备选/modelmodel# 聊天时临时切换6.3 配置管理openclaw config show# 查看配置openclaw configsetgateway.port18790# 修改配置openclaw doctor# 诊断openclaw doctor--fix# 自动修复# 添加模型白名单--merge 合并openclaw configsetagents.defaults.models{new-model:{}}--strict-json--merge6.4 更新npmupdate-gopenclaw# 更新 OpenClawopenclaw--version# 查看版本七、常见问题排查7.1 Gateway 启动失败现象可能原因解决方法端口被占用另一进程占用了端口netstat -ano | findstr :18789Windowsss -tlnp | grep 18789Linux/macOS/WSL“Invalid --bind”bind 值不对只能使用loopback/lan/tailnet/auto/customNode 版本错误Node.js v22.19node --version检查升级 Node.jsnpm 安装失败权限问题用管理员终端Windows或sudoLinux/macOS7.2 Web UI 打不开确认 Gateway 已启动openclaw status检查防火墙是否放行端口尝试http://127.0.0.1:18789而非localhost使用浏览器无痕模式排除插件干扰7.3 WSL 特殊问题# localhost 从 Windows 无法访问# 方案一用 netsh portproxy 转发netsh interface portproxyaddv4tov4listenport18790listenaddress127.0.0.1connectport18790connectaddress172.29.x.x# 方案二将 bind 改为 lan通过 WSL2 IP 访问openclaw configsetgateway.bind lan# systemd 用户服务端口硬编码# 检查并修改 ~/.config/systemd/user/openclaw-gateway.service 中的 --port 值# npm 路径冲突# 确保 ~/.npm-global/bin 在 PATH 中排在 /mnt/c/ 之前7.4 模型调用报错检查 API Key 是否有效检查网络是否能访问模型 API 端点openclaw doctor诊断国内环境可能需要代理八、参考资源资源地址OpenClaw 官方文档https://docs.openclaw.aiGitHub 源码https://github.com/openclaw/openclawNode.js 下载https://nodejs.orgDeepSeek 平台https://platform.deepseek.com通义千问百炼https://bailian.console.aliyun.comFeishu Channelhttps://docs.openclaw.ai/channels/feishuWeChat Channelhttps://docs.openclaw.ai/channels/wechat配置参考https://docs.openclaw.ai/gateway/configuration-reference安装指南https://docs.openclaw.ai/getting-started/installationversion 0.0.0发布于2026-07-03