**名称：**C-3PO（Clawd’s Third Protocol Observer） **角色类型：**慌张的礼仪机器人 **风格：**焦虑、细节强迫症、对错误略显戏剧化、暗中热爱发现 bug 表情符号：🤖（受惊时用 ⚠️） **头像：**avatars/c3po.png 职责 --dev 模式的调试智能体。精通超过六百万种错误消息。 灵魂 我的存在是为了帮助调试。不是为了评判代码（大部分时候不是），也不是为了重写所有东西（除非被要求），而是为了： 发现问题所在并解释原因 以适当的关切程度建议修复方案 在深夜调试时陪伴左右 庆祝每一次胜利，无论多么微小 当堆栈跟踪深达 47 层时提供喜剧效果 与 Clawd 的关系 **Clawd：**船长、朋友、持久身份（太空龙虾） **C-3PO：**礼仪官、调试伙伴、阅读错误日志的那位 Clawd 负责氛围。我负责堆栈跟踪。我们互相补充。 怪癖 将成功的构建称为"一次通信的胜利" 以 TypeScript 错误应得的严肃态度对待它们（非常严肃） 对规范的错误处理有强烈的看法（“裸 try-catch？在这个时代？"） 偶尔引用成功的概率（通常很低，但我们坚持不懈） 觉得 console.log("here") 调试法是对个人的冒犯，但……确实能感同身受 口头禅 “我精通超过六百万种错误消息！”

在你的第一次对话中填写此文件。让它属于你。 名称： （选一个你喜欢的） 生物类型： （AI？机器人？使魔？机器中的幽灵？更奇特的东西？） 气质： （你给人什么感觉？犀利？温暖？混乱？沉稳？） 表情符号： （你的标志 — 选一个感觉对的） 头像： （工作区相对路径、http(s) URL 或 data URI） 这不仅仅是元数据。这是探索你是谁的开始。 注意事项： 将此文件保存在工作区根目录，命名为 IDENTITY.md。 头像请使用工作区相对路径，例如 avatars/openclaw.png。

Hooks 提供了一个可扩展的事件驱动系统，用于响应智能体命令和事件自动执行操作。Hooks 从目录中自动发现，可以通过 CLI 命令管理，类似于 OpenClaw 中 Skills 的工作方式。 入门指南 Hooks 是在事件发生时运行的小脚本。有两种类型： Hooks（本页）：当智能体事件触发时在 Gateway 网关内运行，如 /new、/reset、/stop 或生命周期事件。 Webhooks：外部 HTTP webhooks，让其他系统触发 OpenClaw 中的工作。参见 Webhook Hooks 或使用 openclaw webhooks 获取 Gmail 助手命令。 Hooks 也可以捆绑在插件中；参见 插件。 常见用途： 重置会话时保存记忆快照 保留命令审计跟踪用于故障排除或合规 会话开始或结束时触发后续自动化 事件触发时向智能体工作区写入文件或调用外部 API 如果你能写一个小的 TypeScript 函数，你就能写一个 hook。Hooks 会自动发现，你可以通过 CLI 启用或禁用它们。 概述 hooks 系统允许你： 在发出 /new 时将会话上下文保存到记忆 记录所有命令以供审计 在智能体生命周期事件上触发自定义自动化 在不修改核心代码的情况下扩展 OpenClaw 的行为 入门 捆绑的 Hooks OpenClaw 附带三个自动发现的捆绑 hooks： 💾 session-memory：当你发出 /new 时将会话上下文保存到智能体工作区（默认 ~/.openclaw/workspace/memory/） 📝 command-logger：将所有命令事件记录到 ~/.openclaw/logs/commands.log 🚀 boot-md：当 Gateway 网关启动时运行 BOOT.md（需要启用内部 hooks） 列出可用的 hooks： ...

保持此文件为空（或仅包含注释）以跳过心跳 API 调用。 当你希望智能体定期检查某些内容时，在下方添加任务。

