Agent 配置¶

Agent 配置定义 Datus Agent 的核心设置，包括默认目标模型与整个系统可用的 LLM 提供方。

结构¶

目标模型（target）¶

在未单独覆盖时，所有节点默认使用 target 指向的 LLM 设置：

agent:
  target: openai

响应语言（language）¶

language 是可选字段，用于把所有 agentic 节点的面向用户自然语言输出统一到指定语言，覆盖：回答文本、总结、澄清提问、通过 task 工具调用子 agent 时写入的 prompt、以及写入文件的注释与说明。代码、SQL、表/列标识符、文件路径、URL、JSON key 等机器可读成分保持原样。

若不填写该字段，系统不会向 system prompt 注入任何语言指令，模型将自行根据上下文选择回答语言。

agent:
  # 完全省略该字段即可让模型自行决定语言。
  # 填写语言码即可固定所有 agentic 节点的输出语言：
  language: zh   # 常用取值：en, zh, ja, ko, es, fr, de, pt, ru, it

内置语言码映射：en → English、zh / zh-cn → Chinese、zh-tw → Traditional Chinese、ja → Japanese、ko → Korean、es → Spanish、fr → French、de → German、pt → Portuguese、ru → Russian、it → Italian。未知代码将原样注入 system prompt，方便扩展。

Chat API 请求可通过请求体中的 language 字段按任务覆盖该默认值（详见 Chat API）。CLI 无覆盖参数，直接沿用 yaml 中的默认。

模型提供方（models）¶

为智能体配置可用的 LLM 提供方：

每个提供方条目的必填参数：

提供方键名 (models.<key>) —— 逻辑标识符，由 agent.target 和节点 model 字段引用（可自定义命名）
type：接口类型（与厂商适配）
base_url：接口基础地址
api_key：访问密钥（支持环境变量）
model：具体模型名
ssl_verify（可选）：该端点的 TLS 校验方式。true（默认）、false（关闭校验，不推荐）、指向 CA 证书包（PEM）的路径，或直接内联 CA 证书内容（以 -----BEGIN CERTIFICATE----- 开头的值），以信任私有/自签名网关 CA。优先级高于 SSL_VERIFY / SSL_CERT_FILE 环境变量。参见私有或自签名证书。

agent:
  target: provider_name
  models:
    provider_name:
      type: provider_type
      base_url: https://api.example.com/v1
      api_key: ${API_KEY_ENV_VAR}
      model: model-name

环境变量

建议通过环境变量管理敏感信息：

api_key: ${YOUR_API_KEY}
# 不建议在生产中明文写入
api_key: "sk-your-actual-key-here"

私有或自签名证书¶

当 Datus 连接的是内部 LLM 网关或测试环境，而其 TLS 证书由私有 CA（不在公共信任库中）签发时，请求会失败并报错：

litellm.InternalServerError: AnthropicException - [SSL: CERTIFICATE_VERIFY_FAILED]
certificate verify failed: self-signed certificate in certificate chain

根因是 Python 自带的 certifi 信任库只包含公共 CA，且不会读取操作系统信任库，因此私有 CA 永远不会被自动信任。正确做法是让 Datus 信任该 CA 证书包，而不是关闭校验：

agent:
  models:
    claude-staging:
      type: claude
      base_url: https://ai.internal.example.com
      api_key: ${ANTHROPIC_API_KEY}
      model: claude-3-7-sonnet
      ssl_verify: /etc/ssl/internal-ca.pem   # 信任私有 CA，校验保持开启

ssl_verify 也可直接内联 CA 证书内容（任何以 -----BEGIN CERTIFICATE----- 开头的值），无需在磁盘上放置文件——当配置是由程序生成（例如来自数据库）而非与 .pem 一起部署时尤其有用：

      ssl_verify: |
        -----BEGIN CERTIFICATE-----
        MIIB...snip...IDAQAB
        -----END CERTIFICATE-----

原生客户端会把内联内容加载进内存信任库；litellm 代码路径只接受 CA 证书包的路径，因此会将其落到一个进程私有目录下、按内容哈希命名的临时文件。

解析优先级（取首个命中项）：

ssl_verify（agent.yml）  →  SSL_VERIFY 环境变量  →  SSL_CERT_FILE 环境变量  →  certifi 默认

ssl_verify 是项目级配置，优先级高于环境变量。
标准的 SSL_CERT_FILE / SSL_VERIFY 环境变量可作为免配置的替代方案（例如 IT 在机器层面统一下发 CA 路径时）。
提取服务端 CA 证书链： openssl s_client -showcerts -connect host:443 </dev/null | openssl x509 -outform PEM > ca.pem

切勿关闭校验

ssl_verify: false（或 SSL_VERIFY=false）会完全关闭 TLS 证书校验，使连接暴露于中间人攻击。请勿关闭校验，务必通过信任 CA 证书包来解决证书问题。

支持的提供方¶

初始化/配置向导中的 provider，最终都会写入 agent.models，并通过 agent.target 指定默认模型。也就是说：

