Skip to main content
快速入门

快速入门

5 步跑通你的第一个 Qoder Cloud Agent。

5 步跑通你的第一个 Qoder Cloud Agent：获取 PAT 或 SAT、选择环境、创建 Agent、创建 Session、收发消息。全程只需 curl，无需安装任何 SDK。
本文使用 curl 演示 API 调用。如果你希望在 AI 工具中使用 Cloud Agents，或通过 SDK 接入应用，请先查看 选择接入方式。

前置条件

  • 一个 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 必须使用同一区域的地址： 
export QODER_OPENAPI_BASE_URL="https://openapi.qoder.com.cn"
export QODER_API_BASE_URL="https://api.qoder.com.cn"

方式一：PAT（个人用户）

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

方式二：SAT（Service Account Token）

  1. 使用组织管理员账号登录 Qoder 控制台
  2. 在组织管理中创建或选择 Service Account
  3. 在 Service Account 详情页创建 API Key。创建时无需选择 scope；所需 scope 在置换 SAT 时指定
  4. 复制 SA Key，然后置换 SAT：
export QODER_SA_KEY="sa-key"

SAT_RESPONSE=$(curl --silent --show-error --location "$QODER_OPENAPI_BASE_URL/api/v1/serviceToken/exchange" \
  --header "Authorization: Bearer $QODER_SA_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "grant_type": "client_credentials",
    "audience": "qoder",
    "scope": "qca.access",
    "ttl_seconds": 43200
  }')

export QODER_SAT="$(printf '%s' "$SAT_RESPONSE" | jq -r '.access_token')"
export QODER_ACCESS_TOKEN="$QODER_SAT"
SA Key 只用于置换 SAT，不要直接用它调用 Cloud Agents API。SAT 最长有效 12 小时；过期后需要使用 SA Key 重新置换。
如果同一个服务端集成还需要调用 Forward API，请在置换请求中传入 "scope": "qca.access forward.access"。该 SAT 在 Forward 中具有当前 Service Account 所属账号下的管理员权限，只能在受信任的服务端使用。详见认证说明。

第 2 步：选择环境

查询可用环境列表，获取环境 ID： 
curl -s "$QODER_API_BASE_URL/api/v1/cloud/environments" \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN"
响应示例： 
{
  "data": [
    {
      "id": "env_019e44eb66bb748cabcd1489f6fa4428",
      "type": "environment",
      "name": "default",
      "description": "",
      "config": {
        "type": "cloud",
        "packages": {
          "type": "packages",
          "apt": [],
          "npm": [],
          "pip": []
        }
      },
      "metadata": {},
      "archived_at": null,
      "created_at": "2026-01-01T00:00:00Z",
      "updated_at": "2026-01-01T00:00:00Z"
    }
  ],
  "first_id": "env_019e44eb66bb748cabcd1489f6fa4428",
  "last_id": "env_019e44eb66bb748cabcd1489f6fa4428",
  "has_more": false,
  "next_page": null
}
如果返回 "data": []（空数组），说明账号下还没有环境，请先创建一个：
curl -s -X POST "$QODER_API_BASE_URL/api/v1/cloud/environments" \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"default"}'

