OpenClaw Power User Guide

OpenClaw is not just another CLI wrapped around a model. It is an operating layer: gateway, agents, channels, sessions, browser control, approvals, heartbeats, sub-agents, ACP, and skills all fit together. That is why the command list alone is never enough. You need an operating model.

This guide turns the raw notes into a single playbook. It is based on OpenClaw 2026.3.2 and the supplied community notes validated on March 8, 2026. Where a command mentions a skill, plugin, or provider-specific tool, treat it as an installed-extension example unless your own environment already ships it.

Table of contents

The Mental Model

If you understand this flow, most of OpenClaw becomes easier to reason about:

Human -> Channel -> Agent Binding -> Session -> Tools/Sub-Agents -> Gateway -> Nodes

The key layers:

1. Channels are where messages arrive: Telegram, Discord, WhatsApp, ACP, CLI, and browser-connected workflows.
2. Agents are the personalities and routing targets that own behavior, bindings, heartbeat settings, and approvals.
3. Sessions are the durable workstreams. They hold history and give continuity across turns.
4. Gateway is the runtime bridge for remote access, browser nodes, auth, discovery, and health checks.
5. Tools and sub-agents are how work gets done: browser actions, exec, file ops, messaging, skills, and spawned workers.

If you only remember one rule, make it this one: sessions are where state lives, files are where durable memory lives, and the gateway is what makes the whole system reachable.

The Five Commands That Matter Most

If you are under time pressure, start with these:

openclaw status
openclaw gateway status
openclaw sessions list --active 120
openclaw channels status
openclaw gateway logs --tail 100

Those five commands answer the five most common operator questions:

1. Is the system generally healthy?
2. Is the gateway up?
3. What sessions are currently alive?
4. Are channels connected?
5. What do the last logs say before I touch anything?

CLI Commands Quick Reference

Gateway management

# Query commands
openclaw gateway status
openclaw gateway health
openclaw gateway probe
openclaw gateway call <method>

# Lifecycle commands
openclaw gateway run
openclaw gateway install
openclaw gateway start
openclaw gateway stop
openclaw gateway restart
openclaw gateway uninstall

# Discovery and logs
openclaw gateway discover
openclaw gateway logs --tail 100

Key options:

• --url <url> for remote WebSocket targets.
• --token <token> or --password <password> when auth is required.
• --json when the output is for scripts, dashboards, or automation.
• --timeout <ms> to prevent long hangs during unhealthy probes.
• --ssh <user@host> when you want remote access without exposing the gateway publicly.

Session control

openclaw sessions list
openclaw sessions list --agent <id>
openclaw sessions list --all-agents
openclaw sessions list --active 120
openclaw sessions list --json

openclaw sessions cleanup --dry-run
openclaw sessions cleanup --enforce
openclaw sessions cleanup --active-key <key>

Important distinction: openclaw sessions lists stored sessions. For live session interaction, use the agent-side tools such as sessions_list, sessions_history, sessions_send, and sessions_spawn.

Sub-agent management

openclaw subagents list
openclaw subagents kill --target <id>
openclaw subagents steer --target <id> --message "..."

The CLI is enough for inspection and intervention. Full orchestration usually happens through agent tools.

Agent routing and multi-agent control

openclaw agents list
openclaw agents add <id> --workspace <path>
openclaw agents bindings
openclaw agents bind --agent <id> --bind <channel>[:account]
openclaw agents unbind --agent <id> --bind <channel>
openclaw agents set-identity --agent <id> --name "..."
openclaw agents delete <id>

Binding scope is where many teams get tripped up:

• --bind telegram means the default Telegram account for that channel.
• --bind telegram:ops means a specific account or named route.
• accountId: "*" acts as a fallback.

Channel management

openclaw channels list
openclaw channels status
openclaw channels logs --tail 50
openclaw channels login telegram
openclaw channels login whatsapp

When a provider disconnects, check the channel before you restart the gateway. Most failures are auth or provider-side state, not core runtime failure.

Browser control

