Octop

腾讯云开源的自托管多用户、多 Agent 助手平台，单进程同时提供 Web 控制台、CLI 和飞书/钉钉/QQ/Discord/企业微信等 IM 接入，每个用户可拥有独立工作区和专属 agent 团队。亮点在于把多用户隔离、MBTI 人格模板、专家库、RAG 知识库、cron 定时任务和 Connectors（OAuth + MCP）都塞进一个用 SQLite 落地的进程里，并通过 ACP 双向对接 OpenCode、Claude Code 等编码 agent，还有内置的浏览器自动化和终端 AI 能力。适合家庭或小团队私有化部署，数据与凭证都留在本地 /.octop/。MIT 协议。

README

Octop Banner

更智能的自托管 AI 助手 —— 多用户、多 agent。

亮点 · 概览 · 核心技术 · 功能特性 · 路线图 · 快速开始 · 目录

English · 中文

Octop 是一个开源、自托管的 AI 助手。它不只是一件工具——它是一种能够并行运作的数字生命体。借助多 agent 架构，它为团队、家庭和个人打造了一个既独立又协作的智能环境。最棒的是，它完全运行在你自己的机器上——完全自托管的形态意味着隐私无需任何妥协，而单进程启动让强大的 Web 控制台、CLI 和 IM 集成触手可及。

你可以通过 Web Dashboard、飞书、钉钉、QQ、Discord、企业微信，或程序化的 HTTP/SSE/WebSocket 进行对话。通过 专家库、Connectors（OAuth + MCP）以及用于 IDE 工作流的 ACP 集成扩展能力。

✨ 亮点

	特性	说明
👥	多用户专家团队	一个管理员，全家共享；内置专家库——按场景切换专家
🎭	MBTI 人格	16 种人格模板外加互动测试——为每个 agent 赋予鲜明性格
🔒	内置安全	JWT 多用户隔离、工具审批、shell 命令护栏与 PII 脱敏——数据始终留在本地
🔌	Connector 生态	腾讯全家桶（文档、微博热搜、新闻……）；OAuth 与 MCP 网关拓展资源边界
💾	可插拔后端	本地磁盘、Docker 容器、PostgreSQL 或 COS/S3——AI 在隔离边界内运行
🧠	可迁移记忆	由 harness-memory 驱动；记忆随工作区一同迁移
📚	知识库	基于你的文档进行 RAG；语义检索让 agent 的回答扎根于你的私有语料
🧩	插件	用第三方插件扩展 Octop；内置插件预置并按需启停
↔️	ACP 双向互通	`octop acp` 用于 IDE/终端 AI；在权限关卡下委派给 OpenCode / Claude Code
💻	终端 AI+	浏览器内的交互式 shell——AI 辅助的命令执行与排障
🌐	浏览器 AI+	无头 Chromium 会话，用于 Web 自动化、截图与远程浏览
🖥️	远程桌面	在 Linux、Windows 和 macOS 上从 dashboard 实时查看屏幕并操作输入——支持远程办公与 GUI 应用；在无头 Linux 上一键创建隔离桌面
🏠	自托管	Dashboard、CLI、IM 渠道和 cron 全在一个 `octop run` 中——所有数据都在 `~/.octop/` 下

📌 概览

Octop 是一个面向家庭和小型团队的自托管 AI 助手平台。它以单进程运行，同时提供 Web dashboard、CLI、IM 渠道（飞书、钉钉、QQ、Discord、企业微信等）和 cron 自动化——全部共享 ~/.octop/ 下的同一个控制面数据库（默认 SQLite；可选 PostgreSQL）。

Octop 的设计目标：让每一段对话、每一个工作区和每一份凭证都留在你自己的机器上，同时为每位用户提供一支可按任务切换的专属专家 agent 团队。

🐾 用 Octop 能做什么

个人助理——让专属 agent 写周报、整理笔记、管理日程；记忆随工作区持久保留。
家庭共享——一个管理员账号，全家共用；为每位成员分配不同的 agent 和专家。
团队助手——多个 agent 并行协作，打通飞书 / 钉钉 / 企业微信，将任务路由进群聊。
开发者提效——通过 ACP 把编码任务委派给 OpenCode / Claude Code，或在终端中借助 AI 辅助排障。
Web 自动化——使用 Browser AI+ 填写表单、截图并采集公开信息。
定时任务——用自然语言配置 cron，让 agent 每天准时推送或执行任务。

🧠 核心技术

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

Octop 构建在 Harness 技术栈之上——这是一组专注的运行时，Octop 将它们组合进单个进程：

harness-agent——Agent 运行时：模型路由、工具、技能与对话检查点。
harness-gateway——多平台 IM 渠道桥接，将收到的消息归一化为单一处理流水线。
harness-memory——带全文检索的分层召回，让 agent 的记忆随其工作区一同流转。
harness-browser——基于 CDP 的浏览器自动化，配合持久化 profile 执行 Web 任务。

