OpenClaw 零基础本地与云端部署完整指南
OpenClaw 简介
OpenClaw（原名 Clawdbot）是一个可在本地或云端运行的 AI Agent 框架，具备任务执行、记忆能力和插件扩展机制。它能够响应用户的自然语言指令，执行如文件操作、信息查询、内容处理和流程自动化等任务。通过 Skills 插件机制，还可以拓展更多功能。
该框架基于 Node.js 构建，支持在服务器上长期运行以及本地设备离线运行，数据可完全保存于本地，确保更高的可控性和隐私保护。
部署前准备
所需环境
- 操作系统：Windows 11、macOS 12+ 或主流 Linux 发行版（如 Ubuntu、CentOS）
- 运行环境：Node.js 版本 ≥ 22.x
- 辅助工具：终端/命令行工具、文本编辑器
- 网络连接：用于下载依赖项和获取程序包
验证环境是否就绪
node -v
npm -v
如果返回了版本号，则表示 Node.js 和 npm 已正确安装。
阿里云轻量服务器部署流程
以下内容适用于使用 Alibaba Cloud Linux 3 的阿里云轻量服务器用户。
服务器配置要求
- CPU 核心数 ≥ 1，内存 ≥ 2GB
- 磁盘空间 ≥ 40GB
- 开放端口：18789（Web 控制台默认端口）
快速部署步骤
- 访问阿里云 OpenClaw 一键部署页面，点击"一键购买并部署"按钮。
- 选择合适的服务器规格与镜像（推荐使用预装 OpenClaw 的镜像）。
- 进入百炼平台控制台创建 API 密钥。
- 在服务器控制台中放行 18789 端口，设置 API 密钥，并生成访问 Token。
- 通过浏览器访问
http://[服务器公网IP]:18789使用 OpenClaw。
手动部署命令示例
# 更新系统组件
sudo yum update -y
sudo yum install -y curl git
# 安装 Node.js 22
curl -fsSL https://nodejs.org/dist/v22.0.0/node-v22.0.0-linux-x64.tar.xz | sudo tar -xJ -C /usr/local
sudo ln -s /usr/local/node-v22.0.0-linux-x64/bin/node /usr/bin/node
sudo ln -s /usr/local/node-v22.0.0-linux-x64/bin/npm /usr/bin/npm
# 设置国内镜像源
npm config set registry https://registry.npmmirror.com
# 安装 OpenClaw
npm install -g openclaw
# 初始化配置
openclaw onboard
# 开放外网访问
openclaw config set gateway.host 0.0.0.0
openclaw config set gateway.port 18789
# 启动服务
openclaw gateway start
# 设置开机自启
echo "/usr/bin/openclaw gateway start" | sudo tee -a /etc/rc.local
sudo chmod +x /etc/rc.local
本地环境部署流程
macOS 部署
# 安装 Homebrew（如有必要）
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
# 安装 Node.js
brew install node
# 配置镜像源
npm config set registry https://registry.npmmirror.com
# 安装 OpenClaw
npm install -g openclaw
# 初始化
openclaw onboard
# 启动服务
openclaw gateway start
Ubuntu/Debian 部署
sudo apt update
sudo apt install -y curl git nodejs npm
# 升级到最新稳定版 Node.js
sudo npm install -g n
sudo n stable
npm config set registry https://registry.npmmirror.com
npm install -g openclaw
openclaw onboard
openclaw gateway start
Windows 11 部署
请以管理员身份运行 PowerShell：
# 修改执行策略
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
# 安装 Node.js
winget install OpenJS.NodeJS --version 22.0.0
# 配置镜像源
npm config set registry https://registry.npmmirror.com
# 安装 OpenClaw
npm install -g openclaw
# 初始化
openclaw onboard
# 启动服务
openclaw gateway start
访问地址：http://127.0.0.1:18789
Skills 功能扩展安装指南
Skills 是 OpenClaw 的功能扩展模块，可用于增强搜索、网页交互、内容提炼等功能。
安装技能管理工具
npm install -g clawhub
常用技能列表
# 联网搜索
clawhub install tavily-search
# 浏览器操作
clawhub install agent-browser
# 内容摘要
clawhub install summarize
# 安全审查
clawhub install skill-vetter
# 自动提醒
clawhub install proactive-agent
# Notion 集成
clawhub install notion
技能管理命令
# 查看已安装技能
openclaw skill list
# 启动某项技能
openclaw skill start <skill-name>
# 重启技能
openclaw skill restart <skill-name>
# 查询技能状态
openclaw skill status <skill-name>
# 使新技能生效
openclaw gateway restart
大模型接入配置
OpenClaw 必须对接大语言模型 API 才能实现智能交互能力。
阿里云百炼平台接入
- 登录阿里云百炼平台，创建 API Key 与 Access Key Secret。
- 修改配置文件：
- macOS/Linux:
~/.openclaw/config.json - Windows:
C:\Users\用户名\.openclaw\config.json
- macOS/Linux:
- 配置字段如下：
"model": {
"type": "aliyun-bailian",
"api_key": "YOUR_API_KEY",
"secret": "YOUR_SECRET",
"model_name": "qwen-7b-chat",
"max_tokens": 2048,
"temperature": 0.7,
"timeout": 30,
"reasoning": false
}
- 重启服务使其生效：
openclaw gateway restart
其他免费模型接入
"model": {
"type": "openai",
"api_key": "FREE_API_KEY",
"base_url": "https://free.api.endpoint/path",
"model_name": "gpt-3.5-turbo",
"max_tokens": 2048,
"temperature": 0.7
}
常见问题排查
部署相关
- `command not found` 错误：重新安装 OpenClaw 并确认 PATH 是否正确。
- 服务启动后退出：检查内存资源是否充足，查看日志：
openclaw logs - 无法访问 Web 页面：确认端口是否放行，尝试重启服务。
- 端口冲突解决办法：
lsof -i:18789 # Linux/macOS kill -9 PID netstat -ano | findstr "18789" # Windows taskkill /F /PID PID
技能相关
- `clawhub` 不可用：重新全局安装：
npm install -g clawhub - 技能未生效：重启网关服务。
模型调用异常
- 无响应或空结果：增加 timeout 参数，减少 max_tokens 数值。
- 权限错误：检查密钥有效性，确认账户已实名认证。
权限问题
- Linux/macOS 权限不足：使用 sudo 安装全局包。
- Windows 执行策略限制：临时修改策略：
Set-ExecutionPolicy RemoteSigned - 无法写入配置文件：检查目录权限或重置配置：
openclaw onboard --reset
基本使用流程
- 启动服务：
openclaw gateway start - 访问 Web 控制台，输入指令进行操作。
- 根据需要安装和启用相应 Skills。
- 实时监控日志：
openclaw logs --follow
