> ## Documentation Index
> Fetch the complete documentation index at: https://openclaw.zhcndoc.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 询问用户

`ask_user` 允许代理向人类提出一到三个结构化问题，并
等待回答。它适用于真正属于用户的决策，
而不是例行确认，或代理可以从请求、
代码，或合理默认值中推导出的信息。

该工具仅在主会话中可用。子代理和其他非主
运行不会获得它。

## 回答问题

您可以从任何受支持的对话界面进行回答：

* Web Control UI 会在输入框上方直接停靠一个问题面板。对于
  多问题提示，该面板一次显示一个问题，并通过一个简短的步骤器逐步推进。解决后，面板会关闭，聊天中
  只保留一个简洁的答案摘要。
* Telegram、Discord 和 Slack 会为单选、单问题提示渲染原生按钮。
* 纯文本回复适用于任何频道。您可以回复一个数字、一个选项标签，
  或者您自己的答案。

OpenClaw 始终启用一个自由文本的 **其他** 答案。代理不得向已编写的选项列表中添加
`Other` 选项。

## 平台行为

答案在每个受支持的会话界面上都有效。Web Control UI 使用一个停靠式步骤器，在展开时会替代输入框；折叠后会在一条纤细的问题栏下恢复完整输入框。iOS、macOS 和 Android 显示内联卡片；多个问题会作为一种有意的、适合触控的模式叠放在一起。每个平台都会将问题到答案的摘要保留在当前聊天时间线中，不会因超时而移除，而且 **Skip** 在所有地方都可用。

无法使用原生按钮的提示，包括多问题和多选提示，会在各渠道降级为可读文本。Control UI 保留完整的结构化步骤器。

## 超时和无答案

默认超时时间为 900 秒。`timeoutSeconds` 会被限制在
30 到 3600 秒的范围内。

如果问题在答案到达之前过期或被取消，工具会返回
`status: "no_answer"`。然后代理会基于自己的最佳判断继续执行。

中止的代理运行会取消其挂起的 Gateway 问题。

Gateway 问题记录包含可选的来源 `runId`。客户端可以
使用它将提示及其最终答案摘要与正确的代理轮次保持关联，
包括在重新连接并通过 `question.list` 或 `question.get` 恢复问题之后。

## 工具 schema

```ts theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  questions: Array<{
    id: string; // 唯一的 snake_case 答案键
    header: string; // 简短标签；截断为 12 个字符
    question: string; // 一句话
    options: Array<{
      label: string;
      description?: string;
    }>; // 2-4 个选项
    multiSelect?: boolean;
  }>; // 1-3 个问题
  timeoutSeconds?: number; // 整数；默认 900，限制在 30-3600 之间
}
```

当 `multiSelect: true` 时，用户可以选择多个选项。每个问题的答案值都以数组形式返回。

示例已回答结果：

```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  "status": "answered",
  "answers": {
    "answers": {
      "deploy_target": ["预发布环境（推荐）"]
    }
  }
}
```

## 模型指导

面向模型的契约告诉代理要：

* 仅在真正由用户决定且因此被阻塞时才提问；
* 优先只问一个问题，且最多不超过三个；
* 将推荐选项放在第一位，并在其标签后加上 `(Recommended)`；
* 省略手动编写的 `Other` 选项，因为自由文本会自动添加；
* 在 `no_answer` 后继续依据最佳判断执行。

代理不应使用 `ask_user` 来询问是否可以继续，或用于确认
其自身的计划。