Agent not responding

Symptoms#

You send a message in the chat panel and get no response, see an error, or the chat is disabled.

"Agent starting up..." message#

Your desktop is still booting, and the chat panel's header says "Agent starting up..." until its agent is ready. The AI agent is the last service to come online.

Why this happens#

The boot process has several phases. Your desktop may show running and even have a working VNC display, but the agent is not available until it finishes initializing. A new desktop is usually working, its agent included, about 2 minutes after you create it, well after VNC and the terminal are up.

The initialization process differs by agent type, but every agent (OpenClaw, Claude Code, Hermes Agent, Codex, and Grok) needs to fully start before chat is available.

What to try#

Wait. This is normal until about 2 minutes after you create the desktop. The chat panel enables automatically once the agent is ready. At the 3-minute mark the toolbar may show "Boot is taking longer than expected." That message alone is not a reason to restart. If the agent is still not ready 4 minutes after creation, stop and restart the desktop.

A Grok desktop is the exception: it waits for you to sign in with your xAI account, and its chat shows a "Sign in to Grok" card instead of this message. Sign in there and do not restart: a restart brings the same card back.

"Agent did not start" message#

Your desktop is running, but its agent did not finish starting, so it cannot answer you. The toolbar and the chat panel say "Agent did not start", and a card above the chat's message box names the cause.

What the card says#

• "No account connected": the agent has no account to run with. Connect one with the card's button, or in Settings.
• "No API key": the desktop runs on your own provider API key and has none. A key is given when a desktop is created, so create a new desktop with your key.
• "Account refused": the provider refused the account the agent started with. Reconnect it, or switch to another.
• "API key refused": the provider refused the API key the desktop was created with. A key cannot be changed on a running desktop, so create a new desktop with a valid key.
• "Account quota reached": the account has no requests left with its provider. Switch to another account, or start the desktop again once the quota resets.
• "API key quota reached": the API key has no requests left with its provider. Start the desktop again once the quota resets, or create a new desktop with another key.
• "xAI quota reached": the xAI account the desktop signs in with has no requests left. Start the desktop again once the quota resets, or create a new desktop and sign in there with another xAI account.
• "Agent could not start": the text under it says which case this is. If your account is fine and the agent could not reach a model, the fault is on our side. If the cause cannot be identified from here, check the account or API key your desktop runs on, with your provider; on a Grok desktop, start the desktop again, and create a new desktop if the card comes back. If the page does not recognise the reason, reload the page.

What to try#

1. Do what the list above says for your card. Where the card shows a button, use it.
2. If the card says the fault is on our side, or the same card comes back after you have acted on it, email contact@spinestudio.dev.

An error in place of the reply#

The agent started, but something failed while it worked on your message. The chat shows what went wrong, in red, where the reply would be. For example:

• "The agent on this desktop can't connect to its AI provider, and the API key is likely missing, wrong or expired. Reconnect the account in Settings, or create a new desktop with a valid key."
• "The AI provider has no credits. Please add credits to your API key or contact your admin."

Do what the message says. If the desktop runs on an account you connected, reconnect that account in Settings. A provider API key given to a desktop when it is created cannot be changed on a running one, which is why a wrong key there means a new desktop.

When the error tells you to check before sending the message again, do that first. The agent had already started on your message, so part of the work may be done, and sending it again could run it twice.

Chat messages get no response#

You send a message, it shows up in the chat, but nothing comes back. No error, no response.

Possible causes#

If you sent many messages quickly, the provider may be rate-limiting you. This is common with free-tier API keys.

Some tasks, especially file operations, web browsing, or complex reasoning, can take 30 seconds or more. The agent may still be working.

The agent process may also have crashed silently after starting. This can happen if the VM runs out of memory.

What to try#

1. Wait 30 seconds. The agent may still be processing.
2. Send a short message like "hello" to check if the agent responds.
3. Open the terminal panel and look for error output from the agent process.
4. Stop and start the desktop to get a fresh agent process.

Troubleshooting by agent type#

OpenClaw#

• If the agent behaves unexpectedly, the soul file may contain instructions that conflict with your request. You can review and edit it from the terminal.
• Verify your API key is valid and has credits on your provider's dashboard.

Claude Code#

• If the agent is unresponsive, check the Claude account or Anthropic API key it runs on.
• Claude Code runs on Anthropic only. It does not work with OpenAI or OpenRouter.

Hermes Agent#

• If the agent is unresponsive, check that your API key is valid and has credits.
• Hermes Agent is self-improving and may take longer on initial tasks as it builds context.

Codex#

• If the agent is unresponsive, check the ChatGPT account or OpenAI API key it runs on.
• When its ChatGPT account runs out of quota, the chat shows "Codex account out of quota". "Switch ChatGPT account" moves the desktop to another account; you can also wait for the quota to reset.

Grok#

• A new Grok desktop asks you to sign in before it can answer: start the sign-in from the chat's "Sign in to Grok" card and approve it with your xAI account.

Avoiding agent problems#

• Test your API key on the provider's website before using it in SpineOS
• Keep your key funded. Most agent failures come down to expired credits.
• Start with a known-good model (Claude Sonnet, GPT-4o) before trying specialized ones
• Give the desktop about 2 minutes after creation before expecting chat to work