Làm thế nào để thay đổi thư mục của Gemini CLI

Google’s open-source Gemini CLI—tác nhân AI dựa trên terminal đưa Gemini vào shell của bạn—đã nhanh chóng hoàn thiện kể từ khi ra mắt và hiện hỗ trợ cấu hình phong phú, tệp ngữ cảnh dự án (GEMINI.md / .gemini), lệnh slash tùy chỉnh, và điều khiển thư mục không gian làm việc. Dự án đang phát triển tích cực trên GitHub (repo chính thức), đã bước vào giai đoạn xem trước công khai với hạn mức rộng rãi, và đang được tích hợp vào các công cụ nhà phát triển khác (tích hợp trình soạn thảo và CI/Actions). Nhưng khi đội nhóm mở rộng, hoặc khi bạn làm việc qua nhiều ổ đĩa hay các môi trường hạn chế (container, laptop do công ty quản lý, Cloud Shell, hệ thống Windows), bạn sẽ nhanh chóng gặp một câu hỏi thực tiễn: Gemini lưu trữ tệp ở đâu, và làm thế nào để thay đổi các thư mục mà Gemini đọc và ghi?

What is Gemini CLI?

Gemini CLI là tác nhân AI dòng lệnh mã nguồn mở của Google đưa sức mạnh của các mô hình Gemini trực tiếp vào terminal của bạn. Nó cung cấp khả năng tác nhân tương tác để hỗ trợ mã, kiểm tra tệp và dự án, thực thi lệnh shell (có cơ chế bảo vệ), và tích hợp các công cụ như Google Search, Model Context Protocol (MCP) extensions, và các công cụ tạo nội dung đa phương tiện đi kèm với Gemini. CLI được thiết kế nhẹ, có thể script hóa và mở rộng; có sẵn từ kho chính thức và được đóng gói để cài đặt dễ dàng.

Why the directory matters

Gemini CLI lưu trữ cấu hình (ví dụ, settings.json), lời nhắc hệ thống hoặc ngữ cảnh (GEMINI.md), thông tin xác thực được lưu vào bộ nhớ đệm, định danh telemetry, và trạng thái lưu trữ lâu dài khác bên trong thư mục .gemini. Vị trí của thư mục đó quyết định:

• CLI sẽ tải những thiết lập nào (toàn cục so với theo dự án),
• các tệp “memory” mà tác nhân sẽ đọc,
• nơi thông tin xác thực được lưu vào bộ nhớ đệm (ảnh hưởng đến hành vi đăng nhập),
• khả năng tái lập giữa máy và CI khi bạn muốn cung cấp một repo cấu hình tùy chỉnh.

Việc hiểu và (nếu cần) thay đổi thư mục giúp ích cho quy trình nhiều dự án, CI, triển khai container, và các đội ngũ có kho lưu trữ cấu hình tập trung.

Where does Gemini CLI store configuration by default?

Theo mặc định CLI sử dụng thư mục .gemini. Đối với hầu hết cài đặt người dùng, điều đó tương ứng với ~/.gemini (thư mục .gemini trong thư mục home của bạn). CLI cũng hỗ trợ các tệp .gemini ở cấp dự án (ví dụ, .gemini/settings.json tại thư mục gốc dự án) sẽ ghi đè thiết lập người dùng khi bạn hoạt động trong thư mục dự án đó. Thiết lập cấp hệ thống được đọc từ các vị trí phụ thuộc HĐH (chẳng hạn /etc/ trên Linux hoặc %PROGRAMDATA% trên Windows) khi áp dụng. Các đường dẫn điển hình:

• Linux / macOS: ~/.gemini/ (ví dụ /home/alice/.gemini hoặc /Users/alice/.gemini).
• Windows: %USERPROFILE%\.gemini (ví dụ C:\Users\Alice\.gemini).
  Bên trong .gemini bạn thường sẽ thấy settings.json, GEMINI.md, commands/, và các bộ nhớ đệm cục bộ. CLI cũng đọc các thư mục .gemini/ theo dự án (thư mục gốc dự án) cho thiết lập cấp dự án.

Mặc định này quan trọng: theo lịch sử, thư mục cấu hình đã được cố định (hard-coded) là .gemini trong thư mục home

