diff --git a/.github/workflows/shell.yml b/.github/workflows/shell.yml
index 014ec8c..0343fc0 100644
--- a/.github/workflows/shell.yml
+++ b/.github/workflows/shell.yml
@@ -58,6 +58,14 @@ jobs:
       - name: Run tests/cli-channel-perms.sh
         run: ./tests/cli-channel-perms.sh
 
+  ai-gateway:
+    name: WP AI Gateway opt-in regression (#173)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Run tests/ai-gateway.sh
+        run: ./tests/ai-gateway.sh
+
   kimaki-agent-fallback:
     name: Kimaki native agent fallback regression
     runs-on: ubuntu-latest
diff --git a/README.md b/README.md
index 7ed6da3..2174f05 100644
--- a/README.md
+++ b/README.md
@@ -156,6 +156,11 @@ operator-entrypoints/wp-coding-agents-setup/setup.md
 | `--chat <bridge>` | Chat bridge: `kimaki`, `cc-connect`, or `telegram`. |
 | `--no-chat` | Skip chat bridge setup. |
 | `--with-homeboy` | Enable optional Homeboy project/lab integration when available. |
+| `--with-ai-gateway` | Enable optional [WP AI Gateway](https://github.com/Automattic/wp-ai-gateway) setup for OpenCode runtimes. |
+| `--ai-gateway-provider <id>` | WordPress AI Client backend provider for the gateway route (default: `openai`). |
+| `--ai-gateway-model <id>` | Backend model for the gateway route (default: `gpt-4o-mini`). |
+| `--ai-gateway-opencode-model <id>` | OpenCode-facing gateway model ID (default: `site-default`). |
+| `--rotate-ai-gateway-token` | Mint a replacement gateway token instead of reusing `.opencode/wp-ai-gateway.env`. |
 | `--multisite` | Configure WordPress multisite. |
 | `--subdomain` | Use subdomain multisite. |
 | `--no-skills` | Skip installing bundled agent skills. |
@@ -169,6 +174,13 @@ Run `./setup.sh --help` for the complete setup surface.
 
 OpenCode uses `opencode.json` with Data Machine-composed instruction files. Kimaki is the default chat bridge for OpenCode when chat is enabled.
 
+Pass `--with-ai-gateway` to opt OpenCode into this site's [WP AI Gateway](https://github.com/Automattic/wp-ai-gateway) endpoint. Setup installs the gateway/provider stack, configures the backend route via WP-CLI, mints (or reuses) a gateway token, and writes an OpenAI-compatible `provider.wp-ai-gateway` entry so clients receive only the gateway token while upstream credentials stay in WordPress. Native OpenCode auth is untouched unless gateway mode is opted in.
+
+```bash
+EXISTING_WP=~/Studio/my-site ./setup.sh --local --runtime opencode \
+  --with-ai-gateway --ai-gateway-provider openai --ai-gateway-model gpt-4o-mini
+```
+
 ### Claude Code
 
 Claude Code uses `CLAUDE.md` with generated `@` includes. A SessionStart hook refreshes the Data Machine memory includes for each session.
diff --git a/bridges/_dispatch.sh b/bridges/_dispatch.sh
index 7fc4705..3360267 100644
--- a/bridges/_dispatch.sh
+++ b/bridges/_dispatch.sh
@@ -287,6 +287,35 @@ adopt_service_identity_from_units() {
   return 0
 }
 
+# Redact secret-looking values before printing generated unit/plist diffs.
+# Dry-run output is operator-facing and often pasted into chats or PRs.
+_redact_secret_diff() {
+  awk '
+    /<key>[^<]*(TOKEN|SECRET|PASSWORD|API_KEY|REFRESH_TOKEN)[^<]*<\/key>/ {
+      print
+      redact_next_string = 1
+      next
+    }
+    redact_next_string && /<string>.*<\/string>/ {
+      sub(/<string>.*<\/string>/, "<string><redacted></string>")
+      print
+      redact_next_string = 0
+      next
+    }
+    /^[-+ ]Environment=[^=]*(TOKEN|SECRET|PASSWORD|API_KEY|REFRESH_TOKEN)=/ {
+      sub(/=.*/, "=<redacted>")
+      print
+      next
+    }
+    /^[-+ ](OPENAI_API_KEY|KIMAKI_BOT_TOKEN|TELEGRAM_BOT_TOKEN|CC_CONNECT_TOKEN)=/ {
+      sub(/=.*/, "=<redacted>")
+      print
+      next
+    }
+    { print }
+  '
+}
+
 # _smart_update_systemd_unit <unit_file> <new_unit> [<label>]
 #
 # Diff + write + daemon-reload a single systemd unit. Records the change in
@@ -326,29 +355,6 @@ _smart_update_systemd_unit() {
   UPDATED_ITEMS+=("$label (daemon-reloaded, not restarted)")
 }
 
-_redact_secret_diff() {
-  awk '
-    /Environment=.*TOKEN=/ {
-      sub(/=.*/, "=<redacted>")
-      print
-      redact_next_string = 0
-      next
-    }
-    /<key>.*TOKEN/ {
-      print
-      redact_next_string = 1
-      next
-    }
-    redact_next_string && /<string>.*<\/string>/ {
-      sub(/<string>.*<\/string>/, "<string><redacted></string>")
-      print
-      redact_next_string = 0
-      next
-    }
-    { print; redact_next_string = 0 }
-  '
-}
-
 # _plist_string_after_key <plist_path> <key>
 #
 # Extract the <string>VALUE</string> immediately after a given <key>NAME</key>
diff --git a/bridges/kimaki.sh b/bridges/kimaki.sh
index 9154db9..cd989ea 100644
--- a/bridges/kimaki.sh
+++ b/bridges/kimaki.sh
@@ -457,6 +457,10 @@ Environment=DATAMACHINE_AGENT_SLUG=$AGENT_SLUG"
     ENV_BLOCK="$ENV_BLOCK
 Environment=KIMAKI_BOT_TOKEN=$KIMAKI_BOT_TOKEN"
   fi
+  if declare -F ai_gateway_enabled_for_opencode >/dev/null && ai_gateway_enabled_for_opencode; then
+    ENV_BLOCK="$ENV_BLOCK
+EnvironmentFile=-$(ai_gateway_env_file)"
+  fi
 
   write_file "/etc/systemd/system/kimaki.service" \
     "$(bridge_render_systemd kimaki.service "$ENV_BLOCK")"
@@ -720,6 +724,13 @@ Environment=DATAMACHINE_AGENT_SLUG=$AGENT_SLUG"
   local MERGED_ENV
   MERGED_ENV=$(_merge_systemd_env_lines "$CURRENT_ENV" "$TEMPLATE_ENV")
   MERGED_ENV=$(_preserve_systemd_umask "$UNIT_FILE" "$MERGED_ENV")
+  if declare -F ai_gateway_enabled_for_opencode >/dev/null && ai_gateway_enabled_for_opencode; then
+    local gateway_env_line="EnvironmentFile=-$(ai_gateway_env_file)"
+    if ! grep -qF "$gateway_env_line" "$UNIT_FILE" 2>/dev/null; then
+      MERGED_ENV="$MERGED_ENV
+$gateway_env_line"
+    fi
+  fi
 
   local NEW_UNIT
   NEW_UNIT=$(bridge_render_systemd kimaki.service "$MERGED_ENV")
@@ -866,7 +877,7 @@ $skill_filter_plist_args
         <key>DATAMACHINE_AGENT_SLUG</key>
         <string>$AGENT_SLUG</string>"; fi)$(if [ -n "${KIMAKI_BOT_TOKEN:-}" ]; then echo "
         <key>KIMAKI_BOT_TOKEN</key>
-        <string>$KIMAKI_BOT_TOKEN</string>"; fi)
+        <string>$KIMAKI_BOT_TOKEN</string>"; fi)$(_kimaki_ai_gateway_launchd_env_xml)
     </dict>
 </dict>
 </plist>
@@ -894,6 +905,26 @@ _kimaki_skill_filter_mode() {
   printf '%s\n' "disable"
 }
 
+_kimaki_ai_gateway_launchd_env_xml() {
+  declare -F ai_gateway_enabled_for_opencode >/dev/null || return 0
+  ai_gateway_enabled_for_opencode || return 0
+  declare -F ai_gateway_read_env_value >/dev/null || return 0
+
+  local env_file base_url api_key
+  env_file="$(ai_gateway_env_file)"
+  base_url="$(ai_gateway_read_env_value OPENAI_BASE_URL "$env_file")"
+  api_key="$(ai_gateway_read_env_value OPENAI_API_KEY "$env_file")"
+  [ -n "$base_url" ] || base_url="$(ai_gateway_base_url)"
+
+  echo "
+        <key>OPENAI_BASE_URL</key>
+        <string>$base_url</string>"
+  if [ -n "$api_key" ]; then
+    echo "        <key>OPENAI_API_KEY</key>
+        <string>$api_key</string>"
+  fi
+}
+
 _kimaki_skill_filter_source() {
   if [ "$(_kimaki_skill_filter_mode)" = "enable" ]; then
     if [ -n "${KIMAKI_SKILL_ENABLES_FILE:-}" ]; then
diff --git a/lib/ai-gateway.sh b/lib/ai-gateway.sh
new file mode 100644
index 0000000..591223c
--- /dev/null
+++ b/lib/ai-gateway.sh
@@ -0,0 +1,217 @@
+#!/bin/bash
+# Optional WP AI Gateway integration for OpenCode runtimes.
+
+AI_GATEWAY_PROVIDER_ID="wp-ai-gateway"
+AI_GATEWAY_MODEL_ID="${AI_GATEWAY_MODEL_ID:-site-default}"
+AI_GATEWAY_ROUTE_PROVIDER="${AI_GATEWAY_ROUTE_PROVIDER:-openai}"
+AI_GATEWAY_ROUTE_MODEL="${AI_GATEWAY_ROUTE_MODEL:-gpt-4o-mini}"
+AI_GATEWAY_ENV_FILE="${AI_GATEWAY_ENV_FILE:-}"
+
+ai_gateway_enabled_for_opencode() {
+  [ "${WITH_AI_GATEWAY:-false}" = true ] || return 1
+
+  local runtime
+  for runtime in "${DETECTED_RUNTIMES[@]:-}"; do
+    [ "$runtime" = "opencode" ] && return 0
+  done
+
+  [ "${RUNTIME:-}" = "opencode" ]
+}
+
+ai_gateway_validate_topology() {
+  ai_gateway_enabled_for_opencode || return 0
+
+  local route_provider route_model model_provider
+  route_provider="$(printf '%s' "$AI_GATEWAY_ROUTE_PROVIDER" | tr '[:upper:]' '[:lower:]')"
+  route_model="$AI_GATEWAY_ROUTE_MODEL"
+  model_provider=""
+  case "$route_model" in
+    *:*) model_provider="${route_model%%:*}" ;;
+  esac
+  model_provider="$(printf '%s' "$model_provider" | tr '[:upper:]' '[:lower:]')"
+
+  case "$route_provider" in
+    wp-ai-gateway|ai-gateway|opencode)
+      error "Refusing recursive WP AI Gateway topology: OpenCode gateway route provider '$AI_GATEWAY_ROUTE_PROVIDER' would route back toward OpenCode/gateway mode. Choose a backend provider such as openai."
+      ;;
+  esac
+
+  case "$model_provider" in
+    wp-ai-gateway|ai-gateway|opencode)
+      error "Refusing recursive WP AI Gateway topology: OpenCode gateway route model '$AI_GATEWAY_ROUTE_MODEL' is provider-qualified back toward OpenCode/gateway mode. Choose a backend model for $AI_GATEWAY_ROUTE_PROVIDER."
+      ;;
+  esac
+}
+
+ai_gateway_base_url() {
+  local site_url="${AI_GATEWAY_SITE_URL:-}"
+  if [ -z "$site_url" ]; then
+    if [ -n "${SITE_DOMAIN:-}" ]; then
+      case "$SITE_DOMAIN" in
+        http://*|https://*) site_url="$SITE_DOMAIN" ;;
+        *) site_url="https://$SITE_DOMAIN" ;;
+      esac
+    else
+      site_url="https://example.com"
+    fi
+  fi
+
+  printf '%s/wp-json/wp-ai-gateway/v1' "${site_url%/}"
+}
+
+ai_gateway_env_file() {
+  if [ -n "$AI_GATEWAY_ENV_FILE" ]; then
+    printf '%s' "$AI_GATEWAY_ENV_FILE"
+    return
+  fi
+  printf '%s/.opencode/wp-ai-gateway.env' "$SITE_PATH"
+}
+
+ai_gateway_install_stack() {
+  ai_gateway_enabled_for_opencode || return 0
+
+  log "Phase 6.5: Installing WP AI Gateway provider stack..."
+  install_plugin ai-provider-for-openai https://github.com/WordPress/ai-provider-for-openai.git
+  install_plugin wp-ai-gateway https://github.com/Automattic/wp-ai-gateway.git
+}
+
+ai_gateway_configure_wordpress() {
+  ai_gateway_enabled_for_opencode || return 0
+
+  log "Configuring WP AI Gateway route: $AI_GATEWAY_ROUTE_PROVIDER / $AI_GATEWAY_ROUTE_MODEL"
+  if [ "$DRY_RUN" = true ]; then
+    echo -e "${BLUE}[dry-run]${NC} $WP_CMD ai-gateway configure $AI_GATEWAY_ROUTE_PROVIDER $AI_GATEWAY_ROUTE_MODEL --path=$SITE_PATH $WP_ROOT_FLAG"
+    return 0
+  fi
+
+  wp_cmd ai-gateway configure "$AI_GATEWAY_ROUTE_PROVIDER" "$AI_GATEWAY_ROUTE_MODEL"
+}
+
+ai_gateway_read_env_value() {
+  local key="$1" file="$2" line
+  [ -f "$file" ] || return 0
+  while IFS= read -r line || [ -n "$line" ]; do
+    case "$line" in
+      "$key"=*) printf '%s' "${line#*=}"; return 0 ;;
+      export\ "$key"=*) printf '%s' "${line#export $key=}"; return 0 ;;
+    esac
+  done < "$file"
+}
+
+ai_gateway_mint_token() {
+  local token_output token
+  token_output=$(wp_cmd ai-gateway token 2>&1)
+  token=$(printf '%s\n' "$token_output" | grep '^wpag_' | tail -1 || true)
+  if [ -z "$token" ]; then
+    warn "Could not parse WP AI Gateway token output; leaving OpenCode env unchanged"
+    return 1
+  fi
+  printf '%s' "$token"
+}
+
+ai_gateway_write_env() {
+  ai_gateway_enabled_for_opencode || return 0
+
+  local env_file token base_url existing_token
+  env_file="$(ai_gateway_env_file)"
+  base_url="$(ai_gateway_base_url)"
+  existing_token="$(ai_gateway_read_env_value OPENAI_API_KEY "$env_file")"
+
+  if [ -n "$existing_token" ] && [ "${ROTATE_AI_GATEWAY_TOKEN:-false}" != true ]; then
+    log "Reusing existing WP AI Gateway token reference at $env_file"
+    token="$existing_token"
+  elif [ "$DRY_RUN" = true ]; then
+    echo -e "${BLUE}[dry-run]${NC} Would mint a WP AI Gateway token and write OPENAI_API_KEY to $env_file (redacted)"
+    echo -e "${BLUE}[dry-run]${NC} Would write OPENAI_BASE_URL=$base_url to $env_file"
+    return 0
+  else
+    token="$(ai_gateway_mint_token)" || return 0
+  fi
+
+  if [ "$DRY_RUN" = true ]; then
+    return 0
+  fi
+
+  mkdir -p "$(dirname "$env_file")"
+  {
+    printf 'OPENAI_BASE_URL=%s\n' "$base_url"
+    printf 'OPENAI_API_KEY=%s\n' "$token"
+  } > "$env_file"
+  chmod 600 "$env_file"
+  if [ "${LOCAL_MODE:-false}" = false ] && [ -n "${SERVICE_USER:-}" ]; then
+    chown "$SERVICE_USER:$SERVICE_USER" "$env_file" 2>/dev/null || true
+  fi
+  UPDATED_ITEMS+=("WP AI Gateway OpenCode env ($env_file)")
+}
+
+ai_gateway_configure_opencode() {
+  ai_gateway_enabled_for_opencode || return 0
+
+  local config_file env_file base_url
+  config_file="$SITE_PATH/opencode.json"
+  env_file="$(ai_gateway_env_file)"
+  base_url="$(ai_gateway_base_url)"
+
+  if [ "$DRY_RUN" = true ]; then
+    echo -e "${BLUE}[dry-run]${NC} Would merge WP AI Gateway provider into $config_file"
+    echo -e "${BLUE}[dry-run]${NC} Provider: $AI_GATEWAY_PROVIDER_ID/$AI_GATEWAY_MODEL_ID via OPENAI_BASE_URL=$base_url and OPENAI_API_KEY=<redacted>"
+    return 0
+  fi
+
+  if [ ! -f "$config_file" ]; then
+    warn "OpenCode config not found at $config_file — skipping WP AI Gateway provider merge"
+    return 0
+  fi
+
+  python3 - "$config_file" "$AI_GATEWAY_PROVIDER_ID" "$AI_GATEWAY_MODEL_ID" <<'PY'
+import json
+import sys
+from pathlib import Path
+
+path = Path(sys.argv[1])
+provider_id = sys.argv[2]
+model_id = sys.argv[3]
+
+data = json.loads(path.read_text(encoding="utf-8"))
+provider = data.setdefault("provider", {}).setdefault(provider_id, {})
+provider.setdefault("name", "WP AI Gateway")
+provider.setdefault("npm", "@ai-sdk/openai-compatible")
+provider.setdefault("env", ["OPENAI_API_KEY"])
+provider.setdefault("options", {})
+provider["options"].setdefault("baseURL", "${OPENAI_BASE_URL}")
+provider["options"].setdefault("name", "wp-ai-gateway")
+models = provider.setdefault("models", {})
+model = models.setdefault(model_id, {})
+model.setdefault("name", "WP AI Gateway site default")
+model.setdefault("id", model_id)
+model.setdefault("tool_call", True)
+model.setdefault("temperature", True)
+model.setdefault("limit", {"context": 128000, "output": 8192})
+model.setdefault("cost", {"input": 0, "output": 0})
+
+if not data.get("model"):
+    data["model"] = f"{provider_id}/{model_id}"
+
+path.write_text(json.dumps(data, indent=2) + "\n", encoding="utf-8")
+PY
+
+  UPDATED_ITEMS+=("opencode.json WP AI Gateway provider")
+  log "Merged WP AI Gateway provider into $config_file"
+  log "OpenCode env file: $env_file"
+}
+
+setup_ai_gateway() {
+  ai_gateway_enabled_for_opencode || return 0
+  ai_gateway_validate_topology
+  ai_gateway_install_stack
+  ai_gateway_configure_wordpress
+  ai_gateway_write_env
+}
+
+upgrade_ai_gateway() {
+  ai_gateway_enabled_for_opencode || return 0
+  ai_gateway_validate_topology
+  ai_gateway_install_stack
+  ai_gateway_configure_wordpress
+  ai_gateway_write_env
+}
diff --git a/lib/summary.sh b/lib/summary.sh
index 1771138..2772bc7 100644
--- a/lib/summary.sh
+++ b/lib/summary.sh
@@ -24,6 +24,15 @@ print_summary() {
   # Runtime-specific config summary
   runtime_print_summary
 
+  if declare -F ai_gateway_enabled_for_opencode >/dev/null && ai_gateway_enabled_for_opencode; then
+    echo "WP AI Gateway:"
+    echo "  Base URL:  $(ai_gateway_base_url)"
+    echo "  Env file:  $(ai_gateway_env_file)"
+    echo "  Model:     ${AI_GATEWAY_PROVIDER_ID}/${AI_GATEWAY_MODEL_ID}"
+    echo "  Route:     ${AI_GATEWAY_ROUTE_PROVIDER} / ${AI_GATEWAY_ROUTE_MODEL}"
+    echo ""
+  fi
+
   if [ "$MULTISITE" = true ]; then
     echo "Multisite:"
     echo "  Type:        $MULTISITE_TYPE"
diff --git a/setup.sh b/setup.sh
index c3d0583..6ab008a 100755
--- a/setup.sh
+++ b/setup.sh
@@ -23,7 +23,7 @@ set -e
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 
 # Source shared modules
-for lib in common detect wordpress infrastructure data-machine carried-plugins homeboy skills summary cli-transport cli-channel runtime-signature agents-md-guidance; do
+for lib in common detect wordpress infrastructure data-machine carried-plugins homeboy ai-gateway skills summary cli-transport cli-channel runtime-signature agents-md-guidance; do
   source "$SCRIPT_DIR/lib/${lib}.sh"
 done
 
@@ -59,6 +59,8 @@ INSTALL_SKILLS=true
 SKILLS_ONLY=false
 RUNTIME_ONLY=false
 WITH_HOMEBOY=false
+WITH_AI_GATEWAY=false
+ROTATE_AI_GATEWAY_TOKEN=false
 RUNTIME=""
 HOMEBOY_MODE="auto"
 HOMEBOY_PROJECT_ID="${HOMEBOY_PROJECT_ID:-}"
@@ -134,6 +136,26 @@ while [[ $# -gt 0 ]]; do
       WITH_HOMEBOY=true
       shift
       ;;
+    --with-ai-gateway)
+      WITH_AI_GATEWAY=true
+      shift
+      ;;
+    --ai-gateway-provider)
+      AI_GATEWAY_ROUTE_PROVIDER="$2"
+      shift 2
+      ;;
+    --ai-gateway-model)
+      AI_GATEWAY_ROUTE_MODEL="$2"
+      shift 2
+      ;;
+    --ai-gateway-opencode-model)
+      AI_GATEWAY_MODEL_ID="$2"
+      shift 2
+      ;;
+    --rotate-ai-gateway-token)
+      ROTATE_AI_GATEWAY_TOKEN=true
+      shift
+      ;;
     --no-homeboy)
       HOMEBOY_MODE="disabled"
       shift
