Orlo 使用指南：首次任务、API 接入与部署核验

更新于 2026-11-02 · wj-kc.top

简答：先确认你使用的是 docs.useorlo.com 对应的 Orlo AI 平台，而不是同名的社媒管理或文档工具；官方入口通常会出现 Tasks、Agent、Skills、API 或 Operate 等路径。新手最短流程是：注册或接受邀请→确认工作区权限→添加并测试模型提供商密钥→用 Support ticket routing 示例完成比较→发布可用版本→发送一次测试请求。若你遇到连不上、401、403、429 或超时，先保留任务 ID、trace ID 和错误信息，再区分账号权限、Orlo API、模型提供商与本地网络问题。

定义：如果你指的是 docs.useorlo.com 上的 Orlo，它是一个将 AI 任务、模型比较、发布版本、答案校验、Agent 工具权限和共享技能连接起来的平台。

先确认产品与入口：你说的 Orlo 是哪个？

“Orlo”可能指向多个不同产品，不能只凭名称判断。本文仅覆盖 docs.useorlo.com 上的 Orlo AI 平台；如果你的页面没有任务、Agent、Skills、API 或 Operate 等相关入口，先不要照搬本文的菜单和接口。

识别时优先核对三项：第一，页面域名是否与组织管理员提供的入口一致；第二，是否能看到工作区、任务或 Agent 相关内容；第三，文档是否明确写出 Orlo、runtime key、provider credentials 或 release。无法互相印证域名、账户和组织归属时，停止下载、付款或导入配置，先向管理员或产品提供方核实。

你的目标	应选择的路径	开始前需要	完成标准
第一次体验 AI 任务	Test an AI task	工作区、管理员权限、模型提供商凭证	看到返回答案并完成一次可检查的比较
让应用调用任务	Task API 或 OpenAI-compatible endpoint	已发布版本、runtime key、`inference.run`	收到完整答案并保存验证结果与 trace ID
治理 Agent 工具动作	Connect an agent	Agent SDK、任务标识、runtime key	能复现工具被阻止、允许或进入审批的结果
自己部署平台	Operate Orlo	授权部署包、HTTPS、持久化存储、密钥和备份方案	非生产环境完成登录、邀请、密钥、任务和恢复验证

新手只需先完成 5 步：确认入口；加入或创建工作区；让管理员配置提供商密钥；跑通内置示例；确认实际返回答案后再接入自己的数据。

首次上手：用内置任务跑通最小闭环

官方首次任务流程使用 Support ticket routing starter。页面说明该流程需要组织管理员权限和模型提供商密钥，比较与实时请求可能产生提供商费用；因此应先用少量、非敏感的测试输入验证链路，不要直接上传生产数据。具体路径见 How do I get my first checked task answer?。

创建或加入工作区。官方注册页说明，可通过 https://app.useorlo.com 注册，或接受组织邀请。创建者会成为组织所有者；被邀请成员的访问范围取决于组织设置。
确认人员权限。控制台登录和应用调用不是同一套凭据。管理员可以管理任务、比较、发布、提供商密钥和 runtime key；受限成员只能使用被授予的预设权限。访问范围可参考组织成员权限说明。
添加并测试提供商密钥。管理员在当前控制台的 Settings → Keys 区域添加凭证并执行 Test key。已保存的密钥或已列出的模型，并不等于仍有额度，也不保证真实请求成功。
打开示例任务。官方页面给出的路径是 Tasks → New task → Start with an example → Support ticket routing。菜单可能随控制台调整，若页面不同，以当前界面为准。
比较并检查结果。至少阅读一个实际返回答案、预期答案和已执行的检查。官方说明，评分和置信区间只描述当前示例集；区间重叠时，不能直接认定某个模型明显胜出。
发布后再测试。完成比较后选择合适候选并创建可用发布版本，再发送测试请求。排队中的比较、全部失败的比较或只有部分结果的比较，都不足以证明适合生产使用。

成功标准不是“按钮显示完成”，而是你能看到真实答案、验证状态和可追踪记录。如果没有任何模型返回答案，先阅读失败信息，修复提供商访问或请求兼容性，再重新比较。

API 接入：任务接口与兼容接口怎么选？

