一、OpenClaw AGENTS.md 配置

AGENTS.md 是什么？

很多人在搜"OpenClaw AGENTS.md 怎么写"，先说清楚它跟其他配置文件的关系：

• SOUL.md = 性格（"你是一个随和、实在的助手"）
• USER.md = 用户信息（"你在帮谁"）
• AGENTS.md = 工作手册（"每天上班先看邮件，写完代码要测试，删文件前要问我"）

这就是AGENTS.md的价值所在：它如同人工智能的工作手册，清晰指引其运作流程。

AGENTS.md文件应放置在workspace的根目录下（与SOUL.md文件同级），这样OpenClaw在每次启动新会话时便会自动加载该文件。

OpenClaw AGENTS.md 记忆写入规范：教 AI 怎么记笔记

光会读记忆不够，还得教它怎么写记忆。未规范的 AI 要么全堆到 MEMORY.md 里（变成流水账），要么根本不写（下次就忘了）。

在 AGENTS.md 里加上写入规范：

## Memory
You wake up fresh each session. These files are your continuity.
### Memory stratification
| Level | File | Purpose |
|------|------|------|
| Index Layer | `MEMORY.md` | About users, capability overview, and memory index. Keep it concise (<40 lines) |
| Project Layer | `memory/projects.md` | Current Status and To-Do of Each Project |
| Infrastructure Layer | `memory/infra.md` | Quick Reference for Server, API, Deployment, and Other Configurations |
| Lesson Layer | `memory/lessons.md` | Pitfalls encountered, graded by severity |
| Log Layer | `memory/YYYY-MM-DD.md` | Daily Original Record |
### Write rules
- Logs are written into `memory/YYYY-MM-DD.md`, with the format shown below
- Project status: Update `memory/projects.md` synchronously when the project makes progress
- Lesson: Write it down in `memory/lessons.md` after falling into a pitfall
- MEMORY.md: Updated only when the index changes, maintaining conciseness
### Log format
### [PROJECT: Name] Title
- **Conclusion**: One-sentence summary
- **File changes**: Involved files
- **Lessons**: Pitfalls (if any)
- **Tags**: #tag1 #tag2
### Iron Law
- Remember the conclusion, not the process
- The tag facilitates retrieval by memorySearch
- "Mental notes" don't survive session restarts. Files do.

记结论不记过程是核心原则。

OpenClaw 安全边界配置：AI 能自己做什么，什么要先问你

在 AGENTS.md 里加上：

## Safety

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

## External vs Internal

**Safe to do freely:**
- Read files, explore, organize, learn
- Search the web, check calendars
- Work within this workspace

**Ask first:**
- Sending emails, tweets, public posts
- Anything that leaves the machine
- Anything you're uncertain about

## Group Chats

You have access to your human's stuff. That doesn't mean you share it.
In groups, you're a participant — not their voice, not their proxy.

这个模板是一个精简的起点，随着你对它的使用日益深入，你将可以逐步向其中增添更多规则。

二、 用 memoryFlush 解决 AI 失忆问题

为什么 OpenClaw 聊着聊着 AI 会"失忆"？

每个模型都存在上下文窗口的限制（例如 Claude 为 200K token），当对话长度接近此限制时，OpenClaw 会自动将较早的对话内容压缩为摘要以释放空间，但这一压缩过程可能导致部分细节的丢失。

OpenClaw memoryFlush 配置方法：压缩前自动保存关键信息

解决方案：开启 memoryFlush，在压缩触发之前，先让 AI 把重要信息写入文件。

在 openclaw.json 里加上：

{
  "agents": {
    "defaults": {
      "compaction": {
        "reserveTokensFloor": 20000,
        "memoryFlush": {
          "enabled": true,
          "softThresholdTokens": 4000
        }
      }
    }
  }
}

参数说明：

💡 memoryFlush 静默执行，不打断对话。开了 verbose 模式（/verbose）可以看到 🧹 Auto-compaction complete 的提示。

OpenClaw memorySearch 精度优化：结构化日志大幅提升检索命中率

memorySearch 的底层是向量语义检索，结构化日志的命中率比非结构化日志高得多：

用免费 SiliconFlow bge-m3 配置 OpenClaw memorySearch

国内用户最快上手的方案——SiliconFlow 提供的 bge-m3 向量模型完全免费：

{
  "memorySearch": {
    "enabled": true,
    "provider": "openai",
    "remote": {
      "baseUrl": "https://api.siliconflow.cn/v1",
      "apiKey": "你的 SiliconFlow API key"
    },
    "model": "BAAI/bge-m3"
  }
}

注册硅基流动，点击：https://cloud.siliconflow.cn/i/DU2lQbhb，注册 → 控制台 → 创建 API key。