---

How can I change or redirect Gemini CLI’s configuration directory?

Có một số cách thực tế — từ đơn giản nhất (làm việc trong thư mục mong muốn) đến vững chắc hơn (biến môi trường hoặc chuyển hướng hệ thống tệp). Hãy chọn cách tiếp cận tùy thuộc vào việc bạn có kiểm soát môi trường chạy (máy dev cục bộ so với CI), bạn đang dùng HĐH nào, và bạn muốn thay đổi tạm thời hay vĩnh viễn.

1) Use a project-level .gemini (recommended for per-project settings)

Nếu bạn muốn thiết lập theo từng dự án, hãy tạo thư mục con .gemini trong thư mục gốc dự án và đặt settings.json, GEMINI.md, và các tệp dự án khác vào đó. Gemini CLI ưu tiên thiết lập dự án khi bạn chạy từ thư mục dự án:

your-project/├─ .gemini/│  ├─ settings.json│  └─ GEMINI.md└─ src/

Khởi chạy gemini khi shell của bạn đang ở your-project/ và CLI sẽ nhận các tệp .gemini từ cây đó (nó tìm kiếm ngược lên để xác định ngữ cảnh dự án). Đây là phương pháp an toàn, rõ ràng nhất cho cấu hình theo dự án.

2) Use documented environment variables (when supported)

Mã nguồn và tài liệu của Gemini CLI tham chiếu một số biến môi trường dùng để thay đổi hành vi. Một số dành cho thiết lập hệ thống hoặc ghi đè tệp đặc biệt:

• GEMINI_API_KEY, GEMINI_MODEL, v.v. thường được dùng cho xác thực và chọn mô hình.
• Có tham chiếu trong mã và tài liệu tới các biến như GEMINI_CLI_SYSTEM_SETTINGS_PATH (dùng để ghi đè đường dẫn thiết lập hệ thống) và các hằng như GEMINI_CONFIG_DIR (tên mặc định .gemini dùng trong mã). Một số yêu cầu cộng đồng và PR đề xuất thêm hoặc tôn trọng biến môi trường GEMINI_CONFIG_DIR để cho phép người dùng di chuyển toàn bộ thư mục cấu hình.

Example (bash / macOS / Linux):

# Temporary for this shell sessionexport GEMINI_CONFIG_DIR="$HOME/custom_gemini_dir"​# Or override system settings path if your install supports it:export GEMINI_CLI_SYSTEM_SETTINGS_PATH="/etc/my-gemini/system.settings.json"​# Then rungemini

PowerShell (Windows):

$env:GEMINI_CONFIG_DIR = 'C:\Users\you\CustomGemini'gemini

Lưu ý quan trọng: theo các thảo luận và issue mới nhất từ cộng đồng, GEMINI_CONFIG_DIR đã được yêu cầu và được tham chiếu ở một số nơi trong mã — nhưng đã có báo cáo về lỗi theo nền tảng và hành vi không nhất quán (đặc biệt trên Windows). Điều đó có nghĩa là việc chuyển hướng dựa trên biến môi trường có thể không đáng tin cậy một cách nhất quán trên mọi nền tảng hoặc bản phát hành. Hãy kiểm tra ghi chú phát hành và issue của repo Gemini CLI cho phiên bản bạn cài đặt nếu bạn phụ thuộc vào cách này.

3) Add directories to Gemini’s workspace inside a session

Nếu bạn muốn Gemini biết thêm các thư mục (để đọc tệp làm ngữ cảnh), có bộ lệnh tương tác /directory. Ví dụ:

/directory add path/to/another/project/directory list

Cách này không di chuyển thư mục cấu hình, nhưng cho phép tác nhân đưa các tệp từ thư mục khác vào ngữ cảnh không gian làm việc. Hữu ích khi bạn muốn tác nhân tham chiếu các repo khác mà không thay đổi cấu hình toàn cục.

4) Create a symlink or filesystem bind (practical workaround)

Nếu CLI không chấp nhận ghi đè bằng biến môi trường hoặc bạn cần giải pháp đáng tin cậy ở cấp độ liên tiến trình, hãy dùng chuyển hướng hệ thống tệp:

On Unix/macOS:

# move the original config foldermv ~/.gemini ~/gemini_backup​# create a symlink to your desired locationln -s /path/to/central/gemini-config ~/.gemini

On Windows (PowerShell administrative prompt):

# Move the original directoryMove-Item -Path $env:USERPROFILE\.gemini -Destination C:\GeminiConfigBackup​# Create a junction (administrator)New-Item -ItemType Junction -Path $env:USERPROFILE\.gemini -Target C:\CentralGeminiConfig

Cách này buộc CLI đọc từ vị trí bạn mong muốn mà không cần hỗ trợ gốc trong CLI. Lưu ý: symlink/junction cần quyền hệ thống tệp phù hợp và có thể hành xử khác nhau trong môi trường container hoặc Windows. Sử dụng cẩn trọng. (Xem “ghi chú dành riêng cho Windows” bên dưới.)

5) Change the effective home directory for the process (container/CI trick)

Khi chạy trong CI, container, hoặc môi trường tạm thời, bạn có thể thay đổi biến $HOME (Unix) hoặc %USERPROFILE% (Windows) cho tiến trình gemini để ~/.gemini mặc định trỏ đến đường dẫn bạn kiểm soát:

# Run gemini with a custom HOME (bash)HOME=/ci/workspace/you gemini --some-command​# Or in a container DockerfileENV HOME=/app/userRUN mkdir -p /app/user/.geminiCOPY config /app/user/.gemini

Điều này hữu ích cho khả năng tái lập trong CI nhưng hãy lưu ý: thay đổi HOME có thể ảnh hưởng tới công cụ khác và luồng xác thực (ví dụ, bộ nhớ đệm OAuth của Google), vì vậy hãy giới hạn kỹ thuật này cho container cô lập hoặc các trình bao ở cấp tiến trình.

How can I install and use Gemini CLI via CometAPI?

Câu trả lời ngắn gọn: bạn có hai cách thực tế — (A) gọi các mô hình Gemini trực tiếp qua CometAPI (được khuyến nghị và đơn giản nhất), hoặc (B) khiến Gemini CLI chính thức giao tiếp với CometAPI bằng cách sử dụng bản phát hành Gemini-CLI hỗ trợ base URL tùy chỉnh (một số bản phát hành/PR thêm điều này), hoặc chạy một proxy cục bộ nhỏ chuyển đổi các yêu cầu từ Gemini-CLI sang kiểu CometAPI/OpenAI.

What is CometAPI?

CometAPI là một cổng/tổng hợp API (API aggregation/gateway) cung cấp hàng trăm mô hình bên thứ ba (bao gồm họ Gemini của Google) qua một API HTTP theo phong cách OpenAI. Bạn đăng ký, nhận khóa API bearer, rồi gọi các endpoint như https://api.cometapi.com/v1/chat/completions. CometAPI sử dụng bearer token chuẩn trong header Authorization.

Vì sao dùng CometAPI? Nó cung cấp mức giá API thấp hơn so với API chính thức để hỗ trợ tích hợp. Hướng dẫn Cài đặt và Sử dụng Gemini CLI:

How can I call Gemini models directly via CometAPI? (Recommended)

Nếu mục tiêu của bạn chỉ là sử dụng các mô hình Gemini và bạn không nhất thiết cần tính năng của Gemini CLI, gọi trực tiếp CometAPI là đơn giản và đáng tin cậy.

export COMET_KEY="sk-xxxx"​curl -s -X POST "https://api.cometapi.com/v1/chat/completions" \  -H "Authorization: Bearer $COMET_KEY" \  -H "Content-Type: application/json" \  -d '{    "model": "gemini-2.5-pro",    "messages": [      {"role": "system", "content": "You are a helpful assistant."},      {"role": "user", "content": "Summarize the 3 key benefits of unit tests."}    ],    "max_tokens": 300  }' | jq .

Những lệnh gọi trực tiếp này cho phép bạn tích hợp CometAPI vào script, ứng dụng, hoặc CI mà không cần dựa vào Gemini CLI.

Can I make Gemini CLI use CometAPI?

