Octop 自托管 AI 助手怎么装、怎么跑、数据放在哪

如果你手上有一台闲置的 Linux 机器或者 NAS，想搭一个多用户、多 Agent 的 AI 助手，模型自己选，数据留在本地，Octop 给了一条能照着走的路径。它是腾讯云开源的项目，走本地优先路线，和同门的 WorkBuddy 那种登录买积分的 SaaS 模式完全不同。下面把安装、启动、目录、配置、扩展和开发这几块拆开讲，重点标出容易漏掉的参数和目录。

装之前要准备什么

最常被问到的问题是「要不要先装 Python」。不需要。安装脚本会通过 uv 在 ~/.octop/ 下创建隔离的 Python 3.12 虚拟环境，不会碰系统里已有的 Python。

系统支持 macOS、Linux、Windows 三个平台。硬件方面，README 给的要求是现代多核 CPU，预留数 GB 内存供进程和模型、Embedding 缓存使用，磁盘要能容纳数据库、Agent 工作区和文档语料。

装完有一件事最容易漏。安装脚本会把 octop 加入 PATH，路径是 ~/.octop/bin，但当前终端不会立刻生效。你需要打开一个新终端，或者手动重新加载 shell 配置。Zsh 用 source ~/.zshrc，Bash 用 source ~/.bashrc。漏了这一步，敲 octop 会提示找不到命令。

各平台的安装命令

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 用户可以下载 install.bat 后运行，或者从已克隆的仓库里执行。

安装脚本有两个可选附加组件。浏览器自动化需要 Playwright Chromium，安装时加 --extras browser。飞书通道支持加 --extras channels-feishu。

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

完整的安装选项在 scripts/README.md 里，包括 --version、--from-source、--mirror 以及 Windows 下的对应参数。

如果你已经自己管理 Python 环境，可以直接走 PyPI。

pip install octop
# 可选：pip install "octop[browser]"
# 可选本地 ONNX Embedding 模型缓存：pip install "octop[local-embedding]"

本地 Embedding 那个额外包只做一件事，把目录模型下载到 ~/.octop/embedding_models。它不用于对话，也不接入 Memory，别误以为装了它就能本地推理。

从源码开发的话用 uv。

uv sync --extra local-embedding

桌面客户端从 GitHub Releases 下载，Windows 是 NSIS 安装程序，macOS 是 dmg，Linux 是 tar.gz。飞牛 NAS 用户有 fpk 包可选，分依赖 Docker 和无 Docker 两个版本，通过应用中心安装。桌面客户端说明在 desktop/README.md，飞牛打包指南在 fnos/README.md。

首次启动和 Docker 部署

前台启动就一条命令。

octop run

默认监听 http://127.0.0.1:8088，同时拉起 API 和 Web 控制台。想换主机和端口。

octop run --host 0.0.0.0 --port 8088

想让它在后台常驻，注册成系统服务。

octop service start

支持 systemd、launchd 和 Windows 服务三种。

Docker 更适合生产部署。用 compose 一条命令起来。

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 位，同时包含字母和数字。被应用密码策略拒绝的常见弱密码会自动回退成随机密码，不会硬塞进去。管理员用户名默认 admin，可以用 OCTOP_ADMIN_USERNAME 覆盖。

Docker 相关的环境变量如下。

交互式的 octop init 和设置向导会让你自己设置密码，规则一样，至少 8 位，字母数字都要有。API 文档默认关闭，需要开启的话，在 config.json 里设置 "enable_api_docs": true，然后访问 /api/docs。

数据都存在哪里

这是自托管方案最该先搞清楚的部分。所有运行时数据在 ~/.octop/ 下面，结构如下。

~/.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

控制面默认用 SQLite，WAL 模式。想换 PostgreSQL，在 config.json 的 database 段配置，或者用 OCTOP_DATABASE_* 环境变量，也可以在首次设置向导里选。控制面切到 PostgreSQL 之后，Agent 记忆默认复用同一个 DSN，按 per-agent schema 存。如果你还想继续用文件记忆，在 agent 配置里写 "memory": { "backend": { "type": "sqlite" } }。详细说明在 docs/configuration.md 和 docs/adr/002-database-backends.md。

升级用 octop update。它只替换 wheel 或二进制，~/.octop/ 下的数据库、工作区、密钥和 config.json 都会保留。数据库结构在下次启动时自动迁移。只有设置向导提示需要迁移时，才去跑 octop init。跨版本升级前先备份，命令是 octop backup。

怎么配置模型和 IM 通道

CLI 覆盖了大部分日常配置。

octop models           # LLM 供应商与模型
octop provider list    # 列出供应商
octop channel list     # 列出 IM 通道
octop channel install  # 安装通道
octop skills list --agent main   # 按 Agent 查看 Skill
octop cron list        # 列出定时任务
octop user list        # 管理员查看用户

支持的 LLM 供应商预设包括 OpenAI 兼容 API、DashScope（千问）、Ollama 等。可以在控制台里配，也可以用 octop provider 按 Agent 分别配。

IM 通道这块，每个通道需要的凭证不一样，配之前先对一下表。

Web UI、IM 和定时任务走的是同一套消息处理链路。定时任务用 APScheduler 调度，可以用自然语言配 Cron，也可以用斜杠命令触发，适合让 Agent 每天按时推送内容或执行任务。

多用户多 Agent 怎么组织

多用户 JWT 认证，支持管理员角色。首次运行向导是 octop init。每位用户可以创建多个 Agent，每个 Agent 有自己独立的工作区、供应商、通道和定时任务。家庭共用或者小团队分工，这套结构能隔离开。

