iPhone Codex remote control setup fails until desktop session satisfies MFA

[omid-method]

Summary

Codex on iPhone could not complete secure setup / remote-control pairing after a desktop account re-login triggered by a password change. Reinstalling the iPhone app and resetting the desktop app did not fully fix it. The connection started working only after MFA was enabled / refreshed for the ChatGPT account and the desktop Codex session was re-authenticated.

The likely root cause is that the desktop remote-control enrollment endpoint requires a session with MFA assurance, but the iPhone and desktop UX only surfaced a generic setup failure instead of explaining that MFA was required.

User-visible symptoms

• iPhone Codex setup repeatedly failed with:

Setup failed. Couldn't finish secure setup. Try again.

• The failure happened after changing the account password, which forced Codex desktop to re-login.
• Reinstalling the iPhone app did not help.
• Resetting the desktop app made the iPhone appear connected at a basic device/account level, but Codex remote control still failed.
• The iPhone authorization flow could be completed through the browser, but returning to the app still ended in setup failure.

Environment

• macOS desktop Codex app
• iPhone ChatGPT/Codex app
• ChatGPT Pro account
• Account had recently changed password
• Desktop Codex remote-control daemon was running

Relevant versions observed during troubleshooting:

• Desktop Codex app: 26.519.41501, build 3044
• Bundled Codex CLI: 0.133.0-alpha.1
• Standalone Codex CLI: 0.133.0
• iPhone ChatGPT app: 1.2026.132

Fixes / checks tried

• Reinstalled the iPhone app.
• Reset the desktop Codex app.
• Confirmed iPhone app could launch and enter the Codex setup flow.
• Tried both Personal and workspace account contexts during iPhone authorization.
• Confirmed iPhone app permissions were not obviously blocking setup:
  • Background App Refresh enabled.
  • Cellular Data enabled.
  • No obvious Local Network permission prompt / setting appeared.
• Confirmed desktop Codex remote-control settings were enabled:
  • Device discoverable / controllable setting enabled.
  • Keep Mac awake enabled.
• Confirmed the local desktop remote-control daemon was running.
• Confirmed codex doctor was otherwise healthy.
• Confirmed the desktop remote-control enrollment database stayed empty while setup was failing.
• Re-authenticated the desktop Codex CLI through browser login.
• Enabled Codex device-code authorization in ChatGPT security settings.
• Enabled / refreshed Authenticator app MFA in ChatGPT security settings.
• Re-authenticated desktop Codex after MFA changes.

Key diagnostic evidence

The desktop remote-control daemon was failing enrollment with:

HTTP 403 Forbidden
{"detail":"Multi-factor authentication required"}

This occurred while enrolling the desktop remote-control server with the backend remote-control endpoint.

This explains why local fixes did not resolve the problem: the desktop service was alive locally, but backend enrollment was rejected because the authenticated session did not satisfy the backend's MFA requirement.

Working workaround

The connection started working after refreshing the account's MFA state and re-authenticating Codex desktop.

Practical workaround:

1. Open ChatGPT account security settings.
2. Enable or refresh MFA, such as Authenticator app MFA.
3. Re-login to Codex desktop / Codex CLI after MFA is active.
4. Restart or toggle Codex desktop remote control.
5. Retry iPhone Codex setup.

Important: users should complete password and MFA prompts locally. They should not paste passwords, recovery codes, or MFA codes into support tools or chat.

Likely root cause

The remote-control server enrollment path requires MFA, but the client surfaces the failure as a generic iPhone setup error.

There may also be a session-state mismatch after password changes:

• Desktop Codex can appear logged in.
• The remote-control daemon can be running locally.
• The iPhone authorization flow can appear to complete.
• But backend enrollment still rejects the desktop remote-control server because the desktop auth session lacks MFA assurance.

Suggested product fix

Backend / API

• Return a structured error code for this case, for example:

{
  "code": "mfa_required",
  "message": "Multi-factor authentication is required to enable Codex remote control."
}

• Preserve the existing HTTP status if needed, but make the machine-readable cause explicit.

Desktop Codex

• Detect mfa_required during remote-control enrollment.
• Mark remote control as blocked by account security instead of generic connection failure.
• Show a direct action in Settings > Connections:

Multi-factor authentication is required before this Mac can be controlled from iPhone.
Open account security settings, enable MFA, then sign in to Codex again.

• After a password change or auth refresh, force remote-control enrollment to re-check MFA and update the visible state.

iPhone Codex

• Replace the generic setup failure with a specific message when desktop enrollment failed due to MFA:

Your Mac needs multi-factor authentication enabled before iPhone setup can finish.
Enable MFA on your ChatGPT account, sign in to Codex on your Mac again, then retry.

• If possible, include a "Send instructions to Mac" or "Open account security" affordance.

CLI / diagnostics

• Add this condition to codex doctor or remote-control diagnostics:

Remote control enrollment: blocked
Reason: Multi-factor authentication required
Action: Enable MFA and re-authenticate Codex desktop.

Possible PR shape

1. Add a typed remote-control enrollment error for MFA-required responses.
2. Thread that error through the desktop remote-control daemon status model.
3. Update desktop Settings > Connections to display the MFA-required remediation.
4. Update iPhone setup failure handling to show the same remediation when the backend reports MFA-required enrollment.
5. Add regression coverage:
   • Enrollment returns 403 with detail: "Multi-factor authentication required".
   • Desktop status becomes blocked_mfa_required.
   • iPhone setup renders an MFA-specific failure message.
   • Generic setup failure remains the fallback for unknown errors.

Expected outcome

Users who hit this after password changes or account security changes should get an actionable MFA message instead of cycling through app reinstalls, desktop resets, and repeated pairing attempts.

[github-actions]

Potential duplicates detected. Please review them and close your issue if it is a duplicate.

• Surface remote-control MFA enrollment errors in codex remote-control start #24046
• Remote control stays offline after switching Business accounts; enrollment fails with MFA required #23977

Powered by Codex Action