# Aionui > 这个项目配置了完整的 GitHub Actions CI/CD 流水线，支持自动构建、测试和发布到多个平台。 --- # CI/CD 设置指南 ## 概述 这个项目配置了完整的 GitHub Actions CI/CD 流水线，支持自动构建、测试和发布到多个平台。 ## 工作流说明 ### 1. `build-and-release.yml` - 主构建和发布流 - **触发时机**: 仅推送到 `main` 分支 - **功能**: - 代码质量检查 (ESLint, Prettier, TypeScript) - 多平台构建 (macOS Intel/Apple Silicon, Windows, Linux) - 自动创建版本标签 - 创建 Draft Release (需要手动审批和发布) - **流程**: 1. 代码质量检查 2. 三平台并行构建 3. 自动创建基于 package.json 版本的标签 4. 等待环境审批 5. 创建 Draft Release (需要手动编辑和发布) ## 必需的 GitHub Secrets 配置 在 GitHub 仓库的 Settings → Secrets and variables → Actions 中配置以下 Secrets： ### macOS 应用签名 (可选，用于发布到 Mac App Store) ``` APPLE_ID=你的苹果开发者账号邮箱 APPLE_ID_PASSWORD=应用专用密码 TEAM_ID=苹果开发者团队ID IDENTITY=签名证书名称 ``` ### GitHub Token ``` GH_TOKEN=你的Personal Access Token (github_pat_开头) ``` **注意**: 需要手动配置，因为需要 `contents: write` 权限来创建 releases。 ### Environment Secrets 在 Settings → Environments → release 中也需要配置： ``` GH_TOKEN=相同的Personal Access Token ``` ## 如何获取 Apple 签名配置 ### 1. Apple ID App-Specific Password 1. 访问 [appleid.apple.com](https://appleid.apple.com) 2. 登录你的 Apple ID 3. 在"Sign-In and Security"部分点击"App-Specific Passwords" 4. 生成新的应用专用密码 5. 复制生成的密码作为 `APPLE_ID_PASSWORD` ### 2. Team ID 1. 访问 [Apple Developer Portal](https://developer.apple.com/account/) 2. 在"Membership Details"中找到 Team ID 3. 复制 Team ID 作为 `TEAM_ID` ### 3. 签名证书 Identity 1. 打开 Xcode 或 Keychain Access 2. 查看已安装的开发者证书 3. 证书名称类似："Developer ID Application: Your Name (TEAM_ID)" 4. 复制完整证书名称作为 `IDENTITY` ## 使用方法 ### 推荐发布流程 (使用 release.sh) 1. 确保代码质量符合要求 2. 使用发布脚本升级版本: ```bash # 修复版本 ./scripts/release.sh patch # 功能版本 ./scripts/release.sh minor # 重大版本 ./scripts/release.sh major # 预发布版本 ./scripts/release.sh prerelease ``` 3. 脚本会自动: - 运行代码质量检查 - 升级版本号 - 创建 git tag - 推送到 main 分支 4. GitHub Actions 自动触发构建 5. 在 Deployments 页面审批发布 6. 编辑 Draft Release 内容 7. 手动发布给用户 ### 直接推送发布 1. 手动修改 `package.json` 中的版本号 2. 提交并推送到 `main` 分支 3. GitHub Actions 将自动构建并创建 Draft Release ### 版本管理规范 - `patch`: 修复bug (1.0.0 → 1.0.1) - `minor`: 新功能 (1.0.0 → 1.1.0) - `major`: 重大更新 (1.0.0 → 2.0.0) - `prerelease`: 预发布版本 (1.0.0 → 1.0.1-beta.0) ## 构建产物 成功构建后，将生成以下文件： ### macOS - `.dmg` 文件 (Intel 和 Apple Silicon 版本) - 应用程序包 ### Windows - `.exe` NSIS 安装程序 (x64/arm64) - `.zip` 便携版应用 (x64/arm64) ### Linux - `.deb` 安装包 (x64/arm64/armv7l) - `.AppImage` 便携式应用 (x64/arm64/armv7l) ## 故障排查 ### 常见问题 1. **Release创建失败 (403错误)** - 检查 GH_TOKEN 是否正确配置 - 确认 token 格式为 `github_pat_` 开头 - 验证 repository 和 environment 中都有 GH_TOKEN 2. **macOS 签名失败** - 检查 Apple ID 和密码是否正确 - 确认 Team ID 和证书名称准确 - 验证苹果开发者账号状态 3. **构建超时 (Windows)** - Windows 构建通常最慢 (可能40分钟+) - 考虑禁用 MSI target 加速构建 4. **重复tag错误** - CI/CD 会检查并跳过已存在的 tag - 如果手动创建了 tag，CI/CD 不会重复创建 ### 调试方法 1. 查看 GitHub Actions 日志 2. 本地运行相同的构建命令测试 3. 检查 package.json 中的构建脚本 ## 安全建议 1. 定期更新 GitHub Actions 版本 2. 使用最小权限原则配置 Secrets 3. 定期审查和清理未使用的 Secrets 4. 监控构建日志，避免敏感信息泄露 ## 进阶配置 ### 自动更新检查 可以集成应用内自动更新功能，配合 GitHub Releases API 实现自动更新提醒。 ### 多环境部署 可以扩展工作流支持开发、测试、生产环境的分别部署。 ### 性能优化 - 使用构建缓存加速构建 - 并行构建不同平台 - 优化依赖安装速度 --- # Pull Request ## Description ## Related Issues - Closes # ## Type of Change - [ ] Bug fix (non-breaking change which fixes an issue) - [ ] New feature (non-breaking change which adds functionality) - [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected) - [ ] Documentation update ## Testing - [ ] Tested on macOS - [ ] Tested on Windows - [ ] Tested on Linux - [ ] My code follows the project's code style guidelines - [ ] I have performed a self-review of my own code - [ ] My changes generate no new warnings or errors ## Screenshots ## Additional Context --- **Thank you for contributing to AionUi! 🎉** --- # Source: https://github.com/iOfficeAI/AionUi/blob/main/CODE_STYLE.md # 代码风格指南 本项目使用 ESLint 和 Prettier 来确保代码质量和一致性。 ## 工具配置 ### ESLint - 配置文件：`.eslintrc.json` - 忽略文件：`.eslintignore` - 主要规则： - TypeScript 支持 - 导入规则检查 - 代码长度限制（120字符） - 未使用变量检查 - 类型安全检查 ### Prettier - 配置文件：`.prettierrc.json` - 忽略文件：`.prettierignore` - 格式化规则： - 单引号 - 分号 - 2空格缩进 - 行长度限制（700字符） ## 可用的脚本命令 ### 代码检查 ```bash # 运行 ESLint 检查 npm run lint # 运行 ESLint 检查并自动修复 npm run lint:fix # 检查代码格式 npm run format:check # 自动格式化代码 npm run format ``` ### Git Hooks 项目配置了 Git hooks 来确保代码质量： 1. **pre-commit**: 在提交前自动运行 lint-staged 2. **commit-msg**: 检查提交信息格式 ### 提交信息格式 提交信息必须遵循以下格式： ``` type(scope): description ``` 类型（type）： - `feat`: 新功能 - `fix`: 修复bug - `docs`: 文档更新 - `style`: 代码格式调整 - `refactor`: 代码重构 - `test`: 测试相关 - `chore`: 构建过程或辅助工具变动 示例： ``` feat: 添加用户登录功能 fix(login): 修复登录验证问题 docs: 更新API文档 ``` ## 工作流程 1. **开发时**： - 编写代码 - 运行 `npm run lint` 检查代码质量 - 运行 `npm run format` 格式化代码 2. **提交前**： - Git hooks 会自动运行 lint-staged - 自动修复可修复的问题 - 检查提交信息格式 3. **持续集成**： - 可以运行 `npm run lint` 和 `npm run format:check` 来验证代码质量 ## 常见问题 ### 忽略特定文件的检查 在 `.eslintignore` 或 `.prettierignore` 中添加文件路径。 ### 禁用特定行的检查 ```typescript // eslint-disable-next-line @typescript-eslint/no-explicit-any const data: any = getData(); ``` ### 自定义规则 在 `.eslintrc.json` 中修改规则配置。 ## IDE 集成 ### VS Code 推荐安装以下扩展： - ESLint - Prettier - Code formatter 配置 `settings.json`： ```json { "editor.formatOnSave": true, "editor.defaultFormatter": "esbenp.prettier-vscode", "editor.codeActionsOnSave": { "source.fixAll.eslint": true } } ``` ### 其他编辑器 请参考相应编辑器的 ESLint 和 Prettier 插件配置。 --- # Source: https://github.com/iOfficeAI/AionUi/blob/main/WEBUI_GUIDE.md # AionUi WebUI Mode - Startup Guide AionUi supports WebUI mode, allowing you to access the application through a web browser. This guide covers how to start WebUI mode on all supported platforms. ## Table of Contents - [What is WebUI Mode?](#what-is-webui-mode) - [Windows](#windows) - [macOS](#macos) - [Linux](#linux) - [Android (Termux)](#android-termux) - [Remote Access](#remote-access) - [Troubleshooting](#troubleshooting) --- ## What is WebUI Mode? WebUI mode starts AionUi with an embedded web server, allowing you to: - Access the application through any modern web browser - Use AionUi from remote devices on the same network (with `--remote` flag) - Run the application headless on servers Default access URL: `http://localhost:3000` (port may vary, check the application output) --- ## Windows ### Method 1: Command Line (Recommended) Open **Command Prompt** or **PowerShell** and run: ```cmd # Using full path "C:\Program Files\AionUi\AionUi.exe" --webui # Or if AionUi is in your PATH AionUi.exe --webui ``` ### Method 2: Create a Desktop Shortcut 1. Right-click on desktop → **New** → **Shortcut** 2. Enter target location: ``` "C:\Program Files\AionUi\AionUi.exe" --webui ``` 3. Name it **AionUi WebUI** 4. Click **Finish** 5. Double-click the shortcut to launch ### Method 3: Create a Batch File Create `start-aionui-webui.bat`: ```batch @echo off "C:\Program Files\AionUi\AionUi.exe" --webui pause ``` Double-click the batch file to start WebUI mode. --- ## macOS ### Method 1: Terminal Command (Recommended) Open **Terminal** and run: ```bash # Using full path /Applications/AionUi.app/Contents/MacOS/AionUi --webui # Or using open command open -a AionUi --args --webui ``` ### Method 2: Create Shell Script Create `start-aionui-webui.sh`: ```bash #!/bin/bash /Applications/AionUi.app/Contents/MacOS/AionUi --webui ``` Make it executable and run: ```bash chmod +x start-aionui-webui.sh ./start-aionui-webui.sh ``` ### Method 3: Create Automator Application 1. Open **Automator** 2. Choose **Application** 3. Add **Run Shell Script** action 4. Enter: ```bash /Applications/AionUi.app/Contents/MacOS/AionUi --webui ``` 5. Save as **AionUi WebUI.app** 6. Double-click to launch ### Method 4: Add to Dock 1. Create an Automator app (Method 3) 2. Drag **AionUi WebUI.app** to your Dock 3. Click the Dock icon to start WebUI mode anytime --- ## Linux ### Method 1: Command Line (Recommended) #### For .deb Installation ```bash # Using system path aionui --webui # Or using full path /opt/AionUi/aionui --webui ``` #### For AppImage ```bash # Make AppImage executable (first time only) chmod +x AionUi-*.AppImage # Run with --webui flag ./AionUi-*.AppImage --webui ``` ### Method 2: Create Desktop Entry Create `~/.local/share/applications/aionui-webui.desktop`: ```ini [Desktop Entry] Name=AionUi WebUI Comment=Start AionUi in WebUI mode Exec=/opt/AionUi/aionui --webui Icon=aionui Terminal=false Type=Application Categories=Utility;Office; ``` Make it executable: ```bash chmod +x ~/.local/share/applications/aionui-webui.desktop ``` The launcher will appear in your application menu. ### Method 3: Create Shell Script Create `~/bin/start-aionui-webui.sh`: ```bash #!/bin/bash /opt/AionUi/aionui --webui ``` Make it executable: ```bash chmod +x ~/bin/start-aionui-webui.sh ``` Run it: ```bash start-aionui-webui.sh ``` ### Method 4: Systemd Service (Background) Create `/etc/systemd/system/aionui-webui.service`: ```ini [Unit] Description=AionUi WebUI Service After=network.target [Service] Type=simple User=YOUR_USERNAME ExecStart=/opt/AionUi/aionui --webui --remote Restart=on-failure RestartSec=10 [Install] WantedBy=multi-user.target ``` Enable and start the service: ```bash sudo systemctl daemon-reload sudo systemctl enable aionui-webui.service sudo systemctl start aionui-webui.service # Check status sudo systemctl status aionui-webui.service ``` --- ## Android (Termux) **Important Note**: Electron desktop mode is **not supported** on Android. However, you can run AionUi in WebUI mode using Termux with a prooted Linux environment. > **Community Contribution**: This guide is contributed by [@Manamama](https://github.com/Manamama). Special thanks for making AionUi accessible on Android devices! 🙏 > > **Original Tutorial**: [Running AionUi WebUI on Android via Termux + Proot Ubuntu](https://gist.github.com/Manamama/b4f903c279b5e73bdad4c2c0a58d5ddd) > > **Related Issues**: [#217 - Android Support Discussion](https://github.com/iOfficeAI/AionUi/issues/217) ### Prerequisites - **Termux** from [F-Droid](https://f-droid.org/en/packages/com.termux/) (Google Play version is outdated and not recommended) - **~5 GB free storage** - **Internet connection** - **Android 7.0+** (tested on Android 14) ### Installation Steps #### 1. Install Termux and Update Packages ```bash # Update package list pkg update -y # Install proot-distro pkg install proot-distro -y ``` #### 2. Install Ubuntu via Proot ```bash # Install Ubuntu rootfs proot-distro install ubuntu # Login to Ubuntu environment proot-distro login ubuntu ``` #### 3. Install System Dependencies ```bash # Update Ubuntu package list apt update # Install required dependencies apt install -y \ wget \ libgtk-3-0 \ libnss3 \ libasound2 \ libgbm1 \ libxshmfence1 \ ca-certificates # Optional: Install additional libraries if needed apt install -y \ libx11-xcb1 \ libxcomposite1 \ libxdamage1 \ libxrandr2 \ libatk1.0-0 \ libcups2 ``` #### 4. Download and Install AionUi ```bash # Download the ARM64 .deb package (replace VERSION with the actual version) # Check latest version at: https://github.com/iOfficeAI/AionUi/releases wget https://github.com/iOfficeAI/AionUi/releases/download/vVERSION/AionUi_VERSION_arm64.deb # Example (replace VERSION with the release tag, e.g. v1.5.2): wget https://github.com/iOfficeAI/AionUi/releases/download/vVERSION/AionUi_VERSION_arm64.deb # Install the package apt install -y ./AionUi_*.deb # Verify installation which AionUi ``` #### 5. Launch AionUi WebUI ```bash # Start AionUi in WebUI mode with no-sandbox flag AionUi --no-sandbox --webui ``` **Important**: The `--no-sandbox` flag is required in Termux/proot environments. #### 6. Access the WebUI Once started, open your browser and navigate to: ``` http://localhost:25808 ``` **Note**: The default port is 25808. Check the terminal output if a different port is used. ### Expected Warnings (Non-Fatal) You may see the following warnings in the terminal - these are normal and can be ignored: ``` [WARNING] Could not connect to session bus: Using X11 for dbus-daemon autolaunch was disabled at compile time [ERROR] Failed to connect to the bus: Failed to connect to socket: No such file or directory [WARNING] Multiple instances of the app detected, but not running on display server ``` These errors are related to D-Bus and X server, which are not needed for WebUI mode. ### Remote Access on LAN To access AionUi from other devices on your local network: ```bash # Start with --remote flag AionUi --no-sandbox --webui --remote # Find your Android device's IP address # In Termux (outside proot): # ifconfig or ip addr show ``` Access from other devices: `http://YOUR_ANDROID_IP:25808` ### Troubleshooting #### Port Already in Use If port 25808 is occupied: ```bash # Specify a different port AionUi --no-sandbox --webui --port 8080 ``` #### Permission Denied Errors ```bash # Ensure the binary has execute permissions chmod +x /opt/AionUi/aionui ``` #### Out of Memory AionUi requires sufficient RAM. Close other apps if you encounter memory issues. #### Cannot Access from Browser 1. Check if AionUi is running: look for "Server started" message 2. Try using Termux's built-in browser or Chrome 3. Clear browser cache ### Performance Tips 1. **Use a lightweight browser** - Chrome or Firefox Focus recommended 2. **Close background apps** - Free up RAM for better performance 3. **Use WiFi** - More stable than mobile data for remote access 4. **Keep device charged** - Running AionUi consumes battery ### Tested Environment - **Device**: Android 14 - **Termux Version**: 0.118.0 - **AionUi Version**: Latest release (e.g. 1.5.2) - **Proot-distro**: Ubuntu (latest) ### Creating a Startup Script For convenience, create a script to launch AionUi quickly: ```bash # Create script in Ubuntu (proot) cat > ~/start-aionui.sh << 'EOF' #!/bin/bash echo "Starting AionUi WebUI..." AionUi --no-sandbox --webui --remote EOF # Make executable chmod +x ~/start-aionui.sh # Run anytime ./start-aionui.sh ``` ### Quick Start Command (One-liner) From Termux main shell: ```bash proot-distro login ubuntu -- bash -c "AionUi --no-sandbox --webui --remote" ``` ### Feedback and Improvements If you encounter issues or have suggestions for improving Android support: 1. Check the [original community guide](https://gist.github.com/Manamama/b4f903c279b5e73bdad4c2c0a58d5ddd) 2. Report issues at [GitHub Issues #217](https://github.com/iOfficeAI/AionUi/issues/217) 3. Share your experience to help other Android users! --- ## Remote Access To allow access from other devices on your network, use the `--remote` flag: ### Windows ```cmd AionUi.exe --webui --remote ``` ### macOS ```bash /Applications/AionUi.app/Contents/MacOS/AionUi --webui --remote ``` ### Linux ```bash aionui --webui --remote ``` **Security Note**: Remote mode allows network access. Use only on trusted networks. Consider setting up authentication and firewall rules for production use. ### Finding Your Local IP Address **Windows:** ```cmd ipconfig ``` Look for "IPv4 Address" under your active network adapter. **macOS/Linux:** ```bash ifconfig # or ip addr show ``` Look for `inet` address (e.g., `192.168.1.100`). Access from other devices: `http://YOUR_IP_ADDRESS:3000` --- ## Troubleshooting ### Port Already in Use If port 3000 is already in use, the application will automatically try the next available port. Check the console output for the actual port number. ### Cannot Access from Browser 1. **Check if the application started successfully** - Look for "Server started on port XXXX" message in the console 2. **Try a different browser** - Chrome, Firefox, Safari, or Edge 3. **Clear browser cache** - Press `Ctrl+Shift+Delete` (Windows/Linux) or `Cmd+Shift+Delete` (macOS) ### Firewall Blocking Access **Windows:** ```cmd # Allow through Windows Firewall netsh advfirewall firewall add rule name="AionUi WebUI" dir=in action=allow protocol=TCP localport=3000 ``` **Linux (UFW):** ```bash sudo ufw allow 3000/tcp ``` **macOS:** Go to **System Preferences** → **Security & Privacy** → **Firewall** → **Firewall Options** → Add AionUi ### Application Not Found **Find application location:** **Windows:** ```cmd where AionUi.exe ``` **macOS:** ```bash mdfind -name "AionUi.app" ``` **Linux:** ```bash which aionui # or find /opt -name "aionui" 2>/dev/null ``` ### View Logs **Windows (PowerShell):** ```powershell & "C:\Program Files\AionUi\AionUi.exe" --webui 2>&1 | Tee-Object -FilePath aionui.log ``` **macOS/Linux:** ```bash /path/to/aionui --webui 2>&1 | tee aionui.log ``` --- ## Environment Variables You can customize WebUI behavior with environment variables: ```bash # Override the listening port export AIONUI_PORT=8080 # Allow remote access without passing --remote export AIONUI_ALLOW_REMOTE=true # Optional host hint (0.0.0.0 behaves the same as AIONUI_ALLOW_REMOTE=true) export AIONUI_HOST=0.0.0.0 # Then start the application aionui --webui # You can also pass the port directly via CLI aionui --webui --port 8080 ``` --- ## User Configuration File From v1.5.0+, you can store persistent WebUI preferences in `webui.config.json` located in your Electron user-data folder: | Platform | Location | | -------- | -------------------------------------------------------- | | Windows | `%APPDATA%/AionUi/webui.config.json` | | macOS | `~/Library/Application Support/AionUi/webui.config.json` | | Linux | `~/.config/AionUi/webui.config.json` | Example file: ```json { "port": 8080, "allowRemote": true } ``` Settings from CLI flags take priority, followed by environment variables, then the user config file. --- ## Command Line Options Summary | Option | Description | | ------------------ | --------------------------- | | `--webui` | Start in WebUI mode | | `--remote` | Allow remote network access | | `--webui --remote` | Combine both flags | --- ## Reset Admin Password If you forgot your admin password in WebUI mode, you can reset it using the `--resetpass` command. ### Using --resetpass Command **IMPORTANT:** The --resetpass command resets the password and generates a new random one. All existing JWT tokens will be invalidated. **Windows:** ```cmd # Using full path "C:\Program Files\AionUi\AionUi.exe" --resetpass # Or for a specific user "C:\Program Files\AionUi\AionUi.exe" --resetpass username ``` **macOS:** ```bash # Using full path /Applications/AionUi.app/Contents/MacOS/AionUi --resetpass # Or for a specific user /Applications/AionUi.app/Contents/MacOS/AionUi --resetpass username ``` **Linux:** ```bash # Using system path aionui --resetpass # Or for a specific user aionui --resetpass username # Or using full path /opt/AionUi/aionui --resetpass ``` ### What happens when you run --resetpass: 1. The command connects to the database 2. Finds the specified user (default: `admin`) 3. Generates a new random 12-character password 4. Updates the password hash in the database 5. Rotates the JWT secret (invalidating all previous tokens) 6. Displays the new password in the terminal ### After running --resetpass: 1. The command will display your new password - **copy it immediately** 2. Refresh your browser (Cmd+R or Ctrl+R) 3. You will be redirected to the login page 4. Login with the new password shown in the terminal ### Development Environment Only If you're in a development environment with Node.js, you can also use: ```bash # In the project directory npm run --resetpass # Or for a specific user npm run --resetpass username ``` --- ## Additional Resources - [Main README](./readme.md) - [中文说明](./readme_ch.md) - [日本語ドキュメント](./readme_jp.md) - [GitHub Issues](https://github.com/iOfficeAI/AionUi/issues) --- ## Support If you encounter any issues: 1. Check the [Troubleshooting](#troubleshooting) section 2. Search [existing issues](https://github.com/iOfficeAI/AionUi/issues) 3. Create a [new issue](https://github.com/iOfficeAI/AionUi/issues/new) with: - Your OS and version - AionUi version - Steps to reproduce - Error messages or logs --- **Happy using AionUi in WebUI mode!** 🚀 --- # Source: https://github.com/iOfficeAI/AionUi/wiki/ACP-Setup # 🤖 AionUi Multi-Agent Mode Configuration Tutorial This tutorial will detail how to configure and use Multi-Agent Mode in AionUi, including integration with external CLI tools like Claude Code, Qwen Code, CodeX, iFlow CLI, etc. These external tools are integrated through ACP (Agent Communication Protocol) for unified interface management. **[English](ACP-Setup)** | [简体中文](ACP-Setup-Chinese) ## 🎯 Multi-Agent Mode Overview Multi-Agent Mode is one of AionUi's core features, allowing you to use different AI agents in a unified interface. These external CLI tools are integrated through ACP (Agent Communication Protocol) with the following characteristics: - **Unified Interface Management**: All agents operate in the same interface - **Independent Functionality**: Each agent maintains its original features and capabilities - **Protocol Standardization**: Standardized communication through ACP protocol - **Flexible Extension**: Supports integration of more CLI tools that comply with ACP protocol ### Supported External Agents | Agent | CLI Command | Authentication Required | Status | |-------|-------------|------------------------|--------| | **Claude Code** | `claude` | ✅ | ✅ Supported | | **Qwen Code** | `qwen` | ✅ | ✅ Supported | | **CodeX** | `codex` | ✅ | ✅ Supported | | **iFlow CLI** | `iflow` | ✅ | ✅ Supported | | **Gemini CLI** | Built into AionUi | ✅ | ✅ Enabled by default | ### Multi-Agent Mode vs Gemini CLI Mode | Feature | Gemini CLI Mode | Multi-Agent Mode | |---------|-----------------|----------------| | **Installation Requirements** | **Built into AionUi, users get it by default after downloading** | **Requires users to download and install themselves, then AionUi recognizes and integrates** | | **Technical Architecture** | AionUi built-in Agent, based on Google Gemini CLI | External CLI tools integrated via ACP protocol | | **Feature Completeness** | Complete features (image generation, tool scheduling, multi-API key rotation, etc.) | Currently relatively simple, mainly GUI management of conversations and workspaces | | **Configuration Integration** | Direct access to all AionUi configuration features | Currently cannot directly use AionUi's LLM configuration, image generation, and other built-in features | | **Future Development** | Most complete functionality, continuous optimization | ACP-integrated tools will gradually catch up, unified management features planned | | **Use Cases** | Daily use, complete AI functionality experience | Professional users, specific CLI tool requirements | --- ## 🚀 Step 1: Install CLI Tools Before configuring Multi-Agent Mode, you need to install the corresponding CLI tools first. ### Claude Code Installation 1. **Install Claude CLI** ```bash # Install globally with npm npm install -g @anthropic-ai/claude-code ``` 2. **Verify Installation** ```bash claude --version ``` 3. **Authentication Configuration** ```bash # Login to Claude account claude login ``` > 📖 **Official Documentation**: [Claude Code GitHub](https://github.com/anthropics/claude-code) ### Qwen Code Installation 1. **Install Qwen CLI** ```bash # Install globally with npm npm install -g @qwen-code/qwen-code ``` 2. **Verify Installation** ```bash qwen --version ``` 3. **Authentication Configuration** ```bash # Login to Qwen account qwen login ``` > 📖 **Official Documentation**: [Qwen Code GitHub](https://github.com/QwenLM/qwen-code) ### CodeX Installation 1. **Install CodeX CLI** ```bash # Install globally with npm npm install -g @openai/codex ``` 2. **Verify Installation** ```bash # Check version codex --version ``` 3. **Authentication Configuration** ```bash # Login to OpenAI account codex login ``` > 📖 **Official Documentation**: [OpenAI Codex CLI](https://developers.openai.com/codex/cli/) ### iFlow CLI Installation 1. **Install iFlow CLI** ```bash # Install globally with npm npm install -g @iflow-ai/iflow-cli ``` 2. **Verify Installation** ```bash iflow --version ``` 3. **Authentication Configuration** ```bash # Login to iFlow account iflow login ``` > 📖 **Official Documentation**: [iFlow CLI GitHub](https://github.com/iflow-ai/iflow-cli) --- ## 💬 Step 2: Using Multi-Agent Mode ### Create Multi-Agent Conversation 1. **Select Agent** - Choose the external agent to use on the welcome interface - System will display detected available agents (integrated via ACP protocol) 2. **Create Conversation** - Enter message content - Select working directory (optional) - Click send to start conversation ![ACP conversation creation screenshot - showing agent selection and conversation creation](assets/Images/ACP.png) ### Conversation Features 1. **Real-time Connection Status** - Shows agent connection status - Automatic reconnection mechanism - Connection error prompts 2. **Permission Management** - CLI tools will request file operation permissions - Confirm or deny permission requests in AionUi - Supports one-time or permanent authorization 3. **Tool Calling** - Supports CLI tool's native functionality - File read/write operations - Code execution and debugging --- ## ❓ Common Questions ### Q: What's the difference between Multi-Agent Mode and Gemini CLI mode? **A**: Main differences: - **Gemini CLI Mode**: AionUi's built-in core functionality, users get it by default after downloading, supports image generation, tool scheduling and other complete features - **Multi-Agent Mode**: Requires users to install external CLI tools themselves, AionUi recognizes and integrates them through ACP protocol, currently relatively simple functionality, will develop MCP settings functionality to enhance integration in the future ### Q: When to choose Multi-Agent Mode? **A**: Selection recommendations: - **Daily Use**: Recommend Gemini CLI mode, most complete functionality, ready to use out of the box - **Professional Needs**: If you need specific CLI tool functionality (like Claude Code, Qwen Code, etc.), you can choose Multi-Agent Mode - **Future Planning**: MCP functionality will let Multi-Agent Mode enjoy more unified features ### Q: How to know if Multi-Agent Mode is working properly? **A**: Check methods: - Can see agent options on welcome interface - Can connect normally when creating conversations - Can receive replies when sending messages - Permission requests display normally ### Q: What features does Multi-Agent Mode support? **A**: Current features: - Basic conversation functionality - File operation permission management - CLI tool's native functionality - Working directory management --- ## 🔧 Troubleshooting ### Q: Multi-Agent Mode not detected? **A**: Check steps: 1. **Confirm CLI tool is properly installed** ```bash # macOS/Linux which claude which qwen which iflow # Windows where claude where qwen where iflow ``` 2. **Verify CLI is in system PATH** - Ensure CLI tools are in system environment variable PATH - Restart terminal or command line window 3. **Check CLI tool version** ```bash claude --version qwen --version iflow --version ``` 4. **Restart AionUi to re-detect** - AionUi automatically scans system PATH on startup - Detects installed external CLI tools - Shows available Multi-Agent options on welcome interface ### Q: Authentication failed? **A**: Solutions: 1. Run `claude login` or `qwen login` in terminal 2. Complete CLI tool authentication process 3. Restart AionUi to reconnect ### Q: Connection timeout? **A**: Possible reasons: 1. Network connection issues 2. CLI tool service unavailable 3. Firewall blocking connection 4. CLI tool version too old ### Q: Permission requests not showing? **A**: Check configuration: 1. Confirm Multi-Agent Mode is properly connected 2. Check AionUi permission settings 3. Restart conversation to re-establish connection --- ## 📚 Related Documentation - **Quick Start**: [Getting Started](Getting-Started) - **LLM Configuration**: [LLM Configuration](LLM-Configuration) - **Image Generation Configuration**: [Image Generation Setup](AionUi-Image-Generation-Tool-Model-Configuration-Guide) - **Common Questions**: [FAQ](FAQ) --- **Need Help?** - 🐛 [Report Issues](https://github.com/iOfficeAI/AionUi/issues) - 💬 [Community Discussions](https://github.com/iOfficeAI/AionUi/discussions) - 📖 [Complete Documentation](Home) *Multi-Agent Mode lets you enjoy the powerful functionality of multiple AI tools in AionUi!* --- # Source: https://github.com/iOfficeAI/AionUi/wiki/Configuration-Guides # 📚 AionUi Configuration & Usage Guides Welcome to AionUi's comprehensive configuration and usage guides! This section provides detailed tutorials for setting up and using all AionUi features. **[English](Configuration-Guides)** | [简体中文](Configuration-Guides-Chinese) ## 🚀 Getting Started ### [Quick Start Guide](Getting-Started) **Start here if you're new to AionUi** - Download and installation - First launch configuration - Basic setup and authentication - Your first conversation ## ⚙️ Core Configuration ### [LLM Configuration](LLM-Configuration) **Configure your AI models and platforms** - Google account login setup - API key configuration for multiple platforms - Multi-API key rotation - Model capability configuration - Advanced settings (proxy, custom URLs) ### [Multi-Agent Mode Setup](ACP-Setup) **Connect external CLI tools** - Claude Code installation and configuration - CodeX installation and configuration - Qwen Code setup - iFlow CLI integration - Multi-Agent mode management - Troubleshooting guide ### [Image Generation Setup](AionUi-Image-Generation-Tool-Model-Configuration-Guide) **Configure AI image generation** - Enable image generation tools - Model selection for image generation - Platform configuration - Usage examples and best practices ### [MCP Configuration](MCP-Configuration-Guide) **Configure Model Context Protocol services** - MCP service addition and management - JSON configuration and one-click import - Connection testing and status monitoring - Tool discovery and usage examples ### [WebUI Configuration](WebUI-Configuration-Guide) **Access AionUi through web browsers** - Start WebUI mode - Remote access configuration - Authentication and security setup - Background service deployment - Password management ## ❓ Support & Troubleshooting ### [FAQ](FAQ) **Common issues and solutions** - Installation problems - Configuration issues - Performance troubleshooting - Feature-specific questions --- ## 🔗 Related Resources - **Application Cases**: [Use Cases Overview](Use-Cases-Overview) - See AionUi in action - **Community**: [GitHub Discussions](https://github.com/iOfficeAI/AionUi/discussions) - **Issues**: [Report Problems](https://github.com/iOfficeAI/AionUi/issues) - **Updates**: [GitHub Releases](https://github.com/iOfficeAI/AionUi/releases) --- ## 💡 Pro Tips 1. **Start Simple**: Begin with Google login for Gemini - it's the easiest way to get started 2. **Read the Prerequisites**: Each guide lists what you need before starting 3. **Check Troubleshooting**: If something doesn't work, check the FAQ first 4. **Join the Community**: Get help from other users in GitHub Discussions --- *Need help? Check our [FAQ](FAQ) or [report an issue](https://github.com/iOfficeAI/AionUi/issues)!* --- # Source: https://github.com/iOfficeAI/AionUi/wiki/FAQ # ❓ AionUi Frequently Asked Questions This FAQ covers the most common questions and issues users encounter when using AionUi. **[English](FAQ)** | [简体中文](FAQ-Chinese) --- ## 🚀 Installation & Setup ### Q: How do I install AionUi? **A:** AionUi is available for Windows, macOS, and Linux. Download the latest release from our [GitHub releases page](https://github.com/iOfficeAI/AionUi/releases) and follow the installation instructions for your operating system. ### Q: What are the system requirements? **A:** - **Operating System**: Windows 10+, macOS 10.15+, or Linux (Ubuntu 18.04+) - **Memory**: Minimum 4GB RAM, recommended 8GB+ - **Storage**: At least 2GB free space - **Network**: Internet connection for AI model access ### Q: Can I run AionUi on older operating systems? **A:** AionUi requires modern operating systems due to its Electron-based architecture. We recommend updating to supported versions for the best experience. --- ## 🔑 Authentication & API Keys ### Q: Do I need to create API keys for all platforms? **A:** No, you can start with just one platform. We recommend beginning with Google Gemini (free) or OpenAI (if you have credits). You can add more platforms later as needed. ### Q: How do I get a Google Gemini API key? **A:** 1. Visit [Google AI Studio](https://aistudio.google.com/) 2. Sign in with your Google account 3. Navigate to "Get API Key" and create a new key 4. Copy the key and paste it into AionUi's LLM settings ### Q: My API key isn't working. What should I check? **A:** - Verify the key is correctly copied (no extra spaces or characters) - Check if the key has expired or been revoked - Ensure you have sufficient credits/quota remaining - Try regenerating the key from the platform's dashboard ### Q: Can I use multiple API keys for the same platform? **A:** Yes! AionUi supports multiple API keys per platform with automatic rotation. This helps with rate limits and reliability. --- ## 🤖 AI Models & Agents ### Q: What's the difference between Gemini CLI and Multi-Agent Mode? **A:** Main differences: - **Gemini CLI Mode**: AionUi's built-in core functionality, used by default after download, supports image generation, tool scheduling and other complete features - **Multi-Agent Mode**: Requires users to install external CLI tools themselves, AionUi recognizes and integrates them through ACP protocol, currently has relatively simple functionality, future MCP settings will enhance integration ### Q: Which agent should I choose? **A:** Selection recommendations: - **Daily use**: Recommend Gemini CLI mode, most complete functionality, ready to use out of the box - **Professional needs**: If you need specific CLI tool functionality (like Claude Code, Qwen Code, etc.), choose Multi-Agent Mode - **Future planning**: MCP functionality will allow Multi-Agent Mode to enjoy more unified features ### Q: How do I switch between different AI models? **A:** Model switching is not currently supported. Switching to different agents will automatically use their default models: - Gemini CLI Mode: Uses configured default models - Multi-Agent Mode: Choose different agents on the welcome page, each agent uses its default model - **Note**: Model switching during current conversation is not currently supported ### Q: Why can't I see image generation tools? **A:** Check the following configuration: - Enable image generation in "Tools Settings" - Select a model that supports image generation - Refer to [Image Generation Configuration Guide](AionUi-Image-Generation-Tool-Model-Configuration-Guide) --- ## 🖼️ Image Generation ### Q: Which image generation models are recommended? **A:** We recommend Gemini 2.5 Flash Image Preview for high-quality image generation. Check Google AI Studio for current pricing policies. ### Q: How do I configure image generation? **A:** 1. Set up a platform with image models (Gemini or OpenRouter) 2. Go to Settings → Tools → Image Generation 3. Select an image generation model 4. Test with a simple prompt like "Generate a sunset landscape" ### Q: My image generation is slow. How can I improve it? **A:** - Choose faster models (like Gemini image models) - Reduce image resolution requirements - Check your internet connection - Consider upgrading to premium models for better performance --- ## 🔧 Configuration & Settings ### Q: Where are my settings stored? **A:** All conversations are saved locally: - **macOS**: `~/Library/Application Support/AionUi/` - **Windows**: `%APPDATA%/AionUi/` - **Linux**: `~/.config/AionUi/` ### Q: How do I backup my configuration? **A:** 1. Manually copy the configuration file directory 2. Export your configuration file 3. Store it safely for future restoration ### Q: Can I reset AionUi to default settings? **A:** Yes, you can reset settings: 1. Close AionUi completely 2. Delete the configuration folder 3. Restart AionUi to create fresh settings --- ## 🚨 Troubleshooting ### Q: AionUi won't start. What should I do? **A:** 1. Check if another instance is already running 2. Restart your computer 3. Reinstall AionUi if the problem persists 4. Check our [GitHub issues](https://github.com/iOfficeAI/AionUi/issues) for known problems ### Q: I'm getting "API key invalid" errors. **A:** - Verify the key is correctly entered - Check if the key has expired - Ensure you have sufficient credits - Try regenerating the key ### Q: My conversations are not saving. **A:** - Check if you have write permissions to the AionUi data directory - Ensure sufficient disk space is available - Try restarting AionUi ### Q: The interface is slow or unresponsive. **A:** - Close unnecessary applications to free up memory - Check your internet connection - Try reducing the number of concurrent conversations - Restart AionUi --- ## 🔄 Updates & Maintenance ### Q: How do I update AionUi? **A:** - **Automatic**: AionUi will notify you of updates - **Manual**: Download the latest version from GitHub releases - **Settings**: Check for updates in Settings → About ### Q: Will updating affect my settings and conversations? **A:** No, updates preserve your settings and conversation history. However, we recommend backing up important data before major updates. ### Q: How often is AionUi updated? **A:** We release updates regularly with new features, bug fixes, and improvements. Follow our [GitHub releases](https://github.com/iOfficeAI/AionUi/releases) for the latest updates. --- ## 🔒 Security & Privacy ### Q: Is my data secure? **A:** - Conversations are stored locally on your device - API keys are encrypted and stored securely - We don't collect personal data without your consent - Review our privacy policy for detailed information ### Q: How do I delete my conversation history? **A:** 1. Manually delete conversation data from the configuration file directory 2. Or delete the entire configuration folder to reset all data 3. Restart AionUi to apply changes --- ## 🤝 Community & Support ### Q: Where can I get help? **A:** - **GitHub Issues**: Report bugs and request features - **GitHub Discussions**: Ask questions and share tips - **Documentation**: Check our comprehensive guides - **Community**: Join our user community for support ### Q: How can I contribute to AionUi? **A:** - **Code**: Submit pull requests for bug fixes and features - **Documentation**: Help improve our guides and tutorials - **Testing**: Report issues and provide feedback - **Community**: Help other users in discussions ### Q: Is AionUi open source? **A:** Yes! AionUi is open source and available on GitHub. We welcome contributions from the community. --- ## 📚 Additional Resources - **[Getting Started Guide](Getting-Started)**: Complete setup tutorial - **[LLM Configuration](LLM-Configuration)**: Detailed model setup guide - **[Multi-Agent Mode Setup](ACP-Setup)**: External CLI tool integration - **[Image Generation Setup](AionUi-Image-Generation-Tool-Model-Configuration-Guide)**: Image generation configuration --- *Still have questions? [Open an issue](https://github.com/iOfficeAI/AionUi/issues) or [start a discussion](https://github.com/iOfficeAI/AionUi/discussions) on GitHub!* --- # Source: https://github.com/iOfficeAI/AionUi/wiki/Getting-Started # 🚀 AionUi Quick Start Guide Welcome to AionUi! This guide will help you install, configure, and start using AionUi in just 5 minutes. **[English](Getting-Started)** | [简体中文](Getting-Started-Chinese) ## 📥 Step 1: Download and Install ### System Requirements - **macOS**: macOS 10.14 or higher - **Windows**: Windows 10 or higher - **Linux**: Ubuntu 18.04+ or other mainstream distributions - **Memory**: At least 4GB RAM - **Storage**: At least 500MB available space ### Download Methods 1. Visit [AionUi GitHub Releases](https://github.com/iOfficeAI/AionUi/releases) 2. Choose the version suitable for your operating system: - **macOS**: Download `.dmg` file (Apple Silicon or Intel) - **Windows**: Download `.exe` installer - **Linux**: Download `.deb` or `.AppImage` file ### Installation Steps - **macOS**: Double-click the `.dmg` file and drag AionUi to the Applications folder - **Windows**: Run the `.exe` installer and follow the prompts - **Linux**: Install the `.deb` file using package manager, or run the `.AppImage` directly --- ## 🎯 Step 2: First Launch Configuration ### Launch the Application After installation, launch AionUi. You'll see the welcome interface on first startup: ![Welcome interface screenshot - showing main interface and model selection](assets/Images/hello%20screen.png) ### Choose AI Agent Mode The default interface you see is Gemini CLI mode, which is AionUi's built-in Agent (used by default after download). AionUi also supports Multi-Agent Mode, including external CLI tools (requires users to install themselves). For detailed information, please refer to the [Multi-Agent Mode Configuration Tutorial](ACP-Setup). --- ## ⚙️ Step 3: Configure Authentication ### Method 1: Google Account Login (Recommended) 1. **Enter Settings** - Click the "Settings" icon in the left sidebar 2. **Configure Google Authentication** - In the "Gemini Settings" page - **Network Proxy Settings** (if needed): - If you have a network proxy, recommend setting VPN to US - Enter proxy address in proxy settings - Click the "Google Login" button - Complete Google account login in the popup browser window - After successful login, the interface will display your Google account **💡 Login Troubleshooting**: - **Network Issues**: Ensure VPN is set to US, enter proxy address - **Project ID Issues**: Need to create Google Cloud Project, see detailed tutorial below ![Google login configuration screenshot - showing login button and account info](assets/Images/login%20setting.png) ### 📋 Google Cloud Project ID Creation Detailed Tutorial If you encounter Project ID issues, follow these steps to create a Google Cloud Project: #### Step 1: Access Google Cloud Console 1. Open your browser and visit [Google Cloud Console](https://console.cloud.google.com/) 2. Sign in with your Google account #### Step 2: Create New Project 1. At the top of the page, click the project selector (dropdown menu showing current project name) 2. Click **"New Project"** button 3. Fill in project information: - **Project Name**: Enter a descriptive name (e.g., "AionUi-Gemini-Project") - **Organization**: Select your organization (if any) - **Location**: Choose project location 4. Click **"Create"** button #### Step 3: Get Project ID 1. After project creation, you can see the newly created project in the project selector 2. Click the project name to enter the project details page 3. In the project information card, find **"Project ID"** (format like: `my-project-123456`) 4. Copy this Project ID #### Step 4: Configure in AionUi 1. Return to AionUi's Gemini settings page 2. Paste the copied Project ID in the Project ID input box 3. Click save configuration #### Step 5: Enable Required APIs (Optional) To ensure complete functionality, it's recommended to enable the following APIs: 1. In Google Cloud Console, click **"APIs & Services"** > **"Library"** in the left menu 2. Search and enable: - **Generative Language API** - **AI Platform API** - **Vertex AI API** **Reference Documentation**: [Gemini CLI Authentication Documentation](https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/authentication.md#workspace-gca) ### Method 2: API Key Configuration If you prefer using API keys, you can configure multiple platforms: 1. **Enter Model Settings** - Click the "Settings" icon in the left sidebar - Select "Model Settings" 2. **Add Platform** - Click the "Add Model" button - Select platform type (Gemini, OpenAI, ModelScope, OpenRouter, etc.) - Enter API key and configuration information ![Model configuration screenshot - showing platform selection and API key input](assets/Images/llm%20setting.png) **Detailed Configuration**: See the [LLM Configuration Tutorial](LLM-Configuration) for detailed configuration steps for each platform. --- ## 💬 Step 4: Start Your First Conversation ### Create New Conversation 1. **Return to Main Interface** - Click the "Chat" icon in the left sidebar 2. **Select Model** - Choose the AI model to use in the bottom left of the input box - If using Google login, you'll see "Gemini Google Auth" option 3. **Enter Message** - Type your question or request in the input box - You can upload files or select a working directory ![Conversation interface screenshot - showing input box, model selection, and send button](assets/gifs/file-management/file-organization.gif) ### Example Conversations Try these simple conversations: ``` Hello, please introduce yourself ``` ``` Help me write a Python function to calculate Fibonacci sequence ``` ``` Please help me analyze the content of this file ``` --- ## 🔧 Step 5: Basic Feature Experience ### File Upload - **Drag and Drop**: Directly drag files to the input box - **Click Upload**: Click the "+" button to select files or folders - **Supported Formats**: Text files, images, code files, etc. ### Multi-Session Management - **Create New Session**: Click "New Conversation" button - **Switch Sessions**: Click different sessions in the left session list ### Working Directory Association - **Associate Working Directory**: Click the "+" button in the input box, select "Open Folder" from the dropdown - **Workspace Display**: After association, the "workspace" area will appear on the right side of the session, showing a directory tree - **File Selection**: You can quickly view and select files to add to the dialog - **Session Lock**: After working directory association, it cannot be modified during the session --- ## ❓ Common Questions ### Q: No models visible after startup? **A**: Please ensure authentication is configured: - Use Google login, or - Add at least one platform's API key in "Model Settings" ### Q: Image generation not working? **A**: Check the following configuration: - Image generation is enabled in "Tool Configuration" - A model supporting image generation is selected - Refer to [Image Generation Configuration Guide](AionUi-Image-Generation-Tool-Model-Configuration-Guide) ### Q: How to switch between different AI models? **A**: Model switching is not currently supported. Switching to different agents will automatically use their default models: - Gemini CLI mode: Uses configured default models - Multi-Agent mode: Choose different agents on the welcome page, each agent uses its default model ### Q: Where are conversation histories saved? **A**: All conversations are saved locally: - **macOS**: `~/Library/Application Support/AionUi/` - **Windows**: `%APPDATA%/AionUi/` - **Linux**: `~/.config/AionUi/` --- ## 🎉 Congratulations! You have successfully completed the basic configuration of AionUi! Now you can: - ✅ Use Gemini CLI mode for daily AI conversations - ✅ Upload files for AI analysis and processing - ✅ Use image generation features to create images - ✅ Manage multiple conversation sessions ## 📚 Next Steps - **Deep Learning**: Check out [LLM Configuration Tutorial](LLM-Configuration) - **Advanced Features**: Learn about [Multi-Agent Mode Configuration](ACP-Setup) - **Practical Cases**: Browse [Application Case Library](Use-Cases-Overview) - **Troubleshooting**: Refer to [FAQ](FAQ) --- **Need Help?** - 📖 [Complete Documentation](Home) - 🐛 [Report Issues](https://github.com/iOfficeAI/AionUi/issues) - 💬 [Community Discussions](https://github.com/iOfficeAI/AionUi/discussions) *Let AI become your work assistant, making every day easier and more efficient!* --- # Source: https://github.com/iOfficeAI/AionUi/wiki/Home # AionUi Wiki Welcome to the AionUi Wiki! Your comprehensive guide to installing, configuring, and using AionUi - the powerful AI assistant that works right on your computer. **[English](Home)** | [简体中文](Home-Chinese) ## 🌟 What is AionUi? AionUi is a desktop GUI application based on Google Gemini CLI, a free AI assistant that works right on your computer. Think of it as having a smart helper that can chat with you and get things done - from organizing files to analyzing data, all through simple conversation. ### Key Features - **Multi-Agent Mode**: Seamlessly integrate multiple terminal AI agents (Gemini CLI, Claude Code, Qwen Code, CodeX, iFlow CLI, etc.) - **AI Image Generation & Editing**: Intelligent image generation, editing, and recognition powered by Gemini 2.5 Flash Image Preview - **File Management**: Batch renaming, auto organization, smart classification, file merging - **Multi-Task Processing**: Multiple conversations, no task confusion, independent memory, double efficiency - **Multi-API Key Rotation Service**: Multi-key automatic rotation, intelligent error recovery, high availability --- ## 📚 [Configuration & Usage Guides](Configuration-Guides) | Guide | Description | Difficulty | Time | |-------|-------------|------------|------| | [Quick Start Guide](Getting-Started) | Start here for new users, includes download installation and first-time setup | Beginner | 5 minutes | | [Image Generation Setup](AionUi-Image-Generation-Tool-Model-Configuration-Guide) | Configure AI image generation features and model selection | Intermediate | 5-10 minutes | | [LLM Configuration](LLM-Configuration) | Configure AI models and platforms, including Google login and API key setup | Intermediate | 10-15 minutes | | [Multi-Agent Mode Setup](ACP-Setup) | Connect external CLI tools (Claude Code, Qwen Code, CodeX, iFlow CLI, etc.) | Advanced | 15-20 minutes | | [MCP Configuration](MCP-Configuration-Guide) | Configure Model Context Protocol services to extend AI assistant capabilities | Advanced | 10-15 minutes | | [WebUI Configuration](WebUI-Configuration-Guide) | Configure WebUI mode for browser access and remote connections | Intermediate | 5-10 minutes | | [FAQ](FAQ) | Common questions and solutions, troubleshooting guide | - | - | --- ## 🎯 [Application Use Cases](Use-Cases-Overview) | Case | Description | Use Cases | |------|-------------|-----------| | [File Management](file-management) | Smart file organization, batch processing, duplicate cleanup | Daily file management | | [Excel Smart Processing (Coming Soon)](excel-processing) | Auto data fill, smart queries, chart creation | Data processing analysis | | [Smart Information Gathering (Coming Soon)](smart-information-gathering) | Information search recording, data extraction, multi-source integration | Information collection | | [Local Knowledge Base Application (Coming Soon)](local-knowledge-base-application) | Style learning, document extraction, knowledge Q&A | Knowledge management | | [AI Learning Assistant (Coming Soon)](ai-learning-assistant) | Technical problem solving, concept explanation, learning guidance | Learning assistance | | [Writing & Content Creation (Coming Soon)](writing-content-creation) | Email drafting, report outlines, content polishing | Content creation | --- ## 🤝 Join the Community Found a cool new way to use AionUi? Share it with everyone! We'd love to have you contribute to this growing collection of AI use cases. ### How to Contribute - Submit a Pull Request with your new use case - You'll automatically be added as a contributor ### Share Your Ideas - Report bugs or suggest features via GitHub Issues - Share your tips and tricks with the community ### Let's Grow Together - Help others discover what AI can do - Build the ultimate AI use case library --- ## 🔗 Quick Links - **Configuration Guides**: [Configuration & Usage](Configuration-Guides) - **Use Cases**: [Application Cases](Use-Cases-Overview) - **Community**: [GitHub Discussions](https://github.com/iOfficeAI/AionUi/discussions) - **Issues**: [Report Problems](https://github.com/iOfficeAI/AionUi/issues) - **Updates**: [GitHub Releases](https://github.com/iOfficeAI/AionUi/releases) --- *This wiki grows with every contribution. Join us and help make AI accessible to everyone!* --- # Source: https://github.com/iOfficeAI/AionUi/wiki/AionUi-Image-Generation-Tool-Model-Configuration-Guide # AionUi Image Generation Tool Model Configuration Guide > This guide will help you configure multiple image generation models: > 1) Gemini official 2.5 Flash Image Preview model configuration > 2) OpenRouter platform paid image model configuration > 3) Model selection and usage recommendations **[English](AionUi-Image-Generation-Tool-Model-Configuration-Guide)** | [简体中文](AionUi-Image-Generation-Tool-Model-Configuration-Guide-Chinese) --- ## 1. Gemini Official Image Model Configuration (Recommended) ### 1.1 Get Gemini API Key 1. Visit Google AI Studio: `https://aistudio.google.com/` 2. Log in with your Google account. 3. Create a new API Key on the API Keys page. ### 1.2 Bind Gemini in AionUi 1. Open AionUi → Settings → LLM Settings. 2. Add new model, select "Google" platform. 3. Enter Gemini API Key and save. ![Configure LLM Example](assets/Images/configure%20llm.png) ### 1.3 Configure Gemini Image Model 1. Open AionUi → Settings → Tools Configuration → Image Generation Tool. 2. Select Gemini model that supports image generation from Google platform. 3. Confirm the model supports image generation functionality and save configuration. ![Set Tool LLM Example](assets/Images/set%20tool%20llm.png) --- ## 2. OpenRouter Platform Image Model Configuration ### 2.1 Get OpenRouter API Key 1. Visit `https://openrouter.ai/`, register and log in with Google / GitHub / email. 2. Open Keys page: `https://openrouter.ai/keys`. 3. Click "Create Key", name your key (e.g., "AionUi"), create and copy to save (only shown once). ![Create API Key Example](assets/Images/open%20router%20create%20key.jpeg) **Important**: OpenRouter has discontinued free image models. You need to purchase credits to use paid models. ### 2.2 Bind OpenRouter in AionUi 1. Open AionUi → Settings → LLM Settings. 2. Add new model, select "OpenRouter" platform. 3. Paste the API Key copied in the previous step into the key input field and save. ### 2.3 Configure Image Model 1. Open AionUi → Settings → Tools Configuration → Image Generation Tool. 2. In model selection, choose models with image generation capabilities from OpenRouter platform: - Look for models containing keywords like `image`, `dall-e`, `midjourney`, `stable-diffusion`, `flux` - Select image generation models suitable for your needs - Pay attention to model pricing and usage limits --- ## 3. Verify Configuration Success 1. Return to chat, select LLM that supports tool calling to start new conversation. 2. Input "What tools do you have?" should show tool list including `image-generation`. ![Tool List Example](assets/Images/tool%20check.png) 3. Try sending image generation command, e.g.: "Generate a 1024×1024 blue neon cyberpunk city nightscape" to verify. ![Image Generation Test Example](assets/Images/image%20generation%20test.png) --- ## 4. Frequently Asked Questions ### 4.1 Model Selection Recommendations In image generation tool settings, you need to select an image model. Choose appropriate model based on your needs: - **High Quality**: Recommend Gemini 2.5 Flash Image Preview - **Creative Design**: Choose models supporting high-quality image generation (like DALL-E series, Midjourney, etc.) - **Fast Generation**: Choose models with faster generation speed (like Flux series, Gemini image models, etc.) **Cost Considerations**: - **Official Models**: Choose Gemini official models - **Sufficient Budget**: Choose commercial image generation models for best quality - **Balanced Cost-Performance**: Choose cost-effective image generation models ### 4.2 Configuration Issues - **Invalid API Key**: Check if key is correctly copied and activated - **Model Unavailable**: Confirm model name is correct and platform configuration is correct - **Generation Failed**: Check network connection and ensure sufficient account balance ### 4.3 Usage Issues - **Tools Not Showing**: Confirm image model is correctly configured, restart AionUi and retry - **Poor Generation Quality**: Try adjusting prompt descriptions or switch to other image models - **Slow Generation Speed**: Choose models with faster generation speed or check network connection ### 4.4 Platform Support Information Currently AionUi supports image generation models from Gemini and OpenRouter platforms. We are continuously developing support for more platforms, including ModelScope, Hugging Face and other open-source model platforms. Stay tuned! --- ## 5. Reference Links - **OpenRouter**: `https://openrouter.ai/` | `https://openrouter.ai/models` - **Google AI Studio**: `https://aistudio.google.com/` - **AionUi Official Documentation**: Check latest configuration instructions --- # Source: https://github.com/iOfficeAI/AionUi/wiki/LLM-Configuration # ⚙️ AionUi LLM Configuration Tutorial This tutorial will detail how to configure various large language models in AionUi, including Gemini, OpenAI, ModelScope, OpenRouter and other platforms, as well as advanced features like multi-API key rotation. **[English](LLM-Configuration)** | [简体中文](LLM-Configuration-Chinese) ## 🎯 Configuration Overview AionUi supports multiple LLM platforms, each with different configuration methods: | Platform | Authentication | Multi-Key Support | Special Features | |----------|----------------|-------------------|------------------| | **Gemini** | API Key / Google Login | ✅ | Image generation, tool calling | | **OpenAI** | API Key | ✅ | Function calling, image generation | | **ModelScope** | API Key | ❌ | Chinese optimization | | **OpenRouter** | API Key | ❌ | Multi-model aggregation | | **Custom Platform** | API Key | ✅ | OpenAI-compatible interface | --- ## 🌟 Method 1: Google Account Login (Recommended) ### Advantages - **No API Key Required**: Direct Google account login - **Auto Update**: Token automatically refreshes, no manual maintenance - **Secure & Reliable**: Uses OAuth 2.0 standard authentication - **Complete Features**: Supports all Gemini functionality ### Configuration Steps 1. **Enter Gemini Settings** - Click the "Settings" icon in the left sidebar - Select "Gemini Settings" 2. **Google Login** - Click the "Google Login" button - Complete Google account login in the popup browser window - Authorize AionUi to access your Google account ![Google login configuration screenshot - showing login button and authorization page](assets/Images/login%20before.png) 3. **Verify Login Status** - After successful login, the interface will display your Google account information - You can click "Logout" button to switch accounts ![Google account status screenshot - showing logged-in account info](assets/Images/login%20setting.png) ### Common Login Issues If you encounter problems with Google login, try the following solutions: #### 1. Network Issues - **VPN Setup**: It's recommended to set VPN to US region - **Proxy Configuration**: Fill in proxy address in Gemini settings - **Network Check**: Ensure stable network connection and normal access to Google services #### 2. Cloud Project ID Issues - **Solution**: Need to create Google Cloud Project, detailed steps please refer to the "📋 Google Cloud Project ID Creation Detailed Tutorial" section in [Getting Started Guide](Getting-Started) --- ## 🔑 Method 2: API Key Configuration ![LLM configuration interface screenshot - showing model configuration and platform selection](assets/Images/model%20setting.png) ### Gemini Platform Configuration 1. **Get Gemini API Key** - Visit [Google AI Studio](https://aistudio.google.com/) - Login with Google account - Create new API Key in "API Keys" page 2. **Configure in AionUi** - Click the "Settings" icon in the left sidebar - Select "Model Settings" - Click "Add Model" button - Select platform: **Gemini** - Enter API Key - System will automatically fetch available model list ### Custom Platform Configuration 1. **Get API Key** - Visit the corresponding platform's API Key management page - Login to account and create new API Key - Copy API Key for later use 2. **Configure in AionUi** - Select platform: **Custom Platform** - Enter corresponding Base URL - Enter API Key - Select models to use **Common Platform Base URLs**: - **OpenAI**: `https://api.openai.com/v1` - **Anthropic**: `https://api.anthropic.com/v1` - **xAI**: `https://api.x.ai/v1` - **DeepSeek**: `https://api.deepseek.com` - **Moonshot**: `https://api.moonshot.cn/v1` - **Zhipu**: `https://open.bigmodel.cn/api/paas/v4` ### ModelScope Platform Configuration 1. **Get ModelScope API Key** - Visit [ModelScope](https://modelscope.cn/my/myaccesstoken) - Login with Alibaba Cloud account - Create access token 2. **Configure in AionUi** - Select platform: **ModelScope** - Base URL: `https://api-inference.modelscope.cn/v1` - Enter ModelScope API Key - Select models (like qwen-turbo, qwen-plus, etc.) ### OpenRouter Platform Configuration 1. **Get OpenRouter API Key** - Visit [OpenRouter](https://openrouter.ai/keys) - Register OpenRouter account - Create API Key 2. **Configure in AionUi** - Select platform: **OpenRouter** - Base URL: `https://openrouter.ai/api/v1` - Enter OpenRouter API Key - Select models (supports various open-source and commercial models) --- ## 🔄 Multi-API Key Rotation Configuration ### Feature Description AionUi supports automatic multi-API key rotation to improve service reliability and availability: - **Automatic Rotation**: Automatically switch to next key when current key encounters errors - **Smart Blacklist**: Failed keys are temporarily blacklisted for 90 seconds - **Error Recovery**: Blacklisted keys automatically recover after expiration - **Load Balancing**: Randomly select starting key to distribute request pressure ### Configuration Method 1. **Enter Multiple Keys in API Key Field** ``` sk-xxx1,sk-xxx2,sk-xxx3 ``` Or use line breaks: ``` sk-xxx1 sk-xxx2 sk-xxx3 ``` 2. **Supported Platforms** - ✅ **Gemini**: Supports multi-key rotation - ✅ **OpenAI**: Supports multi-key rotation - ❌ **ModelScope**: Not currently supported - ❌ **OpenRouter**: Not currently supported ![Multi-API Key configuration screenshot - showing multiple key input format](assets/Images/multi-key.png) ### Rotation Mechanism Details 1. **Error Detection** - Detect errors like 401 (authentication failed), 429 (rate limit), 503 (service unavailable) - Automatically add current key to blacklist 2. **Automatic Switching** - Randomly select next key from available key list - Update environment variables, reinitialize client 3. **Blacklist Management** - Failed keys are blacklisted for 90 seconds - Blacklisted keys automatically recover after expiration - Avoid performance issues from frequent switching --- ## ❓ Common Questions ### Q: How to know if configuration is successful? **A**: Check methods: - Can see configured platforms and models in model list - Can select configured models in conversation interface - Can receive normal replies when sending messages ### Q: Multi-API key rotation not working? **A**: Check points: - Ensure key format is correct (comma or line break separated) - Check if platform supports multi-key (currently only Gemini and OpenAI support) - Check console logs to understand rotation status ### Q: Model list empty or loading failed? **A**: Possible reasons: - API key invalid or expired - Base URL configuration error - Network connection issues - Platform service temporarily unavailable ### Q: How to switch between different models? **A**: Switching methods: - Select different models when starting a new conversation - Model switching during current conversation is not currently supported - System will remember your selection preferences ### Q: Configured models not visible in conversation? **A**: Check configuration: - Ensure model supports `function_calling` capability - Re-save configuration and restart application --- ## 📚 Related Documentation - **Quick Start**: [Quick Start Guide](Getting-Started) - **Image Generation Configuration**: [Image Generation Setup](AionUi-Image-Generation-Tool-Model-Configuration-Guide) - **Multi-Agent Mode Configuration**: [Multi-Agent Mode Setup](ACP-Setup) - **Common Questions**: [FAQ](FAQ) --- **Need Help?** - 🐛 [Report Issues](https://github.com/iOfficeAI/AionUi/issues) - 💬 [Community Discussions](https://github.com/iOfficeAI/AionUi/discussions) - 📖 [Complete Documentation](Home) *After configuration, you can enjoy multi-platform, multi-model AI experience!* --- # Source: https://github.com/iOfficeAI/AionUi/wiki/MCP-Configuration-Guide # 🔌 AionUi MCP Configuration Guide Welcome to AionUi's MCP (Model Context Protocol) configuration guide! This tutorial will provide detailed instructions on how to configure and manage MCP services in AionUi, helping you easily extend your AI assistant's capabilities. **[English](MCP-Configuration-Guide)** | [简体中文](MCP-Configuration-Guide-Chinese) ## 🌟 What is MCP? **MCP (Model Context Protocol)** is an open standard that allows AI assistants to communicate securely and structurally with external tools and services. In AionUi, MCP enables you to: - **Extend AI functionality**: Connect to various external tools and services - **Unified management**: Manage all MCP services in one interface - **Simplify configuration**: Support multiple addition methods, reducing configuration difficulty - **Real-time monitoring**: Automatically test connection status to ensure service availability ### How MCP Works ``` AI Assistant ←→ MCP Protocol ←→ External Tools/Services ``` MCP acts as a middleware layer, allowing AI assistants to: 1. **Discover tools**: Automatically identify available tools and functions 2. **Call services**: Securely execute external operations 3. **Get results**: Receive and process data returned by services --- ## 🎯 MCP Implementation in AionUi ### Core Features | Feature | Description | Benefits | |---------|-------------|----------| | **Unified Management Interface** | Centralized management of all MCP services in settings | Simple operation, clear overview | | **Multiple Addition Methods** | Support for JSON configuration and one-click import | Flexible adaptation to different needs | | **Automatic Connection Testing** | Automatic validation of service availability after addition | Ensures correct configuration | | **Batch Operations** | One-click enable/disable multiple services | Improves management efficiency | | **Status Monitoring** | Real-time display of connection status and tool lists | Facilitates troubleshooting | ### Supported Transport Methods AionUi currently supports the following MCP transport methods: 1. **stdio**: Standard input/output (most common) 2. **sse**: Server-sent events 3. **http**: HTTP requests 4. **streamable-http**: Streamable HTTP --- ## 🚀 Quick Start ### Prerequisites Before starting MCP configuration, ensure: - ✅ AionUi is properly installed and running - ✅ At least one AI model is configured (Gemini, OpenAI, etc.) - ✅ Basic understanding of JSON configuration format (optional) ### Accessing MCP Management Interface 1. **Open AionUi** 2. **Enter Settings Page** - Click the "Settings" icon in the left sidebar 3. **Select Tools Settings** - Choose "Tools Settings" in the settings page 4. **Find MCP Management** - Locate the "MCP Management" section in tools settings ![MCP Settings Entry Interface](assets/Images/mcp%20setting%20entrance.png) --- ## 📋 Configuration Methods ### Method 1: Add via JSON Configuration This is the most flexible configuration method, suitable for experienced users: #### Step 1: Prepare JSON Configuration The JSON configuration format for MCP services is as follows: ```json { "mcpServers": { "service-name": { "description": "Service description", "command": "command", "args": ["arg1", "arg2"], "env": { "ENV_VAR_NAME": "env_var_value" } } } } ``` #### Step 2: Add Service 1. **Click Add Button** - Click "Add MCP Service" button in MCP management interface - Select "Add via JSON" 2. **Input Configuration** - Paste JSON configuration in the popup dialog - Click "Confirm" button 3. **Automatic Testing** - AionUi will automatically test the connection - Successfully connected services will show green checkmark ![JSON Configuration Interface](assets/Images/mcp%20import%20from%20JSON.png) ### Method 2: One-Click Import from CLI If you have already configured MCP in CLI tools, you can use the one-click import feature: #### Step 1: Select CLI Tool 1. **Click Add Button** - Click "Add MCP Service" button in MCP management interface - Select "Import from CLI" 2. **Choose CLI** - Select the CLI tool with configured MCP from the dropdown - Supported CLIs: Gemini CLI, Claude Code, Qwen Code, etc. #### Step 2: Import Configuration 1. **Click Import Button** - After selecting CLI, click "Import from CLI" button - AionUi will automatically read the CLI's MCP configuration 2. **Confirm Import** - Review the imported service list - Click "Save" to complete the import ![CLI One-Click Import Interface](assets/Images/MCP%20import%20form%20CLI.png) --- ## ⚙️ Service Management ### View Service Status In the MCP management interface, each service displays: - **Service Name**: MCP service identifier - **Connection Status**: - ✅ **Connected**: Service running normally - ❌ **Connection Failed**: Service unavailable - 🔄 **Testing**: Testing connection - ⚪ **Disconnected**: Service not started - **Tool List**: Click to expand and view available tools ### Management Operations #### Enable/Disable Service 1. **Toggle Switch** - Click the switch button on the right side of the service - After enabling, it will automatically sync to all CLI tools 2. **View Sync Status** - After successful enabling, CLI icons will appear next to the service name - Indicates the service has been synced to corresponding CLI tools #### Test Connection 1. **Manual Test** - Click the refresh button on the right side of the service - Re-test the service connection status 2. **View Results** - Status icon will be updated after testing - Error information will be displayed if failed #### Edit Service 1. **Enter Edit Mode** - Click the edit button on the right side of the service - Modify service configuration 2. **Save Changes** - Click save after modifications - System will automatically re-test the connection #### Delete Service 1. **Confirm Deletion** - Click the delete button on the right side of the service - Click "Confirm" in the confirmation dialog 2. **Clean Sync** - After deletion, it will automatically remove from all CLI tools - Ensures configuration consistency --- ## 🛠️ Usage Examples ### Example 1: File Management Tools After configuring filesystem MCP service, you can: ``` User: Help me organize the files on my desktop AI: I'll help you organize your desktop files. Let me first check what files are on your desktop... [Calling filesystem MCP] - Scan desktop directory - Categorize by file type - Create organized folder structure - Move files to corresponding folders Organization complete! I've categorized and organized your desktop files by type. ``` ### Example 2: Browser Automation After configuring Chrome DevTools MCP, you can: ``` User: Help me open GitHub and search for AionUi project AI: I'll help you open GitHub and search for the AionUi project. [Calling chrome-devtools MCP] - Open Chrome browser - Navigate to GitHub.com - Enter "AionUi" in search box - Execute search operation Search complete! I've opened GitHub and searched for the AionUi project for you. ``` ### Example 3: Git Operations After configuring Git MCP service, you can: ``` User: Help me check the commit history of the current project AI: I'll help you check the project's commit history. [Calling git MCP] - Connect to Git repository - Get commit history records - Format and output commit information Commit History: commit abc123 - Fix login functionality (2024-01-15) commit def456 - Add user management module (2024-01-14) commit ghi789 - Initialize project (2024-01-13) ``` ### Example 4: Memory Management After configuring Memory MCP service, you can: ``` User: Help me remember this important information: project deadline is next Friday AI: I'll help you remember this important information. [Calling memory MCP] - Store important information in memory - Set reminder tags - Confirm save success Information saved! I've remembered "project deadline is next Friday" as important information. ``` --- ## 🔧 Troubleshooting ### Common Issues and Solutions #### 1. Service Connection Failed **Problem**: MCP service shows red X, cannot connect **Possible Causes**: - Incorrect command path - Dependencies not installed - Network connection issues - Insufficient permissions **Solutions**: 1. **Check Command**: Ensure `command` and `args` configuration is correct 2. **Install Dependencies**: Run `npm install -g package-name` to install required packages 3. **Check Network**: Ensure network connection is normal 4. **Permission Check**: Ensure sufficient system permissions #### 2. Empty Tool List **Problem**: Service connects successfully, but tool list is empty **Possible Causes**: - MCP service doesn't properly implement tool interface - Service version incompatibility - Missing configuration parameters **Solutions**: 1. **Check Service**: Ensure MCP service implementation is correct 2. **Update Version**: Use the latest version of the service 3. **Complete Configuration**: Add necessary environment variables #### 3. CLI Sync Failed **Problem**: Service works normally in AionUi, but CLI tools cannot use it **Possible Causes**: - CLI tool version is too old - Configuration format incompatibility - CLI tool not properly installed **Solutions**: 1. **Update CLI**: Upgrade to the latest version 2. **Re-sync**: Disable and re-enable the service 3. **Check Installation**: Ensure CLI tool is properly installed --- ## 🔗 Related Resources ### Official Documentation - **[MCP Official Specification](https://modelcontextprotocol.io/)** - Official MCP protocol documentation - **[AionUi GitHub](https://github.com/iOfficeAI/AionUi)** - AionUi project homepage - **[MCP Server List](https://github.com/modelcontextprotocol/servers)** - Official MCP servers ### Community Resources - **[GitHub Discussions](https://github.com/iOfficeAI/AionUi/discussions)** - Community discussions and feedback - **[Issue Reports](https://github.com/iOfficeAI/AionUi/issues)** - Report bugs and feature requests - **[Release Notes](https://github.com/iOfficeAI/AionUi/releases)** - View latest versions and updates ### Learning Resources - **[Quick Start Guide](Getting-Started)** - AionUi basic configuration - **[LLM Configuration](LLM-Configuration)** - AI model configuration tutorial - **[Multi-Agent Mode Setup](ACP-Setup)** - CLI tool integration tutorial - **[FAQ](FAQ)** - Q&A and troubleshooting --- **Start your MCP journey and make your AI assistant more powerful!** 🚀 --- # Source: https://github.com/iOfficeAI/AionUi/wiki/Use-Cases-Overview # 🎯 Application Use Cases **[English](Use-Cases-Overview)** | [简体中文](Use-Cases-Overview-Chinese) | Case | Description | Use Cases | |------|-------------|-----------| | [File Management](file-management) | Smart file organization, batch processing, duplicate cleanup | Daily file management | | [Excel Smart Processing (Coming Soon)](excel-processing) | Auto data fill, smart queries, chart creation | Data processing analysis | | [Smart Information Gathering (Coming Soon)](smart-information-gathering) | Information search recording, data extraction, multi-source integration | Information collection | | [Local Knowledge Base Application (Coming Soon)](local-knowledge-base-application) | Style learning, document extraction, knowledge Q&A | Knowledge management | | [AI Learning Assistant (Coming Soon)](ai-learning-assistant) | Technical problem solving, concept explanation, learning guidance | Learning assistance | | [Writing & Content Creation (Coming Soon)](writing-content-creation) | Email drafting, report outlines, content polishing | Content creation | --- ## 🤝 Join the Community Found a cool new way to use AionUi? Share it with everyone! We'd love to have you contribute to this growing collection of AI use cases. - **💬 [GitHub Discussions](https://github.com/iOfficeAI/AionUi/discussions)** - Share your use cases and learn from others - **🐛 [Report Issues](https://github.com/iOfficeAI/AionUi/issues)** - Found a bug or have a feature request? - **📦 [GitHub Releases](https://github.com/iOfficeAI/AionUi/releases)** - Stay updated with the latest features --- ## 🔗 Quick Links - **[Configuration Guides](Configuration-Guides)** - Set up AionUi for optimal performance - **[Getting Started](Getting-Started)** - Learn the basics of using AionUi - **[FAQ](FAQ)** - Common questions and troubleshooting --- # Source: https://github.com/iOfficeAI/AionUi/wiki/WebUI-Configuration-Guide # 🌐 AionUi WebUI Configuration Guide This guide covers how to configure and use AionUi in WebUI mode, enabling browser-based access and remote connections to your local AI assistant. **[English](WebUI-Configuration-Guide)** | [简体中文](WebUI-Configuration-Guide-Chinese) ## 🎯 WebUI Mode Overview WebUI mode allows you to access AionUi through a browser, supporting any browser, remote access, secure login, and server deployment. **Configuration Process (4 Steps):** 1. **Start WebUI** → Select platform, run startup command 2. **First Login** → Open `http://localhost:25808` in browser, create account 3. **Remote Access** (optional) → Use `--remote` for same network, Tailscale for cross-network 4. **Server Deployment** (optional) → macOS uses LaunchAgent, Linux uses systemd **Usage Scenarios:** - 🏠 **Local Use Only**: Step 1 → Step 2 - 📱 **LAN Access**: Step 1 → Step 2 → Step 3 (same network) - 🌐 **Cross-Network Access**: Step 1 → Step 2 → Step 3 (Tailscale) - 🖥️ **Server Deployment**: Step 1 → Step 2 → Step 4 --- ## 📋 Quick Command Reference Before starting, here are the common commands for starting WebUI on each platform: | Platform | Local Access | Network Access (LAN) | |:---:|:---:|:---:| | **Windows** | `AionUi.exe --webui` | `AionUi.exe --webui --remote` | | **macOS** | `/Applications/AionUi.app/Contents/MacOS/AionUi --webui` | `/Applications/AionUi.app/Contents/MacOS/AionUi --webui --remote` | | **Linux** | `AionUi --webui` | `AionUi --webui --remote` | | **Android** | `AionUi --no-sandbox --webui` | `AionUi --no-sandbox --webui --remote` | > **Tip**: If the command is not found, use the full path (see detailed instructions below for each platform). Linux root users and Android need to add the `--no-sandbox` parameter. --- ## 📑 Quick Navigation | [📋 Command Reference](#commands) | [🚀 Quick Start](#quick-start) | [🔐 Authentication](#auth) | [🔐 Tailscale](#tailscale) | [🌍 Remote Access](#remote) | |:---:|:---:|:---:|:---:|:---:| | [🖥️ Server Deployment](#server) | [🔑 Password Management](#password) | [🛠️ Troubleshooting](#troubleshooting) | [📝 CLI Options](#cli) | [💡 Best Practices](#best-practices) | --- ## 🚀 Quick Start ### Step 1: Start WebUI Mode --- ### 🪟 Windows **Open Command Prompt or PowerShell, and run:** Method 1: Using full path ```cmd "C:\Program Files\AionUi\AionUi.exe" --webui ``` Method 2: If AionUi is in your PATH ```cmd AionUi.exe --webui ``` --- ### 🍎 macOS **Open Terminal, and run:** ```bash /Applications/AionUi.app/Contents/MacOS/AionUi --webui ``` --- ### 🐧 Linux **Open Terminal, and select the command based on your user type:** Desktop Environment (Non-root User): Local Access: ```bash AionUi --webui ``` Network Access (LAN): ```bash AionUi --webui --remote ``` Alternative Methods: Using system path: ```bash AionUi --webui ``` Or using full path: ```bash /usr/bin/AionUi --webui ``` For AppImage: ```bash ./AionUi-*.AppImage --webui ``` --- **Root User:** If using root user, you need to add `--no-sandbox` flag. Local Access: ```bash sudo AionUi --webui --no-sandbox ``` Network Access (LAN): ```bash sudo AionUi --webui --remote --no-sandbox ``` ---
📱 Android (Termux) > **Community Contribution**: Special thanks to [@Manamama](https://github.com/Manamama) for creating this guide! > **Original Tutorial**: [Running AionUi WebUI on Android via Termux + Proot Ubuntu](https://gist.github.com/Manamama/b4f903c279b5e73bdad4c2c0a58d5ddd) > **Related Issues**: [#217 - Android Support Discussion](https://github.com/iOfficeAI/AionUi/issues/217) > ⚠️ **Important**: > - Electron desktop mode is **NOT supported** on Android, only WebUI mode works > - Install Termux from [F-Droid](https://f-droid.org/en/packages/com.termux/) (Google Play version is outdated) > - Requirements: ~5 GB free storage, Internet connection, Android 7.0+ **Step 1: Install Termux and Proot** Open Termux and execute: ```bash pkg update -y pkg install proot-distro -y proot-distro install ubuntu proot-distro login ubuntu ``` **Step 2: Install System Dependencies** ```bash apt update apt install -y wget libgtk-3-0 libnss3 libasound2 libgbm1 libxshmfence1 ca-certificates ``` **Step 3: Download and Install AionUi** ```bash wget https://github.com/iOfficeAI/AionUi/releases/download/v1.5.2/AionUi_1.5.2_arm64.deb apt install -y ./AionUi_*.deb which AionUi ``` **Step 4: Launch AionUi** - **Local Access**: `AionUi --no-sandbox --webui` - **Network Access**: `AionUi --no-sandbox --webui --remote` > 💡 **Quick Start** (from Termux main shell): > ```bash > proot-distro login ubuntu -- bash -c "AionUi --no-sandbox --webui --remote" > ``` **Step 5: Access WebUI** Open `http://localhost:25808` in your browser
📋 Additional Information **Expected Warnings (Safe to Ignore):** ``` [WARNING] Could not connect to session bus... [ERROR] Failed to connect to the bus... [WARNING] Multiple instances of the app detected... ``` These errors are related to D-Bus and X server, which are not needed for WebUI mode. **Performance Tips:** - Use lightweight browsers (Chrome or Firefox Focus) - Close background apps to free RAM - Use WiFi instead of mobile data - Keep device charged **Troubleshooting:** - **Port in use**: Add `--port 8080` flag - **Permission denied**: Run `chmod +x /opt/AionUi/aionui` - **Out of memory**: Close other apps - **Cannot access**: Check if AionUi is running, clear browser cache **Need Help?** Check the [full detailed tutorial](https://gist.github.com/Manamama/b4f903c279b5e73bdad4c2c0a58d5ddd) or report issues at [GitHub Issue #217](https://github.com/iOfficeAI/AionUi/issues/217)
--- ### Step 2: Access the Web Interface After starting with the `--webui` flag, you'll see output like: ``` 🚀 WebUI started / WebUI 已启动: http://localhost:25808 ``` Simply open this URL in your browser. The application will automatically open your default browser when started. --- ### Step 3: First Login On first launch, you'll see your initial credentials: First login credentials display ``` ======================================== ✅ Default admin user created! ======================================== Username: admin Password: [random-password] 🌐 Access URL: http://localhost:25808 ======================================== ``` **Important**: Copy the password immediately - you'll need it to log in! --- ## 🔐 Authentication Setup ### Default Credentials When AionUi starts in WebUI mode for the first time, a default admin user is automatically created: - **Username**: `admin` - **Password**: Randomly generated 12-character password (displayed in console) ### Security Features - **Rate Limiting**: Login attempts are rate-limited (5 attempts per 15 minutes) - **Password Hashing**: Passwords are hashed using bcrypt - **Session Tokens**: JWT tokens for secure session management - **Cookie Protection**: HttpOnly and SameSite cookies for CSRF protection ### Adding Multiple Users You can add more users through the WebUI: 1. Log in as admin 2. Navigate to User Settings 3. Add new users with custom credentials --- ## 🔐 Using Tailscale for Cross-Network Access (Recommended) > **Use Case**: Access from different networks (e.g., office computer accessing home server, or mobile data access) Using Tailscale allows cross-network access without router configuration or public IP: 1. Install Tailscale on both server and client devices 2. Log in with the same Tailscale account 3. Access using Tailscale's virtual IP (typically `100.x.x.x:25808`) --- ## 🌍 Remote Access Configuration > **Use Case**: Access from devices on the same WiFi/LAN (e.g., phone and computer on the same WiFi) ### Step 1: Enable Remote Access Add the `--remote` flag to your startup command: - **Windows**: `AionUi.exe --webui --remote` - **macOS**: `/Applications/AionUi.app/Contents/MacOS/AionUi --webui --remote` - **Linux**: `AionUi --webui --remote` (root users need to add `--no-sandbox`) - **Android**: `AionUi --no-sandbox --webui --remote` ### Step 2: Get Access Address After starting, AionUi will display the network access address: ``` 🚀 Network access / 网络访问: http://192.168.1.100:25808 ``` > 💡 **Tip**: If not displayed, Windows users run `ipconfig`, macOS/Linux users run `ifconfig` to check IP address. ### Step 3: Access from Other Devices Open the displayed address in a browser on other devices (phone, tablet, etc.) and log in with your credentials. ⚠️ **Note**: Only use remote mode on trusted networks. --- ## 🖥️ Server Deployment > **Use Case**: Run 24/7 on servers with remote access and auto-restart support ### 🍎 macOS - LaunchAgent Background Running **Step 1: Create Configuration File** Create `~/Library/LaunchAgents/com.aionui.webui.plist`: ```xml Label com.aionui.webui ProgramArguments /Applications/AionUi.app/Contents/MacOS/AionUi --webui --remote RunAtLoad KeepAlive ``` **Step 2: Start Service** ```bash launchctl load ~/Library/LaunchAgents/com.aionui.webui.plist launchctl start com.aionui.webui ``` ### 🐧 Linux - systemd (Recommended) **Step 1: Create Service File** ```bash sudo nano /etc/systemd/system/aionui-webui.service ``` **Step 2: Add Configuration** ```ini [Unit] Description=AionUi WebUI Service After=network.target [Service] Type=simple User=YOUR_USERNAME WorkingDirectory=/home/YOUR_USERNAME ExecStart=/usr/bin/AionUi --webui --remote Restart=on-failure RestartSec=10 [Install] WantedBy=multi-user.target ``` > 💡 **Tip**: Replace `YOUR_USERNAME` and `/usr/bin/AionUi` with actual values. **Step 3: Enable and Start** ```bash sudo systemctl daemon-reload sudo systemctl enable aionui-webui.service sudo systemctl start aionui-webui.service sudo systemctl status aionui-webui.service ``` **Common Management Commands:** - View logs: `sudo journalctl -u aionui-webui.service -f` - Restart service: `sudo systemctl restart aionui-webui.service` - Stop service: `sudo systemctl stop aionui-webui.service` **Step 4: Get Access Address** Check the access address in logs, or run: ```bash sudo journalctl -u aionui-webui.service | grep "WebUI" ``` > 💡 **Custom Port**: Add `Environment="AIONUI_PORT=8080"` in `[Service]`, then restart the service. --- ## 🔑 Password Management ### Reset Admin Password > 💡 **Tip**: Currently, WebUI does not support custom password changes in the interface. To change your password, use the `--resetpass` command to reset it to a new random password. If you forget your admin password or need to change it, run the `--resetpass` command in terminal: #### Windows Open **Command Prompt** or **PowerShell**, and run: **Reset admin password:** ```cmd "C:\Program Files\AionUi\AionUi.exe" --resetpass ``` **Or for a specific user:** ```cmd "C:\Program Files\AionUi\AionUi.exe" --resetpass username ``` #### macOS Open **Terminal**, and run: **Reset admin password:** ```bash /Applications/AionUi.app/Contents/MacOS/AionUi --resetpass ``` **Or for a specific user:** ```bash /Applications/AionUi.app/Contents/MacOS/AionUi --resetpass username ``` #### Linux Open **Terminal**, and run: **Reset admin password:** ```bash AionUi --resetpass ``` **Or for a specific user:** ```bash AionUi --resetpass username ``` **What happens when you run `--resetpass`:** 1. Connects to the database 2. Finds the specified user (default: `admin`) 3. Generates a new random 12-character password 4. Updates the password hash in the database 5. Rotates the JWT secret (invalidating all previous tokens) 6. Displays the new password in the terminal **After running `--resetpass`:** 1. Copy the new password from the terminal 2. Refresh your browser (Cmd+R or Ctrl+R) 3. You'll be redirected to the login page 4. Log in with the new password shown in the terminal --- ## 🛠️ Troubleshooting ### Port Already in Use If port 25808 is already in use, AionUi will automatically try the next available port. Check the console output for the actual port number. ### Cannot Access from Browser 1. **Check if the application started successfully** - Look for "Server started on port XXXX" message in the console 2. **Try a different browser** - Chrome, Firefox, Safari, or Edge 3. **Clear browser cache** - Press `Ctrl+Shift+Delete` (Windows/Linux) or `Cmd+Shift+Delete` (macOS) ### Firewall Blocking Access **Windows:** ```cmd # Allow through Windows Firewall netsh advfirewall firewall add rule name="AionUi WebUI" dir=in action=allow protocol=TCP localport=3000 ``` **Linux (UFW):** ```bash sudo ufw allow 3000/tcp ``` **macOS:** - Go to **System Preferences** → **Security & Privacy** → **Firewall** → **Firewall Options** → Add AionUi ### Application Not Found **Find application location:** **Windows:** ```cmd where AionUi.exe ``` **macOS:** ```bash mdfind -name "AionUi.app" ``` **Linux:** ```bash which AionUi # or find /usr/bin -name "AionUi" 2>/dev/null ``` ### View Logs **Windows (PowerShell):** ```powershell & "C:\Program Files\AionUi\AionUi.exe" --webui 2>&1 | Tee-Object -FilePath aionui.log ``` **macOS/Linux:** ```bash AionUi --webui 2>&1 | tee aionui.log ``` --- ## 📝 Command Line Options Summary | Option | Description | | ------------------ | ------------------------------------- | | `--webui` | Start in WebUI mode | | `--remote` | Allow remote network access | | `--webui --remote` | Combine both flags | | `--resetpass` | Reset admin password (usage above) | --- ## 💡 Best Practices ### For Development - Use `--webui` flag for quick testing - Enable remote access only on local network - Keep default admin password secure ### For Production - Use systemd/LaunchAgent for automatic startup - Set up firewall rules to restrict access - Use VPN for external access - Regularly update your password - Keep AionUi updated to the latest version ### For Local Network Access - Ensure all devices are on the same network - Check your router settings if access doesn't work - Use your computer's IP address for access --- ## 🔗 Related Resources - [📖 Getting Started Guide](Getting-Started) - Initial setup and configuration - [⚙️ LLM Configuration](LLM-Configuration) - Configure AI models - [🤖 Multi-Agent Setup](ACP-Setup) - Integrate terminal AI agents - [🔌 MCP Configuration](MCP-Configuration-Guide) - Model Context Protocol setup - [❓ FAQ](FAQ) - Common issues and solutions --- ## 🌟 Features ### Security - **HTTPS Ready**: Can be deployed behind a reverse proxy with SSL - **Session Management**: Automatic session timeout after 24 hours - **Rate Limiting**: Protection against brute force attacks - **CSRF Protection**: Built-in cross-site request forgery protection ### Data Storage - **Local SQLite Database**: All data stored locally - **No Cloud Storage**: Your conversations never leave your computer - **Privacy First**: Full control over your data ### Performance - **Low Resource Usage**: Runs efficiently on most systems - **WebSocket Real-time**: Real-time updates via WebSocket - **Efficient Streaming**: Optimized response streaming --- **Happy using AionUi in WebUI mode!** 🚀