OpenClaw Control Center: safety-first local control center for OpenClaw

OpenClaw Control Center provides a unified monitoring and management interface for OpenClaw users both teams and individuals. It displays the operational status of the OpenClaw system, including system stability, resource consumption (usage and spending trends), the actual work and queue status of agents (referred to as "employees"), current task progress, approval workflows, and execution evidence. The Control Center also offers source‑file‑based documentation and memory management, ensuring that information stays synchronized with active OpenClaw agents. Through clearly organized modules—Overview, Usage, Staff, Tasks, Docs, and Memory—it transforms complex backend data into intuitive views. By default, the Control Center runs in read‑only mode with local token authentication, disables high‑risk write operations (such as live imports and approvals), avoids direct exposure of raw backend data, and provides structured APIs for querying and controlled modifications.

When to Use OpenClaw Control Center

• Teams or individuals already using OpenClaw who need a centralized control hub.
• Users running OpenClaw on the same machine or within a reachable local environment.
• Developers who want to publish a security‑first OpenClaw console rather than building a generic agent platform.

Secure Defaults

Upon first connection, the system automatically applies multiple security settings to minimize risk:

• Read‑only mode enabled by default (READONLY_MODE=true).
• Local token authentication required by default (LOCAL_TOKEN_AUTH_REQUIRED=true).
• High‑risk write operations disabled by default.
• Approval actions disabled by default (APPROVAL_ACTIONS_ENABLED=false) and set to dry‑run mode (APPROVAL_ACTIONS_DRY_RUN=true).
• Import mutations disabled by default (IMPORT_MUTATION_ENABLED=false) and set to dry‑run mode (IMPORT_MUTATION_DRY_RUN=false).

Core Features

Overview

The main dashboard for non‑technical users. It consolidates the overall system status, pending items, anomalies, stalled executions, budget risks, and work state, allowing you to quickly assess whether OpenClaw is running smoothly.

Usage

Displays usage and spending trends for the last day, week, and month. It includes subscription windows, quota consumption, usage breakdown, and data connection status, helping you spot potential cost or quota issues at a glance.

Staff

Clearly distinguishes between tasks that are currently executing and those queued next. For each agent, you see its name, role, current status, active task, latest outputs, and schedule—so you always know who is working, who is on standby, who is stuck, and who is waiting.

Memory

A source‑file‑based workspace for viewing and editing both short‑term and long‑term memories. The displayed scope follows the active agents defined in openclaw.json; memories of deleted agents are not shown, making it easy to maintain up‑to‑date information.

Docs

A source‑file‑based workspace for viewing and editing shared documents and core agent documentation. All opens and saves directly modify the source files (no intermediate copies), simplifying the maintenance of the documents that actually affect system behavior.

Tasks

Integrates task boards, schedules, approvals, execution chains, and execution evidence. It distinguishes between board placeholders and actual execution proof, so you can see at a glance which tasks are in progress, which are merely planned, and which are stuck and require intervention.

Settings

Shows security modes, connector status, and data link expectations. It explicitly states which data sources are connected, which parts are visible, and which high‑risk actions are disabled. This helps troubleshoot environment configuration issues and explains why certain signals may be missing.

Core Constraints

• The Control Center only modifies files inside its own control-center/ directory; it never touches external files.
• It does not rewrite the ~/.openclaw/openclaw.json configuration file.
• When authentication is enabled, all import/export and state‑changing endpoints require a valid local token.
• High‑risk operations are guarded by hard switches and are either disabled or set to safe mode by default.

Starting OpenClaw Control Center

You can launch the project with a few simple commands:

npm install
cp .env.example .env
npm run build
npm test
npm run smoke:ui
UI_MODE=true npm run dev