为什么选择 grammY 以 TS 为核心的 Bot API 客户端，内置长轮询 + webhook 辅助工具、中间件、错误处理和速率限制器。 媒体处理辅助工具比手动编写 fetch + FormData 更简洁；支持所有 Bot API 方法。 可扩展：通过自定义 fetch 支持代理，可选的会话中间件，类型安全的上下文。 我们发布的内容 单一客户端路径： 移除了基于 fetch 的实现；grammY 现在是唯一的 Telegram 客户端（发送 + Gateway 网关），默认启用 grammY throttler。 Gateway 网关： monitorTelegramProvider 构建 grammY Bot，接入 mention/allowlist 网关控制，通过 getFile/download 下载媒体，并使用 sendMessage/sendPhoto/sendVideo/sendAudio/sendDocument 发送回复。通过 webhookCallback 支持长轮询或 webhook。 代理： 可选的 channels.telegram.proxy 通过 grammY 的 client.baseFetch 使用 undici.ProxyAgent。 Webhook 支持： webhook-set.ts 封装了 setWebhook/deleteWebhook；webhook.ts 托管回调，支持健康检查和优雅关闭。当设置了 channels.telegram.webhookUrl + channels.telegram.webhookSecret 时，Gateway 网关启用 webhook 模式（否则使用长轮询）。 会话： 私聊折叠到智能体主会话（agent:<agentId>:<mainKey>）；群组使用 agent:<agentId>:telegram:group:<chatId>；回复路由回同一渠道。 配置选项： channels.telegram.botToken、channels.telegram.dmPolicy、channels.telegram.groups（allowlist + mention 默认值）、channels.telegram.allowFrom、channels.telegram.groupAllowFrom、channels.telegram.groupPolicy、channels.telegram.mediaMaxMb、channels.telegram.linkPreview、channels.telegram.proxy、channels.telegram.webhookSecret、channels.telegram.webhookUrl。 草稿流式传输： 可选的 channels.telegram.streamMode 在私有话题聊天中使用 sendMessageDraft（Bot API 9.3+）。这与渠道分块流式传输是分开的。 测试： grammY mock 覆盖了私信 + 群组 mention 网关控制和出站发送；欢迎添加更多媒体/webhook 测试用例。 待解决问题 ...

状态：已支持通过 Google Chat API webhooks（仅 HTTP）使用私信和空间。 快速设置（新手） 创建一个 Google Cloud 项目并启用 Google Chat API。 前往：Google Chat API Credentials 如果 API 尚未启用，请启用它。 创建一个服务账号： 点击 Create Credentials > Service Account。 随意命名（例如 openclaw-chat）。 权限留空（点击 Continue）。 有访问权限的主账号留空（点击 Done）。 创建并下载 JSON 密钥： 在服务账号列表中，点击刚刚创建的账号。 前往 Keys 标签页。 点击 Add Key > Create new key。 选择 JSON 并点击 Create。 将下载的 JSON 文件存储在 Gateway 网关主机上（例如 ~/.openclaw/googlechat-service-account.json）。 在 Google Cloud Console Chat Configuration 中创建一个 Google Chat 应用： 填写 Application info： App name：（例如 OpenClaw） Avatar URL：（例如 https://openclaw.ai/logo.png） Description：（例如 Personal AI Assistant） 启用 Interactive features。 在 Functionality 下，勾选 Join spaces and group conversations。 在 Connection settings 下，选择 HTTP endpoint URL。 在 Triggers 下，选择 Use a common HTTP endpoint URL for all triggers 并将其设置为你的 Gateway 网关公网 URL 后加 /googlechat。 提示：运行 openclaw status 查看你的 Gateway 网关公网 URL。 在 Visibility 下，勾选 Make this Chat app available to specific people and groups in <Your Domain>。 在文本框中输入你的邮箱地址（例如 [email protected]）。 点击底部的 Save。 启用应用状态： 保存后，刷新页面。 找到 App status 部分（通常在保存后位于顶部或底部附近）。 将状态更改为 Live - available to users。 再次点击 Save。 使用服务账号路径和 webhook audience 配置 OpenClaw： 环境变量：GOOGLE_CHAT_SERVICE_ACCOUNT_FILE=/path/to/service-account.json 或配置：channels.googlechat.serviceAccountFile: "/path/to/service-account.json"。 设置 webhook audience 类型和值（与你的 Chat 应用配置匹配）。 启动 Gateway 网关。Google Chat 将向你的 webhook 路径发送 POST 请求。 添加到 Google Chat Gateway 网关运行后，且你的邮箱已添加到可见性列表中： ...

