跳转到主要内容

Documentation Index

Fetch the complete documentation index at: https://docs.qoder.com/llms.txt

Use this file to discover all available pages before exploring further.

Qoder Cloud Agents API 使用 PAT（Personal Access Token，个人访问令牌） 进行身份认证。所有 API 请求必须在 HTTP 头中携带有效的 PAT。

​
PAT 获取方式

  1. 登录 Qoder 控制台
  2. 进入 设置 → API 令牌 页面
  3. 点击 创建令牌，设置名称与权限范围
  4. 复制生成的令牌（仅显示一次，请妥善保存）
PAT 以 pt- 前缀开头，格式如 pt-your-token-here。请勿将令牌提交到代码仓库或公开分享。

​
Bearer 头格式

在每个请求的 Authorization 头中以 Bearer 方式传递 PAT： 
Authorization: Bearer pt-your-token-here
完整请求示例： 
# 获取 Agent 列表
curl -s "https://openapi.qoder.sh/api/v1/cloud/agents" \
  -H "Authorization: Bearer $QODER_PAT"

​
环境变量配置（推荐）

建议将 PAT 存储为环境变量，避免硬编码： 
# 在 ~/.bashrc 或 ~/.zshrc 中添加
export QODER_PAT="pt-your-token-here"

# 验证配置是否生效
curl -s "https://openapi.qoder.sh/api/v1/cloud/agents?limit=1" \
  -H "Authorization: Bearer $QODER_PAT"

​
与 x-api-key 的区别

方式头部格式适用场景
Bearer TokenAuthorization: Bearer <PAT>推荐方式，用于所有 Cloud Agents API 调用
x-api-keyx-api-key: <key>旧版或第三方集成场景，Cloud Agents API 不支持
Cloud Agents API 仅接受 Authorization: Bearer 方式。使用 x-api-key 头会返回 401 authentication_error。

​
认证失败排查

​
常见错误

HTTP 状态码错误类型可能原因
401authentication_errorPAT 无效、已过期或格式错误
403permission_errorPAT 有效但无权访问目标资源

​
401 错误响应示例

{
  "type": "error",
  "error": {
    "type": "authentication_error",
    "message": "Invalid API key or token."
  }
}

​
排查步骤

  1. 确认 PAT 未过期或被撤销
  2. 检查是否误用了 x-api-key 头
  3. 确认 Bearer 前缀拼写正确（注意大小写与空格）
  4. 验证环境变量是否正确导出
# 快速诊断：打印当前 PAT 前几位确认已加载
echo "${QODER_PAT:0:8}..."

​
安全建议

  • 为不同环境（开发/测试/生产）创建独立 PAT
  • 定期轮换令牌
  • 使用最小权限原则分配令牌范围
  • 发现泄露时立即在控制台撤销