トラブルシューティング / Troubleshooting

日本語

🚫 エージェントが応答しない / 止まってしまう

エージェントに指示を出しても返事がない場合は、以下の原因が考えられます。

1. APIキーが無効、または残高不足:
   • プロバイダー（OpenAIなど）のクレジット殘高を確認してください。
2. インターネット接続エラー:
   • 通信環境を確認してください。
3. ログの確認:
   • ワークスペースの logs/agent.log や logs/gateway.log というファイルを開くと、詳しいエラーメッセージ（例: RateLimitError など）が書かれているので確認してみましょう。

🔒 コマンド実行時に「Permission Denied」が出る

AIが「コマンドを実行しようとしましたが、権限エラーで失敗しました」と報告してくることがあります。

• 原因: エージェントが、自分が触ってはいけないシステムフォルダ（/etc など）のファイルを編集しようとしたり、セキュリティ設定でブロックされているコマンド（sudo など）を打とうとしている。
• 解決策: AIに「ワークスペースのフォルダ内（例 my-ai-assistant/）だけで作業してください」と指示を出し直してください。

💸 思ったよりAPI料金が高騰している…

AIを常駐させて監視などをさせると、リクエストの回数が積み重なり、API料金が高額になることがあります。

• 解決策（モデルの使い分け）: 毎日の数分おきのチェック作業（RSSの巡回、メールの読み上げ）には、高速で無料枠の大きいLLM（Cerebras経由のLlamaなど）を利用します。 複雑な推論タスク（本格的なコーディング、翻訳）でのみ、大型モデル（Gemini 1.5 Pro や GPT-4o）を指定するように設定（prompt）やジョブを見直してください。

English

🚫 Agent is Unresponsive / Stalls

If the agent stops answering your instructions, consider these typical causes:

1. Invalid API Key or Insufficient Balance:
   • Check your credit balance with your AI provider (e.g., OpenAI dashboard).
2. Internet Connection Error:
   • Ensure your network is stable and not blocking API endpoints.
3. Check the Logs:
   • Open logs/agent.log or logs/gateway.log in your workspace. You'll likely find specific error messages (e.g., RateLimitError) explaining the stall.

🔒 Getting "Permission Denied" When Running Commands

Sometimes the AI reports, "I tried to run a command but failed due to a permission error."

• Cause: The agent might be trying to edit crucial system files (like /etc) outside its scope, or attempting commands blocked by your security settings (like sudo).
• Solution: Simply instruct the AI: "Please work strictly within the workspace folder (e.g., my-ai-assistant/)."

💸 API Bills Are Higher Than Expected...

Leaving a highly autonomous AI running constantly to monitor systems can rack up massive API bills if every check costs money.

• Solution (Model Tiering): For frequent, routine tasks (checking RSS feeds every few minutes, scanning emails), explicitly use fast, free-tier LLM providers (like Llama 3 via Cerebras) or local models. Reserve giant models (like Gemini 1.5 Pro or GPT-4o) exclusively for highly complex reasoning tasks (coding, deep translation) by adjusting their prompts and job assignments.

简体中文

🚫 代理无响应 / 卡死

如果您给代理发送指令却未收到任何答复，请排查以下常见原因：

1. API 密钥无效或余额不足：
   • 请登录您的 AI 供应商仪表盘（如 OpenAI），检查余额（Credit）是否耗尽。
2. 网络连接错误：
   • 请确认您的互联网环境稳定。
3. 查看日志分析：
   • 请打开工作空间中的 logs/agent.log 或 logs/gateway.log 文件。里面通常会记录详细的报错信息（例如 RateLimitError 频率限制），这也是排查的最快办法。

🔒 运行命令时出现 “Permission Denied”（权限被拒绝）

有时候 AI 会向你报告：“我试图执行某个命令，但是因为权限问题失败了。”

• 原因：代理极有可能试图编辑它不应该触碰的系统文件夹（例如 /etc），或者是尝试调用被您的安全策略屏蔽的敏感命令（如 sudo 等）。
• 解决方案：重新向 AI 发送指令纠正它：“请只在工作空间文件夹（例如 my-ai-assistant/）内部进行操作。”

💸 API 费用远超预期……

由于 AI 是自主运行的，如果您让它做高频的持续监控，账单会像滚雪球一样迅速增加。

• 解决方案（分层使用模型）： 在配置那些每天频繁触发的轮询任务（如几分钟扫一次 RSS、邮件筛选）时，请务必使用高速且免费额度极高的 LLM（例如通过 Cerebras 调用的 Llama 模型）或本地大模型。 只有在需要复杂推理（硬核编程开发、高质量长篇翻译）的任务中，才主动唤起大型收费模型（如 Gemini 1.5 Pro 或 GPT-4o）。请重新检查您的调度作业（Cron Job）与设定。