安装与环境
约 1670 字大约 6 分钟
2026-03-02
环境要求
在开始安装之前,请确保你的系统满足以下要求:
必需环境
- Node.js ≥ 22.0.0
- npm ≥ 10.0.0(或 pnpm ≥ 8.0.0)
推荐配置
- 操作系统:Linux、macOS、Windows 10/11
- 内存:至少 4GB RAM(推荐 8GB 以上)
- 存储空间:至少 2GB 可用空间
- 包管理器:推荐使用 pnpm(性能更好,磁盘占用更少)
检查环境
在安装前,先检查你的 Node.js 版本:
node --version
# 应该显示 v22.x.x 或更高版本
npm --version
# 应该显示 10.x.x 或更高版本如果版本不符合要求,请先升级 Node.js:
- 使用 nvm(推荐):
nvm install 22 - 或从 Node.js 官网下载安装
基础安装
方式 1:使用 npm(推荐)
npm install -g openclaw@latest方式 2:使用 pnpm
# 如果还没有安装 pnpm
npm install -g pnpm
# 安装 OpenClaw
pnpm add -g openclaw@latest方式 3:使用 bun
bun install -g openclaw@latest验证安装
安装完成后,验证 OpenClaw 是否正确安装:
openclaw --version应该显示当前安装的版本号,例如:openclaw/2.1.0
📦 遇到安装问题?
夸克网盘资源包提供了完整的安装包、配置文件和视频教程,帮助你快速解决安装问题!
👉 立即下载资源包 👈
包含内容:
- ✅ Windows/Mac/Linux 安装包
- ✅ 详细配置文件模板
- ✅ 视频安装教程
- ✅ 常见问题解决方案
- ✅ 常用技能包
初始化配置
运行引导向导
执行以下命令启动交互式配置向导:
openclaw onboard --install-daemon配置流程
引导向导会按以下步骤进行:
1. 选择配置模式
- QuickStart:快速开始配置(推荐新手)
- Custom:自定义配置(适合高级用户)
推荐选择 QuickStart 快速开始。
2. 配置 AI 模型
选择你要使用的 AI 模型供应商,常见选项:
- MiniMax:国内可用,中文支持好
- Kimi:月之暗面出品,长文本处理强
- DeepSeek:推理能力强,代码能力出色
- Claude:Anthropic 出品,综合能力强(需要国际网络)
- OpenAI GPT:经典选择(需要国际网络)
- Ollama:本地模型,完全离线
3. 认证配置
根据选择的模型供应商,输入相应的认证信息:
- API Key 方式:输入从供应商获取的 API Key
- OAuth 方式:按提示完成 OAuth 授权流程
示例(使用 MiniMax):
? 选择认证方式: MiniMax M2.5(CN)
? 输入 API Key: [粘贴你的 API Key]
✓ 认证成功4. 跳过可选配置
首次配置时,可以暂时跳过以下配置:
- Channel(渠道)配置 - 稍后单独配置
- Skill(技能)安装 - 稍后从市场安装
- Hooks(钩子)配置 - 高级功能,稍后配置
5. 打开 Web UI
配置完成后,选择打开 Web UI:
? 是否打开 Web UI? Yes
✓ 正在启动 Dashboard...
✓ Dashboard 已启动: http://127.0.0.1:18789浏览器会自动打开 OpenClaw 的 Web 管理界面。
提示
如果浏览器没有自动打开,可以手动访问 http://127.0.0.1:18789
常用命令
管理命令
# 打开 Web Dashboard
openclaw dashboard
# 启动 Gateway 控制平面
openclaw gateway --port 18789 --verbose
# 查看运行状态
openclaw status
# 查看日志
openclaw logs
# 运行诊断工具
openclaw doctor
# 停止所有服务
openclaw stopAgent 命令
# 与助手对话
openclaw agent --message "你好" --thinking high
# 发送消息到指定渠道
openclaw message send --to +1234567890 --message "Hello from OpenClaw"
# 列出所有 Agent
openclaw agents list
# 添加新 Agent
openclaw agents add <agent-name>
# 编辑 Agent 配置
openclaw agents edit <agent-name>Channel 命令
# 列出所有渠道
openclaw channels list
# 添加新渠道
openclaw channels add
# 删除渠道
openclaw channels remove <channel-name>
# 重启渠道
openclaw channels restart <channel-name>Skill 命令
# 列出已安装的技能
openclaw skills list
# 搜索技能(需要先安装 clawhub)
clawhub search <关键词>
# 安装技能
clawhub install <skill-name>
# 卸载技能
openclaw skills uninstall <skill-name>Plugin 命令
# 列出所有插件
openclaw plugins list
# 启用插件
openclaw plugins enable <plugin-name>
# 禁用插件
openclaw plugins disable <plugin-name>更新命令
# 更新到最新稳定版
openclaw update
# 切换版本通道
openclaw update --channel stable # 稳定版
openclaw update --channel beta # 测试版
openclaw update --channel dev # 开发版从源码构建(开发者)
如果你想参与 OpenClaw 的开发或使用最新的开发版本:
克隆仓库
git clone https://github.com/openclaw/openclaw.git
cd openclaw安装依赖
# 推荐使用 pnpm
pnpm install
# 或使用 npm
npm install构建项目
# 构建 UI
pnpm ui:build
# 构建核心
pnpm build运行开发服务器
# 启动 Gateway(开发模式,支持热重载)
pnpm gateway:watch
# 或启动完整服务
pnpm dev运行测试
# 运行单元测试
pnpm test
# 运行集成测试
pnpm test:integration
# 代码检查
pnpm lint配置文件位置
OpenClaw 的配置文件存储在以下位置:
Linux / macOS
~/.openclaw/
├── config.json # 主配置文件
├── agents/ # Agent 工作区
│ ├── main/
│ │ ├── SOUL.md
│ │ ├── USER.md
│ │ └── AGENTS.md
│ └── ...
├── channels/ # 渠道配置
├── skills/ # 已安装的技能
└── logs/ # 日志文件Windows
C:\Users\<用户名>\.openclaw\
├── config.json
├── agents\
├── channels\
├── skills\
└── logs\守护进程配置
安装守护进程
openclaw onboard --install-daemon管理守护进程
# 启动守护进程
openclaw daemon start
# 停止守护进程
openclaw daemon stop
# 重启守护进程
openclaw daemon restart
# 查看守护进程状态
openclaw daemon status开机自启动
Linux (systemd)
# 创建 systemd 服务
sudo nano /etc/systemd/system/openclaw.service添加以下内容:
[Unit]
Description=OpenClaw AI Agent
After=network.target
[Service]
Type=simple
User=<你的用户名>
ExecStart=/usr/bin/openclaw gateway
Restart=always
[Install]
WantedBy=multi-user.target启用服务:
sudo systemctl enable openclaw
sudo systemctl start openclawmacOS (launchd)
# 创建 plist 文件
nano ~/Library/LaunchAgents/ai.openclaw.plist添加以下内容:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>Label</key>
<string>ai.openclaw</string>
<key>ProgramArguments</key>
<array>
<string>/usr/local/bin/openclaw</string>
<string>gateway</string>
</array>
<key>RunAtLoad</key>
<true/>
<key>KeepAlive</key>
<true/>
</dict>
</plist>加载服务:
launchctl load ~/Library/LaunchAgents/ai.openclaw.plist常见问题
Q: 安装时提示权限错误?
如果遇到 EACCES 权限错误,可以:
- 使用 nvm 管理 Node.js(推荐)
- 或配置 npm 全局目录:
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrcQ: 如何卸载 OpenClaw?
# 卸载全局包
npm uninstall -g openclaw
# 删除配置文件(可选)
rm -rf ~/.openclawQ: 如何更换模型供应商?
# 重新运行配置向导
openclaw onboard
# 或直接编辑配置文件
openclaw config editQ: 端口 18789 被占用怎么办?
# 使用其他端口启动
openclaw gateway --port 18790下一步
安装完成后,你可以: