GPT Image Studio Companion CLI

本地 CLI 助手，为 GPT Image Studio 网页端提供安全的 API 凭据代理服务。

安装与运行

npm 安装

推荐用户通过 npm 全局安装：

npm install -g @honlnk/image-studio-companion
gpt-image-studio login
gpt-image-studio start

已安装 pnpm 的用户也可以使用：

pnpm add -g @honlnk/image-studio-companion
gpt-image-studio login
gpt-image-studio start

从源码开发运行

项目使用 pnpm workspace。在仓库根目录执行：

pnpm install
pnpm dev:companion

pnpm dev:companion 会以开发渠道启动服务，默认允许本地 Web App origin。

从源码构建后运行

pnpm --filter @honlnk/image-studio-companion build
pnpm --filter @honlnk/image-studio-companion start

也可以直接调用入口文件：

npx tsx companion/src/main.ts serve --port 19750

生产渠道运行

通过 npm 安装后，生产渠道默认只允许正式站点访问本地 companion：

gpt-image-studio start

如需临时允许额外调试页面，必须显式提供完整 origin：

gpt-image-studio start --channel stable --allow-origin http://localhost:5173

启动后监听 127.0.0.1:19750。如果还没有完成配对，start 会在当前终端等待网页端首次配对成功，然后退出；后台服务会继续运行。

命令

serve — 启动本地服务

gpt-image-studio serve
# 源码开发时也可以直接调用入口文件
npx tsx companion/src/main.ts serve

常用参数：

| 参数 | 说明 | |------|------| | --port <port> | 指定监听端口，默认 19750 | | --channel stable|dev | 指定安全渠道；stable 只允许正式站点，dev 额外允许本地开发 origin | | --allow-origin <origin...> | 追加允许的完整 origin，不支持通配符 | | --session-ttl-days <days> | 指定配对 session 有效天数，默认 30 天 |

start — 后台启动服务

gpt-image-studio start

后台启动 companion 服务，日志写入 ~/.gpt-image-studio/logs/，PID 信息写入 ~/.gpt-image-studio/companion.pid。start 只负责启动服务，需要配对时请另行运行 gpt-image-studio pair。

start 支持和 serve 相同的端口、channel、origin 和 session 参数。

stop / restart — 管理后台服务

gpt-image-studio stop
gpt-image-studio restart

stop 只会停止由 start 记录的 companion 后台进程，不会按端口杀掉未知进程。

logs — 查看后台日志

gpt-image-studio logs
gpt-image-studio logs --lines 200
gpt-image-studio logs --follow
gpt-image-studio logs --date 2026-05-25

默认显示当前后台日志最后 100 行。每次 start 时会自动清理 7 天前的 companion 日志。

pair — 重新发起配对

gpt-image-studio pair
gpt-image-studio pair --port 19750

进入配对模式并等待网页端发起配对。运行后在网页设置中点击「开始配对」，当前终端会显示 6 位配对码，并等待网页端完成确认。进入配对模式会清除旧的本地 session，适合网页端断开连接后重新连接。

login — 配置 API 凭据

gpt-image-studio login
# 源码开发时
npx tsx companion/src/main.ts login

交互式输入：

1. API Base URL — 回车使用默认值 https://api.openai.com/v1/images
2. API Key — 输入时不回显

凭据保存到 ~/.gpt-image-studio/credentials.json。

status — 查看状态

gpt-image-studio status
# 源码开发时
npx tsx companion/src/main.ts status

显示：

• 凭据配置情况（Base URL + 脱敏后的 API Key）
• 配对状态
• 服务是否运行

logout — 清除凭据

gpt-image-studio logout
# 源码开发时
npx tsx companion/src/main.ts logout

删除本地保存的 API 凭据文件。

unpair — 清除网页端配对

gpt-image-studio unpair
# 源码开发时
npx tsx companion/src/main.ts unpair

删除本地保存的配对 session，不会清除 API 凭据。

配对流程

1. 启动 companion 服务（gpt-image-studio start）
2. 运行 gpt-image-studio pair 进入配对模式
3. 在网页端设置中切换到「本地 Companion」模式并点击「开始配对」
4. 在终端查看 6 位配对码
5. 在网页端输入配对码完成连接

配对码有效期 5 分钟。配对成功后，session token 保存在 ~/.gpt-image-studio/session.json，默认有效期 30 天，下次启动服务时自动恢复。可以通过 --session-ttl-days 调整有效天数。

网页端点击「断开连接」会通知 Companion 清除本地 session。如果浏览器已经丢失 token，也可以运行 gpt-image-studio unpair 手动清除。

数据目录

所有本地状态保存在 ~/.gpt-image-studio/：

| 文件 | 内容 | |------|------| | credentials.json | API Base URL + API Key | | session.json | 配对 session token |

升级

npm 安装升级

使用全局安装的用户可以通过同一包管理器升级：

npm update -g @honlnk/image-studio-companion
# 或
pnpm update -g @honlnk/image-studio-companion

升级后建议运行：

gpt-image-studio status

源码升级

从源码升级时，在仓库根目录拉取最新代码并重新安装依赖：

git pull
pnpm install
pnpm --filter @honlnk/image-studio-companion build

升级不会自动删除 ~/.gpt-image-studio/ 中的凭据和配对 session。升级后建议运行：

npx tsx companion/src/main.ts status

如果服务端口、正式站点 origin 或 session 策略发生变化，重新启动 serve 后按网页端提示重新配对。

卸载与清理

npm 卸载

使用全局安装的用户可以执行：

npm uninstall -g @honlnk/image-studio-companion
# 或
pnpm remove -g @honlnk/image-studio-companion

卸载 npm 包不会自动删除 ~/.gpt-image-studio/ 中的凭据和配对 session。

本地状态清理

停止 companion 进程后，可以按需要清理本地状态：

# 只清除 API 凭据
gpt-image-studio logout
# 源码开发时
npx tsx companion/src/main.ts logout

# 只清除网页端配对 session
gpt-image-studio unpair
# 源码开发时
npx tsx companion/src/main.ts unpair

# 完整删除 companion 本地状态
rm -rf ~/.gpt-image-studio

如果只是切换 API key，运行 login 覆盖当前凭据即可，不需要删除整个目录。

安全说明

• 服务仅监听 127.0.0.1，不对外暴露
• CORS 白名单默认只允许 https://image.honlnk.com
• --channel dev 会额外允许 http://127.0.0.1:8888 和 http://localhost:8888
• --allow-origin 只接受完整 origin，不支持通配符
• 非公开端点需要配对后的 Bearer token 鉴权
• 网页端无法读取真实 API Key，只能通过代理发起请求
• 代理请求会限制 body 大小、引用图片数量和图片 MIME 类型
• 日志会脱敏 Authorization、API key 和图片 base64 字段
• 凭据和 session 文件会以 0600 权限写入
• 凭据当前以明文 JSON 保存，请确保在个人设备上使用