@byokit/openclaw 0.3.6 → 0.4.0

package/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 ## Unreleased
 
+## 0.4.0 (2026-10-01)
+
+- Dependency update: pins @byokit/ui-core 0.6.0.
+- Dependency update: pins @byokit/reach 0.6.0.
+
+- Key readiness waits through the engine's retryable restart refusal after activation; missing keys still fail without another account.
+- API key (billed per use): `addKey` verifies and stores an explicitly entered key in a separate member-owned agent, with copying disabled and no automatic subscription fallback. `run({ auth: 'apiKey' })` selects it explicitly with separate history; key-entry labels, errors and route revision dates are included.
+- Offer subscription sign-ins, including pasted tokens and native Claude Code, by default and allow their provider plugins. API key (billed per use) routes remain app opt-in; proxies, compatibility aliases and local routes stay off.
+
 ## 0.3.6 (2026-10-01)
 
 - FIX: Live orphan gateways recover after the engine rewrites its process title. Recovery verifies the recorded launch pid and process start time with the executable and isolated store paths; ambiguous ownership preserves the saved sign-in state.

package/README.md

@@ -69,6 +69,23 @@ provider or model. If the member isn't signed in to it, the run ends `{ ok: fals
 engine is never called. Leave `model` out to keep the engine's own choice. A specific sign-in (`@profile`) can't be
 picked per run: the pinned engine may still switch to another sign-in for the same provider.
 
+
+For an owner who explicitly offers keys, `kit.addKey('ana', { authChoice: 'openai-api-key', apiKey })` returns
+`ok`, `invalid` or `not_included`. Label the option **API key (billed per use)**. Select only `routes()` rows with
+`keyEntry: true`; API rows remain `offer: false`. Each route also carries its engine `revision`, `checked` date,
+label and key error word names. Submit the input directly, clear the field afterwards, and never log or save it in
+app state. The kit never returns engine key-check errors or the key. `ui-core/kits` supplies `keyStep`/`keyView`
+for entry, checking, success and failure states, using the kit's `key.*` words.
+
+To use the saved key for one run, pass `auth: 'apiKey'`. The key lives in the member's separate
+`byokit-key-<member>` agent and workspace, with `copyToAgents: false` and only that key in its local auth order.
+Its selected model is used; omit `model` or pass that same model. Key runs have separate history. To steer or stop
+one, pass `{ auth: 'apiKey' }` to `steer` or `abort` too (the device helpers accept the same option).
+Ordinary runs never enter the key agent, even when the subscription is resting. This agent boundary is necessary
+because the engine's profile pins can rotate. The `byokit-key-` member prefix is reserved. Adding another key
+replaces the previous key; a failed replacement leaves this option unavailable. If the normal agent already has
+an API key added through pass-through calls, `addKey` returns `invalid` and leaves that key untouched.
+
 A run spec also takes `system`, `images` (`{ data, mimeType }[]`), `thinking` and `tools`, a subset of the app tools
 (`KitOptions.tools` names) this run may call; any other app tool is refused at the gate before `ToolHost.gate` sees
 it. Tool events carry the engine's call `id`, the `input` on `start` and the `output` and `error` on `end`. A run that
@@ -120,10 +137,15 @@ route: github-copilot             subscription code
 route: github-copilot-enterprise  subscription code
 route: minimax-global-oauth       subscription code
 route: minimax-cn-oauth           subscription code
