> ## Documentation Index
> Fetch the complete documentation index at: https://nextmind-85153aa2-dev.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 配置参考

> runtime.json、models.json、高级集成和环境变量

Mycel 使用拆分配置文件管理运行时默认值、模型、观测和提供商基础设施。产品运行时状态不从工作区本地 `runtime.json` 加载。

## 配置文件概览

| 文件                                | 用途                      |
| --------------------------------- | ----------------------- |
| `runtime.json`                    | 工具、记忆、高级集成、安全           |
| `models.json`                     | 模型身份、提供商、API Key、虚拟模型映射 |
| `observation.json`                | Langfuse / LangSmith 追踪 |
| `ENV_FILE`                        | 可选的显式 env 文件            |
| `$LEON_SANDBOXES_DIR/<name>.json` | 各提供商的沙箱配置               |

runtime 配置优先级：显式 server/CLI overrides → 内置默认值。

**各域合并策略：**

| 域                                       | 策略                             |
| --------------------------------------- | ------------------------------ |
| `runtime`、`memory`、`tools`              | 深度合并 — 显式 overrides 按字段覆盖内置默认值 |
| `mcp`                                   | 显式 overrides 覆盖内置默认值           |
| `system_prompt`                         | 显式 override                    |
| `providers`、`mapping`（models.json）      | 按 key 深度合并                     |
| `pool`（models.json）                     | 最后者胜 — 不合并列表                   |
| `catalog`、`virtual_models`（models.json） | 仅系统层 — 用户不可覆盖                  |

## 首次运行

在 shell 中导出变量，或在启动服务前设置 `ENV_FILE=/path/to/mycel.env`：

```env theme={null}
OPENAI_API_KEY=sk-xxx
OPENAI_BASE_URL=https://api.openai.com/v1
MODEL_NAME=claude-sonnet-4-5-20250929
```

## runtime.json

控制 Agent 行为、工具、记忆和高级集成。

```json theme={null}
{
  "context_limit": 0,
  "enable_audit_log": true,
  "allowed_extensions": null,
  "block_dangerous_commands": true,
  "block_network_commands": false,
  "temperature": null,
  "max_tokens": null,
  "memory": {
    "pruning": {
      "enabled": true,
      "soft_trim_chars": 3000,
      "hard_clear_threshold": 10000,
      "protect_recent": 3
    },
    "compaction": {
      "enabled": true,
      "reserve_tokens": 16384,
      "keep_recent_tokens": 20000,
      "min_messages": 20
    }
  },
  "system_prompt": null,
  "tools": { ... },
  "mcp": { "enabled": true, "servers": {} }
}
```

### 运行时字段

| 字段                         | 默认值   | 说明                          |
| -------------------------- | ----- | --------------------------- |
| `temperature`              | null  | 采样温度（0–2），null 表示使用模型默认值    |
| `max_tokens`               | null  | 最大输出 token 数，null 表示使用模型默认值 |
| `context_limit`            | 0     | 上下文窗口 token 数，0 表示自动检测      |
| `enable_audit_log`         | true  | 启用文件操作审计日志                  |
| `allowed_extensions`       | null  | 限制文件访问的扩展名，null 表示不限        |
| `block_dangerous_commands` | true  | 屏蔽 `rm -rf`、`sudo` 等危险命令    |
| `block_network_commands`   | false | 屏蔽网络命令                      |

### 工具

每个工具组有 `enabled` 标志和 `tools` 子对象，两者均需启用工具才可用。

**完整工具目录：**

| 工具           | 分组         | 模式       | 说明               |
| ------------ | ---------- | -------- | ---------------- |
| Read         | filesystem | inline   | 读取文件内容           |
| Write        | filesystem | inline   | 写入文件             |
| Edit         | filesystem | inline   | 编辑文件（精确替换）       |
| list\_dir    | filesystem | inline   | 列出目录             |
| Grep         | search     | inline   | 正则搜索（基于 ripgrep） |
| Glob         | search     | inline   | Glob 模式文件搜索      |
| Bash         | command    | inline   | 执行 Shell 命令      |
| WebSearch    | web        | inline   | 互联网搜索            |
| WebFetch     | web        | inline   | 抓取并提取网页内容        |
| Agent        | agent      | inline   | 派发子 Agent        |
| SendMessage  | agent      | inline   | 给另一个 Agent 发消息   |
| TaskOutput   | agent      | inline   | 获取后台任务输出         |
| TaskStop     | agent      | inline   | 停止后台任务           |
| TaskCreate   | todo       | deferred | 创建任务             |
| TaskGet      | todo       | deferred | 获取任务详情           |
| TaskList     | todo       | deferred | 列出任务             |
| TaskUpdate   | todo       | deferred | 更新任务状态           |
| load\_skill  | skills     | inline   | 加载 Skill         |
| tool\_search | system     | inline   | 发现 deferred 工具   |

`deferred` 工具不注入每次请求，Agent 在需要时通过 `tool_search` 发现。

### 项目级示例

显式 runtime overrides：

