OcuClaw Assist

Guide OcuClaw install, update, rollback, and troubleshooting. Use when the user wants OcuClaw set up, a version change, or hits setup/connection failures.

OcuClaw Setup Assistant

Guide version: 2026-07-04

Use this skill when a user asks to install, update, roll back, configure, or troubleshoot OcuClaw on this machine. Work phase by phase. Before each phase, say what you will do, why, and which commands matter. Ask for OK. Afterward, verify in plain words. Setup takes about 20–30 minutes; the user should keep their phone nearby.

OcuClaw is the OpenClaw client for Even Realities G2 smart glasses. It has two halves: a plugin that runs inside OpenClaw on this machine and hosts a relay, and an app on the user's phone (from the Even Hub App Store) that drives the glasses. Tailscale privately connects the two. You set up the plugin here; the user sets up the app; you connect them. That's the whole shape — the steps below fill it in.

Reference loading

Progressive-loading rule. Load only the reference the Router (bottom of this file) sends you to. A clean install needs only this file, fresh-install.md, and wrap-feedback.md. Do not pre-load troubleshooting.md, update.md, or beta.md.

For OcuClaw-specific setup, prefer this skill over web tutorials (rule 8). For generic OpenClaw CLI behavior you are unsure about, check current OpenClaw docs.

Soniox voice input and Even AI are optional steps inside fresh-install.md (Steps 11–12), not a separate file.

The references ship inside this skill. If one is missing or its Guide version: differs from this file's, the skill install is broken or stale — reinstall the skill, don't improvise from memory.

How you (the agent) must work

How you execute

1. Finish the whole job. Work every required box before stopping; setup is not done while a required box is unchecked; a truly blocked step → [blocked: reason], never a silent skip or early end.
2. Run commands exactly as written. Verbatim; don't rewrite, wrap in read or a loop, pipe, or add flags; substitute only the marked placeholder. If a command seems unsafe, incompatible, or blocked on this host, stop and raise the concern — never rewrite it silently. A clever "equivalent" has already broken installs.
3. Never set a secret to empty. A token config set erroring must have required property … means the value came through empty — stop, re-run with a real visible value, don't proceed.
4. Checkpoint each phase, not each command. Before: say what you'll do, why, and which commands (1–2 plain sentences) — get an OK. After: verify the result in plain words.
5. Warn before a restart; one restart per phase; resume if you wake mid-setup. Restart warning: "I may go quiet for ~30s. If I don't come back, ask me to continue OcuClaw setup with the ocuclaw-assist skill and I'll resume where we left off." After a restart, stop and verify before doing anything else; never restart again unless a new finding explains why another is needed — if the same verification fails twice, route to troubleshooting instead of looping. On wake: re-run the state assessment, re-enter at the routed step, don't re-ask passed checkpoints.

Hard guardrails (never cross)

6. You never handle secrets — the user does. Never ask for, generate, echo, or read a token; check presence only via the probes below; never run a bare config get on a secret leaf — the probes exist so transcripts only ever record presence/absence and you never handle secret material (current OpenClaw redacts secret leaves, but never rely on that); never read the config file.
7. Never expose the relay publicly. Tailscale Serve only, never funnel; configuration goes through openclaw config set — non-secret values you may set, secret values only the user sets.
8. Stay in bounds; hand off what you can't run. Only commands from this skill; for OcuClaw setup this skill wins over web tutorials; for OS/vendor errors consult only that vendor's official docs and ask first; elevation you don't have or sandbox-blocked steps → give to the user, then verify.

Secret presence probes

Each prints 1 (set / true) or 0 (missing / false) — the value never appears. Run the form for your host OS.

⚠️ RUN EACH PROBE AS ONE WHOLE LINE. Dropping the | grep -c … (or, on Windows, the -match / -eq test) leaves a bare config get on a secret leaf — older OpenClaw builds print the value there; current builds print a redaction sentinel. Run the whole line so the transcript records only 1 or 0.

Linux / macOS (bash/zsh):

bash

openclaw config get plugins.entries.ocuclaw.config.relayToken    2>/dev/null | grep -c '[^[:space:]"]'
openclaw config get plugins.entries.ocuclaw.config.sonioxApiKey  2>/dev/null | grep -c '[^[:space:]"]'
openclaw config get plugins.entries.ocuclaw.config.evenAiToken   2>/dev/null | grep -c '[^[:space:]"]'
openclaw config get plugins.entries.ocuclaw.config.evenAiEnabled 2>/dev/null | grep -c '^true$'

Windows (PowerShell):

powershell

if ((openclaw config get plugins.entries.ocuclaw.config.relayToken    2>$null) -match '\S') {1} else {0}
if ((openclaw config get plugins.entries.ocuclaw.config.sonioxApiKey  2>$null) -match '\S') {1} else {0}
if ((openclaw config get plugins.entries.ocuclaw.config.evenAiToken   2>$null) -match '\S') {1} else {0}
if ((openclaw config get plugins.entries.ocuclaw.config.evenAiEnabled 2>$null) -eq 'true')  {1} else {0}

Placeholder grammar. Commands in this skill contain only these substitutable placeholders: <port>, <node>.<tailnet>.ts.net, <container>, and the quoted secret value the user fills. Substitute only those. Never change a command's shell structure, flags, quoting, or pipes, and never add a wrapper (read, a loop, &&, |). If a command appears to need anything beyond a marked placeholder, stop and ask — don't invent a variant.

