Help · Agents
Troubleshooting agents
| On screen / the agent says | Cause | Fix |
|---|---|---|
| Row stays grey, “listening” | The agent is still asking questions, or never ran the check | Answer the agent; ask it to “run the AtControl setup check” |
Orange: refused, opened by an app · journal: deeplink_sender_refused |
A deeplink opened by a browser, Mail, Messages, a chat app or Shortcuts’ “Open URL” while Protection is “Refuse links opened by apps”; the caller is not told | Expected if you did not open it yourself; send commands with open from a command line, or through Shortcuts |
| Orange: authorization required | A deeplink without the capability token, or with an old one, while Protection is “Require a token”; the caller is not told, only the journal shows it | Copy the token from Settings ▸ Agents ▸ Access into the link’s &token=… |
Agent: missing_wrappers |
Shortcuts not installed | Settings ▸ Agents ▸ Add to Shortcuts… |
Orange: surface disabled · agent: agent_surface_disabled |
That way in is switched off | Settings ▸ Agents, switch it on |
Agent: shortcuts_unavailable / cannot run shortcuts |
The agent’s own sandbox blocks it | Allow the agent to run shortcuts (its permission settings), or run it with fewer restrictions |
Agent: wrapper_outdated: true · Settings ▸ Agents ▸ Setup: “These shortcuts are out of date” |
Old shortcuts from an earlier AtControl (for example ones that still pass a token) | Delete them in Shortcuts, install again |
| A parameter “never arrives”; an End ends the wrong session | A second copy of AtControl is registered (another build, or one in the Trash) — Shortcuts resolves actions against that copy’s catalog and drops parameters it does not know | Leave exactly one copy; empty the Trash |
Mac did not sleep or shut down, and the agent reports call_failed, shortcuts_unavailable or a timeout at the end |
macOS asked whether the Sleep or Shutdown shortcut may run, and nobody chose Always Allow — often because nobody was at the Mac | At the Mac, ask your agent to go through the AtControl shortcuts (setup, step 5) and choose Always Allow for each |
| A macOS question about an AtControl shortcut appears | The first run of that shortcut from a program; Allow Once asks every time | Choose Always Allow |
The agent’s walkthrough lists a shortcut as call_failed |
You chose Don’t Allow, or nobody answered in time | Run the walkthrough again and choose Always Allow; if the question does not come back, reset that shortcut’s permission in its details in the Shortcuts app first |
Mac did not sleep, agent said deferred |
Another agent is still working | Expected; it sleeps after the last one |
Agent said simulated |
Service Mode is on (developer builds) | Turn Service Mode off |
Agent: ambiguous_session |
An ending command without an id while several sessions run | Use the session id or the request id |
Agent: conflicting_identities |
Both id and request_id in one command |
Send one |
Codex: nothing appears in AtControl during a turn although the hook is in ~/.codex/hooks.json |
Codex has not been told to trust the hook yet — it skips new or changed hooks | In Codex, /hooks, trust the AtControl entries |
| The agent says a hook “could not keep the Mac awake” | The hook ran, but AtControl refused or could not be reached | See ~/.atcontrol/hooks/hook.log; the causes are the rows above |
Agent: no_hook_turn |
The agent tried to record sleep for a turn no hook started (the hook is missing or not trusted) | Add or trust the hook, or let the agent register and finish on its own |
Agent: shortcuts_unavailable in Codex |
Codex runs the agent’s commands in a sandbox that cannot reach Shortcuts | Add the MCP server (setup); hooks run outside the sandbox and need nothing more |
| An agent that crashed still holds the Mac awake | It asked for nothing afterwards, so it has no time limit | End it from the agent grid (End session) or the menu bar; with a hook, the next prompt in that conversation ends it |
| “Copy for Your Agent” is disabled | macOS runs the app from a temporary copy | Move AtControl to Applications and relaunch |
| The app comes forward at every agent command | Bring AtControl to the front is set to For every command | Settings ▸ Agents ▸ Behavior — choose For sleep and shutdown |