1. 为什么要在 macOS 上跑 Mano-P 这类端侧 GUI 智能体Mano-P 是一个面向端侧设备的 GUI 智能体项目核心能力是让模型直接“看屏幕、动鼠标、敲键盘”用自然语言完成桌面自动化任务。它适合三类人一是想把重复桌面操作交给 AI 的普通用户二是需要本地推理、数据不出设备的安全敏感场景三是想研究 GUI-VLA视觉-语言-动作闭环的开发者。在 macOS 上它通过mano-cua这个命令行工具落地配合 Homebrew 安装门槛比想象中低。我最初关注它是因为很多 GUI 自动化方案要么依赖云端截图上传要么需要自己拼一堆 Python 依赖。Mano-P 的思路不一样它把“截图—推理—执行”做成一个闭环本地有算力就本地跑没有就切云端客户端只负责执行动作。对 macOS 用户来说这意味着你可以用一条mano-cua run ...命令让智能体自己打开访达、创建文件夹、在 Safari 里搜索甚至操作微信发消息。但真正跑起来之前有两个现实问题必须解决。第一是权限macOS 对屏幕录制和辅助功能管得很严没配好权限命令执行了也只会报“无法录制屏幕”。第二是模型调用通道Mano-P 的推理需要模型服务如果你不想把截图发到不可控的端点或者想统一管理 Key就需要一个稳定的 API 通道。这也是本文把 TaoToken 统一 Key 接入放在前面的原因——先把模型调用链路打通再跑桌面任务排障会清晰很多。这一节先明确目标在 macOS 上用 Homebrew 装好mano-cua配好屏幕录制与辅助功能权限再用 TaoToken 的 API 通道给智能体提供模型调用能力最后跑通一次桌面自动化任务并看到预期输出。下面按步骤来命令都可以直接复制。2. TaoToken 统一 Key 与 API 通道准备Mano-P 的本地模式依赖本地模型或算力棒但很多人的 Mac 并没有 M4 32GB 的配置这时候云端推理就是默认路径。云端推理需要模型服务地址和 Key。TaoToken 在这里的角色是提供一个统一的 API 通道你拿到一个 Key就可以在mano-cua的环境变量或配置文件里指定 Base URL 和 Model ID让智能体的推理请求走这条通道。先拿 Key。打开 TaoToken 官网https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content注册后进入控制台在 API Keys 页面创建一个新 Key。建议给这个 Key 起个名字比如mano-p-macos方便后面区分。创建后立刻复制页面刷新后就看不到完整 Key 了。拿到 Key 之后你需要确认两件事Base URL 和 Model ID。TaoToken 的 API 地址是https://taotoken.net/api注意这个地址不加 UTM 参数直接作为请求前缀。Model ID 则取决于你想让 Mano-P 用哪个视觉模型来解析截图。在控制台的模型列表里选一个支持视觉输入的模型把它的 ID 记下来比如gpt-4o或claude-3-5-sonnet这类。Mano-P 的推理需要模型能理解截图内容所以不要选纯文本模型。接下来是配置方式。mano-cua支持通过环境变量读取模型配置常见的是OPENAI_API_KEY、OPENAI_BASE_URL和MANO_MODEL这三个。你可以在终端里临时导出也可以写进 shell 配置文件。临时导出适合先验证export OPENAI_API_KEY你的TaoToken Key export OPENAI_BASE_URLhttps://taotoken.net/api export MANO_MODELgpt-4o如果你希望每次打开终端都生效就把这三行加到~/.zshrc里然后执行source ~/.zshrc。注意 Key 不要提交到 Git也不要在截图里暴露。如果你用 Claude Code 集成方式还需要在 Claude Code 的配置里指定同样的 Base URL 和 Key后面第 4 节会给出 settings 片段。这里有个容易踩的坑OPENAI_BASE_URL末尾不要多加/v1TaoToken 的 API 路径已经包含了版本前缀多写会导致 404。另外如果你之前配过其他服务的环境变量先unset掉避免冲突。验证通道是否通可以用一条 curl 命令测一下模型列表或一次简单对话确认返回 200 再继续装mano-cua。3. Homebrew 安装 mano-cua 与可复制配置片段这一节是实操核心。先确认 Homebrew 已安装。在终端输入brew -v如果显示版本号就跳过安装如果提示command not found先装 Homebrew。安装命令如下/bin/bash -c $(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)如果提示需要 Xcode 命令行工具按终端提示执行xcode-select --install装完再重新跑上面的命令。Homebrew 装好后直接安装mano-cuabrew install HanningWang/tap/mano-cua这个命令会自动创建独立的 Python 3.13 虚拟环境不会污染系统 Python。安装完成后终端会显示Successfully installed mano-cua。验证安装mano-cua -h如果看到run、stop等命令说明就说明装好了。如果提示command not found先重启终端再试仍然不行就检查 Homebrew 的 bin 目录是否在 PATH 里。接下来是配置文件。mano-cua会读取一个 JSON 配置文件路径通常在~/.config/mano-cua/config.json。你可以手动创建这个文件把 TaoToken 的通道信息写进去这样就不依赖环境变量了。配置片段如下{ model: { provider: openai, base_url: https://taotoken.net/api, api_key: 你的TaoToken Key, model_id: gpt-4o }, runtime: { mode: auto, screenshot_interval: 1.5, max_steps: 30 } }注意mode设为auto让mano-cua自动检测本地模型如果没有本地模型它会走云端也就是用你配的 TaoToken 通道。screenshot_interval控制截图间隔太小会增加推理频率太大可能错过界面变化1.5 秒是个折中值。max_steps限制单任务最大步数防止死循环。如果你用 Claude Code 集成还需要在 Claude Code 的 settings 里加一段。路径是~/Library/Application Support/Claude Code/settings.json片段如下{ mcpServers: { mano-cua: { command: mano-cua, args: [mcp], env: { OPENAI_API_KEY: 你的TaoToken Key, OPENAI_BASE_URL: https://taotoken.net/api, MANO_MODEL: gpt-4o } } } }这段配置把mano-cua作为 MCP 服务注册给 Claude CodeClaude Code 就能在会话里调用桌面自动化能力。注意 Base URL、Key、Model ID 三件套要写全缺一个都会导致调用失败。配置写完后重启 Claude Code让它重新加载 MCP 服务。权限配置不能忘。打开“系统设置”→“隐私与安全”→“屏幕录制”点“”号把终端加进去再到“辅助功能”里同样加上终端。加完后必须重启终端否则权限不生效。如果你用 iTerm2也要把 iTerm2 加进去。这一步没做后面执行任务会直接报权限不足。4. 验证请求与一次桌面自动化任务的成功结果配置完成后先做一次最小验证让mano-cua执行一个简单任务确认模型通道和权限都正常。打开终端输入mano-cua run 打开访达进入文稿文件夹创建一个名为 Mano-P 测试 的文件夹预期行为是终端开始输出步骤日志屏幕上的鼠标会自己移动访达被打开进入文稿目录新建文件夹。终端日志大致会显示截图捕获、模型推理、动作执行三个阶段。如果看到类似step 1: screenshot captured、step 2: model response: click Finder icon、step 3: action executed这样的输出说明链路通了。任务结束后你可以去文稿文件夹确认Mano-P 测试文件夹是否存在。如果存在说明从 TaoToken 通道到mano-cua执行器的整条链路都正常。这一步很关键因为它同时验证了三件事TaoToken Key 有效、Base URL 正确、macOS 权限到位。再跑一个稍微复杂点的任务验证多步闭环mano-cua run 打开 Safari搜索 Mano-P 最新版本把第一条搜索结果的标题读出来这个任务涉及打开应用、输入搜索词、读取页面内容能测试智能体的多步规划能力。预期输出会在终端里打印出第一条结果的标题文本。如果中途某一步失败mano-cua会尝试调整比如重新聚焦地址栏、检查窗口是否最小化。你可以在日志里看到retry或adjust字样。如果你用 Claude Code 集成验证方式是在 Claude Code 会话里输入“帮我打开 Excel创建一个表格包含姓名、年龄、联系方式三列填入 3 条测试数据”。Claude Code 会自动调用mano-cua的 MCP 服务你会在 Claude Code 的界面里看到工具调用记录。任务完成后Excel 里应该出现对应的表格。实测下来第一次跑任务时建议把screenshot_interval调大一点比如 2 秒给模型更多时间分析界面。等稳定后再调回 1.5 秒。另外任务执行过程中不要手动动鼠标键盘否则会干扰智能体的动作序列。5. 本篇常见错误排查401、local proxy failed、reading choices、OAuth跑mano-cua时最容易遇到四类报错下面逐个对照。第一类401 Unauthorized。终端输出401或invalid api key。这通常是 TaoToken Key 没配对或者环境变量和配置文件里的 Key 不一致。检查~/.config/mano-cua/config.json里的api_key是否和 TaoToken 控制台里的一致注意不要有多余空格。如果你同时设了环境变量和配置文件环境变量优先级更高先unset OPENAI_API_KEY再试。另外确认 Base URL 是https://taotoken.net/api末尾没有多余的/v1。第二类local proxy failed。终端输出local proxy failed或connection refused。这通常是因为你之前配过本地代理但代理服务没启动。检查~/.zshrc里有没有HTTP_PROXY、HTTPS_PROXY之类的变量有的话先注释掉执行source ~/.zshrc后重试。如果你确实需要走代理确保代理服务在运行并且mano-cua的配置里没有冲突的 Base URL。第三类reading choices 报错。终端输出error reading choices或unexpected response format。这通常是模型返回的格式不符合mano-cua的预期常见原因是 Model ID 选错了比如选了纯文本模型而不是视觉模型。回到 TaoToken 控制台确认你用的 Model ID 支持视觉输入。另外如果模型返回了空内容也会触发这个错误检查截图是否成功捕获权限是否生效。第四类OAuth 相关报错。如果你用 Claude Code 集成可能会看到OAuth token expired或authentication failed。这通常是 Claude Code 自身的登录态过期和 TaoToken 无关。重新登录 Claude Code 即可。如果同时用了 TaoToken 的 Key确认 MCP 配置里的env字段写全了 Base URL、Key、Model ID 三件套缺一个都会导致认证失败。还有一个常见问题是权限不足终端输出screen recording permission denied。回到系统设置把终端从屏幕录制和辅助功能里移除重新添加然后重启终端。如果系统提示无法修改先解锁左下角的锁。排障时建议先跑mano-cua -h确认工具本身可用再用一条最简单的任务验证通道。如果简单任务能跑通复杂任务失败那就是任务描述或界面识别的问题不是配置问题。6. 长期使用与 CTA把 Mano-P 接入你的日常工作流跑通一次任务之后你可以把mano-cua用在更多场景。比如每天早上让它打开邮件客户端、整理未读邮件或者让它定时打开某个网页、截图保存。对于开发者可以把mano-cua作为 MCP 服务接入 Claude Code让编码助手在需要时直接操作桌面应用比如打开终端跑测试、在浏览器里验证页面。如果你打算长期用建议把 TaoToken 的 Key 管理起来。在控制台里可以创建多个 Key给不同工具分配不同的 Key方便追踪用量。如果团队使用可以把 Key 放在统一的配置管理里避免散落在各个终端。TaoToken 的 API 通道支持模型切换你可以在配置文件里改model_id不用改代码。对于需要长期编码和 Agent 任务的场景可以了解 TaoToken 的 Coding Plan它更适合高频调用。如果你只是想验证模型对话效果可以用模型对话页面快速测试。接入文档里有更详细的参数说明排障时可以先查文档。最后提醒一点mano-cua的云端模式会把截图发送到模型服务所以运行任务时避免屏幕上显示敏感信息。如果你处理的是敏感数据优先用本地模式或者确保 TaoToken 通道的端点符合你的安全要求。定期执行brew update mano-cua更新工具获取最新的兼容性修复。