Claude Env Switcher

English | 中文

English

Claude Env Switcher manages Claude Code environment profiles for each workspace. It switches Anthropic-compatible and OpenAI-compatible providers without hand-editing .claude/settings.local.json.

Profiles are stored in VS Code user settings and can sync across machines. The active profile and generated runtime state remain workspace-local.

Design Goals

• Keep profile switching explicit, visible, and workspace-scoped.
• Avoid global detached background services.
• Start the OpenAI-compatible router only when Claude Code actually needs it.
• Keep each workspace isolated, even when multiple VS Code windows are open.
• Work the same way on local VS Code, Remote SSH, Linux, macOS, and Windows.

Key Features

• Manage named Claude Code profiles from a VS Code panel or quick pick.
• Switch native Anthropic-compatible environment variables.
• Use OpenAI-compatible APIs through the built-in workspace router.
• Configure router port mode per OpenAI-compatible profile:
  • Auto
  • Random in range
  • Preferred port with fallback
• Keep one router owner per workspace.
• Reuse one workspace router for multiple Claude sessions in the same workspace.
• Support owner/follower coordination when the same workspace is opened in multiple VS Code windows.
• Handle Claude Code token-count compatibility requests locally with the router's heuristic estimator.
• Preserve Claude Code model context suffixes such as [1m] while sending clean model IDs upstream.
• Preserve Claude Code image, tool-use, thinking/reasoning, Responses API, and fallback model-chain behavior across OpenAI-compatible providers.
• Add files or folders to Claude Chat from the Explorer context menu.
• Optionally restart the extension host or reopen the latest Claude session after switching profiles.

OpenAI-Compatible Router Model

OpenAI-compatible profiles do not start the router immediately when applied. Applying a profile only prepares workspace state:

• route token
• desired profile config
• workspace hook
• owner/follower coordination files

When Claude Code runs the UserPromptSubmit hook, the helper asks the current workspace owner to start the router. The owner then:

1. Selects the public endpoint port according to the profile strategy.
2. Starts the workspace endpoint and native OpenAI-compatible router.
3. Confirms the router is ready.
4. Writes the actual ANTHROPIC_BASE_URL back to .claude/settings.local.json.

Request flow:

Claude Code
  -> workspace endpoint
  -> OpenAI-compatible upstream

The router is not a standalone global service. It is a child lifecycle resource of the current workspace owner plugin instance. When that owner closes, the endpoint exits as well. If another VS Code window has the same workspace open, it can become the next owner and rebuild the router on the next hook.

The compatibility endpoint POST /v1/messages/count_tokens is handled by the lightweight workspace endpoint itself. It does not call the upstream provider and does not store prompt content. It uses a local heuristic estimate, so it is best treated as a compression-timing aid rather than provider-exact billing data.

GET /v1/models is also handled by the workspace endpoint. For Claude Code clients it returns Claude-style model metadata and context capability fields without contacting the upstream provider. If a configured model uses Claude Code's context suffix, for example gpt-4.1[1m], the suffix is kept visible to Claude Code but stripped before the request reaches the OpenAI-compatible upstream:

Claude-facing model:  gpt-4.1[1m]
Upstream model:       gpt-4.1

The OpenAI-compatible router follows the Claude Code behavior used by cc-switch for normal development workflows:

• router.apiFormat can select anthropic, openai_chat, or openai_responses.
• OpenRouter defaults to Claude-compatible Anthropic passthrough unless a format is explicitly configured.
• Anthropic image blocks are preserved as OpenAI image_url or Responses input_image inputs.
• Unknown models are treated as image-capable until an explicit model catalog says otherwise.
• Text-only model handling and unsupported-image retry replace images with [Unsupported Image] only when needed.
• Thinking/reasoning deltas, tool calls, tool results, usage, cache tokens, and fallback model chains are normalized for Claude Code.
• OpenAI o-series chat models receive max_completion_tokens instead of max_tokens.

Cache And Usage Notes

Claude Env Switcher does not implement a local prompt/content cache. Cache hit-rate numbers, when available, come from upstream usage fields such as cached_tokens, cache_read_tokens, or cache_read_input_tokens returned by the OpenAI-compatible provider and normalized by the router runtime.

Dynamic local ports, workspace hashes, runtime ids, generation numbers, and route tokens are management-layer data and are not injected into the upstream request body. In practice, cache hit rate depends mostly on the upstream provider's own cache support, model/key/provider stability, and whether Claude Code sends a stable prompt prefix across requests. Some OpenAI-compatible services do not report cache usage fields, so their displayed cache ratio may be low or zero even when the provider has internal optimizations.

Multi-Window Behavior

For one workspace:

workspace X -> one owner -> one endpoint/router
other VS Code windows -> followers

