设置

musepi 从内置默认值、持久化的全局配置文件、可选的项目本地配置、一次性 CLI overlay 以及内存中的 runtime 覆盖中解析设置。当某个 repository 需要不同于全局默认值的 provider 集合、model role、tool 策略、memory backend 或 UI 行为时，可以使用项目设置——而无需改动整台机器的配置。

设置以纯 YAML mapping 形式存储。每个键、其类型、默认值和枚举值都来自 settings schema，你可以用 musepi config 或交互式 /settings 面板查看或修改其中任何一项。

• 关于 model/provider 凭据、.env 文件以及解析 API key 的环境变量表，见 Providers。
• 关于 models.yml 中的自定义 model 定义，见 Models。
• 关于被发现到 agent context 中的指令文件（AGENTS.md、.musepi/ 等），见 Context files。
• 关于环境变量的完整目录，见 Environment variables。
• 关于激活每轮专属行为的提示词，见 Magic keywords。

设置存放位置

PI_CODING_AGENT_DIR 可重新定位 ~/.musepi/agent 基础目录。设置后，全局 config.yml、auth 存储（agent.db）以及 agent 目录下的一切都会随之移动。使用 musepi config path 打印当前生效的 agent 目录。

原生项目设置有意限定在进程工作目录的 .musepi/ 文件夹——设置发现不会向上遍历祖先目录寻找最近的 .musepi/。其他 discovery provider（Claude、Codex、Gemini、Cursor、OpenCode）也可以从它们自己的文件贡献项目级设置；这些对 musepi 设置命令而言是只读的，可以按 provider id 关闭（见 Provider 与来源禁用）。

配置文件格式

全局 config.yml 始终是 YAML。用于其他文件（例如 models.yml）的通用配置加载器接受 .yml、.yaml、.json 和 .jsonc：

• 当请求的是 .yml/.yaml 路径而只存在同名的 .json 时，会自动迁移为 YAML（幂等，每个进程一次）。
• .json 和 .jsonc 配置按原样读取，不做迁移。
• 顶层不是 mapping 的文件（裸数组或标量）在持久化设置中被视为空，而对 --config overlay 则是硬错误。

读取与写入设置

在 session 内使用交互式 /settings 面板，或在 shell 中使用 musepi config 命令。两者都作用于合并后的生效设置，但每次持久化写入只会落到全局文件。

musepi config list                 # 所有设置及其当前生效值
musepi config list --json          # 同上，机器可读
musepi config get theme.dark       # 单个值
musepi config get theme.dark --json
musepi config set compaction.enabled false
musepi config set defaultThinkingLevel medium
musepi config reset steeringMode   # 将某个键恢复为 schema 默认值
musepi config path                 # 打印当前生效的 agent 目录

对于希望在正常启动时也看到完整首次运行动画的用户，设置 startup.showSplash：

musepi config set startup.showSplash true

这只控制启动 splash 动画。它不会重新运行 setup 或改变 setup 状态，并且 startup.quiet: true 仍会抑制包括 splash 在内的所有启动界面元素。

子命令

不带子命令的 musepi config 或 --help 会打印帮助并列出设置。list、get、set 和 reset 都接受 --json flag。

值解析

musepi config set 按目标键的 schema 类型解析值字符串。字符串会先做 trim。

键必须精确匹配真实的 schema path。没有简写——应设置 theme.dark，而不是 theme。

写入去向

musepi config set、musepi config reset、/settings 以及任何 runtime 设置变更都写入当前 agent 目录下的全局 config.yml。它们从不写入 <cwd>/.musepi/config.yml。要创建项目本地覆盖，请直接编辑该文件（见 项目本地配置）。保存做了防抖处理，并在锁保护下重新读取文件，因此 session 打开期间的外部编辑会被保留。

优先级

从最低到最高优先级，设置的生效值按以下顺序构建：

built-in defaults  <-  global config  <-  project config  <-  CLI overlays  <-  runtime overrides

从最高到最低：

1. Runtime 覆盖 — 为当前进程在内存中应用的专用 CLI flag 和 feature 环境变量：--model、--smol、--slow、--plan、--approval-mode、--auto-approve/--yolo、--hide-thinking、--advisor、--no-pty、--api-key 以及 protocol-mode 默认值。永不持久化。
2. CLI 配置 overlay — 每个 --config <file>；后面的 overlay 文件覆盖前面的。
3. 项目设置 — 先 <cwd>/.musepi/settings.json 再 <cwd>/.musepi/config.yml（以及其他 discovery provider 在项目级的贡献）。
4. 全局设置 — ~/.musepi/agent/config.yml。
5. 内置默认值 — 来自 settings schema。

