@open-gonka/openclaw-setup

Onboarding helper that points a local OpenClaw install at the OpenAI-compatible Open Gonka Router endpoint — without hand-editing ~/.openclaw/openclaw.json.

This is the OpenClaw sibling of @open-gonka/hermes-setup. It adds a single custom provider (models.providers.gonka) and, when safe, sets the default model — it does not replace openclaw onboard and never touches your gateway, channels, daemon, or workspace.

npx @open-gonka/openclaw-setup
# headless / agent:
npx @open-gonka/openclaw-setup --connect --model moonshotai/Kimi-K2.6 --yes

⚠️ Provisional contract. The OpenClaw config/CLI contract this helper targets is sourced from docs.openclaw.ai and github.com/openclaw/openclaw, but the pinned OpenClaw release tag, version floor, and qualification commit are placeholders that must be re-verified before this package is published. See docs/specs/openclaw-agent-setup-prd/spec.md.

What it does

1. Preflight — checks Node >=22.19.0, a supported platform (Linux, macOS, WSL2), openclaw --version, and resolves the config file via OPENCLAW_CONFIG_PATH or the ~/.openclaw/openclaw.json default. It refuses to write through a symlinked openclaw.json (OpenClaw-owned writes are atomic and may replace the path).

2. API key — either the browser-based --connect device flow on https://opengonka.com, or a hidden prompt for a gnk-sk-… key. Not registered? The helper prints an active link to sign up.

3. Model catalog — fetches the live Gonka Router GET /v1/models catalog and intersects it with the checked-in launch qualification artifacts. Live-only, unqualified entries are not selectable.

4. Apply — delegates the managed surface to openclaw config set:

   openclaw config set models.providers.gonka '<json>' --strict-json --merge
   openclaw config set models.mode "merge"      # only if unset
   openclaw config set agents.defaults.model.primary "gonka/<model id>"

The managed surface in ~/.openclaw/openclaw.json:

{
  models: {
    mode: "merge",
    providers: {
      gonka: {
        baseUrl: "https://api.opengonka.com/v1",
        api: "openai-completions",
        apiKey: "${GONKA_ROUTER_API_KEY}",
        models: [
          { id: "<selected model id>", name: "<display>", input: ["text"] },
        ],
      },
    },
  },
  agents: { defaults: { model: { primary: "gonka/<selected model id>" } } },
}

The API key is an env-ref, not a secret in your config

The helper stores the key as the env-ref ${GONKA_ROUTER_API_KEY} — the raw gnk-sk-… key is never written to openclaw.json. You must make GONKA_ROUTER_API_KEY available to the OpenClaw gateway process:

export GONKA_ROUTER_API_KEY=<your gnk-sk- key>
# then start/restart the OpenClaw gateway in that same environment

For a managed daemon (launchd/systemd/Scheduled Task), set GONKA_ROUTER_API_KEY in the service environment. The helper does not modify daemon units or shell profiles — it only tells you how.

Connect mode (--connect): for your safety the helper never displays or stores a raw key, so a Connect-provisioned key is not printed. Copy your key from your OpenGonka account at https://opengonka.com to export it. The success output explains this explicitly when you use --connect.

Safety

• It only sets agents.defaults.model.primary when it is absent or already a gonka/* ref. A foreign default model is never hijacked.
• Re-running is idempotent: it does not duplicate the provider or model.
• It backs up an existing openclaw.json before applying and rolls back if an openclaw config set command fails.
• The live /v1/models check confirms auth and catalog visibility only. It does not prove billing/quota for the first billable request or full OpenClaw runtime readiness. Optional follow-ups: openclaw models list, openclaw doctor.

Scope

• Supported launch platforms: Linux, macOS, and WSL2. Native Windows is backlog.
• Out of scope: shell-profile mutation, daemon-unit mutation, arbitrary custom base URLs, replacing openclaw onboard, and deep runtime verification beyond /v1/models.
• The public flow inherits the current Gonka Router Terms availability boundaries and is not positioned for users or entities in the United States of America or U.S. territories.

Develop

npm install
npm run dev      # tsx src/cli.ts
npm run ci       # typecheck + tests + qualification validate + format + publint

See docs/ for how it works, security notes, the PRD spec, and launch qualification artifacts.

License

Apache-2.0