3 分钟快速上手

U 盘便携版（免安装）

从 U 盘运行（免安装便携模式）

便携模式下，所有配置、API Key、记忆保存在 U 盘的 data/ 目录。换电脑插上 U 盘，配置还在。

U 盘文件说明

目录结构

portable/
├── app/                    ← 运行时（约 2.3GB）
│   ├── core/                  OpenClaw + 依赖 + QQ 插件
│   └── runtime/
│       ├── node-mac-arm64/    Mac Apple Silicon
│       ├── node-win-x64/     Windows 64-bit
├── data/                   ← 用户数据（配置、记忆、备份）
│   ├── .openclaw/             openclaw.json 配置文件
│   ├── memory/                AI 记忆
│   └── backups/               备份
└── [启动脚本和HTML页面]

首次配置向导

首次运行自动进入 onboard 向导：

手动重新运行：openclaw onboard

国产模型（免翻墙）

新手首次配置推荐

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

国际模型

通过 OpenRouter（推荐）

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

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

DeepSeek 配置指南

配置步骤

Base URL:  https://api.deepseek.com/v1
API Key:   你的 DeepSeek API Key
Model ID:  deepseek-chat
Alias:     deepseek（可自定义）

API Key 申请：platform.deepseek.com

QQ 机器人接入（1 分钟）

# 安装 QQ 插件
openclaw plugins install @sliverp/qqbot@latest

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

# 设置白名单（重要！）
openclaw config set channels.qqbot.allowFrom "你的QQ号"

# 重启网关
openclaw gateway restart

飞书接入

OpenClaw 内置飞书支持（feishu 命令）。

# 安装飞书插件
openclaw plugins install @larksuiteoapi/feishu-openclaw-plugin

# 运行配置向导
openclaw onboard

钉钉接入

OpenClaw 内置钉钉连接器。

# 运行配置向导会引导钉钉配置
openclaw onboard

企业微信接入

OpenClaw 内置企业微信 API 支持。

# 运行配置向导
openclaw onboard

Telegram 接入（最快）

# 1. 在 @BotFather 创建 Bot，获取 Token
# 2. 添加渠道
openclaw channels add --channel telegram --token "你的Bot_Token"
# 3. 重启网关
openclaw gateway restart

全部聊天平台一览

技能概览

uClaw 预装了 52 个技能，覆盖编程、搜索、文件管理、社交媒体等场景。总大小仅 404KB。

预装技能列表

国内热门技能推荐

以下技能专为国内社交媒体和内容创作设计，可通过 ClawHub 安装。

自媒体运营（6 大平台）

内容创作工具

数据分析与增长

一键安装全部自媒体技能

# 一键安装全部 6 大平台 + 创作工具（推荐）
clawhub install xiaohongshu-ops canghe-post-to-wechat douyin-publisher bilibili-helper weibo-scheduler multi-post copywriter headline-optimizer canghe-xhs-images trending-hot analytics-dashboard

基础效率工具（推荐新手）

技能安装与管理

# 查看已安装技能
openclaw skills list

# 安装新技能
openclaw skills install <skill-name>

# 从 ClawdHub 安装
openclaw skills install clawdhub/<skill-name>

# 创建自定义技能
openclaw skill-creator

网页控制台

启动网关后，浏览器访问：

http://127.0.0.1:18789

控制台功能

• 直接和 AI 聊天（无需其他平台）
• 查看所有渠道状态
• 管理技能和插件
• 查看聊天记录
• 配置模型和参数

手动打开：openclaw dashboard

常用命令速查

环境变量

uClaw 便携模式通过环境变量把配置指向 U 盘：

诊断修复

# 运行诊断
openclaw doctor

# 强制启动（端口被占用时）
openclaw gateway run --force

# 查看日志
openclaw logs

常见问题排查

• 端口 18789 被占用 — 加 --force 参数
• 控制台打不开 — 先运行 openclaw gateway status 确认网关在跑
• 渠道连不上 — 检查 API Key 是否正确，运行 openclaw status

维护与卸载

