—┌─────────────────────────────────────┐
│ Application Layer │
│ (Agent 实例，按需选择模型子集) │
├─────────────────────────────────────┤
│ Optional Filter Layer │
│ (可选过滤规则，动态排除/包含) │
├─────────────────────────────────────┤
│ Shared Catalog Core │
│ (共享模型目录，单例模式管理) │
├─────────────────────────────────────┤
│ Model Providers │
│ (OpenAI、Claude、本地模型等) │
└─────────────────────────────────────┘
2.2 关键代码实现
以下示例展示了如何在 OpenClaw 配置中启用该功能：
javascript
// openclaw.config.js
module.exports = {
// 启用共享模型目录
modelCatalog: {
// 共享配置：所有实例共用同一份基础目录
shared: true,
// 可选加载：指定当前 Agent 需要的模型子集
optional: {
// 白名单模式：仅加载指定模型
include: [‘gpt-4’, ‘claude-3-opus’, ‘local-llama’],
// 或黑名单模式：排除特定模型
// exclude: [‘deprecated-model-v1’],
// 动态过滤条件
filter: (model) => model.contextWindow >= 4096
}
},
// Agent 特定配置
agent: {
name: ‘code-assistant’,
// 继承共享目录，但仅使用可选子集
useSharedCatalog: true
}
};
2.3 内存优化效果
通过共享机制，多 Agent 部署时的内存占用显著降低：
| 部署模式 | 模型目录内存占用 | 启动时间 |
|:---|:---|:---|
| 独立加载（传统） | N × 完整目录大小 | 线性增长 |
| 共享加载（新功能） | 1 × 完整目录 + N × 子集引用 | 接近常数 |
---
三、5 步快速配置指南
步骤 1：升级 OpenClaw 版本
bash
克隆最新代码
git clone https://github.com/openclaw/openclaw.git
cd openclaw
切换到包含该功能的提交
git checkout dd8d52c7d9c6e890464ec4c6f0a774c2930b3599
安装依赖
npm install
步骤 2：初始化共享目录
javascript
// 在应用入口启用共享模式
const { createSharedCatalog } = require(‘openclaw’);
// 创建全局共享实例（仅需执行一次）
const sharedCatalog = await createSharedCatalog({
source: ‘./models/catalog.yaml’, // 模型定义文件
cache: true, // 启用缓存加速
watch: process.env.NODE_ENV === ‘development’ // 开发环境热重载
});
步骤 3：定义可选加载规则
yaml
models/agent-specific.yaml
代码助手 Agent 专用配置
catalog:
extends: shared # 继承共享目录
optional:
include:
– id: gpt-4-turbo
priority: high # 优先使用
– id: claude-3-sonnet
fallback: true # 降级备选
exclude:
– id: gpt-3.5-turbo # 明确排除旧模型
reason: “context window insufficient”
步骤 4：Agent 实例化配置
javascript
// agents/code-assistant.js
const { Agent } = require(‘openclaw’);
const codeAgent = new Agent({
name: ‘code-assistant’,
// 关键配置：引用共享目录 + 可选子集
modelCatalog: {
shared: true, // 使用全局共享实例
optional: ‘./models/agent-specific.yaml’
},
// 运行时动态选择
selectModel: (task) => {
if (task.complexity > 0.8) {
return ‘gpt-4-turbo’;
}
return ‘claude-3-sonnet’;
}
});
步骤 5：验证与监控
bash
启动时检查模型加载状态
DEBUG=openclaw:catalog npm start
预期输出示例：
openclaw:catalog Shared catalog initialized: 12 models total
openclaw:catalog Optional filter applied: 3 models selected for agent “code-assistant”
openclaw:catalog Memory saved: ~2.4MB (vs independent loading)
---
四、典型应用场景
场景 1：多租户 SaaS 平台
为不同企业客户定制模型白名单，同时共享底层基础设施：
javascript
// 租户配置示例
const tenantConfigs = {
‘enterprise-a’: { include: [‘gpt-4’, ‘claude-3’] },
‘startup-b’: { include: [‘claude-3-haiku’, ‘local-mistral’] },
‘edu-c’: { include: [‘local-llama-3’], exclude: [‘paid-apis’] }
};
场景 2：边缘设备部署
在资源受限环境中仅加载轻量级模型：
yaml
edge-device.yaml
optional:
filter:
maxSize: “2GB” # 模型文件大小限制
maxMemory: “4GB” # 运行时内存限制
quantization: [“q4_0”, “q5_k_m”] # 仅加载量化版本
场景 3：A/B 测试与灰度发布
javascript
// 动态切换模型版本，无需重启服务
await codeAgent.updateCatalog({
optional: {
include: [‘gpt-4-turbo-preview’] // 灰度测试新模型
},
rollback: ‘gpt-4-turbo’ // 保留回退选项
});
---
五、常见问题解答（FAQ）
Q1: 启用共享模式后，如何确保模型目录的线程安全？
OpenClaw 的共享目录采用 不可变数据结构（Immutable） 设计，所有读取操作无锁进行。可选过滤层会创建独立的只读视图，写操作（如热更新）通过 Copy-on-Write 机制实现，不会影响运行中的 Agent 实例。
Q2: 是否支持混合云部署——部分模型本地、部分调用 API？
完全支持。在可选配置中可以为每个模型指定独立的 provider：
yaml
include:
– id: local-llama
provider: local # 本地推理
– id: gpt-4
provider: openai # 云端 API
routing: fallback-only # 仅当本地模型不可用时调用
Q3: 从旧版本迁移需要做哪些改动？
主要变更点：
1. 将 modelCatalog.path 改为 modelCatalog.shared + modelCatalog.optional
2. 移除手动实现的模型缓存逻辑（现已内置）
3. 更新环境变量：OPENCLAW_CATALOG_MODE=shared
详细迁移指南请参考 OpenClaw 文档。
Q4: 可选过滤规则支持哪些条件？
当前支持的条件类型：
- ID 列表：精确匹配模型标识符
- 属性过滤：
contextWindow、costPer1K、latency 等数值比较
- 标签匹配：
tags: ["coding", "multilingual"]
- 自定义函数：JavaScript 谓词函数，实现任意复杂逻辑
Q5: 该功能对性能的具体提升有多少？
根据官方基准测试：
- 内存占用：多 Agent 场景降低 60-80%
- 启动时间：从 O(n) 降至 O(1)，冷启动提升 3-5 倍
- 运行时开销：可选过滤增加 <1ms 延迟（可忽略）
---
六、总结与下一步
可选模型目录共享加载 是 OpenClaw 向生产级 AI Agent 平台演进的重要一步。它解决了多实例部署中的资源冗余问题，同时保持了配置的灵活性。
关键要点回顾：
- ✅ 共享机制显著降低内存占用
- ✅ 可选加载实现精细化模型控制
- ✅ 向后兼容，迁移成本低
- ✅ 支持动态更新，无需重启服务
建议下一步行动：
1. 在 OpenClaw 文档 查阅完整 API 参考
2. 在测试环境验证现有 Agent 的兼容性
3. 关注后续更新：模型目录的版本控制与回滚功能正在开发中
---
相关阅读
---
参考来源
