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_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，API 基址是 https://taotoken.net/api 。你需要先在控制台创建一个 API Key，然后把它写进环境变量或 OpenClaw 的配置文件里。
第一步，拿到 Key。打开控制台页面 https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_content=console&utm_campaign=rewrite ，登录后进入 API Keys 管理页 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite ，新建一个 Key 并复制保存。这个 Key 就是后面所有请求的凭证。
第二步，确认你要用的模型 ID。agent-send 本身不绑定具体模型，模型由 OpenClaw 的代理配置决定。你可以在模型对话页 https://taotoken.net/chat?utm_source=taotoken_aicg_blog_end&utm_content=model_chat&utm_campaign=rewrite 先试一下目标模型是否可用，确认模型 ID 拼写无误，再写进配置。
第三步，把 Base URL、Key、Model ID 三件套准备好。无论你后面用环境变量还是配置文件，这三个值都是核心。Base URL 用https://taotoken.net/api，Key 用刚才创建的，Model ID 用你在对话页验证过的那个。
注意：不要把 Key 直接硬编码进会提交到 Git 的脚本里。用环境变量或本地
.env文件，并在.gitignore里排除。
如果你用的是 Claude Code 这类工具做辅助开发，接入文档在 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite ，里面有 Base URL 和鉴权头的完整说明。对于长期跑编码任务或 Agent 编排的场景，可以考虑 Coding Plan https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding_plan&utm_campaign=rewrite ，把额度集中管理，避免每个脚本单独配 Key。
这一步做完，你手里应该有三个确定的值：Base URL、API Key、Model ID。接下来把它们落到 OpenClaw 的配置里。
3. 可复制配置：agent-send 的 settings 与调用参数落地
这一节给出可以直接复制的配置片段。OpenClaw 的配置通常分两层：一层是模型提供商凭证，一层是代理定义。agent-send 在--local模式下读取 Shell 环境变量，走网关时读取网关配置。为了两边都能用，我建议把凭证放在环境变量里，代理定义放在配置文件里。
先看环境变量。在你的 Shell 配置文件（比如~/.zshrc或~/.bashrc）里加入：
export TAOTOKEN_API_KEY="sk-你的Key" export TAOTOKEN_BASE_URL="https://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_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite 检查状态。
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_source=taotoken_aicg_blog_end&utm_content=model_chat&utm_campaign=rewrite 验证过的一致。如果 Model ID 正确，检查配置文件里models.default和agents.ops.model是否指向同一个值，两处不一致会导致路由混乱。
OAuth 相关报错。如果你用的是需要 OAuth 的客户端（比如某些 Claude Code 接入场景），报错通常和 token 过期或回调地址不匹配有关。接入文档 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite 里有完整的鉴权流程说明。对于 Claude Code 场景，参考 https://taotoken.net/claude-code-anthropic?utm_source=taotoken_aicg_blog_end&utm_content=claude_code&utm_campaign=rewrite 的配置方式，确认 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_source=taotoken_aicg_blog_end&utm_content=coding_plan&utm_campaign=rewrite 适合这种场景，避免每个脚本单独配 Key 导致管理混乱。API Keys 页面 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite 可以随时轮换和吊销凭证。
一个实用技巧：把常用的 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 不一样，这是很多人第一次接自动化时会踩的坑。
