外部接入：发布服务并发送第一次请求

用途#

外部接入让业务后端通过 API 调用 Onevium 助手、延续对话，或用签名 Webhook 触发任务。入口为 「渠道 → 外部接入」 和 「接入设置」 弹窗。

左栏用于选择、搜索和筛选业务应用，右侧查看所选应用的服务与历史。接入模式、连接状态和 「接入设置」 集中在左栏底部。

发布助手服务后，再发送测试请求，确认服务能接收请求并执行任务。

截图使用隔离演示数据，展示目录、连接和草稿状态；不代表真实业务请求、公网、模型执行、MCP 或回调已连通。

放大图片从外部接入创建第一个业务应用。

开始前#

• 使用可信业务系统、适合测试的项目和已配置的模型服务商。允许修改项目之前，先了解权限边界。
• 保持 Onevium 运行、电脑处于唤醒状态。网关负责接收请求，指定的 Onevium 设备负责执行。内置接入在电脑休眠或关闭时无法接收新请求。
• 第一次使用内置接入，在同一台电脑的终端测试即可。公网、Docker 和结果回调都是可选项。

下文命令使用 Bash/zsh 与 curl 语法；Windows 可在已有的兼容终端中执行，或按相同 HTTP 方法、请求头和 JSON 实现后端调用。不要把业务应用密钥与模型服务商 API Key、私有管理令牌混用。

第一次本地测试可直接创建应用，默认的 「Onevium 内置」 无需额外设置。需要查看或更改接入方式时，再打开主页面的 「接入设置 → 连接方式」。编辑字段和切换方式只修改草稿，点击 「保存」 后才生效；「取消」 放弃未保存修改。在两种方式之间切换时，各自的草稿会保留。保存不同连接方式会暂停接入，请完成配置后再启用。保存失败时，弹窗和已填写内容会保留。

不需要服务器通知时，无需修改 「结果回调」 页签。域名名单留空表示禁止所有回调，并非不限制目标。这份名单只限制向外发送结果；业务系统调用 API 仍由应用密钥和业务用户权限控制。

第一次操作#

1. 创建应用并保管密钥

点击左栏 「新建应用」，填写容易识别的名称。一个应用代表一个业务系统，每个应用的密钥和会话相互隔离。

放大图片为一个业务系统创建独立应用。

创建后，应用密钥只展示一次。关闭弹窗前，将它保存到业务后端的凭证存储中；不要放进浏览器 JavaScript、共享截图、代码仓库或 URL 查询参数。后续创建的 API 密钥可以使用更小的操作范围。

本次目录查询、发送任务和读取结果分别需要 endpoints:read、runs:write、runs:read。使用后续创建的限权密钥时，确认具备所需范围；字段含义和密钥替换见应用密钥与权限。

2. 添加服务，完成基础配置与能力选择

选中应用，点击 「添加服务」。在 「基础配置」 中填写服务名称、选择工作目录、选择模型服务商和模型，并说明任务要求。目录和模型选择沿用聊天界面的操作方式。点击 「下一步」 进入 「能力」。

不要直接照抄截图里的 /workspace/support-demo。应使用自己的测试目录，并确认模型连接可用。

放大图片选择工作目录、模型，并说明服务要处理的任务。

新服务默认选择 「项目工具」，勾选 Read、Grep、Glob、Edit、Write。这些能力允许在服务审批规则下读取、搜索和修改项目文件；勾选工具不等于授予完全访问权限，也不会绕过审批。不需要的能力可以取消；无需访问项目文件的服务，可以使用 「仅对话」。

「执行终端命令」 对应 Bash，默认未勾选，并需要额外的沙箱能力检查。选中一项能力，并不证明当前平台和运行环境支持发布它。

放大图片默认选入五项项目文件工具；Bash 未开启，工具操作仍受审批规则约束。

3. 按需选入项目 Skills 与 MCP 工具

需要这些能力时，再展开高级 Skills 与 MCP 区域。点击 「读取项目配置」，明确读取所选项目，并将可用的项目 Skills 选入草稿。请检查列表，取消不需要的条目。发布内容只包含 SKILL.md 指令，不会导入附带脚本或个人 Skills。

放大图片读取项目配置后，检查选入的 Skills 和 MCP 服务（示例目录）。

对于符合条件的 MCP 服务，点击 「读取工具」，会连接该服务并选入可用工具；随后可以移除不应开放的工具。当前流程仅支持可发布的 HTTPS MCP 连接。发现 stdio 或 SSE 配置不表示它已经可用；不可用条目会说明限制。读取配置、发现工具和通过发布能力检查是不同步骤。

