How to Set Up and Configure OpenClaw Integration in AionUi for Autonomous File Operations

To set up and configure OpenClaw integration in AionUi, install the OpenClaw CLI globally, run its onboarding wizard to generate ~/.openclaw/openclaw.json, and then select "OpenClaw" as the agent type when creating a new conversation in AionUi; the application will automatically detect gateway credentials and spawn the agent worker.

The iOfficeAI/AionUi repository provides a complete Electron-based interface for managing AI conversations, and its native support for OpenClaw enables autonomous file operations through a WebSocket gateway. When you set up and configure OpenClaw integration in AionUi, the application reads local configuration files, initializes a dedicated agent manager, and bridges file-selection events between the renderer process and the OpenClaw worker.

Understanding the OpenClaw Integration Architecture

The integration relies on three distinct layers that handle configuration, process management, and user interaction.

Configuration Layer

The src/agent/openclaw/openclawConfig.ts module exposes readOpenClawConfig(), getGatewayPort(), and getGatewayAuthToken() to resolve connection parameters. By default, the module searches for ~/.openclaw/openclaw.json (or legacy variants such as clawdbot.json), parses JSON-C comments, and extracts the gateway port (default 18789) and authentication token. You can override the state directory via the OPENCLAW_STATE_DIR or OPENCLAW_CONFIG_PATH environment variables.

Agent Management Layer

src/process/task/OpenClawAgentManager.ts extends BaseAgentManager and implements initAgent() to instantiate the OpenClawAgent. The manager receives a gateway object containing host, port, token, password, and the useExternalGateway flag. When useExternalGateway is false (the default), AionUi spawns the gateway worker defined in src/worker/openclaw-gateway.ts. The manager routes stream events—including content, agent_status, acp_tool_call, and plan—to the database and the renderer via ipcBridge, and transforms permission requests (acp_permission) into UI confirmation dialogs.

User Interface Layer

The renderer layer consists of src/renderer/pages/conversation/openclaw/OpenClawChat.tsx and OpenClawSendBox.tsx. OpenClawChat.tsx initializes a ConversationProvider with type: 'openclaw-gateway', while OpenClawSendBox.tsx polls runtime status via ipcBridge.openclawConversation.getRuntime() and dispatches messages via ipcBridge.openclawConversation.sendMessage(). The UI also emits openclaw-gateway.selected.file and openclaw-gateway.selected.file.append events, allowing the OpenClaw agent to perform autonomous reads and writes on files the user has explicitly selected.

Prerequisites and Initial Setup

Before configuring the integration, you must install the OpenClaw CLI and generate its configuration file.

1. Install OpenClaw globally using npm:

   npm install -g openclaw@latest

2. Run the onboarding wizard to create the state directory and default configuration:

   openclaw onboard --install-daemon

   The wizard writes ~/.openclaw/openclaw.json containing the gateway settings, including the default port 18789 and an authentication token.

3. Verify the configuration by inspecting the generated file:

   cat ~/.openclaw/openclaw.json

   Ensure the JSON contains a gateway object with port and auth keys. If you need to customize the port or token, edit this file directly or set the OPENCLAW_STATE_DIR environment variable to point to an alternative configuration directory.

Configuring the Gateway Connection

AionUi can detect OpenClaw settings automatically or accept manual overrides depending on your deployment scenario.

Automatic Configuration Detection

When you start AionUi, the main process invokes readOpenClawConfig() from src/agent/openclaw/openclawConfig.ts. This function searches standard paths (~/.openclaw/openclaw.json, legacy clawdbot.json, or paths specified by OPENCLAW_CONFIG_PATH), parses JSON-C comments, and returns a configuration object. The getGatewayPort() and getGatewayAuthToken() helpers extract the WebSocket endpoint details, defaulting to port 18789 if unspecified.

Manual Gateway Configuration

For development or remote gateway scenarios, you can instantiate the OpenClawAgentManager with explicit parameters rather than relying on file-based detection. The initAgent() method in src/process/task/OpenClawAgentManager.ts accepts a gateway object containing host, port, token, password, and useExternalGateway.

If useExternalGateway is set to true, AionUi skips spawning the internal worker and connects to an existing OpenClaw gateway process. If false (default), the manager launches src/worker/openclaw-gateway.ts as a dedicated Node.js worker thread.

Launching and Managing the OpenClaw Agent

Once configuration is resolved, you programmatically start the agent using the manager class. The following TypeScript example demonstrates manual creation with custom gateway settings:

import { OpenClawAgentManager } from '@/process/task/OpenClawAgentManager';
import { getGatewayPort, getGatewayAuthToken } from '@/agent/openclaw/openclawConfig';

// Resolve gateway credentials from the user's OpenClaw configuration
const gateway = {
  host: '127.0.0.1',
  port: getGatewayPort(),        // Defaults to 18789
  token: getGatewayAuthToken(),  // Extracted from openclaw.json
  useExternalGateway: false,     // Spawn internal worker
};

