配置指南¶

Synapse 使用 Pydantic Settings 实现分层配置系统。

配置加载顺序¶

优先级从高到低：

CLI 参数（如 -m gpt-4.1、--readonly）
环境变量（OPENAI_API_KEY 等）
.env 文件（项目根目录，覆盖系统环境变量）
分层 JSON 配置（models.json、mcp_servers.json）
代码默认值

配置文件路径¶

用途	路径
模型配置	`.coding-agent/models.json`
MCP 配置	`.coding-agent/mcp_servers.json`
主题自定义	`.coding-agent/themes.json`
环境变量	项目根目录 `.env`（legacy，推荐 models.json `api_key_env`）
会话数据	`.coding-agent/checkpoints.sqlite`

环境变量参考¶

模型相关¶

变量	默认值	说明
`MODEL`	`openai:gpt-4.1`	默认模型（legacy 单模型模式）
`OPENAI_API_KEY`	—	OpenAI API Key
`OPENAI_BASE_URL`	—	OpenAI API 自定义网关
`OPENAI_WEBSOCKET`	`false`	启用 WebSocket 连接；瞬时断流按模型 `max_retries` 重连，耗尽后在尚未输出内容时回退 HTTP/SSE
`OPENAI_FAST_MODE`	`false`	Codex Fast 档：对 `auth=openai_oauth` 的模型请求注入 `service_tier=priority`（优先处理、计费更高）。可用 `/fast on\\|off\\|status` 运行时切换；详见 models.md 的「Codex Fast 档」
`ANTHROPIC_API_KEY`	—	Anthropic API Key
`AGENT_MODELS_CONFIG`	—	`models.json` 路径（覆盖默认）
`MODELS_JSON`	—	内联 JSON（替代文件）
`AGENT_ACTIVE_MODEL`	—	活跃模型 profile 别名
`AGENT_SUGGESTION_MODEL`	—	轮次结束建议使用的轻量模型 profile 别名（未配置时回退到当前会话模型）
`VISION_MODEL`	—	独立视觉模型的 OpenAI 兼容配置

工作区¶

变量	默认值	说明
`WORKSPACE`	`$PWD`	工作目录
`SHELL_TIMEOUT`	`120`	Shell 命令超时（秒）
`MAX_OUTPUT_BYTES`	`100000`	命令输出最大字节数
`SHELL_EXECUTABLE`	`pwsh`	Shell 类型（`pwsh`/`powershell`/`cmd`/`bash`/`system`）
`SHELL_ENCODING`	`utf-8`	Shell 输出编码
`INHERIT_ENV`	`true`	继承系统环境变量
`VIRTUAL_MODE`	`true`	虚拟文件系统模式

审批与安全¶

变量	默认值	说明
`AGENT_REQUIRE_APPROVAL`	`false`	启用人工审批
`AGENT_AUTO_APPROVE`	`true`	自动放行（审批关闭）
`AGENT_SAFETY_PROFILE`	`dev-autopass`	安全策略
`AGENT_READONLY`	`false`	全局只读模式
`AGENT_DENY_FS_PATHS`	—	禁止访问的文件路径（JSON 数组）
`AGENT_ENABLE_FS_PERMISSIONS`	`false`	启用文件系统权限
`AGENT_EXCLUDED_TOOLS`	—	排除的工具列表（JSON 数组）
`AGENT_MINIMAL_FILESYSTEM_TOOLS`	`false`	启用极简文件工具模式（开启后自动剔除 `AGENT_MINIMAL_FILESYSTEM_EXCLUDED_TOOLS` 指定的工具，只保留必要的文件操作）
`AGENT_MINIMAL_FILESYSTEM_EXCLUDED_TOOLS`	`["search_files", "edit_file", "write_file"]`	极简模式下剔除的文件工具列表（可自定义组合）
`ENABLE_COMMAND_BLACKLIST`	`true`	启用命令黑名单

程序化工具调用（PTC）¶

