Ubuntu 24.04 安装 Octop 1.0.2 指南

Octop 1.0.2 在 Ubuntu 24.04 的完整安装指南：官方一键脚本与 uv+venv 手动两条路线实测、初始化配置、systemd 服务托管、Ollama 模型接入与端到端对话验证，附升级/卸载与 FAQ。

OctopOctop人工智能LLM2026/10/23

Ubuntu 24.04 安装 Octop 1.0.2 指南

目标：在一台全新的 Ubuntu 24.04 服务器上从零安装 Octop 1.0.2，覆盖官方一键脚本与 PyPI 两种安装方案、初始化、前台启动、systemd 服务托管、模型接入（Ollama OpenAI 兼容端点）与端到端对话验证，全部命令与回显均在该环境实测通过。

一、环境信息

  • 操作系统：Ubuntu 24.04（x86_64，实测环境 cat /etc/os-release 可见 PRETTY_NAME="Ubuntu 24.04 LTS"）
  • Octop 版本：1.0.2（当前最新稳定版，2026-10-23 查证）
  • 运行时 Python：3.12.15（方案 A 由安装器自动准备，不依赖系统 Python；实测回显见 4.2）
  • Web 控制台端口：8088（默认，监听 127.0.0.1；LAN 访问需改 0.0.0.0，见 7.3）
  • 数据目录：/root/.octop/（root 安装；普通用户为 ~/.octop/）
  • 模型验证端点：内网另一台服务器上的 Ollama 0.40.8（http://10.89.66.2:11434，已拉取模型 qwen2.5:0.5b），Octop 通过其 OpenAI 兼容端点 /v1 接入
  • 相关版本：Ollama 0.40.8、qwen2.5:0.5b（模型）

二、前置条件

  1. 一台 Ubuntu 22.04 / 24.04 服务器（本文以 24.04 为准），具备 root 或 sudo 权限；
  2. 已安装 curl（一键脚本下载用；最小系统可用 apt install -y curl 补齐）；
  3. 硬件：官方要求「现代多核 CPU + 数 GB 内存（进程本体 + 模型/嵌入缓存）」；实测 systemd 托管后进程常驻内存约 260 MB（见 8.2 systemctl status 回显），给模型缓存与浏览器自动化留 2 GB 以上更稳妥；
  4. 磁盘：实测安装完成后的隔离环境约 814 MB（du -sh /root/.octop/venv），另加 Playwright Chromium 下载约 120 MiB，预留 2 GB 足够；
  5. 网络：能访问安装脚本源 finnie-1258344699.cos.ap-guangzhou.myqcloud.com（腾讯云 COS）与 PyPI；国内网络 PyPI 直连缓慢时用镜像源（方案 B 演示）或脚本 --mirror 参数；
  6. 无需预装 Python：官方安装器使用 uv 自动准备 Python 3.12 隔离环境，不触碰系统 Python（来源：GitHub README「Prerequisites」，2026-10-23）；
  7. 一个可用的 LLM 端点（可选但强烈建议）：云厂商 API Key，或内网 Ollama（本文验证采用后者，部署见 9.1）。

三、版本选型说明

版本信息实查于 2026-10-23（来源：GitHub Releases 与 PyPI JSON 接口）：

版本发布时间说明
1.0.22026-10-17（PyPI 上传 2026-10-18）当前最新稳定版，本文实装版本
1.0.12026-09-19新增飞书/钉钉/企微 OAuth SSO、登录验证码
1.0.02026-09-14GA 正式版
1.0.2b1~b92026-09-23 ~ 10-14预发布线，不建议生产使用

选型建议：生产环境锁定 1.0.x 稳定线（当前即 1.0.2）；想尝鲜 AgentTeams 等新特性可用 octop update --allow-prerelease（见 10.1）。指定版本安装可用安装脚本 --version <VER> 参数（仅 PyPI 源生效），或在方案 B 中 pip install octop==1.0.2 固定版本。

四、方案 A：官方一键脚本安装（推荐）

4.1 方案说明

官方对 macOS / Linux 的推荐安装方式是一条 curl | bash 命令：脚本自动用 uv 准备 Python 3.12 隔离虚拟环境到 ~/.octop/venv，安装 octop 及其全部依赖，把 CLI 链接进 PATH，并顺带下载浏览器自动化所需的 Playwright Chromium。整个过程不修改系统 Python。

