1. 项目概述：从ClawdBot到OpenClaw，一个本地优先的AI智能体框架

如果你和我一样，对AI智能体（AI Agent）的潜力感到兴奋，但又对把个人数据、工作流程乃至家庭自动化完全托付给云端服务心存疑虑，那么OpenClaw的出现，可能就是我们一直在等待的答案。它不是一个全新的概念，而是由社区中广为人知的ClawdBot和Moltbot项目演进而来，最终汇聚成一个更强大、更统一的形态。简单来说，OpenClaw是一个开源的、自主运行的AI智能体框架，它的核心哲学是“本地优先”。这意味着，这个能帮你处理消息、执行任务、甚至写代码的AI助手，可以直接运行在你自己的电脑或服务器上，数据不出你的家门，控制权完全在你手中。

想象一下，你可以在Telegram上给AI发一条消息：“检查一下生产环境的日志，看看最近一小时有没有错误激增”，几分钟后，它就能把分析报告和可疑的堆栈跟踪发回给你。或者，在忙碌的早晨，你对着手机说一句“打开客厅的灯并播放新闻”，家里的智能设备就能应声而动。OpenClaw正是为了实现这类场景而设计的。它不是一个单一的应用，而是一个高度可扩展的平台，通过一个名为“技能”（Skills）的插件生态系统，它能接入WhatsApp、Slack、Discord等几乎所有主流通讯工具，也能调用成千上万的自动化能力，从管理日历到控制智能家居，从代码审查到内容分发，几乎没有边界。

我最初接触它的前身ClawdBot时，就被这种“将AI能力私有化部署”的理念所吸引。在尝试了各种云端AI助手后，我越发觉得，一个真正能融入个人工作流和生活的智能体，必须建立在信任和可控的基础上。OpenClaw正是这个理念的工程化实现。它不仅解决了隐私问题，还因为运行在本地或你自己的VPS上，带来了近乎零延迟的响应速度和7x24小时不间断运行的可靠性。接下来，我将结合自己从部署到深度使用的全过程，为你拆解这个框架的设计精髓、实战部署的每一个细节，以及如何让它真正成为你的生产力倍增器。

2. 核心架构与设计哲学解析

2.1 “本地优先”意味着什么？

在AI服务普遍云化的今天，“本地优先”是OpenClaw最旗帜鲜明的设计选择，也是其吸引技术爱好者和隐私敏感用户的核心。但这不仅仅是“把软件装在自己机器上”那么简单。它意味着整个架构的思考起点，是优先考虑数据主权、网络延迟和离线可用性。

从技术实现上看，OpenClaw的“本地”体现在几个层面。首先，它的核心运行时（Core Runtime）和大脑（通常是集成的开源大语言模型，如Llama、Mistral等）可以完全运行在你的硬件上。你与AI的所有对话历史、它执行任务时产生的中间数据、以及通过技能访问的API密钥和令牌，都存储在你指定的本地目录或数据库中，不会未经你的许可流向第三方服务器。其次，它的技能执行引擎也设计为优先在本地环境调用。例如，一个“读取本地文件并总结”的技能，其文件I/O操作直接发生在你的磁盘上；一个“执行Shell命令”的技能，也是在你的系统权限下运行。

这种设计带来了几个直接优势：

1. 极致隐私 ：你的日程、消息、文件乃至智能家居状态，这些高度敏感的信息完全由你掌控。
2. 低延迟响应 ：无需经过互联网往返云端数据中心，指令的解析和执行的反馈几乎是即时的，体验流畅。
3. 定制化与可控 ：你可以自由选择接入哪个大语言模型（本地部署的或特定云API），可以深度审查和修改任何技能代码，也可以完全控制其网络访问权限。
4. 成本确定 ：除了电费和硬件成本，没有按Token数或API调用次数计费的隐形成本，尤其适合高频次使用的场景。

当然，“本地优先”不意味着“只能本地”。OpenClaw的架构非常灵活，它允许你将计算密集型的部分（如大模型推理）部署在性能更强的家庭服务器或云端VPS上，而将轻量级的客户端（如消息桥接）留在你的笔记本电脑或手机上，形成一种混合部署模式，在能力与便利性之间取得平衡。

2.2 技能生态系统：可扩展性的基石

如果说“本地优先”是OpenClaw的骨骼，那么“技能”（Skills）就是它的肌肉和神经。技能本质上是一个个独立的、功能单一的Node.js模块（或Python脚本，通过适配器调用），每个技能都教会了OpenClaw智能体一项新的本领。

OpenClaw官方维护了一个名为ClawHub的中心化技能注册表，社区开发者可以将自己编写的技能发布到这里。目前，ClawHub上已有超过5000个技能，涵盖了从“发送一封邮件”到“在云服务器上部署一个Kubernetes集群”等几乎你能想到的所有自动化场景。技能采用声明式配置，一个典型的技能定义文件（ skill.json ）会描述它的名称、版本、触发命令、所需参数以及执行入口点。

例如，一个简单的“查天气”技能，其元数据可能如下：

{
  "name": "weather",
  "version": "1.0.0",
  "description": "获取指定城市的天气信息",
  "trigger": "weather [city]",
  "parameters": [
    {
      "name": "city",
      "description": "城市名称",
      "required": true
    }
  ],
  "entryPoint": "index.js"
}

