配置说明

运行时配置以 config.toml 为中心。常见配置任务看本页；完整生成版 config.example.toml 看配置参考，精确默认值看默认值与限制。

配置地图

本地监听

Proxy 和 MCP 控制面的 HTTP 地址。

[server][mcp]

路由

默认 providers 和显式 model/protocol routes。

[routing.default_provider_names][[routing.routes]]

Providers

上游 endpoint、provider protocol、API key 和兼容模式。

[providers.<name>]

流式安全

未完成 streamed tool-call arguments 和上游 idle read 的超时。

[tool_calls]read_idle_timeout_secs

诊断

Capture 开关、日志格式和耗时颜色阈值。

[capture][logging][logging.duration_thresholds]

客户端错误

适合 Zed 阅读的 text errors，或给 OpenAI 兼容客户端的 JSON errors。

[error_responses]

找到 app 目录

运行时文件会生成在用户 app 目录：

平台	路径
Windows	%USERPROFILE%.proxai\
Linux/macOS	~/.proxai/

重要条目：

路径	用途
`config.toml`	运行时配置，刻意不进入 git
`config.example.toml`	生成的本地示例/参考
`logs/`	运行日志输出
`captures/`	可选的 per-phase capture artifacts

仓库和 app 目录边界见环境与文件。

最小本地配置

一个最小可用配置需要本地 listener、默认 provider 映射，以及至少一个 provider。

[server]
host = "127.0.0.1"
port = 18080

[routing.default_provider_names]
openai_responses = "openai"
openai_chat_completions = "openai"
anthropic_messages = "anthropic"

[providers.openai]
protocol = "openai_responses"
base_url = "https://api.openai.com"
api_key = "..."

[providers.anthropic]
protocol = "anthropic_messages"
base_url = "https://api.anthropic.com"
api_key = "..."

添加 provider

每个 provider 描述一个具体上游。本页只保留快速形态；provider 命名、认证头、defaults 和 route 示例见 Provider 设置。

[providers.openai]
protocol = "openai_responses"
base_url = "https://api.openai.com"
api_key = "..."

Provider 名称只是标签。Provider protocol 控制出站 wire 行为。Provider name 和 provider protocol 的区别见术语表。

设置默认 providers

[routing.default_provider_names] 为每个入站 request protocol 声明 fallback provider。只有没有显式 route 命中时才使用 defaults。

[routing.default_provider_names]
openai_responses = "openai"
openai_chat_completions = "openai_chat"
anthropic_messages = "anthropic"

支持的 key 是协议中的 protocol values：

openai_responses
openai_chat_completions
anthropic_messages

添加显式 route

当某个模型 pattern 需要指定 provider、可选入站协议 guard 或上游模型改写时，使用显式 route。

[[routing.routes]]
name = "m3_chat"
request_protocol = "openai_chat_completions"
match_kind = "exact"
model_pattern = "MiniMax-M3-preview"
provider = "minimax"
upstream_model = "MiniMax-M3"

字段	作用
`name`	CLI override 使用的可选稳定标识
`request_protocol`	可选入站协议 guard
`match_kind`	可选 `exact`、`glob`、`regex` 或 `auto`
`model_pattern`	逻辑模型选择器
`provider`	route 命中时选择的 provider 名称
`upstream_model`	可选上游模型映射

精确匹配结果见路由匹配。

调整流式超时

这里有两个不同的超时概念：

配置	层级	用途
`[tool_calls].timeout_secs`	协议语义	未完成 streamed tool-call arguments 的语义超时
`[providers.<name>].read_idle_timeout_secs`	传输 carrier	等待上游 response bytes 时的 idle-read timeout

不要混淆它们：read_idle_timeout_secs 看原始上游 bytes，tool_calls.timeout_secs 看语义 tool-call completion。

启用 captures

Capture phase 开关在 [capture] 下：

[capture]
inbound_request_enabled = false
provider_request_enabled = false
upstream_response_enabled = false
outbound_response_enabled = false

1选择最窄 phase用能回答问题的 phase。
2短时间启用通过配置或 `proxai capture enable ...` 打开一个调试窗口。
3复现一次发送一个脱敏请求。
4关闭 captureCaptures 可能包含 prompt、tool arguments、模型输出和上游 payload。

Capture 路径固定在 app 目录下。Phase 含义和隐私风险见 Capture Phases。

配置日志

[logging] 控制输出格式和颜色行为。[logging.duration_thresholds] 控制 human logs 的耗时颜色。

字段	含义
`output_format`	`human` 适合交互调试，`json` 适合机器消费
`use_color`	启用或禁用 colored human logs
`warn_ms / error_ms`	Human log duration coloring thresholds

日志应保持紧凑，不应包含 request bodies、API keys、Authorization headers 或 private prompts。

选择错误响应格式

[error_responses] 决定客户端错误如何渲染。

取值	含义
`text`	紧凑、适合 Zed 阅读的错误 body；默认值
`json`	给非 Zed 客户端使用的 OpenAI 风格 JSON error body

[error_responses]
format = "text" # 或 "json"

上游 status 处理和保留 headers 见错误响应。