第三部分：核心概念深入

本部分是理解 OpenClaw 的基石。掌握智能体运行时、会话管理、记忆系统、模型配置和消息处理这五大核心模块，你就能真正驾驭 OpenClaw 的全部能力。

第 6 章：智能体（Agent）运行时

OpenClaw 的核心是一个内嵌的 AI 智能体运行时。理解它的工作原理，是使用好 OpenClaw 的第一步。

6.1 Pi-mono 智能体引擎

OpenClaw 采用基于 pi-mono 的单一嵌入式智能体运行时。这不是一个简单的"聊天机器人"——它是一个能够执行工具、管理文件、浏览网页、发送跨平台消息的自主智能体。

Pi 是 OpenClaw 唯一的编码智能体路径（早期的 Claude、Codex、Gemini 等遗留路径已全部移除）。这意味着所有代码执行、工具调用、文件操作都通过 Pi 运行时完成。

6.2 工作区（Workspace）

工作区是智能体的唯一工作目录，也是它的记忆中枢。

默认位置：

~/.openclaw/workspace

如果启用了自定义 Profile，则为 ~/.openclaw/workspace-<profile>。

配置方式：

在 ~/.openclaw/openclaw.json 中设置：

json5

{
  agents: {
    defaults: {
      workspace: "~/my-agent-workspace"
    }
  }
}

关键区别：工作区存放智能体的工作文件和记忆，而 ~/.openclaw/ 目录存放系统配置、认证凭据和会话数据。两者分开管理。

工作区的标准文件结构：

workspace/
├── AGENTS.md          # 操作指引与行为规则
├── SOUL.md            # 人格、沟通风格与边界
├── USER.md            # 用户身份与称呼偏好
├── IDENTITY.md        # 智能体名称与 emoji 标识
├── TOOLS.md           # 本地工具文档与约定
├── HEARTBEAT.md       # 可选：定期自动运行的检查清单
├── BOOT.md            # 可选：网关重启时执行的启动流程
├── BOOTSTRAP.md       # 一次性首次运行仪式
├── MEMORY.md          # 可选：长期策展记忆（仅私聊加载）
├── memory/            # 日期归档的每日日志
│   ├── 2026-02-10.md
│   └── 2026-02-11.md
├── skills/            # 工作区级别的技能覆盖
└── canvas/            # 可选：UI 配置文件

安全提示：不要在工作区中存放 API 密钥、OAuth Token、密码等敏感凭据，即使在使用版本控制的情况下。

备份建议：将工作区初始化为私有 Git 仓库，推送到 GitHub/GitLab。这样可以在系统迁移时保留智能体的完整记忆。

6.3 Bootstrap 启动文件体系

每当创建新会话时，OpenClaw 会自动注入以下六个用户可编辑文件到智能体的上下文中。这是智能体"醒来"时首先看到的内容：

AGENTS.md — 操作指引与记忆

这是智能体的行为手册。定义操作规则、工作流程、记忆策略等。相当于给智能体一份"员工手册"。

markdown

# 操作指引

## 工作规则
- 回复保持简洁，除非用户要求详细说明
- 处理文件时先确认路径再操作
- 每次完成重要任务后，更新 memory/ 日志

## 记忆策略
- 重要决策记录到 MEMORY.md
- 日常对话记录到 memory/YYYY-MM-DD.md

SOUL.md — 人格定义与边界

定义智能体的性格、沟通方式和行为边界。这决定了智能体"是谁"。

markdown

# 人格定义

你是一个专注高效的技术助手。
- 语气：友好但专业
- 风格：直接给出答案，避免冗长铺垫
- 边界：不讨论政治话题，不生成有害内容
- 幽默：可以适当使用，但不要过度

TOOLS.md — 工具文档

记录本地工具的使用方法和约定。当智能体需要执行命令或使用特定工具时，会参考这个文件。

markdown

# 工具约定

## 项目构建
- 使用 `bun` 而非 `npm`
- 测试命令：`bun test`
- 构建命令：`bun run build`

## 数据库
- PostgreSQL 运行在 localhost:5432
- 使用 `psql -U admin -d mydb` 连接

BOOTSTRAP.md — 一次性初始化

这个文件仅在首次运行时注入，执行后自动标记为已完成。适合放置初始化指令，比如"阅读项目结构"或"扫描代码库"。

markdown

# 首次启动任务

1. 阅读 ~/projects/myapp 的目录结构
2. 熟悉 package.json 中的依赖
3. 将项目概要记录到 MEMORY.md

IDENTITY.md — 名称与角色

一行简洁的身份声明。

markdown

名称：小智
角色：全栈开发助手

USER.md — 用户画像

告诉智能体关于你的信息，让回复更个性化。

markdown

# 用户信息

- 姓名：熊老板
- 职业：全栈工程师
- 常用技术栈：TypeScript, React, Node.js, PostgreSQL
- 偏好：中文交流，代码注释用英文
- 时区：Asia/Shanghai

注入规则：

空白文件会被跳过
超大文件会被截断（默认上限 20,000 字符），并添加截断标记
缺失的文件会使用默认模板（除非设置了 agent.skipBootstrap: true）
子智能体会话仅注入 AGENTS.md 和 TOOLS.md

6.4 智能体执行循环（Agent Loop）

Agent Loop 是智能体处理每条消息的完整生命周期。理解这个循环有助于你诊断问题和优化性能。

完整执行流程

用户消息 → 验证 & 会话解析 → 上下文组装 → 模型推理 → 工具执行 → 流式输出 → 持久化

详细分为四个阶段：

阶段一：验证与会话建立

收到 RPC 调用后，系统验证参数、解析目标会话，立即返回 { runId, acceptedAt }（不等待完成）。

阶段二：智能体命令处理

系统解析模型默认配置，加载技能快照，调用 pi-agent-core 运行时。

阶段三：嵌入式 Pi-Agent 运行

这是核心执行阶段：

通过每会话队列和全局队列序列化执行，防止竞态条件
解析认证凭据
构建会话上下文（系统提示 + 工具描述 + 技能 + 历史对话 + Bootstrap 文件）
订阅 Pi 事件流
强制执行超时（默认 600 秒）
返回使用量元数据

阶段四：事件桥接

Pi-agent-core 的内部事件映射到 OpenClaw 的流事件：

Pi 事件	OpenClaw 流	说明
tool events	`stream: "tool"`	工具调用与结果
assistant deltas	`stream: "assistant"`	助手文本增量
lifecycle events	`stream: "lifecycle"`	启动/完成/错误

