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中定义的基类。这种设计带来了两个巨大好处平台无关性增加一个新的消息平台比如Discord你只需要按照接口规范实现一个新的适配器核心的AI逻辑完全不用动。统一消息处理无论消息来自哪个平台都会被标准化成内部统一的格式发送者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 工具层与集成能力的无限扩展这是项目从“智能聊天”迈向“智能执行”的关键。工具层又分为两部分本地系统工具在config.js的agent.allowedTools中定义如Bash执行Shell命令、Read/Write/Edit文件操作、Glob文件查找。这些工具让AI具备了直接操作你部署环境的能力功能强大但也需谨慎授权。外部应用集成通过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 KeyOpencode开源可自托管模型选择多。安装Claude CodeClaude提供商必需npm install -g anthropic-ai/claude-code安装后在终端运行claude命令会打开浏览器引导你完成OAuth登录认证。这步是为了在本地建立凭证。请注意在后续的远程Docker部署中认证方式不同是通过环境变量ANTHROPIC_API_KEY无需此交互步骤。安装OpencodeOpencode提供商必需curl -fsSL https://opencode.ai/install | bash安装后Opencode会在后台运行一个本地服务。你可以通过opencode --help查看命令。第三步获取并配置核心API密钥这是让项目“活”起来的关键。Anthropic API Key访问 Anthropic控制台 创建API Key。然后在终端设置环境变量export ANTHROPIC_API_KEYsk-ant-xxxxxxxxxxxxComposio API Key这是解锁500应用集成的钥匙。按照项目说明安装Composio CLI并登录curl -fsSL https://composio.dev/install | bash composio login composio whoami # 此命令会显示你的API Key export COMPOSIO_API_KEYyour_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-123456g.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。allowedToolsBash工具权限极高。如果你不完全信任AI模型的行为或部署在存有关键数据的服务器上可以考虑从列表中移除Bash仅保留文件读写等相对安全的工具。respondToMentionsOnly在群组中启用此选项是良好的“礼仪”设置能有效避免机器人对群内所有聊天都进行响应造成干扰。4. 多平台接入实战与权限管理配置好后就可以启动网关连接你的消息平台了。运行node cli.js选择2) Start gateway或直接运行node cli.js start。4.1 WhatsApp接入详解WhatsApp的接入体验最接近官方客户端通过扫描二维码链接。启动网关后终端会显示一个二维码ASCII艺术形式并提示你访问http://localhost:4096/qr获取更清晰的二维码图片。打开手机WhatsApp进入设置 - 已链接的设备 - 链接设备。扫描终端显示的二维码或网页上的二维码。链接成功后终端会显示“WhatsApp authenticated!”。会话信息会保存在项目根目录的auth_whatsapp/文件夹中。下次启动时无需重新扫描除非你删除了这个文件夹。踩坑记录有时二维码可能不显示或扫描失败。首先检查网络确保你的服务器或本地电脑IP可被手机访问本地运行时就是localhost没问题。如果多次失败可以尝试删除auth_whatsapp/目录并重启网关强制重新进行认证流程。这通常能解决大部分会话异常问题。4.2 Telegram Bot接入Telegram的接入需要先创建一个Bot。在Telegram中搜索BotFather发送/newbot指令按提示设置名字和用户名最终你会获得一个形如1234567890:ABCdefGhIJKlmNoPQRsTUVwxyZ的token。在config.js中将telegram.enabled设为true并填入获得的token。重启网关。然后在Telegram中找到你刚创建的Bot发送/start命令激活它。现在你就可以像跟好友聊天一样直接给这个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 服务器初始化与基础配置创建Droplet在DigitalOcean控制台选择创建Ubuntu 24.04 LTS系统的Droplet最低配置1GB内存25GB SSD$6/月完全足够。创建时建议设置SSH密钥登录比密码更安全。记下分配给你的公网IP。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安装Docker和Docker Composecurl -fsSL https://get.docker.com | sh安装后可以运行docker --version和docker compose version验证。5.2 项目部署与持久化配置克隆项目在服务器上克隆你的项目仓库。如果是私有仓库需要在URL中嵌入Personal Access Token。git clone https://github.com/你的用户名/secure-openclaw.git cd secure-openclaw配置环境变量复制环境变量模板并编辑。cp .env.example .env nano .env在.env文件中最关键的是设置好你的ANTHROPIC_API_KEY和COMPOSIO_API_KEY。同时在这里配置你打算启用的消息平台参数比如TELEGRAM_BOT_TOKEN。所有在config.js中可配置的项几乎都可以通过环境变量覆盖这是12-Factor应用的最佳实践。启动Docker服务一键启动。docker compose up -d --build这个命令会执行以下操作基于Dockerfile构建镜像镜像内会安装Claude Code和Opencode、读取.env配置、以后台模式启动容器。首次构建由于要下载基础镜像和安装依赖可能需要5-10分钟。开放防火墙端口网关默认运行在4096端口需要允许外部访问。ufw allow 4096/tcp5.3 部署后连接与运维连接WhatsApp在浏览器中访问http://你的服务器IP:4096/qr用手机WhatsApp扫描二维码完成链接。此链接是持久化的只要服务器上的Docker容器和数据卷不删除就无需重复扫描。日常运维命令docker compose logs -f实时查看所有容器的日志输出调试时非常有用。docker compose ps查看服务运行状态。docker compose down停止并移除容器。docker compose up -d重新启动容器。docker compose exec openclaw sh进入正在运行的容器内部进行调试或执行命令。更新项目当项目有更新时进入项目目录执行git pull docker compose up -d --buildDocker Compose会检测到代码变化重新构建并启动新容器。数据持久化说明在docker-compose.yml中项目已经配置了卷映射将容器内的/home/claw/secure-openclaw工作空间和记忆和/app/auth_whatsappWhatsApp认证信息目录映射到了宿主机的对应目录。因此即使容器销毁重建你的记忆和会话也不会丢失。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时流程如下你发出指令“用我的Gmail给张三发一封邮件内容是关于明天会议的。”AI识别出需要调用Composio的Gmail工具但由于未授权它会通过Composio生成一个OAuth授权链接并发送给你在消息平台上是一条可点击的消息。你点击链接跳转到Google的授权页面登录并同意授权。授权完成后Composio会存储一个访问令牌token并与你的AI助理会话关联。此后AI就可以在需要时直接使用这个令牌来代表你调用Gmail API发送邮件了。管理授权你可以通过Composio的Web控制台或CLI查看和管理所有已授权的连接随时可以撤销某个应用的访问权限。这保证了即使AI助理被滥用你也可以快速切断它对特定服务的访问。7. 故障排查与性能优化即使按照步骤操作也难免会遇到问题。这里整理了一份常见问题速查表覆盖了从部署到使用的各个阶段。问题现象可能原因排查步骤与解决方案启动时报错ANTHROPIC_API_KEY not set环境变量未正确设置。1. 检查.env文件是否存在且KEY填写正确。2. 在服务器上运行 docker compose exec openclaw envDocker构建过程中被杀死 (Exit Code 137)服务器内存不足。这是部署到小内存VPS最常见的问题。确保已按照前述步骤正确创建了2GB的Swap空间。运行free -h查看Swap是否已启用。无法访问http://IP:4096/qr防火墙未开放端口或服务未启动。1. 运行ufw allow 4096开放端口。2. 运行docker compose logs -f查看网关是否成功启动并监听在4096端口。3. 确认你访问的是服务器的公网IP而非内网IP。WhatsApp二维码页面一直显示“Waiting...”网关服务尚未就绪或WhatsApp适配器初始化失败。查看Docker日志 (docker compose logs -f openclaw)。等待直到看到[Gateway] Ready和[WhatsApp] Authenticated or QR generated类似的日志信息。如果长时间无响应检查.env中WhatsApp配置是否正确。Telegram Bot不回复消息Token错误或未发送/start命令。1. 确认config.js或.env中的TELEGRAM_BOT_TOKEN无误。2. 在Telegram中找到你的Bot首先发送/start命令来激活会话。3. 检查Docker日志看是否有收到消息的日志。AI回复缓慢或无响应API网络延迟、模型负载高或本地工具执行耗时。1. 如果是Claude检查Anthropic API状态页。2. 尝试在聊天中使用/model命令终端模式切换到一个更轻量的模型如Haiku。3. 检查是否在等待工具审批。在消息平台查看是否有待批准的询问。记忆似乎没有保存工作空间目录权限问题或路径错误。1. 本地运行检查~/secure-openclaw/目录是否存在且可写。2. Docker运行进入容器 (docker compose exec openclaw sh)检查/home/claw/secure-openclaw/目录下的文件。确认启动时配置的卷映射正确。Composio集成授权失败网络问题或Composio账户配置问题。1. 运行composio whoami确认API Key有效且登录状态正常。2. 尝试在浏览器中手动打开AI提供的授权链接看是否能正常跳转到目标应用如Google的授权页面。3. 检查Docker/服务器防火墙是否阻止了与Composio API服务器的连接。性能优化建议模型选择对于日常聊天和简单任务Claude Haiku或Opencode的轻量级模型响应更快、成本更低。仅在需要复杂推理时切换至Opus等大模型。上下文管理关注maxTurns配置。过长的对话历史会消耗更多Token增加成本和延迟。对于长期对话依赖记忆系统而非冗长的上下文是更优策略。工具审批超时默认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能力“降解”到了最简单的短信对话层面这种低门槛的交互方式才是技术普惠的关键。如果你也打算部署我的建议是从小处着手先启用一两个最常用的平台和工具让它帮你处理一些固定的、重复的查询或任务比如“今天天气如何”、“我的日程有什么安排”。当你习惯了这种交互模式再逐步探索更复杂的自动化和集成你会发现自己正在亲手塑造一个越来越懂你的数字助手。