openclaw browser profiles
openclaw browser --browser-profile chrome tabs
openclaw browser --browser-profile openclaw start
openclaw browser snapshot --refs aria
openclaw browser screenshot --fullPage
openclaw browser navigate <url>
openclaw browser click <ref>
openclaw browser type <ref> "text"
openclaw browser act --kind click --ref <ref>

Use the chrome profile when you need your already logged-in browser context. Use the openclaw profile when you need isolation and reproducibility.

Config and system

openclaw config list
openclaw config get <key>
openclaw config set <key> <value>
openclaw config file
openclaw status
openclaw doctor

ACP and IDE integration

openclaw acp
openclaw acp client
openclaw acp --session agent:main:main
openclaw acp --session-label "name"
openclaw acp --reset-session

For Zed, add this to ~/.config/zed/settings.json:

{
  "agent_servers": {
    "OpenClaw ACP": {
      "command": "openclaw",
      "args": ["acp"]
    }
  }
}

Approvals and exec security

openclaw approvals get
openclaw approvals allowlist add "<pattern>"
openclaw approvals allowlist remove "<pattern>"
openclaw approvals set --file ./approvals.json
openclaw approvals get --gateway
openclaw approvals get --node <id>

Approvals are not polish. They are your blast-radius control.

Gateway Mastery

The gateway is the hinge of a serious OpenClaw setup. Once you understand how it is started, exposed, authenticated, and discovered, remote workflows become much easier to operate safely.

Run the gateway locally

openclaw gateway run --port 18789 --bind loopback
openclaw gateway run --dev
openclaw gateway run --allow-unconfigured

Safety guards worth remembering:

1. Local mode typically requires gateway.mode=local unless you explicitly bypass it.
2. OpenClaw should not bind beyond loopback without auth.
3. SIGUSR1 triggers an in-process restart.
4. SIGINT and SIGTERM should shut down gracefully.

Prefer SSH for remote access

The safest remote pattern is usually SSH tunneling first, public exposure later.

openclaw gateway probe --ssh user@gateway-host
openclaw gateway probe --ssh user@gateway-host:2222
openclaw gateway health --url wss://gateway.example.com:18789 --token <token>

Use direct WebSocket exposure only when you have clear network controls and proper auth. If Tailscale is already part of your stack, it is usually a cleaner option:

openclaw gateway run --tailscale serve
openclaw gateway run --tailscale funnel

funnel is public. Treat it accordingly.

Discovery matters

Discovery saves time in local and hybrid networks:

openclaw gateway discover
openclaw gateway discover --domain openclaw.internal.

Bonjour TXT records typically expose fields such as role, authMode, port, and bindMode. That is enough to identify whether you are hitting the right runtime before you waste time on auth debugging.

Gateway configuration

Default config location:

~/.openclaw/openclaw.json

Representative configuration:

{
  gateway: {
    mode: "local",
    port: 18789,
    bind: "loopback",
    auth: {
      mode: "token",
      token: "your-token",
    },
    remote: {
      url: "wss://gateway.example.com:18789",
      sshTarget: "user@gateway-host",
      sshIdentity: "~/.ssh/id_ed25519",
    },
    nodes: {
      browser: {
        mode: "auto",
        node: "node-id",
      },
    },
  },
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",
        target: "last",
        prompt: "Read HEARTBEAT.md if it exists...",
        activeHours: { start: "08:00", end: "22:00" },
        lightContext: true,
        includeReasoning: false,
      },
    },
  },
  session: {
    maintenance: {
      mode: "warn",
      maxSessions: 100,
      maxTranscriptLines: 5000,
    },
  },
}

The most important gateway decision is not the port. It is the trust boundary: loopback, LAN, tailnet, or public exposure.

Session Management That Scales

In small setups, sessions feel like chat logs. In real use, they are more like named workstreams with retention, history, and maintenance policy.

Session keys

OpenClaw session keys use a stable shape:

agent:<agent-id>:<channel>:<chat-id>

Examples:

• agent:main:telegram:direct:1847295601
• agent:main:discord:guild-123:channel-456
• agent:ops:main

That naming matters because it lets you reason about ownership, route, and scope directly from the key.

Core session tools