Octop 不使用外部队列或消息中间件，而是将每个入口面——Web UI、IM 和 cron——都经由进程内的单个 HarnessProcessor 路由。最终得到的是一个可安全重启的单一进程，其全部状态在启动时从控制面数据库重建（默认本地 SQLite；可选 PostgreSQL）。

🤔 功能特性

服务与认证

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

Agents

每个用户可拥有多个 agent；每个 agent 拥有自己的工作区、provider、渠道和 cron
16 种 MBTI 人格模板 + 自定义 system prompt
专家库在启动时扫描（infra/agents/experts/library/）
工作区后端：本地磁盘、COS、S3 及其他远程存储

渠道与自动化

IM 渠道：飞书、钉钉、QQ、Discord、企业微信等
主动式 cron 任务，支持自然语言与斜杠命令触发
跨 Web UI、IM 和 cron 入口面的统一消息处理

入口面

Web dashboard——聊天、agents、connectors、channels、cron、settings
CLI——octop run、octop chat、octop acp、管理命令
HTTP/SSE/WebSocket API——完整的程序化访问

知识与插件

知识库——基于你的文档进行 RAG；上传文件，让语义检索把 agent 的回答扎根于你的私有语料
插件——安装并管理第三方插件（octop plugin）；内置插件预置，可在 dashboard 中按需启停

ACP（Agent Client Protocol）

Octop 以两个方向支持 ACP：

入站（Inbound）——外部工具使用你的 Octop agent

octop acp --agent main   # 面向 Zed、OpenCode 等的 stdio ACP 服务

出站（Outbound）——Octop 委派给外部编码 agent
- Dashboard → ACP（/acp）：配置 runner（按用户全局）
- 为每个 agent 启用 acp_runner，然后在聊天中委派

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

完整配置说明：docs/acp.md。

🧭 路线图

以下是我们中长期的规划：

共享资源池——一个集中的技能与子 agent 资源池，任何用户都能将其放入新的专家中，而无需从零重建。
专家共享——将你的专家发布给同一部署下的其他用户，让优秀的配置被复用而非重复创建。
浏览器与终端打磨——浏览器技能录制（捕获工作流并作为技能回放）以及能力更强的终端 AI 助手。
AgentTeams——让一个协调者自主调度并编排多个专家来处理多步骤任务。
自我进化——自动将日常对话提炼为可复用技能，让助手与你一同成长。
PC / 移动客户端——在 Web dashboard 与 IM 渠道之外，提供原生桌面与移动应用。

随着社区的发展，该路线图可能会调整；请仅将其视为参考。

🚀 快速开始

前置条件

macOS / Linux / Windows
无需预先安装 Python——安装器使用 uv 在 ~/.octop/ 下的隔离 venv 中准备 Python 3.12
现代多核 CPU，数 GB 内存用于进程及模型/embedding 缓存；足够的磁盘空间用于数据库、agent 工作区和文档语料

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
# or
source ~/.bashrc  # Bash

安装器会将 octop 通过 ~/.octop/bin 放入你的 PATH。可选扩展：

# Browser automation (Playwright Chromium)
curl -fsSL https://finnie-1258344699.cos.ap-guangzhou.myqcloud.com/octop/install.sh | bash -s -- --extras browser

# Feishu channel support
curl -fsSL https://finnie-1258344699.cos.ap-guangzhou.myqcloud.com/octop/install.sh | bash -s -- --extras channels-feishu

所有安装选项（--version、--from-source、--mirror、Windows 参数）见 scripts/README.md。

桌面应用（GUI，无需终端）——从 GitHub Releases 下载对应平台的产物：

平台	产物
Windows	`Octop-desktop-windows-amd64-<version>.exe`（64 位）/ `Octop-desktop-windows-arm64-<version>.exe`（ARM64）—— NSIS 安装器
macOS	`Octop-desktop-darwin-arm64-<version>.dmg`（Apple Silicon）/ `Octop-desktop-darwin-amd64-<version>.dmg`（Intel）
Linux	`Octop-desktop-linux-amd64-<version>.tar.gz` / `Octop-desktop-linux-arm64-<version>.tar.gz`
FnOS NAS	`Octop-fnos-docker-<version>.fpk`（基于 Docker）/ `Octop-fnos-native-<version>.fpk`（无需 Docker）—— 通过 App Center 安装

桌面 shell 说明见 desktop/README.md，FnOS 打包指南见 fnos/README.md。

备选方案——PyPI（如果你自己管理 Python）：