在所有层都未设置的键在读取时解析为其 schema 默认值。

环境变量覆盖

环境变量不是单一的设置层。每个变量由拥有对应值的 feature 读取，通常作为每台机器的覆盖或 fallback，并且永远不会写回 config.yml。直接映射到某个设置的变量如下：

Provider API key 单独解析（存储的 auth、OAuth、models.yml、环境和 .env 文件）；见 Providers 和完整的 Environment variables 参考。

合并规则

各层通过 deep merge 组合：

• 对象做 deep merge — 只存在于较低层的键被保留；较高层中的键进行覆盖。
• 标量和数组整体替换 为更高优先级层的值。较高层的数组不会追加到较低层的数组之后。

点分设置路径使用嵌套 YAML mapping 表示：

theme:
  dark: titanium
  light: light

tools:
  approvalMode: write
  approval:
    bash: prompt
    read: allow

Bash 命令审批模式

tools.approval 按 tool 名称设置默认策略。对 bash，你可以用 bash.patterns 添加有序的命令规则；第一条匹配的规则胜出。模式支持字面文本加 * 通配符。

tools:
  approvalMode: write
  approval:
    bash: allow

bash:
  patterns:
    - match: "git *"
      approval: allow
    - match: "rm -rf *"
      approval: deny
    - match: "*"
      approval: allow

规则的有效审批值是 allow、prompt 和 deny。除非有匹配规则明确 deny，关键 bash 命令仍然需要确认；诸如 match: "*" 这样的宽泛 allow 规则不能绕过关键命令守卫。

匹配是非对称的，以保证规则语义如其所示：deny 和 prompt 规则在 glob 匹配整条命令或复合行的任一单段（按 &&、||、;、|、单个 &、subshell 和换行拆分）时触发，因此 match: "rm -rf *" 仍会拒绝 cd /tmp && rm -rf build 和 sleep 1 & rm -rf build。allow 规则必须匹配完整命令，且绝不应用于复合行，因此像 match: "git *" 这样的窄 allow 规则无法为 git status && rm -rf / 作保。

Bash interceptor 模式

bashInterceptor 与 bash.patterns 是分开的：它把 Bash 命令重定向到专用 tool，而不是定义命令能否执行。需显式启用并用替换 tool 和面向 model 的消息配置正则表达式模式：

bashInterceptor:
  enabled: true
  patterns:
    - pattern: '^\s*(cat|head|tail)\s+'
      tool: read
      message: "Use the read tool instead."

命名的替换 tool 必须在当前 session 中可用，否则 interceptor 不会拦截 Bash 调用。关于权限策略与专用 tool 路由的详细对比（包括复合命令行为和排序），见 Bash tool 文档。

实例演示：全局 vs. 项目

# ~/.musepi/agent/config.yml
tools:
  approvalMode: write
  approval:
    bash: prompt
    read: allow
disabledProviders:
  - anthropic
  - openai
  - gemini

# <repo>/.musepi/config.yml
tools:
  approval:
    bash: allow
disabledProviders:
  - groq

在 <repo> 内的生效设置：

tools:
  approvalMode: write   # 从全局保留（对象 deep merge）
  approval:
    bash: allow         # 被项目覆盖
    read: allow         # 从全局保留
disabledProviders:
  - groq                # 项目数组替换了全局数组

数组替换是最常见的意外：项目的 disabledProviders 不是在全局列表上扩展——而是成为该项目下的完整列表。enabledModels、cycleOrder、extensions 以及其他所有数组类型的设置同样如此。

项目本地配置

当一个 repository 需要自己的设置时，创建 <repo>/.musepi/config.yml：

# <repo>/.musepi/config.yml
modelRoles:
  default: anthropic/claude-sonnet-4-5
  smol: openai/gpt-4.1-mini
  slow: anthropic/claude-opus-4-5:high

tools:
  approvalMode: write
  approval:
    bash: prompt

compaction:
  strategy: snapcompact
  thresholdPercent: 80

theme:
  dark: titanium

除非你的 repository 政策允许，否则不要把 secret 提交进项目配置。凭据优先使用环境变量、存储的 auth、auth broker 或不纳入版本控制的 --config overlay。

一次性 overlay

对不应持久化的临时层使用 --config：

musepi --config ./local/ci-settings.yml "check this failure"
musepi --config ./base.yml --config ./experiment.yml "try this model"

