Openclaw真的不值得研究了吗？---------openclaw细谈

taohuaracing

215人浏览 · 2026-06-03 23:53:18

taohuaracing · 2026-06-03 23:53:18 发布

OpenClaw 技术解密

最后更新时间：2026-06-03 | 作者：taohaoracing
适合读者：开发者、自部署用户、对 AI 网关架构感兴趣的人

1. 概述

1.1 什么是 OpenClaw

OpenClaw 是一个 单用户 AI 助手网关。它不像 ChatGPT 那样是一个网页聊天框，而是一个运行在你机器上的服务，负责：

连接各种 LLM（大语言模型）—— OpenAI、Claude、Gemini、DeepSeek、本地模型等
连接各种聊天平台 —— WhatsApp、Telegram、Discord、Signal、微信等
提供 Agent 能力和工具调用 —— Shell、浏览器、文件系统、代码编辑
提供 WebSocket/HTTP API 供 CLI、Web UI、桌面端、移动端连接

1.2 一句话总结

OpenClaw = AI 网关 + Agent 运行时 + 多平台连接器 — 让你自己的 AI 助手随时随地可用。

2. 整体架构

2.1 核心原则

原则	说明
单网关	一台机器上只运行一个 Gateway 实例，所有客户端都连接到它
协议统一	所有接入方走同一个 WebSocket 协议——控制平面、频道、节点都是 WS 客户端
串行会话	每个会话（Session）内的 Agent 执行是串行的，避免竞态
可插拔	模型提供者、频道、插件、上下文引擎都是插件化的
单用户模型	设计为单用户个人助手，不是多租户 SaaS

3. Gateway — 中枢网关

Gateway 是 OpenClaw 的心脏——一个常驻的后台守护进程。

3.1 启动与生命周期

openclaw gateway

默认监听 127.0.0.1:18789
同时提供 WebSocket + HTTP 服务（同一个端口）
退出方式：Ctrl+C、系统信号、或 openclaw gateway stop
可以通过 launchd（macOS）或 systemd（Linux）实现自动重启

3.2 端口与服务

路径	说明
`ws://127.0.0.1:18789`	WebSocket 主协议端口
`http://127.0.0.1:18789/`	Control UI（SPA 管理界面）
`http://127.0.0.1:18789/__openclaw__/canvas/`	Canvas 容器（Agent 可编辑的 HTML/CSS/JS）
`http://127.0.0.1:18789/__openclaw__/a2ui/`	A2UI 容器
`http://127.0.0.1:18789/v1/chat/completions`	OpenAI 兼容的 HTTP API
`http://127.0.0.1:18789/v1/responses`	OpenAI Responses API

3.3 Gateway 核心职责

维护外部连接 — WhatsApp（Baileys 库）、Telegram（grammY）、Discord、Signal 等
提供认证授权 — Token / Password / OAuth 认证 + 设备配对
暴露 WebSocket API — 客户端通过 WS 发请求、收事件
调度 Agent 执行 — 管理 Agent Loop 的生命周期
管理会话 — 创建、路由、持久化会话
执行定时任务 — Cron 调度
节点编排 — 管理 iOS/Android/macOS 等节点设备
处理审批 — exec 执行审批、配对审批

3.4 状态存储

所有数据存储在 ~/.openclaw/ 目录下：

~/.openclaw/
├── openclaw.json              # 配置文件
├── agents/
│   └── <agentId>/
│       ├── agent/
│       │   └── auth-profiles.json   # API Key / OAuth 凭据
│       ├── sessions/
│       │   ├── sessions.json        # 会话索引
│       │   └── <sessionId>.jsonl    # 会话对话记录
│       └── workspace/               # Agent 工作区
├── credentials/                # 频道凭据
├── sandboxes/                  # 沙箱工作区
└── secrets.json                # 可选：文件级别密文

4. WebSocket 协议详解

这是 OpenClaw 最核心的部分——所有通信都基于此协议。

4.1 传输层

传输方式：WebSocket，Text Frame（JSON 负载）
协议版本：当前 v4
默认端口：18789
重连策略：初始 1s → 指数退避 → 最多 30s

4.2 帧格式

所有消息都是 JSON 格式的 Text Frame：

请求（Request）

{
  "type": "req",
  "id": "uuid-or-counter",
  "method": "send",
  "params": { ... }
}

响应（Response）

