ghcr.io/tencentcloud/octop:0.9.30

镜像名称：ghcr.io/tencentcloud/octop 参考标签：latest

一款更智能的自托管 AI 助手——支持多用户、多智能体。

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

English · 中文

---

Octop 是一款开源的自托管 AI 助手。它不只是一个工具，更是一套可并行运行的数字生命形态。通过多智能体架构，它能为团队、家庭和个人搭建既相互独立又可协同的智能环境。最核心的优势是它完全在你的本地设备上运行——全自托管的设计绝不会牺牲隐私，同时单进程启动的特性也能让你便捷使用功能完备的 Web 控制台、CLI 和即时通讯集成能力。

你可以通过 Web 仪表盘、飞书、钉钉、QQ、微信、、、企业微信发起对话，也可以通过 HTTP/SSE/WebSocket 以编程方式调用。你还可以通过专家库、Connectors（OAuth + MCP）以及面向 IDE 工作流的 ACP 集成扩展它的能力边界。

✨ 功能亮点

📌 概览

Octop 是面向家庭与小型团队的自托管 AI 助手平台。它以单进程模式运行，对外提供 Web 仪表盘、CLI、即时通讯渠道（飞书、钉钉、QQ、微信、、、企业微信等）和定时自动化能力，所有组件共用位于 ~/.octop/ 下的同一个控制平面数据库（默认使用 SQLite，也可选择 PostgreSQL）。

Octop 的设计目标：让所有对话、工作区和凭证都保存在你自己的设备上，同时让每个用户都能拥有一支可随任务灵活切换的专属专业智能体团队。

🐾 Octop 可实现的场景：

• 个人助理 — 安排专属智能体撰写周报、整理笔记、管理日程；记忆数据会随工作区持久留存。
• 家庭共享 — 只需一个管理员账号，全家即可共用；可为每位成员分配不同的智能体与专家，需要时还能共享专家和知识库。
• 团队帮手 — 通过 AgentTeams 或并行智能体，对接飞书/钉钉/企业微信/微信，直接将任务路由到群聊中处理。
• 开发提效 — 通过 ACP 将编码任务委派给 OpenCode / Claude Code，也可在 AI 辅助下直接在终端完成故障排查。
• 网页自动化 — 借助 Browser AI+ 和远程桌面能力自动填写表单、截图、操作 GUI 应用。
• 定时任务 — 使用自然语言配置 cron 规则，智能体会按照设定的时间自动推送通知或执行任务。

🧠 核心技术

Octop 基于 Octop Harness 技术栈构建——这是一组经过专注优化的运行时组件，Octop 将它们编排到同一个进程内运行：

• https://github.com/TencentCloud/octop-harness — 智能体运行时：负责模型路由、工具调用、技能执行与对话断点续传。
• https://github.com/TencentCloud/octop-gateway — 多平台即时通讯渠道桥接组件，可将不同渠道的入站消息统一标准化到单一流水线处理。
• https://github.com/TencentCloud/octop-memory — 支持全文检索的分层回忆引擎，让智能体的记忆数据可以随工作区一同迁移。
• https://github.com/TencentCloud/octop-browser — 基于 CDP 的浏览器自动化组件，可为网页任务提供持久化用户配置文件。

Octop 没有使用外部队列或消息代理，所有入口（Web UI、即时通讯、定时任务）的流量都通过进程内的 HarnessProcessor 完成路由。最终实现了单进程、支持安全重启的运行模式，进程启动时会从控制平面数据库（默认本地 SQLite，可选 PostgreSQL）中重建全部状态。

🤔 特性

服务器与身份认证

• 支持带管理员角色的多用户 JWT 身份认证
• 提供首次运行配置向导（octop init）
• 交互式 API 文档托管在 /api/docs 路径下（默认关闭，可在 config.json 中设置 "enable_api_docs": true 开启）

专家智能体

