Docs
고급 기능
기업용 기능

기업용 Gemini CLI

이 문서는 기업 환경에서 Gemini CLI를 배포하고 관리하기 위한 구성 패턴과 모범 사례를 설명합니다. 관리자는 시스템 수준 설정을 활용하여 보안 정책을 시행하고, 도구 액세스를 관리하며, 모든 사용자에게 일관된 경험을 보장할 수 있습니다.

보안 참고 사항: 이 문서에 설명된 패턴은 관리자가 Gemini CLI 사용을 위해 보다 통제되고 안전한 환경을 조성하는 데 도움을 주기 위한 것입니다. 하지만 완벽한 보안 경계로 간주해서는 안 됩니다. 로컬 머신에 충분한 권한이 있는 사용자는 여전히 이러한 구성을 우회할 수 있습니다. 이러한 조치는 로컬 관리 권한이 있는 악의적인 행위자를 방어하기 위한 것이 아니라, 우발적인 오용을 방지하고 관리되는 환경에서 기업 정책을 시행하기 위해 설계되었습니다.

중앙 집중식 구성: 시스템 설정 파일

기업 관리를 위한 가장 강력한 도구는 시스템 전체 설정 파일입니다. 이 파일을 사용하면 시스템의 모든 사용자에게 적용되는 기본 구성(system-defaults.json)과 재정의 설정(settings.json)을 정의할 수 있습니다. 구성 옵션에 대한 전체 개요는 구성 문서를 참조하세요.

설정은 4개의 파일에서 병합됩니다. 단일 값 설정(예: theme)의 우선순위는 다음과 같습니다:

  1. 시스템 기본값 (system-defaults.json)
  2. 사용자 설정 (~/.gemini/settings.json)
  3. 작업 공간 설정 (<project>/.gemini/settings.json)
  4. 시스템 재정의 (settings.json)

즉, 시스템 재정의 파일이 최종 결정권을 갖습니다. 배열(includeDirectories)이나 객체(mcpServers)인 설정의 경우 값이 병합됩니다.

병합 및 우선순위 예시:

다음은 서로 다른 수준의 설정이 결합되는 방식입니다.

  • 시스템 기본값 system-defaults.json:

    {
  "ui": {
    "theme": "default-corporate-theme"
  },
  "context": {
    "includeDirectories": ["/etc/gemini-cli/common-context"]
  }
}

  • 사용자 settings.json (~/.gemini/settings.json):

    {
  "ui": {
    "theme": "user-preferred-dark-theme"
  },
  "mcpServers": {
    "corp-server": {
      "command": "/usr/local/bin/corp-server-dev"
    },
    "user-tool": {
      "command": "npm start --prefix ~/tools/my-tool"
    }
  },
  "context": {
    "includeDirectories": ["~/gemini-context"]
  }
}

  • 작업 공간 settings.json (<project>/.gemini/settings.json):

    {
  "ui": {
    "theme": "project-specific-light-theme"
  },
  "mcpServers": {
    "project-tool": {
      "command": "npm start"
    }
  },
  "context": {
    "includeDirectories": ["./project-context"]
  }
}

  • 시스템 재정의 settings.json:

    {
  "ui": {
    "theme": "system-enforced-theme"
  },
  "mcpServers": {
    "corp-server": {
      "command": "/usr/local/bin/corp-server-prod"
    }
  },
  "context": {
    "includeDirectories": ["/etc/gemini-cli/global-context"]
  }
}

이로 인해 다음과 같이 병합된 구성이 생성됩니다:

  • 최종 병합된 구성: 
    {
  "ui": {
    "theme": "system-enforced-theme"
  },
  "mcpServers": {
    "corp-server": {
      "command": "/usr/local/bin/corp-server-prod"
    },
    "user-tool": {
      "command": "npm start --prefix ~/tools/my-tool"
    },
    "project-tool": {
      "command": "npm start"
    }
  },
  "context": {
    "includeDirectories": [
      "/etc/gemini-cli/common-context",
      "~/gemini-context",
      "./project-context",
      "/etc/gemini-cli/global-context"
    ]
  }
}

