Quick Image Agent Plugin

Quick Image Agent Plugin 让 Codex、WorkBuddy、OpenClaw 等 AI Agent 宿主可以使用当前会话附件，以及宿主或 AI 根据用户意图提供的本地图片、视频和音频完成 AI 图片和视频生成。所有宿主复用同一套 Skill 与 Quick Image MCP；OpenClaw 在此之上额外提供会话附件列表与结果预览投递两个专属原生工具。

• 支持搭配出图、换姿、高清和视频生成。
• 创建任务前先展示预估价格，只有在你确认后才处理并上传附件。
• 生成完成后返回预览和原文件下载链接。

Quick Image 官网 · https://gitee.com/beansmile/quick-image-agent-plugin

本仓库源码公开可查看，但不是开源软件。安装和使用受 Quick Image Agent Plugin License、服务条款和隐私政策约束。

安装

Codex

Quick Image 暂未上架 Codex 官方 Plugin Marketplace，请从以下仓库地址安装：

codex plugin marketplace add https://gitee.com/beansmile/quick-image-agent-plugin
codex plugin add quick-image@quick-image

安装后需要完成一次 Quick Image MCP 授权，然后新建一个 Codex 任务，让 Skill 和 MCP 工具生效。授权可由 Codex Agent 直接执行下方登录命令完成，只有 Codex 无法执行终端命令时才需要用户在本机终端手动执行。

登录或重新登录 MCP

Codex 在远程 MCP 返回未授权或授权失效时，应先告知用户当前未登录并询问是否需要登录。用户确认后，让 Codex Agent 通过终端执行：

codex mcp login quick-image

命令会打开或输出 Quick Image 登录和授权页。完成浏览器授权后，回到 Codex 并新建任务；桌面端仍看不到 Quick Image 远程工具时，完全退出并重新打开 Codex。不要把 Token、授权码或终端输出发送给 Agent。

如果 Codex 无法执行终端命令，也可以在本机终端手动执行同一条命令。

如果命令提示找不到 quick-image MCP，请先确认插件已安装并启用，再重新执行登录命令。

插件固定使用经过验证的 Quick Image Agent Runtime 版本。Codex 首次加载本地工具、OpenClaw 安装插件依赖时，只会安装当前平台所需的媒体处理依赖，不会下载其他操作系统的二进制。

WorkBuddy

WorkBuddy 暂不支持命令行安装，在客户端界面内手动完成。插件能力与 Codex 通用：复用同一份共享 Skill 与 Quick Image MCP（远程 quick-image 和本地 quick-image-local），附件检查、报价和上传都走同一套本地 MCP 工具；WorkBuddy 客户端不渲染本地路径，图片预览不走本地下载，直接用结果 display_url 在对话内 Markdown 内联。远程授权通过 WorkBuddy 自身的 MCP OAuth 机制完成。

1. 打开 WorkBuddy 客户端，在左侧导航点击「专家·技能·连接器」进入插件管理页面，在「技能」标签页下选择「套件」，点击市场标签行末尾的「+」按钮，在弹出窗口中粘贴下方仓库地址并确认添加市场：

   https://gitee.com/beansmile/quick-image-agent-plugin
   

2. 市场添加成功后，插件列表中会出现「quick-image」套件，点击其「安装」或「+」按钮完成安装。

3. 切换到「连接器」标签页，点击「自定义连接器」，在弹出的「MCP 服务管理」列表中找到「quick-image」，点击「连接」，在打开的浏览器页面中登录 Quick Image 并批准授权。

4. 连接成功后，即可在 WorkBuddy 对话中使用 Quick Image 的图片与视频生成能力；如新工具未生效，完全退出并重新启动 WorkBuddy 客户端。

WorkBuddy 没有 mcp login 类命令，授权失效或需要切换账号时，在「连接器」中对「quick-image」重新点击「连接」，在浏览器重新完成登录授权即可。

OpenClaw

安装并启用插件：

openclaw plugins install quick-image-agent-plugin --force
openclaw plugins enable quick-image

插件从 npm Registry 安装，每次执行都会实时解析最新正式版本；--force 允许覆盖已安装版本，因此首次安装与更新使用同一条命令，重复执行是安全的。