• 单个用户可创建多名专家智能体，每个智能体拥有独立的工作区、模型配置、渠道绑定与定时任务
• 内置 16 套 MBTI 人格模板，同时支持自定义系统提示词
• 启动时自动扫描位于 infra/agents/experts/library/ 路径下的专家库；支持专家市场与同实例内的专家共享
• AgentTeams (测试版) — 通过协调者 + 成员专家的模式处理多步骤任务，详情参见 docs/expert-teams.md
• 工作区后端（智能体文件存储）：支持本地磁盘、Docker 沙箱、PostgreSQL、COS/S3 等多种远程存储，与控制平面数据库完全独立

渠道与自动化

• 即时通讯渠道：支持飞书、钉钉、QQ、微信、、、企业微信等多种平台
• 支持自然语言触发与斜杠命令触发的主动定时任务
• 在 Web 界面、即时通讯渠道、定时任务场景下实现统一消息处理

交互入口

• Web 仪表盘 — 内置聊天会话、专家/团队管理、连接器配置、渠道设置、定时任务管理、知识库、插件管理、系统设置等全功能模块
• 桌面客户端 — 面向 Windows / macOS / Linux 的原生应用；同时提供适配 NAS 的 FnOS 安装包
• CLI 命令行 — 支持 octop run、octop chats、octop acp 等常规操作及管理员命令
• HTTP/SSE/WebSocket API — 提供完整的可编程访问能力
• 远程桌面控制 — 可通过仪表盘直接管控主机桌面会话

知识库与插件

• 知识库 — 基于自有文档实现 RAG 检索增强生成；支持在同一部署实例内选择性共享知识库
• 插件 — 可通过 octop plugin 命令安装和管理第三方插件；内置预置插件可直接在仪表盘按需开启使用

ACP（Agent Client Protocol，智能体客户端协议）

Octop 支持双向 ACP 能力：

1. 入向调用 — 外部工具可直接调用你部署的 Octop 智能体

octop acp --agent main # 为 Zed、OpenCode 等工具提供 stdio 标准输入输出模式的 ACP 服务端

2. 出向调用 — Octop 可将任务委托给外部编码智能体执行

• 仪表盘路径 → ACP（/acp 页面）：配置全局用户级别的运行器
• 为指定智能体开启 acp_runner 权限后，即可在聊天会话中调用外部编码智能体完成任务

内置的出向调用运行器包含 OpenCode、CodeBuddy、Claude Code 和 Codex。 完整部署说明请参考 docs/acp.md。

🧭 路线图

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

已上线

• 共享资源池 — 集中存储技能与子智能体的公共池，任意用户均可直接将其加入新专家配置，无需从零开始重复搭建
• 专家共享 — 可将你创建的专家发布给同一部署实例内的其他用户，优质配置可直接复用，无需重复创建
• PC 客户端 — 除 Web 仪表盘和即时通讯渠道外，同时提供 Windows / macOS / Linux 平台的原生桌面应用

开发中

• AgentTeams（智能体团队）（Beta 阶段） — 由协调器自主调度编排多个专家智能体，共同处理多步骤复杂任务
• 移动端客户端（封闭测试） — 原生移动应用目前正在进行内部测试

规划中

• 浏览器与终端体验优化 — 新增浏览器技能录制能力（可捕获工作流并将其复用作自定义技能），同时提供能力更强大的终端 AI 助手
• 自演进能力 — 自动将日常对话内容提炼为可复用技能，让助手随你的使用持续成长
• 托管智能体服务 — 平台侧托管智能体全生命周期管理，无需自行维护完整的自托管技术栈即可完成智能体的部署、扩缩容和运维
• 项目空间 — 以共同目标为核心的项目级工作区，可将相关智能体、文件和会话统一归集管理
• 云边协同能力 — Octop 本地运行时可将指定任务分流至云端处理，轻量任务直接在本地设备执行，资源需求高的任务可按需调用云端算力
• 插件市场 — 提供精选插件集市，无需离开 Octop 即可发现、安装和更新第三方插件
• 会话式控制平面 — 深度扩展 Octop 自身能力，通过聊天操作即可覆盖仪表盘全部功能：创建专家、配置渠道、管理知识库、端到端生成插件脚手架

本路线图会随社区发展动态调整，仅作参考用途。

🚀 快速开始

前置依赖

