1. 项目概述：构建一个安全的个人AI助手服务器

如果你和我一样，对把个人AI助手部署在第三方云服务上总有些顾虑，无论是数据隐私、长期成本，还是对功能定制的限制，那么自己动手在单台VPS上搭建一个完全受控的环境，会是一个极具吸引力的选择。今天要聊的这个 openclaw-deploy 项目，就是一个为个人或小团队设计的、开箱即用的AI助手部署方案。它基于开源的OpenClaw项目，但核心价值在于提供了一套“加固”的生产级部署模板，把安全、可靠和易维护性放在了首位。

简单来说，这个项目帮你把OpenClaw——一个支持Telegram、WhatsApp等多渠道，并能调用各种工具（如搜索、日历、邮件）的AI助手——打包进一个经过安全加固的Docker容器里，通过Docker Compose一键部署到你的VPS上。你得到的不只是一个能聊天的机器人，而是一个拥有执行护栏、自动备份、网络隔离和资源限制的私有化AI系统。它特别适合开发者、技术爱好者和对自动化有较高需求的个人用户，用来处理日常查询、管理日程、筛选邮件，甚至控制音乐播放。接下来，我会带你深入拆解这个项目的设计思路、每一步的实操细节，并分享我在部署和调优过程中积累的经验与踩过的坑。

2. 核心架构与安全设计解析

2.1 为什么选择“单VPS + Docker Compose”模式

在云原生和Kubernetes大行其道的今天，这个项目反其道而行之，采用了最朴素的单VPS搭配Docker Compose的架构。这背后有非常务实的考量。首先， 目标场景是个人使用 ，这意味着并发请求量极低，但对数据隐私和长期运行稳定性要求高。复杂的K8s集群带来的运维开销和潜在故障点，对于个人项目来说是得不偿失的。其次， 成本控制是关键 。一个每月5-7美元的VPS（如Hetzner CX22）就能满足所有需求，而K8s集群的最低成本也要翻好几倍。最后， 简化部署与维护 。Docker Compose的声明式配置让整个服务的启停、更新变得一目了然， Makefile 更是将常用操作封装成简单的命令，极大降低了日常运维的门槛。

这种架构的核心是 “一个定义，随处运行” 。 docker-compose.yml 文件定义了包括OpenClaw网关、Caddy反向代理、Redis会话存储、执行看门狗等所有服务及其关系。只要机器上有Docker，一条 docker compose up -d 就能拉起整个栈。这种极简主义避免了分布式系统的网络复杂性，让开发者能把精力集中在应用逻辑和安全加固上。

2.2 纵深防御：容器与主机的安全加固策略

项目的安全模型可以概括为 “纵深防御” ，即在多个层次设置屏障，即使某一层被突破，还有其他层提供保护。这是它区别于简单Docker化部署的核心。

第一层：容器层面的隔离与降权。 OpenClaw服务运行在一个经过特别加固的容器内。Docker本身提供了命名空间和cgroups的隔离，但项目在此基础上做了更多：

1. 非Root用户运行 ：容器内的应用以普通用户（如 node ）身份运行，而非 root 。这遵循了最小权限原则，即使应用存在漏洞被利用，攻击者获得的权限也受到极大限制。
2. 丢弃Linux能力 ：通过 docker-compose.yml 中的 cap_drop: ALL 配置，容器被剥夺了所有特殊的Linux内核能力（如 NET_ADMIN , SYS_ADMIN ）。这意味着容器内的进程无法执行挂载文件系统、配置网络接口等特权操作。
3. 只读根文件系统 ：将容器的根文件系统挂载为只读（ read_only: true ），防止恶意代码或误操作写入或修改系统文件。应用运行所需的可写目录（如 /data , /tmp ）通过 volumes 单独挂载。
4. 资源限制 ：通过 deploy.resources.limits 设置CPU和内存的上限。这不仅能防止单个容器耗尽主机资源，更是执行看门狗（Guardrail）发挥作用的基础——当资源使用异常飙升时，可能意味着出现了失控的循环或攻击。

第二层：网络层面的隔离。 Docker Compose默认会创建一个独立的桥接网络。项目在此基础上，将Redis这类仅内部访问的服务配置为仅在此网络内可达（ internal: true ），而Caddy作为边缘网关，则同时连接内部网络和主机网络，对外暴露HTTPS端口。这样，Redis存储的用户会话和临时数据完全与公网隔离，即使Caddy存在漏洞，攻击者也无法直接访问到Redis。

第三层：主机层面的加固。 项目提供的 scripts/provision.sh 脚本，在首次部署时会自动对Ubuntu VPS进行安全加固：

