AIstudioProxyAPI 常用 CLI 命令与工具详解

AIstudioProxyAPI v4.1.2_py 命令详解：launch_camoufox.py 全参数实测、模式与端口组合验证、camoufox fetch、systemd 管理与 OpenAI 兼容 API 调用及生命周期判断。

AIstudioProxyAPIAIstudioProxyAPILLM2026/10/23

AIstudioProxyAPI 常用 CLI 命令与工具详解

目标：系统梳理 AIstudioProxyAPI v4.1.2_py 的命令行使用——launch_camoufox.py 启动器全参数详解（含真实 --help 回显）、参数组合实测、camoufox 辅助工具、systemd 服务管理与 OpenAI 兼容 API 调用命令。本项目不提供独立 CLI 二进制，命令面由「启动器脚本参数 + curl API 调用 + 系统服务管理」三部分构成，全部命令在 Ubuntu 22.04 实测取证。

一、环境信息

  • 操作系统：Ubuntu 22.04（x86_64）
  • AIstudioProxyAPI：v4.1.2_py（2026-04-18 发布），安装路径 /opt/AIstudioProxyAPI
  • Python 3.10.12 + Poetry 2.5.1（命令经 poetry run 前缀执行）
  • Camoufox 浏览器：/root/.cache/camoufox/（经 camoufox fetch 安装，约 2.4GB）
  • 实测端口：主 API 2048/8150、Camoufox 调试端口 9222
  • 项目命令入口清单：launch_camoufox.py（主启动器）、server.py（服务本体，见 4.6）、camoufox（浏览器管理）、simple_start.sh（快捷脚本）

二、工具概览

命令/工具定位典型用法
poetry run python launch_camoufox.py主启动器：拉起 Camoufox 浏览器 + FastAPI 服务日常启停、首次登录、无头常驻
poetry run python server.pyFastAPI 服务本体（不管理浏览器）仅连接外部浏览器实例时使用
poetry run camoufox fetchCamoufox 浏览器本体下载安装/重装浏览器
curlOpenAI 兼容 API 调用与健康检查/health、/v1/models、/v1/chat/completions
systemctlsystemd 服务托管生产常驻启停
poetry run pytest项目测试套件开发/改码后回归

命令间关系：launch_camoufox.py 是唯一推荐的完整入口，它内部完成「依赖检查 → 端口检查 → 启动 Camoufox 子进程 → 注入 CAMOUFOX_WS_ENDPOINT → 启动 FastAPI（server.py 的 app）」全链路；server.py 只是链路的最后一段，单独运行必须自备浏览器端点。

三、前置条件

  • 已按《AIstudioProxyAPI 安装指南》完成安装：Poetry 依赖就位、camoufox fetch 已执行、系统 GUI 库已补齐；
  • headless 模式需要 auth_profiles/active/ 存在有效认证 JSON（首次用 --debug 登录生成；无认证时的实测报错见安装指南 4.8 排障实录）；
  • 本篇全部命令默认在项目目录执行：cd /opt/AIstudioProxyAPI。

四、各工具详解

4.1 launch_camoufox.py 参数总览与 --help 实测

先看帮助（真实回显，实测照抄；日志头尾为启动器初始化输出）：

poetry run python launch_camoufox.py --help

usage: launch_camoufox.py [-h] [--server-port SERVER_PORT]
                          [--stream-port STREAM_PORT] [--helper HELPER]
                          [--camoufox-debug-port CAMOUFOX_DEBUG_PORT]
                          [--debug | --headless | --virtual-display]
                          [--active-auth-json ACTIVE_AUTH_JSON]
                          [--auto-save-auth] [--save-auth-as SAVE_AUTH_AS]
                          [--auth-save-timeout AUTH_SAVE_TIMEOUT]
                          [--exit-on-auth-save]
                          [--auto-auth-rotation-on-startup AUTO_AUTH_ROTATION_ON_STARTUP]
                          [--server-log-level {DEBUG,INFO,WARNING,ERROR,CRITICAL}]
                          [--server-redirect-print] [--debug-logs]
                          [--trace-logs]

Launcher for Camoufox browser simulation and FastAPI proxy server.

