# quick-image-agent-plugin **Repository Path**: beansmile/quick-image-agent-plugin ## Basic Information - **Project Name**: quick-image-agent-plugin - **Description**: No description available - **Primary Language**: JavaScript - **License**: Not specified - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-09-29 - **Last Updated**: 2026-09-29 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # Quick Image Agent Plugin Quick Image Agent Plugin 让 Codex、WorkBuddy、OpenClaw 等 AI Agent 宿主可以使用当前会话附件，以及宿主或 AI 根据用户意图提供的本地图片、视频和音频完成 AI 图片和视频生成。所有宿主复用同一套 Skill 与 Quick Image MCP；OpenClaw 在此之上额外提供会话附件列表与结果预览投递两个专属原生工具。 - 支持搭配出图、换姿、高清和视频生成。 - 创建任务前先展示预估价格，只有在你确认后才处理并上传附件。 - 生成完成后返回预览和原文件下载链接。 [Quick Image 官网](https://quickimage.ai) · [https://gitee.com/beansmile/quick-image-agent-plugin](https://gitee.com/beansmile/quick-image-agent-plugin) 本仓库源码公开可查看，但不是开源软件。安装和使用受 [Quick Image Agent Plugin License](LICENSE)、[服务条款](https://quickimage.ai/terms)和[隐私政策](https://quickimage.ai/privacy)约束。 ## 安装 ### Codex Quick Image 暂未上架 Codex 官方 Plugin Marketplace，请从以下仓库地址安装： ```bash 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 通过终端执行： ```bash 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 安装并启用插件： ```bash openclaw plugins install quick-image-agent-plugin --force openclaw plugins enable quick-image ``` 插件从 npm Registry 安装，每次执行都会实时解析最新正式版本；`--force` 允许覆盖已安装版本，因此首次安装与更新使用同一条命令，重复执行是安全的。 然后运行安装向导： ```bash openclaw quick-image setup ``` `setup` 会在保留原有条目的前提下，将 `quick-image` 插件与 `quick-image-local` 本地 MCP 加入 `tools.alsoAllow`，使用正式环境配置覆盖远程 MCP（`quick-image`），并登记本地处理 MCP（`quick-image-local`，提供附件检查、报价、上传和预览下载工具），然后重新加载 MCP 配置。重复执行不会重复添加工具权限。安装或更新完成后，需要重启 Gateway 以加载新安装的 Plugin： ```bash 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 的终端执行： ```bash openclaw mcp login quick-image ``` 登录命令会输出授权链接，该链接会直接进入 Quick Image 前台登录和授权页。浏览器批准后，授权完成页会显示一次性授权码和已经填好授权码的完整命令，请将该命令粘贴到同一个终端执行，例如： ```bash openclaw mcp login quick-image --code '<授权码>' ``` 登录成功后无需重启 Gateway。建议在当前对话中发送 `/reset` 重置会话上下文；若重置后仍无法使用 Quick Image，再执行 `openclaw mcp probe quick-image` 排查连接状态。 ### 检查环境与恢复正式默认 如果维护者曾切换过环境、需要恢复为默认的正式环境，执行： ```bash npx --yes --prefer-online \ --package quick-image-agent-runtime@latest \ quick-image env reset --host ``` `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](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`： ```bash openclaw mcp reload ``` 3. 仍查不到时，执行探测确认连接与授权状态： ```bash openclaw mcp probe quick-image ``` 4. 仅当新安装或更新插件后从未重启过 Gateway 时，才需要重启以加载新插件；正常安装流程一般已执行过： ```bash 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](DEVELOPMENT.md) - 使用问题与贡献政策：[CONTRIBUTING.md](CONTRIBUTING.md)