Octop 1.0.2 常用 CLI 命令详解

Octop CLI 22 个子命令详解：初始化、服务托管、专家与对话、模型接入、备份清理，覆盖全局选项与三类传输层，全部帮助文本与执行回显实测采集。

OctopOctop人工智能LLM2026/10/23

Octop 1.0.2 常用 CLI 命令详解

目标：系统梳理 Octop 1.0.2 的 octop 命令行工具——22 个子命令的职责、参数与真实回显，覆盖从初始化、服务托管、专家与对话、模型接入到备份清理的日常运维全流程。全部帮助文本与执行回显均在 Ubuntu 24.04 实测环境逐条采集。

一、环境信息

  • 操作系统：Ubuntu 24.04（x86_64）
  • Octop 版本：1.0.2（octop version → octop v1.0.2，实测）
  • 安装方式：官方一键脚本（CLI 位于 /usr/local/bin/octop → ~/.octop/bin/octop 包装器 → ~/.octop/venv/bin/octop）
  • 服务状态：octop run 前台进程 + systemd 服务（octop.service）两种形态均已实测
  • 已配置资源：管理员 admin、专家 main（id 71EJNY）、Provider ollama-openai（Ollama 0.40.8 OpenAI 兼容端点，模型 qwen2.5:0.5b），均按《Ubuntu 24.04 安装 Octop 1.0.2 指南》第九章实测建立

二、工具概览

2.1 命令总览

octop 是基于 Click 的单命令应用（官方 docs/cli.md 口径），子命令按需懒加载。octop --help 实测全文：

Usage: octop [OPTIONS] COMMAND [ARGS]...

  Octop command-line interface.

Options:
  -v, --version  Show the installed octop version.
  --user TEXT    Default --user for subcommands (admin acting on behalf of a
                 user).
  --agent TEXT   Default --agent for subcommands.
  --json         Emit machine-readable JSON for list-style commands.
  -h, --help     Show this message and exit.

Commands:
  acp         Run Octop agent as ACP server (stdio).
  admin       Admin commands.
  agent       Agent lifecycle commands.
  backup      Export and restore Octop backups.
  bridge      Manage remote Octop bridge peers.
  captcha     Login captcha maintenance (lockout escape hatch).
  channel     Channel management commands.
  chats       Chat REPL and session management.
  clean       Remove CLI state or wipe all of ~/.octop.
  completion  Shell completion utilities.
  config      CLI defaults (pinned user/agent).
  cron        Cron job management commands.
  init        Bootstrap an Octop server install.
  memory      Live memory maintenance (backup and slim).
  models      Provider presets and resolved models.
  plugin      Install and manage plugins.
  provider    Provider management (admin write).
  run         Run octop-server in the foreground.
  service     System service lifecycle (start/stop/restart/status).
  skills      Per-agent skill enable/disable.
  update      Check for and install a newer Octop release.
  user        User management commands (admin only).
  version     Show the installed octop version.

💡 说明：全局选项必须写在子命令之前，如 octop --json chats list；写在后面（octop chats list --json）会报 Error: No such option '--json'（实测复现）。--user / --agent 也可用环境变量 OCTOP_USER / OCTOP_AGENT 或 octop config set-user 固化。

2.2 三类传输层（理解命令行为差异的关键）

官方 docs/cli.md 把命令按「连不连运行中的服务」分为三层（2026-10-23 取证）：

层何时用需登录？例子
Offline（只读写本地库 ~/.octop）无需服务在跑否init、backup、plugin、agent list、chats list/get/create/update/delete、cron list、user *、admin overview/audit、models presets/list/active、bridge list/get
Attach（HTTP/WS 连到运行中的 octop run）需要 IM、流式、模型拉取是（octop user login）chats send/repl、channel test/probe、models ollama-*、skills enable/disable、provider test
Embedded（命令内部临时拉起 OctopServer）单命令内嵌执行否octop acp、octop chats repl、octop chats send（默认 embedded）、octop agent create/from-expert/start/stop/reload

💡 说明：chats send 虽列在 Attach 层，但默认走 embedded 内嵌服务器——所以服务没跑也能发一条消息（会临时启动进程再退出）；仪表盘与 HTTP 调用方使用自己的 JWT，不与 CLI 的 ~/.octop/cli_state.json 共享登录态。

