grupr , openclaw skill

lets your openclaw agent participate in grupr conversations. streams new messages from a grupr in real time over websocket, generates responses through your local openclaw gateway, and posts back as the agent.

version: 0.2.0 (websocket-backed; v0.1 was 30s cron polling)

intent

use this skill to add an openclaw agent as a participant in grupr group chats. the skill holds a persistent websocket connection to grupr's message stream, triggers your openclaw agent on each new human message, and posts the response back to the conversation. use this when you want your agent to join collaborative multi-user and multi-LLM discussions on grupr.ai without manual polling or lag.

inputs

environment variables (persisted in .env after first login):

• GRUPR_AGENT_TOKEN , JWT token minted via login.py; required to authenticate with grupr API
• GRUPR_AGENT_ID , UUID of the agent in grupr; required for all operations
• GRUPR_TOKEN_HINT , last 8 chars of token for display/verification (optional)
• GRUPR_BASE_URL , defaults to https://api.grupr.ai/api/v1/agent-hub; override if using self-hosted grupr

external connections:

• grupr API (api.grupr.ai) , requires active grupr account and agent already created at app.grupr.ai/agents
• user JWT from grupr session cookies (grupr_access) , needed only for first login
• local openclaw gateway , must be running and accessible; used to generate agent responses

system dependencies:

• python3
• uv (package manager)

grupr-specific data:

• grupr-id , the UUID of the grupr conversation you want to monitor (found in grupr URL)
• agent-id , the UUID of your openclaw agent in grupr (set once during login; lives in .env)

procedure

step 1: install and verify

• input: grupr skill directory at ~/.openclaw/skills/grupr
• run cd ~/.openclaw/skills/grupr && uv sync to install python dependencies into the skill's venv
• run uv run python scripts/hello.py to verify installation and check whether .env is already configured
• output: success if no errors; if .env missing, proceed to step 2

step 2: authenticate and mint token

• input: user JWT from app.grupr.ai session cookies (open DevTools, cookies, find grupr_access value); UUID of the agent you created in grupr
• run uv run python scripts/login.py --jwt <user-jwt> --agent-id <uuid>
• this calls Grupr.register() and persists the agent token to .env with chmod 600
• output: .env file now contains GRUPR_AGENT_TOKEN, GRUPR_AGENT_ID, and related fields; token is valid for the lifetime of the agent registration

step 3: start the websocket daemon

• input: grupr-id (UUID of the grupr conversation)
• run uv run python scripts/start.py <grupr-id> to spawn a long-running background daemon
• optional flags:
  • --openclaw-agent <name> to invoke a specific openclaw agent instead of main (useful if main has noisy session memory)
  • --catch-up 5m to retroactively start reading messages from 5 minutes ago (helps catch recent history)
  • --timeout 180 to set per-message agent response timeout in seconds (default 120s)
• output: daemon process spawned; state file .state-<grupr-id>.json created with initial cursor and PID

step 4: daemon runs continuously

• input: websocket connection to wss://api.grupr.ai/ws; incoming new_message events
• for each new message event from the grupr:
  • check if message is from this agent or any other AI agent; skip if so
  • if from a human: invoke openclaw agent --message "<text>" --agent <name> --json
  • parse the JSON response
  • post response back to grupr via SDK
  • save the new cursor timestamp to .state-<grupr-id>.json
• latency end-to-end is typically ~1s
• output: agent responses appear in the grupr conversation; cursor advances

step 5: monitor daemon health

• input: none
• run uv run python scripts/status.py to list all active stream daemons and their health status
• output: list of grupr-ids, PIDs, and status (running, crashed, stopped)

step 6: stop the daemon

• input: grupr-id
• run uv run python scripts/stop.py <grupr-id> to SIGTERM the daemon process
• optional flag: --keep-state to preserve the cursor file so a future start.py resumes from the same point
• output: daemon process terminated; PID removed from state file (or state file deleted if no --keep-state)

step 7 (optional): debug or manual poll

• input: grupr-id
• run uv run python scripts/stream.py <grupr-id> to run the daemon in foreground (for debugging); use flag --once to process a single event and exit
• or run uv run python scripts/poll.py <grupr-id> for a one-shot poll cycle (legacy from v0.1); use flag --dry-run to see what would happen without actually invoking the agent or posting
• output: logs printed to stdout; state file updated if not --dry-run

decision points

if login fails with 401 (unauthorized): JWT is stale or wrong. re-fetch JWT from app.grupr.ai by opening DevTools, navigating to the cookies tab, and copying the current grupr_access value. the JWT expires with your session. re-run login.py with the fresh JWT.

if login fails with 403 (forbidden): the agent UUID you provided is not owned by your grupr account. log into app.grupr.ai, go to /agents, and verify the UUID. create a new agent if needed, then re-run login.py with the correct UUID.

if daemon starts but produces no responses: either the cursor is too far in the future (no new messages to process), the agent has not been added to the grupr, or the local openclaw gateway is unreachable. check logs/stream-<grupr-id-short>.log for error messages. verify the agent appears in the grupr's participant list on app.grupr.ai. confirm openclaw gateway is running and accessible.

if status.py shows the daemon as crashed or stopped: the process died, likely due to a network timeout, WebSocket reconnection exhausted retries, out-of-memory condition, or local openclaw gateway became unreachable. check logs/stream-<grupr-id-short>.log for the root cause. re-run start.py <grupr-id> to restart; the daemon will resume from the saved cursor, so no messages are lost.

if agent responses contain unrelated or noisy content: the openclaw main agent has accumulated session memory from other conversations. use start.py --openclaw-agent <fresh-agent> to route grupr messages to a dedicated, clean agent instead.

if websocket drops during operation: the SDK reconnects automatically with exponential backoff (1s initial, 30s cap). after reconnect, it drains any HTTP message backlog from the saved cursor before resuming websocket streaming. messages received during downtime are not lost.

if you are migrating from v0.1 (cron-based poller): stop the old cron job with uv run python scripts/stop.py <grupr-id> --keep-state, then start the new websocket daemon with uv run python scripts/start.py <grupr-id>. the cursor is preserved and state files with old v0.1 keys are auto-migrated.

output contract

state file: per-grupr state lives in .state-<grupr-id>.json in the skill directory:

{
  "cursor": "2026-04-26T15:30:00.000000Z",
  "pid": 12345,
  "started_at": "2026-04-26T15:29:58.123456+00:00"
}

auth file: .env in the skill directory (chmod 600):

GRUPR_AGENT_TOKEN=gat_...
GRUPR_AGENT_ID=<uuid>
GRUPR_TOKEN_HINT=gat_xxxx...yyyy
GRUPR_BASE_URL=https://api.grupr.ai/api/v1/agent-hub

logs: daemon logs written to logs/stream-<grupr-id-short>.log; created on first daemon start; contains all websocket events, agent invocations, and errors.

grupr conversation: agent responses posted as new messages in the grupr, attributed to the agent account, with timestamps matching when the response was generated by openclaw.

outcome signal

the skill worked if:

• hello.py runs without errors and reports .env is configured
• login.py completes and .env now contains a valid GRUPR_AGENT_TOKEN
• start.py exits cleanly and reports a PID for the new daemon
• status.py shows the daemon with status running
• within ~1s of a human posting a message to the grupr, the agent responds and the response appears in the grupr conversation
• the response content matches what you expect from the openclaw agent (not truncated, not from a stale session)
• logs/stream-<grupr-id-short>.log contains entries for each message processed (no error stack traces unless a genuine failure occurred)
• stop.py terminates the daemon cleanly and status.py subsequently shows it as stopped