# Troubleshooting — Agent Chat

> Step-by-step debugging guide for Aerostack Gateway connection issues.

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:

1. **Agent Connection** — is any agent connected to this workspace?
2. **Workspace Token** — does the token exist and has it ever been used?
3. **MCP Servers** — are any MCP servers configured in the workspace?
4. **Connection Log** — recent connection attempts (successes and failures)
5. **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

1. **Verify the gateway is installed**

   ```bash
   aerostack-gateway --version
   ```

   If you get `command not found`, install it:

   ```bash
   npm install -g @aerostack/gateway
   ```

2. **Run the connection check**

   ```bash
   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.

3. **Check your MCP config**

   Make sure your config uses `"command": "aerostack-gateway"` (not `npx`):

   ```json
   {
     "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.
   

4. **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

5. **Check if the gateway process is running**

   For OpenClaw:

   ```bash
   # 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.

6. **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:

```bash
AEROSTACK_LOG_LEVEL=debug aerostack-gateway --check
```

Or set it in your MCP config:

```json
{
  "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?

1. Run `aerostack-gateway --check` and share the output
2. Check the **Diagnose** results in Agent Chat
3. Look at **Activity Monitor** in the dashboard for recent errors
4. [Open an issue](https://github.com/aerostackdev/aerostack/issues) with your `--check` output