AstrBot/openspec/config.md

配置规范

概述

AstrBot 配置系统遵循以下原则：

原则	说明
分离关注点	按功能域分离配置
敏感信息隔离	密钥、密码存储在独立的安全文件中
环境变量优先	密钥通过环境变量注入，不写入配置文件
分层配置	系统配置 → 平台配置 → 插件配置

相关: env.md（环境变量）, path.md（路径规范）, api.md（HTTP API）

配置域

域	配置文件	说明
安全配置	secrets.yaml	API keys、密码、JWT secrets、GPG 密钥
平台配置	platform.yaml	平台适配器设置
提供商配置	providers.yaml	LLM 提供商设置（不含密钥）
Agent 配置	agent.yaml	Agent 行为参数
系统配置	system.yaml	日志、调试、代理、API 服务器等
GPG 配置	gpg.yaml	GPG 安全配置（可选）
插件配置	plugins/	各插件独立配置

GPG 安全配置（可选）

概述

AstrBot 提供可选的 GPG 安全功能，用于配置文件的签名与验签，防止配置被篡改。

功能	说明
配置签名	对配置文件进行签名，确保完整性
配置验签	启动时验证配置文件签名，检测篡改
插件签名	验证插件包的 GPG 签名

gpg.yaml（GPG 配置）

# GPG 安全配置
# 可选功能，不启用时不影响正常功能

security:
  # GPG 功能开关
  enable: false

  # 验签模式
  # - none: 不验签
  # - warn: 验签失败仅警告
  # - enforce: 验签失败阻止启动
  verify_mode: "warn"

  # 信任的公钥指纹列表
  trusted_keys:
    - "ABCDEF1234567890..."
    - "FEDCBA0987654321..."

  # 签名的配置文件模式
  signed_configs:
    - "secrets.yaml"
    - "agent.yaml"
    - "platform.yaml"

  # 签名文件后缀
  signature_suffix: ".sig"

  # GPG 主目录（默认使用系统配置）
  gnupg_home: ""

secrets.yaml 中的 GPG 密钥

# GPG 密钥配置
gpg:
  # 私钥（用于签名）
  # 使用空字符串表示不配置
  private_key: ""
  passphrase: ""

  # 或使用 GPG Keybox 格式
  # keybox: "/path/to/s.gpg-keybox"

  # 公钥指纹（用于验签）
  fingerprint: "ABCDEF1234567890..."

配置签名与验签流程

签名流程

# 1. 首次签名
astrbot gpg sign --config secrets.yaml
astrbot gpg sign --config agent.yaml

# 2. 生成签名文件
# secrets.yaml.sig
# agent.yaml.sig

# 3. 签名文件内容（JSON 格式）
{
  "config_file": "secrets.yaml",
  "signature": "-----BEGIN PGP SIGNATURE-----...",
  "signed_at": "2026-03-26T10:00:00Z",
  "issuer": "AstrBot/1.0"
}

验签流程

启动时：
1. 检查 gpg.yaml 中 verify_mode
2. 对 signed_configs 中的每个文件：
   a. 读取配置文件
   b. 读取对应的 .sig 签名文件
   c. 使用 trusted_keys 中的公钥验签
3. 根据 verify_mode 处理结果：
   - none: 跳过验签
   - warn: 验签失败记录警告日志
   - enforce: 验签失败阻止启动并报错

目录结构

$XDG_CONFIG_HOME/astrbot/
├── gpg.yaml                    # GPG 安全配置
├── secrets.yaml                # 包含 GPG 密钥
├── secrets.yaml.sig            # 配置文件签名
├── agent.yaml
├── agent.yaml.sig
└── ...

命令行接口

# 签名配置文件
astrbot gpg sign --config <file> [--output <dir>]

# 验签配置文件
astrbot gpg verify --config <file>

# 验签所有已签名配置
astrbot gpg verify --all

# 导出公钥
astrbot gpg export --keyring <fingerprint> [--output <file>]

# 生成新密钥对
astrbot gpg generate --name "AstrBot" --email "astrbot@example.com"

安全原则

原则	说明
私钥保护	私钥仅存储在 secrets.yaml 中，不提交到版本控制
密钥分离	GPG 签名密钥与 API 密钥分离存储
验签优先	生产环境建议使用 verify_mode: enforce
密钥轮换	定期更换签名密钥并重新签名配置文件

敏感信息隔离

原则

原则	说明
密钥不上传	secrets.yaml 必须在 .gitignore 中
环境变量注入	生产环境通过环境变量注入密钥
不记录日志	配置值不写入日志

secrets.yaml

# 安全配置 - 请勿提交到版本控制
# Security config - DO NOT commit to version control

