Make missing OPENAI_API_KEY error actionable

The OpenAI provider raised a bare "OPENAI_API_KEY is required", which
misdirects CrewAI AMP users who configured an org-wide LLM Connection.
The error now explains the remediation (set the OPENAI_API_KEY
environment variable or pass api_key to LLM()) and clarifies that
org-wide LLM Connections do not apply to code-first AMP deployments,
which read keys from deployment environment variables.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

lib/cli/tests/deploy/test_validate.py

@@ -383,7 +383,11 @@ def test_classify_missing_openai_key_is_warning(tmp_path: Path) -> None:
     v._classify_import_error(
         "ImportError",
         "Error importing native provider: 1 validation error for OpenAICompletion\n"
-        "  Value error, OPENAI_API_KEY is required",
+        "  Value error, OPENAI_API_KEY is required. Set the OPENAI_API_KEY "
+        "environment variable or pass api_key to LLM(). On CrewAI AMP, "
+        "code-first deployments read API keys from deployment environment "
+        "variables — org-wide LLM Connections do not apply to code-first "
+        "deployments.",
         tb="",
     )
     assert len(v.results) == 1

lib/crewai/src/crewai/llms/providers/openai/completion.py

@@ -387,7 +387,13 @@ class OpenAICompletion(BaseLLM):
         if self.api_key is None:
             self.api_key = os.getenv("OPENAI_API_KEY")
             if self.api_key is None:
-                raise ValueError("OPENAI_API_KEY is required")
+                raise ValueError(
+                    "OPENAI_API_KEY is required. Set the OPENAI_API_KEY "
+                    "environment variable or pass api_key to LLM(). On CrewAI "
+                    "AMP, code-first deployments read API keys from deployment "
+                    "environment variables — org-wide LLM Connections do not "
+                    "apply to code-first deployments."
+                )
 
         base_params = {
             "api_key": self.api_key,

lib/crewai/tests/llms/openai/test_openai.py

@@ -618,6 +618,25 @@ def test_openai_get_client_params_no_base_url(monkeypatch):
     assert "base_url" not in client_params or client_params.get("base_url") is None
 
 
+def test_openai_missing_api_key_error_is_actionable(monkeypatch):
+    """
+    Test that the missing-API-key error explains how to fix it: set the
+    OPENAI_API_KEY environment variable or pass api_key, and clarifies that
+    org-wide LLM Connections do not apply to code-first CrewAI AMP deployments.
+    """
+    monkeypatch.delenv("OPENAI_API_KEY", raising=False)
+
+    llm = OpenAICompletion(model="gpt-4o")
+    with pytest.raises(ValueError) as exc_info:
+        llm._get_client_params()
+
+    message = str(exc_info.value)
+    assert "OPENAI_API_KEY environment variable" in message
+    assert "api_key" in message
+    assert "org-wide LLM Connections do not apply to code-first deployments" in message
+    assert "deployment environment variables" in message
+
+
 def test_openai_streaming_with_response_model():
     """
     Test that streaming with response_model works correctly and doesn't call invalid API methods.