openai/codex · error · std::io::Error

remote control requires ChatGPT authentication; API key auth

Error message

remote control requires ChatGPT authentication; API key auth is not supported

What it means

Auth loaded successfully but does not use the Codex/ChatGPT backend — typically API-key authentication. Remote control is a ChatGPT-account feature: it needs the ChatGPT account id header and pairing identity that API-key auth cannot supply, so load_remote_control_auth rejects it with PermissionDenied before any network call.

Source

Thrown at codex-rs/app-server-transport/src/transport/remote_control/auth.rs:65

                ));
            }
            auth_manager.reload().await;
            reloaded = true;
            continue;
        };
        if !auth.uses_codex_backend() {
            break auth;
        }
        if auth.get_account_id().is_none() && !reloaded {
            auth_manager.reload().await;
            reloaded = true;
            continue;
        }
        break auth;
    };

    if !auth.uses_codex_backend() {
        return Err(io::Error::new(
            ErrorKind::PermissionDenied,
            "remote control requires ChatGPT authentication; API key auth is not supported",
        ));
    }

    Ok(RemoteControlConnectionAuth {
        auth_provider: codex_model_provider::auth_provider_from_auth(&auth),
        account_id: auth.get_account_id().ok_or_else(|| {
            io::Error::new(
                ErrorKind::WouldBlock,
                "remote control enrollment is waiting for a ChatGPT account id",
            )
        })?,
    })
}

pub(super) async fn recover_remote_control_auth(
    auth_recovery: &mut UnauthorizedRecovery,

View on GitHub (pinned to 339751715c)

Solutions

Log out and run codex login choosing Sign in with ChatGPT so auth.json holds ChatGPT auth
Unset OPENAI_API_KEY and remove apiKey from preferred-auth-method config so ChatGPT auth is selected
Retry the remote-control call after confirming the session is ChatGPT-backed

Example fix

// before
export OPENAI_API_KEY=sk-...
codex remote-control pair
// Err: remote control requires ChatGPT authentication; API key auth is not supported

// after
unset OPENAI_API_KEY
codex login   # 'Sign in with ChatGPT'
codex remote-control pair   // Ok

Defensive patterns

Strategy: validation

Validate before calling

if let Some(auth) = auth_manager.auth().await {
    if !auth.uses_codex_backend() {
        // disable remote-control actions and prompt ChatGPT sign-in
    }
}

Try / catch

Match PermissionDenied whose message contains 'API key auth is not supported' and offer a 'switch to ChatGPT sign-in' action. The error is deterministic — retrying without changing auth mode always fails.

Prevention

Feature-gate remote control on auth mode, not merely on auth presence
Document that OPENAI_API_KEY and remote control are mutually exclusive
In account pickers, filter to ChatGPT-backed accounts for remote-control actions

When it happens

Trigger: Any remote-control call (pairing, client list/revoke, persist_preference, enrollment refresh) while auth.uses_codex_backend() is false — OPENAI_API_KEY set in the environment, or the preferred auth method resolving to API key, so auth.json holds key-based auth.

Common situations: Developers who usually drive Codex with an API key enable remote control for the first time; CI images injecting OPENAI_API_KEY globally; switching auth mode in config without re-logging in; org defaults that force key auth.

Understand the failure class

Authentication and authorization failures — expired tokens, bad credentials, and missing scopes.

Related errors

AI-assisted analysis of openai/codex@339751715c (2026-08-25). Data as JSON: /api/errors/bbb6f66e87a55437. Report an issue: GitHub.