Зачем этот глоссарий
Когда 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,issuesEndpoint
Конкретный 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 для разработчиков.