> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Octop CLI：渠道、定时任务、插件与管理命令

CLI 与 Web 控制台一样，涵盖渠道设置、定时任务、插件管理和管理任务。您可以用这些命令接入 IM 平台、自动化循环提示、通过插件扩展 Octop，以及从终端管理用户。

## `octop channel`

为专家创建和管理 IM 渠道连接。大多数子命令可离线运行；`test` 会启动嵌入式服务器，不要求另开 `octop run`。


```bash 列出专家的渠道
octop channel list --agent main
```
```bash 查看单条渠道记录
octop channel get --agent main <id>
```
```bash 交互式创建渠道
octop channel create --agent main --kind telegram
```
```bash 更新渠道配置
octop channel patch --agent main <id>
```
```bash 删除渠道
octop channel delete --agent main <id>
```
```bash 测试渠道（实例化 → 启动 → 停止）
octop channel test --agent main <id>
```
```bash 离线编辑渠道配置
octop channel config --agent main <id>
```
```bash 飞书机器人设置向导
octop channel feishu-setup
```
```bash QQ、企业微信或微信的扫码绑定
octop channel bind qq --agent main
octop channel bind wecom --agent main
octop channel bind weixin --agent main
```


### 子命令

| 子命令            | 描述                                                        |
| -------------- | --------------------------------------------------------- |
| `list`         | 列出专家配置的所有渠道                                               |
| `get`          | 显示单条渠道的完整配置记录                                             |
| `create`       | 创建新渠道（交互式）                                                |
| `patch`        | 更新已有渠道的配置                                                 |
| `delete`       | 删除渠道                                                      |
| `test`         | 实例化渠道、启动并停止（需要运行中的服务器）                                    |
| `config`       | 离线编辑渠道配置                                                  |
| `feishu-setup` | 逐步完成飞书机器人创建流程                                             |
| `bind`         | QQ、企业微信与微信的扫码绑定（`bind qq` / `bind wecom` / `bind weixin`） |

***

## `octop cron`

安排自动触发专家提示的循环任务。`run-now` 需要运行中的服务器；其他子命令可离线运行。


```bash 列出专家的定时任务
octop cron list --agent main
```
```bash 创建定时任务
octop cron create --agent main --trigger '0 9 * * *' --prompt 'Morning briefing'
```
```bash 删除定时任务
octop cron delete --agent main <job_id>
```
```bash 立即触发任务
octop cron run-now --agent main <job_id>
```


### 触发格式

向 `--trigger` 传递以下任一值：

| 格式       | 示例                         | 描述                   |
| -------- | -------------------------- | -------------------- |
| Cron 表达式 | `0 9 * * *`                | 标准五段 cron（分 时 日 月 周） |
| 间隔       | `interval:3600`            | 每 N 秒触发一次            |
| 单次日期     | `date:2025-12-31T09:00:00` | 触发一次后自动停用（任务仍留在列表）   |

### 任务类型标志

| `--task-type` 值 | 行为             |
| --------------- | -------------- |
| `agent`（默认）     | 模型处理提示并推送回复    |
| `text`          | 原样推送提示文本，不经过模型 |


> **说明**
> 
> `--prompt` 为必填项。CLI **没有** `--name`。`octop cron run-now` 会启动嵌入式服务器立即跑一次任务，不要求另开 `octop run`；但新建的 cron 要进正在跑的调度器，仍需重启 `octop run`。
> 


***

## `octop plugin`

安装和管理第三方插件。插件放入 `~/.octop/plugins/`，与 Web 控制台使用同一套插件系统。


```bash 列出已安装插件
octop plugin list
```
```bash 从本地路径安装
octop plugin install ./my-plugin
```
```bash 从 Git 仓库安装
octop plugin install https://github.com/user/plugin.git
```
```bash 卸载插件
octop plugin uninstall <name>
```
```bash 不重启服务器重载所有插件
octop plugin reload
```


### 子命令

| 子命令         | 描述                       |
| ----------- | ------------------------ |
| `list`      | 列出所有已安装插件                |
| `install`   | 从本地路径、ZIP 或 Git URL 安装插件 |
| `uninstall` | 删除已安装插件                  |
| `reload`    | 不重启服务器重载所有插件             |

页面**插件**管理也可从本地 ZIP 安装，并可覆盖同名插件。随包分发的内置插件**默认关闭**；卸载后升级不会重建。按智能体的插件开关在**个性化**（`GET`/`PUT` `/api/agents/{id}/tool-settings`）。


> **提示**
> 
> 安装或更新插件后，使用 `octop plugin reload` 即可在运行中的服务器上生效，无需完整重启。
> 


***

## `octop user`

管理本地数据库中的用户。全部子命令离线运行。CLI **没有** `octop user login`：用 `octop config set-user` 固定默认 `--user`，或在子命令上传递 `--user`。


```bash 列出所有用户
octop user list
```
```bash 创建用户
octop user create bob --password secret123
```
```bash 设置或清除邮箱
octop user set-email bob bob@example.com
octop user set-email bob --clear
```
```bash 设置用户角色
octop user role bob admin
```
```bash 重置用户密码
octop user passwd <用户名> --password <密码>
```
```bash 禁用用户
octop user disable bob
```
```bash 删除用户
octop user delete bob --yes
```


***

## `octop admin`

查看系统状态、审计日志，管理全局提供商，并直接对本地数据库执行管理操作。


```bash 显示管理概览（用户数、专家状态）
octop admin overview
```
```bash 显示审计日志条目
octop admin audit
```
```bash 显示全局（管理员）提供商
octop admin providers
```
```bash 轮换 JWT 密钥
octop admin rotate-jwt-secret
```


### 子命令

| 子命令                 | 描述                 |
| ------------------- | ------------------ |
| `overview`          | 显示管理概览（用户数、专家状态分布） |
| `audit`             | 显示审计日志条目           |
| `providers`         | 列出并管理全局（管理员）提供商    |
| `rotate-jwt-secret` | 直接通过本地数据库轮换 JWT 密钥 |


> **注意**
> 
> `octop admin rotate-jwt-secret` 会向 SQLite 数据库写入新的 JWT 密钥。这会**立即使所有活跃会话失效**——包括控制台会话和 CLI 令牌在内的所有已登录用户都会被登出。请有意使用此命令，而非例行操作。
> 


***

## `octop backup`

导出并恢复完整 Octop 状态（数据库、工作区与配置）。所有子命令均可完全离线运行。


```bash 创建备份归档
octop backup create
```
```bash 从备份归档恢复
octop backup restore <archive>
```
```bash 查看自动备份设置
octop backup auto status
```
```bash 立即执行一次自动备份
octop backup auto run
```



> **说明**
> 
> 自动备份在 **`octop run` 进程内**调度。通过 `config.json` 的 `backup`、环境变量或**应用设置 → 备份与恢复**配置。自动归档名为 `octop-auto-backup-*.tar.gz`；保留策略不会删除手动的 `octop-backup-*`。页面中已有备份或恢复操作运行时，会拒绝并发操作。详见[备份与恢复](/guide/guides/backup-restore.md)。
> 