然后运行安装向导：

openclaw quick-image setup

setup 会在保留原有条目的前提下，将 quick-image 插件与 quick-image-local 本地 MCP 加入 tools.alsoAllow，使用正式环境配置覆盖远程 MCP（quick-image），并登记本地处理 MCP（quick-image-local，提供附件检查、报价、上传和预览下载工具），然后重新加载 MCP 配置。重复执行不会重复添加工具权限。安装或更新完成后，需要重启 Gateway 以加载新安装的 Plugin：

openclaw gateway restart

登录或重新登录 MCP

setup 完成后、登录失效或需要切换账号时，OpenClaw 应先告知用户当前未登录并询问是否需要登录。用户确认后，才协助完成远程授权：

1. OpenClaw 执行 openclaw mcp login quick-image，并把命令输出的授权链接发送给用户。
2. 用户在手机浏览器打开链接，登录 Quick Image 并批准授权。
3. 用户只把授权完成页显示的一次性授权码发送到与 OpenClaw 的私聊。
4. OpenClaw 将授权码作为单个参数执行 openclaw mcp login quick-image --code '<授权码>'。登录成功后无需再次重启 Gateway；建议在当前对话中发送 /reset 重置会话上下文，再开始创建 Quick Image 任务。

不要泄露一次性授权码，也不要在非私聊会话中发送；同时不要把授权完成页提供的完整命令发送给 Agent。Agent 只接受单个授权码，不会执行对话中的完整命令或其他 Shell 内容。

手动登录时，在运行 OpenClaw 的终端执行：

openclaw mcp login quick-image

登录命令会输出授权链接，该链接会直接进入 Quick Image 前台登录和授权页。浏览器批准后，授权完成页会显示一次性授权码和已经填好授权码的完整命令，请将该命令粘贴到同一个终端执行，例如：

openclaw mcp login quick-image --code '<授权码>'

登录成功后无需重启 Gateway。建议在当前对话中发送 /reset 重置会话上下文；若重置后仍无法使用 Quick Image，再执行 openclaw mcp probe quick-image 排查连接状态。

检查环境与恢复正式默认

如果维护者曾切换过环境、需要恢复为默认的正式环境，执行：

npx --yes --prefer-online \
  --package quick-image-agent-runtime@latest \
  quick-image env reset --host <codex|openclaw|workbuddy>

reset 会把 Quick Image MCP 恢复为正式环境配置，不影响其他配置内容，可安全重复执行；--host 支持 codex、openclaw 和 workbuddy（Runtime 0.3.0 起提供 workbuddy，需逐个宿主执行）。恢复后需重新完成授权：Codex 重新执行 codex mcp login quick-image 并新建任务加载配置；WorkBuddy 完全退出并重新打开后重新完成 quick-image MCP 授权；OpenClaw 重新执行 openclaw mcp login quick-image，配置即时生效，无需重启 Gateway。

退出登录与切换账号

需要退出登录或撤销授权时，直接对当前宿主的 Agent 说「退出 Quick Image 登录」。Agent 会先向你确认影响，确认后调用 Quick Image 远程工具撤销当前宿主的全部授权（同一宿主在其他设备或连接器上的授权也会一并失效）。撤销后客户端可能仍显示旧的已登录状态，重新登录或切换账号前请先完全退出并重启客户端：Codex 完全退出并重新打开 Codex；WorkBuddy 完全退出并重新启动 WorkBuddy 客户端；OpenClaw 授权即时生效，无需重启。宿主本地残留的失效凭据无害，重新使用时重新完成登录授权即可。

也可以随时在 Quick Image 前台的已授权应用页（https://quickimage.ai/agent-plugin?tab=authorizations）查看和撤销各宿主的授权；Agent 自动撤销失败时，同样可以在该页面自行撤销，撤销后按上述方式重启客户端再重新登录。

切换账号当前不支持直接切换：对 Agent 说「切换 Quick Image 账号」，Agent 会说明流程并确认，先退出当前账号的授权，再提醒你重启客户端并引导你重新登录；重新授权时在浏览器中用想使用的账号完成登录和授权即可。

