配置概览

Alius 将项目配置存储在 .alius/config/ 中。每个文件处理特定的配置领域，你可以通过 TUI 内嵌的 /config、/model、/init 命令交互式管理，也可以直接编辑文件。

文件用途
config.toml主配置——运行时元数据、默认模型/提供商、UI、Session、日志
providers.toml提供商定义、兼容路由层、本地模型库、Base URL 和 API Key
model.tomlPlan/Execute/Review 三角色模型分配
soul.tomlAgent 身份（Agent Card 兼容配置）
tools.toml内置/MCP/插件/工作流工具、超时、确认和注册设置
permissions.toml文件系统、Shell、网络、记忆、项目文档和远程 A2A 权限
protocol.toml协议接口启用和事件/命令设置
mcp.jsonMCP 服务器声明

初始化进度保存在 .alius/runtime/init-state.toml（独立于配置文件），不是配置文件的一部分。

提供商配置

providers.toml 是最核心的配置文件之一，包含提供商定义、兼容路由层和本地模型库。

内置提供商

Alius 内置以下提供商：

提供商标识产品标签OpenAI 兼容 Base URLAnthropic 兼容 Base URL
bigmodelBigModel GLM（智谱 Coding Plan）https://open.bigmodel.cn/api/coding/paas/v4https://open.bigmodel.cn/api/anthropic
xiaomi_mimo小米 MiMo（Token Plan）https://api.xiaomimimo.com/v1https://api.xiaomimimo.com/anthropic
deepseekDeepSeekhttps://api.deepseek.comhttps://api.deepseek.com/anthropic

提供商配置结构

[router]
strategy = "tier"
default = "medium"

[tiers.light]        # Plan Model 对应层
model = "glm-4-flash"
provider = "bigmodel"

[tiers.medium]       # Execute Model 对应层
model = "glm-4-plus"
provider = "bigmodel"

[tiers.high]         # Review Model 对应层
model = "glm-4"
provider = "bigmodel"

[providers.bigmodel]
kind = "openai"
base_url = "https://open.bigmodel.cn/api/coding/paas/v4"
api_key_env = "BIGMODEL_API_KEY"
enabled = true

本地模型库

providers.toml 中的 [[model_library.models]] 段存储项目级模型条目，由 /model 管理、由 /config 分配。

每个模型条目包含：

字段说明
id稳定条目 ID，通常由提供商和模型名派生
display_name面向用户的模型标签
provider匹配 [providers.<name>] 的提供商标识
base_url该模型条目使用的 Base URL
model_name发送到运行时的提供商原生模型 ID
reasoning_note兼容性注释
enabled是否可选择该条目

示例：

[[model_library.models]]
id = "bigmodel_glm-4-flash"
display_name = "GLM-4-Flash"
provider = "bigmodel"
base_url = "https://open.bigmodel.cn/api/coding/paas/v4"
model_name = "glm-4-flash"
enabled = true

模型分配

model.toml 存储三角色模型分配架构：

schema_version = 1

[assignment]
plan = "bigmodel_glm-4-flash"      # Plan Model
execute = "bigmodel_glm-4-plus"     # Execute Model
review = "bigmodel_glm-4"          # Review Model
角色说明兼容映射
Plan Model用于目标理解和计划生成tiers.light
Execute Model用于计划执行和工具调用tiers.medium + 活跃遗留模型
Review Model用于结果审查和质量评估tiers.high + 遗留 review_model

/config 只从已启用的本地模型库条目中分配角色。不允许在分配流程中手动输入模型名、Base URL 或 API Key。

API Key 管理

API Key 通过以下方式提供：

  1. 环境变量（推荐）— 在提供商配置中指定 api_key_env，如 BIGMODEL_API_KEY
  2. 交互式输入 — 在 /model 或 /init 的添加流程中直接输入（明文，支持粘贴）

保存后的 API Key 不会在会话输出或模型详情中显示。成功的 /init 模型获取也会将 API Key 写入活跃运行时设置，确保 Bypass/Chat 模式不会报告缺少 api_key。

修改配置

交互式配置

在工作空间内使用斜杠命令：

/config          # 打开配置中心（模型/语言/Soul）
/model           # 打开模型池管理器
/init            # 重新运行初始化向导

所有配置操作即时生效，无需保存按钮。

命令行

alius config show        # 显示当前配置
alius config validate    # 验证配置完整性
alius config credential  # 管理凭证

全局参数

alius --model gpt-4o-mini --provider openai

配置加载

Alius 的配置加载流程：

  1. 从当前目录向上搜索 .alius/ 找到项目根
  2. 从 .alius/config/ 加载配置文件
  3. 缺少的文件使用默认值
  4. 生成 ProjectConfigSnapshot
  5. 构建运行时视图 RuntimeConfigView（包含提供商、工具、权限、Shell Gate、日志、Session 和 Soul 配置）

安全说明

  • API Key 通过环境变量引用，绝不以明文存储在配置文件中
  • config show 命令会遮盖敏感值
  • 文件写入和 Shell 操作受 permissions.toml 和 Shell Gate 控制