Odysseus

Odysseus 是一个自托管的 AI 工作空间，旨在提供类似于 ChatGPT 和 Claude 的私有化 Web 体验。它不仅支持本地模型，还能无缝对接云端 API（如 Mixroute），具备强大的 Agent 智能体路由、深度研究（Deep Research）、文档协作协作编辑、持久化记忆（ChromaDB）和技能进化系统。

官方 GitHub：pewdiepie-archdaemon/odysseus

核心特性

智能 Agent 路由

内置基于工具调用、网络搜索、文件读写和 Shell 执行的自主 Agent，支持 MCP 服务扩展。

深度研究 (Deep Research)

多步骤、自主化的学术与事实搜索、综合提取，最终输出结构完整的高质量可视化报告。

自托管 AI 协作

配备富文本 Markdown 编辑器，AI 可以根据上下文协同编辑文档，完美适配移动端。

部署前准备

在开始部署前，请确保您的系统满足以下要求：

准备 Mixroute 凭证

智能路由节点
传统API节点

Smart Routing 是一项智能模型路由能力，能够根据输入任务的复杂程度，自动将请求分配至最合适的模型，通过智能分配起到降本增效的作用。

获取 Mixroute API 端点地址，通常为：https://api.mixroute.ai/v1
在 Mixroute Smart Routing 页面生成您的智能路由节点 Key。
为不同级别的任务选择模型，指南和约束见 Smart Routing 指南

配置项示意如下：

    API Key : <you smart routing key>
    API Host : https://api.mixroute.ai/v1
    Models: auto

获取 Mixroute API 端点地址，通常为：https://api.mixroute.ai/v1
在 Mixroute 控制台生成您的 API Key。
确定需要使用的模型名称，如 claude-sonnet-5（需在 Mixroute 控制台已启用该模型）。

配置项示意如下：

    API Key : <you api key>
    API Host : https://api.mixroute.ai/v1
    Models: claude-sonnet-5

环境依赖检查

Docker 部署：需要安装 Docker 和 Docker Compose。
原生 Linux 部署：需要 Python 3.11 或更高版本，并确保系统已安装 git。

部署 Odysseus

您可根据系统情况，选择推荐的 Docker 容器化部署或原生的 Linux 部署方式。

Docker Compose (推荐)
原生 Linux 部署

通过 Docker Compose 一键启动 Odysseus 及其配套服务（ChromaDB、SearXNG 等），全部数据保存在本地 data/ 目录中。

# 克隆仓库并进入工作目录
git clone https://github.com/pewdiepie-archdaemon/odysseus.git
cd odysseus

# 创建并配置文件（可选，用于修改端口或绑定地址）
cp .env.example .env

# 启动服务
docker compose up -d --build

如果您希望获得可选的 PDF 渲染、Office 提取支持（需 AGPL PyMuPDF 协议包支持），请在 up 前加入构建参数进行手动 Build：

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

如果您倾向于直接在宿主机（物理机/虚拟机）上部署，请参考以下指南：

# 克隆并进入目录
git clone https://github.com/pewdiepie-archdaemon/odysseus.git
cd odysseus

# 创建并激活 Python 虚拟环境 (Python 3.11+)
python3 -m venv venv
source venv/bin/activate

# 安装依赖
pip install -r requirements.txt

# 运行初始化脚本
python setup.py

# 启动应用（绑定 127.0.0.1 端口 7000）
python -m uvicorn app:app --host 127.0.0.1 --port 7000

原生部署需要确保系统中已安装必要的依赖（如 sqlite3）。如果需要利用 Odysseus 的 Cookbook 功能下载或管理后台服务，建议额外安装 tmux。

首次登录与密码获取

默认情况下，Odysseus 在首次启动时会自动创建管理员账号 admin，并将其生成的随机初始密码输出到启动日志中。

获取初始管理员密码

在终端中运行以下命令查看输出：

Docker 部署：

docker compose logs odysseus | grep -C3 'password'

原生 Linux 部署：查看 uvicorn 或启动终端中输出的临时初始密码。

进入 Web 控制台

使用用户名为 admin 和刚刚获取到的密码登录。

本地环境访问：http://127.0.0.1:7000
远程云服务器访问：http://<your-server-ip>:7000

默认配置下odysseus只监听127.0.0.1本地，若要在云端服务器部署，请参考下方常见错误和进阶的网络报错或容器监听问题项

接入 MaxRoute 配置

成功登录后，请按照以下步骤配置 Mixroute 的自定义端点，以驱动您的 Odysseus 智能助理。

打开设置面板

在左下角点击 Settings 进入全局系统设置。

配置服务商 (Provider)

在 Settings 中的 Providers/Endpoints 页面添加新的自定义端点：

Base URL: https://api.mixroute.ai/v1
API Key: 填入您的 Mixroute API Key （例如 sk-xxxxxxxx）

启用并管理模型

添加端点后，Odysseus 会自动探测（Probe）并加载该端点下返回的可用模型。您可以在列表中将常用的模型设置为启用状态，或将其指派为全局默认角色（如默认聊天、深度研究、Task 调度、视觉等角色）。

经过测试，GPT系列在odysseus中表现良好，建议配合GPT的模型使用。

享受您的 Odysseus

返回 Chat 主页面，即可顺利使用 Mixroute 的底层模型来完成对话和启动强大的智能 Agent。

常见问题与进阶

Docker 中如何支持 NVIDIA GPU 直通？

如果需要在自托管容器中调用或通过 Cookbook 管理本地 GPU，建议：

运行内置的诊断和配置脚本：

scripts/check-docker-gpu.sh --install-nvidia-toolkit --enable-nvidia-overlay

此脚本会自动在 .env 中添加：COMPOSE_FILE=docker-compose.yml:docker/gpu.nvidia.yml 启用 NVIDIA 容器工具包映射。

网络报错或容器监听问题

默认配置下容器仅监听 127.0.0.1。

如果需要直接从局域网或公网通过 IP 访问，请修改 .env 中的 APP_BIND=0.0.0.0，然后重启容器。
在生产环境下，强烈建议保持 127.0.0.1 监听，并使用 Nginx, Caddy 或 Cloudflare Tunnel 进行反向代理并加持 SSL 证书。

ChromaDB 或记忆检索报错

如果遇到 ChromaDB 无法加载或客户端不兼容问题：

# 推荐手动卸载可能冲突的轻量客户端，重新强行安装完整版本
./venv/bin/pip uninstall chromadb-client -y
./venv/bin/pip install --force-reinstall chromadb

配置完成后，Odysseus 所有的后续功能（深度研究、文件检索、日历/待办及邮件 Triage）都将基于您在设置中绑定和配置的 Mixroute 端点进行驱动，享受到强大且极具性价比的云端大模型服务。

对话型 AI

编程开发

技术工程

翻译场景

核心特性

智能 Agent 路由

深度研究 (Deep Research)

自托管 AI 协作

部署前准备

部署 Odysseus

首次登录与密码获取

接入 MaxRoute 配置

常见问题与进阶

​核心特性

智能 Agent 路由

深度研究 (Deep Research)

自托管 AI 协作

​部署前准备

​部署 Odysseus

​首次登录与密码获取

​接入 MaxRoute 配置

​常见问题与进阶

核心特性

部署前准备

部署 Odysseus

首次登录与密码获取

接入 MaxRoute 配置

常见问题与进阶