安装与环境

在开始安装之前，请确保你的系统满足以下要求，以便获得最佳的运行体验。

💻 环境要求

必需环境

Node.js ≥ 22.0.0
npm ≥ 10.0.0（或 pnpm ≥ 8.0.0）

检查环境

在安装前，先检查你的 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

⚙️ 初始化配置

运行引导向导

执行以下命令启动交互式配置向导：

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 授权流程

CLI 提示示例（使用 MiniMax）：

? 选择认证方式: MiniMax M2.5(CN)
? 输入 API Key: [粘贴你的 API Key]
✓ 认证成功

4. 跳过可选配置

首次配置时，可以暂时全部回车跳过以下配置，后续随时可以通过指令拉起：

Channel（渠道）配置 - 稍后单独配置
Skill（技能）安装 - 稍后从官方市场安装
Hooks（钩子）配置 - 属于高级功能，稍后配置

5. 打开 Web UI

配置收尾阶段，控制中心会询问你是否在浏览器中可视化查看：

? 是否打开 Web UI? Yes
✓ 正在启动 Dashboard...
✓ Dashboard 已启动: http://127.0.0.1:18789

提示：如果浏览器没有自动打开，可以通过手动访问 http://127.0.0.1:18789

⌨️ 常用命令字典

管理命令

# 打开 Web Dashboard
openclaw dashboard

# 启动 Gateway 控制平面
openclaw gateway --port 18789 --verbose

# 查看运行状态
openclaw status

# 查看日志
openclaw logs

# 运行诊断排错工具
openclaw doctor

# 停止所有相关联服务
openclaw stop

Agent（智能体）命令

# 通过终端直接与默认助手对话
openclaw agent --message "你好" --thinking high

# 发送消息到指定被接管渠道
openclaw message send --to +1234567890 --message "Hello from OpenClaw"

# 列出库中所有的自定义 Agent
openclaw agents list

# 脚手架：添加新 Agent
openclaw agents add <agent-name>

# Vim编辑 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>

更新升级命令

# 原地全量更新到最新稳定版
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/            # 渠道 Token 存储与配置
├── skills/              # 第三方已安装技能代码块
└── logs/                # 轮转生成的日志文件夹

Windows

C:\Users\<用户名>\.openclaw\
├── config.json
├── agents\
├── channels\
├── skills\
└── logs\

🛡️ 进程守护服务配置

如果你需要将 OpenClaw 作为纯静默后端开机长期挂接，可以将其丢到系统守护。

安装并在后台启动守护进程

openclaw onboard --install-daemon

CLI 快捷管理守护状态

# 手动唤起守护进程
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 Runtime
After=network.target

[Service]
Type=simple
User=<你的用户名>
ExecStart=/usr/bin/openclaw gateway
Restart=always
RestartSec=3

[Install]
WantedBy=multi-user.target

激活并启动静默服务：

sudo systemctl enable openclaw
sudo systemctl start openclaw

macOS (launchd) 方案

# 为当前用户创建 plist 文件
nano ~/Library/LaunchAgents/ai.openclaw.plist

写入以下标准 XML：

<?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>

加载刚才挂载的 Launch 守护文件：

launchctl load ~/Library/LaunchAgents/ai.openclaw.plist

❓ 安装答疑避坑手册

Q: 尝试 npm 安装时疯狂提示权限错误？

如果你在终端遇到了红彤彤的 EACCES 无权限拒绝错误，你的当前策略通常是尝试添加 sudo，但其实这非常不安全，正确的做法是：

上乘解：使用 nvm 第三方节点包管理器控制 Node.js 全局权限。
权宜解：主动配置重定向 npm 的全局安装目录：

mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

Q: 我想从当前的硬盘系统里干干净净地干掉 OpenClaw 怎么办？

# 清除命令行全局二进制入口
npm uninstall -g openclaw

# （关键）摧毁沙盒配置源文件夹
rm -rf ~/.openclaw

Q: 启动报 18789 被抢占？

因为端口冲突导致服务未能正常拉起。

# 挂载额外端口参数来跳脱默认端口
openclaw gateway --port 18790

🧭 下一步指引

当你在终端看到没有任何 Error 的输出，恭喜你已经完成了对 OpenClaw 所有的基石构建！接下来：

快速开始配置 - 完成对助手的初级认知驯化
接入渠道 - 将 AI 请进你最活跃的聊天软件里
安装技能 - 为 Agent 脑门插上插件来干活
配置更多模型 - 随时随意地切换各大语言大模型的基座大脑

安装与环境

On this page