Troubleshooting

Troubleshooting

The extra is missing

Open OpenSwap from Applications. If it should start at login, check Settings › General › This Mac › Open at login; a warning under it with Open Login Items means macOS refused to start it, so allow OpenSwap there.

From a terminal:

openswap menubar --service-status
launchctl kickstart -k "gui/$(id -u)/com.opensoft.openswap.menubar"

If it is not installed: openswap menubar --install-service.

Logs: ~/Library/Logs/com.opensoft.openswap.menubar.{log,err}.

Extra is light while the Mac is Dark

The popover follows System Settings → Appearance, not the menu bar wallpaper tint. Restart the extra after changing appearance if it looks stuck.

Extra shows only the OpenSoft mark

Settings → General → Menu bar → Show may be Logo only. Pick Claude, ChatGPT, or Both. There is no asterisk setting.

ChatGPT card will not switch

Desktop switching is off by default. Settings → Automation → Enable ChatGPT switching, then wait for Switch and open ChatGPT or Restart ChatGPT. A click before that offers Enable in Settings.

This ChatGPT build isn’t compatible with switching means that build failed the compatibility check. ChatGPT couldn’t be verified means the signature check failed. API-key cards cannot switch the app. Details: ChatGPT.

Widget is empty or missing

1. Extra must be running (openswap menubar --service-status).
2. openswap widget --status should show the app present and the host loaded.
3. Add it from Edit Widgets; search for OpenSwap. Nothing can place it for you.
4. Snapshot file: ~/Library/Application Support/OpenSwap/widget-snapshot.json.
5. Register it again: openswap widget --install. The app needs nothing else; a source install rebuilds it, which needs Xcode.

Moved from a source install to the app, or the Apple team changed? Remove the old widget and add it again.

openswap add / switch errors

• Do not /logout before openswap add.
• Expired token: log into that account in Claude Code, then openswap add again (or openswap add --slot N).
• Quarantined account: same as expired token, or openswap import a known-good export.
• “Same credential” warning on two slots: one backup may have overwritten the other. Same email with different orgs is normal; aliases help.

An API key card says revoked, out of credit, or at its spend limit

OpenSwap checks linked API keys every 30 minutes (every 5 after a failure) and stops using one that fails:

• API key revoked or invalid: make a new key in the Claude Console and add it again with openswap add-token … --for N.
• API key out of credit: buy credit in the Console. The API credit included with Max and Team plans does not cover Claude Code.
• API key at its spend limit: raise the workspace’s spend limit in the Console, or wait for the month to reset.

The card clears on the next check once the key works. Claude Code on a key fails with “Credit balance too low” when the organization holds only the included credit. API credit fallback.

An older openswap keeps running

After moving from a source install, a uv openswap earlier on your PATH can still answer. The uv copy refuses setup, upgrade and widget --install and names the app’s command. Run $(brew --prefix)/bin/openswap setup once, then uv tool uninstall openswap.

Switch did not apply in Claude Code

Wait ~30 seconds on macOS (Keychain cache), or restart Claude Code / reopen the VS Code extension tab.

Auto-switch is not picking the account that resets soon

Default strategy is best: stay until ~90% of the 5-hour or 7-day window that is closer to the limit. The countdown you see (2 hours on a 7d row) is ignored until then.

Use consume-first (soonest weekly reset):

openswap config set autoswitch.strategy consume-first

Or Settings → Automation → Choose the next account by → Burn weekly first. Restart the extra (or the openswap auto process) so it reloads settings.

See Auto-switch.

Kickoff did not run

• Enabled, and local time is at or after the scheduled clock
• At most once per local day
• Skips API-key accounts and accounts whose 5-hour window is still open
• Failed pings retry after 5 minutes

Need a clean slate

openswap uninstall --zap

Or More… › Uninstall OpenSwap… with Also delete saved accounts, settings and logs ticked. That deletes saved accounts and settings; Claude Code itself stays logged in. If something fails, the log ~/Library/Logs/com.opensoft.openswap.uninstall.log says what. A source install ends by naming uv tool uninstall openswap; ~/.openswap is yours to delete.