Plano 配置参考：详解 plano_config.yml 完整字段与网关行为控制-平芜编程栈

Plano 配置参考：详解 plano_config.yml 完整字段与网关行为控制

【免费下载链接】planoPlano is an AI-native proxy server and data plane for agentic apps. Smart LLM routing, observability, agent orchestration, and guardrails so you stay focused on your agents core logic.项目地址: https://gitcode.com/GitHub_Trending/ar/plano

本指南是 Plano 网关单实例配置文件plano_config.yml的完整参考手册，覆盖模型提供商（model_providers）与上游请求头配置、prompt_targets 路由目标、guardrails 护栏、代理可观测性等全部能力开关。读完本文，你将掌握每个顶级配置块的字段含义、取值范围、默认值及其底层实现逻辑，能够独立编写一份可运行的生产级 Plano 配置文件，并理解配置如何驱动 LLM 路由、Agent 编排与追踪导出。

配置总览：一份文件控制整个数据平面

plano_config.yml是 Plano 网关（AI-native proxy server 与 agentic apps 数据平面）的核心配置文件，它决定了一次请求从监听端口进入后，如何被路由到上游 LLM 提供商、如何命中 prompt_targets、如何经过 filter 与 guardrail 链，以及最终如何被追踪与计费。

与配置直接对应的 JSON Schema 位于 config/plano_config_schema.yaml，Schema 中明确要求顶级必须包含version与listeners两个字段，其余均为可选。version字段的可选枚举值为v0.1、v0.1.0、0.1-beta、0.2.0、v0.3.0、v0.4.0，参考配置文件当前使用v0.4.0：

version: v0.4.0

一个典型的最小配置由以下几大块构成：外部 Agent 注册（agents）、MCP 过滤器（filters）、LLM 提供商（model_providers）、HTTP 监听器（listeners）、可复用端点（endpoints）、提示词目标（prompt_targets），以及可选的路由偏好、限流、状态存储、护栏与追踪配置。下面按功能逐一展开。

model_providers：上游 LLM 提供商与请求头配置

model_providers（旧版别名为llm_providers，仅作向后兼容保留）是配置中的核心块，每个条目声明一个可被路由到的上游模型。源码中对应的结构体为LlmProvider，定义在 crates/common/src/configuration.rs，包含name、provider_interface、access_key、model、default、passthrough_auth、headers等字段。

headers：附加到上游请求的 HTTP 头

每个model_providers条目都可以携带一个headers映射，用于向 Plano 转发到上游 LLM 的请求中追加额外的 HTTP 请求头。

类型：字符串映射（header 名 → 值）
可选性：可选
常见用途：某些 API 强制要求的User-Agent值、组织（organization）或账户（account）标识符，以及其他上游服务期望携带的元数据请求头

需要特别强调的是执行顺序：Plano 会先根据access_key或passthrough_auth设置认证信息，之后才应用headers中的追加头。这意味着你可以在headers中提供提供商相关的元数据，而不会覆盖已配置的凭据。源码中该字段类型为Option<HashMap<String, String>>（见 crates/common/src/configuration.rs），即任意数量的键值对都受支持。

原文档给出的标准示例——为 MoonshotAI 的 Kimi for Coding 配置User-Agent：

model_providers: - model: moonshotai/kimi-for-coding access_key: $MOONSHOTAI_API_KEY base_url: https://api.kimi.com/coding/v1 headers: User-Agent: "KimiCLI/1.3"

access_key支持$ENV_VAR形式的环境变量引用，密钥本身不直接写死在配置文件中。而base_url则用于覆盖该模型的默认服务地址，适合接入兼容 OpenAI 协议的自建网关或第三方中转。

其他提供商级字段

在完整参考配置文件 docs/source/resources/includes/plano_config_full_reference.yaml 中，一个提供商条目可以组合使用以下字段：