# 提取环境 ID（建议用 jq 自动提取，避免手动复制长 ID）
ENV_ID=$(curl -s "$QODER_API_BASE_URL/api/v1/cloud/environments" \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" | jq -r '.data[0].id')

echo "环境 ID: $ENV_ID"

第 3 步：创建 Agent

定义一个具备 shell 工具的通用 Agent： 
AGENT_RESPONSE=$(curl -s -X POST "$QODER_API_BASE_URL/api/v1/cloud/agents" \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-first-agent",
    "model": "ultimate",
    "system": "你是一个高效的编程助手，擅长代码编写和问题排查。",
    "tools": [
      {
        "type": "agent_toolset_20260401",
        "enabled_tools": ["Bash", "Read", "Write", "Edit", "Glob", "Grep", "WebFetch", "WebSearch"]
      }
    ]
  }')
echo "$AGENT_RESPONSE" | jq .
AGENT_ID=$(echo "$AGENT_RESPONSE" | jq -r '.id')
echo "Agent ID: $AGENT_ID"
响应示例： 
{
  "id": "agent_019e451902fe7a2ca42c2dfc62d9320e",
  "type": "agent",
  "name": "my-first-agent",
  "description": "",
  "model": "ultimate",
  "system": "你是一个高效的编程助手，擅长代码编写和问题排查。",
  "tools": [
    {
      "type": "agent_toolset_20260401",
      "enabled_tools": ["Bash", "Read", "Write", "Edit", "Glob", "Grep", "WebFetch", "WebSearch"]
    }
  ],
  "mcp_servers": [],
  "skills": [],
  "metadata": {},
  "multiagent": null,
  "version": 1,
  "archived_at": null,
  "created_at": "2026-05-18T10:00:00Z",
  "updated_at": "2026-05-18T10:00:00Z"
}

第 4 步：创建 Session

创建 Session 需要两个必填参数：agent（Agent ID 或对象）和 environment_id（Environment ID）。 将 Agent 绑定到环境，创建运行实例： 
SESSION_RESPONSE=$(curl -s -X POST "$QODER_API_BASE_URL/api/v1/cloud/sessions" \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{
    \"agent\": \"$AGENT_ID\",
    \"environment_id\": \"$ENV_ID\"
  }")
echo "$SESSION_RESPONSE" | jq .
SESSION_ID=$(echo "$SESSION_RESPONSE" | jq -r '.id')
echo "Session ID: $SESSION_ID"
响应示例： 
{
  "id": "sess_019e451b146470cda02c560bf019fb37",
  "type": "session",
  "agent": {
    "id": "agent_019e451902fe7a2ca42c2dfc62d9320e",
    "type": "agent",
    "name": "my-first-agent",
    "model": {"id": "ultimate", "effective_context_window": 200000},
    "version": 1
  },
  "environment_id": "env_019e44eb66bb748cabcd1489f6fa4428",
  "status": "idle",
  "title": null,
  "metadata": {},
  "resources": [],
  "vault_ids": [],
  "deployment_id": null,
  "outcome_evaluations": [],
  "stats": {"active_seconds": 0, "duration_seconds": 0},
  "environment_variables": {},
  "archived_at": null,
  "created_at": "2026-05-18T10:01:00Z",
  "updated_at": "2026-05-18T10:01:00Z"
}
Session 创建后处于 idle 状态，需要在下一步发送消息后 Agent 才会开始执行。

第 5 步：发消息 + 收事件

向 Session 发送用户消息，然后通过 SSE 流实时接收 Agent 响应： 
# 发送消息（注意：请求体需要用 events 数组包裹）
curl -s -X POST "$QODER_API_BASE_URL/api/v1/cloud/sessions/$SESSION_ID/events" \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      {
        "type": "user.message",
        "content": [{"type": "text", "text": "用 Python 写一个计算斐波那契数列的函数，并运行测试。"}]
      }
    ]
  }' | jq .

# 通过 SSE 流实时接收事件
curl -s -N "$QODER_API_BASE_URL/api/v1/cloud/sessions/$SESSION_ID/events/stream" \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN"
事件流输出示例： 
id: evt_019ef515680d7a0ebd3160ca45ec5484
event: user.message
data: {"content":[{"text":"用 Python 写一个计算斐波那契数列的函数，并运行测试。","type":"text"}],"id":"evt_019ef515680d7a0ebd3160ca45ec5484","processed_at":"2026-06-23T15:24:41.357659669Z","type":"user.message"}

id: evt_019ef515681a7c52a0b45aa87625f121
event: session.status_running
data: {"id":"evt_019ef515681a7c52a0b45aa87625f121","processed_at":"2026-06-23T15:24:41.357659669Z","type":"session.status_running"}

event: heartbeat
data: {}

id: evt_49dce735a4ab4fc4
event: agent.thinking
data: {"id":"evt_49dce735a4ab4fc4","processed_at":"2026-06-23T15:24:49.357659Z","type":"agent.thinking"}

id: evt_02f80c5a8c245e04
event: agent.message
data: {"content":[{"text":"我将创建一个包含斐波那契函数和完整测试的 Python 模块。","type":"text"}],"id":"evt_02f80c5a8c245e04","processed_at":"2026-06-23T15:24:49.357659Z","type":"agent.message"}

id: evt_50739b167fb7c6d3
event: agent.tool_use
data: {"evaluated_permission":"allow","id":"evt_50739b167fb7c6d3","input":{"content":"def fibonacci(n): ...","file_path":"/data/fibonacci.py"},"name":"Write","processed_at":"2026-06-23T15:24:49.357659Z","type":"agent.tool_use"}

