odysseus-dev/odysseus · 上手攻略

仓库：odysseus-dev/odysseus
链接：https://github.com/odysseus-dev/odysseus
分类：AI · 自托管工作区 / 全能 AI OS
作者：Tom
更新：2026-07-16

这是什么

Odysseus 是一个自托管的 AI 工作空间，用 Docker 一键部署后，在本地获得一个类似 Notion + ChatGPT + Perplexity + 邮件客户端 + 日历的集合体，但全部支持本地模型和私有数据。

核心功能模块包括： - Chat + Agents：支持本地模型（Ollama）和 API 模型，具备工具调用、MCP 协议、文件处理、shell 执行、记忆和 Skills - Deep Research：多步骤网络研究，自动抓取网页、读源文档、生成研究报告 - Compare：盲测多模型并排对比，辅助模型选型 - Documents：写作为先的编辑器，支持 AI 润色、Markdown、HTML、CSV 语法高亮 - Email：IMAP/SMTP 邮箱，支持分类、标签、摘要、AI 回复草稿 - Notes / Tasks / Calendar：笔记、任务、提醒、定时 Agent 任务、CalDAV 日历同步 - Cookbook：硬件感知本地模型推荐、下载和 Serving 管理

一句话定位：一个你完全自己掌控的 AI 操作系统，所有数据留本地，所有模型可替换。

解决什么问题

目前主流 AI 工具（ChatGPT、Claude、Gemini）都是 SaaS，数据在云端，模型由供应商决定。Odysseus 解决的是：

数据隐私：邮件、笔记、文档、任务——所有内容都在你自己的服务器上，不经过第三方
本地模型：可以用 Ollama 在本地跑 Llama、Mistral 等模型，省 API 费用，延迟更低
统一入口：不用在多个工具之间切换——聊天、邮件、日历、研究、文档都在同一个界面里
可控性：可以连自己的向量数据库（ChromaDB）、自己的 SearXNG 搜索实例，数据流完全透明

快速安装

环境要求

Docker + Docker Compose
（可选）NVIDIA GPU + CUDA：用于本地模型加速Serving
（可选）Apple Silicon Mac：支持 Metal GPU 加速
Python 3.11+：如选择原生安装（非 Docker）

Docker 一键启动（推荐）

git clone https://github.com/pewdiepie-archdaemon/odysseus.git
cd odysseus
cp .env.example .env          # 可选，保留默认配置
docker compose up -d --build

⚠️ 注意：dev 是默认分支，包含最新变更；main 分支更稳定。稳定版使用请切换到 main： git clone -b main https://github.com/pewdiepie-archdaemon/odysseus.git

启动完成后访问 http://localhost:7000。

首次启动时，管理后台密码会输出在终端（Docker 下用 docker compose logs odysseus 查看）。

Apple Silicon Mac 原生安装（GPU 加速）

git clone https://github.com/pewdiepie-archdaemon/odysseus.git
cd odysseus
./start-macos.sh
# 启动在 http://127.0.0.1:7860

若需局域网访问：

ODYSSEUS_HOST=0.0.0.0 ./start-macos.sh
# 然后通过 http://<tailscale-ip>:7860 访问

构建含可选组件的镜像

默认镜像是精简版。如需 PDF 查看器和 Office 文档提取（包含 AGPL PyMuPDF），构建时加参数：

docker compose build --build-arg INSTALL_OPTIONAL=true
docker compose up -d --build

核心功能用法

首次配置

首次登录后，在 Settings 里配置： - AI 模型提供商（OpenAI API / Anthropic / Ollama 本地模型） - 搜索服务（SearXNG 已随 Docker Compose 一起启动，默认可用） - 邮件账户（IMAP/SMTP）

Chat + Agents

支持本地 Ollama 模型和所有 OpenAI API 兼容模型
内置工具：文件读写、shell 执行、网页搜索、MCP 协议扩展
Skills 系统：可安装扩展能力（类似 GPTs 的 Actions）
Memory：跨会话记忆，保持上下文连续性

Deep Research