• 配置UFW防火墙 ：默认只开放SSH（22端口）和HTTP/HTTPS（80, 443端口），屏蔽其他所有不必要的入站连接。
• 强制SSH密钥认证 ：彻底禁用密码登录，这是防止暴力破解最有效的手段。 这里有一个至关重要的前置步骤 ：你必须在运行脚本前，通过 ssh-copy-id 将你的公钥上传到VPS，否则脚本运行后你将永远无法登录。
• 安装Fail2ban ：监控系统日志，自动封禁多次尝试失败（如SSH密码错误）的IP地址。
• 启用无人值守安全更新 ：确保系统软件包能自动安装安全补丁。

这种多层防御的设计，其核心思想是承认OpenClaw作为一个能执行代码的AI助手，本身存在一定的风险（即“执行风险”）。项目的目标不是消除这个风险（这不可能），而是将其“容纳”起来，确保即使AI助手的行为出现偏差，也无法危及宿主机的安全或造成不可控的损失。

3. 从零开始的完整部署实操指南

3.1 前期准备：资源与配置要点

在敲下第一条部署命令前，需要准备好以下几样东西，缺一不可：

1. VPS与域名 ：推荐使用Hetzner、DigitalOcean、Linode或Vultr等提供商，选择最基础的套餐（如1核2G内存）即可。务必选择 Ubuntu 24.04 LTS 系统，这是脚本和Docker镜像测试过的环境。同时，你需要一个域名（哪怕是免费的二级域名），并将其A记录指向你的VPS公网IP。Caddy需要这个域名来申请Let‘s Encrypt的HTTPS证书。
2. OpenClaw本地配置 ：这是一个容易被忽略但关键的点。你需要在你的本地开发机上先完成OpenClaw的初始设置，特别是“配对”过程。因为OpenClaw的CLI（命令行工具）和设备（你的本地终端）需要完成一次配对，生成一个密钥。部署脚本会将这个已配对的设备信息同步到服务器。如果你跳过了这一步，部署后会出现“pairing required”的错误，导致网关无法连接。
3. API密钥与令牌 ：
   • Anthropic API Key ：OpenClaw默认使用Claude模型，你需要从Anthropic控制台获取。
   • Telegram Bot Token ：通过Telegram的 @BotFather 创建一个新的机器人，获取token。
   • （可选） Brave Search API Key ：如果你需要网络搜索功能，可以去Brave官网免费申请。

3.2 一键部署与初始化流程

准备好上述资源后，部署过程被 Makefile 封装得极其简单：

# 1. 克隆项目到本地
git clone https://github.com/eratchev/openclaw-deploy.git
cd openclaw-deploy

# 2. 执行一键部署，替换 `user` 和 `your-vps-ip` 为你的实际信息
make deploy HOST=user@your-vps-ip

这个 make deploy 命令背后做了很多事情，理解它们有助于排查问题：

1. 通过SSH连接到你的VPS ，并执行 scripts/provision.sh 脚本。该脚本会安装Docker、Docker Compose，并进行前述的主机安全加固。
2. 交互式配置 ：脚本会提示你输入必要的环境变量，如 DOMAIN （你的域名）、 TELEGRAM_TOKEN 、 ANTHROPIC_API_KEY 等。这些值会被写入VPS上项目目录下的 .env 文件。
3. 启动服务 ：配置完成后，脚本会在VPS上执行 docker compose up -d ，拉取镜像并启动所有容器。
4. 引导OpenClaw配置 ：一个定制的入口点（entrypoint）脚本会在容器首次运行时，读取 .env 文件中的变量，并自动调用 openclaw config set 命令来生成 openclaw.json 配置文件。

实操心得： .env 文件的管理 项目根目录下的 .env.example 文件是所有可用环境变量的模板。建议在本地也保留一份 .env 文件（不要提交到Git），用于记录你的配置。 make deploy 会在远程生成它，但后续手动修改或添加变量（如备份配置、日历集成）时，你可能需要直接编辑VPS上的这个文件。可以使用 make ssh 命令快速登录到VPS进行操作。

部署完成后，你可以通过 make doctor 命令检查服务健康状态。如果一切正常，现在就可以给你的Telegram机器人发送消息，开始对话了。

3.3 可选功能集成：日历、邮件与语音

基础栈运行起来后，你可以按需添加“超能力”。这些集成都是模块化的，通过Docker Compose的“profiles”功能来控制启停。

Google日历集成： 这个功能允许AI助手帮你查看和创建日历事件。实现上，它并非让OpenClaw直接调用Google API，而是通过一个独立的“日历代理”服务（ calendar-proxy ）。这个代理运行在内部网络，OpenClaw通过标准的进程调用（exec）与之通信。代理内部还包含一个策略引擎，会对所有写操作（创建、修改、删除事件）进行冲突检测、工作时间判断等审查，再调用Google API。

设置步骤：

