openclaw/docs
openclaw/docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore(i18n): refresh zh-CN translations

Browse Source
This commit is contained in:
openclaw-docs-i18n[bot] 2026-04-22 02:38:04 +00:00
parent 11cd1afd96
commit cd1a2bbdfd
2 changed files with 125 additions and 105 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

191
docs/zh-CN/pi.md
View File

@ -1,50 +1,50 @@
---
read_when:
- 理解 OpenClaw 中的 Pi SDK 集成设计
- 修改 Pi 的智能体会话生命周期、工具或提供商接线方式
summary: OpenClaw 的内置 Pi 智能体集成架构和会话生命周期
- 理解 OpenClaw 中 Pi SDK 集成设计
- 修改 Pi 的智能体会话生命周期、工具能力或提供商接线
summary: OpenClaw 内置 Pi 智能体集成的架构与会话生命周期
title: Pi 集成架构
x-i18n:
generated_at: "2026-04-20T18:49:33Z"
generated_at: "2026-04-22T02:37:02Z"
model: gpt-5.4
provider: openai
source_hash: ece62eb1459e8a861610c8502f2b3bf5172500207df5e78f4abe7a2a416a47fc
source_hash: 0ab2934958cd699b585ce57da5ac3077754d46725e74a8e604afc14d2b4ca022
source_path: pi.md
workflow: 15
---
# Pi 集成架构
本文档介绍了 OpenClaw 如何与 [pi-coding-agent](https://github.com/badlogic/pi-mono/tree/main/packages/coding-agent) 及其同级软件包（`pi-ai`、`pi-agent-core`、`pi-tui`）集成，以支撑其 AI 智能体能力。
本文档介绍 OpenClaw 如何与 [pi-coding-agent](https://github.com/badlogic/pi-mono/tree/main/packages/coding-agent) 及其同级包（`pi-ai`、`pi-agent-core`、`pi-tui`）集成，以驱动其 AI 智能体能力。
## 概览
## 概述
OpenClaw 使用 pi SDK，将一个 AI 编码智能体嵌入到其消息 Gateway 网关架构中。OpenClaw 不会将 pi 作为子进程启动，也不使用 RPC 模式，而是通过 `createAgentSession()` 直接导入并实例化 pi 的 `AgentSession`。这种内嵌方式提供了：
OpenClaw 使用 pi SDK，将一个 AI 编码智能体嵌入到其消息 Gateway 网关架构中。OpenClaw 不会将 pi 作为子进程启动，也不会使用 RPC 模式，而是通过 `createAgentSession()` 直接导入并实例化 pi 的 `AgentSession`。这种内嵌方式提供了：
- 对会话生命周期和事件处理的完全控制
- 自定义工具注入（消息、沙箱、渠道特定操作）
- 按渠道/上下文定制系统提示词
- 支持分支/压缩的会话持久化
- 带故障转移的多账号凭证配置轮换
- 支持故障切换的多账户凭证配置轮换
- 与提供商无关的模型切换
## 软件包依赖
## 包依赖
```json
{
"@mariozechner/pi-agent-core": "0.64.0",
"@mariozechner/pi-ai": "0.64.0",
"@mariozechner/pi-coding-agent": "0.64.0",
"@mariozechner/pi-tui": "0.64.0"
"@mariozechner/pi-agent-core": "0.68.1",
"@mariozechner/pi-ai": "0.68.1",
"@mariozechner/pi-coding-agent": "0.68.1",
"@mariozechner/pi-tui": "0.68.1"
}
```
| Package | 用途 |
| ----------------- | -------------------------------------------------------------------------------------- |
| `pi-ai` | 核心 LLM 抽象：`Model`、`streamSimple`、消息类型、提供商 API |
| `pi-agent-core` | 智能体循环、工具执行、`AgentMessage` 类型 |
| Package | 用途 |
| ----------------- | -------------------------------------------------------------------- |
| `pi-ai` | 核心 LLM 抽象：`Model`、`streamSimple`、消息类型、提供商 API |
| `pi-agent-core` | 智能体循环、工具执行、`AgentMessage` 类型 |
| `pi-coding-agent` | 高层 SDK：`createAgentSession`、`SessionManager`、`AuthStorage`、`ModelRegistry`、内置工具 |
| `pi-tui` | 终端 UI 组件（用于 OpenClaw 的本地 TUI 模式） |
| `pi-tui` | 终端 UI 组件（用于 OpenClaw 的本地 TUI 模式） |
## 文件结构
@ -59,7 +59,7 @@ src/agents/
│ │ ├── payloads.ts # 从运行结果构建响应负载
│ │ ├── images.ts # Vision 模型图像注入
│ │ └── types.ts # EmbeddedRunAttemptResult
│ ├── abort.ts # Abort 错误检测
│ ├── abort.ts # 中止错误检测
│ ├── cache-ttl.ts # 用于上下文裁剪的缓存 TTL 跟踪
│ ├── compact.ts # 手动/自动压缩逻辑
│ ├── extensions.ts # 为内嵌运行加载 pi 扩展
@ -68,13 +68,13 @@ src/agents/
│ ├── history.ts # 历史记录限制（私信 vs 群组）
│ ├── lanes.ts # 会话/全局命令通道
│ ├── logger.ts # 子系统日志记录器
│ ├── model.ts # 通过 ModelRegistry 进行模型解析
│ ├── runs.ts # 活跃运行跟踪、终止、排队
│ ├── model.ts # 通过 ModelRegistry 解析模型
│ ├── runs.ts # 活动运行跟踪、中止、队列
│ ├── sandbox-info.ts # 用于系统提示词的沙箱信息
│ ├── session-manager-cache.ts # SessionManager 实例缓存
│ ├── session-manager-init.ts # 会话文件初始化
│ ├── system-prompt.ts # 系统提示词构建器
│ ├── tool-split.ts # 将工具拆分为 builtIn 和 custom
│ ├── tool-split.ts # 将工具拆分为 builtIn 与 custom
│ ├── types.ts # EmbeddedPiAgentMeta、EmbeddedPiRunResult
│ └── utils.ts # ThinkLevel 映射、错误描述
├── pi-embedded-subscribe.ts # 会话事件订阅/分发
@ -82,16 +82,16 @@ src/agents/
├── pi-embedded-subscribe.handlers.ts # 事件处理器工厂
├── pi-embedded-subscribe.handlers.lifecycle.ts
├── pi-embedded-subscribe.handlers.types.ts
├── pi-embedded-block-chunker.ts # 流式块回复分块
├── pi-embedded-messaging.ts # 消息工具已发送跟踪
├── pi-embedded-helpers.ts # 错误分类、轮次校验
├── pi-embedded-block-chunker.ts # 流式分块回复切块
├── pi-embedded-messaging.ts # 消息工具发送跟踪
├── pi-embedded-helpers.ts # 错误分类、轮次验证
├── pi-embedded-helpers/ # 辅助模块
├── pi-embedded-utils.ts # 格式化工具函数
├── pi-embedded-utils.ts # 格式化工具
├── pi-tools.ts # createOpenClawCodingTools()
├── pi-tools.abort.ts # 工具的 AbortSignal 包装
├── pi-tools.abort.ts # 用于工具的 AbortSignal 包装
├── pi-tools.policy.ts # 工具允许列表/拒绝列表策略
├── pi-tools.read.ts # Read 工具自定义
├── pi-tools.schema.ts # 工具 schema 标准化
├── pi-tools.read.ts # Read 工具定制
├── pi-tools.schema.ts # 工具 schema 规范化
├── pi-tools.types.ts # AnyAgentTool 类型别名
├── pi-tool-definition-adapter.ts # AgentTool -> ToolDefinition 适配器
├── pi-settings.ts # 设置覆盖
@ -101,9 +101,9 @@ src/agents/
│ ├── context-pruning.ts # 缓存 TTL 上下文裁剪扩展
│ └── context-pruning/
├── model-auth.ts # 凭证配置解析
├── auth-profiles.ts # 配置存储、冷却、故障转移
├── auth-profiles.ts # 配置存储、冷却、故障切换
├── model-selection.ts # 默认模型解析
├── models-config.ts # `models.json` 生成
├── models-config.ts # 生成 models.json
├── model-catalog.ts # 模型目录缓存
├── context-window-guard.ts # 上下文窗口校验
├── failover-error.ts # FailoverError 类
@ -113,9 +113,9 @@ src/agents/
├── system-prompt-report.ts # 调试报告生成
├── tool-summaries.ts # 工具描述摘要
├── tool-policy.ts # 工具策略解析
├── transcript-policy.ts # 转录校验策略
├── skills.ts # Skill 快照/提示词构建
├── skills/ # Skill 子系统
├── transcript-policy.ts # Transcript 校验策略
├── skills.ts # Skills 快照/提示词构建
├── skills/ # Skills 子系统
├── sandbox.ts # 沙箱上下文解析
├── sandbox/ # 沙箱子系统
├── channel-tools.ts # 渠道特定工具注入
@ -136,7 +136,7 @@ src/agents/
└── ...
```
渠道特定的消息操作运行时现在位于由插件拥有的扩展目录中，而不是放在 `src/agents/tools` 下，例如：
渠道特定的消息操作运行时现在位于插件自有的扩展目录中，而不再位于 `src/agents/tools` 下，例如：
- Discord 插件操作运行时文件
- Slack 插件操作运行时文件
@ -171,7 +171,7 @@ const result = await runEmbeddedPiAgent({
### 2. 创建会话
在 `runEmbeddedAttempt()`（由 `runEmbeddedPiAgent()` 调用）内部，会使用 pi SDK：
在 `runEmbeddedAttempt()`（由 `runEmbeddedPiAgent()` 调用）内部，使用了 pi SDK：
```typescript
import {
@ -233,7 +233,7 @@ const subscription = subscribeEmbeddedPiSession({
- `agent_start` / `agent_end`
- `compaction_start` / `compaction_end`
### 4. 提示
### 4. 提示输入
完成设置后，会向会话发送提示：
@ -243,23 +243,23 @@ await session.prompt(effectivePrompt, { images: imageResult.images });
SDK 会处理完整的智能体循环：发送到 LLM、执行工具调用、流式返回响应。
图像注入仅限当前提示：OpenClaw 会从当前提示中加载图像引用，并通过 `images` 仅传入该轮。它不会重新扫描更早的历史轮次来重新注入图像负载。
图像注入是提示词局部的：OpenClaw 从当前提示词中加载图像引用，并仅通过 `images` 将其传递给当前轮次。它不会重新扫描更早的历史轮次来重新注入图像负载。
## 工具架构
### 工具流水线
1. **基础工具**：pi 的 `codingTools`（read、bash、edit、write）
2. **自定义替换**：OpenClaw 用 `exec`/`process` 替换 bash，并为沙箱定制 read/edit/write
3. **OpenClaw 工具**：消息、浏览器、canvas、会话、cron、Gateway 网关 等
2. **自定义替换**：OpenClaw 将 bash 替换为 `exec`/`process`，并为沙箱定制 read/edit/write
3. **OpenClaw 工具**：消息、浏览器、画布、会话、cron、Gateway 网关等
4. **渠道工具**：Discord/Telegram/Slack/WhatsApp 特定操作工具
5. **策略过滤**：按配置、提供商、智能体、群组、沙箱策略过滤工具
6. **Schema 标准化**：为适配 Gemini/OpenAI 的特殊情况清理 schema
7. **AbortSignal 包装**：包装工具以支持 abort signals
6. **Schema 规范化**：为兼容 Gemini/OpenAI 的特殊行为而清理 schema
7. **AbortSignal 包装**：对工具进行包装，以遵守 abort signal
### 工具定义适配器
pi-agent-core 的 `AgentTool` 与 pi-coding-agent 的 `ToolDefinition` 在 `execute` 签名上不同。`pi-tool-definition-adapter.ts` 中的适配器负责桥接两者：
pi-agent-core 的 `AgentTool` 与 pi-coding-agent 的 `ToolDefinition` 具有不同的 `execute` 签名。`pi-tool-definition-adapter.ts` 中的适配器负责桥接二者：
```typescript
export function toToolDefinitions(tools: AnyAgentTool[]): ToolDefinition[] {
@ -269,7 +269,7 @@ export function toToolDefinitions(tools: AnyAgentTool[]): ToolDefinition[] {
description: tool.description ?? "",
parameters: tool.parameters,
execute: async (toolCallId, params, onUpdate, _ctx, signal) => {
// pi-coding-agent 签名与 pi-agent-core 不同
// pi-coding-agent 的签名与 pi-agent-core 不同
return await tool.execute(toolCallId, params, signal, onUpdate);
},
}));
@ -278,24 +278,24 @@ export function toToolDefinitions(tools: AnyAgentTool[]): ToolDefinition[] {
### 工具拆分策略
`splitSdkTools()` 会通过 `customTools` 传递所有工具：
`splitSdkTools()` 通过 `customTools` 传递全部工具：
```typescript
export function splitSdkTools(options: { tools: AnyAgentTool[]; sandboxEnabled: boolean }) {
return {
builtInTools: [], // 为空。我们覆盖所有内容
builtInTools: [], // 为空。我们会覆盖所有内容
customTools: toToolDefinitions(options.tools),
};
}
```
这可确保 OpenClaw 的策略过滤、沙箱集成和扩展工具集在不同提供商之间保持一致。
这可确保 OpenClaw 的策略过滤、沙箱集成和扩展工具集在各个提供商之间保持一致。
## 系统提示词构建
系统提示词在 `buildAgentSystemPrompt()`（`system-prompt.ts`）中构建。它会组装一个完整提示词，其中包含 Tooling、Tool Call Style、安全护栏、OpenClaw CLI 参考、Skills、文档、工作区、沙箱、消息、回复标签、语气、静默回复、心跳、运行时元数据，以及在启用时包含 Memory 和 Reactions，还支持可选的上下文文件和额外系统提示词内容。用于子智能体的最小提示词模式会对各个部分进行裁剪。
系统提示词在 `buildAgentSystemPrompt()`（`system-prompt.ts`）中构建。它会组装一个完整提示词，其中包含 Tooling、工具调用风格、安全护栏、OpenClaw CLI 参考、Skills、文档、工作区、沙箱、消息、回复标签、语气、静默回复、心跳、运行时元数据，以及在启用时包含的 Memory 和 Reactions，还包括可选的上下文文件和额外系统提示词内容。用于子智能体的最小提示词模式会对这些部分进行裁剪。
该提示词会在会话创建后通过 `applySystemPromptOverrideToSession()` 应用：
系统提示词会在会话创建后通过 `applySystemPromptOverrideToSession()` 应用：
```typescript
const systemPromptOverride = createSystemPromptOverride(appendPrompt);
@ -306,13 +306,13 @@ applySystemPromptOverrideToSession(session, systemPromptOverride);
### 会话文件
会话文件是带树状结构的 JSONL 文件（通过 id/parentId 链接）。Pi 的 `SessionManager` 负责持久化：
会话以 JSONL 文件存储，并具有树状结构（通过 id/parentId 链接）。pi 的 `SessionManager` 负责持久化：
```typescript
const sessionManager = SessionManager.open(params.sessionFile);
```
OpenClaw 使用 `guardSessionManager()` 对其进行包装，以确保工具结果的安全性。
OpenClaw 通过 `guardSessionManager()` 对其进行包装，以确保工具结果安全。
### 会话缓存
@ -326,11 +326,16 @@ trackSessionManagerAccess(params.sessionFile);
### 历史记录限制
`limitHistoryTurns()` 会根据渠道类型（私信 或群组）裁剪会话历史。
`limitHistoryTurns()` 会根据渠道类型（私信 与 群组）裁剪对话历史。
### 压缩
当上下文溢出时，会触发自动压缩。常见的溢出特征包括 `request_too_large`、`context length exceeded`、`input exceeds the maximum number of tokens`、`input token count exceeds the maximum number of input tokens`、`input is too long for the model` 以及 `ollama error: context length exceeded`。`compactEmbeddedPiSessionDirect()` 负责手动压缩：
当上下文溢出时会触发自动压缩。常见的溢出特征包括
`request_too_large`、`context length exceeded`、`input exceeds the
maximum number of tokens`、`input token count exceeds the maximum number of
input tokens`、`input is too long for the model`，以及 `ollama error: context
length exceeded`。`compactEmbeddedPiSessionDirect()` 负责处理手动
压缩：
```typescript
const compactResult = await compactEmbeddedPiSessionDirect({
@ -342,14 +347,14 @@ const compactResult = await compactEmbeddedPiSessionDirect({
### 凭证配置
OpenClaw 维护了一个凭证配置存储，为每个提供商支持多个 API key：
OpenClaw 维护一个凭证配置存储，为每个提供商保存多个 API 密钥：
```typescript
const authStore = ensureAuthProfileStore(agentDir, { allowKeychainPrompt: false });
const profileOrder = resolveAuthProfileOrder({ cfg, store: authStore, provider, preferredProfile });
```
配置在失败时会轮换，并带有冷却跟踪：
配置会在失败时轮换，并跟踪冷却状态：
```typescript
await markAuthProfileFailure({ store, profileId, reason, cfg, agentDir });
@ -372,9 +377,9 @@ const { model, error, authStorage, modelRegistry } = resolveModel(
authStorage.setRuntimeApiKey(model.provider, apiKeyInfo.apiKey);
```
### 故障转移
### 故障切换
如果已配置回退模型，`FailoverError` 会触发模型回退：
当配置了回退时，`FailoverError` 会触发模型回退：
```typescript
if (fallbackConfigured && isFailoverErrorMessage(errorText)) {
@ -390,7 +395,7 @@ if (fallbackConfigured && isFailoverErrorMessage(errorText)) {
## Pi 扩展
OpenClaw 会加载自定义 pi 扩展，以实现特定行为：
OpenClaw 会加载自定义 Pi 扩展，以实现专门行为：
### 压缩保护
@ -421,28 +426,28 @@ if (cfg?.agents?.defaults?.contextPruning?.mode === "cache-ttl") {
## 流式传输与分块回复
### 块分块
### 分块切块
`EmbeddedBlockChunker` 负责将流式文本管理为离散的回复块：
`EmbeddedBlockChunker` 负责将流式文本整理为离散的回复块：
```typescript
const blockChunker = blockChunking ? new EmbeddedBlockChunker(blockChunking) : null;
```
### 思考/最终标签剥离
### Thinking/Final 标签剥离
流式输出会经过处理，以去除 `<think>`/`<thinking>` 块，并提取 `<final>` 内容：
流式输出会经过处理，以剥离 `<think>`/`<thinking>` 块并提取 `<final>` 内容：
```typescript
const stripBlockTags = (text: string, state: { thinking: boolean; final: boolean }) => {
// 去除 <think>...</think> 内容
// 剥离 <think>...</think> 内容
// 如果 enforceFinalTag 为 true，则只返回 <final>...</final> 内容
};
```
### 回复指令
会解析并提取诸如 `[[media:url]]`、`[[voice]]`、`[[reply:id]]` 之类的回复指令：
会解析并提取 `[[media:url]]`、`[[voice]]`、`[[reply:id]]` 等回复指令：
```typescript
const { text: cleanedText, mediaUrls, audioAsVoice, replyToId } = consumeReplyDirectives(chunk);
@ -452,20 +457,20 @@ const { text: cleanedText, mediaUrls, audioAsVoice, replyToId } = consumeReplyDi
### 错误分类
`pi-embedded-helpers.ts` 会对错误进行分类，以便采取合适的处理方式：
`pi-embedded-helpers.ts` 会对错误进行分类，以便采取适当处理：
```typescript
isContextOverflowError(errorText) // 上下文过大
isCompactionFailureError(errorText) // 压缩失败
isAuthAssistantError(lastAssistant) // 认证失败
isRateLimitAssistantError(...) // 命中速率限制
isFailoverAssistantError(...) // 应触发故障转移
isRateLimitAssistantError(...) // 达到速率限制
isFailoverAssistantError(...) // 应执行故障切换
classifyFailoverReason(errorText) // "auth" | "rate_limit" | "quota" | "timeout" | ...
```
### 思考级别回退
### Thinking level 回退
如果某个思考级别不受支持，则会回退：
如果某个 thinking level 不受支持，则会回退：
```typescript
const fallbackThinking = pickFallbackThinkingLevel({
@ -480,7 +485,7 @@ if (fallbackThinking) {
## 沙箱集成
当启用沙箱模式时，工具和路径会受到约束：
启用沙箱模式时，工具和路径都会受到约束：
```typescript
const sandbox = await resolveSandboxContext({
@ -490,7 +495,7 @@ const sandbox = await resolveSandboxContext({
});
if (sandboxRoot) {
// 使用沙箱隔离的 read/edit/write 工具
// 使用经过沙箱隔离的 read/edit/write 工具
// Exec 在容器中运行
// Browser 使用 bridge URL
}
@ -500,22 +505,22 @@ if (sandboxRoot) {
### Anthropic
- 清理拒答魔法字符串
- 校验连续角色的轮次
- 严格执行上游 Pi 工具参数校验
- 拒绝魔术字符串清理
- 连续角色的轮次校验
- 严格的上游 Pi 工具参数校验
### Google/Gemini
- 由插件拥有的工具 schema 清理
- 插件自有的工具 schema 清理
### OpenAI
- 为 Codex 模型提供 `apply_patch` 工具
- 处理思考级别降级
- 面向 Codex 模型的 `apply_patch` 工具
- thinking level 降级处理
## TUI 集成
OpenClaw 还有一个本地 TUI 模式，可直接使用 pi-tui 组件：
OpenClaw 还提供本地 TUI 模式，可直接使用 pi-tui 组件：
```typescript
// src/tui/tui.ts
@ -524,27 +529,27 @@ import { ... } from "@mariozechner/pi-tui";
这提供了与 pi 原生模式类似的交互式终端体验。
## 与 Pi CLI 的主要区别
## 与 Pi CLI 的关键差异
| Aspect | Pi CLI | OpenClaw 内嵌版 |
| 方面 | Pi CLI | OpenClaw 内嵌模式 |
| --------------- | ----------------------- | ---------------------------------------------------------------------------------------------- |
| Invocation | `pi` 命令 / RPC | 通过 `createAgentSession()` 使用 SDK |
| Tools | 默认编码工具 | 自定义 OpenClaw 工具套件 |
| System prompt | AGENTS.md + 提示词 | 按渠道/上下文动态生成 |
| Session storage | `~/.pi/agent/sessions/` | `~/.openclaw/agents/<agentId>/sessions/`（或 `$OPENCLAW_STATE_DIR/agents/<agentId>/sessions/`） |
| Auth | 单一凭证 | 支持轮换的多配置 |
| Extensions | 从磁盘加载 | 以编程方式 + 磁盘路径加载 |
| Event handling | TUI 渲染 | 基于回调（`onBlockReply` 等） |
| 调用方式 | `pi` 命令 / RPC | 通过 `createAgentSession()` 使用 SDK |
| 工具 | 默认编码工具 | 自定义 OpenClaw 工具套件 |
| 系统提示词 | AGENTS.md + prompts | 按渠道/上下文动态生成 |
| 会话存储 | `~/.pi/agent/sessions/` | `~/.openclaw/agents/<agentId>/sessions/`（或 `$OPENCLAW_STATE_DIR/agents/<agentId>/sessions/`） |
| 认证 | 单一凭证 | 支持轮换的多配置 |
| 扩展 | 从磁盘加载 | 编程方式 + 磁盘路径 |
| 事件处理 | TUI 渲染 | 基于回调（`onBlockReply` 等） |
## 未来考虑
潜在需要重构的领域：
1. **工具签名对齐**：目前需要在 pi-agent-core 和 pi-coding-agent 签名之间进行适配
2. **Session manager 包装**：`guardSessionManager` 提高了安全性，但也增加了复杂度
1. **工具签名对齐**：当前需要在 pi-agent-core 与 pi-coding-agent 签名之间做适配
2. **Session manager 包装**：`guardSessionManager` 增加了安全性，但也提高了复杂度
3. **扩展加载**：可以更直接地使用 pi 的 `ResourceLoader`
4. **流式处理器复杂度**：`subscribeEmbeddedPiSession` 变得越来越庞大
5. **提供商特殊情况**：存在许多提供商特定代码路径，而这些可能本应由 pi 来处理
4. **流式处理器复杂度**：`subscribeEmbeddedPiSession` 已变得较大
5. **提供商特殊行为**：存在许多提供商特定代码路径，而 pi 未来可能可以统一处理这些问题
## 测试
@ -566,4 +571,4 @@ Pi 集成覆盖以下测试套件：
- `src/agents/pi-embedded-runner-extraparams.live.test.ts`（启用 `OPENCLAW_LIVE_TEST=1`）
当前运行命令请参见 [Pi 开发工作流](/zh-CN/pi-dev)。
关于当前运行命令，请参见 [Pi Development Workflow](/zh-CN/pi-dev)。

39
docs/zh-CN/providers/opencode-go.md
View File

@ -2,13 +2,13 @@
read_when:
- 你想要 OpenCode Go 目录
- 你需要 Go 托管模型的运行时模型引用
summary: 使用共享的 OpenCode 设置配合 OpenCode Go 目录
summary: 使用共享 OpenCode 设置中的 OpenCode Go 目录目录
title: OpenCode Go
x-i18n:
generated_at: "2026-04-12T10:38:50Z"
generated_at: "2026-04-22T02:37:04Z"
model: gpt-5.4
provider: openai
source_hash: d1f0f182de81729616ccc19125d93ba0445de2349daf7067b52e8c15b9d3539c
source_hash: bb03bc609f0dfff2981eac13b67cbcae066184f4606ce54ba24ca6a5737fdae8
source_path: providers/opencode-go.md
workflow: 15
---
@ -16,7 +16,7 @@ x-i18n:
# OpenCode Go
OpenCode Go 是 [OpenCode](/zh-CN/providers/opencode) 中的 Go 目录。
它使用与 Zen 目录相同的 `OPENCODE_API_KEY`，但保留运行时提供商 id `opencode-go`，这样上游的按模型路由就能保持正确。
它与 Zen 目录使用相同的 `OPENCODE_API_KEY`，但保留运行时提供商 id `opencode-go`，这样上游的按模型路由才能保持正确。
| 属性 | 值 |
| ---------------- | ------------------------------- |
@ -26,11 +26,23 @@ OpenCode Go 是 [OpenCode](/zh-CN/providers/opencode) 中的 Go 目录。
## 支持的模型
OpenClaw 从内置的 Pi 模型注册表中获取 Go 目录。运行
`openclaw models list --provider opencode-go` 查看当前模型列表。
根据当前内置的 Pi 目录，该提供商包含：
| 模型引用 | 名称 |
| -------------------------- | ------------ |
| -------------------------- | --------------------- |
| `opencode-go/glm-5` | GLM-5 |
| `opencode-go/glm-5.1` | GLM-5.1 |
| `opencode-go/kimi-k2.5` | Kimi K2.5 |
| `opencode-go/glm-5` | GLM 5 |
| `opencode-go/kimi-k2.6` | Kimi K2.6（3 倍限制） |
| `opencode-go/mimo-v2-omni` | MiMo V2 Omni |
| `opencode-go/mimo-v2-pro` | MiMo V2 Pro |
| `opencode-go/minimax-m2.5` | MiniMax M2.5 |
| `opencode-go/minimax-m2.7` | MiniMax M2.7 |
| `opencode-go/qwen3.5-plus` | Qwen3.5 Plus |
| `opencode-go/qwen3.6-plus` | Qwen3.6 Plus |
## 入门指南
@ -84,21 +96,24 @@ OpenCode Go 是 [OpenCode](/zh-CN/providers/opencode) 中的 Go 目录。
<AccordionGroup>
<Accordion title="路由行为">
当模型引用使用 `opencode-go/...` 时，OpenClaw 会自动处理按模型路由。无需额外的提供商配置。
当模型引用使用
`opencode-go/...` 时，OpenClaw 会自动处理按模型路由。不需要额外的提供商配置。
</Accordion>
<Accordion title="运行时引用约定">
运行时引用保持显式：Zen 使用 `opencode/...`，Go 使用 `opencode-go/...`。
这样可以在两个目录之间保持上游按模型路由正确无误。
运行时引用保持明确：Zen 使用 `opencode/...`，Go 使用 `opencode-go/...`。
这样可以在两个目录之间保持上游按模型路由的正确性。
</Accordion>
<Accordion title="共享凭证">
Zen 和 Go 目录都使用同一个 `OPENCODE_API_KEY`。在设置期间输入该密钥后，会为这两个运行时提供商都存储凭证。
Zen 目录和 Go 目录使用相同的 `OPENCODE_API_KEY`。在设置期间输入
该密钥后，会同时为这两个运行时提供商存储凭证。
</Accordion>
</AccordionGroup>
<Tip>
有关共享新手引导概览以及完整的 Zen + Go 目录参考，请参阅 [OpenCode](/zh-CN/providers/opencode)。
有关共享新手引导概览以及完整的
Zen + Go 目录参考，请参阅 [OpenCode](/zh-CN/providers/opencode)。
</Tip>
## 相关内容
@ -108,6 +123,6 @@ OpenCode Go 是 [OpenCode](/zh-CN/providers/opencode) 中的 Go 目录。
共享新手引导、目录概览和高级说明。
</Card>
<Card title="模型选择" href="/zh-CN/concepts/model-providers" icon="layers">
选择提供商、模型引用和故障转移行为。
选择提供商、模型引用和故障切换行为。
</Card>
</CardGroup>