openclaw-install

name	openclaw-install
description	Cleanly install and configure an OpenClaw server on an Ubuntu VPS via Docker, with OpenAI API (GPT-5.5), Telegram, Tavily, Whisper, ElevenLabs, and Google Cloud Hebrew TTS. Encodes the hard-won lessons — never use Codex/ChatGPT login, restrict ports to localhost, lock the plugin allow-list, and back up state. Trigger whenever the user wants to install OpenClaw, set up an OpenClaw server, redeploy/recover a corrupted OpenClaw, add Telegram or Hebrew voice to OpenClaw, or says "install openclaw", "set up openclaw", "openclaw server".
argument-hint	[fresh-install | recover | add-hebrew-tts | telegram-pairing]
allowed-tools	Bash, Read, Write, Edit, AskUserQuestion, Glob, Grep
homepage	https://github.com/jackvidal/openclaw-install-by-jack-vidal
repository	https://github.com/jackvidal/openclaw-install-by-jack-vidal
author	jackvidal
license	MIT
user-invocable	true

/openclaw-install — clean OpenClaw server setup

A battle-tested runbook for deploying a stable OpenClaw server on an Ubuntu VPS with Docker, OpenAI (GPT-5.5), Telegram, Tavily, Whisper, ElevenLabs, and Google Hebrew TTS.

This skill targets a remote Ubuntu host, not the local Windows machine. Run the commands over SSH on the VPS (paste them for the user, or run via an SSH session if one is available). All paths below are VPS paths.

The non-negotiable rules (read first)

These come from a real failed install. Violating them corrupts the runtime:

1. NEVER use ChatGPT Login, Codex Login, or Codex Runtime. Use an OpenAI API key only. Codex auth poisons agents/main/agent/codex-home and plugins/installs.json; old sessions keep trying to load codex even after you remove it from config.
2. NEVER enable Codex, ChatGPT login, Anthropic, Gemini, or Claude runtime during onboarding.
3. Bind the gateway to loopback and publish Docker ports only on 127.0.0.1. Never expose the gateway publicly.
4. Lock the plugin allow-list — OpenClaw auto-detects a Codex plugin even on a clean install.
5. Back up /root/.openclaw once it works. Recovery = restore the tarball.

Step 0 — Pick the task

If the user didn't specify, ask via AskUserQuestion which path they want:

• Fresh install — full clean deployment from scratch (Steps 1–16).
• Recover — OpenClaw is corrupted; restore from backup (Recovery section).
• Add Hebrew TTS — existing install, add Google Cloud Hebrew voice (Hebrew TTS section).
• Telegram pairing — bot is running, just approve the owner (Telegram Pairing section).

Then jump to the matching section. Confirm the target host with the user before running destructive commands (anything with rm -rf, docker compose down, docker rm).

---

Fresh install

1. Server prep

apt update && apt upgrade -y
# reboot only if a kernel update landed; warn the user it drops the SSH session

2. Install Docker

curl -fsSL https://get.docker.com | sh
docker --version
docker compose version

3. Clone OpenClaw

mkdir -p /opt/apps
cd /opt/apps
git clone https://github.com/openclaw/openclaw.git
cd openclaw

4. Write .env

Create /opt/apps/openclaw/.env with the Write tool or nano:

OPENCLAW_CONFIG_DIR=/root/.openclaw
OPENCLAW_WORKSPACE_DIR=/root/.openclaw/workspace
OPENCLAW_AUTH_PROFILE_SECRET_DIR=/root/.openclaw-auth-profile-secrets

OPENCLAW_GATEWAY_PORT=18789
OPENCLAW_BRIDGE_PORT=18790

OPENCLAW_GATEWAY_BIND=loopback

OPENCLAW_IMAGE=ghcr.io/openclaw/openclaw:latest

5. Restrict ports to localhost

Edit /opt/apps/openclaw/docker-compose.yml. Find:

ports:
  - "${OPENCLAW_GATEWAY_PORT:-18789}:18789"
  - "${OPENCLAW_BRIDGE_PORT:-18790}:18790"

Replace with:

ports:
  - "127.0.0.1:${OPENCLAW_GATEWAY_PORT:-18789}:18789"
  - "127.0.0.1:${OPENCLAW_BRIDGE_PORT:-18790}:18790"

6. Clean any prior state (only if reinstalling)

Critical: a half-finished or Codex-poisoned install MUST be wiped, not patched.

cd /opt/apps/openclaw && docker compose down
# optional full sweep:
# docker stop $(docker ps -aq); docker rm $(docker ps -aq)
rm -rf /opt/apps/openclaw
rm -rf /root/.openclaw
rm -rf /root/.openclaw-auth-profile-secrets

Then re-clone (Step 3) and re-write .env + compose edits (Steps 4–5).

7. Prepare folders & permissions

mkdir -p /root/.openclaw/workspace
chmod -R 777 /root/.openclaw
mkdir -p /root/.openclaw-auth-profile-secrets
chmod -R 777 /root/.openclaw-auth-profile-secrets

8. Run onboarding

