私有化AI助理网关部署指南：从工具调用到多平台集成

1. 项目概述：打造你的24x7全天候AI个人助理

如果你和我一样，厌倦了在手机和电脑之间来回切换，只为让AI助手帮你处理一些琐事——比如查邮件、定日程、或者只是简单地问个问题——那么Secure OpenClaw这个项目，绝对值得你花上一个下午的时间来部署。这本质上是一个可私有化部署、支持多消息平台、且具备强大工具调用能力的AI助理网关。你可以把它想象成一个永远在线、只听你指挥的“数字管家”，它住在你自己的服务器（或者电脑）上，通过你日常使用的WhatsApp、Telegram、Signal甚至iMessage与你对话，背后则由Claude或Opencode这样的强大AI模型驱动。

最吸引我的地方在于它的“工具访问”能力。这不仅仅是聊天。当你对它说“提醒我明天下午三点开会”，它能调用系统工具创建一个定时任务；说“给我查一下邮箱里某某的未读邮件”，它能通过Composio集成去调用Gmail API；甚至说“在项目目录里找找所有包含‘TODO’的代码文件”，它也能调用Bash和Grep工具去执行。这一切都通过一个你熟悉的聊天界面完成，体验非常自然。我最初是被其“ClawdBot”和“OpenClaw”系列的关键词吸引，深入后发现，它解决了AI应用落地的一个核心痛点：如何让AI能力无缝、安全地融入你已有的工作流和通信习惯。

2. 核心架构与设计思路拆解

在动手部署之前，理解Secure OpenClaw的架构设计，能帮你更好地驾驭它，并在出问题时快速定位。整个系统可以清晰地分为三层：通信层、代理层和工具层。

2.1 通信层：消息平台的统一抽象

这是项目与用户交互的入口。项目没有重新发明轮子去连接各个IM平台，而是巧妙地使用了各平台成熟的开源库进行封装，例如用Baileys连接WhatsApp，用node-telegram-bot-api连接Telegram。adapters/目录下的每个文件（如whatsapp.js,telegram.js）就是一个适配器，它们都继承自base.js中定义的基类。这种设计带来了两个巨大好处：

1. 平台无关性：增加一个新的消息平台（比如Discord），你只需要按照接口规范实现一个新的适配器，核心的AI逻辑完全不用动。
2. 统一消息处理：无论消息来自哪个平台，都会被标准化成内部统一的格式（发送者ID、消息内容、平台类型等），再交给后端的AI代理处理。这极大地简化了后续逻辑。

注意：这里隐藏了一个关键的安全设计。每个适配器的配置中都有allowedDMs（允许的私聊对象）和allowedGroups（允许的群组）列表。默认配置是严格的白名单机制，来自非白名单联系人的消息会被直接丢弃，不会触发任何AI响应。这是将个人AI助理部署在公网时必须具备的基础安全意识。

2.2 代理层：AI大脑与记忆中枢

这是项目的核心，位于agent/目录。claude-agent.js（或对应的opencode代理）是整个系统的“大脑”。它不仅仅是一个简单的聊天接口封装，而是集成了几个关键子系统：

• 会话管理：维护与用户的对话上下文，通过maxTurns等参数控制上下文长度，防止无限增长。
• 工具调用路由：当AI模型决定要使用一个工具（比如“发送邮件”）时，代理负责解析这个请求，将其分发给正确的工具处理器，并处理工具返回的结果。
• 记忆系统：这是我认为设计最精妙的部分。记忆不是存在某个黑盒数据库里，而是以Markdown文件的形式，持久化存储在本地目录~/secure-openclaw/下。MEMORY.md存储长期偏好和关键信息，memory/YYYY-MM-DD.md则像日记一样记录每日交互。AI在需要时会读取这些文件来获取上下文，并在你明确要求时写入新记忆。这种基于文件系统的记忆，透明、可追溯、且易于备份迁移。
• 调度系统：通过集成cron工具，代理能够理解“每隔一段时间”或“在特定时间点”执行任务的自然语言指令，并将其转换为真正的定时任务，存储在cron-jobs.json中。

runner.js文件则扮演了“调度员”的角色，它管理着一个消息队列，确保来自不同平台的消息被有序、稳定地处理，避免并发冲突。

2.3 工具层与集成：能力的无限扩展

这是项目从“智能聊天”迈向“智能执行”的关键。工具层又分为两部分：