uClaw 的菜单脚本（Mac-Menu / Windows-Menu）内置了完整的维护功能，选择对应编号即可操作。

[9] 杀死残留进程

[10] 查看日志

data/logs/gateway.log

[11] 恢复出厂设置

[12] 完整卸载指南

rm -rf ~/Library/Application\ Support/uClaw/

rd /s /q "%APPDATA%\uClaw"

# 卸载 OpenClaw
npm uninstall -g openclaw

# 删除配置和数据
rm -rf ~/.openclaw/

[13] 检查更新

# U 盘便携版
cd app/core && npm update openclaw

# npm 全局安装版
npm update -g openclaw

# 查看当前版本
openclaw --version

[14] 清理空间

# npm 缓存
npm cache clean --force

# 日志
rm -f data/logs/gateway.log

# 备份
rm -rf data/backups/

[15] 插件管理

# 查看已安装插件
openclaw plugin list

# 安装插件
openclaw plugin install <插件名>

# 卸载插件
openclaw plugin uninstall <插件名>

常见问题

🛠️ AI 开发工具推荐

配置好 uClaw 之后，这些免费工具能帮你进一步提升效率——无论是在终端用 AI 写代码，还是用可视化编辑器开发项目。

🖥️ 终端 AI 工具（CLI）

CLI 工具运行在终端里，适合喜欢命令行操作或想快速完成自动化任务的用户。

uv tool install kimi-cli

📝 AI 编辑器（IDE）

如果你更习惯图形界面，AI 编辑器是更直观的选择。

📊 工具对比

万能启动 U 盘（裸机可用）

把 Ubuntu 系统 + OpenClaw 预装到 U 盘。任何 x86 电脑（Windows 台式机、Mac Intel、旧笔记本、裸机）插上 U 盘开机就能直接进入桌面 + AI 助手，不需要电脑上装任何系统。

准备材料

制作启动盘步骤

BIOS/UEFI 设置 USB 启动

sudo bash /media/*/Ventoy/uClaw-linux/format-persistence.sh

sudo bash /media/*/Ventoy/uClaw-linux/setup-openclaw.sh

bash /opt/uClaw/start-openclaw.sh

sudo bash /media/*/Ventoy/uClaw-linux/enable-ssh.sh

首次启动 Ubuntu

# 打开终端 (Ctrl+Alt+T)
sudo bash /media/*/Ventoy/uClaw-linux/format-persistence.sh

sudo bash /media/*/Ventoy/uClaw-linux/setup-openclaw.sh

日常使用

• 插入 U 盘 → 开机选 USB 启动 → Ventoy 菜单选 Ubuntu → 自动进入桌面
• 双击桌面的 uClaw AI Assistant 图标启动
• 浏览器自动打开控制台，开始使用
• 所有数据保存在持久化镜像中，重启不丢
• 关机前正常关闭 Ubuntu（不要直接拔 U 盘）

远程控制（用另一台电脑管理 Linux）

方法一：用 U 盘自带脚本（推荐）

如果 U 盘里有 uClaw-linux/ 目录：

sudo bash /media/*/Ventoy/uClaw-linux/enable-ssh.sh

脚本会自动安装 SSH、让你设密码、显示 IP 地址。

方法二：手动启用 SSH（3 条命令）

如果脚本找不到，或者没有 U 盘，手动也很简单：

sudo apt update && sudo apt install -y openssh-server && sudo systemctl start ssh

sudo passwd $USER

hostname -I

从另一台电脑连接

在 Mac / Windows / Linux 的终端输入：

ssh [email protected]

把 192.168.18.xx 换成上一步显示的实际 IP，输入刚才设的密码即可连接。

常见问题

USB 启动不了

• 检查 BIOS 启动顺序，确保 USB 排在硬盘前面
• 关闭 Secure Boot（BIOS → Security → Secure Boot → Disabled）
• 换一个 USB 口试试（优先 USB 3.0 蓝色口）
• Legacy/CSM 和 UEFI 模式都试试

持久化不生效（重启后配置丢失）

