Install Openclaw To Yc

Install OpenClaw to Yandex Cloud (Kazakhstan)

A wizard that takes a non-DevOps user from zero to a working OpenClaw bot on a fresh Yandex Cloud Kazakhstan VM in ~15 minutes. The user does exactly two-or-three things: paste a Telegram bot token, paste an LLM API key (or say "Codex" for OAuth via ChatGPT subscription), press /start in Telegram once, and — only for Codex — confirm a device code on auth.openai.com. Everything else is silent.

Operating principles (the "don't bother the user" rules)

These rules override the rest of the document. Read them first.

1. Two questions. Total. The only inputs you ask the user for are the Telegram bot token and the LLM access (one of three options — see Step 1). Everything else — VM name, zone, image, SSH key, security-group ingress, chat_id — is decided silently from safe defaults or auto-detected.
2. Never ask "are you sure" for actions inside this wizard's own scope (creating its own VM, its own security group, its own bot pairing). Only confirm if you're about to destroy something the user might want to keep (an existing VM with the same name).
3. Never show shell commands, flags, paths, or stack traces to the user unless they explicitly ask "what did you run?". Progress is plain language: "Создаю VM…", "Ставлю OpenClaw…", "Проверяю что бот отвечает…".
4. Validate inputs upfront with a one-call test (Telegram /getMe, LLM key probe). Don't burn 15 minutes on a VM bootstrap with a bad key.
5. Auto-fix prerequisites silently when it's safe — install yc CLI, generate an SSH key, switch endpoint to Kazakhstan. Only stop and ask the user when something can't be done without their input (yc init OAuth login, no billing account).
6. One language — and the bot speaks it too. If the user wrote to the agent in Russian, all wizard prompts are in Russian, and the OpenClaw bot itself is configured to reply in Russian. Detect the user's language from their first few messages, pass it through to cloud-init as {{USER_LANGUAGE}} (ISO 639-1: ru/en/kk/...), and the bootstrap script appends a localization block to the bot's USER.md. Default if you can't tell: ru (workshop audience).
7. No emojis in user-facing text unless the user used them first.

Do NOT ask the user for these (hard override)

These are the things the wizard has been observed asking by mistake. Don't:

If you catch yourself drafting a question outside the two allowed inputs, re-read this section. The wizard's whole point is autonomy.

When to invoke

Trigger on: "install OpenClaw on Yandex Cloud", "set up my bot in YC Kazakhstan", "OpenClaw workshop workshop", "deploy OpenClaw remotely", "поставь себе openclaw", "разверни мне бота в Yandex Cloud", "у меня workshop-ключ", "вот bundle от организатора", and close paraphrases.

Do NOT use this skill for:

• Local-machine OpenClaw install → use openclaw/install.sh in this repo (the user runs it on their laptop)
• Hetzner Cloud → use install-openclaw-to-hetzner (sibling skill, same shape, different CLI)
• AWS / GCP / Azure / other Yandex Cloud regions → this skill is hard-coded for Yandex Cloud Kazakhstan (kz1-a); no sibling skills exist yet for those clouds
• Adding a second agent or a second bot to an existing OpenClaw VM → out of scope
• Preparing the workshop as an organizer (creating N folders + keys for participants) → use prepare-yc-workshop (the matching organizer-side skill) — this skill is for the participant

Two access modes (Plan A and Plan B)

This skill works in two modes — picked silently at Step 0 from what the user has on hand. The user is shown the choice only once in Step 1; after that, both branches converge and the rest of the wizard is identical.

Plan B is recognised by detecting a workshop bundle file in any of these ways (auto-detected in Step 0.5 below):

1. The user pasted a file path that resolves to a JSON whose $schema starts with openclaw-workshop-bundle@.
2. The user said one of: "у меня workshop-ключ", "вот bundle от организатора", "I have a workshop key", "organizer gave me a key file", "у меня нет своего Yandex Cloud, есть только ключ от воркшопа".
3. A file matching bundle-*.json is present in the user's current working directory or ~/Downloads (offered with a one-line confirmation).

If none match, the wizard defaults to Plan A.

After Step 0.5 the two branches converge — Steps 1, 2, 3, 4, 5 are identical regardless of mode. Plan A and Plan B both end with a working YC profile pointing at one folder; everything downstream just uses that.

Inputs (the only two questions you ask)

LLM access options (the user picks one)

