10. 配置、主题与终端
文件与环境变量
Matcha CLI 把自己的文件放在 ~/.matcha，产品设置从 MATCHA_* 环境变量读取。本文说明这些文件在哪、哪个名字优先，以及什么不会从服务器同步。没有账号，也没有官方云。
服务商 API 密钥（XAI_API_KEY、OPENAI_API_KEY、ANTHROPIC_API_KEY）不是 Matcha 的名字，仍用服务商官方变量。配置服务商（BYOK）时再设置它们。
你需要什么
一份能运行的 matcha 二进制。不必事先建任何文件：若 ~/.matcha/config.toml 不存在，就用内置默认值。
要查看 Matcha 为当前目录发现的每一层：
matcha inspect脚本需要同一份报告时加上 --json。
主目录
用户主目录是 ~/.matcha，除非你覆盖它。
| 做法 | 结果 |
|---|---|
| 未设置 | ~/.matcha |
MATCHA_HOME=/path | 该目录 |
仅 GROK_HOME=/path | 该目录（只读兼容；仅在 MATCHA_HOME 未设置时读取） |
若同时设置了 MATCHA_HOME 与 GROK_HOME，Matcha 使用 MATCHA_HOME，并按变量名报告冲突，从不打印值。matcha doctor 与 matcha inspect 对其它已注册的成对变量也是这种只报名字的冲突。
第一次使用默认主目录时，Matcha 把 ~/.grok 里缺失的条目复制进 ~/.matcha。旧树不会删除。设置了 MATCHA_HOME（或 GROK_HOME）则跳过这次复制：按你给出的覆盖路径使用。
用户文件
只改你需要的。会话、登录、技能和插件用到时，Matcha 会创建其余文件。
| 路径 | 作用 |
|---|---|
~/.matcha/config.toml | 主设置（[ui]、[models]、[features]、MCP、技能及相关段） |
~/.matcha/pager.toml | 全屏布局、边距、动画、备用屏幕策略 |
~/.matcha/auth.json | 认证元数据（自动管理；密钥在凭证库） |
~/.matcha/credentials/secrets.json | 系统钥匙串不可用时，服务商密钥的文件回退（0600） |
~/.matcha/sessions/ | 持久会话，按工作目录分组 |
~/.matcha/memory/ | 跨会话记忆（记忆开启时） |
~/.matcha/skills/、plugins/、agents/、workflows/ | 用户范围的扩展 |
~/.matcha/logs/ | 内部日志 |
~/.matcha/last-copy.txt | 剪贴板备份（用 MATCHA_COPY_FILE 覆盖） |
Matcha 写入 config.toml 时会盖上 schema_version = 1。没有版本的文件仍能加载。旧键如 [auth]、主题 id groknight / grokday、助手 id grok-build* 在读取时映射；新写入使用 Matcha 名（matchanight、matchaday、matcha-build）。未知键会保留。
会话里用 /settings 做的改动写入用户 config.toml。色板选择是该文件里的 [ui] theme，不是 pager.toml 里的 theme 键。全屏色板见「主题」。
项目文件
在仓库（或当前项目根）放一个 .matcha/ 目录，用于仅限本项目的 MCP 服务器、插件、权限规则、技能、钩子、助手和 LSP。
| 文件 | 配置内容 |
|---|---|
.matcha/config.toml | 仅 [mcp_servers]、[plugins]、[permission]，以及 [mcp] max_output_bytes |
.matcha/skills/、hooks/、agents/、plugins/ | 项目范围的扩展 |
.matcha/lsp.json | 项目 LSP 服务器 |
.matcha/sandbox.toml | 自定义沙箱配置 |
AGENTS.md | 给助手的项目说明 |
config.toml 的其它段只从 ~/.matcha/config.toml 加载。
[mcp_servers] 与 [plugins] 的优先级：当前目录 .matcha/config.toml > <repo-root>/.matcha/config.toml > ~/.matcha/config.toml。权限规则在这些文件间合并（deny > ask > allow）。
若没有 .matcha/，Matcha 仍会发现残留的 .grok/ 项目树（只读兼容）。不会删除它。
优先级
高者优先：
- CLI 标志（例如
--model、--sandbox、--yolo） - 环境变量（
MATCHA_*，外加服务商官方密钥） ~/.matcha/config.toml- 内置默认值
若磁盘上已有残留的 managed_config.toml 或 requirements.toml，matcha inspect 仍会列出它找到的层。不要把这些文件当成 Matcha 会替你下载或刷新的东西。
自更新、产品遥测、插件市场和账号 OAuth 也不可用。设置 [cli] auto_update、[features] telemetry 或 OIDC 环境变量不会打开这些服务，也不会下载二进制。
环境变量
产品名使用 MATCHA_ 前缀。已注册的 GROK_* 别名是只读兼容：仅在对应的 Matcha 名未设置时生效。若两者都设了，Matcha 优先，诊断会点出这两个变量名。
常见产品变量：
| 变量 | 作用 |
|---|---|
MATCHA_HOME | 配置目录（默认 ~/.matcha） |
MATCHA_THEME | 已注册的主题覆盖。若需要立刻看得见的改动，优先用 /theme 或 [ui] theme — 见「主题」。 |
MATCHA_APPEARANCE | 给 theme = "auto" 的已注册 dark / light 提示 |
MATCHA_MEMORY | 1 / 0 — 跨会话记忆 |
MATCHA_SUBAGENTS | 1 / 0 — 子助手 |
MATCHA_WORKFLOWS | 1 / 0 — 后台工作流（默认开） |
MATCHA_SANDBOX | 沙箱配置 |
MATCHA_LOG_FILE | 日志文件路径（按原样使用） |
MATCHA_RESPECT_GITIGNORE | 1 / 0 — 覆盖 [tools] respect_gitignore |
MATCHA_COPY_FILE | 剪贴板备份路径 |
MATCHA_CLIPBOARD_NO_OSC52 | 1 — 关闭 OSC 52 复制路径 |
MATCHA_MODELS_BASE_URL | 自定义 OpenAI-compatible 模型/推理基址 |
RUST_LOG | 日志级别过滤（不是 Matcha 名） |
核对一下
- 在有
.matcha/config.toml的项目和没有该文件的项目里分别运行matcha inspect。确认项目 MCP 与插件层只出现在前者。 - 把
MATCHA_HOME设到一个空目录并启动 Matcha。确认新文件落在那里，而不是~/.matcha。 - 若仍留有 Grok Build 的
GROK_*，先清掉对应的 Matcha 名，确认旧名仍可用（只读兼容）；两者都设时，确认matcha doctor只报冲突名、不打印密钥。