1. OpenClaw agent-send 工具是什么CLI 场景下能解决哪些问题OpenClaw 的 agent-send 工具本质上是把「一次完整的代理对话轮次」从聊天窗口里抽出来变成一个可以在终端里直接调用的命令。你可以把它理解成平时你在聊天软件里发一句话、等模型回复现在这一步被搬到了 CLI 里用openclaw agent --message ...就能触发一次代理运行不需要任何入站聊天消息。它适合谁三类人最常用。第一类是写自动化脚本的开发者想把「让代理汇总日志」「让代理生成报告」这类动作塞进 cron 或 CI 流程里第二类是本地调试代理配置的人想绕过网关直接验证模型和提示词是否正常第三类是做多代理编排的人需要按--agent定向到某个已配置代理复用它的 main 会话键。agent-send 的核心行为有几个关键点值得先记住。必需参数只有--message 文本其余都是可选的会话选择方式--to 目标会派生会话键群组/频道目标保持隔离直接聊天归入 main--session-id ID通过 ID 复用已有会话--agent 代理名直接定向到已配置的代理。运行时会走和常规入站回复相同的嵌入式代理运行时--thinking和--verbose标志会持久保存在会话存储里。输出方面默认打印回复文本可能附带MEDIA:行加--json则打印结构化负载和元数据。如果网关无法访问CLI 会自动回退到嵌入式的本地运行这一点对离线调试非常友好。还有一个容易忽略的能力通过--deliver加--channel可以把回复回传到某个频道用--reply-channel、--reply-to、--reply-account可以覆盖交付方式而不改变会话本身。我试过在本地把 agent-send 当成「一次性任务触发器」来用比如每天早上让代理汇总一次收件箱输出直接进 JSON 再喂给下游脚本。整个链路跑通之后你会发现它比想象中更接近一个标准的命令行工具而不是聊天机器人的附属功能。下面从环境准备开始一步步把调用链打通。2. TaoToken 前置准备统一 Key 与 API 通道接入 agent-send在真正跑openclaw agent之前需要先解决鉴权问题。agent-send 在--local模式下运行时需要在 Shell 环境里提供模型提供商的 API 密钥即使走网关网关侧也要有可用的上游通道。这里我用 TaoToken 来统一管理 Key 和 API 通道好处是本地脚本、网关、多个代理可以共用同一套凭证不用在每个地方重复配置。TaoToken 的定位是一个统一的模型 API 接入层官网入口是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 基址是 https://taotoken.net/api 。你需要先在控制台创建一个 API Key然后把它写进环境变量或 OpenClaw 的配置文件里。第一步拿到 Key。打开控制台页面 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 登录后进入 API Keys 管理页 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 新建一个 Key 并复制保存。这个 Key 就是后面所有请求的凭证。第二步确认你要用的模型 ID。agent-send 本身不绑定具体模型模型由 OpenClaw 的代理配置决定。你可以在模型对话页 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite 先试一下目标模型是否可用确认模型 ID 拼写无误再写进配置。第三步把 Base URL、Key、Model ID 三件套准备好。无论你后面用环境变量还是配置文件这三个值都是核心。Base URL 用https://taotoken.net/apiKey 用刚才创建的Model ID 用你在对话页验证过的那个。注意不要把 Key 直接硬编码进会提交到 Git 的脚本里。用环境变量或本地.env文件并在.gitignore里排除。如果你用的是 Claude Code 这类工具做辅助开发接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里面有 Base URL 和鉴权头的完整说明。对于长期跑编码任务或 Agent 编排的场景可以考虑 Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 把额度集中管理避免每个脚本单独配 Key。这一步做完你手里应该有三个确定的值Base URL、API Key、Model ID。接下来把它们落到 OpenClaw 的配置里。3. 可复制配置agent-send 的 settings 与调用参数落地这一节给出可以直接复制的配置片段。OpenClaw 的配置通常分两层一层是模型提供商凭证一层是代理定义。agent-send 在--local模式下读取 Shell 环境变量走网关时读取网关配置。为了两边都能用我建议把凭证放在环境变量里代理定义放在配置文件里。先看环境变量。在你的 Shell 配置文件比如~/.zshrc或~/.bashrc里加入export TAOTOKEN_API_KEYsk-你的Key export TAOTOKEN_BASE_URLhttps://taotoken.net/api export OPENCLAW_MODEL_ID你的模型ID保存后执行source ~/.zshrc让变量生效。可以用echo $TAOTOKEN_API_KEY确认是否读到了。再看 OpenClaw 的代理配置。假设配置文件路径是~/.openclaw/config.json一个最小可用的代理定义如下{ providers: { taotoken: { baseUrl: https://taotoken.net/api, apiKeyEnv: TAOTOKEN_API_KEY, models: { default: 你的模型ID } } }, agents: { ops: { provider: taotoken, model: 你的模型ID, systemPrompt: 你是一个运维助手负责汇总日志并输出结构化结果。 } } }这里apiKeyEnv指向环境变量名而不是直接写 Key这样配置文件可以安全地放进版本控制。agents.ops定义了一个名为ops的代理后面用--agent ops就能定向到它。如果你更习惯 TOML 格式等价的配置如下[providers.taotoken] baseUrl https://taotoken.net/api apiKeyEnv TAOTOKEN_API_KEY [providers.taotoken.models] default 你的模型ID [agents.ops] provider taotoken model 你的模型ID systemPrompt 你是一个运维助手负责汇总日志并输出结构化结果。配置写完后先做一次语法检查。如果是 JSON可以用python -m json.tool ~/.openclaw/config.json验证格式如果是 TOML用python -c import tomllib; tomllib.load(open(config.toml,rb))验证。关于 agent-send 的参数这里列一个常用对照表方便你按场景选参数作用典型场景--message必需输入文本所有调用--to派生会话键按目标隔离会话--session-id复用已有会话连续多轮任务--agent定向到已配置代理多代理编排--local强制本地嵌入式运行离线调试--json输出结构化负载喂给下游脚本--deliver回传到频道结果通知--thinking持久化思考级别GPT-5.2/Codex 模型--verbose持久化详细级别排障--timeout覆盖代理超时长任务配置和参数都准备好之后就可以进入验证环节了。4. 验证请求从单轮调用到成功结果确认验证分三步走先确认环境变量和配置能读到再跑一次最简单的单轮调用最后验证 JSON 输出和会话复用。第一步确认配置加载。执行openclaw agent --agent ops --message ping --json如果配置正确你会看到一段结构化 JSON里面包含回复文本和元数据。如果这一步就报错先跳到第 5 节排查。第二步跑一个真实任务。假设你要让代理汇总日志openclaw agent --agent ops --message 汇总最近100行日志输出异常条目 --json成功的话JSON 里的回复字段会包含代理整理后的异常列表。这里的关键是确认--agent ops确实定向到了你配置的代理而不是默认代理。你可以临时改一下systemPrompt再跑一次看输出风格是否变化以此确认代理定义生效。第三步验证会话复用。先跑一次带--session-id的调用openclaw agent --session-id 1234 --message 记住当前任务编号是 A-001 --json然后再跑一次同 session-id 的调用openclaw agent --session-id 1234 --message 当前任务编号是多少 --json如果代理能答出 A-001说明会话存储正常工作--thinking和--verbose的持久化也是基于同一套机制。第四步验证本地回退。断开网关或临时把网关地址指向一个不可达端口再跑openclaw agent --local --agent ops --message 本地模式测试 --json如果 CLI 自动回退到嵌入式本地运行并返回结果说明--local路径和 Shell 环境变量都配对了。这一步能过说明你的 Key 和 Base URL 在本地也是可用的。第五步验证交付。如果你配了频道可以试openclaw agent --agent ops --message 生成报告 --deliver --reply-channel slack --reply-to #reports成功的话回复会同时出现在终端和 Slack 频道里。注意--reply-channel和--reply-to只覆盖交付方式不改变会话本身。走完这五步agent-send 在本地任务流里就算稳定可用了。接下来把常见报错过一遍避免踩坑。5. 本篇常见错排查401、local proxy failed、reading choices 与 OAuth这一节对照真实报错来排。agent-send 的报错大多集中在鉴权、网络和配置解析三类。401 Unauthorized。最常见的原因是 Key 没读到或写错了。先确认echo $TAOTOKEN_API_KEY有值再确认配置文件里的apiKeyEnv拼写和实际环境变量名一致。如果 Key 是从控制台复制的注意有没有多余空格或换行。还有一种情况是 Key 被禁用或额度耗尽去控制台 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 检查状态。local proxy failed。这个报错通常出现在--local模式下CLI 尝试直连上游但网络不通。先确认 Base URL 是https://taotoken.net/api没有多余路径。再确认本机 DNS 和出网正常可以用curl -I https://taotoken.net/api测一下连通性。如果公司网络有出口限制联系网络管理员放行不要尝试任何非正规的网络绕过手段。reading choices 相关报错。这类报错一般是响应结构不符合预期常见原因是模型 ID 写错或者上游返回了非标准格式。先确认 Model ID 和你在模型对话页 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite 验证过的一致。如果 Model ID 正确检查配置文件里models.default和agents.ops.model是否指向同一个值两处不一致会导致路由混乱。OAuth 相关报错。如果你用的是需要 OAuth 的客户端比如某些 Claude Code 接入场景报错通常和 token 过期或回调地址不匹配有关。接入文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里有完整的鉴权流程说明。对于 Claude Code 场景参考 https://taotoken.net/claude-code-anthropic?utm_sourcetaotoken_aicg_blog_endutm_contentclaude_codeutm_campaignrewrite 的配置方式确认 Base URL、Key、Model ID 三件套都填对。配置解析失败。JSON 里多一个逗号、TOML 里少一个引号都会导致加载失败。用前面给的语法检查命令先验证格式。另外注意配置文件路径OpenClaw 默认读~/.openclaw/config.json如果你放在别处需要用环境变量或启动参数指定。会话复用不生效。如果--session-id两次调用拿不到上下文检查两次调用是否真的用了同一个 ID以及会话存储目录是否有写权限。--thinking和--verbose的持久化依赖会话存储存储不可写时这些标志会静默失效。排障的核心思路是先确认三件套Base URL、Key、Model ID再确认配置格式最后确认网络连通性。大部分报错都能在这三层里定位到。6. 把 agent-send 接进你的任务流从验证到长期使用验证通过之后agent-send 可以接进各种自动化场景。最简单的做法是写一个 Shell 脚本把openclaw agent --json的输出用jq解析再决定下一步动作。比如每天定时汇总日志、异常时触发告警、批量生成报告。如果你要跑长期编码任务或多代理编排建议把 Key 和额度集中管理。Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 适合这种场景避免每个脚本单独配 Key 导致管理混乱。API Keys 页面 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 可以随时轮换和吊销凭证。一个实用技巧把常用的 agent-send 调用封装成函数放在 Shell 配置里。比如oc-ops() { openclaw agent --agent ops --message $1 --json | jq -r .reply }这样你只需要oc-ops 汇总日志就能拿到纯文本回复方便管道传递。另一个技巧是利用--deliver做结果通知。长任务跑完后让代理把结果直接推到 Slack 或 Telegram你就不用盯着终端了。注意--reply-channel和--reply-to只影响交付不影响会话所以可以放心地在不同任务里复用同一个 session-id。最后提醒一点agent-send 的--local模式依赖 Shell 环境变量如果你在 cron 里跑记得在 crontab 里显式导出这些变量或者用env命令带上。cron 的环境和交互式 Shell 不一样这是很多人第一次接自动化时会踩的坑。