Skip to main content
Glama

oc_run

Dispatch a task to a local OpenClaw agent and synchronously wait for the reply, with an adjustable timeout and duplicate-run protection.

Instructions

向指定 agent 下发任务,并同步等待最多 wait_seconds(默认 20,最大 120)。 参数:agent 填 oc_agents 返回的名字或别名,留空则使用 config.json 里的 defaultAgent;用户点名的 agent 不在 oc_agents 列表里时不要调用本工具,直接告诉用户没有这个 agent。message 只放任务本身,不要带“让某某做”的转述。 安全:任务会被 agent 在本机真实执行,不是模拟。删除、格式化、重启、对外发送消息等破坏性动作先跟用户确认;下发时尽量限定范围。 返回判读:status=done 时 reply 是完整结果,voice.speak 是适合朗读的短句——语音场景只播报 voice.speak,reply 只用于屏幕查看或回答追问,不要整段朗读;voice.needsSummary 或 replyTruncated=true 表示内容偏长或被截断,此时用 1–3 句话总结 reply,不要朗读代码、日志、diff、JSON、URL 或长列表;voice 提示可能含敏感信息时不要复述具体值。status=running 表示仍在跑,请用返回的 runId 调 oc_wait 继续等,不要重复调用本工具;同一会话已有任务时会返回 SESSION_BUSY 并带上当前 runId;submitReconciled=true 表示提交响应丢失但已确认任务在跑,按 running 处理。 限流默认 6 次/分钟,超限返回 RATE_LIMITED 与重试时间,不要立刻重发。

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "message": "<message>"
    },
    "name": "oc_run"
  }
}

Input Schema

NameRequiredDescriptionDefault
agentNoAgent 名字或 ID(先用 oc_agents 获取本机可用值)。留空使用默认 agent。
messageYes要下发的任务消息。
wait_secondsNo同步等待秒数,默认 20,最大 120。设为 0 立即返回。
idempotency_keyNo幂等键,透传给 Gateway;5 秒内相同 agent+message 会自动去重。

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A4.4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations supplied, the description carries the full behavioral burden. It discloses that execution is real and local rather than simulated, that destructive actions need user confirmation, that duplicate agent+message submissions are deduplicated, the error codes SESSION_BUSY, RATE_LIMITED, and submitReconciled, and the rate limit of 6/min. Remaining gaps: it does not say whether a task can be cancelled mid-run or what happens to SESSION_BUSY tasks beyond reusing the runId.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with purpose, then parameters, safety, return interpretation, and limits in a scannable order, and nearly every sentence carries an operational rule. Some redundancy remains, notably restating wait_seconds' default and maximum values that the schema already documents.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

There is no output schema, and the description compensates by fully decoding the response fields done/running, reply, voice.speak, voice.needsSummary, replyTruncated, runId, and submitReconciled, including how to speak results in voice contexts. For a mutation tool with async semantics and several failure modes, nothing an agent needs in order to call and interpret it is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline would be 3, but the description adds real meaning beyond the schema: agent may be a name or alias and empty falls back to config.json defaultAgent, and message must contain only the task itself without 'ask X to do' framing. wait_seconds is restated from the schema without adding detail, and idempotency_key is left entirely to the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: dispatch a task to a named agent and synchronously wait up to wait_seconds. It also distinguishes itself from siblings by saying a still-running task should be continued with oc_wait rather than by re-calling this tool, and that agent names must come from oc_agents.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit when-not-to-use: if the user names an agent absent from oc_agents, do not call and tell the user instead. Explicit alternative routing: status=running means call oc_wait with the runId, and SESSION_BUSY means reuse the returned runId rather than resubmitting. Rate-limit guidance says not to resend immediately.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools