openclaw/openclaw · error · AgentHarnessPreflightError

A Codex auth file exists at ${authPath}, but agent-scoped Co

Error message

A Codex auth file exists at ${authPath}, but agent-scoped Codex runs use OpenClaw's auth store and do not read that file. Preview only that credential import with `openclaw migrate plan codex --from <codex-home> --agent ${targetAgentId} --include-secrets --item auth:openai`, then run `openclaw migrate apply codex --from <codex-home> --agent ${targetAgentId} --include-secrets --item auth:openai --yes`. If the plan finds no credentials, remove the stale auth file.

What it means

Error "A Codex auth file exists at ${authPath}, but agent-scoped Codex runs use OpenClaw's auth store and do not read that file. Preview only that credential import with `openclaw migrate plan codex --from <codex-home> --agent ${targetAgentId} --include-secrets --item auth:openai`, then run `openclaw migrate apply codex --from <codex-home> --agent ${targetAgentId} --include-secrets --item auth:openai --yes`. If the plan finds no credentials, remove the stale auth file." thrown in openclaw/openclaw.

Source

Thrown at extensions/codex/src/app-server/auth-bridge.ts:145

function assertNoUnimportedAgentCodexAuthFile(params: {
  startOptions: CodexAppServerStartOptions;
  agentId?: string;
  agentDir: string;
  authRequirement?: CodexAppServerAuthRequirement;
}): void {
  // Ephemeral managed starts cannot load this stale file, and the shared-client key
  // separates auth requirements plus fallback identities. Preserve the supported
  // stdio API-key login instead of turning a leftover file into a hard failure.
  if (
    params.authRequirement === "api-key" &&
    resolveCodexAppServerFallbackApiKeyCacheKey({ startOptions: params.startOptions })
  ) {
    return;
  }
  const message = resolveUnimportedAgentCodexAuthMessage(params);
  if (message) {
    throw new AgentHarnessPreflightError(message);
  }
}

function resolveUnimportedAgentCodexAuthMessage(params: {
  startOptions: CodexAppServerStartOptions;
  agentId?: string;
  agentDir: string;
}): string | undefined {
  const managedCodexCli =
    params.startOptions.commandSource === "managed" ||
    params.startOptions.commandSource === "resolved-managed";
  if (
    params.startOptions.transport !== "stdio" ||
    !managedCodexCli ||
    params.startOptions.homeScope === "user"
  ) {
    return undefined;
  }

View on GitHub (pinned to 01804a7531)

When it happens

Trigger: Thrown at extensions/codex/src/app-server/auth-bridge.ts:145 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of openclaw/openclaw@01804a7531 (2026-08-12). Data as JSON: /api/errors/288f73e6e4cce8b8. Report an issue: GitHub.