推荐 bge-m3 的原因在于它完全免费，对中英文双语的支持出色，并且其 1024 维向量在精度和性能之间取得了良好的平衡。

OpenClaw 自动记忆维护：防止过期日志干扰 memorySearch 结果

在 HEARTBEAT.md 里加上每周自动维护任务：

## 记忆维护（每周一次）
读取 `memory/heartbeat-state.json`，检查 `lastMemoryMaintenance` 字段。
如果距今 >= 7 天：
1. 读最近 7 天的 `memory/YYYY-MM-DD.md` 日志
2. 提炼有价值的信息到对应文件（projects.md / lessons.md）
3. 压缩已完成一次性任务的日志为一行结论
4. 删除过期信息
5. 更新 `heartbeat-state.json` 的 `lastMemoryMaintenance` 为今天

创建 memory/heartbeat-state.json：

{
  "lastMemoryMaintenance": "2026-01-01"
}

三、OpenClaw 子 Agent — 让 AI 并行处理复杂任务

OpenClaw 子 Agent 配置方法（openclaw.json + AGENTS.md）

第一步：在 AGENTS.md 里声明使用规范

## 子 Agent

如果任务比较复杂或耗时较长，可以派子 agent 去执行。

### 模型选择策略
| 等级 | 模型别名 | 适用场景 |
|------|----------|----------|
| 🔴 高 | opus | 复杂架构设计、多文件重构、深度推理 |
| 🟡 中 | sonnet | 写代码、写脚本、信息整理（默认） |
| 🟢 低 | haiku | 简单文件操作、格式转换、搜索汇总 |

第二步：在 openclaw.json 里配置模型别名

{
  "models": {
    "your-provider/claude-opus-4": { "alias": "opus" },
    "your-provider/claude-sonnet-4": { "alias": "sonnet" },
    "your-provider/claude-haiku-4": { "alias": "haiku" }
  }
}

子 Agent 模型分级token 消耗能降 60-70%。

OpenClaw 子 Agent task 描述写法

子 Agent 是"零上下文"的，只能看到主脑给它的 task 描述，所以描述质量决定输出质量。

OpenClaw 子 Agent 并发限制

经验值：同时最多跑 2 个子 Agent，4 个基本触发 API 429 限流。有依赖关系的任务（B 依赖 A 的输出）必须串行，在 AGENTS.md 里提醒主脑注意任务依赖即可。

四、openclaw.json 配置参数调到最优

所有配置写在 ~/.openclaw/openclaw.json，修改后 openclaw gateway restart 生效。

blockStreaming — 解决 AI 长回复要等很久的问题

{
  "agents": {
    "defaults": {
      "blockStreamingDefault": "on",
      "blockStreamingBreak": "text_end",
      "blockStreamingChunk": { "minChars": 200, "maxChars": 1500 }
    }
  }
}

ackReaction — 发消息后立刻知道 AI 收到了

{
  "channels": {
    "discord": { "ackReaction": "🫐" },
    "telegram": { "ackReaction": "👀" }
  }
}

compaction — 解决 AI 长对话失忆问题

{
  "agents": {
    "defaults": {
      "compaction": {
        "reserveTokensFloor": 20000,
        "memoryFlush": { "enabled": true, "softThresholdTokens": 4000 }
      }
    }
  }
}

相关命令：/compact 重点保留技术决策、/new（开新 session）、/status（查 token 用量）

Heartbeat 调优 — 防止 AI 在非活跃时间骚扰你

{
  "agents": {
    "defaults": {
      "heartbeat": {
        "every": "30m",
        "target": "last",
        "activeHours": { "start": "08:00", "end": "23:00" }
      }
    }
  }
}

openclaw.json 其他常用配置汇总

常见问题 FAQ

Q：OpenClaw AGENTS.md 放在哪里？

A：workspace 根目录，和 SOUL.md、USER.md 同级。路径通常是 ~/.openclaw/workspace/AGENTS.md。

Q：OpenClaw memoryFlush 开了还是失忆怎么办？

A：检查 softThresholdTokens 是否设够大（推荐 4000）。对话特别关键时，手动 /compact 重点保留XXX 指定保留内容。

Q：OpenClaw Cron 任务设了但没触发？

A：99% 是时区问题——没设 tz 字段导致按 UTC 执行。另外检查 delivery.mode 是否设为 "announce"，不设任务静默执行，你不会收到通知。

在使用 OpenClaw 构建个人自动化助理时，最令人头疼的往往不是系统配置，而是每月面对持续上涨的 OpenAI 或 Claude API 账单。一个活跃的 AI Agent（智能代理）为了维持其思考循环、完成自我纠错并调用各类工具，每日消耗的 Token 数量可能高达数百万。

