OpenClaw 完整安装指南

版本： 2026.3.2
适用系统： Windows 10/11、macOS (Intel/Apple Silicon)、Linux (Ubuntu/Debian/Fedora/Arch)

csdn链接：https://blog.csdn.net/weixin_51035135/article/details/?spm=1001.2014.3001.5502

1. 系统要求
2. 前置条件
3. Windows 安装
4. macOS 安装
5. Linux 安装
6. 安装后配置
7. 常见问题与解决方案
8. 服务管理
9. 验证安装
10. 卸载与清理

OpenClaw 基于 Node.js，需要先安装：

• Windows/macOS/Linux 通用： 从 nodejs.org 下载 LTS 版本（v20.x）
• 验证：node -v 应输出 v20.x 或更高

部分技能安装依赖 git：

• Windows： 下载 Git for Windows，安装时勾选“Add to PATH”
• macOS： brew install git
• Linux：
  Ubuntu/Debian: sudo apt install git
  Fedora: sudo dnf install git
  Arch: sudo pacman -S git

某些技能（如 video-frames）需要：

• Python 3.9+（先安装）
• FFmpeg：
  Windows：下载二进制并添加到 PATH
  macOS：brew install ffmpeg
  Linux：sudo apt install ffmpeg 或对应包管理器

Windows 10/11：

• 按 Win + X → 选择 “Windows Terminal (Admin)” 或 “PowerShell (Admin)”
• 如果未启用脚本执行，先运行： Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned

npm install -g openclaw

等待完成（约 1–2 分钟）。如果速度慢，可配置 npm 镜像：

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

openclaw onboard

这个命令会：

• 创建配置文件 C:\Users\
<用户名>
\.openclaw\openclaw.json

• 生成默认技能目录
• 提示你配置 API 密钥（OpenRouter、OpenAI 等）

OpenClaw 使用本地网关进行服务通信。确保：

openclaw gateway status

应显示网关正在运行。如果未运行，执行：

openclaw gateway start

关于网关 token：

• 首次运行会自动生成，存储在 openclaw.json 的 gateway.auth.token
• 如果需要重置，可运行 openclaw gateway token --generate（如果支持）或手动编辑配置文件

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

brew install node

npm install -g openclaw

openclaw onboard

macOS 下网关作为后台服务运行：

# 启动 openclaw gateway start # 状态 openclaw gateway status # 停止 openclaw gateway stop

# 1) 安装 Node.js (使用 Nodesource) curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - sudo apt install -y nodejs # 2) 安装 Git（如未安装） sudo apt update && sudo apt install -y git # 3) 全局安装 OpenClaw sudo npm install -g openclaw # 4) 初始化（普通用户） openclaw onboard # 5) 网关服务（可选 systemd） # 如需开机启动，可设置： sudo openclaw gateway enable sudo openclaw gateway start

# Node.js 20 (使用 Nodesource) curl -fsSL https://rpm.nodesource.com/setup_20.x | sudo bash - sudo dnf install -y nodejs sudo dnf install -y git sudo npm install -g openclaw openclaw onboard

sudo pacman -S nodejs npm git sudo npm install -g openclaw openclaw onboard

运行配置向导：

openclaw configure

选择你要使用的模型提供商：

• OpenRouter（推荐，多模型，按用量计费）
• OpenAI（需 OpenAI API Key）
• Anthropic（Claude 系列）
• 本地模型（Ollama 等）

按提示输入 API Key。这些密钥将保存在 ~/.openclaw/credentials/ 下（加密或明文取决于配置）。

openclaw skills list

应看到已安装的核心技能列表（如 coding-agent、weather、video-frames 等）。如缺少所需技能，可后续安装。

编辑 openclaw.json 或使用命令：

openclaw config set agents.defaults.model.primary openrouter/openrouter/auto

如需连接 Telegram、Discord、Slack 等，需在 openclaw.json 中添加 channels 配置，并安装对应技能。

示例（Discord）：

{ "channels": { "discord": { "token": "YOUR_BOT_TOKEN", "enabled": true } } }

问题： 全局安装时权限不足。

解决：

• 不推荐： 使用 sudo npm install -g openclaw（Linux/macOS）
• 推荐： 修改 npm 全局目录权限：
  mkdir ~/.npm-global npm config set prefix ‘~/.npm-global’ # 然后添加 PATH 到 ~/.profile 或 ~/.bashrc export PATH=~/.npm-global/bin:$PATH
  重新登录后再次安装。

原因： npm 全局 bin 目录未加入 PATH。

解决：

# 查看 npm 全局 bin 路径 npm bin -g # 输出类似 /usr/local/bin 或 ~/.npm-global/bin # 确保该目录在你的 PATH 环境变量中 echo 'export PATH=$PATH:~/.npm-global/bin' >> ~/.bashrc source ~/.bashrc

原因： 配置文件 openclaw.json 中的 gateway.auth.token 与运行中的网关服务环境变量 OPENCLAW_GATEWAY_TOKEN 不一致。

解决：

