大家好，我是讯享网，很高兴认识大家。这里提供最前沿的Ai技术和互联网信息。



目标:尽快从零→第一个可用聊天(使用合理的默认设置)。

最快聊天:打开控制界面(无需配置渠道)。运行 并在浏览器中聊天,或在网关主机上打开 。 文档:仪表板 和 控制界面。

推荐路径:使用 CLI 新手引导向导()。它会设置:

• 模型/认证(推荐 OAuth)
• 网关设置
• 渠道(WhatsApp/Telegram/Discord/Mattermost(插件)/…)
• 配对默认设置(安全私信)
• 工作区引导 + Skills
• 可选的后台服务

如果您想查看更深入的参考页面,请跳转至:向导、设置、配对、安全。

沙箱注意事项: 使用 (默认 ), 因此群组/渠道会话是沙箱隔离的。如果您希望主智能体始终在主机上运行,请设置显式的每个智能体覆盖:

• Node
• (可选;如果从源代码构建则推荐)
• 推荐: Brave Search API 密钥用于网络搜索。最简单的方式: (存储为 )。 参见 Web 工具。

macOS:如果您计划构建应用程序,请安装 Xcode / CLT。对于仅 CLI + 网关,Node 就足够了。 Windows:使用 WSL2(推荐 Ubuntu)。强烈推荐 WSL2;原生 Windows 未经测试,问题更多,工具兼容性较差。首先安装 WSL2,然后在 WSL 中运行 Linux 步骤。参见 Windows (WSL2)。

安装程序选项(安装方法、非交互式、从 GitHub):安装。

Windows (PowerShell):

替代方案(全局安装):

您需要选择的内容:

• 本地 vs 远程网关
• 认证:OpenAI Code (Codex) 订阅(OAuth)或 API 密钥。对于 Anthropic,我们推荐使用 API 密钥;也支持 。
• 提供商:WhatsApp 二维码登录、Telegram/Discord 机器人令牌、Mattermost 插件令牌等。
• 守护进程:后台安装(launchd/systemd;WSL2 使用 systemd)
  • 运行时:Node(推荐;WhatsApp/Telegram 必需)。不推荐 Bun。
• Gateway 网关令牌:向导默认生成一个(即使在 local loopback 上)并存储在 。

向导文档:向导

• 推荐的 Anthropic 路径: 设置 API 密钥(向导可以存储它供服务使用)。如果您想重用 Claude Code 凭据,也支持 。
• OAuth 凭据(旧版导入):
• 认证配置文件(OAuth + API 密钥):

无头/服务器提示:首先在普通机器上执行 OAuth,然后将 复制到网关主机。

如果您在新手引导过程中安装了服务,Gateway 网关应该已经在运行:

手动运行(前台):

仪表板(local loopback): 如果配置了令牌,请将其粘贴到控制界面设置中(存储为 )。

⚠️ Bun 警告(WhatsApp + Telegram): Bun 在这些渠道上存在已知问题。如果您使用 WhatsApp 或 Telegram,请使用 Node 运行 Gateway 网关。

通过 WhatsApp → 设置 → 已关联的设备进行扫描。

WhatsApp 文档:WhatsApp

向导可以为您写入令牌/配置。如果您偏好手动配置,从以下开始:

• Telegram:Telegram
• Discord:Discord
• Mattermost(插件):Mattermost

Telegram 私信提示: 您的第一条私信会返回一个配对代码。批准它(参见下一步)否则机器人不会响应。

默认策略:未知私信会获得一个短代码,在批准之前消息不会被处理。 如果您的第一条私信没有得到回复,请批准配对:

配对文档:配对

如果您正在开发 OpenClaw 本身,请从源代码运行:

如果您还没有全局安装,请从仓库通过 运行新手引导步骤。 还打包了 A2UI 资源;如果您只需要运行该步骤,请使用 。

Gateway 网关(从此仓库):

在新终端中,发送一条测试消息:

如果 显示"未配置认证",请返回向导并设置 OAuth/密钥认证 — 没有它,智能体将无法响应。