# Dashboard 凭证
dashboard:
  password: "your-hashed-password"
  jwt_secret: "your-jwt-secret"

# LLM Provider API Keys
providers:
  openai:
    api_key: "sk-..."
  anthropic:
    api_key: "sk-ant-..."
  dashscope:
    api_key: "..."

# 平台凭证
platforms:
  telegram:
    bot_token: "12345:ABC..."
  discord:
    bot_token: "..."

# 第三方服务
third_party:
  baidu_aip:
    app_id: ""
    api_key: ""
    secret_key: ""
  moonshotai:
    api_key: ""
  coze:
    api_key: ""
    bot_id: ""

# API Keys（HTTP API 服务认证）
api:
  keys:
    - id: "my-app"
      key: "sk-xxxxxxxxxxxx"
      name: "My Application"
      permissions:
        - "chat"
        - "file"
        - "message"
      rate_limit:
        requests: 100
        period: 60

环境变量注入

敏感配置通过环境变量覆盖：

# .env 或系统环境变量
ASTRBOT_DASHBOARD_PASSWORD=xxx
ASTRBOT_DASHBOARD_JWT_SECRET=xxx
ASTRBOT_PROVIDER_OPENAI_API_KEY=sk-xxx
ASTRBOT_PROVIDER_ANTHROPIC_API_KEY=sk-ant-xxx
ASTRBOT_PLATFORM_TELEGRAM_BOT_TOKEN=xxx

配置文件结构

1. system.yaml（系统配置）

# 系统配置

log:
  level: INFO                    # DEBUG, INFO, WARNING, ERROR
  file_enable: false
  file_path: logs/astrbot.log
  file_max_mb: 20
  disable_access_log: true

proxy:
  http_proxy: ""
  https_proxy: ""
  no_proxy:
    - localhost
    - 127.0.0.1

trace:
  enable: false
  log_enable: false
  log_path: logs/astrbot.trace.log

temp:
  dir_max_size: 1024            # MB

timezone: Asia/Shanghai

pypi_index_url: https://mirrors.aliyun.com/pypi/simple/
pip_install_arg: ""

# 回调配置
callback_api_base: ""

# API 服务器配置
api:
  host: "0.0.0.0"
  port: 6185
  timeout: 60
  max_body_size: 100
  rate_limit:
    default:
      requests: 100
      period: 60
    high:
      requests: 1000
      period: 60

2. platform.yaml（平台配置）

# 平台配置

# 通用平台设置
platform_settings:
  unique_session: false
  rate_limit:
    time: 60
    count: 30
    strategy: "stall"           # stall, reject
  reply_prefix: ""
  forward_threshold: 1500
  enable_id_white_list: true
  id_whitelist: []
  id_whitelist_log: true
  wl_ignore_admin_on_group: true
  wl_ignore_admin_on_friend: true
  reply_with_mention: false
  reply_with_quote: false
  path_mapping: []
  segmented_reply:
    enable: false
    only_llm_result: true
    interval_method: "random"
    interval: "1.5,3.5"
    words_count_threshold: 150
    split_mode: "regex"
    regex: ".*?[。？！~…]+|.+$"
    split_words: ["。", "？", "！", "~", "…"]
  no_permission_reply: true
  empty_mention_waiting: true
  empty_mention_waiting_need_reply: true
  friend_message_needs_wake_prefix: false
  ignore_bot_self_message: false
  ignore_at_all: false

# 平台列表
platforms: []

# 平台特定配置
platform_specific:
  lark:
    pre_ack_emoji:
      enable: false
      emojis: ["Typing"]
  telegram:
    pre_ack_emoji:
      enable: false
      emojis: ["✍️"]
  discord:
    pre_ack_emoji:
      enable: false
      emojis: ["🤔"]

3. providers.yaml（提供商配置）

# LLM 提供商配置

provider_settings:
  enable: true
  default_provider_id: ""
  fallback_chat_models: []
  default_image_caption_provider_id: ""
  image_caption_prompt: "Please describe the image using Chinese."
  provider_pool: ["*"]

# API Keys 在 secrets.yaml 中配置
# providers:
#   openai:
#     api_key: "sk-..."        # 在 secrets.yaml 中
#     model: "gpt-4"
#     base_url: ""              # 可选，自定义 endpoint

4. agent.yaml（Agent 配置）

# Agent 配置

