OpenClaw 篇一：开源 AI 代理介绍及安装

共计 10151 个字符，预计需要花费 26 分钟才能阅读完成。

[[OpenClaw]]（前身为 Clawdbot / Moltbot）是一个免费开源的自主 AI 代理框架，由奥地利开发者 Peter Steinberger 开发。与普通聊天机器人不同，OpenClaw 不只是回复文字，它能够操作文件系统、执行代码、管理外部 API，在用户授权下自主完成复杂任务。用户可以通过 [[WhatsApp]]、[[Telegram]]、[[Slack]]、[[Discord]]、[[Signal]]、iMessage、Microsoft Teams 等常见消息平台与之交互。

改名风波

OpenClaw 的改名历程是开源社区品牌管理的一个经典案例，短短数日内经历了两次改名。

Clawdbot 时期（2025 年 11 月 – 2026 年 1 月 27 日）

项目最初于 2025 年 11 月由 Peter Steinberger 发布，命名为 Clawdbot。项目源自他的个人 AI 助手 Clawd，名称灵感来自 [[Anthropic]] 的 [[Claude]] 平台，采用龙虾作为吉祥物。

Clawdbot 到 Moltbot（2026 年 1 月 27 日）

Anthropic 以商标相似性为由，礼貌地要求项目更名。Steinberger 将项目改名为 Moltbot，取自龙虾蜕壳（molting）的含义，象征项目的蜕变。

Moltbot 到 OpenClaw（2026 年 1 月 29-30 日）

Moltbot 这个名字发音困难，社区成员频繁读错。仅两天后，Steinberger 再次更名为 OpenClaw。

• Open 代表开源、社区驱动
• Claw 保留了龙虾爪的传统
• 团队提前完成了商标调查和社交媒体账号注册
• 官方网站迁移至 openclaw.ai
• 项目重新定位为模型无关的代理框架

改名带来的安全混乱

频繁改名导致了一系列安全问题。改名当天，恶意 VS Code 扩展「ClawdBot Agent」就出现在插件市场，诈骗者在改名后数秒内抢注了废弃的 @clawdbot Twitter 账号。

安全研究人员在 2026 年 1 月 27 日至 2 月 2 日期间发现超过 400 个恶意软件包，其中 341 个经确认为恶意 Skills，335 个会安装 Atomic Stealer（AMOS）macOS 恶意软件，许多伪装成加密货币交易工具。此外，研究人员扫描到了 42665 个公开暴露的 OpenClaw 实例。

这一事件提醒所有开源项目维护者，改名不仅是品牌问题，更是安全问题，废弃的命名空间可能迅速被恶意行为者利用。

核心功能

消息平台集成

OpenClaw 支持的平台涵盖了主流即时通讯工具，包括 [[WhatsApp]]、[[Telegram]]、[[Slack]]、[[Discord]]、Google Chat、[[Signal]]、iMessage（通过 BlueBubbles）、Microsoft Teams、WebChat、Matrix、Zalo 等。用户可以直接在日常使用的聊天工具中向 AI 下达指令。

自主代理能力

OpenClaw 具备真正的自主代理能力。

• 浏览器自动化，可以自动执行网页任务
• 文件读写操作，直接管理本地文件
• Shell 命令执行，在服务器上运行任意命令
• 定时任务（Cron Jobs），按计划自动执行工作
• 沙箱模式，隔离环境中安全执行代码

持久化长期记忆

OpenClaw 将上下文数据存储在本地，AI 可以持续记住用户偏好、进行中的项目和个人细节，不会因为对话结束而遗忘。这使得 AI 代理在长期使用中越来越了解用户的工作习惯和需求。

Skills 生态

社区建设的 Skills 市场 ClawHub 提供数百个任务扩展，涵盖邮件处理、数据分析、媒体控制等场景。值得一提的是，AI 甚至可以根据需求自主生成和安装新的 Skills，进一步扩展自身能力。

语音能力

支持 macOS、iOS、Android 上的语音唤醒和对话模式，可以通过语音直接与 AI 代理交互。

Live Canvas

