工具调用与图片输入默认开启。可通过命令行修改插件配置：

# 仅关闭 Gemini Web 的图片输入，保留 AI Studio 的图片输入
magpie plugin options magpie-gemini-web '{"allowImages":false,"studio":{"allowImages":true}}'
关闭 AI Studio 的图片输入
magpie plugin options magpie-gemini-web '{"studio":{"allowImages":false}}'
为 AI Studio 配置代理
magpie plugin options magpie-gemini-web '{"studio":{"proxy":"http://127.0.0.1:7890"}}'

Windows PowerShell：magpie 实际运行的是 magpie.cmd 包装器，它转发参数时会弄丢 JSON 里的双引号。请直接调用它背后的可执行文件：这个文件和 magpie.cmd 在同一个文件夹（where.exe magpie 可以找到），文件名可能是 magpie-windows-amd64.exe 之类，Magpie 的「设置 → 命令行」里也会显示。写法取决于 PowerShell 版本（用 $PSVersionTable.PSVersion 查看）：

- PowerShell 7.3 及以上，默认设置：& "<可执行文件的完整路径>" plugin options magpie-gemini-web '{"allowImages":true}'

- Windows PowerShell 5.1（系统自带）：它不会替你转义参数里的双引号，要写成 \"：& "<可执行文件的完整路径>" plugin options magpie-gemini-web '{\"allowImages\":true}'

| 选项 | 默认值 | 适用范围 | 说明 | | :--- | :--- | :--- | :--- | | allowTools | true | 共用（可用 studio.allowTools 单独覆盖） | 允许工具调用。设为 false 时带工具的请求返回 400 | | allowImages | true | 共用（可用 studio.allowImages 单独覆盖） | 允许对话中的图片输入（图像模型的参考图不受它限制）。Gemini Web 读图需要登录，未登录时返回 400 | | requestTimeoutMs / modelTimeoutMs | Web：570000 / 10000；Studio：1800000 / 10000 | 共用（studio.* 可覆盖） | 单次等待后端 / 拉取模型列表的超时（毫秒）；收到流数据后重新计时，显式配置优先 | | stripCitations | true | 仅 gemini-web | 剥离回复与工具参数中的 [cite: 1]、[cite_start] 标记（AI Studio 不支持剥离） | | proxy | 无 | 仅 gemini-web | 一键配置后端访问 Google 的代理（http / https / socks5 / socks5h），也可用环境变量 GEMINI_WEB_PROXY 或在登录第一步填写 | | baseURL | http://127.0.0.1:8083/v1 | 仅 gemini-web | Gemini Web 默认后端地址 | | contextLimit / outputLimit | 1000000 / 8192 | 仅 gemini-web | 向客户端声明的上下文 / 输出上限 | | studio.proxy | 无 | 仅 ai-studio | 访问 Google 的代理（http / https / socks5），也可用环境变量 AI_STUDIO_PROXY；设置后优先于管理页里保存的代理，留空等于不设置 | | studio.baseURL | http://127.0.0.1:2048/v1 | 仅 ai-studio | 连接已有 AIStudio2API 时的默认地址 | | studio.contextLimit / studio.outputLimit | 模型目录默认值 | 仅 ai-studio | 向客户端声明的上限（仅支持在目录值基础上调低） | | studio.imageModels | true | 仅 ai-studio | 列出 Nano Banana 等图像模型，供 Magpie 的图片生成使用；设为 false 时只列文本模型 |

配置代理访问 Google：

• AI Studio：推荐在本地管理页设置。打开额度卡片「管理页」一行里的地址（默认 http://127.0.0.1:2048），用户名 magpie，密码是数据目录 config.json 里的 adminPassword；保存代理后在管理页重启服务即可生效，之后插件重启后端也不会覆盖它。

• Gemini Web：后端不读取系统代理或 HTTP_PROXY。可在「一键配置本地 Gemini Web」登录第一步直接填写代理地址，或设置插件选项 proxy / 环境变量 GEMINI_WEB_PROXY，也可以打开本地管理面板 http://127.0.0.1:8083/admin 在代理池中添加（登录口令为数据目录 secrets.json 中的 adminToken）。

连接自建后端： 如果你自己运行了 gemini-web2api-go 或 AIStudio2API，登录时选择 「连接已有后端 / 连接已有 AIStudio2API」，填入以 /v1 结尾的地址和对应的 API Key 即可。

刷新模型列表： 升级插件后，可执行 magpie provider models gemini-web 刷新模型列表。

本地服务什么时候启动、停止：

• 插件加载时（例如打开 Magpie）会在后台启动本地服务；之后发请求、刷新额度卡片时，服务没在运行也会自动启动。
• 本地服务是独立进程，退出 Magpie 不会停止它，下次打开 Magpie 直接接着用。
• 停止服务用下表的 studio:stop（或卡片、报错里给出的完整命令）。停止只是一次性的：下一次请求会再次启动它。

| 命令 | 作用 | | :--- | :--- | | npm run studio:status | 查看本地服务与账号状态 | | npm run studio:start / studio:stop | 启动 / 停止本地服务 | | npm run studio:login | 添加 Google 账号 | | npm run studio:relogin -- [<账号>] | 重新登录过期账号（仅一个账号时可省略参数） | | npm run studio:install -- --archive <文件> | 使用已下载的安装包离线安装 | | node scripts/studio.mjs import <目录> | 在服务停止状态下导入已有账号 | | npm run studio:smoke | 发起真实请求验收（会消耗账号额度） |

