U-Claw 教程

从零开始，搭建你的私人 AI 助手 —— 小白也能看懂

什么是 OpenClaw？

OpenClaw 是一个开源 AI 助手框架，可以理解为：

核心架构

你的聊天平台 ←→ OpenClaw Gateway ←→ AI 模型
  (QQ/飞书/TG)      (你的电脑)        (DeepSeek/Kimi/Claude)
                         ↕
                    技能 & 工具
              (邮件/笔记/日程/搜索...)

U-Claw 是 OpenClaw 的便携版 —— 把整套系统做成 U 盘，插上就能用，还能安装到电脑。所有依赖走国内镜像，无需翻墙。

选择安装方式

方式 A：U 盘安装 推荐小白

最简单的方式，不需要联网，不需要终端知识。

安装到电脑（可选）

如果不想每次都插 U 盘：

• Mac：双击 Mac-Install.command，安装到 ~/.uclaw/
• Windows：双击 Windows-Install.bat，安装到 %USERPROFILE%\.uclaw\

方式 B：一键脚本安装

需要联网，通过终端一行命令完成安装。

Mac / Linux / WSL2

curl -fsSL https://openclaw.ai/install.sh | bash

Windows (PowerShell 管理员)

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
iwr -useb https://openclaw.ai/install.ps1 | iex

验证安装

openclaw --version    # 查看版本
openclaw onboard      # 启动配置向导

方式 C：完全手工安装 开发者推荐

一步一步手动安装，理解每个组件。适合想深入学习、或网络环境特殊的用户。

第一步：安装 Node.js 22+

OpenClaw 运行在 Node.js 上，需要 v22 或更高版本。

方法 A：官网下载（最简单）

• 国内直连：nodejs.cn/download（速度快）
• 官网：nodejs.org/download

下载 .pkg（Mac）或 .msi（Windows）安装包，双击安装。

方法 B：nvm 版本管理器（开发者推荐）

# 1. 安装 nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash

# 2. 设置国内镜像（关键！否则下载很慢）
echo 'export NVM_NODEJS_ORG_MIRROR=https://npmmirror.com/mirrors/node' >> ~/.zshrc
source ~/.zshrc

# 3. 安装 Node.js 22
nvm install 22
nvm use 22

# 4. 验证
node -v   # 应显示 v22.x.x

方法 C：fnm（更快，基于 Rust）

# Mac/Linux
curl -fsSL https://fnm.vercel.app/install | bash
echo 'export FNM_NODE_DIST_MIRROR=https://npmmirror.com/mirrors/node' >> ~/.zshrc
source ~/.zshrc
fnm install 22

# Windows (PowerShell)
winget install Schniz.fnm
fnm install 22

第二步：设置 npm 国内镜像

# 设置淘宝 npmmirror（首选，最快最稳）
npm config set registry https://registry.npmmirror.com

# 验证
npm config get registry
# 应返回: https://registry.npmmirror.com/

第三步：安装 OpenClaw

方式 A：npm 安装（通用）

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

# 如果超时，手动指定镜像
npm install -g openclaw@latest --registry=https://registry.npmmirror.com

# 验证
openclaw --version

方式 B：pnpm 安装（更快）

# 如果没有 pnpm，先安装
npm install -g pnpm

# 用 pnpm 安装 OpenClaw
pnpm add -g openclaw@latest
pnpm approve-builds -g
openclaw onboard --install-daemon

方式 C：从源码构建（开发者）

git clone https://github.com/openclaw/openclaw.git
cd openclaw && pnpm install && pnpm ui:build && pnpm build
pnpm link --global
openclaw --version

常见安装问题

SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install -g openclaw@latest

# 添加到 ~/.zshrc 或 ~/.bashrc
export PATH="$(npm prefix -g)/bin:$PATH"
source ~/.zshrc

第四步：启动配置向导

# 推荐：启动向导 + 安装后台服务
openclaw onboard --install-daemon

# 或只启动向导
openclaw onboard

向导会引导你完成：模型选择 → API Key → 聊天平台 → 后台服务。详见下方模型配置章节。

第五步：验证一切正常

openclaw status          # 查看运行状态
openclaw doctor --repair # 诊断并修复问题
openclaw dashboard       # 打开网页控制台

模型选择指南

新手首次配置推荐

如果你是第一次配置 AI 模型，以下模型配置最简单，适合入门：

DeepSeek 配置 国内首选

openclaw onboard
# 选择 Custom Provider
# Base URL: https://api.deepseek.com/v1
# API Key: 粘贴你的 Key
# Model: deepseek-chat

