OpenClaw 本地AI代理框架全平台部署指南（2026版）｜从零开始精通Docker与K8s容器化部署

在AI工具爆炸式增长的今天，如何安全、高效地在本地运行一个真正能“干活”的AI代理？OpenClaw 正是为此而生。本文将为你提供一份覆盖 Windows、macOS、Linux 三大平台的保姆级部署教程，深度结合 容器化部署、Docker、Kubernetes（K8s）等现代容器编排技术，助你轻松搭建属于自己的隐私优先AI网关。

一、OpenClaw 是什么？核心能力一览

OpenClaw 是一款开源的本地AI代理框架，核心理念是“本地优先，隐私安全”。它不仅仅是聊天机器人，更是一个能访问本地文件、执行系统命令、调用第三方API 的智能助手。你可以通过它打通飞书、钉钉、TG 等聊天应用，并接入 OpenAI、Kimi、智谱 GLM 等主流大模型。

关键特性：

• 完全本地部署，数据不出门
• ⚙️ 支持 容器化部署（Docker / K8s），便于运维与扩展
• 多模型兼容，自由切换
• 文件系统交互，真正替你“干活”

本文作者： 圣殿骑士
版本适配： OpenClaw 最新版（2026年4月更新）
难度： ⭐⭐☆☆☆ 零基础友好，建议收藏后按步骤操作

二、环境要求：你的机器准备好了吗？

在开始之前，请确认你的环境满足以下最低要求。如果你的目标是生产级部署，强烈建议结合 容器编排 工具（如 Docker Compose 或 Kubernetes）来管理 OpenClaw 实例。

要求项	最低版本	推荐版本
Node.js	v22.16+	v24 LTS
操作系统	Windows 10 / macOS 12 / Linux	Windows 11 / macOS 14 / Ubuntu 22.04
内存	4GB	8GB+
网络	可访问 npm / GitHub	全球可访问（或配置镜像）

⚠️ 注意：Windows 用户建议使用 WSL2 以获得最佳 Docker 体验。macOS 用户推荐使用 Apple Silicon 芯片以发挥最大性能。

简单理解：OpenClaw = 可以在本地运行的"超级 AI 助手"，所有数据不出本机，隐私有保障。

三、安装 Node.js：全平台实战步骤

OpenClaw 基于 Node.js 构建，因此第一步是安装 Node.js 环境。我们强烈推荐使用 NVM（Node Version Manager）来管理 Node.js 版本，避免版本冲突。

3.1 Windows 用户（推荐 NVM 方式）

首先，下载并安装 NVM for Windows：访问 nvm-windows releases 页面，获取最新版 nvm-setup.exe，双击安装。然后以管理员身份打开 PowerShell，执行以下命令：

nvm install 22.22.0
nvm use 22.22.0

验证安装是否成功：

node -v
# 输出：v22.22.0
npm -v
# 输出：10.x.x

3.2 macOS / Linux 用户

macOS/Linux 用户同样推荐使用 nvm：

# 安装 nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
# 重载配置
source ~/.bashrc   # 或 source ~/.zshrc
# 安装 Node.js 22
nvm install 22
nvm use 22
nvm alias default 22

如果你偏好传统方式，也可以直接下载安装包：

node -v   # v22.x.x
npm -v    # 10.x.x

四、安装 OpenClaw：四种方式深度解析

OpenClaw 提供四种安装方式，从新手到专家，从单机到 容器编排，总有一款适合你。

方式一：一键脚本安装（⭐ 推荐新手）

macOS / Linux / WSL2 用户：

curl -fsSL https://openclaw.ai/install.sh | bash

Windows PowerShell（管理员模式）：

# 先放开执行策略
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
# 执行安装
iwr -useb https://openclaw.ai/install.ps1 | iex

⚠️ Windows 用户特别说明：官方强烈建议在 WSL2（适用于 Linux 的 Windows 子系统） 下运行，以获得最佳体验。若坚持在原生 Windows 下运行，请以管理员身份打开 PowerShell。

方式二：npm 手动安装

若网络受限，可使用 npm：

# 全局安装
npm install -g openclaw@latest
# 安装后初始化
openclaw onboard --install-daemon

pnpm 用户：

