AQBot: a local-first desktop workbench for chat, ACP agents and an OpenAI-compatible gateway

What AQBot is for, and who ends up using it

The problem AQBot addresses is fragmentation. A working AI setup usually means one window for OpenAI, another for Claude, a CLI agent in a terminal, a scratch directory of documents, and a handful of API keys scattered across config files. AQBot puts those in one desktop process. The README describes it as a "本地优先的桌面 AI 工作台" that unifies multi-provider chat, ACP agents, a knowledge base, MCP tools and an API gateway, with application data and user files kept under local control.

The intended user is a developer or power user who already holds several provider keys and wants them in one place. Multi-provider chat covers OpenAI, Claude, Gemini, DeepSeek, Qwen and any OpenAI-compatible endpoint, with custom Base URL, API path, request headers and proxy rules. The gateway side is aimed at someone who wants Claude Code, Codex CLI, OpenCode or Gemini CLI to hit a locally managed endpoint instead of a remote one. Neither group is served well by a browser tab, which is the gap this fills.

Two agent runtimes, one app: provider APIs versus ACP processes

The architecture splits agents into two paths, and the distinction matters more than any feature list. The first is the chat agent. You switch a normal conversation into Agent mode, and the model uses the provider API you already configured to read and edit files, run commands and analyze code in a chosen working directory. The README is explicit that this directory "只是进程的起始 CWD，不是文件系统沙箱": it is the starting working directory of the process, not a filesystem sandbox. Permission modes cover asking every time, auto-accepting edits, and full access, with tool calls and approvals shown live and per-task token and cost recorded.

The second path is the ACP Agent workspace. AQBot implements the Agent Client Protocol and runs compatible coding agents as external processes, streaming replies, thinking blocks and tool calls into a separate workspace. Agents can be added from an ACP Registry (the README lists Codex, Claude Agent, Gemini CLI, Cline, OpenCode and Grok Build) or configured manually with a custom command, arguments, environment variables and icon. Threads are organized per project, pinned sessions restore the last state, and a session can also start without a project in an isolated working directory.

That split is the real design decision. Chat agents inherit your provider billing and your model list; ACP agents inherit whatever the external process does, including its own authentication. AQBot is the client in both cases, not the runtime.

Installing AQBot and pointing a CLI client at the gateway

There is no npm or Homebrew install path. The README's quick start says to go to the Releases page and download the installer for your platform. Builds exist for macOS on Apple Silicon and Intel, Windows 10/11 on x86_64 and arm64, and Linux on x86_64 and arm64 as AppImage, deb or rpm.

On macOS the app is signed with a project self-signed certificate rather than an Apple Developer ID, so Gatekeeper may report it as damaged or from an unverified developer. The README's fix is scoped to AQBot rather than disabling Gatekeeper system-wide: Control-click AQBot.app in Finder and choose Open, then Open again. If it is still blocked, go to System Settings, Privacy & Security, find AQBot in the security section and click Open Anyway. If you use the selection toolbar, accessibility permission is a separate switch under Privacy & Security, Accessibility.

For local development, the repository is a pnpm workspace with a Tauri shell. The package manifest pins pnpm 10.32.1 and exposes these scripts:

pnpm install
pnpm dev        # tauri dev via scripts/tauri-cli.mjs
pnpm test:run   # vitest run
pnpm build      # tsc && vite build

Once the app is running, the gateway is the part worth configuring first. It exposes OpenAI Chat Completions, OpenAI Responses, Claude native and Gemini native endpoints from the desktop process, with locally managed gateway keys, SSL/TLS certificates, request logs and usage statistics, plus configuration templates for Claude Code, Codex CLI, OpenCode, Gemini CLI and custom clients. The README does not print the default listening port or the exact template contents, so take the host, port and key from the gateway page in the app rather than guessing them.

Data layout is worth knowing before you start. Application state lives in ~/.aqbot/ and user files in ~/Documents/aqbot/, and API keys are protected with AES-256 under a local master key.

