chore(i18n): refresh zh-CN translations
This commit is contained in:
openclaw-docs-i18n[bot]
parent
4070588ce9
commit
dfa4120973
File diff suppressed because it is too large
Load Diff
@ -1,28 +1,28 @@
|
||||
---
|
||||
read_when:
|
||||
- 你需要从插件调用核心辅助函数（TTS、STT、图像生成、Web 搜索、子智能体、节点）
|
||||
- 你需要在插件中调用核心辅助函数（TTS、STT、图像生成、Web 搜索、子智能体、节点）
|
||||
- 你想了解 api.runtime 暴露了什么
|
||||
- 你正在从插件代码访问配置、智能体或媒体辅助工具
|
||||
- 你正在从插件代码访问配置、智能体或媒体辅助函数
|
||||
sidebarTitle: Runtime helpers
|
||||
summary: api.runtime -- 可供插件使用的注入式运行时辅助工具
|
||||
title: 插件运行时辅助工具
|
||||
x-i18n:
|
||||
generated_at: "2026-05-04T08:24:36Z"
|
||||
generated_at: "2026-05-06T16:28:32Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: c968f30052ecba4359bdaa9b1c640c1220268933ce01ccef06bcade225b50b7d
|
||||
source_hash: 2ce16325613efc07bccb8baee3fdb46eb28452b760a6c265d3a25d36bfcbcf0f
|
||||
source_path: plugins/sdk-runtime.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
Reference for the `api.runtime` object injected into every plugin during registration. Use these helpers instead of importing host internals directly.
|
||||
这是在注册期间注入到每个插件中的 `api.runtime` 对象参考。请使用这些辅助函数，而不是直接导入主机内部机制。
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Channel plugins" href="/zh-CN/plugins/sdk-channel-plugins">
|
||||
Step-by-step guide that uses these helpers in context for channel plugins.
|
||||
<Card title="渠道插件" href="/zh-CN/plugins/sdk-channel-plugins">
|
||||
分步指南，展示在渠道插件上下文中如何使用这些辅助函数。
|
||||
</Card>
|
||||
<Card title="Provider plugins" href="/zh-CN/plugins/sdk-provider-plugins">
|
||||
Step-by-step guide that uses these helpers in context for provider plugins.
|
||||
<Card title="提供商插件" href="/zh-CN/plugins/sdk-provider-plugins">
|
||||
分步指南，展示在提供商插件上下文中如何使用这些辅助函数。
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
@ -32,40 +32,40 @@ register(api) {
|
||||
}
|
||||
```
|
||||
|
||||
## Config Loading And Writes
|
||||
## 配置加载和写入
|
||||
|
||||
Prefer config that was already passed into the active call path, for example `api.config` during registration or a `cfg` argument on channel/provider callbacks. This keeps one process snapshot flowing through the work instead of reparsing config on hot paths.
|
||||
优先使用已经传入当前调用路径的配置，例如注册期间的 `api.config`，或渠道/提供商回调中的 `cfg` 参数。这样可以让一个进程快照贯穿整个工作流，而不是在热路径上重新解析配置。
|
||||
|
||||
Use `api.runtime.config.current()` only when a long-lived handler needs the current process snapshot and no config was passed to that function. The returned value is readonly; clone or use a mutation helper before editing.
|
||||
仅当长生命周期处理程序需要当前进程快照，并且没有向该函数传入配置时，才使用 `api.runtime.config.current()`。返回值是只读的；编辑前请克隆或使用变更辅助函数。
|
||||
|
||||
Tool factories receive `ctx.runtimeConfig` plus `ctx.getRuntimeConfig()`. Use the getter inside a long-lived tool's `execute` callback when config can change after the tool definition was created.
|
||||
工具工厂会收到 `ctx.runtimeConfig` 和 `ctx.getRuntimeConfig()`。当配置可能在工具定义创建后发生变化时，请在长生命周期工具的 `execute` 回调中使用该 getter。
|
||||
|
||||
Persist changes with `api.runtime.config.mutateConfigFile(...)` or `api.runtime.config.replaceConfigFile(...)`. Each write must choose an explicit `afterWrite` policy:
|
||||
使用 `api.runtime.config.mutateConfigFile(...)` 或 `api.runtime.config.replaceConfigFile(...)` 持久化更改。每次写入都必须选择明确的 `afterWrite` 策略：
|
||||
|
||||
- `afterWrite: { mode: "auto" }` lets the gateway reload planner decide.
|
||||
- `afterWrite: { mode: "restart", reason: "..." }` forces a clean restart when the writer knows hot reload is unsafe.
|
||||
- `afterWrite: { mode: "none", reason: "..." }` suppresses automatic reload/restart only when the caller owns the follow-up.
|
||||
- `afterWrite: { mode: "auto" }` 让 Gateway 网关的重新加载规划器决定。
|
||||
- `afterWrite: { mode: "restart", reason: "..." }` 在写入方知道热重载不安全时强制干净重启。
|
||||
- `afterWrite: { mode: "none", reason: "..." }` 仅当调用方自行负责后续操作时，才抑制自动重新加载/重启。
|
||||
|
||||
The mutation helpers return `afterWrite` plus a typed `followUp` summary so callers can log or test whether they requested a restart. The gateway still owns when that restart actually happens.
|
||||
变更辅助函数会返回 `afterWrite` 以及带类型的 `followUp` 摘要，以便调用方记录或测试它们是否请求了重启。Gateway 网关仍然负责决定重启实际发生的时机。
|
||||
|
||||
`api.runtime.config.loadConfig()` and `api.runtime.config.writeConfigFile(...)` are deprecated compatibility helpers under `runtime-config-load-write`. They warn once at runtime, and remain available for old external plugins during the migration window. Bundled plugins must not use them; the config boundary guards fail if plugin code calls them or imports those helpers from plugin SDK subpaths.
|
||||
`api.runtime.config.loadConfig()` 和 `api.runtime.config.writeConfigFile(...)` 是 `runtime-config-load-write` 下已弃用的兼容性辅助函数。它们会在运行时警告一次，并在迁移窗口期间继续供旧的外部插件使用。内置插件不得使用它们；如果插件代码调用它们，或从插件 SDK 子路径导入这些辅助函数，配置边界保护会失败。
|
||||
|
||||
For direct SDK imports, use the focused config subpaths instead of the broad
|
||||
`openclaw/plugin-sdk/config-runtime` compatibility barrel: `config-types` for
|
||||
types, `plugin-config-runtime` for already-loaded config assertions and plugin
|
||||
entry lookup, `runtime-config-snapshot` for current process snapshots, and
|
||||
`config-mutation` for writes. Bundled plugin tests should mock these focused
|
||||
subpaths directly instead of mocking the broad compatibility barrel.
|
||||
对于直接 SDK 导入，请使用聚焦的配置子路径，而不是宽泛的
|
||||
`openclaw/plugin-sdk/config-runtime` 兼容性 barrel：`config-types` 用于
|
||||
类型，`plugin-config-runtime` 用于已加载配置断言和插件
|
||||
入口查找，`runtime-config-snapshot` 用于当前进程快照，以及
|
||||
`config-mutation` 用于写入。内置插件测试应直接 mock 这些聚焦的
|
||||
子路径，而不是 mock 宽泛的兼容性 barrel。
|
||||
|
||||
Internal OpenClaw runtime code has the same direction: load config once at the CLI, gateway, or process boundary, then pass that value through. Successful mutation writes refresh the process runtime snapshot and advance its internal revision; long-lived caches should key off the runtime-owned cache key instead of serializing config locally. Long-lived runtime modules have a zero-tolerance scanner for ambient `loadConfig()` calls; use a passed `cfg`, a request `context.getRuntimeConfig()`, or `getRuntimeConfig()` at an explicit process boundary.
|
||||
OpenClaw 内部运行时代码也遵循相同方向：在 CLI、Gateway 网关或进程边界加载一次配置，然后传递该值。成功的变更写入会刷新进程运行时快照并推进其内部修订；长生命周期缓存应基于运行时拥有的缓存键，而不是在本地序列化配置。长生命周期运行时模块对环境中的 `loadConfig()` 调用有零容忍扫描器；请使用传入的 `cfg`、请求的 `context.getRuntimeConfig()`，或在明确的进程边界使用 `getRuntimeConfig()`。
|
||||
|
||||
Provider and channel execution paths must use the active runtime config snapshot, not a file snapshot returned for config readback or editing. File snapshots preserve source values such as SecretRef markers for UI and writes; provider callbacks need the resolved runtime view. When a helper may be called with either the active source snapshot or the active runtime snapshot, route through `selectApplicableRuntimeConfig()` before reading credentials.
|
||||
提供商和渠道执行路径必须使用当前运行时配置快照，而不是用于配置读回或编辑的文件快照。文件快照会保留源值，例如用于 UI 和写入的 SecretRef 标记；提供商回调需要已解析的运行时视图。当辅助函数可能以当前源快照或当前运行时快照调用时，请在读取凭证前通过 `selectApplicableRuntimeConfig()` 路由。
|
||||
|
||||
## Runtime namespaces
|
||||
## 运行时命名空间
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="api.runtime.agent">
|
||||
Agent identity, directories, and session management.
|
||||
智能体身份、目录和会话管理。
|
||||
|
||||
```typescript
|
||||
// Resolve the agent's working directory
|
||||
@ -109,15 +109,15 @@ Provider and channel execution paths must use the active runtime config snapshot
|
||||
});
|
||||
```
|
||||
|
||||
`runEmbeddedAgent(...)` is the neutral helper for starting a normal OpenClaw agent turn from plugin code. It uses the same provider/model resolution and agent-harness selection as channel-triggered replies.
|
||||
`runEmbeddedAgent(...)` 是从插件代码启动普通 OpenClaw 智能体轮次的中立辅助函数。它使用与渠道触发回复相同的提供商/模型解析和 agent-harness 选择。
|
||||
|
||||
`runEmbeddedPiAgent(...)` remains as a compatibility alias.
|
||||
`runEmbeddedPiAgent(...)` 仍作为兼容性别名保留。
|
||||
|
||||
`resolveThinkingPolicy(...)` returns the provider/model's supported thinking levels and optional default. Provider plugins own the model-specific profile through their thinking hooks, so tool plugins should call this runtime helper instead of importing or duplicating provider lists.
|
||||
`resolveThinkingPolicy(...)` 返回该提供商/模型支持的 thinking 级别和可选默认值。提供商插件通过自己的 thinking 钩子拥有特定模型的配置文件，因此工具插件应调用这个运行时辅助函数，而不是导入或复制提供商列表。
|
||||
|
||||
`normalizeThinkingLevel(...)` converts user text such as `on`, `x-high`, or `extra high` to the canonical stored level before checking it against the resolved policy.
|
||||
`normalizeThinkingLevel(...)` 会在根据已解析策略检查前，将 `on`、`x-high` 或 `extra high` 等用户文本转换为规范存储级别。
|
||||
|
||||
**Session store helpers** are under `api.runtime.agent.session`:
|
||||
**会话存储辅助函数**位于 `api.runtime.agent.session` 下：
|
||||
|
||||
```typescript
|
||||
const storePath = api.runtime.agent.session.resolveStorePath(cfg);
|
||||
@ -129,11 +129,11 @@ Provider and channel execution paths must use the active runtime config snapshot
|
||||
const filePath = api.runtime.agent.session.resolveSessionFilePath(cfg, sessionId);
|
||||
```
|
||||
|
||||
Prefer `updateSessionStore(...)` or `updateSessionStoreEntry(...)` for runtime writes. They route through the Gateway-owned session-store writer, preserve concurrent updates, and reuse the hot cache. `saveSessionStore(...)` remains available for compatibility and offline maintenance-style rewrites.
|
||||
对于运行时写入，优先使用 `updateSessionStore(...)` 或 `updateSessionStoreEntry(...)`。它们会经过 Gateway 网关拥有的会话存储写入器，保留并发更新，并复用热缓存。`saveSessionStore(...)` 仍可用于兼容性和离线维护式重写。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="api.runtime.agent.defaults">
|
||||
Default model and provider constants:
|
||||
默认模型和提供商常量：
|
||||
|
||||
```typescript
|
||||
const model = api.runtime.agent.defaults.model; // e.g. "anthropic/claude-sonnet-4-6"
|
||||
@ -142,7 +142,7 @@ Provider and channel execution paths must use the active runtime config snapshot
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="api.runtime.subagent">
|
||||
Launch and manage background subagent runs.
|
||||
启动和管理后台 subagent 运行。
|
||||
|
||||
```typescript
|
||||
// Start a subagent run
|
||||
@ -170,14 +170,14 @@ Provider and channel execution paths must use the active runtime config snapshot
|
||||
```
|
||||
|
||||
<Warning>
|
||||
Model overrides (`provider`/`model`) require operator opt-in via `plugins.entries.<id>.subagent.allowModelOverride: true` in config. Untrusted plugins can still run subagents, but override requests are rejected.
|
||||
模型覆盖（`provider`/`model`）需要操作者通过配置中的 `plugins.entries.<id>.subagent.allowModelOverride: true` 选择启用。不受信任的插件仍可运行 subagent，但覆盖请求会被拒绝。
|
||||
</Warning>
|
||||
|
||||
`deleteSession(...)` can delete sessions created by the same plugin through `api.runtime.subagent.run(...)`. Deleting arbitrary user or operator sessions still requires an admin-scoped Gateway request.
|
||||
`deleteSession(...)` 可以删除同一插件通过 `api.runtime.subagent.run(...)` 创建的会话。删除任意用户或操作者会话仍需要管理员范围的 Gateway 网关请求。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="api.runtime.nodes">
|
||||
List connected nodes and invoke a node-host command from Gateway-loaded plugin code or from plugin CLI commands. Use this when a plugin owns local work on a paired device, for example a browser or audio bridge on another Mac.
|
||||
列出已连接节点，并从 Gateway 网关加载的插件代码或插件 CLI 命令调用节点主机命令。当插件拥有配对设备上的本地工作时使用它，例如另一台 Mac 上的浏览器或音频桥接器。
|
||||
|
||||
```typescript
|
||||
const { nodes } = await api.runtime.nodes.list({ connected: true });
|
||||
@ -190,13 +190,13 @@ Provider and channel execution paths must use the active runtime config snapshot
|
||||
});
|
||||
```
|
||||
|
||||
Inside the Gateway this runtime is in-process. In plugin CLI commands it calls the configured Gateway over RPC, so commands such as `openclaw googlemeet recover-tab` can inspect paired nodes from the terminal. Node commands still go through normal Gateway node pairing, command allowlists, plugin node-invoke policies, and node-local command handling.
|
||||
在 Gateway 网关内部，此运行时在进程内。在插件 CLI 命令中，它会通过 RPC 调用已配置的 Gateway 网关，因此 `openclaw googlemeet recover-tab` 等命令可以从终端检查配对节点。节点命令仍会经过常规 Gateway 网关节点配对、命令允许列表、插件节点调用策略和节点本地命令处理。
|
||||
|
||||
Plugins that expose dangerous node-host commands should register a node-invoke policy with `api.registerNodeInvokePolicy(...)`. The policy runs in the Gateway after command allowlist checks and before the command is forwarded to the node, so direct `node.invoke` calls and higher-level plugin tools share the same enforcement path.
|
||||
暴露危险节点主机命令的插件应使用 `api.registerNodeInvokePolicy(...)` 注册节点调用策略。该策略在 Gateway 网关中运行，位于命令允许列表检查之后、命令转发到节点之前，因此直接 `node.invoke` 调用和更高层级的插件工具共享同一条执行路径。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="api.runtime.tasks.managedFlows">
|
||||
Bind a Task Flow runtime to an existing OpenClaw session key or trusted tool context, then create and manage Task Flows without passing an owner on every call.
|
||||
将任务流运行时绑定到现有 OpenClaw 会话键或可信工具上下文，然后创建和管理任务流，而无需在每次调用时传入所有者。
|
||||
|
||||
```typescript
|
||||
const taskFlow = api.runtime.tasks.managedFlows.fromToolContext(ctx);
|
||||
@ -223,11 +223,11 @@ Provider and channel execution paths must use the active runtime config snapshot
|
||||
});
|
||||
```
|
||||
|
||||
Use `bindSession({ sessionKey, requesterOrigin })` when you already have a trusted OpenClaw session key from your own binding layer. Do not bind from raw user input.
|
||||
当你已经从自己的绑定层获得可信 OpenClaw 会话键时，请使用 `bindSession({ sessionKey, requesterOrigin })`。不要从原始用户输入进行绑定。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="api.runtime.tts">
|
||||
Text-to-speech synthesis.
|
||||
文本转语音合成。
|
||||
|
||||
```typescript
|
||||
// Standard TTS
|
||||
@ -249,11 +249,11 @@ Provider and channel execution paths must use the active runtime config snapshot
|
||||
});
|
||||
```
|
||||
|
||||
Uses core `messages.tts` configuration and provider selection. Returns PCM audio buffer + sample rate.
|
||||
使用核心 `messages.tts` 配置和提供商选择。返回 PCM 音频缓冲区和采样率。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="api.runtime.mediaUnderstanding">
|
||||
Image, audio, and video analysis.
|
||||
图像、音频和视频分析。
|
||||
|
||||
```typescript
|
||||
// Describe an image
|
||||
@ -283,7 +283,7 @@ Provider and channel execution paths must use the active runtime config snapshot
|
||||
});
|
||||
```
|
||||
|
||||
未产生输出时返回 `{ text: undefined }`（例如跳过的输入）。
|
||||
无输出时（例如跳过的输入）返回 `{ text: undefined }`。
|
||||
|
||||
<Info>
|
||||
`api.runtime.stt.transcribeAudioFile(...)` 仍作为 `api.runtime.mediaUnderstanding.transcribeAudioFile(...)` 的兼容性别名保留。
|
||||
@ -342,7 +342,7 @@ Provider and channel execution paths must use the active runtime config snapshot
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="api.runtime.config">
|
||||
当前运行时配置快照和事务式配置写入。优先使用已传入当前活动调用路径的配置；只有当处理程序需要直接访问进程快照时，才使用 `current()`。
|
||||
当前运行时配置快照和事务性配置写入。优先使用已传入当前活跃调用路径的配置；仅当处理程序需要直接读取进程快照时才使用 `current()`。
|
||||
|
||||
```typescript
|
||||
const cfg = api.runtime.config.current();
|
||||
@ -354,7 +354,7 @@ Provider and channel execution paths must use the active runtime config snapshot
|
||||
});
|
||||
```
|
||||
|
||||
`mutateConfigFile(...)` 和 `replaceConfigFile(...)` 会返回一个 `followUp` 值，例如 `{ mode: "restart", requiresRestart: true, reason }`，它会记录写入方意图，而不会从 Gateway 网关手中接管重启控制权。
|
||||
`mutateConfigFile(...)` 和 `replaceConfigFile(...)` 会返回一个 `followUp` 值，例如 `{ mode: "restart", requiresRestart: true, reason }`，用于记录写入方意图，同时不会从 Gateway 网关手中接管重启控制权。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="api.runtime.system">
|
||||
@ -425,10 +425,10 @@ Provider and channel execution paths must use the active runtime config snapshot
|
||||
await store.clear();
|
||||
```
|
||||
|
||||
键值存储会在重启后保留，并按运行时绑定的插件 ID 隔离。使用 `registerIfAbsent(...)` 进行原子去重声明：当键缺失或已过期并成功注册时，它返回 `true`；当已有有效值存在时，它返回 `false`，且不会覆盖该值、创建时间或 TTL。限制：每个命名空间 `maxEntries`、每个插件 1,000 个有效行、64KB 以下的 JSON 值，以及可选的 TTL 过期。
|
||||
键值存储会在重启后保留，并按运行时绑定的插件 id 隔离。使用 `registerIfAbsent(...)` 执行原子去重声明：当键缺失或已过期并完成注册时返回 `true`；当已有有效值存在时返回 `false`，且不会覆盖其值、创建时间或 TTL。限制：每个 namespace 的 `maxEntries`、每个插件 1,000 条有效行、JSON 值小于 64KB，以及可选 TTL 过期。
|
||||
|
||||
<Warning>
|
||||
此版本仅支持内置插件。
|
||||
此版本仅限内置插件。
|
||||
</Warning>
|
||||
|
||||
</Accordion>
|
||||
@ -443,9 +443,9 @@ Provider and channel execution paths must use the active runtime config snapshot
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="api.runtime.channel">
|
||||
渠道特定的运行时辅助工具（加载渠道插件时可用）。
|
||||
渠道特定的运行时辅助函数（加载渠道插件时可用）。
|
||||
|
||||
`api.runtime.channel.mentions` 是使用运行时注入的内置渠道插件的共享入站提及策略界面：
|
||||
`api.runtime.channel.mentions` 是使用运行时注入的内置渠道插件共享的入站提及策略表面：
|
||||
|
||||
```typescript
|
||||
const mentionMatch = api.runtime.channel.mentions.matchesMentionWithExplicit(text, {
|
||||
@ -472,7 +472,7 @@ Provider and channel execution paths must use the active runtime config snapshot
|
||||
});
|
||||
```
|
||||
|
||||
可用的提及辅助工具：
|
||||
可用的提及辅助函数：
|
||||
|
||||
- `buildMentionRegexes`
|
||||
- `matchesMentionPatterns`
|
||||
@ -480,7 +480,7 @@ Provider and channel execution paths must use the active runtime config snapshot
|
||||
- `implicitMentionKindWhen`
|
||||
- `resolveInboundMentionDecision`
|
||||
|
||||
`api.runtime.channel.mentions` 有意不暴露较旧的 `resolveMentionGating*` 兼容性辅助工具。优先使用标准化的 `{ facts, policy }` 路径。
|
||||
`api.runtime.channel.mentions` 有意不公开较旧的 `resolveMentionGating*` 兼容性辅助函数。优先使用规范化的 `{ facts, policy }` 路径。
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
@ -490,7 +490,7 @@ Provider and channel execution paths must use the active runtime config snapshot
|
||||
使用 `createPluginRuntimeStore` 存储运行时引用，以便在 `register` 回调之外使用：
|
||||
|
||||
<Steps>
|
||||
<Step title="Create the store">
|
||||
<Step title="创建存储">
|
||||
```typescript
|
||||
import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store";
|
||||
import type { PluginRuntime } from "openclaw/plugin-sdk/runtime-store";
|
||||
@ -502,7 +502,7 @@ Provider and channel execution paths must use the active runtime config snapshot
|
||||
```
|
||||
|
||||
</Step>
|
||||
<Step title="Wire into the entry point">
|
||||
<Step title="接入入口点">
|
||||
```typescript
|
||||
export default defineChannelPluginEntry({
|
||||
id: "my-plugin",
|
||||
@ -513,7 +513,7 @@ Provider and channel execution paths must use the active runtime config snapshot
|
||||
});
|
||||
```
|
||||
</Step>
|
||||
<Step title="Access from other files">
|
||||
<Step title="从其他文件访问">
|
||||
```typescript
|
||||
export function getRuntime() {
|
||||
return store.getRuntime(); // throws if not initialized
|
||||
@ -528,7 +528,7 @@ Provider and channel execution paths must use the active runtime config snapshot
|
||||
</Steps>
|
||||
|
||||
<Note>
|
||||
运行时存储标识优先使用 `pluginId`。较底层的 `key` 形式适用于少见情况，即一个插件有意需要多个运行时槽位。
|
||||
运行时存储身份优先使用 `pluginId`。较低层级的 `key` 形式适用于少见场景，即一个插件有意需要多个运行时槽位。
|
||||
</Note>
|
||||
|
||||
## 其他顶层 `api` 字段
|
||||
@ -536,13 +536,13 @@ Provider and channel execution paths must use the active runtime config snapshot
|
||||
除 `api.runtime` 外，API 对象还提供：
|
||||
|
||||
<ParamField path="api.id" type="string">
|
||||
插件 ID。
|
||||
插件 id。
|
||||
</ParamField>
|
||||
<ParamField path="api.name" type="string">
|
||||
插件显示名称。
|
||||
</ParamField>
|
||||
<ParamField path="api.config" type="OpenClawConfig">
|
||||
当前配置快照（可用时为活动的内存中运行时快照）。
|
||||
当前配置快照（可用时为活跃的内存运行时快照）。
|
||||
</ParamField>
|
||||
<ParamField path="api.pluginConfig" type="Record<string, unknown>">
|
||||
来自 `plugins.entries.<id>.config` 的插件特定配置。
|
||||
@ -551,13 +551,13 @@ Provider and channel execution paths must use the active runtime config snapshot
|
||||
作用域日志记录器（`debug`、`info`、`warn`、`error`）。
|
||||
</ParamField>
|
||||
<ParamField path="api.registrationMode" type="PluginRegistrationMode">
|
||||
当前加载模式；`"setup-runtime"` 是轻量级的完整入口启动前/设置窗口。
|
||||
当前加载模式；`"setup-runtime"` 是轻量级的完整入口前启动/设置窗口。
|
||||
</ParamField>
|
||||
<ParamField path="api.resolvePath(input)" type="(string) => string">
|
||||
解析相对于插件根目录的路径。
|
||||
</ParamField>
|
||||
|
||||
## 相关内容
|
||||
## 相关
|
||||
|
||||
- [插件内部机制](/zh-CN/plugins/architecture) — 能力模型和注册表
|
||||
- [SDK 入口点](/zh-CN/plugins/sdk-entrypoints) — `definePluginEntry` 选项
|
||||
|
||||
@ -1,38 +1,38 @@
|
||||
---
|
||||
read_when:
|
||||
- 你希望对 SSRF 和 DNS 重绑定攻击进行纵深防御
|
||||
- 你希望针对 SSRF 和 DNS 重绑定攻击实现纵深防御
|
||||
- 为 OpenClaw 运行时流量配置外部正向代理
|
||||
summary: 如何通过由操作员管理的过滤代理路由 OpenClaw 运行时 HTTP 和 WebSocket 流量
|
||||
title: 网络代理
|
||||
x-i18n:
|
||||
generated_at: "2026-05-06T16:12:22Z"
|
||||
generated_at: "2026-05-06T16:28:22Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 0aa7f4ff8c8484967b82e58f466cd153ca2f7810b0d29f55a2955683a6ee1444
|
||||
source_hash: aed1cd94ce6a32cd8a3f6c7e579011992af87c1ccc40eb53efaa83b020a6792b
|
||||
source_path: security/network-proxy.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
OpenClaw 可以通过由操作员管理的正向代理路由运行时 HTTP 和 WebSocket 流量。对于希望集中控制出站流量、增强 SSRF 保护并提升网络可审计性的部署，这是可选的纵深防御措施。
|
||||
OpenClaw 可以通过由运维人员管理的正向代理路由运行时 HTTP 和 WebSocket 流量。对于希望实现集中式出站流量控制、更强 SSRF 防护和更好网络可审计性的部署，这是可选的纵深防御措施。
|
||||
|
||||
OpenClaw 不会提供、下载、启动、配置或认证代理。你可以运行适合你的环境的代理技术，OpenClaw 会通过它路由普通的进程本地 HTTP 和 WebSocket 客户端。
|
||||
OpenClaw 不会随附、下载、启动、配置或认证代理。你运行适合自己环境的代理技术，OpenClaw 会通过它路由普通的进程本地 HTTP 和 WebSocket 客户端。
|
||||
|
||||
## 为什么使用代理
|
||||
|
||||
代理为操作员提供一个用于出站 HTTP 和 WebSocket 流量的网络控制点。即使不考虑 SSRF 加固，这也很有用：
|
||||
代理为运维人员提供一个用于出站 HTTP 和 WebSocket 流量的网络控制点。即使在 SSRF 加固之外，这也很有用：
|
||||
|
||||
- 集中策略：维护一个出站策略，而不是依赖每个应用 HTTP 调用点都正确处理网络规则。
|
||||
- 连接时检查：在 DNS 解析之后、代理打开上游连接之前立即评估目标。
|
||||
- 集中式策略：维护一套出站策略，而不是依赖每个应用 HTTP 调用点都正确处理网络规则。
|
||||
- 连接时检查：在 DNS 解析之后，并且在代理打开上游连接之前立即评估目标。
|
||||
- DNS 重绑定防御：缩小应用级 DNS 检查与实际出站连接之间的间隙。
|
||||
- 更广泛的 JavaScript 覆盖：将普通的 `fetch`、`node:http`、`node:https`、WebSocket、axios、got、node-fetch 以及类似客户端路由到同一路径。
|
||||
- 可审计性：在出站边界记录允许和拒绝的目标。
|
||||
- 更广泛的 JavaScript 覆盖：通过同一路径路由普通的 `fetch`、`node:http`、`node:https`、WebSocket、axios、got、node-fetch 以及类似客户端。
|
||||
- 可审计性：在出站边界记录被允许和被拒绝的目标。
|
||||
- 运维控制：无需重新构建 OpenClaw，即可强制执行目标规则、网络分段、速率限制或出站允许列表。
|
||||
|
||||
代理路由是普通 HTTP 和 WebSocket 出站流量的进程级防护栏。它为操作员提供一条故障关闭路径，用于通过他们自己的过滤代理路由受支持的 JavaScript HTTP 客户端，但它不是操作系统级网络沙箱，也不会让 OpenClaw 认证代理的目标策略。
|
||||
代理路由是面向普通 HTTP 和 WebSocket 出站流量的进程级护栏。它为运维人员提供一条故障关闭路径，用于将受支持的 JavaScript HTTP 客户端通过其自有过滤代理进行路由，但它不是 OS 级网络沙箱，也不会让 OpenClaw 认证代理的目标策略。
|
||||
|
||||
## OpenClaw 如何路由流量
|
||||
|
||||
当 `proxy.enabled=true` 且配置了代理 URL 时，受保护的运行时进程（例如 `openclaw gateway run`、`openclaw node run` 和 `openclaw agent --local`）会通过配置的代理路由普通 HTTP 和 WebSocket 出站流量：
|
||||
当 `proxy.enabled=true` 且已配置代理 URL 时，受保护的运行时进程（例如 `openclaw gateway run`、`openclaw node run` 和 `openclaw agent --local`）会通过配置的代理路由普通 HTTP 和 WebSocket 出站流量：
|
||||
|
||||
```text
|
||||
OpenClaw process
|
||||
@ -41,28 +41,28 @@ OpenClaw process
|
||||
WebSocket clients -> operator-managed filtering proxy -> public internet
|
||||
```
|
||||
|
||||
公共契约是路由行为，而不是用于实现它的内部 Node 钩子。当 Gateway 网关 URL 使用 `localhost` 或字面量回环 IP（例如 `127.0.0.1` 或 `[::1]`）时，OpenClaw Gateway 网关控制平面 WebSocket 客户端会对 local loopback Gateway 网关 RPC 流量使用一条狭窄的直连路径。即使操作员代理阻止回环目标，该控制平面路径也必须能够访问回环 Gateway 网关。普通运行时 HTTP 和 WebSocket 请求仍然使用配置的代理。
|
||||
公共契约是路由行为，而不是用于实现它的内部 Node 钩子。当 Gateway 网关 URL 使用 `localhost` 或字面量回环 IP（例如 `127.0.0.1` 或 `[::1]`）时，OpenClaw Gateway 网关控制平面 WebSocket 客户端会为 local loopback Gateway 网关 RPC 流量使用一条窄范围的直连路径。即使运维人员代理阻止回环目标，该控制平面路径也必须能够访问回环 Gateway 网关。普通运行时 HTTP 和 WebSocket 请求仍会使用配置的代理。
|
||||
|
||||
在内部，OpenClaw 为此功能使用两个进程级路由钩子：
|
||||
|
||||
- Undici 调度器路由覆盖 `fetch`、基于 undici 的客户端，以及提供自身 undici 调度器的传输。
|
||||
- `global-agent` 路由覆盖 Node 核心 `node:http` 和 `node:https` 调用方，包括许多构建在 `http.request`、`https.request`、`http.get` 和 `https.get` 之上的库。托管代理模式会强制使用该全局代理，因此显式的 Node HTTP agent 不会意外绕过操作员代理。
|
||||
- Undici 调度器路由覆盖 `fetch`、基于 undici 的客户端，以及提供自有 undici 调度器的传输。
|
||||
- `global-agent` 路由覆盖 Node 核心 `node:http` 和 `node:https` 调用方，包括许多基于 `http.request`、`https.request`、`http.get` 和 `https.get` 构建的库。托管代理模式会强制使用该全局代理，因此显式 Node HTTP 代理不会意外绕过运维人员代理。
|
||||
|
||||
有些插件拥有自定义传输，即使存在进程级路由，也需要显式代理接线。例如，Telegram 的 Bot API 传输使用自己的 HTTP/1 undici 调度器，因此在该所有者特定的传输路径中会遵循进程代理环境变量以及托管的 `OPENCLAW_PROXY_URL` 回退。
|
||||
一些插件拥有自定义传输，即使存在进程级路由，也需要显式代理接线。例如，Telegram 的 Bot API 传输使用自己的 HTTP/1 undici 调度器，因此会在该所有者特定的传输路径中遵循进程代理环境以及托管的 `OPENCLAW_PROXY_URL` 回退。
|
||||
|
||||
代理 URL 本身必须使用 `http://`。仍然支持通过代理访问 HTTPS 目标，并使用 HTTP `CONNECT`；这只表示 OpenClaw 期望一个普通 HTTP 正向代理监听器，例如 `http://127.0.0.1:3128`。
|
||||
代理 URL 本身必须使用 `http://`。HTTPS 目标仍然通过带有 HTTP `CONNECT` 的代理受支持；这只表示 OpenClaw 期望一个普通 HTTP 正向代理监听器，例如 `http://127.0.0.1:3128`。
|
||||
|
||||
代理处于活动状态时，OpenClaw 会清除 `no_proxy`、`NO_PROXY` 和 `GLOBAL_AGENT_NO_PROXY`。这些绕过列表基于目标，因此如果其中保留 `localhost` 或 `127.0.0.1`，高风险 SSRF 目标就可能跳过过滤代理。
|
||||
当代理处于活动状态时，OpenClaw 会清除 `no_proxy`、`NO_PROXY` 和 `GLOBAL_AGENT_NO_PROXY`。这些绕过列表基于目标，因此如果其中保留 `localhost` 或 `127.0.0.1`，高风险 SSRF 目标就能跳过过滤代理。
|
||||
|
||||
关闭时，OpenClaw 会恢复此前的代理环境并重置缓存的进程路由状态。
|
||||
关闭时，OpenClaw 会恢复之前的代理环境，并重置缓存的进程路由状态。
|
||||
|
||||
## 相关代理术语
|
||||
|
||||
- `proxy.enabled` / `proxy.proxyUrl`：OpenClaw 运行时出站流量的出站正向代理路由。本页记录此功能。
|
||||
- `gateway.auth.mode: "trusted-proxy"`：用于 Gateway 网关访问的入站身份感知反向代理身份验证。参见 [受信任代理身份验证](/zh-CN/gateway/trusted-proxy-auth)。
|
||||
- `openclaw proxy`：用于开发和支持的本地调试代理和捕获检查器。参见 [openclaw proxy](/zh-CN/cli/proxy)。
|
||||
- `tools.web.fetch.useTrustedEnvProxy`：为 `web_fetch` 选择启用，让操作员控制的 HTTP(S) 环境代理解析 DNS，同时保留默认严格的 DNS 固定和主机名策略。参见 [Web fetch](/zh-CN/tools/web-fetch#trusted-env-proxy)。
|
||||
- 渠道或提供商特定的代理设置：用于特定传输的所有者特定覆盖。当目标是在整个运行时集中控制出站流量时，优先使用托管网络代理。
|
||||
- `proxy.enabled` / `proxy.proxyUrl`：用于 OpenClaw 运行时出站流量的出站正向代理路由。本页记录该功能。
|
||||
- `gateway.auth.mode: "trusted-proxy"`：用于 Gateway 网关访问的入站身份感知反向代理身份验证。参见 [可信代理身份验证](/zh-CN/gateway/trusted-proxy-auth)。
|
||||
- `openclaw proxy`：用于开发和支持的本地调试代理与捕获检查器。参见 [openclaw proxy](/zh-CN/cli/proxy)。
|
||||
- `tools.web.fetch.useTrustedEnvProxy`：为 `web_fetch` 选择加入，让运维人员控制的 HTTP(S) 环境代理解析 DNS，同时保留默认的严格 DNS 固定和主机名策略。参见 [Web fetch](/zh-CN/tools/web-fetch#trusted-env-proxy)。
|
||||
- 渠道或提供商特定的代理设置：针对特定传输的所有者特定覆盖。当目标是在整个运行时实现集中式出站流量控制时，优先使用托管网络代理。
|
||||
|
||||
## 配置
|
||||
|
||||
@ -82,7 +82,7 @@ OPENCLAW_PROXY_URL=http://127.0.0.1:3128 openclaw gateway run
|
||||
|
||||
### Gateway 网关回环模式
|
||||
|
||||
本地 Gateway 网关控制平面客户端通常连接到回环 WebSocket，例如 `ws://127.0.0.1:18789`。使用 `proxy.loopbackMode` 选择托管代理处于活动状态时该流量的行为：
|
||||
本地 Gateway 网关控制平面客户端通常连接到回环 WebSocket，例如 `ws://127.0.0.1:18789`。使用 `proxy.loopbackMode` 选择托管代理处于活动状态时该流量的行为方式：
|
||||
|
||||
```yaml
|
||||
proxy:
|
||||
@ -91,8 +91,8 @@ proxy:
|
||||
loopbackMode: gateway-only # gateway-only, proxy, or block
|
||||
```
|
||||
|
||||
- `gateway-only`（默认）：OpenClaw 会在活动的 `global-agent` `NO_PROXY` 控制器中注册 Gateway 网关回环 authority，以便本地 Gateway 网关 WebSocket 流量可以直接连接。自定义回环 Gateway 网关端口可以工作，因为活动 Gateway 网关 URL 的主机和端口会被注册。
|
||||
- `proxy`：OpenClaw 不会注册 Gateway 网关回环 `NO_PROXY` authority，因此本地 Gateway 网关流量会发送到托管代理。如果代理是远程的，它必须为 OpenClaw 主机的回环服务提供特殊路由，例如将其映射到代理可访问的主机名、IP 或隧道。标准远程代理会从代理主机解析 `127.0.0.1` 和 `localhost`，而不是从 OpenClaw 主机解析。
|
||||
- `gateway-only`（默认）：OpenClaw 会在活动的 `global-agent` `NO_PROXY` 控制器中注册 Gateway 网关回环授权域，因此本地 Gateway 网关 WebSocket 流量可以直连。自定义回环 Gateway 网关端口也可用，因为活动 Gateway 网关 URL 的主机和端口会被注册。
|
||||
- `proxy`：OpenClaw 不会注册 Gateway 网关回环 `NO_PROXY` 授权域，因此本地 Gateway 网关流量会通过托管代理发送。如果代理是远程的，它必须为 OpenClaw 主机的回环服务提供特殊路由，例如将其映射到代理可访问的主机名、IP 或隧道。标准远程代理会从代理主机解析 `127.0.0.1` 和 `localhost`，而不是从 OpenClaw 主机解析。
|
||||
- `block`：OpenClaw 会在打开套接字之前拒绝回环 Gateway 网关控制平面连接。
|
||||
|
||||
如果 `enabled=true` 但未配置有效的代理 URL，受保护命令会启动失败，而不是回退到直接网络访问。
|
||||
@ -106,63 +106,63 @@ openclaw gateway install --force
|
||||
openclaw gateway start
|
||||
```
|
||||
|
||||
环境回退最适合前台运行。如果你将它用于已安装的服务，请将 `OPENCLAW_PROXY_URL` 放入服务的持久环境中，例如 `$OPENCLAW_STATE_DIR/.env` 或 `~/.openclaw/.env`，然后重新安装服务，以便 launchd、systemd 或 Scheduled Tasks 使用该值启动 Gateway 网关。
|
||||
环境回退最适合前台运行。如果你将其用于已安装的服务，请将 `OPENCLAW_PROXY_URL` 放入服务的持久环境中，例如 `$OPENCLAW_STATE_DIR/.env` 或 `~/.openclaw/.env`，然后重新安装服务，使 launchd、systemd 或 Scheduled Tasks 使用该值启动 Gateway 网关。
|
||||
|
||||
对于 `openclaw --container ...` 命令，设置了 `OPENCLAW_PROXY_URL` 时，OpenClaw 会将其转发到面向容器的子 CLI。该 URL 必须能从容器内部访问；`127.0.0.1` 指的是容器本身，而不是主机。对于面向容器的命令，OpenClaw 会拒绝回环代理 URL，除非你显式覆盖该安全检查。
|
||||
对于 `openclaw --container ...` 命令，当设置了 `OPENCLAW_PROXY_URL` 时，OpenClaw 会将其转发到面向容器的子 CLI。该 URL 必须能从容器内部访问；`127.0.0.1` 指的是容器自身，而不是主机。OpenClaw 会拒绝面向容器命令的回环代理 URL，除非你显式覆盖该安全检查。
|
||||
|
||||
## 代理要求
|
||||
|
||||
代理策略是安全边界。OpenClaw 无法验证代理是否阻止了正确的目标。
|
||||
|
||||
配置代理以：
|
||||
将代理配置为：
|
||||
|
||||
- 仅绑定到回环或私有受信任接口。
|
||||
- 限制访问，使只有 OpenClaw 进程、主机、容器或服务账号能够使用它。
|
||||
- 仅绑定到回环或私有可信接口。
|
||||
- 限制访问，使只有 OpenClaw 进程、主机、容器或服务账户可以使用它。
|
||||
- 自行解析目标，并在 DNS 解析后阻止目标 IP。
|
||||
- 对普通 HTTP 请求和 HTTPS `CONNECT` 隧道都在连接时应用策略。
|
||||
- 在普通 HTTP 请求和 HTTPS `CONNECT` 隧道的连接时都应用策略。
|
||||
- 拒绝针对回环、私有、链路本地、元数据、多播、保留或文档范围的基于目标的绕过。
|
||||
- 除非你完全信任 DNS 解析路径，否则避免使用主机名允许列表。
|
||||
- 记录目标、决策、状态和原因，但不要记录请求正文、授权标头、Cookie 或其他密钥。
|
||||
- 将代理策略纳入版本控制，并像安全敏感配置一样审查变更。
|
||||
- 避免使用主机名允许列表，除非你完全信任 DNS 解析路径。
|
||||
- 记录目标、决策、状态和原因，但不记录请求正文、授权标头、Cookie 或其他密钥。
|
||||
- 将代理策略置于版本控制之下，并像审查安全敏感配置一样审查变更。
|
||||
|
||||
## 建议阻止的目标
|
||||
## 推荐阻止的目标
|
||||
|
||||
将此拒绝列表用作任何正向代理、防火墙或出站策略的起点。
|
||||
将此拒绝列表作为任何正向代理、防火墙或出站策略的起点。
|
||||
|
||||
OpenClaw 应用级分类器逻辑位于 `src/infra/net/ssrf.ts` 和 `src/shared/net/ip.ts`。相关的对等钩子包括 `BLOCKED_HOSTNAMES`、`BLOCKED_IPV4_SPECIAL_USE_RANGES`、`BLOCKED_IPV6_SPECIAL_USE_RANGES`、`RFC2544_BENCHMARK_PREFIX`，以及用于 NAT64、6to4、Teredo、ISATAP 和 IPv4 映射形式的嵌入式 IPv4 哨兵处理。维护外部代理策略时，这些文件是有用的参考，但 OpenClaw 不会自动导出这些规则，也不会在你的代理中强制执行它们。
|
||||
OpenClaw 应用级分类器逻辑位于 `src/infra/net/ssrf.ts` 和 `src/shared/net/ip.ts`。相关的对等钩子是 `BLOCKED_HOSTNAMES`、`BLOCKED_IPV4_SPECIAL_USE_RANGES`、`BLOCKED_IPV6_SPECIAL_USE_RANGES`、`RFC2544_BENCHMARK_PREFIX`，以及针对 NAT64、6to4、Teredo、ISATAP 和 IPv4 映射形式的嵌入式 IPv4 哨兵处理。维护外部代理策略时，这些文件是有用参考，但 OpenClaw 不会自动导出这些规则，也不会在你的代理中强制执行这些规则。
|
||||
|
||||
| 范围或主机 | 阻止原因 |
|
||||
| ---------------------------------------------------------------------------------- | ---------------------------------------------------- |
|
||||
| `127.0.0.0/8`, `localhost`, `localhost.localdomain` | IPv4 回环 |
|
||||
| `::1/128` | IPv6 回环 |
|
||||
| `0.0.0.0/8`, `::/128` | 未指定地址和本网地址 |
|
||||
| `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16` | RFC1918 私有网络 |
|
||||
| `169.254.0.0/16`, `fe80::/10` | 链路本地地址和常见云元数据路径 |
|
||||
| `169.254.169.254`, `metadata.google.internal` | 云元数据服务 |
|
||||
| `100.64.0.0/10` | 运营商级 NAT 共享地址空间 |
|
||||
| `198.18.0.0/15`, `2001:2::/48` | 基准测试范围 |
|
||||
| 范围或主机 | 阻止原因 |
|
||||
| ------------------------------------------------------------------------------------ | ---------------------------------------------------- |
|
||||
| `127.0.0.0/8`, `localhost`, `localhost.localdomain` | IPv4 回环 |
|
||||
| `::1/128` | IPv6 回环 |
|
||||
| `0.0.0.0/8`, `::/128` | 未指定地址和本网络地址 |
|
||||
| `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16` | RFC1918 私有网络 |
|
||||
| `169.254.0.0/16`, `fe80::/10` | 链路本地地址和常见云元数据路径 |
|
||||
| `169.254.169.254`, `metadata.google.internal` | 云元数据服务 |
|
||||
| `100.64.0.0/10` | 运营商级 NAT 共享地址空间 |
|
||||
| `198.18.0.0/15`, `2001:2::/48` | 基准测试范围 |
|
||||
| `192.0.0.0/24`, `192.0.2.0/24`, `198.51.100.0/24`, `203.0.113.0/24`, `2001:db8::/32` | 特殊用途和文档范围 |
|
||||
| `224.0.0.0/4`, `ff00::/8` | 多播 |
|
||||
| `240.0.0.0/4` | 保留 IPv4 |
|
||||
| `fc00::/7`, `fec0::/10` | IPv6 本地/私有范围 |
|
||||
| `100::/64`, `2001:20::/28` | IPv6 丢弃和 ORCHIDv2 范围 |
|
||||
| `64:ff9b::/96`, `64:ff9b:1::/48` | 带嵌入式 IPv4 的 NAT64 前缀 |
|
||||
| `2002::/16`, `2001::/32` | 带嵌入式 IPv4 的 6to4 和 Teredo |
|
||||
| `::/96`, `::ffff:0:0/96` | IPv4 兼容和 IPv4 映射的 IPv6 |
|
||||
| `224.0.0.0/4`, `ff00::/8` | 多播 |
|
||||
| `240.0.0.0/4` | 保留 IPv4 |
|
||||
| `fc00::/7`, `fec0::/10` | IPv6 本地/私有范围 |
|
||||
| `100::/64`, `2001:20::/28` | IPv6 丢弃和 ORCHIDv2 范围 |
|
||||
| `64:ff9b::/96`, `64:ff9b:1::/48` | 带有嵌入式 IPv4 的 NAT64 前缀 |
|
||||
| `2002::/16`, `2001::/32` | 带有嵌入式 IPv4 的 6to4 和 Teredo |
|
||||
| `::/96`, `::ffff:0:0/96` | IPv4 兼容和 IPv4 映射 IPv6 |
|
||||
|
||||
如果你的云提供商或网络平台记录了额外的元数据主机或保留范围，也请将它们加入。
|
||||
如果你的云提供商或网络平台记录了其他元数据主机或保留范围，也请一并添加。
|
||||
|
||||
## 验证
|
||||
|
||||
从运行 OpenClaw 的同一主机、容器或服务账号验证代理：
|
||||
从运行 OpenClaw 的同一主机、容器或服务账户验证代理：
|
||||
|
||||
```bash
|
||||
openclaw proxy validate --proxy-url http://127.0.0.1:3128
|
||||
```
|
||||
|
||||
默认情况下，当未提供自定义目标时，该命令会检查 `https://example.com/` 是否成功，并启动一个代理不得访问的临时回环金丝雀。默认的拒绝检查会在代理返回非 2xx 拒绝响应，或因传输失败而阻止金丝雀时通过；如果成功响应到达金丝雀，则检查失败。如果未启用并配置代理，验证会报告配置问题；在更改配置前，可使用 `--proxy-url` 进行一次性预检。使用 `--allowed-url` 和 `--denied-url` 测试特定部署的预期。添加 `--apns-reachable` 还可验证直连 APNs HTTP/2 投递是否能通过代理打开 CONNECT 隧道并收到沙箱 APNs 响应；该探测会使用故意无效的提供商令牌，因此预期结果是 `403 InvalidProviderToken`，并计为可达。自定义拒绝目标采用失败关闭策略：任何 HTTP 响应都表示目标可通过代理访问，而任何传输错误都会报告为无法判定，因为 OpenClaw 无法证明代理阻止了一个可达来源。验证失败时，该命令以代码 1 退出。
|
||||
默认情况下，如果没有提供自定义目标，该命令会检查 `https://example.com/` 是否成功，并启动一个代理不得访问的临时环回探针。默认的拒绝检查会在代理返回非 2xx 拒绝响应，或通过传输失败阻止探针时通过；如果成功响应到达探针，则检查失败。如果未启用并配置代理，验证会报告配置问题；在更改配置之前，可使用 `--proxy-url` 进行一次性预检。使用 `--allowed-url` 和 `--denied-url` 测试特定部署的预期行为。添加 `--apns-reachable` 还会验证直接 APNs HTTP/2 递送是否可以通过代理打开 CONNECT 隧道并接收沙箱 APNs 响应；该探测会使用故意无效的提供商令牌，因此预期会返回 `403 InvalidProviderToken`，并计为可访问。自定义拒绝目标采用失败关闭策略：任何 HTTP 响应都意味着该目标可通过代理访问，任何传输错误都会报告为无法确定，因为 OpenClaw 无法证明代理阻止了一个可访问的源站。验证失败时，该命令以代码 1 退出。
|
||||
|
||||
自动化场景请使用 `--json`。JSON 输出包含整体结果、有效代理配置来源、任何配置错误，以及每个目标检查。代理 URL 凭据会在文本和 JSON 输出中被遮蔽：
|
||||
使用 `--json` 进行自动化。JSON 输出包含总体结果、有效代理配置来源、所有配置错误以及每个目标检查。代理 URL 凭据会在文本和 JSON 输出中脱敏：
|
||||
|
||||
```json
|
||||
{
|
||||
@ -198,7 +198,7 @@ curl -x http://127.0.0.1:3128 http://127.0.0.1/
|
||||
curl -x http://127.0.0.1:3128 http://169.254.169.254/
|
||||
```
|
||||
|
||||
公共请求应成功。回环和元数据请求应被代理阻止。对于 `openclaw proxy validate`，内置回环金丝雀可以区分代理拒绝和可达来源。自定义 `--denied-url` 检查没有该金丝雀，因此除非你的代理公开了可单独验证的特定部署拒绝信号，否则应将 HTTP 响应和模糊的传输失败都视为验证失败。
|
||||
公共请求应成功。环回和元数据请求应被代理阻止。对于 `openclaw proxy validate`，内置的环回探针可以区分代理拒绝和可访问源站。自定义 `--denied-url` 检查没有该探针，因此除非你的代理暴露了可单独验证的特定部署拒绝信号，否则应将 HTTP 响应和含糊的传输失败都视为验证失败。
|
||||
|
||||
然后启用 OpenClaw 代理路由：
|
||||
|
||||
@ -218,12 +218,12 @@ proxy:
|
||||
|
||||
## 限制
|
||||
|
||||
- 代理会改善进程本地 JavaScript HTTP 和 WebSocket 客户端的覆盖范围，但它不是操作系统级网络沙箱。
|
||||
- Gateway 网关回环控制平面流量默认通过 `proxy.loopbackMode: "gateway-only"` 直接在本地旁路。OpenClaw 通过在托管 `global-agent` `NO_PROXY` 控制器中注册活动 Gateway 网关回环 authority 来实现该旁路。操作员可以设置 `proxy.loopbackMode: "proxy"`，让 Gateway 网关回环流量通过托管代理发送，或设置 `proxy.loopbackMode: "block"` 拒绝回环 Gateway 网关连接。有关远程代理注意事项，请参阅 [Gateway 网关回环模式](#gateway-loopback-mode)。
|
||||
- 代理改善了对进程本地 JavaScript HTTP 和 WebSocket 客户端的覆盖，但它不是操作系统级网络沙箱。
|
||||
- Gateway 网关环回控制平面流量默认通过 `proxy.loopbackMode: "gateway-only"` 直接本地绕过。OpenClaw 通过在托管的 `global-agent` `NO_PROXY` 控制器中注册活动 Gateway 网关环回 authority 来实现该绕过。运维人员可以设置 `proxy.loopbackMode: "proxy"`，让 Gateway 网关环回流量通过托管代理发送，或设置 `proxy.loopbackMode: "block"` 来拒绝环回 Gateway 网关连接。有关远程代理注意事项，请参阅 [Gateway 网关环回模式](#gateway-loopback-mode)。
|
||||
- 原始 `net`、`tls` 和 `http2` 套接字、原生插件以及非 OpenClaw 子进程可能会绕过 Node 级代理路由，除非它们继承并遵循代理环境变量。派生的 OpenClaw 子 CLI 会继承托管代理 URL 和 `proxy.loopbackMode` 状态。
|
||||
- IRC 是位于操作员托管的转发代理路由之外的原始 TCP/TLS 渠道。在要求所有出站流量都通过该转发代理的部署中，除非明确批准直接 IRC 出站，否则请设置 `channels.irc.enabled=false`。
|
||||
- IRC 是一个位于运维人员管理的正向代理路由之外的原始 TCP/TLS 渠道。在要求所有出口流量都经过该正向代理的部署中，除非明确批准直接 IRC 出口流量，否则请设置 `channels.irc.enabled=false`。
|
||||
- 本地调试代理是诊断工具；在托管代理模式处于活动状态时，默认禁用其对代理请求和 CONNECT 隧道的直接上游转发；仅为已批准的本地诊断启用直接转发。
|
||||
- 需要时，应在操作员代理策略中将用户本地 WebUI 和本地模型服务器加入允许列表；OpenClaw 不会为它们公开通用本地网络旁路。
|
||||
- Gateway 网关控制平面代理旁路有意限制为 `localhost` 和字面量回环 IP URL。对于本地直连 Gateway 网关控制平面连接，请使用 `ws://127.0.0.1:18789`、`ws://[::1]:18789` 或 `ws://localhost:18789`；其他主机名会像普通基于主机名的流量一样路由。
|
||||
- 如有需要，应在运维代理策略中允许列出用户本地 WebUI 和本地模型服务器；OpenClaw 不会为它们暴露通用的本地网络绕过。
|
||||
- Gateway 网关控制平面代理绕过会有意限制为 `localhost` 和字面量环回 IP URL。对于本地直接 Gateway 网关控制平面连接，请使用 `ws://127.0.0.1:18789`、`ws://[::1]:18789` 或 `ws://localhost:18789`；其他主机名会像普通基于主机名的流量一样路由。
|
||||
- OpenClaw 不会检查、测试或认证你的代理策略。
|
||||
- 请将代理策略变更视为安全敏感的运维变更。
|
||||
- 将代理策略更改视为安全敏感的运维更改。
|
||||
|
||||
@ -1,24 +1,25 @@
|
||||
---
|
||||
read_when:
|
||||
- 你想获取一个 URL 并提取可读内容
|
||||
- 你需要配置 web_fetch 或其 Firecrawl 回退方案
|
||||
- 你需要配置 web_fetch 或其 Firecrawl 后备方案
|
||||
- 你想了解 web_fetch 的限制和缓存
|
||||
sidebarTitle: Web Fetch
|
||||
summary: web_fetch 工具 -- HTTP 获取并提取可读内容
|
||||
title: 网页获取
|
||||
x-i18n:
|
||||
generated_at: "2026-05-03T21:39:58Z"
|
||||
generated_at: "2026-05-06T16:28:28Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: c8c3efbf4a640b2fd69cc9532dcb06a873a6830a2e8a85ab7510ab38207c8670
|
||||
source_hash: 337174898861db217bf0db052d8e8749989c295e89c73d9d5a6911f6335ba03d
|
||||
source_path: tools/web-fetch.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
`web_fetch` 工具会执行普通的 HTTP GET，并提取可读内容（将 HTML 转为 Markdown 或文本）。它**不会**执行 JavaScript。
|
||||
`web_fetch` 工具会执行普通的 HTTP GET，并提取可读内容
|
||||
（HTML 转为 Markdown 或文本）。它**不会**执行 JavaScript。
|
||||
|
||||
对于重度依赖 JS 的站点或受登录保护的页面，请改用
|
||||
[Web 浏览器](/zh-CN/tools/browser)。
|
||||
对于大量依赖 JS 的站点或受登录保护的页面，请改用
|
||||
[Web Browser](/zh-CN/tools/browser)。
|
||||
|
||||
## 快速开始
|
||||
|
||||
@ -39,23 +40,26 @@ await web_fetch({ url: "https://example.com/article" });
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="maxChars" type="number">
|
||||
将输出截断为指定字符数。
|
||||
将输出截断到这么多字符。
|
||||
</ParamField>
|
||||
|
||||
## 工作原理
|
||||
|
||||
<Steps>
|
||||
<Step title="获取">
|
||||
使用类似 Chrome 的 User-Agent 和 `Accept-Language` 标头发送 HTTP GET。阻止私有/内部主机名，并重新检查重定向。
|
||||
<Step title="Fetch">
|
||||
使用类似 Chrome 的 User-Agent 和 `Accept-Language`
|
||||
标头发送 HTTP GET。阻止私有/内部主机名，并重新检查重定向。
|
||||
</Step>
|
||||
<Step title="提取">
|
||||
在 HTML 响应上运行 Readability（主内容提取）。
|
||||
<Step title="Extract">
|
||||
对 HTML 响应运行 Readability（主内容提取）。
|
||||
</Step>
|
||||
<Step title="回退（可选）">
|
||||
如果 Readability 失败且已配置 Firecrawl，则通过带机器人规避模式的 Firecrawl API 重试。
|
||||
<Step title="Fallback (optional)">
|
||||
如果 Readability 失败且已配置 Firecrawl，则通过
|
||||
Firecrawl API 使用绕过机器人检测模式重试。
|
||||
</Step>
|
||||
<Step title="缓存">
|
||||
结果会缓存 15 分钟（可配置），以减少对同一 URL 的重复获取。
|
||||
<Step title="Cache">
|
||||
结果会缓存 15 分钟（可配置），以减少对同一 URL 的重复
|
||||
获取。
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
@ -87,10 +91,10 @@ await web_fetch({ url: "https://example.com/article" });
|
||||
}
|
||||
```
|
||||
|
||||
## Firecrawl 回退
|
||||
## Firecrawl 兜底
|
||||
|
||||
如果 Readability 提取失败，`web_fetch` 可以回退到
|
||||
[Firecrawl](/zh-CN/tools/firecrawl)，用于机器人规避和更好的提取：
|
||||
[Firecrawl](/zh-CN/tools/firecrawl)，用于绕过机器人检测并获得更好的提取效果：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -120,42 +124,59 @@ await web_fetch({ url: "https://example.com/article" });
|
||||
}
|
||||
```
|
||||
|
||||
`plugins.entries.firecrawl.config.webFetch.apiKey` 支持 SecretRef 对象。旧版 `tools.web.fetch.firecrawl.*` 配置会由 `openclaw doctor --fix` 自动迁移。
|
||||
`plugins.entries.firecrawl.config.webFetch.apiKey` 支持 SecretRef 对象。
|
||||
旧版 `tools.web.fetch.firecrawl.*` 配置会由 `openclaw doctor --fix` 自动迁移。
|
||||
|
||||
<Note>
|
||||
如果 Firecrawl 已启用，并且其 SecretRef 未解析且没有 `FIRECRAWL_API_KEY` 环境变量回退，Gateway 网关启动会快速失败。
|
||||
如果 Firecrawl 已启用，且其 SecretRef 未解析，并且没有
|
||||
`FIRECRAWL_API_KEY` 环境变量兜底，Gateway 网关启动会快速失败。
|
||||
</Note>
|
||||
|
||||
<Note>
|
||||
Firecrawl `baseUrl` 覆盖会被锁定：托管流量使用 `https://api.firecrawl.dev`；自托管覆盖必须指向私有或内部端点，并且 `http://` 仅对这些私有目标可接受。
|
||||
Firecrawl `baseUrl` 覆盖会被锁定：托管流量使用
|
||||
`https://api.firecrawl.dev`；自托管覆盖必须指向私有或
|
||||
内部端点，并且 `http://` 仅对这些私有目标接受。
|
||||
</Note>
|
||||
|
||||
当前运行时行为：
|
||||
|
||||
- `tools.web.fetch.provider` 会显式选择获取回退提供商。
|
||||
- 如果省略 `provider`，OpenClaw 会从可用凭证中自动检测第一个就绪的 Web 获取提供商。非沙箱隔离的 `web_fetch` 可以使用已安装的插件，这些插件声明 `contracts.webFetchProviders` 并在运行时注册匹配的提供商。目前内置提供商是 Firecrawl。
|
||||
- `tools.web.fetch.provider` 会显式选择获取兜底提供商。
|
||||
- 如果省略 `provider`，OpenClaw 会根据可用凭证自动检测第一个就绪的 web-fetch
|
||||
提供商。非沙箱隔离的 `web_fetch` 可以使用已安装的插件，这些插件声明
|
||||
`contracts.webFetchProviders` 并在运行时注册匹配的提供商。目前内置提供商是 Firecrawl。
|
||||
- 沙箱隔离的 `web_fetch` 调用仍仅限于内置提供商。
|
||||
- 如果禁用 Readability，`web_fetch` 会直接跳到选定的提供商回退。如果没有可用提供商，它会以封闭方式失败。
|
||||
- 如果禁用 Readability，`web_fetch` 会直接跳到所选的
|
||||
提供商兜底。如果没有可用提供商，它会默认拒绝并失败。
|
||||
|
||||
## 可信环境代理
|
||||
## 受信任的环境代理
|
||||
|
||||
如果你的部署要求 `web_fetch` 通过可信的出站 HTTP(S) 代理，请设置 `tools.web.fetch.useTrustedEnvProxy: true`。
|
||||
如果你的部署要求 `web_fetch` 通过受信任的出站
|
||||
HTTP(S) 代理，请设置 `tools.web.fetch.useTrustedEnvProxy: true`。
|
||||
|
||||
在此模式下，OpenClaw 仍会在发送请求前应用基于主机名的 SSRF 检查，但会让代理解析 DNS，而不是执行本地 DNS 固定。仅当该代理由操作方控制，并在 DNS 解析后强制执行出站策略时，才启用此选项。
|
||||
在此模式下，OpenClaw 仍会在发送请求前应用基于主机名的 SSRF 检查，
|
||||
但会让代理解析 DNS，而不是执行本地 DNS 固定。仅当该代理由操作员控制，
|
||||
并且在 DNS 解析后仍强制执行出站策略时，才启用此项。
|
||||
|
||||
<Note>
|
||||
如果未配置 HTTP(S) 代理环境变量，或目标主机被 `NO_PROXY` 排除，`web_fetch` 会回退到带本地 DNS 固定的普通严格路径。
|
||||
如果未配置 HTTP(S) 代理环境变量，或者目标主机被
|
||||
`NO_PROXY` 排除，`web_fetch` 会回退到使用本地 DNS
|
||||
固定的常规严格路径。
|
||||
</Note>
|
||||
|
||||
## 限制与安全
|
||||
## 限制和安全性
|
||||
|
||||
- `maxChars` 会被限制到 `tools.web.fetch.maxCharsCap`
|
||||
- 响应体在解析前会被限制为 `maxResponseBytes`；超大响应会被截断并附带警告
|
||||
- `maxChars` 会被限制在 `tools.web.fetch.maxCharsCap` 以内
|
||||
- 响应正文在解析前会被限制为 `maxResponseBytes`；超大的
|
||||
响应会被截断并带有警告
|
||||
- 私有/内部主机名会被阻止
|
||||
- `tools.web.fetch.ssrfPolicy.allowRfc2544BenchmarkRange` 和 `tools.web.fetch.ssrfPolicy.allowIpv6UniqueLocalRange` 是面向可信假 IP 代理栈的窄范围选择加入项；除非你的代理拥有这些合成范围并强制执行自己的目标策略，否则请保持未设置
|
||||
- `tools.web.fetch.ssrfPolicy.allowRfc2544BenchmarkRange` 和
|
||||
`tools.web.fetch.ssrfPolicy.allowIpv6UniqueLocalRange` 是针对
|
||||
受信任假 IP 代理栈的窄范围选择启用项；除非你的代理拥有
|
||||
这些合成地址范围并强制执行自己的目标策略，否则请保持未设置
|
||||
- 重定向会被检查，并受 `maxRedirects` 限制
|
||||
- `useTrustedEnvProxy` 是显式选择加入项，只应为由操作方控制、且在 DNS 解析后仍会强制执行出站策略的代理启用
|
||||
- `web_fetch` 是尽力而为的工具，有些站点需要使用 [Web 浏览器](/zh-CN/tools/browser)
|
||||
- `useTrustedEnvProxy` 是显式选择启用项，并且只应为
|
||||
由操作员控制、在 DNS 解析后仍强制执行出站策略的代理启用
|
||||
- `web_fetch` 是尽力而为的工具，有些站点需要使用 [Web Browser](/zh-CN/tools/browser)
|
||||
|
||||
## 工具配置文件
|
||||
|
||||
@ -172,6 +193,6 @@ await web_fetch({ url: "https://example.com/article" });
|
||||
|
||||
## 相关内容
|
||||
|
||||
- [Web 搜索](/zh-CN/tools/web) -- 使用多个提供商搜索网页
|
||||
- [Web 浏览器](/zh-CN/tools/browser) -- 面向重度依赖 JS 站点的完整浏览器自动化
|
||||
- [Web Search](/zh-CN/tools/web) -- 使用多个提供商搜索 Web
|
||||
- [Web Browser](/zh-CN/tools/browser) -- 面向大量依赖 JS 的站点的完整浏览器自动化
|
||||
- [Firecrawl](/zh-CN/tools/firecrawl) -- Firecrawl 搜索和抓取工具
|
||||
|
||||
Loading…
Reference in New Issue
Block a user