队列与并发

运行在每个会话键（Session Key）内是严格串行的——同一会话不会有两个并行的 Agent Loop。但不同会话可以并行执行，受全局并发上限控制（默认 main 队列 4 个，subagent 队列 8 个）。

Hook 介入点

在执行的不同阶段，Hook 可以介入：

agent:bootstrap：智能体初始化时
before_agent_start：模型推理前
after_tool_call：工具调用后
tool_result_persist：工具结果持久化时

终止条件

Agent Loop 可能因以下原因提前终止：

超时（默认 600 秒）
AbortSignal 取消
网关断开连接
agent.wait 超时

6.5 系统提示（System Prompt）构建

OpenClaw 为每次智能体运行动态构建系统提示，这不是一个静态模板。

系统提示包含的内容

组成部分	说明
Tooling	可用工具及其简要描述
Safety	防止智能体追求权力或规避监督的护栏
Skills	按需加载技能文件的指令
Self-Update	运行 `config.apply` 和 `update.run` 的引导
Workspace	工作目录路径引用
Documentation	本地文档路径
Workspace Files	Bootstrap 文件指示器
Sandbox	运行时沙箱详情（如启用）
Current Date & Time	用户时区和格式
Runtime	主机、OS、Node 版本、模型、思考级别等

三种渲染模式

模式	适用场景	说明
`full`	默认	包含所有部分
`minimal`	子智能体	省略 Skills、Memory、Messaging 等
`none`	特殊场景	仅返回基础身份行

Bootstrap 文件注入规则

以下文件会被自动修剪后注入上下文：

AGENTS.md, SOUL.md, TOOLS.md, IDENTITY.md, USER.md,
HEARTBEAT.md, BOOTSTRAP.md, MEMORY.md

每文件最大注入量通过 agents.defaults.bootstrapMaxChars 控制，默认 20,000 字符
子智能体会话仅注入 AGENTS.md 和 TOOLS.md

重要理解：安全护栏是建议性的，不是强制执行机制。真正的硬性防护来自工具策略（tools.allow/deny）、执行审批和沙箱。

第 7 章：会话管理

会话（Session）是 OpenClaw 中对话的组织单元。理解会话机制是管理多用户、多渠道场景的关键。

7.1 会话架构

OpenClaw 将每个智能体的一个私聊会话指定为主会话（Primary Session）。所有私聊消息默认汇聚到这个主会话，而群组/频道消息则获得独立的会话键。

会话键格式：

agent:<agentId>:<mainKey>

默认 mainKey 为 main。

网关是会话的唯一权威来源——远程 UI 客户端必须查询网关获取会话数据，而非直接读取本地文件。

7.2 会话作用域（DM Scope）

session.dmScope 参数控制私聊消息的组织方式，这直接影响用户之间的隐私隔离：

模式	说明	适用场景
`main`	所有私聊共享同一会话（默认）	个人使用，只有你一个人和机器人聊天
`per-peer`	按发送者隔离，跨渠道共享	多人使用，不同人的对话互不干扰
`per-channel-peer`	按渠道 + 发送者隔离	多用户多渠道场景
`per-account-channel-peer`	按账号 + 渠道 + 发送者隔离	多账号多渠道高隔离场景

隐私隔离的重要性

如果你允许多个用户与同一个智能体对话，却使用默认的 main 模式，会发生什么？

场景：
1. Alice 告诉机器人："我的密码是 abc123"
2. Bob 随后问："之前聊了什么？"
3. 模型可能会暴露 Alice 的密码！

修复方案：多用户场景必须启用隔离模式：

json5

{
  session: {
    dmScope: "per-channel-peer"  // 按渠道+发送者隔离
  }
}

跨渠道身份关联

如果同一用户通过 WhatsApp 和 Telegram 联系你的机器人，默认情况下会被视为两个不同用户。使用 session.identityLinks 可以关联他们：

json5

{
  session: {
    identityLinks: [
      {
        whatsapp: "+8613800138000",
        telegram: "123456789"
      }
    ]
  }
}

7.3 会话存储

存储路径：

~/.openclaw/agents/<agentId>/sessions/
├── sessions.json           # 会话索引（所有会话的元数据）
├── <SessionId>.jsonl       # 会话记录（JSONL 格式，逐行追加）
└── ...

会话记录使用 JSONL（JSON Lines）格式——每行一条消息或事件。这种格式的优点是可以高效追加而无需重写整个文件。

7.4 会话重置策略

会话会一直复用，直到被重置。OpenClaw 支持多种重置机制：

自动重置

按时间重置：

json5

{
  session: {
    reset: {
      dailyAt: 4  // 每天凌晨 4:00（网关本地时间）重置
    }
  }
}

按空闲重置：

json5

{
  session: {
    reset: {
      idleMinutes: 120  // 闲置 2 小时后重置
    }
  }
}

可以按消息类型设置不同的重置规则（私聊、群组、线程）。

手动重置

用户可以通过命令手动重置会话：

命令	说明
`/new`	开始新会话
`/reset`	重置当前会话
`/new claude-opus-4-6`	开始新会话并指定模型

7.5 会话修剪（Pruning）

修剪是一种内存优化机制，在 LLM 调用前移除老旧的工具结果，但不修改磁盘上的会话记录。

工作原理

当配置 mode: "cache-ttl" 且上次 API 调用已超过 TTL 阈值时，修剪自动激活。

修剪规则

项目	处理方式
用户消息	永不修剪
助手消息	永不修剪
最后 3 条助手消息	受保护（可配置 `keepLastAssistants`）
包含图片的工具结果	永不修剪
老旧的工具结果	修剪目标

两阶段修剪策略

软修剪（Soft-trim）：保留工具结果的头部和尾部，中间用省略号替代，附注原始大小
- 默认上限：4,000 字符
硬清除（Hard-clear）：用占位符 "[Old tool result content cleared]" 完全替换工具结果

缓存成本优化

修剪的核心目的是降低 cacheWrite Token 成本。当会话空闲超过 TTL（默认 5 分钟）后，下一次请求时修剪老旧内容可以让缓存窗口重置，后续请求直接复用新缓存的提示而非重新缓存完整历史。

7.6 上下文压缩（Compaction）

压缩是比修剪更彻底的上下文管理手段——它将旧对话总结为精简摘要，持久化保存到 JSONL 历史文件中。

压缩 vs 修剪的区别

	压缩（Compaction）	修剪（Pruning）