sessions_list({ limit: 10, activeMinutes: 120, messageLimit: 1 });

sessions_history({ sessionKey: "agent:main:main", limit: 50 });

sessions_send({ sessionKey: "agent:main:main", message: "Hello" });

sessions_spawn({
  task: "Analyze this code",
  runtime: "subagent",
  mode: "session",
  label: "code-review",
  thread: true,
});

Use mode: "run" for bounded, one-shot tasks. Use mode: "session" when the work should remain available for steering, follow-up, or continued ownership.

Heartbeat versus cron

This is one of the most important design choices in OpenClaw.

Use heartbeat when:

1. Several checks can be batched.
2. Timing can drift a little.
3. Conversational context helps.
4. You want to reduce the number of separate scheduled jobs.

Use cron when:

1. Exact timing matters.
2. You want isolation.
3. The task deserves a different model or policy.
4. The work is explicitly one-shot.

Representative heartbeat config:

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",
        target: "last",
        prompt: "Read HEARTBEAT.md if it exists. Follow it strictly. Do not infer old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.",
        ackMaxChars: 300,
        lightContext: true,
        activeHours: { start: "08:00", end: "22:00" },
      },
    },
  },
}

Recommended response contract:

• Nothing needs attention: reply HEARTBEAT_OK.
• Something needs attention: send the alert text only.

Simple HEARTBEAT.md example:

- Check unread emails from the last 2 hours
- Check calendar events in the next 24 hours
- Check weather for my city
- Check GitHub notifications
- Remind me about task X if it is after 14:00

The smaller and sharper the heartbeat context, the better it tends to behave.

Top 50 Power-User Hacks

The difference between a casual OpenClaw setup and a durable one is rarely one big feature. It is almost always the accumulation of small operating decisions. These 50 hacks are the ones that compound.

Gateway and session control

1. Prefer openclaw gateway restart over manual stop/start for routine reloads because it shortens downtime and reduces operator error.
2. Use openclaw gateway status as your single-command reality check before you touch config.
3. Reach for openclaw gateway probe when you suspect the wrong gateway, stale discovery data, or mixed local/remote state.
4. Read the last 100 to 200 lines of gateway logs before changing runtime settings.
5. Use --json for any output that a script, dashboard, or another agent will consume.
6. Filter sessions by recency instead of scrolling the full store: openclaw sessions list --active 120.
7. Run openclaw sessions cleanup --dry-run first. Cleanup is an ops change, not a guess.
8. Protect a known-live session during maintenance with --active-key.
9. Scope session inspection by agent when debugging routing collisions.
10. Remember that stored session listing and live session control are different surfaces.

Useful commands:

openclaw gateway restart
openclaw gateway status
openclaw gateway probe
openclaw gateway logs --tail 200
openclaw sessions list --active 120 --json
openclaw sessions cleanup --dry-run
openclaw sessions cleanup --enforce --active-key "agent:main:main"

Remote access and multi-agent routing

11. Prefer SSH tunneling over public gateway exposure whenever possible.
12. If you must expose a WebSocket endpoint, treat token or password auth as mandatory.
13. Use Tailscale for private remote access before you consider opening firewall holes.
14. Use gateway discover before hand-editing remote URLs on a local network.
15. Bind channels explicitly to specialist agents rather than hoping the default agent absorbs everything cleanly.
16. Use account-scoped bindings such as telegram:ops when a channel has mixed responsibilities.
17. Set visible agent identity values so humans can tell which agent answered without opening config.
18. Inspect agent bindings before you debug “wrong agent responded” incidents.
19. Check channel logs for provider-specific failures before blaming the gateway.
20. Re-auth the broken channel before you restart the whole stack.

Useful commands:

openclaw gateway probe --ssh user@gateway-host
openclaw gateway health --url wss://gateway.example.com:18789 --token <token>
openclaw agents bindings
openclaw agents bind --agent work --bind telegram:ops
openclaw channels status
openclaw channels logs --tail 100
openclaw channels login telegram

Automation and heartbeats

