Octop：超详细部署与使用教程

Octop 是腾讯云开源的自托管 AI 助手平台，主打「多用户、多专家 Agent」的家庭/小团队智能助手：单进程启动即提供 Web 控制台、CLI、IM 通道（飞书/钉钉/QQ/微信/Telegram/Discord/企业微信）与定时任务，全部数据留在本机，完全自托管。

目录

• 一、项目概述
• 二、环境要求
• 三、部署方式
• 四、使用方法
• 五、常见问题排查（FAQ）
• 六、部署注意事项与最佳实践
• 七、参考资料

一、项目概述

1.1 项目定位

Octop 是一个开源、自托管的 AI 助手平台，面向家庭与小团队。它不是一个单一聊天工具，而是一个「可并行运行的数字生命」：通过多 Agent 架构，为团队、家庭、个人构建一个既独立又协作的智能环境。其完全自托管设计意味着隐私从不妥协——所有对话、工作区、凭证都保存在本机 ~/.octop/ 目录下；单进程启动即可同时提供 Web 控制台、CLI 与 IM 集成能力。

1.2 核心功能

• 多用户专家团队：一个管理员账号，全家/小团队共享；内置专家库与专家市场，按场景切换不同专家。
• 云端协作：两个 Octop 实例可互相连接，浏览对方专家并跨实例聊天，历史记录留在专家侧。
• MBTI 人格：16 种性格模板 + 互动测试，为每个 Agent 赋予独特角色。
• AgentTeams（Beta）：一个协调者调度多个专家完成多步骤工作。
• 安全内置：JWT 多用户隔离、工具审批、Shell 命令护栏、PII 脱敏，数据不出本机。
• Connector 生态：腾讯文档、腾讯会议、Notion、TickTick、MCP 网关等 OAuth/连接器。
• 可插拔工作区后端：本地磁盘、Docker 沙箱、PostgreSQL、COS/S3 存储 Agent 文件。
• 可迁移记忆：基于 Octop Memory 的层级记忆，随工作区迁移。
• 知识库：对个人文档做 RAG，支持部署内共享语料。
• 插件系统：第三方插件扩展能力。
• ACP 双向集成：octop acp 接入 IDE；也可把任务委派给 OpenCode / Claude Code 等编码 Agent。
• 终端 AI+ / 浏览器 AI+ / 远程桌面：浏览器内交互式 Shell、无头 Chromium 自动化、远程控制桌面。
• 桌面客户端：Windows / macOS / Linux 原生应用与 FnOS NAS 包。

1.3 技术架构

技术栈（来自官方 README）：

架构为单进程模型：Web UI、IM、cron 全部走同一个进程内 HarnessProcessor，重启后从控制面数据库重建全部状态。其核心组件包括 Octop Harness（Agent 运行时）、Octop Gateway（IM 通道桥）、Octop Memory（层级记忆 + 全文搜索）、Octop Browser（CDP 浏览器自动化）。

二、环境要求

三、部署方式

下面给出三种部署方式：方式一：一键脚本安装（推荐）→ 方式二：Docker Compose（生产推荐）→ 方式三：PyPI / 源码安装。

3.1 方式一：一键脚本安装（macOS / Linux，推荐）

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

Windows（PowerShell）：

irm https://finnie-1258344699.cos.ap-guangzhou.myqcloud.com/octop/install.ps1 | iex

Windows（cmd）：

curl -fsSL https://finnie-1258344699.cos.ap-guangzhou.myqcloud.com/octop/install.bat -o install.bat
install.bat

安装完成后打开新终端或重载 shell：

source ~/.zshrc   # Zsh
# 或
source ~/.bashrc  # Bash

安装器通过 ~/.octop/bin 把 octop 命令放到 PATH 上。可选附加组件（浏览器自动化 Chromium）：

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

初始化与启动

# 1) 初始化向导：创建 SQLite 数据库、JWT 密钥、第一个管理员账号
octop init

# 2) 前台启动（API + Web 控制台）
octop run

# 自定义监听地址/端口
octop run --host 0.0.0.0 --port 8088

# 注册为系统服务（systemd / launchd / Windows 服务）
octop service start

浏览器打开 http://127.0.0.1:8088 即可进入控制台。

3.2 方式二：Docker Compose（生产推荐）

