> 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 控制台。

## `octop agent`

创建、查看和控制专家生命周期。大多数子命令无需 `octop run` 正在运行。


```bash 创建基础专家
octop agent create myagent
```
```bash 创建带 MBTI 人格的专家
octop agent create analyst --persona-mbti INTJ
```
```bash 从内置专家模板创建
octop agent from-expert <expert_id>
```
```bash 列出所有专家
octop agent list
```
```bash 启动、停止、重载或删除专家
octop agent start <agent_id>
octop agent stop <agent_id>
octop agent reload <agent_id>
octop agent delete <agent_id>
```
```bash 列出内置专家模板
octop agent experts
```


### 子命令

| 子命令           | 描述                                             |
| ------------- | ---------------------------------------------- |
| `create`      | 创建新专家（管理员可用 `--user` 代其他用户创建）                  |
| `from-expert` | 从内置专家模板创建专家                                    |
| `list`        | 列出当前用户的所有专家                                    |
| `use <id>`    | 将此专家固定为后续命令的默认值                                |
| `start`       | 启动专家运行时                                        |
| `stop`        | 停止专家运行时                                        |
| `reload`      | 重载专家运行时（不删除会话历史）                               |
| `delete`      | 删除专家记录、运行时及其 `~/.octop/agents/<id>/` 工作区（不可恢复） |
| `experts`     | 列出本安装上所有可用的内置专家模板                              |

运行 `octop agent use <id>` 会将专家 ID 写入 `~/.octop/cli_state.json`。之后接受 `--agent` 的命令都会默认使用该值，无需重复指定。


> **注意**
> 
> `octop agent delete` 会永久删除专家工作区目录。除非传入 `--yes`，CLI 会要求确认。此操作不可恢复——如需保留文件请先备份。
> 


***

## `octop chats`

管理会话线程并发送消息。`repl` 和 `send` 子命令会自动启动临时服务器进程——无需单独运行 `octop run`。


```bash 启动交互式聊天 REPL
octop chats repl
```
```bash 发送单条消息并流式输出回复
octop chats send --agent main 'Hello'
```
```bash 列出专家的会话线程
octop chats list --agent main
```
```bash 查看线程的消息历史
octop chats get --agent main <thread_id>
```
```bash 创建新线程
octop chats create --agent main
```
```bash 重命名或置顶线程
octop chats update --agent main <thread_id>
```
```bash 删除线程
octop chats delete --agent main <thread_id>
```


### 子命令

| 子命令      | 需要服务器   | 描述            |
| -------- | ------- | ------------- |
| `list`   | 否       | 列出专家的会话线程     |
| `get`    | 否       | 显示线程的消息历史     |
| `create` | 否       | 创建新线程         |
| `update` | 否       | 重命名或置顶线程      |
| `delete` | 否       | 删除线程          |
| `send`   | 自动（嵌入式） | 发送一条消息并流式输出回复 |
| `repl`   | 自动（嵌入式） | 交互式聊天 REPL    |


> **说明**
> 
> `octop chats repl` 和 `octop chats send` 会在命令执行期间启动进程内临时服务器。您无需先运行 `octop run`。`list`、`get`、`create`、`update` 和 `delete` 子命令可完全离线操作 `~/.octop/octop.db`。
> 


***

## `octop skills`

启用或禁用按专家划分的技能。读写本地技能库，**不需要**正在运行的服务器。


```bash 列出专家的技能
octop skills list --agent main
```
```bash 启用技能
octop skills enable weather --agent main
```
```bash 禁用技能
octop skills disable weather --agent main
```
```bash 交互开关按专家划分的技能
octop skills config --agent main
```


### 子命令

| 子命令       | 描述              |
| --------- | --------------- |
| `list`    | 列出专家的技能         |
| `enable`  | 为专家启用技能         |
| `disable` | 为专家禁用技能         |
| `config`  | 查看或编辑按专家划分的技能配置 |


> **说明**
> 
> `octop skills` 离线读写该专家工作区里的技能开关。改完后若 `octop run` 已在跑，用 `octop agent reload <agent_id>` 让运行中的专家加载新配置。
> 


***

## `octop models`

管理模型目录、交互式配置提供商，以及拉取 Ollama 模型。


```bash 交互式配置向导
octop models config
```
```bash 列出所有已启用提供商的解析模型
octop models list
```
```bash 查看或设置全局默认模型
octop models active
```
```bash 列出内置提供商预设模板
octop models presets
```
```bash 列出本地可用的 Ollama 模型
octop models ollama-list
```
```bash 通过 Ollama 拉取模型
octop models ollama-pull llama3.2
```
```bash 删除本地 Ollama 模型
octop models ollama-rm llama3.2
```


### 子命令

| 子命令           | 需要服务器 | 描述                 |
| ------------- | ----- | ------------------ |
| `config`      | 否     | 交互式向导：创建提供商并设置活动模型 |
| `list`        | 否     | 列出所有已启用提供商的解析模型    |
| `active`      | 否     | 查看或设置全局默认模型（管理员）   |
| `presets`     | 否     | 列出内置提供商模板          |
| `ollama-list` | 是     | 列出本地 Ollama 实例中的模型 |
| `ollama-pull` | 是     | 通过 Ollama 拉取模型     |
| `ollama-rm`   | 是     | 删除本地 Ollama 模型     |

***

## `octop provider`

管理本地数据库中的模型提供商记录。`test` 子命令需要运行中的服务器以发起实时 API 调用。


```bash 列出提供商
octop provider list
```
```bash 交互式创建提供商
octop provider create
```
```bash 测试与提供商的连通性
octop provider test
```
```bash 删除提供商
octop provider delete
```



> **说明**
> 
> `octop provider list`、`create` 和 `delete` 离线操作 `~/.octop/octop.db`。仅 `octop provider test` 需要运行中的服务器，因为它会向提供商 API 发送实时 ping。
> 


***

## `octop acp`

将 Octop 专家暴露为 stdio JSON-RPC ACP 服务器。启动独立的 `OctopServer`（读取 `~/.octop/`）；**无需** `octop run` 正在运行。


```bash 暴露默认专家
octop acp
```
```bash 指定专家并启用调试日志
octop acp --agent myagent --debug
```


### 选项

| 选项             | 描述                              |
| -------------- | ------------------------------- |
| `--agent TEXT` | 要暴露的专家（默认：`OCTOP_AGENT` 或第一个专家） |
| `--debug`      | 将日志输出到 stderr                   |

### 让 IDE 指向它

在 IDE 中把 `octop acp` 命令配置为 ACP 服务端。Zed 示例：


```json ~/.config/zed/settings.json
{
  "agent_servers": {
    "Octop": {
      "command": "octop",
      "args": ["acp", "--agent", "main"],
      "env": {}
    }
  }
}
```
```json 开发环境（uv）
{
  "agent_servers": {
    "Octop": {
      "command": "uv",
      "args": ["run", "octop", "acp", "--agent", "main"],
      "env": {}
    }
  }
}
```



> **说明**
> 
> 这是 [ACP 协作指南](/guide/guides/acp-ide.md) 的反方向：这里是 IDE 驱动 Octop 专家，而非 Octop 专家去委托 CLI 工具。
> 

