快速开始

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

前置条件

一个 Qoder 账号
终端环境（macOS / Linux / WSL）
curl 和 jq（可选，用于格式化 JSON）

第 1 步：获取 PAT

登录 Qoder 控制台
进入「设置 → 个人访问令牌」
点击「创建令牌」，设置名称和有效期
复制令牌并设置环境变量：

# 将 PAT 设置为环境变量，后续所有命令都会用到
export QODER_PAT="your-personal-access-token"

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

第 2 步：选择环境

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

# 列出所有可用环境
curl -s https://openapi.qoder.sh/api/v1/cloud/environments \
  -H "Authorization: Bearer $QODER_PAT"

响应示例：

{
  "data": [
    {
      "id": "env_default",
      "name": "default",
      "config": {
        "type": "cloud",
        "networking": "unrestricted"
      },
      "status": "ready",
      "created_at": "2026-01-01T00:00:00Z",
      "updated_at": "2026-01-01T00:00:00Z"
    }
  ],
  "first_id": "env_default",
  "last_id": "env_default",
  "has_more": false
}

# 提取默认环境 ID
ENV_ID=$(curl -s https://openapi.qoder.sh/api/v1/cloud/environments \
  -H "Authorization: Bearer $QODER_PAT" | jq -r '.data[0].id')

echo "环境 ID: $ENV_ID"

第 3 步：创建 Agent

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

# 创建 Agent，返回 201
curl -s -X POST https://openapi.qoder.sh/api/v1/cloud/agents \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-first-agent",
    "model": "ultimate",
    "system": "你是一个高效的编程助手，擅长代码编写和问题排查。",
    "tools": [
      {"type": "bash_20250124"}
    ]
  }' | jq .

响应示例：

{
  "id": "ag_abc123def456",
  "name": "my-first-agent",
  "model": "ultimate",
  "system": "你是一个高效的编程助手，擅长代码编写和问题排查。",
  "tools": [{"type": "bash_20250124"}],
  "metadata": {},
  "version": 1,
  "created_at": "2026-05-18T10:00:00Z",
  "updated_at": "2026-05-18T10:00:00Z"
}

# 提取 Agent ID
AGENT_ID=$(curl -s -X POST https://openapi.qoder.sh/api/v1/cloud/agents \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-first-agent",
    "model": "ultimate",
    "system": "你是一个高效的编程助手。",
    "tools": [{"type": "bash_20250124"}]
  }' | jq -r '.id')

echo "Agent ID: $AGENT_ID"

第 4 步：启动 Session

将 Agent 绑定到环境，创建运行实例：

# 启动 Session，返回 201
curl -s -X POST https://openapi.qoder.sh/api/v1/cloud/sessions \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d "{
    \"agent\": \"$AGENT_ID\",
    \"environment_id\": \"$ENV_ID\"
  }" | jq .

响应示例：

{
  "id": "ses_xyz789",
  "agent_id": "ag_abc123def456",
  "environment_id": "env_default",
  "status": "idle",
  "title": null,
  "metadata": {},
  "usage": {
    "input_tokens": 0,
    "output_tokens": 0
  },
  "created_at": "2026-05-18T10:01:00Z",
  "updated_at": "2026-05-18T10:01:00Z"
}

# 提取 Session ID
SESSION_ID=$(curl -s -X POST https://openapi.qoder.sh/api/v1/cloud/sessions \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d "{\"agent\": \"$AGENT_ID\", \"environment_id\": \"$ENV_ID\"}" | jq -r '.id')

echo "Session ID: $SESSION_ID"

第 5 步：发消息 + 收事件

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

# 发送消息
curl -s -X POST "https://openapi.qoder.sh/api/v1/cloud/sessions/$SESSION_ID/events" \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "user.message",
    "content": "用 Python 写一个计算斐波那契数列的函数，并运行测试。"
  }' | jq .

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

事件流输出示例：

event: session.status_rescheduled
data: {"type":"session.status_rescheduled","status":"processing"}

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":"以下是斐波那契数列的实现：..."}

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

端到端脚本

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

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

set -euo pipefail

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

echo "=== 第 1 步：获取默认环境 ==="
ENV_ID=$(curl -s "$BASE_URL/environments" "${HEADERS[@]}" | jq -r '.data[0].id')
echo "环境 ID: $ENV_ID"

echo "=== 第 2 步：创建 Agent ==="
AGENT_ID=$(curl -s -X POST "$BASE_URL/agents" \
  "${HEADERS[@]}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "quickstart-agent",
    "model": "ultimate",
    "system": "你是一个高效的编程助手。",
    "tools": [{"type": "bash_20250124"}]
  }' | jq -r '.id')
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 '{
    "type": "user.message",
    "content": "打印 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 发送 user.message 事件。Session 创建后默认为 idle，需要发送消息才会触发处理。 Q: SSE 流连接中断了怎么办？ A: 重新请求 events/stream 端点即可，事件会从最新状态开始推送。也可以通过 GET 轮询方式获取历史事件。

下一步

定义 Agent — 了解 Agent 配置的全部字段
云端环境 — 自定义运行环境
启动 Session — 深入会话管理

快速入门

用户指南

SDK

Cloud Agents

前置条件

第 1 步：获取 PAT

第 2 步：选择环境

第 3 步：创建 Agent

第 4 步：启动 Session

第 5 步：发消息 + 收事件

端到端脚本

常见问题

下一步

快速入门

用户指南

SDK

Cloud Agents

Documentation Index

​前置条件

​第 1 步：获取 PAT

​第 2 步：选择环境

​第 3 步：创建 Agent

​第 4 步：启动 Session

​第 5 步：发消息 + 收事件

​端到端脚本

​常见问题

​下一步

前置条件

第 1 步：获取 PAT

第 2 步：选择环境

第 3 步：创建 Agent

第 4 步：启动 Session

第 5 步：发消息 + 收事件

端到端脚本

常见问题

下一步