@byokit/openclaw 0.16.3 → 0.16.5

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 ## Unreleased
 
+## 0.16.5 (2026-10-18)
+
+- Dependency update: pins @byokit/accounts 0.28.0.
+
+## 0.16.4 (2026-10-18)
+
+FIX: Re-check the installed Claude login at every setup detection and switch out of fallback when it becomes signed in.
+
 ## 0.16.3 (2026-10-18)
 
 - Dependency update: pins @byokit/relay 0.8.2.

package/README.md

@@ -387,7 +387,7 @@ streams, [`examples/openclaw-kit`](../../examples/openclaw-kit) for a whole app,
 
 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 engine picks the installed Claude login when it starts; a person who signs in to Claude on that machine after the engine started restarts the engine to use it. A plan key (OpenCode Go: `kit.addAccount(member, { authChoice: 'opencode-go' }, on)`) asks for `Plan key`; `paste` it and the engine live-tests it before `done`. A paired device starts the same sign-in with either `via` and pastes the key over the sealed link, which keeps it on the host. A run reaches the pinned engine's static Go models (default `opencode-go/deepseek-v4-pro`); the kit keeps OpenCode Go's `x-opencode-session` header on every request, the setup probe included. A live-only Go model such as Muse needs no app config: the kit registers the plan's live catalog with each model's API, so `run({ model: 'opencode-go/muse-spark-1.3-contributor' })` runs on the account (or with `auth: 'apiKey'` on a Go key); an app that sets `config.models.providers['opencode-go'].models` keeps its own list. A choice the pinned Gateway cannot set up has readiness `no_upstream_flow` and is never offered. Pass the accounts the app offers in `KitOptions.offered` (the provider, auth choice or alias each route carries, e.g. `'openrouter'`); the kit allow-lists the plugin of every route those name, so an opted-in sign-in is not blocked. An app can still name a plugin directly in `config.plugins.allow`, and pass the route's `choice` explicitly to `kit.signIn()`.