Multiple Claude sessions in the same workspace share the same router. Multiple VS Code windows for the same workspace do not each start their own router. This avoids profile, port, and route-token conflicts.

If the owner window closes, active streams through that owner may be interrupted. Later requests are handled by a follower after takeover.

Remote SSH Support

Remote SSH is a first-class scenario.

The extension runs as a workspace extension, so in a Remote SSH window the owner, helper, endpoint, router, and .claude/settings.local.json all live on the remote machine. The router binds to 127.0.0.1 on the remote host, which is exactly where remote Claude Code runs.

This means:

• no local machine router is required
• no manual SSH port forwarding is required
• remote and local workspaces have separate runtime directories
• synced profiles can be reused, while applied settings stay remote-workspace-local

Quick Start

1. Install the extension.
2. Run Claude Env Switcher: Manage Profiles.
3. Add an Anthropic-compatible or OpenAI-compatible profile.
4. Apply the profile.
5. Start using Claude Code in that workspace.

Applied settings are written to:

.claude/settings.local.json

Security Notes

Profile definitions are stored in VS Code user settings. If VS Code Settings Sync is enabled, profile definitions may sync across machines. Workspace runtime files and active profile state stay local to the current workspace/machine.

Auth tokens are masked in the UI, but they are still stored in VS Code settings. Avoid storing production secrets in synced settings unless that matches your security model.

Third-Party Notices

This extension includes a native workspace router for Anthropic-to-OpenAI-compatible request translation.

• OpenAI/OpenRouter behavior reference: cc-switch, used as the compatibility target for Claude Code's normal OpenAI router workflows.
• Claude Code Router compatibility reference: musistudio/claude-code-router, MIT License.

Claude Env Switcher manages VS Code profiles, workspace lifecycle, hooks, owner/follower coordination, and Remote SSH behavior around that router.

中文

Claude Env Switcher 用来按 workspace 管理 Claude Code 环境 Profile。它可以在 Anthropic-compatible 和 OpenAI-compatible Provider 之间切换，不需要手动编辑 .claude/settings.local.json。

Profile 定义存储在 VS Code 用户设置中，可以跟随 VS Code Settings Sync 同步；当前选中的 Profile 和运行态则保留在当前 workspace 本地。

设计思想

• Profile 切换必须明确、可见，并且以 workspace 为边界。
• 不启动全局 detached 后台服务。
• OpenAI-compatible 路由只在 Claude Code 真正需要时才启动。
• 每个 workspace 独立隔离，即使同一个 workspace 被多个 VS Code 窗口打开。
• 本地 VS Code、Remote SSH、Linux、macOS、Windows 使用同一套机制。

功能亮点

• 通过 VS Code 面板或 Quick Pick 管理命名 Profile。
• 支持原生 Anthropic-compatible 环境变量切换。
• 通过内置 workspace router 使用 OpenAI-compatible API。
• OpenAI-compatible Profile 可配置路由端口策略：
  • Auto
  • Random in range
  • Preferred port with fallback
• 同一个 workspace 只有一个 router owner。
• 同一个 workspace 内多个 Claude 会话共享同一个 workspace router。
• 同一个 workspace 被多个 VS Code 窗口打开时，使用 owner/follower 协调，避免多实例冲突。
• 使用 router 的本地启发式估算处理 Claude Code token-count 兼容请求。
• 保留 Claude Code 的 [1m] 等模型上下文后缀，同时向上游发送干净模型 ID。
• 在 OpenAI-compatible Provider 上保留图片、工具调用、thinking/reasoning、Responses API 和 fallback model-chain 等 Claude Code 正常使用行为。
• 支持从 Explorer 右键把文件或文件夹加入 Claude Chat。
• 切换 Profile 后可选择重启 extension host、重新打开最近 Claude 会话，或不做额外动作。

OpenAI-Compatible Router 模型

应用 OpenAI-compatible Profile 时不会立刻启动 router。此时只准备 workspace 状态：

• route token
• desired profile config
• workspace hook
• owner/follower 协调文件

当 Claude Code 执行 UserPromptSubmit hook 时，helper 会请求当前 workspace owner 启动路由。owner 随后会：

1. 根据 Profile 端口策略确定 public endpoint 端口。
2. 启动 workspace endpoint 和原生 OpenAI-compatible router。
3. 确认 router ready。
4. 将真实的 ANTHROPIC_BASE_URL 写回 .claude/settings.local.json。

请求链路：

Claude Code
  -> workspace endpoint
  -> OpenAI-compatible upstream

Router 不是独立全局服务，而是当前 workspace owner 插件实例的子生命周期资源。owner 关闭时，endpoint 也会退出。如果同一个 workspace 还有其他 VS Code 窗口打开，follower 可以在下一次 hook 时接管并重建路由。

