SolonCode CLI 安装后，配置文件位于 `~/.soloncode/config.yml`。


### 1、核心配置项

| 配置项 | 默认值 | 描述 |
|--------|--------|------|
| `tools` | `**` | 启用工具配置（`**` = 所有工具；`*` = 仅公域工具） |
| `disallowedTools` | / | 禁用工具配置（需要具体的名字，不支持 `*`），子代理也会受其控制 |
| `maxSteps` | `30` | 根代理最大循环步数 |
| `autoRethink` | `true` | 自我反思（每超过 maxSteps后，会由 LLM 自我反思决定是结束或继续） |
| `sessionWindowSize` | `8` | 会话历史窗口大小（新指令时使用几条历史消息） |
| `summaryWindowSize` | `15` | 触发摘要压缩的消息条数阈值 |
| `summaryWindowToken` | `15000` | 触发摘要压缩的内容长度阈值 |


### 2、安全与行为配置

| 配置项 | 默认值 | 描述 |
|--------|--------|------|
| `sandboxMode` | `true` | 沙盒模式，启用时禁止访问绝对路径（只能访问工作区与用户主目录） |
| `thinkPrinted` | `true` | 是否打印 AI 的内心思考（建议关掉，关闭后输出更简洁） |
| `hitlEnabled` | `false` | 是否启用人工审核（危险操作需人工确认） |
| `subagentEnabled` | `true` | 是否启用子代理模式（自动委派任务给专家代理） |


### 3、行为重试配置

| 配置项 | 默认值 | 描述 |
|--------|--------|------|
| `modelRetries` | `3` | 模型 请求失败后重试次数（coding plan 用户，可以调大一点） |
| `mcpRetries` | `3` | MCP 请求失败后重试次数 |
| `apiRetries` | `3` |  API 请求失败后重试次数（适用于所有 http api 请求） |



### 4、CLI 控制台配置

| 配置项 | 默认值 | 描述 |
|--------|--------|------|
| `cliPrintSimplified` | `true` | 是否简化打印（工具调用结果显示为一行） |


### 5、工具权限配置选择（tools）

| 工具名 | 类型 | 描述 |
|--------|------|------|
| `**` | - | 所有公域 + 私域工具 |
| `*` | - | 仅所有公域工具 |
| `pi` | - | 微形命令行工具（包括工具：read, write, edit, bash） |
| | |
| `hitl` | 私域 | 人工介入审核 |
| `generate` | 私域 | 动态生成子代理 |
| `restapi` | 私域 | Web 服务 API 接入 |
| `mcp` | 私域 | MCP 服务接入 |
| | | |
| `code` | 公域 | 编码指引（自动分析项目类型、编译指令等） |
| `lsp` | 公域 | LSP服务（提升代码编辑器的智能感知能力） |
| `codesearch` | 公域 | 网络代码搜索 |
| `websearch` | 公域 | 网络搜索 |
| `webfetch` | 公域 | 网页内容抓取 |
| `todo` | 公域 | 任务清单管理 |
| `skill` | 公域 | 专家技能调用 |
| `task` | 公域 | 子代理任务委派 |
| `bash` | 公域 | Shell 命令执行 |
| `ls` | 公域 | 列出目录内容 |
| `grep` | 公域 | 递归内容搜索 |
| `glob` | 公域 | 通配符文件搜索 |
| `edit` | 公域 | 文件编辑（含 write、edit、read） |
| `read` | 公域 | 读取文件内容 |

**示例：限制危险操作**

```yaml
soloncode:
  tools: "*,read,edit"  # 仅公域工具 + 文件读写
```


### 6、上下文大小优化

影响上下文大小的因素：

| 因素 | 说明 |
|------|------|
| `AGENTS.md` | 系统提示词，建议控制在 200 行以内 |
| `tools` | 工具越多，上下文占用越大 |
| `apiServers` / `mcpServers` / `lspServers` | 扩展接口会转换为工具 |
| `sessionWindowSize` | 历史消息加载越多，占用越大 |
| `maxSteps` | 执行步数越多，累计占用越大（但会有摘要压缩控制） |

**优化建议：**

- 大上下文模型（如 GPT-4-turbo）：调大 `summaryWindowSize` 和 `summaryWindowToken`
- 小上下文模型：调小这两个参数，更频繁地触发摘要压缩


### 7、models 模型配置

支持所有主流大模型 API（注意 apiUrl 是全地址，不是 baseUrl）：

```yaml
soloncode:
  models:
    - name: "bigmodel-glm5.1" #名字（管理用）。可选
      description: "Bigmodel coding plan（更新更强些）" #描述（管理和 llm 选的对参考用）。可选
      apiUrl: "https://open.bigmodel.cn/api/anthropic/v1/messages"
      apiKey: "***"
      model: "GLM-5.1"
      timeout: "300s"
      userAgent: "Mozilla/5.0 AppleWebKit/537.36 (KHTML, like Gecko; compatible; SolonCode/1.0; +https://solon.noear.org/)"
    - name: "aliyun-kimi2.5"
      description: "Aliyun coding plan（适合简单任务）"
      apiUrl: "https://coding.dashscope.aliyuncs.com/v1/chat/completions"
      apiKey: "***"
      model: "kimi-2.5"
      timeout: "300s"
      userAgent: "Mozilla/5.0 AppleWebKit/537.36 (KHTML, like Gecko; compatible; SolonCode/1.0; +https://solon.noear.org/)"
```

详细配置参考：[《模型配置与请求选项》](/article/1087)。关于 apiUrl 可以参考：[《支持哪些模型？及方言定制》](/article/926)。


### 8、完整配置示例

```yaml
solon.logging.appender:
  console:
    enable: false  # 控制台日志（启用会干扰 CLI）
  file:
    level: DEBUG

soloncode:
  # 核心配置
  tools: "**"
  # disallowedTools: "bash"
  maxSteps: 20
  autoRethink: true
  sessionWindowSize: 8
  summaryWindowSize: 15
  summaryWindowToken: 15000

  # 安全配置
  sandboxMode: true
  thinkPrinted: true
  hitlEnabled: false
  subagentEnabled: true

  # CLI 配置
  cliPrintSimplified: true
  
  # 技能池或只读文件池（可选）
  skillPools:
    "@shared": "/path/to/shared-skills"

  # AI 模型配置
  modelRetries: 3
  models:
    - apiUrl: "https://api.deepseek.com/v1/chat/completions"
      apiKey: "sk-xxxxxx"
      model: "deepseek-chat"
      timeout: "120s"

  # REST API 接入（可选）
  apiRetries: 3
  apiServers:
    api1:
      docUrl: "https://api.example.com/openapi.json"
      apiBaseUrl: "https://api.example.com"
      headers: { Authorization: "Bearer xxx" }

  # MCP 服务接入（可选）
  mcpRetries: 3
  mcpServers:
    memory:
      command: "npx"
      args: [ "-y", "@modelcontextprotocol/server-memory" ]
      
  # LSP 服务接入（可选）
  lspServers:
    java:
      command: ["jdtls", "-data", ".solon/lsp/java-workspace"]
      extensions: [".java"]
    typescript:
      command: ["typescript-language-server", "--stdio"]
      extensions: [".ts", ".tsx", ".js", ".jsx"]
    go:
      command: ["gopls"]
      extensions: [".go"]
    python:
      command: ["pylsp"]
      extensions: [".py"]
```