{
  "type": "res",
  "id": "匹配请求的 id",
  "ok": true,
  "payload": { ... }
}

错误响应：

{
  "type": "res",
  "id": "...",
  "ok": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Session not found",
    "details": { ... }
  }
}

事件（Event — 服务器主动推送）

{
  "type": "event",
  "event": "chat",
  "payload": { ... },
  "seq": 42,
  "stateVersion": 3
}

4.3 握手流程（最关键的流程）

Client                          Gateway
  |                               |
  |  -------- 连接 WebSocket --------->|
  |                               |
  |  <--- connect.challenge -------|   服务器发送随机 nonce
  |       {nonce, ts}             |
  |                               |
  |  -------- connect req -------->|   客户端签名 nonce 并发起连接
  |       {minProtocol:3,         |
  |        maxProtocol:4,         |
  |        role:"operator",       |
  |        auth:{token:"..."},    |
  |        device:{id:"...",      |
  |                signature:"..",|
  |                nonce:"...",   |
  |                publicKey,     |
  |                signedAt},     |
  |        ...}                   |
  |                               |
  |  <-------- hello-ok ----------|   握手成功
  |       {protocol:4,            |
  |        server:{version,connId},
  |        features:{methods:[],  |
  |                  events:[]},  |
  |        auth:{role,scopes,     |
  |              deviceToken},    |
  |        snapshot:{presence,...},
  |        policy:{maxPayload,    |
  |                maxBufferedBytes,
  |                tickIntervalMs}}
  |                               |
  |  <---- event:presence --------|   实时状态推送
  |  <---- event:tick ------------|   心跳保活
  |  <---- event:chat/agent ------|   消息/Agent流式输出

4.4 认证方式

模式	配置	说明
Token	`gateway.auth.mode: "token"`	共享 Bearer Token，推荐
Password	`gateway.auth.mode: "password"`	密码认证，通过 `OPENCLAW_GATEWAY_PASSWORD` 环境变量
Trusted-proxy	`gateway.auth.mode: "trusted-proxy"`	信任反向代理的身份头
Tailscale	`gateway.auth.allowTailscale: true`	通过 Tailscale WhoIs 验证身份
无认证	`gateway.auth.mode: "none"`	⚠️ 仅限私密内网

4.5 设备配对

所有 WS 客户端需要提供稳定的 device.id（基于密钥对指纹）。新设备需要配对批准：

客户端首次连接 → 服务器返回 PAIRING_REQUIRED
配对请求（node.pair.request）→ 等待 operator 批准
批准后，服务器发放 device token（hello-ok.auth.deviceToken）
客户端持久化 device token，后续重连使用
本地 loopback 连接可以自动批准

4.6 幂等性

涉及副作用的 RPC（send、agent）需要幂等键 idempotencyKey，服务器有短时去重缓存。

4.7 常用 RPC 方法分类

类别	方法
系统/健康	`health`, `status`, `system-presence`, `gateway.identity.get`
Agent	`agent`, `agent.wait`, `agent.identity.get`
会话	`sessions.list`, `sessions.get`, `sessions.send`, `sessions.abort`, `sessions.reset`
聊天	`chat.history`, `chat.send`, `chat.abort`
消息发送	`send`
配置	`config.get`, `config.set`, `config.patch`, `config.apply`, `config.schema.lookup`
模型	`models.list`, `usage.status`, `usage.cost`
频道	`channels.status`, `channels.logout`
Cron	`cron.list`, `cron.add`, `cron.update`, `cron.remove`, `cron.run`
节点	`node.list`, `node.invoke`, `node.pair.`, `node.pending.`
设备	`device.pair.`, `device.token.`
审批	`exec.approval.`, `plugin.approval.`
Talk/TTS	`talk.`, `tts.`
其他	`skills.*`, `tools.catalog`, `tools.invoke`, `update.run`

5. 连接方式

5.1 CLI 连接

# 本地
openclaw status              # 走 WS 连接 localhost
openclaw agent --message "你好"

# 远程（SSH 隧道）
ssh -N -L 18789:127.0.0.1:18789 user@host
openclaw agent --message "你好"  # 通过隧道

# 远程（Tailscale）
openclaw status --gateway http://100.x.x.x:18789

5.2 Web UI / Control UI

浏览器打开 http://127.0.0.1:18789
可在 Dashboard 中聊天、管理会话、配置、查看节点
远程访问：Tailscale Serve 或 SSH 隧道

