5 步跑通你的第一个 Qoder Cloud Agent：获取 PAT 或 SAT、选择环境、创建 Agent、创建 Session、收发消息。全程只需 curl，无需安装任何 SDK。
根据调用身份选择 PAT 或 SAT。后续步骤统一使用
查询可用环境列表，获取环境 ID：
定义一个具备 shell 工具的通用 Agent：
创建 Session 需要两个必填参数：
向 Session 发送用户消息，然后通过 SSE 流实时接收 Agent 响应：
Q: 提示 401 Unauthorized 怎么办？
A: 检查
前置条件
- 一个 Qoder 账号
- 终端环境（macOS / Linux / WSL）
curl和jq
Windows 用户：本文档中的命令基于 bash 语法。Windows 用户推荐使用 Git Bash（安装 Git for Windows 自带）或 WSL（通过
wsl --install 安装）。如果使用 PowerShell，需注意：环境变量设置用 $env:QODER_ACCESS_TOKEN="your-token"，调用真实 curl 用 curl.exe，jq 需额外安装（winget install jqlang.jq）。第 1 步：获取访问令牌
根据调用身份选择 PAT 或 SAT。后续步骤统一使用 QODER_ACCESS_TOKEN 环境变量。
先设置服务地址。置换 SAT 和调用业务 API 必须使用同一区域的地址：
方式一：PAT（个人用户）
- 登录 Qoder 控制台
- 进入「设置 → 个人访问令牌」
- 点击「创建令牌」，设置名称和有效期
- 复制令牌并设置环境变量：
PAT 只在创建时显示一次，请立即安全保存。
方式二：SAT（Service Account Token）
- 使用组织管理员账号登录 Qoder 控制台
- 在组织管理中创建或选择 Service Account
- 在 Service Account 详情页创建 API Key。创建时无需选择 scope；所需 scope 在置换 SAT 时指定
- 复制 SA Key，然后置换 SAT：
SA Key 只用于置换 SAT，不要直接用它调用 Cloud Agents API。SAT 最长有效 12 小时；过期后需要使用 SA Key 重新置换。
第 2 步：选择环境
查询可用环境列表，获取环境 ID：
如果返回
"data": []（空数组），说明账号下还没有环境，请先创建一个：第 3 步：创建 Agent
定义一个具备 shell 工具的通用 Agent：
记下响应中的
id 字段（如 agent_019e...），后续创建 Session 需要使用。第 4 步：创建 Session
创建 Session 需要两个必填参数：agent（Agent ID 或对象）和 environment_id（Environment ID）。
将 Agent 绑定到环境，创建运行实例：
Session 创建后处于
idle 状态，需要在下一步发送消息后 Agent 才会开始执行。第 5 步：发消息 + 收事件
向 Session 发送用户消息，然后通过 SSE 流实时接收 Agent 响应：
heartbeat 事件约每 15 秒发送一次，用于保持连接活跃。agent.message 的 content 字段使用 [{"type":"text","text":"..."}] 数组格式。常见问题
Q: 提示 401 Unauthorized 怎么办？
A: 检查 $QODER_ACCESS_TOKEN 是否已正确设置，令牌是否过期。PAT 用户请重新创建令牌；Service Account 用户请使用 SA Key 重新置换 SAT。
Q: 创建 Agent 返回 400 Bad Request？
A: 检查请求体 JSON 格式是否正确，model 字段是否为有效值（如 "ultimate"），tools 是否为数组。
Q: Session 一直处于 idle 状态，收不到事件？
A: Session 创建后默认为 idle，必须向其发送 user.message 事件才会触发 Agent 执行。请确认第 5 步已正确执行。
Q: SSE 流连接中断了怎么办？
A: 推荐保留断线前最后一个事件的 id 字段（如 evt_...），重连时带 ?after_id=<last_event_id> 查询参数，服务端会从该事件之后继续推送。
Q:GET /environments返回空数组？
A: 新账号可能没有预置环境，请参照第 2 步中的提示手动创建一个。
下一步
- 定义 Agent — 了解 Agent 配置的全部字段
- 云端环境 — 自定义运行环境
- 启动 Session— 深入会话管理