你在 datus-agent configure 里选择的 provider 名称，就是 agent.models.<provider> 的键名
你也可以在后续手动编辑 agent.yml，把某个节点单独切换到另一套模型配置

通用 provider¶

提供方	典型模型	接口类型	认证方式
`openai`	`gpt-5.2`、`gpt-4.1`、`o3`	`openai`	API Key
`deepseek`	`deepseek-chat`、`deepseek-reasoner`	`deepseek`	API Key
`claude`	`claude-sonnet-4-5`、`claude-opus-4-5`	`claude`	API Key
`kimi`	`kimi-k2.5`、`kimi-k2-thinking`	`kimi`	API Key
`qwen`	`qwen3-max`、`qwen3-coder-plus`	`openai`	API Key
`gemini`	`gemini-2.5-flash`、`gemini-2.5-pro`	`gemini`	API Key
`minimax`	`MiniMax-M2.7`、`MiniMax-M2.5`	`minimax`	API Key
`glm`	`glm-5`、`glm-4.7`	`glm`	API Key
`openrouter`	`anthropic/claude-sonnet-4`、`openai/gpt-4o`	`openrouter`	API Key

OpenRouter —— 一把 Key，300+ 模型

openrouter 是统一网关：一个 OPENROUTER_API_KEY 即可路由到任意厂商。其模型名采用 vendor/slug 形式（如 google/gemini-2.5-pro）。/model 选择器会拉取 OpenRouter 的完整在线目录，并支持输入关键字过滤。

特殊认证 provider¶

提供方	接口类型	认证方式	说明
`claude_subscription`	`claude`	Claude 订阅 token	优先自动探测本地订阅凭据，失败时可手动粘贴 `sk-ant-oat01-...`
`codex`	`codex`	OAuth	读取本地 Codex OAuth 凭据并校验连通性

Coding Plan provider¶

这些 provider 面向编码/规划类 endpoint。虽然它们的名字里带 coding，但在配置层面和普通 provider 没有区别，仍然可以作为 agent.target 或节点级 model 使用。

提供方	默认模型	接口类型	说明
`alibaba_coding`	`qwen3-coder-plus`	`claude`	阿里云 DashScope 的 Anthropic-compatible coding endpoint
`bigmodel_coding`	`glm-5.1`	`claude`	智谱 BigModel 的 Anthropic-compatible coding endpoint
`zai_coding`	`glm-5.1`	`claude`	Z.AI 国际版的 Anthropic-compatible coding endpoint
`minimax_coding`	`MiniMax-M2.7`	`claude`	MiniMax 的 Anthropic-compatible coding endpoint
`kimi_coding`	`kimi-for-coding`	`claude`	Kimi 的 coding endpoint

如何选择 coding plan provider

如果你更看重通用问答、SQL 生成和成本控制，通常优先选择常规 provider。

如果你希望默认模型更偏向规划、代码生成、结构化拆解，或者你会频繁使用计划模式，可以额外配置一个 *_coding provider，并按节点切换使用。

与环境变量的关系¶

所有 provider 的 api_key 都支持环境变量，例如：

api_key: ${OPENAI_API_KEY}

对于 OpenAI、DeepSeek、Claude、Kimi、Qwen、Gemini、OpenRouter，配置向导会自动提示对应环境变量（如 ${OPENROUTER_API_KEY}）。对于 minimax、glm 和各类 *_coding provider，你也可以在输入 API Key 时直接填入 ${MINIMAX_API_KEY}、${GLM_API_KEY}、${KIMI_API_KEY}、${DASHSCOPE_API_KEY} 这类环境变量引用。

另外，当前实现会对少数模型自动补充固定参数覆盖：

kimi-k2.5：自动设置 temperature: 1.0、top_p: 0.95
qwen3-coder-plus：自动设置 temperature: 1.0、top_p: 0.95

配置示例¶

OpenAI

openai:
  type: openai
  base_url: https://api.openai.com/v1
  api_key: ${OPENAI_API_KEY}
  model: gpt-5.2

Anthropic Claude

claude:
  type: claude
  base_url: https://api.anthropic.com
  api_key: ${ANTHROPIC_API_KEY}
  model: claude-sonnet-4-5

DeepSeek

deepseek:
  type: deepseek
  base_url: https://api.deepseek.com
  api_key: ${DEEPSEEK_API_KEY}
  model: deepseek-chat

Google Gemini

gemini:
  type: gemini
  base_url: https://generativelanguage.googleapis.com/v1beta
  api_key: ${GEMINI_API_KEY}
  model: gemini-2.5-flash

Kimi (Moonshot)

kimi:
  type: kimi
  base_url: https://api.moonshot.cn/v1
  api_key: ${KIMI_API_KEY}
  model: kimi-k2.5

Qwen (Alibaba)

qwen:
  type: openai
  base_url: https://dashscope.aliyuncs.com/compatible-mode/v1
  api_key: ${DASHSCOPE_API_KEY}
  model: qwen3-max

OpenRouter