当用户在聊天窗口输入“weather 北京”时，OpenClaw核心会解析出命令 weather 和参数 city=北京 ，然后加载并执行对应的 index.js 文件。这个JavaScript文件里，就会包含调用第三方天气API（如OpenWeatherMap）的逻辑，并将结果格式化后返回给用户。

技能生态的强大，使得OpenClaw从一个单纯的聊天机器人，进化成了一个通用的自动化工作流平台。你可以组合多个技能来完成复杂任务。比如，我配置了一个“晨间简报”工作流：每天早上9点，一个定时任务技能触发，它依次调用“获取Github通知”、“查询日历日程”、“抓取科技新闻头条”和“生成摘要”等技能，最后将整合好的报告通过“发送Telegram消息”技能推送到我的手机。

注意 ：技能生态的开放性也是一把双刃剑。从ClawHub安装第三方技能时，务必审查其代码，特别是它声明的系统权限和网络访问需求。一个恶意的技能可能会读取你的本地文件或向外发送数据。建议初期只从官方或信誉极高的开发者那里安装技能，并尽量在沙箱环境或测试机中先进行验证。

2.3 多通道集成与统一消息总线

一个实用的AI助手必须能在你日常使用的通信工具中出现。OpenClaw通过“桥接器”（Bridges）的概念实现了这一点。每个桥接器都是一个独立的服务，负责与一个特定的通信平台（如Telegram、Discord、Slack）进行对接。

桥接器的工作原理是双向的：

1. 消息接收 ：桥接器监听对应平台的消息。当用户在Telegram的私聊或群组中@机器人或发送特定命令时，Telegram桥接器会捕获这条消息。
2. 消息格式化与转发 ：桥接器将平台原生的消息格式，转换为OpenClaw核心能够理解的内部统一格式（通常是一个JSON对象，包含发送者、聊天ID、纯文本内容、可能的附件等信息），然后通过HTTP或WebSocket发送给OpenClaw核心服务。
3. 处理与响应 ：OpenClaw核心接收到消息后，调用相应的技能进行处理，生成响应内容。
4. 消息回传 ：核心将响应内容发回给对应的桥接器，由桥接器负责将其转换回平台原生格式（如Telegram的Markdown、Slack的Block Kit）并发送出去。

这种架构的好处是清晰的分层和解耦。OpenClaw核心完全不需要关心消息是来自WhatsApp还是Discord，它只处理统一的内部消息对象。同样，Telegram桥接器的更新或故障不会影响Slack桥接器的正常工作。你可以根据需要，同时启用多个桥接器，让你的智能体在多个平台上保持同步的“人格”和记忆。

在实际部署中，每个桥接器通常以独立进程或Docker容器的形式运行。它们通过环境变量或配置文件来获取平台API密钥（如Telegram Bot Token）和核心服务的地址。这种设计也使得水平扩展成为可能，如果某个平台的消息量特别大，你可以单独为该桥接器分配更多计算资源。

3. 实战部署：从零搭建你的专属AI智能体

3.1 环境评估与部署模式选择

在动手安装之前，首先要根据你的使用场景和硬件条件，选择最合适的部署模式。这决定了后续的安装复杂度和使用体验。

模式一：纯本地开发/体验模式

• 适用场景 ：初学者学习、功能测试、低频次个人使用。
• 硬件要求 ：一台性能尚可的台式机或笔记本电脑（建议16GB RAM以上，如有GPU更佳）。
• 优点 ：部署最简单，所有组件都在一台机器上，调试方便。
• 缺点 ：机器关机则服务中断；如果使用本地大模型，会占用大量系统资源，影响电脑其他用途。
• 我的建议 ：如果你是开发者，想为OpenClaw贡献代码或开发新技能，这是最佳起点。对于普通用户，如果你只是想体验基础功能，并且不介意AI响应速度稍慢（如果使用云端大模型API），也可以从这个模式开始。

模式二：家庭服务器常驻模式

• 适用场景 ：希望智能体7x24小时在线，且拥有NAS、小型服务器或闲置PC的家庭用户。
• 硬件要求 ：一台可长期开机的x86设备（如Intel NUC、旧款Mac Mini、DIY的NAS），8GB RAM是底线，16GB或以上为佳。
• 优点 ：服务永久在线，不依赖个人电脑开关机；数据完全留在家庭内网，隐私性最强；可以部署更强大的本地大模型。
• 缺点 ：需要一定的家庭网络和服务器维护知识；从外网访问可能需要配置内网穿透或DDNS。
• 我的建议 ：这是追求隐私和可控性的终极方案。我自己的OpenClaw就部署在一台旧的英特尔NUC上，它安静、省电，足以流畅运行7B参数的量化版大模型。

模式三：云端VPS生产模式