字段	说明	示例值
`model`	完整模型名（provider/model）	`openai/gpt-4o`
`access_key`	API 密钥，支持`$ENV_VAR`	`$OPENAI_API_KEY`
`default`	是否为默认模型（未显式指定时兜底）	`true`
`base_url`	覆盖上游服务地址	`https://litellm.example.com`
`passthrough_auth`	透传客户端`Authorization`头而非使用`access_key`	`true`
`http_host`	显式覆盖上游`Host`头	`api.custom-provider.com`
`headers`	附加请求头（认证之后应用）	`User-Agent: "KimiCLI/1.3"`
`provider_interface`	上游协议接口	`openai`、`anthropic`、`gemini`等

其中passthrough_auth特别适合 LiteLLM 这类代理场景——由 LiteLLM 自行校验虚拟密钥，Plano 只负责把客户端的认证头原样转发，参考配置中对应的示例为：

- model: openai/gpt-4o-litellm base_url: https://litellm.example.com passthrough_auth: true

http_host则用于自定义或自托管端点，当上游要求Host头与地址分离时使用：

- model: openai/llama-3.3-70b base_url: https://api.custom-provider.com http_host: api.custom-provider.com access_key: $CUSTOM_API_KEY

Schema 中provider_interface的枚举值包括plano、deepseek、groq、mistral、openai、xiaomi、gemini、chatgpt、digitalocean、vercel、openrouter、edenai、moonshotai（见 config/plano_config_schema.yaml），覆盖了绝大多数主流模型服务商。此外，旧版将routing_preferences内联在提供商条目下的写法已标记为 DEPRECATED，配置生成器会自动将其迁移到顶级routing_preferences列表，新配置应直接在顶层声明。

model_aliases：友好名称替代完整模型名

model_aliases允许为常用模型定义简短别名，客户端在请求中可直接使用别名而非完整 provider/model 名称：

model_aliases: fast-llm: target: gpt-4o-mini smart-llm: target: gpt-4o

Schema 要求每个别名条目必须包含target字段（config/plano_config_schema.yaml）。别名机制让上层应用与底层模型选择解耦——调整模型时只需修改配置中的target，无需改动客户端代码。

routing_preferences 与 model_metrics_sources：意图驱动的智能模型路由

routing_preferences是顶层列表，将命名任务类别与一组有序的候选模型池绑定。Plano 的 LLM 路由器会把入站请求与这些描述进行语义匹配，返回一个有序模型列表；客户端以models[0]为主模型，在遇到 429/5xx 时依次用models[1]、models[2]重试。

routing_preferences: - name: code generation description: generating new code snippets, functions, or boilerplate based on user prompts or requirements models: - anthropic/claude-sonnet-4-0 - openai/gpt-4o - groq/llama-3.3-70b-versatile - name: code review description: reviewing, analyzing, and suggesting improvements to existing code models: - anthropic/claude-sonnet-4-0 - groq/llama-3.3-70b-versatile selection_policy: prefer: cheapest

使用routing_preferences有两个前置条件：

每个models中的模型必须已在model_providers中声明；
overrides.llm_routing_model必须指向 Plano-Orchestrator（或同等能力的路由模型）。

selection_policy.prefer是可选字段，取值为cheapest、fastest或none（默认）。设置后路由器会利用来自model_metrics_sources的实时成本/延迟数据对候选模型重新排序。

model_metrics_sources声明路由器读取的外部目录，用于支持selection_policy：

model_metrics_sources: - type: cost provider: models.dev url: https://models.dev/api.json # optional; omit to use the provider default refresh_interval: 3600 # optional, seconds model_aliases: # optional: catalog key -> Plano model name openai/gpt-oss-120b: openai/gpt-4o - type: latency provider: prometheus url: http://prometheus:9090 query: avg by (model_name) (rate(plano_llm_latency_seconds_sum[5m])) refresh_interval: 60

cost类型的数据源支持models.dev与digitalocean两种 provider（不写url时使用各自默认目录），用于支撑prefer: cheapest的排序；latency类型使用 Prometheus 查询，用于支撑prefer: fastest。refresh_interval控制目录刷新周期，model_aliases用于把目录中的 key 映射到 Plano 侧模型名（例如openai/gpt-oss-120b→openai/gpt-4o）。

