Skip to content

amux 配置参考 ​

本文档覆盖 ~/.amux/config.toml 中由 amux 代码读取的配置。通用配置元数据位于公共核心的 internal/config/reference.go,发行版通过扩展接口注册自己的配置元数据。修改配置键、默认值或约束时应同步修改所属 module 的元数据,并在相应 module 中运行 make config-doc。scripts/check.sh 会检查遗漏和生成文件漂移。

常用命令:

bash
amux system config path
amux system config get <key>
amux system config set <key> <value>
amux system config unset <key>

“CLI 可管理”专指通用 amux system config set/get/unset;标为“否”的键可能由说明中列出的专用命令管理,否则需要直接编辑 TOML。Profile 键中的 <profile> 替换为实际飞书智能体 Profile 名;Provider 键中的 <provider> 只支持 codex。敏感值不会在本文档中给出示例。

Agent ​

配置键类型默认值约束CLI 可管理说明
adapter.codex.executable字符串codex程序名称、绝对路径或 ~/ 路径;不是 shell 命令是Codex 启动程序;留空使用 codex。在执行节点解析,保存并重启后用于新会话及模型发现。

Runtime 清理 ​

配置键类型默认值约束CLI 可管理说明
maintenance.daily_cleanup.enabled布尔值true—是每日自动清理普通话题和用户隔离话题的运行数据,并向 Bot 管理员私聊报告结果;系统级开关,保存后即时生效。
maintenance.daily_cleanup.at字符串06:17HH:MM是每日清理时间,使用 Hub 本地时区;错过时间后在恢复运行时补一次。
maintenance.daily_cleanup.protected_paths字符串数组[]absolute paths是每日清理始终保留的共享或长期工作区绝对路径,作用于所有 Runtime。
runtime.task_cleanup.enabled布尔值true—否是否自动清理终态 task 历史。
runtime.task_cleanup.terminal_history_ttl_seconds整数秒数604800(7 天)>0否终态 task 历史保留时间。
runtime.task_cleanup.sweep_interval_seconds整数秒数3600>0否终态 task 清理扫描周期。
runtime.broker_reap.enabled布尔值true—否是否定期回收孤儿 session broker 进程及其文件(session 已删除或不再运行、或为重复 broker)。
runtime.broker_reap.sweep_interval_seconds整数秒数300>0否孤儿 broker 回收扫描周期。

飞书实验功能 ​

配置键类型默认值约束CLI 可管理说明
bridge.feishu.group_settings.enabled布尔值false—是群独立配置实验总开关,影响本实例全部助手;关闭时保留群设置和会话,已配置独立策略的群暂停新任务,未配置群和私聊沿用助手设置。修改后重启生效。
bridge.feishu.presentation.completion_notification_enabled布尔值false—是长会话完成通知实验总开关,影响本实例全部助手;关闭时不新增成功、等待补充或失败提醒。修改后重启生效。
bridge.feishu.experimental.steer_foreground布尔值false—是前台协调/忙时注入实验总开关:开启后,任务执行中同一发送者的追加消息注入当前回合(不再中断重来),单例和话题会话注入前台/后台协调说明(首轮及每 20 轮);关闭时忙时消息沿用中断并重新提交。环境变量 AMUX_FEISHU_BUSY_INPUT=interrupt 可强制关闭注入。修改后重启生效。
bridge.feishu.experimental.show_background_tasks布尔值false—是后台任务进度卡片实验开关:开启后,飞书会话发起的每个后台任务(子任务 / 后台 Agent 实例)单独发送实时进度卡片;默认关闭,后台过程不发卡片,由前台 Agent 汇报结果。可在飞书实验功能卡片中切换,保存后立即生效。
memory.enabled布尔值false—是Agent 记忆实验总开关,由 Hub 统一控制所有 Runtime,无需 Agent Profile;非隔离时全局共享,用户隔离时按有效 Principal 保存。关闭阻止读写并保留文件,已有会话保留原生记忆抑制。修改后重启生效。

Hub 与调度 ​

配置键类型默认值约束CLI 可管理说明
hub.addr字符串127.0.0.1:7100host:port是amuxd hub 地址。
hub.token字符串敏感值,不展示—是Hub 与 runtime 共享鉴权令牌。
hub.allowed_targets字符串数组[]—是允许注册到 hub 的 target ID 白名单;空表示不限制。

