WorkClaw CLI

WorkClaw CLI 是一个用于初始化和配置 WorkClaw 插件的命令行工具。

✨ 特性

• 🚀 快速初始化 - 一键安装 WorkClaw 插件
• 🔐 安全认证 - RSA 加密密码，保护用户隐私
• 🌐 多平台支持 - Windows, macOS, Linux
• 📊 详细日志 - 完整的请求/响应日志
• 🎨 友好界面 - 彩色输出和加载动画
• 📦 npm 安装 - 支持自定义安装路径
• 🔧 灵活配置 - 支持自定义 OpenClaw 安装目录

📋 前置要求

• Node.js: >= 20.0.0
• 包管理器: npm / pnpm / yarn（推荐 pnpm）

🚀 快速开始

使用 npx（推荐，无需安装）

# 本地账户安装
npx @workclaw/cli local

# 盒子设备安装
npx @workclaw/cli box

# 查看帮助
npx @workclaw/cli --help

全局安装后使用

# 全局安装
npm install -g @workclaw/cli

# 本地账户安装
workclaw local

# 盒子设备安装
workclaw box

📖 两种安装模式

local 命令 - 本地账户安装

适用场景：个人电脑或需要用户登录的设备

特点：

• ✅ 需要用户登录（手机号 + 密码）
• ✅ 自动获取 appKey 和 appSecret
• ✅ 支持多账号管理
• ✅ 自动创建和管理配置

安装流程：

1. 用户登录（RSA 加密密码）
2. 获取绑定配置
3. 通过手机号补全配置
4. 下载并安装插件
5. 更新配置文件

box 命令 - 盒子设备安装

适用场景：专用设备或无需用户登录的环境

特点：

• ✅ 无需登录（直接使用 appKey + appSecret）
• ✅ 适合批量部署
• ✅ 配置文件默认设置为开放策略
• ✅ 更快的安装速度

安装流程：

1. 清理旧版本插件
2. 下载并安装插件
3. 更新配置文件（dmPolicy: "open"）

📖 使用文档

命令

# 本地账户安装（需要登录）
npx @workclaw/cli local [options]

# 盒子设备安装（无需登录）
npx @workclaw/cli box [options]

# 查看帮助
npx @workclaw/cli --help

local 命令参数

| 参数 | 说明 | | ---------------- | ------------------------------------------ | | --phone | 手机号码（登录账号），未填写时会交互式提示输入 | | --user-pass | 用户密码，未填写时会交互式提示输入 | | --env | 环境 (test/prod/custom)，默认 test，未填写时会交互式提示选择 | | --customIp | 自定义环境后端 IP，仅当 env 为 custom 时使用 | | --plugin-version | 插件版本号（默认安装最新版） | | --openclaw-path | OpenClaw 安装目录（默认 ~/.openclaw） | | --debug | 开启调试日志 |

box 命令参数

| 参数 | 说明 | | ---------------- | ------------------------------------------ | | --app-key | App Key，未填写时会交互式提示输入 | | --app-secret | App Secret，未填写时会交互式提示输入 | | --env | 环境 (test/prod/custom)，默认 test，未填写时会交互式提示选择 | | --customIp | 自定义环境后端 IP，仅当 env 为 custom 时使用 | | --plugin-version | 插件版本号（默认安装最新版） | | --openclaw-path | OpenClaw 安装目录（默认 ~/.openclaw） | | --debug | 开启调试日志 |

💡 使用示例

本地账户安装

# 交互式安装（会提示输入手机号和密码）
npx @workclaw/cli local

# 指定手机号和密码
npx @workclaw/cli local --phone your_phone --user-pass your_password

# 指定正式环境
npx @workclaw/cli local --env prod --phone your_phone --user-pass your_password

# 自定义安装路径
npx @workclaw/cli local --openclaw-path "C:\CustomPath\OpenClaw" --phone your_phone --user-pass your_password

# 开启调试模式
npx @workclaw/cli local --debug --phone your_phone --user-pass your_password

# 自定义环境（使用本地后端服务）
npx @workclaw/cli local --env custom --phone your_phone --user-pass your_password

# 自定义环境（命令行直接传入 IP）
npx @workclaw/cli local --env custom --customIp 192.168.1.100:32005 --phone your_phone --user-pass your_password

# 自定义环境（带协议完整地址）
npx @workclaw/cli local --env custom --customIp http://127.0.0.1:32005 --phone your_phone --user-pass your_password

盒子设备安装

# 交互式安装（会提示输入 AppKey 和 AppSecret）
npx @workclaw/cli box

# 指定参数
npx @workclaw/cli box --app-key your-app-key --app-secret your-app-secret

# 指定正式环境
npx @workclaw/cli box --env prod --app-key your-app-key --app-secret your-app-secret

# 自定义安装路径
npx @workclaw/cli box --openclaw-path "/custom/path" --app-key your-app-key --app-secret your-app-secret

# 开启调试模式
npx @workclaw/cli box --debug --app-key your-app-key --app-secret your-app-secret

