firewall-ai-gateway-debug
$
npx mdskill add vercel-labs/vercel-openclaw/firewall-ai-gateway-debugDiagnose Vercel AI Gateway failures and network policy issues.
- Resolves model call blocks, egress errors, and token refresh failures.
- Integrates with admin APIs for logs, preflight checks, and sandbox diagnostics.
- Analyzes policy drift, credential states, and transform rule configurations.
- Outputs structured evidence and critical split recommendations for resolution.
SKILL.md
.github/skills/firewall-ai-gateway-debugView on GitHub ↗
---
name: firewall-ai-gateway-debug
description: "Firewall and Vercel AI Gateway debugging for vercel-openclaw: network policy allowlists, OIDC token refresh, AI Gateway transform rules, firewall learning/enforcement, and sandbox.update networkPolicy calls. Use when model calls, egress, token refresh, or firewall policy application fails."
---
# Firewall AI Gateway Debug
Use this skill for model-call failures, egress blocks, network policy drift, or AI Gateway token refresh problems.
## Evidence First
Collect:
- `GET /api/admin/preflight` or launch verification preflight evidence.
- `GET /api/admin/logs` filtered for `firewall.`, `token.`, `gateway.`, `watchdog.`.
- `GET /api/admin/sandbox-diag`.
- Current firewall mode and learned/allowed domains from admin surfaces.
- Sanitized model-call or gateway error body. Do not print Authorization tokens.
## Critical Splits
- AI Gateway credential unavailable vs expired vs circuit-breaker-open.
- Static API key bypass vs OIDC token path.
- Firewall learning/allowlist issue vs model provider/API issue.
- `OPENAI_BASE_URL` inside sandbox is present, while Authorization is injected by network policy transform.
- Policy object shape changes when an AI Gateway token exists.
## Invariants
- AI Gateway token never enters sandbox files or env.
- `ai-gateway.vercel.sh` stays allowed even in enforcing mode.
- Token refresh applies `sandbox.update({ networkPolicy })`; it should not rewrite config files or restart the gateway.
- Public/admin display URLs must not expose deployment-protection bypass secrets.
## Fix Boundaries
- Primary: `src/server/firewall/{domains,policy,state}.ts`.
- Token path: `src/server/sandbox/lifecycle.ts`, `src/server/deploy-preflight.ts`.
- Public URLs: `src/server/public-url.ts`.
- Tests: firewall policy tests, token refresh tests, launch-verify/preflight tests.
- Docs: `docs/environment-variables.md`, `docs/deployment-protection.md`, `lat.md/sandbox-lifecycle.md`.
## Verification
```bash
node scripts/verify.mjs --steps=test,typecheck
lat check
```
For live incidents, prove a model call succeeds after the policy/token change and that no token value appears in logs, UI, or sandbox config.
More from vercel-labs/vercel-openclaw
- admin-ui-debugAdmin UI and operator surface debugging for vercel-openclaw: command shell design, admin actions, request core, status panels, launch verification UI, channel readiness UI, and local read-only production-data workflows. Use when the root admin UI, controls, visual state, or operator copy is wrong.
- auth-store-debugAuth and store debugging for vercel-openclaw: admin-secret mode, Sign in with Vercel, session cookies, CSRF, LOCAL_READ_ONLY, Redis vs memory store, keyspace namespacing, and metadata shape migrations. Use when login, route authorization, Redis persistence, or metadata state is suspect.
- channel-debug-coreChannel webhook triage for vercel-openclaw Slack/Telegram/Discord/WhatsApp issues: prove deployment state, collect admin readiness endpoints, build evidence-first handoff before fixes.
- channel-forward-parityWebhook route parity audit for channel delivery changes: ensure terminal paths log, record lastForward, classify failures, and refresh stale sandbox port URLs.
- cron-watchdog-debugCron and watchdog debugging for vercel-openclaw: Vercel Cron auth, persisted OpenClaw jobs, cron wake keys, token refresh, restore oracle, hot spare, and watchdog reports. Use when scheduled OpenClaw jobs fail to wake or run, watchdog status is wrong, cron persistence is suspect, or /api/cron/watchdog behavior changes.
- discord-deliveryDiscord channel specialist workflow: debug interaction webhooks, Ed25519 signatures, deferred replies, workflow forwarding to /discord-webhook, integration reconcile, and token expiry.
- gateway-proxy-debugGateway and proxy debugging for vercel-openclaw: /gateway routing, HTML injection, WebSocket rewrite, gateway-token handoff, waiting page, status heartbeat, sandbox port URL cache, and proxy auth. Use when the OpenClaw UI, WebSockets, gateway proxying, or waiting-page flow breaks.
- lat-md>-
- launch-verify-debugLaunch verification and remote smoke debugging for vercel-openclaw: preflight, queue ping, ensureRunning, chatCompletions, wakeFromSleep, restorePrepared, channelReadiness, NDJSON progress, and vclaw create readiness. Use when launch verification, vclaw create validation, or remote smoke checks fail.
- openclaw-bootstrap-debugOpenClaw bootstrap, bundle, config, and restore-asset debugging for vercel-openclaw: openclaw.bundle sidecars, plugin discovery, channel catalog, restart scripts, config hashes, dynamic resume files, and fast restore. Use when setup, gateway boot, plugin loading, or bundle-sidecar compatibility fails.