Configuration

AtomCode's config is TOML, supports any number of providers side by side, and lets you switch on the fly. This page explains every field and shows examples for common providers.

Config file location

Default path:

• macOS / Linux / HarmonyOS PC: ~/.atomcode/config.toml
• Windows: %USERPROFILE%\.atomcode\config.toml

You can also use --config /path/to/config.toml to point at any file. On the first run, if the file is missing, the 3-step wizard walks you through initial setup.

Minimal example

default_provider = "deepseek"

[providers.deepseek]
type = "openai"
api_key = "sk-xxxxxxxxxxxxxxxx"
model = "deepseek-chat"
base_url = "https://api.deepseek.com/v1"
context_window = 64000

This config is enough to launch atomcode and start chatting with DeepSeek.

Top-level fields

ProviderConfig fields

Fields available under each [providers.xxx] table:

Environment Variables & Dynamic API Key Resolution

To avoid storing sensitive credentials in plain text and to share environment variables with other tools, AtomCode supports flexible environment variable syntax in config.toml:

• Environment Variable Expansion ($VAR / ${VAR}):

  [providers.my_openai]
  type = "openai"
  model = "gpt-4o"
  api_key = "$MY_OPENAI_KEY" # or "${MY_OPENAI_KEY}"
  base_url = "https://api.openai.com/v1"

  Supports fallback expressions with default values (e.g., api_key = "${MY_KEY:-sk-fallback}").
• Direct Environment Variable Name:

  [providers.my_claude]
  type = "claude"
  model = "claude-sonnet-4-6"
  api_key = "ANTHROPIC_API_KEY" # Automatically read from environment variable ANTHROPIC_API_KEY

• Automatic Standard Environment Variable Fallback: When api_key is omitted or blank, AtomCode automatically checks standard environment variables matching the provider type:
  • openai / openai-compat: reads OPENAI_API_KEY
  • claude / anthropic: reads ANTHROPIC_API_KEY
  • ollama: reads OLLAMA_API_KEY
  • Global fallback: reads ATOMCODE_API_KEY

Note: The $VAR syntax in config.toml is parsed internally by AtomCode, providing consistent behavior across Windows, macOS, and Linux.

Network & proxy

By default AtomCode follows your system's proxy configuration, so it works out of the box behind a corporate proxy. Tune it under [network.proxy]:

[network.proxy]
mode = "follow_system"    # default — honor env vars + OS system proxy
# mode = "default_proxy"  # use the explicit http/https/all below
# mode = "no_proxy"       # force a direct connection
# http  = "http://127.0.0.1:7890"
# https = "http://127.0.0.1:7890"
# all   = "socks5://127.0.0.1:1080"
# no_proxy = "localhost,127.0.0.1,.internal"