应用和 Agent SDK 使用 runtime key 调用 https://api.useorlo.com。官方建议将密钥保存在服务端或 Agent 运行环境，不要放进前端公开代码、普通浏览器包、截图或公开日志。认证与 scope 规则见 Orlo 应用认证说明。

方式	适合场景	官方已核实的要点
`POST /v1/tasks/:id/run`	结构化输入、任务字段、明确的发布版本	需要 `inference.run`；返回完整答案和验证结果；不提供 token streaming
`POST /v1/chat/completions`	复用 OpenAI 风格客户端发送文本消息	需要 `X-Orlo-Task-Id`；请求体中的 `model` 不负责选择模型；必须使用非流式文本请求
Agent SDK	模型调用仍由现有应用负责，只让 Orlo 检查工具动作	应用保留原有模型连接；Orlo 在工具执行前提供权限判断和记录

任务接口的官方示例是向 /v1/tasks/:id/run 发送 JSON 输入，并使用 Bearer runtime key。返回内容包含 output、validation 和 trace_id 等字段；其中 output 即使包含 JSON，也可能以字符串形式返回，应用应先检查 HTTP 状态和验证结果，再解析内容。详情见 Run a task。

兼容接口要求提供 X-Orlo-Task-Id，成功响应会通过响应头提供模型、追踪 ID、验证状态、任务版本和路由模式。官方明确说明，该接口不是完整的 OpenAI API；多模态消息、工具编排、Responses API 和流式请求不属于当前兼容契约。发送 stream: true 会在模型调用前返回 400 INVALID_INPUT。可参考 OpenAI-compatible clients。

如果你的应用必须逐 token 输出，应保留应用自身的模型调用，再通过 Agent SDK 检查工具动作；不要把任务接口误当作流式模型网关。

部署 Orlo：托管调用和自部署要分开

“部署 Orlo”有两种含义：把已经发布的任务接入应用，或把 Orlo 平台安装到自己的环境。前者主要关注 API 地址、runtime key、任务发布版本和网络连通性；后者还涉及授权部署包、存储、密钥、备份、升级、恢复和运维责任。

公开部署文档没有提供一套适用于所有环境的固定镜像名、版本号或安装命令，因此这些信息不能凭经验补写。官方要求使用与当前发布版本匹配的授权部署包，并依据该版本专属说明配置。可核对自有环境部署前置条件和 Operate Orlo。

自部署前置条件

控制台和 API 都有明确的 HTTPS 地址。
有受保护的密钥存储和备份流程。
任务历史、示例和上传来源使用持久化存储。
模型提供商访问路径已确认。
如果需要邀请或审批通知，准备邮件投递能力。
如果接入 AI 应用或连接器，准备可从外部访问的连接器地址；不要把本机 localhost 当成托管连接器地址。
明确负责安装、升级、故障恢复和数据保留的人员。

上线前验证顺序

按当前发布包通过健康检查。
登录控制台并创建或进入目标组织。
邀请一名测试成员，确认邀请和权限生效。
添加并测试提供商密钥。
比较一个 starter task 并发送一次实时请求。
如果使用 Agent，执行连接检查；如果启用连接器，验证技能能被 AI 应用检索。
确认通知到达，并实际验证备份恢复流程。

升级时应先阅读发布说明，在独立环境测试，备份数据和必要密钥，再使用匹配的应用镜像、迁移配置与回滚说明。API、网关、worker 和 console 应保持兼容版本；具体升级命令以当前发布资料为准。

连接与错误排查：先保存证据，再判断是不是网络问题

Orlo 请求失败不一定是 DNS、延迟或丢包造成的。先从受影响的任务、运行或连接消息开始，保存任务 ID、运行 ID、trace ID、时间、HTTP 状态和错误文本；不要提交 runtime key、模型提供商密钥或完整敏感输入。官方排错入口见 Troubleshooting。

