## SimpleClaw Provider API

SimpleClaw предоставляет единый минимальный Provider API и каталог разрешённых моделей. У одного пользователя может быть любое число API-ключей; все они используют общий баланс credits и квоты аккаунта.

- Public documentation: /docs
- OpenAPI: /v1/docs
- Models: GET /v1/models — публичный каталог доступных сейчас моделей LLMRouter с display_name. pricing содержит credits за 1 млн input, output, cache и reasoning токенов либо null, если ставка ещё не настроена.
- Model favorites: GET /v1/models/favorites, PUT/DELETE /v1/models/{publicId}/favorite — личное избранное сессионного пользователя
- Chat completions: POST /v1/chat/completions
- Authentication: Authorization: Bearer sc_your_key
- Request body: { "model": "model-id", "messages": [{ "role": "user", "content": "text" }] }

- Anthropic Messages (Claude Code): POST /v1/messages
- Authentication: Authorization: Bearer sc_your_key or x-api-key: sc_your_key; header anthropic-version: 2023-06-01
- Request body: { "model": "anthropic-model-id", "max_tokens": 1024, "messages": [{ "role": "user", "content": "text" }], "stream": true }

- OpenAI Responses (Codex): POST /v1/responses
- Authentication: Authorization: Bearer sc_your_key
- Request body: { "model": "model-id", "input": [{ "type": "message", "role": "user", "content": [{ "type": "input_text", "text": "text" }] }], "stream": true }

Provider API принимает OpenAI-совместимый Chat Completions запрос: model, messages, max_tokens и temperature. Поле message временно поддержано для обратной совместимости; streaming и tools в этом transport не поддерживаются. Для Codex есть stateless OpenAI Responses transport с instructions, message/function_call/function_call_output и function tools, а также конечным response.* SSE; previous_response_id, hosted tools, images и files не поддержаны. Для Claude Code есть Anthropic Messages transport с system, text/tool_use/tool_result blocks и конечным SSE. Он принимает только включённые модели ANTHROPIC; image, document, cache и thinking blocks не поддержаны. Доступ требует активной Provider-подписки или предоплаченного баланса в credits. SimpleClaw валидирует ключ, блокировку пользователя, недельный бюджет ключа и общий доступный остаток, затем вызывает внутренний Model Gateway. Gateway выбирает upstream-провайдера; его URL и сервисный токен не выдаются клиенту. Баланс и лимиты ключей измеряются в credits; rate card определяет расход credits за 1 млн input, output, cache и reasoning токенов. Не передавайте API-ключи в документацию, source control или browser storage.

Готовые команды настройки: /docs/codex и /docs/claude-code. В каждом руководстве пользователь заменяет только API-ключ и public model ID, затем целиком вставляет один скрипт в терминал. Скрипт создаёт изолированный launcher, но не сохраняет API-ключ в файл или профиль оболочки.

Read-only MCP: POST /v1/mcp — public tools search_docs и list_models. POST /v1/mcp/account — собственные limits/usage после OAuth 2.1 Authorization Code + обязательного PKCE S256, scope account:read и resource/audience validation. MCP не выполняет inference, платежи, админские операции и не раскрывает ключи.

Account linking: GET /v1/auth/identities возвращает только provider и createdAt для способов входа владельца сессии. GET /v1/auth/{telegram|vk|yandex|sber}/link начинает подтверждённую привязку из действующей сессии. Callback требует тот же server-side session и одноразовый provider state, не создаёт новую сессию и не раскрывает subject. Если identity уже принадлежит другому пользователю, возвращается 409 IDENTITY_ALREADY_LINKED; автоматического объединения аккаунтов, платежей, подписок, ключей и usage нет.

Cabinet session: после входа сервер выдаёт HttpOnly active-session cookie на 5 минут и отдельную HttpOnly refresh cookie на 30 дней. Успешное обращение к кабинету продлевает active session ещё на 5 минут. После простоя сервер бесшовно выпускает новую active session по действующему refresh token, без повторного обращения к внешнему провайдеру. Refresh token имеет абсолютный срок и не продлевается. Logout на устройстве и блокировка пользователя отзывают соответствующие active и refresh credentials.