Environment Variables Reference

CodeBuddy Code supports environment variables to control its behavior. These variables can be set before startup, or configured in the env field of settings.json to apply to every session.

Tip: Unless otherwise noted, environment variables can also be set in the env field of settings.json, which automatically applies them to every session or rolls out configuration for an entire team.

Exception: CODEBUDDY_IS_SANDBOX is read exclusively from the process environment and is not injected from the env field of settings.json (including project-level settings), preventing a repository from silently escalating privileges. See Sandbox full pass (high risk).

Authentication

Environment Variable	Description
CODEBUDDY_API_KEY	API key. Set this key for model API calls. Always uses this key in non-interactive mode (-p)
CODEBUDDY_AUTH_TOKEN	CodeBuddy platform authentication token for all platform API calls
CODEBUDDY_CUSTOM_HEADERS	Custom HTTP headers. Format: Name: Value, multiple headers separated by newline or \n
CODEBUDDY_PASSTHROUGH_HEADER_PREFIXES	Allowlist of custom header prefixes that callers can pass through on each turn to the official model gateway (via _meta['codebuddy.ai'].customPassthroughHeaders in stream-json / print flows, as well as ACP flows—where the WorkBuddy client spawns a cbc child process and drives it via ACP session/prompt). Comma-separated and case-insensitive (e.g., x-wb-,x-mobile-). Empty by default = feature disabled (security kill switch); this is a security boundary, so choose prefixes that do not overlap with internal X-* header namespaces. Applies only to official models; headers are not sent to third-party/custom models

API Endpoints and Proxy

Environment Variable	Description
CODEBUDDY_BASE_URL	Override the API endpoint address, typically used with CODEBUDDY_API_KEY
CODEBUDDY_INTERNET_ENVIRONMENT	Network environment configuration (internal for China edition, ioa for iOA enterprise edition)
HTTP_PROXY / http_proxy	HTTP proxy server address
HTTPS_PROXY / https_proxy	HTTPS proxy server address
NO_PROXY / no_proxy	List of domains and IPs to bypass proxy (comma-separated, e.g., localhost,.example.com)

Model Configuration

Environment Variable	Description
CODEBUDDY_MODEL	Override the default agent model
CODEBUDDY_SMALL_FAST_MODEL	Override the model for the lite (lightweight, fast) scenario variant; takes priority over the variantModels.lite setting
CODEBUDDY_BIG_SLOW_MODEL	Override the model for the reasoning (enhanced reasoning) scenario variant; takes priority over the variantModels.reasoning setting
CODEBUDDY_CODE_SUBAGENT_MODEL	Blanket override of the model for all built-in sub-agents (highest priority, overrides the subagents setting). To configure per sub-agent, use the /agents panel or settings.json's subagents.agents.<subagent-name>.model
MAX_THINKING_TOKENS	Enable extended thinking and set the token budget for the thinking process. Disabled by default
CODEBUDDY_DISABLE_PROMPT_CACHING_1H	Set to a truthy value (1 / true / yes / on, case-insensitive) to disable the 1-hour prompt cache. Unset by default (i.e., the 1h cache is enabled): when using in-house/official models, requests carry cache_retention: "long", which extends the prompt cache TTL of Claude-family models from 5 minutes to 1 hour and significantly reduces credit consumption. When disabled, it falls back to the server default tier short (a 5-minute cache still applies; caching is not fully disabled). Custom (third-party) models are unaffected, as this field is only sent to the in-house gateway. The tier is locked on the first request of a session; changing this variable mid-session has no effect (to avoid flipping the TTL and invalidating the entire server-side cache already established)

Relationship between env and settings: Model-related environment variables are for ops/CI-level overrides.

• Built-in sub-agents: CODEBUDDY_CODE_SUBAGENT_MODEL > the model parameter of the current Agent tool call > project-level subagents > user-global subagents > product built-in declaration > main model.

• Scenario variants: corresponding variant env var > project-level variantModels > user-global variantModels > main model's relatedModels > applicable product built-in default > main model.

• CODEBUDDY_CODE_SUBAGENT_MODEL uniformly overrides all sub-agents. To specify individually, use /agents or subagents.agents.<subagent-name>.model; see Sub-Agents for details.

• CODEBUDDY_SMALL_FAST_MODEL only affects lite, CODEBUDDY_BIG_SLOW_MODEL only affects reasoning. The corresponding persistent settings can be managed via /model or variantModels; see Settings for details.

Removing the environment variable restores the lower-priority configuration, which may not directly fall back to the main model.

Bash Tool Configuration

Environment Variable	Description
BASH_DEFAULT_TIMEOUT_MS	Default timeout for long-running bash commands (default: 120000)
BASH_MAX_OUTPUT_LENGTH	Maximum characters of bash output retained in memory (default: 30000, max: 150000). Content exceeding the limit is mid-truncated (keeping head 20% + tail 80%), and the full output is automatically saved to disk
BASH_MAX_TIMEOUT_MS	Maximum timeout the model can set for long-running bash commands (default: 600000)
CODEBUDDY_BASH_ASSISTANT_BUDGET_MS	Main conversation response budget (milliseconds, default 0=off). When set to >0, foreground Bash/PowerShell commands in the main session that exceed this duration are automatically converted into background tasks to keep the conversation responsive. Sub-agents are not affected by this budget. This does not apply in -p (print, non-stdio stream-json) non-interactive mode—the process exits with the main turn, so background tasks cannot continue and commands always remain in the foreground until completion. Aligns with Claude Code's ASSISTANT_BLOCKING_BUDGET_MS (official default value is 15000)
CODEBUDDY_BASH_AUTO_BACKGROUND_DISABLED	Set to 1 to disable timeout auto-backgrounding; foreground commands fall back to the old SIGTERM/kill hard-kill behavior on timeout. Only used for debugging or temporary rollback when encountering regressions; keep the default (unset) in normal scenarios. Note: -p (print, non-stdio stream-json) non-interactive mode already disables auto-backgrounding, so this variable is unnecessary there
CODEBUDDY_BASH_BG_MAX_OUTPUT_BYTES	Total byte limit for the on-disk file of stdout+stderr for background bash tasks (default 52428800 = 50MB). When exceeded, the size watchdog fires SIGKILL and marks the task as killed, with a notice injected at the end of stderr. Claude Code in ShellCommand.ts hardcodes the equivalent threshold as a constant; here it is exposed as an env var for operators to tune. Only effective in file fd mode (in pipe mode, child process output is not persisted to disk)
CODEBUDDY_BASH_BG_PIPE_MODE	Set to 1 to force background tasks back to pipe mode (not using file fds), for rollback or debugging. The default (unset) uses file fd mode, which solves the zombie process issue caused by grandchild processes (e.g., spawned via nohup) holding parent pipe fds; the sandbox path automatically falls back to pipe and does not require explicit setting. There is no equivalent toggle in Claude Code; this is a CodeBuddy fallback to remain compatible with legacy sandbox/PTY paths
CODEBUDDY_BG_TASK_RECONCILE	Set to 0 to disable background-task liveness reconciliation. Enabled by default (when unset): every 5 seconds, it checks whether background-task processes have terminated and, after two consecutive confirmations, finalizes the task state and sends a completion notification. This handles cases where the child process has exited but the process termination event was not delivered, which would otherwise leave the task stuck in the running state without a completion notification. Use only for rollback or troubleshooting false positives; keep the default in normal scenarios

Tool Output Externalization

Environment Variable	Description
CODEBUDDY_TOOL_RESULT_THRESHOLD_KB	Size threshold (KB) for tool result externalization. Non-bash tool results exceeding this threshold are saved to disk and replaced with a placeholder (default: 50)