5.3 macOS 桌面应用

原生 Swift 客户端
通过 WS 连接 Gateway
支持 Canvas、暗色模式等

5.4 iOS/Android 节点 App

App Store / Google Play 安装
扫码配对或手动输入 Gateway 地址
功能：麦克风、相机、屏幕录制、位置、Canvas

5.5 第三方连接

任何语言都可以实现 WS 客户端连接 OpenClaw
协议定义在 packages/gateway-protocol/src/schema/frames.ts
有 TypeBox Schema 定义，可生成 Swift/TypeScript 模型

6. Agent 运行时

这是 OpenClaw 最核心的智能部分——AI Agent 的完整执行循环。

6.1 完整 Agent Loop 生命周期

6.2 System Prompt 结构

OpenClaw 每次 Agent 运行时都会动态组装 System Prompt。结构如下：

┌──────────────────────────────────────┐
│  OpenClaw 基础指令                    │ ← 固定模板
├──────────────────────────────────────┤
│  项目上下文文件 (Project Context)     │ ← 缓存友好
│  - AGENTS.md                         │
│  - SOUL.md                           │
│  - IDENTITY.md                       │
│  - USER.md                           │
│  - TOOLS.md                          │
│  - MEMORY.md (摘要)                  │
├──────────────────────────────────────┤
│  Skills 列表                         │ ← 按需加载
├──────────────────────────────────────┤
│  频道上下文 (Group Chat Context)      │ ← 变化部分
├──────────────────────────────────────┤
│  Messaging 指令                      │ ← 变化部分
├──────────────────────────────────────┤
│  运行时信息 (Runtime)                 │ ← 每次不同
│  - 时间/时区                         │
│  - 模型/OS/Node 版本                 │
│  - 推理模式                           │
└──────────────────────────────────────┘

6.3 工具系统

Agent 可以调用多种工具，通过 JSON Schema 定义：

工具组	包含工具	说明
文件系统	`read`, `write`, `edit`	读写编辑文件
Shell	`exec`, `process`	执行命令
浏览器	`browser.*`	网页浏览操作
网络	`web_fetch`, `web_search`	获取网页/搜索
记忆	`memory_search`, `memory_get`	长时记忆
会话	`sessions_spawn`, `sessions_send`	子 Agent 管理
网关	`gateway`	配置管理（限 operator）
Cron	`cron.*`	定时任务（限 operator）
感知	`session_status`, `image`	状态/图像分析
节点	`node.invoke`	调用设备节点

6.4 集成 Hook 系统

Agent 生命周期中的可拦截点：

Hook	触发时机
`before_model_resolve`	解析模型之前
`before_prompt_build`	组装 System Prompt
`before_agent_reply`	Agent 回复之前，可劫持回复
`before_tool_call` / `after_tool_call`	工具调用前后
`before_compaction` / `after_compaction`	上下文压缩前后
`agent_end`	Agent 运行结束
`message_received` / `message_sending` / `message_sent`	消息生命周期
`gateway_start` / `gateway_stop`	Gateway 生命周期

6.5 Agent 运行时架构

代码路径：src/agents/embedded-agent-runner/

src/
├── agents/
│   ├── embedded-agent-runner/    # 内置 Agent 循环
│   ├── sessions/                 # 会话、扩展、技能加载
│   ├── agent-tools*.ts           # 工具定义
│   ├── agent-hooks/              # 内置 Hook
│   └── runtime/                  # OpenClaw 运行时封装
├── llm/                          # 模型/Provider 注册和传输
└── packages/
    └── agent-core/               # 可复用的 Agent 核心

6.6 上下文压缩（Compaction）

当会话接近 Token 限制时自动触发：

记录"记忆快照"前通知（提醒 Agent 保存重要笔记到 MEMORY.md）
将较早的对话总结为紧凑摘要
保留最近的对话完整
磁盘上的完整历史不删除，只影响模型看到的上下文

手动压缩：/compact Focus on <topic>

7. 会话管理

7.1 消息路由规则

来源	路由行为
私聊	默认共享会话（可配置为 per-peer 隔离）
群聊	每个群独立会话
频道/房间	每个房间独立会话
Cron 任务	每次运行新会话
Webhook	每个 Webhook 独立会话

7.2 会话生命周期

