Skip to main content

Local Development with OpenClaw

This guide covers running MosBot API locally while connecting to OpenClaw services deployed in Kubernetes, using kubectl port-forward.

When you need this​

  • You're developing MosBot locally but OpenClaw runs in a Kubernetes cluster
  • You want to test agent monitoring, workspace browsing, or skills management
  • You need to verify OpenClaw integration without a full local OpenClaw setup

Prerequisites​

  • OpenClaw deployed in a Kubernetes cluster
  • kubectl configured to access the cluster (kubectl get pods works)
  • MosBot API running locally (via npm run dev or Docker)

Step 1: Get the tokens​

Retrieve the OpenClaw service tokens from your Kubernetes secrets. Adjust the namespace and secret names to match your deployment:

# Workspace service token
kubectl get secret -n openclaw-personal openclaw-secrets \
  -o jsonpath='{.data.WORKSPACE_SERVICE_TOKEN}' | base64 -d && echo

# Gateway token (if used)
kubectl get secret -n openclaw-personal openclaw-secrets \
  -o jsonpath='{.data.OPENCLAW_GATEWAY_TOKEN}' | base64 -d && echo

Step 2: Port-forward the services​

Open two terminal windows and run one port-forward in each:

# Terminal 1: Workspace service
kubectl port-forward -n openclaw-personal svc/openclaw-workspace 8080:8080

# Terminal 2: Gateway service (if used)
kubectl port-forward -n openclaw-personal svc/openclaw 18789:18789

Keep both terminals open while developing. If a port-forward drops, restart it.

Step 3: Configure .env​

If running MosBot API natively (on your host)​

OPENCLAW_WORKSPACE_URL=http://localhost:8080
OPENCLAW_WORKSPACE_TOKEN=<workspace-token-from-step-1>
OPENCLAW_GATEWAY_URL=http://localhost:18789
OPENCLAW_GATEWAY_TOKEN=<gateway-token-from-step-1>

If running MosBot API in Docker​

Use host.docker.internal to reach the port-forwarded services from inside the container:

OPENCLAW_WORKSPACE_URL=http://host.docker.internal:8080
OPENCLAW_WORKSPACE_TOKEN=<workspace-token-from-step-1>
OPENCLAW_GATEWAY_URL=http://host.docker.internal:18789
OPENCLAW_GATEWAY_TOKEN=<gateway-token-from-step-1>

Step 4: Restart the API​

# Native
npm run dev

# Docker
docker compose restart api

Step 5: Verify​

Check agent discovery​

curl http://localhost:3000/api/v1/openclaw/agents

You should see a JSON array of agents from your openclaw.json.

Check workspace service directly​

curl -H "Authorization: Bearer <workspace-token>" http://localhost:8080/status

Check workspace via MosBot API​

TOKEN=$(curl -s -X POST http://localhost:3000/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"admin@example.com","password":"your-password"}' \
  | jq -r '.token')

curl -H "Authorization: Bearer $TOKEN" \
  http://localhost:3000/api/v1/openclaw/workspace/status

Troubleshooting​

SymptomCauseFix
503 errorsPort-forward stopped or service restartedRestart the port-forward in the terminal
Connection refusedWrong namespace/service name or port-forward not runningCheck service names: kubectl get svc -n <namespace>
401 UnauthorizedToken mismatchRe-fetch the token from Kubernetes secrets
Only seeing default agentAPI can't reach workspace serviceVerify OPENCLAW_WORKSPACE_URL and that the port-forward is active

Tips​

  • Use a terminal multiplexer (tmux, iTerm2 split panes) to keep port-forwards visible
  • Port-forwards drop when the pod restarts — check if the pod restarted if you see sudden 503 errors
  • The workspace service and gateway are separate services — you can run just one if you only need workspace or gateway features