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

目录

一、环境要求
二、依赖安装（按平台）
三、部署 OpenClaw
四、外部渠道连接
五、部署验证
六、常用维护命令
七、常见问题排查
八、参考资源

一、环境要求

1.1 硬件要求

项目 最低要求 推荐配置
CPU x86_64 双核 4 核及以上
内存 4GB 可用 8GB+
磁盘 2GB 可用 10GB+
网络 可访问模型 API 端点 宽带连接

未搜索到 OpenClaw 官方硬件要求文档，以上基于实际部署经验。

1.2 软件要求

要求 版本 说明
Node.js ≥ v22.19.0（推荐 v24.x） 核心运行时
npm ≥ 10.x 包管理器，随 Node 安装
终端 各平台推荐终端见下
浏览器 Chrome / Edge 最新版 访问 Control UI

1.3 各平台终端推荐

平台 推荐终端 检查命令
Windows PowerShell 7+ / Windows Terminal pwsh --version
Linux bash / zsh echo $SHELL
macOS zsh（默认） / bash echo $SHELL
WSL bash（默认） / zsh echo $SHELL

1.4 通用环境检查

# 操作系统
uname -a                  # Linux / macOS / WSL
winver                    # Windows（运行对话框运行）

# Node.js
node --version            # 需要 >= v22.19.0

# npm
npm --version             # 建议 >= 10.x

# 内存
free -h                   # Linux / WSL / macOS
systeminfo | findstr "物理内存"  # Windows

# 磁盘
df -h /                   # Linux / WSL / macOS
wmic logicaldisk get size,freespace,caption  # Windows

二、依赖安装（按平台）

2.1 Windows

方案 A：官方安装包（推荐）

  1. 访问 nodejs.org 下载 LTS 版
  2. 运行安装程序，全程默认选项
  3. 重启终端后验证：
node --version
npm --version

方案 B：winget

winget install OpenJS.NodeJS.LTS

方案 C：fnm（推荐开发人员使用）

winget install fnm
fnm install 24
fnm use 24
fnm default 24

2.2 Linux（Ubuntu / Debian）

方案 A：NodeSource 官方源

# 安装 Node.js 24.x
curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash -
sudo apt-get install -y nodejs

# 验证
node --version
npm --version

方案 B：nvm（推荐）

# 安装 nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.4/install.sh | bash

# 重新加载 shell
source ~/.bashrc

# 安装并使用 Node.js 24
nvm install 24
nvm use 24
nvm alias default 24

配置 npm 全局安装路径（避免 sudo）：

mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

2.3 macOS

方案 A：Homebrew（推荐）

# 安装 Homebrew（如未安装）
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# 安装 Node.js 24
brew install node@24
brew link --overwrite node@24

# 验证
node --version
npm --version

方案 B：nvm

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.4/install.sh | bash
source ~/.zshrc   # macOS 默认 zsh
nvm install 24
nvm use 24
nvm alias default 24

2.4 WSL（Windows Subsystem for Linux）

WSL 中的安装方法同 2.2 Linux 章节（NodeSource 或 nvm）。

WSL 环境特殊配置：

# 确保 npm 全局安装路径在 PATH 中
export PATH="$HOME/.npm-global/bin:$PATH"

# 并写入 .bashrc 持久化
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.bashrc

⚠️ 注意：Windows 的 npm 路径（/mnt/c/Users/.../npm）可能影响 WSL 中命令解析。
确保 WSL 原生安装路径在 PATH 中排在更前面。

三、部署 OpenClaw

3.1 安装

# 所有平台通用
npm install -g openclaw

# 验证
openclaw --version
# 输出示例：OpenClaw 2026.6.8 (844f405)

💡 国内网络加速：

npm config set registry https://registry.npmmirror.com

3.2 首次配置（引导式）

openclaw onboard

引导流程依次询问：

步骤 说明 建议值
运行模式 本地运行还是远程连接 local（个人使用）
模型提供商 选择 API 提供商 DeepSeek / Qwen / OpenAI 等
API Key 输入密钥 从对应平台获取
Gateway 端口 服务监听端口 18789
认证方式 访问控制 token（推荐）
Agent 名称 给你的智能体命名 自定义