• 适用场景 ：团队协作使用、需要从公网稳定访问、个人使用但无合适家庭服务器。
• 硬件要求 ：云服务商的VPS实例。对于轻量使用（仅集成云端大模型API），1核2GB的实例可能够用；但如果计划在VPS上本地运行大模型，至少需要4核8GB，甚至需要带GPU的实例，成本会显著上升。
• 优点 ：拥有公网IP，访问最方便；服务商提供高可用性保障；无需关心硬件维护。
• 缺点 ：有持续性的租赁成本；数据存储在第三方服务器上，需要额外关注VPS的安全加固。
• 我的建议 ：对于大多数希望智能体“永远在线”的个人用户，选择一家主流云服务商（如AWS、DigitalOcean、Linode）的中等配置VPS，并仅将其作为“中控大脑”（运行OpenClaw核心和桥接器），而将大模型推理交给专门的云API（如OpenAI、Anthropic或国内的深度求索、智谱AI等），是成本、性能和复杂度平衡的最佳选择。原文档中提到的AWS t3.medium 或 m7i-flex.large 实例就是为这种场景准备的。

3.2 基于Linux服务器的标准部署流程

这里我以最常用的**模式三（云端VPS）**为例，详细讲解在Ubuntu 22.04 LTS系统上的部署步骤。这个流程也基本适用于模式二的家庭服务器。

第一步：服务器初始化与安全加固 在购买并启动VPS后，第一件事不是安装软件，而是加固安全。用SSH登录后：

1. 更新系统 ： sudo apt update && sudo apt upgrade -y
2. 创建非root用户 ： sudo adduser openclaw ，并赋予其sudo权限： sudo usermod -aG sudo openclaw 。
3. 设置SSH密钥登录，禁用密码登录 ：这是防止暴力破解的关键。在你的本地电脑生成密钥对（如果还没有）： ssh-keygen -t ed25519 ，然后将公钥（ ~/.ssh/id_ed25519.pub ）的内容，复制到VPS上 openclaw 用户的 ~/.ssh/authorized_keys 文件中。随后编辑SSH服务配置 /etc/ssh/sshd_config ，设置 PasswordAuthentication no ，并重启SSH服务。
4. 配置防火墙 ：使用 ufw ，默认拒绝所有入站，只开放必要端口。通常只需要SSH端口（如22）和未来OpenClaw管理界面的端口（如3000）。 sudo ufw allow 22/tcp && sudo ufw allow 3000/tcp && sudo ufw enable

第二步：安装核心依赖 切换到 openclaw 用户： su - openclaw 。

1. 安装Node.js ：OpenClaw要求Node.js 22或更高版本。推荐使用Node Version Manager (nvm)进行安装，便于管理多版本。

   curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
   # 重新加载shell配置，或退出重新登录
   source ~/.bashrc
   # 安装Node.js 22
   nvm install 22
   nvm use 22
   node --version # 确认版本为22.x
   

2. 安装Docker与Docker Compose ：虽然OpenClaw可以用npm直接安装，但Docker方式更干净，隔离性更好，也是社区推荐的方式。

   # 安装Docker
   curl -fsSL https://get.docker.com -o get-docker.sh
   sudo sh get-docker.sh
   sudo usermod -aG docker $USER
   # 安装Docker Compose插件
   sudo apt install docker-compose-plugin -y
   # 验证安装
   docker --version
   docker compose version
   

   执行完 usermod 后需要 退出SSH会话并重新登录 ，以便用户组更改生效。

第三步：部署OpenClaw核心服务 我们将使用官方提供的Docker Compose模板，这是最快捷、最不易出错的方式。

1. 克隆仓库并进入目录 ：

   git clone https://github.com/openclaw/openclaw.git
   cd openclaw
   

2. 配置环境变量 ：Docker Compose会读取目录下的 .env 文件。首先复制示例配置文件：

   cp .env.example .env
   

   然后，用文本编辑器（如 nano ）打开 .env 文件。这里有几个关键配置项你必须修改：
   • OPENCLAW_SECRET_KEY ：生成一个强随机字符串，用于加密敏感数据。可以用命令 openssl rand -base64 32 生成。
   • OPENAI_API_KEY 或 ANTHROPIC_API_KEY 等：如果你打算使用云端大模型API，在此填入你的密钥。如果打算用本地模型，可以先留空。
   • DATABASE_URL ：数据库连接字符串。默认的SQLite适用于轻量使用，如果团队使用或数据量大，建议改为PostgreSQL。
   • HOST 和 PORT ：设置服务监听的地址和端口。如果希望从公网访问管理界面， HOST 可设为 0.0.0.0 。
3. 启动服务 ：

   docker compose up -d
   

   这个命令会拉取所有必要的Docker镜像（核心服务、数据库、Redis等）并在后台启动它们。使用 docker compose logs -f 可以查看实时日志，确认服务是否启动成功。

第四步：访问管理界面与初始配置 服务启动后，在浏览器中访问 http://你的VPS公网IP:3000 （端口号取决于你在 .env 中的 PORT 设置），你应该能看到OpenClaw的Web管理界面。

1. 首次登录 ：通常需要设置一个管理员账号和密码。
2. 模型配置 ：在管理界面的设置中，配置AI模型。如果你在 .env 中配置了API密钥，这里可以选择对应的提供商（如OpenAI GPT-4）。如果你想使用本地模型，需要额外部署一个Ollama或LM Studio等服务，并将其API端点配置在这里。
3. 安装桥接器 ：管理界面通常提供了“添加集成”或“桥接器”的选项。以Telegram为例，你需要先通过 @BotFather 创建一个Telegram Bot，获取 Bot Token ，然后在OpenClaw管理界面中填入这个Token和Webhook地址（格式通常为 https://你的域名或IP:端口/webhooks/telegram ），即可完成绑定。

