OpenClaw gateway not found. Either: - Install and run…

Error message

OpenClaw gateway not found. Either:
  - Install and run openclaw locally
  - Set OPENCLAW_GATEWAY_URL env var
  - Pass --gateway-url

What it means

resolveGatewayConfig() determines the OpenClaw gateway URL with priority: CLI flag --gateway-url, then OPENCLAW_GATEWAY_URL env var, then auto-detection from a locally installed openclaw binary. If all three yield nothing, happy cannot reach any gateway and throws this aggregated message listing every resolution path.

Solutions

Install and start openclaw locally so auto-detection can find it
Export OPENCLAW_GATEWAY_URL to the gateway's address (e.g. `export OPENCLAW_GATEWAY_URL=ws://localhost:port`)
Pass the URL explicitly: `happy --gateway-url ws://... openclaw`
Verify the env var is visible in the actual process environment (`printenv OPENCLAW_GATEWAY_URL`)

Example fix

// before
happy openclaw
// after
OPENCLAW_GATEWAY_URL=ws://localhost:3000 happy openclaw
// or
happy --gateway-url ws://localhost:3000 openclaw

Defensive patterns

Strategy: validation

Validate before calling

const url = opts.gatewayUrl
  ?? process.env.OPENCLAW_GATEWAY_URL
  ?? detectLocalGatewayUrl();
if (!url) {
  console.error('Set OPENCLAW_GATEWAY_URL or pass --gateway-url before continuing');
  process.exit(1);
}

Try / catch

try {
  await runOpenClaw(opts);
} catch (err) {
  if (err.message.startsWith('OpenClaw gateway not found')) {
    console.error(err.message); // shows all three resolution paths
    process.exit(1);
  }
  throw err;
}

Prevention

Set OPENCLAW_GATEWAY_URL in the environment that actually launches happy (check IDE/CI env)
Or always pass --gateway-url explicitly in scripts
Install openclaw locally so auto-detection works as a fallback

When it happens

Trigger: Running runOpenClaw with no --gateway-url flag, no OPENCLAW_GATEWAY_URL environment variable set, and queryGatewayUrl() finding no running local openclaw instance to auto-detect.

Common situations: Fresh machine where openclaw is not installed; openclaw installed but not running; env var defined in a shell profile but not in the environment running happy (CI, IDE launcher); typo in the env var name.

Related errors

AI-assisted analysis of slopus/happy@b824cd0a46 (2026-08-31). Data as JSON: /api/errors/a843e1d487bd1401. Report an issue: GitHub.

Appendix: source

Thrown at packages/happy-cli/src/openclaw/runOpenClaw.ts:114

 */
function queryGatewayToken(): string | null {
  try {
    const raw = JSON.parse(readFileSync(resolveConfigPath(), 'utf-8'));
    const token = raw?.gateway?.auth?.token;
    return typeof token === 'string' ? token : null;
  } catch {
    return null;
  }
}

function resolveGatewayConfig(opts: RunOpenClawOptions): OpenClawGatewayConfig {
  // Priority: CLI args > env vars > openclaw binary auto-detection
  const url = opts.gatewayUrl
    ?? process.env.OPENCLAW_GATEWAY_URL
    ?? queryGatewayUrl();

  if (!url) {
    throw new Error(
      'OpenClaw gateway not found. Either:\n'
      + '  - Install and run openclaw locally\n'
      + '  - Set OPENCLAW_GATEWAY_URL env var\n'
      + '  - Pass --gateway-url',
    );
  }

  const token = opts.gatewayToken
    ?? process.env.OPENCLAW_GATEWAY_TOKEN
    ?? queryGatewayToken()
    ?? undefined;

  return {
    url,
    token,
    password: opts.gatewayPassword ?? process.env.OPENCLAW_GATEWAY_PASSWORD ?? undefined,
  };
}

View on GitHub (pinned to b824cd0a46)