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,159 @@
|
||||
> Voltar ao [README](../../README.pt-br.md)
|
||||
|
||||
# Criptografia de Credenciais
|
||||
|
||||
O PicoClaw suporta a criptografia de valores `api_key` nas entradas de configuração `model_list`.
|
||||
As chaves criptografadas são armazenadas como strings `enc://<base64>` e descriptografadas automaticamente na inicialização.
|
||||
|
||||
---
|
||||
|
||||
## Início Rápido
|
||||
|
||||
**1. Defina sua frase secreta**
|
||||
|
||||
```bash
|
||||
export PICOCLAW_KEY_PASSPHRASE="your-passphrase"
|
||||
```
|
||||
|
||||
**2. Criptografe uma chave de API**
|
||||
|
||||
Execute `picoclaw onboard` — ele solicita sua frase secreta e gera a chave SSH,
|
||||
depois recriptografa automaticamente quaisquer entradas `api_key` em texto simples na sua configuração
|
||||
na próxima chamada `SaveConfig`. O valor `enc://` resultante será semelhante a:
|
||||
|
||||
```
|
||||
enc://AAAA...base64...
|
||||
```
|
||||
|
||||
**3. Cole a saída na sua configuração**
|
||||
|
||||
```json
|
||||
{
|
||||
"model_list": [
|
||||
{
|
||||
"model_name": "gpt-4o",
|
||||
"model": "openai/gpt-4o",
|
||||
"api_key": "enc://AAAA...base64...",
|
||||
"api_base": "https://api.openai.com/v1"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Formatos de `api_key` Suportados
|
||||
|
||||
| Formato | Exemplo | Comportamento |
|
||||
|---------|---------|---------------|
|
||||
| Texto simples | `sk-abc123` | Usado como está |
|
||||
| Referência de arquivo | `file://openai.key` | Conteúdo lido do mesmo diretório do arquivo de configuração |
|
||||
| Criptografado | `enc://<base64>` | Descriptografado na inicialização usando `PICOCLAW_KEY_PASSPHRASE` |
|
||||
| Vazio | `""` | Passado sem alteração (usado com `auth_method: oauth`) |
|
||||
|
||||
---
|
||||
|
||||
## Design Criptográfico
|
||||
|
||||
### Derivação de Chave
|
||||
|
||||
A criptografia utiliza **HKDF-SHA256** com uma chave privada SSH como segundo fator.
|
||||
|
||||
```
|
||||
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)
|
||||
```
|
||||
|
||||
### Criptografia
|
||||
|
||||
```
|
||||
AES-256-GCM(key=aes_key, nonce=random[12], plaintext=api_key)
|
||||
```
|
||||
|
||||
### Formato de Transmissão
|
||||
|
||||
```
|
||||
enc://<base64( salt[16] + nonce[12] + ciphertext )>
|
||||
```
|
||||
|
||||
| Campo | Tamanho | Descrição |
|
||||
|-------|---------|-----------|
|
||||
| `salt` | 16 bytes | Aleatório por criptografia; alimentado no HKDF |
|
||||
| `nonce` | 12 bytes | Aleatório por criptografia; IV do AES-GCM |
|
||||
| `ciphertext` | variável | Texto cifrado AES-256-GCM + tag de autenticação de 16 bytes |
|
||||
|
||||
O tag de autenticação GCM é anexado automaticamente ao texto cifrado. Qualquer adulteração faz com que a descriptografia falhe com um erro em vez de retornar texto simples corrompido.
|
||||
|
||||
### Desempenho
|
||||
|
||||
| Operação | Tempo (ARM Cortex-A) |
|
||||
|----------|----------------------|
|
||||
| Derivação de chave (HKDF) | < 1 ms |
|
||||
| Descriptografia AES-256-GCM | < 1 ms |
|
||||
| **Sobrecarga total na inicialização** | **< 2 ms por chave** |
|
||||
|
||||
---
|
||||
|
||||
## Segurança de Dois Fatores com Chave SSH
|
||||
|
||||
Quando uma chave privada SSH é fornecida, quebrar a criptografia requer **ambos**:
|
||||
|
||||
1. A **frase secreta** (`PICOCLAW_KEY_PASSPHRASE`)
|
||||
2. O **arquivo de chave privada SSH**
|
||||
|
||||
Isso significa que um arquivo de configuração vazado sozinho não é suficiente para recuperar a chave de API, mesmo que a frase secreta seja fraca. A chave SSH contribui com 256 bits de entropia (Ed25519) independentemente da força da frase secreta.
|
||||
|
||||
### Modelo de Ameaça
|
||||
|
||||
| O que o atacante possui | Pode descriptografar? |
|
||||
|------------------------|----------------------|
|
||||
| Apenas o arquivo de configuração | Não — necessita da frase secreta + chave SSH |
|
||||
| Apenas a chave SSH | Não — necessita da frase secreta |
|
||||
| Apenas a frase secreta | Não — necessita da chave SSH |
|
||||
| Arquivo de configuração + chave SSH + frase secreta | Sim — comprometimento total |
|
||||
|
||||
---
|
||||
|
||||
## Variáveis de Ambiente
|
||||
|
||||
| Variável | Obrigatório | Descrição |
|
||||
|----------|-------------|-----------|
|
||||
| `PICOCLAW_KEY_PASSPHRASE` | Sim (para `enc://`) | Frase secreta usada para derivação de chave |
|
||||
| `PICOCLAW_SSH_KEY_PATH` | Não | Caminho para a chave privada SSH. Se não definido, detecta automaticamente em `~/.ssh/picoclaw_ed25519.key` |
|
||||
|
||||
### Detecção Automática da Chave SSH
|
||||
|
||||
Se `PICOCLAW_SSH_KEY_PATH` não estiver definido, o PicoClaw procura a chave dedicada:
|
||||
|
||||
```
|
||||
~/.ssh/picoclaw_ed25519.key
|
||||
```
|
||||
|
||||
Este arquivo dedicado evita conflitos com as chaves SSH existentes do usuário.
|
||||
Execute `picoclaw onboard` para gerá-lo automaticamente.
|
||||
|
||||
`os.UserHomeDir()` é usado para resolução multiplataforma do diretório home (lê `USERPROFILE` no Windows, `HOME` no Unix/macOS).
|
||||
|
||||
> **Nota:** Um arquivo de chave SSH é obrigatório para a criptografia de credenciais. Se nenhuma chave for encontrada e `PICOCLAW_SSH_KEY_PATH` não estiver definido, a criptografia/descriptografia falhará. Execute `picoclaw onboard` para gerar a chave automaticamente.
|
||||
|
||||
---
|
||||
|
||||
## Migração
|
||||
|
||||
Como os únicos materiais secretos são `PICOCLAW_KEY_PASSPHRASE` e o arquivo de chave privada SSH, a migração é simples:
|
||||
|
||||
1. Copie o arquivo de configuração para a nova máquina.
|
||||
2. Defina `PICOCLAW_KEY_PASSPHRASE` com o mesmo valor.
|
||||
3. Copie o arquivo de chave privada SSH para o mesmo caminho (ou defina `PICOCLAW_SSH_KEY_PATH` para sua nova localização).
|
||||
|
||||
Nenhuma recriptografia é necessária.
|
||||
|
||||
---
|
||||
|
||||
## Considerações de Segurança
|
||||
|
||||
- **Tanto a frase secreta quanto a chave SSH são obrigatórias.** A chave SSH atua como um segundo fator — sem ela, a criptografia/descriptografia falhará. Execute `picoclaw onboard` para gerar a chave se ela não existir.
|
||||
- **A chave SSH é somente leitura em tempo de execução.** O PicoClaw nunca escreve ou modifica o arquivo de chave SSH.
|
||||
- **Chaves em texto simples continuam sendo suportadas.** Configurações existentes sem `enc://` não são afetadas.
|
||||
- **O formato `enc://` é versionado** através do campo `info` do HKDF (`picoclaw-credential-v1`), permitindo futuras atualizações de algoritmo sem quebrar valores criptografados existentes.
|
||||
Reference in New Issue
Block a user