代理驱动的可视化工作区，支持 A2UI（Agent-to-UI）集成，让 AI 可以直接生成和操作可视化界面。

多代理路由

支持在不同的工作区和会话中隔离不同的代理，适合将工作、个人、项目等场景分开管理。

技术架构

OpenClaw 基于 [[Node.js]] 构建，作为本地消息路由器和代理运行时运行。

整体架构采用分层模式：

Internet → 反向代理（Caddy/Nginx）
         → Docker 网络（bridge）
         → OpenClaw Gateway 容器（绑定 127.0.0.1，非 root node 用户）
         → 挂载卷（config/、workspace/、state/）

Docker Compose 定义两个主要服务：

• openclaw-gateway — 网关服务，运行 node dist/index.js gateway，绑定端口 18789
• openclaw-cli — CLI 容器，用于运行管理命令

搭建指南

系统要求

组件	最低要求	推荐配置
操作系统	macOS 12+, Ubuntu 20.04+, Windows 10 (WSL2)	macOS 14+, Ubuntu 22.04+, Windows 11
Node.js	v22（硬性要求）	v22 LTS 最新版
内存	2 GB（树莓派最低 1 GB）	8-16 GB
磁盘空间	500 MB（含工作空间 10 GB）	20 GB SSD
CPU	1 核	4+ 核

生产环境推荐使用 [[Docker]] 和 Docker Compose。

验证前置条件：

node --version    # 必须 v22.x.x 或更高
npm --version
git --version

安装方式速查表

方式	平台	官方支持	难度	适合场景
curl 脚本	macOS / Linux	是	简单	个人使用，首选
npm 全局安装	全平台	是	简单	已有 Node.js 环境
Homebrew	macOS / Linux	是	简单	macOS 用户首选
PowerShell 脚本	Windows	是	简单	Windows 原生
WSL2	Windows	是	中等	Windows 用户推荐
Docker Compose	全平台	是	中等	服务器 / 生产环境
源码编译	全平台	是	中等	开发者 / 贡献代码
Nix	macOS / Linux	是	较高	NixOS 用户
AUR	Arch Linux	社区	中等	Arch 用户
Ansible	Debian / Ubuntu	是	中等	批量服务器部署
Kubernetes / Helm	任意 K8s	社区	较高	企业环境
NAS（Unraid / Synology / TrueNAS）	NAS	社区	简单	家庭服务器
树莓派	ARM Linux	是	中等	低功耗 24/7 运行
云服务商一键部署	云端	部分官方	简单	免运维

curl 脚本安装（macOS / Linux 首选）

官方推荐的安装方式，脚本会自动检测系统架构、安装 Node.js（如果缺失）、通过 npm 安装 CLI，并配置开机自启守护进程。

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

如果想从源码安装而不是 npm：

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

跳过交互式向导（适合脚本化部署）：

curl -fsSL https://openclaw.ai/install.sh | bash -s -- --no-prompt --no-onboard

npm 全局安装

前提是系统已经安装了 Node.js >= 22。

npm install -g openclaw@latest
openclaw onboard --install-daemon

安装指定版本：

npm install -g [email protected]

更新到最新版：

npm update -g openclaw

如果安装后提示 command not found，需要把 npm 全局 bin 目录加入 PATH：

export PATH="$PATH:$(npm config get prefix)/bin"

把这行加入 ~/.bashrc 或 ~/.zshrc 使其永久生效。

也可以使用 pnpm（OpenClaw 开发团队内部使用的包管理器）：

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

Homebrew 安装（macOS / Linux）

OpenClaw 已收录到 Homebrew core，包名为 openclaw-cli。

brew install openclaw-cli
openclaw onboard --install-daemon

更新：

brew upgrade openclaw-cli

Homebrew 会自动处理 Node.js 依赖。支持 macOS Apple Silicon、macOS Intel、Linux ARM64、Linux x86_64 的预编译二进制。

Windows 安装

Windows 上有多种安装方式，按推荐程度排序。

方式一：PowerShell 脚本（最简单）

iwr -useb https://openclaw.ai/install.ps1 | iex
openclaw onboard

