1. 为什么 HITL 配置总在“最后一公里”卡住GUI-Agent 跑自动化任务时最怕的不是模型不会点而是它太敢点。阶跃星辰 Step-GUI 里的 GUI-MCP 把 HITLHuman In The Loop做成了协议级能力当 Agent 遇到验证码、支付确认、信息补充这类需要人类判断的节点会抛出一个 INFO 动作把执行权交还给客户端。这个设计本身很清晰但落到工程配置层问题就来了——settings.json 里 reply_mode 写哪个值、session_id 怎么透传、人工回复通过什么通道回注给 Agent这些细节一旦配错Agent 要么卡死在 INFO 循环里要么直接跳过确认把敏感操作执行了。我试过在本地把 GUI-MCP 的 HITL 链路完整跑通发现真正耗时间的不是理解协议而是把“人工审批”这个动作接到一个稳定的 Key/API 通道上。因为 HITL 回调本质上是一次带上下文的模型请求客户端拿到 INFO 动作后需要把截图、任务描述、Agent 的提问一起发给一个能理解多模态输入的模型生成人类可读的确认提示再把用户的回复回注给 Agent 继续执行。这条链路里如果 Key 管理散落在多个配置文件调试成本会成倍上升。这篇就聚焦 HITL 的配置骨架从 settings.json / config.toml 的字段定义到 CC Switch、Cline 的接入示例再到用 TaoToken 统一 Key 通道完成一次人工审批回调的验证。目标很明确——把 HITL 从“协议里有个 INFO 动作”变成“我本地能跑通一次带人工确认的完整任务”。适合谁看正在给 GUI-Agent 加人工确认环节的开发者手里已经有 Step-GUI 或类似 GUI-MCP 实现需要把 HITL 落到配置文件层面的人。如果你还没接触过 GUI-MCP建议先看前几篇关于 MCP 工具定义和 execute_task 流程的内容这篇默认你已经知道 ask_agent_start_new_task 和 ask_agent_continue 的区别。2. TaoToken 在 HITL 链路里承担什么角色HITL 的核心动作是“暂停—人工输入—恢复”。在 GUI-MCP 的实现里这个暂停由 reply_mode 控制恢复靠 session_id reply_from_client 两个参数。但人工输入的内容不是随便填的它需要被模型理解成“对当前截图中某个问题的回答”。也就是说客户端在把用户回复回注给 Agent 之前往往要先做一次模型调用把用户的自然语言回复转成 Agent 能消费的 query 字段。这一步就是 TaoToken 介入的位置。TaoToken 提供统一的 API 通道把模型调用收敛到一个 Key 上。对于 HITL 场景这意味着客户端侧不需要为“生成确认提示”和“解析用户回复”分别维护不同的模型配置settings.json 里只需要写一个 base_url 和一个 api_key所有 HITL 相关的模型请求都走这条通道调试时切换模型或调整参数改一处配置即可不用在多个文件之间同步。TaoToken 的 API 地址是https://taotoken.net/api官网入口在https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content。注意 API 地址不带 UTM 参数配置里直接写裸地址就行。需要说清楚的是TaoToken 在这里不是“替代 GUI-MCP”而是给 HITL 回调提供一个稳定的模型调用出口。GUI-MCP 负责协议和动作编排TaoToken 负责让“人工审批”这个环节里的模型请求有统一的 Key 通道。两者是配合关系不是替代关系。3. settings.json 与 config.toml 配置骨架GUI-MCP 的配置通常分两层一层是 MCP 客户端侧的 settings.json定义工具调用和 HITL 行为另一层是模型通道侧的 config.toml定义 API 端点和 Key。下面给出可复制的骨架。3.1 settings.jsonHITL 行为定义{ mcpServers: { gui-mcp: { command: python, args: [-m, gui_mcp.server], env: { GUI_MCP_DEVICE_ID: emulator-5554, GUI_MCP_REPLY_MODE: pass_to_client, GUI_MCP_MAX_STEPS: 20, GUI_MCP_SESSION_TIMEOUT: 300 } } }, hitl: { enabled: true, reply_mode: pass_to_client, approval_required_actions: [INFO, PAYMENT_CONFIRM, DELETE_CONFIRM], auto_reply_fallback: false, session_persistence: true, callback_timeout_seconds: 120 } }这里几个字段值得展开reply_mode设成pass_to_client是 HITL 的关键。GUI-MCP 支持四种模式auto_reply让模型自动生成回复no_reply直接忽略Agent 可能卡死manual_reply在服务端控制台手动输入pass_to_client把 INFO 动作抛回客户端。要做人工审批必须用pass_to_client。approval_required_actions列出需要人工确认的动作类型。除了 INFO支付和删除类操作也建议加进来避免 Agent 在敏感节点自作主张。session_persistence打开后session_id 会持久化到本地HITL 中断后可以用同一个 session_id 恢复不用重新初始化任务。3.2 config.tomlTaoToken 统一 Key 通道[model_provider] name taotoken base_url https://taotoken.net/api api_key sk-your-taotoken-key default_model step-gui timeout_seconds 60 max_retries 3 [hitl_model] provider taotoken model step-gui temperature 0.2 max_tokens 512 purpose hitl_approval_prompt [logging] level info log_dir ./logs/gui-mcp log_hitl_events truebase_url写 TaoToken 的 API 地址api_key从 TaoToken 控制台生成。hitl_model这一段专门给 HITL 回调用temperature 调低是因为确认提示需要稳定输出不需要创造性。log_hitl_events打开后每次 INFO 动作的触发、人工回复、恢复执行都会记日志排查时很有用。Key 的获取路径登录 TaoToken 控制台在 API Keys 页面创建新 Key。控制台入口是https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentAPI Keys 页面是https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content。创建时建议给 Key 起个能识别的名字比如gui-mcp-hitl-dev方便后续按环境区分。3.3 CC Switch 接入示例CC Switch 用来在多个模型通道之间切换。把 TaoToken 配成一个 profile{ profiles: { taotoken-hitl: { base_url: https://taotoken.net/api, api_key: sk-your-taotoken-key, model: step-gui, description: GUI-MCP HITL 专用通道 } }, active_profile: taotoken-hitl }切换时只需要改active_profile不用动 settings.json 里的 HITL 配置。这样调试阶段可以在不同模型之间快速对比 HITL 确认提示的质量。3.4 Cline 接入示例Cline 作为 MCP 客户端时配置写在 Cline 的 settings 里{ cline.mcpServers: { gui-mcp: { command: python, args: [-m, gui_mcp.server], env: { GUI_MCP_REPLY_MODE: pass_to_client } } }, cline.apiProvider: taotoken, cline.apiBaseUrl: https://taotoken.net/api, cline.apiKey: sk-your-taotoken-key, cline.model: step-gui }Cline 侧的关键是apiProvider指向 TaoToken这样 Cline 在处理 HITL 回调时模型请求会走统一通道。如果 Cline 和 GUI-MCP 用的是同一个 Key配置里只需要维护一份 api_key。4. 验证一次人工审批回调配置写完后需要跑一次完整的 HITL 回调来验证链路。下面用一个“打开淘宝搜索生日礼物”的任务来演示任务会在搜索前触发 INFO 动作要求人工确认搜索关键词。4.1 启动 MCP 服务并初始化任务先确认设备连接python -m gui_mcp.server --list-devices输出里应该能看到设备 ID比如emulator-5554。然后通过 MCP 客户端调用ask_agent_start_new_task{ tool: ask_agent_start_new_task, arguments: { device_id: emulator-5554, task: 打开淘宝搜索生日礼物遇到需要确认的步骤停下来问我, max_steps: 20, reply_mode: pass_to_client } }注意reply_mode显式写成pass_to_client覆盖 settings.json 里的默认值确保这次调用走人工审批路径。4.2 捕获 INFO 动作Agent 执行几步后会在搜索框输入前触发 INFO。返回结构大致如下{ stop_reason: INFO_ACTION_NEEDS_REPLY, session_id: sess_abc123, final_action: { action_type: INFO, value: 请确认搜索关键词生日礼物。是否继续 }, global_step_idx: 3 }stop_reason是INFO_ACTION_NEEDS_REPLY说明 HITL 中断生效。session_id要记下来恢复时要用。final_action.value就是 Agent 抛给人类的问题。4.3 通过 TaoToken 通道生成确认提示客户端拿到 INFO 后调用 TaoToken 的模型接口把截图和问题一起发过去生成人类可读的确认提示curl -X POST https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer sk-your-taotoken-key \ -H Content-Type: application/json \ -d { model: step-gui, messages: [ { role: system, content: 你是 GUI-Agent 的人工审批助手。根据截图和 Agent 的提问生成一句简洁的确认提示不要多余解释。 }, { role: user, content: Agent 提问请确认搜索关键词生日礼物。是否继续截图描述淘宝首页搜索框为空。 } ], temperature: 0.2, max_tokens: 128 }返回内容类似{ choices: [ { message: { content: Agent 准备在淘宝搜索「生日礼物」确认继续 } } ] }这一步验证了 TaoToken 通道能正常处理 HITL 相关的模型请求。如果返回 401检查 api_key 是否正确如果返回 404检查 base_url 是否写成了带路径的形式正确写法是https://taotoken.net/api不要在后面加/v1。4.4 回注人工回复并恢复任务用户在客户端确认后把回复通过ask_agent_continue回注{ tool: ask_agent_continue, arguments: { device_id: emulator-5554, session_id: sess_abc123, reply_from_client: 确认搜索生日礼物, reply_mode: pass_to_client, max_steps: 20 } }关键参数是session_id和reply_from_client。session_id用上一步返回的值reply_from_client是用户的确认内容。task字段留空因为这是继续会话不是新任务。调用成功后返回结构里stop_reason会变成TASK_COMPLETED_SUCCESSFULLY或继续到下一个 INFO。如果还是INFO_ACTION_NEEDS_REPLY说明 Agent 又抛了一个新问题需要再次走审批流程。4.5 验证结果完整的成功链路应该看到第一次调用返回INFO_ACTION_NEEDS_REPLY带 session_idTaoToken 通道返回确认提示HTTP 200第二次调用返回TASK_COMPLETED_SUCCESSFULLYglobal_step_idx 比第一次大日志文件./logs/gui-mcp/hitl.log里有 INFO 触发和恢复记录。如果日志里看到Passing INFO action to client for reply说明pass_to_client模式生效了。5. 本篇常见错排查5.1 INFO 动作反复触发Agent 卡在同一个问题现象调用ask_agent_continue后返回的stop_reason还是INFO_ACTION_NEEDS_REPLYfinal_action.value和上一次一样。原因通常是reply_from_client没有正确传递或者session_id对不上。检查两点一是session_id是否用了第一次返回的值不要自己拼二是reply_from_client是否为空字符串空字符串会被 Agent 当成“没有回复”继续抛 INFO。另一个可能是reply_mode在ask_agent_continue里被写成了auto_reply导致 Agent 自己生成回复后又触发新的 INFO。确保两次调用的reply_mode都是pass_to_client。5.2 TaoToken 返回 401 或 403401 一般是 api_key 无效或过期。去 TaoToken 控制台确认 Key 状态如果刚创建等几秒再试。403 可能是 Key 没有对应模型的权限检查default_model是否写成了控制台里已开通的模型名。还有一种情况是 api_key 前面多了空格或换行从控制台复制时容易带上。用echo -n sk-xxx | wc -c检查长度或者直接在配置文件里重新粘贴一次。5.3 settings.json 里 reply_mode 不生效GUI-MCP 的工具调用参数优先级高于 settings.json 里的环境变量。如果ask_agent_start_new_task的 arguments 里没写reply_mode才会用GUI_MCP_REPLY_MODE的值。调试时建议在 arguments 里显式写避免被环境变量覆盖。另外GUI_MCP_REPLY_MODE的值必须是auto_reply、no_reply、manual_reply、pass_to_client四个之一大小写敏感。写成Pass_To_Client会被当成未知模式可能直接报错或回退到默认值。5.4 session_id 持久化失败如果session_persistence设为 true 但重启服务后 session_id 丢了检查log_dir是否有写权限。session 文件默认存在./logs/gui-mcp/sessions/下目录不存在时不会自动创建需要手动建mkdir -p ./logs/gui-mcp/sessions chmod 755 ./logs/gui-mcp/sessions5.5 Cline 侧 HITL 回调不走 TaoTokenCline 的apiProvider如果写成openai或其他默认值HITL 回调会走 Cline 内置的通道不走 TaoToken。检查 Cline settings 里cline.apiProvider是否为taotokencline.apiBaseUrl是否为https://taotoken.net/api。改完后重启 Cline让配置生效。6. 把 HITL 配置固化下来的几个习惯跑通一次回调之后建议把配置固化下来避免每次调试都重新拼参数。我的做法是把 settings.json 和 config.toml 都纳入版本管理但 api_key 用环境变量注入不写死在文件里。比如 config.toml 里写api_key ${TAOTOKEN_API_KEY}启动前 export 一下。这样配置文件可以共享Key 不会泄露。HITL 的日志单独存一个文件和普通执行日志分开。排查时直接 grepINFO_ACTION_NEEDS_REPLY能快速定位到所有人工审批节点。如果某个节点的确认提示质量不稳定把对应的截图和 Agent 提问存下来单独调 temperature 或换模型对比。最后approval_required_actions不要只写 INFO。支付、删除、发送消息这类动作即使 Agent 没抛 INFO也建议在客户端侧拦截一次。GUI-MCP 的 HITL 是协议级能力但客户端侧的二次确认是最后一道防线。两者叠加才能让 GUI-Agent 在自动化效率和操作安全之间找到平衡。