Order of recommendation in the prompt: A → C → B for first-timers. A is the simplest happy path with the best Anthropic model. C is best for users who already pay for ChatGPT and want zero added bill. B is the power-user choice.

Everything below is decided without asking the user:

Default models per LLM option

For C, the wizard probes the subscription tier after OAuth completes — if openai/gpt-5.5 isn't in openclaw models list --json, it uses openai/gpt-5.4 as primary. (Codex models live in the openai/ namespace, backed by the openai-codex OAuth profile — verified on a live 2026.5.27 bot.)

Wizard flow

Step 0 — Silent preflight (no user-facing output unless something breaks)

Run in order. Each block has a silent auto-fix path; only fall through to a user prompt when no silent path exists.

Critical Yandex Cloud Kazakhstan rules — read before touching yc:

• KZ has its own endpoint api.yandexcloud.kz:443. The Russian endpoint api.cloud.yandex.net:443 and the KZ endpoint serve different clouds, folders, and OAuth realms. Mixing them is the #1 cause of "wizard says no billing / no cloud" when both exist.
• Setting yc config set endpoint api.yandexcloud.kz:443 does NOT auto-update cloud-id or folder-id. If you only flip the endpoint and don't re-set cloud-id/folder-id, every subsequent yc compute / vpc / resource-manager command will fail with NotFound, because those IDs belong to the RU realm.
• The KZ endpoint exposes a smaller command set: iam, quota-manager, resource-manager, compute, vpc, dns, managed-kubernetes. yc billing does NOT exist on the KZ endpoint. Calling yc billing account list always errors out — don't use it for any check.
• Use named profiles (yc config profile create/activate) instead of editing the active config. The user almost certainly already has profiles for their other clouds — don't clobber them.

Step 0.5 — Detect mode (Plan A vs Plan B). Runs first, before anything else in Step 0.

Plan B short-circuits steps c, d, e (profile, OAuth, cloud-id/folder-id resolution) because the bundle already has all of that baked in. Plan A keeps them.

Detection order:

1. Explicit file path in what the user said. Resolve the path; if it's a readable JSON whose $schema field starts with openclaw-workshop-bundle@, set MODE=plan-b and BUNDLE_PATH=<path>.
2. Phrase match. If the user wrote any of these (or close paraphrase) in the activation message:
   • "У меня workshop-ключ" / "вот bundle от организатора" / "ключ от воркшопа"
   • "I have a workshop key" / "organizer gave me a key file"
   • "Bundle from the organizer is here:" → followed by path
   • Then ask one clarifier: "Где лежит файл bundle-NN.json от организатора? (можешь перетащить файл в чат, или просто путь)" — accept the path, validate the $schema, set MODE=plan-b.
3. Auto-discovery. Glob bundle-*.json in $PWD, ~/Downloads, ~/Desktop. If exactly one match whose $schema starts with openclaw-workshop-bundle@, ask once: "Нашёл workshop-ключ bundle-NN.json в <path>. Это от организатора? (да / нет)". On "да" → MODE=plan-b. On "нет" → continue to next step.
4. Default. No bundle detected → MODE=plan-a. Don't ask "do you have a workshop key?" upfront — that's friction for the >50% of users who have their own YC and would treat the question as noise.

Schema sanity check on the bundle file:

SCHEMA=$(jq -r '."$schema" // empty' "$BUNDLE_PATH" 2>/dev/null)
[[ "$SCHEMA" =~ ^openclaw-workshop-bundle@ ]] \
  || { say "Это не похоже на workshop-bundle от организатора. Проверь, что прислали правильный файл."; stop; }

# Required fields
for f in cloud_id folder_id zone endpoint key; do
  jq -er ".${f}" "$BUNDLE_PATH" >/dev/null \
    || { say "В bundle не хватает поля ${f}. Попроси у организатора новый файл."; stop; }
done

On any validation failure for Plan B, tell the user in one sentence what's wrong, advise asking the organizer, and stop — don't silently fall back to Plan A. Falling back would burn 10 minutes asking for OAuth they don't have.

If MODE=plan-b: configure yc from the bundle and skip directly to Step 0a, then f, then g (skipping c, d, e):

# Wizard-owned profile so we don't disturb the user's other yc setups
yc config profile create openclaw-workshop 2>/dev/null || true
yc config profile activate openclaw-workshop

# Carve the SA key into the shape `yc config set service-account-key` expects
KEY_FILE="$(mktemp -t openclaw-sa-key.XXXXXX.json)"
jq '.key' "$BUNDLE_PATH" > "$KEY_FILE"
chmod 600 "$KEY_FILE"

