Troubleshooting — Agent Chat

If your agent isn’t connecting to your workspace, follow these steps in order. Each step checks one layer of the connection.

Quick Diagnostic

Open Agent Chat in the dashboard and click Diagnose. It runs automated checks on:

Agent Connection — is any agent connected to this workspace?
Workspace Token — does the token exist and has it ever been used?
MCP Servers — are any MCP servers configured in the workspace?
Connection Log — recent connection attempts (successes and failures)
Gateway Relay — can the dashboard reach the agent via WebSocket?

Each failed step shows a fix command you can copy and run.

Step-by-Step Debug

Verify the gateway is installed
Terminal window
```
aerostack-gateway --version
```
If you get command not found, install it:
Terminal window
```
npm install -g @aerostack/gateway
```
Run the connection check
Terminal window
```
AEROSTACK_WORKSPACE_URL="https://mcp.aerostack.dev/ws/your-workspace" \
AEROSTACK_TOKEN="mwt_your_token_here" \
aerostack-gateway --check
```
This tests 5 things:
- Workspace URL is reachable
- Token is valid
- Workspace exists
- Tools are available
- Dashboard registration works
If any step fails, the output tells you exactly what to fix.
Check your MCP config

Make sure your config uses "command": "aerostack-gateway" (not npx):
```
{
  "mcpServers": {
    "aerostack": {
      "command": "aerostack-gateway",
      "env": {
        "AEROSTACK_WORKSPACE_URL": "https://mcp.aerostack.dev/ws/your-workspace",
        "AEROSTACK_TOKEN": "mwt_your_token_here"
      }
    }
  }
}
```
Common mistake: Using npx instead of aerostack-gateway. The npx approach downloads the package on every startup, which can fail on servers, VMs, or slow networks. Always use the globally installed binary.
Verify your token
1. Go to Workspaces in the dashboard
2. Select your workspace
3. Click Tokens
4. Check the token status — it should show “last used: …” if it has connected before
5. If the token says “never used”, copy it again and update your MCP config
Check if the gateway process is running

For OpenClaw:
Terminal window
```
# Is the gateway running?
openclaw gateway status

# Check MCP server config
openclaw mcp show aerostack

# Restart the gateway
openclaw gateway restart
```
For Claude Code / Claude Desktop:

The gateway process starts automatically when your AI tool starts. Restart the AI tool to restart the gateway.
Check the workspace
1. Does the workspace have MCP servers added? Go to Workspaces → MCP Servers
2. Built-in tools (Local Guardian, Chat) are always available even without MCP servers
3. Make sure the workspace URL matches exactly: https://mcp.aerostack.dev/ws/your-workspace-slug

Common Issues

Problem	Solution
`aerostack-gateway: command not found`	Run `npm install -g @aerostack/gateway`
”Token invalid” in `--check`	Regenerate token: Dashboard → Workspace → Tokens
”0 workspace tools”	Add MCP servers to your workspace. Built-in tools are always available
Dashboard shows “No agents”	Run `aerostack-gateway --check` to verify. Wait 2 minutes for heartbeat
Agent appears then disappears	Check network stability. The gateway auto-reconnects on disconnect
Duplicate agents in sidebar	Update to latest: `npm install -g @aerostack/gateway@latest`
OpenClaw: tools not loading	Send any message via chat to trigger tool loading. From v0.17.5+, this happens automatically
`McpError: Connection closed`	Update the gateway: `npm install -g @aerostack/gateway@latest`

Debug Logs

Enable debug logging to see detailed connection info:

AEROSTACK_LOG_LEVEL=debug aerostack-gateway --check

Or set it in your MCP config:

{
  "mcpServers": {
    "aerostack": {
      "command": "aerostack-gateway",
      "env": {
        "AEROSTACK_WORKSPACE_URL": "https://mcp.aerostack.dev/ws/your-workspace",
        "AEROSTACK_TOKEN": "mwt_your_token_here",
        "AEROSTACK_LOG_LEVEL": "debug"
      }
    }
  }
}

Still Stuck?

Run aerostack-gateway --check and share the output
Check the Diagnose results in Agent Chat
Look at Activity Monitor in the dashboard for recent errors
Open an issue with your --check output