1. 本地系统工具：在config.js的agent.allowedTools中定义，如Bash（执行Shell命令）、Read/Write/Edit（文件操作）、Glob（文件查找）。这些工具让AI具备了直接操作你部署环境的能力，功能强大但也需谨慎授权。
2. 外部应用集成：通过Composio实现。这是项目的“杀手级”特性。Composio作为一个工具路由平台，预先集成了500多个常见应用的API（如Gmail, Slack, GitHub, Notion）。你的AI助理无需知道OAuth2.0的细节，只需要通过Composio声明“我想用Gmail发邮件”，Composio就会提供一个授权链接，你点一下完成授权，之后AI就能直接使用了。这相当于为你的AI助理瞬间接上了整个互联网的工作流。

三层之间的协作流程可以概括为：消息平台适配器接收用户输入 -> 标准化后送入代理的消息队列 -> AI模型根据对话历史和记忆生成思考，决定是否需要调用工具 -> 如需调用，则根据工具类型路由到本地工具或通过Composio调用外部API -> 工具执行结果返回给AI模型 -> AI生成最终回复，经由适配器发回原消息平台。

3. 环境准备与核心配置详解

理解了架构，我们就可以开始动手了。部署Secure OpenClaw有两种主要模式：本地开发运行和远程服务器部署。我强烈建议先从本地模式开始，熟悉所有组件和流程后，再迁移到远程服务器实现24x7运行。

3.1 本地环境快速搭建

本地运行适合测试和开发，所有组件都跑在你的电脑上。

第一步：基础环境与项目克隆确保你的系统已安装Node.js 18或更高版本。然后克隆项目并安装依赖：

git clone https://github.com/ComposioHQ/secure-openclaw.git cd secure-openclaw npm install

这一步很简单，如果npm install遇到网络问题，可以尝试配置npm镜像源。

第二步：AI提供商二选一（或全都要）项目支持Claude和Opencode两种AI后端。Claude效果稳定但需要API Key；Opencode开源可自托管，模型选择多。

• 安装Claude Code（Claude提供商必需）：

  npm install -g @anthropic-ai/claude-code

  安装后，在终端运行claude命令，会打开浏览器引导你完成OAuth登录认证。这步是为了在本地建立凭证。请注意：在后续的远程Docker部署中，认证方式不同，是通过环境变量ANTHROPIC_API_KEY，无需此交互步骤。
• 安装Opencode（Opencode提供商必需）：

  curl -fsSL https://opencode.ai/install | bash

  安装后，Opencode会在后台运行一个本地服务。你可以通过opencode --help查看命令。

第三步：获取并配置核心API密钥这是让项目“活”起来的关键。

1. Anthropic API Key：访问 Anthropic控制台 ，创建API Key。然后在终端设置环境变量：

   export ANTHROPIC_API_KEY=sk-ant-xxxxxxxxxxxx

2. Composio API Key：这是解锁500+应用集成的钥匙。按照项目说明安装Composio CLI并登录：

   curl -fsSL https://composio.dev/install | bash composio login composio whoami # 此命令会显示你的API Key export COMPOSIO_API_KEY=your_composio_key_here

   实操心得：为了永久生效，务必把这两个export命令添加到你的Shell配置文件（~/.zshrc或~/.bashrc）末尾，然后执行source ~/.zshrc。

第四步：首次运行与配置向导运行node cli.js，你会看到一个简洁的交互菜单。我建议先选择3) Setup adapters运行设置向导，它会以问答形式引导你配置想要启用的消息平台（如WhatsApp），并自动更新config.js文件。你也可以直接编辑config.js，结构非常直观。

3.2 配置文件深度解析

config.js是整个项目的心脏，理解每个配置项的意义至关重要。

// config.js 核心配置片段解读 { agentId: 'secure-openclaw', // 代理标识，用于会话隔离，多实例部署时可区分 // 消息平台配置 whatsapp: { enabled: true, allowedDMs: ['+8612345678900'], // 允许私聊的号码，['*']代表允许所有人 allowedGroups: ['123456789-123456@g.us'], // 允许的群组ID，['*']允许所有群 respondToMentionsOnly: true // 在群聊中，仅当被@时才回复，避免刷屏 }, telegram: { enabled: false, token: 'YOUR_BOT_TOKEN' }, // ... 其他平台类似 // AI代理核心配置 agent: { workspace: '~/secure-openclaw', // 工作空间和记忆存储路径 maxTurns: 100, // 对话轮次上限，防止上下文过长 allowedTools: ['Read', 'Write', 'Edit', 'Bash', 'Glob', 'Grep'], // 允许使用的本地工具 provider: 'claude', // 'claude' 或 'opencode' // Opencode专属配置 opencode: { model: 'opencode/gpt-5-nano', // 使用的模型 hostname: '127.0.0.1', port: 4096 } }, }