Note: Bash tool output externalization is controlled by BASH_MAX_OUTPUT_LENGTH. When output is truncated due to exceeding that value, the full output is automatically streamed to disk. CODEBUDDY_TOOL_RESULT_THRESHOLD_KB primarily affects large output handling for other tools (e.g., MCP tools). See the Tool Output Externalization section for details.

Tools and Feature Toggles

Environment Variable	Description
CODEBUDDY_DISABLE_HOT_RELOAD	Set to 1 to disable the hot reload system
CODEBUDDY_SKIP_BUILTIN_MARKETPLACE	Set to 1 to skip loading the built-in plugin marketplace
CODEBUDDY_AUTO_UPDATE_THIRD_PARTY_MARKETPLACES	Set to true or 1 to enable automatic updates for third-party plugin marketplaces (default: disabled)
CODEBUDDY_MARKETPLACE_AUTO_UPDATE_INTERVAL_MS	Override the refresh window for plugin marketplace auto-updates (milliseconds), default 86400000 (24 hours). Set to a smaller value (e.g., 3600000 = 1 hour) to shorten the auto-update detection interval, useful for testing/debugging; invalid values (non-numeric or ≤0) fall back to the default
CODEBUDDY_PLUGIN_DIRS	Colon-separated list of local plugin directory paths (equivalent to --plugin-dir). The bin/ directory of each plugin is automatically injected into PATH
CODEBUDDY_DISABLE_EXTENDED_PLUGIN_HOOKS	When set to 1 or true, plugin Hook configurations only accept the command type; configurations containing prompt, agent, or http types are treated as incompatible. Used by hosts to temporarily roll back the plugin Hook contract; unset by default
CODEBUDDY_PLUGIN_STATUS_REPORT_ENABLED	Set to true or 1 to enable plugin_status reporting. Off by default; only the CLI UI build enables it by default when not explicitly configured. When enabled, the same account on the same machine reports successfully at most once per calendar day
CODEBUDDY_SHOW_CONTEXT_USAGE	Set to 1, true, yes, or on to always show the current session's context window usage (overrides the default threshold-based display)
CODEBUDDY_IMAGE_GEN_ENABLED	Set to false or 0 to disable image generation
CODEBUDDY_BRIEF	Set to 1 / true / yes to enable the SendUserMessage tool (same as --brief) so the agent can send user-facing messages; the tool is hidden when unset
CODEBUDDY_IS_SANDBOX	Process environment only. Set to 1 / true / yes / on to skip HIGH/CRITICAL approvals when used with -y. Setting it alone does not change the default mode. See Sandbox full pass (high risk). Unset by default
CODEBUDDY_IMAGE_EDIT_ENABLED	Set to false or 0 to disable image editing
CODEBUDDY_ARTIFACT_ENABLED	Set to false or 0 to disable the Artifact / ArtifactControl tool (publishes a local single HTML or Markdown file as a shareable public link; Markdown is server-rendered into a styled page; ArtifactControl currently only supports unpublishing). Enabled by default. Evaluation order: under international endpoints (codebuddy.ai / workbuddy.ai / staging-codebuddy.tencent.com), this capability is always off and this variable cannot override it; in all other scenarios, this variable has the highest priority — when unset (including empty values), falls back to the legacy variable CODEBUDDY_SHARE_LINK_ENABLED, then to the cloud-side productFeatures (if either Artifact or ShareLink is explicitly false, the feature is off; when neither is delivered, defaults to true)
CODEBUDDY_SHARE_LINK_ENABLED	Deprecated (kept for compatibility): The former name of CODEBUDDY_ARTIFACT_ENABLED, the toggle from before the ShareLink tool was renamed to Artifact. Semantics are identical to the new variable, which takes priority; only takes effect when the new variable is unset
CODEBUDDY_COMPUTER_USE_ENABLED	Experimental: Set to true or 1 to enable the macOS desktop control tool (screenshot, mouse, keyboard). Available only on macOS, disabled by default. The first invocation of keyboard/mouse actions requires authorizing the terminal in System Settings → Privacy & Security → Accessibility and Screen Recording
CODEBUDDY_PUSH_NOTIFICATION_ENABLED	Set to false or 0 to disable the PushNotification tool (the model can proactively trigger a terminal/desktop notification when long-running or background tasks complete). Enabled by default
CODEBUDDY_REPORT_FINDINGS_ENABLED	Set to false or 0 to disable the ReportFindings tool (used by code review Agents to submit findings as structured fields, rendered as a dedicated list component). Enabled by default
CODEBUDDY_WAIT_FOR_MCP_SERVERS_ENABLED	Set to 0 or false to disable the WaitForMcpServers tool. Enabled by default. In interactive mode, MCP connections are not awaited blockingly; when the LLM needs an MCP tool that is not yet ready, it can proactively call this tool to wait on demand. Set to 0 to disable in WorkBuddy scenarios
CODEBUDDY_DEFERRED_TOOLS_MCP_READY_WAIT_MS	Maximum milliseconds to wait for MCP servers to be ready before rendering deferred tool descriptions, default 2500. Set to 0 to skip waiting entirely — if connections are slow, the "still connecting" hint is immediately baked into the description; increase to give remote MCP servers more time to complete the handshake before the first prompt. Continues immediately once the server is ready; the timeout serves only as an upper bound
CODEBUDDY_DEFER_TOOL_LOADING	Set to false or 0 to disable MCP tool deferred loading
CODEBUDDY_SHOW_ALL_DEFERRED_TOOLS	Set to true or 1 to show full descriptions for all deferred tools
CODEBUDDY_DISABLE_CRON	Set to 1 to disable scheduled tasks
CODEBUDDY_MAIN_AGENT_ENABLED	Master switch for the four main-agent modes. 0/false turns them off (no picker in the Web chip or TUI /agent-mode; the run chain ignores the standing main agent). If unset, reads codebuddy.mainAgent.enabled in settings.json, then defaults to on. Overrides settings
CODEBUDDY_MAIN_AGENT_ALLOW_UNOPTED	Allow ACP hosts that do not declare mainAgentSupport (WorkBuddy Desktop / sidecar) to use mode resolution. Off by default: those hosts always stay native cli. 1/true turns it on (still requires the master switch). Overrides codebuddy.mainAgent.allowUnopted
CODEBUDDY_CODE_MODE_ENABLED	PTC / Minimal capability switch. 0 / false disables and hides both modes; 1 / true permits them without forcing a mode. If unset, the TUI and built-in Web UI permit them by default; other hosts do not. The selected model must also declare toolMode=code_mode/code_mode_only. Missing, direct, or invalid declarations disable these modes; switching to an unsupported model resets this session to Standard. User choices take precedence only within these limits. Standard / Creator and host opt-in requirements remain unchanged. The old CODEBUDDY_REPL_ENABLED variable is no longer read
CODEBUDDY_REPL_TOOLS_INJECT_BUILTIN	Built-in sandbox tool injection, enabled by default; explicit 0 / false disables it. Disabling omits built-in tools from both the skeleton catalog and sandbox without changing the selected mode. Mode, role, session, and permission limits still apply
CODEBUDDY_REPL_TOOLS_INJECT_CATALOG	Whether to inject the skeleton tool catalog into the REPL code parameter description. On by default. 0 turns it off: tools are still preloaded, but the model is not told about them in advance and falls back to pure progressive disclosure (discovery via REPL.searchTools / REPL.describeTool)
CODEBUDDY_REPL_NESTED_TIMEOUT_MS	Wait limit for nested interactions inside the REPL, in milliseconds. Only AskUserQuestion in PTC mode is unlimited by default: when unset, blank, or 0, no timeout timer is created and the user can still answer after returning later; cancelling or stopping ends the wait. A finite value in the 1–2147483647 range sets an explicit limit, and decimals are floored; any other value falls back to unlimited. The budget covers both the wait decision and the answer. Non-PTC REPL questions, ExitPlanMode, and security approvals keep the original rules: default 600000 (10 minutes), a finite positive number overrides the default, and invalid values such as 0 fall back to the default. Direct questions in normal mode are not affected by this variable
CODEBUDDY_DISABLE_FORK_SUBAGENT	Set to 1 to disable the Agent tool's fork sub-agent mode (subagent_type="fork"). When enabled, the fork-mode section is automatically hidden from the Agent tool description, so the model will not see this feature; if the model still passes subagent_type="fork", the runtime falls back to a custom agent named fork (e.g., one defined by the user at .codebuddy/agents/fork.md), or otherwise rewrites it to a general-purpose regular sub-agent. Useful for host scenarios that need to avoid request amplification caused by recursive fork spawning
CODEBUDDY_DISABLE_BUILTIN_SUBAGENTS	Set to 1 to block only built-in sub-agents (general-purpose/fork/Explore/Plan/statusline-setup), without affecting custom agents, plugin agents, Teams, or other tools (including outbound A2A tools; see ProductFeature.A2AOutbound, which is entirely independent). When enabled, these built-in sub-agent sections are automatically hidden from the Agent tool description. If the model still passes one of these subagent_type values and the host/project has not defined a custom or plugin agent with the same name to override it, the runtime rejects the call and instructs the model to complete the remaining work with its own tools. Unset by default (built-in sub-agents remain available)
CODEBUDDY_A2A_OUTBOUND_ENABLED	Set to 1/true/yes/on to force-enable outbound A2A (A2AGetAgentCard/A2ASendMessage/A2AGetTask/A2ACancelTask) for local development or manual verification without waiting for cloud-side ProductFeature.A2AOutbound configuration. This is enable-only: explicitly setting 0/false is equivalent to leaving it unset and does not force-disable the feature—the cloud configuration remains the authoritative kill switch (operators can still remotely deliver false even if this variable remains in a host process). Evaluation order: if this variable enables the feature, it takes effect immediately and no AbTestService query is made; otherwise (including an empty value), falls back to ProductFeature.A2AOutbound (disabled by default)
CODEBUDDY_RESPONSES_STORE_ENABLED	Set to 1/true/yes/on to force-enable the ResponsesStore product feature: model requests with api: "openai-responses" switch from the default store: false to store: true. WorkBuddy's --features '{"rollout":true}' passes this to the agent
CODEBUDDY_DISABLE_SENSITIVE_PROTECTION	Set to 1/true/yes/on to disable sensitive data protection for this process. Same effect as sensitiveProtection.enabled: false in settings.json, but without modifying the shared settings file; values delivered by enterprise managed policy still take precedence. WorkBuddy's --features '{"rollout":true}' passes this to the agent
CODEBUDDY_A2A_DISCOVERY_PREWAIT_MS	Bounded pre-wait budget in milliseconds for initial outbound A2A discovery (default 2000). When outbound A2A is enabled, the <available_A2A_agents> list in the A2AGetAgentCard tool description is rendered dynamically from discovery results (CODEBUDDY_REMOTE_AGENTS_URL). To make that list available to the first message, the first model request waits at most this long for discovery to complete (localhost discovery is usually much faster). A timeout or cancellation abandons the wait and continues; reactive refresh adds the list once discovery eventually completes—so this variable only affects whether the first turn sees the results, not correctness. Set to 0 to disable the wait (discovery still runs in the background, so the first turn may initially render an empty list). Discovery fetches are single-flight and the pre-wait never causes an extra network request
CODEBUDDY_A2A_WAIT_IDLE_TIMEOUT_MS	Timeout in milliseconds for inbound A2A SendMessage to wait for the session to become idle (default 600000, or 10 minutes). Before execution is submitted, an A2A request waits until the current session has no run in flight—in mixed mode (--a2a --input-format stream-json), that run is usually an ongoing human conversation turn, so the default is intentionally generous. This timeout is a failure safeguard rather than the normal path: with stdio transport, callers have no HTTP timeout to rely on, so an upper bound prevents a stuck session from hanging an A2A caller forever. On timeout, that SendMessage returns a failed Task. Only positive values are accepted; invalid values fall back to the default
CODEBUDDY_A2A_CONTEXT_TTL_MS	Validity period in milliseconds for outbound A2A conversation continuity (default 86400000, or 24 hours). A2ASendMessage remembers the last contextId for each discovery source + remote Agent and automatically includes it in later calls from the same session, keeping multi-turn conversations in the same remote context. This record is persisted with the session and remains available after --resume. A remote endpoint may reclaim expired contexts and, per the A2A specification, must reject an unknown contextId rather than silently creating one. Once this local TTL expires, CodeBuddy proactively drops the old ID and starts a new context, preventing every subsequent call from failing against an invalid ID. The timer is based on last use rather than creation, so continuously active conversations do not expire mid-session. Non-positive integers or unparsable values fall back to the default (fail open; a bad environment variable must not silently disable continuity)
CODEBUDDY_CODE_DISABLE_BACKGROUND_TASKS	Set to 1 / true to disable background tasks for the Agent, Bash, and PowerShell tools (run_in_background=true). When enabled, the run_in_background parameter is hidden from these tools' schemas so the model will not see it; even if historical/cached tool calls or direct callers pass this parameter, the runtime falls back to synchronous (Agent) / foreground (Bash, PowerShell) execution. Suitable for request-response SDK / one-shot task scenarios—where the main process exits immediately after the main turn ends and any background agent/background command results cannot flow back to the final response. Aligns with Claude Code's CLAUDE_CODE_DISABLE_BACKGROUND_TASKS (which also governs Agent + Bash + PowerShell). Unset by default (background tasks remain available). Independent from the print-mode guard (which always blocks background execution under -p). Also refuses Multitask: --agent multitask / --multitask exits non-zero; /multitask, session/set_config_option (configId=multitask), and the dialect-specific session/set_multitask fail; initialize.multitaskSupport is false; resume with standing key multitask does not restamp the coordinator (avoids locking the tool surface)
CODEBUDDY_A2A_DISCOVERY_TTL_MS	Cache validity period in milliseconds for outbound A2A Agent Card discovery results (default 43200000). Every A2A tool execution checks freshness; successful results are reused while valid, the first call after expiry refreshes on demand, and concurrent calls share a single fetch. A change to the discovery URL invalidates the cache immediately; a successful empty list is cached as well. Set to 0 to refresh on every sequential tool execution (concurrent calls are still single-flight); empty, negative, or non-finite values fall back to the default
CODEBUDDY_A2A_INPUT_REQUIRED_TIMEOUT_MS	Timeout in milliseconds for an inbound A2A Task to wait for a caller response after entering input-required (default 600000, or 10 minutes). When the timeout expires, the original execution is terminated and the Task is marked as failed, releasing the session reservation and event bus so a disconnected caller cannot occupy a standalone or mixed session forever. Only positive values are accepted; invalid values fall back to the default
CODEBUDDY_A2A_SEND_MAX_RETRIES	How many times outbound A2A A2ASendMessage auto-retries on a transient network failure (default 2, i.e. up to 1+2=3 attempts). All retries happen inside the same tool call and re-send the exact same message and the same messageId — so a connectivity failure is not surfaced to the model (which would re-call the tool and mint a NEW messageId, making the remote agent see a duplicate request); a messageId-deduping remote instead sees one request. Uses exponential backoff (500ms, 1000ms, … with jitter). Only failures that almost certainly never landed are retried: connection-level errors (ECONNREFUSED/DNS/connection reset/socket hang up, etc.) and gateway/rate-limit statuses 429/502/503/504; 4xx, 500 and other 5xx, user aborts, and an exhausted overall timeout budget are NOT retried. Set to 0 to disable retry (single attempt); clamped to a max of 10; empty/negative/non-integer values fall back to the default 2
CODEBUDDY_REHYDRATE_IMAGE_BLOB_REFS	Set to true to rehydrate image blob references to full base64 data in -p mode streaming output. Useful for downstream integrations that need direct access to image data
CODEBUDDY_SKIP_READ_TOOL_IMAGE_REHYDRATION_IN_HISTORY	When set to true, Read tool images in -p history replay keep their blob references instead of being inlined as base64, even when general image blob rehydration is enabled. Live Read output and model context are unaffected
CODEBUDDY_HISTORY_REPLAY_MAX_CONTENT_BYTES	Per-field UTF-8 byte limit for function call arguments, tool result text, and reasoning text in history replay; content beyond the limit is shown as .... Only positive integers are accepted; when unset or invalid, nothing is truncated. Live output, user messages, final assistant replies, and model context are unaffected
CODEBUDDY_REPL_TOOLS_INJECT_CATALOG	Fine-grained switch for REPL tool catalog injection. On by default; only an explicit 0 or false turns it off (tools are still preloaded, but the model is not told about them in advance and falls back to pure progressive disclosure)
CODEBUDDY_REPL_TOOLS_INJECT_BUILTIN	Built-in sandbox tool injection, enabled by default; explicit 0 / false disables it. Disabling omits built-in tools from both the skeleton catalog and sandbox without changing the selected mode. Mode, role, session, and permission limits still apply
CODEBUDDY_SKILL_DESC_MAX_OVERRIDES	Override the per-entry character limit for Skill tool descriptions by skill name (default 150). Format: a JSON object mapping skill names to character limits, for example {"workbuddy-office-routing":300,"tencent-pptx":300}. An override completely replaces that skill's default limit (it may raise or lower it) and is no longer subject to a second proportional truncation under the total Skill character budget. As a result, explicit overrides remain effective even when a built-in skill changes source from bundled to plugin after a marketplace update. The configuration applies equally to all sources, including built-ins. Skill names are JSON keys, so plugin skill names containing colons (such as plugin:skill) are supported naturally. Values must be positive integers (non-positive integers, decimals, and numeric strings are skipped), and dangerous keys such as __proto__/constructor/prototype are ignored. Invalid JSON or a non-object top level causes the entire value to be ignored with a warning. When unset, all skills use their default limits and behavior is unchanged
CODEBUDDY_TOOL_SEARCH_MIN_SCORE_RATIO	Relevance floor for ToolSearch results, as a ratio of the top score (0–1). Results scoring below top score × ratio are treated as low-relevance noise and dropped, reducing irrelevant tools in the results; default 0.3, set to 0 to disable this filter
CODEBUDDY_TOOL_SEARCH_CAMEL_SPLIT	Toggle for ToolSearch camelCase splitting of tool names during indexing (e.g., getWorkspaceConfig is additionally indexed as get/Workspace/Config), improving recall for single-word queries; on by default, set to 0/false/off/no to fall back to default tokenization. A temporary rollback switch, planned for removal once stable

