fix: warn users when ANTHROPIC_API_KEY conflicts with Claude Code subscription

- Add environment variable detection in ClaudeCodeHandler constructor
- Show warning notification when ANTHROPIC_API_KEY is detected
- Add i18n translations for the warning message
- Include "Learn More" action that links to Claude Code authentication docs
- Add comprehensive tests for the new functionality

Fixes #7196

Author: roomote

src/api/providers/__tests__/claude-code.spec.ts

@@ -1,8 +1,27 @@
-import { describe, test, expect, vi, beforeEach } from "vitest"
+import { describe, test, expect, vi, beforeEach, afterEach } from "vitest"
+import * as vscode from "vscode"
 import { ClaudeCodeHandler } from "../claude-code"
 import { ApiHandlerOptions } from "../../../shared/api"
 import { ClaudeCodeMessage } from "../../../integrations/claude-code/types"
 
+// Mock vscode module
+vi.mock("vscode", () => ({
+	window: {
+		showWarningMessage: vi.fn(() => Promise.resolve(undefined)),
+	},
+	env: {
+		openExternal: vi.fn(),
+	},
+	Uri: {
+		parse: vi.fn((url: string) => ({ url })),
+	},
+}))
+
+// Mock i18n
+vi.mock("../../../i18n", () => ({
+	t: vi.fn((key: string) => key),
+}))
+
 // Mock the runClaudeCode function
 vi.mock("../../../integrations/claude-code/run", () => ({
 	runClaudeCode: vi.fn(),
@@ -20,16 +39,27 @@ const mockFilterMessages = vi.mocked(filterMessagesForClaudeCode)
 
 describe("ClaudeCodeHandler", () => {
 	let handler: ClaudeCodeHandler
+	let originalEnv: NodeJS.ProcessEnv
 
 	beforeEach(() => {
 		vi.clearAllMocks()
+		// Save original environment
+		originalEnv = { ...process.env }
+		// Reset the static flag
+		;(ClaudeCodeHandler as any).hasShownApiKeyWarning = false
+
 		const options: ApiHandlerOptions = {
 			claudeCodePath: "claude",
 			apiModelId: "claude-3-5-sonnet-20241022",
 		}
 		handler = new ClaudeCodeHandler(options)
 	})
 
+	afterEach(() => {
+		// Restore original environment
+		process.env = originalEnv
+	})
+
 	test("should create handler with correct model configuration", () => {
 		const model = handler.getModel()
 		expect(model.id).toBe("claude-3-5-sonnet-20241022")
@@ -563,4 +593,122 @@ describe("ClaudeCodeHandler", () => {
 
 		consoleSpy.mockRestore()
 	})
+
+	describe("ANTHROPIC_API_KEY environment variable detection", () => {
+		test("should show warning when ANTHROPIC_API_KEY is set", async () => {
+			// Set the environment variable
+			process.env.ANTHROPIC_API_KEY = "sk-ant-test-key"
+
+			// Reset the static flag to allow warning to show
+			;(ClaudeCodeHandler as any).hasShownApiKeyWarning = false
+
+			// Create a new handler instance
+			const options: ApiHandlerOptions = {
+				claudeCodePath: "claude",
+				apiModelId: "claude-3-5-sonnet-20241022",
+			}
+			new ClaudeCodeHandler(options)
+
+			// Verify warning was shown
+			expect(vscode.window.showWarningMessage).toHaveBeenCalledWith(
+				"common:warnings.anthropic_api_key_conflict",
+				"common:actions.learn_more",
+			)
+		})
+
+		test("should not show warning when ANTHROPIC_API_KEY is not set", async () => {
+			// Ensure the environment variable is not set
+			delete process.env.ANTHROPIC_API_KEY
+
+			// Reset the static flag
+			;(ClaudeCodeHandler as any).hasShownApiKeyWarning = false
+
+			// Create a new handler instance
+			const options: ApiHandlerOptions = {
+				claudeCodePath: "claude",
+				apiModelId: "claude-3-5-sonnet-20241022",
+			}
+			new ClaudeCodeHandler(options)
+
+			// Verify warning was not shown
+			expect(vscode.window.showWarningMessage).not.toHaveBeenCalled()
+		})
+
+		test("should only show warning once per session", async () => {
+			// Set the environment variable
+			process.env.ANTHROPIC_API_KEY = "sk-ant-test-key"
+
+			// Reset the static flag
+			;(ClaudeCodeHandler as any).hasShownApiKeyWarning = false
+
+			// Create first handler instance
+			const options: ApiHandlerOptions = {
+				claudeCodePath: "claude",
+				apiModelId: "claude-3-5-sonnet-20241022",
+			}
+			new ClaudeCodeHandler(options)
+
+			// Clear mock calls
+			vi.clearAllMocks()
+
+			// Create second handler instance
+			new ClaudeCodeHandler(options)
+
+			// Verify warning was not shown the second time
+			expect(vscode.window.showWarningMessage).not.toHaveBeenCalled()
+		})
+
+		test("should open external link when Learn More is clicked", async () => {
+			// Set the environment variable
+			process.env.ANTHROPIC_API_KEY = "sk-ant-test-key"
+
+			// Reset the static flag
+			;(ClaudeCodeHandler as any).hasShownApiKeyWarning = false
+
+			// Mock the showWarningMessage to simulate clicking "Learn More"
+			vi.mocked(vscode.window.showWarningMessage).mockResolvedValue("common:actions.learn_more" as any)
+
+			// Create a new handler instance
+			const options: ApiHandlerOptions = {
+				claudeCodePath: "claude",
+				apiModelId: "claude-3-5-sonnet-20241022",
+			}
+			new ClaudeCodeHandler(options)
+
+			// Wait for the promise to resolve
+			await new Promise((resolve) => setTimeout(resolve, 0))
+
+			// Verify external link was opened
+			expect(vscode.Uri.parse).toHaveBeenCalledWith(
+				"https://docs.anthropic.com/en/docs/claude-code/setup#authentication",
+			)
+			expect(vscode.env.openExternal).toHaveBeenCalledWith({
+				url: "https://docs.anthropic.com/en/docs/claude-code/setup#authentication",
+			})
+		})
+
+		test("should handle when user dismisses the warning", async () => {
+			// Set the environment variable
+			process.env.ANTHROPIC_API_KEY = "sk-ant-test-key"
+
+			// Reset the static flag
+			;(ClaudeCodeHandler as any).hasShownApiKeyWarning = false
+
+			// Mock the showWarningMessage to simulate dismissing
+			vi.mocked(vscode.window.showWarningMessage).mockResolvedValue(undefined as any)
+
+			// Create a new handler instance
+			const options: ApiHandlerOptions = {
+				claudeCodePath: "claude",
+				apiModelId: "claude-3-5-sonnet-20241022",
+			}
+			new ClaudeCodeHandler(options)
+
+			// Wait for the promise to resolve
+			await new Promise((resolve) => setTimeout(resolve, 0))
+
+			// Verify external link was not opened
+			expect(vscode.env.openExternal).not.toHaveBeenCalled()
+		})
+	})
 })

src/api/providers/claude-code.ts

@@ -1,4 +1,5 @@
 import type { Anthropic } from "@anthropic-ai/sdk"
+import * as vscode from "vscode"
 import {
 	claudeCodeDefaultModelId,
 	type ClaudeCodeModelId,
@@ -16,10 +17,35 @@ import { ApiHandlerOptions } from "../../shared/api"
 
 export class ClaudeCodeHandler extends BaseProvider implements ApiHandler {
 	private options: ApiHandlerOptions
+	private static hasShownApiKeyWarning = false
 
 	constructor(options: ApiHandlerOptions) {
 		super()
 		this.options = options
+		this.checkForAnthropicApiKey()
+	}
+
+	private async checkForAnthropicApiKey() {
+		// Only check and warn once per session to avoid annoying the user
+		if (!ClaudeCodeHandler.hasShownApiKeyWarning && process.env.ANTHROPIC_API_KEY) {
+			ClaudeCodeHandler.hasShownApiKeyWarning = true
+
+			try {
+				// Show warning notification to the user
+				const selection = await vscode.window.showWarningMessage(
+					t("common:warnings.anthropic_api_key_conflict"),
+					t("common:actions.learn_more"),
+				)
+
+				if (selection === t("common:actions.learn_more")) {
+					vscode.env.openExternal(
+						vscode.Uri.parse("https://docs.anthropic.com/en/docs/claude-code/setup#authentication"),
+					)
+				}
+			} catch {
+				// Silently ignore any errors from the warning dialog
+			}
+		}
 	}
 
 	override async *createMessage(systemPrompt: string, messages: Anthropic.Messages.MessageParam[]): ApiStream {

src/i18n/locales/en/common.json

@@ -105,7 +105,8 @@
 	"warnings": {
 		"no_terminal_content": "No terminal content selected",
 		"missing_task_files": "This task's files are missing. Would you like to remove it from the task list?",
-		"auto_import_failed": "Failed to auto-import RooCode settings: {{error}}"
+		"auto_import_failed": "Failed to auto-import RooCode settings: {{error}}",
+		"anthropic_api_key_conflict": "An ANTHROPIC_API_KEY environment variable was detected. This may conflict with your Claude Max/Pro subscription login and cause authentication errors. Please unset this environment variable to ensure your subscription plan is used correctly."
 	},
 	"info": {
 		"no_changes": "No changes found.",
@@ -134,6 +135,9 @@
 		"edit": "Edit",
 		"learn_more": "Learn More"
 	},
+	"actions": {
+		"learn_more": "Learn More"
+	},
 	"tasks": {
 		"canceled": "Task error: It was stopped and canceled by the user.",
 		"deleted": "Task failure: It was stopped and deleted by the user.",