openrouter:
  type: openrouter
  base_url: https://openrouter.ai/api/v1
  api_key: ${OPENROUTER_API_KEY}
  model: anthropic/claude-sonnet-4   # vendor/slug 形式

Alibaba Coding Plan

alibaba_coding:
  type: claude
  base_url: https://coding-intl.dashscope.aliyuncs.com/apps/anthropic
  api_key: ${DASHSCOPE_API_KEY}
  model: qwen3-coder-plus
  temperature: 1.0
  top_p: 0.95

Claude Subscription

claude_subscription:
  type: claude
  base_url: https://api.anthropic.com
  api_key: ${CLAUDE_CODE_OAUTH_TOKEN}
  model: claude-sonnet-4-6
  auth_type: subscription

Codex

codex:
  type: codex
  base_url: https://chatgpt.com/backend-api/codex
  api_key: ${CODEX_OAUTH_TOKEN}
  model: codex-mini-latest
  auth_type: oauth

Agentic Nodes¶

agent.agentic_nodes 用于配置 chat 和各类 subagent 的行为。

这部分配置会被用于：

chat、explore、gen_sql、gen_report、gen_dashboard、scheduler 等内置 agentic 节点
通过统一 agent TUI（/agent 或 /subagent）创建的自定义 subagent
把自定义名称 alias 到某个内置节点类的高级手工配置

常见字段¶

当前运行时会读取这些常见字段：

model：引用 agent.models 中的 provider key
system_prompt：subagent 名称 / 提示词模板基名
node_class：要使用的节点实现，例如 gen_sql、gen_report、explore、gen_table、gen_skill、gen_dashboard、scheduler
prompt_version、prompt_language
agent_description
tools、mcp、skills
rules
max_turns
workspace_root
scoped_context
subagents
dashboard agent 使用的 bi_platform
scheduler 节点使用的 scheduler_service

语义适配器选择统一配置在 agent.services.semantic_layer。旧的 node 级 semantic_adapter 和 authoring_format 字段会被忽略。

scoped_kb_path 已废弃。新配置使用共享的全局存储，并在查询时应用过滤，而不是为每个 subagent 持有独立 scoped KB 目录。

`subagents` 委派控制¶

subagents 决定该节点是否暴露 task() 工具，以及允许委派到哪些 subagent 类型。

subagents: "*"：允许委派到所有可发现的 subagent（排除自己）
subagents: explore, gen_sql：只允许委派到指定子集
为空或省略时：
chat 默认是 *
多数其他 agentic 节点默认是 explore
显式写成空值时可禁用委派

`scoped_context`¶

scoped_context 用来限制 subagent 在共享元数据和知识库里可见的范围：

scoped_context:
  datasource: finance
  tables: mart.finance_daily, mart.finance_budget
  metrics: finance.revenue.daily_revenue
  sqls: finance.revenue.region_rollup

手工写 YAML 时请显式填写 datasource。统一 agent TUI 的 Custom Tab 向导会自动从当前数据库填充该值。

示例¶

agent:
  agentic_nodes:
    chat:
      model: claude
      max_turns: 50
      subagents: "*"

    finance_report:
      node_class: gen_report
      model: claude
      system_prompt: finance_report
      prompt_version: "1.0"
      prompt_language: en
      agent_description: "财务分析助手"
      tools: semantic_tools.*, db_tools.*, context_search_tools.list_subject_tree
      subagents: explore, gen_sql
      max_turns: 30
      scoped_context:
        datasource: finance
        tables: mart.finance_daily
        metrics: finance.revenue.daily_revenue
        sqls: finance.revenue.region_rollup

    sales_dashboard:
      node_class: gen_dashboard
      model: claude
      bi_platform: superset
      max_turns: 30

    semantic_metrics:
      node_class: gen_metrics
      model: claude
      max_turns: 30

    etl_scheduler:
      node_class: scheduler
      model: claude
      scheduler_service: airflow_prod
      max_turns: 30

上下文压缩（在长会话中自动运行的 minor/major 压缩，使会话保持在模型上下文窗口内）通过 agent.compact 配置。其工作方式与可调参数见上下文压缩。

完整示例¶

datus-config.yaml

agent:
  target: alibaba_coding
  models:
    openai:
      type: openai
      base_url: https://api.openai.com/v1
      api_key: ${OPENAI_API_KEY}
      model: gpt-5.2

    gemini:
      type: gemini
      base_url: https://generativelanguage.googleapis.com/v1beta
      api_key: ${GEMINI_API_KEY}
      model: gemini-2.5-flash

    claude:
      type: claude
      base_url: https://api.anthropic.com
      api_key: ${ANTHROPIC_API_KEY}
      model: claude-sonnet-4-5

    deepseek:
      type: deepseek
      base_url: https://api.deepseek.com
      api_key: ${DEEPSEEK_API_KEY}
      model: deepseek-chat

    alibaba_coding:
      type: claude
      base_url: https://coding-intl.dashscope.aliyuncs.com/apps/anthropic
      api_key: ${DASHSCOPE_API_KEY}
      model: qwen3-coder-plus
      temperature: 1.0
      top_p: 0.95