每日重置 — 默认凌晨 4:00 新建会话
空闲重置 — 可选，配置 session.reset.idleMinutes
手动重置 — /new 或 /reset
模型切换 — /new <model>

7.3 DM 隔离模式

{
  session: {
    dmScope: "per-channel-peer" // 按(频道+发送者)隔离 - 推荐
    // "main"            - 所有DM共享（默认）
    // "per-peer"          - 按发送者隔离（跨频道）
    // "per-account-channel-peer" - 按账号+频道+发送者
  }
}

7.4 会话存储

~/.openclaw/agents/<agentId>/sessions/
├── sessions.json           # 会话索引
├── xxxxxx.jsonl            # 单条会话完整对话（JSON Lines）
└── xxxxxx.compacted.jsonl  # 压缩后的对话存档

每个 JSONL 条目是一条消息或系统事件，格式：

{"role":"user","content":"你好","ts":1700000000000}

8. 模型提供者体系

8.1 支持的提供者

OpenClaw 支持 30+ 模型提供者，核心分类：

分类	提供者	示例模型 ref
商业云 API	OpenAI	`openai/gpt-5.5`
	Anthropic	`anthropic/claude-opus-4-6`
	Google	`google/gemini-3.1-pro-preview`
	DeepSeek	`deepseek/deepseek-v4-flash`
	Z.AI (GLM)	`zai/glm-5.1`
	Moonshot (Kimi)	`moonshot/kimi-k2.6`
OAuth 订阅	OpenAI Codex	`openai/gpt-5.5` (native route)
	Z.AI Coding	`zai/glm-5.1`
	MiniMax	`minimax/MiniMax-M2.7`
	xAI (Grok)	`xai/grok-4.3`
聚合/代理	OpenRouter	`openrouter/auto`
	Kilo	`kilocode/kilo/auto`
	OpenCode	`opencode/claude-opus-4-6`
本地/自托管	Ollama	`ollama/llama3.3`
	LM Studio	`lmstudio/<model>`
	vLLM	`vllm/<model>`
	SGLang	`sglang/<model>`
中国区	BytePlus/火山引擎	`volcengine-plan/ark-code-latest`
	通义千问	`qwen/qwen3.5-plus`
	StepFun	`stepfun/step-3.5-flash`
	MiniMax (CN)	`minimax-portal/MiniMax-M2.7`

8.2 模型引用格式

<provider>/<model-id>

例子：moonshot/kimi-k2.6、openai/gpt-5.5、deepseek/deepseek-v4-flash

8.3 模型 Fallback 链

当主模型不可用时（429、超时、上下文溢出），可以配置备选链：

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "moonshot/kimi-k2.6",
        "fallbacks": [
          "openai/gpt-5.4-mini",
          "anthropic/claude-sonnet-4-6"
        ]
      }
    }
  }
}

8.4 Provider 插件化的实现

每个 Provider 是一个插件，注册方式：

api.registerProvider({
  id: "moonshot",
  label: "Moonshot AI (Kimi)",
  // 负责：模型列表、认证、请求格式化、流解析、思考模式等
})

8.5 自定义 Provider

通过 models.providers 可以添加任意 OpenAI/Anthropic 兼容的端点：

{
  models: {
    providers: {
      myproxy: {
        baseUrl: "https://my-proxy.example.com/v1",
        apiKey: "${MY_API_KEY}",
        api: "openai-completions",
        models: [{ id: "custom-model", name: "My Model" }]
      }
    }
  }
}

9. 频道系统

9.1 完整频道列表

频道	连接方式	协议
WhatsApp	QR 配对	Baileys (非官方 WhatsApp Web)
Telegram	Bot Token	grammY
Discord	Bot Token	Discord Bot API + Gateway
Signal	CLI	signal-cli
iMessage	macOS 原生	imsg 桥接
QQ Bot	QQ Bot API	官方 API
微信	Tencent iLink	外部插件
Slack	App Token	Bolt SDK
Matrix	自建/公共	下载插件
飞书	Bot Token	内置插件
IRC	服务器连接	内置插件
LINE	Messaging API	下载插件
Twitch	IRC	内置插件
Zalo	Bot API	内置插件
Microsoft Teams	Bot Framework	内置插件
WebChat	WS 连接	Gateway WebSocket

9.2 频道接入架构

社交平台 ---> Gateway WS协议 ---> Agent Loop ---> LLM
                              ↓
                          Queue(会话队列)

