@openclaw/clickclack 2026.7.2-beta.2 → 2026.7.2-beta.4

package/README.md

@@ -10,6 +10,18 @@ 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 \
@@ -24,6 +36,31 @@ Run `openclaw onboard` for guided setup. The workspace value can be a
 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
@@ -35,6 +72,89 @@ 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.
+
+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`.

package/dist/api.js

@@ -1,3 +1,3 @@
-import { a as createClickClackClient, d as DEFAULT_ACCOUNT_ID, f as listClickClackAccountIds, h as resolveDefaultClickClackAccountId, m as resolveClickClackAccount, p as listEnabledClickClackAccounts, s as clickClackConfigSchema } from "./setup-surface-B346XaAu.js";
-import { a as setClickClackRuntime, i as getClickClackRuntime, n as buildClickClackTarget, r as parseClickClackTarget, t as clickClackPlugin } from "./channel-BnREQIP8.js";
+import { S as resolveDefaultClickClackAccountId, b as listEnabledClickClackAccounts, d as createClickClackClient, m as clickClackConfigSchema, v as DEFAULT_ACCOUNT_ID, x as resolveClickClackAccount, y as listClickClackAccountIds } from "./setup-surface-Baf26N-D.js";
+import { T as setClickClackRuntime, n as buildClickClackTarget, r as parseClickClackTarget, t as clickClackPlugin, w as getClickClackRuntime } from "./channel-BDq0KWDB.js";
 export { DEFAULT_ACCOUNT_ID, buildClickClackTarget, clickClackConfigSchema, clickClackPlugin, createClickClackClient, getClickClackRuntime, listClickClackAccountIds, listEnabledClickClackAccounts, parseClickClackTarget, resolveClickClackAccount, resolveDefaultClickClackAccountId, setClickClackRuntime };