API Key 获取地址：

提供商 控制台地址
DeepSeek https://platform.deepseek.com/api_keys
通义千问/Qwen https://bailian.console.aliyun.com/
OpenAI https://platform.openai.com/api-keys

3.3 快速配置（非交互式）

# Linux / macOS / WSL
openclaw onboard --non-interactive --mode local \
  --auth-choice deepseek-api-key \
  --deepseek-api-key "sk-你的API_KEY" \
  --skip-health --accept-risk

# Windows PowerShell（反引号换行）
openclaw onboard --non-interactive --mode local `
  --auth-choice deepseek-api-key `
  --deepseek-api-key "sk-你的API_KEY" `
  --skip-health --accept-risk

3.4 配置文件参考

路径：~/.openclaw/openclaw.json（JSON5 格式，支持注释）

{
  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 Gateway

3.5 启动 Gateway

# 通用启动
openclaw gateway start

# 指定端口
openclaw gateway start --port 18789

# 局域网可访问
openclaw gateway start --bind lan

# 查看实时日志
openclaw logs --follow

--bind 可选值：

值 说明 适用场景
loopback 仅本地 127.0.0.1 默认，安全
lan 局域网可访问 需要从其他设备访问
tailnet Tailscale 网络 通过 Tailscale 远程访问
auto 自动选择 通用
custom 自定义 高级用户

3.6 各平台开机自启

Windows（Startup 文件夹）：

$shortcut = "$env:APPDATA\Microsoft\Windows\Start Menu\Programs\Startup\OpenClaw.lnk"
$wshell = New-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 / macOS（systemd 用户服务）：

# 如果系统支持 systemd（多数 Linux 发行版）
openclaw gateway start  # 自动创建 systemd 用户服务

# 检查服务状态
systemctl --user status openclaw-gateway.service

# macOS（使用 launchd）
# OpenClaw 自动处理 macOS 的 launchd 配置

WSL（.bashrc / .profile）：

# 在 ~/.bashrc 末尾添加
if ! pgrep -f "gateway --port" > /dev/null 2>&1; then
  nohup openclaw gateway start > /dev/null 2>&1 &
fi

四、外部渠道连接

4.1 飞书 / Lark

飞书是 OpenClaw 内置支持的渠道（需版本 ≥ 2026.5.29）。

前置条件： 在 飞书开放平台 创建应用，获取 App ID 和 App Secret。

配置：

# 运行设置向导
openclaw channels login --channel feishu

# 选择手动模式输入 App ID + App Secret
# 或选择二维码模式自动创建机器人

# 重启 Gateway
openclaw gateway restart

访问控制：

# 私聊策略
openclaw config set channels.feishu.dmPolicy pairing

# 群聊策略
openclaw config set channels.feishu.groupPolicy allowlist

# 要求 @提及
openclaw config set channels.feishu.requireMention true

# 批准配对
openclaw pairing list feishu
openclaw pairing approve feishu <CODE>

参考：https://docs.openclaw.ai/channels/feishu

4.2 个人微信

通过腾讯外部插件 @tencent-weixin/openclaw-weixin 连接。

安装：

# 方式一（推荐）
npx -y @tencent-weixin/openclaw-weixin-cli install

# 方式二：手动安装
openclaw plugins install "@tencent-weixin/openclaw-weixin"
openclaw config set plugins.entries.openclaw-weixin.enabled true
openclaw gateway restart

登录：

openclaw channels login --channel openclaw-weixin
# 用手机微信扫描终端二维码

兼容性：

插件版本 OpenClaw 版本 npm 标签
2.x >= 2026.3.22 latest
1.x >= 2026.1.0, < 2026.3.22 legacy

参考：https://docs.openclaw.ai/channels/wechat

4.3 钉钉

❌ 未发现 OpenClaw 官方钉钉频道支持。

替代方案：

  1. 钉钉群机器人 webhook + 中间服务转发到 OpenClaw API
  2. 参照 Channel Plugin SDK 开发自定义插件

4.4 企业微信

❌ 未发现 OpenClaw 官方企业微信频道支持。

替代方案：

  1. 企业微信群机器人 webhook 转发
  2. 自定义渠道插件

企业微信与个人微信的账号体系不互通，openclaw-weixin 插件不能用于企业微信。

五、部署验证

5.1 服务状态

# 通用检查
openclaw status
openclaw config validate
openclaw models status
openclaw doctor

5.2 Web UI

  • 浏览器打开 http://localhost:18789
  • 应看到 OpenClaw Control UI 登录页面
  • 用配置的 token 或密码登录

5.3 模型测试

# 终端测试
openclaw chat --message "你好，能正常交流吗？" --model deepseek/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 models set <provider/model>        # 切换默认模型
openclaw models status                      # 查看当前
openclaw models list                        # 列出所有
openclaw models fallbacks add <model>       # 添加备选
/model <model>                              # 聊天时临时切换

6.3 配置管理

openclaw config show                        # 查看配置
openclaw config set gateway.port 18790      # 修改配置
openclaw doctor                             # 诊断
openclaw doctor --fix                       # 自动修复

# 添加模型白名单（--merge 合并）
openclaw config set agents.defaults.models '{"new-model":{}}' --strict-json --merge

6.4 更新

npm update -g openclaw     # 更新 OpenClaw
openclaw --version          # 查看版本

七、常见问题排查

7.1 Gateway 启动失败

现象 可能原因 解决方法
端口被占用 另一进程占用了端口 netstat -ano | findstr :18789（Windows）
ss -tlnp | grep 18789（Linux/macOS/WSL）
“Invalid --bind” bind 值不对 只能使用 loopback/lan/tailnet/auto/custom
Node 版本错误 Node.js < v22.19 node --version 检查，升级 Node.js
npm 安装失败 权限问题 用管理员终端（Windows）或 sudo（Linux/macOS）

7.2 Web UI 打不开

  1. 确认 Gateway 已启动（openclaw status）
  2. 检查防火墙是否放行端口
  3. 尝试 http://127.0.0.1:18789 而非 localhost
  4. 使用浏览器无痕模式排除插件干扰

7.3 WSL 特殊问题

# localhost 从 Windows 无法访问
# 方案一：用 netsh portproxy 转发
netsh interface portproxy add v4tov4 listenport=18790 listenaddress=127.0.0.1 connectport=18790 connectaddress=172.29.x.x

# 方案二：将 bind 改为 lan，通过 WSL2 IP 访问
openclaw config set gateway.bind lan

# systemd 用户服务端口硬编码
# 检查并修改 ~/.config/systemd/user/openclaw-gateway.service 中的 --port 值

# npm 路径冲突
# 确保 ~/.npm-global/bin 在 PATH 中排在 /mnt/c/ 之前

7.4 模型调用报错

  1. 检查 API Key 是否有效
  2. 检查网络是否能访问模型 API 端点
  3. openclaw doctor 诊断
  4. 国内环境可能需要代理

八、参考资源

资源 地址
OpenClaw 官方文档 https://docs.openclaw.ai
GitHub 源码 https://github.com/openclaw/openclaw
Node.js 下载 https://nodejs.org
DeepSeek 平台 https://platform.deepseek.com
通义千问百炼 https://bailian.console.aliyun.com
Feishu Channel https://docs.openclaw.ai/channels/feishu
WeChat Channel https://docs.openclaw.ai/channels/wechat
配置参考 https://docs.openclaw.ai/gateway/configuration-reference
安装指南 https://docs.openclaw.ai/getting-started/installation

version 0.0.0
发布于2026-07-03

Logo
智能体开发者社区

中国智能体开发者社区，聚焦智能体与大模型开发，提供前沿资讯、实用工具链、开源项目及行业案例。通过技术沙龙、开发者大赛等活动，促进经验交流与协作，助力开发者快速构建创新智能应用。

更多推荐

cover

基于vue多维数据融合与混合推荐算法的智能旅行规划系统设计与实现

avatar 智能体开发者社区
cover

2026 年，最适合 AI 搜索可见性的 AI 建站工具怎么选？

avatar 智能体开发者社区
cover

GLM-5.2、DeepSeek-V4-flash、Qwen3免费领 记得调好闹钟

avatar 智能体开发者社区