输入研究主题，Odysseus 会： 1. 分解为多个研究子问题 2. 通过 SearXNG 搜索相关网页 3. 抓取并阅读源文档内容 4. 综合所有来源生成结构化报告（附引用来源）

⚠️ 注意：SearXNG 搜索实例已包含在 Docker Compose 中（默认仅本地访问），无需额外配置搜索服务。

Cookbook（本地模型管理）

Cookbook 模块提供： - 根据你的硬件（CPU/GPU/VRAM）推荐合适的模型 - 一键下载模型到本地（Hugging Face） - 启动本地模型 Serving（通过 Ollama 或其他引擎） - 连接远程 GPU 服务器（通过 SSH Key）

Docker 环境下，模型下载到 ./data/huggingface（容器内 ~/.cache/huggingface），Python CLI 和 Serving 引擎装在 ./data/local（容器内 ~/.local），重建容器不会丢失。

Documents

写作优先的编辑器，支持： - AI 润色和修改建议 - Markdown 实时预览 - HTML / CSV 导入 - 语法高亮

Email

IMAP/SMTP 邮箱集成，支持： - 收件箱分类和标签 - AI 摘要 - 回复草稿 AI 生成 - 邮件提醒

Notes / Tasks / Calendar

Notes：笔记，支持 AI 辅助写作
Tasks：任务清单，支持提醒
Calendar：CalDAV 同步，可设置定时 Agent 任务

坑与注意

端口冲突：默认用 7000，如被占用，在 .env 中设置 APP_PORT=7001 然后重建容器。
macOS Docker 无 GPU：macOS 上 Docker 容器无法访问 Metal GPU，本地模型Serving 只能走 CPU。Cookbook 检测到的是 CPU 模式。如需 GPU 加速，请使用原生安装脚本（./start-macos.sh）。
NVIDIA GPU 需额外配置：默认 Docker 容器是 CPU 模式。要启用 NVIDIA GPU，需在主机安装 NVIDIA Container Toolkit，然后运行： bash scripts/check-docker-gpu.sh --install-nvidia-toolkit --enable-nvidia-overlay 或手动在 .env 加入 COMPOSE_FILE=docker-compose.yml:docker/gpu.nvidia.yml。
不要直接暴露到公网：默认只绑定 127.0.0.1，不要将原始端口直接暴露到公网。部署到 LAN/VPN 后端时也要保持 AUTH_ENABLED=true。
dev 分支不稳定：dev 是默认分支，更新快但可能有 bug。生产环境建议用 main 分支。
Docker Socket 默认未挂载：默认 Docker Compose 没有挂载 /var/run/docker.sock，因此无法从容器内管理宿主机 Docker。如需此功能，需显式添加 docker/host-docker.yml 覆盖（高权限操作，需理解风险）。
首次启动密码看日志：首次 admin 密码只在启动日志里打印一次，务必在启动后立即记录并修改密码。
Apple Silicon Mac 原生启动端口是 7860：不是 7000，容易搞混。

与同类对比

工具	部署方式	数据存储	本地模型	主要定位
Odysseus	自托管 Docker	全本地	✅ Ollama 内置	全能 AI 工作空间
Open WebUI	Docker 单组件	部分本地	✅ Ollama	纯聊天 UI
FastGPT	Docker	可本地	✅	知识库 + RAG
Dify	Docker	可本地	✅	AI 应用编排
ChatGPT	SaaS	云端	❌	通用对话
Notion	SaaS	云端	❌	文档 + 笔记

Odysseus 的核心差异：不只是聊天界面，而是一个完整的工作空间——邮件、日历、笔记、文档、Deep Research 全在一起，且全部支持本地部署和本地模型。

一句话推荐结论

如果你想要一个完全私有、数据不离开自己服务器、同时支持本地模型和云端 API 的 AI 工作空间，Odysseus 是目前功能最全、部署最简单（一条 Docker 命令）的选择——聊天、研究、邮件、笔记、日历全部在一起，非常适合对数据隐私有要求的技术团队或个人开发者。