agent_settings:
  wake_prefix: ["/"]
  default_personality: "default"
  persona_pool: ["*"]
  prompt_prefix: "{{prompt}}"

  # 上下文配置
  context_limit_reached_strategy: "truncate_by_turns"
  llm_compress_instruction: "..."
  llm_compress_keep_recent: 6
  llm_compress_provider_id: ""
  max_context_length: -1
  dequeue_context_length: 1

  # 输出配置
  streaming_response: false
  show_tool_use_status: false
  show_tool_call_result: false
  sanitize_context_by_modalities: false
  max_quoted_fallback_images: 20

  # Web Search
  web_search: false
  websearch_provider: "default"
  # websearch_tavily_key: 在 secrets.yaml 中
  # websearch_bocha_key: 在 secrets.yaml 中
  web_search_link: false

  # 标识
  identifier: false
  group_name_display: false
  datetime_system_prompt: true

  # Agent Runner
  agent_runner_type: "local"    # local, dify, coze, dashscope, deerflow
  dify_agent_runner_provider_id: ""
  coze_agent_runner_provider_id: ""
  dashscope_agent_runner_provider_id: ""
  deerflow_agent_runner_provider_id: ""

  # 工具配置
  unsupported_streaming_strategy: "realtime_segmenting"
  reachability_check: false
  max_agent_step: 30
  tool_call_timeout: 60
  tool_schema_mode: "full"

  # 安全模式
  llm_safety_mode: true
  safety_mode_strategy: "system_prompt"

  # 主动能力
  proactive_capability:
    add_cron_tools: true

  # Computer Use
  computer_use_runtime: "none"
  computer_use_require_admin: true

  # 图片压缩
  image_compress_enabled: true
  image_compress_options:
    max_size: 1024
    quality: 95

# 子 Agent 编排
subagent_orchestrator:
  main_enable: false
  remove_main_duplicate_tools: false
  router_system_prompt: "..."
  agents: []

# STT/TTS
provider_stt_settings:
  enable: false
  provider_id: ""

provider_tts_settings:
  enable: false
  provider_id: ""
  dual_output: false
  use_file_service: false
  trigger_probability: 1.0

# LTM
provider_ltm_settings:
  group_icl_enable: false
  group_message_max_cnt: 300
  image_caption: false
  image_caption_provider_id: ""
  active_reply:
    enable: false
    method: "possibility_reply"
    possibility_reply: 0.1
    whitelist: []

5. plugins/（插件配置）

各插件配置在 plugins/ 目录下，文件名与插件名对应：

plugins/
├── _conf_schema.json           # 插件配置 schema
├── my_plugin.yaml             # my_plugin 插件配置
└── another_plugin.yaml         # another_plugin 插件配置

目录结构

$XDG_CONFIG_HOME/astrbot/
├── config.yaml                  # 主配置入口
├── secrets.yaml                 # 安全配置（不提交）
├── system.yaml                  # 系统配置
├── platform.yaml                # 平台配置
├── providers.yaml               # 提供商配置
├── agent.yaml                   # Agent 配置
├── gpg.yaml                    # GPG 安全配置（可选）
├── plugins/                     # 插件配置
│   ├── _conf_schema.json        # 插件 schema
│   └── *.yaml                   # 各插件配置
└── mcp_servers.json             # MCP 服务器配置

配置加载优先级

环境变量 > secrets.yaml > config.yaml > 默认值

优先级	来源	说明
最高	环境变量	ASTRBOT_* 前缀
高	secrets.yaml	敏感信息
中	config.yaml	用户配置
低	默认值	代码中的默认值

配置迁移

旧版 cmd_config.json 迁移到新版：

旧字段	新配置文件	说明
dashboard.*	secrets.yaml	密码、JWT secret
provider_settings.websearch_*_key	secrets.yaml	API keys
platform_settings.*	platform.yaml	平台设置
provider_settings.*	providers.yaml + agent.yaml	提供商和 Agent
provider_stt/tts_settings.*	agent.yaml	STT/TTS
content_safety.baidu_aip.*	secrets.yaml	安全密钥
log_level, http_proxy	system.yaml	系统配置
plugin_set, kb_*	plugins/	插件配置

不规范示例

❌ 旧方式 - 所有配置混在一起：

{
  "dashboard": {
    "password": "plain-text-or-hashed",
    "jwt_secret": "secret-in-config"
  },
  "provider_settings": {
    "openai_api_key": "sk-xxx"
  }
}

✅ 新方式 - 分离关注点：

config/
├── secrets.yaml      # 密码、密钥
├── system.yaml       # 日志、代理
├── platform.yaml     # 平台设置
├── providers.yaml    # 提供商配置
└── agent.yaml        # Agent 配置

实施建议

1. 新增配置：新功能应按域分类到对应文件
2. 敏感信息：绝不写入 config.yaml，使用 secrets.yaml 或环境变量
3. 默认值：在代码中设置默认值，配置文件仅覆盖需要修改的项
4. Schema 验证：使用 JSON Schema 验证配置文件格式