Login Register

mike / Claude Code 3Party Config

Last active 1 month ago

Like 0

mike revised this gist 1 month ago · f79bbe5

1 file changed, 237 insertions

claudecode3p.md (file created)
@@ -0,0 +1,237 @@
1 + # Claude Desktop 3P Mode with LiteLLM
2 +
3 + Claude Desktop has a **third-party inference (3P) mode** that allows the Desktop application to route inference requests through a custom gateway such as LiteLLM. This is configured separately from the normal Anthropic account login. Recent Claude Desktop configurations use a `Claude-3p` configuration directory and an `inferenceProvider: "gateway"` configuration. ([Gist][1])
4 +
5 + > **Important:** When configuring the LiteLLM gateway URL in Claude Desktop 3P mode, **do not include `/v1` in the Base URL**. Claude Desktop adds the `/v1/...` API paths itself. For example, use `http://localhost:4000`, **not** `http://localhost:4000/v1`. A working 3P gateway will ultimately receive requests such as `/v1/models` and `/v1/messages`. ([GitHub][2])
6 +
7 + ## 1. Enable Developer Mode
8 +
9 + Open Claude Desktop and go to:
10 +
11 + **Help → Troubleshooting → Enable Developer Mode**
12 +
13 + After enabling Developer Mode, Claude Desktop exposes the developer configuration options, including:
14 +
15 + **Developer → Configure third-party inference**
16 +
17 + This is the preferred way to create the 3P configuration.
18 +
19 + ## 2. Configure the LiteLLM gateway
20 +
21 + In **Configure third-party inference**, select the gateway/custom provider option.
22 +
23 + Use your LiteLLM proxy as the gateway.
24 +
25 + For a local LiteLLM installation:
26 +
27 + ```text
28 + Gateway/Base URL:
29 + http://localhost:4000
30 +
31 + API Key:
32 + sk-your-litellm-key
33 + ```
34 +
35 + For a remote LiteLLM installation:
36 +
37 + ```text
38 + Gateway/Base URL:
39 + https://litellm.example.com
40 +
41 + API Key:
42 + sk-your-litellm-key
43 + ```
44 +
45 + ### Do NOT use this
46 +
47 + ```text
48 + http://localhost:4000/v1
49 + ```
50 +
51 + ### Use this instead
52 +
53 + ```text
54 + http://localhost:4000
55 + ```
56 +
57 + LiteLLM itself exposes the Anthropic-compatible API under paths such as:
58 +
59 + ```text
60 + /v1/messages
61 + /v1/models
62 + ```
63 +
64 + Claude Desktop's gateway configuration supplies those API paths. ([GitHub][2])
65 +
66 + ## 3. LiteLLM configuration
67 +
68 + For example, a minimal LiteLLM configuration could look like:
69 +
70 + ```yaml
71 + model_list:
72 + - model_name: claude-sonnet
73 + litellm_params:
74 + model: anthropic/claude-sonnet-4-6
75 + api_key: os.environ/ANTHROPIC_API_KEY
76 +
77 + general_settings:
78 + master_key: os.environ/LITELLM_MASTER_KEY
79 + ```
80 +
81 + Start LiteLLM on port 4000:
82 +
83 + ```bash
84 + litellm --config config.yaml --port 4000
85 + ```
86 +
87 + Then Claude Desktop should connect to:
88 +
89 + ```text
90 + http://localhost:4000
91 + ```
92 +
93 + while LiteLLM handles:
94 +
95 + ```text
96 + http://localhost:4000/v1/messages
97 + http://localhost:4000/v1/models
98 + ```
99 +
100 + ## 4. What the resulting 3P configuration looks like
101 +
102 + Claude Desktop stores its 3P configuration separately from the normal Desktop configuration. On macOS, for example, configurations can be found under:
103 +
104 + ```text
105 + ~/Library/Application Support/Claude-3p/
106 + ```
107 +
108 + A representative configuration contains:
109 +
110 + ```json
111 + {
112 + "deploymentMode": "3p",
113 + "enterpriseConfig": {
114 + "inferenceProvider": "gateway",
115 + "inferenceGatewayBaseUrl": "http://localhost:4000",
116 + "inferenceGatewayApiKey": "sk-your-litellm-key",
117 + "inferenceGatewayAuthScheme": "bearer",
118 + "inferenceModels": [
119 + "claude-sonnet-4-6"
120 + ]
121 + }
122 + }
123 + ```
124 +
125 + The exact configuration structure can vary between Claude Desktop releases, so it is preferable to let **Configure third-party inference** generate the configuration rather than manually replacing the entire file. Current examples confirm the `deploymentMode: "3p"` and `inferenceProvider: "gateway"` structure. ([Gist][1])
126 +
127 + ## 5. Restart Claude Desktop
128 +
129 + After saving the third-party inference configuration, allow Claude Desktop to restart.
130 +
131 + You should now be running in **3P mode**, with inference routed approximately as follows:
132 +
133 + ```text
134 + ┌──────────────────────┐
135 + │ Claude Desktop │
136 + │ │
137 + │ 3P Mode │
138 + └──────────┬───────────┘
139 + │
140 + │ Base URL:
141 + │ http://localhost:4000
142 + ▼
143 + ┌──────────────────────┐
144 + │ LiteLLM │
145 + │ │
146 + │ /v1/messages │
147 + │ /v1/models │
148 + └──────────┬───────────┘
149 + │
150 + ▼
151 + ┌──────────────────────┐
152 + │ Configured model │
153 + │ │
154 + │ Anthropic / OpenAI / │
155 + │ Bedrock / etc. │
156 + └──────────────────────┘
157 + ```
158 +
159 + ## 6. Verify LiteLLM independently
160 +
161 + Before troubleshooting Claude Desktop, verify that LiteLLM is responding.
162 +
163 + For example:
164 +
165 + ```bash
166 + curl http://localhost:4000/v1/models \
167 + -H "Authorization: Bearer sk-your-litellm-key"
168 + ```
169 +
170 + You should get a model list.
171 +
172 + You can also test the Anthropic Messages endpoint directly:
173 +
174 + ```bash
175 + curl http://localhost:4000/v1/messages \
176 + -H "x-api-key: sk-your-litellm-key" \
177 + -H "anthropic-version: 2023-06-01" \
178 + -H "content-type: application/json" \
179 + -d '{
180 + "model": "claude-sonnet",
181 + "max_tokens": 100,
182 + "messages": [
183 + {
184 + "role": "user",
185 + "content": "Say hello"
186 + }
187 + ]
188 + }'
189 + ```
190 +
191 + If these work but Claude Desktop doesn't, the problem is likely the 3P configuration rather than LiteLLM.
192 +
193 + ## 7. Authentication caveat
194 +
195 + There is an important distinction between **authenticating to LiteLLM** and **authenticating LiteLLM to Anthropic**.
196 +
197 + Your Claude Desktop 3P API key:
198 +
199 + ```text
200 + sk-your-litellm-key
201 + ```
202 +
203 + authenticates **Claude Desktop → LiteLLM**.
204 +
205 + If LiteLLM is routing to Anthropic, LiteLLM still needs valid credentials for **LiteLLM → Anthropic**. Current testing indicates that Claude Desktop's 3P/Cowork path does not necessarily forward an existing Claude subscription OAuth credential to LiteLLM, so a normal Anthropic API key may be required on the LiteLLM side. ([GitHub][3])
206 +
207 + For example:
208 +
209 + ```yaml
210 + model_list:
211 + - model_name: claude-sonnet
212 + litellm_params:
213 + model: anthropic/claude-sonnet-4-6
214 + api_key: os.environ/ANTHROPIC_API_KEY
215 + ```
216 +
217 + This is different from the Claude Code CLI, which has a different credential-forwarding behavior. ([GitHub][3])
218 +
219 + ## Quick reference
220 +
221 + | Setting | Value |
222 + | ------------------- | -------------------------------------------------- |
223 + | Mode | `3p` |
224 + | Provider | `gateway` |
225 + | LiteLLM local URL | `http://localhost:4000` |
226 + | **Include `/v1`?** | **No** |
227 + | API key | Your LiteLLM virtual/master key |
228 + | LiteLLM API paths | `/v1/messages`, `/v1/models` |
229 + | LiteLLM → Anthropic | Requires appropriate Anthropic credentials |
230 + | Developer Mode | **Help → Troubleshooting → Enable Developer Mode** |
231 + | Configuration | **Developer → Configure third-party inference** |
232 +
233 + **The key gotcha:** **Claude Desktop 3P Base URL = the gateway root, not the API version path.** So if LiteLLM is listening on port 4000, enter `http://localhost:4000`, not `http://localhost:4000/v1`. ([GitHub][2])
234 +
235 + [1]: https://gist.github.com/avarayr/a9a35354aa6d7d8430ce0c27cd9aff3f?permalink_comment_id=6137995&utm_source=chatgpt.com "~/Library/Application Support/Claude-3p/claude_desktop_config.json · GitHub"
236 + [2]: https://github.com/farion1231/cc-switch/issues/2982?utm_source=chatgpt.com "Claude Desktop 3P mode: WebFetch fails because domain safety check is not allowed/proxied · Issue #2982 · farion1231/cc-switch · GitHub"
237 + [3]: https://github.com/BerriAI/litellm/discussions/30827?utm_source=chatgpt.com "Claude Chat/Cowork Desktop App LiteLLM Integration · BerriAI litellm · Discussion #30827 · GitHub"