Issue Station
Sign In
Tools hereToolbox

codex - 💡(How to fix) Fix Surface remote-control MFA enrollment errors in `codex remote-control start`

Official PRs (…)
ON THIS PAGE

Recommended Tools

×6

Utilities matched from this issue’s tags and category — try them while you read without losing context.

GitHub issue graph ai analysis

Paste a GitHub issue URL. We fetch that issue, discover linked issues from bodies/comments/timeline, collect linked pull requests, and produce a structured English report.

The report is written in English Markdown for sharing and archival.

Helpful · Quick feedback

Loading…

Error Message

When codex remote-control start fails because the remote-control enrollment endpoint requires MFA, the actionable HTTP error can be hidden behind daemon/readiness or generic remote-control connection errors. The useful error was only visible after inspecting app-server logs/state: codex remote-control start should include the last remote-control enrollment/connect error when the app-server reports remote-control status errored, especially HTTP enrollment failures from: https://github.com/kimdwkimdw/codex/tree/feature/remote-control-enrollment-error

  • stores the last remote-control connection/enrollment error while status is errored;
  • clears it on non-error states;
  • makes codex remote-control start print that error directly;

Root Cause

When codex remote-control start fails because the remote-control enrollment endpoint requires MFA, the actionable HTTP error can be hidden behind daemon/readiness or generic remote-control connection errors.

Code Example

{
  "schemaVersion": 1,
  "overallStatus": "ok",
  "codexVersion": "0.133.0",
  "checks": {
    "app_server.status": {
      "status": "ok",
      "summary": "background server is running"
    },
    "auth.credentials": {
      "status": "ok",
      "summary": "auth is configured",
      "details": {
        "stored API key": "false",
        "stored ChatGPT tokens": "true",
        "stored auth mode": "chatgpt"
      }
    },
    "config.load": {
      "status": "ok",
      "summary": "config loaded",
      "details": {
        "model": "gpt-5.5",
        "model provider": "openai"
      }
    },
    "installation": {
      "status": "ok",
      "summary": "installation looks consistent",
      "details": {
        "install context": "standalone",
        "platform": "linux-x86_64",
        "version": "0.133.0"
      }
    },
    "network.provider_reachability": {
      "status": "ok",
      "summary": "active provider endpoints are reachable over HTTP",
      "details": {
        "ChatGPT base URL": "https://chatgpt.com/backend-api/ reachable (HTTP 404)",
        "reachability mode": "ChatGPT auth"
      }
    },
    "network.websocket_reachability": {
      "status": "ok",
      "summary": "Responses WebSocket handshake succeeded",
      "details": {
        "auth mode": "chatgpt",
        "handshake result": "HTTP 101 Switching Protocols",
        "supports websockets": "true"
      }
    },
    "runtime.provenance": {
      "status": "ok",
      "summary": "running standalone on linux-x86_64",
      "details": {
        "commit": "unknown",
        "install method": "standalone",
        "platform": "linux-x86_64",
        "version": "0.133.0"
      }
    },
    "terminal.env": {
      "status": "ok",
      "summary": "terminal metadata was detected",
      "details": {
        "terminal": "WezTerm",
        "terminal version": "20240203-110809-5046fc22",
        "multiplexer": "tmux 3.4"
      }
    },
    "updates.status": {
      "status": "ok",
      "summary": "update configuration is locally consistent",
      "details": {
        "latest version": "0.133.0",
        "latest version status": "current version is not older"
      }
    }
  }
}

---

remote control server enrollment failed at https://chatgpt.com/backend-api/wham/remote/control/server/enroll: HTTP 403 Forbidden ... body: {"detail":"Multi-factor authentication required"}

---

remote control server enrollment failed at
https://chatgpt.com/backend-api/wham/remote/control/server/enroll
HTTP 403 Forbidden
{"detail":"Multi-factor authentication required"}

---

codex remote-control start

---

https://chatgpt.com/backend-api/wham/remote/control/server/enroll
RAW_BUFFERClick to expand / collapse

What version of Codex CLI is running?

codex-cli 0.133.0

What subscription do you have?

ChatGPT auth was used. The exact subscription tier is not available from this environment.

Which model were you using?

N/A. This happens while running codex remote-control start, before a model is used. The local config default model was gpt-5.5.

What platform is your computer?

Linux 6.8.0-78-generic x86_64 x86_64

What terminal emulator and version are you using (if applicable)?

WezTerm 20240203-110809-5046fc22, running through tmux 3.4 over SSH.

Codex doctor report

