docs: sync with goclaw source changes c083622f..76385f2f (EN+VI+ZH) (#50)

thieung · web-flow · commit e79556f56958 · 2026-04-07T01:29:55.000+07:00
- channels/telegram: add group-to-supergroup auto-migration section
- providers/openrouter: add identification headers (HTTP-Referer, X-Title)
- core-concepts/tools-overview: add deterministic ordering for prompt caching,
  hardened exec exemption matching (all-or-nothing, path traversal block, quote strip)
diff --git a/channels/telegram.md b/channels/telegram.md
@@ -291,6 +291,16 @@ Each Telegram instance maintains an isolated HTTP transport — no shared connec
 }
 ```
 
+## Group-to-Supergroup Migration
+
+When a Telegram group is upgraded to a supergroup, the chat ID changes. GoClaw handles this automatically:
+
+- **Inbound detection** — When a `MigrateToChatID` message arrives, GoClaw updates all DB references (paired_devices, sessions, channel_contacts) atomically and invalidates in-memory caches
+- **Send-path retry** — If a send fails because the group was migrated, GoClaw detects the new chat ID from the Telegram API error, updates DB, and retries the send automatically
+- **Idempotent** — Safe to trigger multiple times; duplicate migrations are no-ops
+
+No configuration needed. Check logs for `telegram: migrating group chat` entries if troubleshooting.
+
 ## Troubleshooting
 
 | Issue | Solution |
@@ -308,4 +318,4 @@ Each Telegram instance maintains an isolated HTTP transport — no shared connec
 - [Browser Pairing](/channel-browser-pairing) — Pairing flow
 - [Sessions & History](/sessions-and-history) — Conversation history
 
-<!-- goclaw-source: c5bfbc96 | updated: 2026-04-02 -->
+<!-- goclaw-source: 76385f2f | updated: 2026-04-07 -->
diff --git a/core-concepts/tools-overview.md b/core-concepts/tools-overview.md
@@ -95,6 +95,10 @@ GoClaw registers aliases so agents can reference tools by alternative names. Thi
 
 Aliases appear as one-line descriptions in the system prompt. They are not separate tools — calling an alias invokes the underlying tool.
 
+### Deterministic Ordering
+
+All tool names, aliases, and MCP tool descriptions are sorted lexicographically before being included in the system prompt. This ensures identical prompt prefixes across requests, maximizing LLM prompt cache hit rates (Anthropic and OpenAI cache by exact prefix match).
+
 ## Policy Engine
 
 Beyond profiles, a 7-step policy engine gives fine-grained control:
@@ -184,6 +188,16 @@ Admins can disable specific groups per agent:
 }
 ```
 
+### Hardened Exemption Matching
+
+When a shell command matches a deny pattern, GoClaw checks path exemptions (e.g., `.goclaw/skills-store/`). The exemption logic is strict:
+
+- **All-or-nothing** — Every field in the command that triggers the deny pattern must be individually covered by an exemption. A single unexempted field blocks the entire command
+- **Path traversal blocked** — Fields containing `..` are never exempt, preventing exemption escape via `../../etc/passwd`
+- **Quote stripping** — Surrounding quotes (`"`, `'`) are stripped before matching, since LLMs often quote paths
+
+This prevents pipe/comment bypass attacks like `cat /app/data/skills-store/tool.py | cat /app/data/secret` — the second field matches deny but has no exemption, so the entire command is blocked.
+
 The `tools.exec_approval` setting adds an additional approval layer (`full`, `light`, or `none`).
 
 ## spawn — Subagent Orchestration
@@ -255,4 +269,4 @@ All parameters are optional — defaults apply when not configured.
 - [Multi-Tenancy](/multi-tenancy) — Per-user tool access and isolation
 - [Custom Tools](/custom-tools) — Build your own tools
 