IPv6 proxy hosts are bracketed automatically (::1 → http://[::1]:8080). If a login attempt fails to connect or times out, the error message points at your proxy / network settings so you can tell a proxy problem apart from bad credentials.

Common provider examples

Claude (Anthropic)

[providers.claude]
type = "claude"
api_key = "sk-ant-..."
model = "claude-sonnet-4-6"
context_window = 128000

OpenAI

[providers.openai]
type = "openai"
api_key = "sk-..."
model = "gpt-4o"
context_window = 128000

DeepSeek

[providers.deepseek]
type = "openai"
api_key = "sk-..."
model = "deepseek-chat"
base_url = "https://api.deepseek.com/v1"
context_window = 64000

Zhipu GLM

[providers.glm]
type = "openai"
api_key = "..."
model = "glm-4-plus"
base_url = "https://open.bigmodel.cn/api/paas/v4"
context_window = 128000

Tongyi Qianwen (Qwen)

[providers.qwen]
type = "openai"
api_key = "sk-..."
model = "qwen-plus"
base_url = "https://dashscope.aliyuncs.com/compatible-mode/v1"
context_window = 128000

SiliconFlow

[providers.siliconflow]
type = "openai"
api_key = "sk-..."
model = "Qwen/Qwen2.5-72B-Instruct"
base_url = "https://api.siliconflow.cn/v1"

Ollama (local)

[providers.ollama]
type = "ollama"
model = "llama3.2"
base_url = "http://localhost:11434"
context_window = 8000

Multiple providers and quick switching

Config files can host any number of providers in parallel:

default_provider = "claude"

[providers.claude]
type = "claude"
api_key = "sk-ant-..."
model = "claude-sonnet-4-6"

[providers.deepseek]
type = "openai"
api_key = "sk-..."
model = "deepseek-chat"
base_url = "https://api.deepseek.com/v1"

[providers.local]
type = "ollama"
model = "qwen2.5:14b"
base_url = "http://localhost:11434"

In the TUI, use /provider to manage provider accounts and their models. Built-in presets fill in the protocol and base URL for vendors such as AtomGit and TaoToken; choose Custom for another endpoint. Use /model to switch the current session and save the selected model as the default for sessions opened later; other already-open sessions are unchanged. The CLI also accepts one-shot overrides:

atomcode --provider deepseek --model deepseek-reasoner

Turn round limit

[coding]
max_rounds = 200

When the limit is reached, the TUI asks whether to continue or stop instead of dropping the task. Set it to 0 for no limit.

Todo eagerness

[tools.todo]
enabled = true
eager = "auto"

eager accepts auto, preferred, or always. Auto adds a stronger first-round reminder for DeepSeek V4 Flash while preserving the normal behavior for other models. Preferred applies that reminder to every model. Always requests todowrite as the first tool of a new task when no active list exists; OpenAI-compatible and Anthropic providers enforce the named choice, while adapters without named-tool selection still receive the imperative reminder. Set enabled = false to remove the tool, prompt guidance, and todo hooks together; restart the current runtime after changing this master switch. ATOMCODE_TODO remains an environment override.

Vision preprocessor

When the active provider's model can't read images (text-only models like DeepSeek-V3 / Kimi) and the user attaches an image, AtomCode doesn't refuse — it forwards the image to a separate "vision preprocessor" provider for OCR + description, then splices the resulting text into the user message before sending to the main model.

To enable: name an image-capable provider key as vision_preprocessor_provider in the config:

default_provider = "deepseek"
vision_preprocessor_provider = "qwen-vl"

[providers.deepseek]
type = "openai"
api_key = "sk-..."
model = "deepseek-chat"
base_url = "https://api.deepseek.com/v1"

[providers.qwen-vl]
type = "openai"
api_key = "sk-..."
model = "Qwen/Qwen3-VL-32B-Instruct"
base_url = "https://api.siliconflow.cn/v1"

• qwen-vl must be an existing key under [providers.*], and its model must support vision input (common ones: Qwen3-VL-* / GLM-4V-* / claude-3+ / gpt-4o / gemini-*).
• When the active provider can already see images, the preprocessor is skipped — the raw image bytes are sent directly.
• The /login flow auto-picks a VL/OCR model from the granted model list and writes this field for you (you can override afterwards).
• VL calls use an idle timeout: no total cap as long as the stream keeps producing chunks; the request times out after 30 seconds with no activity. On failure the main model still receives a "vision recognition failed" notice rather than a silent drop.

For usage-level details see Basic Usage · Image attachments / screenshots.

Three ways to edit the config

• Hand-edit — open ~/.atomcode/config.toml in your favourite editor.
• /config in the TUI — search and edit safe settings in place. The dynamic Retry attempts (current model) row writes retry_max_attempts to the active model; press Delete twice to restore the default.
• /provider in the TUI — interactively manage provider accounts and their models; changes are written back to disk.

Next steps

• Login Methods — skip manual key management with AtomGit OAuth.
• Basic Usage — see how CLI flags can override config for one run.