ClawHub

Ruby On Rails Gateway

Workflows

Configure and operate a Ruby On Rails Agent Gateway integration from the OpenClaw side for briefing pull workflows. Use when setting up OpenClaw to read app data through a Rails `/agent-gateway/:secret/briefing` endpoint, validating tokens/URL env vars, testing connectivity, and generating summary pulls for reports or automations.

Install

openclaw skills install ruby-on-rails-gateway

Rails Agent Gateway

This skill works in tandem with the agent_gateway Ruby gem, a mountable Rails engine that must be installed and configured on the Rails side (gem "agent_gateway" + initializer). This skill handles the OpenClaw-side setup and usage for pulling data from that endpoint.

Quick Workflow

  1. Confirm required env vars are available.
  2. Validate endpoint connectivity with a non-destructive briefing fetch.
  3. Pull briefing data for a selected period/resources.
  4. Summarize result counts, aggregations, and latest records.
  5. If requested, prepare commands suitable for cron/automation.

Required Environment

Require these variables before any live fetch:

  • AGENT_GATEWAY_TOKEN (bearer token — set in the Rails app initializer as c.auth_token)
  • AGENT_GATEWAY_SECRET (path secret — set as c.path_secret)

The OpenClaw helper script may also read:

  • RAILS_GATEWAY_URL (full /briefing URL, e.g. https://myapp.com/agent-gateway/<secret>/briefing)
  • RAILS_GATEWAY_TOKEN (maps to bearer token)

If env vars are missing, stop and show the exact export commands needed.

Authentication

The gem uses two-layer auth:

  1. Path secret — embedded in the URL (/agent-gateway/<secret>/briefing). Wrong value returns 404 (endpoint appears nonexistent).
  2. Bearer token — sent via Authorization header. Wrong/missing value returns 401.

Both are compared using timing-safe secure_compare.

Command Patterns

Direct curl

curl -H "Authorization: Bearer $AGENT_GATEWAY_TOKEN" \
  "https://myapp.com/agent-gateway/$AGENT_GATEWAY_SECRET/briefing?period=7d&resources=users,orders"

Helper script

Prefer the local helper script when present:

/home/node/.openclaw/workspace/scripts/rails-gateway-briefing --period 7d

With explicit env vars:

RAILS_GATEWAY_URL='https://myapp.com/agent-gateway/<secret>/briefing' \
RAILS_GATEWAY_TOKEN='***' \
/home/node/.openclaw/workspace/scripts/rails-gateway-briefing --period 7d --resources users,orders

Query Parameters

ParamDescriptionExample
periodTime window: 1d, 7d, 30d, 90d, 1y, all?period=30d
resourcesComma-separated resource keys?resources=users,orders
latestOverride latest count for all resources?latest=10

Resource-Scoped Pulls

Resources are configured per-app via the gem's DSL. Common examples:

  • --resources users
  • --resources orders

Use --latest N to cap detailed rows while keeping counts.

The gem DSL also supports aggregations (count, sum, avg) on numeric columns — these appear in the response alongside count and latest.

Safety Rules

  • Never print or echo live tokens in user-visible output.
  • Redact secrets in pasted commands.
  • Do not perform external write actions unless explicitly asked.
  • Keep pulls read-only (briefing endpoint usage only).

Troubleshooting

If calls fail:

  1. Confirm helper script exists and is executable.
  2. Confirm endpoint URL includes /agent-gateway/<secret>/briefing.
  3. Confirm bearer token is current (AGENT_GATEWAY_TOKEN).
  4. Check two-layer auth: 404 = bad path secret, 401 = bad bearer token.
  5. Retry with minimal scope (--resources users --period 7d --latest 1).
  6. Report exact error class (auth/network/format), then propose a fix.

For reusable command snippets and output interpretation, read references/usage.md.

More in Workflows