至此，一个最基本的OpenClaw核心服务就已经在云端运行起来了。它现在是一个没有“四肢”（桥接器）和“技能”的大脑，接下来我们需要让它变得有用。

3.3 技能安装与桥接器配置实战

技能安装的两种主要途径：

1. 通过ClawHub网页界面 ：这是最直观的方式。在OpenClaw的管理界面中，一般会有“技能商店”或类似入口，连接至ClawHub。你可以浏览、搜索技能，并一键安装。安装后，技能所需的配置参数也会在界面中呈现供你填写。
2. 通过命令行 ：对于高级用户或需要安装特定版本、本地开发的技能，可以使用OpenClaw CLI工具。首先确保CLI已安装： npm install -g @openclaw/cli （或在Docker容器内执行）。然后使用 openclaw skills:install <skill-name> 命令进行安装。

实操心得 ：初期建议从安装一些基础且实用的技能开始，例如：

• web-search ：让AI能够联网搜索，弥补大模型知识截止日期的问题。
• filesystem ：谨慎使用，它允许AI读取你指定的本地目录文件，用于总结文档等。
• shell ： 高风险技能，务必谨慎 。它允许AI执行Shell命令。配置时一定要将其限制在绝对安全的目录和命令白名单内。
• calendar 、 todo ：连接你的Google Calendar或Todoist，管理日程。 每安装一个技能，都花时间阅读其文档，理解它需要哪些权限，并最小化地授予权限。

桥接器配置详解（以Telegram为例）： 桥接器通常作为独立的Docker容器运行，在 docker-compose.yml 中已有定义，但需要额外配置。

1. 在 .env 文件中，找到或添加Telegram桥接器的配置段，例如：

   # Telegram Bridge
   TELEGRAM_ENABLED=true
   TELEGRAM_TOKEN=你的BotToken
   TELEGRAM_WEBHOOK_URL=https://your-domain.com/webhooks/telegram
   TELEGRAM_ADMIN_USERNAME=你的Telegram用户名
   

2. TELEGRAM_WEBHOOK_URL 是关键。你需要确保这个URL是公网可访问的，并且指向你OpenClaw核心服务所在的服务器和正确的端口（通常是核心服务的 /webhooks/telegram 路径）。如果你没有域名，直接使用VPS的IP地址和端口也可以，但部分平台（如Telegram）对IP地址形式的Webhook支持可能不稳定，建议还是配置一个域名并设置反向代理（如用Nginx）。
3. 修改配置后，需要重启桥接器容器： docker compose restart openclaw-telegram-bridge （容器名可能不同，请用 docker compose ps 查看）。
4. 在Telegram中与你创建的Bot对话，发送 /start 。如果配置正确，Bot应该会回复你。

配置反向代理（Nginx）以获得域名和HTTPS： 为了更稳定、安全地使用Webhook，并为管理界面提供HTTPS加密，配置Nginx反向代理是生产环境的必备步骤。

1. 安装Nginx ： sudo apt install nginx -y
2. 申请SSL证书 ：使用Let‘s Encrypt的Certbot工具非常方便。 sudo apt install certbot python3-certbot-nginx -y ，然后执行 sudo certbot --nginx -d your-domain.com ，按照提示操作即可获得免费证书。
3. 配置Nginx站点 ：在 /etc/nginx/sites-available/ 下创建一个配置文件，例如 openclaw ：

   server {
       listen 80;
       server_name your-domain.com;
       # 将HTTP请求重定向到HTTPS
       return 301 https://$server_name$request_uri;
   }
   
   server {
       listen 443 ssl http2;
       server_name your-domain.com;
   
       ssl_certificate /etc/letsencrypt/live/your-domain.com/fullchain.pem;
       ssl_certificate_key /etc/letsencrypt/live/your-domain.com/privkey.pem;
   
       # 反向代理到OpenClaw核心服务（假设运行在3000端口）
       location / {
           proxy_pass http://localhost:3000;
           proxy_set_header Host $host;
           proxy_set_header X-Real-IP $remote_addr;
           proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
           proxy_set_header X-Forwarded-Proto $scheme;
       }
   
       # 可选：为Webhook路径设置更长的超时时间
       location /webhooks/ {
           proxy_pass http://localhost:3000;
           proxy_read_timeout 300s;
           proxy_connect_timeout 75s;
           # ... 其他proxy_set_header设置同上
       }
   }
   

4. 创建软链接并测试配置： sudo ln -s /etc/nginx/sites-available/openclaw /etc/nginx/sites-enabled/ ，然后 sudo nginx -t 测试配置，无误后 sudo systemctl reload nginx 重启Nginx。
5. 最后，别忘了将 .env 文件和桥接器配置中的所有 http://你的IP:3000 替换为 https://your-domain.com ，并重启所有OpenClaw相关容器。

完成以上所有步骤后，你就拥有了一个通过域名安全访问、7x24小时运行、并连接了Telegram的OpenClaw智能体。你可以开始和它对话，并尝试安装技能来扩展它的能力了。