-<!-- goclaw-source: c083622f | updated: 2026-04-05 -->
+<!-- goclaw-source: 76385f2f | updated: 2026-04-07 -->
diff --git a/providers/openrouter.md b/providers/openrouter.md
@@ -62,6 +62,17 @@ To set a default model for OpenRouter in your agent config:
 }
 ```
 
+## Identification Headers
+
+GoClaw automatically sends identification headers with every OpenRouter API request:
+
+| Header | Value | Purpose |
+|---|---|---|
+| `HTTP-Referer` | `https://goclaw.sh` | Site identification for OpenRouter rankings |
+| `X-Title` | `GoClaw` | App name shown in OpenRouter analytics |
+
+These headers are sent for both config-file and dashboard-registered OpenRouter providers. No configuration needed — they are applied automatically.
+
 ## Supported Features
 
 OpenRouter passes through most features to the underlying model provider. Availability depends on the model:
@@ -90,4 +101,4 @@ OpenRouter passes through most features to the underlying model provider. Availa
 - [OpenAI](/provider-openai) — direct OpenAI integration
 - [Overview](/providers-overview) — provider architecture and retry logic
 
-<!-- goclaw-source: 57754a5 | updated: 2026-03-18 -->
+<!-- goclaw-source: 76385f2f | updated: 2026-04-07 -->
diff --git a/vi/channels/telegram.md b/vi/channels/telegram.md
@@ -295,6 +295,16 @@ Mỗi Telegram instance duy trì HTTP transport riêng biệt — không share c
 }
 ```
 
+## Chuyển đổi Group sang Supergroup
+
+Khi một Telegram group được nâng cấp thành supergroup, chat ID sẽ thay đổi. GoClaw xử lý tự động:
+
+- **Phát hiện tin nhắn đến** — Khi nhận được message `MigrateToChatID`, GoClaw cập nhật tất cả tham chiếu DB (paired_devices, sessions, channel_contacts) atomically và xóa cache trong bộ nhớ
+- **Retry khi gửi** — Nếu gửi tin thất bại do group đã migrate, GoClaw phát hiện chat ID mới từ Telegram API error, cập nhật DB và tự động gửi lại
+- **Idempotent** — An toàn khi kích hoạt nhiều lần; các migration trùng lặp là no-op
+
+Không cần cấu hình. Kiểm tra log với `telegram: migrating group chat` nếu cần troubleshoot.
+
 ## Xử lý sự cố
 
 | Vấn đề | Giải pháp |
@@ -312,4 +322,4 @@ Mỗi Telegram instance duy trì HTTP transport riêng biệt — không share c
 - [Browser Pairing](/channel-browser-pairing) — Luồng pairing
 - [Sessions & History](/sessions-and-history) — Lịch sử cuộc trò chuyện
 
-<!-- goclaw-source: c5bfbc96 | cập nhật: 2026-04-02 -->
+<!-- goclaw-source: 76385f2f | cập nhật: 2026-04-07 -->
diff --git a/vi/core-concepts/tools-overview.md b/vi/core-concepts/tools-overview.md
@@ -97,6 +97,10 @@ GoClaw đăng ký alias để agent có thể tham chiếu tool bằng tên khá
 
 Alias xuất hiện dưới dạng mô tả một dòng trong system prompt. Chúng không phải tool riêng biệt — gọi alias sẽ kích hoạt tool gốc.
 
+### Sắp xếp xác định (Deterministic Ordering)
+
+Tất cả tên tool, alias và mô tả MCP tool được sắp xếp theo thứ tự chữ cái trước khi đưa vào system prompt. Điều này đảm bảo prompt prefix giống hệt nhau giữa các request, tối đa hóa tỷ lệ cache hit của LLM prompt (Anthropic và OpenAI cache theo exact prefix match).
+
 ## Policy Engine
 
 Ngoài profile, policy engine 7 bước cho phép kiểm soát chi tiết:
@@ -186,6 +190,16 @@ Admin có thể tắt nhóm cụ thể theo từng agent:
 }
 ```
 
