2026年7月19日

OpenClaw 中文版完整部署手册（Eword版本）

转载请注明来源:https://www.cnblogs.com/eword/
Author：eword
Email:eword@139.com

前置总览与资源说明
前置统一工具：mirror-switcher 全平台镜像一键切换
方案一：Docker 容器化一键部署（全平台通用）
方案二：原生 npm 部署（分 macOS / Windows / 信创系统）
两种部署方案优劣对比与选型建议
配置详解：初始化向导、大模型与企业微信渠道接入
进阶运维与生产化部署
更新与升级
常见问题排查
附录 A：Anaconda / Miniconda 官方下载与源配置

1. 前置总览与资源说明

1.1 仓库镜像优先级（优先 Gitee）

原始 GitHub 地址	国内 Gitee 镜像地址（推荐）
`https://github.com/OpenClawAI/OpenClaw.git`	`https://gitee.com/mirrors_ai/OpenClaw.git`

1.2 部署环境说明

本手册提供两种独立部署方案，可按需二选一：

Docker 部署：零环境依赖，一条命令拉起，跨系统环境完全一致，适合快速部署、批量上线
原生 npm 部署：不使用容器，技术栈为 nvm（Node 版本管理）+ 原生 nrm 源管理 + Node.js + Anaconda（Python 可选环境）；OpenClaw 本身为 Node.js 全局工具，通过 npm 安装后直接使用 openclaw 命令，Python 环境用于插件与扩展能力

1.3 源管理双方案说明

推荐方案：使用 mirror-switcher 一键统一管理 npm/pip/conda/docker/git/apt/brew 全链路镜像，完整教程跳转：
《mirror-switcher（镜像切换工具 / Mirror Switcher）》https://www.cnblogs.com/eword/p/21636099
备选方案：保留原生独立 nrm 手动安装与源切换步骤，两种方式任选其一即可，无需重复配置。

1.4 适配操作系统

macOS（Intel x86_64 / Apple Silicon M 系列 arm64）
Windows 10 / Windows 11（64 位）
统信 UOS（AMD64 / ARM64 鲲鹏/飞腾）
银河麒麟 V10（AMD64 / ARM64）

2. 前置统一工具：mirror-switcher 全平台镜像一键切换

2.1 工具说明

部署全程涉及 npm、pip、conda、docker、homebrew、git、系统 apt/yum 源，全部统一使用 mirror-switcher 工具一键切换国内镜像，无需手动修改各类配置文件。
完整安装、命令、各生态源切换、国产系统适配、备份还原功能请查阅专属教程：

《mirror-switcher（镜像切换工具 / Mirror Switcher）》https://www.cnblogs.com/eword/p/21636099

2.2 部署 OpenClaw 核心切换命令速查

安装完成 mirror-switcher 并刷新终端环境后，执行以下命令完成全链路国内加速：

# 1. Node/npm 源切换淘宝镜像（替代 nrm）
switch-npm use tsinghua
# 2. Python pip 清华源
switch-pip use tsinghua
# 3. Anaconda/Miniconda conda 镜像
switch-conda use tsinghua
# 4. Docker 镜像加速器（ghcr.io 加速拉取）
switch-docker use 163
# 5. Git GitHub 代理加速（克隆 Gitee 无需，拉取 GitHub 仓库使用）
switch-git use ghproxy
# 6. macOS Homebrew 镜像（macOS 专属）
switch-brew use tsinghua
# 7. 国产信创系统（麒麟/统信）apt 软件源
switch-apt use tsinghua

2.3 快速安装入口

macOS / Linux（麒麟/统信）一键安装

