OpenClaw macOS 网关接入指南:外部 launchd 服务托管与本地模式排查

发布时间:2026/10/14 20:32:19

OpenClaw macOS 网关接入指南:外部 launchd 服务托管与本地模式排查 人工智能AI Agent即时通讯后端本地部署语音【免费下载链接】openclaw-cn中文社区版OpenClaw同原版保持定期更新已内置钉钉、企业微信、飞书、QQ、微信以及国内网络环境优化。你的专属个人AI助手。支持所有操作系统和平台。项目地址https://gitcode.com/gh_mirrors/op/openclaw-cn点击查看免费下载导读本文围绕 OpenClawopenclaw-cn 中文社区版在 macOS 上的网关托管方案展开macOS 桌面应用Clawdbot.app不再内嵌 Node/Bun 运行时与网关进程而是依赖一个独立的全局 CLI并通过launchd LaunchAgent以守护进程方式常驻运行本地网关。读完本文你将掌握在 Mac 上安装全局 CLI、理解 LaunchAgent 的安装/启用/停用机制、处理应用与网关的版本兼容校验以及用一条命令完成网关启动与健康探测的完整流程。原文档位置docs/platforms/mac/bundled-gateway.md。macOS 网关托管架构从内嵌到外部化原文档明确了 Clawdbot.app 的重大架构变化不再捆绑 Node/Bun 运行时也不再把 Gateway 作为应用子进程child process拉起macOS 应用期望一个外部安装的clawdbotCLI应用通过管理一个按用户per-user的 launchd 服务来保持网关常驻如果配置端口上已经有网关在运行应用会直接附加attach到现有实例而不是重复启动。这一设计可以从 macOS 应用源码中得到印证。在 GatewayProcessManager.swift 中启动流程被明确为先尝试附加、再启用 launchd两阶段// 1. 先尝试连接已经运行的网关避免重复拉起 if await self.attachExistingGatewayIfAvailable() { return } // 2. 没有可用的现有实例才启用 launchd 托管 await self.enableLaunchdGateway()在远程模式Remote mode下应用甚至完全跳过本地网关的拉起逻辑——setActive会直接置为停止并记录日志remote mode active; skipping local gateway见 GatewayProcessManager.swift。也就是说本篇文章讨论的 launchd 托管方案只适用于本地模式Local mode。说明本仓库openclaw-cn的 npm 包名与命令名与原版略有差异——package.json 中定义了clawdbot-cn、openclaw、openclaw-cn三个 bin 别名。安装指南见仓库根目录的 README.md。安装全局 CLI本地模式的前提环境要求与安装命令macOS 本地模式必须先在 Mac 上装好 Node.js 22随后全局安装clawdbotCLInpm install -g clawdbotversion在本仓库的实际安装命令为npm install -g openclaw-cnlatest # 或 pnpm add -g openclaw-cnlatest版本号version应替换为与 macOS 应用版本匹配的具体版本详见下文版本兼容校验一节。应用内的 Install CLI 流程macOS 应用内置了Install CLI按钮触发相同的安装流程。从 CLIInstallPrompter.swift 可以看到应用会弹出提示框Local mode needs the CLI so launchd can run the gateway提供Install CLI/Not now/Open Settings三个选项。安装器在 GatewayEnvironment.swift 中按 npm → pnpm → bun 的顺序解析包管理器实际执行npm install -g clawdbottarget或对应 pnpm/bun 等价命令。需要注意原文档的明确提示bun 不推荐用于 Gateway 运行时。从源码侧看守护进程运行时的合法值是node与bun但默认值固定为node且在 daemon-runtime.ts 的选项说明中标注了 Bun 的隐患Bun can corrupt memory on reconnectWhatsApp Telegram 渠道必需 Node。因此在 Mac 上请优先使用 npm/pnpm 安装并保持 Node 22 环境。Launchd把 Gateway 托管为 LaunchAgentLabel 与 plist 位置原文档给出了两条关键路径信息Labelcom.openclaw.gateway或配置了 profile 时为com.openclaw.profileplist 路径按用户~/Library/LaunchAgents/com.openclaw.gateway.plist或com.openclaw.profile.plist在本仓库实现中默认 Label 定义在 src/daemon/constants.ts 为com.clawdbot.gatewayprofile 化逻辑见 resolveGatewayLaunchAgentLabel未指定 profile或 profile 为 default时使用默认 Label否则生成com.clawdbot.profile。macOS 应用侧也保持了同一约定Constants.swift 中的gatewayLaunchdLabel com.clawdbot.gateway与 GatewayLaunchAgentManager.swift 中拼装的 plist URL~/Library/LaunchAgents/label.plist完全对应。原文档中的com.openclaw.*是上游命名以你实际安装版本生成的 Label 为准。plist 关键字段CLI 安装守护进程时plist 由 src/daemon/launchd-plist.ts 生成核心字段包括RunAtLoad true用户登录加载时即启动网关KeepAlive true进程退出后由 launchd 自动拉起这正是App 退出后网关仍在运行的机制来源ProgramArgumentsnode路径 dist入口 gateway --port portresolveGatewayProgramArguments 负责拼装Node 运行时下固定带--portStandardOutPath/StandardErrorPathlaunchd 的标准输出/错误重定向文件EnvironmentVariables注入网关运行所需的环境变量。CLI 侧同样有一份守护进程审计逻辑校验 plist 是否包含RunAtLoadtrue与KeepAlivetrue见 src/daemon/service-audit.ts侧面印证这两个字段对该托管方案至关重要。环境变量注入buildServiceEnvironment 展示了 launchd 服务注入的关键环境变量包括变量含义HOME用户主目录PATH最小化 PATH含/opt/homebrew/bin、/usr/local/bin等OPENCLAW_PROFILE当前 profileOPENCLAW_GATEWAY_PORT网关端口OPENCLAW_GATEWAY_TOKEN网关令牌token 认证模式OPENCLAW_LAUNCHD_LABEL当前 LaunchAgent LabelOPENCLAW_SERVICE_MARKER/OPENCLAW_SERVICE_KIND服务标识与类型openclaw/gatewayOPENCLAW_SERVICE_VERSION服务版本其中 token 的写入逻辑值得注意CLI 在自动生成令牌后会尽量持久化到配置文件因为launchd 不会继承 shell 环境变量并同时嵌入 plist 的EnvironmentVariables作为兜底见 src/cli/daemon-cli/install.ts。管理方式与行为细节原文档对管理权责与行为做了明确说明Manager本地模式下macOS 应用拥有 LaunchAgent 的安装/更新权限CLI 也可通过clawdbot gateway install安装。Clawdbot Active 开关负责启用/禁用 LaunchAgent。在 GatewayLaunchAgentManager.swift 中可以看到启用时执行install --force --port port --runtime node停用时执行uninstall且远程模式下跳过一切 launchd 变更。退出不停止应用退出不会停止网关launchd 的KeepAlivetrue保证常驻。应用侧 stop() 只负责在用户主动关闭时执行卸载并不会在普通退出时干扰 launchd 托管的实例。附加优先若配置端口上已有网关应用直接附加attach而非新建。附加流程在 attachExistingGatewayIfAvailable先探测端口上是否存在监听者再调用healthRPC超时 2 秒、最多重试 3 次成功后状态显示为 Using existing gateway若端口被占用但健康探测失败则会给出针对性的失败原因认证失败、协议不匹配、端口被其他进程占用等。CLI 侧的守护进程管理命令install/uninstall/start/stop/restart/status注册在 src/cli/gateway-cli/register.tsinstall支持--port、--runtime node|bun、--token、--force、--json等选项macOS 上平台适配经由 resolveGatewayService 映射到 LaunchAgent 实现。版本兼容校验macOS 应用会拿网关版本与自身版本做比对版本不兼容时提示更新全局 CLI使其与应用版本一致。源码实现位于 GatewayEnvironment.swift应用期望版本来自CFBundleShortVersionStringexpectedGatewayVersionString实际安装版本通过运行clawdbot --version读取readGatewayVersion本地项目入口存在时也可回退读取package.json的 version 字段兼容规则为主版本号一致且不低于应用版本self.major required.major self required一旦判定不兼容check() 会返回incompatible(found:required:)状态提示 install or update the global package。因此当你看到应用提示网关版本不兼容时直接按上文安装全局 CLI一节把全局包更新到与应用相同的版本即可。冒烟检查启动网关并验证健康状态原文档给出了完整的两段式冒烟检查命令可直接照用clawdbot --version OPENCLAW_SKIP_CHANNELS1 \ OPENCLAW_SKIP_CANVAS_HOST1 \ clawdbot gateway --port 18999 --bind loopback随后验证健康状态clawdbot gateway call health --url ws://127.0.0.1:18999 --timeout 3000环境变量与参数的含义OPENCLAW_SKIP_CHANNELS1跳过渠道channels启动。源码中网关启动时会检查该变量并跳过渠道初始化见 src/gateway/server-startup.ts适合只想验证网关本体、不接入任何消息渠道的冒烟场景。OPENCLAW_SKIP_CANVAS_HOST1跳过 Canvas Host。实现于 src/canvas-host/server.ts与上一条同理用于最小化启动面。--port 18999指定临时端口避免与默认端口冲突。默认端口在本仓库中为18789应用侧 fallback 见 GatewayEnvironment.swift。端口取值也可来自CLAWDBOT_GATEWAY_PORT环境变量或配置中的gateway.port。--bind loopback仅绑定回环地址不对外暴露。合法值为loopback/lan/tailnet/auto/custom校验见 src/cli/gateway-cli/run.ts。health 调用的底层实现clawdbot gateway call health最终通过 WebSocket 调用网关的health方法。call.ts 定义了--url、--token、--password、--timeout ms、--expect-final、--json等选项默认超时 10 秒冒烟命令显式指定 3000ms 以快速失败。子命令注册见 src/cli/gateway-cli/register.ts成功后输出Gateway Health: OK及耗时信息。日志与故障排查日志位置launchd 的 stdout/stderr 统一重定向到/tmp/clawdbot/clawdbot-gateway.log。macOS 应用侧 LogLocator.swift 也返回同一路径launchdGatewayLogPath应用内的Gateway Log面板读取的正是这个文件。若想覆盖日志目录可设置环境变量CLAWDBOT_LOG_DIR见 LogLocator.swift。注意 launchd 托管模式下环境来自 plist 注入改动环境变量后需重新gateway install --force才会生效。常见问题定位思路应用提示 CLI 未安装 / Local mode needs the CLI检查node --version是否 ≥ 22然后通过应用内Install CLI或手动npm install -g openclaw-cnlatest完成安装。提示版本不兼容按版本兼容校验一节更新全局 CLI 至与应用一致的版本。端口被占用但附加失败健康探测失败原因会明确区分认证失败auth协议不匹配protocol mismatch端口被其他进程占用invalid response三类按提示核对gateway.auth.token或改用--force清理端口占用。不想让应用自动写 LaunchAgent应用支持在用户主目录放置标记文件~/.clawdbot/disable-launchagent以禁用自动安装/启用见 GatewayLaunchAgentManager.swift此时需手动用clawdbot gateway install管理服务。小结macOS 上的 OpenClaw 网关托管遵循外部 CLI launchd LaunchAgent的清晰分工CLI 提供运行时与安装能力launchd 保证常驻与崩溃恢复应用只负责按需安装、启停和附加已有实例。理解 Label、plist 字段、环境变量注入与版本兼容规则之后无论是日常使用还是排查本地模式故障都能快速定位问题所在。相关参考docs/platforms/mac/bundled-gateway.mdsrc/daemon/launchd-plist.tssrc/daemon/service-env.tsapps/macos/Sources/Clawdbot/GatewayLaunchAgentManager.swiftapps/macos/Sources/Clawdbot/GatewayProcessManager.swiftapps/macos/Sources/Clawdbot/GatewayEnvironment.swift赞分享人工智能AI Agent即时通讯后端本地部署语音【免费下载链接】openclaw-cn中文社区版OpenClaw同原版保持定期更新已内置钉钉、企业微信、飞书、QQ、微信以及国内网络环境优化。你的专属个人AI助手。支持所有操作系统和平台。项目地址https://gitcode.com/gh_mirrors/op/openclaw-cn点击查看免费下载相关推荐openclaw-cn 网关服务操作手册本地运行、远程访问与 launchd/systemd 监管实战指南openclaw cn 网关服务操作手册本地运行、远程访问与 launchd/systemd 监管实战指南 网关Gateway是 openclaw cn人工智能AI Agent即时通讯后端本地部署语音OpenClaw 自托管 AI 网关完整实战指南安装、模型接入、多通道配置与故障排查OpenClaw 自托管 AI 网关完整实战指南安装、模型接入、多通道配置与故障排查 导读 本文围绕 OpenClaw —— 一个 MIT 许可、可自托管的人工智能MCP 服务AI Agent开发工具OpenClaw openclaw uninstall 完全指南安全卸载网关服务与本地数据OpenClaw openclaw uninstall 完全指南安全卸载网关服务与本地数据 openclaw uninstall 是 OpenClaw CLI人工智能大模型LLM 网关AI Agent即时通讯上一篇Product-Manager-Skills 用户故事拆分实战指南基于 8 种拆分模式的 user-story-splitting 技能全解析下一篇Images-to-PDF图片转PDF工具完全指南创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
延伸阅读

