aider 配置完全指南：命令行开关、YAML 配置与 .env 文件的四种等价配置方式

aider 配置完全指南命令行开关、YAML 配置与 .env 文件的四种等价配置方式【免费下载链接】aideraider is AI pair programming in your terminal项目地址: https://gitcode.com/GitHub_Trending/ai/aider本文基于 aider 仓库的配置文档与源码完整讲解 aider 的四种等价配置方式命令行开关、.aider.conf.yml、环境变量、.env文件、配置文件搜索路径与优先级规则、列表型选项的 YAML 写法以及模型、Git、lint/test 等常用选项的含义与默认值帮助你在不反复修改启动命令的情况下为个人环境、团队仓库和脚本化调用分别建立稳定可复现的 aider 配置。一、四种等价的配置方式aider 提供大量命令行开关来调整其行为。文档明确指出绝大多数的选项都可以通过四种等价的方式设置引自 config.md命令行开关command line switch.aider.conf.ymlYAML 配置文件——可放在用户主目录或放在 git 仓库根目录形如AIDER_xxx的环境变量——可以在 shell 中export也可以写进.env文件.env文件。以深色模式--dark-mode为例下面四种写法效果完全一致命令行开关$ aider --dark-mode.aider.conf.yml文件dark-mode: true环境变量export AIDER_DARK_MODEtrue.env文件AIDER_DARK_MODEtrue从命名规律看环境变量名是把开关名的连字符转为下划线、全部大写并加上AIDER_前缀例如--user-input-color对应AIDER_USER_INPUT_COLOR、--edit-format对应AIDER_EDIT_FORMAT。这个规律在 options 参考文档 中为每个选项都标注了对应的Environment variable可以逐一对照。提示API key 相关的配置有专门的规范与推荐存放位置见 API key 配置文档。二、.aider.conf.ymlYAML 配置文件大多数 aider 选项都可以写进.aider.conf.yml文件。根据 aider_conf.mdaider 会按以下位置查找该文件你的主目录home directory你的 git 仓库根目录当前目录。如果上述文件存在将按该顺序加载后加载的文件优先生效。此外还可以用--config filename别名-c显式指定配置文件——此时只加载这一个文件不再走默认搜索路径。列表型选项的两种写法有些选项接受列表值YAML 中可以用项目符号列表read: - CONVENTIONS.md - anotherfile.txt - thirdfile.py也可以用逗号加方括号的内联写法read: [CONVENTIONS.md, anotherfile.txt, thirdfile.py]完整示例配置仓库中附带了由源码自动生成的完整示例文件 sample.aider.conf.yml其中每个条目都注明了含义与默认值节选其中几个最常用的片段# 主模型 model: xxx # 指定 LLM 使用的编辑格式默认取决于模型 #edit-format: xxx # 使用 architect 模式规划模型 编辑模型 #architect: false # 仓库地图的 token 预算0 表示禁用 #map-tokens: xxx # 修改后自动 lint默认 True #auto-lint: true # 指定各语言的 lint 命令 #lint-cmd: # - python: flake8 --select... # 指定测试命令与自动测试 #test-cmd: xxx #auto-test: false示例文件开头的注释特别说明了一个限制YAML 配置文件里只能放 OpenAI 和 Anthropic 的 API key其他各家 API 的 key 应存放在.env文件中。配置文件加载的源码实现配置文件的搜索逻辑在 main.py 中程序先收集当前目录、git 根目录、主目录下的.aider.conf.yml候选路径随后调用 args.py 中的get_parser(default_config_files, git_root)构造解析器。该解析器基于configargparse并以configargparse.YAMLConfigFileParser解析 YAML 配置见 args.py——这也是文档中强调 YAML 语法的原因配置文件的格式由YAMLConfigFileParser直接解析而非简单的keyvalue文本。-vverbose模式下aider 会把“未指定--config时的配置文件搜索顺序”打印出来便于排查配置来源。另外main.py 中的check_config_files_for_yes会检查各配置文件里是否出现以yes:开头的行并在启动时给出提示——因为yes-always对所有确认自动回答 yes这类选项一旦误写进共享的仓库级配置文件可能造成不受控的自动操作。三、.env文件与环境变量根据 dotenv.md.env文件既可以存放各家 LLM 的 API key如OPENAI_API_KEY、ANTHROPIC_API_KEY也可以存放大量AIDER_前缀的通用选项。aider 查找.env的位置为主目录git 仓库根目录当前目录--env-file filename显式指定的文件。同样按该顺序加载后加载的优先生效。仓库中的示例文件为 sample.env结构如下节选################# # LLM parameters: # Include xxx_API_KEY parameters and other params needed for your LLMs. ## OpenAI #OPENAI_API_KEY ## Anthropic #ANTHROPIC_API_KEY ############# # Main model: #AIDER_MODEL # 指定各 Provider 的 API key #AIDER_API_KEY ################# # Model settings: #AIDER_EDIT_FORMAT #AIDER_MAP_TOKENS ################ # Git settings: #AIDER_AUTO_COMMITStrue #AIDER_ATTRIBUTE_CO_AUTHORED_BYtrue.env加载的源码细节main.py 中的load_dotenv_files通过统一的generate_search_path_list见 main.py生成候选列表——该函数把主目录、git 根目录、当前目录及命令行指定文件按“优先级从低到高”排序并去重然后逐个调用load_dotenv(fname, overrideTrue)因此后加载的文件覆盖先加载的变量。还有一个源码细节值得注意若存在~/.aider/oauth-keys.env它会被插到列表最前面最先加载、可被其他文件覆盖这是 OAuth 登录产生的 key 的存放位置。同样的搜索路径机制还被复用于模型自定义文件.aider.model.settings.yml未知模型的 aider 设置与.aider.model.metadata.json未知模型的上下文窗口与费用也分别按“主目录 → git 根 → 当前目录 → 命令行参数”的顺序搜索见 main.py 的register_models与register_litellm_models。四、核心选项速查以下从 options 参考文档 中选取各分组的核心选项含默认值完整列表以aider --help或该文档为准。主模型与 API选项环境变量说明与默认值--model MODELAIDER_MODEL主聊天使用的模型--openai-api-key/--anthropic-api-keyAIDER_OPENAI_API_KEY/AIDER_ANTHROPIC_API_KEY对应 API key--openai-api-baseAIDER_OPENAI_API_BASE自定义 API base url--api-key PROVIDERKEYAIDER_API_KEY为任意 provider 设置 key设置PROVIDER_API_KEYKEY--set-env NAMEvalueAIDER_SET_ENV设置任意环境变量可多次使用替代多个已弃用的--openai-api-*参数--timeout VALUEAIDER_TIMEOUTAPI 调用超时秒数默认 None--verify-ssl/--no-verify-sslAIDER_VERIFY_SSL是否校验 SSL 证书默认 True模型设置与编辑格式选项默认值说明--edit-format取决于模型指定 LLM 使用的编辑格式如whole、diff等--architect关主聊天使用 architect 编辑格式--auto-accept-architectTrue是否自动接受 architect 的修改--weak-model取决于--model生成 commit message 与聊天历史摘要用的弱模型--editor-model取决于--model编辑器任务所用模型--max-chat-history-tokens模型的max_chat_history_tokens聊天历史 token 软上限超过后开始摘要--reasoning-effort/--thinking-tokens未设置推理类模型的参数thinking-tokens设 0 可禁用仓库地图Repomap选项默认值说明--map-tokens建议值仓库地图建议使用的 token 数0 表示禁用--map-refreshauto地图刷新策略auto、always、files、manual--map-multiplier-no-files2未指定文件时地图 token 的放大倍数Git 相关选项默认值说明--git/--no-gitTrue是否查找 git 仓库--auto-commitsTrueLLM 修改后自动提交--dirty-commitsTrue仓库发现已“脏”时是否仍提交--attribute-co-authored-byTrue用Co-authored-bytrailer 标注 aider 的编辑优先于 author/committer 归因的默认行为--attribute-author/--attribute-committerTrue在 git author / committer 名字中归因 aider--aiderignore.aiderignoregit 根指定 ignore 文件--subtree-onlyFalse只考虑当前子树下的文件--git-commit-verifyFalse提交时是否运行 pre-commit 钩子默认用--no-verify跳过--dry-runFalse演练模式不实际修改文件修复、lint 与测试选项默认值说明--auto-lintTrue修改后自动 lint--lint-cmd[]按语言指定 lint 命令如python: flake8 --select...可多次使用--test-cmd[]测试命令--auto-testFalse修改后自动测试--lint/--testFalse一次性 lint/test 后退出运行模式与输出选项默认值说明--message-m/--message-file-f—发送单条消息后处理回复并退出禁用聊天模式适合脚本化--gui/--browserFalse在浏览器中运行 aider--copy-pasteFalseaider 与网页 UI 之间自动复制粘贴聊天--dark-mode/--light-modeFalse / False深色 / 浅色终端配色--streamTrue是否流式输出响应--show-repo-map/--show-promptsFalse调试打印仓库地图 / 系统提示词后退出--yes-always—对所有确认自动回答 yes--verbose-vFalse详细输出含配置文件搜索顺序等文档同时列出了一批已弃用的模型快捷开关--opus、--sonnet、--haiku、--4o、--mini、--deepseek、--o1-mini、--o1-preview等均已标注 “deprecated, use--model”新项目应统一使用--model。五、按场景选择配置方式结合搜索路径与优先级规则实践中可以这样分工个人偏好模型、配色、vim输入模式等放主目录的.aider.conf.yml所有项目共享且优先级最低可被仓库级配置覆盖仓库级约定.aiderignore、lint-cmd、auto-test等放 git 仓库根目录的.aider.conf.yml随仓库分发给团队API key放.envgit 根或主目录YAML 中只建议放 OpenAI/Anthropic 两家 key其余一律用.envCI / 脚本调用直接传--model、-m、--yes-always等命令行参数或用-c指定单一配置文件避免依赖环境。需要注意的是优先级链条命令行参数 后加载的配置文件/.env 先加载者。对于.env加载顺序为~/.aider/oauth-keys.env如存在最先→ 主目录 → git 根 → 当前目录 →--env-file指定文件见 main.py。配置不生效时可以用aider -v查看实际加载的文件与搜索顺序这是仓库源码中内置的排查手段。【免费下载链接】aideraider is AI pair programming in your terminal项目地址: https://gitcode.com/GitHub_Trending/ai/aider创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考