Agents

After reading this page you will be able to: tell assistants and Agents apart, detect your local CLIs, test connections, and fix startup problems yourself on the repair page.

1. Assistants wrap tasks; Agents do the work

In one sentence: an assistant is a task-oriented configuration; the Agent is the engine that actually runs the conversation.

An assistant bundles name, avatar, rules, and defaults into a “role” you can switch with one click
The Agent decides which AI engine runs behind the chat and which models and permission modes it supports
One Agent can serve many assistants; change an assistant’s Agent and its capabilities follow

Where: Settings → “AI Core” → Agents

The page opening line states the rule: “Manage the AI coding agents available on this device. Aion CLI is built in and ships with the app — no install needed; other agents are detected only after their CLI is installed locally.” A “Setup guide” link sits next to it.

2. Reading the Agent list

The first row is always the built-in Aion CLI — it ships with the app, nothing to install. Below it are the CLI Agents detected on this computer; common ones include:

Agent	Notes
Claude Code	Anthropic’s coding Agent; install its CLI first
Codex	OpenAI’s coding Agent; install its CLI first
Gemini CLI	Google’s command-line Agent; install its CLI first
Qwen Code	Qwen’s command-line Agent; install its CLI first
Kimi CLI	Kimi’s command-line Agent; install its CLI first
Goose	Open-source command-line Agent; install its CLI first
…	Any ACP-compatible CLI may be detected once installed — what the app actually finds wins

Each row has two buttons: Test Connection and Edit. The colored tag next to the name is the current status:

Status tag	Meaning	Next step
Available	Command found, connection healthy	Use it in any assistant
Needs Sign-in	Reachable, but not signed in or missing a key	Sign in inside the CLI, or add the key on the repair page
Unavailable	Command found, but the connection failed	Open the repair page and read the error
Not Installed	The command is not on the default path	Install the CLI first, or set a launch path on the repair page
Not Checked	Never tested	Click Test Connection once

Filter the list with the All / Available / Unavailable tabs, or use the search box (“Search agents…“).

3. Test connection and the repair page

Click Test Connection and wait a moment; a toast reports the result — success shows “<name> connected successfully.”, while not installed, needs sign-in, and offline each get their own message.

Click the Agent row (or Edit) to open its repair page:

Block	How to use it
Status card	Advice per status: Connected (“online” only means reachable, not signed in), Connection failed (follow the error, then adjust below), Not detected (if installed, set the full launch path below), Not checked yet (click “Test Connection” in the top-right)
Launch Path	If the default path cannot find the command, enter the full path here; Reset to Default undoes it
Environment Variables	One variable per row. The page lists three things this fixes: a missing API key (e.g. ANTHROPIC_API_KEY), a custom API endpoint (e.g. ANTHROPIC_BASE_URL), and a network proxy (e.g. HTTPS_PROXY)
Save & Test	After changing the path or variables, click it to retest immediately

At the bottom, “Assistants using this agent” lists every assistant bound to this Agent; click one to jump to its details page.

Common failures and the guidance to expect:

Symptom	Check first
Command not found	Is the CLI installed? Install it as prompted, then test again
Starts but initialization fails	Open the CLI once in a terminal to finish sign-in or first-run setup
Reachable but needs sign-in	Sign in inside the CLI, or add the API key under Environment Variables
No model provider configured	Add and enable a provider under Settings → Models
Managed component missing	Follow the prompt to repair or reinstall the component (see below)

4. Managed runtimes, handled for you

Some components an Agent depends on (such as the managed Node runtime) are prepared by the app automatically: downloaded and verified in the background on first use, nothing for you to install. If preparation fails or a component is damaged, the Agent status shows a repair hint — reopen the app or reinstall as prompted, and when a component is missing, follow “fix or reinstall the component, then test the connection again.”

5. Adding a custom Agent

The top-right Add Custom Agent button offers Add via chat (the Butler guides you) or Add manually. The manual form has these fields:

Field	What to enter
Display Name	The name shown in the agent picker
Avatar	Optional; “Upload image”
Command	The executable command that runs the Agent CLI, e.g. `my-agent` or a full path
Arguments	Space-separated arguments, e.g. `--acp --verbose`
Environment Variables	Name / value pairs, one per row; “Add Variable” adds a row

Click Test Connection first — “Connection successful! CLI exists and ACP protocol is working.” — and then save. For fine-tuning, expand the Advanced (JSON) section and edit the JSON directly.

6. Two notes for this version

The remote Agent connection entry of older versions (such as OpenClaw Gateway) is no longer offered in this version’s settings page; for remote use, reach this computer through WebUI remote access instead
The Agent market (installing, updating, and uninstalling more Agents) is coming soon and is not open in the current version

What success looks like

You can explain the assistant/Agent split and open the list at Settings → “AI Core” → Agents
The built-in Aion CLI is in the list, and every CLI you installed shows up with one Test Connection done
You can read the status tags (Available / Needs Sign-in / Unavailable / Not Installed / Not Checked) and know the next step for each
Adding a launch path or an environment variable on the repair page ends with a successful Save & Test