推荐一个自托管的 AI 助手开源项目

一、项目简介

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

项目代码仓库地址，在文章末尾。

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

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

二、项目亮点

你能用它做什么

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

三、项目技术栈

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

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

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

四、功能特性

服务器与认证

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

Agent

• 每位租户可创建多个 Agent；各自拥有独立工作区、供应商、通道和定时任务
• 16 种 MBTI 人格模板 + 自定义系统提示词
• 启动时扫描专家库（infra/agents/experts/library/）
• 工作区后端：本地磁盘、COS、S3 及其他远程存储

通道与自动化

• IM 通道：飞书、钉钉、QQ、Discord、企业微信等
• 主动定时任务，支持自然语言和斜杠命令触发
• Web UI、IM、定时任务共用同一套消息处理链路

使用入口

• Web 控制台 — 对话、Agent 管理、连接器、通道、定时任务、设置
• CLI — octop run、octop chat、octop acp、管理命令
• HTTP/SSE/WebSocket API — 完整的程序化访问能力

知识库与插件

• 知识库 — 基于文档的 RAG 检索；上传文件后，语义检索让 Agent 的回答锚定你的私有知识库
• 插件 — 安装并管理第三方插件（octop plugin）；内置插件随安装注入，按需在控制台一键启用

ACP（Agent Client Protocol）

Octop 支持两个方向的 ACP 集成：

1. 入站 — 外部工具使用你的 Octop Agent

   octop acp --agent main   # 为 Zed、OpenCode 等提供 stdio ACP 服务
   

2. 出站 — Octop 委派给外部编程 Agent

   • 控制台 → ACP（/acp）：配置 Runner（按用户全局）
   • 为 Agent 启用 acp_runner 后，在对话中委派任务

内置出站 Runner 包括 OpenCode、CodeBuddy、Claude Code 和 Codex。

五、支持多种AI大模型供应商

OpenAI 兼容 API、DashScope（千问）、Ollama 等预设 — 在控制台或通过 octop provider 按 Agent 配置。

六、支持的通道

七、项目架构

OctopServer
 ├─ DatabasePool         SQLite (WAL) 或 PostgreSQL
 ├─ SharedServices       依赖注入根 — 所有 repo 与配置
 ├─ ExpertCatalog        启动时扫描 agents/experts/library/
 ├─ UserManager
 │   └─ HarnessAgentManager（按用户）
 │       └─ AgentRuntime（按 Agent）
 │           ├─ HarnessAgent      Agent 运行时（harness-agent）
 │           ├─ HarnessProcessor  IM / UI / 定时任务入口
 │           ├─ ChannelManager    IM 连接（harness-gateway）
 │           └─ CronManager       APScheduler
 └─ FastAPI app (uvicorn)

单进程架构。重启后从控制面数据库重建状态（默认本地 SQLite；可选 PostgreSQL）。

八、项目目录结构

src/octop/
  config.py    环境变量配置
  launch.py    OctopServer 启动 + uvicorn
  infra/       业务核心（agents、gateway、cron、db、users …）
  api/         HTTP 层 — FastAPI 路由、JWT、SSE
  cli/         CLI 层 — Click 命令
  dashboard/   构建后的 React SPA（wheel 产物）

dashboard/     前端源码（Vite）— 在此编辑，运行 make build-frontend

docker/        Docker Compose、入口脚本、构建与部署脚本
tests/         unit/ + integration/

九、快速开始

环境要求

• macOS / Linux / Windows
• 无需预先安装 Python — 安装脚本通过 uv 在 ~/.octop/ 下创建隔离的 Python 3.12 虚拟环境
• 现代多核 CPU，并预留数 GB 内存供进程与模型/Embedding 缓存使用；磁盘需容纳数据库、Agent 工作区与文档语料

支持多种安装方式

所有安装脚本均在 ~/.octop/venv 创建隔离环境，并通过 ~/.octop/bin/octop 包装 CLI，不会影响系统 Python。

本地开发

前置条件： Python 3.12+、Node 18+、uv

# 后端
make install          # pip install -e ".[dev]"
make all              # format-all + lint + typecheck + test（发布门槛）

# 前端（另开终端）
make dev-frontend     # Vite 开发服务器 :5173
make build-frontend   # 生产构建 → src/octop/dashboard/
cd dashboard && npx tsc --noEmit

单独执行：make test、make lint、make typecheck、make format。

1. 本地启动

# 前台运行（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。Docker 首次初始化会自动生成随机管理员密码（写入 /data/.octop/credential.txt），除非设置了 OCTOP_DEFAULT_PASSWORD。交互式 octop init / 设置向导会让你自行设置密码（至少 8 位，且同时包含字母和数字）。

2、Docker（推荐用于生产部署）

# 构建并启动
docker compose -f docker/docker-compose.yml up -d

# 或手动构建
bash docker/docker_build.sh
docker run -d \
  -p 8088:8088 \
  -v octop-data:/data/.octop \
  -e HOME=/data \
  -e OCTOP_DEFAULT_PASSWORD="<自定义强密码，留空则自动生成随机密码>" \
  octop:latest

打开 http://localhost:8088。首次初始化会创建管理员账号，并把凭据写入容器内 /data/.octop/credential.txt。未设置 OCTOP_DEFAULT_PASSWORD 时自动生成随机强密码；自行设置的密码须 ≥8 位且同时包含字母和数字（被应用密码策略拒绝的常见弱密码会自动回退为随机密码）。可通过 OCTOP_ADMIN_USERNAME 覆盖用户名。

密码策略： 至少 8 位，且同时包含字母和数字。

数据目录

~/.octop/                          ← 安装与数据根目录
├── config.json                    # 进程配置（含可选 database 段）
├── octop.db                       # 默认 SQLite 控制面（用户、Agent、通道、定时任务 …）
├── secrets/                       # JWT 密钥、通道 Token
├── agents/<agent_id>/             # 各 Agent 工作区（SOUL.md、skills …）
├── security/tool_guard/           # Shell 命令允许/拒绝规则
├── logs/                          # 运行日志
├── venv/                          # uv 管理的 Python（安装脚本布局）
└── bin/octop                      # PATH 包装脚本 → venv/bin/octop

控制面也可改用 PostgreSQL（config.json → database，或 OCTOP_DATABASE_* / 首次设置向导）。控制面为 PostgreSQL 时，Agent 记忆默认复用同一 DSN（per-agent schema）；若需继续用文件记忆，在 agent 配置里设 "memory": { "backend": { "type": "sqlite" } }。

Web 控制台

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

• 对话 — 与 Agent 实时聊天
• Agent — 创建 Agent，选择专家库 / MBTI 人格，配置供应商
• Connector — OAuth 应用与 MCP 网关
• 通道 — IM 平台配置
• 定时任务 — 可视化 Cron 管理
• 知识库 — 管理文档语料与语义检索
• 插件 — 安装、启用与配置插件
• ACP — 配置出站编程 Agent Runner
• 设置 — 用户、安全、TLS、系统

交互式 API 文档：http://127.0.0.1:8088/api/docs（默认关闭 — 在 config.json 中设置 "enable_api_docs": true 开启）

十、项目代码仓库地址

项目代码仓库地址: https://github.com/TencentCloud/Octop