兼容端点 POST /v1/messages/count_tokens 由轻量 workspace endpoint 自己处理。它不会请求上游 Provider，也不会保存 prompt 内容。该接口使用本地启发式估算，因此它更适合作为压缩时机参考，而不是精确的 Provider 计费数据。

GET /v1/models 也由 workspace endpoint 处理。对于 Claude Code 客户端，它会返回 Claude 风格的模型元信息和上下文能力字段。如果配置的模型带有 Claude Code 上下文后缀，例如 gpt-4.1[1m]，该后缀会继续暴露给 Claude Code，但真正请求 OpenAI-compatible 上游前会被剥离：

Claude-facing model:  gpt-4.1[1m]
Upstream model:       gpt-4.1

OpenAI-compatible router 按 cc-switch 的 Claude Code 正常开发链路对齐：

• router.apiFormat 可选择 anthropic、openai_chat 或 openai_responses。
• OpenRouter 默认走 Claude-compatible Anthropic 透传，除非显式配置格式转换。
• Anthropic 图片块会保留为 OpenAI image_url 或 Responses input_image。
• 未知模型默认按支持图片处理，只有显式 catalog 表明 text-only 时才提前替换图片。
• text-only 模型和上游不支持图片错误会按需把图片替换为 [Unsupported Image] 后重试。
• thinking/reasoning delta、工具调用、工具结果、usage、cache token 和 fallback model-chain 会归一化为 Claude Code 可用的 Anthropic 形态。
• OpenAI o-series chat 模型会使用 max_completion_tokens，而不是 max_tokens。

缓存与用量说明

Claude Env Switcher 不实现本地 prompt/content 缓存。缓存命中率如果可见，来源于 OpenAI-compatible Provider 返回的 usage 字段，例如 cached_tokens、cache_read_tokens 或 cache_read_input_tokens，再由 router runtime 做归一化。

动态本地端口、workspace hash、runtime id、generation 和 route token 都属于管理层数据，不会注入到上游请求 body。实际缓存命中率主要取决于上游 Provider 是否支持缓存上报、模型/key/Provider 是否稳定，以及 Claude Code 在多次请求中是否发送稳定的 prompt 前缀。部分 OpenAI-compatible 服务不会返回缓存用量字段，因此展示出来的缓存比例可能很低或为 0，即使 Provider 内部存在优化。

多窗口行为

对于同一个 workspace：

workspace X -> one owner -> one endpoint/router
other VS Code windows -> followers

同一个 workspace 内的多个 Claude 会话共享同一个 router。同一个 workspace 的多个 VS Code 窗口不会各自启动一套路由，从而避免 Profile、端口和 route token 冲突。

如果关闭的是 owner 窗口，正在通过该 owner streaming 的请求可能会中断。后续请求会在 follower 接管后重新启动路由。

Remote SSH 支持

Remote SSH 是完整适配场景。

本插件是 workspace extension，因此在 Remote SSH 窗口中，owner、helper、endpoint、router 和 .claude/settings.local.json 都运行或写入在远程机器上。路由绑定的是远程主机上的 127.0.0.1，这正是远程 Claude Code 所在的位置。

这意味着：

• 不需要本机启动 router
• 不需要手动配置 SSH 端口转发
• 远程 workspace 和本地 workspace 拥有独立 runtime 目录
• Profile 定义可以同步，但实际应用结果保留在远程 workspace 本地

快速开始

1. 安装插件。
2. 执行 Claude Env Switcher: Manage Profiles。
3. 添加 Anthropic-compatible 或 OpenAI-compatible Profile。
4. 应用 Profile。
5. 在当前 workspace 中使用 Claude Code。

应用后的设置写入：

.claude/settings.local.json

安全说明

Profile 定义存储在 VS Code 用户设置中。如果开启 VS Code Settings Sync，Profile 定义可能会同步到其他机器。workspace runtime 文件和当前激活状态仍保留在当前 workspace/机器本地。

认证 token 会在 UI 中隐藏，但仍然存储在 VS Code 设置里。是否把生产密钥放进同步设置中，应按你的安全模型决定。

第三方声明

本插件内置了一个原生 workspace router，用于 Anthropic 到 OpenAI-compatible 的请求转换。

• OpenAI/OpenRouter 行为参考：cc-switch，作为 Claude Code 正常 OpenAI router 工作流的兼容目标。
• Claude Code Router 兼容参考：musistudio/claude-code-router，MIT License。

Claude Env Switcher 负责围绕该 router 管理 VS Code Profile、workspace 生命周期、hook、owner/follower 协调以及 Remote SSH 场景。