
OpenClaw llm-task 插件JSON-only 结构化 LLM 任务工具完整指南【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 项目地址: https://gitcode.com/GitHub_Trending/cl/openclawllm-task是 OpenClaw 内置bundled的可选插件工具它发起一次纯粹的 JSON-only LLM 推理调用返回结构化 JSON并可选地按 JSON Schema 校验结果。本指南围绕 docs/plugins/reference/llm-task.md 的参考定义展开覆盖启用方式、配置项、工具参数与输出契约并结合 extensions/llm-task 目录下的插件源码与测试用例深入解析其内部实现原理。读完本文你将能够在 OpenClaw 中启用 llm-task把它接入 Lobster 等工作流引擎并为草稿生成、摘要、分类等结构化任务编写可靠的、带 Schema 强校验的 LLM 步骤而无需为每个工作流编写自定义 OpenClaw 代码。插件是什么llm-task 是一个Generic JSON-only LLM tool for structured tasks callable from workflows面向结构化任务、可由工作流调用的通用 JSON-only LLM 工具。它的核心定位是JSON-only模型被明确指令“只输出一个合法的 JSON 值”不输出 Markdown 代码围栏code fences不附带任何评论Schema 校验调用方可传入 JSON Schema输出在返回前会被强制校验不匹配即报错零工具面本次运行不向模型暴露任何工具避免结构化任务被“带偏”成一次普通的、可调用工具的 Agent 回合隔离运行每次调用都是一次全新的、仅 prompt 的推理操作不复用调用方 Agent 的对话记录或原生运行时会话。这一设计使它特别适合被 Lobster 等工作流引擎通过openclaw.invoke --each等方式批量调用从而在不新增 OpenClaw 代码的前提下为工作流注入“起草、总结、分类”等 LLM 能力。发行与分发方式项目值包名openclaw/llm-task安装途径随 OpenClaw 内置included in OpenClaw契约Contractstools注册工具llm-task激活方式activation.onStartup true见 openclaw.plugin.json插件的元数据定义在 openclaw.plugin.json 中configSchema声明了defaultProvider、defaultModel、defaultAuthProfileId、maxTokens、timeoutMs五个配置键均为可选maxTokens/timeoutMs要求最小值为 1toolMetadata[llm-task][optional]标记该工具为可选工具因此默认不会出现在 Agent 的工具集中必须显式启用并加入白名单。需要注意的是README.md 明确说明该扩展依赖 OpenClaw 内部模块内嵌 Agent runner设计为随 OpenClaw 一起内置分发类似lobster插件当前不支持被复制到~/.openclaw/extensions作为独立插件目录使用。启用插件并放行工具由于工具以optional: true注册启用分为两步先启用插件条目再通过工具白名单放行。第一步启用插件在配置的plugins.entries中加入llm-task{ plugins: { entries: { llm-task: { enabled: true } } } }第二步放行工具{ agents: { list: [ { id: main, tools: { allow: [llm-task] } } ] } }README.md 与 docs/tools/llm-task.md 同时提供了另一种推荐写法tools.alsoAllow{ tools: { alsoAllow: [llm-task] } }alsoAllow是在当前活跃工具配置tool profile之上追加该工具不会限制其他核心工具tools.allow则属于严格白名单模式只有列出名称的工具可用。若你的 Agent 配置启用了工具 profile 管理建议优先使用alsoAllow避免误伤其他工具。可选配置项详解启用后可以进一步配置默认值所有config键均为可选作为工具调用省略对应参数时的选择默认值{ plugins: { entries: { llm-task: { enabled: true, llm: { allowModelOverride: true, allowedCompletionModels: [openai/gpt-5.6-sol], allowAuthProfileOverride: true }, config: { defaultProvider: openai, defaultModel: gpt-5.6-sol, defaultAuthProfileId: main, maxTokens: 800, timeoutMs: 30000 } } } } }llm块宿主持有的授权策略llm块属于宿主导管host-owned的模型/凭据策略与插件自身的config语义不同allowModelOverride允许本次调用覆盖模型。开启后工具调用中的provider/model参数才能生效allowedCompletionModels限制每一次补全completion。注意它同样约束“解析后的 Agent 默认模型”因此该列表除了覆盖目标外还应当包含解析后的 Agent 默认模型否则连默认模型的调用也会被拒绝allowAuthProfileId授权defaultAuthProfileId以及每次调用传入的authProfileId参数。从 src/llm-task-tool.ts 的实现看模型解析遵循严格的优先级调用参数provider/model→ 插件config.defaultProvider/defaultModel→ Agent 默认模型api.config.agents.defaults.model的primary。解析过程还会通过buildModelAliasIndex与resolveModelRefFromString识别配置中定义的模型别名并在显式 provider 之前先解析别名目标对应测试见 llm-task-tool.test.ts 中 “resolves configured model aliases before applying an explicit provider” 与 “before dispatching isolated completion” 两个用例。若最终无法解析出provider/model工具会抛出provider/model could not be resolved错误。config块选择默认值配置键类型说明defaultProviderstring默认提供商如openai、anthropicdefaultModelstring默认模型 IDdefaultAuthProfileIdstring默认认证凭据 profilemaxTokensinteger ≥ 1输出 token 上限尽力而为timeoutMsinteger ≥ 1运行超时默认30000毫秒configSchema在 openclaw.plugin.json 中声明为additionalProperties: false未知键会被拒绝。旧版本迁移openclaw doctor --fix由旧版本创建的 llm-task 条目需要运行一次迁移openclaw doctor --fixDoctor 会自动完成两件事实现见 doctor-contract-api.ts测试见 doctor-contract-api.test.ts授予随包分发的模型/profile 选择权限为缺失的llm.allowModelOverride、llm.allowAuthProfileOverride补上true把遗留的config.allowedModels迁移到llm.allowedCompletionModels且不会放大权限只有符合provider/model字面量格式的条目会被保留preserveLiteralLegacyModelRefs会过滤掉带空白、通配符*或无法解析的引用已存在的llm.allowedCompletionModels保持权威。工具参数与输出契约参数表参数类型说明promptstring必填交给 LLM 的任务指令为空会抛prompt requiredinputany可选输入载荷JSON 序列化后追加到 prompt 中schemaobject可选输出必须通过的 JSON Schemaproviderstring可选覆盖defaultProvider或 Agent 默认提供商modelstring可选覆盖defaultModel接受裸模型 ID、别名或provider/model引用重复的 provider 前缀会被自动剥离thinkingstring可选推理级别如low、medium必须是被解析模型支持的值authProfileIdstring可选覆盖defaultAuthProfileIdtemperaturenumber可选采样温度尽力而为部分提供商不遵守maxTokensnumber可选输出 token 上限尽力而为timeoutMsnumber可选运行超时默认30000参数定义位于 src/llm-task-tool.ts 的llmTaskToolDefinition第 101–124 行类型校验依赖openclaw/plugin-sdk提供的optionalFiniteNumberSchematemperature、optionalPositiveIntegerSchemamaxTokens、timeoutMs。测试确认temperature必须是有限数、maxTokens/timeoutMs必须是正整数非法值如NaN、0、4096.5会在分发前被拒绝rejects malformed numeric run options before dispatch 用例同时数字字符串如0.2、512会被规范化后正常使用。输出结构调用成功返回{ content: [{ type: text, text: {...} }], details: { json: { …解析后的 JSON… }, provider: 实际运行的提供商, model: 实际运行的模型 } }其中details.json是解析后且已通过 Schema 校验的 JSON 对象details.provider与details.model报告真实运行的提供商与模型——当宿主执行器如 CLI对模型 ID 做了规范化时这里返回的是执行所有者回报的规范值测试用例 reports the canonical provider and model returned by the execution owner 展示了google-gemini-cli将flash解析为google/gemini-3.1-flash-preview的过程。源码级原理一次 llm-task 调用发生了什么结合 src/llm-task-tool.ts 的实现一次调用的完整链路如下1. 构造系统提示第 213–219 行注入硬编码的 JSON-only 指令You are a JSON-only function. Return ONLY a valid JSON value. Do not wrap in markdown fences. Do not include commentary. Do not call tools.2. 组装用户消息第 222–226 行以TASK:\n{prompt}\n\nINPUT_JSON:\n{inputJson}的形式把任务指令与序列化后的input未提供时为null且要求可被JSON.stringify序列化否则报input must be JSON-serializable拼接为唯一的用户消息。3. 发起隔离补全第 221–240 行调用api.runtime.llm.completeexecution.mode isolated-agent-runtime隔离 Agent 运行时并透传reasoning思考级别、maxTokens、temperature、signal调用方取消信号与timeoutMs。测试 uses the isolated-completion operation 断言了这些字段的透传forwards caller cancellation to the isolated completion 验证取消信号会原样转发。4. 剥离代码围栏第 19–26 行stripCodeFences即使模型违规输出json ... 也会被正则剥离后进入解析阶段测试 strips fenced json。5. 严格 JSON 解析第 242–248 行JSON.parse失败立即抛LLM returned invalid JSON不做任何猜测性修复。6. Schema 校验第 250–262 行若提供了schema使用validateJsonSchemaValue校验解析结果不匹配时抛LLM JSON did not match schema: …并附上具体校验错误文本。测试还验证了不同调用传入相同$id的 Schema 时彼此独立、不会串用缓存validates caller schemas with repeated $id independently across calls。7. 思考级别thinking规范化第 182–191 行thinking参数会经api.runtime.agent.normalizeThinkingLevel规范化如on→low非法值如banana在发起推理前即抛Invalid thinking level且不调用补全对应测试用例模型专属级别如 gpt-5.6 的max/ultra由宿主策略校验。隔离与安全保证llm-task 的“隔离”不只是实现细节而是安全契约docs/tools/llm-task.md 的 Safety notes 与 README.md 的 Notes 均明确无对话记录不读取、不写入调用方 Agent 的 transcript不触发 Agent 生命周期钩子不向任何频道投递模型输出无回退no fallback使用选定的 provider/model/auth profile/runtime 只执行一次当该执行者无法提供字面零工具调用时不会偷偷回退到其他路由失败即关闭fail-closed所选 Agent harness 必须实现隔离补全否则调用在推理前直接失败报does not support isolated completion——这防止一个 JSON 任务静默退化成一次普通的、可调用工具的 Agent 回合CLI 运行时同样必须提供等效的隔离准备保证内置的 Claude、Gemini CLI 运行时已支持未采用该内部契约的第三方 CLI 会在进程启动前失败Gemini CLI 特殊限制Gemini CLI 的隔离补全支持 API-key 与 Vertex 认证但 Google OAuth 与 compute/Code Assist 认证会被拒绝托管账号策略可能在本地 CLI 设置加载后注入需要管理员权限的工具prompt 含原生path包含或开头/command也会在推理前失败因为 Gemini CLI 没有字面原始输入模式输出视为不可信除非用schema校验否则不要信任输出内容任何消费该输出的副作用步骤发送消息/邮件、post、exec之前应先在 Lobster 等工作流中完成审批approval。实战示例在 Lobster 工作流中调用llm-task 的目标场景是从工作流引擎发起结构化 LLM 步骤。以独立运行的 Lobster CLI 为例openclaw.invoke --tool llm-task --action json --args-json { prompt: Given the input email, return intent and draft., thinking: low, input: { subject: Hello, body: Can you help? }, schema: { type: object, properties: { intent: { type: string }, draft: { type: string } }, required: [intent, draft], additionalProperties: false } }重要限制上述示例假定独立的 Lobster CLI正在运行且其openclaw.invoke已具备正确的网关 URL/认证上下文。对于 OpenClaw 内置的嵌入式 Lobster runner这种嵌套 CLI 模式当前并不可靠参见 docs/tools/llm-task.md 的 Important limitation。在嵌入式 Lobster 提供受支持的桥接之前推荐两种替代方案直接在 Lobster 之外发起llm-task工具调用使用不依赖嵌套openclaw.invoke的 Lobster 步骤。关于 Lobster 工作流引擎本身的更多用法可参考 docs/tools/lobster.md 与 docs/automation/taskflow.md。总结llm-task 以“一次调用、纯 JSON、强校验、零工具、完全隔离”五个特性为 OpenClaw 工作流提供了一个可组合、可审计的结构化 LLM 原语prompt负责任务意图input携带上下文schema把关输出质量provider/model/thinking/authProfileId/temperature/maxTokens/timeoutMs精确控制每次推理details.json让下游步骤拿到可直接消费的结构化数据。配合openclaw doctor --fix的自动化迁移和宿主导管的模型授权策略它既能安全地服务于批量自动化场景也避免了为每个工作流重复造轮子。延伸阅读插件完整配置说明见 extensions/llm-task/README.md实现源码见 src/llm-task-tool.ts行为契约测试见 src/llm-task-tool.test.tsDoctor 迁移逻辑见 doctor-contract-api.ts推理级别thinking体系可参考 docs/tools/thinking.md。【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 项目地址: https://gitcode.com/GitHub_Trending/cl/openclaw创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考