Find the symptom below. Run project-specific checks inside the affected folder;
use the repository directory for commands starting with ./bin/.
| Task | Common problems |
|---|---|
| Helper commands and updates | Command missing, outdated helper, bundled Finder copy |
| Opening a project | Launch failures, direnv approval, missing or moved files |
| Identity labels and VS Code windows | Wrong label, Dock name, isolated window, missing extension |
| Accounts and models | Wrong account, authentication, model discovery and selection |
| Finder menus and context removal | Missing Quick Action, removal refused, extra Open With entries |
| Shared skills and validation | Skipped skills, prerequisites, configuration checks |
If the shell reports command not found: codex-home, it cannot find the helper
on PATH. From the repository directory, use the explicit path:
./bin/codex-home refresh-models umgptFor the standard installation location, make the helper available in the current terminal with:
export PATH="$HOME/Developer/codex-contexts/bin:$PATH"
command -v codex-home
codex-home helpUse your clone's actual location if different. Keep the same export in your
shell startup file for future terminals; see
shell setup. Terminals already open
when the setting was added need the export above or a restart.
If the helper instead reports unknown command: refresh-models, it was found
but that copy is older. Run type -a codex-home to locate all copies, then
update the selected checkout
or invoke the updated checkout's bin/codex-home directly.
Run these checks inside the affected project. Its .envrc may prepend
the helper bundled in Codex Project.app, so a fresh shell outside the project
can find a different version. If the resolved path is inside that app,
update the Finder integration.
The message U-M GPT Azure OpenAI identities may not set model_catalog_json
comes from an older helper. The current version permits a scope-filtered
catalog generated by refresh-models umgpt.
A project created through Finder can put this bundled copy first on PATH:
~/Applications/Codex Project.app/Contents/Resources/codex-home
Updating the repository does not update that app or its identity-specific Finder handlers. From the updated checkout, run:
./bin/install-macos-open-withThen retry the command or reopen the project through Finder's Open in Codex
Project action. Keep the generated model catalog. If a terminal still uses
an old command location, open a new terminal in the project and check
type -a codex-home. See updating the Finder integration.
codex-home run reads CODEX_IDENTITY from your shell. Check the
direnv shell hook, review
and approve the project's .envrc, then leave and re-enter the folder. You
can also choose a context directly with codex-home run NAME.
Run command -v codex-home to identify the helper your shell uses. Follow
Updating to refresh it and the
Finder integration; existing projects do not need to be configured again.
The project path was interpreted as a new command, usually because it was put on a separate line. Run one complete command and quote paths containing spaces:
./bin/codex-home vscode personal "/path/to/project"The helper checks code on PATH and standard macOS application paths. If
needed, open the VS Code Command Palette and run Shell Command: Install 'code'
command in PATH, or set:
export CODEX_VSCODE_CLI="/Applications/Visual Studio Code.app/Contents/Resources/app/bin/code"The launcher preserves direnv or editor failure status and diagnostics, then
prints the project path. Read the preceding diagnostic to identify an .envrc error,
missing command, or VS Code CLI failure. Commands used by .envrc must be
available in its noninteractive environment.
Project launches require direnv 2.32.2 or newer. Earlier versions incorrectly
expand shell characters such as $ in project paths. Check direnv version
and upgrade direnv if needed.
The launcher cannot obtain both CODEX_IDENTITY and CODEX_HOME from the
project's .envrc. The file may be unapproved or skipped by direnv.
Inspect the file and approval state before changing approval:
cd "/path/to/project"
direnv statusRead .envrc in a text editor and confirm its identity, home path, and other
shell commands are intended. Approve it only after that review:
direnv allow "/path/to/project"Inspect the named path, file permissions, and Codex Project's folder access
under macOS Privacy & Security. direnv allow cannot fix a file-access denial.
Once the file is readable, review it and check its approval with direnv status.
The identity name and home directory in .envrc disagree. Correct the
configuration through Set or change Codex identity…, or follow the
project recovery instructions.
If the home directory is missing, restore or configure that identity before
opening the project.
For errors from obsolete Finder or Dock entries, follow launcher recovery.
The .envrc records absolute paths to the helper's directory and the selected
identity home. If either location moves, review and update the file, then
approve the change again:
direnv allow "/path/to/project"Reinstall the Finder app after moving or updating the helper so its bundled copy is current.
Inside a configured project, launch it with codex-home run. To choose an
identity explicitly, use codex-home run NAME. The helper prints a context
banner and keeps [CODEX: NAME] in the terminal tab/window title. Plain
codex does not use this launcher label. The helper labels the terminal
title, not Codex's footer.
If the title stays hidden, allow applications to set titles in your terminal's settings. See Terminal context labels.
An ordinary VS Code window probably inherited another running instance's environment. Close that identity's window and launch through:
./bin/codex-home vscode NAME "/path/to/project"The separate --user-data-dir gives VS Code the intended identity environment.
Open a new Codex chat and integrated terminal after launch.
The icons use the standard VS Code artwork. By default, the helper uses the
installed VS Code app for every identity and keeps their user data separate.
Window titles and status-bar colors identify the context. If
CODEX_VSCODE_DOCK_LABEL=1 is set, the helper prepares named editor copies
under $CODEX_HOME/vscode-editor/; hover over a running icon to read
VS Code - NAME, including VS Code - default.
Quit the intended identity and reopen its project through the helper, Finder's
Open in Codex Project Quick Action/Service, or a file manager's
Open With > VS Code - NAME handler. For an unconfigured folder, the handler
offers setup for that identity. For a configured folder, it checks that
.envrc selects the same identity before opening it. An
already-running identity keeps its original application until it quits.
Clicking a running Dock icon focuses that editor. **After quitting, use Finder > Quick Actions > Open in Codex Project, a file manager's Open With
VS Code - NAME, or
codex-home vscode.** Do not pin or directly launch the generated editor copies under the identity home: a direct macOS launch does not supply the identity environment and isolated user-data arguments.
If the installed VS Code version changed, the helper waits until the identity
is stopped before refreshing its application copy. The existing copy is used
while the identity is running. For launch or approval errors, run the helper
from a terminal to read the diagnostic. If macOS reports Operation not permitted, inspect the named path and its privacy permissions. See
macOS Dock names.
The launcher reuses ~/.vscode/extensions when it exists. If extensions live
elsewhere, set CODEX_VSCODE_EXTENSIONS_DIR, or install the Codex extension in
that isolated VS Code instance.
Creation commands refuse to overwrite existing state. Inspect it:
./bin/codex-home show NAMEUse a new name, or inspect and update the existing home's settings manually.
The local name does not verify the browser-selected workspace. Reauthenticate only that home:
./bin/codex-home run work logout
./bin/codex-home login workCheck the intended account and workspace in the browser during sign-in, then follow the CLI or VS Code verification steps.
Check that:
- the key belongs to the intended service/project;
- it has not expired or been revoked;
- the base URL is correct;
- the service accepts bearer authentication;
- VPN or institutional-network requirements are satisfied.
Replace the stored key with codex-home set-key NAME. Never print the key to
debug it.
Model listing is a discovery convenience, not a Codex requirement. Use the
provider's exact documented model/deployment ID and test Codex directly. Some
direct Azure resources do not expose an OpenAI-style bearer-authenticated
/models route.
The gateway may support models or Chat Completions without implementing the
Responses API. Current Codex custom providers require wire_api = "responses".
Ask the provider whether the chosen route/model supports streaming Responses
and tool calls.
The active model and the picker catalog are separate. A CLI header showing
claude-sonnet-5 alongside an OpenAI-only /model menu means the configured
model loaded, but the picker still uses Codex's bundled catalog. VS Code uses
the same catalog mechanism.
Run codex-home refresh-models umgpt-low to generate the broader U-M text
catalog, or codex-home refresh-models umgpt for the GPT/o-series scope. Then
restart the CLI. In VS Code, run Developer: Reload Window and start a new
Codex chat. Repeat the refresh when gateway models change. models NAME only
prints the live IDs and does not update the picker. See
model refresh and recovery.
Do not substitute a public model name for a gateway-specific ID. Rerun:
./bin/codex-home models NAMEFor Azure, check whether model must be a deployment name and whether the
configured api-version is valid for that resource.
Install or update the Finder integration with ./bin/install-macos-open-with,
then right-click the folder itself and choose Quick Actions > Open in Codex
Project (or Services). A native Open With menu is not available for
every folder context. Check Finder > Services and enable the action in
Keyboard Shortcuts > Services if necessary. See the
Finder menu checks.
If Remove Codex context from this folder… does nothing or reports an error, choose the route that matches what happened:
- The menu cannot run the helper: Try removal from Terminal.
- Removal is refused or files are customized/missing: Remove the settings manually.
Both routes lead to a result check. Manual removal starts with a backup and preserves your project's other environment and VS Code settings.
This removes the folder's identity selection. To clean up menu entries instead, see Remove extra VS Code entries from Open With.
project-change and project-reset act only on a complete, untracked pair of
files that still exactly matches a template generated by this helper. They
refuse modified, tracked, incomplete, or symlinked setups so custom or shared
project configuration is not overwritten.
For removal, follow Remove the settings manually.
It separates disposable generated files from settings that must be preserved.
To change identities in a custom setup, edit the
Codex environment block after backing up
and reviewing the file, then review and reapprove .envrc.
Use the Open With cleanup guide to remove generated launchers while keeping your accounts, projects, and settings. Choose the relevant steps below, or uninstall the Finder integration to remove the app and Quick Action too.
Follow the one-entry cleanup steps.
Follow the all-entry cleanup steps.
Check stale registrations and older editor copies.
Use the terminal launch settings each time you open a project.
Follow the restore instructions.
share-skills found an existing target with the same name and refused to
overwrite it. Compare the local and shared versions. Keep the local skill,
or move it to a backup and rerun the command. See Sharing skills.
Install the named prerequisite and rerun the suite. The default tests require
bash, direnv, expect, and jq; see Installation.
The production helper also uses curl 7.76.0 or newer for model discovery and
Codex for login, diagnostics, and sessions. If curl rejects --fail-with-body,
check curl --version and update it.
Run:
./bin/codex-home doctor NAMEThe doctor checks more than TOML parsing, so missing subscription credentials or restricted network access may produce additional failures. It may contact Codex update services and the configured provider.
The default tests run offline. They check generated files and reject accidental
codex or live curl calls. They do not test a live provider:
./tests/test.shMaintainers can additionally run the Codex config.load checks with synthetic
credentials and endpoints:
CODEX_CONTEXTS_LIVE_TESTS=1 ./tests/test.shThat opt-in mode can make network requests. Run it only when outbound checks are acceptable; it is not required for an ordinary installation.