diff --git a/docs/.i18n/glossary.zh-CN.json b/docs/.i18n/glossary.zh-CN.json index 62a7741c37..9ab7e1254e 100644 --- a/docs/.i18n/glossary.zh-CN.json +++ b/docs/.i18n/glossary.zh-CN.json @@ -5,7 +5,7 @@ }, { "source": "Gateway", - "target": "Gateway网关" + "target": "Gateway 网关" }, { "source": "Pi", @@ -17,11 +17,11 @@ }, { "source": "Skills config", - "target": "Skills配置" + "target": "Skills 配置" }, { "source": "Skills Config", - "target": "Skills配置" + "target": "Skills 配置" }, { "source": "local loopback", @@ -47,6 +47,22 @@ "source": "DM", "target": "私信" }, + { + "source": "sandbox", + "target": "沙箱" + }, + { + "source": "Sandbox", + "target": "沙箱" + }, + { + "source": "sandboxing", + "target": "沙箱隔离" + }, + { + "source": "Sandboxing", + "target": "沙箱隔离" + }, { "source": "sandboxed", "target": "沙箱隔离" @@ -55,6 +71,46 @@ "source": "Sandboxed", "target": "沙箱隔离" }, + { + "source": "Sandboxing note", + "target": "沙箱注意事项" + }, + { + "source": "Companion apps", + "target": "配套应用" + }, + { + "source": "expected keys", + "target": "预期键名" + }, + { + "source": "block streaming", + "target": "分块流式传输" + }, + { + "source": "Block streaming", + "target": "分块流式传输" + }, + { + "source": "Discovery + transports", + "target": "设备发现 + 传输协议" + }, + { + "source": "Discovery", + "target": "设备发现" + }, + { + "source": "Network model", + "target": "网络模型" + }, + { + "source": "for full details", + "target": "了解详情" + }, + { + "source": "First 60 seconds", + "target": "最初的六十秒" + }, { "source": "Auth: where it lives (important)", "target": "凭证：存储位置（重要）" diff --git a/docs/.i18n/zh-CN.tm.jsonl b/docs/.i18n/zh-CN.tm.jsonl index 83f41ad406..24076e5a08 100644 --- a/docs/.i18n/zh-CN.tm.jsonl +++ b/docs/.i18n/zh-CN.tm.jsonl @@ -3,13 +3,10 @@ {"cache_key":"00ee1ece05b05ab7b12cfe673000c037bb2037fe93a069a71ec2368184e83944","segment_id":"index.md:45e6d69dbe995a36","source_path":"index.md","text_hash":"45e6d69dbe995a36f7bc20755eff4eb4d2afaaedbcac4668ab62540c57219f32","text":"macOS app","translated":"macOS 应用","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T13:05:06Z"} {"cache_key":"00eeb87b1774979860c4b016d48e416ab9157539c41f5f3f0c58c1deb8f075c9","segment_id":"environment.md:frontmatter:read_when:2","source_path":"environment.md:frontmatter:read_when:2","text_hash":"822b3d74ce16c1be19059fad4ca5bf7ae9327f58fa1ff4e75e78d5afa75c038f","text":"You are documenting provider auth or deployment environments","translated":"你正在记录提供商认证或部署环境的相关文档","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T12:15:51Z"} {"cache_key":"01063749652c55481b7da485911a80de3049ded0257874b376efbc55a14293a7","segment_id":"start/wizard.md:037b8f564390e097","source_path":"start/wizard.md","text_hash":"037b8f564390e09742421c621a1f785d2ee5338d0c680c76f7a9b991518e909d","text":" and optional ","translated":" 和可选的 ","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T13:48:48Z"} -{"cache_key":"011732db491eea64ff252f1a211df0eee3edbf29b3839a36468aff0d600565a8","segment_id":"index.md:58d30d963f28264b","source_path":"index.md","text_hash":"58d30d963f28264bd9ba0e2d4c07c2c43c0ac1c1609c25b3fccf475eebf41727","text":"Skills config","translated":"技能配置","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T12:52:44Z"} {"cache_key":"01814fd9d09399c075081056c6fa2befa388c67ba4f8745122804fd044fd82d6","segment_id":"start/getting-started.md:d1564fd156e28160","source_path":"start/getting-started.md","text_hash":"d1564fd156e28160c83922ad7a18428ce2c966e790f477e740d1d9f6cadd51e9","text":"WhatsApp (QR login)","translated":"WhatsApp（二维码登录）","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T13:37:08Z"} -{"cache_key":"019f9aef85c71dc5ed35acd441246cf7ca7e8734347c659aff797b91a593805e","segment_id":"index.md:22159a426e4f2635","source_path":"index.md","text_hash":"22159a426e4f26356382cc3ac9b2e7af5123c1309250332f5dcbbc6e6f952b0e","text":"Network model","translated":"网络 模型","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T12:48:28Z"} {"cache_key":"01b87576d7ade6b91ca28935f65c167c2f4fb5d1b6bfd1189fd416b229500af4","segment_id":"start/getting-started.md:7421b911bc203f6f","source_path":"start/getting-started.md","text_hash":"7421b911bc203f6fe3c677d752379f23dc314719d39d18179406da675f58d039","text":"Scan via WhatsApp → Settings → Linked Devices.","translated":"通过 WhatsApp → 设置 → 已关联设备 进行扫描。","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T13:37:10Z"} {"cache_key":"01d8d8ec84ad8f4c74e29e254e56c02f7d75005160c27d99e9ce183767e16c55","segment_id":"index.md:6b8ebac7903757ce","source_path":"index.md","text_hash":"6b8ebac7903757ce7399cc729651a27e459903c24c64aa94827b20d8a2a411d2","text":"For Tailnet access, run ","translated":"如需 Tailnet 访问，请运行 ","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T13:00:08Z"} {"cache_key":"024efbb5ac15e07c191effa78c0b23bf173c8af6725e988743ea055e9a4e8c3b","segment_id":"index.md:f9b8279bc46e847b","source_path":"index.md","text_hash":"f9b8279bc46e847bfcc47b8701fd5c5dc27baa304d5add8278a7f97925c3ec13","text":"Mattermost (plugin)","translated":"Mattermost（插件）","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T13:32:40Z"} -{"cache_key":"025574196252a6e36b88a27c440de11b7f0e0d981df3595a0aefda198b2cde9c","segment_id":"index.md:4d705f0fa835fd21","source_path":"index.md","text_hash":"4d705f0fa835fd216c4fd6dea0ee851d33720e23fb714c4c9ea74ac3211fccdc","text":"Discovery + transports","translated":"发现 + 传输","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T12:53:02Z"} {"cache_key":"02d1e10492e8721462f16e39467b94ad3197e4eb76f6d671a09b4246d5b4d27b","segment_id":"start/getting-started.md:7ac362063b9f2046","source_path":"start/getting-started.md","text_hash":"7ac362063b9f204602f38f9f1ec9cf047f03e0d7b83896571c9df6d31ad41e9c","text":"Nodes","translated":"节点","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T13:38:28Z"} {"cache_key":"02f39c075115bee6bdb015a49436f2b2a56365b87558fdd7aff7b17cb83bff6c","segment_id":"environment.md:frontmatter:summary","source_path":"environment.md:frontmatter:summary","text_hash":"78351223e7068721146d2de022fdf440c2866b2ee02fbbb50bf64369b999820b","text":"Where OpenClaw loads environment variables and the precedence order","translated":"OpenClaw 加载环境变量的位置及优先级顺序","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T12:19:12Z"} {"cache_key":"02f4067265058ed8929f3772d87e1c5dc0af8422b8e7b513b7db155108a422c3","segment_id":"start/wizard.md:961eb43699731759","source_path":"start/wizard.md","text_hash":"961eb43699731759fd0d04f177bb24f09971bddd41426702276e761269d0a5b9","text":" does ","translated":" 会 ","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T13:40:48Z"} @@ -19,13 +16,8 @@ {"cache_key":"0457a19cd3a82171f6cdb92d82d5a0f6358da4c1220d42d5b0575bde871e7f91","segment_id":"environment.md:e234227b0e001687","source_path":"environment.md","text_hash":"e234227b0e001687821541fac3af38fc6be293ec6e13910c6826b9afc8ca33be","text":" syntax:","translated":" 语法：","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T13:13:00Z"} {"cache_key":"045fb6f3989827561e347dfa56a164069bf8b7afaa50d2d02c20ad264495d351","segment_id":"index.md:e9f63c8876aec738","source_path":"index.md","text_hash":"e9f63c8876aec7381ffb5a68efb39f50525f9fc4e732857488561516d47f5654","text":" — Uses Baileys for WhatsApp Web protocol","translated":" — 使用 Baileys 实现 WhatsApp Web 协议","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T13:29:31Z"} {"cache_key":"046c83b658b7dd8bce829f07bd09dcee3413753ab72cf95d638925aa163d3486","segment_id":"start/getting-started.md:f4117324994aaad1","source_path":"start/getting-started.md","text_hash":"f4117324994aaad1d3413064ade8f2037e43ab2fac0b385d731ff154925ec3b3","text":"Windows (PowerShell):","translated":"Windows (PowerShell)：","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T13:35:51Z"} -{"cache_key":"04b1191bfbfc3062975be3fbc5b169b9c3151d3fbce07bfffc05483c40191c76","segment_id":"environment.md:28e19c6e69c7a2aa","source_path":"environment.md","text_hash":"28e19c6e69c7a2aa071951dda3ff0a11ca178e3fb295dae8d6ed7dcc994434a4","text":" for full details.","translated":" 了解完整详情。","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T13:13:07Z"} {"cache_key":"04d48cfdb6b444cb4691ea55a5deb23df20694659ae1bc5e082e242e749f5e3c","segment_id":"help/index.md:bfc5930cc2660330","source_path":"help/index.md","text_hash":"bfc5930cc2660330260afd407e98d86adaec0af48dd72b88dc33ef8e9066e2c9","text":"Install sanity (Node/npm/PATH):","translated":"安装完整性检查（Node/npm/PATH）：","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T12:39:38Z"} -{"cache_key":"04fee8dc5ef25d6bc83852bc30abc64dab335a974f1a9aa3528d0a463f3df80e","segment_id":"environment.md:a42cc4a7174c83a8","source_path":"environment.md","text_hash":"a42cc4a7174c83a853752b3e74cb001a234f3eca099688fdf0dd2540c60bb1e2","text":" expected keys:","translated":" 预期密钥：","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T12:16:53Z"} {"cache_key":"05405710e256b2e1031234be855a7c11cf1505c627df14884d655fa42a1568a7","segment_id":"index.md:f0a7f9d068cb7a14","source_path":"index.md","text_hash":"f0a7f9d068cb7a146d0bb89b3703688d690ed0b92734b78bcdb909aace617dbf","text":"WhatsApp group messages","translated":"WhatsApp 群组消息","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T13:32:45Z"} -{"cache_key":"060d0a2c79a17edab07399082756201b03bbc948813e274fd902e138a7188268","segment_id":"start/getting-started.md:9bb7dee21b23322b","source_path":"start/getting-started.md","text_hash":"9bb7dee21b23322b15ce4a4400e6fe70a582d3d15f7e61f2c4cdf68654de1f09","text":" is also supported if you want to reuse Claude Code credentials.","translated":" 如果您想复用 Claude Code 凭据，也受支持。","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T13:36:35Z"} -{"cache_key":"0644dfe5ea449a35c3a87047a17fb132ee1ef58000d49c1849006ad247310f90","segment_id":"index.md:f14185309c5ab262","source_path":"index.md","text_hash":"f14185309c5ab26233fde49831f9fc27857a6e7ac200e91dc247ae3e3b74be27","text":"Companion apps:","translated":"伴侣应用：","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T13:05:03Z"} -{"cache_key":"06489e87ae62a43327838658fac6a96383f6c84a0f1e59319d89b2ce6a6f34b9","segment_id":"environment.md:e4255aa4e8f9e525","source_path":"environment.md","text_hash":"e4255aa4e8f9e52571c9bc93336d0774bcd7f017b7b5297fb33b8e1986166f92","text":"), applied only for missing expected keys.","translated":"），仅对缺失的预期密钥应用。","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T12:57:57Z"} {"cache_key":"064dcdb5051313b748c0b775ec69683149e1861d84fa47a74c68ddd8086bdebc","segment_id":"index.md:81a1c0449ea684aa","source_path":"index.md","text_hash":"81a1c0449ea684aadad54a7f8575061ddc5bfa713b6ca3eb8a0228843d2a3ea1","text":"Nodes (iOS/Android)","translated":"节点（iOS/Android）","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T12:52:57Z"} {"cache_key":"0687549a28e71ec1e17b261001a9e818e27784ce3286b7d21e856e37c07915a6","segment_id":"start/getting-started.md:bad5d156dc5e0cd3","source_path":"start/getting-started.md","text_hash":"bad5d156dc5e0cd39db3a90645cd150e846743103f3acfa5182ad5a003a172dc","text":"0) Prereqs","translated":"0）前提条件","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T13:35:23Z"} {"cache_key":"06c13f0dfc6cd5fa142e329fd2cfb2538e19e33de83c4b9d366542f0d03cdf08","segment_id":"index.md:c3af076f92c5ed8d","source_path":"index.md","text_hash":"c3af076f92c5ed8dcb0d0b0d36dd120bc31b68264efea96cf8019ca19f1c13a3","text":"Troubleshooting","translated":"故障排除","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T13:33:14Z"} @@ -40,7 +32,6 @@ {"cache_key":"08a071c1e71388ad18ffca39565a37edb304794146d2f7ea1e2bac93493f89d6","segment_id":"start/wizard.md:903ea1cf1f2831b3","source_path":"start/wizard.md","text_hash":"903ea1cf1f2831b3e836aff6e23c7d261a83381614361e65df16ade48e84b26c","text":" (API keys + OAuth).","translated":" （API 密钥 + OAuth）。","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T13:43:34Z"} {"cache_key":"08b4ff7a8e04409d740ca4090c8d83bc3b05d7084bce4b83fa4c91b930eb7161","segment_id":"environment.md:62d66b8c36a6c9aa","source_path":"environment.md","text_hash":"62d66b8c36a6c9aa7134c8f9fe5912435cb0b3bfce3172712646a187954e7040","text":"See [Configuration: Env var substitution](/gateway/configuration#env-var-substitution-in-config) for full details.","translated":"详见 [配置：环境变量替换](/gateway/configuration#env-var-substitution-in-config)。","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T12:11:58Z"} {"cache_key":"08f97e3d7baa10a515db441b79273f697f85c83da040cdf821f9e725243112f2","segment_id":"environment.md:f6b2ffe1d0d5f521","source_path":"environment.md","text_hash":"f6b2ffe1d0d5f521b76cabc67d6e96da2b1170eef8086d530558e9906a7f092d","text":"Models overview","translated":"模型概览","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T12:17:17Z"} -{"cache_key":"09057abbc867280c96888e1b1eb5d35e4f5b3175c0c5fca9900f147e577fb4b7","segment_id":"index.md:80fc402133201fbe","source_path":"index.md","text_hash":"80fc402133201fbe0e4e9962a9570e741856aa8b0c033f1a20a9bcb06c68e809","text":"Discovery","translated":"发现机制","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T13:29:24Z"} {"cache_key":"090f33f5db1fde14d7fc04aaa9febae674e9e6ed0d04ce8f1813dac53ccae3a2","segment_id":"start/wizard.md:ab4386608f0ebc6e","source_path":"start/wizard.md","text_hash":"ab4386608f0ebc6e151eab042c6de71d09863aab6dcb2551665e34210e4a4439","text":"What you’ll set:","translated":"您需要设置的内容：","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T13:46:15Z"} {"cache_key":"09824fcf1352f54ff162268163b8670ead0660d4e0a45d1f236b5b3ef938a56b","segment_id":"index.md:86e2bbbc305c31aa","source_path":"index.md","text_hash":"86e2bbbc305c31aa988751196a1e207da68801a48798c48b90485c11578443a0","text":"Providers and UX:","translated":"提供商 和用户体验：","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T13:04:39Z"} {"cache_key":"0a2b53b4943a0ba87fb991fef20f822df6c2fd0584f88d394de35b081daac564","segment_id":"environment.md:668e5590b5bb9990","source_path":"environment.md","text_hash":"668e5590b5bb9990eeb25bf657f7d17281a4c613ee4442036787cd4b2efd22bb","text":"If the config file is missing entirely, step 4 is skipped; shell import still runs if enabled.","translated":"如果配置文件完全缺失，则跳过第 4 步；如果已启用，shell 导入仍会运行。","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T12:58:00Z"} @@ -52,7 +43,6 @@ {"cache_key":"0aaaa653a1bad3c2f1d6bbf34819ea4ae8700ea5d6c593937aa6812051809168","segment_id":"environment.md:453c14128fbfb5f6","source_path":"environment.md","text_hash":"453c14128fbfb5f6757511557132a1dbb3bcbf243267630bfec49db8518c7780","text":"Env var substitution in config","translated":"配置中的 环境变量 替换","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T12:58:16Z"} {"cache_key":"0b149311bd258e33ab5e06f16483d6b14bfb23bbf8137339bc4cf8d29e2d3d5c","segment_id":"environment.md:453c14128fbfb5f6","source_path":"environment.md","text_hash":"453c14128fbfb5f6757511557132a1dbb3bcbf243267630bfec49db8518c7780","text":"Env var substitution in config","translated":"配置中的环境变量替换","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T12:11:54Z"} {"cache_key":"0b68a76b412628864a90e4b194a0db6bcc593e8700ee9228d04b45427a95c7af","segment_id":"environment.md:cf3f9ba035da9f09","source_path":"environment.md","text_hash":"cf3f9ba035da9f09202ba669adca3109148811ef31d484cc2efa1ff50a1621b1","text":" (what the Gateway process already has from the parent shell/daemon).","translated":" （Gateway 进程从父 shell/守护进程继承的已有环境变量）。","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T12:57:23Z"} -{"cache_key":"0b6b7380e75d36476a24a56bb3825600832745e76c1a2d862e6631c0aa48c51e","segment_id":"index.md:41dc1288a547d7d1","source_path":"index.md","text_hash":"41dc1288a547d7d155c2d7b831e8cff388e12ab9d77d4c24cd0757ed47e9e209","text":" — Block streaming + Telegram draft streaming details (","translated":" — 块流式传输 + Telegram 草稿流式传输详情（","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T13:01:36Z"} {"cache_key":"0bab5344d37eb10f7f0a1105ba4cf723e069867a7f745d016657752c1dc0c21a","segment_id":"environment.md:5105555b1be5f84b","source_path":"environment.md","text_hash":"5105555b1be5f84b47576d6ea432675cef742e63fa52f7b254ef2aa4c90e7cca","text":" (applied only if","translated":" （仅在","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T11:46:04Z"} {"cache_key":"0bbc0779389fa7b103e39fff721c2df8f37e36a72350175e61b8334f79dd6555","segment_id":"index.md:0b7e778664921066","source_path":"index.md","text_hash":"0b7e77866492106632e98e7718a8e1e89e8cb0ee3f44c1572dfd9e54845023de","text":"/concepts/streaming","translated":"/concepts/streaming","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T13:30:06Z"} {"cache_key":"0bda3d8fa9978471f16800fbab17622f054477505f8a680d6165e924184818eb","segment_id":"index.md:3fc5f55ea5862824","source_path":"index.md","text_hash":"3fc5f55ea5862824fc266d26cd39fb5da22cc56670c11905d5743adac10bc9ef","text":"Mattermost Bot (plugin)","translated":"Mattermost 机器人（插件）","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T13:29:46Z"} @@ -87,7 +77,6 @@ {"cache_key":"11951539669d912b24dac16f9ed27e1de0a950a3baa481474a65de0ca85fbe7b","segment_id":"start/wizard.md:ec2d0a7d20f3b660","source_path":"start/wizard.md","text_hash":"ec2d0a7d20f3b6602a6593e0abef2337e84ba728ca8f6fef2534dc1e9dbfe06b","text":"Remote mode configures a local client to connect to a Gateway elsewhere.","translated":"远程模式配置本地客户端以连接到其他位置的 Gateway。","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T13:46:13Z"} {"cache_key":"11a42ddb57b9c1ba4022984efe25b463da52e7b9c5d7ec3a925d7a6d0e5a6c39","segment_id":"index.md:cdb4ee2aea69cc6a","source_path":"index.md","text_hash":"cdb4ee2aea69cc6a83331bbe96dc2caa9a299d21329efb0336fc02a82e1839a8","text":".","translated":".","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T13:28:19Z"} {"cache_key":"11a6809809867ab84f2a66da213f7894876530602a0743b37fc93e614c7ccbfe","segment_id":"help/index.md:71095a6d42f5d9c2","source_path":"help/index.md","text_hash":"71095a6d42f5d9c2464a8e3f231fc53636d4ce0f9356b645d245874162ec07e2","text":"Gateway troubleshooting","translated":"Gateway 故障排除","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T12:39:44Z"} -{"cache_key":"11e66a0f11d149ca8994761cbc3771066650e21d33cb9986d47624a35fb5f177","segment_id":"help/index.md:5c94724fa7810fa9","source_path":"help/index.md","text_hash":"5c94724fa7810fa9902e565cf66c5f5a973074f2961fcd3a40bad4ee4aeca5e0","text":"If you want a quick “get unstuck” flow, start here:","translated":"如果你想快速\"脱困\"，从这里开始：","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T12:21:37Z"} {"cache_key":"1226fe0b47712f49a01581113142855bc5ae36e3289353b5d592ece5191b0159","segment_id":"start/wizard.md:c90e6f2be18d7e02","source_path":"start/wizard.md","text_hash":"c90e6f2be18d7e02413e18d4174fe7d855c9753005652614556204123b37c96e","text":": browser flow; paste the ","translated":"：浏览器流程；粘贴 ","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T13:42:18Z"} {"cache_key":"1249a5c279b0761418bca0826571d62b0526075a0c91018c35002331e3c6d6b5","segment_id":"environment.md:aac7246f5e97142c","source_path":"environment.md","text_hash":"aac7246f5e97142c3f257b7d8b84976f10c29e1b89804bb9d3eb7c43cc03cb8e","text":"Environment variables","translated":"环境变量","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T12:25:14Z"} {"cache_key":"124e4ad52161941e1842f43e4f5d0c12d573babaf3f319ec7d5db46ba8ee7e84","segment_id":"index.md:0b60fe04b3c5c3c7","source_path":"index.md","text_hash":"0b60fe04b3c5c3c76371b6eca8b19c8e09a0e54c9010711ff87e782d87d2190b","text":"Android app","translated":"Android 应用","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T13:32:57Z"} @@ -115,7 +104,6 @@ {"cache_key":"18bd8d592ca11411d1c02c1a70123dc798352f581db4c9ce297c5ebb04841fa3","segment_id":"index.md:03279877bfe1de07","source_path":"index.md","text_hash":"03279877bfe1de0766393b51e69853dec7e95c287ef887d65d91c8bbe84ff9ff","text":"WebChat + macOS app","translated":"网页聊天 + macOS 应用","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T13:02:30Z"} {"cache_key":"190c49164ee5535fac803e9c0f057588d634e056d2c4fc072a0ca26e01ddc391","segment_id":"index.md:7d8b3819c6a9fb72","source_path":"index.md","text_hash":"7d8b3819c6a9fb726f40c191f606079b473f6f72d4080c13bf3b99063a736187","text":"Ops and safety:","translated":"运维和安全：","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T13:05:19Z"} {"cache_key":"19207e4ed0ae44f965f33707377a0217c1765cf57b09c0268ee36c10fb108dd9","segment_id":"index.md:c6e91f3b51641b1c","source_path":"index.md","text_hash":"c6e91f3b51641b1c43d297281ee782b40d9b3a0bdd7afc144ba86ba329d5f95f","text":"OpenClaw = CLAW + TARDIS","translated":"OpenClaw = CLAW + TARDIS","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T13:33:18Z"} -{"cache_key":"19429bac6dc1b8ea7457c6d7eb4bcf0f89cef2a5b2a017e79a0ed5d093e1665a","segment_id":"start/getting-started.md:6b65292dc52408c1","source_path":"start/getting-started.md","text_hash":"6b65292dc52408c15bb07aa90735e215262df697d1a7bd2d907c9d1ff294ed5e","text":"If you don’t have a global install yet, run the onboarding step via ","translated":"如果您尚未进行全局安装，请通过以下方式运行上手引导步骤 ","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T13:37:47Z"} {"cache_key":"194e63ecfe45556973c28ccafc39f814f42d2478037734ce44eee72f6fc6fc66","segment_id":"index.md:856302569e24c4d6","source_path":"index.md","text_hash":"856302569e24c4d64997e2ec5c37729f852bcccf333ba1e2f71e189c9d172e6d","text":": SSH tunnel or tailnet/VPN; see ","translated":"：SSH 隧道或 Tailnet/VPN；请参阅 ","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T13:29:21Z"} {"cache_key":"196942db05e9e40cbdf74a89cdd1be042430343a64ac2185009414f0d092af66","segment_id":"environment.md:cda454f61dfcac70","source_path":"environment.md","text_hash":"cda454f61dfcac7007a9edc538f9f58cf38caa0652e253975979308162bccc53","text":"Gateway configuration","translated":"Gateway 配置","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T13:13:11Z"} {"cache_key":"19c0ced45bb35a1d8801864910a9f7bc2c460229fdd97366f546255feeb1db0e","segment_id":"index.md:8816c52bc5877a2b","source_path":"index.md","text_hash":"8816c52bc5877a2b24e3a2f4ae7313d29cf4eba0ca568a36f2d00616cfe721d0","text":"Wizard","translated":"向导","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T12:59:12Z"} @@ -162,10 +150,8 @@ {"cache_key":"221e7c2c0fe8b9bb39aa23d66ead440852512864ee62242cc3d9290dbd135860","segment_id":"index.md:9bd86b0bbc71de88","source_path":"index.md","text_hash":"9bd86b0bbc71de88337aa8ca00f0365c1333c43613b77aaa46394c431cb9afd8","text":"Maxim Vovshin","translated":"Maxim Vovshin","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T13:33:49Z"} {"cache_key":"2220f5ebb94a086ce480f01165b1993d04e470d58154e2aa482056a2eecbb1f1","segment_id":"help/index.md:3c33340bd23b8db8","source_path":"help/index.md","text_hash":"3c33340bd23b8db89f18fe7d05a954738c0dd5ba9623cf6bdb7bb5d1a3729cfc","text":"FAQ (concepts)","translated":"常见问题（概念）","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T12:24:59Z"} {"cache_key":"2229ff2bff7c65fc1a4cd5515373b1b3319f43a26222f43787452e985cf5e4bb","segment_id":"index.md:11d28de5b79e3973","source_path":"index.md","text_hash":"11d28de5b79e3973f6a3e44d08725cdd5852e3e65e2ff188f6708ae9ce776afc","text":"Docs hubs (all pages linked)","translated":"文档中心（所有页面链接）","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T13:31:49Z"} -{"cache_key":"228b4027bfc7ab84d118c7534132c84e4135f86c319e047f014d862beb938c26","segment_id":"environment.md:a42cc4a7174c83a8","source_path":"environment.md","text_hash":"a42cc4a7174c83a853752b3e74cb001a234f3eca099688fdf0dd2540c60bb1e2","text":" expected keys:","translated":" 预期密钥：","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T12:26:16Z"} {"cache_key":"22baac03ae69320ee9635f7e23e85e926ed40c441e97357b30b48e271e88770f","segment_id":"index.md:013e11a23ec9833f","source_path":"index.md","text_hash":"013e11a23ec9833f907b2ead492b0949015e25d10ba92461669609aee559335d","text":"Start here:","translated":"从这里开始：","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T13:31:47Z"} {"cache_key":"22bfdd3e9e4f7a5447edf31592e38d663a8907afca5f46061f314b924280a94b","segment_id":"index.md:d53b75d922286041","source_path":"index.md","text_hash":"d53b75d9222860417f783b0829023b450905d982011d35f0e71de8eed93d90fc","text":"New install from zero:","translated":"从零开始全新安装：","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T12:47:41Z"} -{"cache_key":"22c699e5178ceeaa86c9029a62d9e0cea3b3c6ff75e19666d912f28097ecca91","segment_id":"index.md:5eeecff4ba2df15c","source_path":"index.md","text_hash":"5eeecff4ba2df15c51bcc1ba70a5a2198fbcac141ebe047a2db7acf0e1e83450","text":" — Local UI + menu bar companion for ops and voice wake","translated":" —— 本地界面 + 菜单栏伴侣应用，用于操作和语音唤醒","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T12:51:05Z"} {"cache_key":"22c7a06691f087acabe4321804edbb000eaf7520b16060ac2879f19252b639e3","segment_id":"index.md:31365ab9453d6a1e","source_path":"index.md","text_hash":"31365ab9453d6a1ec03731622803d3b44f345b6afad08040d7f3e97290c77913","text":"do nothing","translated":"不做任何操作","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T13:31:33Z"} {"cache_key":"22d40e91dde10d2912781df931ab0fac2802d5b81e63fdd93bdb7856c8c43976","segment_id":"environment.md:7175517a370b5cd2","source_path":"environment.md","text_hash":"7175517a370b5cd2e664e3fd29c4ea9db5ce17058eb9772fe090a5485e49dad6","text":" or ","translated":" 或 ","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T12:26:00Z"} {"cache_key":"23004dacbc322d02e170261429793a8b23569f398c4f21352a030b42543cdef9","segment_id":"index.md:6b65292dc52408c1","source_path":"index.md","text_hash":"6b65292dc52408c15bb07aa90735e215262df697d1a7bd2d907c9d1ff294ed5e","text":"If you don’t have a global install yet, run the onboarding step via ","translated":"如果您还没有全局安装，请通过以下方式运行 上手引导 步骤 ","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T12:51:37Z"} @@ -488,7 +474,6 @@ {"cache_key":"60cd1a8fee21c221c625fe6961c620592e9f99a88910d9f557d86f92e17d793c","segment_id":"start/wizard.md:1d6bc09c9a9a3dad","source_path":"start/wizard.md","text_hash":"1d6bc09c9a9a3dad8fcbe9ed89a206b2dba3d8cf16046315aee976577d534cae","text":"Downloads the appropriate release asset.","translated":"下载相应的发布资源。","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T13:47:59Z"} {"cache_key":"60f998f050fe63afd0938f40b2f1cf78a16d5dd9fa6abc631aa8e217ce1e7cc5","segment_id":"index.md:053bc65874ad6098","source_path":"index.md","text_hash":"053bc65874ad6098e58c41c57b378a2f36b0220e5e0b46722245e6c2f796818c","text":"Discord","translated":"Discord","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T12:53:15Z"} {"cache_key":"61277a40a0e409e2f324452a28cc35c44e1ac080b4400e7bdaa3c161ce51d545","segment_id":"start/wizard.md:3fcf806de5c2ace5","source_path":"start/wizard.md","text_hash":"3fcf806de5c2ace5327f65078cfb2139aaa8dd33ffdc3b04e9fef6f11778423c","text":"MiniMax M2.1","translated":"MiniMax M2.1","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T13:42:55Z"} -{"cache_key":"6131873fe6c607965685280107b0527c8bda0c8c322154c415c74adf0b2d6aea","segment_id":"environment.md:cf0923bd0c80e86a","source_path":"environment.md","text_hash":"cf0923bd0c80e86a7aa644d04aa412cbd7baa3273153c40c625ceca9e012bde8","text":" runs your login shell and imports only **missing** expected keys:","translated":" 运行你的登录 shell 并仅导入**缺失的**预期密钥：","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T12:19:37Z"} {"cache_key":"613744b9849b1cacbbcdcebd3fcb2637696f177d0364b9e32042a74bf2c1b350","segment_id":"index.md:80fc402133201fbe","source_path":"index.md","text_hash":"80fc402133201fbe0e4e9962a9570e741856aa8b0c033f1a20a9bcb06c68e809","text":"Discovery","translated":"发现","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T12:49:20Z"} {"cache_key":"613d01b2aa6e9a9127f428233d5f88e84e2c86b5079776f57becfe4143f86992","segment_id":"start/wizard.md:3ccbb3a92014470f","source_path":"start/wizard.md","text_hash":"3ccbb3a92014470f73c71c81684da45b1e07ee3a49cca372ec678ce89229ea58","text":"Vercel AI Gateway example:","translated":"Vercel AI Gateway 示例：","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T13:47:26Z"} {"cache_key":"614a1ff5ae5f98f2f46f1ee6bbb53ace3482d9d15a8842906f26dcbad10c4d71","segment_id":"index.md:084514e91f37c3ce","source_path":"index.md","text_hash":"084514e91f37c3ce85360e26c70b77fdc95f0d3551ce309db96fbcf956a53b01","text":"Dashboard (browser Control UI)","translated":"仪表板（浏览器控制界面）","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T12:59:30Z"} @@ -559,7 +544,6 @@ {"cache_key":"6b14f5e839df1e54026ee6d3db5886a6e9360039fd681101a4a9a2b101ff0919","segment_id":"index.md:084514e91f37c3ce","source_path":"index.md","text_hash":"084514e91f37c3ce85360e26c70b77fdc95f0d3551ce309db96fbcf956a53b01","text":"Dashboard (browser Control UI)","translated":"仪表盘（浏览器控制界面）","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T13:28:21Z"} {"cache_key":"6b3dbfa396df75c279946f5b8741a67863a0107d3f08c55dc642a8fac173a4c8","segment_id":"index.md:1074116f823ec992","source_path":"index.md","text_hash":"1074116f823ec992e76d7e8be19d3235fec5ddd7020562b06e7242e410174686","text":"Remote use","translated":"远程使用","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T12:49:11Z"} {"cache_key":"6b44e5cb8d21527ef6ad754e2792b9416080f2a132c8fd7b6d431fc76113aad9","segment_id":"environment.md:a42cc4a7174c83a8","source_path":"environment.md","text_hash":"a42cc4a7174c83a853752b3e74cb001a234f3eca099688fdf0dd2540c60bb1e2","text":" expected keys:","translated":" 预期的键：","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T12:22:25Z"} -{"cache_key":"6bf1a3983ec9759b076402ea6998c8207a0b0ef0d87b56ef4945599c9f8bd90a","segment_id":"environment.md:e4255aa4e8f9e525","source_path":"environment.md","text_hash":"e4255aa4e8f9e52571c9bc93336d0774bcd7f017b7b5297fb33b8e1986166f92","text":"), applied only for missing expected keys.","translated":"），仅对缺失的预期密钥应用。","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T12:26:02Z"} {"cache_key":"6c18bb32586b6c812ebf5323b8ed442c63be7b4014bc62e51f0d7f5eb46d223b","segment_id":"environment.md:582967534d0f909d","source_path":"environment.md","text_hash":"582967534d0f909d196b97f9e6921342777aea87b46fa52df165389db1fb8ccf","text":" in ","translated":" 在 ","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T12:40:54Z"} {"cache_key":"6c1b9632694258c227417b61df6433ac71eca1f2d35ff31cb5e145a7188dacfe","segment_id":"start/getting-started.md:d7849463c3ab6a49","source_path":"start/getting-started.md","text_hash":"d7849463c3ab6a496d77b8e6745d00ad430324bc5ed419a859f7c9e494102d68","text":"Manual run (foreground):","translated":"手动运行（前台）：","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T13:36:51Z"} {"cache_key":"6c3d2263be9d0d6dd77934bd87f882599e2e9449e67bdee4388f84ab0aa6571b","segment_id":"start/wizard.md:698fdfc9c55bd3e4","source_path":"start/wizard.md","text_hash":"698fdfc9c55bd3e4ed5a9365317ae70aac20783ec38057088da27012a470a901","text":"Gateway port ","translated":"Gateway 端口 ","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T13:39:50Z"} @@ -588,7 +572,6 @@ {"cache_key":"71667555ad1cea654225fec33df1804c97a0b8167affbf3d3c426ccb778e780a","segment_id":"start/wizard.md:82e1216ede141cb1","source_path":"start/wizard.md","text_hash":"82e1216ede141cb1553d20be7356c3f1ab9da9a4a05303cf7cd05ef01142558f","text":"Gateway settings (port/bind/auth/tailscale)","translated":"Gateway 设置（端口/绑定/认证/Tailscale）","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T13:40:23Z"} {"cache_key":"7170dcd349905701fd3cde7dc5bce0aed2618717e87ffa06e9ab230041f689a1","segment_id":"environment.md:cdb4ee2aea69cc6a","source_path":"environment.md","text_hash":"cdb4ee2aea69cc6a83331bbe96dc2caa9a299d21329efb0336fc02a82e1839a8","text":".","translated":"。","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T11:45:26Z"} {"cache_key":"724a450b6cdfc09dd0fc5acf94bb7f20a45c43e524810239d0e6e7cac65ff74b","segment_id":"index.md:bd293e4db98037bc","source_path":"index.md","text_hash":"bd293e4db98037bc9da5137af50453ac9c81b49e14eb4c47f121b12bed880877","text":" — Direct chats collapse into shared ","translated":" — 直接聊天合并到共享的 ","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T13:01:59Z"} -{"cache_key":"726990d1aefefc1ae562bce73f84f1de90c5c6cc094dc9121495e4480aedab92","segment_id":"environment.md:28e19c6e69c7a2aa","source_path":"environment.md","text_hash":"28e19c6e69c7a2aa071951dda3ff0a11ca178e3fb295dae8d6ed7dcc994434a4","text":" for full details.","translated":" 了解完整详情。","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T12:22:42Z"} {"cache_key":"72d5ce369dd6489f427c02710fae70f6426a51de9441678410a023761cee215b","segment_id":"start/wizard.md:8f7c7d2f15e90b42","source_path":"start/wizard.md","text_hash":"8f7c7d2f15e90b420fb6f2cc7632d7d7a433bc94eeb262d9718286e5ffd9b365","text":"Related docs","translated":"相关文档","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T13:49:00Z"} {"cache_key":"730b6369e65b8f27f57a90f6ee355beca28d783793767209a7cfe7beb736769b","segment_id":"start/wizard.md:eda31fe8fb873697","source_path":"start/wizard.md","text_hash":"eda31fe8fb873697fd7d5bfba08f263eaa917808a644bddd2b6d89d3a6b1c868","text":"QuickStart vs Advanced","translated":"快速入门与高级模式","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T13:39:30Z"} {"cache_key":"73164a8584f9cc4e546493100199d4ebcbb65ce74c33e21d06da689c6d7b9328","segment_id":"start/wizard.md:ce85fecfbffa2746","source_path":"start/wizard.md","text_hash":"ce85fecfbffa2746f0a9b66464140eb2ed5a085ce85fff062ef0ff8b5686a0a5","text":".\nSessions are stored under ","translated":"下。会话存储在 ","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T13:48:54Z"} @@ -624,7 +607,6 @@ {"cache_key":"77b6a43a45b36b25b51859a5b976fa12609b6d19ed351bc0e84fae2290d32da9","segment_id":"help/index.md:2adc964c084749b1","source_path":"help/index.md","text_hash":"2adc964c084749b1f2d8aef24030988b667dbda2e38a6a1699556c93e07c1cea","text":"Start here","translated":"从这里开始","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T13:11:12Z"} {"cache_key":"7806b590e1e2ff8ab2244875f7a2c370ab3b11462fd2061e5f4af9cf72f70d19","segment_id":"start/wizard.md:9c706a2bb9ebcb20","source_path":"start/wizard.md","text_hash":"9c706a2bb9ebcb206633616f2a40867b0c02716657ac4c0e95c7c1939287d3d8","text":"; auth profiles live in ","translated":"；认证配置存储在 ","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T13:43:31Z"} {"cache_key":"78161c8de8a14607cd003796d4c4ace7048f9116ecbe036601136d7f0cef4ff3","segment_id":"start/getting-started.md:bfd99edf844f6205","source_path":"start/getting-started.md","text_hash":"bfd99edf844f62050af2f7d37df7cfa7f651b8e1be341eb4f07c3849ca4efc43","text":"Fastest chat: open the Control UI (no channel setup needed). Run ","translated":"最快聊天方式：打开控制界面（无需设置渠道）。运行 ","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T13:34:33Z"} -{"cache_key":"78165d4ed88f199c04e34f0686aca8ee87969331cf02c78e26a1851d3673baae","segment_id":"help/index.md:0b554dd0f4b96cff","source_path":"help/index.md","text_hash":"0b554dd0f4b96cff4e1137c5fb22253b12125b6a3dce5d9238c80b20491bcb8e","text":"Help\n\nIf you want a quick “get unstuck” flow, start here:","translated":"# 帮助\n\n如果你想要一个快速的\"脱困\"流程，从这里开始：","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T12:15:12Z"} {"cache_key":"785cae01bc172c4c47e2e82cda4c5afd7d37d7069a008e44c8a4176eeacafe67","segment_id":"help/index.md:a8ab86b9313a9236","source_path":"help/index.md","text_hash":"a8ab86b9313a92362150f5e5ba8a19de4ee52f2e3162f9bd2bc6cf128a2fcd18","text":"If you’re looking for conceptual questions (not “something","translated":"如果你在寻找概念性问题（不是\"出了什么","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T11:45:00Z"} {"cache_key":"78ae0fabb1aab02156d5bf1b4e148ba155369b079aa0b733aca5a750a3d0cdc2","segment_id":"index.md:329f3c913c0a1636","source_path":"index.md","text_hash":"329f3c913c0a16363949eb8ee7eb0cda7e81137a3851108019f33e5d18b57d8f","text":"Switching between npm and git installs later is easy: install the other flavor and run ","translated":"之后在 npm 和 git 安装之间切换很简单：安装另一种方式然后运行 ","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T12:51:30Z"} {"cache_key":"791458a3464d7dd0036471e90590958905611942f9f0aefd8917c701e4e587d4","segment_id":"start/wizard.md:0516de0bbbd36c95","source_path":"start/wizard.md","text_hash":"0516de0bbbd36c95c5c45902d43caf2abdab59363114c4d6abae961f6ed1c1cb","text":" imply non-interactive mode. Use ","translated":" 意味着非交互模式。请使用 ","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T13:40:50Z"} @@ -669,7 +651,6 @@ {"cache_key":"7eefff451137a5fd592db6fef6e65447cae69abe23699c34cb838a1c3cc04d73","segment_id":"start/wizard.md:d3745cec7a646b22","source_path":"start/wizard.md","text_hash":"d3745cec7a646b229f6d7123ef3557f68640f35a54a593f1e0e32776da0677c1","text":" (auto‑generated, even on loopback)","translated":" （自动生成，即使在回环地址上也是如此）","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T13:39:58Z"} {"cache_key":"7f2e9e14503f22acab8659b458900c0864bdc52ee5055d4a3a742508a8e41314","segment_id":"environment.md:45ca56d179d4788c","source_path":"environment.md","text_hash":"45ca56d179d4788c55ba9f7653b376d62e7faa738e92259e3d4f6f5c1b554f28","text":"Related","translated":"相关","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T11:47:13Z"} {"cache_key":"7f4d30ae34bbfb95b016db35c14a77f46cdda52ff397a69b63ad655c6128f0f6","segment_id":"index.md:30f035b33a6c35d5","source_path":"index.md","text_hash":"30f035b33a6c35d51e09f9241c61061355c872f2fb9a82822cd2f5f443fd4ad4","text":"Group Chat Support","translated":"群聊支持","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T13:30:31Z"} -{"cache_key":"7f5759f942e4173b7e990de6fbc0eada6e5b6c3106c5aa6fae08456d7b79dcf8","segment_id":"index.md:6b65292dc52408c1","source_path":"index.md","text_hash":"6b65292dc52408c15bb07aa90735e215262df697d1a7bd2d907c9d1ff294ed5e","text":"If you don’t have a global install yet, run the onboarding step via ","translated":"如果尚未进行全局安装，请通过以下方式运行上手引导步骤 ","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T13:31:19Z"} {"cache_key":"7f8a0ec6c0614299ed8aca539dde67e208ecc32d4022975fbb37f7930f3f70e5","segment_id":"start/getting-started.md:4cc7ae6d3b7fbaaf","source_path":"start/getting-started.md","text_hash":"4cc7ae6d3b7fbaaf56673ea3268caa38af191a587867ef1090c9f689ecccec96","text":"Headless/server tip: do OAuth on a normal machine first, then copy ","translated":"无头/服务器提示：先在普通机器上完成 OAuth，然后复制 ","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T13:36:40Z"} {"cache_key":"7fec8c329b4438aef905e1918364b86faca2a2580bb29eded4850a67ba16109b","segment_id":"environment.md:496aca80e4d8f29f","source_path":"environment.md","text_hash":"496aca80e4d8f29fb8e8cd816c3afb48d3f103970b3a2ee1600c08ca67326dee","text":" block","translated":" 块","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T12:25:48Z"} {"cache_key":"8070c35741bdfaa2f8878a7460406a597ccf7fec7994522389adeafea46b6e8e","segment_id":"environment.md:frontmatter:read_when:0","source_path":"environment.md:frontmatter:read_when:0","text_hash":"90fc0487bff88009979cff1061c1a882df8c3b1baa9c43538331d9d5dab15479","text":"You need to know which env vars are loaded, and in what order","translated":"你需要了解加载了哪些环境变量，以及加载的顺序","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T11:45:10Z"} @@ -681,7 +662,6 @@ {"cache_key":"822efbc5bcf680421493847f6b76e9626f1d8202ff5ff47cd3e141ecdac58a9f","segment_id":"environment.md:496aca80e4d8f29f","source_path":"environment.md","text_hash":"496aca80e4d8f29fb8e8cd816c3afb48d3f103970b3a2ee1600c08ca67326dee","text":" block","translated":" 块","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T12:16:27Z"} {"cache_key":"829cc48b5c60f16b09e63437a5de27acc17910473f8e3dfbc505a0d3e3b593c7","segment_id":"start/wizard.md:79a482cf546c23b0","source_path":"start/wizard.md","text_hash":"79a482cf546c23b04cd48a33d4ca8411f62e5b7dc8c3a8f30165e28e747f263a","text":"iMessage","translated":"iMessage","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T13:44:54Z"} {"cache_key":"82d122e7cc5c895b61dec28850c3f07a68e69c19f554d9088318f62c6cd30fe1","segment_id":"environment.md:6d28a9f099e563d9","source_path":"environment.md","text_hash":"6d28a9f099e563d9322b5bcdea9ff98af87e9c213c2222462ae738d2fb27ecbe","text":" block\n\nTwo equivalent ways to set inline env vars (both are non-overriding):","translated":" 块\n\n设置内联环境变量的两种等效方式（均为非覆盖式）：","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T12:16:44Z"} -{"cache_key":"83090d5cbebceddaa2f500bdb4240d4ea9a8ee14da3654f77128a067e4dc220a","segment_id":"environment.md:e4255aa4e8f9e525","source_path":"environment.md","text_hash":"e4255aa4e8f9e52571c9bc93336d0774bcd7f017b7b5297fb33b8e1986166f92","text":"), applied only for missing expected keys.","translated":"），仅对缺失的预期密钥应用。","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T13:12:37Z"} {"cache_key":"8334186d1a61e931ed7b3905a26e470159f86593819124c5626df7a012733ee9","segment_id":"environment.md:frontmatter:summary","source_path":"environment.md:frontmatter:summary","text_hash":"78351223e7068721146d2de022fdf440c2866b2ee02fbbb50bf64369b999820b","text":"Where OpenClaw loads environment variables and the precedence order","translated":"其中 OpenClaw 加载 环境变量 及优先级顺序","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T12:56:59Z"} {"cache_key":"833685db37cf96f2342238018bd6a4a6e7812d1794a7389dc1e349917b140f50","segment_id":"environment.md:668e5590b5bb9990","source_path":"environment.md","text_hash":"668e5590b5bb9990eeb25bf657f7d17281a4c613ee4442036787cd4b2efd22bb","text":"If the config file is missing entirely, step 4 is skipped; shell import still runs if enabled.","translated":"如果配置文件完全缺失，则跳过第 4 步；如果启用了 shell 导入，它仍会运行。","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T12:19:28Z"} {"cache_key":"834bd8857aa5700b0ec493efb4625ba88e34c885a8254b13f6c44a75589021d2","segment_id":"index.md:9bcda844990ec646","source_path":"index.md","text_hash":"9bcda844990ec646b3b6ee63cbdf10f70b0403727dea3b5ab601ca55e3949db9","text":" for node WebViews; see ","translated":" 用于节点 WebView；请参阅 ","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T13:29:13Z"} @@ -695,7 +675,6 @@ {"cache_key":"84c686db4b4fc386bbb4efa35c380073babbc5fb4b2eb1ba3a8213a5f135a5bc","segment_id":"start/getting-started.md:161660030aa6c9e3","source_path":"start/getting-started.md","text_hash":"161660030aa6c9e32470cc1c023dab32dc748d80b0e61882b368cb775d12638e","text":" → ","translated":" → ","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T13:34:27Z"} {"cache_key":"84e200d4c823802e34a99da4faa8328d0e250aca858b0a32cc08e3ae12e0cc0e","segment_id":"start/wizard.md:e4442451c634e0db","source_path":"start/wizard.md","text_hash":"e4442451c634e0db2db0fae78725becbeafd567302e3ecbfeb5ccdc5887d29be","text":" from GitHub releases:","translated":" （从 GitHub 发布版本）：","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T13:47:56Z"} {"cache_key":"85040674d9e2db6adb1ebb8c6215e72171d213a9dac8bd3c6bcb438178adc88b","segment_id":"index.md:0a4a282eda1af348","source_path":"index.md","text_hash":"0a4a282eda1af34874b588bce628b76331fbe907de07b57d39afdedccac2ba14","text":" http://127.0.0.1:18789/ (or http://localhost:18789/)","translated":" http://127.0.0.1:18789/（或 http://localhost:18789/）","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T13:28:15Z"} -{"cache_key":"850dacfab0ff7f9fd9498aeac24c0b84c59f266291d504465d7dead52da552bf","segment_id":"index.md:41dc1288a547d7d1","source_path":"index.md","text_hash":"41dc1288a547d7d155c2d7b831e8cff388e12ab9d77d4c24cd0757ed47e9e209","text":" — Block streaming + Telegram draft streaming details (","translated":" — 块流式传输 + Telegram 草稿流式传输详情（","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T13:30:04Z"} {"cache_key":"85cb0b7ed6991128b9fe65b7b103c5f32da742641cb24ffc1a3469002a2bcad6","segment_id":"start/getting-started.md:e24d86fa815827a4","source_path":"start/getting-started.md","text_hash":"e24d86fa815827a4dc5b8b22711caaf036427796512a74167ebaf615c495f9f8","text":"Telegram / Discord / others","translated":"Telegram / Discord / 其他","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T13:37:17Z"} {"cache_key":"85e39779810391375b7241f2d999fbd5e6b2830ddf226a9ad561132c40d4fd47","segment_id":"start/wizard.md:21b111cbfe6e8fca","source_path":"start/wizard.md","text_hash":"21b111cbfe6e8fca2d181c43f53ad548b22e38aca955b9824706a504b0a07a2d","text":"Default ","translated":"默认 ","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T13:43:41Z"} {"cache_key":"85fdea7998dfe111261588f998c93aceaa9b04ba174bc16bd188e3bbd8f3228a","segment_id":"environment.md:668e5590b5bb9990","source_path":"environment.md","text_hash":"668e5590b5bb9990eeb25bf657f7d17281a4c613ee4442036787cd4b2efd22bb","text":"If the config file is missing entirely, step 4 is skipped; shell import still runs if enabled.","translated":"如果配置文件完全缺失，则跳过第 4 步；如果已启用，shell 导入仍会运行。","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T13:12:40Z"} @@ -712,7 +691,6 @@ {"cache_key":"87b42c17fb63bfdcd059198572016f6b8b3cd297aaa991c4c1dea8723a68fbfe","segment_id":"index.md:9abe8e9025013e78","source_path":"index.md","text_hash":"9abe8e9025013e78a6bf2913f8c20ee43134ad001ce29ced89e2af9c07096d8f","text":"Media: images","translated":"媒体：图片","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T13:32:48Z"} {"cache_key":"87d80d180c9d4789c20123b3bc177f99c4d00909f70c6fe3c209c078bdcafdce","segment_id":"index.md:1074116f823ec992","source_path":"index.md","text_hash":"1074116f823ec992e76d7e8be19d3235fec5ddd7020562b06e7242e410174686","text":"Remote use","translated":"远程使用","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T13:00:36Z"} {"cache_key":"87f8e99a729beb8e55fdef7ca70ebe4b11f4ff1c5dbbfcb3e654429198c6bf0f","segment_id":"help/index.md:729bc562eec2658b","source_path":"help/index.md","text_hash":"729bc562eec2658bd11ffdd522fe5277177dc73e86eaca7baac0b472a4d8f8b2","text":"If you’re looking for conceptual questions (not “something broke”):","translated":"如果你在寻找概念性问题（不是\"出了故障\"）：","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T12:19:05Z"} -{"cache_key":"8819cee05e67d9206c9adc7cf9539b1586a050f9c259e65a3099184303440591","segment_id":"environment.md:a42cc4a7174c83a8","source_path":"environment.md","text_hash":"a42cc4a7174c83a853752b3e74cb001a234f3eca099688fdf0dd2540c60bb1e2","text":" expected keys:","translated":" 预期密钥：","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T12:58:11Z"} {"cache_key":"88ab429b0aa43b0cfc93a1fc0e69576a2acbf64d0cd407fc1028488a0c27c9fc","segment_id":"index.md:fdef9f917ee2f72f","source_path":"index.md","text_hash":"fdef9f917ee2f72fbd5c08b709272d28a2ae7ad8787c7d3b973063f0ebeeff7a","text":" to update the gateway service entrypoint.","translated":" 以更新网关服务入口点。","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T13:03:03Z"} {"cache_key":"88d02146dbe2246af19afc2deecbb627547528cd1bf8b9839d358e8987a88a99","segment_id":"index.md:9c870aa6e5e93270","source_path":"index.md","text_hash":"9c870aa6e5e93270170d5a81277ad3e623afe8d4efd186d3e28f3d2b646d52e6","text":"How it works","translated":"工作原理","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T12:59:42Z"} {"cache_key":"88f63f39528cb8bcb530a350a6b610125dbf6ab7034c2509a772e2ec28ed9476","segment_id":"help/index.md:frontmatter:read_when:1","source_path":"help/index.md:frontmatter:read_when:1","text_hash":"857eafc389d179e83e21e46c10527fec40894fe064c63847ba06b946b7d5eb73","text":"Something broke and you want the fastest path to a fix","translated":"出了问题，你想找到最快的修复方法","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T12:15:10Z"} @@ -725,7 +703,6 @@ {"cache_key":"8a81f73e519177081d755623ff45ac47552fa513f5aaf9c77335ce2c329087f3","segment_id":"start/getting-started.md:524bf322c2034388","source_path":"start/getting-started.md","text_hash":"524bf322c2034388f76cd94c1c7834341cedfa09bc4a864676749a08b243416d","text":"model/auth (OAuth recommended)","translated":"模型/认证（推荐使用 OAuth）","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T13:34:53Z"} {"cache_key":"8a83aabc21a6b84ce7552d72a9bc0a7c2d99864c31350064cbd39564354421f1","segment_id":"index.md:9adcfa4aa10a4e8b","source_path":"index.md","text_hash":"9adcfa4aa10a4e8b991a72ccc45261cd64f296aed5b257e4caf9c87aff1290a0","text":" — Send and receive images, audio, documents","translated":" —— 发送和接收图片、音频、文档","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T12:50:51Z"} {"cache_key":"8a984f774ac8874be4797ffddd21cbdddc9379fa6bc51121620fbe9395cd91cf","segment_id":"help/index.md:bfc5930cc2660330","source_path":"help/index.md","text_hash":"bfc5930cc2660330260afd407e98d86adaec0af48dd72b88dc33ef8e9066e2c9","text":"Install sanity (Node/npm/PATH):","translated":"安装完整性检查（Node/npm/PATH）：","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T12:15:18Z"} -{"cache_key":"8aba2e1efca29d503bd185064c1e676dd87fa34c81fa9bb059ed6300f6bfd517","segment_id":"environment.md:28e19c6e69c7a2aa","source_path":"environment.md","text_hash":"28e19c6e69c7a2aa071951dda3ff0a11ca178e3fb295dae8d6ed7dcc994434a4","text":" for full details.","translated":" 了解完整详情。","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T12:41:35Z"} {"cache_key":"8ac55f265f3496db43dce513fde21c137826476afcff2ed1b3e86e613ff28b3c","segment_id":"start/wizard.md:44dab6c89cc5e6d9","source_path":"start/wizard.md","text_hash":"44dab6c89cc5e6d9a3112d3cb45c19cd16c3a9963082276015d4b624e5e67782","text":"Some channels are delivered as plugins. When you pick one during onboarding, the wizard\nwill prompt to install it (npm or a local path) before it can be configured.","translated":"部分渠道以插件形式提供。当您在上手引导期间选择某个渠道时，向导会提示先安装它（通过 npm 或本地路径），然后才能进行配置。","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T13:48:57Z"} {"cache_key":"8b2c90beec3893be65468e57df762fcbc285a9772042200eee3d4bf8f7ff9c0d","segment_id":"index.md:96be070791b7d545","source_path":"index.md","text_hash":"96be070791b7d545dc75084e59059d2170eed247350b351db5330fbd947e4be6","text":"👥 ","translated":"👥 ","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T13:30:29Z"} {"cache_key":"8b921a960a8b92bc6210c2e228fe886cd93000a5a77f1cb5ac97233de2c4f965","segment_id":"index.md:fb87b8dba88b3edc","source_path":"index.md","text_hash":"fb87b8dba88b3edced028edfe2efa5f884ab2639c1b26efa290ccd0469454d25","text":"Slash commands","translated":"斜杠命令","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T13:04:03Z"} @@ -807,7 +784,6 @@ {"cache_key":"9a7478d471c30618239146c8b7adbd3669fd552a2fafba13cc6dc8b51c083243","segment_id":"index.md:a194ca16424ddd17","source_path":"index.md","text_hash":"a194ca16424ddd17dacc45f1cbd7d0e41376d8955a7b6d02bc38c295cedd04e4","text":"RPC adapters","translated":"RPC 适配器","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T13:04:25Z"} {"cache_key":"9aaaeb76bc162fe216b19290b0978994ad43023335a81224b65bf7e4849ed5b6","segment_id":"index.md:frontmatter:summary","source_path":"index.md:frontmatter:summary","text_hash":"891b2aa093410f546b89f8cf1aa2b477ba958c2c06d2ae772e126d49786df061","text":"Top-level overview of OpenClaw, features, and purpose","translated":"OpenClaw 的顶层概述、功能和用途","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T12:47:18Z"} {"cache_key":"9b0b553b6bb64b97bc340190fc4f10febadb5c4542122d2dea4661534f60b8b6","segment_id":"index.md:a10f6ed8c1ddbc10","source_path":"index.md","text_hash":"a10f6ed8c1ddbc10d3528db7f7b6921c1dd5a5e78aa191ff017bf29ce2d26449","text":"⏱️ ","translated":"⏱️ ","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T12:50:04Z"} -{"cache_key":"9b4a9e428618ff38c3d8e54131d987860c0ebbb45007e3493d99964d9cd436a6","segment_id":"index.md:4d705f0fa835fd21","source_path":"index.md","text_hash":"4d705f0fa835fd216c4fd6dea0ee851d33720e23fb714c4c9ea74ac3211fccdc","text":"Discovery + transports","translated":"发现机制 + 传输方式","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T13:32:28Z"} {"cache_key":"9bb6f5ad39ff9d7aff3bca1fda6f474e19f25c0ffaaffaf3b19c924234d8c03a","segment_id":"index.md:f0d82ba647b4a33d","source_path":"index.md","text_hash":"f0d82ba647b4a33da3008927253f9bed21e380f54eab0608b1136de4cbff1286","text":"OpenClaw bridges WhatsApp (via WhatsApp Web / Baileys), Telegram (Bot API / grammY), Discord (Bot API / channels.discord.js), and iMessage (imsg CLI) to coding agents like ","translated":"OpenClaw 将 WhatsApp（通过 WhatsApp Web / Baileys）、Telegram（Bot API / grammY）、Discord（Bot API / 渠道.discord.js）和 iMessage（imsg CLI）桥接到编程 智能体，例如 ","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T12:47:31Z"} {"cache_key":"9c03abf2c27129fa2698e7640a7b9add5936e84cf6d779d5f189bf9a27940aa6","segment_id":"index.md:310cc8cec6b20a30","source_path":"index.md","text_hash":"310cc8cec6b20a3003ffab12f5aade078a0e7a7d6a27ff166d62ab4c3a1ee23d","text":"If you ","translated":"如果你 ","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T13:03:25Z"} {"cache_key":"9c11b2ec1c922e332f69000a8a937f0a2318b5356faa6278a7580cc49c3526d5","segment_id":"index.md:e47cdb55779aa06a","source_path":"index.md","text_hash":"e47cdb55779aa06a74ae994c998061bd9b7327f5f171c141caf2cf9f626bfe4b","text":"Peter Steinberger","translated":"Peter Steinberger","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T13:05:52Z"} @@ -818,7 +794,6 @@ {"cache_key":"9cbdb7ff14fdd8d015b7bcce3b3c0d48b1711e631ff86cae2c699684f8e4d143","segment_id":"start/wizard.md:c4b2896a2081395e","source_path":"start/wizard.md","text_hash":"c4b2896a2081395e282313d6683f07c81e3339ef8b9d2b5a299ea5b626a0998f","text":").","translated":"）。","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T13:41:17Z"} {"cache_key":"9d44e8f510b7e2cf5ea7b08188a9c606937bc3db8c49e22d903828b34b8b04c1","segment_id":"start/wizard.md:19f53c2ccaf19969","source_path":"start/wizard.md","text_hash":"19f53c2ccaf199696e23d43812941e23fed0625900d2a551533304d6ca1980f6","text":" install or change anything on the remote host.","translated":" 在远程主机上安装或更改任何内容。","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T13:40:40Z"} {"cache_key":"9d7b3ce341253f712ecd8b4ca661ae0a6d85b1ee8e8ddf00b1ec02ca13d67237","segment_id":"help/index.md:569ca49f4aaf7846","source_path":"help/index.md","text_hash":"569ca49f4aaf7846e952c1d4aeca72febd0b79fa1c4f9db08fd3127551218572","text":"Install","translated":"安装","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T12:24:41Z"} -{"cache_key":"9d829bdffa4f3aa22d063ea4b6391f8094b8f4db9df8a985430559d4a153e286","segment_id":"index.md:58d30d963f28264b","source_path":"index.md","text_hash":"58d30d963f28264bd9ba0e2d4c07c2c43c0ac1c1609c25b3fccf475eebf41727","text":"Skills config","translated":"技能配置","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T13:04:19Z"} {"cache_key":"9db03f9dc7b789dbc3b4115e9b644cd22de2a63adeed02eb3b403a223d96b819","segment_id":"index.md:2b402c90e9b15d9c","source_path":"index.md","text_hash":"2b402c90e9b15d9c3ef65c432c4111108f54ee544cda5424db46f6ac974928e4","text":"🔐 ","translated":"🔐 ","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T13:30:14Z"} {"cache_key":"9e0b7ed9895b612971d582145c837e95bfec8b051c6bccddd008d56dff778711","segment_id":"start/wizard.md:28d03596d24eeb4e","source_path":"start/wizard.md","text_hash":"28d03596d24eeb4eab2d6fe21ca1cb95be7cb1fa6f92933db05e2cc4f4cdfa06","text":"Skip","translated":"跳过","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T13:43:16Z"} {"cache_key":"9e3a338fc3d6bce679ff4711d74e67c66877245b6ebd2c2a08f182a3a788dae6","segment_id":"start/getting-started.md:fd82e54418ec23cd","source_path":"start/getting-started.md","text_hash":"fd82e54418ec23cda00219878eaf76c3b37337b3dcb7560a941db6a0d2ec249e","text":": background install (launchd/systemd; WSL2 uses systemd)","translated":"：后台安装（launchd/systemd；WSL2 使用 systemd）","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T13:36:15Z"} @@ -848,7 +823,6 @@ {"cache_key":"a235aca76de620b9ed0805727dc5f142a660dc6dac3254a01531acad96cb084d","segment_id":"index.md:d53b75d922286041","source_path":"index.md","text_hash":"d53b75d9222860417f783b0829023b450905d982011d35f0e71de8eed93d90fc","text":"New install from zero:","translated":"从零开始全新安装：","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T12:59:05Z"} {"cache_key":"a28528856eac855eaf431dc468f5d1a9b3918df6dc73a9bb54c488aa7c23faad","segment_id":"start/getting-started.md:387847437e10c06c","source_path":"start/getting-started.md","text_hash":"387847437e10c06cae87567a6579b38e71849aea9c2355eba4a8d090418360b9","text":"The wizard can write tokens/config for you. If you prefer manual config, start with:","translated":"向导可以为您写入令牌/配置。如果您更喜欢手动配置，请从以下内容开始：","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T13:37:19Z"} {"cache_key":"a28d9fd85bfd4afc9a62b3cfe12607c86001b32a9a97d72eeb6cd50993fb51ee","segment_id":"index.md:c6e91f3b51641b1c","source_path":"index.md","text_hash":"c6e91f3b51641b1c43d297281ee782b40d9b3a0bdd7afc144ba86ba329d5f95f","text":"OpenClaw = CLAW + TARDIS","translated":"OpenClaw = CLAW + TARDIS","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T12:54:04Z"} -{"cache_key":"a29d82b0936a3237f692bb4c86bb8bcc8b1840db6ab6f2922a249fda830bdc5a","segment_id":"index.md:4d705f0fa835fd21","source_path":"index.md","text_hash":"4d705f0fa835fd216c4fd6dea0ee851d33720e23fb714c4c9ea74ac3211fccdc","text":"Discovery + transports","translated":"发现 + 传输","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T13:04:36Z"} {"cache_key":"a2c462e51d228b070aba2a14a09d41aa54e0962d795724d5a090c71c7e242dfe","segment_id":"start/getting-started.md:acdd1e734125f341","source_path":"start/getting-started.md","text_hash":"acdd1e734125f341604c0efbabdcc4c4b0597e8f6235d66c2445edd1812838c1","text":"Telegram","translated":"Telegram","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T13:37:22Z"} {"cache_key":"a2f08193fbeb8a9400b75d96157bbbf488ab3aa51d50658094d00bb841646217","segment_id":"help/index.md:2adc964c084749b1","source_path":"help/index.md","text_hash":"2adc964c084749b1f2d8aef24030988b667dbda2e38a6a1699556c93e07c1cea","text":"Start here","translated":"从这里开始","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T11:44:37Z"} {"cache_key":"a32d46351380765e1ec38639781fc9e5abaccdf74240eee7ab685f570551f487","segment_id":"index.md:7d8b3819c6a9fb72","source_path":"index.md","text_hash":"7d8b3819c6a9fb726f40c191f606079b473f6f72d4080c13bf3b99063a736187","text":"Ops and safety:","translated":"运维与安全：","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T13:33:04Z"} @@ -858,7 +832,6 @@ {"cache_key":"a3909a297d0e74a4cb418a7a549f495f6eed24048ebf8f12f448eff8d7a20c50","segment_id":"environment.md:1ec31258a6b45ea9","source_path":"environment.md","text_hash":"1ec31258a6b45ea903cd76f5b0190a99ab56afff6241a04f0681eb12b7a02484","text":"Env var equivalents:","translated":"等效的环境变量：","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T12:26:18Z"} {"cache_key":"a3e59ee4578bdb5fd68940692f78e9389e163da63e350ba9f0689ffbc980d4a5","segment_id":"environment.md:28b1103adde15a9d","source_path":"environment.md","text_hash":"28b1103adde15a9ddd8fc71f0c57dc155395ade46a0564865ccb5135b01c99b7","text":"OpenClaw pulls environment variables from multiple sources. The rule is **never override existing values**.","translated":"OpenClaw 从多个来源拉取环境变量。规则是**永远不覆盖已有的值**。","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T12:19:23Z"} {"cache_key":"a4384986e5ce06eca0118051e6a851ac0fd3d922d4d1f31b60000687962a2288","segment_id":"start/wizard.md:ec1a3a5d6d6f0bac","source_path":"start/wizard.md","text_hash":"ec1a3a5d6d6f0baca7805bf1ea17fc7b02042416f02f80bc1970ad8c710abd89","text":"Flow details (local)","translated":"流程详情（本地）","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T13:40:56Z"} -{"cache_key":"a44af8d86be9e8883c8df3ed68722e659e4d7bb99e2675df13ee0ab386219e51","segment_id":"index.md:22159a426e4f2635","source_path":"index.md","text_hash":"22159a426e4f26356382cc3ac9b2e7af5123c1309250332f5dcbbc6e6f952b0e","text":"Network model","translated":"网络 模型","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T12:59:51Z"} {"cache_key":"a46b3daf9b1e1045e72e437a283e8377ec9b4820cde181d05a24a9a582cbf914","segment_id":"start/wizard.md:12754931af777521","source_path":"start/wizard.md","text_hash":"12754931af777521bcb6a904d2a7d342d0d77e6c4f1f2eb1b8b3753d25a1ab4a","text":"If the Control UI assets are missing, the wizard attempts to build them; fallback is ","translated":"如果 Control UI 资源文件缺失，向导会尝试构建它们；后备方案是 ","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T13:46:06Z"} {"cache_key":"a4a009f8c9411234d5dd3ef4a71fdf292ec59e29a2b74d197acea1c789825536","segment_id":"help/index.md:6cb77499abdccd9a","source_path":"help/index.md","text_hash":"6cb77499abdccd9a2dbb7c93a4d31eed01613dda06302933057970df9ecdeb54","text":"Logs:","translated":"日志：","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T12:24:46Z"} {"cache_key":"a4b963e5c58f681343b2e7b98ade4df71e3a328906ed382ffc8c0e4853fdf162","segment_id":"environment.md:b1d6b91b67c2afa5","source_path":"environment.md","text_hash":"b1d6b91b67c2afa5e322988d9462638d354ddf8a1ef79dba987f815c22b4baee","text":" at ","translated":" 位于 ","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T12:25:39Z"} @@ -891,7 +864,6 @@ {"cache_key":"a9c30fa450ed436cb03bc256b3075761a9215bd99bcd7bd2891cf15317ffd34f","segment_id":"environment.md:d08a8493f686363a","source_path":"environment.md","text_hash":"d08a8493f686363a78b913d45ebfbd87a3768d1c77b70f23b1fdade3c066e481","text":"Shell env import","translated":"Shell 环境导入","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T12:16:47Z"} {"cache_key":"aa80cfc76e76409c5ba7bf331e4fb8aadf72703ead80d203c94e74209da993f9","segment_id":"index.md:310cc8cec6b20a30","source_path":"index.md","text_hash":"310cc8cec6b20a3003ffab12f5aade078a0e7a7d6a27ff166d62ab4c3a1ee23d","text":"If you ","translated":"如果你 ","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T13:31:31Z"} {"cache_key":"aaa5becdcd694b68de2e61f6a13bd932c3f80f8b0b5a959a054a61ad5911beef","segment_id":"index.md:81a1c0449ea684aa","source_path":"index.md","text_hash":"81a1c0449ea684aadad54a7f8575061ddc5bfa713b6ca3eb8a0228843d2a3ea1","text":"Nodes (iOS/Android)","translated":"节点（iOS/Android）","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T13:32:22Z"} -{"cache_key":"aab013ce01ee6fc5b450d86a4cb8582865cc8b2e84ef22a6b5e0191462c1ee45","segment_id":"index.md:6b65292dc52408c1","source_path":"index.md","text_hash":"6b65292dc52408c15bb07aa90735e215262df697d1a7bd2d907c9d1ff294ed5e","text":"If you don’t have a global install yet, run the onboarding step via ","translated":"如果尚未进行全局安装，请通过以下方式运行 上手引导 步骤 ","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T13:03:09Z"} {"cache_key":"aacffcbc2a97abf1a5eccd00e5893be1125e364251fa27f3e0c88ef2db2b0248","segment_id":"index.md:acdd1e734125f341","source_path":"index.md","text_hash":"acdd1e734125f341604c0efbabdcc4c4b0597e8f6235d66c2445edd1812838c1","text":"Telegram","translated":"Telegram","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T13:32:36Z"} {"cache_key":"aad00bc21098071ff9c86ff467cb7f5c65d3467ce4bf7d707f560479783e9eaa","segment_id":"index.md:b79cac926e0b2e34","source_path":"index.md","text_hash":"b79cac926e0b2e347e72cc91d5174037c9e17ae7733fd7bdb570f71b10cd7bfc","text":"Help","translated":"帮助","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T13:31:51Z"} {"cache_key":"aae01909516ef373ddb2e4996f9016675f297208f7f075a68490f1f48eb0c87f","segment_id":"environment.md:6a26e1694d9e8520","source_path":"environment.md","text_hash":"6a26e1694d9e852038e5a472ed6b54cc023b4ace8ac10d745cad426d5dc057f3","text":" details.","translated":" 详情。","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T11:47:11Z"} @@ -939,7 +911,6 @@ {"cache_key":"b1a0214973416cbfb4dcac01605c51911f412a6b7d862a6b8aed7db6364bb93a","segment_id":"start/wizard.md:1a0f5fc7ca6e8a74","source_path":"start/wizard.md","text_hash":"1a0f5fc7ca6e8a74bc099d9c397a23564b55eca50c3b2e33c472acb7032a6f3b","text":" (if Minimax chosen)","translated":" （如果选择了 Minimax）","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T13:48:35Z"} {"cache_key":"b1babe6ce88663854adf02aa4a23f21c9a98e036c72bf36dbe4b518d5d025d8b","segment_id":"environment.md:8d076464a84995bc","source_path":"environment.md","text_hash":"8d076464a84995bc095e934b0aa1e4419372f27cd71d033571e4dbba201ee5d8","text":"You can reference env vars directly in config string values using ","translated":"您可以使用以下方式在配置字符串值中直接引用 环境变量 ","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T12:41:25Z"} {"cache_key":"b1bfed2a2039ffc6f83d8201645caf18d6b942a8e5efbe2a28ca24978f750aa7","segment_id":"index.md:a97c0f391117ef55","source_path":"index.md","text_hash":"a97c0f391117ef554586ed43255ab3ff0e15adcfc1829c62b6d359672c0bec93","text":" — Mention-based by default; owner can toggle ","translated":" — 默认基于提及；所有者可切换 ","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T13:02:09Z"} -{"cache_key":"b1d6847512a77312c1152a3f04694cdfc058f6d51d29f421a97d1f7799705076","segment_id":"help/index.md:d5d5bf0c0c86cfaa","source_path":"help/index.md","text_hash":"d5d5bf0c0c86cfaa612b370c3c796bb03e31b285fc928b5a690bfd156d177e88","text":"If you want a quick “get unstuck” flow, start","translated":"如果你想要一个快速的\"摆脱困境\"流程，请从这里开始","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T11:44:31Z"} {"cache_key":"b1e93b43d06bcf0651c4bee0920f356e1f38bceca29db1936d449b4be99e77d2","segment_id":"index.md:8f6fb4eb7f42c0e2","source_path":"index.md","text_hash":"8f6fb4eb7f42c0e245e29e63f5b82cc3ba19852681d1ed9aed291f59cf75ec0e","text":"Security","translated":"安全","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T12:53:56Z"} {"cache_key":"b212246fea49637bc0db899bd39dff2b1762ecf0d8cac3ec6160a8cd4c4da860","segment_id":"start/wizard.md:1f01936efef6e09c","source_path":"start/wizard.md","text_hash":"1f01936efef6e09cd29c9b1a9b6a64c1fcdb35682c9cf25db02dfde331f83fa7","text":" if present or prompts for a key, then saves it to ","translated":" （如果存在）或提示输入密钥，然后保存到 ","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T13:42:29Z"} {"cache_key":"b240cb7927de51aca09fb318798ffd79fe597965722be259f799a2002cbe0f43","segment_id":"start/getting-started.md:4ea5ee68fea05586","source_path":"start/getting-started.md","text_hash":"4ea5ee68fea05586106890ded5733820bb77d919cda27bc4b8139b7cd33b8889","text":" gateway","translated":" Gateway","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T13:36:02Z"} @@ -1031,7 +1002,6 @@ {"cache_key":"c2802148a29fff6480dd7c4126df1d7787f83156807ce1f6e0abb05d2e0a7863","segment_id":"index.md:6e0f6eca4ff17d33","source_path":"index.md","text_hash":"6e0f6eca4ff17d3377c1c3e8e1f73457553ad3b9cfcd5e4f2b94cfb1028b6234","text":"iOS app","translated":"iOS 应用","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T12:53:36Z"} {"cache_key":"c2acf62bea34b4557cbab8b7ceadd55c5cf37516c124b93afc1b8e9f08d62ab0","segment_id":"index.md:39bbb719fa2b9d22","source_path":"index.md","text_hash":"39bbb719fa2b9d2251039cbf2cd072e1120a414278263e2f11d99af0236c4262","text":"Groups","translated":"群组","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T12:53:21Z"} {"cache_key":"c2e74d237df6614199282b8822741be509ff03e31b7319f3184bb2537860e8a9","segment_id":"index.md:bf084dc7b82e1e62","source_path":"index.md","text_hash":"bf084dc7b82e1e62c63727b13451d1eba2269860e27db290d2d5908d7ade0529","text":" — Pairs as a node and exposes Canvas + Chat + Camera","translated":" — 作为节点配对并提供 Canvas + 聊天 + 相机","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T13:02:43Z"} -{"cache_key":"c2e91312acca3baab311ea42b62c2fcea1bf5ec3fe9f444cc63f3e00c3b1da02","segment_id":"environment.md:7c3c58e5e1838eae","source_path":"environment.md","text_hash":"7c3c58e5e1838eaeec35be812eb7edad1525e370c3420121710cc1d5fb627c1b","text":"), applied only for missing expected keys.\n\nIf the config file is missing entirely, step 4 is skipped; shell import still runs if enabled.","translated":"），仅对缺失的预期密钥应用。\n\n如果配置文件完全不存在，则跳过第 4 步；如果已启用，shell 导入仍会运行。","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T12:16:42Z"} {"cache_key":"c335a0e455574c0e23a45c10a55511400b6168c38aa7d8e43521b1c8650e58f9","segment_id":"environment.md:frontmatter:read_when:1","source_path":"environment.md:frontmatter:read_when:1","text_hash":"a3a2d99a99de98220c8e0296d6f4e4b2a34024916bd2379d1b3b9179c8fae46f","text":"You are debugging missing API keys in the Gateway","translated":"您正在调试 Gateway 中缺失的 API 密钥","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T12:40:15Z"} {"cache_key":"c34f893f16dcd3b37a3752585df805b44212829550f3d82cb5f539fdb50a5a50","segment_id":"environment.md:87e89abb4c1c551f","source_path":"environment.md","text_hash":"87e89abb4c1c551fe08d355d097f18b8de78edca5f556997085681662fce8eed","text":"Config ","translated":"配置 ","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T12:25:46Z"} {"cache_key":"c359a69d5e0e9e6470f36436f1b27a946ef28ef1069e7b7d59e0ea3132f6003c","segment_id":"start/wizard.md:4cd440e57b28aba7","source_path":"start/wizard.md","text_hash":"4cd440e57b28aba7f789ba11d0bb5837f09937ba45bab9a80b9a6a980894250e","text":"Follow‑up reconfiguration:","translated":"后续重新配置：","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T13:39:15Z"} @@ -1085,7 +1055,6 @@ {"cache_key":"cc8f5dcfbe51a4638b375d367381be97b79d012b56b2c7eadd2e38d164cdd177","segment_id":"start/wizard.md:e18251a039a6b735","source_path":"start/wizard.md","text_hash":"e18251a039a6b7353675decc475898bfdb91d3bd9d37e83c8447d0359b8711c3","text":"Non-interactive flags: ","translated":"非交互标志： ","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T13:47:05Z"} {"cache_key":"cc906618700533ea8dd9d752b8e2ef28ffb8707654a557d7cef1b867cdd57f1a","segment_id":"index.md:ceee4f2088b9d5ba","source_path":"index.md","text_hash":"ceee4f2088b9d5ba7d417bac7395003acfbcef576fd4cc1dd3063972f038218a","text":"The name","translated":"名称","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T12:54:01Z"} {"cache_key":"cc93bf5458542a509cb8460472bf3269d769fe1cdee6201ab736c4b5460d64d5","segment_id":"start/wizard.md:4bba41aa0148ebb4","source_path":"start/wizard.md","text_hash":"4bba41aa0148ebb49b33763f1b38a983af7c0a4dd22fff07d3cf94fdcb96ecd3","text":"Linux (and Windows via WSL2): systemd user unit","translated":"Linux（以及通过 WSL2 的 Windows）：systemd 用户单元","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T13:45:17Z"} -{"cache_key":"ccd10d490dbeb4a1e0c3b7b4ccf7653af6ff78a7d498755c92bf4a6c24b2aacd","segment_id":"environment.md:a42cc4a7174c83a8","source_path":"environment.md","text_hash":"a42cc4a7174c83a853752b3e74cb001a234f3eca099688fdf0dd2540c60bb1e2","text":" expected keys:","translated":" 预期密钥：","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T13:12:51Z"} {"cache_key":"cd2d7cce6f1c10e008e8efe49ecf02b6ac401d686667986409f7e6796e9f1140","segment_id":"environment.md:45ca56d179d4788c","source_path":"environment.md","text_hash":"45ca56d179d4788c55ba9f7653b376d62e7faa738e92259e3d4f6f5c1b554f28","text":"Related","translated":"相关内容","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T12:22:44Z"} {"cache_key":"cd4cdcf85e185ce70df30cbda64fb2d77baa6a6c989e67cde3f80315c06b3839","segment_id":"index.md:45e6d69dbe995a36","source_path":"index.md","text_hash":"45e6d69dbe995a36f7bc20755eff4eb4d2afaaedbcac4668ab62540c57219f32","text":"macOS app","translated":"macOS 应用","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T12:53:33Z"} {"cache_key":"cd82c395857efd6e374fec3ad86de5dd8989415770d38a86d8a1980cd372b7f5","segment_id":"start/wizard.md:c4e77a12a2c0b664","source_path":"start/wizard.md","text_hash":"c4e77a12a2c0b664f398de857da71528f66ffb4a70e65769897dcc7147167b2c","text":" or use allowlists.","translated":" 批准，或使用允许名单。","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T13:45:05Z"} @@ -1098,7 +1067,6 @@ {"cache_key":"ce3c2713f373fff6ebab9c70141debe3262d0a7ff6214fd146fa277b67c1ab3e","segment_id":"start/wizard.md:bd8a6e0ff884f51d","source_path":"start/wizard.md","text_hash":"bd8a6e0ff884f51d6a4a9b70f4680033876871936c72cf8af5df4e4b2836c75c","text":"Wizard runs a model check and warns if the configured model is unknown or missing auth.","translated":"向导会运行模型检查，如果配置的模型未知或缺少认证则发出警告。","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T13:43:24Z"} {"cache_key":"ce618de323766f3aa222b534fb69a1502c03699a6b57e801e6f1a1b3c32d3431","segment_id":"index.md:9abe8e9025013e78","source_path":"index.md","text_hash":"9abe8e9025013e78a6bf2913f8c20ee43134ad001ce29ced89e2af9c07096d8f","text":"Media: images","translated":"媒体：图片","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T12:53:25Z"} {"cache_key":"ce62c5006939b21f7a2d236f9cdb545ce653778800504e85668fe99075067cbf","segment_id":"environment.md:6db0742daaf9f191","source_path":"environment.md","text_hash":"6db0742daaf9f191ab7816d2c9d317b1ea1693453a8c63b95af8b01477e0f5bb","text":" runs your login shell and imports only ","translated":" 运行你的登录 shell，并仅导入 ","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T13:12:47Z"} -{"cache_key":"cebc7667fbb15ccecd6359fe5ec38ae1ad00df26f18e56e7debd760a47d30a94","segment_id":"start/getting-started.md:2fa27cf15c3773de","source_path":"start/getting-started.md","text_hash":"2fa27cf15c3773deb54ae880d0f3250d86ef8c316abe07373f5f6a16df7afbed","text":" is also supported.","translated":" 也受支持。","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T13:36:08Z"} {"cache_key":"cf001b0403d7ae959797460c96aa4da24818c662362595f2da0be349caeb6a09","segment_id":"index.md:cda454f61dfcac70","source_path":"index.md","text_hash":"cda454f61dfcac7007a9edc538f9f58cf38caa0652e253975979308162bccc53","text":"Gateway configuration","translated":"Gateway 配置","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T13:00:31Z"} {"cache_key":"cf9fc66b44905a0c47ca04f98d6e6507821789844f1e97ca2026f7df6e5b1451","segment_id":"environment.md:f7e239a42b7cd986","source_path":"environment.md","text_hash":"f7e239a42b7cd986a1558fed234e975ed2e96e9d37cf0a93f381778c461c89dd","text":"OpenClaw pulls environment variables from multiple sources. The rule is ","translated":"OpenClaw 从多个来源拉取 环境变量。规则是 ","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T12:57:11Z"} {"cache_key":"cfc26997d872d590a2aba69f0aba6f704354d3aea9aa3bd433693ca7182cacdc","segment_id":"start/getting-started.md:1093115897879aa3","source_path":"start/getting-started.md","text_hash":"1093115897879aa3ad9511a1dc2850929cfb60ba45ec741605f69f5d20203472","text":"Runtime","translated":"运行时","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T13:36:17Z"} @@ -1110,7 +1078,6 @@ {"cache_key":"d0f76abf14b1216bff9974f7e507a3c2a43f331f1ebd805279843692ae78f662","segment_id":"index.md:5cf9ea2e20780551","source_path":"index.md","text_hash":"5cf9ea2e2078055129b38cfbc394142ca6ca41556bd6e31cbd527425647c1d1e","text":"One Gateway per host (recommended)","translated":"每台主机一个 Gateway（推荐）","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T12:48:30Z"} {"cache_key":"d12af03e20c20a4ebdcdbf4c32f52081339c0aa7bd1bb44b311875547bb39918","segment_id":"start/wizard.md:14a01a1b76ad6311","source_path":"start/wizard.md","text_hash":"14a01a1b76ad63111eb126c1d124a893abcb5cc90fe893825a9c96362112ab4f","text":" adds gateway health probes to status output (requires a reachable gateway).","translated":" 将 Gateway 健康探测添加到状态输出中（需要可达的 Gateway）。","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T13:45:41Z"} {"cache_key":"d1818c531bc4e1cca14e64f751cf8698cb0701a745fb3da03b37b4fd7129c18b","segment_id":"start/wizard.md:6d0323ac97e5a313","source_path":"start/wizard.md","text_hash":"6d0323ac97e5a3136bae41278bfd46f5985969ee57dea5f25d7faa78bb01c87e","text":" when model is unset or ","translated":" （当模型未设置或为 ","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T13:42:24Z"} -{"cache_key":"d181ecac73ffcad6ec7afe0e692144db4ea470fa5de3a2d218f4b8127ad7d588","segment_id":"environment.md:28e19c6e69c7a2aa","source_path":"environment.md","text_hash":"28e19c6e69c7a2aa071951dda3ff0a11ca178e3fb295dae8d6ed7dcc994434a4","text":" for full details.","translated":" 了解完整详情。","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T12:58:28Z"} {"cache_key":"d1a349d8c1859f2d1c00367b86704fa95d4168c8615ada60834a6890215d1f58","segment_id":"index.md:3c064c83b8d244fe","source_path":"index.md","text_hash":"3c064c83b8d244fef61e5fd8ce5f070b857a3578a71745e61eea02892788c020","text":" — Anthropic (Claude Pro/Max) + OpenAI (ChatGPT/Codex) via OAuth","translated":" —— 通过 OAuth 支持 Anthropic（Claude Pro/Max）+ OpenAI（ChatGPT/Codex）","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T12:50:28Z"} {"cache_key":"d1d30ee69fb8519a966ebbb5cb51d2be029399b2951ef296b23f96d3fea4bc3a","segment_id":"start/wizard.md:3fad3d2e2c01a9ea","source_path":"start/wizard.md","text_hash":"3fad3d2e2c01a9ea3a66cbcb1b05a0d5982e3665cf0e1ec6dee0e031e83137e1","text":"Reads the available skills and checks requirements.","translated":"读取可用技能并检查依赖条件。","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T13:45:43Z"} {"cache_key":"d234d82b06f65337a5ab45e775d0f0abda696d4e04e6115c6a042853b3b11ca4","segment_id":"index.md:084514e91f37c3ce","source_path":"index.md","text_hash":"084514e91f37c3ce85360e26c70b77fdc95f0d3551ce309db96fbcf956a53b01","text":"Dashboard (browser Control UI)","translated":"仪表板（浏览器控制界面）","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T12:48:04Z"} @@ -1151,7 +1118,6 @@ {"cache_key":"d8fe9f40df201863d43f4937a52bac7d14019fae82150f1191fe4bb66819d827","segment_id":"help/index.md:3c33340bd23b8db8","source_path":"help/index.md","text_hash":"3c33340bd23b8db89f18fe7d05a954738c0dd5ba9623cf6bdb7bb5d1a3729cfc","text":"FAQ (concepts)","translated":"常见问题（概念）","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T13:11:34Z"} {"cache_key":"d93001811d4774893fac9a800d8e9c14259b90fc5ed85a3e5e6d381bfb591846","segment_id":"index.md:32ebb1abcc1c601c","source_path":"index.md","text_hash":"32ebb1abcc1c601ceb9c4e3c4faba0caa5b85bb98c4f1e6612c40faa528a91c9","text":" (","translated":" （","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T13:28:10Z"} {"cache_key":"d952c24b47cb7a9f69823c976f2f5e103fdc731a8bd74cae1436d86f420022df","segment_id":"environment.md:frontmatter:read_when:1","source_path":"environment.md:frontmatter:read_when:1","text_hash":"a3a2d99a99de98220c8e0296d6f4e4b2a34024916bd2379d1b3b9179c8fae46f","text":"You are debugging missing API keys in the Gateway","translated":"你正在调试 Gateway 中缺失的 API 密钥","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T12:21:50Z"} -{"cache_key":"d963cbde28040dde98de9fd8684bb5552ff2ba0e13e2c9921a8e36d90d7237a4","segment_id":"index.md:58d30d963f28264b","source_path":"index.md","text_hash":"58d30d963f28264bd9ba0e2d4c07c2c43c0ac1c1609c25b3fccf475eebf41727","text":"Skills config","translated":"技能配置","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T13:32:15Z"} {"cache_key":"d972ebc19ef87492ca8c11159fd6342cced6b4e19743d79d81ae33fafe35bbd8","segment_id":"environment.md:f7e239a42b7cd986","source_path":"environment.md","text_hash":"f7e239a42b7cd986a1558fed234e975ed2e96e9d37cf0a93f381778c461c89dd","text":"OpenClaw pulls environment variables from multiple sources. The rule is ","translated":"OpenClaw 从多个来源获取环境变量。规则是 ","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T12:21:57Z"} {"cache_key":"d9923f60f9531ccaaefa870fa682febfe862bf9a38ced5baa99ea8637d7fc5ae","segment_id":"start/getting-started.md:63d3b285bad7d501","source_path":"start/getting-started.md","text_hash":"63d3b285bad7d5015cea4d6e62f972e83221dfce48c6919bd536c5e894a6607d","text":" set an API key (wizard can store it for service use). ","translated":" 设置 API 密钥（向导可以将其存储以供服务使用）。 ","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T13:36:32Z"} {"cache_key":"d9b22590788b6c0abf9a15102d23d2aeb6608cf4acc0339e69be4e52ae38af48","segment_id":"index.md:f9b8279bc46e847b","source_path":"index.md","text_hash":"f9b8279bc46e847bfcc47b8701fd5c5dc27baa304d5add8278a7f97925c3ec13","text":"Mattermost (plugin)","translated":"Mattermost（插件）","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T12:53:18Z"} @@ -1167,7 +1133,6 @@ {"cache_key":"dbec24d595565c4c294a91f556c491976ccdeb4f7976d9258e6420af47259608","segment_id":"help/index.md:24669ff48290c187","source_path":"help/index.md","text_hash":"24669ff48290c1875d8067bbd241e8a55444839747bffb8ab99f3a34ef248436","text":"Doctor","translated":"诊断","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T13:11:29Z"} {"cache_key":"dbeeb5b2ad003e4152107ceade1290b2001163df5f2fb93a792c8c9d94cec345","segment_id":"start/getting-started.md:922f3f28b57bdd14","source_path":"start/getting-started.md","text_hash":"922f3f28b57bdd146b8892adf494a28a0969d5eaf21333bfdb314db2eb6c8da8","text":"Installer options (install method, non-interactive, from GitHub): ","translated":"安装选项（安装方式、非交互式、从 GitHub 安装）： ","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T13:35:48Z"} {"cache_key":"dbf5bae2a9b91c346475334bdb1294ace20ee07ca1e471c488c5311579ef37ab","segment_id":"index.md:b0d125182029e6c5","source_path":"index.md","text_hash":"b0d125182029e6c500cbcc81011341df77de8fe24d9e80190c32be390c916ec2","text":"🤖 ","translated":"🤖 ","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T12:49:58Z"} -{"cache_key":"dc16a7d72c37b5b48ed3034555c195ab7432617c1a8182e92d98e23f1051f615","segment_id":"index.md:f14185309c5ab262","source_path":"index.md","text_hash":"f14185309c5ab26233fde49831f9fc27857a6e7ac200e91dc247ae3e3b74be27","text":"Companion apps:","translated":"伴侣应用：","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T12:53:30Z"} {"cache_key":"dc745b075f86ec95e5a22fbb2ba14c5a6f2c00911dfa570cbe2f5123627e887d","segment_id":"environment.md:f15f5f9f4ef4d668","source_path":"environment.md","text_hash":"f15f5f9f4ef4d6688876c894f8eba251ed1db6eaf2209084028d43c9e76a8ba1","text":" (aka ","translated":" （即 ","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T12:40:44Z"} {"cache_key":"dc8c80f84e5339af07824daa81e39f2801c9d6beb851b21e632b3eb6ddf79749","segment_id":"start/wizard.md:4b2a013a2a09958e","source_path":"start/wizard.md","text_hash":"4b2a013a2a09958e251e8998bdfa5fd89cc1c69abb1273fe2c1522cf54363cc6","text":"JVM builds require ","translated":"JVM 构建需要 ","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T13:48:09Z"} {"cache_key":"dcb357452715d4a3fee760c79dfdee6719f235e48d176456a053646ffae10f44","segment_id":"environment.md:d08a8493f686363a","source_path":"environment.md","text_hash":"d08a8493f686363a78b913d45ebfbd87a3768d1c77b70f23b1fdade3c066e481","text":"Shell env import","translated":"Shell 环境导入","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T12:58:04Z"} @@ -1217,7 +1182,6 @@ {"cache_key":"e5b4eab0ca38617f4b76c99dc5fa36151812c02576b33f954a56cf5f77703696","segment_id":"index.md:bf0e823c81b87c5d","source_path":"index.md","text_hash":"bf0e823c81b87c5de79676155debf20a29b52d6d7eb7e77deda73a56d0afbaaa","text":"🧠 ","translated":"🧠 ","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T13:30:08Z"} {"cache_key":"e5be378ff2d92da3de35b20680f90f5d1aa0a98ce205139d6fcaeac91ef06f65","segment_id":"index.md:9bcda844990ec646","source_path":"index.md","text_hash":"9bcda844990ec646b3b6ee63cbdf10f70b0403727dea3b5ab601ca55e3949db9","text":" for node WebViews; see ","translated":" 用于节点 WebView；参见 ","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T12:49:04Z"} {"cache_key":"e5d655052f08f79672770734c9717dc24a5a9359defba7095dc7a9e2cf9e801b","segment_id":"start/wizard.md:bba52d8bacabbacc","source_path":"start/wizard.md","text_hash":"bba52d8bacabbacc510a1902b4eb35435f691903eb2db22fd110d41eadedec8d","text":" exists, the wizard can reuse it.","translated":" 存在，向导可以复用它。","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T13:42:13Z"} -{"cache_key":"e5febac01358bd99e804e54a33e30d0d88ea12bcab990c3e29c66351fb5a598f","segment_id":"index.md:41dc1288a547d7d1","source_path":"index.md","text_hash":"41dc1288a547d7d155c2d7b831e8cff388e12ab9d77d4c24cd0757ed47e9e209","text":" — Block streaming + Telegram draft streaming details (","translated":" —— 块流式传输 + Telegram 草稿流式传输详情（","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T12:50:10Z"} {"cache_key":"e628a7773be8d41e10dc53dcb383a11096e0573ec6b470aa13d2a14adcefb8e7","segment_id":"start/wizard.md:e3ba8a2959965f9c","source_path":"start/wizard.md","text_hash":"e3ba8a2959965f9c8360537e304016b2f75d561bdb03655a42adb02ce75a0e3f","text":"Default workspaces follow ","translated":"默认工作区遵循 ","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T13:46:57Z"} {"cache_key":"e62ed5670f8283396dcc6a81182cda94667ff98973f153e4c86a04db364a4895","segment_id":"start/wizard.md:a8dbd136ed7c8e55","source_path":"start/wizard.md","text_hash":"a8dbd136ed7c8e55f9c0ae6e5acd2576d485f642d964a61f3693afc1c0c4ffdf","text":": uses ","translated":"：使用 ","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T13:41:50Z"} {"cache_key":"e66b34ec94f9a9c10b99b098ad8806551356222f1ac50f6fec7d719991faceee","segment_id":"start/wizard.md:c36d819e7bc6d2b7","source_path":"start/wizard.md","text_hash":"c36d819e7bc6d2b7da51394411c733db89c395987885ca6770167a3b9bc45c3c","text":"Use ","translated":"使用 ","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T13:46:45Z"} @@ -1225,7 +1189,6 @@ {"cache_key":"e6b4ca13a3b7e39f521b1aadbb4f54f37875d228cd918c6406bd6519d5c7b6c8","segment_id":"index.md:6638cf2301d3109d","source_path":"index.md","text_hash":"6638cf2301d3109da66a44ee3506fbd35b29773fa4ca33ff35eb838c21609e19","text":"Features (high level)","translated":"功能特性（概览）","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T13:29:26Z"} {"cache_key":"e6e2a9985237253e0478229a54f3693bc7b0472bc450d53a4122dc20dfe08b21","segment_id":"environment.md:6863067eb0a2c749","source_path":"environment.md","text_hash":"6863067eb0a2c7499425c6c189b2c88bac55ca754285a6ab1ef37b75b4cfad4d","text":"See ","translated":"参见 ","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T12:22:37Z"} {"cache_key":"e6e456289628d5a4b6cbbc0fbb263d656ba7d49427a2009ce3c5f608b8505ea0","segment_id":"index.md:f0d82ba647b4a33d","source_path":"index.md","text_hash":"f0d82ba647b4a33da3008927253f9bed21e380f54eab0608b1136de4cbff1286","text":"OpenClaw bridges WhatsApp (via WhatsApp Web / Baileys), Telegram (Bot API / grammY), Discord (Bot API / channels.discord.js), and iMessage (imsg CLI) to coding agents like ","translated":"OpenClaw 将 WhatsApp（通过 WhatsApp Web / Baileys）、Telegram（Bot API / grammY）、Discord（Bot API / channels.discord.js）和 iMessage（imsg CLI）桥接到编程 智能体，例如 ","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T12:58:56Z"} -{"cache_key":"e6ede2965d77195fa0296a69f8dc8beb3a2fee2b0264180126200d4adbaf4aa3","segment_id":"index.md:f14185309c5ab262","source_path":"index.md","text_hash":"f14185309c5ab26233fde49831f9fc27857a6e7ac200e91dc247ae3e3b74be27","text":"Companion apps:","translated":"伴侣应用：","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T13:32:51Z"} {"cache_key":"e723a0b2ab360a74b84f4ccd08fdc4cc1639b85d5178d45d8103a18069bd3d8d","segment_id":"start/getting-started.md:1b59a1d9fa6d392f","source_path":"start/getting-started.md","text_hash":"1b59a1d9fa6d392f1f68642200583ed0f7b372af2fbc7c01d5f7f00463e229de","text":" also bundles A2UI assets; if you need to run just that step, use ","translated":" 也会打包 A2UI 资源；如果您只需要运行该步骤，请使用 ","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T13:37:51Z"} {"cache_key":"e7279b78eeb5dccdf1897af612ce9f34bbae6f6ad7d8a7fed40a48f2f59c2367","segment_id":"environment.md:frontmatter:summary","source_path":"environment.md:frontmatter:summary","text_hash":"78351223e7068721146d2de022fdf440c2866b2ee02fbbb50bf64369b999820b","text":"Where OpenClaw loads environment variables and the precedence order","translated":"OpenClaw 加载环境变量的位置及优先级顺序","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T12:25:05Z"} {"cache_key":"e73887cca1549bd1acf945a50dfbd054a3ec1c87741be5a0a4381a4840ce13e5","segment_id":"index.md:1df4f2299f0d9cc4","source_path":"index.md","text_hash":"1df4f2299f0d9cc466fa05abeb2831e76e9f89583228174ffcd9af415fd869fe","text":"Send a test message (requires a running Gateway):","translated":"发送测试消息（需要运行中的 Gateway）：","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T13:03:17Z"} @@ -1235,7 +1198,6 @@ {"cache_key":"e7bc8ffa042426610faa9c40c7191933bfda50deb769ef153580d4ab1c75d679","segment_id":"start/getting-started.md:cdb4ee2aea69cc6a","source_path":"start/getting-started.md","text_hash":"cdb4ee2aea69cc6a83331bbe96dc2caa9a299d21329efb0336fc02a82e1839a8","text":".","translated":"。","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T13:34:45Z"} {"cache_key":"e8160fc2a7763ac99c0933d4424a99f211b661b0d7649bb1d33f908c3ff5e0d2","segment_id":"start/getting-started.md:75e23f5184b23835","source_path":"start/getting-started.md","text_hash":"75e23f5184b23835efb6fdc64309312d3c9212d10566350b1a08ff7838c79d03","text":"2) Run the onboarding wizard (and install the service)","translated":"2）运行上手引导向导（并安装服务）","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T13:35:55Z"} {"cache_key":"e81fa8ea81e681a305d677a823722958c2fdf42c3afbf4149a2d5cdfc4c6e1df","segment_id":"index.md:4eb58187170dc141","source_path":"index.md","text_hash":"4eb58187170dc14198eacb534c8577bef076349c26f2479e1f6a2e31df8eb948","text":" — An AI, probably high on tokens","translated":" — 一个可能被令牌冲昏头脑的 AI","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T13:06:53Z"} -{"cache_key":"e83550368cc1a10f9407b5e8da39dc639896bb6669eca7e49f6107ff3a3c306c","segment_id":"environment.md:e4255aa4e8f9e525","source_path":"environment.md","text_hash":"e4255aa4e8f9e52571c9bc93336d0774bcd7f017b7b5297fb33b8e1986166f92","text":"), applied only for missing expected keys.","translated":"），仅对缺失的预期密钥应用。","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T12:41:05Z"} {"cache_key":"e87435d09fd52a520aeae4097eb83a149aeb498192ccfbdd63da8db57571de09","segment_id":"index.md:d08cec54f66c140c","source_path":"index.md","text_hash":"d08cec54f66c140c655a1631f6d629927c7c38b9c8bfa91c875df9bd3ad3c559","text":"OpenClaw assistant setup","translated":"OpenClaw 助手设置","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T13:32:12Z"} {"cache_key":"e8a313447619fd5d7895acf1c467e347d47a8c35861910facf5ff08f88a8905e","segment_id":"index.md:5928d14b4d45263d","source_path":"index.md","text_hash":"5928d14b4d45263d4964dfd301c84ed2674ca8b4b698c5efeb88fb86076d2bf9","text":"🎮 ","translated":"🎮 ","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T13:29:39Z"} {"cache_key":"e8bfa9777ff1ca6f2921ef47688f6ddb7d1a68c074dc27c7af195521940fb68f","segment_id":"help/index.md:frontmatter:summary","source_path":"help/index.md:frontmatter:summary","text_hash":"aece82a2d540ab1a9a21c7b038127cae6e9db2149491564bb1856b6f8999f205","text":"Help hub: common fixes, install sanity, and where to look when something breaks","translated":"帮助中心：常见修复方法、安装完整性检查，以及出现问题时的排查指南","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T12:39:25Z"} @@ -1257,11 +1219,9 @@ {"cache_key":"eca7489e62538a4b68a7d49f3a67df1c6bad8affc75d6411f68ca1e81bef47b2","segment_id":"environment.md:f6b2ffe1d0d5f521","source_path":"environment.md","text_hash":"f6b2ffe1d0d5f521b76cabc67d6e96da2b1170eef8086d530558e9906a7f092d","text":"Models overview","translated":"模型概览","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T13:13:17Z"} {"cache_key":"ecb4df64e132ff6212066948863adabaa06122c77d8971d5c924dc2e744df845","segment_id":"index.md:98a670e2fb754896","source_path":"index.md","text_hash":"98a670e2fb7548964e8b78b90fef47f679580423427bfd15e5869aca9681d0dd","text":"\"We're all just playing with our own prompts.\"","translated":"\"我们都只是在玩弄自己的提示词。\"","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T13:05:43Z"} {"cache_key":"ecd894720faa37450014e0fe1630be8382cf6ec23cbb9bfe76bc4125495d8fa5","segment_id":"index.md:9adcfa4aa10a4e8b","source_path":"index.md","text_hash":"9adcfa4aa10a4e8b991a72ccc45261cd64f296aed5b257e4caf9c87aff1290a0","text":" — Send and receive images, audio, documents","translated":" — 收发图片、音频、文档","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T13:30:38Z"} -{"cache_key":"ed00b197a3002ae69c3929cf870943136f802bf17b2850a71b6091111b76527d","segment_id":"environment.md:28e19c6e69c7a2aa","source_path":"environment.md","text_hash":"28e19c6e69c7a2aa071951dda3ff0a11ca178e3fb295dae8d6ed7dcc994434a4","text":" for full details.","translated":" 了解完整详情。","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T12:26:33Z"} {"cache_key":"ed10c233aa195883b17061f166f647efac5a27535a85ce4d16fc90d40e138882","segment_id":"help/index.md:8cd501e1124c3047","source_path":"help/index.md","text_hash":"8cd501e1124c30473473c06e536a2d145e2a14a6d7dc1b99028ce818e14442e2","text":"Repairs:","translated":"修复：","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T12:39:56Z"} {"cache_key":"ed15427258ffbf85620a0c9c0c42deb7f37be17b7abeff5993a34962964f0e96","segment_id":"index.md:a194ca16424ddd17","source_path":"index.md","text_hash":"a194ca16424ddd17dacc45f1cbd7d0e41376d8955a7b6d02bc38c295cedd04e4","text":"RPC adapters","translated":"RPC 适配器","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T13:32:19Z"} {"cache_key":"ed24753e60b54d629cfd978be87185f4772676322534432302319caf28452d29","segment_id":"index.md:ab201ddd7ab330d0","source_path":"index.md","text_hash":"ab201ddd7ab330d04be364c0ac14ce68c52073a0ee8d164a98c3034e91ce1848","text":" from the repo.","translated":" （在仓库目录中执行）。","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T13:31:21Z"} -{"cache_key":"ed366700bbcca6548c3fb1f7dae544b9a9cb0c56d6b36ca8e26c4880bc4e5667","segment_id":"environment.md:28e19c6e69c7a2aa","source_path":"environment.md","text_hash":"28e19c6e69c7a2aa071951dda3ff0a11ca178e3fb295dae8d6ed7dcc994434a4","text":" for full details.","translated":" 了解完整详情。","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T12:17:08Z"} {"cache_key":"ed37a2b1a8c3351a6c04bee81df6f507f306be344485e69eb87b3b2451aad89f","segment_id":"help/index.md:d3ef01b4a9c99103","source_path":"help/index.md","text_hash":"d3ef01b4a9c9910364c9b26b2499c8787a0461d2d24ab80376fff736a288b34c","text":"Logging","translated":"日志记录","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T12:24:47Z"} {"cache_key":"ee3f1647acf674397ba7f7e1aee0f9972b9830f978b622695d8ab5360de5a496","segment_id":"index.md:255ce77b7a6a015f","source_path":"index.md","text_hash":"255ce77b7a6a015f8595868a524b67c134e8fb405f4584fdac020e57f4ccd5f6","text":"Loopback-first","translated":"回环优先","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T13:00:01Z"} {"cache_key":"ee582fba5363de60fb2c00f9238f2ac9ad6dc7615694d8d23d24d88bf7ec13e1","segment_id":"environment.md:582967534d0f909d","source_path":"environment.md","text_hash":"582967534d0f909d196b97f9e6921342777aea87b46fa52df165389db1fb8ccf","text":" in ","translated":" 在 ","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T12:16:29Z"} @@ -1291,7 +1251,6 @@ {"cache_key":"f2a0941718593a4be66a7a033a4117a7b3a502ef64b25fd7d6d3475c77dd5a1a","segment_id":"environment.md:87e89abb4c1c551f","source_path":"environment.md","text_hash":"87e89abb4c1c551fe08d355d097f18b8de78edca5f556997085681662fce8eed","text":"Config ","translated":"配置 ","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T12:16:24Z"} {"cache_key":"f2a0c70d8b9f94722b586320f11c58339d30dd1fe8ff7250a962bb2db84d5ab4","segment_id":"environment.md:ffa63583dfa6706b","source_path":"environment.md","text_hash":"ffa63583dfa6706b87d284b86b0d693a161e4840aad2c5cf6b5d27c3b9621f7d","text":"missing","translated":"缺失的","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T12:58:09Z"} {"cache_key":"f2c14989f888bbff9c7330f2d5b3892af3b900910840435595031590dc8248e3","segment_id":"environment.md:frontmatter:read_when:0","source_path":"environment.md:frontmatter:read_when:0","text_hash":"90fc0487bff88009979cff1061c1a882df8c3b1baa9c43538331d9d5dab15479","text":"You need to know which env vars are loaded, and in what order","translated":"你需要了解加载了哪些环境变量，以及它们的加载顺序","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T12:15:47Z"} -{"cache_key":"f2e6682f149332f775039f6c872837c04dbab51ea935ed4fe0085aa2a75cabe6","segment_id":"environment.md:a42cc4a7174c83a8","source_path":"environment.md","text_hash":"a42cc4a7174c83a853752b3e74cb001a234f3eca099688fdf0dd2540c60bb1e2","text":" expected keys:","translated":" 预期密钥：","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T12:41:18Z"} {"cache_key":"f34789e2cb492196e8c057294dd98c5f9d4b8054d548a7b883a47f113efa1277","segment_id":"index.md:31365ab9453d6a1e","source_path":"index.md","text_hash":"31365ab9453d6a1ec03731622803d3b44f345b6afad08040d7f3e97290c77913","text":"do nothing","translated":"不做任何操作","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T12:51:55Z"} {"cache_key":"f36f13a67a73f6768bfbf346d552067475ef4f8137e13edfd4f636e1b7ef2ef8","segment_id":"start/getting-started.md:649cfa2f76a80b42","source_path":"start/getting-started.md","text_hash":"649cfa2f76a80b42e1821c89edd348794689409dcdf619dcd10624fb577c676b","text":"not recommended","translated":"不推荐","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T13:36:21Z"} {"cache_key":"f3701b1ce8ac7f8931cafd209250aa5ae388ecfdb0154dbbb21c03fd72ce5d08","segment_id":"help/index.md:729bc562eec2658b","source_path":"help/index.md","text_hash":"729bc562eec2658bd11ffdd522fe5277177dc73e86eaca7baac0b472a4d8f8b2","text":"If you’re looking for conceptual questions (not “something broke”):","translated":"如果你在寻找概念性问题（不是\"某个东西坏了\"）：","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T12:11:29Z"} @@ -1340,7 +1299,6 @@ {"cache_key":"fab1c40ef11182f7118f5528b5ba6ed5b5c169c37b302382107e3fbab3d200c1","segment_id":"index.md:3d8fed7c358b2ccf","source_path":"index.md","text_hash":"3d8fed7c358b2ccf225ee16857a0bb9b950fd414319749e0f6fff58c99fa5f22","text":"Subscription auth","translated":"订阅认证","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T12:50:25Z"} {"cache_key":"fae191ae8b8380df30a34afd63fc9ba9125258cee9f76e625da9a9c41a858973","segment_id":"start/wizard.md:158ac20b77d1dc12","source_path":"start/wizard.md","text_hash":"158ac20b77d1dc1223a47723e75f03b49fe61d0a6d69de4c3bba9fdd4c123c04","text":" only configures the local client to connect to a Gateway elsewhere.\nIt does ","translated":" 仅配置本地客户端以连接到其他位置的 Gateway。它 ","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T13:40:36Z"} {"cache_key":"faf6394b29b7de4f1af4a5c01405a2c33d4a1f8f58691915d75eedd3572b1d49","segment_id":"index.md:a7a19d4f14d001a5","source_path":"index.md","text_hash":"a7a19d4f14d001a56c27f68a13ff267859a407c7a9ab457c0945693c9067dd1c","text":"Configuration (optional)","translated":"配置（可选）","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T13:03:21Z"} -{"cache_key":"fb2cd6f6a8308f9b9ad6cb30dec3a08de2db675e77bc696aeb2ddb3084c9a6c4","segment_id":"start/wizard.md:58d30d963f28264b","source_path":"start/wizard.md","text_hash":"58d30d963f28264bd9ba0e2d4c07c2c43c0ac1c1609c25b3fccf475eebf41727","text":"Skills config","translated":"技能配置","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T13:49:20Z"} {"cache_key":"fc41f7c0ff1d82b20353a8a79f2da756675af014a48e1c36b3e693e2030aca4c","segment_id":"help/index.md:6201111b83a0cb5b","source_path":"help/index.md","text_hash":"6201111b83a0cb5b0922cb37cc442b9a40e24e3b1ce100a4bb204f4c63fd2ac0","text":" and ","translated":" 和 ","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T12:39:50Z"} {"cache_key":"fc43ec1fbbcff82d8d617e73687d1fa0c004b3fa731fdb6c9a1b0825ac2df2f5","segment_id":"start/wizard.md:d80c4025fe9728d6","source_path":"start/wizard.md","text_hash":"d80c4025fe9728d67b8330bdbb25a3062c7748ae6779d348b66687d5a796550f","text":"Gateway wizard RPC","translated":"Gateway 向导 RPC","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T13:47:41Z"} {"cache_key":"fc503e5044847f8c5412b75ba55ec912df5577a3bc37a7a975393684059d9c12","segment_id":"environment.md:61115f6649792387","source_path":"environment.md","text_hash":"61115f664979238731a390e84433a818965b7eaf1d38fa5b4b1507c33ef28c91","text":"Precedence (highest → lowest)","translated":"优先级（从高到低）","provider":"pi","model":"claude-opus-4-5","src_lang":"en","tgt_lang":"zh-CN","updated_at":"2026-02-01T12:16:00Z"} diff --git a/docs/zh-CN/automation/auth-monitoring.md b/docs/zh-CN/automation/auth-monitoring.md index b5a5da1cd1..7e093214da 100644 --- a/docs/zh-CN/automation/auth-monitoring.md +++ b/docs/zh-CN/automation/auth-monitoring.md @@ -5,19 +5,19 @@ read_when: summary: 监控模型提供商的 OAuth 过期状态 title: 认证监控 x-i18n: - generated_at: "2026-02-01T19:36:14Z" + generated_at: "2026-02-03T10:03:53Z" model: claude-opus-4-5 provider: pi source_hash: eef179af9545ed7ab881f3ccbef998869437fb50cdb4088de8da7223b614fa2b source_path: automation/auth-monitoring.md - workflow: 14 + workflow: 15 --- # 认证监控 -OpenClaw 通过 `openclaw models status` 暴露 OAuth 过期健康状态。可将其用于自动化和告警；脚本是针对手机工作流的可选补充。 +OpenClaw 通过 `openclaw models status` 提供 OAuth 过期健康状态。请使用该命令进行自动化和告警；脚本是为手机工作流程提供的可选附加功能。 -## 推荐方式：CLI 检查（跨平台通用） +## 推荐方式：CLI 检查（可移植） ```bash openclaw models status --check @@ -26,22 +26,22 @@ openclaw models status --check 退出码： - `0`：正常 -- `1`：凭证已过期或缺失 +- `1`：凭证过期或缺失 - `2`：即将过期（24 小时内） -适用于 cron/systemd，无需额外脚本。 +此方式适用于 cron/systemd，无需额外脚本。 -## 可选脚本（运维/手机工作流） +## 可选脚本（运维 / 手机工作流程） -这些脚本位于 `scripts/` 目录下，属于**可选项**。它们假定你可以通过 SSH 访问 Gateway网关主机，并针对 systemd + Termux 进行了调优。 +这些脚本位于 `scripts/` 目录下，属于**可选**内容。它们假定你可以通过 SSH 访问 Gateway 网关主机，并针对 systemd + Termux 进行了调优。 -- `scripts/claude-auth-status.sh` 现在使用 `openclaw models status --json` 作为数据源（如果 CLI 不可用则回退到直接读取文件），因此请确保定时器中 `openclaw` 在 `PATH` 中。 +- `scripts/claude-auth-status.sh` 现在使用 `openclaw models status --json` 作为数据来源（如果 CLI 不可用则回退到直接读取文件），因此请确保 `openclaw` 在定时器的 `PATH` 中。 - `scripts/auth-monitor.sh`：cron/systemd 定时器目标；发送告警（ntfy 或手机）。 - `scripts/systemd/openclaw-auth-monitor.{service,timer}`：systemd 用户定时器。 - `scripts/claude-auth-status.sh`：Claude Code + OpenClaw 认证检查器（完整/json/简洁模式）。 -- `scripts/mobile-reauth.sh`：通过 SSH 进行引导式重新认证流程。 -- `scripts/termux-quick-auth.sh`：一键小组件状态查看 + 打开认证 URL。 -- `scripts/termux-auth-widget.sh`：完整的引导式小组件流程。 -- `scripts/termux-sync-widget.sh`：将 Claude Code 凭证同步至 OpenClaw。 +- `scripts/mobile-reauth.sh`：通过 SSH 引导的重新认证流程。 +- `scripts/termux-quick-auth.sh`：一键小部件状态查看 + 打开认证 URL。 +- `scripts/termux-auth-widget.sh`：完整的引导式小部件流程。 +- `scripts/termux-sync-widget.sh`：同步 Claude Code 凭证 → OpenClaw。 如果你不需要手机自动化或 systemd 定时器，可以跳过这些脚本。 diff --git a/docs/zh-CN/automation/cron-jobs.md b/docs/zh-CN/automation/cron-jobs.md index 7e3fdaef3d..5c3b6471ad 100644 --- a/docs/zh-CN/automation/cron-jobs.md +++ b/docs/zh-CN/automation/cron-jobs.md @@ -1,39 +1,39 @@ --- read_when: - 调度后台任务或唤醒 - - 配置需要与心跳一起或并行运行的自动化 - - 在心跳和定时任务之间做选择 -summary: Gateway网关调度器的定时任务与唤醒 + - 配置需要与心跳一起运行或配合运行的自动化任务 + - 决定计划任务使用心跳还是定时任务 +summary: Gateway 网关调度器的定时任务与唤醒机制 title: 定时任务 x-i18n: - generated_at: "2026-02-01T19:37:32Z" + generated_at: "2026-02-03T07:44:30Z" model: claude-opus-4-5 provider: pi source_hash: d43268b0029f1b13d0825ddcc9c06a354987ea17ce02f3b5428a9c68bf936676 source_path: automation/cron-jobs.md - workflow: 14 + workflow: 15 --- -# 定时任务（Gateway网关调度器） +# 定时任务（Gateway 网关调度器） > **定时任务还是心跳？** 请参阅[定时任务与心跳对比](/automation/cron-vs-heartbeat)了解何时使用哪种方式。 -定时任务是 Gateway网关内置的调度器。它持久化任务、在合适的时间唤醒智能体，并可选择将输出发送回聊天。 +定时任务是 Gateway 网关内置的调度器。它持久化任务，在正确的时间唤醒智能体，并可选择将输出发送回聊天。 -如果你想要 _"每天早上运行"_ 或 _"20 分钟后提醒智能体"_，定时任务就是对应的机制。 +如果你需要"每天早上运行这个"或"20 分钟后触发智能体"，定时任务就是实现机制。 ## 简要概述 -- 定时任务运行在 **Gateway网关内部**（而非模型内部）。 +- 定时任务运行在 **Gateway 网关内部**（不是在模型内部）。 - 任务持久化存储在 `~/.openclaw/cron/` 下，因此重启不会丢失计划。 - 两种执行方式： - - **主会话**：入队一个系统事件，然后在下一次心跳时运行。 - - **隔离式**：在 `cron:` 中运行专用智能体轮次，可选择投递输出。 -- 唤醒是一等功能：任务可以请求"立即唤醒"或"下次心跳时"。 + - **主会话**：将系统事件加入队列，然后在下一次心跳时运行。 + - **隔离**：在 `cron:` 中运行专用的智能体回合，可选择发送输出。 +- 唤醒是一等功能：任务可以请求"立即唤醒"或"下次心跳"。 ## 快速开始（可操作） -创建一个一次性提醒，验证其存在，然后立即运行： +创建一个一次性提醒，验证它是否存在，然后立即运行： ```bash openclaw cron add \ @@ -49,7 +49,7 @@ openclaw cron run --force openclaw cron runs --id ``` -调度一个带投递功能的周期性隔离任务： +调度一个带消息发送的循环隔离任务： ```bash openclaw cron add \ @@ -63,99 +63,97 @@ openclaw cron add \ --to "channel:C1234567890" ``` -## 工具调用等价形式（Gateway网关定时任务工具） +## 工具调用等效项（Gateway 网关定时任务工具） -有关规范的 JSON 结构和示例，请参阅[工具调用的 JSON 模式](/automation/cron-jobs#json-schema-for-tool-calls)。 +有关规范的 JSON 结构和示例，请参阅[工具调用的 JSON schema](/automation/cron-jobs#json-schema-for-tool-calls)。 ## 定时任务的存储位置 -定时任务默认持久化存储在 Gateway网关主机的 `~/.openclaw/cron/jobs.json` 中。Gateway网关将文件加载到内存中，并在更改时写回，因此仅在 Gateway网关停止时手动编辑才是安全的。请优先使用 `openclaw cron add/edit` 或定时任务工具调用 API 进行更改。 +定时任务默认持久化存储在 Gateway 网关主机的 `~/.openclaw/cron/jobs.json`。Gateway 网关将文件加载到内存中，并在更改时写回，因此只有在 Gateway 网关停止时手动编辑才是安全的。建议使用 `openclaw cron add/edit` 或定时任务工具调用 API 进行更改。 ## 新手友好概述 将定时任务理解为：**何时**运行 + **做什么**。 -1. **选择调度计划** +1. **选择计划** - 一次性提醒 → `schedule.kind = "at"`（CLI：`--at`） - 重复任务 → `schedule.kind = "every"` 或 `schedule.kind = "cron"` - - 如果你的 ISO 时间戳省略了时区，将被视为 **UTC**。 + - 如果你的 ISO 时间戳省略了时区，它将被视为 **UTC**。 2. **选择运行位置** - - `sessionTarget: "main"` → 在下一次心跳时使用主会话上下文运行。 - - `sessionTarget: "isolated"` → 在 `cron:` 中运行专用智能体轮次。 + - `sessionTarget: "main"` → 在下一次心跳时使用主上下文运行。 + - `sessionTarget: "isolated"` → 在 `cron:` 中运行专用的智能体回合。 3. **选择负载** - 主会话 → `payload.kind = "systemEvent"` - 隔离会话 → `payload.kind = "agentTurn"` -可选：`deleteAfterRun: true` 会在一次性任务成功运行后将其从存储中删除。 +可选：`deleteAfterRun: true` 会在成功执行后从存储中删除一次性任务。 ## 概念 ### 任务 -定时任务是一条存储记录，包含： +定时任务是一个存储的记录，包含： -- 一个**调度计划**（何时运行）， +- 一个**计划**（何时运行）， - 一个**负载**（做什么）， -- 可选的**投递**（输出发送到哪里）。 -- 可选的**智能体绑定**（`agentId`）：在指定智能体下运行任务；如果缺失或未知，Gateway网关会回退到默认智能体。 +- 可选的**发送**（输出发送到哪里）。 +- 可选的**智能体绑定**（`agentId`）：在特定智能体下运行任务；如果缺失或未知，Gateway 网关会回退到默认智能体。 -任务通过稳定的 `jobId` 标识（用于 CLI/Gateway网关 API）。 -在智能体工具调用中，`jobId` 是规范字段；旧版 `id` 仍可兼容使用。 -任务可以通过 `deleteAfterRun: true` 在一次性任务成功运行后自动删除。 +任务通过稳定的 `jobId` 标识（供 CLI/Gateway 网关 API 使用）。在智能体工具调用中，`jobId` 是规范名称；为了兼容性也接受旧版的 `id`。任务可以通过 `deleteAfterRun: true` 选择在一次性成功运行后自动删除。 -### 调度计划 +### 计划 -定时任务支持三种调度类型： +定时任务支持三种计划类型： -- `at`：一次性时间戳（自纪元起的毫秒数）。Gateway网关接受 ISO 8601 格式并转换为 UTC。 +- `at`：一次性时间戳（自纪元以来的毫秒数）。Gateway 网关接受 ISO 8601 并转换为 UTC。 - `every`：固定间隔（毫秒）。 -- `cron`：5 字段 cron 表达式，可选 IANA 时区。 +- `cron`：5 字段 cron 表达式，带可选的 IANA 时区。 -Cron 表达式使用 `croner`。如果省略时区，将使用 Gateway网关主机的本地时区。 +Cron 表达式使用 `croner`。如果省略时区，则使用 Gateway 网关主机的本地时区。 -### 主会话与隔离式执行 +### 主会话与隔离执行 #### 主会话任务（系统事件） -主会话任务入队一个系统事件，并可选择唤醒心跳运行器。它们必须使用 `payload.kind = "systemEvent"`。 +主任务将系统事件加入队列并可选择唤醒心跳运行器。它们必须使用 `payload.kind = "systemEvent"`。 -- `wakeMode: "next-heartbeat"`（默认）：事件等待下一次计划心跳。 +- `wakeMode: "next-heartbeat"`（默认）：事件等待下一次计划的心跳。 - `wakeMode: "now"`：事件触发立即心跳运行。 当你需要正常的心跳提示 + 主会话上下文时，这是最佳选择。参见[心跳](/gateway/heartbeat)。 #### 隔离任务（专用定时会话） -隔离任务在会话 `cron:` 中运行专用智能体轮次。 +隔离任务在会话 `cron:` 中运行专用的智能体回合。 关键行为： -- 提示以 `[cron: <任务名称>]` 为前缀，便于追踪。 -- 每次运行都会启动一个**全新的会话 ID**（不继承之前的对话）。 +- 提示以 `[cron: ]` 为前缀以便追踪。 +- 每次运行启动一个**新的会话 id**（没有先前的对话延续）。 - 摘要会发布到主会话（前缀 `Cron`，可配置）。 - `wakeMode: "now"` 在发布摘要后触发立即心跳。 -- 如果 `payload.deliver: true`，输出会投递到渠道；否则保留在内部。 +- 如果 `payload.deliver: true`，输出会发送到渠道；否则保持内部。 -对于嘈杂、频繁或"后台杂务"类任务，使用隔离任务可以避免污染你的主聊天记录。 +对于嘈杂、频繁或不应该刷屏主聊天历史的"后台杂务"，使用隔离任务。 -### 负载结构（运行内容） +### 负载结构（运行什么） 支持两种负载类型： - `systemEvent`：仅限主会话，通过心跳提示路由。 -- `agentTurn`：仅限隔离会话，运行专用智能体轮次。 +- `agentTurn`：仅限隔离会话，运行专用的智能体回合。 -常用 `agentTurn` 字段： +常见的 `agentTurn` 字段： -- `message`：必填文本提示。 +- `message`：必需的文本提示。 - `model` / `thinking`：可选覆盖（见下文）。 -- `timeoutSeconds`：可选超时覆盖。 -- `deliver`：设为 `true` 以将输出发送到渠道目标。 +- `timeoutSeconds`：可选的超时覆盖。 +- `deliver`：`true` 则将输出发送到渠道目标。 - `channel`：`last` 或特定渠道。 -- `to`：渠道特定目标（电话/聊天/频道 ID）。 -- `bestEffortDeliver`：投递失败时避免任务失败。 +- `to`：特定于渠道的目标（电话/聊天/频道 id）。 +- `bestEffortDeliver`：发送失败时避免任务失败。 隔离选项（仅适用于 `session=isolated`）： @@ -163,60 +161,60 @@ Cron 表达式使用 `croner`。如果省略时区，将使用 Gateway网关主 - `postToMainMode`：`summary`（默认）或 `full`。 - `postToMainMaxChars`：当 `postToMainMode=full` 时的最大字符数（默认 8000）。 -### 模型和思维覆盖 +### 模型和思考覆盖 -隔离任务（`agentTurn`）可以覆盖模型和思维级别： +隔离任务（`agentTurn`）可以覆盖模型和思考级别： - `model`：提供商/模型字符串（例如 `anthropic/claude-sonnet-4-20250514`）或别名（例如 `opus`） -- `thinking`：思维级别（`off`、`minimal`、`low`、`medium`、`high`、`xhigh`；仅限 GPT-5.2 + Codex 模型） +- `thinking`：思考级别（`off`、`minimal`、`low`、`medium`、`high`、`xhigh`；仅限 GPT-5.2 + Codex 模型） -注意：你也可以在主会话任务上设置 `model`，但这会更改共享的主会话模型。我们建议仅对隔离任务使用模型覆盖，以避免意外的上下文切换。 +注意：你也可以在主会话任务上设置 `model`，但它会更改共享的主会话模型。我们建议仅对隔离任务使用模型覆盖，以避免意外的上下文切换。 -优先级解析顺序： +解析优先级： -1. 任务负载覆盖（最高优先级） +1. 任务负载覆盖（最高） 2. 钩子特定默认值（例如 `hooks.gmail.model`） 3. 智能体配置默认值 -### 投递（渠道 + 目标） +### 发送（渠道 + 目标） -隔离任务可以将输出投递到渠道。任务负载可以指定： +隔离任务可以将输出发送到渠道。任务负载可以指定： - `channel`：`whatsapp` / `telegram` / `discord` / `slack` / `mattermost`（插件）/ `signal` / `imessage` / `last` -- `to`：渠道特定的接收目标 +- `to`：特定于渠道的接收者目标 如果省略 `channel` 或 `to`，定时任务可以回退到主会话的"最后路由"（智能体最后回复的位置）。 -投递说明： +发送说明： -- 如果设置了 `to`，即使省略 `deliver`，定时任务也会自动投递智能体的最终输出。 -- 当你需要最后路由投递但不指定明确 `to` 时，使用 `deliver: true`。 -- 使用 `deliver: false` 即使存在 `to` 也保持输出为内部使用。 +- 如果设置了 `to`，即使省略了 `deliver`，定时任务也会自动发送智能体的最终输出。 +- 当你想要不带显式 `to` 的最后路由发送时，使用 `deliver: true`。 +- 使用 `deliver: false` 即使存在 `to` 也保持输出在内部。 目标格式提醒： -- Slack/Discord/Mattermost（插件）目标应使用明确前缀（例如 `channel:`、`user:`）以避免歧义。 -- Telegram 主题应使用 `:topic:` 格式（见下文）。 +- Slack/Discord/Mattermost（插件）目标应使用显式前缀（例如 `channel:`、`user:`）以避免歧义。 +- Telegram 话题应使用 `:topic:` 形式（见下文）。 -#### Telegram 投递目标（主题/论坛帖子） +#### Telegram 发送目标（话题/论坛帖子） -Telegram 通过 `message_thread_id` 支持论坛主题。对于定时任务投递，你可以将主题/帖子编码到 `to` 字段中： +Telegram 通过 `message_thread_id` 支持论坛话题。对于定时任务发送，你可以将话题/帖子编码到 `to` 字段中： -- `-1001234567890`（仅聊天 ID） -- `-1001234567890:topic:123`（推荐：明确的主题标记） +- `-1001234567890`（仅聊天 id） +- `-1001234567890:topic:123`（推荐：显式话题标记） - `-1001234567890:123`（简写：数字后缀） -带前缀的目标如 `telegram:...` / `telegram:group:...` 也可接受： +带前缀的目标如 `telegram:...` / `telegram:group:...` 也被接受： - `telegram:group:-1001234567890:topic:123` -## 工具调用的 JSON 模式 +## 工具调用的 JSON schema -直接调用 Gateway网关 `cron.*` 工具（智能体工具调用或 RPC）时使用这些结构。CLI 标志接受人类可读的时间格式如 `20m`，但工具调用对 `atMs` 和 `everyMs` 使用纪元毫秒数（`at` 时间接受 ISO 时间戳）。 +直接调用 Gateway 网关 `cron.*` 工具时（智能体工具调用或 RPC）使用这些结构。CLI 标志接受人类可读的时间格式如 `20m`，但工具调用对 `atMs` 和 `everyMs` 使用纪元毫秒（`at` 时间接受 ISO 时间戳）。 ### cron.add 参数 -一次性主会话任务（系统事件）： +一次性，主会话任务（系统事件）： ```json { @@ -229,7 +227,7 @@ Telegram 通过 `message_thread_id` 支持论坛主题。对于定时任务投 } ``` -带投递的周期性隔离任务： +循环，带发送的隔离任务： ```json { @@ -252,8 +250,8 @@ Telegram 通过 `message_thread_id` 支持论坛主题。对于定时任务投 说明： - `schedule.kind`：`at`（`atMs`）、`every`（`everyMs`）或 `cron`（`expr`，可选 `tz`）。 -- `atMs` 和 `everyMs` 为纪元毫秒数。 -- `sessionTarget` 必须为 `"main"` 或 `"isolated"`，且必须与 `payload.kind` 匹配。 +- `atMs` 和 `everyMs` 是纪元毫秒。 +- `sessionTarget` 必须是 `"main"` 或 `"isolated"` 并且必须与 `payload.kind` 匹配。 - 可选字段：`agentId`、`description`、`enabled`、`deleteAfterRun`、`isolation`。 - `wakeMode` 省略时默认为 `"next-heartbeat"`。 @@ -271,8 +269,8 @@ Telegram 通过 `message_thread_id` 支持论坛主题。对于定时任务投 说明： -- `jobId` 是规范字段；`id` 可兼容使用。 -- 在补丁中使用 `agentId: null` 可清除智能体绑定。 +- `jobId` 是规范名称；为了兼容性也接受 `id`。 +- 在补丁中使用 `agentId: null` 来清除智能体绑定。 ### cron.run 和 cron.remove 参数 @@ -284,9 +282,9 @@ Telegram 通过 `message_thread_id` 支持论坛主题。对于定时任务投 { "jobId": "job-123" } ``` -## 存储与历史 +## 存储和历史 -- 任务存储：`~/.openclaw/cron/jobs.json`（Gateway网关管理的 JSON）。 +- 任务存储：`~/.openclaw/cron/jobs.json`（Gateway 网关管理的 JSON）。 - 运行历史：`~/.openclaw/cron/runs/.jsonl`（JSONL，自动清理）。 - 覆盖存储路径：配置中的 `cron.store`。 @@ -332,7 +330,7 @@ openclaw cron add \ --wake now ``` -周期性隔离任务（投递到 WhatsApp）： +循环隔离任务（发送到 WhatsApp）： ```bash openclaw cron add \ @@ -346,7 +344,7 @@ openclaw cron add \ --to "+15551234567" ``` -周期性隔离任务（投递到 Telegram 主题）： +循环隔离任务（发送到 Telegram 话题）： ```bash openclaw cron add \ @@ -360,7 +358,7 @@ openclaw cron add \ --to "-1001234567890:topic:123" ``` -带模型和思维覆盖的隔离任务： +带模型和思考覆盖的隔离任务： ```bash openclaw cron add \ @@ -376,10 +374,10 @@ openclaw cron add \ --to "+15551234567" ``` -智能体选择（多智能体配置）： +智能体选择（多智能体设置）： ```bash -# 将任务绑定到智能体 "ops"（如果该智能体不存在则回退到默认智能体） +# 将任务绑定到智能体"ops"（如果该智能体不存在则回退到默认） openclaw cron add --name "Ops sweep" --cron "0 6 * * *" --session isolated --message "Check ops queue" --agent ops # 切换或清除现有任务的智能体 @@ -408,27 +406,27 @@ openclaw cron edit \ openclaw cron runs --id --limit 50 ``` -不创建任务直接发送系统事件： +不创建任务的立即系统事件： ```bash openclaw system event --mode now --text "Next heartbeat: check battery." ``` -## Gateway网关 API 接口 +## Gateway 网关 API 接口 - `cron.list`、`cron.status`、`cron.add`、`cron.update`、`cron.remove` - `cron.run`（强制或到期）、`cron.runs` - 如需不创建任务直接发送系统事件，请使用 [`openclaw system event`](/cli/system)。 + 对于不创建任务的立即系统事件，使用 [`openclaw system event`](/cli/system)。 ## 故障排除 -### "没有任何任务运行" +### "什么都不运行" -- 检查定时任务是否已启用：`cron.enabled` 和 `OPENCLAW_SKIP_CRON`。 -- 检查 Gateway网关是否持续运行（定时任务运行在 Gateway网关进程内部）。 -- 对于 `cron` 调度：确认时区（`--tz`）与主机时区的关系。 +- 检查定时任务是否启用：`cron.enabled` 和 `OPENCLAW_SKIP_CRON`。 +- 检查 Gateway 网关是否持续运行（定时任务在 Gateway 网关进程内运行）。 +- 对于 `cron` 计划：确认时区（`--tz`）与主机时区的关系。 -### Telegram 投递到了错误的位置 +### Telegram 发送到错误的位置 -- 对于论坛主题，使用 `-100…:topic:` 以确保明确无歧义。 -- 如果你在日志或存储的"最后路由"目标中看到 `telegram:...` 前缀，这是正常的；定时任务投递接受这些前缀并仍能正确解析主题 ID。 +- 对于论坛话题，使用 `-100…:topic:` 以确保明确无歧义。 +- 如果你在日志或存储的"最后路由"目标中看到 `telegram:...` 前缀，这是正常的；定时任务发送接受它们并仍然正确解析话题 ID。 diff --git a/docs/zh-CN/automation/gmail-pubsub.md b/docs/zh-CN/automation/gmail-pubsub.md index 0bfbc48b57..56ec04a02b 100644 --- a/docs/zh-CN/automation/gmail-pubsub.md +++ b/docs/zh-CN/automation/gmail-pubsub.md @@ -5,12 +5,12 @@ read_when: summary: 通过 gogcli 将 Gmail Pub/Sub 推送接入 OpenClaw webhooks title: Gmail PubSub x-i18n: - generated_at: "2026-02-01T19:38:47Z" + generated_at: "2026-02-03T07:43:25Z" model: claude-opus-4-5 provider: pi source_hash: dfb92133b69177e4e984b7d072f5dc28aa53a9e0cf984a018145ed811aa96195 source_path: automation/gmail-pubsub.md - workflow: 14 + workflow: 15 --- # Gmail Pub/Sub -> OpenClaw @@ -20,11 +20,11 @@ x-i18n: ## 前置条件 - 已安装并登录 `gcloud`（[安装指南](https://docs.cloud.google.com/sdk/docs/install-sdk)）。 -- 已安装 `gog`（gogcli）并已授权 Gmail 账号（[gogcli.sh](https://gogcli.sh/)）。 +- 已安装 `gog` (gogcli) 并为 Gmail 账户授权（[gogcli.sh](https://gogcli.sh/)）。 - 已启用 OpenClaw hooks（参见 [Webhooks](/automation/webhook)）。 -- 已登录 `tailscale`（[tailscale.com](https://tailscale.com/)）。支持的配置使用 Tailscale Funnel 作为公共 HTTPS 端点。 - 其他隧道服务也可以使用，但属于自行配置/不受支持，需要手动接线。 - 目前我们支持的是 Tailscale。 +- 已登录 `tailscale`（[tailscale.com](https://tailscale.com/)）。支持的设置使用 Tailscale Funnel 作为公共 HTTPS 端点。 + 其他隧道服务也可以使用，但需要自行配置/不受支持，需要手动接入。 + 目前，我们支持的是 Tailscale。 示例 hook 配置（启用 Gmail 预设映射）： @@ -39,7 +39,7 @@ x-i18n: } ``` -如需将 Gmail 摘要投递到聊天界面，可覆盖预设并设置带 `deliver` 以及可选的 `channel`/`to` 的映射： +要将 Gmail 摘要投递到聊天界面，请用设置了 `deliver` 以及可选的 `channel`/`to` 的映射覆盖预设： ```json5 { @@ -65,11 +65,11 @@ x-i18n: } ``` -如果你想要固定渠道，请设置 `channel` + `to`。否则 `channel: "last"` 会使用最后的投递路由（回退到 WhatsApp）。 +如果你想使用固定渠道，请设置 `channel` + `to`。否则 `channel: "last"` 会使用上次的投递路由（默认回退到 WhatsApp）。 -如需为 Gmail 运行强制使用更便宜的模型，在映射中设置 `model`（`provider/model` 或别名）。如果你设置了 `agents.defaults.models`，请将其包含在允许列表中。 +要为 Gmail 运行强制使用更便宜的模型，请在映射中设置 `model`（`provider/model` 或别名）。如果你强制启用了 `agents.defaults.models`，请将其包含在内。 -如需专门为 Gmail hooks 设置默认模型和思维级别，在配置中添加 `hooks.gmail.model` / `hooks.gmail.thinking`： +要专门为 Gmail hooks 设置默认模型和思考级别，请在配置中添加 `hooks.gmail.model` / `hooks.gmail.thinking`： ```json5 { @@ -82,42 +82,42 @@ x-i18n: } ``` -说明： +注意事项： -- 映射中每个 hook 的 `model`/`thinking` 仍会覆盖这些默认值。 +- 映射中的每个 hook 的 `model`/`thinking` 仍会覆盖这些默认值。 - 回退顺序：`hooks.gmail.model` → `agents.defaults.model.fallbacks` → 主模型（认证/速率限制/超时）。 - 如果设置了 `agents.defaults.models`，Gmail 模型必须在允许列表中。 -- Gmail hook 内容默认使用外部内容安全边界进行包装。 - 如需禁用（危险），请设置 `hooks.gmail.allowUnsafeExternalContent: true`。 +- Gmail hook 内容默认使用外部内容安全边界包装。 + 要禁用（危险），请设置 `hooks.gmail.allowUnsafeExternalContent: true`。 -如需进一步自定义负载处理，可添加 `hooks.mappings` 或在 `hooks.transformsDir` 下添加 JS/TS 转换模块（参见 [Webhooks](/automation/webhook)）。 +要进一步自定义负载处理，请添加 `hooks.mappings` 或在 `hooks.transformsDir` 下添加 JS/TS 转换模块（参见 [Webhooks](/automation/webhook)）。 ## 向导（推荐） -使用 OpenClaw 辅助工具一键完成所有配置（在 macOS 上通过 brew 安装依赖）： +使用 OpenClaw 助手将所有内容接入在一起（在 macOS 上通过 brew 安装依赖）： ```bash openclaw webhooks gmail setup \ --account openclaw@gmail.com ``` -默认配置： +默认设置： - 使用 Tailscale Funnel 作为公共推送端点。 - 为 `openclaw webhooks gmail run` 写入 `hooks.gmail` 配置。 - 启用 Gmail hook 预设（`hooks.presets: ["gmail"]`）。 -路径说明：当启用 `tailscale.mode` 时，OpenClaw 会自动将 `hooks.gmail.serve.path` 设置为 `/`，并将公共路径保持在 `hooks.gmail.tailscale.path`（默认 `/gmail-pubsub`），因为 Tailscale 在代理前会去除设置的路径前缀。 -如果你需要后端接收带前缀的路径，请将 `hooks.gmail.tailscale.target`（或 `--tailscale-target`）设置为完整 URL，例如 `http://127.0.0.1:8788/gmail-pubsub`，并匹配 `hooks.gmail.serve.path`。 +路径说明：当启用 `tailscale.mode` 时，OpenClaw 会自动将 `hooks.gmail.serve.path` 设置为 `/`，并将公共路径保持在 `hooks.gmail.tailscale.path`（默认 `/gmail-pubsub`），因为 Tailscale 在代理之前会剥离设置的路径前缀。 +如果你需要后端接收带前缀的路径，请将 `hooks.gmail.tailscale.target`（或 `--tailscale-target`）设置为完整 URL，如 `http://127.0.0.1:8788/gmail-pubsub`，并匹配 `hooks.gmail.serve.path`。 -需要自定义端点？使用 `--push-endpoint ` 或 `--tailscale off`。 +想要自定义端点？使用 `--push-endpoint ` 或 `--tailscale off`。 平台说明：在 macOS 上，向导通过 Homebrew 安装 `gcloud`、`gogcli` 和 `tailscale`；在 Linux 上请先手动安装它们。 -Gateway网关自动启动（推荐）： +Gateway 网关自动启动（推荐）： -- 当 `hooks.enabled=true` 且设置了 `hooks.gmail.account` 时，Gateway网关会在启动时运行 `gog gmail watch serve` 并自动续期 watch。 -- 设置 `OPENCLAW_SKIP_GMAIL_WATCHER=1` 可退出自动启动（如果你自行运行守护进程则很有用）。 +- 当 `hooks.enabled=true` 且设置了 `hooks.gmail.account` 时，Gateway 网关会在启动时运行 `gog gmail watch serve` 并自动续期 watch。 +- 设置 `OPENCLAW_SKIP_GMAIL_WATCHER=1` 可退出（如果你自己运行守护进程则很有用）。 - 不要同时运行手动守护进程，否则会遇到 `listen tcp 127.0.0.1:8788: bind: address already in use`。 手动守护进程（启动 `gog gmail watch serve` + 自动续期）： @@ -135,7 +135,7 @@ gcloud auth login gcloud config set project ``` -注意：Gmail watch 要求 Pub/Sub 主题位于与 OAuth 客户端相同的项目中。 +注意：Gmail watch 要求 Pub/Sub 主题与 OAuth 客户端位于同一项目中。 2. 启用 API： @@ -149,7 +149,7 @@ gcloud services enable gmail.googleapis.com pubsub.googleapis.com gcloud pubsub topics create gog-gmail-watch ``` -4. 允许 Gmail 推送发布： +4. 允许 Gmail push 发布： ```bash gcloud pubsub topics add-iam-policy-binding gog-gmail-watch \ @@ -168,9 +168,9 @@ gog gmail watch start \ 保存输出中的 `history_id`（用于调试）。 -## 运行推送处理器 +## 运行推送处理程序 -本地示例（共享令牌认证）： +本地示例（共享 token 认证）： ```bash gog gmail watch serve \ @@ -185,17 +185,17 @@ gog gmail watch serve \ --max-bytes 20000 ``` -说明： +注意事项： - `--token` 保护推送端点（`x-gog-token` 或 `?token=`）。 -- `--hook-url` 指向 OpenClaw `/hooks/gmail`（已映射；隔离运行 + 摘要发送到主会话）。 +- `--hook-url` 指向 OpenClaw `/hooks/gmail`（已映射；隔离运行 + 摘要发送到主线程）。 - `--include-body` 和 `--max-bytes` 控制发送到 OpenClaw 的正文片段。 推荐：`openclaw webhooks gmail run` 封装了相同的流程并自动续期 watch。 -## 暴露处理器（高级，不受支持） +## 暴露处理程序（高级，不受支持） -如果你需要非 Tailscale 隧道，请手动接线并在推送订阅中使用公共 URL（不受支持，无保护措施）： +如果你需要非 Tailscale 隧道，请手动接入并在推送订阅中使用公共 URL（不受支持，无保护措施）： ```bash cloudflared tunnel --url http://127.0.0.1:8788 --no-autoupdate @@ -217,7 +217,7 @@ gog gmail watch serve --verify-oidc --oidc-email ## 测试 -向被监控的收件箱发送一封邮件： +向被监视的收件箱发送一条消息： ```bash gog gmail send \ @@ -227,7 +227,7 @@ gog gmail send \ --body "ping" ``` -检查 watch 状态和历史： +检查 watch 状态和历史记录： ```bash gog gmail watch status --account openclaw@gmail.com @@ -237,8 +237,8 @@ gog gmail history --account openclaw@gmail.com --since ## 故障排除 - `Invalid topicName`：项目不匹配（主题不在 OAuth 客户端项目中）。 -- `User not authorized`：主题缺少 `roles/pubsub.publisher` 权限。 -- 空消息：Gmail 推送仅提供 `historyId`；通过 `gog gmail history` 获取详情。 +- `User not authorized`：主题缺少 `roles/pubsub.publisher`。 +- 空消息：Gmail push 仅提供 `historyId`；通过 `gog gmail history` 获取。 ## 清理 diff --git a/docs/zh-CN/automation/poll.md b/docs/zh-CN/automation/poll.md index f9fee64109..2b26891b13 100644 --- a/docs/zh-CN/automation/poll.md +++ b/docs/zh-CN/automation/poll.md @@ -1,16 +1,16 @@ --- read_when: - 添加或修改投票支持 - - 调试从 CLI 或 Gateway网关发送的投票 -summary: 通过 Gateway网关 + CLI 发送投票 + - 调试从 CLI 或 Gateway 网关发送的投票 +summary: 通过 Gateway 网关 + CLI 发送投票 title: 投票 x-i18n: - generated_at: "2026-02-01T19:38:57Z" + generated_at: "2026-02-03T07:43:12Z" model: claude-opus-4-5 provider: pi source_hash: 760339865d27ec40def7996cac1d294d58ab580748ad6b32cc34d285d0314eaf source_path: automation/poll.md - workflow: 14 + workflow: 15 --- # 投票 @@ -19,7 +19,7 @@ x-i18n: - WhatsApp（Web 渠道） - Discord -- Microsoft Teams（Adaptive Cards） +- MS Teams（Adaptive Cards） ## CLI @@ -47,29 +47,30 @@ openclaw message poll --channel msteams --target conversation:19:abc@thread.tacv - `--poll-multi`：允许选择多个选项 - `--poll-duration-hours`：仅限 Discord（省略时默认为 24） -## Gateway网关 RPC +## Gateway 网关 RPC 方法：`poll` 参数： -- `to`（字符串，必填） -- `question`（字符串，必填） -- `options`（字符串数组，必填） +- `to`（字符串，必需） +- `question`（字符串，必需） +- `options`（字符串数组，必需） - `maxSelections`（数字，可选） - `durationHours`（数字，可选） - `channel`（字符串，可选，默认：`whatsapp`） -- `idempotencyKey`（字符串，必填） +- `idempotencyKey`（字符串，必需） ## 渠道差异 - WhatsApp：2-12 个选项，`maxSelections` 必须在选项数量范围内，忽略 `durationHours`。 -- Discord：2-10 个选项，`durationHours` 限制在 1-768 小时（默认 24）。`maxSelections > 1` 启用多选；Discord 不支持严格的选择数量限制。 -- Microsoft Teams：Adaptive Card 投票（由 OpenClaw 管理）。没有原生投票 API；`durationHours` 被忽略。 +- Discord：2-10 个选项，`durationHours` 限制在 1-768 小时之间（默认 24）。`maxSelections > 1` 启用多选；Discord 不支持严格的选择数量限制。 +- MS Teams：Adaptive Card 投票（由 OpenClaw 管理）。无原生投票 API；`durationHours` 被忽略。 ## 智能体工具（Message） 使用 `message` 工具的 `poll` 操作（`to`、`pollQuestion`、`pollOption`，可选 `pollMulti`、`pollDurationHours`、`channel`）。 -注意：Discord 没有"精确选择 N 个"模式；`pollMulti` 映射为多选。 -Teams 投票以 Adaptive Cards 形式渲染，需要 Gateway网关保持在线以在 `~/.openclaw/msteams-polls.json` 中记录投票结果。 +注意：Discord 没有"恰好选择 N 个"模式；`pollMulti` 映射为多选。 +Teams 投票以 Adaptive Cards 形式渲染，需要 Gateway 网关保持在线 +以将投票记录到 `~/.openclaw/msteams-polls.json`。 diff --git a/docs/zh-CN/automation/webhook.md b/docs/zh-CN/automation/webhook.md index c2ad6fd897..5400b0a35e 100644 --- a/docs/zh-CN/automation/webhook.md +++ b/docs/zh-CN/automation/webhook.md @@ -1,21 +1,21 @@ --- read_when: - - 添加或修改 webhook 端点 + - 添加或更改 webhook 端点 - 将外部系统接入 OpenClaw -summary: 用于唤醒和隔离式智能体运行的 Webhook 入口 +summary: 用于唤醒和隔离智能体运行的 Webhook 入口 title: Webhooks x-i18n: - generated_at: "2026-02-01T19:39:20Z" + generated_at: "2026-02-03T07:43:23Z" model: claude-opus-4-5 provider: pi source_hash: f26b88864567be82366b1f66a4772ef2813c7846110c62fce6caf7313568265e source_path: automation/webhook.md - workflow: 14 + workflow: 15 --- # Webhooks -Gateway网关可以暴露一个小型 HTTP webhook 端点用于外部触发。 +Gateway 网关可以暴露一个小型 HTTP webhook 端点用于外部触发。 ## 启用 @@ -29,7 +29,7 @@ Gateway网关可以暴露一个小型 HTTP webhook 端点用于外部触发。 } ``` -说明： +注意事项： - 当 `hooks.enabled=true` 时，`hooks.token` 为必填项。 - `hooks.path` 默认为 `/hooks`。 @@ -40,7 +40,7 @@ Gateway网关可以暴露一个小型 HTTP webhook 端点用于外部触发。 - `Authorization: Bearer `（推荐） - `x-openclaw-token: ` -- `?token=`（已弃用；会记录警告，将在未来的主要版本中移除） +- `?token=`（已弃用；会记录警告日志，将在未来的主要版本中移除） ## 端点 @@ -52,13 +52,13 @@ Gateway网关可以暴露一个小型 HTTP webhook 端点用于外部触发。 { "text": "System line", "mode": "now" } ``` -- `text` **必填**（字符串）：事件描述（例如 "New email received"）。 -- `mode` 可选（`now` | `next-heartbeat`）：是否触发立即心跳（默认 `now`）或等待下一次周期性检查。 +- `text` **必填**（字符串）：事件描述（例如"收到新邮件"）。 +- `mode` 可选（`now` | `next-heartbeat`）：是否立即触发心跳（默认 `now`）或等待下一次定期检查。 效果： -- 为**主**会话入队一个系统事件 -- 如果 `mode=now`，触发立即心跳 +- 为**主**会话加入一个系统事件队列 +- 如果 `mode=now`，则立即触发心跳 ### `POST /hooks/agent` @@ -79,44 +79,44 @@ Gateway网关可以暴露一个小型 HTTP webhook 端点用于外部触发。 } ``` -- `message` **必填**（字符串）：智能体处理的提示或消息。 -- `name` 可选（字符串）：hook 的人类可读名称（例如 "GitHub"），用作会话摘要的前缀。 +- `message` **必填**（字符串）：智能体要处理的提示或消息。 +- `name` 可选（字符串）：hook 的可读名称（例如"GitHub"），用作会话摘要的前缀。 - `sessionKey` 可选（字符串）：用于标识智能体会话的键。默认为随机的 `hook:`。使用一致的键可以在 hook 上下文中进行多轮对话。 -- `wakeMode` 可选（`now` | `next-heartbeat`）：是否触发立即心跳（默认 `now`）或等待下一次周期性检查。 -- `deliver` 可选（布尔值）：如果为 `true`，智能体的回复将发送到消息渠道。默认为 `true`。仅为心跳确认的回复会被自动跳过。 -- `channel` 可选（字符串）：投递的消息渠道。可选值：`last`、`whatsapp`、`telegram`、`discord`、`slack`、`mattermost`（插件）、`signal`、`imessage`、`msteams`。默认为 `last`。 -- `to` 可选（字符串）：渠道的接收方标识符（例如 WhatsApp/Signal 的电话号码、Telegram 的聊天 ID、Discord/Slack/Mattermost（插件）的频道 ID、Microsoft Teams 的会话 ID）。默认为主会话中的最后一个接收方。 -- `model` 可选（字符串）：模型覆盖（例如 `anthropic/claude-3-5-sonnet` 或别名）。如果有模型限制，必须在允许的模型列表中。 -- `thinking` 可选（字符串）：思维级别覆盖（例如 `low`、`medium`、`high`）。 +- `wakeMode` 可选（`now` | `next-heartbeat`）：是否立即触发心跳（默认 `now`）或等待下一次定期检查。 +- `deliver` 可选（布尔值）：如果为 `true`，智能体的响应将发送到消息渠道。默认为 `true`。仅为心跳确认的响应会自动跳过。 +- `channel` 可选（字符串）：用于投递的消息渠道。可选值：`last`、`whatsapp`、`telegram`、`discord`、`slack`、`mattermost`（插件）、`signal`、`imessage`、`msteams`。默认为 `last`。 +- `to` 可选（字符串）：渠道的接收者标识符（例如 WhatsApp/Signal 的电话号码、Telegram 的聊天 ID、Discord/Slack/Mattermost（插件）的频道 ID、MS Teams 的会话 ID）。默认为主会话中的最后一个接收者。 +- `model` 可选（字符串）：模型覆盖（例如 `anthropic/claude-3-5-sonnet` 或别名）。如果有限制，必须在允许的模型列表中。 +- `thinking` 可选（字符串）：思考级别覆盖（例如 `low`、`medium`、`high`）。 - `timeoutSeconds` 可选（数字）：智能体运行的最大持续时间（秒）。 效果： -- 运行一次**隔离式**智能体轮次（使用独立的会话键） -- 始终将摘要发布到**主**会话 -- 如果 `wakeMode=now`，触发立即心跳 +- 运行一个**隔离的**智能体回合（独立的会话键） +- 始终在**主**会话中发布摘要 +- 如果 `wakeMode=now`，则立即触发心跳 ### `POST /hooks/`（映射） -自定义 hook 名称通过 `hooks.mappings` 解析（参见配置）。映射可以将任意请求体转换为 `wake` 或 `agent` 操作，并支持可选的模板或代码转换。 +自定义 hook 名称通过 `hooks.mappings` 解析（见配置）。映射可以将任意请求体转换为 `wake` 或 `agent` 操作，支持可选的模板或代码转换。 -映射选项（概要）： +映射选项（摘要）： - `hooks.presets: ["gmail"]` 启用内置的 Gmail 映射。 - `hooks.mappings` 允许你在配置中定义 `match`、`action` 和模板。 -- `hooks.transformsDir` + `transform.module` 加载 JS/TS 模块以实现自定义逻辑。 +- `hooks.transformsDir` + `transform.module` 加载 JS/TS 模块用于自定义逻辑。 - 使用 `match.source` 保持通用的接收端点（基于请求体的路由）。 - TS 转换需要 TS 加载器（例如 `bun` 或 `tsx`）或运行时预编译的 `.js`。 - 在映射上设置 `deliver: true` + `channel`/`to` 可将回复路由到聊天界面（`channel` 默认为 `last`，回退到 WhatsApp）。 -- `allowUnsafeExternalContent: true` 为该 hook 禁用外部内容安全包装（危险；仅限受信任的内部来源）。 -- `openclaw webhooks gmail setup` 为 `openclaw webhooks gmail run` 写入 `hooks.gmail` 配置。完整的 Gmail watch 流程请参阅 [Gmail Pub/Sub](/automation/gmail-pubsub)。 +- `allowUnsafeExternalContent: true` 禁用该 hook 的外部内容安全包装（危险；仅用于受信任的内部来源）。 +- `openclaw webhooks gmail setup` 为 `openclaw webhooks gmail run` 写入 `hooks.gmail` 配置。完整的 Gmail 监听流程请参阅 [Gmail Pub/Sub](/automation/gmail-pubsub)。 ## 响应 - `200` 用于 `/hooks/wake` - `202` 用于 `/hooks/agent`（异步运行已启动） - `401` 认证失败 -- `400` 无效请求体 +- `400` 请求体无效 - `413` 请求体过大 ## 示例 @@ -137,7 +137,7 @@ curl -X POST http://127.0.0.1:18789/hooks/agent \ ### 使用不同的模型 -在 agent 请求体（或映射）中添加 `model` 以覆盖该次运行的模型： +在智能体请求体（或映射）中添加 `model` 以覆盖该次运行的模型： ```bash curl -X POST http://127.0.0.1:18789/hooks/agent \ @@ -146,7 +146,7 @@ curl -X POST http://127.0.0.1:18789/hooks/agent \ -d '{"message":"Summarize inbox","name":"Email","model":"openai/gpt-5.2-mini"}' ``` -如果你设置了 `agents.defaults.models`，请确保覆盖的模型包含在其中。 +如果你启用了 `agents.defaults.models` 限制，请确保覆盖的模型包含在其中。 ```bash curl -X POST http://127.0.0.1:18789/hooks/gmail \ @@ -157,7 +157,7 @@ curl -X POST http://127.0.0.1:18789/hooks/gmail \ ## 安全 -- 将 hook 端点限制在 local loopback、tailnet 或受信任的反向代理之后。 -- 使用专用的 hook 令牌；不要复用 Gateway网关认证令牌。 +- 将 hook 端点保持在 loopback、tailnet 或受信任的反向代理之后。 +- 使用专用的 hook 令牌；不要复用 Gateway 网关认证令牌。 - 避免在 webhook 日志中包含敏感的原始请求体。 -- Hook 请求体默认被视为不受信任的，并使用安全边界进行包装。如果你必须为特定 hook 禁用此功能，请在该 hook 的映射中设置 `allowUnsafeExternalContent: true`（危险）。 +- Hook 请求体默认被视为不受信任并使用安全边界包装。如果你必须为特定 hook 禁用此功能，请在该 hook 的映射中设置 `allowUnsafeExternalContent: true`（危险）。 diff --git a/docs/zh-CN/bedrock.md b/docs/zh-CN/bedrock.md index b1d665589f..bf88fe1418 100644 --- a/docs/zh-CN/bedrock.md +++ b/docs/zh-CN/bedrock.md @@ -1,23 +1,23 @@ --- read_when: - 你想在 OpenClaw 中使用 Amazon Bedrock 模型 - - 你需要为模型调用设置 AWS 凭证/区域 + - 你需要为模型调用配置 AWS 凭证/区域 summary: 在 OpenClaw 中使用 Amazon Bedrock（Converse API）模型 title: Amazon Bedrock x-i18n: - generated_at: "2026-02-01T19:39:40Z" + generated_at: "2026-02-03T10:04:01Z" model: claude-opus-4-5 provider: pi source_hash: 318f1048451a1910b70522e2f7f9dfc87084de26d9e3938a29d372eed32244a8 source_path: bedrock.md - workflow: 14 + workflow: 15 --- # Amazon Bedrock OpenClaw 可以通过 pi‑ai 的 **Bedrock Converse** 流式提供商使用 **Amazon Bedrock** 模型。Bedrock 认证使用 **AWS SDK 默认凭证链**，而非 API 密钥。 -## pi‑ai 支持的内容 +## pi‑ai 支持的功能 - 提供商：`amazon-bedrock` - API：`bedrock-converse-stream` @@ -26,7 +26,7 @@ OpenClaw 可以通过 pi‑ai 的 **Bedrock Converse** 流式提供商使用 **A ## 自动模型发现 -如果检测到 AWS 凭证，OpenClaw 可以自动发现支持**流式传输**和**文本输出**的 Bedrock 模型。发现功能使用 `bedrock:ListFoundationModels`，并带有缓存（默认：1 小时）。 +如果检测到 AWS 凭证，OpenClaw 可以自动发现支持**流式传输**和**文本输出**的 Bedrock 模型。发现功能使用 `bedrock:ListFoundationModels`，并会被缓存（默认：1 小时）。 配置选项位于 `models.bedrockDiscovery` 下： @@ -45,17 +45,17 @@ OpenClaw 可以通过 pi‑ai 的 **Bedrock Converse** 流式提供商使用 **A } ``` -说明： +注意事项： -- 当 AWS 凭证存在时，`enabled` 默认为 `true`。 +- `enabled` 在存在 AWS 凭证时默认为 `true`。 - `region` 默认为 `AWS_REGION` 或 `AWS_DEFAULT_REGION`，然后是 `us-east-1`。 - `providerFilter` 匹配 Bedrock 提供商名称（例如 `anthropic`）。 - `refreshInterval` 单位为秒；设置为 `0` 可禁用缓存。 -- `defaultContextWindow`（默认：`32000`）和 `defaultMaxTokens`（默认：`4096`）用于发现的模型（如果你了解模型限制可以覆盖）。 +- `defaultContextWindow`（默认：`32000`）和 `defaultMaxTokens`（默认：`4096`）用于已发现的模型（如果你知道模型限制，可以覆盖这些值）。 ## 设置（手动） -1. 确保 AWS 凭证在 **Gateway网关主机**上可用： +1. 确保 AWS 凭证在 **Gateway 网关主机**上可用： ```bash export AWS_ACCESS_KEY_ID="AKIA..." @@ -102,9 +102,9 @@ export AWS_BEARER_TOKEN_BEDROCK="..." ## EC2 实例角色 -在附加了 IAM 角色的 EC2 实例上运行 OpenClaw 时，AWS SDK 会自动使用实例元数据服务（IMDS）进行认证。但是，OpenClaw 的凭证检测目前仅检查环境变量，不检查 IMDS 凭证。 +当在附加了 IAM 角色的 EC2 实例上运行 OpenClaw 时，AWS SDK 会自动使用实例元数据服务（IMDS）进行认证。但是，OpenClaw 的凭证检测目前只检查环境变量，不检查 IMDS 凭证。 -**解决方法：** 设置 `AWS_PROFILE=default` 以表明 AWS 凭证可用。实际认证仍通过 IMDS 使用实例角色。 +**解决方法：** 设置 `AWS_PROFILE=default` 以表明 AWS 凭证可用。实际认证仍然通过 IMDS 使用实例角色。 ```bash # 添加到 ~/.bashrc 或你的 shell 配置文件 @@ -118,7 +118,7 @@ EC2 实例角色**所需的 IAM 权限**： - `bedrock:InvokeModelWithResponseStream` - `bedrock:ListFoundationModels`（用于自动发现） -或附加托管策略 `AmazonBedrockFullAccess`。 +或者附加托管策略 `AmazonBedrockFullAccess`。 **快速设置：** @@ -147,11 +147,11 @@ aws ec2 associate-iam-instance-profile \ --instance-id i-xxxxx \ --iam-instance-profile Name=EC2-Bedrock-Access -# 3. 在 EC2 实例上启用发现 +# 3. 在 EC2 实例上启用发现功能 openclaw config set models.bedrockDiscovery.enabled true openclaw config set models.bedrockDiscovery.region us-east-1 -# 4. 设置解决方法的环境变量 +# 4. 设置解决方法所需的环境变量 echo 'export AWS_PROFILE=default' >> ~/.bashrc echo 'export AWS_REGION=us-east-1' >> ~/.bashrc source ~/.bashrc @@ -160,11 +160,11 @@ source ~/.bashrc openclaw models list ``` -## 说明 +## 注意事项 - Bedrock 需要在你的 AWS 账户/区域中启用**模型访问**。 - 自动发现需要 `bedrock:ListFoundationModels` 权限。 -- 如果你使用配置文件，请在 Gateway网关主机上设置 `AWS_PROFILE`。 -- OpenClaw 按以下顺序检测凭证来源：`AWS_BEARER_TOKEN_BEDROCK`，然后 `AWS_ACCESS_KEY_ID` + `AWS_SECRET_ACCESS_KEY`，然后 `AWS_PROFILE`，最后是默认的 AWS SDK 链。 +- 如果你使用配置文件，请在 Gateway 网关主机上设置 `AWS_PROFILE`。 +- OpenClaw 按以下顺序获取凭证来源：`AWS_BEARER_TOKEN_BEDROCK`，然后是 `AWS_ACCESS_KEY_ID` + `AWS_SECRET_ACCESS_KEY`，然后是 `AWS_PROFILE`，最后是默认的 AWS SDK 链。 - 推理支持取决于模型；请查看 Bedrock 模型卡了解当前功能。 -- 如果你偏好托管密钥流程，也可以在 Bedrock 前面放置一个兼容 OpenAI 的代理，将其配置为 OpenAI 提供商。 +- 如果你更喜欢托管密钥流程，也可以在 Bedrock 前面放置一个 OpenAI 兼容的代理，并将其配置为 OpenAI 提供商。 diff --git a/docs/zh-CN/brave-search.md b/docs/zh-CN/brave-search.md index b3b56a7c22..d69d45f04d 100644 --- a/docs/zh-CN/brave-search.md +++ b/docs/zh-CN/brave-search.md @@ -2,15 +2,15 @@ read_when: - 你想使用 Brave Search 进行 web_search - 你需要 BRAVE_API_KEY 或套餐详情 -summary: 为 web_search 设置 Brave Search API +summary: 用于 web_search 的 Brave Search API 设置 title: Brave Search x-i18n: - generated_at: "2026-02-01T19:39:45Z" + generated_at: "2026-02-03T07:43:09Z" model: claude-opus-4-5 provider: pi source_hash: cdcb037b092b8a10609f02acf062b4164cb826ac22bdb3fb2909c842a1405341 source_path: brave-search.md - workflow: 14 + workflow: 15 --- # Brave Search API @@ -19,9 +19,9 @@ OpenClaw 使用 Brave Search 作为 `web_search` 的默认提供商。 ## 获取 API 密钥 -1. 在 https://brave.com/search/api/ 创建 Brave Search API 账户。 +1. 在 https://brave.com/search/api/ 创建 Brave Search API 账户 2. 在控制面板中，选择 **Data for Search** 套餐并生成 API 密钥。 -3. 将密钥存储在配置中（推荐）或在 Gateway网关环境中设置 `BRAVE_API_KEY`。 +3. 将密钥存储在配置中（推荐），或在 Gateway 网关环境中设置 `BRAVE_API_KEY`。 ## 配置示例 @@ -40,9 +40,9 @@ OpenClaw 使用 Brave Search 作为 `web_search` 的默认提供商。 } ``` -## 说明 +## 注意事项 - Data for AI 套餐与 `web_search` **不**兼容。 -- Brave 提供免费套餐和付费套餐；请查看 Brave API 门户了解当前限制。 +- Brave 提供免费层级和付费套餐；请查看 Brave API 门户了解当前限制。 -完整的 web_search 配置请参阅 [Web 工具](/tools/web)。 +请参阅 [Web 工具](/tools/web) 了解完整的 web_search 配置。 diff --git a/docs/zh-CN/broadcast-groups.md b/docs/zh-CN/broadcast-groups.md index 183f8a41af..dff1e9c814 100644 --- a/docs/zh-CN/broadcast-groups.md +++ b/docs/zh-CN/broadcast-groups.md @@ -3,29 +3,29 @@ read_when: - 配置广播群组 - 调试 WhatsApp 中的多智能体回复 status: experimental -summary: 将 WhatsApp 消息广播给多个智能体 +summary: 向多个智能体广播 WhatsApp 消息 title: 广播群组 x-i18n: - generated_at: "2026-02-01T19:40:25Z" + generated_at: "2026-02-03T07:43:43Z" model: claude-opus-4-5 provider: pi source_hash: eaeb4035912c49413e012177cf0bd28b348130d30d3317674418dca728229b70 source_path: broadcast-groups.md - workflow: 14 + workflow: 15 --- # 广播群组 -**状态：** 实验性 -**版本：** 在 2026.1.9 中添加 +**状态：** 实验性功能 +**版本：** 于 2026.1.9 版本新增 ## 概述 -广播群组允许多个智能体同时处理和回复同一条消息。这使你可以创建在单个 WhatsApp 群组或私聊中协同工作的专业智能体团队——全部使用同一个电话号码。 +广播群组允许多个智能体同时处理并响应同一条消息。这使你能够在单个 WhatsApp 群组或私信中创建协同工作的专业智能体团队——全部使用同一个手机号码。 -当前范围：**仅限 WhatsApp**（Web 渠道）。 +当前范围：**仅限 WhatsApp**（web 渠道）。 -广播群组在渠道允许列表和群组激活规则之后进行评估。在 WhatsApp 群组中，这意味着广播发生在 OpenClaw 正常回复的时机（例如：被提及时，取决于你的群组设置）。 +广播群组在渠道白名单和群组激活规则之后进行评估。在 WhatsApp 群组中，这意味着广播会在 OpenClaw 正常回复时发生（例如：被提及时，具体取决于你的群组设置）。 ## 使用场景 @@ -34,53 +34,53 @@ x-i18n: 部署多个具有原子化、专注职责的智能体： ``` -群组："Development Team" -智能体： - - CodeReviewer（审查代码片段） - - DocumentationBot（生成文档） - - SecurityAuditor（检查漏洞） - - TestGenerator（建议测试用例） +Group: "Development Team" +Agents: + - CodeReviewer (reviews code snippets) + - DocumentationBot (generates docs) + - SecurityAuditor (checks for vulnerabilities) + - TestGenerator (suggests test cases) ``` -每个智能体处理同一条消息并提供其专业视角。 +每个智能体处理相同的消息并提供其专业视角。 ### 2. 多语言支持 ``` -群组："International Support" -智能体： - - Agent_EN（用英语回复） - - Agent_DE（用德语回复） - - Agent_ES（用西班牙语回复） +Group: "International Support" +Agents: + - Agent_EN (responds in English) + - Agent_DE (responds in German) + - Agent_ES (responds in Spanish) ``` ### 3. 质量保证工作流 ``` -群组："Customer Support" -智能体： - - SupportAgent（提供回答） - - QAAgent（审查质量，仅在发现问题时回复） +Group: "Customer Support" +Agents: + - SupportAgent (provides answer) + - QAAgent (reviews quality, only responds if issues found) ``` ### 4. 任务自动化 ``` -群组："Project Management" -智能体： - - TaskTracker（更新任务数据库） - - TimeLogger（记录时间消耗） - - ReportGenerator（创建摘要） +Group: "Project Management" +Agents: + - TaskTracker (updates task database) + - TimeLogger (logs time spent) + - ReportGenerator (creates summaries) ``` ## 配置 ### 基本设置 -添加顶层 `broadcast` 部分（与 `bindings` 同级）。键为 WhatsApp peer ID： +添加一个顶层 `broadcast` 部分（与 `bindings` 同级）。键为 WhatsApp peer id： - 群聊：群组 JID（例如 `120363403215116621@g.us`） -- 私聊：E.164 格式电话号码（例如 `+15551234567`） +- 私信：E.164 格式的电话号码（例如 `+15551234567`） ```json { @@ -90,7 +90,7 @@ x-i18n: } ``` -**效果：** 当 OpenClaw 在此聊天中回复时，它会运行所有三个智能体。 +**结果：** 当 OpenClaw 在此聊天中回复时，将运行所有三个智能体。 ### 处理策略 @@ -111,7 +111,7 @@ x-i18n: #### 顺序 -智能体按顺序处理（每个等待前一个完成）： +智能体按顺序处理（后一个等待前一个完成）： ```json { @@ -161,62 +161,62 @@ x-i18n: ### 消息流程 -1. **收到消息**，来自 WhatsApp 群组 +1. **接收消息** 到达 WhatsApp 群组 2. **广播检查**：系统检查 peer ID 是否在 `broadcast` 中 3. **如果在广播列表中**： - 所有列出的智能体处理该消息 - 每个智能体有自己的会话键和隔离的上下文 - - 智能体并行（默认）或顺序处理 + - 智能体并行处理（默认）或顺序处理 4. **如果不在广播列表中**： - 应用正常路由（第一个匹配的绑定） -注意：广播群组不会绕过渠道允许列表或群组激活规则（提及/命令等）。它们仅在消息符合处理条件时改变*哪些智能体运行*。 +注意：广播群组不会绕过渠道白名单或群组激活规则（提及/命令等）。它们只改变消息符合处理条件时*运行哪些智能体*。 ### 会话隔离 -广播群组中的每个智能体维护完全独立的： +广播群组中的每个智能体完全独立维护： -- **会话键**（`agent:alfred:whatsapp:group:120363...` 与 `agent:baerbel:whatsapp:group:120363...`） +- **会话键**（`agent:alfred:whatsapp:group:120363...` vs `agent:baerbel:whatsapp:group:120363...`） - **对话历史**（智能体看不到其他智能体的消息） -- **工作区**（如果配置了则为独立沙箱） -- **工具访问**（不同的允许/拒绝列表） +- **工作空间**（如果配置了则使用独立的沙箱） +- **工具访问权限**（不同的允许/拒绝列表） - **记忆/上下文**（独立的 IDENTITY.md、SOUL.md 等） -- **群组上下文缓冲区**（用于上下文的最近群组消息）按 peer 共享，因此所有广播智能体在触发时看到相同的上下文 +- **群组上下文缓冲区**（用于上下文的最近群组消息）按 peer 共享，因此所有广播智能体在被触发时看到相同的上下文 -这使得每个智能体可以拥有： +这允许每个智能体拥有： - 不同的个性 -- 不同的工具访问权限（例如只读与读写） -- 不同的模型（例如 opus 与 sonnet） +- 不同的工具访问权限（例如只读 vs 读写） +- 不同的模型（例如 opus vs sonnet） - 不同的已安装 Skills -### 示例：隔离会话 +### 示例：隔离的会话 在群组 `120363403215116621@g.us` 中，智能体为 `["alfred", "baerbel"]`： **Alfred 的上下文：** ``` -会话：agent:alfred:whatsapp:group:120363403215116621@g.us -历史：[用户消息，alfred 之前的回复] -工作区：/Users/pascal/openclaw-alfred/ -工具：read、write、exec +Session: agent:alfred:whatsapp:group:120363403215116621@g.us +History: [user message, alfred's previous responses] +Workspace: /Users/pascal/openclaw-alfred/ +Tools: read, write, exec ``` **Bärbel 的上下文：** ``` -会话：agent:baerbel:whatsapp:group:120363403215116621@g.us -历史：[用户消息，baerbel 之前的回复] -工作区：/Users/pascal/openclaw-baerbel/ -工具：仅 read +Session: agent:baerbel:whatsapp:group:120363403215116621@g.us +History: [user message, baerbel's previous responses] +Workspace: /Users/pascal/openclaw-baerbel/ +Tools: read only ``` ## 最佳实践 ### 1. 保持智能体专注 -为每个智能体设计单一、明确的职责： +将每个智能体设计为具有单一、明确的职责： ```json { @@ -226,12 +226,12 @@ x-i18n: } ``` -✅ **好的做法：** 每个智能体只有一项工作 -❌ **不好的做法：** 一个通用的 "dev-helper" 智能体 +✅ **好的做法：** 每个智能体只有一个任务 +❌ **不好的做法：** 一个通用的"dev-helper"智能体 ### 2. 使用描述性名称 -让每个智能体的功能一目了然： +明确每个智能体的功能： ```json { @@ -245,16 +245,16 @@ x-i18n: ### 3. 配置不同的工具访问权限 -只给智能体它们需要的工具： +只给智能体提供它们需要的工具： ```json { "agents": { "reviewer": { - "tools": { "allow": ["read", "exec"] } // 只读 + "tools": { "allow": ["read", "exec"] } // Read-only }, "fixer": { - "tools": { "allow": ["read", "write", "edit", "exec"] } // 读写 + "tools": { "allow": ["read", "write", "edit", "exec"] } // Read-write } } } @@ -262,19 +262,19 @@ x-i18n: ### 4. 监控性能 -当智能体数量较多时，请考虑： +当有多个智能体时，请考虑： - 使用 `"strategy": "parallel"`（默认）以提高速度 - 将广播群组限制在 5-10 个智能体 -- 为较简单的智能体使用更快的模型 +- 为较简单的智能体使用较快的模型 -### 5. 优雅处理失败 +### 5. 优雅地处理失败 智能体独立失败。一个智能体的错误不会阻塞其他智能体： ``` -消息 → [智能体 A ✓, 智能体 B ✗ 错误, 智能体 C ✓] -结果：智能体 A 和 C 回复，智能体 B 记录错误 +Message → [Agent A ✓, Agent B ✗ error, Agent C ✓] +Result: Agent A and C respond, Agent B logs error ``` ## 兼容性 @@ -290,7 +290,7 @@ x-i18n: ### 路由 -广播群组与现有路由并行工作： +广播群组与现有路由一起工作： ```json { @@ -306,14 +306,14 @@ x-i18n: } ``` -- `GROUP_A`：仅 alfred 回复（正常路由） -- `GROUP_B`：agent1 和 agent2 都回复（广播） +- `GROUP_A`：只有 alfred 响应（正常路由） +- `GROUP_B`：agent1 和 agent2 都响应（广播） **优先级：** `broadcast` 优先于 `bindings`。 ## 故障排除 -### 智能体没有回复 +### 智能体不响应 **检查：** @@ -327,18 +327,18 @@ x-i18n: tail -f ~/.openclaw/logs/gateway.log | grep broadcast ``` -### 仅一个智能体回复 +### 只有一个智能体响应 **原因：** Peer ID 可能在 `bindings` 中但不在 `broadcast` 中。 -**修复：** 添加到广播配置中或从 bindings 中移除。 +**修复：** 添加到广播配置或从绑定中移除。 ### 性能问题 -**如果智能体较多时速度慢：** +**如果智能体较多时速度较慢：** - 减少每个群组的智能体数量 -- 使用更轻量的模型（sonnet 而非 opus） +- 使用较轻的模型（sonnet 而非 opus） - 检查沙箱启动时间 ## 示例 @@ -380,9 +380,9 @@ tail -f ~/.openclaw/logs/gateway.log | grep broadcast ``` **用户发送：** 代码片段 -**回复：** +**响应：** -- code-formatter："已修复缩进并添加了类型提示" +- code-formatter："修复了缩进并添加了类型提示" - security-scanner："⚠️ 第 12 行存在 SQL 注入漏洞" - test-coverage："覆盖率为 45%，缺少错误情况的测试" - docs-checker："函数 `process_data` 缺少文档字符串" @@ -420,7 +420,7 @@ interface OpenClawConfig { ### 字段 -- `strategy`（可选）：智能体的处理方式 +- `strategy`（可选）：如何处理智能体 - `"parallel"`（默认）：所有智能体同时处理 - `"sequential"`：智能体按数组顺序处理 - `[peerId]`：WhatsApp 群组 JID、E.164 号码或其他 peer ID @@ -428,19 +428,19 @@ interface OpenClawConfig { ## 限制 -1. **最大智能体数：** 无硬性限制，但 10 个以上可能会变慢 -2. **共享上下文：** 智能体看不到彼此的回复（设计如此） -3. **消息排序：** 并行回复可能以任意顺序到达 -4. **速率限制：** 所有智能体共同计入 WhatsApp 速率限制 +1. **最大智能体数：** 无硬性限制，但 10 个以上智能体可能会较慢 +2. **共享上下文：** 智能体看不到彼此的响应（设计如此） +3. **消息顺序：** 并行响应可能以任意顺序到达 +4. **速率限制：** 所有智能体都计入 WhatsApp 速率限制 ## 未来增强 计划中的功能： -- [ ] 共享上下文模式（智能体可以看到彼此的回复） -- [ ] 智能体协调（智能体可以互相通信） +- [ ] 共享上下文模式（智能体可以看到彼此的响应） +- [ ] 智能体协调（智能体可以相互发信号） - [ ] 动态智能体选择（根据消息内容选择智能体） -- [ ] 智能体优先级（某些智能体先于其他智能体回复） +- [ ] 智能体优先级（某些智能体先于其他智能体响应） ## 另请参阅 diff --git a/docs/zh-CN/channels/bluebubbles.md b/docs/zh-CN/channels/bluebubbles.md index 7000f6e1e0..15e85d0c1d 100644 --- a/docs/zh-CN/channels/bluebubbles.md +++ b/docs/zh-CN/channels/bluebubbles.md @@ -3,36 +3,36 @@ read_when: - 设置 BlueBubbles 渠道 - 排查 webhook 配对问题 - 在 macOS 上配置 iMessage -summary: 通过 BlueBubbles macOS 服务器集成 iMessage（REST 发送/接收、输入状态、回应、配对、高级操作）。 +summary: 通过 BlueBubbles macOS 服务器使用 iMessage（REST 发送/接收、输入状态、回应、配对、高级操作）。 title: BlueBubbles x-i18n: - generated_at: "2026-02-01T19:41:18Z" + generated_at: "2026-02-03T10:04:52Z" model: claude-opus-4-5 provider: pi - source_hash: ac9a9d71f3bbc661da6cb2897ea32d290bbd16b35925250601cfff53bc85de8c + source_hash: 3aae277a8bec479800a7f6268bfbca912c65a4aadc6e513694057fb873597b69 source_path: channels/bluebubbles.md - workflow: 14 + workflow: 15 --- # BlueBubbles（macOS REST） -状态：内置插件，通过 HTTP 与 BlueBubbles macOS 服务器通信。**推荐用于 iMessage 集成**，因为相比旧版 imsg 渠道，其 API 更丰富且更易于设置。 +状态：内置插件，通过 HTTP 与 BlueBubbles macOS 服务器通信。由于其更丰富的 API 和更简便的设置，**推荐用于 iMessage 集成**，优于旧版 imsg 渠道。 ## 概述 - 通过 BlueBubbles 辅助应用在 macOS 上运行（[bluebubbles.app](https://bluebubbles.app)）。 -- 推荐/已测试：macOS Sequoia (15)。macOS Tahoe (26) 可用；编辑功能目前在 Tahoe 上不可用，群组图标更新可能报告成功但不会同步。 +- 推荐/已测试版本：macOS Sequoia (15)。macOS Tahoe (26) 可用；但在 Tahoe 上编辑功能目前不可用，群组图标更新可能显示成功但实际未同步。 - OpenClaw 通过其 REST API 与之通信（`GET /api/v1/ping`、`POST /message/text`、`POST /chat/:id/*`）。 -- 收到的消息通过 webhooks 到达；发出的回复、输入指示器、已读回执和 tapback 回应均为 REST 调用。 -- 附件和贴纸作为入站媒体被接收（在可能的情况下呈现给智能体）。 -- 配对/允许列表与其他渠道的工作方式相同（`/start/pairing` 等），使用 `channels.bluebubbles.allowFrom` + 配对码。 -- 回应作为系统事件呈现，与 Slack/Telegram 相同，因此智能体可以在回复前"提及"它们。 -- 高级功能：编辑、撤回、回复线程、消息特效、群组管理。 +- 传入消息通过 webhook 到达；发出的回复、输入指示器、已读回执和 tapback 均为 REST 调用。 +- 附件和贴纸作为入站媒体被接收（并在可能时呈现给智能体）。 +- 配对/白名单的工作方式与其他渠道相同（`/start/pairing` 等），使用 `channels.bluebubbles.allowFrom` + 配对码。 +- 回应作为系统事件呈现，与 Slack/Telegram 类似，智能体可以在回复前"提及"它们。 +- 高级功能：编辑、撤回、回复线程、消息效果、群组管理。 ## 快速开始 1. 在你的 Mac 上安装 BlueBubbles 服务器（按照 [bluebubbles.app/install](https://bluebubbles.app/install) 的说明操作）。 -2. 在 BlueBubbles 配置中，启用 Web API 并设置密码。 +2. 在 BlueBubbles 配置中，启用 web API 并设置密码。 3. 运行 `openclaw onboard` 并选择 BlueBubbles，或手动配置： ```json5 { @@ -46,8 +46,8 @@ x-i18n: }, } ``` -4. 将 BlueBubbles webhooks 指向你的 Gateway网关（示例：`https://your-gateway-host:3000/bluebubbles-webhook?password=`）。 -5. 启动 Gateway网关；它将注册 webhook 处理器并开始配对。 +4. 将 BlueBubbles webhook 指向你的 Gateway 网关（示例：`https://your-gateway-host:3000/bluebubbles-webhook?password=`）。 +5. 启动 Gateway 网关；它将注册 webhook 处理程序并开始配对。 ## 新手引导 @@ -62,8 +62,8 @@ openclaw onboard - **服务器 URL**（必填）：BlueBubbles 服务器地址（例如 `http://192.168.1.100:1234`） - **密码**（必填）：来自 BlueBubbles 服务器设置的 API 密码 - **Webhook 路径**（可选）：默认为 `/bluebubbles-webhook` -- **私聊策略**：配对、允许列表、开放或禁用 -- **允许列表**：电话号码、邮箱或聊天目标 +- **私信策略**：配对、白名单、开放或禁用 +- **白名单**：电话号码、电子邮件或聊天目标 你也可以通过 CLI 添加 BlueBubbles： @@ -71,13 +71,13 @@ openclaw onboard openclaw channels add bluebubbles --http-url http://192.168.1.100:1234 --password ``` -## 访问控制（私聊 + 群组） +## 访问控制（私信 + 群组） -私聊： +私信： - 默认：`channels.bluebubbles.dmPolicy = "pairing"`。 -- 未知发送者会收到配对码；消息在批准前会被忽略（配对码 1 小时后过期）。 -- 通过以下方式批准： +- 未知发送者会收到配对码；在批准之前消息会被忽略（配对码 1 小时后过期）。 +- 批准方式： - `openclaw pairing list bluebubbles` - `openclaw pairing approve bluebubbles ` - 配对是默认的令牌交换方式。详情：[配对](/start/pairing) @@ -92,10 +92,10 @@ openclaw channels add bluebubbles --http-url http://192.168.1.100:1234 --passwor BlueBubbles 支持群聊的提及门控，与 iMessage/WhatsApp 行为一致： - 使用 `agents.list[].groupChat.mentionPatterns`（或 `messages.groupChat.mentionPatterns`）检测提及。 -- 当群组启用 `requireMention` 时，智能体仅在被提及时回复。 +- 当群组启用 `requireMention` 时，智能体仅在被提及时响应。 - 来自授权发送者的控制命令会绕过提及门控。 -按群组配置： +单群组配置： ```json5 { @@ -104,8 +104,8 @@ BlueBubbles 支持群聊的提及门控，与 iMessage/WhatsApp 行为一致： groupPolicy: "allowlist", groupAllowFrom: ["+15555550123"], groups: { - "*": { requireMention: true }, // 所有群组的默认值 - "iMessage;-;chat123": { requireMention: false }, // 针对特定群组的覆盖 + "*": { requireMention: true }, // 所有群组的默认设置 + "iMessage;-;chat123": { requireMention: false }, // 特定群组的覆盖设置 }, }, }, @@ -115,12 +115,12 @@ BlueBubbles 支持群聊的提及门控，与 iMessage/WhatsApp 行为一致： ### 命令门控 - 控制命令（例如 `/config`、`/model`）需要授权。 -- 使用 `allowFrom` 和 `groupAllowFrom` 来确定命令授权。 -- 授权发送者即使在群组中未提及也可以运行控制命令。 +- 使用 `allowFrom` 和 `groupAllowFrom` 确定命令授权。 +- 授权发送者即使在群组中未被提及也可以运行控制命令。 ## 输入状态 + 已读回执 -- **输入指示器**：在生成回复前和生成过程中自动发送。 +- **输入指示器**：在响应生成前和生成期间自动发送。 - **已读回执**：由 `channels.bluebubbles.sendReadReceipts` 控制（默认：`true`）。 - **输入指示器**：OpenClaw 发送输入开始事件；BlueBubbles 在发送或超时时自动清除输入状态（通过 DELETE 手动停止不可靠）。 @@ -136,21 +136,21 @@ BlueBubbles 支持群聊的提及门控，与 iMessage/WhatsApp 行为一致： ## 高级操作 -在配置中启用后，BlueBubbles 支持高级消息操作： +BlueBubbles 在配置中启用时支持高级消息操作： ```json5 { channels: { bluebubbles: { actions: { - reactions: true, // tapback 回应（默认：true） - edit: true, // 编辑已发送消息（macOS 13+，macOS 26 Tahoe 上不可用） + reactions: true, // tapback（默认：true） + edit: true, // 编辑已发送消息（macOS 13+，在 macOS 26 Tahoe 上不可用） unsend: true, // 撤回消息（macOS 13+） - reply: true, // 按消息 GUID 回复线程 - sendWithEffect: true, // 消息特效（slam、loud 等） + reply: true, // 通过消息 GUID 进行回复线程 + sendWithEffect: true, // 消息效果（slam、loud 等） renameGroup: true, // 重命名群聊 - setGroupIcon: true, // 设置群聊图标/头像（macOS 26 Tahoe 上不稳定） - addParticipant: true, // 向群组添加参与者 + setGroupIcon: true, // 设置群聊图标/照片（在 macOS 26 Tahoe 上不稳定） + addParticipant: true, // 将参与者添加到群组 removeParticipant: true, // 从群组移除参与者 leaveGroup: true, // 离开群聊 sendAttachment: true, // 发送附件/媒体 @@ -166,40 +166,40 @@ BlueBubbles 支持群聊的提及门控，与 iMessage/WhatsApp 行为一致： - **edit**：编辑已发送的消息（`messageId`、`text`） - **unsend**：撤回消息（`messageId`） - **reply**：回复特定消息（`messageId`、`text`、`to`） -- **sendWithEffect**：使用 iMessage 特效发送（`text`、`to`、`effectId`） +- **sendWithEffect**：带 iMessage 效果发送（`text`、`to`、`effectId`） - **renameGroup**：重命名群聊（`chatGuid`、`displayName`） -- **setGroupIcon**：设置群聊图标/头像（`chatGuid`、`media`）——在 macOS 26 Tahoe 上不稳定（API 可能返回成功但图标不会同步）。 -- **addParticipant**：向群组添加成员（`chatGuid`、`address`） -- **removeParticipant**：从群组移除成员（`chatGuid`、`address`） +- **setGroupIcon**：设置群聊图标/照片（`chatGuid`、`media`）— 在 macOS 26 Tahoe 上不稳定（API 可能返回成功但图标未同步）。 +- **addParticipant**：将某人添加到群组（`chatGuid`、`address`） +- **removeParticipant**：将某人从群组移除（`chatGuid`、`address`） - **leaveGroup**：离开群聊（`chatGuid`） - **sendAttachment**：发送媒体/文件（`to`、`buffer`、`filename`、`asVoice`） - - 语音备忘录：设置 `asVoice: true` 并使用 **MP3** 或 **CAF** 音频以 iMessage 语音消息形式发送。BlueBubbles 在发送语音备忘录时会将 MP3 转换为 CAF。 + - 语音备忘录：将 `asVoice: true` 与 **MP3** 或 **CAF** 音频一起设置，以 iMessage 语音消息形式发送。BlueBubbles 在发送语音备忘录时会将 MP3 转换为 CAF。 -### 消息 ID（短格式与完整格式） +### 消息 ID（短格式 vs 完整格式） -OpenClaw 可能会呈现*短*消息 ID（例如 `1`、`2`）以节省 token。 +OpenClaw 可能会显示*短*消息 ID（例如 `1`、`2`）以节省 token。 - `MessageSid` / `ReplyToId` 可以是短 ID。 - `MessageSidFull` / `ReplyToIdFull` 包含提供商的完整 ID。 - 短 ID 存储在内存中；它们可能在重启或缓存清除后过期。 -- 操作接受短格式或完整格式的 `messageId`，但如果短 ID 不再可用则会报错。 +- 操作接受短或完整的 `messageId`，但如果短 ID 不再可用将会报错。 对于持久化自动化和存储，请使用完整 ID： - 模板：`{{MessageSidFull}}`、`{{ReplyToIdFull}}` - 上下文：入站负载中的 `MessageSidFull` / `ReplyToIdFull` -模板变量请参阅[配置](/gateway/configuration)。 +参见[配置](/gateway/configuration)了解模板变量。 ## 分块流式传输 -控制回复是作为单条消息发送还是分块流式传输： +控制响应是作为单条消息发送还是分块流式传输： ```json5 { channels: { bluebubbles: { - blockStreaming: true, // 启用分块流式传输（默认行为） + blockStreaming: true, // 启用分块流式传输（默认关闭） }, }, } @@ -209,7 +209,7 @@ OpenClaw 可能会呈现*短*消息 ID（例如 `1`、`2`）以节省 token。 - 入站附件会被下载并存储在媒体缓存中。 - 媒体上限通过 `channels.bluebubbles.mediaMaxMb` 设置（默认：8 MB）。 -- 出站文本按 `channels.bluebubbles.textChunkLimit` 进行分块（默认：4000 字符）。 +- 出站文本按 `channels.bluebubbles.textChunkLimit` 分块（默认：4000 字符）。 ## 配置参考 @@ -222,17 +222,17 @@ OpenClaw 可能会呈现*短*消息 ID（例如 `1`、`2`）以节省 token。 - `channels.bluebubbles.password`：API 密码。 - `channels.bluebubbles.webhookPath`：Webhook 端点路径（默认：`/bluebubbles-webhook`）。 - `channels.bluebubbles.dmPolicy`：`pairing | allowlist | open | disabled`（默认：`pairing`）。 -- `channels.bluebubbles.allowFrom`：私聊允许列表（句柄、邮箱、E.164 号码、`chat_id:*`、`chat_guid:*`）。 +- `channels.bluebubbles.allowFrom`：私信白名单（句柄、电子邮件、E.164 号码、`chat_id:*`、`chat_guid:*`）。 - `channels.bluebubbles.groupPolicy`：`open | allowlist | disabled`（默认：`allowlist`）。 -- `channels.bluebubbles.groupAllowFrom`：群组发送者允许列表。 -- `channels.bluebubbles.groups`：按群组配置（`requireMention` 等）。 +- `channels.bluebubbles.groupAllowFrom`：群组发送者白名单。 +- `channels.bluebubbles.groups`：单群组配置（`requireMention` 等）。 - `channels.bluebubbles.sendReadReceipts`：发送已读回执（默认：`true`）。 -- `channels.bluebubbles.blockStreaming`：启用分块流式传输（默认：`true`）。 -- `channels.bluebubbles.textChunkLimit`：出站分块大小（字符数，默认：4000）。 -- `channels.bluebubbles.chunkMode`：`length`（默认）仅在超过 `textChunkLimit` 时分割；`newline` 在空行（段落边界）处分割，然后再进行长度分块。 -- `channels.bluebubbles.mediaMaxMb`：入站媒体上限（MB，默认：8）。 -- `channels.bluebubbles.historyLimit`：用于上下文的最大群组消息数（0 表示禁用）。 -- `channels.bluebubbles.dmHistoryLimit`：私聊历史限制。 +- `channels.bluebubbles.blockStreaming`：启用分块流式传输（默认：`false`；流式回复必需）。 +- `channels.bluebubbles.textChunkLimit`：出站分块大小（字符）（默认：4000）。 +- `channels.bluebubbles.chunkMode`：`length`（默认）仅在超过 `textChunkLimit` 时分割；`newline` 在长度分块前先按空行（段落边界）分割。 +- `channels.bluebubbles.mediaMaxMb`：入站媒体上限（MB）（默认：8）。 +- `channels.bluebubbles.historyLimit`：上下文的最大群组消息数（0 表示禁用）。 +- `channels.bluebubbles.dmHistoryLimit`：私信历史限制。 - `channels.bluebubbles.actions`：启用/禁用特定操作。 - `channels.bluebubbles.accounts`：多账户配置。 @@ -241,31 +241,31 @@ OpenClaw 可能会呈现*短*消息 ID（例如 `1`、`2`）以节省 token。 - `agents.list[].groupChat.mentionPatterns`（或 `messages.groupChat.mentionPatterns`）。 - `messages.responsePrefix`。 -## 寻址/投递目标 +## 地址 / 投递目标 -推荐使用 `chat_guid` 以实现稳定路由： +优先使用 `chat_guid` 以获得稳定的路由： -- `chat_guid:iMessage;-;+15555550123`（群组推荐使用） +- `chat_guid:iMessage;-;+15555550123`（群组推荐） - `chat_id:123` - `chat_identifier:...` - 直接句柄：`+15555550123`、`user@example.com` - - 如果直接句柄没有现有的私聊会话，OpenClaw 将通过 `POST /api/v1/chat/new` 创建一个。这需要启用 BlueBubbles Private API。 + - 如果直接句柄没有现有的私信聊天，OpenClaw 将通过 `POST /api/v1/chat/new` 创建一个。这需要启用 BlueBubbles Private API。 -## 安全 +## 安全性 -- Webhook 请求通过将 `guid`/`password` 查询参数或请求头与 `channels.bluebubbles.password` 比较来进行认证。来自 `localhost` 的请求也会被接受。 -- 请保密 API 密码和 webhook 端点（将其视为凭证）。 -- localhost 信任意味着同主机的反向代理可能会无意间绕过密码。如果你为 Gateway网关设置了代理，请在代理层要求认证并配置 `gateway.trustedProxies`。参见 [Gateway网关安全](/gateway/security#reverse-proxy-configuration)。 -- 如果将 BlueBubbles 服务器暴露到局域网外部，请启用 HTTPS + 防火墙规则。 +- Webhook 请求通过比较 `guid`/`password` 查询参数或头部与 `channels.bluebubbles.password` 进行身份验证。来自 `localhost` 的请求也会被接受。 +- 保持 API 密码和 webhook 端点的机密性（将它们视为凭证）。 +- localhost 信任意味着同主机的反向代理可能无意中绕过密码验证。如果你使用代理 Gateway 网关，请在代理处要求身份验证并配置 `gateway.trustedProxies`。参见 [Gateway 网关安全性](/gateway/security#reverse-proxy-configuration)。 +- 如果将 BlueBubbles 服务器暴露在局域网之外，请启用 HTTPS + 防火墙规则。 ## 故障排除 -- 如果输入/已读事件停止工作，请检查 BlueBubbles webhook 日志并验证 Gateway网关路径是否与 `channels.bluebubbles.webhookPath` 匹配。 +- 如果输入/已读事件停止工作，请检查 BlueBubbles webhook 日志并验证 Gateway 网关路径是否与 `channels.bluebubbles.webhookPath` 匹配。 - 配对码在一小时后过期；使用 `openclaw pairing list bluebubbles` 和 `openclaw pairing approve bluebubbles `。 -- 回应功能需要 BlueBubbles private API（`POST /api/v1/message/react`）；请确保服务器版本已暴露该接口。 +- 回应需要 BlueBubbles private API（`POST /api/v1/message/react`）；确保服务器版本支持它。 - 编辑/撤回需要 macOS 13+ 和兼容的 BlueBubbles 服务器版本。在 macOS 26（Tahoe）上，由于 private API 变更，编辑功能目前不可用。 -- 群组图标更新在 macOS 26（Tahoe）上可能不稳定：API 可能返回成功但新图标不会同步。 -- OpenClaw 会根据 BlueBubbles 服务器的 macOS 版本自动隐藏已知不可用的操作。如果编辑功能在 macOS 26（Tahoe）上仍然显示，请手动通过 `channels.bluebubbles.actions.edit=false` 禁用。 +- 在 macOS 26（Tahoe）上群组图标更新可能不稳定：API 可能返回成功但新图标未同步。 +- OpenClaw 会根据 BlueBubbles 服务器的 macOS 版本自动隐藏已知不可用的操作。如果在 macOS 26（Tahoe）上编辑仍然显示，请使用 `channels.bluebubbles.actions.edit=false` 手动禁用。 - 查看状态/健康信息：`openclaw status --all` 或 `openclaw status --deep`。 -通用渠道工作流参考请参阅[渠道](/channels)和[插件](/plugins)指南。 +有关通用渠道工作流参考，请参阅[渠道](/channels)和[插件](/plugins)指南。 diff --git a/docs/zh-CN/channels/discord.md b/docs/zh-CN/channels/discord.md index 727a5a29c2..2483a2c678 100644 --- a/docs/zh-CN/channels/discord.md +++ b/docs/zh-CN/channels/discord.md @@ -1,32 +1,32 @@ --- read_when: - - 开发 Discord 渠道功能 + - 开发 Discord 渠道功能时 summary: Discord 机器人支持状态、功能和配置 title: Discord x-i18n: - generated_at: "2026-02-01T19:19:25Z" + generated_at: "2026-02-03T07:45:45Z" model: claude-opus-4-5 provider: pi - source_hash: 44e44e855481a81557d9c205bacaa82efef528f8dba59a2c39c26aeb4f420c62 + source_hash: 2f0083b55648f9158668b80d078353421e7dc310135fdc43f2d280b242bf8459 source_path: channels/discord.md - workflow: 14 + workflow: 15 --- # Discord（Bot API） -状态：已可用于通过官方 Discord 机器人网关进行私信和服务器文字频道通信。 +状态：已支持通过官方 Discord 机器人网关进行私信和服务器文字频道通信。 ## 快速设置（新手） -1. 创建一个 Discord 机器人并复制机器人 token。 -2. 在 Discord 应用设置中，启用 **Message Content Intent**（如果你计划使用允许列表或名称查找，还需启用 **Server Members Intent**）。 -3. 为 OpenClaw 设置 token： +1. 创建 Discord 机器人并复制机器人令牌。 +2. 在 Discord 应用设置中启用 **Message Content Intent**（如果你计划使用允许列表或名称查找，还需启用 **Server Members Intent**）。 +3. 为 OpenClaw 设置令牌： - 环境变量：`DISCORD_BOT_TOKEN=...` - 或配置：`channels.discord.token: "..."`。 - - 如果两者都设置了，配置优先（环境变量回退仅用于默认账户）。 -4. 邀请机器人到你的服务器并赋予消息权限（如果只想用私信可以创建一个私人服务器）。 -5. 启动 Gateway网关。 -6. 私信访问默认需要配对；首次联系时批准配对码即可。 + - 如果两者都设置，配置优先（环境变量回退仅适用于默认账户）。 +4. 使用消息权限邀请机器人到你的服务器（如果你只想使用私信，可以创建一个私人服务器）。 +5. 启动 Gateway 网关。 +6. 私信访问默认采用配对模式；首次联系时需批准配对码。 最小配置： @@ -44,42 +44,42 @@ x-i18n: ## 目标 - 通过 Discord 私信或服务器频道与 OpenClaw 对话。 -- 私聊合并到智能体的主会话（默认 `agent:main:main`）；服务器频道作为 `agent::discord:channel:` 保持隔离（显示名称使用 `discord:#`）。 -- 群组私信默认被忽略；通过 `channels.discord.dm.groupEnabled` 启用，可选通过 `channels.discord.dm.groupChannels` 限制。 -- 保持路由确定性：回复始终发回消息到达的渠道。 +- 直接聊天会合并到智能体的主会话（默认 `agent:main:main`）；服务器频道保持隔离为 `agent::discord:channel:`（显示名称使用 `discord:#`）。 +- 群组私信默认被忽略；通过 `channels.discord.dm.groupEnabled` 启用，并可选择通过 `channels.discord.dm.groupChannels` 进行限制。 +- 保持路由确定性：回复始终返回到消息来源的渠道。 ## 工作原理 -1. 创建 Discord 应用 → Bot，启用所需的 intent（私信 + 服务器消息 + 消息内容），获取机器人 token。 -2. 邀请机器人到你的服务器，赋予在你需要使用的地方读取/发送消息所需的权限。 +1. 创建 Discord 应用程序 → Bot，启用你需要的意图（私信 + 服务器消息 + 消息内容），并获取机器人令牌。 +2. 使用所需权限邀请机器人到你的服务器，以便在你想使用的地方读取/发送消息。 3. 使用 `channels.discord.token` 配置 OpenClaw（或使用 `DISCORD_BOT_TOKEN` 作为回退）。 -4. 运行 Gateway网关；当 token 可用（配置优先，环境变量回退）且 `channels.discord.enabled` 不为 `false` 时，它会自动启动 Discord 渠道。 - - 如果你偏好使用环境变量，设置 `DISCORD_BOT_TOKEN`（配置块是可选的）。 -5. 私聊：投递时使用 `user:`（或 `<@id>` 提及）；所有回合都进入共享的 `main` 会话。裸数字 ID 具有歧义性，会被拒绝。 -6. 服务器频道：投递时使用 `channel:`。默认需要提及，可按服务器或按频道设置。 -7. 私聊：默认通过 `channels.discord.dm.policy`（默认：`"pairing"`）进行安全保护。未知发送者会收到配对码（1 小时后过期）；通过 `openclaw pairing approve discord ` 批准。 +4. 运行 Gateway 网关；当令牌可用（配置优先，环境变量回退）且 `channels.discord.enabled` 不为 `false` 时，它会自动启动 Discord 渠道。 + - 如果你更喜欢使用环境变量，设置 `DISCORD_BOT_TOKEN`（配置块是可选的）。 +5. 直接聊天：发送时使用 `user:`（或 `<@id>` 提及）；所有对话都进入共享的 `main` 会话。纯数字 ID 是模糊的，会被拒绝。 +6. 服务器频道：发送时使用 `channel:`。默认需要提及，可以按服务器或按频道设置。 +7. 直接聊天：默认通过 `channels.discord.dm.policy` 进行安全保护（默认：`"pairing"`）。未知发送者会收到配对码（1 小时后过期）；通过 `openclaw pairing approve discord ` 批准。 - 要保持旧的"对任何人开放"行为：设置 `channels.discord.dm.policy="open"` 和 `channels.discord.dm.allowFrom=["*"]`。 - - 要硬性限制允许列表：设置 `channels.discord.dm.policy="allowlist"` 并在 `channels.discord.dm.allowFrom` 中列出发送者。 + - 要使用硬编码允许列表：设置 `channels.discord.dm.policy="allowlist"` 并在 `channels.discord.dm.allowFrom` 中列出发送者。 - 要忽略所有私信：设置 `channels.discord.dm.enabled=false` 或 `channels.discord.dm.policy="disabled"`。 -8. 群组私信默认被忽略；通过 `channels.discord.dm.groupEnabled` 启用，可选通过 `channels.discord.dm.groupChannels` 限制。 -9. 可选的服务器规则：设置 `channels.discord.guilds`，以服务器 ID（推荐）或 slug 为键，包含按频道的规则。 -10. 可选的原生命令：`commands.native` 默认为 `"auto"`（Discord/Telegram 开启，Slack 关闭）。通过 `channels.discord.commands.native: true|false|"auto"` 覆盖；`false` 会清除之前注册的命令。文本命令由 `commands.text` 控制，必须作为独立的 `/...` 消息发送。使用 `commands.useAccessGroups: false` 可绕过命令的访问组检查。 +8. 群组私信默认被忽略；通过 `channels.discord.dm.groupEnabled` 启用，并可选择通过 `channels.discord.dm.groupChannels` 进行限制。 +9. 可选服务器规则：设置 `channels.discord.guilds`，以服务器 ID（首选）或 slug 为键，并包含每个频道的规则。 +10. 可选原生命令：`commands.native` 默认为 `"auto"`（Discord/Telegram 开启，Slack 关闭）。使用 `channels.discord.commands.native: true|false|"auto"` 覆盖；`false` 会清除之前注册的命令。文本命令由 `commands.text` 控制，必须作为独立的 `/...` 消息发送。使用 `commands.useAccessGroups: false` 可跳过命令的访问组检查。 - 完整命令列表 + 配置：[斜杠命令](/tools/slash-commands) -11. 可选的服务器上下文历史：设置 `channels.discord.historyLimit`（默认 20，回退到 `messages.groupChat.historyLimit`）以在回复提及时包含最近 N 条服务器消息作为上下文。设置 `0` 可禁用。 -12. 回应：智能体可以通过 `discord` 工具触发回应（由 `channels.discord.actions.*` 控制）。 - - 回应移除语义：参见 [/tools/reactions](/tools/reactions)。 - - `discord` 工具仅在当前渠道为 Discord 时暴露。 -13. 原生命令使用隔离的会话键（`agent::discord:slash:`）而非共享的 `main` 会话。 +11. 可选服务器上下文历史：设置 `channels.discord.historyLimit`（默认 20，回退到 `messages.groupChat.historyLimit`）以在回复提及时包含最近 N 条服务器消息作为上下文。设置 `0` 禁用。 +12. 表情反应：智能体可以通过 `discord` 工具触发表情反应（受 `channels.discord.actions.*` 控制）。 + - 表情反应移除语义：参见 [/tools/reactions](/tools/reactions)。 + - `discord` 工具仅在当前渠道是 Discord 时暴露。 +13. 原生命令使用隔离的会话键（`agent::discord:slash:`）而不是共享的 `main` 会话。 注意：名称 → ID 解析使用服务器成员搜索，需要 Server Members Intent；如果机器人无法搜索成员，请使用 ID 或 `<@id>` 提及。 -注意：Slug 为小写且空格替换为 `-`。频道名称的 slug 不包含前导 `#`。 -注意：服务器上下文 `[from:]` 行包含 `author.tag` + `id`，方便进行可直接 ping 的回复。 +注意：Slug 为小写，空格替换为 `-`。频道名称的 slug 不包含前导 `#`。 +注意：服务器上下文 `[from:]` 行包含 `author.tag` + `id`，便于进行可提及的回复。 ## 配置写入 -默认情况下，Discord 允许通过 `/config set|unset` 触发的配置更新写入（需要 `commands.config: true`）。 +默认情况下，允许 Discord 写入由 `/config set|unset` 触发的配置更新（需要 `commands.config: true`）。 -通过以下方式禁用： +禁用方式： ```json5 { @@ -91,32 +91,32 @@ x-i18n: 这是在服务器（guild）频道（如 `#help`）中运行 OpenClaw 的"Discord 开发者门户"设置。 -### 1) 创建 Discord 应用 + 机器人用户 +### 1）创建 Discord 应用 + 机器人用户 1. Discord 开发者门户 → **Applications** → **New Application** 2. 在你的应用中： - **Bot** → **Add Bot** - - 复制 **Bot Token**（这就是你放入 `DISCORD_BOT_TOKEN` 的值） + - 复制 **Bot Token**（这是你放入 `DISCORD_BOT_TOKEN` 的内容） -### 2) 启用 OpenClaw 所需的网关 intent +### 2）启用 OpenClaw 需要的网关意图 -Discord 会阻止"特权 intent"，除非你明确启用。 +Discord 会阻止"特权意图"，除非你明确启用它们。 -在 **Bot** → **Privileged Gateway Intents** 中，启用： +在 **Bot** → **Privileged Gateway Intents** 中启用： - **Message Content Intent**（在大多数服务器中读取消息文本所必需；没有它你会看到"Used disallowed intents"或机器人会连接但不响应消息） -- **Server Members Intent**（推荐；某些成员/用户查找和服务器中的允许列表匹配所必需） +- **Server Members Intent**（推荐；服务器中的某些成员/用户查找和允许列表匹配需要） -通常你**不**需要 **Presence Intent**。 +你通常**不需要** **Presence Intent**。 -### 3) 生成邀请 URL（OAuth2 URL 生成器） +### 3）生成邀请 URL（OAuth2 URL Generator） 在你的应用中：**OAuth2** → **URL Generator** **Scopes** - ✅ `bot` -- ✅ `applications.commands`（原生命令所必需） +- ✅ `applications.commands`（原生命令所需） **Bot Permissions**（最小基线） @@ -126,27 +126,27 @@ Discord 会阻止"特权 intent"，除非你明确启用。 - ✅ Embed Links - ✅ Attach Files - ✅ Add Reactions（可选但推荐） -- ✅ Use External Emojis / Stickers（可选；仅在你需要时） +- ✅ Use External Emojis / Stickers（可选；仅当你需要时） -除非你在调试且完全信任机器人，否则避免使用 **Administrator**。 +除非你在调试并完全信任机器人，否则避免使用 **Administrator**。 -复制生成的 URL，打开它，选择你的服务器，安装机器人。 +复制生成的 URL，打开它，选择你的服务器，然后安装机器人。 -### 4) 获取 ID（服务器/用户/频道） +### 4）获取 ID（服务器/用户/频道） -Discord 到处使用数字 ID；OpenClaw 配置推荐使用 ID。 +Discord 到处使用数字 ID；OpenClaw 配置优先使用 ID。 1. Discord（桌面/网页）→ **用户设置** → **高级** → 启用 **开发者模式** 2. 右键点击： - - 服务器名称 → **复制服务器 ID**（guild id） + - 服务器名称 → **复制服务器 ID**（服务器 ID） - 频道（例如 `#help`）→ **复制频道 ID** - 你的用户 → **复制用户 ID** -### 5) 配置 OpenClaw +### 5）配置 OpenClaw -#### Token +#### 令牌 -通过环境变量设置机器人 token（推荐用于服务器）： +通过环境变量设置机器人令牌（服务器上推荐）： - `DISCORD_BOT_TOKEN=...` @@ -163,7 +163,7 @@ Discord 到处使用数字 ID；OpenClaw 配置推荐使用 ID。 } ``` -多账户支持：使用 `channels.discord.accounts`，每个账户配置独立的 token 和可选的 `name`。共享模式请参阅 [`gateway/configuration`](/gateway/configuration#telegramaccounts--discordaccounts--slackaccounts--signalaccounts--imessageaccounts)。 +多账户支持：使用 `channels.discord.accounts`，每个账户有自己的令牌和可选的 `name`。参见 [`gateway/configuration`](/gateway/configuration#telegramaccounts--discordaccounts--slackaccounts--signalaccounts--imessageaccounts) 了解通用模式。 #### 允许列表 + 频道路由 @@ -195,52 +195,57 @@ Discord 到处使用数字 ID；OpenClaw 配置推荐使用 ID。 } ``` -注意事项： +注意： -- `requireMention: true` 表示机器人仅在被提及时回复（推荐用于共享频道）。 -- `agents.list[].groupChat.mentionPatterns`（或 `messages.groupChat.mentionPatterns`）对服务器消息也算作提及。 +- `requireMention: true` 意味着机器人只在被提及时回复（推荐用于共享频道）。 +- `agents.list[].groupChat.mentionPatterns`（或 `messages.groupChat.mentionPatterns`）对于服务器消息也算作提及。 - 多智能体覆盖：在 `agents.list[].groupChat.mentionPatterns` 上设置每个智能体的模式。 - 如果存在 `channels`，任何未列出的频道默认被拒绝。 -- 使用 `"*"` 频道条目来应用所有频道的默认值；明确的频道条目会覆盖通配符。 -- 帖子继承父频道配置（允许列表、`requireMention`、Skills、提示等），除非你明确添加帖子频道 ID。 -- 机器人发送的消息默认被忽略；设置 `channels.discord.allowBots=true` 可允许它们（自己的消息仍然被过滤）。 -- 警告：如果你允许回复其他机器人（`channels.discord.allowBots=true`），请使用 `requireMention`、`channels.discord.guilds.*.channels..users` 允许列表和/或在 `AGENTS.md` 和 `SOUL.md` 中设置明确的防护规则来防止机器人之间的回复循环。 +- 使用 `"*"` 频道条目在所有频道应用默认值；显式频道条目覆盖通配符。 +- 话题继承父频道配置（允许列表、`requireMention`、Skills、提示词等），除非你显式添加话题频道 ID。 +- 机器人发送的消息默认被忽略；设置 `channels.discord.allowBots=true` 允许它们（自己的消息仍被过滤）。 +- 警告：如果你允许回复其他机器人（`channels.discord.allowBots=true`），请使用 `requireMention`、`channels.discord.guilds.*.channels..users` 允许列表和/或在 `AGENTS.md` 和 `SOUL.md` 中设置明确的防护措施来防止机器人之间的回复循环。 -### 6) 验证是否正常工作 +### 6）验证是否工作 -1. 启动 Gateway网关。 -2. 在你的服务器频道中，发送：`@Krill hello`（或你的机器人名称）。 -3. 如果没有响应：查看下方**故障排除**。 +1. 启动 Gateway 网关。 +2. 在你的服务器频道中发送：`@Krill hello`（或你的机器人名称）。 +3. 如果没有反应：查看下面的**故障排除**。 ### 故障排除 - 首先：运行 `openclaw doctor` 和 `openclaw channels status --probe`（可操作的警告 + 快速审计）。 -- **"Used disallowed intents"**：在开发者门户中启用 **Message Content Intent**（以及可能的 **Server Members Intent**），然后重启 Gateway网关。 -- **机器人连接但在服务器频道中从不回复**： +- **"Used disallowed intents"**：在开发者门户中启用 **Message Content Intent**（可能还需要 **Server Members Intent**），然后重启 Gateway 网关。 +- **机器人连接但从不在服务器频道回复**： - 缺少 **Message Content Intent**，或 - 机器人缺少频道权限（View/Send/Read History），或 - - 你的配置要求提及但你没有提及它，或 + - 你的配置需要提及但你没有提及它，或 - 你的服务器/频道允许列表拒绝了该频道/用户。 - **`requireMention: false` 但仍然没有回复**： -- `channels.discord.groupPolicy` 默认为 **allowlist**；将其设置为 `"open"` 或在 `channels.discord.guilds` 下添加服务器条目（可选在 `channels.discord.guilds..channels` 下列出频道以进行限制）。 - - 如果你只设置了 `DISCORD_BOT_TOKEN` 且从未创建 `channels.discord` 部分，运行时默认将 `groupPolicy` 设为 `open`。添加 `channels.discord.groupPolicy`、`channels.defaults.groupPolicy` 或服务器/频道允许列表来锁定它。 +- `channels.discord.groupPolicy` 默认为 **allowlist**；将其设置为 `"open"` 或在 `channels.discord.guilds` 下添加服务器条目（可选择在 `channels.discord.guilds..channels` 下列出频道以进行限制）。 + - 如果你只设置了 `DISCORD_BOT_TOKEN` 而从未创建 `channels.discord` 部分，运行时会将 `groupPolicy` 默认为 `open`。添加 `channels.discord.groupPolicy`、`channels.defaults.groupPolicy` 或服务器/频道允许列表来锁定它。 - `requireMention` 必须位于 `channels.discord.guilds`（或特定频道）下。顶层的 `channels.discord.requireMention` 会被忽略。 -- **权限审计**（`channels status --probe`）仅检查数字频道 ID。如果你使用 slug/名称作为 `channels.discord.guilds.*.channels` 的键，审计无法验证权限。 -- **私信不工作**：`channels.discord.dm.enabled=false`、`channels.discord.dm.policy="disabled"`，或你尚未被批准（`channels.discord.dm.policy="pairing"`）。 +- **权限审计**（`channels status --probe`）只检查数字频道 ID。如果你使用 slug/名称作为 `channels.discord.guilds.*.channels` 键，审计无法验证权限。 +- **私信不工作**：`channels.discord.dm.enabled=false`、`channels.discord.dm.policy="disabled"`，或者你尚未被批准（`channels.discord.dm.policy="pairing"`）。 +- **Discord 中的执行审批**：Discord 支持私信中执行审批的**按钮 UI**（允许一次 / 始终允许 / 拒绝）。`/approve ...` 仅用于转发的审批，不会解析 Discord 的按钮提示。如果你看到 `❌ Failed to submit approval: Error: unknown approval id` 或 UI 从未出现，请检查： + - 你的配置中有 `channels.discord.execApprovals.enabled: true`。 + - 你的 Discord 用户 ID 在 `channels.discord.execApprovals.approvers` 中列出（UI 仅发送给审批者）。 + - 使用私信提示中的按钮（**Allow once**、**Always allow**、**Deny**）。 + - 参见[执行审批](/tools/exec-approvals)和[斜杠命令](/tools/slash-commands)了解更广泛的审批和命令流程。 -## 功能与限制 +## 功能和限制 -- 私信和服务器文字频道（帖子被视为独立频道；不支持语音）。 -- 输入指示尽力发送；消息分块使用 `channels.discord.textChunkLimit`（默认 2000）并按行数分割较长回复（`channels.discord.maxLinesPerMessage`，默认 17）。 -- 可选的换行分块：设置 `channels.discord.chunkMode="newline"` 在按长度分块之前按空行（段落边界）分割。 -- 支持文件上传，上限为配置的 `channels.discord.mediaMaxMb`（默认 8 MB）。 -- 服务器回复默认需要提及门控，以避免嘈杂的机器人。 +- 支持私信和服务器文字频道（话题被视为独立频道；不支持语音）。 +- 打字指示器尽力发送；消息分块使用 `channels.discord.textChunkLimit`（默认 2000），并按行数分割长回复（`channels.discord.maxLinesPerMessage`，默认 17）。 +- 可选换行分块：设置 `channels.discord.chunkMode="newline"` 以在空行（段落边界）处分割，然后再进行长度分块。 +- 支持文件上传，最大 `channels.discord.mediaMaxMb`（默认 8 MB）。 +- 默认服务器回复需要提及，以避免嘈杂的机器人。 - 当消息引用另一条消息时，会注入回复上下文（引用内容 + ID）。 -- 原生回复线程**默认关闭**；通过 `channels.discord.replyToMode` 和回复标签启用。 +- 原生回复线程**默认关闭**；使用 `channels.discord.replyToMode` 和回复标签启用。 ## 重试策略 -出站 Discord API 调用在速率限制（429）时使用 Discord 的 `retry_after`（如可用）进行重试，采用指数退避和抖动。通过 `channels.discord.retry` 配置。参见[重试策略](/concepts/retry)。 +出站 Discord API 调用在速率限制（429）时使用 Discord `retry_after`（如果可用）进行重试，采用指数退避和抖动。通过 `channels.discord.retry` 配置。参见[重试策略](/concepts/retry)。 ## 配置 @@ -311,57 +316,58 @@ Discord 到处使用数字 ID；OpenClaw 配置推荐使用 ID。 } ``` -确认回应由 `messages.ackReaction` + `messages.ackReactionScope` 全局控制。使用 `messages.removeAckAfterReply` 在机器人回复后清除确认回应。 +确认表情反应通过 `messages.ackReaction` + `messages.ackReactionScope` 全局控制。使用 `messages.removeAckAfterReply` 在机器人回复后清除确认表情反应。 -- `dm.enabled`：设置 `false` 可忽略所有私信（默认 `true`）。 +- `dm.enabled`：设置 `false` 忽略所有私信（默认 `true`）。 - `dm.policy`：私信访问控制（推荐 `pairing`）。`"open"` 需要 `dm.allowFrom=["*"]`。 -- `dm.allowFrom`：私信允许列表（用户 ID 或名称）。用于 `dm.policy="allowlist"` 和 `dm.policy="open"` 验证。向导接受用户名并在机器人可以搜索成员时将其解析为 ID。 +- `dm.allowFrom`：私信允许列表（用户 ID 或名称）。用于 `dm.policy="allowlist"` 和 `dm.policy="open"` 验证。向导接受用户名，并在机器人可以搜索成员时将其解析为 ID。 - `dm.groupEnabled`：启用群组私信（默认 `false`）。 - `dm.groupChannels`：群组私信频道 ID 或 slug 的可选允许列表。 -- `groupPolicy`：控制服务器频道处理方式（`open|disabled|allowlist`）；`allowlist` 需要频道允许列表。 -- `guilds`：按服务器 ID（推荐）或 slug 为键的按服务器规则。 -- `guilds."*"`：当没有明确条目时应用的默认按服务器设置。 +- `groupPolicy`：控制服务器频道处理（`open|disabled|allowlist`）；`allowlist` 需要频道允许列表。 +- `guilds`：按服务器规则，以服务器 ID（首选）或 slug 为键。 +- `guilds."*"`：当没有显式条目时应用的默认每服务器设置。 - `guilds..slug`：用于显示名称的可选友好 slug。 -- `guilds..users`：可选的按服务器用户允许列表（ID 或名称）。 -- `guilds..tools`：可选的按服务器工具策略覆盖（`allow`/`deny`/`alsoAllow`），在频道覆盖缺失时使用。 -- `guilds..toolsBySender`：可选的按发送者工具策略覆盖（服务器级别，在频道覆盖缺失时应用；支持 `"*"` 通配符）。 +- `guilds..users`：可选的每服务器用户允许列表（ID 或名称）。 +- `guilds..tools`：可选的每服务器工具策略覆盖（`allow`/`deny`/`alsoAllow`），在频道覆盖缺失时使用。 +- `guilds..toolsBySender`：服务器级别的可选每发送者工具策略覆盖（在频道覆盖缺失时应用；支持 `"*"` 通配符）。 - `guilds..channels..allow`：当 `groupPolicy="allowlist"` 时允许/拒绝频道。 -- `guilds..channels..requireMention`：频道的提及门控。 -- `guilds..channels..tools`：可选的按频道工具策略覆盖（`allow`/`deny`/`alsoAllow`）。 -- `guilds..channels..toolsBySender`：可选的频道内按发送者工具策略覆盖（支持 `"*"` 通配符）。 -- `guilds..channels..users`：可选的按频道用户允许列表。 +- `guilds..channels..requireMention`：频道的提及限制。 +- `guilds..channels..tools`：可选的每频道工具策略覆盖（`allow`/`deny`/`alsoAllow`）。 +- `guilds..channels..toolsBySender`：频道内的可选每发送者工具策略覆盖（支持 `"*"` 通配符）。 +- `guilds..channels..users`：可选的每频道用户允许列表。 - `guilds..channels..skills`：Skills 过滤器（省略 = 所有 Skills，空 = 无）。 -- `guilds..channels..systemPrompt`：频道的额外系统提示（与频道主题合并）。 -- `guilds..channels..enabled`：设置 `false` 可禁用频道。 +- `guilds..channels..systemPrompt`：频道的额外系统提示词（与频道主题组合）。 +- `guilds..channels..enabled`：设置 `false` 禁用频道。 - `guilds..channels`：频道规则（键为频道 slug 或 ID）。 -- `guilds..requireMention`：按服务器的提及要求（可按频道覆盖）。 -- `guilds..reactionNotifications`：回应系统事件模式（`off`、`own`、`all`、`allowlist`）。 -- `textChunkLimit`：出站文本分块大小（字符）。默认：2000。 -- `chunkMode`：`length`（默认）仅在超过 `textChunkLimit` 时分割；`newline` 在按长度分块之前按空行（段落边界）分割。 +- `guilds..requireMention`：每服务器提及要求（可按频道覆盖）。 +- `guilds..reactionNotifications`：表情反应系统事件模式（`off`、`own`、`all`、`allowlist`）。 +- `textChunkLimit`：出站文本块大小（字符）。默认：2000。 +- `chunkMode`：`length`（默认）仅在超过 `textChunkLimit` 时分割；`newline` 在空行（段落边界）处分割，然后再进行长度分块。 - `maxLinesPerMessage`：每条消息的软最大行数。默认：17。 - `mediaMaxMb`：限制保存到磁盘的入站媒体大小。 -- `historyLimit`：回复提及时包含的最近服务器消息数作为上下文（默认 20；回退到 `messages.groupChat.historyLimit`；`0` 禁用）。 -- `dmHistoryLimit`：私信历史限制（用户回合数）。按用户覆盖：`dms[""].historyLimit`。 +- `historyLimit`：回复提及时作为上下文包含的最近服务器消息数量（默认 20；回退到 `messages.groupChat.historyLimit`；`0` 禁用）。 +- `dmHistoryLimit`：私信历史限制（用户轮次）。每用户覆盖：`dms[""].historyLimit`。 - `retry`：出站 Discord API 调用的重试策略（attempts、minDelayMs、maxDelayMs、jitter）。 - `pluralkit`：解析 PluralKit 代理消息，使系统成员显示为不同的发送者。 -- `actions`：按操作的工具门控；省略则允许所有（设置 `false` 可禁用）。 - - `reactions`（涵盖添加回应 + 读取回应） +- `actions`：每操作工具门控；省略允许所有（设置 `false` 禁用）。 + - `reactions`（涵盖表情反应 + 读取表情反应） - `stickers`、`emojiUploads`、`stickerUploads`、`polls`、`permissions`、`messages`、`threads`、`pins`、`search` - `memberInfo`、`roleInfo`、`channelInfo`、`voiceStatus`、`events` - - `channels`（创建/编辑/删除频道 + 分类 + 权限） + - `channels`（创建/编辑/删除频道 + 类别 + 权限） - `roles`（角色添加/移除，默认 `false`） - `moderation`（超时/踢出/封禁，默认 `false`） +- `execApprovals`：Discord 专用执行审批私信（按钮 UI）。支持 `enabled`、`approvers`、`agentFilter`、`sessionFilter`。 -回应通知使用 `guilds..reactionNotifications`： +表情反应通知使用 `guilds..reactionNotifications`： -- `off`：无回应事件。 -- `own`：机器人自己消息上的回应（默认）。 -- `all`：所有消息上的所有回应。 -- `allowlist`：来自 `guilds..users` 的用户在所有消息上的回应（空列表则禁用）。 +- `off`：无表情反应事件。 +- `own`：机器人自己消息上的表情反应（默认）。 +- `all`：所有消息上的所有表情反应。 +- `allowlist`：来自 `guilds..users` 的用户在所有消息上的表情反应（空列表禁用）。 ### PluralKit（PK）支持 -启用 PK 查找，使代理消息解析为底层的系统 + 成员。启用后，OpenClaw 使用成员身份进行允许列表匹配，并将发送者标记为 `Member (PK:System)` 以避免意外的 Discord ping。 +启用 PK 查找，以便代理消息解析到底层系统 + 成员。启用后，OpenClaw 使用成员身份进行允许列表匹配，并将发送者标记为 `Member (PK:System)` 以避免意外的 Discord 提及。 ```json5 { @@ -378,86 +384,85 @@ Discord 到处使用数字 ID；OpenClaw 配置推荐使用 ID。 允许列表注意事项（启用 PK 时）： -- 在 `dm.allowFrom`、`guilds..users` 或按频道的 `users` 中使用 `pk:`。 -- 成员显示名称也通过名称/slug 匹配。 -- 查找使用**原始** Discord 消息 ID（代理前的消息），因此 PK API 仅在其 30 分钟窗口内解析它。 -- 如果 PK 查找失败（例如没有 token 的私有系统），代理消息被视为机器人消息并被丢弃，除非设置 `channels.discord.allowBots=true`。 +- 在 `dm.allowFrom`、`guilds..users` 或每频道 `users` 中使用 `pk:`。 +- 成员显示名称也按名称/slug 匹配。 +- 查找使用**原始** Discord 消息 ID（代理前的消息），因此 PK API 只在其 30 分钟窗口内解析它。 +- 如果 PK 查找失败（例如，没有令牌的私有系统），代理消息会被视为机器人消息并被丢弃，除非 `channels.discord.allowBots=true`。 ### 工具操作默认值 -| 操作组 | 默认值 | 说明 | -| -------------- | ------ | ------------------------------- | -| reactions | 启用 | 添加回应 + 列出回应 + emojiList | -| stickers | 启用 | 发送贴纸 | -| emojiUploads | 启用 | 上传表情 | -| stickerUploads | 启用 | 上传贴纸 | -| polls | 启用 | 创建投票 | -| permissions | 启用 | 频道权限快照 | -| messages | 启用 | 读取/发送/编辑/删除 | -| threads | 启用 | 创建/列出/回复 | -| pins | 启用 | 置顶/取消置顶/列出 | -| search | 启用 | 消息搜索（预览功能） | -| memberInfo | 启用 | 成员信息 | -| roleInfo | 启用 | 角色列表 | -| channelInfo | 启用 | 频道信息 + 列表 | -| channels | 启用 | 频道/分类管理 | -| voiceStatus | 启用 | 语音状态查询 | -| events | 启用 | 列出/创建计划事件 | -| roles | 禁用 | 角色添加/移除 | -| moderation | 禁用 | 超时/踢出/封禁 | +| 操作组 | 默认 | 说明 | +| -------------- | ---- | ----------------------------------- | +| reactions | 启用 | 表情反应 + 列出表情反应 + emojiList | +| stickers | 启用 | 发送贴纸 | +| emojiUploads | 启用 | 上传表情 | +| stickerUploads | 启用 | 上传贴纸 | +| polls | 启用 | 创建投票 | +| permissions | 启用 | 频道权限快照 | +| messages | 启用 | 读取/发送/编辑/删除 | +| threads | 启用 | 创建/列出/回复 | +| pins | 启用 | 置顶/取消置顶/列出 | +| search | 启用 | 消息搜索（预览功能） | +| memberInfo | 启用 | 成员信息 | +| roleInfo | 启用 | 角色列表 | +| channelInfo | 启用 | 频道信息 + 列表 | +| channels | 启用 | 频道/类别管理 | +| voiceStatus | 启用 | 语音状态查询 | +| events | 启用 | 列出/创建预定事件 | +| roles | 禁用 | 角色添加/移除 | +| moderation | 禁用 | 超时/踢出/封禁 | -- `replyToMode`：`off`（默认）、`first` 或 `all`。仅在模型输出包含回复标签时生效。 +- `replyToMode`：`off`（默认）、`first` 或 `all`。仅在模型包含回复标签时适用。 ## 回复标签 -要请求线程回复，模型可以在输出中包含一个标签： +要请求线程回复，模型可以在其输出中包含一个标签： - `[[reply_to_current]]` — 回复触发的 Discord 消息。 -- `[[reply_to:]]` — 回复上下文/历史中的特定消息 ID。 - 当前消息 ID 以 `[message_id: …]` 附加到提示中；历史条目已包含 ID。 +- `[[reply_to:]]` — 回复上下文/历史中的特定消息 ID。当前消息 ID 作为 `[message_id: …]` 附加到提示词；历史条目已包含 ID。 行为由 `channels.discord.replyToMode` 控制： - `off`：忽略标签。 -- `first`：仅第一个出站分块/附件作为回复。 -- `all`：每个出站分块/附件都作为回复。 +- `first`：只有第一个出站块/附件是回复。 +- `all`：每个出站块/附件都是回复。 允许列表匹配注意事项： -- `allowFrom`/`users`/`groupChannels` 接受 ID、名称、标签或 `<@id>` 格式的提及。 +- `allowFrom`/`users`/`groupChannels` 接受 ID、名称、标签或像 `<@id>` 这样的提及。 - 支持 `discord:`/`user:`（用户）和 `channel:`（群组私信）等前缀。 - 使用 `*` 允许任何发送者/频道。 - 当存在 `guilds..channels` 时，未列出的频道默认被拒绝。 - 当省略 `guilds..channels` 时，允许列表中服务器的所有频道都被允许。 -- 要**不允许任何频道**，设置 `channels.discord.groupPolicy: "disabled"`（或保持空的允许列表）。 -- 配置向导接受 `Guild/Channel` 名称（公共 + 私有）并在可能时将其解析为 ID。 +- 要**不允许任何频道**，设置 `channels.discord.groupPolicy: "disabled"`（或保持空允许列表）。 +- 配置向导接受 `Guild/Channel` 名称（公开 + 私有）并在可能时将其解析为 ID。 - 启动时，OpenClaw 将允许列表中的频道/用户名称解析为 ID（当机器人可以搜索成员时）并记录映射；未解析的条目保持原样。 原生命令注意事项： -- 注册的命令与 OpenClaw 的聊天命令一致。 -- 原生命令遵循与私信/服务器消息相同的允许列表（`channels.discord.dm.allowFrom`、`channels.discord.guilds`、按频道规则）。 -- 斜杠命令在 Discord UI 中可能对不在允许列表中的用户仍然可见；OpenClaw 在执行时强制执行允许列表并回复"未授权"。 +- 注册的命令镜像 OpenClaw 的聊天命令。 +- 原生命令遵循与私信/服务器消息相同的允许列表（`channels.discord.dm.allowFrom`、`channels.discord.guilds`、每频道规则）。 +- 斜杠命令可能在 Discord UI 中对未在允许列表中的用户仍然可见；OpenClaw 在执行时强制执行允许列表并回复"未授权"。 ## 工具操作 -智能体可以调用 `discord` 执行以下操作： +智能体可以使用以下操作调用 `discord`： -- `react` / `reactions`（添加或列出回应） +- `react` / `reactions`（添加或列出表情反应） - `sticker`、`poll`、`permissions` - `readMessages`、`sendMessage`、`editMessage`、`deleteMessage` -- 读取/搜索/置顶工具的负载包含标准化的 `timestampMs`（UTC 纪元毫秒）和 `timestampUtc`，同时保留原始 Discord `timestamp`。 +- 读取/搜索/置顶工具负载包含规范化的 `timestampMs`（UTC 纪元毫秒）和 `timestampUtc` 以及原始 Discord `timestamp`。 - `threadCreate`、`threadList`、`threadReply` - `pinMessage`、`unpinMessage`、`listPins` - `searchMessages`、`memberInfo`、`roleInfo`、`roleAdd`、`roleRemove`、`emojiList` - `channelInfo`、`channelList`、`voiceStatus`、`eventList`、`eventCreate` - `timeout`、`kick`、`ban` -Discord 消息 ID 在注入的上下文中呈现（`[discord message id: …]` 和历史行），方便智能体定位它们。 +Discord 消息 ID 在注入的上下文中显示（`[discord message id: …]` 和历史行），以便智能体可以定位它们。 表情可以是 unicode（例如 `✅`）或自定义表情语法如 `<:party_blob:1234567890>`。 ## 安全与运维 -- 将机器人 token 视为密码；在受管主机上推荐使用 `DISCORD_BOT_TOKEN` 环境变量或锁定配置文件权限。 -- 仅授予机器人所需的权限（通常是读取/发送消息）。 -- 如果机器人卡住或被速率限制，在确认没有其他进程占用 Discord 会话后重启 Gateway网关（`openclaw gateway --force`）。 +- 像对待密码一样对待机器人令牌；在受监督的主机上优先使用 `DISCORD_BOT_TOKEN` 环境变量，或锁定配置文件权限。 +- 只授予机器人所需的权限（通常是读取/发送消息）。 +- 如果机器人卡住或受到速率限制，在确认没有其他进程拥有 Discord 会话后重启 Gateway 网关（`openclaw gateway --force`）。 diff --git a/docs/zh-CN/channels/googlechat.md b/docs/zh-CN/channels/googlechat.md index c83d751225..0a515bd777 100644 --- a/docs/zh-CN/channels/googlechat.md +++ b/docs/zh-CN/channels/googlechat.md @@ -1,38 +1,38 @@ --- read_when: - - 开发 Google Chat 渠道功能 + - 开发 Google Chat 渠道功能时 summary: Google Chat 应用支持状态、功能和配置 title: Google Chat x-i18n: - generated_at: "2026-02-01T19:20:03Z" + generated_at: "2026-02-03T07:43:39Z" model: claude-opus-4-5 provider: pi source_hash: 3b2bb116cdd12614c3d5afddd0879e9deb05c3606e3a2385cbc07f23552b357e source_path: channels/googlechat.md - workflow: 14 + workflow: 15 --- # Google Chat（Chat API） -状态：已可通过 Google Chat API webhook（仅 HTTP）用于私信和空间。 +状态：已支持通过 Google Chat API webhooks（仅 HTTP）使用私信和空间。 ## 快速设置（新手） 1. 创建一个 Google Cloud 项目并启用 **Google Chat API**。 - - 前往：[Google Chat API 凭据](https://console.cloud.google.com/apis/api/chat.googleapis.com/credentials) - - 如果尚未启用，请启用该 API。 -2. 创建**服务账户**： + - 前往：[Google Chat API Credentials](https://console.cloud.google.com/apis/api/chat.googleapis.com/credentials) + - 如果 API 尚未启用，请启用它。 +2. 创建一个**服务账号**： - 点击 **Create Credentials** > **Service Account**。 - 随意命名（例如 `openclaw-chat`）。 - 权限留空（点击 **Continue**）。 - - 有权访问的主体留空（点击 **Done**）。 + - 有访问权限的主账号留空（点击 **Done**）。 3. 创建并下载 **JSON 密钥**： - - 在服务账户列表中，点击你刚创建的那个。 - - 进入 **Keys** 标签页。 + - 在服务账号列表中，点击刚刚创建的账号。 + - 前往 **Keys** 标签页。 - 点击 **Add Key** > **Create new key**。 - 选择 **JSON** 并点击 **Create**。 -4. 将下载的 JSON 文件存储在你的 Gateway网关主机上（例如 `~/.openclaw/googlechat-service-account.json`）。 -5. 在 [Google Cloud Console Chat 配置](https://console.cloud.google.com/apis/api/chat.googleapis.com/hangouts-chat) 中创建 Google Chat 应用： +4. 将下载的 JSON 文件存储在 Gateway 网关主机上（例如 `~/.openclaw/googlechat-service-account.json`）。 +5. 在 [Google Cloud Console Chat Configuration](https://console.cloud.google.com/apis/api/chat.googleapis.com/hangouts-chat) 中创建一个 Google Chat 应用： - 填写 **Application info**： - **App name**：（例如 `OpenClaw`） - **Avatar URL**：（例如 `https://openclaw.ai/logo.png`） @@ -40,49 +40,49 @@ x-i18n: - 启用 **Interactive features**。 - 在 **Functionality** 下，勾选 **Join spaces and group conversations**。 - 在 **Connection settings** 下，选择 **HTTP endpoint URL**。 - - 在 **Triggers** 下，选择 **Use a common HTTP endpoint URL for all triggers** 并将其设置为你的 Gateway网关公共 URL 后跟 `/googlechat`。 - - _提示：运行 `openclaw status` 可查找你的 Gateway网关公共 URL。_ + - 在 **Triggers** 下，选择 **Use a common HTTP endpoint URL for all triggers** 并将其设置为你的 Gateway 网关公网 URL 后加 `/googlechat`。 + - _提示：运行 `openclaw status` 查看你的 Gateway 网关公网 URL。_ - 在 **Visibility** 下，勾选 **Make this Chat app available to specific people and groups in <Your Domain>**。 - 在文本框中输入你的邮箱地址（例如 `user@example.com`）。 - 点击底部的 **Save**。 6. **启用应用状态**： - 保存后，**刷新页面**。 - - 查找 **App status** 部分（通常在保存后位于顶部或底部附近）。 + - 找到 **App status** 部分（通常在保存后位于顶部或底部附近）。 - 将状态更改为 **Live - available to users**。 - 再次点击 **Save**。 -7. 使用服务账户路径 + webhook audience 配置 OpenClaw： +7. 使用服务账号路径和 webhook audience 配置 OpenClaw： - 环境变量：`GOOGLE_CHAT_SERVICE_ACCOUNT_FILE=/path/to/service-account.json` - 或配置：`channels.googlechat.serviceAccountFile: "/path/to/service-account.json"`。 -8. 设置 webhook audience 类型 + 值（与你的 Chat 应用配置匹配）。 -9. 启动 Gateway网关。Google Chat 将向你的 webhook 路径发送 POST 请求。 +8. 设置 webhook audience 类型和值（与你的 Chat 应用配置匹配）。 +9. 启动 Gateway 网关。Google Chat 将向你的 webhook 路径发送 POST 请求。 ## 添加到 Google Chat -Gateway网关运行且你的邮箱已添加到可见性列表后： +Gateway 网关运行后，且你的邮箱已添加到可见性列表中： 1. 前往 [Google Chat](https://chat.google.com/)。 2. 点击 **Direct Messages** 旁边的 **+**（加号）图标。 -3. 在搜索栏中（通常用于添加人员的地方），输入你在 Google Cloud Console 中配置的 **App name**。 - - **注意**：机器人*不会*出现在"Marketplace"浏览列表中，因为它是私有应用。你必须按名称搜索。 +3. 在搜索栏（通常用于添加联系人的位置）中，输入你在 Google Cloud Console 中配置的 **App name**。 + - **注意**：该机器人*不会*出现在"Marketplace"浏览列表中，因为它是私有应用。你必须按名称搜索。 4. 从结果中选择你的机器人。 5. 点击 **Add** 或 **Chat** 开始一对一对话。 6. 发送"Hello"来触发助手！ -## 公共 URL（仅 Webhook） +## 公网 URL（仅 Webhook） -Google Chat webhook 需要公共 HTTPS 端点。为安全起见，**仅将 `/googlechat` 路径暴露**到互联网。将 OpenClaw 仪表板和其他敏感端点保持在私有网络上。 +Google Chat webhooks 需要一个公网 HTTPS 端点。为了安全起见，**只将 `/googlechat` 路径暴露到互联网**。将 OpenClaw 仪表板和其他敏感端点保留在你的私有网络上。 ### 方案 A：Tailscale Funnel（推荐） -使用 Tailscale Serve 用于私有仪表板，Funnel 用于公共 webhook 路径。这样 `/` 保持私有，仅暴露 `/googlechat`。 +使用 Tailscale Serve 提供私有仪表板，使用 Funnel 提供公网 webhook 路径。这样可以保持 `/` 私有，同时只暴露 `/googlechat`。 -1. **检查你的 Gateway网关绑定在哪个地址上：** +1. **检查你的 Gateway 网关绑定的地址：** ```bash ss -tlnp | grep 18789 ``` - 注意 IP 地址（例如 `127.0.0.1`、`0.0.0.0` 或你的 Tailscale IP 如 `100.x.x.x`）。 + 记下 IP 地址（例如 `127.0.0.1`、`0.0.0.0` 或你的 Tailscale IP 如 `100.x.x.x`）。 2. **仅将仪表板暴露给 tailnet（端口 8443）：** @@ -104,8 +104,8 @@ Google Chat webhook 需要公共 HTTPS 端点。为安全起见，**仅将 `/goo tailscale funnel --bg --set-path /googlechat http://100.106.161.80:18789/googlechat ``` -4. **为节点授权 Funnel 访问：** - 如果出现提示，请访问输出中显示的授权 URL，在你的 tailnet 策略中为此节点启用 Funnel。 +4. **授权节点访问 Funnel：** + 如果出现提示，请访问输出中显示的授权 URL，以在你的 tailnet 策略中为此节点启用 Funnel。 5. **验证配置：** ```bash @@ -113,19 +113,19 @@ Google Chat webhook 需要公共 HTTPS 端点。为安全起见，**仅将 `/goo tailscale funnel status ``` -你的公共 webhook URL 将是： +你的公网 webhook URL 将是： `https://..ts.net/googlechat` 你的私有仪表板仅限 tailnet 访问： `https://..ts.net:8443/` -在 Google Chat 应用配置中使用公共 URL（不带 `:8443`）。 +在 Google Chat 应用配置中使用公网 URL（不带 `:8443`）。 -> 注意：此配置在重启后持续有效。要在之后移除，运行 `tailscale funnel reset` 和 `tailscale serve reset`。 +> 注意：此配置在重启后会保留。如需稍后移除，请运行 `tailscale funnel reset` 和 `tailscale serve reset`。 ### 方案 B：反向代理（Caddy） -如果你使用像 Caddy 这样的反向代理，仅代理特定路径： +如果你使用像 Caddy 这样的反向代理，只代理特定路径： ```caddy your-domain.com { @@ -133,31 +133,31 @@ your-domain.com { } ``` -使用此配置，对 `your-domain.com/` 的任何请求将被忽略或返回 404，而 `your-domain.com/googlechat` 安全地路由到 OpenClaw。 +使用此配置，任何发往 `your-domain.com/` 的请求将被忽略或返回 404，而 `your-domain.com/googlechat` 会安全地路由到 OpenClaw。 ### 方案 C：Cloudflare Tunnel -配置你的隧道入口规则，仅路由 webhook 路径： +配置你的隧道入口规则，只路由 webhook 路径： - **路径**：`/googlechat` -> `http://localhost:18789/googlechat` -- **默认规则**：HTTP 404（Not Found） +- **默认规则**：HTTP 404（未找到） ## 工作原理 -1. Google Chat 向 Gateway网关发送 webhook POST 请求。每个请求包含一个 `Authorization: Bearer ` 头。 -2. OpenClaw 根据配置的 `audienceType` + `audience` 验证 token： +1. Google Chat 向 Gateway 网关发送 webhook POST 请求。每个请求都包含一个 `Authorization: Bearer ` 头。 +2. OpenClaw 根据配置的 `audienceType` + `audience` 验证令牌： - `audienceType: "app-url"` → audience 是你的 HTTPS webhook URL。 - `audienceType: "project-number"` → audience 是 Cloud 项目编号。 3. 消息按空间路由： - 私信使用会话键 `agent::googlechat:dm:`。 - 空间使用会话键 `agent::googlechat:group:`。 -4. 私信访问默认需要配对。未知发送者会收到配对码；通过以下方式批准： +4. 私信访问默认为配对模式。未知发送者会收到配对码；使用以下命令批准： - `openclaw pairing approve googlechat ` 5. 群组空间默认需要 @提及。如果提及检测需要应用的用户名，请使用 `botUser`。 -## 目标 +## 目标标识符 -使用以下标识符进行投递和允许列表： +使用这些标识符进行消息投递和允许列表： - 私信：`users/` 或 `users/`（接受邮箱地址）。 - 空间：`spaces/`。 @@ -173,7 +173,7 @@ your-domain.com { audienceType: "app-url", audience: "https://gateway.example.com/googlechat", webhookPath: "/googlechat", - botUser: "users/1234567890", // 可选；辅助提及检测 + botUser: "users/1234567890", // 可选；帮助提及检测 dm: { policy: "pairing", allowFrom: ["users/1234567890", "name@example.com"], @@ -197,11 +197,11 @@ your-domain.com { 注意事项： -- 服务账户凭据也可以通过 `serviceAccount`（JSON 字符串）内联传递。 +- 服务账号凭证也可以通过 `serviceAccount`（JSON 字符串）内联传递。 - 如果未设置 `webhookPath`，默认 webhook 路径为 `/googlechat`。 -- 当 `actions.reactions` 启用时，可通过 `reactions` 工具和 `channels action` 使用回应功能。 +- 当 `actions.reactions` 启用时，可通过 `reactions` 工具和 `channels action` 使用表情回应。 - `typingIndicator` 支持 `none`、`message`（默认）和 `reaction`（reaction 需要用户 OAuth）。 -- 附件通过 Chat API 下载并存储在媒体管道中（大小由 `mediaMaxMb` 限制）。 +- 附件通过 Chat API 下载并存储在媒体管道中（大小受 `mediaMaxMb` 限制）。 ## 故障排除 @@ -213,15 +213,15 @@ your-domain.com { status code: 405, reason phrase: HTTP error response: HTTP/1.1 405 Method Not Allowed ``` -这意味着 webhook 处理器未注册。常见原因： +这意味着 webhook 处理程序未注册。常见原因： -1. **渠道未配置**：配置中缺少 `channels.googlechat` 部分。通过以下方式验证： +1. **渠道未配置**：配置中缺少 `channels.googlechat` 部分。使用以下命令验证： ```bash openclaw config get channels.googlechat ``` - 如果返回"Config path not found"，添加配置（参见[配置要点](#配置要点)）。 + 如果返回"Config path not found"，请添加配置（参见[配置要点](#配置要点)）。 2. **插件未启用**：检查插件状态： @@ -229,9 +229,9 @@ status code: 405, reason phrase: HTTP error response: HTTP/1.1 405 Method Not Al openclaw plugins list | grep googlechat ``` - 如果显示"disabled"，在配置中添加 `plugins.entries.googlechat.enabled: true`。 + 如果显示"disabled"，请在配置中添加 `plugins.entries.googlechat.enabled: true`。 -3. **Gateway网关未重启**：添加配置后，重启 Gateway网关： +3. **Gateway 网关未重启**：添加配置后，重启 Gateway 网关： ```bash openclaw gateway restart ``` @@ -245,13 +245,13 @@ openclaw channels status ### 其他问题 -- 检查 `openclaw channels status --probe` 查看认证错误或缺失的 audience 配置。 -- 如果没有消息到达，确认 Chat 应用的 webhook URL + 事件订阅。 -- 如果提及门控阻止了回复，将 `botUser` 设置为应用的用户资源名称并验证 `requireMention`。 -- 发送测试消息时使用 `openclaw logs --follow` 查看请求是否到达 Gateway网关。 +- 检查 `openclaw channels status --probe` 以查看认证错误或缺少 audience 配置。 +- 如果没有收到消息，请确认 Chat 应用的 webhook URL 和事件订阅。 +- 如果提及门控阻止了回复，请将 `botUser` 设置为应用的用户资源名称并验证 `requireMention`。 +- 在发送测试消息时使用 `openclaw logs --follow` 查看请求是否到达 Gateway 网关。 相关文档： -- [Gateway网关配置](/gateway/configuration) +- [Gateway 网关配置](/gateway/configuration) - [安全](/gateway/security) -- [回应](/tools/reactions) +- [表情回应](/tools/reactions) diff --git a/docs/zh-CN/channels/grammy.md b/docs/zh-CN/channels/grammy.md index 9279d97fd9..88e20fec96 100644 --- a/docs/zh-CN/channels/grammy.md +++ b/docs/zh-CN/channels/grammy.md @@ -1,38 +1,38 @@ --- read_when: - - 开发 Telegram 或 grammY 相关功能 -summary: 通过 grammY 集成 Telegram Bot API 及设置说明 + - 开发 Telegram 或 grammY 相关功能时 +summary: 通过 grammY 集成 Telegram Bot API，附设置说明 title: grammY x-i18n: - generated_at: "2026-02-01T19:20:16Z" + generated_at: "2026-02-03T10:03:55Z" model: claude-opus-4-5 provider: pi source_hash: ea7ef23e6d77801f4ef5fc56685ef4470f79f5aecab448d644a72cbab53521b7 source_path: channels/grammy.md - workflow: 14 + workflow: 15 --- # grammY 集成（Telegram Bot API） # 为什么选择 grammY -- TypeScript 优先的 Bot API 客户端，内置长轮询 + webhook 辅助工具、中间件、错误处理、速率限制器。 -- 比手动编写 fetch + FormData 更简洁的媒体辅助工具；支持所有 Bot API 方法。 -- 可扩展：通过自定义 fetch 支持代理，会话中间件（可选），类型安全的上下文。 +- 以 TS 为核心的 Bot API 客户端，内置长轮询 + webhook 辅助工具、中间件、错误处理和速率限制器。 +- 媒体处理辅助工具比手动编写 fetch + FormData 更简洁；支持所有 Bot API 方法。 +- 可扩展：通过自定义 fetch 支持代理，可选的会话中间件，类型安全的上下文。 -# 已交付的功能 +# 我们发布的内容 -- **单一客户端路径：** 基于 fetch 的实现已移除；grammY 现在是唯一的 Telegram 客户端（发送 + Gateway网关），默认启用 grammY throttler。 -- **Gateway网关：** `monitorTelegramProvider` 构建一个 grammY `Bot`，接入提及/允许列表门控、通过 `getFile`/`download` 下载媒体，并通过 `sendMessage/sendPhoto/sendVideo/sendAudio/sendDocument` 投递回复。支持通过 `webhookCallback` 进行长轮询或 webhook。 +- **单一客户端路径：** 移除了基于 fetch 的实现；grammY 现在是唯一的 Telegram 客户端（发送 + Gateway 网关），默认启用 grammY throttler。 +- **Gateway 网关：** `monitorTelegramProvider` 构建 grammY `Bot`，接入 mention/allowlist 网关控制，通过 `getFile`/`download` 下载媒体，并使用 `sendMessage/sendPhoto/sendVideo/sendAudio/sendDocument` 发送回复。通过 `webhookCallback` 支持长轮询或 webhook。 - **代理：** 可选的 `channels.telegram.proxy` 通过 grammY 的 `client.baseFetch` 使用 `undici.ProxyAgent`。 -- **Webhook 支持：** `webhook-set.ts` 封装了 `setWebhook/deleteWebhook`；`webhook.ts` 托管回调并支持健康检查 + 优雅关闭。当设置了 `channels.telegram.webhookUrl` + `channels.telegram.webhookSecret` 时 Gateway网关启用 webhook 模式（否则使用长轮询）。 -- **会话：** 私聊合并到智能体主会话（`agent::`）；群组使用 `agent::telegram:group:`；回复路由回同一渠道。 -- **配置选项：** `channels.telegram.botToken`、`channels.telegram.dmPolicy`、`channels.telegram.groups`（允许列表 + 提及默认值）、`channels.telegram.allowFrom`、`channels.telegram.groupAllowFrom`、`channels.telegram.groupPolicy`、`channels.telegram.mediaMaxMb`、`channels.telegram.linkPreview`、`channels.telegram.proxy`、`channels.telegram.webhookSecret`、`channels.telegram.webhookUrl`。 +- **Webhook 支持：** `webhook-set.ts` 封装了 `setWebhook/deleteWebhook`；`webhook.ts` 托管回调，支持健康检查和优雅关闭。当设置了 `channels.telegram.webhookUrl` + `channels.telegram.webhookSecret` 时，Gateway 网关启用 webhook 模式（否则使用长轮询）。 +- **会话：** 私聊折叠到智能体主会话（`agent::`）；群组使用 `agent::telegram:group:`；回复路由回同一渠道。 +- **配置选项：** `channels.telegram.botToken`、`channels.telegram.dmPolicy`、`channels.telegram.groups`（allowlist + mention 默认值）、`channels.telegram.allowFrom`、`channels.telegram.groupAllowFrom`、`channels.telegram.groupPolicy`、`channels.telegram.mediaMaxMb`、`channels.telegram.linkPreview`、`channels.telegram.proxy`、`channels.telegram.webhookSecret`、`channels.telegram.webhookUrl`。 - **草稿流式传输：** 可选的 `channels.telegram.streamMode` 在私有话题聊天中使用 `sendMessageDraft`（Bot API 9.3+）。这与渠道分块流式传输是分开的。 -- **测试：** grammY mock 覆盖了私信 + 群组提及门控和出站发送；欢迎更多媒体/webhook 测试用例。 +- **测试：** grammY mock 覆盖了私信 + 群组 mention 网关控制和出站发送；欢迎添加更多媒体/webhook 测试用例。 -待讨论问题 +待解决问题 - 如果遇到 Bot API 429 错误，考虑使用可选的 grammY 插件（throttler）。 -- 添加更多结构化的媒体测试（贴纸、语音消息）。 -- 使 webhook 监听端口可配置（目前固定为 8787，除非通过 Gateway网关接入）。 +- 添加更多结构化媒体测试（贴纸、语音消息）。 +- 使 webhook 监听端口可配置（目前固定为 8787，除非通过 Gateway 网关配置）。 diff --git a/docs/zh-CN/channels/imessage.md b/docs/zh-CN/channels/imessage.md index 9504d30c39..84ab14103b 100644 --- a/docs/zh-CN/channels/imessage.md +++ b/docs/zh-CN/channels/imessage.md @@ -1,29 +1,29 @@ --- read_when: - 设置 iMessage 支持 - - 调试 iMessage 收发 -summary: 通过 imsg（基于 stdio 的 JSON-RPC）实现 iMessage 支持、设置和 chat_id 路由 + - 调试 iMessage 发送/接收 +summary: 通过 imsg（基于 stdio 的 JSON-RPC）实现 iMessage 支持、设置及 chat_id 路由 title: iMessage x-i18n: - generated_at: "2026-02-01T19:21:07Z" + generated_at: "2026-02-03T07:44:18Z" model: claude-opus-4-5 provider: pi source_hash: bc19756a42ead80a0845f18c4830c3f1f40948f69b2b016a4026598cfb8fef0d source_path: channels/imessage.md - workflow: 14 + workflow: 15 --- -# iMessage（imsg） +# iMessage (imsg) -状态：外部 CLI 集成。Gateway网关启动 `imsg rpc`（基于 stdio 的 JSON-RPC）。 +状态：外部 CLI 集成。Gateway 网关生成 `imsg rpc`（基于 stdio 的 JSON-RPC）。 ## 快速设置（新手） -1. 确保此 Mac 上的"信息"已登录。 +1. 确保在此 Mac 上已登录"信息"。 2. 安装 `imsg`： - `brew install steipete/tap/imsg` 3. 配置 OpenClaw 的 `channels.imessage.cliPath` 和 `channels.imessage.dbPath`。 -4. 启动 Gateway网关并批准所有 macOS 提示（自动化 + 完全磁盘访问权限）。 +4. 启动 Gateway 网关并批准所有 macOS 提示（自动化 + 完全磁盘访问权限）。 最小配置： @@ -39,18 +39,18 @@ x-i18n: } ``` -## 它是什么 +## 简介 -- 在 macOS 上由 `imsg` 支持的 iMessage 渠道。 -- 确定性路由：回复始终发回 iMessage。 +- 基于 macOS 上 `imsg` 的 iMessage 渠道。 +- 确定性路由：回复始终返回到 iMessage。 - 私信共享智能体的主会话；群组是隔离的（`agent::imessage:group:`）。 -- 如果多参与者线程以 `is_group=false` 到达，你仍然可以通过 `chat_id` 使用 `channels.imessage.groups` 来隔离它（参见下方"类群组线程"）。 +- 如果多参与者会话以 `is_group=false` 到达，你仍可使用 `channels.imessage.groups` 按 `chat_id` 隔离（参见下方"类群组会话"）。 ## 配置写入 -默认情况下，iMessage 允许通过 `/config set|unset` 触发的配置更新写入（需要 `commands.config: true`）。 +默认情况下，iMessage 允许写入由 `/config set|unset` 触发的配置更新（需要 `commands.config: true`）。 -通过以下方式禁用： +禁用方式： ```json5 { @@ -60,31 +60,31 @@ x-i18n: ## 要求 -- macOS 且"信息"已登录。 -- OpenClaw + `imsg` 需要完全磁盘访问权限（访问 Messages 数据库）。 +- 已登录"信息"的 macOS。 +- OpenClaw + `imsg` 的完全磁盘访问权限（访问"信息"数据库）。 - 发送时需要自动化权限。 - `channels.imessage.cliPath` 可以指向任何代理 stdin/stdout 的命令（例如，通过 SSH 连接到另一台 Mac 并运行 `imsg rpc` 的包装脚本）。 ## 设置（快速路径） -1. 确保此 Mac 上的"信息"已登录。 -2. 配置 iMessage 并启动 Gateway网关。 +1. 确保在此 Mac 上已登录"信息"。 +2. 配置 iMessage 并启动 Gateway 网关。 ### 专用机器人 macOS 用户（用于隔离身份） -如果你希望机器人从一个**独立的 iMessage 身份**发送消息（并保持你的个人"信息"整洁），请使用专用的 Apple ID + 专用的 macOS 用户。 +如果你希望机器人从**独立的 iMessage 身份**发送（并保持你的个人"信息"整洁），请使用专用 Apple ID + 专用 macOS 用户。 -1. 创建一个专用的 Apple ID（例如：`my-cool-bot@icloud.com`）。 - - Apple 可能需要手机号码进行验证/双重认证。 -2. 创建一个 macOS 用户（例如：`openclawhome`）并登录。 +1. 创建专用 Apple ID（例如：`my-cool-bot@icloud.com`）。 + - Apple 可能需要电话号码进行验证 / 2FA。 +2. 创建 macOS 用户（例如：`openclawhome`）并登录。 3. 在该 macOS 用户中打开"信息"并使用机器人 Apple ID 登录 iMessage。 4. 启用远程登录（系统设置 → 通用 → 共享 → 远程登录）。 5. 安装 `imsg`： - `brew install steipete/tap/imsg` 6. 设置 SSH 使 `ssh @localhost true` 无需密码即可工作。 -7. 将 `channels.imessage.accounts.bot.cliPath` 指向一个以机器人用户身份运行 `imsg` 的 SSH 包装脚本。 +7. 将 `channels.imessage.accounts.bot.cliPath` 指向以机器人用户身份运行 `imsg` 的 SSH 包装脚本。 -首次运行注意事项：发送/接收可能需要在*机器人 macOS 用户*中进行 GUI 审批（自动化 + 完全磁盘访问权限）。如果 `imsg rpc` 看起来卡住或退出，请登录该用户（屏幕共享很有帮助），运行一次 `imsg chats --limit 1` / `imsg send ...`，批准提示，然后重试。 +首次运行注意事项：发送/接收可能需要在*机器人 macOS 用户*中进行 GUI 批准（自动化 + 完全磁盘访问权限）。如果 `imsg rpc` 看起来卡住或退出，请登录该用户（屏幕共享很有帮助），运行一次 `imsg chats --limit 1` / `imsg send ...`，批准提示，然后重试。 示例包装脚本（`chmod +x`）。将 `` 替换为你的实际 macOS 用户名： @@ -92,7 +92,7 @@ x-i18n: #!/usr/bin/env bash set -euo pipefail -# 先运行一次交互式 SSH 以接受主机密钥： +# Run an interactive SSH once first to accept host keys: # ssh @localhost true exec /usr/bin/ssh -o BatchMode=yes -o ConnectTimeout=5 -T @localhost \ "/usr/local/bin/imsg" "$@" @@ -118,11 +118,11 @@ exec /usr/bin/ssh -o BatchMode=yes -o ConnectTimeout=5 -T @local } ``` -对于单账户设置，使用扁平选项（`channels.imessage.cliPath`、`channels.imessage.dbPath`）而非 `accounts` 映射。 +对于单账户设置，使用扁平选项（`channels.imessage.cliPath`、`channels.imessage.dbPath`）而不是 `accounts` 映射。 ### 远程/SSH 变体（可选） -如果你想在另一台 Mac 上使用 iMessage，将 `channels.imessage.cliPath` 设置为通过 SSH 在远程 macOS 主机上运行 `imsg` 的包装脚本。OpenClaw 只需要 stdio。 +如果你想在另一台 Mac 上使用 iMessage，请将 `channels.imessage.cliPath` 设置为通过 SSH 在远程 macOS 主机上运行 `imsg` 的包装脚本。OpenClaw 只需要 stdio。 示例包装脚本： @@ -131,36 +131,36 @@ exec /usr/bin/ssh -o BatchMode=yes -o ConnectTimeout=5 -T @local exec ssh -T gateway-host imsg "$@" ``` -**远程附件：** 当 `cliPath` 通过 SSH 指向远程主机时，Messages 数据库中的附件路径引用的是远程机器上的文件。OpenClaw 可以通过设置 `channels.imessage.remoteHost` 自动通过 SCP 获取这些文件： +**远程附件：** 当 `cliPath` 通过 SSH 指向远程主机时，"信息"数据库中的附件路径引用的是远程机器上的文件。OpenClaw 可以通过设置 `channels.imessage.remoteHost` 自动通过 SCP 获取这些文件： ```json5 { channels: { imessage: { - cliPath: "~/imsg-ssh", // 到远程 Mac 的 SSH 包装脚本 - remoteHost: "user@gateway-host", // 用于 SCP 文件传输 + cliPath: "~/imsg-ssh", // SSH wrapper to remote Mac + remoteHost: "user@gateway-host", // for SCP file transfer includeAttachments: true, }, }, } ``` -如果未设置 `remoteHost`，OpenClaw 会尝试通过解析你包装脚本中的 SSH 命令来自动检测。建议显式配置以确保可靠性。 +如果未设置 `remoteHost`，OpenClaw 会尝试通过解析包装脚本中的 SSH 命令自动检测。建议显式配置以提高可靠性。 #### 通过 Tailscale 连接远程 Mac（示例） -如果 Gateway网关运行在 Linux 主机/虚拟机上但 iMessage 必须运行在 Mac 上，Tailscale 是最简单的桥接方案：Gateway网关通过 tailnet 与 Mac 通信，通过 SSH 运行 `imsg`，并通过 SCP 传回附件。 +如果 Gateway 网关运行在 Linux 主机/虚拟机上但 iMessage 必须运行在 Mac 上，Tailscale 是最简单的桥接方式：Gateway 网关通过 tailnet 与 Mac 通信，通过 SSH 运行 `imsg`，并通过 SCP 获取附件。 架构： ``` ┌──────────────────────────────┐ SSH (imsg rpc) ┌──────────────────────────┐ -│ Gateway网关主机（Linux/VM） │──────────────────────────────────▶│ 装有 Messages + imsg 的 Mac │ -│ - openclaw gateway │ SCP（附件） │ - Messages 已登录 │ -│ - channels.imessage.cliPath │◀──────────────────────────────────│ - 远程登录已启用 │ +│ Gateway host (Linux/VM) │──────────────────────────────────▶│ Mac with Messages + imsg │ +│ - openclaw gateway │ SCP (attachments) │ - Messages signed in │ +│ - channels.imessage.cliPath │◀──────────────────────────────────│ - Remote Login enabled │ └──────────────────────────────┘ └──────────────────────────┘ ▲ - │ Tailscale tailnet（主机名或 100.x.y.z） + │ Tailscale tailnet (hostname or 100.x.y.z) ▼ user@gateway-host ``` @@ -190,19 +190,19 @@ exec ssh -T bot@mac-mini.tailnet-1234.ts.net imsg "$@" 注意事项： -- 确保 Mac 已登录"信息"，且远程登录已启用。 +- 确保 Mac 已登录"信息"，并已启用远程登录。 - 使用 SSH 密钥使 `ssh bot@mac-mini.tailnet-1234.ts.net` 无需提示即可工作。 - `remoteHost` 应与 SSH 目标匹配，以便 SCP 可以获取附件。 -多账户支持：使用 `channels.imessage.accounts`，每个账户配置独立选项和可选的 `name`。共享模式请参阅 [`gateway/configuration`](/gateway/configuration#telegramaccounts--discordaccounts--slackaccounts--signalaccounts--imessageaccounts)。不要提交 `~/.openclaw/openclaw.json`（它通常包含 token）。 +多账户支持：使用 `channels.imessage.accounts` 配置每个账户及可选的 `name`。参见 [`gateway/configuration`](/gateway/configuration#telegramaccounts--discordaccounts--slackaccounts--signalaccounts--imessageaccounts) 了解共享模式。不要提交 `~/.openclaw/openclaw.json`（它通常包含令牌）。 ## 访问控制（私信 + 群组） 私信： - 默认：`channels.imessage.dmPolicy = "pairing"`。 -- 未知发送者会收到配对码；在批准之前消息会被忽略（配对码 1 小时后过期）。 -- 通过以下方式批准： +- 未知发送者会收到配对码；消息在批准前会被忽略（配对码在 1 小时后过期）。 +- 批准方式： - `openclaw pairing list imessage` - `openclaw pairing approve imessage ` - 配对是 iMessage 私信的默认令牌交换方式。详情：[配对](/start/pairing) @@ -210,23 +210,23 @@ exec ssh -T bot@mac-mini.tailnet-1234.ts.net imsg "$@" 群组： - `channels.imessage.groupPolicy = open | allowlist | disabled`。 -- 当设置为 `allowlist` 时，`channels.imessage.groupAllowFrom` 控制谁可以在群组中触发。 -- 提及门控使用 `agents.list[].groupChat.mentionPatterns`（或 `messages.groupChat.mentionPatterns`），因为 iMessage 没有原生提及元数据。 +- 设置 `allowlist` 时，`channels.imessage.groupAllowFrom` 控制谁可以在群组中触发。 +- 提及检测使用 `agents.list[].groupChat.mentionPatterns`（或 `messages.groupChat.mentionPatterns`），因为 iMessage 没有原生提及元数据。 - 多智能体覆盖：在 `agents.list[].groupChat.mentionPatterns` 上设置每个智能体的模式。 ## 工作原理（行为） -- `imsg` 流式传输消息事件；Gateway网关将其标准化为共享的渠道信封。 -- 回复始终路由回同一个 chat id 或用户名。 +- `imsg` 流式传输消息事件；Gateway 网关将它们规范化为共享渠道信封。 +- 回复始终路由回相同的 chat id 或 handle。 -## 类群组线程（`is_group=false`） +## 类群组会话（`is_group=false`） -一些 iMessage 线程可能有多个参与者，但由于"信息"存储聊天标识符的方式，仍然以 `is_group=false` 到达。 +某些 iMessage 会话可能有多个参与者，但根据"信息"存储聊天标识符的方式，仍以 `is_group=false` 到达。 -如果你在 `channels.imessage.groups` 下显式配置了一个 `chat_id`，OpenClaw 会将该线程视为"群组"，用于： +如果你在 `channels.imessage.groups` 下显式配置了 `chat_id`，OpenClaw 会将该会话视为"群组"用于： - 会话隔离（独立的 `agent::imessage:group:` 会话键） -- 群组允许列表/提及门控行为 +- 群组允许列表 / 提及检测行为 示例： @@ -244,27 +244,27 @@ exec ssh -T bot@mac-mini.tailnet-1234.ts.net imsg "$@" } ``` -当你想为特定线程使用隔离的个性/模型时很有用（参见[多智能体路由](/concepts/multi-agent)）。有关文件系统隔离，请参阅[沙箱](/gateway/sandboxing)。 +当你想为特定会话使用隔离的个性/模型时这很有用（参见[多智能体路由](/concepts/multi-agent)）。关于文件系统隔离，参见[沙箱隔离](/gateway/sandboxing)。 ## 媒体 + 限制 -- 通过 `channels.imessage.includeAttachments` 可选接收附件。 -- 媒体上限通过 `channels.imessage.mediaMaxMb` 设置。 +- 通过 `channels.imessage.includeAttachments` 可选附件摄取。 +- 通过 `channels.imessage.mediaMaxMb` 设置媒体上限。 ## 限制 - 出站文本按 `channels.imessage.textChunkLimit` 分块（默认 4000）。 -- 可选的换行分块：设置 `channels.imessage.chunkMode="newline"` 在按长度分块之前按空行（段落边界）分割。 -- 媒体上传上限由 `channels.imessage.mediaMaxMb` 限制（默认 16）。 +- 可选换行分块：设置 `channels.imessage.chunkMode="newline"` 在长度分块前按空行（段落边界）分割。 +- 媒体上传受 `channels.imessage.mediaMaxMb` 限制（默认 16）。 ## 寻址 / 投递目标 -推荐使用 `chat_id` 进行稳定路由： +优先使用 `chat_id` 进行稳定路由： - `chat_id:123`（推荐） - `chat_guid:...` - `chat_identifier:...` -- 直接用户名：`imessage:+1555` / `sms:+1555` / `user@example.com` +- 直接 handle：`imessage:+1555` / `sms:+1555` / `user@example.com` 列出聊天： @@ -279,22 +279,22 @@ imsg chats --limit 20 提供商选项： - `channels.imessage.enabled`：启用/禁用渠道启动。 -- `channels.imessage.cliPath`：`imsg` 的路径。 -- `channels.imessage.dbPath`：Messages 数据库路径。 -- `channels.imessage.remoteHost`：当 `cliPath` 指向远程 Mac 时用于 SCP 附件传输的 SSH 主机（例如 `user@gateway-host`）。未设置时从 SSH 包装脚本自动检测。 +- `channels.imessage.cliPath`：`imsg` 路径。 +- `channels.imessage.dbPath`："信息"数据库路径。 +- `channels.imessage.remoteHost`：当 `cliPath` 指向远程 Mac 时用于 SCP 附件传输的 SSH 主机（例如 `user@gateway-host`）。如未设置则从 SSH 包装脚本自动检测。 - `channels.imessage.service`：`imessage | sms | auto`。 -- `channels.imessage.region`：SMS 区域。 +- `channels.imessage.region`：短信区域。 - `channels.imessage.dmPolicy`：`pairing | allowlist | open | disabled`（默认：pairing）。 -- `channels.imessage.allowFrom`：私信允许列表（用户名、邮箱、E.164 号码或 `chat_id:*`）。`open` 需要 `"*"`。iMessage 没有用户名；使用用户名或聊天目标。 +- `channels.imessage.allowFrom`：私信允许列表（handle、邮箱、E.164 号码或 `chat_id:*`）。`open` 需要 `"*"`。iMessage 没有用户名；使用 handle 或聊天目标。 - `channels.imessage.groupPolicy`：`open | allowlist | disabled`（默认：allowlist）。 - `channels.imessage.groupAllowFrom`：群组发送者允许列表。 -- `channels.imessage.historyLimit` / `channels.imessage.accounts.*.historyLimit`：包含为上下文的最大群组消息数（0 禁用）。 -- `channels.imessage.dmHistoryLimit`：私信历史限制（用户回合数）。按用户覆盖：`channels.imessage.dms[""].historyLimit`。 -- `channels.imessage.groups`：按群组默认值 + 允许列表（使用 `"*"` 设置全局默认值）。 -- `channels.imessage.includeAttachments`：将附件接收到上下文中。 +- `channels.imessage.historyLimit` / `channels.imessage.accounts.*.historyLimit`：作为上下文包含的最大群组消息数（0 禁用）。 +- `channels.imessage.dmHistoryLimit`：私信历史限制（用户轮次）。每用户覆盖：`channels.imessage.dms[""].historyLimit`。 +- `channels.imessage.groups`：每群组默认值 + 允许列表（使用 `"*"` 作为全局默认值）。 +- `channels.imessage.includeAttachments`：将附件摄取到上下文。 - `channels.imessage.mediaMaxMb`：入站/出站媒体上限（MB）。 - `channels.imessage.textChunkLimit`：出站分块大小（字符）。 -- `channels.imessage.chunkMode`：`length`（默认）或 `newline`，在按长度分块之前按空行（段落边界）分割。 +- `channels.imessage.chunkMode`：`length`（默认）或 `newline` 在长度分块前按空行（段落边界）分割。 相关全局选项： diff --git a/docs/zh-CN/channels/index.md b/docs/zh-CN/channels/index.md index 6ff3163f1c..9bafe7cbd9 100644 --- a/docs/zh-CN/channels/index.md +++ b/docs/zh-CN/channels/index.md @@ -5,46 +5,48 @@ read_when: summary: OpenClaw 可连接的消息平台 title: 聊天渠道 x-i18n: - generated_at: "2026-02-01T19:21:22Z" + generated_at: "2026-02-03T07:43:27Z" model: claude-opus-4-5 provider: pi source_hash: 2632863def6dee97e0fa8b931762f0969174fd4fb22303a00dcd46527fe4a141 source_path: channels/index.md - workflow: 14 + workflow: 15 --- # 聊天渠道 -OpenClaw 可以在你已经使用的任何聊天应用上与你对话。每个渠道通过 Gateway网关连接。所有渠道都支持文本；媒体和回应功能因渠道而异。 +OpenClaw 可以在你已经使用的任何聊天应用上与你交流。每个渠道通过 Gateway 网关连接。 +所有渠道都支持文本；媒体和表情回应的支持因渠道而异。 ## 支持的渠道 -- [WhatsApp](/channels/whatsapp) — 最受欢迎；使用 Baileys 并需要二维码配对。 +- [WhatsApp](/channels/whatsapp) — 最受欢迎；使用 Baileys，需要二维码配对。 - [Telegram](/channels/telegram) — 通过 grammY 使用 Bot API；支持群组。 -- [Discord](/channels/discord) — Discord Bot API + Gateway网关；支持服务器、频道和私信。 +- [Discord](/channels/discord) — Discord Bot API + Gateway；支持服务器、频道和私信。 - [Slack](/channels/slack) — Bolt SDK；工作区应用。 -- [Google Chat](/channels/googlechat) — 通过 HTTP webhook 使用 Google Chat API 应用。 +- [Google Chat](/channels/googlechat) — 通过 HTTP webhook 的 Google Chat API 应用。 - [Mattermost](/channels/mattermost) — Bot API + WebSocket；频道、群组、私信（插件，需单独安装）。 - [Signal](/channels/signal) — signal-cli；注重隐私。 -- [BlueBubbles](/channels/bluebubbles) — **推荐用于 iMessage**；使用 BlueBubbles macOS 服务器 REST API，功能完整（编辑、撤回、特效、回应、群组管理——编辑功能在 macOS 26 Tahoe 上目前不可用）。 -- [iMessage](/channels/imessage) — 仅限 macOS；通过 imsg 原生集成（旧版，新设置建议使用 BlueBubbles）。 +- [BlueBubbles](/channels/bluebubbles) — **iMessage 推荐方案**；使用 BlueBubbles macOS 服务器 REST API，完整功能支持（编辑、撤回、特效、表情回应、群组管理——编辑功能目前在 macOS 26 Tahoe 上存在问题）。 +- [iMessage](/channels/imessage) — 仅限 macOS；通过 imsg 原生集成（旧版方案，新部署建议使用 BlueBubbles）。 - [Microsoft Teams](/channels/msteams) — Bot Framework；企业支持（插件，需单独安装）。 - [LINE](/channels/line) — LINE Messaging API 机器人（插件，需单独安装）。 - [Nextcloud Talk](/channels/nextcloud-talk) — 通过 Nextcloud Talk 的自托管聊天（插件，需单独安装）。 - [Matrix](/channels/matrix) — Matrix 协议（插件，需单独安装）。 - [Nostr](/channels/nostr) — 通过 NIP-04 的去中心化私信（插件，需单独安装）。 -- [Tlon](/channels/tlon) — 基于 Urbit 的通讯工具（插件，需单独安装）。 +- [Tlon](/channels/tlon) — 基于 Urbit 的消息应用（插件，需单独安装）。 - [Twitch](/channels/twitch) — 通过 IRC 连接的 Twitch 聊天（插件，需单独安装）。 -- [Zalo](/channels/zalo) — Zalo Bot API；越南流行的通讯工具（插件，需单独安装）。 -- [Zalo Personal](/channels/zalouser) — 通过二维码登录的 Zalo 个人账户（插件，需单独安装）。 -- [WebChat](/web/webchat) — 通过 WebSocket 的 Gateway网关 WebChat UI。 +- [Zalo](/channels/zalo) — Zalo Bot API；越南流行的消息应用（插件，需单独安装）。 +- [Zalo Personal](/channels/zalouser) — 通过二维码登录的 Zalo 个人账号（插件，需单独安装）。 +- [WebChat](/web/webchat) — 基于 WebSocket 的 Gateway 网关 WebChat 界面。 ## 注意事项 -- 渠道可以同时运行；配置多个渠道后 OpenClaw 会按聊天路由。 -- 最快的设置通常是 **Telegram**（简单的 bot token）。WhatsApp 需要二维码配对并在磁盘上存储更多状态。 +- 渠道可以同时运行；配置多个渠道后，OpenClaw 会按聊天进行路由。 +- 最快的设置方式通常是 **Telegram**（简单的机器人令牌）。WhatsApp 需要二维码配对， + 并在磁盘上存储更多状态。 - 群组行为因渠道而异；参见[群组](/concepts/groups)。 -- 私信配对和允许列表出于安全考虑强制执行；参见[安全](/gateway/security)。 -- Telegram 内部实现：[grammY 说明](/channels/grammy)。 +- 为安全起见，私信配对和允许列表会被强制执行；参见[安全](/gateway/security)。 +- Telegram 内部机制：[grammY 说明](/channels/grammy)。 - 故障排除：[渠道故障排除](/channels/troubleshooting)。 -- 模型提供商单独文档化；参见[模型提供商](/providers/models)。 +- 模型提供商单独记录；参见[模型提供商](/providers/models)。 diff --git a/docs/zh-CN/channels/line.md b/docs/zh-CN/channels/line.md index 18a900d30e..4640d4abb2 100644 --- a/docs/zh-CN/channels/line.md +++ b/docs/zh-CN/channels/line.md @@ -1,26 +1,26 @@ --- read_when: - 你想将 OpenClaw 连接到 LINE - - 你需要 LINE webhook + 凭据设置 - - 你需要 LINE 特定的消息选项 -summary: LINE Messaging API 插件设置、配置和使用 + - 你需要配置 LINE webhook + 凭证 + - 你想了解 LINE 特有的消息选项 +summary: LINE Messaging API 插件的配置、设置和使用方法 title: LINE x-i18n: - generated_at: "2026-02-01T19:21:38Z" + generated_at: "2026-02-03T07:43:38Z" model: claude-opus-4-5 provider: pi source_hash: 8fbac126786f95b9454f3cc61906c2798393a8d7914e787d3755c020c7ab2da6 source_path: channels/line.md - workflow: 14 + workflow: 15 --- # LINE（插件） -LINE 通过 LINE Messaging API 连接到 OpenClaw。插件作为 Gateway网关上的 webhook 接收器运行，使用你的频道访问 token + 频道密钥进行认证。 +LINE 通过 LINE Messaging API 连接到 OpenClaw。该插件作为 webhook 接收器在 Gateway 网关上运行，使用你的 channel access token + channel secret 进行身份验证。 -状态：通过插件支持。支持私信、群聊、媒体、位置、Flex 消息、模板消息和快速回复。不支持回应和线程。 +状态：通过插件支持。支持私信、群聊、媒体、位置、Flex 消息、模板消息和快捷回复。不支持表情回应和话题回复。 -## 需要插件 +## 需要安装插件 安装 LINE 插件： @@ -34,20 +34,20 @@ openclaw plugins install @openclaw/line openclaw plugins install ./extensions/line ``` -## 设置 +## 配置步骤 1. 创建 LINE Developers 账户并打开控制台： https://developers.line.biz/console/ -2. 创建（或选择）一个 Provider 并添加一个 **Messaging API** 频道。 -3. 从频道设置中复制 **Channel access token** 和 **Channel secret**。 +2. 创建（或选择）一个 Provider 并添加 **Messaging API** 渠道。 +3. 从渠道设置中复制 **Channel access token** 和 **Channel secret**。 4. 在 Messaging API 设置中启用 **Use webhook**。 -5. 将 webhook URL 设置为你的 Gateway网关端点（需要 HTTPS）： +5. 将 webhook URL 设置为你的 Gateway 网关端点（必须使用 HTTPS）： ``` https://gateway-host/line/webhook ``` -Gateway网关响应 LINE 的 webhook 验证（GET）和入站事件（POST）。如果你需要自定义路径，请设置 `channels.line.webhookPath` 或 `channels.line.accounts..webhookPath` 并相应更新 URL。 +Gateway 网关会响应 LINE 的 webhook 验证（GET）和入站事件（POST）。如果你需要自定义路径，请设置 `channels.line.webhookPath` 或 `channels.line.accounts..webhookPath` 并相应更新 URL。 ## 配置 @@ -66,12 +66,12 @@ Gateway网关响应 LINE 的 webhook 验证（GET）和入站事件（POST）。 } ``` -环境变量（仅默认账户）： +环境变量（仅限默认账户）： - `LINE_CHANNEL_ACCESS_TOKEN` - `LINE_CHANNEL_SECRET` -Token/密钥文件： +Token/secret 文件： ```json5 { @@ -84,7 +84,7 @@ Token/密钥文件： } ``` -多账户： +多账户配置： ```json5 { @@ -104,7 +104,7 @@ Token/密钥文件： ## 访问控制 -私信默认需要配对。未知发送者会收到配对码，在批准之前其消息会被忽略。 +私信默认使用配对模式。未知发送者会收到配对码，其消息在获得批准前会被忽略。 ```bash openclaw pairing list line @@ -114,12 +114,12 @@ openclaw pairing approve line 允许列表和策略： - `channels.line.dmPolicy`：`pairing | allowlist | open | disabled` -- `channels.line.allowFrom`：私信的允许 LINE 用户 ID 列表 +- `channels.line.allowFrom`：私信的允许列表 LINE 用户 ID - `channels.line.groupPolicy`：`allowlist | open | disabled` -- `channels.line.groupAllowFrom`：群组的允许 LINE 用户 ID 列表 -- 按群组覆盖：`channels.line.groups..allowFrom` +- `channels.line.groupAllowFrom`：群组的允许列表 LINE 用户 ID +- 单群组覆盖：`channels.line.groups..allowFrom` -LINE ID 区分大小写。有效的 ID 格式如下： +LINE ID 区分大小写。有效 ID 格式如下： - 用户：`U` + 32 位十六进制字符 - 群组：`C` + 32 位十六进制字符 @@ -127,14 +127,14 @@ LINE ID 区分大小写。有效的 ID 格式如下： ## 消息行为 -- 文本在 5000 字符处分块。 -- Markdown 格式会被去除；代码块和表格在可能时会转换为 Flex 卡片。 -- 流式响应会被缓冲；智能体工作时 LINE 接收完整分块并显示加载动画。 -- 媒体下载上限由 `channels.line.mediaMaxMb` 限制（默认 10）。 +- 文本按 5000 字符分块。 +- Markdown 格式会被移除；代码块和表格会尽可能转换为 Flex 卡片。 +- 流式响应会被缓冲；智能体处理时，LINE 会收到完整分块并显示加载动画。 +- 媒体下载受 `channels.line.mediaMaxMb` 限制（默认 10）。 ## 渠道数据（富消息） -使用 `channelData.line` 发送快速回复、位置、Flex 卡片或模板消息。 +使用 `channelData.line` 发送快捷回复、位置、Flex 卡片或模板消息。 ```json5 { @@ -151,7 +151,7 @@ LINE ID 区分大小写。有效的 ID 格式如下： flexMessage: { altText: "Status card", contents: { - /* Flex 负载 */ + /* Flex payload */ }, }, templateMessage: { @@ -167,7 +167,7 @@ LINE ID 区分大小写。有效的 ID 格式如下： } ``` -LINE 插件还附带一个 `/card` 命令用于 Flex 消息预设： +LINE 插件还提供 `/card` 命令用于 Flex 消息预设： ``` /card info "Welcome" "Thanks for joining!" @@ -175,6 +175,6 @@ LINE 插件还附带一个 `/card` 命令用于 Flex 消息预设： ## 故障排除 -- **Webhook 验证失败：** 确保 webhook URL 为 HTTPS 且 `channelSecret` 与 LINE 控制台匹配。 -- **没有入站事件：** 确认 webhook 路径与 `channels.line.webhookPath` 匹配且 Gateway网关可从 LINE 访问。 -- **媒体下载错误：** 如果媒体超过默认限制，请增大 `channels.line.mediaMaxMb`。 +- **Webhook 验证失败：** 确保 webhook URL 使用 HTTPS 且 `channelSecret` 与 LINE 控制台中的一致。 +- **没有入站事件：** 确认 webhook 路径与 `channels.line.webhookPath` 匹配，且 Gateway 网关可从 LINE 访问。 +- **媒体下载错误：** 如果媒体超过默认限制，请提高 `channels.line.mediaMaxMb`。 diff --git a/docs/zh-CN/channels/matrix.md b/docs/zh-CN/channels/matrix.md index 4dcbace568..d793560125 100644 --- a/docs/zh-CN/channels/matrix.md +++ b/docs/zh-CN/channels/matrix.md @@ -4,25 +4,25 @@ read_when: summary: Matrix 支持状态、功能和配置 title: Matrix x-i18n: - generated_at: "2026-02-01T19:22:24Z" + generated_at: "2026-02-03T07:44:02Z" model: claude-opus-4-5 provider: pi source_hash: b276b5263593c766e7be6549abbb27927177e7b51cfd297b4825965372513ee4 source_path: channels/matrix.md - workflow: 14 + workflow: 15 --- # Matrix（插件） -Matrix 是一个开放、去中心化的消息协议。OpenClaw 作为 Matrix **用户**连接到任何主服务器，因此你需要为机器人创建一个 Matrix 账户。登录后，你可以直接私信机器人或邀请它加入房间（Matrix 的"群组"）。Beeper 也是一个可用的客户端选项，但它需要启用端到端加密。 +Matrix 是一个开放的去中心化消息协议。OpenClaw 以 Matrix **用户**身份连接到任意主服务器，因此你需要为机器人创建一个 Matrix 账户。登录后，你可以直接私信机器人或邀请它加入房间（Matrix"群组"）。Beeper 也是一个有效的客户端选项，但它需要启用 E2EE。 -状态：通过插件支持（@vector-im/matrix-bot-sdk）。支持私信、房间、线程、媒体、回应、投票（发送 + poll-start 转为文本）、位置和端到端加密（需要加密支持）。 +状态：通过插件（@vector-im/matrix-bot-sdk）支持。支持私信、房间、话题、媒体、表情回应、投票（发送 + poll-start 作为文本）、位置和 E2EE（需要加密支持）。 ## 需要插件 -Matrix 作为插件发布，不包含在核心安装中。 +Matrix 作为插件提供，不包含在核心安装中。 -通过 CLI 安装（npm 注册表）： +通过 CLI 安装（npm 仓库）： ```bash openclaw plugins install @openclaw/matrix @@ -34,7 +34,7 @@ openclaw plugins install @openclaw/matrix openclaw plugins install ./extensions/matrix ``` -如果你在配置/新手引导期间选择了 Matrix 并检测到 git 检出，OpenClaw 会自动提供本地安装路径。 +如果你在配置/新手引导期间选择 Matrix 并检测到 git 检出，OpenClaw 将自动提供本地安装路径。 详情：[插件](/plugin) @@ -46,8 +46,8 @@ openclaw plugins install ./extensions/matrix 2. 在主服务器上创建 Matrix 账户： - 在 [https://matrix.org/ecosystem/hosting/](https://matrix.org/ecosystem/hosting/) 浏览托管选项 - 或自行托管。 -3. 获取机器人账户的访问 token： - - 在你的主服务器上使用 Matrix 登录 API 配合 `curl`： +3. 获取机器人账户的访问令牌： + - 在你的主服务器上使用 `curl` 调用 Matrix 登录 API： ```bash curl --request POST \ @@ -64,18 +64,18 @@ openclaw plugins install ./extensions/matrix ``` - 将 `matrix.example.org` 替换为你的主服务器 URL。 - - 或设置 `channels.matrix.userId` + `channels.matrix.password`：OpenClaw 调用相同的登录端点，将访问 token 存储在 `~/.openclaw/credentials/matrix/credentials.json` 中，并在下次启动时重用。 + - 或设置 `channels.matrix.userId` + `channels.matrix.password`：OpenClaw 会调用相同的登录端点，将访问令牌存储在 `~/.openclaw/credentials/matrix/credentials.json`，并在下次启动时重用。 -4. 配置凭据： +4. 配置凭证： - 环境变量：`MATRIX_HOMESERVER`、`MATRIX_ACCESS_TOKEN`（或 `MATRIX_USER_ID` + `MATRIX_PASSWORD`） - 或配置：`channels.matrix.*` - - 如果两者都设置了，配置优先。 - - 使用访问 token 时：用户 ID 通过 `/whoami` 自动获取。 - - 设置时，`channels.matrix.userId` 应为完整的 Matrix ID（例如：`@bot:example.org`）。 -5. 重启 Gateway网关（或完成新手引导）。 -6. 从任何 Matrix 客户端（Element、Beeper 等；参见 https://matrix.org/ecosystem/clients/）与机器人开始私信或邀请它加入房间。Beeper 需要端到端加密，因此请设置 `channels.matrix.encryption: true` 并验证设备。 + - 如果两者都设置，配置优先。 + - 使用访问令牌时：用户 ID 通过 `/whoami` 自动获取。 + - 设置时，`channels.matrix.userId` 应为完整的 Matrix ID（示例：`@bot:example.org`）。 +5. 重启 Gateway 网关（或完成新手引导）。 +6. 从任何 Matrix 客户端（Element、Beeper 等；参见 https://matrix.org/ecosystem/clients/）与机器人开始私信或邀请它加入房间。Beeper 需要 E2EE，因此请设置 `channels.matrix.encryption: true` 并验证设备。 -最小配置（访问 token，用户 ID 自动获取）： +最小配置（访问令牌，用户 ID 自动获取）： ```json5 { @@ -90,7 +90,7 @@ openclaw plugins install ./extensions/matrix } ``` -端到端加密配置（启用端到端加密）： +E2EE 配置（启用端到端加密）： ```json5 { @@ -106,27 +106,27 @@ openclaw plugins install ./extensions/matrix } ``` -## 加密（端到端加密） +## 加密（E2EE） -端到端加密通过 Rust 加密 SDK **支持**。 +通过 Rust 加密 SDK **支持**端到端加密。 -通过 `channels.matrix.encryption: true` 启用： +使用 `channels.matrix.encryption: true` 启用： - 如果加密模块加载成功，加密房间会自动解密。 -- 向加密房间发送时，出站媒体会被加密。 -- 首次连接时，OpenClaw 会从你的其他会话请求设备验证。 +- 发送到加密房间时，出站媒体会被加密。 +- 首次连接时，OpenClaw 会向你的其他会话请求设备验证。 - 在另一个 Matrix 客户端（Element 等）中验证设备以启用密钥共享。 -- 如果加密模块无法加载，端到端加密将被禁用且加密房间无法解密；OpenClaw 会记录警告。 -- 如果你看到缺少加密模块的错误（例如 `@matrix-org/matrix-sdk-crypto-nodejs-*`），请允许 `@matrix-org/matrix-sdk-crypto-nodejs` 的构建脚本并运行 `pnpm rebuild @matrix-org/matrix-sdk-crypto-nodejs` 或通过 `node node_modules/@matrix-org/matrix-sdk-crypto-nodejs/download-lib.js` 获取二进制文件。 +- 如果无法加载加密模块，E2EE 将被禁用，加密房间将无法解密；OpenClaw 会记录警告。 +- 如果你看到缺少加密模块的错误（例如 `@matrix-org/matrix-sdk-crypto-nodejs-*`），请允许 `@matrix-org/matrix-sdk-crypto-nodejs` 的构建脚本并运行 `pnpm rebuild @matrix-org/matrix-sdk-crypto-nodejs`，或使用 `node node_modules/@matrix-org/matrix-sdk-crypto-nodejs/download-lib.js` 获取二进制文件。 -加密状态按账户 + 访问 token 存储在 `~/.openclaw/matrix/accounts//__//crypto/`（SQLite 数据库）。同步状态存储在同一目录下的 `bot-storage.json` 中。如果访问 token（设备）发生变化，会创建新的存储，机器人必须重新验证才能在加密房间中使用。 +加密状态按账户 + 访问令牌存储在 `~/.openclaw/matrix/accounts//__//crypto/`（SQLite 数据库）。同步状态存储在同目录的 `bot-storage.json` 中。如果访问令牌（设备）更改，将创建新的存储，机器人必须重新验证才能访问加密房间。 **设备验证：** -启用端到端加密后，机器人会在启动时从你的其他会话请求验证。打开 Element（或其他客户端）并批准验证请求以建立信任。验证完成后，机器人可以解密加密房间中的消息。 +启用 E2EE 时，机器人将在启动时向你的其他会话请求验证。打开 Element（或其他客户端）并批准验证请求以建立信任。验证后，机器人可以解密加密房间中的消息。 ## 路由模型 -- 回复始终发回 Matrix。 +- 回复始终返回到 Matrix。 - 私信共享智能体的主会话；房间映射到群组会话。 ## 访问控制（私信） @@ -136,12 +136,12 @@ openclaw plugins install ./extensions/matrix - `openclaw pairing list matrix` - `openclaw pairing approve matrix ` - 公开私信：`channels.matrix.dm.policy="open"` 加上 `channels.matrix.dm.allowFrom=["*"]`。 -- `channels.matrix.dm.allowFrom` 仅接受完整 Matrix 用户 ID（例如 `@user:server`）。向导仅在目录搜索得到唯一精确匹配时解析显示名称为用户 ID。 +- `channels.matrix.dm.allowFrom` 仅接受完整 Matrix 用户 ID（例如 `@user:server`）。向导仅在目录搜索得到唯一精确匹配时将显示名称解析为用户 ID。 ## 房间（群组） -- 默认：`channels.matrix.groupPolicy = "allowlist"`（提及门控）。使用 `channels.defaults.groupPolicy` 可在未设置时覆盖默认值。 -- 使用 `channels.matrix.groups` 允许列表中的房间（房间 ID/别名；名称仅在目录搜索得到唯一精确匹配时解析为 ID）： +- 默认：`channels.matrix.groupPolicy = "allowlist"`（提及门控）。使用 `channels.defaults.groupPolicy` 在未设置时覆盖默认值。 +- 使用 `channels.matrix.groups` 配置房间允许列表（房间 ID 或别名；名称仅在目录搜索得到唯一精确匹配时解析为 ID）： ```json5 { @@ -160,35 +160,35 @@ openclaw plugins install ./extensions/matrix - `requireMention: false` 启用该房间的自动回复。 - `groups."*"` 可以设置跨房间的提及门控默认值。 -- `groupAllowFrom` 限制哪些发送者可以在房间中触发机器人（完整 Matrix 用户 ID）。 -- 按房间的 `users` 允许列表可以进一步限制特定房间内的发送者（使用完整 Matrix 用户 ID）。 +- `groupAllowFrom` 限制哪些发送者可以在房间中触发机器人（需完整 Matrix 用户 ID）。 +- 每个房间的 `users` 允许列表可以进一步限制特定房间内的发送者（需完整 Matrix 用户 ID）。 - 配置向导会提示输入房间允许列表（房间 ID、别名或名称），仅在精确且唯一匹配时解析名称。 - 启动时，OpenClaw 将允许列表中的房间/用户名称解析为 ID 并记录映射；未解析的条目不会参与允许列表匹配。 -- 邀请默认自动加入；通过 `channels.matrix.autoJoin` 和 `channels.matrix.autoJoinAllowlist` 控制。 -- 要**不允许任何房间**，设置 `channels.matrix.groupPolicy: "disabled"`（或保持空的允许列表）。 -- 旧版键：`channels.matrix.rooms`（与 `groups` 结构相同）。 +- 默认自动加入邀请；使用 `channels.matrix.autoJoin` 和 `channels.matrix.autoJoinAllowlist` 控制。 +- 要**禁止所有房间**，设置 `channels.matrix.groupPolicy: "disabled"`（或保持空的允许列表）。 +- 旧版键名：`channels.matrix.rooms`（与 `groups` 相同的结构）。 -## 线程 +## 话题 -- 支持回复线程。 -- `channels.matrix.threadReplies` 控制回复是否保持在线程中： +- 支持回复话题。 +- `channels.matrix.threadReplies` 控制回复是否保持在话题中： - `off`、`inbound`（默认）、`always` -- `channels.matrix.replyToMode` 控制不在线程中回复时的 reply-to 元数据： +- `channels.matrix.replyToMode` 控制不在话题中回复时的 reply-to 元数据： - `off`（默认）、`first`、`all` ## 功能 -| 功能 | 状态 | -| ---------- | ---------------------------------------------------------- | -| 私信 | ✅ 支持 | -| 房间 | ✅ 支持 | -| 线程 | ✅ 支持 | -| 媒体 | ✅ 支持 | -| 端到端加密 | ✅ 支持（需要加密模块） | -| 回应 | ✅ 支持（通过工具发送/读取） | -| 投票 | ✅ 支持发送；入站 poll start 转换为文本（响应/结束被忽略） | -| 位置 | ✅ 支持（geo URI；忽略海拔） | -| 原生命令 | ✅ 支持 | +| 功能 | 状态 | +| -------- | ------------------------------------------------------ | +| 私信 | ✅ 支持 | +| 房间 | ✅ 支持 | +| 话题 | ✅ 支持 | +| 媒体 | ✅ 支持 | +| E2EE | ✅ 支持（需要加密模块） | +| 表情回应 | ✅ 支持（通过工具发送/读取） | +| 投票 | ✅ 支持发送；入站投票开始转换为文本（响应/结束被忽略） | +| 位置 | ✅ 支持（geo URI；忽略海拔） | +| 原生命令 | ✅ 支持 | ## 配置参考（Matrix） @@ -198,24 +198,24 @@ openclaw plugins install ./extensions/matrix - `channels.matrix.enabled`：启用/禁用渠道启动。 - `channels.matrix.homeserver`：主服务器 URL。 -- `channels.matrix.userId`：Matrix 用户 ID（使用访问 token 时可选）。 -- `channels.matrix.accessToken`：访问 token。 -- `channels.matrix.password`：登录密码（token 会被存储）。 +- `channels.matrix.userId`：Matrix 用户 ID（使用访问令牌时可选）。 +- `channels.matrix.accessToken`：访问令牌。 +- `channels.matrix.password`：登录密码（令牌会被存储）。 - `channels.matrix.deviceName`：设备显示名称。 -- `channels.matrix.encryption`：启用端到端加密（默认：false）。 +- `channels.matrix.encryption`：启用 E2EE（默认：false）。 - `channels.matrix.initialSyncLimit`：初始同步限制。 - `channels.matrix.threadReplies`：`off | inbound | always`（默认：inbound）。 - `channels.matrix.textChunkLimit`：出站文本分块大小（字符）。 -- `channels.matrix.chunkMode`：`length`（默认）或 `newline`，在按长度分块之前按空行（段落边界）分割。 +- `channels.matrix.chunkMode`：`length`（默认）或 `newline` 在长度分块前按空行（段落边界）分割。 - `channels.matrix.dm.policy`：`pairing | allowlist | open | disabled`（默认：pairing）。 -- `channels.matrix.dm.allowFrom`：私信允许列表（完整 Matrix 用户 ID）。`open` 需要 `"*"`。向导在可能时将名称解析为 ID。 +- `channels.matrix.dm.allowFrom`：私信允许列表（需完整 Matrix 用户 ID）。`open` 需要 `"*"`。向导在可能时将名称解析为 ID。 - `channels.matrix.groupPolicy`：`allowlist | open | disabled`（默认：allowlist）。 -- `channels.matrix.groupAllowFrom`：群组消息的允许发送者列表（完整 Matrix 用户 ID）。 -- `channels.matrix.allowlistOnly`：强制对私信 + 房间执行允许列表规则。 -- `channels.matrix.groups`：群组允许列表 + 按房间设置映射。 +- `channels.matrix.groupAllowFrom`：群组消息的允许发送者列表（需完整 Matrix 用户 ID）。 +- `channels.matrix.allowlistOnly`：强制私信 + 房间使用允许列表规则。 +- `channels.matrix.groups`：群组允许列表 + 每个房间的设置映射。 - `channels.matrix.rooms`：旧版群组允许列表/配置。 -- `channels.matrix.replyToMode`：线程/标签的 reply-to 模式。 +- `channels.matrix.replyToMode`：话题/标签的 reply-to 模式。 - `channels.matrix.mediaMaxMb`：入站/出站媒体上限（MB）。 - `channels.matrix.autoJoin`：邀请处理（`always | allowlist | off`，默认：always）。 - `channels.matrix.autoJoinAllowlist`：自动加入的允许房间 ID/别名。 -- `channels.matrix.actions`：按操作的工具门控（reactions/messages/pins/memberInfo/channelInfo）。 +- `channels.matrix.actions`：每个操作的工具限制（reactions/messages/pins/memberInfo/channelInfo）。 diff --git a/docs/zh-CN/channels/mattermost.md b/docs/zh-CN/channels/mattermost.md index 984a3a1818..67cb5897dc 100644 --- a/docs/zh-CN/channels/mattermost.md +++ b/docs/zh-CN/channels/mattermost.md @@ -5,21 +5,23 @@ read_when: summary: Mattermost 机器人设置和 OpenClaw 配置 title: Mattermost x-i18n: - generated_at: "2026-02-01T19:22:40Z" + generated_at: "2026-02-03T07:43:43Z" model: claude-opus-4-5 provider: pi source_hash: 57fabe5eb0efbcb885f4178b317b2fa99a41daf609e3a471de2b44db9def4ad7 source_path: channels/mattermost.md - workflow: 14 + workflow: 15 --- # Mattermost（插件） -状态：通过插件支持（bot token + WebSocket 事件）。支持频道、群组和私信。Mattermost 是一个可自托管的团队消息平台；有关产品详情和下载请访问官方网站 [mattermost.com](https://mattermost.com)。 +状态：通过插件支持（bot token + WebSocket 事件）。支持频道、群组和私信。 +Mattermost 是一个可自托管的团队消息平台；有关产品详情和下载，请访问官方网站 +[mattermost.com](https://mattermost.com)。 ## 需要插件 -Mattermost 作为插件发布，不包含在核心安装中。 +Mattermost 以插件形式提供，不包含在核心安装中。 通过 CLI 安装（npm 注册表）： @@ -33,16 +35,16 @@ openclaw plugins install @openclaw/mattermost openclaw plugins install ./extensions/mattermost ``` -如果你在配置/新手引导期间选择了 Mattermost 并检测到 git 检出，OpenClaw 会自动提供本地安装路径。 +如果你在配置/新手引导期间选择 Mattermost 并检测到 git 检出，OpenClaw 会自动提供本地安装路径。 详情：[插件](/plugin) ## 快速设置 1. 安装 Mattermost 插件。 -2. 创建一个 Mattermost 机器人账户并复制 **bot token**。 +2. 创建 Mattermost bot 账户并复制 **bot token**。 3. 复制 Mattermost **基础 URL**（例如 `https://chat.example.com`）。 -4. 配置 OpenClaw 并启动 Gateway网关。 +4. 配置 OpenClaw 并启动 Gateway 网关。 最小配置： @@ -61,7 +63,7 @@ openclaw plugins install ./extensions/mattermost ## 环境变量（默认账户） -如果你偏好使用环境变量，请在 Gateway网关主机上设置： +如果你偏好使用环境变量，请在 Gateway 网关主机上设置： - `MATTERMOST_BOT_TOKEN=...` - `MATTERMOST_URL=https://chat.example.com` @@ -73,7 +75,7 @@ openclaw plugins install ./extensions/mattermost Mattermost 自动响应私信。频道行为由 `chatmode` 控制： - `oncall`（默认）：仅在频道中被 @提及时响应。 -- `onmessage`：响应频道中的每条消息。 +- `onmessage`：响应每条频道消息。 - `onchar`：当消息以触发前缀开头时响应。 配置示例： @@ -91,8 +93,8 @@ Mattermost 自动响应私信。频道行为由 `chatmode` 控制： 注意事项： -- `onchar` 模式仍然响应明确的 @提及。 -- `channels.mattermost.requireMention` 对旧版配置仍然有效，但推荐使用 `chatmode`。 +- `onchar` 仍会响应显式 @提及。 +- `channels.mattermost.requireMention` 对旧配置仍然有效，但推荐使用 `chatmode`。 ## 访问控制（私信） @@ -104,13 +106,13 @@ Mattermost 自动响应私信。频道行为由 `chatmode` 控制： ## 频道（群组） -- 默认：`channels.mattermost.groupPolicy = "allowlist"`（提及门控）。 -- 使用 `channels.mattermost.groupAllowFrom` 允许列表发送者（用户 ID 或 `@username`）。 -- 开放频道：`channels.mattermost.groupPolicy="open"`（提及门控）。 +- 默认：`channels.mattermost.groupPolicy = "allowlist"`（提及限制）。 +- 使用 `channels.mattermost.groupAllowFrom` 将发送者加入允许列表（用户 ID 或 `@username`）。 +- 开放频道：`channels.mattermost.groupPolicy="open"`（提及限制）。 ## 出站投递目标 -在 `openclaw message send` 或定时任务/webhook 中使用以下目标格式： +在 `openclaw message send` 或 cron/webhooks 中使用这些目标格式： - `channel:` 用于频道 - `user:` 用于私信 @@ -137,6 +139,6 @@ Mattermost 支持在 `channels.mattermost.accounts` 下配置多个账户： ## 故障排除 -- 频道中没有回复：确保机器人已加入频道并提及它（oncall 模式），使用触发前缀（onchar 模式），或设置 `chatmode: "onmessage"`。 +- 频道中无回复：确保 bot 在频道中并提及它（oncall），使用触发前缀（onchar），或设置 `chatmode: "onmessage"`。 - 认证错误：检查 bot token、基础 URL 以及账户是否已启用。 - 多账户问题：环境变量仅适用于 `default` 账户。 diff --git a/docs/zh-CN/channels/msteams.md b/docs/zh-CN/channels/msteams.md index 9d48a0b892..e957ee0e56 100644 --- a/docs/zh-CN/channels/msteams.md +++ b/docs/zh-CN/channels/msteams.md @@ -1,32 +1,32 @@ --- read_when: - - 开发 Microsoft Teams 渠道功能 + - 开发 MS Teams 渠道功能 summary: Microsoft Teams 机器人支持状态、功能和配置 title: Microsoft Teams x-i18n: - generated_at: "2026-02-01T19:26:12Z" + generated_at: "2026-02-03T07:46:52Z" model: claude-opus-4-5 provider: pi - source_hash: 3d5641c578086f7569f42276d4ef2462200b9927ca3f505e6ee26806103eaa60 + source_hash: 2046cb8fa3dd349f4b25a40c013a87188af8f75c1886a782698bff2bb9f70971 source_path: channels/msteams.md - workflow: 14 + workflow: 15 --- # Microsoft Teams（插件） -> "进入此处者，放弃一切希望。" +> "进入此地者，放弃一切希望。" 更新时间：2026-01-21 -状态：支持文本 + 私信附件；频道/群组文件发送需要 `sharePointSiteId` + Graph 权限（参见[在群聊中发送文件](#在群聊中发送文件)）。投票通过 Adaptive Cards 发送。 +状态：支持文本 + 私信附件；频道/群组文件发送需要 `sharePointSiteId` + Graph 权限（参见[在群聊中发送文件](#sending-files-in-group-chats)）。投票通过 Adaptive Cards 发送。 ## 需要插件 -Microsoft Teams 作为插件发布，不包含在核心安装中。 +Microsoft Teams 作为插件提供，不包含在核心安装中。 -**破坏性变更（2026.1.15）：** Microsoft Teams 已从核心中移出。如果你使用它，必须安装插件。 +**破坏性变更（2026.1.15）：** MS Teams 已从核心移出。如果你使用它，必须安装插件。 -原因说明：保持核心安装更轻量，并让 Microsoft Teams 依赖项可以独立更新。 +原因说明：保持核心安装更轻量，并让 MS Teams 依赖项可以独立更新。 通过 CLI 安装（npm 注册表）： @@ -40,17 +40,18 @@ openclaw plugins install @openclaw/msteams openclaw plugins install ./extensions/msteams ``` -如果你在配置/新手引导期间选择了 Teams 并检测到 git 检出，OpenClaw 会自动提供本地安装路径。 +如果你在配置/新手引导过程中选择 Teams 并检测到 git 检出， +OpenClaw 将自动提供本地安装路径。 详情：[插件](/plugin) -## 快速设置（新手） +## 快速设置（初学者） 1. 安装 Microsoft Teams 插件。 2. 创建一个 **Azure Bot**（App ID + 客户端密钥 + 租户 ID）。 -3. 使用这些凭据配置 OpenClaw。 +3. 使用这些凭证配置 OpenClaw。 4. 通过公共 URL 或隧道暴露 `/api/messages`（默认端口 3978）。 -5. 安装 Teams 应用包并启动 Gateway网关。 +5. 安装 Teams 应用包并启动 Gateway 网关。 最小配置： @@ -68,19 +69,19 @@ openclaw plugins install ./extensions/msteams } ``` -注意：群聊默认被阻止（`channels.msteams.groupPolicy: "allowlist"`）。要允许群组回复，请设置 `channels.msteams.groupAllowFrom`（或使用 `groupPolicy: "open"` 允许任何成员，提及门控）。 +注意：群聊默认被阻止（`channels.msteams.groupPolicy: "allowlist"`）。要允许群组回复，请设置 `channels.msteams.groupAllowFrom`（或使用 `groupPolicy: "open"` 允许任何成员，需要提及才能触发）。 ## 目标 -- 通过 Teams 私信、群聊或频道与 OpenClaw 对话。 -- 保持路由确定性：回复始终发回消息到达的渠道。 -- 默认使用安全的渠道行为（除非另行配置，否则需要提及）。 +- 通过 Teams 私信、群聊或频道与 OpenClaw 交流。 +- 保持路由确定性：回复始终返回到消息到达的渠道。 +- 默认使用安全的渠道行为（除非另有配置，否则需要提及）。 ## 配置写入 默认情况下，Microsoft Teams 允许通过 `/config set|unset` 触发的配置更新写入（需要 `commands.config: true`）。 -通过以下方式禁用： +禁用方式： ```json5 { @@ -92,14 +93,14 @@ openclaw plugins install ./extensions/msteams **私信访问** -- 默认：`channels.msteams.dmPolicy = "pairing"`。未知发送者在批准前会被忽略。 -- `channels.msteams.allowFrom` 接受 AAD 对象 ID、UPN 或显示名称。当凭据允许时，向导通过 Microsoft Graph 将名称解析为 ID。 +- 默认：`channels.msteams.dmPolicy = "pairing"`。未知发送者在获得批准之前将被忽略。 +- `channels.msteams.allowFrom` 接受 AAD 对象 ID、UPN 或显示名称。当凭证允许时，向导会通过 Microsoft Graph 将名称解析为 ID。 **群组访问** -- 默认：`channels.msteams.groupPolicy = "allowlist"`（被阻止，除非你添加 `groupAllowFrom`）。使用 `channels.defaults.groupPolicy` 可在未设置时覆盖默认值。 +- 默认：`channels.msteams.groupPolicy = "allowlist"`（除非添加 `groupAllowFrom`，否则被阻止）。使用 `channels.defaults.groupPolicy` 在未设置时覆盖默认值。 - `channels.msteams.groupAllowFrom` 控制哪些发送者可以在群聊/频道中触发（回退到 `channels.msteams.allowFrom`）。 -- 设置 `groupPolicy: "open"` 可允许任何成员（默认仍需提及门控）。 +- 设置 `groupPolicy: "open"` 允许任何成员（默认仍需提及才能触发）。 - 要**不允许任何频道**，设置 `channels.msteams.groupPolicy: "disabled"`。 示例： @@ -117,11 +118,12 @@ openclaw plugins install ./extensions/msteams **团队 + 频道允许列表** -- 通过在 `channels.msteams.teams` 下列出团队和频道来限定群组/频道回复范围。 +- 通过在 `channels.msteams.teams` 下列出团队和频道来限定群组/频道回复的范围。 - 键可以是团队 ID 或名称；频道键可以是会话 ID 或名称。 -- 当 `groupPolicy="allowlist"` 且存在团队允许列表时，仅接受列出的团队/频道（提及门控）。 +- 当 `groupPolicy="allowlist"` 且存在团队允许列表时，仅接受列出的团队/频道（需要提及才能触发）。 - 配置向导接受 `Team/Channel` 条目并为你存储。 -- 启动时，OpenClaw 将团队/频道和用户允许列表名称解析为 ID（当 Graph 权限允许时）并记录映射；未解析的条目保持原样。 +- 启动时，OpenClaw 将团队/频道和用户允许列表名称解析为 ID（当 Graph 权限允许时） + 并记录映射；未解析的条目保持原样。 示例： @@ -146,10 +148,10 @@ openclaw plugins install ./extensions/msteams 1. 安装 Microsoft Teams 插件。 2. 创建一个 **Azure Bot**（App ID + 密钥 + 租户 ID）。 -3. 构建一个引用该机器人并包含下方 RSC 权限的 **Teams 应用包**。 -4. 将 Teams 应用上传/安装到团队（或私人范围用于私信）。 -5. 在 `~/.openclaw/openclaw.json`（或环境变量）中配置 `msteams` 并启动 Gateway网关。 -6. Gateway网关默认在 `/api/messages` 上监听 Bot Framework webhook 流量。 +3. 构建一个引用机器人并包含以下 RSC 权限的 **Teams 应用包**。 +4. 将 Teams 应用上传/安装到团队中（或用于私信的个人范围）。 +5. 在 `~/.openclaw/openclaw.json`（或环境变量）中配置 `msteams` 并启动 Gateway 网关。 +6. Gateway 网关默认在 `/api/messages` 上监听 Bot Framework webhook 流量。 ## Azure Bot 设置（前提条件） @@ -158,13 +160,13 @@ openclaw plugins install ./extensions/msteams ### 步骤 1：创建 Azure Bot 1. 前往[创建 Azure Bot](https://portal.azure.com/#create/Microsoft.AzureBot) -2. 填写 **Basics** 标签页： +2. 填写**基本信息**选项卡： | 字段 | 值 | | ------------------ | --------------------------------------------------- | | **Bot handle** | 你的机器人名称，例如 `openclaw-msteams`（必须唯一） | | **Subscription** | 选择你的 Azure 订阅 | - | **Resource group** | 新建或使用现有的 | + | **Resource group** | 新建或使用现有 | | **Pricing tier** | **Free** 用于开发/测试 | | **Type of App** | **Single Tenant**（推荐 - 见下方说明） | | **Creation type** | **Create new Microsoft App ID** | @@ -173,22 +175,22 @@ openclaw plugins install ./extensions/msteams 3. 点击 **Review + create** → **Create**（等待约 1-2 分钟） -### 步骤 2：获取凭据 +### 步骤 2：获取凭证 1. 前往你的 Azure Bot 资源 → **Configuration** 2. 复制 **Microsoft App ID** → 这是你的 `appId` -3. 点击 **Manage Password** → 进入应用注册 +3. 点击 **Manage Password** → 前往应用注册 4. 在 **Certificates & secrets** → **New client secret** → 复制 **Value** → 这是你的 `appPassword` -5. 进入 **Overview** → 复制 **Directory (tenant) ID** → 这是你的 `tenantId` +5. 前往 **Overview** → 复制 **Directory (tenant) ID** → 这是你的 `tenantId` ### 步骤 3：配置消息端点 1. 在 Azure Bot → **Configuration** 2. 将 **Messaging endpoint** 设置为你的 webhook URL： - 生产环境：`https://your-domain.com/api/messages` - - 本地开发：使用隧道（参见下方[本地开发](#本地开发隧道)） + - 本地开发：使用隧道（见下方[本地开发](#local-development-tunneling)） -### 步骤 4：启用 Teams 频道 +### 步骤 4：启用 Teams 渠道 1. 在 Azure Bot → **Channels** 2. 点击 **Microsoft Teams** → Configure → Save @@ -198,7 +200,7 @@ openclaw plugins install ./extensions/msteams Teams 无法访问 `localhost`。本地开发请使用隧道： -**方案 A：ngrok** +**选项 A：ngrok** ```bash ngrok http 3978 @@ -206,7 +208,7 @@ ngrok http 3978 # 将消息端点设置为：https://abc123.ngrok.io/api/messages ``` -**方案 B：Tailscale Funnel** +**选项 B：Tailscale Funnel** ```bash tailscale funnel 3978 @@ -215,31 +217,31 @@ tailscale funnel 3978 ## Teams 开发者门户（替代方案） -除了手动创建清单 ZIP 外，你可以使用 [Teams 开发者门户](https://dev.teams.microsoft.com/apps)： +除了手动创建清单 ZIP，你可以使用 [Teams 开发者门户](https://dev.teams.microsoft.com/apps)： 1. 点击 **+ New app** 2. 填写基本信息（名称、描述、开发者信息） -3. 进入 **App features** → **Bot** +3. 前往 **App features** → **Bot** 4. 选择 **Enter a bot ID manually** 并粘贴你的 Azure Bot App ID 5. 勾选范围：**Personal**、**Team**、**Group Chat** 6. 点击 **Distribute** → **Download app package** 7. 在 Teams 中：**Apps** → **Manage your apps** → **Upload a custom app** → 选择 ZIP -这通常比手动编辑 JSON 清单更简单。 +这通常比手动编辑 JSON 清单更容易。 ## 测试机器人 -**方案 A：Azure Web Chat（先验证 webhook）** +**选项 A：Azure Web Chat（先验证 webhook）** 1. 在 Azure 门户 → 你的 Azure Bot 资源 → **Test in Web Chat** -2. 发送一条消息 - 你应该看到回复 -3. 这确认了你的 webhook 端点在 Teams 设置之前可以正常工作 +2. 发送一条消息 - 你应该看到响应 +3. 这确认你的 webhook 端点在 Teams 设置之前正常工作 -**方案 B：Teams（安装应用后）** +**选项 B：Teams（应用安装后）** -1. 安装 Teams 应用（旁加载或组织目录） +1. 安装 Teams 应用（侧载或组织目录） 2. 在 Teams 中找到机器人并发送私信 -3. 检查 Gateway网关日志中的传入活动 +3. 检查 Gateway 网关日志中的传入活动 ## 设置（最小纯文本） @@ -248,7 +250,7 @@ tailscale funnel 3978 - 从本地检出：`openclaw plugins install ./extensions/msteams` 2. **机器人注册** - - 创建 Azure Bot（见上方）并记录： + - 创建一个 Azure Bot（见上文）并记录： - App ID - 客户端密钥（App password） - 租户 ID（单租户） @@ -256,10 +258,10 @@ tailscale funnel 3978 3. **Teams 应用清单** - 包含一个 `bot` 条目，其中 `botId = `。 - 范围：`personal`、`team`、`groupChat`。 - - `supportsFiles: true`（个人范围文件处理所必需）。 - - 添加 RSC 权限（见下方）。 + - `supportsFiles: true`（个人范围文件处理所需）。 + - 添加 RSC 权限（见下文）。 - 创建图标：`outline.png`（32x32）和 `color.png`（192x192）。 - - 将三个文件打包在一起：`manifest.json`、`outline.png`、`color.png`。 + - 将三个文件一起打包：`manifest.json`、`outline.png`、`color.png`。 4. **配置 OpenClaw** @@ -275,29 +277,29 @@ tailscale funnel 3978 } ``` - 你也可以使用环境变量替代配置键： + 你也可以使用环境变量代替配置键： - `MSTEAMS_APP_ID` - `MSTEAMS_APP_PASSWORD` - `MSTEAMS_TENANT_ID` 5. **机器人端点** - - 将 Azure Bot 消息端点设置为： + - 将 Azure Bot Messaging Endpoint 设置为： - `https://:3978/api/messages`（或你选择的路径/端口）。 -6. **运行 Gateway网关** - - 当插件已安装且 `msteams` 配置存在凭据时，Teams 渠道会自动启动。 +6. **运行 Gateway 网关** + - 当插件已安装且 `msteams` 配置存在并有凭证时，Teams 渠道会自动启动。 ## 历史上下文 -- `channels.msteams.historyLimit` 控制多少条最近的频道/群组消息被包含在提示中。 -- 回退到 `messages.groupChat.historyLimit`。设置 `0` 可禁用（默认 50）。 -- 私信历史可通过 `channels.msteams.dmHistoryLimit`（用户回合数）限制。按用户覆盖：`channels.msteams.dms[""].historyLimit`。 +- `channels.msteams.historyLimit` 控制将多少条最近的频道/群组消息包含到提示中。 +- 回退到 `messages.groupChat.historyLimit`。设置 `0` 禁用（默认 50）。 +- 私信历史可以通过 `channels.msteams.dmHistoryLimit`（用户轮次）限制。每用户覆盖：`channels.msteams.dms[""].historyLimit`。 ## 当前 Teams RSC 权限（清单） -以下是我们 Teams 应用清单中**现有的 resourceSpecific 权限**。它们仅在安装了应用的团队/聊天中适用。 +这些是我们 Teams 应用清单中**现有的 resourceSpecific 权限**。它们仅适用于安装了应用的团队/聊天内部。 -**频道（团队范围）：** +**对于频道（团队范围）：** - `ChannelMessage.Read.Group`（Application）- 无需 @提及即可接收所有频道消息 - `ChannelMessage.Send.Group`（Application） @@ -307,11 +309,11 @@ tailscale funnel 3978 - `TeamMember.Read.Group`（Application） - `TeamSettings.Read.Group`（Application） -**群聊：** +**对于群聊：** - `ChatMessage.Read.Chat`（Application）- 无需 @提及即可接收所有群聊消息 -## 示例 Teams 清单（已脱敏） +## Teams 清单示例（已脱敏） 包含必需字段的最小有效示例。请替换 ID 和 URL。 @@ -361,30 +363,30 @@ tailscale funnel 3978 } ``` -### 清单注意事项（必需字段） +### 清单注意事项（必填字段） - `bots[].botId` **必须**与 Azure Bot App ID 匹配。 - `webApplicationInfo.id` **必须**与 Azure Bot App ID 匹配。 -- `bots[].scopes` 必须包含你计划使用的范围（`personal`、`team`、`groupChat`）。 -- `bots[].supportsFiles: true` 是个人范围文件处理所必需的。 -- `authorization.permissions.resourceSpecific` 必须包含频道读取/发送权限（如果你需要频道流量）。 +- `bots[].scopes` 必须包含你计划使用的界面（`personal`、`team`、`groupChat`）。 +- `bots[].supportsFiles: true` 是个人范围文件处理所需的。 +- `authorization.permissions.resourceSpecific` 如果你需要频道流量，必须包含频道读取/发送权限。 ### 更新现有应用 -要更新已安装的 Teams 应用（例如添加 RSC 权限）： +要更新已安装的 Teams 应用（例如，添加 RSC 权限）： -1. 使用新设置更新 `manifest.json` -2. **递增 `version` 字段**（例如 `1.0.0` → `1.1.0`） +1. 使用新设置更新你的 `manifest.json` +2. **增加 `version` 字段**（例如，`1.0.0` → `1.1.0`） 3. **重新打包**清单和图标（`manifest.json`、`outline.png`、`color.png`） 4. 上传新的 zip： - - **方案 A（Teams 管理中心）：** Teams 管理中心 → Teams apps → Manage apps → 找到你的应用 → Upload new version - - **方案 B（旁加载）：** 在 Teams 中 → Apps → Manage your apps → Upload a custom app + - **选项 A（Teams 管理中心）：** Teams 管理中心 → Teams apps → Manage apps → 找到你的应用 → Upload new version + - **选项 B（侧载）：** 在 Teams 中 → Apps → Manage your apps → Upload a custom app 5. **对于团队频道：** 在每个团队中重新安装应用以使新权限生效 -6. **完全退出并重新启动 Teams**（不只是关闭窗口）以清除缓存的应用元数据 +6. **完全退出并重新启动 Teams**（不仅仅是关闭窗口）以清除缓存的应用元数据 -## 功能：仅 RSC vs Graph +## 功能：仅 RSC 与 Graph -### 仅使用 **Teams RSC**（已安装应用，无 Graph API 权限） +### 仅使用 **Teams RSC**（应用已安装，无 Graph API 权限） 可用： @@ -394,108 +396,109 @@ tailscale funnel 3978 不可用： -- 频道/群组**图片或文件内容**（负载仅包含 HTML 占位符）。 +- 频道/群组**图片或文件内容**（负载仅包含 HTML 存根）。 - 下载存储在 SharePoint/OneDrive 中的附件。 -- 读取消息历史（超出实时 webhook 事件范围）。 +- 读取消息历史（超出实时 webhook 事件）。 ### 使用 **Teams RSC + Microsoft Graph Application 权限** -新增： +增加： - 下载托管内容（粘贴到消息中的图片）。 - 下载存储在 SharePoint/OneDrive 中的文件附件。 - 通过 Graph 读取频道/聊天消息历史。 -### RSC vs Graph API +### RSC 与 Graph API 对比 -| 功能 | RSC 权限 | Graph API | -| -------------- | ------------------ | --------------------------- | -| **实时消息** | 是（通过 webhook） | 否（仅轮询） | -| **历史消息** | 否 | 是（可查询历史） | -| **设置复杂度** | 仅需应用清单 | 需要管理员同意 + token 流程 | -| **离线可用** | 否（必须运行中） | 是（可随时查询） | +| 功能 | RSC 权限 | Graph API | +| -------------- | ------------------ | ------------------------- | +| **实时消息** | 是（通过 webhook） | 否（仅轮询） | +| **历史消息** | 否 | 是（可查询历史） | +| **设置复杂度** | 仅应用清单 | 需要管理员同意 + 令牌流程 | +| **离线工作** | 否（必须运行） | 是（随时查询） | -**总结：** RSC 用于实时监听；Graph API 用于历史访问。要补上离线期间错过的消息，你需要具有 `ChannelMessage.Read.All` 的 Graph API（需要管理员同意）。 +**结论：** RSC 用于实时监听；Graph API 用于历史访问。要在离线时补上错过的消息，你需要带有 `ChannelMessage.Read.All` 的 Graph API（需要管理员同意）。 -## 启用 Graph 的媒体 + 历史（频道所必需） +## 启用 Graph 的媒体 + 历史（频道所需） -如果你需要**频道**中的图片/文件或想获取**消息历史**，必须启用 Microsoft Graph 权限并授予管理员同意。 +如果你需要**频道**中的图片/文件或想要获取**消息历史**，你必须启用 Microsoft Graph 权限并授予管理员同意。 -1. 在 Entra ID（Azure AD）**应用注册**中，添加 Microsoft Graph **Application 权限**： +1. 在 Entra ID（Azure AD）**App Registration** 中，添加 Microsoft Graph **Application 权限**： - `ChannelMessage.Read.All`（频道附件 + 历史） - `Chat.Read.All` 或 `ChatMessage.Read.All`（群聊） 2. 为租户**授予管理员同意**。 -3. 递增 Teams 应用**清单版本**，重新上传，并在 **Teams 中重新安装应用**。 +3. 提升 Teams 应用**清单版本**，重新上传，并**在 Teams 中重新安装应用**。 4. **完全退出并重新启动 Teams** 以清除缓存的应用元数据。 ## 已知限制 ### Webhook 超时 -Teams 通过 HTTP webhook 投递消息。如果处理时间过长（例如 LLM 响应缓慢），你可能会看到： +Teams 通过 HTTP webhook 传递消息。如果处理时间过长（例如，LLM 响应缓慢），你可能会看到： -- Gateway网关超时 +- Gateway 网关超时 - Teams 重试消息（导致重复） -- 回复丢失 +- 丢失的回复 -OpenClaw 通过快速返回并主动发送回复来处理此问题，但非常慢的响应仍可能导致问题。 +OpenClaw 通过快速返回并主动发送回复来处理这个问题，但非常慢的响应仍可能导致问题。 -### 格式 +### 格式化 Teams markdown 比 Slack 或 Discord 更有限： -- 基本格式有效：**粗体**、_斜体_、`代码`、链接 -- 复杂 markdown（表格、嵌套列表）可能无法正确渲染 -- 支持 Adaptive Cards 用于投票和任意卡片发送（见下方） +- 基本格式化有效：**粗体**、_斜体_、`代码`、链接 +- 复杂的 markdown（表格、嵌套列表）可能无法正确渲染 +- 支持 Adaptive Cards 用于投票和任意卡片发送（见下文） ## 配置 -关键设置（共享渠道模式请参见 `/gateway/configuration`）： +关键设置（共享渠道模式见 `/gateway/configuration`）： - `channels.msteams.enabled`：启用/禁用渠道。 -- `channels.msteams.appId`、`channels.msteams.appPassword`、`channels.msteams.tenantId`：机器人凭据。 +- `channels.msteams.appId`、`channels.msteams.appPassword`、`channels.msteams.tenantId`：机器人凭证。 - `channels.msteams.webhook.port`（默认 `3978`） - `channels.msteams.webhook.path`（默认 `/api/messages`） - `channels.msteams.dmPolicy`：`pairing | allowlist | open | disabled`（默认：pairing） - `channels.msteams.allowFrom`：私信允许列表（AAD 对象 ID、UPN 或显示名称）。当 Graph 访问可用时，向导在设置期间将名称解析为 ID。 - `channels.msteams.textChunkLimit`：出站文本分块大小。 -- `channels.msteams.chunkMode`：`length`（默认）或 `newline`，在按长度分块之前按空行（段落边界）分割。 +- `channels.msteams.chunkMode`：`length`（默认）或 `newline` 在长度分块之前按空行（段落边界）分割。 - `channels.msteams.mediaAllowHosts`：入站附件主机允许列表（默认为 Microsoft/Teams 域名）。 +- `channels.msteams.mediaAuthAllowHosts`：在媒体重试时附加 Authorization 头的允许列表（默认为 Graph + Bot Framework 主机）。 - `channels.msteams.requireMention`：在频道/群组中需要 @提及（默认 true）。 -- `channels.msteams.replyStyle`：`thread | top-level`（参见[回复样式：线程 vs 帖子](#回复样式线程-vs-帖子)）。 -- `channels.msteams.teams..replyStyle`：按团队覆盖。 -- `channels.msteams.teams..requireMention`：按团队覆盖。 -- `channels.msteams.teams..tools`：按团队默认工具策略覆盖（`allow`/`deny`/`alsoAllow`），在频道覆盖缺失时使用。 -- `channels.msteams.teams..toolsBySender`：按团队按发送者工具策略覆盖（支持 `"*"` 通配符）。 -- `channels.msteams.teams..channels..replyStyle`：按频道覆盖。 -- `channels.msteams.teams..channels..requireMention`：按频道覆盖。 -- `channels.msteams.teams..channels..tools`：按频道工具策略覆盖（`allow`/`deny`/`alsoAllow`）。 -- `channels.msteams.teams..channels..toolsBySender`：按频道按发送者工具策略覆盖（支持 `"*"` 通配符）。 -- `channels.msteams.sharePointSiteId`：用于群聊/频道文件上传的 SharePoint 站点 ID（参见[在群聊中发送文件](#在群聊中发送文件)）。 +- `channels.msteams.replyStyle`：`thread | top-level`（见[回复样式](#reply-style-threads-vs-posts)）。 +- `channels.msteams.teams..replyStyle`：每团队覆盖。 +- `channels.msteams.teams..requireMention`：每团队覆盖。 +- `channels.msteams.teams..tools`：当缺少频道覆盖时使用的默认每团队工具策略覆盖（`allow`/`deny`/`alsoAllow`）。 +- `channels.msteams.teams..toolsBySender`：默认每团队每发送者工具策略覆盖（支持 `"*"` 通配符）。 +- `channels.msteams.teams..channels..replyStyle`：每频道覆盖。 +- `channels.msteams.teams..channels..requireMention`：每频道覆盖。 +- `channels.msteams.teams..channels..tools`：每频道工具策略覆盖（`allow`/`deny`/`alsoAllow`）。 +- `channels.msteams.teams..channels..toolsBySender`：每频道每发送者工具策略覆盖（支持 `"*"` 通配符）。 +- `channels.msteams.sharePointSiteId`：用于群聊/频道文件上传的 SharePoint 站点 ID（见[在群聊中发送文件](#sending-files-in-group-chats)）。 -## 路由与会话 +## 路由和会话 -- 会话键遵循标准智能体格式（参见 [/concepts/session](/concepts/session)）： +- 会话键遵循标准智能体格式（见 [/concepts/session](/concepts/session)）： - 私信共享主会话（`agent::`）。 - 频道/群组消息使用会话 ID： - `agent::msteams:channel:` - `agent::msteams:group:` -## 回复样式：线程 vs 帖子 +## 回复样式：话题 vs 帖子 Teams 最近在相同的底层数据模型上引入了两种频道 UI 样式： | 样式 | 描述 | 推荐的 `replyStyle` | | ----------------------- | ------------------------------ | ------------------- | -| **Posts**（经典） | 消息显示为卡片，下方有线程回复 | `thread`（默认） | -| **Threads**（类 Slack） | 消息线性排列，更像 Slack | `top-level` | +| **Posts**（经典） | 消息显示为卡片，下方有话题回复 | `thread`（默认） | +| **Threads**（类 Slack） | 消息线性流动，更像 Slack | `top-level` | -**问题：** Teams API 不暴露频道使用哪种 UI 样式。如果你使用了错误的 `replyStyle`： +**问题：** Teams API 不暴露频道使用的 UI 样式。如果你使用错误的 `replyStyle`： -- 在 Threads 样式的频道中使用 `thread` → 回复嵌套显示不自然 -- 在 Posts 样式的频道中使用 `top-level` → 回复显示为独立的顶级帖子而非在线程中 +- 在 Threads 样式频道中使用 `thread` → 回复嵌套显示很别扭 +- 在 Posts 样式频道中使用 `top-level` → 回复显示为单独的顶级帖子而不是在话题中 -**解决方案：** 根据频道的设置方式按频道配置 `replyStyle`： +**解决方案：** 根据频道的设置方式为每个频道配置 `replyStyle`： ```json { @@ -514,41 +517,43 @@ Teams 最近在相同的底层数据模型上引入了两种频道 UI 样式： } ``` -## 附件与图片 +## 附件和图片 **当前限制：** -- **私信：** 图片和文件附件通过 Teams bot 文件 API 可用。 -- **频道/群组：** 附件存储在 M365 存储（SharePoint/OneDrive）中。Webhook 负载仅包含 HTML 占位符，而非实际文件字节。**需要 Graph API 权限**才能下载频道附件。 +- **私信：** 图片和文件附件通过 Teams bot file API 工作。 +- **频道/群组：** 附件存储在 M365 存储（SharePoint/OneDrive）中。webhook 负载仅包含 HTML 存根，而非实际文件字节。**需要 Graph API 权限**才能下载频道附件。 -没有 Graph 权限时，包含图片的频道消息将仅作为纯文本接收（机器人无法访问图片内容）。默认情况下，OpenClaw 仅从 Microsoft/Teams 主机名下载媒体。通过 `channels.msteams.mediaAllowHosts` 覆盖（使用 `["*"]` 允许任何主机）。 +没有 Graph 权限，带图片的频道消息将作为纯文本接收（机器人无法访问图片内容）。 +默认情况下，OpenClaw 仅从 Microsoft/Teams 主机名下载媒体。使用 `channels.msteams.mediaAllowHosts` 覆盖（使用 `["*"]` 允许任何主机）。 +Authorization 头仅附加到 `channels.msteams.mediaAuthAllowHosts` 中的主机（默认为 Graph + Bot Framework 主机）。保持此列表严格（避免多租户后缀）。 ## 在群聊中发送文件 -机器人可以使用 FileConsentCard 流程在私信中发送文件（内置）。然而，**在群聊/频道中发送文件**需要额外设置： +机器人可以使用 FileConsentCard 流程在私信中发送文件（内置）。但是，**在群聊/频道中发送文件**需要额外设置： -| 场景 | 文件发送方式 | 所需设置 | -| -------------------- | --------------------------------------- | ------------------------------------ | -| **私信** | FileConsentCard → 用户接受 → 机器人上传 | 开箱即用 | -| **群聊/频道** | 上传到 SharePoint → 分享链接 | 需要 `sharePointSiteId` + Graph 权限 | -| **图片（任何场景）** | Base64 编码内联 | 开箱即用 | +| 上下文 | 文件发送方式 | 所需设置 | +| ---------------------- | --------------------------------------- | ------------------------------------ | +| **私信** | FileConsentCard → 用户接受 → 机器人上传 | 开箱即用 | +| **群聊/频道** | 上传到 SharePoint → 共享链接 | 需要 `sharePointSiteId` + Graph 权限 | +| **图片（任何上下文）** | Base64 编码内联 | 开箱即用 | ### 为什么群聊需要 SharePoint -机器人没有个人 OneDrive 驱动器（`/me/drive` Graph API 端点对应用程序标识不可用）。要在群聊/频道中发送文件，机器人上传到 **SharePoint 站点**并创建共享链接。 +机器人没有个人 OneDrive 驱动器（`/me/drive` Graph API 端点对应用程序身份不起作用）。要在群聊/频道中发送文件，机器人上传到 **SharePoint 站点**并创建共享链接。 ### 设置 -1. 在 Entra ID（Azure AD）→ 应用注册中**添加 Graph API 权限**： +1. **在 Entra ID（Azure AD）→ App Registration 中添加 Graph API 权限**： - `Sites.ReadWrite.All`（Application）- 上传文件到 SharePoint - - `Chat.Read.All`（Application）- 可选，启用按用户共享链接 + - `Chat.Read.All`（Application）- 可选，启用每用户共享链接 2. 为租户**授予管理员同意**。 3. **获取你的 SharePoint 站点 ID：** ```bash - # 通过 Graph Explorer 或使用有效 token 的 curl： + # 通过 Graph Explorer 或带有效令牌的 curl： curl -H "Authorization: Bearer $TOKEN" \ "https://graph.microsoft.com/v1.0/sites/{hostname}:/{site-path}" @@ -575,38 +580,38 @@ Teams 最近在相同的底层数据模型上引入了两种频道 UI 样式： | 权限 | 共享行为 | | --------------------------------------- | ------------------------------------------ | -| 仅 `Sites.ReadWrite.All` | 组织范围共享链接（组织中的任何人都可访问） | -| `Sites.ReadWrite.All` + `Chat.Read.All` | 按用户共享链接（仅聊天成员可访问） | +| 仅 `Sites.ReadWrite.All` | 组织范围共享链接（组织中任何人都可以访问） | +| `Sites.ReadWrite.All` + `Chat.Read.All` | 每用户共享链接（仅聊天成员可以访问） | -按用户共享更安全，因为只有聊天参与者可以访问文件。如果缺少 `Chat.Read.All` 权限，机器人回退到组织范围共享。 +每用户共享更安全，因为只有聊天参与者才能访问文件。如果缺少 `Chat.Read.All` 权限，机器人回退到组织范围共享。 ### 回退行为 -| 场景 | 结果 | -| --------------------------------------- | ------------------------------------------ | -| 群聊 + 文件 + 已配置 `sharePointSiteId` | 上传到 SharePoint，发送共享链接 | -| 群聊 + 文件 + 未配置 `sharePointSiteId` | 尝试 OneDrive 上传（可能失败），仅发送文本 | -| 个人聊天 + 文件 | FileConsentCard 流程（无需 SharePoint） | -| 任何场景 + 图片 | Base64 编码内联（无需 SharePoint） | +| 场景 | 结果 | +| --------------------------------------- | ------------------------------------------------ | +| 群聊 + 文件 + 已配置 `sharePointSiteId` | 上传到 SharePoint，发送共享链接 | +| 群聊 + 文件 + 无 `sharePointSiteId` | 尝试 OneDrive 上传（可能失败），仅发送文本 | +| 个人聊天 + 文件 | FileConsentCard 流程（无需 SharePoint 即可工作） | +| 任何上下文 + 图片 | Base64 编码内联（无需 SharePoint 即可工作） | ### 文件存储位置 -上传的文件存储在已配置 SharePoint 站点默认文档库中的 `/OpenClawShared/` 文件夹。 +上传的文件存储在配置的 SharePoint 站点默认文档库中的 `/OpenClawShared/` 文件夹中。 ## 投票（Adaptive Cards） -OpenClaw 通过 Adaptive Cards 发送 Teams 投票（没有原生 Teams 投票 API）。 +OpenClaw 将 Teams 投票作为 Adaptive Cards 发送（没有原生 Teams 投票 API）。 - CLI：`openclaw message poll --channel msteams --target conversation: ...` -- 投票由 Gateway网关记录在 `~/.openclaw/msteams-polls.json` 中。 -- Gateway网关必须保持在线以记录投票。 -- 投票尚不会自动发布结果摘要（如需要请查看存储文件）。 +- 投票由 Gateway 网关记录在 `~/.openclaw/msteams-polls.json` 中。 +- Gateway 网关必须保持在线才能记录投票。 +- 投票尚不自动发布结果摘要（如需要请检查存储文件）。 ## Adaptive Cards（任意） 使用 `message` 工具或 CLI 向 Teams 用户或会话发送任意 Adaptive Card JSON。 -`card` 参数接受 Adaptive Card JSON 对象。提供 `card` 时，消息文本是可选的。 +`card` 参数接受 Adaptive Card JSON 对象。当提供 `card` 时，消息文本是可选的。 **智能体工具：** @@ -631,11 +636,11 @@ openclaw message send --channel msteams \ --card '{"type":"AdaptiveCard","version":"1.5","body":[{"type":"TextBlock","text":"Hello!"}]}' ``` -卡片 schema 和示例请参见 [Adaptive Cards 文档](https://adaptivecards.io/)。目标格式详情请参见下方[目标格式](#目标格式)。 +参见 [Adaptive Cards 文档](https://adaptivecards.io/)了解卡片模式和示例。目标格式详情见下方[目标格式](#target-formats)。 ## 目标格式 -Microsoft Teams 目标使用前缀区分用户和会话： +MSTeams 目标使用前缀来区分用户和会话： | 目标类型 | 格式 | 示例 | | ----------------- | -------------------------------- | ------------------------------------------------- | @@ -685,12 +690,12 @@ openclaw message send --channel msteams --target "conversation:19:abc...@thread. } ``` -注意：不带 `user:` 前缀时，名称默认解析为群组/团队。通过显示名称定位人员时请始终使用 `user:`。 +注意：没有 `user:` 前缀时，名称默认解析为群组/团队。按显示名称定位人员时始终使用 `user:`。 ## 主动消息 -- 主动消息仅在用户**已交互后**才可能，因为我们在那个时候存储会话引用。 -- `dmPolicy` 和允许列表门控请参见 `/gateway/configuration`。 +- 主动消息仅在用户交互**之后**才可能，因为我们在那时存储会话引用。 +- 有关 `dmPolicy` 和允许列表控制，请参见 `/gateway/configuration`。 ## 团队和频道 ID（常见陷阱） @@ -714,8 +719,8 @@ https://teams.microsoft.com/l/channel/19%3A15bc...%40thread.tacv2/ChannelName?gr **用于配置：** -- 团队 ID = `/team/` 后的路径段（URL 解码后，例如 `19:Bk4j...@thread.tacv2`） -- 频道 ID = `/channel/` 后的路径段（URL 解码后） +- 团队 ID = `/team/` 后的路径段（URL 解码，例如 `19:Bk4j...@thread.tacv2`） +- 频道 ID = `/channel/` 后的路径段（URL 解码） - **忽略** `groupId` 查询参数 ## 私有频道 @@ -725,12 +730,12 @@ https://teams.microsoft.com/l/channel/19%3A15bc...%40thread.tacv2/ChannelName?gr | 功能 | 标准频道 | 私有频道 | | ------------------- | -------- | ---------------- | | 机器人安装 | 是 | 有限 | -| 实时消息（webhook） | 是 | 可能不可用 | +| 实时消息（webhook） | 是 | 可能不工作 | | RSC 权限 | 是 | 行为可能不同 | | @提及 | 是 | 如果机器人可访问 | -| Graph API 历史 | 是 | 是（需要权限） | +| Graph API 历史 | 是 | 是（有权限） | -**私有频道不可用时的变通方案：** +**如果私有频道不工作的变通方法：** 1. 使用标准频道进行机器人交互 2. 使用私信 - 用户始终可以直接给机器人发消息 @@ -740,31 +745,31 @@ https://teams.microsoft.com/l/channel/19%3A15bc...%40thread.tacv2/ChannelName?gr ### 常见问题 -- **频道中图片不显示：** Graph 权限或管理员同意缺失。重新安装 Teams 应用并完全退出/重新打开 Teams。 -- **频道中没有响应：** 默认需要提及；设置 `channels.msteams.requireMention=false` 或按团队/频道配置。 -- **版本不匹配（Teams 仍显示旧清单）：** 移除并重新添加应用，完全退出 Teams 以刷新。 -- **Webhook 返回 401 Unauthorized：** 在没有 Azure JWT 的情况下手动测试时这是预期的 - 表示端点可达但认证失败。使用 Azure Web Chat 进行正确测试。 +- **频道中图片不显示：** 缺少 Graph 权限或管理员同意。重新安装 Teams 应用并完全退出/重新打开 Teams。 +- **频道中无响应：** 默认需要提及；设置 `channels.msteams.requireMention=false` 或按团队/频道配置。 +- **版本不匹配（Teams 仍显示旧清单）：** 移除 + 重新添加应用并完全退出 Teams 以刷新。 +- **来自 webhook 的 401 Unauthorized：** 在没有 Azure JWT 的情况下手动测试时属于预期情况 - 意味着端点可达但认证失败。使用 Azure Web Chat 正确测试。 ### 清单上传错误 -- **"Icon file cannot be empty"：** 清单引用了 0 字节的图标文件。创建有效的 PNG 图标（`outline.png` 32x32，`color.png` 192x192）。 -- **"webApplicationInfo.Id already in use"：** 应用仍安装在其他团队/聊天中。先找到并卸载它，或等待 5-10 分钟传播。 -- **上传时显示"Something went wrong"：** 改为通过 https://admin.teams.microsoft.com 上传，打开浏览器 DevTools（F12）→ Network 标签页，检查响应体中的实际错误。 -- **旁加载失败：** 尝试"Upload an app to your org's app catalog"而非"Upload a custom app" - 这通常可以绕过旁加载限制。 +- **"Icon file cannot be empty"：** 清单引用的图标文件为 0 字节。创建有效的 PNG 图标（`outline.png` 为 32x32，`color.png` 为 192x192）。 +- **"webApplicationInfo.Id already in use"：** 应用仍安装在另一个团队/聊天中。先找到并卸载它，或等待 5-10 分钟让其传播。 +- **上传时"Something went wrong"：** 改为通过 https://admin.teams.microsoft.com 上传，打开浏览器 DevTools（F12）→ Network 选项卡，检查响应正文中的实际错误。 +- **侧载失败：** 尝试"Upload an app to your org's app catalog"而不是"Upload a custom app" - 这通常可以绕过侧载限制。 -### RSC 权限不生效 +### RSC 权限不工作 1. 验证 `webApplicationInfo.id` 与你的机器人 App ID 完全匹配 2. 重新上传应用并在团队/聊天中重新安装 3. 检查你的组织管理员是否阻止了 RSC 权限 -4. 确认你使用了正确的范围：`ChannelMessage.Read.Group` 用于团队，`ChatMessage.Read.Chat` 用于群聊 +4. 确认你使用的是正确的范围：团队使用 `ChannelMessage.Read.Group`，群聊使用 `ChatMessage.Read.Chat` -## 参考 +## 参考资料 - [创建 Azure Bot](https://learn.microsoft.com/en-us/azure/bot-service/bot-service-quickstart-registration) - Azure Bot 设置指南 - [Teams 开发者门户](https://dev.teams.microsoft.com/apps) - 创建/管理 Teams 应用 -- [Teams 应用清单 schema](https://learn.microsoft.com/en-us/microsoftteams/platform/resources/schema/manifest-schema) +- [Teams 应用清单模式](https://learn.microsoft.com/en-us/microsoftteams/platform/resources/schema/manifest-schema) - [使用 RSC 接收频道消息](https://learn.microsoft.com/en-us/microsoftteams/platform/bots/how-to/conversations/channel-messages-with-rsc) - [RSC 权限参考](https://learn.microsoft.com/en-us/microsoftteams/platform/graph-api/rsc/resource-specific-consent) -- [Teams bot 文件处理](https://learn.microsoft.com/en-us/microsoftteams/platform/bots/how-to/bots-filesv4)（频道/群组需要 Graph） +- [Teams 机器人文件处理](https://learn.microsoft.com/en-us/microsoftteams/platform/bots/how-to/bots-filesv4)（频道/群组需要 Graph） - [主动消息](https://learn.microsoft.com/en-us/microsoftteams/platform/bots/how-to/conversations/send-proactive-messages) diff --git a/docs/zh-CN/channels/nextcloud-talk.md b/docs/zh-CN/channels/nextcloud-talk.md index 61cec2ef91..e3cad25edf 100644 --- a/docs/zh-CN/channels/nextcloud-talk.md +++ b/docs/zh-CN/channels/nextcloud-talk.md @@ -1,53 +1,54 @@ --- read_when: - - 开发 Nextcloud Talk 渠道功能 + - 开发 Nextcloud Talk 渠道功能时 summary: Nextcloud Talk 支持状态、功能和配置 title: Nextcloud Talk x-i18n: - generated_at: "2026-02-01T19:26:32Z" + generated_at: "2026-02-03T10:04:00Z" model: claude-opus-4-5 provider: pi source_hash: 21b7b9756c4356a76dc0f14c10e44ed74a284cf3badf87e2df75eb88d8a90c31 source_path: channels/nextcloud-talk.md - workflow: 14 + workflow: 15 --- # Nextcloud Talk（插件） -状态：通过插件支持（webhook 机器人）。支持私信、房间、回应和 markdown 消息。 +状态：通过插件支持（webhook 机器人）。支持私信、房间、表情回应和 Markdown 消息。 ## 需要插件 -Nextcloud Talk 作为插件发布，不包含在核心安装中。 +Nextcloud Talk 以插件形式提供，不包含在核心安装包中。 -通过 CLI 安装（npm 注册表）： +通过 CLI 安装（npm 仓库）： ```bash openclaw plugins install @openclaw/nextcloud-talk ``` -本地检出（从 git 仓库运行时）： +本地检出安装（从 git 仓库运行时）： ```bash openclaw plugins install ./extensions/nextcloud-talk ``` -如果你在配置/新手引导期间选择了 Nextcloud Talk 并检测到 git 检出，OpenClaw 会自动提供本地安装路径。 +如果你在配置/新手引导过程中选择了 Nextcloud Talk，并且检测到 git 检出， +OpenClaw 将自动提供本地安装路径。 详情：[插件](/plugin) ## 快速设置（新手） 1. 安装 Nextcloud Talk 插件。 -2. 在你的 Nextcloud 服务器上创建一个机器人： +2. 在你的 Nextcloud 服务器上创建机器人： ```bash ./occ talk:bot:install "OpenClaw" "" "" --feature reaction ``` -3. 在目标房间设置中启用该机器人。 +3. 在目标房间设置中启用机器人。 4. 配置 OpenClaw： - - 配置：`channels.nextcloud-talk.baseUrl` + `channels.nextcloud-talk.botSecret` + - 配置项：`channels.nextcloud-talk.baseUrl` + `channels.nextcloud-talk.botSecret` - 或环境变量：`NEXTCLOUD_TALK_BOT_SECRET`（仅默认账户） -5. 重启 Gateway网关（或完成新手引导）。 +5. 重启 Gateway 网关（或完成新手引导）。 最小配置： @@ -66,23 +67,23 @@ openclaw plugins install ./extensions/nextcloud-talk ## 注意事项 -- 机器人无法主动发起私信。用户必须先给机器人发消息。 -- Webhook URL 必须能被 Gateway网关访问；如果在代理后面，请设置 `webhookPublicUrl`。 +- 机器人无法主动发起私信。用户必须先向机器人发送消息。 +- Webhook URL 必须可被 Gateway 网关访问；如果在代理后面，请设置 `webhookPublicUrl`。 - 机器人 API 不支持媒体上传；媒体以 URL 形式发送。 -- Webhook 负载不区分私信和房间；设置 `apiUser` + `apiPassword` 以启用房间类型查询（否则私信会被视为房间）。 +- Webhook 载荷无法区分私信和房间；设置 `apiUser` + `apiPassword` 以启用房间类型查询（否则私信将被视为房间）。 ## 访问控制（私信） -- 默认：`channels.nextcloud-talk.dmPolicy = "pairing"`。未知发送者会收到配对码。 -- 通过以下方式批准： +- 默认：`channels.nextcloud-talk.dmPolicy = "pairing"`。未知发送者将收到配对码。 +- 批准方式： - `openclaw pairing list nextcloud-talk` - `openclaw pairing approve nextcloud-talk ` - 公开私信：`channels.nextcloud-talk.dmPolicy="open"` 加上 `channels.nextcloud-talk.allowFrom=["*"]`。 ## 房间（群组） -- 默认：`channels.nextcloud-talk.groupPolicy = "allowlist"`（提及门控）。 -- 使用 `channels.nextcloud-talk.rooms` 允许列表中的房间： +- 默认：`channels.nextcloud-talk.groupPolicy = "allowlist"`（需要提及触发）。 +- 使用 `channels.nextcloud-talk.rooms` 设置房间白名单： ```json5 { @@ -96,17 +97,17 @@ openclaw plugins install ./extensions/nextcloud-talk } ``` -- 要不允许任何房间，保持允许列表为空或设置 `channels.nextcloud-talk.groupPolicy="disabled"`。 +- 如需禁止所有房间，保持白名单为空或设置 `channels.nextcloud-talk.groupPolicy="disabled"`。 -## 功能 +## 功能支持 | 功能 | 状态 | | -------- | ------ | | 私信 | 支持 | | 房间 | 支持 | -| 线程 | 不支持 | +| 话题 | 不支持 | | 媒体 | 仅 URL | -| 回应 | 支持 | +| 表情回应 | 支持 | | 原生命令 | 不支持 | ## 配置参考（Nextcloud Talk） @@ -127,15 +128,15 @@ openclaw plugins install ./extensions/nextcloud-talk - `channels.nextcloud-talk.webhookPath`：webhook 路径（默认：/nextcloud-talk-webhook）。 - `channels.nextcloud-talk.webhookPublicUrl`：外部可达的 webhook URL。 - `channels.nextcloud-talk.dmPolicy`：`pairing | allowlist | open | disabled`。 -- `channels.nextcloud-talk.allowFrom`：私信允许列表（用户 ID）。`open` 需要 `"*"`。 +- `channels.nextcloud-talk.allowFrom`：私信白名单（用户 ID）。`open` 需要 `"*"`。 - `channels.nextcloud-talk.groupPolicy`：`allowlist | open | disabled`。 -- `channels.nextcloud-talk.groupAllowFrom`：群组允许列表（用户 ID）。 -- `channels.nextcloud-talk.rooms`：按房间设置和允许列表。 -- `channels.nextcloud-talk.historyLimit`：群组历史限制（0 禁用）。 -- `channels.nextcloud-talk.dmHistoryLimit`：私信历史限制（0 禁用）。 -- `channels.nextcloud-talk.dms`：按私信覆盖（historyLimit）。 -- `channels.nextcloud-talk.textChunkLimit`：出站文本分块大小（字符）。 -- `channels.nextcloud-talk.chunkMode`：`length`（默认）或 `newline`，在按长度分块之前按空行（段落边界）分割。 +- `channels.nextcloud-talk.groupAllowFrom`：群组白名单（用户 ID）。 +- `channels.nextcloud-talk.rooms`：每个房间的设置和白名单。 +- `channels.nextcloud-talk.historyLimit`：群组历史记录限制（0 表示禁用）。 +- `channels.nextcloud-talk.dmHistoryLimit`：私信历史记录限制（0 表示禁用）。 +- `channels.nextcloud-talk.dms`：每个私信的覆盖设置（historyLimit）。 +- `channels.nextcloud-talk.textChunkLimit`：出站文本分块大小（字符数）。 +- `channels.nextcloud-talk.chunkMode`：`length`（默认）或 `newline`，在长度分块前按空行（段落边界）分割。 - `channels.nextcloud-talk.blockStreaming`：禁用此渠道的分块流式传输。 - `channels.nextcloud-talk.blockStreamingCoalesce`：分块流式传输合并调优。 -- `channels.nextcloud-talk.mediaMaxMb`：入站媒体上限（MB）。 +- `channels.nextcloud-talk.mediaMaxMb`：入站媒体大小上限（MB）。 diff --git a/docs/zh-CN/channels/nostr.md b/docs/zh-CN/channels/nostr.md index 73655a1336..7d0359ce21 100644 --- a/docs/zh-CN/channels/nostr.md +++ b/docs/zh-CN/channels/nostr.md @@ -1,37 +1,37 @@ --- read_when: - - 你想让 OpenClaw 通过 Nostr 接收私信 + - 你希望 OpenClaw 通过 Nostr 接收私信 - 你正在设置去中心化消息 summary: 通过 NIP-04 加密消息的 Nostr 私信渠道 title: Nostr x-i18n: - generated_at: "2026-02-01T19:26:55Z" + generated_at: "2026-02-03T07:44:13Z" model: claude-opus-4-5 provider: pi source_hash: 6b9fe4c74bf5e7c0f59bbaa129ec5270fd29a248551a8a9a7dde6cff8fb46111 source_path: channels/nostr.md - workflow: 14 + workflow: 15 --- # Nostr **状态：** 可选插件（默认禁用）。 -Nostr 是一个去中心化的社交网络协议。此渠道使 OpenClaw 能够通过 NIP-04 接收和回复加密私信（私信）。 +Nostr 是一个去中心化的社交网络协议。此渠道使 OpenClaw 能够通过 NIP-04 接收和回复加密私信（DMs）。 ## 安装（按需） ### 新手引导（推荐） - 新手引导向导（`openclaw onboard`）和 `openclaw channels add` 会列出可选的渠道插件。 -- 选择 Nostr 时会提示你按需安装插件。 +- 选择 Nostr 会提示你按需安装插件。 -安装默认行为： +安装默认值： -- **开发渠道 + 可用 git 检出：** 使用本地插件路径。 -- **稳定版/测试版：** 从 npm 下载。 +- **Dev 渠道 + git checkout 可用：** 使用本地插件路径。 +- **Stable/Beta：** 从 npm 下载。 -你始终可以在提示中覆盖此选择。 +你可以随时在提示中覆盖选择。 ### 手动安装 @@ -39,13 +39,13 @@ Nostr 是一个去中心化的社交网络协议。此渠道使 OpenClaw 能够 openclaw plugins install @openclaw/nostr ``` -使用本地检出（开发工作流）： +使用本地 checkout（开发工作流）： ```bash openclaw plugins install --link /extensions/nostr ``` -安装或启用插件后请重启 Gateway网关。 +安装或启用插件后重启 Gateway 网关。 ## 快速设置 @@ -74,7 +74,7 @@ nak key generate export NOSTR_PRIVATE_KEY="nsec1..." ``` -4. 重启 Gateway网关。 +4. 重启 Gateway 网关。 ## 配置参考 @@ -90,7 +90,7 @@ export NOSTR_PRIVATE_KEY="nsec1..." ## 个人资料元数据 -个人资料数据作为 NIP-01 `kind:0` 事件发布。你可以从控制 UI（Channels -> Nostr -> Profile）管理它，或直接在配置中设置。 +个人资料数据作为 NIP-01 `kind:0` 事件发布。你可以从控制界面（Channels -> Nostr -> Profile）管理它，或直接在配置中设置。 示例： @@ -124,9 +124,9 @@ export NOSTR_PRIVATE_KEY="nsec1..." ### 私信策略 - **pairing**（默认）：未知发送者会收到配对码。 -- **allowlist**：只有 `allowFrom` 中的公钥可以发私信。 -- **open**：公开入站私信（需要 `allowFrom: ["*"]`）。 -- **disabled**：忽略入站私信。 +- **allowlist**：只有 `allowFrom` 中的公钥可以发送私信。 +- **open**：公开接收私信（需要 `allowFrom: ["*"]`）。 +- **disabled**：忽略接收的私信。 ### 允许列表示例 @@ -164,20 +164,20 @@ export NOSTR_PRIVATE_KEY="nsec1..." } ``` -建议： +提示： - 使用 2-3 个中继以实现冗余。 - 避免使用过多中继（延迟、重复）。 - 付费中继可以提高可靠性。 -- 本地中继适用于测试（`ws://localhost:7777`）。 +- 本地中继适合测试（`ws://localhost:7777`）。 ## 协议支持 | NIP | 状态 | 描述 | | ------ | ------ | ----------------------------- | -| NIP-01 | 支持 | 基本事件格式 + 个人资料元数据 | -| NIP-04 | 支持 | 加密私信（`kind:4`） | -| NIP-17 | 计划中 | Gift-wrapped 私信 | +| NIP-01 | 已支持 | 基本事件格式 + 个人资料元数据 | +| NIP-04 | 已支持 | 加密私信（`kind:4`） | +| NIP-17 | 计划中 | 礼物包装私信 | | NIP-44 | 计划中 | 版本化加密 | ## 测试 @@ -203,38 +203,38 @@ docker run -p 7777:7777 ghcr.io/hoytech/strfry ### 手动测试 1. 从日志中记下机器人公钥（npub）。 -2. 打开一个 Nostr 客户端（Damus、Amethyst 等）。 -3. 私信机器人公钥。 -4. 验证回复。 +2. 打开 Nostr 客户端（Damus、Amethyst 等）。 +3. 向机器人公钥发送私信。 +4. 验证响应。 ## 故障排除 -### 无法收到消息 +### 未收到消息 - 验证私钥是否有效。 -- 确保中继 URL 可达并使用 `wss://`（本地使用 `ws://`）。 -- 确认 `enabled` 未设为 `false`。 -- 检查 Gateway网关日志中的中继连接错误。 +- 确保中继 URL 可访问并使用 `wss://`（本地使用 `ws://`）。 +- 确认 `enabled` 不是 `false`。 +- 检查 Gateway 网关日志中的中继连接错误。 -### 无法发送回复 +### 未发送响应 - 检查中继是否接受写入。 - 验证出站连接。 - 注意中继速率限制。 -### 重复回复 +### 重复响应 -- 使用多个中继时属于预期行为。 -- 消息按事件 ID 去重；只有第一次投递会触发回复。 +- 使用多个中继时属于正常现象。 +- 消息按事件 ID 去重；只有首次投递会触发响应。 ## 安全 -- 绝不提交私钥。 +- 切勿提交私钥。 - 使用环境变量存储密钥。 -- 生产机器人请考虑使用 `allowlist`。 +- 生产环境机器人考虑使用 `allowlist`。 ## 限制（MVP） -- 仅支持私信（无群聊）。 +- 仅支持私信（不支持群聊）。 - 不支持媒体附件。 -- 仅支持 NIP-04（计划支持 NIP-17 gift-wrap）。 +- 仅支持 NIP-04（计划支持 NIP-17 礼物包装）。 diff --git a/docs/zh-CN/channels/signal.md b/docs/zh-CN/channels/signal.md index 3810e2f450..ec3c0ff13c 100644 --- a/docs/zh-CN/channels/signal.md +++ b/docs/zh-CN/channels/signal.md @@ -1,29 +1,29 @@ --- read_when: - 设置 Signal 支持 - - 调试 Signal 收发 -summary: 通过 signal-cli（JSON-RPC + SSE）实现 Signal 支持、设置和号码模型 + - 调试 Signal 发送/接收 +summary: 通过 signal-cli（JSON-RPC + SSE）支持 Signal，设置和号码模型 title: Signal x-i18n: - generated_at: "2026-02-01T19:27:25Z" + generated_at: "2026-02-03T07:44:15Z" model: claude-opus-4-5 provider: pi source_hash: ca4de8b3685017f54a959e3e2699357ab40b3e4e68574bd7fb5739e4679e7d8a source_path: channels/signal.md - workflow: 14 + workflow: 15 --- -# Signal（signal-cli） +# Signal (signal-cli) -状态：外部 CLI 集成。Gateway网关通过 HTTP JSON-RPC + SSE 与 `signal-cli` 通信。 +状态：外部 CLI 集成。Gateway 网关通过 HTTP JSON-RPC + SSE 与 `signal-cli` 通信。 -## 快速设置（新手） +## 快速设置（初学者） -1. 为机器人使用一个**单独的 Signal 号码**（推荐）。 +1. 为 bot 使用**单独的 Signal 号码**（推荐）。 2. 安装 `signal-cli`（需要 Java）。 -3. 链接机器人设备并启动守护进程： +3. 链接 bot 设备并启动守护进程： - `signal-cli link -n "OpenClaw"` -4. 配置 OpenClaw 并启动 Gateway网关。 +4. 配置 OpenClaw 并启动 Gateway 网关。 最小配置： @@ -44,14 +44,14 @@ x-i18n: ## 它是什么 - 通过 `signal-cli` 的 Signal 渠道（非嵌入式 libsignal）。 -- 确定性路由：回复始终发回 Signal。 +- 确定性路由：回复始终返回到 Signal。 - 私信共享智能体的主会话；群组是隔离的（`agent::signal:group:`）。 ## 配置写入 -默认情况下，Signal 允许通过 `/config set|unset` 触发的配置更新写入（需要 `commands.config: true`）。 +默认情况下，Signal 允许写入由 `/config set|unset` 触发的配置更新（需要 `commands.config: true`）。 -通过以下方式禁用： +禁用方式： ```json5 { @@ -61,16 +61,16 @@ x-i18n: ## 号码模型（重要） -- Gateway网关连接到一个 **Signal 设备**（`signal-cli` 账户）。 -- 如果你在**个人 Signal 账户**上运行机器人，它会忽略你自己的消息（循环保护）。 -- 要实现"我给机器人发消息它回复我"，请使用一个**单独的机器人号码**。 +- Gateway 网关连接到一个 **Signal 设备**（`signal-cli` 账户）。 +- 如果你在**个人 Signal 账户**上运行 bot，它会忽略你自己的消息（循环保护）。 +- 要实现"我发消息给 bot 然后它回复"，请使用**单独的 bot 号码**。 ## 设置（快速路径） 1. 安装 `signal-cli`（需要 Java）。 -2. 链接机器人账户： +2. 链接 bot 账户： - `signal-cli link -n "OpenClaw"` 然后在 Signal 中扫描二维码。 -3. 配置 Signal 并启动 Gateway网关。 +3. 配置 Signal 并启动 Gateway 网关。 示例： @@ -88,11 +88,11 @@ x-i18n: } ``` -多账户支持：使用 `channels.signal.accounts`，每个账户配置独立选项和可选的 `name`。共享模式请参阅 [`gateway/configuration`](/gateway/configuration#telegramaccounts--discordaccounts--slackaccounts--signalaccounts--imessageaccounts)。 +多账户支持：使用 `channels.signal.accounts` 配置每个账户及可选的 `name`。共享模式请参见 [`gateway/configuration`](/gateway/configuration#telegramaccounts--discordaccounts--slackaccounts--signalaccounts--imessageaccounts)。 ## 外部守护进程模式（httpUrl） -如果你想自行管理 `signal-cli`（JVM 冷启动慢、容器初始化或共享 CPU），可以单独运行守护进程并将 OpenClaw 指向它： +如果你想自己管理 `signal-cli`（JVM 冷启动慢、容器初始化或共享 CPU），请单独运行守护进程并将 OpenClaw 指向它： ```json5 { @@ -105,19 +105,19 @@ x-i18n: } ``` -这会跳过 OpenClaw 内部的自动启动和启动等待。当自动启动较慢时，请设置 `channels.signal.startupTimeoutMs`。 +这会跳过自动启动和 OpenClaw 内部的启动等待。对于自动启动时的慢启动，请设置 `channels.signal.startupTimeoutMs`。 ## 访问控制（私信 + 群组） 私信： - 默认：`channels.signal.dmPolicy = "pairing"`。 -- 未知发送者会收到配对码；在批准之前消息会被忽略（配对码 1 小时后过期）。 +- 未知发送者会收到配对码；消息在批准前会被忽略（配对码 1 小时后过期）。 - 通过以下方式批准： - `openclaw pairing list signal` - `openclaw pairing approve signal ` - 配对是 Signal 私信的默认令牌交换方式。详情：[配对](/start/pairing) -- 仅 UUID 的发送者（来自 `sourceUuid`）以 `uuid:` 形式存储在 `channels.signal.allowFrom` 中。 +- 仅有 UUID 的发送者（来自 `sourceUuid`）在 `channels.signal.allowFrom` 中存储为 `uuid:`。 群组： @@ -126,31 +126,31 @@ x-i18n: ## 工作原理（行为） -- `signal-cli` 作为守护进程运行；Gateway网关通过 SSE 读取事件。 -- 入站消息被标准化为共享的渠道信封。 -- 回复始终路由回同一个号码或群组。 +- `signal-cli` 作为守护进程运行；Gateway 网关通过 SSE 读取事件。 +- 入站消息被规范化为共享渠道信封。 +- 回复始终路由回同一号码或群组。 ## 媒体 + 限制 - 出站文本按 `channels.signal.textChunkLimit` 分块（默认 4000）。 -- 可选的换行分块：设置 `channels.signal.chunkMode="newline"` 在按长度分块之前按空行（段落边界）分割。 +- 可选换行分块：设置 `channels.signal.chunkMode="newline"` 在长度分块前按空行（段落边界）分割。 - 支持附件（从 `signal-cli` 获取 base64）。 - 默认媒体上限：`channels.signal.mediaMaxMb`（默认 8）。 -- 使用 `channels.signal.ignoreAttachments` 跳过媒体下载。 -- 群组历史上下文使用 `channels.signal.historyLimit`（或 `channels.signal.accounts.*.historyLimit`），回退到 `messages.groupChat.historyLimit`。设置 `0` 可禁用（默认 50）。 +- 使用 `channels.signal.ignoreAttachments` 跳过下载媒体。 +- 群组历史上下文使用 `channels.signal.historyLimit`（或 `channels.signal.accounts.*.historyLimit`），回退到 `messages.groupChat.historyLimit`。设置 `0` 禁用（默认 50）。 -## 输入指示 + 已读回执 +## 输入指示器 + 已读回执 -- **输入指示**：OpenClaw 通过 `signal-cli sendTyping` 发送输入信号，并在回复运行期间刷新。 +- **输入指示器**：OpenClaw 通过 `signal-cli sendTyping` 发送输入信号，并在回复运行时刷新它们。 - **已读回执**：当 `channels.signal.sendReadReceipts` 为 true 时，OpenClaw 为允许的私信转发已读回执。 -- signal-cli 不暴露群组的已读回执。 +- Signal-cli 不暴露群组的已读回执。 -## 回应（message 工具） +## 表情回应（message 工具） - 使用 `message action=react` 配合 `channel=signal`。 - 目标：发送者 E.164 或 UUID（使用配对输出中的 `uuid:`；裸 UUID 也可以）。 - `messageId` 是你要回应的消息的 Signal 时间戳。 -- 群组回应需要 `targetAuthor` 或 `targetAuthorUuid`。 +- 群组表情回应需要 `targetAuthor` 或 `targetAuthorUuid`。 示例： @@ -162,13 +162,13 @@ message action=react channel=signal target=signal:group: targetAuthor=u 配置： -- `channels.signal.actions.reactions`：启用/禁用回应操作（默认 true）。 +- `channels.signal.actions.reactions`：启用/禁用表情回应操作（默认 true）。 - `channels.signal.reactionLevel`：`off | ack | minimal | extensive`。 - - `off`/`ack` 禁用智能体回应（message 工具 `react` 会报错）。 - - `minimal`/`extensive` 启用智能体回应并设置引导级别。 -- 按账户覆盖：`channels.signal.accounts..actions.reactions`、`channels.signal.accounts..reactionLevel`。 + - `off`/`ack` 禁用智能体表情回应（message 工具 `react` 会报错）。 + - `minimal`/`extensive` 启用智能体表情回应并设置指导级别。 +- 每账户覆盖：`channels.signal.accounts..actions.reactions`、`channels.signal.accounts..reactionLevel`。 -## 投递目标（CLI/定时任务） +## 投递目标（CLI/cron） - 私信：`signal:+15551234567`（或纯 E.164）。 - UUID 私信：`uuid:`（或裸 UUID）。 @@ -182,24 +182,24 @@ message action=react channel=signal target=signal:group: targetAuthor=u 提供商选项： - `channels.signal.enabled`：启用/禁用渠道启动。 -- `channels.signal.account`：机器人账户的 E.164。 +- `channels.signal.account`：bot 账户的 E.164。 - `channels.signal.cliPath`：`signal-cli` 的路径。 - `channels.signal.httpUrl`：完整守护进程 URL（覆盖 host/port）。 - `channels.signal.httpHost`、`channels.signal.httpPort`：守护进程绑定（默认 127.0.0.1:8080）。 -- `channels.signal.autoStart`：自动启动守护进程（未设置 `httpUrl` 时默认 true）。 -- `channels.signal.startupTimeoutMs`：启动等待超时，单位毫秒（上限 120000）。 +- `channels.signal.autoStart`：自动启动守护进程（如果未设置 `httpUrl` 则默认 true）。 +- `channels.signal.startupTimeoutMs`：启动等待超时（毫秒）（上限 120000）。 - `channels.signal.receiveMode`：`on-start | manual`。 - `channels.signal.ignoreAttachments`：跳过附件下载。 - `channels.signal.ignoreStories`：忽略来自守护进程的动态。 - `channels.signal.sendReadReceipts`：转发已读回执。 - `channels.signal.dmPolicy`：`pairing | allowlist | open | disabled`（默认：pairing）。 -- `channels.signal.allowFrom`：私信允许列表（E.164 或 `uuid:`）。`open` 需要 `"*"`。Signal 没有用户名；使用电话/UUID 标识。 +- `channels.signal.allowFrom`：私信允许列表（E.164 或 `uuid:`）。`open` 需要 `"*"`。Signal 没有用户名；使用电话/UUID id。 - `channels.signal.groupPolicy`：`open | allowlist | disabled`（默认：allowlist）。 - `channels.signal.groupAllowFrom`：群组发送者允许列表。 -- `channels.signal.historyLimit`：包含为上下文的最大群组消息数（0 禁用）。 -- `channels.signal.dmHistoryLimit`：私信历史限制（用户回合数）。按用户覆盖：`channels.signal.dms[""].historyLimit`。 +- `channels.signal.historyLimit`：作为上下文包含的最大群组消息数（0 禁用）。 +- `channels.signal.dmHistoryLimit`：私信历史限制（用户轮次）。每用户覆盖：`channels.signal.dms[""].historyLimit`。 - `channels.signal.textChunkLimit`：出站分块大小（字符）。 -- `channels.signal.chunkMode`：`length`（默认）或 `newline`，在按长度分块之前按空行（段落边界）分割。 +- `channels.signal.chunkMode`：`length`（默认）或 `newline` 在长度分块前按空行（段落边界）分割。 - `channels.signal.mediaMaxMb`：入站/出站媒体上限（MB）。 相关全局选项： diff --git a/docs/zh-CN/channels/slack.md b/docs/zh-CN/channels/slack.md index 6472f693a3..d75616486f 100644 --- a/docs/zh-CN/channels/slack.md +++ b/docs/zh-CN/channels/slack.md @@ -1,14 +1,14 @@ --- -read_when: 设置 Slack 或调试 Slack Socket/HTTP 模式 -summary: Slack 的 Socket 或 HTTP webhook 模式设置 +read_when: Setting up Slack or debugging Slack socket/HTTP mode +summary: Slack 的 socket 或 HTTP webhook 模式设置 title: Slack x-i18n: - generated_at: "2026-02-01T19:29:15Z" + generated_at: "2026-02-03T07:45:49Z" model: claude-opus-4-5 provider: pi source_hash: 703b4b4333bebfef26b64710ba452bdfc3e7d2115048d4e552e8659425b3609b source_path: channels/slack.md - workflow: 14 + workflow: 15 --- # Slack @@ -19,7 +19,7 @@ x-i18n: 1. 创建一个 Slack 应用并启用 **Socket Mode**。 2. 创建一个 **App Token**（`xapp-...`）和 **Bot Token**（`xoxb-...`）。 -3. 为 OpenClaw 设置 token 并启动 Gateway网关。 +3. 为 OpenClaw 设置令牌并启动 Gateway 网关。 最小配置： @@ -37,10 +37,10 @@ x-i18n: ### 设置 -1. 在 https://api.slack.com/apps 创建 Slack 应用（从头开始）。 -2. **Socket Mode** → 开启。然后进入 **Basic Information** → **App-Level Tokens** → **Generate Token and Scopes**，使用范围 `connections:write`。复制 **App Token**（`xapp-...`）。 -3. **OAuth & Permissions** → 添加 bot token 范围（使用下方清单）。点击 **Install to Workspace**。复制 **Bot User OAuth Token**（`xoxb-...`）。 -4. 可选：**OAuth & Permissions** → 添加 **User Token Scopes**（参见下方只读列表）。重新安装应用并复制 **User OAuth Token**（`xoxp-...`）。 +1. 在 https://api.slack.com/apps 创建一个 Slack 应用（从头开始）。 +2. **Socket Mode** → 开启。然后前往 **Basic Information** → **App-Level Tokens** → **Generate Token and Scopes**，添加 `connections:write` 权限范围。复制 **App Token**（`xapp-...`）。 +3. **OAuth & Permissions** → 添加 bot token 权限范围（使用下面的 manifest）。点击 **Install to Workspace**。复制 **Bot User OAuth Token**（`xoxb-...`）。 +4. 可选：**OAuth & Permissions** → 添加 **User Token Scopes**（参见下面的只读列表）。重新安装应用并复制 **User OAuth Token**（`xoxp-...`）。 5. **Event Subscriptions** → 启用事件并订阅： - `message.*`（包括编辑/删除/线程广播） - `app_mention` @@ -49,16 +49,16 @@ x-i18n: - `channel_rename` - `pin_added`、`pin_removed` 6. 邀请机器人加入你希望它读取的频道。 -7. Slash Commands → 如果你使用 `channels.slack.slashCommand`，创建 `/openclaw`。如果你启用原生命令，为每个内置命令添加一个斜杠命令（名称与 `/help` 列表相同）。Slack 的原生命令默认关闭，除非你设置 `channels.slack.commands.native: true`（全局 `commands.native` 为 `"auto"`，Slack 下默认关闭）。 -8. App Home → 启用 **Messages Tab** 以便用户可以给机器人发私信。 +7. Slash Commands → 如果你使用 `channels.slack.slashCommand`，创建 `/openclaw`。如果启用原生命令，为每个内置命令添加一个斜杠命令（名称与 `/help` 相同）。除非你设置 `channels.slack.commands.native: true`，否则 Slack 默认关闭原生命令（全局 `commands.native` 是 `"auto"`，对 Slack 保持关闭）。 +8. App Home → 启用 **Messages Tab** 以便用户可以私信机器人。 -使用下方清单以保持范围和事件同步。 +使用下面的 manifest 以保持权限范围和事件同步。 -多账户支持：使用 `channels.slack.accounts`，每个账户配置独立 token 和可选的 `name`。共享模式请参阅 [`gateway/configuration`](/gateway/configuration#telegramaccounts--discordaccounts--slackaccounts--signalaccounts--imessageaccounts)。 +多账户支持：使用 `channels.slack.accounts` 配置每个账户的令牌和可选的 `name`。参见 [`gateway/configuration`](/gateway/configuration#telegramaccounts--discordaccounts--slackaccounts--signalaccounts--imessageaccounts) 了解共享模式。 ### OpenClaw 配置（最小） -通过环境变量设置 token（推荐）： +通过环境变量设置令牌（推荐）： - `SLACK_APP_TOKEN=xapp-...` - `SLACK_BOT_TOKEN=xoxb-...` @@ -77,13 +77,13 @@ x-i18n: } ``` -### 用户 token（可选） +### 用户令牌（可选） -OpenClaw 可以使用 Slack 用户 token（`xoxp-...`）进行读取操作（历史记录、置顶、回应、表情、成员信息）。默认保持只读：有用户 token 时读取操作优先使用它，写入仍使用 bot token，除非你明确选择。即使设置了 `userTokenReadOnly: false`，当 bot token 可用时写入操作仍优先使用它。 +OpenClaw 可以使用 Slack 用户令牌（`xoxp-...`）进行读取操作（历史记录、置顶、表情回应、表情符号、成员信息）。默认情况下保持只读：当存在用户令牌时，读取优先使用用户令牌，而写入仍然使用 bot 令牌，除非你明确选择加入。即使设置了 `userTokenReadOnly: false`，当 bot 令牌可用时，写入仍然优先使用 bot 令牌。 -用户 token 在配置文件中设置（不支持环境变量）。多账户时设置 `channels.slack.accounts..userToken`。 +用户令牌在配置文件中配置（不支持环境变量）。对于多账户，设置 `channels.slack.accounts..userToken`。 -同时使用 bot + app + user token 的示例： +包含 bot + app + 用户令牌的示例： ```json5 { @@ -98,7 +98,7 @@ OpenClaw 可以使用 Slack 用户 token（`xoxp-...`）进行读取操作（历 } ``` -显式设置 userTokenReadOnly 的示例（允许用户 token 写入）： +明确设置 userTokenReadOnly 的示例（允许用户令牌写入）： ```json5 { @@ -114,26 +114,27 @@ OpenClaw 可以使用 Slack 用户 token（`xoxp-...`）进行读取操作（历 } ``` -#### Token 使用 +#### 令牌使用 -- 读取操作（历史记录、回应列表、置顶列表、表情列表、成员信息、搜索）在配置了用户 token 时优先使用，否则使用 bot token。 -- 写入操作（发送/编辑/删除消息、添加/移除回应、置顶/取消置顶、文件上传）默认使用 bot token。如果 `userTokenReadOnly: false` 且没有 bot token 可用，OpenClaw 回退到用户 token。 +- 读取操作（历史记录、表情回应列表、置顶列表、表情符号列表、成员信息、搜索）在配置了用户令牌时优先使用用户令牌，否则使用 bot 令牌。 +- 写入操作（发送/编辑/删除消息、添加/移除表情回应、置顶/取消置顶、文件上传）默认使用 bot 令牌。如果 `userTokenReadOnly: false` 且没有可用的 bot 令牌，OpenClaw 会回退到用户令牌。 ### 历史上下文 -- `channels.slack.historyLimit`（或 `channels.slack.accounts.*.historyLimit`）控制多少条最近的频道/群组消息被包含在提示中。 -- 回退到 `messages.groupChat.historyLimit`。设置 `0` 可禁用（默认 50）。 +- `channels.slack.historyLimit`（或 `channels.slack.accounts.*.historyLimit`）控制将多少条最近的频道/群组消息包含到提示中。 +- 回退到 `messages.groupChat.historyLimit`。设置为 `0` 以禁用（默认 50）。 ## HTTP 模式（Events API） -当你的 Gateway网关可通过 HTTPS 被 Slack 访问时使用 HTTP webhook 模式（适用于服务器部署）。HTTP 模式使用 Events API + Interactivity + Slash Commands，共享请求 URL。 +当你的 Gateway 网关可以通过 HTTPS 被 Slack 访问时（服务器部署的典型情况），使用 HTTP webhook 模式。 +HTTP 模式使用 Events API + Interactivity + Slash Commands，共享一个请求 URL。 ### 设置 -1. 创建 Slack 应用并**禁用 Socket Mode**（如果你只使用 HTTP 则可选）。 +1. 创建一个 Slack 应用并**禁用 Socket Mode**（如果你只使用 HTTP 则可选）。 2. **Basic Information** → 复制 **Signing Secret**。 3. **OAuth & Permissions** → 安装应用并复制 **Bot User OAuth Token**（`xoxb-...`）。 -4. **Event Subscriptions** → 启用事件并将 **Request URL** 设置为你的 Gateway网关 webhook 路径（默认 `/slack/events`）。 +4. **Event Subscriptions** → 启用事件并将 **Request URL** 设置为你的 Gateway 网关 webhook 路径（默认 `/slack/events`）。 5. **Interactivity & Shortcuts** → 启用并设置相同的 **Request URL**。 6. **Slash Commands** → 为你的命令设置相同的 **Request URL**。 @@ -158,9 +159,9 @@ OpenClaw 可以使用 Slack 用户 token（`xoxp-...`）进行读取操作（历 多账户 HTTP 模式：设置 `channels.slack.accounts..mode = "http"` 并为每个账户提供唯一的 `webhookPath`，以便每个 Slack 应用可以指向自己的 URL。 -### 清单（可选） +### Manifest（可选） -使用此 Slack 应用清单可快速创建应用（根据需要调整名称/命令）。如果你计划配置用户 token，请包含用户范围。 +使用此 Slack 应用 manifest 快速创建应用（如果需要可以调整名称/命令）。如果你计划配置用户令牌，请包含用户权限范围。 ```json { @@ -250,23 +251,23 @@ OpenClaw 可以使用 Slack 用户 token（`xoxp-...`）进行读取操作（历 } ``` -如果你启用原生命令，为你想暴露的每个命令添加一个 `slash_commands` 条目（匹配 `/help` 列表）。通过 `channels.slack.commands.native` 覆盖。 +如果启用原生命令，为每个要公开的命令添加一个 `slash_commands` 条目（与 `/help` 列表匹配）。使用 `channels.slack.commands.native` 覆盖。 -## 范围（当前 vs 可选） +## 权限范围（当前 vs 可选） -Slack 的 Conversations API 按类型设定范围：你只需要你实际使用的会话类型（channels、groups、im、mpim）对应的范围。概览请参见 https://docs.slack.dev/apis/web-api/using-the-conversations-api/。 +Slack 的 Conversations API 是按类型区分的：你只需要你实际接触的会话类型（channels、groups、im、mpim）的权限范围。概述参见 https://docs.slack.dev/apis/web-api/using-the-conversations-api/。 -### Bot token 范围（必需） +### Bot 令牌权限范围（必需） - `chat:write`（通过 `chat.postMessage` 发送/更新/删除消息） https://docs.slack.dev/reference/methods/chat.postMessage -- `im:write`（通过 `conversations.open` 打开用户私信） +- `im:write`（通过 `conversations.open` 打开私信用于用户私信） https://docs.slack.dev/reference/methods/conversations.open - `channels:history`、`groups:history`、`im:history`、`mpim:history` https://docs.slack.dev/reference/methods/conversations.history - `channels:read`、`groups:read`、`im:read`、`mpim:read` https://docs.slack.dev/reference/methods/conversations.info -- `users:read`（用户查找） +- `users:read`（用户查询） https://docs.slack.dev/reference/methods/users.info - `reactions:read`、`reactions:write`（`reactions.get` / `reactions.add`） https://docs.slack.dev/reference/methods/reactions.get @@ -279,9 +280,9 @@ Slack 的 Conversations API 按类型设定范围：你只需要你实际使用 - `files:write`（通过 `files.uploadV2` 上传） https://docs.slack.dev/messaging/working-with-files/#upload -### 用户 token 范围（可选，默认只读） +### 用户令牌权限范围（可选，默认只读） -如果你配置了 `channels.slack.userToken`，请在 **User Token Scopes** 下添加这些。 +如果你配置了 `channels.slack.userToken`，在 **User Token Scopes** 下添加这些。 - `channels:history`、`groups:history`、`im:history`、`mpim:history` - `channels:read`、`groups:read`、`im:read`、`mpim:read` @@ -291,19 +292,19 @@ Slack 的 Conversations API 按类型设定范围：你只需要你实际使用 - `emoji:read` - `search:read` -### 目前不需要（但未来可能） +### 目前不需要（但未来可能需要） -- `mpim:write`（仅在我们添加群组私信打开/私信开始功能时需要，通过 `conversations.open`） -- `groups:write`（仅在我们添加私有频道管理时需要：创建/重命名/邀请/归档） -- `chat:write.public`（仅在我们想向机器人未加入的频道发帖时需要） +- `mpim:write`（仅当我们添加群组私信打开/私信启动时通过 `conversations.open`） +- `groups:write`（仅当我们添加私有频道管理时：创建/重命名/邀请/归档） +- `chat:write.public`（仅当我们想发布到机器人未加入的频道时） https://docs.slack.dev/reference/scopes/chat.write.public -- `users:read.email`（仅在我们需要从 `users.info` 获取邮箱字段时需要） +- `users:read.email`（仅当我们需要从 `users.info` 获取邮箱字段时） https://docs.slack.dev/changelog/2017-04-narrowing-email-access -- `files:read`（仅在我们开始列出/读取文件元数据时需要） +- `files:read`（仅当我们开始列出/读取文件元数据时） ## 配置 -Slack 仅使用 Socket Mode（无 HTTP webhook 服务器）。提供两个 token： +Slack 仅使用 Socket Mode（无 HTTP webhook 服务器）。提供两个令牌： ```json { @@ -352,40 +353,40 @@ Slack 仅使用 Socket Mode（无 HTTP webhook 服务器）。提供两个 token } ``` -Token 也可以通过环境变量提供： +令牌也可以通过环境变量提供： - `SLACK_BOT_TOKEN` - `SLACK_APP_TOKEN` -确认回应由 `messages.ackReaction` + `messages.ackReactionScope` 全局控制。使用 `messages.removeAckAfterReply` 在机器人回复后清除确认回应。 +确认表情回应通过 `messages.ackReaction` + `messages.ackReactionScope` 全局控制。使用 `messages.removeAckAfterReply` 在机器人回复后清除确认表情回应。 ## 限制 - 出站文本按 `channels.slack.textChunkLimit` 分块（默认 4000）。 -- 可选的换行分块：设置 `channels.slack.chunkMode="newline"` 在按长度分块之前按空行（段落边界）分割。 -- 媒体上传上限由 `channels.slack.mediaMaxMb` 限制（默认 20）。 +- 可选的换行分块：设置 `channels.slack.chunkMode="newline"` 以在长度分块之前按空行（段落边界）分割。 +- 媒体上传受 `channels.slack.mediaMaxMb` 限制（默认 20）。 ## 回复线程 -默认情况下，OpenClaw 在主频道中回复。使用 `channels.slack.replyToMode` 控制自动线程行为： +默认情况下，OpenClaw 在主频道回复。使用 `channels.slack.replyToMode` 控制自动线程： -| 模式 | 行为 | -| ------- | ------------------------------------------------------------------------------------------------ | -| `off` | **默认。** 在主频道回复。仅在触发消息已在线程中时才在线程中回复。 | -| `first` | 第一条回复进入线程（在触发消息下方），后续回复进入主频道。适用于保持上下文可见同时避免线程杂乱。 | -| `all` | 所有回复都进入线程。保持对话集中但可能降低可见性。 | +| 模式 | 行为 | +| ------- | -------------------------------------------------------------------------------------------- | +| `off` | **默认。** 在主频道回复。仅当触发消息已在线程中时才使用线程。 | +| `first` | 第一条回复进入线程（在触发消息下），后续回复进入主频道。适合保持上下文可见同时避免线程混乱。 | +| `all` | 所有回复都进入线程。保持对话集中但可能降低可见性。 | -该模式同时适用于自动回复和智能体工具调用（`slack sendMessage`）。 +该模式适用于自动回复和智能体工具调用（`slack sendMessage`）。 -### 按聊天类型设置线程 +### 按聊天类型的线程 -你可以通过设置 `channels.slack.replyToModeByChatType` 为不同聊天类型配置不同的线程行为： +你可以通过设置 `channels.slack.replyToModeByChatType` 为每种聊天类型配置不同的线程行为： ```json5 { channels: { slack: { - replyToMode: "off", // 频道默认 + replyToMode: "off", // 频道的默认值 replyToModeByChatType: { direct: "all", // 私信始终使用线程 group: "first", // 群组私信/MPIM 第一条回复使用线程 @@ -399,7 +400,7 @@ Token 也可以通过环境变量提供： - `direct`：一对一私信（Slack `im`） - `group`：群组私信 / MPIM（Slack `mpim`） -- `channel`：标准频道（公共/私有） +- `channel`：标准频道（公开/私有） 优先级： @@ -407,11 +408,11 @@ Token 也可以通过环境变量提供： 2. `replyToMode` 3. 提供商默认值（`off`） -旧版 `channels.slack.dm.replyToMode` 在未设置聊天类型覆盖时仍作为 `direct` 的回退值。 +当未设置聊天类型覆盖时，旧版 `channels.slack.dm.replyToMode` 仍可作为 `direct` 的回退。 示例： -仅私信使用线程： +仅对私信使用线程： ```json5 { @@ -424,7 +425,7 @@ Token 也可以通过环境变量提供： } ``` -群组私信使用线程但频道保持在根级： +对群组私信使用线程但保持频道在根级别： ```json5 { @@ -437,7 +438,7 @@ Token 也可以通过环境变量提供： } ``` -频道使用线程，私信保持在根级： +让频道使用线程，保持私信在根级别： ```json5 { @@ -452,79 +453,79 @@ Token 也可以通过环境变量提供： ### 手动线程标签 -对于精细控制，在智能体回复中使用以下标签： +对于细粒度控制，在智能体响应中使用这些标签： - `[[reply_to_current]]` — 回复触发消息（开始/继续线程）。 -- `[[reply_to:]]` — 回复特定消息 ID。 +- `[[reply_to:]]` — 回复特定的消息 id。 ## 会话 + 路由 -- 私信共享 `main` 会话（与 WhatsApp/Telegram 类似）。 +- 私信共享 `main` 会话（与 WhatsApp/Telegram 相同）。 - 频道映射到 `agent::slack:channel:` 会话。 - 斜杠命令使用 `agent::slack:slash:` 会话（前缀可通过 `channels.slack.slashCommand.sessionPrefix` 配置）。 -- 如果 Slack 不提供 `channel_type`，OpenClaw 从频道 ID 前缀（`D`、`C`、`G`）推断并默认为 `channel` 以保持会话键稳定。 -- 原生命令注册使用 `commands.native`（全局默认 `"auto"` → Slack 关闭），可通过 `channels.slack.commands.native` 按工作区覆盖。文本命令需要独立的 `/...` 消息，可通过 `commands.text: false` 禁用。Slack 斜杠命令在 Slack 应用中管理，不会自动移除。使用 `commands.useAccessGroups: false` 可绕过命令的访问组检查。 +- 如果 Slack 未提供 `channel_type`，OpenClaw 会从频道 ID 前缀（`D`、`C`、`G`）推断并默认为 `channel` 以保持会话键稳定。 +- 原生命令注册使用 `commands.native`（全局默认 `"auto"` → Slack 关闭），可以使用 `channels.slack.commands.native` 按工作空间覆盖。文本命令需要独立的 `/...` 消息，可以使用 `commands.text: false` 禁用。Slack 斜杠命令在 Slack 应用中管理，不会自动移除。使用 `commands.useAccessGroups: false` 绕过命令的访问组检查。 - 完整命令列表 + 配置：[斜杠命令](/tools/slash-commands) ## 私信安全（配对） -- 默认：`channels.slack.dm.policy="pairing"` — 未知私信发送者会收到配对码（1 小时后过期）。 -- 通过 `openclaw pairing approve slack ` 批准。 +- 默认：`channels.slack.dm.policy="pairing"` — 未知的私信发送者会收到配对码（1 小时后过期）。 +- 通过以下方式批准：`openclaw pairing approve slack `。 - 要允许任何人：设置 `channels.slack.dm.policy="open"` 和 `channels.slack.dm.allowFrom=["*"]`。 -- `channels.slack.dm.allowFrom` 接受用户 ID、@用户名或邮箱（启动时当 token 允许时解析）。向导在设置期间当 token 允许时接受用户名并将其解析为 ID。 +- `channels.slack.dm.allowFrom` 接受用户 ID、@用户名或邮箱（在令牌允许时启动时解析）。向导在设置期间接受用户名，并在令牌允许时将其解析为 ID。 ## 群组策略 -- `channels.slack.groupPolicy` 控制频道处理方式（`open|disabled|allowlist`）。 -- `allowlist` 需要频道列在 `channels.slack.channels` 中。 -- 如果你只设置了 `SLACK_BOT_TOKEN`/`SLACK_APP_TOKEN` 且从未创建 `channels.slack` 部分，运行时默认将 `groupPolicy` 设为 `open`。添加 `channels.slack.groupPolicy`、`channels.defaults.groupPolicy` 或频道允许列表来锁定它。 -- 配置向导接受 `#channel` 名称并在可能时将其解析为 ID（公共 + 私有）；如果存在多个匹配，优先选择活跃频道。 -- 启动时，OpenClaw 将允许列表中的频道/用户名称解析为 ID（当 token 允许时）并记录映射；未解析的条目保持原样。 -- 要**不允许任何频道**，设置 `channels.slack.groupPolicy: "disabled"`（或保持空的允许列表）。 +- `channels.slack.groupPolicy` 控制频道处理（`open|disabled|allowlist`）。 +- `allowlist` 要求频道列在 `channels.slack.channels` 中。 +- 如果你只设置了 `SLACK_BOT_TOKEN`/`SLACK_APP_TOKEN` 而从未创建 `channels.slack` 部分，运行时默认将 `groupPolicy` 设为 `open`。添加 `channels.slack.groupPolicy`、`channels.defaults.groupPolicy` 或频道白名单来锁定它。 +- 配置向导接受 `#channel` 名称，并在可能时（公开 + 私有）将其解析为 ID；如果存在多个匹配，它优先选择活跃的频道。 +- 启动时，OpenClaw 将白名单中的频道/用户名解析为 ID（在令牌允许时）并记录映射；未解析的条目按原样保留。 +- 要**不允许任何频道**，设置 `channels.slack.groupPolicy: "disabled"`（或保留空白名单）。 频道选项（`channels.slack.channels.` 或 `channels.slack.channels.`）： - `allow`：当 `groupPolicy="allowlist"` 时允许/拒绝频道。 - `requireMention`：频道的提及门控。 -- `tools`：可选的按频道工具策略覆盖（`allow`/`deny`/`alsoAllow`）。 -- `toolsBySender`：可选的频道内按发送者工具策略覆盖（键为发送者 ID/@用户名/邮箱；支持 `"*"` 通配符）。 +- `tools`：可选的每频道工具策略覆盖（`allow`/`deny`/`alsoAllow`）。 +- `toolsBySender`：频道内可选的每发送者工具策略覆盖（键为发送者 id/@用户名/邮箱；支持 `"*"` 通配符）。 - `allowBots`：允许此频道中机器人发送的消息（默认：false）。 -- `users`：可选的按频道用户允许列表。 +- `users`：可选的每频道用户白名单。 - `skills`：Skills 过滤器（省略 = 所有 Skills，空 = 无）。 -- `systemPrompt`：频道的额外系统提示（与主题/目的合并）。 -- `enabled`：设置 `false` 可禁用频道。 +- `systemPrompt`：频道的额外系统提示（与主题/目的组合）。 +- `enabled`：设置为 `false` 以禁用频道。 ## 投递目标 -在定时任务/CLI 发送中使用： +与 cron/CLI 发送一起使用： - `user:` 用于私信 - `channel:` 用于频道 ## 工具操作 -Slack 工具操作可通过 `channels.slack.actions.*` 控制： +Slack 工具操作可以通过 `channels.slack.actions.*` 进行门控： -| 操作组 | 默认值 | 说明 | -| ---------- | ------ | ------------------- | -| reactions | 启用 | 添加回应 + 列出回应 | -| messages | 启用 | 读取/发送/编辑/删除 | -| pins | 启用 | 置顶/取消置顶/列出 | -| memberInfo | 启用 | 成员信息 | -| emojiList | 启用 | 自定义表情列表 | +| 操作组 | 默认 | 说明 | +| ---------- | ------ | ----------------------- | +| reactions | 已启用 | 表情回应 + 列出表情回应 | +| messages | 已启用 | 读取/发送/编辑/删除 | +| pins | 已启用 | 置顶/取消置顶/列表 | +| memberInfo | 已启用 | 成员信息 | +| emojiList | 已启用 | 自定义表情符号列表 | -## 安全注意事项 +## 安全说明 -- 写入操作默认使用 bot token，以便状态变更操作保持在应用机器人权限和身份范围内。 -- 设置 `userTokenReadOnly: false` 允许在 bot token 不可用时使用用户 token 进行写入操作，这意味着操作以安装用户的访问权限运行。请将用户 token 视为高权限凭据，并严格设置操作门控和允许列表。 -- 如果你启用用户 token 写入，请确保用户 token 包含你预期的写入范围（`chat:write`、`reactions:write`、`pins:write`、`files:write`），否则这些操作会失败。 +- 写入默认使用 bot 令牌，因此状态更改操作保持在应用的机器人权限和身份范围内。 +- 设置 `userTokenReadOnly: false` 允许在 bot 令牌不可用时使用用户令牌进行写入操作，这意味着操作以安装用户的访问权限运行。将用户令牌视为高权限，并保持操作门控和白名单严格。 +- 如果你启用用户令牌写入，请确保用户令牌包含你期望的写入权限范围（`chat:write`、`reactions:write`、`pins:write`、`files:write`），否则这些操作将失败。 -## 注意事项 +## 说明 -- 提及门控通过 `channels.slack.channels` 控制（将 `requireMention` 设为 `true`）；`agents.list[].groupChat.mentionPatterns`（或 `messages.groupChat.mentionPatterns`）也算作提及。 -- 多智能体覆盖：在 `agents.list[].groupChat.mentionPatterns` 上设置每个智能体的模式。 -- 回应通知遵循 `channels.slack.reactionNotifications`（使用 `reactionAllowlist` 配合 `allowlist` 模式）。 -- 机器人发送的消息默认被忽略；通过 `channels.slack.allowBots` 或 `channels.slack.channels..allowBots` 启用。 -- 警告：如果你允许回复其他机器人（`channels.slack.allowBots=true` 或 `channels.slack.channels..allowBots=true`），请使用 `requireMention`、`channels.slack.channels..users` 允许列表和/或在 `AGENTS.md` 和 `SOUL.md` 中设置明确的防护规则来防止机器人之间的回复循环。 -- Slack 工具的回应移除语义请参见 [/tools/reactions](/tools/reactions)。 -- 在权限允许且未超过大小限制时，附件会被下载到媒体存储。 +- 提及门控通过 `channels.slack.channels` 控制（将 `requireMention` 设置为 `true`）；`agents.list[].groupChat.mentionPatterns`（或 `messages.groupChat.mentionPatterns`）也算作提及。 +- 多智能体覆盖：在 `agents.list[].groupChat.mentionPatterns` 上设置每智能体的模式。 +- 表情回应通知遵循 `channels.slack.reactionNotifications`（在 `allowlist` 模式下使用 `reactionAllowlist`）。 +- 默认忽略机器人发送的消息；通过 `channels.slack.allowBots` 或 `channels.slack.channels..allowBots` 启用。 +- 警告：如果你允许回复其他机器人（`channels.slack.allowBots=true` 或 `channels.slack.channels..allowBots=true`），请使用 `requireMention`、`channels.slack.channels..users` 白名单和/或在 `AGENTS.md` 和 `SOUL.md` 中设置明确的防护措施来防止机器人之间的回复循环。 +- 对于 Slack 工具，表情回应移除语义见 [/tools/reactions](/tools/reactions)。 +- 附件在允许且在大小限制内时会下载到媒体存储。 diff --git a/docs/zh-CN/channels/telegram.md b/docs/zh-CN/channels/telegram.md index 4b46a3bfd9..e51418ba58 100644 --- a/docs/zh-CN/channels/telegram.md +++ b/docs/zh-CN/channels/telegram.md @@ -1,30 +1,30 @@ --- read_when: - - 开发 Telegram 功能或 webhook 时 -summary: Telegram 机器人支持状态、功能与配置 + - 开发 Telegram 功能或 webhook +summary: Telegram 机器人支持状态、功能和配置 title: Telegram x-i18n: - generated_at: "2026-02-01T19:54:11Z" + generated_at: "2026-02-03T10:07:32Z" model: claude-opus-4-5 provider: pi - source_hash: 63198fce8c29a1020590d6a3ca142314b30c35d50317b878bf1fb1bfd8d54747 + source_hash: 65da427e5f2383edb674054f8133a5777b2aae8a7c4bd78defa065124090a19c source_path: channels/telegram.md - workflow: 14 + workflow: 15 --- -# Telegram (Bot API) +# Telegram（Bot API） -状态：通过 grammY 实现的机器人私聊 + 群组功能已可用于生产环境。默认使用长轮询；webhook 可选。 +状态：通过 grammY 支持机器人私信和群组，已可用于生产环境。默认使用长轮询；webhook 可选。 -## 快速设置（新手） +## 快速设置（入门） -1. 通过 **@BotFather**（[直达链接](https://t.me/BotFather)）创建机器人。确认用户名确实是 `@BotFather`，然后复制令牌。 -2. 设置令牌： +1. 通过 **@BotFather**（[直达链接](https://t.me/BotFather)）创建机器人。确认用户名确实是 `@BotFather`，然后复制 token。 +2. 设置 token： - 环境变量：`TELEGRAM_BOT_TOKEN=...` - 或配置：`channels.telegram.botToken: "..."`。 - 如果两者都设置了，配置优先（环境变量回退仅适用于默认账户）。 -3. 启动 Gateway网关。 -4. 私聊访问默认为配对模式；首次联系时需批准配对码。 +3. 启动 Gateway 网关。 +4. 私信访问默认使用配对模式；首次联系时需要批准配对码。 最小配置： @@ -40,26 +40,26 @@ x-i18n: } ``` -## 简介 +## 这是什么 -- 由 Gateway网关管理的 Telegram Bot API 渠道。 -- 确定性路由：回复始终发回 Telegram；模型不会选择渠道。 -- 私聊共享智能体的主会话；群组保持隔离（`agent::telegram:group:`）。 +- 一个由 Gateway 网关拥有的 Telegram Bot API 渠道。 +- 确定性路由：回复返回到 Telegram；模型不会选择渠道。 +- 私信共享智能体的主会话；群组保持隔离（`agent::telegram:group:`）。 ## 设置（快速路径） -### 1）创建机器人令牌（BotFather） +### 1）创建机器人 token（BotFather） -1. 打开 Telegram，与 **@BotFather**（[直达链接](https://t.me/BotFather)）对话。确认用户名确实是 `@BotFather`。 -2. 运行 `/newbot`，然后按提示操作（名称 + 以 `bot` 结尾的用户名）。 -3. 复制令牌并安全保存。 +1. 打开 Telegram 并与 **@BotFather**（[直达链接](https://t.me/BotFather)）对话。确认用户名确实是 `@BotFather`。 +2. 运行 `/newbot`，然后按照提示操作（名称 + 以 `bot` 结尾的用户名）。 +3. 复制 token 并安全保存。 可选的 BotFather 设置： -- `/setjoingroups` — 允许/禁止将机器人添加到群组。 -- `/setprivacy` — 控制机器人是否能看到所有群组消息。 +- `/setjoingroups` — 允许/拒绝将机器人添加到群组。 +- `/setprivacy` — 控制机器人是否可以看到所有群组消息。 -### 2）配置令牌（环境变量或配置） +### 2）配置 token（环境变量或配置文件） 示例： @@ -79,34 +79,32 @@ x-i18n: 环境变量选项：`TELEGRAM_BOT_TOKEN=...`（适用于默认账户）。 如果环境变量和配置都设置了，配置优先。 -多账户支持：使用 `channels.telegram.accounts`，为每个账户设置令牌和可选的 `name`。请参阅 [`gateway/configuration`](/gateway/configuration#telegramaccounts--discordaccounts--slackaccounts--signalaccounts--imessageaccounts) 了解通用模式。 +多账户支持：使用 `channels.telegram.accounts`，每个账户有独立的 token 和可选的 `name`。参见 [`gateway/configuration`](/gateway/configuration#telegramaccounts--discordaccounts--slackaccounts--signalaccounts--imessageaccounts) 了解共享模式。 -3. 启动 Gateway网关。当令牌被解析后（配置优先，环境变量回退），Telegram 即启动。 -4. 私聊访问默认为配对模式。机器人首次被联系时需批准配对码。 -5. 对于群组：添加机器人，决定隐私/管理员行为（见下文），然后设置 `channels.telegram.groups` 来控制提及门控 + 白名单。 +3. 启动 Gateway 网关。当 token 解析成功时 Telegram 启动（配置优先，环境变量回退）。 +4. 私信访问默认为配对模式。机器人首次被联系时批准配对码。 +5. 对于群组：添加机器人，决定隐私/管理员行为（见下文），然后设置 `channels.telegram.groups` 来控制提及门控和允许列表。 -## 令牌 + 隐私 + 权限（Telegram 端） +## Token + 隐私 + 权限（Telegram 端） -### 令牌创建（BotFather） +### Token 创建（BotFather） -- `/newbot` 创建机器人并返回令牌（请保密）。 -- 如果令牌泄露，通过 @BotFather 撤销/重新生成令牌并更新配置。 +- `/newbot` 创建机器人并返回 token（请保密）。 +- 如果 token 泄露，通过 @BotFather 撤销/重新生成，并更新你的配置。 ### 群组消息可见性（隐私模式） -Telegram 机器人默认启用**隐私模式**，这会限制它们能接收到的群组消息。 -如果你的机器人必须看到*所有*群组消息，有两种选择： +Telegram 机器人默认启用**隐私模式**，这会限制它们接收哪些群组消息。 +如果你的机器人必须看到*所有*群组消息，有两个选项： -- 使用 `/setprivacy` 禁用隐私模式，**或者** -- 将机器人设为群组**管理员**（管理员机器人可以接收所有消息）。 +- 使用 `/setprivacy` 禁用隐私模式**或** +- 将机器人添加为群组**管理员**（管理员机器人可以接收所有消息）。 -**注意：** 切换隐私模式后，Telegram 要求将机器人从每个群组中移除并重新添加， -更改才能生效。 +**注意：** 当你切换隐私模式时，Telegram 要求将机器人从每个群组中移除并重新添加，更改才能生效。 ### 群组权限（管理员权限） -管理员状态在群组内设置（Telegram 界面）。管理员机器人始终能接收所有 -群组消息，因此如果需要完全可见性，请使用管理员身份。 +管理员状态在群组内设置（Telegram UI）。管理员机器人始终接收所有群组消息，因此如果需要完全可见性，请使用管理员身份。 ## 工作原理（行为） @@ -114,31 +112,31 @@ Telegram 机器人默认启用**隐私模式**，这会限制它们能接收到 - 群组回复默认需要提及（原生 @提及或 `agents.list[].groupChat.mentionPatterns` / `messages.groupChat.mentionPatterns`）。 - 多智能体覆盖：在 `agents.list[].groupChat.mentionPatterns` 上设置每个智能体的模式。 - 回复始终路由回同一个 Telegram 聊天。 -- 长轮询使用 grammY runner，按聊天排序；总体并发受 `agents.defaults.maxConcurrent` 限制。 +- 长轮询使用 grammY runner，每个聊天按顺序处理；总体并发受 `agents.defaults.maxConcurrent` 限制。 - Telegram Bot API 不支持已读回执；没有 `sendReadReceipts` 选项。 ## 草稿流式传输 -OpenClaw 可以使用 `sendMessageDraft` 在 Telegram 私聊中流式传输部分回复。 +OpenClaw 可以在 Telegram 私信中使用 `sendMessageDraft` 流式传输部分回复。 要求： -- 在 @BotFather 中为机器人启用话题模式（论坛话题模式）。 -- 仅限私聊话题（Telegram 在入站消息中包含 `message_thread_id`）。 -- `channels.telegram.streamMode` 未设为 `"off"`（默认：`"partial"`，`"block"` 启用分块草稿更新）。 +- 在 @BotFather 中为机器人启用线程模式（论坛话题模式）。 +- 仅限私聊线程（Telegram 在入站消息中包含 `message_thread_id`）。 +- `channels.telegram.streamMode` 未设置为 `"off"`（默认：`"partial"`，`"block"` 启用分块草稿更新）。 -草稿流式传输仅适用于私聊；Telegram 在群组或频道中不支持此功能。 +草稿流式传输仅限私信；Telegram 在群组或频道中不支持此功能。 ## 格式化（Telegram HTML） - 出站 Telegram 文本使用 `parse_mode: "HTML"`（Telegram 支持的标签子集）。 -- 类 Markdown 输入被渲染为 **Telegram 安全的 HTML**（粗体/斜体/删除线/代码/链接）；块级元素被扁平化为带换行符/项目符号的文本。 +- 类 Markdown 输入被渲染为 **Telegram 安全 HTML**（粗体/斜体/删除线/代码/链接）；块级元素被扁平化为带换行/项目符号的文本。 - 来自模型的原始 HTML 会被转义，以避免 Telegram 解析错误。 -- 如果 Telegram 拒绝 HTML 负载，OpenClaw 会以纯文本重试同一条消息。 +- 如果 Telegram 拒绝 HTML 负载，OpenClaw 会以纯文本重试相同的消息。 ## 命令（原生 + 自定义） -OpenClaw 在启动时将原生命令（如 `/status`、`/reset`、`/model`）注册到 Telegram 的机器人菜单。 +OpenClaw 在启动时向 Telegram 的机器人菜单注册原生命令（如 `/status`、`/reset`、`/model`）。 你可以通过配置向菜单添加自定义命令： ```json5 @@ -146,8 +144,8 @@ OpenClaw 在启动时将原生命令（如 `/status`、`/reset`、`/model`）注 channels: { telegram: { customCommands: [ - { command: "backup", description: "Git backup" }, - { command: "generate", description: "Create an image" }, + { command: "backup", description: "Git 备份" }, + { command: "generate", description: "创建图片" }, ], }, }, @@ -157,29 +155,29 @@ OpenClaw 在启动时将原生命令（如 `/status`、`/reset`、`/model`）注 ## 故障排除 - 日志中出现 `setMyCommands failed` 通常意味着到 `api.telegram.org` 的出站 HTTPS/DNS 被阻止。 -- 如果看到 `sendMessage` 或 `sendChatAction` 失败，请检查 IPv6 路由和 DNS。 +- 如果你看到 `sendMessage` 或 `sendChatAction` 失败，检查 IPv6 路由和 DNS。 更多帮助：[渠道故障排除](/channels/troubleshooting)。 注意： -- 自定义命令**仅为菜单条目**；除非你在其他地方处理它们，否则 OpenClaw 不会实现它们。 -- 命令名称会被规范化（去除前导 `/`，转为小写），且必须匹配 `a-z`、`0-9`、`_`（1–32 个字符）。 -- 自定义命令**不能覆盖原生命令**。冲突会被忽略并记录到日志。 -- 如果 `commands.native` 被禁用，则只注册自定义命令（如果没有自定义命令则清空）。 +- 自定义命令**仅是菜单条目**；除非你在其他地方处理它们，否则 OpenClaw 不会实现它们。 +- 命令名称会被规范化（去除前导 `/`，转为小写），必须匹配 `a-z`、`0-9`、`_`（1-32 个字符）。 +- 自定义命令**不能覆盖原生命令**。冲突会被忽略并记录日志。 +- 如果禁用了 `commands.native`，则只注册自定义命令（如果没有则清空）。 ## 限制 - 出站文本按 `channels.telegram.textChunkLimit` 分块（默认 4000）。 -- 可选的换行分块：设置 `channels.telegram.chunkMode="newline"` 以在空行（段落边界）处拆分，然后再按长度分块。 +- 可选的换行分块：设置 `channels.telegram.chunkMode="newline"` 在长度分块之前按空行（段落边界）分割。 - 媒体下载/上传受 `channels.telegram.mediaMaxMb` 限制（默认 5）。 -- Telegram Bot API 请求在 `channels.telegram.timeoutSeconds` 后超时（通过 grammY 默认 500）。设置更低的值以避免长时间挂起。 -- 群组历史上下文使用 `channels.telegram.historyLimit`（或 `channels.telegram.accounts.*.historyLimit`），回退到 `messages.groupChat.historyLimit`。设为 `0` 以禁用（默认 50）。 -- 私聊历史可通过 `channels.telegram.dmHistoryLimit`（用户轮次）限制。按用户覆盖：`channels.telegram.dms[""].historyLimit`。 +- Telegram Bot API 请求在 `channels.telegram.timeoutSeconds` 后超时（通过 grammY 默认 500）。设置较低的值以避免长时间挂起。 +- 群组历史上下文使用 `channels.telegram.historyLimit`（或 `channels.telegram.accounts.*.historyLimit`），回退到 `messages.groupChat.historyLimit`。设置 `0` 禁用（默认 50）。 +- 私信历史可以用 `channels.telegram.dmHistoryLimit`（用户轮次）限制。每用户覆盖：`channels.telegram.dms[""].historyLimit`。 ## 群组激活模式 -默认情况下，机器人在群组中只响应提及（`@botname` 或 `agents.list[].groupChat.mentionPatterns` 中的模式）。要更改此行为： +默认情况下，机器人只响应群组中的提及（`@botname` 或 `agents.list[].groupChat.mentionPatterns` 中的模式）。要更改此行为： ### 通过配置（推荐） @@ -188,31 +186,31 @@ OpenClaw 在启动时将原生命令（如 `/status`、`/reset`、`/model`）注 channels: { telegram: { groups: { - "-1001234567890": { requireMention: false }, // 在此群组中始终回复 + "-1001234567890": { requireMention: false }, // 在此群组中始终响应 }, }, }, } ``` -**重要：** 设置 `channels.telegram.groups` 会创建一个**白名单** - 只有列出的群组（或 `"*"`）会被接受。 -论坛话题继承其父群组配置（allowFrom、requireMention、skills、prompts），除非你在 `channels.telegram.groups..topics.` 下添加每个话题的覆盖。 +**重要：** 设置 `channels.telegram.groups` 会创建一个**允许列表** - 只有列出的群组（或 `"*"`）会被接受。 +论坛话题继承其父群组配置（allowFrom、requireMention、skills、prompts），除非你在 `channels.telegram.groups..topics.` 下添加每话题覆盖。 -允许所有群组且始终回复： +要允许所有群组并始终响应： ```json5 { channels: { telegram: { groups: { - "*": { requireMention: false }, // 所有群组，始终回复 + "*": { requireMention: false }, // 所有群组，始终响应 }, }, }, } ``` -保持所有群组仅提及时回复（默认行为）： +要保持所有群组仅提及响应（默认行为）： ```json5 { @@ -230,26 +228,26 @@ OpenClaw 在启动时将原生命令（如 `/status`、`/reset`、`/model`）注 在群组中发送： -- `/activation always` - 回复所有消息 +- `/activation always` - 响应所有消息 - `/activation mention` - 需要提及（默认） -**注意：** 命令仅更新会话状态。要在重启后保持行为，请使用配置。 +**注意：** 命令只更新会话状态。要在重启后保持持久行为，请使用配置。 ### 获取群组聊天 ID -将群组中的任意消息转发给 Telegram 上的 `@userinfobot` 或 `@getidsbot`，即可看到聊天 ID（负数，如 `-1001234567890`）。 +将群组中的任何消息转发给 Telegram 上的 `@userinfobot` 或 `@getidsbot` 以查看聊天 ID（负数，如 `-1001234567890`）。 -**提示：** 要获取你自己的用户 ID，私聊机器人，它会回复你的用户 ID（配对消息），或者在命令启用后使用 `/whoami`。 +**提示：** 要获取你自己的用户 ID，私信机器人，它会回复你的用户 ID（配对消息），或者在命令启用后使用 `/whoami`。 -**隐私提示：** `@userinfobot` 是第三方机器人。如果你更注重隐私，可以将机器人添加到群组，发送一条消息，然后使用 `openclaw logs --follow` 读取 `chat.id`，或使用 Bot API 的 `getUpdates`。 +**隐私注意：** `@userinfobot` 是第三方机器人。如果你更倾向于其他方式，将机器人添加到群组，发送一条消息，然后使用 `openclaw logs --follow` 读取 `chat.id`，或使用 Bot API `getUpdates`。 ## 配置写入 默认情况下，Telegram 允许写入由渠道事件或 `/config set|unset` 触发的配置更新。 -以下情况会发生配置写入： +这发生在以下情况： -- 群组升级为超级群组时，Telegram 发出 `migrate_to_chat_id`（聊天 ID 变更）。OpenClaw 可以自动迁移 `channels.telegram.groups`。 +- 群组升级为超级群组，Telegram 发出 `migrate_to_chat_id`（聊天 ID 更改）。OpenClaw 可以自动迁移 `channels.telegram.groups`。 - 你在 Telegram 聊天中运行 `/config set` 或 `/config unset`（需要 `commands.config: true`）。 禁用方式： @@ -264,14 +262,14 @@ OpenClaw 在启动时将原生命令（如 `/status`、`/reset`、`/model`）注 Telegram 论坛话题在每条消息中包含 `message_thread_id`。OpenClaw： -- 将 `:topic:` 追加到 Telegram 群组会话键，使每个话题相互隔离。 -- 发送输入指示器和回复时携带 `message_thread_id`，确保回复留在话题内。 -- 通用话题（thread id `1`）比较特殊：消息发送时省略 `message_thread_id`（Telegram 会拒绝），但输入指示器仍包含它。 -- 在模板上下文中暴露 `MessageThreadId` + `IsForum`，用于路由/模板。 -- 话题级配置可在 `channels.telegram.groups..topics.` 下设置（skills、白名单、自动回复、系统提示词、禁用）。 -- 话题配置继承群组设置（requireMention、白名单、skills、提示词、enabled），除非按话题覆盖。 +- 将 `:topic:` 附加到 Telegram 群组会话键，使每个话题隔离。 +- 发送输入指示器和回复时带上 `message_thread_id`，使响应保持在话题内。 +- 通用话题（线程 id `1`）是特殊的：消息发送省略 `message_thread_id`（Telegram 会拒绝），但输入指示器仍然包含它。 +- 在模板上下文中暴露 `MessageThreadId` + `IsForum` 用于路由/模板。 +- 话题特定配置可在 `channels.telegram.groups..topics.` 下设置（skills、允许列表、自动回复、系统提示、禁用）。 +- 话题配置继承群组设置（requireMention、允许列表、skills、提示、enabled），除非每话题覆盖。 -私聊在某些边缘情况下可能包含 `message_thread_id`。OpenClaw 保持私聊会话键不变，但在存在 thread id 时仍将其用于回复/草稿流式传输。 +私聊在某些边缘情况下可能包含 `message_thread_id`。OpenClaw 保持私信会话键不变，但在存在线程 id 时仍将其用于回复/草稿流式传输。 ## 内联按钮 @@ -289,7 +287,7 @@ Telegram 支持带回调按钮的内联键盘。 } ``` -按账户配置： +对于每账户配置： ```json5 { @@ -310,30 +308,30 @@ Telegram 支持带回调按钮的内联键盘。 作用域： - `off` — 禁用内联按钮 -- `dm` — 仅私聊（群组目标被阻止） -- `group` — 仅群组（私聊目标被阻止） -- `all` — 私聊 + 群组 -- `allowlist` — 私聊 + 群组，但仅限 `allowFrom`/`groupAllowFrom` 允许的发送者（与控制命令规则相同） +- `dm` — 仅私信（群组目标被阻止） +- `group` — 仅群组（私信目标被阻止） +- `all` — 私信 + 群组 +- `allowlist` — 私信 + 群组，但仅限 `allowFrom`/`groupAllowFrom` 允许的发送者（与控制命令规则相同） -默认值：`allowlist`。 +默认：`allowlist`。 旧版：`capabilities: ["inlineButtons"]` = `inlineButtons: "all"`。 ### 发送按钮 -使用消息工具的 `buttons` 参数： +使用带 `buttons` 参数的消息工具： ```json5 { action: "send", channel: "telegram", to: "123456789", - message: "Choose an option:", + message: "选择一个选项：", buttons: [ [ - { text: "Yes", callback_data: "yes" }, - { text: "No", callback_data: "no" }, + { text: "是", callback_data: "yes" }, + { text: "否", callback_data: "no" }, ], - [{ text: "Cancel", callback_data: "cancel" }], + [{ text: "取消", callback_data: "cancel" }], ], } ``` @@ -343,75 +341,75 @@ Telegram 支持带回调按钮的内联键盘。 ### 配置选项 -Telegram 功能可在两个层级配置（上面展示了对象形式；旧版字符串数组仍受支持）： +Telegram 功能可以在两个级别配置（上面显示的对象形式；旧版字符串数组仍然支持）： -- `channels.telegram.capabilities`：全局默认功能配置，应用于所有 Telegram 账户，除非被覆盖。 -- `channels.telegram.accounts..capabilities`：按账户的功能配置，覆盖该账户的全局默认值。 +- `channels.telegram.capabilities`：应用于所有 Telegram 账户的全局默认功能配置，除非被覆盖。 +- `channels.telegram.accounts..capabilities`：每账户功能，覆盖该特定账户的全局默认值。 -当所有 Telegram 机器人/账户应具有相同行为时，使用全局设置。当不同机器人需要不同行为时，使用按账户配置（例如，一个账户只处理私聊，另一个允许在群组中使用）。 +当所有 Telegram 机器人/账户应具有相同行为时使用全局设置。当不同机器人需要不同行为时使用每账户配置（例如，一个账户只处理私信，而另一个允许在群组中使用）。 -## 访问控制（私聊 + 群组） +## 访问控制（私信 + 群组） -### 私聊访问 +### 私信访问 -- 默认：`channels.telegram.dmPolicy = "pairing"`。未知发送者会收到配对码；消息在批准前被忽略（配对码 1 小时后过期）。 +- 默认：`channels.telegram.dmPolicy = "pairing"`。未知发送者收到配对码；在批准之前消息被忽略（配对码 1 小时后过期）。 - 批准方式： - `openclaw pairing list telegram` - `openclaw pairing approve telegram ` -- 配对是 Telegram 私聊使用的默认令牌交换方式。详情：[配对](/start/pairing) -- `channels.telegram.allowFrom` 接受数字用户 ID（推荐）或 `@username` 条目。这**不是**机器人用户名；请使用人类发送者的 ID。向导接受 `@username` 并在可能时将其解析为数字 ID。 +- 配对是 Telegram 私信使用的默认 token 交换。详情：[配对](/start/pairing) +- `channels.telegram.allowFrom` 接受数字用户 ID（推荐）或 `@username` 条目。这**不是**机器人用户名；使用人类发送者的 ID。向导接受 `@username` 并在可能时将其解析为数字 ID。 #### 查找你的 Telegram 用户 ID -更安全的方式（无需第三方机器人）： +更安全（无第三方机器人）： -1. 启动 Gateway网关并私聊你的机器人。 +1. 启动 Gateway 网关并私信你的机器人。 2. 运行 `openclaw logs --follow` 并查找 `from.id`。 -替代方式（官方 Bot API）： +备选（官方 Bot API）： -1. 私聊你的机器人。 -2. 使用你的机器人令牌获取更新，并读取 `message.from.id`： +1. 私信你的机器人。 +2. 使用你的机器人 token 获取更新并读取 `message.from.id`： ```bash curl "https://api.telegram.org/bot/getUpdates" ``` -第三方方式（隐私性较低）： +第三方（隐私性较低）： -- 私聊 `@userinfobot` 或 `@getidsbot` 并使用返回的用户 ID。 +- 私信 `@userinfobot` 或 `@getidsbot` 并使用返回的用户 id。 ### 群组访问 两个独立的控制： -**1. 允许哪些群组**（通过 `channels.telegram.groups` 的群组白名单）： +**1. 允许哪些群组**（通过 `channels.telegram.groups` 的群组允许列表）： -- 没有 `groups` 配置 = 允许所有群组 +- 无 `groups` 配置 = 允许所有群组 - 有 `groups` 配置 = 只允许列出的群组或 `"*"` - 示例：`"groups": { "-1001234567890": {}, "*": {} }` 允许所有群组 **2. 允许哪些发送者**（通过 `channels.telegram.groupPolicy` 的发送者过滤）： -- `"open"` = 允许的群组中所有发送者都可以发消息 +- `"open"` = 允许群组中的所有发送者发消息 - `"allowlist"` = 只有 `channels.telegram.groupAllowFrom` 中的发送者可以发消息 -- `"disabled"` = 完全不接受群组消息 - 默认为 `groupPolicy: "allowlist"`（除非添加 `groupAllowFrom`，否则被阻止）。 +- `"disabled"` = 不接受任何群组消息 + 默认是 `groupPolicy: "allowlist"`（除非添加 `groupAllowFrom` 否则被阻止）。 大多数用户需要：`groupPolicy: "allowlist"` + `groupAllowFrom` + 在 `channels.telegram.groups` 中列出特定群组 ## 长轮询 vs webhook -- 默认：长轮询（不需要公网 URL）。 +- 默认：长轮询（不需要公共 URL）。 - Webhook 模式：设置 `channels.telegram.webhookUrl` 和 `channels.telegram.webhookSecret`（可选 `channels.telegram.webhookPath`）。 - - 本地监听器绑定到 `0.0.0.0:8787`，默认服务 `POST /telegram-webhook`。 - - 如果你的公网 URL 不同，请使用反向代理并将 `channels.telegram.webhookUrl` 指向公网端点。 + - 本地监听器绑定到 `0.0.0.0:8787`，默认服务于 `POST /telegram-webhook`。 + - 如果你的公共 URL 不同，使用反向代理并将 `channels.telegram.webhookUrl` 指向公共端点。 ## 回复线程 Telegram 通过标签支持可选的线程回复： - `[[reply_to_current]]` -- 回复触发消息。 -- `[[reply_to:]]` -- 回复特定消息 ID。 +- `[[reply_to:]]` -- 回复特定消息 id。 通过 `channels.telegram.replyToMode` 控制： @@ -419,17 +417,16 @@ Telegram 通过标签支持可选的线程回复： ## 音频消息（语音 vs 文件） -Telegram 区分**语音消息**（圆形气泡）和**音频文件**（元数据卡片）。 -OpenClaw 默认使用音频文件以保持向后兼容。 +Telegram 区分**语音备忘录**（圆形气泡）和**音频文件**（元数据卡片）。 +OpenClaw 默认使用音频文件以保持向后兼容性。 -要在智能体回复中强制使用语音消息气泡，在回复中的任意位置包含此标签： +要在智能体回复中强制使用语音备忘录气泡，在回复中的任何位置包含此标签： -- `[[audio_as_voice]]` — 以语音消息而非文件形式发送音频。 +- `[[audio_as_voice]]` — 将音频作为语音备忘录而不是文件发送。 -该标签会从发送的文本中移除。其他渠道会忽略此标签。 +该标签会从发送的文本中去除。其他渠道会忽略此标签。 -对于消息工具发送，设置 `asVoice: true` 并附带兼容语音的音频 `media` URL -（当有 media 时 `message` 为可选）： +对于消息工具发送，设置 `asVoice: true` 并配合兼容语音的音频 `media` URL（当存在 media 时 `message` 是可选的）： ```json5 { @@ -443,34 +440,34 @@ OpenClaw 默认使用音频文件以保持向后兼容。 ## 贴纸 -OpenClaw 支持接收和发送 Telegram 贴纸，并带有智能缓存。 +OpenClaw 支持接收和发送 Telegram 贴纸，并具有智能缓存功能。 ### 接收贴纸 -当用户发送贴纸时，OpenClaw 根据贴纸类型进行处理： +当用户发送贴纸时，OpenClaw 根据贴纸类型处理： -- **静态贴纸（WEBP）：** 下载并通过视觉能力处理。贴纸在消息内容中显示为 `` 占位符。 -- **动态贴纸（TGS）：** 跳过（不支持 Lottie 格式处理）。 -- **视频贴纸（WEBM）：** 跳过（不支持视频格式处理）。 +- **静态贴纸（WEBP）：** 下载并通过视觉处理。贴纸在消息内容中显示为 `` 占位符。 +- **动画贴纸（TGS）：** 跳过（Lottie 格式不支持处理）。 +- **视频贴纸（WEBM）：** 跳过（视频格式不支持处理）。 接收贴纸时可用的模板上下文字段： - `Sticker` — 包含以下属性的对象： - - `emoji` — 与贴纸关联的表情 + - `emoji` — 与贴纸关联的表情符号 - `setName` — 贴纸集名称 - - `fileId` — Telegram 文件 ID（可用于发回同一贴纸） + - `fileId` — Telegram 文件 ID（用于发送相同贴纸） - `fileUniqueId` — 用于缓存查找的稳定 ID - `cachedDescription` — 可用时的缓存视觉描述 ### 贴纸缓存 -贴纸通过 AI 的视觉能力处理以生成描述。由于相同的贴纸经常被重复发送，OpenClaw 会缓存这些描述以避免冗余的 API 调用。 +贴纸通过 AI 的视觉功能处理以生成描述。由于相同的贴纸经常重复发送，OpenClaw 缓存这些描述以避免冗余的 API 调用。 **工作原理：** 1. **首次遇到：** 贴纸图像被发送给 AI 进行视觉分析。AI 生成描述（例如"一只卡通猫热情地挥手"）。 -2. **缓存存储：** 描述与贴纸的文件 ID、表情和集合名称一起保存。 -3. **后续遇到：** 再次看到同一贴纸时，直接使用缓存的描述，不再将图像发送给 AI。 +2. **缓存存储：** 描述与贴纸的文件 ID、表情符号和集合名称一起保存。 +3. **后续遇到：** 当再次看到相同贴纸时，直接使用缓存的描述。图像不会发送给 AI。 **缓存位置：** `~/.openclaw/telegram/sticker-cache.json` @@ -482,22 +479,22 @@ OpenClaw 支持接收和发送 Telegram 贴纸，并带有智能缓存。 "fileUniqueId": "AgADBAADb6cxG2Y", "emoji": "👋", "setName": "CoolCats", - "description": "A cartoon cat waving enthusiastically", + "description": "一只卡通猫热情地挥手", "cachedAt": "2026-01-15T10:30:00.000Z" } ``` -**优势：** +**优点：** -- 通过避免对同一贴纸重复调用视觉能力来降低 API 成本 -- 缓存贴纸的响应速度更快（无视觉处理延迟） -- 支持基于缓存描述的贴纸搜索功能 +- 通过避免对相同贴纸重复调用视觉 API 来降低 API 成本 +- 缓存贴纸响应更快（无视觉处理延迟） +- 基于缓存描述启用贴纸搜索功能 -缓存在接收贴纸时自动填充，无需手动管理。 +缓存在接收贴纸时自动填充。无需手动缓存管理。 ### 发送贴纸 -智能体可以使用 `sticker` 和 `sticker-search` 动作发送和搜索贴纸。这些功能默认禁用，必须在配置中启用： +智能体可以使用 `sticker` 和 `sticker-search` 动作发送和搜索贴纸。这些默认禁用，必须在配置中启用： ```json5 { @@ -524,24 +521,24 @@ OpenClaw 支持接收和发送 Telegram 贴纸，并带有智能缓存。 参数： -- `fileId`（必填）— 贴纸的 Telegram 文件 ID。可从接收贴纸时的 `Sticker.fileId` 获取，或从 `sticker-search` 结果获取。 +- `fileId`（必需）— 贴纸的 Telegram 文件 ID。从接收贴纸时的 `Sticker.fileId` 获取，或从 `sticker-search` 结果获取。 - `replyTo`（可选）— 要回复的消息 ID。 - `threadId`（可选）— 论坛话题的消息线程 ID。 **搜索贴纸：** -智能体可以通过描述、表情或集合名称搜索缓存的贴纸： +智能体可以按描述、表情符号或集合名称搜索缓存的贴纸： ```json5 { action: "sticker-search", channel: "telegram", - query: "cat waving", + query: "猫 挥手", limit: 5, } ``` -从缓存返回匹配的贴纸： +返回缓存中匹配的贴纸： ```json5 { @@ -551,14 +548,14 @@ OpenClaw 支持接收和发送 Telegram 贴纸，并带有智能缓存。 { fileId: "CAACAgIAAxkBAAI...", emoji: "👋", - description: "A cartoon cat waving enthusiastically", + description: "一只卡通猫热情地挥手", setName: "CoolCats", }, ], } ``` -搜索使用跨描述文本、表情字符和集合名称的模糊匹配。 +搜索在描述文本、表情符号字符和集合名称之间使用模糊匹配。 **带线程的示例：** @@ -575,73 +572,72 @@ OpenClaw 支持接收和发送 Telegram 贴纸，并带有智能缓存。 ## 流式传输（草稿） -Telegram 可以在智能体生成回复时流式传输**草稿气泡**。 -OpenClaw 使用 Bot API 的 `sendMessageDraft`（非真实消息），然后将 -最终回复作为普通消息发送。 +Telegram 可以在智能体生成响应时流式传输**草稿气泡**。 +OpenClaw 使用 Bot API `sendMessageDraft`（不是真实消息），然后将最终回复作为普通消息发送。 要求（Telegram Bot API 9.3+）： - **启用话题的私聊**（机器人的论坛话题模式）。 -- 入站消息必须包含 `message_thread_id`（私聊话题线程）。 -- 群组/超级群组/频道中的流式传输会被忽略。 +- 入站消息必须包含 `message_thread_id`（私有话题线程）。 +- 群组/超级群组/频道的流式传输被忽略。 配置： - `channels.telegram.streamMode: "off" | "partial" | "block"`（默认：`partial`） - `partial`：用最新的流式文本更新草稿气泡。 - - `block`：以更大的块更新草稿气泡（分块）。 + - `block`：以较大块（分块）更新草稿气泡。 - `off`：禁用草稿流式传输。 -- 可选（仅适用于 `streamMode: "block"`）： +- 可选（仅用于 `streamMode: "block"`）： - `channels.telegram.draftChunk: { minChars?, maxChars?, breakPreference? }` - - 默认值：`minChars: 200`、`maxChars: 800`、`breakPreference: "paragraph"`（受 `channels.telegram.textChunkLimit` 限制）。 + - 默认值：`minChars: 200`、`maxChars: 800`、`breakPreference: "paragraph"`（限制在 `channels.telegram.textChunkLimit` 内）。 注意：草稿流式传输与**分块流式传输**（渠道消息）不同。 -分块流式传输默认关闭，如果你想要提前的 Telegram 消息而非草稿更新，需要设置 `channels.telegram.blockStreaming: true`。 +分块流式传输默认关闭，如果你想要早期 Telegram 消息而不是草稿更新，需要 `channels.telegram.blockStreaming: true`。 -推理流式传输（仅 Telegram）： +推理流（仅限 Telegram）： -- `/reasoning stream` 在回复生成时将推理过程流式传输到草稿气泡中，然后发送不包含推理过程的最终答案。 -- 如果 `channels.telegram.streamMode` 为 `off`，推理流式传输将被禁用。 +- `/reasoning stream` 在回复生成时将推理流式传输到草稿气泡中，然后发送不带推理的最终答案。 +- 如果 `channels.telegram.streamMode` 为 `off`，推理流被禁用。 更多上下文：[流式传输 + 分块](/concepts/streaming)。 ## 重试策略 -出站 Telegram API 调用在遇到瞬态网络/429 错误时会以指数退避和抖动进行重试。通过 `channels.telegram.retry` 配置。参见[重试策略](/concepts/retry)。 +出站 Telegram API 调用在遇到临时网络/429 错误时会以指数退避和抖动进行重试。通过 `channels.telegram.retry` 配置。参见[重试策略](/concepts/retry)。 -## 智能体工具（消息 + 表情回应） +## 智能体工具（消息 + 反应） -- 工具：`telegram`，`sendMessage` 动作（`to`、`content`，可选 `mediaUrl`、`replyToMessageId`、`messageThreadId`）。 -- 工具：`telegram`，`react` 动作（`chatId`、`messageId`、`emoji`）。 -- 工具：`telegram`，`deleteMessage` 动作（`chatId`、`messageId`）。 -- 表情回应移除语义：参见 [/tools/reactions](/tools/reactions)。 +- 工具：`telegram`，使用 `sendMessage` 动作（`to`、`content`，可选 `mediaUrl`、`replyToMessageId`、`messageThreadId`）。 +- 工具：`telegram`，使用 `react` 动作（`chatId`、`messageId`、`emoji`）。 +- 工具：`telegram`，使用 `deleteMessage` 动作（`chatId`、`messageId`）。 +- 反应移除语义：参见 [/tools/reactions](/tools/reactions)。 - 工具门控：`channels.telegram.actions.reactions`、`channels.telegram.actions.sendMessage`、`channels.telegram.actions.deleteMessage`（默认：启用），以及 `channels.telegram.actions.sticker`（默认：禁用）。 -## 表情回应通知 +## 反应通知 -**表情回应的工作原理：** -Telegram 表情回应作为**独立的 `message_reaction` 事件**到达，而非消息负载中的属性。当用户添加表情回应时，OpenClaw： +**反应工作原理：** +Telegram 反应作为**单独的 `message_reaction` 事件**到达，而不是消息负载中的属性。当用户添加反应时，OpenClaw： 1. 从 Telegram API 接收 `message_reaction` 更新 2. 将其转换为**系统事件**，格式为：`"Telegram reaction added: {emoji} by {user} on msg {id}"` -3. 使用与常规消息**相同的会话键**将系统事件入队 -4. 当该对话中的下一条消息到达时，系统事件被排出并添加到智能体上下文的前面 +3. 使用与常规消息**相同的会话键**将系统事件加入队列 +4. 当该对话中的下一条消息到达时，系统事件被排出并前置到智能体的上下文中 -智能体将表情回应视为对话历史中的**系统通知**，而非消息元数据。 +智能体将反应视为对话历史中的**系统通知**，而不是消息元数据。 **配置：** -- `channels.telegram.reactionNotifications`：控制哪些表情回应触发通知 - - `"off"` — 忽略所有表情回应 - - `"own"` — 当用户对机器人消息做出表情回应时通知（尽力而为；内存中）（默认） - - `"all"` — 对所有表情回应进行通知 +- `channels.telegram.reactionNotifications`：控制哪些反应触发通知 + - `"off"` — 忽略所有反应 + - `"own"` — 当用户对机器人消息做出反应时通知（尽力而为；内存中）（默认） + - `"all"` — 通知所有反应 -- `channels.telegram.reactionLevel`：控制智能体的表情回应能力 - - `"off"` — 智能体不能对消息做表情回应 - - `"ack"` — 机器人发送确认表情回应（处理时显示 👀）（默认） - - `"minimal"` — 智能体可以少量使用表情回应（指导原则：每 5-10 次交流 1 次） - - `"extensive"` — 智能体可以在适当时大量使用表情回应 +- `channels.telegram.reactionLevel`：控制智能体的反应能力 + - `"off"` — 智能体不能对消息做出反应 + - `"ack"` — 机器人发送确认反应（处理时显示 👀）（默认） + - `"minimal"` — 智能体可以少量反应（指导：每 5-10 次交换 1 次） + - `"extensive"` — 智能体可以在适当时自由反应 -**论坛群组：** 论坛群组中的表情回应包含 `message_thread_id`，使用如 `agent:main:telegram:group:{chatId}:topic:{threadId}` 的会话键。这确保同一话题中的表情回应和消息保持在一起。 +**论坛群组：** 论坛群组中的反应包含 `message_thread_id`，使用类似 `agent:main:telegram:group:{chatId}:topic:{threadId}` 的会话键。这确保同一话题中的反应和消息保持在一起。 **示例配置：** @@ -649,8 +645,8 @@ Telegram 表情回应作为**独立的 `message_reaction` 事件**到达，而 { channels: { telegram: { - reactionNotifications: "all", // 查看所有表情回应 - reactionLevel: "minimal", // 智能体可以少量使用表情回应 + reactionNotifications: "all", // 查看所有反应 + reactionLevel: "minimal", // 智能体可以少量反应 }, }, } @@ -658,51 +654,51 @@ Telegram 表情回应作为**独立的 `message_reaction` 事件**到达，而 **要求：** -- Telegram 机器人必须在 `allowed_updates` 中显式请求 `message_reaction`（由 OpenClaw 自动配置） -- 对于 webhook 模式，表情回应包含在 webhook 的 `allowed_updates` 中 -- 对于轮询模式，表情回应包含在 `getUpdates` 的 `allowed_updates` 中 +- Telegram 机器人必须在 `allowed_updates` 中明确请求 `message_reaction`（由 OpenClaw 自动配置） +- 对于 webhook 模式，反应包含在 webhook `allowed_updates` 中 +- 对于轮询模式，反应包含在 `getUpdates` `allowed_updates` 中 -## 投递目标（CLI/定时任务） +## 投递目标（CLI/cron） -- 使用聊天 ID（`123456789`）或用户名（`@name`）作为目标。 +- 使用聊天 id（`123456789`）或用户名（`@name`）作为目标。 - 示例：`openclaw message send --channel telegram --target 123456789 --message "hi"`。 ## 故障排除 -**机器人在群组中不响应非提及消息：** +**机器人不响应群组中的非提及消息：** -- 如果你设置了 `channels.telegram.groups.*.requireMention=false`，Telegram 的 Bot API **隐私模式**必须被禁用。 +- 如果你设置了 `channels.telegram.groups.*.requireMention=false`，Telegram 的 Bot API **隐私模式**必须禁用。 - BotFather：`/setprivacy` → **Disable**（然后从群组中移除并重新添加机器人） -- `openclaw channels status` 在配置期望接收非提及群组消息时会显示警告。 -- `openclaw channels status --probe` 可以额外检查显式数字群组 ID 的成员资格（无法审计通配符 `"*"` 规则）。 -- 快速测试：`/activation always`（仅会话级别；持久化请使用配置） +- `openclaw channels status` 在配置期望未提及群组消息时显示警告。 +- `openclaw channels status --probe` 可以额外检查显式数字群组 ID 的成员资格（它无法审计通配符 `"*"` 规则）。 +- 快速测试：`/activation always`（仅会话级别；使用配置以持久化） **机器人完全看不到群组消息：** - 如果设置了 `channels.telegram.groups`，群组必须被列出或使用 `"*"` -- 在 @BotFather 中检查隐私设置 → "Group Privacy" 应为 **OFF** -- 确认机器人确实是成员（而非只是没有读取权限的管理员） -- 检查 Gateway网关日志：`openclaw logs --follow`（查找 "skipping group message"） +- 在 @BotFather 中检查隐私设置 →"Group Privacy"应为 **OFF** +- 验证机器人确实是成员（不仅仅是没有读取权限的管理员） +- 检查 Gateway 网关日志：`openclaw logs --follow`（查找"skipping group message"） **机器人响应提及但不响应 `/activation always`：** -- `/activation` 命令更新会话状态但不会持久化到配置 +- `/activation` 命令更新会话状态但不持久化到配置 - 要持久化行为，将群组添加到 `channels.telegram.groups` 并设置 `requireMention: false` -**`/status` 等命令不工作：** +**像 `/status` 这样的命令不起作用：** - 确保你的 Telegram 用户 ID 已授权（通过配对或 `channels.telegram.allowFrom`） - 即使在 `groupPolicy: "open"` 的群组中，命令也需要授权 -**长轮询在 Node 22+ 上立即中止（通常涉及代理/自定义 fetch）：** +**长轮询在 Node 22+ 上立即中止（通常与代理/自定义 fetch 有关）：** -- Node 22+ 对 `AbortSignal` 实例更严格；外部信号可能会立即中止 `fetch` 调用。 -- 升级到规范化 abort 信号的 OpenClaw 版本，或在 Node 20 上运行 Gateway网关直到可以升级。 +- Node 22+ 对 `AbortSignal` 实例更严格；外部信号可以立即中止 `fetch` 调用。 +- 升级到规范化中止信号的 OpenClaw 构建版本，或在可以升级之前在 Node 20 上运行 Gateway 网关。 -**机器人启动后静默停止响应（或日志中出现 `HttpError: Network request ... failed`）：** +**机器人启动后静默停止响应（或日志显示 `HttpError: Network request ... failed`）：** -- 某些主机优先将 `api.telegram.org` 解析为 IPv6。如果你的服务器没有可用的 IPv6 出口，grammY 可能会卡在仅 IPv6 的请求上。 -- 修复方法：启用 IPv6 出口**或者**强制 `api.telegram.org` 使用 IPv4 解析（例如，使用 IPv4 A 记录添加 `/etc/hosts` 条目，或在操作系统 DNS 栈中优先使用 IPv4），然后重启 Gateway网关。 +- 某些主机首先将 `api.telegram.org` 解析为 IPv6。如果你的服务器没有可用的 IPv6 出口，grammY 可能会卡在仅 IPv6 的请求上。 +- 通过启用 IPv6 出口**或**强制 `api.telegram.org` 使用 IPv4 解析来修复（例如，使用 IPv4 A 记录添加 `/etc/hosts` 条目，或在你的 OS DNS 堆栈中优先使用 IPv4），然后重启 Gateway 网关。 - 快速检查：`dig +short api.telegram.org A` 和 `dig +short api.telegram.org AAAA` 确认 DNS 返回的内容。 ## 配置参考（Telegram） @@ -712,44 +708,44 @@ Telegram 表情回应作为**独立的 `message_reaction` 事件**到达，而 提供商选项： - `channels.telegram.enabled`：启用/禁用渠道启动。 -- `channels.telegram.botToken`：机器人令牌（BotFather）。 -- `channels.telegram.tokenFile`：从文件路径读取令牌。 +- `channels.telegram.botToken`：机器人 token（BotFather）。 +- `channels.telegram.tokenFile`：从文件路径读取 token。 - `channels.telegram.dmPolicy`：`pairing | allowlist | open | disabled`（默认：pairing）。 -- `channels.telegram.allowFrom`：私聊白名单（ID/用户名）。`open` 需要 `"*"`。 +- `channels.telegram.allowFrom`：私信允许列表（id/用户名）。`open` 需要 `"*"`。 - `channels.telegram.groupPolicy`：`open | allowlist | disabled`（默认：allowlist）。 -- `channels.telegram.groupAllowFrom`：群组发送者白名单（ID/用户名）。 -- `channels.telegram.groups`：按群组的默认设置 + 白名单（使用 `"*"` 作为全局默认）。 +- `channels.telegram.groupAllowFrom`：群组发送者允许列表（id/用户名）。 +- `channels.telegram.groups`：每群组默认值 + 允许列表（使用 `"*"` 作为全局默认值）。 - `channels.telegram.groups..requireMention`：提及门控默认值。 - - `channels.telegram.groups..skills`：Skills 过滤（省略 = 所有 Skills，空 = 无 Skills）。 - - `channels.telegram.groups..allowFrom`：按群组的发送者白名单覆盖。 - - `channels.telegram.groups..systemPrompt`：群组的额外系统提示词。 - - `channels.telegram.groups..enabled`：设为 `false` 时禁用该群组。 - - `channels.telegram.groups..topics..*`：按话题覆盖（与群组字段相同）。 - - `channels.telegram.groups..topics..requireMention`：按话题的提及门控覆盖。 + - `channels.telegram.groups..skills`：skill 过滤器（省略 = 所有 skills，空 = 无）。 + - `channels.telegram.groups..allowFrom`：每群组发送者允许列表覆盖。 + - `channels.telegram.groups..systemPrompt`：群组的额外系统提示。 + - `channels.telegram.groups..enabled`：为 `false` 时禁用群组。 + - `channels.telegram.groups..topics..*`：每话题覆盖（与群组相同的字段）。 + - `channels.telegram.groups..topics..requireMention`：每话题提及门控覆盖。 - `channels.telegram.capabilities.inlineButtons`：`off | dm | group | all | allowlist`（默认：allowlist）。 -- `channels.telegram.accounts..capabilities.inlineButtons`：按账户覆盖。 +- `channels.telegram.accounts..capabilities.inlineButtons`：每账户覆盖。 - `channels.telegram.replyToMode`：`off | first | all`（默认：`first`）。 -- `channels.telegram.textChunkLimit`：出站分块大小（字符数）。 -- `channels.telegram.chunkMode`：`length`（默认）或 `newline`，在空行（段落边界）处拆分后再按长度分块。 +- `channels.telegram.textChunkLimit`：出站分块大小（字符）。 +- `channels.telegram.chunkMode`：`length`（默认）或 `newline` 在长度分块之前按空行（段落边界）分割。 - `channels.telegram.linkPreview`：切换出站消息的链接预览（默认：true）。 - `channels.telegram.streamMode`：`off | partial | block`（草稿流式传输）。 - `channels.telegram.mediaMaxMb`：入站/出站媒体上限（MB）。 - `channels.telegram.retry`：出站 Telegram API 调用的重试策略（attempts、minDelayMs、maxDelayMs、jitter）。 -- `channels.telegram.network.autoSelectFamily`：覆盖 Node 的 autoSelectFamily（true=启用，false=禁用）。在 Node 22 上默认禁用以避免 Happy Eyeballs 超时。 +- `channels.telegram.network.autoSelectFamily`：覆盖 Node autoSelectFamily（true=启用，false=禁用）。在 Node 22 上默认禁用以避免 Happy Eyeballs 超时。 - `channels.telegram.proxy`：Bot API 调用的代理 URL（SOCKS/HTTP）。 - `channels.telegram.webhookUrl`：启用 webhook 模式（需要 `channels.telegram.webhookSecret`）。 -- `channels.telegram.webhookSecret`：webhook 密钥（设置 webhookUrl 时必填）。 +- `channels.telegram.webhookSecret`：webhook 密钥（设置 webhookUrl 时必需）。 - `channels.telegram.webhookPath`：本地 webhook 路径（默认 `/telegram-webhook`）。 -- `channels.telegram.actions.reactions`：Telegram 工具表情回应门控。 -- `channels.telegram.actions.sendMessage`：Telegram 工具消息发送门控。 -- `channels.telegram.actions.deleteMessage`：Telegram 工具消息删除门控。 -- `channels.telegram.actions.sticker`：Telegram 贴纸动作门控 — 发送和搜索（默认：false）。 -- `channels.telegram.reactionNotifications`：`off | own | all` — 控制哪些表情回应触发系统事件（未设置时默认：`own`）。 -- `channels.telegram.reactionLevel`：`off | ack | minimal | extensive` — 控制智能体的表情回应能力（未设置时默认：`minimal`）。 +- `channels.telegram.actions.reactions`：门控 Telegram 工具反应。 +- `channels.telegram.actions.sendMessage`：门控 Telegram 工具消息发送。 +- `channels.telegram.actions.deleteMessage`：门控 Telegram 工具消息删除。 +- `channels.telegram.actions.sticker`：门控 Telegram 贴纸动作 — 发送和搜索（默认：false）。 +- `channels.telegram.reactionNotifications`：`off | own | all` — 控制哪些反应触发系统事件（未设置时默认：`own`）。 +- `channels.telegram.reactionLevel`：`off | ack | minimal | extensive` — 控制智能体的反应能力（未设置时默认：`minimal`）。 相关全局选项： - `agents.list[].groupChat.mentionPatterns`（提及门控模式）。 - `messages.groupChat.mentionPatterns`（全局回退）。 -- `commands.native`（默认为 `"auto"` → Telegram/Discord 启用，Slack 禁用）、`commands.text`、`commands.useAccessGroups`（命令行为）。通过 `channels.telegram.commands.native` 覆盖。 +- `commands.native`（默认为 `"auto"` → Telegram/Discord 开启，Slack 关闭）、`commands.text`、`commands.useAccessGroups`（命令行为）。使用 `channels.telegram.commands.native` 覆盖。 - `messages.responsePrefix`、`messages.ackReaction`、`messages.ackReactionScope`、`messages.removeAckAfterReply`。 diff --git a/docs/zh-CN/channels/tlon.md b/docs/zh-CN/channels/tlon.md index 93e13d895d..e71bcd3fee 100644 --- a/docs/zh-CN/channels/tlon.md +++ b/docs/zh-CN/channels/tlon.md @@ -1,36 +1,34 @@ --- read_when: - - 开发 Tlon/Urbit 渠道功能时 + - 开发 Tlon/Urbit 渠道功能 summary: Tlon/Urbit 支持状态、功能和配置 title: Tlon x-i18n: - generated_at: "2026-02-01T19:58:15Z" + generated_at: "2026-02-03T07:44:17Z" model: claude-opus-4-5 provider: pi source_hash: 19d7ffe23e82239fd2a2e35913e0d52c809b2c2b939dd39184e6c27a539ed97d source_path: channels/tlon.md - workflow: 14 + workflow: 15 --- # Tlon（插件） -Tlon 是一个基于 Urbit 构建的去中心化通讯工具。OpenClaw 连接到你的 Urbit ship，可以 -回复私信和群聊消息。群聊回复默认需要 @ 提及，并可通过白名单进一步限制。 +Tlon 是一个基于 Urbit 构建的去中心化即时通讯工具。OpenClaw 连接到你的 Urbit ship，可以响应私信和群聊消息。群组回复默认需要 @ 提及，并可通过允许列表进一步限制。 -状态：通过插件支持。支持私信、群组提及、线程回复和纯文本媒体回退 -（URL 附加到标题）。不支持反应、投票和原生媒体上传。 +状态：通过插件支持。支持私信、群组提及、话题回复和纯文本媒体回退（URL 附加到说明文字）。不支持表情回应、投票和原生媒体上传。 ## 需要插件 -Tlon 以插件形式提供，不包含在核心安装包中。 +Tlon 作为插件提供，不包含在核心安装中。 -通过 CLI 安装（npm 注册表）： +通过 CLI 安装（npm 仓库）： ```bash openclaw plugins install @openclaw/tlon ``` -本地签出（从 git 仓库运行时）： +本地检出（从 git 仓库运行时）： ```bash openclaw plugins install ./extensions/tlon @@ -43,8 +41,8 @@ openclaw plugins install ./extensions/tlon 1. 安装 Tlon 插件。 2. 获取你的 ship URL 和登录代码。 3. 配置 `channels.tlon`。 -4. 重启 Gateway网关。 -5. 向机器人发送私信或在群组渠道中提及它。 +4. 重启 Gateway 网关。 +5. 私信机器人或在群组频道中提及它。 最小配置（单账户）： @@ -61,9 +59,9 @@ openclaw plugins install ./extensions/tlon } ``` -## 群组渠道 +## 群组频道 -默认启用自动发现。你也可以手动固定渠道： +默认启用自动发现。你也可以手动固定频道： ```json5 { @@ -89,7 +87,7 @@ openclaw plugins install ./extensions/tlon ## 访问控制 -私信白名单（为空 = 允许所有）： +私信允许列表（空 = 允许全部）： ```json5 { @@ -101,7 +99,7 @@ openclaw plugins install ./extensions/tlon } ``` -群组授权（默认为受限模式）： +群组授权（默认受限）： ```json5 { @@ -124,15 +122,15 @@ openclaw plugins install ./extensions/tlon } ``` -## 投递目标（CLI/定时任务） +## 投递目标（CLI/cron） -与 `openclaw message send` 或定时投递配合使用： +与 `openclaw message send` 或 cron 投递一起使用： - 私信：`~sampel-palnet` 或 `dm/~sampel-palnet` - 群组：`chat/~host-ship/channel` 或 `group:~host-ship/channel` -## 备注 +## 注意事项 -- 群聊回复需要提及（例如 `~your-bot-ship`）才会响应。 -- 线程回复：如果收到的消息在线程中，OpenClaw 会在线程内回复。 -- 媒体：`sendMedia` 回退为文本 + URL（不支持原生上传）。 +- 群组回复需要提及（例如 `~your-bot-ship`）才能响应。 +- 话题回复：如果入站消息在话题中，OpenClaw 会在话题内回复。 +- 媒体：`sendMedia` 回退为文本 + URL（无原生上传）。 diff --git a/docs/zh-CN/channels/twitch.md b/docs/zh-CN/channels/twitch.md index de141f3b00..05a0d352da 100644 --- a/docs/zh-CN/channels/twitch.md +++ b/docs/zh-CN/channels/twitch.md @@ -1,32 +1,32 @@ --- read_when: - 为 OpenClaw 设置 Twitch 聊天集成 -summary: Twitch 聊天机器人配置与设置 +summary: Twitch 聊天机器人配置和设置 title: Twitch x-i18n: - generated_at: "2026-02-01T19:58:38Z" + generated_at: "2026-02-03T07:44:41Z" model: claude-opus-4-5 provider: pi - source_hash: aa7d60444e7f7e5dd7d02ce21527089058e024b8f427aeedf9e200a2818eb007 + source_hash: 0dd1c05bef570470d8b82c1f6dee5337e8b76b57269c5cad6aee2e711483f8ba source_path: channels/twitch.md - workflow: 14 + workflow: 15 --- # Twitch（插件） -通过 IRC 连接支持 Twitch 聊天。OpenClaw 以 Twitch 用户（机器人账号）身份连接，在频道中接收和发送消息。 +通过 IRC 连接支持 Twitch 聊天。OpenClaw 以 Twitch 用户（机器人账户）身份连接，在频道中接收和发送消息。 ## 需要插件 -Twitch 以插件形式提供，未包含在核心安装中。 +Twitch 作为插件发布，未与核心安装捆绑。 -通过 CLI（npm 注册表）安装： +通过 CLI 安装（npm 注册表）： ```bash openclaw plugins install @openclaw/twitch ``` -本地签出（从 git 仓库运行时）： +本地检出（从 git 仓库运行时）： ```bash openclaw plugins install ./extensions/twitch @@ -34,19 +34,19 @@ openclaw plugins install ./extensions/twitch 详情：[插件](/plugin) -## 快速设置（入门） +## 快速设置（新手） -1. 为机器人创建一个专用 Twitch 账号（或使用现有账号）。 +1. 为机器人创建一个专用的 Twitch 账户（或使用现有账户）。 2. 生成凭证：[Twitch Token Generator](https://twitchtokengenerator.com/) - 选择 **Bot Token** - - 确认已勾选 `chat:read` 和 `chat:write` 权限范围 + - 确认已选择 `chat:read` 和 `chat:write` 权限范围 - 复制 **Client ID** 和 **Access Token** 3. 查找你的 Twitch 用户 ID：https://www.streamweasels.com/tools/convert-twitch-username-to-user-id/ 4. 配置令牌： - - 环境变量：`OPENCLAW_TWITCH_ACCESS_TOKEN=...`（仅限默认账号） - - 或配置文件：`channels.twitch.accessToken` - - 如果两者都设置了，配置文件优先（环境变量回退仅适用于默认账号）。 -5. 启动 Gateway网关。 + - 环境变量：`OPENCLAW_TWITCH_ACCESS_TOKEN=...`（仅限默认账户） + - 或配置：`channels.twitch.accessToken` + - 如果两者都设置，配置优先（环境变量回退仅适用于默认账户）。 +5. 启动 Gateway 网关。 **⚠️ 重要：** 添加访问控制（`allowFrom` 或 `allowedRoles`）以防止未授权用户触发机器人。`requireMention` 默认为 `true`。 @@ -57,22 +57,22 @@ openclaw plugins install ./extensions/twitch channels: { twitch: { enabled: true, - username: "openclaw", // 机器人的 Twitch 账号 + username: "openclaw", // 机器人的 Twitch 账户 accessToken: "oauth:abc123...", // OAuth Access Token（或使用 OPENCLAW_TWITCH_ACCESS_TOKEN 环境变量） - clientId: "xyz789...", // 从 Token Generator 获取的 Client ID - channel: "vevisk", // 要加入的 Twitch 频道聊天室（必填） + clientId: "xyz789...", // Token Generator 中的 Client ID + channel: "vevisk", // 要加入的 Twitch 频道聊天（必填） allowFrom: ["123456789"], // （推荐）仅限你的 Twitch 用户 ID - 从 https://www.streamweasels.com/tools/convert-twitch-username-to-user-id/ 获取 }, }, } ``` -## 工作原理 +## 它是什么 -- 由 Gateway网关拥有的 Twitch 渠道。 -- 确定性路由：回复始终返回到 Twitch。 -- 每个账号映射到一个隔离的会话键 `agent::twitch:`。 -- `username` 是机器人的账号（用于认证），`channel` 是要加入的聊天室。 +- 由 Gateway 网关拥有的 Twitch 渠道。 +- 确定性路由：回复总是返回到 Twitch。 +- 每个账户映射到一个隔离的会话键 `agent::twitch:`。 +- `username` 是机器人账户（进行身份验证的账户），`channel` 是要加入的聊天室。 ## 设置（详细） @@ -81,20 +81,20 @@ openclaw plugins install ./extensions/twitch 使用 [Twitch Token Generator](https://twitchtokengenerator.com/)： - 选择 **Bot Token** -- 确认已勾选 `chat:read` 和 `chat:write` 权限范围 +- 确认已选择 `chat:read` 和 `chat:write` 权限范围 - 复制 **Client ID** 和 **Access Token** -无需手动注册应用。令牌在数小时后过期。 +无需手动注册应用。令牌在几小时后过期。 ### 配置机器人 -**环境变量（仅限默认账号）：** +**环境变量（仅限默认账户）：** ```bash OPENCLAW_TWITCH_ACCESS_TOKEN=oauth:abc123... ``` -**或配置文件：** +**或配置：** ```json5 { @@ -110,7 +110,7 @@ OPENCLAW_TWITCH_ACCESS_TOKEN=oauth:abc123... } ``` -如果环境变量和配置文件都设置了，配置文件优先。 +如果环境变量和配置都设置了，配置优先。 ### 访问控制（推荐） @@ -119,23 +119,24 @@ OPENCLAW_TWITCH_ACCESS_TOKEN=oauth:abc123... channels: { twitch: { allowFrom: ["123456789"], // （推荐）仅限你的 Twitch 用户 ID - allowedRoles: ["moderator"], // 或按角色限制 }, }, } ``` +优先使用 `allowFrom` 作为硬性允许列表。如果你想要基于角色的访问控制，请改用 `allowedRoles`。 + **可用角色：** `"moderator"`、`"owner"`、`"vip"`、`"subscriber"`、`"all"`。 -**为什么使用用户 ID？** 用户名可以更改，存在冒充风险。用户 ID 是永久的。 +**为什么用用户 ID？** 用户名可以更改，允许冒充。用户 ID 是永久的。 -查找你的 Twitch 用户 ID：https://www.streamweasels.com/tools/convert-twitch-username-%20to-user-id/（将 Twitch 用户名转换为 ID） +查找你的 Twitch 用户 ID：https://www.streamweasels.com/tools/convert-twitch-username-%20to-user-id/（将你的 Twitch 用户名转换为 ID） ## 令牌刷新（可选） -从 [Twitch Token Generator](https://twitchtokengenerator.com/) 获取的令牌无法自动刷新——过期后需重新生成。 +来自 [Twitch Token Generator](https://twitchtokengenerator.com/) 的令牌无法自动刷新 - 过期时需要重新生成。 -如需自动刷新令牌，请在 [Twitch Developer Console](https://dev.twitch.tv/console) 创建你自己的 Twitch 应用，并添加到配置中： +要实现自动令牌刷新，请在 [Twitch Developer Console](https://dev.twitch.tv/console) 创建你自己的 Twitch 应用并添加到配置中： ```json5 { @@ -150,11 +151,11 @@ OPENCLAW_TWITCH_ACCESS_TOKEN=oauth:abc123... 机器人会在令牌过期前自动刷新，并记录刷新事件。 -## 多账号支持 +## 多账户支持 -使用 `channels.twitch.accounts` 配置每个账号的令牌。参见 [`gateway/configuration`](/gateway/configuration) 了解通用模式。 +使用 `channels.twitch.accounts` 配置每个账户的令牌。参阅 [`gateway/configuration`](/gateway/configuration) 了解共享模式。 -示例（一个机器人账号加入两个频道）： +示例（一个机器人账户在两个频道中）： ```json5 { @@ -179,7 +180,7 @@ OPENCLAW_TWITCH_ACCESS_TOKEN=oauth:abc123... } ``` -**注意：** 每个账号需要自己的令牌（每个频道一个令牌）。 +**注意：** 每个账户需要自己的令牌（每个频道一个令牌）。 ## 访问控制 @@ -199,7 +200,7 @@ OPENCLAW_TWITCH_ACCESS_TOKEN=oauth:abc123... } ``` -### 按用户 ID 设置允许列表（最安全） +### 按用户 ID 允许列表（最安全） ```json5 { @@ -215,9 +216,10 @@ OPENCLAW_TWITCH_ACCESS_TOKEN=oauth:abc123... } ``` -### 组合允许列表 + 角色 +### 基于角色的访问（替代方案） -`allowFrom` 中的用户可绕过角色检查： +`allowFrom` 是硬性允许列表。设置后，只允许这些用户 ID。 +如果你想要基于角色的访问，请不设置 `allowFrom`，改为配置 `allowedRoles`： ```json5 { @@ -225,7 +227,6 @@ OPENCLAW_TWITCH_ACCESS_TOKEN=oauth:abc123... twitch: { accounts: { default: { - allowFrom: ["123456789"], allowedRoles: ["moderator"], }, }, @@ -263,17 +264,17 @@ openclaw channels status --probe ### 机器人不响应消息 -**检查访问控制：** 临时设置 `allowedRoles: ["all"]` 进行测试。 +**检查访问控制：** 确保你的用户 ID 在 `allowFrom` 中，或临时移除 `allowFrom` 并设置 `allowedRoles: ["all"]` 来测试。 **检查机器人是否在频道中：** 机器人必须加入 `channel` 中指定的频道。 ### 令牌问题 -**"Failed to connect" 或认证错误：** +**"Failed to connect"或身份验证错误：** -- 确认 `accessToken` 是 OAuth 访问令牌值（通常以 `oauth:` 前缀开头） -- 检查令牌是否具有 `chat:read` 和 `chat:write` 权限范围 -- 如果使用令牌刷新，确认已设置 `clientSecret` 和 `refreshToken` +- 验证 `accessToken` 是 OAuth 访问令牌值（通常以 `oauth:` 前缀开头） +- 检查令牌具有 `chat:read` 和 `chat:write` 权限范围 +- 如果使用令牌刷新，验证 `clientSecret` 和 `refreshToken` 已设置 ### 令牌刷新不工作 @@ -284,36 +285,36 @@ Using env token source for mybot Access token refreshed for user 123456 (expires in 14400s) ``` -如果看到 "token refresh disabled (no refresh token)"： +如果你看到"token refresh disabled (no refresh token)"： -- 确保已提供 `clientSecret` -- 确保已提供 `refreshToken` +- 确保提供了 `clientSecret` +- 确保提供了 `refreshToken` ## 配置 -**账号配置：** +**账户配置：** - `username` - 机器人用户名 - `accessToken` - 具有 `chat:read` 和 `chat:write` 权限的 OAuth 访问令牌 - `clientId` - Twitch Client ID（来自 Token Generator 或你的应用） - `channel` - 要加入的频道（必填） -- `enabled` - 启用此账号（默认：`true`） -- `clientSecret` - 可选：用于自动刷新令牌 -- `refreshToken` - 可选：用于自动刷新令牌 +- `enabled` - 启用此账户（默认：`true`） +- `clientSecret` - 可选：用于自动令牌刷新 +- `refreshToken` - 可选：用于自动令牌刷新 - `expiresIn` - 令牌过期时间（秒） - `obtainmentTimestamp` - 令牌获取时间戳 - `allowFrom` - 用户 ID 允许列表 - `allowedRoles` - 基于角色的访问控制（`"moderator" | "owner" | "vip" | "subscriber" | "all"`） -- `requireMention` - 要求 @提及（默认：`true`） +- `requireMention` - 需要 @提及（默认：`true`） **提供商选项：** - `channels.twitch.enabled` - 启用/禁用渠道启动 -- `channels.twitch.username` - 机器人用户名（简化单账号配置） -- `channels.twitch.accessToken` - OAuth 访问令牌（简化单账号配置） -- `channels.twitch.clientId` - Twitch Client ID（简化单账号配置） -- `channels.twitch.channel` - 要加入的频道（简化单账号配置） -- `channels.twitch.accounts.` - 多账号配置（上述所有账号字段） +- `channels.twitch.username` - 机器人用户名（简化的单账户配置） +- `channels.twitch.accessToken` - OAuth 访问令牌（简化的单账户配置） +- `channels.twitch.clientId` - Twitch Client ID（简化的单账户配置） +- `channels.twitch.channel` - 要加入的频道（简化的单账户配置） +- `channels.twitch.accounts.` - 多账户配置（以上所有账户字段） 完整示例： @@ -370,15 +371,15 @@ Access token refreshed for user 123456 (expires in 14400s) ## 安全与运维 -- **将令牌视为密码** - 切勿将令牌提交到 git +- **将令牌视为密码** - 永远不要将令牌提交到 git - **使用自动令牌刷新** 用于长时间运行的机器人 -- **使用用户 ID 允许列表** 而非用户名进行访问控制 -- **监控日志** 关注令牌刷新事件和连接状态 -- **最小化令牌权限范围** - 仅请求 `chat:read` 和 `chat:write` -- **如遇问题**：确认没有其他进程占用会话后，重启 Gateway网关 +- **使用用户 ID 允许列表** 而不是用户名进行访问控制 +- **监控日志** 查看令牌刷新事件和连接状态 +- **最小化令牌权限范围** - 只请求 `chat:read` 和 `chat:write` +- **如果卡住**：在确认没有其他进程拥有会话后重启 Gateway 网关 ## 限制 -- 每条消息最多 **500 个字符**（按词边界自动分块） -- 分块前会移除 Markdown 格式 +- 每条消息 **500 个字符**（在单词边界自动分块） +- 分块前会去除 Markdown - 无速率限制（使用 Twitch 内置的速率限制） diff --git a/docs/zh-CN/channels/whatsapp.md b/docs/zh-CN/channels/whatsapp.md index b2157bf0d3..16587486a6 100644 --- a/docs/zh-CN/channels/whatsapp.md +++ b/docs/zh-CN/channels/whatsapp.md @@ -4,24 +4,24 @@ read_when: summary: WhatsApp（网页渠道）集成：登录、收件箱、回复、媒体和运维 title: WhatsApp x-i18n: - generated_at: "2026-02-01T20:00:02Z" + generated_at: "2026-02-03T07:46:24Z" model: claude-opus-4-5 provider: pi source_hash: 44fd88f8e269284999e5a5a52b230edae6e6f978528dd298d6a5603d03c0c38d source_path: channels/whatsapp.md - workflow: 14 + workflow: 15 --- # WhatsApp（网页渠道） -状态：仅支持通过 Baileys 的 WhatsApp Web。Gateway网关拥有会话。 +状态：仅支持通过 Baileys 的 WhatsApp Web。Gateway 网关拥有会话。 -## 快速设置（入门） +## 快速设置（新手） 1. 如果可能，使用**单独的手机号码**（推荐）。 2. 在 `~/.openclaw/openclaw.json` 中配置 WhatsApp。 -3. 运行 `openclaw channels login` 扫描二维码（已关联设备）。 -4. 启动 Gateway网关。 +3. 运行 `openclaw channels login` 扫描二维码（关联设备）。 +4. 启动 Gateway 网关。 最小配置： @@ -38,13 +38,13 @@ x-i18n: ## 目标 -- 单个 Gateway网关进程中支持多个 WhatsApp 账号（多账号）。 +- 在一个 Gateway 网关进程中支持多个 WhatsApp 账户（多账户）。 - 确定性路由：回复返回到 WhatsApp，无模型路由。 -- 模型获得足够的上下文以理解引用回复。 +- 模型能看到足够的上下文来理解引用回复。 ## 配置写入 -默认情况下，WhatsApp 允许通过 `/config set|unset` 触发配置更新写入（需要 `commands.config: true`）。 +默认情况下，WhatsApp 允许写入由 `/config set|unset` 触发的配置更新（需要 `commands.config: true`）。 禁用方式： @@ -54,21 +54,21 @@ x-i18n: } ``` -## 架构（职责划分） +## 架构（谁拥有什么） -- **Gateway网关** 拥有 Baileys socket 和收件箱循环。 -- **CLI / macOS 应用** 与 Gateway网关通信；不直接使用 Baileys。 -- **活跃监听器** 是出站发送的必要条件；否则发送会快速失败。 +- **Gateway 网关**拥有 Baileys socket 和收件箱循环。 +- **CLI / macOS 应用**与 Gateway 网关通信；不直接使用 Baileys。 +- 发送出站消息需要**活跃的监听器**；否则发送会快速失败。 ## 获取手机号码（两种模式） -WhatsApp 需要真实的手机号码进行验证。VoIP 和虚拟号码通常会被屏蔽。在 WhatsApp 上运行 OpenClaw 有两种支持的方式： +WhatsApp 需要真实手机号码进行验证。VoIP 和虚拟号码通常会被封锁。在 WhatsApp 上运行 OpenClaw 有两种支持的方式： ### 专用号码（推荐） -为 OpenClaw 使用**单独的手机号码**。最佳用户体验，干净的路由，无自聊天问题。理想设置：**备用/旧 Android 手机 + eSIM**。保持 Wi-Fi 和充电连接，通过二维码关联。 +为 OpenClaw 使用**单独的手机号码**。最佳用户体验，清晰的路由，无自聊天怪异问题。理想设置：**备用/旧 Android 手机 + eSIM**。保持 Wi-Fi 和电源连接，通过二维码关联。 -**WhatsApp Business：** 你可以在同一设备上使用不同号码的 WhatsApp Business。非常适合将个人 WhatsApp 分开 — 安装 WhatsApp Business 并在其中注册 OpenClaw 号码。 +**WhatsApp Business：** 你可以在同一设备上使用不同号码的 WhatsApp Business。非常适合将个人 WhatsApp 分开——安装 WhatsApp Business 并在那里注册 OpenClaw 号码。 **示例配置（专用号码，单用户允许列表）：** @@ -84,13 +84,13 @@ WhatsApp 需要真实的手机号码进行验证。VoIP 和虚拟号码通常会 ``` **配对模式（可选）：** -如果你想使用配对而非允许列表，将 `channels.whatsapp.dmPolicy` 设置为 `pairing`。未知发送者会收到配对码；通过以下命令批准： +如果你想使用配对而不是允许列表，请将 `channels.whatsapp.dmPolicy` 设置为 `pairing`。未知发送者会收到配对码；使用以下命令批准： `openclaw pairing approve whatsapp ` ### 个人号码（备选方案） -快速备选方案：在**你自己的号码**上运行 OpenClaw。给自己发消息（WhatsApp "给自己发消息"）进行测试，避免打扰联系人。在设置和实验期间，需要在主手机上读取验证码。**必须启用自聊天模式。** -当向导询问你的个人 WhatsApp 号码时，输入你将用来发消息的手机号（所有者/发送者），而不是助手号码。 +快速备选方案：在**你自己的号码**上运行 OpenClaw。给自己发消息（WhatsApp"给自己发消息"）进行测试，这样就不会打扰联系人。在设置和实验期间需要在主手机上阅读验证码。**必须启用自聊天模式。** +当向导询问你的个人 WhatsApp 号码时，输入你将用于发送消息的手机（所有者/发送者），而不是助手号码。 **示例配置（个人号码，自聊天）：** @@ -104,64 +104,65 @@ WhatsApp 需要真实的手机号码进行验证。VoIP 和虚拟号码通常会 } ``` -当设置了 `messages.responsePrefix` 时，自聊天回复默认使用 `[{identity.name}]`（否则为 `[openclaw]`）。 -如果 `messages.responsePrefix` 未设置，则使用默认值。显式设置可自定义或禁用前缀（使用 `""` 来移除）。 +当设置了 `identity.name` 时，自聊天回复默认为 `[{identity.name}]`（否则为 `[openclaw]`）， +前提是 `messages.responsePrefix` 未设置。明确设置它可以自定义或禁用 +前缀（使用 `""` 来移除）。 -### 号码获取技巧 +### 号码获取提示 -- **本国 eSIM**，来自你所在国家的移动运营商（最可靠） +- **本地 eSIM** 来自你所在国家的移动运营商（最可靠） - 奥地利：[hot.at](https://www.hot.at) - 英国：[giffgaff](https://www.giffgaff.com) — 免费 SIM 卡，无合约 - **预付费 SIM 卡** — 便宜，只需接收一条验证短信 -**避免使用：** TextNow、Google Voice、大多数"免费短信"服务 — WhatsApp 会积极屏蔽这些号码。 +**避免：** TextNow、Google Voice、大多数"免费短信"服务——WhatsApp 会积极封锁这些。 -**提示：** 该号码只需接收一条验证短信。之后，WhatsApp Web 会话通过 `creds.json` 持久保存。 +**提示：** 该号码只需要接收一条验证短信。之后，WhatsApp Web 会话通过 `creds.json` 持久化。 ## 为什么不用 Twilio？ - 早期 OpenClaw 版本支持 Twilio 的 WhatsApp Business 集成。 - WhatsApp Business 号码不适合个人助手。 - Meta 强制执行 24 小时回复窗口；如果你在过去 24 小时内没有回复，商业号码无法发起新消息。 -- 高频或"频繁"使用会触发激进的封禁，因为商业账号不适合发送大量个人助手消息。 -- 结果：投递不可靠且频繁被封禁，因此已移除支持。 +- 高频或"频繁"使用会触发激进的封锁，因为商业账户不适合发送大量个人助手消息。 +- 结果：投递不可靠且频繁被封锁，因此该支持已被移除。 ## 登录 + 凭证 -- 登录命令：`openclaw channels login`（通过已关联设备扫描二维码）。 -- 多账号登录：`openclaw channels login --account `（`` = `accountId`）。 -- 默认账号（省略 `--account` 时）：如果存在则为 `default`，否则为第一个已配置的账号 ID（排序后）。 +- 登录命令：`openclaw channels login`（通过关联设备扫描二维码）。 +- 多账户登录：`openclaw channels login --account `（`` = `accountId`）。 +- 默认账户（省略 `--account` 时）：如果存在则为 `default`，否则为第一个配置的账户 id（排序后）。 - 凭证存储在 `~/.openclaw/credentials/whatsapp//creds.json`。 -- 备份副本位于 `creds.json.bak`（损坏时恢复）。 -- 旧版兼容：早期安装将 Baileys 文件直接存储在 `~/.openclaw/credentials/`。 -- 注销：`openclaw channels logout`（或 `--account `）删除 WhatsApp 认证状态（但保留共享的 `oauth.json`）。 -- 已注销的 socket => 错误提示重新关联。 +- 备份副本在 `creds.json.bak`（损坏时恢复）。 +- 旧版兼容性：较旧的安装将 Baileys 文件直接存储在 `~/.openclaw/credentials/` 中。 +- 登出：`openclaw channels logout`（或 `--account `）删除 WhatsApp 认证状态（但保留共享的 `oauth.json`）。 +- 已登出的 socket => 错误提示重新关联。 -## 入站流程（私聊 + 群聊） +## 入站流程（私信 + 群组） - WhatsApp 事件来自 `messages.upsert`（Baileys）。 -- 收件箱监听器在关闭时解除绑定，以避免在测试/重启中累积事件处理器。 +- 收件箱监听器在关闭时分离，以避免在测试/重启时累积事件处理器。 - 状态/广播聊天被忽略。 -- 私聊使用 E.164 格式；群聊使用群组 JID。 -- **私聊策略**：`channels.whatsapp.dmPolicy` 控制私聊访问（默认：`pairing`）。 +- 直接聊天使用 E.164；群组使用群组 JID。 +- **私信策略**：`channels.whatsapp.dmPolicy` 控制直接聊天访问（默认：`pairing`）。 - 配对：未知发送者会收到配对码（通过 `openclaw pairing approve whatsapp ` 批准；码在 1 小时后过期）。 - 开放：需要 `channels.whatsapp.allowFrom` 包含 `"*"`。 - - 你关联的 WhatsApp 号码被隐式信任，因此自消息跳过 `channels.whatsapp.dmPolicy` 和 `channels.whatsapp.allowFrom` 检查。 + - 你关联的 WhatsApp 号码是隐式信任的，因此自身消息会跳过 `channels.whatsapp.dmPolicy` 和 `channels.whatsapp.allowFrom` 检查。 ### 个人号码模式（备选方案） -如果你在**个人 WhatsApp 号码**上运行 OpenClaw，启用 `channels.whatsapp.selfChatMode`（参见上方示例配置）。 +如果你在**个人 WhatsApp 号码**上运行 OpenClaw，请启用 `channels.whatsapp.selfChatMode`（见上面的示例）。 行为： -- 出站私聊消息不会触发配对回复（防止骚扰联系人）。 +- 出站私信永远不会触发配对回复（防止打扰联系人）。 - 入站未知发送者仍遵循 `channels.whatsapp.dmPolicy`。 - 自聊天模式（allowFrom 包含你的号码）避免自动已读回执并忽略提及 JID。 -- 非自聊天私聊会发送已读回执。 +- 非自聊天私信会发送已读回执。 ## 已读回执 -默认情况下，Gateway网关会在接受入站 WhatsApp 消息后将其标记为已读（蓝色对勾）。 +默认情况下，Gateway 网关在接受入站 WhatsApp 消息后将其标记为已读（蓝色勾号）。 全局禁用： @@ -171,7 +172,7 @@ WhatsApp 需要真实的手机号码进行验证。VoIP 和虚拟号码通常会 } ``` -按账号禁用： +按账户禁用： ```json5 { @@ -185,31 +186,31 @@ WhatsApp 需要真实的手机号码进行验证。VoIP 和虚拟号码通常会 } ``` -备注： +注意事项： - 自聊天模式始终跳过已读回执。 ## WhatsApp 常见问题：发送消息 + 配对 -**关联 WhatsApp 后，OpenClaw 会给随机联系人发消息吗？** -不会。默认私聊策略是**配对**，因此未知发送者只会收到配对码，其消息**不会被处理**。OpenClaw 只回复收到的聊天，或你显式触发的发送（智能体/CLI）。 +**当我关联 WhatsApp 时，OpenClaw 会给随机联系人发消息吗？** +不会。默认私信策略是**配对**，因此未知发送者只会收到配对码，他们的消息**不会被处理**。OpenClaw 只会回复它收到的聊天，或你明确触发的发送（智能体/CLI）。 **WhatsApp 上的配对是如何工作的？** -配对是针对未知发送者的私聊门控： +配对是未知发送者的私信门控： -- 新发送者的首条私聊消息会返回一个短码（消息不会被处理）。 -- 通过以下命令批准：`openclaw pairing approve whatsapp `（用 `openclaw pairing list whatsapp` 列出）。 +- 来自新发送者的第一条私信返回一个短码（消息不会被处理）。 +- 使用以下命令批准：`openclaw pairing approve whatsapp `（使用 `openclaw pairing list whatsapp` 列出）。 - 码在 1 小时后过期；每个渠道的待处理请求上限为 3 个。 -**多人可以在同一个 WhatsApp 号码上使用不同的 OpenClaw 实例吗？** -可以，通过 `bindings` 将每个发送者路由到不同的智能体（peer `kind: "dm"`，发送者 E.164 如 `+15551234567`）。回复仍然来自**同一个 WhatsApp 账号**，且私聊会折叠到每个智能体的主会话，因此请使用**每人一个智能体**。私聊访问控制（`dmPolicy`/`allowFrom`）在每个 WhatsApp 账号级别是全局的。参见[多智能体路由](/concepts/multi-agent)。 +**多个人可以在一个 WhatsApp 号码上使用不同的 OpenClaw 实例吗？** +可以，通过 `bindings` 将每个发送者路由到不同的智能体（peer `kind: "dm"`，发送者 E.164 如 `+15551234567`）。回复仍然来自**同一个 WhatsApp 账户**，直接聊天会折叠到每个智能体的主会话，因此**每人使用一个智能体**。私信访问控制（`dmPolicy`/`allowFrom`）是每个 WhatsApp 账户全局的。参见[多智能体路由](/concepts/multi-agent)。 -**为什么向导要询问我的手机号码？** -向导使用它来设置你的**允许列表/所有者**，以便允许你自己的私聊消息。它不用于自动发送。如果你在个人 WhatsApp 号码上运行，使用相同的号码并启用 `channels.whatsapp.selfChatMode`。 +**为什么向导会询问我的手机号码？** +向导使用它来设置你的**允许列表/所有者**，以便允许你自己的私信。它不会用于自动发送。如果你在个人 WhatsApp 号码上运行，请使用相同的号码并启用 `channels.whatsapp.selfChatMode`。 -## 消息标准化（模型看到的内容） +## 消息规范化（模型看到的内容） -- `Body` 是当前消息正文及其信封。 +- `Body` 是带有信封的当前消息正文。 - 引用回复上下文**始终附加**： ``` [Replying to +1555 id:ABC123] @@ -219,35 +220,35 @@ WhatsApp 需要真实的手机号码进行验证。VoIP 和虚拟号码通常会 - 回复元数据也会设置： - `ReplyToId` = stanzaId - `ReplyToBody` = 引用正文或媒体占位符 - - `ReplyToSender` = E.164（已知时） + - `ReplyToSender` = 已知时为 E.164 - 纯媒体入站消息使用占位符： - `` -## 群聊 +## 群组 -- 群聊映射到 `agent::whatsapp:group:` 会话。 -- 群聊策略：`channels.whatsapp.groupPolicy = open|disabled|allowlist`（默认 `allowlist`）。 +- 群组映射到 `agent::whatsapp:group:` 会话。 +- 群组策略：`channels.whatsapp.groupPolicy = open|disabled|allowlist`（默认 `allowlist`）。 - 激活模式： - `mention`（默认）：需要 @提及或正则匹配。 - `always`：始终触发。 -- `/activation mention|always` 仅限所有者且必须作为独立消息发送。 -- 所有者 = `channels.whatsapp.allowFrom`（未设置时为自身 E.164）。 +- `/activation mention|always` 仅限所有者，必须作为独立消息发送。 +- 所有者 = `channels.whatsapp.allowFrom`（如果未设置则为自身 E.164）。 - **历史注入**（仅待处理）： - 最近*未处理*的消息（默认 50 条）插入在： - `[Chat messages since your last reply - for context]`（已在会话中的消息不会被重复注入） - - 当前消息位于： + `[Chat messages since your last reply - for context]`（已在会话中的消息不会重新注入） + - 当前消息在： `[Current message - respond to this]` - - 发送者后缀附加：`[from: Name (+E164)]` -- 群聊元数据缓存 5 分钟（主题 + 参与者）。 + - 附加发送者后缀：`[from: Name (+E164)]` +- 群组元数据缓存 5 分钟（主题 + 参与者）。 ## 回复投递（线程） -- WhatsApp Web 发送标准消息（当前 Gateway网关中无引用回复线程）。 +- WhatsApp Web 发送标准消息（当前 Gateway 网关无引用回复线程）。 - 此渠道忽略回复标签。 -## 确认反应（收到消息时自动反应） +## 确认表情（收到时自动回应） -WhatsApp 可以在收到消息时立即自动发送表情反应，在机器人生成回复之前。这为用户提供即时反馈，表明其消息已收到。 +WhatsApp 可以在收到传入消息时立即自动发送表情回应，在机器人生成回复之前。这为用户提供即时反馈，表明他们的消息已收到。 **配置：** @@ -265,14 +266,14 @@ WhatsApp 可以在收到消息时立即自动发送表情反应，在机器人 **选项：** -- `emoji`（字符串）：用于确认的表情（例如 "👀"、"✅"、"📨"）。为空或省略 = 功能禁用。 -- `direct`（布尔值，默认：`true`）：在私聊/私信 中发送反应。 +- `emoji`（字符串）：用于确认的表情（例如"👀"、"✅"、"📨"）。为空或省略 = 功能禁用。 +- `direct`（布尔值，默认：`true`）：在直接/私信聊天中发送表情回应。 - `group`（字符串，默认：`"mentions"`）：群聊行为： - - `"always"`：对所有群聊消息做出反应（即使没有 @提及） - - `"mentions"`：仅在机器人被 @提及时做出反应 - - `"never"`：从不在群聊中做出反应 + - `"always"`：对所有群消息做出回应（即使没有 @提及） + - `"mentions"`：仅在机器人被 @提及时做出回应 + - `"never"`：从不在群组中做出回应 -**按账号覆盖：** +**按账户覆盖：** ```json { @@ -292,42 +293,42 @@ WhatsApp 可以在收到消息时立即自动发送表情反应，在机器人 **行为说明：** -- 反应在收到消息时**立即**发送，在输入指示器或机器人回复之前。 -- 在 `requireMention: false`（激活模式：always）的群组中，`group: "mentions"` 会对所有消息做出反应（不仅仅是 @提及）。 -- 即发即忘：反应失败会被记录但不会阻止机器人回复。 -- 群聊反应会自动包含参与者 JID。 +- 表情回应在消息收到时**立即**发送，在输入指示器或机器人回复之前。 +- 在 `requireMention: false`（激活：always）的群组中，`group: "mentions"` 会对所有消息做出回应（不仅仅是 @提及）。 +- 即发即忘：表情回应失败会被记录但不会阻止机器人回复。 +- 群组表情回应会自动包含参与者 JID。 - WhatsApp 忽略 `messages.ackReaction`；请改用 `channels.whatsapp.ackReaction`。 -## 智能体工具（反应） +## 智能体工具（表情回应） -- 工具：`whatsapp`，使用 `react` 动作（`chatJid`、`messageId`、`emoji`，可选 `remove`）。 -- 可选：`participant`（群聊发送者）、`fromMe`（对自己的消息做出反应）、`accountId`（多账号）。 -- 反应移除语义：参见 [/tools/reactions](/tools/reactions)。 +- 工具：`whatsapp`，带有 `react` 动作（`chatJid`、`messageId`、`emoji`，可选 `remove`）。 +- 可选：`participant`（群组发送者）、`fromMe`（对自己的消息做出回应）、`accountId`（多账户）。 +- 表情移除语义：参见 [/tools/reactions](/tools/reactions)。 - 工具门控：`channels.whatsapp.actions.reactions`（默认：启用）。 ## 限制 - 出站文本按 `channels.whatsapp.textChunkLimit` 分块（默认 4000）。 -- 可选换行分块：设置 `channels.whatsapp.chunkMode="newline"` 在空行（段落边界）处分割，再进行长度分块。 +- 可选换行分块：设置 `channels.whatsapp.chunkMode="newline"` 在长度分块之前按空行（段落边界）分割。 - 入站媒体保存受 `channels.whatsapp.mediaMaxMb` 限制（默认 50 MB）。 - 出站媒体项受 `agents.defaults.mediaMaxMb` 限制（默认 5 MB）。 ## 出站发送（文本 + 媒体） -- 使用活跃的网页监听器；如果 Gateway网关未运行则报错。 +- 使用活跃的网页监听器；如果 Gateway 网关未运行则报错。 - 文本分块：每条消息最大 4k（可通过 `channels.whatsapp.textChunkLimit` 配置，可选 `channels.whatsapp.chunkMode`）。 - 媒体： - 支持图片/视频/音频/文档。 - - 音频以 PTT 发送；`audio/ogg` => `audio/ogg; codecs=opus`。 - - 仅第一个媒体项带字幕。 + - 音频作为 PTT 发送；`audio/ogg` => `audio/ogg; codecs=opus`。 + - 仅在第一个媒体项上添加标题。 - 媒体获取支持 HTTP(S) 和本地路径。 - - 动态 GIF：WhatsApp 期望带 `gifPlayback: true` 的 MP4 以实现内联循环播放。 + - 动画 GIF：WhatsApp 期望带有 `gifPlayback: true` 的 MP4 以实现内联循环。 - CLI：`openclaw message send --media --gif-playback` - - Gateway网关：`send` 参数包含 `gifPlayback: true` + - Gateway 网关：`send` 参数包含 `gifPlayback: true` ## 语音消息（PTT 音频） -WhatsApp 以**语音消息**（PTT 气泡）发送音频。 +WhatsApp 将音频作为**语音消息**（PTT 气泡）发送。 - 最佳效果：OGG/Opus。OpenClaw 将 `audio/ogg` 重写为 `audio/ogg; codecs=opus`。 - WhatsApp 忽略 `[[audio_as_voice]]`（音频已作为语音消息发送）。 @@ -336,43 +337,43 @@ WhatsApp 以**语音消息**（PTT 气泡）发送音频。 - 默认出站上限：5 MB（每个媒体项）。 - 覆盖：`agents.defaults.mediaMaxMb`。 -- 图片会自动优化为 JPEG 以控制在上限内（缩放 + 质量扫描）。 -- 超大媒体 => 错误；媒体回复回退为文本警告。 +- 图片自动优化为上限以下的 JPEG（调整大小 + 质量扫描）。 +- 超大媒体 => 错误；媒体回复降级为文本警告。 ## 心跳 -- **Gateway网关心跳** 记录连接健康状态（`web.heartbeatSeconds`，默认 60 秒）。 -- **智能体心跳** 可按智能体配置（`agents.list[].heartbeat`）或通过 - `agents.defaults.heartbeat` 全局配置（未设置每智能体条目时的回退）。 - - 使用配置的心跳提示（默认：`Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.`）+ `HEARTBEAT_OK` 跳过行为。 - - 投递默认到最后使用的渠道（或已配置的目标）。 +- **Gateway 网关心跳**记录连接健康状态（`web.heartbeatSeconds`，默认 60 秒）。 +- **智能体心跳**可以按智能体配置（`agents.list[].heartbeat`）或通过 + `agents.defaults.heartbeat` 全局配置（当没有设置按智能体条目时的降级）。 + - 使用配置的心跳提示词（默认：`Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.`）+ `HEARTBEAT_OK` 跳过行为。 + - 投递默认为最后使用的渠道（或配置的目标）。 ## 重连行为 - 退避策略：`web.reconnect`： - `initialMs`、`maxMs`、`factor`、`jitter`、`maxAttempts`。 - 如果达到 maxAttempts，网页监控停止（降级）。 -- 已注销 => 停止并要求重新关联。 +- 已登出 => 停止并要求重新关联。 -## 配置速查表 +## 配置快速映射 -- `channels.whatsapp.dmPolicy`（私聊策略：pairing/allowlist/open/disabled）。 -- `channels.whatsapp.selfChatMode`（同号设置；机器人使用你的个人 WhatsApp 号码）。 -- `channels.whatsapp.allowFrom`（私聊允许列表）。WhatsApp 使用 E.164 手机号码（无用户名）。 +- `channels.whatsapp.dmPolicy`（私信策略：pairing/allowlist/open/disabled）。 +- `channels.whatsapp.selfChatMode`（同手机设置；机器人使用你的个人 WhatsApp 号码）。 +- `channels.whatsapp.allowFrom`（私信允许列表）。WhatsApp 使用 E.164 手机号码（无用户名）。 - `channels.whatsapp.mediaMaxMb`（入站媒体保存上限）。 -- `channels.whatsapp.ackReaction`（消息收到时的自动反应：`{emoji, direct, group}`）。 -- `channels.whatsapp.accounts..*`（按账号设置 + 可选 `authDir`）。 -- `channels.whatsapp.accounts..mediaMaxMb`（按账号入站媒体上限）。 -- `channels.whatsapp.accounts..ackReaction`（按账号确认反应覆盖）。 -- `channels.whatsapp.groupAllowFrom`（群聊发送者允许列表）。 -- `channels.whatsapp.groupPolicy`（群聊策略）。 -- `channels.whatsapp.historyLimit` / `channels.whatsapp.accounts..historyLimit`（群聊历史上下文；`0` 禁用）。 -- `channels.whatsapp.dmHistoryLimit`（私聊历史限制，按用户轮数）。按用户覆盖：`channels.whatsapp.dms[""].historyLimit`。 -- `channels.whatsapp.groups`（群聊允许列表 + 提及门控默认值；使用 `"*"` 允许全部） -- `channels.whatsapp.actions.reactions`（WhatsApp 工具反应门控）。 +- `channels.whatsapp.ackReaction`（消息收到时的自动回应：`{emoji, direct, group}`）。 +- `channels.whatsapp.accounts..*`（按账户设置 + 可选 `authDir`）。 +- `channels.whatsapp.accounts..mediaMaxMb`（按账户入站媒体上限）。 +- `channels.whatsapp.accounts..ackReaction`（按账户确认回应覆盖）。 +- `channels.whatsapp.groupAllowFrom`（群组发送者允许列表）。 +- `channels.whatsapp.groupPolicy`（群组策略）。 +- `channels.whatsapp.historyLimit` / `channels.whatsapp.accounts..historyLimit`（群组历史上下文；`0` 禁用）。 +- `channels.whatsapp.dmHistoryLimit`（私信历史限制，按用户轮次）。按用户覆盖：`channels.whatsapp.dms[""].historyLimit`。 +- `channels.whatsapp.groups`（群组允许列表 + 提及门控默认值；使用 `"*"` 允许全部） +- `channels.whatsapp.actions.reactions`（门控 WhatsApp 工具表情回应）。 - `agents.list[].groupChat.mentionPatterns`（或 `messages.groupChat.mentionPatterns`） - `messages.groupChat.historyLimit` -- `channels.whatsapp.messagePrefix`（入站前缀；按账号：`channels.whatsapp.accounts..messagePrefix`；已弃用：`messages.messagePrefix`） +- `channels.whatsapp.messagePrefix`（入站前缀；按账户：`channels.whatsapp.accounts..messagePrefix`；已弃用：`messages.messagePrefix`） - `messages.responsePrefix`（出站前缀） - `agents.defaults.mediaMaxMb` - `agents.defaults.heartbeat.every` @@ -390,21 +391,21 @@ WhatsApp 以**语音消息**（PTT 气泡）发送音频。 - 子系统：`whatsapp/inbound`、`whatsapp/outbound`、`web-heartbeat`、`web-reconnect`。 - 日志文件：`/tmp/openclaw/openclaw-YYYY-MM-DD.log`（可配置）。 -- 故障排除指南：[Gateway网关故障排除](/gateway/troubleshooting)。 +- 故障排除指南：[Gateway 网关故障排除](/gateway/troubleshooting)。 ## 故障排除（快速） **未关联 / 需要二维码登录** -- 症状：`channels status` 显示 `linked: false` 或警告"未关联"。 -- 修复：在 Gateway网关主机上运行 `openclaw channels login` 并扫描二维码（WhatsApp → 设置 → 已关联设备）。 +- 症状：`channels status` 显示 `linked: false` 或警告"Not linked"。 +- 修复：在 Gateway 网关主机上运行 `openclaw channels login` 并扫描二维码（WhatsApp → 设置 → 关联设备）。 **已关联但断开连接 / 重连循环** -- 症状：`channels status` 显示 `running, disconnected` 或警告"已关联但断开连接"。 -- 修复：`openclaw doctor`（或重启 Gateway网关）。如果问题持续，通过 `channels login` 重新关联并检查 `openclaw logs --follow`。 +- 症状：`channels status` 显示 `running, disconnected` 或警告"Linked but disconnected"。 +- 修复：`openclaw doctor`（或重启 Gateway 网关）。如果问题持续，通过 `channels login` 重新关联并检查 `openclaw logs --follow`。 **Bun 运行时** -- **不推荐**使用 Bun。WhatsApp（Baileys）和 Telegram 在 Bun 上不稳定。 - 请使用 **Node** 运行 Gateway网关。（参见入门指南运行时说明。） +- **不推荐** Bun。WhatsApp（Baileys）和 Telegram 在 Bun 上不可靠。 + 请使用 **Node** 运行 Gateway 网关。（参见入门指南运行时说明。） diff --git a/docs/zh-CN/channels/zalo.md b/docs/zh-CN/channels/zalo.md index b76112a3dc..b1378e0ab7 100644 --- a/docs/zh-CN/channels/zalo.md +++ b/docs/zh-CN/channels/zalo.md @@ -1,40 +1,40 @@ --- read_when: - - 处理 Zalo 功能或 webhook 时 -summary: Zalo 机器人支持状态、功能和配置 + - 开发 Zalo 功能或 webhooks +summary: Zalo bot 支持状态、功能和配置 title: Zalo x-i18n: - generated_at: "2026-02-01T19:58:32Z" + generated_at: "2026-02-03T07:44:44Z" model: claude-opus-4-5 provider: pi source_hash: 0311d932349f96412b712970b5d37329b91929bf3020536edf3ca0ff464373c0 source_path: channels/zalo.md - workflow: 14 + workflow: 15 --- # Zalo (Bot API) -状态：实验性。仅支持私信；根据 Zalo 文档，群组功能即将推出。 +状态：实验性。仅支持私信；根据 Zalo 文档，群组即将推出。 ## 需要插件 Zalo 以插件形式提供，不包含在核心安装中。 - 通过 CLI 安装：`openclaw plugins install @openclaw/zalo` -- 或在新手引导中选择 **Zalo** 并确认安装提示 +- 或在新手引导期间选择 **Zalo** 并确认安装提示 - 详情：[插件](/plugin) -## 快速设置（新手） +## 快速设置（初学者） 1. 安装 Zalo 插件： - - 从源码检出安装：`openclaw plugins install ./extensions/zalo` - - 从 npm 安装（如已发布）：`openclaw plugins install @openclaw/zalo` + - 从源代码检出：`openclaw plugins install ./extensions/zalo` + - 从 npm（如果已发布）：`openclaw plugins install @openclaw/zalo` - 或在新手引导中选择 **Zalo** 并确认安装提示 -2. 设置令牌： +2. 设置 token： - 环境变量：`ZALO_BOT_TOKEN=...` - 或配置：`channels.zalo.botToken: "..."`。 -3. 重启 Gateway网关（或完成新手引导）。 -4. 私信访问默认使用配对模式；首次联系时需批准配对码。 +3. 重启 Gateway 网关（或完成新手引导）。 +4. 私信访问默认为配对模式；首次联系时批准配对码。 最小配置： @@ -50,25 +50,25 @@ Zalo 以插件形式提供，不包含在核心安装中。 } ``` -## 简介 +## 它是什么 -Zalo 是一款面向越南市场的即时通讯应用；其 Bot API 允许 Gateway网关运行一个用于一对一对话的机器人。 -它非常适合需要将消息确定性路由回 Zalo 的客服或通知场景。 +Zalo 是一款专注于越南市场的即时通讯应用；其 Bot API 让 Gateway 网关可以运行一个用于一对一对话的 bot。 +它非常适合需要确定性路由回 Zalo 的支持或通知场景。 -- 由 Gateway网关管理的 Zalo Bot API 渠道。 -- 确定性路由：回复始终返回 Zalo；模型不会选择渠道。 +- 由 Gateway 网关拥有的 Zalo Bot API 渠道。 +- 确定性路由：回复返回到 Zalo；模型不会选择渠道。 - 私信共享智能体的主会话。 - 群组尚不支持（Zalo 文档标注"即将推出"）。 ## 设置（快速路径） -### 1) 创建机器人令牌（Zalo Bot Platform） +### 1）创建 bot token（Zalo Bot 平台） 1. 前往 **https://bot.zaloplatforms.com** 并登录。 -2. 创建新机器人并配置其设置。 -3. 复制机器人令牌（格式：`12345689:abc-xyz`）。 +2. 创建新 bot 并配置其设置。 +3. 复制 bot token（格式：`12345689:abc-xyz`）。 -### 2) 配置令牌（环境变量或配置文件） +### 2）配置 token（环境变量或配置） 示例： @@ -86,49 +86,49 @@ Zalo 是一款面向越南市场的即时通讯应用；其 Bot API 允许 Gatew 环境变量选项：`ZALO_BOT_TOKEN=...`（仅适用于默认账户）。 -多账户支持：使用 `channels.zalo.accounts`，为每个账户配置令牌和可选的 `name`。 +多账户支持：使用 `channels.zalo.accounts` 配置每账户 token 和可选的 `name`。 -3. 重启 Gateway网关。当令牌被解析（通过环境变量或配置）时，Zalo 将启动。 -4. 私信访问默认使用配对模式。机器人首次被联系时，请批准配对码。 +3. 重启 Gateway 网关。当 token 被解析（环境变量或配置）时，Zalo 启动。 +4. 私信访问默认为配对模式。当 bot 首次被联系时批准配对码。 ## 工作原理（行为） -- 入站消息被标准化为共享渠道信封，并包含媒体占位符。 -- 回复始终路由回同一个 Zalo 聊天。 +- 入站消息被规范化为带有媒体占位符的共享渠道信封。 +- 回复始终路由回同一 Zalo 聊天。 - 默认使用长轮询；可通过 `channels.zalo.webhookUrl` 启用 webhook 模式。 ## 限制 - 出站文本按 2000 字符分块（Zalo API 限制）。 - 媒体下载/上传受 `channels.zalo.mediaMaxMb` 限制（默认 5）。 -- 由于 2000 字符限制导致流式传输意义不大，默认禁用流式传输。 +- 由于 2000 字符限制使流式传输效果不佳，默认阻止流式传输。 ## 访问控制（私信） ### 私信访问 -- 默认：`channels.zalo.dmPolicy = "pairing"`。未知发送者会收到配对码；消息在批准前将被忽略（配对码 1 小时后过期）。 -- 批准方式： +- 默认：`channels.zalo.dmPolicy = "pairing"`。未知发送者会收到配对码；消息在批准前会被忽略（配对码 1 小时后过期）。 +- 通过以下方式批准： - `openclaw pairing list zalo` - `openclaw pairing approve zalo ` - 配对是默认的令牌交换方式。详情：[配对](/start/pairing) -- `channels.zalo.allowFrom` 接受数字用户 ID（不支持用户名查找）。 +- `channels.zalo.allowFrom` 接受数字用户 ID（无用户名查找功能）。 ## 长轮询与 webhook -- 默认：长轮询（无需公网 URL）。 +- 默认：长轮询（不需要公共 URL）。 - Webhook 模式：设置 `channels.zalo.webhookUrl` 和 `channels.zalo.webhookSecret`。 - - Webhook 密钥必须为 8-256 个字符。 + - Webhook secret 必须为 8-256 个字符。 - Webhook URL 必须使用 HTTPS。 - - Zalo 通过 `X-Bot-Api-Secret-Token` 请求头发送事件以进行验证。 - - Gateway网关 HTTP 在 `channels.zalo.webhookPath` 处理 webhook 请求（默认为 webhook URL 路径）。 + - Zalo 发送事件时带有 `X-Bot-Api-Secret-Token` 头用于验证。 + - Gateway 网关 HTTP 在 `channels.zalo.webhookPath` 处理 webhook 请求（默认为 webhook URL 路径）。 -**注意：** 根据 Zalo API 文档，getUpdates（轮询）和 webhook 互斥。 +**注意：** 根据 Zalo API 文档，getUpdates（轮询）和 webhook 是互斥的。 ## 支持的消息类型 -- **文本消息**：完全支持，按 2000 字符分块。 -- **图片消息**：下载并处理入站图片；通过 `sendPhoto` 发送图片。 +- **文本消息**：完全支持，2000 字符分块。 +- **图片消息**：下载和处理入站图片；通过 `sendPhoto` 发送图片。 - **贴纸**：已记录但未完全处理（无智能体响应）。 - **不支持的类型**：已记录（例如来自受保护用户的消息）。 @@ -140,30 +140,30 @@ Zalo 是一款面向越南市场的即时通讯应用；其 Bot API 允许 Gatew | 群组 | ❌ 即将推出（根据 Zalo 文档） | | 媒体（图片） | ✅ 支持 | | 表情回应 | ❌ 不支持 | -| 话题 | ❌ 不支持 | +| 主题 | ❌ 不支持 | | 投票 | ❌ 不支持 | | 原生命令 | ❌ 不支持 | -| 流式传输 | ⚠️ 已禁用（2000 字符限制） | +| 流式传输 | ⚠️ 已阻止（2000 字符限制） | -## 投递目标（CLI/定时任务） +## 投递目标（CLI/cron） -- 使用聊天 ID 作为目标。 +- 使用聊天 id 作为目标。 - 示例：`openclaw message send --channel zalo --target 123456789 --message "hi"`。 ## 故障排除 -**机器人无响应：** +**Bot 不响应：** -- 检查令牌是否有效：`openclaw channels status --probe` -- 验证发送者是否已批准（配对或 allowFrom） -- 检查 Gateway网关日志：`openclaw logs --follow` +- 检查 token 是否有效：`openclaw channels status --probe` +- 验证发送者已被批准（配对或 allowFrom） +- 检查 Gateway 网关日志：`openclaw logs --follow` **Webhook 未收到事件：** - 确保 webhook URL 使用 HTTPS -- 验证密钥令牌为 8-256 个字符 -- 确认 Gateway网关 HTTP 端点在配置的路径上可达 -- 检查 getUpdates 轮询是否未在运行（两者互斥） +- 验证 secret token 为 8-256 个字符 +- 确认 Gateway 网关 HTTP 端点在配置的路径上可访问 +- 检查 getUpdates 轮询未在运行（它们是互斥的） ## 配置参考（Zalo） @@ -172,25 +172,25 @@ Zalo 是一款面向越南市场的即时通讯应用；其 Bot API 允许 Gatew 提供商选项： - `channels.zalo.enabled`：启用/禁用渠道启动。 -- `channels.zalo.botToken`：来自 Zalo Bot Platform 的机器人令牌。 -- `channels.zalo.tokenFile`：从文件路径读取令牌。 +- `channels.zalo.botToken`：来自 Zalo Bot 平台的 bot token。 +- `channels.zalo.tokenFile`：从文件路径读取 token。 - `channels.zalo.dmPolicy`：`pairing | allowlist | open | disabled`（默认：pairing）。 -- `channels.zalo.allowFrom`：私信允许列表（用户 ID）。`open` 需要 `"*"`。向导会要求输入数字 ID。 -- `channels.zalo.mediaMaxMb`：入站/出站媒体大小上限（MB，默认 5）。 +- `channels.zalo.allowFrom`：私信允许列表（用户 ID）。`open` 需要 `"*"`。向导会询问数字 ID。 +- `channels.zalo.mediaMaxMb`：入站/出站媒体上限（MB，默认 5）。 - `channels.zalo.webhookUrl`：启用 webhook 模式（需要 HTTPS）。 -- `channels.zalo.webhookSecret`：webhook 密钥（8-256 个字符）。 -- `channels.zalo.webhookPath`：Gateway网关 HTTP 服务器上的 webhook 路径。 +- `channels.zalo.webhookSecret`：webhook secret（8-256 字符）。 +- `channels.zalo.webhookPath`：Gateway 网关 HTTP 服务器上的 webhook 路径。 - `channels.zalo.proxy`：API 请求的代理 URL。 多账户选项： -- `channels.zalo.accounts..botToken`：每个账户的令牌。 -- `channels.zalo.accounts..tokenFile`：每个账户的令牌文件。 +- `channels.zalo.accounts..botToken`：每账户 token。 +- `channels.zalo.accounts..tokenFile`：每账户 token 文件。 - `channels.zalo.accounts..name`：显示名称。 - `channels.zalo.accounts..enabled`：启用/禁用账户。 -- `channels.zalo.accounts..dmPolicy`：每个账户的私信策略。 -- `channels.zalo.accounts..allowFrom`：每个账户的允许列表。 -- `channels.zalo.accounts..webhookUrl`：每个账户的 webhook URL。 -- `channels.zalo.accounts..webhookSecret`：每个账户的 webhook 密钥。 -- `channels.zalo.accounts..webhookPath`：每个账户的 webhook 路径。 -- `channels.zalo.accounts..proxy`：每个账户的代理 URL。 +- `channels.zalo.accounts..dmPolicy`：每账户私信策略。 +- `channels.zalo.accounts..allowFrom`：每账户允许列表。 +- `channels.zalo.accounts..webhookUrl`：每账户 webhook URL。 +- `channels.zalo.accounts..webhookSecret`：每账户 webhook secret。 +- `channels.zalo.accounts..webhookPath`：每账户 webhook 路径。 +- `channels.zalo.accounts..proxy`：每账户代理 URL。 diff --git a/docs/zh-CN/channels/zalouser.md b/docs/zh-CN/channels/zalouser.md index 1f1ed25527..36630ddd78 100644 --- a/docs/zh-CN/channels/zalouser.md +++ b/docs/zh-CN/channels/zalouser.md @@ -1,27 +1,27 @@ --- read_when: - 为 OpenClaw 设置 Zalo Personal - - 调试 Zalo Personal 登录或消息流 -summary: 通过 zca-cli（二维码登录）支持 Zalo 个人账号，功能与配置说明 + - 调试 Zalo Personal 登录或消息流程 +summary: 通过 zca-cli（QR 登录）支持 Zalo 个人账户、功能和配置 title: Zalo Personal x-i18n: - generated_at: "2026-02-01T19:58:27Z" + generated_at: "2026-02-03T07:44:34Z" model: claude-opus-4-5 provider: pi source_hash: 2a249728d556e5cc52274627bdaf390fa10e815afa04f4497feb57a2a0cb9261 source_path: channels/zalouser.md - workflow: 14 + workflow: 15 --- # Zalo Personal（非官方） -状态：实验性。此集成通过 `zca-cli` 自动化操作一个**个人 Zalo 账号**。 +状态：实验性。此集成通过 `zca-cli` 自动化**个人 Zalo 账户**。 -> **警告：** 这是一个非官方集成，可能导致账号被暂停或封禁。使用风险自负。 +> **警告：**这是一个非官方集成，可能导致账户被暂停/封禁。使用风险自负。 -## 需要安装插件 +## 需要插件 -Zalo Personal 以插件形式提供，不包含在核心安装包中。 +Zalo Personal 作为插件提供，不包含在核心安装中。 - 通过 CLI 安装：`openclaw plugins install @openclaw/zalouser` - 或从源码检出安装：`openclaw plugins install ./extensions/zalouser` @@ -29,17 +29,17 @@ Zalo Personal 以插件形式提供，不包含在核心安装包中。 ## 前置条件：zca-cli -Gateway网关所在机器必须在 `PATH` 中包含 `zca` 可执行文件。 +Gateway 网关机器必须在 `PATH` 中有可用的 `zca` 二进制文件。 - 验证：`zca --version` - 如果缺失，请安装 zca-cli（参见 `extensions/zalouser/README.md` 或上游 zca-cli 文档）。 -## 快速设置（入门） +## 快速设置（新手） 1. 安装插件（见上文）。 -2. 登录（二维码方式，在 Gateway网关机器上操作）： +2. 登录（QR，在 Gateway 网关机器上）： - `openclaw channels login --channel zalouser` - - 使用 Zalo 手机应用扫描终端中的二维码。 + - 用 Zalo 手机应用扫描终端中的二维码。 3. 启用渠道： ```json5 @@ -53,22 +53,22 @@ Gateway网关所在机器必须在 `PATH` 中包含 `zca` 可执行文件。 } ``` -4. 重启 Gateway网关（或完成新手引导）。 -5. 私信访问默认为配对模式；首次联系时需批准配对码。 +4. 重启 Gateway 网关（或完成新手引导）。 +5. 私信访问默认为配对模式；首次联系时批准配对码。 -## 功能说明 +## 这是什么 - 使用 `zca listen` 接收入站消息。 - 使用 `zca msg ...` 发送回复（文本/媒体/链接）。 -- 专为 Zalo Bot API 不可用时的"个人账号"使用场景设计。 +- 专为"个人账户"使用场景设计，适用于 Zalo Bot API 不可用的情况。 -## 命名说明 +## 命名 -渠道 ID 为 `zalouser`，以明确表示这是对**个人 Zalo 用户账号**的自动化操作（非官方）。我们将 `zalo` 保留给未来可能的官方 Zalo API 集成。 +渠道 ID 为 `zalouser`，以明确表示这是自动化**个人 Zalo 用户账户**（非官方）。我们保留 `zalo` 用于未来可能的官方 Zalo API 集成。 -## 查找 ID（通讯录） +## 查找 ID（目录） -使用通讯录 CLI 发现联系人/群组及其 ID： +使用目录 CLI 发现联系人/群组及其 ID： ```bash openclaw directory self --channel zalouser @@ -78,13 +78,13 @@ openclaw directory groups list --channel zalouser --query "work" ## 限制 -- 出站文本按约 2000 字符分块（Zalo 客户端限制）。 -- 流式传输默认被禁用。 +- 出站文本分块为约 2000 字符（Zalo 客户端限制）。 +- 默认阻止流式传输。 ## 访问控制（私信） `channels.zalouser.dmPolicy` 支持：`pairing | allowlist | open | disabled`（默认：`pairing`）。 -`channels.zalouser.allowFrom` 接受用户 ID 或名称。向导在可用时通过 `zca friend find` 将名称解析为 ID。 +`channels.zalouser.allowFrom` 接受用户 ID 或名称。向导会在可用时通过 `zca friend find` 将名称解析为 ID。 通过以下方式批准： @@ -93,13 +93,13 @@ openclaw directory groups list --channel zalouser --query "work" ## 群组访问（可选） -- 默认：`channels.zalouser.groupPolicy = "open"`（允许群组）。未设置时使用 `channels.defaults.groupPolicy` 覆盖默认值。 -- 通过允许列表进行限制： +- 默认：`channels.zalouser.groupPolicy = "open"`（允许群组）。使用 `channels.defaults.groupPolicy` 在未设置时覆盖默认值。 +- 通过以下方式限制为允许列表： - `channels.zalouser.groupPolicy = "allowlist"` - `channels.zalouser.groups`（键为群组 ID 或名称） -- 禁止所有群组：`channels.zalouser.groupPolicy = "disabled"`。 -- 配置向导可以提示设置群组允许列表。 -- 启动时，OpenClaw 会将允许列表中的群组/用户名称解析为 ID 并记录映射关系；未解析的条目保持原样。 +- 阻止所有群组：`channels.zalouser.groupPolicy = "disabled"`。 +- 配置向导可以提示输入群组允许列表。 +- 启动时，OpenClaw 将允许列表中的群组/用户名称解析为 ID 并记录映射；未解析的条目保持原样。 示例： @@ -117,9 +117,9 @@ openclaw directory groups list --channel zalouser --query "work" } ``` -## 多账号 +## 多账户 -账号映射到 zca 配置文件。示例： +账户映射到 zca 配置文件。示例： ```json5 { @@ -139,9 +139,9 @@ openclaw directory groups list --channel zalouser --query "work" **找不到 `zca`：** -- 安装 zca-cli 并确保 Gateway网关进程的 `PATH` 中包含该命令。 +- 安装 zca-cli 并确保它在 Gateway 网关进程的 `PATH` 中。 -**登录状态无法保持：** +**登录不保持：** - `openclaw channels status --probe` - 重新登录：`openclaw channels logout --channel zalouser && openclaw channels login --channel zalouser` diff --git a/docs/zh-CN/cli/acp.md b/docs/zh-CN/cli/acp.md index bd676c442b..9adb0a8a52 100644 --- a/docs/zh-CN/cli/acp.md +++ b/docs/zh-CN/cli/acp.md @@ -1,63 +1,63 @@ --- read_when: - 设置基于 ACP 的 IDE 集成 - - 调试 ACP 会话到 Gateway网关的路由 -summary: 运行用于 IDE 集成的 ACP 桥接 + - 调试到 Gateway 网关的 ACP 会话路由 +summary: 运行用于 IDE 集成的 ACP 桥接器 title: acp x-i18n: - generated_at: "2026-02-01T19:58:33Z" + generated_at: "2026-02-03T07:44:38Z" model: claude-opus-4-5 provider: pi source_hash: 0c09844297da250bc1a558423e7e534d6b6be9045de12d797c07ecd64a0c63ed source_path: cli/acp.md - workflow: 14 + workflow: 15 --- # acp -运行与 OpenClaw Gateway网关通信的 ACP（Agent Client Protocol）桥接。 +运行与 OpenClaw Gateway 网关通信的 ACP（Agent Client Protocol）桥接器。 -此命令通过 stdio 使用 ACP 协议与 IDE 通信，并通过 WebSocket 将提示转发到 Gateway网关。它将 ACP 会话映射到 Gateway网关会话密钥。 +此命令通过 stdio 使用 ACP 协议与 IDE 通信，并通过 WebSocket 将提示转发到 Gateway 网关。它将 ACP 会话映射到 Gateway 网关会话键。 ## 用法 ```bash openclaw acp -# 远程 Gateway网关 +# Remote Gateway openclaw acp --url wss://gateway-host:18789 --token -# 附加到现有会话密钥 +# Attach to an existing session key openclaw acp --session agent:main:main -# 通过标签附加（必须已存在） +# Attach by label (must already exist) openclaw acp --session-label "support inbox" -# 在第一个提示之前重置会话密钥 +# Reset the session key before the first prompt openclaw acp --session agent:main:main --reset-session ``` ## ACP 客户端（调试） -使用内置 ACP 客户端在无需 IDE 的情况下对桥接进行安装完整性检查。 -它会启动 ACP 桥接并允许你交互式地输入提示。 +使用内置 ACP 客户端在没有 IDE 的情况下检查桥接器的安装完整性。 +它会启动 ACP 桥接器并让你交互式输入提示。 ```bash openclaw acp client -# 将启动的桥接指向远程 Gateway网关 +# Point the spawned bridge at a remote Gateway openclaw acp client --server-args --url wss://gateway-host:18789 --token -# 覆盖服务器命令（默认：openclaw） +# Override the server command (default: openclaw) openclaw acp client --server "node" --server-args openclaw.mjs acp --url ws://127.0.0.1:19001 ``` ## 如何使用 -当 IDE（或其他客户端）使用 Agent Client Protocol 并且你希望它驱动 OpenClaw Gateway网关会话时，请使用 ACP。 +当 IDE（或其他客户端）使用 Agent Client Protocol 并且你希望它驱动 OpenClaw Gateway 网关会话时，请使用 ACP。 -1. 确保 Gateway网关正在运行（本地或远程）。 -2. 配置 Gateway网关目标（通过配置文件或标志）。 +1. 确保 Gateway 网关正在运行（本地或远程）。 +2. 配置 Gateway 网关目标（配置或标志）。 3. 将你的 IDE 配置为通过 stdio 运行 `openclaw acp`。 示例配置（持久化）： @@ -75,9 +75,9 @@ openclaw acp --url wss://gateway-host:18789 --token ## 选择智能体 -ACP 不直接选择智能体。它通过 Gateway网关会话密钥进行路由。 +ACP 不直接选择智能体。它通过 Gateway 网关会话键进行路由。 -使用智能体作用域的会话密钥来指定特定智能体： +使用智能体作用域的会话键来定位特定智能体： ```bash openclaw acp --session agent:main:main @@ -85,7 +85,7 @@ openclaw acp --session agent:design:main openclaw acp --session agent:qa:bug-123 ``` -每个 ACP 会话映射到单个 Gateway网关会话密钥。一个智能体可以有多个会话；除非你覆盖密钥或标签，否则 ACP 默认使用隔离的 `acp:` 会话。 +每个 ACP 会话映射到单个 Gateway 网关会话键。一个智能体可以有多个会话；除非你覆盖键或标签，否则 ACP 默认使用隔离的 `acp:` 会话。 ## Zed 编辑器设置 @@ -104,7 +104,7 @@ openclaw acp --session agent:qa:bug-123 } ``` -要指定特定的 Gateway网关或智能体： +要定位特定的 Gateway 网关或智能体： ```json { @@ -127,18 +127,18 @@ openclaw acp --session agent:qa:bug-123 } ``` -在 Zed 中，打开 Agent 面板并选择 "OpenClaw ACP" 来开始一个对话线程。 +在 Zed 中，打开 Agent 面板并选择"OpenClaw ACP"来开始一个会话。 ## 会话映射 -默认情况下，ACP 会话会获得一个带有 `acp:` 前缀的隔离 Gateway网关会话密钥。 -要复用已知会话，请传递会话密钥或标签： +默认情况下，ACP 会话获得一个带有 `acp:` 前缀的隔离 Gateway 网关会话键。 +要重用已知会话，请传递会话键或标签： -- `--session `：使用特定的 Gateway网关会话密钥。 +- `--session `：使用特定的 Gateway 网关会话键。 - `--session-label