Ask User Tool: Pause Agent for Human Decisions

ask_user enables the agent to pose between one and three structured questions to the human, then pause for their responses. It is meant for choices that rightly belong to the user, not for routine check-ins or details the agent can figure out from the request, the code, or a reasonable default.

Only the main session gets this tool. Subagents and other non-primary runs are excluded from it.

Answer a question

Responses can come from any supported conversation surface:

• The web Control UI places a question panel right above the composer. When multiple questions are asked, the panel displays them one at a time and moves through a short stepper. Once resolved, the panel disappears and the chat shows only a brief summary of the answer.
• Telegram, Discord, and Slack display native buttons for a prompt with a single question and a single choice.
• A plain-text reply works on every channel. Respond with a number, an option label, or your own text.

OpenClaw always provides a free-text Other answer. The agent must not include an Other option in the authored list.

Platform behavior

Answers function across all supported conversation surfaces. The web Control UI relies on a docked stepper that takes over the composer while open; collapsing it brings back the full composer below a slim question bar. iOS, macOS, and Android show inline cards; multiple questions remain stacked as a deliberate touch-friendly pattern. Every platform keeps the question-to-answer summary in the active chat timeline with no timed eviction, and Skip is available on all of them.

Prompts that cannot use native buttons, such as multi-question and multi-select ones, fall back to readable text on channels. The Control UI retains the full structured stepper.

Timeout and no answer

The default timeout is 900 seconds. timeoutSeconds is limited to the range 30 through 3600 seconds.

If the question times out or is cancelled before an answer arrives, the tool returns status: "no_answer". The agent then proceeds using its best judgment. An aborted agent run cancels its pending Gateway question.

Gateway question records include the optional originating runId. Clients can use it to keep the prompt and its final answer summary aligned with the correct agent turn, even after reconnecting and restoring the question via question.list or question.get.

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 come back as an array for every question.

Example answered result:

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

Model guidance

The model-facing contract instructs the agent to:

• ask only when stuck on a decision that truly belongs to the user;
• aim for one question and never exceed three;
• list the recommended option first and append (Recommended) to its label;
• leave out an authored Other option, since free text is added automatically;
• fall back on best judgment after no_answer.

The agent should not use ask_user to ask for permission to proceed or to validate its own plan.