21. Use heartbeat for batched situational awareness, not for exact reminders.
22. Use cron when the exact minute matters or when you want strong task isolation.
23. Add activeHours so your automation does not become ambient spam.
24. Keep lightContext: true on heartbeat unless you have a strong reason to inject more.
25. Adopt a strict HEARTBEAT_OK contract so no-op turns stay cheap and quiet.
26. Keep heartbeat prompts narrow and operational; vague prompts drift.
27. Put the recurring checklist in HEARTBEAT.md, not in your head.
28. Use one-shot sessions_spawn for bounded analysis and synthesis tasks.
29. Use persistent session mode for streams of work that need continuity and steering.
30. Archive stale memory files instead of letting the workspace turn into an archaeological dig.

Useful patterns:

openclaw sessions spawn --task "Summarize today's activity from memory/*.md" --label "daily-summary"

# HEARTBEAT.md

- Calendar events in the next 24 hours
- Weather for my city
- GitHub notifications
- Surface anything urgent, else HEARTBEAT_OK

Browser, ACP, and execution workflows

31. Prefer ARIA refs from browser snapshot because they stay stable longer than pixel-based targeting.
32. Use the chrome browser profile when you need existing cookies, sessions, and live tabs.
33. Use the isolated openclaw browser profile when you need reproducibility.
34. Use ACP for IDE-linked work where session continuity should follow your editor.
35. Use --reset-session in ACP when context drifts but the session identity should remain stable.
36. For long installs and builds, use background execution plus polling instead of blocking the whole turn.
37. Split large investigations across multiple sub-agents and synthesize the results.
38. Chain browser research into local presentation workflows instead of dumping raw findings into chat.
39. Compare models on the same prompt for hard coding tasks or visual guide generation.
40. Cache expensive outputs in workspace files so repeated workflows stay cheap.

Representative patterns:

const run = await exec({
  command: "npm install",
  yieldMs: 10000,
  background: true,
});

const result = await process({
  action: "poll",
  sessionId: run.sessionId,
  timeout: 30000,
});

const results = await Promise.all(
  repos.map(repo =>
    sessions_spawn({
      task: `Analyze ${repo}`,
      label: `analyze-${repo}`,
      mode: "run",
    })
  )
);

Performance, safety, and operating discipline

41. Search memory before you read large files into context.
42. Use fast models for lightweight tasks and reserve heavier models for analysis.
43. Check session or token budget regularly in long-running workflows.
44. Avoid tight poll loops; use longer waits and push-based completion when available.
45. Use trash instead of rm for recoverable deletes.
46. Build an approvals allowlist for high-trust commands to reduce repetitive friction safely.
47. Keep tokens out of CLI args because process lists are not private.
48. Never inject MEMORY.md into shared or group contexts.
49. Maintain a lightweight audit trail for external actions.
50. Write lessons into AGENTS.md, TOOLS.md, or durable files instead of trusting chat memory.

Useful commands:

openclaw approvals allowlist add "~/Projects/**/bin/rg"
openclaw approvals allowlist add "/usr/bin/uptime"
openclaw approvals allowlist add --agent main "/usr/bin/uname"

export OPENCLAW_GATEWAY_TOKEN=abc123
openclaw acp

Example audit file:

# External Actions Log

## 2026-03-06

- 10:30 Sent email to team@example.com
- 11:00 Posted product update to social
- 14:00 Sent webhook to https://api.example.com/hook

30 Advanced Patterns

Power users eventually discover that commands are not the hard part. The hard part is choosing the right pattern before the system drifts into noise, cost, or accidental complexity.

Design and memory discipline

1. Follow the text-over-brain rule: files persist, memory windows do not.
2. When someone says “remember this,” update a real file such as memory/YYYY-MM-DD.md.
3. Distill daily logs into MEMORY.md instead of letting the summary file become a transcript dump.
4. Put reusable conventions in AGENTS.md or TOOLS.md, not in ephemeral chat.
5. Treat sessions as named workstreams with owners and purpose, not just conversation threads.

Scheduling and orchestration

