Openclaw Zo Guide

Installing OpenClaw on Zo Computer & Connecting All 50+ Tools

> Last updated: March 10, 2026

A complete guide to installing the OpenClaw agent framework on your Zo Computer and bridging it with Zo's native MCP tools via mcporter — from zero to a fully-equipped AI agent.

> 📖 Live version: nytemode.zo.space/openclaw-zo-guide

---

Why Run OpenClaw on Your Zo Computer?

OpenClaw turns your Zo Computer into something more than a server you talk to — it becomes home to a persistent, autonomous AI agent. One that connects to your messaging apps (Telegram, Discord, WhatsApp), remembers context between conversations, runs scheduled tasks while you sleep, and takes action on its own when needed.

The real power is the combination: OpenClaw's agent framework (memory, identity, scheduling, multi-channel messaging) plus Zo's 50+ pre-authenticated MCP tools (Gmail, Calendar, image generation, web research, website deployment, and more). Your agent doesn't just answer questions — it checks your calendar, drafts emails, deploys pages, monitors services, and carries the load.

---

For AI Agents

> 🤖 This guide is designed to be followed step-by-step by either a human or an AI agent operating on a Zo Computer. If you're an agent and someone gave you this link, you can execute every command in this guide directly on the Zo server. Work through each step in order, verify each one succeeds before moving on, and you'll have a fully operational OpenClaw agent with access to all Zo platform tools.

---

What You'll Set Up

1. Install OpenClaw on the Zo Computer
2. Configure it with an LLM provider (Anthropic, OpenAI, etc.)
3. Connect a messaging channel (Telegram, Discord, or WhatsApp)
4. Enable full tool access (shell, files, web)
5. Install mcporter to bridge Zo's 50+ MCP tools into your agent
6. Write workspace files so your agent knows how to use everything

---

Prerequisites

You need:

• A Zo Computer account (any tier)
• An API key from an LLM provider — Anthropic (Claude) or OpenAI
• A messaging channel to talk to your agent — Telegram bot token (easiest), Discord bot, or WhatsApp

> ℹ️ Zo Computer runs Linux with Node.js pre-installed. You don't need Docker, containers, or a reverse proxy — OpenClaw runs directly on the server.

---

Step 1: Install OpenClaw

