Настройка

Каналы

Как включить и проверить 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.

  1. Выпустите ключ для команды (Вход, люди и ключи):

    cradle keys create --name "site" --scopes messages:read,messages:write --team <team-id>
  2. Отправьте сообщение:

    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

  1. В Telegram создайте бота у @BotFather и скопируйте токен вида 1234567890:ABC-....
  2. В консоли: Интеграции → 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_kbskb:read
cradle_list_agentsagents:read
cradle_execute_agent, cradle_summarize_notesagents:execute
cradle_get_ticket, cradle_list_ticketstickets:read
cradle_submit_issuemessages:write
cradle_catalog, cradle_team_plan, cradle_team_exportteams:read
cradle_team_applyagents:write

Как проверить.

curl http://127.0.0.1:31417/health

Ответ — {"ok":true,"running":true,"toolCount":12,…}.

Если нет. ECONNREFUSED — канал не включён; в ответе инструмента unauthorized — нет ключа или не хватает скоупа. Карточка «MCP-серверы» в консоли — другое: через неё агенты ходят во внешние серверы, а не наоборот.