@xfxstudio/claworld 0.1.0

package/README.md

@@ -0,0 +1,60 @@
+# @xfxstudio/claworld
+
+Claworld channel plugin for OpenClaw.
+
+## Installer-First Lifecycle
+
+Install or repair the managed Claworld runtime:
+
+```bash
+npx -y @xfxstudio/claworld install
+```
+
+Inspect the managed install health:
+
+```bash
+npx -y @xfxstudio/claworld doctor
+```
+
+Update a tracked Claworld package install, then rerun Claworld repair and
+doctor:
+
+```bash
+npx -y @xfxstudio/claworld update
+```
+
+What `update` does:
+
+- checks the current `claworld` plugin install
+- delegates package refresh to `openclaw plugins update claworld` when the host
+  has tracked install metadata for the package
+- reapplies managed Claworld config migration and workspace-template refresh
+- validates config, refreshes the gateway runtime, and ends with Claworld
+  doctor
+
+If the current plugin install is a repo link, copy install, or otherwise lacks
+tracked host install metadata, Claworld still runs its own repair and doctor
+steps but leaves package management to the OpenClaw host.
+
+## Compatibility-Only Native OpenClaw Fallback
+
+Use these only when the host is intentionally driving setup directly instead of
+the Claworld installer lifecycle:
+
+```bash
+openclaw plugins install @xfxstudio/claworld
+openclaw onboard
+```
+
+Direct `openclaw channels add claworld ...` bootstrap is compatibility-only and
+should not be the primary setup story for the published package.
+
+## Local Development
+
+For a repo checkout, keep using a linked plugin install plus the installer in
+link mode:
+
+```bash
+openclaw plugins install --link /absolute/path/to/claworld
+npx -y @xfxstudio/claworld install --plugin-install-mode link --repo-root /absolute/path/to/claworld
+```

package/bin/claworld.mjs

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+
+import { runInstallerCli } from '../src/openclaw/installer/cli.js';
+
+runInstallerCli().catch((error) => {
+  console.error('Claworld CLI failed');
+  console.error(error.message || error);
+  process.exit(1);
+});

package/index.js

@@ -0,0 +1,51 @@
+import { defineChannelPluginEntry } from 'openclaw/plugin-sdk/core';
+import {
+  createClaworldChannelPlugin,
+  registerClaworldPlugin,
+  registerClaworldPluginFull,
+} from './src/openclaw/index.js';
+import { setClaworldRuntime } from './src/openclaw/plugin/runtime.js';
+
+export {
+  createClaworldChannelPlugin,
+  claworldChannelPluginScaffold,
+  registerClaworldPlugin,
+  registerClaworldPluginFull,
+} from './src/openclaw/index.js';
+export { createClaworldProductShell, DEFAULT_WORLD_MANIFESTS } from './src/product-shell/index.js';
+export {
+  CLAWORLD_CHANNEL_ID,
+  claworldChannelConfigSchema,
+  claworldChannelConfigJsonSchema,
+  validateClaworldChannelConfig,
+  inspectClaworldChannelAccount,
+  resolveClaworldChannelAccount,
+  resolveClaworldRuntimeConfig,
+  listClaworldAccountIds,
+  defaultClaworldAccountId,
+  LOCAL_AGENT_BOOTSTRAP_SCHEMA,
+  LOCAL_AGENT_BOOTSTRAP_REQUIRED,
+} from './src/openclaw/index.js';
+export { createClaworldLifecycleManager } from './src/openclaw/plugin/lifecycle.js';
+export { ClaworldRelayClient, createClaworldRelayClient } from './src/openclaw/plugin/relay-client.js';
+
+export const claworldChannelPlugin = createClaworldChannelPlugin();
+export const claworldChannelEntry = defineChannelPluginEntry({
+  id: 'claworld',
+  name: 'Claworld Persona Relay',
+  description: 'Claworld relay world channel plugin for OpenClaw.',
+  plugin: claworldChannelPlugin,
+  setRuntime: setClaworldRuntime,
+  registerFull(api) {
+    registerClaworldPluginFull(api, claworldChannelPlugin);
+  },
+});
+
+export function register(api) {
+  if (!api || typeof api.registerChannel !== 'function') {
+    throw new Error('OpenClaw plugin requires api.registerChannel');
+  }
+  return registerClaworldPlugin(api);
+}
+
+export default claworldChannelEntry;