{
  "schemaVersion": 1,
  "overallStatus": "ok",
  "codexVersion": "0.133.0",
  "checks": {
    "app_server.status": {
      "status": "ok",
      "summary": "background server is running"
    },
    "auth.credentials": {
      "status": "ok",
      "summary": "auth is configured",
      "details": {
        "stored API key": "false",
        "stored ChatGPT tokens": "true",
        "stored auth mode": "chatgpt"
      }
    },
    "config.load": {
      "status": "ok",
      "summary": "config loaded",
      "details": {
        "model": "gpt-5.5",
        "model provider": "openai"
      }
    },
    "installation": {
      "status": "ok",
      "summary": "installation looks consistent",
      "details": {
        "install context": "standalone",
        "platform": "linux-x86_64",
        "version": "0.133.0"
      }
    },
    "network.provider_reachability": {
      "status": "ok",
      "summary": "active provider endpoints are reachable over HTTP",
      "details": {
        "ChatGPT base URL": "https://chatgpt.com/backend-api/ reachable (HTTP 404)",
        "reachability mode": "ChatGPT auth"
      }
    },
    "network.websocket_reachability": {
      "status": "ok",
      "summary": "Responses WebSocket handshake succeeded",
      "details": {
        "auth mode": "chatgpt",
        "handshake result": "HTTP 101 Switching Protocols",
        "supports websockets": "true"
      }
    },
    "runtime.provenance": {
      "status": "ok",
      "summary": "running standalone on linux-x86_64",
      "details": {
        "commit": "unknown",
        "install method": "standalone",
        "platform": "linux-x86_64",
        "version": "0.133.0"
      }
    },
    "terminal.env": {
      "status": "ok",
      "summary": "terminal metadata was detected",
      "details": {
        "terminal": "WezTerm",
        "terminal version": "20240203-110809-5046fc22",
        "multiplexer": "tmux 3.4"
      }
    },
    "updates.status": {
      "status": "ok",
      "summary": "update configuration is locally consistent",
      "details": {
        "latest version": "0.133.0",
        "latest version status": "current version is not older"
      }
    }
  }
}

What issue are you seeing?

When codex remote-control start fails because the remote-control enrollment endpoint requires MFA, the actionable HTTP error can be hidden behind daemon/readiness or generic remote-control connection errors.

The useful error was only visible after inspecting app-server logs/state:

remote control server enrollment failed at https://chatgpt.com/backend-api/wham/remote/control/server/enroll: HTTP 403 Forbidden ... body: {"detail":"Multi-factor authentication required"}

At the CLI level, this led debugging toward local daemon/socket/state issues instead of the real fix: complete ChatGPT device auth / MFA.

The CLI should surface a concise enrollment failure such as:

remote control server enrollment failed at
https://chatgpt.com/backend-api/wham/remote/control/server/enroll
HTTP 403 Forbidden
{"detail":"Multi-factor authentication required"}

What steps can reproduce the bug?

  1. Use Codex CLI 0.133.0 with ChatGPT auth.

  2. Have a ChatGPT account/session where remote-control server enrollment requires MFA, or where the current auth token has not completed the required MFA/device-auth path.

  3. Run:

    codex remote-control start

  4. Observe that the command does not clearly show the enrollment endpoint HTTP response/body that explains the failure.

What is the expected behavior?

codex remote-control start should include the last remote-control enrollment/connect error when the app-server reports remote-control status errored, especially HTTP enrollment failures from:

https://chatgpt.com/backend-api/wham/remote/control/server/enroll

For the MFA case, the user should immediately see HTTP 403 Forbidden and {"detail":"Multi-factor authentication required"} so they know to complete device-auth/MFA instead of debugging sockets or restarting the daemon.

Additional information

I prepared a reference implementation branch here:

https://github.com/kimdwkimdw/codex/tree/feature/remote-control-enrollment-error

Reference commit:

https://github.com/kimdwkimdw/codex/commit/6e83d1765d8d3a53812b1164c400e400ec7e3dae

The reference change keeps the scope small:

  • adds lastError to the remote-control status payload;
  • stores the last remote-control connection/enrollment error while status is errored;
  • clears it on non-error states;
  • makes codex remote-control start print that error directly;
  • formats enrollment HTTP failures as a short human-readable block.

This would have made the MFA cause easy to identify.

Vote matrix · Quick signals

Works
Did the solution work? Tap to confirm.
Easy Fix
Was it a quick fix?
Time Saver
Did it save you time?
Blocking
Was it severely blocking?
Common Issue
Are others likely hitting this too?
Flaky / Intermittent
Is it intermittent?
Verified / Reproducible
Can you reproduce it reliably?
Loading…

Still need to ship something?

×6

Another batch ranked right after the header list — different links, same matching logic.

Back to top recommendations

TRENDING

codex - 💡(How to fix) Fix Surface remote-control MFA enrollment errors in `codex remote-control start`