配置文件

AtomCode 的配置采用 TOML 格式,支持多个 provider 并行存在、随时切换。本页讲清每一个字段的含义和常见 provider 的示例配置。

配置文件位置

默认路径:

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

也可以通过 --config /path/to/config.toml 指定任意路径。首次运行时,若该文件不存在,3 步启动向导会引导你完成初始化。

最小示例

default_provider = "deepseek"

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

这个配置已经可以启动 atomcode 并与 DeepSeek 对话。

v5.0.7 的 Provider 管理

推荐直接运行 /provider：先添加供应商账号，再在该账号下添加一个或多个模型。供应商共用协议、Base URL 和 API Key；模型分别保存名称、上下文窗口等参数。旧版 [providers.*] 配置仍可继续使用，AtomCode 会自动兼容。

顶层字段

字段	类型	说明
`default_provider`	string	启动时默认使用的 provider 名(必须是 `[providers.*]` 中定义过的 key)
`default_workdir`	string?	默认工作目录。用 `/cd` 切换目录时自动写回这里,下次启动恢复
`providers`	table	provider 名到 ProviderConfig 的映射
`vision_preprocessor_provider`	string?	当主 provider 不支持图片但用户 attach 了图时,把图片转交给这里指定的 provider 做 OCR / 描述,结果以文本形式 splice 给主模型。详见视觉预处理器
`init_prompt_file`	string?	追加到内置 `/init` 提示词后的 UTF-8 文件。相对路径基于 `$ATOMCODE_HOME` 解析，最大 64 KiB；也可以在 `/config` 中编辑。

ProviderConfig 字段

每一个 [providers.xxx] 表下可用的字段:

字段	类型	必填	说明
`type`	string	是	provider 协议类型,目前支持 `openai`、`claude`、`ollama`
`api_key`	string?	视情况	API Key。支持明文密钥、环境变量语法（如 `$MY_KEY` 或 `${MY_KEY:-default}`）、环境变量名（如 `MY_KEY`），或留空自动回退标准环境变量（如 `OPENAI_API_KEY` / `ANTHROPIC_API_KEY`）。`ollama` 可不填。OAuth 登录的 provider 不含此字段，token 从 `~/.atomcode/auth.toml` 自动读取
`model`	string	是	模型名,比如 `deepseek-chat`、`gpt-4o`、`claude-sonnet-4-6`
`base_url`	string	是	API 基地址,需指向实际接口。例:`https://api.deepseek.com/v1`、`http://localhost:11434`
`context_window`	integer	否	模型上下文窗口(tokens),默认 64000。`ollama` 默认 8000
`max_tokens`	integer?	否	单次响应的最大输出 token 数。留空则使用 `context_window / 4`
`retry_max_attempts`	integer?	否	Provider OPEN 重试循环的总尝试次数；显式设置后也会限制由 kernel 接管的 HTTP 429 恢复次数（均包含首次请求）。留空时保留原有默认策略（adapter 3 次及 kernel 的限流保护策略）；设为 1 可关闭 adapter 层及 429 自动重试，且取值不得小于 1。使用账号/模型新配置结构时，应写在 `[models."..."]` 模型配置中，因为重试策略属于模型行为。
`system_prompt`	string?	否	覆盖默认系统提示。大多数场景不需要
`user_agent`	string?	否	覆盖 HTTP 请求的 User-Agent,当上游接口屏蔽通用 UA 时使用

环境变量与 API Key 动态解析

为避免在配置文件中明文保存敏感密钥，并方便与其他开发工具共用环境变量，AtomCode 支持在 config.toml 中灵活使用环境变量：

环境变量语法展开 ($VAR / ${VAR})：

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

支持带默认值的表达式（例：api_key = "${MY_KEY:-sk-fallback}"）。

直接填写环境变量名：

[providers.my_claude]
type = "claude"
model = "claude-sonnet-4-6"
api_key = "ANTHROPIC_API_KEY" # 自动从环境变量 ANTHROPIC_API_KEY 中读取

留空自动回退标准环境变量：当未配置或留空 api_key 时，系统会自动寻找对应 type 的标准环境变量：
- openai / openai-compat：读取 OPENAI_API_KEY
- claude / anthropic：读取 ANTHROPIC_API_KEY
- ollama：读取 OLLAMA_API_KEY
- 通用后备：读取 ATOMCODE_API_KEY

注：配置文件中的 $VAR 语法由 AtomCode 程序内部解析，在 Windows、macOS 和 Linux 上保持统一写法。

为什么默认 64K 而不是 128K?