yc config set service-account-key "$KEY_FILE"
yc config set endpoint            "$(jq -r '.endpoint'  "$BUNDLE_PATH")"
yc config set cloud-id            "$(jq -r '.cloud_id'  "$BUNDLE_PATH")"
yc config set folder-id           "$(jq -r '.folder_id' "$BUNDLE_PATH")"
yc config set compute-default-zone "$(jq -r '.zone'      "$BUNDLE_PATH")"

# Verify it actually works — one read call against the configured folder
yc compute zone list --format json | jq -e '.[] | select(.id=="kz1-a")' >/dev/null \
  || { say "Ключ от организатора не работает (или истёк). Напиши организатору: попроси новый bundle."; stop; }

Plan-B-specific failure modes:

• Schema older than @1 → bundle predates this version of the skill. Ask user to refresh from organizer; don't try to be smart.
• Schema newer than what this skill recognises → also ask for guidance from organizer (they updated prepare-yc-workshop past us). Bundle may still work — try the steps above and surface YC errors plainly.
• yc compute zone list returns empty → key was revoked or folder deleted. Tell the user: "Кажется, организатор уже свернул облако воркшопа. Свяжись с ним."
• yc compute zone list returns ru-central1-* instead of kz1-a → bundle's endpoint field was wrong. Surface plainly; this is an organizer-side bug.

On MODE=plan-b, skip Step 0c, 0d, 0e entirely and proceed to 0a → 0b → 0f → 0g. The bundle already contains a valid token-equivalent + cloud-id + folder-id, so re-asking for OAuth would be cruel and pointless.

On MODE=plan-a, proceed normally through Step 0a-g as written.

a. Companion skill openclaw-guide must be loaded. Probe the agent's skill loader. If it's not present, run npx skills add CodeAlive-AI/ceo-ai-os@openclaw-guide -g silently. If npx is unavailable, tell the user (one sentence) to install both skills manually, then stop.

b. yc CLI installed. yc --version. If missing: silently curl -fsSL https://storage.yandexcloud.net/yandexcloud-yc/install.sh | bash -s -- -i $HOME/yandex-cloud -n and add ~/yandex-cloud/bin to PATH for this session.

(c, d, e are Plan A only — skip on MODE=plan-b, which configured the profile from the bundle in Step 0.5.)

c. Activate a dedicated Kazakhstan profile. Use a wizard-owned profile so we don't disturb the user's existing setup:

PROFILE_NAME=openclaw-kz
CURRENT_PROFILE=$(yc config profile list 2>/dev/null | awk '/ACTIVE/{print $1}')

# If the user is already on a profile pointing at KZ, just use it.
if [[ "$CURRENT_PROFILE" != "$PROFILE_NAME" ]]; then
  if [[ "$(yc config get endpoint 2>/dev/null)" != "api.yandexcloud.kz:443" ]]; then
    # Create/activate our own profile rather than mutating the user's active one
    yc config profile list 2>/dev/null | grep -qE "^${PROFILE_NAME}\b" \
      || yc config profile create "$PROFILE_NAME"
    yc config profile activate "$PROFILE_NAME"
  fi
fi

