starred/openclaude
1
0
Fork 0
mirror of https://github.com/Gitlawb/openclaude.git synced 2026-08-24 02:34:15 -05:00
Code Issues Packages Projects Releases Wiki Activity
Files
4e56fd59212258694c82fcd654e66883c33cd937
openclaude/.env.example
T
CalGitHubClaude Opus 4.8
 822eff39d1 fix(copilot): limit sub-agent concurrency to reduce Premium Request usage (#678) (#1534) 
* fix(copilot): limit sub-agent concurrency to reduce Premium Request usage (#678)

* fix(copilot): enforce sub-agent concurrency cap at Agent invocation level

AgentTool.isConcurrencySafe() now returns false when
getCopilotMaxConcurrentSubagents() > 0, preventing the tool scheduler
from batching multiple Agent calls together. This ensures at most one
sub-agent runs at a time when the cap is active.

Previously, AgentTool was always concurrency-safe, allowing the
scheduler's runToolsConcurrently to batch multiple Agent calls from
a single assistant message — bypassing the documented MAX_SUBAGENTS cap.

Add comprehensive copilotOptimization unit tests.

* fix(copilot): enforce cap for any positive value and honor OPTIMIZATION_DISABLED

- shouldForceSyncSubagentsInCopilotMode: gate on > 0 instead of === 1
  so any configured cap (2, 3, ..., 10) forces serial execution
- isConcurrencySafe: early-return true when OPTIMIZATION_DISABLED is set
- Update log message to reflect any-cap behavior

* fix(copilot): align scheduler with launch path, fix mock leak

- isConcurrencySafe now uses shouldForceSyncSubagentsInCopilotMode()
  instead of raw cap check, matching the launch path at line 447
- Add afterAll(mock.restore) to copilotOptimization.test.ts to
  prevent providers.js mock leaking to AgentTool routing tests

* fix(copilot): clarify MAX_SUBAGENTS semantics and fix remediation hint log

- Document that only MAX_SUBAGENTS=0 and =1 are enforced; values 2-10
  have no runtime effect.
- Fix the log remediation hint to depend on the actual cause: MAX=0
  suppresses sub-agents entirely (not just forces sync), FORCE_SYNC=1
  requires unsetting the flag, and MAX>=1 requires ALLOW_SUBAGENTS=1
  to restore parallel execution.

* docs(env): document GITHUB_COPILOT_* tuning vars in .env.example

The Copilot Premium Request optimization introduces four env vars
(GITHUB_COPILOT_MAX_SUBAGENTS, GITHUB_COPILOT_ALLOW_SUBAGENTS,
GITHUB_COPILOT_FORCE_SYNC_SUBAGENTS, GITHUB_COPILOT_OPTIMIZATION_DISABLED)
that change how sub-agents run for CLAUDE_CODE_USE_GITHUB=1 sessions.
Previously these were documented only in source comments, which made
them undiscoverable for users affected by the new default.

Add them to the GitHub Models section (Option 4) of .env.example with
descriptions of each var's effect and default value, addressing the
reviewer ask to put the new default behavior in user-facing docs.

* fix(copilot): telemetry reflects final async mode; docs in README

Address outstanding review gaps for #1534:

1. Telemetry is_async/isAsync now uses the final shouldRunAsync value
   computed once at the top of the function (was duplicating the partial
   expression, omitting isCoordinator/forceAsync/assistantForceAsync/
   proactiveModule signals that contribute to the launch decision).
2. The shouldSuppressSubagentsInCopilotMode() throw now happens before
   the event log (so a suppressed-agent error isn't followed by a
   misleading 'is_async: true' event).
3. isCoordinator, forceAsync, assistantForceAsync are now computed once
   alongside forceSyncCopilot instead of being declared inline later.
4. README: add GitHub Copilot sub-agent optimization subsection under
   Provider Notes, with the env var table mirroring the .env.example
   entry (default behavior, cap semantics, all-opt-out).

The doc comment in copilotOptimization.ts L16-29 already explains
MAX_SUBAGENTS=0/1 enforcement; the test at L186-191 is consistent with
the current implementation (positive cap = synchronous).

Skipped: getEffectiveConcurrencyCap() in toolOrchestration.ts (the
function no longer exists in the current code; the bot's review was
based on an earlier version).

* fix(copilot): skip <BackgroundHint /> when forced sync

When forceSyncCopilot is true the task can no longer be backgrounded
(registerAgentForeground is skipped at L918), but the background hint
UI was still rendered once the progress threshold elapsed. That
advertises a non-existent affordance on every long-running Copilot
sub-agent, which is confusing for users.

Gate the hint on the same !forceSyncCopilot condition as the
foreground registration. Address the CodeRabbit P2 on round 6.

* test(copilot): use spyOn instead of mock.module to avoid partial-mock leak

CodeRabbit P2 review on round 7 found the copilotOptimization test
registered mock.module('./model/providers.js', () => ({ only 4 exports }))
which removed all other exports of providers.ts. Downstream tests in the
same CI process (e.g. withRetry, domainCheck, apiPreconnect, agent) that
import symbols like isFirstPartyAnthropicBaseUrl would then fail with
'Export named ... not found in module' errors.

Switch to spyOn() on the real providers module's getAPIProvider. The
real module's other exports remain available, and the spy is torn
down via mockRestore() in afterEach. Also drop the cache-busting
dynamic-import pattern: the spy persists across the static import, so
the test no longer needs a fresh module per test.

Also fix README P3: the earlier PowerShell heredoc introduced a TAB
(0x09) and Form Feed (0x0C) in place of 't' and 'f' in the new Copilot
section, rendering 'tengu_agent_tool_selected' as 'engu_...' and 'false'
as 'alse'. Rewrite the line with proper 't' and 'f' characters and add
backticks for code formatting (was unformatted plain text).

Skipped: P2 scheduler-boundary coverage (CodeRabbit round 6 item).
That requires driving multiple Agent tool-use blocks through the
scheduler in AgentTool/StreamingToolExecutor, which is a larger change
than the current PR's scope.

* test(copilot): add FORCE_SYNC overrides ALLOW_SUBAGENTS precedence test

CodeRabbit round 9: add a test that pins the precedence between
GITHUB_COPILOT_FORCE_SYNC_SUBAGENTS=1 and GITHUB_COPILOT_ALLOW_SUBAGENTS=1.
The user explicitly asking for synchronous execution must win over the
softer "I'm fine with the cap" opt-out. A future reordering of the
checks in shouldForceSyncSubagentsInCopilotMode() would silently allow
parallel Copilot sub-agent launches when the user asked for sync; this
test locks the precedence.

Verified locally: 23/23 pass (was 22/22 before adding this test).

* fix(copilot): address jatmn round 11 P2/P3 and add scheduler-boundary coverage

This commit addresses the latest human + bot review feedback on #1534
across three findings:

1. **P3: Update GitHub Copilot comment in github.ts to use billing-cycle
   wording.** The previous comment hard-coded "per month (300 for
   Copilot Free)" — a calendar quota the runtime doesn't own. Mirror
   the wording from src/utils/copilotOptimization.ts: "per billing
   cycle, with the exact quota set by the user's Copilot plan." Same
   docstring shape across both files now.

2. **P2: Add afterEach cleanup to copilotOptimization.test.ts.**
   Captured the GITHUB_COPILOT_* env vars at module top-level and
   restore them in afterEach. Previously only beforeEach deleted them,
   so the precedence test (which sets FORCE_SYNC=1 + ALLOW_SUBAGENTS=1)
   left those values in process.env after the file completed. Verified
   by `bun test src/utils/copilotOptimization.test.ts ../copilot-env-probe.test.ts`:
   before the fix, the probe test sees FORCE_SYNC=1 leaked. After the
   fix, the probe sees the original env. This is the round 11 P2
   review item from jatmn.

3. **P2: Add scheduler-boundary regression test.** New file
   src/tools/AgentTool/AgentTool.copilotScheduling.test.ts pins the
   launch↔scheduler alignment by calling `AgentTool.isConcurrencySafe()`
   directly under each Copilot flag combination. Seven matrix rows:
   OPTIMIZATION_DISABLED=1, default cap=1, cap=2, ALLOW_SUBAGENTS=1,
   FORCE_SYNC=1 alone, FORCE_SYNC=1 + ALLOW_SUBAGENTS=1 (precedence),
   cap=0 (suppressed). A future reorder of the helpers in
   copilotOptimization.ts that breaks the precedence would fail
   FORCE_SYNC + ALLOW_SUBAGENTS, locking the launch/scheduling
   alignment. This is the round 9 / round 11 P2 review item from
   CodeRabbit + jatmn that has been deferred across multiple rounds.

   The test uses spyOn on providers.getAPIProvider to control the
   provider state, then imports AgentTool via cache-busting
   (?copilotScheduling=... query string) — the same pattern as
   AgentTool.routing.test.ts. Per-test timeout of 30s absorbs the
   ~16s one-time AgentTool module load (subsequent tests are sub-1ms
   because the module is cached after the first beforeAll import).

All three changes are verified locally:
  - `bun test src/utils/copilotOptimization.test.ts` — 23/23 pass
  - `bun test src/tools/AgentTool/AgentTool.copilotScheduling.test.ts` — 7/7 pass
  - `bun test --max-concurrency=1` of both files together — 30/30 pass

* test(copilot): move per-test timeout to 3rd arg (bun:test API)

* fix(copilot): let FORCE_SYNC override MAX_SUBAGENTS=0 + add scheduler-boundary test

Two review findings:

1. FORCE_SYNC vs suppression: shouldSuppressSubagentsInCopilotMode()
   returned true for MAX_SUBAGENTS=0 before FORCE_SYNC was consulted, so
   GITHUB_COPILOT_MAX_SUBAGENTS=0 + GITHUB_COPILOT_FORCE_SYNC_SUBAGENTS=1
   threw "Sub-agents are disabled" instead of running them synchronously,
   contradicting the documented behavior. FORCE_SYNC (like ALLOW_SUBAGENTS)
   now bypasses the =0 suppression; docs clarified accordingly.

2. Scheduler-boundary coverage: the existing tests only called
   isConcurrencySafe() directly. Added a regression that drives multiple
   Agent tool-use blocks through the real batching path
   (partitionToolCalls, now exposed via _test): forced-sync splits them
   into serial single-block batches, ALLOW_SUBAGENTS coalesces them into
   one concurrent batch. Catches a future divergence between launch and
   scheduling policy for multiple Agent blocks in one assistant message.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
2026-06-14 10:15:34 +08:00

498 lines
21 KiB
Bash
Raw Blame History

# =============================================================================
# OpenClaude Environment Configuration
# =============================================================================
# Copy this file to .env and fill in your values:
# cp .env.example .env
#
# Only set the variables for the provider you want to use.
# All other sections can be left commented out.
# =============================================================================
# =============================================================================
# SYSTEM-WIDE SETUP (OPTIONAL)
# =============================================================================
# Instead of using a .env file per project, you can set these variables
# system-wide so OpenClaude works from any directory on your machine.
#
# STEP 1: Pick your provider variables from the list below.
# STEP 2: Set them using the method for your OS (see further down).
#
# ── Provider variables ───────────────────────────────────────────────
#
# Option 1 — Anthropic:
# ANTHROPIC_API_KEY=sk-ant-your-key-here
# ANTHROPIC_MODEL=claude-sonnet-4-5 (optional)
# ANTHROPIC_BASE_URL=https://api.anthropic.com (optional)
#
# Option 2 — OpenAI:
# CLAUDE_CODE_USE_OPENAI=1
# OPENAI_API_KEY=sk-your-key-here
# OPENAI_MODEL=gpt-4o
# OPENAI_BASE_URL=https://api.openai.com/v1 (optional)
#
# Option 11 — NEAR AI (unified gateway: Claude, GPT, Gemini + TEE models):
# NEARAI_API_KEY=your_key_here
# OPENAI_MODEL=anthropic/claude-sonnet-4-6 (optional, default)
#
# Option 3 — Google Gemini:
# CLAUDE_CODE_USE_GEMINI=1
# GEMINI_API_KEY=your-gemini-key-here
# GEMINI_MODEL=gemini-2.0-flash
# GEMINI_BASE_URL=https://generativelanguage.googleapis.com (optional)
#
# Option 4 — GitHub Models:
# CLAUDE_CODE_USE_GITHUB=1
# GITHUB_TOKEN=ghp_your-token-here
#
# -- Copilot Premium Request optimization (default ON for sub-agents) --
# By default, when using GitHub Copilot, OpenClaude serializes sub-agent
# execution to reduce Premium Request consumption. Set these to tune:
#
# GITHUB_COPILOT_MAX_SUBAGENTS=1 Max concurrent sub-agents.
# 0 = suppress sub-agents, 1 = force
# sync, 2-10 = parsed/clamped.
# Default: 1.
# GITHUB_COPILOT_ALLOW_SUBAGENTS= Set to 1 to re-enable parallel
# background sub-agents
# (overrides the cap).
# GITHUB_COPILOT_FORCE_SYNC_SUBAGENTS= Set to 1 to force sync
# execution regardless of cap.
# GITHUB_COPILOT_OPTIMIZATION_DISABLED= Set to 1 to disable all
# optimization (sub-agents run
# as before this feature).
#
# Option 5 — Ollama (local):
# CLAUDE_CODE_USE_OPENAI=1
# OPENAI_BASE_URL=http://localhost:11434/v1
# OPENAI_API_KEY=ollama
# OPENAI_MODEL=llama3.2
#
# Option 6 — LM Studio (local):
# CLAUDE_CODE_USE_OPENAI=1
# OPENAI_BASE_URL=http://localhost:1234/v1
# OPENAI_MODEL=your-model-id-here
# OPENAI_API_KEY=lmstudio (optional)
#
# Option 7 — AWS Bedrock (may also need: aws configure):
# CLAUDE_CODE_USE_BEDROCK=1
# AWS_REGION=us-east-1
# AWS_DEFAULT_REGION=us-east-1
# AWS_BEARER_TOKEN_BEDROCK=your-bearer-token-here
# ANTHROPIC_BEDROCK_BASE_URL=https://bedrock-runtime.us-east-1.amazonaws.com
#
# Option 8 — Google Vertex AI:
# CLAUDE_CODE_USE_VERTEX=1
# ANTHROPIC_VERTEX_PROJECT_ID=your-gcp-project-id
# CLOUD_ML_REGION=us-east5
# GOOGLE_CLOUD_PROJECT=your-gcp-project-id
#
# ── How to set variables on each OS ──────────────────────────────────
#
# macOS (zsh):
# 1. Open: nano ~/.zshrc
# 2. Add each variable as: export VAR_NAME=value
# 3. Save and reload: source ~/.zshrc
#
# Linux (bash):
# 1. Open: nano ~/.bashrc
# 2. Add each variable as: export VAR_NAME=value
# 3. Save and reload: source ~/.bashrc
#
# Windows (PowerShell):
# Run for each variable:
# [System.Environment]::SetEnvironmentVariable('VAR_NAME', 'value', 'User')
# Then restart your terminal.
#
# Windows (Command Prompt):
# Run for each variable:
# setx VAR_NAME value
# Then restart your terminal.
#
# Windows (GUI):
# Settings > System > About > Advanced System Settings >
# Environment Variables > under "User variables" click New,
# then add each variable.
#
# ── Important notes ──────────────────────────────────────────────────
#
# LOCAL SERVERS: If using LM Studio or Ollama, the server MUST be
# running with a model loaded before you launch OpenClaude —
# otherwise you'll get connection errors.
#
# SWITCHING PROVIDERS: To temporarily switch, unset the relevant
# variables in your current terminal session:
#
# macOS / Linux:
# unset VAR_NAME
# # e.g.: unset CLAUDE_CODE_USE_OPENAI OPENAI_BASE_URL OPENAI_MODEL
#
# Windows (PowerShell — current session only):
# Remove-Item Env:VAR_NAME
#
# To permanently remove a variable on Windows:
# [System.Environment]::SetEnvironmentVariable('VAR_NAME', $null, 'User')
#
# LOAD ORDER:
# Shell and system environment variables are inherited by the process.
# Project .env files are only used if your launcher or shell loads them
# before starting OpenClaude.
# COMPATIBILITY:
# System-wide variables work regardless of how you run OpenClaude:
# npx, global npm install, bun run, or node directly. Any process
# launched from your terminal inherits your shell's environment.
#
# REMINDER: Make sure .env is in your .gitignore to avoid committing secrets.
# =============================================================================
# =============================================================================
# PROVIDER SELECTION — uncomment ONE block below
# =============================================================================
# -----------------------------------------------------------------------------
# Option 1: Anthropic (default — no provider flag needed)
# -----------------------------------------------------------------------------
ANTHROPIC_API_KEY=sk-ant-your-key-here
# Override the default model (optional)
# ANTHROPIC_MODEL=claude-sonnet-4-5
# Use a custom Anthropic-compatible endpoint (optional)
# ANTHROPIC_BASE_URL=https://api.anthropic.com
# -----------------------------------------------------------------------------
# Option 2: OpenAI
# -----------------------------------------------------------------------------
# CLAUDE_CODE_USE_OPENAI=1
# OPENAI_API_KEY=sk-your-key-here
# OPENAI_MODEL=gpt-4o
# For DeepSeek, set:
# OPENAI_BASE_URL=https://api.deepseek.com/v1
# OPENAI_MODEL=deepseek-v4-flash
# Optional: OPENAI_MODEL=deepseek-v4-pro
# Legacy aliases also work: deepseek-chat and deepseek-reasoner
# For Z.AI GLM Coding Plan, set:
# OPENAI_BASE_URL=https://api.z.ai/api/coding/paas/v4
# OPENAI_MODEL=GLM-5.1
# Optional: OPENAI_MODEL=GLM-5-Turbo, GLM-4.7, or GLM-4.5-Air
# For Hicap, use the OpenAI-compatible route flag above and set:
# HICAP_API_KEY=your-hicap-key-here
# OPENAI_BASE_URL=https://api.hicap.ai/v1
# OPENAI_MODEL=claude-opus-4.7
# Use a custom OpenAI-compatible endpoint (optional — defaults to api.openai.com)
# OPENAI_BASE_URL=https://api.openai.com/v1
# Choose the OpenAI-compatible API surface (optional — defaults to chat_completions)
# Supported: chat_completions, responses
# OPENAI_API_FORMAT=chat_completions
# Choose a custom auth header for OpenAI-compatible providers (optional).
# Authorization defaults to Bearer; custom headers default to the raw API key.
# Set OPENAI_AUTH_HEADER_VALUE when the header value differs from OPENAI_API_KEY.
# OPENAI_AUTH_HEADER=api-key
# OPENAI_AUTH_SCHEME=raw
# OPENAI_AUTH_HEADER_VALUE=your-header-value-here
# Fallback context window size (tokens) when the model is not found in
# integration model metadata (default: 128000). Increase this for models with larger
# context windows (e.g. 200000 for Claude-sized contexts).
# CLAUDE_CODE_OPENAI_FALLBACK_CONTEXT_WINDOW=128000
# Per-model context window overrides as a JSON object.
# Takes precedence over integration model metadata, so you can register new or
# custom models without patching source.
# Example: CLAUDE_CODE_OPENAI_CONTEXT_WINDOWS={"my-corp/llm-v3":262144,"gpt-4o-mini":128000}
# CLAUDE_CODE_OPENAI_CONTEXT_WINDOWS=
# Per-model maximum output token overrides as a JSON object.
# Use this alongside CLAUDE_CODE_OPENAI_CONTEXT_WINDOWS when your model
# supports a different output limit than what integration metadata specifies.
# Example: CLAUDE_CODE_OPENAI_MAX_OUTPUT_TOKENS={"my-corp/llm-v3":8192}
# CLAUDE_CODE_OPENAI_MAX_OUTPUT_TOKENS=
# -----------------------------------------------------------------------------
# Option 3: Google Gemini
# -----------------------------------------------------------------------------
# CLAUDE_CODE_USE_GEMINI=1
# GEMINI_API_KEY=your-gemini-key-here
# GEMINI_MODEL=gemini-2.0-flash
# Use a custom Gemini endpoint (optional)
# GEMINI_BASE_URL=https://generativelanguage.googleapis.com/v1beta/openai
# -----------------------------------------------------------------------------
# Option 4: GitHub Models
# -----------------------------------------------------------------------------
# CLAUDE_CODE_USE_GITHUB=1
# GITHUB_TOKEN=ghp_your-token-here
# -----------------------------------------------------------------------------
# Option 5: Ollama (local models)
# -----------------------------------------------------------------------------
# CLAUDE_CODE_USE_OPENAI=1
# OPENAI_BASE_URL=http://localhost:11434/v1
# OPENAI_API_KEY=ollama
# OPENAI_MODEL=llama3.2
# -----------------------------------------------------------------------------
# Option 6: LM Studio (local models)
# -----------------------------------------------------------------------------
# LM Studio exposes an OpenAI-compatible API, so we use the OpenAI provider.
# Make sure LM Studio is running with the Developer server enabled
# (Developer tab > toggle server ON).
#
# Steps:
# 1. Download and install LM Studio from https://lmstudio.ai
# 2. Search for and download a model (e.g. any coding or instruct model)
# 3. Load the model and start the Developer server
# 4. Set OPENAI_MODEL to the model ID shown in LM Studio's Developer tab
#
# The default server URL is http://localhost:1234 — change the port below
# if you've configured a different one in LM Studio.
#
# OPENAI_API_KEY is optional — LM Studio runs locally and ignores it.
# Some clients require a non-empty value; if you get auth errors, set it
# to any dummy value (e.g. "lmstudio").
#
# CLAUDE_CODE_USE_OPENAI=1
# OPENAI_BASE_URL=http://localhost:1234/v1
# OPENAI_MODEL=your-model-id-here
# -----------------------------------------------------------------------------
# Option 7: AWS Bedrock
# -----------------------------------------------------------------------------
# You may also need AWS CLI credentials configured (run: aws configure)
# or have AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY set in your
# environment in addition to the variables below.
#
# CLAUDE_CODE_USE_BEDROCK=1
# AWS_REGION=us-east-1
# AWS_DEFAULT_REGION=us-east-1
# AWS_BEARER_TOKEN_BEDROCK=your-bearer-token-here
# ANTHROPIC_BEDROCK_BASE_URL=https://bedrock-runtime.us-east-1.amazonaws.com
# -----------------------------------------------------------------------------
# Option 8: Google Vertex AI
# -----------------------------------------------------------------------------
# CLAUDE_CODE_USE_VERTEX=1
# ANTHROPIC_VERTEX_PROJECT_ID=your-gcp-project-id
# CLOUD_ML_REGION=us-east5
# GOOGLE_CLOUD_PROJECT=your-gcp-project-id
# -----------------------------------------------------------------------------
# Option 9: NVIDIA NIM
# -----------------------------------------------------------------------------
# NVIDIA NIM provides hosted inference endpoints for NVIDIA models.
# Get your API key from https://build.nvidia.com/
#
# CLAUDE_CODE_USE_OPENAI=1
# NVIDIA_API_KEY=nvapi-your-key-here
# OPENAI_BASE_URL=https://integrate.api.nvidia.com/v1
# OPENAI_MODEL=nvidia/llama-3.1-nemotron-70b-instruct
# -----------------------------------------------------------------------------
# Option 10: MiniMax
# -----------------------------------------------------------------------------
# MiniMax API provides text generation models.
# Get your API key from https://platform.minimax.io/
#
# MINIMAX_API_KEY=your-minimax-key-here
# ANTHROPIC_BASE_URL=https://api.minimax.io/anthropic
# ANTHROPIC_MODEL=MiniMax-M2.7
# -----------------------------------------------------------------------------
# Option 11: NEAR AI
# -----------------------------------------------------------------------------
# NEAR AI is a unified OpenAI-compatible gateway to Claude, GPT, Gemini,
# and TEE-hosted open models — all under one API key.
# Get your API key from https://cloud.near.ai/dashboard/organizations
#
# NEARAI_API_KEY=your-nearai-key-here
# OPENAI_BASE_URL=https://cloud-api.near.ai/v1 (optional, default)
# OPENAI_MODEL=anthropic/claude-sonnet-4-6 (optional, default)
#
# For direct TEE completions (lower latency + verifiable privacy):
# OPENAI_BASE_URL=https://qwen35-122b.completions.near.ai/v1
# -----------------------------------------------------------------------------
# Option 12: Fireworks AI
# -----------------------------------------------------------------------------
# Fireworks AI provides a fully OpenAI-compatible endpoint.
# Get your API key from https://fireworks.ai/
# Model IDs use the full path format: accounts/fireworks/models/<model-name>
#
# CLAUDE_CODE_USE_OPENAI=1
# FIREWORKS_API_KEY=fw_your_key_here
# OPENAI_BASE_URL=https://api.fireworks.ai/inference/v1
# OPENAI_MODEL=accounts/fireworks/models/llama-v3p1-70b-instruct
# =============================================================================
# OPTIONAL TUNING
# =============================================================================
# Max number of API retries on failure (default: 10, cap: 100)
# Set to 0 to disable retries after the initial request
# Deprecated fallback when OPENCLAUDE_MAX_RETRIES is unset: CLAUDE_CODE_MAX_RETRIES
# OPENCLAUDE_MAX_RETRIES=10
# Base retry delay in milliseconds when the API does not send Retry-After
# Uses exponential backoff from this value with jitter (default: 500, cap: 60000)
# OPENCLAUDE_RETRY_DELAY_MS=500
# Enable persistent retry mode for unattended/CI sessions
# Retries 429/529 indefinitely with smart backoff
# CLAUDE_CODE_UNATTENDED_RETRY=1
# Enable extended key reporting (Kitty keyboard protocol)
# Useful for iTerm2, WezTerm, Ghostty if modifier keys feel off
# OPENCLAUDE_ENABLE_EXTENDED_KEYS=1
# Disable "Co-authored-by" line in git commits made by OpenClaude
# OPENCLAUDE_DISABLE_CO_AUTHORED_BY=1
# Disable strict tool schema normalization for non-Gemini providers
# Useful when MCP tools with complex optional params (e.g. list[dict])
# trigger "Extra required key ... supplied" errors from OpenAI-compatible endpoints
# OPENCLAUDE_DISABLE_STRICT_TOOLS=1
# Disable hidden <system-reminder> messages injected into tool output
# Suppresses the file-read cyber-risk reminder and the todo/task tool nudges
# Useful for users who want full transparency over what the model sees
# OPENCLAUDE_DISABLE_TOOL_REMINDERS=1
# Log structured per-request token usage (including cache metrics) to stderr.
# Useful for auditing cache hit rate / debugging cost spikes outside the REPL.
# Any truthy value enables it ("verbose", "1", "true").
#
# Complements (does NOT replace) CLAUDE_CODE_ENABLE_TOKEN_USAGE_ATTACHMENT —
# they serve different audiences:
# - OPENCLAUDE_LOG_TOKEN_USAGE is user-facing: one JSON line per API
# request on stderr, intended for humans inspecting cost/caching.
# - CLAUDE_CODE_ENABLE_TOKEN_USAGE_ATTACHMENT is model-facing: injects
# a context-usage attachment INTO the prompt so the model can reason
# about its own remaining context. Does not touch stderr.
# Turn on whichever audience you're debugging; both can run together.
# OPENCLAUDE_LOG_TOKEN_USAGE=verbose
# Custom timeout for API requests in milliseconds (default: varies)
# API_TIMEOUT_MS=60000
# Enable debug logging
# CLAUDE_DEBUG=1
# =============================================================================
# WEB SEARCH (OPTIONAL)
# =============================================================================
# OpenClaude includes a web search tool. By default it uses DuckDuckGo (free)
# or the provider's native search (Anthropic firstParty / vertex).
#
# Set one API key below to enable a provider. That's it.
# ── Provider API keys — set ONE of these ────────────────────────────
# Tavily (AI-optimized search, recommended)
# TAVILY_API_KEY=tvly-your-key-here
# Exa (neural/semantic search)
# EXA_API_KEY=your-exa-key-here
# You.com (RAG-ready snippets)
# YOU_API_KEY=your-you-key-here
# Jina (s.jina.ai endpoint)
# JINA_API_KEY=your-jina-key-here
# Brave (independent web index, generous free tier)
# BRAVE_API_KEY=your-brave-key-here
# Bing Web Search
# BING_API_KEY=your-bing-key-here
# Mojeek (privacy-focused)
# MOJEEK_API_KEY=your-mojeek-key-here
# Linkup
# LINKUP_API_KEY=your-linkup-key-here
# Firecrawl (premium, uses @mendable/firecrawl-js)
# FIRECRAWL_API_KEY=fc-your-key-here
# Self-hosted Firecrawl endpoint (optional — omit to use cloud API)
# FIRECRAWL_API_URL=https://your-firecrawl-instance.com
# ── Provider selection mode ─────────────────────────────────────────
#
# WEB_SEARCH_PROVIDER controls fallback behavior:
#
# "auto" (default) — try all configured providers, fall through on failure
# "custom" — custom API only, throw on failure (NOT in auto chain)
# "firecrawl" — firecrawl only
# "tavily" — tavily only
# "exa" — exa only
# "you" — you.com only
# "jina" — jina only
# "brave" — brave only
# "bing" — bing only
# "mojeek" — mojeek only
# "linkup" — linkup only
# "ddg" — duckduckgo only
# "native" — anthropic native / codex only
#
# Auto mode priority: firecrawl → tavily → exa → you → jina → brave → bing →
# mojeek → linkup → ddg
# Note: "custom" is NOT in the auto chain. To use the custom API provider,
# you must explicitly set WEB_SEARCH_PROVIDER=custom.
#
# WEB_SEARCH_PROVIDER=auto
# ── Built-in custom API presets ─────────────────────────────────────
#
# Use with WEB_KEY for the API key:
# WEB_PROVIDER=searxng|google|brave|serpapi
# WEB_KEY=your-api-key-here
#
# Google Custom Search additionally requires the Programmable Search Engine ID:
# WEB_PROVIDER=google
# WEB_KEY=your-google-api-key
# GOOGLE_CSE_ID=your-programmable-search-engine-id
#
# Note: Google's Custom Search JSON API is closed to new customers and is
# scheduled for sunset on 2027-01-01. Prefer BRAVE_API_KEY / TAVILY_API_KEY
# / EXA_API_KEY for new setups.
# ── Custom API endpoint (advanced) ──────────────────────────────────
#
# WEB_SEARCH_API — base URL of your search endpoint
# WEB_QUERY_PARAM — query parameter name (default: "q")
# WEB_METHOD — GET or POST (default: GET)
# WEB_PARAMS — extra static query params as JSON: {"lang":"en","count":"10"}
# WEB_URL_TEMPLATE — URL template with {query} for path embedding
# WEB_BODY_TEMPLATE — custom POST body with {query} placeholder
# WEB_AUTH_HEADER — header name for API key (default: "Authorization")
# WEB_AUTH_SCHEME — prefix before key (default: "Bearer")
# WEB_HEADERS — extra headers as "Name: value; Name2: value2"
# WEB_JSON_PATH — dot-path to results array in response
# ── Custom API security guardrails ──────────────────────────────────
#
# The custom provider enforces security guardrails by default.
# Override these only if you understand the risks.
#
# WEB_CUSTOM_TIMEOUT_SEC=15 — request timeout in seconds (default 15)
# WEB_CUSTOM_MAX_BODY_KB=300 — max POST body size in KB (default 300)
# WEB_CUSTOM_ALLOW_ARBITRARY_HEADERS=false — set "true" to use non-standard headers
# WEB_CUSTOM_ALLOW_HTTP=false — set "true" to allow http:// URLs
# WEB_CUSTOM_ALLOW_PRIVATE=false — set "true" to target localhost/private IPs
# (needed for self-hosted SearXNG)
Reference in New Issue View Git Blame Copy Permalink