@@ -203,7 +225,23 @@ OPTIONS:
   --subdomain        Use subdomain multisite (requires wildcard DNS; use with --multisite)
   --no-skills        Skip installing the wp-coding-agents upgrade skill
   --with-homeboy     Create/update a Homeboy project and install/verify the
-                     WordPress Homeboy extension
+                      WordPress Homeboy extension
+  --with-ai-gateway  Opt in to WP AI Gateway setup for OpenCode runtimes.
+                     Installs/activates the gateway/provider stack, configures
+                     the gateway route, mints/reuses a gateway token, and adds
+                     an OpenAI-compatible provider to opencode.json.
+  --ai-gateway-provider <id>
+                     Backend WordPress AI Client provider for site-default
+                     routing (default: openai)
+  --ai-gateway-model <id>
+                     Backend provider model for site-default routing
+                     (default: gpt-4o-mini)
+  --ai-gateway-opencode-model <id>
+                     OpenCode model ID exposed by the gateway provider
+                     (default: site-default)
+  --rotate-ai-gateway-token
+                     Mint a new gateway token instead of reusing the existing
+                     .opencode/wp-ai-gateway.env value
   --no-homeboy       Skip Homeboy project setup, even if homeboy is installed
   --homeboy-project-id <id>
                      Override Homeboy project ID (default: agent/site slug)
