配置参考

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：

OPENAI_API_KEY=sk-xxx
OPENAI_BASE_URL=https://api.openai.com/v1
MODEL_NAME=claude-sonnet-4-5-20250929

runtime.json

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

{
  "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：

{
  "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

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

{
  "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 中设置：

{ "active": { "model": "leon:large" } }

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

{
  "mapping": {
    "leon:medium": {
      "model": "gpt-4o",
      "provider": "openai"
    }
  }
}

提供商自动检测

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

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

添加自定义模型

{
  "pool": {
    "custom": ["deepseek-chat"],
    "custom_config": {
      "deepseek-chat": {
        "based_on": "gpt-4o",
        "context_limit": 65536
      }
    }
  }
}

高级 MCP 服务器

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

{
  "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 运行追踪：

{
  "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 沙箱

快速开始

核心概念

部署

配置参考

配置文件概览

首次运行

runtime.json

运行时字段

工具

项目级示例

models.json

虚拟模型别名

提供商自动检测

添加自定义模型

高级 MCP 服务器

可观测性（追踪）

环境变量

​配置文件概览

​首次运行

​runtime.json

​运行时字段

​工具

​项目级示例

​models.json

​虚拟模型别名

​提供商自动检测

​添加自定义模型

​高级 MCP 服务器

​可观测性（追踪）

​环境变量

配置文件概览

首次运行

runtime.json

运行时字段

工具

项目级示例

models.json

虚拟模型别名

提供商自动检测

添加自定义模型

高级 MCP 服务器

可观测性（追踪）

环境变量