listeners：网关的三种流量入口

listeners是配置中除version外的另一个必填块，定义了网关对外暴露的监听端口。Schema 支持三种type：model、prompt、agent，且提供旧版ingress_traffic/egress_traffic对象格式的兼容（已弃用，建议使用列表格式）。

agent 监听器：多 Agent 请求路由

- type: agent name: travel_booking_service port: 8001 router: plano_orchestrator_v1 address: 0.0.0.0 agents: - id: rag_agent description: virtual assistant for retrieval augmented generation tasks input_filters: - input_guards

router指定使用的编排器（当前枚举值为plano_orchestrator_v1），每个子 agent 条目包含id、description（供编排器做语义选择）、可选default标记与input_filters列表。API 类型由请求路径控制：/v1/responses、/v1/messages、/v1/chat/completions。

model 监听器：直接 LLM 访问

- type: model name: model_1 address: 0.0.0.0 port: 12000 timeout: 30s # Request timeout (e.g. "30s", "60s") max_retries: 3 # Number of retries on upstream failure input_filters: # Filters applied before forwarding to LLM - input_guards output_filters: # Filters applied to LLM responses before returning to client - input_guards

timeout控制请求超时（字符串形式，如30s、60s），max_retries控制上游失败时的重试次数，input_filters/output_filters分别在转发前与返回前应用过滤器。

prompt 监听器：函数调用入口

- type: prompt name: prompt_function_listener address: 0.0.0.0 port: 10000

prompt 监听器为prompt_targets提供函数调用能力入口。

endpoints：可复用的服务端点

endpoints定义可被prompt_targets引用的后端服务地址，通过名称复用，避免重复书写连接参数：

endpoints: app_server: endpoint: 127.0.0.1:80 connect_timeout: 0.005s protocol: http # http or https mistral_local: endpoint: 127.0.0.1:8001 secure_service: endpoint: api.example.com:443 protocol: https http_host: api.example.com # Override the Host header sent upstream

字段说明：

endpoint（必填）：服务地址host:port
protocol：http或https，默认按端口推断
connect_timeout：连接超时（如0.005s）
http_host：显式覆盖发送给上游的Host头
prefix_affinity（Schema 中额外定义）：针对 vLLM 等多副本自托管后端，按x-plano-prefix-hash头做一致性哈希，使相同 prompt 前缀始终命中同一副本以复用其 KV cache，默认false

prompt_targets：函数调用与 API 编排的目标

prompt_targets定义可供 LLM 调用的函数（function calling）目标。每个目标声明参数 Schema、后端端点以及可选的目标级系统提示词：

prompt_targets: - name: get_current_weather description: Get current weather at a location. parameters: - name: location description: The location to get the weather for required: true type: string format: City, State - name: days description: the number of days for the request required: true type: int endpoint: name: app_server path: /weather http_method: POST system_prompt: You are a weather expert. Provide accurate and concise weather information. auto_llm_dispatch_on_response: true

关键字段：

parameters：每个参数包含name、description、type、required、可选的format、enum、default、in_path（Schema 中定义，控制参数是否放入路径）
endpoint：引用endpoints中定义的name，配合path与http_method（GET/POST），可选http_headers附加请求头
system_prompt：目标级系统提示词，覆盖顶层system_prompt
auto_llm_dispatch_on_response：为true时，LLM 会携带函数调用返回结果再次被调用，以生成面向用户的最终自然语言回答，形成完整的工具调用闭环

顶层的system_prompt作为默认系统提示词，对所有未单独配置的prompt_targets生效：

system_prompt: | You are a helpful assistant. Always respond concisely and accurately.

agents 与 filters：外部 Agent 与 MCP 过滤器

agents注册外部 HTTP Agent 服务，供 agent 监听器路由使用：

agents: - id: weather_agent # Example agent for weather url: http://localhost:10510 - id: flight_agent # Example agent for flights url: http://localhost:10520

filters注册应用于请求/响应的 MCP 过滤器（输入校验、查询重写等）：

