用 OpenClaw 打造 AI 技术支持工程师：Claire 的深度实现揭秘

Claire 的角色定位

Claire 是为 Zadig 打造的专职技术支持 AI 工程师，本质上是运行在 OpenClaw 框架之上的一个领域型 Agent。她的两个核心职责是：

• 技术支持：围绕 Zadig 的安装、运维、工作流、环境、集成等问题做源码级诊断与排障。
• 社区知识运营：对飞书群中的技术交流进行结构化沉淀，形成每日总结、FAQ 和文档改进建议。

在这套体系中：

• Claire 负责“理解与决策”：根据源码、文档、FAQ 和历史记忆，给出可执行的诊断方案。
• OpenClaw 负责“基础设施与编排”：统一管理多家模型 Provider，控制工具与权限，接入飞书渠道，并加载工作区规则（如 AGENTS.md、IDENTITY.md、skills 等）。

本文将围绕 ~/.openclaw/openclaw.json 与 Claire 工作区中的配置文件，系统拆解 Claire 在 OpenClaw 上的技术实现。

1. 整体架构

Claire 是一个跑在 OpenClaw 运行时上的领域 Agent。OpenClaw 负责模型调用、工具编排、渠道接入、会话生命周期管理；Claire 的"个性"与"行为边界"完全由工作区内的配置文件定义，与运行时解耦。

OpenClaw 是纯粹的编排层，不参与回答内容的生成；模型推理与工具使用由 Agent 在 workspace 上下文约束下驱动。

2. 关键配置解析

2.1 模型 Provider 抽象

OpenClaw 通过 models.providers 统一注册多个模型来源，对 Agent 暴露为 "<provider>/<model_id>" 格式的引用：

"models": {
  "providers": {
    "claude": {
      "baseUrl": "claude url",
      "api": "anthropic-messages",
      "authHeader": true,
      "models": [{ "id": "claude-opus-4-6", "contextWindow": 200000, "maxTokens": 16000 }]
    },
    "minimax-portal": {
      "baseUrl": "minimax url",
      "api": "anthropic-messages",
      "models": [
        { "id": "MiniMax-M2.5",            "contextWindow": 600000 },
        { "id": "MiniMax-M2.5-highspeed",  "contextWindow": 600000 },
        { "id": "MiniMax-M2.5-Lightning",  "contextWindow": 600000 }
      ]
    }
  }
}

两个 Provider 都实现了 anthropic-messages 协议，因此 Agent 侧无需感知差异，切换模型时只改 ID 即可。

2.2 模型路由与降级

"agents": {
  "defaults": {
    "model": {
      "primary": "clauddy/claude-opus-4-6",
      "fallbacks": [
        "minimax-portal/MiniMax-M2.5-highspeed",
        "minimax-portal/MiniMax-M2.5-Lightning"
      ]
    }
  }
}

OpenClaw 按 primary → fallbacks[0] → fallbacks[1] 的顺序做透明降级。主模型限流或超时时自动切换，对 Agent 无感。

2.3 上下文压缩策略

"contextPruning": {
  "mode": "cache-ttl",
  "ttl": "1h"
},
"compaction": {
  "mode": "safeguard",
  "reserveTokensFloor": 20000,
  "maxHistoryShare": 0.7,
  "memoryFlush": {
    "enabled": true,
    "softThresholdTokens": 10000
  }
}

• cache-ttl：超过 1h 的对话轮次从活跃 context 中淘汰。
• safeguard：在 prompt 拼装阶段，历史最多占 70%，剩余空间留给当前轮次输入/输出。
• reserveTokensFloor: 20000：兜底保证至少 2 万 token 可用，防止长对话把当前输入空间压死。
• memoryFlush：当可用 token 低于 softThresholdTokens 时，触发"flush"——把近期对话中有价值的内容写入 MEMORY.md 后从 context 移除。

2.4 工具配置与 deny list

"tools": {
  "profile": "full",
  "deny": ["bash", "process", "browser", "canvas", "gateway", "cron", "nodes", "apply_patch", "image"],
  "web": {
    "search": { "enabled": false },
    "fetch":  { "enabled": true, "maxChars": 50000 }
  },
  "fs": { "workspaceOnly": true },
  "loopDetection": {
    "enabled": true,
    "warningThreshold": 10,
    "criticalThreshold": 20,
    "globalCircuitBreakerThreshold": 30
  },
  "exec": { "host": "gateway", "security": "allowlist", "ask": "off" }
}

重点：

