配置参考（config.json）

Mogick 从全局 <config-dir>/config.json 和项目 <workspace>/.mogick/config.json 加载非敏感配置，多数用户配置以项目层优先。普通标量通常按字段覆盖；项目层非空的 llm.providers[] 整体替换全局 Provider 数组。agents 则保留全局和项目两层，按 Agent 类型与工具名解析。

MOGICK_CONFIG_FILE 只替代主配置文件加载路径，不改变 auth.json、mcp.json、Skills 或数据目录。

最小单 Provider 示例

将示例地址及两处 your-model-id 替换为服务实际支持的值，并在 auth.json 中配置对应 API Key。此示例适用于 llm.providers 不存在或为空的情况；非空 provider 数组会优先于这些单 Provider 字段。

{
  "llm": {
    "provider": "openai-compatible",
    "base_url": "https://your-provider/v1",
    "model": "your-model-id",
    "models": [
      { "id": "your-model-id", "name": "My Model" }
    ],
    "timeout_ms": 60000,
    "max_retries": 3
  }
}

最小多 Provider 示例

{
  "llm": {
    "providers": [
      {
        "id": "private",
        "type": "openai-compatible",
        "base_url": "https://example.com/v1",
        "models": [
          { "id": "code-model", "name": "Code Model" }
        ]
      }
    ],
    "default_model": "private/code-model"
  }
}

凭据不属于本文件，见认证与模型。

LLM 顶层字段（llm）

字段	类型	默认值	说明
providers	array	[]	多 Provider 定义；非空时启用多 Provider 路由
default_model	string	空	多 Provider 默认模型，使用 provider-id/model-id
provider	string	空	旧式单 Provider 类型；常用 llm-store 或 openai-compatible；providers[] 非空时忽略
base_url	string	空	单 Provider API base；providers[] 非空时以 Provider 自身字段为准
model	string	空	单 Provider 默认模型 ID；providers[] 非空时以 default_model 为准
models	array	空	单 Provider 静态模型列表（字段同 models[]）；providers[] 非空时以各 Provider 自身 models 为准
light_model	string	回退默认模型	标题、摘要等轻量任务模型
embedding_model	string	空	记忆和搜索 embedding 模型；空表示不启用对应语义来源
rerank_model	string	空	检索 rerank 模型
subagent_model	string	继承会话模型	内置子代理默认模型
app_id	string	空	llm-store 应用 ID；providers[] 非空时以各 Provider 自身 app_id 为准
extra_headers	object	空	非敏感附加请求头；providers[] 非空时以各 Provider 自身 extra_headers 为准
timeout_ms	int	180000	普通请求和响应头超时，毫秒
connect_timeout_ms	int	10000	TCP/TLS 建连超时，毫秒
stream_idle_timeout_ms	int	60000	SSE 流无业务数据的空闲超时，毫秒
stream_overall_timeout_ms	int	1800000	SSE 请求总时长上限，毫秒
max_retries	int	0	失败后的最大重试次数；运行时上限为 5
client_type	string	mogick	X-Client-Type 请求头
client_version	string	当前二进制版本	X-Client-Version 请求头

模型级 models[].thinking.enabled 是三态：true 请求开启，false 请求关闭，省略则不覆盖服务端默认值。26.9.11 的 budget_tokens 仅保留兼容，不作为思考预算发送。推理程度通过 /efforts 选择支持的值，不等同于此开关。

llm.providers[]

字段	类型	必填	默认值/说明
id	string	是	稳定且唯一的 Provider 命名空间
type	string	否	llm-store 或 openai-compatible；省略时按 openai-compatible 处理
enabled	bool	否	默认 true
base_url	string	是	Provider 服务地址；llm-store 运行时追加 /api/v1
app_id	string	否	llm-store 的 X-APP-ID
models	array	OpenAI-compatible 是	静态模型列表；没有启用模型时 Provider 初始化失败；llm-store 会忽略本字段并动态获取目录
extra_headers	object	否	非敏感附加请求头

当项目配置提供非空 llm.providers[] 时，它整体替换全局数组，不按 id 合并。

models[]

字段	类型	必填	默认值/说明
id	string	是	发送给该 Provider 的模型本地 ID
name	string	否	TUI 显示名称；建议填写
description	string	否	模型说明
input_modals	string[]	否	例如 text、image
output_modals	string[]	否	例如 text
context_length	int	否	上下文窗口 token 数；0 表示未知
enabled	bool	否	默认 true
thinking	object	否	可选 enabled 布尔值；省略时保留服务端默认行为

