OpenClaw 完全安装教程：从零到一的 AI 助手部署指南
|
17
|
0
|
科技

2724 字
|
24 分钟

OpenClaw 完全安装教程：从零到一的 AI 助手部署指南

文章摘要

OpenClaw 是一个开源的 AI 助手框架，让你可以将 AI 助手连接到各种通信渠道（如 Telegram、Discord、WhatsApp 等）并赋予其实用工具能力。本教程将详细介绍如何在不同操作系统上安装和配置 OpenClaw，涵盖从系统要求到完整部署的每一个步骤。

目录

  1. 系统要求与准备
  2. 安装方法选择
  3. 详细安装步骤
  1. 配置与初始化
  1. 验证安装
  2. 故障排除
  3. 常见问题解答
  4. 进阶配置

系统要求与准备

在开始安装之前，请确保你的系统满足以下最低要求：

硬件要求

  • CPU: 现代 x64 或 ARM64 处理器
  • 内存: 至少 2GB RAM
  • 磁盘空间: 至少 1GB 可用空间

软件要求

  • 操作系统:
    • macOS 11 (Big Sur) 或更高版本
    • Linux (Ubuntu 20.04+, Debian 11+, CentOS 8+)
    • Windows 10/11（推荐使用 WSL2）
  • 运行时环境:
    • Node.js 24（推荐）或 Node.js 22.14+
    • npm 10+ 或 pnpm 8+ 或 bun 1.0+
  • 必要的工具:
  # 检查 Node.js 版本
  node --version
  
  # 检查包管理器版本
  npm --version  # 或 pnpm --version, bun --version
  
  # 检查 curl 是否可用
  curl --version

API 密钥准备

OpenClaw 需要 AI 模型 API 密钥才能正常工作，你可以从以下提供商中选择：

  • OpenAI (ChatGPT API)
  • Anthropic (Claude API)
  • Google (Gemini API)
  • DeepSeek
  • 智谱 GLM
  • Kimi 等

请确保在安装前准备好至少一个有效的 API 密钥。

安装方法选择

OpenClaw 提供多种安装方式，你可以根据需求选择：

安装方法适用场景难度备注
官方安装脚本新手用户、快速部署★☆☆最推荐的方式，自动化程度最高
npm/pnpm/bunNode.js 开发者★★☆适合熟悉 Node.js 环境的用户
Docker容器化部署、生产环境★★☆便于管理和隔离
从源代码开发者、自定义修改★★★需要技术背景

详细安装步骤

方法一：官方安装脚本（推荐）

这是最简单快捷的安装方式，适合所有用户。

1. macOS / Linux / WSL2 用户

# 使用 curl 下载并运行安装脚本
curl -fsSL https://openclaw.ai/install.sh | bash

脚本执行过程详解：

  1. 环境检测 – 自动识别操作系统和架构
  2. Node.js 检查 – 检查是否安装 Node.js，如未安装则自动安装
  3. 包管理器选择 – 自动选择适合的包管理器（npm/pnpm）
  4. OpenClaw 安装 – 下载并安装最新版本
  5. 依赖安装 – 安装必要的 npm 依赖包
  6. 版本验证 – 检查安装是否成功

2. Windows PowerShell 用户

# 使用 PowerShell 安装
iwr -useb https://openclaw.ai/install.ps1 | iex

Windows 安装注意事项：

  • 建议使用 WSL2 (Windows Subsystem for Linux 2) 以获得最佳体验
  • 如果使用原生 Windows，确保已安装 Windows Terminal 或 PowerShell 7+
  • 可能需要以管理员身份运行 PowerShell

3. 安装选项

# 如果不想立即运行配置向导
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --no-onboard

# 指定安装目录（本地前缀安装）
curl -fsSL https://openclaw.ai/install-cli.sh | bash

选项说明：

  • --no-onboard – 只安装不运行配置向导
  • 本地前缀安装将 OpenClaw 安装到 ~/.openclaw 目录，避免系统污染

方法二：使用 npm/pnpm/bun 安装

如果你已经熟悉 Node.js 生态系统，可以使用包管理器直接安装。

1. npm 安装方式

# 全局安装 OpenClaw
npm install -g openclaw@latest

# 如果遇到 sharp 包构建错误（常见于全局 libvips 冲突）
SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install -g openclaw@latest

# 验证安装
openclaw --version

2. pnpm 安装方式

# 全局安装
pnpm add -g openclaw@latest

# pnpm 需要显式批准构建脚本
pnpm approve-builds -g

# 验证安装
openclaw --version

3. bun 安装方式

# 使用 bun 安装（仅 CLI 路径）
bun add -g openclaw@latest