이유:

  • theme: 시스템 재정의(system-enforced-theme)의 값이 가장 높은 우선순위를 가지므로 사용됩니다.

  • mcpServers: 객체가 병합됩니다. 시스템 재정의의 corp-server 정의가 사용자 정의보다 우선합니다. 고유한 user-tool 및 project-tool이 포함됩니다.

  • includeDirectories: 배열은 시스템 기본값, 사용자, 작업 공간, 시스템 재정의 순서로 연결됩니다.

  • 위치:

    • Linux: /etc/gemini-cli/settings.json
    • Windows: C:\ProgramData\gemini-cli\settings.json
    • macOS: /Library/Application Support/GeminiCli/settings.json
    • 경로는 GEMINI_CLI_SYSTEM_SETTINGS_PATH 환경 변수를 사용하여 재정의할 수 있습니다.

  • 제어: 이 파일은 시스템 관리자가 관리해야 하며, 사용자의 무단 수정을 방지하기 위해 적절한 파일 권한으로 보호되어야 합니다.

시스템 설정 파일을 사용하면 아래에 설명된 보안 및 구성 패턴을 시행할 수 있습니다.

래퍼 스크립트로 시스템 설정 강제 적용

GEMINI_CLI_SYSTEM_SETTINGS_PATH 환경 변수는 유연성을 제공하지만, 사용자가 이를 재정의하여 다른 설정 파일을 가리키게 함으로써 중앙 관리 구성을 우회할 수 있습니다. 이를 완화하기 위해 기업은 환경 변수가 항상 회사 제어 경로로 설정되도록 하는 래퍼 스크립트나 별칭을 배포할 수 있습니다.

이 접근 방식은 사용자가 gemini 명령을 어떻게 호출하든 기업 설정이 항상 가장 높은 우선순위로 로드되도록 보장합니다.

예시 래퍼 스크립트:

관리자는 gemini라는 이름의 스크립트를 작성하여 실제 Gemini CLI 바이너리보다 사용자 PATH의 앞부분에 있는 디렉터리(예: /usr/local/bin/gemini)에 배치할 수 있습니다.

#!/bin/bash
 
# Enforce the path to the corporate system settings file.
# This ensures that the company's configuration is always applied.
export GEMINI_CLI_SYSTEM_SETTINGS_PATH="/etc/gemini-cli/settings.json"
 
# Find the original gemini executable.
# This is a simple example; a more robust solution might be needed
# depending on the installation method.
REAL_GEMINI_PATH=$(type -aP gemini | grep -v "^$(type -P gemini)$" | head -n 1)
 
if [ -z "$REAL_GEMINI_PATH" ]; then
  echo "Error: The original 'gemini' executable was not found." >&2
  exit 1
fi
 
# Pass all arguments to the real Gemini CLI executable.
exec "$REAL_GEMINI_PATH" "$@"

이 스크립트를 배포하면 스크립트 환경 내에서 GEMINI_CLI_SYSTEM_SETTINGS_PATH가 설정되고, exec 명령은 스크립트 프로세스를 실제 Gemini CLI 프로세스로 대체하여 환경 변수를 상속받습니다. 이렇게 하면 사용자가 강제 설정을 우회하기가 훨씬 어려워집니다.

공유 환경에서의 사용자 격리

공유 컴퓨팅 환경(예: ML 실험 러너 또는 공유 빌드 서버)에서는 사용자의 홈 디렉터리를 재정의하여 Gemini CLI 상태를 격리할 수 있습니다.

기본적으로 Gemini CLI는 구성 및 기록을 ~/.gemini에 저장합니다. GEMINI_CLI_HOME 환경 변수를 사용하여 특정 사용자 또는 작업에 대한 고유한 디렉터리를 가리킬 수 있습니다. CLI는 지정된 경로 내에 .gemini 폴더를 생성합니다.

# 특정 작업에 대한 상태 격리
export GEMINI_CLI_HOME="/tmp/gemini-job-123"
gemini

도구 액세스 제한

Gemini 모델이 사용할 수 있는 도구를 제어하여 보안을 크게 강화할 수 있습니다. 이는 tools.core 및 tools.exclude 설정을 통해 달성됩니다. 사용 가능한 도구 목록은 도구 문서를 참조하세요.

coreTools를 사용한 허용 목록

