配置参考

本页是 zhin.config.yml 的完整参考。第一次配置时，先运行 npx zhin setup 生成一份能启动的配置，再回来查需要改的字段。

最常见的修改

我想……	看这里
换 HTTP 端口、让外网访问 Console	http
接入数据库	database
给插件或适配器填配置、填平台凭据	plugin 与 plugins
一个适配器登录多个账号	endpoints 数组
设置 master、命令前缀	适配器实例
配置 AI 模型	ai，或直接看 AI 总览
引用 `.env` 里的密钥	环境变量展开
看一份完整的最小配置	最小配置

配置文件的位置

启动时 zhin runtime start 会在项目根目录找配置文件，按下面的顺序找到第一个就停；同时存在多个则直接报错，不会帮你猜：

config.yml
config.yaml
config.json
zhin.config.yml
zhin.config.yaml
zhin.config.json

建议统一用 zhin.config.yml，本文的示例都以它为准。

需要逐字段核对类型、必填项、默认值与插件 Schema 时，请使用自动生成配置字段参考。该页面由 Runtime 源码与插件的单一配置声明（config: Schema.object(...) 或 schema.json）生成，并由 CI 阻止漂移。

这份参考怎么用

提交前运行 npx zhin doctor 检查。启动后以 Console 显示的实际运行状态为准——配置文件写了什么，不等于已经生效了什么（例如新配置校验失败时，运行中的仍是旧配置）。

你要改变什么	应该放在哪里
安装哪些插件与 Feature	`package.json#zhin` 与依赖
Host、插件实例与 AI 参数	`zhin.config.yml`
密钥与环境差异	`.env` / `.env.<环境>`，由 `${VAR}` 引用
Workroom、成员与群/仓库绑定	持久 Workroom Catalog，通过 Console 管理
当前运行时到底发布了什么	Console 的 Endpoint、能力目录与 generation 状态

主配置使用 configVersion: 2。先安装依赖，再在 plugins 映射实例名与包，业务参数放在顶层同名块；disable_plugins 列出停用实例。Feature 需求仍在 package.json#zhin.features。旧配置请先阅读迁移指南。

加载与校验流程

配置文件会经过 JSON Schema 校验，顶层只允许下文列出的键。键名写错会在启动时报 Invalid Plugin config in zhin.config.yml。

Host 键由 CLI 装配层消费；每个插件只收到顶层同名块的业务值，不会收到其他实例的配置。

环境变量展开

字符串值中的 ${VAR}、${VAR:-default}、${VAR:=default} 会被展开：

yaml

http:
  token: ${HTTP_TOKEN:-dev-token}   # 未设置 HTTP_TOKEN 时回退为 dev-token

变量未设置且没有默认值时会展开为空字符串。对 apiKey 等字段，这会触发 AI provider 的 soft-prune。

dotenv 按 .env → .env.<环境> 加载。环境名由 --environment 指定，默认 development。密钥一律走环境变量，不要硬编码进配置文件。

顶层键

键	类型	说明
`log_level`	string \| number	日志级别（如 `info`、`debug`）；`ZHIN_LOG_LEVEL` / `LOG_LEVEL` 环境变量可临时覆盖
`http`	object	HTTP Host（Console / API 入口）
`database`	object	数据库
`speech`	object	语音 STT/TTS（需安装 `@zhin.js/speech`）
`assistant`	object	Assistant Runtime（调度任务 / 事件 API）
`ai`	object	AI 栈（需安装 `@zhin.js/agent` 等，见下文）
`mcp`	object	MCP Host（把 bot 工具暴露为 MCP Server）
`a2a`	object	A2A Host（Agent Card / 远程 Agent 互调）
`htmlRenderer`	object	Shotium HTML 渲染（如 `width` / `viewport` / `scale`）
`menuKeyword`	string \| false	内置菜单关键词；默认 `菜单`，`false` 或空字符串关闭
`menuStyle`	object	菜单标题、副标题、强调色与背景图；渲染能力可用时生效
`plugin`	object	Root Plugin（应用自身）的配置
`configVersion`	number	必须为 2
`plugins`	object	实例名到插件包的映射
`disable_plugins`	string[]	停用实例名，配置仍保留
`<instanceKey>`	object	已声明实例的业务配置

http

yaml