pnpm add -g openclaw@latest
pnpm approve-builds -g
openclaw onboard --install-daemon

方式三：Docker 部署（ 生产级推荐）

对于服务器或 VPS 环境，Docker 是最佳选择。它提供了环境隔离和易于管理的特性。如果你未来计划迁移到 Kubernetes（K8s），Docker 镜像可直接用于容器编排。

docker run -d \
--name openclaw \
--restart unless-stopped \
-p 18789:18789 \
-v ~/.openclaw:/root/.openclaw \
openclaw/openclaw:latest

使用 Docker Compose 管理（推荐）：

# docker-compose.yml
version: "3.8"
services:
openclaw:
image: openclaw/openclaw:latest
container_name: openclaw
restart: unless-stopped
ports:
- "18789:18789"
volumes:
- ~/.openclaw:/root/.openclaw

docker compose up -d

进阶提示：在生产环境中，你可以将 OpenClaw 容器化后部署到 Kubernetes 集群，利用 K8s 的自动伸缩、滚动更新等特性实现高可用。

方式四：从源码构建（开发者）

# 克隆仓库
git clone https://github.com/openclaw/openclaw.git
cd openclaw
# 安装依赖（需要 pnpm）
npm install -g pnpm
pnpm install
# 构建
pnpm ui:build
pnpm build
# 全局链接
pnpm link --global
# 初始化
openclaw onboard --install-daemon

五、初始化配置（onboard）

安装完成后，必须运行初始化命令：

openclaw onboard

这是一个交互式向导，你将配置管理员账号、端口、存储路径等核心参数：

? 是否了解并接受风险告知？ → 选择 Yes
? 请选择启动模式 → 选择 QuickStart（新手推荐）
? 请配置 AI 模型 API Key → 输入你的 API Key（如智谱 GLM-4、OpenAI 等）
? 通讯平台配置 → 选择 skip for now（稍后再配置）
? 是否安装 Skills 扩展包 → 选择 NO（稍后按需安装）
? Hooks 配置 → 选择 skip for now

安装脚本会自动检测你的环境、安装 CLI 和依赖，并自动启动初始化向导，全程约 2-5 分钟。

六、启动服务与验证

6.1 启动网关

openclaw gateway start

你也可以将其设为后台服务：

# 后台启动（daemon 模式）
openclaw gateway start --daemon

6.2 打开 Dashboard

新开终端窗口：

openclaw dashboard

获取 API Key：

• 智谱 AI（GLM）：https://open.bigmodel.cn/
• OpenAI：https://platform.openai.com/
• Moonshot（Kimi）：https://platform.moonshot.cn/

6.3 验证安装状态

# 综合诊断
openclaw doctor
# 查看网关状态
openclaw gateway status
# 查看系统状态
openclaw status

七、配置 AI 模型：接入你的大模型

在 Dashboard 中，点击“模型配置”或使用命令行：

openclaw config

以下是三个常见模型的配置示例：

• 智谱 AI（GLM-4.6 / 4.7）：

  {
  "provider": "zhipu",
  "model": "glm-4-plus",
  "apiKey": "your-api-key-here",
  "baseURL": "https://open.bigmodel.cn/api/paas/v4/"
  }

• OpenAI / 兼容接口：

  {
  "provider": "openai",
  "model": "gpt-4o",
  "apiKey": "sk-xxxx",
  "baseURL": "https://api.openai.com/v1"
  }

• Moonshot（Kimi）：

  {
  "provider": "openai",
  "model": "moonshot-v1-8k",
  "apiKey": "your-api-key-here",
  "baseURL": "https://api.moonshot.cn/v1"
  }

八、接入飞书机器人（可选）

8.1 安装飞书插件

openclaw plugins install @m1heng-clawd/feishu

8.2 在飞书开放平台创建应用

访问飞书开放平台，创建“企业自建应用”，导入权限配置：

["im:message", "im:message.group_at_msg", "im:message.p2p_msg",
"im:resource", "im:message:send_as_bot"]

在“事件订阅”中选择“长连接”模式，添加事件 im.message.receive_v1，然后发布应用版本。

8.3 绑定机器人到 OpenClaw

# 在 OpenClaw 中启动飞书绑定
openclaw bind feishu

