picoclaw/docs/guides/configuration.ja.md

⚙️ 設定ガイド

README に戻る

⚙️ 設定詳細

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

環境変数

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

変数	説明	デフォルトパス
PICOCLAW_CONFIG	設定ファイルのパスを上書きします。picoclaw がどの config.json を読み込むかを直接指定し、他のすべての場所を無視します。	~/.picoclaw/config.json
PICOCLAW_HOME	picoclaw データのルートディレクトリを上書きします。workspace やその他のデータディレクトリのデフォルト場所を変更します。	~/.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 は次のリクエスト時に最新の内容を自動的に読み込みます。

リクエストコンテキストポリシー

turn_profile は agents.defaults.turn_profile に置く任意のリクエストコンテキストポリシーです。各ターンに履歴、system prompt、skill prompt、許可ツールを含めるかどうかを制御します。未設定、または "enabled": false の場合、PicoClaw は通常動作のままです。"enabled": true にすると、このポリシーが各新規ターンに適用されます。

各ブロックは同じ mode を使います。

Mode	意味
default	PicoClaw の通常動作を維持します。ブロックまたは mode が省略された場合も default です。
off	そのブロックを無効にします。
custom	許可リストを使います。このバージョンでは skills と tools のみ対応し、history や system_prompt で使うと検証エラーになります。

ブロックの意味：

ブロック	制御する内容
history	履歴と要約の読み込み、ユーザー/アシスタント/ツールメッセージの保存、コンテキスト取り込み、圧縮と要約。
system_prompt	PicoClaw の既定の identity、ワークスペース指示、メモリ、実行時コンテキスト、要約の注入。off でも外部 system prompt は利用できます。
skills	Skill カタログと active skill のプロンプト内容。custom.allow は列挙した skill 名だけを残します。
tools	モデルに見せ、実行を許可するツール。custom.allow は登録済みで列挙されたツール名だけを残します。

system_prompt.mode が off で、ツールが表示され、外部 system prompt がない場合、PicoClaw は既存のツール使用ルールを最小のフォールバックプロンプトとして再利用します。tools.mode が off の場合、このフォールバックは追加されません。

Web ツールだけを残すクリーンなコンテキスト例：

{
  "agents": {
    "defaults": {
      "turn_profile": {
        "enabled": true,
        "history": { "mode": "off" },
        "system_prompt": { "mode": "off" },
        "skills": { "mode": "off" },
        "tools": {
          "mode": "custom",
          "allow": ["web_search", "web_fetch"]
        }
      }
    }
  }
}

スキルソース

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

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
    }
  }
}

オプション	デフォルト値	説明
workspace	~/.picoclaw/workspace	Agent の作業ディレクトリ
restrict_to_workspace	true	ファイル/コマンドアクセスをワークスペース内に制限

保護されたツール

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

ツール	機能	制限
read_file	ファイル読み取り	ワークスペース内のファイルのみ
write_file	ファイル書き込み	ワークスペース内のファイルのみ
list_dir	ディレクトリ一覧	ワークスペース内のディレクトリのみ
edit_file	ファイル編集	ワークスペース内のファイルのみ
append_file	ファイル追記	ワークスペース内のファイルのみ
exec	コマンド実行	コマンドパスはワークスペース内必須

追加の 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 :(){ :|:& };:

ファイルアクセス制御

設定キー	型	デフォルト値	説明
tools.allow_read_paths	string[]	[]	ワークスペース外で読み取りを許可する追加パス
tools.allow_write_paths	string[]	[]	ワークスペース外で書き込みを許可する追加パス

Exec セキュリティ設定

設定キー	型	デフォルト値	説明
tools.exec.allow_remote	bool	false	リモートチャネル（Telegram/Discord など）からの exec ツール実行を許可
tools.exec.enable_deny_patterns	bool	true	危険なコマンドのインターセプトを有効化
tools.exec.custom_deny_patterns	string[]	[]	カスタムブロック正規表現パターン
tools.exec.custom_allow_patterns	string[]	[]	カスタム許可正規表現パターン

セキュリティ注意: 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	restrict_to_workspace ✅
サブ Agent / Spawn	同じ制限を継承 ✅
ハートビートタスク	同じ制限を継承 ✅

すべてのパスは同じワークスペース制限を共有しており、サブ 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

主な動作：

特性	説明
spawn	非同期サブ Agent を作成、メインハートビートをブロックしない
独立コンテキスト	サブ Agent は独自のコンテキストを持ち、セッション履歴なし
message tool	サブ Agent は message ツールでユーザーと直接通信
ノンブロッキング	spawn 後、ハートビートは次のタスクに進む

設定：

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

オプション	デフォルト値	説明
enabled	true	ハートビートの有効/無効
interval	30	チェック間隔（分単位、最小: 5）

環境変数:

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

サブ Agent の通信フロー

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

Providers

Note

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