提示: 是**的可粘贴只读调试报告。 健康探测:(或 )向运行中的网关请求健康快照。

• 加入虾聊社区交流:虾聊社区
• macOS 菜单栏应用 + 语音唤醒:macOS 应用
• iOS/Android 节点(Canvas/相机/语音):节点
• 远程访问(SSH 隧道 / Tailscale Serve):远程访问 和 Tailscale
• 永远在线 / VPN 设置:远程访问、exe.dev、Hetzner、macOS 远程

引导向导是在 macOS、Linux 或 Windows(通过 WSL2;强烈推荐)上设置 OpenClaw 的推荐方式。 它在一个引导式流程中配置本地 Gateway 网关或远程 Gateway 网关连接,以及渠道、技能和工作空间默认设置。

主要入口点:

最快的首次聊天:打开控制 UI(无需渠道设置)。运行 并在浏览器中聊天。文档:控制面板。

后续重新配置:

推荐:设置 Brave Search API 密钥,以便智能体可以使用 ( 无需密钥即可工作)。最简单的方法: 它会存储 。文档:Web 工具。

向导从快速启动(默认)vs 高级(完全控制)开始。

快速启动保持默认设置:

• 本地网关(local loopback)
• 工作空间默认值(或现有工作空间)
• Gateway 网关端口 18789
• Gateway 网关认证 Token(自动生成,即使在 local loopback 上)
• Tailscale 暴露关闭
• Telegram + WhatsApp 私信默认为允许列表(系统会提示您输入电话号码)

高级暴露每个步骤(模式、工作空间、网关、渠道、守护进程、技能)。

本地模式(默认)引导您完成:

• 模型/认证(OpenAI Code (Codex) 订阅 OAuth、Anthropic API 密钥(推荐)或 setup-token(粘贴),以及 MiniMax/GLM/Moonshot/AI Gateway 选项)
• 工作空间位置 + 引导文件
• Gateway 网关设置(端口/绑定/认证/tailscale)
• 提供商(Telegram、WhatsApp、Discord、Google Chat、Mattermost(插件)、Signal)
• 守护进程安装(LaunchAgent / systemd 用户单元)
• 健康检查
• 技能(推荐)

远程模式仅配置本地客户端以连接到其他地方的 Gateway 网关。 它不会在远程主机上安装或更改任何内容。

要添加更多隔离的智能体(独立的工作空间 + 会话 + 认证),使用:

提示: 不意味着非交互模式。使用 (和 )用于脚本。

1. 现有配置检测
   • 如果 存在,选择保留 / 修改 / 重置。
   • 重新运行向导不会清除任何内容,除非您明确选择重置 (或传递 )。
   • 如果配置无效或包含旧版键名,向导会停止并要求您在继续之前运行 。
   • 重置使用 (永远不使用 )并提供范围:
     • 仅配置
     • 配置 + 凭据 + 会话
     • 完全重置(也删除工作空间)
