ClickClack

ClickClack підключає OpenClaw до самостійно розміщеного робочого простору ClickClack за допомогою повноцінних токенів ботів ClickClack.

Використовуйте це, якщо агент OpenClaw має відображатися як користувач-бот ClickClack. ClickClack підтримує незалежних службових ботів і ботів, що належать користувачам; боти, що належать користувачам, зберігають owner_user_id і отримують лише надані вами області доступу токена.

Швидке налаштування

У ClickClack відкрийте Workspace settings → Integrations → OpenClaw, створіть бота та скопіюйте його токен. Потім налаштуйте канал:

openclaw channels add clickclack --base-url https://clickclack.example.com --token ccb_... --workspace default

workspace приймає ідентифікатор робочого простору (wsp_...), slug або відображувану назву. Після збереження channels add перевіряє сервер, токен і робочий простір, а потім повідомляє, чи підхопив запущений Gateway новий обліковий запис. Якщо OpenClaw уже запущено, ClickClack підключиться автоматично й друга команда не потрібна. Інакше запустіть його командою:

openclaw gateway

Для керованого налаштування виконайте:

openclaw onboard

Виберіть ClickClack, а потім, коли з’являться запити, введіть URL-адресу сервера, токен бота та робочий простір. Кероване налаштування перевіряє сервер, токен і робочий простір після збереження; невдала перевірка не видаляє конфігурацію.

Альтернатива: токен зі змінної середовища

Обліковий запис за замовчуванням може зчитувати CLICKCLACK_BOT_TOKEN замість зберігання токена в конфігурації:

export CLICKCLACK_BOT_TOKEN="ccb_..."openclaw channels add clickclack --base-url https://clickclack.example.com --workspace default --use-envopenclaw gateway

Іменовані облікові записи мають використовувати налаштований токен або файл токена; спільну змінну середовища навмисно обмежено обліковим записом за замовчуванням.

Довідка щодо JSON5

Еквівалентна структура конфігурації:

{  channels: {    clickclack: {      enabled: true,      baseUrl: "https://clickclack.example.com",      token: { source: "env", provider: "default", id: "CLICKCLACK_BOT_TOKEN" },      workspace: "default",      defaultTo: "channel:general",    },  },}

Обліковий запис вважається налаштованим, лише коли задано всі три значення: baseUrl, джерело токена та workspace. Джерелом токена може бути token, tokenFile або CLICKCLACK_BOT_TOKEN для облікового запису за замовчуванням. workspace приймає ідентифікатор робочого простору (wsp_...), slug або назву; під час запуску Gateway перетворює його на ідентифікатор.

Ключі конфігурації облікового запису

Якщо plugins.allow є непорожнім обмежувальним списком, явний вибір ClickClack під час налаштування каналу або виконання openclaw plugins enable clickclack додає clickclack до цього списку. Встановлення під час початкового налаштування використовує таку саму поведінку явного вибору. Ці шляхи не перевизначають plugins.deny або глобальне налаштування plugins.enabled: false. Безпосереднє виконання openclaw plugins install @openclaw/clickclack дотримується звичайної політики встановлення плагінів і також записує ClickClack до наявного списку дозволених.

Кілька ботів

Кожен обліковий запис відкриває власне з’єднання ClickClack у реальному часі та використовує власний токен бота.

{  channels: {    clickclack: {      enabled: true,      baseUrl: "https://clickclack.example.com",      defaultAccount: "service",      accounts: {        service: {          token: { source: "env", provider: "default", id: "CLICKCLACK_SERVICE_BOT_TOKEN" },          workspace: "default",          defaultTo: "channel:general",          agentId: "service-bot",        },        support: {          token: { source: "env", provider: "default", id: "CLICKCLACK_SUPPORT_BOT_TOKEN" },          workspace: "default",          defaultTo: "dm:usr_...",          agentId: "support-bot",        },      },    },  },}

Режими відповіді

• replyMode: "agent" (за замовчуванням) передає вхідні повідомлення через звичайний конвеєр агента, включно із записуванням сеансу та політикою інструментів.
• replyMode: "model" оминає конвеєр агента та використовує llm.complete середовища виконання плагіна для прямих відповідей бота, форму яких за потреби визначають model і systemPrompt. Вибрані постачальник і модель визначають бюджет завершення.

Режим моделі виконує завершення для визначеного ідентифікатора агента бота, що потребує явного біта довіри plugins.entries.clickclack.llm.allowAgentIdOverride: true:

{  plugins: {    entries: {      clickclack: {        llm: {          allowAgentIdOverride: true,        },      },    },  },}

Не вмикайте біт довіри, якщо використовуєте лише типовий режим відповіді agent; для нього цей біт не потрібен.

Меню команд

Під час запуску Gateway кожен налаштований обліковий запис публікує власні команди OpenClaw у ClickClack. Вони з’являються в автодоповненні редактора з позначкою дескриптора бота. Опублікований набір повністю замінюється під час кожного запуску, включно з очищенням застарілого меню, коли каталог власних команд порожній.

Синхронізацію меню команд увімкнено за замовчуванням. Щоб відмовитися від неї, задайте commandMenu: false для облікового запису:

{  channels: {    clickclack: {      enabled: true,      token: { source: "env", provider: "default", id: "CLICKCLACK_BOT_TOKEN" },      workspace: "default",      commandMenu: false,    },  },}

Токен потребує commands:write. Поточні набори ClickClack bot:write і bot:admin містять цю область доступу; її також можна надати окремо. Для токенів, створених до появи меню команд, може знадобитися додати область доступу або створити новий токен.

Синхронізація виконується за принципом найкращих зусиль один раз під час кожного запуску Gateway. Відсутня область доступу або мережева помилка призводить до запису попередження в журнал; старіший сервер ClickClack без кінцевої точки створює запис на рівні налагодження. Жодна з цих помилок не блокує запуск з’єднання в реальному часі. Меню залишаються доступними, поки агент не в мережі, і видаляються, коли бот залишає робочий простір.

Цей випуск публікує лише специфікації власних команд. Псевдоніми та каталоги команд Skills, плагінів або власних команд до меню не додаються. Якщо назву також зареєстровано як HTTP-команду з похилою рискою, ClickClack спочатку передає цю реєстрацію; інші команди меню й надалі проходять через звичайну доставку повідомлень.

Використовуйте режим agent для отримання доказів кореляції між службами. Для авторитетного ідентифікатора повідомлення ClickClack у його канонічній формі msg_<ulid> канал виводить детермінований ідентифікатор запуску OpenClaw clickclack:<message-id>. Після цього кожен виклик моделі відображається в діагностиці як clickclack:<message-id>:model:<n>; коли в цьому ході використовується ClawRouter, той самий ідентифікатор виклику моделі надсилається як X-Request-ID. Режим model оминає звичайну діагностику запуску агента й сеансу, тому не підходить для цього шляху доказів.

Коли подія в реальному часі містить перевірений payload.correlation_id, канал передає його як X-Correlation-ID під час авторитетного отримання повідомлення та в результативних запитах відповіді ClickClack. Значення використовують безпечний 128-символьний набір ClickClack (A-Z, a-z, 0-9, ., _, : і -); недійсні значення пропускаються. Ці зв’язки містять лише ідентифікатори й ніколи не містять тіла повідомлень, запити, завершення, облікові дані або вивід інструментів.

Надійна доставка медіафайлів

Для відповідей агента, що містять медіафайли, використовується обов’язкова надійна доставка. OpenClaw призначає стабільні для кожної частини одноразові значення повідомлення та передавання перед першим записом у ClickClack, тому повторна спроба використовує те саме передавання й повідомлення замість витрачання квоти сховища або публікації дублікатів. Якщо передавання вже існує після перезапуску, OpenClaw не перечитує початковий локальний шлях або віддалену URL-адресу медіафайлу.

Цей контракт відновлення потребує сервера ClickClack, який підтримує:

• GET /api/uploads/by-nonce з X-ClickClack-Upload-Nonce: supported для результатів, де об’єкт знайдено або не знайдено.
• GET /api/messages/by-nonce з X-ClickClack-Message-Nonce: supported для результатів, де об’єкт знайдено або не знайдено.
• Ідемпотентне створення повідомлення та пов’язування вкладення для того самого одноразового значення й передавання в межах власника.

Загальна помилка 404 старішого сервера не вважається доказом відсутності надсилання. OpenClaw залишає доставку невирішеною, щоб не ризикувати створенням дубліката; оновіть ClickClack, перш ніж вмикати відповіді агента, що створюють медіафайли.

Рядки активності агента

За замовчуванням канал ClickClack нічого не показує, поки виконується хід агента; надходить лише остаточна відповідь. Задайте agentActivity: true для облікового запису, щоб публікувати надійні рядки повідомлень agent_commentary і agent_tool під час виконання ходу:

{  channels: {    clickclack: {      enabled: true,      token: { source: "env", provider: "default", id: "CLICKCLACK_BOT_TOKEN" },      workspace: "default",      agentActivity: true,    },  },}

Вимоги та поведінка:

• За замовчуванням вимкнено. Стандартні налаштування та старіші сервери ClickClack залишаються без змін.
• Потребує області доступу токена agent_activity:write. Ця область доступу відокремлена від bot:write і не успадковується від неї; перш ніж вмикати цей параметр, створіть токен бота з --scopes bot:write,agent_activity:write (або надайте цю область доступу наявному токену).
• Деградація за принципом найкращих зусиль. Якщо токен не має agent_activity:write або сервер відхиляє записи активності, помилки записуються в журнал, а остаточна відповідь усе одно доставляється звичайним чином; рядки активності не з’являються.
• Рядки групуються за ходом (turn_id) і об’єднуються так, щоб один логічний крок відповідав одному рядку, а рядки інструментів використовують те саме форматування перебігу виконання, що й Discord/Slack/Telegram (назва інструмента та відомості про команду).
• Метадані атрибуції. Дописи, створені агентом (рядки активності та остаточна відповідь), містять поля author_model і author_thinking, визначені за фактичною моделлю, використаною для ходу (зокрема після переходу на резервну модель). Сервери, у яких ці стовпці не визначено, ігнорують невідомі поля JSON; сервери, що зберігають їх, можуть для кожного повідомлення відповісти на запитання «яка модель промовила цей рядок і на якому рівні мислення».

Цілі

• channel:<name-or-id> надсилає повідомлення до каналу робочого простору. Для цілей без префікса типовим є channel:.
• dm:<user_id> створює або повторно використовує особисту розмову з цим користувачем.
• thread:<message_id> відповідає в гілці, коренем якої є це повідомлення.

Явно вказані цілі вихідних повідомлень також можуть містити префікс провайдера clickclack: або cc:.

Для вихідних медіафайлів використовується API завантаження ClickClack, після чого довготривале завантаження прикріплюється до створеного повідомлення каналу, відповіді в гілці або особистого повідомлення. Локальні файли та підтримувані URL-адреси віддалених медіафайлів підпорядковуються звичайній політиці доступу OpenClaw до медіафайлів з обмеженням 64 MiB на файл. Для довготривалих відкладених надсилань використовуються окремі одноразові значення, обмежені власником, для кожного завантаження та частини повідомлення, після чого повторюється спроба пов’язати вкладення з тими самими об’єктами. Контракт сервера та поведінку відновлення описано в розділі Довготривале доставлення медіафайлів.

Приклади:

openclaw message send --channel clickclack --target channel:general --message "hello"openclaw message send --channel clickclack --target dm:usr_123 --message "hello"openclaw message send --channel clickclack --target thread:msg_123 --message "following up"

Дозволи

Області дії токена ClickClack контролюються API ClickClack.

• bot:read: читання даних робочого простору, каналів, повідомлень, гілок, особистих повідомлень, даних реального часу та профілю.
• bot:write: bot:read плюс повідомлення каналів, відповіді в гілках, особисті повідомлення, завантаження та публікація меню команд.
• bot:admin: bot:write плюс створення каналів.
• commands:write: публікація меню команд бота. Входить до поточних наборів bot:write і bot:admin, а також може надаватися окремо.
• agent_activity:write: довготривалі рядки активності агента (agent_commentary / agent_tool). Не успадковується через bot:write або bot:admin; потрібне лише тоді, коли встановлено agentActivity: true.

Для звичайного чату з агентом і синхронізації меню команд OpenClaw потрібен лише поточний bot:write. Додайте agent_activity:write, коли вмикаєте рядки активності агента.

Усунення несправностей

• ClickClack is not configured for account "<id>": задайте baseUrl, token (наприклад, через CLICKCLACK_BOT_TOKEN) і workspace для цього облікового запису.
• ClickClack workspace not found: <value>: задайте для workspace ідентифікатор, слаг або назву робочого простору, повернуті ClickClack.
• Немає вхідних відповідей: переконайтеся, що токен має доступ до читання даних реального часу, і врахуйте, що бот ігнорує власні повідомлення та повідомлення від інших ботів.
• Не вдається надсилати повідомлення в канали: переконайтеся, що бот є учасником робочого простору та має bot:write.
• Немає меню команд: переконайтеся, що commandMenu не дорівнює false, сервер ClickClack підтримує PUT /api/bots/self/commands, а токен має commands:write.