---
title: "harness - OpenAPI 业务接口接入"
---


Harness 可以把 OpenAPI v2 / v3 文档描述的 HTTP 接口接入为 Agent 工具。需要区分两个概念：

- `apiServerAdd(name, source)` 的 `name` 是 Harness 构建期配置 Map 的键；
- `ApiSource.docUrl` 是 `OpenApiGatewayTalent` 的运行时管理键。

### 1、开启 OpenAPI 工具权限

当前工具权限枚举是 `ToolName.TOOL_OPENAPI`，实际工具名为 `openapi`：

```java
HarnessEngine engine = HarnessEngine.of("work", ".soloncode/")
        .sessionProvider(sessionProvider)
        .toolsAdd(ToolName.TOOL_OPENAPI)
        .build();

// 运行时动态授权
engine.allowTool("openapi");
```

新代码不要再使用旧的 REST API 工具枚举；`AgentFactory` 仍兼容旧字符串 `restapi`，但推荐统一使用 `ToolName.TOOL_OPENAPI` 或字符串 `openapi`。

### 2、构建期静态注册

```java
ApiSource source = new ApiSource().then(api -> {
    api.setDocUrl("https://api.example.com/v3/api-docs");
    api.setApiBaseUrl("https://api.example.com");
});

HarnessEngine engine = HarnessEngine.of("work", ".soloncode/")
        .sessionProvider(sessionProvider)
        .toolsAdd(ToolName.TOOL_OPENAPI)
        .apiServerAdd("orders", source)
        .build();
```

这里的 `"orders"` 只作为 `HarnessOptions.apiServers` 配置 Map 的键。引擎构建 `OpenApiGatewayTalent` 时遍历 Map 的 value，并通过 `source.getDocUrl()` 注册运行时 API 源；配置键 `orders` 不会传给网关，也不是 Agent 工具名。

因此，运行时查询、刷新和移除必须传 `docUrl`，不能传 `orders`：

```java
String docUrl = "https://api.example.com/v3/api-docs";

ApiSourceClient client = engine.getApiServer(docUrl);
engine.refreshApiServer(docUrl);
engine.removeApiServer(docUrl);
```

### 3、ApiSource 配置

```java
ApiSource source = new ApiSource();
source.setDocUrl("https://api.example.com/v3/api-docs");
source.setApiBaseUrl("https://api.example.com");
source.addHeaderVar("Authorization", "Bearer ${token}");
source.addAllowedTool("getOrder");
source.addDisallowedTool("deleteOrder");
source.setTimeout(Duration.ofSeconds(30));
source.setAuthenticator(authenticator);
source.setEnabled(true);
```

主要字段：

| 字段 | 说明 |
|---|---|
| `docUrl` | OpenAPI 文档地址；也是网关运行时 API 源键 |
| `apiBaseUrl` | 实际业务接口基地址，可覆盖文档中的 server 地址 |
| `headers` | 获取文档或调用接口时使用的请求头，可用 `addHeaderVar` 追加 |
| `allowedTools` | 工具白名单；为空时不按白名单限制 |
| `disallowedTools` | 工具黑名单，从候选接口中排除 |
| `timeout` | HTTP 请求超时，类型为 `Duration` |
| `authenticator` | 自定义 `ApiAuthenticator` |
| `enabled` | 是否把该源的工具加入激活索引，默认 `true` |

`allowedTools` / `disallowedTools` 用于裁剪最终激活的接口工具。修改运行时 Client 的过滤配置后，应刷新对应 `docUrl`，使网关工具索引重新同步。

### 4、运行时动态管理

```java
ApiSource source = new ApiSource();
source.setDocUrl("https://api.example.com/v3/api-docs");
source.setApiBaseUrl("https://api.example.com");

// 运行时添加：docUrl 同时作为网关运行键和 Harness 配置 Map 键
engine.addApiServer(source);

String docUrl = source.getDocUrl();
ApiSourceClient client = engine.getApiServer(docUrl);
engine.refreshApiServer(docUrl);
engine.removeApiServer(docUrl);
```

运行时 API 的键语义如下：

| API | 使用的键 |
|---|---|
| `Builder.apiServerAdd(name, source)` | `name` 写入 Harness 配置 Map；网关仍以 `source.docUrl` 注册 |
| `engine.addApiServer(source)` | `source.docUrl` 同时写入配置 Map 和网关 |
| `engine.getApiServer(docUrl)` | 网关运行时 `docUrl` |
| `engine.refreshApiServer(docUrl)` | 网关运行时 `docUrl` |
| `engine.removeApiServer(docUrl)` | 按 `docUrl` 移除网关项，并尝试移除同键配置项 |
| `engine.getApiServers()` | 返回 Harness 配置 `Map<String, ApiSource>` |

这意味着 `engine.getApiServers()` 的 Map 键取决于注册入口：

- 构建期 `.apiServerAdd("orders", source)` 的键是 `orders`；
- 运行时 `engine.addApiServer(source)` 的键是 `source.getDocUrl()`。

还要注意：如果构建期配置键 `orders` 与 `docUrl` 不同，`removeApiServer(docUrl)` 能移除网关运行项，但配置 Map 中的 `orders` 项不是同一个键。不要把配置 Map 的 `name` 与网关运行时 `docUrl` 混为一谈。

### 5、查看与刷新接口工具

```java
String docUrl = "https://api.example.com/v3/api-docs";
ApiSourceClient client = engine.getApiServer(docUrl);

client.getTools();           // 文档解析出的全部接口工具
client.getToolsActivated();  // 经允许/禁用列表裁剪后的激活工具

client.setAllowedTools(Arrays.asList("getOrder", "listOrders"));
client.setDisallowedTools(Collections.singletonList("deleteOrder"));
engine.refreshApiServer(docUrl);
```

`ApiSourceClient` 的运行时过滤配置与网关全局工具索引是两个层次；调整允许/禁用列表后调用 `refreshApiServer(docUrl)`，才能把变化同步到后续 Agent 工具选择中。

### 6、说明

- OpenAPI 私域工具权限使用 `ToolName.TOOL_OPENAPI`，实际工具名为 `openapi`。
- `apiServerAdd(name, source)` 的 `name` 是构建期配置键；运行时管理 API 一律使用 `docUrl`。
- OpenAPI 工具由 `OpenApiGatewayTalent` 管理，重试次数由 `apiRetries` 控制，默认 3。
- MCP 接入见 [《harness - MCP 服务接入》](/article/1433)，LSP 接入见 [《harness - LSP 服务接入》](/article/1438)。