# 自定义环境（使用本地后端服务）
npx @workclaw/cli box --env custom --app-key your-app-key --app-secret your-app-secret

# 自定义环境（命令行直接传入 IP）
npx @workclaw/cli box --env custom --customIp 192.168.1.100:32005 --app-key your-app-key --app-secret your-app-secret

🔧 技术实现

安装机制

1. 插件下载
   • 使用 npm pack 从 npm 镜像源下载插件包
   • 默认使用腾讯云 npm 镜像：https://mirrors.tencent.com/npm/
   • 支持重试机制（最多 3 次）
2. 文件解压
   • 使用 tar.extract() 解压到目标目录
   • 自动创建必要的目录结构
3. 依赖安装
   • 使用 npm install --omit=dev 安装生产依赖
   • 自动跳过开发依赖，减小安装体积

路径结构

~/.openclaw/                    # 或自定义路径
├── openclaw.json              # 主配置文件
├── extensions/
│   └── openclaw-workclaw/     # 插件目录
│       ├── package.json
│       ├── dist/
│       └── ...
├── workspace/                 # 工作空间
└── .temp/                    # 临时文件

路径验证

工具会自动验证用户输入的 --openclaw-path 参数：

• ✅ 必须是绝对路径
• ✅ 不能包含非法字符：< > : " | ? *

❓ 常见问题

Q: 安装失败，提示"网络错误"？

A: 检查网络连接，可以尝试：

• 使用代理或 VPN
• 配置 npm 镜像源：npm config set registry https://registry.npmmirror.com

Q: 提示"路径必须是绝对路径"？

A: --openclaw-path 需要使用绝对路径，例如：

• Windows: C:\OpenClaw 或 C:/OpenClaw
• Linux/macOS: /opt/openclaw

Q: 如何查看详细日志？

A: 使用 --debug 参数：

npx @workclaw/cli local --debug --phone your_phone --user-pass your_password

Q: 如何指定插件版本？

A: 使用 --plugin-version 参数：

npx @workclaw/cli local --plugin-version 1.0.100 --phone your_phone --user-pass your_password

Q: local 和 box 命令有什么区别？

A:

• local: 需要用户登录，适合个人设备，支持多账号
• box: 无需登录，直接使用 appKey+appSecret，适合专用设备

Q: 什么是自定义环境（custom）？

A:

自定义环境允许你连接到自己本地或私有部署的后端服务，适合前后端联调测试场景。使用方式：

1. 选择 custom 环境
2. 输入你的后端 IP 地址（支持 192.168.1.100:32005 或 http://127.0.0.1:32005 格式）
3. 工具会自动适配协议和路径

MODEL_BASE_URL 始终保持为固定值，不会随自定义环境改变。

🛠 开发

项目结构

packages/cli/
├── src/
│   ├── bin/              # CLI 入口
│   ├── local/            # 本地账户安装模块
│   │   ├── installer/    # 安装器
│   │   ├── apis/        # API 调用
│   │   ├── types/       # 类型定义
│   │   ├── error/       # 错误处理
│   │   └── utils/       # 工具函数
│   ├── box/              # 盒子设备安装模块
│   ├── shared/           # 共享模块
│   └── utils/            # 工具函数
├── package.json
├── vite.config.ts
└── README.md

构建

# 安装依赖
pnpm install

# 构建项目
pnpm build

# 代码检查
pnpm lint

# 自动修复
pnpm lint:fix

📝 更新日志

v1.0.314 (2026-04-27)

• ✨ 新增自定义环境（custom）- 支持连接私有部署后端服务
• 🔧 新增 --customIp 参数 - 命令行直接传入自定义后端 IP
• 🎨 优化交互体验 - 仅选择 custom 环境时才提示输入 IP
• 📝 更新文档 - 添加自定义环境使用说明和示例
• 🔒 MODEL_BASE_URL 保持固定，不随自定义环境改变

v1.0.313 (2026-04-23)

• ✨ 新增 --openclaw-path 参数 - 支持自定义安装路径
• 🔧 新增路径验证功能 - 检查绝对路径和非法字符
• ⚡ 优化安装流程 - 使用 npm pack + tar 替代 openclaw 命令
• 🔒 移除 --scenario 参数 - 自动检测系统环境
• 📦 更新 npm 镜像源 - 使用腾讯云 npm 镜像
• 📝 完善文档和错误提示

v1.0.30 (2026-04-08)

• ✨ 新增 local 命令 - 本地账户安装（需要登录）
• ✨ 新增 box 命令 - 盒子设备安装（无需登录）
• 🔧 重构命令结构，分离 local 和 box 命令
• 🔒 新增 RSA 密码加密
• 📝 新增完整请求日志
• 🎨 优化交互式提示和进度显示

v1.0.0

• 🎉 初始版本
• ✨ 支持 appKey + appSecret 认证
• ✨ 支持多平台安装

📄 许可证

MIT License

📞 联系方式

如有问题，请联系项目维护者。

🙏 致谢

• commander - 命令行解析
• chalk - 彩色输出
• ora - 加载动画
• axios - HTTP 客户端
• tar - tar 文件解压