Provider	用途	API キー取得
gemini	LLM（Gemini 直接）	aistudio.google.com
zhipu	LLM（Zhipu 直接）	bigmodel.cn
volcengine	LLM（Volcengine 直接）	volcengine.com
openrouter	LLM（推奨、全モデルにアクセス可能）	openrouter.ai
anthropic	LLM（Claude 直接）	console.anthropic.com
openai	LLM（GPT 直接）	platform.openai.com
deepseek	LLM（DeepSeek 直接）	platform.deepseek.com
qwen	LLM（Qwen 直接）	dashscope.console.aliyun.com
groq	LLM + 音声文字起こし（Whisper）	console.groq.com
cerebras	LLM（Cerebras 直接）	cerebras.ai
vivgrid	LLM（Vivgrid 直接）	vivgrid.com

モデル設定 (model_list)

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

サポートされている全 Vendor

Vendor	model プレフィックス	デフォルト API Base	プロトコル	API Key
OpenAI	openai/	https://api.openai.com/v1	OpenAI	取得
Anthropic	anthropic/	https://api.anthropic.com/v1	Anthropic	取得
智谱 AI (GLM)	zhipu/	https://open.bigmodel.cn/api/paas/v4	OpenAI	取得
DeepSeek	deepseek/	https://api.deepseek.com/v1	OpenAI	取得
Google Gemini	gemini/	https://generativelanguage.googleapis.com/v1beta	Gemini	取得
Groq	groq/	https://api.groq.com/openai/v1	OpenAI	取得
通義千問 (Qwen)	qwen/	https://dashscope.aliyuncs.com/compatible-mode/v1	OpenAI	取得
Ollama	ollama/	http://localhost:11434/v1	OpenAI	ローカル（キー不要）
OpenRouter	openrouter/	https://openrouter.ai/api/v1	OpenAI	取得
VolcEngine (Doubao)	volcengine/	https://ark.cn-beijing.volces.com/api/v3	OpenAI	取得
Antigravity	antigravity/	Google Cloud	Custom	OAuth のみ

ロードバランシング

同じモデル名に複数のエンドポイントを設定すると、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 ストリーミングは二重の opt-in 方式で、デフォルトでは無効です。現在の channel に settings.streaming.enabled: true があり、アクティブなモデルエントリに streaming.enabled: true があり、さらに provider と channel の両方がストリーミングをサポートしている場合にのみ、agent はストリーミングリクエストを試行します。いずれかの条件が欠ける場合、PicoClaw は通常の非ストリーミングリクエスト経路を使います。

Pico WebUI が最初に完全対応した channel です。Pico は既存の message.create wire message で最初の assistant メッセージを作成し、その後 message.update で同じメッセージを更新します。新しい Pico wire message type は追加されません。

ストリーミングを使わない場合は streaming を省略してください。streaming ブロックの省略は無効を意味するため、"streaming": {"enabled": false} を書く必要はありません。

有効化例：

{
  "model_list": [
    {
      "model_name": "gpt-5.4",
      "provider": "openai",
      "model": "gpt-5.4",
      "api_keys": ["sk-your-openai-key"],
      "streaming": {
        "enabled": true
      }
    }
  ],
  "channel_list": {
    "pico": {
      "enabled": true,
      "type": "pico",
      "settings": {
        "token": "YOUR_PICO_TOKEN",
        "streaming": {
          "enabled": true
        }
      }
    }
  }
}

フィールド	型	デフォルト	説明
channel_list.<name>.settings.streaming.enabled	bool	false	この channel で provider のストリーミング出力を表示できるようにします
channel_list.<name>.settings.streaming.throttle_seconds	int	Pico で有効化後のデフォルト：0	中間更新の最小間隔。最終内容は常に flush されます
channel_list.<name>.settings.streaming.min_growth_chars	int	Pico で有効化後のデフォルト：1	次の中間更新を送るために必要な最小文字増加数。最終内容は常に flush されます
model_list[].streaming.enabled	bool	false	このモデルエントリで provider ストリーミングリクエストを試行できるようにします

既存の Telegram 環境変数 PICOCLAW_CHANNELS_TELEGRAM_STREAMING_ENABLED、PICOCLAW_CHANNELS_TELEGRAM_STREAMING_THROTTLE_SECONDS、PICOCLAW_CHANNELS_TELEGRAM_STREAMING_MIN_GROWTH_CHARS は互換性のため引き続き使えます。これらは Telegram settings にのみ適用され、Pico の settings.streaming を有効化または変更しません。

失敗時の動作は保守的です。可視 chunk が送信される前にストリーミングが失敗した場合、PicoClaw は通常の Chat() 経路で一度だけ再試行します。すでに chunk がユーザーに表示されている場合は、表示済み出力の重複を避けるため、二つ目の非ストリーミング回答は送信しません。

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/ に保存されます。

高度なトピック

トピック	説明
Hook システム	イベント駆動 Hook：オブザーバー、インターセプター、承認 Hook
Steering	実行中の Agent ループにメッセージを注入
SubTurn	サブ Agent の調整、並行制御、ライフサイクル
コンテキスト管理	コンテキスト境界検出、圧縮戦略