macOS 应用是 OpenClaw 的菜单栏配套应用。它拥有权限，在本地管理/附加到 Gateway 网关（launchd 或手动），并作为节点向智能体暴露 macOS 功能。 功能 在菜单栏中显示原生通知和状态。 拥有 TCC 提示（通知、辅助功能、屏幕录制、麦克风、语音识别、自动化/AppleScript）。 运行或连接到 Gateway 网关（本地或远程）。 暴露 macOS 专用工具（Canvas、相机、屏幕录制、system.run）。 在远程模式下启动本地节点主机服务（launchd），在本地模式下停止它。 可选地托管 PeekabooBridge 用于 UI 自动化。 根据请求通过 npm/pnpm 安装全局 CLI（openclaw）（不建议使用 bun 作为 Gateway 网关运行时）。 本地 vs 远程模式 本地（默认）：如果存在运行中的本地 Gateway 网关，应用附加到它；否则通过 openclaw gateway install 启用 launchd 服务。 远程：应用通过 SSH/Tailscale 连接到 Gateway 网关，从不启动本地进程。 应用启动本地节点主机服务，以便远程 Gateway 网关可以访问此 Mac。 应用不会将 Gateway 网关作为子进程生成。 Launchd 控制 应用管理一个标记为 bot.molt.gateway 的每用户 LaunchAgent（使用 --profile/OPENCLAW_PROFILE 时为 bot.molt.<profile>；旧版 com.openclaw.* 仍会卸载）。 launchctl kickstart -k gui/$UID/bot.molt.gateway launchctl bootout gui/$UID/bot.molt.gateway 运行命名配置文件时，将标签替换为 bot.molt.<profile>。 ...

本应用现已支持 Sparkle 自动更新。发布构建必须经过 Developer ID 签名、压缩，并发布包含签名的 appcast 条目。 前提条件 已安装 Developer ID Application 证书（示例：Developer ID Application: <Developer Name> (<TEAMID>)）。 环境变量 SPARKLE_PRIVATE_KEY_FILE 已设置为 Sparkle ed25519 私钥路径（公钥已嵌入 Info.plist）。如果缺失，请检查 ~/.profile。 用于 xcrun notarytool 的公证凭据（钥匙串配置文件或 API 密钥），以实现通过 Gatekeeper 安全分发的 DMG/zip。 我们使用名为 openclaw-notary 的钥匙串配置文件，由 shell 配置文件中的 App Store Connect API 密钥环境变量创建： APP_STORE_CONNECT_API_KEY_P8、APP_STORE_CONNECT_KEY_ID、APP_STORE_CONNECT_ISSUER_ID echo "$APP_STORE_CONNECT_API_KEY_P8" | sed 's/\\n/\n/g' > /tmp/openclaw-notary.p8 xcrun notarytool store-credentials "openclaw-notary" --key /tmp/openclaw-notary.p8 --key-id "$APP_STORE_CONNECT_KEY_ID" --issuer "$APP_STORE_CONNECT_ISSUER_ID" 已安装 pnpm 依赖（pnpm install --config.node-linker=hoisted）。 Sparkle 工具通过 SwiftPM 自动获取，位于 apps/macos/.build/artifacts/sparkle/Sparkle/bin/（sign_update、generate_appcast 等）。 构建与打包 注意事项： ...

当前模型： 一个本地 Unix 套接字将节点主机服务连接到 macOS 应用，用于 exec 审批 + system.run。存在一个 openclaw-mac 调试 CLI 用于发现/连接检查；智能体操作仍通过 Gateway 网关 WebSocket 和 node.invoke 流转。UI 自动化使用 PeekabooBridge。 目标 单个 GUI 应用实例拥有所有面向 TCC 的工作（通知、屏幕录制、麦克风、语音、AppleScript）。 小型自动化接口：Gateway 网关 + 节点命令，加上用于 UI 自动化的 PeekabooBridge。 可预测的权限：始终是同一个签名的 bundle ID，由 launchd 启动，因此 TCC 授权保持有效。 工作原理 Gateway 网关 + 节点传输 应用运行 Gateway 网关（本地模式）并作为节点连接到它。 智能体操作通过 node.invoke 执行（例如 system.run、system.notify、canvas.*）。 节点服务 + 应用 IPC 一个无头节点主机服务连接到 Gateway 网关 WebSocket。 system.run 请求通过本地 Unix 套接字转发到 macOS 应用。 应用在 UI 上下文中执行 exec，必要时提示，并返回输出。 图示（SCI）： ...