@@ -229,6 +267,10 @@ ENVIRONMENT VARIABLES:
   HOMEBOY_SERVER_ID  Homeboy server ID for VPS project registration
   OPENCODE_MODEL     Override default model (e.g., anthropic/claude-sonnet-4-20250514)
   OPENCODE_SMALL_MODEL  Override small model (e.g., anthropic/claude-haiku-4-5)
+  AI_GATEWAY_ROUTE_PROVIDER  Backend provider used by --with-ai-gateway
+  AI_GATEWAY_ROUTE_MODEL     Backend model used by --with-ai-gateway
+  AI_GATEWAY_MODEL_ID        OpenCode gateway model id (default: site-default)
+  AI_GATEWAY_SITE_URL        Public site URL for OPENAI_BASE_URL override
   KIMAKI_BOT_TOKEN          Discord bot token (skip interactive setup)
   TELEGRAM_BOT_TOKEN        Telegram bot token from @BotFather (--chat telegram)
   TELEGRAM_ALLOWED_USER_ID  Numeric Telegram user ID (--chat telegram)
@@ -331,9 +373,12 @@ if [ "$RUNTIME_ONLY" != true ]; then
   setup_service_permissions
 fi
 
+setup_ai_gateway
+
 runtime_install
 runtime_discover_dm_paths
 runtime_generate_config