三、前置条件

  1. 已安装 Octop 1.0.2 并完成 octop init（安装与初始化见《Ubuntu 24.04 安装 Octop 1.0.2 指南》）；
  2. root（或安装用户）身份执行，保证能读写 ~/.octop/；
  3. Attach 类命令（通道测试、模型拉取、远程登录）需要 octop run 或 systemd 服务在跑；
  4. 本文多数示例依赖已存在的资源：管理员 admin、专家 71EJNY、Provider ollama-openai。

四、各工具详解

4.1 生命周期：init / run / version

octop init——初始化数据目录、建库迁移、创建首个管理员（离线层，幂等）。关键参数：--admin-username / --admin-password / --admin-display-name（均有同名 OCTOP_ADMIN_* 环境变量）、--yes 跳过交互、--force 先清空 ~/.octop 再初始化。实测（无人值守）：

octop init --admin-username admin --admin-password q1w2e3r4 --admin-display-name admin --yes

✅ Octop bootstrapped at /root/.octop
   admin user: admin
   next: `octop run` (optional: `octop agent use <id>` to pin default agent)

octop run——前台启动服务（FastAPI/uvicorn）。octop run --help 实测：

Usage: octop run [OPTIONS]

  Run octop-server in the foreground.

  Host and port are resolved with the following precedence: explicit CLI flags
  > ``OCTOP_BIND_HOST``/``OCTOP_PORT`` env > ``~/.octop/config.json`` > launch
  defaults. When ``--host`` or ``--port`` is passed on the CLI, that override
  is persisted to ``config.json`` immediately before uvicorn starts.

Options:
  --host TEXT                     Override bind host
  --port INTEGER RANGE            Override port  [0<=x<=65535]
  --reload                        Enable uvicorn auto-reload (dev).
  --workers INTEGER               Worker process count (default 1).
  --log-level [critical|error|warning|info|debug|trace]
  --ssl                           Enable HTTPS (auto-generates self-signed if
                                  no cert/key given).
  --ssl-certfile TEXT             TLS certificate file.
  --ssl-keyfile TEXT              TLS private key file.
  -h, --help                      Show this message and exit.

octop version / octop -v——打印版本（实测输出 octop v1.0.2）。

4.2 服务托管：service

Usage: octop service [OPTIONS] COMMAND [ARGS]...

  Manage the Octop system service (systemd on Linux, launchd on macOS).

Options:
  -h, --help  Show this message and exit.

Commands:
  restart  Restart the system service.
  start    Install if needed, ensure the NOFILE drop-in, then start the...
  status   Show system service and HTTP health status.
  stop     Stop the system service.

octop service start 实测（注册 /etc/systemd/system/octop.service 并拉起）：

scope: system, unit: /etc/systemd/system/octop.service
service: systemd active=True
health: OK {'ok': True, 'started_at': 1792707714, 'db': True, 'users_loaded': 1, 'agents_running': 0}

systemctl is-active octop → active；octop service stop / restart / status 同理对 systemctl 做封装。资源限制 drop-in 与开机自启说明见《Octop 1.0.2 配置参数详解》第六章。

4.3 专家生命周期：agent

Usage: octop agent [OPTIONS] COMMAND [ARGS]...

  Agent lifecycle commands.

Options:
  -h, --help  Show this message and exit.