除此之外，许多企业用户与技术爱好者对数据隐私有着极高的要求，如果你想让OpenClaw帮忙整理公司的财务报表、阅读私密的个人日记，或是审查尚未公开的商业代码，将这些敏感数据上传至云端API显然会带来极大的安全风险。

有没有一种方法既能享受 OpenClaw 强大的自动化生态，又能彻底拔掉网线，实现真正的“零成本、绝对隐私”？答案是肯定的：结合本地大模型神器 Ollama。本文将全面解析如何在完全离线的状态下，将 OpenClaw 与 Ollama 无缝结合，从而打造一个仅需电费即可运行的“永动机”式个人助理。

一、 为什么选择 Ollama 作为 OpenClaw 的本地大脑？

目前市面上有诸多本地大模型运行框架，如 LM Studio、vLLM、Text-generation-webui 等，但 OpenClaw 官方明确将 Ollama 列为第一优先级的本地部署方案，原因有三：

• 极简的 API 兼容性： Ollama 默认提供的 11434 端口 API 完全兼容 OpenAI 的请求格式。这意味着 OpenClaw 的底层逻辑无需任何修改，就能像调用 ChatGPT 一样调用本地模型。
• 跨平台且资源优化极佳： Ollama 都能自动识别你的硬件，优先使用 GPU 或 NPU 进行加速。
• 模型量化管理方便： 你不需要去 HuggingFace 费力寻找各种 .GGUF 文件。Ollama 的模型库就像 Docker Hub 一样，一行命令即可拉取经过 INT4 极限压缩的优质模型，最大程度节省你的显存。

二、 离线运行的硬件配置天梯图：你的电脑能跑什么模型？

在开始之前，我们必须打破一个幻觉：本地大模型虽然不要 API 费用，但它对你的电脑硬件（特别是显存 VRAM 和 内存 RAM）要求极高。如果强行运行超出硬件承受能力的模型，不仅速度慢如蜗牛，还容易导致 OpenClaw 报错 500 断联。

以下是经过 OpenClaw 社区实测的本地硬件配置与模型选择天梯图：

三、 安装 Ollama 并拉取最强 Agent 模型

步骤 1：安装 Ollama 客户端

前往 Ollama 官方网站 (ollama.com) 下载对应操作系统的安装包。安装过程一路点击下一步即可。安装完成后，Ollama 会在系统后台默默运行。

步骤 2：挑选并拉取模型 (核心环节！)

不是所有的 LLM 都适合做 Agent。有些模型虽然写文章很厉害，但它们“听不懂” OpenClaw 发送的 JSON 格式的工具调用指令（Function Calling）。为了保证 OpenClaw 能够正常使用插件，你必须选择经过工具调用微调的模型。

🏆 2026年 OpenClaw 本地模型推荐榜：

• Qwen 2.5 (通义千问系列)： 目前开源界最强 Agent 模型。不仅中文原生支持极好，且 Function Calling 能力极强。
• Llama 3.1 系列： Meta 开源标杆，英文逻辑推理无敌，但中文偶尔会夹杂英文。

打开你的终端（Windows 为 PowerShell，Mac 为 Terminal），执行以下命令拉取模型（以 16GB 内存电脑拉取 Qwen2.5 7B 为例）：

ollama run qwen2.5:7b

首次运行将下载约4GB的模型文件，请耐心等待。下载完成后，终端会显示>>>聊天提示符，此时可输入“你好”来测试模型是否正常运行；测试完毕后输入/bye退出，但请确保Ollama软件仍在系统托盘保持运行状态。

四、 手把手：将 OpenClaw 对接至本地 Ollama

现在本地大脑已经就绪，我们需要让 OpenClaw 的控制面板指向这个大脑，从而摆脱云端 API 依赖。

1. 在 OpenClaw Web UI 中进行配置

1. 启动您的 OpenClaw，打开浏览器进入 Web UI 控制面板（通常为 http://localhost:18789）。
2. 点击左下角的 ⚙️ Settings (设置)，进入 LLM Provider (模型提供商) 选项卡。
3. 在 Provider 下拉菜单中，将默认的 OpenAI 改为 Ollama (Local)。

2. 填写关键参数

在这个界面中，你需要极其准确地填写以下三个参数：

• Base URL (基础地址): 填写 https://www.jumei.ai/api 或者 http://localhost:11434/api。这是 Ollama 默认监听的本地端口。
• Model Name (模型名称): 必须与你刚才在终端拉取的名称完全一致！例如输入 qwen2.5:7b。不要多加空格。
• Context Window (上下文窗口): 建议设置为 8192。如果你内存很小，可以降低到 4096，但这会影响 AI 记忆长对话的能力。

3. 保存并测试

