Getting Started

Installation

Download the latest installer from the Download page or the GitHub Releases.

macOS

Chip	File
Apple Silicon (M1 / M2 / M3 / M4)	`AQBot_x.x.x_aarch64.dmg`
Intel	`AQBot_x.x.x_x64.dmg`

Open the .dmg and drag AQBot into the Applications folder.
Launch AQBot. If macOS blocks the app, go to System Settings → Privacy & Security and click Open Anyway.

macOS: "App Is Damaged" or "Cannot Verify Developer"

AQBot is signed with the project's own code-signing certificate, not an Apple Developer ID certificate, so after downloading it from a browser macOS may still say "AQBot is damaged and can't be opened" or "AQBot can't be opened because the developer cannot be verified".

There is no need to disable Gatekeeper system-wide — allow only AQBot:

In Finder, Control-click AQBot.app, choose Open, then click Open again.
If it is still blocked, go to System Settings → Privacy & Security, find AQBot in the Security section and click Open Anyway.
Launch AQBot again.

Gatekeeper approval and Accessibility permission are separate settings. To use the text-selection toolbar, also enable AQBot under System Settings → Privacy & Security → Accessibility when prompted in the app.

Windows

Architecture	File
x64 (most PCs)	`AQBot_x.x.x_x64-setup.exe`
ARM64	`AQBot_x.x.x_arm64-setup.exe`

Run the installer and follow the wizard. Launch AQBot from the Start Menu or the desktop shortcut.

Linux

Format	Architecture	File
Debian / Ubuntu	x64	`AQBot_x.x.x_amd64.deb`
Debian / Ubuntu	ARM64	`AQBot_x.x.x_arm64.deb`
Fedora / openSUSE	x64	`AQBot_x.x.x_x86_64.rpm`
Fedora / openSUSE	ARM64	`AQBot_x.x.x_aarch64.rpm`
Any distro	x64	`AQBot_x.x.x_amd64.AppImage`
Any distro	ARM64	`AQBot_x.x.x_aarch64.AppImage`

bash

# Debian / Ubuntu
sudo dpkg -i AQBot_x.x.x_amd64.deb
# Fedora / openSUSE
sudo rpm -i AQBot_x.x.x_x86_64.rpm
# AppImage (any distro)
chmod +x AQBot_x.x.x_amd64.AppImage
./AQBot_x.x.x_amd64.AppImage

First-Time Setup

1. Open Settings

Launch AQBot and click the gear icon at the bottom of the sidebar, or press Cmd/Ctrl+,.

2. Add a Provider

Navigate to Settings → Providers and click the + button.

Enter a display name (e.g. OpenAI).
Select the provider type (OpenAI, Anthropic, Google Gemini, etc.).
Paste your API key.
Confirm the Base URL — the official endpoint is pre-filled for built-in types. Change it only if you use a third-party relay or proxy.

3. Fetch Models

Click Fetch Models to pull the list of available models from the provider's API. You can also add model IDs manually if needed.

4. Set a Default Model

Go to Settings → Default Model and choose the provider and model that new conversations should use by default.

Your First Conversation

Click New Chat in the sidebar (or press Cmd/Ctrl+N).
Select a model from the model selector at the top of the chat.
Type a message and press Enter.
AQBot streams the response in real time. Models that support thinking blocks (e.g. Claude, DeepSeek R1) display the reasoning process in a collapsible section above the answer.

Key Concepts

Conversation Branching

Edit or regenerate any message to create a branch. The original and new versions coexist in the same conversation tree — navigate between them with the arrow controls on each message.

Message Versions

Every regeneration creates a new version. Switch between versions using the ◀ ▶ arrows on the message bubble.

Context Attachments

Enrich your prompts by attaching files, search results, or MCP tool outputs directly to the conversation context.

Terminal and shell commands are not Chat MCP tools. Switch the conversation to Agent mode to run non-interactive commands after approval. The selected working directory is the process starting CWD, not a filesystem sandbox.

Shortcuts

Below are the default keyboard shortcuts. All shortcuts can be customized in Settings → Shortcuts.

Shortcut	Action
`Cmd/Ctrl`+`Shift`+`A`	Show / hide the current window
`Cmd/Ctrl`+`Shift`+`Alt`+`A`	Show / hide all windows
`Cmd/Ctrl`+`Shift`+`W`	Close window
`Cmd/Ctrl`+`N`	New conversation
`Cmd/Ctrl`+`,`	Open Settings
`Cmd/Ctrl`+`K`	Command palette
`Cmd/Ctrl`+`Shift`+`M`	Toggle model selector
`Cmd/Ctrl`+`Shift`+`↑`	Fill last message
`Cmd/Ctrl`+`Shift`+`K`	Clear context
`Cmd/Ctrl`+`Shift`+`Backspace`	Clear conversation messages
`Cmd/Ctrl`+`Shift`+`G`	Toggle API Gateway

Desktop Settings

Open Settings to configure the desktop experience.

Setting	Options
Theme	Dark, Light, or System (auto)
Language	简体中文, 繁體中文, English, 日本語, 한국어, Français, Deutsch, Español, Русский, हिन्दी, العربية
System tray	Minimize to tray, close to tray
Auto-start	Launch AQBot when your computer starts
Always on top	Keep the window above other applications
Proxy	HTTP or SOCKS5 proxy with host and port

Data & Backup

Data Directories

AQBot stores data in two locations:

Path	Contents
`~/.aqbot/`	Application state — database, encryption keys, vector DB, SSL certificates
`~/Documents/aqbot/`	User-visible files — images, documents, backups

Auto Backup

Go to Settings → Backup to configure automatic backups:

Enabled — toggle automatic backups on or off.
Interval — how often to back up (in hours).
Max count — number of backups to keep before the oldest is deleted.
Storage target — local directory (default: ~/Documents/aqbot/backups/) or WebDAV server.

Manual Backup & Restore

Create a manual backup at any time from the Backup settings panel. To restore, select a backup from the history list and click Restore.