目录

设置与通知

本页说明设置页里能配置的所有内容，以及 3Studio 在什么情况下会给你弹系统通知。

打开设置的入口

点击左侧栏底部的用户头像旁边的齿轮图标，即可打开设置页；设置页左上角有一个"←"箭头按钮，点击可返回主界面。

设置页顶部有四个标签：通用、LLM、工具、经验。切换到标签后，标签下方通常会出现一条小字号的分区快捷跳转条，点击其中某个分区名可以直接滚动到对应内容，长页面找设置项时比较方便；唯一的例外是 LLM 标签页——它内部改用两个纵向子标签组织内容（见下一节），不再需要横向的分区跳转条，因此不显示。

通用

语言

两个选项：中文 / English，点选即切换，界面文案会实时变化。默认是中文。本文档后续所有截图式描述都按默认中文界面书写。

⚠️ 3Studio 目前没有主题切换，界面固定为深色，设置里不会看到"深色/浅色"这类选项。

界面缩放

在系统自动适配的基础上再叠加一个倍率，供个人偏好微调。可选档位：80% / 90% / 标准（100%） / 110% / 125% / 150%。标准即纯自动适配，已经保证在不同显示器上占比一致；其余档位用于你个人觉得界面偏大或偏小时手动调整。

减弱动效

一个开关，默认关闭。打开后会减少动画、关闭装饰性动效，同时也会跟随你系统本身的"减弱动态效果"设置。

Agent 指令

这里控制 3Studio 里各个 Agent（替你干活的 AI 助手）的行为，指令分三层，自上而下叠加生效：

  • 全局指令：写在这里，对所有 Agent 生效（比如统一的语气、语言偏好、通用约束）。列表第一行是"全局指令（所有 agent）"，点"编辑"进入编辑页。
  • 各 agent 人设：每个 Agent 自己的角色设定，列表里每个 Agent 单独一行，点"编辑"单独修改。
  • 项目指令：每个项目根目录下的 AGENTS.md 文件，只在该项目内生效（这一层不在设置页里编辑，是工作区文件本身）。

改动只对新发起的对话生效，不会影响正在进行中的对话。如果你希望 Agent 用中文回答和思考，可以在全局指令里明确写出来，比如"请用中文回答与思考"——这是对模型的引导而非强制，个别模型仍可能不完全遵守。

LLM（模型服务）

第二个标签的名字是 LLM（大语言模型，Agent 背后驱动对话和决策的模型）。这里配置的模型服务是全局的：所有 Agent 共用同一份模型配置，无法给某个 Agent 单独指定不同的模型。

