配置参考

配置文件位置与结构#

主配置文件记录了工作区列表、模型连接和应用级默认值，放在配置目录下的 config.json。

多数设置可以直接在应用界面里修改；需要批量调整或排查问题时，再直接编辑这个文件。

1. 退出工作台后再编辑文件，避免运行中的写入覆盖你的改动。
2. 修改前先复制一份备份。
3. 重新启动工作台，让配置生效。

~/.zero-works/config.json

模型连接与能力配置#

llmConnections 保存连接对象；defaultLlmConnection 保存默认连接的 slug。工作区 defaults.defaultLlmConnection 可覆盖全局默认值，但已有会话仍保留自己的连接。

首条消息之后连接锁定。可以在同一连接内换模型；更换连接需新建会话。下面是合并到主配置的片段，保留原来的 workspaces、activeWorkspaceId 等字段。

• providerType: pi_compat 对应自定义兼容端点；customEndpoint.api 仅接受 openai-completions 或 anthropic-messages。
• 有 Key 的兼容服务使用 authType: api_key_with_endpoint，Key 在界面的专用凭据字段保存；本地无认证服务才用 none。
• models[].contextWindow 是上下文 token 数。图片支持按 models[].supportsImages > customEndpoint.supportsImages > false 解析，单模型 false 可以覆盖连接级 true。
• customEndpoint.maxTokens 是正整数输出上限，默认 8192，也约束压缩摘要；服务端允许时可提高来处理长会话摘要空间不足。
• midStreamBehavior 为 queue 或 steer；未指定时 anthropic 默认 queue，pi / pi_compat 默认 steer。

{
  "defaultLlmConnection": "ollama-local",
  "llmConnections": [
    {
      "slug": "ollama-local",
      "name": "Ollama local",
      "providerType": "pi_compat",
      "authType": "none",
      "baseUrl": "http://localhost:11434/v1",
      "models": [
        {
          "id": "gpt-oss:20b",
          "name": "gpt-oss:20b",
          "shortName": "gpt-oss:20b",
          "contextWindow": 131072,
          "supportsImages": false
        }
      ],
      "defaultModel": "gpt-oss:20b",
      "customEndpoint": {
        "api": "openai-completions",
        "supportsImages": false,
        "maxTokens": 8192
      },
      "midStreamBehavior": "steer",
      "createdAt": 1793059200000
    }
  ]
}

独立配置并启用决策层#

决策层使用独立的小模型处理分类、是非判断和风险提示，不会因为主对话模型已配置就自动开启。decisionLayer.enabled 默认为 false，没有用于替代总开关的环境变量。

在“设置 → AI → 决策模型”配置服务商、凭据与模型。以下是当前内置预设，不代表已经对你的账号或网络做过真实调用验收。

1. 打开决策模型设置，先选择服务商，或选择可复用 Key 的 OpenRouter / Vercel AI Gateway 连接。
2. 直接接入需 Key 的服务时，在决策模型专用字段填写并保存 Key。选择 Laya 时先启动服务；自定义服务填写实际基地址，必要时填模型覆盖值。
3. 保持总开关关闭也可以点击 Test。它发送固定示例问题，成功会显示响应模型与延迟；这只验证连通性，不代表业务分类准确率。
4. 测试成功后开启总开关，再展开 Advanced settings，逐项启用本次需要的功能；Guarded、自动化条件与自动选模都需要各自的子开关。
5. 以一条可核对的小任务验证所选功能；需要停用时关闭对应子开关或总开关。

• Laya 预设的启动提示为 pip install "laya[serve]" 后运行 laya-serve；在 Agent 所在主机启动并通过设置中的 Recheck 检查服务，再运行 Test。
• 决策请求使用 System One 协议，请求地址由 baseUrl 追加 /v1/systemone；已经包含该路径时不会重复追加。
• deadlineMs 是后台调用预算，默认 1500 毫秒，范围 250–60000；设置页的 Test 使用独立的 10000 毫秒预算。测试通过但后台超时时，检查主机性能、模型与网络，按需在配置中调整预算。
• connectionSlug 仅用于复用兼容的 OpenRouter / Vercel AI Gateway 连接，服务商随连接解析；普通聊天连接不能任意复用。
• 更换服务商或 Key 来源会清除旧的 baseUrl 与 model 覆盖，防止把新 Key 送往旧端点；切换后重新核对并测试。

{
  "decisionLayer": {
    "enabled": true,
    "provider": "laya",
    "baseUrl": "http://127.0.0.1:8000",
    "model": "auto",
    "deadlineMs": 1500,
    "features": {
      "decideTool": true,
      "taskVerdicts": true,
      "semanticLabels": true,
      "guardedMode": false,
      "automationConditions": false
    }
  }
}

