OpenClaw AGENTS.md 深度配置指南:打造你的 AI 助手大脑

## Session StartupBefore doing anything else:1. Read `SOUL.md` — this is who you are2. Read `USER.md` — this is who you're helping3. Read `memory/YYYY-MM-DD.md` (today + yesterday) for recent context4. **If in MAIN SESSION** (direct chat with your human): Also read `MEMORY.md`

{  session: {    dmScope: "per-channel-peer", // 按渠道 + 发送者隔离    // 其他可选值：    // - "main": 所有私信共享一个会话（默认）    // - "per-peer": 按发送者隔离（跨渠道）    // - "per-account-channel-peer": 按账户 + 渠道 + 发送者隔离  },}

{  session: {    reset: {      // 每日重置（默认凌晨 4 点，网关主机当地时间）      dailyTime: "04:00",      // 空闲重置（可选）      idleMinutes: 1440, // 24 小时无活动则重置    },    // 会话维护    maintenance: {      mode: "enforce", // 或 "warn"      pruneAfter: "30d", // 30 天后清理      maxEntries: 500, // 最多保留 500 个会话      rotateBytes: "10mb", // sessions.json 超过此大小则轮换    },  },}

┌─────────────────────────────────────────┐│           MEMORY.md (长期记忆)           ││  持久化事实、偏好、决策、经验教训         ││  类似人类的"长期记忆"                     │└─────────────────────────────────────────┘                    ↑                    │ 定期提炼                    │┌─────────────────────────────────────────┐│        memory/YYYY-MM-DD.md (每日日志)   ││  原始对话记录、临时上下文、观察笔记       ││  类似人类的"短期记忆/工作记忆"            │└─────────────────────────────────────────┘

## 用户偏好- 喜欢 TypeScript 而非 JavaScript- 工作时间：9:00-18:00 (Asia/Shanghai)- 通信偏好：重要事项用邮件，日常用即时消息## 项目上下文- 当前主要项目：OpenClaw 文档优化- GitHub 仓库：github.com/openclaw/openclaw## 重要决策- 2026-04-01: 决定使用 Qwen 作为默认模型- 2026-04-05: 启用沙箱模式执行代码

# 2026-04-09## 进行中的任务- [ ] 撰写 AGENTS.md 配置博文- [x] 修复 webhook 路由问题## 重要对话摘要- 用户 Nancy 询问了 OpenClaw 记忆系统的工作原理- 讨论了会话隔离的安全配置## 临时上下文- 用户今天可能会外出，需要关注天气- 明天有团队会议需要准备材料

{  agents: {    defaults: {      compaction: {        memoryFlush: {          enabled: true, // 默认开启          softThresholdTokens: 4000, // 软阈值          prompt: "请将重要信息写入记忆文件",          systemPrompt: "使用 NO_REPLY 标记，不要输出用户可见内容",        },      },    },  },}

# 手动触发记忆回填（从历史日志中提炼）openclaw memory rem-backfill --path ./memory --stage-short-term

## Red Lines- Don't exfiltrate private data. Ever.- Don't run destructive commands without asking.- `trash` > `rm` (recoverable beats gone forever)- When in doubt, ask.

{  agents: {    defaults: {      sandbox: {        mode: "non-main",    // "off" | "non-main" | "all"        scope: "session",    // "agent" | "session" | "shared"        backend: "docker",   // "docker" | "ssh" | "openshell"        workspaceAccess: "none", // "none" | "ro" | "rw"        // Docker 沙箱配置        docker: {          image: "openclaw-sandbox:bookworm-slim",          network: "none",   // 默认无网络，可设为 "bridge" 或其他          binds: [           // 挂载主机目录            "/home/user/source:/source:ro", // 只读挂载          ],          // 一次性设置命令（容器创建后运行一次）          setupCommand: "apt-get update && apt-get install -y curl jq",        },        // 沙箱浏览器配置        browser: {          autoStart: true,   // 自动启动浏览器容器          network: "openclaw-sandbox-browser", // 专用网络        },      },    },  },}

{  tools: {    // 工具配置文件    profile: "messaging",    // 拒绝的工具组    deny: [      "group:automation",       "group:runtime",       "group:fs",      "sessions_spawn",      "sessions_send",    ],    // 文件系统限制    fs: {      workspaceOnly: true,  // 限制文件访问到工作空间    },    // 执行配置    exec: {      security: "allowlist", // "deny" | "allowlist" | "full"      ask: "on-miss",        // "off" | "on-miss" | "always"      applyPatch: {        workspaceOnly: true, // apply_patch 仅限工作空间      },    },    // 高权限工具（逃逸沙箱）    elevated: {      enabled: false,        // 禁用高权限工具      allowFrom: {           // 如果启用，指定允许的用户        discord: ["user:123456789"],        telegram: ["tg:123456789"],      },    },    // 沙箱内工具策略（可选）    sandbox: {      tools: {        // 沙箱内允许的工具      },    },  },}

{  channels: {    telegram: {      contextVisibility: "allowlist", // "all" | "allowlist" | "allowlist_quote"    },  },}

# 运行安全审计openclaw security audit# 深度审计（包含实时 Gateway 探测）openclaw security audit --deep# 自动修复常见问题openclaw security audit --fix# JSON 输出（用于自动化）openclaw security audit --json

{  gateway: {    mode: "local",    bind: "loopback",    auth: { mode: "token", 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" },    elevated: { enabled: false },  },  channels: {    whatsapp: { dmPolicy: "pairing", groups: { "*": { requireMention: true } } },  },}

Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.

{  channels: {    defaults: {      heartbeat: {        showOk: false,        // 是否在心跳中显示正常状态        showAlerts: true,     // 是否显示告警状态        useIndicator: true,   // 使用紧凑指示器格式      },    },  },}

# HEARTBEAT.md## 定期检查清单- [ ] 检查紧急未读邮件- [ ] 查看未来 24-48 小时日历事件- [ ] 检查社交媒体提及- [ ] 查看天气（如果用户可能外出）## 状态追踪记录在 `memory/heartbeat-state.json`:```json{  "lastChecks": {    "email": 1703275200,    "calendar": 1703260800,    "weather": null  }}

### 5.4 何时主动联系用户- 重要邮件到达- 即将发生的日历事件（<2 小时）- 发现有趣的信息- 超过 8 小时没有交流### 5.5 何时保持安静- 深夜（23:00-08:00）除非紧急- 用户明显忙碌- 自上次检查后没有新内容- 刚检查过（<30 分钟）---## 六、实战配置示例### 6.1 个人助手完整配置（v2026.3.13）> **完整配置文件**：`~/.openclaw/openclaw.json````json5// ~/.openclaw/openclaw.json// 使用 JSON5 格式（支持注释和尾随逗号）{  // ==================== 网关配置 ====================  // 文件位置：~/.openclaw/openclaw.json  // 配置路径：gateway.*  // ==================== 网关配置 ====================  gateway: {    mode: "local",    bind: "loopback",  // 仅本地访问    auth: {       mode: "token",       token: "your-secure-token-here", // 使用长随机令牌      rateLimit: { requests: 100, intervalMs: 60000 }, // 速率限制    },    // 可信代理（如果使用反向代理）    trustedProxies: ["127.0.0.1"],    // Control UI 配置    controlUi: {      allowedOrigins: ["http://localhost:18789"],    },  },  // ==================== 会话配置 ====================  // 文件位置：~/.openclaw/openclaw.json  // 配置路径：session.*  session: {    dmScope: "per-channel-peer", // DM 隔离策略    reset: {      dailyTime: "04:00",  // 每日重置时间（网关当地时间）      idleMinutes: 1440,   // 空闲重置（24 小时）    },    maintenance: {      mode: "enforce",      pruneAfter: "30d",      maxEntries: 500,      rotateBytes: "10mb",    },  },  // ==================== 渠道配置 ====================  // 文件位置：~/.openclaw/openclaw.json  // 配置路径：channels.*  channels: {    // 渠道默认策略    defaults: {      groupPolicy: "allowlist", // open | allowlist | disabled      contextVisibility: "all", // all | allowlist | allowlist_quote      heartbeat: {        showOk: false,        showAlerts: true,        useIndicator: true,      },    },    // WhatsApp 配置    whatsapp: {      dmPolicy: "pairing", // pairing | allowlist | open | disabled      allowFrom: ["+8613800138000"],      groups: {        "*": { requireMention: true },      },      sendReadReceipts: true,    },    // Telegram 配置    telegram: {      enabled: true,      botToken: "your-bot-token", // 或使用 tokenFile      dmPolicy: "pairing",      allowFrom: ["tg:123456789"],      groups: {        "*": { requireMention: true },      },      streaming: "partial", // off | partial | block | progress    },  },  // ==================== 命令配置 ====================  // 文件位置：~/.openclaw/openclaw.json  // 配置路径：commands.*  commands: {    native: "auto",        // 自动注册原生命令    nativeSkills: "auto",  // 自动注册技能命令    text: true,            // 解析聊天中的 /commands    bash: false,           // 禁用 ! 命令（安全）    config: false,         // 禁用 /config（生产环境建议关闭）    ownerAllowFrom: ["discord:123456789"],  },  // ==================== 代理配置 ====================  // 文件位置：~/.openclaw/openclaw.json  // 配置路径：agents.defaults.*  agents: {    defaults: {      workspace: "~/.openclaw/workspace",      // 模型配置      model: {        primary: "anthropic/claude-opus-4-6",        fallbacks: ["openai/gpt-5.4", "qwen/qwen3.5-plus"],      },      // 图像模型      imageModel: {        primary: "openai/gpt-4.1-nano",        fallbacks: ["google/gemini-2.0-flash"],      },      // 记忆搜索配置      memorySearch: {        provider: "openai", // 或 gemini, voyage, mistral, ollama        model: "text-embedding-3-small",      },      // 沙箱配置      sandbox: {        mode: "non-main",        scope: "session",        backend: "docker",        workspaceAccess: "none",        docker: {          network: "none",          binds: [],        },      },      // 压缩配置      compaction: {        enabled: true,        reserveTokens: 16384,        keepRecentTokens: 20000,        memoryFlush: {          enabled: true,          softThresholdTokens: 4000,        },      },      // 上下文注入优化      contextInjection: "continuation-skip", // 安全延续回合跳过重复注入      bootstrapMaxChars: 20000, // 单文件最大字符      bootstrapTotalMaxChars: 150000, // 总注入字符限制    },  },  // ==================== 工具配置 ====================  // 文件位置：~/.openclaw/openclaw.json  // 配置路径：tools.*  tools: {    profile: "messaging",    deny: [      "group:automation",      "group:runtime",      "sessions_spawn",      "sessions_send",    ],    fs: { workspaceOnly: true },    exec: {      security: "allowlist",      ask: "on-miss",      applyPatch: { workspaceOnly: true },    },    elevated: { enabled: false },  },  // ==================== 日志配置 ====================  // 文件位置：~/.openclaw/openclaw.json  // 配置路径：logging.*  logging: {    redactSensitive: "tools", // none | tools | all  },}

# 配置文件：~/.openclaw/openclaw.jsonopenclaw security audit --fix  # 自动修复常见问题

openclaw security audit --deep  # 深度审计（包含实时探测）openclaw security audit --json  # JSON 输出（自动化）

// 配置文件：~/.openclaw/openclaw.json// 配置路径：agents.defaults.sandbox{ agents: { defaults: { sandbox: { mode: "non-main" } } } }

cd ~/.openclaw/workspace  # 工作空间目录git initgit add AGENTS.md SOUL.md USER.md MEMORY.md memory/git commit -m "Initial workspace"

openclaw config schema      # 查看完整配置架构openclaw config.schema.lookup session  # 查看特定配置路径

// 配置文件：~/.openclaw/openclaw.json// 配置路径：agents.defaults.contextInjection{ agents: { defaults: { contextInjection: "continuation-skip" } } }

{  gateway: {    mode: "local",           // 网关模式    bind: "loopback",        // 绑定地址    auth: { mode: "token" }, // 认证方式  },}

{  session: {    dmScope: "per-channel-peer",  // DM 隔离策略    reset: { dailyTime: "04:00" }, // 每日重置时间    maintenance: { mode: "enforce" }, // 会话维护  },}

{  channels: {    defaults: {      groupPolicy: "allowlist",   // 群组策略      heartbeat: { showOk: false }, // 心跳输出    },    whatsapp: { dmPolicy: "pairing" }, // WhatsApp 配置    telegram: { botToken: "xxx" },     // Telegram 配置  },}

{  agents: {    defaults: {      workspace: "~/.openclaw/workspace", // 工作空间      model: { primary: "anthropic/claude-opus-4-6" }, // 模型      memorySearch: { provider: "openai" }, // 记忆搜索      sandbox: { mode: "non-main" }, // 沙箱模式      compaction: { enabled: true }, // 压缩配置    },  },}

{  tools: {    profile: "messaging",  // 工具配置文件    deny: ["group:fs"],    // 拒绝的工具    exec: { security: "allowlist" }, // 执行安全    elevated: { enabled: false },    // 高权限工具  },}

# 查看配置openclaw config get <path>              # 获取配置值openclaw config schema                  # 查看完整配置架构openclaw config.schema.lookup session   # 查看特定配置路径# 修改配置openclaw config set session.dmScope per-channel-peer# 安全审计openclaw security audit                 # 运行安全审计openclaw security audit --deep          # 深度审计openclaw security audit --fix           # 自动修复# 会话管理openclaw sessions                       # 查看会话列表openclaw sessions cleanup --dry-run     # 预览清理# 记忆管理openclaw memory status                  # 查看记忆状态openclaw memory search "query"          # 搜索记忆openclaw memory index --force           # 重建索引# 定时任务openclaw cron list                      # 查看 cron 任务openclaw cron add                       # 添加任务# Gateway 管理openclaw gateway status                 # 查看状态openclaw gateway restart                # 重启服务openclaw dashboard                      # 打开控制面板

~/.openclaw/├── openclaw.json                    # 主配置文件├── credentials/                     # 渠道凭证（加密存储）│   └── whatsapp/├── agents/│   └── default/│       ├── sessions/                # 会话存储│       │   ├── sessions.json        # 会话索引│       │   └── *.jsonl              # 会话转录│       └── agent/│           └── auth-profiles.json   # 认证配置文件├── workspace/                       # 工作空间（可自定义）│   ├── AGENTS.md                    # 行为准则│   ├── SOUL.md                      # 人格定义│   ├── USER.md                      # 用户信息│   ├── MEMORY.md                    # 长期记忆│   ├── HEARTBEAT.md                 # 心跳任务│   ├── TOOLS.md                     # 工具笔记│   └── memory/│       ├── 2026-04-09.md            # 今日日志│       ├── 2026-04-08.md            # 昨日日志│       └── ...                      # 历史日志└── memory/                          # 记忆索引（SQLite）    └── default.sqlite               # 记忆数据库