OpenClaw 的 Gateway 网关可以提供一个小型的 OpenAI 兼容 Chat Completions 端点。 此端点默认禁用。请先在配置中启用它。 POST /v1/chat/completions 与 Gateway 网关相同的端口（WS + HTTP 多路复用）：http://<gateway-host>:<port>/v1/chat/completions 底层实现中，请求作为普通的 Gateway 网关智能体运行执行（与 openclaw agent 相同的代码路径），因此路由/权限/配置与你的 Gateway 网关一致。 认证 使用 Gateway 网关认证配置。发送 bearer 令牌： Authorization: Bearer <token> 注意事项： 当 gateway.auth.mode="token" 时，使用 gateway.auth.token（或 OPENCLAW_GATEWAY_TOKEN）。 当 gateway.auth.mode="password" 时，使用 gateway.auth.password（或 OPENCLAW_GATEWAY_PASSWORD）。 选择智能体 无需自定义头：在 OpenAI model 字段中编码智能体 ID： model: "openclaw:<agentId>"（例如："openclaw:main"、"openclaw:beta"） model: "agent:<agentId>"（别名） 或通过头指定特定的 OpenClaw 智能体： x-openclaw-agent-id: <agentId>（默认：main） 高级选项： x-openclaw-session-key: <sessionKey> 完全控制会话路由。 启用端点 将 gateway.http.endpoints.chatCompletions.enabled 设置为 true： ...

OpenAI 提供 GPT 模型的开发者 API。Codex 支持ChatGPT 登录进行订阅访问，或API 密钥登录进行按量计费访问。Codex 云端需要 ChatGPT 登录。 方式 A：OpenAI API 密钥（OpenAI Platform） **适用于：**直接 API 访问和按量计费。 从 OpenAI 控制台获取你的 API 密钥。 CLI 设置 openclaw onboard --auth-choice openai-api-key # 或非交互式 openclaw onboard --openai-api-key "$OPENAI_API_KEY" 配置片段 { env: { OPENAI_API_KEY: "sk-..." }, agents: { defaults: { model: { primary: "openai/gpt-5.2" } } }, } 方式 B：OpenAI Code（Codex）订阅 **适用于：**使用 ChatGPT/Codex 订阅访问而非 API 密钥。 Codex 云端需要 ChatGPT 登录，而 Codex CLI 支持 ChatGPT 或 API 密钥登录。 ...

Ollama 是一个本地 LLM 运行时，可以轻松在你的机器上运行开源模型。OpenClaw 通过 Ollama 的 OpenAI 兼容 API 进行集成，并且当你通过 OLLAMA_API_KEY（或认证配置）启用且未定义显式的 models.providers.ollama 条目时，可以自动发现支持工具调用的模型。 快速开始 安装 Ollama：https://ollama.ai 拉取模型： ollama pull llama3.3 # 或 ollama pull qwen2.5-coder:32b # 或 ollama pull deepseek-r1:32b 为 OpenClaw 启用 Ollama（任意值即可；Ollama 不需要真实密钥）： # 设置环境变量 export OLLAMA_API_KEY="ollama-local" # 或在配置文件中设置 openclaw config set models.providers.ollama.apiKey "ollama-local" 使用 Ollama 模型： { agents: { defaults: { model: { primary: "ollama/llama3.3" }, }, }, } 模型发现（隐式提供商） 当你设置了 OLLAMA_API_KEY（或认证配置）且未定义 models.providers.ollama 时，OpenClaw 会从本地 Ollama 实例 http://127.0.0.1:11434 发现模型： ...

OpenClaw 支持通过 OAuth 进行"订阅认证"，适用于提供此功能的提供商（特别是 OpenAI Codex（ChatGPT OAuth））。对于 Anthropic 订阅，请使用 setup-token 流程。本页说明： OAuth 令牌交换的工作原理（PKCE） 令牌存储在哪里（以及原因） 如何处理多账户（配置文件 + 按会话覆盖） OpenClaw 还支持提供商插件，它们自带 OAuth 或 API 密钥流程。通过以下命令运行： openclaw models auth login --provider <id> 令牌汇聚点（为什么需要它） OAuth 提供商通常在登录/刷新流程中发放新的刷新令牌。某些提供商（或 OAuth 客户端）在为同一用户/应用发放新令牌时，可能会使旧的刷新令牌失效。 实际症状： 你通过 OpenClaw 和 Claude Code / Codex CLI 登录 → 其中一个稍后会随机"登出" 为减少这种情况，OpenClaw 将 auth-profiles.json 视为令牌汇聚点： 运行时从同一个位置读取凭据 我们可以保留多个配置文件并确定性地路由它们 存储（令牌存放位置） 密钥按智能体存储： 认证配置文件（OAuth + API 密钥）：~/.openclaw/agents/<agentId>/agent/auth-profiles.json 运行时缓存（自动管理；请勿编辑）：~/.openclaw/agents/<agentId>/agent/auth.json 仅用于导入的旧版文件（仍然支持，但不是主存储）： ~/.openclaw/credentials/oauth.json（首次使用时导入到 auth-profiles.json） 以上所有路径也遵循 $OPENCLAW_STATE_DIR（状态目录覆盖）。完整参考：/gateway/configuration Anthropic setup-token（订阅认证） 在任意机器上运行 claude setup-token，然后将其粘贴到 OpenClaw 中： ...

