1. 从 Claude Code 源码看 Computer Use 到底在 Mac 上做了什么Claude Code 的 Computer Use 能力简单说就是让模型能“看见”屏幕并“动手”操作截屏拿到当前画面再用鼠标键盘事件去点击、输入、滚动。它适合谁适合想把重复的 GUI 操作交给 Agent 的开发者比如自动打开浏览器查资料、批量填表单、跑一遍端到端流程。但很多人卡在第一步源码里那套控制链路到底怎么在 Mac 上跑起来权限怎么给配置写在哪Key 和 API 通道怎么接。我这次把 Claude Code 源码里 Computer Use 的调用链拆了一遍重点看它在 Mac 上如何调用系统能力。核心结论先放这它并不是直接调 AppleScript 或 Accessibility API 的裸接口而是通过一层“宿主环境适配器”把高层工具调用翻译成原生模块动作原生模块再落到 macOS 的辅助功能与屏幕录制权限上。整条链路大致是会话上下文管理 → 宿主环境适配器 → CLI 执行器 → 原生模块鼠标键盘 / 截屏应用管理。会话上下文负责状态、权限检查、文件锁适配器负责创建执行器、检查权限CLI 执行器包装两个原生模块一个管输入一个管截图和应用切换。理解这条链路后配置就不再是玄学。你需要做的是给终端或宿主进程授予辅助功能和屏幕录制权限准备一份 settings.json 描述允许操作的应用白名单再用 config.toml 把模型通道指向统一入口。下面我按可复制的顺序把配置骨架和验证动作写清楚你照着改路径就能在本地复现控制流程。2. TaoToken 前置统一 Key 与 API 通道别让多套凭证拖慢调试在复现 Computer Use 之前先把模型通道理顺。Claude Code 这类工具在跑 Agent 循环时会频繁请求模型如果每个环节用不同 Key、不同 Base URL排障时你根本分不清是权限问题还是鉴权问题。我的做法是统一走 TaoToken 的 API 通道一个 Key 覆盖对话与编码场景Base URL 固定成https://taotoken.net/api这样 settings.json 和 config.toml 里只维护一处凭证。具体操作先到控制台创建 API Key地址是https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite创建后复制保存它只显示一次。如果你主要做长期编码或 Agent 任务可以看 Coding Plan 的额度说明https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite。想先验证模型是否通用模型对话页发一条消息即可https://taotoken.net/model-chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite。Key 管理入口在https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite接入文档在https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite。注意Key 不要写进会提交到 Git 的文件。用环境变量注入配置文件里只引用变量名。这一步做完你手里应该有一个可用的 Key 和一个固定的 Base URL。接下来所有配置都围绕这两个值展开。3. 可复制配置settings.json 与 config.toml 骨架Claude Code 在 Mac 上的配置分两层一层是工具自身的 settings.json描述权限、白名单、执行器行为另一层是模型通道的 config.toml描述 provider、base_url、model。下面给的是骨架路径和包名按你本地实际改。先看 settings.json。它放在项目根目录或用户配置目录下核心字段包括computerUse开关、allowedApps白名单、screenshot参数、lock锁文件路径。白名单很关键源码里截图方法会接收允许的应用列表不在列表里的应用会被排除避免模型看到无关窗口。{ computerUse: { enabled: true, allowedApps: [Safari, Finder, Terminal], screenshot: { quality: 70, maxWidth: 1440, displayId: 0, excludeTerminal: true }, lock: { path: /tmp/claude-computer-use.lock, timeoutMs: 30000 }, input: { moveDurationMs: 120, clickDelayMs: 80, typeDelayMs: 30 } } }几个参数说明quality控制截图压缩质量太高传输慢太低模型看不清小字70 是实测比较平衡的值maxWidth限制截图宽度Retina 屏原始分辨率很大缩到 1440 能明显降延迟excludeTerminal对应源码里的终端特殊处理避免终端窗口被截进去或被误点lock.path是文件锁保证同一时间只有一个会话操作电脑多开时会排队。再看 config.toml把模型通道指向 TaoToken。这里用环境变量引用 Key避免明文。[provider] name taotoken base_url https://taotoken.net/api api_key_env TAOTOKEN_API_KEY [model] name claude-sonnet max_tokens 4096 temperature 0.2 [agent] computer_use true settings_path ./settings.json然后在 shell 里导出 Keyexport TAOTOKEN_API_KEY你的Key如果你用的是 ClaudeCodeAnthropic 兼容入口可以参考https://taotoken.net/claude-code-anthropic?utm_sourcetaotoken_aicg_blog_endutm_contentclaude-code-anthropicutm_campaignrewrite里的说明对齐字段名。配置写完后先别急着跑控制流程先做一次纯文本请求验证通道。4. 验证请求先通模型再通控制链路验证分两步先确认模型通道通再确认 Computer Use 控制链路通。第一步用 curl 打一次对话请求确认 Key 和 Base URL 正确。curl -s https://taotoken.net/api/v1/messages \ -H Content-Type: application/json \ -H x-api-key: $TAOTOKEN_API_KEY \ -H anthropic-version: 2023-06-01 \ -d { model: claude-sonnet, max_tokens: 128, messages: [{role: user, content: 回复 ok 两个字母}] }返回里能看到content字段带ok说明通道没问题。如果返回 401检查 Key 是否带空格返回 404检查 base_url 是否多了斜杠。第二步验证控制链路。先确认系统权限打开“系统设置 → 隐私与安全性 → 辅助功能”把你的终端iTerm 或 Terminal加进去并勾选再到“屏幕录制”里同样加上终端。这两项缺一不可源码里的权限检查会同时验证它们缺哪个都会在会话初始化阶段失败。权限给完后跑一个最小控制动作让 Agent 打开 Safari 并截一张图。你可以用 CLI 触发也可以写个脚本调执行器。下面用脚本方式演示重点是观察日志里会话初始化、权限检查、截图返回三个阶段。TAOTOKEN_API_KEY$TAOTOKEN_API_KEY node ./run-computer-use.js \ --task 打开 Safari访问 example.com截图保存到 /tmp/shot.png \ --settings ./settings.json成功时你会看到类似输出session initialized、permissions ok: accessibilitytrue, screenRecordingtrue、screenshot saved: /tmp/shot.png, size1440x900。打开/tmp/shot.png应该能看到 Safari 窗口内容且终端窗口不在截图里这说明excludeTerminal生效了。如果截图是黑屏多半是屏幕录制权限没给终端如果点击没反应多半是辅助功能权限没生效重启终端再试。5. 本篇常见错排查Mac 上 Computer Use 跑不起来的几个坑第一个坑是权限给了但没重启进程。macOS 的辅助功能和屏幕录制权限在进程启动时读取你给终端授权后必须完全退出终端再打开否则旧进程仍然没有权限。源码里的权限检查会返回 false但错误提示可能只写“permission denied”不告诉你是哪一项。第二个坑是坐标偏移。源码用逻辑坐标再转物理坐标如果你外接了显示器且缩放不是默认值displayId选错会导致点击落到别的屏幕。排查方法把displayId设成 0 先只在主屏跑确认无误再改。另外maxWidth缩放后模型返回的坐标是基于缩放图的执行器会做反向换算如果你自己改了这个值又改了换算逻辑就容易偏。第三个坑是锁文件残留。上次会话异常退出/tmp/claude-computer-use.lock没释放下次启动会一直等锁超时。手动删掉锁文件即可或者把timeoutMs调小一点加快失败反馈。第四个坑是白名单太窄。allowedApps里没写目标应用截图时该应用被排除模型看不到内容就会反复尝试打开或点击空白区域。日志里会显示app not in allowlist把应用名加进去就行注意用应用显示名而不是进程名。第五个坑是 Key 注入失败。config.toml 里写的是api_key_env如果你在 IDE 里跑而不是在 shell 里跑环境变量可能没继承。排查方法在脚本里打印process.env.TAOTOKEN_API_KEY是否存在不存在就改用启动配置注入。接入文档里有环境变量注入的示例遇到鉴权类报错可以先对照https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite检查字段名。6. 把控制流程接进你的日常编码配置跑通后你可以把 Computer Use 接进日常流程让 Agent 在跑完测试后自动打开浏览器验证页面或者批量处理需要 GUI 的重复操作。长期做编码和 Agent 任务的话用 Coding Plan 的额度更省心入口在https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite。Key 和通道统一走 TaoToken 后settings.json 和 config.toml 只需要维护一处凭证排障时能快速区分是权限问题还是鉴权问题。最后留一个实用技巧把screenshot.quality和maxWidth做成环境变量覆盖调试时临时调低加快循环正式跑时再调高保证识别率。这样你不用改配置文件就能在两种模式间切换。