← Quay lại blog

Proxy cho Gemini CLI và VS Code Code Assist: truy cập từ khu vực không hỗ trợ Google

Hướng dẫn từng bước để cấu hình proxy HTTP/HTTPS cho Gemini CLI và tiện ích mở rộng Gemini Code Assist trong VS Code, nếu khu vực của bạn không được Google hỗ trợ.

📅14 tháng 11, 2026

Nếu khi cố gắng xác thực trong Gemini CLI hoặc sử dụng tiện ích mở rộng Gemini Code Assist trong VS Code bạn thấy lỗi như FAILED_PRECONDITION: User location is not supported — vấn đề không phải ở tài khoản của bạn và cũng không phải ở mã. Google AI Studio và Gemini API được triển khai không đồng đều ở các quốc gia, và một số khu vực bị loại trừ khỏi danh sách hỗ trợ. Vấn đề này có thể được giải quyết bằng cách cấu hình proxy với địa chỉ IP từ một quốc gia được phép — và sau đây chúng ta sẽ tìm hiểu cách thực hiện điều này đúng cách trong terminal, trong VS Code và ở cấp độ biến môi trường.

Gemini CLI và Gemini Code Assist là gì

Gemini CLI là một công cụ dòng lệnh của Google cho phép giao tiếp với các mô hình Gemini ngay từ terminal: viết mã, tạo lệnh, phân tích tệp dự án và thực hiện các tác vụ mà không cần rời khỏi môi trường làm việc. Nó truy cập API trên các miền generativelanguage.googleapis.com hoặc thông qua Vertex AI, tùy thuộc vào phương thức xác thực bạn sử dụng — khóa Google AI Studio hoặc tài khoản Google Cloud.

Gemini Code Assist là một tiện ích mở rộng cho VS Code (cũng như cho JetBrains IDE), tích hợp gợi ý, tự động hoàn thành và trò chuyện với mô hình ngay trong trình soạn thảo mã. Về cơ bản, đây là cùng một API, nhưng được gọi từ IDE thông qua tiện ích mở rộng, chứ không phải từ dòng lệnh. Cả hai công cụ đều sử dụng cùng một backend, vì vậy vấn đề chặn khu vực xuất hiện tương tự trong cả hai trường hợp — tiện ích mở rộng không thể thiết lập phiên hoặc trả về lỗi khi thực hiện yêu cầu đầu tiên đến mô hình.

Một điểm quan trọng: cả hai công cụ đều thực hiện các yêu cầu mạng không chỉ đến chính API tạo ra mà còn đến các dịch vụ xác thực của Google (OAuth, Identity Toolkit). Nếu proxy chỉ được cấu hình cho một điểm cuối, xác thực có thể thành công nhưng việc tạo ra thì không, hoặc ngược lại. Do đó, proxy cần được thiết lập ở cấp độ biến môi trường hệ thống, chứ không chỉ ở một nơi cụ thể.

Tại sao Gemini không khả dụng ở khu vực của bạn

Google thường triển khai các sản phẩm AI mới theo từng giai đoạn: trước tiên ở Mỹ và một phần châu Âu, sau đó là các quốc gia khác. Đối với Gemini, điều này thể hiện qua các hạn chế địa lý ở cấp độ API — máy chủ kiểm tra địa chỉ IP của yêu cầu đến (và đôi khi cả địa chỉ thanh toán của tài khoản Google) và so sánh với danh sách các vị trí được phép. Nếu quốc gia không có trong danh sách, yêu cầu sẽ bị ngắt với lỗi precondition hoặc đơn giản là hết thời gian mà không có lời giải thích rõ ràng.

Đây không phải là chặn theo nghĩa thông thường — nhà cung cấp ở quốc gia của bạn không cắt giảm gì cả, mà là một bộ lọc địa lý từ phía Google. Do đó, VPN với IP chung thường không cứu vãn được: những địa chỉ này thường được hàng ngàn người sử dụng, Google đánh dấu chúng là nghi ngờ và yêu cầu xác thực CAPTCHA, hoặc vẫn cắt giảm theo địa lý nếu dải IP được đăng ký không chính thức ở quốc gia đó. Cần một địa chỉ trông giống như một IP gia đình hoặc di động thông thường từ một khu vực được hỗ trợ — tức là nhiệm vụ tương tự như những gì mà proxy cư trú và di động giải quyết.

Chọn loại proxy nào để làm việc với Gemini API

Đối với các công cụ phát triển như Gemini CLI, các thông số chính của proxy là độ ổn định của phiên (để không bị ngắt kết nối giữa chừng khi tạo ra phản hồi dài), tốc độ và độ "sạch" của IP đối với các hệ thống chống gian lận của Google. Dưới đây là so sánh ba loại:

Loại proxy Tốc độ Rủi ro bị chặn địa lý Khi nào sử dụng
Proxy trung tâm dữ liệu Cao Trung bình-cao Kiểm tra nhanh, yêu cầu đơn lẻ đến API
Proxy cư trú Trung bình-cao Thấp Làm việc hàng ngày với Gemini CLI và Code Assist
Proxy di động Trung bình Tối thiểu Khi IP cư trú vẫn bị chặn bởi bộ lọc địa lý

Trên thực tế, để làm việc hàng ngày, các nhà phát triển thường thấy proxy cư trú gắn với một quốc gia cụ thể và tốt nhất là có phiên sticky từ 10-30 phút — điều này đủ để không bị ngắt kết nối xác thực OAuth và không bị mất phiên terminal giữa chừng khi tạo mã. Proxy trung tâm dữ liệu rẻ hơn và nhanh hơn, nhưng một số dải IP đã bị Google nhận diện và đôi khi yêu cầu xác thực tài khoản bổ sung khi truy cập qua IP đó. Proxy di động nên được giữ sẵn — nếu địa chỉ cư trú vì lý do nào đó bị đưa vào danh sách nghi ngờ, mạng di động của nhà cung cấp thường vượt qua kiểm tra địa lý mà không gặp vấn đề gì.

Cấu hình proxy trong terminal: Linux, macOS, Windows

Gemini CLI, giống như hầu hết các tiện ích dòng lệnh trên Node.js (và nó được viết trên nền tảng này), tôn trọng các biến môi trường tiêu chuẩn HTTP_PROXY và HTTPS_PROXY. Điều này đủ để chuyển toàn bộ lưu lượng CLI qua proxy mà không cần chỉnh sửa cấu hình ứng dụng.

Đối với macOS và Linux (bash/zsh), hãy thêm vào phiên hiện tại:

export HTTP_PROXY="http://login:password@proxy_host:port"
export HTTPS_PROXY="http://login:password@proxy_host:port"
export NO_PROXY="localhost,127.0.0.1"

gemini --version

Để proxy được áp dụng liên tục, không chỉ trong phiên terminal hiện tại, hãy thêm những dòng này vào ~/.zshrc hoặc ~/.bashrc và khởi động lại terminal bằng lệnh source ~/.zshrc.

Đối với Windows trong PowerShell, các biến được thiết lập như sau:

$env:HTTP_PROXY = "http://login:password@proxy_host:port"
$env:HTTPS_PROXY = "http://login:password@proxy_host:port"

gemini --version

Nếu bạn muốn các biến được lưu lại sau khi khởi động lại PowerShell, hãy sử dụng [System.Environment]::SetEnvironmentVariable("HTTPS_PROXY", "http://login:password@proxy_host:port", "User") — biến này sẽ được ghi vào hồ sơ người dùng Windows.

Nếu proxy của bạn yêu cầu xác thực riêng mà không có tên đăng nhập trong URL (ví dụ, theo danh sách IP trắng), chỉ cần bỏ tên đăng nhập và mật khẩu khỏi chuỗi kết nối và thêm IP của máy chủ hoặc máy làm việc của bạn vào danh sách trắng trên bảng điều khiển của nhà cung cấp proxy.

Cấu hình proxy trong VS Code cho Code Assist

VS Code có các thiết lập proxy riêng, không tự động kế thừa từ các biến môi trường hệ thống nếu không bật tùy chọn tương ứng. Mở settings.json (Ctrl+Shift+P → "Preferences: Open User Settings (JSON)") và thêm:

{
  "http.proxy": "http://login:password@proxy_host:port",
  "http.proxyStrictSSL": false,
  "http.proxySupport": "override"
}

Tham số http.proxySupport: "override" là rất quan trọng: nếu không có nó, VS Code có thể tiếp tục sử dụng proxy hệ thống hoặc hoàn toàn bỏ qua thiết lập cho các tiện ích mở rộng riêng lẻ. Sau khi chỉnh sửa cài đặt, hãy khởi động lại hoàn toàn VS Code (không chỉ đơn giản là khởi động lại cửa sổ), vì tiện ích mở rộng Gemini Code Assist khởi tạo khách hàng mạng chỉ một lần khi ứng dụng khởi động.

