> ## Documentation Index
> Fetch the complete documentation index at: https://octop.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

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

> octop CLI 完整参考：全局选项、传输模式，以及管理 Octop 服务器的所有顶层命令。

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

## 全局选项

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

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

## 传输模式

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

> [card] 离线（Offline）
>
> 直接读写 `~/.octop/`，无需运行中的服务器。用于 `init`、`backup`、`plugin`、`agent list`、`user *`、`admin overview/audit` 以及大多数 CRUD 命令。

> [card] 附加（Attach）
>
> 通过 HTTP 连接到正在运行的 `octop run` 进程。需先执行 `octop user login`。用于 `chats send/repl`（非嵌入式时）、`channel test`、`models ollama-*`、`skills enable/disable` 和 `provider test`。

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

## 命令分类

> [card] [服务器命令](https://octop.mintlify.site/zh/cli/server-commands.md)
>
> `init`、`run`、`service`、`update`、`user login`、`clean`、`config`、`completion`、`version`

> [card] [专家命令](https://octop.mintlify.site/zh/cli/agent-commands.md)
>
> `agent`、`chats`、`skills`、`models`、`provider`、`acp`

> [card] [渠道与定时任务](https://octop.mintlify.site/zh/cli/channel-cron-commands.md)
>
> `channel`、`cron`、`plugin`、`user`、`admin`、`backup`

## 命令参考

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

| 命令 | 描述 |
| - | - |
| `octop init` | 引导 `~/.octop/`（数据库、管理员账户、JWT 密钥） |
| `octop run` | 在前台启动服务器 |
| `octop service` | 管理系统服务（Linux 上为 systemd，macOS 上为 launchd） |
| `octop agent` | 创建、列出、启动、停止和重载专家 |
| `octop chats` | 聊天 REPL 与会话管理 |
| `octop chat` | `octop chats` 的已弃用别名——新脚本请使用 `octop chats` |
| `octop channel` | IM 渠道配置与管理 |
| `octop cron` | 定时任务管理 |
| `octop provider` | LLM 提供商管理 |
| `octop models` | 模型目录与活动模型设置 |
| `octop skills` | 启用或禁用按专家划分的技能 |
| `octop acp` | 将专家暴露为 ACP 服务器（IDE 集成） |
| `octop backup` | 导出与恢复备份 |
| `octop user` | 用户管理 |
| `octop admin` | 管理操作（审计日志、JWT 轮换） |
| `octop plugin` | 安装与管理插件 |
| `octop update` | 检查并安装更新 |
| `octop clean` | 重置 CLI 状态或清空 `~/.octop/` |
| `octop config` | 查看与编辑 CLI 状态（基础 URL、默认值） |
| `octop completion` | Shell 补全工具 |
| `octop version` | 打印已安装的 octop 版本 |

## CLI 状态文件

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

```json theme={null}
{
  "base_url": "http://127.0.0.1:8088",
  "token": null,
  "default_user": null,
  "default_agent": null
}
```

| 字段 | 描述 |
| - | - |
| `base_url` | Attach 模式命令使用的服务器 URL |
| `token` | `octop user login` 后存储的 JWT |
| `default_user` | 固定的 `--user` 值（通过 `octop config set-user` 设置） |
| `default_agent` | 固定的 `--agent` 值（通过 `octop agent use` 设置） |

删除此文件即可在不联系服务器的情况下退出 CLI 登录。Web 控制台和 HTTP API 客户端各自管理令牌，不会共享此文件。

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.