Skip to main content
操作指南

快速开始

5 步跑通你的第一个 Qoder Cloud Agent：获取令牌、选择环境、创建 Agent、创建 Session、收发消息。全程只需 curl，无需安装任何 SDK。

前置条件

  • 一个 Qoder 账号
  • 终端环境（macOS / Linux / WSL）
  • curl 和 jq（可选，用于格式化 JSON）
Windows 用户：本文档中的命令基于 bash 语法。Windows 用户推荐使用 Git Bash（安装 Git for Windows 自带）或 WSL（通过 wsl --install 安装）。如果使用 PowerShell，需注意：环境变量设置用 $env:QODER_PAT="your-token"，调用真实 curl 用 curl.exe，jq 需额外安装（winget install jqlang.jq）。

第 1 步：获取 PAT

  1. 登录 Qoder 控制台
  2. 进入「设置 → 个人访问令牌」
  3. 点击「创建令牌」，设置名称和有效期
  4. 复制令牌并设置环境变量：
export QODER_PAT="your-token-here"
令牌只在创建时显示一次，请立即保存。建议写入 ~/.bashrc 或 ~/.zshrc。

第 2 步：选择环境

查询可用环境列表，获取环境 ID： 
curl -s https://api.qoder.com.cn/api/v1/cloud/environments \
  -H "Authorization: Bearer $QODER_PAT" | jq .
如果返回 "data": []（空数组），说明账号下还没有环境，请先创建一个：
curl -s -X POST https://api.qoder.com.cn/api/v1/cloud/environments \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{"name": "default", "config": {"type": "cloud", "networking": {"type": "unrestricted"}}}' | jq .

第 3 步：创建 Agent

定义一个具备 shell 工具的通用 Agent： 
curl -s -X POST https://api.qoder.com.cn/api/v1/cloud/agents \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "quickstart-agent",
    "model": "ultimate",
    "instructions": "You are a helpful coding assistant.",
    "tools": [
      {
        "type": "agent_toolset_20260401",
        "enabled_tools": ["Bash", "Read", "Write", "Edit", "Glob", "Grep", "WebFetch", "WebSearch"]
      }
    ]
  }' | jq .
记下响应中的 id 字段（如 agent_019e...），后续创建 Session 需要使用。

第 4 步：创建 Session

创建 Session 需要两个必填参数：agent（Agent ID 或对象）和 environment_id（Environment ID）。 将 Agent 绑定到环境，创建运行实例： 
curl -s -X POST https://api.qoder.com.cn/api/v1/cloud/sessions \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "agent_YOUR_AGENT_ID",
    "environment_id": "env_YOUR_ENV_ID"
  }' | jq .
Session 创建后处于 idle 状态，需要在下一步发送消息后 Agent 才会开始执行。

第 5 步：发消息 + 收事件

向 Session 发送用户消息，然后通过 SSE 流实时接收 Agent 响应： 
# 发送消息
curl -s -X POST "https://api.qoder.com.cn/api/v1/cloud/sessions/sess_YOUR_SESSION_ID/events" \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "user.message",
    "content": [{"type": "text", "text": "Write a Python function that calculates fibonacci numbers"}]
  }'

# 接收 SSE 事件流
curl -sN "https://api.qoder.com.cn/api/v1/cloud/sessions/sess_YOUR_SESSION_ID/events/stream" \
  -H "Authorization: Bearer $QODER_PAT"
heartbeat 事件约每 15 秒发送一次，用于保持连接活跃。agent.message 的 content 字段使用 [{"type":"text","text":"..."}] 数组格式。

常见问题

Q: 提示 401 Unauthorized 怎么办？ A: 检查 $QODER_PAT 是否已正确设置，令牌是否过期。重新创建令牌并更新环境变量。 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 步中的提示手动创建一个。

下一步

操作指南
实践教程
API参考