• 确认 persistence.dat 已格式化为 ext4（运行 format-persistence.sh）
• 确认 ventoy/ventoy.json 配置正确（image 路径与 ISO 文件名匹配）
• 格式化后必须重启才能生效

运行很慢

• 使用 USB 3.0 或更快的 U 盘 + USB 3.0 接口
• 首次加载约 1-3 分钟属正常
• 推荐品牌：三星 BAR Plus、闪迪 CZ880、金士顿

中国区原生安装教程

不用 U 盘，直接在中国网络环境下从零安装 OpenClaw。全程使用国内镜像，无需翻墙。

第一步：安装 Node.js

OpenClaw 需要 Node.js v22 或以上版本。

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

• Node.js 中文网：nodejs.cn/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. 设置 Node.js 国内镜像（关键！否则下载很慢）
export NVM_NODEJS_ORG_MIRROR=https://npmmirror.com/mirrors/node
echo 'export NVM_NODEJS_ORG_MIRROR=https://npmmirror.com/mirrors/node' >> ~/.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

# Windows (PowerShell):
winget install Schniz.fnm

# 设置国内镜像
export FNM_NODE_DIST_MIRROR=https://npmmirror.com/mirrors/node
echo 'export FNM_NODE_DIST_MIRROR=https://npmmirror.com/mirrors/node' >> ~/.zshrc

# 安装 Node.js 22
fnm install 22 && fnm use 22

第二步：设置 npm 国内镜像

安装完 Node.js 后，必须先换镜像源，否则安装 OpenClaw 会超时。

# 推荐：淘宝 npmmirror（最稳定，速度最快）
npm config set registry https://registry.npmmirror.com

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

国内可用的 npm 镜像源

使用 nrm 快速切换镜像

# 安装 nrm 镜像源管理工具
npm install -g nrm

nrm ls          # 查看所有可用镜像源
nrm use taobao  # 一键切换淘宝源
nrm test        # 测速，看哪个最快

第三步：安装 OpenClaw

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

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

# 验证
openclaw --version

用 pnpm 安装（更快）

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

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

从源码构建（开发者）

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

第四步：配置国产 AI 模型

启动配置向导：

# 启动引导向导 + 安装后台守护进程
openclaw onboard --install-daemon

# 或只启动引导向导
openclaw onboard

国产模型注册与配置

配置示例（DeepSeek）

# 在配置向导中：
# 1. 选择 Custom Provider
# 2. 填写：
#    API Base URL: https://api.deepseek.com/v1
#    API Key: sk-xxxxxxxx（在 platform.deepseek.com 获取）
#    Model: deepseek-chat

第五步：启动与验证

# 启动网关
openclaw gateway run

# 查看状态
openclaw gateway status

# 浏览器打开控制台
# http://127.0.0.1:18789

常见问题

npm install 超时 / ECONNREFUSED

# 1. 确认镜像源已切换
npm config get registry
# 应该是 https://registry.npmmirror.com/

# 2. 如果还超时，试其他镜像
npm config set registry https://mirrors.cloud.tencent.com/npm/

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

node: command not found

# 重新打开终端，或手动加载配置
source ~/.zshrc   # macOS
source ~/.bashrc  # Linux

openclaw onboard 报错

# 确认 Node.js 版本
node -v  # 需要 v22+

# 如果版本太低
nvm install 22 && nvm use 22
# 或
fnm install 22 && fnm use 22

API 调用失败

• 检查 API Key 是否正确（注意不要多余空格）
• 检查 API Base URL 是否正确
• 确认模型名称正确（如 deepseek-chat）
• 国产模型 API 直连，不需要翻墙

Kimi / 月之暗面 配置

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

通义千问 Qwen 配置

阿里云生态，免费额度大，适合免费体验。

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

OpenRouter 统一网关

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

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

直连方式

定时任务

通过 cron 设置自动执行的任务，让 AI 助手定时完成工作。

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

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

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

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

多模型与省钱技巧

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

安全加固

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

配置文件参考

配置文件位置：~/.openclaw/openclaw.json（uClaw 用户：uClaw/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" }
  }
}