mobygate 0.7.3 → 0.8.0

package/CHANGELOG.md

@@ -4,6 +4,81 @@ All notable changes to mobygate are documented here. Format loosely follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); version numbers are
 [Semantic Versioning](https://semver.org/).
 
+## [0.8.0] — 2026-04-25
+
+Auto-wire third-party clients to use mobygate. The "find your client's
+config file → paste this JSON → restart" dance is replaced by
+`mobygate connect`.
+
+### Added
+
+- **`mobygate connect` CLI** — auto-detects supported clients on the
+  system, plans the minimal config edit to register mobygate as a
+  provider, and applies it atomically with a backup. Subcommands:
+  - `mobygate connect` — interactive, lists detected clients and asks
+    which to wire (default: all)
+  - `mobygate connect <id>` — wire one specific client
+  - `mobygate connect --all` — every detected client, no prompts
+  - `mobygate connect --dry-run` — show planned diff, don't write
+  - `mobygate connect --yes` — skip the per-client confirm prompt
+  - `mobygate connect --no-default` — register the provider but don't
+    change the client's active default model
+  - `mobygate disconnect <id>` — remove our entries cleanly
+- **Auto-wire prompt at the end of `mobygate init`** — after services
+  start, if any supported client is detected, init asks "wire them
+  up?" before printing Done. Skipped in `--yes` mode (we don't edit
+  third-party configs in non-interactive flows without explicit opt-in).
+- **Hermes connector** (`lib/connectors/hermes.js`) — registers the
+  `moby` provider in `~/.hermes/config.yaml`. Hermes only speaks the
+  OpenAI-compat wire format, so a single provider entry covers it.
+- **OpenClaw connector** (`lib/connectors/openclaw.js`) — registers
+  BOTH `moby` (OpenAI-compat) and `moby-native` (Anthropic-messages)
+  in `~/.openclaw/openclaw.json`. With `setDefault`, points OpenClaw's
+  main + default at `moby-native/claude-opus-4-7` — the wire format
+  that unlocks vision, native tool calls, and reasoning blocks.
+
+### Provider naming
+
+All registered entries use the `moby` prefix to be unmistakably from
+mobygate:
+- **`moby`** — OpenAI-compat surface (POST /v1/chat/completions)
+- **`moby-native`** — Anthropic-messages surface (POST /v1/messages)
+
+### Safety
+
+Every config write goes through `lib/connectors/safety.js`:
+- Timestamped backup at `<file>.mobygate-backup-<ISO>` before any write
+- Atomic write via temp file + rename
+- Read-back verification that the on-disk content matches what we
+  intended to write
+- Idempotent — running `connect` twice doesn't duplicate entries; we
+  detect existing moby entries by key and update vs append
+
+### Caveats
+
+- **YAML comments are not preserved.** Hermes config uses YAML, and
+  `js-yaml` parse-then-emit drops comments and blank lines. The
+  auto-backup catches this — the connector also warns on first
+  detection. Comment-preserving YAML is a v0.8.x candidate.
+- **Custom config locations not yet supported.** Connectors probe
+  `~/.hermes/` and `~/.openclaw/`. If you've installed a client to a
+  non-standard path, you'd still need to wire it manually, or set
+  `HERMES_HOME` / `OPENCLAW_HOME` env vars (which the connectors
+  honor).
+- **No `verify()` step yet.** The connector contract has slots for it,
+  but v0.8.0 doesn't fire a real test request through the wired
+  client. Verification is on the v0.8.x roadmap.
+
+### v0.8.x backlog (deferred)
+
+- More connectors (pi-agent, Goose, Aider, Cursor — anything that
+  takes a custom OpenAI-compat baseURL)
+- `verify()` step that exercises the new provider end-to-end
+- Comment-preserving YAML for Hermes
+- Auxiliary-client routing helpers (pin Hermes vision/compression to
+  Sonnet/Haiku via mobygate to save Opus quota)
+- `mobygate doctor` extended to check connection health per client
+
 ## [0.7.3] — 2026-04-25
 
 Hotfix bundle from a thorough security + bugs + ops audit. Six items.

package/bin/mobygate.js

@@ -39,6 +39,13 @@ import {
 } from '../lib/platform.js';
 import { getAuthStatus, forceRefresh } from '../scripts/auth-helper.js';
 import { banner, compactBanner } from '../lib/ascii.js';
+import {
+  CONNECTORS,
+  detectAll as detectAllConnectors,
+  getConnector,
+  DEFAULT_BASE_URL as MOBY_BASE_URL,
+  DEFAULT_API_KEY as MOBY_API_KEY,
+} from '../lib/connectors/index.js';
 
 const __filename = fileURLToPath(import.meta.url);
 const REPO_ROOT = resolve(dirname(__filename), '..');
@@ -280,6 +287,54 @@ async function cmdInit() {
     info('Start the server manually (see instructions above) then run `mobygate status`.');
   }
 