+ai_gateway_configure_opencode
 runtime_install_hooks
 configure_homeboy_wordpress_extension
 runtime_generate_instructions
diff --git a/tests/ai-gateway.sh b/tests/ai-gateway.sh
new file mode 100755
index 0000000..14241a1
--- /dev/null
+++ b/tests/ai-gateway.sh
@@ -0,0 +1,160 @@
+#!/bin/bash
+# tests/ai-gateway.sh — regression tests for optional WP AI Gateway integration.
+set -eu
+
+SCRIPT_DIR="$(cd "$(dirname "$0")/.." && pwd)"
+cd "$SCRIPT_DIR"
+
+# shellcheck disable=SC1091
+source lib/common.sh
+# shellcheck disable=SC1091
+source lib/ai-gateway.sh
+# shellcheck disable=SC1091
+source bridges/_dispatch.sh
+
+TMPDIR_TEST="$(mktemp -d)"
+trap 'rm -rf "$TMPDIR_TEST"' EXIT
+
+PASS=0
+FAIL=0
+
+assert_eq() {
+  local label="$1" expected="$2" actual="$3"
+  if [ "$expected" = "$actual" ]; then
+    echo "  ok   $label"
+    PASS=$((PASS+1))
+  else
+    echo "  FAIL $label"
+    echo "       expected: '$expected'"
+    echo "       actual:   '$actual'"
+    FAIL=$((FAIL+1))
+  fi
+}
+
+assert_file_contains() {
+  local label="$1" file="$2" needle="$3"
+  if grep -qF "$needle" "$file"; then
+    echo "  ok   $label"
+    PASS=$((PASS+1))
+  else
+    echo "  FAIL $label"
+    echo "       expected $file to contain: $needle"
+    FAIL=$((FAIL+1))
+  fi
+}
+
+assert_lacks() {
+  local label="$1" haystack="$2" needle="$3"
+  if ! printf '%s' "$haystack" | grep -qF "$needle"; then
+    echo "  ok   $label"
+    PASS=$((PASS+1))
+  else
+    echo "  FAIL $label"
+    echo "       did not expect output to contain: $needle"
+    FAIL=$((FAIL+1))
+  fi
+}
+
+SITE_PATH="$TMPDIR_TEST/site"
+SITE_DOMAIN="example.test"
+WP_CMD="wp"
+WP_ROOT_FLAG="--allow-root"
+LOCAL_MODE=true
+DRY_RUN=false
+WITH_AI_GATEWAY=true
+ROTATE_AI_GATEWAY_TOKEN=false
+DETECTED_RUNTIMES=(opencode)
+UPDATED_ITEMS=()
+mkdir -p "$SITE_PATH/.opencode"
+
+echo "==> existing gateway env is reused instead of rotated"
+cat > "$SITE_PATH/.opencode/wp-ai-gateway.env" <<'EOF'
+OPENAI_BASE_URL=https://old.example/wp-json/wp-ai-gateway/v1
+OPENAI_API_KEY=wpag_existing_secret
+EOF
+
+ai_gateway_write_env
+assert_file_contains "existing token preserved" "$SITE_PATH/.opencode/wp-ai-gateway.env" "OPENAI_API_KEY=wpag_existing_secret"
+assert_file_contains "base URL refreshed" "$SITE_PATH/.opencode/wp-ai-gateway.env" "OPENAI_BASE_URL=https://example.test/wp-json/wp-ai-gateway/v1"
+
+echo "==> dry-run redacts gateway token material"
+DRY_RUN=true
+ROTATE_AI_GATEWAY_TOKEN=true
+DRY_OUTPUT="$(ai_gateway_write_env 2>&1)"
+assert_lacks "dry-run does not print existing token" "$DRY_OUTPUT" "wpag_existing_secret"
+assert_lacks "dry-run does not print fake token" "$DRY_OUTPUT" "wpag_"
+assert_file_contains "dry-run leaves env token untouched" "$SITE_PATH/.opencode/wp-ai-gateway.env" "OPENAI_API_KEY=wpag_existing_secret"
+
+echo "==> unit/plist dry-run diffs redact secrets"
+REDACTED="$(printf '%s\n' '+Environment=OPENAI_API_KEY=wpag_existing_secret' ' <key>KIMAKI_BOT_TOKEN</key>' ' <string>discord_secret</string>' | _redact_secret_diff)"
+assert_lacks "systemd-style secret redacted" "$REDACTED" "wpag_existing_secret"
+assert_lacks "plist-style secret redacted" "$REDACTED" "discord_secret"
+
+echo "==> Kimaki launchd inherits gateway environment"
+# shellcheck disable=SC1091
+source bridges/kimaki.sh
+KIMAKI_BIN="/usr/bin/kimaki"
+KIMAKI_DATA_DIR="$TMPDIR_TEST/kimaki"
+PLIST_OUT="$TMPDIR_TEST/kimaki.plist"
+bridge_render_launchd com.wp.kimaki > "$PLIST_OUT"
+assert_file_contains "launchd includes gateway base URL" "$PLIST_OUT" "<key>OPENAI_BASE_URL</key>"
+assert_file_contains "launchd includes gateway key" "$PLIST_OUT" "<key>OPENAI_API_KEY</key>"
+
+echo "==> recursive gateway topologies are rejected in wp-coding-agents"
+AI_GATEWAY_ROUTE_PROVIDER="wp-ai-gateway"
+if ( ai_gateway_validate_topology ) >/dev/null 2>&1; then
+  echo "  FAIL recursive provider should be rejected"
+  FAIL=$((FAIL+1))
+else
+  echo "  ok   recursive provider rejected"
+  PASS=$((PASS+1))
+fi
+AI_GATEWAY_ROUTE_PROVIDER="openai"
+AI_GATEWAY_ROUTE_MODEL="opencode:site-default"
+if ( ai_gateway_validate_topology ) >/dev/null 2>&1; then
+  echo "  FAIL recursive provider-qualified model should be rejected"
+  FAIL=$((FAIL+1))
+else
+  echo "  ok   recursive provider-qualified model rejected"
+  PASS=$((PASS+1))
+fi
+AI_GATEWAY_ROUTE_MODEL="gpt-4o-mini"
+
+echo "==> opencode.json merge uses OpenCode custom provider shape"
+DRY_RUN=false
+cat > "$SITE_PATH/opencode.json" <<'JSON'
+{
+  "$schema": "https://opencode.ai/config.json",
+  "model": "anthropic/claude-sonnet-4-5",
+  "provider": {
+    "custom": {
+      "name": "Custom",
+      "models": {}
+    }
+  }
+}
+JSON
+
+ai_gateway_configure_opencode
+python3 - "$SITE_PATH/opencode.json" <<'PY'
+import json
+import sys
+
+with open(sys.argv[1], encoding="utf-8") as handle:
+    data = json.load(handle)
+
+provider = data["provider"]["wp-ai-gateway"]
+assert provider["npm"] == "@ai-sdk/openai-compatible"
+assert provider["env"] == ["OPENAI_API_KEY"]
+assert provider["options"]["baseURL"] == "${OPENAI_BASE_URL}"
+assert "site-default" in provider["models"]
+assert data["model"] == "anthropic/claude-sonnet-4-5"
+assert "custom" in data["provider"]
+PY
+
+echo
+if [ "$FAIL" -gt 0 ]; then
+  echo "FAILED: $FAIL of $((PASS+FAIL)) assertion(s)"
+  exit 1
+fi
+echo "OK: $PASS / $PASS assertions passed"
diff --git a/upgrade.sh b/upgrade.sh
index 591fc76..e26e6cc 100755
--- a/upgrade.sh
+++ b/upgrade.sh
@@ -67,7 +67,7 @@ TIMESTAMP="$(date +%Y%m%d-%H%M%S)"
 
 # Source shared modules (common, detect needed for environment resolution;
 # wordpress is needed for wp_cmd helper used by compose and plugin updates).
