OpenClaw connection and alerts¶

Use this optional connection only when OpenClaw is part of your private setup. It can do two separate jobs:

OpenClaw → Hub: OpenClaw uses Hub skills/MCP.
Hub → OpenClaw: the Hub sends a short stale-work reminder through OpenClaw hooks.

For OpenClaw → Hub MCP OAuth, including remote-browser callbacks, use the MCP OAuth callback guide. This page focuses mainly on Hub → OpenClaw reminder hooks.

Recommended setup path¶

Install the Hub skills.
Enable OpenClaw HTTP hooks with a dedicated hook token.
Use Settings → Phone alerts → Start pairing when your OpenClaw deployment can provision the hook token securely.
Use the manual path only when pairing is not suitable.
Run Save and send a test.
Set the alert schedule only after the connection works.

1. Add the ADHD Hub skills to OpenClaw¶

Run this where OpenClaw is installed:

npx skills add uniskela/adhd-hub -g -a openclaw

This installs the skills in OpenClaw's global skills directory. If you are developing an unreleased checkout instead, run the command from that checkout with ./skills in place of uniskela/adhd-hub.

2. Connect the Hub to OpenClaw¶

The simple mental model¶

This connection involves two separate services:

ADHD Hub finds stale open work and sends a reminder.
OpenClaw Gateway receives that reminder through its HTTP hook.

The hook bearer token is the shared password for that private connection. It is created/configured on the OpenClaw Gateway, then copied once into ADHD Hub's Settings → Phone alerts form. It is not the ADHD Hub auth token, not the Gateway login token, and not part of either URL.

An OpenClaw agent can help inspect configuration, explain errors, or submit the pairing request, but it must not print or reveal the hook token. A human operator or the deployment's secret-management mechanism must make the token available to both services.

Before configuring ADHD Hub, the Gateway must have HTTP hooks enabled:

{
  "hooks": {
    "enabled": true,
    "token": "<dedicated-long-random-hook-token>",
    "path": "/hooks",
    "allowedAgentIds": ["main"]
  }
}

Use a dedicated token that is different from the Gateway's normal authentication token. You can keep the value in an untracked OpenClaw .env file and reference it from openclaw.json with environment substitution:

# ~/.openclaw/.env or the Gateway process's working-directory .env
OPENCLAW_HOOK_TOKEN=<dedicated-long-random-hook-token>

{
  "hooks": {
    "enabled": true,
    "token": "${OPENCLAW_HOOK_TOKEN}",
    "path": "/hooks",
    "allowedAgentIds": ["main"]
  }
}

OpenClaw supports ${UPPERCASE_ENV_NAME} substitution in config strings. Keep the .env file out of Git and restrict its file permissions. Do not use the normal OPENCLAW_GATEWAY_TOKEN for this value: the hook token must be separate. A generic SecretRef object cannot be pasted directly into hooks.token on current OpenClaw versions, so use environment substitution or another supported deployment secret mechanism instead.

After hooks are enabled, configure ADHD Hub with the matching URL and token, then use Save and send a test. The token remains in the Gateway .env and is entered into the Hub UI only through the protected settings form; it should not be pasted into an agent prompt.

Pairing (recommended)¶

In ADHD Hub:

Open Settings → Phone alerts.
Click Start pairing.
Copy the generated prompt into OpenClaw.
Approve the pairing request in the Hub.

OpenClaw needs only the short pairing code; it never needs ADHD_HUB_AUTH_TOKEN.

Pairing is safe only when the OpenClaw side can provision hooks.token without exposing the raw token to the agent. Use a protected runtime secret mechanism supported by your OpenClaw version, or inject the token through the gateway service environment.

The pairing agent must never print, echo, paste, or reveal the hook token in chat, command arguments, config files, or tool output.

If secure provisioning is unsupported, pairing reports hooks_token_secretref_unsupported and stops. Follow the Hub's prerequisite message; do not work around it by exposing the token.

Manual path¶

Enable hooks on the OpenClaw gateway and create a bearer token there. Configure hooks.token securely on the gateway first. Then, as the operator, use Settings → Phone alerts to:

Open Advanced and add the private webhook URL, or the optional agent URL for a richer message.
Enter the OpenClaw hook bearer token (also under Advanced) directly into the Hub UI.
Turn Send alerts on or off.
Save, then choose Save and send a test.

The token is encrypted using the Hub's server access token before it is stored in openclaw.json. The API returns only whether a token is configured, never the token or a fragment of it. If you rotate ADHD_HUB_AUTH_TOKEN, enter the OpenClaw token again.

Use an HTTPS domain¶