更多相关文章

2026/10/14 20:32:19

新能源无人化场站:智能化、自动化控制与AI数据分析落地指南

简介:这份《新能源“无人化”场站解决方案白皮书》由金风服务GOLDWIND推出,面向新能源场站运维、智能化改造及能源数字化领域的技术与管理人员,聚焦场站智能化、无人化操作与自动化控制等核心议题。白皮书围绕智能化场站、无人化操作、自动化…

2026/10/14 20:32:19

artcraft:轻量级浏览器创意工具从架构到性能优化实战

1. 项目缘起与整体设计思路1.1 为什么会有 artcraft 这个想法做创意工具这些年,我越来越强烈地感受到一个矛盾:市面上要么是功能极其强大的专业软件,学习曲线陡峭到让人望而却步;要么是轻量级的小工具,用起来简单但稍微…

2026/10/14 23:36:07

Redis从安装到实战:配置、数据结构与缓存问题排查全攻略

先问自己一个问题:有没有遇到过这样的场景——线上接口突然变慢,数据库CPU飙高,用户反馈页面打不开,重启服务后过几分钟又被打爆;或者明明是同一个数据,每次请求都要去数据库查一遍,白白浪费了连…

2026/10/14 23:36:07

告别收藏即掌握:用认知模式重塑知识过程

