ocuclaw 1.2.4 → 1.3.1

package/README.md

@@ -2,13 +2,16 @@
 
 OcuClaw is an OpenClaw plugin for Even G2 smart glasses. Use the OcuClaw application within Even Hub App Store to connect the client side.
 
+## Requirements
+
+OpenClaw `>= 2026.5.20` (older versions have a known plugin-install bug). Upgrade with `npm install -g openclaw@latest`.
+
 ## Install
 
 Install the plugin from the OpenClaw CLI:
 
 ```bash
 openclaw plugins install ocuclaw
-openclaw plugins enable ocuclaw
 ```
 
 ## Configure
@@ -18,7 +21,7 @@ Required:
 Set the OcuClaw relay token. This is a user-created password that must match the relay server token field in the OcuClaw application within Even Hub App Store.
 
 ```bash
-openclaw config set plugins.entries.ocuclaw.config.relayToken "<relay-token>"
+openclaw config set plugins.entries.ocuclaw.config.relayToken "your-relay-token"
 ```
 
 Recommended:
@@ -26,7 +29,7 @@ Recommended:
 - `sonioxApiKey`: Enables Soniox speech-to-text for voice input.
 
 ```bash
-openclaw config set plugins.entries.ocuclaw.config.sonioxApiKey "<soniox-api-key>"
+openclaw config set plugins.entries.ocuclaw.config.sonioxApiKey "your-soniox-api-key"
 ```
 
 - `evenAiEnabled`: Enables Even AI integration for OcuClaw.
@@ -38,18 +41,30 @@ openclaw config set plugins.entries.ocuclaw.config.evenAiEnabled true --strict-j
 - `evenAiToken`: Sets the user-created password for Even AI requests. This must match the password set in the Even AI Agent Configure section within the Even Realities app.
 
 ```bash
-openclaw config set plugins.entries.ocuclaw.config.evenAiToken "<even-ai-token>"
+openclaw config set plugins.entries.ocuclaw.config.evenAiToken "your-even-ai-token"
 ```
 
+> **Note:** When `evenAiEnabled` is `true`, `evenAiToken` is required. Config validation will reject the change if you enable Even AI without setting the token.
+
 Advanced optional settings:
 
 ```bash
 openclaw config set plugins.entries.ocuclaw.config.wsBind "127.0.0.1"
-openclaw config set plugins.entries.ocuclaw.config.wsPort 9000 --strict-json
+# wsPort default is 9000; on Windows that port is often reserved by WinNAT, so the
+# setup assistant uses 47800. Pick any free port in 30000-49151 if you override it.
+openclaw config set plugins.entries.ocuclaw.config.wsPort 47800 --strict-json
 openclaw config set plugins.entries.ocuclaw.config.sessionLimit 10 --strict-json
 openclaw config set plugins.entries.ocuclaw.config.externalDebugToolsEnabled true --strict-json
 ```
 
+Run `openclaw plugins inspect ocuclaw` to see all settings with their descriptions and defaults.
+
+## Enable
+
+```bash
+openclaw plugins enable ocuclaw
+```
+
 ## Restart
 
 Restart the gateway so the plugin and config changes take effect:
@@ -61,7 +76,7 @@ openclaw gateway restart
 ## Verify
 
 ```bash
-openclaw plugins inspect ocuclaw
+openclaw plugins inspect ocuclaw --runtime
 openclaw plugins doctor
 openclaw gateway status
 ```

package/dist/config/runtime-config.js

@@ -97,6 +97,59 @@ function resolveDebugNoisyPolicies(pluginValue, envValue) {
   return parseJsonOrUndefined(envValue, "debugNoisyPolicies");
 }
 