4.2 执行安装

curl -fsSL https://finnie-1258344699.cos.ap-guangzhou.myqcloud.com/octop/install.sh | bash

实测输出节选（实测尾部，进度条略）：

Chrome Headless Shell 156.0.8078.4 (playwright chromium-headless-shell v1248) downloaded to /root/.cache/ms-playwright/chromium_headless_shell-1248
[octop] ✓ Playwright Chromium installed successfully
[octop] Wrapper script created: /root/.octop/bin/octop
[octop] Linked to /usr/local/bin/octop (octop works in the current shell)
[octop] Updated /root/.bashrc
[octop] Updated /root/.profile
[octop] Updated /root/.zshrc
[octop] Wrote /etc/profile.d/octop.sh

Octop installed successfully!

  Location:          /root/.octop
  Python:            Python 3.12.15
  CLI link:          /usr/local/bin/octop
  Console (Web UI):  available

[octop] octop is ready to use in the current shell (no source needed)

Then run:

  octop run       # Run in the foreground (API + Web console)
  octop service start  # Install and run in the background (systemd / launchd)
  open http://127.0.0.1:8088

Upgrade: re-run this installer. Cleanup: octop clean
Playwright reinstall: /root/.octop/venv/bin/python -m playwright install chromium

💡 说明：脚本做了五件事——① uv 建立 ~/.octop/venv（Python 3.12.15）；② 安装 octop 轮子与依赖；③ 下载 Playwright Chromium（浏览器 AI+ 与远程桌面的底层，约 120 MiB）；④ 生成 ~/.octop/bin/octop 包装器并链接到 /usr/local/bin/octop；⑤ 写入 /etc/profile.d/octop.sh 与各 shell rc 文件保证 PATH 生效。国内网络 PyPI 缓慢时可在脚本后加参数：... install.sh | bash -s -- --mirror https://mirrors.aliyun.com/pypi/simple。

4.3 安装结果验证

新开终端（或重载 shell）后验证版本与目录结构：

octop version

实测输出：

octop v1.0.2

ls /root/.octop/

实测输出（刚装完、尚未初始化）：

bin  venv

du -sh /root/.octop/venv

实测输出：

814M    /root/.octop/venv

4.4 初始化（创建数据库、JWT 密钥与首个管理员）

先看官方帮助：

octop init --help

实测输出：

Usage: octop init [OPTIONS]

  Bootstrap an Octop server (~/.octop dir, DB migrations, first admin).

Options:
  --admin-username TEXT      First admin username (or set
                             OCTOP_ADMIN_USERNAME).
  --admin-password TEXT      First admin password (or set
                             OCTOP_ADMIN_PASSWORD).
  --admin-display-name TEXT  Optional display name for the admin user.
  --force                    Wipe existing ~/.octop contents before
                             bootstrapping.
  --yes                      Skip all interactive prompts.
  -h, --help                 Show this message and exit.

交互式执行 octop init 会进入向导逐项询问管理员账号与密码（密码要求至少 8 位且同时含字母与数字）；无人值守（自动化脚本）场景用参数直填并以 --yes 跳过全部交互提示。本文以管理员 admin、密码 q1w2e3r4 实测：

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)

⚠️ 注意：q1w2e3r4 仅为本文演示口令，实际部署请换成你自己的强密码（≥8 位字母+数字）。初始化落盘内容：octop.db（SQLite 控制平面）、secrets/jwt_secret、config.json，参数含义见《Octop 1.0.2 配置参数详解》。

4.5 前台启动与验证

octop run --host 0.0.0.0 --port 8088

实测输出：

Saved config to /root/.octop/config.json
INFO:     Started server process [6770]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:8088 (Press CTRL+C to quit)

保持该终端运行，另开一个终端验证 HTTP 服务与初始化状态：

curl -s -o /dev/null -w "%{http_code}" http://127.0.0.1:8088/

实测输出：

200

curl -s http://127.0.0.1:8088/api/setup/status

实测输出：

{"setup_required":false,"wizard_password_required":true,"wizard_password_exists":false,"wizard_password_path":"/root/octop-login.txt","database_driver":"sqlite","database_bound":true}

