远程 API

通过经认证的前台 HTTP 服务运行 q 会话和一次性代理请求。

查看 Markdown

配置并启动

配置监听地址、认证开关和 Remote 专用 API 密钥：

powershell

q remote config

然后运行前台服务：

powershell

q remote

默认监听地址为 127.0.0.1:0。Remote 密钥与 Gateway 密钥分开，因为 Remote 可以选择 q 进程有权访问的任何工作目录，并执行可修改工作区的工具。

查询工作区状态

列出指定工作目录中的会话：

powershell

curl.exe -H "Authorization: Bearer $env:Q_REMOTE_KEY" "http://127.0.0.1:8080/v1/sessions?working_directory=C%3A%5Cwork%5Cproject"

列出同一工作区中有效的内置和自定义子代理：

powershell

curl.exe -H "Authorization: Bearer $env:Q_REMOTE_KEY" "http://127.0.0.1:8080/v1/subagents?working_directory=C%3A%5Cwork%5Cproject"

运行代理

POST /v1/subagent-runs 接受 JSON，并流式返回 application/x-ndjson 事件：

powershell

curl.exe -N `
  -H "Authorization: Bearer $env:Q_REMOTE_KEY" `
  -H "Content-Type: application/json" `
  -d '{"working_directory":"C:\\work\\project","prompt":"解释启动路径"}' `
  http://127.0.0.1:8080/v1/subagent-runs

必须提供 working_directory 和 prompt。省略 session_id 会创建新会话；提供它会恢复未被占用的现有会话。省略 subagent 或发送空值会运行默认主循环。设置为 builtin/scout 等 ID 则使用直接子代理流程。

提示上限为 32 KiB UTF-8 数据，完整 JSON 请求正文上限为 256 KiB。未知 JSON 字段会被拒绝。响应使用 Cache-Control: no-store，X-Q-Session-ID 标头给出所选会话。

流事件

第一个 NDJSON 记录始终是 session。其中 working_directory、session_id 和 created 表示规范化的工作区以及是否创建了新会话。

类型	主要字段	含义
`status`	`detail`	启动警告或简短运行状态
`activity`	`agent`, `task_id`, `parent_id`, `action`, `detail`	子代理生命周期进度
`trace`	`agent`, `kind`, `call_id`, `name`, `content`, `is_error`	详细子代理跟踪项
`tool_call`	`call_id`, `name`, `content`	主代理工具请求；`content` 包含参数
`message`	`role`, `name`, `call_id`, `content`, `is_error`	加入会话的模型或工具消息
`question`	`question`, `context`	尝试交互提问；Remote 无法接受回答
`result`	`session_id`, `outcome`, `content`	成功的最终结果
`cancelled`	—	取消后的终止记录
`error`	`error`	开始流式响应后的最终错误

客户端应忽略不需要的字段，并持续读取直到终止记录。断开连接会取消请求上下文和当前运行。

错误与容量

开始流式响应前的失败使用 JSON error 对象和 HTTP 状态：

状态	代码	含义
`400`	`invalid_request`	JSON、目录、会话 ID、Content-Type 或请求形状无效
`401`	`invalid_api_key`	已开启认证，但 bearer 密钥缺失或无效
`404`	`session_not_found` 或 `subagent_not_found`	所选会话或子代理不存在
`409`	`session_busy`	另一进程已占用所选会话
`413`	`request_too_large`	正文或提示超出限制
`429`	`remote_capacity`	活跃运行达到 `agents.max_parallel`
`503`	`subagent_unavailable`	代理存在，但配置的运行时不可用

GET /v1/health 报告服务版本及当前是否接受新运行。它与 /openapi.json 都允许无 bearer 密钥访问，但不暴露工作区状态。

远程边界

Remote 保留工具列表中的 ask_to_user，但流是单向的。q 会发出尝试的 question，随后立即返回“无法交互”的工具错误。模型可以根据现有信息继续，或报告被阻塞。

Remote 不提供内置 TLS、路径允许列表、后台任务、重新连接或交互回答。除非具备认证及可信的保密网络或反向代理，否则请仅在回环地址使用。

运行中的服务通过 /openapi.json 提供准确协议。