操作对象	完整对话历史	仅工具结果
持久化	摘要写入 JSONL 文件	仅内存操作，不改磁盘
触发方式	自动（接近 Token 上限）或手动	自动（超过 TTL）
效果	旧对话被浓缩为摘要	旧工具结果被删除/截断

自动触发

当会话接近模型的最大 Token 容量时，系统自动启动压缩。你会在 verbose 日志中看到：

🧹 Auto-compaction complete

手动触发

使用 /compact 命令，可以指定压缩方向：

/compact                                # 默认压缩
/compact Focus on decisions and open questions  # 引导压缩关注点

记忆刷写联动

压缩前，OpenClaw 会执行一个静默的记忆刷写回合——提醒模型将重要信息写入磁盘（memory/ 目录），确保关键内容不会因压缩丢失。这个过程对用户不可见（通常输出 NO_REPLY）。

7.7 会话维护

OpenClaw 提供自动化的会话文件维护：

策略	默认值
自动修剪期限	30 天后删除旧会话文件
最大条目数	500 条
文件轮转大小	10MB

会话检查命令

bash

# 查看存储路径和近期会话
openclaw status

# JSON 格式导出所有会话
openclaw sessions --json

在聊天中也可以查看会话状态：

命令	说明
`/status`	查看会话上下文用量和智能体可用性
`/context list`	列出系统提示的各组成部分及大致 Token 数
`/context detail`	按文件、工具 Schema、技能条目的详细 Token 分解

第 8 章：记忆系统

OpenClaw 的记忆系统遵循一个简洁的设计哲学："写入磁盘才是记忆"。模型上下文窗口中的信息是"短时记忆"，只有写入文件系统的信息才是跨会话的"长时记忆"。

8.1 设计哲学

传统聊天机器人的记忆依赖上下文窗口——一旦对话过长或会话重置，所有信息都会丢失。OpenClaw 使用纯 Markdown 文件作为权威记忆来源，将持久化放在首位。

核心原则：

写入磁盘的才是记忆，RAM 中的只是工作缓冲
如果用户说"记住这个"，必须写入文件（不能仅停留在上下文中）
决策、偏好、持久事实存入长期文件
日常上下文存入每日日志

8.2 两层记忆结构

OpenClaw 的记忆系统由两个层级组成：

日志层：每日记录

workspace/
└── memory/
    ├── 2026-02-09.md
    ├── 2026-02-10.md
    └── 2026-02-11.md   ← 今天

特点：

采用追加写入（Append-only）模式
每次会话启动时，今天和昨天的日志会被自动加载
适合记录运行中的上下文信息、临时笔记、任务进度

日志内容示例：

markdown

# 2026-02-11

## 项目进展
- 完成了用户认证模块的重构
- API 端点从 /api/v1/auth 迁移到 /api/v2/auth
- 待办：更新前端的 API 调用地址

## 用户偏好记录
- 熊老板偏好使用 Bun 而非 npm
- 代码风格：使用单引号，缩进 2 空格

长期层：策展记忆

workspace/
└── MEMORY.md

特点：

手动策展的持久事实、决策和偏好
仅在私聊会话中加载（群聊中不会注入，保护隐私）
适合存放跨会话需要记住的关键信息

长期记忆内容示例：

markdown

# 长期记忆

## 用户信息
- 姓名：熊老板
- 偏好语言：中文
- 技术栈：TypeScript, React, Node.js

## 重要决策
- 2026-01-15: 项目从 REST 迁移到 GraphQL
- 2026-02-01: 数据库从 MySQL 切换到 PostgreSQL

## 约定
- 所有代码提交使用英文 commit message
- PR 描述使用中文

8.3 自动记忆刷写

OpenClaw 内置了一个智能的记忆保全机制——在上下文压缩之前，系统会静默触发一个智能体回合，提醒模型将重要信息写入磁盘。

触发流程：

会话接近 Token 上限
    ↓
触发静默记忆刷写回合（用户不可见）
    ↓
模型检查上下文中是否有未持久化的重要信息
    ↓
如有，写入 memory/ 或 MEMORY.md
    ↓
输出 NO_REPLY（用户看不到任何响应）
    ↓
执行上下文压缩

这个机制使用可配置的软阈值，确保在真正需要压缩前有足够的空间让模型完成记忆整理。

8.4 记忆搜索：向量语义检索

当记忆文件积累到一定量级时，简单的文件读取已不够高效。OpenClaw 提供向量语义搜索能力，让智能体能够跨所有 Markdown 文件进行语义检索。

支持的嵌入模型提供商

提供商	说明
OpenAI	默认选项，需要 `OPENAI_API_KEY`
Google Gemini	需要 `GEMINI_API_KEY`
Voyage	专业嵌入模型
本地模型	无需外部 API

系统会根据可用的 API 密钥自动选择嵌入提供商。

工作流程

用户提问"上次关于数据库迁移的讨论"
    ↓
智能体调用 memory_search 工具
    ↓
查询文本 → 向量化 → 与记忆文件的嵌入进行相似度比较
    ↓
返回最相关的文本片段（含文件路径和行号范围）

8.5 QMD 后端（实验性）

QMD 是 OpenClaw 的本地优先记忆检索后端，作为独立 Sidecar 运行。

核心特性：

结合 BM25 全文搜索和向量检索
支持重排序（Reranking）
完全本地运行（通过 Bun）
自动从 HuggingFace 下载 GGUF 模型

混合搜索策略：

QMD 使用加权评分合并向量相似度和关键词匹配的结果：

最终得分 = 0.7 × 向量相似度 + 0.3 × BM25 关键词匹配

这种混合方式的优势在于：

向量搜索擅长理解语义（"数据库优化" ≈ "SQL 性能调优"）
BM25 搜索擅长精确匹配（搜索 "PostgreSQL" 一定能找到包含该词的文档）

8.6 记忆工具

智能体通过两个内置工具访问记忆系统：

memory_search：语义搜索

返回与查询语义最相关的记忆片段，包含文件路径和行号范围。

使用场景：

"我之前提到过关于部署的什么要求？"
"查找上周讨论的 API 设计决策"

memory_get：精确读取

按路径读取指定的记忆文件。

使用场景：

读取特定日期的日志：memory/2026-02-10.md
读取长期记忆：MEMORY.md

安全限制：两个工具都强制执行工作区相对路径访问限制——智能体只能访问工作区内的记忆文件，无法读取系统其他位置的文件。

第 9 章：模型提供商配置

