README

支持多用户、多 Agent 的自托管 AI 助手 — 更聪明，更懂你。



  
    
  



  
  
  
  
  
  
  
  



  亮点 ·
  概述 ·
  核心技术 ·
  功能特性 ·
  规划 ·
  快速开始 ·
  目录



  English · 中文


---

Octop 是一个开源、自托管的 AI 助手。它不仅是工具，更是可并行运作的数字生命体。通过多 Agent 架构，它为团队、家庭和个人构建了既独立又协作的智能环境。并且这一切都运行在你的机器上——完全自托管的设计让隐私不再是妥协，而单进程启动的便捷性，则让强大的 Web 控制台、CLI 与 IM 集成触手可及。

借助飞书、钉钉、QQ、微信、企业微信或 HTTP/SSE/WebSocket API 与任意 Agent 对话；通过专家库一键创建专业角色，通过 Connector（OAuth + MCP）接入外部服务，通过 ACP 与 IDE / 终端 AI 工具双向协作。

 ✨ 亮点

| | 特性 | 说明 |
|---|------|------|
| 👥 | 多用户多 Agent 专家团 | 一人管理，全家共用；内置专家库与专家市场，按场景切换专业角色 |
| 🤝 | 云端协作 | 将本机 Octop 连接到另一实例，可浏览对端专家并跨实例对话；对话记录保留在专家所在侧 |
| 🎭 | MBTI 人格 | 16 种人格模板与互动测试，为每个 Agent 赋予鲜明性格 |
| 🎯 | AgentTeams （Beta） | 协调者调度多位专家协作完成多步骤任务；详见 |
| 🔒 | 更安全 | JWT 多用户隔离、工具审批、Shell 命令防护与敏感信息脱敏，数据留在本地 |
| 🔌 | Connector 拓展体系 | 一键接入腾讯全家桶（文档 / 会议 / 新闻等），OAuth 与 MCP 网关轻松扩展 — 支持的连接器 |
| 💾 | 可插拔工作区后端 | 本地目录、Docker 沙箱、PostgreSQL 或 COS/S3 存放 Agent 文件 — 与控制面数据库分离 |
| 🧠 | 可迁移记忆系统 | 基于 Octop Memory，记忆随工作区迁移 |
| 📚 | 知识库 | 基于文档的 RAG 检索；支持同实例共享语料，让回答锚定私有知识 |
| 🧩 | 插件 | 支持第三方插件扩展；内置插件随安装注入，按需一键启用 |
| ↔️ | ACP 双向集成 | octop acp 增强 IDE 与终端 AI；对话中委派 OpenCode / Claude Code 等 |
| 💻 | 终端 AI+ | 浏览器内交互式 Shell，AI 辅助命令执行与排障 |
| 🌐 | 浏览器 AI+ | 基于 Chromium 的无头浏览器会话，支持网页自动化、截图与远程操控 |
| 🖥️ | 远程桌面 | 控制台内实时看屏与键鼠操控，跨 Linux / Windows / macOS；适合远程办公、GUI 软件操作，无图形 Linux 可一键搭建隔离桌面 |
| 🪟 | 桌面客户端 | Windows / macOS / Linux 原生应用，另有飞牛（FnOS）安装包，可与 Web 控制台并行使用 |
| 🏠 | 可自托管 | 一条 octop run 即可运行控制台、CLI、IM 通道与定时任务，数据存于 ~/.octop/ |

 📌 概述

Octop 是面向家庭与小团队的自托管 AI 助手平台。单进程同时提供 Web 控制台、CLI、IM 通道（飞书、钉钉、QQ、微信、企业微信等）与定时任务，共享 ~/.octop/ 下的控制面数据库（默认 SQLite；可选 PostgreSQL）。

 Octop 的设计目标：让每一次对话、工作区与凭据都留在你自己的机器上，同时为每个用户配备一组可按场景切换的专业 Agent。


🐾 你能用 Octop 做什么

- 个人助理 — 让专属 Agent 帮你写周报、整理资料、定日程，记忆随工作区长期保留。
- 家庭共享 — 一个管理员账号，全家共用；按成员分配不同 Agent 与专家角色，也可共享专家与知识库。
- 团队助手 — AgentTeams 或多 Agent 并行协作，对接飞书 / 钉钉 / 企业微信 / 微信，把任务自动分发到群里。
- 开发者增效 — 通过 ACP 把编码任务委派给 OpenCode / Claude Code，或在终端用 AI 辅助排障。
- 网页自动化 — 用浏览器 AI+ 与远程桌面自动填表、截图、操作 GUI 软件。
- 定时任务 — 用自然语言配置 Cron，让 Agent 每天按时推送或执行任务。





 🧠 核心技术

| 层级 | 技术 |
|------|------|
| 语言 | Python 3.12+ |
| Web 框架 | FastAPI + uvicorn |
| Agent 运行时 | Octop Harness |
| IM 桥接 | Octop Gateway |
| 控制平面数据库 | SQLite (WAL，默认) 或 PostgreSQL（可选） |
| 前端 | React 18 + TypeScript + Vite + Ant Design |
| 调度 | APScheduler |
| ACP | agent-client-protocol |
| 构建 / 质量 | hatchling · ruff · mypy · pytest |

Octop 基于一系列 Octop Harness 工程实践构建——它将这些专注的运行时组合进同一个进程：

- Octop Harness — Agent 运行时：模型路由、工具、技能与对话检查点。
- Octop Gateway — 多平台 IM 通道桥接，将各类入站消息归一为统一的处理管线。
- Octop Memory — 分层记忆与全文检索，让 Agent 的记忆随工作区一同迁移。
- Octop Browser — 基于 CDP 的浏览器自动化，支持持久化配置，用于网页类任务。

Octop 不依赖外部消息队列或中间件，而是通过进程内的 HarnessProcessor 统一路由所有入口——Web UI、IM 与定时任务。最终呈现为一个可重启恢复的单进程：启动时整个状态都从控制面数据库重建（默认 ~/.octop/octop.db，亦可配置 PostgreSQL）。

 🤔 功能特性

 服务器与认证
- 多用户 JWT 认证，支持管理员角色
- 首次运行向导（octop init）
- 交互式 API 文档：/api/docs（默认关闭 — 在 config.json 中设置 "enable_api_docs": true 开启）

 专家
- 每位用户可创建多个专家；各自拥有独立工作区、供应商、通道和定时任务
- 16 种 MBTI 人格模板 + 自定义系统提示词
- 启动时扫描专家库（infra/agents/experts/library/）；支持专家市场与同实例专家共享
- Agen