按终端提示操作：在飞书中向机器人发送任意消息，机器人会回复配对码，粘贴到终端即可完成绑定。

九、常用维护命令

# 查看日志（实时）
openclaw logs --follow
# 重启网关
openclaw gateway restart
# 停止网关
openclaw gateway stop
# 更新到最新版
npm update -g openclaw
# 系统诊断
openclaw doctor
# 重新配置
openclaw config

十、常见问题 & 排错

• ❓ 问题1：命令 openclaw 找不到：npm 全局路径未加入 PATH。解决方案：

  # 查看 npm 全局安装目录
  npm prefix -g
  # 将其 bin 目录加入 PATH（以下以 Linux/macOS 为例）
  echo 'export PATH="$(npm prefix -g)/bin:$PATH"' >> ~/.bashrc
  source ~/.bashrc

• ❓ 问题2：Dashboard 打不开：检查步骤：

  # 1. 确认网关是否正在运行
  openclaw gateway status
  # 2. 查看实时日志
  openclaw logs --follow
  # 3. 尝试重启网关
  openclaw gateway restart

  ；确认端口 18789 未被占用：

  # Windows
  netstat -ano | findstr :18789
  # Linux / macOS
  lsof -i :18789

• ❓ 问题3：Windows PowerShell 提示“不允许执行脚本”：解决方案：

  Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass

• ❓ 问题4：API Key 调用失败：检查 API Key 是否正确、未过期，baseURL 是否填写正确，账号余额是否充足，网络是否可达。
• ❓ 问题5：初始化失败 / onboard 卡住：

  # 重新运行初始化
  openclaw onboard
  # 如果还不行，清除配置重试
  rm -rf ~/.openclaw   # Linux/macOS
  # Windows: 删除 C:\Users\用户名\.openclaw 文件夹
  openclaw onboard --install-daemon

十一、安全建议

这会自动打开浏览器，访问地址为：http://127.0.0.1:18789
也可以手动打开浏览器，输入该地址访问。

• 隔离部署：不建议在主力生产机上直接部署，优先使用虚拟机或云服务器，结合 容器化部署 实现环境隔离。
• 最小权限原则：不要赋予 AI 不必要的高权限，尤其是在 K8s 环境中，应使用 RBAC 控制访问。
• 定期更新：及时更新到最新版本，修复已知安全漏洞。
• 网络隔离：如部署在服务器上，建议配置防火墙，限制 Dashboard 端口的访问来源。
• API Key 保护：不要将含 API Key 的配置文件提交到公开代码仓库。

⚠️ OpenClaw 具有执行系统命令的能力，请务必注意以下安全事项！

十二、环境变量参考

变量名	说明	示例
	OpenClaw 主目录路径
	可变状态数据存储路径
	配置文件路径

十三、总结与延伸

至此，你已完成 OpenClaw 的完整部署！整个流程回顾：

步骤	内容	状态
1	安装 Node.js 22+	✅
2	安装 OpenClaw	✅
3	运行 初始化	✅
4	启动网关服务	✅
5	访问 Dashboard	✅
6	配置 AI 模型 API Key	✅
7	（可选）接入飞书/钉钉等平台	⚙️ 按需

进阶推荐：如果你正在搭建生产级 AI 网关，不妨将 OpenClaw 与 容器编排 工具（如 Docker Swarm 或 Kubernetes）结合使用，实现自动扩缩容与滚动更新。未来，随着多集群管理的普及，OpenClaw 在 K8s 生态中的潜力巨大。

如果你对本文有任何疑问，或者想了解更多关于 容器化部署 的最佳实践，欢迎在评论区留言交流！

参考资料

• OpenClaw 官方文档：https://docs.openclaw.ai/
• OpenClaw GitHub：https://github.com/openclaw/openclaw
• 飞书开放平台：https://open.feishu.cn/

如果本文对你有帮助，欢迎点赞 收藏 ⭐ 关注！有任何问题欢迎在评论区留言。

最后更新：2026年4月

OPENCLAW_HOME/home/user/.openclawOPENCLAW_STATE_DIR/var/openclaw/stateOPENCLAW_CONFIG_PATH/etc/openclaw/config.jsonopenclaw onboard