安全配置要点：

• allowedDMs/allowedGroups：切勿在生产环境轻易设置为['*']。尤其是将服务暴露在公网时，这可能导致你的AI助理被陌生人随意调用，消耗你的API额度，甚至带来安全风险。务必配置为你自己或可信联系人的ID。
• allowedTools：Bash工具权限极高。如果你不完全信任AI模型的行为，或部署在存有关键数据的服务器上，可以考虑从列表中移除Bash，仅保留文件读写等相对安全的工具。
• respondToMentionsOnly：在群组中启用此选项是良好的“礼仪”设置，能有效避免机器人对群内所有聊天都进行响应，造成干扰。

4. 多平台接入实战与权限管理

配置好后，就可以启动网关，连接你的消息平台了。运行node cli.js选择2) Start gateway，或直接运行node cli.js start。

4.1 WhatsApp接入详解

WhatsApp的接入体验最接近官方客户端，通过扫描二维码链接。

1. 启动网关后，终端会显示一个二维码（ASCII艺术形式），并提示你访问http://localhost:4096/qr获取更清晰的二维码图片。
2. 打开手机WhatsApp，进入设置 -> 已链接的设备 -> 链接设备。
3. 扫描终端显示的二维码或网页上的二维码。
4. 链接成功后，终端会显示“WhatsApp authenticated!”。会话信息会保存在项目根目录的auth_whatsapp/文件夹中。下次启动时无需重新扫描，除非你删除了这个文件夹。

踩坑记录：有时二维码可能不显示或扫描失败。首先检查网络，确保你的服务器（或本地电脑）IP可被手机访问（本地运行时就是localhost，没问题）。如果多次失败，可以尝试删除auth_whatsapp/目录并重启网关，强制重新进行认证流程。这通常能解决大部分会话异常问题。

4.2 Telegram Bot接入

Telegram的接入需要先创建一个Bot。

1. 在Telegram中搜索@BotFather，发送/newbot指令，按提示设置名字和用户名，最终你会获得一个形如1234567890:ABCdefGhIJKlmNoPQRsTUVwxyZ的token。
2. 在config.js中，将telegram.enabled设为true，并填入获得的token。
3. 重启网关。然后，在Telegram中找到你刚创建的Bot，发送/start命令激活它。
4. 现在，你就可以像跟好友聊天一样，直接给这个Bot发消息了。Bot的回复就是你的AI助理的回复。

权限管理实践：你可以在allowedDMs里设置只允许你自己的Telegram User ID私聊Bot。获取你的User ID可以通过给@userinfobot这个Bot发送任意消息。这样，即使别人知道了你的Bot用户名，也无法私聊使用它。

4.3 Signal与iMessage接入要点

• Signal：依赖signal-cli这个命令行工具。你需要先在一个真实的手机号上注册Signal（这个项目就是模拟一个Signal客户端）。过程稍显复杂，涉及注册、验证等步骤，且需要保持signal-cli的运行环境。适合对Signal有强需求且不怕折腾的用户。
• iMessage：仅限macOS。需要安装imsgCLI工具（可通过Homebrew安装）。它直接读取和写入macOS系统自带的“信息”App数据库。这意味着，AI助理将出现在你的iMessage对话列表中，可以与你的Apple ID绑定的任何iMessage联系人交互。注意隐私：确保你理解并信任此工具访问你的所有iMessage历史。

4.4 工具调用审批机制

这是一个至关重要的安全特性。在config.js中，权限模式默认为default，意味着AI在使用某些工具（尤其是Bash和通过Composio调用外部API的敏感操作）前，需要你的明确批准。

• 在终端聊天中：当AI尝试调用一个需要批准的工具时，对话会暂停，终端会打印出工具名称和参数，并等待你输入y（同意）或n（拒绝）。
• 在消息平台上：AI会给你发送一条询问消息，例如：“Claude想要使用‘Gmail: Send Email’工具。回复Y允许，N拒绝。”你只需在聊天中回复Y或N即可。

这个机制确保了AI不会在你不知情的情况下执行潜在的危险或非预期操作。审批请求有2分钟的超时时间，超时未响应则视为拒绝。