+`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 kit re-checks the installed Claude login at each setup detection and, once it is signed in, restarts the engine onto it. A plan key (OpenCode Go: `kit.addAccount(member, { authChoice: 'opencode-go' }, on)`) asks for `Plan key`; `paste` it and the engine live-tests it before `done`. A paired device starts the same sign-in with either `via` and pastes the key over the sealed link, which keeps it on the host. A run reaches the pinned engine's static Go models (default `opencode-go/deepseek-v4-pro`); the kit keeps OpenCode Go's `x-opencode-session` header on every request, the setup probe included. A live-only Go model such as Muse needs no app config: the kit registers the plan's live catalog with each model's API, so `run({ model: 'opencode-go/muse-spark-1.3-contributor' })` runs on the account (or with `auth: 'apiKey'` on a Go key); an app that sets `config.models.providers['opencode-go'].models` keeps its own list. A choice the pinned Gateway cannot set up has readiness `no_upstream_flow` and is never offered. Pass the accounts the app offers in `KitOptions.offered` (the provider, auth choice or alias each route carries, e.g. `'openrouter'`); the kit allow-lists the plugin of every route those name, so an opted-in sign-in is not blocked. An app can still name a plugin directly in `config.plugins.allow`, and pass the route's `choice` explicitly to `kit.signIn()`.
 Offered provider plugins are allowed by default alongside the app's plugin ids. A route whose provider plugin ships outside the engine (Z.AI's GLM Coding Plan, for one) has readiness `needs_plugin` until the app calls `await kit.installPlugin(route.needs.plugin)`: it installs that plugin into the kit's own engine at exactly the engine's version and pinned npm integrity, keeps it allowed across restarts, and rejects `PluginInstallError` (`code` `version` or `integrity`) with nothing installed on a mismatch. Discovery never installs.
 
 ## API at a glance
@@ -748,4 +748,4 @@ frozen (docs/runtime-kits.md §5).
 
 Apache-2.0. See [LICENSE](LICENSE); the bundled engine's MIT text is [engine/OPENCLAW-LICENSE](engine/OPENCLAW-LICENSE).
 
-Claude: `anthropic-cli` uses your own unmodified Claude Code login on this machine (provider `claude-cli`, plugin `anthropic`; subscription billing; `kit.signedIn(member, 'claude-cli')` is true once Claude Code is signed in, and `'anthropic'` stays the API-billed provider a Claude Code login never satisfies. Before 0.7.0 this route reported provider `anthropic`; that value is deprecated, kept as `deprecatedProvider` until 0.9.0), and the engine uses the installed Claude Code’s own login as is: it runs with your `HOME` (and your own `CLAUDE_CONFIG_DIR` when you set one), so a signed-in Claude Code needs no sign-in step. Only when the installed `claude auth status --json` is not signed in does the engine use its own fallback folder `CLAUDE_CONFIG_DIR=<stateDir>/openclaw/home/.claude`; `kit.signIn(member, { authChoice: 'anthropic-cli' }, on)` then starts `claude auth login --claudeai` with that `CLAUDE_CONFIG_DIR` (in its own login HOME). When the status check gave no answer (a timeout, say), the engine keeps your own login location, and a sign-in it does not detect fails at once with “Claude Code is installed here, but its sign-in could not be checked. Run claude once on this machine to sign in, then try again.” Codex and the engine’s other agent CLIs likewise see your `HOME` and your own `CODEX_HOME`, never a kit-owned one. The gateway and doctor run with your `HOME` too; it is not an access boundary, since engine processes run with your account’s own rights. The waiting view shows the native sign-in address and asks for the returned code; send it through the same handle's `paste`, or `openclawDevice(link).signIn.paste('claude-cli', code)` on the phone. Cancel and expiry stop only this login. The `setup.activate` call is the one commit point: a phone cancel or engine shutdown before it (even with a ready native row) declines with nothing activated; after it a cancel changes nothing, and the result is `done` once the engine restart is confirmed, or says the sign-in was saved but the engine did not restart in time. Engine shutdown also ends that restart wait. An already-ready native row can be detected and activated without a new login. If engine detection disagrees, the stale ready Claude roster row is cleared through Accounts, which deletes that folder's Claude login files (`.credentials.json`, `.claude.json`) but keeps the folder, and one fresh login is started. Pass the installed Claude binary's directory in `enginePath`. For remote ChatGPT use `openai-device-code` with `via: 'code'`; it needs no localhost callback on the phone. Native sign-out is through Claude Code. `apiKey` is explicit API billing (“API key (billed per use)”, `offer: false`): `signIn` asks for the key through `paste`, then engine activation verifies it. The `setup-token` choice is listed but never offered: the pinned Gateway has no app-guided sign-in for it. The kit never imports Claude credentials or implements direct Claude.ai OAuth; [Anthropic’s terms](https://code.claude.com/docs/en/legal-and-compliance#authentication-and-credential-use) apply.
+Claude: `anthropic-cli` uses your own unmodified Claude Code login on this machine (provider `claude-cli`, plugin `anthropic`; subscription billing; `kit.signedIn(member, 'claude-cli')` is true once Claude Code is signed in, and `'anthropic'` stays the API-billed provider a Claude Code login never satisfies. Before 0.7.0 this route reported provider `anthropic`; that value is deprecated, kept as `deprecatedProvider` until 0.9.0), and the engine uses the installed Claude Code’s own login as is: it runs with your `HOME` (and your own `CLAUDE_CONFIG_DIR` when you set one), so a signed-in Claude Code needs no sign-in step. Only when the installed `claude auth status --json` is not signed in does the engine use its own fallback folder `CLAUDE_CONFIG_DIR=<stateDir>/openclaw/home/.claude`; `kit.signIn(member, { authChoice: 'anthropic-cli' }, on)` then starts `claude auth login --claudeai` with that `CLAUDE_CONFIG_DIR` (in its own login HOME). When the status check gave no answer (a timeout, say), the engine keeps your own login location, and a sign-in it does not detect fails at once with “Claude Code is installed here, but its sign-in could not be checked. Run claude once on this machine to sign in, then try again.” For the installed Codex subscription, pass its binary directory in `enginePath` and run with `model: 'openai-codex/gpt-6-luna'` (or another Codex model). `kit.signedIn(member, 'openai-codex')` asks the installed `codex login status`; it is ready only for a ChatGPT subscription login. The pinned engine's supported CLI backend runs `codex exec` with your normal `HOME` and no `CODEX_HOME` override, never copies or links your login, and keeps its own config, sessions and workspace isolated. The gateway and doctor deliberately retain `CODEX_HOME=<stateDir>/openclaw/home/.codex` so the engine itself cannot import or refresh the installed login. Upstream's discovery-only CLI probes also use that isolated override; the actual model call does not. The Codex CLI owns its own sign-in and sign-out, with no API-key fallback. The gateway and doctor run with your `HOME` too; it is not an access boundary, since engine processes run with your account’s own rights. The waiting view shows the native sign-in address and asks for the returned code; send it through the same handle's `paste`, or `openclawDevice(link).signIn.paste('claude-cli', code)` on the phone. Cancel and expiry stop only this login. The `setup.activate` call is the one commit point: a phone cancel or engine shutdown before it (even with a ready native row) declines with nothing activated; after it a cancel changes nothing, and the result is `done` once the engine restart is confirmed, or says the sign-in was saved but the engine did not restart in time. Engine shutdown also ends that restart wait. An already-ready native row can be detected and activated without a new login. If engine detection disagrees, the stale ready Claude roster row is cleared through Accounts, which deletes that folder's Claude login files (`.credentials.json`, `.claude.json`) but keeps the folder, and one fresh login is started. Pass the installed Claude binary's directory in `enginePath`. For remote ChatGPT use `openai-device-code` with `via: 'code'`; it needs no localhost callback on the phone. Native sign-out is through Claude Code. `apiKey` is explicit API billing (“API key (billed per use)”, `offer: false`): `signIn` asks for the key through `paste`, then engine activation verifies it. The `setup-token` choice is listed but never offered: the pinned Gateway has no app-guided sign-in for it. The kit never imports Claude credentials or implements direct Claude.ai OAuth; [Anthropic’s terms](https://code.claude.com/docs/en/legal-and-compliance#authentication-and-credential-use) apply.

package/dist/auth-status.d.ts

@@ -21,7 +21,7 @@ export declare function authStatus(request: GatewayTransport['request'], agentId
  * Witness only app-owned file metadata (absence included); changed/unreadable state and auth/lifecycle mutations recheck.
  * Remote revocation still comes from the real run's signed-out error (a local status read cannot prove it either).
  */
-export declare function createAuthStatus(root: string, request: GatewayTransport['request']): {
+export declare function createAuthStatus(root: string, request: GatewayTransport['request'], codex?: () => Promise<boolean>): {
     read: (agentId: string, refresh?: boolean, native?: boolean, reuse?: boolean) => Promise<AuthStatus>;
     invalidate: () => void;
 };

package/dist/auth-status.js

@@ -19,7 +19,7 @@ async function nativeStatus(request, agentId, status) {
  * Witness only app-owned file metadata (absence included); changed/unreadable state and auth/lifecycle mutations recheck.
  * Remote revocation still comes from the real run's signed-out error (a local status read cannot prove it either).
  */
-export function createAuthStatus(root, request) {
+export function createAuthStatus(root, request, codex) {
     const snapshots = new Map();
     let generation = 0;
     const invalidate = () => { generation++; snapshots.clear(); };
@@ -55,6 +55,11 @@ export function createAuthStatus(root, request) {
         snapshots.delete(key);
         snapshots.delete(`${agentId}:false`);
         const profiles = await authStatus(request, agentId, refresh);
+        if (codex) {
+            profiles.providers = (profiles.providers ?? []).filter(row => (typeof row === 'string' ? row : row.provider) !== 'openai-codex');
+            if (await codex())
+                profiles.providers.push({ provider: 'openai-codex', status: 'ok' });
+        }
         const status = native ? await nativeStatus(request, agentId, profiles) : profiles;
         if (before !== undefined && epoch === generation && witness(agentId) === before) {
             for (const [route, answer] of (native ? [[false, profiles], [true, status]] : [[false, profiles]])) {

package/dist/bridge.js

@@ -37,6 +37,7 @@ export function writePlugin(dir, o) {
         id: o.id,
         name: 'BYOKit bridge',
         activation: { onStartup: true },
+        cliBackends: ['openai-codex'],
         contracts: { tools: o.tools.map((t) => t.name), ...(o.browser ? { agentToolResultMiddleware: ['openclaw', 'codex'] } : {}) },
         configSchema: { type: 'object', additionalProperties: false },
     };

package/dist/engine.d.ts

@@ -69,7 +69,10 @@ export declare class Engine {
     };
     /** The engine's own shutdown signal; aborted by stop() and replaced by the next start(). */
     get stopSignal(): AbortSignal;
+    installedCodexSignedIn(): Promise<boolean>;
     private installedClaudeSignedOut;
+    /** Re-select the installed login on setup detection; only a confirmed login switches away from fallback. */
+    refreshInstalledClaudeLogin(): Promise<boolean>;
     /** The fallback Claude sign-in for a machine whose installed Claude Code is signed out: it signs into the engine's folder. */
     nativeClaudeLogin(): ReturnType<typeof remoteCliHost>;
     /** Whether a fallback sign-in would write a folder this engine's gateway does not read: it started on the person's

package/dist/engine.js

@@ -207,7 +207,7 @@ export class Engine {
         putOnce(join(this.root, 'npmrc'), ''); // engine npm runs read this empty config, never the person's ~/.npmrc
         this.sweepAccountOrphans();
         if (this.o.spawnEngine)
-            this.claudeFallback = await this.installedClaudeSignedOut();
+            this.claudeFallback = (await this.installedClaudeSignedOut()) ?? false;
         try {
             await this.authStore.prepare();
             this.credentialsLocked = false;
@@ -303,7 +303,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', 'keys.js', 'usage.js', 'accounts.js', 'catalog.js']) {
+        for (const f of ['package.json', 'index.js', 'keys.js', 'usage.js', 'accounts.js', 'catalog.js', 'codex.js']) {
             const source = join(kitDir, 'plugin', f);
             putChanged(join(pluginDir, f), readFileSync(source, 'utf8'));
         }
@@ -348,6 +348,8 @@ export class Engine {
         return { entry: this.entry, env: {
                 PATH: this.path, LANG: 'C.UTF-8', ...personal(), OPENCLAW_HOME: home,
                 OPENCLAW_STATE_DIR: join(this.root, 'state'), OPENCLAW_CONFIG_PATH: join(this.root, 'openclaw.json'),
+                // Upstream eagerly imports/refreshes Codex OAuth. Only the CLI may see the person's login.
+                CODEX_HOME: join(home, '.codex'),
                 XDG_CACHE_HOME: join(home, '.cache'), ...this.claudeFallback ? { CLAUDE_CONFIG_DIR: this.claudeFolder } : {},
                 TMPDIR: join(this.root, 'tmp'), npm_config_cache: join(this.root, 'npm-cache'), npm_config_userconfig: join(this.root, 'npmrc'),
                 OPENCLAW_NO_RESPAWN: '1', OPENCLAW_SKIP_CHANNELS: '1', OPENCLAW_DISABLE_BONJOUR: '1',
@@ -358,6 +360,18 @@ export class Engine {
     }
     /** The engine's own shutdown signal; aborted by stop() and replaced by the next start(). */
     get stopSignal() { return this.stopOwner.signal; }
+    async installedCodexSignedIn() {
+        if (!this.o.spawnEngine)
+            return false;
+        const env = { PATH: this.path, LANG: 'C.UTF-8', ...personal() };
+        delete env.CODEX_HOME;
+        const bin = onPath(env.PATH, 'codex');
+        if (!bin)
+            return false;
+        return new Promise(resolve => execFile(bin, ['login', 'status'], { env, timeout: 15_000, maxBuffer: 256 * 1024 }, (error, stdout, stderr) => {
+            resolve(!error && /^Logged in using ChatGPT\b/m.test(stdout + stderr));
+        }));
+    }
     installedClaudeSignedOut() {
         const env = { PATH: this.path, LANG: 'C.UTF-8', TMPDIR: join(this.root, 'tmp'), ...personal() };
         const bin = onPath(env.PATH, 'claude');
@@ -376,9 +390,19 @@ export class Engine {
                 return resolve(true);
             }
             this.o.log?.(`claude: sign-in status unknown, using the person's own login location (${String(error?.message ?? 'unparseable output').slice(0, 200)})`);
