Clawdbot（现已更名为 Moltbot）是一款开源自托管 AI 助手，截至 2026 年 1 月已获得 GitHub 63.9k Stars。它不仅仅是一个聊天机器人，更是一个能够执行任务、管理文件、自动化工作流的智能代理平台。本文将深入解析其 Gateway 架构、WebSocket API 协议、自定义 Skill 开发流程，并提供国产模型接入、API 中转配置、安全最佳实践等中国开发者急需的实用指南。无论你是想集成到现有项目，还是开发自己的 Skill 扩展功能，这份指南都将帮助你从"会用"升级到"精通"。
要点速览
开始深入技术细节之前，先快速了解本文的核心内容。Clawdbot/Moltbot 是一个基于 Gateway 架构的 AI 助手平台，通过 WebSocket 协议统一管理消息、工具和事件。以下是你将学到的关键知识点：
- Gateway 架构：单一控制平面，默认运行在
ws://127.0.0.1:18789，支持 13 个消息渠道（WhatsApp、Telegram、Slack、Discord 等）和多代理路由 - Skill 开发：通过 SKILL.md 文件定义技能，支持 Gating 机制控制加载条件，可发布到 ClawdHub（565+ 社区技能）
- 多模型接入：支持 Anthropic Claude、OpenAI GPT、DeepSeek、智谱 GLM、Moonshot AI 等，以及 Ollama 本地模型
- API 中转配置：解决国内网络限制，通过 laozhang.ai 等中转服务稳定访问国际模型
- 安全最佳实践：Gateway 认证、权限控制、数据保护的完整清单
- 故障排查：常见错误代码、连接问题、模型调用失败的系统性解决方案
Gateway 架构深度解析
Gateway 是 Clawdbot 的核心，它作为单一控制平面，统一管理所有消息表面、工具调用和事件分发。理解 Gateway 的工作原理，是进行 API 开发和集成的基础。与传统的客户端-服务器架构不同，Clawdbot 采用了网关中心化的设计，这意味着每台主机只运行一个 Gateway 进程，所有组件都通过 WebSocket 连接到它。
Gateway 默认绑定在 ws://127.0.0.1:18789，作为所有通信的中枢。它接收来自消息渠道（WhatsApp、Telegram 等）的入站消息，将其路由到对应的 AI Agent 进行处理，然后协调 Skill 执行和响应发送。这种架构的优势在于：所有状态集中管理，易于调试和监控；单一入口点简化了安全配置；支持多代理路由，不同渠道可以路由到不同的 Agent 工作区。
WebSocket 通信采用 JSON 文本帧格式，遵循请求-响应模式。典型的消息流程是：客户端发送 {type:"req", id, method, params} 格式的请求，Gateway 返回 {type:"res", id, ok, payload} 格式的响应。对于异步事件，Gateway 会推送 {type:"event", event, payload} 格式的消息，常见的事件类型包括 event:presence（在线状态）、event:agent（Agent 响应流）等。
在认证机制方面，Clawdbot 采用设备配对模式。新设备首次连接时需要配对批准，Gateway 会颁发设备令牌供后续连接使用。本地连接可以自动批准，而远程连接则需要签署随机挑战并获得明确批准。你可以通过设置 CLAWDBOT_GATEWAY_TOKEN 环境变量来启用令牌认证，所有连接都必须在 connect 消息中包含匹配的令牌才能建立连接。关于 API 网关的更多设计模式，可以参考我们的 LLM API 网关开发者指南。
对于需要直接与 Gateway 通信的场景（比如开发自定义客户端或集成工具），你需要了解完整的连接流程。首先建立 WebSocket 连接，然后发送 connect 帧进行握手，握手成功后就可以发送各种请求和接收事件了。需要注意的是，具有副作用的方法（如 send、agent）需要提供幂等密钥（idempotency key）以支持安全重试，Gateway 会维护一个短期的去重缓存来处理重复请求。
自定义 Skill 开发实战
Skill 是扩展 Clawdbot 功能的核心机制。通过编写 Skill，你可以教会 AI 助手使用新的工具、集成外部服务或自动化特定工作流。每个 Skill 本质上是一个包含 SKILL.md 文件的目录，文件中包含 YAML 前置元数据和 Markdown 格式的指令说明。与传统的插件系统不同，Skill 采用声明式定义，让你专注于描述"做什么"而不是"怎么做"。
创建 Skill 的第一步是选择存放位置。Clawdbot 支持三层加载优先级：工作区级别（<workspace>/skills）优先级最高，适合项目特定的技能；用户级别（~/.clawdbot/skills）次之，适合跨项目共享的技能；内置技能优先级最低，可以被前两者覆盖。如果你想创建一个在所有项目中都可用的技能，推荐放在用户目录下。
SKILL.md 文件的格式遵循 AgentSkills 标准，确保跨平台兼容性。必需字段只有两个：name（技能唯一标识）和 description（功能描述）。前置元数据使用 YAML 格式，紧随其后的是 Markdown 格式的技能指令，告诉 AI 如何以及何时使用这个技能。一个简单的示例如下：
yaml--- name: "weather-check" description: "查询指定城市的天气信息" --- 当用户询问天气信息时，使用此技能。 ## 使用方法 1. 提取用户查询中的城市名称 2. 调用天气 API 获取数据 3. 以友好的格式返回天气信息 ## 示例 用户："北京今天天气怎么样？" 响应：调用 weather API 查询北京天气，返回温度、湿度、天气状况等信息。
Gating 机制是 Skill 系统的一个强大特性，它允许你控制技能何时加载。通过在 metadata.clawdbot 下配置条件，你可以指定技能只在特定操作系统上加载（os: [darwin, linux]）、只在某些二进制文件存在时加载（requires.bins: [node, python]）、或只在特定环境变量设置时加载（requires.env: [API_KEY]）。这对于需要特定依赖的技能非常有用，避免了在不满足条件的环境中加载失败。
本地测试技能时，运行 moltbot skills list 可以查看所有已加载的技能，确认你的新技能出现在列表中。如果技能没有加载，检查 Gating 条件是否满足。测试完成后，你可以通过 clawdhub sync 命令将技能发布到公共注册中心 ClawdHub，让全球用户都能使用。目前 ClawdHub 上已有 565+ 个社区贡献的技能，涵盖浏览器控制、文件操作、API 集成等各种场景。
进阶开发者还可以探索安装钩子（install hooks）功能，在 Skill 安装时自动安装依赖。支持的安装器类型包括 brew、node、go 和 download，系统会自动选择最优的安装方案。这使得复杂技能的分发和部署变得更加顺畅，用户不需要手动处理依赖问题。
多模型接入配置
Clawdbot 的设计理念是"模型无关"，这意味着你可以自由选择最适合任务的 AI 模型。目前官方支持 Anthropic Claude 和 OpenAI GPT，同时通过 OpenAI 兼容 API 也可以接入各种国产模型。对于注重隐私的用户，还可以使用 Ollama 运行完全本地的模型。
Anthropic Claude 是官方推荐的首选模型，特别是 Claude Opus 4.5 版本（截至 2026 年 1 月的最新版本，来源：docs.molt.bot）。Claude 的优势在于 200K 的超长上下文窗口和出色的代码能力，非常适合需要处理大量信息或复杂编程任务的场景。配置方式是在 moltbot.json 中指定 "model": "anthropic/claude-opus-4-5"，认证可以选择 API Key 或 OAuth 订阅（支持 Claude Pro/Max）。
OpenAI GPT 系列同样得到良好支持，配置方式类似。GPT-5.2 是当前支持的版本（来源：docs.molt.bot），你可以通过 API Key 或 Codex 订阅进行认证。OpenAI 的优势在于丰富的生态系统和广泛的兼容性，如果你的项目已经使用了 OpenAI API，迁移到 Clawdbot 会非常顺畅。
对于中国开发者来说，国产模型是一个重要选项。DeepSeek、智谱 GLM/ChatGLM、Moonshot AI (Kimi) 等国产模型都可以通过 OpenAI 兼容 API 接入。这些模型的优势在于国内访问稳定、无需翻墙、成本更低。配置时需要设置对应的 BASE_URL 指向模型提供商的 API 端点，然后使用兼容的模型名称即可。
本地模型是数据隐私最高优先级的选择。通过 Ollama，你可以在本地运行 Llama 3 等开源模型，所有数据完全不出本地。配置非常简单：安装 Ollama，运行 ollama run llama3 启动模型，然后在 Clawdbot 中指定模型提供商为 Ollama。需要注意的是，本地模型对硬件有一定要求，至少需要 8GB 显存的 GPU 才能获得流畅的体验。
API 中转服务配置是解决国内网络限制的关键。由于 Anthropic 和 OpenAI 的直连在国内经常不稳定，使用中转服务可以大幅提升可靠性。配置方法是设置环境变量：ANTHROPIC_BASE_URL="https://api.laozhang.ai/v1" 和对应的 API Key。laozhang.ai 支持 Claude、GPT 以及多种国产模型，按量计费无月费，可以参考 Claude API 国内访问方案 了解更多细节。获取 API Key 后，完整的配置文档可以在 https://docs.laozhang.ai/ 查看。
生产环境部署方案
将 Clawdbot 从本地开发环境部署到生产服务器，需要考虑稳定性、安全性和可维护性。虽然本地使用只需要 moltbot onboard 一条命令，但生产部署需要更多的配置和监控措施。
服务器要求方面，推荐使用至少 2 核 CPU 和 4GB 内存的实例。Node.js 版本必须 >= 22（这是官方要求，来源：GitHub README）。如果使用本地模型，还需要配置 GPU。操作系统支持 macOS、Linux 和 Windows（通过 WSL2）。对于大多数用户，我推荐使用 Linux 服务器，因为它提供了最稳定的运行环境和最完善的进程管理支持。
进程管理是生产部署的关键。Clawdbot 的 Gateway 需要持续运行，任何中断都会导致消息丢失。在 Linux 上，推荐使用 systemd 来管理 Gateway 进程。创建一个 service 文件，配置自动重启和日志轮转。安装时使用 --install-daemon 参数，系统会自动配置 launchd（macOS）或 systemd（Linux）用户服务。
监控和日志是排查问题的基础。Gateway 运行时默认将日志输出到 stdout，你可以通过 moltbot logs --follow 实时查看。生产环境建议将日志持久化到文件，并配置日志聚合工具（如 Loki、ELK Stack）进行集中管理。关键指标包括：WebSocket 连接数、消息处理延迟、API 调用成功率、内存使用量等。
网络配置需要特别注意。如果 Gateway 需要接受外部连接，必须配置正确的绑定地址和防火墙规则。默认的 127.0.0.1 只允许本地连接，要允许远程连接需要绑定到 0.0.0.0 或具体的网络接口地址。强烈建议在外网暴露时启用 TLS 加密和令牌认证，防止未授权访问。
备份策略也很重要。Clawdbot 的配置文件位于 ~/.clawdbot/，包括 clawdbot.json（配置）、skills/（自定义技能）和 memory/（对话记忆）。定期备份这些文件，可以在服务器故障时快速恢复。如果使用多台服务器，可以考虑将配置存储在版本控制系统中，实现配置即代码。
安全配置与最佳实践
安全是自托管 AI 助手的核心考量。Clawdbot 拥有对本地系统的广泛访问权限——它可以执行 Shell 命令、读写文件、控制浏览器，这意味着不当的配置可能带来严重的安全风险。以下是我总结的安全配置清单和最佳实践。
Gateway 认证是第一道防线。在生产环境中，必须设置 CLAWDBOT_GATEWAY_TOKEN 环境变量，所有客户端连接都需要提供正确的令牌。令牌应该足够复杂（至少 32 个随机字符），并定期轮换。不要将令牌硬编码在代码或配置文件中，而是通过环境变量或密钥管理服务注入。
权限控制遵循最小权限原则。Clawdbot 支持细粒度的执行审批（exec-approvals），你可以配置哪些命令需要用户确认、哪些命令被禁止执行。对于敏感操作（如删除文件、修改系统配置），建议默认设置为需要审批。通过 ~/.clawdbot/clawdbot.json 中的 security 配置项，你可以精确控制各种权限。
数据保护涉及多个层面。首先，敏感信息（如 API Key、密码）不要通过消息渠道传输，而是通过环境变量或配置文件注入。其次，对话记忆默认存储在本地，如果包含敏感信息，确保文件权限正确（只有运行 Clawdbot 的用户可以访问）。第三，如果使用云端 AI 模型，注意数据会被发送到外部服务器，评估是否符合你的合规要求。
网络安全不容忽视。不要在公网直接暴露 Gateway 端口，而是通过 VPN 或 Tailscale 等工具建立安全隧道。如果必须公网访问，使用反向代理（如 Nginx）添加 TLS 加密和额外的认证层。定期检查端口暴露情况，关闭不必要的服务。
定期审计是安全管理的一部分。检查已安装的 Skill，确保没有未知来源的技能。审查 Gateway 日志，关注异常的连接尝试和命令执行。更新 Clawdbot 到最新版本，获取安全补丁。如果发现可疑活动，立即更换认证令牌并检查系统完整性。
故障排查完整手册
即使配置正确，运行过程中仍可能遇到各种问题。本节提供系统性的故障排查方法，帮助你快速定位和解决常见问题。
连接问题是最常见的故障类型。如果客户端无法连接到 Gateway，首先检查 Gateway 是否正在运行（moltbot gateway status），然后确认端口是否正确（默认 18789）。如果是远程连接，检查防火墙规则和网络路由。如果启用了令牌认证，确保客户端提供了正确的令牌。WebSocket 连接超时可能是网络不稳定导致，尝试增加超时设置或检查网络质量。
模型调用失败有多种可能原因。API Key 无效或过期是常见原因，检查环境变量或配置文件中的 Key 是否正确。如果使用中转服务，确认 BASE_URL 设置正确。网络错误（如连接超时、DNS 解析失败）通常与网络环境有关，可以尝试切换网络或使用中转服务。模型限流（rate limit）会返回 429 错误，解决方法是降低请求频率或升级 API 配额。
Skill 加载失败通常与 Gating 条件有关。运行 moltbot skills list --verbose 查看每个 Skill 的加载状态和失败原因。常见原因包括：所需的二进制文件不在 PATH 中、环境变量未设置、配置项缺失等。检查 SKILL.md 文件的格式是否正确，YAML 前置元数据必须是合法的 YAML 格式。
日志分析是定位问题的关键。使用 moltbot logs --follow 实时查看日志，关注 ERROR 和 WARN 级别的消息。常见的错误代码包括：ECONNREFUSED（连接被拒绝，检查目标服务是否运行）、ETIMEDOUT（连接超时，检查网络）、ENOTFOUND（域名解析失败，检查 DNS）、401（认证失败，检查令牌或 API Key）、429（限流，降低请求频率）。
如果问题持续无法解决，可以采取以下步骤：首先尝试重启 Gateway（moltbot gateway restart），很多临时性问题可以通过重启解决。然后检查是否是版本兼容问题，尝试更新到最新版本。如果仍然无法解决，可以在 GitHub Issues 中搜索类似问题或提交新的 Issue，附上详细的日志和复现步骤。
常见问题 FAQ
Clawdbot 和 Moltbot 是什么关系？
Clawdbot 是项目的原始名称，由 Peter Steinberger（PSPDFKit 创始人）开发。2026 年 1 月，由于收到 Anthropic 的 C&D 函件（因名称中包含"Claud"），项目更名为 Moltbot。域名从 clawd.bot 改为 molt.bot，GitHub 组织从 clawdbot 改为 moltbot。功能上完全相同，只是品牌名称变化。
如何选择最适合的 AI 模型？
这取决于你的具体需求。如果需要处理长文档或复杂代码任务，推荐 Claude Opus 4.5，它有 200K 上下文窗口。如果追求性价比，国产模型如 DeepSeek 是不错的选择。如果对数据隐私要求极高，使用 Ollama 运行本地模型。对于一般使用场景，Claude 或 GPT 都能胜任。
国内使用需要翻墙吗？
不一定。如果使用国产模型（DeepSeek、智谱、Moonshot 等），完全不需要翻墙。如果使用 Anthropic 或 OpenAI，可以通过 API 中转服务（如 laozhang.ai）访问，也不需要翻墙。只有直连官方 API 时才需要考虑网络问题。更多方案可以参考 Claude API 购买指南。
Skill 开发需要什么技术背景？
最基础的 Skill 只需要会写 Markdown 即可——SKILL.md 文件的核心是用自然语言描述技能的用途和使用方法。如果要开发涉及 API 调用或复杂逻辑的技能，需要一定的编程基础。高级技能可能需要 TypeScript/JavaScript 知识，因为可以编写自定义的工具函数。
如何保证数据安全？
Clawdbot 是自托管的，数据完全存储在你自己的设备上。使用本地模型时，数据不会发送到任何外部服务器。使用云端模型时，对话会发送到模型提供商（遵循其数据政策）。通过配置 Gateway 认证、权限控制和网络隔离，可以进一步加强安全性。详细的安全配置请参考本文的"安全配置与最佳实践"章节。