如果脚本执行后窗口直接关闭（已知 Bug），改用以下方式：

iwr -useb https://openclaw.ai/install.ps1 -OutFile install.ps1
.\install.ps1

方式二：CMD 命令提示符

curl -fsSL https://openclaw.ai/install.cmd -o install.cmd && install.cmd && del install.cmd
openclaw onboard

方式三：WSL2（推荐，体验最接近 Linux）

第一步，安装 WSL2：

# 以管理员身份运行 PowerShell
wsl --install -d Ubuntu

第二步，在 WSL 内启用 systemd（守护进程需要）：

sudo tee /etc/wsl.conf <<EOF
[boot]
systemd=true
EOF

从 PowerShell 重启 WSL：wsl --shutdown，然后重新打开。

第三步，安装 Node.js 22 和 OpenClaw：

curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs
curl -fsSL https://openclaw.ai/install.sh | bash
openclaw onboard --install-daemon

方式四：npm 直接安装（需要先装 Node.js）

从 nodejs.org 下载安装 Node.js 22 后：

npm install -g openclaw@latest
openclaw onboard

Docker 部署

Docker 适合服务器环境和需要隔离的场景。官方镜像为 alpine/openclaw。

Docker 单容器运行

docker pull alpine/openclaw:latest

docker run -it \
  -p 18789:18789 \
  -v ~/.openclaw:/root/.openclaw \
  -v $(pwd)/workspace:/workspace \
  -e ANTHROPIC_API_KEY=sk-ant-your-key-here \
  alpine/openclaw:latest

在容器内执行一次性初始化：

docker run -it \
  -v ~/.openclaw:/root/.openclaw \
  alpine/openclaw:latest \
  openclaw onboard

Docker Compose（推荐用于服务器）

创建 docker-compose.yml：

version: "3.8"
services:
  openclaw:
    image: alpine/openclaw:latest
    ports:
      - "127.0.0.1:18789:18789"
    volumes:
      - ~/.openclaw:/root/.openclaw
      - ./workspace:/workspace
    environment:
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
    restart: unless-stopped
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"

docker compose up -d          # 后台启动
docker compose logs -f         # 查看日志
docker compose restart         # 重启
docker compose pull && docker compose up -d   # 更新到最新版

Docker 安装会使用两个目录：

• ~/.openclaw — 配置目录，包含记忆、配置和 API 密钥
• workspace/ — 工作区目录，代理可直接访问的文件

额外挂载目录可通过 OPENCLAW_EXTRA_MOUNTS 环境变量设置。

也可以使用官方安装脚本：

git clone https://github.com/openclaw/openclaw.git
cd openclaw
bash docker-setup.sh
docker-compose up -d

从源码编译

适合想要贡献代码或使用开发版本的用户。

git clone https://github.com/openclaw/openclaw.git
cd openclaw

pnpm install
pnpm ui:build
pnpm build

# 使用本地构建执行初始化
pnpm openclaw onboard --install-daemon

# 开发模式（自动重载）
pnpm gateway:watch

更新：

git pull origin main && pnpm install && pnpm build

pnpm openclaw 会通过 tsx 直接运行 TypeScript，开发时无需编译。pnpm build 生成 dist/ 目录用于打包分发。

树莓派安装

树莓派适合作为 24/7 低功耗运行的 OpenClaw 服务器，功耗约 5W，年电费约 $4。

硬件兼容性：

型号	内存	状态
Pi 5 (4GB/8GB)	最佳	推荐
Pi 4 (4GB)	良好	性价比最高
Pi 4 (2GB)	可用	需要添加 swap
Pi 4 (1GB)	紧张	加 swap 后可运行
Pi 3B+ (1GB)	慢	可用但体验不好

安装步骤：

# 更新系统
sudo apt update && sudo apt upgrade -y
sudo apt install -y git curl build-essential

# 安装 Node.js 22 (ARM64)
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs

# 2GB 及以下内存的型号需要添加 swap
sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab

# 安装 OpenClaw
curl -fsSL https://openclaw.ai/install.sh | bash
openclaw onboard --install-daemon