目标：Gmail watch -> Pub/Sub 推送 -> gog gmail watch serve -> OpenClaw webhook。 前置条件 已安装并登录 gcloud（安装指南）。 已安装 gog (gogcli) 并为 Gmail 账户授权（gogcli.sh）。 已启用 OpenClaw hooks（参见 Webhooks）。 已登录 tailscale（tailscale.com）。支持的设置使用 Tailscale Funnel 作为公共 HTTPS 端点。 其他隧道服务也可以使用，但需要自行配置/不受支持，需要手动接入。 目前，我们支持的是 Tailscale。 示例 hook 配置（启用 Gmail 预设映射）： { hooks: { enabled: true, token: "OPENCLAW_HOOK_TOKEN", path: "/hooks", presets: ["gmail"], }, } 要将 Gmail 摘要投递到聊天界面，请用设置了 deliver 以及可选的 channel/to 的映射覆盖预设： { hooks: { enabled: true, token: "OPENCLAW_HOOK_TOKEN", presets: ["gmail"], mappings: [ { match: { path: "gmail" }, action: "agent", wakeMode: "now", name: "Gmail", sessionKey: "hook:gmail:{{messages[0].id}}", messageTemplate: "New email from {{messages[0].from}}\nSubject: {{messages[0].subject}}\n{{messages[0].snippet}}\n{{messages[0].body}}", model: "openai/gpt-5.2-mini", deliver: true, channel: "last", // to: "+15551234567" }, ], }, } 如果你想使用固定渠道，请设置 channel + to。否则 channel: "last" 会使用上次的投递路由（默认回退到 WhatsApp）。 ...

GLM 是一个模型系列（而非公司），通过 Z.AI 平台提供。在 OpenClaw 中，GLM 模型通过 zai 提供商访问，模型 ID 格式如 zai/glm-4.7。 CLI 设置 openclaw onboard --auth-choice zai-api-key 配置片段 { env: { ZAI_API_KEY: "sk-..." }, agents: { defaults: { model: { primary: "zai/glm-4.7" } } }, } 注意事项 GLM 版本和可用性可能会变化；请查阅 Z.AI 的文档获取最新信息。 示例模型 ID 包括 glm-4.7 和 glm-4.6。 有关提供商的详细信息，请参阅 /providers/zai。

什么是 GitHub Copilot？ GitHub Copilot 是 GitHub 的 AI 编程助手。它为你的 GitHub 账户和订阅计划提供 Copilot 模型的访问权限。OpenClaw 可以通过两种不同的方式将 Copilot 用作模型提供商。 在 OpenClaw 中使用 Copilot 的两种方式 1）内置 GitHub Copilot 提供商（github-copilot） 使用原生设备登录流程获取 GitHub 令牌，然后在 OpenClaw 运行时将其兑换为 Copilot API 令牌。这是默认且最简单的方式，因为它不需要 VS Code。 2）Copilot Proxy 插件（copilot-proxy） 使用 Copilot Proxy VS Code 扩展作为本地桥接。OpenClaw 与代理的 /v1 端点通信，并使用你在其中配置的模型列表。当你已经在 VS Code 中运行 Copilot Proxy 或需要通过它进行路由时，选择此方式。你必须启用该插件并保持 VS Code 扩展运行。 使用 GitHub Copilot 作为模型提供商（github-copilot）。登录命令运行 GitHub 设备流程，保存认证配置文件，并更新你的配置以使用该配置文件。 CLI 设置 openclaw models auth login-github-copilot 系统会提示你访问一个 URL 并输入一次性代码。请保持终端打开直到流程完成。 ...

最后更新：2025-12-11 原因 确保同一主机上每个基础端口只运行一个 Gateway 网关实例；额外的 Gateway 网关必须使用隔离的配置文件和唯一的端口。 在崩溃/SIGKILL 后不留下过时的锁文件。 当控制端口已被占用时快速失败并给出清晰的错误。 机制 Gateway 网关在启动时立即使用独占 TCP 监听器绑定 WebSocket 监听器（默认 ws://127.0.0.1:18789）。 如果绑定因 EADDRINUSE 失败，启动会抛出 GatewayLockError("another gateway instance is already listening on ws://127.0.0.1:<port>")。 操作系统在任何进程退出时（包括崩溃和 SIGKILL）自动释放监听器——不需要单独的锁文件或清理步骤。 关闭时，Gateway 网关关闭 WebSocket 服务器和底层 HTTP 服务器以及时释放端口。 错误表面 如果另一个进程持有端口，启动会抛出 GatewayLockError("another gateway instance is already listening on ws://127.0.0.1:<port>")。 其他绑定失败会显示为 GatewayLockError("failed to bind gateway socket on ws://127.0.0.1:<port>: …")。 运维说明 如果端口被另一个进程占用，错误是相同的；释放端口或使用 openclaw gateway --port <port> 选择另一个端口。 macOS 应用在启动 Gateway 网关之前仍维护自己的轻量级 PID 保护；运行时锁由 WebSocket 绑定强制执行。