SSH into your Zo Computer (or run commands via Zo's shell tools) and install OpenClaw using npm:

# Install OpenClaw globally
npm install -g openclaw@latest

# Verify installation
openclaw --version

You should see the version number (e.g., 2026.3.2). If npm isn't found, install Node.js first:

# Only if Node.js is missing (unlikely on Zo)
curl -fsSL https://deb.nodesource.com/setup_22.x | bash -
apt-get install -y nodejs

---

Step 2: Run the Onboarding Wizard

OpenClaw has an interactive onboarding wizard that walks you through initial configuration:

openclaw onboard

The wizard will ask you to:

1. Choose an LLM provider — select Anthropic (for Claude) or OpenAI
2. Enter your API key — paste your provider's API key
3. Select a model — for Anthropic, choose claude-opus-4-6 (best) or claude-sonnet-4-6 (faster/cheaper)
4. Configure permissions — choose "Full access" when prompted
5. Install starter skills — accept the defaults or skip

> ⚠️ The wizard creates /root/.openclaw/openclaw.json with your configuration. Even if you select "Full access" during onboarding, the wizard often sets tools.profile to "messaging" anyway. We'll fix this in the next step.

If you prefer to skip the wizard and configure manually, create the config file directly:

mkdir -p /root/.openclaw/workspace

cat > /root/.openclaw/openclaw.json  ⚠️ If the output isn't `"full"`, edit the config file directly:
> ```bash
> sed -i 's/"messaging"/"full"/g' /root/.openclaw/openclaw.json
> ```

---

## Step 4: Connect a Messaging Channel

Your agent needs a way to talk to you. Telegram is the easiest option.

### Option A: Telegram (Recommended)

1. Message [@BotFather](https://t.me/BotFather) on Telegram
2. Send `/newbot`, give it a name and username
3. Copy the bot token BotFather gives you
4. Configure OpenClaw with it:

```bash
openclaw config set channels.telegram.enabled true
openclaw config set channels.telegram.botToken "YOUR_TELEGRAM_BOT_TOKEN"

# If you'll use group chats and want immediate replies:
openclaw config set channels.telegram.groupPolicy open

> ℹ️ If you keep channels.telegram.groupPolicy as "allowlist", add sender IDs to channels.telegram.groupAllowFrom (or allowFrom). An empty allowlist silently drops all group messages.

Option B: Discord

openclaw config set channels.discord.enabled true
openclaw config set channels.discord.token "YOUR_DISCORD_BOT_TOKEN"

Option C: WhatsApp

WhatsApp requires QR code scanning. Run openclaw onboard and select WhatsApp when prompted — it'll display a QR code to scan with your phone.

---

Step 5: Install mcporter

Now for the key piece: bridging Zo's native MCP tools into OpenClaw. mcporter is an npm package that makes Zo's 50+ tools callable from inside your agent's session.

Without mcporter, your agent only has OpenClaw's built-in tools (shell, files, basic web browsing). With mcporter, your agent gains access to Gmail, Google Calendar, image generation, web research, website deployment, scheduled automations, and everything else Zo offers.

npm install -g mcporter

---

Step 6: Authenticate mcporter with Zo

mcporter needs to authenticate with Zo's MCP API. There are two ways to do this:

Option A: Access Token (Recommended)

Access tokens are permanent API keys that never expire. This is the recommended approach — it eliminates the most common cause of agents going offline.

1. Go to Zo Dashboard → Settings → Advanced
2. Under Access Tokens, enter a name (e.g., "mcporter") and click +
3. Copy the token immediately — it starts with zo_sk_ and won't be shown again

> ℹ️ Access tokens grant full access to your Zo. Keep them secure and never commit them to version control. You can create multiple tokens (one per integration) and revoke them individually from Settings.

Option B: JWT Token (Not Recommended)

Your Zo Computer also has a JWT token at /root/.zo_secrets. While this works, JWTs expire every ~24 hours. If the platform refreshes .zo_secrets but your mcporter config still has the old token, your agent silently loses access to all Zo tools and can go offline without any error message.

> ⚠️ The JWT expiry problem is the #1 cause of agents appearing silent every ~24 hours. Expired JWTs break Zo tool calls until credentials are refreshed. Use a permanent access token (zo_sk_...) to eliminate this failure mode.

---

Step 7: Configure mcporter

Create the mcporter config file pointing to Zo's MCP endpoint with your access token:

mkdir -p /root/.mcporter

cat > /root/.mcporter/mcporter.json  /root/.openclaw/workspace/TOOLS.md  key=value key2=value2

Available Tool Categories

• Communication: sendemailtouser, sendsmstouser
• Calendar: useappgoogle_calendar
• Web: websearch, webresearch, readwebpage, openwebpage
• Files (Zo): readfile, createorrewritefile, editfile, listfiles
• Shell (Zo): runbashcommand, runsequentialcmds
• Media: generateimage, generatevideo, editimage, transcribeaudio
• Publishing: updatespaceroute, listspaceroutes, create_website
• Research: findsimilarlinks, xsearch, mapssearch
• Automation: createagent, listagents (scheduled tasks)

Examples

# Search the web
mcporter call zo.web_search query="latest AI news" time_range="week"

# Check calendar
mcporter call zo.use_app_google_calendar tool_name="list-events" \
  configured_props='{"maxResults": 5}'

# Send yourself an email
mcporter call zo.send_email_to_user subject="Test" markdown_body="Hello!"

# Generate an image
mcporter call zo.generate_image prompt="a sunset" file_stem="sunset"

Important

• All app integrations (Gmail, Calendar, etc.) are pre-authenticated through Zo
• Use mcporter list zo to see all available tools
• Use mcporter call zo.tool_docs tool_name="" for detailed tool usage

TOOLSEOF

Optionally, add an identity file so your agent has a name and personality:

```bash
cat > /root/.openclaw/workspace/IDENTITY.md  ⚠️ **Workspace char limit:** All files in `/root/.openclaw/workspace/` combined must stay under 20,000 characters. If you exceed this, content gets silently truncated and your agent loses context. Monitor with:
> ```bash
> for f in /root/.openclaw/workspace/*.md; do printf "%6d chars %s\n" $(wc -c  ```

---

## Step 9: Start the Gateway

The OpenClaw gateway is the process that connects your agent to its messaging channel and keeps it running.

### Production Setup: Zo User Service (Recommended)

Zo Computer has a built-in **User Service** system that manages processes with auto-restart **and persists across container reprovisions**. This is the only reliable way to keep your agent online long-term.

> ⚠️ **Do not manually edit `/etc/zo/supervisord-user.conf`.** Manual edits get wiped when Zo reprovisions your container (which happens periodically for maintenance). Only services registered via `register_user_service` survive reprovisions.

Register the gateway as a persistent Zo User Service using mcporter (which you set up in Steps 5-7):

```bash
# Stop any manually started gateway first (prevents port conflicts)
openclaw gateway stop || true
pkill -f openclaw-gateway || true

# Register the gateway as a persistent Zo User Service via mcporter
mcporter call zo.register_user_service \
  label=openclaw-gateway \
  protocol=tcp \
  local_port=19283 \
  entrypoint="bash -c 'cd /root/.openclaw && exec openclaw gateway run'" \
  workdir=/root/.openclaw

# Verify it's running (give it a few seconds to start)
sleep 5
supervisorctl -s http://127.0.0.1:29011 status openclaw-gateway
openclaw gateway status | grep -E "RPC probe: ok|Listening:"

Once registered, the service auto-starts on boot and auto-restarts on crash — even after container reprovisions. To restart after config/workspace changes:

supervisorctl -s http://127.0.0.1:29011 restart openclaw-gateway

To check logs:

tail -50 /dev/shm/openclaw-gateway.log

> ⚠️ Do not use bare nohup or manually edit supervisord configs. A nohup process has no auto-restart, and manual supervisord entries get wiped on container reprovision. Always use register_user_service for production.

Quick Start (Development Only)

For quick testing, you can start the gateway directly. This is fine for development but not recommended for production since it won't auto-restart on crash:

cd /root/.openclaw
nohup openclaw gateway run > /root/.openclaw/gateway.log 2>&1 &

# Verify it's running
sleep 3
ps aux | grep openclaw | grep -v grep
tail -20 /root/.openclaw/gateway.log

---

Verify Everything Works

Run through this checklist to confirm your setup is complete:

# 1. OpenClaw is installed
openclaw --version

# 2. tools.profile is "full"
openclaw config get tools.profile

# 3. mcporter can reach Zo
mcporter list zo | head -5

# 4. Gateway is registered as a Zo User Service + running
supervisorctl -s http://127.0.0.1:29011 status openclaw-gateway

# 5. Gateway RPC probe is healthy
openclaw gateway status | grep -E "RPC probe: ok|Listening:"

# 6. Recovery test: restart gateway and confirm it comes back
supervisorctl -s http://127.0.0.1:29011 restart openclaw-gateway
sleep 2
supervisorctl -s http://127.0.0.1:29011 status openclaw-gateway

# 7. Workspace files are within limits
total=0
for f in /root/.openclaw/workspace/*.md; do
  chars=$(wc -c Hello from my agent! }'

---

Gotchas & Troubleshooting

| Issue | Fix | |-------|-----| | tools.profile reverts to "messaging" | After updates or re-running the onboard wizard, tools.profile can silently reset. Always verify with openclaw config get tools.profile | | Workspace files exceed 20,000 chars | Content gets silently truncated. Your agent loses context without any error. Keep files lean and monitor sizes. | | Gateway not picking up changes | Workspace and config changes require a full gateway restart. Just editing files isn't enough — restart via supervisorctl or kill and re-launch. | | Container reprovision wipes manual configs | Zo periodically reprovisions containers for maintenance. Manual edits to /etc/zo/supervisord-user.conf are lost. Only data in /root/ and /home/ survives, plus services registered via register_user_service. Always use register_user_service for persistent processes. | | Gateway not registered as a Zo User Service | If the gateway was started manually or added to supervisord by hand, it will disappear after a container reprovision — your agent silently goes offline. Fix: register via mcporter call zo.register_user_service (see Step 9). | | Port 18789 already in use | If logs show "another gateway instance is already listening", you have duplicate starts (manual + supervisor). Fix: run openclaw gateway stop, kill stale openclaw-gateway processes, then restart only through supervisorctl. | | JWT token expiry causes tool failures every ~24h | The JWT in /root/.zo_secrets rotates about every 24 hours. If mcporter uses that JWT, Zo tool calls fail when it expires. Fix: use a permanent access token (zo_sk_...) from Settings → Advanced. | | Gateway crashes and stays offline | If you started the gateway with bare nohup or manually edited supervisord, your agent has no reliable auto-recovery. Fix: register via register_user_service which survives crashes AND container reprovisions. | | mcporter shows "auth required" or "0 healthy" | Run mcporter list — if it says "auth required", your token is invalid or expired. If using a JWT from .zo_secrets, switch to a permanent access token. If using an access token, verify it in Zo Settings → Advanced. | | Telegram group messages are ignored | If channels.telegram.groupPolicy is "allowlist" and no allowed IDs are configured, all group messages are dropped. Set groupPolicy to "open" or populate groupAllowFrom. | | mcporter call syntax | Use key=value pairs, not JSON flags. For nested objects, pass JSON strings in single quotes: configured_props='{"key": "value"}' | | OpenClaw tools vs Zo tools | Don't confuse them. OpenClaw has its own built-in tools (shell, files, browser). Zo's MCP tools (Gmail, Calendar, image gen, etc.) are only accessible through mcporter. | | Agent says it will do something but goes silent | Check three things in order: (1) tools.profile must be "full", (2) mcporter must be healthy (mcporter list), (3) gateway must be running. The most common cause is an expired mcporter token. | | npm install fails | If npm isn't found, install Node.js first: curl -fsSL https://deb.nodesource.com/setup_22.x \| bash - && apt-get install -y nodejs |

---

Quick Reference

# --- Installation ---
npm install -g openclaw@latest
npm install -g mcporter
openclaw onboard

# --- Configuration ---
openclaw config set tools.profile full
openclaw config get tools.profile

# --- mcporter ---
mcporter list                              # verify health
mcporter call zo. key=value     # call a tool
mcporter call zo.tool_docs tool_name="X"   # get tool docs

# --- Gateway (Production — Zo User Service) ---
# Register (only needed once — survives reprovisions)
mcporter call zo.register_user_service \
  label=openclaw-gateway protocol=tcp local_port=19283 \
  entrypoint="bash -c 'c

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [NYTEMODEONLY](https://github.com/NYTEMODEONLY)
- **Source:** [NYTEMODEONLY/openclaw-zo-guide](https://github.com/NYTEMODEONLY/openclaw-zo-guide)
- **License:** MIT
- **Homepage:** https://nytemode.zo.space/openclaw-zo-guide

Install and usage instructions live in the source repository linked above.