每个频道是一个 WS 客户端或 HTTP webhook 接收器
消息入队，串行执行（避免并发竞态）
支持在群聊中通过 @提及或回复触发
支持 DM 配对/允许列表策略

9.3 频道策略（安全）

{
  channels: {
    whatsapp: {
      dmPolicy: "pairing",      // pairing(默认) | allowlist | open | disabled
      groups: {
        "*": { requireMention: true }  // 群聊需要 @提及
      }
    }
  }
}

10. 插件系统

10.1 插件类型

类型	说明	例子
Provider 插件	注册模型提供者	`openai`, `google`, `moonshot`
Channel 插件	注册聊天频道	`discord`, `qqbot`, `zalo`
Context Engine 插件	替换上下文组装引擎	`lossless-claw`
Memory 插件	替换记忆系统	自定义向量数据库
Tool 插件	注册新工具	自定义 API 工具
Hook 插件	注册生命周期钩子	自动化操作
UI 插件	贡献 Web UI 面板	Canvas, A2UI

10.2 插件声明

{
  "openclaw": {
    "extensions": ["extensions/index.ts"],
    "skills": ["skills/*.md"],
    "prompts": ["prompts/*.md"],
    "themes": ["themes/*.json"]
  }
}

10.3 插件钩子 API

api.registerHook("before_tool_call", async ({ tool, args }) => {
  if (tool === "exec" && args.command.includes("dangerous")) {
    return { block: true, reason: "Blocked by safety policy" };
  }
  return {};
});

10.4 安装方式

# 从 npm 安装
openclaw plugins install @my-org/my-plugin

# 从本地路径安装（开发）
openclaw plugins install -l ./my-plugin

# 查看已安装
openclaw plugins list

11. 节点系统

节点是 OpenClaw 的远程执行能力层。

11.1 节点角色

节点类型	能力
macOS 节点	Screen recording, camera, location, canvas, voice, system.run
iOS 节点	Camera, screen recording, canvas, location, voice
Android 节点	Camera, canvas, location
Headless 节点	system.run (远程命令执行)

11.2 节点配对流程

1. 节点 App 扫描 Gateway 的配对码 (QR)
2. 发送 node.pair.request
3. Gateway 通知 operator 审批（或 autoApproveCidrs）
4. operator 批准后，Gateway 发放 node device token
5. 节点使用 device token 连接
6. 节点声明 caps/commands/permissions

11.3 节点命令执行

# 通过 Gateway 在节点上执行命令
node.invoke system.run { command: "ls -la", cwd: "/tmp" }

# 需要审批的命令会触发 exec.approval.requested

11.4 节点与 Gateway 的信任模型

Gateway 为控制平面和策略面
节点为远程执行面（需配对后才能操作）
配对后的节点命令 = 受信 operator 在该节点上的操作
节点自身有独立的执行审批策略

12. 自动化与定时任务

12.1 Cron 定时任务

通过 cron 工具或 RPC 创建：

{
  "name": "daily-weather",
  "schedule": {
    "kind": "cron",
    "expr": "0 8 * * *",
    "tz": "Asia/Shanghai"
  },
  "payload": {
    "kind": "agentTurn",
    "message": "查一下今天上海的天气"
  },
  "sessionTarget": "isolated"  // 每次用独立会话
  // 或 "main" 用于系统事件
}

12.2 Heartbeat 心跳

Gateway 定期触发心跳事件
Agent 可以检查日历、邮件、提醒等
配置在 HEARTBEAT.md
心跳间隔可配置

12.3 TaskFlow（多步骤任务）

用于编排多步骤、有状态的异步任务：

TaskFlow: 订机票
  ├── 搜索航班 → 等待用户选择
  ├── 填写乘客信息
  ├── 等待支付确认
  └── 发送确认单

12.4 Webhook

接收外部系统推送，触发 Agent：

{
  hooks: {
    webhooks: [{
      id: "my-webhook",
      path: "/hooks/my-webhook",
      agentId: "main"
    }]
  }
}

13. 安全模型

13.1 核心假设

OpenClaw 设计为单用户个人助手，不是多租户安全边界。

假设	含义
一个 Gateway = 一个信任域	所有认证过的 operator 是同一个信任边界内
Gateway 配置是受信的	能改 `openclaw.json` = 能控制一切
节点操作是受信操作	配对后的节点 = 该 Gateway 的远程执行端
Prompt 注入无法完全解决	用工具策略、审批、沙箱做硬性防护