options:
  -h, --help            show this help message and exit
  --server-port SERVER_PORT
                        Port number for FastAPI server (Default: 2048)
                        (default: 2048)
  --stream-port STREAM_PORT
                        Port for stream proxy server. Provide --stream-port=0
                        to disable. Default: 3120 (default: 3120)
  --helper HELPER       Helper server getStreamResponse endpoint (e.g.,
                        http://127.0.0.1:3121/getStreamResponse). Provide
                        empty string (e.g., --helper='') to disable. Default:
                        (default: )
  --camoufox-debug-port CAMOUFOX_DEBUG_PORT
                        Debug port number for internal Camoufox instance
                        (Default: 9222) (default: 9222)
  --debug               Start debug mode (browser UI visible, allows
                        interactive auth) (default: False)
  --headless            Start headless mode (no browser UI, requires saved
                        auth file) (default: False)
  --virtual-display     Start headless mode with virtual display (Xvfb, Linux
                        only) (default: False)
  --active-auth-json ACTIVE_AUTH_JSON
                        [Headless/Debug Optional] Path to active auth JSON file (in auth_profiles/active/ or saved/, or absolute path). 
                        If not provided, headless mode uses latest in active/, debug mode prompts or uses none. (default:
                        None)
  --auto-save-auth      [Debug Mode] Automatically prompt to save new auth
                        state after successful login if no auth file was
                        loaded. (default: False)
  --save-auth-as SAVE_AUTH_AS
                        [Debug Mode] Specify filename for saving new auth file
                        (without .json suffix). (default: None)
  --auth-save-timeout AUTH_SAVE_TIMEOUT
                        [Debug Mode] Timeout (seconds) for auto-save auth or
                        filename input. Default: 30 (default: 30)
  --exit-on-auth-save   [Debug Mode] Automatically close launcher and all
                        processes after successful auth save via UI.
                        (default: False)
  --auto-auth-rotation-on-startup AUTO_AUTH_ROTATION_ON_STARTUP
                        Enable auto-rotation to saved/emergency profiles on
                        startup if active profile is missing (true/false).
                        (default: false)
  --server-log-level {DEBUG,INFO,WARNING,ERROR,CRITICAL}
                        Log level for server.py. Default: INFO (default: INFO)
  --server-redirect-print
                        Redirect print output in server.py to its logging
                        system. Default is not to redirect so input() prompts
                        in debug mode are visible. (default: False)
  --debug-logs          Enable DEBUG level detailed logs inside server.py (env
                        DEBUG_LOGS_ENABLED). (default: False)
  --trace-logs          Enable TRACE level more detailed logs inside server.py
                        (env TRACE_LOGS_ENABLED). (default: False)

参数按功能域解读：

功能域参数说明
模式选择（三选一互斥）--debug / --headless / --virtual-display浏览器可见调试 / 无头常驻 / Xvfb 虚拟显示无头
端口--server-port、--stream-port、--camoufox-debug-port主 API 端口（默认 2048）、流代理端口（0=关闭）、浏览器调试端口（默认 9222）
认证--active-auth-json、--auto-save-auth、--save-auth-as、--auth-save-timeout、--exit-on-auth-save指定认证文件、自动保存、保存命名、保存超时、保存后退出
轮转--auto-auth-rotation-on-startup启动时 active 缺失则自动轮转到 saved/emergency 池
日志--server-log-level、--debug-logs、--trace-logs、--server-redirect-print级别与详细度控制
外部 helper--helper指定外部流式响应端点，空串禁用

4.2 模式组合实测：指定端口 + 关闭流代理

换端口并关闭流式代理的组合（2048 被占用时常用），实测启动（认证未配置，预期止步于认证检查，但端口参数生效可从日志确认）：

poetry run python launch_camoufox.py --headless --server-port 8150 --stream-port 0

实测日志关键行（照抄）：

--- Step 2: Check if FastAPI server target port (8150) is in use ---
  ✅ Port 8150 (host 0.0.0.0) is currently available.
--- Step 5: Start Integrated FastAPI Server (Listening on: 8150) ---

验证结论：--server-port 同时作用于端口检查（Step 2）与 FastAPI 监听（Step 5）；--stream-port 0 时启动日志中不再出现 STREAM proxy 相关行。

4.3 LAUNCH_MODE 环境变量与命令行参数的优先级实测

.env 设 LAUNCH_MODE=headless、命令行给 --debug，验证覆盖关系：

grep '^LAUNCH_MODE=' .env

LAUNCH_MODE=headless

poetry run python launch_camoufox.py --debug 2>&1 | grep 'Final selected launch mode'

Final selected launch mode: debug mode

验证结论：命令行参数优先于 .env 环境变量——启动器日志明确打印最终选择的模式。与《AIstudioProxyAPI 配置参数详解》3.1 的优先级规则一致。

4.4 日常启停命令速查

# 首次登录（浏览器可见，登录后自动保存认证）
poetry run python launch_camoufox.py --debug --auto-save-auth --save-auth-as admin

# 无头常驻（需已完成登录保存认证）
poetry run python launch_camoufox.py --headless

# 无图形界面的 Linux 服务器（Xvfb 虚拟显示）
poetry run python launch_camoufox.py --virtual-display

# 指定认证文件启动
poetry run python launch_camoufox.py --headless --active-auth-json auth_profiles/active/admin.json

# 指定日志级别启动（排障）
poetry run python launch_camoufox.py --headless --server-log-level DEBUG --debug-logs

停止运行：前台运行直接 Ctrl+C（启动器会清理 Camoufox 子进程，实测日志：--- Starting cleanup routine (launch_camoufox.py) --- → ✓ Camoufox (PID: 5515) successfully terminated via SIGTERM.）；systemd 托管用 systemctl stop aistudio-proxy。

4.5 camoufox 浏览器管理工具

浏览器本体下载与校验（安装指南 4.4 的完整用法）：

poetry run camoufox fetch

验证浏览器就位：

ls /root/.cache/camoufox/ | head -6

addons
application.ini
browser
camoufox
camoufox-bin
camoufox.cfg

⚠️ 注意：未执行 fetch 直接启动会报 FileNotFoundError: Version information not found at /root/.cache/camoufox/version.json. Please run 'camoufox fetch' to install.（实测，见安装指南 FAQ Q6）；模型定义文件与浏览器下载均需可访问外网，必要时先 export http_proxy/https_proxy。

4.6 server.py：服务本体（限制用法）

server.py 启动 FastAPI 服务但不管浏览器，直接运行的实测结果（照抄关键行）：

poetry run python server.py

22:26:23.036 INF SYS           Starting STREAM proxy on port 3120 with upstream proxy:
22:26:23.038 INF SYS           [SUCCESS] Received 'READY' signal from STREAM proxy.
22:26:23.075 INF SYS           Starting Playwright...
22:26:23.241 CRT SYS           Application startup failed: CAMOUFOX_WS_ENDPOINT environment variable is missing.
ValueError: CAMOUFOX_WS_ENDPOINT environment variable is missing.

结论：缺浏览器端点即退出。仅当已有独立运行的 Camoufox/Chrome（如远程浏览器）并在 .env 配置 CAMOUFOX_WS_ENDPOINT=ws://127.0.0.1:9222 时才可用此形态；日常一律用 launch_camoufox.py。

4.7 systemd 服务管理

服务文件与启用步骤见《AIstudioProxyAPI 安装指南》4.10，日常管理命令：

systemctl start aistudio-proxy     # 启动
systemctl stop aistudio-proxy      # 停止
systemctl restart aistudio-proxy   # 重启（改 .env 后生效用）
systemctl status aistudio-proxy --no-pager   # 状态与近期日志
journalctl -u aistudio-proxy -f    # 跟踪实时日志

4.8 API 调用命令（curl）

服务完整启动（认证校验通过）后，OpenAI 兼容 API 的调用命令如下（端点清单取证自官方 docs/api-usage.md；响应结构以官方文档口径为准）：

# 健康检查：200=正常；503 时看 details 中 browser/page/worker 状态
curl http://127.0.0.1:2048/health

# 模型列表
curl http://127.0.0.1:2048/v1/models

# 非流式对话
curl -X POST http://127.0.0.1:2048/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"gemini-2.5-pro","messages":[{"role":"user","content":"你好"}]}'

# 流式对话
curl -X POST http://127.0.0.1:2048/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"gemini-2.5-pro","stream":true,"messages":[{"role":"user","content":"写一段 100 字短文"}]}' \
  --no-buffer

# 请求队列查看与取消
curl http://127.0.0.1:2048/v1/queue
curl -X POST http://127.0.0.1:2048/v1/cancel/abc1234

配置了 API Key 时加请求头（二选一）：-H "Authorization: Bearer <token>" 或 -H "X-API-Key: <token>"。

服务未就绪/未启动时的实测回显（实验环境无 Google 认证、服务止步于认证校验，curl 表现照抄）：

curl -s -m 3 http://127.0.0.1:8150/health; echo " exit=$?"

 exit=7

curl 退出码 7 = 连接被拒（进程已退出、端口未监听）。据此可判断服务生命周期：exit=7 服务未在运行；HTTP 503 服务在、浏览器/页面未就绪；HTTP 200 全链路就绪。

⚠️ 注意：对话接口的真实转译输出依赖有效 Google 认证（需自备 Google 账号完成登录），本篇实验环境无法登录 Google，故对话接口仅给官方口径的命令形态与判断方法，未展示编造的模型响应。

五、注意事项

  1. 模式三选一：--debug/--headless/--virtual-display 是互斥参数，同给多个会报 argparse 冲突错误；
  2. headless 前必须有认证：先 --debug 登录保存，否则启动即报 No active profile found（实测见安装指南 4.8）；
  3. 端口冲突先看 Step 2：启动器自检端口占用并给出明确报错，换端口用 --server-port（生效实测见 4.2）；
  4. 命令行参数优先：与 .env 冲突时以命令行为准（实测见 4.3），systemd 单元里的 ExecStart 参数要和 .env 口径核对一致；
  5. 清理靠启动器：停止服务用 Ctrl+C 或 systemctl，让启动器的 cleanup 例程回收 Camoufox 子进程；强杀进程组可能留下浏览器孤儿进程，可用 pgrep -f camoufox 复查；
  6. 升级后重跑 fetch：git pull 切新版本后，若 Camoufox 大版本变化需重跑 poetry run camoufox fetch，再 poetry install 同步依赖。

六、常见问题（FAQ）

Q1：--help 都报错，提示 browserforge 数据文件缺失？ 模型定义文件未下载成功（需外网）。export http_proxy/https_proxy 后重跑 --help 触发自动下载（实测过程见安装指南 4.4）。

Q2：--stream-port 0 与流式请求的关系？ 0 关闭的是流式代理服务（3120 端口进程），/v1/chat/completions 的 stream:true 仍可用；外部 helper 场景才需要 --helper 指定端点。

Q3：systemd 启动后日志在哪？ journalctl -u aistudio-proxy -f 看 stdout；应用日志在项目目录 logs/launch_app.log 与 logs/app.log。

Q4：如何验证我的认证文件会被 headless 使用？ 启动日志会打印实际加载文件：Using first alphabetic JSON file in '/opt/AIstudioProxyAPI/auth_profiles/active': <文件名>（实测照抄）；也可用 --active-auth-json 显式指定。

Q5：8150 端口启动后 curl 报 exit=7？ 按 4.8 判断：服务进程没活到监听阶段。回看启动日志最后 20 行定位（常见为认证失败、端口检查失败、浏览器启动失败三类），对应处置见安装指南第八章 FAQ。

七、参考链接

  1. 官方部署与运维指南（systemd 示例来源）：https://github.com/CJackHwang/AIstudioProxyAPI/blob/main/docs/deployment-and-operations.md
  2. 官方 API 使用说明（端点清单来源）：https://github.com/CJackHwang/AIstudioProxyAPI/blob/main/docs/api-usage.md
  3. 官方排障指南：https://github.com/CJackHwang/AIstudioProxyAPI/blob/main/docs/troubleshooting.md
  4. 日常使用文档：https://github.com/CJackHwang/AIstudioProxyAPI/blob/main/docs/daily-usage.md
  5. 本专栏相关篇目：《AIstudioProxyAPI 安装指南》《AIstudioProxyAPI 配置参数详解》《AIstudioProxyAPI 介绍与选型指南》