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

​
核心特性

智能 Agent 路由

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

深度研究 (Deep Research)

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

自托管 AI 协作

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

​
部署前准备

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

准备 Mixroute 凭证

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

环境依赖检查

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

​
部署 Odysseus

您可根据系统情况，选择推荐的 Docker 容器化部署或原生的 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

​
首次登录与密码获取

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

获取初始管理员密码

在终端中运行以下命令查看输出：
  • Docker 部署： 
    docker compose logs odysseus | grep -C3 'password'
  • 原生 Linux 部署： 查看 uvicorn 或启动终端中输出的临时初始密码。
2

进入 Web 控制台

使用用户名为 admin 和刚刚获取到的密码登录。
  • 本地环境访问：http://127.0.0.1:7000
  • 远程云服务器访问：http://<your-server-ip>:7000
默认配置下odysseus只监听127.0.0.1本地，若要在云端服务器部署，请参考下方常见错误和进阶的网络报错或容器监听问题项

​
接入 MaxRoute 配置

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

打开设置面板

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

配置服务商 (Provider)

在 Settings 中的 Providers/Endpoints 页面添加新的自定义端点：
  • Base URL: https://api.mixroute.ai/v1
  • API Key: 填入您的 Mixroute API Key （例如 sk-xxxxxxxx） Odysseus Add Provider
3

启用并管理模型

添加端点后，Odysseus 会自动探测（Probe）并加载该端点下返回的可用模型。 您可以在列表中将常用的模型设置为启用状态，或将其指派为全局默认角色（如默认聊天、深度研究、Task 调度、视觉等角色）。
经过测试，GPT系列在odysseus中表现良好，建议配合GPT的模型使用。
Odysseus Models Enabled
4

享受您的 Odysseus

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

​
常见问题与进阶

如果需要在自托管容器中调用或通过 Cookbook 管理本地 GPU，建议：
  1. 运行内置的诊断和配置脚本： 
    scripts/check-docker-gpu.sh --install-nvidia-toolkit --enable-nvidia-overlay
  2. 此脚本会自动在 .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 无法加载或客户端不兼容问题：
# 推荐手动卸载可能冲突的轻量客户端，重新强行安装完整版本
./venv/bin/pip uninstall chromadb-client -y
./venv/bin/pip install --force-reinstall chromadb
配置完成后，Odysseus 所有的后续功能（深度研究、文件检索、日历/待办及邮件 Triage）都将基于您在设置中绑定和配置的 Mixroute 端点进行驱动，享受到强大且极具性价比的云端大模型服务。