默认启动命令、acp 和 models 都接受 --config。

Wrapper 也可以将 PI_CONFIG_FILES 设为平台分隔的路径列表（Unix 上是 :，Windows 上是 ;）。环境变量 overlay 按列出的顺序在显式 --config overlay 之前加载。

Overlay 路径相对于进程工作目录解析（~ 会被展开）。每个 overlay 必须能解析为 YAML mapping；文件缺失、YAML 无效或顶层数组/标量都是硬错误——它不会静默回退到更低优先级的设置。

路径作用域数组

两个数组设置——enabledModels 和 disabledProviders——除裸字符串外还接受路径作用域条目，使单一全局配置可以在不同目录表现不同：

enabledModels:
  - claude-sonnet-4-5            # 处处适用
  - path: ~/work/high-context
    models:
      - anthropic/claude-opus-4-5

disabledProviders:
  - ollama                       # 处处适用
  - paths:
      - ~/projects/sensitive
      - ~/clients/acme
    providers:
      - anthropic
      - openai

裸字符串条目处处适用。作用域条目在当前工作目录就是配置路径或位于其之下时生效。~ 展开为你的 home 目录，相对路径在匹配前先做解析。

接受的 path 键（可任选组合）：path、paths、pathPrefix、pathPrefixes。

接受的 value 键：

• models（用于 enabledModels）或 providers（用于 disabledProviders）
• values 或 items（两者通用）

只有字符串值会被保留；畸形的作用域条目会被忽略。路径作用域在层合并之后解析，因此读取的是最终生效数组。

Provider 与来源禁用

disabledProviders 是一个共享的 id 命名空间，在任何凭据检查之前门控两个不同的子系统：

大多数 provider 控制场景列出的是 model provider id。禁用 claude discovery source 与禁用 anthropic model provider 不同——前者停止 Claude 格式配置的发现，后者停止 Anthropic model 后端。

由于数组是替换而非追加，设置了 disabledProviders 的项目必须列出完整的目标集合：

# ~/.musepi/agent/config.yml
disabledProviders:
  - anthropic
  - openai

# <repo>/.musepi/config.yml — 在此 repo 内只禁用 groq
disabledProviders:
  - groq

默认值是空数组（什么都不禁用）。关于这两个子系统的 provider id 和排序，见 Providers 和 Context files。

设置目录

下面每个键都在 settings schema 中定义；musepi config list 显示完整集合及当前值。默认值和枚举值取自 schema。支持 env 或 flag 覆盖的设置已注明；这些覆盖只在进程内生效，不会持久化。

Models

modelRoles、modelTags 和 cycleOrder 共同定义你可以在哪些 model 之间切换。Role 值可携带 thinking 后缀（:minimal、:low、:medium、:high、:xhigh、:max）。

modelRoles:
  default: anthropic/claude-sonnet-4-5
  smol: openai/gpt-4.1-mini
  slow: anthropic/claude-opus-4-5:high
  vision: gemini/gemini-3-pro-preview
  plan: anthropic/claude-opus-4-5
  advisor: anthropic/claude-sonnet-4-5:medium

cycleOrder:
  - smol
  - default
  - slow

modelProviderOrder:
  - anthropic
  - openai

enabledModels:
  - claude-sonnet-4-5

models.yml schema 与自定义 provider 定义见 Models。

Advisor

Advisor 是第二个 model，它会审查每一轮完成的 turn 并可向主 session 注入建议。先用 modelRoles.advisor 分配一个 model，然后通过 advisor.enabled、/advisor on 或带 --advisor flag 启动来启用它。

运行时行为、WATCHDOG.md 发现以及有界 catch-up 语义见 Advisor and WATCHDOG.md。

Thinking

defaultThinkingLevel: high
hideThinkingBlock: false
thinkingBudgets:
  minimal: 1024
  low: 2048
  medium: 8192
  high: 16384
  xhigh: 32768
  max: 32768

Sampling

值为 -1 表示”使用 provider/model 默认值”——musepi 不会发送该参数。

Retry 与 fallback