setup_required: false 说明 4.4 的 CLI 初始化已创建好管理员，浏览器打开 http://<服务器IP>:8088 直接用 admin / q1w2e3r4 登录即可，无需再走向导。再用登录接口做一次带凭据的验证（截取回显前段）：

curl -s -X POST http://127.0.0.1:8088/api/auth/login -H "Content-Type: application/json" -d '{"username":"admin","password":"q1w2e3r4"}'

实测输出节选：

{"access_token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxIiwidW5hbWUiOiJhZG1pbiIsInJvbGUiOiJhZG1pbiIsImlhdCI6MTc5MjcwNzQzNywiZXhwIjoxNzkyNzkzODM3fQ.6K-qZGnQTRBbCNrlKFpYVQIjwnXW9PLW0MdodpRbCkI","token_type":"Bearer","expires_in":86400,"user":{"id":1,"username":"admin","role":"admin",...

返回 token_type: Bearer、expires_in: 86400（即 24 小时 JWT），登录链路正常。

💡 说明：octop run --host 0.0.0.0 的作用是把监听地址从默认 127.0.0.1 改为所有网卡，供 LAN 内其他设备访问 Web 控制台；该覆盖会被持久化进 config.json 的 bind_host 字段（官方 run 命令帮助明确「CLI 覆盖会在 uvicorn 启动前立即持久化到 config.json」）。

五、方案 B：PyPI 手动安装（自管 Python）

5.1 方案说明

如果你已经用 pyenv/venv/conda 自行管理 Python 3.12+，可以跳过官方脚本，直接从 PyPI 安装 octop 轮子。它与方案 A 的差异是：不生成 PATH 包装器、不自动配置 shell、不自动下载 Playwright Chromium（浏览器自动化需事后手动补装）。

5.2 安装步骤

Ubuntu 24.04 自带 Python 3.12，先补齐 venv 组件（若缺）：

apt install -y python3.12-venv

创建独立虚拟环境：

python3 -m venv /opt/octop-venv

⚠️ 排障实录：未安装 python3.12-venv 时 python3 -m venv 会直接失败，实测报错为：

The virtual environment was not created successfully because ensurepip is not
available.  On Debian/Ubuntu systems, you need to install the python3-venv
package using the following command.

    apt install python3.12-venv

按提示补装 python3.12-venv 后重建 venv 即可。

⚠️ 排障实录：直接 pip install octop 在国内网络实测长期停滞无输出；换国内镜像源后下载正常，但 Octop 依赖树较大（201 个包），pip 解析依赖时逐版本回溯，实测两个镜像源均运行 20 分钟以上仍未完成解析。方案 B 建议改用 uv 安装——Octop 官方一键脚本内部同样是把依赖安装交给 uv 处理，uv 的依赖解析为秒级。

先给 venv 装 uv（PyPI 官方轮子，走腾讯云镜像）：

/opt/octop-venv/bin/pip install -i https://mirrors.cloud.tencent.com/pypi/simple uv

实测输出：

Installing collected packages: uv
Successfully installed uv-0.13.5

用 uv 安装 octop：

/opt/octop-venv/bin/uv pip install --python /opt/octop-venv/bin/python -i https://mirrors.cloud.tencent.com/pypi/simple octop

实测输出节选（首次安装）：

Using Python 3.12.3 environment at: /opt/octop-venv
Resolved 201 packages in 13.37s
Downloading sqlalchemy (4.5MiB)
Downloading aiohttp (1.8MiB)
Downloading langchain-community (2.3MiB)
Downloading google-genai (1.2MiB)
   Building oss2==2.19.1
Downloading cryptography (4.5MiB)

Installed 201 packages in 150ms
 + octop==1.0.2
 + octop-browser==1.0.0
 + octop-gateway==1.0.3
 + octop-harness==1.0.4
 + octop-memory==1.0.2

安装完成后重复执行同一条命令会做幂等校验，实测回显 Checked 1 package in 8ms，可用于确认安装完整。

验证：

/opt/octop-venv/bin/octop version

实测输出：

octop v1.0.2

5.3 补齐浏览器自动化（可选）

方案 B 没有自动下载 Chromium，需要网页自动化/远程桌面时手动补装（README 官方口径）：

/opt/octop-venv/bin/python -m playwright install chromium

实测执行退出码为 0，浏览器落位 ~/.cache/ms-playwright/（实测目录含 chromium-1248、chromium_headless_shell-1248、ffmpeg-1013）。

5.4 后续步骤

方案 B 的初始化（octop init）、启动（octop run）、服务托管（octop service）与方案 A 完全一致，后续步骤直接从 4.4 继续；注意把 octop 命令替换为 /opt/octop-venv/bin/octop，或把 /opt/octop-venv/bin 加入 PATH。

六、方案对比与选择建议

维度方案 A：官方一键脚本方案 B：PyPI 手动
命令curl … install.sh | bashuv pip install octop（详见 5.2）
Python 环境自动 uv 隔离 venv（3.12.15），零依赖需自备 Python 3.12+ 与 venv
PATH/Shell 配置自动（/usr/local/bin/octop + profile.d）手动
Playwright Chromium自动下载手动补装
版本固定--version（PyPI 源）uv pip install octop==1.0.2
适用场景全新服务器快速起步（推荐）自管 Python / 离线 wheel 审计 / 定制路径

关键差异在于「环境准备由谁负责」：全新机器选方案 A 一步到位；已有统一的 Python 管理规范或需要把 octop 纳入既有 venv 体系时选方案 B。两方案的运行态数据都在 ~/.octop/，互相切换只需重装程序本体，数据不丢。

七、初始化与首次启动的配置说明

7.1 数据目录布局

安装并初始化完成、服务跑起来后，~/.octop/ 的实测结构：

ls -la /root/.octop/

实测输出：

drwxr-xr-x 9 root root   4096 Oct 22 22:16 .
drwx------ 1 root root   4096 Oct 22 22:15 ..
drwxr-xr-x 3 root root   4096 Oct 22 22:16 agents
drwxr-xr-x 2 root root   4096 Oct 22 22:14 bin
drwxr-xr-x 2 root root   4096 Oct 22 22:16 browser-profiles
-rw-r--r-- 1 root root     55 Oct 22 22:16 cli_state.json
-rw-r--r-- 1 root root   1239 Oct 22 22:15 config.json
drwxr-xr-x 2 root root   4096 Oct 22 22:15 logs
-rw------- 1 root root    105 Oct 22 22:15 memory-slim-control.json
-rw------- 1 root root 458752 Oct 22 22:14 octop.db
-rw------- 1 root root  32768 Oct 22 22:17 octop.db-shm
-rw------- 1 root root 304912 Oct 22 22:17 octop.db-wal
drwxr-xr-x 2 root root   4096 Oct 22 22:14 plugins
drwxr-xr-x 3 root root   4096 Oct 22 22:15 security
drwxr-xr-x 6 root root   4096 Oct 22 22:12 venv

其中 octop.db（含 -shm/-wal）是 SQLite WAL 模式的控制平面数据库，config.json 是进程级配置，agents/ 存每个专家的工作区。目录与文件含义的逐项解读见《Octop 1.0.2 配置参数详解》。

7.2 备份先行

升级或大改动前先备份（octop backup 会打包数据库与工作区）：

octop backup create --help

实测输出：

Usage: octop backup create [OPTIONS]

  Create a selected-content backup archive.

Options:
  -o, --output PATH    Output .tar.gz path.
  --home PATH          Octop home (default ~/.octop).
  --no-config          Do not include config.json / env.
  --no-workspaces      Do not include agent workspaces.
  --no-skill-packages  Do not include global skill packages.
  --no-plugins         Do not include installed plugins.
  --no-knowledge       Do not include knowledge base files.
  --include-chats      Include chat history (omitted by default).
  -h, --help           Show this message and exit.

7.3 局域网访问

默认监听 127.0.0.1 只允许本机访问；要给家庭/团队其他成员用，两种方式任选：

  • 启动参数覆盖：octop run --host 0.0.0.0（会持久化到 config.json）；
  • 配置文件修改：把 ~/.octop/config.json 的 bind_host 改为 "0.0.0.0" 后重启服务。

公网暴露前务必：修改默认口令、启用 TLS（octop run --ssl 或反代）并配置登录验证码（OCTOP_CAPTCHA_PROVIDER），相关参数详见《Octop 1.0.2 配置参数详解》。

八、systemd 服务托管（生产推荐）

8.1 注册并启动服务

前台 octop run 关掉终端就停了，生产环境用官方 service 子命令注册成 systemd 服务：

octop service start

实测输出：

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}

该命令一次完成三件事：安装 /etc/systemd/system/octop.service 单元、写入 NOFILE 资源 drop-in、启动服务并立即探测 HTTP 健康端点（health: OK 且 db: True、users_loaded: 1）。

8.2 服务状态验证

systemctl is-active octop

实测输出：

active

systemctl status octop --no-pager

实测输出节选：

● octop.service - Octop AI Server
     Loaded: loaded (/etc/systemd/system/octop.service; enabled; preset: enabled)
    Drop-In: /etc/systemd/system/octop.service.d
             └─10-nofile.conf, 15-resource-limits.conf
     Active: active (running) since Thu 2026-10-22 22:21:51 UTC; 5s ago
   Main PID: 4073 (octop)
      Tasks: 9 (limit: 94371)
     Memory: 260.6M (high: 18.7G max: 23.4G swap max: 512.0M available: 18.5G peak: 263.2M)
        CPU: 4.301s

Oct 22 22:21:51 octop-server systemd[1]: Started octop.service - Octop AI Server.

关键信息解读：单元文件 enabled（开机自启）；两个 drop-in——10-nofile.conf（LimitNOFILE=65535，官方自动写入）与 15-resource-limits.conf（内存保护，默认 MemoryHigh=60%、MemoryMax=75%、MemorySwapMax=512M，取物理内存百分比，可通过 systemctl edit octop.service 按机器预算覆盖，如 MemoryHigh=5G/MemoryMax=6G）；进程常驻内存实测约 260 MB。

curl -s -o /dev/null -w "%{http_code}" http://127.0.0.1:8088/

实测输出：

200

8.3 日常运维命令

octop service status    # 查看服务安装/运行/健康状态
octop service restart   # 重启（升级后使用）
octop service stop      # 停止

💡 说明：octop service 在 Linux 用 systemd、macOS 用 launchd，后端自动探测；可用 OCTOP_SERVICE_SCOPE=user|system 强制用户级或系统级单元（用户级单元需要 cgroup v2 内存控制器支持）。

九、模型接入与端到端对话验证

9.1 准备 Ollama 端点（内网另一台服务器）

Octop 不内置模型，需要至少一个 LLM Provider。本文用内网 Ollama 0.40.8（监听 http://10.89.66.2:11434，已 ollama pull qwen2.5:0.5b）验证。先在 Octop 服务器上确认 OpenAI 兼容端点可达：

curl -s --max-time 5 http://10.89.66.2:11434/v1/models

实测输出：

{"object":"list","data":[{"id":"qwen2.5:0.5b","object":"model","created":1792707082,"owned_by":"library"}]}

9.2 创建 Provider 并连通性测试

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
}

