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, CPU when no GPU is usable. Managed local models ship for Linux x64 only; on arm64 point the agent at an external llama-server instead.
• 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, run it with --no-sandbox. - 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 in the TUI Models tab. 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>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_URL: external llama-server URL. - ATOMIC_AGENT_LLAMA_API_KEY: optional bearer token for llama-server. - ATOMIC_AGENT_LLAMA_MAX_TOKENS: completion cap. - 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.

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.

</details>

<details> <summary><b>Claude Code / OpenAI Codex subscriptions</b> (no API key)</summary>

Drives a vendor CLI you are already signed into, so a flat-rate subscription can power the agent with no API key and no per-token billing. Two are supported: claude (Claude Code) and codex (OpenAI Codex).

Prerequisite: the CLI installed and signed in — claude then /login, or npm i -g @openai/codex then codex login. Atomic only spawns the binary; it never reads, copies, or replays its OAuth tokens or keychain entries.

In the TUI: Providers → n → pick the subscription row, then type a model. For Claude that is sonnet, opus, haiku, fable, or a pinned id like claude-sonnet-5; for Codex leave it blank — under a ChatGPT login Codex rejects explicit model ids (not supported when using Codex with a ChatGPT account) and resolves one itself. There is no API-key screen, because there is no key. Equivalent config.json:

{
  "llm": {
    "activeTextProvider": "claude-cli",
    "providers": [
      {
        "id": "claude-cli",
        "kind": "subscription-cli",
        "defaultChatModel": "sonnet",
        "subscriptionCli": { "cli": "claude" }
      }
    ]
  }
}

Optional keys inside subscriptionCli: binPath (absolute path when the CLI is not on PATH), extraArgs (appended verbatim — e.g. ["--effort", "high"]), streaming (set false to buffer), maxBudgetUsd.

Swap "cli": "claude" for "cli": "codex" to drive Codex instead, and drop defaultChatModel.

Each completion spawns the CLI fresh with the prompt on stdin (a two-zone prompt exceeds the 128 KiB argv limit). For claude it runs claude --print with these flags, which are load-bearing rather than cosmetic:

• --tools "" — disables Claude Code's own Bash/Edit/Write. Without it a second agent would act on your machine outside Atomic's approval ladder.
• --strict-mcp-config with no config — keeps your MCP servers out of what should be a stateless completion.
• --system-prompt — replaces Claude Code's coding-agent prompt, which would otherwise compete with the prompt Atomic already built.
• --no-session-persistence — Atomic owns session state; CLI-side history would double-count context.
• --bare is never passed. Its own docs say OAuth and keychain are never read under it, which would defeat the whole feature.

For codex it runs codex exec --json with --ephemeral, --skip-git-repo-check, --ignore-user-config and -s read-only. Three differences are worth knowing, because Codex is a more opinionated agent than Claude's headless mode:

• There is no --tools "" equivalent. -s read-only confines Codex's own tools to reading; it cannot remove them. Left to itself, Codex will try to perform the request with its own tools instead of emitting Atomic's tool-call protocol — in testing it answered "I can't find probe.txt" after looking in its own working directory. The fix is an explicit completion-engine instruction prepended to the prompt (Codex has no system-prompt flag). It works — verified turns drive os.fs.read → reply and os.fs.read → os.fs.write → reply with no parse retries — but it is a prompt-level guarantee, not a structural one like --tools "".
• Codex exits 0 even when the turn fails. A bad model id, an expired login and a rate limit all produce a clean exit with a turn.failed event, so the adapter treats a missing turn.completed as a failure rather than trusting the exit code.
• No streaming. codex exec --json emits the answer in one item.completed, with no incremental text events, so this provider buffers instead of pretending to stream.

Not supported on either CLI: vision, embeddings (they stay on the local daemon), and the sampling knobs temperature / top_p / top_k / seed / stop / maxTokens — neither CLI exposes a flag for them, so they are dropped rather than silently approximated. Reconfiguring binPath or extraArgs means editing config.json; the model is changeable from the LLM tab.

Two things worth knowing before you switch a long-running agent onto either: each completion pays roughly 0.8 s of process startup, and subscription plans have session and weekly caps that an autonomous multi-step agent reaches much faster than interactive use. When a cap is hit, the CLI's own message is surfaced verbatim.

[!NOTE] Whether driving a subscription CLI from another agent is acceptable use is the vendor's call, not this project's. Atomic uses the officially documented headless mode and nothing else; the decision to use it is yours. </details>

<details> <summary><b>Qwen / Tinker tagged tool calls</b> (opt-in compatibility provider)</summary>

Some Qwen-serving OpenAI-compatible backends (Tinker, certain vLLM/llama.cpp front-ends) emit tool calls as inline <tool_call><function=…>…</function></tool_call> text instead of the native tool_calls field — they show up as assistant prose and never execute (#105).

To enable the adapter, set the provider kind to qwen-openai-compatible in config.json (with baseUrl + defaultChatModel). Plain openai-compatible does not enable it — the generic kind is left untouched on purpose. There is no TUI wizard row for this kind yet; it is config-only for now.

{
  "llm": {
    "providers": [
      {
        "id": "tinker",
        "kind": "qwen-openai-compatible",
        "baseUrl": "https://your-tinker-host",
        "defaultChatModel": "Qwen3-32B"
      }
    ]
  }
}

Behavior: - The tagged call is read from content, or from reasoning_content when content is empty or holds unparseable tag noise. - Argument values are coerced against the offered tool's JSON schema; a call that does not match is dropped (fail-closed) rather than executed with guessed args. - Streaming stays live: text/reasoning deltas stream as usual and the buffered final message is adapted once the stream closes.

Limitation — MCP tools: the schema coercion supports a fixed JSON-Schema subset and rejects unknown keywords such as $ref. Atomic's built-in tools are fine, but MCP tools that ship a draft-07 inputSchema with $ref (or other unsupported keywords) will fail coercion and remain prose. MCP + tagged Qwen is therefore unsupported for now. </details>

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.

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, 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).

<stateDir>/.env

TELEGRAM_BOT_TOKEN=123456789:AA-your-bot-token

The TUI can store the token, start the channel, open pairing mode, and show status. Approvals arrive as inline buttons in your DM. Telegram is intentionally single-user.

While a turn runs, the bot keeps one live progress bubble updated in place. It is sent silently and shows step labels only, never tool output; turn it off with `"telegram": { "progressIndicator": false }`.

Scheduled tasks can report back to the same chat: create a cron job with `atomic-agent task create --cron "0 9 * * *" --message "morning digest" --notify telegram` (or ask the agent to schedule with `notify: "telegram"`), and each run posts its final result to your paired DM when it finishes. Reporting is strictly per-task opt-in, and the report's result text is sent to Telegram's servers; when the channel is down or unpaired the report is skipped with a logged warning and the task itself is unaffected.

</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.

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.