filters: - id: input_guards # Example filter for input validation url: http://localhost:10500 # type: mcp (default) # transport: streamable-http (default) # tool: input_guards (default - same as filter id)

Schema 表明type可选mcp或http（默认mcp），transport当前支持streamable-http，tool默认与 filter 的id相同。过滤器通过在监听器或 agent 条目中引用id挂载到请求链路。

ratelimits：按模型与选择器的令牌限流

ratelimits按「模型 + 选择器」维度控制令牌用量。selector通过 HTTP 请求头识别限流主体，limit声明时间单位内的最大令牌数：

ratelimits: - model: openai/gpt-4o selector: key: x-user-id # HTTP header key used to identify the rate-limit subject value: "*" # Wildcard matches any value; use a specific string to target one limit: tokens: 100000 # Maximum tokens allowed in the given time unit unit: hour # Time unit: "minute", "hour", or "day" - model: openai/gpt-4o-mini selector: key: x-org-id value: acme-corp limit: tokens: 500000 unit: day

selector.value支持通配符*（匹配任意值）或精确字符串（仅限特定主体），unit的合法取值为minute、hour、day。

overrides：全局行为覆盖

overrides控制网关级全局行为，参考配置中列出的字段及含义如下：

overrides: prompt_target_intent_matching_threshold: 0.7 optimize_context_window: true use_agent_orchestrator: false upstream_connect_timeout: 10s upstream_tls_ca_path: /etc/ssl/certs/ca-certificates.crt llm_routing_model: Plano-Orchestrator agent_orchestration_model: Plano-Orchestrator disable_signals: false

字段	说明	默认值
`prompt_target_intent_matching_threshold`	将请求路由到 prompt_target 的意图匹配阈值（0.0–1.0），越低越宽松	—
`optimize_context_window`	修剪对话历史以适配模型上下文窗口	`false`
`use_agent_orchestrator`	启用多 Agent 请求编排	`false`
`upstream_connect_timeout`	上游提供商集群的连接超时（如`5s`、`10s`）	`5s`
`upstream_tls_ca_path`	上游 TLS 校验的受信 CA 包路径	`/etc/ssl/certs/ca-certificates.crt`
`llm_routing_model`	意图型 LLM 路由所用模型（必须已在 model_providers 中声明）	—
`agent_orchestration_model`	Agent 编排所用模型（必须已在 model_providers 中声明）	—
`disable_signals`	关闭 LLM 响应上的 agentic 信号分析（挫败感、重复、升级等）以节省 CPU	`false`
`orchestrator_model_context_length`	编排/路由模型的上下文窗口最大令牌数（Schema 定义）	`8192`

其中disable_signals对应 Plano 的 agentic signals 能力——位于 crates/brightstaff/src/signals 下的环境信号（exhaustion）、执行信号（failure、loops）、交互信号（disengagement、misalignment、satisfaction、stagnation）等分析模块，在不需要时可整体关闭以降低 CPU 开销。

routing：会话亲和与模型路由缓存

routing块为 agentic 循环中的路由决策提供会话级钉扎（pinning）能力：

routing: session_ttl_seconds: 600 # How long a pinned session lasts (default: 600s / 10 min) session_max_entries: 10000 # Max cached sessions before eviction (upper limit: 10000) # route_on_user_only: true session_cache: type: memory # "memory" (default) or "redis" # url: redis://localhost:6379 # tenant_header: x-org-id

session_ttl_seconds：会话钉扎的存活时长，默认 600 秒（10 分钟）
session_max_entries：缓存会话上限，默认 10000（Schema 上限 10000）
route_on_user_only：可选开关，为true时只在最后一条消息为用户消息时执行质量路由，工具结果/助手延续步骤则回放之前的决策，默认false
session_cache.type：memory（默认，进程内，适用于单实例）或redis（跨副本共享，多副本/Kubernetes 部署必需；type为redis时必须提供url，支持redis://与rediss://TLS 连接）
tenant_header：可选，设置后缓存键按plano:affinity:{tenant_id}:{session_id}隔离租户