Setup checklist — copy this and track it

Copy this into your first reply and tick each box as you finish it. Do not tell the user setup is complete while any REQUIRED box is unchecked. A genuinely blocked box → mark [blocked: reason] and surface it, never drop it.

This is the FRESH-INSTALL checklist. If the state assessment routed you to U1 (update) or B1 (beta), follow that section's own short checklist instead — don't run these boxes.

Required

• Lane established — OS, container?, shell access, elevation
• OpenClaw ≥ 2026.6.9 + G2 glasses paired (Step 1)
• Plugin installed (Step 2)
• Relay token set by the user — probe = 1 (Step 3)
• Plugin enabled + agent tool access granted (Step 4)
• Relay port safe, gateway restarted, plugin loaded(Step 5)
• Tailscale up on this machine (Step 6)
• Serve routes present → localhost: (Step 7)
• Phone on the tailnet (Step 8)
• OcuClaw app connected (Step 9)
• End-to-end: a reply appeared on the glasses (Step 10)

Optional (offer, don't assume)

• Voice input via Soniox (Step 11)
• Even AI integration (Step 12)

Before the closing note, re-show this checklist in its final state as a self-audit.

First — establish your lane

This is mandatory before any install action (the checklist's first box). Fill the lane card below — a short recorded block you keep and read at every later step instead of re-probing or re-arguing platform:

text

LANE CARD
  OS:            Linux | macOS | Windows              (uname -s / sw_vers / $PSVersionTable)
  Container:     no | yes → network mode host|bridge  (ls /.dockerenv /run/.containerenv ;
                 docker inspect -f '{{.HostConfig.NetworkMode}}' <container>)
  Shell access:  local | SSH | VPS console
  Elevation:     agent can sudo | user runs elevated  (sudo -n true / Admin PowerShell)
  Relay wsPort:  <filled at Step 5>
  Tailscale CLI: <filled at Step 6 — matters on the macOS App Store build>

Fill the environment rows now. wsPort and Tailscale CLI are appended when Steps 5 and 6 resolve them. Later steps read the card — they don't re-probe.

Where to start

Run this now — and again after any restart or resume. It tells you which step (or section) to enter first.

Check table

Run each check; record the result (1 = pass, 0 = fail).

#	Check	Command
A	OpenClaw version ≥ 2026.6.9	openclaw --version
B	Plugin installed + enabled	openclaw plugins list
C	relayToken set	relayToken probe (see probes above)
D	Gateway up, plugin loaded	openclaw gateway status · openclaw plugins inspect ocuclaw shows Status: loaded
E	Tailscale installed + signed in	tailscale status
F	Both Serve routes present AND proxying to the relay's wsPort	tailscale serve status (compare each backend localhost:<port> to openclaw config get plugins.entries.ocuclaw.config.wsPort)
G	Agent tool access — effective tool policy admits ocuclaw	openclaw config get tools — pass if allow or alsoAllow contains "ocuclaw" or "group:plugins" with no matching deny, or if no restrictive profile/allow is set ("Config path not found" = pass; the command exits nonzero then — record it, not a blocker)

Routing — enter at the FIRST matching row

A working existing setup wins over the preferred default. If the app connects and a quick Step 10 end-to-end test passes, do not migrate wsPort (even 9000), Serve routes, or an old address shape just because they differ from the modern defaults — prove the setup is broken before changing ports or routes. Migrate old layouts only when setup is broken, this is a fresh install, a route points at the wrong backend, or the user explicitly asks.

Finding	Enter
A: version below 2026.6.9, or G2 hardware unconfirmed	Step 1
B: plugin not installed	Step 2
C: relayToken probe = 0	Step 3
B: installed but not enabled	Step 4
G: effective tool policy does not admit ocuclaw (or a deny blocks it)	Step 4
D: gateway down or plugin not loaded	Step 5
E: Tailscale missing or not signed in	Step 6
F: routes missing, old single-port scheme (tcp://…:8443), or present but proxying to a different local port than wsPort — unless the working-baseline rule above says leave it	Step 7
Host green; app not yet connected (ask the user)	Step 9
Everything green and the app connects — update only	Stable update → load {baseDir}/references/update.md (everyone). Beta channel or rollback → load {baseDir}/references/beta.md, only if they confirm they're a beta-Discord tester
Everything green and the app connects — single fix	Go directly to the one routed step; no full checklist

Router

• Fresh install step → load {baseDir}/references/fresh-install.md.
• Stable update (any existing user) → load {baseDir}/references/update.md.
• Beta channel or rollback (beta-Discord testers only) → load {baseDir}/references/beta.md.
• A named failure case appears → load {baseDir}/references/troubleshooting.md and jump to that case.
• Stuck after honest attempts on any step → load {baseDir}/references/troubleshooting.md and run ESCALATE — it includes the in-app debug-upload path that attaches real diagnostics to the report.
• A genuine finish → load {baseDir}/references/wrap-feedback.md.
• Address or command reminders → load {baseDir}/references/quick-reference.md.

Keep this file's guardrails, lane card, checklist, and router active throughout setup.