Dot2API

把你的 OpenAI Dot 变成兼容 OpenAI 与 Claude 格式的 API

English | 简体中文

Python Docker License

> [!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)。