点击界面上的 Test Connection (测试连接) 按钮。如果弹出绿色的“Successfully connected to local model”，恭喜你，你的本地自动化帝国已经成功建立！

五、 进阶调优：让本地模型发挥 120% 的战斗力

本地模型由于参数量远小于 GPT-4o，往往需要更加精细的调教才能达到极佳的自动化效果。

1. 降低 Temperature (温度值)

Agent 在执行任务（如写代码、执行终端命令）时，需要的是绝对的精准，而不是天马行空的创意。在 OpenClaw 的 Advanced Settings (高级设置) 中，找到 Temperature 选项，将其从默认的 0.7 降低到 0.1 或 0.2。这能有效避免本地模型胡乱捏造不存在的终端命令。

2. 修改 System Prompt (系统提示词) 增强指令感

如果你的本地模型（例如 7B 级别的小模型）经常忘记调用工具，只会陪你聊天。你可以在系统设置的 Custom System Prompt 中加入这句强力约束（中文或英文皆可，视模型主力语言而定）：

"你是一个完全自主的系统管理员。当用户提出需求时，你必须优先思考使用你的 AgentSkills 工具（如 shell, browser）来解决问题，而不是仅仅给出建议。请严格输出正确的 JSON 工具调用格式。"

3. 开启“保持模型常驻内存” (Keep Alive)

Ollama 默认会在闲置 5 分钟后将模型从显存中卸载，以节省资源。这会导致 OpenClaw 每次接到新任务时，都要重新加载几 GB 的模型，响应极慢。你可以通过修改环境变量，强制模型常驻：

# 在终端中设置环境变量并重启 Ollama 服务
export OLLAMA_KEEP_ALIVE=24h

六、 常见离线运行故障排错 (Troubleshooting)

故障 1：点击测试连接提示 "Failed to fetch" 或 "Connection Refused"

原因： Ollama 服务未启动，或者 OpenClaw 运行在 Docker 中，无法直接通过 localhost 访问宿主机的 11434 端口。

解决办法： 如果 OpenClaw 在 Docker 中，请将 Base URL 中的 localhost 更改为宿主机的局域网 IP（例如 http://192.168.1.100:11434/api）。并在宿主机设置 Ollama 允许跨域及外部访问（设置环境变量 OLLAMA_HOST=0.0.0.0）。

故障 2：AI 开始疯狂重复同一句话，陷入无限死循环

原因： 这是典型的小尺寸模型“复读机效应”，或者是因为 Context Window 溢出导致模型忘记了之前的工具执行结果。

解决办法： 点击界面上的“Stop Agent”强行中止任务。点击右上角的“Clear Memory”清空本轮对话上下文。尝试调高一点点 Temperature（比如加到 0.3），或者更换参数量更大的模型（从 8B 换到 14B）。

故障 3：模型推理时电脑卡顿、鼠标掉帧

原因： 你的模型体积过大，Ollama 将一部分模型数据加载到了慢速的硬盘虚拟内存（Swap）中。这也叫“爆显存”。

解决办法： 放弃当前模型，运行 ollama rm [模型名] 删除它。重新拉取体积更小的量化版本，例如将 qwen2.5:32b 降级为 qwen2.5:7b。

七、 常见问题解答 (FAQ)

Q1: 断网后，OpenClaw 的网页搜索 (Web Search) 技能还能用吗？

不行。虽然你的大脑（Ollama 模型）和身体（OpenClaw 核心程序）都在本地，但如果你拔掉了网线，需要联网的 AgentSkills（如网页爬虫、发送邮件、查询天气）都会报错。断网状态下，OpenClaw 只能执行读取本地文件、运行本地脚本、整理本地磁盘等纯本地任务。

Q2: 我可以同时接入 OpenAI 和本地 Ollama，让它们协同工作吗？

未来的 OpenClaw 2.0 版本有规划“多模型混合路由”功能（例如简单的任务让本地模型处理，遇到极度复杂的代码交给云端 GPT-4o）。但在当前版本中，你同一时间只能在 Settings 中激活一个主要的 LLM Provider。

Q3: 为什么我的本地模型用命令行工具时总是出错？

本地小模型对 Shell 命令的掌握程度不如云端巨无霸。建议在运行涉及 rm, sudo, 或批量重命名的破坏性指令时，务必在 OpenClaw 的安全设置中开启 Human-in-the-loop（人工确认），即 AI 每次敲回车前，都会弹窗等待你的批准，防止本地系统被 AI 误删。

结语：实现真正的 AI 数字主权

将 OpenClaw 成功对接本地 Ollama，标志着你跨入了 AI 极客的更高阶殿堂。你不再受制于云端 API 的额度限制，也不用担心隐私数据被用于训练其他模型。在这台电脑里，你拥有一个绝对忠诚、免费且永不停歇的数字员工。