```json theme={null}
{
  "allowed_extensions": ["py", "js", "ts", "json", "yaml", "md"],
  "block_dangerous_commands": true,
  "tools": {
    "web": { "enabled": false },
    "command": {
      "tools": {
        "run_command": { "default_timeout": 300 }
      }
    }
  },
  "system_prompt": "你是一个 Python 专家，正在开发一个 FastAPI 项目。"
}
```

## models.json

控制使用哪个模型、提供商凭证和虚拟模型映射。

```json theme={null}
{
  "active": {
    "model": "claude-sonnet-4-5-20250929",
    "provider": null
  },
  "providers": {
    "anthropic": {
      "api_key": "${ANTHROPIC_API_KEY}",
      "base_url": "https://api.anthropic.com"
    },
    "openai": {
      "api_key": "${OPENAI_API_KEY}",
      "base_url": "https://api.openai.com/v1"
    }
  }
}
```

### 虚拟模型别名

Mycel 提供四个 `leon:*` 别名：

| 别名            | 对应模型                       | 适用场景    |
| ------------- | -------------------------- | ------- |
| `leon:mini`   | claude-haiku-4-5-20250929  | 快速、简单任务 |
| `leon:medium` | claude-sonnet-4-5-20250929 | 均衡、日常工作 |
| `leon:large`  | claude-opus-4-6            | 复杂推理    |
| `leon:max`    | claude-opus-4-6 + temp=0   | 最高精度    |

通过 **Settings → Models** 在 Web UI 中设置：

```json theme={null}
{ "active": { "model": "leon:large" } }
```

可通过 Settings 持久化的模型配置重新映射这些别名：

```json theme={null}
{
  "mapping": {
    "leon:medium": {
      "model": "gpt-4o",
      "provider": "openai"
    }
  }
}
```

### 提供商自动检测

未明确设置 provider 时，Mycel 从环境变量自动检测：

* 设置了 `ANTHROPIC_API_KEY` → 使用 `anthropic`
* 设置了 `OPENAI_API_KEY` → 使用 `openai`
* 设置了 `OPENROUTER_API_KEY` → 使用 `openai`（OpenRouter 兼容）

### 添加自定义模型

```json theme={null}
{
  "pool": {
    "custom": ["deepseek-chat"],
    "custom_config": {
      "deepseek-chat": {
        "based_on": "gpt-4o",
        "context_limit": 65536
      }
    }
  }
}
```

## 高级 MCP 服务器

通过 Model Context Protocol 连接外部服务（GitHub、数据库、API 等）。

```json theme={null}
{
  "mcp": {
    "enabled": true,
    "servers": {
      "github": {
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-github"],
        "env": {
          "GITHUB_TOKEN": "${GITHUB_TOKEN}"
        }
      },
      "remote-service": {
        "url": "https://mcp.example.com/sse",
        "allowed_tools": ["search", "fetch"]
      }
    }
  }
}
```

| 字段              | 说明                       |
| --------------- | ------------------------ |
| `command`       | 启动的可执行文件（stdio 传输）       |
| `args`          | 命令参数                     |
| `env`           | 传给服务器进程的环境变量             |
| `url`           | HTTP 传输的 URL（替代 command） |
| `allowed_tools` | 工具白名单，null 表示暴露所有工具      |

MCP 工具在 Agent 工具列表中显示为 `mcp__{server_name}__{tool_name}`。

本地运行配置也可以携带 `.mcp.json`。产品界面里，MCP 放在 Agent 配置页的高级集成入口。

## 可观测性（追踪）

配置 Langfuse 或 LangSmith 用于 Agent 运行追踪：

```json theme={null}
{
  "active": "langfuse",
  "langfuse": {
    "secret_key": "${LANGFUSE_SECRET_KEY}",
    "public_key": "${LANGFUSE_PUBLIC_KEY}",
    "host": "https://cloud.langfuse.com"
  },
  "langsmith": {
    "api_key": "${LANGSMITH_API_KEY}",
    "project": "mycel"
  }
}
```

将 `active` 设为 `"langfuse"`、`"langsmith"` 或 `null`（禁用）。

## 环境变量

所有 JSON 配置文件中的字符串值都支持 `${VAR}` 展开和 `~` 表示家目录。

| 变量                       | 用途                                 |
| ------------------------ | ---------------------------------- |
| `ANTHROPIC_API_KEY`      | Anthropic API Key                  |
| `OPENAI_API_KEY`         | OpenAI 兼容 API Key                  |
| `OPENAI_BASE_URL`        | API Base URL                       |
| `OPENROUTER_API_KEY`     | OpenRouter API Key                 |
| `MODEL_NAME`             | 覆盖活跃模型                             |
| `LEON_SANDBOX`           | 默认沙箱名称                             |
| `LEON_AVATAR_ROOT`       | Avatar 图片的 host-side 存储根目录         |
| `LEON_FILE_CHANNEL_ROOT` | Thread 文件上传的 host-side staging 根目录 |
| `TAVILY_API_KEY`         | Tavily 网络搜索                        |
| `EXA_API_KEY`            | Exa 搜索                             |
| `JINA_API_KEY`           | Jina AI 抓取                         |
| `E2B_API_KEY`            | E2B 沙箱                             |
| `DAYTONA_API_KEY`        | Daytona 沙箱                         |
| `AGENTBAY_API_KEY`       | AgentBay 沙箱                        |