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

# Octop CLI 概览：所有命令与传输模式

`octop` CLI 是与服务器二进制文件一同安装的单条命令。大多数命令可在**离线**模式下运行——直接读写 `~/.octop/`——因此您无需启动服务器即可管理专家、用户、渠道和定时任务。少数命令（例如 `chats repl`、`channel test`）会自动启动嵌入式服务器，或要求已有 `octop run`。

## 全局选项

在任意子命令前传递以下标志，以控制输出格式和默认目标：

| 选项              | 环境变量          | 作用                          |
| --------------- | ------------- | --------------------------- |
| `--user TEXT`   | `OCTOP_USER`  | 管理类子命令的默认 `--user`（代其他用户操作） |
| `--agent TEXT`  | `OCTOP_AGENT` | 子命令的默认 `--agent`            |
| `--json`        | —             | 为列表类命令输出机器可读的 JSON          |
| `-v, --version` | —             | 打印已安装版本并退出                  |

## 传输模式

每条 `octop` 命令会根据操作需求自动选择以下三种传输方式之一：


**离线（Offline）**

直接读写 `~/.octop/`，无需运行中的服务器。用于 `init`、`backup`、`plugin`、`agent list`、`user *`、`admin overview/audit`、`captcha reset` 以及大多数 CRUD 命令。

**附加（Attach）**

通过 HTTP 连接到正在运行的 `octop run` 进程。用于 `channel test`、`models ollama-*`、`provider test` 等。CLI **不需要**先 `login`：本机文件系统访问即足够，用 `octop config set-user` 固定操作用户。

**嵌入式（Embedded）**

为单条命令启动进程内临时服务器，执行完毕后退出。无需单独运行 `octop run`。用于 `octop acp`、`octop chats repl`、`octop chats send` 以及 `octop agent create/from-expert/start/stop/reload`。

## 命令分类


[**服务器命令**](/cli/server-commands.md)

`init`、`run`、`service`、`update`、`captcha`、`user`、`clean`、`config`、`completion`、`version`

[**专家命令**](/cli/agent-commands.md)

`agent`、`chats`、`skills`、`models`、`provider`、`acp`

[**渠道与定时任务**](/cli/channel-cron-commands.md)

`channel`、`cron`、`plugin`、`user`、`admin`、`backup`

## 命令参考


> **提示**
> 
> 在任意列表命令后加上 `--json`，即可获得机器可读的 JSON 输出——适合脚本和 CI 流水线。
> 


| 命令                 | 描述                                                |
| ------------------ | ------------------------------------------------- |
| `octop init`       | 引导 `~/.octop/`（数据库、管理员账户、JWT 密钥）                  |
| `octop run`        | 在前台启动服务器                                          |
| `octop service`    | 管理系统服务（Linux 上为 systemd，macOS 上为 launchd）         |
| `octop agent`      | 创建、列出、启动、停止和重载专家                                  |
| `octop chats`      | 聊天 REPL 与会话管理                                     |
| `octop channel`    | IM 渠道配置与管理                                        |
| `octop bridge`     | 连接另一台 Octop（云端协同）                                 |
| `octop cron`       | 定时任务管理                                            |
| `octop provider`   | 模型提供商管理                                           |
| `octop models`     | 模型目录与活动模型设置                                       |
| `octop skills`     | 启用或禁用按专家划分的技能                                     |
| `octop acp`        | 将专家暴露为 ACP 服务器（IDE 集成）                            |
| `octop backup`     | 导出与恢复备份                                           |
| `octop migrate`    | 把 OpenClaw 或 Hermes Agent 的配置迁进一位专家               |
| `octop cloud`      | 把本机 `tccli` 登录导入云服务器页                             |
| `octop user`       | 用户管理                                              |
| `octop admin`      | 管理操作（审计日志、JWT 轮换）                                 |
| `octop captcha`    | 登录验证码维护（`reset` 可解除误配提供方导致的锁定）                    |
| `octop plugin`     | 安装与管理插件                                           |
| `octop update`     | 检查并安装更新                                           |
| `octop clean`      | 重置 CLI 状态，或删除 `~/.octop` 下的数据并保留 `venv/` 与 `bin/` |
| `octop config`     | 查看与编辑 CLI 状态（固定的默认用户 / 专家）                        |
| `octop completion` | Shell 补全工具                                        |
| `octop version`    | 打印已安装的 octop 版本                                   |

## CLI 状态文件

文件 `~/.octop/cli_state.json` 存储您的 CLI 会话状态：

```json
{
  "default_user": null,
  "default_agent": null
}
```

| 字段              | 描述                                            |
| --------------- | --------------------------------------------- |
| `default_user`  | 固定的 `--user` 值（通过 `octop config set-user` 设置） |
| `default_agent` | 固定的 `--agent` 值（通过 `octop agent use` 设置）      |

删除此文件即可清除 CLI 固定项。Web 控制台和 HTTP API 客户端各自管理令牌，不会共享此文件。


> **说明**
> 
> 在运行任意 `octop` 命令前设置 `OCTOP_HOME` 环境变量，可覆盖 `~/.octop/` 的位置。
> 

