本文档描述了 OpenClaw 如何与 pi-coding-agent 及其相关包（pi-ai、pi-agent-core、pi-tui）集成以实现其 AI 智能体能力。 概述 OpenClaw 使用 pi SDK 将 AI 编码智能体嵌入到其消息 Gateway 网关架构中。OpenClaw 不是将 pi 作为子进程生成或使用 RPC 模式，而是通过 createAgentSession() 直接导入并实例化 pi 的 AgentSession。这种嵌入式方法提供了： 对会话生命周期和事件处理的完全控制 自定义工具注入（消息、沙箱、渠道特定操作） 每个渠道/上下文的系统提示自定义 支持分支/压缩的会话持久化 带故障转移的多账户认证配置文件轮换 与提供商无关的模型切换 包依赖 { "@mariozechner/pi-agent-core": "0.49.3", "@mariozechner/pi-ai": "0.49.3", "@mariozechner/pi-coding-agent": "0.49.3", "@mariozechner/pi-tui": "0.49.3" } 包 用途 pi-ai 核心 LLM 抽象：Model、streamSimple、消息类型、提供商 API pi-agent-core 智能体循环、工具执行、AgentMessage 类型 pi-coding-agent 高级 SDK：createAgentSession、SessionManager、AuthStorage、ModelRegistry、内置工具 pi-tui 终端 UI 组件（用于 OpenClaw 的本地 TUI 模式） 文件结构 src/agents/ ├── pi-embedded-runner.ts # Re-exports from pi-embedded-runner/ ├── pi-embedded-runner/ │ ├── run.ts # Main entry: runEmbeddedPiAgent() │ ├── run/ │ │ ├── attempt.ts # Single attempt logic with session setup │ │ ├── params.ts # RunEmbeddedPiAgentParams type │ │ ├── payloads.ts # Build response payloads from run results │ │ ├── images.ts # Vision model image injection │ │ └── types.ts # EmbeddedRunAttemptResult │ ├── abort.ts # Abort error detection │ ├── cache-ttl.ts # Cache TTL tracking for context pruning │ ├── compact.ts # Manual/auto compaction logic │ ├── extensions.ts # Load pi extensions for embedded runs │ ├── extra-params.ts # Provider-specific stream params │ ├── google.ts # Google/Gemini turn ordering fixes │ ├── history.ts # History limiting (DM vs group) │ ├── lanes.ts # Session/global command lanes │ ├── logger.ts # Subsystem logger │ ├── model.ts # Model resolution via ModelRegistry │ ├── runs.ts # Active run tracking, abort, queue │ ├── sandbox-info.ts # Sandbox info for system prompt │ ├── session-manager-cache.ts # SessionManager instance caching │ ├── session-manager-init.ts # Session file initialization │ ├── system-prompt.ts # System prompt builder │ ├── tool-split.ts # Split tools into builtIn vs custom │ ├── types.ts # EmbeddedPiAgentMeta, EmbeddedPiRunResult │ └── utils.ts # ThinkLevel mapping, error description ├── pi-embedded-subscribe.ts # Session event subscription/dispatch ├── pi-embedded-subscribe.types.ts # SubscribeEmbeddedPiSessionParams ├── pi-embedded-subscribe.handlers.ts # Event handler factory ├── pi-embedded-subscribe.handlers.lifecycle.ts ├── pi-embedded-subscribe.handlers.types.ts ├── pi-embedded-block-chunker.ts # Streaming block reply chunking ├── pi-embedded-messaging.ts # Messaging tool sent tracking ├── pi-embedded-helpers.ts # Error classification, turn validation ├── pi-embedded-helpers/ # Helper modules ├── pi-embedded-utils.ts # Formatting utilities ├── pi-tools.ts # createOpenClawCodingTools() ├── pi-tools.abort.ts # AbortSignal wrapping for tools ├── pi-tools.policy.ts # Tool allowlist/denylist policy ├── pi-tools.read.ts # Read tool customizations ├── pi-tools.schema.ts # Tool schema normalization ├── pi-tools.types.ts # AnyAgentTool type alias ├── pi-tool-definition-adapter.ts # AgentTool -> ToolDefinition adapter ├── pi-settings.ts # Settings overrides ├── pi-extensions/ # Custom pi extensions │ ├── compaction-safeguard.ts # Safeguard extension │ ├── compaction-safeguard-runtime.ts │ ├── context-pruning.ts # Cache-TTL context pruning extension │ └── context-pruning/ ├── model-auth.ts # Auth profile resolution ├── auth-profiles.ts # Profile store, cooldown, failover ├── model-selection.ts # Default model resolution ├── models-config.ts # models.json generation ├── model-catalog.ts # Model catalog cache ├── context-window-guard.ts # Context window validation ├── failover-error.ts # FailoverError class ├── defaults.ts # DEFAULT_PROVIDER, DEFAULT_MODEL ├── system-prompt.ts # buildAgentSystemPrompt() ├── system-prompt-params.ts # System prompt parameter resolution ├── system-prompt-report.ts # Debug report generation ├── tool-summaries.ts # Tool description summaries ├── tool-policy.ts # Tool policy resolution ├── transcript-policy.ts # Transcript validation policy ├── skills.ts # Skill snapshot/prompt building ├── skills/ # Skill subsystem ├── sandbox.ts # Sandbox context resolution ├── sandbox/ # Sandbox subsystem ├── channel-tools.ts # Channel-specific tool injection ├── openclaw-tools.ts # OpenClaw-specific tools ├── bash-tools.ts # exec/process tools ├── apply-patch.ts # apply_patch tool (OpenAI) ├── tools/ # Individual tool implementations │ ├── browser-tool.ts │ ├── canvas-tool.ts │ ├── cron-tool.ts │ ├── discord-actions*.ts │ ├── gateway-tool.ts │ ├── image-tool.ts │ ├── message-tool.ts │ ├── nodes-tool.ts │ ├── session*.ts │ ├── slack-actions.ts │ ├── telegram-actions.ts │ ├── web-*.ts │ └── whatsapp-actions.ts └── ... 核心集成流程 1. 运行嵌入式智能体 主入口点是 pi-embedded-runner/run.ts 中的 runEmbeddedPiAgent()： ...

