mirror of
https://github.com/openclaw/openclaw.git
synced 2026-08-02 11:31:34 +00:00
56d9d07516
* feat(ui): align ClickClack discussion themes * fix(ui): synchronize custom discussion palettes from first paint * fix(clickclack): explicitly identify theme-aware discussion embeds
166 lines
6.7 KiB
Markdown
166 lines
6.7 KiB
Markdown
# ClickClack OpenClaw channel
|
|
|
|
Official OpenClaw channel plugin for ClickClack.
|
|
|
|
## Install
|
|
|
|
```sh
|
|
openclaw plugins install @openclaw/clickclack
|
|
```
|
|
|
|
## Setup
|
|
|
|
The recommended setup path uses the one-time command generated by ClickClack:
|
|
|
|
```sh
|
|
openclaw channels add clickclack --code 'https://clickclack.example.com/#XXXX-XXXX-XXXX'
|
|
```
|
|
|
|
Split-origin and path-mounted ClickClack deployments generate an exact
|
|
`/api/bot-setup-codes/claim#CODE` endpoint. OpenClaw validates the versioned
|
|
claim response and saves its canonical API base.
|
|
|
|
For manual token setup:
|
|
|
|
```sh
|
|
openclaw channels add clickclack \
|
|
--base-url https://clickclack.example.com \
|
|
--token ccb_... \
|
|
--workspace default
|
|
openclaw gateway
|
|
```
|
|
|
|
Run `openclaw onboard` for guided setup. The workspace value can be a
|
|
`wsp_...` id, slug, or display name.
|
|
|
|
For the default account only, `--use-env` reads `CLICKCLACK_BOT_TOKEN`; config
|
|
storage is the normal setup path.
|
|
|
|
### Public and private endpoints
|
|
|
|
`baseUrl` is the public ClickClack URL used in links that people open. Set the
|
|
optional `apiBaseUrl` when the gateway should call ClickClack through a
|
|
different server-to-server endpoint:
|
|
|
|
```json5
|
|
{
|
|
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",
|
|
},
|
|
},
|
|
}
|
|
```
|
|
|
|
This same-host pattern lets the public hostname stay fully protected by an
|
|
authentication gateway such as Cloudflare Access while the local OpenClaw
|
|
gateway talks directly to ClickClack. REST requests, setup verification, and
|
|
the realtime WebSocket use `apiBaseUrl`; browser-facing discussion links keep
|
|
using `baseUrl`. When `apiBaseUrl` is unset, it defaults to `baseUrl`.
|
|
|
|
## Command menus
|
|
|
|
ClickClack command menus are enabled by default. At gateway startup, the
|
|
extension publishes OpenClaw's native commands for composer autocomplete,
|
|
labeled with the bot's handle. The bot token must include `commands:write`;
|
|
current `bot:write` and `bot:admin` bundles include it.
|
|
|
|
Set `commandMenu: false` on an account to disable menu sync. Sync failures do
|
|
not prevent the gateway from starting, so older tokens and ClickClack servers
|
|
continue to work without a menu.
|
|
|
|
## Discussions
|
|
|
|
ClickClack can create one managed channel for each OpenClaw session:
|
|
|
|
The account token needs `channels:write`, which is included in `bot:admin` but
|
|
not in the normal `bot:write` setup token. The ClickClack server must also
|
|
support and return the managed-channel fields used by this integration.
|
|
|
|
```json5
|
|
{
|
|
channels: {
|
|
clickclack: {
|
|
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",
|
|
},
|
|
},
|
|
},
|
|
}
|
|
```
|
|
|
|
Opening a session discussion creates a public, externally managed channel and
|
|
stores its binding in the ClickClack plugin's SQLite state. Session archive,
|
|
restore, label, category, and deletion changes are reflected in the channel;
|
|
deletion archives the channel and never deletes its messages. `workspace`
|
|
defaults to the account workspace, and `section` defaults to `Sessions`.
|
|
`controlUrlBase` adds a link back to `/chat?session=<session-key>` in the
|
|
OpenClaw Control UI.
|
|
|
|
ClickClack-managed embed URLs explicitly advertise host-theme support. The
|
|
Control UI uses that provider-owned capability to apply its full palette before
|
|
the sidebar first paints and to stream live palette changes without rewriting
|
|
opaque or signed discussion URLs from other providers.
|
|
|
|
Enable discussions on exactly one ClickClack account. Multiple enabled
|
|
discussion accounts are rejected because the session discussion provider does
|
|
not have an account selector.
|
|
|
|
Messages in the managed channel run in a stable side session under the same
|
|
agent id as the attached main session. The plugin installs a scoped host grant
|
|
for `sessions_history`, `session_status`, and `sessions_send` between that side
|
|
session and its attached main session, so `tools.sessions.visibility` can stay
|
|
at its safer default `tree`. A second host-side policy blocks session discovery
|
|
and alternate targets; the side-agent prompt is not the authorization boundary.
|
|
The agent still needs those three tools in its effective tool allowlist.
|
|
|
|
The binding, managed ownership reference, and side-session identity include the
|
|
concrete OpenClaw session id as well as the pinned server and channel. Resetting
|
|
a reusable session key, replacing a binding, or retargeting it therefore revokes
|
|
the old channel locally, archives it when the old credential remains usable, and
|
|
starts a fresh channel and side transcript.
|
|
Messages arriving through an archived, reset, disabled, or retargeted managed
|
|
binding are dropped instead of falling back to the account's normal channel
|
|
routing. Released bindings leave a durable revoked-channel marker so delayed
|
|
realtime events remain fail-closed. Remote ownership is keyed by ClickClack
|
|
server and channel id, so renaming the local account cannot turn a managed
|
|
channel into an ordinary one.
|
|
|
|
Managed-channel ownership references include a durable per-installation id, so
|
|
two OpenClaw gateways using the same ClickClack workspace do not adopt each
|
|
other's discussion channels. They also include the destination and a durable
|
|
binding generation, so an account or workspace round trip cannot re-adopt a
|
|
previous channel. Changing or removing `controlUrlBase` is reflected on the next
|
|
lifecycle reconciliation pass.
|
|
|
|
If a channel-create response is lost, the pending ownership reservation
|
|
temporarily quarantines otherwise-unbound events in that workspace. The same
|
|
coarse reconciler then adopts the created channel or clears/archives the
|
|
ambiguous attempt; a reset cannot make the old channel fall through to ordinary
|
|
routing.
|
|
|
|
When a workspace move keeps the original workspace credential configured, the
|
|
plugin archives the old channel before release. If the token is replaced with a
|
|
workspace-scoped credential that cannot access the old workspace, OpenClaw
|
|
releases the binding into the revoked-channel marker without trying the new token
|
|
against the old channel; archive that leftover channel from ClickClack.
|
|
|
|
The main session gets a read-only `discussion` tool that pulls the latest
|
|
channel messages, including recent thread replies. The pull uses bounded
|
|
history and thread-request budgets; its output says when older active threads
|
|
may have been omitted. It never posts, archives, renames, or otherwise mutates
|
|
the discussion.
|
|
|
|
## Docs
|
|
|
|
See `docs/channels/clickclack.md` in the OpenClaw repository, or the published docs at `https://docs.openclaw.ai/channels/clickclack`.
|