决策子功能与失败回退#

总开关开启后仍按 features 逐项控制。默认只有 decideTool、taskVerdicts、semanticLabels 为 true，其他子功能为 false；它们都不会绕过已有权限或审批要求。

• 启用 Guarded 时，还需在会话权限选择器里选中该模式。活跃风险检查超时或无有效答案时会要求确认；它不能把原本需要确认的调用变成自动允许。
• 关闭决策层后不要继续把 Guarded 当成仍在进行模型风险检查；需要逐项确认时，把会话切回 Ask to Edit。
• 语义标签在层关闭、超时或回答不达阈值时不新增标签；正则规则仍可独立运行。
• 自动化语义条件属于可选筛选：关闭或判断失败时按原有路径运行，不会因决策服务不可用而自动跳过任务。需要硬性阻断时使用实际权限与调度规则。
• 自动标题、推理强度、子代理模型等可选优化在无法判断时保留原有路径。先核对总开关、对应子开关、Key 和 Test，再排查超时、额度与服务端协议。

凭据管理#

通过模型、来源和决策模型专用表单保存的 Key、OAuth 令牌等，通常写入本机加密凭据文件 credentials.enc，并按全局、连接或来源标识区分。

代理 URL 是明确例外：networkProxy 直接保存在普通 config.json，URL 中的用户名和密码不会进入加密凭据库。备份或反馈前也要检查这个字段。

1. 在对应设置表单保存凭据，并用该连接的测试入口验证。
2. 查看配置状态和连接标识即可确认归属；不要通过聊天或日志输出凭据内容。
3. 停用不再使用的连接，在对应界面删除或替换其凭据；不要为处理一条过期 Key 删除整个凭据文件。

~/.zero-works/credentials.enc

环境变量#

环境变量由启动进程读取，各变量作用域不同；不会一律覆盖所有桌面连接凭据。下表区分配置根、调试、源码 CLI run、云 SDK 与子进程网络设置。

偏好设置#

偏好文件记录个人偏好，例如称呼、时区、所在地和沟通风格。这些内容会进入 Agent 的上下文，帮助它给出更贴合你习惯的回答。

偏好文件放在配置目录下的 preferences.json。界面语言单独在设置里切换，切换后界面与回答语言会一起变化。

• name：希望被如何称呼，会出现在问候与个性化回答里。
• timezone：IANA 时区，用于今天、本周这类时间表达和任务截止时间。
• location：城市、地区与国家，用于位置相关的信息。
• notes：自由描述的回答偏好，会作为上下文提供给 Agent。

{ "name": "Alex", "timezone": "Asia/Shanghai", "location": { "city": "上海", "region": "上海", "country": "中国" }, "notes": "偏好要点式回答，技术背景较强" }

网络代理#

在企业网络、需要通过代理访问外部服务的环境里，可以让工作台的出网请求走 HTTP 或 HTTPS 代理。代理设置写在设置的网络页面，并保存到配置文件的 networkProxy 字段。

networkProxy.httpProxy 与 httpsProxy 是普通配置字符串。包含认证信息的 URL 会把口令以明文写入 config.json 及其备份，不受 credentials.enc 保护；分享配置前先移除认证部分。

不要依赖本机地址自动绕过：未匹配 noProxy 时，Node 出网请求仍会走代理。要直连本机服务，明确填写 localhost,127.0.0.1,[::1]；需要直连的内网域名也逐项加入。

{
  "networkProxy": {
    "enabled": true,
    "httpProxy": "http://proxy.example.com:8080",
    "httpsProxy": "http://proxy.example.com:8080",
    "noProxy": "localhost,127.0.0.1,[::1],.internal.example.com"
  }
}

配置校验与常见问题#

• JSON 语法错误：启动或切换工作区时会提示某个文件解析失败，先用编辑器校验 JSON 结构。
• 修改后没有生效：确认改动写入了正确路径，并新建会话或重启工作台。
• 凭据无法解密：确认是否来自另一台机器；保留原文件，并在当前机器重新保存对应连接凭据。
• 文件权限错误：把凭据文件的权限收紧到仅当前用户可读写。
• 代理能浏览但登录失败：企业代理通常会做 TLS 检查，需要用 NODE_EXTRA_CA_CERTS 指向企业 CA 证书后重试。
• 本地 MCP 连接异常：确认本地命令在运行 Agent 的机器上存在，并按需检查本地 MCP 开关。
• 决策功能没有生效：检查 decisionLayer.enabled、对应 features 开关、服务商 Key 与 Test 结果。Test 的 10 秒预算与后台 deadlineMs 不同。
• 本机端点被代理拦截：把 localhost、127.0.0.1 和实际使用的 IPv6 主机加入 noProxy，再发起新的请求。