2. 模型/认证
   • Anthropic API 密钥(推荐):如果存在则使用 ,或提示输入密钥,然后保存供守护进程使用。
   • Anthropic OAuth (Claude Code CLI):在 macOS 上,向导检查钥匙串项"Claude Code-credentials"(选择"始终允许"以便 launchd 启动时不会阻塞);在 Linux/Windows 上,如果存在则重用 。
   • Anthropic token(粘贴 setup-token):在任何机器上运行 ,然后粘贴令牌(您可以命名它;空白 = 默认)。
   • OpenAI Code (Codex) 订阅 (Codex CLI):如果 存在,向导可以重用它。
   • OpenAI Code (Codex) 订阅 (OAuth):浏览器流程;粘贴 。
     • 当模型未设置或为 时,将 设置为 。
   • OpenAI API 密钥:如果存在则使用 ,或提示输入密钥,然后保存到 以便 launchd 可以读取。
   • OpenCode Zen(多模型代理):提示输入 (或 ,在 https://opencode.ai/auth 获取)。
   • API 密钥:为您存储密钥。
   • Vercel AI Gateway(多模型代理):提示输入 。
   • 更多详情:Vercel AI Gateway
   • MiniMax M2.1:配置自动写入。
   • 更多详情:MiniMax
   • Synthetic (Anthropic 兼容):提示输入 。
   • 更多详情:Synthetic
   • Moonshot (Kimi K2):配置自动写入。
   • Kimi Coding:配置自动写入。
   • 更多详情:Moonshot AI (Kimi + Kimi Coding)
   • 跳过:尚未配置认证。
   • 从检测到的选项中选择默认模型(或手动输入提供商/模型)。
   • 向导运行模型检查,如果配置的模型未知或缺少认证,则发出警告。

• OAuth 凭据位于 ;认证配置文件位于 (API 密钥 + OAuth)。
• 更多详情:/concepts/oauth

3. 工作空间
   • 默认 (可配置)。
   • 为智能体引导仪式准备工作空间所需的文件。
   • 完整工作空间布局 + 备份指南:智能体工作空间
4. Gateway 网关
   • 端口、绑定、认证模式、tailscale 暴露。
   • 认证建议:即使对于 local loopback 也保持 Token,以便本地 WS 客户端必须进行身份验证。
   • 仅当您完全信任每个本地进程时才禁用认证。
   • 非 loopback 绑定仍然需要认证。
5. 渠道
   • WhatsApp:可选的二维码登录。
   • Telegram:机器人令牌。
   • Discord:机器人令牌。
   • Google Chat:服务账户 JSON + webhook 受众。
   • Mattermost(插件):机器人令牌 + 基础 URL。
   • Signal:可选的 安装 + 账户配置。
   • BlueBubbles:推荐用于 iMessage;服务器 URL + 密码 + webhook。
   • iMessage:旧版 CLI 路径 + DB 访问。
   • 私信安全:默认是配对。首次私信发送代码;通过 批准或使用允许列表。
6. 守护进程安装
   • macOS:LaunchAgent
     • 需要已登录的用户会话;对于无头运行,使用自定义 LaunchDaemon(未提供)。
   • Linux(和通过 WSL2 的 Windows):systemd 用户单元
     • 向导尝试通过 启用持久化,以便 Gateway 网关在注销后保持运行。
     • 可能提示 sudo(写入 );它首先尝试不使用 sudo。
   • 运行时选择: Node(推荐;WhatsApp/Telegram 必需)。不推荐 Bun。
7. 健康检查
   • 启动 Gateway 网关(如果需要)并运行 。
   • 提示: 将网关健康探测添加到状态输出(需要可访问的网关)。
8. 技能(推荐)
   • 读取可用技能并检查要求。
   • 让您选择节点管理器:npm / pnpm(不推荐 bun)。
   • 安装可选依赖项(某些在 macOS 上使用 Homebrew)。
9. 完成
   • 摘要 + 下一步,包括用于额外功能的 iOS/Android/macOS 应用。

• 如果未检测到 GUI,向导会打印控制 UI 的 SSH 端口转发说明,而不是打开浏览器。
• 如果缺少控制 UI 资源,向导会尝试构建它们;回退是 (自动安装 UI 依赖项)。

远程模式配置本地客户端以连接到其他地方的 Gateway 网关。

您将设置的内容:

• 远程 Gateway 网关 URL ()
• 如果远程网关需要认证,则需要令牌(推荐)

注意事项:

• 不执行远程安装或守护进程更改。
• 如果网关仅限 loopback,请使用 SSH 隧道或 tailnet。
• 发现提示:
  • macOS:Bonjour ()
  • Linux:Avahi ()

使用 创建具有自己的工作空间、会话和认证配置文件的独立智能体。 不带 运行会启动向导。

它设置的内容:

注意事项:

• 默认工作空间遵循 。
• 添加 以路由入站消息(向导可以执行此操作)。
• 非交互式标志:、、、。

使用 自动化或编写引导脚本:

添加 以获取机器可读的摘要。

Gemini 示例:

Z.AI 示例:

Vercel AI Gateway 示例:

Moonshot 示例:

Synthetic 示例:

OpenCode Zen 示例:

添加智能体(非交互式)示例:

Gateway 网关通过 RPC 暴露向导流程(、、、)。 客户端(macOS 应用、控制 UI)可以渲染步骤而无需重新实现引导逻辑。

向导可以从 GitHub 发布版安装 :

• 下载适当的发布资源。
• 将其存储在 下。
• 将 写入您的配置。

注意事项:

• JVM 构建需要 Java 21。
• 在可用时使用原生构建。
• Windows 使用 WSL2;signal-cli 安装遵循 WSL 内的 Linux 流程。

中的典型字段:

• / (如果选择了 Minimax)
• (模式、绑定、认证、tailscale)
• 、、、
• 当您在提示期间选择时的渠道允许列表(Slack/Discord/Matrix/Microsoft Teams)(名称在可能时解析为 ID)。

写入 和可选的 。

WhatsApp 凭据位于 下。 会话存储在 下。

某些渠道作为插件交付。当您在引导期间选择一个时,向导会在配置之前提示安装它(npm 或本地路径)。

• macOS 应用新手引导:新手引导
• 配置参考:Gateway 网关配置
• 提供商:WhatsApp、Telegram、Discord、Google Chat、Signal、BlueBubbles(iMessage)、iMessage(旧版)
• 技能:Skills、Skills 配置

最后更新：2026-01-01

• 定制内容位于仓库外： （工作区）+ （配置）。
• 稳定工作流： 安装 macOS 应用；让它运行捆绑的 Gateway。
• 前沿工作流： 通过 自行运行 Gateway，然后让 macOS 应用以本地模式连接。

• Node
• Docker（可选；仅用于容器化设置/e2e — 参见 Docker）

如果您想要"100% 定制"_同时_轻松更新，请将您的自定义内容保存在：

• 配置： （JSON/JSON5 风格）
• 工作区： （Skills、提示词、记忆；建议设为私有 git 仓库）

一次性初始化：

在此仓库内，使用本地 CLI 入口：

如果您还没有全局安装，通过 运行。

1. 安装并启动 OpenClaw.app（菜单栏）。
2. 完成新手引导/权限检查清单（TCC 提示）。
3. 确保 Gateway 为 本地模式并正在运行（应用会管理它）。
4. 链接界面（例如：WhatsApp）：

5. 完整性检查：

如果您的构建版本中没有新手引导功能：

• 运行 ，然后 ，接着手动启动 Gateway（）。

目标：开发 TypeScript Gateway，获得热重载，保持 macOS 应用 UI 连接。

如果您也希望 macOS 应用保持前沿版本：

在监视模式下运行 gateway，并在 TypeScript 更改时重新加载。

在 OpenClaw.app 中：

• 连接模式：本地 应用将连接到配置端口上运行的 gateway。

• 应用内 Gateway 状态应显示 "使用现有 gateway …"
• 或通过 CLI：

• 端口错误： Gateway WS 默认为 ；保持应用 + CLI 使用相同端口。
• 状态存储位置：
  • 凭证：
  • 会话：
  • 日志：

调试身份验证或决定备份内容时使用：

• WhatsApp：
• Telegram bot token：config/env 或
• Discord bot token：config/env（尚不支持 token 文件）
• Slack tokens：config/env（）
• 配对白名单：
• 模型认证配置：
• 旧版 OAuth 导入： 更多详情：安全。

• 将 和 保留为"您的内容"；不要将个人提示词/配置放入 仓库。
• 更新源码： + （当 lockfile 变更时）+ 继续使用 。

Linux 安装使用 systemd 用户服务。默认情况下，systemd 在注销/空闲时停止用户服务，这会终止 Gateway。新手引导程序会尝试为您启用持久化（可能需要 sudo 提示）。如果仍未开启，运行：

对于始终在线或多用户服务器，考虑使用 系统服务而非用户服务（无需持久化）。参见 Gateway 运维手册中的 systemd 说明。

• Gateway 运维手册（标志、监控、端口）
• Gateway 配置（配置架构 + 示例）
• Discord 和 Telegram（回复标签 + replyToMode 设置）
• OpenClaw 助手设置
• macOS 应用（gateway 生命周期）

本文档描述当前的首次运行引导流程。目标是提供流畅的"第 0 天"体验：选择 Gateway 运行位置、连接身份验证、运行向导，并让智能体自我引导启动。

1. 欢迎 + 安全提示
2. Gateway 选择（本地 / 远程 / 稍后配置）
3. 身份验证（Anthropic OAuth） — 仅限本地
4. 设置向导（Gateway 驱动）
5. 权限（TCC 提示）
6. CLI（可选）
7. 新手引导对话（专用会话）
8. 就绪

阅读显示的安全提示并据此决定。

Gateway 在哪里运行？

• 本地（此 Mac）： 引导流程可以运行 OAuth 流程并在本地写入凭据。
• 远程（通过 SSH/Tailnet）： 引导流程不在本地运行 OAuth；凭据必须存在于 Gateway 主机上。
• 稍后配置： 跳过设置，保持应用未配置状态。

Gateway 身份验证提示：

• 向导现在即使对于环回也会生成令牌，因此本地 WS 客户端必须进行身份验证。
• 如果禁用身份验证，任何本地进程都可以连接；仅在完全受信任的机器上使用。
• 对于多机器访问或非环回绑定，请使用令牌。

macOS 应用支持 Anthropic OAuth（Claude Pro/Max）。流程如下：

• 打开浏览器进行 OAuth（PKCE）
• 要求用户粘贴 值
• 将凭据写入

其他提供商（OpenAI、自定义 API）目前通过环境变量或配置文件进行配置。

应用可以运行与 CLI 相同的设置向导。这使新手引导与 Gateway 端行为保持同步，避免在 SwiftUI 中重复逻辑。

新手引导请求所需的 TCC 权限：

• 通知
• 辅助功能
• 屏幕录制
• 麦克风 / 语音识别
• 自动化（AppleScript）

应用可以通过 npm/pnpm 安装全局 CLI，使终端工作流和 launchd 任务开箱即用。

设置完成后，应用打开一个专用的新手引导对话会话，以便智能体可以介绍自己并指导后续步骤。这使首次运行指导与正常对话分开。

在首次智能体运行时，OpenClaw 引导一个工作空间（默认为 ）：

• 植入 、、、
• 运行简短的问答仪式（一次一个问题）
• 将身份 + 偏好写入 、、
• 完成后删除 ，使其仅运行一次

Gmail Pub/Sub 设置目前是手动步骤。使用：

详见 /automation/gmail-pubsub。

当 Gateway 在另一台机器上运行时，凭据和工作空间文件位于该主机上。如果在远程模式下需要 OAuth，请创建：

在 Gateway 主机上。

"配对"是 OpenClaw 的显式所有者批准步骤。 它用于两个地方：

1. 私信配对（谁被允许与机器人对话）
2. 节点配对（哪些设备/节点被允许加入网关网络）

安全上下文：安全性

当渠道配置为私信策略 时，未知发送者会收到一个短代码，并且他们的消息在您批准之前不会被处理。

默认私信策略记录在：安全性

配对代码：

• 8 个字符，大写，无歧义字符（）。
• 1 小时后过期。机器人仅在创建新请求时发送配对消息（每个发送者大约每小时一次）。
• 待处理的私信配对请求默认情况下每个渠道上限为 3 个；在一个请求过期或被批准之前，其他请求将被忽略。

支持的渠道：、、、、、。

存储在 下：

• 待处理请求：
• 已批准的允许列表存储：

将这些视为敏感信息（它们控制对您的助手的访问）。

节点通过 作为设备连接到 Gateway 网关。Gateway 网关 创建一个必须被批准的设备配对请求。

存储在 下：

• （短期；待处理请求会过期）
• （已配对设备 + 令牌）

• 旧版 API（CLI：）是一个 单独的网关所有的配对存储。WS 节点仍然需要设备配对。

• 安全模型 + 提示注入：安全性
• 安全更新（运行 doctor）：更新
• 渠道配置：
  • Telegram：Telegram
  • WhatsApp：WhatsApp
  • Signal：Signal
  • BlueBubbles (iMessage)：BlueBubbles
  • iMessage（旧版）：iMessage
  • Discord：Discord
  • Slack：Slack

OpenClaw 是 Pi 智能体的 WhatsApp + Telegram + Discord + iMessage 网关。插件可添加 Mattermost。本指南为"个人助手"设置：一个专用的 WhatsApp 号码，表现为您的全天候智能体。

您正在将智能体置于如下位置：

• 在您的机器上运行命令（取决于您的 Pi 工具设置）
• 在您的工作区中读/写文件
• 通过 WhatsApp/Telegram/Discord/Mattermost（插件）回发消息

保守起见：

• 始终设置 （切勿在您的个人 Mac 上开放给所有人）。
• 为助手使用专用的 WhatsApp 号码。
• 心跳现在默认为每 30 分钟一次。通过设置 来禁用，直到您信任该设置。

• Node 22+
• OpenClaw 在 PATH 中可用（推荐：全局安装）
• 助手的第二个电话号码（SIM/eSIM/预付费）

从源码安装（开发）：

您需要这样：

如果您将个人 WhatsApp 链接到 OpenClaw，发给您的每条消息都会成为"智能体输入"。这很少是您想要的。

1. 配对 WhatsApp Web（显示二维码；用助手手机扫描）：

2. 启动 Gateway 网关（保持运行）：

3. 在 中放入最小配置：

现在从您的白名单手机向助手号码发送消息。

当新手引导完成后，我们会自动打开带有您的网关令牌的仪表板，并打印令牌化链接。稍后重新打开：。

OpenClaw 从其工作区目录读取操作指令和"记忆"。

默认情况下，OpenClaw 使用 作为智能体工作区，并在设置/首次智能体运行时自动创建它（加上入门 、、、、）。 仅在工作区全新时创建（删除后不应再出现）。

提示：将此文件夹视为 OpenClaw 的"记忆"，并将其设为 git 仓库（最好是私有的），以便备份您的 + 记忆文件。如果已安装 git，全新工作区会自动初始化。

完整工作区布局 + 备份指南：智能体工作区 记忆工作流：记忆

可选：使用 选择不同的工作区（支持 ）。

如果您已经从仓库提供自己的工作区文件，可以完全禁用引导文件创建：

OpenClaw 默认为良好的助手设置，但您通常需要调整：

• 中的角色/指令
• 思考默认值（如果需要）
• 心跳（一旦您信任它）

示例：

• 会话文件：
• 会话元数据（令牌使用情况、最后路由等）：（旧版：）
• 或 为该聊天启动新会话（可通过 配置）。如果单独发送，智能体会回复简短的问候以确认重置。
• 压缩会话上下文并报告剩余上下文预算。

默认情况下，OpenClaw 每 30 分钟运行一次心跳，提示为： 设置 以禁用。

• 如果 存在但实际上为空（仅有空行和 markdown 标题，如 ），OpenClaw 会跳过心跳运行以节省 API 调用。
• 如果文件缺失，心跳仍会运行，模型决定如何处理。
• 如果智能体回复 （可选择带有简短填充；见 ），OpenClaw 会抑制该心跳的出站传递。
• 心跳运行完整的智能体回合——较短的间隔会消耗更多令牌。

入站附件（图像/音频/文档）可以通过模板传递给您的命令：

• （本地临时文件路径）
• （伪 URL）
• （如果启用了音频转录）

来自智能体的出站附件：单独一行包含 （无空格）。示例：

OpenClaw 会提取这些内容，并将它们作为媒体与文本一起发送。

日志位于 下（默认：）。

• WebChat：WebChat
• Gateway 网关操作：Gateway 网关运行手册
• Cron + 唤醒：Cron 作业
• macOS 菜单栏伴侣：OpenClaw macOS 应用
• iOS 节点应用：iOS 应用
• Android 节点应用：Android 应用
• Windows 状态：Windows (WSL2)
• Linux 状态：Linux 应用
• 安全性：安全性