这个标签里显示什么内容，取决于你用的是哪种发行版：

  • 多数情况（自行配置模型服务）：显示"Model Provider"区域，左侧多了两个纵向排列的子标签——公开 Provider（选一个预置厂商，填个密钥就能用）和自定义 Provider（对接你自己部署或公司内网的模型服务，需要手工声明这个服务具备哪些能力，见下面「自定义 Provider」一节）。打开设置页时，会自动停在你当前保存的配置所属的那个子标签。

    ⚠️ 切换子标签不等于切换正在生效的模型，只有点击「保存 Provider」才会生效。 两个子标签各自维护一份独立的草稿，来回切换不会互相覆盖，但也不会自动保存；关闭设置页会丢弃所有未保存的草稿。点击「保存 Provider」时，写盘并生效的是你当前所在的那个子标签里的内容，并且和下面第 6 条一样会重启背后的模型引擎。

    公开 Provider 标签页：

    1. 从 Provider 下拉框选一个预设——目前可选 Kimi Code Plan (cn) 和 DeepSeek；列表里还会看到一项灰色不可选的 Sin7y（暂未开放），是预留位置，暂时选不了。选择后会自动帮你填好下面的 Base URL / API 类型等字段。如果你是从旧版本升级、之前保存过其他 provider 的配置，下拉框里还会额外显示你当前保存的那一项，老配置可以继续正常使用。
    2. 填 API Key（密码框，输入内容会被遮盖）。填完（或改完）后 3Studio 会自动向该 provider 拉取一次当前可用的模型列表。
    3. 填 Chat Model ID——模型列表拉取成功后，这里会先给你一个下拉框从最新模型里挑选（下拉框旁边有一个"刷新模型列表"按钮，可以随时手动重新拉取），也可以在下拉框下方的文本框里直接手填模型 ID。
      • 如果拉取失败，输入框上方会出现提示：API Key 错误或过期时显示"API Key 无效或已过期，请检查后重试"；其他网络问题会显示具体错误信息，并自动回退到内置的模型列表兜底。
      • 如果你之前保存过的模型 ID，在最新拉取结果里已经找不到了（provider 下线了这个模型），输入框上方会出现"当前模型 xxx 已不在厂商列表，请重新选择"的提示，提醒你换一个模型。
    4. 下方"Compaction"区域有一个 Context Window（tokens） 数字框，控制对话上下文的容量上限。从下拉框选模型时会自动带出该模型的默认容量；一旦你手动改过这个数字，就不再跟随模型自动变化（旁边会出现"重置为 N tokens"的按钮，点击可以恢复成所选模型的默认值，并重新变回自动跟随状态）。
    5. 更下面是一个可折叠的"高级"区域，收起时不显示；点开后能看到"聊天 Base URL"、"API 类型"（OpenAI Chat / Anthropic Messages 二选一）、"发送 Auth Header"复选框。这个区域的用途现在变窄了：它用来临时覆盖当前所选预设本身的默认值（比如预设的 Base URL 有调整、想强制切换 API 类型），不是用来接一个全新的自定义端点——接自定义端点现在请切到上面的自定义 Provider标签页。
    6. 公开 Provider 标签页也有自己的测试连接按钮（用法见下面「自定义 Provider」一节的说明，两边共用同一套自检逻辑），测试时会自动带上所选预设固定的请求头（比如 Kimi Code Plan 要求固定的 User-Agent，不带就会连接失败）。
    7. 改完之后要点 保存 Provider 按钮——3Studio 会先把配置写盘，然后自动重启背后的模型引擎（通常几秒钟，按钮会显示"保存中"），重启完成后新模型 / 新 API Key 立即生效，不需要重启整个应用。如果引擎重启失败，按钮旁会显示错误提示；此时配置其实已经保存成功，你可以重试保存，或者直接重启应用让新配置生效。有未保存的改动时按钮旁会提示"有未保存的更改"。

    ⚠️ 除了打开设置页时会拉取一次模型列表，3Studio 还会在启动时以及此后每 6 小时在后台自动向 provider 拉取一次最新模型信息：如果你的 Context Window 处于"自动跟随"状态，会被静默刷新为 provider 当前的数值（你手动改过的数值不会被这个后台过程覆盖）；如果发现你保存的模型已经从 provider 下线，后台只会记一条日志，不会自动帮你切换模型或弹通知——你会在下次打开设置页时看到上面提到的"已不在厂商列表"提示，自己决定要不要换。这条自动刷新只针对公开 Provider 标签页，自定义 Provider 的字段都是你手工填的，不会被后台改写。

  • 商业发行版（且未开启内部调试面板）：不显示上述模型配置区域，改为显示 License 区域，用于填写激活码、查看积分余额和到期重置时间；此时模型服务由 3Studio 后台代管，不需要你自己填 API Key。如果激活的授权码带有路由能力，License 区域还会多出一个开关"主订阅额度不可用时使用组织积分继续请求"——打开后，主订阅额度用完时会自动改用组织积分继续请求；如果管理员没有开启这项权限，该开关会显示为禁用状态，并在旁边提示"管理员未开启付费 API fallback"。这种发行版下看不到自定义 Provider 标签页。

自定义 Provider

自定义 Provider 标签页面向的场景是：你自己（或公司内部）用 vLLM、SGLang、Ollama、LM Studio 之类的推理引擎部署了一个开源模型，想让 3Studio 接上它。这类端点没有一个"官方预设"帮你把参数填好，所以需要你逐项手工声明。

表单分三段：

