ClickClack

ClickClack 通过原生 ClickClack 机器人令牌将 OpenClaw 连接到自托管的 ClickClack 工作区。

当你希望 OpenClaw 代理以 ClickClack 机器人用户身份出现时，请使用此功能。ClickClack 支持独立服务机器人和用户拥有的机器人；用户拥有的机器人会保留 owner_user_id，并且只接收你授予的令牌作用域。

快速设置¶

在 ClickClack 中，打开 工作区设置 → 集成 → OpenClaw，使用 设置代码（推荐） 创建机器人，并复制生成的命令：

openclaw channels add clickclack --code 'https://clickclack.example.com/#XXXX-XXXX-XXXX'

对于前端和 API 源不同，或 API 挂载在路径下的情况，ClickClack 会改为输出精确的认领端点：

openclaw channels add clickclack --code 'https://api.example.com/services/clickclack/api/bot-setup-codes/claim#XXXX-XXXX-XXXX'

设置代码为一次性使用，10 分钟后过期。OpenClaw 会认领它，接收新签发的机器人令牌和工作区设置，保存账户，验证连接，并报告正在运行的网关是否已加载它。对于带版本的精确端点，OpenClaw 会验证并保存 ClickClack 返回的规范 API 基础地址，包括任何路径前缀。设置代码本身不会存储在 OpenClaw 配置中。

设置代码认领对公共服务器使用 HTTPS。对于回环地址（如 localhost 和 127.0.0.1）上的本地安装，也支持普通 HTTP。

如果 OpenClaw 已在运行，ClickClack 会自动连接，无需第二条命令。否则，使用以下命令启动它：

openclaw gateway

你也可以将代码与服务器 URL 分开传递：

openclaw channels add clickclack --code XXXX-XXXX-XXXX --base-url https://clickclack.example.com

要进行引导式设置，请运行：

openclaw onboard

选择 ClickClack，然后在提示时输入服务器 URL、机器人令牌和工作区。引导式设置会在保存后检查服务器、令牌和工作区；检查失败不会丢弃配置。

替代方案：手动令牌¶

在 ClickClack 中配置非 OpenClaw 客户端，或当你明确需要自行管理令牌时，选择 手动令牌：

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

workspace 接受工作区 id（wsp_...）、slug 或显示名称。 --code 不能与 --token、--token-file 或 --use-env 组合使用。

替代方案：基于环境变量的令牌¶

默认账户可以读取 CLICKCLACK_BOT_TOKEN，而无需在配置中存储令牌：

export CLICKCLACK_BOT_TOKEN="ccb_..."
openclaw channels add clickclack --base-url https://clickclack.example.com --workspace default --use-env
openclaw 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 接受工作区 id（wsp_...）、slug 或名称；网关会在启动时将其解析为 id。

账户配置键¶

保留身份验证门控的公共主机名¶

当 ClickClack 和 OpenClaw 网关运行在同一主机上，但公共 ClickClack 主机名受 Cloudflare Access 等身份验证网关保护时，请使用 apiBaseUrl：

{
  channels: {
    clickclack: {
      baseUrl: "https://clack.openclaw.ai",
      apiBaseUrl: "http://127.0.0.1:8484",
      token: { source: "env", provider: "default", id: "CLICKCLACK_BOT_TOKEN" },
      workspace: "default",
    },
  },
}

公共主机名可以完全保留身份验证门控，供浏览器用户使用。OpenClaw 使用回环端点处理 REST 请求、设置验证和实时 WebSocket，而讨论的 embedUrl 和 openUrl 链接继续使用公共 baseUrl。如果省略 apiBaseUrl，所有流量都会使用 baseUrl，从而保留现有行为。

插件允许列表行为¶

如果 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",
        },
      },
    },
  },
}

会话讨论¶

在一个 ClickClack 账户上启用讨论，可为每个 OpenClaw 会话提供一个专用的 ClickClack 频道。账户令牌必须包含 channels:write（bot:admin 捆绑包包含它）；普通的 bot:write 设置令牌无法创建或同步频道。

