OpenClaw 会话配置完全指南:从原理到实操

一文搞懂 OpenClaw 的会话配置体系，掌握每个配置项的作用与最佳实践。

写在前面

如果你刚开始用 OpenClaw，可能会被它的配置体系弄得有点晕：Agent 配置、会话配置、上下文修剪、模型参数、提示词缓存……这么多概念，它们之间到底什么关系？

别急，这篇文章会带你从零开始，把 OpenClaw 的会话配置体系彻底搞清楚。我们不仅讲"怎么配"，更要讲"为什么这样配"，让你知其然更知其所以然。

第一部分：核心概念——Agent 和 Session 的关系

1.1 什么是 Agent？

在 OpenClaw 的世界里，Agent（智能体）是配置的载体。你可以把它理解为一个"机器人"的配置档案，里面记录着：

• 这个机器人用什么模型（GPT-4、Claude、Qwen 等）
• 它的性格是什么样的（SOUL.md）
• 它知道什么（MEMORY.md）
• 它会用什么工具（Tools）
• 它有什么特殊技能（Skills）

每个 Agent 都有自己独立的配置目录，结构如下：

~/.openclaw/agents/ ├── main/                    # 主 Agent（默认） │   ├── agent.json           # Agent 主配置文件 │   ├── agent/               # Agent 级别的配置子目录 │   │   ├── models.json      # 模型提供商配置 │   │   ├── system.md        # 自定义系统提示词 │   │   └── mcp.json         # MCP 服务器配置 │   ├── sessions/            # 这个 Agent 的所有会话 │   │   ├── sessions.json    # 会话索引 │   │   └── <session-id>/    # 具体会话目录 │   │       ├── messages.jsonl  # 消息历史 │   │       └── session.json    # 会话配置 │   └── ... ├── wechat-writer/           # 另一个 Agent（比如专门写微信文章） │   └── ... └── ...

1.2 什么是 Session？

Session（会话）是 Agent 的一次"对话实例"。每次你和 AI 开始一段新对话，就会创建一个新 Session。

Session 的特点：

• 每个 Session 属于某个 Agent
• Session 继承 Agent 的基础配置
• Session 可以有自己的独立配置（覆盖 Agent 配置）
• Session 保存完整的对话历史

用一个比喻：Agent 是"剧本"，Session 是"演出"。同一个剧本可以有多次演出，每次演出都有自己的独特性。

1.3 配置的优先级

OpenClaw 的配置遵循"就近原则"——越具体的配置优先级越高：

Session 配置 > Agent 配置 > 默认配置

举例： - Agent 默认使用 gpt-4，但你可以在某个 Session 临时切换到 gpt-3.5-turbo - Agent 默认不开启推理模式，但某个 Session 可以临时开启

第二部分：Agent 配置详解

2.1 agent.json —— Agent 的"身份证"

agent.json 是每个 Agent 的主配置文件，让我们看看它长什么样：

{   "id": "main",   "name": "Main Agent",   "description": "默认主智能体",   "runtime": "agent",   "model": "claude-3-opus",   "default": true,   "thinking": "off",   "reasoningBudget": 10000,   "maxTokens": 4096,   "toolPolicy": {     "mode": "allowlist",     "allow": ["read", "write", "edit", "exec", "web_search"]   },   "heartbeat": {     "every": "55m"   },   "contextPruning": {     "mode": "auto",     "maxTokens": 100000,     "triggerRatio": 0.75   },   "compaction": {     "enabled": true,     "style": "summary",     "threshold": 50   },   "sandbox": {     "enabled": true,     "workdir": "/workspace"   } }

2.2 关键配置项解读

2.2.1 model —— 模型选择

最核心的配置，决定 Agent 使用哪个大模型：

{   "model": "anthropic/claude-3-opus" }

支持的模型格式： - anthropic/claude-3-opus —— Anthropic 直连 - openai/gpt-4 —— OpenAI 直连 - openrouter/anthropic/claude-3-opus —— 通过 OpenRouter 调用 - custom-provider/model-name —— 自定义提供商

2.2.2 thinking —— 推理模式

控制模型是否进行"深度思考"：