-for lib in common detect wordpress data-machine carried-plugins wp-codebox homeboy skills cli-transport cli-channel runtime-signature agents-md-guidance; do
+for lib in common detect wordpress data-machine carried-plugins wp-codebox homeboy ai-gateway skills cli-transport cli-channel runtime-signature agents-md-guidance; do
   source "$SCRIPT_DIR/lib/${lib}.sh"
 done
 
@@ -94,6 +94,8 @@ SKILLS_ONLY=false
 AGENTS_MD_ONLY=false
 REPAIR_OPENCODE_JSON=false
 SKIP_PLUGINS=false
+WITH_AI_GATEWAY=false
+ROTATE_AI_GATEWAY_TOKEN=false
 SHOW_HELP=false
 
 # Defaults setup.sh expects (detect.sh reads these)
@@ -124,6 +126,11 @@ while [[ $# -gt 0 ]]; do
     --agents-md-only) AGENTS_MD_ONLY=true; shift ;;
     --repair-opencode-json) REPAIR_OPENCODE_JSON=true; shift ;;
     --skip-plugins)  SKIP_PLUGINS=true; shift ;;
+    --with-ai-gateway) WITH_AI_GATEWAY=true; shift ;;
+    --ai-gateway-provider) AI_GATEWAY_ROUTE_PROVIDER="$2"; shift 2 ;;
+    --ai-gateway-model) AI_GATEWAY_ROUTE_MODEL="$2"; shift 2 ;;
+    --ai-gateway-opencode-model) AI_GATEWAY_MODEL_ID="$2"; shift 2 ;;
+    --rotate-ai-gateway-token) ROTATE_AI_GATEWAY_TOKEN=true; shift ;;
     --runtime)       RUNTIME="$2"; shift 2 ;;
     --wp-path)       EXISTING_WP="$2"; shift 2 ;;
     --local)         LOCAL_MODE=true; RUN_AS_ROOT=false; shift ;;
