codex - 💡(How to fix) Fix Codex Desktop keeps stale app connector link after reauth-required 401 until codex_apps cache is cleared

Summary

Codex Desktop on macOS kept using a stale app connector link after a Linear connector started returning 401 Reauthentication required. Restarting Codex and removing/re-adding the Linear plugin did not fix it. Moving aside the local Codex app/tool discovery cache forced regeneration and made the connector work again.

Environment

• Codex Doctor: v0.134.0
• Platform: macOS arm64
• Connector: Linear installed as a Codex Desktop app/plugin connector
• Linear was not configured as a CLI MCP server, so codex mcp list did not show Linear

Symptoms

A read-only Linear connector tool call failed with:

401: "Server returned 401: 'Reauthentication required'"

Restarting Codex Desktop did not help. Removing and re-adding the Linear plugin did not help.

What Fixed It

Moving aside the local Codex app/tool discovery cache caused Codex to regenerate connector tool metadata. After that, the same read-only Linear tool call succeeded.

The relevant local cache files were under:

~/.codex/cache/codex_apps_tools/*.json
~/.codex/cache/codex_app_directory/*.json

Before cache regeneration, the Linear tool metadata referenced one opaque link_* connector link. After cache regeneration, it referenced a different opaque link_* connector link, and calls succeeded.

Expected Behavior

When an app connector returns 401 Reauthentication required, Codex Desktop should either:

• invalidate/regenerate the cached connector tool metadata automatically,
• expose a reconnect/reauth action in the plugin/app UI, or
• clear the relevant app connector cache when the plugin is removed/re-added.

Actual Behavior

The stale connector link survived:

• full Codex Desktop restart,
• Linear plugin remove/re-add,
• and retrying the same connector call.

The only working recovery was manually clearing/moving aside the app/tool discovery cache.

Workaround

Move aside the app/tool discovery cache and restart/retry Codex Desktop:

mkdir -p ~/.codex/cache/app-connector-cache-backup
mv ~/.codex/cache/codex_apps_tools/*.json ~/.codex/cache/app-connector-cache-backup/ 2>/dev/null || true
mv ~/.codex/cache/codex_app_directory/*.json ~/.codex/cache/app-connector-cache-backup/ 2>/dev/null || true

This appears to force Codex to fetch fresh connector metadata.

Notes

This may be related to broader Desktop/app connector auth-refresh behavior, but the specific issue here is that stale codex_apps discovery metadata retained an invalid connector link even after restart and plugin reinstall.