{
  channels: {
    clickclack: {
      enabled: true,
      baseUrl: "https://clickclack.example.com",
      token: { source: "env", provider: "default", id: "CLICKCLACK_BOT_TOKEN" },
      workspace: "default",
      discussions: {
        enabled: true,
        workspace: "default",
        controlUrlBase: "https://team.openclaw.ai",
        section: "Sessions",
      },
    },
  },
}

discussions.workspace 接受与账户级 workspace 相同的工作区 ID、slug 或显示名称，并默认使用该值。section 控制 ClickClack 侧边栏部分，默认为 Sessions。当设置 controlUrlBase 时，受管理的频道会链接回规范的 Control UI 会话路径。

在恰好一个 ClickClack 账户上启用讨论。网关提供程序没有账户选择器，因此多个已启用的讨论账户会被拒绝，而不是按配置顺序选择一个。

打开讨论会创建一个标记为外部管理的公共 ClickClack 频道。插件会保持会话标签和类别同步，但频道生命周期保持独立。清除会话类别会将频道移回配置的默认部分。归档、重置或删除 OpenClaw 会话永远不会归档或替换 ClickClack 频道。ClickClack 独立拥有频道的归档和恢复。当使用讨论 RPC 时，插件会协调绑定，并且在存在任何绑定时大约每分钟协调一次。

受管理频道中的入站消息使用确定性的侧会话，其位于与所附加主会话相同的 agent ID 下。侧代理会被告知要观察哪个主会话，并可以使用 sessions_history 和 session_status（changesSince 适用于增量检查）。只有当讨论中的人们要求它中继或引导主会话时，它才会使用 sessions_send。绑定将持久的房间身份与其可替换的会话附加分离。侧会话的对等身份和作用域授权包含确切的、具体的 OpenClaw 会话 ID，因此重置可复用的会话密钥会轮换附加项，并且无法重用旧的侧会话记录。ClickClack 频道 ID、URL、历史和所有权引用保持不变。通过非活动、已禁用或已重新定向的附加项到达的消息会被丢弃，而不是回退到账户的正常频道路由。已释放的绑定会留下持久的已撤销频道标记，因此延迟的实时事件保持失败关闭。远程所有权以 ClickClack 服务器和频道 ID 为键，因此重命名本地账户不会将受管理的频道变成普通频道。

For narrower session access, explicitly set tools.sessions.visibility to tree rather than the default all. The plugin installs a host-scoped grant only between each side session and its attached main session, plus a tool-policy hook that blocks session discovery and cross-session targets. It allows sessions_history, session_status, and sessions_send only for the attached main session and prevents the status call from changing that session's model. Those tools must still be present in the agent's effective tool allowlist. The system prompt is guidance; the host grant and hook are the authorization boundary.

The ClickClack server must support managed-channel fields (external_managed, external_ref, external_url, and sidebar_section) on channel creation and updates and return them in channel responses. OpenClaw verifies that contract before persisting a binding. If a create response is lost, the next open adopts the channel by its server-enforced external_ref instead of creating another. Until that outcome is reconciled, the pending reservation quarantines otherwise-unbound events in the destination workspace. The coarse reconciler adopts the channel when the logical session is active, including after its concrete session id changes; it clears the reservation when no remote channel was created. That reference contains a durable per-OpenClaw-installation namespace plus a hash of the session key, ClickClack destination, and durable binding generation. Separate gateways cannot adopt each other's channels, while concrete session resets keep the same channel. An account or workspace round trip cannot re-adopt a previous channel. Bindings are also pinned to the configured ClickClack server URL and are invalidated if the account is retargeted. Changing or removing controlUrlBase updates or clears the managed channel link on the next reconciliation pass. Changing discussions.workspace releases the old attachment before a channel can be opened in the new workspace. It never archives the old room. If the token was replaced with a workspace-scoped credential that cannot access the old workspace, OpenClaw records the old channel as revoked and releases the binding without trying the replacement token.