@@ -166,6 +173,16 @@ USAGE:
   ./upgrade.sh --root           Force root service identity (skips adoption
                                 of the existing unit's User=)
   ./upgrade.sh --non-root       Force non-root service identity (User=opencode)
+  ./upgrade.sh --with-ai-gateway
+                                Opt in to additive WP AI Gateway integration
+                                for OpenCode: install/activate gateway stack,
+                                configure route, reuse existing token env, and
+                                merge a wp-ai-gateway OpenAI-compatible provider
+                                into opencode.json.
+  ./upgrade.sh --with-ai-gateway --rotate-ai-gateway-token
+                                Explicitly mint a replacement gateway token.
+  ./upgrade.sh --with-ai-gateway --ai-gateway-provider openai --ai-gateway-model gpt-4o-mini
+                                Configure the WordPress gateway backend route.
 
 SERVICE IDENTITY:
   By default the upgrade adopts the service user from the EXISTING
@@ -203,6 +220,11 @@ OPT-IN TOUCHES:
   - opencode.json (--repair-opencode-json) — full reconcile. In addition
     to the additive behaviour above, removes unexpected plugin entries
     so the array matches exactly what setup would produce today.
+  - WP AI Gateway (--with-ai-gateway) — installs/updates wp-ai-gateway and
+    ai-provider-for-openai, configures the gateway route, writes/reuses
+    .opencode/wp-ai-gateway.env, and additively merges provider.wp-ai-gateway
+    into opencode.json. Existing gateway tokens are reused unless
+    --rotate-ai-gateway-token is also passed.
 HELP
   exit 0
 fi
@@ -356,6 +378,11 @@ sync_cli_transport_runtime() {
   cli_transport_install
 }
 
+update_ai_gateway() {
+  _run_filter_active plugins || return 0
+  upgrade_ai_gateway
+}
+
 # ============================================================================
 # Phase 3: Sync chat-bridge config
 #   kimaki    → plugins + post-upgrade.sh + skills-enable-list (see below).
@@ -794,6 +821,15 @@ print_summary() {
     warn "  to remove them (the backup from this run is preserved)."
   fi
 
+  if declare -F ai_gateway_enabled_for_opencode >/dev/null && ai_gateway_enabled_for_opencode; then
+    echo ""
+    log "WP AI Gateway:"
+    log "  Base URL:  $(ai_gateway_base_url)"
+    log "  Env file:  $(ai_gateway_env_file)"
+    log "  Model:     ${AI_GATEWAY_PROVIDER_ID}/${AI_GATEWAY_MODEL_ID}"
+    log "  Route:     ${AI_GATEWAY_ROUTE_PROVIDER} / ${AI_GATEWAY_ROUTE_MODEL}"
+  fi
+
   echo ""
   _print_bridge_restart_hint
   _print_verify_block
@@ -872,8 +908,10 @@ _print_verify_block() {
 
 update_data_machine_plugins
 sync_cli_transport_runtime
+update_ai_gateway
 sync_chat_bridge_config
 check_opencode_json_drift
+ai_gateway_configure_opencode
 sync_skills
 regenerate_agents_md
 update_chat_bridge_systemd