Python
OpenClaw 入门指南：AI Agent 开发新范式
目 录 一、OpenClaw 是什么？为什么它如此火爆？ 1.1 项目背景与起源 1.2 核心定位与价值主张 1.3 与主流框架的技术对比 1.4 技术架构全景解析 二、快速部署：5 分钟上手体验 2.1 环境要求与准备 2.2 部署流程概览 2.3 详细安装步骤 2.4 常见安装问题排查 三、部署方案深度对比 3.1 四种主流部署方案 3.2 方案详细对比 3.3 方案一：本地开发机（零成本体验…
目 录 一、OpenClaw 是什么？为什么它如此火爆？ 1.1 项目背景与起源 1.2 核心定位与价值主张 1.3 与主流框架的技术对比 1.4 技术架构全景解析 二、快速部署：5 分钟上手体验 2.1 环境要求与准备 2.2 部署流程概览 2.3 详细安装步骤 2.4 常见安装问题排查 三、部署方案深度对比 3.1 四种主流部署方案 3.2 方案详细对比 3.3 方案一：本地开发机（零成本体验…
摘要：OpenClaw 是 2026 年最火爆的开源 AI 助手项目，GitHub 两周突破 15 万 Star。本文将从架构原理、部署实践、成本优化、安全加固四个维度，手把手教你搭建属于自己的 7×24 小时 AI 智能体。
OpenClaw（原名 Clawdbot，后更名为 Moltbot，最终定名为 OpenClaw）由 PSPDFKit 创始人 Peter Steinberger 于 2026 年初开源。作为一个深耕 PDF 技术多年的连续创业者，Peter 在开发过程中深刻体会到 AI 辅助工具的重要性，于是决定打造一个真正属于自己的 AI 助手。
项目开源后，在技术社区引发了巨大反响。在 GitHub 上，项目在 72 小时内增长超过 6 万 Star，两周内突破 15 万 Star，成为 GitHub 史上增长最快的开源项目之一。这一现象级的增长背后，折射出开发者对"拥有自己的 AI 助手"的强烈需求。
OpenClaw 的核心定位非常清晰：
在你自己的设备上运行的 AI Agent，连接各种消息平台，提供 24/7 全天候的 AI 助手体验。
这个定位解决了当前 AI 助手市场的三大痛点：
第一，数据隐私问题。使用 ChatGPT、Claude 等云端服务，意味着你的对话数据、工作内容都存储在第三方服务器上。对于企业用户和注重隐私的个人用户来说，这是一个难以接受的风险。OpenClaw 完全本地运行，数据不出你的设备，从根本上解决了隐私问题。
第二，多平台碎片化问题。你可能同时在用 WhatsApp 和同事沟通、用 Telegram 和朋友聊天、用飞书处理工作。每个平台都有独立的 AI 机器人，体验割裂。OpenClaw 支持 20+ 消息平台，一套系统统一接入，无论你在哪个平台，都能获得一致的 AI 助手体验。
第三，成本控制问题。订阅多个 AI 服务每月可能花费上百美元，而且按量计费的模型很容易因为配置不当而产生意外高额账单。OpenClaw 开源免费，支持本地模型，让你完全掌控成本。
为了帮助读者更好地理解 OpenClaw 在技术生态中的定位，我们将其与当前主流的 AI Agent 框架进行对比：
| 特性 | OpenClaw | LangChain | AutoGPT | ChatGPT |
|---|---|---|---|---|
| 部署方式 | 本地自托管 | 云端/本地 | 云端 | 云端 |
| 消息平台 | 20+ 平台 | 单一 | 单一 | 单一 |
| 成本模型 | 开源免费 | 部分付费 | 付费 | 订阅制 |
| 数据隐私 | ✅ 完全本地 | ⚠️ 可配置 | ❌ 云端存储 | ❌ 云端存储 |
| 可扩展性 | Skill 系统 | 插件系统 | 有限 | 插件系统 |
| 本地模型 | ✅ Ollama | ✅ 支持 | ❌ 不支持 | ❌ 不支持 |
| 浏览器控制 | ✅ 内置 | ⚠️ 需集成 | ⚠️ 需集成 | ❌ 无 |
| 定时任务 | ✅ Cron | ❌ 无 | ❌ 无 | ❌ 无 |
从对比可以看出，OpenClaw 在多渠道接入、本地部署、隐私保护方面具有独特优势，特别适合需要多平台统一接入、对数据隐私有较高要求的场景。
OpenClaw 采用三层架构设计，从下到上分别是消息渠道层、Gateway 核心控制平面、AI 模型层。
图1：OpenClaw 三层架构设计，展示了消息渠道层、Gateway 核心层、AI 模型层的关系
🤖 AI 模型层
⚙️ Gateway 核心控制平面
📱 消息渠道层
Telegram
Discord
飞书
钉钉
Slack
Session Manager
Channel Router
Tools Registry
Memory Store
OpenAI GPT-4o
Claude
DeepSeek
豆包
Ollama 本地
消息渠道层负责统一接入各种消息平台。无论是即时通讯软件（WhatsApp、Telegram、Discord）、企业协作工具（飞书、钉钉、Slack），还是社交媒体平台，都可以通过统一的接口接入 OpenClaw。这一层屏蔽了不同平台的协议差异，让上层不需要关心消息来自哪个平台。
Gateway 核心控制平面是 OpenClaw 的"大脑"，包含四个核心模块：Session Manager 负责管理用户会话，维护对话上下文；Channel Router 负责消息路由，将消息分发到正确的处理流程；Tools Registry 管理所有可用工具，包括内置工具和自定义技能；Memory Store 负责记忆存储，支持短期记忆和长期记忆。
AI 模型层提供智能推理能力。OpenClaw 支持多种 AI 模型后端，包括 OpenAI 的 GPT 系列、Anthropic 的 Claude、国内的 DeepSeek 和豆包，以及通过 Ollama 运行的本地开源模型。用户可以根据需求灵活选择，在成本、性能、隐私之间找到最佳平衡。
在开始部署之前，请确保你的系统满足以下要求：
| 环境 | 最低要求 | 推荐配置 |
|---|---|---|
| Node.js | ≥ 22 LTS | 24+ |
| 操作系统 | macOS / Linux / Windows (WSL2) | macOS / Linux |
| 内存 | 2GB | 4GB+ |
| 磁盘 | 500MB | 1GB+ |
Node.js 是 OpenClaw 的唯一依赖，建议使用 LTS（长期支持）版本以获得最佳稳定性。如果你还没有安装 Node.js，可以从官网下载安装包，或使用 nvm（Node Version Manager）进行版本管理。
整个部署过程可以分为五个步骤，从环境检查到最终验证，通常只需要 5 分钟左右。
环境检查
安装OpenClaw
初始化配置
启动Gateway
验证运行
第一步：安装 OpenClaw
使用 npm 或 pnpm 全局安装 OpenClaw：
# 使用 npm 安装npminstall-g openclaw@latest # 或使用 pnpm（推荐，更快更省空间）pnpmadd-g openclaw@latest
安装过程通常需要 1-2 分钟，取决于你的网络环境。如果遇到网络问题，可以配置国内镜像源加速下载。
第二步：运行初始化向导
安装完成后，运行引导向导进行初始化配置：
openclaw onboard
向导会引导你完成以下配置：
第三步：启动 Gateway 服务
配置完成后，启动 Gateway 服务：
# 前台运行（调试模式） openclaw gateway --verbose# 或使用守护进程（生产环境推荐） openclaw gateway start
前台运行模式可以看到详细的日志输出，适合调试和问题排查。守护进程模式会在后台运行，适合生产环境长期运行。
第四步：验证安装
发送一条测试消息验证系统是否正常工作：
openclaw agent --message"你好，请介绍一下你自己"
如果一切正常，你会收到 AI 的回复。至此，OpenClaw 已经成功部署并运行。
在安装过程中，可能会遇到一些常见问题。以下是问题列表和解决方案：
| 问题 | 原因 | 解决方案 |
|---|---|---|
EACCES 权限错误 | npm 全局目录权限不足 | 使用 sudo npm install -g openclaw 或配置 npm 用户目录 |
| 网络超时 | 网络连接问题 | 配置国内镜像：npm config set registry https://registry.npmmirror.com |
| Node 版本过低 | Node.js 版本不满足要求 | 升级到 Node.js 22+ |
| 端口被占用 | 18789 端口已被其他程序使用 | 使用 lsof -i :18789 查找并终止占用进程，或更换端口 |
根据不同的使用场景和需求，OpenClaw 支持四种部署方案：
个人体验
长期运行
远程访问
企业生产
部署方案选择
使用场景?
本地开发机
Mac Mini 服务器
云服务器
Docker 容器化
| 方案 | 适用场景 | 成本 | 优点 | 缺点 | 推荐指数 |
|---|---|---|---|---|---|
| 本地开发机 | 个人体验、开发调试 | 零成本 | 5分钟上手、零基础设施 | 关机后无法访问 | ⭐⭐⭐ |
| Mac Mini | 长期运行、隐私优先 | $599-$1999 | 零月租、可本地模型 | 一次性投入高 | ⭐⭐⭐⭐⭐ |
| 云服务器 | 远程访问、团队协作 | 68-99元/年 | 随时随地访问 | 需要运维 | ⭐⭐⭐⭐ |
| Docker | 企业部署、多实例 | 按需 | 安全隔离、易扩展 | 配置复杂 | ⭐⭐⭐⭐⭐ |
这是最简单的部署方式，适合想要快速体验 OpenClaw 的用户。只需要一台日常使用的电脑，无需额外投入。
优点：零成本、5分钟上手、无需额外基础设施。
缺点：电脑关机后服务停止，无法 24 小时运行；网络环境变化可能导致连接中断。
适用人群：想要快速体验 OpenClaw 的个人用户、开发调试阶段的开发者。
如果你需要 24 小时运行 AI 助手，同时注重数据隐私，Mac Mini 是最佳选择。Apple Silicon 芯片的能效比极高，待机功耗仅几瓦，非常适合长期运行。
硬件配置推荐：
| 配置 | 价格 | 性能 | 适用模型 |
|---|---|---|---|
| Mac Mini M4 (16GB) | $599 | 流畅运行 7B 模型 | Qwen-7B, Llama-7B |
| Mac Mini M4 Pro (32GB) | $1,399 | 流畅运行 32B 模型 | DeepSeek-32B, Qwen-32B |
| Mac Mini M4 Pro (64GB) | $1,999 | 可运行 70B 模型 | Llama-70B, Qwen-72B |
搭配 Ollama 实现完全离线：
# 安装 Ollama brew install ollama # 下载本地模型 ollama pull deepseek-r1:32b # 配置 OpenClaw 使用本地模型 openclaw config set models.default.provider ollama openclaw config set models.default.model deepseek-r1:32b
使用本地模型后，你的 AI 助手完全不需要联网，数据隐私得到最大保障，同时运行成本为零。
如果你需要从任何地方访问 AI 助手，或者需要与团队成员共享使用，云服务器是合适的选择。
国内云厂商推荐：
| 厂商 | 配置 | 价格 | 特点 |
|---|---|---|---|
| 阿里云 | 2C4G | 68元/年 | 预装镜像，一键部署 |
| 腾讯云 | 2C4G | 99元/年 | 新用户优惠 |
| 华为云 | 2C4G | 88元/年 | 企业级稳定性 |
云服务器部署需要注意安全配置，建议配置防火墙规则，仅允许特定 IP 访问 Gateway 端口。
对于企业用户或需要多实例部署的场景，Docker 容器化是最佳选择。
# docker-compose.ymlversion:'3.8'services:openclaw:image: openclaw/gateway:latest container_name: openclaw-gateway ports:-"18789:18789"volumes:- ./workspace:/workspace - ./config:/config environment:- OPENCLAW_AUTH_TOKEN=${AUTH_TOKEN}- OPENAI_API_KEY=${OPENAI_API_KEY}restart: unless-stopped # 安全加固read_only:trueuser:"1000:1000"security_opt:- no-new-privileges:true
Docker 部署的优势包括：环境隔离、易于扩展、便于版本管理、支持 CI/CD 集成。
OpenClaw 本身是免费开源的，但调用 LLM API 会产生费用。如果配置不当，成本很容易失控。
以下是真实案例中的成本陷阱：
| 场景 | 消耗 | 费用 |
|---|---|---|
| 配置不当的心跳检查（30分钟/次） | 一晚 | $18.75 |
| 单日"待机"状态 | 5000万 Tokens | ~$11 |
| 无限制的上下文累积 | 持续增长 | 不可控 |
一个用户曾因为心跳任务配置过于频繁，一晚上消耗了 $18.75。另一个用户因为没有限制上下文窗口，Token 消耗持续增长，月度账单达到 $150。
了解 Token 消耗的构成，才能有针对性地优化：
Token 消耗
上下文累积
历史对话存储
工具输出缓存
占比 40-50%
工具输出
搜索结果
文件内容
占比 20-30%
系统提示词
角色定义
技能说明
占比 10-15%
心跳任务
定期检查
状态同步
占比 5-10%
从分析可以看出，上下文累积是最大的消耗来源，占比高达 40-50%。这是因为每轮对话都会保留历史记录，随着对话轮数增加，Token 消耗呈线性增长。
策略一：智能模型路由
根据任务复杂度选择合适的模型，简单任务用便宜模型，复杂任务用强模型：
{"models":{"routing":{"default":"gpt-4o-mini","tasks":{"coding":"claude-3-5-sonnet","chat":"gemini-flash","summary":"haiku"}}}}
策略二：上下文窗口限制
设置上下文窗口上限，防止对话过长导致 Token 爆炸：
{"sessions":{"maxContextTokens":4000,"autoResetThreshold":0.8}}
策略三：会话定期重置
设置定时任务，每天凌晨重置会话：
crontab-e# 添加04 * * * openclaw sessions reset --all
策略四：本地模型回退
配置本地模型作为备用，当云端模型不可用或预算超限时自动切换：
{"models":{"fallback":{"enabled":true,"local":"ollama:deepseek-r1:14b","trigger":"rate_limit_exceeded"}}}
策略五：心跳任务优化
将心跳间隔从 30 分钟改为 4 小时，可节省 87% 的待机成本：
{"heartbeat":{"enabled":true,"interval":"4h","tasks":["email","calendar"]}}
策略六：供应商硬性限制
设置月度预算上限，防止意外超支：
exportOPENAI_MAX_MONTHLY_BUDGET=50
| 指标 | 优化前 | 优化后 | 节省 |
|---|---|---|---|
| 月度成本 | $150 | $35 | 77% |
| 日均 Tokens | 1500万 | 320万 | 79% |
| 响应速度 | 2.3s | 1.1s | 52% |
| 待机消耗 | $0.5/天 | $0.06/天 | 88% |
通过以上六大策略的组合使用，月度成本可以从 $150 降至 $35，节省 77%。同时，由于上下文更精简，响应速度反而提升了 52%。
OpenClaw 作为一个快速发展的项目，也经历过安全事件。了解这些事件有助于我们更好地保护自己的部署：
| 事件 | 时间 | 影响 | 状态 |
|---|---|---|---|
| CVE-2026-25253 | 2026.1 | WebSocket 劫持，RCE 漏洞 | ✅ 已修复 |
| 923 个网关暴露 | 2026.2 | 零认证暴露公网 | ⚠️ 用户责任 |
| 恶意 VS Code 扩展 | 2026.2 | 远程访问木马 | ✅ 已下架 |
最严重的是 CVE-2026-25253，攻击者可以通过 WebSocket 劫持实现远程代码执行。这个漏洞在 2026 年 1 月被披露后，开发团队在 24 小时内发布了修复版本。
另一个值得警惕的是 923 个网关暴露事件。由于用户将 Gateway 直接暴露在公网且未配置认证，任何人都可以访问这些 AI 助手。这提醒我们，安全配置是用户的责任。
AI 模型Gateway用户AI 模型Gateway用户alt[不在白名单][在白名单]alt[认证失败][认证成功]发送消息Token 认证401 未授权白名单检查403 禁止访问权限检查转发请求返回响应返回结果
OpenClaw 提供四级访问控制策略，从最严格到最宽松：
{"security":{"dmPolicy":"pairing","allowlist":["+86138xxxxxxxx"],"groupChat":{"requireMention":true}}}
四级策略说明：
| 策略 | 说明 | 适用场景 |
|---|---|---|
pairing | 必须通过配对流程 | 个人使用，最安全 |
allowlist | 仅白名单用户可访问 | 团队内部使用 |
open | 开放访问 | 公开服务（不推荐） |
disabled | 完全禁用 | 维护模式 |
部署 OpenClaw 时，请逐项检查以下安全配置：
每天自动收集工作信息，生成结构化日报：
# 创建技能目录mkdir-p ~/.openclaw/skills/daily-report # 设置定时任务crontab-e# 添加：每天下午 6 点生成日报018 * * * openclaw agent --message"生成今日工作日报"
基于知识库自动回答用户问题：
常见问题
投诉/退款
接收消息
关键词匹配
自动回复
转人工
自动审查代码提交，提供改进建议：
# 配置 Git Hookecho'#!/bin/bash openclaw agent --message "审查本次代码提交：$(git diff HEAD~1)"'> .git/hooks/post-commit chmod +x .git/hooks/post-commit
# 查找占用 18789 端口的进程lsof-i :18789 # 终止进程kill-9<PID># 或更换端口 openclaw gateway --port18888
# 使用终端二维码渲染 openclaw channels login whatsapp --qr-terminal
# 切换到更快的模型 openclaw config set models.default.model gpt-4o-mini # 或使用本地模型 openclaw config set models.default.provider ollama openclaw config set models.default.model deepseek-r1:7b
# 备份整个配置目录tar-czf openclaw-backup-$(date +%Y%m%d).tar.gz ~/.openclaw/ # 恢复备份tar-xzf openclaw-backup-20260315.tar.gz -C ~/
# 实时查看日志 openclaw logs --follow# 查看最近 100 行 openclaw logs --lines100# 日志文件位置cat ~/.openclaw/logs/gateway.log
| 维度 | 优势 |
|---|---|
| 隐私 | 完全自托管，数据不出本地 |
| 灵活 | 支持 20+ 消息平台，统一接入 |
| 经济 | 开源免费，成本可控 |
| 强大 | 浏览器控制、定时任务、技能扩展 |
| 安全 | 多层防护，企业级加固方案 |
参考资料：
微信公众号「极客日志」，在微信中扫描左侧二维码关注。展示文案：极客日志 zeeklog
解析常见 curl 参数并生成 fetch、axios、PHP curl 或 Python requests 示例代码。 在线工具，curl 转代码在线工具，online
将字符串编码和解码为其 Base64 格式表示形式即可。 在线工具，Base64 字符串编码/解码在线工具，online
将字符串、文件或图像转换为其 Base64 表示形式。 在线工具，Base64 文件转换器在线工具，online
将 Markdown（GFM）转为 HTML 片段，浏览器内 marked 解析；与 HTML转Markdown 互为补充。 在线工具，Markdown转HTML在线工具，online
将 HTML 片段转为 GitHub Flavored Markdown，支持标题、列表、链接、代码块与表格等；浏览器内处理，可链接预填。 在线工具，HTML转Markdown在线工具，online
通过删除不必要的空白来缩小和压缩JSON。 在线工具，JSON 压缩在线工具，online