Octop

Octop 项目概述

Octop 是一款开源、自托管的多用户 AI 助手平台，面向家庭、小型团队及个人开发者。它采用多智能体架构，既能为每位用户保留独立的工作空间与记忆，又支持专家共享与跨实例协作。所有数据均保存在本地（~/.octop/），单进程同时承载 Web 控制台、CLI、IM 通道与定时任务，强调"数据不离开本机"的设计理念。

核心特性

• 多用户与专家团队：内置管理员/家庭共享模式，可创建多个专家（Expert），并提供专家库与专家市场，按需切换。
• MBTI 角色：内置 16 种人格模板及交互式测验，可为每个智能体赋予差异化性格。
• AgentTeams（Beta）：由协调者调度多个专家执行多步任务。
• 安全机制：JWT 多用户隔离、工具调用审批、Shell 命令守卫、PII 信息脱敏，数据全部本地化。
• 连接器生态：内置腾讯文档、腾讯会议、Notion、TickTick、Obsidian 等 OAuth / MCP 连接器，支持 MCP 网关与自定义服务器。
• 可插拔工作区后端：本地磁盘、Docker 沙箱、PostgreSQL、COS/S3 等，与控制平面数据库相互独立。
• 可移植记忆：由 Octop Memory 提供层级化召回与全文检索，记忆随工作区一起迁移。
• ACP 双向协议：既可作为 stdio ACP 服务端供 Zed、OpenCode 等 IDE 调用，也可调用 OpenCode、Claude Code、Codex 等外部编码代理。
• 浏览器与终端能力：内置基于 Chromium 的浏览器自动化、远程桌面控制（Windows/macOS/Linux）以及网页版交互式终端。
• 多端入口：Web 控制台、原生桌面客户端（Windows/macOS/Linux/FnOS NAS）、CLI、HTTP/SSE/WebSocket API。

技术架构

层级	技术栈
语言	Python 3.12+
Web 框架	FastAPI + uvicorn
智能体运行时	Octop Harness
IM 网关	Octop Gateway
数据库	SQLite（WAL 模式，默认）或 PostgreSQL（可选）
前端	React 18 + TypeScript + Vite + Ant Design
调度	APScheduler
ACP	agent-client-protocol
工程化	hatchling · ruff · mypy · pytest

Octop 由四个核心组件构成：Harness（模型路由、工具、技能、会话快照）、Gateway（多平台 IM 归一化）、Memory（层级记忆与 FTS）、Browser（基于 CDP 的浏览器自动化）。所有入口（Web、IM、定时任务）统一经过进程内的 HarnessProcessor，无需外部消息队列，重启即可从控制平面数据库重建状态。

快速部署

安装

支持 macOS、Linux、Windows：

# macOS / Linux
curl -fsSL https://finnie-1258348699.cos.ap-guangzhou.myqcloud.com/octop/install.sh | bash

# Windows PowerShell
irm https://finnie-1258348699.cos.ap-guangzhou.myqcloud.com/octop/install.ps1 | iex

安装脚本使用 uv 在 ~/.octop/venv 内创建隔离的 Python 环境，并生成 ~/.octop/bin/octop 包装命令，不会污染系统 Python。可通过 --extras browser 参数下载 Playwright Chromium。也支持 pip install octop（可选 [local-embedding] 扩展）。

初始化与启动

octop init                    # 交互式向导：建库、生成 JWT、创建管理员
octop run                     # 前台运行
octop run --host 0.0.0.0 --port 8088
octop service start           # 注册为系统服务（systemd/launchd/Windows service）

启动后访问 http://127.0.0.1:8088。

Docker 部署

docker compose -f docker/docker-compose.yml up -d
# 国内镜像
docker compose -f docker/docker-compose.cn.yml up -d

# 手动运行
docker run -d -p 8088:8088 \
  -v octop-data:/data/.octop \
  -e HOME=/data \
  -e OCTOP_DEFAULT_PASSWORD="<strong-password>" \
  octop:latest

首次启动若 OCTOP_DEFAULT_PASSWORD 合法，则自动创建管理员并写入 /data/.octop/credential.txt；否则进入引导向导（解锁密码位于 /data/.octop/octop-login.txt）。密码策略：至少 8 位，需包含字母与数字。

升级与备份

octop update    # 仅替换 wheel/二进制，数据与配置完整保留
octop backup    # 升级前先备份

核心 CLI

命令	功能
octop init	初始化 ~/.octop/（数据库、管理员、JWT 密钥）
octop run	前台启动服务
octop service start/stop	管理系统服务
octop agent	创建、列出、启停智能体
octop channel list/install	管理 IM 通道
octop chats	REPL 与会话管理
octop acp --agent main	stdio ACP 服务端
octop cron	定时任务管理
octop models / provider list	LLM 提供商与模型
octop skills list --agent main	按代理启用/禁用技能
octop plugin	插件安装与管理
octop memory slim [--agent ID\|--all]	备份并精简 SQLite 记忆
octop update / backup / clean	升级、备份、清理

配置与数据目录

所有运行时状态位于 ~/.octop/：

~/.octop/
├── config.json                # 进程配置（可选 database 段）
├── octop.db                   # SQLite：用户、代理、通道、定时任务等
├── secrets/                   # JWT 密钥、通道令牌
├── agents/<agent_id>/         # 单代理工作区（SOUL.md、skills 等）
├── security/tool_guard/       # Shell 命令允许/拒绝规则
├── logs/
├── venv/                      # uv 管理的 Python 环境
└── bin/octop                  # PATH 包装器

数据库可切换为 PostgreSQL（通过 config.json 的 database 段或 OCTOP_DATABASE_* 环境变量）。IM 通道覆盖飞书、钉钉、QQ、微信、Telegram、Discord、企业微信等，凭据通过 octop channel 子命令或控制台配置。

ACP 双向集成

# 入站：外部工具使用本机 Octop 代理
octop acp --agent main

# 出站：Octop 调用外部编码代理
# 1. 控制台 → ACP 配置 runner（OpenCode、CodeBuddy、Claude Code、Codex）
# 2. 在代理上启用 acp_runner 后即可在对话中委托任务

安全与扩展

• 本地优先：配置、会话、工作区与凭据全部位于 ~/.octop/。
• 多用户隔离：JWT 认证 + 独立工作区。
• PII 脱敏与工具审批：敏感数据在离开工作区前脱敏；高风险工具或 Shell 命令需用户显式批准。
• 可编辑守卫规则：~/.octop/security/tool_guard/ 提供用户自定义命令白/黑名单。
• 无供应商锁定：可自由替换 LLM 提供商、存储后端与 IM 通道。

Octop 提供完整的 REST/SSE/WebSocket API（默认关闭，可在 config.json 设置 "enable_api_docs": true 启用交互式文档 /api/docs），支持第三方系统以编程方式集成。