Каналы
Как включить и проверить HTTP API, Telegram (бот и группы), виджет и входящий MCP-канал, и в какую команду попадает сообщение.
Канал — то, откуда в колыбель приходят сообщения. Каналов четыре; HTTP API работает с первого запуска, остальные включаются. В консоли настройки лежат на странице команды: вкладка Интеграции → карточка канала.
1. В какую команду попадает сообщение
| Канал | Команда |
|---|---|
| HTTP API | команда ключа, с которым пришёл запрос |
| MCP-канал | команда ключа |
| Telegram, группа | команда, выбранная у группы в карточке Telegram |
| Telegram, личный чат | «команда канала» |
| Виджет | «команда канала» |
«Команда канала» хранится в самой настройке канала; по умолчанию это служебная
команда колыбели opencradle. Ни экрана, ни команды для её смены в версии 0.9.2 нет.
Пока в opencradle нет агентов, консоль её не показывает. Чтобы личные чаты
Telegram и виджет кому-то отвечали, заведите агента в этой команде:
cradle teams use opencradle
cradle agents create --template support --name "Support"(нужен ключ admin:*). Когда агент появится, команда «OpenCradle» видна на
странице «Команды». Для HTTP API и MCP это не нужно: команду определяет ключ.
2. HTTP API
Канал включён сразу и слушает 127.0.0.1:31416. Порт и адрес прослушивания
задают флаги сервера --port и --bind (переменная CRADLE_BIND) при каждом
запуске: карточка их не переопределит. Поле «API key» в карточке нужно только
чтобы канал стартовал (не короче 16 символов): при первом запуске сервер кладёт
туда копию ключа администратора, поэтому не показывайте карточку посторонним.
Запросы авторизуются ключами из cradle keys.
-
Выпустите ключ для команды (Вход, люди и ключи):
cradle keys create --name "site" --scopes messages:read,messages:write --team <team-id> -
Отправьте сообщение:
curl -sS -X POST http://127.0.0.1:31416/api/v1/messages \ -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \ -d '{"text":"Hello","chatId":"test-1"}'
В ответе — ok, mode, chatId, conversationId, messageId, ticketId
(null, если ответ ушёл без участия человека) и replies. Режимы: sync (по
умолчанию, ответ в этом же запросе), async (ответ 202 и drainUrl, ответы
забираются GET /api/v1/messages/<chatId>?wait=<мс>) и webhook (поле
webhookUrl; подпись — заголовок X-Cradle-Signature: sha256=…, HMAC-SHA256
секретом вебхука или ключом канала). Продолжение разговора — тот же chatId.
Как проверить. Ответ "ok":true. Без модели ответ такой: «Запрос принят и
передан оператору на проверку. Ответим в течение нескольких минут.», а
ticketId заполнен — тикет ждёт человека (Ждут решения).
Карточка «HTTP API» показывает «requests: N».
Если нет.
- 401
unauthorized— ключ неверен; 403 сmissing— не хватаетmessages:write. - 400
text length out of bounds (1..50000)— пустой или слишком длинныйtext. - 429 — больше 120 запросов в минуту с одного адреса и ключа.
3. Telegram
- В Telegram создайте бота у
@BotFatherи скопируйте токен вида1234567890:ABC-.... - В консоли: Интеграции → Telegram → поле «Bot token» → Save → Start.
Бот работает через long polling: входящий порт открывать не нужно.
Как проверить. В карточке написано «Connected as @имя_бота»; напишите боту в
личный чат — в «Ждут решения» команды канала появится тикет или бот ответит сам.
Состояние всех каналов: cradle channels list (колонка RUNNING).
Если нет. Ответ Failed to connect to Telegram: … — токен неверен или у сервера нет выхода
к api.telegram.org.
Группы
Добавьте бота в группу Telegram: он читает всё, что в ней пишут, а отвечает тем,
кто обращается к нему (упоминание @бот, ответ на его сообщение, команда). В карточке
Telegram появится список «Группы» с селектом для каждой группы. Выберите команду
и нажмите Save.
Пока у группы выбрано «Команда канала», она не привязана: бот ответит один раз «Меня сюда не подключили. Попросите администратора привязать группу к команде в Cradle.» и замолчит.
Если карточка показывает «Privacy mode включён», боту доходят только команды и
упоминания. Чтобы бот видел всё: в @BotFather — /setprivacy → Disable, затем
удалите бота из группы и добавьте заново (либо сделайте бота администратором группы).
4. Виджет
Плавающий чат одним <script> на сайте. В консоли: Интеграции → Web Widget
→ Port (по умолчанию 31415), Accent color, API key (кнопка Generate
выдаёт ключ вида wk_...), Allowed origins (через запятую; пусто — любые),
Greeting → Save → Start. Готовый код — в поле «Embed snippet»
(Copy to clipboard):
<script
src="https://<public-address>/widget.js"
data-cradle-widget
data-api-key="wk_..."
async></script>Виджет слушает только 127.0.0.1: чтобы страница в интернете его видела,
опубликуйте порт через reverse proxy или туннель. Кроме того, бандл
widget.js в архив установщика и в образ Docker не входит:
на таком сервере GET /widget.js
отвечает 503 «Widget bundle not built yet». Соберите его bun run widget:build в клоне
репозитория и запускайте сервер оттуда.
Как проверить. curl -i http://127.0.0.1:31415/widget.js — 200 и
application/javascript; в карточке «Connections: N · Port: 31415».
Если нет. 503 — бандл не собран (см. выше); виджет не открывается на сайте — домен сайта не в «Allowed origins».
5. Входящий MCP-канал
Через него Claude Code, n8n или SmartNotes обращаются к колыбели как к серверу MCP. Канал по умолчанию выключен. Включите его одним из способов.
При запуске сервера — переменной окружения (0.0.0.0 открывает канал для сети,
порт задаёт CRADLE_MCP_PORT, по умолчанию 31417):
CRADLE_MCP_BIND=127.0.0.1 cradle-server …На работающем сервере ни экрана в консоли, ни работающей команды CLI
(cradle channels start — заглушка) нет, поэтому канал включается вызовом
POST /api/v1/rpc/channels:start:
curl -s -X POST http://127.0.0.1:31416/api/v1/rpc/channels:start \
-H "Authorization: Bearer $ADMIN_KEY" -H "Content-Type: application/json" \
-d '{"args":["mcp-server"]}'Адрес — http://127.0.0.1:31417/mcp (метод POST), ключ — в заголовке
x-api-key или Authorization: Bearer; каждый инструмент требует свой скоуп:
| Инструмент | Скоуп |
|---|---|
cradle_search_kb, cradle_list_kbs | kb:read |
cradle_list_agents | agents:read |
cradle_execute_agent, cradle_summarize_notes | agents:execute |
cradle_get_ticket, cradle_list_tickets | tickets:read |
cradle_submit_issue | messages:write |
cradle_catalog, cradle_team_plan, cradle_team_export | teams:read |
cradle_team_apply | agents:write |
Как проверить.
curl http://127.0.0.1:31417/healthОтвет — {"ok":true,"running":true,"toolCount":12,…}.
Если нет. ECONNREFUSED — канал не включён; в ответе инструмента
unauthorized — нет ключа или не хватает скоупа. Карточка «MCP-серверы» в
консоли — другое: через неё агенты ходят во внешние серверы, а не наоборот.