① 连接：

  • 显示名：只用于界面展示和作为内部标识，中英文都可以填。输入框下方会实时显示这个名字最终会转换成的英文 Provider ID（比如输入"内网 Qwen3"会提示将用作 qwen3）。

    ⚠️ 目前显示名本身不会单独保存，落盘的只有上面这个转换后的 Provider ID。这份原文只存在于表单当前这次挂载的内存里，不只是"关闭设置页再打开"才会丢——切到公开 Provider 标签页看一眼再切回来，这份原文也会丢，字段会显示转换后的英文形态而不是你当初填的中文原文。这只影响显示，不影响连接是否正常工作，详见 docs/tech-debt.md 的 PROV1 条目。

  • 协议：OpenAI 兼容（/v1/chat/completions，vLLM / SGLang / Ollama / LM Studio 等绝大多数自建推理引擎都是这一种）或 Anthropic 兼容（/v1/messages，比如智谱等厂商面向 Claude Code 提供的兼容端点）。选择 Anthropic 兼容后，下面的"思维链字段"会被禁用置灰——Anthropic 协议原生驱动思考过程，不需要你额外声明。
  • Base URL：要带上版本前缀，例如 http://10.0.0.8:8000/v1。
  • API Key：本地部署且未设密钥的服务可以留空。

    ⚠️ 陷阱：选择 Anthropic 兼容协议时，API Key 是必填项，留空会在保存前被拦下并提示。这不是 3Studio 刻意加的限制，而是因为它底层依赖的 Anthropic 客户端库在缺少密钥时会直接抛错——如果不在这里拦，你保存的配置会在第一次对话时必定崩溃。OpenAI 兼容协议下密钥则可以留空，未设置密钥时 3Studio 也不会发送鉴权请求头。

  • 测试连接按钮：见下面单独一节。

② 模型与能力：

  • Model ID：如果刚做过一次成功的测试连接，这里会先给一个从服务端发现的模型列表下拉框，选完还能在下方文本框里手改；没有发现结果时直接手填。
  • 上下文窗口：模型支持的总上下文长度。测试连接如果从服务端探测到这个值（vLLM 的 /v1/models 响应里带 max_model_len 字段），会自动帮你填上，检测结果面板里探测到的上下文长度那一行会注明"已填入"；一旦你手动改过这个数字，自动填充就会让位，不再覆盖你的手改值（恢复方式见下面「测试连接：作用与局限」）。
  • 输出预留 tokens：在上下文窗口里为模型输出预留的额度——可用于输入的上下文等于总窗口减去这个预留值，超出预留会触发对话历史压缩。留空则用默认值 32000。
  • 工具调用支持：勾选表示这个服务端支持返回工具调用（tool_calls）。这一项对应服务端启动参数 --enable-auto-tool-choice——如果部署时没开这个参数，这里就要取消勾选，否则 Agent 会把工具调用误判为可用，实际却拿不到任何工具调用结果。取消勾选后界面会给出红字警告：关闭工具调用后 Agent 基本无法正常工作，但这终究是你的判断，3Studio 不会因此阻止保存。测试连接如果明确判定出支持或不支持，会自动帮你勾选或取消勾选，并标注"已自动填入"；如果探测因为回复被截断而无法判断（结果显示为警告），这一项不会被自动改动，需要你自己判断（见下面「测试连接：作用与局限」）。
  • 图片输入支持：模型是否接受图片输入（多模态）。勾错会导致图片被服务端直接拒绝，纯文本模型（比如下面例子里的 GLM 5.2）不要勾选。测试连接不会探测这一项——自检请求不发图片，所以无论模型是否支持多模态，这里都需要你自己勾选。
  • 思维链字段：模型把思考过程放在响应的哪个字段里，可选无 / reasoning_content / reasoning_details。这一项对应服务端启动参数 --reasoning-parser——服务端配置了对应的解析器就照实填，没配置就选"无"。这一项在协议选择 Anthropic 兼容时不可用（见上）。测试连接如果探测到具体的字段名，会自动帮你选中并标注"已自动填入"；但如果这次探测没有看到任何思维链内容，不会把这一项设为"无"——探测请求很简短，模型很可能根本没有对这么简单的问题进行思考，看不到不等于不支持，这一项会保持原样，需要你自己判断（见下面「测试连接：作用与局限」）。

③ 高级（默认折叠）：

  • 自定义请求头：以键值对形式增删，公司内网网关常见的额外鉴权头或租户标识可以在这里加。删掉最后一条后这里会恢复成空。
  • 请求超时（毫秒）：留空用默认的 300000（5 分钟）；自建集群排队较慢时可以调大。

测试连接：作用与局限

点击"测试连接"，3Studio 会从主进程直接发起两个请求：一个 GET {Base URL}/models（验证端点可达、鉴权是否通过、能否拿到模型列表和上下文长度），一个带着一个占位工具定义的对话请求（验证真正的对话通路是否连通、返回是否包含工具调用）。这第二个请求的具体形状取决于你选的协议：OpenAI 兼容协议下是 POST /chat/completions；Anthropic 兼容协议下是 POST /messages。结果按"端点可达 / 鉴权通过 / 模型可用 / 工具调用可用 / 思维链字段"逐项展示，失败或异常的项会给出具体建议（比如提示 Base URL 可能少了 /v1，或者服务端可能缺少某个启动参数）。