// Instantiate the manager (normally handled by createOpenClawAgent)
const manager = new OpenClawAgentManager({
  conversation_id: 'conv-123',
  workspace: '/home/alice/projects',
  gateway,                       // Injected configuration
  yoloMode: false,               // Require permission confirmation
});

// Send a message triggering a file operation
await manager.sendMessage({
  content: 'Read the file ~/projects/todo.txt and summarize unfinished items.',
});

// Listen to stream events for debugging
manager.agent.on('stream', (msg) => console.log('Stream:', msg));

The OpenClawAgentManager handles the lifecycle of the underlying OpenClawAgent, routing stream events such as content, agent_status, and acp_tool_call to the UI via ipcBridge. It also intercepts permission requests (acp_permission) and renders confirmation dialogs before allowing autonomous file mutations.

Enabling Autonomous File Operations

OpenClaw performs file reads, writes, moves, and deletions through the Gateway using WebSocket messages. AionUi mediates these operations via two mechanisms: permission gating and explicit file selection.

Handling Permission Requests

When OpenClaw attempts a file operation, the agent emits an acp_permission event. The OpenClawAgentManager transforms this into a UI confirmation dialog. Setting yoloMode: true in the manager configuration bypasses these prompts for fully autonomous operation, while yoloMode: false (the default) requires explicit user approval for each file mutation.

Emitting File Selection Events

The UI can proactively supply file handles to OpenClaw through Electron IPC events. The renderer emits openclaw-gateway.selected.file or openclaw-gateway.selected.file.append with an array of absolute paths:

// Example: UI component sending a selected file to OpenClaw
import { emitter } from '@/renderer/utils/emitter';

emitter.emit('openclaw-gateway.selected.file', ['/home/alice/report.pdf']);

OpenClaw listens for these events and can immediately read the specified files without additional permission prompts, streamlining workflows where the user has already explicitly chosen a target file through AionUi's file picker.

Conflict Detection and Resolution

AionUi includes a conflict detector implemented in src/process/services/openclawConflictDetector.ts to prevent credential collisions. If OpenClaw's configuration uses the same Telegram or Lark bot tokens as AionUi's native channel integrations, the detector triggers a ChannelConflictWarning in the UI. Resolve these conflicts by disabling the overlapping channel in either OpenClaw's openclaw.json or AionUi's settings to prevent autonomous operations from accidentally hijacking the wrong bot endpoint.

Summary

• Install OpenClaw globally and run openclaw onboard --install-daemon to generate ~/.openclaw/openclaw.json with gateway credentials.
• AionUi auto-detects the configuration via readOpenClawConfig() in src/agent/openclaw/openclawConfig.ts, defaulting to port 18789.
• Create an OpenClaw conversation in AionUi to instantiate OpenClawAgentManager, which spawns the worker at src/worker/openclaw-gateway.ts unless useExternalGateway is enabled.
• Approve permission requests (acp_permission) for file operations, or emit openclaw-gateway.selected.file events from the UI to pre-authorize specific files.
• Monitor conflicts using src/process/services/openclawConflictDetector.ts to avoid token collisions with Telegram or Lark integrations.

Frequently Asked Questions

Where does AionUi look for the OpenClaw configuration file?

AionUi searches for openclaw.json (or legacy variants like clawdbot.json) in the ~/.openclaw directory by default. You can override this path by setting the OPENCLAW_STATE_DIR or OPENCLAW_CONFIG_PATH environment variables before launching AionUi. The configuration parser in src/agent/openclaw/openclawConfig.ts handles JSON-C comments and extracts the gateway port and authentication token.

Can I connect AionUi to an external OpenClaw gateway instead of the built-in worker?

Yes. When instantiating the OpenClawAgentManager, set the useExternalGateway property to true in the gateway configuration object. This prevents AionUi from spawning the internal worker defined in src/worker/openclaw-gateway.ts and instead connects to the specified host and port of your external gateway process. This is useful for running OpenClaw on a remote server or in a separate Docker container.

How does AionUi handle file permission requests from OpenClaw?

When OpenClaw attempts an autonomous file operation, it emits an acp_permission event through the gateway stream. The OpenClawAgentManager in src/process/task/OpenClawAgentManager.ts intercepts this event and transforms it into a UI confirmation dialog via the ipcBridge. If the user approves, the operation proceeds; if denied, the agent receives a rejection signal. You can bypass these prompts by setting yoloMode: true in the manager configuration, though this is recommended only for trusted automation workflows.

What should I do if AionUi reports a channel conflict with OpenClaw?

The conflict detector in src/process/services/openclawConflictDetector.ts monitors for overlapping Telegram or Lark bot tokens between AionUi's native channel integrations and OpenClaw's configuration. If a conflict is detected, AionUi displays a ChannelConflictWarning in the settings interface. To resolve this, disable the conflicting channel in either OpenClaw's openclaw.json or in AionUi's channel settings, ensuring that each bot token is used by only one service to prevent message routing errors.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}