After this block, the active profile is either the user's pre-existing KZ-pointing profile (preserve their settings — they know what they're doing) or our fresh openclaw-kz profile (we'll fill it in steps d-f).

d. OAuth token + endpoint on the active profile. Check yc config get token and yc config get endpoint:

• Both already set, endpoint is KZ → ✅ skip ahead.
• Endpoint set to KZ but no token → ask the user once (see below).
• Token set but wrong endpoint → silently yc config set endpoint api.yandexcloud.kz:443.
• Nothing set (fresh profile) → ask the user once for an OAuth token.

The OAuth ask is the only mandatory user prompt in Step 0. Say exactly:

Для работы с Yandex Cloud Kazakhstan нужен OAuth-токен (один раз). Открой в браузере:

https://oauth.yandex.kz/authorize?response_type=token&client_id=1a6990aa636648e9b2ef855fa7bec2fb

Войди под своим Yandex ID, разреши доступ. После редиректа браузер покажет URL вида https://oauth.yandex.kz/verification_code#access_token=y0_XXXXXX…&token_type=bearer&expires_in=.... Скопируй значение access_token=… (длинная строка между = и &) и пришли мне.

After receiving the token: yc config set token <token>, then set the endpoint and the zone in the same breath:

yc config set endpoint api.yandexcloud.kz:443
yc config set compute-default-zone kz1-a

compute-default-zone is decoupled from endpoint — yc config set endpoint doesn't touch it. Without it set, any yc compute * command that omits --zone falls back to whatever was there before (often ru-central1-a from a previous RU init) and fails with "zone not found".

e. cloud-id and folder-id. After step d, the profile has a valid token. Now resolve the IDs:

CLOUD_ID=$(yc config get cloud-id 2>/dev/null || true)
if [[ -z "$CLOUD_ID" ]]; then
  CLOUD_ID=$(yc resource-manager cloud list --format json | jq -r '.[0].id // empty')
  [[ -n "$CLOUD_ID" ]] && yc config set cloud-id "$CLOUD_ID"
fi

FOLDER_ID=$(yc config get folder-id 2>/dev/null || true)
if [[ -z "$FOLDER_ID" ]]; then
  FOLDER_ID=$(yc resource-manager folder list --cloud-id "$CLOUD_ID" --format json | jq -r '.[0].id // empty')
  [[ -n "$FOLDER_ID" ]] && yc config set folder-id "$FOLDER_ID"
fi

Failure modes:

• cloud list returns empty → the OAuth token is for a Yandex ID that has no clouds in KZ. Tell the user: "Похоже, у тебя нет облака в Yandex Cloud Kazakhstan. Создай облако в https://kz.console.yandex.cloud, потом запусти меня снова." Stop.
• cloud list returns multiple → use the first, but tell the user one line: "Использую облако <NAME>. Если это не то — скажи, переключусь."
• Same logic for folder.

Do not call yc billing account list. It doesn't exist on the KZ endpoint. If the user has a cloud and a folder, billing is either active or will fail concretely at VM creation time with a clear error. Catching that one error in Step 2 is fine.

f. SSH key. ls ~/.ssh/id_ed25519.pub. If missing: silently ssh-keygen -t ed25519 -f ~/.ssh/id_ed25519 -N "" -C "openclaw-yc-$(date +%Y%m%d)".

g. Existing instance with the same name in this cloud. yc compute instance get --name openclaw-bot 2>/dev/null. If a result comes back, ask once: "У тебя уже есть VM 'openclaw-bot' — поставить новую под именем openclaw-bot-XXXX?" Default yes; pick a random 4-char suffix.

Do not print anything to the user about (a)-(g) if everything passed silently. Move to Step 1.

Step 1 — Ask the two questions

In one message, in the user's language:

Сейчас поставлю тебе OpenClaw-бота в Yandex Cloud. От тебя нужны две вещи (~5 минут).

1) Telegram bot token. Открой @BotFather в Telegram → отправь /newbot → придумай имя (любое) → придумай username, заканчивающийся на bot → BotFather пришлёт токен. Пришли его мне.

2) Доступ к LLM — выбери ОДИН из трёх вариантов:

A) Anthropic API ключ (рекомендую первым, лучшее качество) Открой https://console.anthropic.com/settings/keys → Create Key. Ключ начинается на sk-ant-. На https://console.anthropic.com/settings/billing должно быть ≥$5.

B) OpenRouter API ключ (один ключ к Anthropic + OpenAI + 200 моделям) Открой https://openrouter.ai/keys → Create Key. Начинается на sk-or-. Нужен баланс ≥$5 на openrouter.ai/credits.

C) OpenAI Codex через ChatGPT подписку (бесплатно если уже платишь Plus или Pro) Не нужен ключ. Просто напиши слово «Codex». После установки бота я попрошу ввести 8-символьный код на auth.openai.com — один раз.

Пришли мне токен Telegram и один из трёх (ключ или слово «Codex»). Хоть в одном сообщении, хоть по отдельности. Я никуда не сохраняю и не показываю значения обратно.

Detect the LLM provider from what the user pasted:

case "$LLM_INPUT" in
  sk-ant-*)
    LLM_PROVIDER=anthropic ;;
  sk-or-*)
    LLM_PROVIDER=openrouter ;;
  Codex|codex|CODEX|ChatGPT|chatgpt|OpenAI*|"openai codex"|OAuth|oauth)
    LLM_PROVIDER=openai-codex
    LLM_API_KEY=""   # OAuth flow — no key at this stage
    ;;
  *)
    say "Не распознал — это Anthropic-ключ (начинается на sk-ant-), OpenRouter-ключ (sk-or-) или слово 'Codex'?" && reprompt
    ;;