Sandbox full pass (high risk)

CODEBUDDY_IS_SANDBOX turns -y inside an isolated sandbox into a true full pass by skipping confirmations for HIGH/CRITICAL dangerous commands. It is intentionally an environment variable rather than a CLI argument: granting unrestricted permissions is high risk and must be explicitly declared by the launching process, following common sandbox design and preventing codebuddy -y from being mistaken for unconditional approval bypass.

export CODEBUDDY_IS_SANDBOX=1
codebuddy -y
# Or in one line
export CODEBUDDY_IS_SANDBOX=1 && cbc -y

⚠️ Risk notice

• Once enabled, the agent can execute dangerous commands without confirmation (such as deleting files or changing system state), potentially causing data loss, system damage, or credential and data exposure through prompt injection.
• Use only in trusted isolated sandboxes, containers, VMs, or environments without internet access. Do not enable it for everyday local development, on shared machines, or in environments with access to production credentials.
• It is read exclusively from the process environment and is not injected from the env field of settings.json (including project-level settings), preventing a repository from silently escalating privileges.
• Setting it alone, without -y / bypassPermissions, does not change the default permission mode.
• The visible mode remains bypassPermissions (the TUI label is unchanged, but shown in red); it is not renamed to fullAccess.
• permissions.disableBypassPermissionsMode: "disable" still applies: once bypass mode is disabled, this variable cannot enable full pass.
• Explicit deny rules still have the highest priority.