5. 远程服务器部署：实现24x7在线

要让助理真正全天候待命，部署到云服务器是必由之路。项目提供了完善的Docker支持，让部署变得异常简单。我以最推荐的DigitalOcean为例，详细走一遍流程。

5.1 服务器初始化与基础配置

1. 创建Droplet：在DigitalOcean控制台，选择创建Ubuntu 24.04 LTS系统的Droplet，最低配置（1GB内存，25GB SSD，$6/月）完全足够。创建时建议设置SSH密钥登录，比密码更安全。记下分配给你的公网IP。
2. SSH登录并配置Swap：由于后续Docker构建过程可能超过1GB内存，我们先配置一个2GB的Swap分区。

   ssh root@你的服务器IP # 创建Swap文件 fallocate -l 2G /swapfile chmod 600 /swapfile mkswap /swapfile swapon /swapfile # 永久生效 echo '/swapfile none swap sw 0 0' >> /etc/fstab

3. 安装Docker和Docker Compose：

   curl -fsSL https://get.docker.com | sh

   安装后，可以运行docker --version和docker compose version验证。

5.2 项目部署与持久化配置

1. 克隆项目：在服务器上克隆你的项目仓库。如果是私有仓库，需要在URL中嵌入Personal Access Token。

   git clone https://github.com/你的用户名/secure-openclaw.git cd secure-openclaw

2. 配置环境变量：复制环境变量模板并编辑。

   cp .env.example .env nano .env

   在.env文件中，最关键的是设置好你的ANTHROPIC_API_KEY和COMPOSIO_API_KEY。同时，在这里配置你打算启用的消息平台参数，比如TELEGRAM_BOT_TOKEN。所有在config.js中可配置的项，几乎都可以通过环境变量覆盖，这是12-Factor应用的最佳实践。
3. 启动Docker服务：一键启动。

   docker compose up -d --build

   这个命令会执行以下操作：基于Dockerfile构建镜像（镜像内会安装Claude Code和Opencode）、读取.env配置、以后台模式启动容器。首次构建由于要下载基础镜像和安装依赖，可能需要5-10分钟。
4. 开放防火墙端口：网关默认运行在4096端口，需要允许外部访问。

   ufw allow 4096/tcp

5.3 部署后连接与运维

1. 连接WhatsApp：在浏览器中访问http://你的服务器IP:4096/qr，用手机WhatsApp扫描二维码完成链接。此链接是持久化的，只要服务器上的Docker容器和数据卷不删除，就无需重复扫描。
2. 日常运维命令：
   • docker compose logs -f：实时查看所有容器的日志输出，调试时非常有用。
   • docker compose ps：查看服务运行状态。
   • docker compose down：停止并移除容器。
   • docker compose up -d：重新启动容器。
   • docker compose exec openclaw sh：进入正在运行的容器内部，进行调试或执行命令。
3. 更新项目：当项目有更新时，进入项目目录，执行：

   git pull docker compose up -d --build

   Docker Compose会检测到代码变化，重新构建并启动新容器。

数据持久化说明：在docker-compose.yml中，项目已经配置了卷映射，将容器内的/home/claw/secure-openclaw（工作空间和记忆）和/app/auth_whatsapp（WhatsApp认证信息）目录映射到了宿主机的对应目录。因此，即使容器销毁重建，你的记忆和会话也不会丢失。

6. 高级功能：记忆、调度与集成应用

6.1 记忆系统的使用与维护

记忆系统是让AI助理显得“有连续性”的关键。它不是魔法，而是一个基于文件的、结构化的存储。

• 如何让AI记住东西：你需要明确地指示它。例如：“记住一下，我更喜欢在下午处理邮件。”或者“把我对项目X的偏好记到长期记忆里。”AI会在MEMORY.md中创建或更新相应的条目。
• 如何查询记忆：在聊天中，可以使用内置命令。输入/memory可以查看记忆摘要；/memory list列出所有记忆文件；/memory search 项目X可以搜索包含特定关键词的记忆。
• 手动维护：因为记忆就是Markdown文件，你可以直接用文本编辑器打开~/secure-openclaw/MEMORY.md或memory/目录下的文件进行查看、编辑或清理。这种透明性给了你完全的控制权。

6.2 定时任务与提醒

调度功能非常实用。你可以用自然语言创建定时任务：

