ACP Setup

🤖 AionUi Multi-Agent Mode Configuration Tutorial

This tutorial explains how Multi-Agent Mode works in AionUi and how to bring external CLI agents (Claude Code, Codex, Qwen Code, Cursor, Goose, OpenClaw, and more) into a single unified Cowork interface via ACP (Agent Client Protocol).

English | 简体中文

🎯 Multi-Agent Mode Overview

Multi-Agent Mode is optional. AionUi already ships with a complete Built-in Agent (powered by Aion CLI / aionrs) — you can use AionUi without installing anything else. Multi-Agent Mode is for users who already use external CLI agents and want to drive them from AionUi's GUI alongside the built-in one.

Key characteristics:

• Auto-detection — AionUi scans your PATH on startup and lights up agents that are already installed
• Unified interface — one Cowork window for all agents, instead of jumping between terminals
• ACP standardization — every external agent talks to AionUi over the Agent Client Protocol
• Independent capabilities — each external agent keeps its own model, auth, tools, and behaviors
• Custom agents — any ACP-compliant CLI can be added through Settings → Agent Management → Custom Agents

Supported Agents

The Built-in Agent (Aion CLI / aionrs) is always available with zero setup. The agents below are auto-detected if their CLI is on your PATH:

Agent	CLI Command	Notes
Built-in Agent (Aion CLI)	bundled	✅ Default, no install required
Claude Code	claude	Anthropic
Codex	codex	OpenAI
Qwen Code	qwen	Alibaba Qwen
Gemini CLI	gemini	Google
Cursor Agent	cursor-agent	Cursor
Snow CLI	snow	Snow
Kiro	kiro	Kiro
Hermes Agent	hermes	Nous Research
Goose	goose	Block
OpenCode	opencode	OpenCode
OpenClaw	openclaw	OpenClaw (gateway mode)
Augment Code	auggie	Augment
CodeBuddy	codebuddy	Tencent
Kimi CLI	kimi	Moonshot
Factory Droid	droid	Factory
GitHub Copilot CLI	copilot	GitHub
Qoder CLI	qoder	Qoder
Mistral Vibe	vibe-acp	Mistral
Nanobot	nanobot	Nanobot

💡 New ACP-compatible CLIs are added regularly. The exact set may grow with each AionUi release — check the welcome screen for the up-to-date list, or define your own under Settings → Agent Management → Custom Agents.

Multi-Agent Mode vs Built-in Agent Mode

Aspect	Built-in Agent Mode	Multi-Agent Mode
Install requirements	None — bundled with AionUi	You install the external CLI yourself; AionUi auto-detects it
Architecture	AionUi's Aion CLI engine + ACP	External CLI processes spoken to over ACP
Feature integration	Full integration: image generation, MCP tools, multi-key rotation, scheduled tasks, etc.	Agent's native features only — AionUi provides the chat/file UI
Configuration	One AionUi config covers everything	Each external CLI handles its own auth & config
Best for	Daily use, full AionUi feature surface	Power users who already live in a specific CLI

---

🚀 Step 1: Install the CLI You Want to Use

AionUi does not ship external CLIs — install whichever ones you want, following the vendor's official documentation. The package names and install commands change frequently, so this guide intentionally points to upstream rather than copying outdated commands.

Agent	Where to install from
Claude Code	https://docs.anthropic.com/claude/claude-code
Codex	https://developers.openai.com/codex/cli/
Qwen Code	https://github.com/QwenLM/qwen-code
Gemini CLI	https://github.com/google-gemini/gemini-cli
Cursor Agent	https://docs.cursor.com/
Snow CLI	https://snowcli.dev/
Kiro	https://kiro.dev/
Hermes Agent	https://github.com/NousResearch/hermes-agent
Goose	https://github.com/block/goose
OpenCode	https://github.com/opencode-ai/opencode
OpenClaw	https://github.com/openclaw/openclaw
Augment Code	https://www.augmentcode.com/
CodeBuddy	https://github.com/Tencent/CodeBuddy
Kimi CLI	https://platform.moonshot.cn/
Factory Droid	https://www.factory.ai/
GitHub Copilot CLI	https://docs.github.com/en/copilot/github-copilot-in-the-cli
Qoder CLI	https://qoder.com/
Mistral Vibe	https://github.com/mistralai/vibe-acp
Nanobot	https://github.com/nanobot-ai/nanobot

📌 After installation, make sure the CLI command is callable from a fresh terminal (i.e. on your PATH). On macOS/Linux verify with which <command>; on Windows use where <command>.

🔐 Each CLI handles authentication on its own — usually claude login, qwen login, an API key env var, or an OAuth flow. Follow the vendor docs.

---

💬 Step 2: Use Multi-Agent Mode in AionUi

1. Open AionUi — installed agents appear on the welcome screen
2. Pick an agent — choose any auto-detected CLI, or the Built-in Agent
3. Start a conversation — pick a project (working directory), type a message, send
4. Approve permissions — when an agent requests file/tool access, AionUi shows an approval prompt (one-time or persistent)
5. Switch any time — each conversation is bound to its own agent; spin up multiple in parallel

Adding a Custom Agent

If your CLI supports ACP but isn't auto-detected:

1. Open Settings → Agent Management → Custom Agents
2. Click Add Custom Agent, fill in display name, command, and arguments
3. Save — it now appears alongside the built-in detections

---

❓ FAQ

Q: Do I need any external CLI to use AionUi?

A: No. The Built-in Agent (Aion CLI / aionrs) ships inside AionUi and works out of the box. External CLIs are purely additive.

Q: When should I pick Multi-Agent Mode?

A: Choose it when you already pay for / log into a specific CLI agent (e.g. Claude Code or Cursor), and want to drive it from AionUi's GUI alongside other agents. For everything else, the Built-in Agent gives you the most integrated experience.

Q: How do I know detection worked?

A: Open AionUi — the welcome screen lists every detected agent. If one is missing, run which <command> (or where on Windows) in a terminal launched from the same login shell to confirm it's on PATH, then restart AionUi.

Q: An agent is installed but not showing up.

A: Common causes:

1. The CLI is installed in a shell-only path (~/.local/bin, nvm, asdf) that AionUi did not inherit — restart AionUi from a fresh terminal, or move the binary to a system-wide location
2. The CLI requires a one-time login before it speaks ACP — run it manually once and complete auth
3. Older CLI versions may not implement ACP — upgrade to the latest

Q: My agent connects but immediately disconnects.

A: Check the CLI's own logs and confirm authentication succeeded outside AionUi (run the agent in a terminal first). Network restrictions, expired tokens, and outdated versions are the usual culprits.

Q: What features still apply in Multi-Agent Mode?

A: AionUi provides: conversation history, project (working directory) management, permission gating, file preview, and Cowork orchestration. AionUi-specific features like image generation and built-in MCP tooling are part of the Built-in Agent, not external CLIs.

---

📚 Related Documentation

• Quick Start
• LLM Configuration
• Image Generation Setup
• Assistant Configuration
• FAQ

---

Need Help?

• 🐛 Report Issues
• 💬 Community Discussions
• 📖 Complete Documentation

Multi-Agent Mode lets you drive every CLI agent you own from one Cowork window.