The agent permission model is not a sandbox

The most consequential limitation is stated plainly in the README and is easy to skim past. The chat agent's working directory is the process's starting CWD, not a filesystem sandbox. Auto-accept-edit and full-access modes exist for convenience, and they are exactly what they sound like. If you point an agent at your home directory and grant full access, the permission prompts you would otherwise see are gone. There is no claim in the README that file writes are confined to the chosen directory, so treat the working directory as a starting point rather than a boundary.

A second constraint is platform reach. macOS, Windows and Linux are covered, but there is no documented server or headless mode. The gateway runs inside the desktop application, so the machine hosting the gateway is the machine running the GUI. Anyone wanting an always-on gateway on a headless box has to keep a desktop session alive, which the README does not address.

A third is version velocity. The most recent release listed is v0.0.158 on 2026-09-08, following v0.0.157 on 2026-09-06 and v0.0.156 on 2026-09-05, and the project version is still 0.0.x. Frequent small releases on a 0.0 line mean interfaces and storage formats can move; the README does not document a downgrade path or a migration guarantee between versions.

How AQBot differs from a chat client like Cherry Studio

Cherry Studio is the closest comparison, and AQBot's own README makes the relationship concrete: it imports Cherry Studio backups, and the import can optionally migrate associated providers, API keys and file attachments. So the two overlap heavily on multi-provider chat, roles and local storage.

The difference is scope. Cherry Studio is a chat client. AQBot adds an API gateway that exposes OpenAI Chat Completions, OpenAI Responses, Claude native and Gemini native interfaces from the desktop app, with gateway keys, TLS certificates, request logs and usage statistics, plus ready templates for Claude Code, Codex CLI, OpenCode and Gemini CLI. It also adds the ACP Agent workspace, which runs external ACP-compatible coding agents as processes. If your need is a clean chat interface with provider management, the extra surface here is weight you will not use. If you want your existing CLI agents and a local endpoint in the same app as your chat history, that is the reason to pick this one.

AQBot also imports ChatGPT official exports and Kelivo backups, with preview statistics, warnings and duplicate handling, which suggests the project expects to be adopted alongside existing tools rather than replacing them outright.

Licence, upgrade cost and what the repository tells you about maintenance

AQBot is licensed AGPL-3.0, and package.json records the SPDX identifier as AGPL-3.0-only. That is a strong copyleft licence with a network clause. Running the desktop app for yourself is unremarkable. The gateway is where the question becomes real: if you expose a modified AQBot over a network, the AGPL's source-availability obligation is the thing to read, and this is a question for your own legal review rather than something to settle from a README.

Upgrade cost is mostly the 0.0.x cadence. Three releases landed in the four days before 2026-09-08, and the repository ships a bump script (pnpm bump) plus a cliff.toml changelog configuration, so releases are generated rather than hand-assembled. The app includes an auto-update check through the Tauri updater plugin, which means updates arrive without you tracking the Releases page. The README does not describe how to roll back to an earlier version if an update breaks a workflow, so keep your own copy of the installer you installed from.

On maintenance, the last push was on 2026-09-08, and the repository is not archived. The README documents backups through a local directory, WebDAV or S3-compatible storage, which is the mechanism to use before any version jump.

Editorial conclusion

Adopt AQBot if you want one desktop process holding your provider keys, an ACP agent workspace and a local gateway that Claude Code, Codex CLI, OpenCode or Gemini CLI can point at, and you accept AGPL-3.0 terms. Skip it if you need a filesystem sandbox around agent tool calls, or a server-side deployment with no desktop in the loop. Before installing, read the Releases page for your architecture, and check the macOS code-signing note, since the app is signed with a project certificate rather than an Apple Developer ID.

Frequently asked questions

Official sources

1. AQBot-Desktop/AQBot on GitHub
2. License: AGPL-3.0
3. Project website
4. README
5. Releases