• 支持 macOS / Linux / Windows 全平台
• 无需预先安装 Python — 安装器会通过 uv 在 ~/.octop/ 路径下的独立虚拟环境中自动部署 Python 3.12
• 配备现代多核 CPU，预留数 GB 内存供进程、模型及嵌入向量缓存使用；同时准备足够磁盘空间用于存储数据库、智能体工作区和文档语料库

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 命令通过 ~/.octop/bin 路径加入系统环境变量。可选附加安装项：

# 下载用于浏览器自动化的 Playwright Chromium 组件（若系统已存在 Chrome/Chromium 则自动跳过该步骤）
curl -fsSL https://finnie-1258344699.cos.ap-guangzhou.myqcloud.com/octop/install.sh | bash -s -- --extras browser

所有安装参数（--version、--from-source、--mirror 及 Windows 平台专属参数）可参考 scripts/README.md。

桌面应用（GUI 图形化，无需终端环境） — 从 https://github.com/TencentCloud/Octop/releases/latest 下载对应平台的安装包：

桌面端开发说明请参考 desktop/README.md，FnOS 打包指南请参考 fnos/README.md。

备选安装方式 — PyPI 包（适用于你已自行管理 Python 环境的场景）：

pip install octop
# 可选本地 ONNX 嵌入向量模型缓存（配置路径：设置 → 本地模型）：执行 pip install "octop[local-embedding]"
# 该操作会将目录权重文件下载至 ~/.octop/embedding_models 路径，不包含对话相关模型与记忆功能组件
# 浏览器自动化基于内置 Playwright 包实现；可通过安装器 --extras browser 参数、仪表盘设置，或下方命令安装 Chromium：
# python -m playwright install chromium

通过 uv 从源码签出版本安装：

uv sync --extra local-embedding

2. 初始化

octop init

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

3. 运行

# 前台启动（同时启用 API 服务 + Web 仪表盘）
octop run

# 自定义访问地址与端口
octop run --host 0.0.0.0 --port 8088

# 注册为系统后台服务（自动适配 systemd / launchd / Windows 服务机制）
octop service start

启动完成后访问 [*] 即可使用。若通过 Docker 部署，配置合法的 OCTOP_DEFAULT_PASSWORD 环境变量后，系统会在首次启动时自动创建管理员账户（账户凭据存放在 /data/.octop/credential.txt 中）；若该环境变量未设置或校验不通过，可访问初始化向导页面完成配置，解锁密码存放在 /data/.octop/octop-login.txt 中。交互式 octop init 命令和初始化向导会要求你设置符合要求的密码（至少 8 位，需同时包含字母和数字）。

Docker 部署（生产环境推荐方案）

# 构建镜像并后台启动服务
docker compose -f docker/docker-compose.yml up -d

# 当 ghcr.io 无法访问时使用中国镜像（无需本地构建）
docker compose -f docker/docker-compose.cn.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。有效的 OCTOP_DEFAULT_PASSWORD 会在首次启动时创建管理员账号，并将凭据写入 /data/.octop/credential.txt。如果未设置该变量，或密码不符合密码策略，系统将不会创建管理员账号 — 此时请完成安装向导（解锁密码位于 /data/.octop/octop-login.txt）。你可以通过 OCTOP_ADMIN_USERNAME 覆盖默认用户名。

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

完整变量列表请参考 .env.example。

如需在反向代理子路径下运行仪表板（例如 https://example.com/octop/），请使用 VITE_BASE_PATH=/octop/ 重新构建前端，并在代理配置中去除该路径前缀（nginx 配置为 proxy_pass …/;）。默认构建版本假定服务部署在域名根路径下。

通过云平台部署

📑 目录

• 亮点
• 概述
• 核心技术栈
• 功能特性
• 路线图
• 快速开始
• 部署与使用
• 安装选项
• 配置
• CLI 参考
• Web 仪表板
• 数据目录
• 架构与开发
• 架构说明
• 项目结构
• 开发指南
• 项目信息
• 安全与隐私
• 贡献指南
• 更新日志
• 相关项目
• 社区
• 许可证

📦 安装选项

所有安装脚本都会在 ~/.octop/venv 下创建独立运行环境，并生成位于 ~/.octop/bin/octop 的启动封装脚本，不会修改系统自带的 Python 环境。

