github/openclaw
1
1
Fork 0
mirror of https://github.com/openclaw/openclaw.git synced 2026-02-19 18:39:20 -05:00
Code Issues Packages Projects Releases Wiki Activity

Docs: update zh-CN translations and pipeline

Browse Source 
What:
- update zh-CN glossary, TM, and translator prompt
- regenerate zh-CN docs and apply targeted fixes
- add zh-CN AGENTS pipeline guidance

Why:
- address terminology/spacing feedback from #6995

Tests:
- pnpm build && pnpm check && pnpm test
This commit is contained in:
Josh Palmer
2026-02-03 13:23:00 -08:00
parent 9f03791aa9
commit a3ec2d0734
228 changed files with 10651 additions and 10475 deletions
Download Patch File Download Diff File Expand all files Collapse all files

62
docs/.i18n/glossary.zh-CN.json
View File

@@ -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": "凭证：存储位置（重要）"

42
docs/.i18n/zh-CN.tm.jsonl
View File

@@ -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"}

26
docs/zh-CN/automation/auth-monitoring.md
View File

@@ -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 定时器，可以跳过这些脚本。

188
docs/zh-CN/automation/cron-jobs.md
View File

@@ -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:<jobId>` 中运行专用智能体轮次，可选择投递输出。
- 唤醒是一等功能：任务可以请求"立即唤醒"或"下次心跳时"。
- **主会话**：将系统事件加入队列，然后在下一次心跳时运行。
- **隔离**：在 `cron:<jobId>` 中运行专用的智能体回合，可选择发送输出。
- 唤醒是一等功能：任务可以请求"立即唤醒"或"下次心跳"。
## 快速开始（可操作）
创建一个一次性提醒，验证其存在，然后立即运行：
创建一个一次性提醒，验证它是否存在，然后立即运行：
```bash
openclaw cron add \
@@ -49,7 +49,7 @@ openclaw cron run <job-id> --force
openclaw cron runs --id <job-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:<jobId>` 中运行专用智能体轮次。
- `sessionTarget: "main"` → 在下一次心跳时使用主上下文运行。
- `sessionTarget: "isolated"` → 在 `cron:<jobId>` 中运行专用的智能体回合。
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:<jobId>` 中运行专用智能体轮次。
隔离任务在会话 `cron:<jobId>` 中运行专用的智能体回合。
关键行为：
- 提示以 `[cron:<jobId> <任务名称>]` 为前缀，便于追踪。
- 每次运行都会启动一个**全新的会话 ID**（不继承之前的对话）。
- 提示以 `[cron:<jobId> <job name>]` 为前缀以便追踪。
- 每次运行启动一个**新的会话 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:<id>`、`user:<id>`）以避免歧义。
- Telegram 主题应使用 `:topic:` 格式（见下文）。
- Slack/Discord/Mattermost（插件）目标应使用显式前缀（例如 `channel:<id>`、`user:<id>`）以避免歧义。
- 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/<jobId>.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 <jobId> \
openclaw cron runs --id <jobId> --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:<id>` 以确保明确无歧义。
- 如果你在日志或存储的"最后路由"目标中看到 `telegram:...` 前缀，这是正常的；定时任务投递接受这些前缀并仍能正确解析主题 ID。
- 对于论坛话题，使用 `-100…:topic:<id>` 以确保明确无歧义。
- 如果你在日志或存储的"最后路由"目标中看到 `telegram:...` 前缀，这是正常的；定时任务发送接受它们并仍然正确解析话题 ID。

70
docs/zh-CN/automation/gmail-pubsub.md
View File

@@ -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 <url>` 或 `--tailscale off`。
想要自定义端点？使用 `--push-endpoint <url>` 或 `--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 <project-id>
```
注意：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 <svc@...>
## 测试
向被监控的收件箱发送一封邮件：
向被监视的收件箱发送一条消息：
```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 <historyId>
## 故障排除
- `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` 获取。
## 清理

29
docs/zh-CN/automation/poll.md
View File

@@ -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`。

66
docs/zh-CN/automation/webhook.md
View File

@@ -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 <token>`（推荐）
- `x-openclaw-token: <token>`
- `?token=<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:<uuid>`。使用一致的键可以在 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/<name>`（映射）
自定义 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`（危险）。

36
docs/zh-CN/bedrock.md
View File

@@ -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 提供商。

16
docs/zh-CN/brave-search.md
View File

@@ -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 配置。

166
docs/zh-CN/broadcast-groups.md
View File

@@ -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 速率限制
## 未来增强
计划中的功能：
- [ ] 共享上下文模式（智能体可以看到彼此的回复）
- [ ] 智能体协调（智能体可以互相通信）
- [ ] 共享上下文模式（智能体可以看到彼此的响应）
- [ ] 智能体协调（智能体可以相互发信号）
- [ ] 动态智能体选择（根据消息内容选择智能体）
- [ ] 智能体优先级（某些智能体先于其他智能体回复）
- [ ] 智能体优先级（某些智能体先于其他智能体响应）
## 另请参阅

138
docs/zh-CN/channels/bluebubbles.md
View File

@@ -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=<password>`）。
5. 启动 Gateway网关；它将注册 webhook 处理器并开始配对。
4. 将 BlueBubbles webhook 指向你的 Gateway 网关（示例：`https://your-gateway-host:3000/bluebubbles-webhook?password=<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 <password>
```
## 访问控制（私聊 + 群组）
## 访问控制（私信 + 群组）
私聊：
私信：
- 默认：`channels.bluebubbles.dmPolicy = "pairing"`。
- 未知发送者会收到配对码；消息在批准前会被忽略（配对码 1 小时后过期）。
- 通过以下方式批准：
- 未知发送者会收到配对码；在批准之前消息会被忽略（配对码 1 小时后过期）。
- 批准方式：
- `openclaw pairing list bluebubbles`
- `openclaw pairing approve bluebubbles <CODE>`
- 配对是默认的令牌交换方式。详情：[配对](/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 <code>`。
- 回应功能需要 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)指南。

311
docs/zh-CN/channels/discord.md
View File

@@ -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:<agentId>:discord:channel:<channelId>` 保持隔离（显示名称使用 `discord:<guildSlug>#<channelSlug>`）。
- 群组私信默认被忽略；通过 `channels.discord.dm.groupEnabled` 启用，可选通过 `channels.discord.dm.groupChannels` 限制。
- 保持路由确定性：回复始终发回消息到达的渠道。
- 直接聊天会合并到智能体的主会话（默认 `agent:main:main`）；服务器频道保持隔离为 `agent:<agentId>:discord:channel:<channelId>`（显示名称使用 `discord:<guildSlug>#<channelSlug>`）。
- 群组私信默认被忽略；通过 `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>`（或 `<@id>` 提及）；所有回合都进入共享的 `main` 会话。裸数字 ID 具有歧义性，会被拒绝。
6. 服务器频道：投递时使用 `channel:<channelId>`。默认需要提及，可按服务器或按频道设置。
7. 私聊：默认通过 `channels.discord.dm.policy`（默认：`"pairing"`）进行安全保护。未知发送者会收到配对码（1 小时后过期）；通过 `openclaw pairing approve discord <code>` 批准。
4. 运行 Gateway 网关；当令牌可用（配置优先，环境变量回退）且 `channels.discord.enabled` 不为 `false` 时，它会自动启动 Discord 渠道。
- 如果你更喜欢使用环境变量，设置 `DISCORD_BOT_TOKEN`（配置块是可选的）。
5. 直接聊天：发送时使用 `user:<id>`（或 `<@id>` 提及）；所有对话都进入共享的 `main` 会话。纯数字 ID 是模糊的，会被拒绝。
6. 服务器频道：发送时使用 `channel:<channelId>`。默认需要提及，可以按服务器或按频道设置。
7. 直接聊天：默认通过 `channels.discord.dm.policy` 进行安全保护（默认：`"pairing"`）。未知发送者会收到配对码（1 小时后过期）；通过 `openclaw pairing approve discord <code>` 批准。
- 要保持旧的"对任何人开放"行为：设置 `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:<agentId>:discord:slash:<userId>`）而非共享的 `main` 会话。
11. 可选服务器上下文历史：设置 `channels.discord.historyLimit`（默认 20，回退到 `messages.groupChat.historyLimit`）以在回复提及时包含最近 N 条服务器消息作为上下文。设置 `0` 禁用。
12. 表情反应：智能体可以通过 `discord` 工具触发表情反应（受 `channels.discord.actions.*` 控制）。
- 表情反应移除语义：参见 [/tools/reactions](/tools/reactions)。
- `discord` 工具仅在当前渠道是 Discord 时暴露。
13. 原生命令使用隔离的会话键（`agent:<agentId>:discord:slash:<userId>`）而不是共享的 `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.<id>.users` 允许列表和/或在 `AGENTS.md` 和 `SOUL.md` 中设置明确的防护规则来防止机器人之间的回复循环。
- 使用 `"*"` 频道条目在所有频道应用默认值；显式频道条目覆盖通配符。
- 话题继承父频道配置（允许列表、`requireMention`、Skills、提示词等），除非你显式添加话题频道 ID。
- 机器人发送的消息默认被忽略；设置 `channels.discord.allowBots=true` 允许它们（自己的消息仍被过滤）。
- 警告：如果你允许回复其他机器人（`channels.discord.allowBots=true`），请使用 `requireMention`、`channels.discord.guilds.*.channels.<id>.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.<id>.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.<id>.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 <id> ...` 仅用于转发的审批，不会解析 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.<id>.slug`：用于显示名称的可选友好 slug。
- `guilds.<id>.users`：可选的按服务器用户允许列表（ID 或名称）。
- `guilds.<id>.tools`：可选的按服务器工具策略覆盖（`allow`/`deny`/`alsoAllow`），在频道覆盖缺失时使用。
- `guilds.<id>.toolsBySender`：可选的按发送者工具策略覆盖（服务器级别，在频道覆盖缺失时应用；支持 `"*"` 通配符）。
- `guilds.<id>.users`：可选的每服务器用户允许列表（ID 或名称）。
- `guilds.<id>.tools`：可选的每服务器工具策略覆盖（`allow`/`deny`/`alsoAllow`），在频道覆盖缺失时使用。
- `guilds.<id>.toolsBySender`：服务器级别的可选每发送者工具策略覆盖（在频道覆盖缺失时应用；支持 `"*"` 通配符）。
- `guilds.<id>.channels.<channel>.allow`：当 `groupPolicy="allowlist"` 时允许/拒绝频道。
- `guilds.<id>.channels.<channel>.requireMention`：频道的提及门控。
- `guilds.<id>.channels.<channel>.tools`：可选的按频道工具策略覆盖（`allow`/`deny`/`alsoAllow`）。
- `guilds.<id>.channels.<channel>.toolsBySender`：可选的频道内按发送者工具策略覆盖（支持 `"*"` 通配符）。
- `guilds.<id>.channels.<channel>.users`：可选的按频道用户允许列表。
- `guilds.<id>.channels.<channel>.requireMention`：频道的提及限制。
- `guilds.<id>.channels.<channel>.tools`：可选的每频道工具策略覆盖（`allow`/`deny`/`alsoAllow`）。
- `guilds.<id>.channels.<channel>.toolsBySender`：频道内的可选每发送者工具策略覆盖（支持 `"*"` 通配符）。
- `guilds.<id>.channels.<channel>.users`：可选的每频道用户允许列表。
- `guilds.<id>.channels.<channel>.skills`：Skills 过滤器（省略 = 所有 Skills，空 = 无）。
- `guilds.<id>.channels.<channel>.systemPrompt`：频道的额外系统提示（与频道主题合并）。
- `guilds.<id>.channels.<channel>.enabled`：设置 `false` 可禁用频道。
- `guilds.<id>.channels.<channel>.systemPrompt`：频道的额外系统提示词（与频道主题组合）。
- `guilds.<id>.channels.<channel>.enabled`：设置 `false` 禁用频道。
- `guilds.<id>.channels`：频道规则（键为频道 slug 或 ID）。
- `guilds.<id>.requireMention`：按服务器的提及要求（可按频道覆盖）。
- `guilds.<id>.reactionNotifications`：回应系统事件模式（`off`、`own`、`all`、`allowlist`）。
- `textChunkLimit`：出站文本分块大小（字符）。默认：2000。
- `chunkMode`：`length`（默认）仅在超过 `textChunkLimit` 时分割；`newline` 在按长度分块之前按空行（段落边界）分割。
- `guilds.<id>.requireMention`：每服务器提及要求（可按频道覆盖）。
- `guilds.<id>.reactionNotifications`：表情反应系统事件模式（`off`、`own`、`all`、`allowlist`）。
- `textChunkLimit`：出站文本块大小（字符）。默认：2000。
- `chunkMode`：`length`（默认）仅在超过 `textChunkLimit` 时分割；`newline` 在空行（段落边界）处分割，然后再进行长度分块。
- `maxLinesPerMessage`：每条消息的软最大行数。默认：17。
- `mediaMaxMb`：限制保存到磁盘的入站媒体大小。
- `historyLimit`：回复提及时包含的最近服务器消息数作为上下文（默认 20；回退到 `messages.groupChat.historyLimit`；`0` 禁用）。
- `dmHistoryLimit`：私信历史限制（用户回合数）。按用户覆盖：`dms["<user_id>"].historyLimit`。
- `historyLimit`：回复提及时作为上下文包含的最近服务器消息数量（默认 20；回退到 `messages.groupChat.historyLimit`；`0` 禁用）。
- `dmHistoryLimit`：私信历史限制（用户轮次）。每用户覆盖：`dms["<user_id>"].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.<id>.reactionNotifications`：
表情反应通知使用 `guilds.<id>.reactionNotifications`：
- `off`：无回应事件。
- `own`：机器人自己消息上的回应（默认）。
- `all`：所有消息上的所有回应。
- `allowlist`：来自 `guilds.<id>.users` 的用户在所有消息上的回应（空列表则禁用）。
- `off`：无表情反应事件。
- `own`：机器人自己消息上的表情反应（默认）。
- `all`：所有消息上的所有表情反应。
- `allowlist`：来自 `guilds.<id>.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.<id>.users` 或按频道的 `users` 中使用 `pk:<memberId>`。
- 成员显示名称也通过名称/slug 匹配。
- 查找使用**原始** Discord 消息 ID（代理前的消息），因此 PK API 仅在其 30 分钟窗口内解析它。
- 如果 PK 查找失败（例如没有 token 的私有系统），代理消息被视为机器人消息并被丢弃，除非设置 `channels.discord.allowBots=true`。
- 在 `dm.allowFrom`、`guilds.<id>.users` 或每频道 `users` 中使用 `pk:<memberId>`。
- 成员显示名称也按名称/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。
当前消息 ID 以 `[message_id: …]` 附加到提示中；历史条目已包含 ID。
- `[[reply_to:<id>]]` — 回复上下文/历史中的特定消息 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.<id>.channels` 时，未列出的频道默认被拒绝。
- 当省略 `guilds.<id>.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`）。

110
docs/zh-CN/channels/googlechat.md
View File

@@ -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 &lt;Your Domain&gt;**。
- 在文本框中输入你的邮箱地址（例如 `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://<node-name>.<tailnet>.ts.net/googlechat`
你的私有仪表板仅限 tailnet 访问：
`https://<node-name>.<tailnet>.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 <token>` 头。
2. OpenClaw 根据配置的 `audienceType` + `audience` 验证 token：
1. Google Chat 向 Gateway 网关发送 webhook POST 请求。每个请求都包含一个 `Authorization: Bearer <token>` 头。
2. OpenClaw 根据配置的 `audienceType` + `audience` 验证令牌：
- `audienceType: "app-url"` → audience 是你的 HTTPS webhook URL。
- `audienceType: "project-number"` → audience 是 Cloud 项目编号。
3. 消息按空间路由：
- 私信使用会话键 `agent:<agentId>:googlechat:dm:<spaceId>`。
- 空间使用会话键 `agent:<agentId>:googlechat:group:<spaceId>`。
4. 私信访问默认需要配对。未知发送者会收到配对码；通过以下方式批准：
4. 私信访问默认为配对模式。未知发送者会收到配对码；使用以下命令批准：
- `openclaw pairing approve googlechat <code>`
5. 群组空间默认需要 @提及。如果提及检测需要应用的用户名，请使用 `botUser`。
## 目标
## 目标标识符
使用以下标识符进行投递和允许列表：
使用这些标识符进行消息投递和允许列表：
- 私信：`users/<userId>` 或 `users/<email>`（接受邮箱地址）。
- 空间：`spaces/<spaceId>`。
@@ -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)

34
docs/zh-CN/channels/grammy.md
View File

@@ -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:<agentId>:<mainKey>`）；群组使用 `agent:<agentId>:telegram:group:<chatId>`；回复路由回同一渠道。
- **配置选项：** `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:<agentId>:<mainKey>`）；群组使用 `agent:<agentId>:telegram:group:<chatId>`；回复路由回同一渠道。
- **配置选项：** `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 网关配置）。

130
docs/zh-CN/channels/imessage.md
View File

@@ -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:<agentId>:imessage:group:<chat_id>`）。
- 如果多参与者线程以 `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 <bot-macos-user>@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`）。将 `<bot-macos-user>` 替换为你的实际 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 <bot-macos-user>@localhost true
exec /usr/bin/ssh -o BatchMode=yes -o ConnectTimeout=5 -T <bot-macos-user>@localhost \
"/usr/local/bin/imsg" "$@"
@@ -118,11 +118,11 @@ exec /usr/bin/ssh -o BatchMode=yes -o ConnectTimeout=5 -T <bot-macos-user>@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 <bot-macos-user>@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 <CODE>`
- 配对是 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:<agentId>:imessage:group:<chat_id>` 会话键）
- 群组允许列表/提及门控行为
- 群组允许列表 / 提及检测行为
示例：
@@ -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["<handle>"].historyLimit`。
- `channels.imessage.groups`：按群组默认值 + 允许列表（使用 `"*"` 设置全局默认值）。
- `channels.imessage.includeAttachments`：将附件接收到上下文中。
- `channels.imessage.historyLimit` / `channels.imessage.accounts.*.historyLimit`：作为上下文包含的最大群组消息数（0 禁用）。
- `channels.imessage.dmHistoryLimit`：私信历史限制（用户轮次）。每用户覆盖：`channels.imessage.dms["<handle>"].historyLimit`。
- `channels.imessage.groups`：每群组默认值 + 允许列表（使用 `"*"` 作为全局默认值）。
- `channels.imessage.includeAttachments`：将附件摄取到上下文。
- `channels.imessage.mediaMaxMb`：入站/出站媒体上限（MB）。
- `channels.imessage.textChunkLimit`：出站分块大小（字符）。
- `channels.imessage.chunkMode`：`length`（默认）或 `newline`，在按长度分块之前按空行（段落边界）分割。
- `channels.imessage.chunkMode`：`length`（默认）或 `newline` 在长度分块前按空行（段落边界）分割。
相关全局选项：

36
docs/zh-CN/channels/index.md
View File

@@ -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)。

62
docs/zh-CN/channels/line.md
View File

@@ -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.<id>.webhookPath` 并相应更新 URL。
Gateway 网关会响应 LINE 的 webhook 验证（GET）和入站事件（POST）。如果你需要自定义路径，请设置 `channels.line.webhookPath` 或 `channels.line.accounts.<id>.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 <CODE>
允许列表和策略：
- `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.<groupId>.allowFrom`
- `channels.line.groupAllowFrom`：群组的允许列表 LINE 用户 ID
- 单群组覆盖：`channels.line.groups.<groupId>.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`。

124
docs/zh-CN/channels/matrix.md
View File

@@ -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/<account>/<homeserver>__<user>/<token-hash>/crypto/`（SQLite 数据库）。同步状态存储在同一目录下的 `bot-storage.json` 中。如果访问 token（设备）发生变化，会创建新的存储，机器人必须重新验证才能在加密房间中使用。
加密状态按账户 + 访问令牌存储在 `~/.openclaw/matrix/accounts/<account>/<homeserver>__<user>/<token-hash>/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 <CODE>`
- 公开私信：`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）。

34
docs/zh-CN/channels/mattermost.md
View File

@@ -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:<id>` 用于频道
- `user:<id>` 用于私信
@@ -137,6 +139,6 @@ Mattermost 支持在 `channels.mattermost.accounts` 下配置多个账户：
## 故障排除
- 频道中没有回复：确保机器人已加入频道并提及它（oncall 模式），使用触发前缀（onchar 模式），或设置 `chatmode: "onmessage"`。
- 频道中无回复：确保 bot 在频道中并提及它（oncall），使用触发前缀（onchar），或设置 `chatmode: "onmessage"`。
- 认证错误：检查 bot token、基础 URL 以及账户是否已启用。
- 多账户问题：环境变量仅适用于 `default` 账户。

347
docs/zh-CN/channels/msteams.md
View File

@@ -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 = <App ID>`。
- 范围：`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://<host>: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["<user_id>"].historyLimit`。
- `channels.msteams.historyLimit` 控制将多少条最近的频道/群组消息包含到提示中。
- 回退到 `messages.groupChat.historyLimit`。设置 `0` 禁用（默认 50）。
- 私信历史可以通过 `channels.msteams.dmHistoryLimit`（用户轮次）限制。每用户覆盖：`channels.msteams.dms["<user_id>"].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.<teamId>.replyStyle`：按团队覆盖。
- `channels.msteams.teams.<teamId>.requireMention`：按团队覆盖。
- `channels.msteams.teams.<teamId>.tools`：按团队默认工具策略覆盖（`allow`/`deny`/`alsoAllow`），在频道覆盖缺失时使用。
- `channels.msteams.teams.<teamId>.toolsBySender`：按团队按发送者工具策略覆盖（支持 `"*"` 通配符）。
- `channels.msteams.teams.<teamId>.channels.<conversationId>.replyStyle`：按频道覆盖。
- `channels.msteams.teams.<teamId>.channels.<conversationId>.requireMention`：按频道覆盖。
- `channels.msteams.teams.<teamId>.channels.<conversationId>.tools`：按频道工具策略覆盖（`allow`/`deny`/`alsoAllow`）。
- `channels.msteams.teams.<teamId>.channels.<conversationId>.toolsBySender`：按频道按发送者工具策略覆盖（支持 `"*"` 通配符）。
- `channels.msteams.sharePointSiteId`：用于群聊/频道文件上传的 SharePoint 站点 ID（参见[在群聊中发送文件](#在群聊中发送文件)）。
- `channels.msteams.replyStyle`：`thread | top-level`（见[回复样式](#reply-style-threads-vs-posts)）。
- `channels.msteams.teams.<teamId>.replyStyle`：每团队覆盖。
- `channels.msteams.teams.<teamId>.requireMention`：每团队覆盖。
- `channels.msteams.teams.<teamId>.tools`：当缺少频道覆盖时使用的默认每团队工具策略覆盖（`allow`/`deny`/`alsoAllow`）。
- `channels.msteams.teams.<teamId>.toolsBySender`：默认每团队每发送者工具策略覆盖（支持 `"*"` 通配符）。
- `channels.msteams.teams.<teamId>.channels.<conversationId>.replyStyle`：每频道覆盖。
- `channels.msteams.teams.<teamId>.channels.<conversationId>.requireMention`：每频道覆盖。
- `channels.msteams.teams.<teamId>.channels.<conversationId>.tools`：每频道工具策略覆盖（`allow`/`deny`/`alsoAllow`）。
- `channels.msteams.teams.<teamId>.channels.<conversationId>.toolsBySender`：每频道每发送者工具策略覆盖（支持 `"*"` 通配符）。
- `channels.msteams.sharePointSiteId`：用于群聊/频道文件上传的 SharePoint 站点 ID（见[在群聊中发送文件](#sending-files-in-group-chats)）。
## 路由与会话
## 路由和会话
- 会话键遵循标准智能体格式（参见 [/concepts/session](/concepts/session)）：
- 会话键遵循标准智能体格式（见 [/concepts/session](/concepts/session)）：
- 私信共享主会话（`agent:<agentId>:<mainKey>`）。
- 频道/群组消息使用会话 ID：
- `agent:<agentId>:msteams:channel:<conversationId>`
- `agent:<agentId>:msteams:group:<conversationId>`
## 回复样式：线程 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:<id> ...`
- 投票由 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)

65
docs/zh-CN/channels/nextcloud-talk.md
View File

@@ -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" "<shared-secret>" "<webhook-url>" --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 <CODE>`
- 公开私信：`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）。

72
docs/zh-CN/channels/nostr.md
View File

@@ -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 <path-to-openclaw>/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 礼物包装）。

92
docs/zh-CN/channels/signal.md
View File

@@ -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:<agentId>:signal:group:<groupId>`）。
## 配置写入
默认情况下，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 <CODE>`
- 配对是 Signal 私信的默认令牌交换方式。详情：[配对](/start/pairing)
- 仅 UUID 的发送者（来自 `sourceUuid`）以 `uuid:<id>` 形式存储在 `channels.signal.allowFrom` 中。
- 仅有 UUID 的发送者（来自 `sourceUuid`）在 `channels.signal.allowFrom` 中存储为 `uuid:<id>`。
群组：
@@ -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:<id>`；裸 UUID 也可以）。
- `messageId` 是你要回应的消息的 Signal 时间戳。
- 群组回应需要 `targetAuthor` 或 `targetAuthorUuid`。
- 群组表情回应需要 `targetAuthor` 或 `targetAuthorUuid`。
示例：
@@ -162,13 +162,13 @@ message action=react channel=signal target=signal:group:<groupId> 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.<id>.actions.reactions`、`channels.signal.accounts.<id>.reactionLevel`。
- `off`/`ack` 禁用智能体表情回应（message 工具 `react` 会报错）。
- `minimal`/`extensive` 启用智能体表情回应并设置指导级别。
- 每账户覆盖：`channels.signal.accounts.<id>.actions.reactions`、`channels.signal.accounts.<id>.reactionLevel`。
## 投递目标（CLI/定时任务）
## 投递目标（CLI/cron）
- 私信：`signal:+15551234567`（或纯 E.164）。
- UUID 私信：`uuid:<id>`（或裸 UUID）。
@@ -182,24 +182,24 @@ message action=react channel=signal target=signal:group:<groupId> 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:<id>`）。`open` 需要 `"*"`。Signal 没有用户名；使用电话/UUID 标识。
- `channels.signal.allowFrom`：私信允许列表（E.164 或 `uuid:<id>`）。`open` 需要 `"*"`。Signal 没有用户名；使用电话/UUID id。
- `channels.signal.groupPolicy`：`open | allowlist | disabled`（默认：allowlist）。
- `channels.signal.groupAllowFrom`：群组发送者允许列表。
- `channels.signal.historyLimit`：包含为上下文的最大群组消息数（0 禁用）。
- `channels.signal.dmHistoryLimit`：私信历史限制（用户回合数）。按用户覆盖：`channels.signal.dms["<phone_or_uuid>"].historyLimit`。
- `channels.signal.historyLimit`：作为上下文包含的最大群组消息数（0 禁用）。
- `channels.signal.dmHistoryLimit`：私信历史限制（用户轮次）。每用户覆盖：`channels.signal.dms["<phone_or_uuid>"].historyLimit`。
- `channels.signal.textChunkLimit`：出站分块大小（字符）。
- `channels.signal.chunkMode`：`length`（默认）或 `newline`，在按长度分块之前按空行（段落边界）分割。
- `channels.signal.chunkMode`：`length`（默认）或 `newline` 在长度分块前按空行（段落边界）分割。
- `channels.signal.mediaMaxMb`：入站/出站媒体上限（MB）。
相关全局选项：

207
docs/zh-CN/channels/slack.md
View File

@@ -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.<id>.userToken`。
用户令牌在配置文件中配置（不支持环境变量）。对于多账户，设置 `channels.slack.accounts.<id>.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.<id>.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>]]` — 回复特定消息 ID。
- `[[reply_to:<id>]]` — 回复特定的消息 id。
## 会话 + 路由
- 私信共享 `main` 会话（与 WhatsApp/Telegram 类似）。
- 私信共享 `main` 会话（与 WhatsApp/Telegram 相同）。
- 频道映射到 `agent:<agentId>:slack:channel:<channelId>` 会话。
- 斜杠命令使用 `agent:<agentId>:slack:slash:<userId>` 会话（前缀可通过 `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 <code>` 批准。
- 默认：`channels.slack.dm.policy="pairing"` — 未知的私信发送者会收到配对码（1 小时后过期）。
- 通过以下方式批准：`openclaw pairing approve slack <code>`。
- 要允许任何人：设置 `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.<id>` 或 `channels.slack.channels.<name>`）：
- `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:<id>` 用于私信
- `channel:<id>` 用于频道
## 工具操作
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.<id>.allowBots` 启用。
- 警告：如果你允许回复其他机器人（`channels.slack.allowBots=true` 或 `channels.slack.channels.<id>.allowBots=true`），请使用 `requireMention`、`channels.slack.channels.<id>.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.<id>.allowBots` 启用。
- 警告：如果你允许回复其他机器人（`channels.slack.allowBots=true` 或 `channels.slack.channels.<id>.allowBots=true`），请使用 `requireMention`、`channels.slack.channels.<id>.users` 白名单和/或在 `AGENTS.md` 和 `SOUL.md` 中设置明确的防护措施来防止机器人之间的回复循环。
- 对于 Slack 工具，表情回应移除语义见 [/tools/reactions](/tools/reactions)。
- 附件在允许且在大小限制内时会下载到媒体存储。

448
docs/zh-CN/channels/telegram.md
View File

@@ -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:<agentId>:telegram:group:<chatId>`）。
- 一个由 Gateway 网关拥有的 Telegram Bot API 渠道。
- 确定性路由：回复返回到 Telegram；模型不会选择渠道。
- 私信共享智能体的主会话；群组保持隔离（`agent:<agentId>:telegram:group:<chatId>`）。
## 设置（快速路径）
### 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["<user_id>"].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["<user_id>"].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.<groupId>.topics.<topicId>` 下添加每个话题的覆盖。
**重要：** 设置 `channels.telegram.groups` 会创建一个**允许列表** - 只有列出的群组（或 `"*"`）会被接受。
论坛话题继承其父群组配置（allowFrom、requireMention、skills、prompts），除非你在 `channels.telegram.groups.<groupId>.topics.<topicId>` 下添加每话题覆盖。
允许所有群组且始终回复：
要允许所有群组并始终响应：
```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:<threadId>` 追加到 Telegram 群组会话键，使每个话题相互隔离。
- 发送输入指示器和回复时携带 `message_thread_id`，确保回复留在话题内。
- 通用话题（thread id `1`）比较特殊：消息发送时省略 `message_thread_id`（Telegram 会拒绝），但输入指示器仍包含它。
- 在模板上下文中暴露 `MessageThreadId` + `IsForum`，用于路由/模板。
- 话题级配置可在 `channels.telegram.groups.<chatId>.topics.<threadId>` 下设置（skills、白名单、自动回复、系统提示词、禁用）。
- 话题配置继承群组设置（requireMention、白名单、skills、提示词、enabled），除非按话题覆盖。
- 将 `:topic:<threadId>` 附加到 Telegram 群组会话键，使每个话题隔离。
- 发送输入指示器和回复时带上 `message_thread_id`，使响应保持在话题内。
- 通用话题（线程 id `1`）是特殊的：消息发送省略 `message_thread_id`（Telegram 会拒绝），但输入指示器仍然包含它。
- 在模板上下文中暴露 `MessageThreadId` + `IsForum` 用于路由/模板。
- 话题特定配置可在 `channels.telegram.groups.<chatId>.topics.<threadId>` 下设置（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.<account>.capabilities`：按账户的功能配置，覆盖该账户的全局默认值。
- `channels.telegram.capabilities`：应用于所有 Telegram 账户的全局默认功能配置，除非被覆盖。
- `channels.telegram.accounts.<account>.capabilities`：每账户功能，覆盖该特定账户的全局默认值。
当所有 Telegram 机器人/账户应具有相同行为时，使用全局设置。当不同机器人需要不同行为时，使用按账户配置（例如，一个账户只处理私聊，另一个允许在群组中使用）。
当所有 Telegram 机器人/账户应具有相同行为时使用全局设置。当不同机器人需要不同行为时使用每账户配置（例如，一个账户只处理私信，而另一个允许在群组中使用）。
## 访问控制（私聊 + 群组）
## 访问控制（私信 + 群组）
### 私聊访问
### 私信访问
- 默认：`channels.telegram.dmPolicy = "pairing"`。未知发送者会收到配对码；消息在批准前被忽略（配对码 1 小时后过期）。
- 默认：`channels.telegram.dmPolicy = "pairing"`。未知发送者收到配对码；在批准之前消息被忽略（配对码 1 小时后过期）。
- 批准方式：
- `openclaw pairing list telegram`
- `openclaw pairing approve telegram <CODE>`
- 配对是 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<bot_token>/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>]]` -- 回复特定消息 ID。
- `[[reply_to:<id>]]` -- 回复特定消息 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）：** 下载并通过视觉能力处理。贴纸在消息内容中显示为 `<media:sticker>` 占位符。
- **动态贴纸（TGS）：** 跳过（不支持 Lottie 格式处理）。
- **视频贴纸（WEBM）：** 跳过（不支持视频格式处理）。
- **静态贴纸（WEBP）：** 下载并通过视觉处理。贴纸在消息内容中显示为 `<media:sticker>` 占位符。
- **动画贴纸（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.<id>.requireMention`：提及门控默认值。
- `channels.telegram.groups.<id>.skills`：Skills 过滤（省略 = 所有 Skills，空 = 无 Skills）。
- `channels.telegram.groups.<id>.allowFrom`：按群组的发送者白名单覆盖。
- `channels.telegram.groups.<id>.systemPrompt`：群组的额外系统提示词。
- `channels.telegram.groups.<id>.enabled`：设为 `false` 时禁用该群组。
- `channels.telegram.groups.<id>.topics.<threadId>.*`：按话题覆盖（与群组字段相同）。
- `channels.telegram.groups.<id>.topics.<threadId>.requireMention`：按话题的提及门控覆盖。
- `channels.telegram.groups.<id>.skills`：skill 过滤器（省略 = 所有 skills，空 = 无）。
- `channels.telegram.groups.<id>.allowFrom`：每群组发送者允许列表覆盖。
- `channels.telegram.groups.<id>.systemPrompt`：群组的额外系统提示。
- `channels.telegram.groups.<id>.enabled`：为 `false` 时禁用群组。
- `channels.telegram.groups.<id>.topics.<threadId>.*`：每话题覆盖（与群组相同的字段）。
- `channels.telegram.groups.<id>.topics.<threadId>.requireMention`：每话题提及门控覆盖。
- `channels.telegram.capabilities.inlineButtons`：`off | dm | group | all | allowlist`（默认：allowlist）。
- `channels.telegram.accounts.<account>.capabilities.inlineButtons`：按账户覆盖。
- `channels.telegram.accounts.<account>.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`。

42
docs/zh-CN/channels/tlon.md
View File

@@ -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（无原生上传）。

133
docs/zh-CN/channels/twitch.md
View File

@@ -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:<agentId>:twitch:<accountName>`。
- `username` 是机器人的账号（用于认证），`channel` 是要加入的聊天室。
- 由 Gateway 网关拥有的 Twitch 渠道。
- 确定性路由：回复总是返回到 Twitch。
- 每个账户映射到一个隔离的会话键 `agent:<agentId>:twitch:<accountName>`。
- `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.<accountName>` - 多账号配置（上述所有账号字段）
- `channels.twitch.username` - 机器人用户名（简化的单账户配置）
- `channels.twitch.accessToken` - OAuth 访问令牌（简化的单账户配置）
- `channels.twitch.clientId` - Twitch Client ID（简化的单账户配置）
- `channels.twitch.channel` - 要加入的频道（简化的单账户配置）
- `channels.twitch.accounts.<accountName>` - 多账户配置（以上所有账户字段）
完整示例：
@@ -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 内置的速率限制）

241
docs/zh-CN/channels/whatsapp.md
View File

@@ -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 <code>`
### 个人号码（备选方案）
快速备选方案：在**你自己的号码**上运行 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 <id>`（`<id>` = `accountId`）。
- 默认账号（省略 `--account` 时）：如果存在则为 `default`，否则为第一个已配置的账号 ID（排序后）。
- 登录命令：`openclaw channels login`（通过关联设备扫描二维码）。
- 多账户登录：`openclaw channels login --account <id>`（`<id>` = `accountId`）。
- 默认账户（省略 `--account` 时）：如果存在则为 `default`，否则为第一个配置的账户 id（排序后）。
- 凭证存储在 `~/.openclaw/credentials/whatsapp/<accountId>/creds.json`。
- 备份副本位于 `creds.json.bak`（损坏时恢复）。
- 旧版兼容：早期安装将 Baileys 文件直接存储在 `~/.openclaw/credentials/`。
- 注销：`openclaw channels logout`（或 `--account <id>`）删除 WhatsApp 认证状态（但保留共享的 `oauth.json`）。
- 已注销的 socket => 错误提示重新关联。
- 备份副本在 `creds.json.bak`（损坏时恢复）。
- 旧版兼容性：较旧的安装将 Baileys 文件直接存储在 `~/.openclaw/credentials/` 中。
- 登出：`openclaw channels logout`（或 `--account <id>`）删除 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 <code>` 批准；码在 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 <code>`（用 `openclaw pairing list whatsapp` 列出）。
- 来自新发送者的第一条私信返回一个短码（消息不会被处理）。
- 使用以下命令批准：`openclaw pairing approve whatsapp <code>`（使用 `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
- 纯媒体入站消息使用占位符：
- `<media:image|video|audio|document|sticker>`
## 群聊
## 群组
- 群聊映射到 `agent:<agentId>:whatsapp:group:<jid>` 会话。
- 群聊策略：`channels.whatsapp.groupPolicy = open|disabled|allowlist`（默认 `allowlist`）。
- 群组映射到 `agent:<agentId>:whatsapp:group:<jid>` 会话。
- 群组策略：`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 <mp4> --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.<accountId>.*`（按账号设置 + 可选 `authDir`）。
- `channels.whatsapp.accounts.<accountId>.mediaMaxMb`（按账号入站媒体上限）。
- `channels.whatsapp.accounts.<accountId>.ackReaction`（按账号确认反应覆盖）。
- `channels.whatsapp.groupAllowFrom`（群聊发送者允许列表）。
- `channels.whatsapp.groupPolicy`（群聊策略）。
- `channels.whatsapp.historyLimit` / `channels.whatsapp.accounts.<accountId>.historyLimit`（群聊历史上下文；`0` 禁用）。
- `channels.whatsapp.dmHistoryLimit`（私聊历史限制，按用户轮数）。按用户覆盖：`channels.whatsapp.dms["<phone>"].historyLimit`。
- `channels.whatsapp.groups`（群聊允许列表 + 提及门控默认值；使用 `"*"` 允许全部）
- `channels.whatsapp.actions.reactions`（WhatsApp 工具反应门控）。
- `channels.whatsapp.ackReaction`（消息收到时的自动回应：`{emoji, direct, group}`）。
- `channels.whatsapp.accounts.<accountId>.*`（按账户设置 + 可选 `authDir`）。
- `channels.whatsapp.accounts.<accountId>.mediaMaxMb`（按账户入站媒体上限）。
- `channels.whatsapp.accounts.<accountId>.ackReaction`（按账户确认回应覆盖）。
- `channels.whatsapp.groupAllowFrom`（群组发送者允许列表）。
- `channels.whatsapp.groupPolicy`（群组策略）。
- `channels.whatsapp.historyLimit` / `channels.whatsapp.accounts.<accountId>.historyLimit`（群组历史上下文；`0` 禁用）。
- `channels.whatsapp.dmHistoryLimit`（私信历史限制，按用户轮次）。按用户覆盖：`channels.whatsapp.dms["<phone>"].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.<accountId>.messagePrefix`；已弃用：`messages.messagePrefix`）
- `channels.whatsapp.messagePrefix`（入站前缀；按账户：`channels.whatsapp.accounts.<accountId>.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 网关。（参见入门指南运行时说明。）

124
docs/zh-CN/channels/zalo.md
View File

@@ -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 <CODE>`
- 配对是默认的令牌交换方式。详情：[配对](/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.<id>.botToken`：每个账户的令牌。
- `channels.zalo.accounts.<id>.tokenFile`：每个账户的令牌文件。
- `channels.zalo.accounts.<id>.botToken`：每账户 token。
- `channels.zalo.accounts.<id>.tokenFile`：每账户 token 文件。
- `channels.zalo.accounts.<id>.name`：显示名称。
- `channels.zalo.accounts.<id>.enabled`：启用/禁用账户。
- `channels.zalo.accounts.<id>.dmPolicy`：每个账户的私信策略。
- `channels.zalo.accounts.<id>.allowFrom`：每个账户的允许列表。
- `channels.zalo.accounts.<id>.webhookUrl`：每个账户的 webhook URL。
- `channels.zalo.accounts.<id>.webhookSecret`：每个账户的 webhook 密钥。
- `channels.zalo.accounts.<id>.webhookPath`：每个账户的 webhook 路径。
- `channels.zalo.accounts.<id>.proxy`：每个账户的代理 URL。
- `channels.zalo.accounts.<id>.dmPolicy`：每账户私信策略。
- `channels.zalo.accounts.<id>.allowFrom`：每账户允许列表。
- `channels.zalo.accounts.<id>.webhookUrl`：每账户 webhook URL。
- `channels.zalo.accounts.<id>.webhookSecret`：每账户 webhook secret。
- `channels.zalo.accounts.<id>.webhookPath`：每账户 webhook 路径。
- `channels.zalo.accounts.<id>.proxy`：每账户代理 URL。

64
docs/zh-CN/channels/zalouser.md
View File

@@ -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`

70
docs/zh-CN/cli/acp.md
View File

@@ -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 <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 <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 <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:<uuid>` 会话。
每个 ACP 会话映射到单个 Gateway 网关会话键。一个智能体可以有多个会话；除非你覆盖键或标签，否则 ACP 默认使用隔离的 `acp:<uuid>` 会话。
## 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 <key>`：使用特定的 Gateway网关会话密钥。
- `--session <key>`：使用特定的 Gateway 网关会话键。
- `--session-label <label>`：通过标签解析现有会话。
- `--reset-session`：为该密钥生成新的会话 ID（相同密钥，新的对话记录）。
- `--reset-session`：为该键生成新的会话 ID（相同键，新对话记录）。
如果你的 ACP 客户端支持元数据，你可以按会话进行覆盖：
如果你的 ACP 客户端支持元数据，你可以按会话覆盖：
```json
{
@@ -150,19 +150,19 @@ openclaw acp --session agent:qa:bug-123
}
```
了解更多关于会话密钥的信息，请参阅 [/concepts/session](/concepts/session)。
在 [/concepts/session](/concepts/session) 了解更多关于会话键的信息。
## 选项
- `--url <url>`：Gateway网关 WebSocket URL（配置后默认使用 gateway.remote.url）。
- `--token <token>`：Gateway网关认证令牌。
- `--password <password>`：Gateway网关认证密码。
- `--session <key>`：默认会话密钥。
- `--url <url>`：Gateway 网关 WebSocket URL（配置后默认为 gateway.remote.url）。
- `--token <token>`：Gateway 网关认证令牌。
- `--password <password>`：Gateway 网关认证密码。
- `--session <key>`：默认会话键。
- `--session-label <label>`：要解析的默认会话标签。
- `--require-existing`：如果会话密钥/标签不存在则失败。
- `--reset-session`：在首次使用前重置会话密钥。
- `--require-existing`：如果会话键/标签不存在则失败。
- `--reset-session`：在首次使用前重置会话键。
- `--no-prefix-cwd`：不在提示前添加工作目录前缀。
- `--verbose, -v`：将详细日志输出到 stderr。
- `--verbose, -v`：向 stderr 输出详细日志。
### `acp client` 选项

13
docs/zh-CN/cli/agent.md
View File

@@ -1,25 +1,24 @@
---
read_when:
- 你想从脚本中运行一次智能体轮次（可选择投递回复）
summary: "`openclaw agent` 的 CLI 参考（通过 Gateway网关发送一次智能体轮次）"
- 你想从脚本运行一个智能体回合（可选发送回复）
summary: "`openclaw agent` 的 CLI 参考（通过 Gateway 网关发送一个智能体回合）"
title: agent
x-i18n:
generated_at: "2026-02-01T19:58:31Z"
generated_at: "2026-02-03T07:44:38Z"
model: claude-opus-4-5
provider: pi
source_hash: dcf12fb94e207c68645f58235792596d65afecf8216b8f9ab3acb01e03b50a33
source_path: cli/agent.md
workflow: 14
workflow: 15
---
# `openclaw agent`
通过 Gateway网关运行一次智能体轮次（使用 `--local` 进行嵌入式运行）。
使用 `--agent <id>` 直接指定一个已配置的智能体。
通过 Gateway 网关运行智能体回合（使用 `--local` 进行嵌入式运行）。使用 `--agent <id>` 直接指定已配置的智能体。
相关内容：
- 智能体发送工具：[智能体发送](/tools/agent-send)
- 智能体发送工具：[Agent send](/tools/agent-send)
## 示例

18
docs/zh-CN/cli/approvals.md
View File

@@ -1,22 +1,22 @@
---
read_when:
- 你想通过 CLI 编辑执行审批
- 你需要管理 Gateway网关或节点主机上的允许列表
summary: "`openclaw approvals` 的 CLI 参考（用于 Gateway网关或节点主机的执行审批）"
- 你需要管理 Gateway 网关或节点主机上的允许列表
summary: CLI 参考：`openclaw approvals`（Gateway 网关或节点主机的执行审批）
title: approvals
x-i18n:
generated_at: "2026-02-01T19:58:39Z"
generated_at: "2026-02-03T10:04:09Z"
model: claude-opus-4-5
provider: pi
source_hash: 4329cdaaec2c5f5d619415b6431196512d4834dc1ccd7363576f03dd9b845130
source_path: cli/approvals.md
workflow: 14
workflow: 15
---
# `openclaw approvals`
管理**本地主机**、**Gateway网关主机**或**节点主机**的执行审批。
默认情况下，命令针对磁盘上的本地审批文件。使用 `--gateway` 针对 Gateway网关，或使用 `--node` 针对特定节点。
管理**本地主机**、**Gateway 网关主机**或**节点主机**的执行审批。
默认情况下，命令针对磁盘上的本地审批文件。使用 `--gateway` 可针对 Gateway 网关，使用 `--node` 可针对特定节点。
相关内容：
@@ -51,7 +51,7 @@ openclaw approvals allowlist remove "~/Projects/**/bin/rg"
## 注意事项
- `--node` 使用与 `openclaw nodes` 相同的解析器（id、名称、ip 或 id 前缀）。
- `--agent` 默认为 `"*"`，即适用于所有智能体。
- 节点主机必须公布 `system.execApprovals.get/set`（macOS 应用或无头节点主机）。
- `--node` 使用与 `openclaw nodes` 相同的解析器（id、name、ip 或 id 前缀）。
- `--agent` 默认为 `"*"`，表示适用于所有智能体。
- 节点主机必须公开 `system.execApprovals.get/set`（macOS 应用或无头节点主机）。
- 审批文件按主机存储在 `~/.openclaw/exec-approvals.json`。

44
docs/zh-CN/cli/browser.md
View File

@@ -1,35 +1,35 @@
---
read_when:
- 使用 `openclaw browser` 并需要常见任务的示例
- 想要通过节点主机控制运行在另一台机器上的浏览器
- 想要使用 Chrome 扩展中继（通过工具栏按钮附加/分离）
- 你使用 `openclaw browser` 并想要常见任务的示例
- 你想通过 node host 控制在另一台机器上运行的浏览器
- 你想使用 Chrome 扩展中继（通过工具栏按钮附加/分离）
summary: "`openclaw browser` 的 CLI 参考（配置文件、标签页、操作、扩展中继）"
title: browser
x-i18n:
generated_at: "2026-02-01T19:58:45Z"
generated_at: "2026-02-03T07:44:49Z"
model: claude-opus-4-5
provider: pi
source_hash: af35adfd68726fd519c704d046451effd330458c2b8305e713137fb07b2571fd
source_path: cli/browser.md
workflow: 14
workflow: 15
---
# `openclaw browser`
管理 OpenClaw 的浏览器控制服务器并执行浏览器操作（标签页、快照、截图、导航、点击、输入）。
管理 OpenClaw 的浏览器控制服务器并运行浏览器操作（标签页、快照、截图、导航、点击、输入）。
相关内容：
相关：
- 浏览器工具 + API：[浏览器工具](/tools/browser)
- Chrome 扩展中继：[Chrome 扩展](/tools/chrome-extension)
## 常用标志
## 通用标志
- `--url <gatewayWsUrl>`：Gateway网关 WebSocket URL（默认使用配置值）。
- `--token <token>`：Gateway网关令牌（如需要）。
- `--timeout <ms>`：请求超时时间（毫秒）。
- `--browser-profile <name>`：选择浏览器配置文件（默认使用配置值）。
- `--json`：机器可读输出（在支持的情况下）。
- `--url <gatewayWsUrl>`：Gateway 网关 WebSocket URL（默认从配置获取）。
- `--token <token>`：Gateway 网关令牌（如果需要）。
- `--timeout <ms>`：请求超时（毫秒）。
- `--browser-profile <name>`：选择浏览器配置文件（默认从配置获取）。
- `--json`：机器可读输出（在支持的地方）。
## 快速开始（本地）
@@ -42,9 +42,9 @@ openclaw browser --browser-profile openclaw snapshot
## 配置文件
配置文件是命名的浏览器路由配置。实际使用中：
配置文件是命名的浏览器路由配置。实际上：
- `openclaw`：启动/附加到一个专用的 OpenClaw 管理的 Chrome 实例（隔离的用户数据目录）。
- `openclaw`：启动/附加到专用的 OpenClaw 管理的 Chrome 实例（隔离的用户数据目录）。
- `chrome`：通过 Chrome 扩展中继控制你现有的 Chrome 标签页。
```bash
@@ -82,7 +82,7 @@ openclaw browser snapshot
openclaw browser screenshot
```
导航/点击/输入（基于引用的 UI 自动化）：
导航/点击/输入（基于 ref 的 UI 自动化）：
```bash
openclaw browser navigate https://example.com
@@ -92,7 +92,7 @@ openclaw browser type <ref> "hello"
## Chrome 扩展中继（通过工具栏按钮附加）
此模式允许智能体控制你手动附加的现有 Chrome 标签页（不会自动附加）。
此模式让智能体控制你手动附加的现有 Chrome 标签页（不会自动附加）。
将未打包的扩展安装到稳定路径：
@@ -101,14 +101,14 @@ openclaw browser extension install
openclaw browser extension path
```
然后在 Chrome 中 → `chrome://extensions` → 启用"开发者模式" → "加载已解压的扩展程序" → 选择打印出的文件夹。
然后 Chrome → `chrome://extensions` → 启用"开发者模式" → "加载已解压的扩展程序" → 选择打印的文件夹。
完整指南：[Chrome 扩展](/tools/chrome-extension)
## 远程浏览器控制（节点主机代理）
## 远程浏览器控制（node host 代理）
如果 Gateway网关与浏览器运行在不同的机器上，请在安装了 Chrome/Brave/Edge/Chromium 的机器上运行**节点主机**。Gateway网关会将浏览器操作代理到该节点（无需单独的浏览器控制服务器）。
如果 Gateway 网关与浏览器运行在不同的机器上，在有 Chrome/Brave/Edge/Chromium 的机器上运行 **node host**。Gateway 网关会将浏览器操作代理到该节点（无需单独的浏览器控制服务器）。
使用 `gateway.nodes.browser.mode` 控制自动路由，使用 `gateway.nodes.browser.node` 在多个节点连接时固定到特定节点。
使用 `gateway.nodes.browser.mode` 控制自动路由，使用 `gateway.nodes.browser.node` 在连接多个节点时固定特定节点。
安全性 + 远程设置：[浏览器工具](/tools/browser)、[远程访问](/gateway/remote)、[Tailscale](/gateway/tailscale)、[安全](/gateway/security)
安全 + 远程设置：[浏览器工具](/tools/browser)、[远程访问](/gateway/remote)、[Tailscale](/gateway/tailscale)、[安全](/gateway/security)

28
docs/zh-CN/cli/channels.md
View File

@@ -1,26 +1,26 @@
---
read_when:
- 你想添加/移除渠道账号（WhatsApp/Telegram/Discord/Google Chat/Slack/Mattermost（插件）/Signal/iMessage）
- 你想检查渠道状态或查看渠道日志
summary: "`openclaw channels` 的 CLI 参考（账号、状态、登录/登出、日志）"
- 你想添加/删除渠道账户（WhatsApp/Telegram/Discord/Google Chat/Slack/Mattermost（插件）/Signal/iMessage）
- 你想检查渠道状态或跟踪渠道日志
summary: "`openclaw channels` 的 CLI 参考（账户、状态、登录/登出、日志）"
title: channels
x-i18n:
generated_at: "2026-02-01T19:58:48Z"
generated_at: "2026-02-03T07:44:51Z"
model: claude-opus-4-5
provider: pi
source_hash: 16ab1642f247bfa96e8e08dfeb1eedfccb148f40d91099f5423f971df2b54e20
source_path: cli/channels.md
workflow: 14
workflow: 15
---
# `openclaw channels`
管理 Gateway网关上的聊天渠道账号及其运行时状态。
管理 Gateway 网关上的聊天渠道账户及其运行时状态。
相关文档：
- 渠道指南：[渠道](/channels/index)
- Gateway网关配置：[配置](/gateway/configuration)
- Gateway 网关配置：[配置](/gateway/configuration)
## 常用命令
@@ -33,14 +33,14 @@ openclaw channels resolve --channel slack "#general" "@jane"
openclaw channels logs --channel all
```
## 添加/移除账号
## 添加/删除账户
```bash
openclaw channels add --channel telegram --token <bot-token>
openclaw channels remove --channel telegram --delete
```
提示：`openclaw channels add --help` 可查看各渠道的专用参数（token、app token、signal-cli 路径等）。
提示：`openclaw channels add --help` 显示每个渠道的标志（token、app token、signal-cli 路径等）。
## 登录/登出（交互式）
@@ -53,7 +53,7 @@ openclaw channels logout --channel whatsapp
- 运行 `openclaw status --deep` 进行全面探测。
- 使用 `openclaw doctor` 获取引导式修复。
- `openclaw channels list` 输出 `Claude: HTTP 403 ... user:profile` → 用量快照需要 `user:profile` 权限范围。使用 `--no-usage`，或提供 claude.ai 会话密钥（`CLAUDE_WEB_SESSION_KEY` / `CLAUDE_WEB_COOKIE`），或通过 Claude Code CLI 重新认证。
- `openclaw channels list` 输出 `Claude: HTTP 403 ... user:profile` → 用量快照需要 `user:profile` 权限范围。使用 `--no-usage`，或提供 claude.ai 会话密钥（`CLAUDE_WEB_SESSION_KEY` / `CLAUDE_WEB_COOKIE`），或通过 Claude Code CLI 重新授权。
## 能力探测
@@ -66,11 +66,11 @@ openclaw channels capabilities --channel discord --target channel:123
说明：
- `--channel` 是可选的；省略时将列出所有渠道（包括扩展）。
- `--target` 接受 `channel:<id>` 或原始数字频道 ID，仅适用于 Discord。
- 探测因提供商而异：Discord intents + 可选的频道权限；Slack bot + 用户权限范围；Telegram bot 标志 + webhook；Signal 守护进程版本；MS Teams 应用令牌 + Graph 角色/权限范围（已知的会标注）。无探测功能的渠道会报告 `Probe: unavailable`。
- `--channel` 是可选的；省略它可列出所有渠道（包括扩展）。
- `--target` 接受 `channel:<id>` 或原始数字频道 id，仅适用于 Discord。
- 探测是特定于提供商的：Discord intents + 可选的频道权限；Slack bot + user scopes；Telegram bot 标志 + webhook；Signal daemon 版本；MS Teams app token + Graph roles/scopes（在已知处标注）。没有探测功能的渠道报告 `Probe: unavailable`。
## 将名称解析为 ID
## 解析名称为 ID
使用提供商目录将渠道/用户名称解析为 ID：

17
docs/zh-CN/cli/config.md
View File

@@ -1,20 +1,21 @@
---
read_when:
- 你想以非交互方式读取或编辑配置
summary: "`openclaw config` 的 CLI 参考（获取/设置/删除配置值）"
summary: "`openclaw config` 的 CLI 参考（获取/设置/取消设置配置值）"
title: config
x-i18n:
generated_at: "2026-02-01T19:58:45Z"
generated_at: "2026-02-03T10:04:13Z"
model: claude-opus-4-5
provider: pi
source_hash: d60a35f5330f22bc99a0df090590586109d329ddd2ca294aeed191a22560c1c2
source_path: cli/config.md
workflow: 14
workflow: 15
---
# `openclaw config`
配置辅助工具：通过路径获取/设置/删除值。不带子命令运行时将打开配置向导（与 `openclaw configure` 相同）。
配置辅助命令：通过路径获取/设置/取消设置值。不带子命令运行将打开
配置向导（与 `openclaw configure` 相同）。
## 示例
@@ -28,14 +29,14 @@ openclaw config unset tools.web.search.apiKey
## 路径
路径使用点号或方括号表示法：
路径使用点号或括号表示法：
```bash
openclaw config get agents.defaults.workspace
openclaw config get agents.list[0].id
```
使用智能体列表索引来指定特定智能体：
使用智能体列表索引来定位特定智能体：
```bash
openclaw config get agents.list
@@ -44,7 +45,7 @@ openclaw config set agents.list[1].tools.exec.node "node-id-or-name"
## 值
值会尽可能按 JSON5 解析；否则视为字符串。
值会尽可能解析为 JSON5；否则将被视为字符串。
使用 `--json` 强制要求 JSON5 解析。
```bash
@@ -53,4 +54,4 @@ openclaw config set gateway.port 19001 --json
openclaw config set channels.whatsapp.groups '["*"]' --json
```
编辑后请重启 Gateway网关。
编辑后请重启 Gateway 网关。

20
docs/zh-CN/cli/configure.md
View File

@@ -1,36 +1,34 @@
---
read_when:
- 你想通过交互方式调整凭据、设备或智能体默认设置
- 你想交互式地调整凭证、设备或智能体默认设置
summary: "`openclaw configure` 的 CLI 参考（交互式配置提示）"
title: configure
x-i18n:
generated_at: "2026-02-01T19:58:46Z"
generated_at: "2026-02-03T07:44:46Z"
model: claude-opus-4-5
provider: pi
source_hash: 9cb2bb5237b02b3a2dca71b5e43b11bd6b9939b9e4aa9ce1882457464b51efd2
source_path: cli/configure.md
workflow: 14
workflow: 15
---
# `openclaw configure`
交互式提示，用于设置凭据、设备和智能体默认配置。
用于设置凭证、设备和智能体默认值的交互式提示。
注意：**模型**部分现在包含一个多选项，用于设置
`agents.defaults.models` 允许列表（决定在 `/model` 和模型选择器中显示哪些模型）。
注意：**模型**部分现在包含一个用于 `agents.defaults.models` 允许列表的多选项（显示在 `/model` 和模型选择器中的内容）。
提示：不带子命令运行 `openclaw config` 会打开相同的向导。使用
`openclaw config get|set|unset` 进行非交互式编辑。
提示：不带子命令的 `openclaw config` 会打开相同的向导。使用 `openclaw config get|set|unset` 进行非交互式编辑。
相关内容：
- Gateway网关配置参考：[配置](/gateway/configuration)
- Gateway 网关配置参考：[配置](/gateway/configuration)
- Config CLI：[Config](/cli/config)
注意事项：
- 选择 Gateway网关运行位置时会始终更新 `gateway.mode`。如果你只需要修改这一项，可以直接选择"继续"而无需配置其他部分。
- 面向渠道的服务（Slack/Discord/Matrix/Microsoft Teams）在设置过程中会提示配置渠道/房间允许列表。你可以输入名称或 ID；向导会尽可能将名称解析为 ID。
- 选择 Gateway 网关运行位置始终会更新 `gateway.mode`。如果这是你唯一需要的，可以不选择其他部分直接选择"继续"。
- 面向渠道的服务（Slack/Discord/Matrix/Microsoft Teams）在设置期间会提示输入频道/房间允许列表。你可以输入名称或 ID；向导会尽可能将名称解析为 ID。
## 示例

22
docs/zh-CN/cli/cron.md
View File

@@ -1,37 +1,37 @@
---
read_when:
- 你需要定时任务和唤醒功能
- 你正在调试定时任务的执行和日志
summary: "`openclaw cron` 的 CLI 参考（调度和运行后台任务）"
- 你需要定时作业和唤醒功能
- 你正在调试 cron 执行和日志
summary: "`openclaw cron` 的 CLI 参考（调度和运行后台作业）"
title: cron
x-i18n:
generated_at: "2026-02-01T19:58:49Z"
generated_at: "2026-02-03T07:44:47Z"
model: claude-opus-4-5
provider: pi
source_hash: bc9317c824f3b6339df657cc269961d9b5f121da65ec2b23a07d454e6d611135
source_path: cli/cron.md
workflow: 14
workflow: 15
---
# `openclaw cron`
管理 Gateway网关调度器的定时任务。
管理 Gateway 网关调度器的 cron 作业。
相关内容：
- 定时任务：[定时任务](/automation/cron-jobs)
- Cron 作业：[Cron 作业](/automation/cron-jobs)
提示：运行 `openclaw cron --help` 查看完整的命令列表。
提示：运行 `openclaw cron --help` 查看完整的命令集。
## 常见编辑
## 常用编辑
更新投递设置而不更改消息内容：
更新投递设置而不更改消息：
```bash
openclaw cron edit <job-id> --deliver --channel telegram --to "123456789"
```
为隔离任务禁用投递：
为隔离的作业禁用投递：
```bash
openclaw cron edit <job-id> --no-deliver

28
docs/zh-CN/cli/devices.md
View File

@@ -1,21 +1,21 @@
---
read_when:
- 你正在审批设备配对请求
- 你需要轮换或吊销设备令牌
summary: "`openclaw devices` 的 CLI 参考（设备配对 + 令牌轮换/吊销）"
- 你正在批准设备配对请求
- 你需要轮换或撤销设备 token
summary: "`openclaw devices` 的 CLI 参考（设备配对 + token 轮换/撤销）"
title: devices
x-i18n:
generated_at: "2026-02-01T19:58:53Z"
generated_at: "2026-02-03T07:44:52Z"
model: claude-opus-4-5
provider: pi
source_hash: 52f903817d2886c1dc29b85d30168d1edff7944bd120a1e139159c9d99a1f517
source_path: cli/devices.md
workflow: 14
workflow: 15
---
# `openclaw devices`
管理设备配对请求和设备范围的令牌。
管理设备配对请求和设备范围的 token。
## 命令
@@ -46,7 +46,7 @@ openclaw devices reject <requestId>
### `openclaw devices rotate --device <id> --role <role> [--scope <scope...>]`
轮换特定角色的设备令牌（可选择更新权限范围）。
为特定角色轮换设备 token（可选更新 scope）。
```
openclaw devices rotate --device <deviceId> --role operator --scope operator.read --scope operator.write
@@ -54,7 +54,7 @@ openclaw devices rotate --device <deviceId> --role operator --scope operator.rea
### `openclaw devices revoke --device <id> --role <role>`
吊销特定角色的设备令牌。
为特定角色撤销设备 token。
```
openclaw devices revoke --device <deviceId> --role node
@@ -62,13 +62,13 @@ openclaw devices revoke --device <deviceId> --role node
## 通用选项
- `--url <url>`：Gateway网关 WebSocket URL（配置后默认使用 `gateway.remote.url`）。
- `--token <token>`：Gateway网关令牌（如需要）。
- `--password <password>`：Gateway网关密码（密码认证）。
- `--timeout <ms>`：RPC 超时时间。
- `--url <url>`：Gateway 网关 WebSocket URL（配置后默认使用 `gateway.remote.url`）。
- `--token <token>`：Gateway 网关 token（如需要）。
- `--password <password>`：Gateway 网关密码（密码认证）。
- `--timeout <ms>`：RPC 超时。
- `--json`：JSON 输出（推荐用于脚本）。
## 注意事项
- 令牌轮换会返回新令牌（敏感信息）。请将其视为机密处理。
- 这些命令需要 `operator.pairing`（或 `operator.admin`）权限范围。
- Token 轮换会返回新 token（敏感信息）。请像对待密钥一样对待它。
- 这些命令需要 `operator.pairing`（或 `operator.admin`）scope。

16
docs/zh-CN/cli/dns.md
View File

@@ -1,26 +1,26 @@
---
read_when:
- 你需要通过 Tailscale + CoreDNS 实现广域发现（DNS-SD）
- 你正在为自定义发现域名设置分离 DNS（例如：openclaw.internal）
summary: "`openclaw dns` 的 CLI 参考（广域发现辅助工具）"
- 你想通过 Tailscale + CoreDNS 实现广域设备发现（DNS-SD）
- You’re setting up split DNS for a custom discovery domain (example: openclaw.internal)
summary: "`openclaw dns` 的 CLI 参考（广域设备发现辅助工具）"
title: dns
x-i18n:
generated_at: "2026-02-01T19:58:53Z"
generated_at: "2026-02-03T07:44:52Z"
model: claude-opus-4-5
provider: pi
source_hash: d2011e41982ffb4b71ab98211574529bc1c8b7769ab1838abddd593f42b12380
source_path: cli/dns.md
workflow: 14
workflow: 15
---
# `openclaw dns`
用于广域发现的 DNS 辅助工具（Tailscale + CoreDNS）。目前专注于 macOS + Homebrew CoreDNS。
用于广域设备发现（Tailscale + CoreDNS）的 DNS 辅助工具。目前专注于 macOS + Homebrew CoreDNS。
相关内容：
- Gateway网关发现：[发现](/gateway/discovery)
- 广域发现配置：[配置](/gateway/configuration)
- Gateway 网关设备发现：[设备发现](/gateway/discovery)
- 广域设备发现配置：[配置](/gateway/configuration)
## 设置

10
docs/zh-CN/cli/docs.md
View File

@@ -1,20 +1,20 @@
---
read_when:
- 想要从终端搜索 OpenClaw 在线文档
summary: "`openclaw docs` 的 CLI 参考（搜索在线文档索引）"
- 你想从终端搜索实时 OpenClaw 文档
summary: "`openclaw docs` 的 CLI 参考（搜索实时文档索引）"
title: docs
x-i18n:
generated_at: "2026-02-01T19:58:52Z"
generated_at: "2026-02-03T07:44:50Z"
model: claude-opus-4-5
provider: pi
source_hash: 7a4000e91f7c6ed1140f684e2d1849577651e9389c5c90532a74db58c0b86d47
source_path: cli/docs.md
workflow: 14
workflow: 15
---
# `openclaw docs`
搜索在线文档索引。
搜索实时文档索引。
```bash
openclaw docs browser extension

16
docs/zh-CN/cli/doctor.md
View File

@@ -1,21 +1,21 @@
---
read_when:
- 遇到连接/认证问题并需要引导修复
- 更新后想要进行安装完整性检查
summary: "`openclaw doctor` 的 CLI 参考（健康检查 + 引导修复）"
- 你遇到连接/认证问题，需要引导式修复
- 你更新后想进行完整性检查
summary: "`openclaw doctor` 的 CLI 参考（健康检查 + 引导式修复）"
title: doctor
x-i18n:
generated_at: "2026-02-01T19:58:59Z"
generated_at: "2026-02-03T10:04:15Z"
model: claude-opus-4-5
provider: pi
source_hash: 92310aa3f3d111e91a74ce1150359d5d8a8d70a856666d9419e16c60d78209f2
source_path: cli/doctor.md
workflow: 14
workflow: 15
---
# `openclaw doctor`
Gateway网关和渠道的健康检查 + 快速修复。
Gateway 网关和渠道的健康检查 + 快速修复。
相关内容：
@@ -30,9 +30,9 @@ openclaw doctor --repair
openclaw doctor --deep
```
备注：
注意事项：
- 交互式提示（如钥匙串/OAuth 修复）仅在 stdin 为 TTY 且**未**设置 `--non-interactive` 时运行。无头运行（cron、Telegram、无终端）将跳过提示。
- 交互式提示（如钥匙串/OAuth 修复）仅在 stdin 是 TTY 且**未**设置 `--non-interactive` 时运行。无头运行（cron、Telegram、无终端）将跳过提示。
- `--fix`（`--repair` 的别名）会将备份写入 `~/.openclaw/openclaw.json.bak`，并删除未知的配置键，同时列出每个删除项。
## macOS：`launchctl` 环境变量覆盖

104
docs/zh-CN/cli/gateway.md
View File

@@ -1,22 +1,22 @@
---
read_when:
- 从 CLI 运行 Gateway网关（开发或服务器环境）
- 调试 Gateway网关认证、绑定模式和连接问题
- 通过 Bonjour 发现 Gateway网关（局域网 + tailnet）
summary: OpenClaw Gateway网关 CLI（`openclaw gateway`）— 运行、查询和发现 Gateway网关
- 从 CLI 运行 Gateway 网关（开发或服务器）
- 调试 Gateway 网关认证、绑定模式和连接性
- 通过 Bonjour 发现 Gateway 网关（局域网 + tailnet）
summary: OpenClaw Gateway 网关 CLI（`openclaw gateway`）— 运行、查询和发现 Gateway 网关
title: gateway
x-i18n:
generated_at: "2026-02-01T19:59:19Z"
generated_at: "2026-02-03T07:45:15Z"
model: claude-opus-4-5
provider: pi
source_hash: 054dd48056e4784f153c6511c8eb35b56f239db8d4e629661841a00259e9abbf
source_path: cli/gateway.md
workflow: 14
workflow: 15
---
# Gateway网关 CLI
# Gateway 网关 CLI
Gateway网关是 OpenClaw 的 WebSocket 服务器（渠道、节点、会话、钩子）。
Gateway 网关是 OpenClaw 的 WebSocket 服务器（渠道、节点、会话、hooks）。
本页中的子命令位于 `openclaw gateway …` 下。
@@ -26,7 +26,9 @@ Gateway网关是 OpenClaw 的 WebSocket 服务器（渠道、节点、会话、
- [/gateway/discovery](/gateway/discovery)
- [/gateway/configuration](/gateway/configuration)
## 运行 Gateway网关运行本地 Gateway网关进程：
## 运行 Gateway 网关
运行本地 Gateway 网关进程：
```bash
openclaw gateway
@@ -40,10 +42,10 @@ openclaw gateway run
注意事项：
- 默认情况下，除非在 `~/.openclaw/openclaw.json` 中设置了 `gateway.mode=local`，否则 Gateway网关会拒绝启动。使用 `--allow-unconfigured` 进行临时/开发运行。
- 在没有认证的情况下绑定到 local loopback 以外的地址会被阻止（安全防护措施）。
- 授权后 `SIGUSR1` 会触发进程内重启（需启用 `commands.restart` 或使用 Gateway网关工具/配置应用/更新）。
- `SIGINT`/`SIGTERM` 处理程序会停止 Gateway网关进程，但不会恢复任何自定义终端状态。如果你使用 TUI 或原始模式输入包装 CLI，请在退出前恢复终端。
- 默认情况下，除非在 `~/.openclaw/openclaw.json` 中设置了 `gateway.mode=local`，否则 Gateway 网关将拒绝启动。使用 `--allow-unconfigured` 进行临时/开发运行。
- 在没有认证的情况下绑定到 loopback 之外的地址会被阻止（安全护栏）。
- `SIGUSR1` 在授权时触发进程内重启（启用 `commands.restart` 或使用 gateway 工具/config apply/update）。
- `SIGINT`/`SIGTERM` 处理程序会停止 Gateway 网关进程，但不会恢复任何自定义终端状态。如果你用 TUI 或 raw-mode 输入包装 CLI，请在退出前恢复终端。
### 选项
@@ -52,12 +54,12 @@ openclaw gateway run
- `--auth <token|password>`：认证模式覆盖。
- `--token <token>`：令牌覆盖（同时为进程设置 `OPENCLAW_GATEWAY_TOKEN`）。
- `--password <password>`：密码覆盖（同时为进程设置 `OPENCLAW_GATEWAY_PASSWORD`）。
- `--tailscale <off|serve|funnel>`：通过 Tailscale 暴露 Gateway网关。
- `--tailscale <off|serve|funnel>`：通过 Tailscale 暴露 Gateway 网关。
- `--tailscale-reset-on-exit`：关闭时重置 Tailscale serve/funnel 配置。
- `--allow-unconfigured`：允许在配置中没有 `gateway.mode=local` 的情况下启动 Gateway网关。
- `--dev`：如果缺失则创建开发配置和工作区（跳过 BOOTSTRAP.md）。
- `--reset`：重置开发配置 + 凭据 + 会话 + 工作区（需要 `--dev`）。
- `--force`：启动前终止所选端口上的现有监听器。
- `--allow-unconfigured`：允许在配置中没有 `gateway.mode=local` 的情况下启动 Gateway 网关。
- `--dev`：如果缺失则创建开发配置 + 工作区（跳过 BOOTSTRAP.md）。
- `--reset`：重置开发配置 + 凭证 + 会话 + 工作区（需要 `--dev`）。
- `--force`：启动前杀死所选端口上的任何现有监听器。
- `--verbose`：详细日志。
- `--claude-cli-logs`：仅在控制台显示 claude-cli 日志（并启用其 stdout/stderr）。
- `--ws-log <auto|full|compact>`：WebSocket 日志样式（默认 `auto`）。
@@ -65,20 +67,22 @@ openclaw gateway run
- `--raw-stream`：将原始模型流事件记录到 jsonl。
- `--raw-stream-path <path>`：原始流 jsonl 路径。
## 查询运行中的 Gateway网关所有查询命令使用 WebSocket RPC。
## 查询运行中的 Gateway 网关
所有查询命令使用 WebSocket RPC。
输出模式：
- 默认：人类可读（TTY 中带颜色）。
- `--json`：机器可读的 JSON（无样式/加载动画）。
- `--json`：机器可读 JSON（无样式/进度指示器）。
- `--no-color`（或 `NO_COLOR=1`）：禁用 ANSI 但保持人类可读布局。
共享选项（在支持的命令中）：
共享选项（在支持的地方）：
- `--url <url>`：Gateway网关 WebSocket URL。
- `--token <token>`：Gateway网关令牌。
- `--password <password>`：Gateway网关密码。
- `--timeout <ms>`：超时时间/预算（因命令而异）。
- `--url <url>`：Gateway 网关 WebSocket URL。
- `--token <token>`：Gateway 网关令牌。
- `--password <password>`：Gateway 网关密码。
- `--timeout <ms>`：超时/预算（因命令而异）。
- `--expect-final`：等待"最终"响应（智能体调用）。
### `gateway health`
@@ -89,7 +93,7 @@ openclaw gateway health --url ws://127.0.0.1:18789
### `gateway status`
`gateway status` 显示 Gateway网关服务（launchd/systemd/schtasks）以及可选的 RPC 探测。
`gateway status` 显示 Gateway 网关服务（launchd/systemd/schtasks）以及可选的 RPC 探测。
```bash
openclaw gateway status
@@ -101,27 +105,27 @@ openclaw gateway status --json
- `--url <url>`：覆盖探测 URL。
- `--token <token>`：探测的令牌认证。
- `--password <password>`：探测的密码认证。
- `--timeout <ms>`：探测超时时间（默认 `10000`）。
- `--no-probe`：跳过 RPC 探测（仅查看服务状态）。
- `--deep`：同时扫描系统级服务。
- `--timeout <ms>`：探测超时（默认 `10000`）。
- `--no-probe`：跳过 RPC 探测（仅服务视图）。
- `--deep`：也扫描系统级服务。
### `gateway probe`
`gateway probe` 是"全面调试"命令。它始终会探测：
`gateway probe` 是"调试一切"命令。它始终探测：
- 你配置的远程 Gateway网关（如已设置），以及
- localhost（local loopback），**即使已配置远程 Gateway网关**。
- 你配置的远程 Gateway 网关（如果设置了），以及
- localhost（loopback）**即使配置了远程也会探测**。
如果有多个 Gateway网关可达，它会全部输出。当你使用隔离的配置文件/端口时（例如救援机器人），支持多个 Gateway网关，但大多数安装仍然运行单个 Gateway网关。
如果多个 Gateway 网关可达，它会打印所有。当你使用隔离的配置文件/端口（例如救援机器人）时支持多个 Gateway 网关，但大多数安装仍然运行单个 Gateway 网关。
```bash
openclaw gateway probe
openclaw gateway probe --json
```
#### 通过 SSH 远程连接（Mac 应用对等模式）
#### 通过 SSH 远程（Mac 应用对等）
macOS 应用的"通过 SSH 远程连接"模式使用本地端口转发，使远程 Gateway网关（可能仅绑定到 local loopback）可通过 `ws://127.0.0.1:<port>` 访问。
macOS 应用的"通过 SSH 远程"模式使用本地端口转发，因此远程 Gateway 网关（可能仅绑定到 loopback）变得可以通过 `ws://127.0.0.1:<port>` 访问。
CLI 等效命令：
@@ -133,7 +137,7 @@ openclaw gateway probe --ssh user@gateway-host
- `--ssh <target>`：`user@host` 或 `user@host:port`（端口默认为 `22`）。
- `--ssh-identity <path>`：身份文件。
- `--ssh-auto`：自动选择第一个发现的 Gateway网关主机作为 SSH 目标（仅限局域网/WAB）。
- `--ssh-auto`：选择第一个发现的 Gateway 网关主机作为 SSH 目标（仅限局域网/WAB）。
配置（可选，用作默认值）：
@@ -142,14 +146,14 @@ openclaw gateway probe --ssh user@gateway-host
### `gateway call <method>`
底层 RPC 辅助工具。
低级 RPC 辅助工具。
```bash
openclaw gateway call status
openclaw gateway call logs.tail --params '{"sinceMs": 60000}'
```
## 管理 Gateway网关服务
## 管理 Gateway 网关服务
```bash
openclaw gateway install
@@ -162,26 +166,26 @@ openclaw gateway uninstall
注意事项：
- `gateway install` 支持 `--port`、`--runtime`、`--token`、`--force`、`--json`。
- 生命周期命令接受 `--json` 用于脚本编写。
- 生命周期命令接受 `--json` 用于脚本。
## 发现 Gateway网关（Bonjour）
## 发现 Gateway 网关（Bonjour）
`gateway discover` 扫描 Gateway网关信标（`_openclaw-gw._tcp`）。
`gateway discover` 扫描 Gateway 网关信标（`_openclaw-gw._tcp`）。
- 组播 DNS-SD：`local.`
- 单播 DNS-SD（广域 Bonjour）：选择一个域名（例如：`openclaw.internal.`）并设置分离 DNS + DNS 服务器；参见 [/gateway/bonjour](/gateway/bonjour)
- 单播 DNS-SD（广域 Bonjour）：选择一个域（示例：`openclaw.internal.`）并设置分割 DNS + DNS 服务器；参见 [/gateway/bonjour](/gateway/bonjour)
只有启用了 Bonjour 发现（默认启用）的 Gateway网关才会广播信标。
只有启用了 Bonjour 发现（默认）的 Gateway 网关才会广播信标。
广域发现记录包含（TXT）：
广域发现记录包括（TXT）：
- `role`（Gateway网关角色提示）
- `role`（Gateway 网关角色提示）
- `transport`（传输提示，例如 `gateway`）
- `gatewayPort`（WebSocket 端口，通常为 `18789`）
- `sshPort`（SSH 端口；如未指定默认为 `22`）
- `tailnetDns`（MagicDNS 主机名，如可用）
- `sshPort`（SSH 端口；如果不存在则默认为 `22`）
- `tailnetDns`（MagicDNS 主机名，如果可用）
- `gatewayTls` / `gatewayTlsSha256`（TLS 启用 + 证书指纹）
- `cliPath`（可选的远程安装路径提示）
- `cliPath`（远程安装的可选提示）
### `gateway discover`
@@ -191,8 +195,8 @@ openclaw gateway discover
选项：
- `--timeout <ms>`：每条命令的超时时间（浏览/解析）；默认 `2000`。
- `--json`：机器可读输出（同时禁用样式/加载动画）。
- `--timeout <ms>`：每个命令的超时（浏览/解析）；默认 `2000`。
- `--json`：机器可读输出（同时禁用样式/进度指示器）。
示例：

16
docs/zh-CN/cli/health.md
View File

@@ -1,20 +1,20 @@
---
read_when:
- 你想快速检查正在运行的 Gateway网关的健康状态
summary: "`openclaw health` 的 CLI 参考（通过 RPC 访问 Gateway网关健康端点）"
- 你想快速检查运行中的 Gateway 网关健康状态
summary: "`openclaw health` 的 CLI 参考（通过 RPC 获取 Gateway 网关健康端点）"
title: health
x-i18n:
generated_at: "2026-02-01T19:58:57Z"
generated_at: "2026-02-03T07:44:55Z"
model: claude-opus-4-5
provider: pi
source_hash: 82a78a5a97123f7a5736699ae8d793592a736f336c5caced9eba06d14d973fd7
source_path: cli/health.md
workflow: 14
workflow: 15
---
# `openclaw health`
从正在运行的 Gateway网关获取健康状态。
从运行中的 Gateway 网关获取健康状态。
```bash
openclaw health
@@ -22,7 +22,7 @@ openclaw health --json
openclaw health --verbose
```
说明：
注意：
- `--verbose` 会运行实时探测，并在配置了多个账号时打印每个账号的耗时。
- 配置了多个智能体时，输出中会包含每个智能体的会话存储信息。
- `--verbose` 运行实时探测，并在配置了多个账户时打印每个账户的耗时。
- 当配置了多个智能体时，输出包括每个智能体的会话存储。

45
docs/zh-CN/cli/hooks.md
View File

@@ -2,20 +2,20 @@
read_when:
- 你想管理智能体钩子
- 你想安装或更新钩子
summary: "`openclaw hooks` 的 CLI 参考（智能体钩子）"
summary: CLI 参考：`openclaw hooks`（智能体钩子）
title: hooks
x-i18n:
generated_at: "2026-02-01T19:59:18Z"
generated_at: "2026-02-03T10:04:32Z"
model: claude-opus-4-5
provider: pi
source_hash: e2032e61ff4b9135cb2708d92eb7889ac627b85a5fc153e3d5b84265f7bd7bc6
source_path: cli/hooks.md
workflow: 14
workflow: 15
---
# `openclaw hooks`
管理智能体钩子（用于 `/new`、`/reset` 等命令以及 Gateway网关启动的事件驱动自动化）。
管理智能体钩子（针对 `/new`、`/reset` 等命令以及 Gateway 网关启动的事件驱动自动化）。
相关内容：
@@ -28,13 +28,13 @@ x-i18n:
openclaw hooks list
```
列出从工作区、托管和内置目录中发现的所有钩子。
列出从工作区、托管目录和内置目录中发现的所有钩子。
**选项：**
- `--eligible`：仅显示符合条件的钩子（需求已满足）
- `--eligible`：仅显示符合条件的钩子（满足要求）
- `--json`：以 JSON 格式输出
- `-v, --verbose`：显示详细信息，包括缺失的需求
- `-v, --verbose`：显示详细信息，包括缺失的要求
**示例输出：**
@@ -54,7 +54,7 @@ Ready:
openclaw hooks list --verbose
```
显示不符合条件的钩子缺失的需求。
显示不符合条件的钩子缺失的要求。
**示例（JSON）：**
@@ -62,7 +62,7 @@ openclaw hooks list --verbose
openclaw hooks list --json
```
返回结构化 JSON 以供程序化使用。
返回结构化 JSON，供程序化使用。
## 获取钩子信息
@@ -110,7 +110,7 @@ Requirements:
openclaw hooks check
```
显示钩子资格状态摘要（就绪与未就绪的数量）。
显示钩子资格状态摘要（有多少已就绪，有多少未就绪）。
**选项：**
@@ -132,9 +132,10 @@ Not ready: 0
openclaw hooks enable <name>
```
通过将特定钩子添加到配置文件（`~/.openclaw/config.json`）来启用它。
通过将特定钩子添加到配置（`~/.openclaw/config.json`）来启用它。
**注意：** 由插件管理的钩子在 `openclaw hooks list` 中显示为 `plugin:<id>`，无法在此处启用/禁用。请改为启用/禁用对应的插件。
**注意：** 由插件管理的钩子在 `openclaw hooks list` 中显示 `plugin:<id>`，
无法在此处启用/禁用。请改为启用/禁用该插件。
**参数：**
@@ -160,7 +161,7 @@ openclaw hooks enable session-memory
**启用后：**
- 重启 Gateway网关以重新加载钩子（macOS 上重启菜单栏应用，或在开发环境中重启 Gateway网关进程）。
- 重启 Gateway 网关以重新加载钩子（macOS 上重启菜单栏应用，或在开发环境中重启 Gateway 网关进程）。
## 禁用钩子
@@ -188,7 +189,7 @@ openclaw hooks disable command-logger
**禁用后：**
- 重启 Gateway网关以重新加载钩子
- 重启 Gateway 网关以重新加载钩子
## 安装钩子
@@ -196,7 +197,7 @@ openclaw hooks disable command-logger
openclaw hooks install <path-or-spec>
```
从本地文件夹/归档包或 npm 安装钩子包。
从本地文件夹/压缩包或 npm 安装钩子包。
**执行操作：**
@@ -206,9 +207,9 @@ openclaw hooks install <path-or-spec>
**选项：**
- `-l, --link`：链接本地目录而非复制（将其添加到 `hooks.internal.load.extraDirs`）
- `-l, --link`：链接本地目录而不是复制（将其添加到 `hooks.internal.load.extraDirs`）
**支持的归档格式：** `.zip`、`.tgz`、`.tar.gz`、`.tar`
**支持的压缩包格式：** `.zip`、`.tgz`、`.tar.gz`、`.tar`
**示例：**
@@ -216,13 +217,13 @@ openclaw hooks install <path-or-spec>
# 本地目录
openclaw hooks install ./my-hook-pack
# 本地归档包
# 本地压缩包
openclaw hooks install ./my-hook-pack.zip
# NPM 包
openclaw hooks install @openclaw/my-hook-pack
# 链接本地目录而非复制
# 链接本地目录而不复制
openclaw hooks install -l ./my-hook-pack
```
@@ -238,7 +239,7 @@ openclaw hooks update --all
**选项：**
- `--all`：更新所有已跟踪的钩子包
- `--dry-run`：显示将要更改的内容而不实际写入
- `--dry-run`：显示将要进行的更改，但不写入
## 内置钩子
@@ -258,7 +259,7 @@ openclaw hooks enable session-memory
### command-logger
将所有命令事件记录到集中审计文件中。
将所有命令事件记录到集中的审计文件中。
**启用：**
@@ -297,7 +298,7 @@ openclaw hooks enable soul-evil
### boot-md
在 Gateway网关启动时（渠道启动之后）运行 `BOOT.md`。
在 Gateway 网关启动时（渠道启动后）运行 `BOOT.md`。
**事件**：`gateway:startup`

223
docs/zh-CN/cli/index.md
View File

@@ -1,21 +1,21 @@
---
read_when:
- 添加或修改 CLI 命令或选项
- 为新的命令界面编写文档
- 为新命令界面编写文档
summary: OpenClaw `openclaw` 命令、子命令和选项的 CLI 参考
title: CLI 参考
x-i18n:
generated_at: "2026-02-01T20:02:06Z"
generated_at: "2026-02-03T07:47:54Z"
model: claude-opus-4-5
provider: pi
source_hash: a73923763d7b89d4b183f569d543927ffbfd1f3e02f9e66639913f6daf226850
source_path: cli/index.md
workflow: 14
workflow: 15
---
# CLI 参考
本页描述当前的 CLI 行为。如果命令发生变更，请更新此文档。
本页描述当前的 CLI 行为。如果命令发生变化，请更新此文档。
## 命令页面
@@ -57,12 +57,12 @@ x-i18n:
- [`channels`](/cli/channels)
- [`security`](/cli/security)
- [`skills`](/cli/skills)
- [`voicecall`](/cli/voicecall)（插件；需已安装）
- [`voicecall`](/cli/voicecall)（插件；如已安装）
## 全局参数
## 全局标志
- `--dev`：将状态隔离到 `~/.openclaw-dev` 并偏移默认端口。
- `--profile <name>`：将状态隔离到 `~/.openclaw-<name>`。
- `--dev`：将状态隔离到 `~/.openclaw-dev` 下并调整默认端口。
- `--profile <name>`：将状态隔离到 `~/.openclaw-<name>` 下。
- `--no-color`：禁用 ANSI 颜色。
- `--update`：`openclaw update` 的简写（仅限源码安装）。
- `-V`、`--version`、`-v`：打印版本并退出。
@@ -70,25 +70,25 @@ x-i18n:
## 输出样式
- ANSI 颜色和进度指示器仅在 TTY 会话中渲染。
- OSC-8 超链接在支持的终端中显示为可点击链接；否则回退为纯 URL。
- `--json`（以及支持的 `--plain`）禁用样式以获得干净输出。
- `--no-color` 禁用 ANSI 样式；同样支持 `NO_COLOR=1`。
- 长时间运行的命令会显示进度指示器（支持时使用 OSC 9;4）。
- OSC-8 超链接在支持的终端中渲染为可点击链接；否则回退到纯 URL。
- `--json`（以及支持的地方使用 `--plain`）禁用样式以获得干净输出。
- `--no-color` 禁用 ANSI 样式；也支持 `NO_COLOR=1`。
- 长时间运行的命令显示进度指示器（支持时使用 OSC 9;4）。
## 配色方案
## 颜色调色板
OpenClaw 使用龙虾色配色方案作为 CLI 输出。
OpenClaw 在 CLI 输出中使用龙虾调色板。
- `accent`（#FF5A2D）：标题、标签、主要高亮。
- `accentBright`（#FF7A3D）：命令名称、强调。
- `accentDim`（#D14A22）：次要高亮文本。
- `info`（#FF8A5B）：信息值。
- `info`（#FF8A5B）：信息性值。
- `success`（#2FBF71）：成功状态。
- `warn`（#FFB020）：警告、回退、注意。
- `error`（#E23D2D）：错误、失败。
- `muted`（#8B7F77）：弱化、元数据。
配色方案的权威来源：`src/terminal/palette.ts`（即 "lobster seam"）。
调色板权威来源：`src/terminal/palette.ts`（又名"lobster seam"）。
## 命令树
@@ -244,13 +244,13 @@ openclaw [--dev] [--profile <name>] <command>
tui
```
注意：插件可以添加额外的顶层命令（例如 `openclaw voicecall`）。
注意：插件可以添加额外的顶级命令（例如 `openclaw voicecall`）。
## 安全
- `openclaw security audit` — 审计配置和本地状态中常见的安全隐患。
- `openclaw security audit --deep` — 尽力进行实时 Gateway网关探测。
- `openclaw security audit --fix` — 收紧安全默认设置并修改状态/配置文件权限。
- `openclaw security audit` — 审计配置 + 本地状态中常见的安全隐患。
- `openclaw security audit --deep` — 尽力进行实时 Gateway 网关探测。
- `openclaw security audit --fix` — 收紧安全默认值并 chmod 状态/配置。
## 插件
@@ -262,13 +262,13 @@ openclaw [--dev] [--profile <name>] <command>
- `openclaw plugins enable <id>` / `disable <id>` — 切换 `plugins.entries.<id>.enabled`。
- `openclaw plugins doctor` — 报告插件加载错误。
大多数插件变更需要重启 Gateway网关。参见 [/plugin](/plugin)。
大多数插件更改需要重启 Gateway 网关。参见 [/plugin](/plugin)。
## 记忆
对 `MEMORY.md` + `memory/*.md` 进行向量搜索：
- `openclaw memory status` — 显示索引统计信息。
- `openclaw memory status` — 显示索引统计。
- `openclaw memory index` — 重新索引记忆文件。
- `openclaw memory search "<query>"` — 对记忆进行语义搜索。
@@ -282,11 +282,11 @@ openclaw [--dev] [--profile <name>] <command>
- `/config` 用于持久化配置更改。
- `/debug` 用于仅运行时的配置覆盖（内存中，不写入磁盘；需要 `commands.debug: true`）。
## 设置与新手引导
## 设置 + 新手引导
### `setup`
初始化配置和工作区。
初始化配置 + 工作区。
选项：
@@ -294,19 +294,19 @@ openclaw [--dev] [--profile <name>] <command>
- `--wizard`：运行新手引导向导。
- `--non-interactive`：无提示运行向导。
- `--mode <local|remote>`：向导模式。
- `--remote-url <url>`：远程 Gateway网关 URL。
- `--remote-token <token>`：远程 Gateway网关令牌。
- `--remote-url <url>`：远程 Gateway 网关 URL。
- `--remote-token <token>`：远程 Gateway 网关令牌。
当存在任何向导参数（`--non-interactive`、`--mode`、`--remote-url`、`--remote-token`）时，向导会自动运行。
当存在任何向导标志（`--non-interactive`、`--mode`、`--remote-url`、`--remote-token`）时，向导自动运行。
### `onboard`
交互式向导，用于设置 Gateway网关、工作区和 Skills。
交互式向导，用于设置 Gateway 网关、工作区和 Skills。
选项：
- `--workspace <dir>`
- `--reset`（在向导运行前重置配置 + 凭证 + 会话 + 工作区）
- `--reset`（在向导之前重置配置 + 凭证 + 会话 + 工作区）
- `--non-interactive`
- `--mode <local|remote>`
- `--flow <quickstart|advanced|manual>`（manual 是 advanced 的别名）
@@ -341,56 +341,56 @@ openclaw [--dev] [--profile <name>] <command>
- `--skip-skills`
- `--skip-health`
- `--skip-ui`
- `--node-manager <npm|pnpm|bun>`（推荐 pnpm；不建议将 bun 用于 Gateway网关运行时）
- `--node-manager <npm|pnpm|bun>`（推荐 pnpm；不建议将 bun 用于 Gateway 网关运行时）
- `--json`
### `configure`
交互式配置向导（模型、渠道、Skills、Gateway网关）。
交互式配置向导（模型、渠道、Skills、Gateway 网关）。
### `config`
非交互式配置辅助工具（get/set/unset）。不带子命令运行 `openclaw config` 将启动向导。
非交互式配置辅助工具（get/set/unset）。不带子命令运行 `openclaw config` 会启动向导。
子命令：
- `config get <path>`：打印配置值（点号/方括号路径）。
- `config get <path>`：打印配置值（点/括号路径）。
- `config set <path> <value>`：设置值（JSON5 或原始字符串）。
- `config unset <path>`：移除值。
- `config unset <path>`：删除值。
### `doctor`
健康检查和快速修复（配置 + Gateway网关 + 旧版服务）。
健康检查 + 快速修复（配置 + Gateway 网关 + 旧版服务）。
选项：
- `--no-workspace-suggestions`：禁用工作区记忆提示。
- `--yes`：无需提示接受默认值（无头模式）。
- `--yes`：无提示接受默认值（无头模式）。
- `--non-interactive`：跳过提示；仅应用安全迁移。
- `--deep`：扫描系统服务以查找额外的 Gateway网关安装。
- `--deep`：扫描系统服务以查找额外的 Gateway 网关安装。
## 渠道辅助工具
### `channels`
管理聊天渠道账号（WhatsApp/Telegram/Discord/Google Chat/Slack/Mattermost（插件）/Signal/iMessage/MS Teams）。
管理聊天渠道账户（WhatsApp/Telegram/Discord/Google Chat/Slack/Mattermost（插件）/Signal/iMessage/MS Teams）。
子命令：
- `channels list`：显示已配置的渠道和认证配置。
- `channels status`：检查 Gateway网关可达性和渠道健康状态（`--probe` 运行额外检查；使用 `openclaw health` 或 `openclaw status --deep` 进行 Gateway网关健康探测）。
- 提示：`channels status` 在检测到常见配置错误时会打印警告并提供修复建议（然后引导你使用 `openclaw doctor`）。
- `channels logs`：显示来自 Gateway网关日志文件的最近渠道日志。
- `channels add`：不传参数时以向导模式设置；传入参数则切换为非交互模式。
- `channels remove`：默认仅禁用；传入 `--delete` 可无提示删除配置条目。
- `channels list`：显示已配置的渠道和认证配置文件。
- `channels status`：检查 Gateway 网关可达性和渠道健康状况（`--probe` 运行额外检查；使用 `openclaw health` 或 `openclaw status --deep` 进行 Gateway 网关健康探测）。
- 提示：`channels status` 在检测到常见配置错误时会打印带有建议修复的警告（然后指向 `openclaw doctor`）。
- `channels logs`：显示 Gateway 网关日志文件中最近的渠道日志。
- `channels add`：不传标志时使用向导式设置；标志切换到非交互模式。
- `channels remove`：默认禁用；传 `--delete` 可无提示删除配置条目。
- `channels login`：交互式渠道登录（仅限 WhatsApp Web）。
- `channels logout`：登出渠道会话（如果支持）。
- `channels logout`：登出渠道会话（如支持）。
通用选项：
- `--channel <name>`：`whatsapp|telegram|discord|googlechat|slack|mattermost|signal|imessage|msteams`
- `--account <id>`：渠道账号 ID（默认 `default`）
- `--name <label>`：账号的显示名称
- `--account <id>`：渠道账户 id（默认 `default`）
- `--name <label>`：账户的显示名称
`channels login` 选项：
@@ -406,7 +406,7 @@ openclaw [--dev] [--profile <name>] <command>
`channels list` 选项：
- `--no-usage`：跳过模型提供商用量/配额快照（仅限 OAuth/API 支持的）。
- `--json`：输出 JSON（除非设置了 `--no-usage`，否则包含用量信息）。
- `--json`：输出 JSON（除非设置 `--no-usage`，否则包含用量）。
`channels logs` 选项：
@@ -428,25 +428,25 @@ openclaw status --deep
### `skills`
列出和检查可用 Skills 及就绪信息。
列出和检查可用的 Skills 及就绪信息。
子命令：
- `skills list`：列出 Skills（无子命令时的默认行为）。
- `skills info <name>`：显示某个 Skills 的详情。
- `skills info <name>`：显示单个 Skill 的详情。
- `skills check`：就绪与缺失需求的摘要。
选项：
- `--eligible`：仅显示就绪的 Skills。
- `--json`：输出 JSON（无样式）。
- `-v`、`--verbose`：包含缺失需求的详情。
- `-v`、`--verbose`：包含缺失需求详情。
提示：使用 `npx clawhub` 搜索、安装和同步 Skills。
### `pairing`
跨渠道审批私聊配对请求。
批准跨渠道的私信配对请求。
子命令：
@@ -455,12 +455,12 @@ openclaw status --deep
### `webhooks gmail`
Gmail Pub/Sub 钩子设置与运行。参见 [/automation/gmail-pubsub](/automation/gmail-pubsub)。
Gmail Pub/Sub 钩子设置 + 运行器。参见 [/automation/gmail-pubsub](/automation/gmail-pubsub)。
子命令：
- `webhooks gmail setup`（需要 `--account <email>`；支持 `--project`、`--topic`、`--subscription`、`--label`、`--hook-url`、`--hook-token`、`--push-token`、`--bind`、`--port`、`--path`、`--include-body`、`--max-bytes`、`--renew-minutes`、`--tailscale`、`--tailscale-path`、`--tailscale-target`、`--push-endpoint`、`--json`）
- `webhooks gmail run`（相同参数的运行时覆盖）
- `webhooks gmail run`（相同标志的运行时覆盖）
### `dns setup`
@@ -470,11 +470,11 @@ Gmail Pub/Sub 钩子设置与运行。参见 [/automation/gmail-pubsub](/automat
- `--apply`：安装/更新 CoreDNS 配置（需要 sudo；仅限 macOS）。
## 消息与智能体
## 消息 + 智能体
### `message`
统一的出站消息和渠道操作。
统一的出站消息 + 渠道操作。
参见：[/cli/message](/cli/message)
@@ -497,7 +497,7 @@ Gmail Pub/Sub 钩子设置与运行。参见 [/automation/gmail-pubsub](/automat
### `agent`
通过 Gateway网关（或 `--local` 嵌入模式）运行一个智能体回合。
通过 Gateway 网关运行一个智能体回合（或使用 `--local` 嵌入式运行）。
必需：
@@ -505,7 +505,7 @@ Gmail Pub/Sub 钩子设置与运行。参见 [/automation/gmail-pubsub](/automat
选项：
- `--to <dest>`（用于会话键和可选的投递）
- `--to <dest>`（用于会话键和可选发送）
- `--session-id <id>`
- `--thinking <off|minimal|low|medium|high|xhigh>`（仅限 GPT-5.2 + Codex 模型）
- `--verbose <on|full|off>`
@@ -530,7 +530,7 @@ Gmail Pub/Sub 钩子设置与运行。参见 [/automation/gmail-pubsub](/automat
#### `agents add [name]`
添加新的隔离智能体。除非传入参数（或 `--non-interactive`），否则运行引导向导；非交互模式下 `--workspace` 为必需。
添加新的隔离智能体。除非传入标志（或 `--non-interactive`），否则运行引导向导；非交互模式下 `--workspace` 是必需的。
选项：
@@ -541,11 +541,11 @@ Gmail Pub/Sub 钩子设置与运行。参见 [/automation/gmail-pubsub](/automat
- `--non-interactive`
- `--json`
绑定规格使用 `channel[:accountId]`。当 WhatsApp 省略 `accountId` 时，使用默认账号 ID。
绑定规范使用 `channel[:accountId]`。对于 WhatsApp，省略 `accountId` 时使用默认账户 id。
#### `agents delete <id>`
删除智能体并清理其工作区和状态。
删除智能体并清理其工作区 + 状态。
选项：
@@ -554,13 +554,13 @@ Gmail Pub/Sub 钩子设置与运行。参见 [/automation/gmail-pubsub](/automat
### `acp`
运行将 IDE 连接到 Gateway网关的 ACP 桥接。
运行连接 IDE 到 Gateway 网关的 ACP 桥接。
参见 [`acp`](/cli/acp) 获取完整选项和示例。
完整选项和示例参见 [`acp`](/cli/acp)。
### `status`
显示已关联会话的健康状态和最近的接收者。
显示关联会话健康状况和最近的收件人。
选项：
@@ -574,28 +574,28 @@ Gmail Pub/Sub 钩子设置与运行。参见 [/automation/gmail-pubsub](/automat
说明：
- 概览在可用时包含 Gateway网关 + 节点主机服务状态。
- 概览包含 Gateway 网关 + 节点主机服务状态（如可用）。
### 用量追踪
### 用量跟踪
当 OAuth/API 凭证可用时，OpenClaw 可以展示提供商的用量/配额信息。
当 OAuth/API 凭证可用时，OpenClaw 可以显示提供商用量/配额。
展示位置：
显示位置：
- `/status`（可用时添加简短的提供商用量行）
- `openclaw status --usage`（打印完整的提供商用量明细）
- macOS 菜单栏（Context 下的用量部分）
- `openclaw status --usage`（打印完整的提供商明细）
- macOS 菜单栏（上下文下的用量部分）
说明：
- 数据直接来自提供商的用量端点（非估算值）。
- 提供商：Anthropic、GitHub Copilot、OpenAI Codex OAuth，以及启用相应提供商插件时的 Gemini CLI/Antigravity。
- 如果没有匹配的凭证，用量信息将被隐藏。
- 详情：参见 [用量追踪](/concepts/usage-tracking)。
- 数据直接来自提供商用量端点（非估算）。
- 提供商：Anthropic、GitHub Copilot、OpenAI Codex OAuth，以及启用这些提供商插件时的 Gemini CLI/Antigravity。
- 如果没有匹配的凭证，用量会被隐藏。
- 详情：参见[用量跟踪](/concepts/usage-tracking)。
### `health`
从运行中的 Gateway网关获取健康状态。
从运行中的 Gateway 网关获取健康状态。
选项：
@@ -605,7 +605,7 @@ Gmail Pub/Sub 钩子设置与运行。参见 [/automation/gmail-pubsub](/automat
### `sessions`
列出已存储的对话会话。
列出存储的对话会话。
选项：
@@ -629,11 +629,11 @@ Gmail Pub/Sub 钩子设置与运行。参见 [/automation/gmail-pubsub](/automat
说明：
- `--non-interactive` 需要同时指定 `--scope` 和 `--yes`。
- `--non-interactive` 需要 `--scope` 和 `--yes`。
### `uninstall`
卸载 Gateway网关服务和本地数据（CLI 保留）。
卸载 Gateway 网关服务 + 本地数据（CLI 保留）。
选项：
@@ -650,11 +650,11 @@ Gmail Pub/Sub 钩子设置与运行。参见 [/automation/gmail-pubsub](/automat
- `--non-interactive` 需要 `--yes` 和明确的范围（或 `--all`）。
## Gateway网关
## Gateway 网关
### `gateway`
运行 WebSocket Gateway网关。
运行 WebSocket Gateway 网关。
选项：
@@ -667,7 +667,7 @@ Gmail Pub/Sub 钩子设置与运行。参见 [/automation/gmail-pubsub](/automat
- `--tailscale-reset-on-exit`
- `--allow-unconfigured`
- `--dev`
- `--reset`（重置开发配置 + 凭证 + 会话 + 工作区）
- `--reset`（重置 dev 配置 + 凭证 + 会话 + 工作区）
- `--force`（终止端口上的现有监听器）
- `--verbose`
- `--claude-cli-logs`
@@ -678,11 +678,11 @@ Gmail Pub/Sub 钩子设置与运行。参见 [/automation/gmail-pubsub](/automat
### `gateway service`
管理 Gateway网关服务（launchd/systemd/schtasks）。
管理 Gateway 网关服务（launchd/systemd/schtasks）。
子命令：
- `gateway status`（默认探测 Gateway网关 RPC）
- `gateway status`（默认探测 Gateway 网关 RPC）
- `gateway install`（服务安装）
- `gateway uninstall`
- `gateway start`
@@ -691,21 +691,21 @@ Gmail Pub/Sub 钩子设置与运行。参见 [/automation/gmail-pubsub](/automat
说明：
- `gateway status` 默认使用服务解析的端口/配置探测 Gateway网关 RPC（可通过 `--url/--token/--password` 覆盖）。
- `gateway status` 支持 `--no-probe`、`--deep` 和 `--json` 用于脚本编写。
- `gateway status` 还会在检测到旧版或额外的 Gateway网关服务时展示（`--deep` 添加系统级扫描）。以配置文件命名的 OpenClaw 服务被视为正式服务，不会被标记为"额外"。
- `gateway status` 会打印 CLI 使用的配置路径与服务可能使用的配置（服务环境变量），以及解析后的探测目标 URL。
- `gateway install|uninstall|start|stop|restart` 支持 `--json` 用于脚本编写（默认输出保持人类可读）。
- `gateway install` 默认使用 Node 运行时；**不建议**使用 bun（WhatsApp/Telegram 存在 bug）。
- `gateway status` 默认使用服务解析的端口/配置探测 Gateway 网关 RPC（使用 `--url/--token/--password` 覆盖）。
- `gateway status` 支持 `--no-probe`、`--deep` 和 `--json` 用于脚本化。
- `gateway status` 在检测到旧版或额外的 Gateway 网关服务时也会显示（`--deep` 添加系统级扫描）。配置文件命名的 OpenClaw 服务被视为一等公民，不会被标记为"额外"。
- `gateway status` 打印 CLI 使用的配置路径与服务可能使用的配置（服务环境），以及解析的探测目标 URL。
- `gateway install|uninstall|start|stop|restart` 支持 `--json` 用于脚本化（默认输出保持人类友好）。
- `gateway install` 默认使用 Node 运行时；**不建议**使用 bun（WhatsApp/Telegram bug）。
- `gateway install` 选项：`--port`、`--runtime`、`--token`、`--force`、`--json`。
### `logs`
通过 RPC 追踪 Gateway网关文件日志。
通过 RPC 跟踪 Gateway 网关文件日志。
说明：
- TTY 会话渲染彩色结构化视图；非 TTY 回退为纯文本。
- TTY 会话渲染彩色、结构化视图；非 TTY 回退到纯文本。
- `--json` 输出行分隔的 JSON（每行一个日志事件）。
示例：
@@ -720,7 +720,7 @@ openclaw logs --no-color
### `gateway <subcommand>`
Gateway网关 CLI 辅助工具（RPC 子命令使用 `--url`、`--token`、`--password`、`--timeout`、`--expect-final`）。
Gateway 网关 CLI 辅助工具（RPC 子命令使用 `--url`、`--token`、`--password`、`--timeout`、`--expect-final`）。
子命令：
@@ -732,7 +732,7 @@ Gateway网关 CLI 辅助工具（RPC 子命令使用 `--url`、`--token`、`--pa
- `gateway install|uninstall|start|stop|restart`
- `gateway run`
常用 RPC：
常见 RPC：
- `config.apply`（验证 + 写入配置 + 重启 + 唤醒）
- `config.patch`（合并部分更新 + 重启 + 唤醒）
@@ -742,9 +742,9 @@ Gateway网关 CLI 辅助工具（RPC 子命令使用 `--url`、`--token`、`--pa
## 模型
参见 [/concepts/models](/concepts/models) 了解回退行为和扫描策略。
回退行为和扫描策略参见 [/concepts/models](/concepts/models)。
推荐的 Anthropic 认证方式（setup-token）：
首选 Anthropic 认证（setup-token）：
```bash
claude setup-token
@@ -777,16 +777,15 @@ openclaw models status
- `--json`
- `--plain`
- `--check`（退出码 1=已过期/缺失，2=即将过期）
- `--probe`（对已配置的认证配置进行实时探测）
- `--check`（退出码 1=过期/缺失，2=即将过期）
- `--probe`（对已配置认证配置文件进行实时探测）
- `--probe-provider <name>`
- `--probe-profile <id>`（可重复或逗号分隔）
- `--probe-profile <id>`（重复或逗号分隔）
- `--probe-timeout <ms>`
- `--probe-concurrency <n>`
- `--probe-max-tokens <n>`
始终包含认证概览和认证存储中配置的 OAuth 过期状态。
`--probe` 运行实时请求（可能消耗令牌并触发速率限制）。
始终包含认证概览和认证存储中配置文件的 OAuth 过期状态。`--probe` 运行实时请求（可能消耗令牌并触发速率限制）。
### `models set <model>`
@@ -859,7 +858,7 @@ openclaw models status
### `system event`
入队系统事件并可选触发心跳（Gateway网关 RPC）。
将系统事件加入队列并可选触发心跳（Gateway 网关 RPC）。
必需：
@@ -873,7 +872,7 @@ openclaw models status
### `system heartbeat last|enable|disable`
心跳控制（Gateway网关 RPC）。
心跳控制（Gateway 网关 RPC）。
选项：
@@ -882,7 +881,7 @@ openclaw models status
### `system presence`
列出系统存在条目（Gateway网关 RPC）。
列出系统存在条目（Gateway 网关 RPC）。
选项：
@@ -891,14 +890,14 @@ openclaw models status
## 定时任务
管理调度作业（Gateway网关 RPC）。参见 [/automation/cron-jobs](/automation/cron-jobs)。
管理计划任务（Gateway 网关 RPC）。参见 [/automation/cron-jobs](/automation/cron-jobs)。
子命令：
- `cron status [--json]`
- `cron list [--all] [--json]`（默认表格输出；使用 `--json` 获取原始数据）
- `cron add`（别名：`create`；需要 `--name` 和 `--at` | `--every` | `--cron` 三选一，以及 `--system-event` | `--message` 二选一的负载）
- `cron edit <id>`（修补字段）
- `cron add`（别名：`create`；需要 `--name` 和 `--at` | `--every` | `--cron` 三选一，以及 `--system-event` | `--message` 负载二选一）
- `cron edit <id>`（补丁字段）
- `cron rm <id>`（别名：`remove`、`delete`）
- `cron enable <id>`
- `cron disable <id>`
@@ -922,7 +921,7 @@ openclaw models status
## 节点
`nodes` 与 Gateway网关通信并操作已配对的节点。参见 [/nodes](/nodes)。
`nodes` 与 Gateway 网关通信并针对已配对的节点。参见 [/nodes](/nodes)。
通用选项：
@@ -938,16 +937,16 @@ openclaw models status
- `nodes reject <requestId>`
- `nodes rename --node <id|name|ip> --name <displayName>`
- `nodes invoke --node <id|name|ip> --command <command> [--params <json>] [--invoke-timeout <ms>] [--idempotency-key <key>]`
- `nodes run --node <id|name|ip> [--cwd <path>] [--env KEY=VAL] [--command-timeout <ms>] [--needs-screen-recording] [--invoke-timeout <ms>] <command...>`（Mac 节点或无头节点主机）
- `nodes notify --node <id|name|ip> [--title <text>] [--body <text>] [--sound <name>] [--priority <passive|active|timeSensitive>] [--delivery <system|overlay|auto>] [--invoke-timeout <ms>]`（仅限 Mac）
- `nodes run --node <id|name|ip> [--cwd <path>] [--env KEY=VAL] [--command-timeout <ms>] [--needs-screen-recording] [--invoke-timeout <ms>] <command...>`（mac 节点或无头节点主机）
- `nodes notify --node <id|name|ip> [--title <text>] [--body <text>] [--sound <name>] [--priority <passive|active|timeSensitive>] [--delivery <system|overlay|auto>] [--invoke-timeout <ms>]`（仅限 mac）
摄像头：
相机：
- `nodes camera list --node <id|name|ip>`
- `nodes camera snap --node <id|name|ip> [--facing front|back|both] [--device-id <id>] [--max-width <px>] [--quality <0-1>] [--delay-ms <ms>] [--invoke-timeout <ms>]`
- `nodes camera clip --node <id|name|ip> [--facing front|back] [--device-id <id>] [--duration <ms|10s|1m>] [--no-audio] [--invoke-timeout <ms>]`
画布与屏幕：
画布 + 屏幕：
- `nodes canvas snapshot --node <id|name|ip> [--format png|jpg|jpeg] [--max-width <px>] [--quality <0-1>] [--invoke-timeout <ms>]`
- `nodes canvas present --node <id|name|ip> [--target <urlOrPath>] [--x <px>] [--y <px>] [--width <px>] [--height <px>] [--invoke-timeout <ms>]`
@@ -1018,7 +1017,7 @@ openclaw models status
### `tui`
打开连接到 Gateway网关的终端 UI。
打开连接到 Gateway 网关的终端 UI。
选项：

12
docs/zh-CN/cli/logs.md
View File

@@ -1,21 +1,21 @@
---
read_when:
- 需要远程查看 Gateway网关日志（无需 SSH）
- 需要 JSON 格式的日志行以供工具使用
summary: 通过 RPC 查看 Gateway网关日志的 `openclaw logs` CLI 参考
- 你需要远程跟踪 Gateway 网关日志（无需 SSH）
- 你需要 JSON 日志行用于工具处理
summary: "`openclaw logs` 的 CLI 参考（通过 RPC 跟踪 Gateway 网关日志）"
title: logs
x-i18n:
generated_at: "2026-02-01T20:21:08Z"
generated_at: "2026-02-03T07:44:57Z"
model: claude-opus-4-5
provider: pi
source_hash: 911a57f0f3b78412c26312f7bf87a5a26418ab7b74e5e2eb40f16edefb6c6b8e
source_path: cli/logs.md
workflow: 14
workflow: 15
---
# `openclaw logs`
通过 RPC 实时查看 Gateway网关文件日志（支持远程模式）。
通过 RPC 跟踪 Gateway 网关文件日志（在远程模式下可用）。
相关内容：

52
docs/zh-CN/cli/node.md
View File

@@ -2,37 +2,37 @@
read_when:
- 运行无头节点主机
- 为 system.run 配对非 macOS 节点
summary: "`openclaw node`（无头节点主机）的 CLI 参考"
summary: "`openclaw node` 的 CLI 参考（无头节点主机）"
title: node
x-i18n:
generated_at: "2026-02-01T20:21:18Z"
generated_at: "2026-02-03T07:45:07Z"
model: claude-opus-4-5
provider: pi
source_hash: a8b1a57712663e2285c9ecd306fe57d067eb3e6820d7d8aec650b41b022d995a
source_path: cli/node.md
workflow: 14
workflow: 15
---
# `openclaw node`
运行一个**无头节点主机**，连接到 Gateway网关 WebSocket 并在本机上暴露
运行一个**无头节点主机**，连接到 Gateway 网关 WebSocket 并在此机器上暴露
`system.run` / `system.which`。
## 为什么使用节点主机？
当你希望智能体**在网络中的其他机器上运行命令**，而无需在那些机器上安装完整的 macOS 伴侣应用时，可以使用节点主机。
当你希望智能体**在网络中的其他机器上运行命令**，而无需在那里安装完整的 macOS 配套应用时，请使用节点主机。
常见用例：
- 在远程 Linux/Windows 机器上运行命令（构建服务器、实验室机器、NAS）。
- 在 Gateway网关上保持执行**沙箱隔离**，但将已批准的运行委派给其他主机。
- 在 Gateway 网关上保持执行的**沙箱隔离**，但将批准的运行委托给其他主机。
- 为自动化或 CI 节点提供轻量级、无头的执行目标。
执行仍受**执行审批**和节点主机上的按智能体白名单保护，因此你可以保持命令访问的范围明确可控。
执行仍然受**执行批准**和节点主机上的每智能体允许列表保护，因此你可以保持命令访问的范围明确。
## 浏览器代理（零配置）
如果节点上的 `browser.enabled` 未被禁用，节点主机会自动通告浏览器代理。这使智能体无需额外配置即可在该节点上使用浏览器自动化。
如果节点上的 `browser.enabled` 未被禁用，节点主机会自动广播浏览器代理。这让智能体无需额外配置即可在该节点上使用浏览器自动化。
如需在节点上禁用：
@@ -46,7 +46,7 @@ x-i18n:
}
```
## 前台运行
## 运行（前台）
```bash
openclaw node run --host <gateway-host> --port 18789
@@ -54,14 +54,14 @@ openclaw node run --host <gateway-host> --port 18789
选项：
- `--host <host>`：Gateway网关 WebSocket 主机（默认：`127.0.0.1`）
- `--port <port>`：Gateway网关 WebSocket 端口（默认：`18789`）
- `--tls`：为 Gateway网关连接使用 TLS
- `--host <host>`：Gateway 网关 WebSocket 主机（默认：`127.0.0.1`）
- `--port <port>`：Gateway 网关 WebSocket 端口（默认：`18789`）
- `--tls`：为 Gateway 网关连接使用 TLS
- `--tls-fingerprint <sha256>`：预期的 TLS 证书指纹（sha256）
- `--node-id <id>`：覆盖节点 ID（清除配对令牌）
- `--node-id <id>`：覆盖节点 id（清除配对 token）
- `--display-name <name>`：覆盖节点显示名称
## 服务（后台运行）
## 服务（后台）
将无头节点主机安装为用户服务。
@@ -71,11 +71,11 @@ openclaw node install --host <gateway-host> --port 18789
选项：
- `--host <host>`：Gateway网关 WebSocket 主机（默认：`127.0.0.1`）
- `--port <port>`：Gateway网关 WebSocket 端口（默认：`18789`）
- `--tls`：为 Gateway网关连接使用 TLS
- `--host <host>`：Gateway 网关 WebSocket 主机（默认：`127.0.0.1`）
- `--port <port>`：Gateway 网关 WebSocket 端口（默认：`18789`）
- `--tls`：为 Gateway 网关连接使用 TLS
- `--tls-fingerprint <sha256>`：预期的 TLS 证书指纹（sha256）
- `--node-id <id>`：覆盖节点 ID（清除配对令牌）
- `--node-id <id>`：覆盖节点 id（清除配对 token）
- `--display-name <name>`：覆盖节点显示名称
- `--runtime <runtime>`：服务运行时（`node` 或 `bun`）
- `--force`：如果已安装则重新安装/覆盖
@@ -89,13 +89,13 @@ openclaw node restart
openclaw node uninstall
```
使用 `openclaw node run` 进行前台节点主机运行（无服务）。
使用 `openclaw node run` 运行前台节点主机（无服务）。
服务命令支持 `--json` 以获取机器可读输出。
服务命令接受 `--json` 以获取机器可读输出。
## 配对
首次连接会在 Gateway网关上创建一个待处理的节点配对请求。
首次连接会在 Gateway 网关上创建待处理的节点配对请求。
通过以下方式批准：
```bash
@@ -103,13 +103,13 @@ openclaw nodes pending
openclaw nodes approve <requestId>
```
节点主机将其节点 ID、令牌、显示名称和 Gateway网关连接信息存储在
节点主机将其节点 id、token、显示名称和 Gateway 网关连接信息存储在
`~/.openclaw/node.json` 中。
## 执行审批
## 执行批准
`system.run` 受本地执行审批控制：
`system.run` 受本地执行批准限制：
- `~/.openclaw/exec-approvals.json`
- [执行审批](/tools/exec-approvals)
- `openclaw approvals --node <id|name|ip>`（从 Gateway网关编辑）
- [执行批准](/tools/exec-approvals)
- `openclaw approvals --node <id|name|ip>`（从 Gateway 网关编辑）

39
docs/zh-CN/cli/nodes.md
View File

@@ -1,21 +1,21 @@
---
read_when:
- 正在管理配对节点（摄像头、屏幕、画布）
- 需要批准请求或调用节点命令
summary: 管理配对节点（列表/状态/批准/调用，摄像头/画布/屏幕）的 `openclaw nodes` CLI 参考
- 你正在管理已配对的节点（摄像头、屏幕、画布）
- 你需要批准请求或调用节点命令
summary: "`openclaw nodes` 的 CLI 参考（列表/状态/批准/调用，摄像头/画布/屏幕）"
title: nodes
x-i18n:
generated_at: "2026-02-01T20:21:19Z"
generated_at: "2026-02-03T10:04:26Z"
model: claude-opus-4-5
provider: pi
source_hash: 23da6efdd659a82dbbc4afd18eb4ab1020a2892f69c28d610f912c8a799f734c
source_path: cli/nodes.md
workflow: 14
workflow: 15
---
# `openclaw nodes`
管理配对节点（设备）并调用节点功能。
管理已配对的节点（设备）并调用节点功能。
相关内容：
@@ -23,7 +23,7 @@ x-i18n:
- 摄像头：[摄像头节点](/nodes/camera)
- 图像：[图像节点](/nodes/images)
常用选项：
通用选项：
- `--url`、`--token`、`--timeout`、`--json`
@@ -40,8 +40,9 @@ openclaw nodes status --connected
openclaw nodes status --last-connected 24h
```
`nodes list` 输出待处理/已配对的表格。已配对的行包含最近一次连接的时间间隔（Last Connect）。
使用 `--connected` 仅显示当前已连接的节点。使用 `--last-connected <duration>` 筛选在指定时间段内连接过的节点（例如 `24h`、`7d`）。
`nodes list` 打印待处理/已配对表格。已配对行包含最近连接时长（Last Connect）。
使用 `--connected` 仅显示当前已连接的节点。使用 `--last-connected <duration>`
筛选在指定时间段内连接过的节点（例如 `24h`、`7d`）。
## 调用 / 运行
@@ -55,24 +56,24 @@ openclaw nodes run --agent main --node <id|name|ip> --raw "git status"
调用标志：
- `--params <json>`：JSON 对象字符串（默认 `{}`）。
- `--invoke-timeout <ms>`：节点调用超时时间（默认 `15000`）。
- `--invoke-timeout <ms>`：节点调用超时（默认 `15000`）。
- `--idempotency-key <key>`：可选的幂等键。
### Exec 风格的默认行为
### Exec 风格默认值
`nodes run` 模拟模型的 exec 行为（默认值 + 审批）：
`nodes run` 与模型的 exec 行为一致（默认值 + 审批）：
- 读取 `tools.exec.*`（以及 `agents.list[].tools.exec.*` 的覆盖配置）。
- 在调用 `system.run` 之前使用 exec 审批（`exec.approval.request`）。
- 当设置了 `tools.exec.node` 时，可以省略 `--node`。
- 需要一个声明支持 `system.run` 的节点（macOS 伴侣应用或无头节点主机）。
- 读取 `tools.exec.*`（以及 `agents.list[].tools.exec.*` 覆盖）。
- 在调用 `system.run` 前使用 exec 审批（`exec.approval.request`）。
- 当设置了 `tools.exec.node` 时可省略 `--node`。
- 需要支持 `system.run` 的节点（macOS 配套应用或无头节点主机）。
标志：
- `--cwd <path>`：工作目录。
- `--env <key=val>`：环境变量覆盖（可重复使用）。
- `--command-timeout <ms>`：命令超时时间。
- `--invoke-timeout <ms>`：节点调用超时时间（默认 `30000`）。
- `--env <key=val>`：环境变量覆盖（可重复）。
- `--command-timeout <ms>`：命令超时。
- `--invoke-timeout <ms>`：节点调用超时（默认 `30000`）。
- `--needs-screen-recording`：要求屏幕录制权限。
- `--raw <command>`：运行 shell 字符串（`/bin/sh -lc` 或 `cmd.exe /c`）。
- `--agent <id>`：智能体范围的审批/白名单（默认为已配置的智能体）。

14
docs/zh-CN/cli/onboard.md
View File

@@ -1,20 +1,20 @@
---
read_when:
- 你想要通过引导式设置配置 Gateway网关、工作区、认证、渠道和 Skills
summary: "`openclaw onboard`（交互式新手引导向导）的 CLI 参考"
- 你想要 Gateway 网关、工作区、认证、渠道和 Skills 的引导式设置
summary: "`openclaw onboard` 的 CLI 参考（交互式新手引导向导）"
title: onboard
x-i18n:
generated_at: "2026-02-01T20:21:15Z"
generated_at: "2026-02-03T07:45:00Z"
model: claude-opus-4-5
provider: pi
source_hash: a661049a6983233986a880a68440a3bcc6869ee2c4c6f5e9f3ab8ff973e22f60
source_path: cli/onboard.md
workflow: 14
workflow: 15
---
# `openclaw onboard`
交互式新手引导向导（本地或远程 Gateway网关设置）。
交互式新手引导向导（本地或远程 Gateway 网关设置）。
相关内容：
@@ -31,6 +31,6 @@ openclaw onboard --mode remote --remote-url ws://gateway-host:18789
流程说明：
- `quickstart`：最少提示，自动生成 Gateway网关令牌。
- `quickstart`：最少提示，自动生成 Gateway 网关令牌。
- `manual`：完整的端口/绑定/认证提示（`advanced` 的别名）。
- 最快开始聊天的方式：`openclaw dashboard`（控制台 UI，无需渠道设置）。
- 最快开始聊天：`openclaw dashboard`（控制 UI，无需渠道设置）。

8
docs/zh-CN/cli/pairing.md
View File

@@ -1,15 +1,15 @@
---
read_when:
- 你正在使用配对模式的私信功能，需要批准发送者
summary: "`openclaw pairing`（批准/列出配对请求）的 CLI 参考"
- 你正在使用配对模式私信并需要批准发送者
summary: "`openclaw pairing` 的 CLI 参考（批准/列出配对请求）"
title: pairing
x-i18n:
generated_at: "2026-02-01T20:21:19Z"
generated_at: "2026-02-03T07:45:02Z"
model: claude-opus-4-5
provider: pi
source_hash: e0bc9707294463c95d13e0deb67d834cfad6a105ab44baf4c25592e5de65ddf5
source_path: cli/pairing.md
workflow: 14
workflow: 15
---
# `openclaw pairing`

20
docs/zh-CN/cli/plugins.md
View File

@@ -1,26 +1,26 @@
---
read_when:
- 你想安装或管理进程内 Gateway网关插件
- 你想安装或管理进程内 Gateway 网关插件
- 你想调试插件加载失败问题
summary: "`openclaw plugins` 的 CLI 参考（list、install、enable/disable、doctor）"
summary: "`openclaw plugins` 的 CLI 参考（列出、安装、启用/禁用、诊断）"
title: plugins
x-i18n:
generated_at: "2026-02-01T20:21:23Z"
generated_at: "2026-02-03T07:45:08Z"
model: claude-opus-4-5
provider: pi
source_hash: c6bf76b1e766b912ec30a0101d455151c88f1a778bffa121cdd1d0b4fbe73e1c
source_path: cli/plugins.md
workflow: 14
workflow: 15
---
# `openclaw plugins`
管理 Gateway网关插件/扩展（进程内加载）。
管理 Gateway 网关插件/扩展（进程内加载）。
相关内容：
- 插件系统：[插件](/plugin)
- 插件清单 + schema：[插件清单](/plugins/manifest)
- 插件清单 + 模式：[插件清单](/plugins/manifest)
- 安全加固：[安全](/gateway/security)
## 命令
@@ -35,9 +35,9 @@ openclaw plugins update <id>
openclaw plugins update --all
```
内置插件随 OpenClaw 一起分发，但默认处于禁用状态。使用 `plugins enable` 来激活它们。
内置插件随 OpenClaw 一起发布，但默认禁用。使用 `plugins enable` 来激活它们。
所有插件必须附带一个 `openclaw.plugin.json` 文件，其中包含内联 JSON Schema（`configSchema`，即使为空也需要）。缺失或无效的清单或 schema 会导致插件无法加载，并使配置验证失败。
所有插件必须提供 `openclaw.plugin.json` 文件，其中包含内联 JSON Schema（`configSchema`，即使为空）。缺少或无效的清单或模式会阻止插件加载并导致配置验证失败。
### 安装
@@ -45,11 +45,11 @@ openclaw plugins update --all
openclaw plugins install <path-or-spec>
```
安全提示：安装插件等同于运行代码，请优先使用固定版本。
安全提示：将插件安装视为运行代码。优先使用固定版本。
支持的归档格式：`.zip`、`.tgz`、`.tar.gz`、`.tar`。
使用 `--link` 可避免复制本地目录（会添加到 `plugins.load.paths`）：
使用 `--link` 避免复制本地目录（添加到 `plugins.load.paths`）：
```bash
openclaw plugins install -l ./my-plugin

74
docs/zh-CN/cli/sandbox.md
View File

@@ -1,30 +1,30 @@
---
read_when: 你正在管理沙箱容器或调试沙箱/工具策略行为。
read_when: You are managing sandbox containers or debugging sandbox/tool-policy behavior.
status: active
summary: 管理沙箱容器并检查生效的沙箱策略
title: Sandbox CLI
title: 沙箱 CLI
x-i18n:
generated_at: "2026-02-01T20:21:35Z"
generated_at: "2026-02-03T07:45:18Z"
model: claude-opus-4-5
provider: pi
source_hash: 6e1186f26c77e188206ce5e198ab624d6b38bc7bb7c06e4d2281b6935c39e347
source_path: cli/sandbox.md
workflow: 14
workflow: 15
---
# Sandbox CLI
# 沙箱 CLI
管理基于 Docker 的沙箱容器，用于隔离智能体执行。
## 概述
OpenClaw 可以在隔离的 Docker 容器中运行智能体以确保安全性。`sandbox` 命令帮助你管理这些容器，尤其是在更新或配置变更之后。
OpenClaw 可以在隔离的 Docker 容器中运行智能体以确保安全。`sandbox` 命令帮助你管理这些容器，特别是在更新或配置更改后。
## 命令
### `openclaw sandbox explain`
检查**生效的**沙箱模式/作用域/工作区访问权限、沙箱工具策略以及提权门控（附带修复建议的配置键路径）。
检查**生效的**沙箱模式/作用域/工作区访问权限、沙箱工具策略和提权门控（附带修复配置的键路径）。
```bash
openclaw sandbox explain
@@ -39,62 +39,62 @@ openclaw sandbox explain --json
```bash
openclaw sandbox list
openclaw sandbox list --browser # 仅列出浏览器容器
openclaw sandbox list --json # JSON 输出
openclaw sandbox list --browser # List only browser containers
openclaw sandbox list --json # JSON output
```
**输出包括：**
- 容器名称和状态（运行中/已停止）
- Docker 镜像及其是否与配置匹配
- 存在时间（自创建以来的时长）
- 空闲时间（自上次使用以来的时长）
- 创建时间
- 空闲时间（自上次使用以来的时间）
- 关联的会话/智能体
### `openclaw sandbox recreate`
移除沙箱容器，以便使用更新的镜像/配置强制重新创建。
移除沙箱容器以强制使用更新的镜像/配置重新创建。
```bash
openclaw sandbox recreate --all # 重新创建所有容器
openclaw sandbox recreate --session main # 指定会话
openclaw sandbox recreate --agent mybot # 指定智能体
openclaw sandbox recreate --browser # 仅浏览器容器
openclaw sandbox recreate --all --force # 跳过确认提示
openclaw sandbox recreate --all # Recreate all containers
openclaw sandbox recreate --session main # Specific session
openclaw sandbox recreate --agent mybot # Specific agent
openclaw sandbox recreate --browser # Only browser containers
openclaw sandbox recreate --all --force # Skip confirmation
```
**选项：**
- `--all`：重新创建所有沙箱容器
- `--session <key>`：重新创建指定会话的容器
- `--agent <id>`：重新创建指定智能体的容器
- `--session <key>`：重新创建特定会话的容器
- `--agent <id>`：重新创建特定智能体的容器
- `--browser`：仅重新创建浏览器容器
- `--force`：跳过确认提示
**重要提示：** 容器会在智能体下次使用时自动重新创建。
**重要：** 容器会在智能体下次使用时自动重新创建。
## 使用场景
### 更新 Docker 镜像后
```bash
# 拉取新镜像
# Pull new image
docker pull openclaw-sandbox:latest
docker tag openclaw-sandbox:latest openclaw-sandbox:bookworm-slim
# 更新配置以使用新镜像
# 编辑配置：agents.defaults.sandbox.docker.image（或 agents.list[].sandbox.docker.image）
# Update config to use new image
# Edit config: agents.defaults.sandbox.docker.image (or agents.list[].sandbox.docker.image)
# 重新创建容器
# Recreate containers
openclaw sandbox recreate --all
```
### 更改沙箱配置后
```bash
# 编辑配置：agents.defaults.sandbox.*（或 agents.list[].sandbox.*）
# Edit config: agents.defaults.sandbox.* (or agents.list[].sandbox.*)
# 重新创建以应用新配置
# Recreate to apply new config
openclaw sandbox recreate --all
```
@@ -102,32 +102,32 @@ openclaw sandbox recreate --all
```bash
openclaw sandbox recreate --all
# 或仅针对某个智能体：
# or just one agent:
openclaw sandbox recreate --agent family
```
### 仅针对特定智能体
```bash
# 仅更新某个智能体的容器
# Update only one agent's containers
openclaw sandbox recreate --agent alfred
```
## 为什么需要这样做？
## 为什么需要这个？
**问题：** 当你更新沙箱 Docker 镜像或配置时：
- 现有容器会继续使用旧设置运行
- 容器仅在空闲 24 小时后才会被清理
- 经常使用的智能体会无限期地保持旧容器运行
- 现有容器继续使用旧设置运行
- 容器仅在空闲 24 小时后才被清理
- 经常使用的智能体会无限期保持旧容器运行
**解决方案：** 使用 `openclaw sandbox recreate` 强制移除旧容器。它们会在下次需要时自动使用当前设置重新创建。
提示：建议使用 `openclaw sandbox recreate` 而非手动执行 `docker rm`。它使用 Gateway网关的容器命名规则，避免在作用域/会话键发生变化时出现不匹配问题。
提示：优先使用 `openclaw sandbox recreate` 而不是手动 `docker rm`。它使用 Gateway 网关的容器命名规则，避免在作用域/会话键更改时出现不匹配。
## 配置
沙箱设置位于 `~/.openclaw/openclaw.json` 中的 `agents.defaults.sandbox` 下（按智能体覆盖的配置放在 `agents.list[].sandbox` 中）：
沙箱设置位于 `~/.openclaw/openclaw.json` 的 `agents.defaults.sandbox` 下（每个智能体的覆盖设置在 `agents.list[].sandbox` 中）：
```jsonc
{
@@ -139,11 +139,11 @@ openclaw sandbox recreate --agent alfred
"docker": {
"image": "openclaw-sandbox:bookworm-slim",
"containerPrefix": "openclaw-sbx-",
// ... 更多 Docker 选项
// ... more Docker options
},
"prune": {
"idleHours": 24, // 空闲 24 小时后自动清理
"maxAgeDays": 7, // 7 天后自动清理
"idleHours": 24, // Auto-prune after 24h idle
"maxAgeDays": 7, // Auto-prune after 7 days
},
},
},

16
docs/zh-CN/cli/security.md
View File

@@ -1,23 +1,23 @@
---
read_when:
- 想要对配置/状态进行快速安全审计
- 想要应用安全的"修复"建议（chmod、收紧默认值）
summary: 审计和修复常见安全隐患的 `openclaw security` CLI 参考
- 你想对配置/状态运行快速安全审计
- 你想应用安全的"修复"建议（chmod、收紧默认值）
summary: "`openclaw security` 的 CLI 参考（审计和修复常见安全隐患）"
title: security
x-i18n:
generated_at: "2026-02-01T20:21:24Z"
generated_at: "2026-02-03T07:45:13Z"
model: claude-opus-4-5
provider: pi
source_hash: 19705b0fff848fa6f302b4ed09b7660c64e09048dba517c7f6a833d2db40bebf
source_path: cli/security.md
workflow: 14
workflow: 15
---
# `openclaw security`
安全工具（审计 + 可选修复）。
相关内容：
相关：
- 安全指南：[安全](/gateway/security)
@@ -29,5 +29,5 @@ openclaw security audit --deep
openclaw security audit --fix
```
当多个私信发送者共享主会话时，审计会发出警告，并建议共享收件箱使用 `session.dmScope="per-channel-peer"`（多账户渠道则使用 `per-account-channel-peer`）。
审计还会在小模型（`<=300B`）未启用沙箱且启用了 web/browser 工具时发出警告。
当多个私信发送者共享主会话时，审计会发出警告，并建议对共享收件箱使用 `session.dmScope="per-channel-peer"`（或多账户渠道使用 `per-account-channel-peer`）。
当使用小模型（`<=300B`）且未启用沙箱隔离但启用了 web/browser 工具时，它也会发出警告。

14
docs/zh-CN/cli/skills.md
View File

@@ -1,26 +1,26 @@
---
read_when:
- 想要查看哪些 Skills 可用且可以运行
- 想要调试 Skills 缺失的二进制文件/环境变量/配置
summary: Skills 列表/信息/检查及 Skills 资格的 `openclaw skills` CLI 参考
- 你想查看哪些 Skills 可用并准备好运行
- 你想调试 Skills 缺少的二进制文件/环境变量/配置
summary: "`openclaw skills` 的 CLI 参考（列出/信息/检查）和 skill 资格"
title: skills
x-i18n:
generated_at: "2026-02-01T20:21:28Z"
generated_at: "2026-02-03T07:45:14Z"
model: claude-opus-4-5
provider: pi
source_hash: 7878442c88a27ec8033f3125c319e9a6a85a1c497a404a06112ad45185c261b0
source_path: cli/skills.md
workflow: 14
workflow: 15
---
# `openclaw skills`
检查 Skills（内置 + 工作区 + 托管覆盖），查看哪些符合条件以及哪些缺少依赖。
检查 Skills（内置 + 工作区 + 托管覆盖）并查看哪些符合条件，哪些缺少要求。
相关内容：
- Skills 系统：[Skills](/tools/skills)
- Skills配置：[Skills配置](/tools/skills-config)
- Skills 配置：[Skills 配置](/tools/skills-config)
- ClawHub 安装：[ClawHub](/tools/clawhub)
## 命令

22
docs/zh-CN/cli/status.md
View File

@@ -1,21 +1,21 @@
---
read_when:
- 你想快速诊断渠道健康状况及近期会话接收者
- 你想获取可粘贴的完整状态信息用于调试
summary: "`openclaw status`（诊断、探测、使用情况快照）的 CLI 参考"
- 你想快速诊断渠道健康状况 + 最近的会话接收者
- 你想获取可粘贴的"all"状态用于调试
summary: "`openclaw status` 的 CLI 参考（诊断、探测、使用量快照）"
title: status
x-i18n:
generated_at: "2026-02-01T20:21:30Z"
generated_at: "2026-02-03T07:45:21Z"
model: claude-opus-4-5
provider: pi
source_hash: 2bbf5579c48034fc15c2cbd5506c50456230b17e4a74c06318968c590d8f1501
source_path: cli/status.md
workflow: 14
workflow: 15
---
# `openclaw status`
渠道和会话的诊断信息。
渠道 + 会话的诊断。
```bash
openclaw status
@@ -24,10 +24,10 @@ openclaw status --deep
openclaw status --usage
```
说明：
注意事项：
- `--deep` 会运行实时探测（WhatsApp Web + Telegram + Discord + Google Chat + Slack + Signal）。
- `--deep` 运行实时探测（WhatsApp Web + Telegram + Discord + Google Chat + Slack + Signal）。
- 当配置了多个智能体时，输出包含每个智能体的会话存储。
- 概览包含 Gateway网关和节点主机服务的安装/运行状态（如可用）。
- 概览包含更新渠道和 git SHA（适用于源码检出）。
- 更新信息会显示在概览中；如果有可用更新，状态会提示运行 `openclaw update`（参见[更新](/install/updating)）。
- 概览包含 Gateway 网关 + 节点主机服务安装/运行时状态（如果可用）。
- 概览包含更新渠道 + git SHA（用于源代码检出）。
- 更新信息显示在概览中；如果有可用更新，status 会打印提示运行 `openclaw update`（参见[更新](/install/updating)）。

26
docs/zh-CN/cli/system.md
View File

@@ -1,22 +1,22 @@
---
read_when:
- 你想在不创建 cron 任务的情况下将系统事件加入队列
- 你想在不创建 cron 作业的情况下入队系统事件
- 你需要启用或禁用心跳
- 你想检查系统存在状态条目
summary: "`openclaw system` 的 CLI 参考（系统事件、心跳、存在状态）"
- 你想检查系统在线状态条目
summary: "`openclaw system` 的 CLI 参考（系统事件、心跳、在线状态）"
title: system
x-i18n:
generated_at: "2026-02-01T20:21:34Z"
generated_at: "2026-02-03T07:45:23Z"
model: claude-opus-4-5
provider: pi
source_hash: 36ae5dbdec327f5a32f7ef44bdc1f161bad69868de62f5071bb4d25a71bfdfe9
source_path: cli/system.md
workflow: 14
workflow: 15
---
# `openclaw system`
Gateway网关的系统级辅助工具：将系统事件加入队列、控制心跳以及查看存在状态。
Gateway 网关的系统级辅助工具：入队系统事件、控制心跳和查看在线状态。
## 常用命令
@@ -29,11 +29,11 @@ openclaw system presence
## `system event`
在**主**会话上将系统事件加入队列。下一次心跳会将其作为 `System:` 行注入到提示中。使用 `--mode now` 可立即触发心跳；`next-heartbeat` 则等待下一次计划的心跳周期。
在**主**会话上入队系统事件。下一次心跳会将其作为 `System:` 行注入到提示中。使用 `--mode now` 立即触发心跳；`next-heartbeat` 等待下一个计划的心跳时刻。
标志：
- `--text <text>`：必需的系统事件文本。
- `--text <text>`：必填的系统事件文本。
- `--mode <mode>`：`now` 或 `next-heartbeat`（默认）。
- `--json`：机器可读输出。
@@ -41,8 +41,8 @@ openclaw system presence
心跳控制：
- `last`：显示上一次心跳事件。
- `enable`：重新开启心跳（如果之前被禁用，请使用此命令）。
- `last`：显示最后一次心跳事件。
- `enable`：重新开启心跳（如果之前被禁用，使用此命令）。
- `disable`：暂停心跳。
标志：
@@ -51,13 +51,13 @@ openclaw system presence
## `system presence`
列出 Gateway网关已知的当前系统存在状态条目（节点、实例及类似状态行）。
列出 Gateway 网关已知的当前系统在线状态条目（节点、实例和类似状态行）。
标志：
- `--json`：机器可读输出。
## 注意事项
## 注意
- 需要当前配置（本地或远程）可访问的运行中 Gateway网关。
- 需要一个运行中的 Gateway 网关，可通过你当前的配置访问（本地或远程）。
- 系统事件是临时的，不会在重启后持久化。

14
docs/zh-CN/cli/tui.md
View File

@@ -1,23 +1,23 @@
---
read_when:
- 想要使用 Gateway网关的终端 UI（支持远程）
- 想要从脚本传递 url/token/session
summary: 连接到 Gateway网关的终端 UI 的 `openclaw tui` CLI 参考
- 你想要一个连接 Gateway 网关的终端 UI（支持远程）
- 你想从脚本传递 url/token/session
summary: "`openclaw tui` 的 CLI 参考（连接到 Gateway 网关的终端 UI）"
title: tui
x-i18n:
generated_at: "2026-02-01T20:21:31Z"
generated_at: "2026-02-03T07:45:20Z"
model: claude-opus-4-5
provider: pi
source_hash: f0a97d92e08746a9d6a4f31d361ccad9aea4c3dc61cfafb310d88715f61cfb64
source_path: cli/tui.md
workflow: 14
workflow: 15
---
# `openclaw tui`
打开连接到 Gateway网关的终端 UI。
打开连接到 Gateway 网关的终端 UI。
相关内容：
相关：
- TUI 指南：[TUI](/tui)

10
docs/zh-CN/cli/uninstall.md
View File

@@ -1,21 +1,21 @@
---
read_when:
- 你想移除 Gateway网关服务和/或本地状态
- 你想移除 Gateway 网关服务和/或本地状态
- 你想先进行试运行
summary: "`openclaw uninstall`（移除 Gateway网关服务 + 本地数据）的 CLI 参考"
summary: "`openclaw uninstall` 的 CLI 参考（移除 Gateway 网关服务 + 本地数据）"
title: uninstall
x-i18n:
generated_at: "2026-02-01T20:21:33Z"
generated_at: "2026-02-03T10:04:23Z"
model: claude-opus-4-5
provider: pi
source_hash: 8d6c3890923f18f95c12b76443d649a6b404934ebd054fb86a9fa1abae843fe4
source_path: cli/uninstall.md
workflow: 14
workflow: 15
---
# `openclaw uninstall`
卸载 Gateway网关服务 + 本地数据（CLI 保留）。
卸载 Gateway 网关服务 + 本地数据（CLI 保留）。
```bash
openclaw uninstall

38
docs/zh-CN/cli/update.md
View File

@@ -2,22 +2,22 @@
read_when:
- 你想安全地更新源码检出
- 你需要了解 `--update` 简写行为
summary: "`openclaw update`（安全的源码更新 + Gateway网关自动重启）的 CLI 参考"
summary: "`openclaw update` 的 CLI 参考（相对安全的源码更新 + Gateway 网关自动重启）"
title: update
x-i18n:
generated_at: "2026-02-01T20:21:45Z"
generated_at: "2026-02-03T07:45:34Z"
model: claude-opus-4-5
provider: pi
source_hash: 3a08e8ac797612c498eef54ecb83e61c9a1ee5de09162a01dbb4b3bd72897206
source_path: cli/update.md
workflow: 14
workflow: 15
---
# `openclaw update`
安全更新 OpenClaw 并在 stable/beta/dev 渠道之间切换。
如果你通过 **npm/pnpm** 安装（全局安装，无 git 元数据），更新将通过[更新](/install/updating)中的包管理器流程进行。
如果你通过 **npm/pnpm** 安装（全局安装，无 git 元数据），更新通过 [更新](/install/updating) 中的包管理器流程进行。
## 用法
@@ -35,17 +35,17 @@ openclaw --update
## 选项
- `--no-restart`：成功更新后跳过重启 Gateway网关服务。
- `--no-restart`：成功更新后跳过重启 Gateway 网关服务。
- `--channel <stable|beta|dev>`：设置更新渠道（git + npm；持久化到配置中）。
- `--tag <dist-tag|version>`：仅为本次更新覆盖 npm dist-tag 或版本。
- `--json`：输出机器可读的 `UpdateRunResult` JSON。
- `--timeout <seconds>`：每步超时时间（默认为 1200 秒）。
- `--json`：打印机器可读的 `UpdateRunResult` JSON。
- `--timeout <seconds>`：每步超时时间（默认 1200 秒）。
注意：降级需要确认，因为旧版本可能会破坏配置。
## `update status`
显示当前活跃的更新渠道 + git 标签/分支/SHA（适用于源码检出），以及更新可用性。
显示当前更新渠道 + git 标签/分支/SHA（对于源码检出），以及更新可用性。
```bash
openclaw update status
@@ -55,12 +55,12 @@ openclaw update status --timeout 10
选项：
- `--json`：输出机器可读的状态 JSON。
- `--timeout <seconds>`：检查超时时间（默认为 3 秒）。
- `--json`：打印机器可读的状态 JSON。
- `--timeout <seconds>`：检查超时时间（默认 3 秒）。
## `update wizard`
交互式流程，用于选择更新渠道并确认更新后是否重启 Gateway网关（默认重启）。如果你选择 `dev` 但没有 git 检出，它会提供创建一个的选项。
交互式流程，用于选择更新渠道并确认是否在更新后重启 Gateway 网关（默认重启）。如果你选择 `dev` 但没有 git 检出，它会提供创建一个的选项。
## 工作原理
@@ -77,21 +77,21 @@ openclaw update status --timeout 10
- `beta`：检出最新的 `-beta` 标签，然后构建 + doctor。
- `dev`：检出 `main`，然后 fetch + rebase。
概要流程：
高层概述：
1. 要求工作树干净（无未提交的更改）。
1. 需要干净的工作树（无未提交的更改）。
2. 切换到所选渠道（标签或分支）。
3. 拉取上游（仅 dev）。
4. 仅 dev：在临时工作树中进行预检 lint + TypeScript 构建；如果最新提交失败，会向前回溯最多 10 个提交以找到最新的可成功构建的提交。
3. 获取上游（仅 dev）。
4. 仅 dev：在临时工作树中预检 lint + TypeScript 构建；如果最新提交失败，回退最多 10 个提交以找到最新的干净构建。
5. Rebase 到所选提交（仅 dev）。
6. 安装依赖（优先使用 pnpm；回退到 npm）。
7. 构建项目 + 构建控制台 UI。
6. 安装依赖（优先使用 pnpm；npm 作为备选）。
7. 构建 + 构建控制界面。
8. 运行 `openclaw doctor` 作为最终的"安全更新"检查。
9. 将插件同步到活跃渠道（dev 使用内置扩展；stable/beta 使用 npm）并更新通过 npm 安装的插件。
9. 将插件同步到当前渠道（dev 使用捆绑的扩展；stable/beta 使用 npm）并更新 npm 安装的插件。
## `--update` 简写
`openclaw --update` 会重写为 `openclaw update`（便于在 shell 和启动脚本中使用）。
`openclaw --update` 会重写为 `openclaw update`（便于 shell 和启动脚本使用）。
## 另请参阅

100
docs/zh-CN/concepts/agent-loop.md
View File

@@ -4,147 +4,143 @@ read_when:
summary: 智能体循环生命周期、流和等待语义
title: 智能体循环
x-i18n:
generated_at: "2026-02-01T20:22:03Z"
generated_at: "2026-02-03T10:05:11Z"
model: claude-opus-4-5
provider: pi
source_hash: 0775b96eb3451e137297661a1095eaefb2bafeebb5f78123174a46290e18b014
source_path: concepts/agent-loop.md
workflow: 14
workflow: 15
---
# 智能体循环（OpenClaw）
智能体循环是智能体的一次完整"真实"运行：接收 → 上下文组装 → 模型推理 →
工具执行 → 流式回复 → 持久化。它是将消息转化为操作和最终回复的权威路径，同时保持会话状态的一致性。
智能体循环是智能体的完整"真实"运行：接收 → 上下文组装 → 模型推理 → 工具执行 → 流式回复 → 持久化。这是将消息转化为操作和最终回复的权威路径，同时保持会话状态的一致性。
在 OpenClaw 中，循环是每个会话的单次序列化运行，在模型思考、调用工具和流式输出时发出生命周期和流事件。本文档解释了这个完整循环是如何端到端连接的。
在 OpenClaw 中，循环是每个会话的单次序列化运行，在模型思考、调用工具和流式输出时发出生命周期和流事件。本文档解释了这个真实循环是如何端到端连接的。
## 入口点
- Gateway网关 RPC：`agent` 和 `agent.wait`。
- Gateway 网关 RPC：`agent` 和 `agent.wait`。
- CLI：`agent` 命令。
## 工作原理（高层概述）
## 工作原理（高层次）
1. `agent` RPC 验证参数，解析会话（sessionKey/sessionId），持久化会话元数据，立即返回 `{ runId, acceptedAt }`。
2. `agentCommand` 运行智能体：
- 解析模型 + thinking/verbose 默认值
- 解析模型 + 思考/详细模式默认值
- 加载 Skills 快照
- 调用 `runEmbeddedPiAgent`（pi-agent-core 运行时）
- 如果嵌入式循环未发出**生命周期 end/error** 事件，则补充发出
- 如果嵌入式循环未发出**生命周期结束/错误**事件，则发出该事件
3. `runEmbeddedPiAgent`：
- 通过每会话 + 全局队列序列化运行
- 解析模型 + 认证配置并构建 pi 会话
- 解析模型 + 认证配置文件并构建 pi 会话
- 订阅 pi 事件并流式传输助手/工具增量
- 强制执行超时 -> 超时则中止运行
- 返回载荷 + 使用量元数据
- 返回有效负载 + 使用元数据
4. `subscribeEmbeddedPiSession` 将 pi-agent-core 事件桥接到 OpenClaw `agent` 流：
- 工具事件 => `stream: "tool"`
- 助手增量 => `stream: "assistant"`
- 生命周期事件 => `stream: "lifecycle"`（`phase: "start" | "end" | "error"`）
5. `agent.wait` 使用 `waitForAgentJob`：
- 等待 `runId` 的**生命周期 end/error**
- 等待 `runId` 的**生命周期结束/错误**
- 返回 `{ status: ok|error|timeout, startedAt, endedAt, error? }`
## 队列 + 并发
- 运行按会话键（会话通道）序列化，并可选择通过全局通道进行。
- 运行按会话键（会话通道）序列化，可选择通过全局通道。
- 这可以防止工具/会话竞争并保持会话历史的一致性。
- 消息渠道可以选择队列模式（collect/steer/followup）来供给此通道系统。
参见[命令队列](/concepts/queue)。
- 消息渠道可以选择队列模式（collect/steer/followup）来馈送此通道系统。参见[命令队列](/concepts/queue)。
## 会话 + 工作区准备
- 工作区被解析并创建；沙箱运行可能会重定向到沙箱工作区根目录。
- Skills 被加载（或从快照中复用）并注入到环境和提示中。
- 引导/上下文文件被解析并注入到系统提示报告中。
- 解析并创建工作区；沙箱隔离运行可能会重定向到沙箱工作区根目录。
- 加载 Skills（或从快照中复用）并注入到环境和提示中。
- 解析引导/上下文文件并注入到系统提示报告中。
- 获取会话写锁；在流式传输之前打开并准备 `SessionManager`。
## 提示组装 + 系统提示
- 系统提示由 OpenClaw 的基础提示、Skills 提示、引导上下文和每次运行的覆盖项构建而成。
- 强制执行模型特定的限制和压缩预留令牌数。
- 参见[系统提示](/concepts/system-prompt)了解模型所看到的内容。
- 系统提示由 OpenClaw 的基础提示、Skills 提示、引导上下文和每次运行的覆盖构建。
- 强制执行模型特定的限制和压缩保留令牌。
- 参见[系统提示](/concepts/system-prompt)了解模型看到的内容。
## 钩子点（可拦截的位置）
## 钩子点（可以拦截的位置）
OpenClaw 有两个钩子系统：
- **内部钩子**（Gateway网关钩子）：用于命令和生命周期事件的事件驱动脚本。
- **插件钩子**：智能体/工具生命周期和 Gateway网关管道中的扩展点。
- **内部钩子**（Gateway 网关钩子）：用于命令和生命周期事件的事件驱动脚本。
- **插件钩子**：智能体/工具生命周期和 Gateway 网关管道中的扩展点。
### 内部钩子（Gateway网关钩子）
### 内部钩子（Gateway 网关钩子）
- **`agent:bootstrap`**：在系统提示最终确定之前构建引导文件时运行。
用于添加/移除引导上下文文件。
- **`agent:bootstrap`**：在系统提示最终确定之前构建引导文件时运行。用于添加/删除引导上下文文件。
- **命令钩子**：`/new`、`/reset`、`/stop` 和其他命令事件（参见钩子文档）。
参见[钩子](/hooks)了解设置和示例。
### 插件钩子（智能体 + Gateway网关生命周期）
### 插件钩子（智能体 + Gateway 网关生命周期）
这些在智能体循环或 Gateway网关管道内运行：
这些在智能体循环或 Gateway 网关管道内运行：
- **`before_agent_start`**：在运行开始前注入上下文或覆盖系统提示。
- **`agent_end`**：在完成后检查最终消息列表和运行元数据。
- **`before_compaction` / `after_compaction`**：观察或标注压缩周期。
- **`before_compaction` / `after_compaction`**：观察或注释压缩周期。
- **`before_tool_call` / `after_tool_call`**：拦截工具参数/结果。
- **`tool_result_persist`**：在工具结果写入会话记录之前同步转换工具结果。
- **`tool_result_persist`**：在工具结果写入会话记录之前同步转换它们。
- **`message_received` / `message_sending` / `message_sent`**：入站 + 出站消息钩子。
- **`session_start` / `session_end`**：会话生命周期边界。
- **`gateway_start` / `gateway_stop`**：Gateway网关生命周期事件。
- **`gateway_start` / `gateway_stop`**：Gateway 网关生命周期事件。
参见[插件](/plugin#plugin-hooks)了解钩子 API 和注册详情。
## 流式传输 + 部分回复
- 助手增量从 pi-agent-core 流式传输并作为 `assistant` 事件发出。
- 块流式传输可以在 `text_end` 或 `message_end` 时发出部分回复。
- 分块流式传输可以在 `text_end` 或 `message_end` 时发出部分回复。
- 推理流式传输可以作为单独的流或作为块回复发出。
- 参见[流式传输](/concepts/streaming)了解分块和块回复行为。
## 工具执行 + 消息工具
- 工具的 start/update/end 事件在 `tool` 流上发出。
- 工具结果在记录/发出之前会针对大小和图片载荷进行清理。
- 消息工具的发送会被跟踪，以抑制重复的助手确认。
- 工具开始/更新/结束事件在 `tool` 流上发出。
- 工具结果在记录/发出之前会对大小和图像有效负载进行清理。
- 消息工具发送会被跟踪以抑制重复的助手确认。
## 回复整形 + 抑制
- 最终载荷由以下内容组装：
- 助手文本（及可选的推理内容）
- 内联工具摘要（当 verbose + 允许时）
- 最终有效负载由以下内容组装：
- 助手文本（和可选的推理）
- 内联工具摘要（当详细模式 + 允许时）
- 模型出错时的助手错误文本
- `NO_REPLY` 被视为静默令牌，从传出载荷中过滤。
- 消息工具的重复项从最终载荷列表中移除。
- 如果没有可渲染的载荷且工具出错，则发出回退的工具错误回复
（除非消息工具已发送了用户可见的回复）。
- `NO_REPLY` 被视为静默令牌，从出站有效负载中过滤。
- 消息工具重复项从最终有效负载列表中移除。
- 如果没有剩余可渲染的有效负载且工具出错，则发出回退工具错误回复（除非消息工具已经发送了用户可见的回复）。
## 压缩 + 重试
- 自动压缩发出 `compaction` 流事件，并可能触发重试。
- 重试时，内存缓冲区和工具摘要会被重置以避免重复输出。
- 自动压缩发出 `compaction` 流事件，可以触发重试。
- 重试时，内存缓冲区和工具摘要会重置以避免重复输出。
- 参见[压缩](/concepts/compaction)了解压缩管道。
## 事件流（当前）
- `lifecycle`：由 `subscribeEmbeddedPiSession` 发出（以及作为 `agentCommand` 的回退）
- `assistant`：来自 pi-agent-core 的流式增量
- `tool`：来自 pi-agent-core 的流式工具事件
- `assistant`：从 pi-agent-core 流式传输的增量
- `tool`：从 pi-agent-core 流式传输的工具事件
## 聊天渠道处理
- 助手增量被缓冲为聊天 `delta` 消息。
- 在**生命周期 end/error** 时发出聊天 `final`。
- 助手增量被缓冲到聊天 `delta` 消息中。
- 在**生命周期结束/错误**时发出聊天 `final`。
## 超时
- `agent.wait` 默认值：30 秒（仅等待阶段）。`timeoutMs` 参数可覆盖。
- `agent.wait` 默认：30 秒（仅等待）。`timeoutMs` 参数可覆盖。
- 智能体运行时：`agents.defaults.timeoutSeconds` 默认 600 秒；在 `runEmbeddedPiAgent` 中止计时器中强制执行。
## 可能提前结束的情况
- 智能体超时（中止）
- AbortSignal（取消）
- Gateway网关断开连接或 RPC 超时
- `agent.wait` 超时（仅等待阶段，不会停止智能体）
- Gateway 网关断开连接或 RPC 超时
- `agent.wait` 超时（仅等待，不会停止智能体）

113
docs/zh-CN/concepts/agent-workspace.md
View File

@@ -1,30 +1,32 @@
---
read_when:
- 你需要解释智能体工作区或其文件布局
- 你想要备份或迁移智能体工作区
- 你想备份或迁移智能体工作区
summary: 智能体工作区：位置、布局和备份策略
title: 智能体工作区
x-i18n:
generated_at: "2026-02-01T20:22:05Z"
generated_at: "2026-02-03T07:45:49Z"
model: claude-opus-4-5
provider: pi
source_hash: 84c550fd89b5f2474aeae586795485fd29d36effbb462f13342b31540fc18b82
source_path: concepts/agent-workspace.md
workflow: 14
workflow: 15
---
# 智能体工作区
工作区是智能体的主目录。它是文件工具和工作区上下文使用的唯一工作目录。请将其保持私密，并视为记忆来对待。
工作区是智能体的家。它是文件工具和工作区上下文使用的唯一工作目录。请保持其私密性并将其视为记忆。
它与 `~/.openclaw/` 是分开的，后者存储配置、凭据和会话。
这与 `~/.openclaw/` 是分开的，后者存储配置、凭证和会话。
**重要提示：** 工作区是**默认工作目录**，而非硬性沙箱。工具会基于工作区解析相对路径，但绝对路径仍然可以访问主机上的其他位置，除非启用了沙箱。如果你需要隔离，请使用 [`agents.defaults.sandbox`](/gateway/sandboxing)（和/或按智能体的沙箱配置）。当启用沙箱且 `workspaceAccess` 不是 `"rw"` 时，工具在 `~/.openclaw/sandboxes` 下的沙箱工作区中运行，而非你的主机工作区。
**重要：** 工作区是**默认 cwd**，而不是硬性沙箱。工具会根据工作区解析相对路径，但绝对路径仍然可以访问主机上的其他位置，除非启用了沙箱隔离。如果你需要隔离，请使用
[`agents.defaults.sandbox`](/gateway/sandboxing)（和/或每智能体沙箱配置）。
当启用沙箱隔离且 `workspaceAccess` 不是 `"rw"` 时，工具在 `~/.openclaw/sandboxes` 下的沙箱工作区内操作，而不是你的主机工作区。
## 默认位置
- 默认：`~/.openclaw/workspace`
- 如果设置了 `OPENCLAW_PROFILE` 且不是 `"default"`，则默认变为
- 如果设置了 `OPENCLAW_PROFILE` 且不是 `"default"`，默认值变为
`~/.openclaw/workspace-<profile>`。
- 在 `~/.openclaw/openclaw.json` 中覆盖：
@@ -36,9 +38,9 @@ x-i18n:
}
```
`openclaw onboard`、`openclaw configure` 或 `openclaw setup` 将创建工作区，并在引导文件缺失时生成它们。
`openclaw onboard`、`openclaw configure` 或 `openclaw setup` 将创建工作区并在缺失时填充引导文件。
如果你已经自行管理工作区文件，可以禁用引导文件创建：
如果你已经自己管理工作区文件，可以禁用引导文件创建：
```json5
{ agent: { skipBootstrap: true } }
@@ -46,20 +48,21 @@ x-i18n:
## 额外的工作区文件夹
较旧的安装可能创建了 `~/openclaw`。保留多个工作区目录可能会导致认证或状态不一致的困惑，因为同一时间只有一个工作区处于活跃状态。
旧版安装可能创建了 `~/openclaw`。保留多个工作区目录可能会导致混乱的认证或状态漂移，因为同一时间只有一个工作区是活动的。
**建议：** 保持单一活跃工作区。如果你不再使用额外的文件夹，请将其归档或移至回收站（例如 `trash ~/openclaw`）。如果你有意保留多个工作区，请确保 `agents.defaults.workspace` 指向活跃的那个。
**建议：** 保持单个活动工作区。如果你不再使用额外的文件夹，请归档或移至废纸篓（例如 `trash ~/openclaw`）。
如果你有意保留多个工作区，请确保 `agents.defaults.workspace` 指向活动的那个。
`openclaw doctor` 在检测到额外工作区目录时会发出警告。
## 工作区文件映射（每个文件的含义）
以下是 OpenClaw 在工作区中期望的标准文件：
这些是 OpenClaw 在工作区内期望的标准文件：
- `AGENTS.md`
- 智能体的操作指令以及它应如何使用记忆。
- 智能体的操作指南以及它应该如何使用记忆。
- 在每个会话开始时加载。
- 适合放置规则、优先级和"行为方式"的详细说明。
- 适合放置规则、优先级和"如何行为"的详细信息。
- `SOUL.md`
- 人设、语气和边界。
@@ -74,61 +77,62 @@ x-i18n:
- 在引导仪式期间创建/更新。
- `TOOLS.md`
- 关于本地工具和约定的说明。
- 关于你本地工具和惯例的注释。
- 不控制工具可用性；仅作为指导。
- `HEARTBEAT.md`
- 可选的心跳运行小清单。
- 保持简短以避免消耗令牌。
- 可选的心跳运行小型检查清单。
- 保持简短以避免 token 消耗。
- `BOOT.md`
- 可选的启动清单，在启用内部钩子时于 Gateway网关重启时执行。
- 保持简短；使用消息工具进行外发。
- 当启用内部 hooks 时，在 Gateway 网关重启时执行的可选启动检查清单。
- 保持简短；使用 message 工具进行出站发送。
- `BOOTSTRAP.md`
- 一次性首次运行仪式。
- 仅为全新工作区创建。
- 仪式完成后请删除它。
- 仪式完成后删除它。
- `memory/YYYY-MM-DD.md`
- 每日记忆日志（每天一个文件）。
- 建议在会话开始时读取今天和昨天的内容。
- 建议在会话开始时读取今天 + 昨天的内容。
- `MEMORY.md`（可选）
- 精选的长期记忆。
- 仅在主要的私人会话中加载（不在共享/群组上下文中）。
- 仅在主私密会话中加载（不在共享/群组上下文中）。
参见[记忆](/concepts/memory)了解工作流程和自动记忆刷写。
参见 [记忆](/concepts/memory) 了解工作流程和自动记忆刷新。
- `skills/`（可选）
- 工作区特定的 Skills。
- 名称冲突时覆盖托管/内置 Skills。
- 当名称冲突时覆盖托管/捆绑的 Skills。
- `canvas/`（可选）
- 用于节点显示的 Canvas UI 文件（例如 `canvas/index.html`）。
如果任何引导文件缺失，OpenClaw 会在会话中注入"文件缺失"标记并继续运行。大型引导文件在注入时会被截断；可通过 `agents.defaults.bootstrapMaxChars`（默认：20000）调整限制。`openclaw setup` 可以重新创建缺失的默认文件而不会覆盖现有文件。
如果任何引导文件缺失，OpenClaw 会在会话中注入"缺失文件"标记并继续。大型引导文件在注入时会被截断；使用 `agents.defaults.bootstrapMaxChars` 调整限制（默认：20000）。
`openclaw setup` 可以重新创建缺失的默认值而不覆盖现有文件。
## 不在工作区中的内容
## 工作区中不包含的内容
以下内容位于 `~/.openclaw/` 下，**不应**提交到工作区仓库：
这些位于 `~/.openclaw/` 下，不应提交到工作区仓库：
- `~/.openclaw/openclaw.json`（配置）
- `~/.openclaw/credentials/`（OAuth 令牌、API 密钥）
- `~/.openclaw/agents/<agentId>/sessions/`（会话记录和元数据）
- `~/.openclaw/skills/`（托管 Skills）
- `~/.openclaw/credentials/`（OAuth token、API 密钥）
- `~/.openclaw/agents/<agentId>/sessions/`（会话记录 + 元数据）
- `~/.openclaw/skills/`（托管的 Skills）
如果你需要迁移会话或配置，请单独复制它们并将其排除在版本控制之外。
如果你需要迁移会话或配置，请单独复制它们并将它们排除在版本控制之外。
## Git 备份（推荐，私有）
将工作区视为私有记忆。将其放入一个**私有** git 仓库中，以便备份和恢复。
将工作区视为私密记忆。将其放入**私有** git 仓库以便备份和恢复。
在 Gateway网关运行的机器上执行以下步骤（工作区就在那里）。
在运行 Gateway 网关的机器上执行这些步骤（工作区就在那里）。
### 1) 初始化仓库
### 1）初始化仓库
如果安装了 git，全新的工作区会自动初始化。如果此工作区尚未是仓库，请运行：
如果安装了 git，全新工作区会自动初始化。如果此工作区还不是仓库，请运行：
```bash
cd ~/.openclaw/workspace
@@ -137,14 +141,14 @@ git add AGENTS.md SOUL.md TOOLS.md IDENTITY.md USER.md HEARTBEAT.md memory/
git commit -m "Add agent workspace"
```
### 2) 添加私有远程仓库（新手友好选项）
### 2）添加私有远程（适合初学者的选项）
选项 A：GitHub 网页界面
1. 在 GitHub 上创建一个新的**私有**仓库。
2. 不要使用 README 初始化（避免合并冲突）。
1. 在 GitHub 上创建新的**私有**仓库。
2. 不要用 README 初始化（避免合并冲突）。
3. 复制 HTTPS 远程 URL。
4. 添加远程仓库并推送：
4. 添加远程并推送：
```bash
git branch -M main
@@ -152,7 +156,7 @@ git remote add origin <https-url>
git push -u origin main
```
选项 B：GitHub CLI (`gh`)
选项 B：GitHub CLI（`gh`）
```bash
gh auth login
@@ -161,10 +165,10 @@ gh repo create openclaw-workspace --private --source . --remote origin --push
选项 C：GitLab 网页界面
1. 在 GitLab 上创建一个新的**私有**仓库。
2. 不要使用 README 初始化（避免合并冲突）。
1. 在 GitLab 上创建新的**私有**仓库。
2. 不要用 README 初始化（避免合并冲突）。
3. 复制 HTTPS 远程 URL。
4. 添加远程仓库并推送：
4. 添加远程并推送：
```bash
git branch -M main
@@ -172,7 +176,7 @@ git remote add origin <https-url>
git push -u origin main
```
### 3) 持续更新
### 3）持续更新
```bash
git status
@@ -185,13 +189,13 @@ git push
即使在私有仓库中，也要避免在工作区中存储密钥：
- API 密钥、OAuth 令牌、密码或私有凭据。
- API 密钥、OAuth token、密码或私有凭证。
- `~/.openclaw/` 下的任何内容。
- 聊天记录的原始转储或敏感附件。
- 聊天的原始转储或敏感附件。
如果你必须存储敏感引用，请使用占位符并将真实密钥保存在其他地方（密码管理器、环境变量或 `~/.openclaw/`）。
如果你必须存储敏感引用，请使用占位符并将真正的密钥保存在其他地方（密码管理器、环境变量或 `~/.openclaw/`）。
建议的 `.gitignore` 起始内容：
建议的 `.gitignore` 起始配置：
```gitignore
.DS_Store
@@ -203,12 +207,13 @@ git push
## 将工作区迁移到新机器
1. 将仓库克隆到目标路径（默认 `~/.openclaw/workspace`）。
1. 将仓库克隆到所需路径（默认 `~/.openclaw/workspace`）。
2. 在 `~/.openclaw/openclaw.json` 中将 `agents.defaults.workspace` 设置为该路径。
3. 运行 `openclaw setup --workspace <path>` 以生成任何缺失的文件。
4. 如果你需要会话记录，请从旧机器单独复制 `~/.openclaw/agents/<agentId>/sessions/`。
3. 运行 `openclaw setup --workspace <path>` 来填充任何缺失的文件。
4. 如果你需要会话，请单独从旧机器复制 `~/.openclaw/agents/<agentId>/sessions/`。
## 高级说明
## 高级注意事项
- 多智能体路由可以为每个智能体使用不同的工作区。参见[渠道路由](/concepts/channel-routing)了解路由配置。
- 如果启用了 `agents.defaults.sandbox`，非主要会话可以使用 `agents.defaults.sandbox.workspaceRoot` 下的按会话沙箱工作区。
- 多智能体路由可以为每个智能体使用不同的工作区。参见
[渠道路由](/concepts/channel-routing) 了解路由配置。
- 如果启用了 `agents.defaults.sandbox`，非主会话可以在 `agents.defaults.sandbox.workspaceRoot` 下使用每会话沙箱工作区。

71
docs/zh-CN/concepts/agent.md
View File

@@ -1,51 +1,51 @@
---
read_when:
- 更改智能体运行时、工作区引导或会话行为
- 更改智能体运行时、工作区引导或会话行为时
summary: 智能体运行时（嵌入式 pi-mono）、工作区契约和会话引导
title: 智能体运行时
x-i18n:
generated_at: "2026-02-01T20:22:02Z"
generated_at: "2026-02-03T10:04:53Z"
model: claude-opus-4-5
provider: pi
source_hash: 04b4e0bc6345d2afd9a93186e5d7a02a393ec97da2244e531703cb6a1c182325
source_path: concepts/agent.md
workflow: 14
workflow: 15
---
# 智能体运行时 🤖
OpenClaw 运行一个源自 **pi-mono** 的单一嵌入式智能体运行时。
OpenClaw 运行一个源自 **pi-mono** 的嵌入式智能体运行时。
## 工作区（必需）
OpenClaw 使用单一智能体工作区目录（`agents.defaults.workspace`）作为智能体工具和上下文的**唯一**工作目录（`cwd`）。
OpenClaw 使用单一智能体工作区目录（`agents.defaults.workspace`）作为智能体**唯一**的工作目录（`cwd`），用于工具和上下文。
建议：使用 `openclaw setup` 创建 `~/.openclaw/openclaw.json`（如果不存在）并初始化工作区文件。
建议：使用 `openclaw setup` 在缺失时创建 `~/.openclaw/openclaw.json` 并初始化工作区文件。
完整的工作区布局 + 备份指南：[智能体工作区](/concepts/agent-workspace)
完整工作区布局 + 备份指南：[智能体工作区](/concepts/agent-workspace)
如果启用了 `agents.defaults.sandbox`，非主会话可以使用 `agents.defaults.sandbox.workspaceRoot` 下的按会话工作区覆盖此设置（参见 [Gateway网关配置](/gateway/configuration)）。
如果启用了 `agents.defaults.sandbox`，非主会话可以在 `agents.defaults.sandbox.workspaceRoot` 下使用按会话隔离的工作区覆盖此设置（参见 [Gateway 网关配置](/gateway/configuration)）。
## 引导文件（注入）
在 `agents.defaults.workspace` 内，OpenClaw 期望这些用户可编辑的文件：
在 `agents.defaults.workspace` 内，OpenClaw 期望以下用户可编辑的文件：
- `AGENTS.md` — 操作指令 + "记忆"
- `SOUL.md` — 角色设定、边界、语气
- `SOUL.md` — 人设、边界、语气
- `TOOLS.md` — 用户维护的工具说明（例如 `imsg`、`sag`、约定）
- `BOOTSTRAP.md` — 一次性首次运行仪式（完成后删除）
- `IDENTITY.md` — 智能体名称/风格/表情符号
- `USER.md` — 用户档案 + 首选称呼
- `IDENTITY.md` — 智能体名称/风格/表情
- `USER.md` — 用户档案 + 偏好称呼
在新会话的第一轮对话中，OpenClaw 会将这些文件的内容直接注入到智能体上下文中。
在新会话的第一轮，OpenClaw 将这些文件的内容直接注入智能体上下文。
空白文件会被跳过。大文件会被裁剪和截断并附带标记，以保持提示词精简（阅读完整文件以获取全部内容）。
空文件会被跳过。大文件会被修剪和截断并添加标记，以保持提示词精简（阅读文件获取完整内容）。
如果文件缺失，OpenClaw 会注入一行"文件缺失"标记（`openclaw setup` 会创建安全的默认模板）。
如果文件缺失，OpenClaw 会注入一行"文件缺失"标记（`openclaw setup` 将创建安全的默认模板）。
`BOOTSTRAP.md` 仅在**全新工作区**（没有其他引导文件存在）时创建。如果你在完成仪式后删除了它，后续重启时不会重新创建。
`BOOTSTRAP.md` 仅在**全新工作区**（没有其他引导文件存在）时创建。如果你在完成仪式后删除它，后续重启不应重新创建。
要完全禁用引导文件创建（用于预填充的工作区），请设置：
要完全禁用引导文件创建（用于预置工作区），请设置：
```json5
{ agent: { skipBootstrap: true } }
@@ -53,24 +53,24 @@ OpenClaw 使用单一智能体工作区目录（`agents.defaults.workspace`）
## 内置工具
核心工具（read/exec/edit/write 及相关系统工具）始终可用，受工具策略约束。`apply_patch` 是可选的，由 `tools.exec.applyPatch` 控制。`TOOLS.md` **不**控制哪些工具存在；它是关于你希望如何使用这些工具的指导。
核心工具（read/exec/edit/write 及相关系统工具）始终可用，受工具策略约束。`apply_patch` 是可选的，由 `tools.exec.applyPatch` 控制。`TOOLS.md` **不**控制哪些工具存在；它是关于*你*希望如何使用它们的指导。
## Skills
OpenClaw 从三个位置加载 Skills（名称冲突时工作区优先）：
- 内置（随安装包附带）
- 内置（随安装包提供）
- 托管/本地：`~/.openclaw/skills`
- 工作区：`<workspace>/skills`
Skills 可以通过配置/环境变量进行控制（参见 [Gateway网关配置](/gateway/configuration) 中的 `skills`）。
Skills 可通过配置/环境变量控制（参见 [Gateway 网关配置](/gateway/configuration) 中的 `skills`）。
## pi-mono 集成
OpenClaw 复用了 pi-mono 代码库的部分内容（模型/工具），但**会话管理、发现和工具连接由 OpenClaw 负责**。
OpenClaw 复用 pi-mono 代码库的部分内容（模型/工具），但**会话管理、设备发现和工具连接由 OpenClaw 负责**。
- 没有 pi-coding 智能体运行时。
- 不会读取 `~/.pi/agent` 或 `<workspace>/.pi` 设置。
- 无 pi-coding 智能体运行时。
- 不读取 `~/.pi/agent` 或 `<workspace>/.pi` 设置。
## 会话
@@ -79,30 +79,31 @@ OpenClaw 复用了 pi-mono 代码库的部分内容（模型/工具），但**
- `~/.openclaw/agents/<agentId>/sessions/<SessionId>.jsonl`
会话 ID 是稳定的，由 OpenClaw 选择。
**不会**读取旧版 Pi/Tau 会话文件夹。
**不**读取旧版 Pi/Tau 会话文件夹。
## 流式传输期间的引导
## 流式传输中的引导
当队列模式为 `steer` 时，入站消息会被注入到当前运行中。队列在**每次工具调用后**检查；如果存在排队消息，当前助手消息的剩余工具调用会被跳过（工具结果显示"Skipped due to queued user message."错误），然后在下一个助手响应之前注入排队的用户消息。
当队列模式为 `steer` 时，入站消息会注入当前运行。
队列在**每次工具调用后**检查；如果存在排队消息，当前助手消息的剩余工具调用将被跳过（工具结果显示错误"Skipped due to queued user message."），然后在下一个助手响应前注入排队的用户消息。
当队列模式为 `followup` 或 `collect` 时，入站消息会被保留直到当前轮次结束，然后使用排队的负载开始新的智能体轮次。参见[队列](/concepts/queue)了解模式 + 防抖/上限行为。
当队列模式为 `followup` 或 `collect` 时，入站消息会保留到当前轮次结束，然后使用排队的载荷开始新的智能体轮次。参见 [队列](/concepts/queue) 了解模式 + 防抖/上限行为。
块流式传输在完成的助手块完成后立即发送；**默认关闭**（`agents.defaults.blockStreamingDefault: "off"`）。
分块流式传输在助手块完成后立即发送；默认为**关闭**（`agents.defaults.blockStreamingDefault: "off"`）。
通过 `agents.defaults.blockStreamingBreak` 调整边界（`text_end` 与 `message_end`；默认为 text_end）。
使用 `agents.defaults.blockStreamingChunk` 控制软块分块（默认 800–1200 字符；优先段落分隔，其次换行；最后是句子）。
使用 `agents.defaults.blockStreamingCoalesce` 合并流式块，以减少单行刷屏（基于空闲的合并后再发送）。非 Telegram 渠道需要显式设置 `*.blockStreaming: true` 以启用块回复。
详细的工具摘要在工具启动时发出（无防抖）；Control UI 在可用时通过智能体事件流式传输工具输出。
使用 `agents.defaults.blockStreamingCoalesce` 合并流式块以减少单行刷屏（发送前基于空闲的合并）。非 Telegram 渠道需要显式设置 `*.blockStreaming: true` 以启用分块回复。
工具启动时发出详细工具摘要（无防抖）；Control UI 在可用时通过智能体事件流式传输工具输出。
更多详情：[流式传输 + 分块](/concepts/streaming)。
## 模型引用
配置中的模型引用（例如 `agents.defaults.model` 和 `agents.defaults.models`）通过**第一个** `/` 进行拆分解析。
配置中的模型引用（例如 `agents.defaults.model` 和 `agents.defaults.models`）通过在**第一个** `/` 处分割来解析。
- 配置模型时使用 `provider/model` 格式。
- 如果模型 ID 本身包含 `/`（OpenRouter 风格），请包含提供商前缀（示例：`openrouter/moonshotai/kimi-k2`）。
- 如果省略提供商，OpenClaw 会将输入视为别名或**默认提供商**的模型（仅在模型 ID 中没有 `/` 时有效）。
- 配置模型时使用 `provider/model`。
- 如果模型 ID 本身包含 `/`（OpenRouter 风格），请包含提供商前缀（例如：`openrouter/moonshotai/kimi-k2`）。
- 如果省略提供商，OpenClaw 将输入视为别名或**默认提供商**的模型（仅在模型 ID 中没有 `/` 时有效）。
## 配置（最小化）
## 配置（最小）
至少需要设置：

98
docs/zh-CN/concepts/architecture.md
View File

@@ -1,123 +1,123 @@
---
read_when:
- 处理 Gateway网关协议、客户端或传输层相关工作时
summary: WebSocket Gateway网关架构、组件和客户端流程
title: Gateway网关架构
- 正在开发 Gateway 网关协议、客户端或传输层
summary: WebSocket Gateway 网关架构、组件和客户端流程
title: Gateway 网关架构
x-i18n:
generated_at: "2026-02-01T20:22:27Z"
generated_at: "2026-02-03T07:45:55Z"
model: claude-opus-4-5
provider: pi
source_hash: c636d5d8a5e628067432b30671466309e3d630b106d413f1708765bf2a9399a1
source_path: concepts/architecture.md
workflow: 14
workflow: 15
---
# Gateway网关架构
# Gateway 网关架构
最后更新：2026-01-22
## 概述
- 单个长生命周期的 **Gateway网关** 管理所有消息接入面（通过 Baileys 接入 WhatsApp、通过 grammY 接入 Telegram、Slack、Discord、Signal、iMessage、WebChat）。
- 控制面客户端（macOS 应用、CLI、Web UI、自动化）通过 **WebSocket** 连接到 Gateway网关，使用配置的绑定地址（默认 `127.0.0.1:18789`）。
- **节点**（macOS/iOS/Android/无头模式）也通过 **WebSocket** 连接，但声明 `role: node` 并显式指定能力/命令。
- 每台主机一个 Gateway网关；它是唯一打开 WhatsApp 会话的位置。
- **画布主机**（默认 `18793`）提供智能体可编辑的 HTML 和 A2UI。
- 单个长期运行的 **Gateway 网关**拥有所有消息平台（通过 Baileys 的 WhatsApp、通过 grammY 的 Telegram、Slack、Discord、Signal、iMessage、WebChat）。
- 控制平面客户端（macOS 应用、CLI、Web 界面、自动化）通过配置的绑定主机（默认 `127.0.0.1:18789`）上的 **WebSocket** 连接到 Gateway 网关。
- **节点**（macOS/iOS/Android/无头设备）也通过 **WebSocket** 连接，但声明 `role: node` 并带有明确的能力/命令。
- 每台主机一个 Gateway 网关；它是唯一打开 WhatsApp 会话的位置。
- **canvas 主机**（默认 `18793`）提供智能体可编辑的 HTML 和 A2UI。
## 组件和流程
### Gateway网关（守护进程）
### Gateway 网关（守护进程）
- 维护提供商连接。
- 暴露类型化的 WS API（请求、响应、服务端推送事件）。
- 暴露类型化的 WS API（请求、响应、服务器推送事件）。
- 根据 JSON Schema 验证入站帧。
- 发出 `agent`、`chat`、`presence`、`health`、`heartbeat`、`cron` 等事件。
- 发出事件如 `agent`、`chat`、`presence`、`health`、`heartbeat`、`cron`。
### 客户端（Mac 应用 / CLI / Web 管理端）
### 客户端（mac 应用 / CLI / web 管理）
- 每个客户端一个 WS 连接。
- 发送请求（`health`、`status`、`send`、`agent`、`system-presence`）。
- 订阅事件（`tick`、`agent`、`presence`、`shutdown`）。
### 节点（macOS / iOS / Android / 无头模式）
### 节点（macOS / iOS / Android / 无头设备）
- 连接到**同一个 WS 服务器**，声明 `role: node`。
- 在 `connect` 中提供设备身份；配对是**基于设备**的（角色为 `node`），审批信息存储在设备配对存储中。
- 暴露 `canvas.*`、`camera.*`、`screen.record`、`location.get` 等命令。
- 以 `role: node` 连接到**同一个 WS 服务器**。
- 在 `connect` 中提供设备身份；配对是**基于设备**的（角色为 `node`），批准存储在设备配对存储中。
- 暴露命令如 `canvas.*`、`camera.*`、`screen.record`、`location.get`。
协议详情：
- [Gateway网关协议](/gateway/protocol)
- [Gateway 网关协议](/gateway/protocol)
### WebChat
- 静态 UI，使用 Gateway网关 WS API 获取聊天历史和发送消息。
- 静态界面，使用 Gateway 网关 WS API 获取聊天历史和发送消息。
- 在远程设置中，通过与其他客户端相同的 SSH/Tailscale 隧道连接。
## 连接生命周期（单个客户端）
```
Client Gateway网关
Client Gateway
| |
|---- req:connect -------->|
|<------ res (ok) ---------| （或 res error + 关闭）
| （payload=hello-ok 携带快照：presence + health）
|<------ res (ok) ---------| (or res error + close)
| (payload=hello-ok carries snapshot: presence + health)
| |
|<------ event:presence ---|
|<------ event:tick -------|
| |
|------- req:agent ------->|
|<------ res:agent --------| （确认：{runId,status:"accepted"}）
|<------ event:agent ------| （流式传输）
|<------ res:agent --------| （最终：{runId,status,summary}）
|<------ res:agent --------| (ack: {runId,status:"accepted"})
|<------ event:agent ------| (streaming)
|<------ res:agent --------| (final: {runId,status,summary})
| |
```
## 线路协议（摘要）
- 传输层：WebSocket，文本帧携带 JSON 负载。
- 传输：WebSocket，带 JSON 载荷的文本帧。
- 第一帧**必须**是 `connect`。
- 握手完成后：
- 握手后：
- 请求：`{type:"req", id, method, params}` → `{type:"res", id, ok, payload|error}`
- 事件：`{type:"event", event, payload, seq?, stateVersion?}`
- 如果设置了 `OPENCLAW_GATEWAY_TOKEN`（或 `--token`），`connect.params.auth.token` 必须匹配，否则套接字将关闭。
- 有副作用的方法（`send`、`agent`）需要幂等性键以安全重试；服务器维护一个短期去重缓存。
- 如果设置了 `OPENCLAW_GATEWAY_TOKEN`（或 `--token`），`connect.params.auth.token` 必须匹配，否则套接字关闭。
- 有副作用的方法（`send`、`agent`）需要幂等键以安全重试；服务器保持短期去重缓存。
- 节点必须在 `connect` 中包含 `role: "node"` 以及能力/命令/权限。
## 配对与本地信任
## 配对 + 本地信任
- 所有 WS 客户端（操作员 + 节点）在 `connect` 时包含**设备身份**。
- 新设备 ID 需要配对审批；Gateway网关颁发**设备令牌**用于后续连接。
- **本地**连接（local loopback 或 Gateway网关主机自身的 tailnet 地址）可以自动审批，以保持同主机用户体验的流畅性。
- **非本地**连接必须对 `connect.challenge` nonce 签名，并需要显式审批。
- Gateway网关认证（`gateway.auth.*`）仍适用于**所有**连接，无论本地还是远程。
- 新设备 ID 需要配对批准；Gateway 网关为后续连接颁发**设备令牌**。
- **本地**连接（loopback 或 Gateway 网关主机自身的 tailnet 地址）可以自动批准以保持同主机用户体验流畅。
- **非本地**连接必须签名 `connect.challenge` nonce 并需要明确批准。
- Gateway 网关认证（`gateway.auth.*`）仍适用于**所有**连接，无论本地还是远程。
详情：[Gateway网关协议](/gateway/protocol)、[配对](/start/pairing)、[安全](/gateway/security)。
详情：[Gateway 网关协议](/gateway/protocol)、[配对](/start/pairing)、[安全](/gateway/security)。
## 协议类型定义与代码生成
## 协议类型和代码生成
- TypeBox schema 定义协议。
- 从这些 schema 生成 JSON Schema。
- TypeBox 模式定义协议。
- 从这些模式生成 JSON Schema。
- 从 JSON Schema 生成 Swift 模型。
## 远程访问
- 推荐方式：Tailscale 或 VPN。
- 备选方式：SSH 隧道
- 推荐：Tailscale 或 VPN。
- 替代方案：SSH 隧道
```bash
ssh -N -L 18789:127.0.0.1:18789 user@host
```
- 相同的握手 + 认证令牌适用于隧道连接。
- 远程设置中可为 WS 启用 TLS + 可选的证书固定。
- 远程设置中可以为 WS 启用 TLS + 可选的证书固定。
## 运维概览
## 操作快照
- 启动：`openclaw gateway`（前台运行，日志输出到 stdout）。
- 健康检查：通过 WS 发送 `health`（也包含在 `hello-ok` 中）。
- 监管：使用 launchd/systemd 实现自动重启。
- 启动：`openclaw gateway`（前台，日志输出到 stdout）。
- 健康检查：通过 WS 的 `health`（也包含在 `hello-ok` 中）。
- 监控：使用 launchd/systemd 自动重启。
## 不变量
- 每台主机恰好一个 Gateway网关控制单个 Baileys 会话。
- 握手是强制的；任何非 JSON 或非 connect 的首帧将导致硬关闭。
- 每台主机恰好一个 Gateway 网关控制单个 Baileys 会话。
- 握手是强制的；任何非 JSON 或非 connect 的第一帧都会导致硬关闭。
- 事件不会重放；客户端必须在出现间隙时刷新。

94
docs/zh-CN/concepts/context.md
View File

@@ -1,40 +1,40 @@
---
read_when:
- 你想了解 OpenClaw 中"上下文"的含义
- 你在调试为什么模型"知道"某些内容（或遗忘了它）
- 你在调试为什么模型"知道"某些内容（或忘记了）
- 你想减少上下文开销（/context、/status、/compact）
summary: 上下文：模型看到的内容、如何构建以及如何检查
title: 上下文
x-i18n:
generated_at: "2026-02-01T20:22:35Z"
generated_at: "2026-02-03T07:46:15Z"
model: claude-opus-4-5
provider: pi
source_hash: b32867b9b93254fdd1077d0d97c203cabfdba3330bb941693c83feba8e5db0cc
source_path: concepts/context.md
workflow: 14
workflow: 15
---
# 上下文
"上下文"是 **OpenClaw 在一次运行中发送给模型的所有内容**。它受模型的**上下文窗口**（token 限制）约束。
初学者心智模型：
新手心智模型：
- **系统提示词**（由 OpenClaw 构建）：规则、工具、Skills 列表、时间/运行时信息，以及注入的工作区文件。
- **对话历史**：你的消息 + 助手在本次会话中的消息。
- **系统提示词**（OpenClaw 构建）：规则、工具、Skills 列表、时间/运行时，以及注入的工作区文件。
- **对话历史**：你的消息 + 助手在此会话中的消息。
- **工具调用/结果 + 附件**：命令输出、文件读取、图片/音频等。
上下文与"记忆"_不是同一回事_：记忆可以存储在磁盘上并在之后重新加载；上下文是当前模型窗口内的内容。
上下文与"记忆"_不是同一回事_：记忆可以存储在磁盘上并稍后重新加载；上下文是模型当前窗口内的内容。
## 快速开始（检查上下文）
- `/status` → 快速查看"我的窗口还剩多少空间？"以及会话设置。
- `/context list` → 查看注入了哪些内容及大致大小（按文件和总计）。
- `/context detail` → 更深入的分解：按文件、按工具 schema 大小、按 Skills 条目大小，以及系统提示词大小。
- `/usage tokens` → 在正常回复后附加每次回复的用量信息。
- `/compact` → 将较早的历史记录总结为一个压缩条目，以释放窗口空间。
- `/status` → 快速查看"我的窗口有多满？" + 会话设置。
- `/context list` → 注入了什么 + 大致大小（每个文件 + 总计）。
- `/context detail` → 更深入的分解：每个文件、每个工具 schema 大小、每个 Skills 条目大小和系统提示词大小。
- `/usage tokens` → 在正常回复后附加每次回复的使用量页脚。
- `/compact` → 将较旧的历史总结为紧凑条目以释放窗口空间。
另请参阅：[斜杠命令](/tools/slash-commands)、[Token 用量与费用](/token-use)、[压缩](/concepts/compaction)。
另请参阅：[斜杠命令](/tools/slash-commands)、[Token 使用与成本](/token-use)、[压缩](/concepts/compaction)。
## 示例输出
@@ -83,33 +83,33 @@ Top tools (schema size):
… (+N more tools)
```
## 哪些内容计入上下文窗口
## 什么计入上下文窗口
模型接收到的所有内容都会计入，包括：
模型接收的所有内容都计入，包括：
- 系统提示词（所有部分）。
- 对话历史。
- 工具调用 + 工具结果。
- 附件/转录内容（图片/音频/文件）。
- 附件/转录（图片/音频/文件）。
- 压缩摘要和修剪产物。
- 提供商的"包装器"或隐藏头信息（不可见，但仍会计入）。
- 提供商"包装器"或隐藏头部（不可见，仍然计数）。
## OpenClaw 如何构建系统提示词
系统提示词由 **OpenClaw 拥有**，每次运行时重新构建。它包括：
系统提示词由 **OpenClaw 拥有**，每次运行时重建。它包括：
- 工具列表 + 简短描述。
- Skills 列表（仅元数据；见下文）。
- 工作区位置。
- 时间（UTC + 如已配置则转换为用户时间）。
- 运行时元数据（主机/操作系统/模型/思考模式）。
- 在 **Project Context** 下注入的工作区引导文件。
- 时间（UTC + 如果配置了则转换为用户时间）。
- 运行时元数据（主机/操作系统/模型/思考）。
- 在**项目上下文**下注入的工作区引导文件。
完整分解：[系统提示词](/concepts/system-prompt)。
## 注入的工作区文件（Project Context）
## 注入的工作区文件（项目上下文）
默认情况下，OpenClaw 会注入一组固定的工作区文件（如果存在）：
默认情况下，OpenClaw 注入一组固定的工作区文件（如果存在）：
- `AGENTS.md`
- `SOUL.md`
@@ -119,50 +119,50 @@ Top tools (schema size):
- `HEARTBEAT.md`
- `BOOTSTRAP.md`（仅首次运行）
大文件会按 `agents.defaults.bootstrapMaxChars`（默认 `20000` 字符）逐文件截断。`/context` 会显示**原始大小与注入大小**的对比，以及是否发生了截断。
大文件按文件使用 `agents.defaults.bootstrapMaxChars`（默认 `20000` 字符）截断。`/context` 显示**原始 vs 注入**大小以及是否发生了截断。
## Skills：注入的内容与按需加载的内容
## Skills：注入的内容 vs 按需加载的内容
系统提示词中包含一个紧凑的**Skills 列表**（名称 + 描述 + 位置）。此列表会产生实际开销。
系统提示词包含一个紧凑的 **Skills 列表**（名称 + 描述 + 位置）。此列表有实际开销。
Skills 指令默认*不会*包含在内。模型应在**需要时**才 `read` Skills 的 `SKILL.md`。
Skill 指令默认*不*包含。模型应该**仅在需要时**`read` Skill 的 `SKILL.md`。
## 工具：两种开销
## 工具：有两种成本
工具以两种方式影响上下文：
1. 系统提示词中的**工具列表文本**（即你看到的"Tooling"部分）。
2. **工具 schema**（JSON）。这些会发送给模型以便其调用工具。即使你看不到它们的纯文本形式，它们也会计入上下文。
1. 系统提示词中的**工具列表文本**（你看到的"Tooling"）。
2. **工具 schema**（JSON）。这些发送给模型以便它可以调用工具。它们计入上下文，即使你看不到它们作为纯文本。
`/context detail` 会分解最大的工具 schema，让你了解哪些占用最多。
`/context detail` 分解最大的工具 schema，以便你可以看到什么占主导。
## 命令、指令和"内联快捷方式"
斜杠命令由 Gateway网关处理。有几种不同的行为：
斜杠命令由 Gateway 网关处理。有几种不同的行为：
- **独立命令**：仅包含 `/...` 的消息作为命令运行。
- **指令**：`/think`、`/verbose`、`/reasoning`、`/elevated`、`/model`、`/queue` 会在模型看到消息之前被移除。
- 仅含指令的消息会持久化会话设置。
- 普通消息中的内联指令作为单次消息提示生效。
- **内联快捷方式**（仅限白名单发送者）：普通消息中的某些 `/...` 标记可以立即执行（例如："hey /status"），并在模型看到剩余文本之前被移除。
- **独立命令**：仅为 `/...` 的消息作为命令运行。
- **指令**：`/think`、`/verbose`、`/reasoning`、`/elevated`、`/model`、`/queue` 在模型看到消息之前被剥离。
- 仅指令消息会持久化会话设置。
- 正常消息中的内联指令作为每条消息的提示。
- **内联快捷方式**（仅允许列表中的发送者）：正常消息中的某些 `/...` token 可以立即运行（例如："hey /status"），并在模型看到剩余文本之前被剥离。
详情：[斜杠命令](/tools/slash-commands)。
## 会话、压缩和修剪（哪些内容会持久化）
## 会话、压缩和修剪（什么会持久化）
跨消息持久化的内容取决于机制：
什么在消息之间持久化取决于机制：
- **普通历史**会持久化在会话转录中，直到被策略压缩/修剪。
- **压缩**会将摘要持久化到转录中，并保留最近的消息不变。
- **修剪**会从运行的*内存中*提示词里移除旧的工具结果，但不会重写转录。
- **正常历史**在会话记录中持久化，直到被策略压缩/修剪。
- **压缩**将摘要持久化到记录中，并保持最近的消息不变。
- **修剪**从运行的*内存中*提示词中删除旧的工具结果，但不重写记录。
文档：[会话](/concepts/session)、[压缩](/concepts/compaction)、[会话修剪](/concepts/session-pruning)。
## `/context` 实际报告的内容
## `/context` 实际报告什么
`/context` 优先使用最新的**运行时构建的**系统提示词报告（如果可用）：
`/context` 在可用时优先使用最新的**运行构建的**系统提示词报告：
- `System prompt (run)` = 从上一次嵌入式（具有工具能力的）运行中捕获，并持久化在会话存储中。
- `System prompt (estimate)` = 当不存在运行报告时（或通过不生成该报告的 CLI 后端运行时）即时计算。
- `System prompt (run)` = 从最后一次嵌入式（具有工具能力的）运行中捕获，并持久化在会话存储中。
- `System prompt (estimate)` = 当没有运行报告存在时（或通过不生成报告的 CLI 后端运行时）即时计算。
无论哪种方式，它都会报告大小和主要贡献者；它**不会**输出完整的系统提示词或工具 schema。
无论哪种方式，它都报告大小和主要贡献者；它**不会**转储完整的系统提示词或工具 schema。

56
docs/zh-CN/concepts/group-messages.md
View File

@@ -1,36 +1,36 @@
---
read_when:
- 更改群组消息规则或提及方式时
summary: WhatsApp 群组消息处理的行为与配置（mentionPatterns 在各平台间共享）
- 更改群组消息规则或提及设置时
summary: WhatsApp 群组消息处理的行为和配置（mentionPatterns 在各平台间共享）
title: 群组消息
x-i18n:
generated_at: "2026-02-01T20:22:33Z"
generated_at: "2026-02-03T10:05:00Z"
model: claude-opus-4-5
provider: pi
source_hash: 181a72f12f5021af77c2e4c913120f711e0c0bc271d218d75cb6fe80dab675bb
source_path: concepts/group-messages.md
workflow: 14
workflow: 15
---
# 群组消息（WhatsApp 网页渠道）
目标：让 Clawd 驻留在 WhatsApp 群组中，仅在被提及时唤醒，并将该线程与个人私聊会话隔离。
目标：让 Clawd 留在 WhatsApp 群组中，仅在被提及时唤醒，并将该对话线程与个人私信会话分开。
注意：`agents.list[].groupChat.mentionPatterns` 现在也被 Telegram/Discord/Slack/iMessage 使用；本文档重点介绍 WhatsApp 特定的行为。对于多智能体配置，请为每个智能体设置 `agents.list[].groupChat.mentionPatterns`（或使用 `messages.groupChat.mentionPatterns` 作为全局回退）。
注意：`agents.list[].groupChat.mentionPatterns` 现在也被 Telegram/Discord/Slack/iMessage 使用；本文档重点介绍 WhatsApp 特定的行为。对于多智能体设置，为每个智能体设置 `agents.list[].groupChat.mentionPatterns`（或使用 `messages.groupChat.mentionPatterns` 作为全局回退）。
## 已实现的功能（2025-12-03）
- 激活模式：`mention`（默认）或 `always`。`mention` 需要一次提及（通过 `mentionedJids` 实现的 WhatsApp 原生 @提及、正则匹配，或消息文本中包含机器人的 E.164 号码）。`always` 会在每条消息时唤醒智能体，但智能体仅在能提供有价值的回复时才会响应；否则返回静默令牌 `NO_REPLY`。默认值可在配置中设置（`channels.whatsapp.groups`），也可通过 `/activation` 按群组覆盖。设置 `channels.whatsapp.groups` 后，它同时充当群组白名单（添加 `"*"` 以允许所有群组）。
- 群组策略：`channels.whatsapp.groupPolicy` 控制是否接受群组消息（`open|disabled|allowlist`）。`allowlist` 使用 `channels.whatsapp.groupAllowFrom`（回退：显式的 `channels.whatsapp.allowFrom`）。默认为 `allowlist`（在添加发送者之前将被阻止）。
- 按群组隔离会话：会话键格式为 `agent:<agentId>:whatsapp:group:<jid>`，因此 `/verbose on` 或 `/think high` 等命令（作为独立消息发送）仅作用于该群组；个人私聊状态不受影响。群组线程会跳过心跳。
- 上下文注入：**仅待处理的**群组消息（默认 50 条）——即未触发运行的消息——会以 `[Chat messages since your last reply - for context]` 为前缀注入，触发消息则以 `[Current message - respond to this]` 为前缀。已在会话中的消息不会被重复注入。
- 发送者标识：每个群组消息批次末尾会附加 `[from: Sender Name (+E164)]`，以便 Pi 知道发言者是谁。
- 阅后即焚/一次性查看消息：我们在提取文本/提及之前先解包这些消息，因此其中的提及仍然会触发。
- 群组系统提示词：在群组会话的第一轮（以及每次通过 `/activation` 更改模式时），我们会在系统提示词中注入一段简短说明，例如 `You are replying inside the WhatsApp group "<subject>". Group members: Alice (+44...), Bob (+43...), … Activation: trigger-only … Address the specific sender noted in the message context.` 如果元数据不可用，我们仍然会告知智能体这是一个群聊。
- 激活模式：`mention`（默认）或 `always`。`mention` 需要被提及（通过 `mentionedJids` 的真实 WhatsApp @提及、正则表达式模式，或文本中任意位置的机器人 E.164 号码）。`always` 会在每条消息时唤醒智能体，但它应该只在能提供有意义价值时才回复；否则返回静默令牌 `NO_REPLY`。默认值可在配置中设置（`channels.whatsapp.groups`），并可通过 `/activation` 为每个群组单独覆盖。当设置了 `channels.whatsapp.groups` 时，它同时充当群组允许列表（包含 `"*"` 以允许所有群组）。
- 群组策略：`channels.whatsapp.groupPolicy` 控制是否接受群组消息（`open|disabled|allowlist`）。`allowlist` 使用 `channels.whatsapp.groupAllowFrom`（回退：显式的 `channels.whatsapp.allowFrom`）。默认为 `allowlist`（在你添加发送者之前被阻止）。
- 独立群组会话：会话键格式为 `agent:<agentId>:whatsapp:group:<jid>`，因此 `/verbose on` 或 `/think high`（作为独立消息发送）等命令仅作用于该群组；个人私信状态不受影响。群组线程会跳过心跳。
- 上下文注入：**仅待处理**的群组消息（默认 50 条），即*未*触发运行的消息，会以 `[Chat messages since your last reply - for context]` 为前缀注入，触发行在 `[Current message - respond to this]` 下。已在会话中的消息不会重复注入。
- 发送者显示：每个群组批次现在以 `[from: Sender Name (+E164)]` 结尾，让 Pi 知道是谁在说话。
- 阅后即焚/一次性查看：我们在提取文本/提及之前会先解包这些消息，因此其中的提及仍会触发。
- 群组系统提示：在群组会话的第一轮（以及每当 `/activation` 更改模式时），我们会向系统提示注入一段简短说明，如 `You are replying inside the WhatsApp group "<subject>". Group members: Alice (+44...), Bob (+43...), … Activation: trigger-only … Address the specific sender noted in the message context.` 如果元数据不可用，我们仍会告知智能体这是一个群聊。
## 配置示例（WhatsApp）
在 `~/.openclaw/openclaw.json` 中添加 `groupChat` 块，以便在 WhatsApp 去除文本正文中可见的 `@` 时，显示名称提及仍然有效：
在 `~/.openclaw/openclaw.json` 中添加 `groupChat` 块，以便在 WhatsApp 剥离文本正文中的可视 `@` 时，显示名称提及仍能正常工作：
```json5
{
@@ -55,37 +55,37 @@ x-i18n:
}
```
说明：
注意：
- 正则表达式不区分大小写；它们涵盖了 `@openclaw` 这样的显示名称提及，以及带或不带 `+`/空格的原始号码。
- 当用户点击联系人时，WhatsApp 仍会通过 `mentionedJids` 发送规范提及，因此号码回退方式很少需要，但作为安全保障很有用。
- 正则表达式不区分大小写；它们涵盖了像 `@openclaw` 这样的显示名称提及，以及带或不带 `+`/空格的原始号码。
- 当有人点击联系人时，WhatsApp 仍会通过 `mentionedJids` 发送规范的提及，因此号码回退很少需要，但作为安全网很有用。
### 激活命令（仅限所有者）
### 激活命令（仅所有者）
使用群聊命令：
- `/activation mention`
- `/activation always`
只有所有者号码（来自 `channels.whatsapp.allowFrom`，未设置时使用机器人自身的 E.164 号码）可以更改此设置。在群组中发送 `/status` 作为独立消息即可查看当前激活模式。
只有所有者号码（来自 `channels.whatsapp.allowFrom`，或未设置时使用机器人自己的 E.164）可以更改此设置。在群组中发送 `/status` 作为独立消息以查看当前激活模式。
## 使用方法
1. 将你的 WhatsApp 账号（运行 OpenClaw 的账号）添加到群组。
2. 发送 `@openclaw …`（或包含号码）。除非设置了 `groupPolicy: "open"`，否则只有白名单中的发送者才能触发。
3. 智能体提示词将包含最近的群组上下文以及末尾的 `[from: …]` 标记，以便它能回复正确的人。
4. 会话级指令（`/verbose on`、`/think high`、`/new` 或 `/reset`、`/compact`）仅适用于该群组的会话；请将它们作为独立消息发送以确保生效。你的个人私聊会话保持独立。
2. 说 `@openclaw …`（或包含号码）。只有允许列表中的发送者才能触发，除非你设置 `groupPolicy: "open"`。
3. 智能体提示将包含最近的群组上下文以及尾部的 `[from: …]` 标记，以便它能够回应正确的人。
4. 会话级指令（`/verbose on`、`/think high`、`/new` 或 `/reset`、`/compact`）仅适用于该群组的会话；将它们作为独立消息发送以使其生效。你的个人私信会话保持独立。
## 测试 / 验证
## 测试/验证
- 手动冒烟测试：
- 在群组中发送 `@openclaw` 提及，确认回复中引用了发送者名称。
- 再次发送提及，验证历史消息块已包含并在下一轮清除。
- 检查 Gateway网关日志（使用 `--verbose` 运行）查看 `inbound web message` 条目，确认其显示 `from: <groupJid>` 和 `[from: …]` 后缀。
- 在群组中发送 `@openclaw` 提及，确认收到引用发送者名称的回复。
- 发送第二次提及，验证历史记录块被包含，然后在下一轮清除。
- 检查 Gateway 网关日志（使用 `--verbose` 运行）以查看 `inbound web message` 条目，显示 `from: <groupJid>` 和 `[from: …]` 后缀。
## 已知注意事项
- 群组有意跳过心跳以避免嘈杂的广播。
- 回声抑制使用组合的批次字符串；如果你在没有提及的情况下发送两次相同文本，只有第一次会收到响应。
- 会话存储条目将以 `agent:<agentId>:whatsapp:group:<jid>` 的形式出现在会话存储中（默认为 `~/.openclaw/agents/<agentId>/sessions/sessions.json`）；缺少条目仅表示该群组尚未触发过运行。
- 回声抑制使用组合的批次字符串；如果你发送两次相同的文本但没有提及，只有第一次会得到响应。
- 会话存储条目将在会话存储中显示为 `agent:<agentId>:whatsapp:group:<jid>`（默认为 `~/.openclaw/agents/<agentId>/sessions/sessions.json`）；缺失条目只是意味着该群组尚未触发运行。
- 群组中的输入指示器遵循 `agents.defaults.typingMode`（默认：未被提及时为 `message`）。

147
docs/zh-CN/concepts/groups.md
View File

@@ -1,54 +1,53 @@
---
read_when:
- 更改群聊行为或提及门控
- 更改群聊行为或提及限制
summary: 跨平台的群聊行为（WhatsApp/Telegram/Discord/Slack/Signal/iMessage/Microsoft Teams）
title: 群组
x-i18n:
generated_at: "2026-02-01T20:23:08Z"
generated_at: "2026-02-03T07:47:08Z"
model: claude-opus-4-5
provider: pi
source_hash: b727a053edf51f6e7b5c0c324c2fc9c9789a9796c37f622418bd555e8b5a0ec4
source_path: concepts/groups.md
workflow: 14
workflow: 15
---
# 群组
OpenClaw 在各平台上统一处理群聊：WhatsApp、Telegram、Discord、Slack、Signal、iMessage、Microsoft Teams。
## 入门简介（2 分钟）
## 新手入门（2 分钟）
OpenClaw "运行"在你自己的消息账户上。没有单独的 WhatsApp 机器人用户。
如果**你**在某个群组中，OpenClaw 就能看到该群组并在其中回复。
OpenClaw"运行"在你自己的消息账户上。没有单独的 WhatsApp 机器人用户。如果**你**在一个群组中，OpenClaw 就可以看到该群组并在其中回复。
默认行为：
- 群组受限（`groupPolicy: "allowlist"`）。
- 除非你显式禁用提及门控，否则回复需要 @提及。
- 除非你明确禁用提及限制，否则回复需要 @ 提及。
含义：允许列表中的发送者可以通过提及 OpenClaw 来触发它。
解释：允许列表中的发送者可以通过提及来触发 OpenClaw。
> 简而言之
>
> - **私聊访问**由 `*.allowFrom` 控制。
> - **私信访问**由 `*.allowFrom` 控制。
> - **群组访问**由 `*.groupPolicy` + 允许列表（`*.groups`、`*.groupAllowFrom`）控制。
> - **回复触发**由提及门控（`requireMention`、`/activation`）控制。
> - **回复触发**由提及限制（`requireMention`、`/activation`）控制。
快速流程（群消息的处理过程）：
快速流程（群消息会发生什么）：
```
groupPolicy? disabled -> drop
groupPolicy? allowlist -> group allowed? no -> drop
requireMention? yes -> mentioned? no -> store for context only
otherwise -> reply
groupPolicy? disabled -> 丢弃
groupPolicy? allowlist -> 群组允许? 否 -> 丢弃
requireMention? 是 -> 被提及? 否 -> 仅存储为上下文
否则 -> 回复
```
![群消息流程](/images/groups-flow.svg)
如果你想要...
| 目标 | 需要设置的内容 |
如果你想...
| 目标 | 设置什么 |
|------|-------------|
| 允许所有群组但仅在 @提及时回复 | `groups: { "*": { requireMention: true } }` |
| 允许所有群组但仅在 @ 提及时回复 | `groups: { "*": { requireMention: true } }` |
| 禁用所有群组回复 | `groupPolicy: "disabled"` |
| 仅特定群组 | `groups: { "<group-id>": { ... } }`（无 `"*"` 键） |
| 仅你可以在群组中触发 | `groupPolicy: "allowlist"`、`groupAllowFrom: ["+1555..."]` |
@@ -56,32 +55,32 @@ otherwise -> reply
## 会话键
- 群组会话使用 `agent:<agentId>:<channel>:group:<id>` 会话键（房间/频道使用 `agent:<agentId>:<channel>:channel:<id>`）。
- Telegram 论坛主题会在群组 ID 后追加 `:topic:<threadId>`，使每个主题拥有独立的会话。
- 私聊使用主会话（或按发送者分配，如已配置）。
- 群组会话跳过心跳检测。
- Telegram 论坛话题在群组 ID 后添加 `:topic:<threadId>`，因此每个话题都有自己的会话。
- 私聊使用主会话（或按发送者配置时使用各自的会话）。
- 群组会话跳过心跳。
## 模式：个人私聊 + 公开群组（单智能体）
## 模式：个人私信 + 公开群组（单智能体）
可以——如果你的"个人"流量是**私聊**，"公开"流量是**群组**，这种方式效果很好。
是的——如果你的"个人"流量是**私信**而"公开"流量是**群组**，这种方式效果很好。
原因：在单智能体模式下，私聊通常落在**主**会话键（`agent:main:main`）上，而群组始终使用**非主**会话键（`agent:main:<channel>:group:<id>`）。如果你启用沙箱并设置 `mode: "non-main"`，这些群组会话将在 Docker 中运行，而你的主私聊会话留在主机上。
原因：在单智能体模式下，私信通常落在**主**会话键（`agent:main:main`）中，而群组始终使用**非主**会话键（`agent:main:<channel>:group:<id>`）。如果你启用 `mode: "non-main"` 的沙箱隔离，这些群组会话在 Docker 中运行，而你的主私信会话保持在主机上。
这为你提供了一个智能体"大脑"（共享工作区 + 记忆），但有两种执行姿态：
这给你一个智能体"大脑"（共享工作区 + 记忆），但两种执行姿态：
- **私聊**：完整工具（主机）
- **私信**：完整工具（主机）
- **群组**：沙箱 + 受限工具（Docker）
> 如果你需要真正独立的工作区/角色（"个人"和"公开"绝不能混合），请使用第二个智能体 + 绑定。参见[多智能体路由](/concepts/multi-agent)。
示例（私聊在主机上，群组沙箱隔离 + 仅消息工具）：
示例（私信在主机上，群组沙箱隔离 + 仅消息工具）：
```json5
{
agents: {
defaults: {
sandbox: {
mode: "non-main", // groups/channels are non-main -> sandboxed
scope: "session", // strongest isolation (one container per group/channel)
mode: "non-main", // 群组/频道是非主 -> 沙箱隔离
scope: "session", // 最强隔离（每个群组/频道一个容器）
workspaceAccess: "none",
},
},
@@ -89,7 +88,7 @@ otherwise -> reply
tools: {
sandbox: {
tools: {
// If allow is non-empty, everything else is blocked (deny still wins).
// 如果 allow 非空，其他所有工具都被阻止（deny 仍然优先）。
allow: ["group:messaging", "group:sessions"],
deny: ["group:runtime", "group:fs", "group:ui", "nodes", "cron", "gateway"],
},
@@ -98,7 +97,7 @@ otherwise -> reply
}
```
想要"群组只能访问文件夹 X"而不是"无主机访问"？保持 `workspaceAccess: "none"` 并仅将允许的路径挂载到沙箱中：
想要"群组只能看到文件夹 X"而不是"无主机访问"？保持 `workspaceAccess: "none"` 并仅将允许的路径挂载到沙箱中：
```json5
{
@@ -120,20 +119,20 @@ otherwise -> reply
}
```
相关内容：
相关：
- 配置键和默认值：[Gateway网关配置](/gateway/configuration#agentsdefaultssandbox)
- 调试工具被阻止的原因：[沙箱 vs 工具策略 vs 提权](/gateway/sandbox-vs-tool-policy-vs-elevated)
- 配置键和默认值：[Gateway 网关配置](/gateway/configuration#agentsdefaultssandbox)
- 调试为什么工具被阻止：[沙箱 vs 工具策略 vs 提权](/gateway/sandbox-vs-tool-policy-vs-elevated)
- 绑定挂载详情：[沙箱隔离](/gateway/sandboxing#custom-bind-mounts)
## 显示标签
- UI 标签在可用时使用 `displayName`，格式为 `<channel>:<token>`。
- `#room` 保留给房间/频道；群聊使用 `g-<slug>`（小写，空格转为 `-`，保留 `#@+._-`）。
- `#room` 保留用于房间/频道；群聊使用 `g-<slug>`（小写，空格 -> `-`，保留 `#@+._-`）。
## 群组策略
按渠道控制群组/房间消息的处理方式：
控制每个渠道如何处理群组/房间消息：
```json5
{
@@ -180,34 +179,34 @@ otherwise -> reply
}
```
| 策略 | 行为 |
| ------------- | ------------------------------------- |
| `"open"` | 群组绕过允许列表；提及门控仍然适用。 |
| `"disabled"` | 完全阻止所有群组消息。 |
| `"allowlist"` | 仅允许匹配已配置允许列表的群组/房间。 |
| 策略 | 行为 |
| ------------- | --------------------------------------- |
| `"open"` | 群组绕过允许列表；提及限制仍然适用。 |
| `"disabled"` | 完全阻止所有群组消息。 |
| `"allowlist"` | 仅允许与配置的允许列表匹配的群组/房间。 |
注意事项：
- `groupPolicy` 与提及门控（要求 @提及）是分开的。
- `groupPolicy` 与提及限制（需要 @ 提及）是分开的。
- WhatsApp/Telegram/Signal/iMessage/Microsoft Teams：使用 `groupAllowFrom`（回退：显式 `allowFrom`）。
- Discord：允许列表使用 `channels.discord.guilds.<id>.channels`。
- Slack：允许列表使用 `channels.slack.channels`。
- Matrix：允许列表使用 `channels.matrix.groups`（房间 ID、别名或名称）。使用 `channels.matrix.groupAllowFrom` 限制发送者；也支持按房间的 `users` 允许列表。
- 群组私聊单独控制（`channels.discord.dm.*`、`channels.slack.dm.*`）。
- Matrix：允许列表使用 `channels.matrix.groups`（房间 ID、别名或名称）。使用 `channels.matrix.groupAllowFrom` 限制发送者；也支持每个房间的 `users` 允许列表。
- 群组私信单独控制（`channels.discord.dm.*`、`channels.slack.dm.*`）。
- Telegram 允许列表可以匹配用户 ID（`"123456789"`、`"telegram:123456789"`、`"tg:123456789"`）或用户名（`"@alice"` 或 `"alice"`）；前缀不区分大小写。
- 默认为 `groupPolicy: "allowlist"`；如果你的群组允许列表为空，群组消息将被阻止。
快速心智模型（群消息的评估顺序）：
快速心智模型（群组消息的评估顺序）：
1. `groupPolicy`（open/disabled/allowlist）
2. 群组允许列表（`*.groups`、`*.groupAllowFrom`、渠道特定的允许列表）
3. 提及门控（`requireMention`、`/activation`）
2. 群组允许列表（`*.groups`、`*.groupAllowFrom`、渠道特定允许列表）
3. 提及限制（`requireMention`、`/activation`）
## 提及门控（默认）
## 提及限制（默认）
群消息需要提及才能触发，除非按群组覆盖。默认值位于 `*.groups."*"` 下的各子系统中。
群组消息需要提及，除非按群组覆盖。默认值位于 `*.groups."*"` 下的每个子系统中。
回复机器人消息视为隐式提及（当渠道支持回复元数据时）。这适用于 Telegram、WhatsApp、Slack、Discord 和 Microsoft Teams。
回复机器人消息被视为隐式提及（当渠道支持回复元数据时）。这适用于 Telegram、WhatsApp、Slack、Discord 和 Microsoft Teams。
```json5
{
@@ -248,18 +247,18 @@ otherwise -> reply
注意事项：
- `mentionPatterns` 是不区分大小写的正则表达式。
- 提供原生提及的平台仍然通过；模式匹配是备用方案。
- 按智能体覆盖：`agents.list[].groupChat.mentionPatterns`（多个智能体共享一个群组时很有用）。
- 提及门控仅在可以检测提及时生效（原生提及或已配置 `mentionPatterns`）。
- Discord 默认值位于 `channels.discord.guilds."*"` 中（可按服务器/频道覆盖）。
- 群组历史上下文在各渠道中统一包装，且为**仅待处理**（因提及门控跳过的消息）；使用 `messages.groupChat.historyLimit` 设置全局默认值，使用 `channels.<channel>.historyLimit`（或 `channels.<channel>.accounts.*.historyLimit`）进行覆盖。设为 `0` 以禁用。
- 提供显式提及的平台仍然通过；模式是回退。
- 每个智能体覆盖：`agents.list[].groupChat.mentionPatterns`（当多个智能体共享一个群组时有用）。
- 提及限制仅在提及检测可行时强制执行（原生提及或 `mentionPatterns` 已配置）。
- Discord 默认值位于 `channels.discord.guilds."*"`（可按服务器/频道覆盖）。
- 群组历史上下文在渠道间统一包装，并且是**仅待处理**（由于提及限制而跳过的消息）；使用 `messages.groupChat.historyLimit` 作为全局默认值，使用 `channels.<channel>.historyLimit`（或 `channels.<channel>.accounts.*.historyLimit`）进行覆盖。设置 `0` 以禁用。
## 群组/频道工具限制（可选）
某些渠道配置支持限制**特定群组/房间/频道内**可用的工具。
- `tools`：为整个群组允许/拒绝工具。
- `toolsBySender`：群组内按发送者覆盖（键为发送者 ID/用户名/邮箱/电话号码，取决于渠道）。使用 `"*"` 作为通配符。
- `toolsBySender`：群组内的按发送者覆盖（键是发送者 ID/用户名/邮箱/电话号码，取决于渠道）。使用 `"*"` 作为通配符。
解析顺序（最具体的优先）：
@@ -290,14 +289,14 @@ otherwise -> reply
注意事项：
- 群组/频道工具限制在全局/智能体工具策略之上额外应用（拒绝仍然优先）。
- 某些渠道对房间/频道使用不同的嵌套结构（例如 Discord `guilds.*.channels.*`、Slack `channels.*`、Microsoft Teams `teams.*.channels.*`）。
- 群组/频道工具限制在全局/智能体工具策略之外额外应用（deny 仍然优先）。
- 某些渠道对房间/频道使用不同的嵌套结构（例如，Discord `guilds.*.channels.*`、Slack `channels.*`、MS Teams `teams.*.channels.*`）。
## 群组允许列表
当配置了 `channels.whatsapp.groups`、`channels.telegram.groups` 或 `channels.imessage.groups` 时，键充当群组允许列表。使用 `"*"` 允许所有群组，同时仍可设置默认提及行为。
当配置了 `channels.whatsapp.groups`、`channels.telegram.groups` 或 `channels.imessage.groups` 时，键作为群组允许列表。使用 `"*"` 允许所有群组，同时仍设置默认提及行为。
常见意图（可直接复制粘贴）：
常见意图（复制/粘贴）：
1. 禁用所有群组回复
@@ -322,7 +321,7 @@ otherwise -> reply
}
```
3. 允许所有群组但要求提及（显式）
3. 允许所有群组但需要提及（显式）
```json5
{
@@ -350,31 +349,31 @@ otherwise -> reply
## 激活（仅所有者）
群组所有者可以切换按群组的激活方式：
群组所有者可以切换每个群组的激活状态：
- `/activation mention`
- `/activation always`
所有者由 `channels.whatsapp.allowFrom` 确定（未设置时使用机器人自身的 E.164 号码）。以独立消息发送该命令。其他平台目前忽略 `/activation`。
所有者由 `channels.whatsapp.allowFrom` 确定（未设置时为机器人自身的 E.164）。将命令作为独立消息发送。其他平台目前忽略 `/activation`。
## 上下文字段
群组入站消息负载设置：
群组入站负载设置：
- `ChatType=group`
- `GroupSubject`（如已知）
- `GroupMembers`（如已知）
- `WasMentioned`（提及门控结果）
- Telegram 论坛主题还包含 `MessageThreadId` 和 `IsForum`。
- `GroupSubject`（如果已知）
- `GroupMembers`（如果已知）
- `WasMentioned`（提及限制结果）
- Telegram 论坛话题还包括 `MessageThreadId` 和 `IsForum`。
智能体系统提示词在新群组会话的首轮包含群组简介。它提醒模型像人一样回复，避免 Markdown 表格，避免输入字面的 `\n` 序列。
智能体系统提示在新群组会话的第一轮包含群组介绍。它提醒模型像人类一样回复，避免 Markdown 表格，避免输入字面量 `\n` 序列。
## iMessage 特定说明
## iMessage 特定内容
- 路由或添加允许列表时优先使用 `chat_id:<id>`。
- 路由或允许列表时优先使用 `chat_id:<id>`。
- 列出聊天：`imsg chats --limit 20`。
- 群组回复始终返回到同一个 `chat_id`。
- 群组回复始终返回到相同的 `chat_id`。
## WhatsApp 特定说明
## WhatsApp 特定内容
有关 WhatsApp 专有行为（历史注入、提及处理详情），请参阅[群消息](/concepts/group-messages)。
参见[群消息](/concepts/group-messages)了解 WhatsApp 专有行为（历史注入、提及处理详情）。

171
docs/zh-CN/concepts/memory.md
View File

@@ -1,48 +1,48 @@
---
read_when:
- 想了解记忆文件布局和工作流程
- 想调整自动预压缩记忆刷写
summary: OpenClaw 记忆的工作原理（工作区文件 + 自动记忆刷写）
- 你想了解记忆文件布局和工作流程
- 你想调整自动压缩前的记忆刷新
summary: OpenClaw 记忆的工作原理（工作空间文件 + 自动记忆刷新）
title: 记忆
x-i18n:
generated_at: "2026-02-01T20:24:01Z"
generated_at: "2026-02-03T07:47:38Z"
model: claude-opus-4-5
provider: pi
source_hash: f3a7f5d9f61f9742eb3a8adbc3ccaddeadb7e48ceccdfb595327d6d1f55cd00e
source_path: concepts/memory.md
workflow: 14
workflow: 15
---
# 记忆
OpenClaw 的记忆是**智能体工作区中的纯 Markdown 文件**。这些文件是唯一的事实来源；模型只"记住"写入磁盘的内容。
OpenClaw 记忆是**智能体工作空间中的纯 Markdown 文件**。这些文件是唯一的事实来源；模型只"记住"写入磁盘的内容。
记忆搜索工具由活跃的记忆插件提供（默认：`memory-core`）。通过 `plugins.slots.memory = "none"` 可禁用记忆插件。
记忆搜索工具由活动的记忆插件提供（默认：`memory-core`）。使用 `plugins.slots.memory = "none"` 禁用记忆插件。
## 记忆文件（Markdown）
默认工作区布局使用两个记忆层：
默认工作空间布局使用两个记忆层：
- `memory/YYYY-MM-DD.md`
- 每日日志（仅追加）。
- 会话开始时读取今天和昨天的内容。
- 在会话开始时读取今天和昨天的内容。
- `MEMORY.md`（可选）
- 精心整理的长期记忆。
- **仅在主要的私人会话中加载**（不在群组上下文中加载）。
- **仅在主要的私人会话中加载**（绝不在群组上下文中加载）。
这些文件位于工作区目录下（`agents.defaults.workspace`，默认 `~/.openclaw/workspace`）。完整布局参见[智能体工作区](/concepts/agent-workspace)。
这些文件位于工作空间下（`agents.defaults.workspace`，默认 `~/.openclaw/workspace`）。完整布局参见[智能体工作空间](/concepts/agent-workspace)。
## 何时写入记忆
- 决策、偏好和持久性事实写入 `MEMORY.md`。
- 日常笔记和运行上下文写入 `memory/YYYY-MM-DD.md`。
- 如果有人说"记住这个"，就写下来（不要只保留在内存中）。
- 这个领域仍在发展中。提醒模型存储记忆会有帮助；它知道该怎么做。
- 如果你想让某些信息持久保留，**让机器人把它写入**记忆。
- 如果有人说"记住这个"，就写下来（不要只保存在内存中）。
- 这个领域仍在发展中。提醒模型存储记忆会有帮助；它会知道该怎么做。
- 如果你想让某些内容持久保存，**请要求机器人将其写入**记忆。
## 自动记忆刷写（预压缩 ping）
## 自动记忆刷新（压缩前触发）
当会话**接近自动压缩**时，OpenClaw 会触发一个**静默的智能体轮次**，提醒模型在上下文被压缩**之前**写入持久记忆。默认提示词明确表示模型*可以回复*，但通常 `NO_REPLY` 是正确的响应，这样用户不会看到这个轮次。
当会话**接近自动压缩**时，OpenClaw 会触发一个**静默的智能体回合**，提醒模型在上下文被压缩**之前**写入持久记忆。默认提示明确说明模型*可以回复*，但通常 `NO_REPLY` 是正确的响应，因此用户永远不会看到这个回合。
这由 `agents.defaults.compaction.memoryFlush` 控制：
@@ -66,35 +66,35 @@ OpenClaw 的记忆是**智能体工作区中的纯 Markdown 文件**。这些文
详情：
- **软阈值**：当会话 token 估计值超过 `contextWindow - reserveTokensFloor - softThresholdTokens` 时触发刷写。
- 默认**静默**：提示词包含 `NO_REPLY`，因此不会传递任何内容。
- **两个提示词**：一个用户提示词加一个系统提示词附加提醒。
- **每个压缩周期刷写一次**（在 `sessions.json` 中跟踪）。
- **工作区必须可写**：如果会话以 `workspaceAccess: "ro"` 或 `"none"` 在沙箱中运行，则跳过刷写。
- **软阈值**：当会话 token 估计超过 `contextWindow - reserveTokensFloor - softThresholdTokens` 时触发刷新。
- 默认**静默**：提示包含 `NO_REPLY`，因此不会发送任何内容。
- **两个提示**：一个用户提示加一个系统提示附加提醒。
- **每个压缩周期刷新一次**（在 `sessions.json` 中跟踪）。
- **工作空间必须可写**：如果会话以 `workspaceAccess: "ro"` 或 `"none"` 在沙箱中运行，则跳过刷新。
完整的压缩生命周期参见[会话管理 + 压缩](/reference/session-management-compaction)。
## 向量记忆搜索
OpenClaw 可以对 `MEMORY.md` 和 `memory/*.md`（以及你选择加入的任何额外目录或文件）构建小型向量索引，这样即使措辞不同，语义查询也能找到相关笔记。
OpenClaw 可以在 `MEMORY.md` 和 `memory/*.md`（以及你选择加入的任何额外目录或文件）上构建小型向量索引，以便语义查询可以找到相关笔记，即使措辞不同。
默认设置：
默认值：
- 默认启用。
- 监视记忆文件变更（带防抖）。
- 默认使用远程嵌入。如果未设置 `memorySearch.provider`，OpenClaw 会自动选择：
- 监视记忆文件的更改（去抖动）。
- 默认使用远程嵌入。如果未设置 `memorySearch.provider`，OpenClaw 自动选择：
1. 如果配置了 `memorySearch.local.modelPath` 且文件存在，则使用 `local`。
2. 如果可以解析到 OpenAI 密钥，则使用 `openai`。
3. 如果可以解析到 Gemini 密钥，则使用 `gemini`。
4. 否则记忆搜索保持禁用，直到完成配置。
2. 如果可以解析 OpenAI 密钥，则使用 `openai`。
3. 如果可以解析 Gemini 密钥，则使用 `gemini`。
4. 否则记忆搜索保持禁用状态直到配置完成。
- 本地模式使用 node-llama-cpp，可能需要运行 `pnpm approve-builds`。
- 使用 sqlite-vec（可用时）加速 SQLite 内的向量搜索。
- 使用 sqlite-vec（如果可用）在 SQLite 中加速向量搜索。
远程嵌入**需要**嵌入提供商的 API 密钥。OpenClaw 从认证配置文件、`models.providers.*.apiKey` 或环境变量中解析密钥。Codex OAuth 仅覆盖 chat/completions，**不满足**记忆搜索的嵌入需求。对于 Gemini，使用 `GEMINI_API_KEY` 或 `models.providers.google.apiKey`。使用自定义 OpenAI 兼容端点时，设置 `memorySearch.remote.apiKey`（以及可选的 `memorySearch.remote.headers`）。
远程嵌入**需要**嵌入提供商的 API 密钥。OpenClaw 从身份验证配置文件、`models.providers.*.apiKey` 或环境变量解析密钥。Codex OAuth 仅涵盖聊天/补全，**不**满足记忆搜索的嵌入需求。对于 Gemini，使用 `GEMINI_API_KEY` 或 `models.providers.google.apiKey`。使用自定义 OpenAI 兼容端点时，设置 `memorySearch.remote.apiKey`（以及可选的 `memorySearch.remote.headers`）。
### 额外记忆路径
如果你想索引默认工作区布局之外的 Markdown 文件，添加显式路径：
如果你想索引默认工作空间布局之外的 Markdown 文件，添加显式路径：
```json5
agents: {
@@ -106,12 +106,12 @@ agents: {
}
```
注意事项：
说明：
- 路径可以是绝对路径或工作区相对路径。
- 路径可以是绝对路径或工作空间相对路径。
- 目录会递归扫描 `.md` 文件。
- 仅索引 Markdown 文件。
- 符号链接会被忽略（文件或目录）。
- 符号链接被忽略（文件或目录）。
### Gemini 嵌入（原生）
@@ -131,13 +131,13 @@ agents: {
}
```
注意事项：
说明：
- `remote.baseUrl` 是可选的（默认为 Gemini API 基础 URL）。
- `remote.headers` 允许你在需要时添加额外的请求头。
- `remote.headers` 让你可以在需要时添加额外的标头。
- 默认模型：`gemini-embedding-001`。
如果你想使用**自定义 OpenAI 兼容端点**（OpenRouter、vLLM 或代理），可以在 OpenAI 提供商下使用 `remote` 配置：
如果你想使用**自定义 OpenAI 兼容端点**（OpenRouter、vLLM 或代理），可以使用 `remote` 配置与 OpenAI 提供商：
```json5
agents: {
@@ -157,23 +157,23 @@ agents: {
如果你不想设置 API 密钥，使用 `memorySearch.provider = "local"` 或设置 `memorySearch.fallback = "none"`。
回退策略：
回退：
- `memorySearch.fallback` 可以是 `openai`、`gemini`、`local` 或 `none`。
- 回退提供商仅在主嵌入提供商失败时使用。
批量索引（OpenAI + Gemini）：
- OpenAI 和 Gemini 嵌入默认启用批量索引。设置 `agents.defaults.memorySearch.remote.batch.enabled = false` 可禁用。
- 默认行为等待批量完成；如需调整，请调节 `remote.batch.wait`、`remote.batch.pollIntervalMs` 和 `remote.batch.timeoutMinutes`。
- 设置 `remote.batch.concurrency` 控制并行提交的批量作业数（默认：2）。
- 批量模式在 `memorySearch.provider = "openai"` 或 `"gemini"` 时适用，并使用相应的 API 密钥。
- Gemini 批量作业使用异步嵌入批量端点，需要 Gemini Batch API 可用。
- OpenAI 和 Gemini 嵌入默认启用。设置 `agents.defaults.memorySearch.remote.batch.enabled = false` 以禁用。
- 默认行为等待批处理完成；如果需要可以调整 `remote.batch.wait`、`remote.batch.pollIntervalMs` 和 `remote.batch.timeoutMinutes`。
- 设置 `remote.batch.concurrency` 以控制我们并行提交多少个批处理作业（默认：2）。
- 批处理模式在 `memorySearch.provider = "openai"` 或 `"gemini"` 时适用，并使用相应的 API 密钥。
- Gemini 批处理作业使用异步嵌入批处理端点，需要 Gemini Batch API 可用。
为什么 OpenAI 批量又快又便宜：
为什么 OpenAI 批处理快速又便宜：
- 对于大规模回填，OpenAI 通常是我们支持的最快选项，因为我们可以在单个批量作业中提交多个嵌入请求，让 OpenAI 异步处理。
- OpenAI 为 Batch API 工作负载提供折扣定价，因此大规模索引运行通常比同步发送相同请求更便宜。
- 对于大型回填，OpenAI 通常是我们支持的最快选项，因为我们可以在单个批处理作业中提交许多嵌入请求，让 OpenAI 异步处理它们。
- OpenAI 为 Batch API 工作负载提供折扣定价，因此大型索引运行通常比同步发送相同请求更便宜。
- 详情参见 OpenAI Batch API 文档和定价：
- https://platform.openai.com/docs/api-reference/batch
- https://platform.openai.com/pricing
@@ -198,7 +198,7 @@ agents: {
工具：
- `memory_search` — 返回包含文件路径和行范围的片段。
- `memory_search` — 返回带有文件 + 行范围的片段。
- `memory_get` — 按路径读取记忆文件内容。
本地模式：
@@ -209,65 +209,67 @@ agents: {
### 记忆工具的工作原理
- `memory_search` 对来自 `MEMORY.md` + `memory/**/*.md` 的 Markdown 分块（约 400 token 目标，80 token 重叠）进行语义搜索。返回片段文本（上限约 700 字符）、文件路径、行范围、分数、提供商/模型，以及是否从本地回退到了远程嵌入。不返回完整文件内容。
- `memory_get` 读取特定的记忆 Markdown 文件（工作区相对路径），可选从起始行读取 N 行。`MEMORY.md` / `memory/` 之外的路径仅在 `memorySearch.extraPaths` 中显式列出时才允许访问。
- 两个工具仅在 `memorySearch.enabled` 对智能体解析为 true 时启用。
- `memory_search` 从 `MEMORY.md` + `memory/**/*.md` 语义搜索 Markdown 块（目标约 400 个 token，80 个 token 重叠）。它返回片段文本（上限约 700 个字符）、文件路径、行范围、分数、提供商/模型，以及我们是否从本地回退到远程嵌入。不返回完整文件内容。
- `memory_get` 读取特定的记忆 Markdown 文件（工作空间相对路径），可选从起始行开始读取 N 行。`MEMORY.md` / `memory/` 之外的路径仅在明确列在 `memorySearch.extraPaths` 中时才允许。
- 两个工具仅在智能体的 `memorySearch.enabled` 解析为 true 时启用。
### 索引内容（及时机）
- 文件类型：仅 Markdown（`MEMORY.md`、`memory/**/*.md`，以及 `memorySearch.extraPaths` 下的任何 `.md` 文件）。
- 索引存储：每个智能体的 SQLite 位于 `~/.openclaw/memory/<agentId>.sqlite`（可通过 `agents.defaults.memorySearch.store.path` 配置，支持 `{agentId}` 占位符）。
- 时效性：监视 `MEMORY.md`、`memory/` 和 `memorySearch.extraPaths` 的变更并标记索引为脏（防抖 1.5 秒）。同步在会话开始时、搜索时或按间隔调度，并异步运行。会话记录使用增量阈值触发后台同步。
- 重新索引触发条件：索引存储嵌入的**提供商/模型 + 端点指纹 + 分块参数**。如果其中任何一项发生变化，OpenClaw 会自动重置并重新索引整个存储。
- 索引存储：每个智能体的 SQLite 位于 `~/.openclaw/memory/<agentId>.sqlite`（可通过 `agents.defaults.memorySearch.store.path` 配置，支持 `{agentId}` 令牌）。
- 新鲜度：监视器监视 `MEMORY.md`、`memory/` 和 `memorySearch.extraPaths`，标记索引为脏（去抖动 1.5 秒）。同步在会话开始时、搜索时或按间隔安排，并异步运行。会话记录使用增量阈值触发后台同步。
- 重新索引触发器：索引存储嵌入的**提供商/模型 + 端点指纹 + 分块参数**。如果其中任何一个发生变化，OpenClaw 会自动重置并重新索引整个存储。
### 混合搜索（BM25 + 向量）
启用后，OpenClaw 结合以下两种方式：
启用时，OpenClaw 结合：
- **向量相似度**（语义匹配，措辞可以不同）
- **BM25 关键词相关性**（精确 token，如 ID、环境变量、代码符号）
- **BM25 关键词相关性**（精确令牌如 ID、环境变量、代码符号）
如果你的平台上全文搜索不可用，OpenClaw 会回退到纯向量搜索。
#### 为什么用混合搜索？
#### 为什么使用混合搜索？
向量搜索擅长"这表达的是同一个意思"：
向量搜索擅长"这意味着同一件事"：
- "Mac Studio gateway 主机" vs "运行 gateway 的机器"
- "防抖文件更新" vs "避免每次写入都索引"
- "Mac Studio gateway host" vs "运行 gateway 的机器"
- "debounce file updates" vs "避免每次写入都索引"
但对于精确的高信号 token 可能较弱：
但它在精确的高信号令牌上可能较弱：
- ID（`a828e60`、`b3b9895a…`）
- 代码符号（`memorySearch.query.hybrid`）
- 错误字符串（"sqlite-vec unavailable"）
BM25（全文搜索）恰好相反：擅长精确 token，较弱于同义改写。混合搜索是务实的折中方案：**同时使用两种检索信号**，这样"自然语言"查询和"大海捞针"查询都能获得好结果。
BM25（全文）正好相反：擅长精确令牌，弱于释义。
混合搜索是务实的中间地带：**同时使用两种检索信号**，这样你可以在"自然语言"查询和"大海捞针"查询上都获得好结果。
#### 我们如何合并结果（当前设计）
实现概要：
实现概述：
1. 从两端检索候选池：
1. 从双方检索候选池：
- **向量**：按余弦相似度取前 `maxResults * candidateMultiplier` 个。
- **BM25**：按 FTS5 BM25 排名取前 `maxResults * candidateMultiplier` 个（值越低越好）。
- **BM25**：按 FTS5 BM25 排名取前 `maxResults * candidateMultiplier` 个（越低越好）。
2. 将 BM25 排名转换为 0..1 范围的分数：
- `textScore = 1 / (1 + max(0, bm25Rank))`
3. 按分块 ID 合并候选并计算加权分数：
3. 按块 id 合并候选并计算加权分数：
- `finalScore = vectorWeight * vectorScore + textWeight * textScore`
注意事项：
说明：
- 在配置解析时 `vectorWeight` + `textWeight` 会归一化到 1.0，因此权重表现为百分比。
- 如果嵌入不可用（或提供商返回零向量），我们仍会运行 BM25 并返回关键词匹配结果。
- 在配置解析中 `vectorWeight` + `textWeight` 归一化为 1.0，因此权重表现为百分比。
- 如果嵌入不可用（或提供商返回零向量），我们仍然运行 BM25 并返回关键词匹配。
- 如果无法创建 FTS5，我们保持纯向量搜索（不会硬失败）。
这不是"信息检索理论上的完美方案"，但它简单、快速，在实际笔记上倾向于提升召回率/精确率。如果以后想更精细，常见的下一步是互惠排名融合（RRF）或混合前的分数归一化（最小/最大值或 z-score）。
这不是"IR 理论完美"的，但它简单、快速，并且往往能提高真实笔记的召回率/精确率。
如果我们以后想要更复杂的方案，常见的下一步是倒数排名融合（RRF）或在混合之前进行分数归一化（最小/最大或 z 分数）。
配置：
@@ -290,7 +292,7 @@ agents: {
### 嵌入缓存
OpenClaw 可以在 SQLite 中缓存**分块嵌入**，这样重新索引和频繁更新（特别是会话记录）不会重新嵌入未更改的文本。
OpenClaw 可以在 SQLite 中缓存**块嵌入**，这样重新索引和频繁更新（特别是会话记录）不会重新嵌入未更改的文本。
配置：
@@ -309,7 +311,8 @@ agents: {
### 会话记忆搜索（实验性）
你可以选择索引**会话记录**并通过 `memory_search` 进行搜索。此功能受实验性标志控制。
你可以选择性地索引**会话记录**并通过 `memory_search` 呈现它们。
这由实验性标志控制。
```json5
agents: {
@@ -322,14 +325,14 @@ agents: {
}
```
注意事项：
说明：
- 会话索引是**选择加入**的（默认关闭）。
- 会话更新带防抖，在超过增量阈值后**异步索引**（尽力而为）。
- `memory_search` 不会阻塞等待索引；在后台同步完成之前结果可能略有延迟。
- 结果仍然只包含片段；`memory_get` 仍限于记忆文件。
- 会话更新被去抖动并在超过增量阈值后**异步索引**（尽力而为）。
- `memory_search` 永远不会阻塞索引；在后台同步完成之前，结果可能略有延迟。
- 结果仍然只包含片段；`memory_get` 仍然仅限于记忆文件。
- 会话索引按智能体隔离（仅索引该智能体的会话日志）。
- 会话日志存储在磁盘上（`~/.openclaw/agents/<agentId>/sessions/*.jsonl`）。任何拥有文件系统访问权限的进程/用户都可以读取它们，因此应将磁盘访问视为信任边界。如需更严格的隔离，请在不同的操作系统用户或主机下运行智能体。
- 会话日志存储在磁盘上（`~/.openclaw/agents/<agentId>/sessions/*.jsonl`）。任何具有文件系统访问权限的进程/用户都可以读取它们，因此将磁盘访问视为信任边界。对于更严格的隔离，在单独的操作系统用户或主机下运行智能体。
增量阈值（显示默认值）：
@@ -350,7 +353,7 @@ agents: {
### SQLite 向量加速（sqlite-vec）
当 sqlite-vec 扩展可用时，OpenClaw 将嵌入存储在 SQLite 虚拟表（`vec0`）中，并在数据库内执行向量距离查询。这使搜索保持快速，无需将所有嵌入加载到 JS 中。
当 sqlite-vec 扩展可用时，OpenClaw 将嵌入存储在 SQLite 虚拟表（`vec0`）中，并在数据库中执行向量距离查询。这使搜索保持快速，无需将每个嵌入加载到 JS 中。
配置（可选）：
@@ -369,18 +372,18 @@ agents: {
}
```
注意事项：
说明：
- `enabled` 默认为 true；禁用时，搜索回退到对存储嵌入进行进程内余弦相似度计算。
- `enabled` 默认为 true；禁用时，搜索回退到对存储嵌入的进程内余弦相似度计算。
- 如果 sqlite-vec 扩展缺失或加载失败，OpenClaw 会记录错误并继续使用 JS 回退（无向量表）。
- `extensionPath` 覆盖捆绑的 sqlite-vec 路径（适用于自定义构建或非标准安装位置）。
- `extensionPath` 覆盖捆绑的 sqlite-vec 路径（对于自定义构建或非标准安装位置很有用）。
### 本地嵌入自动下载
- 默认本地嵌入模型：`hf:ggml-org/embeddinggemma-300M-GGUF/embeddinggemma-300M-Q8_0.gguf`（约 0.6 GB）。
- 当 `memorySearch.provider = "local"` 时，`node-llama-cpp` 解析 `modelPath`；如果 GGUF 文件缺失，会**自动下载**到缓存目录（或 `local.modelCacheDir`，如已设置），然后加载。下载在重试时可恢复。
- 当 `memorySearch.provider = "local"` 时，`node-llama-cpp` 解析 `modelPath`；如果 GGUF 缺失，它会**自动下载**到缓存（或 `local.modelCacheDir`，如果已设置），然后加载它。下载在重试时会续传。
- 原生构建要求：运行 `pnpm approve-builds`，选择 `node-llama-cpp`，然后运行 `pnpm rebuild node-llama-cpp`。
- 回退：如果本地设置失败且 `memorySearch.fallback = "openai"`，我们会自动切换到远程嵌入（`openai/text-embedding-3-small`，除非被覆盖）并记录原因。
- 回退：如果本地设置失败且 `memorySearch.fallback = "openai"`，我们自动切换到远程嵌入（`openai/text-embedding-3-small`，除非被覆盖）并记录原因。
### 自定义 OpenAI 兼容端点示例
@@ -403,7 +406,7 @@ agents: {
}
```
注意事项：
说明：
- `remote.*` 优先于 `models.providers.openai.*`。
- `remote.headers` 与 OpenAI 请求头合并；键冲突时 remote 优先。省略 `remote.headers` 则使用 OpenAI 默认值。
- `remote.headers` 与 OpenAI 标头合并；键冲突时 remote 优先。省略 `remote.headers` 以使用 OpenAI 默认值。

102
docs/zh-CN/concepts/messages.md
View File

@@ -1,50 +1,50 @@
---
read_when:
- 解释入站消息如何变为回复
- 澄清会话、队列模式或流式传输行为
- 记录推理可见性和用量影响
summary: 消息流、会话、队列和推理可见性
- 解释入站消息如何转化为回复
- 阐明会话、队列模式或流式传输行为
- 记录推理可见性和使用影响
summary: 消息流程、会话、队列和推理可见性
title: 消息
x-i18n:
generated_at: "2026-02-01T20:22:57Z"
generated_at: "2026-02-03T10:05:22Z"
model: claude-opus-4-5
provider: pi
source_hash: 147362b61bee21ee6e303654d970a052325f076ddb45814306053f70409737b5
source_path: concepts/messages.md
workflow: 14
workflow: 15
---
# 消息
本页汇总了 OpenClaw 处理入站消息、会话、队列、流式传输和推理可见性的方式。
本页汇总了 OpenClaw 如何处理入站消息、会话、队列、流式传输和推理可见性。
## 消息流（概览）
## 消息流程（高层概述）
```
入站消息
-> 路由/绑定 -> 会话键
-> 路由/绑定 -> 会话密钥
-> 队列（如果有运行中的任务）
-> 智能体运行（流式传输 + 工具）
-> 出站回复（渠道限制 + 分块）
```
关键配置项位于配置文件中：
关键配置项在配置中：
- `messages.*` 用于前缀、队列和群组行为。
- `agents.defaults.*` 用于块流式传输和分块默认值。
- `agents.defaults.*` 用于分块流式传输和分块默认值。
- 渠道覆盖（`channels.whatsapp.*`、`channels.telegram.*` 等）用于上限和流式传输开关。
完整配置结构请参见[配置](/gateway/configuration)。
完整 schema 参见[配置](/gateway/configuration)。
## 入站去重
渠道在重新连接后可能会重新投递相同的消息。OpenClaw 维护一个短期缓存，以渠道/账号/对端/会话/消息 ID 为键，避免重复投递触发额外的智能体运行。
渠道可能在重新连接后重复投递同一消息。OpenClaw 保持一个短期缓存，以渠道/账户/对端/会话/消息 ID 为键，因此重复投递不会触发另一次智能体运行。
## 入站防抖
来自**同一发送者**的快速连续消息可以通过 `messages.inbound` 合并为单个智能体轮次。防抖按渠道 + 对话维度隔离，并使用最新消息进行回复线程/ID 关联。
来自**同一发送者**的快速连续消息可以通过 `messages.inbound` 批量合并为单个智能体轮次。防抖按渠道 + 会话为范围，并使用最近的消息进行回复线程/ID 处理。
配置（全局默认 + 按渠道覆盖）：
配置（全局默认 + 单渠道覆盖）：
```json5
{
@@ -61,54 +61,54 @@ x-i18n:
}
```
说明：
注意事项：
- 防抖仅适用于**纯文本**消息；媒体/附件会立即发送。
- 控制命令会绕过防抖，保持为独立消息。
- 防抖仅适用于**纯文本**消息；媒体/附件会立即刷新。
- 控制命令会绕过防抖，保持独立。
## 会话与设备
## 会话和设备
会话由 Gateway网关管理，而非由客户端管理。
会话由 Gateway 网关拥有，而非客户端。
- 私聊消息归并到智能体的主会话键。
- 群组/频道拥有各自独立的会话键。
- 会话存储和对话记录保存在 Gateway网关主机上。
- 直接聊天合并到智能体主会话密钥。
- 群组/渠道获得各自的会话密钥。
- 会话存储和记录保存在 Gateway 网关主机上。
多个设备/渠道可以映射到同一个会话，但历史记录不会完全同步回每个客户端。建议：长对话使用一个主要设备，以避免上下文分歧。控制界面和 TUI 始终显示 Gateway网关端的会话记录，因此它们是权威数据源。
多个设备/渠道可以映射到同一会话，但历史记录不会完全同步回每个客户端。建议：对长对话使用一个主设备，以避免上下文分歧。控制 UI 和 TUI 始终显示 Gateway 网关支持的会话记录，因此它们是事实来源。
详情请参见：[会话管理](/concepts/session)。
详情：[会话管理](/concepts/session)。
## 入站消息体和历史上下文
## 入站正文和历史上下文
OpenClaw 将**提示词体**与**命令体**分开处理：
OpenClaw 将**提示正文**与**命令正文**分开：
- `Body`：发送给智能体的提示词文本。可能包含渠道信封和可选的历史包装。
- `Body`：发送给智能体的提示文本。这可能包括渠道信封和可选的历史包装器。
- `CommandBody`：用于指令/命令解析的原始用户文本。
- `RawBody`：`CommandBody` 的旧版别名（保留以兼容）。
- `RawBody`：`CommandBody` 的旧别名（为兼容性保留）。
当渠道提供历史记录时，使用共享的包装格式：
当渠道提供历史记录时，使用共享包装器：
- `[Chat messages since your last reply - for context]`
- `[Current message - respond to this]`
对于**非私聊**（群组/频道/房间），**当前消息体**会添加发送者标签前缀（与历史条目使用相同的格式）。这使得实时消息和排队/历史消息在智能体提示词中保持一致。
对于**非直接聊天**（群组/渠道/房间），**当前消息正文**会加上发送者标签前缀（与历史条目使用的样式相同）。这使智能体提示中的实时消息和队列/历史消息保持一致。
历史缓冲区为**仅待处理消息**：它们包含未触发运行的群组消息（例如，提及门控的消息），并**排除**已在会话记录中的消息。
历史缓冲区是**仅待处理的**：它们包含*未*触发运行的群组消息（例如，提及门控的消息），并**排除**已在会话记录中的消息。
指令剥离仅适用于**当前消息**部分，历史记录保持不变。包装历史记录的渠道应将 `CommandBody`（或 `RawBody`）设置为原始消息文本，并将 `Body` 保留为组合提示词。历史缓冲区可通过 `messages.groupChat.historyLimit`（全局默认）和按渠道覆盖进行配置，例如 `channels.slack.historyLimit` 或 `channels.telegram.accounts.<id>.historyLimit`（设置为 `0` 可禁用）。
指令剥离仅适用于**当前消息**部分，因此历史记录保持完整。包装历史记录的渠道应将 `CommandBody`（或 `RawBody`）设置为原始消息文本，并将 `Body` 保留为组合提示。历史缓冲区可通过 `messages.groupChat.historyLimit`（全局默认）和单渠道覆盖（如 `channels.slack.historyLimit` 或 `channels.telegram.accounts.<id>.historyLimit`）进行配置（设置 `0` 表示禁用）。
## 队列与后续消息
## 队列和后续消息
如果已有运行中的任务，入站消息可以排队、引导至当前运行，或收集用于后续轮次。
如果运行已在进行中，入站消息可以排队、导入当前运行，或收集用于后续轮次。
- 通过 `messages.queue`（及 `messages.queue.byChannel`）进行配置。
- 模式：`interrupt`、`steer`、`followup`、`collect`，以及 backlog 变体。
- 通过 `messages.queue`（和 `messages.queue.byChannel`）配置。
- 模式：`interrupt`、`steer`、`followup`、`collect`，以及积压变体。
详情请参见：[队列](/concepts/queue)。
详情：[队列](/concepts/queue)。
## 流式传输、分块与批处理
## 流式传输、分块和批处理
块流式传输在模型生成文本块时发送部分回复。分块遵循渠道文本限制，避免拆分代码围栏。
分块流式传输在模型生成文本块时发送部分回复。分块遵循渠道文本限制，避免拆分围栏代码。
关键设置：
@@ -116,26 +116,26 @@ OpenClaw 将**提示词体**与**命令体**分开处理：
- `agents.defaults.blockStreamingBreak`（`text_end|message_end`）
- `agents.defaults.blockStreamingChunk`（`minChars|maxChars|breakPreference`）
- `agents.defaults.blockStreamingCoalesce`（基于空闲的批处理）
- `agents.defaults.humanDelay`（块回复之间的仿人类停顿）
- `agents.defaults.humanDelay`（块回复之间的拟人化暂停）
- 渠道覆盖：`*.blockStreaming` 和 `*.blockStreamingCoalesce`（非 Telegram 渠道需要显式设置 `*.blockStreaming: true`）
详情请参见：[流式传输 + 分块](/concepts/streaming)。
详情：[流式传输 + 分块](/concepts/streaming)。
## 推理可见性与令牌
## 推理可见性和 token
OpenClaw 可以显示或隐藏模型推理过程：
OpenClaw 可以显示或隐藏模型推理：
- `/reasoning on|off|stream` 控制可见性。
- 推理内容在模型生成时仍然计入令牌用量。
- Telegram 支持将推理过程流式传输到草稿气泡中。
- 当模型产生推理内容时，它仍计入 token 使用量。
- Telegram 支持将推理流式传输到草稿气泡中。
详情请参见：[思考 + 推理指令](/tools/thinking) 和 [令牌用量](/token-use)。
详情：[思考 + 推理指令](/tools/thinking)和 [Token 使用](/token-use)。
## 前缀、线程与回复
## 前缀、线程和回复
出站消息格式集中在 `messages` 中管理：
出站消息格式在 `messages` 中集中配置：
- `messages.responsePrefix`（出站前缀）和 `channels.whatsapp.messagePrefix`（WhatsApp 入站前缀）
- 通过 `replyToMode` 和按渠道默认值进行回复线程关联
- 通过 `replyToMode` 和单渠道默认值进行回复线程
详情请参见：[配置](/gateway/configuration#messages) 和各渠道文档。
详情：[配置](/gateway/configuration#messages)和渠道文档。

83
docs/zh-CN/concepts/model-failover.md
View File

@@ -1,16 +1,16 @@
---
read_when:
- 诊断认证配置文件轮换、冷却期或模型回退行为
- 诊断认证配置文件轮换、冷却时间或模型回退行为
- 更新认证配置文件或模型的故障转移规则
summary: OpenClaw 如何轮换认证配置文件并在模型之间进行故障回退
summary: OpenClaw 如何轮换认证配置文件并在模型之间进行回退
title: 模型故障转移
x-i18n:
generated_at: "2026-02-01T20:23:02Z"
generated_at: "2026-02-03T07:46:17Z"
model: claude-opus-4-5
provider: pi
source_hash: eab7c0633824d941cf0d6ce4294f0bc8747fbba2ce93650e9643eca327cd04a9
source_path: concepts/model-failover.md
workflow: 14
workflow: 15
---
# 模型故障转移
@@ -20,78 +20,70 @@ OpenClaw 分两个阶段处理故障：
1. 在当前提供商内进行**认证配置文件轮换**。
2. **模型回退**到 `agents.defaults.model.fallbacks` 中的下一个模型。
本文档介绍运行时规则及其背后的数据。
本文档解释运行时规则及其背后的数据。
## 认证存储（密钥 + OAuth）
OpenClaw 对 API 密钥和 OAuth 令牌都使用**认证配置文件**。
- 密钥存储在 `~/.openclaw/agents/<agentId>/agent/auth-profiles.json`（旧版路径：`~/.openclaw/agent/auth-profiles.json`）。
- 配置项 `auth.profiles` / `auth.order` **仅包含元数据和路由信息**（不含密钥）。
- 旧版仅导入的 OAuth 文件：`~/.openclaw/credentials/oauth.json`（首次使用时导入到 `auth-profiles.json`）。
- 密钥存储在 `~/.openclaw/agents/<agentId>/agent/auth-profiles.json`（旧版：`~/.openclaw/agent/auth-profiles.json`）。
- 配置 `auth.profiles` / `auth.order` **仅用于元数据和路由**（不含密钥）。
- 旧版仅导入 OAuth 文件：`~/.openclaw/credentials/oauth.json`（首次使用时导入到 `auth-profiles.json`）。
更多详情：[/concepts/oauth](/concepts/oauth)
凭证类型：
- `type: "api_key"` → `{ provider, key }`
- `type: "oauth"` → `{ provider, access, refresh, expires, email? }`（部分提供商还包含 `projectId`/`enterpriseUrl`）
- `type: "oauth"` → `{ provider, access, refresh, expires, email? }`（某些提供商还有 `projectId`/`enterpriseUrl`）
## 配置文件 ID
OAuth 登录会创建不同的配置文件，以便多个账户共存。
OAuth 登录创建不同的配置文件，以便多个账户可以共存。
- 默认值：当没有可用邮箱时为 `provider:default`。
- 带邮箱的 OAuth：`provider:<email>`（例如 `google-antigravity:user@gmail.com`）。
- 默认：当没有电子邮件可用时为 `provider:default`。
- 带电子邮件的 OAuth：`provider:<email>`（例如 `google-antigravity:user@gmail.com`）。
配置文件存储在 `~/.openclaw/agents/<agentId>/agent/auth-profiles.json` 的 `profiles` 下。
## 轮换顺序
当一个提供商有多个配置文件时，OpenClaw 按如下方式选择顺序：
当一个提供商有多个配置文件时，OpenClaw 按以下顺序选择：
1. **显式配置**：`auth.order[provider]`（如果已设置）。
1. **显式配置**：`auth.order[provider]`（如果设置）。
2. **已配置的配置文件**：按提供商过滤的 `auth.profiles`。
3. **已存储的配置文件**：`auth-profiles.json` 中该提供商的条目。
如果未配置显式顺序，OpenClaw 使用轮询顺序：
如果没有配置显式顺序，OpenClaw 使用轮询顺序：
- **主排序键：** 配置文件类型（**OAuth 优先于 API 密钥**）。
- **次排序键：** `usageStats.lastUsed`（同类型内最旧的优先）。
- **冷却中/已禁用的配置文件**被移到末尾，按最早到期时间排序。
- **主键：** 配置文件类型（**OAuth 优先于 API 密钥**）。
- **次键：** `usageStats.lastUsed`（每种类型中最旧的优先）。
- **冷却/禁用的配置文件**会移到末尾，按最早过期时间排序。
### 会话粘性（缓存友好）
OpenClaw 会**在每个会话中固定选定的认证配置文件**，以保持提供商缓存活跃。
它**不会**在每次请求时轮换。固定的配置文件会持续使用，直到：
OpenClaw **为每个会话固定所选的认证配置文件**以保持提供商缓存热度。它**不会**在每个请求时轮换。固定的配置文件会被重用直到：
- 会话被重置（`/new` / `/reset`）
- 压缩完成（压缩计数递增）
- 配置文件处于冷却中/已禁用状态
- 配置文件处于冷却/禁用状态
通过 `/model …@<profileId>` 手动选择会为该会话设置一个**用户覆盖**，
在新会话开始前不会自动轮换。
通过 `/model …@<profileId>` 手动选择会为该会话设置**用户覆盖**，在新会话开始之前不会自动轮换。
自动固定的配置文件（由会话路由器选择）被视为一种**偏好**：
它们会优先尝试，但 OpenClaw 可能在遇到速率限制/超时时轮换到其他配置文件。
用户固定的配置文件会锁定在该配置文件上；如果它失败且配置了模型回退，
OpenClaw 会转移到下一个模型，而不是切换配置文件。
自动固定的配置文件（由会话路由器选择）被视为**偏好**：它们会优先尝试，但 OpenClaw 可能在速率限制/超时时轮换到另一个配置文件。用户固定的配置文件会锁定到该配置文件；如果失败且配置了模型回退，OpenClaw 会移动到下一个模型而不是切换配置文件。
### 为什么 OAuth 可能"看起来丢失了"
### 为什么 OAuth 可能"看起来丢失"
如果你对同一个提供商同时拥有 OAuth 配置文件和 API 密钥配置文件，轮询可能在消息之间切换它们（除非已固定）。要强制使用单个配置文件：
如果你为同一个提供商同时拥有 OAuth 配置文件和 API 密钥配置文件，除非固定，否则轮询可能在消息之间切换它们。要强制使用单个配置文件：
- 通过 `auth.order[provider] = ["provider:profileId"]` 固定，或
- 通过 `/model …` 使用按会话覆盖并指定配置文件（当你的 UI/聊天界面支持时）。
- 使用 `auth.order[provider] = ["provider:profileId"]` 固定，或
- 通过 `/model …` 使用每会话覆盖并指定配置文件覆盖（当你的 UI/聊天界面支持时）。
## 冷却期
## 冷却时间
当配置文件因认证/速率限制错误（或看起来像速率限制的超时）而失败时，
OpenClaw 会将其标记为冷却状态并移至下一个配置文件。
格式/无效请求错误（例如 Cloud Code Assist 工具调用 ID
验证失败）也被视为可故障转移的，并使用相同的冷却机制。
当配置文件因认证/速率限制错误（或看起来像速率限制的超时）而失败时，OpenClaw 将其标记为冷却状态并移动到下一个配置文件。格式/无效请求错误（例如 Cloud Code Assist 工具调用 ID 验证失败）被视为值得故障转移的情况，使用相同的冷却时间。
冷却期使用指数退避：
冷却时间使用指数退避：
- 1 分钟
- 5 分钟
@@ -112,9 +104,9 @@ OpenClaw 会将其标记为冷却状态并移至下一个配置文件。
}
```
## 计费禁用
## 账单禁用
计费/额度失败（例如"额度不足"/"信用余额过低"）被视为可故障转移的，但通常不是临时性的。OpenClaw 不会使用短冷却期，而是将配置文件标记为**已禁用**（使用更长的退避时间）并轮换到下一个配置文件/提供商。
账单/额度失败（例如"insufficient credits"/"credit balance too low"）被视为值得故障转移的情况，但它们通常不是暂时性的。OpenClaw 不使用短冷却时间，而是将配置文件标记为**禁用**（使用更长的退避时间）并轮换到下一个配置文件/提供商。
状态存储在 `auth-profiles.json` 中：
@@ -131,21 +123,18 @@ OpenClaw 会将其标记为冷却状态并移至下一个配置文件。
默认值：
- 计费退避从 **5 小时**开始，每次计费失败加倍，上限为 **24 小时**。
- 如果配置文件在 **24 小时**内未失败，退避计数器将重置（可配置）。
- 账单退避从 **5 小时**开始，每次账单失败翻倍，上限为 **24 小时**。
- 如果配置文件 **24 小时**内没有失败，退避计数器会重置（可配置）。
## 模型回退
如果某个提供商的所有配置文件都失败，OpenClaw 会移至
`agents.defaults.model.fallbacks` 中的下一个模型。这适用于认证失败、速率限制和
耗尽配置文件轮换的超时情况（其他错误不会触发回退）。
如果某个提供商的所有配置文件都失败，OpenClaw 会移动到 `agents.defaults.model.fallbacks` 中的下一个模型。这适用于认证失败、速率限制和耗尽配置文件轮换的超时（其他错误不会推进回退）。
当运行以模型覆盖（钩子或 CLI）启动时，回退仍会在尝试所有已配置的回退后
止于 `agents.defaults.model.primary`。
当运行以模型覆盖（钩子或 CLI）开始时，在尝试任何配置的回退之后，回退仍会在 `agents.defaults.model.primary` 处结束。
## 相关配置
参阅 [Gateway网关配置](/gateway/configuration) 了解：
参阅 [Gateway 网关配置](/gateway/configuration) 了解：
- `auth.profiles` / `auth.order`
- `auth.cooldowns.billingBackoffHours` / `auth.cooldowns.billingBackoffHoursByProvider`

61
docs/zh-CN/concepts/model-providers.md
View File

@@ -1,32 +1,32 @@
---
read_when:
- 你需要按提供商查阅模型设置参考
- 你需要按提供商分类的模型设置参考
- 你需要模型提供商的示例配置或 CLI 新手引导命令
summary: 模型提供商概览，包含示例配置和 CLI 流程
summary: 模型提供商概述，包含示例配置和 CLI 流程
title: 模型提供商
x-i18n:
generated_at: "2026-02-01T20:23:13Z"
generated_at: "2026-02-03T07:46:28Z"
model: claude-opus-4-5
provider: pi
source_hash: b3940c91ce3aee3d701af7978284966a60ec8c669649cc4be48ba9472243e444
source_hash: 14f73e5a9f9b7c6f017d59a54633942dba95a3eb50f8848b836cfe0b9f6d7719
source_path: concepts/model-providers.md
workflow: 14
workflow: 15
---
# 模型提供商
本页介绍 **LLM/模型提供商**（非 WhatsApp/Telegram 等聊天渠道）。
有关模型选择规则，请参见 [/concepts/models](/concepts/models)。
本页介绍 **LLM/模型提供商**（不是 WhatsApp/Telegram 等聊天渠道）。
关于模型选择规则，请参阅 [/concepts/models](/concepts/models)。
## 快速规则
- 模型引用使用 `provider/model` 格式（例如：`opencode/claude-opus-4-5`）。
- 如果设置了 `agents.defaults.models`，它将成为白名单。
- CLI 辅助命令：`openclaw onboard`、`openclaw models list`、`openclaw models set <provider/model>`。
- 如果设置了 `agents.defaults.models`，它将成为允许列表。
- CLI 辅助工具：`openclaw onboard`、`openclaw models list`、`openclaw models set <provider/model>`。
## 内置提供商（pi-ai 目录）
OpenClaw 自带 pi‑ai 目录。这些提供商**无需**配置 `models.providers`；只需设置认证并选择模型即可。
OpenClaw 附带 pi-ai 目录。这些提供商**不需要** `models.providers` 配置；只需设置认证 + 选择模型。
### OpenAI
@@ -97,7 +97,7 @@ OpenClaw 自带 pi‑ai 目录。这些提供商**无需**配置 `models.provide
- Gemini CLI OAuth 作为捆绑插件提供（`google-gemini-cli-auth`，默认禁用）。
- 启用：`openclaw plugins enable google-gemini-cli-auth`
- 登录：`openclaw models auth login --provider google-gemini-cli --set-default`
- 注意：你**无需**将客户端 ID 或密钥粘贴到 `openclaw.json` 中。CLI 登录流程会将令牌存储在 Gateway网关主机的认证配置文件中。
- 注意：你**不需要**将客户端 ID 或密钥粘贴到 `openclaw.json` 中。CLI 登录流程将令牌存储在 Gateway 网关主机的认证配置文件中。
### Z.AI (GLM)
@@ -105,7 +105,7 @@ OpenClaw 自带 pi‑ai 目录。这些提供商**无需**配置 `models.provide
- 认证：`ZAI_API_KEY`
- 示例模型：`zai/glm-4.7`
- CLI：`openclaw onboard --auth-choice zai-api-key`
- 别名：`z.ai/*` 和 `z-ai/*` 会规范化为 `zai/*`
- 别名：`z.ai/*` 和 `z-ai/*` 规范化为 `zai/*`
### Vercel AI Gateway
@@ -137,14 +137,17 @@ Moonshot 使用 OpenAI 兼容端点，因此将其配置为自定义提供商：
- 提供商：`moonshot`
- 认证：`MOONSHOT_API_KEY`
- 示例模型：`moonshot/kimi-k2.5`
- Kimi K2 模型 ID：
{/_ moonshot-kimi-k2-model-refs:start _/}
- `moonshot/kimi-k2.5`
- `moonshot/kimi-k2-0905-preview`
- `moonshot/kimi-k2-turbo-preview`
- `moonshot/kimi-k2-thinking`
- `moonshot/kimi-k2-thinking-turbo`
{/_ moonshot-kimi-k2-model-refs:end _/}
Kimi K2 模型 ID：
{/_ moonshot-kimi-k2-model-refs:start _/ && null}
- `moonshot/kimi-k2.5`
- `moonshot/kimi-k2-0905-preview`
- `moonshot/kimi-k2-turbo-preview`
- `moonshot/kimi-k2-thinking`
- `moonshot/kimi-k2-thinking-turbo`
{/_ moonshot-kimi-k2-model-refs:end _/ && null}
```json5
{
@@ -182,7 +185,7 @@ Kimi Coding 使用 Moonshot AI 的 Anthropic 兼容端点：
}
```
### Qwen OAuth（免费版）
### Qwen OAuth（免费层级）
Qwen 通过设备码流程提供对 Qwen Coder + Vision 的 OAuth 访问。
启用捆绑插件，然后登录：
@@ -197,11 +200,11 @@ openclaw models auth login --provider qwen-portal --set-default
- `qwen-portal/coder-model`
- `qwen-portal/vision-model`
详见 [/providers/qwen](/providers/qwen) 了解设置详情和注意事项。
参见 [/providers/qwen](/providers/qwen) 了解设置详情和注意事项。
### Synthetic
Synthetic 在 `synthetic` 提供商下提供 Anthropic 兼容的模型：
Synthetic 通过 `synthetic` 提供商提供 Anthropic 兼容模型：
- 提供商：`synthetic`
- 认证：`SYNTHETIC_API_KEY`
@@ -234,11 +237,11 @@ MiniMax 通过 `models.providers` 配置，因为它使用自定义端点：
- MiniMax（Anthropic 兼容）：`--auth-choice minimax-api`
- 认证：`MINIMAX_API_KEY`
详见 [/providers/minimax](/providers/minimax) 了解设置详情、模型选项和配置片段。
参见 [/providers/minimax](/providers/minimax) 了解设置详情、模型选项和配置片段。
### Ollama
Ollama 是一个本地 LLM 运行时，提供 OpenAI 兼容的 API：
Ollama 是提供 OpenAI 兼容 API 的本地 LLM 运行时：
- 提供商：`ollama`
- 认证：无需（本地服务器）
@@ -246,7 +249,7 @@ Ollama 是一个本地 LLM 运行时，提供 OpenAI 兼容的 API：
- 安装：https://ollama.ai
```bash
# 安装 Ollama，然后拉取模型：
# Install Ollama, then pull a model:
ollama pull llama3.3
```
@@ -258,7 +261,7 @@ ollama pull llama3.3
}
```
Ollama 在本地运行于 `http://127.0.0.1:11434/v1` 时会被自动检测。详见 [/providers/ollama](/providers/ollama) 了解模型推荐和自定义配置。
当 Ollama 在本地 `http://127.0.0.1:11434/v1` 运行时会自动检测。参见 [/providers/ollama](/providers/ollama) 了解模型推荐和自定义配置。
### 本地代理（LM Studio、vLLM、LiteLLM 等）
@@ -304,7 +307,7 @@ Ollama 在本地运行于 `http://127.0.0.1:11434/v1` 时会被自动检测。
- `cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }`
- `contextWindow: 200000`
- `maxTokens: 8192`
- 建议：设置与你的代理/模型限制匹配的明确值。
- 建议：设置与你的代理/模型限制匹配的显式值。
## CLI 示例
@@ -314,4 +317,4 @@ openclaw models set opencode/claude-opus-4-5
openclaw models list
```
另请参见：[/gateway/configuration](/gateway/configuration) 了解全部配置示例。
另请参阅：[/gateway/configuration](/gateway/configuration) 了解完整配置示例。

82
docs/zh-CN/concepts/models.md
View File

@@ -1,76 +1,76 @@
---
read_when:
- 添加或修改模型 CLI（models list/set/scan/aliases/fallbacks）
- 更改模型回退行为或选择体验
- 更改模型回退行为或选择用户体验
- 更新模型扫描探测（工具/图像）
summary: 模型 CLI：列表、设置、别名、回退、扫描、状态
title: 模型 CLI
x-i18n:
generated_at: "2026-02-01T20:23:26Z"
generated_at: "2026-02-03T10:05:42Z"
model: claude-opus-4-5
provider: pi
source_hash: e8b54bb370b4f63a9b917594fb0f6ff48192e168196d30c713b8bbe72b78fef6
source_path: concepts/models.md
workflow: 14
workflow: 15
---
# 模型 CLI
认证配置轮换、冷却时间以及与回退的交互方式请参见 [/concepts/model-failover](/concepts/model-failover)。
提供商快速概览 + 示例：[/concepts/model-providers](/concepts/model-providers)。
参见 [/concepts/model-failover](/concepts/model-failover) 了解认证配置文件轮换、冷却时间及其与回退的交互。
快速提供商概述 + 示例：[/concepts/model-providers](/concepts/model-providers)。
## 模型选择的工作方式
## 模型选择工作原理
OpenClaw 按以下顺序选择模型：
1. **主模型**（`agents.defaults.model.primary` 或 `agents.defaults.model`）。
2. `agents.defaults.model.fallbacks` 中的**回退模型**（按顺序）。
3. **提供商认证故障转移**在切换到下一个模型之前，会先在提供商内部进行。
1. **主要**模型（`agents.defaults.model.primary` 或 `agents.defaults.model`）。
2. `agents.defaults.model.fallbacks` 中的**回退**（按顺序）。
3. **提供商认证故障转移**在移动到下一个模型之前在提供商内部发生。
相关说明：
相关：
- `agents.defaults.models` 是 OpenClaw 可使用的模型白名单/目录（含别名）。
- `agents.defaults.imageModel` **仅在**主模型无法处理图像时使用。
- `agents.defaults.models` 是 OpenClaw 可使用的模型白名单/目录（加上别名）。
- `agents.defaults.imageModel` **仅在**主要模型无法接受图像时使用。
- 每个智能体的默认值可以通过 `agents.list[].model` 加绑定覆盖 `agents.defaults.model`（参见 [/concepts/multi-agent](/concepts/multi-agent)）。
## 快速模型推荐（经验之谈）
- **GLM**：在编码/工具调用方面稍好。
- **MiniMax**：在写作和风格表现方面更好。
- **GLM**：在编程/工具调用方面稍好。
- **MiniMax**：在写作和氛围方面更好。
## 设置向导（推荐）
如果不想手动编辑配置，可以运行新手引导向导：
如果你不想手动编辑配置，请运行新手引导向导：
```bash
openclaw onboard
```
它可以为常见提供商设置模型和认证，包括 **OpenAI Code (Codex) 订阅**（OAuth）和 **Anthropic**（推荐使用 API 密钥；也支持 `claude setup-token`）。
它可以为常见提供商设置模型 + 认证，包括 **OpenAI Code（Codex）订阅**（OAuth）和 **Anthropic**（推荐使用 API 密钥；也支持 `claude setup-token`）。
## 配置键（概览）
## 配置键（概述）
- `agents.defaults.model.primary` 和 `agents.defaults.model.fallbacks`
- `agents.defaults.imageModel.primary` 和 `agents.defaults.imageModel.fallbacks`
- `agents.defaults.models`（白名单 + 别名 + 提供商参数）
- `models.providers`（写入 `models.json` 的自定义提供商）
模型引用会被统一转为小写。提供商别名如 `z.ai/*` 会被规范化为 `zai/*`。
模型引用会规范化为小写。提供商别名如 `z.ai/*` 会规范化为 `zai/*`。
提供商配置示例（包括 OpenCode Zen）请参见 [/gateway/configuration](/gateway/configuration#opencode-zen-multi-model-proxy)。
提供商配置示例（包括 OpenCode Zen）在 [/gateway/configuration](/gateway/configuration#opencode-zen-multi-model-proxy)。
## "Model is not allowed"（以及为什么回复停止）
如果设置了 `agents.defaults.models`，它将成为 `/model` 和会话覆盖的**白名单**。当用户选择了不在白名单中的模型时，OpenClaw 会返回：
如果设置了 `agents.defaults.models`，它将成为 `/model` 和会话覆盖的**白名单**。当用户选择不在该白名单中的模型时，OpenClaw 返回：
```
Model "provider/model" is not allowed. Use /model to list available models.
```
这发生在正常回复生成**之前**，因此消息看起来可能像是"没有响应"。修复方法是：
这发生在正常回复生成**之前**，所以消息可能感觉像"没有响应"。修复方法是：
- 将该模型添加到 `agents.defaults.models`，或
- 清除白名单（移除 `agents.defaults.models`），或
- 将模型添加到 `agents.defaults.models`，或
- 清除白名单（删除 `agents.defaults.models`），或
- 从 `/model list` 中选择一个模型。
白名单配置示例：
@@ -89,7 +89,7 @@ Model "provider/model" is not allowed. Use /model to list available models.
## 在聊天中切换模型（`/model`）
你可以在当前会话中切换模型而无需重启：
你可以在不重启的情况下切换当前会话的模型：
```
/model
@@ -99,14 +99,14 @@ Model "provider/model" is not allowed. Use /model to list available models.
/model status
```
说明：
注意事项：
- `/model`（和 `/model list`）是一个紧凑的编号选择器（模型系列 + 可用提供商）。
- `/model`（和 `/model list`）是紧凑的编号选择器（模型系列 + 可用提供商）。
- `/model <#>` 从该选择器中选择。
- `/model status` 是详细视图（认证候选项，以及配置后的提供商端点 `baseUrl` + `api` 模式）。
- 模型引用通过**第一个** `/` 进行分割解析。输入 `/model <ref>` 时请使用 `provider/model` 格式。
- 如果模型 ID 本身包含 `/`（OpenRouter 风格），必须包含提供商前缀（例如：`/model openrouter/moonshotai/kimi-k2`）。
- 如果省略提供商，OpenClaw 会将输入视为别名或**默认提供商**的模型（仅在模型 ID 中不含 `/` 时有效）。
- `/model status` 是详细视图（认证候选项，以及配置时的提供商端点 `baseUrl` + `api` 模式）。
- 模型引用通过在**第一个** `/` 处分割来解析。输入 `/model <ref>` 时使用 `provider/model`。
- 如果模型 ID 本身包含 `/`（OpenRouter 风格），你必须包含提供商前缀（例如：`/model openrouter/moonshotai/kimi-k2`）。
- 如果省略提供商，OpenClaw 将输入视为别名或**默认提供商**的模型（仅在模型 ID 中没有 `/` 时有效）。
完整命令行为/配置：[斜杠命令](/tools/slash-commands)。
@@ -137,7 +137,7 @@ openclaw models image-fallbacks clear
### `models list`
默认显示已配置的模型。常用标志：
默认显示已配置的模型。有用的标志：
- `--all`：完整目录
- `--local`：仅本地提供商
@@ -147,12 +147,12 @@ openclaw models image-fallbacks clear
### `models status`
显示已解析的主模型、回退模型、图像模型，以及已配置提供商的认证概览。还会显示认证存储中找到的 OAuth 配置过期状态（默认在 24 小时内发出警告）。`--plain` 仅打印已解析的主模型。
显示已解析的主要模型、回退、图像模型，以及已配置提供商的认证概述。它还显示认证存储中找到的配置文件的 OAuth 过期状态（默认在 24 小时内警告）。`--plain` 仅打印已解析的主要模型。
OAuth 状态始终显示（并包含在 `--json` 输出中）。如果已配置的提供商没有凭证，`models status` 会打印 **Missing auth** 部分。
JSON 包含 `auth.oauth`（警告窗口 + 配置文件）和 `auth.providers`（每个提供商的有效认证）。
使用 `--check` 进行自动化检测（缺失/过期时退出码为 `1`，即将过期时为 `2`）。
JSON 包括 `auth.oauth`（警告窗口 + 配置文件）和 `auth.providers`（每个提供商的有效认证）。
使用 `--check` 进行自动化（缺失/过期时退出 `1`，即将过期时退出 `2`）。
推荐的 Anthropic 认证方式是 Claude Code CLI setup-token（可在任何地方运行；如有需要可粘贴到 Gateway网关主机上）：
首选的 Anthropic 认证是 Claude Code CLI setup-token（在任何地方运行；如需要在 Gateway 网关主机上粘贴）：
```bash
claude setup-token
@@ -161,9 +161,9 @@ openclaw models status
## 扫描（OpenRouter 免费模型）
`openclaw models scan` 检查 OpenRouter 的**免费模型目录**，并可选择性地探测模型的工具和图像支持情况。
`openclaw models scan` 检查 OpenRouter 的**免费模型目录**，并可选择性地探测模型的工具和图像支持。
主要标志：
关键标志：
- `--no-probe`：跳过实时探测（仅元数据）
- `--min-params <b>`：最小参数量（十亿）
@@ -173,7 +173,7 @@ openclaw models status
- `--set-default`：将 `agents.defaults.model.primary` 设置为第一个选择
- `--set-image`：将 `agents.defaults.imageModel.primary` 设置为第一个图像选择
探测需要 OpenRouter API 密钥（来自认证配置或 `OPENROUTER_API_KEY`）。没有密钥时，使用 `--no-probe` 仅列出候选模型。
探测需要 OpenRouter API 密钥（来自认证配置文件或 `OPENROUTER_API_KEY`）。没有密钥时，使用 `--no-probe` 仅列出候选项。
扫描结果按以下顺序排名：
@@ -185,12 +185,12 @@ openclaw models status
输入
- OpenRouter `/models` 列表（筛选 `:free`）
- 需要来自认证配置或 `OPENROUTER_API_KEY` 的 OpenRouter API 密钥（参见 [/environment](/environment)）
- 需要来自认证配置文件或 `OPENROUTER_API_KEY` 的 OpenRouter API 密钥（参见 [/environment](/environment)）
- 可选筛选器：`--max-age-days`、`--min-params`、`--provider`、`--max-candidates`
- 探测控制：`--timeout`、`--concurrency`
在 TTY 中运行时，你可以交互式地选择回退模型。在非交互模式下，传入 `--yes` 以接受默认值。
在 TTY 中运行时，你可以交互式选择回退。在非交互模式下，传递 `--yes` 接受默认值。
## 模型注册表（`models.json`）
`models.providers` 中的自定义提供商会被写入智能体目录下的 `models.json`（默认为 `~/.openclaw/agents/<agentId>/models.json`）。除非 `models.mode` 设置为 `replace`，否则此文件默认会被合并。
`models.providers` 中的自定义提供商会写入智能体目录下的 `models.json`（默认 `~/.openclaw/agents/<agentId>/models.json`）。除非 `models.mode` 设置为 `replace`，否则此文件默认会被合并。

135
docs/zh-CN/concepts/multi-agent.md
View File

@@ -1,46 +1,46 @@
---
read_when: 你希望在一个 Gateway网关进程中运行多个隔离的智能体（工作区 + 认证）。
read_when: You want multiple isolated agents (workspaces + auth) in one gateway process.
status: active
summary: 多智能体路由：隔离的智能体、渠道账户和绑定
title: 多智能体路由
x-i18n:
generated_at: "2026-02-01T20:23:55Z"
generated_at: "2026-02-03T07:47:38Z"
model: claude-opus-4-5
provider: pi
source_hash: 1848266c632cd6c96ff99ea9eb9c17bbfe6d35fa1f90450853083e7c548d5324
source_path: concepts/multi-agent.md
workflow: 14
workflow: 15
---
# 多智能体路由
目标：在一个运行中的 Gateway网关中托管多个*隔离的*智能体（独立的工作区 + `agentDir` + 会话），以及多个渠道账户（例如两个 WhatsApp）。入站消息通过绑定路由到对应的智能体。
目标：多个*隔离的*智能体（独立的工作区 + `agentDir` + 会话），加上多个渠道账户（例如两个 WhatsApp）在一个运行的 Gateway 网关中。入站消息通过绑定路由到智能体。
## 什么是"一个智能体"？
一个**智能体**是一个完全独立作用域的大脑，拥有自己的：
- **工作区**（文件、AGENTS.md/SOUL.md/USER.md、本地笔记、人设规则）。
- **状态目录**（`agentDir`），用于存储认证配置文件、模型注册表和按智能体配置。
- **会话存储**（聊天历史 + 路由状态），位于 `~/.openclaw/agents/<agentId>/sessions`。
- **状态目录**（`agentDir`）用于认证配置文件、模型注册表和每智能体配置。
- **会话存储**（聊天历史 + 路由状态）位于 `~/.openclaw/agents/<agentId>/sessions` 下。
认证配置文件是**按智能体隔离的**。每个智能体从自己的目录读取：
认证配置文件是**每智能体独立的**。每个智能体从自己的位置读取：
```
~/.openclaw/agents/<agentId>/agent/auth-profiles.json
```
主智能体的凭证**不会**自动共享。切勿在智能体之间复用 `agentDir`（会导致认证/会话冲突）。如果你想共享凭证，请将 `auth-profiles.json` 复制到另一个智能体的 `agentDir` 中。
主智能体凭证**不会**自动共享。切勿在智能体之间重用 `agentDir`（这会导致认证/会话冲突）。如果你想共享凭证，请将 `auth-profiles.json` 复制到另一个智能体的 `agentDir`。
Skills 通过每个工作区的 `skills/` 文件夹按智能体隔离，共享 Skills 可从 `~/.openclaw/skills` 获取。参阅[Skills：按智能体 vs 共享](/tools/skills#per-agent-vs-shared-skills)。
Skills 通过每个工作区的 `skills/` 文件夹实现每智能体独立，共享的 Skills 可从 `~/.openclaw/skills` 获取。参见 [Skills：每智能体 vs 共享](/tools/skills#per-agent-vs-shared-skills)。
Gateway网关可以托管**一个智能体**（默认）或**多个智能体**并行运行。
Gateway 网关可以托管**一个智能体**（默认）或**多个智能体**并行。
**工作区说明：** 每个智能体的工作区是**默认工作目录**，而非严格的沙箱。相对路径在工作区内解析，但绝对路径可以访问主机上的其他位置，除非启用了沙箱。参阅[沙箱](/gateway/sandboxing)。
**工作区注意事项：** 每个智能体的工作区是**默认 cwd**，而不是硬性沙箱。相对路径在工作区内解析，但绝对路径可以访问主机的其他位置，除非启用了沙箱隔离。参见 [沙箱隔离](/gateway/sandboxing)。
## 路径（速查）
## 路径（快速映射）
- 配置文件：`~/.openclaw/openclaw.json`（或 `OPENCLAW_CONFIG_PATH`）
- 配置：`~/.openclaw/openclaw.json`（或 `OPENCLAW_CONFIG_PATH`）
- 状态目录：`~/.openclaw`（或 `OPENCLAW_STATE_DIR`）
- 工作区：`~/.openclaw/workspace`（或 `~/.openclaw/workspace-<agentId>`）
- 智能体目录：`~/.openclaw/agents/<agentId>/agent`（或 `agents.list[].agentDir`）
@@ -48,11 +48,11 @@ Gateway网关可以托管**一个智能体**（默认）或**多个智能体**
### 单智能体模式（默认）
如果你不做任何配置，OpenClaw 会运行单个智能体：
如果你什么都不做，OpenClaw 运行单个智能体：
- `agentId` 默认为 **`main`**。
- 会话键格式为 `agent:main:<mainKey>`。
- 工作区默认为 `~/.openclaw/workspace`（设置了 `OPENCLAW_PROFILE` 时为 `~/.openclaw/workspace-<profile>`）。
- 会话键为 `agent:main:<mainKey>`。
- 工作区默认为 `~/.openclaw/workspace`（或当设置了 `OPENCLAW_PROFILE` 时为 `~/.openclaw/workspace-<profile>`）。
- 状态默认为 `~/.openclaw/agents/main/agent`。
## 智能体助手
@@ -65,27 +65,27 @@ openclaw agents add work
然后添加 `bindings`（或让向导完成）来路由入站消息。
验证方式：
验证：
```bash
openclaw agents list --bindings
```
## 多智能体 = 多用户、多人设
## 多个智能体 = 多个人、多种人格
使用**多个智能体**时，每个 `agentId` 都成为一个**完全隔离的人设**：
使用**多个智能体**，每个 `agentId` 成为一个**完全隔离的人格**：
- **不同的手机号/账户**（按渠道 `accountId`）。
- **不同的性格**（按智能体工作区文件，如 `AGENTS.md` 和 `SOUL.md`）。
- **独立的认证 + 会话**（除非显式启用，否则无串扰）。
- **不同的电话号码/账户**（每渠道 `accountId`）。
- **不同的人格**（每智能体工作区文件如 `AGENTS.md` 和 `SOUL.md`）。
- **独立的认证 + 会话**（除非明确启用，否则无交叉通信）。
这使得**多个用户**可以共享一台 Gateway网关服务器，同时保持各自的 AI "大脑"和数据隔离。
这让**多个人**共享一个 Gateway 网关服务器，同时保持他们的 AI"大脑"和数据隔离。
## 一个 WhatsApp 号码，多个用户（私聊分流）
## 一个 WhatsApp 号码，多个人（私信分割）
你可以将**不同的 WhatsApp 私聊**路由到不同的智能体，同时使用**同一个 WhatsApp 账户**。通过发送者的 E.164 格式号码（如 `+15551234567`）配合 `peer.kind: "dm"` 进行匹配。回复仍然从同一个 WhatsApp 号码发出（没有按智能体的发送者身份）。
你可以将**不同的 WhatsApp 私信**路由到不同的智能体，同时保持**一个 WhatsApp 账户**。使用 `peer.kind: "dm"` 匹配发送者 E.164（如 `+15551234567`）。回复仍然来自同一个 WhatsApp 号码（无每智能体发送者身份）。
重要细节：私聊会折叠到智能体的**主会话键**，因此真正的隔离需要**每人一个智能体**。
重要细节：直接聊天折叠到智能体的**主会话键**，因此真正的隔离需要**每人一个智能体**。
示例：
@@ -110,32 +110,32 @@ openclaw agents list --bindings
}
```
说明：
注意事项：
- 私聊访问控制是**按 WhatsApp 账户全局的**（配对/白名单），而非按智能体。
- 对于共享群组，将群组绑定到一个智能体或使用[广播群组](/broadcast-groups)。
- 私信访问控制是**每 WhatsApp 账户全局的**（配对/允许列表），而不是每智能体。
- 对于共享群组，将群组绑定到一个智能体或使用 [广播群组](/broadcast-groups)。
## 路由规则（消息如何选择智能体）
绑定是**确定性的**，遵循**最精确匹配优先**原则：
绑定是**确定性的**，**最具体的优先**：
1. `peer` 匹配（精确的私聊/群组/渠道 ID）
1. `peer` 匹配（精确私信/群组/频道 id）
2. `guildId`（Discord）
3. `teamId`（Slack）
4. `accountId` 匹配（按渠道）
4. 渠道的 `accountId` 匹配
5. 渠道级匹配（`accountId: "*"`）
6. 回退到默认智能体（`agents.list[].default`，否则取列表第一项，默认值：`main`）
6. 回退到默认智能体（`agents.list[].default`，否则列表中的第一个条目，默认：`main`）
## 多账户/多手机号
## 多账户/电话号码
支持**多账户**的渠道（如 WhatsApp）使用 `accountId` 来标识每个登录。每个 `accountId` 可以路由到不同的智能体，这样一台服务器就可以托管多个手机号而不会混淆会话。
支持**多账户**的渠道（如 WhatsApp）使用 `accountId` 来识别每个登录。每个 `accountId` 可以路由到不同的智能体，因此一个服务器可以托管多个电话号码而不混合会话。
## 概念
- `agentId`：一个"大脑"（工作区、按智能体认证、按智能体会话存储）。
- `agentId`：一个"大脑"（工作区、每智能体认证、每智能体会话存储）。
- `accountId`：一个渠道账户实例（例如 WhatsApp 账户 `"personal"` vs `"biz"`）。
- `binding`：通过 `(channel, accountId, peer)` 以及可选的 guild/team ID 将入站消息路由到 `agentId`。
- 私聊折叠到 `agent:<agentId>:<mainKey>`（按智能体的"主会话"；`session.mainKey`）。
- `binding`：通过 `(channel, accountId, peer)` 以及可选的 guild/team id 将入站消息路由到 `agentId`。
- 直接聊天折叠到 `agent:<agentId>:<mainKey>`（每智能体"主"；`session.mainKey`）。
## 示例：两个 WhatsApp → 两个智能体
@@ -161,12 +161,12 @@ openclaw agents list --bindings
],
},
// 确定性路由：第一个匹配生效（最精确的在前）。
// 确定性路由：第一个匹配获胜（最具体的优先）。
bindings: [
{ agentId: "home", match: { channel: "whatsapp", accountId: "personal" } },
{ agentId: "work", match: { channel: "whatsapp", accountId: "biz" } },
// 可选的按对端覆盖（示例：将特定群组发送到 work 智能体）。
// 可选的每对等方覆盖（示例：将特定群组发送到 work 智能体）。
{
agentId: "work",
match: {
@@ -177,7 +177,7 @@ openclaw agents list --bindings
},
],
// 默认关闭：智能体间消息传递必须显式启用 + 白名单。
// 默认关闭：智能体到智能体的消息必须明确启用 + 加入允许列表。
tools: {
agentToAgent: {
enabled: false,
@@ -189,11 +189,11 @@ openclaw agents list --bindings
whatsapp: {
accounts: {
personal: {
// 可选覆盖。默认值：~/.openclaw/credentials/whatsapp/personal
// 可选覆盖。默认：~/.openclaw/credentials/whatsapp/personal
// authDir: "~/.openclaw/credentials/whatsapp/personal",
},
biz: {
// 可选覆盖。默认值：~/.openclaw/credentials/whatsapp/biz
// 可选覆盖。默认：~/.openclaw/credentials/whatsapp/biz
// authDir: "~/.openclaw/credentials/whatsapp/biz",
},
},
@@ -204,7 +204,7 @@ openclaw agents list --bindings
## 示例：WhatsApp 日常聊天 + Telegram 深度工作
按渠道分流：将 WhatsApp 路由到快速日常智能体，将 Telegram 路由到 Opus 智能体。
按渠道分割：将 WhatsApp 路由到快速日常智能体，Telegram 路由到 Opus 智能体。
```json5
{
@@ -231,14 +231,14 @@ openclaw agents list --bindings
}
```
说明：
注意事项：
- 如果一个渠道有多个账户，请在绑定中添加 `accountId`（例如 `{ channel: "whatsapp", accountId: "personal" }`）。
- 要将单个私聊/群组路由到 Opus 而其余保持在 chat 上，请为该对端添加 `match.peer` 绑定；对端匹配始终优先于渠道级规则。
- 如果你有一个渠道的多个账户，请在绑定中添加 `accountId`（例如 `{ channel: "whatsapp", accountId: "personal" }`）。
- 要将单个私信/群组路由到 Opus 而保持其余在 chat 上，请为该对等方添加 `match.peer` 绑定；对等方匹配始终优先于渠道级规则。
## 示例：同一渠道，将一个对端路由到 Opus
## 示例：同一渠道，一个对等方到 Opus
将 WhatsApp 保持在快速智能体上，但将一个私聊路由到 Opus：
保持 WhatsApp 在快速智能体上，但将一个私信路由到 Opus：
```json5
{
@@ -265,11 +265,11 @@ openclaw agents list --bindings
}
```
对端绑定始终优先，因此请将它们放在渠道级规则之上。
对等方绑定始终获胜，因此将它们放在渠道级规则之上。
## 绑定到 WhatsApp 群组的家庭智能体
将一个专用家庭智能体绑定到单个 WhatsApp 群组，使用提及控制和更严格的工具策略：
将专用家庭智能体绑定到单个 WhatsApp 群组，使用提及限制和更严格的工具策略：
```json5
{
@@ -314,12 +314,12 @@ openclaw agents list --bindings
}
```
说明：
注意事项：
- 工具允许/拒绝列表针对的是**工具**，而非 Skills。如果某个 Skills 需要运行二进制文件，请确保允许 `exec` 并且该二进制文件存在于沙箱中。
- 要实现更严格的控制，请设置 `agents.list[].groupChat.mentionPatterns` 并为渠道启用群组白名单。
- 工具允许/拒绝列表是**工具**，不是 Skills。如果 skill 需要运行二进制文件，请确保 `exec` 被允许且二进制文件存在于沙箱中。
- 对于更严格的限制，设置 `agents.list[].groupChat.mentionPatterns` 并为渠道保持群组允许列表启用。
## 按智能体的沙箱和工具配置
## 每智能体沙箱和工具配置
从 v2026.1.6 开始，每个智能体可以有自己的沙箱和工具限制：
@@ -331,7 +331,7 @@ openclaw agents list --bindings
id: "personal",
workspace: "~/.openclaw/workspace-personal",
sandbox: {
mode: "off", // 个人智能体不使用沙箱
mode: "off", // 个人智能体无沙箱
},
// 无工具限制 - 所有工具可用
},
@@ -340,15 +340,15 @@ openclaw agents list --bindings
workspace: "~/.openclaw/workspace-family",
sandbox: {
mode: "all", // 始终沙箱隔离
scope: "agent", // 每个智能体一个容器
scope: "agent", // 每智能体一个容器
docker: {
// 容器创建后的可选一次性设置
setupCommand: "apt-get update && apt-get install -y git curl",
},
},
tools: {
allow: ["read"], // 仅允许 read 工具
deny: ["exec", "write", "edit", "apply_patch"], // 拒绝其他工具
allow: ["read"], // 仅 read 工具
deny: ["exec", "write", "edit", "apply_patch"], // 拒绝其他
},
},
],
@@ -356,14 +356,17 @@ openclaw agents list --bindings
}
```
注意：`setupCommand` 位于 `sandbox.docker` 下，在容器创建时运行一次。当解析的 scope 为 `"shared"` 时，按智能体的 `sandbox.docker.*` 覆盖会被忽略。
注意：`setupCommand` 位于 `sandbox.docker` 下，在容器创建时运行一次。
当解析的 scope 为 `"shared"` 时，每智能体 `sandbox.docker.*` 覆盖会被忽略。
**优势：**
**好处：**
- **安全隔离**：限制不受信任的智能体的工具
- **资源控制**：沙箱隔离特定智能体，同时让其他智能体在主机上运行
- **灵活策略**：按智能体设置不同权限
- **安全隔离**：限制不受信任智能体的工具
- **资源控制**：沙箱隔离特定智能体同时保持其他智能体在主机上
- **灵活策略**：每智能体不同的权限
注意：`tools.elevated` 是**全局的**且基于发送者；不能按智能体配置。如果你需要按智能体的边界，请使用 `agents.list[].tools` 来拒绝 `exec`。对于群组定向，请使用 `agents.list[].groupChat.mentionPatterns`，以便 @提及能准确映射到目标智能体。
注意：`tools.elevated` 是**全局的**且基于发送者；不能按智能体配置。
如果你需要每智能体边界，使用 `agents.list[].tools` 拒绝 `exec`。
对于群组定向，使用 `agents.list[].groupChat.mentionPatterns` 使 @提及清晰地映射到目标智能体。
参阅[多智能体沙箱与工具](/multi-agent-sandbox-tools)获取详细示例。
参见 [多智能体沙箱和工具](/multi-agent-sandbox-tools) 了解详细示例。

80
docs/zh-CN/concepts/presence.md
View File

@@ -1,99 +1,99 @@
---
read_when:
- 调试实例选项卡
- 调试实例标签页
- 排查重复或过期的实例行
- 更改 Gateway网关 WebSocket 连接或系统事件信标
summary: OpenClaw 在线状态条目的生成、合并与显示方式
- 更改 Gateway 网关 WS 连接或系统事件信标
summary: OpenClaw 在线状态条目如何生成、合并和显示
title: 在线状态
x-i18n:
generated_at: "2026-02-01T20:23:31Z"
generated_at: "2026-02-03T07:46:37Z"
model: claude-opus-4-5
provider: pi
source_hash: c752c76a880878fed673d656db88beb5dbdeefff2491985127ad791521f97d00
source_path: concepts/presence.md
workflow: 14
workflow: 15
---
# 在线状态
OpenClaw 的"在线状态"是一个轻量级、尽力而为的视图，展示：
OpenClaw"在线状态"是以下内容的轻量级、尽力而为的视图：
- **Gateway网关** 自身，以及
- **连接到 Gateway网关的客户端**（Mac 应用、WebChat、CLI 等）
- **Gateway 网关**本身，以及
- **连接到 Gateway 网关的客户端**（mac 应用、WebChat、CLI 等）
在线状态主要用于渲染 macOS 应用的**实例**选项卡，并为操作人员提供快速可视化。
在线状态主要用于渲染 macOS 应用的**实例**标签页，并为运维人员提供快速可见性。
## 在线状态字段（显示内容）
## 在线状态字段（显示的内容）
在线状态条目是结构化对象，包含以下字段：
在线状态条目是具有以下字段的结构化对象：
- `instanceId`（可选但强烈建议提供）：稳定的客户端标识（通常为 `connect.client.instanceId`）
- `host`：人类可读的主机名
- `instanceId`（可选但强烈推荐）：稳定的客户端身份（通常是 `connect.client.instanceId`）
- `host`：人类友好的主机名
- `ip`：尽力而为的 IP 地址
- `version`：客户端版本字符串
- `deviceFamily` / `modelIdentifier`：硬件提示信息
- `deviceFamily` / `modelIdentifier`：硬件提示
- `mode`：`ui`、`webchat`、`cli`、`backend`、`probe`、`test`、`node`，...
- `lastInputSeconds`："距上次用户输入的秒数"（如果已知）
- `lastInputSeconds`："自上次用户输入以来的秒数"（如果已知）
- `reason`：`self`、`connect`、`node-connected`、`periodic`，...
- `ts`：最后更新时间戳（自纪元以来的毫秒数）
## 生产者（在线状态的来源）
## 生产者（在线状态来源）
在线状态条目由多个来源产生并进行**合并**。
在线状态条目由多个来源生成并**合并**。
### 1）Gateway网关自身条目
### 1）Gateway 网关自身条目
Gateway网关在启动时始终会创建一个"self"条目，这样即使在任何客户端连接之前，UI 也能显示 Gateway网关主机。
Gateway 网关始终在启动时植入一个"self"条目，这样即使在任何客户端连接之前，UI 也能显示 Gateway 网关主机。
### 2）WebSocket 连接
每个 WebSocket 客户端都以 `connect` 请求开始。握手成功后，Gateway网关会为该连接更新插入一个在线状态条目。
每个 WS 客户端都以 `connect` 请求开始。在成功握手后，Gateway 网关为该连接更新插入一个在线状态条目。
#### 为什么一次性 CLI 命令不会显示
CLI 通常只为短暂的一次性命令建立连接。为避免实例列表被频繁刷新，`client.mode === "cli"` **不会**被转换为在线状态条目。
CLI 经常为短暂的一次性命令进行连接。为避免实例列表被刷屏，`client.mode === "cli"` **不会**被转换为在线状态条目。
### 3）`system-event` 信标
客户端可以通过 `system-event` 方法发送更丰富的周期性信标。Mac 应用使用此机制报告主机名、IP 和 `lastInputSeconds`。
客户端可以通过 `system-event` 方法发送更丰富的周期性信标。mac 应用使用此方法报告主机名、IP 和 `lastInputSeconds`。
### 4）节点连接（role: node）
当节点通过 Gateway网关 WebSocket 以 `role: node` 连接时，Gateway网关会为该节点更新插入一个在线状态条目（与其他 WebSocket 客户端流程相同）。
当节点通过 Gateway 网关 WebSocket 以 `role: node` 连接时，Gateway 网关为该节点更新插入一个在线状态条目（与其他 WS 客户端流程相同）。
## 合并与去重规则（为什么 `instanceId` 很重要）
## 合并 + 去重规则（为什么 `instanceId` 很重要）
在线状态条目存储在单个内存映射中：
- 条目以**在线状态键**作为索引。
- 最佳键是稳定的 `instanceId`（来自 `connect.client.instanceId`），可在重启后保持不变。
- 条目以**在线状态键**为索引。
- 最佳键是稳定的 `instanceId`（来自 `connect.client.instanceId`），它在重启后仍然有效。
- 键不区分大小写。
如果客户端在没有稳定 `instanceId` 的情况下重新连接，可能会显示为**重复**行。
如果客户端在没有稳定 `instanceId` 的情况下重新连接，它可能会显示为**重复**行。
## TTL 和大小限制
## TTL 和有界大小
在线状态是有意设计为临时性的：
在线状态是有意设计为短暂的：
- **TTL：**超过 5 分钟的条目将被清除
- **最大条目数：**200（优先丢弃最旧的条目）
- **TTL：** 超过 5 分钟的条目会被修剪
- **最大条目数：** 200（最旧的优先删除）
这确保列表保持新鲜，避免无限制的内存增长。
这使列表保持新鲜并避免无限制的内存增长。
## 远程/隧道注意事项（local loopback IP）
## 远程/隧道注意事项（回环 IP）
当客户端通过 SSH 隧道/本地端口转发连接时，Gateway网关可能会将远程地址识别为 `127.0.0.1`。为避免覆盖客户端报告的有效 IP，local loopback 远程地址会被忽略。
当客户端通过 SSH 隧道/本地端口转发连接时，Gateway 网关可能会看到远程地址为 `127.0.0.1`。为避免覆盖客户端报告的有效 IP，回环远程地址会被忽略。
## 消费者
### macOS 实例选项卡
### macOS 实例标签页
macOS 应用渲染 `system-presence` 的输出，并根据最后更新的时间显示小型状态指示器（活跃/空闲/过期）。
macOS 应用渲染 `system-presence` 的输出，并根据最后更新的时间应用一个小的状态指示器（活跃/空闲/过期）。
## 调试技巧
- 要查看原始列表，请对 Gateway网关调用 `system-presence`。
- 如果看到重复条目：
- 确认客户端在握手中发送了稳定的 `client.instanceId`
- 要查看原始列表，对 Gateway 网关调用 `system-presence`。
- 如果你看到重复项：
- 确认客户端在握手中发送稳定的 `client.instanceId`
- 确认周期性信标使用相同的 `instanceId`
- 检查连接派生的条目是否缺少 `instanceId`（此时重复是预期行为）
- 检查连接派生的条目是否缺少 `instanceId`（这种情况下重复是预期的）

68
docs/zh-CN/concepts/queue.md
View File

@@ -1,53 +1,53 @@
---
read_when:
- 更改自动回复执行或并发机制
summary: 序列化入站自动回复运行的命令队列设计
- 更改自动回复执行或并发设置时
summary: 用于序列化入站自动回复运行的命令队列设计
title: 命令队列
x-i18n:
generated_at: "2026-02-01T20:23:48Z"
generated_at: "2026-02-03T10:05:28Z"
model: claude-opus-4-5
provider: pi
source_hash: 2104c24d200fb4f9620e52a19255cd614ababe19d78f3ee42936dc6d0499b73b
source_path: concepts/queue.md
workflow: 14
workflow: 15
---
# 命令队列（2026-01-16）
我们通过一个轻量的进程内队列来序列化入站自动回复运行（所有渠道），以防止多个智能体运行发生冲突，同时仍允许跨会话的安全并行。
我们通过一个小型进程内队列序列化入站自动回复运行（所有渠道），以防止多个智能体运行发生冲突，同时仍允许跨会话的安全并行。
## 原因
## 为什么需要
- 自动回复运行可能开销很大（LLM 调用），当多条入站消息几乎同时到达时可能发生冲突。
- 序列化可以避免争用共享资源（会话文件、日志、CLI 标准输入），并降低触发上游速率限制的概率。
- 自动回复运行可能开销很大（LLM 调用），当多条入站消息接近同时到达时可能发生冲突。
- 序列化可以避免竞争共享资源（会话文件、日志、CLI stdin），并降低上游速率限制的可能性。
## 工作原理
- 一个支持通道感知的 FIFO 队列以可配置的并发上限逐通道排空（未配置的通道默认为 1；main 默认为 4，subagent 默认为 8）。
- `runEmbeddedPiAgent` 按**会话键**（通道 `session:<key>`）入队，以保证每个会话同一时间只有一个活跃运行。
- 每个会话运行随后被排入**全局通道**（默认为 `main`），因此整体并行度受 `agents.defaults.maxConcurrent` 限制。
- 启用详细日志时，如果排队的运行在启动前等待超过约 2 秒，会发出一条简短通知。
- 输入指示器在入队时仍会立即触发（当渠道支持时），因此在等待期间用户体验不受影响。
- 一个支持通道感知的 FIFO 队列以可配置的并发上限排空每个通道（未配置的通道默认为 1；main 默认为 4，subagent 为 8）。
- `runEmbeddedPiAgent` 按**会话键**入队（通道 `session:<key>`），以保证每个会话只有一个活动运行。
- 然后每个会话运行被排入**全局通道**（默认为 `main`），因此整体并行度受 `agents.defaults.maxConcurrent` 限制。
- 启用详细日志时，如果排队运行在开始前等待超过约 2 秒，会发出简短通知。
- 输入指示器仍在入队时立即触发（当渠道支持时），因此在等待轮次时用户体验不受影响。
## 队列模式（按渠道）
入站消息可以引导当前运行、等待后续轮次，或两者兼顾：
- `steer`：立即注入当前运行（在下一个工具边界后取消待执行的工具调用）。如果未在流式传输，则回退为 followup。
- `followup`：在当前运行结束后排队等待下一个智能体轮次。
- `steer`：立即注入当前运行（在下一个工具边界后取消待处理的工具调用）。如果未在流式传输，则回退到 followup。
- `followup`：在当前运行结束后为下一个智能体轮次入队。
- `collect`：将所有排队消息合并为**单个**后续轮次（默认）。如果消息针对不同的渠道/线程，它们会单独排空以保留路由。
- `steer-backlog`（又名 `steer+backlog`）：立即引导**并且**保留消息用于后续轮次。
- `interrupt`（旧版）：中止该会话的活跃运行，然后运行最新消息。
- `queue`（旧版别名）：等同于 `steer`。
- `steer-backlog`（又名 `steer+backlog`）：现在引导**并**保留消息用于后续轮次。
- `interrupt`（旧版）：中止该会话的活动运行，然后运行最新消息。
- `queue`（旧版别名）：与 `steer` 相同。
steer-backlog 意味着在引导运行之后你还能获得后续响应，因此流式传输界面可能看起来像重复内容。如果希望每条入站消息只获得一次响应，请优先使用 `collect`/`steer`。
发送 `/queue collect` 作为独立命令（按会话生效），或设置 `messages.queue.byChannel.discord: "collect"`。
steer-backlog 意味着你可以在被引导的运行之后获得后续响应，因此流式传输界面可能看起来像重复。如果你希望每条入站消息只有一个响应，请优先使用 `collect`/`steer`。
发送 `/queue collect` 作为独立命令（按会话）或设置 `messages.queue.byChannel.discord: "collect"`。
默认值（配置中未设置时）：
- 所有界面 → `collect`
通过 `messages.queue` 进行全局或按渠道配置：
通过 `messages.queue` 全局或按渠道配置：
```json5
{
@@ -65,30 +65,30 @@ steer-backlog 意味着在引导运行之后你还能获得后续响应，因此
## 队列选项
选项适用于 `followup`、`collect` 和 `steer-backlog`（以及 `steer` 回退为 followup 时）：
选项适用于 `followup`、`collect` 和 `steer-backlog`（以及当 `steer` 回退到 followup 时）：
- `debounceMs`：在启动后续轮次前等待静默期（防止"继续，继续"的情况）。
- `debounceMs`：在开始后续轮次前等待静默（防止"继续，继续"）。
- `cap`：每个会话的最大排队消息数。
- `drop`：溢出策略（`old`、`new`、`summarize`）。
summarize 会保留一个被丢弃消息的简短要点列表，并将其作为合成的后续提示词注入。
summarize 保留被丢弃消息的简短要点列表，并将其作为合成的后续提示注入。
默认值：`debounceMs: 1000`、`cap: 20`、`drop: summarize`。
## 按会话覆盖
- 发送 `/queue <mode>` 作为独立命令，可将该模式存储到当前会话。
- 选项可以组合使用：`/queue collect debounce:2s cap:25 drop:summarize`
- 发送 `/queue <mode>` 作为独立命令，为当前会话存储该模式。
- 选项可以组合：`/queue collect debounce:2s cap:25 drop:summarize`
- `/queue default` 或 `/queue reset` 清除会话覆盖。
## 作用范围与保证
## 范围和保证
- 适用于所有使用 Gateway网关回复管道的入站渠道的自动回复智能体运行（WhatsApp 网页版、Telegram、Slack、Discord、Signal、iMessage、网页聊天等）。
- 默认通道（`main`）在进程范围内适用于入站消息和主心跳；设置 `agents.defaults.maxConcurrent` 以允许多个会话并行。
- 可能存在其他通道（如 `cron`、`subagent`），以便后台任务可以并行运行而不阻塞入站回复。
- 按会话通道保证同一时间只有一个智能体运行接触给定会话。
- 无外部依赖或后台工作线程；纯 TypeScript + Promise 实现。
- 适用于所有使用 Gateway 网关回复管道的入站渠道的自动回复智能体运行（WhatsApp 网页版、Telegram、Slack、Discord、Signal、iMessage、网页聊天等）。
- 默认通道（`main`）对入站 + 主心跳是进程范围的；设置 `agents.defaults.maxConcurrent` 以允许多个会话并行。
- 可能存在额外的通道（例如 `cron`、`subagent`），以便后台任务可以并行运行而不阻塞入站回复。
- 按会话通道保证一次只有一个智能体运行触及给定会话。
- 无外部依赖或后台工作线程；纯 TypeScript + promises。
## 故障排除
- 如果命令似乎卡住，启用详细日志并查找 "queued for …ms" 行，以确认队列正在正常排空。
- 如果需要查看队列深度，启用详细日志并观察队列计时行。
- 如果命令似乎卡住，启用详细日志并查找"queued for …ms"行以确认队列正在排空。
- 如果你需要查看队列深度，启用详细日志并观察队列计时行。

76
docs/zh-CN/concepts/session-pruning.md
View File

@@ -1,72 +1,72 @@
---
read_when:
- 你想减少工具输出导致的 LLM 上下文增长
- 你正在调优 agents.defaults.contextPruning
summary: 会话裁剪：通过修剪工具结果来减少上下文膨胀
- 你正在调整 agents.defaults.contextPruning
summary: 会话剪枝：工具结果修剪以减少上下文膨胀
x-i18n:
generated_at: "2026-02-01T20:23:53Z"
generated_at: "2026-02-03T07:46:35Z"
model: claude-opus-4-5
provider: pi
source_hash: 9b0aa2d1abea7050ba848a2db038ccc3e6e2d83c6eb4e3843a2ead0ab847574a
source_path: concepts/session-pruning.md
workflow: 14
workflow: 15
---
# 会话裁剪
# 会话剪枝
会话裁剪在每次 LLM 调用之前修剪内存上下文中的**旧工具结果**。它**不会**重写磁盘上的会话历史（`*.jsonl`）。
会话剪枝在每次 LLM 调用之前从内存上下文中修剪**旧的工具结果**。它**不会**重写磁盘上的会话历史（`*.jsonl`）。
## 运行时机
- 当启用 `mode: "cache-ttl"` 且该会话的上次 Anthropic 调用时间超过 `ttl` 时触发。
- 当启用 `mode: "cache-ttl"` 且该会话的最后一次 Anthropic 调用早于 `ttl` 时。
- 仅影响该请求发送给模型的消息。
- 仅对 Anthropic API 调用（以及 OpenRouter Anthropic 模型）生效。
- 为获得最佳效果，请将 `ttl` 与模型的 `cacheControlTtl` 保持一致。
- 裁剪后，TTL 窗口会重置，后续请求将继续使用缓存直到 `ttl` 再次过期。
- 仅对 Anthropic API 调用（和 OpenRouter Anthropic 模型）生效。
- 为获得最佳效果，请将 `ttl` 与你的模型 `cacheControlTtl` 匹配。
- 剪枝后，TTL 窗口会重置，因此后续请求会保持缓存直到 `ttl` 再次过期。
## 智能默认值（Anthropic）
- **OAuth 或 setup-token** 配置文件：启用 `cache-ttl` 裁剪，并将心跳设置为 `1h`。
- **API 密钥**配置文件：启用 `cache-ttl` 裁剪，将心跳设置为 `30m`，并将 Anthropic 模型的 `cacheControlTtl` 默认设为 `1h`。
- **OAuth 或 setup-token** 配置文件：启用 `cache-ttl` 剪枝并将心跳设置为 `1h`。
- **API 密钥**配置文件：启用 `cache-ttl` 剪枝，将心跳设置为 `30m`，并将 Anthropic 模型的 `cacheControlTtl` 默认为 `1h`。
- 如果你显式设置了这些值中的任何一个，OpenClaw **不会**覆盖它们。
## 改善效果（成本 + 缓存行为）
## 改进内容（成本 + 缓存行为）
- **为什么要裁剪：** Anthropic 提示缓存仅在 TTL 内生效。如果会话空闲超过 TTL，下一次请求将重新缓存完整提示，除非你先对其进行修剪。
- **哪些费用会降低：** 裁剪减少了 TTL 过期后首次请求的 **cacheWrite** 大小。
- **为什么 TTL 重置很重要：** 裁剪运行后，缓存窗口会重置，因此后续请求可以复用新缓存的提示，而不是再次重新缓存完整历史。
- **它不会做什么：** 裁剪不会增加令牌或"翻倍"成本；它只改变 TTL 过期后首次请求的缓存内容。
- **为什么要剪枝：** Anthropic 提示缓存仅在 TTL 内适用。如果会话空闲超过 TTL，下一个请求会重新缓存完整提示，除非你先修剪它。
- **什么变得更便宜：** 剪枝减少了 TTL 过期后第一个请求的 **cacheWrite** 大小。
- **为什么 TTL 重置很重要：** 一旦剪枝运行，缓存窗口会重置，因此后续请求可以重用新缓存的提示，而不是再次重新缓存完整历史。
- **它不做什么：** 剪枝不会添加 token 或"双倍"成本；它只改变该 TTL 后第一个请求缓存的内容。
## 可裁剪的内容
## 可以剪枝的内容
- 仅限 `toolResult` 消息。
- 用户和助手消息**永远不会**被修改。
- 最后 `keepLastAssistants` 条助手消息受保护；该截止点之后的工具结果不会被裁剪。
- 如果助手消息数量不足以确定截止点，则跳过裁剪。
- 包含**图片块**的工具结果会被跳过（永远不会被修剪/清除）。
- 仅 `toolResult` 消息。
- 用户 + 助手消息**永远不会**被修改。
- 最后 `keepLastAssistants` 条助手消息受保护；该截止点之后的工具结果不会被剪枝。
- 如果没有足够的助手消息来确定截止点，则跳过剪枝。
- 包含**图像块**的工具结果会被跳过（永不修剪/清除）。
## 上下文窗口估算
裁剪使用估算的上下文窗口（字符数 ≈ 令牌数 × 4）。基础窗口按以下顺序解析：
剪枝使用估算的上下文窗口（字符 ≈ token × 4）。基础窗口按以下顺序解析：
1. `models.providers.*.models[].contextWindow` 覆盖值。
2. 模型定义中的 `contextWindow`（来自模型注册表）。
3. 默认 `200000` 令牌。
1. `models.providers.*.models[].contextWindow` 覆盖。
2. 模型定义 `contextWindow`（来自模型注册表）。
3. 默认 `200000` token。
如果设置了 `agents.defaults.contextTokens`，它将作为解析窗口的上限（取最小值）。
如果设置了 `agents.defaults.contextTokens`，它将被视为解析窗口的上限（最小值）。
## 模式
### cache-ttl
- 仅当上次 Anthropic 调用时间超过 `ttl`（默认 `5m`）时才运行裁剪。
- 仅当最后一次 Anthropic 调用早于 `ttl`（默认 `5m`）时才运行剪枝。
- 运行时：与之前相同的软修剪 + 硬清除行为。
## 软裁剪与硬裁剪
## 软剪枝 vs 硬剪枝
- **软修剪**：仅针对超大的工具结果。
- 保留头部和尾部，插入 `...`，并附加一条包含原始大小的说明。
- 跳过包含图片块的结果。
- **软修剪**：仅用于过大的工具结果。
- 保留头部 + 尾部，插入 `...`，并附加一个包含原始大小的注释。
- 跳过包含图像块的结果。
- **硬清除**：用 `hardClear.placeholder` 替换整个工具结果。
## 工具选择
@@ -78,8 +78,8 @@ x-i18n:
## 与其他限制的交互
- 内置工具已经会截断自身的输出；会话裁剪是一个额外的保护层，防止长时间运行的对话在模型上下文中积累过多的工具输出。
- 压缩是独立的：压缩会进行摘要并持久化，裁剪则是每次请求的临时操作。参见 [/concepts/compaction](/concepts/compaction)。
- 内置工具已经截断自己的输出；会话剪枝是一个额外的层，防止长时间运行的聊天在模型上下文中累积过多的工具输出。
- 压缩是独立的：压缩进行总结并持久化，剪枝是每个请求的临时操作。参阅 [/concepts/compaction](/concepts/compaction)。
## 默认值（启用时）
@@ -103,7 +103,7 @@ x-i18n:
}
```
启用 TTL 感知裁剪：
启用 TTL 感知剪枝：
```json5
{
@@ -113,7 +113,7 @@ x-i18n:
}
```
将裁剪限制为特定工具：
限制剪枝到特定工具：
```json5
{
@@ -126,4 +126,4 @@ x-i18n:
}
```
参见配置参考：[Gateway网关配置](/gateway/configuration)
参阅配置参考：[Gateway 网关配置](/gateway/configuration)

120
docs/zh-CN/concepts/session-tool.md
View File

@@ -1,20 +1,20 @@
---
read_when:
- 添加或修改会话工具
summary: 智能体会话工具：列出会话、获取历史记录和发送跨会话消息
- 添加或修改会话工具时
summary: 用于列出会话、获取历史记录和发送跨会话消息的智能体会话工具
title: 会话工具
x-i18n:
generated_at: "2026-02-01T20:24:08Z"
generated_at: "2026-02-03T07:46:54Z"
model: claude-opus-4-5
provider: pi
source_hash: cb6e0982ebf507bcf9de4bb17719759c2b6d3e519731c845580a55279084e4c8
source_path: concepts/session-tool.md
workflow: 14
workflow: 15
---
# 会话工具
目标：提供小型、不易误用的工具集，使智能体能够列出会话、获取历史记录以及向其他会话发送消息。
目标：小型、不易误用的工具集，使智能体能够列出会话、获取历史记录并向另一个会话发送消息。
## 工具名称
@@ -25,62 +25,62 @@ x-i18n:
## 键模型
- 主私聊桶始终使用字面键 `"main"`（解析为当前智能体的主键）。
- 群聊使用 `agent:<agentId>:<channel>:group:<id>` 或 `agent:<agentId>:<channel>:channel:<id>`（传入完整键）。
- 主直接聊天桶始终是字面键 `"main"`（解析为当前智能体的主键）。
- 群聊使用 `agent:<agentId>:<channel>:group:<id>` 或 `agent:<agentId>:<channel>:channel:<id>`（传递完整键）。
- 定时任务使用 `cron:<job.id>`。
- 钩子使用 `hook:<uuid>`，除非显式设置。
- 节点会话使用 `node-<nodeId>`，除非显式设置。
- Hooks 使用 `hook:<uuid>`，除非明确设置。
- Node 会话使用 `node-<nodeId>`，除非明确设置。
`global` 和 `unknown` 是保留值，永远不会被列出。如果 `session.scope = "global"`，我们会将其别名为 `main` 供所有工具使用，这样调用方永远看不到 `global`。
`global` 和 `unknown` 是保留值，永远不会被列出。如果 `session.scope = "global"`，我们会将其别名为 `main` 用于所有工具，这样调用者永远不会看到 `global`。
## sessions_list
以行数组形式列出会话。
将会话列为行数组。
参数：
- `kinds?: string[]` 过滤器：`"main" | "group" | "cron" | "hook" | "node" | "other"` 的任意组合
- `limit?: number` 最大行数（默认：服务器默认值，上限如 200）
- `activeMinutes?: number` 仅返回 N 分钟内更新的会话
- `messageLimit?: number` 0 = 不返回消息（默认 0）；>0 = 包含最近 N 条消息
- `kinds?: string[]` 过滤器：`"main" | "group" | "cron" | "hook" | "node" | "other"` 中的任意一个
- `limit?: number` 最大行数（默认：服务器默认值，限制如 200）
- `activeMinutes?: number` 仅在 N 分钟内更新的会话
- `messageLimit?: number` 0 = 无消息（默认 0）；>0 = 包含最后 N 条消息
行为：
- `messageLimit > 0` 时会获取每个会话的 `chat.history` 并包含最近 N 条消息。
- 列表输出中会过滤工具结果；使用 `sessions_history` 获取工具消息。
- 在**沙箱隔离**的智能体会话中运行时，会话工具默认为**仅已生成可见**（见下文）。
- `messageLimit > 0` 获取每个会话的 `chat.history` 并包含最后 N 条消息。
- 工具结果在列表输出中被过滤；使用 `sessions_history` 获取工具消息。
- 在**沙箱隔离**的智能体会话中运行时，会话工具默认为**仅生成的可见性**（见下文）。
行结构（JSON）：
- `key`：会话键（字符串）
- `kind`：`main | group | cron | hook | node | other`
- `channel`：`whatsapp | telegram | discord | signal | imessage | webchat | internal | unknown`
- `displayName`（群组显示标签，如可用）
- `displayName`（如果可用的群组显示标签）
- `updatedAt`（毫秒）
- `sessionId`
- `model`、`contextTokens`、`totalTokens`
- `thinkingLevel`、`verboseLevel`、`systemSent`、`abortedLastRun`
- `sendPolicy`（会话覆盖，如已设置）
- `sendPolicy`（如果设置的会话覆盖）
- `lastChannel`、`lastTo`
- `deliveryContext`（规范化的 `{ channel, to, accountId }`，如可用）
- `transcriptPath`（根据存储目录 + sessionId 推导的尽力路径）
- `deliveryContext`（可用时的规范化 `{ channel, to, accountId }`）
- `transcriptPath`（从存储目录 + sessionId 派生的尽力路径）
- `messages?`（仅当 `messageLimit > 0` 时）
## sessions_history
获取单个会话的对话记录。
获取一个会话的记录。
参数：
- `sessionKey`（必需；接受会话键或来自 `sessions_list` 的 `sessionId`）
- `limit?: number` 最大消息数（服务器限制上限）
- `sessionKey`（必填；接受会话键或来自 `sessions_list` 的 `sessionId`）
- `limit?: number` 最大消息数（服务器限制）
- `includeTools?: boolean`（默认 false）
行为：
- `includeTools=false` 过滤 `role: "toolResult"` 的消息。
- 以原始对话记录格式返回消息数组。
- 当传入 `sessionId` 时，OpenClaw 会将其解析为对应的会话键（缺失的 ID 会报错）。
- `includeTools=false` 过滤 `role: "toolResult"` 消息。
- 以原始记录格式返回消息数组。
- 当给定 `sessionId` 时，OpenClaw 将其解析为相应的会话键（缺失的 id 会报错）。
## sessions_send
@@ -88,8 +88,8 @@ x-i18n:
参数：
- `sessionKey`（必需；接受会话键或来自 `sessions_list` 的 `sessionId`）
- `message`（必需）
- `sessionKey`（必填；接受会话键或来自 `sessions_list` 的 `sessionId`）
- `message`（必填）
- `timeoutSeconds?: number`（默认 >0；0 = 即发即忘）
行为：
@@ -98,28 +98,28 @@ x-i18n:
- `timeoutSeconds > 0`：等待最多 N 秒完成，然后返回 `{ runId, status: "ok", reply }`。
- 如果等待超时：`{ runId, status: "timeout", error }`。运行继续；稍后调用 `sessions_history`。
- 如果运行失败：`{ runId, status: "error", error }`。
- 通知投递在主运行完成后运行，属于尽力而为；`status: "ok"` 不保证通知已成功投递。
- 通过 Gateway网关 `agent.wait`（服务器端）等待，因此重连不会中断等待。
- 智能体间消息上下文会注入到主运行中。
- 主运行完成后，OpenClaw 运行**回复往返循环**：
- 第 2 轮及之后在请求方和目标智能体之间交替。
- 回复 `REPLY_SKIP` 可停止来回往返。
- 通告投递在主运行完成后运行，且为尽力而为；`status: "ok"` 不保证通告已投递。
- 通过 Gateway 网关 `agent.wait`（服务器端）等待，因此重连不会丢失等待。
- 智能体到智能体的消息上下文会为主运行注入。
- 主运行完成后，OpenClaw 运行**回复循环**：
- 第 2 轮及以后在请求者和目标智能体之间交替。
- 精确回复 `REPLY_SKIP` 以停止来回。
- 最大轮数为 `session.agentToAgent.maxPingPongTurns`（0–5，默认 5）。
- 循环结束后，OpenClaw 运行**智能体间通知步骤**（仅目标智能体）：
- 回复 `ANNOUNCE_SKIP` 可保持静默。
- 其他任何回复都会发送到目标渠道。
- 通知步骤包含原始请求 + 第 1 轮回复 + 最新的往返回复。
- 循环结束后，OpenClaw 运行**智能体到智能体通告步骤**（仅目标智能体）：
- 精确回复 `ANNOUNCE_SKIP` 以保持静默。
- 任何其他回复都会发送到目标渠道。
- 通告步骤包括原始请求 + 第 1 轮回复 + 最新的来回回复。
## Channel 字段
- 对于群组，`channel` 是会话条目上记录的渠道。
- 对于私聊，`channel` 从 `lastChannel` 映射。
- 对于定时任务/钩子/节点，`channel` 为 `internal`。
- 如果缺失，`channel` 为 `unknown`。
- 对于直接聊天，`channel` 从 `lastChannel` 映射。
- 对于 cron/hook/node，`channel` 是 `internal`。
- 如果缺失，`channel` 是 `unknown`。
## 安全 / 发送策略
基于策略的按渠道/聊天类型阻止（非按会话 ID）。
基于策略的按渠道/聊天类型阻止（不是按会话 id）。
```json
{
@@ -144,45 +144,45 @@ x-i18n:
执行点：
- `chat.send` / `agent`（Gateway网关）
- `chat.send` / `agent`（Gateway 网关）
- 自动回复投递逻辑
## sessions_spawn
在隔离会话中生成子智能体运行，并将结果通知回请求方的聊天渠道。
在隔离会话中生成子智能体运行，并将结果通告回请求者聊天渠道。
参数：
- `task`（必需）
- `task`（必填）
- `label?`（可选；用于日志/UI）
- `agentId?`（可选；如允许，在另一个智能体 ID 下生成）
- `agentId?`（可选；如果允许，在另一个智能体 id 下生成）
- `model?`（可选；覆盖子智能体模型；无效值会报错）
- `runTimeoutSeconds?`（默认 0；设置后，N 秒后中止子智能体运行）
- `runTimeoutSeconds?`（默认 0；设置时，在 N 秒后中止子智能体运行）
- `cleanup?`（`delete|keep`，默认 `keep`）
允许列表：
- `agents.list[].subagents.allowAgents`：允许通过 `agentId` 使用的智能体 ID 列表（`["*"]` 允许任意）。默认：仅请求方智能体。
- `agents.list[].subagents.allowAgents`：通过 `agentId` 允许的智能体 id 列表（`["*"]` 允许任意）。默认：仅请求者智能体。
发现：
- 使用 `agents_list` 发现哪些智能体 ID 可用于 `sessions_spawn`。
- 使用 `agents_list` 发现哪些智能体 id 允许用于 `sessions_spawn`。
行为：
- 启动一个新的 `agent:<agentId>:subagent:<uuid>` 会话，设置 `deliver: false`。
- 使用 `deliver: false` 启动新的 `agent:<agentId>:subagent:<uuid>` 会话。
- 子智能体默认使用完整工具集**减去会话工具**（可通过 `tools.subagents.tools` 配置）。
- 子智能体不允许调用 `sessions_spawn`（不允许子智能体生成子智能体）。
- 子智能体不允许调用 `sessions_spawn`（无子智能体 → 子智能体生成）。
- 始终非阻塞：立即返回 `{ status: "accepted", runId, childSessionKey }`。
- 完成后，OpenClaw 运行子智能体**通知步骤**并将结果发布到请求方的聊天渠道。
- 在通知步骤中回复 `ANNOUNCE_SKIP` 可保持静默。
- 通知回复规范化为 `Status`/`Result`/`Notes`；`Status` 来自运行时结果（非模型文本）。
- 子智能体会话在 `agents.defaults.subagents.archiveAfterMinutes`（默认：60）后自动归档。
- 通知回复包含统计行（运行时间、token 数、sessionKey/sessionId、对话记录路径和可选费用）。
- 完成后，OpenClaw 运行子智能体**通告步骤**并将结果发布到请求者聊天渠道。
- 在通告步骤中精确回复 `ANNOUNCE_SKIP` 以保持静默。
- 通告回复规范化为 `Status`/`Result`/`Notes`；`Status` 来自运行时结果（不是模型文本）。
- 子智能体会话在 `agents.defaults.subagents.archiveAfterMinutes` 后自动归档（默认：60）。
- 通告回复包含统计行（运行时间、token 数、sessionKey/sessionId、记录路径和可选成本）。
## 沙箱会话可见性
沙箱隔离的会话可以使用会话工具，但默认只能看到通过 `sessions_spawn` 生成的会话。
沙箱隔离的会话可以使用会话工具，但默认情况下它们只能看到通过 `sessions_spawn` 生成的会话。
配置：
@@ -191,7 +191,7 @@ x-i18n:
agents: {
defaults: {
sandbox: {
// 默认: "spawned"
// 默认："spawned"
sessionToolsVisibility: "spawned", // 或 "all"
},
},

124
docs/zh-CN/concepts/session.md
View File

@@ -1,88 +1,88 @@
---
read_when:
- 修改会话处理或存储时
- 修改会话处理或存储
summary: 聊天的会话管理规则、键和持久化
title: 会话管理
x-i18n:
generated_at: "2026-02-01T20:24:31Z"
generated_at: "2026-02-03T07:47:44Z"
model: claude-opus-4-5
provider: pi
source_hash: 147c8d1a4b6b4864cb16ad942feba80181b6b0e29afa765e7958f8c2483746b5
source_path: concepts/session.md
workflow: 14
workflow: 15
---
# 会话管理
OpenClaw 将**每个智能体一个私聊会话**视为主会话。私聊归并到 `agent:<agentId>:<mainKey>`（默认 `main`），而群组/频道聊天拥有各自独立的键。`session.mainKey` 会被遵循。
OpenClaw 将**每个智能体的一个直接聊天会话**视为主会话。直接聊天折叠为 `agent:<agentId>:<mainKey>`（默认 `main`），而群组/频道聊天获得各自的键。`session.mainKey` 会被遵循。
使用 `session.dmScope` 控制**私信**的分组方式：
使用 `session.dmScope` 控制**私信**如何分组：
- `main`（默认）：所有私信共享主会话以保持连续性。
- `per-peer`：按发送者 ID 跨渠道隔离。
- `per-peer`：跨渠道按发送者 ID 隔离。
- `per-channel-peer`：按渠道 + 发送者隔离（推荐用于多用户收件箱）。
- `per-account-channel-peer`：按账号 + 渠道 + 发送者隔离（推荐用于多账号收件箱）。
使用 `session.identityLinks` 将带提供商前缀的对端 ID 映射到规范身份，这样在使用 `per-peer`、`per-channel-peer` 或 `per-account-channel-peer` 时，同一个人可以跨渠道共享私信会话。
- `per-account-channel-peer`：按账户 + 渠道 + 发送者隔离（推荐用于多账户收件箱）。
使用 `session.identityLinks` 将带提供商前缀的对等 ID 映射到规范身份，这样在使用 `per-peer`、`per-channel-peer` 或 `per-account-channel-peer` 时，同一个人可以跨渠道共享私信会话。
## Gateway网关是权威数据源
## Gateway 网关是唯一数据源
所有会话状态均由 **Gateway网关**（"主" OpenClaw）管理。UI 客户端（macOS 应用、WebChat 等）必须向 Gateway网关查询会话列表和令牌计数，而不是读取本地文件。
所有会话状态都**由 Gateway 网关拥有**（"主" OpenClaw）。UI 客户端（macOS 应用、WebChat 等）必须向 Gateway 网关查询会话列表和令牌计数，而不是读取本地文件。
- 在**远程模式**下，你关心的会话存储位于远程 Gateway网关主机上，而不是你的 Mac 上。
- UI 中显示的令牌计数来自 Gateway网关存储字段（`inputTokens`、`outputTokens`、`totalTokens`、`contextTokens`）。客户端不会解析 JSONL 记录来"修正"总数。
- 在**远程模式**下，你关心的会话存储位于远程 Gateway 网关主机上，而不是你的 Mac 上。
- UI 中显示的令牌计数来自 Gateway 网关的存储字段（`inputTokens`、`outputTokens`、`totalTokens`、`contextTokens`）。客户端不会解析 JSONL 对话记录来"修正"总数。
## 状态存储位置
- 在 **Gateway网关主机**上：
- 在 **Gateway 网关主机**上：
- 存储文件：`~/.openclaw/agents/<agentId>/sessions/sessions.json`（每个智能体）。
- 对话记录：`~/.openclaw/agents/<agentId>/sessions/<SessionId>.jsonl`（Telegram 话题会话使用 `.../<SessionId>-topic-<threadId>.jsonl`）。
- 存储是一个 `sessionKey -> { sessionId, updatedAt, ... }` 的映射。删除条目是安全的；它们会按需重新创建。
- 群组条目可能包含 `displayName`、`channel`、`subject`、`room` 和 `space`，用于在 UI 中标记会话。
- 会话条目包含 `origin` 元数据（标签 + 路由提示），以便 UI 能够解释会话的来源。
- OpenClaw **不会**读取旧版 Pi/Tau 会话文件夹。
- 存储是一个映射 `sessionKey -> { sessionId, updatedAt, ... }`。删除条目是安全的；它们会按需重新创建。
- 群组条目可能包含 `displayName`、`channel`、`subject`、`room` 和 `space` 以在 UI 中标记会话。
- 会话条目包含 `origin` 元数据（标签 + 路由提示），以便 UI 可以解释会话的来源。
- OpenClaw **不**读取旧版 Pi/Tau 会话文件夹。
## 会话修剪
OpenClaw 默认在 LLM 调用之前从内存上下文中修剪**旧的工具结果**。
这**不会**重写 JSONL 历史记录。请参见 [/concepts/session-pruning](/concepts/session-pruning)。
默认情况下，OpenClaw 在 LLM 调用之前从内存上下文中修剪**旧的工具结果**。
这**不会**重写 JSONL 历史记录。参见 [/concepts/session-pruning](/concepts/session-pruning)。
## 压缩前记忆刷写
## 压缩前记忆刷新
当会话接近自动压缩时，OpenClaw 可以运行一次**静默记忆刷写**轮次，提醒模型将持久笔记写入磁盘。这仅在工作区可写时运行。请参见[记忆](/concepts/memory)和[压缩](/concepts/compaction)。
当会话接近自动压缩时，OpenClaw 可以运行一个**静默记忆刷新**轮次，提醒模型将持久性笔记写入磁盘。这仅在工作区可写时运行。参见[记忆](/concepts/memory)和[压缩](/concepts/compaction)。
## 传输层 → 会话键的映射
## 传输到会话键的映射
- 私聊遵循 `session.dmScope`（默认 `main`）。
- `main`：`agent:<agentId>:<mainKey>`（跨设备/渠道保持连续性）。
- 多个电话号码和渠道可以映射到同一个智能体主键；它们充当一个对话的传输通道。
- 直接聊天遵循 `session.dmScope`（默认 `main`）。
- `main`：`agent:<agentId>:<mainKey>`（跨设备/渠道的连续性）。
- 多个电话号码和渠道可以映射到同一个智能体主键；它们作为进入同一个对话的传输通道。
- `per-peer`：`agent:<agentId>:dm:<peerId>`。
- `per-channel-peer`：`agent:<agentId>:<channel>:dm:<peerId>`。
- `per-account-channel-peer`：`agent:<agentId>:<channel>:<accountId>:dm:<peerId>`（accountId 默认为 `default`）。
- 如果 `session.identityLinks` 匹配到带提供商前缀的对端 ID（例如 `telegram:123`），规范键将替换 `<peerId>`，使同一个人跨渠道共享会话。
- 群聊隔离状态：`agent:<agentId>:<channel>:group:<id>`（房间/频道使用 `agent:<agentId>:<channel>:channel:<id>`）。
- Telegram 论坛话题在群组 ID 后附加 `:topic:<threadId>` 以实现隔离。
- 旧版 `group:<id>` 键仍被识别以支持迁移。
- 入站上下文可能仍使用 `group:<id>`；渠道从 `Provider` 推断并规范化为 `agent:<agentId>:<channel>:group:<id>` 的规范形式。
- 如果 `session.identityLinks` 匹配带提供商前缀的对等 ID（例如 `telegram:123`），则规范键替换 `<peerId>`，这样同一个人可以跨渠道共享会话。
- 群组聊天隔离状态：`agent:<agentId>:<channel>:group:<id>`（房间/频道使用 `agent:<agentId>:<channel>:channel:<id>`）。
- Telegram 论坛话题在群组 ID 后附加 `:topic:<threadId>` 以进行隔离。
- 旧版 `group:<id>` 键仍被识别以进行迁移。
- 入站上下文可能仍使用 `group:<id>`；渠道从 `Provider` 推断并规范化为规范的 `agent:<agentId>:<channel>:group:<id>` 形式。
- 其他来源：
- 定时任务：`cron:<job.id>`
- Webhook：`hook:<uuid>`（除非由 hook 显式设置）
- Webhooks：`hook:<uuid>`（除非由 hook 显式设置）
- 节点运行：`node-<nodeId>`
## 生命周期
- 重置策略：会话持续复用直到过期，过期在下一条入站消息时评估。
- 每日重置：默认为 **Gateway网关主机本地时间凌晨 4:00**。当会话的最后更新早于最近一次每日重置时间时，会话即为过期。
- 空闲重置（可选）：`idleMinutes` 添加一个滑动空闲窗口。当同时配置了每日重置和空闲重置时，**先到期的那个**强制创建新会话。
- 旧版仅空闲模式：如果设置了 `session.idleMinutes` 但没有任何 `session.reset`/`resetByType` 配置，OpenClaw 会保持仅空闲模式以向后兼容。
- 按类型覆盖（可选）：`resetByType` 允许你为 `dm`、`group` 和 `thread` 会话覆盖策略（thread = Slack/Discord 线程、Telegram 话题、连接器提供的 Matrix 线程）。
- 按渠道覆盖（可选）：`resetByChannel` 覆盖特定渠道的重置策略（适用于该渠道的所有会话类型，优先级高于 `reset`/`resetByType`）。
- 重置触发器：精确的 `/new` 或 `/reset`（加上 `resetTriggers` 中的额外项）会启动一个新的会话 ID，并将消息的剩余部分继续传递。`/new <model>` 接受模型别名、`provider/model` 或提供商名称（模糊匹配）来设置新会话的模型。如果单独发送 `/new` 或 `/reset`，OpenClaw 会运行一个简短的"问候"轮次来确认重置。
- 手动重置：从存储中删除特定键或移除 JSONL 记录；下一条消息会重新创建它们。
- 隔离的定时任务每次运行都会创建一个新的 `sessionId`（不复用空闲会话）。
- 重置策略：会话被重用直到过期，过期在下一条入站消息时评估。
- 每日重置：默认为 **Gateway 网关主机本地时间凌晨 4:00**。当会话的最后更新早于最近的每日重置时间时，会话即为过期。
- 空闲重置（可选）：`idleMinutes` 添加一个滑动空闲窗口。当同时配置每日和空闲重置时，**先过期者**强制新会话。
- 旧版仅空闲模式：如果你设置了 `session.idleMinutes` 而没有任何 `session.reset`/`resetByType` 配置，OpenClaw 会保持仅空闲模式以保持向后兼容。
- 按类型覆盖（可选）：`resetByType` 允许你覆盖 `dm`、`group` 和 `thread` 会话的策略（thread = Slack/Discord 线程、Telegram 话题、连接器提供的 Matrix 线程）。
- 按渠道覆盖（可选）：`resetByChannel` 覆盖渠道的重置策略（适用于该渠道的所有会话类型，优先于 `reset`/`resetByType`）。
- 重置触发器：精确的 `/new` 或 `/reset`（加上 `resetTriggers` 中的任何额外项）启动新的会话 ID 并传递消息的其余部分。`/new <model>` 接受模型别名、`provider/model` 或提供商名称（模糊匹配）来设置新会话模型。如果单独发送 `/new` 或 `/reset`，OpenClaw 会运行一个简短的"问候"轮次来确认重置。
- 手动重置：从存储中删除特定键或删除 JSONL 对话记录；下一条消息会重新创建它们。
- 隔离的定时任务总是每次运行生成新的 `sessionId`（没有空闲重用）。
## 发送策略（可选）
无需列出单个 ID 即可按特定会话类型阻止投递。
阻止特定会话类型的投递，无需列出单个 ID。
```json5
{
@@ -98,27 +98,27 @@ OpenClaw 默认在 LLM 调用之前从内存上下文中修剪**旧的工具结
}
```
运行时覆盖（仅限所有者）：
运行时覆盖（仅所有者）：
- `/send on` → 允许此会话发送
- `/send off` → 禁止此会话发送
- `/send on` → 为此会话允许
- `/send off` → 为此会话拒绝
- `/send inherit` → 清除覆盖并使用配置规则
请将这些作为独立消息发送以确保生效。
将这些作为独立消息发送以使其生效。
## 配置（可选的重命名示例）
## 配置（可选重命名示例）
```json5
// ~/.openclaw/openclaw.json
{
session: {
scope: "per-sender", // 保持群组键独立
dmScope: "main", // 私信连续性（共享收件箱请设置 per-channel-peer/per-account-channel-peer）
scope: "per-sender", // keep group keys separate
dmScope: "main", // DM continuity (set per-channel-peer/per-account-channel-peer for shared inboxes)
identityLinks: {
alice: ["telegram:123456789", "discord:987654321012345678"],
},
reset: {
// 默认值：mode=daily，atHour=4（Gateway网关主机本地时间）。
// 如果同时设置了 idleMinutes，先到期的优先。
// Defaults: mode=daily, atHour=4 (gateway host local time).
// If you also set idleMinutes, whichever expires first wins.
mode: "daily",
atHour: 4,
idleMinutes: 120,
@@ -141,26 +141,26 @@ OpenClaw 默认在 LLM 调用之前从内存上下文中修剪**旧的工具结
## 检查
- `openclaw status` — 显示存储路径和最近的会话。
- `openclaw sessions --json` — 转储所有条目（使用 `--active <minutes>` 进行筛选）。
- `openclaw gateway call sessions.list --params '{}'` — 从运行中的 Gateway网关获取会话（使用 `--url`/`--token` 访问远程 Gateway网关）。
- 在聊天中发送 `/status` 作为独立消息，可查看智能体是否可达、会话上下文使用了多少、当前的思考/详细模式开关，以及 WhatsApp 网页凭证的最后刷新时间（有助于发现需要重新链接的情况）。
- 发送 `/context list` 或 `/context detail` 查看系统提示词和注入的工作区文件中的内容（以及最大的上下文贡献者）。
- 发送 `/stop` 作为独立消息，可中止当前运行、清除该会话的排队后续消息，并停止由其生成的任何子智能体运行（回复中包含已停止的数量）。
- 发送 `/compact`（可选指令）作为独立消息，可总结旧的上下文并释放窗口空间。请参见 [/concepts/compaction](/concepts/compaction)。
- JSONL 记录可以直接打开以查看完整的对话轮次。
- `openclaw sessions --json` — 导出每个条目（使用 `--active <minutes>` 过滤）。
- `openclaw gateway call sessions.list --params '{}'` — 从运行中的 Gateway 网关获取会话（使用 `--url`/`--token` 进行远程 Gateway 网关访问）。
- 在聊天中单独发送 `/status` 消息可查看智能体是否可达、会话上下文使用了多少、当前的思考/详细模式开关，以及你的 WhatsApp Web 凭证上次刷新时间（有助于发现重新链接需求）。
- 发送 `/context list` 或 `/context detail` 查看系统提示中的内容和注入的工作区文件（以及最大的上下文贡献者）。
- 单独发送 `/stop` 消息可中止当前运行、清除该会话的排队后续操作，并停止从中生成的任何子智能体运行（回复包含已停止的数量）。
- 单独发送 `/compact`（可选指令）消息可总结旧上下文并释放窗口空间。参见 [/concepts/compaction](/concepts/compaction)。
- 可以直接打开 JSONL 对话记录查看完整轮次。
## 提示
- 将主键专用于一对一对话；让群组保持各自独立的键。
- 自动化清理时，删除单个键而不是整个存储，以保留其他地方的上下文。
- 将主键专用于 1:1 通信；让群组保留各自的键。
- 自动清理时，删除单个键而不是整个存储，以保留其他地方的上下文。
## 会话来源元数据
每个会话条目在 `origin` 中记录其来源（尽力而为）：
每个会话条目记录其来源（尽力而为）在 `origin` 中：
- `label`：人类可读标签（从对话标签 + 群组主题/频道解析）
- `provider`：规范化的渠道 ID（包括扩展）
- `from`/`to`：入站信封中的原始路由 ID
- `accountId`：提供商账号 ID（多账号时）
- `accountId`：提供商账户 ID（多账户时）
- `threadId`：渠道支持时的线程/话题 ID
来源字段为私信、频道和群组填充。如果连接器仅更新投递路由（例如，保持私信主会话活跃），它仍应提供入站上下文，以便会话保留其说明性元数据。扩展可以通过在入站上下文中发送 `ConversationLabel`、`GroupSubject`、`GroupChannel`、`GroupSpace` 和 `SenderName`，并调用 `recordSessionMetaFromInbound`（或将相同的上下文传递给 `updateLastRoute`）来实现。
来源字段为私信、频道和群组填充。如果连接器仅更新投递路由（例如，保持私信主会话新鲜），它仍应提供入站上下文，以便会话保留其解释器元数据。扩展可以通过在入站上下文中发送 `ConversationLabel`、`GroupSubject`、`GroupChannel`、`GroupSpace` 和 `SenderName` 并调用 `recordSessionMetaFromInbound`（或将相同上下文传递给 `updateLastRoute`）来实现。

110
docs/zh-CN/concepts/streaming.md
View File

@@ -1,65 +1,65 @@
---
read_when:
- 解释流式传输或分块在渠道上的工作方式
- 更改块流式传输或渠道分块行为
- 调试重复/提前的块回复或草稿流式传输问题
- 解释流式传输或分块在渠道上如何工作
- 更改分块流式传输或渠道分块行为
- 调试重复/提前的块回复或草稿流式传输
summary: 流式传输 + 分块行为（块回复、草稿流式传输、限制）
title: 流式传输与分块
title: 流式传输和分块
x-i18n:
generated_at: "2026-02-01T20:24:24Z"
generated_at: "2026-02-03T10:05:41Z"
model: claude-opus-4-5
provider: pi
source_hash: f014eb1898c4351b1d6b812223226d91324701e3e809cd0f3faf6679841bc353
source_path: concepts/streaming.md
workflow: 14
workflow: 15
---
# 流式传输 + 分块
OpenClaw 有两个独立的"流式传输"层：
- **块流式传输（渠道）：** 在助手生成内容时发送已完成的**块**。这些是普通的渠道消息（不是 token 增量）。
- **类 Token 流式传输（仅 Telegram）：** 在生成过程中用部分文本更新**草稿气泡**；最终消息在结束时发送。
- **分块流式传输（渠道）：** 在助手写入时发出已完成的**块**。这些是普通的渠道消息（不是令牌增量）。
- **类令牌流式传输（仅限 Telegram）：** 在生成时用部分文本更新**草稿气泡**；最终消息在结束时发送。
目前**没有真正的 token 流式传输**到外部渠道消息。Telegram 草稿流式传输是唯一的部分流式传输界面。
目前**没有真正的令牌流式传输**到外部渠道消息。Telegram 草稿流式传输是唯一的部分流式传输界面。
## 块流式传输（渠道消息）
## 分块流式传输（渠道消息）
块流式传输在助手输出可用时以粗粒度块发送。
分块流式传输在助手输出可用时以粗粒度块发送。
```
Model output
模型输出
└─ text_delta/events
├─ (blockStreamingBreak=text_end)
│ └─ chunker emits blocks as buffer grows
│ └─ 分块器在缓冲区增长时发出块
└─ (blockStreamingBreak=message_end)
└─ chunker flushes at message_end
└─ channel send (block replies)
└─ 分块器在 message_end 时刷新
└─ 渠道发送（块回复）
```
图例：
- `text_delta/events`：模型流事件（对于非流式模型可能较为稀疏）。
- `chunker`：`EmbeddedBlockChunker`，应用最小/最大边界 + 断点偏好。
- `text_delta/events`：模型流事件（对于非流式模型可能稀疏）。
- `chunker`：应用最小/最大边界 + 断点偏好的 `EmbeddedBlockChunker`。
- `channel send`：实际的出站消息（块回复）。
**控制项：**
- `agents.defaults.blockStreamingDefault`：`"on"`/`"off"`（默认关闭）。
- 渠道覆盖：`*.blockStreaming`（以及按账户的变体）可按渠道强制 `"on"`/`"off"`。
- 渠道覆盖：`*.blockStreaming`（以及每账户变体）可为每个渠道强制设置 `"on"`/`"off"`。
- `agents.defaults.blockStreamingBreak`：`"text_end"` 或 `"message_end"`。
- `agents.defaults.blockStreamingChunk`：`{ minChars, maxChars, breakPreference? }`。
- `agents.defaults.blockStreamingCoalesce`：`{ minChars?, maxChars?, idleMs? }`（发送前合并流式块）。
- 渠道硬性上限：`*.textChunkLimit`（例如 `channels.whatsapp.textChunkLimit`）。
- 渠道分块模式：`*.chunkMode`（默认 `length`，`newline` 在空行（段落边界）处分割，然后再按长度分块）。
- Discord 软性上限：`channels.discord.maxLinesPerMessage`（默认 17）拆分过长的回复以避免 UI 裁剪。
- 渠道硬上限：`*.textChunkLimit`（例如 `channels.whatsapp.textChunkLimit`）。
- 渠道分块模式：`*.chunkMode`（默认 `length`，`newline` 在长度分块之前按空行（段落边界）分割）。
- Discord 软上限：`channels.discord.maxLinesPerMessage`（默认 17）分割高度较大的回复以避免 UI 裁剪。
**边界语义：**
- `text_end`：分块器发出块后立即流式传输；在每个 `text_end` 时刷新。
- `message_end`：等待助手消息完成后，再刷新缓冲输出。
- `text_end`：分块器发出时立即流式传输块；在每个 `text_end` 时刷新。
- `message_end`：等到助手消息完成，然后刷新缓冲的输出。
`message_end` 在缓冲文本超过 `maxChars` 时仍会使用分块器，因此可能在最后发出多个块。
如果缓冲文本超过 `maxChars`，`message_end` 仍然使用分块器，因此可能在最后发出多个块。
## 分块算法（低/高边界）
@@ -68,66 +68,66 @@ Model output
- **低边界：** 在缓冲区 >= `minChars` 之前不发出（除非强制）。
- **高边界：** 优先在 `maxChars` 之前分割；如果强制，则在 `maxChars` 处分割。
- **断点偏好：** `paragraph` → `newline` → `sentence` → `whitespace` → 硬断点。
- **代码围栏：** 永远不在围栏内分割；当在 `maxChars` 处被强制分割时，关闭并重新打开围栏以保持 Markdown 有效。
- **代码围栏：** 从不在围栏内分割；当在 `maxChars` 处强制分割时，关闭 + 重新打开围栏以保持 Markdown 有效。
`maxChars` 会被限制在渠道的 `textChunkLimit` 以内，因此不会超过按渠道的上限。
`maxChars` 被限制在渠道 `textChunkLimit` 内，因此你无法超过每渠道的上限。
## 合并（合并流式块）
当块流式传输启用时，OpenClaw 可以在发送前**合并连续的块**。这减少了"单行刷屏"的情况，同时仍提供渐进式输出。
启用分块流式传输时，OpenClaw 可以在发送前**合并连续的块分块**。这减少了"单行刷屏"，同时仍提供渐进式输出。
- 合并会等待**空闲间隔**（`idleMs`）后再刷新。
- 缓冲区受 `maxChars` 限制，超出时会刷新。
- `minChars` 防止在积累足够文本之前发送微小片段（最终刷新始终发送剩余文本）。
- 连接符由 `blockStreamingChunk.breakPreference` 派生（`paragraph` → `\n\n`，`newline` → `\n`，`sentence` → 空格）。
- 渠道覆盖可通过 `*.blockStreamingCoalesce` 设置（包括按账户的配置）。
- 除非覆盖，Signal/Slack/Discord 的默认合并 `minChars` 会提升至 1500。
- 合并在**空闲间隙**（`idleMs`）后刷新。
- 缓冲区受 `maxChars` 限制，超过时将刷新。
- `minChars` 防止微小片段发送，直到累积足够文本（最终刷新始终发送剩余文本）。
- 连接符从 `blockStreamingChunk.breakPreference` 派生（`paragraph` → `\n\n`，`newline` → `\n`，`sentence` → 空格）。
- 渠道覆盖通过 `*.blockStreamingCoalesce` 可用（包括每账户配置）。
- 除非覆盖，Signal/Slack/Discord 的默认合并 `minChars` 提高到 1500。
## 块之间的仿真人节奏
## 块之间的类人节奏
当块流式传输启用时，你可以在块回复之间（第一个块之后）添加**随机停顿**。这让多气泡回复感觉更自然。
启用分块流式传输时，你可以在块回复之间添加**随机暂停**（在第一个块之后）。这使多气泡响应感觉更自然。
- 配置：`agents.defaults.humanDelay`（通过 `agents.list[].humanDelay` 按智能体覆盖）。
- 模式：`off`（默认）、`natural`（800–2500ms）、`custom`（`minMs`/`maxMs`）。
- 仅适用于**块回复**，不适用于最终回复或工具摘要。
## "流式发送块还是一次性发送全部"
## "流式传输块或全部内容"
对应关系：
这映射到：
- **流式发送块：** `blockStreamingDefault: "on"` + `blockStreamingBreak: "text_end"`（边生成边发送）。非 Telegram 渠道还需要设置 `*.blockStreaming: true`。
- **结束时一次性发送：** `blockStreamingBreak: "message_end"`（刷新一次，如果内容很长可能产生多个块）。
- **不使用块流式传输：** `blockStreamingDefault: "off"`（仅最终回复）。
- **流式传输块：** `blockStreamingDefault: "on"` + `blockStreamingBreak: "text_end"`（边生成边发出）。非 Telegram 渠道还需要 `*.blockStreaming: true`。
- **最后流式传输全部内容：** `blockStreamingBreak: "message_end"`（刷新一次，如果很长可能有多个块）。
- **无分块流式传输：** `blockStreamingDefault: "off"`（只有最终回复）。
**渠道说明：** 对于非 Telegram 渠道，块流式传输**默认关闭**，除非 `*.blockStreaming` 显式设置为 `true`。Telegram 可以通过 `channels.telegram.streamMode` 进行草稿流式传输，无需块回复。
**渠道说明：** 对于非 Telegram 渠道，分块流式传输**默认关闭**，除非 `*.blockStreaming` 明确设置为 `true`。Telegram 可以在没有块回复的情况下流式传输草稿（`channels.telegram.streamMode`）。
配置位置提醒：`blockStreaming*` 默认值位于 `agents.defaults` 下，而非根配置。
配置位置提醒：`blockStreaming*` 默认值位于 `agents.defaults` 下，而不是根配置。
## Telegram 草稿流式传输（类 Token）
## Telegram 草稿流式传输（类令牌）
Telegram 是唯一支持草稿流式传输的渠道：
- 在**带话题的私聊**中使用 Bot API `sendMessageDraft`。
- 在**带主题的私聊**中使用 Bot API `sendMessageDraft`。
- `channels.telegram.streamMode: "partial" | "block" | "off"`。
- `partial`：用最新的流式文本更新草稿。
- `block`：以分块方式更新草稿（使用相同的分块器规则）。
- `off`：不进行草稿流式传输。
- `block`：以分块方式更新草稿（相同的分块器规则）。
- `off`：无草稿流式传输。
- 草稿分块配置（仅用于 `streamMode: "block"`）：`channels.telegram.draftChunk`（默认值：`minChars: 200`，`maxChars: 800`）。
- 草稿流式传输与块流式传输是分离的；块回复默认关闭，仅在非 Telegram 渠道通过 `*.blockStreaming: true` 启用。
- 草稿流式传输与分块流式传输分开；块回复默认关闭，仅在非 Telegram 渠道上通过 `*.blockStreaming: true` 启用。
- 最终回复仍然是普通消息。
- `/reasoning stream` 将推理过程写入草稿气泡（仅 Telegram）。
- `/reasoning stream` 将推理写入草稿气泡（仅限 Telegram）。
当草稿流式传输处于活跃状态时，OpenClaw 会禁用该回复的块流式传输，以避免双重流式传输。
当草稿流式传输活跃时，OpenClaw 会为该回复禁用分块流式传输以避免双重流式传输。
```
Telegram (private + topics)
└─ sendMessageDraft (draft bubble)
├─ streamMode=partial → update latest text
└─ streamMode=block → chunker updates draft
└─ final reply → normal message
Telegram（私聊 + 主题）
└─ sendMessageDraft（草稿气泡）
├─ streamMode=partial → 更新最新文本
└─ streamMode=block → 分块器更新草稿
└─ 最终回复 → 普通消息
```
图例：
- `sendMessageDraft`：Telegram 草稿气泡（不是真正的消息）。
- `final reply`：普通的 Telegram 消息发送。
- `final reply`：普通 Telegram 消息发送。

70
docs/zh-CN/concepts/system-prompt.md
View File

@@ -2,56 +2,56 @@
read_when:
- 编辑系统提示词文本、工具列表或时间/心跳部分
- 更改工作区引导或 Skills 注入行为
summary: OpenClaw 系统提示词的内容及其组装方式
summary: OpenClaw 系统提示词包含的内容及其组装方式
title: 系统提示词
x-i18n:
generated_at: "2026-02-01T20:24:17Z"
generated_at: "2026-02-03T07:46:58Z"
model: claude-opus-4-5
provider: pi
source_hash: bef4b2674ba0414ce28fd08a4c3ead0e0ebe989e7df3c88ca8a0b2abfec2a50b
source_path: concepts/system-prompt.md
workflow: 14
workflow: 15
---
# 系统提示词
OpenClaw 为每次智能体运行构建自定义系统提示词。该提示词由 **OpenClaw 自有**，不使用 p-coding-agent 的默认提示词。
OpenClaw 为每次智能体运行构建自定义系统提示词。该提示词由 **OpenClaw 拥有**，不使用 p-coding-agent 默认提示词。
提示词由 OpenClaw 组装并注入到每次智能体运行中。
该提示词由 OpenClaw 组装并注入到每次智能体运行中。
## 结构
提示词有意保持紧凑，使用固定的部分：
该提示词设计紧凑，使用固定部分：
- **工具**：当前工具列表及简短描述。
- **安全**：简短的护栏提醒，避免模型追求权力或绕过监督。
- **Skills**（可用时）：告诉模型如何按需加载 Skills 指令。
- **OpenClaw 自更新**：如何运行 `config.apply` 和 `update.run`。
- **工作区**：工作目录（`agents.defaults.workspace`）。
- **文档**：OpenClaw 文档的本地路径（仓库或 npm 包）及查阅时机。
- **工作区文件（注入的）**：表明引导文件包含在下方。
- **沙箱**（启用时）：表明沙箱隔离运行时、沙箱路径，以及是否可用提权执行。
- **当前日期和时间**：用户本地时间、时区和时间格式。
- **回复标签**：支持的提供商的可选回复标签语法。
- **心跳**：心跳提示和确认行为。
- **运行时**：主机、操作系统、Node、模型、仓库根目录（检测到时）、思考级别（一行）。
- **推理**：当前可见性级别及 /reasoning 切换提示。
- **Tooling**：当前工具列表 + 简短描述。
- **Safety**：简短的防护提醒，避免追求权力的行为或绕过监督。
- **Skills**（如果可用）：告诉模型如何按需加载 Skill 指令。
- **OpenClaw Self-Update**：如何运行 `config.apply` 和 `update.run`。
- **Workspace**：工作目录（`agents.defaults.workspace`）。
- **Documentation**：OpenClaw 文档的本地路径（仓库或 npm 包）以及何时阅读它们。
- **Workspace Files (injected)**：表示下方包含引导文件。
- **Sandbox**（启用时）：表示沙箱隔离运行时、沙箱路径，以及是否可用提权执行。
- **Current Date & Time**：用户本地时间、时区和时间格式。
- **Reply Tags**：支持的提供商的可选回复标签语法。
- **Heartbeats**：心跳提示词和确认行为。
- **Runtime**：主机、操作系统、node、模型、仓库根目录（检测到时）、思考级别（一行）。
- **Reasoning**：当前可见性级别 + /reasoning 切换提示。
系统提示词中的安全护栏是建议性的。它们引导模型行为但不强制执行策略。请使用工具策略、执行审批、沙箱隔离和渠道白名单进行硬性执行；操作人员可以按设计禁用这些功能。
系统提示词中的安全防护是建议性的。它们指导模型行为但不强制执行策略。使用工具策略、执行审批、沙箱隔离和渠道允许列表进行硬性执行；运维人员可以按设计禁用这些。
## 提示词模式
OpenClaw 可以为子智能体渲染更小的系统提示词。运行时为每次运行设置一个 `promptMode`（非用户可配置项）：
OpenClaw 可以为子智能体渲染更小的系统提示词。运行时为每次运行设置一个 `promptMode`（不是面向用户的配置）：
- `full`（默认）：包含上述所有部分。
- `minimal`：用于子智能体；省略**Skills**、**记忆召回**、**OpenClaw 自更新**、**模型别名**、**用户身份**、**回复标签**、**消息**、**静默回复**和**心跳**。工具、**安全**、工作区、沙箱、当前日期和时间（已知时）、运行时和注入的上下文仍然可用。
- `none`：仅返回基础身份行。
- `minimal`：用于子智能体；省略 **Skills**、**Memory Recall**、**OpenClaw Self-Update**、**Model Aliases**、**User Identity**、**Reply Tags**、**Messaging**、**Silent Replies** 和 **Heartbeats**。Tooling、**Safety**、Workspace、Sandbox、Current Date & Time（已知时）、Runtime 和注入的上下文仍然可用。
- `none`：仅返回基本身份行。
当 `promptMode=minimal` 时，额外注入的提示词标记为**子智能体上下文**而非**群聊上下文**。
当 `promptMode=minimal` 时，额外注入的提示词标记为 **Subagent Context** 而不是 **Group Chat Context**。
## 工作区引导注入
引导文件经过裁剪后附加在**项目上下文**下，使模型无需显式读取即可看到身份和配置上下文：
引导文件被修剪后附加在 **Project Context** 下，这样模型无需显式读取即可看到身份和配置上下文：
- `AGENTS.md`
- `SOUL.md`
@@ -59,30 +59,30 @@ OpenClaw 可以为子智能体渲染更小的系统提示词。运行时为每
- `IDENTITY.md`
- `USER.md`
- `HEARTBEAT.md`
- `BOOTSTRAP.md`（仅在全新工作区时）
- `BOOTSTRAP.md`（仅在全新工作区上）
大文件会被截断并附加标记。每个文件的最大大小由 `agents.defaults.bootstrapMaxChars` 控制（默认：20000）。缺失的文件会注入一个简短的缺失文件标记。
大文件会带截断标记被截断。每个文件的最大大小由 `agents.defaults.bootstrapMaxChars` 控制（默认：20000）。缺失的文件会注入一个简短的缺失文件标记。
内部钩子可以通过 `agent:bootstrap` 拦截此步骤，以修改或替换注入的引导文件（例如将 `SOUL.md` 替换为备选人格）。
内部钩子可以通过 `agent:bootstrap` 拦截此步骤以修改或替换注入的引导文件（例如将 `SOUL.md` 替换为其他角色）。
要查看每个注入文件的贡献量（原始 vs 注入、截断情况，以及工具模式开销），请使用 `/context list` 或 `/context detail`。参见[上下文](/concepts/context)。
要检查每个注入文件贡献了多少（原始 vs 注入、截断，加上工具 schema 开销），使用 `/context list` 或 `/context detail`。参见[上下文](/concepts/context)。
## 时间处理
当用户时区已知时，系统提示词包含专门的**当前日期和时间**部分。为保持提示词缓存稳定，现在仅包含**时区**（不含动态时钟或时间格式）。
当用户时区已知时，系统提示词包含专用的 **Current Date & Time** 部分。为保持提示词缓存稳定，它现在只包含**时区**（没有动态时钟或时间格式）。
当智能体需要当前时间时，请使用 `session_status`；状态卡片包含时间戳行。
当智能体需要当前时间时使用 `session_status`；状态卡片包含时间戳行。
配置方式：
- `agents.defaults.userTimezone`
- `agents.defaults.timeFormat`（`auto` | `12` | `24`）
详见[日期和时间](/date-time)了解全部行为细节。
完整行为详情参见[日期和时间](/date-time)。
## Skills
当存在符合条件的 Skills 时，OpenClaw 会注入一个紧凑的**可用 Skills 列表**（`formatSkillsForPrompt`），其中包含每个 Skills 的**文件路径**。提示词指示模型使用 `read` 加载位于所列位置（工作区、托管或捆绑）的 SKILL.md。如果没有符合条件的 Skills，则省略 Skills 部分。
当存在符合条件的 Skills 时，OpenClaw 注入一个紧凑的**可用 Skills 列表**（`formatSkillsForPrompt`），其中包含每个 Skill 的**文件路径**。提示词指示模型使用 `read` 加载列出位置（工作区、托管或内置）的 SKILL.md。如果没有符合条件的 Skills，则省略 Skills 部分。
```
<available_skills>
@@ -94,8 +94,8 @@ OpenClaw 可以为子智能体渲染更小的系统提示词。运行时为每
</available_skills>
```
这样可以保持基础提示词精简，同时仍然支持有针对性的 Skills 使用。
这使基础提示词保持小巧，同时仍然支持有针对性的 Skill 使用。
## 文档
当可用时，系统提示词包含一个**文档**部分，指向本地 OpenClaw 文档目录（仓库工作区中的 `docs/` 或捆绑的 npm 包文档），并注明公共镜像、源代码仓库、社区 Discord 和 ClawHub (https://clawhub.com) 用于 Skills 发现。提示词指示模型在查询 OpenClaw 行为、命令、配置或架构时优先查阅本地文档，并在可能时自行运行 `openclaw status`（仅在无法访问时才询问用户）。
如果可用，系统提示词包含一个 **Documentation** 部分，指向本地 OpenClaw 文档目录（仓库工作区中的 `docs/` 或打包的 npm 包文档），并注明公共镜像、源仓库、社区 Discord 和 ClawHub (https://clawhub.com) 用于 Skills 发现。提示词指示模型首先查阅本地文档了解 OpenClaw 行为、命令、配置或架构，并尽可能自己运行 `openclaw status`（仅在无法访问时询问用户）。

96
docs/zh-CN/concepts/typebox.md
View File

@@ -1,39 +1,39 @@
---
read_when:
- 更新协议模式或代码生成
summary: TypeBox 模式作为 Gateway网关协议的唯一事实来源
summary: TypeBox 模式作为 Gateway 网关协议的唯一事实来源
title: TypeBox
x-i18n:
generated_at: "2026-02-01T20:24:36Z"
generated_at: "2026-02-03T07:47:23Z"
model: claude-opus-4-5
provider: pi
source_hash: 233800f4f5fabe8ed0e1b3d8aded2eca27252e08c9b0b24ea9c6293e9282c918
source_path: concepts/typebox.md
workflow: 14
workflow: 15
---
# TypeBox 作为协议的唯一事实来源
# TypeBox 作为协议的事实来源
最后更新：2026-01-10
TypeBox 是一个 TypeScript 优先的模式库。我们用它来定义 **Gateway网关 WebSocket 协议**（握手、请求/响应、服务器事件）。这些模式驱动**运行时验证**、**JSON Schema 导出**以及 macOS 应用的 **Swift 代码生成**。一个事实来源；其他一切都是生成的。
TypeBox 是一个 TypeScript 优先的模式库。我们用它来定义 **Gateway 网关 WebSocket 协议**（握手、请求/响应、服务器事件）。这些模式驱动**运行时验证**、**JSON Schema 导出**和 macOS 应用的 **Swift 代码生成**。一个事实来源；其他一切都是生成的。
如果你想了解更高层次的协议上下文，请从 [Gateway网关架构](/concepts/architecture) 开始。
如果你想了解更高层次的协议上下文，请从 [Gateway 网关架构](/concepts/architecture)开始。
## 心智模型（30 秒）
每条 Gateway网关 WS 消息都是以下三种帧之一：
每个 Gateway 网关 WS 消息都是以下三种帧之一：
- **请求**：`{ type: "req", id, method, params }`
- **响应**：`{ type: "res", id, ok, payload | error }`
- **事件**：`{ type: "event", event, payload, seq?, stateVersion? }`
- **Request**：`{ type: "req", id, method, params }`
- **Response**：`{ type: "res", id, ok, payload | error }`
- **Event**：`{ type: "event", event, payload, seq?, stateVersion? }`
第一帧**必须**是 `connect` 请求。之后，客户端可以调用方法（如 `health`、`send`、`chat.send`）并订阅事件（如 `presence`、`tick`、`agent`）。
第一个帧**必须**是 `connect` 请求。之后，客户端可以调用方法（例如 `health`、`send`、`chat.send`）并订阅事件（例如 `presence`、`tick`、`agent`）。
连接流程（最简）：
连接流程（最小）：
```
Client Gateway网关
Client Gateway
|---- req:connect -------->|
|<---- res:hello-ok --------|
|<---- event:tick ----------|
@@ -41,46 +41,46 @@ Client Gateway网关
|<---- res:health ----------|
```
常见方法 + 事件：
常用方法 + 事件：
| 类别 | 示例 | 备注 |
| ---- | --------------------------------------------------------- | ----------------------------------- |
| 核心 | `connect`、`health`、`status` | `connect` 必须在首位 |
| 消息 | `send`、`poll`、`agent`、`agent.wait` | 有副作用的操作需要 `idempotencyKey` |
| 聊天 | `chat.history`、`chat.send`、`chat.abort`、`chat.inject` | WebChat 使用这些 |
| 会话 | `sessions.list`、`sessions.patch`、`sessions.delete` | 会话管理 |
| 节点 | `node.list`、`node.invoke`、`node.pair.*` | Gateway网关 WS + 节点操作 |
| 事件 | `tick`、`presence`、`agent`、`chat`、`health`、`shutdown` | 服务器推送 |
| 类别 | 示例 | 说明 |
| ---- | --------------------------------------------------------- | ------------------------------- |
| 核心 | `connect`、`health`、`status` | `connect` 必须是第一个 |
| 消息 | `send`、`poll`、`agent`、`agent.wait` | 有副作用的需要 `idempotencyKey` |
| 聊天 | `chat.history`、`chat.send`、`chat.abort`、`chat.inject` | WebChat 使用这些 |
| 会话 | `sessions.list`、`sessions.patch`、`sessions.delete` | 会话管理 |
| 节点 | `node.list`、`node.invoke`、`node.pair.*` | Gateway 网关 WS + 节点操作 |
| 事件 | `tick`、`presence`、`agent`、`chat`、`health`、`shutdown` | 服务器推送 |
权威列表位于 `src/gateway/server.ts`（`METHODS`、`EVENTS`）。
权威列表在 `src/gateway/server.ts`（`METHODS`、`EVENTS`）中。
## 模式文件位置
## 模式所在位置
- 源文件：`src/gateway/protocol/schema.ts`
- 源码：`src/gateway/protocol/schema.ts`
- 运行时验证器（AJV）：`src/gateway/protocol/index.ts`
- 服务器握手 + 方法分发：`src/gateway/server.ts`
- 节点客户端：`src/gateway/client.ts`
- 生成的 JSON Schema：`dist/protocol.schema.json`
- 生成的 Swift 模型：`apps/macos/Sources/OpenClawProtocol/Gateway网关Models.swift`
- 生成的 Swift 模型：`apps/macos/Sources/OpenClawProtocol/GatewayModels.swift`
## 当前流水线
## 当前流程
- `pnpm protocol:gen`
- 将 JSON Schema（draft‑07）写入 `dist/protocol.schema.json`
- `pnpm protocol:gen:swift`
- 生成 Swift Gateway网关模型
- 生成 Swift Gateway 网关模型
- `pnpm protocol:check`
- 运行两个生成器并验证输出已提交
## 模式在运行时的使用方式
- **服务器端**：每个入站帧都通过 AJV 验证。握手仅接受参数匹配 `ConnectParams` 的 `connect` 请求。
- **客户端**：JS 客户端在使用事件和响应帧之前进行验证。
- **方法接口**：Gateway网关在 `hello-ok` 中公布支持的 `methods` 和 `events`。
- **服务器端**：每个入站帧都用 AJV 验证。握手仅接受参数匹配 `ConnectParams` 的 `connect` 请求。
- **客户端**：JS 客户端在使用之前验证事件和响应帧。
- **方法表面**：Gateway 网关在 `hello-ok` 中公布支持的 `methods` 和 `events`。
## 示例帧
连接（第一条消息）：
Connect（第一条消息）：
```json
{
@@ -143,7 +143,7 @@ Hello-ok 响应：
## 最小客户端（Node.js）
最小可用流程：连接 + 健康检查。
最小可用流程：connect + health。
```ts
import { WebSocket } from "ws";
@@ -183,7 +183,7 @@ ws.on("message", (data) => {
});
```
## 实战示例：端到端添加一个方法
## 实践示例：端到端添加方法
示例：添加一个新的 `system.echo` 请求，返回 `{ ok: true, text }`。
@@ -217,7 +217,7 @@ export type SystemEchoResult = Static<typeof SystemEchoResultSchema>;
2. **验证**
在 `src/gateway/protocol/index.ts` 中导出 AJV 验证器：
在 `src/gateway/protocol/index.ts` 中，导出一个 AJV 验证器：
```ts
export const validateSystemEchoParams = ajv.compile<SystemEchoParams>(SystemEchoParamsSchema);
@@ -225,10 +225,10 @@ export const validateSystemEchoParams = ajv.compile<SystemEchoParams>(SystemEcho
3. **服务器行为**
在 `src/gateway/server-methods/system.ts` 中添加处理器：
在 `src/gateway/server-methods/system.ts` 中添加处理程序：
```ts
export const systemHandlers: Gateway网关RequestHandlers = {
export const systemHandlers: GatewayRequestHandlers = {
"system.echo": ({ params, respond }) => {
const text = String(params.text ?? "");
respond(true, { ok: true, text });
@@ -236,7 +236,7 @@ export const systemHandlers: Gateway网关RequestHandlers = {
};
```
在 `src/gateway/server-methods.ts` 中注册（已合并 `systemHandlers`），然后将 `"system.echo"` 添加到 `src/gateway/server.ts` 的 `METHODS` 中。
在 `src/gateway/server-methods.ts` 中注册（已合并 `systemHandlers`），然后将 `"system.echo"` 添加到 `src/gateway/server.ts` 中的 `METHODS`。
4. **重新生成**
@@ -252,28 +252,28 @@ pnpm protocol:check
Swift 生成器输出：
- 包含 `req`、`res`、`event` 和 `unknown` case 的 `Gateway网关Frame` 枚举
- 带有 `req`、`res`、`event` 和 `unknown` 情况的 `GatewayFrame` 枚举
- 强类型的 payload 结构体/枚举
- `ErrorCode` 值和 `GATEWAY_PROTOCOL_VERSION`
未知帧类型保留为原始 payload 以实现前向兼容。
未知的帧类型保留为原始 payload 以实现向前兼容。
## 版本控制 + 兼容性
- `PROTOCOL_VERSION` 位于 `src/gateway/protocol/schema.ts`。
- 客户端发送 `minProtocol` + `maxProtocol`；服务器拒绝不匹配的版本。
- `PROTOCOL_VERSION` 在 `src/gateway/protocol/schema.ts` 中。
- 客户端发送 `minProtocol` + `maxProtocol`；服务器拒绝不匹配的。
- Swift 模型保留未知帧类型以避免破坏旧客户端。
## 模式规范和约定
## 模式模式和约定
- 大多数对象使用 `additionalProperties: false` 以实现严格的 payload。
- `NonEmptyString` 是 ID 和方法/事件名称的默认类型。
- 顶层 `Gateway网关Frame` 在 `type` 上使用**鉴别器**。
- 有副作用的方法通常需要在参数中包含 `idempotencyKey`（示例：`send`、`poll`、`agent`、`chat.send`）。
- `NonEmptyString` 是 ID 和方法/事件名称的默认值。
- 顶层 `GatewayFrame` 在 `type` 上使用**鉴别器**。
- 有副作用的方法通常需要在 params 中包含 `idempotencyKey`（示例：`send`、`poll`、`agent`、`chat.send`）。
## 实时 Schema JSON
## 实时 schema JSON
生成的 JSON Schema 位于仓库的 `dist/protocol.schema.json`。已发布的原始文件通常可在以下位置获取：
生成的 JSON Schema 在仓库的 `dist/protocol.schema.json` 中。发布的原始文件通常可在以下位置获取：
- https://raw.githubusercontent.com/openclaw/openclaw/main/dist/protocol.schema.json

82
docs/zh-CN/debugging.md
View File

@@ -1,28 +1,28 @@
---
read_when:
- 需要检查原始模型输出中的推理泄漏
- 希望在迭代开发时以监视模式运行 Gateway网关
- 需要可重复的调试工作流
summary: 调试工具：监视模式、原始模型流和推理泄漏追踪
- 你需要检查原始模型输出以查找推理泄漏
- 你想在迭代时以监视模式运行 Gateway 网关
- 你需要可重复的调试工作流
summary: 调试工具：监视模式、原始模型流和追踪推理泄漏
title: 调试
x-i18n:
generated_at: "2026-02-01T20:24:57Z"
generated_at: "2026-02-03T07:47:23Z"
model: claude-opus-4-5
provider: pi
source_hash: 504c824bff4790006c8b73600daca66b919e049178e9711e6e65b6254731911a
source_path: debugging.md
workflow: 14
workflow: 15
---
# 调试
本页介绍流式输出的调试辅助工具，尤其适用于提供商将推理内容混入正常文本的情况。
本页介绍用于流式输出的调试辅助工具，特别是当提供商将推理混入正常文本时。
## 运行时调试覆盖
在聊天中使用 `/debug` 设置**仅运行时**的配置覆盖（仅内存，不写入磁盘）。
在聊天中使用 `/debug` 设置**仅运行时**配置覆盖（内存中，不写入磁盘）。
`/debug` 默认禁用；通过 `commands.debug: true` 启用。
当你需要切换一些不常用的设置而又不想编辑 `openclaw.json` 时，这非常方便。
当你需要切换不常用的设置而不编辑 `openclaw.json` 时，这非常方便。
示例：
@@ -33,56 +33,56 @@ x-i18n:
/debug reset
```
`/debug reset` 会清除所有覆盖项，恢复为磁盘上的配置。
`/debug reset` 清除所有覆盖并返回到磁盘上的配置。
## Gateway网关监视模式
## Gateway 网关监视模式
要快速迭代，可在文件监视器下运行 Gateway网关：
为了快速迭代，在文件监视器下运行 Gateway 网关：
```bash
pnpm gateway:watch --force
```
对应命令为：
这映射到：
```bash
tsx watch src/entry.ts gateway --force
```
在 `gateway:watch` 后添加任何 Gateway网关 CLI 标志，它们会在每次重启时被透传。
在 `gateway:watch` 后添加任何 Gateway 网关 CLI 标志，它们将在每次重启时传递。
## 开发配置文件 + 开发 Gateway网关（--dev）
## Dev 配置文件 + dev Gateway 网关（--dev）
使用开发配置文件来隔离状态，搭建一个安全的、可随时丢弃的调试环境。有**两个** `--dev` 标志：
使用 dev 配置文件来隔离状态，并启动一个安全、可丢弃的调试设置。有**两个** `--dev` 标志：
- **全局 `--dev`（配置文件）：** 将状态隔离到 `~/.openclaw-dev`，并将 Gateway网关默认端口设为 `19001`（派生端口随之偏移）。
- **`gateway --dev`：告诉 Gateway网关在缺少配置和工作区时自动创建默认配置 + 工作区**（并跳过 BOOTSTRAP.md）。
- **全局 `--dev`（配置文件）：** 将状态隔离到 `~/.openclaw-dev` 下，并将 Gateway 网关端口默认为 `19001`（派生端口随之移动）。
- **`gateway --dev`：告诉 Gateway 网关在缺失时自动创建默认配置 + 工作区**（并跳过 BOOTSTRAP.md）。
推荐流程（开发配置文件 + 开发引导）：
推荐流程（dev 配置文件 + dev 引导）：
```bash
pnpm gateway:dev
OPENCLAW_PROFILE=dev openclaw tui
```
如果你还没有全局安装，可通过 `pnpm openclaw ...` 运行 CLI。
如果你还没有全局安装，请通过 `pnpm openclaw ...` 运行 CLI。
具体效果：
这会执行：
1. **配置文件隔离**（全局 `--dev`）
- `OPENCLAW_PROFILE=dev`
- `OPENCLAW_STATE_DIR=~/.openclaw-dev`
- `OPENCLAW_CONFIG_PATH=~/.openclaw-dev/openclaw.json`
- `OPENCLAW_GATEWAY_PORT=19001`（浏览器/画布端口随之偏移）
- `OPENCLAW_GATEWAY_PORT=19001`（浏览器/画布相应移动）
2. **开发引导**（`gateway --dev`）
- 如缺少配置则写入最小配置（`gateway.mode=local`，绑定 local loopback）。
- 将 `agent.workspace` 设为开发工作区。
- 设置 `agent.skipBootstrap=true`（不使用 BOOTSTRAP.md）。
- 如缺少工作区文件则进行初始化：
2. **Dev 引导**（`gateway --dev`）
- 如果缺失则写入最小配置（`gateway.mode=local`，绑定 loopback）。
- 将 `agent.workspace` 设置为 dev 工作区。
- 设置 `agent.skipBootstrap=true`（无 BOOTSTRAP.md）。
- 如果缺失则填充工作区文件：
`AGENTS.md`、`SOUL.md`、`TOOLS.md`、`IDENTITY.md`、`USER.md`、`HEARTBEAT.md`。
- 默认身份：**C3‑PO**（礼仪机器人）。
- 在开发模式下跳过渠道提供商（`OPENCLAW_SKIP_CHANNELS=1`）。
- 在 dev 模式下跳过渠道提供商（`OPENCLAW_SKIP_CHANNELS=1`）。
重置流程（全新开始）：
@@ -90,16 +90,16 @@ OPENCLAW_PROFILE=dev openclaw tui
pnpm gateway:dev:reset
```
注意：`--dev` 是一个**全局**配置文件标志，可能会被某些运行器吞掉。
如需显式指定，请使用环境变量形式：
注意：`--dev` 是**全局**配置文件标志，会被某些运行器吞掉。
如果你需要明确拼写，请使用环境变量形式：
```bash
OPENCLAW_PROFILE=dev openclaw gateway --dev --reset
```
`--reset` 会清除配置、凭据、会话和开发工作区（使用 `trash` 而非 `rm`），然后重新创建默认的开发环境。
`--reset` 清除配置、凭证、会话和 dev 工作区（使用 `trash`，而非 `rm`），然后重新创建默认的 dev 设置。
提示：如果非开发 Gateway网关已在运行（launchd/systemd），请先停止它：
提示：如果非 dev Gateway 网关已在运行（launchd/systemd），请先停止它：
```bash
openclaw gateway stop
@@ -108,7 +108,7 @@ openclaw gateway stop
## 原始流日志（OpenClaw）
OpenClaw 可以在任何过滤/格式化之前记录**原始助手流**。
这是查看推理内容是以纯文本增量到达还是以独立思考块到达的最佳方式。
这是查看推理是否作为纯文本增量到达（或作为单独的思考块）的最佳方式。
通过 CLI 启用：
@@ -116,13 +116,13 @@ OpenClaw 可以在任何过滤/格式化之前记录**原始助手流**。
pnpm gateway:watch --force --raw-stream
```
可选的路径覆盖：
可选路径覆盖：
```bash
pnpm gateway:watch --force --raw-stream --raw-stream-path ~/.openclaw/logs/raw-stream.jsonl
```
等效的环境变量：
等效环境变量：
```bash
OPENCLAW_RAW_STREAM=1
@@ -133,9 +133,9 @@ OPENCLAW_RAW_STREAM_PATH=~/.openclaw/logs/raw-stream.jsonl
`~/.openclaw/logs/raw-stream.jsonl`
## 原始数据块日志（pi-mono）
## 原始块日志（pi-mono）
要在解析为块之前捕获**原始 OpenAI 兼容数据块**，pi-mono 提供了一个独立的日志记录器：
要在解析为块之前捕获**原始 OpenAI 兼容块**，pi-mono 暴露了一个单独的日志记录器：
```bash
PI_RAW_STREAM=1
@@ -151,10 +151,10 @@ PI_RAW_STREAM_PATH=~/.pi-mono/logs/raw-openai-completions.jsonl
`~/.pi-mono/logs/raw-openai-completions.jsonl`
> 注意：此日志仅由使用 pi-mono 的 `openai-completions` 提供商的进程生成。
> 注意：这仅由使用 pi-mono 的 `openai-completions` 提供商的进程发出。
## 安全注意事项
- 原始流日志可能包含完整的提示词、工具输出和用户数据。
- 请将日志保存在本地，调试完成后及时删除。
- 如需分享日志，请先清除密钥和个人身份信息。
- 原始流日志可能包含完整提示、工具输出和用户数据。
- 保持日志在本地并在调试后删除它们。
- 如果你分享日志，请先清除密钥和个人身份信息。

32
docs/zh-CN/diagnostics/flags.md
View File

@@ -1,25 +1,25 @@
---
read_when:
- 你需要在不提升全局日志级别的情况下获取定向调试日志
- 你需要为技术支持捕获特定子系统的日志
- 你需要定向调试日志而不提高全局日志级别
- 你需要为支持人员捕获特定子系统的日志
summary: 用于定向调试日志的诊断标志
title: 诊断标志
x-i18n:
generated_at: "2026-02-01T20:24:56Z"
generated_at: "2026-02-03T10:05:34Z"
model: claude-opus-4-5
provider: pi
source_hash: daf0eca0e6bd1cbc2c400b2e94e1698709a96b9cdba1a8cf00bd580a61829124
source_path: diagnostics/flags.md
workflow: 14
workflow: 15
---
# 诊断标志
诊断标志允许你在不开启全局详细日志的情况下启用定向调试日志。标志为可选启用，除非相关子系统检查了它们，否则不会产生任何效果。
诊断标志让你可以启用定向调试日志，而无需在所有地方开启详细日志。标志是可选启用的，除非子系统检查它们，否则不会生效。
## 工作原理
- 标志为字符串（不区分大小写）。
- 标志是字符串（不区分大小写）。
- 你可以在配置中或通过环境变量覆盖来启用标志。
- 支持通配符：
- `telegram.*` 匹配 `telegram.http`
@@ -45,7 +45,7 @@ x-i18n:
}
```
更改标志后需重启 Gateway网关。
更改标志后重启 Gateway 网关。
## 环境变量覆盖（一次性）
@@ -59,15 +59,15 @@ OPENCLAW_DIAGNOSTICS=telegram.http,telegram.payload
OPENCLAW_DIAGNOSTICS=0
```
## 日志输出位置
## 日志存储位置
标志会将日志输出到标准诊断日志文件中。默认路径为：
标志将日志输出到标准诊断日志文件。默认位置：
```
/tmp/openclaw/openclaw-YYYY-MM-DD.log
```
如果你设置了 `logging.file`，则使用该路径。日志格式为 JSONL（每行一个 JSON 对象）。脱敏处理仍根据 `logging.redactSensitive` 设置生效。
如果你设置了 `logging.file`，则使用该路径。日志为 JSONL 格式（每行一个 JSON 对象）。脱敏仍然根据 `logging.redactSensitive` 应用。
## 提取日志
@@ -77,22 +77,22 @@ OPENCLAW_DIAGNOSTICS=0
ls -t /tmp/openclaw/openclaw-*.log | head -n 1
```
筛选 Telegram HTTP 诊断信息：
过滤 Telegram HTTP 诊断：
```bash
rg "telegram http error" /tmp/openclaw/openclaw-*.log
```
或在复现问题时实时追踪：
或在复现时使用 tail：
```bash
tail -f /tmp/openclaw/openclaw-$(date +%F).log | rg "telegram http error"
```
对于远程 Gateway网关，你也可以使用 `openclaw logs --follow`（参见 [/cli/logs](/cli/logs)）。
对于远程 Gateway 网关，你也可以使用 `openclaw logs --follow`（参见 [/cli/logs](/cli/logs)）。
## 注意事项
- 如果 `logging.level` 设置为高于 `warn` 的级别，这些日志可能会被抑制。默认的 `info` 级别即可。
- 标志可以安全地保持启用状态；它们只会影响特定子系统的日志量。
- 使用 [/logging](/logging) 更改日志输出目标、级别和脱敏设置。
- 如果 `logging.level` 设置为高于 `warn`，这些日志可能会被抑制。默认的 `info` 级别即可。
- 标志可以安全地保持启用状态；它们只影响特定子系统的日志量。
- 使用 [/logging](/logging) 更改日志目标、级别和脱敏设置。

42
docs/zh-CN/environment.md
View File

@@ -1,36 +1,36 @@
---
read_when:
- 需要了解加载了哪些环境变量及其加载顺序
- 正在调试 Gateway网关中缺失的 API 密钥
- 正在编写提供商认证或部署环境的文档
summary: OpenClaw 从哪里加载环境变量及其优先级顺序
- 你需要知道哪些环境变量被加载，以及加载顺序
- 你在调试 Gateway 网关中缺失的 API 密钥
- 你在编写提供商认证或部署环境的文档
summary: OpenClaw 从哪里加载环境变量以及优先级顺序
title: 环境变量
x-i18n:
generated_at: "2026-02-01T20:24:58Z"
generated_at: "2026-02-03T07:47:11Z"
model: claude-opus-4-5
provider: pi
source_hash: b49ae50e5d306612f89f93a86236188a4f2ec23f667e2388b043832be3ac1546
source_path: environment.md
workflow: 14
workflow: 15
---
# 环境变量
OpenClaw 从多个来源获取环境变量。规则是**永远不覆盖已有的值**。
OpenClaw 从多个来源拉取环境变量。规则是**永不覆盖现有值**。
## 优先级（从高到低）
1. **进程环境**（Gateway网关进程从父 shell/守护进程继承的变量）。
2. **当前工作目录下的 `.env`**（dotenv 默认行为；不覆盖已有值）。
3. **全局 `.env`**，位于 `~/.openclaw/.env`（即 `$OPENCLAW_STATE_DIR/.env`；不覆盖已有值）。
4. **配置文件中的 `env` 块**，位于 `~/.openclaw/openclaw.json`（仅在变量缺失时应用）。
5. **可选的登录 shell 导入**（`env.shellEnv.enabled` 或 `OPENCLAW_LOAD_SHELL_ENV=1`），仅对缺失的预期键生效。
1. **进程环境**（Gateway 网关进程从父 shell/守护进程已有的内容）。
2. **当前工作目录中的 `.env`**（dotenv 默认；不覆盖）。
3. **全局 `.env`** 位于 `~/.openclaw/.env`（即 `$OPENCLAW_STATE_DIR/.env`；不覆盖）。
4. **配置 `env` 块** 位于 `~/.openclaw/openclaw.json`（仅在缺失时应用）。
5. **可选的登录 shell 导入**（`env.shellEnv.enabled` 或 `OPENCLAW_LOAD_SHELL_ENV=1`），仅对缺失的预期键名应用。
如果配置文件完全不存在，则跳过步骤 4；如果已启用，shell 导入仍会运行。
如果配置文件完全缺失，步骤 4 将被跳过；如果启用了 shell 导入，它仍会运行。
## 配置文件 `env` 块
## 配置 `env` 块
有两种等效方式设置内联环境变量（两者都不覆盖已有值）：
两种等效方式设置内联环境变量（都是非覆盖的）：
```json5
{
@@ -45,7 +45,7 @@ OpenClaw 从多个来源获取环境变量。规则是**永远不覆盖已有的
## Shell 环境导入
`env.shellEnv` 会运行你的登录 shell，并仅导入**缺失的**预期键：
`env.shellEnv` 运行你的登录 shell 并仅导入**缺失的**预期键名：
```json5
{
@@ -58,7 +58,7 @@ OpenClaw 从多个来源获取环境变量。规则是**永远不覆盖已有的
}
```
等效的环境变量：
环境变量等效项：
- `OPENCLAW_LOAD_SHELL_ENV=1`
- `OPENCLAW_SHELL_ENV_TIMEOUT_MS=15000`
@@ -79,10 +79,10 @@ OpenClaw 从多个来源获取环境变量。规则是**永远不覆盖已有的
}
```
详情请参阅[配置：环境变量替换](/gateway/configuration#env-var-substitution-in-config)。
完整详情参见[配置：环境变量替换](/gateway/configuration#env-var-substitution-in-config)。
## 相关内容
- [Gateway网关配置](/gateway/configuration)
- [常见问题：环境变量与 .env 加载](/help/faq#env-vars-and-env-loading)
- [模型概览](/concepts/models)
- [Gateway 网关配置](/gateway/configuration)
- [常见问题：环境变量和 .env 加载](/help/faq#env-vars-and-env-loading)
- [模型概述](/concepts/models)

28
docs/zh-CN/experiments/onboarding-config-protocol.md
View File

@@ -1,29 +1,29 @@
---
read_when: 修改新手引导向导步骤或配置 schema 端点时
summary: 新手引导向导和配置 schema 的 RPC 协议说明
title: 新手引导与配置协议
read_when: Changing onboarding wizard steps or config schema endpoints
summary: 新手引导向导和配置模式的 RPC 协议说明
title: 新手引导和配置协议
x-i18n:
generated_at: "2026-02-01T20:24:58Z"
generated_at: "2026-02-03T07:47:10Z"
model: claude-opus-4-5
provider: pi
source_hash: 55163b3ee029c02476800cb616a054e5adfe97dae5bb72f2763dce0079851e06
source_path: experiments/onboarding-config-protocol.md
workflow: 14
workflow: 15
---
# 新手引导 + 配置协议
用途：在 CLI、macOS 应用和 Web UI 之间共享新手引导与配置界面。
目的：CLI、macOS 应用和 Web UI 之间共享的新手引导 + 配置界面。
## 组件
- 向导引擎（共享会话 + 提示 + 新手引导状态）。
- CLI 新手引导使用与 UI 客户端相同的向导流程。
- Gateway网关 RPC 暴露向导 + 配置 schema 端点。
- Gateway 网关 RPC 公开向导 + 配置模式端点。
- macOS 新手引导使用向导步骤模型。
- Web UI 根据 JSON Schema + UI 提示渲染配置表单。
- Web UI 从 JSON Schema + UI 提示渲染配置表单。
## Gateway网关 RPC
## Gateway 网关 RPC
- `wizard.start` 参数：`{ mode?: "local"|"remote", workspace?: string }`
- `wizard.next` 参数：`{ sessionId, answer?: { stepId, value? } }`
@@ -34,14 +34,14 @@ x-i18n:
响应（结构）
- 向导：`{ sessionId, done, step?, status?, error? }`
- 配置 schema：`{ schema, uiHints, version, generatedAt }`
- 配置模式：`{ schema, uiHints, version, generatedAt }`
## UI 提示
- `uiHints` 按路径作为键；可选元数据（label/help/group/order/advanced/sensitive/placeholder）。
- 敏感字段渲染为密码输入框；无脱敏层。
- 不支持的 schema 节点回退到原始 JSON 编辑器。
- `uiHints` 按路径键入；可选元数据（label/help/group/order/advanced/sensitive/placeholder）。
- 敏感字段渲染为密码输入；无脱敏层。
- 不支持的模式节点回退到原始 JSON 编辑器。
## 说明
## 注意
- 本文档是跟踪新手引导/配置协议重构的唯一位置。

56
docs/zh-CN/experiments/plans/cron-add-hardening.md
View File

@@ -2,69 +2,69 @@
last_updated: "2026-01-05"
owner: openclaw
status: complete
summary: 加固 cron.add 输入处理，对齐 schema，并改进 cron UI/智能体工具
summary: 加固 cron.add 输入处理，对齐 schema，改进 cron UI/智能体工具
title: Cron Add 加固
x-i18n:
generated_at: "2026-02-01T20:25:08Z"
generated_at: "2026-02-03T07:47:26Z"
model: claude-opus-4-5
provider: pi
source_hash: d7e469674bd9435b846757ea0d5dc8f174eaa8533917fc013b1ef4f82859496d
source_path: experiments/plans/cron-add-hardening.md
workflow: 14
workflow: 15
---
# Cron Add 加固与 Schema 对齐
# Cron Add 加固 & Schema 对齐
## 背景
近期 Gateway网关日志显示 `cron.add` 反复因无效参数（缺少 `sessionTarget`、`wakeMode`、`payload` 以及格式错误的 `schedule`）而失败。这表明至少有一个客户端（可能是智能体工具调用路径）正在发送包装过的或部分指定的任务载荷。此外，TypeScript、Gateway网关 schema、CLI 标志和 UI 表单类型之间的 cron 提供商枚举存在偏差，同时 `cron.status` 的 UI 也存在不匹配问题（期望 `jobCount`，而 Gateway网关返回的是 `jobs`）。
最近的 Gateway 网关日志显示重复的 `cron.add` 失败，参数无效（缺少 `sessionTarget`、`wakeMode`、`payload`，以及格式错误的 `schedule`）。这表明至少有一个客户端（可能是智能体工具调用路径）正在发送包装的或部分指定的任务负载。另外，TypeScript 中的 cron 提供商枚举、Gateway 网关 schema、CLI 标志和 UI 表单类型之间存在漂移，加上 `cron.status` 的 UI 不匹配（期望 `jobCount` 而 Gateway 网关返回 `jobs`）。
## 目标
- 通过标准化常见的包装载荷并推断缺失的 `kind` 字段，消除 `cron.add` 的 INVALID_REQUEST 错误。
- 在 Gateway网关 schema、cron 类型、CLI 文档和 UI 表单之间对齐 cron 提供商列表。
- 明确智能体 cron 工具 schema，使 LLM 生成正确的任务载荷。
- 修复 Control UI 中 cron 状态的任务计数显示。
- 添加测试以覆盖标准化和工具行为。
- 通过规范化常见的包装负载并推断缺失的 `kind` 字段来停止 `cron.add` INVALID_REQUEST 垃圾。
- 在 Gateway 网关 schema、cron 类型、CLI 文档和 UI 表单之间对齐 cron 提供商列表。
- 使智能体 cron 工具 schema 明确，以便 LLM 生成正确的任务负载。
- 修复 Control UI cron 状态任务计数显示。
- 添加测试以覆盖规范化和工具行为。
## 非目标
- 更改 cron 调度语义或任务执行行为。
- 添加新的调度类型或 cron 表达式解析。
- 在必要的字段修复之外全面改造 cron 的 UI/UX。
- 除了必要的字段修复外，不大改 cron 的 UI/UX。
## 发现（当前差距）
- Gateway网关中的 `CronPayloadSchema` 不包含 `signal` + `imessage`，而 TS 类型中包含它们。
- Control UI 的 CronStatus 期望 `jobCount`，但 Gateway网关返回的是 `jobs`。
- Gateway 网关中的 `CronPayloadSchema` 排除了 `signal` + `imessage`，而 TS 类型包含它们。
- Control UI CronStatus 期望 `jobCount`，但 Gateway 网关返回 `jobs`。
- 智能体 cron 工具 schema 允许任意 `job` 对象，导致格式错误的输入。
- Gateway网关严格验证 `cron.add` 且不进行标准化，因此包装过的载荷会失败。
- Gateway 网关严格验证 `cron.add` 而不进行规范化，因此包装的负载会失败。
## 变更内容
- `cron.add` 和 `cron.update` 现在会标准化常见的包装结构并推断缺失的 `kind` 字段。
- 智能体 cron 工具 schema 与 Gateway网关 schema 保持一致，减少了无效载荷。
- 提供商枚举已在 Gateway网关、CLI、UI 和 macOS 选择器之间对齐。
- Control UI 使用 Gateway网关的 `jobs` 计数字段显示状态。
- `cron.add` 和 `cron.update` 现在规范化常见的包装形式并推断缺失的 `kind` 字段。
- 智能体 cron 工具 schema 与 Gateway 网关 schema 匹配，减少无效负载。
- 提供商枚举在 Gateway 网关、CLI、UI 和 macOS 选择器之间对齐。
- Control UI 使用 Gateway 网关的 `jobs` 计数字段显示状态。
## 当前行为
- **标准化：** 包装的 `data`/`job` 载荷会被解包；在安全的情况下推断 `schedule.kind` 和 `payload.kind`。
- **默认值：** 当 `wakeMode` 和 `sessionTarget` 缺失时，应用安全的默认值。
- **提供商：** Discord/Slack/Signal/iMessage 现在在 CLI/UI 中一致地显示。
- **规范化：**包装的 `data`/`job` 负载被解包；`schedule.kind` 和 `payload.kind` 在安全时被推断。
- **默认值：**当缺失时，为 `wakeMode` 和 `sessionTarget` 应用安全默认值。
- **提供商：**Discord/Slack/Signal/iMessage 现在在 CLI/UI 中一致显示。
请参阅 [Cron 任务](/automation/cron-jobs) 了解标准化后的结构和示例。
参见 [Cron 任务](/automation/cron-jobs) 了解规范化的形式和示例。
## 验证
- 监控 Gateway网关日志，确认 `cron.add` INVALID_REQUEST 错误已减少。
- 确认 Control UI 的 cron 状态在刷新后显示任务计数。
- 观察 Gateway 网关日志中 `cron.add` INVALID_REQUEST 错误是否减少。
- 确认 Control UI cron 状态在刷新后显示任务计数。
## 可选后续工作
- 手动 Control UI 冒烟测试：为每个提供商添加一个 cron 任务，并验证状态任务计数。
- 手动 Control UI 冒烟测试：为每个提供商添加一个 cron 任务 + 验证状态任务计数。
## 待解决问题
## 开放问题
- `cron.add` 是否应接受客户端显式指定的 `state`（目前被 schema 禁止）？
- 是否应允许 `webchat` 作为显式的投递提供商（目前在投递解析中被过滤）？
- `cron.add` 是否应该接受来自客户端的显式 `state`（当前被 schema 禁止）？
- 我们是否应该允许 `webchat` 作为显式投递提供商（当前在投递解析中被过滤）？

28
docs/zh-CN/experiments/plans/group-policy-hardening.md
View File

@@ -1,15 +1,15 @@
---
read_when:
- 审查 Telegram 允许列表的历史变更
summary: Telegram 允许列表加固：前缀与空白字符规范化
- 查看历史 Telegram 允许列表更改
summary: Telegram 允许列表加固：前缀 + 空白规范化
title: Telegram 允许列表加固
x-i18n:
generated_at: "2026-02-01T20:25:02Z"
generated_at: "2026-02-03T07:47:16Z"
model: claude-opus-4-5
provider: pi
source_hash: a2eca5fcc85376948cfe1b6044f1a8bc69c7f0eb94d1ceafedc1e507ba544162
source_path: experiments/plans/group-policy-hardening.md
workflow: 14
workflow: 15
---
# Telegram 允许列表加固
@@ -18,28 +18,28 @@ x-i18n:
**状态**：已完成
**PR**：#216
## 概要
## 摘要
Telegram 允许列表现在以不区分大小写的方式接受 `telegram:` 和 `tg:` 前缀，并容许意外的空白字符。这使得入站允许列表检查与出站发送的规范化保持一致。
Telegram 允许列表现在不区分大小写地接受 `telegram:` 和 `tg:` 前缀，并容忍意外的空白。这使入站允许列表检查与出站发送规范化保持一致。
## 变更内容
## 更改内容
- 前缀 `telegram:` 和 `tg:` 被视为相同（不区分大小写）。
- 允许列表条目会被修剪空白；空条目将被忽略。
- 前缀 `telegram:` 和 `tg:` 被同等对待（不区分大小写）。
- 允许列表条目会被修剪；空条目会被忽略。
## 示例
以下所有格式均被接受为同一 ID：
以下所有形式都被接受为同一 ID：
- `telegram:123456`
- `TG:123456`
- `tg:123456`
## 重要性
## 为什么重要
从日志或聊天 ID 中复制粘贴时经常会包含前缀和空白字符。规范化处理可以避免在决定是否响应私聊或群组消息时出现误判。
从日志或聊天 ID 复制/粘贴通常会包含前缀和空白。规范化可避免在决定是否在私信或群组中响应时出现误判。
## 相关文档
- [群组聊天](/concepts/groups)
- [Telegram 渠道](/channels/telegram)
- [群聊](/concepts/groups)
- [Telegram 提供商](/channels/telegram)

90
docs/zh-CN/experiments/plans/openresponses-gateway.md
View File

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

170
docs/zh-CN/experiments/research/memory.md
View File

@@ -1,67 +1,67 @@
---
read_when:
- 设计超越每日 Markdown 日志的工作区记忆（~/.openclaw/workspace）
- 决策：独立 CLI 还是深度集成 OpenClaw
- 添加离线召回 + 反思（retain/recall/reflect）
summary: 研究笔记：Clawd 工作区离线记忆系统（Markdown 作为事实来源 + 派生索引）
- Deciding: standalone CLI vs deep OpenClaw integration
- 添加离线回忆 + 反思（retain/recall/reflect）
summary: 研究笔记：Clawd 工作区的离线记忆系统（Markdown 作为数据源 + 派生索引）
title: 工作区记忆研究
x-i18n:
generated_at: "2026-02-01T20:25:43Z"
generated_at: "2026-02-03T10:06:14Z"
model: claude-opus-4-5
provider: pi
source_hash: 1753c8ee6284999fab4a94ff5fae7421c85233699c9d3088453d0c2133ac0feb
source_path: experiments/research/memory.md
workflow: 14
workflow: 15
---
# 工作区记忆 v2（离线）：研究笔记
目标：Clawd 风格的工作区（`agents.defaults.workspace`，默认 `~/.openclaw/workspace`），其中"记忆"以每日一个 Markdown 文件（`memory/YYYY-MM-DD.md`）加上一小组稳定文件（如 `memory.md`、`SOUL.md`）的形式存储。
目标：Clawd 风格的工作区（`agents.defaults.workspace`，默认 `~/.openclaw/workspace`），其中"记忆"以每天一个 Markdown 文件（`memory/YYYY-MM-DD.md`）加上一小组稳定文件（例如 `memory.md`、`SOUL.md`）的形式存储。
本文档提出一种**离线优先**的记忆架构，保持 Markdown 作为规范的、可审查的事实来源，同时通过派生索引添加**结构化召回**（搜索、实体摘要、置信度更新）。
本文档提出一种**离线优先**的记忆架构，保持 Markdown 作为规范的、可审查的数据源，但通过派生索引添加**结构化回忆**（搜索、实体摘要、置信度更新）。
## 为什么要改变？
当前方案（每日一个文件）非常适合：
当前设置（每天一个文件）非常适合：
- "仅追加"的日志记录
- "仅追加"式日志记录
- 人工编辑
- git 支持的持久性 + 可审计性
- 低摩擦的信息捕获（"直接写下来就好"）
- 低摩擦捕获（"直接写下来"）
但在以下方面表现较弱：
但它在以下方面较弱：
- 高召回率检索（"我们对 X 做了什么决定？"、"上次我们尝试 Y 是什么时候？"）
- 以实体为中心的回答（"告诉我关于 Alice / The Castle / warelay 的信息"）而无需重读大量文件
- 观点/偏好的稳定性（以及变化时的证据）
- 时间约束（"2025 年 11 月期间什么是成立的？"）和冲突解决
- 高召回率检索（"我们对 X 做了什么决定？"、"上次我们尝试 Y 时？"）
- 以实体为中心的答案（"告诉我关于 Alice / The Castle / warelay 的信息"）而无需重读多个文件
- 观点/偏好稳定性（以及变化时的证据）
- 时间约束（"2025 年 11 月期间什么是真实的？"）和冲突解决
## 设计目标
- **离线**：无需网络即可工作；可在笔记本/Castle 上运行；无云端依赖。
- **可解释**：检索到的条目应可溯源（文件 + 位置）且与推理结果可分离。
- **低仪式感**：每日记录保持 Markdown 格式，无需繁重的 schema 工作。
- **增量式**：v1 仅用全文搜索即可发挥作用；语义/向量和图谱是可选升级。
- **智能体友好**：使"在 token 预算内召回"变得简单（返回小型事实包）。
- **离线**：无需网络即可工作；可在笔记本电脑/Castle 上运行；无云依赖。
- **可解释**：检索的项目应该可归因（文件 + 位置）并与推理分离。
- **低仪式感**：每日日志保持 Markdown，无需繁重的 schema 工作。
- **增量式**：v1 仅使用 FTS 就很有用；语义/向量和图是可选升级。
- **对智能体友好**：使"在 token 预算内回忆"变得简单（返回小型事实包）。
## 北极星模型（Hindsight × Letta）
需要融合两部分：
需要融合两个部分：
1. **Letta/MemGPT 风格的控制循环**
- 保持一个小型"核心"始终在上下文中（角色设定 + 关键用户事实）
- 保持一个小的"核心"始终在上下文中（角色 + 关键用户事实）
- 其他所有内容都在上下文之外，通过工具检索
- 记忆写入是显式的工具调用（追加/替换/插入），持久化后在下一轮重新注入
- 记忆写入是显式的工具调用（append/replace/insert），持久化后在下一轮重新注入
2. **Hindsight 风格的记忆基底**
- 区分观察到的、认为的和总结的内容
- 分离观察到的、相信的和总结的内容
- 支持 retain/recall/reflect
- 带有置信度的观点，可随证据演变
- 带有置信度的观点可以随证据演变
- 实体感知检索 + 时间查询（即使没有完整的知识图谱）
## 提议架构（Markdown 事实来源 + 派生索引）
## 提议的架构（Markdown 数据源 + 派生索引）
### 规范存储（git 友好）
@@ -71,12 +71,12 @@ x-i18n:
```
~/.openclaw/workspace/
memory.md # 小型：持久事实 + 偏好（核心级别）
memory.md # 小型：持久事实 + 偏好（类似核心）
memory/
YYYY-MM-DD.md # 每日日志（追加；叙事性）
YYYY-MM-DD.md # 每日日志（追加；叙事）
bank/ # "类型化"记忆页面（稳定、可审查）
world.md # 关于世界的客观事实
experience.md # 智能体做过什么（第一人称）
experience.md # 智能体做了什么（第一人称）
opinions.md # 主观偏好/判断 + 置信度 + 证据指针
entities/
Peter.md
@@ -85,40 +85,40 @@ x-i18n:
...
```
说明：
注意：
- **每日日志保持为每日日志**。无需将其转为 JSON。
- **每日日志保持为每日日志**。无需将其转换为 JSON。
- `bank/` 文件是**经过整理的**，由反思任务生成，仍可手动编辑。
- `memory.md` 保持"小型 + 核心级别"：你希望 Clawd 每次会话都能看到的内容。
- `memory.md` 保持"小型 + 类似核心"：你希望 Clawd 每次会话都能看到的内容。
### 派生存储（机器召回）
### 派生存储（机器回忆）
在工作区下添加派生索引（不一定纳入 git 追踪）：
在工作区下添加派生索引（不一定需要 git 跟踪）：
```
~/.openclaw/workspace/.memory/index.sqlite
```
底层支持：
后端支持：
- SQLite schema，用于事实 + 实体链接 + 观点元数据
- SQLite **FTS5**，用于词法召回（快速、轻量、离线）
- 可选的嵌入表，用于语义召回（仍然离线）
- 用于事实 + 实体链接 + 观点元数据的 SQLite schema
- SQLite **FTS5** 用于词法回忆（快速、小巧、离线）
- 可选的嵌入表用于语义回忆（仍然离线）
索引始终**可从 Markdown 重建**。
## Retain / Recall / Reflect（运行循环）
## Retain / Recall / Reflect（操作循环）
### Retain：将每日日志规范化为"事实"
Hindsight 在此处的关键洞察：存储**叙事性的、自包含的事实**，而非零散片段。
Hindsight 在这里重要的关键洞察：存储**叙事性、自包含的事实**，而不是微小的片段。
`memory/YYYY-MM-DD.md` 的实用规则：
- 在一天结束时（或期间），添加一个 `## Retain` 部分，包含 2–5 个要点，要求：
- 叙事性（保留跨轮次上下文）
- 自包含（后续单独查看也能理解）
- 标注类型 + 实体提及
- 在一天结束时（或期间），添加一个 `## Retain` 部分，包含 2-5 个要点：
- 叙事性（保留跨轮上下文）
- 自包含（独立时也有意义）
- 标记类型 + 实体提及
示例：
@@ -131,25 +131,25 @@ Hindsight 在此处的关键洞察：存储**叙事性的、自包含的事实**
最小化解析：
- 类型前缀：`W`（世界）、`B`（经历/传记）、`O`（观点）、`S`（观察/摘要；通常自动生成）
- 类型前缀：`W`（世界）、`B`（经历/传记）、`O`（观点）、`S`（观察/摘要；通常是生成的）
- 实体：`@Peter`、`@warelay` 等（slug 映射到 `bank/entities/*.md`）
- 观点置信度：`O(c=0.0..1.0)` 可选
如果不想让作者考虑这些：反思任务可以从日志的其余部分推断这些要点，但显式的 `## Retain` 部分是最简单的"质量杠杆"。
如果你不想让作者考虑这些：反思任务可以从日志的其余部分推断这些要点，但有一个显式的 `## Retain` 部分是最简单的"质量杠杆"。
### Recall：在派生索引上查询
### Recall：对派生索引的查询
召回应支持：
Recall 应支持：
- **词法**："查找精确术语/名称/命令"（FTS5）
- **实体**："告诉我关于 X 的信息"（实体页面 + 实体关联的事实）
- **时间**："11 月 27 日前后发生了什么"/"上周以来"
- **观点**："Peter 偏好什么？"（附带置信度 + 证据）
- **词法**："查找精确的术语/名称/命令"（FTS5）
- **实体**："告诉我关于 X 的信息"（实体页面 + 实体链接的事实）
- **时间**："11 月 27 日前后发生了什么"/"自上周以来"
- **观点**："Peter 偏好什么？"（带置信度 + 证据）
返回格式应对智能体友好并引用来源：
- `kind`（`world|experience|opinion|observation`）
- `timestamp`（来源日期，或提取的时间范围（如存在））
- `timestamp`（来源日期，或如果存在则提取的时间范围）
- `entities`（`["Peter","warelay"]`）
- `content`（叙事性事实）
- `source`（`memory/2025-11-27.md#L12` 等）
@@ -158,78 +158,78 @@ Hindsight 在此处的关键洞察：存储**叙事性的、自包含的事实**
反思是一个定时任务（每日或心跳 `ultrathink`），它：
- 根据近期事实更新 `bank/entities/*.md`（实体摘要）
- 根据强化/矛盾更新 `bank/opinions.md` 的置信度
- 可选地提议对 `memory.md` 的编辑（"核心级别"持久事实）
- 根据最近的事实更新 `bank/entities/*.md`（实体摘要）
- 根据强化/矛盾更新 `bank/opinions.md` 置信度
- 可选地提议对 `memory.md`（"类似核心"的持久事实）的编辑
观点演变（简单、可解释）：
- 每个观点包含：
- 每个观点有：
- 陈述
- 置信度 `c ∈ [0,1]`
- 最后更新时间
- last_updated
- 证据链接（支持 + 矛盾的事实 ID）
- 当新事实到达时：
- 通过实体重叠 + 相似度查找候选观点（先 FTS，后嵌入）
- 以小增量更新置信度；大幅变动需要强矛盾 + 反复出现的证据
- 通过实体重叠 + 相似性找到候选观点（先 FTS，后嵌入）
- 通过小幅增量更新置信度；大幅跳跃需要强矛盾 + 重复证据
## CLI 集成：独立 vs 深度集成
建议：**深度集成到 OpenClaw**，但保持核心库可分离。
建议：**深度集成到 OpenClaw**，但保持可分离的核心库。
### 为什么集成到 OpenClaw？
### 为什么要集成到 OpenClaw？
- OpenClaw 已经知道：
- 工作区路径（`agents.defaults.workspace`）
- 会话模型 + 心跳
- 日志 + 故障排除模式
- 你希望智能体自身调用这些工具：
- 日志记录 + 故障排除模式
- 你希望智能体自己调用工具：
- `openclaw memory recall "…" --k 25 --since 30d`
- `openclaw memory reflect --since 7d`
### 为什么仍然拆分为库？
### 为什么仍要分离库？
- 保持记忆逻辑可在无 Gateway网关/运行时的情况下测试
- 可在其他上下文中复用（本地脚本、未来的桌面应用等）
- 保持记忆逻辑可测试，无需 Gateway 网关/运行时
- 可从其他上下文重用（本地脚本、未来的桌面应用等）
形态：
记忆工具计划作为一个小型 CLI + 库层，但目前仅处于探索阶段。
记忆工具预计是一个小型 CLI + 库层，但这仅是探索性的。
## "S-Collide" / SuCo：何时使用（研究）
如果"S-Collide"指的是 **SuCo（Subspace Collision）**：这是一种近似最近邻检索方法，通过在子空间中使用学习/结构化碰撞来实现强召回率/延迟权衡（论文：arXiv 2411.14754, 2024）。
如果"S-Collide"指的是 **SuCo（Subspace Collision）**：这是一种 ANN 检索方法，通过在子空间中使用学习/结构化碰撞来实现强召回/延迟权衡（论文：arXiv 2411.14754，2024）。
对于 `~/.openclaw/workspace` 的务实建议：
对于 `~/.openclaw/workspace` 的务实观点：
- **不要从** SuCo 开始。
- 从 SQLite FTS +（可选的）简单嵌入开始；你将立即获得大部分用户体验收益。
- 仅在以下情况时考虑 SuCo/HNSW/ScaNN 级别的方案：
- 语料库很大（数万/数十万个片段）
- 从 SQLite FTS +（可选的）简单嵌入开始；你会立即获得大部分 UX 收益。
- 仅在以下情况下考虑 SuCo/HNSW/ScaNN 级别的解决方案：
- 语料库很大（数万/数十万个块）
- 暴力嵌入搜索变得太慢
- 召回质量明显受限于词法搜索
- 召回质量明显受到词法搜索的瓶颈限制
离线友好的替代方案（按复杂度递增）：
离线友好的替代方案（按复杂性递增）：
- SQLite FTS5 + 元数据过滤（零 ML）
- 嵌入 + 暴力搜索（如果片段数量少，效果出乎意料地好）
- 嵌入 + 暴力搜索（如果块数量低，效果出奇地好）
- HNSW 索引（常见、稳健；需要库绑定）
- SuCo（研究级别；如果有可嵌入的可靠实现则很有吸引力）
- SuCo（研究级；如果有可嵌入的可靠实现则很有吸引力）
开放问题：
- 在你的机器（笔记本 + 台式机）上，**最佳**的离线嵌入模型是什么，用于"个人助手记忆"？
- 如果已有 Ollama：使用本地模型进行嵌入；否则在工具链中附带一个小型嵌入模型。
- 对于你的机器（笔记本 + 台式机）上的"个人助理记忆"，**最佳**的离线嵌入模型是什么？
- 如果你已经有 Ollama：使用本地模型嵌入；否则在工具链中附带一个小型嵌入模型。
## 最小可用试点
如果你想要一个最小但仍然有用的版本：
如果你想要一个最小但仍有用的版本：
- 添加 `bank/` 实体页面和每日日志中的 `## Retain` 部分。
- 使用 SQLite FTS 进行带引用（路径 + 行号）的召回。
- 仅在召回质量或规模有需求时才添加嵌入。
- 使用 SQLite FTS 进行带引用的回忆（路径 + 行号）。
- 仅在召回质量或规模需要时添加嵌入。
## 参考资料
- Letta / MemGPT 概念："核心记忆块" + "归档记忆" + 工具驱动的自编辑记忆。
- Hindsight 技术报告："retain / recall / reflect"、四网络记忆、叙事性事实提取、观点置信度演变。
- SuCo：arXiv 2411.14754 (2024)："Subspace Collision" 近似最近邻检索。
- Letta / MemGPT 概念："核心记忆块" + "档案记忆" + 工具驱动的自编辑记忆。
- Hindsight 技术报告："retain / recall / reflect"，四网络记忆，叙事性事实提取，观点置信度演变。
- SuCo：arXiv 2411.14754（2024）："Subspace Collision"近似最近邻检索。

58
docs/zh-CN/gateway/authentication.md
View File

@@ -1,37 +1,37 @@
---
read_when:
- 调试模型认证或 OAuth 过期问题
- 编写认证或凭据存储相关文档
- 调试模型认证或 OAuth 过期
- 记录认证或凭证存储
summary: 模型认证：OAuth、API 密钥和 setup-token
title: 认证
x-i18n:
generated_at: "2026-02-01T20:25:19Z"
generated_at: "2026-02-03T07:47:32Z"
model: claude-opus-4-5
provider: pi
source_hash: 66fa2c64ff374c9cfcdb4e7a951b0d164d512295e65513eb682f12191b75e557
source_path: gateway/authentication.md
workflow: 14
workflow: 15
---
# 认证
OpenClaw 支持通过 OAuth 和 API 密钥对模型提供商进行认证。对于 Anthropic 账户，我们推荐使用 **API 密钥**。对于 Claude 订阅访问，请使用 `claude setup-token` 创建的长期有效令牌。
OpenClaw 支持模型提供商的 OAuth 和 API 密钥。对于 Anthropic 账户，我们推荐使用 **API 密钥**。对于 Claude 订阅访问，使用 `claude setup-token` 创建的长期令牌。
参见 [/concepts/oauth](/concepts/oauth) 了解全部 OAuth 流程和存储布局。
参阅 [/concepts/oauth](/concepts/oauth) 了解完整的 OAuth 流程和存储布局。
## 推荐的 Anthropic 设置（API 密钥）
如果你直接使用 Anthropic，请使用 API 密钥。
1. 在 Anthropic 控制台中创建 API 密钥。
2. 将其放置在 **Gateway网关主机**（运行 `openclaw gateway` 的机器）上。
1. 在 Anthropic 控制台创建 API 密钥。
2. 将其放在 **Gateway 网关主机**（运行 `openclaw gateway` 的机器）上。
```bash
export ANTHROPIC_API_KEY="..."
openclaw models status
```
3. 如果 Gateway网关在 systemd/launchd 下运行，建议将密钥放在 `~/.openclaw/.env` 中，以便守护进程能够读取：
3. 如果 Gateway 网关在 systemd/launchd 下运行，最好将密钥放在 `~/.openclaw/.env` 中以便守护进程可以读取：
```bash
cat >> ~/.openclaw/.env <<'EOF'
@@ -39,59 +39,59 @@ ANTHROPIC_API_KEY=...
EOF
```
然后重启守护进程（或重启 Gateway网关进程）并重新检查：
然后重启守护进程（或重启你的 Gateway 网关进程）并重新检查：
```bash
openclaw models status
openclaw doctor
```
如果你不想自行管理环境变量，新手引导向导可以为守护进程存储 API 密钥：`openclaw onboard`。
如果你不想自己管理环境变量，新手引导向导可以为守护进程使用存储 API 密钥：`openclaw onboard`。
参见[帮助](/help)了解环境变量继承的详细信息（`env.shellEnv`、`~/.openclaw/.env`、systemd/launchd）。
参阅[帮助](/help)了解环境变量继承的详情（`env.shellEnv`、`~/.openclaw/.env`、systemd/launchd）。
## Anthropic：setup-token（订阅认证）
对于 Anthropic，推荐的方式是使用 **API 密钥**。如果你使用的是 Claude 订阅，也支持 setup-token 流程。在 **Gateway网关主机**上运行：
对于 Anthropic，推荐的路径是 **API 密钥**。如果你使用 Claude 订阅，也支持 setup-token 流程。在 **Gateway 网关主机**上运行：
```bash
claude setup-token
```
然后将其粘贴到 OpenClaw 中：
然后将其粘贴到 OpenClaw：
```bash
openclaw models auth setup-token --provider anthropic
```
如果令牌是在另一台机器上创建的，请手动粘贴：
如果令牌是在另一台机器上创建的，手动粘贴：
```bash
openclaw models auth paste-token --provider anthropic
```
如果你看到如下 Anthropic 错误：
如果你看到类似这样的 Anthropic 错误：
```
This credential is only authorized for use with Claude Code and cannot be used for other API requests.
```
……请改用 Anthropic API 密钥。
…请改用 Anthropic API 密钥。
手动输入令牌（适用于任何提供商；写入 `auth-profiles.json` 并更新配置）：
手动令牌输入（任何提供商；写入 `auth-profiles.json` + 更新配置）：
```bash
openclaw models auth paste-token --provider anthropic
openclaw models auth paste-token --provider openrouter
```
适用于自动化的检查（过期/缺失时退出码为 `1`，即将过期时为 `2`）：
自动化友好检查（过期/缺失时退出 `1`，即将过期时退出 `2`）：
```bash
openclaw models status --check
```
可选的运维脚本（systemd/Termux）文档参见：[/automation/auth-monitoring](/automation/auth-monitoring)
可选的运维脚本（systemd/Termux）在此处记录：[/automation/auth-monitoring](/automation/auth-monitoring)
> `claude setup-token` 需要交互式 TTY。
@@ -102,17 +102,17 @@ openclaw models status
openclaw doctor
```
## 控制使用哪个凭据
## 控制使用哪个凭证
### 按会话（聊天命令）
### 每会话（聊天命令）
使用 `/model <alias-or-id>@<profileId>` 为当前会话指定特定的提供商凭据（示例配置 ID：`anthropic:default`、`anthropic:work`）。
使用 `/model <alias-or-id>@<profileId>` 为当前会话固定特定的提供商凭证（示例配置文件 ID：`anthropic:default`、`anthropic:work`）。
使用 `/model`（或 `/model list`）打开紧凑选择器；使用 `/model status` 查看完整视图（候选项 + 下一个认证配置，以及配置的提供商端点详情）。
使用 `/model`（或 `/model list`）获取紧凑的选择器；使用 `/model status` 获取完整视图（候选项 + 下一个认证配置文件，以及配置时的提供商端点详情）。
### 按智能体（CLI 覆盖）
### 每智能体（CLI 覆盖）
为智能体设置显式的认证配置顺序覆盖（存储在该智能体的 `auth-profiles.json` 中）：
为智能体设置显式的认证配置文件顺序覆盖（存储在该智能体的 `auth-profiles.json` 中）：
```bash
openclaw models auth order get --provider anthropic
@@ -120,13 +120,13 @@ openclaw models auth order set --provider anthropic anthropic:default
openclaw models auth order clear --provider anthropic
```
使用 `--agent <id>` 指定特定智能体；省略则使用已配置的默认智能体。
使用 `--agent <id>` 指定特定智能体；省略它则使用配置的默认智能体。
## 故障排除
### "No credentials found"
如果 Anthropic 令牌配置缺失，请在 **Gateway网关主机**上运行 `claude setup-token`，然后重新检查：
如果 Anthropic 令牌配置文件缺失，在 **Gateway 网关主机**上运行 `claude setup-token`，然后重新检查：
```bash
openclaw models status
@@ -134,7 +134,7 @@ openclaw models status
### 令牌即将过期/已过期
运行 `openclaw models status` 确认哪个配置即将过期。如果配置缺失，请重新运行 `claude setup-token` 并再次粘贴令牌。
运行 `openclaw models status` 确认哪个配置文件即将过期。如果配置文件缺失，重新运行 `claude setup-token` 并再次粘贴令牌。
## 要求

50
docs/zh-CN/gateway/background-process.md
View File

@@ -2,82 +2,82 @@
read_when:
- 添加或修改后台 exec 行为
- 调试长时间运行的 exec 任务
summary: 后台 exec 执行与进程管理
title: 后台 Exec 与 Process 工具
summary: 后台 exec 执行和进程管理
title: 后台 Exec 和 Process 工具
x-i18n:
generated_at: "2026-02-01T20:25:21Z"
generated_at: "2026-02-03T10:05:51Z"
model: claude-opus-4-5
provider: pi
source_hash: e11a7d74a75000d6882f703693c2c49a2ecd3e730b6ec2b475ac402abde9e465
source_path: gateway/background-process.md
workflow: 14
workflow: 15
---
# 后台 Exec + Process 工具
OpenClaw 通过 `exec` 工具运行 shell 命令，并将长时间运行的任务保存在内存中。`process` 工具用于管理这些后台会话。
OpenClaw 通过 `exec` 工具运行 shell 命令，并将长时间运行的任务保存在内存中。`process` 工具管理这些后台会话。
## exec 工具
关键参数：
- `command`（必填）
- `yieldMs`（默认 10000）：超过此延迟后自动转为后台运行
- `background`（布尔值）：立即转入后台
- `timeout`（秒，默认 1800）：超时后终止进程
- `elevated`（布尔值）：如果提权模式已启用/允许，则在宿主机上运行
- `yieldMs`（默认 10000）：在此延迟后自动转为后台运行
- `background`（布尔值）：立即转为后台运行
- `timeout`（秒，默认 1800）：在此超时后终止进程
- `elevated`（布尔值）：如果启用/允许提权模式，则在宿主机上运行
- 需要真实 TTY？设置 `pty: true`。
- `workdir`、`env`
行为：
- 前台运行直接返回输出。
- 转入后台时（显式指定或超时触发），工具返回 `status: "running"` + `sessionId` 以及末尾的少量输出。
- 当转为后台运行（显式或超时）时，工具返回 `status: "running"` + `sessionId` 和一小段尾部输出。
- 输出保存在内存中，直到会话被轮询或清除。
- 如果 `process` 工具被禁用，`exec` 将同步运行并忽略 `yieldMs`/`background`。
## 子进程桥接
在 exec/process 工具之外启动长时间运行的子进程时（例如 CLI 重启或 Gateway网关辅助进程），请挂载子进程桥接助手，以便终止信号能被正确转发，并在退出/出错时分离监听器。这可以避免在 systemd 上产生孤儿进程，并保持跨平台的关闭行为一致性。
当在 exec/process 工具之外生成长时间运行的子进程时（例如 CLI 重新生成或 Gateway 网关辅助程序），请附加子进程桥接辅助程序，以便终止信号被转发，监听器在退出/错误时被分离。这可以避免在 systemd 上产生孤立进程，并保持跨平台的关闭行为一致。
环境变量覆盖：
- `PI_BASH_YIELD_MS`：默认 yield 时间（毫秒）
- `PI_BASH_MAX_OUTPUT_CHARS`：内存输出上限（字符数）
- `OPENCLAW_BASH_PENDING_MAX_OUTPUT_CHARS`：每个流的待处理 stdout/stderr 上限（字符数）
- `PI_BASH_JOB_TTL_MS`：已完成会话的 TTL（毫秒，限制在 1 分钟到 3 小时之间）
- `PI_BASH_MAX_OUTPUT_CHARS`：内存输出上限（字符）
- `OPENCLAW_BASH_PENDING_MAX_OUTPUT_CHARS`：每个流的待处理 stdout/stderr 上限（字符）
- `PI_BASH_JOB_TTL_MS`：已完成会话的 TTL（毫秒，限制在 1 分钟至 3 小时之间）
配置（推荐方式）：
配置（推荐）：
- `tools.exec.backgroundMs`（默认 10000）
- `tools.exec.timeoutSec`（默认 1800）
- `tools.exec.cleanupMs`（默认 1800000）
- `tools.exec.notifyOnExit`（默认 true）：后台 exec 退出时，加入系统事件队列并请求心跳。
- `tools.exec.notifyOnExit`（默认 true）：当后台 exec 退出时，将系统事件加入队列并请求心跳。
## process 工具
操作：
- `list`：列出正在运行和已完成的会话
- `list`：正在运行和已完成的会话
- `poll`：获取会话的新输出（同时报告退出状态）
- `log`：读取聚合输出（支持 `offset` + `limit`）
- `write`：发送 stdin（`data`，可选 `eof`）
- `kill`：终止后台会话
- `clear`：从内存中移除已完成的会话
- `remove`：如果正在运行则终止，如果已完成则清除
- `remove`：如果正在运行则终止，否则清除已完成的会话
注意事项：
- 只有后台会话会被列出/保留在内存中。
- 进程重启后会话会丢失（无磁盘持久化）。
- 会话日志仅在你运行 `process poll/log` 且工具结果被记录时，才会保存到聊天历史中。
- `process` 的作用域为单个智能体；它只能看到该智能体启动的会话。
- `process list` 包含一个派生的 `name`（命令动词 + 目标），方便快速浏览。
- `process log` 使用基于行的 `offset`/`limit`（省略 `offset` 可获取最后 N 行）。
- 只有后台会话会在内存中列出/保留。
- 会话在进程重启时会丢失（无磁盘持久化）。
- 会话日志只有在你运行 `process poll/log` 且工具结果被记录时才会保存到聊天历史。
- `process` 按智能体隔离；它只能看到该智能体启动的会话。
- `process list` 包含派生的 `name`（命令动词 + 目标）以便快速浏览。
- `process log` 使用基于行的 `offset`/`limit`（省略 `offset` 以获取最后 N 行）。
## 示例
运行一个长任务，稍后轮询：
运行长时间任务并稍后轮询：
```json
{ "tool": "exec", "command": "sleep 5 && echo done", "yieldMs": 1000 }

124
docs/zh-CN/gateway/bonjour.md
View File

@@ -1,52 +1,59 @@
---
read_when:
- 在 macOS/iOS 上调试 Bonjour 发现问题
- 更改 mDNS 服务类型、TXT 记录或发现相关的用户体验
summary: Bonjour/mDNS 发现 + 调试（Gateway网关信标、客户端及常见故障模式）
title: Bonjour 发现
- 在 macOS/iOS 上调试 Bonjour 设备发现问题时
- 更改 mDNS 服务类型、TXT 记录或设备发现用户体验时
summary: Bonjour/mDNS 设备发现 + 调试（Gateway 网关信标、客户端和常见故障模式）
title: Bonjour 设备发现
x-i18n:
generated_at: "2026-02-01T20:25:34Z"
generated_at: "2026-02-03T07:47:48Z"
model: claude-opus-4-5
provider: pi
source_hash: 47569da55f0c0523bd5ff05275dc95ccb52f75638193cfbdb4eaaa162aadf08c
source_path: gateway/bonjour.md
workflow: 14
workflow: 15
---
# Bonjour / mDNS 发现
# Bonjour / mDNS 设备发现
OpenClaw 使用 Bonjour（mDNS / DNS‑SD）作为**仅限局域网的便捷方式**来发现活跃的 Gateway网关（WebSocket 端点）。这是尽力而为的机制，**不能**替代 SSH 或基于 Tailnet 的连接。
OpenClaw 使用 Bonjour（mDNS / DNS‑SD）作为**仅限局域网的便捷方式**来发现
活跃的 Gateway 网关（WebSocket 端点）。这是尽力而为的，**不能**替代 SSH 或
基于 Tailnet 的连接。
## 通过 Tailscale 实现广域 Bonjour（单播 DNS‑SD）
## 通过 Tailscale 的广域 Bonjour（单播 DNS‑SD）
如果节点和 Gateway网关处于不同网络，组播 mDNS 无法跨越网络边界。你可以通过切换到基于 Tailscale 的**单播 DNS‑SD**（"广域 Bonjour"）来保持相同的发现体验。
如果节点和 Gateway 网关在不同的网络上，多播 mDNS 无法跨越
边界。你可以通过切换到基于 Tailscale 的**单播 DNS‑SD**
（"广域 Bonjour"）来保持相同的设备发现用户体验。
概要步骤：
1. 在 Gateway网关主机上运行 DNS 服务器（可通过 Tailnet 访问）。
2. 在专用区域下为 `_openclaw-gw._tcp` 发布 DNS‑SD 记录（示例：`openclaw.internal.`）。
3. 配置 Tailscale **分割 DNS**，使你选择的域名通过该 DNS 服务器为客户端（包括 iOS）解析。
1. 在 Gateway 网关主机上运行 DNS 服务器（可通过 Tailnet 访问）。
2. 在专用区域下发布 `_openclaw-gw._tcp` 的 DNS‑SD 记录
（示例：`openclaw.internal.`）。
3. 配置 Tailscale **分割 DNS**，使你选择的域名通过该
DNS 服务器为客户端（包括 iOS）解析。
OpenClaw 支持任意发现域名；`openclaw.internal.` 仅为示例。iOS/Android 节点会同时浏览 `local.` 和你配置的广域域名。
OpenClaw 支持任何发现域名；`openclaw.internal.` 只是一个示例。
iOS/Android 节点同时浏览 `local.` 和你配置的广域域名。
### Gateway网关配置（推荐）
### Gateway 网关配置（推荐）
```json5
{
gateway: { bind: "tailnet" }, // 仅限 tailnet（推荐）
gateway: { bind: "tailnet" }, // 仅 tailnet（推荐）
discovery: { wideArea: { enabled: true } }, // 启用广域 DNS-SD 发布
}
```
### 一次性 DNS 服务器设置（Gateway网关主机）
### 一次性 DNS 服务器设置（Gateway 网关主机）
```bash
openclaw dns setup --apply
```
此命令会安装 CoreDNS 并将其配置为：
这会安装 CoreDNS 并配置它：
- 仅在 Gateway网关的 Tailscale 接口上监听 53 端口
- 仅在 Gateway 网关的 Tailscale 接口上监听 53 端口
- 从 `~/.openclaw/dns/<domain>.db` 提供你选择的域名服务（示例：`openclaw.internal.`）
从 Tailnet 连接的机器上验证：
@@ -60,47 +67,49 @@ dig @<TAILNET_IPV4> -p 53 _openclaw-gw._tcp.openclaw.internal PTR +short
在 Tailscale 管理控制台中：
- 添加指向 Gateway网关 Tailnet IP 的名称服务器（UDP/TCP 53）。
- 添加指向 Gateway 网关 Tailnet IP 的名称服务器（UDP/TCP 53）。
- 添加分割 DNS，使你的发现域名使用该名称服务器。
客户端接受 Tailnet DNS 后，iOS 节点即可在你的发现域名中浏览 `_openclaw-gw._tcp`，无需组播。
一旦客户端接受 Tailnet DNS，iOS 节点就可以在
你的发现域名中浏览 `_openclaw-gw._tcp`，无需多播。
### Gateway网关监听器安全（推荐）
### Gateway 网关监听器安全（推荐）
Gateway网关 WS 端口（默认 `18789`）默认绑定到 local loopback。若需局域网/Tailnet 访问，请显式绑定并保持认证启用。
Gateway 网关 WS 端口（默认 `18789`）默认绑定到 loopback。对于局域网/Tailnet
访问，请明确绑定并保持认证启用。
对于仅限 Tailnet 的设置：
对于仅 Tailnet 的设置：
- 在 `~/.openclaw/openclaw.json` 中设置 `gateway.bind: "tailnet"`。
- 重启 Gateway网关（或重启 macOS 菜单栏应用）。
- 重启 Gateway 网关（或重启 macOS 菜单栏应用）。
## 广播方
## 什么在广播
只有 Gateway网关广播 `_openclaw-gw._tcp`。
只有 Gateway 网关广播 `_openclaw-gw._tcp`。
## 服务类型
- `_openclaw-gw._tcp` — Gateway网关传输信标（供 macOS/iOS/Android 节点使用）。
- `_openclaw-gw._tcp` — Gateway 网关传输信标（被 macOS/iOS/Android 节点使用）。
## TXT 键（非机密提示）
Gateway网关广播小型非机密提示以方便 UI 流程：
Gateway 网关广播小型非机密提示以方便 UI 流程：
- `role=gateway`
- `displayName=<友好名称>`
- `lanHost=<主机名>.local`
- `gatewayPort=<端口>`（Gateway网关 WS + HTTP）
- `gatewayTls=1`（仅在启用 TLS 时）
- `gatewayTlsSha256=<sha256>`（仅在启用 TLS 且指纹可用时）
- `canvasPort=<端口>`（仅在启用 canvas 主机时；默认 `18793`）
- `sshPort=<端口>`（未覆盖时默认为 22）
- `lanHost=<hostname>.local`
- `gatewayPort=<port>`（Gateway 网关 WS + HTTP）
- `gatewayTls=1`（仅当 TLS 启用时）
- `gatewayTlsSha256=<sha256>`（仅当 TLS 启用且指纹可用时）
- `canvasPort=<port>`（仅当画布主机启用时；默认 `18793`）
- `sshPort=<port>`（未覆盖时默认为 22）
- `transport=gateway`
- `cliPath=<路径>`（可选；可运行的 `openclaw` 入口点的绝对路径）
- `tailnetDns=<magicdns>`（可选提示，当 Tailnet 可用时）
- `cliPath=<path>`（可选；可运行的 `openclaw` 入口点的绝对路径）
- `tailnetDns=<magicdns>`（当 Tailnet 可用时的可选提示）
## 在 macOS 上调试
实用的内置工具：
有用的内置工具：
- 浏览实例：
```bash
@@ -111,11 +120,13 @@ Gateway网关广播小型非机密提示以方便 UI 流程：
dns-sd -L "<instance>" _openclaw-gw._tcp local.
```
如果浏览正常但解析失败，通常是遇到了局域网策略或 mDNS 解析器问题。
如果浏览有效但解析失败，你通常遇到的是局域网策略或
mDNS 解析器问题。
## 在 Gateway网关日志中调试
## 在 Gateway 网关日志中调试
Gateway网关会写入滚动日志文件（启动时输出为 `gateway log file: ...`）。查找 `bonjour:` 行，特别是：
Gateway 网关会写入滚动日志文件（启动时打印为
`gateway log file: ...`）。查找 `bonjour:` 行，特别是：
- `bonjour: advertise failed ...`
- `bonjour: ... name conflict resolved` / `hostname conflict resolved`
@@ -125,36 +136,39 @@ Gateway网关会写入滚动日志文件（启动时输出为 `gateway log file:
iOS 节点使用 `NWBrowser` 来发现 `_openclaw-gw._tcp`。
要获取日志：
要捕获日志：
- 设置 → Gateway网关 → 高级 → **发现调试日志**
- 设置 → Gateway网关 → 高级 → **发现日志** → 复现问题 → **复制**
- 设置 → Gateway 网关 → 高级 → **Discovery Debug Logs**
- 设置 → Gateway 网关 → 高级 → **Discovery Logs** → 复现 → **Copy**
日志包含浏览器状态转换和结果集变化。
日志包括浏览器状态转换和结果集变化。
## 常见故障模式
- **Bonjour 无法跨网络**：请使用 Tailnet 或 SSH。
- **组播被阻止**：某些 Wi‑Fi 网络会禁用 mDNS。
- **睡眠 / 接口变动**：macOS 可能会临时丢失 mDNS 结果；请重试。
- **浏览正常但解析失败**：保持机器名称简单（避免使用表情符号或标点符号），然后重启 Gateway网关。服务实例名称来源于主机名，因此过于复杂的名称可能会导致某些解析器混淆。
- **Bonjour 不能跨网络**：使用 Tailnet 或 SSH。
- **多播被阻止**：某些 Wi‑Fi 网络禁用 mDNS。
- **休眠 / 接口变动**：macOS 可能暂时丢弃 mDNS 结果；重试。
- **浏览有效但解析失败**：保持机器名称简单（避免表情符号或
标点符号），然后重启 Gateway 网关。服务实例名称源自
主机名，因此过于复杂的名称可能会混淆某些解析器。
## 转义的实例名称（`\032`）
Bonjour/DNS‑SD 经常将服务实例名称中的字节转义为十进制 `\DDD` 序列（例如空格变为 `\032`）。
Bonjour/DNS‑SD 经常将服务实例名称中的字节转义为十进制 `\DDD`
序列（例如空格变成 `\032`）。
- 这在协议层面是正常的。
- UI 应进行解码后再显示（iOS 使用 `BonjourEscapes.decode`）。
- 这在协议级别是正常的。
- UI 应该解码以进行显示（iOS 使用 `BonjourEscapes.decode`）。
## 禁用 / 配置
- `OPENCLAW_DISABLE_BONJOUR=1` 禁用广播（旧版：`OPENCLAW_DISABLE_BONJOUR`）。
- `~/.openclaw/openclaw.json` 中的 `gateway.bind` 控制 Gateway网关绑定模式。
- `~/.openclaw/openclaw.json` 中的 `gateway.bind` 控制 Gateway 网关绑定模式。
- `OPENCLAW_SSH_PORT` 覆盖 TXT 中广播的 SSH 端口（旧版：`OPENCLAW_SSH_PORT`）。
- `OPENCLAW_TAILNET_DNS` 在 TXT 中发布 MagicDNS 提示（旧版：`OPENCLAW_TAILNET_DNS`）。
- `OPENCLAW_CLI_PATH` 覆盖广播的 CLI 路径（旧版：`OPENCLAW_CLI_PATH`）。
## 相关文档
- 发现策略和传输选择：[发现](/gateway/discovery)
- 节点配对 + 审批：[Gateway网关配对](/gateway/pairing)
- 设备发现策略和传输选择：[设备发现](/gateway/discovery)
- 节点配对 + 批准：[Gateway 网关配对](/gateway/pairing)

74
docs/zh-CN/gateway/bridge-protocol.md
View File

@@ -1,84 +1,86 @@
---
read_when:
- 构建或调试节点客户端（iOS/Android/macOS 节点模式）
- 排查配对或桥接认证故障
- 审计 Gateway网关暴露的节点接口
summary: 桥接协议（旧版节点）：TCP JSONL、配对、作用域 RPC
title: 桥接协议
- 调查配对或 bridge 认证失败
- 审计 Gateway 网关暴露的节点接口
summary: Bridge 协议（旧版节点）：TCP JSONL、配对、作用域 RPC
title: Bridge 协议
x-i18n:
generated_at: "2026-02-01T20:25:34Z"
generated_at: "2026-02-03T07:47:42Z"
model: claude-opus-4-5
provider: pi
source_hash: 789bcf3cbc6841fc293e054b919e63d661b3cc4cd205b2094289f00800127fe2
source_path: gateway/bridge-protocol.md
workflow: 14
workflow: 15
---
# 桥接协议（旧版节点传输）
# Bridge 协议（旧版节点传输）
桥接协议是一种**旧版**节点传输方式（TCP JSONL）。新的节点客户端应改用统一的 Gateway网关 WebSocket 协议。
Bridge 协议是一个**旧版**节点传输（TCP JSONL）。新的节点客户端应该使用统一的 Gateway 网关 WebSocket 协议。
如果你正在构建操作端或节点客户端，请使用 [Gateway网关协议](/gateway/protocol)。
如果你正在构建操作者或节点客户端，请使用 [Gateway 网关协议](/gateway/protocol)。
**注意：** 当前版本的 OpenClaw 不再附带 TCP 桥接监听器；本文档仅作历史参考保留。旧版 `bridge.*` 配置键已不再属于配置模式的一部分。
**注意：** 当前的 OpenClaw 构建不再包含 TCP bridge 监听器；本文档仅作历史参考保留。
旧版 `bridge.*` 配置键不再是配置模式的一部分。
## 为什么有两种协议
## 为什么我们有两种协议
- **安全边界**：桥接仅暴露一个小型允许列表，而非完整的 Gateway网关 API 接口。
- **配对与节点身份**：节点准入由 Gateway网关管理，并与每个节点的令牌绑定。
- **发现体验**：节点可以通过局域网上的 Bonjour 发现 Gateway网关，或通过 tailnet 直接连接。
- **local loopback WS**：完整的 WS 控制平面保持在本地，除非通过 SSH 隧道转发。
- **安全边界**：bridge 暴露一个小的允许列表，而不是完整的 Gateway 网关 API 接口。
- **配对 + 节点身份**：节点准入由 Gateway 网关管理，并与每节点令牌绑定。
- **设备发现用户体验**：节点可以通过局域网上的 Bonjour 发现 Gateway 网关，或通过 tailnet 直接连接。
- **Loopback WS**：完整的 WS 控制平面保持本地，除非通过 SSH 隧道。
## 传输方式
## 传输
- TCP，每行一个 JSON 对象（JSONL）。
- 可选 TLS（当 `bridge.tls.enabled` 为 true 时）。
- 旧版默认监听端口为 `18790`（当前版本不再启动 TCP 桥接）。
- 旧版默认监听端口为 `18790`（当前构建不启动 TCP bridge）。
启用 TLS 时，发现 TXT 记录会包含 `bridgeTls=1` 以及 `bridgeTlsSha256`，以便节点可以固定证书。
当 TLS 启用时，设备发现 TXT 记录包含 `bridgeTls=1` 加上 `bridgeTlsSha256`，以便节点可以固定证书。
## 握手与配对
## 握手 + 配对
1. 客户端发送 `hello`，附带节点元数据和令牌（如果已配对）。
2. 如果未配对，Gateway网关回复 `error`（`NOT_PAIRED`/`UNAUTHORIZED`）。
1. 客户端发送带有节点元数据 + 令牌（如果已配对）的 `hello`。
2. 如果未配对，Gateway 网关回复 `error`（`NOT_PAIRED`/`UNAUTHORIZED`）。
3. 客户端发送 `pair-request`。
4. Gateway网关等待审批，然后发送 `pair-ok` 和 `hello-ok`。
4. Gateway 网关等待批准，然后发送 `pair-ok` 和 `hello-ok`。
`hello-ok` 返回 `serverName`，可能包含 `canvasHostUrl`。
## 帧类型
## 帧
客户端 → Gateway网关：
客户端 → Gateway 网关：
- `req` / `res`：作用域 Gateway网关 RPC（聊天、会话、配置、健康检查、语音唤醒、skills.bins）
- `event`：节点信号（语音转录、智能体请求、聊天订阅、执行生命周期）
- `req` / `res`：作用域 Gateway 网关 RPC（chat、sessions、config、health、voicewake、skills.bins）
- `event`：节点信号（语音转录、智能体请求、聊天订阅、exec 生命周期）
Gateway网关 → 客户端：
Gateway 网关 → 客户端：
- `invoke` / `invoke-res`：节点命令（`canvas.*`、`camera.*`、`screen.record`、`location.get`、`sms.send`）
- `event`：已订阅会话的聊天更新
- `ping` / `pong`：保活
旧版允许列表强制执行逻辑位于 `src/gateway/server-bridge.ts`（已移除）。
旧版允许列表强制执行位于 `src/gateway/server-bridge.ts`（已移除）。
## 执行生命周期事件
## Exec 生命周期事件
节点可以发出 `exec.finished` 或 `exec.denied` 事件以展示 system.run 活动。这些会映射为 Gateway网关中的系统事件。（旧版节点可能仍会发出 `exec.started`。）
节点可以发出 `exec.finished` 或 `exec.denied` 事件来表面化 system.run 活动。
这些被映射到 Gateway 网关中的系统事件。（旧版节点可能仍会发出 `exec.started`。）
有效载荷字段（除特别说明外均为可选）：
Payload 字段（除非注明，否则都是可选的）：
- `sessionKey`（必填）：接收系统事件的智能体会话。
- `runId`：用于分组的唯一执行 ID。
- `sessionKey`（必需）：接收系统事件的智能体会话。
- `runId`：用于分组的唯一 exec id。
- `command`：原始或格式化的命令字符串。
- `exitCode`、`timedOut`、`success`、`output`：完成详情（仅限 finished）。
- `reason`：拒绝原因（仅限 denied）。
## Tailnet 使用
- 将桥接绑定到 tailnet IP：在 `~/.openclaw/openclaw.json` 中设置 `bridge.bind: "tailnet"`。
- 将 bridge 绑定到 tailnet IP：在 `~/.openclaw/openclaw.json` 中设置 `bridge.bind: "tailnet"`。
- 客户端通过 MagicDNS 名称或 tailnet IP 连接。
- Bonjour **不能**跨网络；需要时请使用手动指定主机/端口或广域 DNS-SD。
- Bonjour **不**跨网络；需要时使用手动主机/端口或广域 DNS‑SD。
## 版本控制
桥接目前为**隐式 v1**（无最小/最大版本协商）。预期保持向后兼容；在引入任何破坏性变更之前应添加桥接协议版本字段。
Bridge 目前是**隐式 v1**（无最小/最大协商）。预期向后兼容；在任何破坏性变更之前添加 bridge 协议版本字段。

93
docs/zh-CN/gateway/cli-backends.md
View File

@@ -1,45 +1,45 @@
---
read_when:
- 你需要在 API 提供商故障时使用可靠的回退方案
- 你正在运行 Claude Code CLI 或其他本地 AI CLI，并希望复用它们
- 你需要一个纯文本、无工具的路径，同时仍支持会话和图片
- 你想要一个在 API 提供商失败时的可靠回退
- 你正在运行 Claude Code CLI 或其他本地 AI CLI 并想要复用它们
- 你需要一个纯文本、无工具的路径，但仍支持会话和图像
summary: CLI 后端：通过本地 AI CLI 实现纯文本回退
title: CLI 后端
x-i18n:
generated_at: "2026-02-01T20:25:48Z"
generated_at: "2026-02-03T07:47:52Z"
model: claude-opus-4-5
provider: pi
source_hash: 56a96e83b16a4f6443cbf4a9da7a660c41a5b178af5e13f35352c9d72e1b08dd
source_path: gateway/cli-backends.md
workflow: 14
workflow: 15
---
# CLI 后端（回退运行时）
OpenClaw 可以将**本地 AI CLI** 作为**纯文本回退**运行，适用于 API 提供商宕机、被限流或暂时异常的情况。该方案设计上有意保持保守：
当 API 提供商宕机、被限流或暂时异常时，OpenClaw 可以运行**本地 AI CLI** 作为**纯文本回退**。这是有意保守的设计：
- **工具已禁用**（不进行工具调用）。
- **工具被禁用**（无工具调用）。
- **文本输入 → 文本输出**（可靠）。
- **支持会话**（后续对话轮次保持连贯）。
- **可传递图片**（如果 CLI 接受图片路径）。
- **支持会话**（因此后续轮次保持连贯）。
- 如果 CLI 接受图像路径，**图像可以传递**。
这被设计为**安全兜底方案**，而非主要路径。当你希望在不依赖外部 API 的情况下获得"始终可用"的文本响应时，可以使用它。
这被设计为**安全网**而非主要路径。当你想要"始终有效"的文本响应而不依赖外部 API 时使用它。
## 新手快速入门
## 新手友好快速开始
你可以**无需任何配置**直接使用 Claude Code CLI（OpenClaw 内置了默认配置）：
你可以**无需任何配置**使用 Claude Code CLI（OpenClaw 自带内置默认值）：
```bash
openclaw agent --message "hi" --model claude-cli/opus-4.5
```
Codex CLI 同样开箱即用：
Codex CLI 也可以开箱即用：
```bash
openclaw agent --message "hi" --model codex-cli/gpt-5.2-codex
```
如果你的 Gateway网关在 launchd/systemd 下运行且 PATH 较精简，只需添加命令路径：
如果你的 Gateway 网关在 launchd/systemd 下运行且 PATH 很精简，只需添加命令路径：
```json5
{
@@ -55,11 +55,11 @@ openclaw agent --message "hi" --model codex-cli/gpt-5.2-codex
}
```
就这样。除了 CLI 本身之外，无需密钥，无需额外的认证配置。
就这样。除了 CLI 本身外，不需要密钥，不需要额外的认证配置。
## 用作回退方案
## 作为回退使用
将 CLI 后端添加到回退列表中，这样它只在主模型失败时运行：
将 CLI 后端添加到你的回退列表中，这样它只在主要模型失败时运行：
```json5
{
@@ -80,8 +80,8 @@ openclaw agent --message "hi" --model codex-cli/gpt-5.2-codex
注意事项：
- 如果使用了 `agents.defaults.models`（白名单），必须包含 `claude-cli/...`。
- 如果主提供商失败（认证、限流、超时），OpenClaw 将尝试使用 CLI 后端。
- 如果你使用 `agents.defaults.models`（允许列表），必须包含 `claude-cli/...`。
- 如果主要提供商失败（认证、限流、超时），OpenClaw 将接着尝试 CLI 后端。
## 配置概览
@@ -91,8 +91,7 @@ openclaw agent --message "hi" --model codex-cli/gpt-5.2-codex
agents.defaults.cliBackends
```
每个条目以**提供商 ID** 为键（例如 `claude-cli`、`my-cli`）。
提供商 ID 成为模型引用的左半部分：
每个条目以**提供商 ID**（例如 `claude-cli`、`my-cli`）为键。提供商 ID 成为你的模型引用的左侧部分：
```
<provider>/<model>
@@ -135,47 +134,47 @@ agents.defaults.cliBackends
## 工作原理
1. **根据提供商前缀选择后端**（`claude-cli/...`）。
2. **构建系统提示词**，使用相同的 OpenClaw 提示词 + 工作区上下文。
3. **执行 CLI**，附带会话 ID（如支持），以保持历史记录一致。
4. **解析输出**（JSON 或纯文本），返回最终文本。
5. **持久化会话 ID**（按后端分别存储），后续对话复用同一 CLI 会话。
1. **选择后端**基于提供商前缀（`claude-cli/...`）。
2. **构建系统提示**使用相同的 OpenClaw 提示 + 工作区上下文。
3. **执行 CLI**并带有会话 ID（如果支持），使历史记录保持一致。
4. **解析输出**（JSON 或纯文本）并返回最终文本。
5. **持久化会话 ID**按后端，使后续请求复用相同的 CLI 会话。
## 会话
- 如果 CLI 支持会话，设置 `sessionArg`（例如 `--session-id`），或设置 `sessionArgs`（占位符 `{sessionId}`）以将 ID 插入多个标志中。
- 如果 CLI 使用带有不同标志的**恢复子命令**，设置 `resumeArgs`（恢复时替换 `args`），并可选设置 `resumeOutput`（用于非 JSON 恢复）。
- 如果 CLI 支持会话，设置 `sessionArg`（例如 `--session-id`）或 `sessionArgs`（占位符 `{sessionId}`）当 ID 需要插入到多个标志中时。
- 如果 CLI 使用带有不同标志的**恢复子命令**，设置 `resumeArgs`（恢复时替换 `args`）以及可选的 `resumeOutput`（用于非 JSON 恢复）。
- `sessionMode`：
- `always`：始终发送会话 ID（如无存储则生成新 UUID）。
- `existing`：仅在之前已存储会话 ID 时才发送。
- `always`：始终发送会话 ID（如果没有存储则使用新 UUID）。
- `existing`：仅在之前存储了会话 ID 时才发送。
- `none`：从不发送会话 ID。
## 图片（透传）
## 图像（传递）
如果你的 CLI 接受图片路径，设置 `imageArg`：
如果你的 CLI 接受图像路径，设置 `imageArg`：
```json5
imageArg: "--image",
imageMode: "repeat"
```
OpenClaw 会将 base64 图片写入临时文件。如果设置了 `imageArg`，这些路径将作为 CLI 参数传递。如果未设置 `imageArg`，OpenClaw 会将文件路径追加到提示词中（路径注入），这对于能从纯文本路径自动加载本地文件的 CLI 已经足够（Claude Code CLI 的行为即是如此）。
OpenClaw 会将 base64 图像写入临时文件。如果设置了 `imageArg`，这些路径作为 CLI 参数传递。如果缺少 `imageArg`，OpenClaw 会将文件路径附加到提示中（路径注入），这对于从纯路径自动加载本地文件的 CLI 来说已经足够（Claude Code CLI 行为）。
## 输入 / 输出
- `output: "json"`（默认）尝试解析 JSON 并提取文本 + 会话 ID。
- `output: "jsonl"` 解析 JSONL 流（Codex CLI `--json`），提取最后一条智能体消息以及 `thread_id`（如存在）。
- `output: "text"` 将标准输出作为最终响应。
- `output: "jsonl"` 解析 JSONL 流（Codex CLI `--json`）并提取最后一条智能体消息以及存在时的 `thread_id`。
- `output: "text"` 将 stdout 视为最终响应。
输入模式：
- `input: "arg"`（默认）将提示词作为最后一个 CLI 参数传递。
- `input: "stdin"` 通过标准输入发送提示词。
- 如果提示词很长且设置了 `maxPromptArgChars`，将使用标准输入。
- `input: "arg"`（默认）将提示作为最后一个 CLI 参数传递。
- `input: "stdin"` 通过 stdin 发送提示。
- 如果提示很长且设置了 `maxPromptArgChars`，则使用 stdin。
## 默认值（内置）
OpenClaw 为 `claude-cli` 内置了默认配置：
OpenClaw 自带 `claude-cli` 的默认值：
- `command: "claude"`
- `args: ["-p", "--output-format", "json", "--dangerously-skip-permissions"]`
@@ -186,7 +185,7 @@ OpenClaw 为 `claude-cli` 内置了默认配置：
- `systemPromptWhen: "first"`
- `sessionMode: "always"`
OpenClaw 还为 `codex-cli` 内置了默认配置：
OpenClaw 也自带 `codex-cli` 的默认值：
- `command: "codex"`
- `args: ["exec","--json","--color","never","--sandbox","read-only","--skip-git-repo-check"]`
@@ -197,18 +196,18 @@ OpenClaw 还为 `codex-cli` 内置了默认配置：
- `imageArg: "--image"`
- `sessionMode: "existing"`
仅在需要时覆盖（常见情况：绝对 `command` 路径）。
仅在需要时覆盖（常见：绝对 `command` 路径）。
## 限制
- **无 OpenClaw 工具**（CLI 后端不会接收工具调用）。某些 CLI 可能仍会运行自身的智能体工具。
- **无流式传输**（CLI 输出收集完毕后一次性返回）。
- **无 OpenClaw 工具**（CLI 后端永远不会收到工具调用）。某些 CLI 可能仍会运行它们自己的智能体工具。
- **无流式传输**（CLI 输出被收集后返回）。
- **结构化输出**取决于 CLI 的 JSON 格式。
- **Codex CLI 会话**通过文本输出恢复（非 JSONL），其结构化程度不如初始的 `--json` 运行。OpenClaw 会话仍正常工作。
- **Codex CLI 会话**通过文本输出恢复（无 JSONL），这比初始的 `--json` 运行结构化程度低。OpenClaw 会话仍然正常工作。
## 故障排除
- **找不到 CLI**：将 `command` 设置为完整路径。
- **模型名称错误**：使用 `modelAliases` 将 `provider/model` 映射为 CLI 模型名。
- **无会话连续性**：确保已设置 `sessionArg` 且 `sessionMode` 不是 `none`（Codex CLI 目前无法以 JSON 输出恢复会话）。
- **图片被忽略**：设置 `imageArg`（并确认 CLI 支持文件路径）。
- **模型名称错误**：使用 `modelAliases` 将 `provider/model` 映射到 CLI 模型。
- **无会话连续性**：确保设置了 `sessionArg` 且 `sessionMode` 不是 `none`（Codex CLI 目前无法使用 JSON 输出恢复）。
- **图像被忽略**：设置 `imageArg`（并验证 CLI 支持文件路径）。

42
docs/zh-CN/gateway/configuration-examples.md
View File

@@ -1,26 +1,26 @@
---
read_when:
- 学习如何配置 OpenClaw
- 查找配置示例
- 寻找配置示例
- 首次设置 OpenClaw
summary: 常见 OpenClaw 设置的符合 Schema 的配置示例
summary: 符合模式的常见 OpenClaw 设置配置示例
title: 配置示例
x-i18n:
generated_at: "2026-02-01T20:26:09Z"
generated_at: "2026-02-03T07:48:39Z"
model: claude-opus-4-5
provider: pi
source_hash: 00e9286722653f2748137d5bc641d528b160de16a58015ca7674a3a302f4b2c3
source_path: gateway/configuration-examples.md
workflow: 14
workflow: 15
---
# 配置示例
以下示例与当前配置 Schema 保持一致。如需完整参考和各字段说明，请参阅[配置](/gateway/configuration)。
以下示例与当前配置模式一致。有关详尽的参考和每个字段的说明，请参阅[配置](/gateway/configuration)。
## 快速开始
### 最简配置
### 绝对最小配置
```json5
{
@@ -29,7 +29,7 @@ x-i18n:
}
```
保存到 `~/.openclaw/openclaw.json`，即可从该号码私信机器人。
保存到 `~/.openclaw/openclaw.json`，你就可以从该号码私信机器人了。
### 推荐的入门配置
@@ -55,11 +55,11 @@ x-i18n:
## 扩展示例（主要选项）
> JSON5 允许使用注释和尾随逗号。普通 JSON 同样适用。
> JSON5 允许你使用注释和尾随逗号。普通 JSON 也可以使用。
```json5
{
// 环境变量 + shell
// 环境 + shell
env: {
OPENROUTER_API_KEY: "sk-or-...",
vars: {
@@ -71,7 +71,7 @@ x-i18n:
},
},
// 认证配置文件元数据（密钥存放在 auth-profiles.json 中）
// 认证配置文件元数据（密钥存储在 auth-profiles.json 中）
auth: {
profiles: {
"anthropic:me@example.com": { provider: "anthropic", mode: "oauth", email: "me@example.com" },
@@ -141,7 +141,7 @@ x-i18n:
maxBytes: 20971520,
models: [
{ provider: "openai", model: "gpt-4o-mini-transcribe" },
// 可选的 CLI 回退（Whisper 二进制文件）：
// 可选的 CLI 回退（Whisper 二进制）：
// { type: "cli", command: "whisper", args: ["--model", "base", "{{MediaPath}}"] }
],
timeoutSeconds: 120,
@@ -346,14 +346,14 @@ x-i18n:
},
},
// 定时任务
// Cron 作业
cron: {
enabled: true,
store: "~/.openclaw/cron/cron.json",
maxConcurrentRuns: 2,
},
// Webhook
// Webhooks
hooks: {
enabled: true,
path: "/hooks",
@@ -393,7 +393,7 @@ x-i18n:
},
},
// Gateway网关 + 网络
// Gateway 网关 + 网络
gateway: {
mode: "local",
port: 18789,
@@ -453,7 +453,7 @@ x-i18n:
}
```
### OAuth 加 API 密钥回退
### OAuth 带 API 密钥回退
```json5
{
@@ -522,7 +522,7 @@ x-i18n:
}
```
### 工作机器人（限制访问）
### 工作机器人（受限访问）
```json5
{
@@ -547,7 +547,7 @@ x-i18n:
}
```
### 仅使用本地模型
### 仅本地模型
```json5
{
@@ -581,7 +581,7 @@ x-i18n:
## 提示
- 如果设置了 `dmPolicy: "open"`，对应的 `allowFrom` 列表必须包含 `"*"`。
- 各提供商的 ID 格式不同（电话号码、用户 ID、频道 ID）。请查阅对应提供商的文档确认格式。
- 可稍后添加的可选部分：`web`、`browser`、`ui`、`discovery`、`canvasHost`、`talk`、`signal`、`imessage`。
- 更详细的设置说明请参阅[提供商](/channels/whatsapp)和[故障排除](/gateway/troubleshooting)。
- 如果你设置 `dmPolicy: "open"`，匹配的 `allowFrom` 列表必须包含 `"*"`。
- 提供商 ID 各不相同（电话号码、用户 ID、频道 ID）。使用提供商文档确认格式。
- 稍后添加的可选部分：`web`、`browser`、`ui`、`discovery`、`canvasHost`、`talk`、`signal`、`imessage`。
- 参阅[提供商](/channels/whatsapp)和[故障排除](/gateway/troubleshooting)了解更深入的设置说明。

150
docs/zh-CN/gateway/configuration.md
View File

@@ -30,11 +30,11 @@ OpenClaw 从 `~/.openclaw/openclaw.json` 读取可选的 **JSON5** 配置（支
## 严格配置验证
OpenClaw 只接受完全匹配 schema 的配置。
未知键、类型错误或无效值会导致 Gateway网关 **拒绝启动**以确保安全。
未知键、类型错误或无效值会导致 Gateway 网关 **拒绝启动**以确保安全。
验证失败时：
- Gateway网关不会启动。
- Gateway 网关不会启动。
- 只允许诊断命令（例如：`openclaw doctor`、`openclaw logs`、`openclaw health`、`openclaw status`、`openclaw service`、`openclaw help`）。
- 运行 `openclaw doctor` 查看具体问题。
- 运行 `openclaw doctor --fix`（或 `--yes`）应用迁移/修复。
@@ -43,7 +43,7 @@ Doctor 不会写入任何更改，除非你明确选择了 `--fix`/`--yes`。
## Schema + UI 提示
Gateway网关通过 `config.schema` 暴露配置的 JSON Schema 表示，供 UI 编辑器使用。
Gateway 网关通过 `config.schema` 暴露配置的 JSON Schema 表示，供 UI 编辑器使用。
控制台 UI 根据此 schema 渲染表单，并提供 **Raw JSON** 编辑器作为应急手段。
渠道插件和扩展可以为其配置注册 schema + UI 提示，因此渠道设置
@@ -53,8 +53,8 @@ Gateway网关通过 `config.schema` 暴露配置的 JSON Schema 表示，供 UI
## 应用 + 重启（RPC）
使用 `config.apply` 在一步中验证 + 写入完整配置并重启 Gateway网关。
它会写入重启哨兵文件，并在 Gateway网关恢复后 ping 最后活跃的会话。
使用 `config.apply` 在一步中验证 + 写入完整配置并重启 Gateway 网关。
它会写入重启哨兵文件，并在 Gateway 网关恢复后 ping 最后活跃的会话。
警告：`config.apply` 会替换**整个配置**。如果你只想更改部分键，
请使用 `config.patch` 或 `openclaw config set`。请备份 `~/.openclaw/openclaw.json`。
@@ -88,7 +88,7 @@ openclaw gateway call config.apply --params '{
- `null` 删除键
- 数组替换
与 `config.apply` 类似，它会验证、写入配置、存储重启哨兵，并调度
Gateway网关重启（当提供 `sessionKey` 时可选择唤醒）。
Gateway 网关重启（当提供 `sessionKey` 时可选择唤醒）。
参数：
@@ -294,7 +294,7 @@ OpenClaw 从父进程（shell、launchd/systemd、CI 等）读取环境变量。
}
```
参见 [/environment](/environment) 了解全部优先级和来源。
参见 [/environment](/environment) 了解优先级和来源详情。
### `env.shellEnv`（可选）
@@ -536,7 +536,7 @@ OpenClaw 在以下位置存储**每个智能体的**认证配置文件（OAuth +
### `channels.whatsapp.accounts`（多账号）
在一个 Gateway网关中运行多个 WhatsApp 账号：
在一个 Gateway 网关中运行多个 WhatsApp 账号：
```json5
{
@@ -734,7 +734,7 @@ OpenClaw 在以下位置存储**每个智能体的**认证配置文件（OAuth +
### 多智能体路由（`agents.list` + `bindings`）
在一个 Gateway网关中运行多个隔离的智能体（独立的工作区、`agentDir`、会话）。
在一个 Gateway 网关中运行多个隔离的智能体（独立的工作区、`agentDir`、会话）。
入站消息通过绑定路由到智能体。
- `agents.list[]`：每智能体覆盖。
@@ -749,21 +749,21 @@ OpenClaw 在以下位置存储**每个智能体的**认证配置文件（OAuth +
- 对象形式：`{ primary, fallbacks }`（fallbacks 覆盖 `agents.defaults.model.fallbacks`；`[]` 为该智能体禁用全局回退）
- `identity`：每智能体的名称/主题/表情（用于提及模式 + 确认反应）。
- `groupChat`：每智能体的提及门控（`mentionPatterns`）。
- `sandbox`：每智能体的沙盒配置（覆盖 `agents.defaults.sandbox`）。
- `sandbox`：每智能体的沙箱配置（覆盖 `agents.defaults.sandbox`）。
- `mode`：`"off"` | `"non-main"` | `"all"`
- `workspaceAccess`：`"none"` | `"ro"` | `"rw"`
- `scope`：`"session"` | `"agent"` | `"shared"`
- `workspaceRoot`：自定义沙盒工作区根目录
- `workspaceRoot`：自定义沙箱工作区根目录
- `docker`：每智能体 docker 覆盖（例如 `image`、`network`、`env`、`setupCommand`、限制；`scope: "shared"` 时忽略）
- `browser`：每智能体沙盒浏览器覆盖（`scope: "shared"` 时忽略）
- `prune`：每智能体沙盒清理覆盖（`scope: "shared"` 时忽略）
- `browser`：每智能体沙箱浏览器覆盖（`scope: "shared"` 时忽略）
- `prune`：每智能体沙箱清理覆盖（`scope: "shared"` 时忽略）
- `subagents`：每智能体子智能体默认值。
- `allowAgents`：允许从此智能体执行 `sessions_spawn` 的智能体 id 白名单（`["*"]` = 允许任何；默认：仅同一智能体）
- `tools`：每智能体工具限制（在沙盒工具策略之前应用）。
- `tools`：每智能体工具限制（在沙箱工具策略之前应用）。
- `profile`：基础工具配置文件（在 allow/deny 之前应用）
- `allow`：允许的工具名称数组
- `deny`：拒绝的工具名称数组（deny 优先）
- `agents.defaults`：共享的智能体默认值（模型、工作区、沙盒等）。
- `agents.defaults`：共享的智能体默认值（模型、工作区、沙箱等）。
- `bindings[]`：将入站消息路由到 `agentId`。
- `match.channel`（必需）
- `match.accountId`（可选；`*` = 任何账号；省略 = 默认账号）
@@ -783,15 +783,15 @@ OpenClaw 在以下位置存储**每个智能体的**认证配置文件（OAuth +
#### 每智能体访问配置（多智能体）
每个智能体可以携带自己的沙盒 + 工具策略。用于在一个 Gateway网关中混合访问级别：
每个智能体可以携带自己的沙箱 + 工具策略。用于在一个 Gateway 网关中混合访问级别：
- **完全访问**（个人智能体）
- **只读**工具 + 工作区
- **无文件系统访问**（仅消息/会话工具）
参见[多智能体沙盒与工具](/multi-agent-sandbox-tools)了解优先级和更多示例。
参见[多智能体沙箱与工具](/multi-agent-sandbox-tools)了解优先级和更多示例。
完全访问（无沙盒）：
完全访问（无沙箱）：
```json5
{
@@ -1011,7 +1011,7 @@ OpenClaw 在以下位置存储**每个智能体的**认证配置文件（OAuth +
### `web`（WhatsApp Web 渠道运行时）
WhatsApp 通过 Gateway网关的 Web 渠道（Baileys Web）运行。当存在已链接的会话时自动启动。
WhatsApp 通过 Gateway 网关的 Web 渠道（Baileys Web）运行。当存在已链接的会话时自动启动。
设置 `web.enabled: false` 使其默认关闭。
```json5
@@ -1066,7 +1066,7 @@ OpenClaw 仅在存在 `channels.telegram` 配置段时启动 Telegram。机器
historyLimit: 50, // 包含最近 N 条群消息作为上下文（0 禁用）
replyToMode: "first", // off | first | all
linkPreview: true, // 切换出站链接预览
streamMode: "partial", // off | partial | block（草稿流式传输；与块流式传输分开）
streamMode: "partial", // off | partial | block（草稿流式传输；与分块流式传输分开）
draftChunk: {
// 可选；仅用于 streamMode=block
minChars: 200,
@@ -1505,7 +1505,7 @@ exec ssh -T gateway-host imsg "$@"
}
```
`responsePrefix` 应用于跨渠道的**所有出站回复**（工具摘要、块流式传输、最终回复），除非已存在。
`responsePrefix` 应用于跨渠道的**所有出站回复**（工具摘要、分块流式传输、最终回复），除非已存在。
如果未设置 `messages.responsePrefix`，默认不应用前缀。WhatsApp 自聊天回复是例外：它们在设置时默认为 `[{identity.name}]`，否则为 `[openclaw]`，以保持同一手机上的对话可读性。
设为 `"auto"` 可为路由的智能体推导 `[{identity.name}]`（当设置时）。
@@ -1611,7 +1611,7 @@ WhatsApp 入站前缀通过 `channels.whatsapp.messagePrefix` 配置（已弃用
### `talk`
Talk 模式（macOS/iOS/Android）的默认值。语音 ID 在未设置时回退到 `ELEVENLABS_VOICE_ID` 或 `SAG_VOICE_ID`。
`apiKey` 在未设置时回退到 `ELEVENLABS_API_KEY`（或 Gateway网关的 shell 配置文件）。
`apiKey` 在未设置时回退到 `ELEVENLABS_API_KEY`（或 Gateway 网关的 shell 配置文件）。
`voiceAliases` 允许 Talk 指令使用友好名称（例如 `"voice":"Clawd"`）。
```json5
@@ -1918,10 +1918,10 @@ MiniMax 认证：设置 `MINIMAX_API_KEY`（环境变量）或配置 `models.pro
}
```
块流式传输：
分块流式传输：
- `agents.defaults.blockStreamingDefault`：`"on"`/`"off"`（默认 off）。
- 渠道覆盖：`*.blockStreaming`（及每账号变体）强制块流式传输开/关。
- 渠道覆盖：`*.blockStreaming`（及每账号变体）强制分块流式传输开/关。
非 Telegram 渠道需要显式设置 `*.blockStreaming: true` 来启用块回复。
- `agents.defaults.blockStreamingBreak`：`"text_end"` 或 `"message_end"`（默认：text_end）。
- `agents.defaults.blockStreamingChunk`：流式块的软分块。默认 800–1200 字符，优先段落分隔（`\n\n`），然后换行，然后句子。
@@ -2147,7 +2147,7 @@ Z.AI 模型可通过 `zai/<model>` 使用（例如 `zai/glm-4.7`），需要环
`tools.allow` / `tools.deny` 配置全局工具允许/拒绝策略（deny 优先）。
匹配不区分大小写并支持 `*` 通配符（`"*"` 表示所有工具）。
即使 Docker 沙盒**关闭**，此策略也会应用。
即使 Docker 沙箱**关闭**，此策略也会应用。
示例（全局禁用 browser/canvas）：
@@ -2218,30 +2218,30 @@ Z.AI 模型可通过 `zai/<model>` 使用（例如 `zai/glm-4.7`），需要环
- `tools.elevated` 是全局基线。`agents.list[].tools.elevated` 只能进一步限制（两者都必须允许）。
- `/elevated on|off|ask|full` 按会话键存储状态；内联指令仅应用于单条消息。
- 提升的 `exec` 在主机上运行并绕过沙盒。
- 提升的 `exec` 在主机上运行并绕过沙箱。
- 工具策略仍然适用；如果 `exec` 被拒绝，则无法使用提升。
`agents.defaults.maxConcurrent` 设置跨会话可并行执行的内置智能体运行的最大数量。每个会话仍然是串行的（每个会话键同时只有一个运行）。默认：1。
### `agents.defaults.sandbox`
为内置智能体提供可选的 **Docker 沙盒**。适用于非主会话，使其无法访问你的主机系统。
为内置智能体提供可选的 **Docker 沙箱**。适用于非主会话，使其无法访问你的主机系统。
详情：[沙盒](/gateway/sandboxing)
详情：[沙箱](/gateway/sandboxing)
默认值（如果启用）：
- scope：`"agent"`（每个智能体一个容器 + 工作区）
- 基于 Debian bookworm-slim 的镜像
- 智能体工作区访问：`workspaceAccess: "none"`（默认）
- `"none"`：在 `~/.openclaw/sandboxes` 下使用每范围的沙盒工作区
- `"ro"`：将沙盒工作区保持在 `/workspace`，智能体工作区以只读方式挂载到 `/agent`（禁用 `write`/`edit`/`apply_patch`）
- `"none"`：在 `~/.openclaw/sandboxes` 下使用每范围的沙箱工作区
- `"ro"`：将沙箱工作区保持在 `/workspace`，智能体工作区以只读方式挂载到 `/agent`（禁用 `write`/`edit`/`apply_patch`）
- `"rw"`：将智能体工作区以读写方式挂载到 `/workspace`
- 自动清理：空闲超过 24h 或存在超过 7d
- 工具策略：仅允许 `exec`、`process`、`read`、`write`、`edit`、`apply_patch`、`sessions_list`、`sessions_history`、`sessions_send`、`sessions_spawn`、`session_status`（deny 优先）
- 通过 `tools.sandbox.tools` 配置，通过 `agents.list[].tools.sandbox.tools` 进行每智能体覆盖
- 沙盒策略中支持工具组简写：`group:runtime`、`group:fs`、`group:sessions`、`group:memory`（参见[沙盒 vs 工具策略 vs 提升](/gateway/sandbox-vs-tool-policy-vs-elevated#tool-groups-shorthands)）
- 可选的沙盒浏览器（Chromium + CDP，noVNC 观察器）
- 沙箱策略中支持工具组简写：`group:runtime`、`group:fs`、`group:sessions`、`group:memory`（参见[沙箱 vs 工具策略 vs 提升](/gateway/sandbox-vs-tool-policy-vs-elevated#tool-groups-shorthands)）
- 可选的沙箱浏览器（Chromium + CDP，noVNC 观察器）
- 加固旋钮：`network`、`user`、`pidsLimit`、`memory`、`cpus`、`ulimits`、`seccompProfile`、`apparmorProfile`
警告：`scope: "shared"` 意味着共享容器和共享工作区。无跨会话隔离。使用 `scope: "session"` 获得每会话隔离。
@@ -2332,13 +2332,13 @@ Z.AI 模型可通过 `zai/<model>` 使用（例如 `zai/glm-4.7`），需要环
}
```
首次构建默认沙盒镜像：
首次构建默认沙箱镜像：
```bash
scripts/sandbox-setup.sh
```
注意：沙盒容器默认为 `network: "none"`；如果智能体需要出站访问，请将 `agents.defaults.sandbox.docker.network` 设为 `"bridge"`（或你的自定义网络）。
注意：沙箱容器默认为 `network: "none"`；如果智能体需要出站访问，请将 `agents.defaults.sandbox.docker.network` 设为 `"bridge"`（或你的自定义网络）。
注意：入站附件会暂存到活跃工作区的 `media/inbound/*` 中。使用 `workspaceAccess: "rw"` 时，文件会写入智能体工作区。
@@ -2350,14 +2350,14 @@ scripts/sandbox-setup.sh
scripts/sandbox-browser-setup.sh
```
当 `agents.defaults.sandbox.browser.enabled=true` 时，浏览器工具使用沙盒化的
当 `agents.defaults.sandbox.browser.enabled=true` 时，浏览器工具使用沙箱化的
Chromium 实例（CDP）。如果启用了 noVNC（headless=false 时默认启用），
noVNC URL 会注入系统提示中，以便智能体可以引用它。
这不需要主配置中的 `browser.enabled`；沙盒控制 URL 按会话注入。
这不需要主配置中的 `browser.enabled`；沙箱控制 URL 按会话注入。
`agents.defaults.sandbox.browser.allowHostControl`（默认：false）允许
沙盒会话通过浏览器工具显式访问**主机**浏览器控制服务器
（`target: "host"`）。如果你需要严格的沙盒隔离，请保持关闭。
沙箱会话通过浏览器工具显式访问**主机**浏览器控制服务器
（`target: "host"`）。如果你需要严格的沙箱隔离，请保持关闭。
远程控制白名单：
@@ -2713,7 +2713,7 @@ Z.AI 模型通过内置的 `zai` 提供商提供。在环境中设置 `ZAI_API_K
字段：
- `mainKey`：私聊桶键（默认：`"main"`）。当你想"重命名"主私聊线程而不更改 `agentId` 时有用。
- 沙盒说明：`agents.defaults.sandbox.mode: "non-main"` 使用此键检测主会话。任何不匹配 `mainKey` 的会话键（群组/频道）都会被沙盒化。
- 沙箱说明：`agents.defaults.sandbox.mode: "non-main"` 使用此键检测主会话。任何不匹配 `mainKey` 的会话键（群组/频道）都会被沙箱化。
- `dmScope`：私聊会话如何分组（默认：`"main"`）。
- `main`：所有私聊共享主会话以保持连续性。
- `per-peer`：按发送者 id 跨渠道隔离私聊。
@@ -2721,7 +2721,7 @@ Z.AI 模型通过内置的 `zai` 提供商提供。在环境中设置 `ZAI_API_K
- `per-account-channel-peer`：按账号 + 渠道 + 发送者隔离私聊（推荐用于多账号收件箱）。
- `identityLinks`：将规范 id 映射到提供商前缀的对等方，以便在使用 `per-peer`、`per-channel-peer` 或 `per-account-channel-peer` 时同一人跨渠道共享私聊会话。
- 示例：`alice: ["telegram:123456789", "discord:987654321012345678"]`。
- `reset`：主重置策略。默认为 Gateway网关主机上本地时间凌晨 4:00 每日重置。
- `reset`：主重置策略。默认为 Gateway 网关主机上本地时间凌晨 4:00 每日重置。
- `mode`：`daily` 或 `idle`（当存在 `reset` 时默认：`daily`）。
- `atHour`：本地小时（0-23）作为每日重置边界。
- `idleMinutes`：滑动空闲窗口（分钟）。当 daily + idle 都配置时，先到期的获胜。
@@ -2732,7 +2732,7 @@ Z.AI 模型通过内置的 `zai` 提供商提供。在环境中设置 `ZAI_API_K
- `sendPolicy.default`：无规则匹配时的 `allow` 或 `deny` 回退。
- `sendPolicy.rules[]`：按 `channel`、`chatType`（`direct|group|room`）或 `keyPrefix`（例如 `cron:`）匹配。第一个 deny 获胜；否则 allow。
### `skills`（Skills配置）
### `skills`（Skills 配置）
控制内置白名单、安装偏好、额外 Skills 文件夹和每 Skills 覆盖。适用于**内置**Skills 和 `~/.openclaw/skills`（工作区 Skills 在名称冲突时仍然优先）。
@@ -2742,7 +2742,7 @@ Z.AI 模型通过内置的 `zai` 提供商提供。在环境中设置 `ZAI_API_K
- `load.extraDirs`：额外要扫描的 Skills 目录（最低优先级）。
- `install.preferBrew`：可用时优先使用 brew 安装程序（默认：true）。
- `install.nodeManager`：node 安装偏好（`npm` | `pnpm` | `yarn`，默认：npm）。
- `entries.<skillKey>`：每 Skills配置覆盖。
- `entries.<skillKey>`：每 Skills 配置覆盖。
每 Skills 字段：
@@ -2779,8 +2779,8 @@ Z.AI 模型通过内置的 `zai` 提供商提供。在环境中设置 `ZAI_API_K
### `plugins`（扩展）
控制插件发现、允许/拒绝和每插件配置。插件从 `~/.openclaw/extensions`、`<workspace>/.openclaw/extensions` 以及任何 `plugins.load.paths` 条目加载。**配置更改需要重启 Gateway网关。**
参见 [/plugin](/plugin) 了解全部用法。
控制插件发现、允许/拒绝和每插件配置。插件从 `~/.openclaw/extensions`、`<workspace>/.openclaw/extensions` 以及任何 `plugins.load.paths` 条目加载。**配置更改需要重启 Gateway 网关。**
参见 [/plugin](/plugin) 了解详情。
字段：
@@ -2828,7 +2828,7 @@ OpenClaw 可以为 OpenClaw 启动一个**专用、隔离的** Chrome/Brave/Edge
- 控制服务：仅 local loopback（端口从 `gateway.port` 派生，默认 `18791`）
- CDP URL：`http://127.0.0.1:18792`（控制服务 + 1，旧版单配置文件）
- 配置文件颜色：`#FF4500`（龙虾橙）
- 注意：控制服务器由运行中的 Gateway网关（OpenClaw.app 菜单栏或 `openclaw gateway`）启动。
- 注意：控制服务器由运行中的 Gateway 网关（OpenClaw.app 菜单栏或 `openclaw gateway`）启动。
- 自动检测顺序：如果为 Chromium 内核则使用默认浏览器；否则 Chrome → Brave → Edge → Chromium → Chrome Canary。
```json5
@@ -2873,9 +2873,9 @@ OpenClaw 可以为 OpenClaw 启动一个**专用、隔离的** Chrome/Brave/Edge
}
```
### `gateway`（Gateway网关服务器模式 + 绑定）
### `gateway`（Gateway 网关服务器模式 + 绑定）
使用 `gateway.mode` 明确声明此机器是否应运行 Gateway网关。
使用 `gateway.mode` 明确声明此机器是否应运行 Gateway 网关。
默认值：
@@ -2914,7 +2914,7 @@ OpenClaw 可以为 OpenClaw 启动一个**专用、隔离的** Chrome/Brave/Edge
信任的代理：
- `gateway.trustedProxies`：在 Gateway网关前面终止 TLS 的反向代理 IP 列表。
- `gateway.trustedProxies`：在 Gateway 网关前面终止 TLS 的反向代理 IP 列表。
- 当连接来自这些 IP 之一时，OpenClaw 使用 `x-forwarded-for`（或 `x-real-ip`）来确定客户端 IP，用于本地配对检查和 HTTP 认证/本地检查。
- 仅列出你完全控制的代理，并确保它们**覆盖**传入的 `x-forwarded-for`。
@@ -2924,7 +2924,7 @@ OpenClaw 可以为 OpenClaw 启动一个**专用、隔离的** Chrome/Brave/Edge
- `gateway.port` 控制用于 WebSocket + HTTP（控制台 UI、hooks、A2UI）的单一多路复用端口。
- OpenAI Chat Completions 端点：**默认禁用**；通过 `gateway.http.endpoints.chatCompletions.enabled: true` 启用。
- 优先级：`--port` > `OPENCLAW_GATEWAY_PORT` > `gateway.port` > 默认 `18789`。
- 默认需要 Gateway网关认证（token/密码或 Tailscale Serve 身份）。非 local loopback 绑定需要共享 token/密码。
- 默认需要 Gateway 网关认证（token/密码或 Tailscale Serve 身份）。非 local loopback 绑定需要共享 token/密码。
- 新手引导向导默认生成 gateway token（即使在 local loopback 上）。
- `gateway.remote.token` **仅**用于远程 CLI 调用；它不启用本地 gateway 认证。`gateway.token` 被忽略。
@@ -2946,7 +2946,7 @@ OpenClaw 可以为 OpenClaw 启动一个**专用、隔离的** Chrome/Brave/Edge
远程客户端默认值（CLI）：
- `gateway.remote.url` 设置 `gateway.mode = "remote"` 时 CLI 调用的默认 Gateway网关 WebSocket URL。
- `gateway.remote.url` 设置 `gateway.mode = "remote"` 时 CLI 调用的默认 Gateway 网关 WebSocket URL。
- `gateway.remote.transport` 选择 macOS 远程传输（`ssh` 默认，`direct` 用于 ws/wss）。使用 `direct` 时，`gateway.remote.url` 必须为 `ws://` 或 `wss://`。`ws://host` 默认端口 `18789`。
- `gateway.remote.token` 提供远程调用的 token（不需要认证时留空）。
- `gateway.remote.password` 提供远程调用的密码（不需要认证时留空）。
@@ -2987,13 +2987,13 @@ macOS 应用行为：
### `gateway.reload`（配置热重载）
Gateway网关监视 `~/.openclaw/openclaw.json`（或 `OPENCLAW_CONFIG_PATH`）并自动应用更改。
Gateway 网关监视 `~/.openclaw/openclaw.json`（或 `OPENCLAW_CONFIG_PATH`）并自动应用更改。
模式：
- `hybrid`（默认）：安全更改热应用；关键更改重启 Gateway网关。
- `hybrid`（默认）：安全更改热应用；关键更改重启 Gateway 网关。
- `hot`：仅应用热安全更改；需要重启时记录日志。
- `restart`：任何配置更改都重启 Gateway网关。
- `restart`：任何配置更改都重启 Gateway 网关。
- `off`：禁用热重载。
```json5
@@ -3013,7 +3013,7 @@ Gateway网关监视 `~/.openclaw/openclaw.json`（或 `OPENCLAW_CONFIG_PATH`）
- `~/.openclaw/openclaw.json`（或 `OPENCLAW_CONFIG_PATH`）
热应用（无需完全重启 Gateway网关）：
热应用（无需完全重启 Gateway 网关）：
- `hooks`（webhook 认证/路径/映射）+ `hooks.gmail`（Gmail 监视器重启）
- `browser`（浏览器控制服务器重启）
@@ -3023,7 +3023,7 @@ Gateway网关监视 `~/.openclaw/openclaw.json`（或 `OPENCLAW_CONFIG_PATH`）
- `telegram`、`discord`、`signal`、`imessage`（渠道重启）
- `agent`、`models`、`routing`、`messages`、`session`、`whatsapp`、`logging`、`skills`、`ui`、`talk`、`identity`、`wizard`（动态读取）
需要完全重启 Gateway网关：
需要完全重启 Gateway 网关：
- `gateway`（端口/绑定/认证/控制台 UI/tailscale）
- `bridge`（旧版）
@@ -3034,7 +3034,7 @@ Gateway网关监视 `~/.openclaw/openclaw.json`（或 `OPENCLAW_CONFIG_PATH`）
### 多实例隔离
要在一台主机上运行多个 Gateway网关（用于冗余或救援机器人），请隔离每个实例的状态 + 配置并使用唯一端口：
要在一台主机上运行多个 Gateway 网关（用于冗余或救援机器人），请隔离每个实例的状态 + 配置并使用唯一端口：
- `OPENCLAW_CONFIG_PATH`（每实例配置）
- `OPENCLAW_STATE_DIR`（会话/凭据）
@@ -3046,8 +3046,8 @@ Gateway网关监视 `~/.openclaw/openclaw.json`（或 `OPENCLAW_CONFIG_PATH`）
- `openclaw --dev …` → 使用 `~/.openclaw-dev` + 端口从基础 `19001` 偏移
- `openclaw --profile <name> …` → 使用 `~/.openclaw-<name>`（端口通过配置/环境变量/标志）
参见 [Gateway网关运维手册](/gateway) 了解派生的端口映射（gateway/browser/canvas）。
参见[多 Gateway网关](/gateway/multiple-gateways) 了解浏览器/CDP 端口隔离细节。
参见 [Gateway 网关运维手册](/gateway) 了解派生的端口映射（gateway/browser/canvas）。
参见[多 Gateway 网关](/gateway/multiple-gateways) 了解浏览器/CDP 端口隔离细节。
示例：
@@ -3057,9 +3057,9 @@ OPENCLAW_STATE_DIR=~/.openclaw-a \
openclaw gateway --port 19001
```
### `hooks`（Gateway网关 webhook）
### `hooks`（Gateway 网关 webhook）
在 Gateway网关 HTTP 服务器上启用简单的 HTTP webhook 端点。
在 Gateway 网关 HTTP 服务器上启用简单的 HTTP webhook 端点。
默认值：
@@ -3152,12 +3152,12 @@ Gmail hook 的模型覆盖：
- 启动时，如果配置的模型不在模型目录或白名单中，会发出警告。
- `hooks.gmail.thinking` 设置 Gmail hook 的默认思考级别，被每 hook 的 `thinking` 覆盖。
Gateway网关自动启动：
Gateway 网关自动启动：
- 如果 `hooks.enabled=true` 且 `hooks.gmail.account` 已设置，Gateway网关在启动时
- 如果 `hooks.enabled=true` 且 `hooks.gmail.account` 已设置，Gateway 网关在启动时
启动 `gog gmail watch serve` 并自动续期监视。
- 设置 `OPENCLAW_SKIP_GMAIL_WATCHER=1` 禁用自动启动（用于手动运行）。
- 避免在 Gateway网关旁边单独运行 `gog gmail watch serve`；它会
- 避免在 Gateway 网关旁边单独运行 `gog gmail watch serve`；它会
因 `listen tcp 127.0.0.1:8788: bind: address already in use` 而失败。
注意：当 `tailscale.mode` 开启时，OpenClaw 将 `serve.path` 默认为 `/`，以便
@@ -3167,11 +3167,11 @@ Tailscale 可以正确代理 `/gmail-pubsub`（它会去除设置的路径前缀
### `canvasHost`（LAN/tailnet Canvas 文件服务器 + 实时重载）
Gateway网关通过 HTTP 提供 HTML/CSS/JS 目录服务，以便 iOS/Android 节点可以简单地 `canvas.navigate` 到它。
Gateway 网关通过 HTTP 提供 HTML/CSS/JS 目录服务，以便 iOS/Android 节点可以简单地 `canvas.navigate` 到它。
默认根目录：`~/.openclaw/workspace/canvas`
默认端口：`18793`（选择此端口以避免 OpenClaw 浏览器 CDP 端口 `18792`）
服务器监听 **Gateway网关绑定主机**（LAN 或 Tailnet），以便节点可以访问。
服务器监听 **Gateway 网关绑定主机**（LAN 或 Tailnet），以便节点可以访问。
服务器：
@@ -3196,7 +3196,7 @@ Gateway网关通过 HTTP 提供 HTML/CSS/JS 目录服务，以便 iOS/Android
}
```
`canvasHost.*` 的更改需要重启 Gateway网关（配置重载会触发重启）。
`canvasHost.*` 的更改需要重启 Gateway 网关（配置重载会触发重启）。
禁用方式：
@@ -3206,11 +3206,11 @@ Gateway网关通过 HTTP 提供 HTML/CSS/JS 目录服务，以便 iOS/Android
### `bridge`（旧版 TCP 桥接，已移除）
当前版本不再包含 TCP 桥接监听器；`bridge.*` 配置键会被忽略。
节点通过 Gateway网关 WebSocket 连接。此部分仅保留供历史参考。
节点通过 Gateway 网关 WebSocket 连接。此部分仅保留供历史参考。
旧版行为：
- Gateway网关可以为节点（iOS/Android）暴露简单的 TCP 桥接，通常在端口 `18790`。
- Gateway 网关可以为节点（iOS/Android）暴露简单的 TCP 桥接，通常在端口 `18790`。
默认值：
@@ -3232,7 +3232,7 @@ TLS：
- `bridge.tls.certPath` / `bridge.tls.keyPath`：桥接证书 + 私钥的 PEM 路径。
- `bridge.tls.caPath`：可选的 PEM CA 捆绑包（自定义根证书或未来的 mTLS）。
启用 TLS 后，Gateway网关在发现 TXT 记录中通告 `bridgeTls=1` 和 `bridgeTlsSha256`，以便节点可以固定证书。如果尚未存储指纹，手动连接使用首次信任。
启用 TLS 后，Gateway 网关在发现 TXT 记录中通告 `bridgeTls=1` 和 `bridgeTlsSha256`，以便节点可以固定证书。如果尚未存储指纹，手动连接使用首次信任。
自动生成的证书需要 PATH 中有 `openssl`；如果生成失败，桥接不会启动。
```json5
@@ -3268,14 +3268,14 @@ TLS：
### `discovery.wideArea`（广域 Bonjour / 单播 DNS‑SD）
启用后，Gateway网关在 `~/.openclaw/dns/` 下使用配置的发现域（示例：`openclaw.internal.`）为 `_openclaw-gw._tcp` 写入单播 DNS-SD 区域。
启用后，Gateway 网关在 `~/.openclaw/dns/` 下使用配置的发现域（示例：`openclaw.internal.`）为 `_openclaw-gw._tcp` 写入单播 DNS-SD 区域。
要使 iOS/Android 跨网络发现（跨地域访问），请配合以下使用：
- 在 Gateway网关主机上运行 DNS 服务器，为你选择的域名提供服务（推荐 CoreDNS）
- Tailscale **split DNS**，使客户端通过 Gateway网关 DNS 服务器解析该域名
- 在 Gateway 网关主机上运行 DNS 服务器，为你选择的域名提供服务（推荐 CoreDNS）
- Tailscale **split DNS**，使客户端通过 Gateway 网关 DNS 服务器解析该域名
一次性设置助手（Gateway网关主机）：
一次性设置助手（Gateway 网关主机）：
```bash
openclaw dns setup --apply
@@ -3314,9 +3314,9 @@ openclaw dns setup --apply
| `{{SenderE164}}` | 发送者电话号码（尽力而为） |
| `{{Provider}}` | 提供商提示（whatsapp | telegram | discord | googlechat | slack | signal | imessage | msteams | webchat | …） |
## Cron（Gateway网关调度器）
## Cron（Gateway 网关调度器）
Cron 是 Gateway网关自有的唤醒和定时任务调度器。参见 [Cron 任务](/automation/cron-jobs) 了解功能概述和 CLI 示例。
Cron 是 Gateway 网关自有的唤醒和定时任务调度器。参见 [Cron 任务](/automation/cron-jobs) 了解功能概述和 CLI 示例。
```json5
{

112
docs/zh-CN/gateway/discovery.md
View File

@@ -1,99 +1,99 @@
---
read_when:
- 实现或更改 Bonjour 发现/广播功能
- 实现或更改 Bonjour 发现/广播
- 调整远程连接模式（直连 vs SSH）
- 为远程节点设计节点发现 + 配对方案
summary: 节点发现与传输（Bonjour、Tailscale、SSH）用于查找 Gateway网关
title: 发现与传输
- 设计远程节点的节点发现 + 配对
summary: 用于发现 Gateway 网关的节点发现和传输协议（Bonjour、Tailscale、SSH）
title: 设备发现 + 传输协议
x-i18n:
generated_at: "2026-02-01T20:25:57Z"
generated_at: "2026-02-03T10:06:11Z"
model: claude-opus-4-5
provider: pi
source_hash: e12172c181515bfa6aab8625ed3fbc335b80ba92e2b516c02c6066aeeb9f884c
source_path: gateway/discovery.md
workflow: 14
workflow: 15
---
# 发现与传输
# 设备发现 & 传输协议
OpenClaw 有两个表面上看起来相似但实际上不同的问题：
OpenClaw 有两个表面上看起来相似的不同问题：
1. **操作者远程控制**：macOS 菜单栏应用控制运行在其他位置的 Gateway网关。
2. **节点配对**：iOS/Android（以及未来的节点）找到 Gateway网关并安全配对。
1. **操作员远程控制**：macOS 菜单栏应用控制运行在其他地方的 Gateway 网关。
2. **节点配对**：iOS/Android（以及未来的节点）发现 Gateway 网关并安全配对。
设计目标是将所有网络发现/广播保留在 **Node Gateway网关**（`openclaw gateway`）中，让客户端（Mac 应用、iOS）作为消费者。
设计目标是将所有网络发现/广播保留在 **Node Gateway 网关**（`openclaw gateway`）中，并让客户端（mac 应用、iOS）作为消费者。
## 术语
- **Gateway网关**：一个长期运行的 Gateway网关进程，拥有状态（会话、配对、节点注册表）并运行渠道。大多数配置每台主机使用一个；也可以进行隔离的多 Gateway网关设置。
- **Gateway网关 WS（控制平面）**：默认位于 `127.0.0.1:18789` 的 WebSocket 端点；可通过 `gateway.bind` 绑定到局域网/Tailnet。
- **直连 WS 传输**：面向局域网/Tailnet 的 Gateway网关 WS 端点（无 SSH）。
- **SSH 传输（回退）**：通过 SSH 转发 `127.0.0.1:18789` 实现远程控制。
- **旧版 TCP 桥接（已弃用/移除）**：旧的节点传输方式（参见 [桥接协议](/gateway/bridge-protocol)）；不再用于发现广播。
- **Gateway 网关**：一个长期运行的 Gateway 网关进程，拥有状态（会话、配对、节点注册表）并运行渠道。大多数设置每台主机使用一个；也可以进行隔离的多 Gateway 网关设置。
- **Gateway 网关 WS（控制平面）**：默认在 `127.0.0.1:18789` 上的 WebSocket 端点；可通过 `gateway.bind` 绑定到 LAN/tailnet。
- **直连 WS 传输**：面向 LAN/tailnet 的 Gateway 网关 WS 端点（无 SSH）。
- **SSH 传输（回退）**：通过 SSH 转发 `127.0.0.1:18789` 进行远程控制。
- **旧版 TCP 桥接（已弃用/移除）**：旧的节点传输（参见 [桥接协议](/gateway/bridge-protocol)）；不再用于发现广播。
协议详情：
- [Gateway网关协议](/gateway/protocol)
- [Gateway 网关协议](/gateway/protocol)
- [桥接协议（旧版）](/gateway/bridge-protocol)
## 为什么同时保留"直连"和 SSH
## 为什么我们同时保留"直连"和 SSH
- **直连 WS** 在同一网络和 Tailnet 内提供最佳用户体验：
- 通过 Bonjour 在局域网上自动发现
- 配对令牌 + ACL 由 Gateway网关管理
- 不需要 shell 访问；协议接口可以保持精简且可审计
- **SSH** 仍然是通用的回退方案：
- 在任何有 SSH 访问的地方都可以工作（甚至跨不相关的网络）
- 不受组播/mDNS 问题影响
- 除 SSH 外不需要新的入站端口
- **直连 WS** 在同一网络和 tailnet 内提供最佳用户体验：
- 通过 Bonjour 在 LAN 上自动发现
- 配对令牌 + ACL 由 Gateway 网关管理
- 无需 shell 访问；协议表面可保持紧凑和可审计
- **SSH** 仍然是通用回退方案：
- 只要你有 SSH 访问权限就能工作（即使跨越不相关的网络）
- 能应对多播/mDNS 问题
- 除 SSH 外无需新的入站端口
## 发现输入（客户端如何获知 Gateway网关位置）
## 发现输入（客户端如何了解 Gateway 网关位置）
### 1) Bonjour / mDNS（仅限局域网）
### 1）Bonjour / mDNS（仅限 LAN）
Bonjour 是尽力而为的机制，无法跨网络。它仅用于"同一局域网"的便捷发现。
Bonjour 是尽力而为的，不会跨网络。它仅用于"同一 LAN"的便利性。
目标方向：
- **Gateway网关** 通过 Bonjour 广播其 WS 端点。
- 客户端浏览并显示"选择 Gateway网关"列表，然后存储所选端点。
- **Gateway 网关**通过 Bonjour 广播其 WS 端点。
- 客户端浏览并显示"选择一个 Gateway 网关"列表，然后存储选定的端点。
故障排除和信标详情：[Bonjour](/gateway/bonjour)。
#### 服务信标详情
- 服务类型：
- `_openclaw-gw._tcp`（Gateway网关传输信标）
- `_openclaw-gw._tcp`（Gateway 网关传输信标）
- TXT 键（非机密）：
- `role=gateway`
- `lanHost=<主机名>.local`
- `sshPort=22`（或实际广播的端口）
- `gatewayPort=18789`（Gateway网关 WS + HTTP）
- `gatewayTls=1`（仅在启用 TLS 时）
- `gatewayTlsSha256=<sha256>`（仅在启用 TLS 且指纹可用时）
- `canvasPort=18793`（默认 canvas 主机端口；服务于 `/__openclaw__/canvas/`）
- `cliPath=<路径>`（可选；可运行的 `openclaw` 入口点或二进制文件的绝对路径）
- `lanHost=<hostname>.local`
- `sshPort=22`（或广播的端口）
- `gatewayPort=18789`（Gateway 网关 WS + HTTP）
- `gatewayTls=1`（仅当启用 TLS 时）
- `gatewayTlsSha256=<sha256>`（仅当启用 TLS 且指纹可用时）
- `canvasPort=18793`（默认画布主机端口；服务于 `/__openclaw__/canvas/`）
- `cliPath=<path>`（可选；可运行的 `openclaw` 入口点或二进制文件的绝对路径）
- `tailnetDns=<magicdns>`（可选提示；当 Tailscale 可用时自动检测）
禁用/覆盖：
- `OPENCLAW_DISABLE_BONJOUR=1` 禁用广播。
- `~/.openclaw/openclaw.json` 中的 `gateway.bind` 控制 Gateway网关绑定模式。
- `~/.openclaw/openclaw.json` 中的 `gateway.bind` 控制 Gateway 网关绑定模式。
- `OPENCLAW_SSH_PORT` 覆盖 TXT 中广播的 SSH 端口（默认为 22）。
- `OPENCLAW_TAILNET_DNS` 发布 `tailnetDns` 提示（MagicDNS）。
- `OPENCLAW_CLI_PATH` 覆盖广播的 CLI 路径。
### 2) Tailnet（跨网络）
### 2）Tailnet（跨网络）
对于伦敦/维也纳式的跨地域部署，Bonjour 无法提供帮助。推荐的"直连"目标是：
对于伦敦/维也纳风格的设置，Bonjour 无法帮助。推荐的"直连"目标是：
- Tailscale MagicDNS 名称（首选）或稳定的 Tailnet IP。
- Tailscale MagicDNS 名称（首选）或稳定的 tailnet IP。
如果 Gateway网关能检测到自己运行在 Tailscale 下，它会将 `tailnetDns` 作为可选提示发布给客户端（包括广域信标）。
如果 Gateway 网关能检测到它正在 Tailscale 下运行，它会发布 `tailnetDns` 作为客户端的可选提示（包括广域信标）。
### 3) 手动 / SSH 目标
### 3）手动 / SSH 目标
当没有直接路由（或直连被禁用）时，客户端始终可以通过 SSH 转发 local loopback Gateway网关端口进行连接。
当没有直连路由（或直连被禁用）时，客户端始终可以通过 SSH 转发本地回环 Gateway 网关端口来连接。
参见 [远程访问](/gateway/remote)。
@@ -101,23 +101,23 @@ Bonjour 是尽力而为的机制，无法跨网络。它仅用于"同一局域
推荐的客户端行为：
1. 如果已配置并可达已配对的直连端点，则使用它。
2. 否则，如果 Bonjour 在局域网上发现了 Gateway网关，提供一键"使用此 Gateway网关"选项并将其保存为直连端点。
3. 否则，如果配置了 Tailnet DNS/IP，尝试直连。
1. 如果已配置且可达已配对的直连端点，使用它。
2. 否则，如果 Bonjour 在 LAN 上找到 Gateway 网关，提供一键"使用此 Gateway 网关"选择并将其保存为直连端点。
3. 否则，如果配置了 tailnet DNS/IP，尝试直连。
4. 否则，回退到 SSH。
## 配对 + 认证（直连传输）
Gateway网关是节点/客户端准入的权威来源。
Gateway 网关是节点/客户端准入的唯一权威来源。
- 配对请求在 Gateway网关中创建/批准/拒绝（参见 [Gateway网关配对](/gateway/pairing)）。
- Gateway网关强制执行：
- 配对请求在 Gateway 网关中创建/批准/拒绝（参见 [Gateway 网关配对](/gateway/pairing)）。
- Gateway 网关强制执行：
- 认证（令牌 / 密钥对）
- 权限范围/ACL（Gateway网关不是对所有方法的原始代理）
- 作用域/ACL（Gateway 网关不是每个方法的原始代理）
- 速率限制
## 各组件职责
- **Gateway网关**：广播发现信标，管理配对决策，并托管 WS 端点。
- **macOS 应用**：帮助你选择 Gateway网关，显示配对提示，仅将 SSH 作为回退方案。
- **iOS/Android 节点**：将 Bonjour 浏览作为便捷方式，连接到已配对的 Gateway网关 WS。
- **Gateway 网关**：广播发现信标，拥有配对决策权，并托管 WS 端点。
- **macOS 应用**：帮助你选择 Gateway 网关，显示配对提示，仅将 SSH 作为回退方案。
- **iOS/Android 节点**：将 Bonjour 浏览作为便利功能，连接到已配对的 Gateway 网关 WS。

176
docs/zh-CN/gateway/doctor.md
View File

@@ -1,21 +1,21 @@
---
read_when:
- 添加或修改 doctor 迁移
- 引入破坏性配置变更
- 引入破坏性配置更改
summary: Doctor 命令：健康检查、配置迁移和修复步骤
title: Doctor
x-i18n:
generated_at: "2026-02-01T20:26:33Z"
generated_at: "2026-02-03T07:49:03Z"
model: claude-opus-4-5
provider: pi
source_hash: df7b25f60fd08d508f4c6abfc8e7e06f29bd4bbb34c3320397f47eb72c8de83f
source_path: gateway/doctor.md
workflow: 14
workflow: 15
---
# Doctor
`openclaw doctor` 是 OpenClaw 的修复 + 迁移工具。它修复过时的配置/状态、检查健康状况，并提供可操作的修复步骤。
`openclaw doctor` 是 OpenClaw 的修复 + 迁移工具。它修复过时的配置/状态，检查健康状况，并提供可操作的修复步骤。
## 快速开始
@@ -23,38 +23,38 @@ x-i18n:
openclaw doctor
```
### 无界面 / 自动化
### 无头/自动化
```bash
openclaw doctor --yes
```
无需提示即接受默认值（包括适用时的重启/服务/沙箱修复步骤）。
无需提示接受默认值（包括适用时的重启/服务/沙箱修复步骤）。
```bash
openclaw doctor --repair
```
无需提示即应用推荐修复（安全情况下执行修复 + 重启）。
无需提示应用推荐的修复（安全时进行修复 + 重启）。
```bash
openclaw doctor --repair --force
```
同时应用激进修复（覆盖自定义 supervisor 配置）。
也应用激进的修复（覆盖自定义 supervisor 配置）。
```bash
openclaw doctor --non-interactive
```
无提示运行，仅应用安全迁移（配置规范化 + 磁盘状态迁移）。跳过需要人工确认的重启/服务/沙箱操作。
检测到遗留状态迁移时会自动运行。
无需提示运行，仅应用安全迁移（配置规范化 + 磁盘状态移动）。跳过需要人工确认的重启/服务/沙箱操作。
检测到时自动运行遗留状态迁移。
```bash
openclaw doctor --deep
```
扫描系统服务以查找额外的 Gateway网关安装（launchd/systemd/schtasks）。
扫描系统服务以查找额外的 Gateway 网关安装（launchd/systemd/schtasks）。
如果你想在写入前查看更改，请先打开配置文件：
@@ -64,51 +64,51 @@ cat ~/.openclaw/openclaw.json
## 功能概述
- 可选的 git 安装预检更新（仅交互模式）。
- UI 协议新鲜度检查（当协议 schema 更新时重建控制 UI）。
- git 安装的可选预检更新（仅交互模式）。
- UI 协议新鲜度检查（当协议 schema 较新时重建 Control UI）。
- 健康检查 + 重启提示。
- Skills 状态摘要（可用/缺失/受阻）。
- Skills 状态摘要（符合条件/缺失/被阻止）。
- 遗留值的配置规范化。
- OpenCode Zen 提供商覆盖警告（`models.providers.opencode`）。
- 遗留磁盘状态迁移（会话/智能体目录/WhatsApp 认证）。
- 状态完整性和权限检查（会话、转录、状态目录）。
- 状态完整性和权限检查（会话、记录、状态目录）。
- 本地运行时的配置文件权限检查（chmod 600）。
- 模型认证健康：检查 OAuth 过期、可刷新即将过期的令牌、报告认证配置的冷却/禁用状态。
- 模型认证健康：检查 OAuth 过期，可刷新即将过期的 token，并报告认证配置文件冷却/禁用状态。
- 额外工作区目录检测（`~/openclaw`）。
- 启用沙箱时的沙箱镜像修复。
- 遗留服务迁移和额外 Gateway网关检测。
- Gateway网关运行时检查（服务已安装但未运行；缓存的 launchd 标签）。
- 渠道状态警告（从运行中的 Gateway网关探测）。
- 启用沙箱隔离时的沙箱镜像修复。
- 遗留服务迁移和额外 Gateway 网关检测。
- Gateway 网关运行时检查（服务已安装但未运行；缓存的 launchd 标签）。
- 渠道状态警告（从运行中的 Gateway 网关探测）。
- Supervisor 配置审计（launchd/systemd/schtasks）及可选修复。
- Gateway网关运行时最佳实践检查（Node vs Bun、版本管理器路径）。
- Gateway网关端口冲突诊断（默认 `18789`）。
- 开放 私信 策略的安全警告。
- 未设置 `gateway.auth.token` 时的 Gateway网关认证警告（本地模式；提供令牌生成）。
- Gateway 网关运行时最佳实践检查（Node vs Bun，版本管理器路径）。
- Gateway 网关端口冲突诊断（默认 `18789`）。
- 开放私信策略的安全警告。
- 未设置 `gateway.auth.token` 时的 Gateway 网关认证警告（本地模式；提供 token 生成）。
- Linux 上的 systemd linger 检查。
- 源码安装检查（pnpm workspace 不匹配、缺失 UI 资源、缺失 tsx 二进制文件）。
- 源码安装检查（pnpm workspace 不匹配、缺失 UI 资产、缺失 tsx 二进制文件）。
- 写入更新后的配置 + 向导元数据。
## 详细行为和原理
### 0) 可选更新（git 安装）
### 0）可选更新（git 安装）
如果这是一个 git 检出且 doctor 在交互模式下运行，它会在运行 doctor 之前提供更新（fetch/rebase/build）。
如果这是 git 检出且 doctor 以交互模式运行，它会在运行 doctor 之前提供更新（fetch/rebase/build）。
### 1) 配置规范化
### 1）配置规范化
如果配置包含遗留值格式（例如 `messages.ackReaction` 没有渠道特定的覆盖），doctor 会将其规范化为当前 schema。
如果配置包含遗留值形式（例如没有渠道特定覆盖的 `messages.ackReaction`），doctor 会将它们规范化为当前 schema。
### 2) 遗留配置键迁移
### 2）遗留配置键迁移
当配置包含已弃用的键时，其他命令会拒绝运行并要求你运行 `openclaw doctor`。
Doctor 将：
- 说明找到了哪些遗留键。
- 解释找到了哪些遗留键。
- 显示它应用的迁移。
- 使用更新后的 schema 重写 `~/.openclaw/openclaw.json`。
Gateway网关在启动时检测到遗留配置格式时也会自动运行 doctor 迁移，因此过时的配置无需手动干预即可修复。
Gateway 网关在检测到遗留配置格式时也会在启动时自动运行 doctor 迁移，因此过时的配置无需手动干预即可修复。
当前迁移：
@@ -127,110 +127,112 @@ Gateway网关在启动时检测到遗留配置格式时也会自动运行 doctor
- `agent.model`/`allowedModels`/`modelAliases`/`modelFallbacks`/`imageModelFallbacks`
→ `agents.defaults.models` + `agents.defaults.model.primary/fallbacks` + `agents.defaults.imageModel.primary/fallbacks`
### 2b) OpenCode Zen 提供商覆盖
### 2b）OpenCode Zen 提供商覆盖
如果你手动添加了 `models.providers.opencode`（或 `opencode-zen`），它会覆盖 `@mariozechner/pi-ai` 内置的 OpenCode Zen 目录。这可能会将所有模型强制指向单个 API 或将成本归零。Doctor 会发出警告，以便你移除覆盖并恢复按模型的 API 路由 + 成本。
如果你手动添加了 `models.providers.opencode`（或 `opencode-zen`），它会覆盖 `@mariozechner/pi-ai` 中内置的 OpenCode Zen 目录。这可能会强制将每个模型放到单个 API 上或将成本归零。Doctor 会发出警告，以便你可以移除覆盖并恢复每模型 API 路由 + 成本。
### 3) 遗留状态迁移（磁盘布局）
### 3）遗留状态迁移（磁盘布局）
Doctor 可以将旧版磁盘布局迁移到当前结构：
Doctor 可以将旧的磁盘布局迁移到当前结构：
- 会话存储 + 转录：
- 会话存储 + 记录：
- 从 `~/.openclaw/sessions/` 到 `~/.openclaw/agents/<agentId>/sessions/`
- 智能体目录：
- 从 `~/.openclaw/agent/` 到 `~/.openclaw/agents/<agentId>/agent/`
- WhatsApp 认证状态（Baileys）：
- 从遗留的 `~/.openclaw/credentials/*.json`（`oauth.json` 除外）
- 到 `~/.openclaw/credentials/whatsapp/<accountId>/...`（默认账户 ID：`default`）
- 从遗留的 `~/.openclaw/credentials/*.json`（除 `oauth.json` 外）
- 到 `~/.openclaw/credentials/whatsapp/<accountId>/...`（默认账户 id：`default`）
这些迁移尽力执行且幂等；当 doctor 保留任何遗留文件夹作为备份时会发出警告。Gateway网关/CLI 在启动时也会自动迁移遗留会话 + 智能体目录，使历史/认证/模型落入每个智能体的路径中，无需手动运行 doctor。WhatsApp 认证仅通过 `openclaw doctor` 进行迁移。
这些迁移是尽力而为且幂等的；当 doctor 将任何遗留文件夹作为备份保留时会发出警告。Gateway 网关/CLI 也会在启动时自动迁移遗留会话 + 智能体目录，因此历史/认证/模型会落在每智能体路径中，无需手动运行 doctor。WhatsApp 认证有意仅通过 `openclaw doctor` 迁移。
### 4) 状态完整性检查（会话持久化、路由和安全性）
### 4）状态完整性检查（会话持久化、路由和安全）
状态目录是运行的核心枢纽。如果它消失，你将丢失会话、凭据、日志和配置（除非你在其他地方有备份）。
状态目录是操作的核心。如果它消失，你会丢失会话、凭证、日志和配置（除非你在别处有备份）。
Doctor 检查：
- **状态目录缺失**：警告灾难性状态丢失，提示重新创建目录，并提醒无法恢复丢失的数据。
- **状态目录权限**：验证可写性；提供修复权限的选项（检测到所有者/组不匹配时发出 `chown` 提示）。
- **会话目录缺失**：`sessions/` 和会话存储目录是持久化历史记录和避免 `ENOENT` 崩溃所必需的。
- **转录不匹配**：当近期会话条目缺少转录文件时发出警告。
- **主会话"单行 JSONL"**：当主转录只有一行时标记（历史记录未在累积）。
- **多个状态目录**：当多个 `~/.openclaw` 文件夹存在于不同的 home 目录中，或 `OPENCLAW_STATE_DIR` 指向其他位置时发出警告（历史记录可能在不同安装间分裂）。
- **远程模式提醒**：如果 `gateway.mode=remote`，doctor 提醒你在远程主机上运行（状态存储在那里）。
- **配置文件权限**：当 `~/.openclaw/openclaw.json` 对组/其他用户可读时发出警告，并提供收紧为 `600` 的选项。
- **状态目录缺失**：警告灾难性状态丢失，提示重新创建目录，并提醒你它无法恢复丢失的数据。
- **状态目录权限**：验证可写性；提供修复权限（并在检测到所有者/组不匹配时发出 `chown` 提示）。
- **会话目录缺失**：`sessions/` 和会话存储目录是持久化历史和避免 `ENOENT` 崩溃所必需的。
- **记录不匹配**：当最近的会话条目缺少记录文件时发出警告。
- **主会话"1 行 JSONL"**：当主记录只有一行时标记（历史未累积）。
- **多个状态目录**：当多个 `~/.openclaw` 文件夹存在于不同 home 目录或当 `OPENCLAW_STATE_DIR` 指向别处时发出警告（历史可能在安装之间分裂）。
- **远程模式提醒**：如果 `gateway.mode=remote`，doctor 会提醒你在远程主机上运行它（状态在那里）。
- **配置文件权限**：当 `~/.openclaw/openclaw.json` 对组/其他用户可读时发出警告，并提供收紧到 `600` 的选项。
### 5) 模型认证健康（OAuth 过期）
### 5）模型认证健康（OAuth 过期）
Doctor 检查认证存储中的 OAuth 配置，当令牌即将过期/已过期时发出警告，并在安全时刷新它们。如果 Anthropic Claude Code 配置过时，它会建议运行 `claude setup-token`（或粘贴 setup-token）。刷新提示仅在交互运行（TTY）时出现；`--non-interactive` 跳过刷新尝试。
Doctor 检查认证存储中的 OAuth 配置文件，在 token 即将过期/已过期时发出警告，并在安全时刷新它们。如果 Anthropic Claude Code 配置文件过时，它会建议运行 `claude setup-token`（或粘贴 setup-token）。
刷新提示仅在交互运行（TTY）时出现；`--non-interactive` 跳过刷新尝试。
Doctor 还会报告由于以下原因暂时不可用的认证配置：
Doctor 还会报告由于以下原因暂时不可用的认证配置文件：
- 短期冷却（速率限制/超时/认证失败）
- 较长时间的禁用（账单/额度失败）
- 短冷却（速率限制/超时/认证失败）
- 长禁用（账单/信用失败）
### 6) Hooks 模型验证
### 6）Hooks 模型验证
如果设置了 `hooks.gmail.model`，doctor 会根据目录和允许列表验证模型引用，并在无法解析或被禁止时发出警告。
如果设置了 `hooks.gmail.model`，doctor 会根据目录和允许列表验证模型引用，并在无法解析或不允许时发出警告。
### 7) 沙箱镜像修复
### 7）沙箱镜像修复
当启用沙箱时，doctor 检查 Docker 镜像，并在当前镜像缺失时提供构建或切换到遗留名称的选项。
当启用沙箱隔离时，doctor 检查 Docker 镜像，并在当前镜像缺失时提供构建或切换到遗留名称的选项。
### 8) Gateway网关服务迁移和清理提示
### 8）Gateway 网关服务迁移和清理提示
Doctor 检测遗留 Gateway网关服务（launchd/systemd/schtasks），并提供删除它们并使用当前 Gateway网关端口安装 OpenClaw 服务的选项。它还可以扫描额外的类 Gateway网关服务并打印清理提示。以配置文件命名的 OpenClaw Gateway网关服务被视为一等公民，不会被标记为"额外"。
Doctor 检测遗留的 Gateway 网关服务（launchd/systemd/schtasks），并提供删除它们并使用当前 Gateway 网关端口安装 OpenClaw 服务的选项。它还可以扫描额外的类 Gateway 网关服务并打印清理提示。
配置文件命名的 OpenClaw Gateway 网关服务被视为一等公民，不会被标记为"额外的"。
### 9) 安全警告
### 9）安全警告
当提供商对 私信 开放且没有允许列表时，或当策略以危险方式配置时，doctor 会发出警告。
当提供商对私信开放而没有允许列表，或当策略以危险方式配置时，Doctor 会发出警告。
### 10) systemd linger（Linux）
### 10）systemd linger（Linux）
如果作为 systemd 用户服务运行，doctor 确保 linger 已启用，以便 Gateway网关在注销后保持运行。
如果作为 systemd 用户服务运行，doctor 确保启用 lingering，以便 Gateway 网关在注销后保持活动。
### 11) Skills 状态
### 11）Skills 状态
Doctor 打印当前工作区可用/缺失/受阻 Skills 的快速摘要。
Doctor 打印当前工作区符合条件/缺失/被阻止的 Skills 的快速摘要。
### 12) Gateway网关认证检查（本地令牌）
### 12）Gateway 网关认证检查（本地 token）
当本地 Gateway网关缺少 `gateway.auth` 时，doctor 发出警告并提供生成令牌的选项。使用 `openclaw doctor --generate-gateway-token` 在自动化中强制创建令牌。
当本地 Gateway 网关缺少 `gateway.auth` 时，Doctor 会发出警告并提供生成 token 的选项。使用 `openclaw doctor --generate-gateway-token` 在自动化中强制创建 token。
### 13) Gateway网关健康检查 + 重启
### 13）Gateway 网关健康检查 + 重启
Doctor 运行健康检查，并在 Gateway网关看起来不健康时提供重启选项。
Doctor 运行健康检查，并在 Gateway 网关看起来不健康时提供重启选项。
### 14) 渠道状态警告
### 14）渠道状态警告
如果 Gateway网关健康，doctor 运行渠道状态探测并报告警告及建议的修复方案。
如果 Gateway 网关健康，doctor 运行渠道状态探测并报告警告及建议的修复。
### 15) Supervisor 配置审计 + 修复
### 15）Supervisor 配置审计 + 修复
Doctor 检查已安装的 supervisor 配置（launchd/systemd/schtasks）是否有缺失或过时的默认值（例如 systemd 的 network-online 依赖和重启延迟）。当发现不匹配时，它会推荐更新并可以将服务文件/任务重写为当前默认值。
Doctor 检查已安装的 supervisor 配置（launchd/systemd/schtasks）是否有缺失或过时的默认值（例如 systemd network-online 依赖和重启延迟）。当发现不匹配时，它会推荐更新，并可以将服务文件/任务重写为当前默认值。
说明：
注意事项：
- `openclaw doctor` 在重写 supervisor 配置前会提示确认。
- `openclaw doctor` 在重写 supervisor 配置前提示。
- `openclaw doctor --yes` 接受默认修复提示。
- `openclaw doctor --repair` 无需提示即应用推荐修复。
- `openclaw doctor --repair` 无需提示应用推荐的修复。
- `openclaw doctor --repair --force` 覆盖自定义 supervisor 配置。
- 你始终可以通过 `openclaw gateway install --force` 强制完全重写。
### 16) Gateway网关运行时 + 端口诊断
### 16）Gateway 网关运行时 + 端口诊断
Doctor 检查服务运行时（PID、上次退出状态），并在服务已安装但实际未运行时发出警告。它还检查 Gateway网关端口（默认 `18789`）上的端口冲突并报告可能的原因（Gateway网关已在运行、SSH 隧道）。
Doctor 检查服务运行时（PID、上次退出状态），并在服务已安装但实际未运行时发出警告。它还检查 Gateway 网关端口（默认 `18789`）上的端口冲突，并报告可能的原因（Gateway 网关已在运行、SSH 隧道）。
### 17) Gateway网关运行时最佳实践
### 17）Gateway 网关运行时最佳实践
当 Gateway网关服务运行在 Bun 或版本管理器管理的 Node 路径（`nvm`、`fnm`、`volta`、`asdf` 等）上时，doctor 会发出警告。WhatsApp + Telegram 渠道需要 Node，而版本管理器路径在升级后可能会失效，因为服务不会加载你的 shell 初始化文件。Doctor 会在系统 Node 安装可用时提供迁移选项（Homebrew/apt/choco）。
当 Gateway 网关服务在 Bun 或版本管理器管理的 Node 路径（`nvm`、`fnm`、`volta`、`asdf` 等）上运行时，Doctor 会发出警告。WhatsApp + Telegram 渠道需要 Node，版本管理器路径在升级后可能会中断，因为服务不会加载你的 shell init。Doctor 会在可用时提供迁移到系统 Node 安装的选项（Homebrew/apt/choco）。
### 18) 配置写入 + 向导元数据
### 18）配置写入 + 向导元数据
Doctor 持久化所有配置更改，并记录向导元数据以标记 doctor 运行。
Doctor 持久化任何配置更改，并标记向导元数据以记录 doctor 运行。
### 19) 工作区提示（备份 + 记忆系统）
### 19）工作区提示（备份 + 记忆系统）
当缺少工作区记忆系统时，doctor 会建议添加，并在工作区尚未纳入 git 管理时打印备份提示。
当缺失时，Doctor 建议使用工作区记忆系统，并在工作区尚未在 git 下时打印备份提示。
参见 [/concepts/agent-workspace](/concepts/agent-workspace) 获取工作区结构和 git 备份的完整指南（推荐使用私有 GitHub 或 GitLab）。
参见 [/concepts/agent-workspace](/concepts/agent-workspace) 了解工作区结构和 git 备份的完整指南（推荐私有 GitHub 或 GitLab）。

38
docs/zh-CN/gateway/gateway-lock.md
View File

@@ -1,41 +1,41 @@
---
read_when:
- 运行或调试 Gateway网关进程时
- 调查单实例强制机制时
summary: Gateway网关单例守卫：通过 WebSocket 监听器绑定实现
title: Gateway网关锁
- 运行或调试 Gateway 网关进程
- 调查单实例强制执行
summary: 使用 WebSocket 监听器绑定的 Gateway 网关单例保护
title: Gateway 网关锁
x-i18n:
generated_at: "2026-02-01T20:25:58Z"
generated_at: "2026-02-03T07:47:52Z"
model: claude-opus-4-5
provider: pi
source_hash: 15fdfa066d1925da8b4632073a876709f77ca8d40e6828c174a30d953ba4f8e9
source_path: gateway/gateway-lock.md
workflow: 14
workflow: 15
---
# Gateway网关锁
# Gateway 网关锁
最后更新：2025-12-11
## 原因
- 确保同一主机上每个基础端口只运行一个 Gateway网关实例；额外的 Gateway网关必须使用隔离的配置文件和唯一端口。
- 在崩溃/SIGKILL 后不会留下过期的锁文件。
- 当控制端口已被占用时，快速失败并给出清晰的错误信息。
- 确保同一主机上每个基础端口只运行一个 Gateway 网关实例；额外的 Gateway 网关必须使用隔离的配置文件和唯一的端口。
- 在崩溃/SIGKILL 后不留下过时的锁文件。
- 当控制端口已被占用时快速失败并给出清晰的错误。
## 机制
- Gateway网关在启动时立即通过独占 TCP 监听器绑定 WebSocket 监听器（默认 `ws://127.0.0.1:18789`）。
- 如果绑定失败并返回 `EADDRINUSE`，启动时将抛出 `Gateway网关LockError("another gateway instance is already listening on ws://127.0.0.1:<port>")`。
- 操作系统会在进程以任何方式退出时自动释放监听器，包括崩溃和 SIGKILL——无需单独的锁文件或清理步骤。
- 关闭时，Gateway网关会关闭 WebSocket 服务器和底层 HTTP 服务器以及时释放端口。
- Gateway 网关在启动时立即使用独占 TCP 监听器绑定 WebSocket 监听器（默认 `ws://127.0.0.1:18789`）。
- 如果绑定因 `EADDRINUSE` 失败，启动会抛出 `GatewayLockError("another gateway instance is already listening on ws://127.0.0.1:<port>")`。
- 操作系统在任何进程退出时（包括崩溃和 SIGKILL）自动释放监听器——不需要单独的锁文件或清理步骤。
- 关闭时，Gateway 网关关闭 WebSocket 服务器和底层 HTTP 服务器以及时释放端口。
## 错误表现
## 错误表面
- 如果另一个进程持有该端口，启动时将抛出 `Gateway网关LockError("another gateway instance is already listening on ws://127.0.0.1:<port>")`。
- 其他绑定失败将表现为 `Gateway网关LockError("failed to bind gateway socket on ws://127.0.0.1:<port>: …")`。
- 如果另一个进程持有端口，启动会抛出 `GatewayLockError("another gateway instance is already listening on ws://127.0.0.1:<port>")`。
- 其他绑定失败会显示为 `GatewayLockError("failed to bind gateway socket on ws://127.0.0.1:<port>: …")`。
## 运维说明
- 如果端口被*其他*进程占用，错误信息相同；请释放该端口或使用 `openclaw gateway --port <port>` 选择另一个端口。
- macOS 应用在启动 Gateway网关之前仍会维护自己的轻量级 PID 守卫；运行时锁由 WebSocket 绑定强制执行。
- 如果端口被*另一个*进程占用，错误是相同的；释放端口或使用 `openclaw gateway --port <port>` 选择另一个端口。
- macOS 应用在启动 Gateway 网关之前仍维护自己的轻量级 PID 保护；运行时锁由 WebSocket 绑定强制执行。

34
docs/zh-CN/gateway/health.md
View File

@@ -4,39 +4,39 @@ read_when:
summary: 渠道连接的健康检查步骤
title: 健康检查
x-i18n:
generated_at: "2026-02-01T20:26:10Z"
generated_at: "2026-02-03T07:47:59Z"
model: claude-opus-4-5
provider: pi
source_hash: 74f242e98244c135e1322682ed6b67d70f3b404aca783b1bb5de96a27c2c1b01
source_path: gateway/health.md
workflow: 14
workflow: 15
---
# 健康检查（CLI）
验证渠道连接状态的简要指南，无需猜测。
验证渠道连接的简短指南，无需猜测。
## 快速检查
- `openclaw status` — 本地摘要：Gateway网关可达性/模式、更新提示、已关联渠道认证时长、会话 + 近期活动。
- `openclaw status --all` — 完整本地诊断（只读、带颜色、可安全粘贴用于调试）。
- `openclaw status --deep` — 还会探测运行中的 Gateway网关（支持时进行逐渠道探测）。
- `openclaw health --json` — 向运行中的 Gateway网关请求完整健康快照（仅限 WS；不直接访问 Baileys socket）。
- 在 WhatsApp/WebChat 中发送 `/status` 作为独立消息，可获取状态回复而不触发智能体。
- 日志：尾部查看 `/tmp/openclaw/openclaw-*.log` 并过滤 `web-heartbeat`、`web-reconnect`、`web-auto-reply`、`web-inbound`。
- `openclaw status` — 本地摘要：Gateway 网关可达性/模式、更新提示、已链接渠道认证时长、会话 + 最近活动。
- `openclaw status --all` — 完整本地诊断（只读、彩色、可安全粘贴用于调试）。
- `openclaw status --deep` — 还会探测运行中的 Gateway 网关（支持时进行每渠道探测）。
- `openclaw health --json` — 向运行中的 Gateway 网关请求完整健康快照（仅 WS；不直接访问 Baileys 套接字）。
- 在 WhatsApp/WebChat 中单独发送 `/status` 消息可获取状态回复，而不调用智能体。
- 日志：跟踪 `/tmp/openclaw/openclaw-*.log` 并过滤 `web-heartbeat`、`web-reconnect`、`web-auto-reply`、`web-inbound`。
## 深度诊断
- 磁盘上的凭证：`ls -l ~/.openclaw/credentials/whatsapp/<accountId>/creds.json`（修改时间应为近期）。
- 会话存储：`ls -l ~/.openclaw/agents/<agentId>/sessions/sessions.json`（路径可在配置中覆盖）。计数和近期接收者可通过 `status` 查看。
- 重新关联流程：当日志中出现状态码 409–515 或 `loggedOut` 时，执行 `openclaw channels logout && openclaw channels login --verbose`。（注意：QR 登录流程在配对后遇到状态码 515 时会自动重试一次。）
- 磁盘上的凭证：`ls -l ~/.openclaw/credentials/whatsapp/<accountId>/creds.json`（mtime 应该是最近的）。
- 会话存储：`ls -l ~/.openclaw/agents/<agentId>/sessions/sessions.json`（路径可在配置中覆盖）。计数和最近收件人通过 `status` 显示。
- 重新链接流程：当日志中出现状态码 409–515 或 `loggedOut` 时，执行 `openclaw channels logout && openclaw channels login --verbose`。（注意：配对后状态 515 时 QR 登录流程会自动重启一次。）
## 当出现故障时
- `logged out` 或状态码 409–515 → 使用 `openclaw channels logout` 然后 `openclaw channels login` 重新关联。
- Gateway网关不可达 → 启动它：`openclaw gateway --port 18789`（如果端口被占用，使用 `--force`）。
- 没有收到入站消息 → 确认已关联的手机在线且发送者已被允许（`channels.whatsapp.allowFrom`）；对于群聊，确保允许列表 + 提及规则匹配（`channels.whatsapp.groups`、`agents.list[].groupChat.mentionPatterns`）。
- `logged out` 或状态 409–515 → 使用 `openclaw channels logout` 然后 `openclaw channels login` 重新链接。
- Gateway 网关不可达 → 启动它：`openclaw gateway --port 18789`（如果端口被占用则使用 `--force`）。
- 没有入站消息 → 确认已链接的手机在线且发送者被允许（`channels.whatsapp.allowFrom`）；对于群聊，确保允许列表 + 提及规则匹配（`channels.whatsapp.groups`、`agents.list[].groupChat.mentionPatterns`）。
## 专用 "health" 命令
## 专用"health"命令
`openclaw health --json` 向运行中的 Gateway网关请求其健康快照（CLI 不直接访问渠道 socket）。它会报告已关联凭证/认证时长（如可用）、逐渠道探测摘要、会话存储摘要和探测耗时。如果 Gateway网关不可达或探测失败/超时，则以非零状态码退出。使用 `--timeout <ms>` 可覆盖默认的 10 秒超时。
`openclaw health --json` 向运行中的 Gateway 网关请求其健康快照（CLI 不直接访问渠道套接字）。它报告已链接凭证/认证时长（如可用）、每渠道探测摘要、会话存储摘要和探测持续时间。如果 Gateway 网关不可达或探测失败/超时，它以非零退出。使用 `--timeout <ms>` 覆盖默认的 10 秒。

Some files were not shown because too many files have changed in this diff Show More