+  // ---- Auto-wire detected clients (Hermes, OpenClaw, etc.) ----
+  // Skip in non-interactive mode (--yes) — those flows shouldn't surprise
+  // the user by editing third-party config files. They can still run
+  // `mobygate connect --all --yes` explicitly afterward.
+  if (!nonInteractive) {
+    try {
+      const detected = await detectAllConnectors();
+      const present = detected.filter((d) => d.detection !== null);
+      if (present.length > 0) {
+        section('Detected clients');
+        for (const { connector, detection } of present) {
+          print(`  ${c.green('✓')} ${c.bold(connector.displayName)} ${c.dim('at ' + detection.configPath)}`);
+        }
+        print('');
+        const wire = await confirm('Auto-wire these to use mobygate?', true);
+        if (wire) {
+          for (const { connector } of present) {
+            try {
+              const plan = await connector.plan({
+                baseUrl: MOBY_BASE_URL,
+                apiKey: MOBY_API_KEY,
+                setDefault: true,
+              });
+              if (plan.skip) { warn(`${connector.displayName}: ${plan.reason}`); continue; }
+              for (const w of plan.warnings || []) warn(w);
+              const result = await connector.apply(plan);
+              if (result.applied) {
+                ok(`Wired ${connector.displayName} → ${result.configPath}`);
+                if (result.backupPath) print(c.dim(`  backup: ${result.backupPath}`));
+              } else {
+                warn(`${connector.displayName}: ${result.reason}`);
+              }
+            } catch (e) {
+              warn(`${connector.displayName}: ${e.message}`);
+            }
+          }
+          print('');
+          info('Restart the wired clients so they pick up the new provider.');
+        } else {
+          print(c.dim('Skipped — run `mobygate connect` later to wire them on demand.'));
+        }
+      }
+    } catch (e) {
+      // Detection failures should never block init.
+      warn(`Connector detection failed: ${e.message}`);
+    }
+  }
+
   section('Done');
   print(`Dashboard: ${c.cyan(`http://localhost:${port}`)}`);
   print(`Configure: ${c.cyan(CONFIG_PATH)}`);
@@ -659,22 +714,171 @@ async function cmdUpdate() {
   info(`Tip: if the install-layout changed (new service file, new paths), run \`mobygate init\` to re-install the service definitions.`);
 }
 
+// ---------------------------------------------------------------------------
+// `mobygate connect` — auto-wire third-party clients to use mobygate.
+//
+// Detects supported clients (Hermes, OpenClaw) on the system, plans the
+// minimal config edit to register `moby` (OpenAI-compat) and/or
+// `moby-native` (Anthropic-messages) as a provider, and applies it
+// atomically with a backup. Idempotent — running twice doesn't duplicate
+// entries; running with --dry-run shows the planned diff without writing.
+//
+// Per-client adapters live in lib/connectors/<id>.js and follow a
+// uniform contract (detect/inspect/plan/apply/disconnect). Add a new
+// connector by writing the adapter and registering it in
+// lib/connectors/index.js#CONNECTORS.
+// ---------------------------------------------------------------------------
+
+function parseConnectArgs() {
+  // process.argv is [node, mobygate, connect, ...rest]
+  const rest = process.argv.slice(3);
+  const flags = new Set(rest.filter((a) => a.startsWith('-')));
+  const positional = rest.filter((a) => !a.startsWith('-'));
+  return {
+    targetId: positional[0] || null,
+    dryRun: flags.has('--dry-run'),
+    yes: flags.has('--yes') || flags.has('-y'),
+    all: flags.has('--all'),
+    noDefault: flags.has('--no-default'),
+  };
+}
+
+async function cmdConnect() {
+  const { targetId, dryRun, yes, all, noDefault } = parseConnectArgs();
+  section('mobygate connect');
+  if (dryRun) info('Dry-run mode — no files will be written.');
+
+  const detected = await detectAllConnectors();
+  const present = detected.filter((d) => d.detection !== null);
+
+  if (present.length === 0) {
+    print(c.dim('No supported clients detected. Currently we recognize:'));
+    for (const conn of CONNECTORS) {
+      print(c.dim(`  - ${conn.displayName}`));
+    }
+    print(c.dim('Install one and re-run `mobygate connect`.'));
+    return;
+  }
+
+  // Decide which clients to act on.
+  let targets;
+  if (targetId) {
+    const match = present.find((p) => p.connector.id === targetId.toLowerCase());
+    if (!match) return die(`Client "${targetId}" not detected. Detected: ${present.map((p) => p.connector.id).join(', ')}`);
+    targets = [match];
+  } else if (all || yes) {
+    targets = present;
+  } else {
+    print('');
+    print('Detected clients:');
+    for (const { connector, detection } of present) {
+      print(`  ${c.green('✓')} ${c.bold(connector.displayName)} ${c.dim('at ' + detection.configPath)}`);
+    }
+    print('');
+    const which = await prompt('Wire all? (Y / n / comma-separated ids)', 'Y');
+    const trimmed = which.trim().toLowerCase();
+    if (trimmed === 'n' || trimmed === 'no') return ok('Aborted — nothing changed.');
+    if (!trimmed || trimmed === 'y' || trimmed === 'yes') {
+      targets = present;
+    } else {
+      const ids = trimmed.split(',').map((s) => s.trim()).filter(Boolean);
+      targets = present.filter((p) => ids.includes(p.connector.id));
+      if (targets.length === 0) return die(`No detected clients matched "${which}".`);
+    }
+  }
+
+  // Plan + (maybe) apply per target.
+  for (const { connector } of targets) {
+    print('');
+    section(connector.displayName);
+    let plan;
+    try {
+      plan = await connector.plan({
+        baseUrl: MOBY_BASE_URL,
+        apiKey: MOBY_API_KEY,
+        setDefault: !noDefault,
+      });
+    } catch (e) {
+      warn(`plan failed: ${e.message}`);
+      continue;
+    }
+    if (plan.skip) { warn(plan.reason); continue; }
+
+    print(c.dim(`config: ${plan.configPath}`));
+    print('Changes:');
+    for (const line of plan.summary) {
+      const colored = line.startsWith('+') ? c.green(line) : line.startsWith('-') ? c.red(line) : c.cyan(line);
+      print('  ' + colored);
+    }
+    for (const w of plan.warnings || []) warn(w);
+
+    if (dryRun) { info('Dry-run — skipping write.'); continue; }
+
+    if (!yes) {
+      const ok2 = await confirm('Apply this change?', true);
+      if (!ok2) { warn('Skipped.'); continue; }
+    }
+
+    try {
+      const result = await connector.apply(plan);
+      if (result.applied) {
+        ok(`Wrote ${result.bytesWritten} bytes → ${result.configPath}`);
+        if (result.backupPath) print(c.dim(`  backup: ${result.backupPath}`));
+        info(`Restart ${connector.displayName} so it picks up the new provider.`);
+      } else {
+        warn(`Skipped: ${result.reason}`);
+      }
+    } catch (e) {
+      die(`apply failed: ${e.message}`);
+    }
+  }
+}
+
+async function cmdDisconnect() {
+  const targetId = process.argv[3];
+  if (!targetId) return die('Usage: mobygate disconnect <client-id>\nKnown ids: ' + CONNECTORS.map((c) => c.id).join(', '));
+  const conn = getConnector(targetId.toLowerCase());
+  if (!conn) return die(`No connector for "${targetId}". Known: ${CONNECTORS.map((c) => c.id).join(', ')}`);
+  section(`mobygate disconnect ${conn.displayName}`);
+  let result;
+  try {
+    result = await conn.disconnect();
+  } catch (e) {
+    return die(`disconnect failed: ${e.message}`);
+  }
+  if (result.applied) {
+    ok(`Removed moby entries from ${conn.displayName}`);
+    if (result.backupPath) print(c.dim(`  backup: ${result.backupPath}`));
+    if (result.note) info(result.note);
+    info(`Restart ${conn.displayName} so the change takes effect.`);
+  } else {
+    warn(result.reason);
+  }
+}
+
 function usage() {
   print(`mobygate — OpenAI → Claude Max local gateway
 
 Usage:
-  mobygate init       Interactive setup (add --yes to skip prompts,
-                      --no-browser to not auto-open the dashboard)
-  mobygate update     Upgrade to the latest version + restart service
-  mobygate doctor     Diagnose version mismatches, zombie services, port conflicts
-  mobygate start      Start the proxy service
-  mobygate stop       Stop the proxy service
-  mobygate restart    Stop + start
-  mobygate status     Show service + auth + /health state
-  mobygate logs       Tail the server log
-  mobygate auth       Show auth status + run a refresh probe
-  mobygate uninstall  Remove installed services
-  mobygate version    Print version + install mode + path
+  mobygate init        Interactive setup (add --yes to skip prompts,
+                       --no-browser to not auto-open the dashboard)
+  mobygate update      Upgrade to the latest version + restart service
+  mobygate doctor      Diagnose version mismatches, zombie services, port conflicts
+  mobygate start       Start the proxy service
+  mobygate stop        Stop the proxy service
+  mobygate restart     Stop + start
+  mobygate status      Show service + auth + /health state
+  mobygate logs        Tail the server log
+  mobygate auth        Show auth status + run a refresh probe
+  mobygate connect     Auto-wire detected clients (Hermes, OpenClaw) to
+                       use mobygate. Add: <id> for one client, --all for
+                       every detected, --dry-run to preview, --yes to
+                       skip prompts, --no-default to register without
+                       changing the active model.
+  mobygate disconnect  Remove moby entries from a client config.
+                       Usage: mobygate disconnect <client-id>
+  mobygate uninstall   Remove installed services
+  mobygate version     Print version + install mode + path
 
 Config: ~/.mobygate/config.yaml  (env vars override)
 Repo:   ${REPO_ROOT}
@@ -686,6 +890,8 @@ Repo:   ${REPO_ROOT}
 const cmd = process.argv[2];
 const COMMANDS = {
   init: cmdInit,
+  connect: cmdConnect,
+  disconnect: cmdDisconnect,
   update: cmdUpdate,
   upgrade: cmdUpdate,
   doctor: cmdDoctor,

package/lib/connectors/hermes.js

@@ -0,0 +1,186 @@
+/**
+ * Hermes connector.
+ *
+ * Hermes (the agent harness) lives at `~/.hermes/` with a `config.yaml`
+ * holding `model:` (the active model + provider) and `providers:` (a map
+ * of named providers keyed by id). Hermes only speaks the OpenAI-compat
+ * wire format, so we register a single provider entry: `moby`.
+ *
+ * Hermes references custom providers via `model.provider: custom:<id>`,
+ * so wiring "use mobygate as default" means setting:
+ *   model.default:  claude-opus-4-7
+ *   model.provider: custom:moby
+ *
+ * Caveats:
+ *   - We use js-yaml to parse + re-emit. js-yaml does NOT preserve
+ *     comments or blank lines. If the user has hand-edited their YAML
+ *     with comments, those will be lost in the rewritten file. The
+ *     auto-backup (safety.js) catches this — we also warn on detection.
+ *   - We only touch `providers.moby` (always) and `model.*` (only with
+ *     `setDefault: true`). Everything else in the YAML is preserved.
+ */
+
+import { readFileSync, existsSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+import yaml from 'js-yaml';
+import { backup, writeConfigSafe, diffSummary } from './safety.js';
+import { DEFAULT_BASE_URL, DEFAULT_API_KEY, PROVIDER_NAME_OPENAI } from './index.js';
+
+const HERMES_HOME = process.env.HERMES_HOME || join(homedir(), '.hermes');
+const HERMES_CONFIG = join(HERMES_HOME, 'config.yaml');
+
+function buildProviderEntry({ baseUrl, apiKey }) {
+  return {
+    api: `${baseUrl.replace(/\/$/, '')}/v1`,
+    name: 'Moby (Claude Max via mobygate)',
+    api_key: apiKey,
+    default_model: 'claude-opus-4-7',
+  };
+}
+
+export const hermesConnector = {
+  id: 'hermes',
+  displayName: 'Hermes',
+
+  async detect() {
+    if (!existsSync(HERMES_CONFIG)) return null;
+    let raw;
+    try {
+      raw = readFileSync(HERMES_CONFIG, 'utf8');
+    } catch (e) {
+      return null;
+    }
+    let parsed;
+    try {
+      parsed = yaml.load(raw);
+    } catch (e) {
+      // Config exists but is unparseable — surface that to the user via
+      // detection metadata rather than silently treating as not-installed.
+      return { configPath: HERMES_CONFIG, parseError: e.message };
+    }
+    return {
+      configPath: HERMES_CONFIG,
+      version: parsed?._config_version ?? null,
+      hasComments: /(^|\n)\s*#/.test(raw),
+      parsed,
+    };
+  },
+
+  async inspect() {
+    const det = await this.detect();
+    if (!det) return { installed: false };
+    if (det.parseError) return { installed: true, parseError: det.parseError };
+
+    const providers = det.parsed?.providers || {};
+    const existing = providers[PROVIDER_NAME_OPENAI];
+    const currentDefault = det.parsed?.model?.provider || null;
+    return {
+      installed: true,
+      configPath: det.configPath,
+      mobyProviderExists: !!existing,
+      mobyProviderMatches: existing
+        ? JSON.stringify(existing) === JSON.stringify(buildProviderEntry({
+            baseUrl: existing.api?.replace(/\/v1$/, '') || DEFAULT_BASE_URL,
+            apiKey: existing.api_key,
+          }))
+        : false,
+      currentDefaultProvider: currentDefault,
+      hasComments: det.hasComments,
+    };
+  },
+
+  async plan({ baseUrl = DEFAULT_BASE_URL, apiKey = DEFAULT_API_KEY, setDefault = true } = {}) {
+    const det = await this.detect();
+    if (!det) {
+      return { skip: true, reason: 'Hermes not detected (no ~/.hermes/config.yaml)' };
+    }
+    if (det.parseError) {
+      return { skip: true, reason: `Hermes config is unparseable: ${det.parseError}` };
+    }
+
+    const before = det.parsed || {};
+    const after = JSON.parse(JSON.stringify(before)); // deep clone
+
+    if (!after.providers) after.providers = {};
+    after.providers[PROVIDER_NAME_OPENAI] = buildProviderEntry({ baseUrl, apiKey });
+
+    if (setDefault) {
+      if (!after.model) after.model = {};
+      after.model.default = after.model.default || 'claude-opus-4-7';
+      after.model.provider = `custom:${PROVIDER_NAME_OPENAI}`;
+      after.model.context_length = after.model.context_length || 1000000;
+    }
+
+    const summary = diffSummary(
+      { providers: before.providers, model: before.model },
+      { providers: after.providers,  model: after.model },
+    );
+
+    return {
+      skip: false,
+      configPath: det.configPath,
+      before,
+      after,
+      summary,
+      warnings: det.hasComments
+        ? ['Your config.yaml contains comments. js-yaml will drop them on re-emit. ' +
+           'A timestamped backup is saved before the write — restore from it if needed.']
+        : [],
+    };
+  },
+
+  async apply(plan) {
+    if (plan.skip) return { applied: false, reason: plan.reason };
+    // js-yaml emit options: quote strings that need it, but use block
+    // style for maps (keeps it readable, matches Hermes's existing style).
+    const yamlOut = yaml.dump(plan.after, {
+      indent: 2,
+      lineWidth: 0,
+      noRefs: true,
+      sortKeys: false,
+    });
+    const result = writeConfigSafe(plan.configPath, yamlOut);
+    return {
+      applied: true,
+      configPath: result.path,
+      backupPath: result.backupPath,
+      bytesWritten: result.bytesWritten,
+    };
+  },
+
+  async disconnect() {
+    const det = await this.detect();
+    if (!det) return { applied: false, reason: 'Hermes not installed' };
+    if (det.parseError) return { applied: false, reason: `parse error: ${det.parseError}` };
+    const before = det.parsed || {};
+    const after = JSON.parse(JSON.stringify(before));
+    let changed = false;
+
+    if (after.providers && after.providers[PROVIDER_NAME_OPENAI]) {
+      delete after.providers[PROVIDER_NAME_OPENAI];
+      changed = true;
+    }
+    // Reset default provider if it was pointing at us.
+    if (after.model?.provider === `custom:${PROVIDER_NAME_OPENAI}`) {
+      // Don't pick a replacement — leave it for the user to re-set.
+      // Better than silently switching them to anthropic-direct (which
+      // would burn API tokens) or whatever else we'd guess.
+      after.model.provider = 'anthropic';
+      changed = true;
+    }
+
+    if (!changed) return { applied: false, reason: 'No moby provider entry in Hermes config' };
+
+    const yamlOut = yaml.dump(after, { indent: 2, lineWidth: 0, noRefs: true, sortKeys: false });
+    const result = writeConfigSafe(det.configPath, yamlOut);
+    return {
+      applied: true,
+      configPath: result.path,
+      backupPath: result.backupPath,
+      note: after.model?.provider === 'anthropic'
+        ? 'Reset model.provider to "anthropic" — verify ANTHROPIC_TOKEN is set if you intend to use direct API.'
+        : null,
+    };
+  },
+};

package/lib/connectors/index.js

@@ -0,0 +1,80 @@
+/**
+ * Client connector registry + orchestrator.
+ *
+ * Connectors auto-wire third-party clients (Hermes, OpenClaw, etc.) to
+ * use mobygate as their inference provider. This avoids the manual
+ * "find your client's config file → paste this JSON snippet → restart"
+ * dance for each client a user wants to connect.
+ *
+ * Each connector lives in `lib/connectors/<id>.js` and exports a
+ * uniform contract:
+ *
+ *   - id            — short stable identifier (e.g. 'hermes', 'openclaw')
+ *   - displayName   — human-readable name for prompts/logs
+ *   - detect()      — probe for the client; returns DetectionResult | null
+ *   - inspect()     — read current config; returns InspectionResult
+ *   - plan(opts)    — compute the diff to apply; returns Plan
+ *   - apply(plan)   — perform the modification atomically
+ *   - disconnect()  — remove our entries cleanly
+ *
+ * Branding: all provider entries we register use the `moby` prefix to
+ * make them visually identifiable. Two flavors:
+ *   - `moby`        — OpenAI-compat surface (POST /v1/chat/completions)
+ *   - `moby-native` — Anthropic-messages surface (POST /v1/messages)
+ *
+ * Clients that only handle one wire format get whichever fits; clients
+ * that handle both get both registered, with `moby-native` as the
+ * preferred default.
+ */
+
+import { hermesConnector } from './hermes.js';
+import { openclawConnector } from './openclaw.js';
+
+// Public API for any caller that wants to know where mobygate is reachable.
+// Defaults match server.js's defaults; init can override via opts.
+export const DEFAULT_BASE_URL = 'http://127.0.0.1:3456';
+export const DEFAULT_API_KEY  = 'claude-max';
+
+// Branded provider names. Short, distinct, unmistakably from mobygate.
+export const PROVIDER_NAME_OPENAI    = 'moby';
+export const PROVIDER_NAME_ANTHROPIC = 'moby-native';
+
+/**
+ * All registered connectors, in display order. Add new ones here.
+ * v0.8.0 ships with hermes + openclaw; pi-agent and others are on the
+ * v0.8.x backlog.
+ */
+export const CONNECTORS = [
+  hermesConnector,
+  openclawConnector,
+];
+
+/**
+ * Run detection across every registered connector. Returns an array of
+ * { connector, detection } where detection is the connector's
+ * DetectionResult (or null if not found). Connectors that throw are
+ * treated as "not detected" — we never let one broken adapter break
+ * the whole orchestrator.
+ */
+export async function detectAll() {
+  const out = [];
+  for (const c of CONNECTORS) {
+    let detection = null;
+    try {
+      detection = await c.detect();
+    } catch (e) {
+      // Detection should be silent on failure — the client may simply
+      // not be installed. Don't surface noise.
+      detection = null;
+    }
+    out.push({ connector: c, detection });
+  }
+  return out;
+}
+
+/**
+ * Convenience: get a connector by id, or null.
+ */
+export function getConnector(id) {
+  return CONNECTORS.find((c) => c.id === id) || null;
+}

package/lib/connectors/openclaw.js

@@ -0,0 +1,253 @@
+/**
+ * OpenClaw connector.
+ *
+ * OpenClaw is the Discord-bot agent harness. Its config lives at
+ * `~/.openclaw/openclaw.json` (canonical on Linux/Mac, mirrored as
+ * `%USERPROFILE%\.openclaw\openclaw.json` on Windows — verified
+ * against a real Geekom install).
+ *
+ * Unlike Hermes, OpenClaw understands BOTH wire formats — `openai-completions`
+ * (for legacy OpenAI-shape providers) and `anthropic-messages` (for
+ * Anthropic-native providers, which unlocks vision + native tools +
+ * thinking blocks). So we register both surfaces:
+ *   - moby         (api: openai-completions  → /v1/chat/completions)
+ *   - moby-native  (api: anthropic-messages  → /v1/messages)
+ *
+ * `moby-native` is set as the main + default model when setDefault is
+ * true — that's the wire format that gives OpenClaw the full feature
+ * set. `moby` stays available as fallback / OpenAI-compat clients.
+ *
+ * Config schema (inferred from the user's Geekom config):
+ *   {
+ *     "models": {
+ *       "main":     "<provider>/<model-id>",
+ *       "default":  "<provider>/<model-id>",
+ *       "providers": {
+ *         "<provider-id>": {
+ *           "baseUrl": "...",
+ *           "apiKey":  "...",
+ *           "api":     "openai-completions" | "anthropic-messages",
+ *           "models":  [ { id, name, contextWindow, maxTokens, input, reasoning, cost }, ... ]
+ *         }
+ *       }
+ *     }
+ *   }
+ */
+
+import { readFileSync, existsSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+import { writeConfigSafe, diffSummary } from './safety.js';
+import {
+  DEFAULT_BASE_URL,
+  DEFAULT_API_KEY,
+  PROVIDER_NAME_OPENAI,
+  PROVIDER_NAME_ANTHROPIC,
+} from './index.js';
+
+const OPENCLAW_HOME = process.env.OPENCLAW_HOME || join(homedir(), '.openclaw');
+const OPENCLAW_CONFIG = join(OPENCLAW_HOME, 'openclaw.json');
+
+// Probe order — first match wins. Lets us support installs that put the
+// config somewhere other than ~/.openclaw/.
+const CONFIG_PROBES = [
+  OPENCLAW_CONFIG,
+  // Add other plausible paths here as they're discovered. Empty list is
+  // fine for v0.8.0 — every install we've seen uses ~/.openclaw/.
+];
+
+const MODELS_OPENAI_SURFACE = [
+  { id: 'claude-opus-4-7',   name: 'Claude Opus 4.7 (Max via Moby)',   contextWindow: 1000000, maxTokens: 32768, input: ['text'],          reasoning: false, cost: { input: 0, output: 0 } },
+  { id: 'claude-opus-4-6',   name: 'Claude Opus 4.6 (Max via Moby)',   contextWindow: 200000,  maxTokens: 16384, input: ['text'],          reasoning: false, cost: { input: 0, output: 0 } },
+  { id: 'claude-sonnet-4-6', name: 'Claude Sonnet 4.6 (Max via Moby)', contextWindow: 200000,  maxTokens: 16384, input: ['text'],          reasoning: false, cost: { input: 0, output: 0 } },
+  { id: 'claude-haiku-4-5',  name: 'Claude Haiku 4.5 (Max via Moby)',  contextWindow: 200000,  maxTokens: 16384, input: ['text'],          reasoning: false, cost: { input: 0, output: 0 } },
+];
+
+// Native surface declares text+image input and reasoning capability so
+// OpenClaw will send vision content and surface thinking blocks.
+const MODELS_NATIVE_SURFACE = [
+  { id: 'claude-opus-4-7',   name: 'Claude Opus 4.7 (Max, native)',   contextWindow: 1000000, maxTokens: 32768, input: ['text', 'image'], reasoning: true,  cost: { input: 0, output: 0 } },
+  { id: 'claude-opus-4-6',   name: 'Claude Opus 4.6 (Max, native)',   contextWindow: 200000,  maxTokens: 16384, input: ['text', 'image'], reasoning: true,  cost: { input: 0, output: 0 } },
+  { id: 'claude-sonnet-4-6', name: 'Claude Sonnet 4.6 (Max, native)', contextWindow: 200000,  maxTokens: 16384, input: ['text', 'image'], reasoning: true,  cost: { input: 0, output: 0 } },
+  { id: 'claude-haiku-4-5',  name: 'Claude Haiku 4.5 (Max, native)',  contextWindow: 200000,  maxTokens: 16384, input: ['text', 'image'], reasoning: true,  cost: { input: 0, output: 0 } },
+];
+
+function buildOpenAIProvider({ baseUrl, apiKey }) {
+  return {
+    baseUrl,
+    apiKey,
+    api: 'openai-completions',
+    models: MODELS_OPENAI_SURFACE,
+  };
+}
+
+function buildNativeProvider({ baseUrl, apiKey }) {
+  return {
+    baseUrl,
+    apiKey,
+    api: 'anthropic-messages',
+    models: MODELS_NATIVE_SURFACE,
+  };
+}
+
+function findConfigPath() {
+  for (const p of CONFIG_PROBES) {
+    if (existsSync(p)) return p;
+  }
+  return null;
+}
+
+function isMobyDefaultPointer(s) {
+  if (typeof s !== 'string') return false;
+  return s.startsWith(`${PROVIDER_NAME_OPENAI}/`) || s.startsWith(`${PROVIDER_NAME_ANTHROPIC}/`);
+}
+
+export const openclawConnector = {
+  id: 'openclaw',
+  displayName: 'OpenClaw',
+
+  async detect() {
+    const configPath = findConfigPath();
+    if (!configPath) return null;
+    let raw;
+    try {
+      raw = readFileSync(configPath, 'utf8');
+    } catch (e) {
+      return null;
+    }
+    let parsed;
+    try {
+      parsed = JSON.parse(raw);
+    } catch (e) {
+      return { configPath, parseError: e.message };
+    }
+    return { configPath, parsed };
+  },
+
+  async inspect() {
+    const det = await this.detect();
+    if (!det) return { installed: false };
+    if (det.parseError) return { installed: true, parseError: det.parseError };
+
+    const providers = det.parsed?.models?.providers || {};
+    return {
+      installed: true,
+      configPath: det.configPath,
+      mobyProviderExists: !!providers[PROVIDER_NAME_OPENAI],
+      mobyNativeProviderExists: !!providers[PROVIDER_NAME_ANTHROPIC],
+      currentMain: det.parsed?.models?.main || null,
+      currentDefault: det.parsed?.models?.default || null,
+    };
+  },
+
+  async plan({
+    baseUrl = DEFAULT_BASE_URL,
+    apiKey = DEFAULT_API_KEY,
+    setDefault = true,
+    registerOpenAISurface = true,
+    registerNativeSurface = true,
+  } = {}) {
+    const det = await this.detect();
+    if (!det) {
+      return { skip: true, reason: 'OpenClaw not detected (no ~/.openclaw/openclaw.json)' };
+    }
+    if (det.parseError) {
+      return { skip: true, reason: `OpenClaw config is unparseable JSON: ${det.parseError}` };
+    }
+
+    const before = det.parsed || {};
+    const after = JSON.parse(JSON.stringify(before)); // deep clone
+
+    if (!after.models)            after.models = {};
+    if (!after.models.providers)  after.models.providers = {};
+
+    if (registerOpenAISurface) {
+      after.models.providers[PROVIDER_NAME_OPENAI] = buildOpenAIProvider({ baseUrl, apiKey });
+    }
+    if (registerNativeSurface) {
+      after.models.providers[PROVIDER_NAME_ANTHROPIC] = buildNativeProvider({ baseUrl, apiKey });
+    }
+
+    if (setDefault) {
+      // Prefer native if registered; fall back to openai-compat otherwise.
+      const preferredProvider = registerNativeSurface
+        ? PROVIDER_NAME_ANTHROPIC
+        : registerOpenAISurface
+          ? PROVIDER_NAME_OPENAI
+          : null;
+      if (preferredProvider) {
+        const target = `${preferredProvider}/claude-opus-4-7`;
+        after.models.main = target;
+        after.models.default = target;
+      }
+    }
+
+    const summary = diffSummary(
+      { providers: before.models?.providers, main: before.models?.main, default: before.models?.default },
+      { providers: after.models.providers,  main: after.models.main,  default: after.models.default },
+    );
+
+    return {
+      skip: false,
+      configPath: det.configPath,
+      before,
+      after,
+      summary,
+      warnings: [],
+    };
+  },
+
+  async apply(plan) {
+    if (plan.skip) return { applied: false, reason: plan.reason };
+    // OpenClaw uses 2-space indented JSON in its own config writes.
+    // Match that style so subsequent self-writes don't reformat the
+    // whole file.
+    const jsonOut = JSON.stringify(plan.after, null, 2) + '\n';
+    const result = writeConfigSafe(plan.configPath, jsonOut);
+    return {
+      applied: true,
+      configPath: result.path,
+      backupPath: result.backupPath,
+      bytesWritten: result.bytesWritten,
+    };
+  },
+
+  async disconnect() {
+    const det = await this.detect();
+    if (!det) return { applied: false, reason: 'OpenClaw not installed' };
+    if (det.parseError) return { applied: false, reason: `parse error: ${det.parseError}` };
+    const before = det.parsed || {};
+    const after = JSON.parse(JSON.stringify(before));
+    let changed = false;
+
+    const providers = after.models?.providers;
+    if (providers) {
+      for (const name of [PROVIDER_NAME_OPENAI, PROVIDER_NAME_ANTHROPIC]) {
+        if (providers[name]) { delete providers[name]; changed = true; }
+      }
+    }
+    // If main/default was pointing at us, blank them — let the user
+    // re-pick rather than guess at a replacement.
+    if (isMobyDefaultPointer(after.models?.main)) {
+      after.models.main = null;
+      changed = true;
+    }
+    if (isMobyDefaultPointer(after.models?.default)) {
+      after.models.default = null;
+      changed = true;
+    }
+
+    if (!changed) return { applied: false, reason: 'No moby provider entries in OpenClaw config' };
+
+    const jsonOut = JSON.stringify(after, null, 2) + '\n';
+    const result = writeConfigSafe(det.configPath, jsonOut);
+    return {
+      applied: true,
+      configPath: result.path,
+      backupPath: result.backupPath,
+      note: (after.models?.main === null || after.models?.default === null)
+        ? 'Reset main/default model to null — set a new model in OpenClaw before next request.'
+        : null,
+    };
+  },
+};

package/lib/connectors/safety.js

@@ -0,0 +1,124 @@
+/**
+ * Safety primitives for connector adapters.
+ *
+ * Every connector that modifies a third-party config file goes through
+ * these helpers — they enforce backup, atomic write, and a couple of
+ * sanity guards. Adapters MUST NOT call writeFileSync directly on a
+ * user's config; they MUST go through `writeConfigSafe`.
+ *
+ * The contract:
+ *   1. Always back up first to `<file>.mobygate-backup-<ISO-timestamp>`.
+ *   2. Write to a temp file in the same directory, fsync, then rename.
+ *      Atomic rename on POSIX, near-atomic on Windows (NTFS handles it
+ *      transparently for same-volume renames).
+ *   3. Verify the rename produced the expected content (read-back +
+ *      length sanity check) before declaring success.
+ *
+ * This keeps a corrupt file or partial write from destroying a user's
+ * carefully-tuned client config.
+ */
+
+import {
+  readFileSync,
+  writeFileSync,
+  renameSync,
+  copyFileSync,
+  existsSync,
+  statSync,
+  mkdirSync,
+  unlinkSync,
+} from 'fs';
+import { dirname, basename, join } from 'path';
+
+const ISO_SAFE = (d = new Date()) => d.toISOString().replace(/[:.]/g, '-');
+
+/**
+ * Make a timestamped backup of `path`. Returns the backup path.
+ * No-op (returns null) if `path` doesn't exist — this lets adapters
+ * call `backup()` unconditionally even when they're creating a new file.
+ */
+export function backup(path) {
+  if (!existsSync(path)) return null;
+  const dir = dirname(path);
+  const name = basename(path);
+  const backupPath = join(dir, `${name}.mobygate-backup-${ISO_SAFE()}`);
+  copyFileSync(path, backupPath);
+  return backupPath;
+}
+
+/**
+ * Atomically write `content` to `path`. Backs up first. Returns
+ * `{ path, backupPath, bytesWritten }` on success; throws on any failure
+ * (the original file is preserved by the backup).
+ *
+ * `content` must be a string. Adapters that work in structured formats
+ * (YAML, JSON) serialize before calling this.
+ */
+export function writeConfigSafe(path, content) {
+  if (typeof content !== 'string') {
+    throw new Error(`writeConfigSafe: content must be a string (got ${typeof content})`);
+  }
+  if (content.length === 0) {
+    throw new Error(`writeConfigSafe: refusing to write empty content to ${path}`);
+  }
+  const dir = dirname(path);
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+
+  const backupPath = backup(path);
+  const tempPath = `${path}.mobygate-tmp-${ISO_SAFE()}`;
+
+  try {
+    writeFileSync(tempPath, content, 'utf8');
+    // Sanity check: the temp file should be the size we just wrote.
+    const size = statSync(tempPath).size;
+    if (size === 0) throw new Error('temp file is empty after write');
+    renameSync(tempPath, path);
+  } catch (e) {
+    // Best-effort cleanup of the temp file. If rename failed mid-flight
+    // (rare), the original is intact via the backup.
+    try { if (existsSync(tempPath)) unlinkSync(tempPath); } catch {}
+    throw new Error(`writeConfigSafe failed for ${path}: ${e.message}` +
+                    (backupPath ? ` (original preserved at ${backupPath})` : ''));
+  }
+
+  // Final verify: read back what's on disk and confirm it matches.
+  const onDisk = readFileSync(path, 'utf8');
+  if (onDisk !== content) {
+    throw new Error(`writeConfigSafe verify failed for ${path}: ` +
+                    `read-back differs from intended content` +
+                    (backupPath ? ` (original preserved at ${backupPath})` : ''));
+  }
+
+  return { path, backupPath, bytesWritten: Buffer.byteLength(content, 'utf8') };
+}
+
+/**
+ * Compute a human-readable summary of a planned change. Used by adapters
+ * to produce dry-run output. `before` and `after` are arbitrary objects;
+ * we don't try to be clever — just a count of top-level differences.
+ *
+ * Returns lines like:
+ *   + providers.moby (added)
+ *   ~ providers.moby-native (changed)
+ *   - providers.old-thing (removed)
+ */
+export function diffSummary(before, after, prefix = '') {
+  const lines = [];
+  const beforeKeys = new Set(Object.keys(before || {}));
+  const afterKeys  = new Set(Object.keys(after  || {}));
+  for (const k of afterKeys) {
+    const fullKey = prefix ? `${prefix}.${k}` : k;
+    if (!beforeKeys.has(k)) {
+      lines.push(`+ ${fullKey} (added)`);
+    } else if (JSON.stringify(before[k]) !== JSON.stringify(after[k])) {
+      lines.push(`~ ${fullKey} (changed)`);
+    }
+  }
+  for (const k of beforeKeys) {
+    if (!afterKeys.has(k)) {
+      const fullKey = prefix ? `${prefix}.${k}` : k;
+      lines.push(`- ${fullKey} (removed)`);
+    }
+  }
+  return lines;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mobygate",
-  "version": "0.7.3",
+  "version": "0.8.0",
   "description": "OpenAI-compatible local proxy for Claude Max. The Möbius-strip gateway: OpenAI shape in, Claude Max out.",
   "type": "module",
   "main": "server.js",