4. 高级配置与核心技能开发入门

4.1 模型集成策略：云端API与本地部署的权衡

OpenClaw的核心智能来自于大语言模型（LLM）。如何为你的智能体选择一个“大脑”，是影响其性能、成本和响应速度的最关键决策。主要有三种集成模式：

模式A：纯云端API（最简单，有持续成本）

• 操作 ：在OpenClaw的管理界面或环境变量中，直接填入OpenAI、Anthropic、Google Gemini或国内如智谱AI、深度求索等服务的API密钥。
• 优点 ：
  • 开箱即用 ：无需关心模型下载、硬件兼容性、推理优化。
  • 性能强大 ：直接使用最先进的GPT-4o、Claude 3.5 Sonnet等模型，能力上限高。
  • 弹性伸缩 ：无需为流量峰值准备硬件资源。
• 缺点 ：
  • 持续成本 ：按Token用量计费，高频使用下费用可观。
  • 网络延迟 ：每次交互都需往返云端，延迟在几百毫秒到几秒不等。
  • 隐私顾虑 ：虽然主流厂商有合规承诺，但提示词和对话数据仍需离开本地环境。
• 我的选择 ：在开发测试阶段，或者处理一些非敏感但需要极强推理能力的任务时（如复杂代码生成、创意写作），我会切换到GPT-4 API。这是快速验证想法的最佳方式。

模式B：纯本地模型（最隐私，一次性硬件投入）

• 操作 ：在服务器上部署一个本地模型推理服务，如Ollama、LM Studio或vLLM，然后在OpenClaw中配置其本地API端点（如 http://localhost:11434/api/generate ）。
• 优点 ：
  • 完全隐私 ：所有数据在本地闭环。
  • 零API成本 ：一次性的硬件投入。
  • 响应稳定 ：不依赖外网，无网络波动影响。
• 缺点 ：
  • 硬件门槛高 ：流畅运行70B参数模型需要昂贵的GPU（如RTX 4090, A100）。运行较小的7B/13B模型虽可用CPU，但速度慢，智能水平有显著差距。
  • 技术复杂度 ：涉及模型量化、推理引擎优化等知识。
• 我的选择 ：我的家庭服务器上常驻运行着Ollama，里面加载了量化版的 llama3.2:3b 和 qwen2.5:7b 模型。它们足以处理日常的问答、总结和简单的逻辑推理，所有家庭内部的自动化查询（如“今天家里传感器数据有什么异常？”）都路由到这里，确保隐私。

模式C：混合模式（平衡之道）

• 操作 ：这是最实用的策略。在OpenClaw中配置多个模型终端，并通过路由规则或技能指定来分配任务。
• 实现示例 ：你可以配置一个“路由”技能，根据消息内容或用户指令，决定调用哪个模型。例如，所有包含“总结”、“翻译”、“简单回答”关键词的请求，发给本地的7B模型；而包含“写代码”、“深度分析”、“创意”的请求，则转发给云端GPT-4。

  // 伪代码示例：一个简单的模型路由技能
  module.exports = async ({ context, ack, say }) => {
    const userMessage = context.message.text.toLowerCase();
    let targetModel = 'local-llama3'; // 默认模型
  
    if (userMessage.includes('write code') || userMessage.includes('complex analysis')) {
      targetModel = 'openai-gpt4';
    } else if (userMessage.includes('search web')) {
      // 对于需要联网搜索的，可能结合搜索技能和快速总结的本地模型
      targetModel = 'local-fast';
    }
  
    // 调用OpenClaw内部API，将消息用指定模型处理
    const response = await callOpenClawInternalAPI(userMessage, targetModel);
    await say(response);
  };
  

• 优点 ：在成本、隐私和性能间取得最佳平衡。日常琐事用免费/低成本的本地模型，关键任务调用付费的顶级模型。
• 我的实战配置 ：我创建了一个“模型选择器”技能。当我在Telegram中输入 /smart 时，后续对话会使用云端GPT-4；输入 /local 时，则切换回本地Qwen模型。这样我可以根据任务重要性随时切换。

4.2 开发你的第一个自定义技能

当社区技能无法满足你的特定需求时，自己开发技能是解锁OpenClaw全部潜力的关键。一个技能本质上就是一个Node.js模块，它导出一个异步函数，接收包含上下文（context）、消息（message）等参数的对象，并执行操作。

步骤一：创建技能项目结构 使用OpenClaw CLI可以快速搭建脚手架：

openclaw skills:create my-first-skill
cd my-first-skill

这会生成一个标准的目录结构，包含 package.json 、 skill.json 和入口文件 index.js 。

步骤二：编写skill.json 这是技能的“身份证”，定义了技能的元数据和触发方式。

{
  "name": "greet",
  "version": "1.0.0",
  "description": "一个简单的打招呼技能，并查询当前时间",
  "trigger": "greet [name]",
  "parameters": [
    {
      "name": "name",
      "description": "你的名字",
      "required": false,
      "default": "朋友"
    }
  ],
  "permissions": ["say"] // 声明此技能需要“发送消息”的权限
}

• trigger : 定义了如何触发这个技能。 greet [name] 表示用户输入“greet 小明”时，参数 name 会被赋值为“小明”。
• parameters : 定义了技能接受的参数。 required 为 false 且设置了 default 值，表示此参数可选，未提供时使用默认值“朋友”。

