配置表单

configSchema 声明插件需要的用户配置项。客户端据此自动渲染表单：安装带必填项的插件时弹窗填写，已安装插件可在详情页点「配置」重新填写。

完整示例

json

{
  "configSchema": {
    "fields": [
      {
        "key": "API_KEY",
        "label": "API Key",
        "labelZh": "API 密钥",
        "description": "Get it from https://example.com/api-keys",
        "descriptionZh": "从 https://example.com/api-keys 获取",
        "type": "password",
        "required": true,
        "secret": true,
        "placeholder": "sk-..."
      },
      {
        "key": "provider",
        "label": "Provider",
        "labelZh": "服务商",
        "type": "select",
        "required": true,
        "default": "stability",
        "options": [
          { "value": "dalle3", "label": "DALL-E 3", "labelZh": "DALL-E 3" },
          { "value": "stability", "label": "Stability AI", "labelZh": "Stability AI" }
        ]
      },
      {
        "key": "openai_api_key",
        "label": "OpenAI API Key",
        "labelZh": "OpenAI API 密钥",
        "type": "password",
        "required": true,
        "secret": true,
        "visibleWhen": { "field": "provider", "equals": "dalle3" }
      }
    ]
  }
}

上例实现的效果：先选服务商，只有选择 DALL-E 3 时才显示对应的 API Key 输入框。

字段参考

字段	类型	必需	说明
`key`	string	✅	配置键名（建议大写+下划线）。同时作为注入 stdio 子进程的环境变量名
`label`	string	✅	英文标签
`labelZh`	string	✅	中文标签
`description`	string	❌	英文描述（表单下方灰字提示，常用来写"去哪里申请 Key"）
`descriptionZh`	string	❌	中文描述
`type`	string	✅	字段类型，见下表
`required`	boolean	✅	是否必填
`default`	unknown	❌	默认值（`defaultValue` 为兼容别名，两者都识别）
`placeholder`	string	❌	输入框占位符
`options`	array	❌	`select` / `multiselect` 的选项，每项含 `value` / `label` / `labelZh`
`secret`	boolean	❌	`true` 时走系统安全存储，不落盘明文
`validation`	object	❌	校验规则：`min` / `max` / `pattern` / `patternMessage`
`visibleWhen`	object	❌	条件显示规则
`action`	object	❌	`type: "action"` 专属，声明按钮行为
`presetModels`	string[]	❌	`fetchModels` 动作的预设模型列表
`rows`	number	❌	`textarea` / `code` 的渲染高度
`language`	string	❌	`code` 的语法高亮标识（`json` / `yaml` …）

字段类型

类型	渲染	备注
`text`	单行输入框
`password`	密码输入框（掩码）	与 `secret: true` 搭配使用
`number`	数字输入框
`boolean`	开关	注入子进程时为字符串 `true` / `false`
`select`	下拉单选	需提供 `options`
`multiselect`	下拉多选	需提供 `options`
`textarea`	多行文本框	用 `rows` 控制高度
`code`	代码编辑器（等宽字体）	用 `language` 指定高亮
`action`	按钮	触发 `action.kind` 对应的处理器

条件显示

visibleWhen 支持两种匹配方式（equals 优先，二者互斥）：

json

{ "visibleWhen": { "field": "provider", "equals": "dalle3" } }

json

{ "visibleWhen": { "field": "mode", "in": ["cloud", "hybrid"] } }

没有 visibleWhen 的字段始终显示。

动作按钮

type: "action" 的字段渲染为按钮，用于"测试连接""拉取模型列表"这类交互。

json

{
  "key": "fetch_models_btn",
  "label": "Fetch Models",
  "labelZh": "获取模型列表",
  "type": "action",
  "required": false,
  "action": {
    "kind": "fetchModels",
    "buttonText": "Fetch Models",
    "buttonTextZh": "获取模型列表",
    "targetField": "model",
    "params": { "baseUrl": "{base_url}", "apiKey": "{api_key}" }
  }
}

属性	说明
`kind`	动作标识，用于匹配处理器
`buttonText` / `buttonTextZh`	按钮文案
`targetField`	执行结果写入哪个字段（如模型列表写入 `model`）
`params`	传给处理器的参数映射：值形如 `{fieldKey}` 时取当前表单值，其他按字面量传递

内置 kind：

kind	行为
`fetchModels`	拉取模型列表并填入 `targetField`；也可用 `presetModels` 提供静态列表而免于发起请求
`testConnection`	测试连接连通性

插件也可以自定义 kind：在 ui.js 的 configActions 中按 kind 注册处理器，即可实现任意按钮逻辑（详见 UI 扩展）。

密钥安全

secret: true 的字段值通过系统安全存储保存，不落盘明文：

平台	存储后端
macOS	Keychain
Windows	Credential Manager
Linux	Secret Service

密钥只在运行时通过环境变量注入到 stdio 子进程内存，或由 in-process 插件通过 ctx.getSecret(key) 读取。后端不存储用户密钥，密钥仅存在于用户本机。

配置注入机制

1. 环境变量注入

每个字段以 key 作为环境变量名注入。stdio 子进程内直接读 process.env：

javascript

const API_KEY = process.env.API_KEY

字段未填写且非必填时，环境变量不会被注入，代码里需要给默认值。

2. args / env 模板替换

capabilities.mcp.args 与 env 中可用 config.KEY 引用配置值：

json

{
  "capabilities": {
    "mcp": {
      "transport": "stdio",
      "command": "node",
      "args": ["{{pluginDir}}/index.js"],
      "env": {
        "API_KEY": "{{config.API_KEY}}",
        "LOG_LEVEL": "debug"
      }
    }
  }
}

3. in-process 插件读取配置

in-process 插件不走环境变量，改用上下文 API：

typescript

const config = ctx.getConfig()               // 全部配置（Record<string, unknown>）
const apiKey = await ctx.getSecret('API_KEY') // 安全存储中的密钥
ctx.logger.info('plugin initialized', config.provider)

设计建议

必填项越少越好：每个必填项都是安装流程的一个阻碍。能给出合理默认值的不要设为必填。
key 保持大写+下划线：它同时是环境变量名，写成 apiKey 在 Unix 环境下易与保留变量混淆。
描述写清获取路径：descriptionZh 里给出申请 Key 的入口，能显著减少用户求助。
成对出现：password 类型几乎总该配 secret: true，否则值会以明文写入配置文件。
善用 visibleWhen：多服务商插件把各家的密钥字段按选中项隐藏，表单不会显得冗长。

下一步

工具插件开发 — 读取配置的完整代码
UI 扩展 — 自定义 action 处理器
常见问题 — 配置没生效怎么排查

配置表单 ​

完整示例 ​

字段参考 ​

字段类型 ​

条件显示 ​

动作按钮 ​

密钥安全 ​

配置注入机制 ​

1. 环境变量注入 ​

2. args / env 模板替换 ​

3. in-process 插件读取配置 ​

设计建议 ​

下一步 ​

配置表单

完整示例

字段参考

字段类型

条件显示

动作按钮

密钥安全

配置注入机制

1. 环境变量注入

2. args / env 模板替换

3. in-process 插件读取配置

设计建议

下一步