Một số phiên bản/PR của Gemini CLI thêm biến môi trường để ghi đè base URL của Gemini API. Nếu bản gemini bạn cài đặt hỗ trợ cấu hình base URL Gemini tùy chỉnh + dùng khóa CometAPI, bạn có thể trỏ nó tới CometAPI và đặt khóa CometAPI làm GEMINI_API_KEY (CLI mong đợi biến khóa có tên GEMINI_API_KEY cho xác thực khóa API Gemini).

Ví dụ:

# example env — *check your gemini-cli docs for exact var names*export GEMINI_API_KEY="sk-xxxxx"                    # CometAPI keyexport GOOGLE_GEMINI_BASE_URL="https://api.cometapi.com/v1"  # if supportedgemini   # run the CLI; it will use the configured base URL

Troubleshooting: common problems and fixes

Problem: Gemini can’t see files in another repo

1. Hãy thử gemini --include-directories /path/to/repo khi khởi chạy. Hoặc trong phiên: /directory add /path/to/repo.
2. Nếu repo nằm trên ổ gắn mạng, hãy kiểm tra quyền và bảo đảm người dùng tiến trình CLI có thể đọc tệp.
3. Nếu bạn dùng symlink để di chuyển .gemini, hãy xác minh CLI theo symlink cho GEMINI.md và settings.json (một số phiên bản không theo một số symlink vì lý do bảo mật).

Problem: gemini fails to create ~/.gemini on Windows (EPERM)

Thông thường điều này có nghĩa tiến trình của bạn không có quyền ghi vào %USERPROFILE%. Cách khắc phục:

• Chạy terminal với quyền Administrator hoặc điều chỉnh quyền thư mục.
• Đặt vị trí cấu hình tùy chỉnh qua symlink hoặc, khi được hỗ trợ, qua biến môi trường (theo dõi hỗ trợ GEMINI_CONFIG_DIR trong tương lai).

Problem: cd doesn’t change working dir inside shell mode

Đây là vấn đề đã được ghi nhận trên một số nền tảng. Khuyến nghị: chuyển sang chạy lệnh shell từ bên ngoài tiến trình Gemini CLI hoặc thêm thư mục qua /directory add.

Problem: CometAPI model names don’t match what I expect

Gọi endpoint /v1/models và kiểm tra JSON. ID mô hình thường chứa chuỗi biến thể chính xác (ví dụ, gemini-2.5-flash-preview-04-17). Sử dụng đúng chuỗi trong yêu cầu của bạn.

Conclusion

Thiết kế mặc định của Gemini CLI ưu tiên hành vi hợp lý, dễ khám phá: ~/.gemini toàn cục cho mặc định ở cấp người dùng và .gemini theo dự án cho ghi đè ở cấp repo. Cộng đồng đang thúc đẩy khả năng cấu hình gốc nhiều hơn (biến môi trường hoặc cờ rõ ràng) để khiến công cụ thân thiện hơn với môi trường nhiều người dùng, container hóa, và doanh nghiệp.

How to change the Gemini CLI directory:

Overview: Gemini CLI lưu các tệp cấu hình và ngữ cảnh ở cấp người dùng trong thư mục .gemini (thường là ~/.gemini). Bạn có thể ảnh hưởng tới thư mục CLI sử dụng bằng cách (1) dựa vào .gemini theo dự án trong thư mục làm việc hiện tại, (2) dùng biến môi trường hoặc tùy chọn CLI khi được hỗ trợ, (3) thêm thư mục không gian làm việc bên trong phiên tương tác, hoặc (4) dùng kỹ thuật hệ thống tệp (symlink, bind mount, hoặc thay đổi biến home/profile) khi thiếu tùy chọn gốc.

Để bắt đầu, hãy khám phá khả năng của các mô hình Gemini (chẳng hạn Gemini 3 Pro) trong Playground và tham khảo Hướng dẫn API để biết hướng dẫn chi tiết. Trước khi truy cập, vui lòng đảm bảo bạn đã đăng nhập CometAPI và nhận được khóa API. CometAPI cung cấp mức giá thấp hơn nhiều so với giá chính thức để hỗ trợ bạn tích hợp.

Ready to Go?→ Dùng thử miễn phí các mô hình Gemini !