步骤三：编写核心逻辑（index.js）

module.exports = async ({ context, ack, say, params }) => {
  // 1. 立即确认收到指令，避免用户等待超时（对于耗时操作尤其重要）
  await ack();

  const userName = params.name || '朋友';
  const currentTime = new Date().toLocaleTimeString('zh-CN');

  // 2. 构建回复内容
  const greeting = `你好，${userName}！`;
  const timeInfo = `当前时间是：${currentTime}`;

  // 3. 发送消息。`say`函数由运行时注入，用于向触发此技能的聊天会话发送消息。
  await say(`${greeting}\n${timeInfo}`);

  // 4. 技能也可以执行更复杂的异步操作，比如调用外部API
  // const weather = await fetchWeatherAPI();
  // await say(`另外，今天的天气是：${weather}`);
};

这个简单的技能展示了几个关键点：

1. ack() 函数：用于快速响应平台，告诉平台“指令已收到，正在处理”。这对于Slack、Discord等期望快速响应的平台很重要，可以避免出现“指令未响应”的超时提示。
2. params 对象：包含了从用户消息中解析出的参数。
3. say() 函数：向用户返回消息的主要方式。
4. 技能可以执行任何Node.js支持的异步操作，如读写文件、发起网络请求、查询数据库等。

步骤四：本地测试与安装

1. 在技能目录下，运行 npm link 将其链接到全局。
2. 在OpenClaw的管理界面“技能”部分，应该能看到你的本地技能“greet”，点击安装。
3. 在已连接的聊天工具（如Telegram）中，向你的Bot发送“greet”或“greet 张三”，你应该会收到包含当前时间的个性化问候。

开发心得 ：

• 错误处理 ：务必用 try...catch 包裹你的核心逻辑，并在catch块中调用 say(“抱歉，处理你的请求时出错了: ” + error.message) ，给用户明确的反馈。
• 权限最小化 ：在 skill.json 的 permissions 字段中，只声明你真正需要的权限。如果你的技能只需要发送消息，就不要申请 filesystem.read 权限。
• 使用配置 ：对于API密钥、服务器地址等可变参数，不要硬编码在代码里。OpenClaw提供了技能配置机制，允许用户在安装技能时通过管理界面填写这些配置项，然后在代码中通过 context.config 对象访问。这能让你的技能更易于分发和复用。

4.3 实现自动化工作流：技能组合与事件驱动

单个技能的能力是有限的，但将多个技能通过事件或条件串联起来，就能构建出强大的自动化工作流。OpenClaw支持两种主要的编排方式：

方式一：链式触发（一个技能调用另一个） 在一个技能的代码中，你可以直接调用其他已安装技能的“动作”。这需要你知道目标技能的编程接口。通常，社区技能会在文档中暴露其可被调用的函数。

// 在“生成日报”技能中，调用“获取日历事件”和“获取天气”技能
module.exports = async ({ context, ack, say, client }) => { // 注意注入的client对象
  await ack();
  // 假设有一个已安装的‘calendar’技能，它暴露了一个fetchEvents函数
  const calendar = context.skills.get('calendar');
  const todayEvents = await calendar.actions.fetchEvents({ date: 'today' });

  // 假设有一个‘weather’技能
  const weather = context.skills.get('weather');
  const todayWeather = await weather.actions.getForecast({ city: 'Beijing' });

  // 组合信息并生成摘要
  const report = `# 今日简报\n\n**日程：**\n${todayEvents.map(e => `- ${e.time} ${e.title}`).join('\n')}\n\n**天气：**\n${todayWeather.summary}`;
  await say(report);
};

方式二：基于事件的响应（更灵活） OpenClaw内部有一个事件总线（Event Bus）。技能可以“监听”特定的事件，并在事件发生时被触发。事件可以是外部的（如收到一条消息、一个定时器触发），也可以是内部的（如一个技能执行完成、数据库记录被更新）。

1. 定时任务 ：这是最常见的自动化场景。你可以使用 cron 技能或编写一个监听 schedule 事件的技能。

   // skill.json 中声明监听的事件
   "events": ["schedule.daily-morning"]
   

   // index.js 中处理事件
   module.exports = async ({ context, event }) => {
     if (event.type === 'schedule.daily-morning') {
       // 执行每天早上9点要做的任务，例如发送晨报
       await context.skills.get('morning-report').actions.execute();
     }
   };
   

   你需要在管理界面中配置一个定时器，在每天上午9点发出 schedule.daily-morning 事件。

2. 消息内容触发 ：除了固定的命令触发，技能还可以监听所有消息，并对符合特定模式的消息做出反应。例如，你可以写一个技能，监听所有包含“bug”或“错误”关键词的消息，并自动创建一个Github Issue。

   // skill.json
   "events": ["message.received"]
   

   // index.js
   module.exports = async ({ context, event }) => {
     const message = event.message.text;
     if (message.includes('bug') || message.includes('错误')) {
       // 调用Github技能创建Issue
       await context.skills.get('github').actions.createIssue({
         title: `自动创建：${message.substring(0, 50)}...`,
         body: `来自聊天记录：\n> ${message}`
       });
       // 可以可选地回复用户“已为您创建了Issue”
     }
   };
   