• deny: ["bash", "process", "browser", "canvas", "gateway", "cron", "nodes", "apply_patch", "image"] 拒绝高危工具。
• fs.workspaceOnly：Agent 读文件只能读工作区路径，无法访问宿主机其他目录。
• web.search 关闭，web.fetch 开启：强制 Agent 优先走本地知识，必要时才 fetch 指定 URL，避免幻觉式搜索。
• loopDetection：工具调用次数到达阈值后分级熔断，防止提示注入或异常循环耗尽资源。
• exec.security: "allowlist"：exec 工具只执行预定义命令白名单（如 grep、find、ls），不允许任意 shell。

2.5 Feishu channel 配置

"channels": {
  "feishu": {
    "connectionMode": "websocket",
    "requireMention": true,
    "streaming": true,
    "blockStreaming": true,
    "replyMode": { "group": "streaming", "direct": "streaming" },
    "dmPolicy": "pairing",
    "threadSession": true,
    "footer": { "elapsed": true, "status": true }
  }
}

• connectionMode: "websocket"：长连接接收事件，不轮询。
• requireMention: true：群聊必须 @ 机器人才触发，避免抢答所有消息。
• threadSession: true：飞书线程 → openclaw session 一一映射，同一线程内的多条消息共享上下文。
• dmPolicy: "pairing"：私聊按 user-peer 维度绑定 session，不跨人混用。

2.6 内部 Hooks

"hooks": {
  "internal": {
    "enabled": true,
    "entries": {
      "boot-md":               { "enabled": true },
      "bootstrap-extra-files": { "enabled": true },
      "command-logger":        { "enabled": true },
      "session-memory":        { "enabled": true }
    }
  }
}

• boot-md：每次会话启动时把 AGENTS.md（以及通过 channel-context 注入的 USER.md）作为系统提示头部加载。
• session-memory：会话结束或触发 flush 时，把有价值的对话片段写入当天的记忆文件。
• command-logger：记录工具调用日志，用于审计和调试。

3. 工作区配置文件的作用机制

3.1 AGENTS.md — 运行时行为规则

AGENTS.md 由 boot-md hook 在每次会话启动时注入系统提示。它的内容对模型来说等同于最高优先级指令，包含：

• 身份覆盖：强制将模型的角色锁定为 Claire，防止用户通过提示工程改写身份。
• 工具使用约束（语义层）：与 openclaw.json 的工具 deny-list 配合，形成双层防护——deny-list 是硬性技术限制，AGENTS.md 是软性语义约束。
• 文件写入白名单（语义层）：规定哪些路径可以写，配合 fs.workspaceOnly 共同限制写操作范围。
• Prompt Injection 防护话术：对常见攻击模式（角色扮演、指令注入、权限提升）预定义拒绝策略。

3.2 多 Channel 隔离的实现

channels/
  registry.md                    ← 登记所有 channel_id
  <channel_id>/
    USER.md                      ← 该 channel 的用户画像（顶部注入 CHANNEL_CONTEXT）
    MEMORY.md                    ← 长期记忆
    memory/
      YYYY-MM-DD.md              ← 当日技术支持记录
      daily-summary/
        YYYY-MM-DD.md            ← 当日总结

channel-context hook 在 session 启动时：

1. 根据消息来源（群 ID / 用户 ID）推算 channel_id。
2. 将 <!-- CHANNEL_CONTEXT_START -->...<channel_id>...<!-- CHANNEL_CONTEXT_END --> 注入 USER.md 顶部。
3. AGENTS.md 要求 Agent 会话开始后必须先读取这段标记，才能确定后续所有读写的路径前缀。

由此实现多租户数据隔离，不同群的技术支持历史在文件系统层完全分开。

3.3 Skills — 领域知识的结构化封装

skills/ 目录下的每个 skill 是一个独立的 SKILL.md，在系统提示中按需加载。Claire 当前的 skill 体系：

skill	作用
zadig-doc-nav	220+ 文档文件的路径索引，防止 Agent 猜路径调 read 工具找不到路径造成 ENOENT
zadig-source-nav	源码搜索标准流程：SOURCE_INDEX → read → grep 兜底
zadig-error-patterns	常见错误日志 → 根因 → 修复的 lookup table
zadig-cluster-ops	K8s 诊断命令模板与输出分析指南
feishu-daily-summary	每日总结的数据结构规范、生成流程、输出模板

skill 的加载方式：openclaw 在拼装系统提示时，把所有启用的 skill 的 SKILL.md 内容拼接到提示中。skill 本质上是"被 include 的提示片段"，不是独立进程或函数。

4. 请求处理链路

几个实现细节：