Nếu tiện ích mở rộng vẫn không thấy proxy, hãy kiểm tra thiết lập http.proxyAuthorization — trong một số trường hợp hiếm hoi, các bản dựng doanh nghiệp của VS Code chặn việc truyền tên đăng nhập và mật khẩu trong URL proxy vì lý do bảo mật, và trong trường hợp đó, thông tin đăng nhập cần được truyền qua tiêu đề Proxy-Authorization ở định dạng base64.

Một điểm riêng biệt — hãy tạm thời tắt các tiện ích mở rộng chẩn đoán như các khách hàng VPN doanh nghiệp và phần mềm diệt virus có khả năng chặn lưu lượng (kiểm tra SSL). Chúng thường thay thế chứng chỉ ngay lập tức, và Gemini Code Assist, kiểm tra chuỗi chứng chỉ của Google một cách nghiêm ngặt, sẽ ngắt kết nối với lỗi TLS, điều này dễ bị nhầm lẫn với vấn đề của chính proxy.

Cấu hình proxy trong chính Gemini CLI

Ngoài các biến môi trường, trong Gemini CLI bạn có thể thiết lập proxy thông qua tệp cấu hình dự án hoặc cài đặt toàn cầu của người dùng — điều này rất tiện lợi nếu bạn muốn sử dụng các proxy khác nhau cho các dự án khác nhau mà không cần chạm vào các biến hệ thống. Cấu hình thường được lưu trữ trong ~/.gemini/settings.json hoặc trong tệp .env bên trong thư mục dự án:

# .env ở gốc dự án
GEMINI_API_KEY=khóa_của_bạn
HTTPS_PROXY=http://login:password@proxy_host:port
HTTP_PROXY=http://login:password@proxy_host:port

Nếu bạn xác thực qua tài khoản Google Cloud (Vertex AI), thay vì qua khóa AI Studio, bạn cũng cần đảm bảo rằng proxy được sử dụng cho tiện ích gcloud, qua đó diễn ra quy trình OAuth. Đối với nó, proxy được thiết lập riêng:

gcloud config set proxy/type http
gcloud config set proxy/address proxy_host
gcloud config set proxy/port port
gcloud config set proxy/username login
gcloud config set proxy/password password

Nếu sau đó gcloud auth login vẫn mở trình duyệt với IP thực (không phải IP proxy) để xác nhận đăng nhập, hãy lưu ý: trang OAuth tự mở trong trình duyệt hệ thống của bạn trực tiếp, và nếu trình duyệt không được cấu hình với cùng một proxy, phiên xác thực cuối cùng có thể nhận được mã thông báo gắn với IP thực của bạn. Để đảm bảo tính nhất quán hoàn toàn, hãy cấu hình proxy trong trình duyệt mà bạn xác nhận đăng nhập — ví dụ, thông qua tiện ích proxy hoặc cài đặt mạng hệ thống trong thời gian xác thực.

Kiểm tra kết nối: curl và Python

Trước khi tìm hiểu lý do tại sao Gemini CLI không hoạt động, hãy đảm bảo rằng proxy về cơ bản đang chuyển tiếp lưu lượng đến API Google. Cách nhanh nhất là thực hiện yêu cầu trực tiếp qua curl:

curl -x http://login:password@proxy_host:port \
  "https://generativelanguage.googleapis.com/v1beta/models?key=KHÓA_API_CỦA_BẠN"

Nếu phản hồi nhận được là JSON với danh sách các mô hình (gemini-1.5-flash, gemini-1.5-pro, v.v.) — proxy hoạt động và khu vực được hỗ trợ. Nếu bạn thấy 403 hoặc FAILED_PRECONDITION — vấn đề nằm ở cấp độ bộ lọc địa lý, cần thay đổi quốc gia proxy.

Để chẩn đoán chi tiết hơn, bạn có thể sử dụng Python với việc chỉ định rõ proxy cho phiên:

import requests

proxies = {
    "http": "http://login:password@proxy_host:port",
    "https": "http://login:password@proxy_host:port",
}

url = "https://generativelanguage.googleapis.com/v1beta/models"
params = {"key": "KHÓA_API_CỦA_BẠN"}

response = requests.get(url, params=params, proxies=proxies, timeout=15)
print(response.status_code)
print(response.text[:500])

Kịch bản như vậy rất tiện để giữ bên cạnh như một kiểm tra nhanh trước khi khởi động một phiên đầy đủ trong CLI hoặc IDE — nó cho thấy trong vài giây liệu mạng, khóa hay khu vực IP có vấn đề hay không.

Các lỗi thường gặp và cách giải quyết

Lỗi "User location is not supported" ngay cả sau khi kết nối proxy thường có nghĩa là IP của máy chủ proxy hoặc nằm trong một quốc gia không được hỗ trợ, hoặc Google đã xác định nó là trung tâm dữ liệu và áp dụng kiểm tra bổ sung. Giải pháp — chuyển sang IP cư trú hoặc di động từ Mỹ hoặc quốc gia khác với sự hỗ trợ đầy đủ cho Gemini.

Timeout khi tạo ra các phản hồi dài thường liên quan đến phiên proxy không ổn định — IP thay đổi giữa chừng trong yêu cầu, và kết nối bị ngắt. Cần một phiên sticky trong thời gian dài hơn thời gian yêu cầu điển hình (thường 10-15 phút với một chút thời gian dự phòng là đủ ngay cả cho các tạo mã lớn).

Lỗi SSL/TLS handshake failed gần như luôn chỉ ra việc lưu lượng bị chặn bởi phần mềm diệt virus, tường lửa doanh nghiệp hoặc cấu hình không đúng proxyStrictSSL trong VS Code. Kiểm tra xem có phần mềm nào trên máy có kiểm tra SSL không, và tạm thời tắt nó để chẩn đoán.

CLI hoạt động, nhưng tiện ích mở rộng trong VS Code thì không (hoặc ngược lại) có nghĩa là các biến môi trường không được truyền vào quá trình VS Code. Đây là tình huống phổ biến trong Linux và macOS, nếu VS Code được khởi động không từ terminal mà bạn đã xuất biến, mà từ biểu tượng trong menu hệ thống. Trong trường hợp đó, các biến cần được thiết lập thông qua settings.json, như đã mô tả ở trên, chứ không nên dựa vào việc kế thừa từ shell.

Gắn IP với khu vực của API key và bảo mật

Một điểm tinh tế riêng mà thường bị bỏ qua: nếu API key hoặc dự án Google Cloud được tạo với sự gắn kết với một khu vực thanh toán cụ thể, việc thay đổi IP proxy có thể dẫn đến sự không khớp giữa vị trí mong đợi và thực tế, và Google đôi khi yêu cầu xác thực lại qua SMS hoặc email. Để giảm tần suất kiểm tra như vậy, hãy cố gắng sử dụng proxy với IP cố định (không thay đổi cho mỗi yêu cầu) từ cùng một quốc gia — điều này trông giống như hành vi bình thường của người dùng sống ở quốc gia đó, chứ không phải như một hoạt động nghi ngờ.

Nếu bạn làm việc với nhiều dự án hoặc khóa cùng một lúc và sử dụng trình duyệt chống phát hiện như Dolphin Anty hoặc AdsPower để cách ly các hồ sơ (điều này có thể xảy ra nếu bạn thử nghiệm tích hợp Gemini trong các môi trường trình duyệt khác nhau), hãy gắn mỗi hồ sơ với một proxy riêng có vị trí địa lý cố định — như vậy sẽ giảm rủi ro rằng một dự án "kéo" theo những nghi ngờ từ các IP khác.

Ngoài ra, không nên sử dụng cùng một proxy miễn phí hoặc chung cho Gemini và đồng thời cho các tác vụ khác có tải cao — số lượng phiên đồng thời lớn từ một IP làm tăng khả năng bị giới hạn tỷ lệ hoặc bị chặn tạm thời ở cấp độ Google, điều này trông giống như một vấn đề với khu vực, mặc dù nguyên nhân hoàn toàn khác.

Kết luận

Hạn chế khu vực của Gemini CLI và Gemini Code Assist được giải quyết ở cấp độ mạng: proxy cần được thiết lập đồng thời trong các biến môi trường hệ thống, trong cài đặt VS Code và, khi sử dụng Google Cloud, trong cấu hình gcloud — chỉ khi đó cả ba điểm truy cập (CLI, tiện ích mở rộng IDE và xác thực OAuth) sẽ hoạt động qua cùng một IP mà không bị mất đồng bộ. Trước khi bắt đầu làm việc đầy đủ, hãy luôn kiểm tra kết nối bằng một yêu cầu curl đơn giản — điều này tiết kiệm hàng giờ chẩn đoán khi vấn đề thực sự không phải ở mã mà ở quốc gia của proxy.

Để làm việc ổn định hàng ngày với Gemini CLI, tốt nhất là sử dụng proxy cư trú với vị trí địa lý cố định và phiên sticky dài — chúng trông giống như IP gia đình thông thường và hiếm khi gây ra các kiểm tra bổ sung từ Google. Nếu địa chỉ cư trú vẫn bị chặn bởi bộ lọc địa lý, hãy thử proxy di động, và cho các thử nghiệm API nhanh mà không cần phiên dài, proxy trung tâm dữ liệu là đủ.