> 内容来源：Onevium 官方文档
> 文章: 外部接入：发布服务并发送第一次请求（预览）
> 原文: https://onevium.com/zh/docs/developers/external-access
> 语言：简体中文
> 更新于: 2026-09-09
> 适用版本: 1.1.23-beta.7
> 功能状态: 开发预览

---

# 外部接入：发布服务并发送第一次请求（预览）

在预览构建中创建应用和助手服务、发送测试请求，并选择结果查询、SSE 或公网 HTTPS 回调。

## 用途

外部接入让业务后端通过 API 调用 Onevium 助手、延续对话，或用签名 Webhook 触发任务。本教程对应包含\*\*「渠道 → 外部接入」**和**「接入设置」\*\*弹窗的 **1.1.23 系列新版开发预览交互**。网站当前展示的稳定版仍为 **1.1.22**，并非所有正式版安装都已具备这些界面。如果找不到入口，请先确认当前预览构建是否包含这套流程。

发布助手服务，是让这项配置好的服务可以被调用；不等于发布桌面正式版本，也不代表生产验收通过。真实公网和生产业务验证仍需单独完成。

本文截图直接捕获开发预览的真实组件，使用隔离演示数据。图中的目录、连接和草稿状态仅用于说明步骤，没有发送真实业务请求，也没有验证公网、模型执行、MCP 或回调投递。

![从外部接入创建第一个业务应用。](https://onevium.com/docs/external-access/c2409f75f/zh/01-start.png "从外部接入创建第一个业务应用。")

## 开始前

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

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

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

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

## 第一次操作

### 1. 创建应用并保管密钥

点击\*\*「创建第一个应用」\*\*，填写容易识别的名称，例如「客服工单系统」。一个应用代表一个业务系统，拥有独立的凭证和会话。

![为一个业务系统创建独立应用。](https://onevium.com/docs/external-access/c2409f75f/zh/03-create-application.png "为一个业务系统创建独立应用。")

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

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

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

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

| 字段   | 如何填写                                              |
| ---- | ------------------------------------------------- |
| 服务名称 | 例如「工单分析助手」，用于区分同一应用中的不同服务                         |
| 工作目录 | 选择运行 Onevium 的设备上真实存在的项目；不是调用方服务器的目录              |
| 模型   | 选择已配置、账户可使用的服务商和模型；截图中的 Opus 5 仅作示例               |
| 任务说明 | 固定这项服务要完成的任务，例如分析工单并给出处理建议；调用方随后通过 `input` 提供业务内容 |

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

![选择工作目录、模型，并说明服务要处理的任务。](https://onevium.com/docs/external-access/c2409f75f/zh/04-service-basics.png "选择工作目录、模型，并说明服务要处理的任务。")

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

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

![默认选入五项项目文件工具；Bash 未开启，工具操作仍受审批规则约束。](https://onevium.com/docs/external-access/c2409f75f/zh/05-service-capabilities.png "默认选入五项项目文件工具；Bash 未开启，工具操作仍受审批规则约束。")

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

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

![读取项目配置后，检查选入的 Skills 和 MCP 服务（示例目录）。](https://onevium.com/docs/external-access/c2409f75f/zh/06-project-skills.png "读取项目配置后，检查选入的 Skills 和 MCP 服务（示例目录）。")

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

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

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

![保存得到服务草稿，能力检查通过后才可发布（状态示例）。](https://onevium.com/docs/external-access/c2409f75f/zh/08-service-draft.png "保存得到服务草稿，能力检查通过后才可发布（状态示例）。")

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

### 5. 复制并执行测试请求

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

![连接状态和地址为示例；复制 curl 并替换 YOUR\_APP\_KEY 后自行执行，复制本身不会发送请求。](https://onevium.com/docs/external-access/c2409f75f/zh/09-request-example.png "连接状态和地址为示例；复制 curl 并替换 YOUR_APP_KEY 后自行执行，复制本身不会发送请求。")

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

| 变量            | 取值来源                                                              |
| ------------- | ----------------------------------------------------------------- |
| `GATEWAY_URL` | 当前 API 地址去掉末尾 `/api/v1`；截图中的 `http://127.0.0.1:48541` 仅是示例，不是固定端口 |
| `ENDPOINT_ID` | 已发布服务的标识，可从应用内生成的请求路径或服务目录取得，不是应用 ID                              |
| `APP_KEY`     | 当前业务应用的有效密钥，由后端凭证存储提供                                             |

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

```bash
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 继续提交。确认目标后再发送：

```bash
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`，携带相同应用凭证与主体查询：

```bash
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。断开观察连接不会取消执行。需要停止或重开上下文时，使用明确的控制操作，再查询返回的控制操作记录确认完成；重开不会撤销已经发生的文件修改或其他外部操作。

## 常见问题

| 现象                 | 检查方向                                        |
| ------------------ | ------------------------------------------- |
| 找不到入口              | 确认安装的预览构建包含外部接入；本教程不改变稳定版 1.1.22 的功能可用范围。   |
| 服务一直是草稿            | 保存配置、检查能力、通过后发布；启用接入是独立步骤。                  |
| 能力检查失败             | 查看具体限制，减少能力选择或修正支持的运行环境，不要绕过发布检查。           |
| 返回 401 或 403       | 检查应用密钥、scope、主体处理方式和服务授权。                   |
| 返回 409             | 检查会话 generation、忙碌状态，以及同一请求标识是否被用于不同正文。     |
| 已接收但未完成            | 检查指定设备是否连接且保持唤醒，再看审批和任务状态；查询或重试原操作，避免制造新执行。 |
| 设置保存失败             | 保留草稿，修正错误后重试。已保存私有管理令牌的输入框留空，会保留原密钥。        |
| localhost 或局域网回调失败 | 当前不支持这些回调目标；本地客户端可查询结果或订阅 SSE。              |

## 接下来

下面保留常用请求结构。完整的凭证、会话控制、事件签名和部署步骤分别见[密钥与权限](https://onevium.com/zh/docs/developers/authentication)、[持续对话与运行控制](https://onevium.com/zh/docs/developers/conversations)、[Webhook 与结果回调](https://onevium.com/zh/docs/developers/webhooks)、[远端网关](https://onevium.com/zh/docs/developers/remote-gateway)。

### 延续业务对话

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

```bash
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`，再发送消息：

```bash
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。请在实际使用的环境中，分别核对网络可达性、配对、能力检查、模型真实执行及所需回调目标。

相关产品边界见[团队渠道](https://onevium.com/zh/docs/team-channels)、[权限](https://onevium.com/zh/docs/permissions)和[设置与数据](https://onevium.com/zh/docs/settings-and-data)。