-            resolve(false);
+            resolve(undefined);
         }));
     }
+    /** Re-select the installed login on setup detection; only a confirmed login switches away from fallback. */
+    async refreshInstalledClaudeLogin() {
+        if (!this.o.spawnEngine || !this.claudeFallback)
+            return false;
+        const signedOut = await this.installedClaudeSignedOut();
+        if (signedOut !== false)
+            return false;
+        this.claudeFallback = false;
+        return true;
+    }
     /** The fallback Claude sign-in for a machine whose installed Claude Code is signed out: it signs into the engine's folder. */
     nativeClaudeLogin() {
         if (this.claudeLogin)

package/dist/kit.js

@@ -679,7 +679,7 @@ export class OpenClawKit {
             ...(o.browser ? { browserConfig: () => this.browserConfig() } : {}),
             gateBuiltins: o.gateBuiltins !== false, spawnEngine: o.spawnEngine !== false,
             onState: (s) => this.setState(s), onExit: () => this.closed('engine exited') });
-        this.admission = createAuthStatus(this.engine.root, (method, params, options) => this.request()(method, params, options));
+        this.admission = createAuthStatus(this.engine.root, (method, params, options) => this.request()(method, params, options), () => this.engine.installedCodexSignedIn());
         this.keys = createKeys({ root: this.engine.root,
             prepareOwner: (agentId) => this.prepareKeyOwner(agentId),
             indexLane: (member, route) => this.indexKeyLane(member, route),
@@ -997,7 +997,13 @@ export class OpenClawKit {
         const transport = this.transport;
         if (!transport || this.current.phase !== 'ready')
             return () => Promise.reject(new Error('gateway not ready'));
-        return (method, params, options) => {
+        return async (method, params, options) => {
+            // The gateway's own restart is in-process (OPENCLAW_NO_RESPAWN) and keeps CLAUDE_CONFIG_DIR: a new engine process drops it.
+            if (method === 'openclaw.setup.detect' && await this.engine.refreshInstalledClaudeLogin()) {
+                await this.stop();
+                await this.start();
+                return this.request()(method, params, options);
+            }
             const changesAuth = /^(models\.authLogout|openclaw\.setup\.(auth\.start|activate)|wizard\.(next|cancel)|config\.(apply|patch|set)|agents\.(create|update|delete)|secrets\.(reload|store\.(set|delete))|byokit\.keys)$/.test(method);
             if (!changesAuth || (method === 'byokit.keys' && params?.action === 'ready'))
                 return transport.request(method, params, options);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@byokit/openclaw",
-  "version": "0.16.3",
+  "version": "0.16.5",
   "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",
@@ -60,7 +60,7 @@
     "prepack": "tsc -b && node ../../scripts/fix-words-dts.cjs"
   },
   "dependencies": {
-    "@byokit/accounts": "0.27.1",
+    "@byokit/accounts": "0.28.0",
     "@byokit/pair": "0.10.4",
     "@byokit/relay": "0.8.2",
     "@byokit/discover": "0.8.4",

package/plugin/codex.js

@@ -0,0 +1,28 @@
+// Supported pinned-engine CLI backend: Codex owns its installed login; the gateway never imports it.
+export function registerCodex(api) {
+  api.registerCliBackend({
+    id: 'openai-codex', modelProvider: 'openai',
+    authEpochMode: 'profile-only', autoSelectAuthProfile: false,
+    bundleMcp: true, bundleMcpMode: 'codex-config-overrides',
+    nativeToolMode: 'none', toolAvailabilityEnforcement: 'execution-args', sideQuestionToolMode: 'disabled',
+    config: {
+      command: 'codex', input: 'stdin', output: 'jsonl', modelArg: '--model', sessionMode: 'none',
+      args: ['exec', '--json', '--ephemeral', '--skip-git-repo-check', '--ignore-user-config', '--ignore-rules',
+        '--sandbox', 'read-only', '-c', 'forced_login_method="chatgpt"',
+        '-c', 'features.shell_tool=false', '-c', 'features.unified_exec=false', '-c', 'features.apps=false',
+        '-c', 'features.plugins=false', '-c', 'features.hooks=false', '-c', 'features.multi_agent=false',
+        '-c', 'features.image_generation=false', '-c', 'web_search="disabled"', '-c', 'project_doc_max_bytes=0', '-'],
+      clearEnv: ['CODEX_HOME', 'OPENAI_API_KEY', 'OPENAI_BASE_URL', 'CODEX_OSS_BASE_URL'],
+      systemPromptFileConfigArg: '-c', systemPromptFileConfigKey: 'model_instructions_file', systemPromptWhen: 'always',
+    },
+    parseJsonlEvent(line) {
+      const event = JSON.parse(line);
+      if (event.type === 'item.completed' && event.item?.type === 'agent_message') return { kind: 'text', text: event.item.text };
+      if (event.type === 'turn.completed') return { kind: 'result', usage: {
+        input: event.usage?.input_tokens, output: event.usage?.output_tokens, cacheRead: event.usage?.cached_input_tokens,
+      } };
+      if (event.type === 'turn.failed' || event.type === 'error') return { kind: 'result', errorText: event.error?.message ?? event.message ?? 'Codex failed' };
+      return null;
+    },
+  });
+}

package/plugin/index.js

@@ -7,6 +7,7 @@ import { registerKeys } from './keys.js';
 import { registerUsage } from './usage.js';
 import { registerAccounts } from './accounts.js';
 import { registerCatalog } from './catalog.js';
+import { registerCodex } from './codex.js';
 
 /** TypeBox's Kind is a global symbol, so these schemas are valid TypeBox without importing typebox. */
 const Kind = Symbol.for('TypeBox.Kind');
@@ -149,6 +150,7 @@ export default {
     jsonSchema: { type: 'object', additionalProperties: false, properties: {} },
   },
   register(api) {
+    registerCodex(api);
     if (api.registerGatewayMethod) { registerKeys(api); registerUsage(api); registerAccounts(api); registerCatalog(api); }
     if (BROWSER) {
       if (typeof api.registerAgentToolResultMiddleware !== 'function') throw new Error('browser result protection unavailable');