retry:
  enabled: true
  maxRetries: 10
  baseDelayMs: 500
  maxDelayMs: 300000
  modelFallback: true
  fallbackRevertPolicy: cooldown-expiry
  fallbackChains:
    # 没有显式 chain 的任何 role 都继承 "default" chain。
    default:
      - anthropic/claude-opus-4-5
      - openai/gpt-5.5
      - google/gemini-3-pro
    # Per-role chain 覆盖 default（role 来自 `modelRoles`，
    # 包括自定义 role）。Selector 接受可选的 thinking
    # 后缀，例如 openai/gpt-5.5:low。
    smol:
      - openai/gpt-5.5-mini
      - anthropic/claude-haiku-4-5
    # Model-selector 键（任何包含 "/" 的键）把 chain 绑定到
    # model 本身：只要该 model 处于活跃状态就生效，无论它
    # 被分配给哪个 role，并且在 role 重分配后依然保留。
    google/gemini-3-pro:
      - google-vertex/gemini-3-pro
    # `provider/*` 键覆盖一个 provider 的所有 model——现在的
    # 和未来的。`provider/*` 条目保留失败 model 的 id 并只换
    # provider：google-antigravity/x -> google/x -> google-vertex/x。
    # 目标 provider 上缺失的 id 会被跳过（近似 id 模糊解析）；
    # 精确的 model 键对特定 model 覆盖通配符。
    google-antigravity/*:
      - google/*
      - google-vertex/*

当活跃 model 持续失败（429、配额墙、provider 故障）且 retry.modelFallback 开启时，session 按特异性选择拥有失败 model 的 chain：先是精确的 provider/model-id 键，再是 provider/* 通配符，再是当前 role 的 chain，最后是 default。它会跳过仍在冷却中的 model selector，并为本轮剩余部分完成切换。Subagent 在其 agent 定义列出多个 model pattern 时获得各自的 per-spawn chain——第一个可解析的 pattern 为主 model，其余成为它的 fallback；fallbackChains 中没有 agent:<name> 键。

Tools 与审批

tools:
  approvalMode: yolo          # default
  approval:
    bash: prompt
    edit: allow
  maxTimeout: 0
  intentTracing: true

原生 computer use

默认禁用的 computer essential tool 通过原生 OS API 捕获并控制真实主机桌面。它与 browser 相互独立：computer 可以驱动 IDE、终端、原生应用、浏览器窗口和系统对话框，而 browser 管理 Chromium/CDP tab 和结构化页面自动化。

computer:
  enabled: true
  backend: auto
  display: all
  maxWidth: 1920
  maxHeight: 1200

Computer 设置在 desktop controller 创建时捕获。跨越坐标安全尺寸边界的 model 切换会重建 controller 并重新快照这些设置；仅修改配置不会，所以改完设置后请开新 session。重建后的 controller 没有先前的坐标系，因此在下一次指针操作前先截一张新图。启用输入前，配置 tools.approvalMode 或 tools.approval.computer 并授予平台权限。见 Native computer use。

Shell、eval 与 LSP

bash:
  enabled: true
  autoBackground:
    enabled: false
    thresholdMs: 60000

eval:
  py: true
  js: true

python:
  kernelMode: session       # session, per-call
  interpreter: ""

lsp:
  enabled: true
  lazy: true
  diagnosticsOnWrite: true
  diagnosticsOnEdit: false
  formatOnWrite: false

文件：编辑与读取

edit:
  mode: hashline            # apply_patch, hashline, patch, replace
  fuzzyMatch: true
  fuzzyThreshold: 0.95
  blockAutoGenerated: true

read:
  defaultLimit: 300
  toolResultPreview: false
  summarize:
    enabled: true
    prose: false

Context、compaction 与 memory

contextPromotion:
  enabled: false

compaction:
  enabled: true
  strategy: snapcompact     # context-full, handoff, shake, snapcompact, off
  midTurnEnabled: true      # 在 tool-loop 的 provider 请求之间检查阈值
  thresholdPercent: -1       # -1 = 默认的 reserve 行为
  thresholdTokens: -1        # > 0 时为固定 token 上限
  remoteEnabled: true

memory:
  backend: off               # off, local, hindsight, mnemopi

compaction 还有更多调优键（idle compaction、supersede/drop 启发式），可在 musepi config list 中查看。完整的策略参考见 Compaction。

外观与终端

theme:
  dark: titanium
  light: light
symbolPreset: unicode        # unicode, nerd, ascii
colorBlindMode: false

statusLine:
  preset: default            # default, minimal, compact, full, nerd, ascii, custom
  separator: powerline-thin
  transparent: false
  showHookStatus: true

terminal:
  showImages: true
images:
  autoResize: true
  blockImages: false
tui:
  hyperlinks: auto           # off, auto, always

要自定义 status line，设置 statusLine.preset: custom 并配置 statusLine.leftSegments、statusLine.rightSegments 和 statusLine.segmentOptions。

交互

Providers 与服务

providers:
  webSearchOrder: [perplexity, exa, gemini]
  imageOrder: [openai, xai]
  fetch: auto
  webSearchGeminiModel: gemini-2.5-flash
  tinyModel: online
  tinyModelDevice: default
  tinyModelDtype: default
  openaiWebsockets: auto
  openrouterVariant: default
  kimiApiFormat: anthropic

provider:
  appendOnlyContext: auto    # auto, on, off

exa:
  enabled: true
  enableSearch: true
  enableResearcher: false
  enableWebsets: false

searxng:
  endpoint: https://search.example.com
  token: SEARXNG_TOKEN

Provider 凭据与自定义 model definition 单独配置——见 Providers 和 Models。

其他分组

musepi config list 还暴露许多其他分组设置，包括：task.*（subagent 并发、isolation、model 覆盖）、skills.* 和 commands.*（discovery 开关）、mcp.*、github.*、async.*、goal.*、loop.*、todo.*、magicKeywords.*、ttsr.*（time-traveling stream rules）、display.*、startup.*、share.*、collab.*、stt.*/tts.*、memories.*/hindsight.*/mnemopi.*（memory backend），以及 bashInterceptor.*。每个都遵循上文所示的相同类型/默认值规则。

