快速开始 - Qoder

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 安装 Windows Subsystem for Linux

如果使用 PowerShell，需注意以下差异：

环境变量设置：$env:QODER_PAT="your-token"（而非 export）
调用真实 curl：使用 curl.exe（PowerShell 的 curl 是 Invoke-WebRequest 的别名）
jq 需额外安装：winget install jqlang.jq

获取 PAT

打开 Qoder 控制台。

进入个人访问令牌页面

依次点击 设置 → 个人访问令牌。

创建令牌

点击 创建令牌，设置名称和有效期。

导出为环境变量

复制令牌并执行：

export QODER_PAT="your-personal-access-token"

令牌只在创建时显示一次，请立即保存。建议写入 ~/.bashrc 或 ~/.zshrc。

创建第一个 Session

选择环境

查询可用环境列表，获取环境 ID：

curl -s https://api.qoder.com/api/v1/cloud/environments \
  -H "Authorization: Bearer $QODER_PAT"

响应示例：

{
  "data": [
    {
      "id": "env_019e44eb66bb748cabcd1489f6fa4428",
      "name": "default",
      "config": {
        "type": "cloud",
        "networking": {
          "type": "unrestricted"
        }
      },
      "status": "ready",
      "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
}

如果返回 "data": []（空数组），说明账号下还没有环境，请先创建一个：

curl -s -X POST https://api.qoder.com/api/v1/cloud/environments \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{"name":"default","config":{"type":"cloud","networking":{"type":"unrestricted"}}}'

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

echo "环境 ID: $ENV_ID"

创建 Agent

定义一个具备 shell 工具的通用 Agent：

AGENT_RESPONSE=$(curl -s -X POST https://api.qoder.com/api/v1/cloud/agents \
  -H "Authorization: Bearer $QODER_PAT" \
  -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": {},
  "version": 1,
  "archived": false,
  "archived_at": null,
  "created_at": "2026-05-18T10:00:00Z",
  "updated_at": "2026-05-18T10:00:00Z"
}

创建 Session

创建 Session 需要两个必填参数：agent（Agent ID 或对象）和 environment_id（Environment ID）。将 Agent 绑定到环境，创建运行实例：

SESSION_RESPONSE=$(curl -s -X POST https://api.qoder.com/api/v1/cloud/sessions \
  -H "Authorization: Bearer $QODER_PAT" \
  -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",
  "agent": {
    "id": "agent_019e451902fe7a2ca42c2dfc62d9320e",
    "name": "my-first-agent",
    "model": "ultimate",
    "system": "你是一个高效的编程助手，擅长代码编写和问题排查。",
    "tools": [
      {"type": "agent_toolset_20260401", "enabled_tools": ["Bash", "Read", "Write", "Edit", "Glob", "Grep", "WebFetch", "WebSearch"]}
    ],
    "mcp_servers": [],
    "description": "",
    "skills": [],
    "metadata": {},
    "type": "agent",
    "version": 1,
    "created_at": "2026-05-18T10:00:00Z",
    "updated_at": "2026-05-18T10:00:00Z"
  },
  "agent_id": "agent_019e451902fe7a2ca42c2dfc62d9320e",
  "environment_id": "env_019e44eb66bb748cabcd1489f6fa4428",
  "status": "idle",
  "title": "",
  "turn_status": "idle",
  "memory_store_ids": [],
  "resources": [],
  "vault_ids": [],
  "type": "session",
  "created_at": "2026-05-18T10:01:00Z",
  "updated_at": "2026-05-18T10:01:00Z"
}

Session 创建后处于 idle 状态，需要在下一步发送消息后 Agent 才会开始执行。

发消息并接收事件流

向 Session 发送用户消息，然后通过 SSE 流实时接收 Agent 响应：

# 发送消息（注意：请求体需要用 events 数组包裹）
curl -s -X POST "https://api.qoder.com/api/v1/cloud/sessions/$SESSION_ID/events" \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      {
        "type": "user.message",
        "content": [{"type": "text", "text": "用 Python 写一个计算斐波那契数列的函数，并运行测试。"}]
      }
    ]
  }' | jq .

