快速开始-Qoder CN 系列(Lingma)-阿里云帮助中心

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

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

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 步中的提示手动创建一个。