> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mixroute.ai/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)
## 核心特性
内置基于工具调用、网络搜索、文件读写和 Shell 执行的自主 Agent，支持 MCP 服务扩展。
多步骤、自主化的学术与事实搜索、综合提取，最终输出结构完整的高质量可视化报告。
配备富文本 Markdown 编辑器，AI 可以根据上下文协同编辑文档，完美适配移动端。
## 部署前准备
在开始部署前，请确保您的系统满足以下要求：
**Smart Routing** 是一项智能模型路由能力，能够根据输入任务的复杂程度，自动将请求分配至最合适的模型，通过智能分配起到降本增效的作用。
1. 获取 Mixroute API 端点地址，通常为：`https://api.mixroute.ai/v1`
2. 在 Mixroute [Smart Routing](https://console.mixroute.ai/smart-route) 页面生成您的智能路由节点 Key。
3. 为不同级别的任务选择模型，指南和约束见 [Smart Routing 指南](/cn/smart-routing)
配置项示意如下：
```text theme={null}
API Key :
API Host : https://api.mixroute.ai/v1
Models: auto
```
1. 获取 Mixroute API 端点地址，通常为：`https://api.mixroute.ai/v1`
2. 在 Mixroute 控制台生成您的 API Key。
3. 确定需要使用的模型名称，如 `claude-sonnet-5`（需在 Mixroute 控制台已启用该模型）。
配置项示意如下：
```text theme={null}
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 一键启动 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
```
如果您希望获得可选的 PDF 渲染、Office 提取支持（需 AGPL PyMuPDF 协议包支持），请在 `up` 前加入构建参数进行手动 Build：
```bash theme={null}
docker compose build --build-arg INSTALL_OPTIONAL=true
docker compose up -d
```
如果您倾向于直接在宿主机（物理机/虚拟机）上部署，请参考以下指南：
```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
```
原生部署需要确保系统中已安装必要的依赖（如 `sqlite3`）。如果需要利用 Odysseus 的 Cookbook 功能下载或管理后台服务，建议额外安装 `tmux`。
## 首次登录与密码获取
默认情况下，Odysseus 在首次启动时会自动创建管理员账号 `admin`，并将其生成的随机初始密码输出到启动日志中。
在终端中运行以下命令查看输出：
* **Docker 部署**：
```bash theme={null}
docker compose logs odysseus | grep -C3 'password'
```
* **原生 Linux 部署**： 查看 `uvicorn` 或启动终端中输出的临时初始密码。
使用用户名为 `admin` 和刚刚获取到的密码登录。
* 本地环境访问：`http://127.0.0.1:7000`
* 远程云服务器访问：`http://:7000`
默认配置下odysseus只监听127.0.0.1本地，若要在云端服务器部署，请参考下方**常见错误和进阶**的网络报错或容器监听问题项
## 接入 MaxRoute 配置
成功登录后，请按照以下步骤配置 Mixroute 的自定义端点，以驱动您的 Odysseus 智能助理。
在左下角点击 **Settings** 进入全局系统设置。
在 **Settings** 中的 Providers/Endpoints 页面添加新的自定义端点：
* **Base URL**: `https://api.mixroute.ai/v1`
* **API Key**: 填入您的 Mixroute API Key （例如 `sk-xxxxxxxx`）
添加端点后，Odysseus 会自动探测（Probe）并加载该端点下返回的可用模型。 您可以在列表中将常用的模型设置为启用状态，或将其指派为全局默认角色（如默认聊天、深度研究、Task 调度、视觉等角色）。
经过测试，GPT系列在odysseus中表现良好，建议配合GPT的模型使用。
返回 Chat 主页面，即可顺利使用 Mixroute 的底层模型来完成对话和启动强大的智能 Agent。
## 常见问题与进阶
如果需要在自托管容器中调用或通过 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 无法加载或客户端不兼容问题：
```bash theme={null}
# 推荐手动卸载可能冲突的轻量客户端，重新强行安装完整版本
./venv/bin/pip uninstall chromadb-client -y
./venv/bin/pip install --force-reinstall chromadb
```
配置完成后，Odysseus 所有的后续功能（深度研究、文件检索、日历/待办及邮件 Triage）都将基于您在设置中绑定和配置的 Mixroute 端点进行驱动，享受到强大且极具性价比的云端大模型服务。