6. Choose heartbeat for fuzzy, batched attention management.
7. Choose cron for exact timing, isolation, or model-specific execution.
8. Use thread-bound sessions in Discord-like environments when the conversation needs a durable home.
9. Spawn one-shot sub-agents for finite research, review, and synthesis tasks.
10. Use persistent session mode when the task needs continued steering or accountability.

Communication patterns

11. Reply only when value exceeds interruption cost.
12. Use reactions to acknowledge without cluttering the channel.
13. Adapt formatting to the platform instead of forcing one house style everywhere.
14. Use TTS or voice delivery for long summaries, stories, or briefings.
15. Keep replies direct and consequence-oriented. In ops workflows, friendliness is not a substitute for clarity.

Diagnostics and failure handling

16. Start with openclaw status before you touch anything else.
17. Escalate from gateway health to channels to logs to provider APIs in that order.
18. Read logs before you re-auth, restart, or rewrite config.
19. Confirm session and sub-agent state before you kill stuck workers.
20. When model access fails, test the provider directly with curl before assuming OpenClaw is the problem.

Performance and cost control

21. Search memory before opening large context files.
22. Extract a snippet after search instead of loading the whole document.
23. Cache expensive or repeated outputs inside the workspace.
24. Use background execution and poll with sensible timeouts for long-running commands.
25. Maintain a model-selection matrix by task type.

Workflow composition

26. Broadcast once only when the message is truly universal. Otherwise customize by channel.
27. Chain research, synthesis, and delivery as separate steps.
28. Turn repetitive review workflows into a pipeline: watch, spawn, analyze, report, monitor.
29. Convert recurring gaps into skills instead of solving the same problem manually each week.
30. Treat documentation as part of execution. Good operators leave the system more legible than they found it.

One small example of that mindset:

const results = memory_search({ query: "project X", maxResults: 3 });
const snippet = memory_get({ path: results[0].path, from: 10, lines: 20 });

That pattern scales far better than dumping full files into every turn.

Troubleshooting Guide

The fastest path through most incidents is a diagnostic cascade rather than random command hunting.

Diagnostic cascade

openclaw status
openclaw gateway status
openclaw channels status
openclaw gateway logs --tail 100
openclaw config file

If that does not isolate the problem, move to the relevant subsystem.

Gateway issues

If the gateway will not start:

openclaw gateway status
openclaw gateway stop
rm ~/.openclaw/gateway.pid 2>/dev/null
openclaw gateway run --force
openclaw gateway logs --tail 50

If remote connection fails:

openclaw gateway probe --ssh user@host
openclaw gateway health --url ws://127.0.0.1:18789 --token <token>

Channel issues

If a provider disconnects:

openclaw channels status
openclaw channels login <provider>
openclaw channels logs --tail 100

Memory issues

If memory is not loading as expected:

ls -la ~/.openclaw/workspace/MEMORY.md
ls -la ~/.openclaw/workspace/memory/

Sub-agent issues

If a worker is stuck:

openclaw subagents list
openclaw subagents kill --target <id>

Model issues

If you see API or provider failures:

cat ~/.openclaw/models.json
curl -H "Authorization: Bearer $KEY" https://api.provider.com/v1/models
openclaw models list

The point is not to memorize every recovery command. The point is to stop guessing and narrow the fault domain quickly.

Security Best Practices

Security in OpenClaw is mostly about limiting accidental blast radius.

1. Use trash over rm when deletion should be recoverable.
2. Build an approvals allowlist for trusted commands.
3. Use token files or environment variables instead of CLI args.
4. Never load MEMORY.md in group or shared contexts.
5. Require explicit approval for any action that leaves the machine.
6. Rotate API keys on a schedule and remind yourself via heartbeat if needed.
7. Keep an audit trail for outbound side effects.
8. Restrict heartbeat activity to business or waking hours.
9. Keep heartbeat context light unless broad workspace injection is genuinely necessary.
10. Protect active sessions during cleanup.

The shortest useful security policy is this: read freely, write carefully, send externally only with intent.

pi.dev Bridge Integration

One of the most interesting additions in the supplied notes is the pi.dev bridge. It gives OpenClaw a straightforward path into a large multi-provider coding stack when you want broader model choice or coding-focused workflows.

