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 the embedded aionrs agent engine — you can use AionUi without installing another agent CLI. 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 — supported external agents connect through Agent Client Protocol or an AionUi compatibility adapter
• 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 is always available with zero external-agent setup. Representative agents below are detected when their CLI is available on your PATH:

Agent	CLI Command	Notes
Built-in Agent (aionrs)	bundled	✅ Default, no external agent 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-cli-chat	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	qodercli	Qoder
Mistral Vibe	vibe-acp	Mistral
Nanobot	nanobot	Nanobot
Pi	pi	Pi coding agent
MiMo Code	managed / vendor CLI	Xiaomi MiMo
omp	managed / vendor CLI	Oh My Pi
Antigravity	agy	Antigravity CLI

💡 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	Embedded aionrs agent engine	External CLI processes connected through ACP or a compatibility adapter
Feature integration	Deep AionUi integration with configured models, assistants, Skills, MCP, image tools, and scheduled tasks	Varies by agent; AionUi provides the common UI and bridges only the capabilities that agent supports
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 is powered by the embedded aionrs engine and ships inside AionUi. External CLIs are optional.

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 a common conversation, project, permission, preview, and Cowork interface. Models, tools, MCP transport, permission behavior, and unattended modes vary by agent, so use the controls shown for the selected agent rather than assuming feature parity.

---

📚 Related Documentation

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

---

Need Help?

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

Multi-Agent Mode brings supported CLI agents into one Cowork window.