# 通过 SSE 流实时接收事件
curl -s -N "https://api.qoder.com/api/v1/cloud/sessions/$SESSION_ID/events/stream" \
  -H "Authorization: Bearer $QODER_PAT"

事件流输出示例：

event: user.message
data: {"type":"user.message","content":"用 Python 写一个计算斐波那契数列的函数，并运行测试。"}

event: session.status_running
data: {"type":"session.status_running","status":"running"}

event: heartbeat
data: {}

event: span.model_request_start
data: {"type":"span.model_request_start"}

event: agent.thinking
data: {"type":"agent.thinking","content":"让我编写一个斐波那契函数..."}

event: agent.message
data: {"type":"agent.message","content":[{"type":"text","text":"以下是斐波那契数列的实现：..."}]}

event: agent.tool_use
data: {"type":"agent.tool_use","name":"Bash","input":{"command":"python3 fib.py"}}

event: agent.tool_result
data: {"type":"agent.tool_result","output":"..."}

event: span.model_request_end
data: {"type":"span.model_request_end"}

event: session.status_idle
data: {"type":"session.status_idle","status":"idle"}

heartbeat 事件约每 15 秒发送一次，用于保持连接活跃。
agent.message 的 content 字段使用 [{"type":"text","text":"..."}] 数组格式。

流程解析

当你发送 user.message 事件后，平台会：

接收消息，Session 从 idle 转入 processing（发出 session.status_running）。
启动模型请求，调用绑定的 Agent（发出 span.model_request_start）。
流式输出 Agent 内容 —— agent.thinking 是推理过程，agent.message 是回复正文，agent.tool_use 和 agent.tool_result 对应每次工具调用。
保持连接活跃，定期发送 heartbeat（约 15 秒一次）。
结束本轮 turn，发出 span.model_request_end 和 session.status_idle。Session 可复用 —— 再发一条 user.message 即可继续。

端到端脚本

将以上步骤整合为一个可直接运行的脚本：

#!/bin/bash
# Qoder Cloud Agents 快速开始脚本
# 用法：export QODER_PAT="your-token" && bash quickstart.sh

set -euo pipefail

BASE_URL="https://api.qoder.com/api/v1/cloud"
HEADERS=(
  -H "Authorization: Bearer $QODER_PAT"
)

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","config":{"type":"cloud","networking":{"type":"unrestricted"}}}' | 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_PAT 是否已正确设置，令牌是否过期。重新创建令牌并更新环境变量。 Q: 创建 Agent 返回 400 Bad Request？ A: 检查请求体 JSON 格式是否正确，model 字段是否为有效值（如 "ultimate"），tools 是否为数组。 Q: Session 一直处于 idle 状态，收不到事件？ A: Session 创建后默认为 idle，必须向其发送 user.message 事件才会触发 Agent 执行。请确认第 4 步已正确执行。 Q: SSE 流连接中断了怎么办？ A: 推荐保留断线前最后一个事件的 id 字段（如 evt_...），重连时带 ?after_id=<last_event_id> 查询参数，服务端会从该事件之后继续推送，不丢中间事件。如未保留则用 GET /sessions/{id}/events?order=desc 回放近期事件后再开 stream。 Q: GET /environments 返回空数组？ A: 新账号可能没有预置环境，请参照「选择环境」步骤中的提示手动创建一个。

下一步

定义 Agent

了解 Agent 配置的全部字段。

云端环境配置

自定义运行环境。

启动 Session

深入会话管理。

Agent Skills

为 Agent 附加领域专业知识，提升特定任务表现。

​前置条件

​获取 PAT

​创建第一个 Session

​流程解析

​端到端脚本

​常见问题

​下一步

定义 Agent

云端环境配置

启动 Session

Agent Skills

前置条件

获取 PAT

创建第一个 Session

流程解析

端到端脚本

常见问题

下一步