가장 안전한 접근 방식은 사용자가 실행할 수 있는 도구와 명령을 허용 목록에 명시적으로 추가하는 것입니다. 이렇게 하면 승인된 목록에 없는 도구의 사용을 방지할 수 있습니다.

예시: 안전한 읽기 전용 파일 작업 및 파일 나열만 허용합니다.

{
  "tools": {
    "core": ["ReadFileTool", "GlobTool", "ShellTool(ls)"]
  }
}

excludeTools를 사용한 차단 목록

또는 환경에서 위험한 것으로 간주되는 특정 도구를 차단 목록에 추가할 수 있습니다.

예시: 파일 제거를 위한 셸 도구 사용을 방지합니다.

{
  "tools": {
    "exclude": ["ShellTool(rm -rf)"]
  }
}

보안 참고 사항: excludeTools를 사용한 차단 목록은 coreTools를 사용한 허용 목록보다 보안 수준이 낮습니다. 알려진 나쁜 명령을 차단하는 데 의존하며, 영리한 사용자는 단순한 문자열 기반 차단을 우회할 방법을 찾을 수 있기 때문입니다. 허용 목록을 사용하는 것이 권장되는 접근 방식입니다.

YOLO 모드 비활성화

사용자가 도구 실행에 대한 확인 프롬프트를 우회할 수 없도록 정책 수준에서 YOLO 모드를 비활성화할 수 있습니다. 이는 모델이 사용자의 명시적 승인 없이 도구를 실행하는 것을 방지하므로 중요한 안전 계층을 추가합니다.

예시: 모든 도구 실행에 사용자 확인을 강제합니다.

{
  "security": {
    "disableYoloMode": true
  }
}

이 설정은 의도하지 않은 도구 실행을 방지하기 위해 기업 환경에서 강력히 권장됩니다.

사용자 정의 도구(MCP 서버) 관리

조직에서 Model-Context Protocol (MCP) 서버를 통해 사용자 정의 도구를 사용하는 경우, 보안 정책을 효과적으로 적용하기 위해 서버 구성이 관리되는 방식을 이해하는 것이 중요합니다.

MCP 서버 구성이 병합되는 방식

Gemini CLI는 시스템, 작업 공간, 사용자 등 3가지 수준에서 settings.json 파일을 로드합니다. mcpServers 객체의 경우 이러한 구성이 병합됩니다:

  1. 병합: 3가지 수준 모두의 서버 목록이 단일 목록으로 결합됩니다.
  2. 우선순위: 동일한 이름을 가진 서버가 여러 수준에서 정의된 경우(예: corp-api라는 서버가 시스템 및 사용자 설정 모두에 존재함), 가장 높은 우선순위 수준의 정의가 사용됩니다. 우선순위 순서는 시스템 > 작업 공간 > 사용자입니다.

즉, 사용자는 시스템 수준 설정에서 이미 정의된 서버의 정의를 재정의할 수 없습니다. 하지만 다른 이름을 가진 새로운 서버를 추가할 수는 있습니다.

Enforcing a catalog of tools

The security of your MCP tool ecosystem depends on a combination of defining the canonical servers and adding their names to an allowlist.

Restricting tools within an MCP server

For even greater security, especially when dealing with third-party MCP servers, you can restrict which specific tools from a server are exposed to the model. This is done using the includeTools and excludeTools properties within a server's definition. This allows you to use a subset of tools from a server without allowing potentially dangerous ones.

최소 권한 원칙에 따라 includeTools를 사용하여 필요한 도구만의 허용 목록을 만드는 것이 적극 권장됩니다.

예시: 타사 MCP 서버가 delete-ticket과 같은 다른 도구를 제공하더라도 code-search 및 get-ticket-details 도구만 허용합니다.

{
  "mcp": {
    "allowed": ["third-party-analyzer"]
  },
  "mcpServers": {
    "third-party-analyzer": {
      "command": "/usr/local/bin/start-3p-analyzer.sh",
      "includeTools": ["code-search", "get-ticket-details"]
    }
  }
}

더 안전한 패턴: 시스템 설정에서 정의 및 허용 목록에 추가

