文档分类#
“去壳!去壳!” — 大概是一只太空龙虾说的
适用于任何操作系统的 AI 智能体 Gateway 网关,支持 WhatsApp、Telegram、Discord、iMessage 等。
发送消息,随时随地获取智能体响应。通过插件可添加 Mattermost 等更多渠道。
安装 OpenClaw 并在几分钟内启动 Gateway 网关。
通过 `openclaw onboard` 和配对流程进行引导式设置。
启动浏览器仪表板,管理聊天、配置和会话。
OpenClaw 通过单个 Gateway 网关进程将聊天应用连接到 Pi 等编程智能体。它为 OpenClaw 助手提供支持,并支持本地或远程部署。
工作原理#
flowchart LR
A["Chat apps + plugins"] --> B["Gateway"]
B --> C["Pi agent"]
B --> D["CLI"]
B --> E["Web Control UI"]
B --> F["macOS app"]
B --> G["iOS and Android nodes"]
Gateway 网关是会话、路由和渠道连接的唯一事实来源。
核心功能#
通过单个 Gateway 网关进程连接 WhatsApp、Telegram、Discord 和 iMessage。
通过扩展包添加 Mattermost 等更多渠道。
按智能体、工作区或发送者隔离会话。
发送和接收图片、音频和文档。
浏览器仪表板,用于聊天、配置、会话和节点管理。
配对 iOS 和 Android 节点,支持 Canvas。
快速开始#
```bash
npm install -g openclaw@latest
```
```bash
openclaw onboard --install-daemon
```
```bash
openclaw channels login
openclaw gateway --port 18789
```
需要完整的安装和开发环境设置?请参阅快速开始。
仪表板#
Gateway 网关启动后,打开浏览器控制界面。
配置(可选)#
配置文件位于 ~/.openclaw/openclaw.json。
- 如果你不做任何修改,OpenClaw 将使用内置的 Pi 二进制文件以 RPC 模式运行,并按发送者创建独立会话。
- 如果你想要限制访问,可以从
channels.whatsapp.allowFrom 和(针对群组的)提及规则开始配置。
示例:
{
channels: {
whatsapp: {
allowFrom: ["+15555550123"],
groups: { "*": { requireMention: true } },
},
},
messages: { groupChat: { mentionPatterns: ["@openclaw"] } },
}
从这里开始#
所有文档和指南,按用例分类。
核心 Gateway 网关设置、令牌和提供商配置。
SSH 和 tailnet 访问模式。
WhatsApp、Telegram、Discord 等渠道的具体设置。
iOS 和 Android 节点的配对与 Canvas 功能。
常见修复方法和故障排除入口。
了解更多#
全部渠道、路由和媒体功能。
工作区隔离和按智能体的会话管理。
令牌、白名单和安全控制。
Gateway 网关诊断和常见错误。
项目起源、贡献者和许可证。
Read When 维护 docs/zh-CN/** 更新中文翻译流水线(glossary/TM/prompt) 处理中文翻译反馈或回归 Pipeline(docs-i18n) 源文档:docs/**/*.md 目标文档:docs/zh-CN/**/*.md 术语表:docs/.i18n/glossary.zh-CN.json 翻译记忆库:docs/.i18n/zh-CN.tm.jsonl 提示词规则:scripts/docs-i18n/translator.go 常用运行方式:
# 批量(doc 模式,可并行) go run scripts/docs-i18n/main.go -mode doc -parallel 6 docs/**/*.md # 单文件 go run scripts/docs-i18n/main.go -mode doc docs/channels/matrix.md # 小范围补丁(segment 模式,使用 TM;不支持并行) go run scripts/docs-i18n/main.go -mode segment docs/channels/matrix.md 注意事项:
doc 模式用于整页翻译;segment 模式用于小范围修补(依赖 TM)。 超大文件若超时,优先做定点替换或拆分后再跑。 翻译后检查中文引号、CJK-Latin 间距和术语一致性。 zh-CN 样式规则 CJK-Latin 间距:遵循 W3C CLREQ(如 Gateway 网关、Skills 配置)。 中文引号:正文/标题使用 “”;代码/CLI/键名保持 ASCII 引号。 术语保留英文:Skills、local loopback、Tailscale。 代码块/内联代码:保持原样,不在代码内插入空格或引号替换。 关键术语(#6995 修复) Gateway 网关 Skills 配置 沙箱 预期键名 配套应用 分块流式传输 设备发现 反馈与变更记录 反馈来源:GitHub issue #6995 反馈用户:@AaronWander、@taiyi747、@Explorer1092、@rendaoyuan 变更要点:更新 prompt 规则、扩充 glossary、清理 TM、批量再生成 + 定点修复 参考链接:https://github.com/openclaw/openclaw/issues/6995
OpenClaw 使用 Brave Search 作为 web_search 的默认提供商。
获取 API 密钥 在 https://brave.com/search/api/ 创建 Brave Search API 账户 在控制面板中,选择 Data for Search 套餐并生成 API 密钥。 将密钥存储在配置中(推荐),或在 Gateway 网关环境中设置 BRAVE_API_KEY。 配置示例 { tools: { web: { search: { provider: "brave", apiKey: "BRAVE_API_KEY_HERE", maxResults: 5, timeoutSeconds: 30, }, }, }, } 注意事项 Data for AI 套餐与 web_search 不兼容。 Brave 提供免费层级和付费套餐;请查看 Brave API 门户了解当前限制。 请参阅 Web 工具 了解完整的 web_search 配置。
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/ 下:
...
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 中开发 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 如何与 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():
...
本中心链接到支持的 VPS/托管指南,并在高层次上解释云部署的工作原理。
选择提供商 Railway(一键 + 浏览器设置):Railway Northflank(一键 + 浏览器设置):Northflank Oracle Cloud(永久免费):Oracle — $0/月(永久免费,ARM;容量/注册可能不太稳定) Fly.io:Fly.io Hetzner(Docker):Hetzner GCP(Compute Engine):GCP exe.dev(VM + HTTPS 代理):exe.dev AWS(EC2/Lightsail/免费套餐):也运行良好。视频指南: https://x.com/techfrenAJ/status/2014934471095812547 云设置的工作原理 Gateway 网关运行在 VPS 上并拥有状态 + 工作区。 你通过控制 UI 或 Tailscale/SSH 从笔记本电脑/手机连接。 将 VPS 视为数据源并备份状态 + 工作区。 安全默认:将 Gateway 网关保持在 loopback 上,通过 SSH 隧道或 Tailscale Serve 访问。 如果你绑定到 lan/tailnet,需要 gateway.auth.token 或 gateway.auth.password。 远程访问:Gateway 网关远程访问 平台中心:平台
在 VPS 上使用节点 你可以将 Gateway 网关保持在云端,并在本地设备(Mac/iOS/Android/无头)上配对节点。节点提供本地屏幕/摄像头/canvas 和 system.run 功能,而 Gateway 网关保持在云端。
文档:节点,节点 CLI
OpenClaw 可以使用 ElevenLabs、OpenAI 或 Edge TTS 将出站回复转换为音频。它可以在任何 OpenClaw 能发送音频的地方工作;Telegram 会显示圆形语音消息气泡。
支持的服务 ElevenLabs(主要或备用提供商) OpenAI(主要或备用提供商;也用于摘要) Edge TTS(主要或备用提供商;使用 node-edge-tts,无 API 密钥时为默认) Edge TTS 注意事项 Edge TTS 通过 node-edge-tts 库使用 Microsoft Edge 的在线神经网络 TTS 服务。它是托管服务(非本地),使用 Microsoft 的端点,不需要 API 密钥。node-edge-tts 公开了语音配置选项和输出格式,但并非所有选项都被 Edge 服务支持。citeturn2search0
由于 Edge TTS 是一个没有公布 SLA 或配额的公共 Web 服务,请将其视为尽力而为。如果你需要有保证的限制和支持,请使用 OpenAI 或 ElevenLabs。Microsoft 的语音 REST API 记录了每个请求 10 分钟的音频限制;Edge TTS 没有公布限制,所以假设类似或更低的限制。citeturn0search3
可选密钥 如果你想使用 OpenAI 或 ElevenLabs:
ELEVENLABS_API_KEY(或 XI_API_KEY) OPENAI_API_KEY Edge TTS 不需要 API 密钥。如果没有找到 API 密钥,OpenClaw 默认使用 Edge TTS(除非通过 messages.tts.edge.enabled=false 禁用)。
...
OpenClaw 在两个地方记录日志:
文件日志(JSON 行)由 Gateway 网关写入。 控制台输出显示在终端和控制 UI 中。 本页说明日志存放位置、如何读取日志以及如何配置日志级别和格式。
日志存放位置 默认情况下,Gateway 网关在以下位置写入滚动日志文件:
/tmp/openclaw/openclaw-YYYY-MM-DD.log
日期使用 Gateway 网关主机的本地时区。
你可以在 ~/.openclaw/openclaw.json 中覆盖此设置:
{ "logging": { "file": "/path/to/openclaw.log" } } 如何读取日志 CLI:实时跟踪(推荐) 使用 CLI 通过 RPC 跟踪 Gateway 网关日志文件:
openclaw logs --follow 输出模式:
TTY 会话:美观、彩色、结构化的日志行。 非 TTY 会话:纯文本。 --json:行分隔的 JSON(每行一个日志事件)。 --plain:在 TTY 会话中强制纯文本。 --no-color:禁用 ANSI 颜色。 在 JSON 模式下,CLI 输出带 type 标签的对象:
meta:流元数据(文件、游标、大小) log:解析的日志条目 notice:截断/轮转提示 raw:未解析的日志行 如果 Gateway 网关无法访问,CLI 会打印一个简短提示运行:
openclaw doctor 控制 UI(Web) 控制 UI 的日志标签页使用 logs.tail 跟踪相同的文件。 参见 /web/control-ui 了解如何打开它。
...
OpenClaw 默认使用主机本地时间作为传输时间戳,并且仅在系统提示词中使用用户时区。 提供商时间戳会被保留,因此工具保持其原生语义(当前时间可通过 session_status 获取)。
消息信封(默认为本地时间) 入站消息会附带一个时间戳(分钟精度):
[Provider ... 2026-01-05 16:26 PST] message text 此信封时间戳默认为主机本地时间,与提供商时区无关。
你可以覆盖此行为:
{ agents: { defaults: { envelopeTimezone: "local", // "utc" | "local" | "user" | IANA 时区 envelopeTimestamp: "on", // "on" | "off" envelopeElapsed: "on", // "on" | "off" }, }, } envelopeTimezone: "utc" 使用 UTC。 envelopeTimezone: "local" 使用主机时区。 envelopeTimezone: "user" 使用 agents.defaults.userTimezone(回退到主机时区)。 使用显式 IANA 时区(例如 "America/Chicago")指定固定时区。 envelopeTimestamp: "off" 从信封头中移除绝对时间戳。 envelopeElapsed: "off" 移除已用时间后缀(+2m 样式)。 示例 本地时间(默认):
...