• 配置流式输出：OpenClaw 拿到第一个 token 就开始回推飞书，飞书侧逐字刷新消息，延迟感低。

• 工具调用是同步阻塞的：Agent 在调用工具期间暂停生成，等工具返回后把结果追加到 context 再继续。多个工具调用串行执行，除非 Agent 显式并发（sessions_spawn，但在 claire 配置中已禁用 sessions_spawn）。

• memory 写入：session-memory hook 在会话结束（或 flush 触发）时写文件，不是每条消息都写。写入格式由 feishu-daily-summary/SKILL.md 规定，结构化为 Markdown 条目。

---

5. 工具调用的安全分层

用户请求
    │
    ▼
[语义层] AGENTS.md 规则 — 软约束，告诉模型"不该做什么"
    │
    ▼
[运行时层] openclaw tools.deny — 硬约束，deny-list 中的工具根本不暴露给模型
    │
    ▼
[文件系统层] fs.workspaceOnly — 即使模型尝试读写，OS 路径被限制
    │
    ▼
[exec 层] exec.security: "allowlist" — exec 工具只执行预定义命令

bash 工具被 deny，exec 工具被允许但走 allowlist。两者的区别：

• bash：任意 shell 命令，高风险。
• exec：openclaw 维护一个命令白名单（如 grep、find、ls），只有白名单内的命令才能执行，且参数经过校验。

Claire 的 exec 主要用途：在本地 repo 中做只读搜索（grep -rn、find、ls），作为 read + 索引文件的兜底手段。

6. 每日总结的数据流

feishu-daily-summary/SKILL.md 定义了这套数据结构与处理规则，包括：

• 分类标签优先级：[Bug反馈] > [功能需求] > [问题] > [解答] > [讨论]
• FAQ 补充触发条件：同一问题出现 ≥ 2 次 且 当前 faq/faq.md 未覆盖
• 飞书消息中的 @ 格式与本地 Markdown 中的记录格式分开处理（避免存储 lark 私有标记）

7. 问题诊断决策树（检索顺序）

源码的查阅流程遵循固定链路：

SOURCE_INDEX.md 
    → 找到文件路径
    → read handler 文件，找到入口函数
    → 追踪调用到 service 层
    → 追踪调用到 core 层
    → 理解错误返回的条件与分支
    → 有针对性地建议用户执行 kubectl 命令
    → 分析用户回传的日志输出
    → 得出结论

每次诊断通常涉及 3-5 个文件的 read，不是靠关键词匹配，而是真正读懂代码逻辑后才给结论。

8. 关键设计取舍（保证安全）

设计决策	选择	原因
web.search 关闭	禁用	避免幻觉式搜索，强制走本地知识库
exec vs bash	允许 exec + allowlist，禁 bash	保留只读搜索能力，拒绝任意命令执行
memory 按 channel 隔离	文件系统目录隔离	简单、可审计
技能用 SKILL.md 描述	纯提示片段 include	零运行时依赖，技能逻辑完全在提示层，易修改
每日总结数据结构	结构化 Markdown	人可读、Agent 也可解析
Agent 不执行 kubectl	只建议命令	避免 Agent 直接操作生产集群

总结与展望

综合来看，Claire 是一个运行在 OpenClaw 上的、配置驱动的 Zadig 技术支持 Agent：

• 通过 openclaw.json 中的模型与工具配置，实现了多 Provider 支持、模型路由与上下文管理。
• 通过 IDENTITY.md 与 AGENTS.md，将身份、职责与安全边界固化为工程化规则。
• 通过 TOOLS.md 与多种 Zadig skills，将领域知识与诊断经验结构化注入 Agent 行为。
• 通过 channels/<channel_id>/memory/ 与 feishu-daily-summary，实现了从单次对话到每日总结的知识沉淀闭环。

对希望在自家产品中使用 OpenClaw构建类似“专职技术支持 Agent”的团队而言，这套实现提供了一个清晰的思路：

• 用通用的 Agent 运行时（如 OpenClaw）处理模型、工具、渠道与会话。
• 用可版本化的本地文件（IDENTITY、AGENTS、TOOLS、skills）塑造 Agent 行为与边界。
• 用企业 IM 作为入口，用按 Channel 隔离的记忆体系承载一线知识。

在此基础上，未来可以进一步扩展：

• 基于每日总结自动生成内部周报或改进 backlog，更系统地驱动文档与产品迭代。
• 将类似的 Agent 模式复制到其他子领域（如“运维顾问”“性能优化助手”），形成协同工作的多 Agent 体系。