1. 把核心思路拆开3 个文件到底在做什么OpenClaw Agent 这类运行时本质上做的事情就一件把你输入的指令拆解成一系列可执行的步骤再调用对应工具把结果拿回来。你真正要配置的不是“模型怎么想”而是“模型能碰什么、能调什么、按什么规则工作”。所以在动手之前先把配置结构想清楚不然后面每次调试都会变成猜谜。我见过太多人把模型参数、工具列表、提示词全部塞进一个又长又乱的 YAML 文件。表面上看好像很集中实际一改就崩你想调整一个工具参数却在几千行里找半天模型行为不对你在参数区里来回试结果问题其实出在提示词上。这个项目最值得借鉴的地方就是刻意把配置拆成三个文件每个文件只负责一件清晰的事情。结构如下文件职责典型内容openclaw.yaml运行时与模型连接配置模型供应商、模型名、密钥、上下文长度、记忆策略、执行循环上限tools.yaml工具注册与权限边界工具列表、参数定义、超时时间、重试次数、允许访问的域名范围system_prompt.md行为控制与输出规范角色设定、任务流程、调用工具的顺序、禁止事项、回答格式为什么是这三个文件而不是两个或者四个因为它们的变更频率和关注点是完全不同的。模型连接配置基本只在项目初始化、切换模型、调整上下文大小时才动属于“基建”工具列表会随着项目需求频繁增删比如这个月要接天气 API下个月要接网页搜索属于“插件”提示词则是每次调试行为时大概率要改的属于“运营策略”。三者混在一起等于把地基、门窗和室内装修图纸画在同一张纸上任何一处改动都会牵一发动全身。分开以后排查问题的路径变得非常短。Agent 不调用某个工具你会直接打开tools.yaml看描述和参数Agent 回答了错误格式你会打开system_prompt.md看输出规范Agent 连接失败你会打开openclaw.yaml看供应商配置和模型 ID。这就是逻辑解耦带来的效率提升而且协作时别人接手你的项目也能一眼看懂结构。还要注意一点三个文件不是平等的openclaw.yaml是入口另外两个文件是它引用的资源。启动时通过openclaw.yaml加载工具配置和提示词而不是让运行时去目录里乱找。这样设计的好处是方便做多环境切换比如同一套工具和提示词你可以用一个生产配置和一个调试配置分别引用工具和提示词本身不需要复制一遍。2. 三个文件逐个拆解每个字段都要知道为什么这么写2.1 openclaw.yaml代理运行的发动机标定先看一段最小可运行的openclaw.yaml示例provider: type: openai-compatible base_url: ${MODEL_BASE_URL} api_key: ${MODEL_API_KEY} model: assistant-x1 temperature: 0 max_tokens: 1024 memory: type: local path: ./memory window: 20 loop: max_iterations: 5 timeout_seconds: 30 stop_condition: task_completed tools: config: ./tools.yaml prompt: file: ./system_prompt.md这里有几个字段值得多说两句。provider.type写成openai-compatible而不是直接写死某个厂商。因为目前很多模型服务商都提供兼容某主流格式的接口你只需要换一下base_url和api_key整个项目就可以切换到另一个模型代码和工具配置完全不用动。我实际用下来这种写法在项目初期特别有用因为你会不断对比不同模型的工具调用能力改一行环境变量就能完成切换省掉很多重复操作。api_key写成${MODEL_API_KEY}这种占位符形式而不是直接把密钥写进去。核心原因是防止密钥被提交进版本库。这个问题太常见了很多人配置本地跑通了顺手 git commit结果密钥就进仓库了。用占位符后OpenClaw 启动时会从当前 shell 环境变量里读取真实值没读到会直接报错而不是带一个空字符串跑起来。temperature: 0这个选择是刻意的。对于工具调用类任务你希望模型尽量按照规则走而不是发挥创造力。温度越高模型越容易在工具选择上发挥“想象力”比如明明有搜索工具它偏偏根据训练数据脑补一个结果。我调试过几个同事的项目发现他们总是抱怨 Agent 乱调参数打开配置一看 temperature 是 0.9那不乱才怪。写日志、查天气、调用数据库这类任务建议直接 0只有做头脑风暴、生成文案这种开放式任务才把温度调高。memory.window表示在多少轮对话内保留上下文。窗口设太大token 消耗成倍上升窗口设太小Agent 会忘记前面几步的操作结果。我的经验是先设 10 到 20 之间跑通流程然后看实际日志里最长需要多少上下文再往上微调。没必要一上来就开 50。loop.max_iterations是防止 Agent 陷入死循环的关键保护。一个复杂任务可能会拆成多轮工具调用比如先搜索再读取页面再提取信息再写入文件最后汇总。但如果没有迭代上限模型可能在“调用工具—得到结果—再调用工具”之间循环十几次都不收敛浪费 token 不说还会卡住整个流程。设置成 5 或 6一般的多步任务足够用特殊场景再根据日志调整。2.2 tools.yaml工具注册与权限边界tools.yaml的内容决定了 Agent 的“手”能伸到哪里。下面是一个示例- name: weather_query description: 查询指定城市当天的实时天气返回温度、风向和天气状况。输入需要用中文城市名。 parameters: - name: city type: string required: true description: 城市中文名例如“北京”“上海”“广州” - name: date type: string required: false description: 日期格式 YYYY-MM-DD不填则默认今天 enabled: true timeout: 8 max_retries: 1 allow_domains: - api.weather.example.com - name: write_log description: 把一条文本信息追加写入指定日志文件用于记录 Agent 的行为或结果。 parameters: - name: content type: string required: true description: 要写入文件的具体内容必须是完整的一行文本 - name: file type: string required: false description: 文件名默认是 ./agent.log enabled: true timeout: 3 max_retries: 1工具配置里最重要的不是name而是description。可以这么理解模型看到description的方式就像新同事读使用手册一样。如果你只写“查询天气”语言模型会搞不清楚这个工具是查当前温度还是查未来七天预报更不知道参数应该填城市还是填经纬度。把描述写成一句完整的话说清楚做什么、输入什么、输出什么模型才可能正确调用。parameters里的每个字段都要显式声明是否必填并给出一个具体的示例值。很多 Agent 配置完之后不工作是“参数说明太抽象”导致的。你写“城市string”模型还是不知道到底该填拼音还是填中文还是填城市编码你写“城市中文名例如北京”模型的成功率立刻就上来。这就是给模型喂结构化提示的威力它不需要想象只需要匹配。timeout和max_retries是工具执行层的保障。一个外部 API 可能会因为网络波动而卡住如果不设超时Agent 会一直等下去进而拖垮整个执行循环。我的默认经验是普通 HTTP 请求类工具给 8 秒文件读写类工具给 3 秒重试最多一次。不要无限重试像查天气这种事一次失败后第二次再失败说明大概率是服务端问题再试下去只会浪费时间和额度。allow_domains是权限边界。不是所有工具都需要这个字段但如果工具涉及外部网页请求强烈建议把允许访问的域名写清楚。这就像一个白名单防止 Agent 被恶意或意外的内容诱导去访问不应该访问的地址。实际调试中我发现很多工具调用异常是因为模型生成了错误的 URL白名单直接拦截才不至于继续跑偏。工具数量也不是越多越好。每多一个工具模型在决策时就要多考虑一个选项。工具数量膨胀到二三十个时模型经常选择错误率明显上升。最好的做法是只开启当前任务真正需要的工具然后通过 prompt 告诉它优先使用哪些。2.3 system_prompt.md行为规范的载体第三个文件是行为系统的核心我用一个模板说明结构你是 OpenClaw Agent 下的专用助手负责根据用户请求调用工具完成任务。 任务目标 - 理解用户请求选择正确的工具 - 如果请求涉及多个步骤按顺序执行 工作流程 1. 首先检查用户请求中是否有城市、日期等必填参数 2. 缺少参数时不要猜测直接向用户询问 3. 调用 weather_query 获取天气信息 4. 如果返回失败重试一次仍失败就如实告知 5. 调用 write_log 写入查询记录 6. 最终用简洁的中文回复用户不超过 150 字。 输出规范 - 回答使用 Markdown 格式 - 结果必须基于工具返回的真实数据 - 不要编造不存在的天气信息。 禁止事项 - 不要调用 tools.yaml 之外的任何工具 - 不要输出 API 密钥、文件路径等敏感信息。这段提示词看起来内容不多但每个部分都对应一个控制目标。角色设定让模型知道自己是“执行者”不是“讨论者”工作流程把调用顺序写死尤其是“缺少参数时必须询问”这一条能杜绝模型自己脑补城市名就乱调工具的情况。写提示词最容易犯的毛病是使用模糊词汇。比如“请仔细分析后调用合适的工具”这句话模型无法执行。“仔细”“合适”是人的感受不是可操作指令。换成“如果用户未提供城市名则停止调用天气工具并向用户询问城市名”模型就知道具体在什么条件下做什么动作。用“如果……就……”这种确定性句式比任何形容词都管用。system_prompt.md里还应该有一个“结果是否完成”的判断标准。很多 Agent 跑完工具返回了结果却不知道怎么停下来。你在提示词里写清楚“当已经向用户输出最终回答后任务结束不再调用任何工具”可以有效避免多余的工具调用也为stop_condition: task_completed提供判断依据。3. 从零到可运行准备环境、落盘配置、启动验证3.1 环境准备先让运行时本身可运行OpenClaw 的安装方式取决于具体版本我以常见的 Python 生态为例。首先确认本机有 Python 3.10 或更高版本然后创建一个独立的虚拟环境避免依赖冲突python -m venv .venv source .venv/bin/activate pip install openclaw安装完之后跑一下环境自检命令openclaw doctor这个命令会检查三件事Python 版本是否满足要求、配置文件目录是否可写、是否能解析环境变量占位符。如果doctor报错先解决报错项再往继续配置不要带着环境问题去调试 Agent。我用过几个同事的环境很多“工具调用失败”其实根本不是配置问题而是 Python 版本太低或者依赖没有装全doctor一跑就现原形。如果你的部署环境没有外网也可以从内部仓库安装依赖包。不管用哪种方式关键是保证启动命令能找到三个文件。我的习惯是建一个专门的项目目录比如~/agents/weather-agent/把openclaw.yaml、tools.yaml、system_prompt.md都放进去之后所有命令都在这个目录下执行。3.2 完整的三文件配置示例为了让你直接照抄我用一个具体的 demo 串起来做一个“查询天气并写日志的 Agent”。用户问“北京今天天气如何”Agent 调用天气工具拿到结果后写入一个日志文件再用中文回复。第一个文件openclaw.yamlprovider: type: openai-compatible base_url: ${MODEL_BASE_URL} api_key: ${MODEL_API_KEY} model: assistant-x1 temperature: 0 max_tokens: 1024 memory: type: local path: ./memory window: 10 loop: max_iterations: 5 timeout_seconds: 30 stop_condition: task_completed tools: config: ./tools.yaml prompt: file: ./system_prompt.md第二个文件tools.yaml- name: weather_query description: 查询指定城市当天的实时天气返回温度、风向和天气状况。输入需要用中文城市名。 parameters: - name: city type: string required: true description: 城市中文名例如“北京”“上海”“广州” - name: date type: string required: false description: 日期格式 YYYY-MM-DD不填则默认今天 enabled: true timeout: 8 max_retries: 1 allow_domains: - api.weather.example.com - name: write_log description: 把一条文本信息追加写入日志文件用于记录 Agent 的执行结果。 parameters: - name: content type: string required: true description: 要写入文件的完整文本内容必须是一行 - name: file type: string required: false description: 文件名默认是 ./agent.log enabled: true timeout: 3 max_retries: 1第三个文件system_prompt.md你是天气查询助手。 工作目标 - 根据用户提供的城市名查询天气并把结果写入日志。 执行流程 1. 确认用户请求中是否包含城市名 2. 如果没有城市名先询问用户不要猜测 3. 调用 weather_query 查询天气 4. 调用失败时重试一次仍然失败则如实告知 5. 查询成功后调用 write_log 把结果记录到日志文件 6. 最终用简洁的中文回复用户不超过 150 字。 判断任务完成的标准 - 你已经输出最终回答并且日志写入成功任务结束不再调用任何工具。 禁止事项 - 不要使用未注册的工具 - 不要编造天气数据 - 不要输出 API 密钥和文件路径。这套配置里我把temperature设为 0原因前面已经说过让模型严格按流程执行不要自由发挥。max_iterations设为 5对这个任务来说最多就是查询一次、重试一次、写日志一次三到四步已经能完成留一点余量又不会死循环。memory.window设为 10 是因为这个场景没有长期记忆需求只需要记住当前任务上下文。3.3 启动、验证和迭代用命令行启动 Agentopenclaw run --config ./openclaw.yaml启动成功后日志里会出现模型连接成功、工具加载数量、提示词文件加载状态这些信息。如果你看到类似“loaded 2 tools”的日志说明tools.yaml已经成功解析Agent 具备调用这两个工具的权限。然后输入一条测试指令帮我查一下北京今天天气然后记录到日志里。观察输出。一个正常的执行流程应该是Agent 从指令中识别出城市“北京”调用weather_query拿到天气结果后调用write_log最后给你一句简洁回答。如果它直接回答而没有调用任何工具问题大概率出在tools.yaml的工具描述上模型可能没看懂工具有什么用。这里我还要强调一下命令行的变化。不同版本可能提供不同子命令有的版本用openclaw serve启动 API 服务有的版本用openclaw chat进入交互模式。你可以查看当前版本的帮助openclaw --help按理说,用run或者chat只是入口不同配置逻辑完全一致。实际开发中我用chat模式调试单条指令更快用serve模式接入真实业务请求。调试的过程本质上是“改配置—跑测试—看日志—再改配置”的循环。如果 Agent 不按照你的预期调用工具第一时间不要去改代码去改那个最可能影响决策的文件。行为不对改system_prompt.md工具识别不准改tools.yaml模型连接有问题才改openclaw.yaml。这就是三文件分离的主要收益之一。4. 排查问题的实操笔记这些坑我基本都踩过4.1 配置格式类问题占了七成以上的失败现场配置无法启动最常见的三个原因是 YAML 缩进、环境变量未加载、模型名错误。症状可能原因处理方法启动时报 YAML 解析错误使用了 Tab 缩进或引入了中文标点用空格缩进检查冒号、引号是否全角报api_key或base_url为空环境变量未设置或.env文件未加载在 shell 中执行export MODEL_API_KEYxxx再重启请求模型接口时 404base_url路径错误或模型 ID 与实际不符检查模型服务商的接口文档确认 URL 结尾无多余/Agent 能启动但回答质量奇怪system_prompt.md文件名或路径写错打开 debug 日志确认 prompt 加载是否成功我对 YAML 缩进的提醒始终很啰嗦因为它太容易出问题。尤其是从网页或文档里复制配置时编辑器可能会自动把空格替换成 Tab或者把中文引号带进去。解决办法是配置完成后用一个简单的 YAML 解析器验证一下或者在编辑器里开启“显示空格”功能一眼就能看出问题。环境变量这块有个细节容易卡住你明明在.env文件里写了MODEL_API_KEYxxx但 OpenClaw 启动时没加载.env结果照样报空。很多版本默认不会自动读取.env文件要么你在启动命令里引用.env要么直接 export 到当前 shell。我建议尽量用 export 方式启动少一层负担也避免.env文件里的特殊字符被错误解析。4.2 Agent 不调用工具或者调用错了工具这是最让人头痛的一类问题,因为配置语法没错模型也能对话但它就是不按你的预期走。我从日志里总结了几个高频原因。第一个原因是tools.yaml里的description太模糊。模型是基于文本做路由决策的描述越清楚路由准确率越高。比如把“查询天气的工具”改成“查询指定城市当前天气输入城市中文名返回温度和天气状况”模型就不太可能去别的工具里找答案。我见过一个项目里同时有search和query_database两个工具因为描述里都写了“根据条件获取信息”模型经常调混后来把其中一个改成“只能从人才数据库里查询候选人的工作经历”问题立刻消失。第二个原因是system_prompt.md里写了矛盾指令。你在禁止事项里说“不要调用任何未注册工具”但执行流程里又说“如果用户需要更多信息可以调用查询”。模型在矛盾指令前往往会选择自由发挥它可能跳过工具直接给出结果。所以我写提示词时会把流程收窄所有调用指令都指向具体工具名不给模型自己“发现工具”的机会。第三个原因是模型拿到的工具列表其实是过期的。某些运行时有缓存机制你改了tools.yaml以后不重启命令就不会重新加载。如果你改了配置后没有任何效果先重启 Agent再看日志里加载的工具数有没有变化。我在调试时经常先用一个专门列出工具的调试命令确认加载结果再跑实际指令这样能区分是“配置没加载”还是“模型选择错误”。排查这类问题最好的办法是开启详细日志。很多版本支持--verbose或者--trace参数打开后你会看到模型收到了什么工具描述、模型发起了什么 tool call、工具返回了什么结果。一旦看到完整链路问题往往一眼就能定位。这个习惯我建议从第一次调试就开始养成不要等到出了问题才开日志。4.3 性能与成本控制还没上线就已经被 token 烧光了很多人在本地调试时不太在意 token 用量但一旦接入了真实业务成本会迅速超出预期。我总结几条有效的控制手段。第一给上下文窗口设一个明确上限。像memory.window这种参数要根据任务需要来设置而不是一路调大。天气查询这种一次性任务窗口设 10 就够了设到 50 只会白白把历史对话都算进 token。第二把max_iterations收紧。不是所有任务都需要 10 步工具调用大部分任务两三步就能完成设一个过大的循环上限等于允许模型在出错时反复重试每一轮都是 token 消耗。第三能用一次的不要调两次。很多 Agent 流程会在同一轮对话里反复问同样的问题或者重复调用相同的工具这通常是 prompt 里缺少“拿到结果就直接输出”的终止条件导致的加一句“已经用工具获取到数据后直接基于该数据回答”能明显减少多余调用。我还做过一个实验同一个查询任务一个 prompt 写了如果工具返回数据就用工具结果回答不要用其他信息补全另一个 prompt 什么都没写。前者的工具调用次数稳定在两轮后者在数据不完整时还额外调用了一个无用的搜索工具。可见行为规范直接决定成本不只是决定回答质量。4.4 从配置到运维的一些补充建议配置初期我会建议把三个文件的模板放到项目模板仓库里用 CI 或本地脚本校验一次 YAML 格式。这个操作看起来多了一步但对团队的收益很大提交前就能拦住缩进和字段错误避免把坏配置交到别人手里。对于已有的正式环境配置文件不要直接改线上。先用一份openclaw-dev.yaml指向另一个模型或者环境变量本地验证通过后再替换线上配置。实践上很多问题都是因为改配置时顺手动了别的字段比如想调temperature却不小心改了base_url分离出来的开发配置能让你小范围试验风险更低。再补充一个安全习惯定期检查tools.yaml是否包含了超出需要的权限。Agent 的能力边界会随着项目演进而改变不需要的工具就删掉或置为enabled: false不要一直留着。这不仅是安全问题也是性能问题——工具越少模型路由决策越轻快。5. 后续还能往哪个方向扩展三文件配置模式跑通以后你可以在这个基础上做很多扩展。常见的路径是把多个 Agent 共用的工具抽成一个独立的工具服务通过tools.yaml里的地址引用而不是每个 Agent 各写一份工具配置。这样一旦中心服务更新所有相关 Agent 都拿到新能力。另一个方向是完善观测能力。OpenClaw 本身可能有日志输出但生产环境建议把工具调用的关键节点输出成结构化日志比如每次 tool call 的工具名、返回值长度、执行耗时、这轮对话的 token 消耗。有了这些数据你就能做后续的代码review哪个工具经常被调用、哪些工具从未被使用、哪几轮对话的 token 支出特别高从而反向优化 prompt 和工具描述。还有一点消息循环的参数不只是死配置。你可以把max_iterations根据任务类型拆成多份简单查询类任务走小循环深度研究类任务走大循环形式上通过不同openclaw.yaml实现本质上就是用同一套提示词模板和工具集面对不同任务采取不同策略。这个思路一旦建立你会发现单个 Agent 的扩展方式变得非常灵活。在我实际布置过的场景里有一个看起来不复杂但很有效的小技巧在所有 prompt 模板的末尾增加一段“上次执行的问题记录”。把调试中积累的坏案例写成“不要这样做”的规则直接放进 prompt。这样做比你去模型层面调整参数要直接得多因为模型不需要猜测它只需要读到你给的负样本。比如“上一次用户只问今天天气你却把明天也查了今后除非用户明确要求未来日期否则只查今天”这样的句子放进 prompt可以保证同类问题不再复发。这也是三文件架构最出彩的地方行为问题的修复点集中在system_prompt.md不会污染工具配置也不会影响模型连接。长期维护下来你会积累一套针对特定场景有效的行为规则这些规则比任何模型参数调优都更可控、更可解释。我个人对配置这类工作的体会是技术栈不断变化但好的配置结构设计远比单个参数调整重要。三个文件的拆分方式不一定适用于所有 Agent 框架但“连接配置、工具能力、行为规范三者分离”这个原则放在其他 AI Agent 项目里照样成立。结果导向地看一个不依赖复杂框架、能让新人快速上手的配置比一个看起来很重型、功能很全但调不动工具的配置要实用得多。