13.2 三层防护

1. 身份控制：谁能联系 Agent？
   - DM 配对 / 允许列表 / @提及

2. 作用域控制：Agent 能在哪里行动？
   - 群聊策略、工具白名单、沙箱

3. 模型控制：假设模型可被注入
   - 限制 Agent 的工具权限
   - 关键操作需要审批

13.3 工具策略配置

{
  tools: {
    profile: "messaging",      // messaging | minimal | standard | full
    deny: ["exec", "gateway", "cron"],  // 黑名单
    exec: {
      security: "deny",        // deny | allowlist | ask | full
      ask: "always"            // on-miss | always
    },
    fs: { workspaceOnly: true }  // 文件操作限制在工作区内
  }
}

13.4 安全审计

# 运行安全审计
openclaw security audit
openclaw security audit --deep
openclaw security audit --fix

检查项包括：

DM/Groups 策略是否开放
工具集是否过大
网络暴露情况
文件权限
执行审批配置

13.5 安全的基线配置

{
  gateway: {
    mode: "local",
    bind: "loopback",
    auth: { mode: "token", token: "your-long-random-token" }
  },
  session: {
    dmScope: "per-channel-peer"
  },
  tools: {
    profile: "messaging",
    deny: ["group:automation", "group:runtime", "group:fs", "sessions_spawn", "sessions_send"],
    fs: { workspaceOnly: true },
    exec: { security: "deny", ask: "always" }
  },
  channels: {
    whatsapp: {
      dmPolicy: "pairing",
      groups: { "*": { requireMention: true } }
    }
  }
}

14. 配置参考

14.1 核心配置文件：`~/.openclaw/openclaw.json`

{
  // === Gateway ===
  gateway: {
    port: 18789,
    bind: "loopback",      // loopback | lan | tailnet | custom
    auth: {
      mode: "token",
      token: "sk-xxx"
    },
    mode: "local",         // local | remote
    remote: {               // 远程连接另一个 Gateway
      url: "ws://other-machine:18789",
      token: "sk-xxx"
    }
  },

  // === Agent ===
  agents: {
    defaults: {
      model: {
        primary: "moonshot/kimi-k2.6",
        fallbacks: ["openai/gpt-5.4-mini"]
      },
      workspace: "~/agent-workspace",
      timeoutSeconds: 300,     // 单次会话超时（默认 48h）
      compaction: {            // 上下文压缩
        model: "moonshot/kimi-k2.5",
        notifyUser: true
      },
      heartbeats: true,       // 启用心跳
      userTimezone: "Asia/Shanghai"
    }
  },

  // === 模型提供者 ===
  models: {
    mode: "merge",           // merge | replace
    providers: {
      moonshot: {
        baseUrl: "https://api.moonshot.ai/v1",
        apiKey: "${MOONSHOT_API_KEY}",
        api: "openai-completions",
        models: [{ id: "kimi-k2.6" }]
      }
    }
  },

  // === 聊天频道 ===
  channels: {
    telegram: {
      token: "${TELEGRAM_BOT_TOKEN}",
      dmPolicy: "pairing",
      groups: { "*": { requireMention: true } }
    },
    discord: {
      token: "${DISCORD_BOT_TOKEN}"
    }
  },

  // === 工具/执行策略 ===
  tools: {
    exec: {
      security: "full",       // deny | allowlist | ask | full
      ask: "on-miss"          // on-miss | always
    },
    deny: ["gateway", "cron"]
  },

  // === 会话 ===
  session: {
    dmScope: "per-channel-peer",
    reset: {
      daily: true,            // 每日重置
      idleMinutes: 120        // 空闲 2h 后重置
    }
  },

  // === 日志 ===
  logging: {
    level: "info",           // debug | info | warn | error
    redactSensitive: "tools" // 在日志中脱敏工具输入输出
  }
}

14.2 常用调试命令

# 查看状态
openclaw status
openclaw status --all

# 查看会话
openclaw sessions --json
openclaw sessions --active 60

# 查看模型列表
openclaw models list
openclaw models list --provider moonshot

# 测试 Agent
openclaw agent --message "你好" --thinking low

# 日志
openclaw logs tail
openclaw doctor

# 安全
openclaw security audit --deep

14.3 环境变量参考