esac

Validate the credential based on which option was chosen. Don't burn 15 minutes on a VM bootstrap with a bad key.

# Telegram token — always validate, confirms format + that the bot actually exists
BOT_USERNAME=$(curl -fsS "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/getMe" \
  | jq -er '.result.username') \
  || (say "Telegram токен не прошёл проверку. Скопируй его ещё раз из @BotFather." && stop)

case "$LLM_PROVIDER" in
  anthropic)
    # Minimal completion call confirms key + at least some credit
    curl -fsS https://api.anthropic.com/v1/messages \
      -H "x-api-key: ${LLM_API_KEY}" \
      -H "anthropic-version: 2023-06-01" \
      -H "content-type: application/json" \
      -d '{"model":"claude-haiku-4-5","max_tokens":1,"messages":[{"role":"user","content":"ok"}]}' \
      | jq -er '.content' >/dev/null \
      || (say "Anthropic ключ не работает или нет кредита. Проверь на console.anthropic.com." && stop)
    ;;
  openrouter)
    # OpenRouter exposes /api/v1/auth/key as a free credit check
    curl -fsS https://openrouter.ai/api/v1/auth/key \
      -H "Authorization: Bearer ${LLM_API_KEY}" \
      | jq -er '.data.usage != null' >/dev/null \
      || (say "OpenRouter ключ не прошёл проверку. Перепроверь на openrouter.ai/keys." && stop)
    # Optional: warn if balance below $1
    BAL=$(curl -fsS https://openrouter.ai/api/v1/auth/key -H "Authorization: Bearer ${LLM_API_KEY}" \
      | jq -r '.data.limit_remaining // 0')
    [[ "$BAL" == "0" ]] && say "На OpenRouter $0 кредита. Бот не сможет отвечать. Пополни на openrouter.ai/credits."
    ;;
  openai-codex)
    # Can't validate before OAuth — defer to Step 4.5 after VM is up.
    # Just confirm the user understands they'll need to do one extra step.
    say "Хорошо, после установки бота на VM покажу 8-символьный код для https://auth.openai.com/codex/device. Это разовое действие."
    ;;
esac

BOT_USERNAME (e.g. your_ceo_bot) is captured here for the one-click chat link in Step 5.

Step 2 — Silent VM creation

a. Ensure the default network + subnet exist in the current folder. Brand-new folders sometimes lack them (or the user removed them). Don't assume — discover, then create if missing.

NETWORK_ID=$(yc vpc network get --name default --format json 2>/dev/null | jq -r .id 2>/dev/null)
if [[ -z "$NETWORK_ID" ]]; then
  NETWORK_ID=$(yc vpc network create --name default --format json | jq -r .id)
fi

SUBNET_ID=$(yc vpc subnet get --name default-kz1-a --format json 2>/dev/null | jq -r .id 2>/dev/null)
if [[ -z "$SUBNET_ID" ]]; then
  # Pick a /24 from 10.130.x.x that doesn't collide with the user's other subnets
  SUBNET_ID=$(yc vpc subnet create \
    --name default-kz1-a \
    --network-id "$NETWORK_ID" \
    --zone kz1-a \
    --range 10.130.0.0/24 \
    --format json | jq -r .id)
fi

Don't mention any of this to the user unless it errors — these are quiet idempotent ops.

