Troubleshooting agent chat

Studio doesn't find my agentCopy Anchor Link

Apps opened from the Dock or a launcher don't get your terminal's PATH. Studio looks in the usual install folders as well (Homebrew, ~/.local/bin, npm's global folder, nvm, Volta and others), but if your agent is somewhere else:

1. In a terminal, find it with which codex or which gemini (where on Windows).
2. In Settings → Agent chat, choose that path for the agent.
3. Confirm the command Studio shows you.

Codex and Claude Agent run through adapters that need Node.js. If Node.js isn't installed, install it and press Test again.

The agent says I need to sign inCopy Anchor Link

Sign in to the agent itself, then press Test again or start a new chat:

• Codex: run codex login in a terminal, or sign in with an API key: printenv OPENAI_API_KEY | codex login --with-api-key.
• Gemini CLI: run gemini in a terminal and choose Sign in with Google.
• Claude Agent: see the next section.

Claude Agent needs an API keyCopy Anchor Link

Claude Agent doesn't start without an Anthropic API key. Save one under Anthropic API key in Settings → Agent chat, or in the setup view in the panel. A key set only in your shell profile isn't seen when you open Studio from the Dock. Studio uses an API key for Claude Agent and never a claude.ai or Claude Code sign-in. See Claude Agent.

The agent doesn't have Studio's toolsCopy Anchor Link

Check the line at the top of the chat.

• It says the tools are gone, with Reconnect. Studio's MCP server stopped or restarted while the chat was open, for example after Stop agents, a new token or a new port. Press Reconnect. The agent starts a new session and doesn't see the earlier messages.
• It offers Start it and reconnect. The server couldn't start, often because its port is taken. See The MCP server started on a different port, then press the button.
• It says Studio's tools are turned off. Give the agent Studio's tools is off in Settings → Agent chat. Turn it on and start a new chat.

The agent doesn't use Studio's toolsCopy Anchor Link

If the agent answers from general knowledge, or reaches for curl:

• Check that Use Spec0 instructions is on in Settings → Agent chat. If Settings says you've edited the instructions, press Restore Studio's version.
• Ask for it directly: "Use Studio's tools to send this request."
• Open the Studio context chip on your first message to check what the agent was told is open.

If an agent keeps ignoring the tools, please tell us. See Contributing.

A tool call failedCopy Anchor Link

Each failed tool call shows its error in the card. Studio's errors say what was missing, for example which argument to pass. Usually the agent reads the error and tries again. If it doesn't, tell it what the error said.

The agent says its request was refusedCopy Anchor Link

Studio refuses a request when:

• you pressed Don't allow, or nobody answered within five minutes
• the host is under Blocked hosts in the MCP tab
• agents sent more requests this minute than Requests a minute allows
• you pressed Stop agents

The agent's card shows which. See Approving what agents do.

The agent can't change a collectionCopy Anchor Link

Agents can change only the drafts they created. Once you keep a draft, or for a collection you made, the agent can read and run it, or copy it into a new draft.

The agent stopped unexpectedlyCopy Anchor Link

The chat shows the agent's exit code and the last lines it wrote. The console has the same entry. Start a new chat; if it happens again, please open an issue with those lines.