# 验证安装
openclaw --version

注意: bun 运行时主要用于 CLI，网关服务仍需使用 Node.js。

方法三：Docker 安装

对于容器化部署或希望环境隔离的用户。

1. 基本 Docker 运行

# 拉取并运行 OpenClaw 容器
docker run -d \
  --name openclaw \
  -p 18789:18789 \
  -v openclaw_data:/home/openclaw/.openclaw \
  -v openclaw_workspace:/home/openclaw/workspace \
  ghcr.io/openclaw/openclaw:latest

# 进入容器运行配置
docker exec -it openclaw openclaw onboard

2. Docker Compose 部署

创建 docker-compose.yml 文件：

version: '3.8'
services:
  openclaw:
    image: ghcr.io/openclaw/openclaw:latest
    container_name: openclaw
    restart: unless-stopped
    ports:
      - "18789:18789"
    volumes:
      - openclaw_data:/home/openclaw/.openclaw
      - openclaw_workspace:/home/openclaw/workspace
      - ./config:/home/openclaw/.openclaw/config
    environment:
      - NODE_ENV=production
      - TZ=Asia/Shanghai

volumes:
  openclaw_data:
  openclaw_workspace:

启动服务：

docker-compose up -d

方法四：从源代码安装

适用于开发者或需要自定义修改的情况。

# 克隆仓库
git clone https://github.com/openclaw/openclaw.git
cd openclaw

# 安装依赖（需要 pnpm）
pnpm install

# 构建项目
pnpm ui:build
pnpm build

# 链接到全局
pnpm link --global

# 验证安装
openclaw --version

# 或者直接使用本地版本
pnpm openclaw --version

GitHub main 分支安装：

npm install -g github:openclaw/openclaw#main

配置与初始化

安装完成后，需要进行初始配置。

首次配置向导

运行配置向导，它会引导你完成所有必要设置：

# 启动配置向导（推荐）
openclaw onboard --install-daemon

# 或者
openclaw onboard

配置向导详细步骤

1. 选择配置模式

? 选择配置模式:
  ❯ QuickStart (快速开始，使用默认值)
    Advanced (高级配置，完全控制)

选择建议：

  • QuickStart – 新手用户，使用安全默认值
  • Advanced – 高级用户，需要自定义网关端口、认证方式等

2. 模型和 API 密钥配置

? 选择模型提供商:
  ❯ OpenAI
    Anthropic
    Google (Gemini)
    DeepSeek
    GLM (智谱)
    Kimi
    其他 (自定义)

配置 API 密钥：

  • OpenAI: 输入你的 OpenAI API 密钥（格式：sk-...）
  • Anthropic: 可以使用 Claude CLI 或直接输入 API 密钥
  • 其他提供商: 按提示输入相应的 API 密钥

3. 工作空间设置

? 选择工作空间目录:
  ❯ ~/.openclaw/workspace (默认)
    自定义路径

工作空间说明：

  • 包含所有配置文件、日志、插件和自定义技能
  • 默认位置：~/.openclaw/workspace
  • 可自定义位置，如：/opt/openclaw/workspace

4. 网关配置

? 网关配置:
  - 端口: 18789 (默认)
  - 绑定地址: 127.0.0.1 (本地)
  - 认证模式: Token (推荐)
  - Tailscale 暴露: 关闭

网关选项详解：

  • 端口: 18789（默认），可修改为其他端口
  • 绑定地址:
    • 127.0.0.1 – 仅本地访问（最安全）
    • 0.0.0.0 – 允许网络访问（需要防火墙配置）
  • 认证模式:
    • Token – 令牌认证（推荐）
    • Password – 密码认证
    • None – 无认证（仅限本地环境）

5. 通信渠道选择

? 选择要配置的通信渠道:
  [ ] Discord
  [ ] Telegram
  [x] WhatsApp (推荐)
  [ ] Signal
  [ ] Slack
  [ ] 飞书 (Feishu)
  [ ] QQ 频道
  [ ] 其他...

渠道配置提示：

  • Telegram: 需要 BotFather 创建的机器人令牌
  • WhatsApp: 需要手机号验证
  • Discord: 需要创建 Discord 应用和机器人令牌
  • 可根据需要选择多个渠道

6. 守护进程安装

? 安装为系统服务（守护进程）?
  ❯ 是 (推荐，自动启动)
    否 (手动启动)

各系统服务类型：

  • macOS: LaunchAgent（用户级服务）
  • Linux/WSL2: systemd user service
  • Windows: Scheduled Task + Startup 文件夹备用

7. 技能安装

? 安装推荐技能包?
  ❯ 是 (推荐)
    否 (稍后手动安装)