What pi.dev adds

pi.dev is a terminal coding agent that exposes:

• access to many providers and a large model catalog,
• tree-structured sessions for branching workflows,
• built-in read, shell, edit, write, grep, find, and ls primitives,
• an extension ecosystem for specialized tooling.

That makes it a strong companion when OpenClaw is handling orchestration, messaging, routing, or automation, and pi.dev is handling focused coding work.

Installation

npm install -g @mariozechner/pi-coding-agent
pi --version

Configuration can live in ~/.pi/models.json or in provider-specific environment variables such as GOOGLE_API_KEY, ANTHROPIC_API_KEY, or OPENAI_API_KEY.

OpenClaw skill layout

Expected location:

~/.openclaw/workspace/skills/pi-dev-bridge/

Typical files:

• SKILL.md
• index.js

Bridge usage

Basic task:

pi -
  dev -
  bridge({
    prompt: "Create a REST API with Express.js",
  });

Choose a specific model:

pi -
  dev -
  bridge({
    prompt: "Refactor this function",
    model: "google/gemini-3-flash-preview",
  });

Continue a prior session:

pi -
  dev -
  bridge({
    prompt: "Add error handling",
    continue: true,
  });

Compare models on the same task:

const [gemini, claude, gpt] = await Promise.all([
  pi - dev - bridge({ prompt, model: "gemini-2.5-flash" }),
  pi -
    dev -
    bridge({ prompt, provider: "anthropic", model: "claude-sonnet-4" }),
  pi - dev - bridge({ prompt, provider: "openai", model: "gpt-5.3-codex" }),
]);

Generate a visual guide:

pi -
  dev -
  bridge({
    prompt: "Create infographic markdown for 50 OpenClaw hacks",
    model: "google/gemini-2.5-pro",
    thinking: "high",
  });

Provider landscape

The supplied notes highlight this mix:

According to the supplied notes, the Gemini-focused validated list on March 8, 2026 included:

pi --list-models gemini

# Validated in the source notes on 2026-03-08:
# - gemini-3-flash-preview
# - gemini-3.1-flash-lite-preview
# - gemini-flash-latest
# - gemini-2.5-flash
# - gemini-2.5-pro
# - gemini-3-pro-preview

Visual guide workflow

This bridge is especially useful when you want OpenClaw to orchestrate a workflow and pi.dev to generate the deeper artifact.

const guide =
  (await pi) -
  dev -
  bridge({
    prompt: `Create visual guide with:
  - Section headers
  - Code blocks with syntax highlighting
  - Comparison tables
  - Step-by-step numbered lists

  Topic: "OpenClaw 50 Power Hacks"`,
    model: "google/gemini-2.5-pro",
    thinking: "high",
    timeout: 600000,
  });

await write({
  path: "VISUAL_GUIDE.md",
  content: guide.response,
});

Error handling

Where the bridge fits best

Use the bridge when you want:

1. multi-provider coding tasks from inside an OpenClaw workflow,
2. model comparison for difficult implementation work,
3. high-quality structured markdown for docs or visual guides,
4. session continuity across longer coding efforts.

Final Operating Advice

If you approach OpenClaw like a chatbot, it feels complex. If you approach it like a runtime with clear routes, boundaries, and files-as-memory, it becomes predictable.

That is the real unlock:

1. Use the gateway intentionally.
2. Keep sessions legible.
3. Choose heartbeat and cron on purpose.
4. Keep memory in files, not vibes.
5. Add bridges like pi.dev when they actually improve your workflow.

Do that consistently and OpenClaw stops feeling like a pile of features. It starts behaving like a system.

Related

OpenClaw is a practical example of context engineering in action. If you want to understand the broader discipline behind designing what the model sees, read Context Engineering: The Skill That Replaced Prompt Engineering.

Resources

• Docs mirror: `https://docs.openclaw.ai“
• Source: https://github.com/openclaw/openclaw
• Skills hub: https://clawhub.ai
• Community: https://discord.com/invite/clawd

Last updated: March 8, 2026
OpenClaw version referenced: 2026.3.2