Atomic Agent 本地AI智能体

Requirements & Configuration

<details> <summary><b>Requirements</b> (Node, llama-server, browser, git) + Linux notes</summary>

• Node.js for development; release bundles ship as Node SEA binaries.
• A reachable llama-server, either managed by atomic-agent models or launched externally.
• Managed mode picks the GPU backend automatically: Metal on Apple Silicon, CUDA on Windows when nvidia-smi reports a supported driver (including the reworked driver 610+ headers) with Vulkan as the fallback, Vulkan on Linux, a single CUDA-enabled build on Linux arm64 (tuned for the NVIDIA GB10 in DGX Spark) that uses the GPU when an NVIDIA driver is present and the CPU otherwise, CPU when no GPU is usable.
• Chrome, Microsoft Edge, or another configured Chromium-family executable. Browser binaries are not bundled.
• git for git tools.
• macOS workflows may need Accessibility, Screen Recording, Automation, or Reminders permissions.

Linux notes: - Desktop tools (install via your package manager): ripgrep (file search; bundled binary used when present), xclip/xsel (X11) or wl-clipboard (Wayland) for clipboard, libnotify-bin for notifications, wmctrl for window control (X11/XWayland only), gio (glib2) or trash-cli for fs.trash. - Browser: Chromium-family sandboxing can fail under some Linux setups (containers, certain kernels). If Chrome refuses to launch, set ATOMIC_AGENT_BROWSER_NO_SANDBOX=1 so the agent starts it with --no-sandbox (containers and CI only). - GPU acceleration (managed mode): the backend always starts and falls back to CPU when no GPU driver is available. For GPU offload install a Vulkan driver. Intel/AMD: mesa-vulkan-drivers (+ vulkan-loader/libvulkan1); NVIDIA: the stock proprietary driver bundles its Vulkan ICD. Device auto-selected at start; override with atomic-agent models use-device <auto|cpu|Vulkan0>, inspect with atomic-agent models devices, or press G on the TUI LLM tab's Local pane. Multi-GPU: set localModels.managed.tensorSplit in config.json (e.g. [3, 1] for a 75%/25% layer split) to launch llama-server with --split-mode layer --tensor-split across every visible GPU; combine with use-device Vulkan0,Vulkan1 to restrict which devices join the split.

</details>

<details> <summary><b>How long a reply may run</b> (output ceilings)</summary>

Cloud models are uncapped by default: the service applies the model's own maximum, so one turn can write a whole file. To bound it (spend, or a service that requires the field) set maxOutputTokens on the provider entry:

"llm": { "providers": [{ "id": "openrouter", "kind": "openrouter", "maxOutputTokens": 64000 }] }

Reasoning models spend that same budget on thinking, so a low ceiling can be used up before any answer appears.