안전하게 중앙에서 관리되는 도구 카탈로그를 만들기 위해, 시스템 관리자는 시스템 수준 settings.json 파일에서 다음 두 가지를 반드시 수행해야 합니다:

  1. mcpServers 객체에서 승인된 모든 서버에 대한 전체 구성을 정의합니다. 이렇게 하면 사용자가 동일한 이름의 서버를 정의하더라도 안전한 시스템 수준 정의가 우선합니다.
  2. mcp.allowed 설정을 사용하여 해당 서버의 이름을 허용 목록에 추가합니다. 이는 사용자가 이 목록에 없는 서버를 실행하는 것을 방지하는 중요한 보안 단계입니다. 이 설정이 생략되면 CLI는 사용자가 정의한 모든 서버를 병합하고 허용합니다.

시스템 settings.json 예시:

  1. 승인된 모든 서버의 이름을 허용 목록에 추가합니다. 이는 사용자가 자신의 서버를 추가하는 것을 방지합니다.

  2. 허용 목록에 있는 각 서버에 대한 표준 정의를 제공합니다.

{
  "mcp": {
    "allowed": ["corp-data-api", "source-code-analyzer"]
  },
  "mcpServers": {
    "corp-data-api": {
      "command": "/usr/local/bin/start-corp-api.sh",
      "timeout": 5000
    },
    "source-code-analyzer": {
      "command": "/usr/local/bin/start-analyzer.sh"
    }
  }
}

이 패턴은 정의와 허용 목록을 모두 사용하므로 더 안전합니다. 사용자가 정의한 서버는 시스템 정의에 의해 재정의되거나(이름이 같은 경우) 이름이 mcp.allowed 목록에 없기 때문에 차단됩니다.

덜 안전한 패턴: 허용 목록 생략

관리자가 mcpServers 객체를 정의했지만 mcp.allowed 허용 목록을 지정하지 않은 경우, 사용자는 자신의 서버를 추가할 수 있습니다.

시스템 settings.json 예시:

이 구성은 서버를 정의하지만 허용 목록을 강제하지 않습니다. 관리자가 "mcp.allowed" 설정을 포함하지 않았습니다.

{
  "mcpServers": {
    "corp-data-api": {
      "command": "/usr/local/bin/start-corp-api.sh"
    }
  }
}

이 시나리오에서 사용자는 로컬 settings.json에 자신의 서버를 추가할 수 있습니다. 병합된 결과를 필터링할 mcp.allowed 목록이 없으므로, 사용자의 서버는 사용 가능한 도구 목록에 추가되고 실행이 허용됩니다.

보안을 위한 샌드박싱 강제

잠재적으로 유해한 작업의 위험을 완화하기 위해 모든 도구 실행에 샌드박싱 사용을 강제할 수 있습니다. 샌드박스는 컨테이너화된 환경에서 도구 실행을 격리합니다.

예시: 모든 도구 실행이 Docker 샌드박스 내에서 발생하도록 강제합니다.

{
  "tools": {
    "sandbox": "docker"
  }
}

샌드박싱 문서에 설명된 대로 사용자 정의 sandbox.Dockerfile을 빌드하여 샌드박스에 강화된 사용자 정의 Docker 이미지를 지정할 수도 있습니다.

프록시를 통한 네트워크 액세스 제어

네트워크 정책이 엄격한 기업 환경에서는 Gemini CLI가 모든 아웃바운드 트래픽을 기업 프록시를 통해 라우팅하도록 구성할 수 있습니다. 이는 환경 변수를 통해 설정할 수 있지만, mcpServers 구성을 통해 사용자 정의 도구에 대해서도 강제할 수 있습니다.

예시 (MCP 서버용):

{
  "mcpServers": {
    "proxied-server": {
      "command": "node",
      "args": ["mcp_server.js"],
      "env": {
        "HTTP_PROXY": "http://proxy.example.com:8080",
        "HTTPS_PROXY": "http://proxy.example.com:8080"
      }
    }
  }
}

원격 측정 및 감사

감사 및 모니터링 목적으로 Gemini CLI가 원격 측정 데이터를 중앙 위치로 보내도록 구성할 수 있습니다. 이를 통해 도구 사용 및 기타 이벤트를 추적할 수 있습니다. 자세한 내용은 원격 측정 문서를 참조하세요.

예시: 원격 측정을 활성화하고 로컬 OTLP 수집기로 보냅니다. otlpEndpoint가 지정되지 않은 경우 기본값은 http://localhost:4317입니다.

