@aerostack/gateway 0.17.2 → 0.17.3

package/README.md

@@ -116,12 +116,22 @@ Token: mwt_your_token_here  (Authorization: Bearer header)
 
 ### 3. Verify your connection
 
-Run the built-in diagnostic check to make sure everything is working:
+Run the built-in diagnostic to verify everything works end-to-end:
 
 ```bash
+# Option A: if npx works on your system
 AEROSTACK_WORKSPACE_URL="https://mcp.aerostack.dev/ws/your-workspace" \
 AEROSTACK_TOKEN="mwt_your_token_here" \
-npx @aerostack/gateway --check
+npx -y @aerostack/gateway --check
+```
+
+```bash
+# Option B: install globally first (recommended for servers/VMs)
+npm install -g @aerostack/gateway
+
+export AEROSTACK_WORKSPACE_URL="https://mcp.aerostack.dev/ws/your-workspace"
+export AEROSTACK_TOKEN="mwt_your_token_here"
+aerostack-gateway --check
 ```
 
 You should see:
@@ -141,6 +151,8 @@ You should see:
 
 If any step fails, the output tells you exactly what to fix.
 
+> **Tip:** After global install, you can simplify your MCP config to use `"command": "aerostack-gateway"` instead of `"command": "npx"` — faster startup, no network fetch.
+
 ### 4. Use it
 
 ```
@@ -152,14 +164,38 @@ Tools are namespaced as `{server}__{tool}` (e.g., `github__create_issue`, `slack
 
 ## Troubleshooting
 
+**Step-by-step debug:**
+
+```bash
+# 1. Can the gateway reach your workspace?
+aerostack-gateway --check
+
+# 2. If using OpenClaw, is the gateway running?
+openclaw gateway status
+
+# 3. Is the MCP server configured?
+openclaw mcp show aerostack
+
+# 4. Start the gateway if not running
+openclaw gateway start
+
+# 5. Run OpenClaw's built-in diagnostics
+openclaw doctor
+```
+
+**Common issues:**
+
 | Problem | Solution |
 |---------|----------|
-| `npx` hangs or fails | Run `npm install -g @aerostack/gateway` instead, then use `"command": "aerostack-gateway"` |
+| `npx` hangs or fails | Run `npm install -g @aerostack/gateway` instead, then use `"command": "aerostack-gateway"` in your MCP config |
+| `AEROSTACK_WORKSPACE_URL is required` | The env vars aren't being passed. Use `export` before running `--check`, or verify your MCP config has the `env` block |
+| `npx` error: "could not determine executable" | Install globally: `npm install -g @aerostack/gateway`, then run `aerostack-gateway --check` |
 | "Token invalid" in `--check` | Regenerate token at dashboard → Workspace → Tokens |
-| "0 tools found" | Add MCP servers to your workspace in the dashboard first |
+| "0 tools found" | Add MCP servers or functions to your workspace in the dashboard first |
 | OpenClaw: tools not showing | Send a message via Telegram or another channel to initialize the session |
 | Dashboard shows "No agents" | Run `--check` to verify, or wait 2 minutes for the heartbeat to register |
 | "Workspace unreachable" | Check the URL format: `https://mcp.aerostack.dev/ws/your-workspace` |
+| Multiple phantom agents in dashboard | Update to latest version (`npm install -g @aerostack/gateway@latest`) — fixed in 0.17.2 |
 
 ## How It Works
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aerostack/gateway",
-  "version": "0.17.2",
+  "version": "0.17.3",
   "description": "stdio-to-HTTP bridge connecting any MCP client to Aerostack Workspaces",
   "author": "Aerostack",
   "license": "MIT",