快速開始 - AI Coding Assistant 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 步中的提示手動建立一個。