• “每隔一小时提醒我起来活动一下。” -> AI会创建一个cron表达式为0 * * * *的定时任务。
• “每周一早上9点给我发送本周待办事项。” -> cron表达式为0 9 * * 1。
• “30分钟后提醒我关烤箱。” -> AI会创建一个一次性延迟任务。

所有计划中的任务都保存在~/.secure-openclaw/cron-jobs.json中。重要提示：定时任务的执行依赖于网关进程持续运行。如果你停止了网关服务（docker compose down或本地进程退出），定时任务将不会触发，直到服务重新启动。

6.3 通过Composio连接外部世界

这是项目最强大的扩展能力。首次让AI助理使用一个新应用（比如Gmail）时，流程如下：

1. 你发出指令：“用我的Gmail给张三发一封邮件，内容是关于明天会议的。”
2. AI识别出需要调用Composio的Gmail工具，但由于未授权，它会通过Composio生成一个OAuth授权链接，并发送给你（在消息平台上是一条可点击的消息）。
3. 你点击链接，跳转到Google的授权页面，登录并同意授权。
4. 授权完成后，Composio会存储一个访问令牌（token），并与你的AI助理会话关联。
5. 此后，AI就可以在需要时，直接使用这个令牌来代表你调用Gmail API发送邮件了。

管理授权：你可以通过Composio的Web控制台或CLI查看和管理所有已授权的连接，随时可以撤销某个应用的访问权限。这保证了即使AI助理被滥用，你也可以快速切断它对特定服务的访问。

7. 故障排查与性能优化

即使按照步骤操作，也难免会遇到问题。这里整理了一份常见问题速查表，覆盖了从部署到使用的各个阶段。

性能优化建议：

1. 模型选择：对于日常聊天和简单任务，Claude Haiku或Opencode的轻量级模型响应更快、成本更低。仅在需要复杂推理时切换至Opus等大模型。
2. 上下文管理：关注maxTurns配置。过长的对话历史会消耗更多Token，增加成本和延迟。对于长期对话，依赖记忆系统而非冗长的上下文是更优策略。
3. 工具审批超时：默认2分钟超时是合理的。如果你在处理复杂任务时经常超时，可以考虑在代码中适当延长超时时间（需修改gateway.js或相关适配器中的approvalTimeout参数），但不建议禁用审批。

8. 自定义扩展与进阶玩法

当你熟悉了基本用法后，可以尝试一些进阶操作，让这个助理更贴合你的个人需求。

添加自定义工具：项目的工具系统是可扩展的。你可以在tools/目录下创建新的工具文件。一个工具本质上是一个函数，它接收AI模型传来的参数，执行一些操作（可以是调用本地脚本、访问某个内部API等），然后返回结果。你需要按照base-provider.js中定义的接口规范来编写工具描述（名称、描述、参数schema）。编写完成后，在config.js的allowedTools数组中加入你的新工具名，重启网关即可。

集成内部系统：这是企业级应用的潜力所在。假设你公司内部有一个查询订单状态的HTTP API。你可以编写一个自定义工具来调用这个API。然后，你的团队成员就可以直接在WhatsApp群里@机器人问：“帮我查一下订单#12345的状态”，机器人就能调用内部工具并返回结果。这极大地简化了工作流程。

多助理/多身份：通过修改agentId和配置不同的工作空间路径，你可以在同一台服务器上运行多个独立的网关实例，每个实例连接不同的消息平台或服务于不同的用途（例如，一个用于工作，一个用于个人生活）。配合Docker Compose的多个服务定义，可以轻松实现这一点。

日志与监控：对于生产环境，建议将Docker容器的日志导出到集中式日志系统（如ELK Stack或Loki）。同时，可以编写简单的健康检查脚本，定期访问网关的/根路径（返回OK），以确保服务存活。

部署并使用了Secure OpenClaw几周后，它已经从一个新奇玩具变成了我工作流中一个安静而可靠的伙伴。最大的体会是，真正的生产力工具不在于功能有多炫酷，而在于它能否在你需要的时候，以最自然的方式出现并解决问题。这个项目成功地将强大的AI能力“降解”到了最简单的短信对话层面，这种低门槛的交互方式，才是技术普惠的关键。如果你也打算部署，我的建议是：从小处着手，先启用一两个最常用的平台和工具，让它帮你处理一些固定的、重复的查询或任务（比如“今天天气如何”、“我的日程有什么安排”）。当你习惯了这种交互模式，再逐步探索更复杂的自动化和集成，你会发现自己正在亲手塑造一个越来越懂你的数字助手。