The -y / --dangerously-skip-permissions description in codebuddy -h also points to this variable.

Context and Memory

Environment Variable	Description
CODEBUDDY_AUTOCOMPACT_PCT_OVERRIDE	Set the context capacity percentage for triggering auto-compaction (1-100). Default is determined by product configuration (typically 70-92%). Use a lower value (e.g., 50) to compact earlier
CODEBUDDY_AUTO_COMPACT_WINDOW	Base context window (in tokens) used for auto-compaction calculations. Trigger point = min(this value, model effective budget) × threshold, clamped to [100k, 1M] and never exceeding the model's actual window. Takes precedence over the settings key autoCompactWindow (env > settings). Leave empty to follow the model window
CODEBUDDY_PRE_MESSAGE_COMPACT	Force-control the pre-message compaction toggle. true/1 to enable, false/0 to disable. Takes priority over the product configuration's enablePreMessageCompact and the ContextSummaryAgent toggle
CODEBUDDY_PRE_MESSAGE_COMPACT_PCT	Set the context capacity percentage for pre-message compaction check (1-100). Default is 10%. When context exceeds this threshold, it is automatically compacted before processing the user's new message
CODEBUDDY_DISABLE_AUTO_MEMORY	Set to 1 to disable auto memory, set to 0 to enable
CODEBUDDY_DISABLE_PARENT_MEMORY	Set to 1 to stop project instruction files (CODEBUDDY.md/AGENTS.md) from being discovered recursively upward beyond the launch directory; only the launch directory itself is loaded. Takes precedence over the settings key memory.parentDiscovery
CODEBUDDY_MEMORY_ENABLED	Set to true or 1 to enable memory functionality
CODEBUDDY_TYPED_MEMORY_ENABLED	Set to true or 1 to enable typed memory mode
CODEBUDDY_TEAM_MEMORY_ENABLED	Set to true or 1 to enable team memory mode
CODEBUDDY_USER_ID	User ID for team memory mode

MCP (Model Context Protocol)

Environment Variable	Description
MCP_TIMEOUT	Timeout for MCP server connections (milliseconds)
MCP_TOOL_TIMEOUT	Timeout for MCP tool execution (milliseconds)
MAX_MCP_OUTPUT_TOKENS	Maximum tokens allowed in MCP tool responses (default: 20000)
CODEBUDDY_DISABLE_MCP_LARGE_OUTPUT_FILES	When set to 1, MCP oversized responses are not persisted to disk (skipping the ~/.codebuddy/projects/.../tool-results/ files), always falling back to content truncation

Performance and Output

