CogAgent 部署教程：输入一张截图，让 9B 模型输出可执行的 GUI 操作

【免费下载链接】CogAgentAn open-sourced end-to-end VLM-based GUI Agent项目地址: https://gitcode.com/GitHub_Trending/co/CogAgent

CogAgent 是开源的端到端 VLM 基座 GUI Agent，输入一张屏幕截图和一句中英文指令，它返回该点击哪里、输入什么。按本文操作，你可以在本地部署 CogAgent-9b-20241220 并跑通第一次 GUI 推理。

先跑起来

环境要求：Python 3.10.16+、NVIDIA GPU（BF16 精度推理至少 29GB 显存）。克隆仓库后在根目录执行：

pip install -r requirements.txt python inference/cli_demo.py --model_dir THUDM/cogagent-9b-20241220 --platform "Mac" --max_length 4096 --top_k 1 --output_image_path ./results --format_key status_action_op_sensitive

--model_dir接受本地路径或模型仓库标识，首次运行会自动下载 THUDM/cogagent-9b-20241220 权重（也可从 HuggingFace、ModelScope 手动获取后填本地路径）。启动后终端会依次提示输入任务描述和截图路径，输入exit退出。模型返回带 bbox 的结果时，会保存一张红框标注图到./results，文件名为{你输入的图片名}_{对话轮次}.png。

它是怎么工作的

CogAgent 基于 GLM-4V-9B 构建，定位是执行模型而非对话模型。它不维护连续对话，每一轮推理都需要重新拼接结构化提示词，顺序固定为 Task（任务描述）→ History steps（历史操作）→ Platform（平台）→ format 指令（期望的返回格式）。其中截图是必需输入，纯文字无法完成 GUI Agent 任务。

模型输出采用严格的 STR 格式而非 JSON：按format_key要求返回 Status、Plan、Action 等字段，末尾的 Grounded Operation 描述具体操作，例如CLICK(box=[[219,186,311,207]], element_info='全部标为已读')，box 坐标基于 0–1000 的归一化尺度，示例代码除以 1000 后换算为像素坐标绘制 bbox。多步任务不是靠模型记住上下文，而是把上几轮返回的 Grounded Operation 和 Action 作为 History steps 传回下一轮，由你解析输出并驱动执行。

常见用法

命令行推理

最短命令只给必填参数，其余走默认值：

python inference/cli_demo.py --model_dir THUDM/cogagent-9b-20241220

你会看到终端进入交互循环：输入任务与截图路径后打印完整 query 和模型回复；若回复含 box，终端输出Annotated image saved at: ...，对应的标注图出现在results目录。

Web 界面演示

python inference/web_demo.py --host 0.0.0.0 --port 7860 --model_dir THUDM/cogagent-9b-20241220 --format_key status_action_op_sensitive --platform "Mac" --output_dir ./results

你会看到 7860 端口打开 Gradio 页面：左侧上传截图、输入任务，模型流式返回文本，右侧同步展示红框标注图，页面还提供回退上一轮、清空历史、中途停止按钮。

远程服务加本地自动操作

在 GPU 服务器拉 OpenAI 接口格式的服务端，再在本地跑客户端：

python app/openai_demo.py --model_path THUDM/cogagent-9b-20241220 --host 0.0.0.0 --port 7870

python app/client.py --api_key EMPTY --base_url http://127.0.0.1:7870/v1 --client_name 127.0.0.1 --client_port 7860 --model CogAgent

你会看到客户端 APP 接管电脑：它持续截图发给服务端，按模型返回的坐标执行点击、输入等动作，运行中可随时按 stop 强制停止。此示例仅供学术参考，详见 app/README.md。

常用参数对照

format_key可选值对应五种格式：action_op_sensitive、status_plan_action_op、status_action_op_sensitive、status_action_op、action_op，是否返回敏感操作标记、Status、Plan 字段由它决定。

避坑清单

现象：模型加载阶段 OOM 或无法启动。 原因：BF16 推理至少需要 29GB 显存，官方明确不建议 INT4 量化（性能损失大）。 解法：换用 30GB+ 显存的 GPU；显存不足时在 inference/cli_demo.py 中取消注释 INT8 量化行（约 15GB 显存）。

现象：模型返回的 bbox 位置明显偏移。 原因：截图系统与--platform参数不匹配，例如把 Mac 截图配了 WIN。 解法：截图与平台参数保持同源；未列出的系统可用 Mobile/WIN/Mac 近似，但官方不保证效果。

现象：多轮执行时模型"忘记"之前步骤，或输出字段缺失。 原因：模型不支持连续对话，且要求 Task、History steps、Platform、format 严格按顺序拼接。 解法：即使无历史也要保留History steps:字段；输出是 STR 格式，不支持 JSON 解析，按官方字段名提取。

现象：只发文字任务得不到有效 GUI 结果。 原因：该模型必须传入图片，纯文字对话无法完成 GUI Agent 任务。 解法：每个任务都配一张当前屏幕截图。

现象：客户端 APP 连不上服务端或无法执行操作。 原因：两端未打通网络（需内网穿透），或运行端缺少截图、录屏、模拟键鼠的权限（macOS 需在系统设置中授予终端或 IDE）。 解法：先确认base_url http://127.0.0.1:7870/v1可达，再补齐权限；客户端建议用 venv 创建环境，避免 conda 导致 tkinter 异常。

还能做什么

仓库自带 finetune/ 微调入口：SFT 需要 8 张 A100（每张至少 60GB 显存），LoRA 单卡即可但要求一张 A100 至少 70GB 显存，配置示例在 finetune/configs/lora.yaml；完整动作空间定义见 Action_space.md。模型下载地址、在线体验入口和技术文档汇总在 README_zh.md 的模型资源表中，问题与需求可在仓库 Issues 中提交。

CogAgent 把 GUI 自动化简化为"一张截图加一句指令"，你只需解析 Grounded Operation 接入自己的执行链路。下一步：跑通「先跑起来」一节中的启动命令，用自己的一张桌面截图验证能否输出带 bbox 的结果。

【免费下载链接】CogAgentAn open-sourced end-to-end VLM-based GUI Agent项目地址: https://gitcode.com/GitHub_Trending/co/CogAgent