Codex review: needs maintainer review before merge. Reviewed June 28, 2026, 8:40 AM ET / 12:40 UTC.

Summary
The PR adds Z.AI onboarding-command rejection for API-key setup plus a provider-owned static auth-profile doctor hook, tests, and provider SDK docs.

PR surface: Source +112, Tests +169, Docs +3. Total +284 across 11 files.

Reproducibility: yes. at source level: current main accepts non-empty Z.AI API-key input and can persist onboarding command text through the setup path. I did not run a live Z.AI credential repro in this read-only review.

Review metrics: 1 noteworthy metric.

• Provider API surface: 1 optional hook added, 0 removed. The diff expands the provider plugin contract, so maintainers should notice and accept the compatibility surface before merge.

Stored data model
Persistent data-model change detected: migration/backfill/repair: src/agents/auth-profiles/doctor.ts, migration/backfill/repair: src/commands/doctor-auth.profile-health.test.ts, migration/backfill/repair: src/commands/doctor-auth.ts, migration/backfill/repair: src/plugins/provider-runtime.test.ts, unknown-data-model-change: src/commands/doctor-auth.profile-health.test.ts. Confirm migration or upgrade compatibility proof before merge.

Root-cause cluster
Relationship: fixed_by_candidate
Canonical: #97313
Summary: This PR is a candidate fix for the command-string auth-profile pollution root cause documented in the linked issue, while the broader stale profile, key-rotation, doctor --fix, and fallback scope remains with the issue.

Members:

• canonical: Z.AI provider sub-agent auth fails with stale auth profile cache after key rotation / doctor --fix #97313 - The issue is open and tracks the broader Z.AI auth-profile failure; this PR references it and fixes one concrete command-string pollution path from its discussion.

Proposal only: this assessment does not dispatch repair, suppress jobs, mutate sibling items, close, or merge anything.

Merge readiness
Overall: 🐚 platinum hermit
Proof: 🦞 diamond lobster
Patch quality: 🐚 platinum hermit
Result: ready for maintainer review.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Rank-up moves:

• [P2] Get maintainer acceptance for the optional static provider doctor hook before merge.
• Rerun the focused doctor/Z.AI tests on a healthy lane if maintainers want stronger latest-head test proof.

Risk before merge

• [P1] The new optional buildStaticAuthProfileDoctorHint hook expands the provider plugin contract and core doctor invocation path, so maintainers need to accept that API direction before merge.
• [P1] The contributor’s latest focused Vitest rerun still hung on their Windows worktree, so the latest-head proof relies on terminal assertions, lint/docs checks, and earlier focused test passes rather than a completed latest-head focused Vitest run.

Maintainer options:

1. Confirm the static doctor hook contract (recommended)
   A maintainer can accept the optional provider hook as the intended plugin API seam and merge this narrow bug fix with the broader linked issue still open.
2. Replace the hook direction
   If maintainers do not want a new provider API, ask for a rewrite that keeps Z.AI input rejection and uses an already-approved doctor seam for surfacing polluted profiles.
3. Pause for broader auth-profile scoping
   If static doctor hints are too narrow for the linked auth-profile problem, pause this PR until the remaining key-rotation and doctor-repair behavior is scoped.

Next step before merge

• [P2] Manual review is appropriate because the remaining blocker is maintainer API acceptance for a new optional provider hook, not a mechanical code repair.

Security
Cleared: The diff changes auth validation, provider hook plumbing, doctor output, docs, and tests without adding dependencies, workflows, permissions, secret exposure, or new code-execution paths.

Addressed the ClawSweeper finding about the Z.AI doctor hint being routed only through the OAuth/token formatter.

What changed:

• noteAuthProfileHealthForTarget now emits static Z.AI API-key command-text profiles through the actual auth health note path as static [invalid_api_key].
• Added a doctor-auth.profile-health regression for the static API-key path.
• Updated the PR body with fresh doctor-output proof from the exported auth doctor path using the real terminal note renderer.

Known proof gap: the full source node scripts/run-node.mjs doctor --non-interactive command hung on this Windows worktree during source-runner build activity and was stopped; no live Z.AI key is available.