+route: anthropic-cli              subscription browser
+route: setup-token                subscription browser
 ```
 
-Every offered route is a subscription sign-in. Each `Route` carries `billing` (`subscription`, `api` or `local`), so
-an app labels any other route it shows; API-billed routes are not offered by default.
+Subscription sign-ins are offered by default. API-billed routes remain in `kit.routes()` with `offer: false`;
+apps can offer them when the app or person opts in, labelled API key (billed per use). Each `Route` carries `billing` (`subscription`, `api` or
+`local`) so the app can label what is billed. Proxy routes, compatibility aliases, local runtimes stay off. Native Claude Code sign-in is offered by default. The pinned Gateway guides only some routes; other choices need manual paste or key entry. For an opted-in route, allow its `plugin` id
+in the app configuration and pass its `choice` explicitly to `kit.signIn()`.
+Offered provider plugins are allowed by default alongside the app's plugin ids.
 
 ## API at a glance
 

package/dist/device.d.ts

@@ -23,6 +23,7 @@ export type SessionRow = {
 export type DeviceRunOptions = {
     sessionKey?: string;
     model?: string;
+    auth?: 'apiKey';
     system?: string;
     images?: {
         data: string;
@@ -64,8 +65,12 @@ export declare function openclawDevice(link: DeviceLink): {
         type: 'end';
         end: RunEnd;
     }>;
-    steer(k: string, t: string): Promise<void>;
-    abort(k: string): Promise<void>;
+    steer(k: string, t: string, o?: {
+        auth?: 'apiKey';
+    }): Promise<void>;
+    abort(k: string, o?: {
+        auth?: 'apiKey';
+    }): Promise<void>;
     approvals(): Promise<Approval[]>;
     decide(id: string, d: Decision): Promise<void>;
     events(): AsyncIterable<OpenClawLinkEvent>;

package/dist/device.js

@@ -139,6 +139,7 @@ export function openclawDevice(link) {
         run: (message, o) => {
             const inner = liveStream(() => link.stream('oc.run', { message, ...(o?.sessionKey ? { sessionKey: o.sessionKey } : {}),
                 ...(o?.model !== undefined ? { model: o.model } : {}), ...(o?.system !== undefined ? { system: o.system } : {}),
+                ...(o?.auth !== undefined ? { auth: o.auth } : {}),
                 ...(o?.images !== undefined ? { images: o.images } : {}), ...(o?.thinking !== undefined ? { thinking: o.thinking } : {}),
                 ...(o?.tools !== undefined ? { tools: o.tools } : {}) }));
             let finished = false;
@@ -168,11 +169,11 @@ export function openclawDevice(link) {
                 },
             };
         },
-        steer: async (k, t) => {
-            await link.request('oc.steer', { sessionKey: k, text: t });
+        steer: async (k, t, o) => {
+            await link.request('oc.steer', { sessionKey: k, text: t, ...(o?.auth ? { auth: o.auth } : {}) });
         },
-        abort: async (k) => {
-            await link.request('oc.abort', { sessionKey: k });
+        abort: async (k, o) => {
+            await link.request('oc.abort', { sessionKey: k, ...(o?.auth ? { auth: o.auth } : {}) });
         },
         approvals: () => link.request('oc.approvals'),
         decide: async (id, d) => {

package/dist/engine.js

@@ -148,7 +148,7 @@ export class Engine {
         const pluginDir = join(this.root, 'plugin');
         mkdirSync(pluginDir, { recursive: true, mode: 0o700 });
         // The shipped plugin follows the kit on every prepare too: a state dir from an older kit must not keep its gate.
-        for (const f of ['package.json', 'index.js']) {
+        for (const f of ['package.json', 'index.js', 'keys.js']) {
             const source = join(kitDir, 'plugin', f);
             putChanged(join(pluginDir, f), readFileSync(source, 'utf8'));
         }

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 export { ENGINE_VERSION, OPERATOR_SCOPES, PROTOCOL_VERSION } from './constants.ts';
 export type { Approval, CallOptions, Decision, GatewayEventName, GatewayEventPayload, GatewayMethod, GatewayParams, GatewayResult, GatewayTransport, GateResult, Hello, KitState, Member, PlanWindow, Route, RunEnd, RunEvent, RunRef, RunSpec, RunUsage, SignInOptions, SignInView, ToolHost, ToolSpec, } from './types.ts';
 export { OpenClawKit, type KitOptions, type RetainedLogin } from './kit.ts';
+export type { AddKeyResult } from './keys.ts';
 export { stateWords, toAccountView, words, type AccountView, type WordKey } from './words.ts';
 export { EngineAlreadyRunningError } from './engine-status.ts';

package/dist/keys.d.ts

@@ -0,0 +1,20 @@
+import type { GatewayTransport, Member } from './types.ts';
+export type AddKeyResult = 'ok' | 'invalid' | 'not_included';
+export declare function createKeys(ctx: {
+    root: string;
+    request: GatewayTransport['request'];
+    ensure(member: Member): Promise<{
+        agentId: string;
+    }>;
+    restarting?(): boolean;
+}): {
+    exclusive: <T>(member: Member, work: () => Promise<T>) => Promise<T>;
+    add(member: Member, o: {
+        authChoice: string;
+        apiKey: string;
+    }): Promise<AddKeyResult>;
+    ready(member: Member): Promise<{
+        agentId: string;
+        model: string;
+    } | undefined>;
+};

package/dist/keys.js

@@ -0,0 +1,73 @@
+import { join } from 'node:path';
+import { keyAgentId, MEMBER_ID, KEY_PREFIX } from "./members.js";
+import { routes } from "./routes.js";
+export function createKeys(ctx) {
+    // Serialize key replacement and key runs, so an in-flight run never sees a half-installed replacement.
+    const tails = new Map();
+    const exclusive = async (member, work) => {
+        const previous = tails.get(member) ?? Promise.resolve();
+        const next = previous.catch(() => { }).then(work);
+        tails.set(member, next);
+        try {
+            return await next;
+        }
+        finally {
+            if (tails.get(member) === next)
+                tails.delete(member);
+        }
+    };
+    const check = (member) => MEMBER_ID.test(member) && !member.startsWith(KEY_PREFIX);
+    const control = (member, action, provider) => ctx.request('byokit.keys', { member, action, ...(provider ? { provider } : {}) });
+    return {
+        exclusive,
+        async add(member, o) {
+            if (!check(member) || !o.apiKey.trim())
+                return 'invalid';
+            const route = routes().find((r) => r.choice === o.authChoice && r.keyEntry);
+            if (!route)
+                return 'not_included';
+            return exclusive(member, async () => {
+                try {
+                    await ctx.ensure(member);
+                    const agentId = keyAgentId(member);
+                    const list = await ctx.request('agents.list');
+                    if (!list.agents.some((a) => a.id === agentId))
+                        await ctx.request('agents.create', { name: agentId, workspace: join(ctx.root, 'key-workspaces', member) });
+                    if (!(await control(member, 'prepare', route.provider)).ok)
+                        return 'invalid';
+                    // The public pin's typed API-key path, never a CLI-login import. Discard the engine's lines/errors.
+                    const params = {
+                        kind: 'api-key', agentId, authChoice: o.authChoice, apiKey: o.apiKey,
+                    };
+                    const result = (await ctx.request('openclaw.setup.activate', params, { timeoutMs: 180_000 }));
+                    if (!result.ok)
+                        return result.status === 'unavailable' ? 'not_included' : 'invalid';
+                    return (await control(member, 'seal')).ok ? 'ok' : 'invalid';
+                }
+                catch {
+                    return 'invalid';
+                }
+            });
+        },
+        async ready(member) {
+            if (!check(member))
+                return undefined;
+            const deadline = Date.now() + 60_000;
+            for (;;) {
+                try {
+                    const ready = await control(member, 'ready');
+                    return ready.ok && ready.model ? { agentId: keyAgentId(member), model: ready.model } : undefined;
+                }
+                catch (error) {
+                    // Config writes may drain/restart the gateway after activation. This read is safe to retry;
+                    // an absent profile or a terminal refusal still fails closed immediately.
+                    const refusal = error;
+                    const transient = ctx.restarting?.() || (refusal?.code === 'UNAVAILABLE' && refusal.retryable === true);
+                    if (!transient || Date.now() >= deadline)
+                        return undefined;
+                    await new Promise((resolve) => setTimeout(resolve, 250));
+                }
+            }
+        },
+    };
+}

package/dist/kit.d.ts

@@ -1,4 +1,5 @@
 import type { SealingAdapter } from '@byokit/secrets';
+import { type AddKeyResult } from './keys.ts';
 import type { Approval, CallOptions, Decision, GatewayEventName, GatewayEventPayload, GatewayMethod, GatewayParams, GatewayResult, GatewayTransport, Hello, KitState, Member, Route, RunEnd, RunEvent, RunSpec, SignInOptions, SignInView, ToolHost, ToolSpec } from './types.ts';
 export type KitOptions = {
     stateDir: string;
@@ -47,6 +48,7 @@ export declare class OpenClawKit {
     private greeting?;
     private members?;
     private readonly bridge;
+    private readonly keys;
     private readonly approvalsCtl;
     private listeners;
     private off;
@@ -81,14 +83,24 @@ export declare class OpenClawKit {
         done: Promise<SignInView>;
     };
     signOut(member: Member, provider: string): Promise<void>;
+    /** Save an explicitly supplied API key (billed per use) in this member's separate key agent. */
+    addKey(agentId: Member, o: {
+        authChoice: string;
+        apiKey: string;
+    }): Promise<AddKeyResult>;
     migrateRetainedLogin(member: Member, source: RetainedLogin): Promise<'staged' | 'nothing' | 'failed'>;
     confirmRetainedLogin(member: Member, source: RetainedLogin): Promise<boolean>;
     private runs;
     /** The app tool names (`KitOptions.tools`): the only names `RunSpec.tools` may carry. */
     toolNames(): string[];
     run(spec: RunSpec, on?: (e: RunEvent) => void): Promise<RunEnd>;
-    steer(sessionKey: string, text: string): Promise<void>;
-    abort(sessionKey: string): Promise<void>;
+    private runKey;
+    steer(sessionKey: string, text: string, o?: {
+        auth?: 'apiKey';
+    }): Promise<void>;
+    abort(sessionKey: string, o?: {
+        auth?: 'apiKey';
+    }): Promise<void>;
     approvals(member?: Member): Approval[];
     onApproval(fn: (a: Approval, change: 'added' | 'resolved') => void): () => void;
     decide(id: string, d: Decision): Promise<void>;

package/dist/kit.js

@@ -8,8 +8,10 @@ import { Bridge } from "./bridge.js";
 import { Engine } from "./engine.js";
 import { gatewayTransport } from "./transport.js";
 import { createMembers } from "./members.js";
+import { keyAgentId, KEY_PREFIX, MEMBER_ID } from "./members.js";
 import { confirmRetainedLogin as confirmLogin, migrateRetainedLogin as migrateLogin } from "./migrate.js";
 import { createRuns } from "./runs.js";
+import { createKeys } from "./keys.js";
 import { routes as routeTable } from "./routes.js";
 import { providers as engineProviders, signIn as startSignIn, signOut as engineSignOut } from "./signin.js";
 import { reconcileConfig, memoryLimited as configMemoryLimited } from "./config.js";
@@ -420,6 +422,7 @@ export class OpenClawKit {
     // One bridge and one approval surface per kit: listeners and run registrations survive reconnects (B3).
     // Only the socket itself is per-connection. Approvals always reaches the live transport through this.request().
     bridge;
+    keys;
     approvalsCtl;
     listeners = new Set();
     off = [];
@@ -439,6 +442,10 @@ export class OpenClawKit {
         this.engine = new Engine({ ...o, pluginId: o.plugin?.id ?? 'byokit', tools: o.tools ?? [],
             gateBuiltins: o.gateBuiltins !== false, spawnEngine: o.spawnEngine !== false,
             onState: (s) => this.setState(s), onExit: () => this.closed('engine exited') });
+        this.keys = createKeys({ root: this.engine.root,
+            restarting: () => this.current.phase === 'restarting' || this.current.phase === 'starting',
+            request: (method, params, options) => this.request()(method, params, options),
+            ensure: (member) => this.ensureMember(member) });
         const slot = {};
         this.approvalsCtl = new Approvals({
             request: (method, params, co) => this.request()(method, params, co),
@@ -599,6 +606,10 @@ export class OpenClawKit {
     signOut(member, provider) {
         return engineSignOut(this.signInCtx(), member, provider);
     }
+    /** Save an explicitly supplied API key (billed per use) in this member's separate key agent. */
+    addKey(agentId, o) {
+        return this.keys.add(agentId, o);
+    }
     migrateRetainedLogin(member, source) {
         return migrateLogin({ root: this.engine.root, prepare: () => this.prepare(), doctor: () => this.engine.doctor(120_000),
             seal: this.o.authSeal, log: this.o.log, withStore: (task) => this.engine.withAuthStore(task) }, member, source);
@@ -627,13 +638,35 @@ export class OpenClawKit {
         return (this.o.tools ?? []).map((t) => t.name);
     }
     run(spec, on) {
+        if (spec.auth !== undefined && spec.auth !== 'apiKey')
+            return Promise.reject(new Error('Choose a supported account option.'));
+        if (spec.auth === 'apiKey')
+            return this.keys.exclusive(spec.member, async () => {
+                if (!spec.sessionKey.startsWith(`agent:${spec.member}:`))
+                    throw new Error('This conversation belongs to another member.');
+                const selected = await this.keys.ready(spec.member);
+                if (!selected)
+                    return { ok: false, kind: 'signed-out', message: 'Add an API key to use this option.' };
+                if (spec.model !== undefined && spec.model !== selected.model)
+                    return { ok: false, kind: 'plan', message: 'Choose the model saved with this key.' };
+                // RunRef.member stays the person for app gates; the engine receives the isolated agent and history.
+                return this.runs().run({ ...spec, model: selected.model }, on, selected.agentId);
+            });
         return this.runs().run(spec, on);
     }
-    steer(sessionKey, text) {
-        return this.runs().steer(sessionKey, text);
+    runKey(sessionKey, o) {
+        if (o?.auth !== 'apiKey')
+            return sessionKey;
+        const [, member, tail] = /^agent:([^:]+):(.*)$/.exec(sessionKey) ?? [];
+        if (!member || !MEMBER_ID.test(member) || member.startsWith(KEY_PREFIX))
+            throw new Error('Choose your own conversation.');
+        return `agent:${keyAgentId(member)}:${tail}`;
+    }
+    steer(sessionKey, text, o) {
+        return this.runs().steer(this.runKey(sessionKey, o), text);
     }
-    abort(sessionKey) {
-        return this.runs().abort(sessionKey);
+    abort(sessionKey, o) {
+        return this.runs().abort(this.runKey(sessionKey, o));
     }
     // approvals (5.9)
     approvals(member) {

package/dist/link.js

@@ -25,9 +25,10 @@ function memberSessions(result, member) {
 }
 /** `oc.run`'s run options, type-checked; the kit's own checks (account, tool names) still apply. */
 function runOptions(args) {
-    const { message, model, system, images, thinking, tools } = args;
+    const { message, model, auth, system, images, thinking, tools } = args;
     const ok = typeof message === 'string'
         && (model === undefined || typeof model === 'string')
+        && (auth === undefined || auth === 'apiKey')
         && (system === undefined || typeof system === 'string')
         && (images === undefined || (Array.isArray(images) && images.every((i) => isRecord(i) && typeof i.data === 'string' && typeof i.mimeType === 'string')))
         && (thinking === undefined || (typeof thinking === 'string' && THINKING.has(thinking)))
@@ -37,6 +38,7 @@ function runOptions(args) {
     return {
         message: message,
         ...(model === undefined ? {} : { model: model }),
+        ...(auth === undefined ? {} : { auth: 'apiKey' }),
         ...(system === undefined ? {} : { system: system }),
         ...(images === undefined ? {} : { images: images
                 .map((i) => ({ data: i.data, mimeType: i.mimeType })) }),
@@ -180,19 +182,19 @@ export function openclawLink(kit, o) {
                 return memberSessions(result, member);
             }
             case 'oc.steer': {
-                if (typeof args.sessionKey !== 'string' || typeof args.text !== 'string')
+                if (typeof args.sessionKey !== 'string' || typeof args.text !== 'string' || (args.auth !== undefined && args.auth !== 'apiKey'))
                     throw new Error('oc.steer needs { sessionKey, text }');
                 if (!memberKey(member, args.sessionKey))
                     throw refused();
-                await kit.steer(args.sessionKey, args.text);
+                await kit.steer(args.sessionKey, args.text, args.auth === 'apiKey' ? { auth: 'apiKey' } : undefined);
                 return null;
             }
             case 'oc.abort': {
-                if (typeof args.sessionKey !== 'string')
+                if (typeof args.sessionKey !== 'string' || (args.auth !== undefined && args.auth !== 'apiKey'))
                     throw new Error('oc.abort needs { sessionKey }');
                 if (!memberKey(member, args.sessionKey))
                     throw refused();
-                await kit.abort(args.sessionKey);
+                await kit.abort(args.sessionKey, args.auth === 'apiKey' ? { auth: 'apiKey' } : undefined);
                 return null;
             }
             case 'oc.approvals':

package/dist/members.d.ts

@@ -1,5 +1,7 @@
 import type { GatewayTransport, Member } from './types.ts';
 export declare const MEMBER_ID: RegExp;
+export declare const KEY_PREFIX = "byokit-key-";
+export declare const keyAgentId: (member: Member) => string;
 export declare function createMembers(ctx: {
     request: GatewayTransport['request'];
     root: string;

package/dist/members.js

@@ -1,9 +1,11 @@
 import { join } from 'node:path';
 export const MEMBER_ID = /^[a-z][a-z0-9-]{0,31}$/;
+export const KEY_PREFIX = 'byokit-key-';
+export const keyAgentId = (member) => `${KEY_PREFIX}${member}`;
 export function createMembers(ctx) {
     const cache = new Map();
     return { ensure(member) {
-            if (!MEMBER_ID.test(member))
+            if (!MEMBER_ID.test(member) || member.startsWith(KEY_PREFIX))
                 return Promise.reject(new Error(`invalid member id: ${member}`));
             const existing = cache.get(member);
             if (existing)

package/dist/routes.json

@@ -8,7 +8,12 @@
         "prerequisite": null,
         "offer": true,
         "reason": "ChatGPT/Codex subscription sign-in: the engine writes the redirect to the app's callback port.",
-        "source": "dist/provider-contract-api-*.js (2026.8.1)"
+        "source": "dist/provider-contract-api-*.js (2026.8.1)",
+        "revision": "2026.8.1",
+        "checked": "2026-09-30",
+        "label": "Subscription",
+        "keyEntry": false,
+        "keyErrors": null
     },
     {
         "choice": "openai-device-code",
@@ -19,7 +24,12 @@
         "prerequisite": null,
         "offer": true,
         "reason": "ChatGPT subscription sign-in by device code: the code is shown, no browser on this computer needed.",
-        "source": "dist/provider-contract-api-*.js (2026.8.1)"
+        "source": "dist/provider-contract-api-*.js (2026.8.1)",
+        "revision": "2026.8.1",
+        "checked": "2026-09-30",
+        "label": "Subscription",
+        "keyEntry": false,
+        "keyErrors": null
     },
     {
         "choice": "xai-oauth",
@@ -30,7 +40,12 @@
         "prerequisite": null,
         "offer": true,
         "reason": "Grok subscription sign-in through the engine's own wizard.",
-        "source": "dist/extensions/xai/openclaw.plugin.json (2026.8.1)"
+        "source": "dist/extensions/xai/openclaw.plugin.json (2026.8.1)",
+        "revision": "2026.8.1",
+        "checked": "2026-09-30",
+        "label": "Subscription",
+        "keyEntry": false,
+        "keyErrors": null
     },
     {
         "choice": "github-copilot",
@@ -41,7 +56,12 @@
         "prerequisite": null,
         "offer": true,
         "reason": "GitHub Copilot subscription sign-in; the login stays in the engine's own folder.",
-        "source": "dist/extensions/github-copilot/openclaw.plugin.json (2026.8.1)"
+        "source": "dist/extensions/github-copilot/openclaw.plugin.json (2026.8.1)",
+        "revision": "2026.8.1",
+        "checked": "2026-09-30",
+        "label": "Subscription",
+        "keyEntry": false,
+        "keyErrors": null
     },
     {
         "choice": "github-copilot-enterprise",
@@ -52,7 +72,12 @@
         "prerequisite": null,
         "offer": true,
         "reason": "GitHub Copilot Enterprise sign-in; the login stays in the engine's own folder.",
-        "source": "dist/extensions/github-copilot/openclaw.plugin.json (2026.8.1)"
+        "source": "dist/extensions/github-copilot/openclaw.plugin.json (2026.8.1)",
+        "revision": "2026.8.1",
+        "checked": "2026-09-30",
+        "label": "Subscription",
+        "keyEntry": false,
+        "keyErrors": null
     },
     {
         "choice": "minimax-global-oauth",
@@ -63,7 +88,12 @@
         "prerequisite": null,
         "offer": true,
         "reason": "MiniMax subscription sign-in (global endpoint).",
-        "source": "dist/extensions/minimax/openclaw.plugin.json (2026.8.1)"
+        "source": "dist/extensions/minimax/openclaw.plugin.json (2026.8.1)",
+        "revision": "2026.8.1",
+        "checked": "2026-09-30",
+        "label": "Subscription",
+        "keyEntry": false,
+        "keyErrors": null
     },
     {
         "choice": "minimax-cn-oauth",
@@ -74,7 +104,12 @@
         "prerequisite": null,
         "offer": true,
         "reason": "MiniMax subscription sign-in (CN endpoint).",
-        "source": "dist/extensions/minimax/openclaw.plugin.json (2026.8.1)"
+        "source": "dist/extensions/minimax/openclaw.plugin.json (2026.8.1)",
+        "revision": "2026.8.1",
+        "checked": "2026-09-30",
+        "label": "Subscription",
+        "keyEntry": false,
+        "keyErrors": null
     },
     {
         "choice": "openrouter-oauth",
@@ -84,8 +119,13 @@
         "via": "browser",
         "prerequisite": null,
         "offer": false,
-        "reason": "API billing, not a subscription; upstream OAuth yields a credit-billed key.",
-        "source": "dist/extensions/openrouter/openclaw.plugin.json (2026.8.1)"
+        "reason": "API key (billed per use); offered only when the app or person opts in.",
+        "source": "dist/extensions/openrouter/openclaw.plugin.json (2026.8.1)",
+        "revision": "2026.8.1",
+        "checked": "2026-09-30",
+        "label": "API key (billed per use)",
+        "keyEntry": false,
+        "keyErrors": null
     },
     {
         "choice": "xai-device-code",
@@ -96,7 +136,12 @@
         "prerequisite": null,
         "offer": false,
         "reason": "Compatibility alias the Gateway does not offer; use xai-oauth.",
-        "source": "dist/extensions/xai/openclaw.plugin.json (2026.8.1)"
+        "source": "dist/extensions/xai/openclaw.plugin.json (2026.8.1)",
+        "revision": "2026.8.1",
+        "checked": "2026-09-30",
+        "label": "Subscription",
+        "keyEntry": false,
+        "keyErrors": null
     },
     {
         "choice": "alibaba-model-studio-api-key",
@@ -106,8 +151,13 @@
         "via": "browser",
         "prerequisite": null,
         "offer": false,
-        "reason": "API billing, not a subscription; shown only when an app asks.",
-        "source": "dist/extensions/alibaba/openclaw.plugin.json (2026.8.1)"
+        "reason": "API key (billed per use); offered only when the app or person opts in.",
+        "source": "dist/extensions/alibaba/openclaw.plugin.json (2026.8.1)",
+        "revision": "2026.8.1",
+        "checked": "2026-09-30",
+        "label": "API key (billed per use)",
+        "keyEntry": false,
+        "keyErrors": null
     },
     {
         "choice": "anthropic-cli",
@@ -121,7 +171,12 @@
         "source": "dist/extensions/anthropic/openclaw.plugin.json (2026.8.1)",
         "auth": "cli",
         "terms": "allowed",
-        "termsUrl": "https://code.claude.com/docs/en/legal-and-compliance#authentication-and-credential-use"
+        "termsUrl": "https://code.claude.com/docs/en/legal-and-compliance#authentication-and-credential-use",
+        "revision": "2026.8.1",
+        "checked": "2026-09-30",
+        "label": "Subscription",
+        "keyEntry": false,
+        "keyErrors": null
     },
     {
         "choice": "apiKey",
@@ -135,7 +190,15 @@
         "source": "dist/extensions/anthropic/openclaw.plugin.json (2026.8.1)",
         "auth": "api_key",
         "terms": "allowed",
-        "termsUrl": "https://code.claude.com/docs/en/legal-and-compliance#authentication-and-credential-use"
+        "termsUrl": "https://code.claude.com/docs/en/legal-and-compliance#authentication-and-credential-use",
+        "revision": "2026.8.1",
+        "checked": "2026-09-30",
+        "label": "API key (billed per use)",
+        "keyEntry": true,
+        "keyErrors": {
+            "invalid": "key.invalid",
+            "not_included": "key.notIncluded"
+        }
     },
     {
         "choice": "clawrouter-api-key",
@@ -145,8 +208,13 @@
         "via": "browser",
         "prerequisite": null,
         "offer": false,
-        "reason": "API billing, not a subscription; shown only when an app asks.",
-        "source": "dist/extensions/clawrouter/openclaw.plugin.json (2026.8.1)"
+        "reason": "Proxy route; API key (billed per use); offered only when an app asks.",
+        "source": "dist/extensions/clawrouter/openclaw.plugin.json (2026.8.1)",
+        "revision": "2026.8.1",
+        "checked": "2026-09-30",
+        "label": "API key (billed per use)",
+        "keyEntry": false,
+        "keyErrors": null
     },
     {
         "choice": "copilot-proxy",
@@ -157,7 +225,12 @@
         "prerequisite": null,
         "offer": false,
         "reason": "Local runtime on this computer; no account and no billing.",
-        "source": "dist/extensions/copilot-proxy/openclaw.plugin.json (2026.8.1)"
+        "source": "dist/extensions/copilot-proxy/openclaw.plugin.json (2026.8.1)",
+        "revision": "2026.8.1",
+        "checked": "2026-09-30",
+        "label": "On this computer",
+        "keyEntry": false,
+        "keyErrors": null
     },
     {
         "choice": "custom-api-key",
@@ -167,8 +240,13 @@
         "via": "browser",
         "prerequisite": null,
         "offer": false,
-        "reason": "API billing, not a subscription; shown only when an app asks.",
-        "source": "dist/auth-choice-options-BLHNSTXX.js (2026.8.1)"
+        "reason": "Proxy route; API key (billed per use); offered only when an app asks.",
+        "source": "dist/auth-choice-options-BLHNSTXX.js (2026.8.1)",
+        "revision": "2026.8.1",
+        "checked": "2026-09-30",
+        "label": "API key (billed per use)",
+        "keyEntry": false,
+        "keyErrors": null
     },
     {
         "choice": "fal-api-key",
@@ -178,8 +256,13 @@
         "via": "browser",
         "prerequisite": null,
         "offer": false,
-        "reason": "API billing, not a subscription; shown only when an app asks.",
-        "source": "dist/extensions/fal/openclaw.plugin.json (2026.8.1)"
+        "reason": "API key (billed per use); offered only when the app or person opts in.",
+        "source": "dist/extensions/fal/openclaw.plugin.json (2026.8.1)",
+        "revision": "2026.8.1",
+        "checked": "2026-09-30",
+        "label": "API key (billed per use)",
+        "keyEntry": false,
+        "keyErrors": null
     },
     {
         "choice": "gemini-api-key",
@@ -189,8 +272,16 @@
         "via": "browser",
         "prerequisite": null,
         "offer": false,
-        "reason": "API billing, not a subscription; shown only when an app asks.",
-        "source": "dist/provider-contract-api-*.js (2026.8.1)"
+        "reason": "API key (billed per use); offered only when the app or person opts in.",
+        "source": "dist/provider-contract-api-*.js (2026.8.1)",
+        "revision": "2026.8.1",
+        "checked": "2026-09-30",
+        "label": "API key (billed per use)",
+        "keyEntry": true,
+        "keyErrors": {
+            "invalid": "key.invalid",
+            "not_included": "key.notIncluded"
+        }
     },
     {
         "choice": "huggingface-api-key",
@@ -200,8 +291,16 @@
         "via": "browser",
         "prerequisite": null,
         "offer": false,
-        "reason": "API billing, not a subscription; shown only when an app asks.",
-        "source": "dist/extensions/huggingface/openclaw.plugin.json (2026.8.1)"
+        "reason": "API key (billed per use); offered only when the app or person opts in.",
+        "source": "dist/extensions/huggingface/openclaw.plugin.json (2026.8.1)",
+        "revision": "2026.8.1",
+        "checked": "2026-09-30",
+        "label": "API key (billed per use)",
+        "keyEntry": true,
+        "keyErrors": {
+            "invalid": "key.invalid",
+            "not_included": "key.notIncluded"
+        }
     },
     {
         "choice": "litellm-api-key",
@@ -211,8 +310,16 @@
         "via": "browser",
         "prerequisite": null,
         "offer": false,
-        "reason": "API billing, not a subscription; shown only when an app asks.",
-        "source": "dist/extensions/litellm/openclaw.plugin.json (2026.8.1)"
+        "reason": "Proxy route; API key (billed per use); offered only when an app asks.",
+        "source": "dist/extensions/litellm/openclaw.plugin.json (2026.8.1)",
+        "revision": "2026.8.1",
+        "checked": "2026-09-30",
+        "label": "API key (billed per use)",
+        "keyEntry": true,
+        "keyErrors": {
+            "invalid": "key.invalid",
+            "not_included": "key.notIncluded"
+        }
     },
     {
         "choice": "lmstudio",
@@ -223,7 +330,12 @@
         "prerequisite": null,
         "offer": false,
         "reason": "Local runtime on this computer; no account and no billing.",
-        "source": "dist/extensions/lmstudio/openclaw.plugin.json (2026.8.1)"
+        "source": "dist/extensions/lmstudio/openclaw.plugin.json (2026.8.1)",
+        "revision": "2026.8.1",
+        "checked": "2026-09-30",
+        "label": "On this computer",
+        "keyEntry": false,
+        "keyErrors": null
     },
     {
         "choice": "microsoft-foundry-apikey",
@@ -233,8 +345,13 @@
         "via": "browser",
         "prerequisite": null,
         "offer": false,
-        "reason": "API billing, not a subscription; shown only when an app asks.",
-        "source": "dist/extensions/microsoft-foundry/openclaw.plugin.json (2026.8.1)"
+        "reason": "API key (billed per use); offered only when the app or person opts in.",
+        "source": "dist/extensions/microsoft-foundry/openclaw.plugin.json (2026.8.1)",
+        "revision": "2026.8.1",
+        "checked": "2026-09-30",
+        "label": "API key (billed per use)",
+        "keyEntry": false,
+        "keyErrors": null
     },
     {
         "choice": "microsoft-foundry-entra",
@@ -244,8 +361,13 @@
         "via": "browser",
         "prerequisite": null,
         "offer": false,
-        "reason": "API billing, not a subscription; shown only when an app asks.",
-        "source": "dist/extensions/microsoft-foundry/openclaw.plugin.json (2026.8.1)"
+        "reason": "API key (billed per use); offered only when the app or person opts in.",
+        "source": "dist/extensions/microsoft-foundry/openclaw.plugin.json (2026.8.1)",
+        "revision": "2026.8.1",
+        "checked": "2026-09-30",
+        "label": "API key (billed per use)",
+        "keyEntry": false,
+        "keyErrors": null
     },
     {
         "choice": "minimax-cn-api",
@@ -255,8 +377,13 @@
         "via": "browser",
         "prerequisite": null,
         "offer": false,
-        "reason": "API billing, not a subscription; shown only when an app asks.",
-        "source": "dist/extensions/minimax/openclaw.plugin.json (2026.8.1)"
+        "reason": "API key (billed per use); offered only when the app or person opts in.",
+        "source": "dist/extensions/minimax/openclaw.plugin.json (2026.8.1)",
+        "revision": "2026.8.1",
+        "checked": "2026-09-30",
+        "label": "API key (billed per use)",
+        "keyEntry": false,
+        "keyErrors": null
     },
     {
         "choice": "minimax-global-api",
@@ -266,8 +393,13 @@
         "via": "browser",
         "prerequisite": null,
         "offer": false,
-        "reason": "API billing, not a subscription; shown only when an app asks.",
-        "source": "dist/extensions/minimax/openclaw.plugin.json (2026.8.1)"
+        "reason": "API key (billed per use); offered only when the app or person opts in.",
+        "source": "dist/extensions/minimax/openclaw.plugin.json (2026.8.1)",
+        "revision": "2026.8.1",
+        "checked": "2026-09-30",
+        "label": "API key (billed per use)",
+        "keyEntry": false,
+        "keyErrors": null
     },
     {
         "choice": "nvidia-api-key",
@@ -277,8 +409,16 @@
         "via": "browser",
         "prerequisite": null,
         "offer": false,
-        "reason": "API billing, not a subscription; shown only when an app asks.",
-        "source": "dist/extensions/nvidia/openclaw.plugin.json (2026.8.1)"
+        "reason": "API key (billed per use); offered only when the app or person opts in.",
+        "source": "dist/extensions/nvidia/openclaw.plugin.json (2026.8.1)",
+        "revision": "2026.8.1",
+        "checked": "2026-09-30",
+        "label": "API key (billed per use)",
+        "keyEntry": true,
+        "keyErrors": {
+            "invalid": "key.invalid",
+            "not_included": "key.notIncluded"
+        }
     },
     {
         "choice": "ollama",
@@ -289,7 +429,12 @@
         "prerequisite": null,
         "offer": false,
         "reason": "Local runtime on this computer; no account and no billing.",
-        "source": "dist/extensions/ollama/openclaw.plugin.json (2026.8.1)"
+        "source": "dist/extensions/ollama/openclaw.plugin.json (2026.8.1)",
+        "revision": "2026.8.1",
+        "checked": "2026-09-30",
+        "label": "On this computer",
+        "keyEntry": false,
+        "keyErrors": null
     },
     {
         "choice": "ollama-cloud",
@@ -299,8 +444,16 @@
         "via": "browser",
         "prerequisite": null,
         "offer": false,
-        "reason": "API billing, not a subscription; shown only when an app asks.",
-        "source": "dist/extensions/ollama/openclaw.plugin.json (2026.8.1)"
+        "reason": "API key (billed per use); offered only when the app or person opts in.",
+        "source": "dist/extensions/ollama/openclaw.plugin.json (2026.8.1)",
+        "revision": "2026.8.1",
+        "checked": "2026-09-30",
+        "label": "API key (billed per use)",
+        "keyEntry": true,
+        "keyErrors": {
+            "invalid": "key.invalid",
+            "not_included": "key.notIncluded"
+        }
     },
     {
         "choice": "openai-api-key",
@@ -310,8 +463,16 @@
         "via": "browser",
         "prerequisite": null,
         "offer": false,
-        "reason": "API billing, not a subscription; shown only when an app asks.",
-        "source": "dist/provider-contract-api-*.js (2026.8.1)"
+        "reason": "API key (billed per use); offered only when the app or person opts in.",
+        "source": "dist/provider-contract-api-*.js (2026.8.1)",
+        "revision": "2026.8.1",
+        "checked": "2026-09-30",
+        "label": "API key (billed per use)",
+        "keyEntry": true,
+        "keyErrors": {
+            "invalid": "key.invalid",
+            "not_included": "key.notIncluded"
+        }
     },
     {
         "choice": "opencode-go",
@@ -321,8 +482,16 @@
         "via": "browser",
         "prerequisite": null,
         "offer": false,
-        "reason": "API billing, not a subscription; shown only when an app asks.",
-        "source": "dist/extensions/opencode-go/openclaw.plugin.json (2026.8.1)"
+        "reason": "API key (billed per use); offered only when the app or person opts in.",
+        "source": "dist/extensions/opencode-go/openclaw.plugin.json (2026.8.1)",
+        "revision": "2026.8.1",
+        "checked": "2026-09-30",
+        "label": "API key (billed per use)",
+        "keyEntry": true,
+        "keyErrors": {
+            "invalid": "key.invalid",
+            "not_included": "key.notIncluded"
+        }
     },
     {
         "choice": "openrouter-api-key",
@@ -332,8 +501,16 @@
         "via": "browser",
         "prerequisite": null,
         "offer": false,
-        "reason": "API billing, not a subscription; shown only when an app asks.",
-        "source": "dist/extensions/openrouter/openclaw.plugin.json (2026.8.1)"
+        "reason": "API key (billed per use); offered only when the app or person opts in.",
+        "source": "dist/extensions/openrouter/openclaw.plugin.json (2026.8.1)",
+        "revision": "2026.8.1",
+        "checked": "2026-09-30",
+        "label": "API key (billed per use)",
+        "keyEntry": true,
+        "keyErrors": {
+            "invalid": "key.invalid",
+            "not_included": "key.notIncluded"
+        }
     },
     {
         "choice": "runway-api-key",
@@ -343,8 +520,13 @@
         "via": "browser",
         "prerequisite": null,
         "offer": false,
-        "reason": "API billing, not a subscription; shown only when an app asks.",
-        "source": "dist/extensions/runway/openclaw.plugin.json (2026.8.1)"
+        "reason": "API key (billed per use); offered only when the app or person opts in.",
+        "source": "dist/extensions/runway/openclaw.plugin.json (2026.8.1)",
+        "revision": "2026.8.1",
+        "checked": "2026-09-30",
+        "label": "API key (billed per use)",
+        "keyEntry": false,
+        "keyErrors": null
     },
     {
         "choice": "setup-token",
@@ -353,12 +535,17 @@
         "billing": "subscription",
         "via": "browser",
         "prerequisite": null,
-        "offer": false,
-        "reason": "Token import is not the native Claude Code login route; direct Claude.ai OAuth remains excluded.",
+        "offer": true,
+        "reason": "Claude subscription sign-in by pasting a token.",
         "source": "dist/extensions/anthropic/openclaw.plugin.json (2026.8.1)",
         "auth": "token",
         "terms": "grey",
-        "termsUrl": "https://code.claude.com/docs/en/legal-and-compliance#authentication-and-credential-use"
+        "termsUrl": "https://code.claude.com/docs/en/legal-and-compliance#authentication-and-credential-use",
+        "revision": "2026.8.1",
+        "checked": "2026-09-30",
+        "label": "Subscription",
+        "keyEntry": false,
+        "keyErrors": null
     },
     {
         "choice": "sglang",
@@ -369,7 +556,12 @@
         "prerequisite": null,
         "offer": false,
         "reason": "Local runtime on this computer; no account and no billing.",
-        "source": "dist/extensions/sglang/openclaw.plugin.json (2026.8.1)"
+        "source": "dist/extensions/sglang/openclaw.plugin.json (2026.8.1)",
+        "revision": "2026.8.1",
+        "checked": "2026-09-30",
+        "label": "On this computer",
+        "keyEntry": false,
+        "keyErrors": null
     },
     {
         "choice": "together-api-key",
@@ -379,8 +571,16 @@
         "via": "browser",
         "prerequisite": null,
         "offer": false,
-        "reason": "API billing, not a subscription; shown only when an app asks.",
-        "source": "dist/extensions/together/openclaw.plugin.json (2026.8.1)"
+        "reason": "API key (billed per use); offered only when the app or person opts in.",
+        "source": "dist/extensions/together/openclaw.plugin.json (2026.8.1)",
+        "revision": "2026.8.1",
+        "checked": "2026-09-30",
+        "label": "API key (billed per use)",
+        "keyEntry": true,
+        "keyErrors": {
+            "invalid": "key.invalid",
+            "not_included": "key.notIncluded"
+        }
     },
     {
         "choice": "vllm",
@@ -391,7 +591,12 @@
         "prerequisite": null,
         "offer": false,
         "reason": "Local runtime on this computer; no account and no billing.",
-        "source": "dist/extensions/vllm/openclaw.plugin.json (2026.8.1)"
+        "source": "dist/extensions/vllm/openclaw.plugin.json (2026.8.1)",
+        "revision": "2026.8.1",
+        "checked": "2026-09-30",
+        "label": "On this computer",
+        "keyEntry": false,
+        "keyErrors": null
     },
     {
         "choice": "xai-api-key",
@@ -401,7 +606,15 @@
         "via": "browser",
         "prerequisite": null,
         "offer": false,
-        "reason": "API billing, not a subscription; shown only when an app asks.",
-        "source": "dist/extensions/xai/openclaw.plugin.json (2026.8.1)"
+        "reason": "API key (billed per use); offered only when the app or person opts in.",
+        "source": "dist/extensions/xai/openclaw.plugin.json (2026.8.1)",
+        "revision": "2026.8.1",
+        "checked": "2026-09-30",
+        "label": "API key (billed per use)",
+        "keyEntry": true,
+        "keyErrors": {
+            "invalid": "key.invalid",
+            "not_included": "key.notIncluded"
+        }
     }
 ]

package/dist/runs.d.ts

@@ -14,7 +14,7 @@ export declare function createRuns(ctx: {
     bridge: Pick<Bridge, 'register'>;
     tools: ReadonlySet<string>;
 }): {
-    run(spec: RunSpec, on?: (e: RunEvent) => void): Promise<RunEnd>;
+    run(spec: RunSpec, on?: (e: RunEvent) => void, keyAgent?: string): Promise<RunEnd>;
     steer(k: string, t: string): Promise<void>;
     abort(k: string): Promise<void>;
 };

package/dist/runs.js

@@ -78,7 +78,7 @@ export function createRuns(ctx) {
             return undefined;
         }
     };
-    const run = async (spec, on) => {
+    const run = async (spec, on, keyAgent) => {
         // Member boundary first: a member never speaks in another member's session, refused before any request.
         if (!spec.sessionKey.startsWith(`agent:${spec.member}:`))
             throw new Error(`refused: "${spec.sessionKey}" is not a session of member "${spec.member}"`);
@@ -86,8 +86,9 @@ export function createRuns(ctx) {
         for (const tool of spec.tools ?? [])
             if (!ctx.tools.has(tool))
                 throw new Error(`refused: "${tool}" is not one of this kit's tools`);