pip install octop
# optional: pip install "octop[browser]"
# optional local ONNX embedding model cache (Models → Local): pip install "octop[local-embedding]"
# Downloads catalog weights under ~/.octop/embedding_models; not chat, not Memory.

从源码检出并使用 uv：

uv sync --extra local-embedding

2. 初始化

octop init

交互式向导会在 ~/.octop/ 下创建 SQLite 数据库、JWT 密钥和首个管理员账号。

3. 运行

# Foreground (API + Web dashboard)
octop run

# Custom host / port
octop run --host 0.0.0.0 --port 8088

# Register as a system service (systemd / launchd / Windows service)
octop service start

打开 http://127.0.0.1:8088。使用 Docker 时，首次初始化会生成随机管理员密码（写入 /data/.octop/credential.txt），除非设置了 OCTOP_DEFAULT_PASSWORD。交互式的 octop init / 设置向导会要求你选择密码（≥8 个字符，包含字母和数字）。

Docker（生产环境推荐）

# Build and start
docker compose -f docker/docker-compose.yml up -d

# Or build manually
bash docker/docker_build.sh
docker run -d \
  -p 8088:8088 \
  -v octop-data:/data/.octop \
  -e HOME=/data \
  -e OCTOP_DEFAULT_PASSWORD="<strong-password-or-omit-for-random>" \
  octop:latest

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

密码策略： 至少 8 个字符，包含字母和数字。

变量	默认值	说明
`OCTOP_PORT`	`8088`	HTTP 监听端口
`OCTOP_DEFAULT_PASSWORD`	（未设置）	首次运行的管理员密码（Docker 引导）。未设置 = 随机密码写入 `credential.txt`
`OCTOP_ADMIN_USERNAME`	`admin`	首次运行的管理员用户名
`OCTOP_DATA`	`~/.octop`	宿主数据目录（compose 绑定挂载）

完整列表见 .env.example。

📑 目录

亮点
概览
核心技术
功能特性
路线图
快速开始
部署与使用
架构与开发
项目信息

📦 安装选项

方式	平台	说明
远程一行命令	macOS / Linux	`curl …/octop/install.sh \| bash`
远程一行命令	Windows	`irm …/octop/install.ps1 \| iex` 或 `install.bat`
本地脚本	macOS / Linux	`bash scripts/install.sh`
本地脚本	Windows	`scripts\install.bat` 或 `install.ps1`
PyPI	任意平台	`pip install octop` 或 `pip install "octop[browser]"`
Docker	任意平台	`docker/docker-compose.yml`

所有安装脚本都会在 ~/.octop/venv 下准备隔离环境，并提供 ~/.octop/bin/octop 包装器——它们不会触碰系统 Python。

升级

octop update 只替换 wheel/二进制文件——你的 ~/.octop/ 数据库、工作区、密钥和 config.json 都会保留：

octop update          # fetch and install the latest octop, then restart the service if one is registered

下次启动时 schema 会自动迁移；仅当设置向导提示需要迁移时才运行 octop init。跨版本升级前请务必先备份（octop backup）。

⚙️ 配置

所有运行时状态都位于 ~/.octop/。可通过 CLI 管理，也可直接编辑文件。

# LLM providers and models
octop models
octop provider list

# IM channels
octop channel list
octop channel install

# Skills (per agent)
octop skills list --agent main

# Cron jobs
octop cron list
octop cron create --help

# Users (admin)
octop user list

支持的 LLM provider

OpenAI 兼容 API、DashScope（Qwen）、Ollama 以及其他预设——可在 dashboard 中按 agent 配置，或通过 octop provider 配置。

支持的渠道

渠道	凭证
飞书	App ID、App Secret
钉钉	App Key、App Secret
QQ	Bot AppID、Token
Discord	Bot Token
企业微信	Corp ID、Agent Secret
Web Dashboard	默认启用

📖 CLI 参考

命令	说明
`octop init`	引导 `~/.octop/`（数据库、管理员、JWT 密钥）
`octop run`	在前台启动 Octop
`octop service start`	安装并作为系统服务启动
`octop service stop`	停止系统服务
`octop agent`	创建、列出、启动/停止 agent
`octop channel`	安装并管理 IM 渠道
`octop chats`	REPL 与会话管理
`octop acp`	用于 IDE 集成的 stdio ACP 服务
`octop cron`	管理定时任务
`octop models`	Provider 预设与模型解析
`octop skills`	按 agent 启用/禁用技能
`octop plugin`	安装并管理第三方插件
`octop backup`	导出 / 恢复备份
`octop clean`	移除 CLI 状态或清空 `~/.octop/`
`octop update`	检查并安装更新

完整参考：docs/cli.md。

🖥️ Web dashboard

执行 octop run 后，打开 http://127.0.0.1:8088。

Octop Web Dashboard

