AIstudioProxyAPI 配置参数详解
AIstudioProxyAPI v4.1.2_py 全量配置参数详解：.env 十二分区参数表与逐项说明、命令行覆盖关系实测、生产配置模板与参数排障 FAQ。
AIstudioProxyAPI 配置参数详解
目标：完整梳理 AIstudioProxyAPI v4.1.2_py 的全部配置项——参数载体（.env）、查看与修改方式、按域分类的参数表与逐项说明、可直接落地的生产配置模板，以及参数相关的常见故障处置。参数默认值均取证自项目
.env.example与官方docs/configuration-reference.md（v4.1.2_py，查询日期 2026-10-23）。
一、环境信息
- AIstudioProxyAPI：v4.1.2_py（2026-04-18 发布，官方最新稳定版）
- 配置载体：项目根目录
.env（从.env.example复制），共 12 个分区、约 120 个配置项 - 参数取证来源：仓库内
.env.example与docs/configuration-reference.md - 关联路径：
/opt/AIstudioProxyAPI/.env（本指南写作时的安装路径，安装过程见《AIstudioProxyAPI 安装指南》） - 命令行参数（
launch_camoufox.py --xxx）与本篇环境变量参数存在覆盖关系，见 3.1
二、前置条件
- 已按《AIstudioProxyAPI 安装指南》完成安装，项目目录存在
.env.example模板； - 理解本项目参数的三层来源与优先级：命令行参数 > .env 环境变量 > 代码内置兜底值（官方 configuration-reference 明示：
.env.example为主，代码兜底值少数项可能不同，如FUNCTION_CALLING_MODE代码兜底为emulated而 .env 模板为auto）。
三、参数查看与修改方式
3.1 修改方式
参数统一在项目根目录 .env 中修改。首次使用先复制模板：
cd /opt/AIstudioProxyAPI
cp .env.example .env
编辑后重启服务生效（systemd 形态 systemctl restart aistudio-proxy；直跑形态 Ctrl+C 后重新执行 launch_camoufox.py）。
优先级规则与实测验证：.env 设 LAUNCH_MODE=headless 后，再用命令行 --debug 启动，实际生效为 debug 模式（启动日志打印 Final selected launch mode: debug mode）——命令行覆盖 .env。Docker Compose 形态下 docker-compose.yml 的 environment: 段可覆盖 .env（官方注释原文：这些环境变量会覆盖 .env 文件中的设置）。
3.2 查看当前参数
grep -vE '^#|^$' /opt/AIstudioProxyAPI/.env
输出节选（模板复制后未修改时的实测首部）：
PORT=2048
STREAM_PORT=3120
DEFAULT_FASTAPI_PORT=2048
DEFAULT_CAMOUFOX_PORT=9222
UNIFIED_PROXY_CONFIG=http://127.0.0.1:7890
SERVER_LOG_LEVEL=INFO
SERVER_REDIRECT_PRINT=false
...
运行时还可经内置 Web UI（http://127.0.0.1:2048/）的设置页查看/修改代理、端口、密钥等在线参数，或调用管理接口 GET /api/info、GET/POST /api/proxy/config、GET/POST /api/ports/config（接口清单见《AIstudioProxyAPI 常用 CLI 命令与工具详解》）。
四、参数总览
.env.example 的 12 个分区（官方注释原文归纳）：
| 分区 | 代表参数 | 条目数（约） |
|---|---|---|
| 1. 服务器端口 | PORT、STREAM_PORT | 4 |
| 2. 代理配置 | UNIFIED_PROXY_CONFIG、NO_PROXY | 5 |
| 3. 日志与调试 | SERVER_LOG_LEVEL、JSON_LOGS | 7 |
| 4. 认证配置 | AUTO_ROTATE_AUTH_PROFILE、QUOTA_HARD_LIMIT、COOKIE_REFRESH_* | 13 |
| 5. 浏览器与模型 | LAUNCH_MODE、CAMOUFOX_WS_ENDPOINT、DIRECT_LAUNCH | 6 |
| 6. API 默认参数 | DEFAULT_TEMPERATURE、THINKING_BUDGET_* | 12 |
| （6 续）函数调用 | FUNCTION_CALLING_MODE、FC_DEBUG_* | 30+ |
| 7. 高级超时 | RESPONSE_COMPLETION_TIMEOUT、SILENCE_TIMEOUT_MS | 15 |
| 8. GUI 启动器 | GUI_DEFAULT_PROXY_ADDRESS | 3 |
| 9. 脚本注入 | ENABLE_SCRIPT_INJECTION、USERSCRIPT_PATH | 2 |
| 10. 系统杂项 | MODEL_NAME、AI_STUDIO_URL_PATTERN | 7 |
| 11. 流状态与错误抑制 | STREAM_MAX_INITIAL_ERRORS | 3 |
| 12. 前端构建 | SKIP_FRONTEND_BUILD | 1 |
关键差异/如何读表：日常必调项集中在分区 1（端口）、2（代理）、4（认证）与 5（启动模式）；函数调用与超时区参数保持默认即可满足大多数场景，出问题时才需要按第六章排障口径调整。
五、核心参数分类详解
5.1 网络与端口
| 参数 | 默认值 | 说明 |
|---|---|---|
PORT | 2048 | FastAPI 主服务端口（OpenAI 兼容 API 与 Web UI 都在此端口） |
STREAM_PORT | 3120 | 流式代理端口；设 0 关闭流代理 |
DEFAULT_FASTAPI_PORT | 2048 | 启动器提示用默认端口 |
DEFAULT_CAMOUFOX_PORT | 9222 | Camoufox 浏览器调试端口默认值 |
UNIFIED_PROXY_CONFIG | http://127.0.0.1:7890（模板预填） | 统一代理入口，同时配置 HTTP_PROXY、HTTPS_PROXY 与浏览器内部代理；优先级最高 |
HTTP_PROXY / HTTPS_PROXY | 空（注释态） | 兼容代理配置，仅在 UNIFIED_PROXY_CONFIG 未设置时生效 |
NO_PROXY | 空（注释态） | 代理绕过列表，分号分隔，如 localhost;127.0.0.1;*.local |
说明：UNIFIED_PROXY_CONFIG 是代理配置的首选——一条配置同时作用于 Python 出站请求与 Camoufox 浏览器流量；实测中该值留空表示全部直连。改端口示例（宿主 2048 被 Web 应用占用时改 8150）：
sed -i 's/^PORT=2048/PORT=8150/' /opt/AIstudioProxyAPI/.env
grep '^PORT=' /opt/AIstudioProxyAPI/.env
PORT=8150
5.2 启动与浏览器
| 参数 | 默认值 | 说明 |
|---|---|---|
LAUNCH_MODE | normal | 启动模式：normal/debug/headless/virtual_display/direct_debug_no_browser；命令行 --debug/--headless/--virtual-display 会覆盖此值 |
CAMOUFOX_WS_ENDPOINT | 空 | 外部浏览器 WebSocket 地址（如 ws://127.0.0.1:9222）；常规启动由 launcher 自动注入，直接跑 server.py 时必须手工提供（缺它启动即失败，实测见安装指南 FAQ Q5） |
DIRECT_LAUNCH | false | 跳过启动器菜单/交互，直接按 .env 配置启动 |
ENDPOINT_CAPTURE_TIMEOUT | 45 | 捕获浏览器 WebSocket 端点的超时秒数 |
ONLY_COLLECT_CURRENT_USER_ATTACHMENTS | false | 是否只收集当前用户消息中的附件 |
ENABLE_SCRIPT_INJECTION | false | 油猴脚本注入（官方标注 Deprecated） |
USERSCRIPT_PATH | browser_utils/more_models.js | 注入脚本路径（相对项目根） |
5.3 认证、轮转与 Cookie 刷新
认证体系是本项目运维核心：登录态保存在 auth_profiles/（active/saved/emergency 三级目录）的 JSON 文件中，以下参数控制保存、轮转与刷新行为。
| 参数 | 默认值 | 说明 |
|---|---|---|
AUTO_SAVE_AUTH | false | debug 模式登录成功后自动提示保存认证 |
AUTH_SAVE_TIMEOUT | 30 | 等待用户输入保存文件名的超时秒数 |
AUTO_ROTATE_AUTH_PROFILE | true | 配额超限/异常时自动切换到其他认证配置 |
AUTO_AUTH_ROTATION_ON_STARTUP | false | 启动时 active 无可用配置则自动从 saved/emergency 池选取 |
AUTO_CONFIRM_LOGIN | true | 自动确认登录流程 |
QUOTA_SOFT_LIMIT | 850000 | 配额软阈值：触发「轮转待命」，当前流式响应完成后轮转 |
QUOTA_HARD_LIMIT | 950000 | 配额硬阈值：立即发 Kill Signal，防止硬封号 |
QUOTA_LIMIT_<MODEL_ID> | 空 | 单模型专属阈值（高级用法，如 QUOTA_LIMIT_GEMINI_2_5_PRO） |
COOKIE_REFRESH_ENABLED | true | 自动刷新并持久化浏览器 Cookie |
COOKIE_REFRESH_INTERVAL_SECONDS | 1800 | 周期刷新间隔（秒），默认 30 分钟 |
COOKIE_REFRESH_ON_REQUEST_ENABLED | true | 成功请求后按次数保存 Cookie |
COOKIE_REFRESH_REQUEST_INTERVAL | 10 | 每多少次成功请求保存一次 |
COOKIE_REFRESH_ON_SHUTDOWN | true | 优雅关停时保存 Cookie |
💡 技术拓展：认证轮转的阈值设计是「软硬双闸」——软阈值（默认 85 万 tokens）先安排优雅交接，硬阈值（默认 95 万）直接熔断保护账号。同类实现（如 iBUHub/AIStudioToAPI）多为单账号单文件，无内置轮转池；多账号轮转正是 AIstudioProxyAPI 的差异化能力。本方案实际采用默认双闸值，仅当账号配额明显不同时按模型单独设
QUOTA_LIMIT_<MODEL_ID>。
5.4 API 默认采样与思考预算
| 参数 | 默认值 | 说明 |
|---|---|---|
DEFAULT_TEMPERATURE | 1.0 | 请求未带 temperature 时的默认采样温度 |
DEFAULT_MAX_OUTPUT_TOKENS | 65536 | 默认输出 token 上限 |
DEFAULT_TOP_P | 0.95 | 默认 top_p |
DEFAULT_STOP_SEQUENCES | ["User:"] | 默认停用序列（JSON 字符串格式） |
ENABLE_THINKING_BUDGET | true | 启用思考模型预算（如 gemini-2.0-flash-thinking） |
DEFAULT_THINKING_BUDGET | 8192 | 默认思考预算 tokens |
THINKING_BUDGET_LOW | 10923 | low 档预算值 |
THINKING_BUDGET_MEDIUM | 21845 | medium 档预算值 |
THINKING_BUDGET_HIGH | 32768 | high 档预算值 |
DEFAULT_THINKING_LEVEL_PRO | high | Gemini 3 Pro 系列默认思考等级 |
DEFAULT_THINKING_LEVEL_FLASH | high | Gemini 3 Flash 系列默认思考等级 |
DISABLE_THINKING_BUDGET_ON_STREAMING_DISABLE | false | 请求关闭流式时是否同时关闭思考预算 |
ENABLE_GOOGLE_SEARCH | false | 开启 Google Search 能力映射 |
ENABLE_URL_CONTEXT | false | 开启 URL Context 能力映射 |
说明：这些默认值仅当客户端请求未携带对应参数时生效；客户端显式传参（如 "temperature":0.8）优先。停用序列默认 ["User:"] 是为了防止网页对话被历史消息中的 User: 字样截断。
5.5 函数调用（Function Calling）
OpenAI tools 参数到 AI Studio 网页的桥接策略，是本项目最复杂的参数域：
| 参数 | 默认值 | 说明 |
|---|---|---|
FUNCTION_CALLING_MODE | auto（代码兜底 emulated） | 模式：auto/native/emulated |
FUNCTION_CALLING_NATIVE_FALLBACK | true | 仅 native 模式生效：失败后自动回退 emulated |
FUNCTION_CALLING_UI_TIMEOUT | 10000 | 函数调用 UI 操作超时（毫秒） |
FUNCTION_CALLING_NATIVE_RETRY_COUNT | 3 | native 模式回退前的重试次数 |
FUNCTION_CALLING_CLEAR_BETWEEN_REQUESTS | true | 请求间清理函数定义（无状态行为） |
FUNCTION_CALLING_DEBUG | false | 函数调用调试日志总开关 |
FUNCTION_CALLING_CACHE_ENABLED | true | 函数调用状态缓存（减少重复 UI 操作） |
FUNCTION_CALLING_CACHE_TTL | 0 | 缓存 TTL 秒数（0=会话内不过期） |
FUNCTION_CALLING_THOUGHT_SIGNATURE | true | Gemini 3 thoughtSignature 兼容字段（FC-001） |
FUNCTION_CALLING_UPPERCASE_TYPES | false | JSON Schema 类型转大写兼容模式（FC-004，官方警示需先验证 UI 接受度） |
三种模式的官方注释语义：
auto：推荐。先尝试 native，失败自动回退 emulated，适合绝大多数用户；native：走 AI Studio UI 原生操作驱动函数调用，可靠性最好，要求模型支持；emulated：基于文本提示注入的传统实现，兼容旧环境或 native 异常时使用。
💡 技术拓展：
native与emulated的本质差异在于「tool call 由谁产生」——native 让网页 UI 的工具对话框真实点击产生结构化调用；emulated 把工具 schema 注入提示词、靠模型输出文本再解析。前者可靠但依赖 UI 选择器（网页改版需跟进），后者对 UI 改版免疫但解析易错。auto 模式两者兼用，本项目默认采用。
FC 调试子开关（FC_DEBUG_*，仅在 FUNCTION_CALLING_DEBUG=true 时生效）：FC_DEBUG_ORCHESTRATOR/UI/CACHE/WIRE/DOM/SCHEMA/RESPONSE 七个模块独立开关（默认 false）、FC_DEBUG_LEVEL_* 逐模块日志级别、FC_DEBUG_LOG_MAX_BYTES（5242880）与 FC_DEBUG_LOG_BACKUP_COUNT（3）控制 logs/fc_debug/ 日志切割、FC_DEBUG_TRUNCATE_* 控制载荷截断（TOOL_DEF 500 / ARGS 1000 / RESPONSE 2000 字符）、FC_DEBUG_COMBINED_LOG（false）额外输出合并日志。
5.6 日志与诊断
| 参数 | 默认值 | 说明 |
|---|---|---|
SERVER_LOG_LEVEL | INFO | 主日志级别（DEBUG/INFO/WARNING/ERROR/CRITICAL） |
SERVER_REDIRECT_PRINT | false | 是否把 print 输出重定向到日志系统（debug 模式的 input() 提示需要保持 false 才可见） |
DEBUG_LOGS_ENABLED | false | DEBUG 级日志总开关 |
TRACE_LOGS_ENABLED | false | TRACE 级日志总开关 |
JSON_LOGS | false | JSON 结构化日志（对接日志采集器时开启） |
LOG_FILE_MAX_BYTES | 10485760 | 单日志文件切割阈值（10MB） |
LOG_FILE_BACKUP_COUNT | 5 | 滚动保留份数 |
5.7 超时与稳态参数
全部为毫秒/秒级精细控制，默认值取自 .env.example：
| 参数 | 默认值 | 说明 |
|---|---|---|
RESPONSE_COMPLETION_TIMEOUT | 600000（10 分钟） | 响应完成总超时 |
INITIAL_WAIT_MS_BEFORE_POLLING | 500 | 开始轮询前的初始等待 |
POLLING_INTERVAL / POLLING_INTERVAL_STREAM | 300 / 180 | 轮询间隔（非流式/流式） |
SILENCE_TIMEOUT_MS | 60000 | 无活动静默判定阈值 |
POST_SPINNER_CHECK_DELAY_MS | 500 | 加载动画消失后的复查延迟 |
FINAL_STATE_CHECK_TIMEOUT_MS | 1500 | 最终状态检查超时 |
POST_COMPLETION_BUFFER | 700 | 完成后缓冲 |
UI_GENERATION_WAIT_TIMEOUT_MS | 5000 | UI 生成等待超时 |
UI_GENERATION_CHECK_INTERVAL_MS | 500 | UI 生成检查间隔 |
UI_STABILIZATION_BUFFER_MS | 500 | UI 稳定缓冲 |
CLEAR_CHAT_VERIFY_TIMEOUT_MS / _INTERVAL_MS | 4000 / 4000 | 清空对话的验证超时/间隔 |
CLICK_TIMEOUT_MS | 3000 | 页面元素点击超时 |
CLIPBOARD_READ_TIMEOUT_MS | 3000 | 剪贴板读取超时 |
WAIT_FOR_ELEMENT_TIMEOUT_MS | 10000 | 等待元素出现超时 |
PSEUDO_STREAM_DELAY | 0.01 | 伪流式输出延迟（秒） |
STREAM_MAX_INITIAL_ERRORS | 3 | 流初始错误抑制阈值 |
STREAM_WARNING_INTERVAL_AFTER_SUPPRESS | 60.0 | 抑制期后告警间隔（秒） |
STREAM_SUPPRESS_DURATION_AFTER_INITIAL_BURST | 400.0 | 初始错误爆发后的抑制时长（秒） |
说明：日常不需要动这批参数；长回复被误判超时可上调 RESPONSE_COMPLETION_TIMEOUT，网页响应慢导致超时报错时同步上调 SILENCE_TIMEOUT_MS。
5.8 杂项与 GUI
| 参数 | 默认值 | 说明 |
|---|---|---|
MODEL_NAME | AI-Studio_Proxy_API | /v1/models 返回的模型服务名 |
CHAT_COMPLETION_ID_PREFIX | chatcmpl- | 响应 id 前缀 |
AI_STUDIO_URL_PATTERN | aistudio.google.com/ | 目标网页识别模式 |
EXCLUDED_MODELS_FILENAME | excluded_models.txt | 排除模型清单文件名 |
GUI_DEFAULT_PROXY_ADDRESS | http://127.0.0.1:7890 | GUI 启动器默认代理 |
GUI_DEFAULT_STREAM_PORT | 3120 | GUI 启动器默认流端口 |
GUI_DEFAULT_HELPER_ENDPOINT | 空 | GUI 启动器默认 helper 端点 |
SKIP_FRONTEND_BUILD | false | 跳过前端构建检查（无 Node.js 环境设 true） |
六、生产配置模板
以下为可直接落地的生产模板（适用场景：4GB 内存 Linux 服务器、单账号起步、需代理访问 Google、headless 常驻、开启 API Key 鉴权）：
# ===== 网络 =====
PORT=2048
STREAM_PORT=3120
UNIFIED_PROXY_CONFIG=http://192.168.1.62:7897
# ===== 启动 =====
LAUNCH_MODE=headless
DIRECT_LAUNCH=true
FUNCTION_CALLING_MODE=auto
# ===== 认证 =====
AUTO_ROTATE_AUTH_PROFILE=true
AUTO_AUTH_ROTATION_ON_STARTUP=true
QUOTA_SOFT_LIMIT=850000
QUOTA_HARD_LIMIT=950000
COOKIE_REFRESH_ENABLED=true
COOKIE_REFRESH_INTERVAL_SECONDS=1800
# ===== 日志 =====
SERVER_LOG_LEVEL=INFO
JSON_LOGS=false
LOG_FILE_MAX_BYTES=10485760
LOG_FILE_BACKUP_COUNT=5
逐项说明：UNIFIED_PROXY_CONFIG 指向实际可达代理（本模板以 192.168.1.62:7897 为例，无代理需求的部署删除此行即可直连）；LAUNCH_MODE=headless + DIRECT_LAUNCH=true 实现「开机/重启后无交互直接进入服务状态」；AUTO_AUTH_ROTATION_ON_STARTUP=true 保证 active 配置偶发失效时能从 saved 池自动接管；其余认证与日志项维持官方默认。资源占用参考：单实例含 Camoufox 浏览器进程，实测空载常驻内存约 1GB 量级，4GB 内存单实例稳妥、8GB 可支撑流式高负载；磁盘开销主要为 Camoufox 本体约 2.4GB。
⚠️ 注意：API Key 鉴权由密钥文件驱动（存在有效 key 时
/v1/*自动开启鉴权），经 Web UI 或POST /api/keys管理接口增删，不在 .env 参数域内；生产环境务必配置，并把 2048 端口置于内网或网关鉴权之后。
七、常见问题（FAQ）
Q1：改了 .env 不生效？
确认三点：文件确为项目根目录 .env（不是 .env.example）；修改后已重启服务；没有同名命令行参数覆盖（优先级：命令行 > .env > 代码兜底）。
Q2：FUNCTION_CALLING_MODE 明明没设，行为却像 emulated？
代码兜底值与 .env 模板不同：模板 auto，代码兜底 emulated（官方 configuration-reference 明示）。始终在 .env 显式设置 FUNCTION_CALLING_MODE=auto。
Q3：设置了代理后 API 可用但浏览器打不开 Google？
UNIFIED_PROXY_CONFIG 会同时下发给浏览器；确认代理地址从服务器可达、协议为 http:// 前缀（不是 socks5://，浏览器代理经 Playwright server 转发）。Docker 部署时代理地址不能用 127.0.0.1（容器内指向自身），要写宿主机实际内网 IP。
Q4：QUOTA_SOFT_LIMIT/QUOTA_HARD_LIMIT 数值单位是什么？
tokens 计数。软阈值触发优雅轮转、硬阈值立即熔断，两值需保持「软 < 硬」；单模型差异化阈值用 QUOTA_LIMIT_<MODEL_ID>（模型 ID 中特殊字符以下划线代替）。
Q5：流式响应经常中途中断报流错误？
先开 DEBUG_LOGS_ENABLED=true 复现定位；稳定复现时尝试上调 SILENCE_TIMEOUT_MS（默认 60000）与 RESPONSE_COMPLETION_TIMEOUT（默认 600000）；仍异常时按官方排障文档检查代理稳定性。
Q6：无 Node.js 环境启动报前端构建检查失败？
设 SKIP_FRONTEND_BUILD=true 跳过检查，直接使用仓库预置的静态资源。
八、参考链接
- 官方配置参考：https://github.com/CJackHwang/AIstudioProxyAPI/blob/main/docs/configuration-reference.md （查询日期 2026-10-23）
- 官方环境变量配置文档：https://github.com/CJackHwang/AIstudioProxyAPI/blob/main/docs/environment-configuration.md
.env.example模板（v4.1.2_py）：https://github.com/CJackHwang/AIstudioProxyAPI/blob/v4.1.2_py/.env.example- 函数调用文档：https://github.com/CJackHwang/AIstudioProxyAPI/blob/main/docs/function-calling.md
- 官方排障指南：https://github.com/CJackHwang/AIstudioProxyAPI/blob/main/docs/troubleshooting.md
- 本专栏相关篇目：《AIstudioProxyAPI 安装指南》《AIstudioProxyAPI 常用 CLI 命令与工具详解》