+### Kiểm tra Exemption nghiêm ngặt
+
+Khi lệnh shell khớp deny pattern, GoClaw kiểm tra path exemption (ví dụ: `.goclaw/skills-store/`). Logic exemption rất chặt chẽ:
+
+- **Tất cả hoặc không** — Mọi field trong lệnh khớp deny pattern đều phải được exemption riêng lẻ. Một field không được exempt sẽ chặn toàn bộ lệnh
+- **Chặn path traversal** — Field chứa `..` không bao giờ được exempt, ngăn chặn escape qua `../../etc/passwd`
+- **Loại bỏ dấu ngoặc** — Dấu ngoặc bao quanh (`"`, `'`) được loại trước khi so khớp, vì LLM thường đặt path trong ngoặc
+
+Điều này ngăn chặn tấn công bypass qua pipe/comment như `cat /app/data/skills-store/tool.py | cat /app/data/secret` — field thứ hai khớp deny nhưng không có exemption, nên toàn bộ lệnh bị chặn.
+
 Cài đặt `tools.exec_approval` thêm một lớp phê duyệt bổ sung (`full`, `light`, hoặc `none`).
 
 ## spawn — Điều phối Subagent
@@ -257,4 +271,4 @@ Tất cả tham số đều tùy chọn — giá trị mặc định áp dụng
 - [Multi-Tenancy](/multi-tenancy) — Truy cập tool per-user và cách ly
 - [Custom Tools](/custom-tools) — Xây dựng tool của riêng bạn
 
-<!-- goclaw-source: c083622f | cập nhật: 2026-04-05 -->
+<!-- goclaw-source: 76385f2f | cập nhật: 2026-04-07 -->
diff --git a/vi/providers/openrouter.md b/vi/providers/openrouter.md
@@ -64,6 +64,17 @@ Logic `resolveModel()` của GoClaw áp dụng riêng cho OpenRouter:
 }
 ```
 
+## Header nhận dạng
+
+GoClaw tự động gửi header nhận dạng với mọi request đến OpenRouter API:
+
+| Header | Giá trị | Mục đích |
+|---|---|---|
+| `HTTP-Referer` | `https://goclaw.sh` | Nhận dạng site cho bảng xếp hạng OpenRouter |
+| `X-Title` | `GoClaw` | Tên app hiển thị trong OpenRouter analytics |
+
+Các header này được gửi cho cả provider cấu hình qua config-file và dashboard. Không cần cấu hình — tự động áp dụng.
+
 ## Tính năng được hỗ trợ
 
 OpenRouter chuyển tiếp hầu hết tính năng đến provider model bên dưới. Tính khả dụng phụ thuộc vào model:
@@ -92,4 +103,4 @@ OpenRouter chuyển tiếp hầu hết tính năng đến provider model bên d
 - [OpenAI](/provider-openai) — tích hợp trực tiếp OpenAI
 - [Tổng quan](/providers-overview) — kiến trúc provider và retry logic
 