-        const { agentId } = await ctx.ensure(spec.member);
-        const release = spec.register !== false ? ctx.bridge.register({ sessionKey: spec.sessionKey, member: spec.member }, spec.tools) : undefined;
+        const agentId = keyAgent ?? (await ctx.ensure(spec.member)).agentId;
+        const sessionKey = keyAgent ? `agent:${keyAgent}:${spec.sessionKey.slice(`agent:${spec.member}:`.length)}` : spec.sessionKey;
+        const release = spec.register !== false ? ctx.bridge.register({ sessionKey, member: spec.member }, spec.tools) : undefined;
         let last = '';
         let runId = ''; // gateway events for other runs carry a real runId and never match the empty one
         let ended = false;
@@ -148,7 +149,7 @@ export function createRuns(ctx) {
             };
             const final = ctx.request('agent', {
                 agentId,
-                sessionKey: spec.sessionKey,
+                sessionKey,
                 message: spec.message,
                 idempotencyKey: randomUUID(),
                 ...(picked ?? {}),

package/dist/testing/fake-gateway.js

@@ -7,6 +7,7 @@ import { readFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { ENGINE_VERSION, PROTOCOL_VERSION } from "../constants.js";
 import { toolCalls } from "./model-stub.js";
+import { routes } from "../routes.js";
 // The device-code script from Crewhouse's openclaw-wizard.test.ts, ported: the step, then progress, then done.
 const DEVICE_STEP = {
     id: 'step-device', type: 'note', executor: 'client',
@@ -98,6 +99,7 @@ export function fakeGateway(script) {
     const failures = new Map();
     const handlers = new Map();
     const agents = new Map();
+    const keys = new Map();
     const wizards = new Map();
     const runs = new Map();
     const configBox = { hash: 'hash-1', config: {} };
@@ -220,8 +222,37 @@ export function fakeGateway(script) {
             const agent = agents.get(String(p?.agentId ?? 'main'));
             if (agent)
                 agent.providers = agent.providers.filter((provider) => provider !== p.provider);
+            if (keys.get(String(p.agentId))?.provider === p.provider)
+                keys.delete(String(p.agentId));
             return {};
         },
+        'byokit.keys': (p) => {
+            const id = `byokit-key-${p.member}`;
+            if (p.action === 'prepare') {
+                keys.delete(id);
+                ensureAgent(id).providers = [];
+                return { ok: true };
+            }
+            const key = keys.get(id);
+            if (!key)
+                return { ok: false };
+            if (p.action === 'seal') {
+                key.sealed = true;
+                return { ok: true };
+            }
+            return { ok: key.sealed, ...(key.sealed ? { model: key.model } : {}) };
+        },
+        'openclaw.setup.activate': (p) => {
+            if (p.kind !== 'api-key')
+                throw new Error('only the API-key setup path is simulated');
+            const route = routes().find((r) => r.choice === p.authChoice && r.keyEntry);
+            if (!route)
+                return { ok: false, status: 'unavailable' };
+            const model = `${route.provider}/fake-key-model`;
+            keys.set(p.agentId, { provider: route.provider, key: p.apiKey, model, sealed: false });
+            signInAgent(p.agentId, route.provider);
+            return { ok: true, status: 'ok', modelRef: model };
+        },
         'openclaw.setup.auth.start': (p) => {
             const sessionId = String(p.sessionId ?? `fake-${randomUUID()}`);
             wizards.set(sessionId, { agentId: String(p.agentId ?? 'main'), answered: false, pulls: 0 });
@@ -338,7 +369,8 @@ export function fakeGateway(script) {
     for (const [method, handler] of Object.entries(script ?? {}))
         handlers.set(method, handler);
     const dispatch = async (method, params, bridgeSock) => {
-        calls.push({ method, params });
+        calls.push({ method, params: method === 'openclaw.setup.activate' && isPlainObject(params)
+                ? { ...params, ...(params.apiKey === undefined ? {} : { apiKey: '[redacted]' }) } : params });
         const queue = failures.get(method);
         if (queue?.length)
             throw new Error(queue.shift());

package/dist/types.d.ts

@@ -34,6 +34,8 @@ export interface RunSpec extends RunRef {
     }[];
     thinking?: 'off' | 'low' | 'medium' | 'high';
     model?: string;
+    /** Explicit paid key choice. Uses a separate member-owned agent and separate session history. */
+    auth?: 'apiKey';
     tools?: string[];
     register?: boolean;
 }
@@ -139,6 +141,14 @@ export type Route = {
     offer: boolean;
     reason: string;
     source: string;
+    revision: string;
+    checked: string;
+    label: string;
+    keyEntry: boolean;
+    keyErrors: {
+        invalid: 'key.invalid';
+        not_included: 'key.notIncluded';
+    } | null;
 };
 export interface GatewayTransport {
     start(): Promise<Hello>;

package/dist/words.json

@@ -19,5 +19,12 @@
     "approval.ask": "{helper} wants to {summary}. Allow it?",
     "approval.expired": "Nobody answered in time, so this wasn't allowed.",
     "approval.notice": "Something is waiting for your yes.",
-    "link.notAllowed": "This device can't do that. Ask the person at the computer."
+    "link.notAllowed": "This device can't do that. Ask the person at the computer.",
+    "key.label": "API key (billed per use)",
+    "key.entry": "Paste your API key. You pay the provider for each use.",
+    "key.checking": "Checking your key…",
+    "key.ok": "Your key is ready. Use it only when you choose this option.",
+    "key.invalid": "This key could not be saved. Check it and try again.",
+    "key.notIncluded": "This option is not available here.",
+    "key.missing": "Add an API key to use this option."
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@byokit/openclaw",
-  "version": "0.3.6",
+  "version": "0.4.0",
   "description": "The OpenClaw runtime kit: the pinned engine's full operator surface with plain-words helpers for members, sign-in, runs and approvals.",
   "license": "Apache-2.0",
   "type": "module",
@@ -54,7 +54,7 @@
   "dependencies": {
     "@byokit/link": "0.7.0",
     "@byokit/relay": "0.5.0",
-    "@byokit/reach": "0.5.0",
+    "@byokit/reach": "0.6.0",
     "@byokit/seal": "0.2.0",
     "@byokit/secrets": "0.5.0",
     "@openclaw/gateway-client": "2026.8.1",
@@ -62,7 +62,7 @@
     "ws": "8.21.3"
   },
   "devDependencies": {
-    "@byokit/ui-core": "0.5.0"
+    "@byokit/ui-core": "0.6.0"
   },
   "publishConfig": {
     "access": "public"

package/plugin/index.js

@@ -3,6 +3,7 @@
 // schemas and descriptions stay app data. No imports beyond node builtins: nothing here needs resolving in-gateway.
 import { connect } from 'node:net';
 import { readFileSync } from 'node:fs';
+import { registerKeys } from './keys.js';
 
 /** TypeBox's Kind is a global symbol, so these schemas are valid TypeBox without importing typebox. */
 const Kind = Symbol.for('TypeBox.Kind');
@@ -114,6 +115,7 @@ export default {
     jsonSchema: { type: 'object', additionalProperties: false, properties: {} },
   },
   register(api) {
+    if (api.registerGatewayMethod) registerKeys(api);
     for (const spec of table.tools) {
       api.registerTool({
         name: spec.name,

package/plugin/keys.js

@@ -0,0 +1,101 @@
+// Agent-local key isolation. The engine owns the SQLite transaction and publishes the changed runtime snapshot.
+// No key value crosses this method. Only the typed setup.activate request ever carries a secret.
+export function registerKeys(api) {
+  api.registerGatewayMethod('byokit.keys', async ({ params, respond }) => {
+    const member = params?.member;
+    if (typeof member !== 'string' || !/^[a-z][a-z0-9-]{0,31}$/.test(member) || member.startsWith('byokit-key-')
+      || !['prepare', 'seal', 'ready'].includes(params.action)) {
+      respond(true, { ok: false });
+      return;
+    }
+    const diagnostics = params.action === 'ready' && params.diagnostics === true ? { stage: 'imports' } : undefined;
+    const reply = (value) => respond(true, { ...value, ...(diagnostics ? { diagnostics } : {}) });
+    try {
+      const { readFile, writeFile, rm } = await import('node:fs/promises');
+      const { join } = await import('node:path');
+      const { resolveAgentDir } = await import('openclaw/plugin-sdk/agent-runtime');
+      const { updateAuthProfileStoreWithLock } = await import('openclaw/plugin-sdk/provider-auth');
+      // Read the current config: activation changes the roster and selection during the same gateway lifetime.
+      if (diagnostics) diagnostics.stage = 'config';
+      const config = JSON.parse(await readFile(process.env.OPENCLAW_CONFIG_PATH, 'utf8'));
+      const keyId = `byokit-key-${member}`;
+      if (!config.agents?.entries?.[member] || !config.agents?.entries?.[keyId]) {
+        reply({ ok: false });
+        return;
+      }
+      const keyDir = resolveAgentDir(config, keyId);
+      const marker = join(keyDir, 'byokit-key-ready.json');
+      if (params.action === 'ready') {
+        if (diagnostics) diagnostics.stage = 'marker';
+        const selected = JSON.parse(await readFile(marker, 'utf8'));
+        let ready = false;
+        if (diagnostics) diagnostics.stage = 'store';
+        await updateAuthProfileStoreWithLock({ agentDir: keyDir, updater(store) {
+          if (diagnostics) {
+            diagnostics.profiles = Object.entries(store.profiles).map(([id, p]) => ({ id, apiKey: p.type === 'api_key', local: p.copyToAgents === false }));
+            diagnostics.order = store.order;
+            diagnostics.selected = selected.profileId;
+            diagnostics.stage = 'checked';
+          }
+          const profile = store.profiles[selected.profileId];
+          ready = profile?.type === 'api_key' && profile.copyToAgents === false
+            && store.order?.[profile.provider]?.length === 1 && store.order[profile.provider][0] === selected.profileId;
+          return false;
+        } });
+        reply({ ok: ready, ...(ready ? { model: selected.model } : {}) });
+        return;
+      }
+      await rm(marker, { force: true });
+      if (params.action === 'prepare') {
+        // Only local profiles are loaded by this transaction: no shared-store read-through or CLI sync.
+        const normal = await updateAuthProfileStoreWithLock({
+          agentDir: resolveAgentDir(config, member),
+          saveOptions: { filterExternalAuthProfiles: false, syncExternalCli: false },
+          updater(store) {
+            if (Object.values(store.profiles).some((p) => p.type === 'api_key'))
+              throw new Error('The normal agent already has a key.');
+            const providers = new Set([params.provider, ...Object.values(store.profiles).map((p) => p.provider)].filter((p) => typeof p === 'string'));
+            store.order ??= {};
+            for (const provider of providers) store.order[provider] = Object.entries(store.profiles)
+              .filter(([, p]) => p.provider === provider && p.type === 'oauth').map(([id]) => id);
+            return true;
+          },
+        });
+        if (!normal) { respond(true, { ok: false }); return; }
+        // A replacement starts empty. During activation this agent is unavailable to kit.run.
+        const cleared = await updateAuthProfileStoreWithLock({ agentDir: keyDir,
+          saveOptions: { filterExternalAuthProfiles: false, syncExternalCli: false },
+          updater(store) { store.profiles = {}; store.order = {}; return true; } });
+        respond(true, { ok: Boolean(cleared) });
+        return;
+      }
+      const ref = config.agents.entries[keyId].model;
+      const primary = typeof ref === 'string' ? ref : ref?.primary;
+      const at = typeof primary === 'string' ? primary.lastIndexOf('@') : -1;
+      if (at < 1) { respond(true, { ok: false }); return; }
+      const profileId = primary.slice(at + 1);
+      const model = primary.slice(0, at);
+      let found = false;
+      const sealed = await updateAuthProfileStoreWithLock({ agentDir: keyDir,
+        saveOptions: { filterExternalAuthProfiles: false, syncExternalCli: false },
+        updater(store) {
+          const profile = store.profiles[profileId];
+          if (profile?.type !== 'api_key') return false;
+          found = true;
+          profile.copyToAgents = false;
+          store.profiles = { [profileId]: profile };
+          // A stored agent-local order wins over global config and contains exactly this key, never a sign-in.
+          store.order = { [profile.provider]: [profileId] };
+          store.lastGood = {};
+          return true;
+        },
+      });
+      if (!sealed || !found) { respond(true, { ok: false }); return; }
+      await writeFile(marker, JSON.stringify({ profileId, model }), { mode: 0o600 });
+      respond(true, { ok: true });
+    } catch {
+      // Neither engine errors nor store contents (which contain secrets) ever leave this method.
+      reply({ ok: false });
+    }
+  }, { scope: 'operator.admin' });
+}