1. 查看当前服务 token： echo $OPENCLAWS_GATEWAY_TOKEN # Linux/macOS echo %OPENCLAW_GATEWAY_TOKEN% # Windows CMD $env:OPENCLAW_GATEWAY_TOKEN # PowerShell
2. 更新 openclaw.json 中的 token 与之匹配： openclaw config set gateway.auth.token “实际token值”
3. 重启网关： openclaw gateway restart

原因： openclaw.json 中配置了一个不存在的通道 ID。

解决：

• 检查 openclaw.json 的 channels 部分
• 删除未知的通道配置（如 webchat），仅保留已安装技能的通道（如 discord、slack）
• 运行 openclaw doctor --fix 自动修复

现象： fatal: unable to access ... Couldn't connect to server

解决：

1. 检查网络连接和代理设置： git config –global –unset http.proxy git config –global –unset https.proxy
2. 使用可访问的镜像（如果是中国地区）： git config –global http.proxy http://127.0.0.1:7890 # 本地代理
3. 手动下载 ZIP 并解压到技能目录

原因： 安装的技能不是 OpenClaw 格式，或路径不对。

解决：

• 只从 OpenClaw 官方源或可信仓库安装技能
• 确保技能目录包含 SKILL.md 和可执行文件
• 使用 openclaw skills list 查看已安装技能状态

原因： 可能 stdout 被重定向或终端交互异常。

解决：

• 直接编辑 openclaw.json： { “auth”: { “profiles”: { “openrouter:default”: { “provider”: “openrouter”, “mode”: “api_key” } } } }
• 在 ~/.openclaw/credentials/ 创建对应文件（如 openrouter.creds），内容为 API Key

解决：

1. 检查端口占用： netstat -ano | findstr :18789
2. 更换网关端口： openclaw config set gateway.port 18790 openclaw gateway restart

解决： 为该技能创建虚拟环境并手动安装依赖（或在系统 Python 安装）：

# Windows（PowerShell） python -m venv "%USERPROFILE%\.openclaw\skills\my-skill\.venv" # 激活并安装 %USERPROFILE%\.openclaw\skills\my-skill\.venv\Scripts\Activate.ps1 pip install -r requirements.txt

OpenClaw 将在PATH中自动发现该虚拟环境。

解决： 设置系统时区，或覆盖 OpenClaw 时区：

openclaw config set session.timezone Asia/Shanghai

网关安装为计划任务（Scheduled Task）：

# 查看状态 schtasks /query /tn "OpenClaw Gateway" # 手动启动/停止 schtasks /run /tn "OpenClaw Gateway" schtasks /end /tn "OpenClaw Gateway" # 禁用开机自启 schtasks /delete /tn "OpenClaw Gateway" /f

使用 systemd（Linux）：

# 启用开机启动 sudo openclaw gateway enable sudo systemctl start openclaw-gateway sudo systemctl status openclaw-gateway # 停止/禁用 sudo systemctl stop openclaw-gateway sudo systemctl disable openclaw-gateway

macOS 使用 launchd（由 openclaw 自动安装）。

1. 检查 CLI 版本：
   openclaw –version
2. 查看状态：
   openclaw status

应显示类似：

🦞 OpenClaw 2026.x.x 🕒 Time: ... 🧠 Model: openrouter/openrouter/auto 🧵 Session: agent:main:main

1. 运行快速测试：
   openclaw –say “OpenClaw 安装成功”
2. 检查网关：
   openclaw gateway status

Windows：

# 1) 删除全局 npm 包 npm uninstall -g openclaw # 2) 删除配置和数据 Remove-Item -Recurse -Force "$env:USERPROFILE\.openclaw" # 3) 删除计划任务（如果存在） schtasks /delete /tn "OpenClaw Gateway" /f 2>$null

macOS / Linux：

sudo npm uninstall -g openclaw rm -rf ~/.openclaw # 如果启用了 systemd 服务 sudo systemctl disable openclaw-gateway sudo rm /etc/systemd/system/openclaw-gateway.service sudo systemctl daemon-reload

{ "meta": { "lastTouchedVersion": "2026.3.2" }, "gateway": { "port": 18789, "mode": "local", "bind": "loopback", "auth": { "mode": "token", "token": "YOUR_RANDOM_TOKEN" } }, "agents": { "defaults": { "model": { "primary": "openrouter/openrouter/auto", "fallbacks": ["openrouter/anthropic/claude-3-haiku"] }, "workspace": "C:\\Users\\YourName\\.openclaw\\workspace"openclaw } }, "tools": { "profile": "full" } }

文件：C:\Users\你的用户名\.openclaw\credentials\openrouter.creds

内容：

OPENROUTER_API_KEY=sk-or-v1-xxxxxxxx

• 官方文档：https://docs.openclaw.ai
• GitHub 仓库：https://github.com/openclaw/openclaw
• 社区 Discord：https://discord.com/invite/clawd
• 问题反馈：https://github.com/openclaw/openclaw/issues

祝安装顺利！ 如遇未列出的问题，欢迎在社区提问。