Qoder Cloud Agents 使用说明

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

对应关系如下：

图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也很方便：

wingetinstalljqlang.jq

三、第一步: 获取 PAT

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

示例:

exportQODER_PAT="your-personal-access-token"

PowerShell 示例:

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

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

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

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

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

curl-s-XPOST 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-XPOST 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-XPOST 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-XPOST"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.exportQODER_PAT="..."2.curlGET /environments3.curlPOST /agents4.curlPOST /sessions5.curlPOST /sessions/{id}/events +curl-N/events/stream

十一、补充说明

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

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

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