mirror of
https://github.com/sipeed/picoclaw.git
synced 2026-06-12 18:08:54 +00:00
refactor(docs): reorganize docs by type and locale
This commit is contained in:
wenjie
@@ -0,0 +1,36 @@
|
||||
# Débogage de PicoClaw
|
||||
|
||||
> Retour au [README](../project/README.fr.md)
|
||||
|
||||
PicoClaw effectue de multiples interactions complexes en arrière-plan pour chaque requête qu'il reçoit — du routage des messages et de l'évaluation de la complexité, à l'exécution des outils et à l'adaptation aux défaillances de modèle. Pouvoir voir exactement ce qui se passe est crucial, non seulement pour résoudre les problèmes potentiels, mais aussi pour véritablement comprendre le fonctionnement de l'agent.
|
||||
|
||||
## Démarrer PicoClaw en mode débogage
|
||||
|
||||
Pour obtenir des informations détaillées sur ce que fait l'agent (requêtes LLM, appels d'outils, routage des messages), vous pouvez démarrer la passerelle PicoClaw avec le drapeau de débogage :
|
||||
|
||||
```bash
|
||||
picoclaw gateway --debug
|
||||
# or
|
||||
picoclaw gateway -d
|
||||
```
|
||||
|
||||
Dans ce mode, le système formate les logs de manière détaillée et affiche des aperçus des prompts système et des résultats d'exécution des outils.
|
||||
|
||||
## Désactiver la troncature des logs (logs complets)
|
||||
|
||||
Par défaut, PicoClaw tronque les chaînes très longues (comme le *Prompt Système* ou les résultats JSON volumineux) dans les logs de débogage afin de garder la console lisible.
|
||||
|
||||
Si vous avez besoin d'inspecter la sortie complète d'une commande ou le payload exact envoyé au modèle LLM, vous pouvez utiliser le drapeau `--no-truncate`.
|
||||
|
||||
**Remarque :** Ce drapeau fonctionne *uniquement* en combinaison avec le mode `--debug`.
|
||||
|
||||
```bash
|
||||
picoclaw gateway --debug --no-truncate
|
||||
|
||||
```
|
||||
|
||||
Lorsque ce drapeau est actif, la fonction de troncature globale est désactivée. Cela est extrêmement utile pour :
|
||||
|
||||
* Vérifier la syntaxe exacte des messages envoyés au fournisseur.
|
||||
* Lire la sortie complète d'outils comme `exec`, `web_fetch` ou `read_file`.
|
||||
* Déboguer l'historique de session sauvegardé en mémoire.
|
||||
@@ -0,0 +1,36 @@
|
||||
# PicoClaw のデバッグ
|
||||
|
||||
> [README](../project/README.ja.md) に戻る
|
||||
|
||||
PicoClaw は、受信するすべてのリクエストに対して、メッセージのルーティングや複雑度の評価、ツールの実行、モデル障害への適応など、多くの複雑な処理をバックグラウンドで実行しています。何が起きているかを正確に把握できることは、潜在的な問題のトラブルシューティングだけでなく、エージェントの動作を真に理解するためにも非常に重要です。
|
||||
|
||||
## デバッグモードで PicoClaw を起動する
|
||||
|
||||
エージェントの動作に関する詳細情報（LLM リクエスト、ツール呼び出し、メッセージルーティング）を取得するには、デバッグフラグを付けて PicoClaw ゲートウェイを起動します：
|
||||
|
||||
```bash
|
||||
picoclaw gateway --debug
|
||||
# or
|
||||
picoclaw gateway -d
|
||||
```
|
||||
|
||||
このモードでは、システムがログを詳細にフォーマットし、システムプロンプトやツール実行結果のプレビューを表示します。
|
||||
|
||||
## ログの切り詰めを無効にする（完全なログ）
|
||||
|
||||
デフォルトでは、PicoClaw はコンソールの可読性を保つために、デバッグログ内の非常に長い文字列（*システムプロンプト*や大きな JSON 出力結果など）を切り詰めます。
|
||||
|
||||
コマンドの完全な出力や、LLM モデルに送信された正確なペイロードを確認する必要がある場合は、`--no-truncate` フラグを使用できます。
|
||||
|
||||
**注意：** このフラグは `--debug` モードと組み合わせた場合に*のみ*機能します。
|
||||
|
||||
```bash
|
||||
picoclaw gateway --debug --no-truncate
|
||||
|
||||
```
|
||||
|
||||
このフラグが有効な場合、グローバルな切り詰め機能が無効になります。これは以下の場合に非常に便利です：
|
||||
|
||||
* プロバイダーに送信されるメッセージの正確な構文を確認する。
|
||||
* `exec`、`web_fetch`、`read_file` などのツールの完全な出力を読む。
|
||||
* メモリに保存されたセッション履歴をデバッグする。
|
||||
@@ -0,0 +1,99 @@
|
||||
# Debugging PicoClaw
|
||||
|
||||
PicoClaw performs multiple complex interactions under the hood for every single request it receives—from routing messages and evaluating complexity, to executing tools and adapting to model failures. Being able to see exactly what is happening is crucial, not just for troubleshooting potential issues, but also for truly understanding how the agent operates.
|
||||
## Starting PicoClaw in Debug Mode
|
||||
|
||||
To get detailed information about what the agent is doing (LLM requests, tool calls, message routing), you can start the PicoClaw gateway with the debug flag:
|
||||
|
||||
```bash
|
||||
picoclaw gateway --debug
|
||||
# or
|
||||
picoclaw gateway -d
|
||||
```
|
||||
|
||||
In this mode, the system will format the logs extensively and display previews of system prompts and tool execution results.
|
||||
|
||||
## Disabling Log Truncation (Full Logs)
|
||||
|
||||
By default, PicoClaw truncates very long strings (such as the *System Prompt* or large JSON output results) in the debug logs to keep the console readable.
|
||||
|
||||
If you need to inspect the complete output of a command or the exact payload sent to the LLM model, you can use the `--no-truncate` flag.
|
||||
|
||||
**Note:** This flag *only* works when combined with the `--debug` mode.
|
||||
|
||||
```bash
|
||||
picoclaw gateway --debug --no-truncate
|
||||
|
||||
```
|
||||
|
||||
When this flag is active, the global truncation function is disabled. This is extremely useful for:
|
||||
|
||||
* Verifying the exact syntax of the messages sent to the provider.
|
||||
* Reading the complete output of tools like `exec`, `web_fetch`, or `read_file`.
|
||||
* Debugging the session history saved in memory.
|
||||
|
||||
## Tool Call Visibility in Debug Logs
|
||||
|
||||
When debug mode is active, the agent emits structured log entries at each stage of the tool execution lifecycle. These entries carry a `component=agent` label and use `INFO` or `DEBUG` level depending on the amount of detail:
|
||||
|
||||
| Log message | Level | Key fields | Description |
|
||||
|---|---|---|---|
|
||||
| `LLM requested tool calls` | INFO | `tools`, `count`, `iteration` | List of tool names the model decided to call |
|
||||
| `Tool call: <name>(<args>)` | INFO | `tool`, `iteration` | The tool name and a preview of its arguments (truncated to 200 chars) |
|
||||
| `Sent tool result to user` | DEBUG | `tool`, `content_len` | Fired when a tool result is forwarded to the chat channel |
|
||||
| `TTL tick after tool execution` | DEBUG | `agent_id`, `iteration` | MCP tool-discovery TTL decrement after each tool round |
|
||||
| `Async tool completed, publishing result` | INFO | `tool`, `content_len`, `channel` | Only for tools that run asynchronously in the background |
|
||||
|
||||
### Reading a tool call log entry
|
||||
|
||||
A typical synchronous tool call produces two consecutive lines in the console:
|
||||
|
||||
```
|
||||
[...] [INFO] agent: LLM requested tool calls {tools=[web_search], count=1, iteration=1}
|
||||
[...] [INFO] agent: Tool call: web_search({"query":"picoclaw release notes"}) {tool=web_search, iteration=1}
|
||||
```
|
||||
|
||||
The arguments preview is hard-capped at **200 characters** in the logs regardless of the `--no-truncate` flag, because it belongs to the `INFO`-level path. Use `--no-truncate` together with `--debug` to see the full `tools_json` field emitted by the `Full LLM request` DEBUG entry, which contains every tool definition sent to the model.
|
||||
|
||||
## Real-Time Tool Feedback in Chat (tool_feedback)
|
||||
|
||||
Debug logs are server-side only. If you want the agent to send a visible notification directly into the chat channel every time it executes a tool—useful when sharing the bot with other users or for transparency—enable the `tool_feedback` feature in `config.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"agents": {
|
||||
"defaults": {
|
||||
"tool_feedback": {
|
||||
"enabled": true,
|
||||
"max_args_length": 300
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
When `enabled` is `true`, every tool call sends a short message to the chat before the tool result is returned to the model. The message looks like:
|
||||
|
||||
```bash
|
||||
🔧 `web_search`
|
||||
{"query": "picoclaw release notes"}
|
||||
```
|
||||
|
||||
|
||||
### Options
|
||||
|
||||
| Field | Type | Default | Description |
|
||||
|---|---|---|---|
|
||||
| `enabled` | bool | `false` | Send a chat notification for each tool call |
|
||||
| `max_args_length` | int | `300` | Maximum characters of the serialised arguments included in the notification |
|
||||
|
||||
### Environment variables
|
||||
|
||||
Both fields can also be set via environment variables:
|
||||
|
||||
```bash
|
||||
PICOCLAW_AGENTS_DEFAULTS_TOOL_FEEDBACK_ENABLED=true
|
||||
PICOCLAW_AGENTS_DEFAULTS_TOOL_FEEDBACK_MAX_ARGS_LENGTH=300
|
||||
```
|
||||
|
||||
> **Note:** `tool_feedback` is independent of `--debug` mode. It works in production and does not require the gateway to be started with any special flag.
|
||||
@@ -0,0 +1,33 @@
|
||||
# Penyahpepijatan PicoClaw
|
||||
|
||||
PicoClaw melakukan pelbagai interaksi kompleks di sebalik tabir untuk setiap permintaan yang diterimanya, daripada menghala mesej dan menilai kerumitan, hinggalah melaksanakan tools dan menyesuaikan diri dengan kegagalan model. Keupayaan melihat dengan tepat apa yang sedang berlaku sangat penting, bukan sahaja untuk menyelesaikan masalah, malah untuk benar-benar memahami cara agen ini beroperasi.
|
||||
## Memulakan PicoClaw dalam Mod Debug
|
||||
|
||||
Untuk mendapatkan maklumat terperinci tentang apa yang sedang dilakukan oleh agen (permintaan LLM, panggilan tool, penghalaan mesej), anda boleh memulakan gateway PicoClaw dengan flag debug:
|
||||
|
||||
```bash
|
||||
picoclaw gateway --debug
|
||||
# or
|
||||
picoclaw gateway -d
|
||||
```
|
||||
|
||||
Dalam mod ini, sistem akan memformat log dengan lebih terperinci dan memaparkan pratonton system prompt serta hasil pelaksanaan tool.
|
||||
|
||||
## Menyahaktifkan Pemotongan Log (Log Penuh)
|
||||
|
||||
Secara lalai, PicoClaw memotong rentetan yang sangat panjang (seperti *System Prompt* atau hasil output JSON yang besar) dalam log debug supaya konsol kekal mudah dibaca.
|
||||
|
||||
Jika anda perlu memeriksa output penuh sesuatu arahan atau payload tepat yang dihantar kepada model LLM, anda boleh menggunakan flag `--no-truncate`.
|
||||
|
||||
**Nota:** Flag ini *hanya* berfungsi apabila digabungkan dengan mod `--debug`.
|
||||
|
||||
```bash
|
||||
picoclaw gateway --debug --no-truncate
|
||||
|
||||
```
|
||||
|
||||
Apabila flag ini aktif, fungsi pemotongan global dinyahaktifkan. Ini sangat berguna untuk:
|
||||
|
||||
* Mengesahkan sintaks tepat mesej yang dihantar kepada penyedia.
|
||||
* Membaca output lengkap daripada tools seperti `exec`, `web_fetch`, atau `read_file`.
|
||||
* Menyahpepijat sejarah sesi yang disimpan dalam memori.
|
||||
@@ -0,0 +1,36 @@
|
||||
# Depuração do PicoClaw
|
||||
|
||||
> Voltar ao [README](../project/README.pt-br.md)
|
||||
|
||||
O PicoClaw realiza múltiplas interações complexas nos bastidores para cada requisição que recebe — desde o roteamento de mensagens e avaliação de complexidade, até a execução de ferramentas e adaptação a falhas de modelo. Poder ver exatamente o que está acontecendo é crucial, não apenas para solucionar problemas potenciais, mas também para realmente entender como o agente opera.
|
||||
|
||||
## Iniciando o PicoClaw em modo de depuração
|
||||
|
||||
Para obter informações detalhadas sobre o que o agente está fazendo (requisições LLM, chamadas de ferramentas, roteamento de mensagens), você pode iniciar o gateway do PicoClaw com a flag de depuração:
|
||||
|
||||
```bash
|
||||
picoclaw gateway --debug
|
||||
# or
|
||||
picoclaw gateway -d
|
||||
```
|
||||
|
||||
Neste modo, o sistema formata os logs de forma detalhada e exibe prévias dos prompts do sistema e dos resultados de execução das ferramentas.
|
||||
|
||||
## Desabilitando a truncagem de logs (logs completos)
|
||||
|
||||
Por padrão, o PicoClaw trunca strings muito longas (como o *Prompt do Sistema* ou resultados JSON grandes) nos logs de depuração para manter o console legível.
|
||||
|
||||
Se você precisar inspecionar a saída completa de um comando ou o payload exato enviado ao modelo LLM, pode usar a flag `--no-truncate`.
|
||||
|
||||
**Nota:** Esta flag *só* funciona quando combinada com o modo `--debug`.
|
||||
|
||||
```bash
|
||||
picoclaw gateway --debug --no-truncate
|
||||
|
||||
```
|
||||
|
||||
Quando esta flag está ativa, a função de truncagem global é desabilitada. Isso é extremamente útil para:
|
||||
|
||||
* Verificar a sintaxe exata das mensagens enviadas ao provedor.
|
||||
* Ler a saída completa de ferramentas como `exec`, `web_fetch` ou `read_file`.
|
||||
* Depurar o histórico de sessão salvo na memória.
|
||||
@@ -0,0 +1,36 @@
|
||||
# Gỡ lỗi PicoClaw
|
||||
|
||||
> Quay lại [README](../project/README.vi.md)
|
||||
|
||||
PicoClaw thực hiện nhiều tương tác phức tạp ở hậu trường cho mỗi yêu cầu nhận được — từ định tuyến tin nhắn và đánh giá độ phức tạp, đến thực thi công cụ và thích ứng với lỗi mô hình. Khả năng xem chính xác những gì đang xảy ra là rất quan trọng, không chỉ để khắc phục các sự cố tiềm ẩn, mà còn để thực sự hiểu cách agent hoạt động.
|
||||
|
||||
## Khởi động PicoClaw ở chế độ gỡ lỗi
|
||||
|
||||
Để nhận thông tin chi tiết về những gì agent đang thực hiện (yêu cầu LLM, lệnh gọi công cụ, định tuyến tin nhắn), bạn có thể khởi động gateway PicoClaw với cờ gỡ lỗi:
|
||||
|
||||
```bash
|
||||
picoclaw gateway --debug
|
||||
# or
|
||||
picoclaw gateway -d
|
||||
```
|
||||
|
||||
Ở chế độ này, hệ thống sẽ định dạng log chi tiết và hiển thị bản xem trước của prompt hệ thống và kết quả thực thi công cụ.
|
||||
|
||||
## Tắt cắt ngắn log (log đầy đủ)
|
||||
|
||||
Theo mặc định, PicoClaw cắt ngắn các chuỗi rất dài (như *Prompt Hệ thống* hoặc kết quả JSON lớn) trong log gỡ lỗi để giữ cho console dễ đọc.
|
||||
|
||||
Nếu bạn cần kiểm tra đầu ra đầy đủ của một lệnh hoặc payload chính xác được gửi đến mô hình LLM, bạn có thể sử dụng cờ `--no-truncate`.
|
||||
|
||||
**Lưu ý:** Cờ này *chỉ* hoạt động khi kết hợp với chế độ `--debug`.
|
||||
|
||||
```bash
|
||||
picoclaw gateway --debug --no-truncate
|
||||
|
||||
```
|
||||
|
||||
Khi cờ này được kích hoạt, chức năng cắt ngắn toàn cục sẽ bị vô hiệu hóa. Điều này cực kỳ hữu ích để:
|
||||
|
||||
* Xác minh cú pháp chính xác của các tin nhắn được gửi đến nhà cung cấp.
|
||||
* Đọc đầu ra đầy đủ của các công cụ như `exec`, `web_fetch` hoặc `read_file`.
|
||||
* Gỡ lỗi lịch sử phiên được lưu trong bộ nhớ.
|
||||
@@ -0,0 +1,36 @@
|
||||
# 调试 PicoClaw
|
||||
|
||||
> 返回 [README](../project/README.zh.md)
|
||||
|
||||
PicoClaw 在处理每一个请求时，都会在后台执行多个复杂的交互操作——从消息路由和复杂度评估，到工具执行和模型故障适配。能够准确地看到正在发生什么至关重要，这不仅有助于排查潜在问题，也有助于真正理解代理的运作方式。
|
||||
|
||||
## 以调试模式启动 PicoClaw
|
||||
|
||||
要获取代理运行的详细信息（LLM 请求、工具调用、消息路由），可以使用调试标志启动 PicoClaw 网关：
|
||||
|
||||
```bash
|
||||
picoclaw gateway --debug
|
||||
# or
|
||||
picoclaw gateway -d
|
||||
```
|
||||
|
||||
在此模式下，系统会对日志进行详细格式化，并显示系统提示词和工具执行结果的预览。
|
||||
|
||||
## 禁用日志截断（完整日志）
|
||||
|
||||
默认情况下，PicoClaw 会在调试日志中截断过长的字符串（例如*系统提示词*或大型 JSON 输出结果），以保持控制台的可读性。
|
||||
|
||||
如果你需要检查某个命令的完整输出，或发送给 LLM 模型的确切载荷，可以使用 `--no-truncate` 标志。
|
||||
|
||||
**注意：** 此标志*仅*在与 `--debug` 模式组合使用时有效。
|
||||
|
||||
```bash
|
||||
picoclaw gateway --debug --no-truncate
|
||||
|
||||
```
|
||||
|
||||
当此标志激活时，全局截断功能将被禁用。这在以下场景中非常有用：
|
||||
|
||||
* 验证发送给提供商的消息的确切语法。
|
||||
* 读取 `exec`、`web_fetch` 或 `read_file` 等工具的完整输出。
|
||||
* 调试保存在内存中的会话历史。
|
||||
@@ -0,0 +1,45 @@
|
||||
# 🐛 Dépannage
|
||||
|
||||
> Retour au [README](../project/README.fr.md)
|
||||
|
||||
## "model ... not found in model_list" ou OpenRouter "free is not a valid model ID"
|
||||
|
||||
**Symptôme :** Vous voyez l'une des erreurs suivantes :
|
||||
|
||||
- `Error creating provider: model "openrouter/free" not found in model_list`
|
||||
- OpenRouter retourne 400 : `"free is not a valid model ID"`
|
||||
|
||||
**Cause :** Le champ `model` dans votre entrée `model_list` est ce qui est envoyé à l'API. Pour OpenRouter, vous devez utiliser l'identifiant de modèle **complet**, pas un raccourci.
|
||||
|
||||
- **Incorrect :** `"model": "free"` → OpenRouter reçoit `free` et le rejette.
|
||||
- **Correct :** `"model": "openrouter/free"` → OpenRouter reçoit `openrouter/free` (routage automatique du niveau gratuit).
|
||||
|
||||
**Correction :** Dans `~/.picoclaw/config.json` (ou votre chemin de configuration) :
|
||||
|
||||
1. **agents.defaults.model_name** doit correspondre à un `model_name` dans `model_list` (par ex. `"openrouter-free"`).
|
||||
2. Le **model** de cette entrée doit être un identifiant de modèle OpenRouter valide, par exemple :
|
||||
- `"openrouter/free"` – niveau gratuit automatique
|
||||
- `"google/gemini-2.0-flash-exp:free"`
|
||||
- `"meta-llama/llama-3.1-8b-instruct:free"`
|
||||
|
||||
Exemple :
|
||||
|
||||
```json
|
||||
{
|
||||
"agents": {
|
||||
"defaults": {
|
||||
"model_name": "openrouter-free"
|
||||
}
|
||||
},
|
||||
"model_list": [
|
||||
{
|
||||
"model_name": "openrouter-free",
|
||||
"model": "openrouter/free",
|
||||
"api_key": "sk-or-v1-YOUR_OPENROUTER_KEY",
|
||||
"api_base": "https://openrouter.ai/api/v1"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Obtenez votre clé sur [OpenRouter Keys](https://openrouter.ai/keys).
|
||||
@@ -0,0 +1,45 @@
|
||||
# 🐛 トラブルシューティング
|
||||
|
||||
> [README](../project/README.ja.md) に戻る
|
||||
|
||||
## "model ... not found in model_list" または OpenRouter "free is not a valid model ID"
|
||||
|
||||
**症状：** 以下のいずれかのエラーが表示されます：
|
||||
|
||||
- `Error creating provider: model "openrouter/free" not found in model_list`
|
||||
- OpenRouter が 400 を返す：`"free is not a valid model ID"`
|
||||
|
||||
**原因：** `model_list` エントリの `model` フィールドは API に送信される値です。OpenRouter では省略形ではなく、**完全な**モデル ID を使用する必要があります。
|
||||
|
||||
- **誤り：** `"model": "free"` → OpenRouter は `free` を受け取り、拒否します。
|
||||
- **正しい：** `"model": "openrouter/free"` → OpenRouter は `openrouter/free` を受け取ります（自動無料枠ルーティング）。
|
||||
|
||||
**修正方法：** `~/.picoclaw/config.json`（またはお使いの設定パス）で：
|
||||
|
||||
1. **agents.defaults.model_name** は `model_list` 内の `model_name` と一致する必要があります（例：`"openrouter-free"`）。
|
||||
2. そのエントリの **model** は有効な OpenRouter モデル ID である必要があります。例：
|
||||
- `"openrouter/free"` – 自動無料枠
|
||||
- `"google/gemini-2.0-flash-exp:free"`
|
||||
- `"meta-llama/llama-3.1-8b-instruct:free"`
|
||||
|
||||
設定例：
|
||||
|
||||
```json
|
||||
{
|
||||
"agents": {
|
||||
"defaults": {
|
||||
"model_name": "openrouter-free"
|
||||
}
|
||||
},
|
||||
"model_list": [
|
||||
{
|
||||
"model_name": "openrouter-free",
|
||||
"model": "openrouter/free",
|
||||
"api_key": "sk-or-v1-YOUR_OPENROUTER_KEY",
|
||||
"api_base": "https://openrouter.ai/api/v1"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
キーは [OpenRouter Keys](https://openrouter.ai/keys) で取得できます。
|
||||
@@ -0,0 +1,43 @@
|
||||
# Troubleshooting
|
||||
|
||||
## "model ... not found in model_list" or OpenRouter "free is not a valid model ID"
|
||||
|
||||
**Symptom:** You see either:
|
||||
|
||||
- `Error creating provider: model "openrouter/free" not found in model_list`
|
||||
- OpenRouter returns 400: `"free is not a valid model ID"`
|
||||
|
||||
**Cause:** The `model` field in your `model_list` entry is what gets sent to the API. For OpenRouter you must use the **full** model ID, not a shorthand.
|
||||
|
||||
- **Wrong:** `"model": "free"` → OpenRouter receives `free` and rejects it.
|
||||
- **Right:** `"model": "openrouter/free"` → OpenRouter receives `openrouter/free` (auto free-tier routing).
|
||||
|
||||
**Fix:** In `~/.picoclaw/config.json` (or your config path):
|
||||
|
||||
1. **agents.defaults.model_name** must match a `model_name` in `model_list` (e.g. `"openrouter-free"`).
|
||||
2. That entry’s **model** must be a valid OpenRouter model ID, for example:
|
||||
- `"openrouter/free"` – auto free-tier
|
||||
- `"google/gemini-2.0-flash-exp:free"`
|
||||
- `"meta-llama/llama-3.1-8b-instruct:free"`
|
||||
|
||||
Example snippet:
|
||||
|
||||
```json
|
||||
{
|
||||
"agents": {
|
||||
"defaults": {
|
||||
"model_name": "openrouter-free"
|
||||
}
|
||||
},
|
||||
"model_list": [
|
||||
{
|
||||
"model_name": "openrouter-free",
|
||||
"model": "openrouter/free",
|
||||
"api_key": "sk-or-v1-YOUR_OPENROUTER_KEY",
|
||||
"api_base": "https://openrouter.ai/api/v1"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Get your key at [OpenRouter Keys](https://openrouter.ai/keys).
|
||||
@@ -0,0 +1,43 @@
|
||||
# Penyelesaian Masalah
|
||||
|
||||
## "model ... not found in model_list" atau OpenRouter "free is not a valid model ID"
|
||||
|
||||
**Gejala:** Anda akan melihat salah satu daripada mesej berikut:
|
||||
|
||||
- `Error creating provider: model "openrouter/free" not found in model_list`
|
||||
- OpenRouter memulangkan 400: `"free is not a valid model ID"`
|
||||
|
||||
**Punca:** Medan `model` dalam entri `model_list` anda ialah nilai yang dihantar ke API. Untuk OpenRouter, anda mesti menggunakan ID model **penuh**, bukan bentuk singkatan.
|
||||
|
||||
- **Salah:** `"model": "free"` → OpenRouter menerima `free` dan menolaknya.
|
||||
- **Betul:** `"model": "openrouter/free"` → OpenRouter menerima `openrouter/free` (routing auto free-tier).
|
||||
|
||||
**Penyelesaian:** Dalam `~/.picoclaw/config.json` (atau laluan config anda):
|
||||
|
||||
1. **agents.defaults.model** mesti sepadan dengan `model_name` dalam `model_list` (contohnya `"openrouter-free"`).
|
||||
2. Medan **model** bagi entri tersebut mesti merupakan ID model OpenRouter yang sah, contohnya:
|
||||
- `"openrouter/free"` – auto free-tier
|
||||
- `"google/gemini-2.0-flash-exp:free"`
|
||||
- `"meta-llama/llama-3.1-8b-instruct:free"`
|
||||
|
||||
Example snippet:
|
||||
|
||||
```json
|
||||
{
|
||||
"agents": {
|
||||
"defaults": {
|
||||
"model": "openrouter-free"
|
||||
}
|
||||
},
|
||||
"model_list": [
|
||||
{
|
||||
"model_name": "openrouter-free",
|
||||
"model": "openrouter/free",
|
||||
"api_key": "sk-or-v1-YOUR_OPENROUTER_KEY",
|
||||
"api_base": "https://openrouter.ai/api/v1"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Dapatkan kunci anda di [OpenRouter Keys](https://openrouter.ai/keys).
|
||||
@@ -0,0 +1,45 @@
|
||||
# 🐛 Solução de Problemas
|
||||
|
||||
> Voltar ao [README](../project/README.pt-br.md)
|
||||
|
||||
## "model ... not found in model_list" ou OpenRouter "free is not a valid model ID"
|
||||
|
||||
**Sintoma:** Você vê um dos seguintes erros:
|
||||
|
||||
- `Error creating provider: model "openrouter/free" not found in model_list`
|
||||
- OpenRouter retorna 400: `"free is not a valid model ID"`
|
||||
|
||||
**Causa:** O campo `model` na sua entrada `model_list` é o que é enviado para a API. Para o OpenRouter, você deve usar o ID de modelo **completo**, não uma abreviação.
|
||||
|
||||
- **Errado:** `"model": "free"` → OpenRouter recebe `free` e rejeita.
|
||||
- **Correto:** `"model": "openrouter/free"` → OpenRouter recebe `openrouter/free` (roteamento automático do nível gratuito).
|
||||
|
||||
**Correção:** Em `~/.picoclaw/config.json` (ou seu caminho de configuração):
|
||||
|
||||
1. **agents.defaults.model_name** deve corresponder a um `model_name` em `model_list` (ex.: `"openrouter-free"`).
|
||||
2. O **model** dessa entrada deve ser um ID de modelo OpenRouter válido, por exemplo:
|
||||
- `"openrouter/free"` – nível gratuito automático
|
||||
- `"google/gemini-2.0-flash-exp:free"`
|
||||
- `"meta-llama/llama-3.1-8b-instruct:free"`
|
||||
|
||||
Exemplo:
|
||||
|
||||
```json
|
||||
{
|
||||
"agents": {
|
||||
"defaults": {
|
||||
"model_name": "openrouter-free"
|
||||
}
|
||||
},
|
||||
"model_list": [
|
||||
{
|
||||
"model_name": "openrouter-free",
|
||||
"model": "openrouter/free",
|
||||
"api_key": "sk-or-v1-YOUR_OPENROUTER_KEY",
|
||||
"api_base": "https://openrouter.ai/api/v1"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Obtenha sua chave em [OpenRouter Keys](https://openrouter.ai/keys).
|
||||
@@ -0,0 +1,45 @@
|
||||
# 🐛 Khắc Phục Sự Cố
|
||||
|
||||
> Quay lại [README](../project/README.vi.md)
|
||||
|
||||
## "model ... not found in model_list" hoặc OpenRouter "free is not a valid model ID"
|
||||
|
||||
**Triệu chứng:** Bạn thấy một trong các lỗi sau:
|
||||
|
||||
- `Error creating provider: model "openrouter/free" not found in model_list`
|
||||
- OpenRouter trả về 400: `"free is not a valid model ID"`
|
||||
|
||||
**Nguyên nhân:** Trường `model` trong mục `model_list` của bạn là giá trị được gửi đến API. Đối với OpenRouter, bạn phải sử dụng ID mô hình **đầy đủ**, không phải dạng viết tắt.
|
||||
|
||||
- **Sai:** `"model": "free"` → OpenRouter nhận được `free` và từ chối.
|
||||
- **Đúng:** `"model": "openrouter/free"` → OpenRouter nhận được `openrouter/free` (định tuyến tự động tầng miễn phí).
|
||||
|
||||
**Cách sửa:** Trong `~/.picoclaw/config.json` (hoặc đường dẫn cấu hình của bạn):
|
||||
|
||||
1. **agents.defaults.model_name** phải khớp với một `model_name` trong `model_list` (ví dụ: `"openrouter-free"`).
|
||||
2. **model** của mục đó phải là ID mô hình OpenRouter hợp lệ, ví dụ:
|
||||
- `"openrouter/free"` – tầng miễn phí tự động
|
||||
- `"google/gemini-2.0-flash-exp:free"`
|
||||
- `"meta-llama/llama-3.1-8b-instruct:free"`
|
||||
|
||||
Ví dụ:
|
||||
|
||||
```json
|
||||
{
|
||||
"agents": {
|
||||
"defaults": {
|
||||
"model_name": "openrouter-free"
|
||||
}
|
||||
},
|
||||
"model_list": [
|
||||
{
|
||||
"model_name": "openrouter-free",
|
||||
"model": "openrouter/free",
|
||||
"api_key": "sk-or-v1-YOUR_OPENROUTER_KEY",
|
||||
"api_base": "https://openrouter.ai/api/v1"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Lấy khóa của bạn tại [OpenRouter Keys](https://openrouter.ai/keys).
|
||||
@@ -0,0 +1,45 @@
|
||||
# 🐛 疑难解答
|
||||
|
||||
> 返回 [README](../project/README.zh.md)
|
||||
|
||||
## "model ... not found in model_list" 或 OpenRouter "free is not a valid model ID"
|
||||
|
||||
**症状：** 你看到以下任一错误：
|
||||
|
||||
- `Error creating provider: model "openrouter/free" not found in model_list`
|
||||
- OpenRouter 返回 400：`"free is not a valid model ID"`
|
||||
|
||||
**原因：** `model_list` 条目中的 `model` 字段是发送给 API 的内容。对于 OpenRouter，你必须使用**完整的**模型 ID，而不是简写。
|
||||
|
||||
- **错误：** `"model": "free"` → OpenRouter 收到 `free` 并拒绝。
|
||||
- **正确：** `"model": "openrouter/free"` → OpenRouter 收到 `openrouter/free`（自动免费层路由）。
|
||||
|
||||
**修复方法：** 在 `~/.picoclaw/config.json`（或你的配置路径）中：
|
||||
|
||||
1. **agents.defaults.model_name** 必须匹配 `model_list` 中的某个 `model_name`（例如 `"openrouter-free"`）。
|
||||
2. 该条目的 **model** 必须是有效的 OpenRouter 模型 ID，例如：
|
||||
- `"openrouter/free"` – 自动免费层
|
||||
- `"google/gemini-2.0-flash-exp:free"`
|
||||
- `"meta-llama/llama-3.1-8b-instruct:free"`
|
||||
|
||||
示例片段：
|
||||
|
||||
```json
|
||||
{
|
||||
"agents": {
|
||||
"defaults": {
|
||||
"model_name": "openrouter-free"
|
||||
}
|
||||
},
|
||||
"model_list": [
|
||||
{
|
||||
"model_name": "openrouter-free",
|
||||
"model": "openrouter/free",
|
||||
"api_key": "sk-or-v1-YOUR_OPENROUTER_KEY",
|
||||
"api_base": "https://openrouter.ai/api/v1"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
在 [OpenRouter Keys](https://openrouter.ai/keys) 获取你的密钥。
|
||||
Reference in New Issue
Block a user