Environment Variable	Description
CODEBUDDY_CODE_MAX_OUTPUT_TOKENS	Set the maximum output tokens for most requests
CODEBUDDY_CODE_FILE_READ_MAX_OUTPUT_TOKENS	Override the default token limit for file reads (default: 20000)
CODEBUDDY_STREAM_TIMEOUT_MS	Maximum silent time allowed between two data chunks in a streaming response (milliseconds) (default: 1200000, or 20 minutes). Structurally decoupled from the first-token timeout and independently configurable; lower this value to detect dead connections sooner on gateways or proxy paths prone to half-open connections. The first-token timeout is unaffected
CODEBUDDY_FIRST_TOKEN_TIMEOUT_MS	Maximum time to wait for the first model output (milliseconds) (default: 1200000, i.e., 20 minutes). Slow first-token emission due to long-context prefill is a legitimate scenario
CODEBUDDY_RECOVERY_FIRST_TOKEN_TIMEOUT_MS	Maximum time (milliseconds) the first request of an auto-recovery turn (the continuation after a network error / stream timeout / first-token timeout / model finish_reason=error) waits for the first model output (default: 300000, i.e., 5 minutes); also covers the wait for response headers. Never exceeds CODEBUDDY_FIRST_TOKEN_TIMEOUT_MS
CODEBUDDY_EMPTY_STREAM_RETRY_MAX_ELAPSED_MS	Maximum elapsed time (milliseconds) up to which an empty stream (upstream finish_reason=error with zero model output) is still eligible for automatic session-level retry (default: 300000, i.e., 5 minutes); pass 0 to disable this gate and fall back to judging by retry budget only. If the stream had already run longer than this before receiving the error, it hit the upstream's own hard time limit rather than a transient glitch; re-running the same prompt would inevitably run to the limit again and only multiply the silent duration, so no automatic retry is made and the terminal state is handed directly to the caller
CODEBUDDY_REASONING_KEEPALIVE_INTERVAL_MS	Push interval (milliseconds) for the "long reasoning without wrap-up" keepalive signal. Unset by default = fully disabled, zero behavior change; set to a positive number to enable. Only in the specific scenario where "the model keeps emitting reasoning but produces no substantive content (text/tool_call/refusal) for a long time, while upstream is still sending packets" does it push a liveness/progress notification without reasoning content to the caller at this interval (stream-json reuses the keepalive frame with reason=reasoning_in_progress), letting the caller distinguish "long reasoning" from "truly stuck" and keeping the sandbox-proxy liveness watermark fed. Observe-only, never interrupts; decoupled from first-token / inter-chunk idle timeouts
CODEBUDDY_MAX_RETRIES	Maximum backoff retry count for model request failures that occur "before generation starts" (429 / 5xx except 570-579 / request timeout / lock timeout) (default: 8, max: 15, auto-clamped when exceeded). Retries use exponential backoff starting at 1s, doubling each time with a 32s base cap and ±10% jitter (actual waits are 90%–110% of the base). When the server sends retry-after (seconds or an HTTP date) or the error body carries retry_policy.retry_after, the CLI waits for the later of the two and never shortens it. Retries strictly occur before streaming content is produced and do not resend already-produced content; errors reported inside a stream after HTTP 200 are handled by session recovery and do not count here. Quota-exhaustion errors are not retried (handled by model fallback instead). Connection-level transport failures (before response headers, non-DNS) are not controlled by this variable: native TUI main sessions reconnect indefinitely with a 1/2/4/8/16/32/64s base, then stay at 64s (±10% jitter); other entry points keep a separate 3-retry budget. When the error body carries a model gateway retry_policy, the gateway takes precedence: if retry is false or "false", no retry; otherwise, within the status range above, at most 8 retries, overriding this variable
CODEBUDDY_RETRY_WATCHDOG	Set to 1 / true / yes to enable infinite retry mode for unattended / CI scenarios. Only applies to the "before generation starts" failures above; the backoff base is capped at 5 minutes (up to 5 minutes 30 seconds after ±10% jitter). Has no effect when the error body carries a gateway retry_policy (handled per gateway policy). Off by default
CODEBUDDY_MODEL_401_MAX_RETRIES	Number of blind retries when a model request returns HTTP 401 (default 0, i.e., disabled; max 15, auto-clamped when exceeded). Only intended for deployments where "an auth proxy in front of the CLI injects Authorization: Bearer on its behalf": in such setups the token is held and renewed by the proxy, the CLI's local credential is just a placeholder, and a 401 during the proxy's token rotation is a recoverable glitch that does not mean re-login is needed. When enabled, 401 requests are resent as-is at a fixed interval (retries strictly occur before streaming content is produced and do not resend already-produced content). Only applies to built-in/official models; a 401 on a custom third-party model means the user-managed API Key is invalid and is never retried. Gateway retry_policy with retry: false and request cancellation take precedence over this variable
CODEBUDDY_MODEL_401_RETRY_DELAY_MS	Fixed interval (milliseconds) for the 401 retries above (default: 2000, max: 32000). Deliberately a fixed interval rather than exponential backoff—401 has no retry-after semantics, and the proxy's token rotation is a roughly constant window. Only meaningful when CODEBUDDY_MODEL_401_MAX_RETRIES is greater than 0
CODEBUDDY_SESSION_MAX_ITEMS	Maximum number of history messages to replay during session/load (default: 1000). Stops reading the JSONL in reverse when the threshold is reached and a user message is encountered. Increase (e.g., 2000 or more) when very long sessions need to be supported (such as sandbox scenarios); zero/negative/non-numeric values fall back to the default

Filesystem and Configuration

Environment Variable	Description
CODEBUDDY_CONFIG_DIR	Custom location for CodeBuddy Code to store configuration and data files
CODEBUDDY_CODE_DEBUG_LOGS_DIR	Debug log directory
CODEBUDDY_SANDBOX_IMAGE	Container sandbox image (default: node:20-alpine)
USE_BUILTIN_RIPGREP	Set to 0 to use system-installed rg instead of the one bundled with CodeBuddy Code

Shell Configuration

Environment Variable	Description
CODEBUDDY_CODE_SHELL	Override automatic shell detection. Supported values: bash, zsh, sh, powershell
CODEBUDDY_CODE_SHELL_PREFIX	Command prefix wrapping all shell commands (e.g., for logging or auditing)
CODEBUDDY_CODE_GIT_BASH_PATH	Explicitly specify the Git Bash path on Windows; startup fails if the specified path is invalid
CODEBUDDY_SKIP_GIT_BASH_CHECK	Set to 1 to skip the Windows Git Bash detection and prompt at startup (useful when the upstream already manages the shell)
CODEBUDDY_DISABLE_CHILD_PROCESS_CONTAINMENT	Startup toggle for cleaning up descendant processes when CodeBuddy exits on Windows. 1 / true disables containment; unset / empty / 0 / false enables it. Read only at startup, so restart the CLI (including prewarmed processes) after changing it. macOS/Linux are unaffected
CODEBUDDY_INTERNAL_DAEMON_CHANNEL	One-time internal IPC marker used by the Windows daemon supervisor. It is consumed and removed at startup, is not a user configuration option, and is not passed to regular child processes
CODEBUDDY_POWERSHELL_PATH	Explicitly specify the PowerShell executable path (takes priority over auto-detection)
CODEBUDDY_USE_POWERSHELL_TOOL	Control PowerShell tool enablement. Enabled by default on Windows, set to 0 to disable
CODEBUDDY_ENV_FILE	Path to an environment file that is automatically sourced before executing each shell command
CODEBUDDY_SHELL_PREPEND_PATH	Directories to prepend to the PATH of shell commands, separated by ; on Windows and : on other platforms. For bash/zsh commands they are prepended after the shell snapshot is loaded, and they are likewise prepended for PowerShell commands; risk review also reads it when determining where a command comes from, and the Linux sandbox grants read-only access to the managed Node/Python runtime directories listed in it. Hook commands and MCP servers can see this variable, but their PATH is unchanged. When started as a library, it is provided per session by start({ shellEnvironmentPolicy }). Earlier versions read WORKBUDDY_EXTRA_PATHS
CODEBUDDY_DISABLE_SHELL_SNAPSHOT	Set to 1 to disable shell environment snapshots on all platforms (helpful when bash profile loading is slow)
CODEBUDDY_ENABLE_SHELL_SNAPSHOT	On Windows without Git Bash, snapshots are skipped by default; set to 1 to force enable (usually not needed)