PTC 让模型在一次模型回合里用一段 Python 代码编排多个工具调用（尤其适合批量 MCP 调用）。完整说明见程序化工具调用（PTC）。默认关闭（native），按需选择混合或代码模式。

变量	默认值	说明
`AGENT_TOOL_MODE`	`native`	`native` 不注册 `run_code`；`both` 原生工具与 `run_code` 并存；`code` 折叠可编排工具（审批模式下需审批的工具、会话状态工具仍保留原生）
`AGENT_PTC_TIMEOUT_SECONDS`	`120`	单次 `run_code` 超时（秒），范围 `0.1`–`3600`
`AGENT_PTC_MAX_CALLS`	`100`	单次运行的子调用次数上限，范围 `1`–`10000`
`AGENT_PTC_MAX_PARALLEL`	`8`	并发子调用上限，范围 `1`–`64`
`AGENT_PTC_MAX_OUTPUT_BYTES`	`64000`	`{logs, value, error?}` 整体输出上限（字节），范围 `256`–`16000000`
`AGENT_PTC_MAX_RESULT_BYTES`	`4000000`	中间值（单个工具结果 / `return` 值）上限（字节），范围 `1024`–`64000000`
`AGENT_PTC_MAX_CODE_BYTES`	`64000`	`code` 字节上限，范围 `256`–`1000000`

同样的字段也可写进分层 settings.json（用户层 ~/.synapse/settings.json，项目层 <workspace>/.synapse/settings.json），字段名与上表同名（去掉 AGENT_ 前缀并转小写，如 tool_mode、ptc_timeout_seconds）：

{
  "tool_mode": "both",
  "ptc_timeout_seconds": 120,
  "ptc_max_calls": 100,
  "ptc_max_parallel": 8
}

工具集与上限在 Agent 构建时固定：修改后需重建 Agent / 重启会话才生效，没有运行时或 UI 开关。PTC 不是安全沙箱——模型代码与用户 shell 同权限；只读模式会完全禁用 run_code。

会话¶

变量	默认值	说明
`CHECKPOINT_BACKEND`	`sqlite`	检查点后端（`sqlite`/`memory`）
`CHECKPOINT_PATH`	`.coding-agent/checkpoints.sqlite`	检查点存储路径
`SESSIONS_PATH`	—	会话元数据路径
`AGENT_PROJECT_CATALOG_ENABLED`	`true`	启用用户层全局项目目录（`~/.synapse/catalog.sqlite`）。开启后每次启动 TUI 会注册当前项目并投影会话元数据，供跨项目会话列表/搜索使用
`PROJECT_CATALOG_PATH`	`~/.synapse/catalog.sqlite`	全局项目目录数据库路径（默认用户层，可覆盖为任意路径）
`SESSION_SUMMARY_MODE`	`local`	会话摘要模式：`off` 关闭；`local` 在每轮结束后生成确定性本地摘要（不调用模型）。LLM 摘要为未来扩展位
`SESSION_SUMMARY_MAX_CHARS`	`600`	本地会话摘要的最大字符数（含多轮条目，超出时从最旧条目开始裁剪）
`AGENT_HISTORY_TAIL_TURNS`	`20`	TUI 从轻量 transcript 投影初始读取/渲染的最近可见会话轮数；滚动到顶部后按 turn 游标加载更早历史，最多挂载 5 页
`AGENT_SESSION_PREWARM_ENABLED`	`false`	恢复大上下文会话后，在后台对该会话历史发起一次最小模型请求，让 provider 预填充并缓存历史前缀，用户第一条消息可命中缓存、大幅缩短首 token 等待。注意：预热本身会按输入 token 计费一次，仅在需要时开启

长程目标（Goals）¶

变量	默认值	说明
`AGENT_ENABLE_GOALS`	`true`	启用长程目标：给 Agent 注入 `get_goal`/`create_goal`/`update_goal` 工具并统计目标 token/时间用量。关闭后不做记账、不注入工具
`AGENT_GOAL_AUTO_CONTINUE`	`true`	回合结束后若目标仍为 active，自动开启下一回合继续推进（长程执行核心；用户取消回合或输入新消息时不触发）

