SynClaw logoSynClaw Docs
Sign inHome
OverviewHostingPublic WSSSelf-hostedModelFAQ
DocsHosting

Hosting Troubleshooting

Fast diagnosis for common auth, Convex, and OpenClaw/MCP issues.

Auth callback stays on provider domain

  • Verify provider callback URL matches expected route exactly.
  • Check local vs production host mismatch in provider settings.
  • Confirm app env vars are loaded in current runtime process.

What to compare exactly

Expected callback:
https://<convex-site>.convex.site/api/auth/callback/github
https://<convex-site>.convex.site/api/auth/callback/google

Check:
1) OAuth app callback URL
2) .env.local AUTH_GITHUB_ID / AUTH_GITHUB_SECRET / AUTH_GOOGLE_ID / AUTH_GOOGLE_SECRET
3) runtime restart after env edits

Convex errors like "No matching routes found"

  • Run bunx convex dev and confirm functions are ready.
  • Confirm correct deployment is set in local env.
  • Re-run local server after env changes to pick up values.

Recovery sequence

1) stop both dev processes
2) start convex: bunx convex dev
3) wait for "functions ready"
4) start app: bun run dev
5) retry login flow

OpenClaw session or MCP tool failures

  • Re-validate gateway URL/token/scopes in workspace settings.
  • Check MCP endpoint health and network access rules.
  • Run one minimal tool request to isolate schema/auth issues.
  • Confirm failure appears in activity logs with actionable details.

Minimal isolation test

- create one test agent
- run one deterministic tool call
- verify:
  a) session starts
  b) tool request logged
  c) tool response logged
  d) task status updates

Why "ws://" from "https://" fails

  • Browsers block insecure WebSocket (ws://) from secure pages.
  • Use wss:// for Public WSS setups.
  • If OpenClaw must stay private, use Private Connector (advanced).

Device approval passes but scopes still fail

  • Device approval and role/scope authorization are separate checks.
  • Rotate/re-issue scopes to include required operator scopes for your workflow.
  • Run Test again from Settings -> OpenClaw after scope updates.

Hardened endpoint but handshake still failing

  • Verify exact origin match in allowedOrigins.
  • Confirm token/password is valid for target workspace and role.
  • Confirm TLS cert chain and reverse-proxy upgrade headers are correct.
  • Re-run Settings test and inspect diagnostics output.

Older references in archived docs

  • Prioritize pages under /docs/hosting/* and /docs/self-hosted.
  • If a markdown file mentions legacy provider/payment flow, treat it as historical unless linked from the docs sidebar.
  • Use Public WSS + workspace-level OpenClaw settings as the current source of truth.

Escalation template for support/debug

Include all of the following:
- environment (local/staging/prod)
- exact failing URL
- exact timestamp
- workspace id
- user role
- screenshot/error text
- last successful action before failure