bash <(curl -fsSL https://gitee.com/eword/mirror-switcher/raw/main/bootstrap.sh)
source ~/.zshrc  # zsh 终端
# source ~/.bashrc  # bash 终端

Windows PowerShell 一键安装

iwr -useb https://gitee.com/eword/mirror-switcher/raw/main/bootstrap.ps1 | iex

完整参数、指定工具安装、卸载、测速、备份还原、国产系统适配逻辑，详见博客：
https://www.cnblogs.com/eword/p/21636099

3. 方案一：Docker 容器化一键部署（全平台通用）

3.1 各系统 Docker 前置安装

macOS

安装 Docker Desktop 即可，界面语言不影响终端 CLI 命令执行。安装完成后执行前置工具切换镜像：

switch-docker use 163

Windows

安装 Docker Desktop，开启 WSL2 后端；安装 mirror-switcher 后执行：

switch-docker use 163

统信 UOS / 银河麒麟（信创 Linux）

sudo apt update
sudo apt install docker.io docker-compose -y
sudo systemctl enable --now docker
sudo usermod -aG docker $USER
newgrp docker
# 切换系统 apt 源 + docker 镜像加速器
switch-apt use tsinghua
switch-docker use 163

Docker 镜像加速器配置无需手动修改 daemon.json / Desktop 配置，统一使用 switch-docker 命令，用法详见第 2 章。

3.2 镜像拉取与验证

3.2.1 镜像地址说明

OpenClaw 中文版 Docker 镜像提供两个可用地址，国内环境优先使用 Docker Hub 源，拉取成功率更高：

镜像仓库	完整地址	适用场景
Docker Hub	`1186258278/openclaw-zh:latest`	国内网络、配置通用镜像加速器
GitHub Container Registry	`ghcr.io/1186258278/openclaw-zh:latest`	海外网络、已配置 GH 代理

3.2.2 提前拉取镜像（推荐执行）

正式部署前先单独执行拉取命令，确认镜像完整下载，避免初始化过程中因网络中断导致配置失败。

国内环境推荐命令：

docker pull 1186258278/openclaw-zh:latest

海外/直连环境命令：

docker pull ghcr.io/1186258278/openclaw-zh:latest

3.2.3 验证拉取结果

docker images | grep openclaw

正常输出示例：

1186258278/openclaw-zh   latest    abcdef123456   2 weeks ago   5.36GB

3.2.4 拉取失败排查

网络超时：先执行 switch-docker use 163 配置国内镜像加速器，重启 Docker 后重试
ghcr.io 无法访问：更换为 Docker Hub 地址 1186258278/openclaw-zh:latest
架构不匹配：Apple Silicon / ARM 信创主机需确认镜像支持 arm64 架构，当前 latest 标签已支持多架构自动适配
磁盘空间不足：镜像约 5.3GB，确保本地磁盘剩余空间大于 10GB

3.3 部署标准两步流程

步骤 1：首次交互式初始化（仅执行 1 次）

--rm 含义：退出交互式终端（exit/Ctrl+D/关闭窗口）后自动销毁当前临时容器；
-v openclaw-data:/root/.openclaw 挂载独立数据卷，配置文件永久保存，不会随容器删除丢失。

若已提前拉取镜像，本条命令会直接启动容器，无需等待下载

docker run --rm -it -v openclaw-data:/root/.openclaw \
1186258278/openclaw-zh:latest openclaw onboard

执行后跟随向导填写大模型 API 密钥、用户名、存储路径、功能配置，配置完成输入 exit 退出终端，临时容器自动删除。

步骤 2：后台常驻启动网关服务（禁止添加 –rm）

添加 --rm 会导致容器停止即被删除，服务无法后台持久运行。

docker run -d --name openclaw \
-v openclaw-data:/root/.openclaw \
-p 18789:18789 \
1186258278/openclaw-zh:latest \
openclaw gateway --port 18789

3.4 服务访问地址

本机访问：http://localhost:18789
局域网其他设备访问：http://本机内网IP:18789

3.5 Docker 常用运维命令

# 停止服务
docker stop openclaw
# 重启服务
docker restart openclaw
# 实时查看运行日志
docker logs -f openclaw
# 查看本地镜像版本
docker images | grep openclaw
# 强制重新拉取最新镜像
docker pull 1186258278/openclaw-zh:latest
# 彻底卸载（删除容器+全部配置数据卷，数据不可恢复）
docker rm -f openclaw && docker volume rm openclaw-data
# 一键清理本机所有停止的废弃容器
docker container prune -f
# 清理无用旧镜像释放磁盘
docker image prune -f

4. 方案二：原生 npm 部署（分系统）

4.1 通用前置规范

二选一配置 npm 镜像源：
- 方案 A（推荐）：使用 switch-npm（mirror-switcher 工具）一键切换
- 方案 B：独立安装原生 nrm 手动管理镜像源
nvm 锁定 Node.js 20+ LTS 版本，规避版本兼容问题
（可选）Anaconda 创建 Python 环境，用于 OpenClaw 插件与脚本扩展
通过 npm 全局安装中文版 OpenClaw，安装完成后直接使用 openclaw 命令

4.2 macOS 原生部署

4.2.1 安装 Homebrew（无环境则执行）

/bin/bash -c "$(curl -fsSL https://mirrors.tuna.tsinghua.edu.cn/git/homebrew/install.git/raw/HEAD/install.sh)"
# 切换 brew 国内镜像
switch-brew use tsinghua

4.2.2 国内 GHProxy 镜像安装 nvm

curl -o- https://mirror.ghproxy.com/https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
# 写入 zsh 终端环境变量
echo 'export NVM_DIR="$HOME/.nvm"' >> ~/.zshrc
echo '[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"' >> ~/.zshrc
source ~/.zshrc

# 安装并固定 Node 20 长期支持版
nvm install 20
nvm use 20
nvm alias default 20

4.2.3 原生 nrm 独立安装（可选）

# 全局安装原生 nrm
npm install -g nrm
# 查看可用镜像源列表
nrm ls
# 切换淘宝 npm 镜像源
nrm use taobao
# 如需切回官方源执行 nrm use npm

若已使用 switch-npm 完成源切换，可跳过本小节，两种工具功能重合无需重复配置。

4.2.4（可选）安装 Anaconda Python 环境

用于 OpenClaw Python 插件、脚本执行扩展。安装包下载地址详见附录 A。
安装完成后初始化终端，切换 conda/pip 国内源：

conda init zsh
source ~/.zshrc
# conda 镜像切换
switch-conda use tsinghua
# pip 镜像切换
switch-pip use tsinghua

# 创建 OpenClaw 专属 Python 虚拟环境
conda create -n openclaw python=3.11 -y
conda activate openclaw

4.2.5 npm 全局安装 OpenClaw 中文版并部署启动

# 全局安装中文版 OpenClaw
npm install -g openclaw-zh@latest
# 验证安装
openclaw --version
# 首次初始化配置向导
openclaw onboard
# 前台启动网关服务
openclaw gateway --port 18789
# 后台常驻运行（日志写入文件）
nohup openclaw gateway --port 18789 > openclaw-run.log 2>&1 &

4.3 Windows 10/11 原生部署

4.3.1 nvm-windows 安装

安装包代理地址：
https://mirror.ghproxy.com/https://github.com/coreybutler/nvm-windows/releases/download/1.1.12/nvm-setup.exe
安装后打开 PowerShell/CMD 执行：

nvm install 20
nvm use 20
nvm alias default 20

4.3.2 原生 nrm 独立安装（可选）

npm install -g nrm
nrm ls
nrm use taobao

已使用 switch-npm 则可跳过。

4.3.3（可选）安装 Anaconda Python 环境

安装时勾选 Add Anaconda to my PATH environment variable，打开 Anaconda Prompt 终端：

switch-conda use tsinghua
switch-pip use tsinghua
conda create -n openclaw python=3.11 -y
conda activate openclaw

4.3.4 npm 全局安装 OpenClaw 中文版

npm install -g openclaw-zh@latest
openclaw --version
openclaw onboard
openclaw gateway --port 18789

4.4 统信 UOS / 银河麒麟（信创 Linux AMD64/ARM64 通用）

4.4.1 预装系统基础工具+切换系统源

sudo apt update && sudo apt install git curl wget -y
# 切换 apt 国产系统源
switch-apt use tsinghua

4.4.2 GHProxy 代理安装 nvm

curl -o- https://mirror.ghproxy.com/https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
echo 'export NVM_DIR="$HOME/.nvm"' >> ~/.bashrc
echo '[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"' >> ~/.bashrc
source ~/.bashrc

nvm install 20
nvm use 20
nvm alias default 20

4.4.3 原生 nrm 独立安装（可选）

npm install -g nrm
nrm ls
nrm use taobao

4.4.4（可选）安装 Anaconda Python 环境

安装包下载地址详见附录 A。

# 赋予执行权限并运行安装脚本
bash Anaconda3-xxx-Linux-xxx.sh
# 初始化 bash 终端
conda init bash
source ~/.bashrc
# 切换 conda、pip 国内镜像
switch-conda use tsinghua
switch-pip use tsinghua
# 创建专属虚拟环境
conda create -n openclaw python=3.11 -y
conda activate openclaw

4.4.5 npm 全局安装 OpenClaw 中文版并启动服务

npm install -g openclaw-zh@latest
openclaw --version
openclaw onboard
# 后台守护进程运行
nohup openclaw gateway --port 18789 > openclaw.log 2>&1 &

4.5 原生部署启停与彻底卸载

前台进程停止

快捷键 Ctrl + C 直接终止程序

后台 nohup 进程关闭

ps aux | grep "openclaw gateway"
kill -9 查到的进程 PID

一键清理卸载

# 卸载全局 openclaw 包
npm uninstall -g openclaw-zh
# 清理配置目录
rm -rf ~/.openclaw
# 可选：卸载 Python 虚拟环境
conda deactivate
conda remove -n openclaw --all -y
# 可选：卸载原生 nrm
npm uninstall -g nrm

5. 两种部署方案优劣对比与选型建议

部署方式	核心优点	短板	适用场景
Docker 容器部署	一键部署、环境强隔离、无依赖冲突、多设备部署一致性极强	额外占用少量磁盘存储空间	新手快速搭建、服务器批量部署、不想手动维护环境
原生 npm 部署	无容器额外开销、启动轻量、命令直接调用、插件扩展灵活	需要手动维护 Node 版本，系统环境差异可能导致兼容问题	日常开发使用、本地化定制、信创内网轻量化部署

6. 配置详解：初始化向导、大模型与企业微信渠道接入

6.1 配置文件路径全说明

6.1.1 主配置文件位置

OpenClaw 所有核心配置统一存放于用户主目录下的 .openclaw 目录中，不同系统路径如下：

操作系统	配置根目录	主配置文件
macOS / Linux（统信 UOS/银河麒麟）	`~/.openclaw/`	`~/.openclaw/openclaw.json`
Windows	`%USERPROFILE%\.openclaw\`	`%USERPROFILE%\.openclaw\openclaw.json`
Docker 容器内	`/root/.openclaw/`	`/root/.openclaw/openclaw.json`

6.1.2 目录结构说明

~/.openclaw/
├── openclaw.json          # 核心主配置文件（模型、渠道、网关、Agent等）
├── logs/                  # 运行日志目录
├── agents/                # 各智能体独立状态与记忆数据
├── workspaces/            # 工作空间文件与知识库向量数据
├── skills/                # 已安装技能插件
├── plugins/               # 已安装扩展插件
└── backups/               # 配置自动备份目录

6.1.3 配置修改生效方式

命令行修改（推荐）：执行 openclaw config set 键名值，自动热加载生效
手动编辑文件：修改 openclaw.json 后，执行 openclaw gateway restart 重启网关生效
Docker 部署：配置保存在 openclaw-data 数据卷中，可进入容器内部修改，或重启容器加载

6.2 初始化向导（openclaw onboard）全选项说明

执行 openclaw onboard 进入交互式初始化，各配置项说明如下：

配置项	可选值	说明与推荐选择
运行模式（Mode）	QuickStart / Advanced	QuickStart：快速启动，加载默认配置，新手推荐；Advanced：高级模式，逐项精细配置
模型提供商（Provider）	智谱 AI / 通义千问 / DeepSeek / Kimi / Ollama 等	选择你已获取 API Key 的大模型厂商，本文以智谱 AI 为例
默认模型（Default Model）	对应厂商下的模型列表	推荐选择轻量化高速模型，如智谱 `glm-4-flash`，日常交互响应快、成本低
API Key	字符串	填入对应模型厂商的 API 密钥，保存后加密存储
交互渠道（Channels）	Web 网关 / 企业微信 / 飞书 / 暂不配置	首次部署建议先选「暂不配置」，基础功能跑通后再追加渠道
基础技能（Skills）	启用 / 禁用	推荐启用，内置代码执行、文件读写、网络搜索等核心能力
技能安装源	npm / 本地	国内环境选 npm，配合镜像源加速安装
网关端口	默认 18789	可自定义，避免与本机其他服务端口冲突
访问控制	本地仅可访问 / 局域网可访问	生产环境建议先设为本地访问，配置反向代理后再开放局域网

初始化完成后，所有配置自动写入 openclaw.json，可随时通过命令或手动编辑修改。

6.3 大模型配置详解（以智谱 AI 为例）

6.3.1 前置准备

访问智谱 AI 开放平台：https://open.bigmodel.cn/
注册账号并完成实名认证
进入「API 密钥管理」页面，创建并复制 API Key

6.3.2 方式一：命令行一键配置（推荐）

# 启用智谱 AI 提供商
openclaw config set models.providers.zai.enabled true
# 配置 API 地址
openclaw config set models.providers.zai.baseUrl "https://open.bigmodel.cn/api/coding/paas/v4"
# 填入你的 API Key
openclaw config set models.providers.zai.apiKey "你的智谱 API Key"
# 设置默认主模型为 GLM-4-Flash
openclaw config set agents.defaults.model.primary "zai/glm-4-flash"
# 重启网关生效
openclaw gateway restart

6.3.3 方式二：配置文件完整示例

编辑 ~/.openclaw/openclaw.json，在 models 节点添加智谱配置：

{
  "models": {
    "mode": "merge",
    "providers": {
      "zai": {
        "enabled": true,
        "baseUrl": "https://open.bigmodel.cn/api/coding/paas/v4",
        "api": "openai-completions",
        "apiKey": "你的智谱 API Key",
        "models": [
          {
            "id": "glm-4-flash",
            "name": "GLM-4-Flash",
            "contextWindow": 128000,
            "maxTokens": 8192,
            "reasoning": false
          },
          {
            "id": "glm-4-plus",
            "name": "GLM-4-Plus",
            "contextWindow": 128000,
            "maxTokens": 4096,
            "reasoning": false
          },
          {
            "id": "glm-5",
            "name": "GLM-5",
            "contextWindow": 204800,
            "maxTokens": 131072,
            "reasoning": true
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "zai/glm-4-flash"
      }
    }
  }
}

保存后重启网关即可生效，支持同时配置多个模型，在 Web 界面可随时切换。

6.3.4 验证模型配置

# 查看已配置的所有模型列表
openclaw models ls
# 测试模型连通性
openclaw models test zai/glm-4-flash

6.4 企业微信渠道接入配置

OpenClaw 的企业微信能力以独立插件形式提供，需先通过 npx 安装插件再进行渠道配置。本章节优先推荐长连接 API 模式，配套全量命令行运维能力。

6.4.1 企业微信插件安装（前置必做）

原生 npm 部署环境

前置条件：已完成 Node.js 环境配置，且已通过 switch-npm use taobao 切换国内 npm 镜像，加速插件包拉取。

镜像源统一管理工具用法参见第 2 章。

使用 Node.js 原生 npx 工具直接执行插件安装脚本，无需依赖 openclaw 内置 plugin 子命令，自动适配本地 OpenClaw 配置目录：

# npx 一键安装中文版企业微信官方插件
npx @openclaw-zh/plugin-wecom install

命令说明：

npx 为 Node.js 自带工具，无需额外安装，自动拉取最新稳定版插件包
安装程序自动识别本地 ~/.openclaw 配置目录，完成渠道能力注册
安装全程无额外依赖，适配 nvm 管理的多版本 Node 环境

验证安装结果：

# 查看插件安装状态与版本
npx @openclaw-zh/plugin-wecom status
# 或通过 openclaw 查看已支持的渠道列表，确认 wecom 渠道已加载
openclaw channel ls

Docker 容器部署环境

1186258278/openclaw-zh:latest 中文版镜像已预装企业微信插件，无需额外安装即可直接配置使用。
若需手动更新/重新安装插件，进入容器后通过 npx 执行：

# 进入运行中的 openclaw 容器
docker exec -it openclaw bash
# npx 执行插件安装/更新
npx @openclaw-zh/plugin-wecom install
# 退出容器并重启服务生效
exit
docker restart openclaw

6.4.2 两种接入模式对比（长连接为首选推荐）

对比项	长连接 API 模式（推荐首选）	URL 回调模式（备选）
公网依赖	完全不需要，内网/本地部署即可用	必须有公网可访问的回调地址
核心凭证	Bot ID + Secret	CorpID + AgentID + Secret + Token + AESKey
连接方式	WebSocket 长连接，主动拉取消息	HTTP 回调，企业微信主动推送
适用场景	内网部署、信创环境、本地开发、无公网服务器	公网服务器部署、已有域名与 HTTPS
配置复杂度	低，两步完成配对	高，需配置回调地址、加密校验、可信 IP
消息延迟	极低，长连接实时推送	低，HTTP 实时回调

核心结论：90% 以上场景优先使用长连接模式；仅当必须使用自建应用、深度集成企业微信管理后台能力时，再使用回调模式。

6.4.3 长连接 API 模式（重点推荐）

长连接模式基于企业微信官方「智能机器人 API 模式」，通过 WebSocket 长连接主动订阅消息，无需公网 IP、无需配置回调 URL，是 OpenClaw 对接企业微信的标准方案。

第一步：企业微信侧创建 API 机器人

打开企业微信客户端，进入「工作台」→「智能机器人」→「创建机器人」→「手动创建」
填写机器人名称、选择可见范围，拉到页面底部点击「API 模式创建」
在 API 配置页，连接方式默认勾选「使用长连接」
复制页面生成的两个核心凭证，妥善保存：
- Bot ID：机器人唯一标识
- Secret：机器人鉴权密钥，点击「获取」按钮生成并复制
点击「保存」完成机器人创建，可按需修改头像与简介

第二步：OpenClaw 侧配置（命令行方式，推荐）

# 启用企业微信渠道
openclaw config set channels.wecom.enabled true
# 设置连接模式为长连接 websocket（默认值，显式声明更稳妥）
openclaw config set channels.wecom.connectionMode "websocket"
# 填入企业微信机器人 Bot ID
openclaw config set channels.wecom.botId "你的机器人 Bot ID"
# 填入机器人 Secret 密钥
openclaw config set channels.wecom.secret "你的机器人 Secret"
# 消息回复格式，支持 text / markdown
openclaw config set channels.wecom.messageType "markdown"
# 重启网关服务加载配置
openclaw gateway restart

第三步：配置文件完整示例

编辑 ~/.openclaw/openclaw.json（Docker 部署对应容器内 /root/.openclaw/openclaw.json），在 channels 节点添加：

{
  "channels": {
    "wecom": {
      "enabled": true,
      "connectionMode": "websocket",
      "botId": "wx_bot_xxxxxxxxxxxx",
      "secret": "你的机器人 Secret 密钥",
      "messageType": "markdown",
      "dmPolicy": "open",
      "groupPolicy": "open",
      "streamReply": true
    }
  }
}

保存后重启网关生效。

第四步：配对验证（长连接模式专属步骤）

打开企业微信客户端，在通讯录找到刚创建的机器人，进入聊天窗口
发送任意一条消息，机器人会自动回复一串配对码
回到部署终端，执行配对命令：

openclaw pairing approve wecom 收到的配对码

提示配对成功后，即可在企业微信内正常与 AI 对话，支持单聊与群聊 @机器人

PS : 强烈不建议使用npx安装时引导的扫二维码配对功能，因为扫二维码配对引导创建的机器人只能你自己使用，别人使用时是无法得到回复消息的，应该是企业微信的安全机制造成的，且无法找到配置入口。

长连接模式核心优势

零公网依赖：本地电脑、内网服务器、信创国产化主机均可直接对接，无需申请公网 IP、域名备案
配置极简：仅需 Bot ID + Secret 两个参数，无需处理加密、回调校验、可信 IP 白名单
安全性高：主动向外建立 WebSocket 连接，无需开放任何入站端口，符合等保与内网安全规范
自动重连：网络波动时自动断线重连，无需人工干预，服务稳定性强
流式回复：原生支持 Markdown 流式输出，对话体验与 Web 端一致

6.4.4 URL 回调模式（备选方案）

适用于需要使用企业微信自建应用、深度集成组织架构与后台接口的场景，需公网服务器与回调地址。

第一步：企业微信侧前置准备

登录企业微信管理后台：https://work.weixin.qq.com/
进入「应用管理」→「自建」→「创建应用」
填写应用名称、Logo，选择可见范围，创建完成
记录以下三个关键参数：
- CorpID：企业 ID，在「我的企业」页面底部查看
- AgentId：自建应用的应用 ID
- Secret：应用密钥，在应用详情页获取
进入应用「接收消息」板块，点击「设置 API 接收」，记录：
- Token：自定义，3-32 位字母数字组合
- EncodingAESKey：点击随机生成，复制保存

第二步：OpenClaw 侧配置（命令行方式）

# 启用企业微信渠道
openclaw config set channels.wecom.enabled true
# 设置连接模式为 webhook 回调
openclaw config set channels.wecom.connectionMode "webhook"
# 企业 ID
openclaw config set channels.wecom.corpId "你的企业 CorpID"
# 应用 AgentId
openclaw config set channels.wecom.agentId "你的应用 AgentId"
# 应用 Secret
openclaw config set channels.wecom.secret "你的应用 Secret"
# 消息校验 Token
openclaw config set channels.wecom.token "自定义的 Token"
# 消息加密密钥
openclaw config set channels.wecom.aesKey "生成的 EncodingAESKey"
# Webhook 回调路径
openclaw config set channels.wecom.webhookPath "/webhook/wecom"
# 重启网关生效
openclaw gateway restart

第三步：配置文件完整示例

在 openclaw.json 的 channels 节点添加：

{
  "channels": {
    "wecom": {
      "enabled": true,
      "connectionMode": "webhook",
      "corpId": "wwxxxxxxxxxxxxxx",
      "agentId": "1000001",
      "secret": "你的应用 Secret",
      "token": "OpenClawWeCom2026",
      "aesKey": "你的 EncodingAESKey",
      "webhookPath": "/webhook/wecom",
      "dmPolicy": "open",
      "groupPolicy": "open",
      "messageType": "markdown"
    }
  }
}

第四步：完成企业微信侧回调配置

回到企业微信管理后台「接收消息」设置页面
URL 填写：http://你的服务器公网IP:18789/webhook/wecom（生产环境建议用域名+HTTPS）
填入与 OpenClaw 配置一致的 Token 和 EncodingAESKey
点击「保存」，提示验证成功即完成接入

6.4.5 企业微信专属 CLI 命令大全

所有命令均可在终端直接执行，无需手动修改配置文件，覆盖日常运维、排障、测试全场景。

一、渠道基础管理

# 查看所有已安装的渠道列表
openclaw channel ls
# 查看企业微信渠道实时运行状态（连接状态、在线时长、累计消息数）
openclaw channel status wecom
# 启用企业微信渠道
openclaw channel enable wecom
# 禁用企业微信渠道
openclaw channel disable wecom
# 重启企业微信渠道连接（配置修改后生效、异常断连重连时使用）
openclaw channel restart wecom

二、配对管理（长连接模式专属）

# 查看所有待确认/已生效的配对设备列表
openclaw pairing ls wecom
# 批准用户配对请求（长连接模式首次对话必须执行）
openclaw pairing approve wecom 配对码
# 拒绝指定配对请求
openclaw pairing reject wecom 配对码
# 移除已生效的配对设备
openclaw pairing remove wecom 配对 ID

三、消息测试与连通性校验

# 向指定企业微信用户发送测试消息，验证渠道连通性
openclaw channel test wecom --user "企业微信用户名" --content "OpenClaw渠道连通性测试消息"
# 向指定企业微信群聊发送测试消息
openclaw channel test wecom --group "群聊名称" --content "群聊测试消息"

四、日志排查与问题定位

# 实时滚动查看企业微信渠道运行日志
openclaw channel logs wecom -f
# 导出最近 7 天的渠道日志到本地文件
openclaw channel logs wecom --days 7 > wecom-channel.log

五、插件版本管理（npx 原生命令）

# 查看当前企业微信插件的详细信息与版本号
npx @openclaw-zh/plugin-wecom info
# 更新企业微信插件到最新中文版
npx @openclaw-zh/plugin-wecom update
# 卸载企业微信插件，清理配置注册信息
npx @openclaw-zh/plugin-wecom uninstall

6.4.6 通用渠道策略说明

两种模式共用以下策略配置项：

dmPolicy：私聊消息策略，open 表示所有可见范围内成员私聊都可触发 AI
groupPolicy：群聊消息策略，open 表示群内 @机器人即可触发对话
messageType：消息格式，支持 text 纯文本和 markdown 富文本，推荐 markdown
streamReply：是否开启流式回复，长连接模式默认开启，体验更佳

6.5 常用配置命令速查

# 查看当前全部配置
openclaw config ls
# 查看指定配置项
openclaw config get models.providers.zai.apiKey
# 修改单个配置项
openclaw config set gateway.port 18790
# 备份当前配置
openclaw config backup
# 从备份恢复
openclaw config restore
# 重置为默认配置
openclaw config reset

7. 进阶运维与生产化部署

7.1 开机自启配置（全平台）

7.1.1 macOS 开机自启（LaunchDaemon 原生方式）

适用于 macOS 12+，系统级守护进程，用户未登录也可后台运行。

创建守护进程配置文件：

sudo tee /Library/LaunchDaemons/com.openclaw.gateway.plist << 'EOF'
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.openclaw.gateway</string>
    <key>ProgramArguments</key>
    <array>
        <string>/bin/zsh</string>
        <string>-c</string>
        <string>source ~/.zshrc && openclaw gateway --port 18789</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
    <key>StandardOutPath</key>
    <string>~/.openclaw/logs/daemon.log</string>
    <key>StandardErrorPath</key>
    <string>~/.openclaw/logs/daemon-error.log</string>
    <key>UserName</key>
    <string>root</string>
</dict>
</plist>
EOF

加载并启用自启：

# 创建日志目录
mkdir -p ~/.openclaw/logs
# 加载守护进程
sudo launchctl load -w /Library/LaunchDaemons/com.openclaw.gateway.plist
# 验证运行状态
sudo launchctl list | grep openclaw

关闭自启：

sudo launchctl unload -w /Library/LaunchDaemons/com.openclaw.gateway.plist

7.1.2 Windows 开机自启（服务方式）

推荐使用 nssm 将 OpenClaw 注册为系统服务，崩溃自动重启。

安装 nssm（已配置 mirror-switcher 可直接 scoop install nssm）
打开管理员 PowerShell 执行：

nssm install OpenClawGateway

在弹出窗口中配置：

Path：C:\Users\你的用户名\AppData\Roaming\npm\openclaw.cmd
Arguments：gateway --port 18789
Startup directory：C:\Users\你的用户名\.openclaw

启动服务：

nssm start OpenClawGateway

7.1.3 统信 UOS / 银河麒麟（Linux systemd 自启）

信创系统通用，标准 systemd 服务配置。

创建服务文件：

sudo tee /etc/systemd/system/openclaw.service << 'EOF'
[Unit]
Description=OpenClaw AI Gateway Service
After=network.target

[Service]
Type=simple
User=root
ExecStart=/bin/bash -c "source ~/.bashrc && openclaw gateway --port 18789"
Restart=always
RestartSec=5
StandardOutput=append:/root/.openclaw/logs/service.log
StandardError=append:/root/.openclaw/logs/service-error.log

[Install]
WantedBy=multi-user.target
EOF

启用并启动：

mkdir -p ~/.openclaw/logs
sudo systemctl daemon-reload
sudo systemctl enable --now openclaw
# 查看运行状态
sudo systemctl status openclaw

停止与禁用：

sudo systemctl stop openclaw
sudo systemctl disable openclaw

7.2 Nginx 反向代理与域名访问

适用于绑定内网域名、配置统一入口、多服务共用 80/443 端口。

前置条件

已安装 Nginx（信创系统 sudo apt install nginx，macOS brew install nginx）
已配置好内网 DNS 或 hosts 解析，例如 openclaw.internal.com 指向部署主机 IP

Nginx 配置示例

server {
    listen 80;
    server_name openclaw.internal.com;

    # 客户端请求体大小限制
    client_max_body_size 100M;

    location / {
        proxy_pass http://127.0.0.1:18789;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        
        # WebSocket 支持
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        
        # 超时配置
        proxy_connect_timeout 60s;
        proxy_read_timeout 300s;
        proxy_send_timeout 300s;
    }
}

生效操作

# 配置语法检查
nginx -t
# 重载配置
nginx -s reload

配置完成后，浏览器访问 http://openclaw.internal.com 即可进入 OpenClaw 界面。

7.3 HTTPS 加密访问配置

基于 Nginx 配置 SSL 证书，实现内网 HTTPS 加密访问。

配置示例（续接上方反向代理）

server {
    listen 443 ssl http2;
    server_name openclaw.internal.com;

    # SSL 证书路径
    ssl_certificate /etc/nginx/cert/openclaw.crt;
    ssl_certificate_key /etc/nginx/cert/openclaw.key;

    # SSL 安全配置
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers HIGH:!aNULL:!MD5;
    ssl_prefer_server_ciphers on;
    ssl_session_cache shared:SSL:10m;
    ssl_session_timeout 10m;

    client_max_body_size 100M;

    location / {
        proxy_pass http://127.0.0.1:18789;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

# 80 端口强制跳转 HTTPS
server {
    listen 80;
    server_name openclaw.internal.com;
    return 301 https://$host$request_uri;
}

内网自签证书快速生成

mkdir -p /etc/nginx/cert
openssl req -x509 -nodes -days 3650 -newkey rsa:2048 \
  -keyout /etc/nginx/cert/openclaw.key \
  -out /etc/nginx/cert/openclaw.crt \
  -subj "/CN=openclaw.internal.com"

7.4 多实例并行部署方案

同一台主机部署多个 OpenClaw 实例，分别使用不同配置、不同端口，适用于测试/生产环境隔离。

核心原理

通过指定不同的配置目录与端口，实现多实例独立运行，互不干扰。

部署步骤

创建实例 1（生产环境，端口 18789）：

# 初始化生产配置
OPENCLAW_HOME=~/.openclaw-prod openclaw onboard
# 后台启动
nohup openclaw gateway --port 18789 --home ~/.openclaw-prod > openclaw-prod.log 2>&1 &

创建实例 2（测试环境，端口 18790）：

# 初始化测试配置
OPENCLAW_HOME=~/.openclaw-test openclaw onboard
# 后台启动
nohup openclaw gateway --port 18790 --home ~/.openclaw-test > openclaw-test.log 2>&1 &

systemd 多实例服务配置（Linux 信创）

分别创建 openclaw-prod.service 与 openclaw-test.service 服务文件，修改对应端口与配置目录即可，配置模板参考 7.1.3 小节。

7.5 内网离线部署方案

适用于完全断网的信创内网环境，提前在联网机打包依赖，离线拷贝部署。

第一步：联网机准备离线包

安装好 Node.js 20.x、nrm、OpenClaw 全局包
导出 npm 全局离线包：

# 创建离线包目录
mkdir -p ~/openclaw-offline/node-packages
# 导出全局安装包
npm pack openclaw-zh --pack-destination ~/openclaw-offline/node-packages

打包 Node.js 运行时：

# 复制 node 二进制文件
cp $(which node) ~/openclaw-offline/
cp $(which npm) ~/openclaw-offline/

将整个 openclaw-offline 目录打包为 tar.gz。

第二步：离线目标机部署

解压离线包，配置 Node.js 环境变量
本地安装 OpenClaw：

npm install -g ./openclaw-zh-xxx.tgz

执行初始化与启动：

openclaw onboard
openclaw gateway --port 18789

7.6 数据备份与迁移指南

配置数据目录

OpenClaw 所有配置、模型密钥、会话数据默认存放于：

macOS/Linux：~/.openclaw/
Windows：C:\Users\用户名\.openclaw\

手动备份

# 全量备份配置目录
tar -czf openclaw-backup-$(date +%Y%m%d).tar.gz ~/.openclaw

迁移到新机器

在新机器完成 OpenClaw 基础安装
将备份包解压到对应用户目录下
重启 OpenClaw 服务即可完整恢复所有配置

Docker 部署数据备份

# 备份数据卷到本地 tar 包
docker run --rm -v openclaw-data:/data -v $(pwd):/backup alpine tar czf /backup/openclaw-data.tar.gz -C /data .

# 恢复数据卷
docker run --rm -v openclaw-data:/data -v $(pwd):/backup alpine tar xzf /backup/openclaw-data.tar.gz -C /data

8. 更新与升级

8.1 原生 npm 部署升级

# 查看当前版本
openclaw --version
# 升级到最新中文版
npm update -g openclaw-zh
# 重启网关服务生效

8.2 Docker 部署升级

# 拉取最新镜像
docker pull 1186258278/openclaw-zh:latest
# 删除旧容器（数据卷保留，配置不丢失）
docker rm -f openclaw
# 使用新镜像重新启动
docker run -d --name openclaw \
-v openclaw-data:/root/.openclaw \
-p 18789:18789 \
1186258278/openclaw-zh:latest \
openclaw gateway --port 18789

镜像加速配置统一使用 switch-docker 工具，完整用法参见第 2 章。

9. 常见问题排查

git clone Gitee 仓库超时
切换手机热点重试；或前往 Gitee 仓库页面手动下载 ZIP 压缩包解压后使用。如需拉取 GitHub 源码，执行 switch-git use ghproxy 开启代理加速，工具详情见第 2 章。
nvm 下载 Node.js 缓慢
提前设置 nvm 国内镜像环境变量再执行安装：

export NVM_NODEJS_ORG_MIRROR=https://npmmirror.com/mirrors/node
nvm install 20

npm 下载依赖缓慢二选一：

方式 1：switch-npm use taobao
方式 2：nrm use taobao

macOS Docker 提示权限拒绝
完全退出 Docker Desktop，打开「系统设置 → 隐私与安全性 → 完全磁盘访问权限」，添加 Docker.app 授权；Docker 镜像拉取慢执行 switch-docker use 163。
信创 ARM 架构 pip 依赖编译失败

switch-pip use huawei

switch-pip 内置华为云 ARM 专属镜像源，详细用法见第 2 章。

初始化向导 openclaw onboard 闪退
检查 Node.js 版本是否满足 20+，执行 node --version 确认；执行 switch-npm use taobao 修复 npm 包安装失败问题。
各类源配置错乱、需要恢复官方源

mirror-switcher 工具：统一执行 switch-xxx use official 一键恢复官方配置
原生 nrm 工具：nrm use npm 切回官方 npm 源
支持配置备份/还原，完整功能查看第 2 章引用博客。

10. 附录 A：Anaconda / Miniconda 官方下载与源配置

10.1 官方核心入口

Anaconda 全球官网首页：https://www.anaconda.com/download
官方归档仓库（所有历史版本根目录）：https://repo.anaconda.com/archive/
中文官方文档站点（国内访问更稳定）：https://docs.anaconda.net.cn/anaconda/install/

10.2 分系统官方直链（最新稳定版 Anaconda3-2025.12-2）

Windows x86_64（Win10/11 64 位）

https://repo.anaconda.com/archive/Anaconda3-2025.12-2-Windows-x86_64.exe

macOS

Apple Silicon M 系列 arm64 图形化 pkg 安装包

https://repo.anaconda.com/archive/Anaconda3-2025.12-2-MacOSX-arm64.pkg

Apple Silicon 终端 sh 脚本

https://repo.anaconda.com/archive/Anaconda3-2025.12-2-MacOSX-arm64.sh

Intel 老款 Mac x86_64

https://repo.anaconda.com/archive/Anaconda3-2025.12-2-MacOSX-x86_64.pkg

Linux（麒麟/统信/服务器）

AMD64/x86_64 通用服务器/台式机

https://repo.anaconda.com/archive/Anaconda3-2025.12-2-Linux-x86_64.sh

ARM64/aarch64 鲲鹏、飞腾信创国产主机

https://repo.anaconda.com/archive/Anaconda3-2025.12-2-Linux-aarch64.sh

10.3 清华大学国内高速镜像（优先推荐，无需FQ）

Anaconda 完整版镜像归档页

https://mirrors.tuna.tsinghua.edu.cn/anaconda/archive/
替换规则：将官方链接域名 repo.anaconda.com 改为 mirrors.tuna.tsinghua.edu.cn/anaconda 即可高速下载。

Miniconda 轻量化极简版（推荐服务器/信创使用，体积仅 50MB）

Miniconda 仅包含 conda 环境管理器+基础 Python，无预装冗余数据分析包，资源占用更小：

官方下载页：https://docs.conda.io/en/latest/miniconda.html
清华镜像归档页：https://mirrors.tuna.tsinghua.edu.cn/anaconda/miniconda/

10.4 conda 源切换统一工具

安装完成 mirror-switcher 后一条命令切换清华源：

switch-conda use tsinghua

备份、还原、自定义私有 conda 源、测速功能，参考第 2 章引用博客。

10.5 OpenClaw Python 扩展环境固定创建命令

conda create -n openclaw python=3.11 -y
conda activate openclaw

文章摘自：https://www.cnblogs.com/shylock/p/21643688/openclaw-zhong-wen-wan-zheng-bu-shu-shou-ce-eword

2026年7月
一	二	三	四	五	六	日
« 6月
		1	2	3	4	5
6	7	8	9	10	11	12
13	14	15	16	17	18	19
20	21	22	23	24	25	26
27	28	29	30	31

六狼博客

OpenClaw 中文版完整部署手册（Eword版本）

目录

1. 前置总览与资源说明

1.1 仓库镜像优先级（优先 Gitee）

1.2 部署环境说明

1.3 源管理双方案说明

1.4 适配操作系统

2. 前置统一工具：mirror-switcher 全平台镜像一键切换

2.1 工具说明

2.2 部署 OpenClaw 核心切换命令速查

2.3 快速安装入口

macOS / Linux（麒麟/统信）一键安装

Windows PowerShell 一键安装

3. 方案一：Docker 容器化一键部署（全平台通用）

3.1 各系统 Docker 前置安装

macOS

Windows

统信 UOS / 银河麒麟（信创 Linux）

3.2 镜像拉取与验证

3.2.1 镜像地址说明

3.2.2 提前拉取镜像（推荐执行）

3.2.3 验证拉取结果

3.2.4 拉取失败排查

3.3 部署标准两步流程

步骤 1：首次交互式初始化（仅执行 1 次）

步骤 2：后台常驻启动网关服务（禁止添加 –rm）

3.4 服务访问地址

3.5 Docker 常用运维命令

4. 方案二：原生 npm 部署（分系统）

4.1 通用前置规范

4.2 macOS 原生部署

4.2.1 安装 Homebrew（无环境则执行）

4.2.2 国内 GHProxy 镜像安装 nvm

4.2.3 原生 nrm 独立安装（可选）

4.2.4（可选）安装 Anaconda Python 环境

4.2.5 npm 全局安装 OpenClaw 中文版并部署启动

4.3 Windows 10/11 原生部署

4.3.1 nvm-windows 安装

4.3.2 原生 nrm 独立安装（可选）

4.3.3（可选）安装 Anaconda Python 环境

4.3.4 npm 全局安装 OpenClaw 中文版

4.4 统信 UOS / 银河麒麟（信创 Linux AMD64/ARM64 通用）

4.4.1 预装系统基础工具+切换系统源

4.4.2 GHProxy 代理安装 nvm

4.4.3 原生 nrm 独立安装（可选）

4.4.4（可选）安装 Anaconda Python 环境

4.4.5 npm 全局安装 OpenClaw 中文版并启动服务

4.5 原生部署启停与彻底卸载

前台进程停止

后台 nohup 进程关闭

一键清理卸载

5. 两种部署方案优劣对比与选型建议

6. 配置详解：初始化向导、大模型与企业微信渠道接入

6.1 配置文件路径全说明

6.1.1 主配置文件位置

6.1.2 目录结构说明

6.1.3 配置修改生效方式

6.2 初始化向导（openclaw onboard）全选项说明

6.3 大模型配置详解（以智谱 AI 为例）

6.3.1 前置准备

6.3.2 方式一：命令行一键配置（推荐）

6.3.3 方式二：配置文件完整示例

6.3.4 验证模型配置

6.4 企业微信渠道接入配置

6.4.1 企业微信插件安装（前置必做）

原生 npm 部署环境

Docker 容器部署环境

6.4.2 两种接入模式对比（长连接为首选推荐）

6.4.3 长连接 API 模式（重点推荐）

第一步：企业微信侧创建 API 机器人

第二步：OpenClaw 侧配置（命令行方式，推荐）

第三步：配置文件完整示例

第四步：配对验证（长连接模式专属步骤）

长连接模式核心优势

6.4.4 URL 回调模式（备选方案）

第一步：企业微信侧前置准备

第二步：OpenClaw 侧配置（命令行方式）

第三步：配置文件完整示例

第四步：完成企业微信侧回调配置