测试连接如果拿到了确切结果，会顺手把「模型与能力」里对应的表单字段填上：上下文窗口、工具调用支持、思维链字段这三项，检测结果面板里对应那一行都会标注出来是自动填入的（工具调用支持和思维链字段标"已自动填入"，探测到的上下文长度标"已填入"）。端点可达、鉴权通过、模型可用这几项只做展示，不会写回任何表单字段；图片输入支持也不在自动填范围内——自检请求不发图片，无论模型是否支持多模态都需要你自己勾选。

⚠️ 只有拿到确切结果才会自动填，看不到不等于没有。 工具调用支持只有在探测明确判定「支持」或「不支持」时才会自动改动；如果探测因为回复在触发工具调用之前就被截断而无法判断（对应结果显示为警告），这一项会保持原样。思维链字段同理：探测请求非常简短，一次没看到思维链内容不代表这个端点不支持思维链——模型很可能只是没有对这么简单的问题进行思考。所以看不到思维链不会把这一项自动设为"无"，是否要手动改由你自己判断。

⚠️ 手动改过的项，本次设置页会话里不会再被自动填充覆盖——哪怕你把值改回和探测结果一致的样子，也不会重新跟随。 手改标记在打开设置页期间只会被置上，不会在会话中途自己清除；想恢复自动填充，需要先关闭设置页再重新打开。这条规则对上下文窗口、工具调用支持、思维链字段三项都成立；但如果编辑发生在测试连接还没跑完的过程中，这次探测判断用的是点击测试连接那一刻的手改标记，结束时仍可能把你刚改的值覆盖掉——之后再点一次测试连接就不会了。

⚠️ 思维链字段这一项只在 OpenAI 兼容协议下才会真正判定。 Anthropic 协议原生驱动思考过程，这一项在 Anthropic 兼容协议下不会被判为失败或警告，界面上以灰显呈现——这是预期行为，不代表探测失败，也不代表这个端点不支持思维链。

⚠️ 测试连接通过，不等于保证真实对话一定可用。 自检请求是 3Studio 主进程直接发出的，而你实际发起对话时，请求会经过 3Studio 背后的模型引擎（一个独立的 opencode 子进程）转发，两条路径的具体请求细节并不完全一致。测试连接通过是一个很强的可用性信号，但不是 100% 的保证。反过来，测试连接失败也不会阻止你保存配置——某些网关可能拒绝这种探测式请求而产生误报，是否忽略警告继续保存，由你自己判断。

一个完整的部署示例：GLM 5.2（vLLM 自建）

假设你用官方 recipe 启动了一个 vLLM 服务，启动命令里带了 --reasoning-parser glm45 --tool-call-parser glm47 --enable-auto-tool-choice，思维模式默认开启。对应到表单里应该这样填：

表单项填写
协议OpenAI 兼容（vLLM 只提供这一种协议）
Base URLhttp://<你的主机>:8000/v1
API Key留空，或填部署时 --api-key 指定的值
Model IDzai-org/GLM-5.2，或部署时 --served-model-name 指定的名字（点"测试连接"后可以从下拉框里直接选）
上下文窗口不用手填，测试连接会从 max_model_len 自动带出来
工具调用支持不用手填，测试连接探测到支持工具调用后会自动勾选；如果你的部署没加 --enable-auto-tool-choice，探测会判定为不支持并自动取消勾选
图片输入支持不勾选——GLM 5.2 是纯文本模型；测试连接不会帮你判断这一项
思维链字段不用手填，测试连接探测到 reasoning_content 后会自动选中；这次没探测到就按上面的提示自己选 reasoning_content

另一个常见陷阱：Ollama 默认上下文只有 2048。 如果你对接的是 Ollama，即便模型本身支持更长的上下文，Ollama 服务端默认也只会用 2048 个 token 的上下文窗口，多出的部分会被直接截断。这个限制在服务端而不在 3Studio 这边，需要你在部署 Ollama 时通过 num_ctx 参数调大（比如在 Modelfile 里设置，或者在请求里传参），3Studio 的"上下文窗口"字段本身只是告诉客户端这个模型有多大容量，不会反过来帮你把服务端的限制改大。

工具

MCP 服务器