The URL in this screen is an outbound URL from ADHD Hub to the OpenClaw gateway. It is not the Hub's URL and it does not create a reverse proxy route. If the Hub container cannot resolve or reach the hostname, the alert test will fail even when the URL works in your browser.

If your reverse proxy publishes the OpenClaw hook endpoints at the domain root, enter:

Webhook URL: https://openclaw.example.com/hooks/wake
Agent URL:   https://openclaw.example.com/hooks/agent

Use the Agent URL only when you want the richer agent-run path; the required minimum is the Webhook URL. The proxy must:

terminate TLS and forward POST requests to the OpenClaw gateway;
preserve the /hooks/wake and /hooks/agent paths and JSON request bodies; and
allow the Hub server's network egress while keeping the gateway hook token enabled.

Do not put the bearer token in the URL, query string, repository, .env committed to Git, or an MCP/agent prompt. The Hub sends it as an authentication header. The public hostname is safe to use only if the reverse proxy and OpenClaw hook authentication are already configured; otherwise prefer a Docker-network, LAN, or Tailscale hostname.

If the proxy uses a subpath rather than the domain root, include that prefix in both URLs, for example https://example.com/openclaw/hooks/wake. The final path must still reach OpenClaw's /hooks/wake or /hooks/agent endpoint.

For initial provisioning, you can still use an untracked .env file on the Hub server:

ADHD_HUB_OPENCLAW_WEBHOOK_URL=https://openclaw.example.com/hooks/wake
ADHD_HUB_OPENCLAW_TOKEN=<OpenClaw hook bearer token>
# Optional: lets OpenClaw turn the reminder into a friendly short message.
# ADHD_HUB_OPENCLAW_AGENT_URL=https://openclaw.example.com/hooks/agent

Restart the Hub after changing .env; changes saved in the web UI apply immediately. For a public HTTPS hostname, keep the gateway hook endpoints protected by their bearer token and restrict proxy access to the Hub or your private network where possible. The webhook token belongs only in the Hub server environment or encrypted Hub configuration — never in an MCP client, skill file, or committed configuration.

3. Choose the alert rhythm¶

The Hub checks for stale open threads every day at 09:00 by default. It sends nothing when there is no stale work, and it uses the Hub's reminder cooldown plus optional triage snooze to avoid repeats. Soft UI triage (Still relevant? / ask later) never auto-dismisses a thread; intentional abandon still uses dismiss. Dashboard Help me choose and MCP suggest_next_up use the same calm Next-up ranking (quiet/resume-first; optional energy / focus-project).

Choose the schedule, stale age, repeat cooldown, and maximum items in Settings → Phone alerts. Changes take effect immediately. For an environment-provisioned schedule, set this on the Hub server and restart it:

ADHD_HUB_STALE_NUDGE_CRON=0 18 * * 1-5

That example sends one weekday check-in at 18:00. Keep the message useful: one suggested next step is better than a long list of overdue work.

4. Test once¶

Use Save and send a test for a harmless connection check. To exercise the complete stale-work path, create or keep one deliberately stale open thread, then trigger the check with the Hub access token from a trusted machine:

curl -sS -X POST \
  -H "Authorization: Bearer $ADHD_HUB_AUTH_TOKEN" \
  http://adhd-hub:8787/api/admin/stale-nudge

If it succeeds, OpenClaw receives compact stale-thread entries grounded in the Hub's saved state: a short summary/context, one concrete restart action, and direct CTAs when safe links are available. With ADHD_HUB_PUBLIC_URL configured, a reminder can include Open in ADHD Hub, which opens that thread in the Now screen after authentication. Linked forge/source issues are included as a second CTA when a credential-free http(s) URL is available; otherwise the thread ID remains as the fallback. The optional agent endpoint can turn those entries into a non-nagging message while preserving supplied CTA links exactly, and save a brief memory digest (summaries + next steps only — never raw chats). Agents can also call MCP push_openclaw_memory for an on-demand short round-trip. The Hub's wiki remains the source of truth for project progress.

Optional: OpenClaw reads the Hub¶

An OpenClaw workflow or private cron can fetch stale work directly:

curl -sS \
  -H "Authorization: Bearer $ADHD_HUB_AUTH_TOKEN" \
  "http://adhd-hub:8787/api/threads?stale=true"

Treat the token as a secret and limit network access to trusted devices.

Why reminder hooks have no OAuth callback¶

The supported OpenClaw hook interface uses bearer authentication and does not provide an OAuth authorization contract for ADHD Hub to complete. Settings → Phone alerts therefore uses the same private, token-authenticated hook flow rather than presenting a callback that cannot be verified.