OpenClawのSkills設定ガイド：カスタムスキルの追加と管理方法

開発環境を整える際、どのツールをどのプロジェクトで有効にするか、その管理に頭を悩ませることはありませんか？特に複数のエージェントを運用していると、スキルの管理が複雑になりがちです。

OpenClaw のスキル設定を活用することで、各エージェントが必要な機能だけを安全かつ効率的に利用できるようになります。

スキル設定の構成

スキルの読み込みやインストールに関する設定は、主に ~/.openclaw/openclaw.json 内の skills セクションで行います。エージェントごとのスキルの可視性は、agents.defaults.skills や agents.list[].skills で制御可能です。

{
  skills: {
    allowBundled: ["gemini", "peekaboo"],
    load: {
      extraDirs: ["~/Projects/agent-scripts/skills", "~/Projects/oss/some-skill-pack/skills"],
      watch: true,
      watchDebounceMs: 250,
    },
    install: {
      preferBrew: true,
      nodeManager: "npm", // npm | pnpm | yarn | bun (Gateway runtime still Node; bun not recommended)
    },
    entries: {
      "image-lab": {
        enabled: true,
        apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" }, // or plaintext string
        env: {
          GEMINI_API_KEY: "GEMINI_KEY_HERE",
        },
      },
      peekaboo: { enabled: true },
      sag: { enabled: false },
    },
  },
}

組み込みの画像生成や編集機能を利用する場合は、agents.defaults.imageGenerationModel とコア機能である image_generate ツールを優先してください。skills.entries.* は、カスタムスキルやサードパーティ製のワークフロー専用です。

特定の画像プロバイダーやモデルを選択した場合は、そのプロバイダーの認証情報や API キーも設定してください。一般的な例として、google/* には GEMINI_API_KEY や GOOGLE_API_KEY、openai/* には OPENAI_API_KEY、fal/* には FAL_KEY を使用します。

設定例：

• ネイティブな Nano Banana スタイルの設定: agents.defaults.imageGenerationModel.primary: "google/gemini-3.1-flash-image-preview"
• ネイティブな fal の設定: agents.defaults.imageGenerationModel.primary: "fal/fal-ai/flux/dev"

Agent skill allowlists

同じマシンやワークスペースでスキルルートを共有しつつ、エージェントごとに異なるスキルセットを有効にしたい場合は、エージェント設定を使用します。

{
  agents: {
    defaults: {
      skills: ["github", "weather"],
    },
    list: [
      { id: "writer" }, // inherits defaults -> github, weather
      { id: "docs", skills: ["docs-search"] }, // replaces defaults
      { id: "locked-down", skills: [] }, // no skills
    ],
  },
}

ルールは以下の通りです：

1. agents.defaults.skills: agents.list[].skills を省略したエージェントのための共有ベースラインです。
2. agents.defaults.skills を省略すると、デフォルトでスキルが制限されなくなります。
3. agents.list[].skills: そのエージェント専用の最終的なスキルセットです。デフォルト設定とはマージされません。
4. agents.list[].skills: []: そのエージェントに対してスキルを一切公開しません。

Fields

設定項目を正しく理解することで、OpenClaw の動作を細かく制御できます。

1. 組み込みのスキルルートには、常に ~/.openclaw/skills、~/.agents/skills、<workspace>/.agents/skills、<workspace>/skills が含まれます。
2. allowBundled: bundled スキルのみを対象としたオプションの許可リストです。設定すると、リスト内の bundled スキルのみが有効になります（管理対象スキル、エージェントスキル、ワークスペーススキルには影響しません）。
3. load.extraDirs: スキャン対象となる追加のスキルディレクトリです（優先度は最も低くなります）。
4. load.watch: スキルフォルダを監視し、スキルのスナップショットを更新します（デフォルト: true）。
5. load.watchDebounceMs: スキル監視イベントのデバウンス時間（ミリ秒単位、デフォルト: 250）。
6. install.preferBrew: 利用可能な場合に brew インストーラーを優先します（デフォルト: true）。
7. install.nodeManager: Node.js インストーラーの優先設定（npm | pnpm | yarn | bun、デフォルト: npm）。これは スキルインストール にのみ影響します。Gateway のランタイムは引き続き Node.js である必要があります（WhatsApp/Telegram に bun は推奨されません）。
   • openclaw setup --node-manager コマンドはより限定的で、現在は npm、pnpm、bun を受け付けます。Yarn を使用したい場合は、skills.install.nodeManager: "yarn" を手動で設定してください。
8. entries.<skillKey>: スキルごとのオーバーライド設定です。
9. agents.defaults.skills: agents.list[].skills を省略したエージェントが継承する、オプションのデフォルトスキル許可リストです。
10. agents.list[].skills: エージェントごとの最終的なスキル許可リストです。明示的なリストは継承されたデフォルトを置き換えます（マージはされません）。

スキルごとのフィールド：

1. enabled: false に設定すると、bundled やインストール済みであってもスキルを無効化できます。
2. env: エージェント実行時に注入される環境変数です（未設定の場合のみ適用）。
3. apiKey: 主要な環境変数を宣言するスキルのための便利なオプションです。プレーンテキスト文字列、または SecretRef オブジェクト（{ source, provider, id }）をサポートしています。

Notes

設定の優先順位や挙動について、以下の点に注意してください。

1. entries 配下のキーは、デフォルトでスキル名にマッピングされます。スキルが metadata.openclaw.skillKey を定義している場合は、そのキーを使用してください。
2. 読み込みの優先順位は、<workspace>/skills → <workspace>/.agents/skills → ~/.agents/skills → ~/.openclaw/skills → bundled スキル → skills.load.extraDirs の順です。
3. スキルへの変更は、監視機能が有効な場合、次のエージェントのターンで反映されます。

Sandboxed skills + env vars

セッションが sandboxed されている場合、スキルプロセスは設定されたサンドボックスバックエンド内で実行されます。このサンドボックスはホストの process.env を継承しません。

以下のいずれかを使用してください：

1. Docker バックエンドを使用する場合は agents.defaults.sandbox.docker.env（またはエージェントごとの agents.list[].sandbox.docker.env）を設定します。
2. カスタムサンドボックスイメージやリモートサンドボックス環境に環境変数を組み込みます。

グローバルな env および skills.entries.<skill>.env/apiKey は、ホスト 上での実行にのみ適用されます。

---

さらなる詳細は AI Setup Assistant をご確認ください。

次のステップ

• Getting Started
• Agent Configuration