⚠️ 排障实录：Provider 的 kind 有讲究。实测先建了 --kind ollama（base-url 不带 /v1）的 Provider，octop provider test 报 failed: 404 page not found——ollama 类型的探测路径与「Ollama 托管在外部服务器」的组合不匹配；改用 --kind openai 且 base-url 指到 OpenAI 兼容端点 http://<host>:11434/v1 后测试通过。Ollama 官方本就提供 OpenAI 兼容层，这种接法是最稳的通用路径。

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

实测输出（2 为 Provider id）：

ok (1298 ms)

一次真实的一 token 探测往返 1298 ms，链路打通。

9.3 设默认模型并创建专家

octop models active --provider ollama-openai --model qwen2.5:0.5b

实测输出：

{
  "provider_name": "ollama-openai",
  "model": "qwen2.5:0.5b"
}

⚠️ 排障实录：octop init --yes 只建管理员不建默认专家，直接对话会报 agent 'main' not found（完整排障见 11.3）；并且创建专家必须指定归属用户，否则报 user required (--user, CLI default_user, or agent with an owner)。正确做法：

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

实测输出：

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

octop agent list

实测输出：

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

9.4 端到端对话验证

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

实测输出：

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

main 专家经 Octop → OpenAI 兼容 Provider → Ollama → qwen2.5:0.5b 的完整链路返回了模型自述（0.5b 小模型把 Qwen 系说成「阿里云自研」，属模型自身认知，与链路无关），一轮对话 7.9 s。至此安装、托管、模型接入全部验证通过，Web 控制台 http://<服务器IP>:8088 可正常登录使用。

