CLI 命令参考

xopcbot 提供丰富的 CLI 命令用于管理、对话和配置。

使用方式

从 npm 安装（推荐）

bash

# 全局安装
npm install -g @xopcai/xopcbot

# 直接使用命令
xopcbot <command>

从源码运行（开发）

bash

# 克隆并安装
git clone https://github.com/xopcai/xopcbot.git
cd xopcbot
pnpm install

# 使用 pnpm run dev -- 前缀
pnpm run dev -- <command>

本文档中的命令示例默认使用 xopcbot 命令。 如果你从源码运行，请将 xopcbot 替换为 pnpm run dev --。

命令列表

命令	描述
`setup`	初始化配置文件和工作区目录
`onboard`	交互式设置向导（LLM、渠道、Gateway）
`agent`	与 Agent 对话
`gateway`	启动 REST 网关
`cron`	管理定时任务
`extension`	管理扩展
`skills`	管理技能（安装、启用、配置、测试）
`config`	查看和编辑配置（非交互式）

setup

仅初始化配置文件和工作区目录（无交互式提示）。

bash

xopcbot setup

参数：

参数	描述
`--workspace <path>`	工作区目录路径（默认：~/.xopcbot/workspace）

示例：

bash

# 创建默认配置和工作区
xopcbot setup

# 自定义工作区路径
xopcbot setup --workspace ~/my-workspace

功能：

创建 ~/.xopcbot/config.json（如果不存在）
创建工作区目录并生成引导文件（AGENTS.md、BOOTSTRAP.md 等）

onboard

xopcbot 的交互式设置向导。这是设置 xopcbot 的推荐方式。

bash

xopcbot onboard

选项：

选项	描述
`--model`	仅配置 LLM 提供商和模型
`--channels`	仅配置消息渠道
`--gateway`	仅配置 Gateway WebUI
`--all`	配置所有内容（默认）

示例：

bash

# 完整交互式设置（默认）
xopcbot onboard

# 仅配置 LLM 模型
xopcbot onboard --model

# 仅配置渠道
xopcbot onboard --channels

# 仅配置 Gateway
xopcbot onboard --gateway

功能（不带选项时）：

自动检测是否需要设置工作区
配置 LLM 提供商和模型
配置消息渠道（Telegram）
配置 Gateway WebUI 并自动生成 Token
完成后显示启动网关的命令

完成后：

onboard 完成后会显示：

Gateway 访问 URL
Token 信息
启动网关的命令

注意：Gateway 默认在前台运行。按 Ctrl+C 停止，或使用 xopcbot gateway stop 从另一个终端停止。

agent

与 Agent 对话。

单次对话

bash

xopcbot agent -m "Hello, world!"

参数：

参数	描述
`-m, --message`	发送的消息
`-s, --session`	会话键 (默认: default)
`-i, --interactive`	交互模式

交互模式

bash

xopcbot agent -i

使用：

> Hello!
Bot: Hello! How can I help?

> List files
Bot: File listing...

> quit

指定会话

bash

xopcbot agent -m "Continue our discussion" -s my-session

gateway

启动 REST API 网关。

前台模式（默认）

bash

xopcbot gateway --port 18790

网关默认在前台运行，按 Ctrl+C 停止。

参数：

参数	描述
`-p, --port`	端口号 (默认：18790)
`-h, --host`	绑定地址 (默认：0.0.0.0)
`--token`	认证令牌
`--no-hot-reload`	禁用配置热重载
`--force`	强制终止端口上的现有进程
`--background`	后台模式启动（分离进程）

强制启动

如果端口已被占用，使用 --force 自动终止现有进程：

bash

xopcbot gateway --force

这将发送 SIGTERM，等待 700ms，然后如需要发送 SIGKILL。

子命令

子命令	描述
`gateway status`	查看网关运行状态
`gateway stop`	停止运行的网关
`gateway restart`	重启网关
`gateway logs`	查看网关日志
`gateway token`	查看/生成认证令牌
`gateway install`	安装为系统服务
`gateway uninstall`	卸载系统服务
`gateway service-start`	通过系统服务启动
`gateway service-status`	查看服务状态

示例：

bash

# 查看状态
xopcbot gateway status

# 停止网关（SIGTERM，5秒超时）
xopcbot gateway stop

# 强制停止（立即 SIGKILL）
xopcbot gateway stop --force

# 重启网关（SIGUSR1 信号）
xopcbot gateway restart

# 强制重启（终止并重新启动）
xopcbot gateway restart --force

# 查看最近 50 行日志
xopcbot gateway logs

# 实时跟踪日志
xopcbot gateway logs --follow

# 生成新令牌
xopcbot gateway token --generate

# 安装为系统服务
xopcbot gateway install