1. 在Google Cloud Console创建一个项目，启用Calendar API，并配置OAuth桌面应用凭据，下载 client_secret.json 。
2. 在本地运行 make setup-gcal CLIENT_SECRET=path/to/client_secret.json 。这个命令会打开浏览器让你授权，然后将加密后的令牌上传到VPS。
3. 在 .env 文件中设置你的时区等信息。
4. 运行 make up-calendar 启动带日历代理的完整服务栈。

Gmail集成： 与日历类似，通过独立的 gmail-proxy 服务实现。除了基本的读、写、搜索邮件，它还有一个 智能通知 功能：当新邮件到达时，代理会调用Claude AI对邮件内容进行评分，如果重要性超过阈值（默认7分），它会主动通过Telegram给你发送摘要。这能有效过滤垃圾邮件和无关通知。

设置流程与日历几乎一致，使用同一个 client_secret.json 即可（需同时启用Gmail API）。启动命令是 make up-mail 。

语音转录集成： 这个功能非常实用，它拦截Telegram机器人收到的语音消息，调用OpenAI的Whisper模型将其转为文字，再交给OpenClaw处理。实现的关键在于， 必须将Telegram机器人设置为Webhook模式 ，而不是默认的长轮询（Long Polling）模式。因为只有Webhook模式下，Telegram的消息才会发送到你指定的端点（ https://your-domain/telegram-webhook ），从而被 voice-proxy 服务拦截并处理。

注意事项：Webhook配置顺序 配置Webhook时，必须先设置 webhookSecret ，再设置 webhookUrl 。因为Telegram在设置URL时会立即发送一个测试请求，其中包含这个secret用于验证。如果顺序反了，验证会失败。项目文档里的命令顺序是正确的，务必遵守。

4. 高级功能与技能扩展

4.1 技能系统与外部工具集成

OpenClaw的强大之处在于其“技能”系统，这些技能本质上是预定义的、可供AI调用的工具集。项目通过 make setup-skills 命令，可以一键在容器内安装运行这些技能所需的命令行工具。

GitHub技能： 安装后，AI可以查询你的PR状态、CI运行结果等。但安装二进制文件只是第一步，还需要在容器内完成 gh auth login 认证。这里有个技巧：直接使用 make ssh 登录VPS，然后执行 sudo docker compose exec -it openclaw gh auth login 。认证状态会保存在容器的 /data 卷中，持久化有效。

Spotify播放控制技能： 这是一个非常酷但设置稍显复杂的技能。它使用一个叫 spogo 的第三方CLI工具，通过模拟浏览器Cookie的方式来控制你的Spotify播放。这意味着它不需要你提供Spotify的正式API密钥，但需要你从已登录的浏览器中提取 sp_dc 和 sp_t 这两个Cookie的值。

踩坑记录：Cookie提取与格式化 文档中给出的Python脚本用于生成正确的JSON格式。这里最容易出错的是Cookie的 domain 和 path 属性必须准确设置为 .spotify.com 和 / 。另外，Cookie的有效期（ expires ）可以设置一个很远的未来日期。生成JSON文件后，通过 scp 上传到VPS，再用 docker compose cp 命令复制到容器内的特定路径。整个过程需要仔细核对每一步的路径和权限。

4.2 工作空间与智能体行为定制

workspace/ 目录是你塑造AI助手个性与能力的核心。这里的Markdown文件在部署时会被注入到系统的提示词（Prompt）中，直接影响AI的行为。

• AGENTS.md / SOUL.md / POLICY.md ：这些是“宪法”级文件，定义了AI的核心身份、安全策略和操作原则。例如，在 POLICY.md 中，你可以明确规定“未经明确确认，不得执行任何付费操作”或“不得生成具有人身攻击性的内容”。
• USER.md ：这是你的“用户手册”，告诉AI你的偏好、工作习惯、常用联系人等信息。例如，“我通常在北京时间9点到18点工作”、“向我汇报时优先使用Telegram”。
• COMMANDS.md ：定义全局可用的命令列表。这对于在群组中使用时尤其有用，用户可以快速了解能@机器人做什么。
• MEMORY.md ：这是AI自己维护的长期记忆。一个关键细节是： 只有在你与AI的私聊（DM）中， MEMORY.md 才会被加载 。在群聊中，AI是没有这份长期记忆的。这是出于隐私和上下文管理的考虑。此外，这个文件在首次部署后就不会被覆盖，这意味着AI可以在其中积累和修改信息。

修改这些文件后，运行 make deploy-workspace 即可将更新同步到服务器并重启服务生效。这是实现个性化AI助手最强大的方式。

5. 运维、监控与故障排查实录

5.1 日常运维与自动化备份

项目通过 Makefile 提供了极简的运维命令：

• make logs ：查看所有容器的实时日志。
• make push ：在本地代码更新并 git push 后，在VPS上拉取最新代码，重建并重启容器。这是无缝升级的关键。
• make update ：更新项目本身（如Docker镜像版本、脚本）。