安全与数据目录：

• 两个后端均只监听 127.0.0.1，Cookie 与登录态仅保存在本机，Magpie 仅保存本地生成的随机 API Key。
• Gemini Web 数据目录：~/.local/share/magpie-gemini-web（可通过 GEMINI_WEB_DATA_DIR 修改），日志位于 backend.log。支持 macOS、Linux、Windows（x64 / arm64）。
• AI Studio 数据目录：~/.local/share/magpie-ai-studio（可通过 AI_STUDIO_DATA_DIR 修改），日志位于 backend.log（超 10 MB 下次启动自动轮转）。默认使用 2048 端口，被占用时自动顺延并记录在 config.json。支持 macOS、Linux（x64 / arm64）与 Windows x64。
• Gemini Web 每个登录同时最多 2 个请求（AI Studio 为 1），可在 Magpie 的 provider 设置里调整；仍无法完全排除 Google 账号风控风险，请自行评估使用。

• 插件固定使用经过 SHA-256 校验的 v0.2.19-magpie.1（基于上游 v0.2.19），通过升级插件更新后端。同基线或更旧的官方版、以及旧版插件装的托管后端，在下次管理启动时自动升级，保留账号、端口与登录凭据。
• 0.2.19 的账号绑定与备用请求模型设置会保留；管理页保存的默认值不会在重启后被改回插件默认值。备用请求默认关闭，需要时可在管理页开启并选择模型。
• 从 0.2.18 升级且已开启 auto 时，备用请求从所有模型缩为 FIRST_EVENT_HEDGE_MODELS 中的模型，未配置该列表时仅有 Argon。管理页完整保存会固定当时的默认值，后续上游默认值变化需要手动调整。接管官方 0.2.19 的稀疏配置时，缺失项会按插件规则补齐（例如备用请求变为 off）；详见升级兼容说明。
• 托管后端已在 macOS、Linux、Windows 统一禁用在线更新：管理页提示“更新由 magpie-gemini-web 管理”，更新接口返回 HTTP 409，检查更新也不会访问 GitHub。用户自行连接的外部服务不受影响。托管构建方式和可复现构建流程见 docs/studio-release.md。
• Unix 的 package/ 仍尽力设置为 0555，作为额外的文件保护；权限设置失败不阻断服务，在线更新的禁用也不依赖该权限。若要手动删除数据目录来重置，请先停止服务，再运行 chmod -R u+w "<数据目录>/package" 恢复可写权限，然后删除；将 <数据目录> 替换为实际路径。
• 若自行更新到更新版或定制版，插件会提示版本冲突，并提供带正确 --data-dir 的 stop、install、start 命令。停止时会找回更新后的监听进程 PID，并核对可执行文件路径；无法核实身份就不会发送终止信号。HTTP 端口关闭但进程尚未退出时，插件不会重装或启动第二个进程。
• 已停止但文件被替换的后端会从校验通过的固定版本安装包恢复；校验失败不会启动替换文件。安装会保留账号和运行数据文件，但不保证旧版本能读取新版迁移过的数据。手动降级前先停止服务并备份整个数据目录（包括 auth/、runtime/requests.db 等）；已知发生数据迁移时应升级插件以匹配新版后端。
• AI Studio 后端基础请求期限为 30 分钟；插件默认单次响应等待／流空闲超时也是 30 分钟（仍可用 studio.requestTimeoutMs 调整）。这允许非流式长回复在服务端完整收集；后端卡死时也可能等满 30 分钟，且单 worker 会拖住后续请求。可主动取消请求或设置更短的等待时间，但较短期限可能中断正常长回复。上游自动续写的期限按其规则计算。
• 已核对本机 Magpie v0.1.1285（d783df46）源码：插件请求走 Provider.Do → plugin.Fetch → loader.fetch，绕过普通 HTTP transport 的 10 分钟响应头限制；此插件生成路径没有发现更短的固定总超时。网关 5 分钟 IdleTimeout 仅针对请求之间的空闲连接。客户端或反向代理仍可设置更短期限；这不是一次实等 30 分钟的端到端验证。
• 模型列表过滤 -build / assistant_route 模型：这类模型附带 Build 写代码助手的系统提示词，不作为普通 Agent 模型提供。升级后可执行 magpie provider models ai-studio 刷新列表。

• 插件默认使用本仓库发布的 4.27.0-magpie.1（基于上游 v4.27.0 集成 XSRF 缓存、请求取消传播、工具调用提前收尾与 Argon 校验补丁）。对话请求按上游沉默计时：Google 让请求排队时每 60 秒发一次心跳，后端会一直等到出字；连续 request_timeout_sec（默认 180 秒）没有任何数据才放弃这一次并重试，还在出字的长回复也不会被截断。
• 旧版升级：插件不会打断运行中的后端。先停止旧进程（PID 见数据目录 backend.pid），下次启动 Magpie 或发请求时会自动更新二进制并保留原有配置与账号。
• 回退官方版 / 恢复优化版（停止后端后在插件目录执行）：

npm run backend:install:upstream  # 回退并固定使用官方 v4.27.0
  npm run backend:install           # 恢复默认优化版

• 源码复现构建与发布流程见 docs/backend-release.md。