Exposing Agents to Users

This module covers the design, deployment, and security of assistant gateways that bridge public messaging networks with local system interfaces. You will configure OpenClaw (the real, actively-maintained gateway at github.com/openclaw/openclaw), write a markdown-based custom skill, and audit runtime traces.

Note on this rewrite: an earlier version of this module described a fictional install flow (git clone + npm + a Python @skill decorator, port 9000) that doesn't match how the real tool works. This version is grounded in OpenClaw's actual documentation: it installs via a script, not source; skills are markdown files, not Python decorators; and the gateway's real default port is 18789.

📁 Training Workspace: ~/AI_BOOTCAMP

What you'll learn

• Long polling vs. webhooks vs. WebSockets for messaging gateways
• OpenClaw's real install path and its markdown-based skill system
• Locking down channel access with allow-lists and DM pairing

How it works

An assistant gateway acts as a protocol translator and security proxy between public, asynchronous API networks (e.g., Telegram, Slack, Discord) and your local agent. OpenClaw runs as a single Gateway process, a local-first control plane for sessions, channels, tools, and events, that bridges 20+ messaging platforms to one agent.

A. Physical Constraints & Boundaries

1. Network Latency & Round-Trip-Time (RTT):
   • Long Polling Loop: A gateway querying a platform's /getUpdates-style endpoint in a loop is easy to run behind NAT/firewalls, but introduces a polling latency offset (typically 1.0–2.0 seconds) and increases network overhead.
   • Webhooks: The platform pushes events directly to a public HTTPS endpoint. This reduces RTT to 50–200ms, but requires a public IP address, valid SSL certificates, and open inbound ports.
2. Memory & System Resource Overhead:
   • The Gateway itself is a Node.js process (Node 22.22.3+/24.15+/25.9+ required).
   • Tool execution (exec, file writes) runs as subprocesses under the Gateway's own approval-mode policy rather than an unrestricted shell.
3. I/O Isolation & Security Boundaries:

   RISK OF REMOTE CODE EXECUTION

   • Subprocess Execution: Executing arbitrary system commands on the host machine poses extreme risks. A prompt injection attack could trick the LLM into invoking destructive shell commands.
   • Access controls: OpenClaw's Gateway checks channel-level authorization before ever reaching tool execution, per-platform allow-lists, DM pairing approval, and a global deny-by-default fallback (see Failure Mode Analysis below).

---

Options & when to use each

Integration Model	Latency (RTT)	Local Port / NAT Requirements	Resource Overhead	Payload Security Risk	Connection Stability	Primary Production Bottleneck
Long Polling	Moderate (1–2s)	None (Outbound HTTP Only)	Low (Client-driven loop)	Low (No public port exposed)	High (Auto-reconnects on drop)	HTTP connection timeouts during inactivity
Webhooks (Direct HTTPS)	Low (50–200ms)	Public IP + SSL Cert (Port 443/8443)	Low (Reactive execution)	High (Requires exposing public API)	Moderate (Relies on DNS and firewall status)	Inbound network routing and SSL handshake limits
WebSockets / TCP Tunnel	Ultra-Low (<10ms)	Outbound connection to tunnel broker	Moderate (Persistent socket connection)	Low (Encapsulated payload)	High (Requires custom keep-alive logic)	Client-side socket reconnection drops

---

Build it: OpenClaw + a custom skill

A. Installation

OpenClaw installs via script, not a git clone:

# macOS/Linux
curl -fsSL https://openclaw.ai/install.sh | bash

# Windows PowerShell
irm https://openclaw.ai/install.ps1 | iex

B. First-Run Setup

To perform the initial first-run onboarding configuration and launch the dashboard web UI for OpenClaw, run the following setup commands:

openclaw onboard --install-daemon   # wizard: model provider, API key, Gateway config
openclaw gateway status             # confirms Gateway listening on port 18789
openclaw dashboard                  # opens the browser-based control UI