{   "thinking": "off"     // 关闭（默认）   "thinking": "on"      // 开启（流式输出思考过程）   "thinking": "hidden"  // 开启但不显示 }

原理：某些模型（如 Claude）支持"extended thinking"模式，在给出最终回答前会先进行内部推理。这能显著提高复杂任务的质量，但也会增加 token 消耗。

2.2.3 reasoningBudget —— 推理预算

配合 thinking 使用，控制模型"思考多久"：

{   "reasoningBudget": 10000  // 最多思考 10000 个 token }

实操建议： - 简单任务（翻译、摘要）：设置为 1000-2000 - 中等任务（代码生成、分析）：设置为 5000-10000 - 复杂任务（架构设计、长篇写作）：设置为 20000+

2.2.4 maxTokens —— 最大输出长度

控制模型回复的最大长度：

{   "maxTokens": 4096  // 单次回复最多 4096 个 token }

注意：这是输出限制，不是上下文限制。上下文限制由模型本身决定。

2.2.5 toolPolicy —— 工具权限策略

控制 Agent 可以使用哪些工具：

{   "toolPolicy": {     "mode": "allowlist",           // 白名单模式     "allow": ["read", "write", "exec"]   } }

或者黑名单模式：

{   "toolPolicy": {     "mode": "denylist",     "deny": ["exec", "web_search"]  // 禁止这些工具   } }

三种模式： - deny —— 拒绝所有工具（最严格） - allowlist —— 只允许列表中的工具 - denylist —— 允许所有工具，除了列表中的

第三部分：模型配置（models.json）

3.1 为什么需要 models.json？

agent.json 里的 model 只是"选择哪个模型"，而 models.json 则定义"这个模型的提供商是谁、API 地址在哪、用什么密钥"。

agent.json 的 model: "用什么模型"         ↓ models.json: "这个模型的提供商、API、密钥"         ↓ 实际 API 调用

3.2 models.json 结构详解

{   "providers": {     "anthropic": {       "baseUrl": "https://api.anthropic.com",       "apiKey": "${ANTHROPIC_API_KEY}",       "api": "anthropic-messages",       "models": [         {           "id": "claude-3-opus",           "name": "Claude 3 Opus",           "contextWindow": 200000,           "maxTokens": 4096,           "input": ["text", "image"],           "cost": {             "input": 15,             "output": 75,             "cacheRead": 1.5,             "cacheWrite": 18.75           }         }       ]     },     "openai": {       "baseUrl": "https://api.openai.com/v1",       "apiKey": "${OPENAI_API_KEY}",       "api": "openai-completions",       "models": [         {           "id": "gpt-4",           "name": "GPT-4",           "contextWindow": 8192,           "maxTokens": 4096,           "cost": {             "input": 30,             "output": 60           }         }       ]     }   } }

3.3 关键字段解释

3.3.1 Provider 级别

3.3.2 Model 级别

3.4 多提供商配置示例

实际使用中，你可能需要配置多个提供商：

{   "providers": {     "anthropic": {       "baseUrl": "https://api.anthropic.com",       "apiKey": "${ANTHROPIC_API_KEY}",       "api": "anthropic-messages",       "models": [         { "id": "claude-3-opus", "contextWindow": 200000, "maxTokens": 4096 }       ]     },     "custom-dashscope": {       "baseUrl": "https://dashscope.aliyuncs.com/compatible-mode/v1",       "apiKey": "${DASHSCOPE_API_KEY}",       "api": "openai-completions",       "models": [         { "id": "qwen-max", "contextWindow": 32768, "maxTokens": 8192 }       ]     },     "openrouter": {       "baseUrl": "https://openrouter.ai/api/v1",       "apiKey": "${OPENROUTER_API_KEY}",       "api": "openai-completions",       "models": [         { "id": "anthropic/claude-3-opus", "contextWindow": 200000 }       ]     }   } }

第四部分：上下文管理 —— 让 AI 记住更多

4.1 系统提示词是怎么组装的？

每次对话，OpenClaw 都会自动组装一个"系统提示词"，发送给模型。这个系统提示词包含：

┌─────────────────────────────────────────────────────────┐ │                    系统提示词结构                         │ ├─────────────────────────────────────────────────────────┤ │ 1. 基础指令（角色定义、回复规则）                           │ │ 2. 工具列表（可用工具及简要说明）                           │ │ 3. 技能列表（可用技能元数据）                              │ │ 4. 自更新指令（自我改进机制）                              │ │ 5. 工作区文件（AGENTS.md、SOUL.md、MEMORY.md 等）          │ │ 6. 时间信息（UTC + 用户时区）                              │ │ 7. 回复标签规则                                           │ │ 8. 心跳行为说明                                           │ │ 9. 运行时元数据（主机/OS/模型/思考模式）                    │ └─────────────────────────────────────────────────────────┘

4.2 工作区引导文件详解

OpenClaw 会自动加载以下文件到系统提示词中：

文件大小限制： - 单文件上限：agents.defaults.bootstrapMaxChars（默认 20000 字符） - 总注入上限：agents.defaults.bootstrapTotalMaxChars（默认 150000 字符）

4.3 上下文修剪（Context Pruning）

4.3.1 为什么需要修剪？

对话越长，上下文越大。当上下文接近模型限制时，会出现： - API 报错（超过 context window） - 成本飙升（按 token 计费） - 响应变慢

修剪就是解决这个问题：自动清理不重要的历史内容，保留关键信息。

4.3.2 修剪模式

{   "contextPruning": {     "mode": "auto",        // auto | cache-ttl | disabled     "maxTokens": 100000,   // 修剪后的目标大小     "triggerRatio": 0.75   // 触发阈值（75% 时开始修剪）   } }

三种模式：

4.3.3 修剪策略

OpenClaw 的修剪不是简单"删掉旧消息"，而是智能判断：

优先保留： - 系统消息（system） - 最近的用户消息 - 包含重要决策的消息 - 工具调用和结果（部分）

优先删除： - 旧的闲聊 - 冗长的工具输出 - 重复内容

4.4 会话压缩（Compaction）

4.4.1 什么是 Compaction？

当对话变得很长时，OpenClaw 可以把旧消息"压缩"成摘要：

原始对话（100条消息）         ↓ compaction 摘要 + 最近20条消息（压缩后）

4.4.2 配置 Compaction

{   "compaction": {     "enabled": true,     "style": "summary",      // summary | key-points     "threshold": 50          // 超过50条消息时触发   } }

两种风格： - summary：生成流畅的摘要叙述 - key-points：提取关键决策和待办事项

4.4.3 手动触发压缩

在对话中使用命令：

/compact          # 压缩当前对话 /compact full     # 完整压缩（包括所有历史）

第五部分：提示词缓存（Prompt Caching）

5.1 什么是提示词缓存？

大模型推理时，如果系统提示词没变，可以"复用"之前的计算结果，避免重复处理。这意味着： - 更低的成本：缓存读取比正常输入便宜很多 - 更快的响应：跳过重复处理

5.2 缓存是如何工作的？

第一次请求： 系统提示词（10000 token）→ 模型处理 → 缓存写入（cacheWrite）  第二次请求（系统提示词不变）： 系统提示词 → 缓存命中 → 缓存读取（cacheRead，更便宜）

5.3 配置缓存

{   "params": {     "cacheRetention": "long"    // none | short | long   } }

三种取值：

5.4 缓存与心跳的配合

问题：如果对话空闲超过缓存时长，下次请求就要重新写入缓存。

解决方案：心跳保持活跃

{   "heartbeat": {     "every": "55m"    // 每55分钟发送一次心跳   } }

如果缓存 TTL 是 1 小时，设置 55 分钟的心跳，可以保持缓存"温暖"，避免重复写入。

5.5 多 Agent 的缓存策略

不同 Agent 可以有不同的缓存策略：

{   "agents": {     "defaults": {       "models": {         "anthropic/claude-3-opus": {           "params": {             "cacheRetention": "long"           }         }       }     },     "list": [       {         "id": "research",         "params": {           "cacheRetention": "long"         },         "heartbeat": { "every": "55m" }       },       {         "id": "alerts",         "params": {           "cacheRetention": "none"    // 通知类 Agent 不需要缓存         }       }     ]   } }

第六部分：会话级配置

6.1 会话配置文件（session.json）

每个会话都有自己的配置文件：

{   "id": "session-abc123",   "agentId": "main",   "model": "claude-3-opus",       // 可覆盖 Agent 默认模型   "thinking": "on",               // 可覆盖 Agent 默认设置   "maxTokens": 8192,   "createdAt": "2024-03-26T10:00:00Z",   "lastActiveAt": "2024-03-26T12:30:00Z",   "messageCount": 42,   "status": "active" }

6.2 会话配置的覆盖规则

会话配置可以"临时覆盖"Agent 配置，但不会修改 Agent 配置文件：

6.3 运行时切换配置

在对话中使用命令实时切换：

/model claude-3-opus      # 切换模型 /thinking on             # 开启推理模式 /reasoning 20000         # 设置推理预算 /status                  # 查看当前配置状态

这些命令只影响当前会话，不影响 Agent 默认配置。

第七部分：消息历史与会话持久化

7.1 消息存储格式（messages.jsonl）

OpenClaw 使用 JSONL 格式存储消息历史，每行一条消息：

{"role":"user","content":"你好"} {"role":"assistant","content":"你好！有什么我可以帮助你的吗？"} {"role":"user","content":"帮我写一个 Python 脚本"} {"role":"assistant","content":"好的，请告诉我...","toolCalls":[{"name":"write","args":{"path":"script.py","content":"..."}}]} {"role":"tool","name":"write","content":"文件已创建"}

7.2 消息类型详解

7.3 会话生命周期

创建 → 活跃 → 空闲 → 归档 → 清理   │       │       │       │       │   └───────┴───────┴───────┴───────┘        每个阶段都有对应配置

7.3.1 会话状态

7.3.2 会话清理配置

{   "sessionCleanup": {     "maxAge": "30d",           // 超过30天的空闲会话     "maxSessions": 100,        // 最多保留100个会话     "archiveDir": "archive/"   // 归档目录   } }

第八部分：高级配置技巧

8.1 多模型切换策略

OpenClaw 支持配置多个模型，实现自动切换或手动切换：

{   "models": {     "anthropic/claude-3-opus": {       "fallback": "anthropic/claude-3-sonnet"  // 主模型失败时切换     }   } }

或者配置按任务类型选择模型：

{   "taskRouting": {     "code": "claude-3-opus",           // 编码任务用强模型     "translation": "gpt-3.5-turbo",    // 翻译用快模型     "analysis": "claude-3-sonnet"      // 分析用中等模型   } }

8.2 成本控制配置

{   "costControl": {     "maxCostPerSession": 1.0,     // 单次会话最大1美元     "maxCostPerDay": 10.0,        // 每天最大10美元     "alertThreshold": 0.8         // 达到80%时提醒   } }

查看成本统计：

/status    # 查看当前会话的 token 使用量和成本

8.3 沙箱与安全配置

控制 Agent 的执行环境：

{   "sandbox": {     "enabled": true,     "workdir": "/workspace",           // 工作目录     "allowNetwork": false,             // 禁止网络访问     "allowRead": ["./data"],           // 允许读取的目录     "allowWrite": ["./output"],        // 允许写入的目录     "forbidCommands": ["rm -rf"]       // 禁止执行的命令   } }

第九部分：配置最佳实践

9.1 Agent 配置模板推荐

日常助手型：

{   "model": "claude-3-sonnet",   "thinking": "off",   "maxTokens": 4096,   "contextPruning": { "mode": "auto" },   "heartbeat": { "every": "55m" },   "params": { "cacheRetention": "long" } }

深度分析型：

{   "model": "claude-3-opus",   "thinking": "hidden",   "reasoningBudget": 20000,   "maxTokens": 8192,   "contextPruning": { "mode": "cache-ttl" },   "params": { "cacheRetention": "long" } }

快速响应型：

{   "model": "gpt-3.5-turbo",   "thinking": "off",   "maxTokens": 2048,   "contextPruning": { "mode": "disabled" },   "params": { "cacheRetention": "none" } }

9.2 配置常见问题

Q: 修改了 agent.json 但没生效？ A: 需要重启会话或使用 /reload 命令。

Q: 会话上下文总是被截断？ A: 检查 contextPruning.maxTokens 设置是否合理。

Q: 成本比预期高？ A: 检查是否开启了 thinking 模式，以及 cacheRetention 是否正确配置。

Q: 心跳不工作？ A: 确保 Gateway 服务正在运行：openclaw gateway status

第十部分：总结与速查表

10.1 配置优先级速查

会话配置 > Agent 配置 > 默认配置 命令行参数 > 配置文件 > 环境变量

10.2 常用配置命令速查

10.3 配置文件速查

写在最后

OpenClaw 的会话配置体系虽然看似复杂，但理解了"分层配置"和"优先级覆盖"这两个核心概念后，一切都变得清晰。

记住：Agent 是配置模板，Session 是运行实例。合理配置 Agent 可以让所有继承它的 Session 都受益，而 Session 级别的临时调整则提供了灵活性。

希望这篇指南能帮助你更好地驾驭 OpenClaw！如有问题，欢迎在社区讨论。