mirror of
https://github.com/sipeed/picoclaw.git
synced 2026-06-12 18:08:54 +00:00
docs: fix inaccuracies, add translations, and expand channel docs (#1837)
## Config field fixes (cross-verified against Go source) - MaixCam: server_address → host + port - IRC: use_tls → tls, channels_to_join → channels (all 6 languages) - WeCom AI Bot: callback port 18791 → 18790 - credential_encryption: base_url → api_base, add required model field, remove incorrect passphrase-only mode docs - providers.md: agents.defaults.model → model_name (×4), remove non-existent session.backlog_limit - migration guide, troubleshooting: agents.defaults.model → model_name - ANTIGRAVITY_AUTH: fix file path, Go 1.21 → 1.25, model → model_name - spawn-tasks: fix truncated file, add Heartbeat introduction - tools_configuration: add Tavily/SearXNG/GLMSearch, exec allow_remote/ timeout_seconds/custom_allow_patterns, cron allow_command, skills github/search_cache, clawhub timeout/max_zip_size/max_response_size - configuration: fix builtin skills path (build-time embedded, not cwd), HEARTBEAT.md marked auto-generated ## Broken link fixes (15 total) - chat-apps.md: WeCom/Matrix links with wrong relative paths - providers.md: migration link with extra docs/ prefix - hardware-compatibility.md: README links with wrong depth (all 5 langs) - chat-apps.md: WhatsApp dead links → anchor links (zh/ja) ## Getting-started accuracy - README (all 6 langs): add picoclaw.io as recommended download, add missing picoclaw model CLI command - docker.md: clarify first-run trigger condition (all 6 langs) - configuration.md: fix builtin skills path description (all 6 langs) ## QQ channel - Add quick setup via q.qq.com/qqbot/openclaw (one-click bot creation) - Add manual setup as fallback (all 6 languages) ## Feishu channel - Update setup flow: WebSocket/SDK mode, no webhook URL needed - Preserve Lark international domain note (all 6 languages) ## chat-apps.md - Add Feishu, Slack, IRC, OneBot detail sections (all 6 languages) - Add MaixCam section to ja/fr/pt-br/vi - Fix all channel doc links to point to correct language version ## New translations (25 files, 5 docs × 5 languages) debug.md, credential_encryption.md, hardware-compatibility.md, ANTIGRAVITY_AUTH.md, ANTIGRAVITY_USAGE.md → zh/ja/fr/pt-br/vi ## Channel docs (6 languages each, 60 new files) telegram, discord, qq, feishu, maixcam, dingtalk, line, slack, onebot, wecom/wecom_aibot, wecom/wecom_app, wecom/wecom_bot Co-authored-by: BeaconCat <BeaconCat@users.noreply.github.com>
This commit is contained in:
BeaconCat
@@ -0,0 +1,158 @@
|
||||
> 返回 [README](../../README.zh.md)
|
||||
|
||||
# 凭据加密
|
||||
|
||||
PicoClaw 支持对 `model_list` 配置条目中的 `api_key` 值进行加密。
|
||||
加密后的密钥以 `enc://<base64>` 字符串形式存储，并在启动时自动解密。
|
||||
|
||||
---
|
||||
|
||||
## 快速开始
|
||||
|
||||
**1. 设置密码短语**
|
||||
|
||||
```bash
|
||||
export PICOCLAW_KEY_PASSPHRASE="your-passphrase"
|
||||
```
|
||||
|
||||
**2. 加密 API 密钥**
|
||||
|
||||
运行 `picoclaw onboard` — 它会提示你输入密码短语并生成 SSH 密钥，
|
||||
然后在下一次 `SaveConfig` 调用时自动重新加密配置中所有明文 `api_key` 条目。生成的 `enc://` 值如下所示：
|
||||
|
||||
```
|
||||
enc://AAAA...base64...
|
||||
```
|
||||
|
||||
**3. 将输出粘贴到你的配置中**
|
||||
|
||||
```json
|
||||
{
|
||||
"model_list": [
|
||||
{
|
||||
"model_name": "gpt-4o",
|
||||
"model": "openai/gpt-4o",
|
||||
"api_key": "enc://AAAA...base64...",
|
||||
"api_base": "https://api.openai.com/v1"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 支持的 `api_key` 格式
|
||||
|
||||
| 格式 | 示例 | 行为 |
|
||||
|------|------|------|
|
||||
| 明文 | `sk-abc123` | 直接使用 |
|
||||
| 文件引用 | `file://openai.key` | 从配置文件所在目录读取内容 |
|
||||
| 加密 | `enc://<base64>` | 启动时使用 `PICOCLAW_KEY_PASSPHRASE` 解密 |
|
||||
| 空值 | `""` | 原样传递（用于 `auth_method: oauth`） |
|
||||
|
||||
---
|
||||
|
||||
## 加密设计
|
||||
|
||||
### 密钥派生
|
||||
|
||||
加密使用 **HKDF-SHA256**，并以 SSH 私钥作为第二因子。
|
||||
|
||||
```
|
||||
sshHash = SHA256(ssh_private_key_file_bytes)
|
||||
ikm = HMAC-SHA256(key=sshHash, message=passphrase)
|
||||
aes_key = HKDF-SHA256(ikm, salt, info="picoclaw-credential-v1", 32 bytes)
|
||||
```
|
||||
|
||||
### 加密
|
||||
|
||||
```
|
||||
AES-256-GCM(key=aes_key, nonce=random[12], plaintext=api_key)
|
||||
```
|
||||
|
||||
### 传输格式
|
||||
|
||||
```
|
||||
enc://<base64( salt[16] + nonce[12] + ciphertext )>
|
||||
```
|
||||
|
||||
| 字段 | 大小 | 描述 |
|
||||
|------|------|------|
|
||||
| `salt` | 16 字节 | 每次加密随机生成；输入 HKDF |
|
||||
| `nonce` | 12 字节 | 每次加密随机生成；AES-GCM IV |
|
||||
| `ciphertext` | 可变 | AES-256-GCM 密文 + 16 字节认证标签 |
|
||||
|
||||
GCM 认证标签会自动附加到密文之后。任何篡改都会导致解密失败并报错，而不是返回损坏的明文。
|
||||
|
||||
### 性能
|
||||
|
||||
| 操作 | 耗时 (ARM Cortex-A) |
|
||||
|------|---------------------|
|
||||
| 密钥派生 (HKDF) | < 1 ms |
|
||||
| AES-256-GCM 解密 | < 1 ms |
|
||||
| **启动总开销** | **每个密钥 < 2 ms** |
|
||||
|
||||
---
|
||||
|
||||
## 使用 SSH 密钥的双因子安全
|
||||
|
||||
当提供 SSH 私钥时，破解加密需要**同时具备**：
|
||||
|
||||
1. **密码短语** (`PICOCLAW_KEY_PASSPHRASE`)
|
||||
2. **SSH 私钥文件**
|
||||
|
||||
这意味着仅泄露配置文件不足以恢复 API 密钥，即使密码短语较弱也是如此。SSH 密钥贡献 256 位熵（Ed25519），与密码短语强度无关。
|
||||
|
||||
### 威胁模型
|
||||
|
||||
| 攻击者拥有 | 能否解密？ |
|
||||
|------------|-----------|
|
||||
| 仅配置文件 | 否 — 需要密码短语 + SSH 密钥 |
|
||||
| 仅 SSH 密钥 | 否 — 需要密码短语 |
|
||||
| 仅密码短语 | 否 — 需要 SSH 密钥 |
|
||||
| 配置文件 + SSH 密钥 + 密码短语 | 是 — 完全泄露 |
|
||||
|
||||
---
|
||||
|
||||
## 环境变量
|
||||
|
||||
| 变量 | 是否必需 | 描述 |
|
||||
|------|----------|------|
|
||||
| `PICOCLAW_KEY_PASSPHRASE` | 是（用于 `enc://`） | 用于密钥派生的密码短语 |
|
||||
| `PICOCLAW_SSH_KEY_PATH` | 否 | SSH 私钥路径。如未设置，自动从 `~/.ssh/picoclaw_ed25519.key` 检测 |
|
||||
|
||||
### SSH 密钥自动检测
|
||||
|
||||
如果未设置 `PICOCLAW_SSH_KEY_PATH`，PicoClaw 会查找专用密钥：
|
||||
|
||||
```
|
||||
~/.ssh/picoclaw_ed25519.key
|
||||
```
|
||||
|
||||
此专用文件避免与用户现有的 SSH 密钥冲突。
|
||||
运行 `picoclaw onboard` 可自动生成该密钥。
|
||||
|
||||
`os.UserHomeDir()` 用于跨平台主目录解析（在 Windows 上读取 `USERPROFILE`，在 Unix/macOS 上读取 `HOME`）。
|
||||
|
||||
> **注意：** SSH 密钥文件是凭据加密的必要条件。如果未找到密钥且未设置 `PICOCLAW_SSH_KEY_PATH`，加密/解密将失败。运行 `picoclaw onboard` 可自动生成密钥。
|
||||
|
||||
---
|
||||
|
||||
## 迁移
|
||||
|
||||
由于唯一的密钥材料是 `PICOCLAW_KEY_PASSPHRASE` 和 SSH 私钥文件，迁移非常简单：
|
||||
|
||||
1. 将配置文件复制到新机器。
|
||||
2. 将 `PICOCLAW_KEY_PASSPHRASE` 设置为相同的值。
|
||||
3. 将 SSH 私钥文件复制到相同路径（或将 `PICOCLAW_SSH_KEY_PATH` 设置为新位置）。
|
||||
|
||||
无需重新加密。
|
||||
|
||||
---
|
||||
|
||||
## 安全注意事项
|
||||
|
||||
- **密码短语和 SSH 密钥都是必需的。** SSH 密钥作为第二因子 — 没有它，加密/解密将失败。如果密钥不存在，运行 `picoclaw onboard` 生成。
|
||||
- **SSH 密钥在运行时为只读。** PicoClaw 不会写入或修改 SSH 密钥文件。
|
||||
- **仍然支持明文密钥。** 不使用 `enc://` 的现有配置不受影响。
|
||||
- **`enc://` 格式通过版本控制**，通过 HKDF `info` 字段（`picoclaw-credential-v1`）实现，允许未来升级算法而不破坏现有加密值。
|
||||
Reference in New Issue
Block a user