ChatGPT / Codex desktop on macOS: Appshot fails with `Unable to attach appshot` (`captureNotFound` then `update_poll_failed`) when `~/.codex` is a symlink

Context

Source(s): https://www.v2ex.com/t/1229981 (the original poster's own fix write-up; they report three consecutive successful Appshots after the fix); upstream: https://github.com/openai/codex/issues/25269 (an earlier commenter on 2026-07-14 reported the same fix worked, and the V2EX poster posted their confirmation there as comment 5084912745); same confirmation also posted on https://github.com/openai/codex/issues/29772 Status: reported working by source, not reproduced by us (workaround only; root fix not confirmed).

Problem

In the ChatGPT desktop app for macOS, pressing the Appshot hotkey hangs briefly and then shows "Unable to attach appshot" (Chinese UI: 无法添加智能快照), no matter which app is captured (the poster tried Finder and Edge). The poster checked Screen & System Audio Recording, Accessibility and Full Disk Access for both ChatGPT and Codex Computer Use, restarted, re-authorized and switched target apps; nothing helped. The desktop logs showed the capture starting successfully and then the follow-up query failing with captureNotFound.

Error (redacted / normalized)

Unable to attach appshot
无法添加智能快照

captureNotFound
update_poll_failed
hadAxText=false
hadScreenshot=false

next-capture-update Apple Event failed
Codex Computer Use Apple Event error -10005: captureNotFound(requestID: "...")
capture settled failureReason=update_poll_failed hadAxText=false hadScreenshot=false status=failed

Applies when

ChatGPT desktop app for macOS (after the Codex desktop app was merged into it, July 2026) and Codex Desktop for macOS (the upstream issue was filed against Codex Desktop 26.527.31326 on macOS 26.5; later reports on 26.609.41114, 26.623.70822 and ChatGPT desktop 26.707.31428). Only applies when the root ~/.codex path is a symbolic link to another location.

Confirm it is this problem

1. Run test -L "$HOME/.codex" && echo symlink → expect: it prints symlink. If nothing is printed, ~/.codex is a real directory and this card does not apply.
2. Trigger an Appshot, then search the newest log under ~/Library/Logs/com.openai.codex/ for captureNotFound → expect: captureNotFound followed by update_poll_failed with hadAxText=false and hadScreenshot=false.

Not this when / boundary

If ~/.codex is already a real directory, this is a different failure: one upstream reporter did a clean reinstall without restoring old state and still got captureNotFound, pointing at a helper multi-process or IPC problem. If the Computer Use helper crashes at launch (for example DYLD Symbol missing: _swift_task_addPriorityEscalationHandler reported on macOS 15.7.7) or the logs show a helper crash or missing library instead of captureNotFound, the poster says that is another class of problem. A report on Windows (26.930.31730) has no diagnosis and is not covered.

Root cause

Not confirmed by OpenAI. The poster's inference from the before/after behaviour: when ~/.codex is a symlink, ChatGPT / Computer Use resolves or registers the Computer Use helper under two different paths, so the capture is started by one helper instance and the result is polled from another, which has no record of the request and answers captureNotFound. The upstream commenter's write-up says the same and also labels it an inference.

Variables

<old_target>: the directory that ~/.codex currently points to (printed by readlink). LSREGISTER: /System/Library/Frameworks/CoreServices.framework/Versions/A/Frameworks/LaunchServices.framework/Versions/A/Support/lsregister.

Fix

1. Fully quit ChatGPT / Codex and its Computer Use helper processes (the upstream report names them SkyComputerUseService; checking with pgrep -fl SkyComputerUse is our inference).
2. Record the current target with readlink "$HOME/.codex" → expect: it prints <old_target>.
3. Make two backups: the symlink itself, and a full copy of everything under <old_target>. For example ditto "<old_target>" "<old_target>.backup" for the contents (command is our inference; the poster only says to back up the whole directory). Do not delete <old_target>.
4. Replace the symlink with a real directory at exactly $HOME/.codex, e.g. mv "$HOME/.codex" "$HOME/.codex.symlink-backup" then mkdir "$HOME/.codex" (our inference for the commands; moving a symlink moves the link, not the target).
5. Copy all of the original contents into the new directory, keeping config, login state, skills, plugins and the computer-use folder. The upstream write-up says to preserve ownership, modes, extended attributes and nested symlinks; ditto "<old_target>" "$HOME/.codex" does that on macOS (our inference). → expect: ~/.codex/computer-use/Codex Computer Use.app exists.
6. Remove the stale LaunchServices registration of the helper at the old path with "$LSREGISTER" -u "<old_target>/computer-use/Codex Computer Use.app" (repeat for every old helper path; listing them with "$LSREGISTER" -dump | grep "Codex Computer Use.app" is our inference).
7. Register the helper at the new path with "$LSREGISTER" -f "$HOME/.codex/computer-use/Codex Computer Use.app".
8. Optional check from the upstream write-up: codesign --verify --deep --strict "$HOME/.codex/computer-use/Codex Computer Use.app" passes and spctl --assess --type execute "$HOME/.codex/computer-use/Codex Computer Use.app" reports accepted; the helper's bundle identifier should be com.openai.sky.CUAService.
9. Restart ChatGPT and take an Appshot of Finder or another ordinary app. → expect: the poster reported three consecutive successful Appshots, with screenshot and window text attached.

How to verify

Check the newest log under ~/Library/Logs/com.openai.codex/ → expect: failureReason=undefined, hadAxText=true, hadScreenshot=true, status=success, and no new captureNotFound / update_poll_failed lines.

What did not work

Re-checking Screen & System Audio Recording, Accessibility and Full Disk Access, restarting, re-authorizing and switching target apps did not help the poster. In the upstream report (cause not identified there), updating or reinstalling, resetting or rebuilding the helper, and killing duplicate helper processes also did not help.

Rollback

Quit the app, move the new ~/.codex directory aside, restore the original symlink from ~/.codex.symlink-backup, and if anything is missing restore the contents from the backup copy (the upstream write-up gives the same rollback). Re-register the old helper path with "$LSREGISTER" -f if needed (our inference).

Risks

~/.codex holds config, login state, skills and plugins; a partial copy can log you out or lose settings, so keep both backups until Appshot and normal use have stayed stable (advice from the poster and the upstream write-up). If you symlinked ~/.codex on purpose (for syncing or to move it to another disk), that setup stops after this change; plan where the real directory lives first (our inference). Do not try to fix this by turning off Gatekeeper or System Integrity Protection or by stripping signatures from the helper; nothing in the sources suggests it, and it weakens the system's protection (our inference).

Verified scope

ChatGPT desktop for macOS from July 2026 and Codex Desktop for macOS 26.527.x to 26.623.x, July–Oct 2026.

Becomes obsolete when

OpenAI resolves the ~/.codex path consistently for Computer Use (issue 25269 closed with a fix, or release notes mention symlinked ~/.codex). Open question: whether current builds still fail with a symlinked ~/.codex; issue 25269 was still open when fetched on 2026-10-18.