The attached main session also receives a pull-only discussion tool. It reads the latest messages and recent thread replies as one escaped, attributed record per message, and has no write or lifecycle side effects. Channel-root and thread lookups have fixed request budgets; the result explicitly warns when that safety bound can omit an older active thread.

回复模式¶

• replyMode: "agent"（默认）通过常规代理管道分发传入消息，包括会话记录和工具策略。
• replyMode: "model" 跳过代理管道，并使用插件运行时的 llm.complete 进行直接机器人回复，可选地由 model 和 systemPrompt 塑形。所选提供者和模型负责补全预算。

两种模式都会遵循频道或账户级别的 responsePrefix。账户值优先，包括使用 "" 禁用继承的前缀。使用 "auto" 表示路由代理的身份名称，或使用 "[{model}]" 表示所选模型。显式 message 工具和 CLI 文本发送遵循共享前缀行为，包括省略未解析的模型依赖前缀。

模型模式针对解析后的机器人代理 id 运行补全，这需要显式的 plugins.entries.clickclack.llm.allowAgentIdOverride: true 信任位：

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

如果只使用默认的 agent 回复模式，请保持该信任位关闭；在那里不需要它。

命令菜单¶

在网关启动时，每个已配置的账户都会将 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 捆绑包包含该范围，也可以单独授予。在引入命令菜单之前创建的令牌可能需要添加该范围或更换令牌。

同步是尽力而为的，每次网关启动时运行一次。缺少范围或网络故障会记录警告；没有该端点的旧版 ClickClack 服务器会在调试级别记录。这些故障都不会阻止实时启动。菜单在代理离线期间仍然可用，并在机器人离开工作区时移除。

此版本仅发布原生命令规范。别名以及技能、插件或自定义命令目录不会被添加到菜单中。如果某个名称也注册为 HTTP 斜杠命令，ClickClack 会先分发该注册；其他菜单命令继续通过常规消息传递处理。

使用 agent 模式以获取跨服务关联证据。对于具有规范 msg_<ulid> 形状的权威 ClickClack 消息 id，频道会推导出确定性的 OpenClaw 运行 id clickclack:<message-id>。然后，每次模型调用都会在诊断中显示为 clickclack:<message-id>:model:<n>；当该轮次使用 ClawRouter 时，相同的模型调用 id 会作为 X-Request-ID 发送。model 模式绕过常规代理运行/会话诊断，因此不适合此证据路径。

当实时事件包含经过验证的 payload.correlation_id 时，频道会将其作为 X-Correlation-ID 携带在权威消息获取以及由此产生的 ClickClack 回复请求中。值使用 ClickClack 的安全 128 字符集（A-Z、a-z、0-9、.、_、: 和 -）；无效值会被省略。这些关联仅包含标识符，绝不包含消息正文、提示、补全、凭证或工具输出。

持久媒体投递¶

包含媒体的代理回复采用必需的持久投递。OpenClaw 在首次 ClickClack 写入之前为每个部分的消息和上传分配稳定的 nonce，因此重试会复用相同的上传和消息，而不是消耗存储配额或发布重复内容。如果重启后上传已存在，OpenClaw 不会重新读取原始本地路径或远程媒体 URL。

此恢复契约要求 ClickClack 服务器支持：

• GET /api/uploads/by-nonce，在找到和未找到结果时均带有 X-ClickClack-Upload-Nonce: supported。
• GET /api/messages/by-nonce，在找到和未找到结果时均带有 X-ClickClack-Message-Nonce: supported。
• 对于相同的所有者作用域 nonce 和上传，消息创建和附件关联必须是幂等的。

旧版服务器返回的通用 404 不会被视作某次发送不存在的证据。OpenClaw 会让投递保持未解决状态，而不是冒重复发送的风险；在启用会产生媒体的代理回复之前，请更新 ClickClack。

原生进度与代理活动行¶

原生进度是按账户选择启用的。设置 nativeProgress: true 可在代理回合运行期间显示一个临时的 <agent name> is responding 状态和进度行。代理名称来自配置的账户名、ClickClack bot 句柄或代理 ID。这些使用临时性的 agent.progress 事件，并在回合结束时被清除；只有最终回复是持久的。单独设置 agentActivity: true 可在回合进行期间发布持久的 agent_commentary 和 agent_tool 消息行：

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