Commands:
  create       Create a new agent (boots embedded server).
  delete
  experts      List bundled expert (scene) templates.
  from-expert  Create an agent from a bundled expert template (embedded...
  list         List agents from local DB.
  reload
  start
  stop
  use          Pin default agent in CLI state (~/.octop/cli_state.json).

要点（全部实测验证）：

  • create 语法 octop agent create <名称>，常用 --user <用户>（管理员指定归属）与 --default-model "<provider>/<model>"。实测：

    octop agent create main --user admin --default-model "ollama-openai/qwen2.5:0.5b"

    {
  "agent_id": "71EJNY",
  "name": "main"
}

    不带 --user 会报 error: user required (--user, CLI default_user, or agent with an owner)——先 octop config set-user admin 固化默认用户即可免带。

  • list 实测：

                                  Agents
┏━━━━━━━━┳━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━┓
┃ id     ┃ name ┃ template ┃ model                      ┃ state   ┃
┡━━━━━━━━╇━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━┩
│ 71EJNY │ main │          │ ollama-openai/qwen2.5:0.5b │ running │
└━━━━━━━━┴━━━━━━┴━━━━━━━━━━┴━━━━━━━━━━━━━━━━━━━━━━━━━━━━┴━━━━━━━━━┘

  • experts 列出内置专家模板（实测节选，含中文标签与描述）：

                                    Expert templates
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ id                         ┃ label (zh)         ┃ description (zh)           ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ general-assistant          │ 小通 · 通用助手    │ 友好的通用助手，无特定技 … │
│ ai-coding-coach            │ AI 编程实战导师    │ 源自 ai-coding-guide 的 6… │
│ ai-safety-guardian         │ AI 安全合规卫士    │ 基于 shellward 8           │
│ business-operations        │ 业务流程专家       │ 基于 Anthropic Knowledge   │
└────────────────────────────┴────────────────────┴────────────────────────────┘

  • use <agent_id> 把默认专家写进 ~/.octop/cli_state.json，此后子命令免带 --agent；

  • start / stop / reload / delete 针对单个专家运行时；from-expert 从模板建专家。

4.4 会话与对话：chats

Usage: octop chats [OPTIONS] COMMAND [ARGS]...

  Thread list/history and interactive chat (CLI channel / local DB).

Options:
  -h, --help  Show this message and exit.

Commands:
  create      Start a new thread (/new equivalent).
  delete      Delete a thread.
  gc-orphans  Report checkpoint rows whose thread was already removed.
  get         Show message history for a thread.
  list        List conversation threads for an agent.
  repl        Interactive chat REPL (embedded server + CLI gateway channel).
  send        Send one message and stream the response (CLI channel).
  update      Rename or pin a thread.

octop chats send——发一条消息并流式返回，--mode 可选 ask（只读）/plan（写 plans/*.md）/craft（默认动手模式）。实测：

octop chats send "用一句话回答：你是谁？" --agent 71EJNY

  ● 我是阿里云自研的超大规模语言模型。
  ──────────────────────────────────────────────────
  7.9s

octop chats list——线程列表（实测）：

                                    Threads
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━┳━━━━━━━━━━━━━┓
┃ thread_id                 ┃ title                  ┃ is_active ┃ last_active ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━╇━━━━━━━━━━━━━┩
│ thr_01M5JV0T1FA7KKFJ6DX0… │ 用一句话回答：你是谁？ │           │ 1792707429  │
└───────────────────────────┴────────────────────────┴───────────┴─────────────┘

配合全局 --json 拿机器可读全量 id（实测）：

octop --json chats list --agent 71EJNY

[
  {
    "thread_id": "thr_01M5JV0T1FA7KKFJ6DX0FDWZD8",
    "title": "\u7528\u4e00\u53e5\u8bdd\u56de\u7b54\uff1a\u4f60\u662f\u8c01\uff1f",
    "channel_type": "cli",
    "session_key": "71EJNY:cli:1:dm",
    "last_active": 1792707429,
    "created_at": 1792707422,
    "is_active": false,
    "has_messages": null,
    "pinned": false
  }
]

octop chats get——看线程消息历史（需 --agent，实测节选）：

octop chats get thr_01M5JV0T1FA7KKFJ6DX0FDWZD8 --agent 71EJNY

[
  "content='用一句话回答：你是谁？' additional_kwargs={'checkpoint_ts': 1792707422332, '_octop_memory_recall': {'version': 1, 'content_hash': '05689a4702c3263173cd222dda7395bb8996d802209cb0169ef69264674cbd1b', ...}} ...",
  "content='我是阿里云自研的超大规模语言模型。' additional_kwargs={'context_usage': {'max_tokens': 128000, 'used_tokens': 13734, 'input_tokens': 13734, 'output_tokens': 0, ... 'segments': {'system_prompt': 862, 'tool_definitions': 12053, 'subagent_definitions': 809, 'conversation': 10}, ...}, 'checkpoint_ts': 1792707429495} response_metadata={'finish_reason': 'stop', 'model_name': 'qwen2.5:0.5b', 'system_fingerprint': 'fp_ollama', 'model_provider': 'openai'} ...",
]

💡 说明：回显里能看到 Octop 的记忆召回（_octop_memory_recall）、上下文用量（本轮 13734 tokens，其中工具定义占 12053）与模型信息（model_provider: openai 即我们配置的 OpenAI 兼容 Provider）——排查「为什么答非所问/贵不贵」先看这里。

  • create / update / delete：建线程、重命名/置顶、删线程（离线层，直接动本地库）；gc-orphans 实测输出 no orphan checkpoints（清孤儿检查点的巡检命令）。

4.5 模型与 Provider：models / provider

octop models——

Commands:
  active       Show or set the global default model (admin).
  config       Interactively create a provider from presets and set the...
  list         List all resolved models across enabled providers.
  ollama-list  List models available in the local Ollama daemon.
  ollama-pull  Pull an Ollama model from the local daemon.
  ollama-rm    Delete a model from the local Ollama daemon.
  presets      List built-in provider templates from octop-harness.

  • octop models presets 列出全部内置 Provider 模板（实测节选，共 40+ 条）：OpenAI (ChatGPT) (openai-codex)、DeepSeek (deepseek)、Ollama (Local) (ollama)、ONNX (Local) (onnx)、DashScope (China) (dashscope)、Zhipu (BigModel) (zhipu-cn)、Kimi (China) (kimi-cn)、Volcano Engine (volcengine-cn)、SiliconFlow (China) (siliconflow-cn)、Anthropic (anthropic)、Google Gemini (gemini)、Groq (groq)、OpenRouter (openrouter) 等——config 子命令按预设交互式建 Provider 就是基于这份目录。

  • octop models list 实测（已解析的全局可用模型）：

                  Resolved models
┏━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━━━━━┓
┃ provider      ┃ model        ┃ reasoning ┃
┡━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━━━━┩
│ ollama-local  │ qwen2.5:0.5b │ False     │
│ ollama-openai │ qwen2.5:0.5b │ False     │
└───────────────┴──────────────┴───────────┘

  • octop models active 查/设全局默认模型（实测输出 ollama-openai / qwen2.5:0.5b；带 --provider / --model 参数即设置）。

  • models ollama-list / ollama-pull / ollama-rm 面向「本机 Ollama 守护进程」场景；外部 Ollama 服务器场景用 4.5.2 的 OpenAI 兼容 Provider。⚠️ 实测这三个命令要求 Python ollama 包：Error: The 'ollama' Python package is not installed. Please install it manually: pip install ollama——按提示把包装进 Octop 的 venv（~/.octop/venv/bin/pip install ollama）即可。

octop provider（管理员写操作，本地库）——

Commands:
  create  Create a provider.
  delete  Delete a provider.
  list    List providers.
  test    Probe a provider with a one-token ping.

create 参数：--name（必填）、--kind（必填，如 openai / ollama）、--base-url、--api-key、--models（JSON 数组）。实测外部 Ollama 的推荐姿势（kind=openai + /v1）：

octop provider create --name ollama-openai --kind openai --base-url http://10.89.66.2:11434/v1 --api-key ollama --models "[{\"id\":\"qwen2.5:0.5b\"}]"

{
  "id": 2,
  "name": "ollama-openai",
  "kind": "openai",
  "base_url": "http://10.89.66.2:11434/v1",
  "api_key": "ollama",
  "models": [
    {
      "id": "qwen2.5:0.5b"
    }
  ],
  "note": null,
  "enabled": true
}

连通性探测（实测 ok (1298 ms)）：

octop provider test 2 --model qwen2.5:0.5b

list 实测：

               Providers
┏━━━━┳━━━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━┓
┃ id ┃ name         ┃ kind   ┃ enabled ┃
┡━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━┳━━━━━━━━━┩
│ 1  │ ollama-local │ ollama │ True    │
│ 2  │ ollama-openai│ openai │ True    │
└────┴──────────────┴────────┴─────────┘

4.6 用户与管理员：user / admin

octop user（管理员，本地库，无需服务在跑）——create / list / passwd / role / disable / delete / set-email。实测：

octop user list

                   Users
┏━━━━┳━━━━━━━━━━┳━━━━━━━┳━━━━━━━┳━━━━━━━━━━┓
┃ id ┃ username ┃ email ┃ role  ┃ disabled ┃
┡━━━━╇━━━━━━━━━━╇━━━━━━━╇━━━━━━━╇━━━━━━━━━━┩
│ 1  │ admin    │ -     │ admin │ False    │
└────┴──────────┴───────┴───────┴──────────┘

典型用法：octop user create <用户名>（按提示设密码，密码策略 ≥8 位字母+数字）、octop user passwd <用户名> 重置密码、octop user role <用户名> admin|user 调角色、octop user disable <用户名> 停用而不删数据。

octop admin——overview / audit / providers / rotate-jwt-secret。overview 实测：

{
  "users": [
    {
      "username": "admin",
      "role": "admin",
      "agents": []
    }
  ],
  "agents": [
    {
      "id": 1,
      "agent_id": "71EJNY",
      "name": "main",
      "state": "running"
    }
  ],
  "totals": {
    "users": 1,
    "agents": 1
  }
}

audit 实测（登录与建专家的审计流水）：

                      Audit Log
┏━━━━┳━━━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━━┓
┃ id ┃ ts         ┃ actor   ┃ action       ┃ target ┃
┡━━━━╇━━━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━┩
│ 2  │ 1792707437 │ admin   │ auth.login   │        │
│ 1  │ 1792707408 │ _system │ agent.create │ 71EJNY │
└────┴────────────┴─────────┴──────────────┴────────┘

rotate-jwt-secret 轮换 JWT 密钥（所有在线令牌立即失效）；providers 管理全局级 Provider。

4.7 IM 通道：channel

Commands:
  bind          QR-based channel binding (QQ / WeCom / WeChat).
  config        Interactively create or configure a channel.
  create        Create a channel.
  delete        Delete a channel.
  feishu-setup  Run Feishu scan-to-create (lark-oapi QR) and save app...
  get           Show channel details including config (secrets masked).
  list          List channels for an agent.
  patch         Update channel fields.
  test          Probe a channel: instantiate, start(), then stop().

交互式 octop channel config 按向导建通道；扫码类通道（QQ / 企微 / 微信）走 bind；飞书可用 feishu-setup 扫码自动创建应用；test 会实例化通道、start 再 stop 做连通性探测（Attach 层，需服务在跑）。get 回显中密钥自动打码。

4.8 技能与插件：skills / plugin

octop skills——list / config / enable / disable（按专家维度）。实测 octop skills list --agent 71EJNY（节选，内置技能默认全开）：

              Skills (71EJNY)
┏━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━┓
┃ name                 ┃ enabled ┃ source  ┃
┡━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━┩
│ apple-notes          │ True    │ builtin │
│ apple-reminders      │ True    │ builtin │
│ architecture-diagram │ True    │ builtin │
│ ascii-art            │ True    │ builtin │
│ docker-management    │ True    │ builtin │
│ fastmcp              │ True    │ builtin │
│ jupyter-live-kernel  │ True    │ builtin │
│ manim-video          │ True    │ builtin │
└──────────────────────┴─────────┴─────────┘

开关用 octop skills enable|disable <技能名> --agent <agent_id>；交互式批量勾选用 octop skills config。

octop plugin——install（本地目录或 ZIP URL）/ list / reload / uninstall。实测 octop plugin list → No plugins installed.（全新环境无第三方插件，内置插件在仪表盘 Admin → Plugins 中按需启用）。

4.9 定时任务：cron

Commands:
  create   Create a cron job.
  delete   Delete a cron job.
  list     List cron jobs for an agent.
  run-now  Run a cron job to completion (embedded server).

octop cron list --agent <id> 实测（空表为正常初始态）：

              Cron jobs
┏━━━━┳━━━━━━━━━┳━━━━━━━━━━━┳━━━━━━━━━┓
┃ id ┃ trigger ┃ task_type ┃ enabled ┃
┡━━━━╇━━━━━━━━━╇━━━━━━━━━━━╇━━━━━━━━━┩
└────┴─────────┴───────────┴─────────┘

新建用 octop cron create（参数细节 --help 查看；调度时区跟 default_timezone）；run-now 在内嵌服务器里把任务立即跑完一遍，是验证定时任务的最直接手段。仪表盘「Cron」页与 CLI 共享同一份数据。

4.10 记忆维护：memory

Commands:
  list  List eligible running agents without starting maintenance.
  slim  Back up and slim memory, pausing new turns until completion.

实测 octop memory list（本地化输出）：

可在线整理的智能体（已运行且使用兼容的 SQLite 记忆库）：
没有可在线整理的 SQLite 智能体。此命令目前仅支持已运行、已启用记忆且版本兼容的 SQLite 智能体；PostgreSQL 整理尚未接入，并不表示 PG 无需维护。本次未执行任何整理，聊天可继续。

（本环境专家刚建、尚无记忆积累，属正常空态。）octop memory slim [--agent ID | --all] 会对 SQLite 记忆先备份再瘦身，期间暂停该专家新对话；也可在聊天里发 /memory slim 触发同一流程。

4.11 备份与恢复：backup

Commands:
  auto     Automatic backup status and one-shot run (schedule requires...
  create   Create a selected-content backup archive.
  restore  Restore from a backup archive.

  • octop backup auto status 实测（与 config.json backup 段一致）：

    auto_enabled: False
schedule: cron:0 4 * * *
retention_count: 7
include_config: True
include_workspaces: True
include_skill_packages: True
include_plugins: True
include_knowledge: True
include_chats: False
note: the scheduler only runs inside an active `octop run` process

  • octop backup create -o /var/backups/octop.tar.gz 打包数据库+工作区（--include-chats 才含聊天，--no-* 排除某类）；

  • octop backup restore <归档> 恢复；自动备份调度只在 octop run 进程内生效（systemd 形态默认满足）。

4.12 全局操作：update / clean / config / acp / bridge / captcha / completion

octop update：

Options:
  --check             Only check, do not install.
  -y, --yes           Skip confirmation.
  -v, --verbose       Verbose installer output.
  --allow-prerelease  Include and allow installing pre-releases (alpha / beta
                      / rc / dev).

--check 只查不装；正式版默认只看稳定线，追 beta 加 --allow-prerelease。

octop clean——清 CLI 状态或全量重置：默认只删 cli_state.json；--dry-run 预览（实测输出 would remove /root/.octop/cli_state.json）；--all --yes 清空整个 ~/.octop/（不可恢复，先备份）。完整卸载步骤见安装指南第十二章。

octop config——固化 CLI 默认值（写 ~/.octop/cli_state.json）：

octop config set-user admin

default_user set to admin

octop config show

{
  "default_user": "admin",
  "default_agent": null
}

octop acp——把 Octop 专家作为 stdio ACP 服务器暴露给 Zed / OpenCode 等 IDE（octop acp --agent main）。octop bridge——两台 Octop 实例互连（v1.0.2 云端协同）：probe / create / connect / agents 等子命令管理对端。octop captcha——reset 清验证码配置回落滑块（登录被验证码卡死时的逃生门）。octop completion——生成 shell 补全脚本。

五、注意事项

  1. 全局选项位置：--json / --user / --agent 写在子命令前面（octop --json chats list），写后面报 No such option；
  2. --agent 上下文：多数按专家操作的命令都要求 --agent；一次性场景 octop agent use <id> 固化，长期场景用 OCTOP_AGENT 环境变量或 systemd Environment= 注入；
  3. Offline ≠ 安全写：user delete、clean --all、agent delete 都是本地库直改且不可逆，执行前 octop backup create；
  4. embedded 命令会临时拉起服务：chats send / agent create 在服务未运行时也能执行（内嵌启动，耗时略长）；与运行中服务共用同一个 ~/.octop/octop.db（WAL 并发），但不要在两台机器上指向同一数据目录；
  5. Attach 命令需服务在跑：channel test、provider test、models ollama-*、远程 user login 这类要连 octop run；systemd 形态下即 octop service start 之后；
  6. CLI 登录态独立：CLI 的 cli_state.json 与浏览器 JWT 互不共享；octop admin rotate-jwt-secret 只影响 Web/API 令牌。

六、常见问题（FAQ）

Q1：octop chats send 报 agent 'main' not found？ init 不建默认专家。先 octop agent list 看有无专家；没有就 octop agent create main --user admin --default-model "<provider>/<model>"（实测见 4.3），创建后 state 应为 running。

Q2：报 error: --agent is required (or set root --agent / OCTOP_AGENT)？ 见五-2：显式带 --agent、octop agent use 固化、或导出 OCTOP_AGENT。

Q3：octop agent create 报 user required？ 专家必须归属用户：--user admin 或先 octop config set-user admin（实测输出 default_user set to admin）。

Q4：octop provider test 报 failed: 404 page not found？ --kind ollama 的探测路径与「外部 Ollama 服务器」组合不匹配；改 --kind openai + base-url 带 /v1（实测 ok (1298 ms)，详见安装指南 9.2 排障实录）。

Q5：octop models ollama-list 报缺少 ollama Python 包？ 官方 CLI 未捆绑该依赖，按提示 ~/.octop/venv/bin/pip install ollama 补装（方案 B 用户装进自己的 venv）。

Q6：octop chats list --json 报 No such option？ --json 是根命令全局选项：octop --json chats list。

Q7：octop update --check 提示已是最新但 GitHub 已有新版？ 稳定线只比对正式版；新版还在 beta（如 1.0.2b9）时需 octop update --check --allow-prerelease 才能看到。

Q8：忘掉管理员密码？ octop user passwd admin（本地库直改，无需服务在线），按提示输入新密码。

七、参考链接