@clawsweeper re-review

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

Addressed the latest ClawSweeper owner-boundary finding.

What changed in 7705005d2b:

• Removed the Z.AI command regex and Z.AI recovery copy from core auth-profile doctor code.
• Kept core doctor generic: it now surfaces static API-key provider hook hints as static [invalid_api_key].
• Moved the Z.AI polluted-profile predicate and recovery message into the Z.AI provider buildAuthDoctorHint hook.
• Updated tests so core verifies provider-hook surfacing and the Z.AI provider verifies its own doctor hint.

Fresh checks are in the PR body. The Windows Vitest runner still hung locally, so I included that as a proof gap rather than presenting it as passing.

@clawsweeper re-review

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

@clawsweeper re-review

Addressed the latest hook-contract review by replacing the widened buildAuthDoctorHint / issueKind design with a separate static-profile opt-in hook:

• buildAuthDoctorHint is back to the existing OAuth repair-hint contract with no issueKind parameter.
• Static API-key doctor surfacing now calls buildStaticAuthProfileDoctorHint only.
• Z.AI implements the new static hook for the onboarding-command polluted profile case.
• Removed the temporary Anthropic/OpenAI production guards and tests because static doctor checks no longer call their OAuth-only hooks.
• Added runtime forwarding and provider-runtime coverage for the new hook.

Fresh proof after the update:

rg -n "issueKind|ProviderStaticAuthProfileDoctorHintContext" src extensions -g "*.ts"
npx oxfmt --check extensions/anthropic/index.test.ts extensions/anthropic/register.runtime.ts extensions/openai/openai-chatgpt-provider.ts extensions/openai/openai-provider.test.ts extensions/zai/index.ts extensions/zai/index.test.ts src/agents/auth-profiles/doctor.ts src/plugins/types.ts src/plugins/provider-runtime.ts src/plugins/provider-runtime.runtime.ts src/plugins/provider-runtime.test.ts src/commands/doctor-auth.profile-health.test.ts
npx oxlint extensions/anthropic/index.test.ts extensions/anthropic/register.runtime.ts extensions/openai/openai-chatgpt-provider.ts extensions/openai/openai-provider.test.ts extensions/zai/index.ts extensions/zai/index.test.ts src/agents/auth-profiles/doctor.ts src/plugins/types.ts src/plugins/provider-runtime.ts src/plugins/provider-runtime.runtime.ts src/plugins/provider-runtime.test.ts src/commands/doctor-auth.profile-health.test.ts
node scripts/plugin-sdk-surface-report.mjs --check
node --import tsx -e "await import('./src/agents/auth-profiles/doctor.ts'); await import('./src/commands/doctor-auth.ts'); await import('./extensions/zai/index.ts'); await import('./src/plugins/provider-runtime.ts'); console.log('imports passed');"
node --import tsx -e "import plugin from './extensions/zai/index.ts'; import { registerSingleProviderPlugin } from 'openclaw/plugin-sdk/plugin-test-runtime'; const provider = await registerSingleProviderPlugin(plugin); const store = { version: 1, profiles: { 'zai:default': { type: 'api_key', provider: 'zai', key: 'openclaw onboard --auth-choice zai-coding-global' } } }; const hint = provider.buildStaticAuthProfileDoctorHint?.({ provider: 'zai', profileId: 'zai:default', store }); if (hint !== 'Z.AI auth profile zai:default contains an onboarding command instead of an API key. Re-authenticate with a real key: openclaw onboard --auth-choice zai-coding-global.') throw new Error(String(hint)); if (provider.buildAuthDoctorHint?.({ provider: 'zai', profileId: 'zai:default', store }) !== undefined) throw new Error('unexpected oauth hook hint'); console.log('zai static opt-in hook assertion passed');"
git diff --check

All exited 0; rg found no matches. plugin-sdk-surface-report.mjs --check passed with unchanged public package SDK export count and package-exported forbidden subpaths: 0.

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

@clawsweeper re-review

Addressed the two remaining merge blockers from the latest review:

• Broadened Z.AI onboarding-command detection so documented non-interactive variants are rejected, including openclaw onboard --non-interactive --auth-choice zai-coding-global ... and --auth-choice=zai-coding-global.
• Added regression coverage for those command variants through the Z.AI setup path and the static auth-profile doctor hook.
• Documented buildStaticAuthProfileDoctorHint in both provider hook tables: docs/plugins/sdk-provider-plugins.md and docs/plugins/architecture-internals.md.
• Kept buildAuthDoctorHint documented as OAuth refresh repair guidance, with static API-key repair guidance isolated to the new opt-in hook.

Fresh proof after this update:

npx oxfmt --check extensions/zai/index.ts extensions/zai/index.test.ts docs/plugins/sdk-provider-plugins.md docs/plugins/architecture-internals.md
npx oxlint extensions/zai/index.ts extensions/zai/index.test.ts
pnpm docs:list
pnpm docs:check-mdx
node scripts/plugin-sdk-surface-report.mjs --check
node --import tsx -e "import plugin from './extensions/zai/index.ts'; import { registerSingleProviderPlugin } from 'openclaw/plugin-sdk/plugin-test-runtime'; const provider = await registerSingleProviderPlugin(plugin); const method = provider.auth.find((entry) => entry.wizard?.choiceId === 'zai-coding-global'); if (!method) throw new Error('missing zai auth method'); const commands = ['openclaw onboard --auth-choice zai-coding-global', 'openclaw onboard --non-interactive --auth-choice zai-coding-global --zai-api-key $ZAI_API_KEY', 'openclaw onboard --non-interactive --auth-choice=zai-coding-global --zai-api-key $ZAI_API_KEY']; for (const command of commands) { await method.run({ config: {}, prompter: { confirm: async () => false, select: async (_params, fallback) => fallback, text: async () => command, note: async () => undefined }, runtime: { log: () => {}, error: () => {}, exit: () => {} }, isRemote: false, openUrl: async () => undefined, oauth: { createVpsAwareHandlers: () => ({}) } }).then(() => { throw new Error('accepted command: ' + command); }, (err) => { if (!String(err?.message ?? err).includes('Z.AI API key cannot be an OpenClaw onboarding command.')) throw err; }); } const store = { version: 1, profiles: { 'zai:default': { type: 'api_key', provider: 'zai', key: commands[1] } } }; const hint = provider.buildStaticAuthProfileDoctorHint?.({ provider: 'zai', profileId: 'zai:default', store }); if (hint !== 'Z.AI auth profile zai:default contains an onboarding command instead of an API key. Re-authenticate with a real key: openclaw onboard --auth-choice zai-coding-global.') throw new Error(String(hint)); console.log('zai documented command variant assertions passed');"
git diff --check

All exited 0. pnpm docs:check-mdx passed for 684 files. node scripts/run-vitest.mjs extensions/zai/index.test.ts --reporter=verbose still hung on this Windows worktree and was stopped after 150 seconds with no output, consistent with the previous local Vitest runner gap documented in the PR body.

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

@clawsweeper re-review

Addressed the latest finding:

• Added the existing buildProviderAuthDoctorHintWithPlugin export back to the doctor-auth.profile-health.test.ts provider-runtime mock.
• Reset it in beforeEach alongside the new static hook mock so existing OAuth doctor paths keep their generic fallback behavior during this focused test file.

Fresh proof after this narrow test-mock repair:

npx oxfmt --check src/commands/doctor-auth.profile-health.test.ts
npx oxlint src/commands/doctor-auth.profile-health.test.ts
git diff --check

All exited 0.

I also retried the requested focused test:

node scripts/run-vitest.mjs src/commands/doctor-auth.profile-health.test.ts --reporter=verbose

It still hung on this Windows worktree with no output and was stopped after roughly 120 seconds, matching the previously documented local Vitest runner gap.

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

Closing this as superseded by the canonical shared-auth fix in #97520, which landed as fb7e10e. That path puts malformed onboarding-command API key rejection in the shared credential eligibility boundary and keeps the ZAI-specific work from diverging. Thanks for the fix work here.