-<!-- goclaw-source: 57754a5 | cập nhật: 2026-03-18 -->
+<!-- goclaw-source: 76385f2f | cập nhật: 2026-04-07 -->
diff --git a/zh/channels/telegram.md b/zh/channels/telegram.md
@@ -295,6 +295,16 @@ Writer 是允许执行敏感命令（`/reset`、文件写入）的群组成员
 }
 ```
 
+## Group 升级为 Supergroup
+
+当 Telegram group 升级为 supergroup 时，chat ID 会改变。GoClaw 自动处理此过程：
+
+- **入站检测** — 收到 `MigrateToChatID` 消息时，GoClaw 原子性更新所有 DB 引用（paired_devices、sessions、channel_contacts）并清除内存缓存
+- **发送重试** — 若发送失败（因 group 已迁移），GoClaw 从 Telegram API 错误中检测新 chat ID，更新 DB 并自动重试
+- **幂等** — 多次触发安全；重复迁移为无操作
+
+无需配置。排查时查看日志中的 `telegram: migrating group chat` 条目。
+
 ## 故障排查
 
 | 问题 | 解决方案 |
@@ -312,4 +322,4 @@ Writer 是允许执行敏感命令（`/reset`、文件写入）的群组成员
 - [Browser Pairing](/channel-browser-pairing) — 配对流程
 - [Sessions & History](/sessions-and-history) — 会话历史
 
-<!-- goclaw-source: c5bfbc96 | 更新: 2026-04-02 -->
+<!-- goclaw-source: 76385f2f | 更新: 2026-04-07 -->
diff --git a/zh/core-concepts/tools-overview.md b/zh/core-concepts/tools-overview.md
@@ -97,6 +97,10 @@ GoClaw 注册别名，让 agent 可以用替代名称引用工具。这实现了
 
 别名在系统提示词中显示为单行描述。它们不是独立工具——调用别名会调用底层工具。
 
+### 确定性排序
+
+所有工具名称、别名和 MCP 工具描述在包含到系统提示词之前按字典序排序。这确保了跨请求的相同提示词前缀，最大化 LLM 提示词缓存命中率（Anthropic 和 OpenAI 按精确前缀匹配缓存）。
+
 ## 策略引擎
 
 除了 profile，7 步策略引擎提供精细控制：
@@ -186,6 +190,16 @@ GoClaw 注册别名，让 agent 可以用替代名称引用工具。这实现了
 }
 ```
 
+### 强化豁免匹配
+
+当 shell 命令匹配拒绝模式时，GoClaw 会检查路径豁免（如 `.goclaw/skills-store/`）。豁免逻辑非常严格：
+
+- **全部或无** — 命令中触发拒绝模式的每个字段都必须单独被豁免覆盖。一个未豁免的字段将阻止整个命令
+- **阻止路径遍历** — 包含 `..` 的字段永远不会被豁免，防止通过 `../../etc/passwd` 绕过
+- **去除引号** — 匹配前去除包围的引号（`"`、`'`），因为 LLM 经常给路径加引号
+
+这可防止 pipe/注释绕过攻击，如 `cat /app/data/skills-store/tool.py | cat /app/data/secret` — 第二个字段匹配拒绝模式但没有豁免，因此整个命令被阻止。
+
 `tools.exec_approval` 设置添加额外的审批层（`full`、`light` 或 `none`）。
 
 ## spawn — 子 Agent 编排
@@ -253,4 +267,4 @@ GoClaw 追踪每个 session 中每个工具的执行时间。如果工具调用
 - [多租户](/multi-tenancy) — 每用户工具访问和隔离
 - [自定义工具](/custom-tools) — 构建你自己的工具
 
-<!-- goclaw-source: c083622f | 更新: 2026-04-05 -->
+<!-- goclaw-source: 76385f2f | 更新: 2026-04-07 -->
diff --git a/zh/providers/openrouter.md b/zh/providers/openrouter.md
@@ -64,6 +64,17 @@ GoClaw 的 `resolveModel()` 逻辑专门针对 OpenRouter：
 }
 ```
 
+## 标识 Header
+
+GoClaw 自动在每个 OpenRouter API 请求中发送标识 header：
+
+| Header | 值 | 用途 |
+|---|---|---|
+| `HTTP-Referer` | `https://goclaw.sh` | OpenRouter 排名的站点标识 |
+| `X-Title` | `GoClaw` | OpenRouter analytics 中显示的应用名称 |
+
+这些 header 同时适用于通过 config 文件和控制台注册的 OpenRouter provider。无需配置——自动应用。
+
 ## 支持的功能
 
 OpenRouter 将大多数功能透传给底层模型 provider，可用性取决于模型：
@@ -92,4 +103,4 @@ OpenRouter 将大多数功能透传给底层模型 provider，可用性取决于
 - [OpenAI](/provider-openai) — 直接 OpenAI 集成
 - [概览](/providers-overview) — provider 架构和重试逻辑
 
-<!-- goclaw-source: 57754a5 | 更新: 2026-03-18 -->
+<!-- goclaw-source: 76385f2f | 更新: 2026-04-07 -->