# 编辑 ~/.openclaw/openclaw.json
{
  "models": {
    "providers": {
      "deepseek": {
        "baseUrl": "https://api.deepseek.com/v1",
        "apiKey": "sk-你的Key",
        "api": "openai-completions",
        "models": [{
          "id": "deepseek-chat",
          "name": "DeepSeek Chat",
          "contextWindow": 128000
        }]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": { "primary": "deepseek/deepseek-chat" }
    }
  }
}

openclaw gateway restart
openclaw tui
# 在终端中对话测试

Kimi / 月之暗面 配置

openclaw onboard
# 选择 Moonshot AI
# API Key: 粘贴你的 Key
# Model: moonshot-v1-128k（或 moonshot-v1-8k）

通义千问 Qwen 配置 免费额度大

openclaw onboard
# 选择 Qwen
# API Key: 粘贴你的 Key

国际模型（Claude / GPT / Gemini）

通过 OpenRouter（推荐）

OpenRouter 汇聚了主流 AI 模型，一个 API Key 用所有模型，部分有免费额度。

openclaw onboard
# 选择 OpenRouter
# API Key: 粘贴
# Model: 选择你要用的模型

直连方式

QQ 机器人 国内首选 · 1 分钟搞定

腾讯官方已为 OpenClaw 开放 QQ 机器人能力。完全免费，无需翻墙。

# 安装 QQ 插件（U-Claw 用户已预装，跳过此步）
openclaw plugins install @sliverp/qqbot@latest

# 绑定 QQ 机器人
openclaw channels add --channel qqbot --token "你的AppID:你的AppSecret"

# 设置白名单（重要！否则任何人都能用你的机器人）
openclaw config set channels.qqbot.allowFrom "你的QQ号"

# 重启生效
openclaw gateway restart

Telegram 机器人

# 方式 A：通过向导
openclaw onboard    # 选择 Telegram，输入 Token

# 方式 B：命令行
openclaw channels add --channel telegram --token "你的BotToken"
openclaw gateway restart

openclaw pairing approve telegram 配对码

飞书机器人 企业推荐

openclaw channels add --channel feishu --token "你的AppID:你的AppSecret"
openclaw gateway restart

微信机器人 社区插件

# 安装微信插件（基于 iPad 协议）
openclaw plugins install @icesword760/openclaw-wechat

# 重启网关
openclaw gateway restart

# 按提示扫码登录微信

Discord 机器人

openclaw channels add --channel discord --token "你的BotToken"
openclaw gateway restart

使用场景

技能系统

U-Claw 已预装 52 个技能，开箱即用。

# 搜索更多技能
openclaw skills search 翻译

# 安装新技能
openclaw skills install @xxx/skill-name

定时任务

# 每天早上 8 点发送天气预报
openclaw cron add "0 8 * * *" "查看今天深圳天气并发送到飞书"

# 每小时检查邮件
openclaw cron add "0 * * * *" "检查新邮件，有重要的通知我"

# 每天下午 6 点总结工作
openclaw cron add "0 18 * * *" "总结今天的工作进度"

# 查看所有定时任务
openclaw cron list

命令速查

故障排除

"Node.js v22+ is required"

# 检查当前版本
node -v

# 如果低于 v22，升级
nvm install 22    # 如果用 nvm
fnm install 22    # 如果用 fnm
# 或从 nodejs.cn 下载最新版

npm install 超时

# 设置淘宝镜像
npm config set registry https://registry.npmmirror.com

# 清除缓存重试
npm cache clean --force
npm install -g openclaw@latest

AI 不回复消息

1. 检查 API Key 是否正确：openclaw configure
2. 检查网关是否在运行：openclaw status
3. 查看错误日志：openclaw logs --follow
4. 运行诊断：openclaw doctor --repair

端口被占用

# 查看谁占用了端口
# Mac/Linux:
lsof -i :18789
# Windows:
netstat -ano | findstr ":18789"

# 杀死进程后重启
openclaw gateway restart

sharp 构建失败

# 跳过 sharp 本地编译
SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install -g openclaw@latest

sharp 是图片处理库，某些系统缺少编译工具会报错。上面的环境变量可跳过本地编译。

找不到 openclaw 命令（PATH 问题）

# 查看全局 bin 目录
npm prefix -g

# 添加到 PATH（写入 ~/.zshrc 或 ~/.bashrc）
export PATH="$(npm prefix -g)/bin:$PATH"
source ~/.zshrc

Windows：原生 vs WSL2

原生 Windows 安装可能遇到路径、权限、编译工具问题。推荐使用 WSL2：

# 安装 WSL2（管理员 PowerShell）
wsl --install

# 然后在 WSL2 Ubuntu 中按 Mac/Linux 步骤安装

完全重置

# 重置所有配置
openclaw reset --scope full

# 或手动删除
rm -rf ~/.openclaw    # Mac/Linux
rd /s /q %USERPROFILE%\.openclaw    # Windows

多模型与省钱技巧

1. 日常对话用 DeepSeek（~1元/百万 token），复杂任务切 Claude
2. 用 OpenRouter 统一管理多个模型，一个 Key 用所有
3. 为不同聊天平台配置不同模型（QQ 用便宜的，工作飞书用好的）
4. 善用免费额度：通义千问、Gemini 都有大量免费额度

VPS 部署（24/7 在线）

推荐配置

Docker 一键部署

git clone https://github.com/openclaw/openclaw.git
cd openclaw
cp .env.example .env
# 编辑 .env，填入 API Key 和 Bot Token
docker compose up -d

安全加固

• API Key 安全：不要在群聊中发送 API Key，不要提交到 GitHub
• 白名单：所有聊天平台务必设置 allowFrom，限制谁能用你的机器人
• Token 管理：定期轮换 Gateway Token 和 Bot Token
• 网络安全：Gateway 默认只监听 127.0.0.1，暴露到公网请配置反向代理 + HTTPS
• 权限最小化：只给聊天平台必要的权限，不要开放所有权限

配置文件参考

配置文件位置：~/.openclaw/openclaw.json（U-Claw 用户：U-Claw/data/.openclaw/openclaw.json）

{
  "gateway": {
    "mode": "local",
    "port": 18789,
    "bind": "127.0.0.1",
    "auth": { "token": "你的Token" }
  },
  "models": {
    "providers": {
      "deepseek": {
        "baseUrl": "https://api.deepseek.com/v1",
        "apiKey": "sk-xxx",
        "api": "openai-completions",
        "models": [{ "id": "deepseek-chat", "contextWindow": 128000 }]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": { "primary": "deepseek/deepseek-chat" }
    }
  },
  "channels": {
    "telegram": { "enabled": true, "botToken": "xxx:xxx" },
    "qqbot": { "enabled": true, "appId": "xxx", "appSecret": "xxx" }
  }
}

社区资源