自动化备份是生产部署的基石。 项目集成了每日定时备份到Hetzner对象存储的功能。设置步骤如下：

1. 在Hetzner控制台创建Bucket并生成S3兼容的访问密钥。
2. 在 .env 文件中配置 BACKUP_S3_ENDPOINT 、 BACKUP_S3_BUCKET 、 BACKUP_S3_ACCESS_KEY 等变量。
3. 在VPS上运行 sudo bash scripts/install-backup-cron.sh 安装定时任务。

备份脚本会打包 /data 卷（包含所有配置、会话历史和认证令牌），加密后上传。默认保留7天的备份，更早的会自动清理。你也可以随时手动执行 make backup-remote 。

5.2 执行看门狗：最后的防线

这是本项目在安全设计上的点睛之笔。OpenClaw本身很强大，但也意味着它可能被诱导执行消耗大量令牌（费用）的循环，或滥用工具。项目在容器内运行了一个Python“看门狗”进程，它持续监控OpenClaw的会话，并强制执行以下限制：

• 最大工具调用次数 ：防止无限循环调用某个工具。
• 最大LLM调用次数 ：控制单次会话的令牌消耗上限。
• 最长会话时间 ：避免会话无期限挂起。
• 最长空闲时间 ：清理不活跃的会话。

当任一限制被触发，看门狗会 强制终止OpenClaw进程 。由于Docker Compose配置了 restart: always ，容器会自动重启，从而重置所有会话。这是一种“熔断”机制，虽然粗暴，但能有效防止因提示词注入或模型逻辑错误导致的资源滥用。你可以在 docs/execution-guardrails.md 中调整这些限制的阈值。

5.3 常见问题与排查技巧

在实际部署和运行中，我遇到了几个典型问题，以下是排查思路：

问题一：部署后，容器不断重启，日志显示 gateway closed (1008): pairing required 。

• 原因 ：这通常是因为OpenClaw的配对设备信息是在macOS（ darwin ）上生成的，而服务器是Linux容器。网关会校验客户端平台，不匹配则拒绝连接。
• 解决 ：按照文档，进入容器内部，手动修改 /home/node/.openclaw/devices/paired.json 文件，将 cli 设备的 platform 字段从 darwin 改为 linux 。同时清空 pending.json 文件。修改后重启容器即可。

问题二：Caddy服务启动失败，报错 unrecognized global option: reverse_proxy 。

• 原因 ：Caddy的配置中使用了环境变量 {$DOMAIN} ，但如果Caddy服务没有正确加载 .env 文件，这个变量就是空的，导致Caddy将整个站点块误解析为全局配置。
• 解决 ：检查 docker-compose.yml 中 caddy 服务的定义，确保包含了 env_file: - .env 这一行。这是让Caddy读取环境变量的关键。

问题三：语音转录功能不工作，发送语音消息后机器人无反应。

• 排查步骤 ：
  1. 首先运行 docker compose logs voice-proxy 查看语音代理容器的日志。日志会明确显示状态，如 status=error 、 status=no_api_key 或 status=rate_limited 。
  2. 确认 .env 中已正确设置 OPENAI_API_KEY 。
  3. 确认已按照要求，将Telegram机器人切换到了Webhook模式，并且 webhookUrl 指向了正确的域名和 /telegram-webhook 路径。
  4. 检查 voice-proxy 容器是否正常运行（ docker compose ps ）。

问题四： make doctor 检查时，提示某些环境变量缺失。

• 原因 ： .env 文件配置不完整，或者变量名拼写错误。
• 解决 ：使用 make ssh 登录VPS，直接编辑 ~/openclaw-deploy/.env 文件。可以对照 .env.example 文件，补全所有必需的变量（特别是 TELEGRAM_TOKEN , DOMAIN , ANTHROPIC_API_KEY ）。保存后，运行 docker compose restart openclaw 重启服务使配置生效。

通用调试命令 ：

• docker compose logs -f [service-name] ：实时跟踪特定服务的日志。
• docker compose exec openclaw openclaw config get ：查看容器内OpenClaw的完整配置。
• docker compose exec openclaw openclaw logs --json ：以JSON格式查看OpenClaw的应用日志，对于诊断复杂的会话问题很有帮助。

这个项目将复杂的AI系统部署、安全加固和运维工作进行了精心的封装和简化。它体现了一种务实的技术哲学：不追求技术的时髦与复杂，而是聚焦于解决核心问题——让个人能够安全、可靠、低成本地运行一个功能强大的私有AI助手。从网络隔离、资源限制到执行看门狗和自动备份，每一层设计都旨在将风险控制在可接受的范围内。对于有一定技术基础，希望将AI深度融入个人工作流，同时又对数据主权和系统可控性有要求的用户来说，这是一个非常值得投入时间和精力去搭建和定制的解决方案。