现象	优先检查	回退动作
没有提供商密钥	管理员是否在 Settings → Keys 添加并测试	返回保存的任务，完成密钥测试后再比较
密钥被拒绝或模型未列出	提供商账户、密钥和模型访问权限	修复提供商访问，再重新执行 Test key
所有比较样本失败	失败样本中的提供商错误、模型可用性和请求格式	没有实际答案时不要解释质量分数
401 或 403	Bearer key、scope、组织归属和是否属于人员专属操作	检查服务端变量；由管理员调整最小权限，不要盲目重试
429 或服务繁忙	`Retry-After`、并发量和应用截止时间	使用有上限的退避和抖动，避免重试放大负载
跨网络超时	DNS 解析、HTTPS 握手、出口策略和请求耗时	用同一设备对比办公网、家庭网或手机热点；只有出现分片或连接重置证据时再考虑 MTU

网络排查建议保持低风险：一次只改变一个变量，先做同一请求的网络对照，再判断是本地网络、Orlo 网关、权限、发布版本还是上游提供商。浏览器能打开控制台，也不能自动证明服务器、命令行或桌面客户端可以访问 API。

如果不同网络都失败，优先回到密钥、scope、任务发布、模型访问和服务状态；如果只有某个网络失败，再记录 DNS、TLS、延迟、丢包和代理路径。不要把改变 MTU、重装客户端或更换 DNS 当作第一步。

FAQ：Orlo 使用中最容易混淆的几个问题

Orlo 新手应该先做什么？

先确认你打开的是 docs.useorlo.com 对应的 AI 平台，再创建或加入工作区，确认管理员权限，配置并测试提供商密钥，使用内置 Support ticket routing 示例完成一次比较。看到实际返回答案后，再准备自己的数据或 API 接入。

登录密码、提供商密钥和 runtime key 有什么区别？

登录密码用于人员进入控制台；提供商密钥用于 Orlo 代表组织调用模型；runtime key 用于应用或 Agent 调用 Orlo API，并通过 scope 限制可执行的操作。三者不能互相替代，也不应放在同一处公开保存。

模型已经显示在列表中，为什么请求仍然失败？

官方说明，“模型已由提供商列出”不等于剩余额度充足，也不保证真实调用成功。应重新测试提供商密钥，检查模型是否仍可用、账户是否有额度，以及请求格式是否符合当前接口要求。

OpenAI-compatible 接口支持流式输出吗？

当前公开文档说明该接口使用非流式文本消息；stream: true 会返回输入错误。需要原生 token streaming 的 Agent，应保留应用自身的模型调用，并将 Orlo 放在工具权限检查位置。

自部署时最不能省略哪一步？

不要只验证页面能打开。至少还要验证登录、邀请、提供商密钥、starter task、实时请求、Agent 连接检查或技能检索，以及备份恢复。没有对应发布版本的安装、迁移和回滚说明时，不要直接接入生产流量。

Orlo 连接超时，应该先改 DNS 还是 MTU？

两者都不要立即修改。先记录 DNS 解析、HTTPS 握手、HTTP 状态、请求耗时和跨网络复现结果；只有存在分片异常或连接反复重置等证据时，才把 MTU作为后续假设。所有网络都失败时，应优先检查权限、发布版本、提供商凭证和服务状态。

常见问题

Orlo 新手第一次应该从哪里开始？

先核对是否为 docs.useorlo.com 上的 Orlo AI 平台，再创建或加入工作区，确认管理员权限，配置提供商密钥，用内置 Support ticket routing 示例完成比较和测试请求。

runtime key 和登录密码有什么区别？

登录密码用于人员进入控制台；runtime key 用于应用或 Agent 调用 API，并携带独立 scope。不要把 runtime key 放入前端代码或公开日志。

为什么模型已列出但请求仍然失败？

模型列表只说明提供商列出了该模型，不代表额度、密钥和真实调用都正常。请重新测试提供商密钥并检查模型访问和请求格式。

Orlo 的 OpenAI-compatible 接口支持流式输出吗？

当前公开文档要求使用非流式文本消息；发送 stream: true 会返回输入错误。需要流式输出时，应保留应用自身的模型调用。

Orlo 自部署前要准备什么？

准备匹配发布版本的授权部署包、HTTPS 地址、持久化存储、受保护的密钥、备份流程、提供商访问、必要的邮件投递和运维负责人。

连接超时应该先改 DNS 还是 MTU？

先记录 DNS、TLS、HTTP 状态、耗时和跨网络结果，不要同时修改多个变量。只有出现分片异常或连接重置等证据时，才进一步检查 MTU。