4. 保存、检查能力、发布，再启用

在服务弹窗点击 「保存」，应用页面会显示服务草稿。点击 「检查能力」 并查看结果；失败时先修正能力选择或运行环境。

放大图片保存得到服务草稿，能力检查通过后才可发布（状态示例）。

检查通过后，点击 「发布服务」，再到主页面 「启用外部接入」。已保存、通过检查、已发布、已启用是不同阶段。使用 Onevium 随后显示的 API 地址，不要用桌面应用的管理地址代替。内置接入监听 loopback；其他电脑上的客户端需要明确配置 HTTPS 访问方式，或使用可选的远端网关。

5. 复制并执行测试请求

在 「试一次请求」 区域，如果有多个已发布服务，先选择要测试的服务。展开 「发送测试请求」，点击 「复制示例」。生成的 curl 已包含当前网关地址、服务 ID、消息和所需请求头。把 YOUR_APP_KEY 替换为当前应用的密钥，再到能访问该地址的业务服务器或终端执行。

放大图片连接状态和地址为示例；复制 curl 并替换 YOUR_APP_KEY 后自行执行，复制本身不会发送请求。

如果改用下面的独立示例，先准备这些变量。界面中的 API 地址已包含 /api/v1；GATEWAY_URL 必须去掉末尾的 /api/v1，下面的命令会自行追加。

可以先查询该应用已发布的服务目录，这一步不会启动任务：

curl --fail-with-body -sS "$GATEWAY_URL/api/v1/agent-endpoints" \
  -H "Authorization: Bearer $APP_KEY" \
  -H 'X-Onevium-Subject: docs-test-user'

正常返回 200 与 endpoints 列表。列表为空时，回到所选应用检查服务是否已发布，不要拿草稿 ID 继续提交。确认目标后再发送：

curl -X POST "$GATEWAY_URL/api/v1/agent-endpoints/$ENDPOINT_ID/runs" \
  -H "Authorization: Bearer $APP_KEY" \
  -H 'X-Onevium-Subject: docs-test-user' \
  -H 'Idempotency-Key: docs-test-run-001' \
  -H 'Content-Type: application/json' \
  --data '{"input":{"text":"只回复：连接成功"}}'

应用内示例已经填好地址和服务 ID，不需要额外追加路径。「复制示例」只复制命令，不会自动执行请求。图中的「可以接入」是隔离状态示例，不能作为自己环境的连通证明。

同一次操作重试时，保持 Idempotency-Key、主体、目标和请求体不变；每次有意发起新任务时，使用新的请求标识。 原样重复执行示例，是重试原任务。X-Onevium-Subject 应由已鉴权的业务后端根据自己的用户会话填写，不要直接透传浏览器随意指定的值。

确认成功#

返回 202 和 run_id 表示请求已被接收，不表示执行成功。将返回的 ID 保存为 RUN_ID，携带相同应用凭证与主体查询：

curl "$GATEWAY_URL/api/v1/runs/$RUN_ID" \
  -H "Authorization: Bearer $APP_KEY" \
  -H 'X-Onevium-Subject: docs-test-user'

查看实际状态和结果，并在应用的 「凭证与历史」 区域核对对应记录。等待审批或核对中的任务，还没有已确认的最终结果。

先核对任务是否确实开始，再读取它的最终执行状态与公开结果。若返回失败、取消、过期或仍在等待设备，不能只因 HTTP 查询成功就展示为任务成功。已收到 run_id 后，继续查询这个 ID；不要为了查看进度再创建新任务。

需要实时观察时，可以携带相同鉴权信息，通过 GET /api/v1/runs/{run_id}/events 订阅 SSE。断开观察连接不会取消执行。需要停止或重开上下文时，使用明确的控制操作，再查询返回的控制操作记录确认完成；重开不会撤销已经发生的文件修改或其他外部操作。

停用应用与从列表移除#

不再使用某个应用时，在右侧应用标题旁点击 「停用应用」，核对应用后再确认。停用会撤销该应用的访问与密钥；已有任务仍需要完成停止和回执确认。已经处于停用中间状态的应用会显示 「完成停用」。

放大图片已停用应用保留历史入口，可从日常列表移除（示例状态）。

停用完成后，点击 「从列表移除」。弹窗会说明保留范围；选择 「取消」 不执行移除，选择 「确认移除」 后，应用不再出现在日常列表。停用未完成时，等待执行停止与回执确认后重试。

