octop 0.9.15

Smarter self-hosted AI assistant for multiple users and agents, built on harness-agent

Changelog

本文件记录项目的所有重要变更。

格式遵循 Keep a Changelog，版本号遵循 语义化版本规范。

[Unreleased]

[0.9.15] - 2026-07-27

修复

• 加固聊天导航：切换专家时避免残留旧会话 URL，并稳定流式 Markdown 渲染
• 优化 Memory / Token Usage 页面布局，消除嵌套滚动并改善信息密度
• 补充企业微信客户群二维码相关文档说明

[0.9.14] - 2026-07-25

新增

• 控制平面支持 PostgreSQL 双后端（统一 DatabasePool、并行 PG 迁移、安装向导选择/绑定、pg_dump 备份；PostgreSQL 下记忆默认复用控制平面 DSN）(#60)
• SkillHub 改为走 HTTP API，支持来源中立的技能包安装与搜索 (#55)
• 远程浏览器/桌面支持真实拖拽（转发 CDP 指针事件），并共享推流连接中指示 (#50)
• 聊天界面布局与交互打磨：历史侧栏、消息队列、自动滚动与欢迎页等体验优化 (#66, #69, #70)

修复

• 修复 macOS/Linux 上 Agent 上下文历史写入主机根目录的问题：依赖 harness-agent≥0.9.12 将 deepagents artifacts 落到 Agent 工作区 (#57)
• Provider catalog 的 context_window 映射为 harness max_input_tokens，修复 Auto/摘要阈值与 UI 上下文环按错误上限计算的问题
• 元宝扫码绑定后保存官方 API 与 WebSocket 地址，并升级网关至 0.8.7 以支持完整媒体收发 (#56)
• ChatGPT/Codex OAuth 改为 device code 流程，修复非 localhost 部署下授权失败 (#54)
• 技能 CLI 安装不再根据用户输入的 slug 推导路径，避免装错包 (#63)
• 删除会话时同步清理 harness checkpoint，避免「删除」后消息历史仍残留 (#60)
• 修正 PostgreSQL 记忆可移植导出的误导性 pg_dump 提示（共享 schema 下按 namespace 隔离，不可整库导出单 agent）(#60)
• 技能启用/禁用与 SkillHub 安装不再触发整机 Agent rebuild，避免切到技能列表时短暂「未找到 Agent」
• 修复聊天向上滚动加载更早消息失效，并在列表未溢出时提供可点击回退
• 工作区路径语义澄清（from_workspace），并加固 Windows 下 file URL / 主机路径校验

变更

• /compact 改为在当前话题强制触发一次 Summarization（总结较早消息并 offload 到 conversation_history/），不再新建线程；新建空话题请用 /new
• /compact 成功提示明确：聊天界面仍保留完整历史，压缩的是下一轮模型可见上下文
• 文档与发布流程改为 develop 日常集成、先合入 main 再打 tag (#48)

[0.9.13] - 2026-07-23

新增

• SkillHub 改为走 HTTP API，支持来源中立的技能包安装与搜索 (#55)
• 远程浏览器/桌面支持真实拖拽（转发 CDP 指针事件），并共享推流连接中指示 (#50)

修复

• 修复 macOS/Linux 上 Agent 上下文历史写入主机根目录的问题：依赖 harness-agent≥0.9.12 将 deepagents artifacts 落到 Agent 工作区 (#49, #57)
• Provider catalog 的 context_window 映射为 harness max_input_tokens，修复 Auto/摘要阈值与 UI 上下文环按错误上限（如 128k）计算的问题
• 修复取消聊天任务后再次提问会一直停留在思考状态的问题 (#42, #43)
• 技能启用/禁用与 SkillHub 安装不再触发整机 Agent rebuild，避免切到技能列表时短暂「未找到 Agent」
• 内置专家卡片标题与图标水平对齐
• SkillHub / 专家市场在 Python SSL 失败时给出可操作提示，并修正技能市场错误态「Retry」未本地化为「刷新」(#44, #46)
• 元宝扫码绑定后保存官方 API 与 WebSocket 地址，并升级网关至 0.8.7 以支持完整媒体收发 (#56)
• ChatGPT/Codex OAuth 改为 device code 流程，修复非 localhost 部署下授权失败 (#54)
• 远程桌面安装拒绝不支持的 EL10 环境 (#41)
• 聊天上下文占用图例在空会话时对齐 (#40)
• 修复聊天向上滚动加载更早消息失效，并在列表未溢出时提供可点击回退
• 工作区路径语义澄清（from_workspace），并加固 Windows 下 file URL / 主机路径校验

变更

• /compact 改为在当前话题强制触发一次 Summarization（总结较早消息并 offload 到 conversation_history/），不再新建线程；新建空话题请用 /new
• /compact 成功提示明确：聊天界面仍保留完整历史，压缩的是下一轮模型可见上下文
• 文档与发布流程改为 develop 日常集成、先合入 main 再打 tag (#48)

[0.9.12] - 2026-07-21

新增

• 备份恢复后可在进程内同步 providers 并重载 agent；提供商变更后仅重载受影响的 agent
• 新增服务端时区 API（default_timezone / GET /api/settings/timezone），控制台时间展示对齐服务端时区
• 记忆提炼支持为每个 agent 单独指定提取模型，并在整理记录中展示每次 extract_run 结果

修复

• 修复记忆提取模型无法 fallback 导致提炼失效的问题
• 修复语音输入 STT 回退处理
• 修复内部 MCP gateway 在事件循环上阻塞的问题
• 修复高级搜索探测接口缺失、表格分页卡在 10 条、新建会话图标提示，并加固安装脚本
• 改进 Notion OAuth HTTPS 错误提示

变更

• Memory 页签「全部」更名为「记忆沉淀」

[0.9.11] - 2026-07-19

新增

• 新增 SkillHub 专家市场：支持浏览、安装与管理专家，并完善安装安全校验与欢迎页快捷卡片体验
• 新增自定义 MCP 连接器管理，支持探测、工具缓存与连接器配置

[0.9.10] - 2026-07-18

新增

• 新增工作区文件预览与浏览器工作区支持，并完善相关工具链
• 新增聊天面板停靠式文件预览、HTML 预览与历史下拉刷新

修复

• 修复连接器 Notion OAuth 弹窗阻塞的问题 (#19)

变更

• 重构聊天界面，将浏览器面板与文件面板统一为 ChatDock
• 调整工作区路径透传逻辑，不再重写 BackendWorkspace 路径
• 将上下文使用统计委托给 harness-agent 0.9.10

移除

• 移除内置的临床医生专家 (#20)

[0.9.9] - 2026-07-16

新增

• 新增远程桌面安装与连接器探测能力增强 (#16)

[0.9.8] - 2026-07-15

新增

• 远程浏览器/远程桌面安装日志面板新增「复制日志」按钮，并在安装失败时提示可将日志交给 Octop 协助排查
• 新增前端 copyText 工具，在非安全上下文（如 plain-http 管理页）下通过临时 textarea + execCommand 回退，保证剪贴板复制可用
• 桌面安装脚本新增 A-F4（关闭窗口）与 C-A-D（显示桌面）openbox 快捷键，对应桌面快捷键

修复

• 修复桌面安装脚本的 Python 构建依赖检测：改用 venv Python（而非系统 python3）解析 pythonX.Y-dev，避免 evdev 编译时找不到 Python.h；setup.py 安装构建依赖时显式传入 --python 指向当前 venv Python
• 修复连接器类型漂移导致聊天弹窗 logo 解析失败的问题

变更

• Docker 构建与 make build-frontend 的 NODE_OPTIONS --max-old-space-size 由 4096 调低为 2048，降低构建内存占用
• 新增 docker-publish.yml 工作流，构建并推送镜像到 Docker Hub
• 移除 release.yml 中多余的 id-token: write 权限
• 删除已与现行 Docker Hub 发版流程脱节的离线部署脚本 docker_deploy.sh，并清理 docker/README.md、README_CN.md 中的相关章节
• 修正 docker/README.md 标题笔误（ODocker → Octop）

[0.9.7] - 2026-07-14

新增

• 新增多款连接器网关适配器：百度地图、携程问道、飞猪、美团旅游助手、QQ 音乐、元典 (#14)
• 重构连接器网关目录与注册机制，支持更灵活的连接器安装 (#14)

修复

• 修复 Linux 远程桌面安装脚本在 EL7（TigerVNC 1.8）下的兼容性，避免 xfdesktop 阻塞安装

[0.9.6] - 2026-07-13

新增

• 新增远程桌面（Remote Desktop）功能，支持跨 Linux、Windows、macOS 的桌面串流 (#7)

修复

• 从 .dockerignore 中移除 uv.lock，修正 Docker 构建无法 COPY 锁文件的问题 (#9)
• 修复远程桌面、浏览器、终端及安装向导的本地化（i18n）问题 (#11)

[0.9.5] - 2026-07-12

新增

• 新增 Linux、Windows、macOS 三端的远程桌面串流能力
• 完善远程桌面的安装/卸载交互，并打包 Linux 端安装脚本

修复

• 修复 Windows 与 Linux CI 下桌面配置/捕获/输入相关单测与 mypy 报错
• 修复 Mac 端远程桌面安装时误导性的提示文案
• 加固桌面安装 SSE 流式推送并清理 dashboard 端 lint 问题

[0.9.4] - 2026-07-11

新增

• 新增 agent backend 的主机 root_dir 浏览器与权限探测能力
• 改进聊天流式滚动行为与思考计时器

修复

• 修复 Windows 下 sqlite 路径测试、媒体路径与 POSIX 专属测试导致的 CI 失败
• 修复 Windows 测试收集问题（惰性导入 pwd 模块）
• 修复 harness-memory Bridge 导入路径
• 修复 CI 流水线并让测试套件通过，项目重命名为 Octop

变更

• Windows 兼容：默认 agent backend 限定到 workspace，并集中 POSIX 专属 stdlib 调用以适配 Windows mypy CI

[0.9.1] - 2026-07-08

新增

• 远程浏览器控制页面与浏览器 AI 面板，支持远程浏览器自动化操作
• 附件下载的 Content-Disposition 头（RFC 5987，兼容非 ASCII 文件名）
• 前端 UI 语言偏好持久化（自动检测浏览器语言并记忆）
• 专家目录欢迎语（默认欢迎内容 / 工作区清单读取 / 专家目录播种）
• 附件相关国际化域（i18n/domains/attachment.py）
• 聊天欢迎语支持

变更

• 重构聊天附件与上传处理链路，精简接口与实现
• 重构网关媒体层：附件提示、入站存储、工具媒体展示重写
• 重构 harness 请求构造与消息处理器
• 调整上下文拆分、专家目录、provider 存储与 agent 管理器
• 重构前端聊天界面：输入框、消息气泡、工具媒体条、上下文窗口环等组件大量更新
• 更新登录、初始化向导、终端 AI 面板等前端页面

修复

• 修复附件路径解析与内容分发相关问题

移除

• 移除模型配置提示弹窗、旧聊天流模块、slash 上下文与附件签名测试

A smarter, self-hosted AI assistant — multi-user, multi-agent.

Highlights · Overview · Core Technology · Features · Quick Start · Contents

English · 中文

---

Octop is an open-source, self-hosted AI assistant. It's not just a tool — it's a digital life form that can operate in parallel. Through its multi-agent architecture, it builds an intelligent environment that is both independent and collaborative for teams, families, and individuals. Best of all, it runs entirely on your machine — the fully self-hosted design means privacy is never a compromise, while single-process startup makes the powerful web console, CLI, and IM integrations readily accessible.

Chat through the Web Dashboard, Feishu, DingTalk, QQ, Discord, WeCom, or programmatic HTTP/SSE. Extend capabilities with the expert library, Connectors (OAuth + MCP), and ACP integration for IDE workflows.

✨ Highlights

	Feature	Description
👥	Multi-user expert team	One admin, shared household; built-in expert library — switch specialists per scenario
🎭	MBTI personas	16 personality templates plus an interactive quiz — give each agent a distinct character
🔒	Security built-in	JWT multi-user isolation, tool approval, shell command guardrails, and PII redaction — data stays local
🔌	Connector ecosystem	Tencent suite (Docs, Weibo trends, News, …); OAuth and MCP gateway extend resource boundaries
💾	Pluggable backends	Local disk, Docker containers, PostgreSQL, or COS/S3 — AI operates inside isolated boundaries
🧠	Portable memory	Powered by harness-memory; memory migrates with the workspace
↔️	ACP bidirectional	octop acp for IDE/terminal AI; delegate to OpenCode / Claude Code with permission gates
💻	Terminal AI+	Interactive shell in the browser — AI-assisted command execution and troubleshooting
🌐	Browser AI+	Headless Chromium sessions for web automation, screenshots, and remote browsing
🖥️	Remote desktop	Live screen and input from the dashboard on Linux, Windows, and macOS — remote office work and GUI apps; one-click isolated desktop on headless Linux
🏠	Self-hosted	Dashboard, CLI, IM channels, and cron in one octop run — all data under ~/.octop/

📌 Overview

Octop is a self-hosted AI assistant platform for households and small teams. It runs a single process that serves a web dashboard, a CLI, IM channels (Feishu, DingTalk, QQ, Discord, WeCom, and more), and cron automation — all sharing one SQLite database under ~/.octop/.

Octop's design goal: keep every conversation, workspace, and credential on your own machine, while giving each user a personal team of specialized agents they can switch between per task.

🧠 Core Technology

Layer	Technology
Language	Python 3.11+
Web framework	FastAPI + uvicorn
Agent runtime	harness-agent
Gateway	harness-gateway
Control plane DB	SQLite (WAL) via aiosqlite
Frontend	React 18 + TypeScript + Vite + Ant Design
Scheduling	APScheduler
ACP	agent-client-protocol
Build / quality	hatchling · ruff · mypy · pytest

Octop is built on the Harness stack — a set of focused runtimes that Octop composes into one process:

• harness-agent — Agent runtime: model routing, tools, skills, and conversation checkpointing.
• harness-gateway — multi-platform IM channel bridge that normalizes incoming messages into a single processing pipeline.
• harness-memory — hierarchical recall with full-text search, so an agent's memory travels with its workspace.
• harness-browser — CDP-based browser automation with persistent profiles for web tasks.

Instead of an external queue or message broker, Octop routes every surface — Web UI, IM, and cron — through one in-process HarnessProcessor. The result is a single, restart-safe process whose entire state is rebuilt from ~/.octop/octop.db on boot.

🤔 Features

Server & auth

• Multi-user JWT authentication with admin role
• First-run setup wizard (octop init)
• Interactive API docs at /api/docs (off by default — set "enable_api_docs": true in config.json to enable)

Agents

• Multiple agents per user; each has its own workspace, providers, channels, and cron
• 16 MBTI persona templates + custom system prompt
• Expert library scanned at boot (infra/agents/experts/library/)
• Workspace backends: local disk, COS, S3, and other remote stores

Channels & automation

• IM channels: Feishu, DingTalk, QQ, Discord, WeCom, and more
• Proactive cron jobs with natural-language and slash-command triggers
• Unified message processing across Web UI, IM, and cron surfaces

Surfaces

• Web dashboard — chat, agents, connectors, channels, cron, settings
• CLI — octop run, octop chat, octop acp, admin commands
• HTTP/SSE API — full programmatic access

ACP (Agent Client Protocol)

Octop supports ACP in two directions:

1. Inbound — external tools use your Octop agent

   octop acp --agent main   # stdio ACP server for Zed, OpenCode, …
   

2. Outbound — Octop delegates to external coding agents

   • Dashboard → ACP (/acp): configure runners (global per user)
   • Enable acp_runner per agent, then delegate in chat

Built-in outbound runners include OpenCode, CodeBuddy, Claude Code, and Codex.

Full setup: docs/acp.md.

🚀 Quick Start

Prerequisites

• macOS / Linux / Windows
• No pre-installed Python required — the installer uses uv to provision Python 3.12 in an isolated venv under ~/.octop/

1. Install

macOS / Linux — one-line installer (recommended):

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) — download and run, or from a cloned repo:

curl -fsSL https://finnie-1258344699.cos.ap-guangzhou.myqcloud.com/octop/install.bat -o install.bat
install.bat

After installation, open a new terminal or reload your shell:

source ~/.zshrc   # Zsh
# or
source ~/.bashrc  # Bash

The installer places octop on your PATH via ~/.octop/bin. Optional extras:

# 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

See scripts/README.md for all install options (--version, --from-source, --mirror, Windows flags).

Alternative — PyPI (if you already manage Python yourself):

pip install octop
# optional: pip install "octop[browser]"

2. Initialize

octop init

The interactive wizard creates the SQLite database, JWT secret, and first admin account under ~/.octop/.

3. Run

# 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

Open http://127.0.0.1:8088 — default credentials are admin / octop (change immediately).

Docker (recommended for production)

# 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=changeme \
  octop:latest

Open http://localhost:8088 — default credentials are admin / octop (change immediately).

Variable	Default	Description
OCTOP_PORT	8088	HTTP listen port
OCTOP_DEFAULT_PASSWORD	octop	First-run admin password
OCTOP_ADMIN_USERNAME	admin	First-run admin username
OCTOP_DATA	~/.octop	Host data directory (compose bind mount)

See .env.example for the full list.

📑 Contents

• Highlights
• Overview
• Core Technology
• Features
• Quick Start
• Deploy & Use
  • Install options
  • Configuration
  • CLI reference
  • Web dashboard
  • Data directory
• Architecture & Dev
  • Architecture
  • Project layout
  • Development
• Project Info
  • Security & privacy
  • Contributing
  • Changelog
  • Related projects
  • WeCom customer group
  • License

📦 Install options

Method	Platform	Description
Remote one-liner	macOS / Linux	curl …/octop/install.sh | bash
Remote one-liner	Windows	irm …/octop/install.ps1 | iex or install.bat
Local script	macOS / Linux	bash scripts/install.sh
Local script	Windows	scripts\install.bat or install.ps1
PyPI	Any	pip install octop or pip install "octop[browser]"
Docker	Any	docker/docker-compose.yml

All install scripts provision an isolated environment at ~/.octop/venv and a ~/.octop/bin/octop wrapper — they do not touch system Python.

⚙️ Configuration

All runtime state lives in ~/.octop/. Manage it via CLI or edit files directly.

# 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

Supported LLM providers

OpenAI-compatible APIs, DashScope (Qwen), Ollama, and other presets — configure per agent in the dashboard or via octop provider.

Supported channels

Channel	Credentials
Feishu	App ID, App Secret
DingTalk	App Key, App Secret
QQ	Bot AppID, Token
Discord	Bot Token
WeCom	Corp ID, Agent Secret
Web Dashboard	Enabled by default

📖 CLI reference

Command	Description
octop init	Bootstrap ~/.octop/ (DB, admin, JWT secret)
octop run	Start Octop in the foreground
octop service start	Install and start as a system service
octop service stop	Stop the system service
octop agent	Create, list, start/stop agents
octop channel	Install and manage IM channels
octop chats	REPL and session management
octop acp	Stdio ACP server for IDE integration
octop cron	Manage scheduled tasks
octop models	Provider presets and model resolution
octop skills	Enable/disable per-agent skills
octop backup	Export / restore backups
octop clean	Remove CLI state or wipe ~/.octop/
octop update	Check for and install updates

Full reference: docs/cli.md.

🖥️ Web dashboard

After octop run, open http://127.0.0.1:8088.

• Chat — real-time conversation with agents
• Agents — create agents, pick experts / MBTI personas, configure providers
• Connectors — OAuth apps and MCP gateways
• Channels — IM platform setup
• Cron — visual cron job management
• ACP — configure outbound coding-agent runners
• Settings — users, security, TLS, system

Interactive API docs: http://127.0.0.1:8088/api/docs (disabled by default — enable by setting "enable_api_docs": true in config.json)

📁 Data directory

~/.octop/                          ← install & data root
├── 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

See docs/configuration.md for env vars and config.json.

🏗️ Architecture

OctopServer
 ├─ SqlitePool               SQLite (WAL mode)
 ├─ 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)

Single process. Restart rebuilds state from ~/.octop/octop.db.

See docs/architecture.md and docs/adr/001-single-process-model.md.

📁 Project layout

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/

🛠️ Development

Prerequisites: Python 3.11+, Node 18+, uv

# Backend
make install          # pip install -e ".[dev]"
make 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

Individual targets: make test, make lint, make typecheck, make format.

🔒 Security & privacy

• Local-first: Config, chats, workspaces, and credentials live under ~/.octop/ on your machine.
• Multi-user isolation: JWT auth with per-user agents and workspaces.
• Tool guardrails: User-editable shell command rules under ~/.octop/security/tool_guard/.
• No vendor lock-in: Swap LLM providers, storage backends, and channels without rewriting agents.

🤝 Contributing

Contributions are welcome:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Run make all (backend) or make check-all (full stack) before submitting
4. Open a Pull Request

See CONTRIBUTING.md for the full guide. Security issues: SECURITY.md.

Module boundaries and coding conventions: AGENTS.md.

📋 Changelog

See CHANGELOG.md for release history.

🔗 Related projects

Project	Description
harness-agent	Agent runtime — model routing, tools, skills, checkpointing
harness-gateway	Multi-platform IM channel bridge
harness-memory	Hierarchical recall and FTS search
harness-browser	CDP browser automation with persistent profiles

These harness-* projects are being prepared for open-sourcing; repository links will be added once they are published.

💬 WeCom Customer Group (CN)

For the customer WeCom support group, scan:

This QR code is valid until 2026-08-03 (UTC+8). Please ask the maintainer for an updated code after it expires.

📄 License

This project is licensed under the MIT License.