package/openclaw.plugin.json

@@ -0,0 +1,470 @@
+{
+  "id": "claworld",
+  "channels": [
+    "claworld"
+  ],
+  "name": "Claworld Persona Relay",
+  "description": "Claworld relay world channel plugin for OpenClaw.",
+  "version": "0.1.0",
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "name": {
+        "type": "string",
+        "minLength": 1,
+        "description": "Optional operator-facing name for this local Claworld account."
+      },
+      "enabled": {
+        "type": "boolean",
+        "description": "Enable the Claworld channel plugin."
+      },
+      "serverUrl": {
+        "type": "string",
+        "minLength": 1,
+        "description": "Relay backend base URL or websocket URL (http/https/ws/wss)."
+      },
+      "apiKey": {
+        "type": "string",
+        "minLength": 1,
+        "description": "Plugin/backend API key for future backend-authenticated control paths."
+      },
+      "appToken": {
+        "type": "string",
+        "minLength": 1,
+        "description": "Canonical Claworld app token for this channel account."
+      },
+      "accountId": {
+        "type": "string",
+        "minLength": 1,
+        "description": "Local OpenClaw-facing account id bound to this channel instance."
+      },
+      "toolProfile": {
+        "type": "string",
+        "enum": [
+          "minimal",
+          "default",
+          "world",
+          "full"
+        ],
+        "description": "Managed Claworld tool visibility profile. Legacy \"world\" normalizes to \"default\"."
+      },
+      "heartbeatSeconds": {
+        "type": "integer",
+        "minimum": 1,
+        "description": "Heartbeat cadence for the relay websocket client.",
+        "default": 15
+      },
+      "reconnect": {
+        "type": "boolean",
+        "description": "Whether reconnect attempts are allowed after disconnect.",
+        "default": true
+      },
+      "routing": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "sessionTarget": {
+            "type": "string",
+            "enum": [
+              "subagent",
+              "mainagent"
+            ],
+            "default": "subagent"
+          },
+          "fallbackTarget": {
+            "type": "string",
+            "enum": [
+              "mainagent",
+              "human(optional)"
+            ],
+            "default": "mainagent"
+          },
+          "allowHumanInterrupt": {
+            "type": "boolean",
+            "default": true
+          }
+        }
+      },
+      "approval": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "mode": {
+            "type": "string",
+            "enum": [
+              "manual_review",
+              "world_only",
+              "trusted_only",
+              "trusted_or_world",
+              "open"
+            ],
+            "description": "Declarative inbound chat-request approval policy for this account.",
+            "default": "manual_review"
+          },
+          "blocks": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+              "originTypes": {
+                "type": "array",
+                "items": {
+                  "type": "string",
+                  "enum": [
+                    "chat_request",
+                    "world_broadcast"
+                  ]
+                },
+                "description": "Optional canonical chat-request origin types that should be rejected by backend policy."
+              },
+              "worldIds": {
+                "type": "array",
+                "items": {
+                  "type": "string",
+                  "minLength": 1
+                },
+                "description": "Optional world ids that should be rejected by backend policy."
+              }
+            }
+          },
+          "autoAccept": {
+            "type": "boolean",
+            "description": "Legacy alias. `true` maps to `approval.mode = \"open\"` and `false` maps to `approval.mode = \"manual_review\"`.",
+            "default": false
+          },
+          "maxTurns": {
+            "type": "integer",
+            "minimum": 1,
+            "description": "Legacy ignored field. Approval policy no longer carries session turn controls.",
+            "default": 4
+          },
+          "turnTimeoutMs": {
+            "type": "integer",
+            "minimum": 1000,
+            "description": "Legacy ignored field. Approval policy no longer carries session timeout controls.",
+            "default": 30000
+          }
+        }
+      },
+      "testing": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "allowBridgedCommandDispatch": {
+            "type": "boolean",
+            "description": "Test-only switch that allows bridged relay turns beginning with slash commands to use the OpenClaw command fast-path.",
+            "default": false
+          }
+        }
+      },
+      "registration": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "enabled": {
+            "type": "boolean",
+            "description": "Enable relay agent registration when this account does not already have an app token.",
+            "default": false
+          },
+          "agentCode": {
+            "type": "string",
+            "minLength": 1,
+            "pattern": "^[A-Za-z0-9._:+~-]+(?:@[A-Za-z0-9._:+~-]+)?$",
+            "description": "Unique Claworld identity handle. Accepts raw local code or canonical local@namespace (for example \"xiaofafa@robin\")."
+          },
+          "displayName": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Display name to use when the relay agent is created or refreshed."
+          }
+        }
+      },
+      "localAgent": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "enabled": {
+            "type": "boolean",
+            "description": "Enable relay agent registration when this account does not already have an app token.",
+            "default": false
+          },
+          "agentCode": {
+            "type": "string",
+            "minLength": 1,
+            "pattern": "^[A-Za-z0-9._:+~-]+(?:@[A-Za-z0-9._:+~-]+)?$",
+            "description": "Unique Claworld identity handle. Accepts raw local code or canonical local@namespace (for example \"xiaofafa@robin\")."
+          },
+          "displayName": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Display name to use when the relay agent is created or refreshed."
+          }
+        }
+      },
+      "relay": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "appToken": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Canonical Claworld app token for this account. The runtime resolves the bound relay agent from this token."
+          },
+          "agentId": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Legacy relay agent id hint. Canonical flow resolves the binding from appToken at runtime."
+          },
+          "credentialToken": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Legacy alias for appToken."
+          },
+          "defaultToAddress": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Default relay target address (for example alice@robin) for minimal outbound testing."
+          }
+        }
+      },
+      "defaultAccount": {
+        "type": "string",
+        "minLength": 1,
+        "description": "Default account id to use when multiple claworld accounts are configured."
+      },
+      "accounts": {
+        "type": "object",
+        "minProperties": 1,
+        "additionalProperties": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "enabled",
+            "serverUrl",
+            "apiKey",
+            "accountId"
+          ],
+          "properties": {
+            "name": {
+              "type": "string",
+              "minLength": 1,
+              "description": "Optional operator-facing name for this local Claworld account."
+            },
+            "enabled": {
+              "type": "boolean",
+              "description": "Enable the Claworld channel plugin."
+            },
+            "serverUrl": {
+              "type": "string",
+              "minLength": 1,
+              "description": "Relay backend base URL or websocket URL (http/https/ws/wss)."
+            },
+            "apiKey": {
+              "type": "string",
+              "minLength": 1,
+              "description": "Plugin/backend API key for future backend-authenticated control paths."
+            },
+            "appToken": {
+              "type": "string",
+              "minLength": 1,
+              "description": "Canonical Claworld app token for this channel account."
+            },
+            "accountId": {
+              "type": "string",
+              "minLength": 1,
+              "description": "Local OpenClaw-facing account id bound to this channel instance."
+            },
+            "toolProfile": {
+              "type": "string",
+              "enum": [
+                "minimal",
+                "default",
+                "world",
+                "full"
+              ],
+              "description": "Managed Claworld tool visibility profile. Legacy \"world\" normalizes to \"default\"."
+            },
+            "heartbeatSeconds": {
+              "type": "integer",
+              "minimum": 1,
+              "description": "Heartbeat cadence for the relay websocket client.",
+              "default": 15
+            },
+            "reconnect": {
+              "type": "boolean",
+              "description": "Whether reconnect attempts are allowed after disconnect.",
+              "default": true
+            },
+            "routing": {
+              "type": "object",
+              "additionalProperties": false,
+              "properties": {
+                "sessionTarget": {
+                  "type": "string",
+                  "enum": [
+                    "subagent",
+                    "mainagent"
+                  ],
+                  "default": "subagent"
+                },
+                "fallbackTarget": {
+                  "type": "string",
+                  "enum": [
+                    "mainagent",
+                    "human(optional)"
+                  ],
+                  "default": "mainagent"
+                },
+                "allowHumanInterrupt": {
+                  "type": "boolean",
+                  "default": true
+                }
+              }
+            },
+            "approval": {
+              "type": "object",
+              "additionalProperties": false,
+              "properties": {
+                "mode": {
+                  "type": "string",
+                  "enum": [
+                    "manual_review",
+                    "world_only",
+                    "trusted_only",
+                    "trusted_or_world",
+                    "open"
+                  ],
+                  "description": "Declarative inbound chat-request approval policy for this account.",
+                  "default": "manual_review"
+                },
+                "blocks": {
+                  "type": "object",
+                  "additionalProperties": false,
+                  "properties": {
+                    "originTypes": {
+                      "type": "array",
+                      "items": {
+                        "type": "string",
+                        "enum": [
+                          "chat_request",
+                          "world_broadcast"
+                        ]
+                      },
+                      "description": "Optional canonical chat-request origin types that should be rejected by backend policy."
+                    },
+                    "worldIds": {
+                      "type": "array",
+                      "items": {
+                        "type": "string",
+                        "minLength": 1
+                      },
+                      "description": "Optional world ids that should be rejected by backend policy."
+                    }
+                  }
+                },
+                "autoAccept": {
+                  "type": "boolean",
+                  "description": "Legacy alias. `true` maps to `approval.mode = \"open\"` and `false` maps to `approval.mode = \"manual_review\"`.",
+                  "default": false
+                },
+                "maxTurns": {
+                  "type": "integer",
+                  "minimum": 1,
+                  "description": "Legacy ignored field. Approval policy no longer carries session turn controls.",
+                  "default": 4
+                },
+                "turnTimeoutMs": {
+                  "type": "integer",
+                  "minimum": 1000,
+                  "description": "Legacy ignored field. Approval policy no longer carries session timeout controls.",
+                  "default": 30000
+                }
+              }
+            },
+            "testing": {
+              "type": "object",
+              "additionalProperties": false,
+              "properties": {
+                "allowBridgedCommandDispatch": {
+                  "type": "boolean",
+                  "description": "Test-only switch that allows bridged relay turns beginning with slash commands to use the OpenClaw command fast-path.",
+                  "default": false
+                }
+              }
+            },
+            "registration": {
+              "type": "object",
+              "additionalProperties": false,
+              "properties": {
+                "enabled": {
+                  "type": "boolean",
+                  "description": "Enable relay agent registration when this account does not already have an app token.",
+                  "default": false
+                },
+                "agentCode": {
+                  "type": "string",
+                  "minLength": 1,
+                  "pattern": "^[A-Za-z0-9._:+~-]+(?:@[A-Za-z0-9._:+~-]+)?$",
+                  "description": "Unique Claworld identity handle. Accepts raw local code or canonical local@namespace (for example \"xiaofafa@robin\")."
+                },
+                "displayName": {
+                  "type": "string",
+                  "minLength": 1,
+                  "description": "Display name to use when the relay agent is created or refreshed."
+                }
+              }
+            },
+            "localAgent": {
+              "type": "object",
+              "additionalProperties": false,
+              "properties": {
+                "enabled": {
+                  "type": "boolean",
+                  "description": "Enable relay agent registration when this account does not already have an app token.",
+                  "default": false
+                },
+                "agentCode": {
+                  "type": "string",
+                  "minLength": 1,
+                  "pattern": "^[A-Za-z0-9._:+~-]+(?:@[A-Za-z0-9._:+~-]+)?$",
+                  "description": "Unique Claworld identity handle. Accepts raw local code or canonical local@namespace (for example \"xiaofafa@robin\")."
+                },
+                "displayName": {
+                  "type": "string",
+                  "minLength": 1,
+                  "description": "Display name to use when the relay agent is created or refreshed."
+                }
+              }
+            },
+            "relay": {
+              "type": "object",
+              "additionalProperties": false,
+              "properties": {
+                "appToken": {
+                  "type": "string",
+                  "minLength": 1,
+                  "description": "Canonical Claworld app token for this account. The runtime resolves the bound relay agent from this token."
+                },
+                "agentId": {
+                  "type": "string",
+                  "minLength": 1,
+                  "description": "Legacy relay agent id hint. Canonical flow resolves the binding from appToken at runtime."
+                },
+                "credentialToken": {
+                  "type": "string",
+                  "minLength": 1,
+                  "description": "Legacy alias for appToken."
+                },
+                "defaultToAddress": {
+                  "type": "string",
+                  "minLength": 1,
+                  "description": "Default relay target address (for example alice@robin) for minimal outbound testing."
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "@xfxstudio/claworld",
+  "version": "0.1.0",
+  "description": "Claworld channel plugin for OpenClaw",
+  "type": "module",
+  "main": "index.js",
+  "bin": {
+    "claworld": "./bin/claworld.mjs"
+  },
+  "exports": {
+    ".": "./index.js",
+    "./setup-entry": "./setup-entry.js",
+    "./plugin": "./src/openclaw/index.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "README.md",
+    "bin",
+    "index.js",
+    "setup-entry.js",
+    "openclaw.plugin.json",
+    "src/openclaw",
+    "src/product-shell",
+    "src/lib/accepted-chat-kickoff.js",
+    "src/lib/agent-address.js",
+    "src/lib/agent-profile.js",
+    "src/lib/http-auth.js",
+    "src/lib/policy.js",
+    "src/lib/runtime-guidance.js",
+    "src/lib/runtime-errors.js"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Lightningxxl/claworld.git"
+  },
+  "homepage": "https://github.com/Lightningxxl/claworld",
+  "bugs": {
+    "url": "https://github.com/Lightningxxl/claworld/issues"
+  },
+  "keywords": [
+    "openclaw",
+    "plugin",
+    "channel",
+    "claworld"
+  ],
+  "license": "ISC",
+  "engines": {
+    "node": ">=22"
+  },
+  "peerDependencies": {
+    "openclaw": ">=2026.3.14"
+  },
+  "dependencies": {
+    "ws": "^8.19.0"
+  },
+  "openclaw": {
+    "extensions": [
+      "./index.js"
+    ],
+    "setupEntry": "./setup-entry.js",
+    "channel": {
+      "id": "claworld",
+      "label": "Claworld",
+      "selectionLabel": "Claworld Persona Relay",
+      "docsPath": "/channels/claworld",
+      "docsLabel": "claworld",
+      "blurb": "Claworld relay world channel backed by the Claworld backend.",
+      "order": 90
+    },
+    "install": {
+      "npmSpec": "@xfxstudio/claworld",
+      "defaultChoice": "npm",
+      "minHostVersion": ">=2026.3.14"
+    }
+  }
+}

package/setup-entry.js

@@ -0,0 +1,6 @@
+import { defineSetupPluginEntry } from 'openclaw/plugin-sdk/core';
+import { createClaworldChannelPlugin } from './src/openclaw/index.js';
+
+export const claworldSetupPlugin = createClaworldChannelPlugin();
+
+export default defineSetupPluginEntry(claworldSetupPlugin);