chore(i18n): refresh zh-CN translations
This commit is contained in:
openclaw-docs-i18n[bot]
parent
789ad8e11b
commit
23367a33d2
File diff suppressed because it is too large
Load Diff
@ -1,27 +1,24 @@
|
||||
---
|
||||
read_when:
|
||||
- 你需要从插件中调用核心辅助工具（TTS、STT、图像生成、Web 搜索、subagent）
|
||||
- 你需要从插件中调用核心辅助工具（TTS、STT、图像生成、Web 搜索、子智能体）
|
||||
- 你想了解 `api.runtime` 暴露了什么
|
||||
- 你正在从插件代码中访问配置、智能体或媒体辅助工具
|
||||
sidebarTitle: Runtime Helpers
|
||||
summary: api.runtime —— 可供插件使用的注入式运行时辅助工具
|
||||
title: 插件运行时辅助工具
|
||||
x-i18n:
|
||||
generated_at: "2026-04-23T20:58:07Z"
|
||||
generated_at: "2026-04-23T22:45:07Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 9025693a82c89c1a5b7f72771a34aa2f14836d2987424cec5b3eb3252a1ad82a
|
||||
source_hash: 63069008df16baebbe1ad0189af9002761d3829c4a71bdbf9d753fc51d40741f
|
||||
source_path: plugins/sdk-runtime.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
关于 `api.runtime` 对象的参考，它会在插件注册期间注入到每个插件中。
|
||||
请使用这些辅助工具，而不要直接导入主机内部实现。
|
||||
在注册期间注入到每个插件中的 `api.runtime` 对象参考。请使用这些辅助工具，而不要直接导入宿主内部实现。
|
||||
|
||||
<Tip>
|
||||
**想看完整示例？** 请参见 [渠道插件](/zh-CN/plugins/sdk-channel-plugins)
|
||||
或 [提供商插件](/zh-CN/plugins/sdk-provider-plugins)，那里有分步骤指南，
|
||||
会结合上下文展示这些辅助工具的使用方式。
|
||||
**想看操作演练？** 请参阅 [渠道插件](/zh-CN/plugins/sdk-channel-plugins) 或 [提供商插件](/zh-CN/plugins/sdk-provider-plugins) 中的分步指南，这些指南会结合上下文展示这些辅助工具的用法。
|
||||
</Tip>
|
||||
|
||||
```typescript
|
||||
@ -46,16 +43,16 @@ const workspaceDir = api.runtime.agent.resolveAgentWorkspaceDir(cfg);
|
||||
// 获取智能体身份
|
||||
const identity = api.runtime.agent.resolveAgentIdentity(cfg);
|
||||
|
||||
// 获取默认 thinking 级别
|
||||
// 获取默认思考级别
|
||||
const thinking = api.runtime.agent.resolveThinkingDefault(cfg, provider, model);
|
||||
|
||||
// 获取智能体超时
|
||||
// 获取智能体超时时间
|
||||
const timeoutMs = api.runtime.agent.resolveAgentTimeoutMs(cfg);
|
||||
|
||||
// 确保工作区存在
|
||||
await api.runtime.agent.ensureAgentWorkspace(cfg);
|
||||
|
||||
// 运行一个嵌入式智能体轮次
|
||||
// 运行一次嵌入式智能体回合
|
||||
const agentDir = api.runtime.agent.resolveAgentDir(cfg);
|
||||
const result = await api.runtime.agent.runEmbeddedAgent({
|
||||
sessionId: "my-plugin:task-1",
|
||||
@ -67,13 +64,11 @@ const result = await api.runtime.agent.runEmbeddedAgent({
|
||||
});
|
||||
```
|
||||
|
||||
`runEmbeddedAgent(...)` 是从插件代码启动普通 OpenClaw
|
||||
智能体轮次的中性辅助工具。它使用与渠道触发回复相同的提供商/模型解析和
|
||||
agent-harness 选择逻辑。
|
||||
`runEmbeddedAgent(...)` 是用于从插件代码中启动标准 OpenClaw 智能体回合的中立辅助工具。它使用与渠道触发回复相同的 provider/模型解析和智能体 harness 选择逻辑。
|
||||
|
||||
`runEmbeddedPiAgent(...)` 仍保留作为兼容性别名。
|
||||
`runEmbeddedPiAgent(...)` 仍然保留为兼容性别名。
|
||||
|
||||
**会话存储辅助工具**位于 `api.runtime.agent.session` 下：
|
||||
**会话存储辅助工具** 位于 `api.runtime.agent.session` 下：
|
||||
|
||||
```typescript
|
||||
const storePath = api.runtime.agent.session.resolveStorePath(cfg);
|
||||
@ -93,15 +88,15 @@ const provider = api.runtime.agent.defaults.provider; // 例如 "anthropic"
|
||||
|
||||
### `api.runtime.subagent`
|
||||
|
||||
启动和管理后台 subagent 运行。
|
||||
启动和管理后台子智能体运行。
|
||||
|
||||
```typescript
|
||||
// 启动一次 subagent 运行
|
||||
// 启动一次子智能体运行
|
||||
const { runId } = await api.runtime.subagent.run({
|
||||
sessionKey: "agent:main:subagent:search-helper",
|
||||
message: "Expand this query into focused follow-up searches.",
|
||||
provider: "openai", // 可选覆盖项
|
||||
model: "gpt-4.1-mini", // 可选覆盖项
|
||||
provider: "openai", // 可选覆盖
|
||||
model: "gpt-4.1-mini", // 可选覆盖
|
||||
deliver: false,
|
||||
});
|
||||
|
||||
@ -121,16 +116,13 @@ await api.runtime.subagent.deleteSession({
|
||||
```
|
||||
|
||||
<Warning>
|
||||
模型覆盖（`provider`/`model`）需要通过配置中的
|
||||
`plugins.entries.<id>.subagent.allowModelOverride: true`
|
||||
进行 operator 显式启用。
|
||||
不受信任插件仍可运行 subagents，但覆盖请求会被拒绝。
|
||||
模型覆盖（`provider`/`model`）需要操作员在配置中显式启用 `plugins.entries.<id>.subagent.allowModelOverride: true`。
|
||||
不受信任的插件仍然可以运行子智能体，但覆盖请求会被拒绝。
|
||||
</Warning>
|
||||
|
||||
### `api.runtime.taskFlow`
|
||||
|
||||
将 Task Flow 运行时绑定到现有 OpenClaw 会话键或受信任的工具
|
||||
上下文，然后无需在每次调用时传入 owner，就可以创建和管理 Task Flow。
|
||||
将 Task Flow 运行时绑定到现有的 OpenClaw 会话键或受信任的工具上下文，然后在无需每次调用都传入所有者的情况下创建和管理 Task Flow。
|
||||
|
||||
```typescript
|
||||
const taskFlow = api.runtime.taskFlow.fromToolContext(ctx);
|
||||
@ -157,9 +149,7 @@ const waiting = taskFlow.setWaiting({
|
||||
});
|
||||
```
|
||||
|
||||
当你已经从自己的绑定层中拿到了一个受信任的 OpenClaw 会话键时，请使用
|
||||
`bindSession({ sessionKey, requesterOrigin })`。不要从原始
|
||||
用户输入中进行绑定。
|
||||
当你已经从自己的绑定层获得一个受信任的 OpenClaw 会话键时，请使用 `bindSession({ sessionKey, requesterOrigin })`。不要从原始用户输入进行绑定。
|
||||
|
||||
### `api.runtime.tts`
|
||||
|
||||
@ -172,21 +162,20 @@ const clip = await api.runtime.tts.textToSpeech({
|
||||
cfg: api.config,
|
||||
});
|
||||
|
||||
// 电信优化 TTS
|
||||
// 面向电话场景优化的 TTS
|
||||
const telephonyClip = await api.runtime.tts.textToSpeechTelephony({
|
||||
text: "Hello from OpenClaw",
|
||||
cfg: api.config,
|
||||
});
|
||||
|
||||
// 列出可用语音
|
||||
// 列出可用音色
|
||||
const voices = await api.runtime.tts.listVoices({
|
||||
provider: "elevenlabs",
|
||||
cfg: api.config,
|
||||
});
|
||||
```
|
||||
|
||||
使用核心 `messages.tts` 配置和提供商选择。返回 PCM 音频
|
||||
buffer + 采样率。
|
||||
使用核心 `messages.tts` 配置和提供商选择。返回 PCM 音频缓冲区和采样率。
|
||||
|
||||
### `api.runtime.mediaUnderstanding`
|
||||
|
||||
@ -204,7 +193,7 @@ const image = await api.runtime.mediaUnderstanding.describeImageFile({
|
||||
const { text } = await api.runtime.mediaUnderstanding.transcribeAudioFile({
|
||||
filePath: "/tmp/inbound-audio.ogg",
|
||||
cfg: api.config,
|
||||
mime: "audio/ogg", // 可选，用于无法推断 MIME 时
|
||||
mime: "audio/ogg", // 可选，用于无法推断 MIME 的情况
|
||||
});
|
||||
|
||||
// 描述视频
|
||||
@ -220,11 +209,10 @@ const result = await api.runtime.mediaUnderstanding.runFile({
|
||||
});
|
||||
```
|
||||
|
||||
当没有生成输出时（例如输入被跳过），返回 `{ text: undefined }`。
|
||||
当未产生输出时（例如输入被跳过），返回 `{ text: undefined }`。
|
||||
|
||||
<Info>
|
||||
`api.runtime.stt.transcribeAudioFile(...)` 仍保留为
|
||||
`api.runtime.mediaUnderstanding.transcribeAudioFile(...)` 的兼容性别名。
|
||||
`api.runtime.stt.transcribeAudioFile(...)` 仍然保留为 `api.runtime.mediaUnderstanding.transcribeAudioFile(...)` 的兼容性别名。
|
||||
</Info>
|
||||
|
||||
### `api.runtime.imageGeneration`
|
||||
@ -255,7 +243,7 @@ const result = await api.runtime.webSearch.search({
|
||||
|
||||
### `api.runtime.media`
|
||||
|
||||
底层媒体辅助工具。
|
||||
底层媒体实用工具。
|
||||
|
||||
```typescript
|
||||
const webMedia = await api.runtime.media.loadWebMedia(url);
|
||||
@ -269,11 +257,18 @@ const pngQr = await api.runtime.media.renderQrPngBase64("https://openclaw.ai", {
|
||||
scale: 6, // 1-12
|
||||
marginModules: 4, // 0-16
|
||||
});
|
||||
const pngQrDataUrl = await api.runtime.media.renderQrPngDataUrl("https://openclaw.ai");
|
||||
const tmpRoot = resolvePreferredOpenClawTmpDir();
|
||||
const pngQrFile = await api.runtime.media.writeQrPngTempFile("https://openclaw.ai", {
|
||||
tmpRoot,
|
||||
dirPrefix: "my-plugin-qr-",
|
||||
fileName: "qr.png",
|
||||
});
|
||||
```
|
||||
|
||||
### `api.runtime.config`
|
||||
|
||||
配置加载与写入。
|
||||
配置加载和写入。
|
||||
|
||||
```typescript
|
||||
const cfg = await api.runtime.config.loadConfig();
|
||||
@ -282,7 +277,7 @@ await api.runtime.config.writeConfigFile(cfg);
|
||||
|
||||
### `api.runtime.system`
|
||||
|
||||
系统级辅助工具。
|
||||
系统级实用工具。
|
||||
|
||||
```typescript
|
||||
await api.runtime.system.enqueueSystemEvent(event);
|
||||
@ -306,7 +301,7 @@ api.runtime.events.onSessionTranscriptUpdate((update) => {
|
||||
|
||||
### `api.runtime.logging`
|
||||
|
||||
日志。
|
||||
日志记录。
|
||||
|
||||
```typescript
|
||||
const verbose = api.runtime.logging.shouldLogVerbose();
|
||||
@ -315,7 +310,7 @@ const childLogger = api.runtime.logging.getChildLogger({ plugin: "my-plugin" },
|
||||
|
||||
### `api.runtime.modelAuth`
|
||||
|
||||
模型与提供商认证解析。
|
||||
模型和提供商凭证解析。
|
||||
|
||||
```typescript
|
||||
const auth = await api.runtime.modelAuth.getApiKeyForModel({ model, cfg });
|
||||
@ -335,7 +330,7 @@ const stateDir = api.runtime.state.resolveStateDir();
|
||||
|
||||
### `api.runtime.tools`
|
||||
|
||||
Memory 工具工厂与 CLI。
|
||||
Memory 工具工厂和 CLI。
|
||||
|
||||
```typescript
|
||||
const getTool = api.runtime.tools.createMemoryGetTool(/* ... */);
|
||||
@ -345,9 +340,9 @@ api.runtime.tools.registerMemoryCli(/* ... */);
|
||||
|
||||
### `api.runtime.channel`
|
||||
|
||||
渠道特定运行时辅助工具（在加载渠道插件时可用）。
|
||||
渠道特定的运行时辅助工具（在加载渠道插件时可用）。
|
||||
|
||||
`api.runtime.channel.mentions` 是供使用运行时注入的内置渠道插件使用的共享入站提及策略表面：
|
||||
`api.runtime.channel.mentions` 是供使用运行时注入的内置渠道插件共享的入站提及策略接口：
|
||||
|
||||
```typescript
|
||||
const mentionMatch = api.runtime.channel.mentions.matchesMentionWithExplicit(text, {
|
||||
@ -382,14 +377,11 @@ const decision = api.runtime.channel.mentions.resolveInboundMentionDecision({
|
||||
- `implicitMentionKindWhen`
|
||||
- `resolveInboundMentionDecision`
|
||||
|
||||
`api.runtime.channel.mentions` 有意不暴露旧版的
|
||||
`resolveMentionGating*` 兼容性辅助工具。请优先使用规范化后的
|
||||
`{ facts, policy }` 路径。
|
||||
`api.runtime.channel.mentions` 有意不暴露旧版的 `resolveMentionGating*` 兼容性辅助工具。请优先使用标准化的 `{ facts, policy }` 路径。
|
||||
|
||||
## 存储运行时引用
|
||||
|
||||
使用 `createPluginRuntimeStore` 存储运行时引用，以便在
|
||||
`register` 回调之外使用：
|
||||
使用 `createPluginRuntimeStore` 存储运行时引用，以便在 `register` 回调之外使用：
|
||||
|
||||
```typescript
|
||||
import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store";
|
||||
@ -411,33 +403,32 @@ export default defineChannelPluginEntry({
|
||||
|
||||
// 在其他文件中
|
||||
export function getRuntime() {
|
||||
return store.getRuntime(); // 未初始化时抛出异常
|
||||
return store.getRuntime(); // 如果未初始化则抛出异常
|
||||
}
|
||||
|
||||
export function tryGetRuntime() {
|
||||
return store.tryGetRuntime(); // 未初始化时返回 null
|
||||
return store.tryGetRuntime(); // 如果未初始化则返回 null
|
||||
}
|
||||
```
|
||||
|
||||
对于 runtime-store 标识，优先使用 `pluginId`。较低层级的 `key` 形式
|
||||
适用于少见情况，即一个插件有意需要多个运行时槽位时。
|
||||
对于运行时存储的标识，优先使用 `pluginId`。更底层的 `key` 形式适用于少见场景，即某个插件有意需要多个运行时槽位。
|
||||
|
||||
## 其他顶级 `api` 字段
|
||||
## 其他顶层 `api` 字段
|
||||
|
||||
除 `api.runtime` 之外，API 对象还提供：
|
||||
除了 `api.runtime` 之外，API 对象还提供：
|
||||
|
||||
| 字段 | 类型 | 描述 |
|
||||
| ------------------------ | ------------------------- | ------------------------------------------------------------------------------------------- |
|
||||
| `api.id` | `string` | 插件 ID |
|
||||
| `api.name` | `string` | 插件显示名称 |
|
||||
| `api.config` | `OpenClawConfig` | 当前配置快照（可用时为活动的内存运行时快照） |
|
||||
| `api.pluginConfig` | `Record<string, unknown>` | 来自 `plugins.entries.<id>.config` 的插件专属配置 |
|
||||
| `api.logger` | `PluginLogger` | 带作用域的日志记录器（`debug`、`info`、`warn`、`error`） |
|
||||
| `api.registrationMode` | `PluginRegistrationMode` | 当前加载模式；`"setup-runtime"` 是完整入口前的轻量启动/设置窗口 |
|
||||
| `api.resolvePath(input)` | `(string) => string` | 解析相对于插件根目录的路径 |
|
||||
| `api.id` | `string` | 插件 id |
|
||||
| `api.name` | `string` | 插件显示名称 |
|
||||
| `api.config` | `OpenClawConfig` | 当前配置快照（在可用时为活动的内存中运行时快照） |
|
||||
| `api.pluginConfig` | `Record<string, unknown>` | 来自 `plugins.entries.<id>.config` 的插件专属配置 |
|
||||
| `api.logger` | `PluginLogger` | 作用域日志记录器（`debug`、`info`、`warn`、`error`） |
|
||||
| `api.registrationMode` | `PluginRegistrationMode` | 当前加载模式；`"setup-runtime"` 是完整入口启动/设置前的轻量级启动/设置窗口 |
|
||||
| `api.resolvePath(input)` | `(string) => string` | 解析相对于插件根目录的路径 |
|
||||
|
||||
## 相关内容
|
||||
|
||||
- [SDK 概览](/zh-CN/plugins/sdk-overview) -- 子路径参考
|
||||
- [SDK 入口点](/zh-CN/plugins/sdk-entrypoints) -- `definePluginEntry` 选项
|
||||
- [插件内部结构](/zh-CN/plugins/architecture) -- 能力模型与注册表
|
||||
- [插件内部机制](/zh-CN/plugins/architecture) -- 能力模型和注册表
|
||||
|
||||
Loading…
Reference in New Issue
Block a user