常见技能包：

  • clawflow – 工作流引擎
  • tmux – 终端控制
  • weather – 天气预报
  • wordpress-publisher – WordPress 发布
  • 更多技能可在安装后从 ClawdHub 添加

配置完成后验证

# 检查网关状态
openclaw gateway status

# 运行诊断
openclaw doctor

# 打开控制面板
openclaw dashboard

预期输出示例：

$ openclaw gateway status
Gateway is running (PID: 12345)
Listening on: http://127.0.0.1:18789
Uptime: 2 minutes

验证安装

1. 基础验证

# 检查 CLI 是否可用
openclaw --version
# 预期输出: openclaw/x.y.z (node v24.x.x)

# 检查网关服务
openclaw gateway status
# 预期输出: Gateway is running

# 运行健康检查
openclaw doctor
# 预期输出: All checks passed ✓

2. 控制面板验证

# 打开 Web 控制面板
openclaw dashboard

浏览器会自动打开 http://localhost:18789，你应该能看到：

  • OpenClaw 控制面板界面
  • 聊天窗口
  • 系统状态面板
  • 工具和技能管理界面

3. 发送测试消息

在控制面板聊天框中输入：

Hello, are you working?

你应该能收到 AI 助手的回复，确认模型 API 连接正常。

4. 检查日志

# 查看网关日志
openclaw gateway logs

# 查看详细日志
openclaw gateway logs --follow

# 查看错误日志
openclaw gateway logs --level error

故障排除

常见问题 1：OpenClaw 命令找不到

症状： bash: openclaw: command not found

解决方案：

# 检查 Node.js 和 npm 配置
node --version
npm --version
npm prefix -g
echo $PATH

# 添加全局 bin 目录到 PATH
# 对于 bash/zsh:
echo 'export PATH="$(npm prefix -g)/bin:$PATH"' >> ~/.bashrc
# 或
echo 'export PATH="$(npm prefix -g)/bin:$PATH"' >> ~/.zshrc

# 重新加载配置文件
source ~/.bashrc   # 或 source ~/.zshrc

# 检查软链接
ls -la $(npm prefix -g)/bin/openclaw

常见问题 2：网关启动失败

症状： Gateway failed to start

解决方案：

# 检查端口占用
sudo lsof -i :18789
# 或
netstat -tulpn | grep :18789

# 如果端口被占用，停止占用进程或修改端口
openclaw configure --gateway-port 18790

# 检查配置文件
openclaw doctor --verbose

# 手动启动网关查看详细错误
openclaw gateway start --foreground

常见问题 3：API 密钥验证失败

症状： Authentication failed 或 Invalid API key

解决方案：

# 重新配置 API 密钥
openclaw configure --reset-auth

# 或手动编辑配置文件
nano ~/.openclaw/config.yml
# 找到 auth 部分，更新 API 密钥

# 测试 API 密钥连接
openclaw test-auth

常见问题 4：Docker 容器权限问题

症状： Permission denied 或文件系统错误

解决方案：

# 检查 Docker 权限
docker ps
docker logs openclaw

# 调整数据卷权限
docker run --rm -v openclaw_data:/data alpine chown -R 1000:1000 /data

# 使用 Docker Compose 时确保目录存在
mkdir -p ./config
chmod 755 ./config

常见问题 5：技能安装失败

症状： Skill installation failed

解决方案：

# 清理技能缓存
openclaw skills clean

# 手动安装技能
openclaw skills install clawflow --force

# 检查网络连接
openclaw skills search weather

# 查看技能安装日志
openclaw skills logs

常见问题解答

Q1: OpenClaw 是免费的吗？

A: 是的，OpenClaw 本身是开源免费的。但你需要为使用的 AI 模型 API（如 OpenAI、Anthropic 等）付费。

Q2: 支持哪些 AI 模型？

A: 支持包括 OpenAI GPT、Anthropic Claude、Google Gemini、DeepSeek、智谱 GLM、Kimi、MiniMax 等主流模型。

Q3: 需要多少技术知识？

A: 使用官方安装脚本和向导，只需要基本的命令行知识。高级配置需要一些技术背景。

Q4: 安全吗？

A: OpenClaw 提供多层安全措施：令牌认证、权限控制、沙箱工具执行、会话隔离等。但使用时仍需注意 API 密钥安全和网络暴露。

Q5: 支持中文吗？

A: 是的，完全支持中文。AI 模型和界面都支持中文交互。

Q6: 可以自托管吗？

A: 可以，OpenClaw 设计为可完全自托管，支持在 VPS、家庭服务器、云主机等各种环境部署。

Q7: 如何更新？

# 更新 OpenClaw
openclaw update