通过灵活组合这些模式，你可以构建出极其复杂的自动化流程。例如，我设置了一个工作流：当Github仓库有新的Pull Request时（Webhook事件），触发OpenClaw的一个技能，该技能调用“代码分析”技能对PR进行简单审查，然后将结果摘要发送到团队的Slack频道，并@相关 reviewer。整个过程完全自动，无需人工介入。

5. 运维、安全与故障排查实录

5.1 安全加固清单：将风险降到最低

将一个拥有文件访问、网络请求甚至Shell执行能力的AI智能体部署在公网上，安全是头等大事。以下是我在生产环境中遵循的加固清单：

1. 网络层面隔离 ：

   • 防火墙严格限制 ：除了SSH（22）和管理界面/Webhook端口（如3000、443），封锁VPS所有其他不必要的入站端口。使用 ufw 或云服务商的安全组实现。
   • 使用反向代理与HTTPS ：如前面所述，务必使用Nginx/Apache作为反向代理，并配置SSL证书（如Let‘s Encrypt）。这不仅能加密通信，还能隐藏后端服务的真实端口和指纹。
   • 考虑私有网络 ：如果仅在内部使用，可以将OpenClaw部署在内网，通过VPN访问管理界面。桥接器如Telegram Bot的Webhook，可以通过有公网IP的反向代理服务器或云函数进行中转。

2. 服务与权限最小化 ：

   • 使用非root用户运行 ：Docker容器默认以root运行存在风险。在 docker-compose.yml 中，为每个服务指定 user: “1000:1000” （你的非root用户UID:GID），或者在Dockerfile中创建专用用户。
   • 技能权限审核 ：这是最大的风险点。 绝不安装 来源不明或未经审查的技能。在安装任何技能前，仔细阅读其 skill.json 中的 permissions 字段和源代码。对于需要高权限（如 shell 、 filesystem.root ）的技能，问自己是否绝对必要。
   • 技能沙箱（高级） ：社区有项目试图通过Firecracker等微虚拟机技术或更严格的Seccomp BPF规则来隔离技能的执行环境，但这需要较高的运维能力。

3. 认证与访问控制 ：

   • 强化管理界面登录 ：使用强密码，并启用多因素认证（如果OpenClaw支持）。考虑将管理界面仅监听在 127.0.0.1 ，然后通过SSH隧道访问。
   • 桥接器访问控制 ：在Telegram、Discord等桥接器配置中，利用平台的权限系统。例如，在Telegram Bot中，使用 TELEGRAM_ADMIN_USERNAME 环境变量限制只有特定用户才能与Bot交互。在Discord中，通过角色和频道权限来控制谁可以@机器人。

4. 数据安全 ：

   • 加密敏感配置 ：将API密钥、数据库密码等存储在 .env 文件中，并确保该文件权限为 600 （仅所有者可读）。 切勿 将 .env 文件提交到Git仓库。
   • 定期备份 ：定期备份OpenClaw的数据库（通常是 ./data 目录下的SQLite文件或PostgreSQL数据库）和重要的配置文件。你可以写一个简单的技能，定期将数据打包加密后上传到安全的云存储。

5. 依赖与更新 ：

   • 定期更新 ：关注OpenClaw核心、技能和Docker镜像的安全更新。定期执行 git pull 和 docker compose pull 来获取最新版本。 但注意 ：在生产环境更新前，务必在测试环境验证。
   • 扫描漏洞 ：使用 npm audit 或 docker scan 等工具定期检查项目依赖和镜像中的已知漏洞。

5.2 日常运维与监控

一个稳定的服务离不开日常的照料。

1. 日志管理 ：OpenClaw各组件的日志是排查问题的第一手资料。

   • 查看实时日志 ： docker compose logs -f openclaw-core （查看核心服务日志）， -f 参数可以持续跟踪。
   • 查看特定时间段的日志 ： docker compose logs --since 1h openclaw-core 。
   • 日志持久化 ：默认日志会随着容器重启而消失。在 docker-compose.yml 中，可以将容器的日志驱动配置为 json-file 并设置大小限制，或者更专业地，使用 docker logging driver 将日志发送到ELK（Elasticsearch, Logstash, Kibana）或Loki等集中式日志系统。

   # 在docker-compose.yml的服务部分示例
   services:
     openclaw-core:
       image: openclaw/core:latest
       logging:
         driver: "json-file"
         options:
           max-size: "10m"
           max-file: "3"
   

2. 资源监控 ：使用 docker stats 命令可以快速查看各容器的CPU、内存使用情况。对于长期运行，建议安装一个轻量级的监控工具如 Netdata 或 Prometheus+Grafana ，以便在资源（特别是内存）不足时收到警报。

3. 健康检查与自愈 ：在 docker-compose.yml 中为关键服务（如核心服务、数据库）定义健康检查（ healthcheck 指令）。这样，Docker可以感知服务是否健康，并结合重启策略（ restart: unless-stopped ）实现简单的自愈。