docker run --rm -it \
  -v /root/.openclaw:/home/node/.openclaw \
  ghcr.io/openclaw/openclaw:latest \
  openclaw onboard --mode local

Onboarding choices — exactly these:

Prompt	Choose
Provider	OpenAI
Auth method	OpenAI API Key (paste the key — never ChatGPT/Codex login)
Setup mode	QuickStart
Gateway bind	Loopback (127.0.0.1)
Telegram	Enable, paste the bot token (see below)

Do not enable Codex, ChatGPT login, Anthropic, Gemini, or Claude runtime.

Other API keys to have ready: Tavily (web search), ElevenLabs (English voice), OpenAI key also covers Whisper STT.

9. Create the Telegram bot (before/at onboarding)

Tell the user to open https://t.me/BotFather, send /newbot, follow prompts, and copy the bot token. Paste that token when onboarding asks.

10. Start the stack

cd /opt/apps/openclaw
docker compose up -d
docker logs -f openclaw-openclaw-gateway-1

Healthy startup shows [gateway] ready and [telegram] starting provider.

11. Lock the plugin allow-list

Even after a clean install OpenClaw may auto-load a Codex plugin. Edit /root/.openclaw/openclaw.json and add:

"plugins": {
  "allow": [
    "browser",
    "canvas",
    "device-pair",
    "file-transfer",
    "memory-core",
    "phone-control",
    "talk-voice",
    "telegram"
  ]
}

Then cd /opt/apps/openclaw && docker compose restart. Confirm logs show http server listening (8 plugins...) without codex.

12. Telegram pairing (claim ownership)

See the Telegram Pairing section below.

13. Back up the working state

cp /root/.openclaw/openclaw.json /root/.openclaw/openclaw-working-backup.json
tar -czf /root/openclaw-clean-working.tar.gz /root/.openclaw

Tell the user to also download /root/openclaw-clean-working.tar.gz off the VPS.

---

Telegram Pairing

The first message to the bot returns OpenClaw: access not configured plus a pairing code. Approve it:

docker exec -it openclaw-openclaw-cli-1 openclaw pairing approve telegram YOUR_CODE

After approval that Telegram account is the permanent owner; access persists.

---

Hebrew TTS (Google Cloud)

Conclusion from testing: ElevenLabs Hebrew is poor even with eleven_multilingual_v2 / eleven_turbo_v2_5. Use Google Cloud TTS for Hebrew, keep ElevenLabs for English.

If sticking with ElevenLabs for English, ensure the API key has: Text to Speech → Access, Models → Access, Voices → Read, Voice Generation → Access (optional Speech to Text → Access).

Google setup

1. In https://console.cloud.google.com/ enable Billing and the Cloud Text-to-Speech API.

2. Create an API key.

3. Add it to /opt/apps/openclaw/.env:

   GOOGLE_TTS_API_KEY=YOUR_API_KEY
   

4. Restart: cd /opt/apps/openclaw && docker compose down && docker compose up -d

Install the Hebrew TTS script

The script ships with this skill at scripts/google_tts_hebrew.py. Copy it onto the VPS:

mkdir -p /root/.openclaw/tools
# write the file (use the Write tool reading scripts/google_tts_hebrew.py,
# or scp it) to /root/.openclaw/tools/google_tts_hebrew.py
chmod +x /root/.openclaw/tools/google_tts_hebrew.py

Test

docker exec -it openclaw-openclaw-gateway-1 \
  python3 /home/node/.openclaw/tools/google_tts_hebrew.py "שלום, בדיקת קול בעברית"
# expected: /home/node/.openclaw/workspace/google-hebrew-tts.mp3
docker cp openclaw-openclaw-gateway-1:/home/node/.openclaw/workspace/google-hebrew-tts.mp3 /root/

Do not try ffplay file.mp3 on the VPS — a VPS has no audio hardware; ALSA errors are normal and expected. Download the MP3 locally to listen.

---

Recovery (corrupted OpenClaw)

If the runtime breaks again (e.g. Requested agent harness "codex" is not registered):

rm -rf /root/.openclaw
tar -xzf /root/openclaw-clean-working.tar.gz -C /
cd /opt/apps/openclaw && docker compose restart

If there is no backup tarball, do a full Fresh install with the Step 6 cleanup.

---

Reduce noisy tool logs

OpenClaw streams Barnacling..., run python..., apply patch.... To quiet it, instruct the agent (in its system/persona config):

Never show internal tool activity, command execution, patches, file reads, progress messages, or reasoning. Only send the final answer or voice response.

Note: some streaming may still require gateway-level changes in future versions — set expectations accordingly.

---

Final working stack (reference)

Ubuntu VPS · Docker · OpenClaw · OpenAI GPT-5.5 · Telegram bot · Tavily · Whisper STT · ElevenLabs (English voice) · Google Hebrew TTS · browser / memory / voice tools.

Standing recommendations: Hebrew → Google Cloud TTS; English → ElevenLabs; stability → no Codex runtimes ever, OpenAI API key only, restricted plugin allow-list, back up /root/.openclaw regularly.