Clawpulse Bridge

Configure and maintain ClawPulse integration for OpenClaw, including token-protected status bridge, Tailscale-safe access, iOS endpoint/token defaults, and t...

Security Scan

The skill largely does what its description says (starts a local bridge + monitor), but the package metadata understates the real requirements and the supplied scripts will write files, spawn background daemons, and by default bind to 0.0.0.0 — behavior worth reviewing before installing.

Purpose & Capability

Metadata claims no required binaries or environment variables, but SKILL.md and shipped scripts clearly require python3 and an 'openclaw' CLI, read/write a workspace (creating .clawpulse.env and Python server files), and may call tailscale. The functional pieces are coherent with the stated purpose, but the registry metadata omits those practical requirements — an incoherence that could mislead users about what access and tools are needed.

Instruction Scope

Runtime instructions are to run the included scripts which invoke 'openclaw status --json', read workspace/IDENTITY.md, write .clawpulse.env, drop Python server files into the workspace, and start background processes. This stays within the stated goal (producing a token-protected status endpoint and a monitor), but it does entail reading local identity/config and exposing generated tokens — so review what data may be served and who can reach the endpoints.

Install Mechanism

There is no external installer or remote download; all code is provided in the skill bundle (shell + Python). The scripts copy files into the workspace and use nohup to run daemons, but there is no high-risk 'download-and-extract arbitrary archive' step in the install spec.

Credentials

The registry lists no required env vars, yet the scripts create and rely on .clawpulse.env (STATUS_TOKEN, MONITOR_TOKEN) and read environment variables like BIND_HOST, WORKSPACE, and Tailscale outputs. The tokens are generated locally (no external secrets requested), which is appropriate, but the metadata omission is misleading and the skill will store tokens on disk (workspace/.clawpulse.env).

Persistence & Privilege

The setup scripts start persistent background processes (nohup, ThreadingHTTPServer) and by default bind the bridge to 0.0.0.0 (remote-ready). While this is part of the bridge/monitor design, it introduces network exposure and a persistent presence on the host that users should intentionally permit and lock down (or run in local-only 127.0.0.1 mode).

What to consider before installing

Before installing/run the scripts: 1) Inspect the included files locally (scripts/*.sh and *.py) — they will write files into the repository/workspace and start background processes. 2) Run the scripts in dry-run mode first (no --apply) to see the generated endpoint/token. 3) Prefer BIND_HOST=127.0.0.1 for local-only use; only use 0.0.0.0 when you understand and accept remote exposure. 4) Verify the presence and trustworthiness of the 'openclaw' binary the scripts call; the monitor executes 'openclaw status --json' and will expose parts of that output via the token-protected endpoints. 5) Review workspace/.clawpulse.env after generation — tokens are stored there; treat them as secrets and rotate if needed. 6) Because the package metadata omits required binaries/envs and has no homepage/source attribution, exercise extra caution (run in an isolated environment or VM if unsure). If you want higher assurance, ask the publisher for a provenance/source URL or sign-off on what host paths the scripts will modify.

ClawPulse

Overview

Set up a secure status bridge from OpenClaw to ClawPulse and keep it working with minimal manual steps.

Dependencies

• Required: openclaw, python3
• Optional (remote access only): tailscale

Quick Workflow

1. One-command bootstrap (recommended): bash scripts/bootstrap_clawpulse.sh --apply.
2. This runs bridge + monitor setup, then prints QR/token for app import.
3. Default bind is remote-ready (0.0.0.0) for mobile devices on Tailscale/LAN.
4. If sync fails, use the troubleshooting checklist.

Step 1 — Bootstrap the bridge

Run:

# Dry-run: generate token/server file and print settings (no background process)
bash scripts/setup_clawpulse_bridge.sh

# Start service (remote-ready default + QR)
bash scripts/setup_clawpulse_bridge.sh --apply

# Optional local-only mode (hardened)
BIND_HOST=127.0.0.1 bash scripts/setup_clawpulse_bridge.sh --apply

Expected outputs:

• endpoint (local or Tailscale format)
• bearer token
• bind host/port and log path

Step 2 — Validate response contract

The bridge response should include at least:

{
  "online": true,
  "assistantName": "OpenClaw",
  "workStatus": "工作中",
  "tokenUsage": {"prompt": 1, "completion": 2, "total": 3},
  "thought": "..."
}

Step 3 — Wire the app

Use in ClawPulse:

• URL: http://<tailscale-or-lan-ip>:8787/health
• Token: Bearer token from setup script
• Polling default: 5s (more responsive)

Monitor mode (recommended)

Use monitor as the public endpoint, keep bridge as internal source.

# Start/restart monitor (reads bridge and applies anti-flap state machine)
bash scripts/setup_clawpulse_monitor.sh --apply

Then configure app with monitor endpoint/token (from script output or QR), not bridge token.

Troubleshooting

• HTTP blocked on iOS: ensure app Info.plist has ATS exception for development, or use HTTPS.
• 401 auth error: token mismatch; regenerate and reapply.
• 403 forbidden: source IP is not local/Tailscale; confirm the device is connected to Tailscale.
• Timeout: check bridge process and network reachability.
• Wrong display name: update workspace/IDENTITY.md Name field.

Token rotation

Re-run setup script with ROTATE_TOKEN=1:

ROTATE_TOKEN=1 bash scripts/setup_clawpulse_bridge.sh

Update token in ClawPulse immediately.