| name | rails-agent-gateway |
| description | 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. |
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
- Confirm required env vars are available.
- Validate endpoint connectivity with a non-destructive briefing fetch.
- Pull briefing data for a selected period/resources.
- Summarize result counts, aggregations, and latest records.
- 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:
- Path secret — embedded in the URL (
/agent-gateway/<secret>/briefing). Wrong value returns 404 (endpoint appears nonexistent).
- 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
| Param | Description | Example |
|---|
period | Time window: 1d, 7d, 30d, 90d, 1y, all | ?period=30d |
resources | Comma-separated resource keys | ?resources=users,orders |
latest | Override 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:
- Confirm helper script exists and is executable.
- Confirm endpoint URL includes
/agent-gateway/<secret>/briefing.
- Confirm bearer token is current (
AGENT_GATEWAY_TOKEN).
- Check two-layer auth: 404 = bad path secret, 401 = bad bearer token.
- Retry with minimal scope (
--resources users --period 7d --latest 1).
- Report exact error class (auth/network/format), then propose a fix.
For reusable command snippets and output interpretation, read
references/usage.md.