Chat——与 agent 实时对话
Agents——创建 agent，选择专家 / MBTI 人格，配置 provider
Connectors——OAuth 应用与 MCP 网关
Channels——IM 平台配置
Cron——可视化的 cron 任务管理
知识库——管理文档语料与语义检索
Plugins——安装、启用与配置插件
ACP——配置出站编码 agent runner
Settings——用户、安全、TLS、系统

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

📁 数据目录

~/.octop/                          ← install & data root
├── config.json                    # process config (optional database section)
├── octop.db                       # SQLite — users, agents, channels, cron, …
├── secrets/                       # JWT secret, channel tokens
├── agents/<agent_id>/             # per-agent workspace (SOUL.md, skills, …)
├── security/tool_guard/           # shell command allow/deny rules
├── logs/                          # runtime logs
├── venv/                          # uv-managed Python (installer layout)
└── bin/octop                      # PATH wrapper → venv/bin/octop

控制面也可以使用 PostgreSQL——在 config.json 中设置 database，或使用 OCTOP_DATABASE_* / 首次运行向导。使用 PostgreSQL 时，agent 记忆默认复用同一 DSN（按 agent 划分 schema）；若想保留基于文件的记忆，请在 agent 配置中设置 "memory": { "backend": { "type": "sqlite" } }。参见 docs/configuration.md 和 docs/adr/002-database-backends.md。

环境变量与 config.json 说明见 docs/configuration.md。

🏗️ 架构

OctopServer
 ├─ DatabasePool            SQLite (WAL) or PostgreSQL
 ├─ SharedServices       DI root — every repo + config
 ├─ ExpertCatalog        scans agents/experts/library/ at boot
 ├─ UserManager
 │   └─ HarnessAgentManager (per user)
 │       └─ AgentRuntime (per agent)
 │           ├─ HarnessAgent      Agent runtime (harness-agent)
 │           ├─ HarnessProcessor  IM / UI / cron entry point
 │           ├─ ChannelManager    IM connections (harness-gateway)
 │           └─ CronManager       APScheduler
 └─ FastAPI app (uvicorn)

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

参见 docs/architecture.md、docs/adr/001-single-process-model.md 和 docs/adr/002-database-backends.md。

📁 项目结构

src/octop/
  config.py    env-var config
  launch.py    OctopServer boot + uvicorn
  infra/       business core (agents, gateway, cron, db, users, …)
  api/         HTTP layer — FastAPI app, routers, JWT, SSE
  cli/         CLI layer — Click commands
  dashboard/   built React SPA (wheel artifact)

dashboard/     frontend source (Vite) — edit here, run make build-frontend

docker/        Docker Compose, entrypoint, build & deploy scripts
tests/         unit/ + integration/

🛠️ 开发

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

# Backend
make install          # pip install -e ".[dev]"
make all              # format-all + lint + typecheck + test (ship bar)

# Frontend (separate terminal)
make dev-frontend     # Vite dev server on :5173 (override with VITE_DEV_PORT)
make build-frontend   # production build → src/octop/dashboard/
cd dashboard && npx tsc --noEmit

单项 make 目标：make test、make lint、make typecheck、make format。

🔒 安全与隐私

本地优先：配置、聊天、工作区和凭证都存放在你机器上的 ~/.octop/ 中。
多用户隔离：JWT 认证，按用户隔离 agent 与工作区。
PII 脱敏与工具审批：敏感数据在离开工作区前会被脱敏，风险工具或 shell 命令需在护栏规则下获得明确批准。
工具护栏：用户可编辑的 shell 命令规则位于 ~/.octop/security/tool_guard/。
无供应商锁定：可自由更换 LLM provider、存储后端和渠道，而无需重写 agent。

🤝 贡献

欢迎贡献：

Fork 仓库
创建功能分支（git checkout -b feature/amazing-feature）
提交前运行 make all（后端）或 make check-all（全栈）
提交 Pull Request

完整指南见 CONTRIBUTING.md。安全问题请见 SECURITY.md。

模块边界与编码规范：AGENTS.md。

📋 更新日志

发布历史见 CHANGELOG.md。

🔗 相关项目

项目	说明
harness-agent	Agent 运行时——模型路由、工具、技能、检查点
harness-gateway	多平台 IM 渠道桥接
harness-memory	分层召回与全文检索
harness-browser	基于 CDP 的浏览器自动化，配合持久化 profile

这些 harness-* 项目正在准备开源；仓库链接将在发布后补充。

💬 企业微信客户群

企业微信客服群请扫码：

WeCom customer group QR code

请扫描二维码加入群聊。如有任何问题或需要帮助，请直接联系群管理员。

📄 许可证

本项目采用 MIT License 许可。

✨ 贡献者

感谢所有贡献者：

开源项目TencentCloud2026-09-17原文

打开互动版