MCP（Model Context Protocol）服务器是给 Agent 扩展外部工具能力的外部程序，比如接入某个专业软件或数据源。这个分区：

  • 顶部有一个"刷新"按钮，重新检测已配置服务器的连接状态。
  • "编辑配置"按钮展开一个 JSON 配置编辑器，编辑前需要先选择范围：全局（对所有工作区生效）或项目（只对当前工作区生效）；改完点"保存"。
  • 下方是已连接服务器的列表，每条显示服务器 ID、连接状态标签、所属范围（global/project）、命令或地址，以及提供的工具数量；连接出错时会额外显示错误信息。

配置文件的 JSON 格式、两个作用域的文件位置、保存后何时生效以及连接问题排查，详见《MCP 扩展工具》。

工具审批

两个独立的开关，控制 Agent 执行"风险工具"（文件编辑 / Shell 命令 / 网络请求等）前是否需要你先确认：

  • 当前项目 · Auto-approve：关闭时，运行风险工具前会先询问你；打开后，自动批准这个项目里的所有工具调用。
  • Pebble 助手 · Auto-approve：单独控制 Pebble（内置的跨项目私人助理 Agent）的审批模式，和上面"当前项目"的开关互不影响，两者可以分别设置。

两个开关切换后立即生效并自动保存，不需要额外点保存按钮。

开关切换后立即生效，不需要重启应用：切到打开（Auto-approve）时，当前对话里尚未处理的审批卡片会被自动批准，后续工具调用也不再询问；切回关闭时，从下一条消息开始恢复询问。

Python 环境（通用设置）

CAE/CAD 软件模块区域上方还有一张通用的 Python 环境 卡片，用来统一设置这些桥接程序背后依赖的基座 Python 和虚拟环境根目录，同样仅在 Windows 系统上出现；完整说明见《支持的 CAE/CAD 软件：概览与通用设置》。工具标签页顶部的分区跳转条里也有一个"Python 环境"直达入口，点击可以直接跳到这张卡片。

CAE/CAD 软件模块

这个标签最下方还会显示 MATLAB / STK / Ansys / Creo / HyperMesh / Nastran 六款专业软件的连接设置卡片，但仅在 Windows 系统上出现（在 macOS / Linux 上这部分完全不显示）。每张卡片的详细配置说明见「支持的 CAE/CAD 软件」章节：

记忆与经验

第四个标签"经验"里的开关都是立即生效自动保存的，跟 LLM 标签下"Model Provider"需要手动点"保存 Provider"不同。

  • 自动记忆抽取（开关，默认打开）：空闲时自动从对话里抽取记忆，作为后台兜底安全网；关闭它不影响你在对话过程中主动让 Agent 存记忆。
  • 梦境整理（开关，默认打开）：空闲时在后台整理已有记忆——合并重复内容、修正矛盾、删除过时事实、精简索引，每天最多执行一次。
  • 抽取 / 做梦模型（文本框）：指定抽取和梦境整理专用的模型，格式是 providerID/modelID；留空则使用你在 LLM 标签配置的主模型。填一个更便宜的模型（比如示例里给出的 anthropic/claude-haiku-4-5）可以节省 token 消耗。
  • 立即整理（按钮）：手动触发一次梦境整理，不用等到空闲时自动执行；旁边会显示"上次整理：<时间>"，从未整理过则显示"尚未整理过"。
  • 全局经验层（开关，默认打开）：把项目里积累的经验再蒸馏一层，变成跨项目通用的经验，供所有 Agent 复用。打开后如果已经有归档的全局经验条目，下方会列出条目名称、层级和证据条数，每条都有"查看"和"删除"按钮（删除前会弹窗二次确认）。

⚠️ 待核对：抽取 / 做梦模型输入框对格式没有做即时校验，填错格式（比如漏掉 /）具体会发生什么现象未在代码里确认，建议照 providerID/modelID 的格式填写。

系统通知

3Studio 会在以下几种情况下弹出你操作系统自带的通知：

  • Agent 完成一个任务时（弹"任务完成"类通知）。
  • Agent 执行任务出错时（弹"任务失败"类通知，附带错误信息）。
  • 后台任务结束时（完成 / 被手动终止 / 以其他方式结束，三种情况各对应不同的通知文案）。

前台不弹：只要 3Studio 窗口处于当前聚焦状态（也就是你正在看着这个窗口），就不会弹出系统通知——避免你正在用的时候被打断。点击一条通知会把 3Studio 窗口带到前台。

目前设置里没有可以单独关闭这些通知的开关。另外，通知标题当前固定是英文（例如 "Task Complete" "Task Failed" "Background Task Complete"），暂未跟随中文/English 界面语言切换。