> ## Documentation Index
> Fetch the complete documentation index at: https://mixroute.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Odysseus

> 如何部署 Odysseus 智能 Agent，并通过自定义端点接入 Mixroute 驱动强大的自托管 AI 工作空间。

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

* 官方 GitHub：[pewdiepie-archdaemon/odysseus](https://github.com/pewdiepie-archdaemon/odysseus)

## 核心特性

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

> **深度研究 (Deep Research)**
>
> 多步骤、自主化的学术与事实搜索、综合提取，最终输出结构完整的高质量可视化报告。

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

## 部署前准备

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

**1. 准备 Mixroute 凭证**

**智能路由节点**

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

1. 获取 Mixroute API 端点地址，通常为：`https://api.mixroute.ai/v1`
2. 在 Mixroute [Smart Routing](https://console.mixroute.ai/smart-route) 页面生成您的智能路由节点 Key。
3. 为不同级别的任务选择模型，指南和约束见 [Smart Routing 指南](/docs/zh-Hans/api-reference/smart-routing)

配置项示意如下：

```text theme={null}
    API Key : <you smart routing key>
    API Host : https://api.mixroute.ai/v1
    Models: auto
```

**传统API节点**

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

配置项示意如下：

```text theme={null}
    API Key : <you api key>
    API Host : https://api.mixroute.ai/v1
    Models: claude-sonnet-5
```

**2. 环境依赖检查**

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

## 部署 Odysseus

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

**Docker Compose (推荐)**

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

```bash theme={null}
# 克隆仓库并进入工作目录
git clone https://github.com/pewdiepie-archdaemon/odysseus.git
cd odysseus

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

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

> [!NOTE]
>
> 如果您希望获得可选的 PDF 渲染、Office 提取支持（需 AGPL PyMuPDF 协议包支持），请在 `up` 前加入构建参数进行手动 Build：
>
> ```bash theme={null}
> docker compose build --build-arg INSTALL_OPTIONAL=true
> docker compose up -d
> ```

**原生 Linux 部署**

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

```bash theme={null}
# 克隆并进入目录
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
```

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

## 首次登录与密码获取

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

**1. 获取初始管理员密码**

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

* **Docker 部署**：
  ```bash theme={null}
  docker compose logs odysseus | grep -C3 'password'
  ```
* **原生 Linux 部署**： 查看 `uvicorn` 或启动终端中输出的临时初始密码。

**2. 进入 Web 控制台**

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

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

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

## 接入 MaxRoute 配置

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

**1. 打开设置面板**

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

![Odysseus Seting](https://mintcdn.com/personal-a5418d9f/w4Hn6AFs5M5kvnax/images/odysseus-seting.png?fit=max\&auto=format\&n=w4Hn6AFs5M5kvnax\&q=85\&s=4cba5cd3a9847270cd144b5e1ebba01c)

**2. 配置服务商 (Provider)**

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

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

  ![Odysseus Add Provider](https://mintcdn.com/personal-a5418d9f/w4Hn6AFs5M5kvnax/images/odysseus-add-provider.png?fit=max\&auto=format\&n=w4Hn6AFs5M5kvnax\&q=85\&s=e6ab543f705168a781d4dadba1d958a8)

**3. 启用并管理模型**

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

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

![Odysseus Models Enabled](https://mintcdn.com/personal-a5418d9f/w4Hn6AFs5M5kvnax/images/odysseus-models-enabled.png?fit=max\&auto=format\&n=w4Hn6AFs5M5kvnax\&q=85\&s=823594619e1a1276cf5a30a06d8c1307)

**4. 享受您的 Odysseus**

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

![Odysseus Finish](https://mintcdn.com/personal-a5418d9f/w4Hn6AFs5M5kvnax/images/odysseus-finish.png?fit=max\&auto=format\&n=w4Hn6AFs5M5kvnax\&q=85\&s=e2b851a0d9abb58fb41c76a867485352)

## 常见问题与进阶

> **Docker 中如何支持 NVIDIA GPU 直通？**
>
> 如果需要在自托管容器中调用或通过 Cookbook 管理本地 GPU，建议：
>
> 1. 运行内置的诊断和配置脚本：
>    ```bash theme={null}
>    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 或记忆检索报错**
>
> 如果遇到 ChromaDB 无法加载或客户端不兼容问题：
>
> ```bash theme={null}
> # 推荐手动卸载可能冲突的轻量客户端，重新强行安装完整版本
> ./venv/bin/pip uninstall chromadb-client -y
> ./venv/bin/pip install --force-reinstall chromadb
> ```

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.