feat(cli): add explicit proxy option in cli #2526

warjiang · 2025-06-29T04:47:05Z

TLDR

gemini-cli will reuse environment HTTP(S)_PROXY(both in upper and lower case), this PR will

provide extra options, use --proxy option to set proxy for gemini-client.
set transport layer with explicit proxy instead of environment variable.

Dive Deeper

Reviewer Test Plan

Testing Matrix

	🍏	🪟	🐧
npm run	❓	❓	❓
npx	❓	❓	❓
Docker	❓	❓	❓
Podman	❓	-	-
Seatbelt	❓	-	-

Linked issues / bugs

gemini-code-assist

Summary of Changes

Hello @warjiang, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request enhances the command-line interface (CLI) by introducing a dedicated --proxy option. This change provides users with a more direct and explicit way to configure proxy settings for the gemini-client, allowing them to override system-wide environment variables when needed.

Highlights

New CLI Option: A --proxy command-line option has been added to the CLI, enabling users to specify a proxy address directly.
Explicit Proxy Configuration: Users can now explicitly set a proxy for the gemini-client via the command line, offering more granular control over network settings.
Configuration Priority: The newly introduced --proxy option takes precedence over existing HTTP(S)_PROXY environment variables when determining the proxy to use, providing a clear override mechanism.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point in your pull request via creating an issue comment (i.e. comment on the pull request page) using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands.

Feature	Command	Description
Code Review	`/gemini review`	Performs a code review for the current pull request in its current state.
Pull Request Summary	`/gemini summary`	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in issue comments and review comments.
Help	`/gemini help`	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist is currently in preview and may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments to provide feedback.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

gemini-code-assist

Code Review

The pull request introduces a new --proxy CLI option, allowing users to explicitly set a proxy for the gemini-client. The changes correctly integrate the option into the CLI arguments and prioritize it over environment variables. However, a high severity issue exists where an explicitly provided empty proxy string via the CLI argument will not override environment variables, leading to unexpected behavior.

allenhutchison

Thanks for adding this important feature! The implementation looks good. Before we can merge this, could you please add some tests to verify that the proxy setting is correctly applied? Also, could you please add documentation for the new --proxy option to the docs/cli/configuration.md file? Also the web-fetch tool has it's own fallback http fetch that should be included in these changes.

warjiang · 2025-06-30T09:01:31Z

Thanks for adding this important feature! The implementation looks good. Before we can merge this, could you please add some tests to verify that the proxy setting is correctly applied? Also, could you please add documentation for the new --proxy option to the docs/cli/configuration.md file? Also the web-fetch tool has it's own fallback http fetch that should be included in these changes.

thanks for your advice:

I've add extra UT for proxy options.
Updated the cli document for proxy options.
Set proxy for web-fetch tool if proxy option set.

allenhutchison · 2025-07-01T03:27:36Z

This is making good progress, but it looks like you have some failing tests, and need to resolve some merge conflicts.

warjiang · 2025-07-01T03:29:08Z

This is making good progress, but it looks like you have some failing tests, and need to resolve some merge conflicts.

Yeah, i'm working on it ~

warjiang · 2025-07-01T03:49:33Z

This is making good progress, but it looks like you have some failing tests, and need to resolve some merge conflicts.

Yeah, i'm working on it ~

@allenhutchison I've tested it locally, could plz re-run the ci task?

allenhutchison · 2025-07-01T19:27:16Z

Thanks for the great work on this PR, @warjiang! Adding proxy support is a fantastic improvement.

I did a deeper dive into the codebase to see if there were any other places that make network requests, and I found a few spots that might also need to be updated to use the new proxy setting.

Here are the files I noticed:

packages/core/src/core/modelCheck.ts: The fetch call on line 46 doesn't seem to be using the proxy.
packages/core/src/telemetry/clearcut-logger/clearcut-logger.ts: The https.request call on line 110 for sending telemetry data could also benefit from the proxy.
scripts/telemetry_utils.js: The getJson function uses curl to fetch release information from GitHub. This curl command should probably include the proxy as well.

Let me know what you think! Happy to discuss further.

warjiang · 2025-07-02T08:16:15Z

Thanks for the great work on this PR, @warjiang! Adding proxy support is a fantastic improvement.

I did a deeper dive into the codebase to see if there were any other places that make network requests, and I found a few spots that might also need to be updated to use the new proxy setting.

Here are the files I noticed:

packages/core/src/core/modelCheck.ts: The fetch call on line 46 doesn't seem to be using the proxy.

packages/core/src/telemetry/clearcut-logger/clearcut-logger.ts: The https.request call on line 110 for sending telemetry data could also benefit from the proxy.

scripts/telemetry_utils.js: The getJson function uses curl to fetch release information from GitHub. This curl command should probably include the proxy as well.

Let me know what you think! Happy to discuss further.

thanks for you comprehensive advice,

for packages/core/src/core/modelCheck.ts, you're right, and I add the proxy when fetch model info:

gemini-cli/packages/core/src/core/modelCheck.ts

Lines 48 to 58 in 8e3d6c4

    
           if (proxy) { 
        
             setGlobalDispatcher(new ProxyAgent(proxy)); 
        
           } 
        
           const response = await fetch(endpoint, { 
        
             method: 'POST', 
        
             headers: { 'Content-Type': 'application/json' }, 
        
             body, 
        
             signal: controller.signal, 
        
           }); 
        
           clearTimeout(timeoutId);

for packages/core/src/telemetry/clearcut-logger/clearcut-logger.ts, because the request use https.request not build-in fetch method, so need extra proxy-agent for proxy request, we follow the implementation of kubernetes-client/javascript (I've tested the implementation of proxy, and I thinks it's robus enough)

for scripts/telemetry_utils.js, I thinks we should split another PR to add feature of proxy, reasons as following:

otel is started through sub process, and the config for otel is load from setting file instead of options, when we start gemini-cli, we'll not start the otel collector directly, the collector is started by running npm run telemetry or npm run start:gcp, the proxy option should be add here not in cli.

currently, the way to parse command line arguments is simple, it read the process.argv and match the keyword like:

gemini-cli/scripts/telemetry.js

Lines 52 to 70 in edd69cb

    
           const allowedTargets = ['local', 'gcp']; 
        
           const targetArg = process.argv.find((arg) => arg.startsWith('--target=')); 
        
           if (targetArg) { 
        
             const potentialTarget = targetArg.split('=')[1]; 
        
             if (allowedTargets.includes(potentialTarget)) { 
        
               target = potentialTarget; 
        
               console.log(`⚙️  Using command-line target: ${target}`); 
        
             } else { 
        
               console.error( 
        
                 `🛑 Error: Invalid target '${potentialTarget}'. Allowed targets are: ${allowedTargets.join(', ')}.`, 
        
               ); 
        
               process.exit(1); 
        
             } 
        
           } else if (settingsTarget) { 
        
             console.log( 
        
               `⚙️ Using telemetry target from settings.json: ${settingsTarget}`, 
        
             ); 
        
           }

here we need to read --target option to start gcp or local otel collector, if we use --target gcp, the implementation above will not detect target=gcp correctly, and fallback to local collector

so, , I want to add arguments parsing in another PR and add proxy options in the command line and setting file at the same time.

warjiang · 2025-07-03T03:03:16Z

@allenhutchison could you help me recheck the PR. BTW the gemini-bot label the PR with status/need-issue, should I create extra issue related to the PR for better description?

Dcatfly

Hi, I saw your related PR at #3017. The functionality of these two PRs is indeed repetitive, but I prefer the implementation in 3017, and I've left some comments for you. 😂

Dcatfly · 2025-07-03T04:17:53Z

packages/core/src/telemetry/clearcut-logger/clearcut-logger.ts

+  getProxyAgent() {
+    const proxyUrl = this.config?.getProxy();
+    if (!proxyUrl) return undefined;
+    if (proxyUrl.startsWith('socks')) {


Both http and https protocols can be handled in HttpsProxyAgent

The ProxyAgent provided by undici currently does not support the socks type. If you want to add support for the socks type proxy, it is not enough to handle it here.

thanks for pointing that~(got the new usage of HttpsProxyAgent and HttpProxyAgent 👍 )
here use https seems not very good, the reason I add the implementation of socks5 protocol here is that, I think the clearcut-logger is an isolated implementation.

Thanks for your reply.
What I mean is, if socks support is to be added, then all requests within the CLI should support socks proxy, as their proxy source is the same.

@Dcatfly Agree with you, so I co-authored with you to re-use https-proxy-agent for http/https proxy protocol, for socks related protocol, it will report the unsupported error

related commit=> e13ef75#diff-053150b640a7ce75eff69d1a22cae7f0f94ad64ce9a855db544dda0929316519

Dcatfly · 2025-07-03T04:22:02Z

packages/core/src/tools/web-fetch.ts

@@ -80,6 +81,9 @@ export class WebFetchTool extends BaseTool<WebFetchToolParams, ToolResult> {
        type: 'object',
      },
    );
+    if (config.getProxy()) {


setGlobalDispatcher will intercept all node fetches in the current program.
setGlobalDispatcher has already been called in core/client.ts, and the timing is early enough. Therefore, the undici-based proxy agent in this PR might be unnecessary.

Dcatfly · 2025-07-03T04:38:53Z

packages/cli/src/config/config.ts

@@ -237,6 +243,7 @@ export async function loadCliConfig(
    },
    checkpointing: argv.checkpointing || settings.checkpointing?.enabled,
    proxy:
+      argv.proxy ||


Is it necessary to add a configuration to set whether the proxy is enabled? Maybe reading from the env is enough.

Is it necessary to add a configuration to set whether the proxy is enabled? Maybe reading from the env is enough.

Use environment variable can works(I've tested it, it worked out ~), but provide explicit option will it easy to understand, also provide extra way to make gemini-cli works with other software, otherwise we need to set and unset the environment variable to achieve that.

You make a good point, but this would require all request-making points in the project to actively add the proxy, including curl in telemetry_utils, as well as libraries that might be introduced in the future, or even AI-generated shells. This might require some trade-offs.

Dcatfly · 2025-07-03T04:40:43Z

packages/core/src/code_assist/oauth2.ts

  const client = new OAuth2Client({
    clientId: OAUTH_CLIENT_ID,
    clientSecret: OAUTH_CLIENT_SECRET,
+    transporter: new Gaxios({


If transporter is not set, OAuth2Client will actually automatically read proxy settings from the environment. Both methods only support http(s).

OAuth2Client extends AuthClient, the transporter is set in the AuthClient:

https://github.com/googleapis/google-auth-library-nodejs/blob/bd7e4e3465567bba6f2599f63ac8ed62c0027de9/src/auth/authclient.ts#L246-L275

if unset transporter for OAuth2Client , it will init a brand new instance using new Gaxios(opts.transporterOptions), but in Gaxios it will not use environment variable directly.

https://github.com/googleapis/gaxios/blob/cdef1bb3f4f382d4581e21ebebfae2aca2f34029/src/gaxios.ts#L70-L76

In the official doc for the google-auth-library, it is mentioned that proxy settings are obtained from the environment.

The specific code implementation is likely located around here.

warjiang · 2025-07-03T05:32:13Z

Thanks for the great work on this PR, @warjiang! Adding proxy support is a fantastic improvement.
I did a deeper dive into the codebase to see if there were any other places that make network requests, and I found a few spots that might also need to be updated to use the new proxy setting.
Here are the files I noticed:

packages/core/src/core/modelCheck.ts: The fetch call on line 46 doesn't seem to be using the proxy.

packages/core/src/telemetry/clearcut-logger/clearcut-logger.ts: The https.request call on line 110 for sending telemetry data could also benefit from the proxy.

scripts/telemetry_utils.js: The getJson function uses curl to fetch release information from GitHub. This curl command should probably include the proxy as well.

Let me know what you think! Happy to discuss further.

thanks for you comprehensive advice,

for packages/core/src/core/modelCheck.ts, you're right, and I add the proxy when fetch model info:

gemini-cli/packages/core/src/core/modelCheck.ts

Lines 48 to 58 in 8e3d6c4

if (proxy) {

setGlobalDispatcher(new ProxyAgent(proxy));

}

const response = await fetch(endpoint, {

method: 'POST',

headers: { 'Content-Type': 'application/json' },

body,

signal: controller.signal,

});

clearTimeout(timeoutId);

for packages/core/src/telemetry/clearcut-logger/clearcut-logger.ts, because the request use https.request not build-in fetch method, so need extra proxy-agent for proxy request, we follow the implementation of kubernetes-client/javascript (I've tested the implementation of proxy, and I thinks it's robus enough)

for scripts/telemetry_utils.js, I thinks we should split another PR to add feature of proxy, reasons as following:

otel is started through sub process, and the config for otel is load from setting file instead of options, when we start gemini-cli, we'll not start the otel collector directly, the collector is started by running npm run telemetry or npm run start:gcp, the proxy option should be add here not in cli.

currently, the way to parse command line arguments is simple, it read the process.argv and match the keyword like:

gemini-cli/scripts/telemetry.js

Lines 52 to 70 in edd69cb

const allowedTargets = ['local', 'gcp'];

const targetArg = process.argv.find((arg) => arg.startsWith('--target='));

if (targetArg) {

const potentialTarget = targetArg.split('=')[1];

if (allowedTargets.includes(potentialTarget)) {

target = potentialTarget;

console.log(`⚙️ Using command-line target: ${target}`);

} else {

console.error(

`🛑 Error: Invalid target '${potentialTarget}'. Allowed targets are: ${allowedTargets.join(', ')}.`,

);

process.exit(1);

}

} else if (settingsTarget) {

console.log(

`⚙️ Using telemetry target from settings.json: ${settingsTarget}`,

);

}

here we need to read --target option to start gcp or local otel collector, if we use --target gcp, the implementation above will not detect target=gcp correctly, and fallback to local collector

so, , I want to add arguments parsing in another PR and add proxy options in the command line and setting file at the same time.

@Dcatfly can we cooperate with the proxy feature. Apart from proxy for cli, I think there is need to add proxy feature for telemetry, like init the otel collector from github, report metrics to gcp endpoint, maybe there still need extra work about this.

warjiang · 2025-07-03T23:08:23Z

I find the problem of ci, the cause is the trailing space at the end of the comment line

howerver, run format task in local machine(for me is macos) cannot find the error.

… & https protocol Co-authored-by: Dcatfly <[email protected]>

warjiang · 2025-07-17T16:08:07Z

@warjiang I tried resolving conflicts for you via the GitHub UI but looks like it missed a bit 😢 . Would you mind fixing the build real quick and re-pushing. Also could you @ me directly once you're done. Apologeis for all this back and forth. There's been so much volume in the repo it's hard to keep up so the @'s have been helpful

Never mind, I know it's really hard to maintain a popular oss repo, especially the repo also iterated in a high speed.

warjiang · 2025-07-17T16:08:45Z

@NTaylorMullen all conflicts have been resolved and re-tested in forked repo. Let's move forward ~

Co-authored-by: Dcatfly <[email protected]>

warjiang requested a review from a team as a code owner June 29, 2025 04:47

gemini-code-assist bot reviewed Jun 29, 2025

View reviewed changes

warjiang force-pushed the feat/explicit-proxy-option branch 2 times, most recently from 11524fa to 0da6cb0 Compare June 29, 2025 07:47

allenhutchison self-assigned this Jun 29, 2025

allenhutchison previously requested changes Jun 29, 2025

View reviewed changes

warjiang force-pushed the feat/explicit-proxy-option branch 4 times, most recently from 88aa0c3 to c0680bf Compare June 30, 2025 08:57

warjiang force-pushed the feat/explicit-proxy-option branch from aee7385 to 3aebac1 Compare July 1, 2025 03:44

warjiang force-pushed the feat/explicit-proxy-option branch 2 times, most recently from 316f835 to 8e3d6c4 Compare July 2, 2025 07:44

warjiang force-pushed the feat/explicit-proxy-option branch 2 times, most recently from ce7ad18 to 7cb4971 Compare July 3, 2025 00:09

gemini-cli bot added the status/need-issue Pull request needs to be associated with an issue label Jul 3, 2025

warjiang force-pushed the feat/explicit-proxy-option branch from 7cb4971 to e02ac39 Compare July 3, 2025 02:54

warjiang mentioned this pull request Jul 3, 2025

fix: add support for proxy in ClearcutLogger #3017

Open

Dcatfly reviewed Jul 3, 2025

View reviewed changes

warjiang force-pushed the feat/explicit-proxy-option branch from c9f8269 to d545b45 Compare July 3, 2025 23:09

warjiang and others added 10 commits July 17, 2025 23:26

feat(cli): add explicit proxy option in cli

ba5a09b

test(cli): add proxy ut for loadCliConfig

31b0ec7

docs(cli): add docs for proxy option

9a46b74

feat(web-fetch): add fetch for web-fetch tool

9b6ae22

feat(core): apply proxy in core & telemetry pkg

b2b47f1

feat(cli): rm socks5 proxy protocol, reuse https-proxy-agent for http…

3a97995

… & https protocol Co-authored-by: Dcatfly <[email protected]>

feat: resolve conflict & use transporterOptions instead of transporter

5c217e8

fix: add getProxy in oauth2 test case

2c61ad5

fix: rm outdated field in CliArgs

04f2077

fix: rebase & fix ut errs

7742d98

auto-merge was automatically disabled July 17, 2025 15:50
Head branch was pushed to by a user without write access

warjiang dismissed NTaylorMullen’s stale review via 7742d98 July 17, 2025 15:50

warjiang force-pushed the feat/explicit-proxy-option branch from 1811937 to 7742d98 Compare July 17, 2025 15:50

Merge branch 'main' into feat/explicit-proxy-option

1017be2

Merge branch 'main' into feat/explicit-proxy-option

b68f596

NTaylorMullen approved these changes Jul 17, 2025

View reviewed changes

NTaylorMullen enabled auto-merge July 17, 2025 18:54

NTaylorMullen added this pull request to the merge queue Jul 17, 2025

Merged via the queue into google-gemini:main with commit 606a770 Jul 17, 2025
10 checks passed

skeshive pushed a commit that referenced this pull request Jul 18, 2025

feat(cli): add explicit proxy option in cli (#2526)

38da20d

Co-authored-by: Dcatfly <[email protected]>

dacian3 pushed a commit to dacian3/gemini-cli that referenced this pull request Jul 20, 2025

feat(cli): add explicit proxy option in cli (google-gemini#2526)

ec1e3af

Co-authored-by: Dcatfly <[email protected]>

galz10 pushed a commit that referenced this pull request Jul 22, 2025

feat(cli): add explicit proxy option in cli (#2526)

b6ba0a9

Co-authored-by: Dcatfly <[email protected]>

davenportjw pushed a commit to davenportjw/gemini-cli that referenced this pull request Jul 24, 2025

feat(cli): add explicit proxy option in cli (google-gemini#2526)

09b7388

Co-authored-by: Dcatfly <[email protected]>

This was referenced Jul 25, 2025

支持传递proxy参数（GEMINI-CLI已有此功能） QwenLM/qwen-code#122

Open

Support HTTP_PROXY & HTTPS_PROXY for millions of users who are behind fire walls in some regions and some organizations. sst/opencode#531

Open

galz10 pushed a commit that referenced this pull request Jul 30, 2025

feat(cli): add explicit proxy option in cli (#2526)

8c48010

Co-authored-by: Dcatfly <[email protected]>

JunYang-tes pushed a commit to JunYang-tes/gemini-cli.nvim that referenced this pull request Aug 9, 2025

feat(cli): add explicit proxy option in cli (google-gemini#2526)

49d21d7

Co-authored-by: Dcatfly <[email protected]>

feat(cli): add explicit proxy option in cli #2526

feat(cli): add explicit proxy option in cli #2526

Conversation

warjiang commented Jun 29, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

TLDR

Dive Deeper

Reviewer Test Plan

Testing Matrix

Linked issues / bugs

Uh oh!

gemini-code-assist bot left a comment

Choose a reason for hiding this comment

Summary of Changes

Highlights

Footnotes

Uh oh!

gemini-code-assist bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

allenhutchison left a comment

Choose a reason for hiding this comment

Uh oh!

warjiang commented Jun 30, 2025

Uh oh!

allenhutchison commented Jul 1, 2025

Uh oh!

warjiang commented Jul 1, 2025

Uh oh!

warjiang commented Jul 1, 2025

Uh oh!

allenhutchison commented Jul 1, 2025

Uh oh!

warjiang commented Jul 2, 2025

Uh oh!

warjiang commented Jul 3, 2025

Uh oh!

Dcatfly left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

warjiang commented Jul 3, 2025

Uh oh!

warjiang commented Jul 3, 2025

Uh oh!

warjiang commented Jul 17, 2025

Uh oh!

warjiang commented Jul 17, 2025

Uh oh!

Uh oh!

Uh oh!

warjiang commented Jun 29, 2025 •

edited

Loading