本指南总结了在 OpenClaw 中开发 Pi 集成的合理工作流程。 类型检查和代码检查 类型检查和构建：pnpm build 代码检查：pnpm lint 格式检查：pnpm format 推送前完整检查：pnpm lint && pnpm build && pnpm test 运行 Pi 测试 使用专用脚本运行 Pi 集成测试集： scripts/pi/run-tests.sh 要包含执行真实提供商行为的实时测试： scripts/pi/run-tests.sh --live 该脚本通过以下 glob 模式运行所有 Pi 相关的单元测试： src/agents/pi-*.test.ts src/agents/pi-embedded-*.test.ts src/agents/pi-tools*.test.ts src/agents/pi-settings.test.ts src/agents/pi-tool-definition-adapter.test.ts src/agents/pi-extensions/*.test.ts 手动测试 推荐流程： 以开发模式运行 Gateway 网关： pnpm gateway:dev 直接触发智能体： pnpm openclaw agent --message "Hello" --thinking low 使用 TUI 进行交互式调试： pnpm tui 对于工具调用行为，提示执行 read 或 exec 操作，以便查看工具流式传输和负载处理。 完全重置 状态存储在 OpenClaw 状态目录下。默认为 ~/.openclaw。如果设置了 OPENCLAW_STATE_DIR，则使用该目录。 ...

OpenClaw 可以使用 Perplexity Sonar 作为 web_search 工具。你可以通过 Perplexity 的直连 API 或通过 OpenRouter 连接。 API 选项 Perplexity（直连） Base URL：https://api.perplexity.ai 环境变量：PERPLEXITY_API_KEY OpenRouter（替代方案） Base URL：https://openrouter.ai/api/v1 环境变量：OPENROUTER_API_KEY 支持预付费/加密货币积分。 配置示例 { tools: { web: { search: { provider: "perplexity", perplexity: { apiKey: "pplx-...", baseUrl: "https://api.perplexity.ai", model: "perplexity/sonar-pro", }, }, }, }, } 从 Brave 切换 { tools: { web: { search: { provider: "perplexity", perplexity: { apiKey: "pplx-...", baseUrl: "https://api.perplexity.ai", }, }, }, }, } 如果同时设置了 PERPLEXITY_API_KEY 和 OPENROUTER_API_KEY，请设置 tools.web.search.perplexity.baseUrl（或 tools.web.search.perplexity.apiKey）以消除歧义。 ...

OpenClaw 可以将 PeekabooBridge 作为本地的、权限感知的 UI 自动化代理进行托管。这使得 peekaboo CLI 能够驱动 UI 自动化，同时复用 macOS 应用的 TCC 权限。 这是什么（以及不是什么） 宿主：OpenClaw.app 可以作为 PeekabooBridge 宿主。 客户端：使用 peekaboo CLI（无需单独的 openclaw ui ... 界面）。 界面：视觉叠加层保留在 Peekaboo.app 中；OpenClaw 只是一个轻量代理宿主。 启用桥接 在 macOS 应用中： 设置 → 启用 Peekaboo Bridge 启用后，OpenClaw 会启动一个本地 UNIX 套接字服务器。如果禁用，宿主会停止，peekaboo 将回退到其他可用宿主。 客户端发现顺序 Peekaboo 客户端通常按以下顺序尝试宿主： Peekaboo.app（完整用户体验） Claude.app（如已安装） OpenClaw.app（轻量代理） 使用 peekaboo bridge status --verbose 查看当前活跃的宿主及使用的套接字路径。你可以通过以下方式覆盖： export PEEKABOO_BRIDGE_SOCKET=/path/to/bridge.sock 安全与权限 桥接会验证调用方的代码签名；强制执行 TeamID 白名单（Peekaboo 宿主 TeamID + OpenClaw 应用 TeamID）。 请求在约 10 秒后超时。 如果缺少所需权限，桥接会返回清晰的错误信息，而不是启动系统设置。 快照行为（自动化） 快照存储在内存中，并在短暂窗口期后自动过期。如果需要更长的保留时间，请从客户端重新捕获。 ...

OpenRouter 提供了一个统一 API，通过单一端点和 API 密钥将请求路由到多种模型。它兼容 OpenAI，因此大多数 OpenAI SDK 只需切换 base URL 即可使用。 CLI 设置 openclaw onboard --auth-choice apiKey --token-provider openrouter --token "$OPENROUTER_API_KEY" 配置片段 { env: { OPENROUTER_API_KEY: "sk-or-..." }, agents: { defaults: { model: { primary: "openrouter/anthropic/claude-sonnet-4-5" }, }, }, } 注意事项 模型引用格式为 openrouter/<provider>/<model>。 更多模型/提供商选项，请参阅模型提供商。 OpenRouter 底层使用 Bearer 令牌和你的 API 密钥进行认证。

背景 OpenClaw Gateway 网关目前在 /v1/chat/completions 暴露了一个最小的 OpenAI 兼容 Chat Completions 端点（参见 OpenAI Chat Completions）。 Open Responses 是基于 OpenAI Responses API 的开放推理标准。它专为智能体工作流设计，使用基于项目的输入加语义流式事件。OpenResponses 规范定义的是 /v1/responses，而不是 /v1/chat/completions。 目标 添加一个遵循 OpenResponses 语义的 /v1/responses 端点。 保留 Chat Completions 作为兼容层，易于禁用并最终移除。 使用隔离的、可复用的 schema 标准化验证和解析。 非目标 第一阶段完全实现 OpenResponses 功能（图片、文件、托管工具）。 替换内部智能体执行逻辑或工具编排。 在第一阶段更改现有的 /v1/chat/completions 行为。 研究摘要 来源：OpenResponses OpenAPI、OpenResponses 规范网站和 Hugging Face 博客文章。 提取的关键点： POST /v1/responses 接受 CreateResponseBody 字段，如 model、input（字符串或 ItemParam[]）、instructions、tools、tool_choice、stream、max_output_tokens 和 max_tool_calls。 ItemParam 是以下类型的可区分联合： 具有角色 system、developer、user、assistant 的 message 项 function_call 和 function_call_output reasoning item_reference 成功响应返回带有 object: "response"、status 和 output 项的 ResponseResource。 流式传输使用语义事件，如： response.created、response.in_progress、response.completed、response.failed response.output_item.added、response.output_item.done response.content_part.added、response.content_part.done response.output_text.delta、response.output_text.done 规范要求： Content-Type: text/event-stream event: 必须匹配 JSON type 字段 终止事件必须是字面量 [DONE] Reasoning 项可能暴露 content、encrypted_content 和 summary。 HF 示例在请求中包含 OpenResponses-Version: latest（可选头部）。 提议的架构 添加 src/gateway/open-responses.schema.ts，仅包含 Zod schema（无 gateway 导入）。 添加 src/gateway/openresponses-http.ts（或 open-responses-http.ts）用于 /v1/responses。 保持 src/gateway/openai-http.ts 不变，作为遗留兼容适配器。 添加配置 gateway.http.endpoints.responses.enabled（默认 false）。 保持 gateway.http.endpoints.chatCompletions.enabled 独立；允许两个端点分别切换。 当 Chat Completions 启用时发出启动警告，以表明其遗留状态。 Chat Completions 弃用路径 保持严格的模块边界：responses 和 chat completions 之间不共享 schema 类型。 通过配置使 Chat Completions 成为可选，这样无需代码更改即可禁用。 一旦 /v1/responses 稳定，更新文档将 Chat Completions 标记为遗留。 可选的未来步骤：将 Chat Completions 请求映射到 Responses 处理器，以便更简单地移除。 第一阶段支持子集 接受 input 为字符串或带有消息角色和 function_call_output 的 ItemParam[]。 将 system 和 developer 消息提取到 extraSystemPrompt 中。 使用最近的 user 或 function_call_output 作为智能体运行的当前消息。 对不支持的内容部分（图片/文件）返回 invalid_request_error 拒绝。 返回带有 output_text 内容的单个助手消息。 返回带有零值的 usage，直到 token 计数接入。 验证策略（无 SDK） 为以下支持子集实现 Zod schema： CreateResponseBody ItemParam + 消息内容部分联合 ResponseResource Gateway 网关使用的流式事件形状 将 schema 保存在单个隔离模块中，以避免漂移并允许未来代码生成。 流式实现（第一阶段） 带有 event: 和 data: 的 SSE 行。 所需序列（最小可行）： response.created response.output_item.added response.content_part.added response.output_text.delta（根据需要重复） response.output_text.done response.content_part.done response.completed [DONE] 测试和验证计划 为 /v1/responses 添加端到端覆盖： 需要认证 非流式响应形状 流式事件顺序和 [DONE] 使用头部和 user 的会话路由 保持 src/gateway/openai-http.e2e.test.ts 不变。 手动：用 stream: true curl /v1/responses 并验证事件顺序和终止 [DONE]。 文档更新（后续） 为 /v1/responses 使用和示例添加新文档页面。 更新 /gateway/openai-http-api，添加遗留说明和指向 /v1/responses 的指针。

OpenClaw 的 Gateway 网关可以提供兼容 OpenResponses 的 POST /v1/responses 端点。 此端点默认禁用。请先在配置中启用。 POST /v1/responses 与 Gateway 网关相同的端口（WS + HTTP 多路复用）：http://<gateway-host>:<port>/v1/responses 底层实现中，请求作为正常的 Gateway 网关智能体运行执行（与 openclaw agent 相同的代码路径），因此路由/权限/配置与你的 Gateway 网关一致。 认证 使用 Gateway 网关认证配置。发送 bearer 令牌： Authorization: Bearer <token> 说明： 当 gateway.auth.mode="token" 时，使用 gateway.auth.token（或 OPENCLAW_GATEWAY_TOKEN）。 当 gateway.auth.mode="password" 时，使用 gateway.auth.password（或 OPENCLAW_GATEWAY_PASSWORD）。 选择智能体 无需自定义头：在 OpenResponses model 字段中编码智能体 id： model: "openclaw:<agentId>"（示例："openclaw:main"、"openclaw:beta"） model: "agent:<agentId>"（别名） 或通过头指定特定的 OpenClaw 智能体： x-openclaw-agent-id: <agentId>（默认：main） 高级： x-openclaw-session-key: <sessionKey> 完全控制会话路由。 启用端点 将 gateway.http.endpoints.responses.enabled 设置为 true： ...

OpenProse 是一种可移植的、以 Markdown 为中心的工作流格式，用于编排 AI 会话。在 OpenClaw 中，它作为插件发布，安装一个 OpenProse Skills 包以及一个 /prose 斜杠命令。程序存放在 .prose 文件中，可以生成多个具有显式控制流的子智能体。 官方网站：https://www.prose.md 它能做什么 具有显式并行性的多智能体研究 + 综合。 可重复的批准安全工作流（代码审查、事件分类、内容管道）。 可在支持的智能体运行时之间运行的可重用 .prose 程序。 安装 + 启用 捆绑的插件默认是禁用的。启用 OpenProse： openclaw plugins enable open-prose 启用插件后重启 Gateway 网关。 开发/本地检出：openclaw plugins install ./extensions/open-prose 相关文档：插件、插件清单、Skills。 斜杠命令 OpenProse 将 /prose 注册为用户可调用的 Skills 命令。它路由到 OpenProse VM 指令，并在底层使用 OpenClaw 工具。 常用命令： /prose help /prose run <file.prose> /prose run <handle/slug> /prose run <https://example.com/file.prose> /prose compile <file.prose> /prose examples /prose update 示例：一个简单的 .prose 文件 # Research + synthesis with two agents running in parallel. input topic: "What should we research?" agent researcher: model: sonnet prompt: "You research thoroughly and cite sources." agent writer: model: opus prompt: "You write a concise summary." parallel: findings = session: researcher prompt: "Research {topic}." draft = session: writer prompt: "Summarize {topic}." session "Merge the findings + draft into a final answer." context: { findings, draft } 文件位置 OpenProse 将状态保存在工作空间的 .prose/ 下： ...

OpenCode Zen 是由 OpenCode 团队推荐的一组精选模型列表，适用于编程智能体。它是一个可选的托管模型访问路径，使用 API 密钥和 opencode 提供商。Zen 目前处于测试阶段。 CLI 设置 openclaw onboard --auth-choice opencode-zen # 或非交互式 openclaw onboard --opencode-zen-api-key "$OPENCODE_API_KEY" 配置片段 { env: { OPENCODE_API_KEY: "sk-..." }, agents: { defaults: { model: { primary: "opencode/claude-opus-4-5" } } }, } 注意事项 也支持 OPENCODE_ZEN_API_KEY。 你需要登录 Zen，添加账单信息，然后复制你的 API 密钥。 OpenCode Zen 按请求计费；详情请查看 OpenCode 控制台。

一个关于龙虾、蜕壳和太多 token 的故事。 起源故事 最初，有一个叫 Warelay 的东西——一个作为 WhatsApp Gateway 网关的合理名字。它完成了它的工作。还不错。 但后来来了一只太空龙虾。 有一段时间，这只龙虾叫做 Clawd，住在 OpenClaw 里。但在 2026 年 1 月，Anthropic 发了一封礼貌的邮件要求更名（商标问题）。于是龙虾做了龙虾最擅长的事： 它蜕壳了。 褪去旧壳，这只生物以 Molty 的新身份出现，住在 Moltbot 里。但这个名字说起来也不太顺口…… 于是在 2026 年 1 月 30 日，龙虾又蜕了一次壳，变成了最终形态：OpenClaw。 新壳，同一个龙虾灵魂。事不过三。 第一次蜕壳（2026 年 1 月 27 日） 凌晨 5 点，社区成员聚集在 Discord。数百个名字被提议：Shelldon、Pinchy、Thermidor、Crusty、Lobstar、Nacre、Scuttlebot…… 最终，OpenClaw 胜出。因为蜕壳是龙虾成长的方式。而成长正是正在发生的事情。 这只被称为 Clawd 的甲壳类动物正式蜕壳了。 名字的含义 OpenClaw = OPEN + CLAW = 开源，向所有人开放 = 我们的龙虾传承，我们从何而来 = 钳即是法 🦞 = 你的助手。你的机器。你的规则。 Dalek 与龙虾 Dalek 说：“EXTERMINATE!”（消灭！） 龙虾说：“EXFOLIATE!”（去角质！） 一个毁灭文明。另一个提倡良好的皮肤护理。 明智选择。 ...