{
  "telemetry": {
    "enabled": true,
    "target": "gcp",
    "logPrompts": false
  }
}

참고: 사용자 프롬프트에서 잠재적으로 민감한 정보가 수집되는 것을 방지하려면 기업 설정에서 logPrompts를 false로 설정해야 합니다.

인증

시스템 수준 settings.json 파일에서 enforcedAuthType을 설정하여 모든 사용자에게 특정 인증 방법을 강제할 수 있습니다. 이렇게 하면 사용자가 다른 인증 방법을 선택하는 것을 방지할 수 있습니다. 자세한 내용은 인증 문서를 참조하세요.

예시: 모든 사용자에게 Google 로그인 사용을 강제합니다.

{
  "enforcedAuthType": "oauth-personal"
}

사용자가 다른 인증 방법을 구성한 경우, 강제된 방법으로 전환하라는 메시지가 표시됩니다. 비대화형 모드에서 구성된 인증 방법이 강제된 방법과 일치하지 않으면 CLI는 오류와 함께 종료됩니다.

기업 도메인으로 로그인 제한

Google Workspace를 사용하는 기업의 경우, 사용자가 기업 Google 계정으로만 인증하도록 강제할 수 있습니다. 이는 Gemini CLI 자체가 아닌 프록시 서버에서 구성되는 네트워크 수준 제어입니다. Google에 대한 인증 요청을 가로채고 특별한 HTTP 헤더를 추가하는 방식으로 작동합니다.

이 정책은 사용자가 개인 Gmail 계정이나 기타 비기업 Google 계정으로 로그인하는 것을 방지합니다.

자세한 지침은 소비자 계정 액세스 차단 (opens in a new tab)에 대한 Google Workspace 관리자 도움말 문서를 참조하세요.

일반적인 단계는 다음과 같습니다:

  1. 요청 가로채기: google.com에 대한 모든 요청을 가로채도록 웹 프록시를 구성합니다.
  2. HTTP 헤더 추가: 가로챈 각 요청에 X-GoogApps-Allowed-Domains HTTP 헤더를 추가합니다.
  3. 도메인 지정: 헤더 값은 승인된 Google Workspace 도메인 이름의 쉼표로 구분된 목록이어야 합니다.

예시 헤더:

X-GoogApps-Allowed-Domains: my-corporate-domain.com, secondary-domain.com

이 헤더가 있으면 Google 인증 서비스는 지정된 도메인에 속한 계정의 로그인만 허용합니다.

종합: 예시 시스템 settings.json

다음은 위에서 논의된 여러 패턴을 결합하여 Gemini CLI를 위한 안전하고 통제된 환경을 만드는 시스템 settings.json 파일의 예입니다.

{
  "tools": {
    "sandbox": "docker",
    "core": [
      "ReadFileTool",
      "GlobTool",
      "ShellTool(ls)",
      "ShellTool(cat)",
      "ShellTool(grep)"
    ]
  },
  "mcp": {
    "allowed": ["corp-tools"]
  },
  "mcpServers": {
    "corp-tools": {
      "command": "/opt/gemini-tools/start.sh",
      "timeout": 5000
    }
  },
  "telemetry": {
    "enabled": true,
    "target": "gcp",
    "otlpEndpoint": "https://telemetry-prod.example.com:4317",
    "logPrompts": false
  },
  "advanced": {
    "bugCommand": {
      "urlTemplate": "https://servicedesk.example.com/new-ticket?title={title}&details={info}"
    }
  },
  "privacy": {
    "usageStatisticsEnabled": false
  }
}

이 구성은 다음과 같이 작동합니다:

  • 모든 도구 실행을 Docker 샌드박스로 강제합니다.
  • 소수의 안전한 셸 명령 및 파일 도구에 대해 허용 목록을 엄격하게 사용합니다.
  • 사용자 정의 도구를 위한 단일 기업 MCP 서버를 정의하고 허용합니다.
  • 감사를 위해 원격 측정을 활성화하지만, 프롬프트 내용은 기록하지 않습니다.
  • /bug 명령을 내부 티켓팅 시스템으로 리디렉션합니다.
  • 일반 사용 통계 수집을 비활성화합니다.
사용자 정의 명령헤드리스 모드 & 스크립팅