Зачем этот глоссарий

Когда OpenClaw интегрируется с внешними сервисами, появляются технические термины: MCP, API, webhook, OAuth, endpoint. Этот словарь объясняет их простым языком применительно к работе с агентом.

MCP (Model Context Protocol)

Открытый протокол, разработанный Anthropic, для стандартизации взаимодействия AI-агентов с внешними инструментами и источниками данных.

Простая аналогия: USB — единый стандарт подключения устройств к компьютеру. MCP — единый стандарт подключения инструментов к AI-агенту.

До MCP: каждый агент и каждый инструмент требовали уникальной интеграции. OpenClaw + Notion = один код. OpenClaw + Salesforce = другой код. Разработчики дублировали работу.

С MCP: инструмент публикует MCP-сервер один раз. Любой MCP-совместимый агент (включая OpenClaw) может его использовать.

Что уже доступно через MCP для OpenClaw:

Базы данных (PostgreSQL, MySQL, SQLite)
Файловые системы
Git репозитории
GitHub, GitLab
Slack, Linear, Notion
Браузер (Puppeteer)
Поисковые системы (Brave, Tavily)

Подключение MCP-сервера:

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "POSTGRES_URL": "postgresql://user:pass@localhost/db"
      }
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "ghp_your_token"
      }
    }
  }
}

После настройки агент может напрямую работать с PostgreSQL или GitHub без дополнительного кода.

API (Application Programming Interface)

Набор правил и форматов для взаимодействия двух программ. API определяет: что можно запросить, в каком формате отправить запрос, и что получить в ответ.

Аналогия: меню в ресторане. Вы (клиент) выбираете из предложенных позиций — нельзя попросить то, чего нет в меню. Кухня (сервер) готовит и возвращает заказанное в стандартном формате.

Как OpenClaw использует API:

Отправляет задачи в GPT-4o через OpenAI API
Читает письма через Gmail API
Публикует посты через Telegram Bot API
Получает данные из Google Analytics API

Типы API:

REST API — самый распространённый. Запросы через HTTP (GET, POST, PUT, DELETE)
GraphQL — гибкий запрос данных, клиент выбирает что получить
WebSocket — двустороннее соединение для реального времени

Пример использования API в задаче OpenClaw:

"Зайди в CRM через API, получи список сделок в статусе 'переговоры',
для каждой отправь персональное письмо через API SendGrid"

Webhook

Механизм, при котором сервис автоматически отправляет уведомление на указанный URL при наступлении события.

Разница от API:

API (polling): вы регулярно спрашиваете «есть что-то новое?» — как проверять почту каждые 5 минут
Webhook (push): сервис сам сообщает «произошло событие» — как получить уведомление о новом письме

Аналогия: webhook — это дверной звонок. Вместо того чтобы каждые 5 минут выглядывать в окно, вы ждёте звонка.

Webhook в OpenClaw:

{
  "webhooks": {
    "github": {
      "url": "https://your-server.com/webhooks/github",
      "events": ["pull_request.opened", "issue.created"],
      "secret": "webhook-secret"
    },
    "telegram": {
      "url": "https://your-server.com/webhooks/telegram",
      "token": "BOT_TOKEN"
    }
  }
}

При открытии PR на GitHub → сервер получает webhook → OpenClaw запускает код-ревью.

OAuth / OAuth 2.0

Стандарт безопасной авторизации: способ дать OpenClaw доступ к вашему аккаунту в сервисе (Google, GitHub, Notion) без передачи пароля.

Как это работает:

OpenClaw перенаправляет вас на страницу Google
Вы входите в Google и подтверждаете: «разрешаю OpenClaw читать Gmail»
Google возвращает временный токен доступа
OpenClaw использует токен для запросов — пароль никогда не передаётся

Токены доступа:

Access token — краткосрочный (1 час), используется для запросов
Refresh token — долгосрочный, используется для получения нового access token