Runtime ​

配置键类型默认值约束CLI 可管理说明
runtime.id字符串主机名—是Runtime 稳定标识。
runtime.name字符串runtime.id—是Runtime 展示名称。
runtime.auto_start布尔值false—是安装或系统启动时是否自动启动 runtime。
runtime.idle_timeout_seconds整数秒数00 或 >=60是旧版默认休眠阈值;新配置优先使用 runtime.session_reclaim。
runtime.max_sessions整数100(runtime 应用)>=0是整机并发 Session 上限;0 由 runtime 使用默认值。
runtime.max_concurrency整数10(runtime 应用)>=0是每种 Agent 的并发上限;0 由 runtime 使用默认值。
runtime.labels.<label>字符串映射项无—是调度标签,例如 pool、repo_cache。

Session 回收 ​

配置键类型默认值约束CLI 可管理说明
runtime.session_reclaim.enabled布尔值true—否Session 分阶段回收总开关。
runtime.session_reclaim.sweep_interval_seconds整数秒数600>0否Session 回收扫描周期。
runtime.session_reclaim.local.sleep_after_seconds整数秒数00 或 >=60否本地 Session 自动休眠阈值。
runtime.session_reclaim.local.archive_after_seconds整数秒数00 或 >=60否本地 Session 自动归档阈值。
runtime.session_reclaim.local.prune_after_seconds整数秒数00 或 >=60否本地 Session 自动删除阈值。
runtime.session_reclaim.feishu.sleep_after_seconds整数秒数172800(48 小时)0 或 >=60否飞书 Session 自动休眠阈值。
runtime.session_reclaim.feishu.archive_after_seconds整数秒数00 或 >=60否飞书 Session 自动归档阈值;默认关闭,显式正值可开启。
runtime.session_reclaim.feishu.prune_after_seconds整数秒数00 或 >=60否飞书 Session 自动删除本地记录与 replay 的阈值;默认关闭,显式正值可开启,不会删除飞书消息。

CLI 与 MCP ​

配置键类型默认值约束CLI 可管理说明
cli.default_target字符串local—是CLI 默认 target。
mcp.enabled布尔值true—是是否启用内置 amux MCP。
mcp.auto_inject布尔值true—是是否向普通 run Session 自动投影内置 MCP。

隔离执行 ​

配置键类型默认值约束CLI 可管理说明
isolation.global_envKEY=VALUE 字符串数组敏感值,不展示合法且不重复的环境变量名否注入所有 identified 隔离 execution 的 installation-level 共享环境;使用 isolation global-env 命令管理,同名显式 launch env 优先,修改后需重启 system。

飞书基础 ​

配置键类型默认值约束CLI 可管理说明
bridge.feishu.notify_chat_id字符串空—是兼容用飞书通知群 ID。
bridge.feishu.prompt.shared_thread_enabled布尔值false—是是否把共享 thread 历史注入 Prompt。
bridge.feishu.prompt.topic_root_enabled布尔值true—是是否在新话题首轮注入根消息。
bridge.feishu.prompt.shared_thread_template_file路径空—是共享 thread Prompt 模板文件。
bridge.feishu.document_comments.enabled布尔值false—是云文档评论入口安装级开关。
bridge.feishu.presentation.thinking_process枚举collapsedexpanded、collapsed、hidden是安装级处理过程展示方式;Profile 未显式配置时继承。
bridge.feishu.presentation.completion_notification_after_seconds整数秒数60>=0;0 禁用本功能全部私聊提醒是普通任务成功、等待补充或失败且耗时达到阈值后,向当前轮发起人发送可跳回原话题的私聊卡片,不在话题内追加通知;不判断已读状态,智能体自动触发不提醒。

智能体协作 ​

配置键类型默认值约束CLI 可管理说明
bridge.feishu.bot_to_bot.enabled布尔值false—是是否接收 shared workspace 群内外部智能体的结构化显式 @。
bridge.feishu.bot_to_bot.max_turns_per_thread整数10>0是每个群话题可接受的智能体协作轮数上限。

群值守 ​