4. 备份策略 ：

   • 数据库 ：如果使用SQLite，直接备份 data/ 目录下的 .db 文件。如果使用PostgreSQL，使用 pg_dump 命令定期导出。
   • 技能配置 ：备份 skills/ 目录和 .env 文件。
   • 自动化 ：编写一个备份技能，利用 cron 技能定时触发，将备份文件加密后上传到其他存储位置。

5.3 常见问题与故障排查速查表

在部署和使用过程中，你几乎一定会遇到下面这些问题。这里是我踩过坑后的经验总结。

问题现象	可能原因	排查步骤与解决方案
管理界面无法访问 (Connection refused/timeout)	1. 服务未启动。 2. 防火墙/安全组阻止了端口。 3. 服务崩溃或端口被占用。	1. docker compose ps 检查服务状态， docker compose logs 查看错误日志。 2. sudo ufw status 或检查云平台安全组规则，确保端口（如3000, 443）已开放。 3. `netstat -tlnp
Telegram/Discord等桥接器收不到消息或无法回复	1. Webhook URL配置错误或未设置。 2. 网络问题，平台无法访问你的Webhook地址。 3. 桥接器容器未运行或配置错误。	1. 确认Webhook URL ：对于Telegram，可以用浏览器访问 https://api.telegram.org/bot<YOUR_BOT_TOKEN>/getWebhookInfo 查看当前设置的Webhook。使用 curl 命令手动设置： curl -F “url=https://your-domain.com/webhooks/telegram” https://api.telegram.org/bot<YOUR_BOT_TOKEN>/setWebhook 。 2. 检查网络连通性 ：在服务器上 curl https://api.telegram.org ，确保出站正常。确保你的域名解析正确且HTTPS证书有效。 3. 检查桥接器日志 ： docker compose logs openclaw-telegram-bridge ，查看是否有配置错误或连接异常。
AI模型不响应或返回空/错误内容	1. API密钥错误或额度不足。 2. 本地模型服务未启动或内存不足。 3. 网络超时或代理问题。 4. 提示词（Prompt）配置不当。	1. 检查API密钥 ：在管理界面或 .env 文件中确认密钥正确，并登录对应平台查看额度。 2. 检查本地模型 ：访问本地模型的服务地址（如 http://localhost:11434/api/tags ）看是否返回模型列表。使用 htop 或 docker stats 查看内存使用，模型加载可能需大量内存。 3. 检查网络 ：如果使用云端API，在服务器上 ping api.openai.com 测试连通性。如果服务器在国内访问国外API不稳定，考虑设置HTTPS代理或在 .env 中配置 HTTP_PROXY / HTTPS_PROXY 。 4. 检查系统提示词 ：在OpenClaw管理界面的模型设置中，查看“系统提示词”（System Prompt）是否被意外清空或修改得过于限制。
技能安装失败或执行时报错	1. 技能依赖未安装。 2. 技能代码有bug或与当前OpenClaw版本不兼容。 3. 技能权限不足。	1. 查看技能日志 ：在管理界面通常有技能的执行日志。 docker compose logs 中也会包含核心服务调用技能的报错信息。 2. 检查技能兼容性 ：查看技能仓库的README，确认其支持的OpenClaw核心版本。尝试安装更早或更晚的技能版本。 3. 以调试模式运行 ：在技能目录下手动执行 node index.js 并传入模拟参数，看是否能正常运行。检查技能所需的权限是否已在管理界面中授予。
服务运行一段时间后变慢或崩溃	1. 内存泄漏（常见于某些技能或模型）。 2. 数据库文件过大或未优化。 3. 磁盘空间不足。	1. 监控资源 ：使用 docker stats 观察内存增长趋势。重启对应的容器可以临时解决内存泄漏问题，并报告给技能或核心的开发者。 2. 数据库维护 ：如果使用SQLite，可以定期执行 VACUUM; 命令来重整数据库，释放空间。对于PostgreSQL，可能需要清理旧会话或日志表。 3. 检查磁盘 ： df -h 查看磁盘使用率，清理Docker无用镜像和容器： docker system prune -a 。
定时任务不触发	1. 服务器时区设置不正确。 2. Cron表达式错误。 3. 负责定时任务的服务（如 node-schedule ）未正常运行。	1. 检查服务器时区 ： date 命令查看当前时间。使用 sudo timedatectl set-timezone Asia/Shanghai 进行设置。 2. 检查Cron表达式 ：使用在线的Cron表达式验证工具（如crontab.guru）检查你的表达式是否正确。 3. 查看定时任务服务日志 ：在OpenClaw核心日志中搜索与定时任务相关的关键词，看是否有加载或执行错误。

最后一点个人体会 ：OpenClaw是一个极其强大但也相对复杂的系统，它的魅力在于其可塑性和控制力。不要试图在第一天就搭建一个完美无缺的“贾维斯”。最好的方式是 从小处着手，迭代增长 。先从在本地安装成功，并让它在Telegram上回应你“你好”开始。然后添加一两个你最需要的技能，比如查天气或记待办。在这个过程中，你会逐渐理解其组件如何交互，遇到并解决上述的典型问题。当基础稳定后，再尝试更复杂的自动化工作流和技能开发。记住，这个框架本身也在快速演进，保持与社区（如Reddit的r/openclaw）的同步，关注核心版本的更新日志，是让你的智能体持续稳定运行的关键。