# Авторизация через OAuth в OpenClaw
openclaw auth google --scopes gmail.readonly,calendar.events
openclaw auth github --scopes repo,issues

Endpoint

Конкретный URL в API, к которому обращается клиент. Каждый endpoint отвечает за конкретную функцию.

Пример:

Base URL: https://api.example.com/v1

Endpoints:
GET  /users           → получить список пользователей
GET  /users/123       → получить пользователя с ID 123
POST /users           → создать нового пользователя
PUT  /users/123       → обновить пользователя 123
DELETE /users/123     → удалить пользователя 123

В контексте OpenClaw: агент знает endpoint’ы сервисов и обращается к нужному в зависимости от задачи.

SDK (Software Development Kit)

Набор библиотек, инструментов и документации для разработки приложений, работающих с конкретным сервисом.

Разница API vs SDK:

API — спецификация (правила взаимодействия)
SDK — реализация (готовый код для работы с API)

# Без SDK: написать HTTP-запрос вручную
import requests
headers = {"Authorization": f"Bearer {api_key}"}
response = requests.post("https://api.openai.com/v1/chat/completions",
                        headers=headers, json={...})

# С SDK: использовать готовую библиотеку
from openai import OpenAI
client = OpenAI(api_key=api_key)
response = client.chat.completions.create(...)

OpenClaw использует SDK провайдеров (OpenAI SDK, Anthropic SDK) внутри — вам не нужно работать с ними напрямую.

REST (Representational State Transfer)

Архитектурный стиль для построения API. Большинство современных API — RESTful.

Ключевые принципы:

Ресурсы идентифицируются URL (/users/123)
HTTP-методы определяют действие (GET = читать, POST = создавать, PUT = обновлять, DELETE = удалять)
Без состояния: каждый запрос содержит всю необходимую информацию

HTTP-методы:

Метод	Действие	Пример
GET	Получить	GET /articles → список статей
POST	Создать	POST /articles → новая статья
PUT	Обновить полностью	PUT /articles/1 → перезаписать статью
PATCH	Обновить частично	PATCH /articles/1 → обновить заголовок
DELETE	Удалить	DELETE /articles/1 → удалить статью

JSON (JavaScript Object Notation)

Текстовый формат обмена данными. Большинство API используют JSON для запросов и ответов.

{
  "name": "OpenClaw",
  "version": "2.1.4",
  "features": ["browser", "files", "terminal"],
  "config": {
    "model": "gpt-4o",
    "temperature": 0.7
  }
}

JSON понятен как людям, так и машинам. Когда агент «читает данные из API» — чаще всего он обрабатывает JSON.

Rate Limit (Ограничение частоты запросов)

Лимит на количество API-запросов за период времени. Провайдеры вводят rate limits для защиты от перегрузки.

Пример лимитов OpenAI:

Tier 1: 500 запросов/мин, 200K токенов/мин
Tier 3: 5000 запросов/мин, 2M токенов/мин

Что происходит при превышении: API возвращает ошибку 429 Too Many Requests. OpenClaw автоматически делает повторную попытку с задержкой.

{
  "api": {
    "rateLimitRetry": true,
    "retryDelay": 5000,
    "maxRetries": 3
  }
}

Latency (Задержка)

Время от отправки запроса до получения ответа. Для интерактивной работы важна низкая latency.

Типичные значения для OpenClaw:

GPT-4o (первый токен): 500-1500 мс
Claude Sonnet (первый токен): 800-2000 мс
Groq + Llama (первый токен): 100-300 мс (очень быстро)
Локальная Ollama: 200-500 мс (зависит от железа)

Streaming: OpenClaw использует streaming API — модель начинает отдавать токены до завершения генерации. Это снижает воспринимаемую задержку.

Следующий раздел — архитектурные термины multi-agent систем: Multi-agent, оркестрация, пайплайн. API для разработчиков: OpenClaw API для разработчиков.