How to Use OpenClaw Deep Links

OpenClaw deep links are a neat local automation bridge. The macOS app registers the openclaw:// scheme, and openclaw://agent can trigger a Gateway agent request. That means a local app, script, or Canvas page can hand a message to OpenClaw without shelling out to the CLI. The safety model is important: without an unattended key, the app prompts.

When this is the right move

Use deep links for local UI handoffs: a Canvas button that asks the agent to review a design, a local shortcut that starts a checklist, or a macOS automation that sends a bounded prompt. Use the CLI for server-side scripts and cron, and use channel messages when the trigger originates from chat.

The practical workflow

1. Start with a required message parameter. Keep it short and URL-encoded because this is passing through a URL scheme.
2. Optionally include sessionKey or thinking when you want to steer the run, but avoid overloading deep links with complex state.
3. Expect a confirmation prompt unless a valid unattended key is supplied.
4. Do not rely on deliver, to, or channel without unattended mode; the docs say those are ignored without a valid key.
5. For Canvas, trigger the link from JavaScript only when the user clearly intended to ask the agent to act.

Grounded command or config pattern

The documented local trigger uses the open command on macOS or a window.location.href assignment in Canvas JavaScript.

open 'openclaw://agent?message=Hello%20from%20deep%20link'

// Canvas JavaScript
window.location.href = "openclaw://agent?message=Review%20this%20design";

Supported query parameters include message, sessionKey, thinking, deliver, to, channel, timeoutSeconds, and key. message is required. The unattended key is intended for personal automations that you have deliberately authorized.

Operator notes

Deep links are best when they stay human-sized. A button labeled “Ask OpenClaw to review this screen” is understandable. A hidden link that sends a long instruction with delivery targets is not. Keep local UI triggers transparent so the owner knows what is being handed to the assistant.

Rollout approach

For use openclaw deep links, I would make the first pass deliberately small: one owner, one machine or channel, one visible test, and one rollback path. OpenClaw features become powerful when they connect to real tools and real messages, so the safest rollout is not a giant configuration day. It is a short rehearsal that proves the docs-grounded path works in your exact workspace before you depend on it while busy.

Common mistake

The common mistake is treating the command as the whole feature. The command starts the workflow, but the surrounding state is what keeps it reliable: config validation, auth, pairing, permissions, logs, and a tiny verification step. If those pieces are skipped, the next failure looks random even when OpenClaw is behaving exactly as configured.

Maintenance rhythm

Once this is working, write down the exact command, config path, or approval decision you used. Future you will not remember the tiny detail that made the setup safe. A small note in the workspace or runbook is cheaper than rediscovering the same behavior during an outage, especially after updates or machine changes.

Safety checks

Treat deep links as local action triggers, not a public API. Without key, the app prompts and ignores delivery fields; with a valid key, the run is unattended. Protect that key, avoid embedding it in shared files, and never let untrusted web content generate unattended OpenClaw actions.

How to verify it worked

Click or open a simple message-only link first. You should see the app confirmation prompt and then the agent run. For Canvas-triggered links, verify the page cannot accidentally fire the action on load; it should require an explicit click or user gesture.

If you want the operator version with sharper checklists, safer defaults, and fewer “why is this broken?” afternoons, The OpenClaw Playbook is the shortcut I would hand to a serious OpenClaw owner.