1. OpenClaw 在 Windows11/macOS 被安全拦截的真实场景OpenClaw 是一类本地 AI Agent 运行时它和普通桌面软件最大的区别在于它需要模拟键鼠、读写本地文件、拉起浏览器进程、监听本地端口。这些行为在操作系统眼里和恶意程序的动作高度重合所以 Windows11 的 Defender、SmartScreen以及 macOS 的 Gatekeeper、XProtect 都会主动拦截。你要做的不是把防护全关掉而是在保留系统防护的前提下给 OpenClaw 划出一条合法通道。我先把问题拆清楚。Windows11 上常见的拦截有三层第一层是 SmartScreen 的「Windows 已保护你的电脑」弹窗针对无签名或低信誉的可执行文件第二层是 Defender 实时防护对进程行为的拦截比如批量文件操作、注册表写入、计划任务创建第三层是防火墙对本地监听端口的入站拦截表现为 Gateway 一直离线。macOS 上则是 Gatekeeper 的「无法验证开发者」、隐私与安全性里的辅助功能/完全磁盘访问权限未授权以及 XProtect 对脚本行为的静默阻断。这三层拦截的应对方式完全不同。SmartScreen 是启动前的信誉判断你点「更多信息 → 仍要运行」就能过但它不解决后续行为拦截。Defender 实时防护是运行时的行为判断需要靠排除项而不是关闭防护。防火墙是网络层需要放行具体端口而不是整体关闭。macOS 的 Gatekeeper 靠xattr和spctl处理权限则必须在系统设置里逐项授权。很多人一遇到拦截就去关 Defender、关防火墙结果 Agent 是跑起来了但系统裸奔而且下次开机防护自动恢复后又失效。正确思路是把 OpenClaw 的安装目录、可执行文件、工作目录加入排除项把监听端口加入防火墙入站规则把辅助功能权限授予具体进程。这样防护还在Agent 也能稳定运行。还有一个容易被忽略的点OpenClaw 的模型侧接入。本地 Agent 只负责执行动作真正做决策的是背后的模型。如果你用本地小模型能力有限如果接云端模型又涉及 Key 管理和通道稳定性。这篇会把模型侧统一走 TaoToken 的 Key/API 通道这样 Windows 和 macOS 两端用同一套配置换机器不用重新折腾。下面按「先解决系统拦截再接入模型最后验证和排障」的顺序展开。每一步都给可复制的命令和配置你照着做就行。2. TaoToken 统一 Key/API 通道前置准备在动手配系统权限之前先把模型侧的通道准备好因为 OpenClaw 启动时会去读模型配置如果 Key 没配好你会误以为是系统拦截导致启动失败排查方向就错了。TaoToken 在这里扮演的角色是统一入口你不需要在 Windows 和 macOS 上分别维护不同的模型供应商配置也不需要为每个 Agent 单独申请 Key。一个 Key 走同一个 Base URL两端配置完全一致。对本地 Agent 来说它只认 OpenAI 兼容格式的接口TaoToken 提供的正是这个格式所以 OpenClaw 的模型配置里只要填三样东西Base URL、API Key、Model ID。先说清楚这三件套在 OpenClaw 里分别填什么。Base URL 填https://taotoken.net/api注意这里不加任何查询参数就是纯 API 根路径。API Key 在控制台的 API Keys 页面创建创建后复制一次页面刷新就不再显示完整 Key所以要当场存好。Model ID 填你实际要用的模型标识比如做代码类 Agent 就选对应的编码模型做通用对话就选通用模型具体可选列表在模型对话页面能看到。创建 Key 的入口在这里https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 。进去之后点创建命名建议带上用途和机器比如openclaw-win11、openclaw-mac这样后面排查哪个 Key 出问题一目了然。这里有个实操细节OpenClaw 的配置文件在不同版本里位置不一样有的在安装目录下的config文件夹有的在用户目录的.openclaw下。你要先确认自己版本的配置路径再往里写。Windows 上通常是%USERPROFILE%\.openclaw\config.jsonmacOS 上是~/.openclaw/config.json。如果找不到就在 OpenClaw 主界面里找「设置 → 模型配置」它会显示当前读取的配置文件路径。配置内容用 JSON 格式结构如下两端通用{ model: { provider: openai-compatible, base_url: https://taotoken.net/api, api_key: sk-你的Key, model_id: 你的模型ID, timeout: 60, max_retries: 3 }, gateway: { host: 127.0.0.1, port: 18789 } }注意gateway.port这个值后面配防火墙入站规则要用到默认是 18789如果你改了要同步改防火墙规则。timeout设 60 秒是因为 Agent 有时要处理长任务设太短会频繁超时。max_retries设 3 是防止偶发网络抖动直接失败。配好之后先别急着启动 OpenClaw用一条 curl 命令验证通道是否通。Windows11 的 PowerShell 和 macOS 的终端都自带 curlcurl -X POST https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer sk-你的Key \ -H Content-Type: application/json \ -d { model: 你的模型ID, messages: [{role: user, content: ping}], max_tokens: 10 }如果返回里有choices字段和内容说明 Key、Base URL、Model ID 三件套都对。如果返回 401是 Key 问题如果返回 404多半是 Base URL 或 Model ID 写错如果连接超时是网络层问题和系统拦截无关。这一步过了再进入系统权限配置排查链路就清晰了。3. Windows11 与 macOS 可复制的权限声明与白名单配置这一节是核心直接给可复制的配置。先讲 Windows11再讲 macOS两端都按「排除项 防火墙 权限」三层来配。Windows11 的 Defender 排除项推荐用 PowerShell 命令行加比在图形界面点更可靠也不容易漏。以管理员身份打开 PowerShell执行# 添加安装目录排除项 Add-MpPreference -ExclusionPath D:\OpenClaw Add-MpPreference -ExclusionPath $env:USERPROFILE\.openclaw # 添加进程排除项 Add-MpPreference -ExclusionProcess Openclaw Windows一键启动.exe Add-MpPreference -ExclusionProcess openclaw-gateway.exe # 添加扩展名排除项针对 Agent 生成的脚本文件 Add-MpPreference -ExclusionExtension .ps1 Add-MpPreference -ExclusionExtension .py执行完可以用Get-MpPreference | Select-Object ExclusionPath, ExclusionProcess确认是否写入成功。这里的关键是排除的是具体路径和进程不是关闭实时防护。实时防护仍然开着只是对这几个对象不扫描。防火墙入站规则放行 Gateway 监听端口New-NetFirewallRule -DisplayName OpenClaw Gateway -Direction Inbound -Protocol TCP -LocalPort 18789 -Action Allow -Profile Private注意-Profile Private只对专用网络生效不要用Any否则在公共网络下也开放端口不安全。如果你在家庭网络或公司内网Private 就够了。SmartScreen 的拦截没法用命令永久绕过因为它是基于文件信誉的。正确做法是首次运行时点「更多信息 → 仍要运行」之后系统会记住这个文件的信誉。如果你要批量部署可以用Unblock-File去掉文件的「来自互联网」标记Unblock-File -Path D:\OpenClaw\Openclaw Windows一键启动.exe这个命令去掉的是 NTFS 的 Zone.Identifier 备用数据流SmartScreen 看到没有这个标记就不会再弹「已保护你的电脑」。这比关 SmartScreen 安全得多。macOS 这边Gatekeeper 的处理用两条命令# 去掉隔离属性 xattr -dr com.apple.quarantine /Applications/OpenClaw.app # 如果还有拦截用 spctl 评估并放行 spctl --add --label OpenClaw /Applications/OpenClaw.app spctl --enable --label OpenClawxattr -dr是递归去掉隔离属性这是 Gatekeeper 判断「从网上下载」的依据。去掉之后双击就不会再提示「无法验证开发者」。辅助功能和完全磁盘访问权限必须在系统设置里手动授权命令行改不了这是 macOS 的安全设计。路径是系统设置 → 隐私与安全性 → 辅助功能点「」添加 OpenClaw 主程序再到「完全磁盘访问」里同样添加。授权后需要重启 OpenClaw 进程才生效。如果你用的是 Claude Code 类的 Agent 配置或者通过 CC Switch、Cline MCP 来管理多个 Agent配置结构会多一层。以 CC Switch 为例它的配置文件里每个 provider 要写全三件套[[providers]] name taotoken base_url https://taotoken.net/api api_key sk-你的Key model 你的模型IDCline MCP 的配置在cline_mcp_settings.json里结构类似{ mcpServers: { openclaw: { command: openclaw-gateway, args: [--port, 18789], env: { OPENAI_BASE_URL: https://taotoken.net/api, OPENAI_API_KEY: sk-你的Key, OPENAI_MODEL: 你的模型ID } } } }Codex 的auth.json则是另一种结构放在~/.codex/auth.json{ OPENAI_API_KEY: sk-你的Key, OPENAI_BASE_URL: https://taotoken.net/api }不管用哪种 Agent 框架核心都是 Base URL Key Model ID 三件套缺一个都会报错。配置文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里面有各框架的完整示例。4. 启动验证与拦截日志排查配置写完启动 OpenClaw然后按下面几步验证。不要只看界面显示「Gateway 在线」就完事要从日志层面确认没有拦截。Windows11 上先看 Defender 的拦截历史。打开 PowerShellGet-MpThreatDetection | Where-Object {$_.Resources -like *OpenClaw*} | Select-Object -Last 10如果这条命令返回空说明 Defender 没有拦截 OpenClaw 相关文件。如果有返回看Resources字段是哪个文件被拦了把它的路径补进排除项。再看防火墙日志确认端口放行生效Get-NetFirewallRule -DisplayName OpenClaw Gateway | Select-Object Enabled, Direction, ActionEnabled应该是TrueAction是Allow。如果Enabled是False说明规则没生效重新执行上一节的New-NetFirewallRule。macOS 上看 Gatekeeper 和 XProtect 的日志# 查看最近的 Gatekeeper 拦截 log show --predicate subsystem com.apple.securityd --last 10m | grep -i openclaw # 查看 XProtect 行为 log show --predicate process XProtect --last 10m如果日志里有denied或blocked字样对照时间点看是哪个操作被拦。macOS 的拦截日志比 Windows 详细通常会写明是权限问题还是签名问题。然后做一次端到端验证在 OpenClaw 里下发一个简单指令比如「列出当前目录文件」看它能不能正常调用模型并执行。同时观察 Gateway 日志里有没有choices字段返回。如果模型返回正常但动作执行失败是系统权限问题如果模型返回就失败是 Key 或通道问题。验证模型通道是否正常可以直接在模型对话页面发一条测试消息https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentchatutm_campaignrewrite 。如果那边正常说明 Key 和通道没问题问题在本地 Agent 配置。回滚动作也要提前准备好。如果配置导致系统异常按这个顺序回滚先删防火墙规则Remove-NetFirewallRule -DisplayName OpenClaw Gateway再删 Defender 排除项Remove-MpPreference -ExclusionPath D:\OpenClawmacOS 上恢复隔离属性xattr -w com.apple.quarantine 0081 /Applications/OpenClaw.app。回滚后系统防护完全恢复原状不会留残留。5. 常见报错对照排查这一节按真实报错来对照你遇到哪个查哪个。401 UnauthorizedKey 无效或过期。先确认 Key 复制完整没有多余空格。如果 Key 是在别的机器上创建的确认没有在其他地方被删除。重新在 API Keys 页面创建一个新 Key 测试https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 。注意 Key 只在创建时显示一次如果当时没存只能重建。local proxy failed / connection refused本地代理连接失败。这个报错通常不是 TaoToken 的问题而是 OpenClaw 的 Gateway 没起来或者端口被占用。先确认gateway.port配置的端口没有被其他程序占用Windows 上用netstat -ano | findstr 18789查macOS 上用lsof -i :18789。如果被占用改配置里的端口同时改防火墙规则。reading choices 报错 / choices 字段为空模型返回格式不对。检查 Base URL 是不是写成了https://taotoken.net/api/v1正确写法是https://taotoken.net/api路径里的/v1由 OpenClaw 自己拼。如果 Base URL 多写了/v1会变成/v1/v1/chat/completions返回 404 或空 choices。另外确认 Model ID 拼写正确大小写敏感。OAuth 相关报错如果你用的是 Claude Code 类需要 OAuth 的 Agent报错说明认证流程没走完。这类 Agent 的配置参考 https://taotoken.net/claude-code-anthropic?utm_sourcetaotoken_aicg_blog_endutm_contentclaude_codeutm_campaignrewrite 里面有针对 Anthropic 兼容格式的完整配置。核心还是三件套但字段名可能不同比如ANTHROPIC_BASE_URL对应base_url。Gateway 持续离线分三种情况。一是防火墙拦截按上一节检查入站规则二是端口被占用换端口三是模型通道不通OpenClaw 启动时连不上模型会一直重试表现为离线。先单独用 curl 测通道通道通了再看 Gateway。权限不足 / 无法操控鼠标Windows 上右键以管理员身份运行macOS 上到系统设置 → 隐私与安全性 → 辅助功能里授权。注意 macOS 授权后要完全退出 OpenClaw 再重启不是关窗口是CmdQ退出。安装包被杀软删除说明排除项没加对。重新加排除项把安装目录和压缩包所在目录都加进去然后重新解压。不要关闭杀软加排除项就够了。首次启动加载慢正常现象Agent 首次运行要初始化组件、下载依赖、建立索引1 到 3 分钟都算正常。如果超过 5 分钟还没起来看日志里卡在哪一步。6. 长期运行与 Coding Plan 接入建议系统拦截解决之后OpenClaw 就能稳定跑了。但如果你要长期用尤其是做编码类 Agent 或者多 Agent 协作单次调用按量计费的成本会上去而且频繁的短请求容易触发限流。这时候可以考虑 Coding Plan它适合长期编码和 Agent 场景按周期计费不用担心每次调用的额度波动。Coding Plan 的入口在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 。接入方式和普通 Key 一样还是三件套只是 Key 的类型不同。配置里不用改结构把api_key换成 Coding Plan 对应的 Key 就行。长期运行还有几个实操建议。第一把 OpenClaw 的日志目录也加入 Defender 排除项因为 Agent 会频繁写日志实时扫描会拖慢速度。第二macOS 上如果 Agent 要访问外部磁盘记得在「完全磁盘访问」里把对应磁盘也授权。第三定期检查 Key 的使用情况在控制台能看到调用量如果发现异常增长及时排查是不是 Agent 陷入了循环调用。最后说一个我踩过的坑OpenClaw 升级版本后配置文件路径可能会变旧配置不生效表现为启动后模型调用失败。升级前先备份~/.openclaw/config.json升级后对比新版本的配置模板把三件套迁移过去。控制台在 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 里面能看到 Key 状态和调用记录排查时很有用。整套流程走下来核心就三件事系统层加排除项和放行端口而不是关防护模型层统一走 TaoToken 的三件套配置验证层用 curl 和日志确认每一层都通。Windows 和 macOS 的差异主要在权限授权方式配置结构是一致的。按这个顺序做Agent 能在保留系统防护的前提下稳定运行。