配置键类型默认值约束CLI 可管理说明
bridge.feishu.group_watch.enabled布尔值false—是群值守安装级开关;允许有正文或有效图片、文件、合并转发素材的根消息自动触发。
bridge.feishu.group_watch.chat_ids字符串数组[]—是允许自动触发的群 chat_id。
bridge.feishu.group_watch.sender_types字符串数组[user, app]user、app是允许自动触发的消息发送者类型。
bridge.feishu.group_watch.chat_sender_types.<chat_id>字符串数组继承 sender_typeschat_id 必须也在 chat_ids 中;值为 user、app是指定单个值守群允许自动触发的发送者类型;未配置的群使用 sender_types。
bridge.feishu.group_watch.poll_interval_seconds整数秒数155-300是其它 App 消息的历史补偿轮询周期。
bridge.feishu.group_watch.lookback_seconds整数秒数605-3600 且不小于轮询周期是历史补偿回看窗口。
bridge.feishu.group_watch.dedup.enabled布尔值false—是是否在创建 Session 和回复卡片前抑制同群内 App 发送的重复报警。
bridge.feishu.group_watch.dedup.window_seconds整数秒数1800(30 分钟)60-86400是App 报警语义去重窗口,从上一次允许创建 Session 的同类报警开始计算;按发送 App、Rule ID 与标题(提取不到时按规范化可见内容)生成指纹。
bridge.feishu.group_watch.max_active_sessions_per_chat整数501-500是当前智能体每个值守群允许的群值守活跃 Session 上限。
bridge.feishu.group_watch.idle_timeout_seconds整数秒数10800(3 小时)60-604800是群值守新 Session 的自动休眠阈值。
bridge.feishu.group_watch.thinking_process枚举collapsedexpanded、collapsed、hidden是安装级群值守处理过程展示方式。

飞书 Workspace 默认值 ​

配置键类型默认值约束CLI 可管理说明
bridge.feishu.workspace_defaults.agent字符串builtin/codex—是新 workspace 的默认 Agent Profile。
bridge.feishu.workspace_defaults.target字符串空(自动选择)—是新 workspace 的默认 target。
bridge.feishu.workspace_defaults.cwd路径空—是旧兼容 cwd;自然入口仍使用独立空 workspace。
bridge.feishu.workspace_defaults.model字符串空—是新 workspace 的默认模型覆盖。
bridge.feishu.workspace_defaults.args字符串数组[]—是新 workspace 的默认 Agent 参数。
bridge.feishu.workspace_defaults.idle_timeout_seconds整数秒数00 或 >=60是新 workspace Session 的休眠阈值。
bridge.feishu.claude_models字符串数组[]—是飞书模型选择器为 Claude 运行引擎额外列出的模型名,按声明顺序追加在内置 opus、sonnet、haiku 之后,便于选择最新模型。修改后重启生效。

飞书智能体 Profile ​