放大图片确认前说明会保留历史记录；取消不会移除应用。

需要核对旧记录时，切换左栏 「已移除」，选择应用查看历史。这里是只读视图；不会恢复已撤销的密钥，也不会重新启用服务。从列表移除不等于立即擦除历史数据：会话、执行和投递记录沿用既有保留策略。

放大图片在已移除列表查看历史，已撤销凭证不会恢复（示例状态）。

常见问题#

接下来#

下面保留常用请求结构。完整的凭证、会话控制、事件签名和部署步骤分别见密钥与权限、持续对话与运行控制、Webhook 与结果回调、远端网关。

延续业务对话

需要稳定会话时，先创建业务容器，再发送消息。将变量替换为真实的网关、服务和应用凭证：

curl "$GATEWAY_URL/api/v1/conversations" \
  -H "Authorization: Bearer $APP_KEY" \
  -H 'X-Onevium-Subject: docs-test-user' \
  -H 'Idempotency-Key: docs-create-001' \
  -H 'Content-Type: application/json' \
  --data '{"endpoint_id":"YOUR_ENDPOINT_ID","conversation_key":"docs-demo"}'

将 YOUR_ENDPOINT_ID 替换为实际服务 ID。把返回的会话 ID 保存为 CONVERSATION_ID，再发送消息：

curl "$GATEWAY_URL/api/v1/conversations/$CONVERSATION_ID/messages" \
  -H "Authorization: Bearer $APP_KEY" \
  -H 'X-Onevium-Subject: docs-test-user' \
  -H 'Idempotency-Key: docs-message-001' \
  -H 'Content-Type: application/json' \
  --data '{"expected_generation":1,"input":{"text":"只回复：连接成功"}}'

新会话从 generation 1 开始。重开上下文后，应读取实际代际，不能一直填写 1。发送失败会保留草稿；代际变化后先检查草稿。接纳响应不确定时，继续保留原执行标识。

按需使用 Webhook、结果查询、SSE 或回调

入站 Webhook 接收签名业务事件并映射为任务，在应用的 「事件与回调 → 添加 Webhook」 中配置事件筛选、字段映射和签名密钥。结果回调把所选任务事件发送给业务服务器。两者方向不同，配置也相互独立。

内置接入的回调配置位于 「接入设置 → 结果回调」：

1. 域名名单留空时禁止所有回调。填写精确域名，多个域名以逗号分隔，再 「保存」；不要包含完整 URL、端口、IP 地址或通配符。
2. 为应用添加实际的 HTTPS 回调地址、签名密钥和所需事件。
3. 单独查看投递记录。只有目标返回 2xx 才确认送达，接收方应按事件 ID 对重复投递去重。

回调当前仅支持公网 HTTPS 目标。即使域名在名单中，localhost、loopback 和局域网仍会被拒绝。本地业务客户端可以查询结果或订阅 SSE，无需启用回调。远端网关的回调域名名单在该服务器上配置。

按需部署远端网关

使用与你的 Onevium 版本匹配的网关部署包；本教程不提供公开服务器镜像的下载链接。Docker 和公网访问都是可选项。常驻网关可以在桌面离线时接收任务，但执行仍要求指定的 Onevium 设备重新连接并保持唤醒。

1. 在 「接入设置 → 连接方式」 选择 「远端网关」 并填写 HTTPS 地址。自建服务器时，展开 「远端高级设置」，选择 「通过 SSH 私有连接」。先 「保存」，再导出或配对；这两项操作不会暗中保存字段或切换方式。
2. 「导出设备公钥」 下载的是公钥身份文件，用它初始化匹配版本的网关部署包。私钥留在 Onevium。
3. 配置网关私有管理 socket，通过已鉴权的 SSH 连接，转发到明确的本机地址，例如 http://127.0.0.1:8430。保持 SSH 主机验证开启。填写该地址和私有控制令牌，再 「保存」；已保存令牌的输入框留空会保留原值。
4. 网关和隧道准备好后，点击 「配对此设备」，再完成服务发布和启用。「使用账户认证的托管网关」 适用于兼容的托管服务，不能代替自建网关的私有控制通道。

公网 HTTPS 代理只能转发独立接入网关的监听端口，不能暴露 Onevium 管理端口或私有管理 socket。请在实际使用的环境中，分别核对网络可达性、配对、能力检查、模型真实执行及所需回调目标。

相关产品边界见团队渠道、权限和设置与数据。