配置参考
config.toml、providers.toml 和 mcp.toml 中每个键的类型、默认值和含义。
所有键使用 camelCase。没有写出的键使用默认值(mcp.toml 的 MCP 服务器取新服务器的值,见下文);TOML 没有空值,要让可选键“未设置”,就不要写它。
config.toml
这些键可以写在用户的 config.toml、配置档 [profiles.名字] 和受信任项目的 .hanafubuki-agent/config.toml 中,也可以用 -c 和 config set 设置。见配置分层。
通用
| 键 | 类型和取值 | 默认值 | 含义 |
|---|---|---|---|
permissionMode | "manual"、"auto_review"、"full_access" | "manual" | 权限模式 |
wakeOnBackgroundTasks | 布尔值 | true | 对话启动的子代理结束或给它发消息时,自行恢复该对话;关闭时,模型被告知等待它的子代理(工具)。每个会话在下一个回合采用修改 |
disabledPlugins | 插件名的数组,最多 64 个 | [] | 关闭的插件,见下表 |
logLevel | "off"、"error"、"warn"、"info"、"debug"、"trace" | "info" | 日志文件的级别,见网络与日志 |
disabledPlugins 中有意义的插件名:
| 插件 | 关闭后 |
|---|---|
execution | 不能运行命令(exec_command、write_stdin、resize_execution) |
workspace-fs | 不能读写文件(read_file、list_directory、search_text、apply_patch、move_path、delete_path) |
web | 不能搜索和抓取网页(web_search、fetch_web_page) |
view-image | 不能查看图片(view_image) |
mcp | 模型看不到 MCP 工具和资源;服务器仍然会连接 |
skills | 没有 Skill 目录、Skill 工具和 $名字 提及 |
memory | 模型看不到记忆,也没有记忆工具 |
titles | 不再用模型为会话生成标题,保留第一条消息开头作为标题;没有标题建议 |
recap | 没有会话概要 |
goal | 没有会话目标:没有目标工具、上下文和继续推进,也没有目标调用;已经设置的目标仍然保存着 |
subagents | 没有子代理:模型没有子代理工具和指引;门面的 subagents 调用不可用 |
review | 没有评审:评审调用不可用,评审会话既不带评审准则,也不保持只读 |
worktree | 没有工作树(/worktree,门面的 worktree_* 调用) |
hooks | 不运行任何钩子,无论是你的还是已安装插件的;钩子调用不可用,设置中心的 Hooks 集合为空 |
plugins | 模型不再被告知已安装的插件,它们的代码停止;它们的 Skill、MCP 服务器和钩子仍然运行,角色也保留 |
workspace-context | 模型看不到 AGENTS.md、工作区目录和环境信息 |
permission-mode | 模型不再被告知当前的权限模式 |
其他名字会被接受但没有效果。
沙箱
模型运行的命令能触及什么,见沙箱。
| 键 | 类型和取值 | 默认值 | 含义 |
|---|---|---|---|
sandboxMode | "read-only"、"workspace-write"、"full-access" | 未设置:Linux 和 macOS 上为 "workspace-write",其他平台为 "full-access" | 沙箱模式。未设置的模式不会被写入文件,所以会随平台获得沙箱而改变 |
sandboxWorkspaceWrite.writableRoots | 绝对路径的数组 | [] | workspace-write 模式下命令还可以写入的目录 |
sandboxWorkspaceWrite.networkAccess | true、false | false | workspace-write 模式下命令能否使用网络 |
windows.sandbox | "unelevated"、"elevated" | 未设置 | Windows 后端:unelevated 限制写入但不限制网络;elevated 需要 /setup-default-sandbox 初始化,并用独立账户执行网络策略。未设置或初始化不完整时拒绝沙箱命令。其他平台忽略此项。 提升模式存在 MSYS 兼容带来的已知隔离回归。 |
无法读取的 sandboxMode 会被修复为最严格的 "read-only",而不是默认值;含有相对路径的 writableRoots 会被整个丢弃;无法读取的 windows.sandbox 会被丢弃,这会关闭 Windows 沙箱,于是沙箱中的命令会失败,而不是以更少的限制运行。
记忆
| 键 | 类型和取值 | 默认值 | 含义 |
|---|---|---|---|
memory.enabled | 布尔值 | false | 是否启用记忆 |
memory.useMemories | 布尔值 | true | 模型是否可以使用已有的记忆 |
memory.generateMemories | 布尔值 | true | 是否从会话中提取新的记忆 |
memory.excludeExternalContext | 布尔值 | false | 会话使用过网页或 MCP 工具的结果后,不再从中提取记忆 |
memory.extractionModel | 模型名,1–256 字节 | 未设置 | 提取记忆使用的模型;未设置时使用模型策略中的模型 |
memory.consolidationModel | 模型名,1–256 字节 | 未设置 | 整合记忆使用的模型;未设置时使用模型策略中的模型 |
memory.maxSourceAgeDays | 整数,1–3650 | 10 | 只读取最近这么多天内的会话 |
memory.minimumIdleHours | 整数,0–8760 | 6 | 会话空闲这么多小时后才提取 |
memory.maxSessionsPerPass | 整数,1–64 | 2 | 每一轮最多提取的会话数 |
memory.maxStage1Outputs | 整数,1–4096 | 256 | 整合时最多使用的提取结果数 |
memory.maxUnusedDays | 整数,1–3650 | 30 | 这么多天没有被使用过的提取结果会过期 |
网页工具
| 键 | 类型和取值 | 默认值 | 含义 |
|---|---|---|---|
webSearchProvider | "auto"、"duckduckgo"、"searxng" | "auto" | 网页搜索使用的服务,见工具 |
searxngBaseUrl | http 或 https URL,不含凭据、查询和片段,最多 2048 字节 | 未设置 | SearXNG 实例的地址;"searxng" 需要它 |
webFetchUseJinaReader | 布尔值 | false | 直接抓取网页失败时,改用 https://r.jina.ai/ 读取 |
webFetchResolveThroughProxy | 布尔值 | false | 设置了代理 URL 时,本机无法解析的页面域名交给代理解析,而不是让抓取失败;见网页抓取与域名解析 |
压缩
会话上下文增长时如何缩减;何时运行标准压缩、运行哪种压缩由模型策略决定(上下文窗口与压缩)。
| 键 | 类型和取值 | 默认值 | 含义 |
|---|---|---|---|
compaction.strategy | "standard"、"background"、"hierarchical" | "standard" | 压缩策略(见下) |
compaction.background.thresholdPercent | 整数,1–100 | 65 | 在后台开始压缩的窗口比例;应低于 autoCompactThresholdPercent |
compaction.background.childSessions | 布尔值 | true | 子会话(子代理的、评审的)是否也在后台压缩;false 时它们用 "standard" |
compaction.hierarchical.maxContextLimitPercent | 整数,1–100 | 75 | 超过窗口的这一比例时,立即请模型折叠历史 |
compaction.hierarchical.emergencyThresholdPercent | 整数,1–100 | 95 | 超过窗口的这一比例时,截短过大的工具输出 |
compaction.hierarchical.nudgeGrowthTokens | 整数 | 50000 | 可折叠片段增长到这么多 token 后才请模型折叠 |
compaction.hierarchical.preserveRecentMessages | 整数 | 3 | 不参与折叠的最近消息数 |
compaction.hierarchical.preserveRecentTokens | 整数 | 5000 | 不参与折叠的最近 token 数 |
compaction.hierarchical.minCompressRangeChars | 整数 | 5000 | 值得折叠的最短历史片段,按字符计 |
compaction.hierarchical.minSummaryLength | 整数,不超过 maxSummaryLength | 50 | 模型所写摘要的最短长度,按字符计;更短的会被拒绝 |
compaction.hierarchical.maxSummaryLength | 整数 | 20000 | 摘要的最长长度;更长的会被拒绝 |
compaction.hierarchical.tiers | 布尔值 | true | 是否把较早的摘要分层再次提炼 |
compaction.hierarchical.protectedTools | 工具名数组 | [] | 结果从不被折叠的工具 |
compaction.hierarchical.messageTimestamps | 布尔值 | true | 每条消息的标签显示请求首次显示它时的本地时间,折叠的回复显示它覆盖的时间段;false 时不显示时间 |
compaction.hierarchical.absorb | 布尔值 | false | 4 000 个 token 及以上的工具结果要求模型用 absorb 提炼它;之后该结果离开请求 |
compaction.hierarchical.contentStore | 布尔值 | false | 4 000 个 token 及以上的工具结果在到达时被替换为占位符;acp_retrieve 返回原文 |
compaction.hierarchical.crush | 布尔值 | false | 在要求 absorb 之前,确定性地折叠大工具结果中的 JSON、代码和日志;只在 absorb 开启时 |
compaction.hierarchical.rules | 布尔值 | false | 模型用 acp_rule 记录持久的提醒,显示在每个请求的指令中 |
各策略:
"standard"同步压缩:上下文用到窗口的autoCompactThresholdPercent时(小窗口为给回复留出空间会更早)在轮次前或轮次中压缩,模型请求新上下文时、Provider 报告上下文窗口错误之后、/compact时也压缩。"background"还会在上下文用到窗口的compaction.background.thresholdPercent(低于autoCompactThresholdPercent)时于后台开始压缩:会话继续工作的同时,它压缩到当时为止已完成的轮次,结果在下一个请求之前安装,排在之后所做的工作之前。它运行期间,如果因为阈值、上下文窗口错误或/compact需要压缩,会等待它而不发送自己的请求;结果失败、已不适用或安装后上下文仍超过阈值时,按"standard"的方式同步压缩。不低于autoCompactThresholdPercent的值永远不会开始,日志会给出警告。autoCompactionEnabled = false也会关闭它。它的用量计入会话,从不计入轮次的预算。"hierarchical"让模型把自己的历史折叠成它写的摘要(源自 billion-context)。保存的历史从不改变:每个请求把折叠的片段显示为它们的摘要。模型得到一段常驻提示、五个工具(compress、decompress、search_context、acp_status、acp_cache),以及上下文变满时折叠的提醒(见maxContextLimitPercent、emergencyThresholdPercent和nudgeGrowthTokens三行);超过emergencyThresholdPercent时还会截短过大的工具输出。没有阈值压缩,也不使用autoCompactThresholdPercent。标准压缩在上下文窗口错误之后、/compact和请求新上下文时运行,以及上下文连续三个请求超过emergencyThresholdPercent且已没有可折叠或可截短的内容时运行;autoCompactionEnabled = false关闭其中两种自动的:错误之后的(与其他策略相同)和超过emergencyThresholdPercent的。上下文窗口未知时,既不提醒也不截短。它的表中每个键都生效。开启messageTimestamps时,每条消息的标签带有请求首次显示它时的本地时间(time="2026-11-09 09:00:00",显示后不再改变,所以请求的缓存前缀不受影响),折叠的回复写明它覆盖的时间段;开启之前已显示过的消息没有时间。模型的折叠在终端界面中显示为折叠的compress调用,/compression显示各个块及其节省的量(分层压缩)。可选功能在此之上加入内容,每个功能的工具只在它开启时提供:absorb(工具absorb;crush先折叠它能折叠的)、contentStore(工具acp_retrieve,它把原文内联返回,或者从 4 000 个 token 起写入会话的导出文件并给出路径;原文保存在会话的一个文件中,随会话删除)和rules(工具acp_rule)。四项都关闭时,请求与没有它们时相同。从它切换走的会话继续把已折叠的内容显示为摘要,直到下一次标准压缩。
每种策略都以标准压缩为底线:/compact、模型请求新上下文、上下文窗口错误之后的重试总是运行它。策略按会话生效:新会话采用它,已有会话在下一轮次或 /compact 时采用,子会话(子代理的、评审的)同样采用,但 "background" 且 childSessions = false 时子会话用 "standard";旁支对话(/side)总是用 "standard"。终端界面的 /config 可以选择它。无法使用的值取默认值;minSummaryLength 大于 maxSummaryLength 时两者都取下一层的值(在用户的文件中即默认值)。
模型元数据
| 键 | 类型和取值 | 默认值 | 含义 |
|---|---|---|---|
modelMetadata.discovery | "auto"、"off" | "auto" | Agent 是否自己在后台列出各 Provider 的模型,以得知每个模型报告的信息(它的上下文窗口) |
modelMetadata.modelsDev | true、false | false | Agent 是否下载 models.dev 的公开目录,以补上其他来源都没说的模型信息(models.dev)。打开后,本机大约每天向第三方 models.dev 发送一次请求 |
为 "auto" 时,Agent 启动时列出默认 Provider 的模型;此后每当在某个 Provider 上创建会话、选用它的模型或在它上面运行轮次时,列出该 Provider 的模型:每个 Provider 每天最多一次,列出失败后每 15 分钟最多一次。会话在列表记录下来时立即采用它报告的窗口,其余得知的信息在下一个轮次采用(上下文窗口与压缩)。没有什么会等待列表;失败的列出只是稍后再试。"off" 时 Agent 不自己列出;/model 和 /providers 的模型列表、Provider 的测试和 doctor --online 仍会列出,它们报告的信息也仍会保存。嵌入 Agent 的应用用同样的方式关闭它,写在它的 Agent 配置的 config.toml 里。
modelsDev 默认关闭,除非你打开它。打开后,Agent 在后台下载 https://models.dev/api.json(在启动时,以及会话绑定到某个 Provider 时,与模型发现相同,不论 discovery 的值),User-Agent 写明 Agent 及其版本,不含任何关于你的信息;下载成功后每天最多一次,失败后每 15 分钟最多一次。副本保存在数据目录的 model-metadata.json 中,使用一周;models.dev 无法访问或返回无法使用的内容时不提示,继续使用已保存的副本。关闭后,副本被丢弃。终端界面中的 /config modelMetadata 可以编辑这两个键。
网络
| 键 | 类型和取值 | 默认值 | 含义 |
|---|---|---|---|
network.proxy | "system"、"disabled",或代理 URL(http、https、socks4、socks4a、socks5、socks5h,可以带凭据) | "system" | 模型 Provider、网页工具、MCP、models.dev 的下载和 Agent 启动的进程使用的代理,见网络与日志 |
终端界面
| 键 | 类型和取值 | 默认值 | 含义 |
|---|---|---|---|
tui.fullscreenTranscript | 布尔值 | true | 终端界面在备用屏幕上自己绘制对话(Fullscreen);false 时对话写入终端的滚动历史(Scrollback)。启动时读取,/tui 会设置它 |
tui.alternateScreen | "auto"、"always"、"never" | "auto" | 界面是否可以使用备用屏幕;"auto" 在 SSH 会话中不使用。不能使用备用屏幕时,界面以 Scrollback 方式运行 |
tui.scrollbackMouse | "tail"、"off" | "tail" | Scrollback 在尾部显示控件时是否捕获鼠标,以便点击到达控件;滚轮第一次滚动后交还鼠标,直到下一个按键或条目。"off" 从不捕获 |
tui.agentsGrouping | "project"、"directory"、"status"、"model" | "project" | 命令中心的分组标题:项目(工作树的会话归入创建它的检出)、目录、状态或模型。在命令中心按 g 会设置它 |
tui.rawOutput | 布尔值 | false | 以对话内容的原始纯文本显示,便于用终端自己的选择复制;/raw 会设置它 |
tui.theme | 字符串 | 未设置 | 语法高亮主题:内置主题的名字,或数据目录 themes/ 下自定义的 名字.tmTheme;未设置时是 ansi。/theme 会设置它 |
tui.welcomeEnabled | 布尔值 | true | 在新的空会话中显示开屏形象,即时生效 |
tui.welcomeTheme | random、center、left_peek、right_sleep、right_read、lower_left | random | 每个新会话随机选择一次,或固定姿态及位置 |
tui.statusLine | 项目 ID 数组,每项可写作 id:place | ["model-with-reasoning", "background-tasks", "current-dir", "session-title"] | 状态栏的项目及顺序;[] 表示不显示(底栏显示 ? for shortcuts)。条目可写成 model:right-2 指定位置:第一行或第二行、左端或右端;只写 ID 时在第一行左侧。/statusline 会设置它 |
tui.statusLineColors | 布尔值 | true | 状态栏的项目是否使用主题的颜色 |
tui.statusLinePalette | id:color 列表 | [] | 状态栏各项目的颜色:model:cyan、context-window:#ff8800。颜色是十六个 ANSI 名称之一或 #rrggbb;没有条目的项目沿用主题的颜色 |
tui.statusLineOverflow | "wrap-all"、"wrap-left" 或 "truncate" | "wrap-all" | 一行放不下右侧的计数时底栏怎么做:两侧都换行、保留计数的行而把左侧换到它下面,或截断左侧 |
tui.terminalTitle | 项目 ID 数组 | ["activity", "session-title", "project-name"] | 终端标题的项目及顺序;[] 表示不修改终端标题。/title 会设置它 |
tui.rendering.tables | 布尔值 | true | 管道表格按列排版(太窄时为键值记录),回答中含表格的 ```md 围栏也一样;false 时按原样显示。对此后显示的内容生效 |
tui.rendering.lists | 布尔值 | true | 列表标记显示为 •,任务框为 ☐/☑;false 时按原样显示 - 和 [ ]/[x]。对此后显示的内容生效 |
tui.rendering.math | 布尔值 | true | $…$、\(…\)、$$…$$ 和 \[…\] 之间的数学公式以 Unicode 记号显示;false 时每个公式按原样显示。对此后显示的内容生效 |
tui.rendering.mermaid | 布尔值 | true | 已闭合的 ```mermaid 围栏在种类和大小允许时绘制成文本图表(否则显示说明和代码);false 时显示为代码。对此后显示的内容生效 |
tui.checkForUpdates | 布尔值 | true | 终端界面启动时最多每 20 小时向 GitHub 询问一次是否有更新的版本发布,并在会话信息框中显示;false 时不自动发送请求,也不显示缓存提示(HANAFUBUKI_AGENT_NO_UPDATE_CHECK 也一样)。启动时读取 |
tui.keymap.上下文.动作 | 按键字符串或其数组 | 各动作的默认按键 | 界面某个动作的按键(按键映射):"ctrl-t"、"ctrl-x ctrl-s"、"leader p";[] 取消绑定。/keymap 会设置它 |
tui.presets.N | 表:input(字符串)、label(字符串,可选) | 无 | N 号位置("0" 到 "9")的预设:像输入一样运行的内容,不能为空,最多 8000 字节,不能以 ! 开头。/presets 会设置它 |
[tui] 下的其他键保留在文件中,但会被忽略;statusLine 和 terminalTitle 中的项目,以及按键映射的上下文、动作和按键,界面不认识或无法使用的也会被忽略,每个都产生一条警告。配置档、项目配置或 -c 中的按键映射项或预设只替换用户文件中同一个动作或位置的设置,其他的保持不变。config set 只能以表的形式写入 tui.keymap 和 tui.presets,并与文件合并(config set tui.keymap '{ global = { open_transcript = "ctrl-q" } }'),不能写入它们下面的某个键。
logLevel、network.proxy 和 [tui] 只对独立运行的 Agent 有效;嵌入 Agent 的应用提供自己的日志、代理和界面。
配置档和项目
| 键 | 类型和取值 | 含义 |
|---|---|---|
profiles.名字 | 表,包含上面任何键 | -p 名字 选择的配置档 |
projects."路径".trustLevel | "trusted";其他值都表示不信任 | 是否读取这个项目的 .hanafubuki-agent/config.toml |
这两个只能写在用户的 config.toml 中。设置中心把它们作为 Profiles 和 Projects 集合(Advanced 标签页):可以添加配置档、设置或取消它的键、删除它(Agent 正在使用的那个(-p)除外);可以信任项目,或不再信任它("untrusted")。
钩子
| 键 | 类型和取值 | 含义 |
|---|---|---|
hooks.事件 | matcher 组的数组,[[hooks.PreToolUse]] | 事件 的钩子:PreToolUse、PostToolUse、SessionStart、UserPromptSubmit 或 Stop |
hooks.事件.matcher | 字符串;默认为空或 * | 组内钩子针对的工具名(或会话开始的来源) |
hooks.事件.hooks | 钩子数组:type = "command"、command,以及 commandWindows、timeout(秒,600)、statusMessage | 要运行的命令 |
用户的文件和被读取的项目文件都可以有它们,各自旁边的 hooks.json 也可以。它们不是设置:config get 和 config set 不处理它们,钩子的信任与启用状态也不是 config.toml 的键(见钩子)。设置中心的 Hooks 集合(Tools 标签页)显示每个钩子的定义,可以信任它、启用或停用它;钩子写在它的文件中。
插件
按插件 id(<插件>@<市场>)设置哪些已安装的插件启用。这些表来自 Codex,键名用 camelCase。
| 键 | 类型和取值 | 默认值 | 含义 |
|---|---|---|---|
plugins._default.enabled | true 或 false | 无 | 自身条目没有说明的包是否启用 |
plugins."插件@市场".enabled | true 或 false | 无 | 这个包是否启用 |
plugins."插件@市场".mcpServers.名字.enabled | true 或 false | 包的值 | 这个包的 MCP 服务器 名字 是否运行 |
plugins."插件@市场".mcpServers.名字.enabledTools | 工具名数组 | 包的值 | 只提供该服务器的这些工具,代替包的列表 |
plugins."插件@市场".mcpServers.名字.disabledTools | 工具名数组 | 包的值 | 不提供该服务器的这些工具,代替包的列表 |
plugins."插件@市场".settings | 表 | 无 | 包的代码的设置,按其清单的 configSchema 描述:它的访客的配置(plugins settings、/plugins、它在设置中心的分节) |
已安装的包默认启用,除非:它的市场被关闭(见下文),或它的条目写了 enabled = false,或它的条目没有说明而 _default.enabled 为 false。键不是插件 id 的条目保留在文件中,但和未知键一样被忽略。包的 MCP 服务器如何运行由包决定,mcpServers 只做限制(插件的服务器):它设置的键替换包的值(列表替换包的列表),两个列表都写了同一个工具的服务器会被略去,成为包的一个问题。Agent 写入的更改立即生效:它在每次写入设置之后重新加载包;手动编辑在下次启动时生效。plugins add(以及 /plugins 中的安装)写入 enabled = true,plugins enable 和 disable 只写 enabled,plugins remove 删除该条目(plugins)。settings 由 set_package_settings(plugins settings --set,以及 /plugins 中代码插件页面的 Settings 行)整体替换,它按清单的 configSchema 及其降低成的选项校验,并以新设置重启访客;不是表的值会被修复。这些选项本身也是设置,即 plugins."ID".settings.选项:/plugins 的选项表单(o)和设置中心 Plugins 标签页中该插件的分节把改动的键写在用户文件已有的设置之上,删除被重置的键,按同样的方式检查结果并重启访客;一次写入只包含一个插件的设置,不含其他内容;它们显示的每个值都来自用户的文件或默认值。config set plugins."ID".settings.选项 以同样的方式写入一个选项(为此会启动 Agent),拒绝选项不接受的值,也拒绝 settings 下的其他键。访客把它作为自己的配置和 settings 视图读取(代码插件),读取包时按这些选项检查:不符合其选项的键取选项的默认值,模式没有给出默认值时则被省略,同时产生包的问题和一条日志警告;越界的整数或数字被截取到边界。文件不会因此被改写(configSchema)。
设置中心在 [plugins] 之上有两个集合:Installed plugins(Plugins 标签页,/config packages)从 插件@市场 或目录安装,启用或停用包(enabled),更新它,重新加载它,信任它的钩子,卸载它并保留或删除它的数据;Plugins' MCP servers(Tools 标签页,/config pluginMcp)为启用的包运行的每个服务器提供一条记录(插件/服务器),显示它的连接阶段和工具,并把它的 enabled、enabledTools 和 disabledTools 写在 mcpServers.名字 下;取消某个字段(r)会删除它的键,于是包的值重新生效。
市场
按名字列出你添加的市场:Agent 从这里找到它们的包。
| 键 | 类型和取值 | 含义 |
|---|---|---|
marketplaces.名字.sourceType | "git" 或 "local" | 来源类型;必填 |
marketplaces.名字.source | 字符串 | git URL,或本地市场的目录;必填 |
marketplaces.名字.ref | 字符串 | git 市场检出的分支、标签或提交 |
marketplaces.名字.sparsePaths | 路径数组 | git 市场只检出这些路径 |
marketplaces.名字.lastUpdated | RFC 3339 时间 | 最近一次添加或升级的时间 |
marketplaces.名字.lastRevision | git 修订 | 检出的修订 |
marketplaces.名字.enabled | true 或 false;true | 为 false 时关闭它的所有包,不管 [plugins] 怎么写 |
plugins marketplace add、upgrade 和 remove 写入这些条目(plugins)。git 市场检出在数据目录的 plugins/marketplaces/名字/ 中;本地市场在原处读取。没有可用的 sourceType 和 source 的条目保留在文件中,但被忽略。两个表可以写在任何一层,config get 和 config set 能处理它们的键(config set plugins."demo@my-mkt".enabled false);-c 覆盖不能给键加引号,所以只能指定名字中没有点的包(-c plugins.demo@my-mkt.enabled=false)。设置中心的 Marketplaces 集合(Plugins 标签页)添加、升级、移除、启用和停用市场;添加 Git 市场时也能填写 sparsePaths。同一标签页的 Installed plugin defaults 编辑 plugins._default.enabled。这两类启用状态的改动都会重新加载已安装插件;市场关闭仍优先于插件自己的开关。
插件选项
编译进 Agent 的插件(以及宿主的插件)的选项,按插件名、再按选项:[pluginOptions.名字]。插件的描述符说明它接受哪些选项,以及它们的种类、界限和默认值;/plugins 用表单显示它们(o),设置中心把它们显示为 Plugins 标签页中该插件自己的分节(/config pluginOptions.名字)。
| 键 | 类型和取值 | 默认值 | 含义 |
|---|---|---|---|
pluginOptions.execution.commandTimeoutMinutes | 整数,1 到 1440 | 10 | 命令从启动起最多运行多久就被停止(分钟):每次 exec_command 运行,包括模型的、子代理的、它们留下的后台终端以及 ! 命令;! 命令在工具超时或宿主配置的回合期限更短时先被它们停止;也限制后台终端使会话和 exec 等待的时长 |
pluginOptions.execution.environmentInherit | all, core, none, unfiltered | "all" | 环境继承范围;unfiltered 继承全部变量并跳过过滤,仍允许显式赋值及功能自动补充 |
pluginOptions.execution.environmentIgnoreDefaultExcludes | 布尔值 | true | 保留继承的 KEY/SECRET/TOKEN 变量,false 启用默认过滤 |
pluginOptions.execution.environmentExclude | 字符串数组 | [] | 不区分大小写的排除模式 |
pluginOptions.execution.environmentSet | 字符串数组 | [] | 保留过滤之前应用的 NAME=VALUE 显式覆盖 |
pluginOptions.execution.environmentIncludeOnly | 字符串数组 | [] | 只保留匹配名称;空数组不做过滤 |
pluginOptions.execution.shellUseProfile | 布尔值 | false | 省略 login 或传入 null 时是否加载 PowerShell Profile;保留 UTF-8 初始化 |
pluginOptions.execution.shellSnapshot | 布尔值 | true | 按会话在内存中缓存登录 POSIX Shell 的启动状态 |
pluginOptions.subagents.maximumRunningAgents | 整数,1 到 16 | 8 | 主对话整棵树中同时工作的子代理数,包括等待自己子代理的父代理 |
pluginOptions.subagents.defaultWaitSeconds | 整数,10 到 300 | 30 | 模型没有给出超时时 wait_agent 等多久,取到最短与最长之间 |
pluginOptions.subagents.minimumWaitSeconds | 整数,10 到 300 | 10 | wait_agent 接受的最短超时;高于最长超时时取为最长超时 |
pluginOptions.subagents.maximumWaitSeconds | 整数,10 到 300 | 300 | wait_agent 接受的最长超时 |
[pluginOptions.execution]
commandTimeoutMinutes = 60
environmentInherit = "all"
environmentExclude = ["PRIVATE_*"]
environmentSet = ["APP_MODE=development"]
[pluginOptions.subagents]
maximumRunningAgents = 4
defaultWaitSeconds = 60这个表按插件和键跨层合并,就像 [plugins] 按条目合并:某层设置的键替换下层的,其余键保留。每个键单独读取:类型不对的值,或不合适的文本,取选项的默认值;越界的整数被截取到边界;两者都会产生一条警告,指明层、插件和键(/warnings,以及 /plugins 中该插件的选项)。插件不接受的键保留在文件中但被忽略,并有一条警告;插件没有选项的表没有意义,就像 disabledPlugins 中的未知名字。写入是严格的:config set pluginOptions.名字.键 值、设置中心、选项表单以及门面的 write_setting_values 和 set_plugin_options 按插件的选项检查每个值,在写入任何内容之前带着原因拒绝不合适的值;config get pluginOptions.名字.键 打印各层解析出的值,没有设置时打印默认值。设置中心的 Profiles 和 Configuration layers 集合也能编辑配置档及受信任项目文件中的已注册插件选项(写入设置)。Agent 写入的更改立即生效:execution 就地接受新的命令超时、环境选择和 Shell 启动选项,作用于此后启动的命令;正在运行的命令保留启动时的设置(环境);subagents 就地接受新的运行中代理上限,对新的等待界限则重新启动,它运行的子代理继续运行。web 插件在 [pluginOptions.web] 下提供引擎、研究与抓取选项;原有顶层 Web 设置继续承担宿主限制及网络/抓取策略。
角色
某一层定义的角色,按名字:[agents.名字],键与角色文件相同(键)。
| 键 | 类型和取值 | 含义 |
|---|---|---|
agents.名字 | 角色的键组成的表 | 角色 名字 |
agents.名字.configFile | 路径,相对于本文件所在的文件夹 | 一个角色文件,条目的键覆盖在它的键之上读取(Codex 的 config_file);agents/ 不会再读这个文件 |
profiles.配置档.agents | 角色组成的表,同 agents | 配置档 配置档 的角色 |
用户的文件、其中的配置档以及受信任项目的文件都可以写。它们不跨层合并:较高层的角色整体替换下一层的同名角色(角色的来源)。它们不是设置:config get 和 config set 不处理它们,-c agents.… 覆盖是未知的键,其中无法使用的内容是角色的问题(roles list、doctor、/warnings),从不会修复文件。设置中心的 Roles 集合(Model 标签页)添加、逐键编辑和删除用户文件中的条目(description、instructions、instructionsMode、model、reasoningEffort、spawnable);收窄角色的键,以及角色文件、配置档、项目和插件中的角色,都写在它们自己的文件中。
providers.toml
providers.toml 没有分层,只有自己可读。通常用 providers 命令修改;终端界面的 /providers(设置中心的 Provider)可以编辑 Provider,/providers policy 可以编辑共享的模型策略,设置中心的 Model overrides(/config providerModels)可以编辑模型自己的设置;也可以直接编辑文件。修改时请先退出正在运行的 Agent。
revision = 2
defaultProviderId = "provider-1"
[modelPolicy]
model = "gpt-5.1"
reasoningEffort = "medium"
autoCompactionEnabled = true
autoCompactThresholdPercent = 80
remoteCompaction = "disabled"
[modelPolicy.inputCapabilities]
imageInput = "auto"
[[providers]]
id = "provider-1"
displayName = "OpenAI"
enabled = true
protocol = "responses"
baseUrl = "https://api.openai.com/v1"
apiToken = "sk-..."
requestHeaders = []顶层
| 键 | 类型 | 含义 |
|---|---|---|
revision | 整数 | 每次修改加一,由 Agent 维护 |
defaultProviderId | 字符串,可选 | 默认 Provider 的 ID,必须是一个启用的 Provider |
[modelPolicy]
模型策略对所有 Provider 生效。
| 键 | 类型和取值 | 默认值 | 含义 |
|---|---|---|---|
model | 字符串,最多 256 字节 | "" | 新会话使用的模型 |
reasoningEffort | "minimal"、"low"、"medium"、"high"、"xhigh" 或其他由 1–64 个 ASCII 字母、数字、-、_ 或 . 组成的标识 | 未设置 | 推理强度,每种协议都会发送(例如 max 属于其他标识;none 会被拒绝:不设置即使用 Provider 的默认值)。请求发送模型目录所列档位中最接近的一个,已知不接受推理的模型则不发送。设置中心提供该模型已知的档位、Default 和 Custom(手动输入),与 /effort 相同(推理强度与思考过程) |
inputCapabilities.imageInput | "auto"、"disabled" | "auto" | 是否向模型发送图片:"auto" 发送,除非已知模型不读图或模型自己的 imageInput 另有设置(图片);"disabled" 从不发送 |
contextWindowTokens | 正整数 | 未设置 | 模型的上下文窗口,除非模型自己设置了一个(见下);未设置时取从 Provider 对过长请求的拒绝中学到的更小窗口、Provider 的模型列表报告的值(除非 modelMetadata.discovery = "off",否则自动列出)、models.dev 给出的值(打开时),或内置表中的值(上下文窗口与压缩) |
autoCompactionEnabled | 布尔值 | true | 是否自动压缩上下文 |
autoCompactThresholdPercent | 整数,1–100 | 80 | 上下文用到窗口的这个百分比时自动压缩;剩下的部分容不下一次回复时更早(上下文窗口与压缩) |
remoteCompaction | "disabled"、"responses_compact"、"responses_compact_v2" | "disabled" | 用 Responses 的远程压缩代替本地摘要 |
turnBudget | 表 | 未设置 | 回合的限制,见下文 |
[modelPolicy.turnBudget] 是可选表。累计用量限制和重复步骤检查默认不设置;省略对应键即不启用。写入此表时,下列其余五个键必须提供。设置的限制必须是正整数。累计限制不再设置额外上限,范围由整数类型决定(u64,重复步骤阈值为 u32)。
设置中心通过 Model policy → Custom turn budget 提供这些字段。累计限制显示未设置时表示不限制;在该字段按 r 可重置。每个新回合开始前都会应用当前设置,恢复已保存的对话后也一样。用户明确配置的限制仍然有效。
| 键 | 默认值 | 上限 | 含义 |
|---|---|---|---|
maximumCumulativeModelInputTokens | 未设置 | 无 | 一个回合所有请求累计的输入 token |
maximumCumulativeModelOutputTokens | 未设置 | 无 | 一个回合所有请求累计的输出 token |
maximumToolInvocations | 未设置 | 无 | 一个回合的工具调用次数 |
maximumToolOutputBytes | 未设置 | 无 | 一个回合的工具输出累计字节数 |
maximumHookFragmentBytes | 未设置 | 无 | 插件钩子注入的累计字节数 |
maximumPendingInputItems | 64 | 1024 | 等待处理的补充消息数 |
maximumInFlightTools | 8 | 64 | 同时运行的工具调用数 |
maximumConsecutiveStalledSteps | 未设置 | 无 | 重复采样步骤数;轮询可能重复调用但返回不同结果,因此默认关闭 |
modelStreamIdleTimeoutSeconds | 120 | 86400 | 模型响应流多久没有数据算超时 |
toolIdleTimeoutSeconds | 600 | 86400 | 工具多久没有进展算超时 |
approvalTimeoutSeconds | 900 | 86400 | 审批最长等待时间 |
[[providers]]
不限制 Provider 数量。读取文件时保留全部有效条目,不会因数量较多而触发配置修复。批量查询模型列表时,最多同时请求 32 个 Provider,其余依次等待。
| 键 | 类型和取值 | 含义 |
|---|---|---|
id | 1–64 个字母、数字、_ 或 - | Provider 的 ID;providers add 分配最小的空闲 provider-N |
displayName | 1–128 字节 | 显示名称 |
enabled | 布尔值 | 是否启用 |
protocol | "responses"、"chat_completions"、"anthropic_messages" | 协议,见 Provider 与模型 |
baseUrl | http 或 https URL,不含凭据、查询和片段 | 接口地址,协议的路径追加在它后面 |
apiToken | 字符串,可选 | API 令牌,原样保存 |
requestHeaders | { name, value } 的数组,最多 32 个 | 附加到每个请求的请求头;不能设置 Authorization、x-api-key、anthropic-version、Host、Content-Type 等由 Agent 管理的请求头 |
models | 以模型 ID 为键的表,每项是一个表(见下),可省略 | 为该 Provider 的每个模型设置的内容 |
默认 Provider 被删除或禁用时,默认改为列表中第一个启用的 Provider。
[providers.models."ID"]
模型自己的设置,以模型 ID 为键(1–256 字节;需加引号)。它们优先于 Provider 的模型列表报告的信息和 Agent 从拒绝中学到的信息,对这个模型也优先于策略的 contextWindowTokens(按模型的设置)。每个键都可省略。
[providers.models."qwen3-coder"]
contextWindowTokens = 262144
maxOutputTokens = 65536
imageInput = "unsupported"
reasoningEfforts = []| 键 | 类型与取值 | 含义 |
|---|---|---|
contextWindowTokens | 正整数 | 模型的上下文窗口 |
maxOutputTokens | 正整数 | 模型的最大输出 |
imageInput | "auto"(默认)、"supported"、"unsupported" | 是否向它发送图片:按已知信息、总是(拒绝仍会让那次请求回退)、从不;策略的 inputCapabilities.imageInput = "disabled" 仍然优先 |
reasoningEfforts | "minimal"、"low"、"medium"、"high"、"xhigh" 或其他标识符组成的数组;或 [] | 它接受的档位,取代模型列表列出的档位;[]:不接受推理参数 |
每个键各自回退:无法使用的键(窗口为 0、推理强度列表中含 none)会被略去并记为一次修复,不是表的条目会被丢弃,Provider 保留。会话在下一个轮次采用它们。providers 命令和设置中心中 Provider 的记录会原样保留它们;设置中心的 Model overrides 集合(Model 标签页,每个 PROVIDER/MODEL 一条记录)添加、编辑、取消和删除它们,每次写入都基于文件的 revision。
mcp.toml
mcp.toml 没有分层,只有自己可读。mcp add 写入新服务器的默认值;终端界面的 /mcp(设置中心的 MCP servers 和 MCP secrets)可以编辑服务器、凭据、协议模式和按工具的策略,也可以直接编辑文件。
revision = 3
[[servers]]
id = "github"
callTimeoutSeconds = 300
[servers.transport]
type = "stdio"
program = "github-mcp-server"
argv = ["stdio"]
[servers.transport.publicEnvironment]
GITHUB_TOOLSETS = "repos,issues"
[servers.transport.credentialEnvironment]
GITHUB_PERSONAL_ACCESS_TOKEN = "github-token"
[servers.toolApprovalPolicies]
get_issue = "allow"
[credentials.github-token]
value = "ghp_..."
generation = 1revision 每次修改加一,和 providers.toml 一样;由 Agent 维护。
[[servers]]
最多 64 个。服务器没有写出的键取最后一列的值,即 mcp add 和设置中心为新服务器写入的值;Agent 写入服务器时会写出每个键。只有 id、transport 及其 type,以及 stdio 传输的 program 或 HTTP 传输的 url 没有默认值:缺少其中之一,或某个值不是该键的类型的服务器会被丢弃,记为一次修复(配置恢复)。
| 键 | 类型和取值 | 默认值 | 含义 |
|---|---|---|---|
id | 1–128 个字母、数字、-、_、. | 服务器 ID;ID 不符合要求的服务器会被丢弃 | |
enabled | 布尔值 | true | 是否启用;启用的服务器在 Agent 启动时连接 |
required | 布尔值 | false | 必需的服务器:它的工具无法使用时,这一步失败 |
protocolMode | "legacy"、"v20260728" | "legacy" | MCP 协议版本 |
transport | 表,见下文 | 传输方式 | |
connectTimeoutSeconds | 1–86400 | 15 | 连接超时 |
initializeTimeoutSeconds | 1–86400 | 30 | 初始化超时 |
listTimeoutSeconds | 1–86400 | 30 | 列出工具的超时 |
callTimeoutSeconds | 1–86400 | 120 | 工具调用超时 |
shutdownTimeoutSeconds | 1–86400 | 10 | 关闭超时 |
maximumConcurrentCalls | 1–64 | 4 | 同时进行的调用数 |
toolMaximumConcurrentCalls | 工具名到 1–64 的表 | {} | 单个工具的并发上限 |
enabledTools | 工具名的数组 | [] | 只开放这些工具;空数组表示全部 |
disabledTools | 工具名的数组 | [] | 不开放这些工具 |
approvalPolicy | "allow"、"ask"、"deny" | "ask" | 工具调用是否需要审批,见 MCP |
toolApprovalPolicies | 工具名到审批策略的表 | {} | 单个工具的审批策略 |
exposurePolicy | "direct"、"direct_model_only"、"deferred"、"hidden" | "deferred" | 工具如何提供给模型 |
toolExposurePolicies | 工具名到暴露策略的表 | {} | 单个工具的暴露策略 |
工具过滤列表和逐工具策略表不限制条目数量。工具名称、策略值和逐工具并发值仍会校验;同一个工具不能同时出现在启用和禁用列表中。
数值超出范围时会被调整到范围内。
transport 的 type = "stdio":
| 键 | 含义 |
|---|---|
program | 程序,必需:绝对路径,或在 PATH 中查找的程序名 |
argv | 参数数组,省略时为空 |
cwd | 工作目录,可选 |
environmentVariables | 额外从 Agent 进程继承的变量名,默认空数组 |
publicEnvironment | 环境变量名到值的表,省略时为空 |
credentialEnvironment | 环境变量名到凭据键的表,省略时为空,值从 [credentials] 中读取 |
transport 的 type = "streamable_http":
| 键 | 含义 |
|---|---|
url | 必需:http 或 https URL,不含凭据和片段 |
publicHeaders | 请求头名到值的表,省略时为空 |
credentialHeaders | 请求头名到凭据键的表,省略时为空,值从 [credentials] 中读取 |
oauth | "disabled"(默认值)、"optional"、"required";不能和 Authorization 请求头同时使用 |
[credentials]
| 键 | 含义 |
|---|---|
credentials.键.value | 凭据的值,原样保存 |
credentials.键.generation | 正整数,修改值时加一,让 Agent 知道凭据变了 |
凭据键由 1–128 个字母、数字、.、_、- 组成。服务器引用了不存在的凭据时无法连接。
Advisor 选项
以下选项位于 [pluginOptions.advisor],内置插件默认未激活。
| 键 | 作用 |
|---|---|
provider、model、reasoningEffort | 主 Advisor 的提供商、模型及可选推理强度。 |
fallbackProvider、fallbackModel、skipSameModel | 可选备用路由。默认跳过与 Executor 相同的模型路由。 |
activationScope、active | 选择持久或会话激活,持久激活标志默认为关闭。 |
executorProvider、executorModel、executorEffort、executorModels | 显式激活主会话时固定执行模型和强度,或限定允许的 provider/model。允许列表为空时接受全部。 |
historyChars、gitChars、gitContext | 历史默认 15,000 字符。Git 默认关闭。摘要提供路径和状态,完整模式包含差异。Git 默认最多 20,000 字符,同时受历史预算一半的约束。 |
summaryTools、excludedTools、redactSecrets | 按工具展示名称选择只提供摘要或完全排除的工具调用及结果。可选脱敏会处理外发文本中常见的凭证模式。 |
projectRules、trackedFiles、untrackedFiles、shareImages | 均默认关闭。可信项目可包含规则和偏好。传递受版本管理的文件需要前一次 Advisor 回复点名,未跟踪文件需在当前请求明确列出。 |
simple、reviewStages、repeatThreshold、gateFailure | 仅自愿咨询模式、审查时机或自定义引导、可选重复阈值和失败策略(告警、阻止工具或阻止本会话)。 |
consultationLimit、scout、recordOutcomes | 默认无次数上限。显式预算中一次咨询及其回退合计一次。Scout 和本地反馈记录分别由用户开启。 |
开启 useModelWindow 后根据选定 Advisor 的已知窗口读取历史;窗口未知时使用 historyChars。关闭 useModelWindow 并将 historyChars 设为零即可省略会话历史。两个可选整数支持重置,分别恢复不限咨询次数和关闭重复调用审查。