十、升级与多版本管理

10.1 内置升级命令

octop update --help

实测输出：

Usage: octop update [OPTIONS]

  Check for and install a newer Octop release.

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).
  -h, --help          Show this message and exit.

官方口径：octop update 只替换程序轮子本体，~/.octop/ 的数据库、工作区、密钥与 config.json 全部保留；跨版本升级前建议先 octop backup。若注册过系统服务，升级后会自动重启服务。

10.2 重跑安装器与固定版本

重跑 4.2 的一键脚本即升级到最新稳定版；需要回退/固定版本时用 --version（PyPI 源）：

curl -fsSL https://finnie-1258344699.cos.ap-guangzhou.myqcloud.com/octop/install.sh | bash -s -- --version 1.0.1

方案 B 用户用 /opt/octop-venv/bin/uv pip install octop==<版本> 同理。数据库 schema 在下次启动时自动迁移，无需手工干预。

十一、常见问题（FAQ）

Q1：python3 -m venv 报 ensurepip is not available 怎么办？ 方案 B 的前置遗漏：Ubuntu 需先 apt install -y python3.12-venv 再建 venv（实测报错与解法见 5.2 排障实录）。

Q2：pip install octop 长时间无进展？ 两层原因实测：国内直连 PyPI 下载停滞；换镜像源后下载正常，但 Octop 依赖树大（201 个包），pip 逐版本回溯解析极慢（实测 20 分钟以上未完成）。推荐改用 uv 安装（解析秒级，完整步骤见 5.2）；一键脚本路径则加 --mirror 参数（见 4.2 说明）。

