Troubleshooting

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

aerostack-gateway --version

If you get command not found, install it:

npm install -g @aerostack/gateway

Run the connection check

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

Go to Workspaces in the dashboard
Select your workspace
Click Tokens
Check the token status — it should show “last used: …” if it has connected before
If the token says “never used”, copy it again and update your MCP config

Check if the gateway process is running

For OpenClaw:

# 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

Does the workspace have MCP servers added? Go to Workspaces → MCP Servers
Built-in tools (Local Guardian, Chat) are always available even without MCP servers
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

Token Savings Agent Automation