遗留迁移

musepi 会自动迁移较旧的配置形状。这些都不需要你采取行动；列出它们是为了让你知道 config.yml 里可能出现哪些变化。

启动时迁移到 config.yml

当 ~/.musepi/agent/config.yml 不存在时，启动会从遗留来源构建一次，然后写出结果：

1. ~/.musepi/agent/settings.json（迁移成功后重命名为 settings.json.bak）。
2. 持久化在 agent.db 中的设置。

config.yml 存在后，这些遗留来源不再被查询。通用配置加载器也会在其他配置文件只存在 .json 形式时执行 .json -> .yml 迁移。

字段级迁移

每当原始设置被加载时应用（全局、项目、overlay 和 runtime 覆盖）：

故障排查

项目设置没有生效

• 从包含 .musepi/config.yml 的目录启动 musepi。设置发现只检查当前工作目录的 .musepi/，不检查祖先目录。
• 确保 .musepi/ 非空；空的配置目录会被忽略。
• 确认文件是合法 YAML 且顶层是一个 mapping。
• 在该目录运行 musepi config get <key> 查看生效值。
• 记住 --config overlay 和 runtime flag 会覆盖项目配置。

全局数组在项目中消失了

数组是替换而非追加。如果项目设置了 disabledProviders、enabledModels、cycleOrder、extensions 或任何其他数组，请在项目层写完整的目标值——全局数组会被完全替换。

修改配置后 provider 仍然可用

• 检查你禁用的是 model provider id（如 anthropic）还是 discovery source id（如 claude）——它们是不同命名空间、效果不同。
• 检查是否有项目（或 overlay）的 disabledProviders 数组替换了你全局的那个。
• 凭据仍可能来自环境变量、.env、OAuth、存储的 auth 或 models.yml；无论如何，禁用一个 provider 都会阻止它被选中，但要确认你编辑对了层。见 Providers。
• 如果 model 列表已经初始化过，重启 session。

musepi config set 写错了文件

musepi config set 和 musepi config reset 始终写入当前 agent 目录下的全局 config.yml。运行 musepi config path 打印它。对于项目本地设置，请直接编辑 <repo>/.musepi/config.yml。

musepi config reset 没有删除我的键

reset 会把 schema 默认值写入全局配置——它持久化默认值而不是删除该键。要让全局配置不再覆盖项目值，请手动从 ~/.musepi/agent/config.yml 删除该键。

--config overlay 在启动时失败

--config 文件是进程本地的 YAML mapping。文件缺失、YAML 无效或顶层数组/标量都是硬错误——它不会静默回退到更低优先级的设置。修正路径或内容。

环境变量压过了我的配置

某些设置（model role、eval backend、tiny-model device/精度、auth broker、PTY）可以被环境变量或 CLI flag 覆盖以便于每台机器的定制，并且它们的优先级高于 config.yml。取消设置变量或去掉 flag，让持久化的值生效。见 环境变量覆盖 和 Environment variables。

musepi config set <key> 提示 “Unknown setting”

键必须精确匹配 schema path，不能简写。使用 theme.dark，而不是 theme。运行 musepi config list 查看所有有效键。