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

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.

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)

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.