变量	说明
`OPENCLAW_GATEWAY_PASSWORD`	Gateway 密码认证
`OPENCLAW_STATE_DIR`	状态目录（默认 `~/.openclaw`）
`OPENCLAW_GATEWAY_PORT`	Gateway 端口（默认 18789）
`OPENCLAW_LIVE_MOONSHOT_KEY`	Moonshot API 单次覆盖
`OPENCLAW_LIVE_OPENAI_KEY`	OpenAI API 单次覆盖
`GEMINI_API_KEY`	Google Gemini Key
`ANTHROPIC_API_KEY`	Anthropic Key
`DEEPSEEK_API_KEY`	DeepSeek Key
`OPENAI_API_KEY`	OpenAI Key
`MOONSHOT_API_KEY`	Moonshot (Kimi) Key

附录：架构图总览

消息流完整路径

写在最后

OpenClaw 是一个把自己当作完整系统的 AI 网关。它不像传统的 bot 框架那样只做消息路由，而是：

理解会话 — 有完整的 Agent Loop + 上下文管理
理解工具 — 可以调用 Shell、API、文件、浏览器
理解设备 — 可以在你的手机上拍照、在你的 Mac 上录屏
理解时间 — 可以定时检查天气、邮件、日历
理解安全 — 有完整的配对、审批、沙箱体系

它的核心设计哲学是：一个用户 + 一个网关 + 多个智能体 = 你的 AI 右臂。

感谢你的耐心阅读，欢迎交流指正---------------taohuaracing

亚马逊云科技技术品牌专区

更多推荐

LangChain入门第一课：从零搭建你的AI智能体开发环境

亚马逊云科技技术品牌专区

如何看待 WAIC 2026？有哪些值得期待的技术与厂商？

亚马逊云科技技术品牌专区

1.26亿只宠物市场：设备厂家如何才能选对物联网卡服务商？

亚马逊云科技技术品牌专区

所有评论(0)

查看更多评论

taohuaracing

@taohuaracing

已为社区贡献1条内容

Openclaw真的不值得研究了吗？---------openclaw细谈

taohuaracing

OpenClaw 技术解密

目录

1. 概述

1.1 什么是 OpenClaw

1.2 一句话总结

2. 整体架构

2.1 核心原则

3. Gateway — 中枢网关

3.1 启动与生命周期

3.2 端口与服务

3.3 Gateway 核心职责

3.4 状态存储

4. WebSocket 协议详解

4.1 传输层

4.2 帧格式

请求（Request）

响应（Response）

事件（Event — 服务器主动推送）

4.3 握手流程（最关键的流程）

4.4 认证方式

4.5 设备配对

4.6 幂等性

4.7 常用 RPC 方法分类

5. 连接方式

5.1 CLI 连接

5.2 Web UI / Control UI

5.3 macOS 桌面应用

5.4 iOS/Android 节点 App

5.5 第三方连接

6. Agent 运行时

6.1 完整 Agent Loop 生命周期

6.2 System Prompt 结构

6.3 工具系统

6.4 集成 Hook 系统

6.5 Agent 运行时架构

6.6 上下文压缩（Compaction）

7. 会话管理

7.1 消息路由规则

7.2 会话生命周期

7.3 DM 隔离模式

7.4 会话存储

8. 模型提供者体系

8.1 支持的提供者

8.2 模型引用格式

8.3 模型 Fallback 链

8.4 Provider 插件化的实现

8.5 自定义 Provider

9. 频道系统

9.1 完整频道列表

9.2 频道接入架构

9.3 频道策略（安全）

10. 插件系统

10.1 插件类型

10.2 插件声明

10.3 插件钩子 API

10.4 安装方式

11. 节点系统

11.1 节点角色

11.2 节点配对流程

11.3 节点命令执行

11.4 节点与 Gateway 的信任模型

12. 自动化与定时任务

12.1 Cron 定时任务

12.2 Heartbeat 心跳

12.3 TaskFlow（多步骤任务）

12.4 Webhook

13. 安全模型

13.1 核心假设

13.2 三层防护

13.3 工具策略配置

13.4 安全审计

13.5 安全的基线配置

14. 配置参考

14.1 核心配置文件：~/.openclaw/openclaw.json

14.2 常用调试命令

14.3 环境变量参考

附录：架构图总览

消息流完整路径

14.1 核心配置文件：`~/.openclaw/openclaw.json`