---
title: "settings.json 与 Web 设置页"
---


`settings.json` 是 Web 设置页持久化配置的主要文件。它适合管理模型、MCP、OpenAPI、LSP、挂载、供应商、通用开关等结构化配置。

### 1、保存位置与作用域

| 作用域 | 文件 | 适用场景 |
|---|---|---|
| 全局 `user` | `~/.soloncode/settings.json` | 多个项目共享的模型、技能池、常用 MCP |
| 工作区 `workspace` | `.soloncode/settings.json` | 仅当前项目需要的模型、API、LSP、挂载 |

启动时先读取用户级，再读取工作区级。工作区配置会覆盖或补充用户级配置。

### 2、通用设置

对应字段：`general`。可配置项主要包括：

#### 会话与压缩
- `sessionWindowSize` - 会话窗口大小（新指令使用几条历史消息），默认 8
- `summaryWindowSize` - 压缩触发消息数，默认 100
- `summaryWindowToken` - 压缩触发 token 阈值
- `summaryModel` - 指定压缩使用的模型
- `compressionThresholdPercent` - 上下文压缩触发比例（按已用上下文百分比，默认 75%）

#### 安全与沙盒
- `sandboxMode` - 沙盒模式（安全隔离），默认 true
- `sandboxAllowUserHome` - 沙盒允许访问用户主目录，默认 true
- `sandboxSystemRestrict` - 沙盒使用系统接口限制，默认 false

#### 记忆
- `memoryEnabled` - 是否启用记忆，默认 true
- `memoryIsolation` - 记忆是否工作区隔离
- `memoryRelevanceCount` - 语义匹配条数，默认 6
- `memoryPriorityCount` - 重要度兜底条数，默认 5
- `memorySummaryLength` - 摘要截断长度，默认 80

#### 重试
- `apiRetries` - API 重试次数，默认 3
- `mcpRetries` - MCP 重试次数，默认 3
- `modelRetries` - 模型重试次数，默认 3

#### 功能开关
- `bashAsyncEnabled` - 是否启用异步 bash
- `mcpEnabled` - 是否启用 MCP，默认 true
- `openApiEnabled` - 是否启用 OpenAPI，默认 true
- `lspEnabled` - 是否启用 LSP，默认 true
- `goalsEnabled` - 是否启用 Goal 长任务模式，默认 true
- `subagentEnabled` - 是否启用子代理模式，默认 true
- `hitlEnabled` - 是否启用人工审核危险操作
- `autoRethink` - 是否允许自我反思重试，默认 true

#### 皮肤
- `activeSkin` - 当前激活的皮肤名称（default / eyecare / contrast 或本地安装名）

#### 执行限制
- `maxTurns` - 单任务最大执行回合数，默认 20
- `userAgent` - HTTP 请求标识（User-Agent）

#### 控制台
- `cliThinkPrinted` - 控制台是否打印内心思考
- `cliPrintSimplified` - 控制台是否简化打印，默认 true

#### Web 安全
- `webAuthUser` - Web 登录页认证用户名（留空则不启用）
- `webAuthPass` - Web 登录页认证密码

#### 日志
- `logLevel` - 日志级别（TRACE/DEBUG/INFO/WARN/ERROR），默认 INFO
- `logFileMaxSize` - 日志文件大小限制（如 "10MB"）
- `logMaxHistory` - 日志存档保留天数，默认 7

保存后，Web 设置页会尽量实时写入运行中的引擎，不一定需要重启。

#### Loop 设置
对应字段：`loop`。用于配置 Goal 长任务模式的默认行为（详见 [loop 循环任务与 Goal 模式](./1477-loop-循环任务与-Goal-模式.md)）：

- `budgetWarningPercent` - 预算警告百分比，默认 70
- `budgetCriticalPercent` - 预算紧急百分比，默认 85
- `defaultMaxTokens` - 默认 Token 预算上限，0 为不限制
- `defaultMaxDurationMinutes` - 默认时间预算上限（分钟），0 为不限制
- `stagnationThreshold` - 连续无进展轮次阈值，默认 3
- `maxConsecutiveErrors` - 连续异常阈值，默认 3
- `validatorEnabled` - 是否启用目标验证器，默认 true

![](/img/88565358f7f543b795beb1090934e6a5.png)


### 3、权限与安全

对应字段：`permission`。可配置项：

- `allowedTools` - 允许的工具列表（白名单模式）
- `disallowedTools` - 禁止的工具列表（黑名单模式）


![](/img/10386d89af2345c9afd25efc9133f9e9.png)


### 4、供应商管理

对应字段：`providers`。用于管理大模型供应商的统一配置，包括 API 地址、密钥等。在 Web 设置页中可新增、修改、启用/停用供应商。


![](/img/feaf2fe7c2724f78910169bcb3f3029f.png)

### 5、大语言模型

对应字段：`models`。主要支持：

- 新增、删除、更新模型。
- 启用或停用模型。
- 测试模型连接。
- 设置作用域：全局或工作区。
- 保存后同步刷新对话区模型列表。


![](/img/ba0ef54308644c78a701e4cc5beaab49.png)

### 6、挂载

对应字段：`mountPools`。挂载用于把外部目录作为 Skills、Agents 或普通资源池暴露给 SolonCode。主要字段：

- `alias`：别名，通常以 `@` 开头。
- `type`：挂载类型，如 `SKILLS`、`AGENTS`。
- `path`：目录路径。
- `primary`：是否作为主要池（即是否系统内置）。
- `enabled`：是否启用。
- `writeable`：是否允许写入。
- `scope`：`user` 或 `workspace`。


![](/img/d304dbcaaf2e4623bcb746b79a3c50ed.png)


### 7、技能市场

Web 设置页内置技能市场入口，可浏览、查看详情并安装 Skills。当前源码包含以下市场适配：

- Clawhub（`clawhub.ai`，默认启用）
- Skillhub（`api.skillhub.cn`，默认启用）
- Skills.sh（`skills.sh`，HTML 爬取，当前默认未启用）

安装时可以选择安装到不同技能池。支持重新安装（达到更新升级效果）。



![](/img/ca14b53b54b84de0bf9bfd6d0899dcbe.png)

### 8、MCP 服务器

对应字段：`mcpServers`。支持：

- 新增、更新、删除 MCP Server。
- 启用或停用。
- 连接检测。
- 查看服务暴露的工具。
- 保存禁用工具配置，控制可调用范围。
- 传输协议支持：stdio（本地命令）、sse（HTTP 流）、streamable。


![](/img/1ce3998732e640f6b50370643fa8285e.png)

### 9、OpenAPI 服务器

对应字段：`apiServers`。支持通过 OpenAPI 规范文档（JSON/YAML）导入 REST API，并管理接口启用状态。


![](/img/8dc1cf2cbcc2452196cb71f9c54f0f17.png)



### 10、LSP 服务器

对应字段：`lspServers`。用于配置代码语言服务。需要本机已安装对应语言服务器命令，例如 `jdtls`、`typescript-language-server`、`gopls`、`pyright-langserver` 等。内置支持 18+ 种语言服务器模板，默认禁用。


![](/img/21a6a6e219c445a3823ae34e772ad3b8.png)