状态： 可选插件（默认禁用）。 Nostr 是一个去中心化的社交网络协议。此渠道使 OpenClaw 能够通过 NIP-04 接收和回复加密私信（DMs）。 安装（按需） 新手引导（推荐） 新手引导向导（openclaw onboard）和 openclaw channels add 会列出可选的渠道插件。 选择 Nostr 会提示你按需安装插件。 安装默认值： Dev 渠道 + git checkout 可用： 使用本地插件路径。 Stable/Beta： 从 npm 下载。 你可以随时在提示中覆盖选择。 手动安装 openclaw plugins install @openclaw/nostr 使用本地 checkout（开发工作流）： openclaw plugins install --link <path-to-openclaw>/extensions/nostr 安装或启用插件后重启 Gateway 网关。 快速设置 生成 Nostr 密钥对（如需要）： # 使用 nak nak key generate 添加到配置： { "channels": { "nostr": { "privateKey": "${NOSTR_PRIVATE_KEY}" } } } 导出密钥： export NOSTR_PRIVATE_KEY="nsec1..." 重启 Gateway 网关。 配置参考 键 类型 默认值 描述 privateKey string 必填 nsec 或十六进制格式的私钥 relays string[] ['wss://relay.damus.io', 'wss://nos.lol'] 中继 URL（WebSocket） dmPolicy string pairing 私信访问策略 allowFrom string[] [] 允许的发送者公钥 enabled boolean true 启用/禁用渠道 name string - 显示名称 profile object - NIP-01 个人资料元数据 个人资料元数据 个人资料数据作为 NIP-01 kind:0 事件发布。你可以从控制界面（Channels -> Nostr -> Profile）管理它，或直接在配置中设置。 ...

该页面是英文文档的中文占位版本，完整内容请先参考英文版：Node.js。

概述 通过 Node 使用 tsx 运行 OpenClaw 时，启动阶段报错： [openclaw] Failed to start CLI: TypeError: __name is not a function at createSubsystemLogger (.../src/logging/subsystem.ts:203:25) at .../src/agents/auth-profiles/constants.ts:25:20 此问题在开发脚本从 Bun 切换到 tsx 后出现（提交 2871657e，2026-01-06）。相同的运行路径在 Bun 下正常工作。 环境 Node: v25.x（在 v25.3.0 上观察到） tsx: 4.21.0 操作系统: macOS（其他运行 Node 25 的平台也可能复现） 复现步骤（仅 Node） # 在仓库根目录 node --version pnpm install node --import tsx src/entry.ts status 仓库内最小复现 node --import tsx scripts/repro/tsx-name-repro.ts Node 版本检查 Node 25.3.0：失败 Node 22.22.0（Homebrew node@22）：失败 Node 24：尚未安装，需要验证 说明 / 假设 tsx 使用 esbuild 转换 TS/ESM。esbuild 的 keepNames 会生成一个 __name 辅助函数，并用 __name(...) 包裹函数定义。 崩溃表明 __name 存在但在运行时不是函数，这意味着在 Node 25 的加载器路径中该辅助函数缺失或被覆盖。 其他 esbuild 使用者也报告过类似的 __name 辅助函数缺失或被重写的问题。 回归历史 2871657e（2026-01-06）：脚本从 Bun 改为 tsx，使 Bun 成为可选项。 在此之前（Bun 路径），openclaw status 和 gateway:watch 均正常工作。 解决方法 开发脚本使用 Bun（当前临时回退方案）。 使用 Node + tsc watch，然后运行编译产物： pnpm exec tsc --watch --preserveWatchOutput node --watch openclaw.mjs status 已在本地确认：pnpm exec tsc -p tsconfig.json + node openclaw.mjs status 在 Node 25 上可正常运行。 如果可能，在 TS 加载器中禁用 esbuild 的 keepNames（防止插入 __name 辅助函数）；tsx 目前不提供此配置项。 在 Node LTS（22/24）上测试 tsx，确认该问题是否为 Node 25 特有。 参考资料 https://opennext.js.org/cloudflare/howtos/keep_names https://esbuild.github.io/api/#keep-names https://github.com/evanw/esbuild/issues/1031 后续步骤 在 Node 22/24 上复现，确认是否为 Node 25 回归问题。 测试 tsx nightly 版本，或在存在已知回归时固定到早期版本。 如果在 Node LTS 上也能复现，则向上游提交包含 __name 堆栈跟踪的最小复现。