验证和访问：

openclaw status
journalctl -u openclaw -f                        # 查看日志
ssh -L 18789:localhost:18789 user@pi-hostname     # SSH 隧道访问 Web UI

建议使用 USB SSD 代替 SD 卡，以获得更好的性能和寿命。

Nix / NixOS 安装

OpenClaw 官方维护了 openclaw/nix-openclaw 仓库，同时也已合并到 nixpkgs（PR #485407，2026-03-03 合并）。

方式一：nixpkgs

nix-env -iA nixpkgs.openclaw

支持平台：x86_64-linux、aarch64-linux、aarch64-darwin。

方式二：Home Manager 模块

通过 github:openclaw/nix-openclaw 仓库的 Home Manager 模块安装，适合需要声明式管理的用户。安装后可以用 home-manager switch --rollback 回滚。

启用 Nix 模式需要设置环境变量：

export OPENCLAW_NIX_MODE=1

Nix 模式下会禁用自动安装和自动更新功能。

Arch Linux AUR

AUR 上有三个包，推荐使用 openclaw-git（跟踪最新 git HEAD）：

yay -S openclaw-git

其他包：moltbot（旧名，低人气）和 clawdbot（已标记过时，不推荐）。

Ansible 自动化部署

官方维护了 Ansible Playbook，适合批量部署到多台服务器。仓库：github.com/openclaw/openclaw-ansible。

curl -fsSL https://raw.githubusercontent.com/openclaw/openclaw-ansible/main/install.sh | bash

或使用社区 Ansible Galaxy Role：

ansible-galaxy install babidi34.openclaw

Playbook 会自动安装 systemd 服务、Node.js 22、Docker CE、UFW 防火墙、[[Tailscale]] 和 Fail2ban，并进行安全加固。仅支持 Debian 11+ / Ubuntu 20.04+。

Kubernetes / Helm

社区维护了两个 Helm Chart，推荐 serhanekicii/openclaw-helm（145 星）：

helm repo add openclaw https://serhanekicii.github.io/openclaw-helm
helm repo update
helm install openclaw openclaw/openclaw \
  --set credentials.anthropicApiKey=sk-ant-xxx

要求 Kubernetes >= 1.26.0、Helm 3.0+。

注意：OpenClaw 是单实例应用，无法水平扩展。如果需要更完整的生产部署（网络隔离、资源限制、密钥管理），可以使用 Kubernetes Operator。

NAS 平台安装

Unraid

在 Unraid Web UI → Apps（Community Applications）中搜索 OpenClaw，点击安装即可。社区模板仓库：github.com/jdhill777/openclaw-unraid。

Synology NAS

要求 DSM 7.0+ 和 Container Manager（原 Docker 包），推荐 4GB+ 内存的 Plus 系列型号。

通过 SSH 使用 Docker 安装：

ssh admin@synology-ip
docker run -d \
  --name openclaw \
  -p 18789:18789 \
  -v /volume1/docker/openclaw:/root/.openclaw \
  alpine/openclaw:latest

docker exec -it openclaw openclaw onboard

也可以在 Container Manager 的图形界面中搜索 alpine/openclaw 镜像进行安装。

TrueNAS

在 TrueNAS Web UI → Apps 中搜索 openclaw，从社区目录安装。以非 root 用户（UID/GID 568）运行。

Android 安装（Termux）

这是社区维护的安装方式，属于「发烧友级别」，需要一定折腾能力。

前提：Android 9+ 设备，4GB+ 内存，从 F-Droid 安装 Termux（不要用 Google Play 版本，那个版本已过时）。

pkg update && pkg upgrade -y
pkg install nodejs-lts git curl

npm install -g openclaw@latest
openclaw onboard

局限：Termux 被切到后台时 OpenClaw 会停止运行（可用 Termux:Boot 解决），浏览器自动化在 Android 上很难配置。对大多数 Android 用户来说，更实际的方案是在服务器上运行 OpenClaw，通过手机上的 Telegram 或 WhatsApp 访问。

云服务商一键部署