onboard --install-daemon is the whole setup path, it configures the model provider, credentials, and the Gateway in one wizard. Connecting a specific channel (Telegram, Discord, Slack) is a separate step documented per-platform; Telegram, for example, needs only a bot token from @BotFather.

C. Writing a Custom Skill

OpenClaw skills are markdown instruction files, not Python code, there is no @skill decorator. A skill teaches the agent when and how to use the tools it already has (like exec), rather than defining a new function.

Directory layout:

~/.openclaw/workspace/skills/
└── workspace-report/
    └── SKILL.md

Create a new markdown configuration file named SKILL.md inside that directory, defining the skill name, description, and execution rules:

---
name: workspace-report
description: Lists files in the active training workspace to check progress.
---

# Workspace Report

When the user asks what's in the training workspace, use the `exec` tool to run:

​```bash
ls -la ~/AI_BOOTCAMP
​```

Summarize the file listing in plain language, group by directory, note anything
that looks like a stale lab file older than the current module.

Required frontmatter is just name (lowercase, digits, hyphens) and description (one line, under 160 characters, shown to the agent and in slash-command discovery). Optional fields include user-invocable (expose as a slash command, default true) and metadata.openclaw.requires (gate the skill on a binary or env var being present).

Verify that the new skill has been successfully detected and registered by running the CLI query command:

openclaw skills list

---

What goes wrong

Failure Mode	Log Signature	Root Cause	Mitigation Action
Gateway Port Collision	Error: listen EADDRINUSE: address already in use :::18789	Another OpenClaw instance or process is already bound to the default Gateway port.	Check running processes with lsof -i :18789, or stop the existing Gateway with openclaw gateway status → openclaw gateway stop.
Unauthorized Channel Access	Gateway logs a denied message from an unrecognized platform user ID.	Sender isn't in a per-platform allow-list, hasn't completed DM pairing, and the global allow-all flag is off, OpenClaw denies by default.	Approve the sender's one-time pairing code via the CLI, or add their platform user ID to the relevant allow-list env var (e.g. TELEGRAM_ALLOWED_USERS).
Skill Not Discovered	openclaw skills list doesn't show the new skill.	Malformed YAML frontmatter, missing required name/description field, or an unmet metadata.openclaw.requires gate.	Validate frontmatter syntax; if the skill file watcher is disabled, start a new session so the agent picks up the refreshed skill list.
Approval Blocked a Tool Call	Agent reports the action needs manual approval, or it's silently rejected.	approvals.mode is manual (or the command matches the hardline blocklist / a user-defined deny rule), so the tool call didn't auto-execute.	Check approvals.mode in config; irreversible commands (recursive deletes, disk formatting) are blocked regardless of mode and are not meant to be bypassed.

---

Confirm it worked

A. Confirming the Gateway Is Live

To confirm that the Gateway process is up and listening on port 18789, run the status query command:

openclaw gateway status

Expected output confirms the Gateway process is running and listening on port 18789, along with which channels are currently connected.

B. Performing a Skill Execution Audit

1. Open your connected messaging client (or use openclaw dashboard for the local web chat) and send a message that should trigger your skill, e.g. "what files do we have in our training workspace?"
2. Confirm the agent's response matches what ls -la ~/AI_BOOTCAMP actually returns, this validates the skill's instructions were matched and the exec tool ran under the current approval-mode policy rather than being silently blocked.
3. Alternatively, test directly from the CLI without a channel round-trip:

   openclaw agent --message "what files do we have in our training workspace?"

C. Testing Skill Discovery After an Edit

1. Edit your SKILL.md file (change the description or add a new instruction).
2. Start a new session (or confirm the file watcher picked up the change) and re-run:

   openclaw skills list

3. Confirm the updated description appears, this is your signal that the agent's next request will use the revised instructions.

Next: Streaming Agent UIs , giving users a live view into what the agent is doing while it works, not just a final answer.