1. 为什么我盯上了 OpenClaw 的 exec 工具第一次在 OpenClaw 里看到exec这个工具名时我下意识把它当成一个普通的跑命令接口。直到我在一个真实项目里需要让 Agent 自己编译、自己起服务、自己看日志才发现这个工具远不止执行一条 Shell这么简单——它其实是一整套命令执行 进程生命周期管理的运行时。先说清楚它是什么。exec是 OpenClaw 的一级工具first-class tool作用是在 workspace 里执行 Shell 命令并且把执行结果、退出码、标准输出/错误都结构化返回给 Agent。它能做什么简单讲三件事跑一次性命令比如ls、rg、git status、把长任务丢到后台比如npm run build、python train.py、以及通过process工具对后台会话做轮询、写输入、终止。适合谁适合所有想让 AI Agent 真正动手而不是只动嘴的开发者尤其是做自动化脚本、CI 辅助、本地开发助手这类场景的人。我踩过的第一个坑是把exec当成同步阻塞调用。结果一个npm run build卡了 30 分钟Agent 一直在等整个对话都僵住了。后来才明白exec的设计里有一套自动后台机制关键参数就是yieldMs。理解这套机制是把它用好的前提。这篇我会按配置 → 调用 → 验证 → 排障的顺序走一遍并且把 TaoToken 的统一 Key/API 通道接进来让 OpenClaw 的模型调用和工具链走同一条通道省得 Key 到处散落。你跟着做能在本地半小时内跑通一条完整的命令执行 后台进程管理链路。2. TaoToken 统一通道前置准备Key、Base URL 与模型 ID在动exec之前得先把 OpenClaw 的模型通道配好。因为exec本身不依赖模型但 Agent 决定要不要执行命令、执行什么命令是靠模型推理的模型通道不通工具链就是空转。TaoToken 在这里的角色是统一入口一个 Key、一个 Base URL就能覆盖对话模型和后续的 Coding Plan 场景。官网入口是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 地址是 https://taotoken.net/api 这个不加 UTM直接填进配置里。你需要准备三样东西我把它叫三件套项目值说明Base URLhttps://taotoken.net/api所有请求的根地址API Key在控制台生成形如sk-...只显示一次Model ID按控制台列表填例如对话模型或编码模型的具体 ID生成 Key 的路径是控制台里的 API Keys 页面https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。点新建复制出来的字符串务必当场存好页面刷新后就看不到了。这里有个细节很多人忽略OpenClaw 的模型配置和exec的工具配置是分开的两块。模型配置决定谁来思考exec配置决定怎么动手。两者都指向同一个 workspace但配置文件不同。我建议你先用模型对话页面验证 Key 是活的https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 随便发一句你好能正常返回就说明通道没问题。这一步花不了一分钟但能帮你排除掉后面 80% 的到底是 Key 错还是配置错的扯皮。如果你打算长期跑编码类 Agent 任务可以顺带了解 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 它更适合高频、长会话的场景。但今天这篇的重点是exec通道配通就够了。3. 可复制的 exec 配置片段openclaw.json 与 exec-approvals.json现在进入正题。OpenClaw 的exec行为由两个配置文件共同决定主配置openclaw.json里的tools段以及审批配置~/.openclaw/exec-approvals.json。我先把可直接复制的片段给你再逐段解释。先看主配置。假设你的 OpenClaw 配置目录在~/.openclaw/编辑openclaw.json{ tools: { exec: { enabled: true, defaultHost: sandbox, defaultSecurity: allowlist, defaultAsk: on-miss, defaultTimeout: 1800, elevated: { enabled: false } } }, models: { provider: openai-compatible, baseUrl: https://taotoken.net/api, apiKey: sk-你的Key, model: 你的ModelID } }这段里几个关键点defaultHost设成sandbox是最稳的起点命令先在沙箱里跑出问题不会污染真实主机defaultSecurity用allowlist而不是full这是安全底线defaultAsk用on-miss意思是白名单命中就直接跑没命中才问你。elevated.enabled先关着等你有明确需求再开。然后是审批配置~/.openclaw/exec-approvals.json这个文件管的是哪些命令被允许{ version: 1, defaults: { security: allowlist, ask: on-miss, askFallback: deny, autoAllowSkills: false }, agents: { main: { security: allowlist, ask: on-miss, allowlist: [ { pattern: ~/Projects/**/bin/rg, lastUsedAt: 1737150000000, lastResolvedPath: /Users/user/Projects/demo/bin/rg }, { pattern: ~/.local/bin/* }, { pattern: /opt/homebrew/bin/rg } ] } } }白名单用的是大小写不敏感的 glob 匹配。~/Projects/**/bin/rg里的**能跨目录层级适合项目结构比较深的场景~/.local/bin/*只匹配一层适合放自己装的工具。askFallback: deny是个保险丝——如果询问机制本身出问题默认拒绝而不是默认放行。还有一个容易被忽略的机制叫 Safe Bins。OpenClaw 内置了一批只能从 stdin 读数据的安全工具jq、cut、uniq、head、tail、tr、wc。这些工具在 allowlist 模式下不用显式加白名单就能跑因为它们拒绝位置参数形式的文件路径、不做 glob 展开、不支持重定向和管道。换句话说它们没法碰你的文件系统所以被信任。这个设计挺聪明的你可以在白名单里少写一堆条目。配置改完记得重启 OpenClaw 的 gateway 进程否则不生效。我一般用openclaw gateway restart具体命令看你的安装方式。4. 验证请求与成功结果从 ls 到后台进程轮询配置好了来跑通一条完整链路。我会分四步一次性命令、后台命令、process 轮询、TTY 交互。第一步一次性命令。调用exec传一个最简单的{ command: ls -la, timeout: 60 }预期结果是返回当前 workspace 的目录列表包含退出码 0。如果这一步就失败先别往下走去看第 5 节的排障。第二步后台命令。这里有两种写法。立即后台{ command: npm run build:large-project, background: true }或者超时自动后台{ command: python train_model.py, yieldMs: 5000 }yieldMs的含义是命令执行超过 5000 毫秒还没结束就自动转入后台把控制权还给 Agent。这个参数是我最喜欢的设计因为它让短命令同步、长命令异步变成自动的不用你提前判断。第三步用process工具管理后台会话。命令进后台后会拿到一个会话 ID然后你可以{ action: poll, sessionId: 你的会话ID }poll拿最新输出和退出状态log看历史日志支持 offset/limitwrite往运行中的进程写输入kill终止clear清记录remove删会话。这里有个重要提醒process是按 agent 隔离的你只能看到自己 agent 创建的会话别的 agent 的会话对你不可见。我第一次遇到poll 不到会话就是因为在另一个 agent 上下文里查的。第四步TTY 交互。有些命令需要真正的终端环境比如vim、top、mysql客户端。这时候加pty: true{ command: mysql -u root -p mydatabase, pty: true, timeout: 300 }设置后 OpenClaw 会分配一个伪终端交互式命令就能正常工作。但 PTY 模式资源消耗更高非必要别开。成功跑通的标志是ls返回目录列表、后台命令拿到会话 ID、poll能看到输出、kill能干净终止。四步都过说明你的exec链路是通的。5. 本篇常见错排查401、local proxy failed 与 OAuth 报错这一节是我实际踩过的坑按报错原文对照。报错一401 Unauthorized。这个几乎都是 Key 问题。检查三处openclaw.json里的apiKey有没有多余空格、Key 是不是已经过期或被删、Base URL 是不是写成了带路径的https://taotoken.net/api/v1应该只到/api。如果三处都对还是 401去控制台重新生成一个 Key 试。注意 Key 只在生成时显示一次复制时别漏字符。报错二local proxy failed。这个报错通常出现在模型请求阶段不是exec本身的问题。含义是 OpenClaw 尝试走本地代理转发但失败了。排查顺序先确认baseUrl是https://taotoken.net/api而不是localhost或127.0.0.1再确认没有在环境变量里残留HTTP_PROXY/HTTPS_PROXY指向一个不存在的本地端口。我遇到过一次是 shell 里 export 了一个早就关掉的代理变量清掉就好了。报错三reading choices相关错误。这类报错一般是响应体解析失败常见原因是模型 ID 写错了服务端返回的不是标准 chat completion 结构。对照控制台的模型列表把model字段改成完全一致的 ID。大小写、连字符都要对。报错四OAuth 相关报错。如果你用的是需要 OAuth 的客户端比如某些 CLI 工具报错里出现OAuth字样通常是 token 过期或回调地址不匹配。这类场景建议直接用 API Key 模式绕开 OAuth 流程配置更简单。报错五exec返回security denied。这不是 bug是白名单没命中。要么把命令加进allowlist要么把ask改成on-miss让系统问你。别图省事直接改成full那等于关掉安全网。排障时有个通用技巧把exec的command换成echo test跑一次。如果echo能过说明工具链路是通的问题在具体命令或权限如果echo都过不了问题在配置或通道。这个二分法能帮你快速定位。6. 把 exec 接进你的日常工作流跑通之后我建议你做一件事把常用的命令模式固化成几个模板。比如代码搜索用rg -n TODO ~/Projects/myapp配timeout: 60起本地服务用python -m http.server 8080配background: true和yieldMs: 2000数据库交互用pty: true配timeout: 300。模板化之后Agent 调用时你不用每次重新想参数。另外exec和process的组合是 OpenClaw 自动化能力的核心。前者负责发起后者负责照看。很多人的误区是只盯着exec的参数忽略了process的轮询和写入能力。实际上一个能写输入、能看日志、能干净终止的后台会话才是真正可用的自动化单元。如果你还没配 Key从 API Keys 页面开始https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。接入细节看文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。想先验证模型通道用模型对话页面https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。长期跑编码 Agent 的话Coding Plan 更合适https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。最后留一个我自己的习惯每次改完exec-approvals.json先用jq . ~/.openclaw/exec-approvals.json校验一遍 JSON 合法性。这个命令本身就在 Safe Bins 里不用加白名单改完随手跑一下能省掉很多配置没生效的困惑。