模型与配置
Mica 通过 provider 连接模型服务。每个 provider 指定 API 地址、认证方式、协议和可选模型。模型 ID 由使用者在服务商配置中填写。
配置文件与入口
在终端输入 /config 打开配置页面,桌面应用中使用设置入口。也可以编辑 ~/.mica/config.json。首次启动会创建默认配置;设置 MICA_HOME 后,路径改为 $MICA_HOME/config.json,会话、Skills 和角色目录也随之切换。
配置文件使用标准 JSON,不支持注释。修改前保留已有 provider、MCP 和其他设置;下面的完整示例适合新建配置。将 YOUR_API_KEY 替换为实际凭证。
连接模型服务
Chat Completions 示例
下面使用仓库默认提供的 DeepSeek API 地址,并显式列出可选模型:
{
"providers": [
{
"id": "deepseek",
"api_base": "https://api.deepseek.com",
"api_key": "YOUR_API_KEY",
"protocol": "openai_chat_completions",
"models": ["deepseek-chat", "deepseek-reasoner"]
}
],
"mcpServers": {}
}Responses 示例
连接支持 OpenAI Responses 的服务时,显式选择 openai_responses。在 models 中填写账户可用、支持该协议和工具调用的模型。
{
"providers": [
{
"id": "openai",
"api_base": "https://api.openai.com/v1",
"api_key": "YOUR_API_KEY",
"protocol": "openai_responses",
"models": ["gpt-5.5"]
}
],
"mcpServers": {}
}兼容服务与模型列表
将以下对象加入 providers 数组,并替换 API 地址、凭证和模型 ID。无论服务是否提供模型列表接口,都要显式配置 models;服务不接受推理强度参数时,将 supportsEffort 设为 false。
{
"id": "local",
"api_base": "http://127.0.0.1:8000/v1",
"api_key": "YOUR_API_KEY",
"protocol": "openai_chat_completions",
"models": ["your-model-id"],
"supportsEffort": false
}新会话的默认模型
在配置页的“新会话默认模型”中设置服务商、模型和 effort,或在配置文件顶层添加defaultModel。例如:
{
"defaultModel": {
"provider": "openai",
"model": "gpt-5.5",
"effort": "high"
}
}provider 必须是已配置的服务商 ID,model 必须存在于该服务商的 models 列表。effort 可省略,此时使用模型默认档位;填写时使用模型支持的真实档位名。 不设置 defaultModel 时,自动使用第一个服务商配置的第一个模型。 新会话不再继承上次使用或当前目录记忆的模型与 effort。恢复会话沿用会话自己的设置,显式选择仍优先。
Provider 字段参考
| 字段 | 用途 |
|---|---|
id | 唯一的名称,既用于 provider/model 形式的模型 ID,也是界面上显示的名字。建议使用简短、稳定的名称。 |
api_base | 服务的 API 根地址,按服务要求保留 /v1 等路径。 |
api_key | 服务凭证。留空不会阻止界面启动,但请求仍须满足服务的认证要求。 |
protocol | openai_chat_completions 或 openai_responses,须与服务实际支持的协议一致。 |
models | 该服务商提供的模型 ID 字符串数组,至少填一个;模型列表全部手填,没有自动拉取。 |
supportsEffort | 设为 false 时不向服务发送推理强度参数。 |
effortLevels | 模型元数据未知时,按服务端真实支持的顺序声明档位,例如 ["low", "medium", "high"]。 |
选择模型与推理强度
终端使用 /model 选择模型,用 /effort 选择推理强度。可用档位就是该模型自己声明的取值: 有的模型是 minimal/low/medium/high,有的最高档叫 max, 有的只有开关(none/on)。Mica 不做档位换算,也不会给不支持推理参数的模型凑出五档。 自建网关或私有部署的模型名如果不在 models.dev 里,可在该 provider 上写 effortLevels 声明服务端真实接受的档位。桌面端在输入区的模型面板中完成同样的操作。
models.dev 用于补充模型能力和档位等元数据,不负责从你的服务商拉取模型列表;有已知模型元数据时,以模型声明的档位为准。
mica models
mica models --json上面的命令列出 provider/model ID;JSON 输出还包含可用推理强度。使用该 ID 指定一次自动化任务的模型:
mica exec --model "PROVIDER_ID/MODEL_ID" "解释项目的测试策略"需要指定强度时,先查看该模型在 mica models --json 输出中的 efforts,再添加例如 --variant high。mica exec 对显式强度严格校验:值不合法、模型没有该档位或没有声明档位时会报错; 没有可选档位时省略此参数。未知模型若确实支持强度,可按服务端支持情况配置 effortLevels。
会话内选择保存在会话状态;新会话默认值由 defaultModel 决定。写在 config.json 顶层的 model 或 effort 在保存时会被丢弃。已有对话切换 API 协议受到限制;需要切换协议时新建会话。
在自动化中使用环境变量
CI 或临时容器可以通过环境变量创建进程内的 openai provider。把 YOUR_MODEL_ID 替换为账户可用的模型名称;以下为 POSIX shell 示例:
export MICA_HOME="$HOME/.mica-ci"
export OPENAI_API_KEY="YOUR_API_KEY"
export OPENAI_BASE_URL="https://api.openai.com/v1"
export MICA_PROVIDER_PROTOCOL="openai_responses"
mica exec --model "openai/YOUR_MODEL_ID" --no-save "概述当前项目结构"这种方式仅在配置中的所有 provider 都没有非空 API key,且没有 ID 为 openai 的 provider 时生效。使用独立的 MICA_HOME 可以避免已有配置影响任务。由环境变量创建的 provider 不会写回配置文件, 也不会自动获取模型列表;调用时应像上例一样通过 --model 指定模型。
| 环境变量 | 行为 |
|---|---|
MICA_HOME | 用户数据根目录,默认 ~/.mica。 |
OPENAI_API_KEY | 环境 provider 的凭证;未设置时不创建该 provider。 |
OPENAI_BASE_URL | 环境 provider 的 API 根地址,默认 https://api.openai.com/v1。 |
MICA_PROVIDER_PROTOCOL | 仅覆盖环境 provider 的协议,默认 openai_responses。可设为上述两种协议之一。 |
SEARXNG_URL | 网络搜索插件读取的 SearXNG 地址;插件设置里填了就以它为准,留空时用这个环境变量,再退回 http://127.0.0.1:8080。 |
JSON 中的 api_key 是字面字符串,不会自动展开 $OPENAI_API_KEY 等占位符。环境认证请使用上面的独立方式。
配置网络搜索
web_search 由官方插件 web-search 提供,使用 SearXNG 实例,实例需启用 JSON 格式响应。地址在配置页的 Plugins → Web Search 中填写:插件设置里的地址优先, 留空时读取环境变量 SEARXNG_URL,两者都未提供则使用 http://127.0.0.1:8080。 这项配置保存在 $MICA_HOME/plugin-settings/web-search.json,与模型 API 分开管理,不写在 config.json。
排查连接问题
- 模型列表为空:在配置页的「服务商」里手动填入至少一个模型名,或直接写
providers[].models;保存后可用「测试连接」先确认一次。 - 认证失败:检查当前 provider 的 key 与 API 地址,环境变量不会覆盖已有的带凭证配置。
- 接口或参数不受支持:核对
protocol;不支持 reasoning 参数的服务可关闭supportsEffort。 - 更改配置后仍使用旧连接:重新选择模型,必要时重启当前客户端,并用
/status确认选择。
接下来可以 配置 MCP、Skills 和角色,或查看 自动化调用方式。