升级

执行 octop update 仅会替换 wheel 包或二进制程序，你的 ~/.octop/ 目录下的数据库、工作区、密钥和 config.json 都会被完整保留：

octop update # 获取并安装最新版 octop，若已注册系统服务则自动重启服务

下次启动时程序会自动完成数据库 schema 迁移，仅当安装向导提示需要迁移时才需要手动执行 octop init。跨大版本升级前请务必先执行备份操作（octop backup）。

⚙️ 配置

所有运行时状态都存储在 ~/.octop/ 目录下，你可以通过 CLI 命令管理，也可以直接编辑对应配置文件。

# 管理 LLM 服务商与模型
octop models
octop provider list

# 管理即时通讯渠道
octop channel list
octop channel install

# 管理技能（按 Agent 维度）
octop skills list --agent main

# 管理定时任务
octop cron list
octop cron create --help

# 管理用户（管理员权限）
octop user list

支持的 LLM 服务商

兼容 OpenAI 协议的 API、通义千问（DashScope）、Ollama 等预设服务商均可使用，你可以在仪表板中按 Agent 单独配置，也可以通过 octop provider 命令操作。

支持的通信渠道

其他渠道类型（例如元宝、小艺、MQTT）可通过网关扩展接入，具体配置方式请查看仪表板或 CLI 中的渠道设置向导。

支持的连接器

内置 OAuth / MCP 连接器包括腾讯文档、腾讯会议、Notion、TickTick、OpenAlex、飞书 CLI、企业微信 CLI、Agent 邮件、Obsidian、WeKnora、Dify 等，所有名称与描述均提供中英文本地化支持。

完整目录、授权方式和 MCP 模式说明请查看 docs/connectors.md。自定义 MCP 服务器可直接在仪表板中添加。

📖 CLI 参考

在已登录的仪表板或本地 CLI 聊天中，输入 /memory slim 可以查看当前 Agent 的内存维护说明；输入 /memory slim --all 可以列出所有符合条件的 Agent。添加 --confirm 参数即可在查看影响范围后启动维护任务。使用 /memory status 可查看进度与结果。在确认并启动维护任务前，聊天功能始终保持可用。外部即时通讯渠道的维护功能需要验证发送者权限，目前尚未开放。

完整 CLI 参考请查看 docs/cli.md。

🖥️ Web 仪表板

执行 octop run 启动后，打开浏览器访问 [*] 即可使用。

• Chat — 与专家及团队进行实时对话
• Experts — 创建专家角色，选择模板/MBI 人格设定，分享或发布专家角色，配置服务提供商
• AgentTeams (Beta) — 由协调专家和成员专家组成，用于处理多步骤任务
• Connectors — OAuth 应用与 MCP 网关
• Channels — 即时通讯平台配置
• Cron — 可视化定时任务管理
• Knowledge base — 管理文档语料库、语义检索与部署内共享
• Plugins — 安装、启用与配置插件
• Remote desktop — 在仪表盘内实时查看屏幕并进行输入操作
• ACP — 配置出站编码代理运行器
• Settings — 用户、安全、TLS 与系统相关配置

交互式 API 文档：[*]（默认禁用 — 可在 config.json 中设置 "enable_api_docs": true 启用）

📁 数据目录

~/.octop/ ← 安装与数据根目录
├── config.json # 进程配置（可选数据库配置段）
├── octop.db # SQLite — 存储用户、代理、频道、定时任务等数据
├── secrets/ # JWT 密钥、频道令牌
├── agents/ / # 每个代理的独立工作目录（包含 SOUL.md、技能等文件）
├── security/tool_guard/ # shell 命令允许/拒绝规则
├── logs/ # 运行时日志
├── venv/ # uv 管理的 Python 环境（安装器默认布局）
└── bin/octop # PATH 包装脚本 → 指向 venv/bin/octop

控制平面也可使用 PostgreSQL — 可在 config.json 中设置 database 参数，或通过 OCTOP_DATABASE_* 系列环境变量、首次运行向导完成配置。使用 PostgreSQL 时，代理内存默认复用同一 DSN（按代理划分独立 Schema）；若需保留基于文件的内存存储，可在代理配置中设置 "memory": { "backend": { "type": "sqlite" } }。更多细节请参考 docs/configuration.md 和 docs/adr/002-database-backends.md。

