Agent UI

Agent UI is the visual layer for an agent. Instead of every agent being only a chat thread, an agent can own a small web app that shows its state, tools, workflow, and domain-specific controls.

This is one of the main differences between xCloud and a normal web chat: the agent still runs on OpenClaw, but xCloud gives it a product-like interface.

How It Works

Each agent can have its own UI project.

~/.openclaw/workspace/<agent-id>/
  IDENTITY.md
  SOUL.md
  AGENTS.md
  ui-config.json
  ui/
    package.json
    src/

The ui-config.json file tells xCloud where the UI project lives and which port to use for preview.

For local engines, the UI normally lives on your computer. For remote engines, the UI can be stored on the remote engine and optionally synced from a local source folder.

Create An Agent UI

1. Open an agent.
2. Open the right preview panel.
3. Choose Create UI or connect an existing UI folder.
4. xCloud creates context files for the UI project.
5. Build the UI with your preferred editor or coding agent.

xCloud writes helper files such as:

Supported Editors

xCloud can open the UI folder in common local tools:

• Cursor
• VS Code
• Windsurf
• Claude Code
• Codex
• OpenCode
• Zed
• Terminal
• iTerm

The editor is only for building the UI. The actual agent still runs in the active OpenClaw engine.

Preview Rules

The preview expects a normal web project.

For React/Vite/Next projects:

• Include a package.json.
• Include a dev or start script.
• Respect the PORT environment variable.
• Bind to 127.0.0.1 locally or 0.0.0.0 on remote engines.

For simple HTML projects:

• Include an index.html.
• xCloud can serve it with a static HTTP server.

If the project has a dev server, xCloud starts it and embeds the URL in the preview.

Live Agent Bridge

xCloud injects a runtime into the UI. The UI can read live agent state from:

const state = window.xcloud.agent.getState();

Useful state fields:

Subscribe to changes:

window.xcloud.agent.onStateChange((state) => {
  console.log(state.status, state.messages);
});

UI Tools

The UI can register tools that the agent can call.

window.xcloud.agent.registerTool({
  name: "selectWorkout",
  description: "Select a workout in the UI.",
  parameters: {
    type: "object",
    properties: {
      workoutId: { type: "string" }
    },
    required: ["workoutId"]
  },
  async execute(args) {
    return { selected: args.workoutId };
  }
});

When the agent calls that tool, xCloud forwards the request into the iframe and returns the UI result to OpenClaw.

Remote Engine Notes

When the active engine is a VPS or another PC:

• The UI project can be copied to the remote engine.
• xCloud starts the dev server on the remote host.
• The preview loads from that host and port.
• If a local source path is configured, xCloud can sync between local files and the remote UI folder.

Remote previews are more sensitive to firewall, host binding, npm install time, and port conflicts.

Common Problems