做 Agent 类项目最怕的不是模型不行而是配置在你面前铺了一堆你根本不知道要改哪行。OpenClaw 的文档结构其实挺清晰但最容易被人跳过的附录C反而成了我折腾一圈下来最值钱的一段它把配置模板和自定义参考揉在一起等于把整套系统的可见面都摊给你看了。我第一次跑 OpenClaw 是在 Windows 上装完依赖启动时报了一句让我印象深刻的话OpenClaw 无法安全验证 WSL 环境请在 PowerShell 中运行 wsl -- status 检查后再启动。后来才发现这不是代码坏掉也不是我电脑有问题而是我在配置阶段少做了一步环境确认。要解决报告里的问题靠的从来不是反复重装而是把配置文件一行一行读懂。这篇我按自己的实操顺序来写先讲附录C在设计上到底解决什么问题再讲配置模板怎么拆然后讲模型接入云端 API 和本地 Ollama怎么选接着讲技能自定义与安全权限最后把 Windows 上的 WSL 和移动端 Termux 这两类容易踩坑的场景单独拿出来说。适合两类人第一类是第一次部署 OpenClaw想知道哪些字段不能乱删的新手第二类是已经跑起来想把自己的需求加进去、又不想让 Agent 乱拿权限的老手。我会尽量把每一步背后的原因也讲清楚这样你改配置的时候心里有底。1. 附录C到底解决什么问题别再盲改 YAML 了1.1 配置不是越多越好而是越准越好第一次打开 OpenClaw 的配置文件我的第一反应是“这也太长了”。一个 Agent 系统的配置段可以横跨模型提供商、模型名称、温度、最大 token、技能目录、数据目录、服务端口、权限策略甚至还有 Windows 上特有的 WSL 检查项。如果你把这些全部堆在同一个文件里不是说不能运行而是你根本分不清哪一行是必须保留的、哪一行会在几天后反过来坑你。附录C 给我最大的价值不是让我背下每个字段而是让我看懂了一个最小可运行配置应该长成什么样只有四个核心部分——模型、技能、权限、服务入口。其他字段基本都是围绕这四个部分打转的可选项。想明白这一点后我就不再追求全量配置了而是把当前用不到的段落直接删掉配置反而比以前更稳定。1.2 Template、Reference、Example一个文本的三层结构我习惯把附录C拆成三层看。第一层叫 Template是官方给的骨架告诉你一个最普通的系统应该有哪些配置节点第二层叫 Reference是字段字典负责解释每个 key 的含义、可取值和默认行为第三层是 Example是具体的组合示例比如本地 Ollama 怎么配、云端 API 怎么配、Windows 下启用 Companion 需要什么、安卓 Termux 精简版又该长什么样。这三层的关系很像一棵树Template 是树干Reference 是树皮上的细节纹理Example 是已经长好的树枝。你不需要把每一行都背下来但至少要知道想实现某个效果时该去哪一层里翻。我的经验做法是先打开 Template 复制一份然后用 Reference 查你想动的字段最后找一个最接近你使用场景的 Example 对照调参。这样比每次从零开始敲配置高效得多也比你对着网上零散帖子东拼西凑要安全。2. 配置模板逐字段拆解最小可运行的骨架我直接画给你2.1 一份可启动的 openclaw.yaml 长什么样下面这份配置是我按常见官方文档结构整理出来的最小模板具体字段名以你安装的版本为准但整体骨架基本一致。你可以直接另存为openclaw.yaml把data_dir换成你自己的目录配好模型密钥启动大概率就能跑起来。# openclaw.yaml —— 最小可运行配置 agent: name: my-openclaw persona: assistant data_dir: ~/.openclaw llm: provider: anthropic model: claude-sonnet-4 temperature: 0.3 max_tokens: 8192 api_key_env: ANTHROPIC_API_KEY server: host: 127.0.0.1 port: 8787 skills: dirs: - ~/.openclaw/skills enabled: - file_ops - terminal我把这份配置叫作“启动底线”意思是它只回答了三个问题模型是谁、技能放哪里、服务端口是多少。你没看错这里甚至没有明确写安全策略因为安全策略的默认行为就是不开权限在初期调试阶段反而最安全。跑通后再按需要把权限一点点放开。2.2 五个关键节点每个都是干什么的如果你打开一个真实的 OpenClaw 配置文件会发现节点比我上面那份多不少但万变不离其宗。我用一张表把最核心的配置段列出来这样你以后看到不认识的字段至少知道它属于哪个大块。配置块关键字段作用我的建议agentname、persona、data_dir定义 Agent 身份与数据落盘位置name 不要用中文和特殊字符避免路径问题llmprovider、model、api_key_env决定模型来源和生成参数temperature 控制在 0.2~0.4skillsdirs、enabled、disabled控制技能扫描目录和启用名单目录层级不要超过两层serverhost、port暴露本地服务端口默认 127.0.0.1别改成 0.0.0.0securityallowed_paths、allowed_commands限制 Agent 能碰的路径和命令先开 dry_run确认无误再放开模板把 agent 放在最上面是因为它定义了整个系统的身份。persona 字段看起来无害但它会持续影响 Agent 的回复风格和决策倾向。我见过有人把 persona 写成“你是一个无所不能的黑客”结果 Agent 总是尝试一些明显不该做的系统操作。persona 不是装饰它是模型行为约束的一部分。2.3 密钥别写进 YAML环境变量的正确姿势新手最容易犯的一个错误是把 API key 直接填在配置文件里llm: provider: openai api_key: sk-xxxxxxxxxxxxxx当时是能跑但后面你会被自己坑死配置文件一旦提交到 Git、分享到群聊、备份到云盘密钥就等于裸奔了。附录C 给的做法是让配置引用环境变量的名字比如api_key_env: OPENAI_API_KEY真正的密钥放到启动进程的环境变量里让配置文件里只留一个变量名。在 Windows PowerShell 里可以这样设置$env:OPENAI_API_KEY sk-xxxxxxxxxxxxxx在 macOS 或 Linux 里可以写入~/.bashrcexport OPENAI_API_KEYsk-xxxxxxxxxxxxxx如果使用.env文件记得把它加入.gitignore。踩过坑的人都知道模型返回 401 时不一定是模型问题有时只是环境变量没有成功加载你在终端里 echo 一下变量名就能确认。不要把密钥保存到配置里这不是偏执这是行业基本素养。3. 模型接入实战云端 API 和本地 Ollama 的切换全流程3.1 云端 API三行配置把大模型接进来很多人问“OpenClaw 是不是只能用接入 API 的方式使用算力”我的答案是不是但 API 方式是最省心的。如果你已经有 OpenAI 或 Anthropic 的 key把 LLM 段落换成这样的结构即可llm: provider: openai model: gpt-4o-mini api_key_env: OPENAI_API_KEY temperature: 0.3 max_tokens: 8192这里三个参数值得认真对待。temperature是采样随机性太高的温度会让 Agent 在一次文件操作任务里突然“发挥创意”把命令参数改得乱七八糟Agent 类任务建议压在 0.2 到 0.4 之间。max_tokens决定单次响应上限像查资料、写短文这种任务 4096 够用但涉及长文本分析或批量修改文件时8192 会更从容。model的选择不用盲目追新普通日常任务用中端型号就够把高端模型留给真正复杂的推理环节能省不少钱。3.2 本地模型把 Ollama 配置成后端本地模型不是塞进同一个文件的隐藏开关而是把 OpenClaw 的模型提供方换成本地服务。以 Ollama 为例安装完成后两步走先启动服务再拉模型。ollama serve ollama pull qwen2.5:14b启动后OpenClaw 的配置这样写llm: provider: ollama model: qwen2.5:14b base_url: http://127.0.0.1:11434 api_key: unused options: keep_alive: 30sapi_key: unused是因为本地 Ollama 默认不做鉴权但有些版本的客户端要求这个字段不能为空所以填一个任意字符串占位。keep_alive是模型在内存里停留的时间如果你的机器内存不大可以把数值调小让空闲模型尽快被释放避免长期占用几个 GB 内存。base_url默认端口就是 Ollama 的 11434除非你改过端口否则不用动。3.3 算力选择决策表别让 API 白烧钱也别让本机跑崩云端 API 和本地模型不是二选一的关系而是不同使用场景下的互补选项。我在实际项目里一般按下面这张表来决策使用场景推荐方式原因原型验证、功能演示云端 API快零环境依赖问题都出在模型外的概率低内网离线环境本地小型模型数据不出网安全可控长文本、复杂推理云端大型模型本地小模型在质量和稳定性上确实有差距低成本批量任务本地量化模型单条成本趋近于零算力要求可控手机或低配电脑云端 API本地模型很容易把设备拖到卡死顺带说一句本机跑 7B 模型不需要顶级显卡但 14B 以上建议至少 16GB 内存量化版本可以适当放宽。内存不够时优先选 Q4_K_M 这类量化格式不要一味追求原版权重。我在一台 8GB 内存的机器上跑过 qwen2.5:14b能启动但每次对话开始前的加载时间都很感人实际用下来效率还不如 API。4. 自定义技能与权限让 OpenClaw 按你的规则干活4.1 Skill 的本质是一个目录不是一个开关OpenClaw 把一次任务里的原子能力叫 skill。你在配置里写enabled: [file_ops, terminal]只是打开了系统自带的两个技能真正的自定义是把自己写的新能力包装成一个目录放进技能扫描路径让 Agent 在运行时能发现它。为什么要用目录而不是一个简单的函数因为一个技能需要三种信息声明这个技能叫什么、说明什么时候该用、怎么用、实现实际执行代码。模型不靠硬编码识别你的技能它靠阅读说明来决定是否调用。你把目录组织得越清晰模型决策的准确率就越高。目录结构不需要复杂但一定要稳定我见过有人把技能脚本动不动就改位置结果 Agent 前一天还能调用后一天就频繁报“技能不存在”。4.2 用 SKILL.md 写一个最小自定义技能一个常见的技能目录长这样比如我在.openclaw/skills下建一个daily_report的文件夹~/.openclaw/skills/ daily_report/ SKILL.md run.pySKILL.md是给模型看的说明书里面的 front matter 会被解析成结构化字段--- name: daily_report description: 汇总当天工作日志并生成简报 arguments: - name: output_dir type: string required: true description: 输出目录路径 scripts: - run.py --- # 使用说明 当用户要求生成日报、工作简报或当日总结时使用该技能。 脚本会读取用户的配置目录并生成 Markdown 文件。 输出文件必须保存在 arguments.output_dir 参数指定的目录中。这段描述里的“什么时候使用”非常关键。模型不会因为你写了个脚本就自动理解它的用途它要通过这段说明来猜测触发条件。description 写得越具体误调用率就越低。后面的run.py就按普通 Python 脚本写接收参数之后完成实际工作即可。你不需要把技能脚本做成服务OpenClaw 会在需要时按声明的方式调用它。4.3 权限控制先限定路径再限定命令很多刚上手的人有一个误解Agent 有了技能是不是就可以随便操作文件了默认不是。OpenClaw 的安全策略需要你主动配置否则很多敏感操作会被拦下来。下面是适合初期调试的权限模板security: allowed_paths: - /workspace/web - /workspace/data allowed_commands: - ls - cat - grep - python3 confirm_commands: - rm - curl dry_run: trueallowed_paths限定 Agent 默认能读写的目录allowed_commands限定它能在 shell 里执行的命令confirm_commands列出的命令每次执行前都需要人工确认。dry_run: true是调试阶段的保命符Agent 会把计划执行的命令打出来但不会真正执行。我踩过最大的坑就是把rm放进了allowed_commands结果某次 Agent 在处理文件时给了我一串误删操作幸好当时有备份。现在我的原则是不放rm必须删除的时候让它把文件移动到.trash目录人工确认后再清空。把选择权留给日志和人工而不是交给模型临场发挥。5. Windows 部署实录WSL 验证与 Windows Companion 配置5.1 为什么 OpenClaw 要验证 WSL 环境Windows 上部署 OpenClaw最经典的开局是七行字“OpenClaw 无法安全验证 WSL 环境。请在 PowerShell 中运行 wsl -- status 检查后再启动。”这句话背后是 OpenClaw 在启动时会尝试确认自己的命令执行沙箱是不是可用。它翻译成人话就是如果你连 WSL 都跑不起来后面所有 shell 操作、文件处理、子任务都会在一个不稳定的底座上执行与其给你一个随时崩的环境不如提前拦住你。所以不要想着通过修改配置直接跳过检查而是应该把 WSL 环境修到能稳定运行。你可以把 WSL 理解为 Windows 里的一个轻量 Linux 环境OpenClaw 的很多命令默认是在这个环境里执行的。Windows 本体也能跑命令但 WSL 提供的文件权限模型和 shell 行为和 Linux 服务器更一致不容易出现路径兼容问题。5.2 用 PowerShell 把 WSL 环境一步步修好如果你在 PowerShell 里运行wsl -- status发现环境有问题按下面这套顺序处理基本能解决 80% 的启动失败# 1. 看当前 WSL 状态 wsl --status # 2. 看已安装发行版和对应版本 wsl --list --verbose # 3. 如果还没有发行版直接装一个 Ubuntu wsl --install -d Ubuntu-22.04 # 4. 把 WSL2 设为默认版本 wsl --set-default-version 2 # 5. 重启终端进入发行版完成用户名和密码设置 wsl -d Ubuntu-22.04装完 Ubuntu 后我建议先手动wsl -d Ubuntu-22.04进去跑一遍ls和python3 --version确认环境真的能用。很多人忽略这一步结果 OpenClaw 启动时调用 WSL 内部命令失败报错信息还是那串“无法安全验证 WSL 环境”。另外如果你的电脑之前装过 WSL1 或者老版本内核建议先更新到最新版本因为它们的安全模型和文件性能都不太能满足 Agent 场景。检查完 WSL 后再确认 OpenClaw 配置里是否允许使用 WSL 沙箱如果配置了sandbox.wsl.enabled: false那你就算把 WSL 修好了它也不会用。5.3 Windows Companion 配置思路Windows Companion 是我后来才搞明白的一个组件它是 OpenClaw 用来和 Windows 原生能力对接的桥目标是在 WSL 的 Linux 环境和 Windows 桌面之间搭一条通路。它的作用不是让你少装 WSL而是让 Agent 在需要时可以调用 Windows 端的应用操作或系统信息比如读取 Windows 注册表、操作桌面文件、查 Windows 进程。Companion 的配置没有太多花样核心是两边要对上同一个 token保证只有你启动的 OpenClaw 实例能连接companion: enabled: true transport: named_pipe pipe_name: openclaw-companion token: 启动时生成的密钥 windows_automation: falsewindows_automation: false默认是关闭的这是我很欣赏的一点。打开这个开关等于允许 Agent 自动操作 Windows 桌面风险等级很高。我的建议是一开始保持关闭先用文件级任务跑一遍确认日志里所有调用都可控之后再在测试环境里开着它跑一天。你想把桌面自动化权限交给一个可能误判上下文的模型听起来就很不稳。6. 高频报错排查与现场笔记我踩过的坑都在这里6.1 先上速查表症状对着抄报错这东西百分之八十的场景其实是重复的。我把自己遇到和被问过最多的几个问题整理成表你可以直接拿来对照症状常见原因解决思路OpenClaw 无法安全验证 WSL 环境WSL 未安装、版本过旧、无默认发行版查看 wsl --status按 5.2 的步骤修复模型返回 401API key 没加载或已过期检查环境变量是否生效确认 key 是否有效Ollama 连接失败ollama serve 未启动或端口被占用确认 base_url 端口重启 Ollama服务端口被占用8787 被其他程序占用改配置里的 port或用随机高位端口Termux 启动报错Node 未安装或路径不正确用 pkg 安装新版 nodejs检查配置文件路径内存占用暴涨本地模型过大或 keep_alive 过长换小参数量模型调低 keep_alive这几个问题都不是大改最耗时间的反而是排查方向不对。比如 401很多人第一反应是检查模型名称或换 provider结果所有都试一遍才发现是环境变量没刷新。先看日志再动配置几秒钟就能定位的问题不要花半小时去猜。6.2 三个容易被忽略的配置级问题第一个是字段大小写陷阱。配置里api_key_env和API_KEY不是同一个东西有的版本把字段叫api_key_env有的写法不规范就会漏掉_env后缀。配置写错了不一定报错常见表现是模型一直返回 401 或者连接被拒绝。遇到这类情况用 OpenClaw 自带的配置检查命令输出一下解析后的实际值比逐行肉眼看快得多。第二个是data_dir放在云同步目录。有个朋友把 OpenClaw 数据目录放在 OneDrive 文件夹结果 Agent 高频读写文件时频繁出现文件占用冲突日志里全是随机错误。Agent 工具会大量读写状态文件和临时文件这类数据应该放在本地磁盘别让云盘参与实时同步。模拟一下你的 Agent 每秒钟可能写好几个小文件云盘同步的速度跟不上就会出现各种莫名其妙的锁冲突。第三个是技能目录嵌套太深。OpenClaw 的技能扫描通常只处理第一层目录你把技能脚本放在三层子目录里Agent 就找不到。保持skills/技能名/SKILL.md这层结构脚本实现可以放子目录但声明文件必须在第一层。6.3 排查心法先把日志打开别盲猜调试 OpenClaw 最有效的动作不是改配置而是把日志级别调到 debug。启动时加上环境变量OPENCLAW_LOG_LEVELdebug npx openclaw你就会看到 Agent 每一步在想什么、调用哪个技能、执行哪条命令、读到什么返回结果。这比前端界面里的状态好看也比看终端错误信息有用十倍。我在排查一次技能调用失败时就是靠 debug 日志发现 Agent 压根没打算调用我写的技能而是试图用内置的终端命令去做最后通过改技能描述解决了问题。所以说日志不是一个辅助工具它应该是排障的第一站。7. 安卓与 Termux 部署能跑通但请降低期待7.1 为什么很多人想在手机上跑 OpenClaw搜索“OpenClaw 安卓部署”“Termux 安装手机版”的人大概率是想要一个随时挂在后台的 Agent或者想拿旧手机当简易服务器。这个方向不是不行只是很多人一开始没意识到手机不是服务器Termux 也不是完整发行版。它能装 Node、Python也能跑轻量 Ollama但内存上限、系统权限和散热会一直限制你。我自己的判断是Termux 适合用来实验、学习、跑轻量定时任务不适合当生产级服务。它最大的优势是方便最大的缺点是稳定性和权限都差一截。如果你只是想在通勤路上让 Agent 帮你整理几个文件完全够用如果你打算让它长期处理批量任务很快就得面对后台进程被系统清掉的现实。7.2 Termux 里的安装步骤在 Termux 里安装的基础流程不复杂先把依赖补齐再拉代码最后用配置指定数据目录pkg update pkg upgrade pkg install nodejs git python wget git clone OpenClaw 仓库地址 cd OpenClaw npm install export OPENCLAW_DATA_DIR/sdcard/openclaw_data npx openclaw --config termux-config.yaml这里我要重点说两个细节。第一Termux 不能直接访问手机内部存储的任意位置但通过/sdcard路径可以把数据保存到外部存储避免 Termux 应用被清理时数据跟着消失。不要把数据目录放在默认的/data下那个目录在应用被系统清理时很可能直接清空。第二Termux 默认没有 root 权限也别想着靠 root 来解决所有问题在 Android 上做越权会导致安全性崩坏而且 OpenClaw 很多命令在 root 权限下反而容易出现路径判断混乱。手机越狱式的操作老实讲弊大于利。7.3 手机上模型怎么选如果你在手机上坚持用本地模型Ollama 是可以跑的但效果要打几个折扣。我试过在 8GB 内存的 Android 设备上加载 7B 量化模型能跑但生成速度明显慢发热也非常快。更实际的选择是日常任务继续用云端 API本地模型只在断网环境下作为兜底。这样配置里其实只改两个地方一个是provider: ollama一个是model: qwen2.5:3b-instruct-q4_K_M。别把手机上的模型和正式业务混在一起它更适合做功能验证。最后再分享一个小技巧也是我个人折腾完这么多环境后最大的一个体会别把附录C当说明书把它当一份选择题。配置模板里每一个字段都是一道题选项不是“保留”和“删除”而是“在这个环境里它是否必要”。我见过太多人为了让 YAML 看起来完整把用不到的系统配置全留着结果换一台机器迁移时照样报一堆错。反而是最简单的一份配置一路跑得最久。如果你现在正准备部署 OpenClaw我建议先只改四个地方模型、模型密钥、技能目录、数据目录。跑通之后想加什么再回来翻附录C的 Reference动手前先问自己一句不加它系统还跑不跑如果还能跑那就说明现在不是加它的时候。