Schema 中还定义了可选的routing_budget块（max_switch_spend_pct必填），作为会话级模型切换成本闸门：把「放弃仍可能温热的 provider 缓存」所带来的输入令牌成本计入会话累计切换开销，仅当该开销不超过从不切换基线成本的max_switch_spend_pct百分比时才允许付费切换；0表示绝不付费切换（仅允许绝对更便宜的切换）。该功能独立于 prompt_caching，且需要model_metrics_sources中存在 cost 数据源。客户端可通过x-plano-max-switch-spend-pct请求头按请求覆盖该百分比。

state_storage：多轮对话历史存储

state_storage决定多轮对话状态的保存后端：

state_storage: type: memory # "memory" (in-process) or "postgres" (persistent) # connection_string: postgresql://user:$DB_PASS@localhost:5432/plano

type：memory（进程内）或postgres（持久化）
connection_string：type为postgres时必填，支持$VAR或${VAR}环境变量替换（Schema 中通过allOf条件约束强制该依赖关系）

PostgreSQL 模式下需要预先初始化对话状态表，建表 SQL 可参考 docs/source/resources/db_setup/conversation_states.sql。

prompt_guards：全局输入护栏

prompt_guards配置全局应用的输入护栏，参考配置中的jailbreak检测在命中异常时的兜底回复：

prompt_guards: input_guards: jailbreak: on_exception: message: "I'm sorry, I can't help with that request."

Schema 要求input_guards下必须包含jailbreak块，且on_exception.message必填。护栏可以与监听器上的input_filters/output_filters组合使用，形成多层防御。

tracing：OpenTelemetry 追踪与 AI 可观测性导出

tracing块控制链路追踪的采样、内部 span 开关、OTLP 导出目标与 span 属性：

tracing: random_sampling: 100 trace_arch_internal: false opentracing_grpc_endpoint: http://localhost:4317 span_attributes: header_prefixes: - x-user- - x-org- static: environment: production service.team: platform exporters: - type: posthog url: https://us.i.posthog.com api_key: $POSTHOG_API_KEY distinct_id_header: x-user-id capture_messages: false

random_sampling：随机采样百分比（1–100）
trace_arch_internal：是否在 trace 中包含 Plano 内部 span
opentracing_grpc_endpoint：OpenTelemetry Collector（如 Jaeger、Tempo）的 gRPC 端点
span_attributes.header_prefixes：将名称以这些前缀开头的请求头作为 span 属性传播
span_attributes.static：附加到每个 span 的静态键值对
exporters：提供商无关的导出目标，LLM span 除发送到上述 gRPC 端点外还会流式发送到每个 exporter。posthog类型将每次 LLM 调用捕获为$ai_generation事件；url后会自动追加/batch/采集路径；api_key支持$ENV_VAR展开；distinct_id_header指定用作 PostHogdistinct_id的请求头（省略则匿名采集）；capture_messages为true时在$ai_input中包含（截断后的）用户消息

组合示例与验证方式

将上述所有块整合到一份配置中，即可得到一个覆盖路由、护栏、限流、状态与追踪的完整示例，即原文档引用的 docs/source/resources/includes/plano_config_full_reference.yaml，本文所有示例均取自该文件，建议作为编写新配置的蓝本直接对照使用。

配置的合法性以 config/plano_config_schema.yaml 为权威校验标准（顶级additionalProperties: false意味着未知字段会直接报错）。Schema 定义与源码结构体（crates/common/src/configuration.rs）保持同步，例如headers字段对应LlmProvider.headers: Option<HashMap<String, String>>，passthrough_auth对应同名布尔字段。仓库中的config/目录还提供了 envoy.template.yaml、docker-compose.dev.yaml 与 plano_config_schema.yaml，可结合本地开发环境（config/docker-compose.dev.yaml）进行编排启动；另有 config/validate_plano_config.sh 可用于对配置文件做前置校验。在动手部署前，建议先通读 docs/source/resources/deployment.rst 了解网关的部署形态，再结合本文逐块编写配置，最后用校验脚本与真实请求验证各监听器、路由偏好与追踪导出是否符合预期。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考