# 卸载系统服务
xopcbot gateway uninstall

# 通过系统服务启动
xopcbot gateway service-start

# 查看服务状态
xopcbot gateway service-status

进程管理

锁文件：~/.xopcbot/locks/gateway.{hash}.lock（替代 PID 文件）
信号：SIGTERM/SIGINT=停止，SIGUSR1=重启
端口管理：自动冲突检测和解决

环境变量：

变量	描述
`XOPCBOT_NO_RESPAWN`	禁用进程重生
`XOPCBOT_ALLOW_SIGUSR1_RESTART`	允许 SIGUSR1 重启
`XOPCBOT_SERVICE_MARKER`	标记受监督环境

添加任务

bash

xopcbot cron add --schedule "0 9 * * *" --message "Good morning!"

参数：

参数	描述
`--schedule`	Cron 表达式
`--message`	定时发送的消息
`--name`	任务名称 (可选)

示例：

bash

# 每天 9 点
xopcbot cron add --schedule "0 9 * * *" --message "Daily update"

# 工作日 18 点
xopcbot cron add --schedule "0 18 * * 1-5" --message "Time to wrap up!"

# 每小时提醒
xopcbot cron add --schedule "0 * * * *" --message "Hourly reminder" --name hourly

删除任务

bash

xopcbot cron remove <task-id>

示例：

bash

xopcbot cron remove abc1

启用/禁用

bash

xopcbot cron enable <task-id>
xopcbot cron disable <task-id>

触发任务

bash

xopcbot cron trigger <task-id>

extension

管理扩展。支持三级存储：workspace (./.extensions/) → global (~/.xopcbot/extensions/) → bundled。

列出扩展

bash

xopcbot extension list

输出示例：

📦 Installed Extensions

══════════════════════════════════════════════════════════════════════

  📁 Workspace (./.extensions/)
    • My Custom Extension @ 0.1.0
      ID: my-custom-extension

  🌐 Global (~/.xopcbot/extensions/)
    • Telegram Channel @ 1.2.0
      ID: telegram-channel

  📦 Bundled (built-in)
    • Discord Channel @ 2.0.0
      ID: discord-channel

安装扩展

从 npm 安装到 workspace（默认）：

bash

xopcbot extension install <package-name>

# 示例
xopcbot extension install xopcbot-extension-telegram
xopcbot extension install @scope/my-extension
xopcbot extension install my-extension@1.0.0

安装到 global（跨项目共享）：

bash

xopcbot extension install <package-name> --global

# 示例
xopcbot extension install xopcbot-extension-telegram --global

从本地目录安装：

bash

# 安装到 workspace
xopcbot extension install ./my-local-extension

# 安装到 global
xopcbot extension install ./my-local-extension --global

参数：

参数	描述
`--global`	安装到全局目录 (~/.xopcbot/extensions/)
`--timeout <ms>`	安装超时时间（默认 120000ms）

安装流程：

下载/复制扩展文件
验证 xopcbot.extension.json 清单
安装依赖（如有 package.json 依赖）
复制到目标目录 (workspace/.extensions/ 或 ~/.xopcbot/extensions/)

三级存储说明：

Workspace (./.extensions/)：项目私有，优先级最高
Global (~/.xopcbot/extensions/)：用户级共享
Bundled：内置扩展，优先级最低

移除扩展

bash

xopcbot extension remove <extension-id>
# 或
xopcbot extension uninstall <extension-id>

示例：

bash

xopcbot extension remove telegram-channel

注意：

优先从 workspace 移除，如不存在则从 global 移除
移除后如果已启用，还需要从配置文件中删除

查看扩展详情

bash

xopcbot extension info <extension-id>

示例：

bash

xopcbot extension info telegram-channel

输出：

📦 Extension: Telegram Channel

  ID: telegram-channel
  Version: 1.2.0
  Kind: channel
  Description: Telegram channel integration
  Path: /home/user/.xopcbot/workspace/.extensions/telegram-channel

创建扩展

创建新插件脚手架。

bash

xopcbot extension create <extension-id> [options]

参数：

参数	描述
`--name <name>`	扩展显示名称
`--description <desc>`	扩展描述
`--kind <kind>`	扩展类型: `channel`, `provider`, `memory`, `tool`, `utility`

示例：

bash

# 创建工具类插件
xopcbot extension create weather-tool --name "Weather Tool" --kind tool

# 创建通道类插件
xopcbot extension create discord-channel --name "Discord Channel" --kind channel

# 创建内存类插件
xopcbot extension create redis-memory --name "Redis Memory" --kind memory

生成的文件：

.extensions/
└── my-extension/
    ├── package.json          # npm 配置
    ├── index.ts              # 扩展入口（TypeScript）
    ├── xopcbot.extension.json   # 扩展清单
    └── README.md             # 文档模板