+// Supported live-refresh LLM backends — both are HTTP API backends. The two
+// CLI-spawn backends were removed: codex-cli because Codex's read-only sandbox
+// still permits filesystem reads (an agent prompt could exfil ~/.aws/credentials,
+// ~/.ssh/*, etc. via stdout into the glasses surface), and claude-cli to remove
+// the plugin's last child_process spawn so the OpenClaw installer's static
+// dangerous-code scanner passes without --dangerously-force-unsafe-install. (The
+// scanner can't see that --tools "" made the CLI tool-less; it just sees a spawn.
+// This is not an exploit claim about claude-cli — it removes spawn surface and
+// clears the static block.) The proper agentic tier — delegating ticks to the
+// native OpenClaw runtime instead of spawning a CLI — is tracked separately (the
+// glasses-ui L1/L2 delegation redesign) and blocked on request-scoped
+// api.runtime.subagent.run. Operators who want Claude/Codex point an *-api
+// backend at the provider endpoint (key resolved via the host modelAuth).
+const GLASSES_UI_LIVE_BACKENDS = new Set([
+  "anthropic-api",
+  "openai-compat",
+]);
+
+const GLASSES_UI_LIVE_DEFAULT_MODEL = {
+  "anthropic-api": "anthropic/claude-haiku-4-5-20251001",
+  "openai-compat": "gpt-4o-mini",
+};
+
+function resolveGlassesUiLive(value) {
+  const raw = isObject(value) ? value : {};
+  // Unknown/removed backends (incl. a stale tickBackend: "claude-cli" or
+  // "codex-cli" from an operator's pre-removal config) coerce to this default.
+  const tickBackend = GLASSES_UI_LIVE_BACKENDS.has(raw.tickBackend)
+    ? raw.tickBackend
+    : "anthropic-api";
+  const tickModel = pickString(raw.tickModel) || GLASSES_UI_LIVE_DEFAULT_MODEL[tickBackend];
+  const tickApiBaseUrl = pickString(raw.tickApiBaseUrl) || "https://api.openai.com";
+  return {
+    enabled: parseBool(raw.enabled, true),
+    tickBackend,
+    tickModel,
+    tickApiBaseUrl,
+    allowAgentModelOverride: parseBool(raw.allowAgentModelOverride, false),
+    tickMaxOutputTokens: parseIntOrDefault(raw.tickMaxOutputTokens, 200),
+    // http recipes issue agent-influenced outbound network requests on a
+    // schedule. The recipe executor blocks loopback/RFC1918/link-local
+    // destinations and resolves hostnames through an SSRF-safe dispatcher,
+    // but the capability — "the plugin's gateway host can fetch arbitrary
+    // public URLs the agent chooses" — is itself worth an operator opt-in.
+    // Default to disabled; set
+    // plugins.entries.ocuclaw.config.glassesUiLive.httpEnabled = true to
+    // enable. The dispatcher protection still applies once enabled.
+    httpEnabled: parseBool(raw.httpEnabled, false),
+    llmEnabled: parseBool(raw.llmEnabled, true),
+    maxConcurrentSurfacesPerHost: parseIntOrDefault(raw.maxConcurrentSurfacesPerHost, 4),
+  };
+}
+
 export function createRuntimeConfig(opts = {}) {
   const pluginConfig = isObject(opts.pluginConfig) ? opts.pluginConfig : {};
   const openclawConfig = isObject(opts.openclawConfig) ? opts.openclawConfig : {};
@@ -106,7 +159,13 @@ export function createRuntimeConfig(opts = {}) {
 
   if (!relayToken) {
     throw new Error(
-      "OcuClaw relayToken is required. Set plugins.entries.ocuclaw.config.relayToken.",
+      [
+        "OcuClaw relayToken is required.",
+        "Set the plugin config with:",
+        '  openclaw config set plugins.entries.ocuclaw.config.relayToken "your-token"',
+        "The same token must be entered in the OcuClaw app's relay server token field within Even Hub.",
+        "Then restart the gateway: openclaw gateway restart",
+      ].join("\n"),
     );
   }
   if (!gatewayUrl) {
@@ -120,6 +179,22 @@ export function createRuntimeConfig(opts = {}) {
     );
   }
 
+  const evenAiEnabled = parseBool(pluginConfig.evenAiEnabled, false);
+  const evenAiToken = pickString(pluginConfig.evenAiToken);
+  if (evenAiEnabled && !evenAiToken) {
+    throw new Error(
+      [
+        "OcuClaw evenAiToken is required when evenAiEnabled is true.",
+        "Set the plugin config with:",
+        '  openclaw config set plugins.entries.ocuclaw.config.evenAiToken "your-token"',
+        "The same token must be entered as the password in the Even AI Agent Configure section of the Even Realities app.",
+        "To disable Even AI instead, run:",
+        "  openclaw config set plugins.entries.ocuclaw.config.evenAiEnabled false --strict-json",
+        "Then restart the gateway: openclaw gateway restart",
+      ].join("\n"),
+    );
+  }
+
   return {
     gatewayUrl,
     gatewayToken,
@@ -140,8 +215,8 @@ export function createRuntimeConfig(opts = {}) {
       pluginConfig.externalDebugToolsEnabled,
       false,
     ),
-    evenAiEnabled: parseBool(pluginConfig.evenAiEnabled, false),
-    evenAiToken: pickString(pluginConfig.evenAiToken),
+    evenAiEnabled,
+    evenAiToken,
     evenAiSystemPrompt: pickString(pluginConfig.evenAiSystemPrompt),
     evenAiRequestTimeoutMs: parseIntOrDefault(
       pluginConfig.evenAiRequestTimeoutMs,
@@ -159,6 +234,12 @@ export function createRuntimeConfig(opts = {}) {
     evenAiDedicatedSessionKey: parseEvenAiDedicatedSessionKey(
       pluginConfig.evenAiDedicatedSessionKey,
     ),
+    renderGlassesUiTimeoutMs: parseIntOrDefault(
+      pluginConfig.renderGlassesUiTimeoutMs,
+      30 * 60 * 1000,
+    ),
+    glassesUiLive: resolveGlassesUiLive(pluginConfig.glassesUiLive),
+    freshnessWindowMs: parseIntOrDefault(pluginConfig.freshnessWindowMs, 5000),
   };
 }