Skip to content

INSTALLATION.md

Latest commit

 

History

History
250 lines (166 loc) · 3.88 KB

INSTALLATION.md

File metadata and controls

250 lines (166 loc) · 3.88 KB

安装指南

📋 前置要求

必需软件

  1. Node.js (v22.12 或更高版本)

    node --version
# 应该显示 v22.12.x 或更高

  2. npm (通常随 Node.js 一起安装)

    npm --version
# 应该显示 8.x.x 或更高

  3. pnpm (用于构建 Web UI)

    pnpm --version
# 如果未安装，可执行：
# corepack enable
# corepack prepare pnpm@latest --activate

  4. Google Chrome (用于调试浏览器)

    • macOS: 已安装
    • Linux: sudo apt install google-chrome-stable
    • Windows: 下载安装

Shell 环境说明（Windows 用户必读）

  • onboard.sh / server.sh / start-chrome-debug.sh 需要在 Bash 环境运行。
  • Windows 推荐使用 WSL（优先）或 Git Bash。
  • 纯 cmd.exe / 原生 PowerShell 不能直接执行 .sh 脚本。

可选软件

  • Git (用于克隆代码) 
    git --version

🚀 安装步骤

步骤 1：克隆或下载代码

使用 Git：

git clone <repository-url>
cd openclaw-zero-token

或者直接下载：

  • 下载 ZIP 文件
  • 解压到目录
  • 进入目录

步骤 2：安装依赖

npm install

预期输出：

added 500+ packages in 30s

如果遇到错误：

# 清理缓存
npm cache clean --force

# 删除 node_modules 和 package-lock.json
rm -rf node_modules package-lock.json

# 重新安装
npm install

步骤 3：编译代码

npm run build
pnpm ui:build   # 构建 Web UI，访问 http://127.0.0.1:3001 时需要

预期输出：

✔ Build complete in 7919ms
✓ built in 1.13s   # ui:build

验证编译成功：

ls dist/index.mjs
ls dist/control-ui/index.html   # Web UI 资源
# 应该看到文件存在

步骤 4：验证安装

# 检查编译后的文件
ls -lh dist/index.mjs

# 应该看到类似输出：
# -rw-r--r--  1 user  staff   2.5M Feb 27 10:00 dist/index.mjs

🔧 配置环境

创建配置目录

配置目录会在首次运行时自动创建（推荐，不需要手动创建）：

./onboard.sh webauth

检查配置文件

# 查看配置文件（如果存在）
cat .openclaw-zero-state/openclaw.json

# 查看认证配置（如果存在）
cat .openclaw-zero-state/agents/main/agent/auth-profiles.json

关键规则：只有在 ./onboard.sh webauth 中完成配置的平台，才会被写入 openclaw.json 并出现在最终 /models 列表中。

✅ 安装完成检查清单

  • Node.js 已安装（v22.12+）
  • npm 已安装
  • pnpm 已安装
  • 依赖已安装（npm install）
  • 代码已编译（npm run build）
  • dist/index.mjs 文件存在
  • Google Chrome 已安装

🎯 下一步

安装完成后，继续阅读：

  1. START_HERE.md - 快速开始指南
  2. TEST_STEPS.md - 详细测试步骤

🔧 常见问题

Q1: npm install 失败

A: 尝试以下方法：

# 使用国内镜像（如果在中国）
npm config set registry https://registry.npmmirror.com

# 重新安装
npm install

Q2: npm run build 失败

A: 检查 Node.js 版本：

node --version
# 必须是 v22.12 或更高

# 如果版本太低，升级 Node.js

Q3: 权限错误

A: 不要使用 sudo：

# 错误：sudo npm install
# 正确：npm install

Q4: 磁盘空间不足

A: 检查磁盘空间：

df -h

# node_modules 大约需要 500MB
# dist 大约需要 10MB

📚 相关命令

# 安装依赖
npm install

# 编译代码
npm run build

# 清理编译产物
rm -rf dist

# 重新编译
npm run build

# 查看 npm 脚本
npm run

# 检查依赖版本
npm list --depth=0

🎉 安装成功！

现在你可以开始测试了。继续阅读 START_HERE.md 开始测试流程。