Dot2API
把你的 OpenAI Dot 变成兼容 OpenAI 与 Claude 格式的 API
English | 简体中文
> [!NOTE]
> 本项目仅供技术研究,以及配合你自己的 Dot 个人使用。请遵守 OpenAI 的使用条款和当地法律,使用后果由使用者自行承担。
> [!WARNING]
> 任何持有 API key 的人都能向你的 Dot 下指令,而 Dot 可能连着你的各种应用。只把 key 发给和你自己同等可信的调用方。见[安全政策](SECURITY.md)。
## 项目简介
Dot2API 是一个自行部署的网关,把一个 OpenAI Dot 以 OpenAI Chat Completions 和 Anthropic Messages 两种格式暴露出来。把现有 SDK 的地址指向它:每个请求会被入队,你的 Dot 通过 MCP Events 被唤醒,再经 MCP 领取并作答,回复以普通的 completion 返回。
和多数 2API 项目不同,Dot2API 不逆向网页接口,也不接触你的 OpenAI 账号凭据。它使用公开的 MCP 2.0 连接器与 Events 协议,本身不调用任何模型。
### 架构
```mermaid
flowchart LR
classDef access fill:#e1f5fe,stroke:#01579b
classDef core fill:#fff3e0,stroke:#e65100
classDef infra fill:#e8f5e9,stroke:#1b5e20
classDef upstream fill:#fce4ec,stroke:#880e4f
Clients["API 客户端
OpenAI SDK · Anthropic SDK · curl"]
subgraph Core["Dot2API"]
direction TB
Compat["兼容层
/v1/chat/completions · /v1/messages"]
Tasks["任务内核
租约 · 重试 · 截止时间"]
Events["事件 outbox
签名 webhook"]
MCP["MCP 端点
/mcp"]
Compat --> Tasks
Tasks --> Events
MCP --> Tasks
end
Database[("SQLite")]
Dot["OpenAI Dot"]
Clients -->|请求| Compat
Compat -.->|回复| Clients
Events -->|task.available| Dot
Dot -->|claim_task / complete_task| MCP
Tasks --> Database
class Clients access
class Compat,Tasks,Events,MCP core
class Database infra
class Dot upstream
```
### 核心能力
| 领域 | 能力 |
|---|---|
| 接口 | OpenAI Chat Completions、Anthropic Messages、模型列表,以及异步任务接口 |
| 客户端 | OpenAI 兼容与 Anthropic 兼容的 SDK、自动化工具和普通 HTTP 调用 |
| 流式 | 两种格式的 SSE,Dot 工作期间持续保活 |
| 可靠性 | 持久化任务、原子领取、租约、有限重试、截止时间,调用方断开时自动取消 |
| 事件 | MCP Events 订阅、回调验证、带签名的至少一次 webhook 投递 |
| 安全 | 有期限且只存指纹的密钥、按权限划分的身份、限流、审计记录 |
| 运维 | 一条命令完成初始化,存活与就绪探针,一致性备份,加固的容器镜像 |
### 能力边界
Dot 是 Agent,不是模型端点,所以这里的兼容是格式兼容,不是行为兼容。
| 方面 | 表现 |
|---|---|
| 延迟 | 每次回复需要几秒到几分钟。请求默认最多等 300 秒,超时返回 504 和一个可稍后读取的 `task_id` |
| 流式 | 完整回复在一个增量里一次性到达,不是逐 token 输出 |
| 内容 | 只支持文本。图片和工具结果块返回 400 |
| 工具调用 | 不支持。`tools` 会被忽略;Dot 使用它自己的工具,不会返回 tool call |
| 参数 | 采样参数和 `max_tokens` 会被接受并忽略。token 用量固定为 0 |
| 并发 | 一个 Dot 处理一个队列,请求需要排队 |
因此 Dot2API 适合定时任务、自动化流程、自建机器人,以及让其他 Agent 委托一件事。它不能作为 Codex、Claude Code 这类编码 Agent 的模型后端,也不适合实时聊天前端。
## 快速开始
Dot 从 OpenAI 的网络连过来,所以服务需要一个公网 HTTPS 地址。下面两种方式都只监听本机,需要在前面放一个 TLS 反向代理。见[部署文档](docs/deployment.md)。
### Docker Compose
```bash
git clone https://github.com/Pluviobyte/dot2api.git
cd dot2api
docker compose build
docker compose run --rm dot2api init
docker compose run --rm dot2api setup
docker compose up -d
```
### 从源码运行
需要 Python 3.11 或更高版本,以及 [uv](https://docs.astral.sh/uv/)。
```bash
uv sync --frozen --no-dev
uv run --no-sync dot2api init
uv run --no-sync dot2api setup
uv run --no-sync dot2api serve
```
`setup` 会输出两个凭据,只显示一次,数据库只保存指纹:
```json
{"api_key": "d2a_...", "dot_token": "d2a_...", "queue": "dot"}
```
- `api_key` 给调用方填进 SDK。
- `dot_token` 给 Dot 访问 MCP 端点用。
## 接入 Dot
1. 添加一个 MCP 连接器,地址为 `https:///mcp`,用 `dot_token` 作为 bearer 凭据。如果连接器无法发送认证头,用 `DOT2API_CAPABILITY_URLS=1` 启动服务,并使用 `https:///mcp/`。
2. 让 Dot 监听队列 `dot` 上的 `task.available` 事件。
3. 给 Dot 一段常驻指令:列出排队任务、领取、回答对话、提交结果。
完整步骤、可直接粘贴的指令提示词和排障方法见[接入 Dot](docs/dot.md)。
## API 用法
| 端点 | 用途 |
|---|---|
| `POST /v1/chat/completions` | OpenAI 兼容的对话补全 |
| `POST /v1/messages` | Anthropic 兼容的消息接口 |
| `GET /v1/models` | 模型列表,只有 `dot` |
| `POST /v1/tasks` · `GET /v1/tasks/{task_id}` | 异步提交与取回结果 |
| `POST /mcp` | Dot 使用的 MCP 工具与事件订阅 |
| `GET /healthz` · `GET /readyz` | 存活与就绪检查 |
凭据可以用 `Authorization: Bearer ` 或 `x-api-key: ` 传递。`model` 可以填任意值,会原样返回。
### curl
```bash
curl https://dot2api.example.com/v1/chat/completions \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "dot",
"messages": [{"role": "user", "content": "总结我今天的未读邮件。"}]
}'
```
### OpenAI SDK
```python
from openai import OpenAI
client = OpenAI(base_url="https://dot2api.example.com/v1", api_key=API_KEY, timeout=600)
reply = client.chat.completions.create(
model="dot",
messages=[{"role": "user", "content": "总结我今天的未读邮件。"}],
)
print(reply.choices[0].message.content)
```
### Anthropic SDK
```python
from anthropic import Anthropic
client = Anthropic(base_url="https://dot2api.example.com", api_key=API_KEY, timeout=600)
reply = client.messages.create(
model="dot",
max_tokens=1024,
messages=[{"role": "user", "content": "总结我今天的未读邮件。"}],
)
print(reply.content[0].text)
```
客户端超时要设得比完成超时更长,或者把 `stream` 设为 true,让保活帧维持连接。请求与响应的细节见[接口文档](docs/api.md)。
## 配置
| 变量 | 默认值 | 含义 |
|---|---|---|
| `DOT2API_DATA_DIR` | `var` | 数据库与加密密钥目录 |
| `DOT2API_HOST` | `127.0.0.1` | 监听地址 |
| `DOT2API_PORT` | `8788` | 监听端口 |
| `DOT2API_QUEUE` | `dot` | Dot 订阅的队列 |
| `DOT2API_COMPLETION_TIMEOUT` | `300` | 请求等待 Dot 的秒数,超过后返回 504 |
| `DOT2API_TASK_TTL` | `3600` | 无人应答的请求在多少秒后过期 |
| `DOT2API_RATE_PER_MINUTE` | `120` | 每个身份每分钟的请求上限 |
| `DOT2API_CAPABILITY_URLS` | 关闭 | 设为 `1` 允许把令牌放在 MCP 路径里 |
签发更多 key、区分调用方、轮换令牌以及各管理命令见[配置文档](docs/configuration.md)。
## 文档
- [接入 Dot](docs/dot.md)
- [接口与 MCP 协议](docs/api.md)
- [架构与投递语义](docs/architecture.md)
- [配置与身份管理](docs/configuration.md)
- [部署、备份与恢复](docs/deployment.md)
- [安全政策](SECURITY.md)
- [贡献指南](CONTRIBUTING.md)
## 开发
```bash
uv sync --frozen
uv run pytest
uv run ruff check .
uv run ruff format --check .
uv run python -m build
uv run python scripts/check_release.py
```
## 许可证
[MIT](LICENSE)。