Agent 的人格有两种来源。内置 16 种 MBTI 人格模板，也可以完全自定义系统提示词。启动时会扫描专家库，路径是 infra/agents/experts/library/，往里放配置就能出现在可选列表里。

工作区后端支持本地磁盘、COS、S3 以及其他远程存储。Agent 的所有文件操作都在这个隔离边界内完成。

ACP 能接什么

ACP 是 Agent Client Protocol，Octop 支持两个方向。

入站方向让外部工具调用你的 Octop Agent。比如给 Zed、OpenCode 这类 IDE 提供 stdio ACP 服务。

octop acp --agent main

出站方向是 Octop 把任务委派给外部编程 Agent。在控制台的 ACP 页面（/acp）配置 Runner，作用范围是按用户全局。然后给某个 Agent 启用 acp_runner，就能在对话里直接委派任务。内置的出站 Runner 有 OpenCode、CodeBuddy、Claude Code 和 Codex。完整配置看 docs/acp.md。

知识库、插件和其他几项能力

知识库基于文档做 RAG 检索。上传文件后，语义检索会让 Agent 的回答锚定在你的私有语料上，适合内部文档问答这类场景。

插件用 octop plugin 管理，支持第三方扩展。内置插件随安装注入，在控制台按需一键启用。

终端 AI+ 是浏览器内的交互式 Shell，AI 辅助命令执行和排障。浏览器 AI+ 基于 Chromium 的无头浏览器会话，支持网页自动化、截图和远程操控。远程桌面能在控制台里实时看屏并做键鼠操控，跨 Linux、Windows、macOS，无图形界面的 Linux 可以一键搭一个隔离桌面出来。这几项 README 没有展开更多配置细节，实际用的时候配合控制台看。

架构和项目结构

Octop 是单进程架构，启动时整个状态从控制面数据库重建。它不依赖外部消息队列或者中间件，所有入口通过进程内的 HarnessProcessor 统一路由。

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)

底层依赖四个 harness 工程。harness-agent 负责模型路由、工具、技能和对话检查点。harness-gateway 把各个 IM 平台的入站消息归一成统一管线。harness-memory 做分层记忆和全文检索，让记忆随工作区迁移。harness-browser 基于 CDP 做浏览器自动化，支持持久化配置。这四个项目正在筹备开源，仓库地址发布后会补上。

技术栈这张表可以留着对照。

项目结构方面，src/octop/ 下有 config.py（环境变量配置）、launch.py（OctopServer 启动加 uvicorn）、infra/（业务核心，含 agents、gateway、cron、db、users 等）、api/（FastAPI 路由、JWT、SSE）、cli/（Click 命令）、dashboard/（构建后的 React SPA）。前端源码在仓库根目录的 dashboard/，改完运行 make build-frontend。docker/ 放 Compose、入口脚本和构建部署脚本。测试在 tests/ 下分 unit/ 和 integration/。

本地开发

前置条件是 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。提交 PR 之前跑一遍 make all，这是仓库的发布门槛。

安全和隐私相关的几条

本地优先意味着配置、对话、工作区和凭证都待在 ~/.octop/ 里。多用户之间靠 JWT 隔离 Agent 和工作区。敏感数据在离开工作区之前会自动脱敏，高风险工具或者 Shell 命令需要按照护栏规则显式审批。护栏规则可以在 ~/.octop/security/tool_guard/ 里改。LLM 供应商、存储后端和 IM 通道都能自由切换，不锁死在某一家。

速览清单

• 装之前确认系统是 macOS / Linux / Windows，不需要预装 Python
• 装完开新终端或 source 一下 shell 配置，否则 octop 找不到
• 一键安装 macOS / Linux 用 curl 管道 bash，Windows 用 irm 管道 iex
• 可选组件在安装命令后加 --extras browser 或 --extras channels-feishu
• 启动用 octop run，默认 http://127.0.0.1:8088，常驻用 octop service start
• Docker 部署后去 /data/.octop/credential.txt 拿管理员密码
• 密码规则是至少 8 位、字母加数字，弱密码会被替换成随机密码
• 数据都在 ~/.octop/，升级用 octop update，备份用 octop backup
• 控制面要换 PostgreSQL 改 config.json 的 database 段
• ACP 入站用 octop acp --agent main，出站在控制台 /acp 配 Runner

FAQ

Q：装 Octop 需要先装 Python 吗？
不需要。安装脚本通过 uv 在 ~/.octop/ 下建隔离的 Python 3.12 环境，不会影响系统 Python。

Q：为什么装完敲 octop 提示找不到命令？
当前终端还没加载新的 PATH。开一个新终端，或者执行 source ~/.zshrc / source ~/.bashrc。

Q：Docker 首次启动的管理员密码在哪？
在容器内 /data/.octop/credential.txt。没设 OCTOP_DEFAULT_PASSWORD 时会自动生成随机强密码写进去。

Q：默认数据库是什么，能换吗？
默认 SQLite，WAL 模式。可以在 config.json 的 database 段改成 PostgreSQL，也可以用 OCTOP_DATABASE_* 环境变量或首次设置向导。

Q：升级会丢数据吗？
octop update 只替换 wheel 或二进制，~/.octop/ 下的数据库、工作区、密钥和 config.json 都保留。数据库结构下次启动自动迁移。跨版本升级前建议先 octop backup。

Q：ACP 能接哪些外部 Agent？
出站内置 OpenCode、CodeBuddy、Claude Code 和 Codex。入站方向给 Zed、OpenCode 等提供 stdio ACP 服务。

Q：API 文档为什么打不开？
默认关闭。在 config.json 里设 "enable_api_docs": true 再访问 /api/docs。

Q：Agent 的人格怎么配？
内置 16 种 MBTI 模板，也可以自定义系统提示词。启动时会扫描 infra/agents/experts/library/。