Ask User Tool: Pausing Agent Execution for Human Input

ask_user enables the agent to present the human with one to three structured questions and pause until responses are received. It is intended for choices that rightfully belong to the user, not for routine acknowledgments or data the agent can infer from the request, existing code, or a reasonable default.

This tool is only present in the main session. Subagents and other non-primary executions do not have access to it.

Answer a question

Responses can be provided from any supported conversation interface:

• In the web Control UI, a question panel appears docked directly above the composer. For prompts with multiple questions, the panel displays them one at a time and moves through a compact stepper. Once resolved, the panel disappears and the chat retains only a brief answer summary.
• Telegram, Discord, and Slack display native buttons for single-choice, single-question prompts.
• A plain text reply functions on every channel. Respond with a number, an option label, or your own text.

OpenClaw always includes a free-text Other option. The agent must not add an Other entry to the list of authored choices.

Platform behavior

Answers function across all supported conversation surfaces. The web Control UI employs a docked stepper that replaces the composer while active; collapsing it reveals the full composer beneath a narrow question bar. iOS, macOS, and Android show inline cards, with multiple questions intentionally stacked for touch-friendly interaction. Every platform preserves the question-to-answer summary in the active chat timeline without automatic deletion, and Skip is available everywhere.

Prompts that cannot use native buttons, such as those with multiple questions or multi-select options, fall back to readable text on channels. The Control UI retains the full structured stepper.

Timeout and no answer

The default timeout is set to 900 seconds. timeoutSeconds is limited to a range of 30 to 3600 seconds.

If the question expires or is canceled before receiving an answer, the tool returns status: "no_answer". The agent then proceeds using its best judgment. An aborted agent run cancels any pending Gateway question.

Tool schema

{
  questions: Array<{
    id: string; // unique snake_case answer key
    header: string; // short label; truncated to 12 characters
    question: string; // one sentence
    options: Array<{
      label: string;
      description?: string;
    }>; // 2-4 options
    multiSelect?: boolean;
  }>; // 1-3 questions
  timeoutSeconds?: number; // integer; default 900, clamped to 30-3600
}

With multiSelect: true, the user can select multiple options. Answer values are provided as an array for each question.

Example of a completed response:

{
  "status": "answered",
  "answers": {
    "answers": {
      "deploy_target": ["Staging (Recommended)"]
    }
  }
}

Model guidance

The model-facing contract instructs the agent to:

• ask only when blocked by a decision that genuinely belongs to the user;
• prefer a single question and use no more than three;
• place the recommended option first and append (Recommended) to its label;
• omit an authored Other option, since free text is included automatically;
• continue with best judgment after receiving no_answer.

The agent should not use ask_user to request permission to proceed or to confirm its own plan.