# 克隆仓库后启动
git clone https://github.com/TencentCloud/Octop.git
cd Octop
docker compose -f docker/docker-compose.yml up -d

# 国内网络 ghcr.io 不可达时使用中国镜像编排
docker compose -f docker/docker-compose.cn.yml up -d

手动 docker run：

docker run -d \
  -p 8088:8088 \
  -v octop-data:/data/.octop \
  -e HOME=/data \
  -e OCTOP_DEFAULT_PASSWORD="<至少8位且含字母数字的强密码>" \
  octop:latest

环境变量说明：

密码策略：至少 8 位，且必须包含字母和数字。 首次启动成功后，凭证写入容器内 /data/.octop/credential.txt；若未设置或密码不合法，解锁密码在 /data/.octop/octop-login.txt。

3.3 方式三：PyPI / 源码安装

已自行管理 Python 环境的用户：

pip install octop
# 可选：本地 ONNX Embedding 模型缓存
pip install "octop[local-embedding]"
# 浏览器自动化使用内置 Playwright，安装 Chromium：
python -m playwright install chromium

源码开发（需 Python 3.12+、Node 18+、uv）：

git clone https://github.com/TencentCloud/Octop.git
cd Octop
uv sync --extra local-embedding
make install          # pip install -e ".[dev]"
make dev-frontend     # 另开终端：Vite 前端 :5173

3.4 桌面客户端（免终端）

从 GitHub Releases 下载对应平台产物：

3.5 验证部署成功

1. octop run 启动后，浏览器访问 http://127.0.0.1:8088 出现登录页；
2. 用 octop init 设置的管理员账号登录，左侧菜单可见 Chat / Experts / Connectors / Channels / Cron / Knowledge / Plugins 等；
3. 交互式 API 文档位于 http://127.0.0.1:8088/api/docs（默认关闭，需在 config.json 中设置 "enable_api_docs": true）。

3.6 云市场一键部署

官方提供腾讯云轻量应用服务器（Lighthouse）与 CVM 镜像蓝图，在腾讯云控制台选择 Octop 应用蓝图即可一键拉起，适合不想自己配 Docker 的用户。

四、使用方法

4.1 基础用法：首次配置

• 首次运行 octop init 按向导设置管理员密码（≥8 位、字母+数字）；
• 在控制台「Settings」中接入 LLM Provider（OpenAI 兼容 API、DashScope Qwen、Ollama 等）；
• 创建第一个专家（Expert），选择 MBTI 人格模板，开始对话。

4.2 常用命令（CLI）

# 初始化 / 启动 / 服务
octop init                 # 引导 ~/.octop（数据库、管理员、JWT 密钥）
octop run                  # 前台启动
octop service start        # 安装并启动为系统服务
octop service stop         # 停止系统服务

# Agent / 专家
octop agent                # 创建、列表、启停 Agent
octop chats                # REPL 与会话管理

# 模型与通道
octop models               # Provider 预设与模型解析
octop provider list        # 列出 Provider
octop channel list         # IM 通道列表
octop channel install      # 安装 IM 通道

# 定时任务 / 技能 / 插件
octop cron list
octop cron create --help
octop skills list --agent main
octop plugin               # 安装管理第三方插件

# 运维
octop backup               # 导出/恢复备份
octop update               # 检查并安装更新（数据库、工作区、密钥保留）
octop clean                # 清理 CLI 状态或清空 ~/.octop/
octop memory list          # 列出可做记忆维护的运行中 Agent
octop memory slim --all    # 顺序维护所有合格 Agent 的记忆

4.3 常用通道与连接器

支持 IM 通道及所需凭证：

内置 OAuth / MCP 连接器包括腾讯文档、腾讯会议、Notion、TickTick、OpenAlex、飞书 CLI、企业微信 CLI、Agent Mail、Obsidian、Dify 等；也可在控制台添加自定义 MCP Server。

4.4 进阶功能

• ACP 双向：外部工具（Zed、OpenCode）用 octop acp --agent main 以 stdio ACP 接入你的 Octop Agent；Octop 也可把编码任务委派给 OpenCode、CodeBuddy、Claude Code、Codex。
• 远程桌面：在 Dashboard 中实时查看并控制主机桌面（Linux/Windows/macOS），无头 Linux 可一键拉起隔离桌面。
• 反向代理子路径：以 https://example.com/octop/ 暴露时，前端需用 VITE_BASE_PATH=/octop/ 重新构建，nginx 侧 strip 前缀。
• PostgreSQL 控制面：在 config.json 配置 database 段或使用 OCTOP_DATABASE_* 环境变量，默认 SQLite(WAL)。