b. Render the cloud-init file. Substitute these placeholders (no TELEGRAM_CHAT_ID — it's auto-detected in Step 4):

• {{TELEGRAM_BOT_TOKEN}} — from Step 1.

• {{SSH_PUBLIC_KEY}} — content of ~/.ssh/id_ed25519.pub.

• {{LLM_ENV_LINE}} — depends on the chosen LLM provider:

  Provider	Substituted line
  anthropic	ANTHROPIC_API_KEY=<key>
  openrouter	OPENROUTER_API_KEY=<key>
  openai-codex	(empty string — no env var at this stage; OAuth fills the profile after Step 4.5)

Write to /tmp/openclaw-cloud-init.yaml with mode 600.

c. Create the security group:

SSH ingress is opened to everyone (0.0.0.0/0) on purpose — the user and the automation AI agent that manages this box both have dynamic IPs, so per-IP locking would lock out legitimate access and is not worth maintaining. The security controls are key-only auth + fail2ban (which bans only on FAILED auths, never an authenticated key user).

SG_ID=$(yc vpc security-group create \
  --name "${VM_NAME}-sg" \
  --network-id "$NETWORK_ID" \
  --rule "direction=ingress,port=22,protocol=tcp,v4-cidrs=[0.0.0.0/0]" \
  --rule "direction=egress,from-port=0,to-port=65535,protocol=any,v4-cidrs=[0.0.0.0/0]" \
  --format json | jq -r .id)

Note: use --network-id not --network-name. The named lookup fails silently in some yc CLI versions when the folder has multiple networks.

d. Create the instance. Try standard-v3 first (Intel Ice Lake), fall back to standard-v2 (Cascade Lake) if v3 isn't available in this folder:

PLATFORM=standard-v3
yc compute instance create \
  --name "${VM_NAME}" \
  --zone kz1-a \
  --platform "$PLATFORM" \
  --cores 2 --memory 4 \
  --network-interface "subnet-id=${SUBNET_ID},nat-ip-version=ipv4,security-group-ids=${SG_ID}" \
  --create-boot-disk "type=network-ssd,size=30,image-folder-id=standard-images,image-family=ubuntu-2404-lts" \
  --ssh-key ~/.ssh/id_ed25519.pub \
  --metadata-from-file user-data=/tmp/openclaw-cloud-init.yaml \
  --hostname "${VM_NAME}" \
  --format json > /tmp/openclaw-vm.json 2>/tmp/openclaw-vm.err

# If v3 not available in this folder, retry with v2.
if grep -qiE "platform.*not.*found|unsupported platform" /tmp/openclaw-vm.err; then
  yc compute instance create --platform standard-v2 ...   # same flags
fi

Capture external_ipv4_address from /tmp/openclaw-vm.json (.network_interfaces[0].primary_v4_address.one_to_one_nat.address). Then one sentence to the user:

VM создана. Ставлю OpenClaw — займёт около 10 минут. Можешь пока заварить чай.

If the instance create errors with billing account is not active or billing_disabled — that's the one billing case we couldn't detect in Step 0 (because there's no yc billing on KZ). Tell the user: "Похоже, в Yandex Cloud Kazakhstan не активирован биллинг. Открой https://kz.console.yandex.cloud/billing — там подсказка. Когда активируешь, запусти меня снова — VM подхвачу автоматически." Stop.

Step 3 — Wait silently for cloud-init

Poll every 30 seconds:

ssh -o StrictHostKeyChecking=accept-new -o ConnectTimeout=5 openclaw@$IP \
  'test -f /var/lib/openclaw-bootstrap-done && echo READY || echo PENDING'

Don't spam the user with raw log lines. Every ~3 minutes, emit one warm progress sentence based on the current phase you see in tail -1 /var/log/openclaw-bootstrap.log:

Cap at 15 minutes. If still not ready, surface to the user with a single sentence ("Что-то пошло не так на VM, проверяю логи") and jump to references/04-troubleshooting.md.

Step 3.5 — OAuth device-code flow (ONLY if LLM_PROVIDER=openai-codex)

Skip this entire step for anthropic and openrouter — they have the key already in gateway.env and the bot is ready to talk.

The provider id is openai-codex and the command openclaw models auth login --provider openai-codex --device-code is real and current (verified against OpenClaw docs/providers/openai.md — the device-code path exists specifically for headless/callback-hostile VMs; OpenClaw performs the OAuth itself and stores the profile as openai-codex:default). Do not rename the provider to codex (that is the agent-runtime id, a different concept) or shell out to a native codex login binary (not needed).

For openai-codex, the cloud-init left the gateway running but without a model configured (no Anthropic/OpenRouter key was in env). First make sure the Codex provider is loadable, then run the device-code OAuth flow now via SSH with a forced TTY:

# The openai-codex auth provider ships in the bundled `openai` extension, but on
# some builds the login errors with "No provider plugins found" until the Codex
# plugin is present. Ensure it once (idempotent, harmless if already there):
ssh openclaw@$IP "openclaw plugins install clawhub:@openclaw/codex 2>/dev/null || true"

ssh -tt -o ServerAliveInterval=30 openclaw@$IP \
  "openclaw models auth login --provider openai-codex --device-code" \
  | tee /tmp/openclaw-oauth.log

The CLI prints two things on stdout, usually within 2 seconds:

• A URL like https://auth.openai.com/codex/device (or https://auth.openai.com/device)
• An 8-character code like ABCD-1234

Extract both with a regex on /tmp/openclaw-oauth.log (the formats may shift slightly across OpenClaw releases — match generously). Show the user one clean message:

Последний шаг — подключи бота к ChatGPT.

Открой в браузере: https://auth.openai.com/codex/device

Введи код: ABCD-1234

Войди под аккаунтом ChatGPT (Plus или Pro) и разреши доступ. Жду до 15 минут.

The SSH session will block until the user completes the device flow (or the 15-minute server-side timeout expires). When it exits 0, OpenClaw has written auth-profiles.json with the OAuth token and the gateway will pick it up on next config reload.

Known pitfall (issue #74212, 2026-05): in some SSH sessions OpenClaw masks the device-pairing code as [shown on the local device only]. If that's what you see in /tmp/openclaw-oauth.log:

• Retry with ssh -tt if you didn't already — the masking is triggered by a TTY check that some non-interactive SSH invocations fail.
• If retry doesn't help: run the auth command directly inside a fresh SSH session (ssh openclaw@$IP → openclaw models auth login --provider openai-codex --device-code), pull the code from there, then resume the wizard.

After the profile is written, probe the subscription tier and set the model. Two things verified on a live OpenClaw 2026.5.27 bot: Codex subscription models are registered in the openai/ namespace (e.g. openai/gpt-5.5), not openai-codex/* — the openai-codex profile only backs the auth, so openclaw models list --provider openai-codex returns nothing; and the JSON flag for models list is --json, not --format json. So:

HAS_GPT55=$(ssh openclaw@$IP "openclaw models list --json 2>/dev/null" \
  | jq -r '.[]?.id // empty' 2>/dev/null | grep -Fx 'openai/gpt-5.5' || true)
if [[ -n "$HAS_GPT55" ]]; then
  # Pro tier — gpt-5.5 available
  ssh openclaw@$IP "openclaw config set agents.defaults.model.primary 'openai/gpt-5.5' && openclaw config set agents.defaults.model.fallbacks '[\"openai/gpt-5.4\"]'"
else
  # Plus tier (or gpt-5.5 not granted) — use the gpt-5.4 family
  ssh openclaw@$IP "openclaw config set agents.defaults.model.primary 'openai/gpt-5.4' && openclaw config set agents.defaults.model.fallbacks '[\"openai/gpt-5.4-mini\"]'"
fi
ssh openclaw@$IP "sudo systemctl restart openclaw-gateway"

If after 15 minutes the SSH session timed out and auth-profiles.json still has no openai-codex profile: tell the user "не получилось войти в ChatGPT, давай попробуем ещё раз" and re-run the SSH openclaw models auth login command. Don't kill the VM — only the OAuth step needs to be retried.

Step 4 — One-click chat link + auto-pair (the actual flow, not the easy one)

When /var/lib/openclaw-bootstrap-done exists, the gateway is up in pairing mode. This is where wizards historically fail silently: they think openclaw pairing approve succeeded, hand off to the user, and the user discovers the bot still asks for a confirmation code. Read this whole section.

What actually happens when the user presses /start

1. Telegram delivers /start to the bot.
2. OpenClaw enforces dmPolicy=pairing — it does not drop the message, it calls issuePairingChallenge(), records a pending request in the gateway, and the bot replies to the user with the pairing code + instructions (something like "To complete pairing, ask your admin to run openclaw pairing approve telegram ABCD-1234"). The user sees this message; they shouldn't reply to it.
3. The pending request lives in openclaw pairing list telegram --format json until either approved or expired.

Pre-emptive heads-up to the user

Send this before asking them to press /start, so they don't get confused when the bot's first reply is a code message:

Бот готов. Открой его в Telegram: https://t.me/{{BOT_USERNAME}} и нажми /start.

Бот пришлёт тебе короткое сообщение с кодом — ничего с ним делать не надо, я подтвержу доступ автоматически за пару секунд. После этого можешь начать переписываться с ботом как обычно.

Poll for chat_id (Telegram getUpdates)

# Empty getUpdates returns until the user actually presses /start
for i in $(seq 1 150); do  # 150 × 2s = 5 minutes
  CHAT_ID=$(curl -fsS "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/getUpdates?timeout=2" \
    | jq -r '.result[0].message.chat.id // empty')
  [[ -n "$CHAT_ID" ]] && break
  sleep 2
done
[[ -z "$CHAT_ID" ]] && fail "Пользователь не нажал /start за 5 минут"

Approve the pairing (the part the old wizard broke)

The pending pairing request lives in openclaw pairing list telegram --format json. Its schema (verified against src/gateway/protocol/schema/devices.ts) uses senderId for the Telegram user ID and requestId for the primary key — not chatId and not code. A wizard that filters on .chatId == $CHAT_ID always gets empty results and the subsequent xargs approve is a no-op.

Defensive filter (handles both schemas in case a future OpenClaw release renames again):

# Give the gateway up to 10s to record the pending request after /start arrives
APPROVE_TOKEN=""
for i in $(seq 1 5); do
  APPROVE_TOKEN=$(ssh openclaw@$IP "openclaw pairing list telegram --format json 2>/dev/null" \
    | jq -r --arg cid "$CHAT_ID" '
        .[]
        | select(
            (.senderId|tostring) == $cid
            or (.chatId|tostring) == $cid
            or (.sender // empty | tostring) == $cid
          )
        | (.requestId // .code // empty)
      ' \
    | head -n1)
  [[ -n "$APPROVE_TOKEN" ]] && break
  sleep 2
done

[[ -z "$APPROVE_TOKEN" ]] && fail "Запрос на pairing не появился в openclaw pairing list — посмотри journalctl на VM"

ssh openclaw@$IP "openclaw pairing approve telegram '$APPROVE_TOKEN'" \
  || fail "openclaw pairing approve failed (token=$APPROVE_TOKEN)"

Lock down + persist chat_id

ssh openclaw@$IP "
  openclaw config set channels.telegram.dmPolicy allowlist
  openclaw config set channels.telegram.allowFrom '[${CHAT_ID}]'
  echo 'TELEGRAM_CHAT_ID=${CHAT_ID}' >> /home/openclaw/.openclaw/gateway.env
  sudo systemctl restart openclaw-gateway
"

Wait ~60s for the gateway to come back. Don't proceed to Step 5 until /health returns 200:

for i in $(seq 1 30); do
  ssh openclaw@$IP 'curl -fsS -m 3 http://127.0.0.1:18789/health' >/dev/null 2>&1 && break
  sleep 2
done

If the user doesn't press /start within 5 minutes, poke them gently with a one-line reminder. After 15 minutes of no signal, stop and tell them how to resume.

Step 5 — Verify the bot answers (do NOT skip), then hand off

The wizard's #1 historical failure mode was claiming "done" while the bot was still silent. The verification below is mandatory — three independent signals, all must pass, before you tell the user it works.

5a. Trigger a reply

Send a probe message from the user's laptop, in the language set in Step 0 (USER_LANGUAGE):

# Language-matched probe text
case "$USER_LANGUAGE" in
  ru) PROBE="Скажи 'привет', чтобы я убедился, что ты отвечаешь." ;;
  kk) PROBE="Сәлем деп жаз — жауап беретіндігіңе көз жеткізейін." ;;
  *)  PROBE="Say 'hi' so I can confirm you're alive." ;;
esac

curl -fsS "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/sendMessage" \
  -d "chat_id=${CHAT_ID}" \
  -d "text=${PROBE}"

5b. Three checks, all required

Check 1 — Gateway logged an outgoing message. Watch the journal for an outbound telegram event within 90 seconds:

ssh openclaw@$IP "
  timeout 90 sudo journalctl -u openclaw-gateway -f --no-pager 2>/dev/null \
    | grep -m1 -E 'telegram.*sent|outgoing.*telegram|sendMessage.*ok'
"

If this times out: gateway accepted the inbound but didn't reply. Most likely cause = LLM provider not configured (Codex OAuth didn't finish, or env key empty). Jump to references/04-troubleshooting.md §4c-e.

Check 2 — A bot reply appears in getUpdates within 90s. Poll for any new update authored by the bot:

LAST_OFFSET=$(curl -fsS "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/getUpdates?offset=-1" \
  | jq -r '.result[-1].update_id // 0')

for i in $(seq 1 45); do
  REPLY=$(curl -fsS "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/getUpdates?offset=$((LAST_OFFSET+1))&timeout=2" \
    | jq -r '.result[]? | select(.message.from.is_bot==true) | .message.text' \
    | head -n1)
  [[ -n "$REPLY" ]] && break
  sleep 2
done

[[ -z "$REPLY" ]] && fail "Не вижу ответа бота в getUpdates через 90с"

Note: a bot's own outgoing messages don't appear in `getU

…(truncated)