Agent 工具策略（agents）

agents 以模式或 Agent 类型为键，例如 agent、plan。每个条目包含 tools map：

{
  "agents": {
    "agent": {
      "tools": {
        "shell.exec": {
          "enabled": true,
          "permission": "ask"
        }
      }
    }
  }
}

字段	类型	取值	说明
agents.<type>.tools.<tool>.enabled	bool	true / false	是否注册该语义工具；省略时继承 preset
agents.<type>.tools.<tool>.permission	string	allow / ask / deny	执行权限；省略时继承 preset

agents 按层解析：项目配置中的同名 Agent、同名工具整体覆盖全局工具项；项目未声明的工具继续使用全局项，再回退到模式 preset。删除类硬门禁和 CLI 会话权限策略仍会参与最终决策。

Skills（skills）

字段	类型	默认值	说明
create_root	string	mogick	新建 Skill 的根目录：mogick 或 agents
create_scope	string	project	新建范围：project 或 global
search_path_extras	string[]	[]	追加的 Skill 父目录；跨层去重追加
disabled	string[]	[]	新会话默认禁用的 Skill ID；项目层显式列表覆盖

Memory（memory）

字段	类型	默认值	说明
db_path	string	按 profile 和通道确定，见数据目录	显式数据库绝对路径
enabled	bool	true	同时控制检索注入和运行后抽取
retrieval.fts_top_n	int	50	全文检索候选数
retrieval.embedding_top_n	int	50	向量检索候选数
retrieval.directive_filter_enabled	bool	true	是否启用指令矛盾过滤
retrieval.directive_filter_top_k	int	10	过滤后保留数量
retrieval.directive_filter_min_candidates	int	3	启用过滤的最少候选数
retrieval.directive_filter_timeout_ms	int	8000	过滤超时，毫秒
retrieval.hybrid_weights.confidence	number	0.1	混合排序的置信权重

Session（session）

字段	类型	默认值	说明
heartbeat_interval_ms	int	15000	宿主会话心跳间隔
command_timeout_ms	int	30000	宿主命令超时
max_payload_bytes	int	1048576	CRP 最大载荷，1 MiB
safe_partition_max_concurrency	int	10	每一步只读工具并发上限
mcp_local_max_concurrency	int	3	每个本地 MCP server 的并发上限
mcp_remote_max_concurrency	int	20	每个远程 MCP server 的并发上限
disable_stream_tools_during_step	bool	false	是否禁止在 LLM 流式阶段启动工具
checkpoint_auto_before_run	bool	true	每轮用户请求前尝试创建检查点
max_concurrent_sessions	int	10	单个 Mogick 进程内加载的会话上限

max_concurrent_sessions 只约束单个进程，不协调共享同一数据库的多个 Mogick 实例。

注意：safe_partition_max_concurrency、mcp_local_max_concurrency、mcp_remote_max_concurrency 和 disable_stream_tools_during_step 是有效的解析字段，但当前实现不要依赖项目层 .mogick/config.json 覆盖全局值；需要设置这些运行时并发/流式边界时，优先写入全局配置或使用 MOGICK_CONFIG_FILE 指向完整配置文件。

语言、诊断与遥测

字段	类型	默认值	说明
language	string	en	en 或 zh-CN
diagnose.enabled	bool	false	录制 ACP/CRP diagnose 追踪
telemetry.enabled	bool	true	OTel tracing 总开关；显式 false 关闭

环境诊断使用 mogick doctor --export <path>；26.9.11 的会话导出不提供协议 trace 模式。

配置合并摘要

类型	合并方式
普通字符串、数字	多数字段项目层非零值覆盖全局；少数运行时边界字段见上方 Session 说明
显式布尔字段	支持项目层显式 false 的字段按实现覆盖
llm.providers[]	项目层非空数组整体替换
agents	项目同名工具覆盖全局工具项；未声明项回退全局和 preset
skills.search_path_extras	追加并去重
auth.providers	不在 config.json；按 Provider ID 合并

完整路径和环境变量见数据目录与环境变量。

路径占位符 <config-dir>、<db-path> 指当前 profile/通道实际生效的路径，见数据目录。