⚙️ 設定ガイド

README に戻る

⚙️ 設定詳細

設定ファイルパス: ~/.picoclaw/config.json

環境変数

環境変数を使用してデフォルトパスを上書きできます。ポータブルインストール、コンテナ化デプロイ、または picoclaw をシステムサービスとして実行する場合に便利です。これらの変数は独立しており、異なるパスを制御します。

例：

# 特定の設定ファイルで picoclaw を実行
# ワークスペースパスはその設定ファイル内から読み込まれます
PICOCLAW_CONFIG=/etc/picoclaw/production.json picoclaw gateway

# /opt/picoclaw にすべてのデータを保存して picoclaw を実行
# 設定はデフォルトの ~/.picoclaw/config.json から読み込まれます
# ワークスペースは /opt/picoclaw/workspace に作成されます
PICOCLAW_HOME=/opt/picoclaw picoclaw agent

# 両方を使用して完全にカスタマイズ
PICOCLAW_HOME=/srv/picoclaw PICOCLAW_CONFIG=/srv/picoclaw/main.json picoclaw gateway

Gateway ログレベル

gateway.log_level は Gateway のログ詳細度を制御します。config.json で設定できます：

{
  "gateway": {
    "log_level": "warn"
  }
}

デフォルト値は warn です。サポートされる値：debug、info、warn、error、fatal。

環境変数でも上書き可能です：PICOCLAW_LOG_LEVEL=info

ワークスペースレイアウト

PicoClaw は設定されたワークスペース（デフォルト: ~/.picoclaw/workspace）にデータを保存します：

~/.picoclaw/workspace/
├── sessions/          # 会話セッションと履歴
├── memory/           # 長期記憶 (MEMORY.md)
├── state/            # 永続化状態 (最後のチャネルなど)
├── cron/             # スケジュールジョブデータベース
├── skills/           # カスタムスキル
├── AGENT.md          # Agent 動作ガイド
├── HEARTBEAT.md      # 定期タスクプロンプト (30 分ごとにチェック)
├── IDENTITY.md       # Agent アイデンティティ
├── SOUL.md           # Agent ソウル/性格
└── USER.md           # ユーザー設定

注意： AGENT.md、SOUL.md、USER.md および memory/MEMORY.md への変更は、ファイル更新時刻（mtime）の追跡により実行時に自動検出されます。これらのファイルを編集した後に gateway を再起動する必要はありません — Agent は次のリクエスト時に最新の内容を自動的に読み込みます。

スキルソース

デフォルトでは、スキルは以下の順序で読み込まれます：

1. ~/.picoclaw/workspace/skills（ワークスペース）
2. ~/.picoclaw/skills（グローバル）
3. <ビルド時埋め込みパス>/skills（ビルトイン）

高度な/テスト用セットアップでは、以下の環境変数でビルトインスキルのルートを上書きできます：

export PICOCLAW_BUILTIN_SKILLS=/path/to/skills

チャットチャネルからスキルとコマンドを使う

スキルをインストールすると、チャットチャネルから直接確認したり明示的に適用したりできます：

• /list skills は現在の Agent から見えるインストール済みスキル名を表示します。
• /use <skill> <message> は 1 回のリクエストだけそのスキルを強制します。
• /use <skill> は同じチャット内の次のメッセージにそのスキルを予約します。
• /use clear は /use <skill> で設定した保留中のスキル上書きを解除します。
• /btw <question> は現在のセッション履歴を変更せずに即時の横道の質問を送ります。/btw はツールなしの直接質問として処理され、通常のツール実行フローには入りません。

例：

/list skills
/use git 直近 3 つのコミットを squash する方法を教えて
/btw さっきのデプロイ方針の結論だけもう一度教えて
/use italiapersonalfinance
dammi le ultime news

統一コマンド実行ポリシー

• 汎用スラッシュコマンドは pkg/agent/loop.go 内の commands.Executor を通じて統一的に実行されます。
• チャネルアダプターはローカルで汎用コマンドを消費しなくなりました。受信テキストを bus/agent パスに転送するだけです。Telegram は起動時に /start、/help、/show、/list、/use、/btw などのサポート済みコマンドを自動登録します。
• 未登録のスラッシュコマンド（例: /foo）は通常の LLM 処理にパススルーされます。
• 登録済みだが現在のチャネルでサポートされていないコマンド（例: WhatsApp での /show）は、明示的なユーザー向けエラーを返し、以降の処理を停止します。

🔒 セキュリティサンドボックス

PicoClaw はデフォルトでサンドボックス環境で実行されます。Agent は設定されたワークスペース内のファイルアクセスとコマンド実行のみが可能です。

デフォルト設定

{
  "agents": {
    "defaults": {
      "workspace": "~/.picoclaw/workspace",
      "restrict_to_workspace": true
    }
  }
}

保護されたツール

restrict_to_workspace: true の場合、以下のツールがサンドボックス化されます：

追加の Exec 保護

restrict_to_workspace: false の場合でも、exec ツールは以下の危険なコマンドをブロックします：

• rm -rf、del /f、rmdir /s — 一括削除
• format、mkfs、diskpart — ディスクフォーマット
• dd if= — ディスクイメージング
• /dev/sd[a-z] への書き込み — 直接ディスク書き込み
• shutdown、reboot、poweroff — システムシャットダウン
• Fork bomb :(){ :|:& };:

ファイルアクセス制御

Exec セキュリティ設定

セキュリティ注意: Symlink 保護はデフォルトで有効です。すべてのファイルパスはホワイトリストマッチング前に filepath.EvalSymlinks で解決され、シンボリックリンクエスケープ攻撃を防止します。