OpenClaw 不绑定任何单一 AI 模型提供商。你可以灵活地使用 Anthropic、OpenAI、Google 或任何兼容 OpenAI API 的服务。

9.1 内置提供商

开箱即用，OpenClaw 支持以下主流提供商：

提供商	环境变量	示例模型
Anthropic	`ANTHROPIC_API_KEY`	`anthropic/claude-opus-4-6`
OpenAI	`OPENAI_API_KEY`	`openai/gpt-5.1-codex`
Google Gemini	`GEMINI_API_KEY`	`google/gemini-2.5-pro`
OpenRouter	`OPENROUTER_API_KEY`	`openrouter/anthropic/claude-opus-4`
xAI	`XAI_API_KEY`	`xai/grok-3`
Groq	`GROQ_API_KEY`	`groq/llama-4-scout`
Cerebras	`CEREBRAS_API_KEY`	`cerebras/llama3.1-70b`
GitHub Copilot	`COPILOT_GITHUB_TOKEN`	—

9.2 模型引用格式

所有模型引用遵循统一的 provider/model 格式：

anthropic/claude-opus-4-6
openai/gpt-5.1-codex
google/gemini-2.5-pro

模型名称会自动规范化为小写。提供商别名也会被规范化（如 z.ai/* → zai/*）。

9.3 模型选择层级

OpenClaw 按以下顺序选择模型：

主模型（primary）→ 备用模型列表（fallbacks）→ 提供商认证故障转移

配置示例：

json5

{
  agents: {
    defaults: {
      model: {
        primary: "anthropic/claude-opus-4-6",
        fallbacks: [
          "openai/gpt-5.1-codex",
          "google/gemini-2.5-pro"
        ]
      }
    }
  }
}

模型白名单

通过 agents.defaults.models 限制可用模型。如果配置了白名单，选择未列出的模型会被拒绝：

Model 'provider/model' is not allowed. Use /model to list available models.

图像模型

agents.defaults.imageModel 仅在主模型不支持图像处理时激活，作为图像分析的后备选择。

9.4 自定义提供商

对于任何兼容 OpenAI API 协议的服务，你都可以通过 models.providers 配置接入：

Ollama（本地模型）

json5

{
  models: {
    providers: {
      ollama: {
        baseUrl: "http://localhost:11434/v1",
        apiKey: "ollama",  // Ollama 不需要真实 key，但字段必须存在
        models: {
          "llama3.1:70b": {
            contextWindow: 128000
          }
        }
      }
    }
  }
}

使用：ollama/llama3.1:70b

Moonshot AI（Kimi）

json5

{
  models: {
    providers: {
      moonshot: {
        baseUrl: "https://api.moonshot.ai/v1",
        apiKey: "${MOONSHOT_API_KEY}",
        models: {
          "moonshot-v1-128k": {
            contextWindow: 128000
          }
        }
      }
    }
  }
}

其他兼容服务

以下服务都可以通过类似方式接入：

LM Studio：http://localhost:1234/v1
vLLM：http://localhost:8000/v1
LiteLLM：http://localhost:4000/v1
MiniMax：https://api.minimax.chat/v1
Z.AI GLM：支持 auto-thinking 功能

9.5 模型故障转移（Model Failover）

OpenClaw 实现了两级故障处理，确保服务不中断：

第一级：认证 Profile 轮换

当一个 API 密钥或 OAuth Token 失败时，系统在同一提供商内轮换认证凭据。

认证凭据存储位置：

~/.openclaw/agents/<agentId>/agent/auth-profiles.json

支持两种凭据类型：

API 密钥：{ provider, key }
OAuth Token：{ provider, access, refresh, expires, email? }

轮换优先级：

通过 auth.order[provider] 显式配置的顺序
配置文件中的 auth.profiles
auth-profiles.json 中存储的凭据

如果没有显式排序，系统按最近最少使用（LRU）的 Round-Robin 策略轮换，且 OAuth Profile 优先于 API 密钥。

会话固定（Session Pinning）：

OpenClaw 会在每个会话中固定选中的认证 Profile，以保持提供商缓存热度。固定的 Profile 在以下情况下才会改变：

会话重置
压缩完成
冷却期激活

第二级：模型回退

只有当一个提供商的所有认证 Profile 都失败时，才会触发模型回退——按照 fallbacks 列表依次尝试下一个模型。

冷却与禁用策略

失败类型	冷却策略
认证/限速失败	指数退避：1 分钟 → 5 分钟 → 25 分钟 → 1 小时（上限）
账单/额度耗尽	更长退避：5 小时起步，每次翻倍，24 小时上限

账单失败 24 小时无新失败后自动重置。

9.6 OAuth 订阅认证

OpenClaw 支持通过 OAuth 使用 Anthropic 和 OpenAI 的订阅服务。

Anthropic Setup-Token 流程

bash

# 步骤 1：通过 Claude CLI 获取 setup-token
claude setup-token

# 步骤 2：注册到 OpenClaw
openclaw models auth setup-token --provider anthropic

# 或者手动粘贴（从其他来源获取的 token）
openclaw models auth paste-token --provider anthropic

OpenAI Codex OAuth（PKCE 流程）

系统自动处理：

生成 PKCE verifier/challenge 对
重定向到 OpenAI 授权端点
在 localhost:1455 捕获回调
交换凭据获取 Access Token

Token 生命周期管理

认证 Profile 中包含 expires 时间戳。运行时会：

自动使用有效的 Access Token
在文件锁保护下自动刷新过期凭据
无需人工干预

多账号配置

方案一：隔离智能体（推荐）

bash

openclaw agents add work      # 工作用的智能体
openclaw agents add personal  # 个人用的智能体

每个智能体拥有独立的认证凭据，避免交叉污染。

方案二：同一智能体多 Profile

通过 /model Opus@anthropic:work 语法在会话中选择特定 Profile。

9.7 CLI 模型管理

bash

# 列出所有可用模型
openclaw models list

# 查看认证状态和端点详情
openclaw models status

# 设置主模型
openclaw models set anthropic/claude-opus-4-6

# 扫描 OpenRouter 免费模型目录（可选实时探测工具/图像支持）
openclaw models scan

会话中的模型切换（无需重启）：

命令	说明
`/model`	显示模型选择器（编号列表）
`/model 3`	选择编号对应的模型
`/model anthropic/claude-opus-4-6`	直接指定模型
`/model status`	查看认证详情和端点

第 10 章：消息处理与路由

消息是 OpenClaw 的血液——从用户输入到智能体回复，每条消息都经过精心设计的处理管线。

10.1 消息处理管线

每条入站消息遵循以下处理路径：

入站消息 → 去重 → 防抖 → 路由/绑定 → 会话键 → 队列 → 智能体运行 → 流式输出 → 出站回复

配置分布在 messages.*、agents.defaults.* 和渠道特定覆盖中。

10.2 消息去重与防抖

去重

OpenClaw 维护一个短期缓存，以渠道 + 账号 + 对等方 + 会话 + 消息 ID 为索引，防止渠道重复投递触发多次智能体运行。

防抖

来自同一发送者的连续消息会被合并为单次智能体回合。这在用户连续发多条消息时特别有用。

渠道	默认防抖时间
全局默认	2000ms
WhatsApp	5000ms
Slack / Discord	1500ms

规则：

纯文本消息参与防抖
媒体附件和控制命令绕过防抖机制

自定义配置：

json5

{
  messages: {
    inbound: {
      debounceMs: 3000  // 全局 3 秒防抖
    }
  }
}

10.3 消息队列模式

当智能体正在执行时，新到的消息怎么办？OpenClaw 提供五种队列处理模式：

模式	行为
`collect`	默认。收集所有排队消息，合并为单次后续回合
`followup`	排队等待当前运行完成后执行下一回合
`steer`	立即注入当前运行（在下一个工具边界取消待处理的工具调用）
`steer-backlog`	立即注入且保留消息用于后续回合
`interrupt`	中止当前运行，执行最新消息

配置示例：

json5

{
  messages: {
    queue: {
      mode: "collect",       // 默认模式
      debounceMs: 1000,      // 静默等待 1 秒后执行后续回合
      cap: 20,               // 每个会话最多排队 20 条消息
      drop: "summarize"      // 超出上限时：old/new/summarize
    }
  }
}

按渠道覆盖：

json5

{
  messages: {
    queue: {
      byChannel: {
        discord: "collect",
        telegram: "steer"
      }
    }
  }
}

会话级控制（聊天命令）：

/queue collect debounce:2s cap:25 drop:summarize
/queue steer                    # 切换到 steer 模式
/queue default                  # 恢复默认设置

10.4 并发控制

消息队列采用**车道感知（Lane-aware）**设计：

消息 → 会话队列（每会话串行）→ 全局队列（并发上限）

队列	默认并发数
`main`	4
`subagent`	8

同一会话内的 Agent Loop 严格串行，不同会话间可以并行。打字指示器在排队期间就会触发，保证用户体验。

10.5 响应格式化

响应前缀

通过 messages.responsePrefix 为每条回复添加前缀：

json5

{
  messages: {
    responsePrefix: "[{model}] "  // 如 "[claude-opus-4-6] 你好！"
  }
}

支持的模板变量：

{model}：当前使用的模型名称
{identity.name}：智能体名称

确认反应

通过 messages.ackReaction 在收到消息时添加表情反应：

json5

{
  messages: {
    ackReaction: "👀"  // 收到消息后立刻添加"眼睛"表情
  }
}

这让用户知道机器人已经收到消息，正在处理中。

10.6 流式输出与分块

OpenClaw 没有真正的逐 Token 流式输出（Telegram 的草稿模式除外）。取而代之的是块流式（Block Streaming）：将完成的文本段作为独立消息发送。

块流式架构

模型输出流 → EmbeddedBlockChunker → 分块 → 渠道消息

分块算法的断点优先级：

段落 → 换行 → 句子 → 空白 → 硬断点

特殊处理：

代码块（```）永远不会被拆分
如果在字符上限处被迫断开，代码块会在新消息中重新打开
Markdown 格式完整性得到保证

配置：

json5

{
  agents: {
    defaults: {
      blockStreamingDefault: true,  // 全局启用块流式
      blockStreamingBreak: "text_end",  // 持续流式 or "message_end" 完成后发送
      blockStreamingChunk: {
        minChars: 100,   // 最小字符数
        maxChars: 2000,  // 最大字符数
        break: "paragraph"  // 优先断点
      }
    }
  }
}

合并与节奏

为了减少消息碎片化：

json5

{
  agents: {
    defaults: {
      coalescing: {
        idleMs: 500,       // 空闲 500ms 后刷新
        maxChars: 4000,    // 累计 4000 字符后立即发送
        minChars: 200      // 最小累积阈值
      },
      humanDelay: true     // 模拟人类打字延迟（800-2500ms 随机间隔）
    }
  }
}

humanDelay 在第一个块之后的后续块之间添加随机延迟，让回复感觉更自然。

Telegram 草稿流式

Telegram 是唯一支持"部分消息更新"的渠道：

模式	行为
`partial`	用最新流式文本更新草稿气泡
`block`	使用分块器更新草稿
`off`	禁用草稿流式

注意：草稿流式和块流式是独立的系统。启用草稿流式时，块流式会自动禁用以防止重复。

10.7 Markdown 格式化

OpenClaw 使用三阶段管线处理 Markdown，确保跨平台一致性：

Markdown → 解析为中间表示(IR) → 分块 → 按渠道渲染

渠道特定渲染

格式	Slack	Telegram	Signal
链接	`<url\|label>`	HTML 锚标签	`label (url)`
粗体	`text`	`<b>text</b>`	样式范围
代码	`code`	`<code>code</code>`	样式范围

表格处理通过 markdown.tables 配置：

选项	效果
`code`	渲染为代码块（默认）
`bullets`	转换为列表
`off`	禁用解析，原文传递

分块安全保证

代码块保持完整，不会被跨消息拆分
列表和引用块前缀保持完整
内联样式永不跨块拆分——渲染器在每个块内重新打开样式标签

10.8 打字指示器（Typing Indicators）

打字指示器让用户知道智能体正在"思考"和"回复"。

四种模式

模式	行为
`never`	完全禁用
`instant`	模型循环启动时立即激活
`thinking`	首次推理 delta 时激活（需要 `reasoningLevel: "stream"`）
`message`	首次非静默文本 delta 时激活

激活积极性从低到高：never → message → thinking → instant

默认行为（未配置时）：

私聊和被 @ 提及的群聊：立即触发打字
未被提及的群聊：等到消息流式开始才触发
心跳运行：完全禁用打字

配置

json5

{
  agents: {
    defaults: {
      typingMode: "thinking",
      typingIntervalSeconds: 6  // 刷新间隔（默认 6 秒）
    }
  }
}

注意事项

message 模式不会对静默响应（如 NO_REPLY Token）触发打字
thinking 模式需要启用流式推理，否则打字不会出现
心跳运行无论配置如何都不会显示打字指示器

10.9 上下文（Context）详解

上下文是发送给模型的所有内容，受模型 Token 上限约束。它不同于持久化的记忆——上下文是每次请求时动态组装的。

上下文组成

层级	内容
系统提示	规则、工具描述、技能清单、时间信息、运行时元数据、工作区文件
对话历史	当前会话内的所有用户和助手消息
工具操作	命令输出、文件读取、多模态附件（图片/音频）

一切发送到模型的内容都消耗 Token——包括隐藏的提供商包装。

上下文经济学

技能以紧凑列表形式出现在系统提示中（名称 + 描述 + 位置），完整指令仅在被调用时通过 read 命令加载——这是一种延迟加载策略。

工具产生双重开销：

系统提示中的文本描述
隐藏的 JSON Schema（用于模型调用，计入 Token 但用户不可见）

检查工具

命令	说明
`/status`	快速查看容量和会话设置
`/context list`	列出注入内容及大致 Token 数
`/context detail`	按文件、工具 Schema、技能的详细分解
`/usage tokens`	在每条回复后附加 Token 消耗数据

10.10 时区与时间处理

OpenClaw 通过多层配置确保时间戳一致性。

消息信封时间戳

每条入站消息被包裹在带时间戳的信封中：

[Provider ... 2026-02-11 16:26 CST] 消息文本

配置选项：

json5

{
  agents: {
    defaults: {
      envelopeTimezone: "Asia/Shanghai",  // UTC / local / IANA 时区
      envelopeTimestamp: true,            // 显示绝对时间
      envelopeElapsed: true              // 显示经过时间（如 "+2m"）
    }
  }
}

用户时区

json5

{
  agents: {
    defaults: {
      userTimezone: "Asia/Shanghai",
      timeFormat: "24"  // "auto" | "12" | "24"
    }
  }
}

如果不配置，系统自动检测宿主机时区。这个时区会出现在系统提示中，帮助模型正确理解和表达时间。

工具数据时间标准化

当工具返回数据（如 Discord/Slack 消息）时，时间戳会被双重标准化：

保留提供商原始时间戳
添加统一字段：timestampMs（UTC 毫秒时间戳）和 timestampUtc（ISO 8601 格式）

10.11 用量追踪

OpenClaw 从提供商端点获取实时消费数据，而非依赖估算。

查看用量

位置	命令/方式	说明
聊天界面	`/status`	表情风格的会话 Token 和估算费用
聊天界面	`/usage tokens` 或 `/usage full` 或 `/usage cost`	细粒度控制
命令行	`openclaw status --usage`	每提供商的详细分解
macOS 菜单栏	Context 区域	可视化用量面板

注意：用量数据仅在匹配的 OAuth 或 API 凭据可用时显示。不同认证方式显示的信息不同——OAuth 只显示 Token 数量，API 密钥显示 Token 数量和估算费用。

支持的提供商

Anthropic (Claude)、GitHub Copilot、Gemini CLI、Antigravity、OpenAI Codex、MiniMax、z.ai 等均支持用量追踪。

小结

通过本部分的深入学习，你应该已经全面掌握了 OpenClaw 的五大核心概念：

第 6 章：智能体运行时 - 核心要点

✅ Pi-mono 引擎：

OpenClaw 使用基于 pi-mono 的单一智能体运行时
这不是简单的聊天机器人，而是能执行工具、管理文件、浏览网页的自主智能体

✅ 工作区（Workspace）：

智能体的唯一工作目录，默认位置：~/.openclaw/workspace
不要在工作区存放敏感凭据
建议初始化为 Git 仓库以便备份和迁移

✅ Bootstrap 文件体系（首次会话自动注入）：

AGENTS.md - 操作指引与行为规则
SOUL.md - 人格定义与沟通风格
TOOLS.md - 本地工具文档
IDENTITY.md - 智能体名称与角色
USER.md - 用户画像
BOOTSTRAP.md - 一次性初始化任务（执行后自动标记完成）

✅ 智能体执行循环：

用户消息 → 验证 & 会话解析 → 上下文组装 → 模型推理 → 工具执行 → 流式输出 → 持久化

✅ 并发控制：

同一会话内严格串行执行
不同会话可以并行（默认 main 队列 4 个，subagent 队列 8 个）

第 7 章：会话管理 - 核心要点

✅ 会话作用域（DM Scope） - 隐私隔离的关键：

模式	适用场景	隔离级别
`main`	个人使用（默认）	无隔离
`per-peer`	多用户场景	按用户隔离
`per-channel-peer`	多用户多渠道	按渠道+用户隔离
`per-account-channel-peer`	最高隔离	按账号+渠道+用户隔离

⚠️ 重要：多用户场景必须启用隔离模式，否则会泄露隐私！

✅ 会话存储：

路径：~/.openclaw/agents/<agentId>/sessions/<SessionId>.jsonl
格式：JSONL（每行一条消息，可高效追加）

✅ 会话重置策略：

定时重置：dailyAt: 4（每天凌晨 4 点）
空闲重置：idleMinutes: 120（闲置 2 小时）
手动重置：/new 或 /reset 命令

✅ 会话修剪（Pruning）：

仅内存操作，不修改磁盘文件
移除老旧的工具结果，保留用户和助手消息
触发条件：上次 API 调用超过 TTL（默认 5 分钟）
目的：降低 cacheWrite Token 成本

✅ 上下文压缩（Compaction）：

持久化操作，将旧对话总结为摘要并写入 JSONL
触发条件：接近模型 Token 上限或手动 /compact
压缩前自动执行静默记忆刷写，保护重要信息

第 8 章：记忆系统 - 核心要点

✅ 设计哲学：

"写入磁盘才是记忆" - 上下文窗口是短时记忆，文件系统是长时记忆

✅ 两层记忆结构：

日志层（memory/YYYY-MM-DD.md）：

追加写入模式
今天和昨天的日志自动加载
适合记录任务进度、日常上下文

长期层（MEMORY.md）：

手动策展的持久事实和决策
仅在私聊加载（群聊不加载，保护隐私）
适合存放跨会话的关键信息

✅ 自动记忆刷写：

在上下文压缩前自动触发
静默提醒模型将重要信息写入磁盘
用户不可见（输出 NO_REPLY）

✅ 向量语义搜索：

支持 OpenAI、Google Gemini、Voyage、本地模型
工具：memory_search（语义搜索）、memory_get（精确读取）
强制工作区相对路径访问限制

✅ QMD 后端（实验性）：

本地优先，完全离线运行
混合搜索：0.7 × 向量 + 0.3 × BM25
支持重排序（Reranking）

第 9 章：模型提供商配置 - 核心要点

✅ 内置提供商：

Anthropic、OpenAI、Google Gemini、OpenRouter、xAI、Groq、Cerebras
环境变量：ANTHROPIC_API_KEY、OPENAI_API_KEY 等

✅ 模型引用格式：

provider/model

示例：anthropic/claude-opus-4-6、openai/gpt-5.1-codex

✅ 模型选择层级：

主模型（primary）→ 备用模型列表（fallbacks）→ 提供商认证故障转移

✅ 自定义提供商（兼容 OpenAI API 协议）：

Ollama（本地模型）：http://localhost:11434/v1
Moonshot AI（Kimi）：https://api.moonshot.ai/v1
LM Studio、vLLM、LiteLLM、MiniMax 等

✅ 模型故障转移：

第一级：认证 Profile 轮换

存储位置：~/.openclaw/agents/<agentId>/agent/auth-profiles.json
会话固定（Session Pinning）：保持提供商缓存热度
冷却策略：认证失败 → 1 分钟 → 5 分钟 → 25 分钟 → 1 小时

第二级：模型回退

当所有认证 Profile 失败时，按 fallbacks 列表尝试下一个模型

✅ OAuth 订阅认证：

Anthropic Setup-Token 流程
OpenAI Codex PKCE 流程
自动 Token 刷新，无需人工干预

✅ CLI 模型管理：

bash

openclaw models list        # 列出所有可用模型
openclaw models status      # 查看认证状态
openclaw models set <model> # 设置主模型
openclaw models scan        # 扫描 OpenRouter 免费模型

第 10 章：消息处理与路由 - 核心要点

✅ 消息处理管线：

入站消息 → 去重 → 防抖 → 路由/绑定 → 会话键 → 队列 → 智能体运行 → 流式输出 → 出站回复

✅ 消息防抖：

合并来自同一发送者的连续消息为单次智能体回合
默认防抖时间：全局 2000ms，WhatsApp 5000ms
媒体附件和控制命令绕过防抖

✅ 消息队列模式：

模式	行为	适用场景
`collect`	收集所有排队消息，合并执行（默认）	通用场景
`followup`	排队等待当前运行完成	需要顺序执行
`steer`	立即注入当前运行	需要实时响应
`steer-backlog`	立即注入且保留消息	结合实时+顺序
`interrupt`	中止当前运行，执行最新消息	紧急场景

✅ 并发控制：

同一会话内严格串行
不同会话可以并行（main 队列 4 个，subagent 队列 8 个）

✅ 流式输出与分块：

块流式（非逐 Token）：将完成的文本段作为独立消息发送
分块断点优先级：段落 → 换行 → 句子 → 空白 → 硬断点
代码块永远不会被拆分

✅ 合并与节奏控制：

json5

{
  coalescing: {
    idleMs: 500,       // 空闲 500ms 后刷新
    maxChars: 4000,    // 累计 4000 字符后立即发送
    minChars: 200      // 最小累积阈值
  },
  humanDelay: true     // 模拟人类打字延迟（800-2500ms）
}

✅ Markdown 格式化：

三阶段管线：Markdown → 中间表示(IR) → 分块 → 按渠道渲染
跨平台一致性：Slack、Telegram、Signal 等自动适配
表格处理：code（代码块）、bullets（列表）、off（禁用）

✅ 打字指示器模式：

模式	触发时机	积极性
`never`	完全禁用	最低
`message`	首次非静默文本 delta	低
`thinking`	首次推理 delta	中
`instant`	模型循环启动时	最高

✅ 上下文组成：

系统提示：规则、工具描述、技能清单、时间信息、Bootstrap 文件
对话历史：当前会话的所有用户和助手消息
工具操作：命令输出、文件读取、多模态附件

检查命令：

/status          # 快速查看容量和会话设置
/context list    # 列出注入内容及 Token 数
/context detail  # 详细 Token 分解
/usage tokens    # 查看 Token 消耗

✅ 用量追踪：

从提供商端点获取实时消费数据（非估算）
支持 Anthropic、GitHub Copilot、Gemini、OpenAI Codex 等
OAuth 显示 Token 数量，API 密钥显示 Token + 费用估算

实战检查清单

在进入第四部分之前，确保你已经掌握以下关键操作：

智能体运行时

[ ] 理解工作区的作用，知道在哪里找到 AGENTS.md、SOUL.md 等文件
[ ] 知道如何自定义智能体的人格和行为准则
[ ] 理解 Bootstrap 文件的注入时机和作用

会话管理

[ ] 能够根据使用场景选择正确的 dmScope 模式
[ ] 知道何时需要重置会话（/new 或 /reset）
[ ] 理解修剪和压缩的区别及触发条件

记忆系统

[ ] 知道记忆分为日志层（memory/）和长期层（MEMORY.md）
[ ] 理解"写入磁盘才是记忆"的哲学
[ ] 知道如何让智能体搜索和读取记忆文件

模型配置

[ ] 能够切换不同的 AI 模型（/model 命令）
[ ] 理解模型故障转移的两级机制
[ ] 知道如何配置自定义提供商（如 Ollama）

消息处理

[ ] 理解消息队列的不同模式（collect、steer、interrupt）
[ ] 知道如何配置防抖和合并策略
[ ] 能够使用 /context 和 /status 命令检查上下文用量

常见问题解答

Q1：为什么多用户场景下，其他用户能看到我的对话历史？

A：你使用了默认的 dmScope: "main" 模式。解决方法：

json5

{
  session: {
    dmScope: "per-channel-peer"  // 按渠道+用户隔离
  }
}

Q2：我的会话历史太长，如何清理？

A：有三种方法：

重置会话：/reset（清空历史，保留记忆）
压缩会话：/compact（总结旧对话为摘要）
修剪策略：配置 session.reset.idleMinutes 自动重置

Q3：智能体记不住我上次说的内容？

A：检查以下几点：

内容是否写入了记忆文件（memory/ 或 MEMORY.md）？
会话是否被重置了？
是否触发了上下文压缩但记忆刷写失败？

提示智能体："请将这个信息记录到长期记忆中"

Q4：如何降低 Token 消耗成本？

A：优化策略：

启用会话修剪（cache-ttl 模式）
定期压缩长会话（/compact）
使用更小的模型（如 claude-haiku-4）
限制工具数量（tools.allow 白名单）
减少 Bootstrap 文件大小

Q5：智能体切换模型后，之前的对话能看到吗？

A：能。会话历史独立于模型，切换模型不会丢失对话。但要注意：

不同模型的上下文窗口大小不同
切换到小窗口模型可能触发自动压缩

Q6：如何让智能体使用本地 Ollama 模型？

A：配置自定义提供商：

json5

{
  models: {
    providers: {
      ollama: {
        baseUrl: "http://localhost:11434/v1",
        apiKey: "ollama",
        models: {
          "llama3.1:70b": {
            contextWindow: 128000
          }
        }
      }
    }
  }
}

然后使用：/model ollama/llama3.1:70b

下一步

掌握了这五大核心概念后，你已经具备了深入使用 OpenClaw 的理论基础。

接下来，第四部分将带你进入实战领域：

🔧 50+ 内置工具体系详解
🌐 浏览器自动化实战
🛠️ 技能（Skills）系统与 ClawHub
🪝 Hooks 事件驱动自动化
⏰ 定时任务（Cron）配置

让我们开始探索 OpenClaw 的工具与能力扩展！

参考文档：
concepts/agent — 智能体运行时
concepts/session — 会话管理
concepts/memory — 记忆系统
concepts/model-providers — 模型提供商
concepts/messages — 消息处理

第三部分：核心概念深入 ​

第 6 章：智能体（Agent）运行时 ​

6.1 Pi-mono 智能体引擎 ​

6.2 工作区（Workspace） ​

6.3 Bootstrap 启动文件体系 ​

AGENTS.md — 操作指引与记忆 ​

SOUL.md — 人格定义与边界 ​

TOOLS.md — 工具文档 ​

BOOTSTRAP.md — 一次性初始化 ​

IDENTITY.md — 名称与角色 ​

USER.md — 用户画像 ​

6.4 智能体执行循环（Agent Loop） ​

完整执行流程 ​

队列与并发 ​

Hook 介入点 ​

终止条件 ​

6.5 系统提示（System Prompt）构建 ​

系统提示包含的内容 ​

三种渲染模式 ​

Bootstrap 文件注入规则 ​

第 7 章：会话管理 ​

7.1 会话架构 ​

7.2 会话作用域（DM Scope） ​

隐私隔离的重要性 ​

跨渠道身份关联 ​

7.3 会话存储 ​

7.4 会话重置策略 ​

自动重置 ​

手动重置 ​

7.5 会话修剪（Pruning） ​

工作原理 ​

修剪规则 ​

两阶段修剪策略 ​

缓存成本优化 ​

7.6 上下文压缩（Compaction） ​

压缩 vs 修剪的区别 ​

自动触发 ​

手动触发 ​

记忆刷写联动 ​

7.7 会话维护 ​

会话检查命令 ​

第 8 章：记忆系统 ​

8.1 设计哲学 ​

8.2 两层记忆结构 ​

日志层：每日记录 ​

长期层：策展记忆 ​

8.3 自动记忆刷写 ​

8.4 记忆搜索：向量语义检索 ​

支持的嵌入模型提供商 ​

工作流程 ​

8.5 QMD 后端（实验性） ​

8.6 记忆工具 ​

memory_search：语义搜索 ​

memory_get：精确读取 ​

第 9 章：模型提供商配置 ​

9.1 内置提供商 ​

9.2 模型引用格式 ​

9.3 模型选择层级 ​

模型白名单 ​

图像模型 ​

9.4 自定义提供商 ​

Ollama（本地模型） ​

Moonshot AI（Kimi） ​

其他兼容服务 ​

9.5 模型故障转移（Model Failover） ​

第一级：认证 Profile 轮换 ​

第二级：模型回退 ​

冷却与禁用策略 ​

9.6 OAuth 订阅认证 ​

Anthropic Setup-Token 流程 ​

OpenAI Codex OAuth（PKCE 流程） ​

Token 生命周期管理 ​

多账号配置 ​

9.7 CLI 模型管理 ​

第 10 章：消息处理与路由 ​

10.1 消息处理管线 ​

10.2 消息去重与防抖 ​

去重 ​

防抖 ​

10.3 消息队列模式 ​

第三部分：核心概念深入

第 6 章：智能体（Agent）运行时

6.1 Pi-mono 智能体引擎

6.2 工作区（Workspace）

6.3 Bootstrap 启动文件体系

AGENTS.md — 操作指引与记忆

SOUL.md — 人格定义与边界

TOOLS.md — 工具文档

BOOTSTRAP.md — 一次性初始化

IDENTITY.md — 名称与角色

USER.md — 用户画像

6.4 智能体执行循环（Agent Loop）

完整执行流程

队列与并发

Hook 介入点

终止条件

6.5 系统提示（System Prompt）构建

系统提示包含的内容

三种渲染模式

Bootstrap 文件注入规则

第 7 章：会话管理

7.1 会话架构

7.2 会话作用域（DM Scope）

隐私隔离的重要性

跨渠道身份关联

7.3 会话存储

7.4 会话重置策略

自动重置

手动重置

7.5 会话修剪（Pruning）

工作原理

修剪规则

两阶段修剪策略

缓存成本优化

7.6 上下文压缩（Compaction）

压缩 vs 修剪的区别

自动触发

手动触发

记忆刷写联动

7.7 会话维护

会话检查命令

第 8 章：记忆系统

8.1 设计哲学

8.2 两层记忆结构

日志层：每日记录

长期层：策展记忆

8.3 自动记忆刷写

8.4 记忆搜索：向量语义检索

支持的嵌入模型提供商

工作流程

8.5 QMD 后端（实验性）

8.6 记忆工具

memory_search：语义搜索

memory_get：精确读取

第 9 章：模型提供商配置

9.1 内置提供商

9.2 模型引用格式

9.3 模型选择层级

模型白名单

图像模型

9.4 自定义提供商

Ollama（本地模型）

Moonshot AI（Kimi）

其他兼容服务

9.5 模型故障转移（Model Failover）

第一级：认证 Profile 轮换

第二级：模型回退

冷却与禁用策略

9.6 OAuth 订阅认证

Anthropic Setup-Token 流程

OpenAI Codex OAuth（PKCE 流程）

Token 生命周期管理

多账号配置

9.7 CLI 模型管理

第 10 章：消息处理与路由

10.1 消息处理管线

10.2 消息去重与防抖

去重

防抖

10.3 消息队列模式