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

> Learn to set up and configure OpenClaw integration in AionUi for autonomous file operations. Follow simple steps to automate your file management tasks effortlessly.

- Repository: [OfficeAI/AionUi](https://github.com/iofficeai/aionui)
- Tags: how-to-guide
- Published: 2026-02-16

---

**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`](https://github.com/iOfficeAI/AionUi/blob/main/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`](https://github.com/iOfficeAI/AionUi/blob/main/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`](https://github.com/iOfficeAI/AionUi/blob/main/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`](https://github.com/iOfficeAI/AionUi/blob/main/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`](https://github.com/iOfficeAI/AionUi/blob/main/src/renderer/pages/conversation/openclaw/OpenClawChat.tsx) and [`OpenClawSendBox.tsx`](https://github.com/iOfficeAI/AionUi/blob/main/OpenClawSendBox.tsx). [`OpenClawChat.tsx`](https://github.com/iOfficeAI/AionUi/blob/main/OpenClawChat.tsx) initializes a `ConversationProvider` with `type: 'openclaw-gateway'`, while [`OpenClawSendBox.tsx`](https://github.com/iOfficeAI/AionUi/blob/main/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:

   ```bash
   npm install -g openclaw@latest
   ```

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

   ```bash
   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:

   ```bash
   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`](https://github.com/iOfficeAI/AionUi/blob/main/src/agent/openclaw/openclawConfig.ts). This function searches standard paths (`~/.openclaw/openclaw.json`, legacy [`clawdbot.json`](https://github.com/iOfficeAI/AionUi/blob/main/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`](https://github.com/iOfficeAI/AionUi/blob/main/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`](https://github.com/iOfficeAI/AionUi/blob/main/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:

```typescript
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:

```typescript
// 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`](https://github.com/iOfficeAI/AionUi/blob/main/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`](https://github.com/iOfficeAI/AionUi/blob/main/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`](https://github.com/iOfficeAI/AionUi/blob/main/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`](https://github.com/iOfficeAI/AionUi/blob/main/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`](https://github.com/iOfficeAI/AionUi/blob/main/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`](https://github.com/iOfficeAI/AionUi/blob/main/openclaw.json) (or legacy variants like [`clawdbot.json`](https://github.com/iOfficeAI/AionUi/blob/main/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`](https://github.com/iOfficeAI/AionUi/blob/main/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`](https://github.com/iOfficeAI/AionUi/blob/main/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`](https://github.com/iOfficeAI/AionUi/blob/main/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`](https://github.com/iOfficeAI/AionUi/blob/main/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`](https://github.com/iOfficeAI/AionUi/blob/main/openclaw.json) or in AionUi's channel settings, ensuring that each bot token is used by only one service to prevent message routing errors.