Q3：octop chats send 报 OctopError: agent 'main' not found？ octop init --yes（含交互式 init）只创建管理员，不创建默认专家；先用 octop agent create main --user admin --default-model "<provider>/<model>" 创建（见 9.3 实测），创建后状态应为 running。

Q4：octop chats send 报 error: --agent is required (or set root --agent / OCTOP_AGENT)？ CLI 需要 Agent 上下文。三种解法：命令行显式 --agent <agent_id>；octop agent use <agent_id> 固化到 ~/.octop/cli_state.json；或导出 OCTOP_AGENT 环境变量。

Q5：octop agent create 报 user required (--user, CLI default_user, or agent with an owner)？ 专家必须归属用户：加 --user admin（管理员给自己建），或先用 octop config set-user admin 固定默认用户（实测输出 default_user set to admin）。

Q6：Provider 测试报 failed: 404 page not found？ --kind ollama 的探测路径与外部 Ollama 服务器组合不匹配（实测复现）；改用 --kind openai 且 base-url 指向 http://<ollama主机>:11434/v1，测试通过返回 ok (<毫秒> ms)（见 9.2 排障实录）。

Q7：LAN 内访问不了 8088？ 确认监听地址：octop run --host 0.0.0.0 或把 config.json 的 bind_host 改为 "0.0.0.0" 后重启（见 7.3）；再查防火墙放行 8088。

Q8：管理员密码忘了？ 管理员在服务器本地直接重置任意用户密码：octop user passwd <用户名>（本地库操作，无需服务在线），按提示输入新密码（≥8 位字母+数字）。

十二、卸载与清理

先停服务，再清理程序与数据：

octop service stop

octop clean --dry-run

实测输出：

would remove /root/.octop/cli_state.json

💡 说明：默认 octop clean 只删 CLI 状态文件（cli_state.json）；octop clean --all --yes 会清空整个 ~/.octop/（含数据库、工作区、密钥，不可恢复，执行前确认已有备份）。

程序本体与链接的手工清理（方案 A）：

rm -f /usr/local/bin/octop /etc/profile.d/octop.sh
rm -rf /root/.octop

再手工移除安装器写入 ~/.bashrc / ~/.profile / ~/.zshrc 的 PATH 行（含 .octop/bin 字样）。方案 B 只需 rm -rf /opt/octop-venv。

十三、参考链接

站内相关：《Octop 1.0.2 配置参数详解》、《Ubuntu 24.04 安装 Octop 1.0.2 指南》