diff --git a/.github/workflows/shell.yml b/.github/workflows/shell.yml
index da6e26df5..b07e31502 100644
--- a/.github/workflows/shell.yml
+++ b/.github/workflows/shell.yml
@@ -10,7 +10,7 @@ concurrency:
   group: ${{ github.workflow }}-${{ github.event_name }}-${{ github.head_ref || github.sha }}
   cancel-in-progress: true
 jobs:
-  shellspec:
+  shell-lint:
     runs-on: ubuntu-latest
     timeout-minutes: 30
     steps:
@@ -20,9 +20,9 @@ jobs:
         uses: cachix/install-nix-action@v31
         with:
           github_access_token: ${{ secrets.GITHUB_TOKEN }}
-      - name: Run ShellSpec Tests (Dev Shell)
-        run: make shell-test-dev
-  shellcheck:
+      - name: Run ShellCheck (Dev Shell)
+        run: make shell-check-dev
+  shell-test:
     runs-on: ubuntu-latest
     timeout-minutes: 30
     steps:
@@ -32,13 +32,13 @@ jobs:
         uses: cachix/install-nix-action@v31
         with:
           github_access_token: ${{ secrets.GITHUB_TOKEN }}
-      - name: Run ShellCheck (Dev Shell)
-        run: make shell-check-dev
+      - name: Run ShellSpec Tests (Dev Shell)
+        run: make shell-test-dev
   shell-check:
     if: always()
     needs:
-      - shellspec
-      - shellcheck
+      - shell-lint
+      - shell-test
     runs-on: ubuntu-latest
     timeout-minutes: 3
     steps:
diff --git a/config/cliproxyapi/config.yaml b/config/cliproxyapi/config.yaml
index f2b52b247..351457cb3 100644
--- a/config/cliproxyapi/config.yaml
+++ b/config/cliproxyapi/config.yaml
@@ -15,7 +15,7 @@ remote-management:
 auth-dir: "~/.cli-proxy-api"
 # API keys for client authentication (optional - leave commented for open access)
 # api-keys:
-#   - "your-api-key"
+#   - "__CLIPROXY_API_KEY__"
 
 # Enable debug logging
 debug: true
diff --git a/home-manager/services/cliproxyapi/scripts/start.sh b/home-manager/services/cliproxyapi/scripts/start.sh
index cf3931156..6a063126a 100755
--- a/home-manager/services/cliproxyapi/scripts/start.sh
+++ b/home-manager/services/cliproxyapi/scripts/start.sh
@@ -68,6 +68,15 @@ if [ -f "$TEMPLATE" ]; then
     -e "s|__ZAI_API_KEY__|${ZAI_API_KEY:-}|g" \
     -e "s|__AMP_UPSTREAM_API_KEY__|${AMP_UPSTREAM_API_KEY:-}|g" \
     "$TEMPLATE" >"$CONFIG"
+
+  # Linux: uncomment and enable api-keys for client authentication
+  # macOS: leave api-keys commented for open access
+  if [ "$(uname)" = "Linux" ]; then
+    @sed@ -i \
+      -e "s|^# api-keys:|api-keys:|" \
+      -e "s|^#   - \"__CLIPROXY_API_KEY__\"|  - \"${CLIPROXY_API_KEY:-}\"|" \
+      "$CONFIG"
+  fi
   # Also copy to objectstore config location (cliproxyapi uses this for persistence)
   mkdir -p "$CONFIG_DIR/objectstore/config"
   cp "$CONFIG" "$CONFIG_DIR/objectstore/config/config.yaml"
diff --git a/spec/cliproxyapi_spec.sh b/spec/cliproxyapi_spec.sh
index a1e7baecb..1057a0534 100644
--- a/spec/cliproxyapi_spec.sh
+++ b/spec/cliproxyapi_spec.sh
@@ -78,6 +78,90 @@ The status should be success
 End
 End
 
+Describe 'platform-specific api-keys handling'
+setup_apikeys() {
+  TEMP_HOME=$(mktemp -d)
+  mkdir -p "$TEMP_HOME/.cli-proxy-api"
+
+  # Create template config with commented api-keys
+  cat >"$TEMP_HOME/.cli-proxy-api/config.template.yaml" <<'YAML'
+port: 8317
+# API keys for client authentication (optional - leave commented for open access)
+# api-keys:
+#   - "__CLIPROXY_API_KEY__"
+debug: true
+YAML
+}
+
+cleanup_apikeys() {
+  rm -rf "$TEMP_HOME"
+}
+
+Before 'setup_apikeys'
+After 'cleanup_apikeys'
+
+It 'uncomments api-keys section on Linux'
+# Create test script that simulates Linux behavior
+cat >"$TEMP_HOME/test_linux_apikeys.sh" <<'EOF'
+#!/usr/bin/env bash
+set -euo pipefail
+CONFIG_DIR="$HOME/.cli-proxy-api"
+TEMPLATE="$CONFIG_DIR/config.template.yaml"
+CONFIG="$CONFIG_DIR/config.yaml"
+CLIPROXY_API_KEY="my_secret_key"
+
+# Copy template to config
+cp "$TEMPLATE" "$CONFIG"
+
+# Simulate Linux behavior (uname = Linux)
+# Use temp file approach for cross-platform sed -i compatibility
+sed \
+  -e "s|^# api-keys:|api-keys:|" \
+  -e "s|^#   - \"__CLIPROXY_API_KEY__\"|  - \"${CLIPROXY_API_KEY:-}\"|" \
+  "$CONFIG" > "$CONFIG.tmp" && mv "$CONFIG.tmp" "$CONFIG"
+
+cat "$CONFIG"
+EOF
+chmod +x "$TEMP_HOME/test_linux_apikeys.sh"
+
+When run bash -c "HOME='$TEMP_HOME' bash '$TEMP_HOME/test_linux_apikeys.sh'"
+The output should include 'api-keys:'
+The output should include '  - "my_secret_key"'
+The output should not include '# api-keys:'
+The status should be success
+End
+
+It 'keeps api-keys commented on macOS'
+# Create test script that simulates macOS behavior (no uncommenting)
+cat >"$TEMP_HOME/test_macos_apikeys.sh" <<'EOF'
+#!/usr/bin/env bash
+set -euo pipefail
+CONFIG_DIR="$HOME/.cli-proxy-api"
+TEMPLATE="$CONFIG_DIR/config.template.yaml"
+CONFIG="$CONFIG_DIR/config.yaml"
+
+# Copy template to config (macOS behavior - no api-keys uncommenting)
+cp "$TEMPLATE" "$CONFIG"
+
+cat "$CONFIG"
+EOF
+chmod +x "$TEMP_HOME/test_macos_apikeys.sh"
+
+When run bash -c "HOME='$TEMP_HOME' bash '$TEMP_HOME/test_macos_apikeys.sh'"
+The output should include '# api-keys:'
+The output should include '#   - "__CLIPROXY_API_KEY__"'
+The status should be success
+End
+
+It 'script has Linux-specific api-keys uncommenting logic'
+When run bash -c "grep -A 6 'Linux: uncomment and enable api-keys' '$SCRIPT'"
+# shellcheck disable=SC2016
+The output should include 'if [ "$(uname)" = "Linux" ]'
+The output should include 's|^# api-keys:|api-keys:|'
+The output should include 'CLIPROXY_API_KEY'
+End
+End
+
 Describe 'binary detection logic'
 It 'checks /opt/homebrew/bin/cliproxyapi first'
 When run bash -c "grep -A 2 'if.*-x.*/opt/homebrew/bin/cliproxyapi' '$SCRIPT'"