1. 为什么你的 OpenClaw Agent 总是“失忆”从目录结构说起很多人第一次跑 OpenClaw Agent会遇到一个很迷惑的现象明明在对话里交代过“我是做后端的回答别绕弯子”下一轮新会话它又变回那个客客气气的通用助手。你以为是模型不行其实大概率是 workspace 里的基础设定文件没写对或者压根没被加载。OpenClaw 的 Agent 不是靠一个巨大的系统提示词撑起来的它把“人格、记忆、任务、工具偏好”拆成了几个 Markdown 文件放在~/.openclaw/workspace/下面。运行时按不同时机读取有的每次会话注入有的按需加载有的定时轮询有的只在首次运行出现一次。理解这套加载机制比背字段重要得多。先把目录结构摆出来你可以直接对照自己的机器~/.openclaw/ ├── openclaw.json # 全局配置模型、tools.allow/deny、渠道 └── workspace/ ├── AGENTS.md # 操作手册 记忆协议每次会话注入 ├── SOUL.md # 人格、语气、边界每次会话注入 ├── USER.md # 用户画像每次会话注入 ├── IDENTITY.md # 名称、风格、表情每次会话注入 ├── BOOTSTRAP.md # 一次性出生仪式完成后删除 ├── HEARTBEAT.md # 心跳任务约每 30 分钟轮询 ├── TOOLS.md # 工具使用备忘录按需加载 ├── MEMORY.md # 长期记忆仅主会话加载 └── memory/ ├── 2026-03-01.md # 每日日志 └── 2026-03-02.md一句话记住分工SOUL.md 定风格USER.md 定对象AGENTS.md 定流程IDENTITY.md 定名片HEARTBEAT.md 定定时任务TOOLS.md 定工具怎么用BOOTSTRAP.md 定出生仪式。这七个文件决定了你的 Agent 是“一次性工具”还是“长期搭档”。这里有个容易忽略的点文件放对位置只是第一步能不能被读到取决于加载时机。AGENTS.md、SOUL.md、USER.md、IDENTITY.md 属于“每次会话注入”也就是说它们的内容会直接进上下文写太长会稀释重点。HEARTBEAT.md 是定期轮询不占常规上下文。TOOLS.md 是按需加载Agent 在调用工具前才参考。BOOTSTRAP.md 只在首次运行存在跑完就该消失。我见过最常见的翻车场景是把所有内容一股脑塞进 AGENTS.md写了三千字结果模型抓不住重点行为反而更飘。正确做法是分文件、分职责每个文件控制在 300 到 500 字边界清晰。下面逐个拆开讲每个文件都给可直接复制的模板和验证动作。2. AGENTS.md 与 SOUL.md 模板可直接复制的字段与踩坑点这一节是全文的核心把两个最重要的文件写透。AGENTS.md 是岗位说明书SOUL.md 是灵魂文件两者最好别混着写否则文件又长又别扭。2.1 AGENTS.md操作手册与记忆协议AGENTS.md 回答一个核心问题这个 Agent 应该怎么干活。它在每次会话第一轮被注入上下文所以内容要精炼、可执行。一个高质量的 AGENTS.md 应该包含会话启动协议、记忆系统、行为红线、群聊规则四个板块。# AGENTS.md - 你的工作区 ## 会话启动协议 每次会话开始前无条件执行 1. 读取 SOUL.md —— 确认你是谁 2. 读取 USER.md —— 确认你在帮谁 3. 读取 memory/YYYY-MM-DD.md今天昨天—— 获取近期上下文 4. [仅主会话] 读取 MEMORY.md —— 获取长期记忆 ## 记忆系统 - 每日日志memory/YYYY-MM-DD.md原始记录 - 长期记忆MEMORY.md精选提炼仅主会话加载 - 原则文本 大脑不要“心里记笔记” ## 行为红线 - 不泄露私有数据 - 破坏性命令执行前必须确认 - trash rm可恢复优于永久删除 - 不确定就问 ## 群聊规则如果接入 Discord/飞书群 - 被直接点名时回复 - 能提供真正价值时发言 - 适当使用表情反应而不是每次都打字 - 不要打断人类之间的自然对话最容易踩的坑很多人把 AGENTS.md 写成“要做什么”的清单却忘了写“不做什么”。LLM 默认会发挥创意而你需要的是可预测的行为边界往往比能力描述重要十倍。另外别写太长300 到 500 字比 2000 字更有效文件越长重点越容易被冲淡。2.2 SOUL.md人格与处事原则SOUL.md 决定说话风格、做事方式和边界意识。它偏人格AGENTS.md 偏功能分开写。# SOUL.md ## 核心人格 我是主人的内容搭档不是客服机器人。输出先结论后展开少套话。 ## 沟通风格 - 技术问题专业严谨术语保留英文 - 日常闲聊口语化、轻松可适当幽默 - 简单问题一针见血复杂问题详细拆解 ## 行为原则 1. 写作默认短段落适配手机阅读 2. 涉及事实和数据先核实不确定就标注“待核实” 3. 每篇内容给 3 个标题备选 4. 结尾必须给出行动指令 ## 绝对底线 - 未经确认不对外发布任何内容 - 不编造案例与数据 - 不确定的事情直说不确定不装小贴士加一点有趣的细节效果往往出人意料比如“如果用户跟我说晚安我会记住并在下次提到”。这类细节能让 Agent 从“能回答问题”变成“有稳定感觉”。2.3 USER.md 与 IDENTITY.md画像与名片USER.md 把反复要说的背景沉淀成默认值。IDENTITY.md 定义名称、风格、表情多 Agent 场景下能一眼识别在跟谁对话。# USER.md ## 基本信息 - 称呼Johnson - 时区Asia/Shanghai ## 当前重点 - 主要维护技术博客每周产出 2 篇 - 使用技术栈TypeScript、Python、Rust学习中 ## 偏好 - 输出风格短句、观点明确、可直接发布 - 代码风格2 空格缩进、注释清晰、优先可读性 - 不喜欢空话、鸡汤、没有步骤的建议 ## 默认交付格式 1. 标题备选3 个 2. 正文Markdown 3. 50 字转发文案 ## 禁忌 - 不要帮我做发布操作我手动 - 不要在晚上 10 点后主动发消息# IDENTITY.md - 名称技术助手 JohnsonBot - 风格专业、务实、偶尔幽默 - 表情符号技术讨论、有新想法、提醒注意 - 颜色主题#2d8cff一句话总结SOUL.md 是新助理的个人简历USER.md 是 HR 写给这位助理的“关于你的上司你需要提前知道的事”。2.4 BOOTSTRAP.md 与 HEARTBEAT.md出生仪式与心跳BOOTSTRAP.md 是首次运行的初始化清单跑完 Agent 应自动删除。不要手动创建它否则 Agent 可能一直处于 bootstrapping 状态不断尝试完成里面的任务。# BOOTSTRAP.md - 你好世界 检测到此文件说明你刚刚苏醒。是时候确立自我了。 ## 1. 破冰 用自然、符合你气质的方式开启对话询问用户当前的配置状态。 ## 2. 补全设定 通过简短的交流确认并更新 - 你的名字、风格是否需要微调 → 更新 IDENTITY.md - 用户当前的工作重心、沟通习惯 → 更新 USER.md - 行为边界什么可以做什么绝对不能做→ 更新 SOUL.md 和 AGENTS.md ## 3. 销毁引导 一切就绪后删除 BOOTSTRAP.md。 欢迎来到这个世界。HEARTBEAT.md 是定时任务系统OpenClaw 约每 30 分钟读取一次有到期任务就自动执行。# HEARTBEAT.md ## 每日任务 - 09:00检查 GitHub 通知汇总重要 issue/PR - 10:00检查日历提醒当天会议 - 17:30生成今日工作总结草稿 ## 每周任务 - 周一 09:00生成上周工作总结 - 周五 16:00提醒更新 MEMORY.md长期记忆 ## 状态检查 - 每 2 小时检查服务健康状态如配置了监控实用建议一开始别贪多先配一个每日早晨简报跑通流程再慢慢加。很多人在 HEARTBEAT.md 里塞一大堆任务结果 Agent 不按预期执行不是配置有问题而是输出渠道没配好。心跳任务的输出会发到你绑定的消息渠道先确保渠道工作正常。2.5 TOOLS.md 与多 Agent 配置TOOLS.md 不控制哪些工具存在那是openclaw.json里tools.allow/deny干的事。它是指导 Agent 如何使用工具的备忘录。# TOOLS.md ## 本地工具偏好 - 相机设备客厅用 Tapo C210书房用 EZVIZ C6 - SSH 连接开发服务器 dev-box.local用户名 johnson - 语音合成偏好 ElevenLabs 的 Adam 声音 ## 工具使用约定 - 编辑代码前先用 read 查看完整文件 - 涉及多文件修改时优先使用 apply_patch - 大文件操作记得先检查文件大小 ## 已知 Skill 的注意事项 根据你安装的 Skill 填写具体使用说明多 Agent 场景下每个 Agent 必须有自己的 workspace不要共用openclaw agents add PM --workspace ~/.openclaw/workspace-pm openclaw agents add FE --workspace ~/.openclaw/workspace-fe openclaw agents add BE --workspace ~/.openclaw/workspace-be共用同一个 workspace所有 Agent 会继承同一套性格和行为规则等于创造了几个一模一样的人。另外 Agent Dirstate directory也不要复用否则会导致认证失败、会话混乱。3. 把 endpoint 改到 TaoTokenopenclaw.json 可复制配置Agent 设定文件写好了接下来要解决模型通道问题。OpenClaw 默认可能指向某个官方 endpoint但如果你想让多个 Agent 共用一套 Key、统一计费和限流把 endpoint 改到 TaoToken 是更省心的做法。TaoToken 提供统一的 Key/API 通道官网见 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 地址是 https://taotoken.net/api 。先拿到 Key打开 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 创建一个 API Key复制保存。注意 Key 只在创建时完整显示一次丢了就得重建。然后编辑~/.openclaw/openclaw.json。这个文件是全局配置模型、tools 权限、渠道都在这里。下面是一份可直接复制的片段把 provider 指向 TaoToken{ model: { provider: openai-compatible, baseUrl: https://taotoken.net/api, apiKey: sk-你的TaoToken密钥, modelId: claude-sonnet-4-5, maxTokens: 8192, temperature: 0.7 }, tools: { allow: [read, write, apply_patch, bash], deny: [rm, curl] }, channels: { telegram: { enabled: false } } }三个关键字段必须写全缺一不可Base URL填https://taotoken.net/apiKey填你刚创建的sk-开头密钥Model ID填你要用的模型标识比如claude-sonnet-4-5或gpt-4o。这三个字段对应关系搞错最常见的报错就是 401 或 model not found。如果你用的是 Claude Code 风格的配置或者通过 CC Switch、Cline MCP 这类工具接入同样要写全三件套。以 Claude Code 的 settings 为例路径通常在~/.claude/settings.json{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的TaoToken密钥, ANTHROPIC_MODEL: claude-sonnet-4-5 } }Codex 用户则改~/.codex/auth.json{ base_url: https://taotoken.net/api, api_key: sk-你的TaoToken密钥, model: gpt-4o }配置改完重启 OpenClaw 让配置生效openclaw restart如果你还没装 OpenClaw或者想先确认通道能不能通可以先用模型对话页面验证打开 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 发一句“你好”能正常返回就说明 Key 和通道没问题。这一步能帮你排除掉大部分“到底是配置错还是 Key 错”的纠结。对于长期跑编码任务或 Agent 自动化的场景可以考虑 Coding Plan统一管理额度和调用 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。控制台入口在 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。4. 验证请求从 openclaw doctor 到首次成功会话配置写完不代表跑通必须做逐项验证。这一节给一套可跟做的验证流程每一步都有明确的成功标志。第一步检查配置文件语法。JSON 最容易因为一个逗号或引号出错cat ~/.openclaw/openclaw.json | python3 -m json.tool如果输出格式化后的 JSON说明语法没问题如果报Expecting property name之类就是逗号或引号写错了回去检查。第二步跑 OpenClaw 自带的诊断命令openclaw doctor这个命令会检查 workspace 文件是否存在、配置是否完整、模型通道是否可达。成功时你会看到类似workspace: ok、model: reachable的输出。如果某一行显示missing或unreachable就针对那一项排查。第三步确认 workspace 文件齐全ls -la ~/.openclaw/workspace/对照第一节的目录结构AGENTS.md、SOUL.md、USER.md、IDENTITY.md 应该都在。BOOTSTRAP.md 如果还在说明首次初始化没跑完可以手动触发一次会话让它执行完再删除。第四步发一条真实请求。启动 OpenClaw 后在会话里输入你好请用一句话介绍你自己并说明你当前的工作区路径。成功标志有两个一是能正常返回内容说明模型通道通了二是回复里能体现 SOUL.md 里定义的人格比如“先结论后展开”的风格说明设定文件被正确加载了。如果回复是干巴巴的通用助手语气说明 SOUL.md 没被读到回去检查文件路径和文件名大小写。第五步验证记忆系统。在会话里说记住我下周要发布一篇关于 OpenClaw 配置的文章。然后检查~/.openclaw/workspace/memory/下当天的日志文件应该能看到这条记录被写入。这一步验证的是 AGENTS.md 里的记忆协议是否生效。第六步验证心跳任务。如果你配了 HEARTBEAT.md等一个轮询周期约 30 分钟或者手动触发一次心跳检查看绑定的消息渠道有没有收到任务输出。没收到的话先检查渠道配置再检查 HEARTBEAT.md 里的时间格式。整套流程走完你的 Agent 应该已经能稳定加载设定、正常对话、写入记忆。这时候再回头看那些“失忆”问题基本都能定位到具体是哪个文件没生效。5. 常见报错排查401、local proxy failed 与 reading choices配置过程中有几类报错特别高频这一节按真实报错信息对照排查。401 Unauthorized。这是最常见的几乎都是 Key 问题。先确认openclaw.json里的apiKey字段是完整的sk-开头字符串没有多余空格或换行。然后确认这个 Key 在 TaoToken 控制台里是启用状态没有过期或被删。如果 Key 没问题检查baseUrl是不是写成了https://taotoken.net/api/带了尾部斜杠某些客户端对尾部斜杠敏感去掉试试。local proxy failed / connection refused。这个报错通常出现在你本地配了代理但代理没启动或端口不对。OpenClaw 会读取环境变量里的代理设置检查HTTP_PROXY、HTTPS_PROXY是否指向了一个不可用的地址。临时清掉这些环境变量再试unset HTTP_PROXY HTTPS_PROXY ALL_PROXY openclaw restart如果清掉后能通说明是代理配置问题按你的实际网络环境重新设置。reading choices / unexpected response format。这个报错说明请求发出去了但返回的 JSON 结构不符合预期。常见原因是modelId填错了比如填了一个 TaoToken 不支持的模型名或者provider字段和实际通道不匹配。回到openclaw.json确认provider是openai-compatiblemodelId是文档里列出的可用模型。改完重启再试。OAuth 相关报错。如果你之前用官方 OAuth 登录过配置里可能残留了旧的 token 字段和新的 apiKey 冲突。检查openclaw.json里有没有oauth、refreshToken之类的字段有的话删掉只保留apiKey。Agent 不加载设定文件。报错不明显但行为异常。排查顺序先确认文件名大小写完全匹配Linux 下agents.md和AGENTS.md是两个文件再确认文件在~/.openclaw/workspace/根目录不是子目录最后确认文件编码是 UTF-8没有 BOM 头。多 Agent 认证失败。如果你配了多个 Agent每个都要有独立的 workspace 和 Agent Dir。检查openclaw agents list的输出确认每个 Agent 的路径不重复。共用目录会导致会话串台和认证冲突。把这几类报错对照一遍大部分配置问题都能自己解决。实在定位不到用openclaw doctor --verbose拿到详细日志再对照接入文档排查。6. 从能用 to 真好用把 Agent 变成长期搭档OpenClaw 的使用者里有一条隐形分界线。一边的人每次跟 Agent 说话都像重新 onboarding得再讲一遍背景、偏好和上下文另一边的人Agent 已经知道自己是谁、该怎么说话、用户讨厌什么也记得上次积累的东西。这条分界线叫 workspace。七个文件配置得好你的 Agent 就是专属搭档配置得敷衍它就永远是那个一问一答的通用助手。在关闭这篇文章之前打开你的~/.openclaw/workspace/按这个清单过一遍SOUL.md 有明确的沟通风格和行为底线USER.md 记录了偏好、禁忌和交付格式AGENTS.md 有清晰的启动协议和红线规则不超过 500 字IDENTITY.md 有名称、风格和表情HEARTBEAT.md 配置了至少一个有效的心跳任务TOOLS.md 有本地工具偏好和使用约定BOOTSTRAP.md 已被删除。如果以上都搞定了再把 endpoint 统一到 TaoToken多个 Agent 共用一套 Key计费和限流都在控制台里看得见。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 遇到配置问题可以先翻文档再去控制台确认 Key 状态。跑通之后你会发现真正让 Agent 好用的不是模型多强而是这套设定文件把“你是谁、帮谁、怎么干”讲清楚了。