Octop：单进程跑完 Web、IM 与 cron 的多用户 Agent 运行时

Octop 是腾讯开源的 MIT 项目（Python 3.12+，约 1k star），定位是自托管的 AI 助手：多用户、多 Agent。

一个进程同时 serve Web 仪表盘、CLI、IM 渠道和 cron 自动化，全部数据落在 ~/.octop/ 下，控制面默认 SQLite（WAL），可选 PostgreSQL。

架构上值得注意的点

• 单进程，无外部消息队列/broker。Web/IM/cron 所有入口都走同一个进程内 HarnessProcessor，状态在启动时从控制面数据库重建，停机后重启是安全的。
• 多用户 JWT 隔离 + admin 角色，首次运行走 setup 向导（octop init）。
• 一个用户可以挂多个「专家」(expert)，每个专家有自己的工作区、provider、渠道、cron。内置 16 种 MBTI 人设模板，有专家库/专家市场，同一部署内可以分享。
• IM 渠道：飞书、钉钉、QQ、微信、Telegram、Discord、企业微信等。
• Connector 生态（OAuth + MCP 网关），含腾讯套件（Docs/Meeting/News 等）。
• 工作区后端可插拔：本地磁盘、Docker 沙箱、PostgreSQL、COS/S3。注意工作区后端和控制面库是两套配置。
• 知识库 RAG、插件系统、远程桌面、浏览器 AI+（headless Chromium）、终端 AI+。
• ACP 双向。inbound：octop acp --agent main 对外提供 stdio ACP server，给 Zed/OpenCode 这类外部工具调用你的 Octop agent；outbound：Octop 反过来把任务委派给外部 coding agent，内置 OpenCode/CodeBuddy/Claude Code/Codex。
• AgentTeams（Beta）：一个 coordinator 编排多个 expert 跑多步任务。

技术栈

Python 3.12+ / FastAPI + uvicorn / 控制面 SQLite(WAL) 默认或 PostgreSQL / 前端 React 18 + TS + Vite + Ant Design / APScheduler / agent-client-protocol / hatchling·ruff·mypy·pytest。

底层 Harness 拆成四个包：octop-harness（运行时）、octop-gateway（IM 桥接）、octop-memory（分层召回 + 全文检索）、octop-browser（CDP 浏览器自动化）。

安装

macOS/Linux 一行安装，用 uv 在 ~/.octop/venv 里隔离装 Python 3.12，不碰系统 Python：

curl -fsSL https://finnie-1258344699.cos.ap-guangzhou.myqcloud.com/octop/install.sh | bash

Windows 用 irm ...install.ps1 | iex 或 install.bat。桌面版从 GitHub Releases 下载 exe/dmg/tar.gz，FnOS NAS 有 .fpk 包。已有 Python 也可以 pip install octop（PyPI）。

浏览器自动化需要额外装 Chromium。无头服务器上桌面版用不上，只能走 CLI 或 Docker，这条依赖别漏。

装完新开终端 source ~/.bashrc，octop 会被放进 PATH（~/.octop/bin）。

初始化与运行

octop init          # 交互向导：创建 SQLite、JWT secret、首个 admin
octop run           # 前台，API + Web 仪表盘
octop run --host 0.0.0.0 --port 8088
octop service start # 注册成 systemd/launchd/Windows 服务

打开 http://127.0.0.1:8088 。

Docker

生产推荐 compose：

docker compose -f docker/docker-compose.yml up -d

或手动：

docker run -p 8088:8088 -v octop-data:/data/.octop \
-e HOME=/data -e OCTOP_DEFAULT_PASSWORD="..." octop:latest

首次启动创建 admin，凭据写到容器内 /data/.octop/credential.txt；不设 OCTOP_DEFAULT_PASSWORD 会生成随机强密码。密码策略 ≥8 位且含字母数字。

环境变量：OCTOP_PORT(8088)、OCTOP_DEFAULT_PASSWORD、OCTOP_ADMIN_USERNAME(admin)、OCTOP_DATA(~/.octop)。

这里有个容易踩的地方：HOME=/data 和 -v octop-data:/data/.octop 必须对应上，否则数据落不进挂载卷，容器一重建就丢。

数据目录

~/.octop/ 下：

• config.json
• octop.db（SQLite）
• secrets/
• agents// —— 每个 agent 的工作区，含 SOUL.md、skills
• security/tool_guard/ —— shell 命令允许/拒绝规则
• logs/
• venv/
• bin/octop

控制面也可以换成 PostgreSQL：在 config.json 的 database 段配，或用 OCTOP_DATABASE_* 环境变量，或在首次向导里选。用 Postgres 时 agent memory 默认复用同一个 DSN（按 agent 分 schema）；如果要保留文件型 memory，得在 agent 配置里显式写：

{"memory": {"backend": {"type": "sqlite"}}}

取舍上，单机自用 SQLite(WAL) 就够了，进程内串行写不会争用；上 Postgres 主要是为了多实例或多用户并发写控制面，代价是 memory 存储得单独交代清楚。

升级

octop update 只换 wheel/二进制，~/.octop/ 下的库、工作区、密钥、config.json 全部保留，下次启动自动迁移 schema。跨版本升级前先跑 octop backup。

CLI

常用子命令：octop agent / channel / chats / acp / cron / models / skills / plugin / backup / clean / update。

memory 维护：

octop memory list
octop memory slim --agent ID
octop memory slim --all

会话里 /memory slim 会先解释影响范围，加 --confirm 才开始执行。

Provider 与渠道凭据

LLM provider 预设覆盖 OpenAI 兼容、DashScope(Qwen)、Ollama 等，按 agent 配。

各渠道需要准备：飞书 App ID/Secret；钉钉 App Key/Secret；QQ Bot AppID/Token；微信扫码绑定；Telegram Bot Token；Discord Bot Token；企业微信 Corp ID/Agent Secret。Web 仪表盘默认启用。

项目信息

• 仓库：
• PyPI：
• 桌面版：