配置键类型默认值约束CLI 可管理说明
bridge.feishu.profiles.<profile>.workspace_defaults.agent字符串继承安装级—是Profile 级 workspace 默认专家。
bridge.feishu.profiles.<profile>.workspace_defaults.target字符串继承安装级—是Profile 级 workspace 默认 target。
bridge.feishu.profiles.<profile>.workspace_defaults.cwd路径继承安装级—是Profile 级兼容 cwd。
bridge.feishu.profiles.<profile>.workspace_defaults.model字符串继承安装级—是Profile 级 workspace 默认模型。
bridge.feishu.profiles.<profile>.workspace_defaults.args字符串数组继承安装级—是Profile 级 workspace 默认参数。
bridge.feishu.profiles.<profile>.workspace_defaults.idle_timeout_seconds整数秒数继承安装级0 或 >=60是Profile 级 workspace 休眠阈值。
bridge.feishu.profiles.<profile>.interaction.mode枚举threadthread、singleton是未保存群独立设置时的消息处理方式;群值守要求对应群的有效模式为 thread。
bridge.feishu.profiles.<profile>.presentation.thinking_process枚举继承安装级(collapsed)expanded、collapsed、hidden是当前助手普通任务的处理过程展示方式。
bridge.feishu.profiles.<profile>.presentation.completion_notification_after_seconds整数秒数继承安装级(60)>=0;0 禁用本功能全部私聊提醒是当前助手普通任务的完成提醒阈值。
bridge.feishu.profiles.<profile>.bot_e2e.sender_open_ids字符串数组[]—是允许通过 @Bot /e2e 发起 owner-authorized 测试输入的 Bot/App sender open_id。
bridge.feishu.profiles.<profile>.bot_e2e.sender_rolesmap[string]string{}owner、shared是把受信测试 Bot sender open_id 映射到其 /e2e 请求投影身份(owner 或 shared);不提供 unauthorized,未命中保持 owner。
bridge.feishu.profiles.<profile>.document_comments.enabled布尔值继承安装级—是Profile 级云文档评论开关。
bridge.feishu.profiles.<profile>.document_comments.agent_profile_ref字符串空(继承助手)—是云文档评论新 Session 使用的专家。
bridge.feishu.profiles.<profile>.document_comments.runtime_ref字符串空(继承助手或兼容旧配置)—是云文档评论新 Session 使用的运行引擎。
bridge.feishu.profiles.<profile>.document_comments.model_ref字符串空(运行引擎默认)—是云文档评论新 Session 使用的模型,按所选运行引擎校验;未覆盖运行引擎时遵循专家模型策略,未声明 supported_models 则允许原生模型名。
bridge.feishu.profiles.<profile>.document_comments.reasoning_effort字符串空(运行引擎默认)—是云文档评论新 Session 使用的思考强度。
bridge.feishu.profiles.<profile>.bot_to_bot.enabled布尔值继承安装级—是Profile 级智能体协作开关。
bridge.feishu.profiles.<profile>.bot_to_bot.max_turns_per_thread整数继承安装级(10)>0是Profile 级单话题智能体协作轮数上限。
bridge.feishu.profiles.<profile>.group_watch.chat_settings.<chat_id>.enabled布尔值true—是本群值守开关,与群值守总开关同时开启才接收自动任务。
bridge.feishu.profiles.<profile>.group_watch.chat_settings.<chat_id>.agent_profile_ref字符串空(继承本群普通会话)—是本群值守专家;空值使用本群普通会话的执行配置。
bridge.feishu.profiles.<profile>.group_watch.chat_settings.<chat_id>.runtime_ref字符串空(继承本群普通会话)—是本群自定义值守的运行引擎;自定义专家时必填。
bridge.feishu.profiles.<profile>.group_watch.chat_settings.<chat_id>.model_ref字符串空(运行引擎默认)—是本群值守模型,按所选运行引擎校验。
bridge.feishu.profiles.<profile>.group_watch.chat_settings.<chat_id>.reasoning_effort字符串空(运行引擎默认)—是本群值守思考强度,按所选运行引擎和模型校验。
bridge.feishu.profiles.<profile>.group_watch.chat_settings.<chat_id>.thinking_process枚举继承群值守默认值expanded、collapsed、hidden是本群值守任务的处理过程展示方式。
bridge.feishu.profiles.<profile>.group_watch.chat_settings.<chat_id>.max_active_sessions_per_chat整数继承群值守默认值1-500是本群值守活跃 Session 上限。
bridge.feishu.profiles.<profile>.group_watch.chat_settings.<chat_id>.idle_timeout_seconds整数秒数继承群值守默认值60-604800是本群新值守 Session 的自动休眠阈值。
bridge.feishu.profiles.<profile>.group_watch.chat_settings.<chat_id>.version整数0非负整数是本群值守设置版本,用于拒绝过期卡片写入。
bridge.feishu.profiles.<profile>.group_watch.enabled布尔值继承安装级—是Profile 级群值守开关;纯图片、纯文件和无正文合并转发也可自动触发。
bridge.feishu.profiles.<profile>.group_watch.chat_ids字符串数组继承安装级—是Profile 级值守群白名单。
bridge.feishu.profiles.<profile>.group_watch.sender_types字符串数组继承安装级user、app是Profile 级发送者类型。
bridge.feishu.profiles.<profile>.group_watch.chat_sender_types.<chat_id>字符串数组继承安装级chat_id 必须也在该 Profile 的有效 chat_ids 中;值为 user、app是Profile 级单值守群发送者类型覆盖;未覆盖的群使用当前 Profile 的 sender_types。
bridge.feishu.profiles.<profile>.group_watch.poll_interval_seconds整数秒数继承安装级5-300是Profile 级历史轮询周期。
bridge.feishu.profiles.<profile>.group_watch.lookback_seconds整数秒数继承安装级5-3600是Profile 级历史回看窗口。
bridge.feishu.profiles.<profile>.group_watch.dedup.enabled布尔值继承安装级—是Profile 级 App 报警语义去重开关。
bridge.feishu.profiles.<profile>.group_watch.dedup.window_seconds整数秒数继承安装级(1800)60-86400是Profile 级 App 报警语义去重窗口。
bridge.feishu.profiles.<profile>.group_watch.max_active_sessions_per_chat整数继承安装级(50)1-500是Profile 级每群活跃 Session 上限。
bridge.feishu.profiles.<profile>.group_watch.idle_timeout_seconds整数秒数继承安装级(10800)60-604800是Profile 级群值守自动休眠阈值。
bridge.feishu.profiles.<profile>.group_watch.agent_profile_ref字符串空(继承助手)—是群值守新 Session 使用的专家;空值继承该群有效默认专家;自定义配置与 Runtime 独立。
bridge.feishu.profiles.<profile>.group_watch.runtime_ref字符串空(继承助手)—是群值守新 Session 使用的运行引擎;继承任务配置时使用该群有效默认 Runtime,自定义配置时必填。
bridge.feishu.profiles.<profile>.group_watch.model_ref字符串空(运行引擎默认)—是群值守新 Session 使用的模型,按所选运行引擎校验;未覆盖运行引擎时遵循专家模型策略,未声明 supported_models 则允许原生模型名。
bridge.feishu.profiles.<profile>.group_watch.reasoning_effort字符串空(运行引擎默认)—是群值守新 Session 使用的思考强度,必须受所选运行引擎和模型支持。
bridge.feishu.profiles.<profile>.group_watch.thinking_process枚举继承安装级群值守(collapsed)expanded、collapsed、hidden是当前助手群值守任务的处理过程展示方式,与普通任务独立配置。