注意：创建的扩展使用 TypeScript，通过 jiti 即时加载，无需预编译。

全局选项

工作区路径

bash

--workspace /path/to/workspace

配置文件

bash

--config /path/to/config.json

详细输出

bash

--verbose

帮助信息

bash

xopcbot --help
xopcbot agent --help
xopcbot gateway --help
xopcbot extension --help

skills

管理技能的 CLI 命令。

列出技能

bash

xopcbot skills list
xopcbot skills list -v          # 详细信息
xopcbot skills list --json      # JSON 格式

安装技能依赖

bash

xopcbot skills install <skill-name>
xopcbot skills install <skill-name> -i <install-id>   # 指定安装器
xopcbot skills install <skill-name> --dry-run         # 预演

启用/禁用技能

bash

xopcbot skills enable <skill-name>
xopcbot skills disable <skill-name>

查看技能状态

bash

xopcbot skills status
xopcbot skills status <skill-name>
xopcbot skills status --json

安全审计

bash

xopcbot skills audit
xopcbot skills audit <skill-name>
xopcbot skills audit <skill-name> --deep    # 详细输出

配置技能

bash

xopcbot skills config <skill-name> --show
xopcbot skills config <skill-name> --api-key=KEY
xopcbot skills config <skill-name> --env KEY=value

测试技能

bash

# 测试所有技能
xopcbot skills test

# 测试特定技能
xopcbot skills test <skill-name>

# 详细输出
xopcbot skills test --verbose

# JSON 格式
xopcbot skills test --format json

# 跳过特定测试
xopcbot skills test --skip-security
xopcbot skills test --skip-examples

# 验证 SKILL.md 文件
xopcbot skills test validate ./skills/weather/SKILL.md

# 检查依赖
xopcbot skills test check-deps

# 安全审计
xopcbot skills test security --deep

测试输出格式：

格式	说明
`text`	人类可读的文本输出（默认）
`json`	JSON 格式，用于机器读取
`tap`	TAP 格式，用于 CI/CD 集成

测试类型：

测试	说明
SKILL.md 格式	验证 YAML frontmatter 和必需字段
依赖检查	检查声明的二进制文件是否可用
安全扫描	扫描危险代码模式
元数据完整性	检查 emoji、homepage 等可选字段
示例验证	验证代码块语法

快捷脚本

创建快捷脚本 bot：

bash

#!/bin/bash

case "$1" in
  chat)
    xopcbot agent -m "${*:2}"
    ;;
  shell)
    xopcbot agent -i
    ;;
  start)
    xopcbot gateway --port 18790
    ;;
  cron)
    shift
    xopcbot cron "$@"
    ;;
  extension)
    shift
    xopcbot extension "$@"
    ;;
  skills)
    shift
    xopcbot skills "$@"
    ;;
  *)
    echo "Usage: bot {chat|shell|start|cron|extension|skills}"
    ;;
esac

使用：

bash

bot chat Hello!
bot start
bot cron list
bot extension list
bot extension install xopcbot-extension-telegram
bot skills list
bot skills test weather

退出码

退出码	描述
`0`	成功
`1`	通用错误
`2`	参数错误
`3`	配置错误

CLI 命令参考 ​

使用方式 ​

从 npm 安装（推荐） ​

从源码运行（开发） ​

命令列表 ​

setup ​

onboard ​

agent ​

单次对话 ​

交互模式 ​

指定会话 ​

gateway ​

前台模式（默认） ​

强制启动 ​

子命令 ​

进程管理 ​

添加任务 ​

删除任务 ​

启用/禁用 ​

触发任务 ​

extension ​

列出扩展 ​

安装扩展 ​

移除扩展 ​

查看扩展详情 ​

创建扩展 ​

全局选项 ​

工作区路径 ​

配置文件 ​

详细输出 ​

帮助信息 ​

skills ​

列出技能 ​

安装技能依赖 ​

启用/禁用技能 ​

查看技能状态 ​

安全审计 ​

配置技能 ​

测试技能 ​

快捷脚本 ​

退出码 ​

CLI 命令参考

使用方式

从 npm 安装（推荐）

从源码运行（开发）

命令列表

setup

onboard

agent

单次对话

交互模式

指定会话

gateway

前台模式（默认）

强制启动

子命令

进程管理

添加任务

删除任务

启用/禁用

触发任务

extension

列出扩展

安装扩展

移除扩展

查看扩展详情

创建扩展

全局选项

工作区路径

配置文件

详细输出

帮助信息

skills

列出技能

安装技能依赖

启用/禁用技能

查看技能状态

安全审计

配置技能

测试技能

快捷脚本

退出码