做知识管理的人,大多经历过一个错觉:把文章存进收藏夹,心里就踏实了;把书里划的线填满页面,就觉得知识已经属于自己;把AI生成的摘要复制进个人笔记,就以为自己完成了学习。这些情况从来不是工具…

2026/10/14 23:36:07

深度学习光流估计实战:从原理到训练调参的完整指南

光流估计是我接触深度学习之后,觉得非常“拧巴”的一个任务。输入是两帧相邻图像,输出的是一个和原图同样大小的二维矢量场,每个像素点告诉你“往哪去了、动了多少”。听起来很直观?等你真的上手调一次模型就会明白,遮…

2026/10/14 23:36:07

前端页面嵌入百度地图:从API接入到白屏排查完整实践

前端页面嵌入百度地图的小demo,这个需求看起来不起眼,但实际做起来,坑比想象中多得多。我最早接触这个需求的时候,以为就是引个脚本、new一个对象、放个容器就完事。结果从申请密钥到地图真正在页面上渲染出来,折腾了小…

2026/10/14 23:36:07

认知模式决定知识管理效率:三种知识处理路径与实操指南

当初我在搭建个人知识库的时候,第一件让我困惑的事情不是工具,而是“为什么信息越来越多,自己却越来越空”。看了很多书,收藏了不少帖子,也做过不少思维导图,可真遇到问题的时候,脑子里的知识点…