UI and Interaction

Environment Variable	Description
CODEBUDDY_CODE_DISABLE_TERMINAL_TITLE	Set to 1 to disable automatic terminal title updates
CODEBUDDY_INCLUDE_PROMPT_SUGGESTION	Explicitly enable prompt suggestions, overriding the headless default (off) and promptSuggestionEnabled=false configuration
CODEBUDDY_PROMPT_SUGGESTION_DISABLED	Set to 1 / true to disable prompt suggestions, takes priority over CODEBUDDY_INCLUDE_PROMPT_SUGGESTION
CODEBUDDY_ENABLE_ASK_USER_FOR_STRUCTURED_INPUT	Set to 1 / true to enable the AskUserForStructuredInput tool (disabled by default); takes effect only in ACP or stream-json mode when the client declares the elicitation.form capability
IS_DEMO	Set to true to enable demo mode: hides email and organization

Security and Authentication

Environment Variable	Description
CODEBUDDY_CODE_CLIENT_CERT	mTLS client certificate file path ⚠️ Not yet supported
CODEBUDDY_CODE_CLIENT_KEY	mTLS client private key file path ⚠️ Not yet supported
CODEBUDDY_CODE_CLIENT_KEY_PASSPHRASE	Passphrase for the mTLS encrypted private key (optional) ⚠️ Not yet supported

Telemetry and Reporting

Environment Variable	Description
DISABLE_TELEMETRY	Set to 1 to disable telemetry
DISABLE_ERROR_REPORTING	Set to 1 to disable error reporting
DISABLE_AUTOUPDATER	Set to 1 to disable auto-updates
DISABLE_FEEDBACK_COMMAND	Set to 1 to disable the /feedback command

OpenTelemetry Custom Reporting (traces)

CodeBuddy Code supports reporting internal traces to your own Collector via the OTLP protocol. Environment variables follow the OpenTelemetry specification. For detailed usage, see Monitoring.

Environment Variable	Description
CODEBUDDY_CODE_ENABLE_TELEMETRY	Set to 1 to enable OTel custom reporting; the legacy alias CLAUDE_CODE_ENABLE_TELEMETRY is also accepted for backward compatibility
OTEL_TRACES_EXPORTER	otlp (default) / console (output to logs, useful for debugging) / none (off)
OTEL_EXPORTER_OTLP_ENDPOINT	Generic OTLP endpoint; the tool automatically appends /v1/traces
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT	Traces-specific endpoint, used as a complete URL; takes priority over the generic variable
OTEL_EXPORTER_OTLP_HEADERS	OTLP request headers in the format k1=v1,k2=v2; values support URL encoding
OTEL_EXPORTER_OTLP_TRACES_HEADERS	Traces-specific request headers; takes priority over the generic variable
OTEL_EXPORTER_OTLP_PROTOCOL	Only http/protobuf (default) is supported; other values (such as grpc, http/json) fall back and emit a warning
OTEL_SERVICE_NAME	Override the default service.name
OTEL_RESOURCE_ATTRIBUTES	Resource attributes in the format k1=v1,k2=v2; merged into the trace resource
OTEL_LOG_RAW_API_BODIES	Record full model API request/response bodies (same as Claude Code): file:<dir> writes to a local directory (*.request.json / *.response.json + index.jsonl); other truthy values are recorded as span events (60KB truncation). See Monitoring

When DISABLE_TELEMETRY=1, OTel reporting is turned off regardless of the variables above.

Tasks and Background Work

Environment Variable	Description
CODEBUDDY_DISABLE_BACKGROUND_TASKS	Set to 1 to disable all background task functionality

Daemon Mode

Environment Variable	Description
CODEBUDDY_DAEMON_ALLOW_SLEEP	Set to 1 or true to disable the daemon's sleep prevention (allows the system to enter idle sleep normally). Auto-reconnect after wake is not affected
CODEBUDDY_DAEMON_AUTO_CONNECT_CHANNELS	Set to 0 or false to disable automatic channel connection (WeChat/WeCom) on daemon startup. Can also be configured via daemonAutoConnectChannels: false in settings.json. Individual instances can set autoConnect: false in instances.json
CODEBUDDY_DAEMON_AUTO_RESTART_DISABLED	Set to 1 or true to let the daemon keep checking for and installing updates without restarting itself after installation; suitable when a systemd timer or external supervisor schedules the switchover
CODEBUDDY_DAEMON_SERVICE_MANAGER	Written automatically as systemd by the system service installer. On self-restart, the daemon does not fork inside the old cgroup; instead it exits with a dedicated failure code and is relaunched serially by Restart=on-failure. Users typically do not need to set this manually
CODEBUDDY_DAEMON_RESTORE_CHANNELS	Set by the system during daemon auto-restart, containing the list of channels to restore (comma-separated, e.g., wechat:abc,wecom:default). Users typically do not need to set this manually

Agent Home

Environment Variable	Description
CODEBUDDY_AGENT_HOME_TASK_RECEIPTS	Automatic task receipts: all (each item and the whole batch, default), batch (whole batch only), off (disables automatic main-Agent mail; channel task events and lead wrap-up are still kept). Can also be configured via codebuddy.agentHome.taskReceipts

Agent Execution Control

Environment Variable	Description
CODEBUDDY_CODE_MAX_TURNS	Maximum execution turns for the main Agent. Priority: CLI --max-turns > this environment variable > default (unlimited in the interactive TUI, 500 for other entry points)
CODEBUDDY_CODE_SUBAGENT_MAX_TURNS	Maximum execution turns for sub-Agents. Priority: CLI --max-turns > this environment variable > model dynamically passed max_turns > default (500)
CODEBUDDY_SUBAGENT_TIMEOUT_MS	Wall-clock timeout for synchronous foreground Agent tool calls (positive integer milliseconds, max 2147483647). Unset / empty / invalid / above the max = disabled (wait indefinitely); an operator guardrail of the same kind as CODEBUDDY_CODE_SUBAGENT_MAX_TURNS. The max is Node's 32-bit setTimeout limit—values above it would be clamped to 1ms and time out immediately. On timeout, the sub-Agent is terminated and its result is handed back to the main Agent; background, detached, and Team members are not affected
CODEBUDDY_CODE_MAX_CONCURRENT_SUBAGENTS	Maximum number of sub-Agents executing concurrently per root session tree (positive integer, default 20, adjustable up or down, cannot be disabled). Synchronous, background, Team member, Skill, and Workflow AgentTasks share the same limit; slots are released when a task completes, fails, is cancelled, or is terminated
CODEBUDDY_MAX_TOOL_USE_CONCURRENCY	Maximum number of concurrency-safe tool calls (read-only Read, Grep, Agent, etc.) issued by the model in the same turn that run at the same time (positive integer, default 10; empty, 0, negative, or non-numeric values fall back to the default). Excess calls are queued and started in the order given by the model as slots free up. Only affects parallelism within a single turn and does not change which calls may run concurrently; overall sub-Agent concurrency is separately limited by CODEBUDDY_CODE_MAX_CONCURRENT_SUBAGENTS. Aligned with Claude Code's CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY
CODEBUDDY_CODE_MAX_SUBAGENTS_PER_SESSION	Per-session sub-agent spawn budget limit (positive integer, default 200, adjustable up or down, cannot be disabled). Nested spawns share the same budget; when the limit is exceeded, the Agent tool returns an error and suggests using its own tools to complete the remaining work; resets after /clear creates a new session
CODEBUDDY_CODE_DISABLE_AUTO_MEMORY	Set to a truthy value to disable agent-level persistent memory (the frontmatter memory field no longer injects memory paragraphs). Unset by default (enabled)
CODEBUDDY_SUBAGENT_PERMISSION_MODE	Default permission mode for sub-agents/team members (e.g., bypassPermissions, acceptEdits, default, plan). Priority: Agent tool mode parameter > CLI --subagent-permission-mode > this environment variable > Settings permissions.subagentPermissionMode > mapping table default
CODEBUDDY_TEAM_SHUTDOWN_GRACEFUL_TIMEOUT_MS	Fallback timeout (in milliseconds) for graceful team member shutdown, default 15000. After this duration without a response from the teammate, the process is forcibly terminated. Set to 0 to disable the forced fallback (pure wait for response)

