OpenClaw 原理详解：自托管 AI 网关架构深度剖析

3.3 认证与配对

• 网关令牌：通过 OPENCLAW_GATEWAY_TOKEN 或 --token 设置
• 设备配对：新设备需要配对批准，网关颁发设备令牌
• 本地信任：环回地址或同一 Tailscale 网络的连接可自动批准
• 签名挑战：所有连接必须签名 connect.challenge nonce

四、会话管理系统

4.1 会话键设计

OpenClaw 使用分层会话键来隔离不同场景的对话上下文：

agent:<agentId>:<channel>:<type>:<id> 

4.2 会话重置策略

{ session: { reset: { mode: "daily", // 每日重置 atHour: 4, // 凌晨 4 点 idleMinutes: 120, // 或 120 分钟空闲后重置 }, dmScope: "per-channel-peer", // 推荐：按渠道 + 发送者隔离 } }

4.3 会话存储

• 会话元数据：~/.openclaw/agents/<agentId>/sessions/sessions.json
• 对话记录：~/.openclaw/agents/<agentId>/sessions/<SessionId>.jsonl
• 维护策略：自动修剪旧会话、归档转录文件、轮转存储

五、工具系统

OpenClaw 为 AI 代理提供第一类工具，无需 shell 调用，类型安全：

5.1 核心工具组

5.2 工具策略

{ tools: { profile: "coding", // 基础配置：coding | messaging | minimal | full allow: ["group:fs", "browser"], // 白名单 deny: ["group:runtime"], // 黑名单（优先） byProvider: { "google-antigravity": { profile: "minimal" }, // 按提供商限制 }, } }

5.3 浏览器自动化流程

Start -> browser: status -> Browser Running? -> Yes -> browser: snapshot -> browser: act -> Need Screenshot? -> Yes -> browser: screenshot -> Done

六、多代理路由

OpenClaw 支持运行多个隔离的代理，每个代理有独立的工作空间和会话：

{ agents: { list: [ { id: "home", default: true, workspace: "~/.openclaw/workspace-home" }, { id: "work", workspace: "~/.openclaw/workspace-work" }, ], bindings: [ { agentId: "home", match: { channel: "whatsapp", accountId: "personal" } }, { agentId: "work", match: { channel: "whatsapp", accountId: "biz" } }, ], } }

路由匹配流程

Message Received -> Has Binding Rule? -> Yes -> Match Channel/Account -> Route to Agent -> Load Workspace -> Inject Config Files -> Agent Responds

七、工作空间与记忆系统

7.1 工作空间文件

7.2 记忆持久化

心跳维护 -> 短期记忆 -> 提炼 -> 长期记忆 -> 定期审查

八、安全与权限

8.1 DM 访问控制

{ channels: { whatsapp: { dmPolicy: "pairing", // pairing | allowlist | open | disabled allowFrom: ["+15555550123"], groups: { "*": { requireMention: true }, // 群聊需要@提及 }, }, }, }

8.2 沙箱隔离

{ agents: { defaults: { sandbox: { mode: "non-main", // off | non-main | all scope: "agent", // session | agent | shared }, }, }, }

8.3 工具权限

• 执行批准：exec 命令可配置为需要用户批准
• 工作空间限制：apply_patch 默认仅限工作空间内
• 提升权限：elevated 模式需要显式配置

九、自动化能力

9.1 心跳检查

{ agents: { defaults: { heartbeat: { every: "30m", target: "last", // last | whatsapp | telegram | discord | none }, }, }, }

9.2 Cron 任务

{ cron: { enabled: true, maxConcurrentRuns: 2, sessionRetention: "24h", }, }

9.3 Webhooks

{ hooks: { enabled: true, token: "shared-secret", mappings: [ { match: { path: "gmail" }, action: "agent", agentId: "main", deliver: true, }, ], }, }

十、配置热重载

OpenClaw 支持配置热重载，无需手动重启：

{ gateway: { reload: { mode: "hybrid" }, // hybrid | hot | restart | off }, }

十一、快速开始

11.1 安装

npm install -g openclaw@latest 

11.2 初始化

openclaw onboard --install-daemon 

11.3 配置渠道

openclaw channels login # WhatsApp 配对

11.4 启动网关

openclaw gateway --port 18789

11.5 打开控制 UI

访问 http://127.0.0.1:18789

十二、总结

OpenClaw 的核心创新在于：

1. 统一网关架构：一个进程服务所有渠道，简化部署和维护
2. 会话隔离：灵活的会话键设计，支持多用户、多场景隔离
3. 工具系统：类型安全的内置工具，无需 shell 调用
4. 自托管优先：数据完全掌控，隐私有保障
5. 扩展性强：插件系统支持自定义渠道和工具

对于希望构建个人 AI 助手的开发者来说，OpenClaw 提供了一个开箱即用、高度可定制的基础架构。无论是简单的消息回复机器人，还是复杂的多代理协作系统，OpenClaw 都能胜任。

参考资源

• 官方文档：https://docs.openclaw.ai
• GitHub: https://github.com/openclaw/openclaw