服务商	状态	说明	参考价格
[[DigitalOcean]]	官方合作	Marketplace 1-Click 部署，预装所有依赖	$12/月起
Hostinger	官方合作	专属 OpenClaw VPS 页面，模板化安装	$6.49/月起
Oracle Cloud	官方提及	Always Free ARM 层，4 OCPU，24GB RAM	免费
[[Vultr]]	官方提及	Docker Compose 部署，带交互向导	$6/月起
Railway	社区模板	一键部署，含持久化存储和管理界面	$5-10/月
Render	官方文档	Fork 仓库后连接部署	按用量
[[Fly.io]]	官方文档	项目自带 fly.toml，原生支持	按用量
Hetzner	官方文档	VPS 部署，CX22 型号	~$4/月起
Northflank	官方文档	托管容器平台部署	按用量
GCP	官方文档	Compute Engine VM 或 Cloud Run	按用量

任何有 2 vCPU、4 GB 内存的 VPS 都可以运行 OpenClaw。通用的 VPS 安装流程：

ssh root@your-vps-ip
apt update && apt upgrade -y
curl -fsSL https://openclaw.ai/install.sh | bash
openclaw onboard --install-daemon

Fly.io 的部署有专门的支持：

git clone https://github.com/openclaw/openclaw.git
cd openclaw
fly apps create my-openclaw
fly volumes create openclaw_data --size 1
fly deploy

引导配置

无论使用哪种安装方式，安装完成后都需要运行 openclaw onboard 进行初始化配置。向导会引导你完成：

• 设置 LLM API 密钥（Anthropic、OpenAI、Google 等）
• 选择默认模型
• 连接第一个消息渠道

消息渠道的配置方式：

• [[Telegram]]：通过 @BotFather 创建 Bot，粘贴 API Token
• [[Discord]]：在 Developer Portal 创建应用，启用 Message Content Intent，邀请 Bot 到服务器
• [[WhatsApp]]：运行 openclaw channels login --channel whatsapp，扫描终端中的二维码

本地管理界面位于 http://127.0.0.1:18789/。

安装后验证

openclaw --version        # 查看版本
openclaw status           # 查看运行状态
openclaw doctor           # 自动诊断和修复
openclaw gateway start    # 手动启动网关
openclaw gateway status   # 查看网关状态

openclaw doctor 有多种模式：

openclaw doctor --non-interactive   # 非交互式，仅安全迁移
openclaw doctor --repair            # 自动修复
openclaw doctor --repair --force    # 强制修复（会覆盖自定义配置）
openclaw doctor --deep              # 深度扫描额外的网关安装

常见问题排查

• 网关无响应：运行 openclaw gateway restart 并验证 API 密钥
• RPC 探测失败：检查端口 18789 是否被占用，使用 sudo lsof -i :18789 确认
• 访问未配置：运行 pairing approve 命令
• 自动诊断：openclaw doctor
• 实时日志：openclaw logs --follow
• Docker 日志：docker compose logs -f
• systemd 日志：journalctl -u openclaw -f

安全建议

OpenClaw 拥有 Shell 访问权限、文件系统控制和浏览器自动化能力，配置不当会有真实风险。部署时建议遵循以下原则：

• 启用显式同意模式（exec.ask: "on"），所有敏感操作需用户确认
• 对敏感目录仅授予只读权限
• 网关绑定到 localhost：在 openclaw.json 中设置 gateway: { bind: "127.0.0.1" }
• 不要将端口 18789 的 Web 界面暴露到公网
• 使用 [[Docker]] 容器化运行，提供安全隔离
• 配置反向代理和身份验证
• 密钥存在 .env 文件中（chmod 600），不要直接写在配置文件里
• 在 API 供应商后台设置消费上限，防止意外账单
• 安装社区 Skills 前先检查 GitHub 源码
• 将代理视为生产基础设施，遵循最小权限原则，使用范围令牌，设置白名单操作

related

• [[Nanobot]]
• [[Pi]]
• mimiclaw.io，可以在低性能环境中运行的轻量替代方案
• https://github.com/voocel/openclaw-mini 一个 OpenClaw 最简实现，适合学习原理