环境变量与 config.json 的完整说明请参考 docs/configuration.md。

🏗️ 架构

OctopServer
├─ DatabasePool SQLite (WAL) 或 PostgreSQL
├─ SharedServices DI 根容器 — 包含所有数据仓库与配置
├─ ExpertCatalog 启动时扫描 agents/experts/library/ 目录
├─ UserManager
│ └─ HarnessAgentManager（按用户隔离）
│ └─ AgentRuntime（按代理隔离）
│   ├─ HarnessAgent 代理运行时（octop-harness）
│   ├─ HarnessProcessor 即时通讯 / UI / 定时任务入口
│   ├─ ChannelManager 即时通讯连接管理（octop-gateway）
│   └─ CronManager APScheduler 定时任务调度器
└─ FastAPI 应用（基于 uvicorn 运行）

Octop 采用单进程架构。服务重启时会从控制平面数据库重建状态（默认使用本地 SQLite，也可选择配置 PostgreSQL）。

更多细节请参考 docs/architecture.md、docs/adr/001-single-process-model.md 和 docs/adr/002-database-backends.md。

📁 项目布局

src/octop/
config.py 环境变量配置
launch.py OctopServer 启动逻辑 + uvicorn 服务启动
infra/ 业务核心模块（代理、网关、定时任务、数据库、用户管理等）
api/ HTTP 层 — FastAPI 应用、路由、JWT 认证、SSE 服务
cli/ CLI 层 — Click 命令集合
dashboard/ 已构建的 React SPA 产物（wheel 包构件）

dashboard/ 前端源码（基于 Vite）— 在此处编辑，执行 make build-frontend 完成构建

docker/ Docker Compose 配置、入口脚本、构建与部署脚本
tests/ 单元测试 + 集成测试

🛠️ 开发环境

前置依赖： Python 3.12+、Node 18+、uv

# 后端开发
make install # pip install -e ".[dev]"
make all # 格式化全量代码 + 代码检查 + 类型检查 + 测试（发布前校验标准）

# 前端开发（开启独立终端运行）
make dev-frontend # Vite 开发服务器默认运行在 :5173 端口（可通过 VITE_DEV_PORT 变量覆盖）
make build-frontend # 生产环境构建 → 产物输出到 src/octop/dashboard/
cd dashboard && npx tsc -b

独立可执行目标：make test、make lint、make typecheck、make format。

🔒 安全与隐私

• 本地优先： 配置、聊天记录、工作区与凭证全部存储在你本地机器的 ~/.octop/ 目录下。
• 多用户隔离： 基于 JWT 认证，不同用户的代理与工作区完全隔离。
• PII 脱敏与工具审批： 敏感数据在离开工作区前会被自动脱敏，高风险工具或 shell 命令需要在护栏规则下获得显式审批才能执行。
• 工具护栏： 用户可在 ~/.octop/security/tool_guard/ 目录下自行编辑 shell 命令规则。
• 无厂商锁定： 无需重写代理逻辑即可自由切换 LLM 服务商、存储后端与通讯频道。

🤝 贡献

欢迎所有形式的贡献：

1. Fork 本仓库
2. 创建功能分支（执行 git checkout -b feature/amazing-feature）
3. 提交前运行 make all（后端）或 make check-all（全栈）完成校验
4. 提交 Pull Request

完整贡献指南请参考 CONTRIBUTING.md。安全问题反馈请参考 SECURITY.md。

模块边界与编码规范请参考 AGENTS.md。

📋 更新日志

发布历史请查看 CHANGELOG.md。

🔗 相关项目

💬 社区

• ******* — 加入英文社区：***.gg/QnWdhJxq9h

中国区微信客户群

如需加入客户微信支持群，请扫描：

扫码加入群聊。如有任何问题或需要协助，可直接联系群管理员。

📄 许可证

本项目采用 MIT 许可证 开源。

✨ 贡献者

感谢所有参与项目的贡献者：