2026/10/14 23:31:06

IPO审核两大雷区:应收账款高企与控制权分散的排雷指南

聊一个最近被反复讨论的IPO案例:一家拟上市制造企业,应收账款余额一路飙到11.22亿元,同时公司股权结构高度分散,几个大股东持股比例拉不开差距,谁都没有绝对话语权。这两个问题单独拎出来,都是IPO审核里的高…

2026/10/14 11:31:03

Python调用Gemini Structured Outputs实现工单路由门禁

客服工单最怕的不是模型“答错一句话”,而是它给出一段看起来合理的说明,程序却从中猜错优先级。通俗做法是:要求模型只交 JSON(JavaScript Object Notation,轻量数据格式),再让代码验证它。Gem…

2026/10/14 17:41:07

Spring Boot超市进销存系统毕设实战:从需求拆解到答辩通关

最近带的一个学生项目组里,有A同学跑来问我:选什么毕设题目最稳妥,既能让评审老师觉得工作量够,又不会在答辩时被问到语无伦次。我第一反应就是推荐基于Spring Boot的超市仓库管理系统——也就是超市进销存系统。这个题目乍一看平…

2026/10/14 2:32:55

Flutter StatefulWidget 生命周期核心解析

很多刚开始接触 Flutter 的朋友,在看完一堆“Hello World”和基础组件之后,大概率都会撞上同一堵墙:StatefulWidget 里那堆 initState、build、dispose 方法,到底什么时候被调用?为什么顺序是那样?在里面到…

2026/10/14 0:00:33

DFS算法解决飞机降落调度问题实战

1. 项目背景与核心思路飞机降落问题是一个经典的调度优化场景,也是算法竞赛和面试中的高频题目。这个题目要求我们合理安排多架飞机的降落顺序和时间,确保所有飞机都能安全着陆而不发生冲突。在实际航空管制中,这类问题直接关系到飞行安全和机…

2026/10/14 0:00:33

macOS/iOS高精度计时:mach_absolute_time原理与实战

1. 项目概述:为什么mach_absolute_time是 macOS/iOS 时间测量的“黄金标准”在 macOS 和 iOS 开发中,我见过太多人用CFAbsoluteTimeGetCurrent()或NSDate.timeIntervalSinceReferenceDate做性能打点,结果在高精度场景下被系统时钟跳变、NTP 同…

2026/10/14 0:00:33

SCORM课件演示与测试全解析:从API通信到自动化验证

简介:这是一套遵循SCORM标准的交互式课件演示与测试资源,面向E-Learning课程开发者、LMS平台测试人员及在线教学从业者,用于验证课件在不同学习管理系统中的识别、传递与跟踪能力。压缩包共28个文件,约12.07MB,以swf动…

还想了解更多?直接咨询顾问

免费诊断 + 免费方案 + 透明报价。

全国咨询热线400-8866-253
免费获取方案
☎咨询二维码 ☎ ↑