http:
  port: 8086                 # Runtime 无配置时的回退值
  host: 127.0.0.1            # 默认 127.0.0.1
  token: ${HTTP_TOKEN}       # API Bearer 令牌
  corsOrigins:               # 允许的跨域来源
    - "https://console.zhin.dev"
  base: /api                 # API 挂载路径

Runtime 无配置时回退到 8086；当前脚手架生成的项目默认写入 8068。以项目配置和启动日志为准。

token 未设置时本地开发可直接访问；生产环境务必设置。tokens 支持按作用域配置多枚令牌。

database

推荐让 CLI 同时生成配置引用和 .env 连接参数：

bash

npx zhin setup --database
npx zhin config check

setup 会把非敏感结构写入 zhin.config.yml，把实际连接值写入项目根目录 .env。Runtime 先读取 .env，再用所选环境的 .env.<environment> 覆盖同名变量；例如生产启动使用 zhin runtime start --mode production --no-watch 默认读取 .env.production；显式传入 --environment <name> 可选择其他环境覆盖层。

SQLite

yaml

database:
  dialect: sqlite            # 默认 sqlite
  filename: ./data/bot.db

完全不写 database 时，默认使用 <项目根>/.zhin/data.sqlite。SQLite 使用 Node 内置驱动，不需要连接环境变量。

PostgreSQL

配置中的方言名是 pg（不是 postgres）：

yaml

database:
  dialect: pg
  host: ${DB_HOST}
  port: ${DB_PORT}
  user: ${DB_USER}
  password: ${DB_PASSWORD}
  database: ${DB_DATABASE}

dotenv

DB_HOST=127.0.0.1
DB_PORT=5432
DB_USER=postgres
DB_PASSWORD=change-me
DB_DATABASE=zhin_bot

DB_PORT 只写端口数字，不要写 http://、主机名或 host:port。目标数据库 DB_DATABASE 必须已经创建，并允许 DB_USER 从 Bot 所在机器连接。在容器中运行 Bot 时，127.0.0.1 指向容器自身，应改成 PostgreSQL 服务名或宿主机可访问地址。

其他方言

CLI 的数据库选择项会同时显示当前支持的服务端实机验收版本与生成项目使用的驱动版本：

方言	当前支持（实机验收版本）	生成的驱动依赖
`sqlite`	Node.js 内置 `node:sqlite`（Node.js 22.5+）	无
`mysql`	MySQL 8.4 LTS	`mysql2 ^3.23.2`
`pg`	PostgreSQL 17	`pg ^8.22.0`
`mongodb`	MongoDB 8	`mongodb ^7.5.0`
`redis`	Redis 8	`redis ^6.1.0`
`memory`	Zhin 内置实现	无

“实机验收基线”表示维护测试覆盖的明确版本，不表示驱动只能连接这一版服务端；更宽的兼容范围由对应驱动和数据库服务端协议共同决定。

方言	配置字段	CLI 生成的环境变量
`mysql`	`host`、`port`、`user`、`password`、`database`	`DB_HOST`、`DB_PORT`（默认 `3306`）、`DB_USER`、`DB_PASSWORD`、`DB_DATABASE`
`mongodb`	`url`、`dbName`	`DB_URL`（如 `mongodb://127.0.0.1:27017`）、`DB_NAME`
`redis`	`socket.host`、`socket.port`、`password`、`database`	`REDIS_HOST`、`REDIS_PORT`（默认 `6379`）、`REDIS_PASSWORD`、`REDIS_DB`
`memory`	无	无

网络数据库对应的驱动依赖分别是 mysql2、pg、mongodb、redis；通过创建项目或 zhin setup --database 选择数据库时，CLI 会按上表把经过验收的驱动版本写入 package.json。 create-zhin-app 会自动安装依赖；zhin setup 会提示你随后手动运行 pnpm install。

启动前运行 npx zhin config check；若连接值只在 .env.production，请运行 npx zhin config check --environment production。数据库环境变量缺失会作为错误报告；端口为空、非整数或超出 1-65535 时，Runtime 会在加载驱动前指出具体配置路径和 .env 变量。若旧版本出现 ERR_SOCKET_BAD_PORT / Received type number (NaN)，通常是 ${DB_PORT} 未在项目根目录 .env 中设置；补齐变量或重新运行 npx zhin setup --database。

speech

yaml