Structured Provider ​

配置键类型默认值约束CLI 可管理说明
provider.structured.turn_idle_timeout_seconds整数秒数9000 禁用,负数回默认,最大 604800否Structured provider 与 ACP turn 无有效活动超时;等待权限及无进度契约的 ACP 工具期间暂停。
provider.structured.turn_hard_cap_seconds整数秒数216000 禁用,负数回默认,最大 604800否Structured provider 与 ACP 单 turn 绝对时长上限,包含等待权限及工具的时间。
provider.structured.tool_idle_timeout_seconds整数秒数36000 禁用,负数回默认,最大 604800否Structured provider 工具无进度超时;ACP 尚无可验证的工具进度契约,使用 turn hard cap。
provider.structured.repeat_tool_call_limit整数计数500 禁用,负数回默认,最大 1000否Structured provider 与 ACP 同一 turn 内连续相同工具调用次数上限;ACP 只计不同调用 ID 且具备完整工具身份和输入的调用。
provider.structured.<provider>.turn_idle_timeout_seconds整数秒数继承全局provider 为 codex;0 禁用,负数回 provider 默认,最大 604800否指定 provider 的 turn idle 覆盖。
provider.structured.<provider>.turn_hard_cap_seconds整数秒数继承全局provider 为 codex否指定 provider 的 turn hard cap 覆盖。
provider.structured.<provider>.tool_idle_timeout_seconds整数秒数继承全局provider 为 codex否指定 provider 的 tool idle 覆盖。
provider.structured.<provider>.repeat_tool_call_limit整数计数继承全局provider 为 codex;0 禁用,负数回 provider 默认,最大 1000否指定 provider 的连续相同工具调用次数上限覆盖。

不属于 config.toml 的状态 ​

飞书 App Secret 与 legacy-host credential 保存在 $AMUX_HOME/secrets/;identified Agent credential 按 Principal 保存在 $AMUX_HOME/principals/<principal-id>/secrets/。workspace Session quota、thread binding 与群值守 binding 等运行状态保存在 Bridge/Runtime SQLite 中。它们不是 config.toml 配置键,不应写入本文件。

Released under the Apache-2.0 License.