docs/channels/clickclack.md
ClickClack connects OpenClaw to a self-hosted ClickClack workspace through first-class ClickClack bot tokens.
Use this when you want an OpenClaw agent to appear as a ClickClack bot user. ClickClack supports independent service bots and user-owned bots; user-owned bots keep an owner_user_id and receive only the token scopes you grant.
Create a bot token on the ClickClack server:
clickclack admin bot create \
--workspace <workspace_id> \
--name "OpenClaw" \
--handle openclaw \
--scopes bot:write \
--plain
For a user-owned bot, add --owner <user_id>.
Configure OpenClaw:
{
channels: {
clickclack: {
enabled: true,
baseUrl: "https://clickclack.example.com",
token: { source: "env", provider: "default", id: "CLICKCLACK_BOT_TOKEN" },
workspace: "default",
defaultTo: "channel:general",
},
},
}
Then run:
export CLICKCLACK_BOT_TOKEN="ccb_..."
openclaw gateway
An account counts as configured only when baseUrl, token, and workspace are all set. workspace accepts a workspace id (wsp_...), slug, or name; the gateway resolves it to the id at startup.
| Key | Default | Notes |
|---|---|---|
baseUrl | none (required) | ClickClack server URL. |
token | none (required) | Plain string or secret ref (source: "env" | "file" | "exec"). |
workspace | none (required) | Workspace id, slug, or name. |
replyMode | "agent" | "agent" runs the full agent pipeline; "model" sends short direct model completions. |
defaultTo | "channel:general" | Target used when an outbound path gives no target. |
allowFrom | ["*"] | User-id allowlist for inbound DMs and channel messages. |
botUserId | auto-detected | Resolved from the bot token identity at startup. |
agentId | route default | Pin this account's inbound messages to one agent. |
toolsAllow | none | Tool allowlist for agent replies from this account. |
model, systemPrompt | none | Used by replyMode: "model" completions. |
reconnectMs | 1500 | Realtime reconnect delay (100 to 60000). |
If plugins.allow is a non-empty restrictive list, explicitly selecting
ClickClack in channel setup or running openclaw plugins enable clickclack
appends clickclack to that list. Onboarding installation uses the same
explicit-selection behavior. These paths do not override plugins.deny or a
global plugins.enabled: false setting. Direct
openclaw plugins install @openclaw/clickclack follows the normal
plugin-install policy and also records ClickClack in an existing allowlist.
Each account opens its own ClickClack realtime connection and uses its own bot token.
{
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" (default) dispatches inbound messages through the normal agent pipeline, including session recording and tool policy.replyMode: "model" skips the agent pipeline and uses the plugin runtime's llm.complete for short direct bot replies (optionally shaped by model and systemPrompt).Model mode runs completions against the resolved bot agent id, which requires
the explicit plugins.entries.clickclack.llm.allowAgentIdOverride: true trust
bit:
{
plugins: {
entries: {
clickclack: {
llm: {
allowAgentIdOverride: true,
},
},
},
},
}
Keep the trust bit off if you only use the default agent reply mode; it is
not needed there.
By default a ClickClack channel shows nothing while an agent turn runs; only the final reply lands. Set agentActivity: true on an account to publish durable agent_commentary and agent_tool message rows while the turn is in progress:
{
channels: {
clickclack: {
enabled: true,
token: { source: "env", provider: "default", id: "CLICKCLACK_BOT_TOKEN" },
workspace: "default",
agentActivity: true,
},
},
}
Requirements and behavior:
agent_activity:write token scope. This scope is separate from bot:write and is not inherited by it; create the bot token with --scopes bot:write,agent_activity:write (or grant the scope to an existing token) before enabling the option.agent_activity:write or the server rejects activity writes, failures are logged and the final reply still delivers normally; no activity rows appear.turn_id), coalesced so one logical step is one row, and tool rows use the same progress formatting as Discord/Slack/Telegram (tool name plus command detail).author_model and author_thinking fields resolved from the actual model used for the turn (including after fallback). Servers that do not define these columns ignore the unknown JSON fields; servers that persist them can answer "which model said this line, at which thinking level" per message.channel:<name-or-id> sends to a workspace channel. Bare targets default to channel:.dm:<user_id> creates or reuses a direct conversation with that user.thread:<message_id> replies in the thread rooted at that message.Explicit outbound targets may also carry the clickclack: or cc: provider prefix.
Examples:
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 token scopes are enforced by the ClickClack API.
bot:read: read workspace/channel/message/thread/DM/realtime/profile data.bot:write: bot:read plus channel messages, thread replies, DMs, and uploads.bot:admin: bot:write plus channel creation.agent_activity:write: durable agent activity rows (agent_commentary / agent_tool). Not inherited by bot:write or bot:admin; required only when agentActivity: true is set.OpenClaw only needs bot:write for normal agent chat. Add agent_activity:write when enabling agent activity rows.
ClickClack is not configured for account "<id>": set baseUrl, token (for example via CLICKCLACK_BOT_TOKEN), and workspace for that account.ClickClack workspace not found: <value>: set workspace to the workspace id, slug, or name returned by ClickClack.bot:write.