After startup, open the provided address (e.g., http://127.0.0.1:4310/?section=overview&lang=en).

Installing OpenClaw Control Center

Prerequisites

• A working OpenClaw installation with a reachable OpenClaw Gateway.
• Node.js and npm installed locally.
• Read access to the OpenClaw home directory.
• To display full usage/subscription information, ensure local read access to ~/.openclaw, ~/.codex, and the OpenClaw subscription snapshot file (if located elsewhere, you must specify the path manually).

Two Installation Methods

Recommended: Automatic Installation via OpenClaw

No manual configuration is needed—just provide the installation instructions to OpenClaw. It will automatically check the environment, install dependencies, create configuration files, perform security checks, and handle special cases (e.g., non‑default paths, multiple OpenClaw instances).

Use the instructions found in:

• English version: INSTALL_PROMPT.en.md

The process follows five steps: environment confirmation → project installation → security configuration → installation verification → result delivery. It automatically avoids high‑risk operations, ensuring a safe and controlled setup.

Manual Installation

1. Clone the repository and navigate into the directory:

git clone https://github.com/TianyiDataScience/openclaw-control-center.git
cd control-center

2. Install dependencies and copy the example environment file:

npm install
cp .env.example .env

3. Edit the .env file (baseline defaults are shown below; modify only what differs from your setup):

GATEWAY_URL=ws://127.0.0.1:18789
READONLY_MODE=true
APPROVAL_ACTIONS_ENABLED=false
APPROVAL_ACTIONS_DRY_RUN=true
IMPORT_MUTATION_ENABLED=false
IMPORT_MUTATION_DRY_RUN=false
LOCAL_TOKEN_AUTH_REQUIRED=true
UI_MODE=false
UI_PORT=4310
# Add these only if your paths are non‑default:
# OPENCLAW_HOME=/path/to/.openclaw
# CODEX_HOME=/path/to/.codex
# OPENCLAW_SUBSCRIPTION_SNAPSHOT_PATH=/path/to/subscription.json

When to modify:

• GATEWAY_URL: if your Gateway is not at the default local address.
• OPENCLAW_HOME: if your OpenClaw home is not ~/.openclaw.
• CODEX_HOME: if your Codex data is not in ~/.codex.
• OPENCLAW_SUBSCRIPTION_SNAPSHOT_PATH: if your subscription/billing snapshot is in a custom location.
• UI_PORT: if port 4310 is already in use.

Verify the Installation

Run these commands to confirm everything is set up correctly:

npm run build
npm test
npm run smoke:ui

Expected outcome: Both build and test succeed, and smoke:ui prints a local access address (e.g., http://127.0.0.1:4310).

First Launch and Checks

1. Start the UI:

UI_MODE=true npm run dev

2. Perform these initial checks:

• Overview: The page loads and shows system status.
• Usage: Either displays real data or clearly states “data source not connected.”
• Staff: Real‑time status matches the active session.
• Tasks: Work boards, approvals, and execution chains load without errors.
• Docs / Memory: The agents shown match the active agents listed in openclaw.json.

Troubleshooting Common Issues

• No real‑time activity: Likely an incorrect GATEWAY_URL or the OpenClaw Gateway is not running.
• Docs / Memory scope is wrong: The OPENCLAW_HOME path may be incorrect, or openclaw.json is not readable.
• Usage / Subscription shows no data: CODEX_HOME or OPENCLAW_SUBSCRIPTION_SNAPSHOT_PATH may not be properly set.

Local Command Reference

Protected commands (e.g., backup-export, import-validate) require the LOCAL_API_TOKEN environment variable to be set when LOCAL_TOKEN_AUTH_REQUIRED=true.

Local HTTP Endpoints

The system exposes a variety of HTTP endpoints for data querying, task management, session inspection, and more:

• GET /snapshot – Get the raw snapshot JSON.
• GET /projects – List projects (supports filtering by status, owner, etc.).
• GET /tasks – List tasks (supports filtering by status, owner, project, etc.).
• GET /sessions – Paginated list of sessions (filters: state, agentId, q).
• GET /sessions/:id – Detailed JSON of a specific session.
• GET /usage-cost – Redirect to the usage/spending page.
• GET /api/usage-cost – Retrieve usage, spending, and subscription window snapshots.
• GET /healthz – System health payload.
• GET /exceptions – Exception stream sorted by severity.
• POST /api/approvals/:approvalId/approve|reject – Approval actions (availability depends on configuration switches).