speech:
  stt: { provider: ollama, model: whisper, host: http://localhost:11434 }
  tts: { provider: edge, voice: zh-CN-XiaoxiaoNeural }

配置后启用语音管道，并向 Agent 暴露 voice_stt / voice_tts 工具。@zhin.js/speech 是 optional peer，需自行安装。

assistant

yaml

assistant:
  enabled: true                    # 启用统一 JobStore，默认 false
  profile:
    enabled: true
    file: assistant.profile.yml    # profile 文件，驱动调度任务
  events:
    enabled: true                  # 开放 POST /api/assistant/events
    rateLimitPerMinute: 60         # 默认 60
  defaults:
    notifyOnFailure: false         # Job 失败时是否通知，默认 false

其余子键：queue（Schedule execution 的并发/重试/超时）。任务事实固定持久化到 schedule-jobs.json，可用 zhin schedule 管理。

mcp / a2a

yaml

mcp:
  enabled: true
  path: /mcp
  token: ${HTTP_TOKEN}                  # 未设时回退 http.token
  allowUnauthenticatedLocalhost: false  # 生产建议 false

a2a:
  enabled: true
  path: /a2a

两段都挂在 HTTP Host 上，按需启用；未配置时对应 SDK 不会被加载。Workroom 远程执行使用 a2a.workroomCallbacks 与 a2a.workroomRemoteExecutors 的固定代级 transport binding（A2A 扩展，已冻结并移出 @zhin.js/workroom 包根，子路径 @zhin.js/workroom/remote；仅 transport 配置按需生效，默认装配仍会创建其内部占位 Remote Callback Runtime 与 Remote Assignment Authority，留到 C2 之后处理）；Project/成员/群绑定不放在这里，而由持久 Workroom Catalog 管理。完整示例见 GitHub 上的 @zhin.js/a2a README。

ai

ai 段由 Agent Host 消费。只要配置了 ai / assistant 任一段，启动图就会加载 Agent 栈；缺凭据的 provider 会被 soft-prune，不阻断启动。

providers：命名模型服务商

yaml

ai:
  providers:
    deepseek:
      sdk: deepseek                  # 必填
      apiKey: ${DEEP_SEEK_API_KEY}
    openrouter:
      sdk: openai-compatible
      baseUrl: ${OPENROUTER_BASE_URL}
      apiKey: ${OPENROUTER_API_KEY}
      contextWindow: 32768
      models:                        # 可用模型白名单
        - "openrouter/free"
    ollama-local:
      sdk: ollama
      host: http://127.0.0.1:11434   # ollama 用 host 而非 baseUrl
    cloudflare:
      sdk: openai-compatible
      apiKey: ${CLOUDFLARE_API_TOKEN}
      accountId: ${CLOUDFLARE_ACCOUNT_ID}

字段	说明
`sdk`	必填，七种之一：`openai`、`anthropic`、`google`、`deepseek`、`minimax`、`ollama`、`openai-compatible`
`apiKey` / `baseUrl` / `host`	凭据与接入点；`ollama` 用 `host`，Cloudflare 另需 `accountId`
`models`	显式模型列表
`defaultModel`、`contextWindow`、`timeout`、`maxRetries`、`firstChunkTimeoutMs`、`chunkTimeoutMs`、`headers`	行为微调（见 AI 文档）
`authScheme`	Authorization 头方案；不写用 SDK 默认，`''` 只发 key，`Bearer` / `Token` 发 `<scheme> <key>`
`imageGeneration`	文生图默认（支持该能力的 driver，如 `defaultModel`、`defaultSize`、`watermarkEnabled`、`promptSuffix`）

provider 别名可任意命名；未显式写 sdk 时会按别名前缀推断（如 deepseek-main → deepseek），推断不出则回退 openai-compatible。对应 @ai-sdk/* 包是 optional peer，按所用 sdk 自行安装。

agents：绑定模型与角色

yaml

ai:
  agents:
    zhin:                            # 主 Agent，默认入口
      provider: openrouter           # 引用 providers 的别名
      model: openrouter/free
      mcpServers: [icqq]             # 引用 ai.mcpServers 的 name
    researcher:
      provider: openrouter
      model: openrouter/free
      nickname: '搜搜'               # Agent 自称与界面展示名

字段	说明
`provider` / `model`	必填，绑定的 provider 别名与模型
`nickname`	Agent 自称与界面展示名
`mcpServers`	该 Agent 可见的 MCP Server 名列表
`permission.task`	`spawn_task` 可见子 Agent 类型（glob → `allow` / `deny`）

IM 消息总是交给 zhin。priority / match 已弃用（从未生效），zhin config check --fix 会删除，详见 ai.agents。

mcpServers：外部 MCP Server

yaml

ai:
  mcpServers:
    - name: icqq
      transport: streamable-http     # stdio | streamable-http | sse
      url: ${ICQQ_MCP_URL}
      headers:
        Authorization: Bearer ${ICQQ_MCP_TOKEN}
    - name: local-tools
      transport: stdio
      command: npx
      args: ["-y", "some-mcp-server"]
      env: { FOO: bar }

连接成功后，这些 Server 的工具进入 Agent 工具池（按 agents.<name>.mcpServers 分配）。

其余 ai 子段

yaml

ai:
  sessions:                # 会话存储
    maxHistory: 200        # 数据库模式默认 200，内存模式默认 100
    expireMs: 604800000    # 数据库模式默认 7 天，内存模式默认 24h
    useDatabase: true      # 默认 true；使用 Database Root Host（未写 database 时为 .zhin/data.sqlite）
  context:                 # 群聊上下文记录
    enabled: true
    maxRecentMessages: 100
    summaryThreshold: 50
    keepAfterSummary: 10
    maxContextTokens: 4000
  memory:                  # 三层 Markdown 文件记忆，默认启用
    semantic:
      enabled: true        # 语义记忆：generation-owned memory_search/memory_upsert；要求 Database Host
      autoConsolidate: false
      recall:              # 每轮 BM25 召回，默认开启
        topK: 5
        maxTokens: 400
    # 启用后 memory_entries 必须在候选代激活时可用，否则该代 fail-closed、不发布
    # memoryMcp 已弃用；语义记忆由上述原生 memory_search / memory_upsert 提供
  access:                  # AI 访问控制
    mode: open             # open | closed | whitelist，默认 open
    users: []              # whitelist 模式下允许的用户 id
    groups: []
    denyMessage: ...
  agent:                   # 工具执行安全
    inboundQueue:
      groupMode: supersede # supersede（默认）| fifo
    execSecurity: allowlist    # deny | allowlist | full
    execPreset: readonly       # readonly | network | development | custom
    execAllowlist: ["^ls ", "^cat "]
    maxIterations: 15          # 单回合最大工具迭代轮次，默认 15
    thinkingPreview: false     # Activity 反馈展示 LLM 实际 thinking 内容（截断），而非静态 "思考中..."，默认 false
    thinkingPreviewMaxLength: 200  # thinkingPreview 展示的最大字符数，默认 200
  trigger:                 # AI 触发规则
    prefixes: ["ai:"]          # 触发前缀，默认 ['#', 'AI:', 'ai:']
    respondToAt: true          # 响应 @机器人，默认 true
    respondToPrivate: true     # 私聊免前缀直达，默认 true
    ignorePrefixes: ['/', '!', '！']  # 避免与命令冲突
    timeout: 60000

ai.multimodal 管理多模态入出站；主模型不能看图时可用 ai.multimodal.perception 让另一个模型先描述图片，见 AI · ai.multimodal.perception。仅在显式配置 ai.knowledge.baseDir 时发布 knowledge_search；该目录必须位于项目根目录内。

远程 Agent 不再通过 ai.remoteAgents 旁路接入。可选 A2A Executor 只通过持久 Workroom Catalog 和 generation-owned authority 接入，并服从 Assignment lease/fence 与 Journal 契约。

ai.workrooms 已删除。Project、成员和协作空间由 Console 的持久化 Workroom Catalog 管理，保存后通过 revision CAS 立即生效，不需要重启运行时。

plugin 与 plugins

yaml

configVersion: 2
# Root Plugin（应用自身）的配置，键由应用的 config schema 决定
plugin:
  terminal:
    interactive: true

# 子插件配置，键为 instanceKey
plugins:
  sandbox: "@zhin.js/adapter-sandbox"
sandbox:
  endpoints:
    - id: sandbox-bot
      owner: sandbox-user

instanceKey 默认取包名最后一段，并移除 adapter- / plugin- / service- 前缀。例如 @zhin.js/adapter-icqq → icqq。

zhin install 将包引用写入 plugins.<instanceKey>，业务参数写入顶层 <instanceKey>；不再写入包清单的旧挂载数组。

适配器实例：master / trusted / commandPrefix

平台适配器插件的实例配置支持三个通用键：

键	位置	说明
`master`	实例顶层	Endpoint Owner：用于权限判定与显式 `/approve` 管理命令的稳定用户 id
`trusted`	实例顶层 / endpoints 逐项	受信任用户 id 列表；数组或空白/逗号分隔字符串
`commandPrefix`	实例顶层 / endpoints 逐项	命令前缀，默认 `''`；endpoints 逐项的值覆盖顶层

endpoints 数组：一个实例挂多个账号

多账号适配器用 endpoints 数组声明多个 Endpoint：

yaml

configVersion: 2
plugins:
  icqq: "@zhin.js/adapter-icqq"
icqq:
  master: "${ICQQ_MASTER}" # 顶层共享：所有 endpoint 生效
  endpoints:
    # 逐项：name 必填，其余字段与顶层合并（逐项优先）
    - name: "${ICQQ_ACCOUNT_1}"
    - name: "${ICQQ_ACCOUNT_2}"

展开规则（@zhin.js/adapter 的 expandEndpointConfigs）：

每个 endpoint 的最终配置 = 实例配置（去掉 endpoints 键）与该项的浅合并，逐项字段覆盖顶层。
name 必填且为非空字符串；不含 ~；重名只保留首个并告警。
endpoints 为空或全部非法时，退回单 Endpoint（名为 instanceKey）。

真实示例（QQ 官方 bot，主账号走代理网关 + 沙箱账号并存）：

yaml

configVersion: 2
plugins:
  qq: "@zhin.js/adapter-qq"
  slack: "@zhin.js/adapter-slack"
qq:
  endpoints:
    - name: zhin
      appid: "${QQ_APPID}"
      secret: "${QQ_SECRET}"
      mode: websocket
      sandbox: false
      gatewayUrl: "https://bots.example.com/gateway/102005927"
      intents: [ GUILDS, GROUP_AND_C2C_EVENT, PUBLIC_GUILD_MESSAGES ]
    - name: "102069707"
      appid: "${QQ_SANDBOX_APPID}"
      secret: "${QQ_SANDBOX_SECRET}"
      mode: websocket
      sandbox: true
      intents: [ GUILDS, GROUP_AND_C2C_EVENT ]
slack:
  endpoints:
    - name: zhin
      token: "${SLACK_TOKEN}"
      appToken: "${SLACK_APP_TOKEN}"
      signingSecret: "${SLACK_SIGNING_SECRET}"
      socketMode: true

各适配器自己的字段（appid、intents、socketMode、url、access_token 等）见对应适配器包的 README。

最小配置

不写任何 Host 段也能跑——这是 examples/minimal-bot 的全部配置：

yaml

configVersion: 2
plugin:
  terminal:
    interactive: true

plugins: {}

启动后按 zhin setup 向导逐步补齐 database / 适配器 / AI（见 CLI 参考）；运行方式见 zhin runtime start 详解。

配置参考 ​

最常见的修改 ​

配置文件的位置 ​

这份参考怎么用 ​

加载与校验流程 ​

环境变量展开 ​

顶层键 ​

http ​

database ​

SQLite ​

PostgreSQL ​

其他方言 ​

speech ​

assistant ​

mcp / a2a ​

ai ​

providers：命名模型服务商 ​

agents：绑定模型与角色 ​

mcpServers：外部 MCP Server ​

其余 ai 子段 ​

plugin 与 plugins ​

适配器实例：master / trusted / commandPrefix ​

endpoints 数组：一个实例挂多个账号 ​

最小配置 ​

配置参考

最常见的修改

配置文件的位置

这份参考怎么用

加载与校验流程

环境变量展开

顶层键

http

database

SQLite

PostgreSQL

其他方言

speech

assistant

mcp / a2a

ai

providers：命名模型服务商

agents：绑定模型与角色

mcpServers：外部 MCP Server

其余 ai 子段

plugin 与 plugins

适配器实例：master / trusted / commandPrefix

endpoints 数组：一个实例挂多个账号

最小配置