即便模型官方声称支持 128K+,其有效注意力窗口通常要小得多,过大上下文反而会触发"迷失在中段"的问题,并且阻止 AtomCode 的上下文压缩策略生效。64K 是经验上最稳的默认值,若你确定模型表现良好,可自行上调。

网络与代理

AtomCode 默认跟随系统代理配置,因此在公司代理后也能开箱即用。行为在 [network.proxy] 下配置:

[network.proxy]
mode = "follow_system"    # 默认 —— 采用环境变量 + 系统代理
# mode = "default_proxy"  # 使用下面显式的 http/https/all
# mode = "no_proxy"       # 强制直连
# 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"

mode	行为
`follow_system`(默认)	采用 `HTTP_PROXY` / `HTTPS_PROXY` / `ALL_PROXY` / `NO_PROXY`;未设置的部分回退到操作系统的系统代理(Windows 注册表 / macOS `scutil --proxy`)。
`default_proxy`	使用本段里显式的 `http` / `https` / `all` / `no_proxy` 值。
`no_proxy`	强制直连,忽略环境变量与系统代理。

IPv6 代理主机会自动加方括号(::1 → http://[::1]:8080)。若登录时连接失败或超时,错误信息会指向你的代理 / 网络设置,便于区分是代理问题还是凭据错误。

常见 provider 配置示例

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

智谱 GLM

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

通义千问 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(本地)

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

注意

Ollama 模型 function calling 的兼容性参差不齐,弱一些的本地模型可能无法稳定触发工具调用。建议优先尝试 Qwen2.5 / Llama3.2 的 Instruct 版本。

多 provider 与快速切换

配置文件允许同时存在任意数量的 provider:

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"

在 TUI 中用 /provider 管理供应商账号和账号下的模型；内置预设会自动填好协议与 Base URL，包括 AtomGit、TaoToken 等，也可以选择“自定义”。用 /model 切换当前会话，并把所选模型保存为后续新会话的默认值；其他已经打开的会话不变。命令行启动时也支持一次性覆盖:

atomcode --provider deepseek --model deepseek-reasoner

回合轮数

[coding]
max_rounds = 200

达到上限时，TUI 会询问继续还是停止，不会直接丢失当前任务。设置为 0 表示不限制。

Todo 触发积极度

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

eager 支持 auto、preferred、always。Auto 会对 DeepSeek V4 Flash 在新任务首轮增加高权重提醒，其他模型保持原行为；Preferred 对所有模型启用该提醒；Always 会在没有活跃任务列表时要求先调用 todowrite：OpenAI-compatible 与 Anthropic provider 会强制指定该工具，不支持 named-tool selection 的 adapter 仍会收到强指令提醒。设置 enabled = false 会一起关闭工具、提示词和 Todo hooks；修改这个总开关后需要重启当前 runtime。环境变量 ATOMCODE_TODO 仍可覆盖该开关。

视觉预处理器

当当前 active provider 的模型不支持图片输入(纯文本模型,比如 DeepSeek-V3 / Kimi),用户却 attach 了图片时,AtomCode 不会直接拒绝,而是会把图片转给一个独立的"视觉预处理 provider"做 OCR + 描述,把结果以文本形式 splice 进用户消息里再发给主模型。

启用方式:在配置里指定一个支持图片的 provider key 作为 vision_preprocessor_provider:

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 必须是 [providers.*] 里已经定义过的 key,且对应的模型支持视觉输入(常见的有 Qwen3-VL-* / GLM-4V-* / claude-3+ / gpt-4o / gemini-* 等)。
当前 active provider 自身就支持图片时,不会走预处理器,直接发原始图片字节。
/login 流程会从下发的模型列表中自动挑选一个 VL/OCR 模型并写入这个字段(可在事后手动覆盖)。
VL 调用使用无进展超时(idle timeout):只要 stream 持续吐 chunk 不限总时长;30 秒没动静才超时。失败时主模型仍会收到带 "图片识别失败" 标记的消息,而不是静默吞掉。

用法层面的细节参见基本使用 · 图片附件 / 截图。

编辑配置的三种方式

手动编辑 —— 直接用你喜欢的编辑器打开 ~/.atomcode/config.toml。
TUI 内 /config —— 可直接搜索和修改安全配置。其中动态的“最大重试次数（当前模型）”会把 retry_max_attempts 写入当前模型；连续按两次 Delete 可恢复默认值。
TUI 内 /provider —— 交互式管理供应商账号及其模型，改动会自动落盘。

下一步

登录方式 —— 如果不想手动管理 API Key,用 AtomGit OAuth 一步到位。
基本使用 —— 看看 CLI 参数如何一次性覆盖配置。