{"record":{"id":"a843e1d487bd1401","repo":"slopus/happy","slug":"openclaw-gateway-not-found-either-install-an","errorCode":null,"errorMessage":"OpenClaw gateway not found. Either:\n  - Install and run openclaw locally\n  - Set OPENCLAW_GATEWAY_URL env var\n  - Pass --gateway-url","messagePattern":"OpenClaw gateway not found\\. Either:\n  - Install and run openclaw locally\n  - Set OPENCLAW_GATEWAY_URL env var\n  - Pass --gateway-url","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/happy-cli/src/openclaw/runOpenClaw.ts","lineNumber":114,"sourceCode":" */\nfunction queryGatewayToken(): string | null {\n  try {\n    const raw = JSON.parse(readFileSync(resolveConfigPath(), 'utf-8'));\n    const token = raw?.gateway?.auth?.token;\n    return typeof token === 'string' ? token : null;\n  } catch {\n    return null;\n  }\n}\n\nfunction resolveGatewayConfig(opts: RunOpenClawOptions): OpenClawGatewayConfig {\n  // Priority: CLI args > env vars > openclaw binary auto-detection\n  const url = opts.gatewayUrl\n    ?? process.env.OPENCLAW_GATEWAY_URL\n    ?? queryGatewayUrl();\n\n  if (!url) {\n    throw new Error(\n      'OpenClaw gateway not found. Either:\\n'\n      + '  - Install and run openclaw locally\\n'\n      + '  - Set OPENCLAW_GATEWAY_URL env var\\n'\n      + '  - Pass --gateway-url',\n    );\n  }\n\n  const token = opts.gatewayToken\n    ?? process.env.OPENCLAW_GATEWAY_TOKEN\n    ?? queryGatewayToken()\n    ?? undefined;\n\n  return {\n    url,\n    token,\n    password: opts.gatewayPassword ?? process.env.OPENCLAW_GATEWAY_PASSWORD ?? undefined,\n  };\n}","sourceCodeStart":96,"sourceCodeEnd":132,"githubUrl":"https://github.com/slopus/happy/blob/b824cd0a4681d41af631a8e422a813873e4455b0/packages/happy-cli/src/openclaw/runOpenClaw.ts#L96-L132","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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`)"],"exampleFix":"// before\nhappy openclaw\n// after\nOPENCLAW_GATEWAY_URL=ws://localhost:3000 happy openclaw\n// or\nhappy --gateway-url ws://localhost:3000 openclaw","handlingStrategy":"validation","validationCode":"const url = opts.gatewayUrl\n  ?? process.env.OPENCLAW_GATEWAY_URL\n  ?? detectLocalGatewayUrl();\nif (!url) {\n  console.error('Set OPENCLAW_GATEWAY_URL or pass --gateway-url before continuing');\n  process.exit(1);\n}","typeGuard":null,"tryCatchPattern":"try {\n  await runOpenClaw(opts);\n} catch (err) {\n  if (err.message.startsWith('OpenClaw gateway not found')) {\n    console.error(err.message); // shows all three resolution paths\n    process.exit(1);\n  }\n  throw err;\n}","preventionTips":["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"],"tags":["openclaw","configuration","gateway","env-var"],"backgroundTag":"missing-configuration","analyzedSha":"b824cd0a4681d41af631a8e422a813873e4455b0","analyzedAt":"2026-08-31T23:12:36.205Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T05:18:18.240Z"}