docs: add deployment and opencode examples

README.md

@@ -172,6 +172,8 @@ Start here for the deeper deployment details:
 - [Onboarding](./docs/ONBOARDING.md)
 - [Examples](./docs/examples)
 - [OpenClaw integration starter](./openclaw-integration.jsonc)
+- [Full OpenClaw example](./docs/examples/openclaw-foundrygate-full.jsonc)
+- [Multi-provider stack example](./docs/examples/foundrygate-multi-provider-stack.yaml)
 - [First-wave AI-native starters](./docs/AI-NATIVE-MATRIX.md#first-wave-template-set-for-v110)
 - [Second-wave AI-native starters](./docs/AI-NATIVE-MATRIX.md#second-wave-template-set)
 - [Third-wave AI-native starters](./docs/AI-NATIVE-MATRIX.md#third-wave-template-set)

docs/CONFIGURATION.md

@@ -42,6 +42,13 @@ Optional base URL overrides in `.env.example`:
 
 Additional optional provider entries in `config.yaml` reference further env vars when you uncomment them.
 
+Examples in `docs/examples` also cover optional provider API keys such as:
+
+- `KILOCODE_API_KEY`
+- `BLACKBOX_API_KEY`
+
+ClawRouter / BlockRun is different: its current public path is wallet-/x402-oriented rather than a normal API-key field, so it is better treated as a separate integration model instead of another `*_API_KEY` example.
+
 ## Security Settings
 
 `config.yaml` exposes explicit security controls for the request surface:
@@ -162,6 +169,8 @@ The repo ships ready-to-copy examples under [`docs/examples`](./examples):
 - cloud provider starter YAML
 - local-worker starter YAML
 - image-provider starter YAML
+- Kilo Gateway starter YAML
+- BLACKBOX AI starter YAML
 - matching provider `.env` examples
 
 ## Validation Helpers

docs/INTEGRATIONS.md

@@ -22,6 +22,7 @@ Use:
 
 - [openclaw-integration.jsonc](../openclaw-integration.jsonc)
 - [examples/openclaw-foundrygate.jsonc](./examples/openclaw-foundrygate.jsonc)
+- [examples/openclaw-foundrygate-full.jsonc](./examples/openclaw-foundrygate-full.jsonc)
 - `client_profiles.presets: ["openclaw"]` for a standard starting point
 
 Important rule:
@@ -139,6 +140,16 @@ As with other clients, prefer token-like client tags over long free-form values
 
 If you want a small Node-facing helper instead of shell aliases, the separate npm package lives in [packages/foundrygate-cli](../packages/foundrygate-cli).
 
+### opencode
+
+`opencode` can use FoundryGate as a custom OpenAI-compatible provider through its `provider` config.
+
+- starter: [examples/opencode-foundrygate.json](./examples/opencode-foundrygate.json)
+- recommended header: `X-FoundryGate-Client: opencode`
+- recommended model: pick one of the FoundryGate model ids exposed by `GET /v1/models`, usually `auto`
+
+The current opencode docs recommend `@ai-sdk/openai-compatible` for custom OpenAI-compatible providers and a custom `provider.<id>.options.baseURL` value for the gateway endpoint. This FoundryGate starter follows that pattern and keeps the provider-local model ids aligned with `GET /v1/models`.
+
 ## AI-native app clients
 
 For future app-specific clients, keep the same OpenAI-compatible base URL and add one stable app header before creating multiple custom profiles.
@@ -280,6 +291,11 @@ Starter snippets:
 - [examples/provider-local-worker.env.example](./examples/provider-local-worker.env.example)
 - [examples/provider-image-provider.yaml](./examples/provider-image-provider.yaml)
 - [examples/provider-image-provider.env.example](./examples/provider-image-provider.env.example)
+- [examples/provider-kilocode.yaml](./examples/provider-kilocode.yaml)
+- [examples/provider-kilocode.env.example](./examples/provider-kilocode.env.example)
+- [examples/provider-blackbox.yaml](./examples/provider-blackbox.yaml)
+- [examples/provider-blackbox.env.example](./examples/provider-blackbox.env.example)
+- [examples/foundrygate-multi-provider-stack.yaml](./examples/foundrygate-multi-provider-stack.yaml)
 
 ## Client onboarding
 

docs/ONBOARDING.md

@@ -51,6 +51,11 @@ Starter snippets:
 - [examples/provider-local-worker.env.example](./examples/provider-local-worker.env.example)
 - [examples/provider-image-provider.yaml](./examples/provider-image-provider.yaml)
 - [examples/provider-image-provider.env.example](./examples/provider-image-provider.env.example)
+- [examples/provider-kilocode.yaml](./examples/provider-kilocode.yaml)
+- [examples/provider-kilocode.env.example](./examples/provider-kilocode.env.example)
+- [examples/provider-blackbox.yaml](./examples/provider-blackbox.yaml)
+- [examples/provider-blackbox.env.example](./examples/provider-blackbox.env.example)
+- [examples/foundrygate-multi-provider-stack.yaml](./examples/foundrygate-multi-provider-stack.yaml)
 
 ### 2. Verify provider health
 
@@ -68,6 +73,8 @@ Starter snippets:
 
 Repeat the same path before introducing more routing complexity.
 
+If you want a fuller multi-provider starting point instead of enabling one block at a time, use [examples/foundrygate-multi-provider-stack.yaml](./examples/foundrygate-multi-provider-stack.yaml) as a copy source and then trim it down to the providers that are actually available in your environment.
+
 For many-provider rollouts, run the onboarding report after every provider change:
 
 ```bash
@@ -126,6 +133,7 @@ OpenClaw:
 
 Starter file: [examples/openclaw-foundrygate.jsonc](./examples/openclaw-foundrygate.jsonc)
 
+Fuller deployment example: [examples/openclaw-foundrygate-full.jsonc](./examples/openclaw-foundrygate-full.jsonc)
 Full reference block: [../openclaw-integration.jsonc](../openclaw-integration.jsonc)
 
 Important:
@@ -157,6 +165,7 @@ Starter files:
 
 - [examples/n8n-foundrygate-http-request.json](./examples/n8n-foundrygate-http-request.json)
 - [examples/cli-foundrygate-env.sh](./examples/cli-foundrygate-env.sh)
+- [examples/opencode-foundrygate.json](./examples/opencode-foundrygate.json)
 - [examples/client-ai-native-app-profile.yaml](./examples/client-ai-native-app-profile.yaml)
 - [examples/swe-af-foundrygate.env.example](./examples/swe-af-foundrygate.env.example)
 - [examples/paperclip-foundrygate.env.example](./examples/paperclip-foundrygate.env.example)

docs/examples/foundrygate-multi-provider-stack.yaml

@@ -0,0 +1,128 @@
+# Example FoundryGate stack for a local-first deployment with:
+# - cloud chat providers
+# - one local worker
+# - one image-capable provider
+# - OpenClaw, n8n, and CLI presets enabled
+#
+# Copy the relevant blocks into config.yaml rather than replacing the whole file.
+
+providers:
+  deepseek-chat:
+    backend: openai-compat
+    base_url: "${DEEPSEEK_BASE_URL:-https://api.deepseek.com/v1}"
+    api_key: "${DEEPSEEK_API_KEY}"
+    model: "deepseek-chat"
+    max_tokens: 8000
+    tier: default
+
+  deepseek-reasoner:
+    backend: openai-compat
+    base_url: "${DEEPSEEK_BASE_URL:-https://api.deepseek.com/v1}"
+    api_key: "${DEEPSEEK_API_KEY}"
+    model: "deepseek-reasoner"
+    max_tokens: 8000
+    tier: reasoning
+
+  gemini-flash-lite:
+    backend: google-genai
+    base_url: "${GEMINI_BASE_URL:-https://generativelanguage.googleapis.com/v1beta}"
+    api_key: "${GEMINI_API_KEY}"
+    model: "gemini-2.5-flash-lite"
+    max_tokens: 8000
+    tier: cheap
+
+  gemini-flash:
+    backend: google-genai
+    base_url: "${GEMINI_BASE_URL:-https://generativelanguage.googleapis.com/v1beta}"
+    api_key: "${GEMINI_API_KEY}"
+    model: "gemini-2.5-flash"
+    max_tokens: 8000
+    tier: mid
+
+  openrouter-fallback:
+    backend: openai-compat
+    base_url: "${OPENROUTER_BASE_URL:-https://openrouter.ai/api/v1}"
+    api_key: "${OPENROUTER_API_KEY}"
+    model: "deepseek/deepseek-chat"
+    max_tokens: 8000
+    tier: fallback
+
+  local-worker:
+    contract: local-worker
+    backend: openai-compat
+    base_url: "http://127.0.0.1:11434/v1"
+    api_key: "local"
+    model: "llama3"
+    tier: local
+    capabilities:
+      local: true
+      cloud: false
+
+  image-provider:
+    contract: image-provider
+    backend: openai-compat
+    base_url: "http://127.0.0.1:9000/v1"
+    api_key: "${IMAGE_PROVIDER_API_KEY}"
+    model: "image-model"
+    tier: specialty
+    capabilities:
+      image_generation: true
+      image_editing: true
+    image:
+      policy_tags: ["editing", "balanced"]
+      max_outputs: 4
+      supported_sizes: ["1024x1024", "1536x1024"]
+
+fallback_chain:
+  - deepseek-chat
+  - deepseek-reasoner
+  - gemini-flash
+  - openrouter-fallback
+  # - kilocode
+  # - blackbox-free
+
+client_profiles:
+  enabled: true
+  default: generic
+  presets: ["openclaw", "n8n", "cli"]
+  profiles:
+    generic: {}
+    openclaw:
+      prefer_tiers: ["default", "reasoning"]
+    n8n:
+      prefer_tiers: ["cheap", "default"]
+    local-only:
+      capability_values:
+        local: true
+  rules: []
+
+routing_policies:
+  enabled: true
+  rules:
+    - name: n8n-cheap-default
+      match:
+        any:
+          - header_contains:
+              x-foundrygate-client: ["n8n"]
+          - client_profile: ["n8n"]
+      select:
+        prefer_tiers: ["cheap", "default"]
+
+# Optional additional fallback providers with free-tier or free-model paths:
+#
+# providers:
+#   kilocode:
+#     backend: openai-compat
+#     base_url: "${KILOCODE_BASE_URL:-https://api.kilo.ai/api/gateway/v1}"
+#     api_key: "${KILOCODE_API_KEY}"
+#     model: "z-ai/glm-5:free"
+#     max_tokens: 8000
+#     tier: fallback
+#
+#   blackbox-free:
+#     backend: openai-compat
+#     base_url: "${BLACKBOX_BASE_URL:-https://api.blackbox.ai}"
+#     api_key: "${BLACKBOX_API_KEY}"
+#     model: "blackboxai/x-ai/grok-code-fast-1:free"
+#     max_tokens: 8000
+#     tier: fallback

docs/examples/openclaw-foundrygate-full.jsonc

@@ -0,0 +1,129 @@
+// Full OpenClaw example for FoundryGate as the primary chat gateway.
+// Merge the relevant blocks into ~/.openclaw/openclaw.json.
+//
+// Notes:
+// - The ids under providers.foundrygate.models must match GET /v1/models
+//   from FoundryGate.
+// - Keep direct providers only when you still want manual overrides outside
+//   the gateway.
+// - If FoundryGate does not yet expose a real image-capable provider, keep
+//   imageModel on one direct provider until it does.
+{
+  "models": {
+    "mode": "merge",
+    "providers": {
+      "foundrygate": {
+        "baseUrl": "http://127.0.0.1:8090/v1",
+        "apiKey": "local",
+        "auth": "api-key",
+        "api": "openai-completions",
+        "models": [
+          {
+            "id": "auto",
+            "name": "FoundryGate Auto-Router",
+            "contextWindow": 128000,
+            "maxTokens": 8000
+          },
+          {
+            "id": "deepseek-chat",
+            "name": "DeepSeek Chat (via FoundryGate)",
+            "contextWindow": 128000,
+            "maxTokens": 8000
+          },
+          {
+            "id": "deepseek-reasoner",
+            "name": "DeepSeek Reasoner (via FoundryGate)",
+            "contextWindow": 128000,
+            "maxTokens": 8000
+          },
+          {
+            "id": "gemini-flash-lite",
+            "name": "Gemini Flash-Lite (via FoundryGate)",
+            "contextWindow": 1000000,
+            "maxTokens": 8000
+          },
+          {
+            "id": "gemini-flash",
+            "name": "Gemini Flash (via FoundryGate)",
+            "contextWindow": 1000000,
+            "maxTokens": 8000
+          },
+          {
+            "id": "openrouter-fallback",
+            "name": "OpenRouter Fallback (via FoundryGate)",
+            "contextWindow": 128000,
+            "maxTokens": 8000
+          }
+        ]
+      },
+      "google": {
+        "baseUrl": "https://generativelanguage.googleapis.com/v1beta",
+        "apiKey": "${GEMINI_API_KEY}",
+        "auth": "api-key",
+        "api": "google-generative-ai",
+        "models": [
+          {
+            "id": "gemini-2.5-flash",
+            "name": "Gemini 2.5 Flash",
+            "contextWindow": 1000000,
+            "maxTokens": 8000
+          }
+        ]
+      }
+    }
+  },
+  "agents": {
+    "defaults": {
+      "model": {
+        "primary": "foundrygate/auto",
+        "fallbacks": []
+      },
+      "imageModel": {
+        "primary": "google/gemini-2.5-flash",
+        "fallbacks": []
+      },
+      "models": {
+        "foundrygate/auto": {
+          "alias": "auto"
+        },
+        "foundrygate/deepseek-chat": {
+          "alias": "ds"
+        },
+        "foundrygate/deepseek-reasoner": {
+          "alias": "r1"
+        },
+        "foundrygate/gemini-flash-lite": {
+          "alias": "lite"
+        },
+        "foundrygate/gemini-flash": {
+          "alias": "flash"
+        },
+        "foundrygate/openrouter-fallback": {
+          "alias": "or"
+        },
+        "google/gemini-2.5-flash": {
+          "alias": "img"
+        }
+      },
+      "contextTokens": 200000,
+      "heartbeat": {
+        "every": "12h",
+        "model": "foundrygate/gemini-flash-lite",
+        "suppressToolErrorWarnings": true
+      },
+      "subagents": {
+        "maxConcurrent": 6,
+        "model": "foundrygate/auto"
+      }
+    }
+  },
+  "commands": {
+    "native": "auto",
+    "nativeSkills": "auto",
+    "restart": true,
+    "ownerDisplay": "raw"
+  },
+  "gateway": {
+    "mode": "local"
+  }
+}