用法：/goal <objective> 设置目标（/goal 查看摘要，/goal pause|resume|clear|edit 管理，gooooal 为别名）。目标跨回合持久化；预算耗尽自动置为 budget-limited 并停止自动续跑。运行中按 Esc 会中止当前回合并把 active 目标置为 paused，可用 /goal resume 恢复。

子代理¶

变量	默认值	说明
`AGENT_ENABLE_SUBAGENTS`	`true`	启用子代理
`AGENT_SUBAGENT_TESTER_MODEL`	—	Tester 子代理模型
`AGENT_SUBAGENT_REVIEWER_MODEL`	—	Reviewer 子代理模型
`AGENT_SUBAGENT_RESEARCHER_MODEL`	—	Researcher 子代理模型
`AGENT_ENABLE_CUSTOM_SUBAGENTS`	`true`	加载用户自定义子代理（`.synapse/agents/*.md`）
`AGENT_CUSTOM_AGENTS_DIRS`	`[]`	额外扫描的子代理定义目录（JSON 数组，绝对路径或相对 workspace）
`AGENT_DISABLE_BUILTIN_SUBAGENTS`	`[]`	禁用的内置子代理名（JSON 数组，如 `["tester"]`）
`AGENT_SUBAGENT_DEFAULT_MODEL`	—	所有子代理的全局默认模型；未配置时继承主 Agent 模型
`AGENT_SUBAGENT_DEFAULT_REASONING_EFFORT`	—	所有子代理的全局默认推理级别（`off`/`minimal`/`low`/`medium`/`high`/`max`）
`AGENT_SUBAGENT_MODEL_OVERRIDES_JSON`	`{}`	按子代理名覆盖模型（JSON 对象，如 `{"tester":"algo:1"}`）
`AGENT_SUBAGENT_REASONING_EFFORT_OVERRIDES_JSON`	`{}`	按子代理名覆盖推理级别（JSON 对象）

自定义子代理¶

