Qoder Cloud Agents 使用说明

官方链接

• Qoder Cloud 首页: https://qoder.com/cloud/
• Qoder Cloud Quickstart: https://qoder.com/cloud/quickstart
• API Base: https://api.qoder.com/api/v1/cloud

一、先看整体流程

Qoder Cloud 的最短路径可以记成一句话：

PAT -> Environment -> Agent -> Session -> Message -> Stream

对应关系如下：

对象	作用
PAT	登录并调用 Cloud API 的凭证
Environment	Agent 运行的云环境
Agent	智能体本体，定义模型、工具和系统提示词
Session	Agent 的一次运行实例
Event	消息输入、工具调用、回复输出都会以事件形式流动

图1展示的是 Cloud Agents 首页。左侧是功能区，右侧是快速开始流程，按照页面提示依次完成 4 步就能跑通第一个 Agent。

---

二、前置条件

1. 账号

先准备一个 Qoder 账号。登录后进入控制台，再创建个人访问令牌，也就是 QODER_PAT。

2. 终端

建议使用以下环境之一：

• macOS
• Linux
• WSL

Windows 用户如果用 PowerShell，建议注意两点：

• 环境变量写法是 $env:QODER_PAT="your-token"
• 真实的 curl 要写成 curl.exe

如果你打算格式化 JSON，jq 也很方便：

winget install jqlang.jq

---

三、第一步: 获取 PAT

在控制台里进入个人访问令牌页面，创建后把 token 立刻保存好。这个值通常只显示一次。

示例:

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

PowerShell 示例:

$env:QODER_PAT="your-personal-access-token"

---

四、第二步: 选择或创建 Environment

Environment 是 Agent 的运行容器。你可以先查询现有环境：

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

如果返回空数组，说明账号下还没有环境，可以手动创建一个默认环境：

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"
      }
    }
  }'

界面上对应的是环境配置页。

图2和图3对应的是 Agent 配置区。这里要填名称、描述，并选择模型。实际可见的模型项会受到账号权限和当前可用模型的影响。

---

五、第三步: 创建 Agent

Agent 负责定义“这个智能体是谁、会用什么模型、能用哪些工具”。

一个最小化的示例：

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"]
      }
    ]
  }'

界面上这一步通常会看到：

• Agent 名称
• 模型下拉框
• 系统提示词
• 工具开关

图4展示的是 Environment 配置页。这里的环境名可以按自己的习惯命名，只要后面创建 Session 时能选对就行。

---

六、第四步: 创建 Session

Session 是 Agent 的一次运行实例。创建 Session 时要同时带上 agent 和 environment_id。

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\"
  }"

Session 创建后一般处于 idle 状态，真正开始执行要等你发第一条消息。

图5对应的是“创建 Session -> 发送消息 -> 接收事件”的核心链路。右侧是在线测试输入框，底部卡片区则是常见能力入口。

界面里也可以直接从会话页创建。

可能出现的问题

---

七、第五步: 发送消息并收事件流

先向 Session 发送一条用户消息：

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": "你好，告诉我你能做什么。"
          }
        ]
      }
    ]
  }'

然后用 SSE 流实时接收结果：

curl -s -N "https://api.qoder.com/api/v1/cloud/sessions/$SESSION_ID/events/stream" \
  -H "Authorization: Bearer $QODER_PAT"

常见事件包括：

• user.message
• session.status_running
• agent.thinking
• agent.message
• agent.tool_use
• agent.tool_result
• session.status_idle
• heartbeat

---

八、把页面当成操作地图看

如果你更习惯先看页面再看 API，可以按这个顺序理解：

1. 首页先选起点
2. 进入 Agent 配置页，填名称和模型
3. 进入 Environment 配置页，选环境
4. 进入 Session 页，创建会话并发第一条消息

图7是一个常见问题提示。如果在线测试区出现 You have no available credit，通常说明当前账号额度不足，需要检查套餐、配额或资源包。

---

九、常见问题

1. 401 Unauthorized

先检查 QODER_PAT 是否设置正确，是否过期。

2. 400 Bad Request

通常是 JSON 格式有问题，或者 model、tools、environment_id 传错了。

3. Session 一直是 idle

这是正常的。Session 只有在收到 user.message 后才会进入执行流程。

4. 事件流中断

可以用 Last-Event-ID 做断点续传；如果想查历史事件，再看事件列表接口。

5. 环境列表为空

新账号可能还没有预置环境，手动创建一个默认环境就行。

---

十、最小可执行顺序

你可以把整个流程记成下面这 5 条命令链：

1. export QODER_PAT="..."
2. curl GET /environments
3. curl POST /agents
4. curl POST /sessions
5. curl POST /sessions/{id}/events + curl -N /events/stream

---

十一、补充说明

• Environment 管运行空间
• Agent 管能力定义
• Session 管一次执行过程
• Event 管上下文流转

如果你只是想先跑通第一个 Demo，优先记住这条链路就够了：

先拿 PAT，再建 Environment，再建 Agent，再建 Session，最后发消息看流。