既知の制限：ビルドツールの子プロセス

exec セキュリティガードは PicoClaw が直接起動するコマンドラインのみを検査します。make、go run、cargo、npm run、またはカスタムビルドスクリプトなどの開発ツールが生成する子プロセスは再帰的に検査しません。

つまり、トップレベルのコマンドが初期ガードチェックを通過した後、他のバイナリをコンパイルまたは起動できます。実際には、ビルドスクリプト、Makefile、パッケージスクリプト、生成されたバイナリを、直接のシェルコマンドと同等レベルの実行可能コードとしてレビューする必要があります。

高リスク環境の場合：

• 実行前にビルドスクリプトをレビューしてください。
• コンパイル・実行ワークフローには承認/手動レビューを優先してください。
• ビルトインガードより強力な分離が必要な場合は、コンテナまたは VM 内で PicoClaw を実行してください。

エラー例

[ERROR] tool: Tool execution failed
{tool=exec, error=Command blocked by safety guard (path outside working dir)}

[ERROR] tool: Tool execution failed
{tool=exec, error=Command blocked by safety guard (dangerous pattern detected)}

制限の無効化（セキュリティリスク）

Agent がワークスペース外のパスにアクセスする必要がある場合：

方法 1: 設定ファイル

{
  "agents": {
    "defaults": {
      "restrict_to_workspace": false
    }
  }
}

方法 2: 環境変数

export PICOCLAW_AGENTS_DEFAULTS_RESTRICT_TO_WORKSPACE=false

⚠️ 警告: この制限を無効にすると、Agent がシステム上の任意のパスにアクセスできるようになります。管理された環境でのみ慎重に使用してください。

セキュリティ境界の一貫性

restrict_to_workspace 設定はすべての実行パスで一貫して適用されます：

すべてのパスは同じワークスペース制限を共有しており、サブ Agent やスケジュールタスクを通じてセキュリティ境界を回避することはできません。

ハートビート（定期タスク）

PicoClaw は定期タスクを自動実行できます。ワークスペースに HEARTBEAT.md ファイルを作成してください：

# Periodic Tasks

- Check my email for important messages
- Review my calendar for upcoming events
- Check the weather forecast

Agent は 30 分ごと（設定可能）にこのファイルを読み取り、利用可能なツールを使用してタスクを実行します。

Spawn を使用した非同期タスク

長時間実行タスク（Web 検索、API 呼び出し）には、spawn ツールを使用してサブ Agent (subagent) を作成します：

# Periodic Tasks

## Quick Tasks (respond directly)

- Report current time

## Long Tasks (use spawn for async)

- Search the web for AI news and summarize
- Check email and report important messages

主な動作：

設定：

{
  "heartbeat": {
    "enabled": true,
    "interval": 30
  }
}

環境変数:

• PICOCLAW_HEARTBEAT_ENABLED=false で無効化
• PICOCLAW_HEARTBEAT_INTERVAL=60 で間隔を変更

サブ Agent の通信フロー

ハートビート起動
    ↓
Agent が HEARTBEAT.md を読む
    ↓
長時間タスク：spawn サブ Agent
    ↓                           ↓
次のタスクへ継続           サブ Agent が独立して動作
    ↓                           ↓
全タスク完了               サブ Agent が "message" ツールを使用
    ↓                           ↓
HEARTBEAT_OK を返信        ユーザーが直接結果を受信

Providers

[!NOTE] Groq は Whisper による無料音声文字起こしを提供します。設定すると、任意のチャンネルの音声メッセージが Agent レベルで自動的に文字起こしされます。

モデル設定 (model_list)

新機能： PicoClaw はモデル中心の設定アプローチを採用しました。vendor/model 形式（例：zhipu/glm-4.7）を指定するだけで新しい Provider を追加できます — コード変更不要！

サポートされている全 Vendor

ロードバランシング

同じモデル名に複数のエンドポイントを設定すると、PicoClaw が自動的にラウンドロビンします：

{
  "model_list": [
    { "model_name": "gpt-5.4", "model": "openai/gpt-5.4", "api_base": "https://api1.example.com/v1", "api_keys": ["sk-key1"] },
    { "model_name": "gpt-5.4", "model": "openai/gpt-5.4", "api_base": "https://api2.example.com/v1", "api_keys": ["sk-key2"] }
  ]
}

旧 providers 設定からの移行

旧 providers 設定は非推奨となり、V2 で削除されました。既存の V0/V1 設定は自動的に移行されます。docs/migration/model-list-migration.md を参照してください。

Provider アーキテクチャ

PicoClaw はプロトコルファミリーで Provider をルーティングします：

• OpenAI 互換：OpenRouter、Groq、Zhipu、vLLM スタイルのエンドポイントなど。
• Gemini ネイティブ：Google Gemini のネイティブ models/*:generateContent / models/*:streamGenerateContent エンドポイント。
• Anthropic：Claude ネイティブ API の動作。
• Codex/OAuth：OpenAI OAuth/トークン認証ルート。

これによりランタイムを軽量に保ちつつ、新しい OpenAI 互換バックエンドの追加をほぼ設定操作（api_base + api_keys）のみで実現します。

スケジュールタスク / リマインダー

PicoClaw は cron ツールを通じて cron スタイルのスケジュールタスクをサポートします。

{
  "tools": {
    "cron": {
      "enabled": true,
      "exec_timeout_minutes": 5
    }
  }
}

スケジュールタスクは再起動後も ~/.picoclaw/workspace/cron/ に保存されます。

高度なトピック