Local models use localModels.completionMaxTokens (llama.cpp's n_predict, default 16384). Set it to 0 in config.json for no cap; generation then stops at a stop token or when the context window fills. That knob bounds time and runaway loops, not memory: what your machine commits is decided at daemon start by the model and --ctx-size, and does not grow with the length of one reply.

</details>

<details> <summary><b>Models that need strict tool schemas</b> (<code>strictTools</code>)</summary>

Some models call tools reliably only when the provider constrains decoding to the tool's schema: OpenAI's strict mode. Set strictTools on the provider entry to send every function as strict:

"llm": { "providers": [{ "id": "mercury", "kind": "openai-compatible", "strictTools": true }] }

Off by default, and only for OpenAI-compatible kinds (openai-compatible, qwen-openai-compatible, openrouter, aimlapi, gemini). strict is a field on each tool, so extraBody cannot reach it; tools is a reserved key that is re-applied after that merge.

With the flag on, every tool schema is rewritten into the subset strict mode accepts: objects are closed, every property is listed in required (an optional one becomes nullable instead of being omitted), and value-range keywords the runtime validators enforce anyway (minItems, minLength, pattern, format, default, …) are stripped. A handful of tools take a free-form map (os.http.request's headers and body, mcp.prompt.get's arguments), and those cannot be expressed strictly; they are sent unconstrained (strict: false) rather than silently losing their arguments.

Because optionals become nullable, a strict model sends "pinned": null where it used to omit the key; on these providers a top-level null argument is dropped again before the call runs, so tools that check for presence behave as they always did.

The flag also sends parallel_tool_calls: false. Strict decoding and parallel calls do not compose (OpenAI's guidance is that a parallel call "may not match supplied schemas"), so a provider asked for strict tools is asked for one call per response. agent.maxParallelToolCalls still governs how the runtime executes a batch.

Turn it on only for a service that implements strict mode: one that does not will reject the whole request, not just the field.

</details>

<details> <summary><b>Choosing OpenRouter's upstream host</b> (<code>providerPreferences</code>)</summary>

OpenRouter serves most models from several hosts and picks one per request. To steer that (pin a host, forbid fallbacks, skip hosts that keep your data), set providerPreferences on an openrouter entry. It is sent unchanged as the request's provider routing object:

"llm": { "providers": [{ "id": "openrouter", "kind": "openrouter", "providerPreferences": { "order": ["z-ai"], "allow_fallbacks": false } }] }

It applies to every chat completion the entry makes (turns, memory sub-calls and vision.describe), and other kinds ignore it. The pre-save key check does not send it: that check asks the cheapest paid model for one token, and a host pinned for your model may not serve that one. If you already set extraBody.provider, that keeps winning.

</details>

<details> <summary><b>Configuration and secrets</b> (state dir, env vars, .env)</summary>

User-facing configuration lives in <stateDir>/config.json.

Useful environment variables: - ATOMIC_AGENT_STATE_DIR: state, config, skills, browser profile, memory, tasks, traces. Default: ~/.atomic-agent. - ATOMIC_AGENT_LLAMA_API_KEY: optional bearer token for llama-server. It does not apply to Atomic Core: Core issues and rotates its own key, and the agent reads it from Core, so there is nothing to set. With the legacy managed llama-server engine the daemon is launched with this key; when it is unset, a key is generated once and kept in <models dir>/llama-server.key (mode 0600), so a web page in a local browser cannot call the daemon. The same key is used in external mode when localModels.url points at the managed port. Anything else that calls the managed daemon directly (scripts, other apps) must send Authorization: Bearer <key> with that key. - ATOMIC_AGENT_LLAMA_MAX_TOKENS: completion cap, clamped to 64-131072. - ATOMIC_AGENT_BROWSER_CHANNEL: chrome, msedge, or chromium. - ATOMIC_AGENT_BROWSER_EXECUTABLE_PATH: explicit Chromium-family executable path. - ATOMIC_AGENT_BROWSER_CDP_URL: attach to an already-running browser via CDP. - ATOMIC_AGENT_BROWSER_HEADLESS: 1 to run the browser headless. - ATOMIC_AGENT_BROWSER_NO_SANDBOX: 1 to launch the browser with --no-sandbox (containers and CI only). - ATOMIC_AGENT_UPDATE_CHECK_ON_STARTUP: false to skip the TUI's update check.

The external llama-server URL is set in config.json (localModels.url), not through the environment.

Secrets for skills and channels belong in <stateDir>/.env, not in config.json:

NOTION_API_KEY=ntn_xxxxxxxx
GITHUB_TOKEN=ghp_xxxxxxxx
TELEGRAM_BOT_TOKEN=123456789:AA-your-bot-token
EXA_API_KEY=exa_xxxxxxxx
OBSIDIAN_VAULT_PATH=/Users/me/Documents/Obsidian Vault

Shell-exported variables win over .env. The built-in parser intentionally supports only simple KEY=VALUE lines.

Commands the agent runs (os.shell.run, os.git.*) do not inherit these secrets: every variable named like a key, token, secret or password, and every known provider key, is removed from the command's environment, so a command slipped in through a web page or a file cannot read OPENAI_API_KEY or TELEGRAM_BOT_TOKEN. The agent itself still uses them. The names in tools.shell.envPassthrough in config.json are passed to shell commands anyway; the default is ["GITHUB_TOKEN", "NOTION_API_KEY"], which the bundled github and notion skills read through the shell. Add a name there when a command of yours needs one, or set [] to keep those two out as well.

EXA_API_KEY is optional. Without it, web search uses Exa's free keyless tier, which runs out quickly, and then DuckDuckGo. When the free limit is reached, or no search provider answers, the search result says so and asks for a free key from <https://dashboard.exa.ai/api-keys>. Apps get the same request as details.keyRequired on the os.web.search result ({ provider: "exa", reason: "rate_limited" | "unreachable" | "missing", getKeyUrl, envVar }); the HTTP stream forwards it as key_required on the tool_result event.

The Integrations tab (/integrations) writes these for you. Its GitHub entry stores GITHUB_TOKEN and carries the Remote sync switch (git.remoteSync, off by default): while it is off, a repository the agent versions stays

Quick Install

macOS / Linux:

curl -fsSL https://atomicagent.io/install | sh

Windows (PowerShell):

irm https://atomicagent.io/install.ps1 | iex

The installer downloads the release archive, verifies the checksum, and installs the CLI plus support assets (grammars/, native prebuilds, and bundled ripgrep). Atomic Agent updates itself in place; after an update the TUI prompts you to restart. Outside the TUI, run atomic-agent update (or atag update) to check for a newer release and re-run the installer in place; atomic-agent update --check probes without installing, and --version <tag> pins a specific release. Only the installed binary can self-update; a dev checkout updates via git.

[!NOTE] Developer preview. APIs, commands, config, and behavior are still moving, so pin a release if you need a stable integration point. Current builds: macOS (Apple Silicon), Linux x64 / arm64, and Windows x64. Intel Macs are not supported yet; Windows on ARM runs the x64 build under emulation.

Uninstall

One command removes everything: the state directory (config, memory, sessions, tasks, traces, downloaded models), the binary and its atag alias, the asset directories beside them, and the PATH line the installer added to your shell rc file:

atomic-agent uninstall

It prints exactly what it will delete, with sizes, and then asks you to type the word uninstall. Nothing is uploaded and nothing is kept; this cannot be undone. Preview it with atomic-agent uninstall --dry-run, keep your data with --keep-data, keep the binary with --keep-binary, leave your shell rc file alone with --keep-path, or skip the prompt in a script with --yes. The same flow is the last entry in the TUI's own menu (Esc → Danger zone, or /uninstall). The desktop app (0.0.3 and later) shares the same ~/.atomic-agent folder. When uninstall finds it, an interactive run asks a separate question before deleting that folder (answer no to remove only the terminal program), and a --yes run keeps the folder and says why; add --include-desktop-data to delete it in a script.

<stateDir>/.env

TELEGRAM_BOT_TOKEN=123456789:AA-your-bot-token DISCORD_BOT_TOKEN=your-discord-bot-token

Both can be set up from the Integrations tab in the TUI. Each bot answers only its owner: in a DM, or in a group or server channel when you @mention it or reply to it. Every chat, forum topic, Discord channel and thread gets its own session, and both bots understand `/status`, `/sessions`, `/switch <id>`, `/new`, `/model [provider] [model-id]` and `/cancel`. Approvals arrive as buttons in the chat the turn came from; only an owner can press them. Messages and files pass through Telegram's or Discord's servers.

Channels belong to the runtime, not to the TUI: `atomic-agent serve` boots them the same way, so the bots keep answering with no terminal UI open. Each bot is guarded by its own lockfile in the state dir; a second process that tries to start the same bot leaves it down with `already running in another atomic-agent (pid N)` and does not retry, so start bots from `serve` or from the TUI, not from both.

**Telegram.** Pair from the TUI (**p** in Integrations, or `/telegram pair`): it shows a one-time 6-digit code, and the account that sends the bot `/start <code>` within 5 minutes becomes the owner; any other message is ignored. Replacing an existing owner asks you to confirm first, and after pairing the TUI names the new owner's @username. In groups, turn off the bot's privacy mode in @BotFather, or plain @mentions are not delivered to it. While a turn runs, the bot keeps one silent progress bubble updated with step labels only, never tool output; turn it off with `"telegram": { "progressIndicator": false }`. Files you send in the DM are saved under `<stateDir>/inbox/telegram/`, one folder per day, and the agent gets the path with your caption (albums arrive as one message; Telegram lets bots fetch up to 20 MB). Files the agent attaches to a reply follow the text, images inline and the rest as documents, up to Telegram's 50 MB bot limit. Scheduled tasks can report back: `atomic-agent task create --cron "0 9 * * *" --message "morning digest" --notify telegram` (or `notify: "telegram"` when the agent schedules it) posts each run's result to your paired DM. Reporting is per task, Telegram only; if the channel is down the report is skipped with a logged warning.

**Discord.** There is no pairing: put your user id (as a string) in `ownerUserIds`; an empty list refuses every message. The bot needs no privileged intents, because Discord delivers DMs and @mentions without them. Inbound files up to 50 MB go to `<stateDir>/inbox/discord/`; reply attachments are uploaded one message each, within your server's upload limit. There is no progress bubble.

**Swarm.** Run extra Telegram or Discord bots beside the two above, each with its own token, owner, lockfile and sessions. Manage them in the Swarm tab (`/swarm`), which writes `swarm.units` and the token for you:

The Swarm tab names the token key `<KIND>_BOT_TOKEN_<ID>`. Each unit has one owner; Telegram units pair from the Swarm tab, Discord units take the id directly. `role` is a free-text note shown in the tab and does not change what the bot does.

</details>

<details>
<summary><b>Composio toolkits</b> (1500+ SaaS apps)</summary>

[Composio](https://composio.dev) is a hosted catalogue of 1500+ SaaS toolkits (Gmail, Slack, Notion, Linear, and more) that also brokers each app's OAuth, so you never register an OAuth client yourself.

Open the **Integrations** tab in the TUI and follow the setup, or drop a key into `<stateDir>/.env`:

The key is the real gate: with no key the runtime opens no connection and registers no tool. Set `"composio": { "enabled": false }` in `config.json` to keep the key on disk with the toolkits off.

Under the hood this is not a new subsystem. Composio's tool router speaks Streamable HTTP MCP and authenticates with a static header, which is exactly the transport the MCP client already supports, so the agent treats it as one more MCP server. Tools land as `mcp.composio.*`.

Rather than loading 1500 toolkits into the prompt, the session exposes four meta-tools: the agent searches for a tool by use case, fetches its schema, then executes. Discovery is annotated read-only and flows without prompting; `COMPOSIO_MULTI_EXECUTE_TOOL` and `COMPOSIO_MANAGE_CONNECTIONS` are marked destructive, so every write to a real account still hits the approval gate.

Connected accounts are scoped by a random install id minted once and stored in `config.json`, never your email. Losing it means re-authorising every connected app.

Note that Composio is a hosted service: your OAuth tokens for connected apps live on Composio's infrastructure, and tool calls are executed through their servers rather than from your machine.

</details>

<details>
<summary><b>MCP client</b></summary>

Configure MCP servers in `config.json`, and their tools join the same registry as local tools. Trusted read-only servers can batch with other reads; untrusted servers default to approval-gated execution.

To offer only some of a server's tools, list their raw names: "enabledTools": ["get_issue", "list_issues"] keeps just those, and "disabledTools": ["delete_repository"] drops tools on top of that (or on its own, from the full list). Turned-off tools never reach the prompt and cannot be called; a change applies when the server reconnects.

The TUI MCP panel supports live add / remove without restarting the process. When a stdio server fails to connect, the tail of its stderr is surfaced in the error instead of a bare disconnect message.

</details>

Troubleshooting

If something isn't working:

1. Copy your error logs and system specs.
2. Open an issue on GitHub.
3. Or ask for help in our Discord.