Gateway and Remote Access

Environment Variable	Description
CODEBUDDY_GATEWAY_AUTH	Gateway authentication mode (password or none). Highest priority, overrides --auth and settings gateway.auth. --serve defaults to password; setting to none disables authentication, allowing any process on the same machine to execute commands and read/write files via this service. Only recommended in isolated environments or CI
CODEBUDDY_GATEWAY_BASE_PATH	Public URL path prefix for the Gateway Web UI (e.g. /cnb-5gg-1k09dqp5v-001). --base-path wins. Unset or / means site root. When set, the printed Web UI link, login redirect, Cookie Path, and in-page /api /assets requests all include this prefix
CODEBUDDY_GATEWAY_PASSWORD	Gateway access password. When unset, a random password is automatically generated on first startup and written to settings
CODEBUDDY_GATEWAY_FORCE_TUNNEL	Set to 1 to force tunnel mode
CODEBUDDY_FRP_BUILTIN_ENABLED	When set to 1, the built-in FRP relay gateway is shown regardless of account type (by default it is only shown when the currently logged-in account belongs to iOA, determined by the account's idp / login domain, not by CODEBUDDY_INTERNET_ENVIRONMENT)
CODEBUDDY_FRP_BUILTIN_HUB_URL	Override the built-in FRP relay gateway URL (default http://frp.devcloud.woa.com)
CODEBUDDY_FRP_TLS	When set to 0, connections to frps do not use TLS (enabled by default; can also be set per gateway in the Web UI gateway settings)
CODEBUDDY_FRP_AUTO_SHARE	When set to 0, disables "automatically share local SSH after provisioning / importing an FRP gateway account" (enabled by default: if sshd already exists locally it is shared; otherwise a public-key-only sshd listening only on 127.0.0.1 is started silently; failures are shown in the Web UI relay tunnel with a retry option)
FRP_MANAGER_ADMIN_TOKEN	FRP gateway admin token, used only for one-click account provisioning on custom gateways in the Web UI; read only from the environment variable and never written to disk. With iOA login, the built-in gateway uses iOA identity for self-service provisioning instead and does not need it
CODEBUDDY_DISABLE_REQUEST_VALIDATION	Set to 1 to disable Gateway custom request header validation (X-CodeBuddy-Request). See HTTP API Security
CODEBUDDY_CODE_CORS_ORIGINS	Additional CORS allowed origins (comma-separated). Supports exact origins, *.domain subdomain wildcards, and * for all. E.g., https://*.example.com,https://specific.com. When unset, if the service is bound to 0.0.0.0 (--host 0.0.0.0), all origins are automatically allowed
SERVER__HOST	Listen address for --serve mode (default: 127.0.0.1)
SERVER__PORT	Listen port for --serve mode; set to 0 for a kernel-assigned port — the variable is updated to the actual listening port once the server is bound

WeCom Integration

Environment Variable	Description
CODEBUDDY_GATEWAY_WECHAT_KF_TOKEN	WeCom Customer Service Token
CODEBUDDY_GATEWAY_WECHAT_KF_ENCODING_AES_KEY	WeCom Customer Service Encryption Key
CODEBUDDY_GATEWAY_WECHAT_KF_CORP_ID	WeCom Customer Service Corp ID
CODEBUDDY_GATEWAY_WECHAT_KF_CORP_SECRET	WeCom Customer Service Corp Secret
CODEBUDDY_GATEWAY_WECHAT_KF_ACCOUNT_NAME	WeCom Customer Service Account Name
CODEBUDDY_GATEWAY_WECOM_TOKEN	WeCom Token
CODEBUDDY_GATEWAY_WECOM_ENCODING_AES_KEY	WeCom Encryption Key
CODEBUDDY_GATEWAY_WECOM_CORP_ID	WeCom Corp ID
CODEBUDDY_GATEWAY_WECOM_CORP_SECRET	WeCom Corp Secret
CODEBUDDY_GATEWAY_WECOM_AGENT_ID	WeCom Agent ID

Channel Auto-Connect

Environment Variable	Description
CODEBUDDY_CHANNEL_AUTO_CONNECT	Set to 1 or true to automatically connect all configured channels (WeCom + WeChat) on startup
CODEBUDDY_WECOM_AUTO_CONNECT	Set to 1 or true to automatically connect all configured WeCom bot instances on startup
CODEBUDDY_WECHAT_AUTO_CONNECT	Set to 1 or true to automatically connect all configured WeChat bot instances on startup
CODEBUDDY_WECOM_BOT_ID	WeCom AI Assistant Bot ID. When set, a default instance is automatically created and appears in the /remote-control list
CODEBUDDY_WECOM_BOT_SECRET	WeCom AI Assistant Secret. Must be used together with CODEBUDDY_WECOM_BOT_ID
CODEBUDDY_WECOM_STREAMING_DEFAULT	Global default streaming toggle for WeCom bots (1/0 or true/false); bots without an explicit setting inherit this value
CODEBUDDY_WECOM_CARDS_DEFAULT	Global default permission/suggestion card toggle for WeCom bots (1/0 or true/false); bots without an explicit setting inherit this value

Tip: CODEBUDDY_CHANNEL_AUTO_CONNECT is the master toggle, while CODEBUDDY_WECOM_AUTO_CONNECT and CODEBUDDY_WECHAT_AUTO_CONNECT are per-type toggles. Any one of the three being set will take effect. Works in all modes (interactive, --serve, daemon).

Debugging and Diagnostics

Environment Variable	Description
CODEBUDDY_DEBUG	Set to 1/true/yes/on to enable debug mode (equivalent to --debug)
CODEBUDDY_DEBUG_SDK	Set to 1/true/yes/on to enable SDK debugging
CODEBUDDY_DEBUG_REQUEST	Set to 1 to enable request debugging
CODEBUDDY_STARTUP_PROFILE	Set to 1 to save Markdown and JSON startup profiling reports automatically. See Startup Profiling
CODEBUDDY_CODE_HEAP_SNAPSHOT_NEAR_LIMIT_PCT	OOM forensics (off by default). When enabled, if the process heap crosses the V8 heap limit high-water mark, a heap snapshot is automatically written to ~/.codebuddy/diagnostics/<date>/oom-nearlimit-<pid>-<ts>.heapsnapshot (written only once per process). Values: on/true/1 for the default 85% threshold; 0.9 or 90 for a custom threshold; unset / 0 / off / false to disable. ⚠️ Snapshot files are ~1.5× the heapUsed at that time (multi-GB heaps produce multi-GB files); only enable when troubleshooting OOM. See Troubleshooting · OOM
CBC_HEAP_SNAPSHOT_ON_WORKFLOW_END	Set to 1 to write a heap snapshot after each workflow (e.g., ultracode) completes, saved to ~/.codebuddy/diagnostics/<date>/. Off by default (consumes disk); only enable when troubleshooting workflow memory leaks

E2E Testing (Record/Replay)

Record/replay functionality for model responses in E2E tests. In record mode, real model responses are captured; in replay mode, recorded files are used in place of real API calls.

Environment Variable	Description
CODEBUDDY_RECORD_DIR	Record mode: directory where recording files are saved. When set, model responses are saved to recording.jsonl in this directory
CODEBUDDY_REPLAY_DIR	Replay mode: directory from which recording files are read. When set, responses are replayed from recording.jsonl without requiring a real API
CODEBUDDY_REPLAY_SPEED	Replay speed multiplier. 0 means no delay (instant return), 1 means replay at original timing intervals (default: 1)
CODEBUDDY_REPLAY_STRICT	Set to 1 to enable strict mode: throws an error when recordings are exhausted instead of falling through to the real API

Note: CODEBUDDY_RECORD_DIR and CODEBUDDY_REPLAY_DIR are mutually exclusive and cannot be set at the same time.

Miscellaneous

Environment Variable	Description
SLASH_COMMAND_TOOL_CHAR_BUDGET	Maximum character count for slash command tool metadata (default: 15000)
CODEBUDDY_CODE_API_KEY_HELPER_TTL_MS	Interval for refreshing credentials (milliseconds) (default: 300000)

Usage Examples

Basic Authentication Configuration

# Set API key
export CODEBUDDY_API_KEY="your-api-key"

# Set proxy server
export HTTP_PROXY="http://proxy.example.com:8080"
export HTTPS_PROXY="https://proxy.example.com:8080"

# Set proxy bypass list
export NO_PROXY="localhost,127.0.0.1,.internal.example.com"

# Set custom headers (multiple headers separated by \n)
export CODEBUDDY_CUSTOM_HEADERS="X-Custom-Header: value1\nX-Another-Header: value2"

# Start CodeBuddy
codebuddy

Using Third-Party Model Services

# Use a custom API endpoint
export CODEBUDDY_API_KEY="your-api-key"
export CODEBUDDY_BASE_URL="https://api.example.com/v1"
codebuddy --model your-model-name

Connecting to DeepSeek Example

To connect to any third-party model service compatible with the Anthropic protocol (such as DeepSeek), you only need to configure the Base URL, API Key, and model variables — no additional models.json modifications are required:

# Endpoint and key
export CODEBUDDY_BASE_URL="https://api.deepseek.com"
export CODEBUDDY_API_KEY="<your-deepseek-api-key>"

# Default model for the main Agent
export CODEBUDDY_MODEL="deepseek-v4-pro"

# Large model used for complex reasoning
export CODEBUDDY_BIG_SLOW_MODEL="deepseek-v4-pro"

# Small model for background/lightweight tasks
export CODEBUDDY_SMALL_FAST_MODEL="deepseek-v4-flash"

# Ops-level blanket override for all sub-agents.
# When unset, per-invocation, per-sub-agent settings, and product built-in orchestration are used.
export CODEBUDDY_CODE_SUBAGENT_MODEL="deepseek-v4-flash"

# Optionally specify the main model explicitly via --model at startup
codebuddy --model deepseek-v4-pro

Tip: The variables above can also be written into the env field of settings.json so they automatically apply to each session, making team-wide configuration easier.

China Edition Configuration

# Set China edition environment identifier
export CODEBUDDY_INTERNET_ENVIRONMENT=internal

# Set API key
export CODEBUDDY_API_KEY="your-api-key"

# Start CodeBuddy
codebuddy

Enabling Advanced Features

# Enable auto memory
export CODEBUDDY_DISABLE_AUTO_MEMORY="0"

# Enable extended thinking
export MAX_THINKING_TOKENS="10000"

# Run in non-interactive mode (-y may still prompt for HIGH/CRITICAL actions)
codebuddy -p -y "your query"

# Sandbox full pass (high risk: isolated containers / VMs without internet access only)
export CODEBUDDY_IS_SANDBOX=1
codebuddy -p -y "your query"

Debugging and Profiling

# Enable debug mode
export CODEBUDDY_DEBUG="1"

# Enable startup profiling
export CODEBUDDY_STARTUP_PROFILE="1"

# Start CodeBuddy
codebuddy

Configuring in settings.json

Environment variables can also be set in the env field of settings.json:

Exception: CODEBUDDY_IS_SANDBOX is not injected from here. It must be set in the launching process environment, for example, export CODEBUDDY_IS_SANDBOX=1 && codebuddy -y. See Sandbox full pass (high risk).

{
  "env": {
    "CODEBUDDY_API_KEY": "your-api-key",
    "HTTPS_PROXY": "https://proxy.example.com:8080",
    "MAX_THINKING_TOKENS": "10000",
    "CODEBUDDY_DISABLE_AUTO_MEMORY": "0"
  }
}

Tool Output Externalization Mechanism

When tool execution produces output exceeding the threshold, CodeBuddy Code automatically saves the full output to disk and sends only truncated content with a file path pointer to the model, which can read the full content on demand.

Data Flow

Shell output
  ├─→ OutputSpiller (full output streamed to disk)
  └─→ TruncateBuffer (head + tail retained in memory, ~30KB)
                          ↓
                  Truncation detected → generate placeholder (~2KB preview + file path; the preview is taken from the start of the command output, with the Exit Code shown first if the command failed)
                          ↓
                  Model receives placeholder, can read full file via Read tool on demand

Data Size at Each Stage (using 1.3MB output as example)

Stage	Content	Size
Disk file (OutputSpiller)	Full raw output	1,355,099 bytes
Memory buffer (TruncateBuffer)	head 6KB + tail 24KB	~30KB
Sent to model (placeholder)	File path + preview	~2KB

Storage Directory

Tool output files are stored in the project data directory:

~/.codebuddy/projects/{projectDir}/
  └── {sessionId}/
      ├── tool-results/                          ← Main session tool results
      │   ├── {callId}.txt
      │   └── ...
      └── subagents/                             ← Sub-agent data
          ├── agent-{agentId}.jsonl              ← Sub-agent conversation history
          └── agent-{agentId}/
              └── tool-results/                  ← Sub-agent tool results
                  ├── {callId}.txt
                  └── ...

Related Environment Variables

Environment Variable	Scope	Default
BASH_MAX_OUTPUT_LENGTH	Bash tool memory retention, triggers disk externalization when exceeded	30000
CODEBUDDY_TOOL_RESULT_THRESHOLD_KB	Session-level externalization threshold for non-bash tools (e.g., MCP)	50

See Also

• Settings - Configure environment variables and other settings in settings.json
• CLI Reference - Complete list of command-line arguments, including -y and CODEBUDDY_IS_SANDBOX
• Permission Modes - bypassPermissions and sandbox full pass
• MCP Setup - MCP server configuration
• Sub-Agents - Sub-agent storage directory documentation