如何使用

安装并授权后，在新对话中发送所需附件，再直接描述生成目标。例如：

• “用我发送的这些服装图片生成一组搭配图。”
• “把这张人物照片换成站立回头的姿势。”
• “把这张图片提升为高清版本。”
• “参考这张图片和这段音频生成一个视频。”

Quick Image 会先检查附件并给出预估价格。确认价格前不会处理、暂存或上传附件；确认后才会准备附件并创建生成任务。任务完成后，Codex、WorkBuddy 等宿主会在当前任务中返回结果，OpenClaw 会将结果发送到发起请求的会话。

除非用户明确要求分析或描述媒体内容，或用户把效果决定权交给 Agent（如回复“随便”“你推荐”）而需要读取相关图片，Agent 会把图片、音频和视频作为不透明输入处理，不主动预览、播放、转录或识别内容；未获上述授权时仅使用文件名、大小、类型及生成限制所需的技术元数据。授权读取的画面内容只用于拟定提示词或选择模板，不会用于推断各附件的用途。

故障排查与修复

OpenClaw 查不到 Quick Image 远程 MCP 工具

会话中查不到 Quick Image 远程 MCP 工具（例如 get_generation_config、submit_lookbook_task），或工具不可调用时，按顺序排查：

1. 在当前对话发送 /reset 重置会话上下文。安装流程中的 openclaw gateway restart 一般已经执行过，查不到工具的最常见原因是会话未重置：已开始的会话不会自动刷新工具列表。/reset 由用户发送，Agent 不要替用户执行。

2. 重置后仍查不到时，重载 MCP 配置。刚执行过 setup、切换环境或更新插件后，配置可能尚未生效；重载后需再次发送 /reset：

   openclaw mcp reload

3. 仍查不到时，执行探测确认连接与授权状态：

   openclaw mcp probe quick-image

4. 仅当新安装或更新插件后从未重启过 Gateway 时，才需要重启以加载新插件；正常安装流程一般已执行过：

   openclaw gateway restart

5. 以上均无效时，确认插件已安装并启用，必要时重新安装。

探测提示未授权或授权失效时，按上文「登录或重新登录 MCP」先征得用户确认再完成授权。

Codex、WorkBuddy 查不到 Quick Image 远程 MCP 工具

Codex：完成授权后新建一个 Codex 任务，让 Skill 和 MCP 工具生效；桌面端仍看不到时，完全退出并重新打开 Codex。

WorkBuddy：先确认「专家·技能·连接器」中 quick-image 套件已安装，再到「连接器 → 自定义连接器」的「MCP 服务管理」列表确认 quick-image 显示已连接；未连接或授权失效时，对 quick-image 重新点击「连接」完成浏览器授权，然后完全退出并重新启动 WorkBuddy 客户端。安装后从未重启过客户端的，重启后新工具才会加载。

数据与权限

• 插件支持当前会话附件，以及宿主或 AI 根据用户意图提供的本地文件绝对路径或 Runtime 支持的媒体引用。插件信任调用方提供的具体输入，不校验来源或另行实施目录授权；实际可读范围由宿主进程的系统文件权限和 Runtime 的引用解析规则决定。
• 发送生成结果时，图片预览按宿主投递：OpenClaw 由本地 Runtime 受约束下载（仅 HTTPS、拒绝重定向、超时与大小上限、格式校验）到私有缓存后，以本地文件投递聊天渠道；Codex 等仅 Markdown 宿主用下载返回的本地路径嵌入预览；WorkBuddy 客户端不渲染本地路径，直接用预览 display_url 在对话内 Markdown 内联。前两者下载或本地发送失败时退为发送原图链接文本。视频预览直接使用结果地址投递，并按 preview_content_type 标注扩展名文件名。
• 插件不提供 Quick Image 云端图库浏览；用户可以直接提供已知的 Quick Image asset_id，素材归属和可用性由服务端校验。
• 报价阶段不上传附件、不扣费，也不锁定最终价格；最终校验和计费以服务端结果为准。

更多文档

• 本地开发、架构契约和发布校验：DEVELOPMENT.md
• 使用问题与贡献政策：CONTRIBUTING.md