要求与行为：

• 原生进度默认关闭。 仅为支持临时实时端点的 ClickClack 部署设置 nativeProgress: true。
• 持久活动默认单独关闭。 设置 agentActivity: true 以持久化活动行；这本身不会启用原生进度。
• 原生进度为尽力而为。 进度发布使用临时实时端点和有限请求超时。失败或停滞的进度请求会被记录，并且不能阻止最终文本的投递。
• 持久活动需要 agent_activity:write 令牌作用域。 该作用域与 bot:write 分离，且不会被 bot:write 继承；在启用 agentActivity 之前，请使用 --scopes bot:write,agent_activity:write 创建机器人令牌。
• 尽力而为的降级。 如果令牌缺少 agent_activity:write 或服务器拒绝活动写入，失败会被记录，最终回复仍会正常投递；但不会出现活动行。
• 行按回合（turn_id）分组，合并为每个逻辑步骤一行；工具行使用与 Discord/Slack/Telegram 相同的进度格式（工具名称加命令详情）。
• 归属元数据。 代理撰写的帖子（活动行和最终回复）携带 author_model 和 author_thinking 字段，这些字段根据回合实际使用的模型（包括回退后）解析。未定义这些列的服务器会忽略未知 JSON 字段；持久化这些字段的服务器可以按消息回答“哪一行由哪个模型、以何种思考层级说出”。

群组提及门控¶

默认情况下，ClickClack 中的每条群组消息都会分发给同一工作区中所有已启用的 ClickClack 账户。此行为向后兼容。为账户添加 requireMention: true，可要求在代理流水线运行之前必须先直接提及该账户。

每个群组策略字段按以下顺序解析：

1. groups 中的精确频道条目（以 ClickClack 频道 ID 为键）。
2. groups 中的通配符 "*" 条目。
3. 账户级值；省略时继承顶层 ClickClack 值。
4. 向后兼容的默认值（{ requireMention: false, mentionPatterns: [] }）。

私聊（DM）永远不会受到 requireMention 的门控。当收到私聊时，提及门控会被完全跳过。

机器人创建的线程¶

设置 requireMentionInBotThreads: false，可让人们在机器人发起的线程中无需提及即可回复，同时仍对频道中的其他消息保持 requireMention: true。你可以在账户级别，或在精确频道或通配符 groups 条目中设置此选项，并使用上述相同的优先级。

仅当 OpenClaw 验证了原生线程的根消息由接收账户的机器人在同一工作区和频道中撰写时，它才会应用此覆盖。由其他人启动的线程，或根消息无法验证的线程，继续保留普通的 requireMention 行为。参与线程并不会让机器人成为线程创建者。

设置 requireMentionInBotThreads: true 会在这些线程中要求提及，即使 requireMention 为 false 也是如此。省略该选项会保留现有的提及策略。私聊、发送者访问规则和 allowBots 限制保持不变；allowBots: "mentions" 仍要求另一个机器人提及。

提及检测¶

在以下情况会检测到 ClickClack 提及：

• 消息正文匹配 mentionPatterns 中的任何模式（每个模式都是一个正则表达式）。
• 消息包含机器人的 ClickClack @handle。网关在启动时从经过身份验证的机器人身份中读取该句柄。

普通显示名称（例如 Blackbird）不会被视为提及，除非它们被显式配置为模式。

机器人对机器人的消息¶

ClickClack 默认忽略机器人撰写的消息。要选择启用，请在该账户上设置 allowBots: true。设置 allowBots: "mentions" 可在群组频道中仅在机器人消息提及此机器人时允许这些消息；私聊消息无需提及仍然符合条件。机器人消息仍会经过 allowFrom 的检查，但机器人作者必须通过 ID 显式列出；通配符 allowFrom: ["*"] 默认不会授权机器人撰写的消息。该通配符仍然可供人类消息使用。自身撰写的消息总是被忽略。