4.5 数据目录结构

~/.octop/
├── config.json          # 进程配置
├── octop.db             # SQLite：用户、Agent、通道、cron
├── secrets/             # JWT 密钥、通道 token
├── agents/<agent_id>/   # 每个 Agent 的工作区（SOUL.md、skills…）
├── security/tool_guard/ # Shell 命令允许/拒绝规则
├── logs/                # 运行日志
├── venv/                # uv 管理的 Python
└── bin/octop            # PATH 包装脚本

4.6 适用场景

• 家庭共享智能助手：一个管理员账号，全家各有专属专家；
• 小团队内部助手：接入飞书/钉钉/企业微信，把群聊任务路由给 Agent；
• 开发者提效：终端 AI+、浏览器自动化、ACP 委派编码 Agent；
• 隐私敏感场景：对话与知识库完全留在本机；
• 定时任务：自然语言配置 cron，让 Agent 每天定时推送/执行任务。

五、常见问题排查（FAQ）

Q1：启动后访问 8088 打不开页面 - 原因：端口被占用，或 octop run 未正常启动。 - 解决：ss -lntp | grep 8088 确认端口；改用 octop run --port 8090 换端口；检查 ~/.octop/logs/ 日志。

Q2：Docker 首次启动没有自动创建管理员 - 原因：OCTOP_DEFAULT_PASSWORD 未设置或不满足密码策略（≥8 位、字母+数字）。 - 解决：打开安装向导，解锁密码在 /data/.octop/octop-login.txt；或设置合法密码后重启容器。

Q3：LLM 调用失败 / 模型无响应 - 原因：未配置 Provider 或 API Key 无效、网络不通。 - 解决：octop provider list 检查；在控制台 Settings 中核对 OpenAI 兼容接口地址与 Key；国内网络可用 DashScope Qwen 或本地 Ollama。

Q4：浏览器自动化不可用 - 原因：未安装 Playwright Chromium。 - 解决：重新执行安装器 --extras browser，或 python -m playwright install chromium。

Q5：升级后数据库结构不兼容 - 解决：官方自动迁移；升级前先 octop backup；跨大版本升级若向导提示迁移，再执行 octop init。

Q6：IM 通道（飞书/钉钉）消息收不到 - 解决：核对 App ID/Secret 与事件回调地址；octop channel list 查看通道状态；企业微信需确认 Corp ID 与 Agent Secret 对应。

Q7：占用资源过高 - 原因：本地 Embedding 模型、Docker 沙箱工作区叠加。 - 解决：octop memory slim 维护记忆；在 Settings 关闭不用的专家/插件；必要时切换控制面到 PostgreSQL。

六、部署注意事项与最佳实践

1. 不要裸奔公网：Octop 带远程桌面与 Shell 能力，务必通过反向代理 + HTTPS 暴露，或仅内网访问。
2. 密码策略：管理员密码 ≥8 位且含字母数字；定期轮换 JWT 密钥。
3. 备份：定期 octop backup，重点备份 ~/.octop/octop.db 与 secrets/。
4. 生产用 PostgreSQL：多人协作、长期运行场景把控制面切到 PostgreSQL，SQLite 适合个人/小规模。
5. 版本固定：Docker 生产环境固定镜像 tag，不要用 latest。
6. 工具护栏：在 ~/.octop/security/tool_guard/ 收紧 Shell 命令白名单，防止 Agent 误操作主机。
7. 资源规划：浏览器 AI+ 与远程桌面会额外消耗显存/内存，按需开启。

七、参考资料

• GitHub 仓库：https://github.com/TencentCloud/Octop
• Releases 与桌面客户端：https://github.com/TencentCloud/Octop/releases
• PyPI：https://pypi.org/project/octop/
• 文档目录（仓库内 docs/）：https://github.com/TencentCloud/Octop/tree/main/docs
• 相关项目：octop-harness / octop-gateway / octop-memory / octop-browser（均在 TencentCloud 组织下）
• Discord 社区：https://discord.gg/QnWdhJxq9h