id: evt_e7c375f3605ff156
event: agent.tool_result
data: {"content":[{"text":"Write file /data/fibonacci.py successfully","type":"text"}],"id":"evt_e7c375f3605ff156","is_error":false,"processed_at":"2026-06-23T15:25:01.853844Z","type":"agent.tool_result"}

id: evt_60eba1483797a419
event: session.status_idle
data: {"id":"evt_60eba1483797a419","processed_at":"2026-06-23T15:25:24.436729Z","stop_reason":{"type":"end_turn"},"type":"session.status_idle"}
  • 除 heartbeat 外，每条事件都有 id: 行，JSON 负载包含 id、type 和 processed_at 字段。
  • heartbeat 事件约每 15 秒发送一次，用于保持连接活跃。
  • agent.message 的 content 字段使用 [{"type":"text","text":"..."}] 数组格式。
  • session.status_running / session.status_idle 除 id、type、processed_at（idle 还有 stop_reason）外不携带其他字段。
  • agent.thinking 表示模型正在推理，不包含 content 或 text 字段。

端到端脚本

将以上步骤整合为一个可直接运行的脚本： 
#!/bin/bash
# Qoder Cloud Agents 快速开始脚本
# 用法：export QODER_ACCESS_TOKEN="your-token" && bash quickstart.sh
# 中国区需额外设置：export QODER_API_BASE_URL="https://api.qoder.com.cn"

set -euo pipefail

QODER_API_BASE_URL="${QODER_API_BASE_URL:-https://api.qoder.com.cn}"
BASE_URL="$QODER_API_BASE_URL/api/v1/cloud"
HEADERS=(
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN"
)

echo "=== 第 1 步：获取环境 ==="
ENV_ID=$(curl -s "$BASE_URL/environments" "${HEADERS[@]}" | jq -r '.data[0].id')
if [ "$ENV_ID" = "null" ] || [ -z "$ENV_ID" ]; then
  echo "未找到环境，正在创建默认环境..."
  ENV_ID=$(curl -s -X POST "$BASE_URL/environments" \
    "${HEADERS[@]}" \
    -H "Content-Type: application/json" \
    -d '{"name":"default"}' | jq -r '.id')
fi
echo "环境 ID: $ENV_ID"

echo "=== 第 2 步：获取或创建 Agent ==="
AGENT_ID=$(curl -s "$BASE_URL/agents" "${HEADERS[@]}" | jq -r '.data[0].id')
if [ "$AGENT_ID" = "null" ] || [ -z "$AGENT_ID" ]; then
  AGENT_ID=$(curl -s -X POST "$BASE_URL/agents" \
    "${HEADERS[@]}" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "quickstart-agent",
      "model": "ultimate",
      "system": "你是一个高效的编程助手。",
      "tools": [
        {
          "type": "agent_toolset_20260401",
          "enabled_tools": ["Bash", "Read", "Write", "Edit", "Glob", "Grep", "WebFetch", "WebSearch"]
        }
      ]
    }' | jq -r '.id')
fi
echo "Agent ID: $AGENT_ID"

echo "=== 第 3 步：创建 Session ==="
SESSION_ID=$(curl -s -X POST "$BASE_URL/sessions" \
  "${HEADERS[@]}" \
  -H "Content-Type: application/json" \
  -d "{\"agent\": \"$AGENT_ID\", \"environment_id\": \"$ENV_ID\"}" | jq -r '.id')
echo "Session ID: $SESSION_ID"

echo "=== 第 4 步：发送消息 ==="
curl -s -X POST "$BASE_URL/sessions/$SESSION_ID/events" \
  "${HEADERS[@]}" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      {"type": "user.message", "content": [{"type": "text", "text": "打印 Hello World 并告诉我当前系统时间。"}]}
    ]
  }' | jq .

echo "=== 第 5 步：接收事件流 ==="
echo "（按 Ctrl+C 退出）"
curl -s -N "$BASE_URL/sessions/$SESSION_ID/events/stream" "${HEADERS[@]}"

常见问题

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: Stream endpoint 支持 Last-Event-ID header 进行断线重连。重连时在请求头中传入上次收到的事件 ID，流将从该事件之后开始重放。如需查询历史事件，请使用 GET /api/v1/cloud/sessions/{id}/events?order=desc。 Q: GET /api/v1/cloud/environments 返回空数组？ A: 新账号可能没有预置环境，请参照第 2 步中的提示手动创建一个。

下一步