在用户层 ~/.synapse/agents/*.md 或项目层 <workspace>/.synapse/agents/*.md 放置 Markdown 文件即可新增子代理（项目层覆盖用户层同名定义）。YAML frontmatter 提供元数据，文件正文是子代理的 system prompt：

---
name: security-reviewer
description: Use after security-sensitive changes. Reviews for injection and secret leaks.
model: inherit            # 或 "provider:model-name"
reasoning_effort: high    # 可选：off/minimal/low/medium/high/max；缺省继承主 Agent
tools: [read_file, search_files, find_files, execute]   # 非空即最终严格白名单；省略则继承 find_files/search_files/patch
disallowed_tools: [write_file, edit_file]               # 可选 denylist
ownership: task           # 预留字段，仅支持 task
---

You are a security reviewer. Inspect diffs for...

name 与内置（researcher/tester/reviewer）同名时覆盖内置定义。
tools: [] 表示仅使用 deepagents 内置工具（不继承主代理工具）；全局排除（excluded_tools / minimal_filesystem_tools / readonly）与 disallowed_tools 仍然生效。
tools: [names] 非空时是最终严格白名单（框架内置工具也受约束），未知名字不会自动获得能力；被全局排除的工具即使点名也不会放开。
内置 tester 的 tools 默认值已由 [] 调整为 null（默认继承 find_files/search_files/patch）。
解析失败的文件会被跳过并记录 warning，不会导致启动失败。
ownership / output_schema 为未来 handoff 与 workflow 编排预留，当前仅支持 task。
首次启动会在 ~/.synapse/agents/ 生成 researcher.md / tester.md / reviewer.md 种子文件，编辑即可覆盖内置；已编辑内容不会被覆盖。同名文件存在但未显式写 model 时，AGENT_SUBAGENT_*_MODEL 仍会注入；在文件里显式写 model（或 model: inherit）后由文件接管。

MCP¶

变量	默认值	说明
`AGENT_ENABLE_MCP`	`true`	启用 MCP 支持
`AGENT_MCP_CONFIG`	—	MCP 配置文件路径
`AGENT_MCP_EAGER`	`false`	Agent 构建时即时连接 MCP
`MCP_SERVERS_JSON`	—	内联 MCP 配置（JSON）

界面¶

变量	默认值	说明
`AGENT_THEME`	`cursor-dark`	TUI 主题
`AGENT_TOOL_DETAILS_EXPANDED`	`true`	工具详情默认展开
`AGENT_EXPAND_THINKING`	`false`	推理块不自动展开：流式时仅显示状态行，结束后折叠为一行预览；设为 `true` 时流式与结束后均完整展开
`AGENT_DEBUG`	`false`	调试模式

语音输入（Web 控制台输入区麦克风）¶

变量	默认值	说明
`STT_ENGINE`	`browser`	识别引擎。`browser` 用浏览器自带的 Web Speech API：免费、无需安装（Chrome / Edge），但音频要经浏览器厂商服务器识别，中文一般。`local` 用本地离线 ONNX 引擎（`synapse.stt`）：中文更好、完全离线、零费用，代价是首次听写要等模型加载（这台机器上约 1 分钟，之后常驻）。`doubao` 用火山引擎豆包大模型流式识别：中文最强、支持热词与上下文，按小时计费且音频会上传服务商；只在桌面端可用，因为它的 WebSocket 握手靠自定义请求头鉴权，浏览器无法设置
`STT_MODEL_DIR`	—	本地模型目录；留空用 `~/.synapse/stt/models`

选 local 需要先 uv sync --extra stt-local 并把模型放进模型目录（清单与文件名校验见 src/synapse/stt/models.py，缺失时错误信息会一次列全）。若引擎不可用，控制台自动回退到浏览器引擎，并在输入卡片里显示原因，不会静默降级。

选 doubao 需要在「设置 → 语音输入」里填一次 API Key（火山引擎控制台获取）。Key 存在 ~/.synapse/stt.json，与 settings.json 分开——后者被文档定义为「非密覆盖项」，密钥不能落进一个可以提交、分享或打印的层。这个文件只由 daemon 写入（原子写、合并其他 provider），从不回传给控制台：状态只回答「是否已配置」。连接由桌面端（rust/synapse-gui/src/stt/）自己建立并读取该文件，不经 daemon 中转——因为握手要带自定义请求头，浏览器做不到；这也让密钥始终留在桌面进程里。在纯浏览器里选择云端引擎会回退到浏览器内置识别，runtime.stt.begin 对云端引擎会直接拒绝并说明原因。

云端的两档延迟参数是代码常量而不是配置项（rust/synapse-gui/src/stt/doubao.rs）：音频分片 DEFAULT_PACKET_MS（100 ms，厂商建议 100–200 ms）和收句静音窗口 DEFAULT_END_WINDOW_MS （400 ms，厂商默认 800 ms；调大它会让句子更晚落进输入框，调小则可能在短停顿处断句）。前端窗口 CLOUD_STT_CHUNK_MS 必须不小于 DEFAULT_PACKET_MS，否则会被桌面端合并回去而失去意义。

第三档是 CloudTuning::nonstream：厂商的第二遍解码，关掉能再省约 270 ms 的落句延迟，代价是提交流式那遍的文本（少一层纠正）。实测这段样本上它反而把英文术语改成大写，但样本只有一段，默认仍保留——它是厂商的准确率特性。

还有两档未默认启用：end_window_ms 官方最小值 200（实测再省 267 ms，但 200 ms 低于正常从句停顿范围，样本测不出断句风险），以及厂商的 enable_accelerate_text / accelerate_score （"首字加速"，实测在这段音频上无效果；厂商对不支持的参数静默忽略，无法区分"没生效"和"没用"）。这几项都在 CloudTuning 里，改一个字段即可。

本地模型只在真正要用它的时候构建（点麦克风，或在设置里按「加载模型」）：打开控制台不会自动构建，否则读者还没决定用哪个引擎就得先等一分钟的本地模型，期间想换成浏览器或云端引擎反而被拖住。构建期间麦克风旁显示进度提示并禁用按钮，完成后常驻在 daemon 进程里（重启 daemon 才需要重新构建）。

这两个值也可以直接在控制台的「设置 → 语音输入」里改：那里写入的是用户层 ~/.synapse/settings.json（原子写、保留其他键），并在同一次调用里应用到运行中的 daemon 的设置对象上，所以无需重启、无需刷新即可生效；环境变量与配置文件仍然优先于它，脚本化场景照旧。

其他¶

变量	默认值	说明
`AGENT_ENABLE_COMPACT_TOOL`	`true`	启用对话压缩
`TOKEN_STREAM`	`true`	启用 token 流式输出
`PARALLEL_TOOL_CALLS`	`true`	启用并行工具调用
`MAX_CONCURRENCY`	`8`	最大并行度
`STREAM_CHUNK_TIMEOUT`	—	流式块超时（秒，None=禁用）
`AGENT_SHOW_REASONING_PLACEHOLDERS`	`true`	网关仅返回推理 token 数、不暴露推理文本时，是否显示占位思考节点；设为 `false` 可隐藏 Codex 等加密推理占位
`AGENT_ENABLE_PROMPT_CACHE_BOUNDARY`	`false`	启用「按构建环境上下文 + prompt-cache 分界断点」这一整组功能：向系统提示词追加 Environment / Git Context / Current Date 动态段落，并在 stable/dynamic 分界处打 `cache_control` 断点，使这些易变内容不落在被缓存的前缀里（断点本身不改变提示词文本）。关闭时不追加动态段落，提示词与旧版逐字节一致。DeepAgents 已有两处断点，开启前请先在真实请求上核对缓存命中率
`LANGSMITH_TRACING`	`false`	启用 LangSmith 追踪
`LANGSMITH_API_KEY`	—	LangSmith API Key
`LANGSMITH_PROJECT`	`coding-agent`	LangSmith 项目名

`.coding-agent/models.json` 格式¶

参见模型配置页面。

配置错误提示¶

启动时如果 models.json、settings.json 或内联 JSON 环境变量格式错误，Synapse 会输出简短的错误说明和修复提示后退出，不会显示完整 Python traceback。对于 models.json，错误信息会包含出错文件路径和 JSON 的行列位置；修复配置后重新启动即可。

`.coding-agent/mcp_servers.json` 格式¶

参见 MCP Server 页面。

`themes.json` Markdown 样式¶

themes.json 支持在继承现有主题的基础上覆盖 Rich Markdown 元素的样式。主题配置仍按用户层到项目层合并，项目层可以只覆盖部分字段：

{
  "themes": {
    "my-dark": {
      "extends": "cursor-dark",
      "label": "My Dark",
      "markdown": {
        "h1": "bold #ff9e64",
        "h2": "bold #e0af68",
        "paragraph": "#c0caf5",
        "code": "bold #7dcfff",
        "block_quote": "italic #565f89",
        "link_url": "underline #7aa2f7",
        "table.border": "#414868",
        "table.header": "bold #bb9af7"
      }
    }
  }
}

支持的 Markdown 键包括：h1～h6、paragraph、strong、em、s、code、 code_block、block_quote、item、link、link_url、kbd、hr、 table.border 和 table.header。值使用 Rich style 语法；非法样式和未知键会被忽略，不会阻止其他主题加载。

code 控制行内代码的样式；代码围栏内部的语法高亮仍由主题的 code_theme（Pygments 主题名）控制。Markdown 样式在渲染期间局部应用，不会污染其他 Rich 输出。