# 或重新运行安装脚本
curl -fsSL https://openclaw.ai/install.sh | bash

Q8: 如何卸载？

# 完全卸载
openclaw uninstall

# 或手动卸载
npm uninstall -g openclaw
rm -rf ~/.openclaw

进阶配置

1. 多代理配置

# 创建新代理
openclaw agents add my-agent

# 配置代理专属工作空间
openclaw agents add work-agent --workspace ~/work/openclaw

# 列出所有代理
openclaw agents list

2. 自定义工具策略

编辑配置文件 ~/.openclaw/config.yml：

tools:
  policy: restricted  # 或 permissive
  allowed:
    - read
    - write
    - exec
    - web_search
  blocked:
    - cron
    - sessions_spawn

3. 网络暴露和安全

# 启用 Tailscale 连接
openclaw configure --tailscale enable

# 设置访问控制列表
openclaw configure --acl ./my-acl.json

# 配置 SSL/TLS
openclaw configure --ssl-cert /path/to/cert.pem --ssl-key /path/to/key.pem

4. 性能优化

# 编辑 config.yml
gateway:
  maxConcurrent: 10
  requestTimeout: 30000
  keepAliveTimeout: 5000

cache:
  enabled: true
  ttl: 3600000
  maxSize: 100

5. 监控和日志

# 启用详细日志
openclaw configure --log-level debug

# 设置日志轮转
openclaw configure --log-rotation daily

# 集成监控
openclaw configure --metrics prometheus

总结

OpenClaw 是一个功能强大且灵活的 AI 助手框架，通过本教程的详细步骤，你应该能够成功完成安装和基础配置。关键要点：

  1. 系统要求 – 确保满足 Node.js 和操作系统要求
  2. 安装方法 – 推荐使用官方安装脚本
  3. 配置向导 – 使用 openclaw onboard 完成初始配置
  4. 验证测试 – 通过控制面板和命令行验证安装
  5. 故障排除 – 遇到问题时参考故障排除章节

安装完成后，你可以：

  • 通过 Web 控制面板与助手对话
  • 连接 Telegram、WhatsApp 等通信渠道
  • 安装技能扩展功能
  • 根据需求进行高级配置

OpenClaw 的生态系统还在不断成长，建议定期查看官方文档和社区获取最新信息。祝你使用愉快！

相关资源

  • 官方文档: https://docs.openclaw.ai
  • GitHub 仓库: https://github.com/openclaw/openclaw
  • 社区讨论: https://discord.com/invite/clawd
  • 技能市场: https://clawhub.ai
  • 问题反馈: https://github.com/openclaw/openclaw/issues

本文基于 OpenClaw 官方文档编写，最后更新于 2026年4月。如有更新，请参考官方文档获取最新信息。

code langdockerfssl httpsnodeopenclaw configureopenclaw gateway statusopenclaw onboardopenclaw 完全安装教程从零到一的 助手部署指南pre classwindows
暂无评论

发送评论 编辑评论 


				

			

						

				

					

						

							

								
							

							
						

					

				

				

					

						

							

								
							

							
						

					

				

				

					

						

							

								
							

							
							
													

					

				

			

			
			

				

					
				

			

				

											

							
							
						

																				
					
											
						

	

		
|´・ω・)ノ
ヾ(≧∇≦*)ゝ
(☆ω☆)
（╯‵□′）╯︵┴─┴
￣﹃￣
(/ω＼)
∠( ᐛ 」∠)＿
(๑•̀ㅁ•́ฅ)
→_→
୧(๑•̀⌄•́๑)૭
٩(ˊᗜˋ*)و
(ノ°ο°)ノ
(´இ皿இ｀)
⌇●﹏●⌇
(ฅ´ω`ฅ)
(╯°A°)╯︵○○○
φ(￣∇￣o)
ヾ(´･ ･｀｡)ノ"
( ง ᵒ̌皿ᵒ̌)ง⁼³₌₃
(ó﹏ò｡)
Σ(っ °Д °;)っ
( ,,´･ω･)ﾉ"(´っω･｀｡)
╮(╯▽╰)╭
o(*////▽////*)q
＞﹏＜
( ๑´•ω•) "(ㆆᴗㆆ)
😂
😀
😅
😊
🙂
🙃
😌
😍
😘
😜
😝
😏
😒
🙄
😳
😡
😔
😫
😱
😭
💩
👻
🙌
🖕
👍
👫
👬
👭
🌚
🌝
🙈
💊
😶
🙏
🍦
🍉
😣
Source: github.com/k4yt3x/flowerhd
	

	

		
颜文字
Emoji
小恐龙
花!
	


									

			

			
			
		

	






下一篇