FreeOS:自由的 AI 工作室,想象空间由你来打开
产品闭环:uv run freeos org loop run。详见 README.md 与 docs/asset-loop.md。
创立初心 · 概述 · 亮点 · 核心技术 · 功能特性 · 规划 · 快速开始· 目录
English · 简体中文简介 · 繁體中文 · 日本語 · 한국어 · Français · Español · Português · Русский · العربية
Historical vs Current. 中文产品入口是 README.zh-CN.md。权威意图见 产品契约。
Current: 见下文创立初心与 产品契约:双系统合一;组织像工作室里另一间可独立布置的房间;托管 Node / 内嵌组织页是过渡桥。
Historical: 下文大量沿自 Octop 宿主能力说明(安装脚本、控制台、CLI、亮点表)。那些能力仍在 FreeOS 宿主里,但本文 不是 Octop 官方产品页,也不再把 FreeOS 写成「只管理云端与付费增强服务」。
FreeOS 是独立的下游二次开发项目,不是 Octop 官方发行版。我们保留上游许可证、版权和 NOTICE,并在此基础上建设本地优先的组织智能化与可导出管理系统能力:
- Octop(MIT)提供多智能体运行时、FastAPI 控制面、Dashboard、桌面打包及兼容层基础。
- openXYOS(Apache-2.0)提供组织模型、智能体蓝图、治理契约和本机定制工作台基础。
- FreeOS 提供集成桥接、行业模板与知识加工、治理校验、版本装配和独立代码导出。我们不宣称获得 Octop、腾讯云或其商标的认可、认证、赞助或官方支持。
完整的许可证分层、署名要求与对外表述见 NOTICE、上游归属说明、产品契约 和 集成架构。
FreeOS 诞生于一个简单而清晰的目标:在 Octop 的自托管多智能体能力之上,让每个人都能同时拥有 Octop + openXYOS 两套系统的力量——不必在「对话与自动化」和「组织与治理」之间二选一。
我们希望模型尽量跑在本地,知识尽量留在本地;Octop 与 openXYOS 已有的能力与资产能够互通、互相增强。用户可以在此基础上开发、优化、自我定制,生长出更贴合自身场景的新 openXYOS,并导出其系统源码,以便进一步产品化与商业化。
为避免整包内嵌 openXYOS 带来的安装负担与体积膨胀,FreeOS 选择另一条路:把 openXYOS 的网页与组织能力,逐步转化为 Octop 宿主上的原生能力,从而形成新的统一系统——FreeOS。当前桌面中的托管 Node / 内嵌组织页,只是通往这一终态的过渡桥,而非终点。
在使用方式上,FreeOS 更像你自己的工作室:先在本机安顿好,注册登录、数据与会话都留在你够得着的地方;以后若需要与更广的服务或授权衔接,会以可选方式慢慢打开,不挡你起步。组织相关能力则像工作室里另一间可独立布置的房间——方便试用、演练和长出自己的组织流程;与日常对话、助手协作同在一个 FreeOS 里,又各自留白,不把两种用法捏成同一种进入方式。
一句话:FreeOS = 本地可控的 Octop 底座 + 可生长、可导出的组织能力,双系统合一,双身份分立。
权威契约:产品契约。
下面「亮点 / 功能特性 / 快速开始」描述的是 从 Octop 继承、仍在 FreeOS 宿主中的能力(控制台、CLI、IM、知识库等),不是把本仓库重新标成 Octop。
借助飞书、钉钉、QQ、Discord、企业微信或 HTTP/SSE/WebSocket API 与任意 Agent 对话;通过专家库一键创建专业角色,通过 Connector(OAuth + MCP)接入外部服务,通过 ACP 与 IDE / 终端 AI 工具双向协作。
宿主设计目标(继承自 Octop):让每一次对话、工作区与凭据都留在你自己的机器上,同时为每个用户配备一组可按场景切换的专业 Agent。
| 特性 | 说明 | |
|---|---|---|
| 👥 | 多用户多 Agent 专家团 | 一人管理,全家共用;内置专家库,按场景切换专业角色 |
| 🎭 | MBTI 人格 | 16 种人格模板与互动测试,为每个 Agent 赋予鲜明性格 |
| 🔒 | 更安全 | JWT 多用户隔离、工具审批、Shell 命令防护与敏感信息脱敏,数据留在本地 |
| 🔌 | Connector 拓展体系 | 一键接入腾讯全家桶(文档 / 微博 / 新闻等),OAuth 与 MCP 网关轻松扩展 |
| 💾 | 可插拔后端存储 | 本地目录、Docker 容器、PostgreSQL 或 COS/S3,AI 在隔离边界内操作 |
| 🧠 | 可迁移记忆系统 | 基于 harness-memory,记忆随工作区迁移 |
| 📚 | 知识库 | 基于文档的 RAG 检索,让 Agent 的回答锚定你的私有知识库 |
| 🧩 | 插件 | 支持第三方插件扩展;内置插件随安装注入,按需一键启用 |
| ACP 双向集成 | octop acp 增强 IDE 与终端 AI;对话中委派 OpenCode / Claude Code 等 |
|
| 💻 | 终端 AI+ | 浏览器内交互式 Shell,AI 辅助命令执行与排障 |
| 🌐 | 浏览器 AI+ | 基于 Chromium 的无头浏览器会话,支持网页自动化、截图与远程操控 |
| 🖥️ | 远程桌面 | 控制台内实时看屏与键鼠操控,跨 Linux / Windows / macOS;适合远程办公、GUI 软件操作,无图形 Linux 可一键搭建隔离桌面 |
| 🏠 | 可自托管 | 一条 octop run 即可运行控制台、CLI、IM 通道与定时任务,数据存于 ~/.octop/ |
🐾 你能用 Octop 做什么
- 个人助理 — 让专属 Agent 帮你写周报、整理资料、定日程,记忆随工作区长期保留。
- 家庭共享 — 一个管理员账号,全家共用;按成员分配不同 Agent 与专家角色。
- 团队助手 — 多 Agent 并行协作,对接飞书 / 钉钉 / 企业微信,把任务自动分发到群里。
- 开发者增效 — 通过 ACP 把编码任务委派给 OpenCode / Claude Code,或在终端用 AI 辅助排障。
- 网页自动化 — 用浏览器 AI+ 自动填表、截图、采集公开信息。
- 定时任务 — 用自然语言配置 Cron,让 Agent 每天按时推送或执行任务。
| 层级 | 技术 |
|---|---|
| 语言 | Python 3.12+ |
| Web 框架 | FastAPI + uvicorn |
| Agent 运行时 | harness-agent |
| IM 桥接 | harness-gateway |
| 控制平面数据库 | SQLite (WAL,默认) 或 PostgreSQL(可选) |
| 前端 | React 18 + TypeScript + Vite + Ant Design |
| 调度 | APScheduler |
| ACP | agent-client-protocol |
| 构建 / 质量 | hatchling · ruff · mypy · pytest |
Octop 基于一系列 Harness 工程实践构建——它将这些专注的运行时组合进同一个进程:
- harness-agent — Agent 运行时:模型路由、工具、技能与对话检查点。
- harness-gateway — 多平台 IM 通道桥接,将各类入站消息归一为统一的处理管线。
- harness-memory — 分层记忆与全文检索,让 Agent 的记忆随工作区一同迁移。
- harness-browser — 基于 CDP 的浏览器自动化,支持持久化配置,用于网页类任务。
Octop 不依赖外部消息队列或中间件,而是通过进程内的 HarnessProcessor 统一路由所有入口——Web UI、IM 与定时任务。最终呈现为一个可重启恢复的单进程:启动时整个状态都从控制面数据库重建(默认 ~/.octop/octop.db,亦可配置 PostgreSQL)。
- 多用户 JWT 认证,支持管理员角色
- 首次运行向导(
octop init) - 交互式 API 文档:
/api/docs(默认关闭 — 在config.json中设置"enable_api_docs": true开启)
- 每位用户可创建多个 Agent;各自拥有独立工作区、供应商、通道和定时任务
- 16 种 MBTI 人格模板 + 自定义系统提示词
- 启动时扫描专家库(
infra/agents/experts/library/) - 工作区后端:本地磁盘、COS、S3 及其他远程存储
- IM 通道:飞书、钉钉、QQ、Discord、企业微信等
- 主动定时任务,支持自然语言和斜杠命令触发
- Web UI、IM、定时任务共用同一套消息处理链路
- Web 控制台 — 对话、Agent 管理、连接器、通道、定时任务、设置
- CLI —
octop run、octop chat、octop acp、管理命令 - HTTP/SSE/WebSocket API — 完整的程序化访问能力
- 知识库 — 基于文档的 RAG 检索;上传文件后,语义检索让 Agent 的回答锚定你的私有知识库
- 插件 — 安装并管理第三方插件(
octop plugin);内置插件随安装注入,按需在控制台一键启用
Octop 支持两个方向的 ACP 集成:
-
入站 — 外部工具使用你的 Octop Agent
octop acp --agent main # 为 Zed、OpenCode 等提供 stdio ACP 服务 -
出站 — Octop 委派给外部编程 Agent
- 控制台 → ACP(
/acp):配置 Runner(按用户全局) - 为 Agent 启用 acp_runner 后,在对话中委派任务
- 控制台 → ACP(
内置出站 Runner 包括 OpenCode、CodeBuddy、Claude Code 和 Codex。
完整配置:docs/acp.md。
以下是我们的中长期规划:
- 资源共享池 — 构建技能 / 子智能体共享池,用户在创建专家时可直接取用,无需从零搭建。
- 专家共享 — 支持用户将自有专家共享给其他用户使用,沉淀优秀配置、避免重复造轮子。
- 浏览器与终端能力补全 — 增强浏览器技能录制(把操作流程录制为可复用技能),并完善终端 AI 助手能力。
- AgentTeams — 支持协调者自主调度、编排多位专家,协同完成复杂多步骤任务。
- 自进化能力 — 将日常对话自动沉淀为技能,让助手随使用不断成长。
- PC / 移动端客户端 — 在 Web 控制台与 IM 通道之外,提供原生桌面与移动端应用。
规划会随社区发展动态调整,以上仅供参考。
- macOS / Linux / Windows
- 无需预先安装 Python — 安装脚本通过 uv 在
~/.octop/下创建隔离的 Python 3.12 虚拟环境 - 现代多核 CPU,并预留数 GB 内存供进程与模型/Embedding 缓存使用;磁盘需容纳数据库、Agent 工作区与文档语料
macOS / Linux — 一键安装(推荐):
curl -fsSL https://finnie-1258344699.cos.ap-guangzhou.myqcloud.com/octop/install.sh | bashWindows(PowerShell):
irm https://finnie-1258344699.cos.ap-guangzhou.myqcloud.com/octop/install.ps1 | iexWindows(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 加入 PATH(~/.octop/bin)。可选附加组件:
# 浏览器自动化(Playwright Chromium)
curl -fsSL https://finnie-1258344699.cos.ap-guangzhou.myqcloud.com/octop/install.sh | bash -s -- --extras browser
# 飞书通道支持
curl -fsSL https://finnie-1258344699.cos.ap-guangzhou.myqcloud.com/octop/install.sh | bash -s -- --extras channels-feishu完整安装选项见 scripts/README.md(--version、--from-source、--mirror 及 Windows 参数)。
Windows 用户:下载安装包 → 安装 → 打开即用 FreeOS(Octop壳+组织能力) — 从 GitHub Releases 下载:
| 平台 | 制品 |
|---|---|
| Windows | FreeOS-desktop-windows-amd64-<version>.exe(64 位)/ FreeOS-desktop-windows-arm64-<version>.exe(ARM64)— NSIS 安装程序,单进程 FreeOS + 宿主内 Organization;不捆绑也不自动拉起 openXYOS Node |
| macOS | FreeOS-desktop-darwin-arm64-<version>.dmg(Apple 芯片)/ FreeOS-desktop-darwin-amd64-<version>.dmg(Intel) |
| Linux | FreeOS-desktop-linux-amd64-<version>.tar.gz / FreeOS-desktop-linux-arm64-<version>.tar.gz |
| 飞牛 NAS(FnOS) | Octop-fnos-docker-<version>.fpk(依赖 Docker)/ Octop-fnos-native-<version>.fpk(无需 Docker)— 通过应用中心安装 |
桌面客户端说明见 desktop/README.md,飞牛打包指南见 fnos/README.md。独立商业组织站见 docs/org-export.md(freeos org export-standalone,默认导出完整 openXYOS 源码树),不是默认安装器里的第二套 Node。
备选 — PyPI(若你已自行管理 Python 环境):
pip install octop
# 可选:pip install "octop[browser]"
# 可选本地 ONNX Embedding 模型缓存(设置 → 模型 → 本地):pip install "octop[local-embedding]"
# 仅下载目录模型到 ~/.octop/embedding_models;不用于对话,也不接入 Memory。从源码用 uv 开发时:
uv sync --extra local-embedding# 前台运行(API + Web 控制台)
octop run
# 自定义主机与端口
octop run --host 0.0.0.0 --port 8088
# 注册为系统服务(systemd / launchd / Windows 服务)
octop service start打开 **http://127.0.0.1:8088**。Docker 首次初始化会自动生成随机管理员密码(写入 /data/.octop/credential.txt),除非设置了 OCTOP_DEFAULT_PASSWORD。交互式 octop init / 设置向导会让你自行设置密码(至少 8 位,且同时包含字母和数字)。向导模型步默认先选本机 Ollama;知识库默认走本机文件夹 + ONNX 向量,云厂商与 ima 是可选项。详见 docs/user-guide.md。
# 构建并启动
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 位且同时包含字母和数字(被应用密码策略拒绝的常见弱密码会自动回退为随机密码)。可通过 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 包装 CLI,不会影响系统 Python。
octop update 只替换 wheel / 二进制,你的 ~/.octop/ 数据库、工作区、密钥与 config.json 均会保留:
octop update # 获取并安装最新版 Octop,若已注册系统服务则自动重启数据库结构会在下次启动时自动迁移;仅当设置向导提示需要迁移时才运行 octop init。跨版本升级前请务必先备份(octop backup)。
所有运行时数据存放在 ~/.octop/。可通过 CLI 管理,也可直接编辑文件。
# LLM 供应商与模型
octop models
octop provider list
# IM 通道
octop channel list
octop channel install
# Skill(按 Agent)
octop skills list --agent main
# 定时任务
octop cron list
octop cron create --help
# 用户(管理员)
octop user list本机优先: Ollama、本机 OpenAI 兼容端点(LM Studio / llama.cpp / vLLM)、本机 ONNX Embedding。云厂商(OpenAI 兼容 API、DashScope 等)是可选项 — 在向导或控制台「模型 → 本地」先配本机,再按需加云。
| 通道 | 所需凭证 |
|---|---|
| 飞书 | App ID、App Secret |
| 钉钉 | App Key、App Secret |
| Bot AppID、Token | |
| Discord | Bot Token |
| 企业微信 | Corp ID、Agent Secret |
| Web 控制台 | 默认启用 |
| 命令 | 说明 |
|---|---|
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 |
供应商预设与模型解析 |
octop skills |
按 Agent 启用/禁用 Skill |
octop plugin |
安装并管理第三方插件 |
octop backup |
导出 / 恢复备份 |
octop clean |
清理 CLI 状态或清空 ~/.octop/ |
octop update |
检查并安装更新 |
完整参考:docs/cli.md。
octop run 启动后访问 **http://127.0.0.1:8088**。
- 对话 — 与 Agent 实时聊天
- Agent — 创建 Agent,选择专家库 / MBTI 人格,配置供应商
- Connector — OAuth 应用与 MCP 网关
- 通道 — IM 平台配置
- 定时任务 — 可视化 Cron 管理
- 知识库 — 管理文档语料与语义检索
- 插件 — 安装、启用与配置插件
- ACP — 配置出站编程 Agent Runner
- 设置 — 用户、安全、TLS、系统
交互式 API 文档:**http://127.0.0.1:8088/api/docs**(默认关闭 — 在 config.json 中设置 "enable_api_docs": true 开启)
~/.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
控制面也可改用 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。
环境变量与 config.json 详见 docs/configuration.md。
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)
单进程架构。重启后从控制面数据库重建状态(默认本地 SQLite;可选 PostgreSQL)。
详见 docs/architecture.md、docs/adr/001-single-process-model.md 与 docs/adr/002-database-backends.md。
产品意图(工作室比喻、Node 只是桥)见 docs/product-contract.zh-CN.md。组织模块目标架构(Dashboard 子 UI + 可导出独立站,单源双交付)见 docs/adr/003-org-ui-single-source-dual-delivery.md 与 docs/org-merge-plan.md(先读文首 Historical vs Current)。
src/octop/
config.py 环境变量配置
launch.py OctopServer 启动 + uvicorn
infra/ 业务核心(agents、gateway、cron、db、users …)
api/ HTTP 层 — FastAPI 路由、JWT、SSE
cli/ CLI 层 — Click 命令
dashboard/ 构建后的 React SPA(wheel 产物)
dashboard/ 前端源码(Vite)— 在此编辑,运行 make build-frontend
docker/ 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。
- 本地优先:配置、对话、工作区与凭证均存储在
~/.octop/。 - 多用户隔离:JWT 认证,按用户隔离 Agent 与工作区。
- 敏感信息脱敏与工具审批:离开工作区前自动脱敏敏感数据;高风险工具或 Shell 命令需依据护栏规则显式审批。
- 工具护栏:可在
~/.octop/security/tool_guard/编辑 Shell 命令规则。 - 无厂商锁定:可自由切换 LLM 供应商、存储后端与 IM 通道。
欢迎贡献代码:
- 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 运行时 — 模型路由、工具、Skill、检查点 |
| harness-gateway | 多平台 IM 通道桥接 |
| harness-memory | 层级召回与全文搜索 |
| harness-browser | CDP 浏览器自动化,支持 profile 持久登录 |
这些
harness-*项目正在筹备开源中,仓库地址将在发布后补充。
如需加入客户企业微信服务群,请扫码:
请扫码进入工作群,如有任何疑问或需求,请直接联系群管理员对接处理。
本项目采用 MIT License。
感谢所有贡献者:


