feat(agent): add custom environment variables to agent configuration (#13357)

beyondkmp · Payne Fu · claude · web-flow · commit 203c94c1aca4 · 2026-03-11T15:11:57.000+08:00
### What this PR does Fix #13343 Before this PR: There was no way to configure custom environment variables for agents. Users could not pass additional env vars to the Claude Code SDK process at runtime. After this PR: Users can set custom environment variables (KEY=value pairs) for agents via a TextArea in both the AgentModal (create/edit popup) and AdvancedSettings (agent settings page). These env vars are merged into the Claude Code SDK process environment at runtime, with a security blocklist preventing overrides of critical system variables. ### Why we need it and why it was done in this way Users need the ability to customize the agent runtime environment (e.g., setting `DEBUG=true`, custom API keys for MCP tools, or tool-specific config). The implementation follows existing patterns: - The `env_vars` field is added to `AgentConfigurationSchema` as an optional `Record<string, string>` — no database migration needed since configuration uses `.loose()` and is stored as JSON text. - The AgentModal uses inline parse/serialize helpers for the KEY=value text format. - The AdvancedSettings follows the existing commit-on-blur pattern (same as `maxTurns`). - A blocklist in ClaudeCodeService prevents users from overriding critical variables (API keys, Electron flags, etc.). The following alternatives were considered: - A key-value pair editor UI — rejected in favor of a simpler TextArea matching the existing code tools page pattern. ### Breaking changes None. ### Special notes for your reviewer - The `env_vars` field uses `.optional().default({})` in Zod, consistent with `permission_mode` and `max_turns`. - Security: A blocklist of 12 critical env var keys (ANTHROPIC_API_KEY, ELECTRON_RUN_AS_NODE, etc.) is enforced server-side with a warning log when blocked. - User env vars are applied **after** system env vars so they can override shell env but NOT critical Anthropic/Electron vars. ### Checklist - [x] PR: The PR description is expressive enough and will help future contributors - [x] Code: Write code that humans can understand and Keep it simple - [x] Refactor: You have left the code cleaner than you found it (Boy Scout Rule) - [ ] Upgrade: Impact of this change on upgrade flows was considered and addressed if required - [x] Documentation: A user-guide update was considered and is present (link) or not required. - [ ] Self-review: I have reviewed my own code before requesting review from others ### Release note ```release-note Add custom environment variables support to agent configuration. Users can now set KEY=value pairs in the agent create/edit modal and advanced settings, which are passed to the Claude Code SDK runtime environment. ``` --------- Signed-off-by: Payne Fu <payne@Paynes-MacBook-Air.local> Co-authored-by: Payne Fu <payne@Paynes-MacBook-Air.local> Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
diff --git a/src/main/services/agents/services/claudecode/index.ts b/src/main/services/agents/services/claudecode/index.ts
@@ -164,6 +164,37 @@ class ClaudeCodeService implements AgentServiceInterface {
       ...(customGitBashPath ? { CLAUDE_CODE_GIT_BASH_PATH: customGitBashPath } : {})
     }
 
+    // Merge user-defined environment variables from session configuration
+    const userEnvVars = session.configuration?.env_vars
+    if (userEnvVars && typeof userEnvVars === 'object') {
+      const BLOCKED_ENV_KEYS = new Set([
+        'ANTHROPIC_API_KEY',
+        'ANTHROPIC_AUTH_TOKEN',
+        'ANTHROPIC_BASE_URL',
+        'ANTHROPIC_MODEL',
+        'ANTHROPIC_DEFAULT_OPUS_MODEL',
+        'ANTHROPIC_DEFAULT_SONNET_MODEL',
+        'ANTHROPIC_DEFAULT_HAIKU_MODEL',
+        'ELECTRON_RUN_AS_NODE',
+        'ELECTRON_NO_ATTACH_CONSOLE',
+        'CLAUDE_CONFIG_DIR',
+        'CLAUDE_CODE_USE_BEDROCK',
+        'CLAUDE_CODE_GIT_BASH_PATH',
+        'NODE_OPTIONS',
+        '__PROTO__',
+        'CONSTRUCTOR',
+        'PROTOTYPE'
+      ])
+      for (const [key, value] of Object.entries(userEnvVars)) {
+        const upperKey = key.toUpperCase()
+        if (BLOCKED_ENV_KEYS.has(upperKey)) {
+          logger.warn('Blocked user env var override for system-critical variable', { key })
+        } else if (typeof value === 'string') {
+          env[key] = value
+        }
+      }
+    }
+
     const errorChunks: string[] = []
 
     const sessionAllowedTools = new Set<string>(session.allowed_tools ?? [])
diff --git a/src/renderer/src/components/Popups/agent/AgentModal.tsx b/src/renderer/src/components/Popups/agent/AgentModal.tsx
@@ -17,6 +17,7 @@ import type {
   UpdateAgentForm
 } from '@renderer/types'
 import { AgentConfigurationSchema, isAgentType } from '@renderer/types'
+import { parseKeyValueString, serializeKeyValueString } from '@renderer/utils/env'
 import type { GitBashPathInfo } from '@shared/config/constant'
 import { Button, Input, Modal, Select } from 'antd'
 import type { ChangeEvent, FormEvent } from 'react'
@@ -166,6 +167,27 @@ const PopupContainer: React.FC<Props> = ({ agent, afterSubmit, resolve }) => {
     }))
   }, [])
 
+  const [envVarsText, setEnvVarsText] = useState(() => serializeKeyValueString(form.configuration?.env_vars ?? {}))
+
+  useEffect(() => {
+    if (open) {
+      setEnvVarsText(serializeKeyValueString(buildAgentForm(agent).configuration?.env_vars ?? {}))
+    }
+  }, [agent, open])
+
+  const onEnvVarsChange = useCallback((e: ChangeEvent<HTMLTextAreaElement>) => {
+    const text = e.target.value
+    setEnvVarsText(text)
+    const parsed = parseKeyValueString(text)
+    setForm((prev) => ({
+      ...prev,
+      configuration: {
+        ...AgentConfigurationSchema.parse(prev.configuration ?? {}),
+        env_vars: parsed
+      }
+    }))
+  }, [])
+
   const addAccessiblePath = useCallback(async () => {
     try {
       const selected = await window.api.file.selectFolder()
@@ -455,6 +477,17 @@ const PopupContainer: React.FC<Props> = ({ agent, afterSubmit, resolve }) => {
               <TextArea rows={3} value={form.instructions ?? ''} onChange={onInstChange} />
             </FormItem>
 
+            <FormItem>
+              <Label>{t('agent.settings.advance.envVars.label')}</Label>
+              <TextArea
+                rows={3}
+                value={envVarsText}
+                onChange={onEnvVarsChange}
+                placeholder={'API_KEY=xxx\nDEBUG=true'}
+              />
+              <HelpText>{t('agent.settings.advance.envVars.helper')}</HelpText>
+            </FormItem>
+
             {/* <FormItem>
               <Label>{t('common.description')}</Label>
               <TextArea rows={1} value={form.description ?? ''} onChange={onDescChange} />
diff --git a/src/renderer/src/i18n/locales/en-us.json b/src/renderer/src/i18n/locales/en-us.json
@@ -135,6 +135,11 @@
     },
     "settings": {
       "advance": {
+        "envVars": {
+          "description": "Set custom environment variables for the agent runtime.",
+          "helper": "Enter custom environment variables (one per line, format: KEY=value)",
+          "label": "Environment Variables"
+        },
         "maxTurns": {
           "description": "Define how many request/response cycles the agent may complete automatically.",
           "helper": "Higher values enable longer autonomous runs; lower values keep sessions short.",
diff --git a/src/renderer/src/i18n/locales/zh-cn.json b/src/renderer/src/i18n/locales/zh-cn.json
@@ -135,6 +135,11 @@
     },
     "settings": {
       "advance": {
+        "envVars": {
+          "description": "为智能体运行时设置自定义环境变量。",
+          "helper": "输入自定义环境变量（每行一个，格式：KEY=value）",
+          "label": "环境变量"
+        },
         "maxTurns": {
           "description": "设定代理自动执行的请求/回复轮次数。",
           "helper": "数值越高可自主运行越久；数值越低更易控制。",
diff --git a/src/renderer/src/i18n/locales/zh-tw.json b/src/renderer/src/i18n/locales/zh-tw.json
@@ -135,6 +135,11 @@
     },
     "settings": {
       "advance": {
+        "envVars": {
+          "description": "為智慧體執行環境設置自訂環境變數。",
+          "helper": "輸入自訂環境變數（每行一個，格式：KEY=value）",
+          "label": "環境變數"
+        },
         "maxTurns": {
           "description": "設定代理自動執行的請求／回覆輪次數。",
           "helper": "數值越高可自動運作越久；數值越低更容易掌控。",
diff --git a/src/renderer/src/i18n/translate/de-de.json b/src/renderer/src/i18n/translate/de-de.json
@@ -135,6 +135,11 @@
     },
     "settings": {
       "advance": {
+        "envVars": {
+          "description": "[to be translated]:Set custom environment variables for the agent runtime.",
+          "helper": "[to be translated]:Enter custom environment variables (one per line, format: KEY=value)",
+          "label": "[to be translated]:Environment Variables"
+        },
         "maxTurns": {
           "description": "Legen Sie die Anzahl der Anfrage-/Antwort-Runden fest, die der Agent automatisch ausführt.",
           "helper": "Höhere Werte ermöglichen längere autonome Ausführung; niedrigere Werte bieten bessere Kontrolle.",
diff --git a/src/renderer/src/i18n/translate/el-gr.json b/src/renderer/src/i18n/translate/el-gr.json
@@ -135,6 +135,11 @@
     },
     "settings": {
       "advance": {
+        "envVars": {
+          "description": "[to be translated]:Set custom environment variables for the agent runtime.",
+          "helper": "[to be translated]:Enter custom environment variables (one per line, format: KEY=value)",
+          "label": "[to be translated]:Environment Variables"
+        },
         "maxTurns": {
           "description": "Ορίστε τον αριθμό γύρων αιτήματος/απάντησης που θα εκτελούνται αυτόματα από τον διαμεσολαβητή.",
           "helper": "Όσο υψηλότερη είναι η τιμή, τόσο περισσότερο μπορεί να λειτουργεί αυτόνομα· όσο χαμηλότερη είναι, τόσο πιο εύκολα ελέγχεται.",
diff --git a/src/renderer/src/i18n/translate/es-es.json b/src/renderer/src/i18n/translate/es-es.json
@@ -135,6 +135,11 @@
     },
     "settings": {
       "advance": {
+        "envVars": {
+          "description": "[to be translated]:Set custom environment variables for the agent runtime.",
+          "helper": "[to be translated]:Enter custom environment variables (one per line, format: KEY=value)",
+          "label": "[to be translated]:Environment Variables"
+        },
         "maxTurns": {
           "description": "Establece el número de rondas de solicitud/respuesta que el agente ejecutará automáticamente.",
           "helper": "Cuanto mayor es el valor, más tiempo puede funcionar de forma autónoma; cuanto menor es el valor, más fácil es de controlar.",
diff --git a/src/renderer/src/i18n/translate/fr-fr.json b/src/renderer/src/i18n/translate/fr-fr.json
@@ -135,6 +135,11 @@
     },
     "settings": {
       "advance": {
+        "envVars": {
+          "description": "[to be translated]:Set custom environment variables for the agent runtime.",
+          "helper": "[to be translated]:Enter custom environment variables (one per line, format: KEY=value)",
+          "label": "[to be translated]:Environment Variables"
+        },
         "maxTurns": {
           "description": "Définir le nombre de cycles de requête/réponse exécutés automatiquement par l'agent.",
           "helper": "Une valeur plus élevée permet une autonomie prolongée ; une valeur plus faible facilite le contrôle.",
diff --git a/src/renderer/src/i18n/translate/ja-jp.json b/src/renderer/src/i18n/translate/ja-jp.json
@@ -135,6 +135,11 @@
     },
     "settings": {
       "advance": {
+        "envVars": {
+          "description": "[to be translated]:Set custom environment variables for the agent runtime.",
+          "helper": "[to be translated]:Enter custom environment variables (one per line, format: KEY=value)",
+          "label": "[to be translated]:Environment Variables"
+        },
         "maxTurns": {
           "description": "プロキシが自動的に実行するリクエスト/レスポンスのラウンド数を設定します。",
           "helper": "数値が高いほど自律動作の時間が長くなり、数値が低いほど制御しやすくなります。",
diff --git a/src/renderer/src/i18n/translate/pt-pt.json b/src/renderer/src/i18n/translate/pt-pt.json
@@ -135,6 +135,11 @@
     },
     "settings": {
       "advance": {
+        "envVars": {
+          "description": "[to be translated]:Set custom environment variables for the agent runtime.",
+          "helper": "[to be translated]:Enter custom environment variables (one per line, format: KEY=value)",
+          "label": "[to be translated]:Environment Variables"
+        },
         "maxTurns": {
           "description": "Defina o número de ciclos de solicitação/resposta executados automaticamente pelo agente.",
           "helper": "Quanto maior o valor, mais tempo pode funcionar de forma autônoma; quanto menor o valor, mais fácil de controlar.",
diff --git a/src/renderer/src/i18n/translate/ro-ro.json b/src/renderer/src/i18n/translate/ro-ro.json
@@ -135,6 +135,11 @@
     },
     "settings": {
       "advance": {
+        "envVars": {
+          "description": "[to be translated]:Set custom environment variables for the agent runtime.",
+          "helper": "[to be translated]:Enter custom environment variables (one per line, format: KEY=value)",
+          "label": "[to be translated]:Environment Variables"
+        },
         "maxTurns": {
           "description": "Definește câte cicluri cerere/răspuns poate finaliza automat agentul.",
           "helper": "Valorile mai mari permit rulări autonome mai lungi; valorile mai mici mențin sesiunile scurte.",
diff --git a/src/renderer/src/i18n/translate/ru-ru.json b/src/renderer/src/i18n/translate/ru-ru.json
@@ -135,6 +135,11 @@
     },
     "settings": {
       "advance": {
+        "envVars": {
+          "description": "[to be translated]:Set custom environment variables for the agent runtime.",
+          "helper": "[to be translated]:Enter custom environment variables (one per line, format: KEY=value)",
+          "label": "[to be translated]:Environment Variables"
+        },
         "maxTurns": {
           "description": "Установить количество циклов запрос/ответ, выполняемых автоматически через прокси.",
           "helper": "Чем выше значение, тем дольше может работать автономно; чем ниже значение, тем легче контролировать.",
diff --git a/src/renderer/src/pages/settings/AgentSettings/components/AdvancedSettings.tsx b/src/renderer/src/pages/settings/AgentSettings/components/AdvancedSettings.tsx
@@ -1,6 +1,7 @@
 import type { UpdateAgentBaseForm } from '@renderer/types'
 import { AgentConfigurationSchema } from '@renderer/types'
-import { InputNumber, Tooltip } from 'antd'
+import { parseKeyValueString, serializeKeyValueString } from '@renderer/utils/env'
+import { Input, InputNumber, Tooltip } from 'antd'
 import { Info } from 'lucide-react'
 import { useCallback, useEffect, useState } from 'react'
 import { useTranslation } from 'react-i18next'
@@ -14,20 +15,25 @@ import {
   SettingsTitle
 } from '../shared'
 
+const { TextArea } = Input
+
 export const AdvancedSettings: React.FC<AgentOrSessionSettingsProps> = ({ agentBase, update }) => {
   const { t } = useTranslation()
   const [configuration, setConfiguration] = useState<AgentConfigurationState>(defaultConfiguration)
   const [maxTurnsInput, setMaxTurnsInput] = useState<number>(defaultConfiguration.max_turns)
+  const [envVarsText, setEnvVarsText] = useState<string>('')
 
   useEffect(() => {
     if (!agentBase) {
       setConfiguration(defaultConfiguration)
       setMaxTurnsInput(defaultConfiguration.max_turns)
+      setEnvVarsText('')
       return
     }
     const parsed: AgentConfigurationState = AgentConfigurationSchema.parse(agentBase.configuration ?? {})
     setConfiguration(parsed)
     setMaxTurnsInput(parsed.max_turns)
+    setEnvVarsText(serializeKeyValueString(parsed.env_vars ?? {}))
   }, [agentBase])
 
   const commitMaxTurns = useCallback(() => {
@@ -47,13 +53,23 @@ export const AdvancedSettings: React.FC<AgentOrSessionSettingsProps> = ({ agentB
     update({ id: agentBase.id, configuration: next } satisfies UpdateAgentBaseForm)
   }, [agentBase, configuration, maxTurnsInput, update])
 
+  const commitEnvVars = useCallback(() => {
+    if (!agentBase) return
+    const parsed = parseKeyValueString(envVarsText)
+    const currentVars = configuration.env_vars ?? {}
+    if (JSON.stringify(parsed) === JSON.stringify(currentVars)) return
+    const next: AgentConfigurationState = { ...configuration, env_vars: parsed }
+    setConfiguration(next)
+    update({ id: agentBase.id, configuration: next } satisfies UpdateAgentBaseForm)
+  }, [agentBase, configuration, envVarsText, update])
+
   if (!agentBase) {
     return null
   }
 
   return (
     <SettingsContainer>
-      <SettingsItem divider={false}>
+      <SettingsItem>
         <SettingsTitle
           contentAfter={
             <Tooltip title={t('agent.settings.advance.maxTurns.description')} placement="left">
@@ -75,6 +91,28 @@ export const AdvancedSettings: React.FC<AgentOrSessionSettingsProps> = ({ agentB
           <span className="mt-1 text-foreground-500 text-xs">{t('agent.settings.advance.maxTurns.helper')}</span>
         </div>
       </SettingsItem>
+      <SettingsItem divider={false}>
+        <SettingsTitle
+          contentAfter={
+            <Tooltip title={t('agent.settings.advance.envVars.description')} placement="left">
+              <Info size={16} className="text-foreground-400" />
+            </Tooltip>
+          }>
+          {t('agent.settings.advance.envVars.label')}
+        </SettingsTitle>
+        <div className="my-2 flex w-full flex-col gap-2">
+          <TextArea
+            rows={4}
+            value={envVarsText}
+            onChange={(e) => setEnvVarsText(e.target.value)}
+            onBlur={commitEnvVars}
+            placeholder={'API_KEY=xxx\nDEBUG=true'}
+            aria-label={t('agent.settings.advance.envVars.label')}
+            style={{ width: '100%' }}
+          />
+          <span className="mt-1 text-foreground-500 text-xs">{t('agent.settings.advance.envVars.helper')}</span>
+        </div>
+      </SettingsItem>
     </SettingsContainer>
   )
 }
diff --git a/src/renderer/src/types/agent.ts b/src/renderer/src/types/agent.ts
@@ -58,7 +58,8 @@ export const AgentConfigurationSchema = z
 
     // https://docs.claude.com/en/docs/claude-code/sdk/sdk-permissions#mode-specific-behaviors
     permission_mode: PermissionModeSchema.optional().default('default'), // Permission mode, default to 'default'
-    max_turns: z.number().optional().default(100) // Maximum number of interaction turns, default to 100
+    max_turns: z.number().optional().default(100), // Maximum number of interaction turns, default to 100
+    env_vars: z.record(z.string(), z.string()).optional().default({}) // Custom environment variables for the agent runtime
   })
   .loose()
 
diff --git a/src/renderer/src/utils/__tests__/env.test.ts b/src/renderer/src/utils/__tests__/env.test.ts
diff --git a/src/renderer/src/utils/env.ts b/src/renderer/src/utils/env.ts