被接受的机器人消息也会经过 OpenClaw 的共享机器人配对循环保护。 在账户上使用 botLoopProtection，或使用 channels.defaults.botLoopProtection， 以调整其窗口、预算、冷却时间或启用状态。群组级别的 allowBots 和 botLoopProtection 值遵循与其他群组策略相同的优先级：精确频道、通配符， 然后是账户级别。顶层频道消息共享一个频道预算，而不同 ClickClack 线程中的 回复使用独立的线程根预算。

ClickClack 的 agent_commentary 和 agent_tool 活动行永远不会触发 OpenClaw 入站回合，即使其作者机器人被明确允许。

较早的 ClickClack 响应可能省略 author.kind。这些消息有意保留在旧版 allowFrom 路径上：allowFrom: ["*"] 可以允许它们，并且针对特定机器人的 allowBots 和机器人配对循环保护检查不适用，因为服务器未对作者进行分类。 因此，针对特定机器人的限制需要 ClickClack 服务器响应中包含作者分类。

配置示例¶

{
  channels: {
    clickclack: {
      enabled: true,
      token: { source: "env", provider: "default", id: "CLICKCLACK_BOT_TOKEN" },
      workspace: "default",
      requireMention: true,
      requireMentionInBotThreads: false,
      mentionPatterns: ["\\bBlackbird\\b"],
      allowBots: "mentions",
      allowFrom: ["usr_trusted_bot"],
      botLoopProtection: { maxEventsPerWindow: 12, windowSeconds: 60 },
      groups: {
        "*": { requireMention: true, allowBots: "mentions" },
        chn_command_and_control: { requireMention: false },
      },
    },
  },
}

同一工作区中的多个账户会独立评估同一条消息，并使用每个账户已解析的 提及策略和机器人身份。

迁移警告¶

ClickClack 频道 ID（例如 chn_...）不会自动成为 Discord 频道 ID。配置按频道 规则需要实际的 ClickClack 频道标识符。除非 ClickClack 服务器明确将它们存储为 external_ref，并且适配器具有文档化的转换层，否则不要复用 Discord ID。

仅添加 requireMention: true 而不限制 allowFrom，不会静默更改群组消息 现有发送者允许列表的行为；提及门控是在现有发送者策略之上的额外保护。

目标¶

• channel:<name-or-id> 发送到工作区频道。裸目标默认为 channel:。
• dm:<user_id> 创建或复用与该用户的直接对话。
• thread:<message_id> 在以该消息为根的线程中回复。

显式出站目标也可以携带 clickclack: 或 cc: 提供商前缀。

出站媒体使用 ClickClack 的上传 API，然后将持久上传附加到创建的频道消息、 线程回复或直接消息。本地文件和受支持的远程媒体 URL 遵循 OpenClaw 的正常 媒体访问策略。设置 channels.clickclack.mediaMaxMb 以 MiB 为单位限制每个 出站附件；accounts.<id>.mediaMaxMb 覆盖根配置，然后 agents.defaults.mediaMaxMb 提供回退值。64 MiB 上传上限始终适用。图像在 发送前可能会被优化。持久队列发送为每个上传和消息部分使用独立的所有者范围 nonce，然后使用相同对象重试附件关联。有关服务器契约和恢复行为，请参阅 持久媒体投递。

示例：

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 令牌作用域由 ClickClack API 强制执行。

• 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 返回的工作区 ID、slug 或名称。
• 没有入站回复：确认令牌具有实时读取访问权限。机器人始终忽略其自己的消息；其他机器人消息默认被拒绝，并且当启用 allowBots 时，发送方机器人 ID 还必须明确列在 allowFrom 中。
• 频道发送失败：验证机器人是工作区成员并具有 bot:write。
• 没有命令菜单：确认 commandMenu 不是 false，ClickClack 服务器支持 PUT /api/bots/self/commands，并且令牌具有 commands:write。

相关¶

• 配对
• 群组
• 机器人循环保护
• 访问组