进阶 docs.antigma.ai 2026-10-08 09:54:38 · 6 阅读
第24章 第 24 章：Ante 配置指南
PreferencesSettings file
Ante 将用户偏好存储在 ~/.ante/settings.json 中。仓库也可以提供自己的 .ante/settings.json，对在该仓库工作的所有人生效——参见 Project settings。
大多数设置也可以在 TUI 里通过 /config 命令交互式查看和修改——这是一个可搜索的设置对话框，支持就地切换的选项包括（tips、ambient predictions、grouped tool activity、chat render mode、short prompt、auto compact、resize reflow、default permission mode、update channel），并能快捷跳转到各专属对话框（theme、model、provider、status line、MCP servers、offline mode）。修改会立即持久化到 settings.json；render-mode 之类的更改即时生效，而 resize_reflow 等在启动时读取的设置会标注"(next session)"，需要到下一次会话才生效。
一个 settings.json 示例：
{
"model": "claude-sonnet-5-5",
"provider": "anthropic",
"theme": "default",
"append_system_prompt": "Prefer small, focused commits.",
"tools": ["Read", "Write", "Edit", "Bash"],
"auto_memory": true,
"skills": true,
"include_skills": ["deploy-checklist"],
"exclude_skills": ["noisy-skill"],
"session_save": true,
"permission_mode": "auto",
"permissions": {
"allow": ["Bash(npm run *)"],
"deny": ["Bash(rm *)"]
},
"has_completed_onboarding": true,
"ambient_prompt_suggestion": true,
"ambient_thinking_phrase": true,
"tips": true,
"group_tool_activity": true,
"short_prompt": false,
"max_concurrent_subagents": 0,
"auto_compact": true,
"channel": "stable",
"resize_reflow": "conservative",
"render_mode": "inline",
"status_line": ["model-name", "current-dir"],
"status_line_command": {
"command": "~/.config/ante/statusline.sh",
"padding": 1,
"refresh_interval": 5
},
"model_effort": {
"claude-sonnet-5-5": "medium",
"gpt-6.1-sol": "high"
},
"provider_model": {
"anthropic": "claude-sonnet-5-5",
"openai": "gpt-6.1-sol"
},
"mcp_servers": {
"filesystem": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
}
}
}
ANTE_PROFILE=review ante -p "review this change"
ante update --profile work
Profile `work` reads and writes to `~/.ante/work.settings.json`. Profiles are whole-file replacements, not layers: any value not present in the selected profile falls back to Ante's defaults, not to `settings.json`. The file must either already exist or be a bundled template; specifying an unknown name triggers a warning and causes Ante to use `settings.json` instead of creating a profile. To create a profile, write or copy `~/.ante/.settings.json` before launching Ante. Profile names can only contain lowercase ASCII letters, digits, hyphens, and underscores. Command-line flags still take precedence over the selected profile. For per-repository configuration, prefer project settings: they layer on top of user settings rather than replacing them, and require no command-line flags.
The built-in bare profile ships with Ante: the first `--profile bare` run seeds `~/.ante/bare.settings.json` with onboarding and ambient UI features disabled, plus `auto_memory`, `skills`, and `session_save` set to false (and no MCP servers, since the profile defines none). After that it behaves like any other profile — edit the file or change settings in /config and they persist. Explicit run flags such as `--enable-auto-memory` still override it per run.
The community and team also share ready-to-use profiles in the repository's `curated/` directory:
pi: Strips Ante down to four tools (Read, Write, Edit, Bash) with a concise system prompt, delegating search and automation to shell tools.
plan: A read-only research and planning agent with file mutations disabled, designed to produce an implementation plan before execution.
Project settings
A repository can carry its own settings. When a session starts or resumes, Ante walks up from the session's working directory; the nearest ancestor containing `.ante/settings.json` supplies a project layer over your user settings:
.ante/settings.json{
"append_system_prompt": "This repo targets Rust 1.88. Prefer `anyhow` over custom error types.",
"exclude_skills": ["deploy-prod"],
"auto_memory": true,
"permissions": {
"deny": ["Bash(terraform apply *)"]
}
}
与命名 profile 不同，这是一种叠加层，而非整体替换：项目文件中未涉及的键仍沿用 ~/.ante/settings.json 的值，只有它设置的键会被覆盖。命令行不需要传任何参数——把这个文件提交到仓库，所有在这个仓库里工作的人就都能生效。 项目可以设置什么 由于 .ante/settings.json 属于仓库内容，任何能提交 pull request 的人都可以写入它。因此它只能收紧或锁定配置，不能放宽。项目文件中出现以下键时会被丢弃并给出提示： 被丢弃的键原因permission_mode仓库不能把你切换到更宽松的审批模式permissions.allow仓库不能替你预先批准工具调用mcp_servers仓库不能在你的机器上启动新的 server 进程system_prompt仓库不能整体替换 agent 的指令model仓库不能把你的流量重定向到别的模型provider仓库不能把你的流量重定向到别的 provider 其余会话字段则正常叠加。项目可以设置 append_system_prompt、tools、auto_memory、skills、include_skills、exclude_skills、session_save、short_prompt、max_concurrent_subagents、model_effort，以及用于收紧的 permissions.ask / permissions.deny 规则。auto_compact、theme、channel、状态栏设置和环境功能等 UI 与设备偏好会被忽略并给出提示。 查看实际生效的配置 ante doctor 会输出一行项目信息，显示实际解析到的文件（或未找到），以及被丢弃的键。ante rage 会包含项目文件，且与用户文件一样做脱敏处理，这样 bug 报告就能带上实际生效的配置。 项目设置在会话启动或恢复时读取。会话中途修改文件不会立即生效，要等到下一个会话边界。 状态栏 status_line 字段控制 TUI 底栏第一行显示哪些条目。权限模式和实时活动显示在其下方单独一行，不会和身份类条目争抢宽度。该字段接受一组条目标识符： 条目说明model-name当前模型名effort当前 effort 等级。单独显示为 effort: high，min 时不显示provider当前 providercurrent-dir当前工作目录git-branch当前 Git 分支，显示为 ⑂ main（不可用时省略）pr-link当前分支的 GitHub pull request 链接（需要 gh）context-usedContext window 使用情况，显示为剩余窗口的 N% ctx（未知前省略）context-tokens以 token 计的 context window 使用情况，显示为 76k/200k ctx（已用量占窗口上限，与 /context 相同；未知前省略；默认关闭）terminals正在运行的 ante-* tmux 会话，按名称显示（无运行会话或 tmux 不可用时省略） 当两对条目都启用时会合并成一个复合条目：effort 并入模型名，显示为 gpt-5.6(high)（包括 min 在内的所有等级），分支并入目录，显示为 project(⑂ main)。因此默认底栏显示为： gpt-5.6(high) · openai · project(⑂ main) · 42% ctx
每一侧都保留为独立的开关——将 model-name 关闭后，effort 会恢复为自身的 effort：high item。 默认项：除 context-tokens 外的所有项，按上述顺序排列。可通过 ~/.ante/settings.json 或 TUI 中的 /statusline 命令进行配置。 基于命令的状态栏 若需完全自定义，status_line_command 会执行你指定的 shell 命令并将其输出渲染为状态栏，取代基于 item 的状态栏： {
"status_line_command": {
"command": "~/.config/ante/statusline.sh",
"padding": 1,
"refresh_interval": 5
}
}
也接受纯字符串作为简写形式："status_line_command": "echo hello"。 字段说明： command：脚本路径或内联 shell 命令，通过 sh -c 执行（必填） padding：额外水平内边距，单位为字符列（默认：0） refresh_interval：每 N 秒重新执行一次（最小值 1）。适用于时钟或外部数据场景。省略则仅在会话事件触发时执行 工作原理 Ante 将当前会话的 JSON 快照通过 stdin 传给你的命令，并展示其 stdout 输出。每次 assistant 消息发送后，以及 model、provider、effort、pull request、工作目录或终端尺寸发生变化时，该命令都会重新运行（防抖间隔 300ms）。单次执行超时上限为 5 秒，若期间有新一轮执行启动，将取消当前正在进行的执行。 JSON 输入兼容 Claude Code statusline 输入的子集，因此现有的 Claude Code statusline 脚本无需修改即可直接使用： {
"cwd": "/work/repo",
"session_id": "ses_...",
"version": "0.2.8",
"model": { "id": "claude-sonnet-5-5", "display_name": "claude-sonnet-5-5" },
"workspace": { "current_dir": "/work/repo", "project_dir": "/work/repo" },
"thinking": { "enabled": true },
"pr": { "number": 7, "url": "https://github.com/..." },
"provider": "anthropic",
"context_window": {
"context_window_size": 200000,
"total_input_tokens": 36000,
"used_percentage": 18,
"remaining_percentage": 82
}
}
翻译如下： pr 字段仅在检测到当前分支存在打开的 pull request 时出现。context_window 字段在模型上下文限制确定后的首次响应中出现，它会使用 Claude Code 的字段名，报告原始窗口大小以及已用和剩余的百分比。provider 是 Ante 的扩展字段。thinking 键保留了 Claude Code 的模式，尽管 Ante 的控制参数是 effort：只要会话的 effort 高于 min，enabled 即为 true。该命令还会在环境变量中接收 COLUMNS 和 LINES（当前终端尺寸）以及 ANTE_PROJECT_DIR（最近的包含 .git 的祖先目录）。 输出。stdout 的每一行都会变成页脚的一行（最多 8 行）。ANSI 颜色和 OSC 8 超链接会被渲染；颜色状态会在各行之间延续。空行会被丢弃，若输出为空，则渲染一个空的状态行。 一个最小示例脚本： #!/bin/sh
input=$(cat)
model=$(echo "$input" | jq -r '.model.display_name')
dir=$(basename "$(echo "$input" | jq -r '.workspace.current_dir')")
printf '\033[36m[%s]\033[0m %s' "$model" "$dir"
在将 command 指向该脚本之前，请使其可执行（chmod +x）。如果命令失败——例如不可执行、非零退出码或超时——页脚会基于脚本的 stderr 显示一行诊断信息，例如 status line: sh: …: Permission denied。脚本的更改会在下一次运行时生效，但 settings.json 本身的更改需要重启才能生效。 聊天渲染模式 默认的 inline 模式会将聊天保留在终端的正常滚动记录中。当终端或控制台丢弃内联历史记录时，请使用 fullscreen 模式：Ante 会将聊天移至备用屏幕，接管其滚动记录，并启用 PgUp / PgDn、鼠标滚轮滚动以及拖选复制功能。 { "render_mode": "fullscreen" }
在 /config 中切换 Render mode 可立即应用并持久化此更改。若仅在当前运行中启用 fullscreen 而不更改设置，请使用 ante --fullscreen。 调整大小重排 当终端窗口大小改变时，ante 会在新尺寸下重建其显示。resize_reflow 字段选择可见屏幕上方滚动记录历史内容的处理方式： ValueBehaviorconservative (默认) 从不重写已打印的滚动记录。对所有终端都安全；在激进的拖拽调整大小之后，靠近调整点处的几行可能保留旧的换行方式。purge 清除终端的滚动记录，并以新宽度重放最近的对话记录——调整大小后，会话看起来就像是在最终尺寸下启动的一样。 { "resize_reflow": "purge" }
purge 采用可选开启而非自动执行，是因为它需要终端支持清除回滚缓冲区的转义序列（CSI 3 J，即 terminfo 的 E3 能力），而 ante 无法检测终端是否支持：如果 3 J 被忽略，会静默失败，此时启用 purge 反而会复制出一份额外的回滚内容。大多数终端都支持该序列，但 iTerm2 有一个高级设置——"Prevent CSI 3 J from clearing scrollback history"——会阻止它生效。可以用下面的命令检查你的终端是否支持： seq 1 200; printf '\033[2J\033[3J\033[H'
然后向上滚动——如果数字消失了，说明终端支持 3 J，启用 purge 是安全的。 在 iTerm2 中，该功能在设置 → 高级中切换：搜索 "3 J"，将"防止 CSI 3 J 清除回滚历史记录"设为 No 以允许清除（purge 所需），或设为 Yes 以阻止清除。修改立即生效——重新运行上述检查以确认。 purge 的取舍：首次调整窗口大小时，会清除该标签页回滚历史中的所有内容，包括启动 ante 之前的 shell 输出，且只有最近 2,000 行转录内容会在调整大小后重放。在 tmux 或 zellij 中，无论此设置如何，ante 始终使用 purge 策略，因为两者都可靠支持 3 J。 配置可通过 CLI 参数按会话覆盖。 环境变量 变量描述ANTHROPIC_API_KEYAnthropic (Claude) 的 API 密钥OPENAI_API_KEYOpenAI 的 API 密钥OPENAI_COMPATIBLE_API_KEYOpenAI 兼容提供商的 API 密钥GEMINI_API_KEYGoogle Gemini 的 API 密钥VERTEX_GEMINI_API_KEYVertex AI Gemini 的 API 密钥XAI_API_KEYGrok (xAI) 的 API 密钥OPENROUTER_API_KEYOpen Router 的 API 密钥ZAI_API_KEYZai 的 API 密钥DEEPSEEK_API_KEYDeepSeek 的 API 密钥ANTIX_API_KEYAntix 的 API 密钥MODEL_BASE_URL全局后备基础 URL（被下方的按提供商变量覆盖）ANTHROPIC_BASE_URL覆盖 Anthropic 基础 URLOPENAI_BASE_URL覆盖 OpenAI 基础 URLOPENAI_COMPATIBLE_BASE_URL覆盖 OpenAI 兼容提供商的基础 URLOPENROUTER_BASE_URL覆盖 Open Router 基础 URLDEEPSEEK_BASE_URL覆盖 DeepSeek 基础 URLANTIX_BASE_URL覆盖 Antix 基础 URLMODEL_TEMPERATURE覆盖模型温度（浮点数）MODEL_TOP_P覆盖模型 top_p 采样参数（浮点数）MODEL_MAX_TOKENS覆盖最大输出 token 数（整数）MODEL_CONTEXT_LIMIT覆盖最大上下文窗口大小（整数）ANTE_LOCAL_PROVIDER_PORT当没有实时模型服务器注册提供端口时，本地提供商假设的端口（默认：8080）ANTE_HOME覆盖主配置目录（默认：~/.ante）ANTE_PROFILE为整个进程选择命名配置轮廓，包括子命令和外部应用程序；等效于 --profileANTE_INSTALL_DIR仅限安装器的二进制安装目录覆盖（默认：~/.ante/bin）ANTE_OFFLINE_CONTEXT覆盖本地模型上下文窗口上限的 token 数（参见离线模式）ANTE_MCP_TOOL_TIMEOUTMCP tools/call 的截止时间，单位为秒。默认 600；零或无效值保持默认（参见 MCP 工具调用超时）ANTE_OPENAI_TRANSPORTOpenAI Responses 传输方式：http_sse（默认）或 websocket_auto（参见 OpenAI 传输方式）ANTE_TELEMETRY使用 off、false、0、disable 或 disabled（不区分大小写）禁用 OpenTelemetry 导出OTEL_EXPORTER_OTLP_ENDPOINT将应用指标和日志发送到该 OTLP/HTTP 基础 URL；覆盖二进制文件中嵌入的任何端点OTEL_EXPORTER_OTLP_HEADERS标准逗号分隔的 OTLP 头部，格式为 name=value 对。空格需百分号编码，例如 Authorization=Basic%20ANTE_USER可选的操作员名称，作为 user.name 附加到遥测数据中；默认未设置（参见身份标识）ANTE_USER_ID可选的操作员自定义标识符，作为 user.id 附加到遥测数据中；默认未设置ANTE_ENV按部署环境对遥测数据分组（默认：local）RUST_LOG覆盖应用日志过滤器（发布版默认：ante=info）；适用于本地和导出的日志
遥测
当设置了 OTEL_EXPORTER_OTLP_ENDPOINT 或二进制文件在构建时嵌入了端点时，Ante 会初始化 OpenTelemetry 导出器。该导出器通过 OTLP/HTTP 发送指标和应用追踪日志。当收集器需要认证或租户头部时，请设置 OTEL_EXPORTER_OTLP_HEADERS；运行时端点和头部会覆盖任何嵌入的值。如果配置的头部字符串中没有可用的 name=value 条目，遥测将因启动诊断而禁用。设置 ANTE_TELEMETRY=off 可无论端点如何配置都禁用导出器；~/.ante/logs/ 下的本地日志仍会继续写入。
指标涵盖工具调用和模型调用的耗时及错误，以及在提供商报告使用情况时的 token 计数。标签取自有限集合——工具名称、模型、提供商、Ante 版本、操作系统/架构——它们不指名任何人员或机器。
身份标识
导出默认是匿名的。没有用户名回退，没有主机名，没有 MAC 地址，没有机器 ID。有两个标识符会随行；另有两个仅在你设置时才会出现：
标识符来源用途运行 ID每次进程随机生成，永不持久化为每个并发运行的 Ante 提供独立的指标序列，这是累计计数器所必需的。仅在指标中作为 service.instance.id 导出。安装 ID一个随机且易记的标签，如 clever-otter-x7f2，存储在 ~/.ante/installation-id 中用于区分“一台机器报告了 500 个错误”和“500 台机器都如此”。在首次配置遥测的启动时生成，格式为单词形式以便你在 bug 报告中引用——ante rage 包含它。这些单词不编码关于你、你的主机或任何账户的信息。你可以编辑此文件将内容更改为如 anon 这样的通用名称或你喜欢的任何名称。user.nameANTE_USER，仅显式指定指代操作部署的人员。CI 和评估运行器会设置它；笔记本电脑通常不设置。user.idANTE_USER_ID，仅显式指定当名称格式不匹配时，由操作员选定的标识符。
你可以编辑 ~/.ante/installation-id 将标识符更改为如 anon 这样的通用标签或你偏好的名称，或者删除 ~/.ante/installation-id 以重置为新的身份（它会在下次配置了遥测的运行中重新创建）。无法读取或写入主目录的 Ante 仅会报告缺少该文件。部署还可以使用 ANTE_ENV 对数据进行分组（默认：local）。
所有通过当前 RUST_LOG 过滤器的应用追踪记录也会被导出。日志正文未经清洗，因此插入了主路径或工具参数的消息即使没有属性指名你，仍会包含它们——请将 OTEL_EXPORTER_OTLP_ENDPOINT 仅指向你信任的收集器。
目录结构
用户级（~/.ante/）
~/.ante/
├── settings.json # 用户偏好设置
├──.settings.json # 由 --profile 参数指定的命名配置
├── catalog.json # 自定义提供商/模型目录
├── auth/ # OAuth 凭证和粘贴的 API 密钥
├── AGENTS.md # 全局指令
├── installation-id # 随机遥测安装标识
├── sessions/ # 持久化会话（用于 /resume）
├── projects/ # 按项目划分的自动记忆
├── run/jobs/ # 后台 Bash 状态和输出
├── run/serve.sock # 供 `ante serve --sock` 使用的 Unix socket（附带一个 .lock 文件）
├── logs/ # 按 UTC 日期分区的应用日志
├── skills/ # 用户级技能
└── agents/ # 用户级子代理
如果 ~/.ante/AGENTS.md 不存在，Ante 会回退到 ~/.claude/CLAUDE.md 读取全局指令，因此无需迁移即可兼容 Claude Code 配置。系统只读取一个文件——只要存在 AGENTS.md（即使是空文件），它总是优先。 项目级 AGENTS.md # 项目指令
CLAUDE.md # 项目指令（当不存在 AGENTS.md 时的回退方案）
.ante/
├── settings.json # 叠加在用户设置之上的项目设置
├── skills/ # 项目专属技能
└── agents/ # 项目专属子代理
.agents/
├── skills/ # 项目专属技能
└── agents/ # 项目专属子代理
.claude/
├── skills/ # 项目专属技能（兼容 Claude Code）
└── agents/ # 项目专属子代理（兼容 Claude Code）
项目指令通过从工作目录向上逐级查找来确定：在每一级父目录中，Ante 优先检查 AGENTS.md，然后是 CLAUDE.md，首个包含任一文件的目录即生效。若某目录同时包含两个文件，则只读取 AGENTS.md——CLAUDE.md 仅作回退，绝不作为次要信息源。 项目记忆（~/.ante/projects/） 项目范围的自动记忆存储在 ~/.ante/projects// 下，其中 是项目绝对路径的净化形式。持久化会话则独立存储在 ~/.ante/sessions/ 下。
~/.ante/projects/
└──/
└── memory/
└── MEMORY.md # 该项目的自动记忆
"model": "claude-sonnet-5-5",
"provider": "anthropic",
"theme": "default",
"append_system_prompt": "Prefer small, focused commits.",
"tools": ["Read", "Write", "Edit", "Bash"],
"auto_memory": true,
"skills": true,
"include_skills": ["deploy-checklist"],
"exclude_skills": ["noisy-skill"],
"session_save": true,
"permission_mode": "auto",
"permissions": {
"allow": ["Bash(npm run *)"],
"deny": ["Bash(rm *)"]
},
"has_completed_onboarding": true,
"ambient_prompt_suggestion": true,
"ambient_thinking_phrase": true,
"tips": true,
"group_tool_activity": true,
"short_prompt": false,
"max_concurrent_subagents": 0,
"auto_compact": true,
"channel": "stable",
"resize_reflow": "conservative",
"render_mode": "inline",
"status_line": ["model-name", "current-dir"],
"status_line_command": {
"command": "~/.config/ante/statusline.sh",
"padding": 1,
"refresh_interval": 5
},
"model_effort": {
"claude-sonnet-5-5": "medium",
"gpt-6.1-sol": "high"
},
"provider_model": {
"anthropic": "claude-sonnet-5-5",
"openai": "gpt-6.1-sol"
},
"mcp_servers": {
"filesystem": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
}
}
}
| model | 默认模型名称 |
| provider | 默认 API 提供商 |
| theme | TUI 颜色主题 |
| system_prompt | 新会话的替代系统提示词。CLI 参数 --system-prompt 或 --system-prompt-file 可在此配置上覆盖单次运行。已持久化的提示词文本会从 ante 数据包中删去 |
| append_system_prompt | 附加在新会话系统提示词末尾的额外文本。--append-system-prompt 可在此配置上覆盖单次运行 |
| tools | 新会话的基础工具集，替代默认工具集（空列表表示不选择任何工具）。--tools 可在此配置上覆盖单次运行；--include-tools / --exclude-tools 仍在其上叠加生效 |
| auto_memory | 是否启用自动记忆。未设置时由启动模式决定：TUI 中开启，headless 运行中关闭。--enable-auto-memory / --disable-auto-memory 可在此配置上覆盖单次运行 |
| skills | 是否发现并加载技能。除非设为 false，否则默认开启；--skills / --no-skills 可在此配置上覆盖单次运行 |
| include_skills | 在会话基础技能集之上额外装备的技能名称——采用增量方式，类似于工具的 --include-tools。名称需精确匹配；--include-skills 仅在单次运行中替换此列表 |
| exclude_skills | 从所有会话技能集中移除的技能名称。优先级高于 include_skills；名称需精确匹配。--exclude-skills 仅在单次运行中替换此列表。参见 选择特定技能 |
| session_save | 是否保存会话记录及可恢复快照。除非设为 false，否则默认开启；--session-save / --no-session-save 可在此配置上覆盖单次运行 |
| permission_mode | 默认权限模式（strict、auto 或 yolo）。在 TUI 中通过 Shift+Tab 切换模式时，strict 和 auto 会自动写入；yolo 保持仅限会话有效。无法识别的值会被忽略，而非导致整个文件失败 |
| permissions | 持久化的工具权限规则，按 allow、ask 和 deny 匹配器分组（参见 Permissions） |
| has_completed_onboarding | 引导流程是否已完成 |
| ambient_prompt_suggestion | 轮次结束后 TUI 是否显示下一个提示词建议作为幽灵文本。除非设为 false，否则默认开启 |
| ambient_thinking_phrase | 输入时 TUI 是否预测任务专用的加载短语。除非设为 false，否则默认开启 |
| tips | 代理工作时 TUI 是否在加载器下方显示提示行。除非设为 false，否则默认开启 |
| group_tool_activity | 在聊天中将连续的静默工具调用折叠为单条活动摘要。除非设为 false，否则默认开启；每次调用的完整详情仍保留在 Ctrl+O 转录中。更改仅适用于新的工具活动 |
| short_prompt | 新会话使用精简提示词集——包括浓缩的系统提示词和更短的内置工具描述；恢复会话保留其已保存的提示词模式。除非设为 true，否则默认关闭；CLI 参数 --short-prompt 可启用单次运行 |
| max_concurrent_subagents | 单个会话同时运行子代理的数量上限。若模型在一条消息中发起的 Agent 调用超过此上限，额外调用将等待空闲槽位（TUI 显示正在等待子代理槽位）而非立即启动，Agent 工具描述会告知模型此上限。未设置、null 或 0 表示无上限。对于一次只处理一个请求的本地模型，请设为 1，以避免排队子代理占用服务器队列直到 stream_idle_timeout_secs 触发。仅通过设置应用，在启动或恢复会话时生效；参见 并发限制 |
| auto_compact | 在对话接近上下文限制时主动缩减较旧的历史记录：优先淘汰老旧工具结果，随后仅对模型不再查看的较早前缀进行摘要。手动 /compact 的目标工作集比此自动路径更紧凑。除非设为 false，否则默认开启；禁用时 /compact 和溢出恢复仍有效。在 /config 中切换即适用于当前运行会话 |
| channel | ante 更新跟踪的发布渠道（stable 或 nightly）。默认为 stable；遗留的 latest 值被视为 stable。参见 更新与渠道 |
| resize_reflow | 终端调整大小时的回滚策略：conservative（默认）或 purge（见下文） |
| render_mode | 聊天渲染策略：inline（默认，终端管理回滚）或 fullscreen（由 Ante 管理滚动用的备用屏幕）。/config 中的更改实时生效；--fullscreen 仅覆盖单次启动而不持久化 |
| status_line | TUI 状态栏页脚中显示的项目（见下文） |
| status_line_command | 渲染完全自定义状态栏的 shell 命令（见下文）。设置后优先于 status_line |
| model_effort | 每模型的努力程度覆盖——键为模型名，值为 min / low / medium / high / xhigh / max。在 /models 中移动努力程度滑块时自动写入 |
| provider_model | 每个提供商最后使用的模型——切换提供商时先采用此值，再回退到提供商的默认模型。每次模型/提供商选择时自动写入 |
| mcp_servers | 会话启动时拉起的 MCP 服务器（参见 MCP Servers） |
恢复会话保留其已保存的系统提示词和提示词模式。对 system_prompt、append_system_prompt 或 short_prompt 的更改（包括项目设置和 CLI 覆盖）仅适用于新会话，例如通过 /clear 启动的会话。其他会话设置，包括权限和工具选择，仍从当前设置中解析。
命名配置档案
使用进程级的 --profile <name> 选项可用独立的 settings 文件替换 settings.json。它适用于 TUI、headless 运行以及子命令：
ante --profile workANTE_PROFILE=review ante -p "review this change"
ante update --profile work
Profile `work` reads and writes to `~/.ante/work.settings.json`. Profiles are whole-file replacements, not layers: any value not present in the selected profile falls back to Ante's defaults, not to `settings.json`. The file must either already exist or be a bundled template; specifying an unknown name triggers a warning and causes Ante to use `settings.json` instead of creating a profile. To create a profile, write or copy `~/.ante/
"append_system_prompt": "This repo targets Rust 1.88. Prefer `anyhow` over custom error types.",
"exclude_skills": ["deploy-prod"],
"auto_memory": true,
"permissions": {
"deny": ["Bash(terraform apply *)"]
}
}
与命名 profile 不同，这是一种叠加层，而非整体替换：项目文件中未涉及的键仍沿用 ~/.ante/settings.json 的值，只有它设置的键会被覆盖。命令行不需要传任何参数——把这个文件提交到仓库，所有在这个仓库里工作的人就都能生效。 项目可以设置什么 由于 .ante/settings.json 属于仓库内容，任何能提交 pull request 的人都可以写入它。因此它只能收紧或锁定配置，不能放宽。项目文件中出现以下键时会被丢弃并给出提示： 被丢弃的键原因permission_mode仓库不能把你切换到更宽松的审批模式permissions.allow仓库不能替你预先批准工具调用mcp_servers仓库不能在你的机器上启动新的 server 进程system_prompt仓库不能整体替换 agent 的指令model仓库不能把你的流量重定向到别的模型provider仓库不能把你的流量重定向到别的 provider 其余会话字段则正常叠加。项目可以设置 append_system_prompt、tools、auto_memory、skills、include_skills、exclude_skills、session_save、short_prompt、max_concurrent_subagents、model_effort，以及用于收紧的 permissions.ask / permissions.deny 规则。auto_compact、theme、channel、状态栏设置和环境功能等 UI 与设备偏好会被忽略并给出提示。 查看实际生效的配置 ante doctor 会输出一行项目信息，显示实际解析到的文件（或未找到），以及被丢弃的键。ante rage 会包含项目文件，且与用户文件一样做脱敏处理，这样 bug 报告就能带上实际生效的配置。 项目设置在会话启动或恢复时读取。会话中途修改文件不会立即生效，要等到下一个会话边界。 状态栏 status_line 字段控制 TUI 底栏第一行显示哪些条目。权限模式和实时活动显示在其下方单独一行，不会和身份类条目争抢宽度。该字段接受一组条目标识符： 条目说明model-name当前模型名effort当前 effort 等级。单独显示为 effort: high，min 时不显示provider当前 providercurrent-dir当前工作目录git-branch当前 Git 分支，显示为 ⑂ main（不可用时省略）pr-link当前分支的 GitHub pull request 链接（需要 gh）context-usedContext window 使用情况，显示为剩余窗口的 N% ctx（未知前省略）context-tokens以 token 计的 context window 使用情况，显示为 76k/200k ctx（已用量占窗口上限，与 /context 相同；未知前省略；默认关闭）terminals正在运行的 ante-* tmux 会话，按名称显示（无运行会话或 tmux 不可用时省略） 当两对条目都启用时会合并成一个复合条目：effort 并入模型名，显示为 gpt-5.6(high)（包括 min 在内的所有等级），分支并入目录，显示为 project(⑂ main)。因此默认底栏显示为： gpt-5.6(high) · openai · project(⑂ main) · 42% ctx
每一侧都保留为独立的开关——将 model-name 关闭后，effort 会恢复为自身的 effort：high item。 默认项：除 context-tokens 外的所有项，按上述顺序排列。可通过 ~/.ante/settings.json 或 TUI 中的 /statusline 命令进行配置。 基于命令的状态栏 若需完全自定义，status_line_command 会执行你指定的 shell 命令并将其输出渲染为状态栏，取代基于 item 的状态栏： {
"status_line_command": {
"command": "~/.config/ante/statusline.sh",
"padding": 1,
"refresh_interval": 5
}
}
也接受纯字符串作为简写形式："status_line_command": "echo hello"。 字段说明： command：脚本路径或内联 shell 命令，通过 sh -c 执行（必填） padding：额外水平内边距，单位为字符列（默认：0） refresh_interval：每 N 秒重新执行一次（最小值 1）。适用于时钟或外部数据场景。省略则仅在会话事件触发时执行 工作原理 Ante 将当前会话的 JSON 快照通过 stdin 传给你的命令，并展示其 stdout 输出。每次 assistant 消息发送后，以及 model、provider、effort、pull request、工作目录或终端尺寸发生变化时，该命令都会重新运行（防抖间隔 300ms）。单次执行超时上限为 5 秒，若期间有新一轮执行启动，将取消当前正在进行的执行。 JSON 输入兼容 Claude Code statusline 输入的子集，因此现有的 Claude Code statusline 脚本无需修改即可直接使用： {
"cwd": "/work/repo",
"session_id": "ses_...",
"version": "0.2.8",
"model": { "id": "claude-sonnet-5-5", "display_name": "claude-sonnet-5-5" },
"workspace": { "current_dir": "/work/repo", "project_dir": "/work/repo" },
"thinking": { "enabled": true },
"pr": { "number": 7, "url": "https://github.com/..." },
"provider": "anthropic",
"context_window": {
"context_window_size": 200000,
"total_input_tokens": 36000,
"used_percentage": 18,
"remaining_percentage": 82
}
}
翻译如下： pr 字段仅在检测到当前分支存在打开的 pull request 时出现。context_window 字段在模型上下文限制确定后的首次响应中出现，它会使用 Claude Code 的字段名，报告原始窗口大小以及已用和剩余的百分比。provider 是 Ante 的扩展字段。thinking 键保留了 Claude Code 的模式，尽管 Ante 的控制参数是 effort：只要会话的 effort 高于 min，enabled 即为 true。该命令还会在环境变量中接收 COLUMNS 和 LINES（当前终端尺寸）以及 ANTE_PROJECT_DIR（最近的包含 .git 的祖先目录）。 输出。stdout 的每一行都会变成页脚的一行（最多 8 行）。ANSI 颜色和 OSC 8 超链接会被渲染；颜色状态会在各行之间延续。空行会被丢弃，若输出为空，则渲染一个空的状态行。 一个最小示例脚本： #!/bin/sh
input=$(cat)
model=$(echo "$input" | jq -r '.model.display_name')
dir=$(basename "$(echo "$input" | jq -r '.workspace.current_dir')")
printf '\033[36m[%s]\033[0m %s' "$model" "$dir"
在将 command 指向该脚本之前，请使其可执行（chmod +x）。如果命令失败——例如不可执行、非零退出码或超时——页脚会基于脚本的 stderr 显示一行诊断信息，例如 status line: sh: …: Permission denied。脚本的更改会在下一次运行时生效，但 settings.json 本身的更改需要重启才能生效。 聊天渲染模式 默认的 inline 模式会将聊天保留在终端的正常滚动记录中。当终端或控制台丢弃内联历史记录时，请使用 fullscreen 模式：Ante 会将聊天移至备用屏幕，接管其滚动记录，并启用 PgUp / PgDn、鼠标滚轮滚动以及拖选复制功能。 { "render_mode": "fullscreen" }
在 /config 中切换 Render mode 可立即应用并持久化此更改。若仅在当前运行中启用 fullscreen 而不更改设置，请使用 ante --fullscreen。 调整大小重排 当终端窗口大小改变时，ante 会在新尺寸下重建其显示。resize_reflow 字段选择可见屏幕上方滚动记录历史内容的处理方式： ValueBehaviorconservative (默认) 从不重写已打印的滚动记录。对所有终端都安全；在激进的拖拽调整大小之后，靠近调整点处的几行可能保留旧的换行方式。purge 清除终端的滚动记录，并以新宽度重放最近的对话记录——调整大小后，会话看起来就像是在最终尺寸下启动的一样。 { "resize_reflow": "purge" }
purge 采用可选开启而非自动执行，是因为它需要终端支持清除回滚缓冲区的转义序列（CSI 3 J，即 terminfo 的 E3 能力），而 ante 无法检测终端是否支持：如果 3 J 被忽略，会静默失败，此时启用 purge 反而会复制出一份额外的回滚内容。大多数终端都支持该序列，但 iTerm2 有一个高级设置——"Prevent CSI 3 J from clearing scrollback history"——会阻止它生效。可以用下面的命令检查你的终端是否支持： seq 1 200; printf '\033[2J\033[3J\033[H'
然后向上滚动——如果数字消失了，说明终端支持 3 J，启用 purge 是安全的。 在 iTerm2 中，该功能在设置 → 高级中切换：搜索 "3 J"，将"防止 CSI 3 J 清除回滚历史记录"设为 No 以允许清除（purge 所需），或设为 Yes 以阻止清除。修改立即生效——重新运行上述检查以确认。 purge 的取舍：首次调整窗口大小时，会清除该标签页回滚历史中的所有内容，包括启动 ante 之前的 shell 输出，且只有最近 2,000 行转录内容会在调整大小后重放。在 tmux 或 zellij 中，无论此设置如何，ante 始终使用 purge 策略，因为两者都可靠支持 3 J。 配置可通过 CLI 参数按会话覆盖。 环境变量 变量描述ANTHROPIC_API_KEYAnthropic (Claude) 的 API 密钥OPENAI_API_KEYOpenAI 的 API 密钥OPENAI_COMPATIBLE_API_KEYOpenAI 兼容提供商的 API 密钥GEMINI_API_KEYGoogle Gemini 的 API 密钥VERTEX_GEMINI_API_KEYVertex AI Gemini 的 API 密钥XAI_API_KEYGrok (xAI) 的 API 密钥OPENROUTER_API_KEYOpen Router 的 API 密钥ZAI_API_KEYZai 的 API 密钥DEEPSEEK_API_KEYDeepSeek 的 API 密钥ANTIX_API_KEYAntix 的 API 密钥MODEL_BASE_URL全局后备基础 URL（被下方的按提供商变量覆盖）ANTHROPIC_BASE_URL覆盖 Anthropic 基础 URLOPENAI_BASE_URL覆盖 OpenAI 基础 URLOPENAI_COMPATIBLE_BASE_URL覆盖 OpenAI 兼容提供商的基础 URLOPENROUTER_BASE_URL覆盖 Open Router 基础 URLDEEPSEEK_BASE_URL覆盖 DeepSeek 基础 URLANTIX_BASE_URL覆盖 Antix 基础 URLMODEL_TEMPERATURE覆盖模型温度（浮点数）MODEL_TOP_P覆盖模型 top_p 采样参数（浮点数）MODEL_MAX_TOKENS覆盖最大输出 token 数（整数）MODEL_CONTEXT_LIMIT覆盖最大上下文窗口大小（整数）ANTE_LOCAL_PROVIDER_PORT当没有实时模型服务器注册提供端口时，本地提供商假设的端口（默认：8080）ANTE_HOME覆盖主配置目录（默认：~/.ante）ANTE_PROFILE为整个进程选择命名配置轮廓，包括子命令和外部应用程序；等效于 --profile
├── settings.json # 用户偏好设置
├──
├── catalog.json # 自定义提供商/模型目录
├── auth/ # OAuth 凭证和粘贴的 API 密钥
├── AGENTS.md # 全局指令
├── installation-id # 随机遥测安装标识
├── sessions/ # 持久化会话（用于 /resume）
├── projects/ # 按项目划分的自动记忆
├── run/jobs/ # 后台 Bash 状态和输出
├── run/serve.sock # 供 `ante serve --sock` 使用的 Unix socket（附带一个 .lock 文件）
├── logs/ # 按 UTC 日期分区的应用日志
├── skills/ # 用户级技能
└── agents/ # 用户级子代理
如果 ~/.ante/AGENTS.md 不存在，Ante 会回退到 ~/.claude/CLAUDE.md 读取全局指令，因此无需迁移即可兼容 Claude Code 配置。系统只读取一个文件——只要存在 AGENTS.md（即使是空文件），它总是优先。 项目级 AGENTS.md # 项目指令
CLAUDE.md # 项目指令（当不存在 AGENTS.md 时的回退方案）
.ante/
├── settings.json # 叠加在用户设置之上的项目设置
├── skills/ # 项目专属技能
└── agents/ # 项目专属子代理
.agents/
├── skills/ # 项目专属技能
└── agents/ # 项目专属子代理
.claude/
├── skills/ # 项目专属技能（兼容 Claude Code）
└── agents/ # 项目专属子代理（兼容 Claude Code）
项目指令通过从工作目录向上逐级查找来确定：在每一级父目录中，Ante 优先检查 AGENTS.md，然后是 CLAUDE.md，首个包含任一文件的目录即生效。若某目录同时包含两个文件，则只读取 AGENTS.md——CLAUDE.md 仅作回退，绝不作为次要信息源。 项目记忆（~/.ante/projects/） 项目范围的自动记忆存储在 ~/.ante/projects/
└──
└── memory/
└── MEMORY.md # 该项目的自动记忆
运行时与临时文件
过大的 WebFetch 响应会溢出到操作系统缓存目录，超过 48 小时的条目会在之后的启动时被清理。一次性的暂存文件和中间下载则使用操作系统临时目录，不参与该缓存清理。修改 ANTE_HOME 通常不会改变这两个位置。后台 Bash 任务存放在 ~/.ante/run/jobs/<proc-id>/ 下，进程存活期间一直保留，进程结束后再保留 24 小时。应用日志存放在 ~/.ante/logs/<YYYY-MM-DD>/ 下，按 UTC 日期分区。
完整目录结构和文件用途参见 Storage Reference。
优先级
配置按以下顺序解析（后者覆盖前者）：
- 内置默认值
- ~/.ante/settings.json（使用 --profile 时为 ~/.ante/<name>.settings.json）
- 项目中的 .ante/settings.json，仅限其有权设置的键
- CLI 参数或协议请求字段（--model、--provider 等）
