Documentation — Spybara

agent-sdk/custom-tools.md +833 −0 created

Details

1> ## Documentation Index

2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt

3> Use this file to discover all available pages before exploring further.

5# Dê a Claude ferramentas personalizadas

7> Defina ferramentas personalizadas com o servidor MCP em processo do Agent SDK do Claude para que Claude possa chamar suas funções, acessar suas APIs e executar operações específicas do domínio.

9Ferramentas personalizadas estendem o Agent SDK permitindo que você defina suas próprias funções que Claude pode chamar durante uma conversa. Usando o servidor MCP em processo do SDK, você pode dar a Claude acesso a bancos de dados, APIs externas, lógica específica do domínio ou qualquer outra capacidade que sua aplicação necessite.

11Este guia cobre como definir ferramentas com esquemas de entrada e manipuladores, agrupá-las em um servidor MCP, passá-las para `query` e controlar quais ferramentas Claude pode acessar. Também cobre tratamento de erros, anotações de ferramentas e retorno de conteúdo não-texto como imagens.

13## Referência rápida

15| Se você quer... | Faça isto |

16| :----------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

17| Definir uma ferramenta | Use [`@tool`](/pt/agent-sdk/python#tool) (Python) ou [`tool()`](/pt/agent-sdk/typescript#tool) (TypeScript) com um nome, descrição, esquema e manipulador. Veja [Criar uma ferramenta personalizada](#create-a-custom-tool). |

18| Registrar uma ferramenta com Claude | Envolva em `create_sdk_mcp_server` / `createSdkMcpServer` e passe para `mcpServers` em `query()`. Veja [Chamar uma ferramenta personalizada](#call-a-custom-tool). |

19| Pré-aprovar uma ferramenta | Adicione às suas ferramentas permitidas. Veja [Configurar ferramentas permitidas](#configure-allowed-tools). |

20| Remover uma ferramenta integrada do contexto de Claude | Passe um array `tools` listando apenas os integrados que você quer. Veja [Configurar ferramentas permitidas](#configure-allowed-tools). |

21| Deixar Claude chamar ferramentas em paralelo | Defina `readOnlyHint: true` em ferramentas sem efeitos colaterais. Veja [Adicionar anotações de ferramentas](#add-tool-annotations). |

22| Tratar erros sem parar o loop | Retorne `isError: true` em vez de lançar uma exceção. Veja [Tratar erros](#handle-errors). |

23| Retornar imagens ou arquivos | Use blocos `image` ou `resource` no array de conteúdo. Veja [Retornar imagens e recursos](#return-images-and-resources). |

24| Retornar um resultado JSON legível por máquina | Defina `structuredContent` no resultado. Veja [Retornar dados estruturados](#return-structured-data). |

25| Escalar para muitas ferramentas | Use [tool search](/pt/agent-sdk/tool-search) para carregar ferramentas sob demanda. |

27## Criar uma ferramenta personalizada

29Uma ferramenta é definida por quatro partes, passadas como argumentos para o auxiliar [`tool()`](/pt/agent-sdk/typescript#tool) em TypeScript ou o decorador [`@tool`](/pt/agent-sdk/python#tool) em Python:

31* **Nome:** um identificador único que Claude usa para chamar a ferramenta.

32* **Descrição:** o que a ferramenta faz. Claude lê isto para decidir quando chamá-la.

33* **Esquema de entrada:** os argumentos que Claude deve fornecer. Em TypeScript isto é sempre um [esquema Zod](https://zod.dev/), e os `args` do manipulador são tipados automaticamente a partir dele. Em Python isto é um dict mapeando nomes para tipos, como `{"latitude": float}`, que o SDK converte para JSON Schema para você. O decorador Python também aceita um dict completo de [JSON Schema](https://json-schema.org/understanding-json-schema/about) diretamente quando você precisa de enums, intervalos, campos opcionais ou objetos aninhados.

34* **Manipulador:** a função assíncrona que executa quando Claude chama a ferramenta. Ela recebe os argumentos validados e deve retornar um objeto com:

35 * `content` (obrigatório): um array de blocos de resultado, cada um com um `type` de `"text"`, `"image"` ou `"resource"`. Veja [Retornar imagens e recursos](#return-images-and-resources) para blocos não-texto.

36 * `structuredContent` (opcional): um objeto JSON contendo o resultado como dados legíveis por máquina, retornado junto com `content`. Veja [Retornar dados estruturados](#return-structured-data).

37 * `isError` (opcional): defina como `true` para sinalizar uma falha de ferramenta para que Claude possa reagir a ela. Veja [Tratar erros](#handle-errors).

39Depois de definir uma ferramenta, envolva-a em um servidor com [`createSdkMcpServer`](/pt/agent-sdk/typescript#createsdkmcpserver) (TypeScript) ou [`create_sdk_mcp_server`](/pt/agent-sdk/python#create_sdk_mcp_server) (Python). O servidor executa em processo dentro de sua aplicação, não como um processo separado.

41### Exemplo de ferramenta de clima

43Este exemplo define uma ferramenta `get_temperature` e a envolve em um servidor MCP. Ele apenas configura a ferramenta; para passá-la para `query` e executá-la, veja [Chamar uma ferramenta personalizada](#call-a-custom-tool) abaixo.

45<CodeGroup>

46 ```python Python theme={null}

47 from typing import Any

48 import httpx

49 from claude_agent_sdk import tool, create_sdk_mcp_server

52 # Define a tool: name, description, input schema, handler

53 @tool(

54 "get_temperature",

55 "Get the current temperature at a location",

56 {"latitude": float, "longitude": float},

57 )

58 async def get_temperature(args: dict[str, Any]) -> dict[str, Any]:

59 async with httpx.AsyncClient() as client:

60 response = await client.get(

61 "https://api.open-meteo.com/v1/forecast",

62 params={

63 "latitude": args["latitude"],

64 "longitude": args["longitude"],

65 "current": "temperature_2m",

66 "temperature_unit": "fahrenheit",

67 },

68 )

69 data = response.json()

71 # Return a content array - Claude sees this as the tool result

72 return {

73 "content": [

74 {

75 "type": "text",

76 "text": f"Temperature: {data['current']['temperature_2m']}°F",

77 }

78 ]

79 }

82 # Wrap the tool in an in-process MCP server

83 weather_server = create_sdk_mcp_server(

84 name="weather",

85 version="1.0.0",

86 tools=[get_temperature],

87 )

88 ```

90 ```typescript TypeScript theme={null}

91 import { tool, createSdkMcpServer } from "@anthropic-ai/claude-agent-sdk";

92 import { z } from "zod";

94 // Define a tool: name, description, input schema, handler

95 const getTemperature = tool(

96 "get_temperature",

97 "Get the current temperature at a location",

98 {

99 latitude: z.number().describe("Latitude coordinate"), // .describe() adds a field description Claude sees

100 longitude: z.number().describe("Longitude coordinate")

101 },

102 async (args) => {

103 // args is typed from the schema: { latitude: number; longitude: number }

104 const response = await fetch(

105 `https://api.open-meteo.com/v1/forecast?latitude=${args.latitude}&longitude=${args.longitude}&current=temperature_2m&temperature_unit=fahrenheit`

106 );

107 const data: any = await response.json();

108

109 // Return a content array - Claude sees this as the tool result

110 return {

111 content: [{ type: "text", text: `Temperature: ${data.current.temperature_2m}°F` }]

112 };

113 }

114 );

115

116 // Wrap the tool in an in-process MCP server

117 const weatherServer = createSdkMcpServer({

118 name: "weather",

119 version: "1.0.0",

120 tools: [getTemperature]

121 });

122 ```

123</CodeGroup>

124

125Veja a referência TypeScript [`tool()`](/pt/agent-sdk/typescript#tool) ou a referência Python [`@tool`](/pt/agent-sdk/python#tool) para detalhes completos de parâmetros, incluindo formatos de entrada JSON Schema e estrutura de valor de retorno.

126

127<Tip>

128 Para tornar um parâmetro opcional: em TypeScript, adicione `.default()` ao campo Zod. Em Python, o esquema dict trata cada chave como obrigatória, então deixe o parâmetro fora do esquema, mencione-o na string de descrição e leia-o com `args.get()` no manipulador. A ferramenta [`get_precipitation_chance` abaixo](#add-more-tools) mostra ambos os padrões.

129</Tip>

130

131### Chamar uma ferramenta personalizada

132

133Passe o servidor MCP que você criou para `query` via a opção `mcpServers`. A chave em `mcpServers` torna-se o segmento `{server_name}` no nome totalmente qualificado de cada ferramenta: `mcp__{server_name}__{tool_name}`. Liste esse nome em `allowedTools` para que a ferramenta execute sem um prompt de permissão.

134

135Estes trechos reutilizam o `weatherServer` do [exemplo acima](#weather-tool-example) para perguntar a Claude qual é o clima em um local específico.

136

137<CodeGroup>

138 ```python Python theme={null}

139 import asyncio

140 from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage

141

142

143 async def main():

144 options = ClaudeAgentOptions(

145 mcp_servers={"weather": weather_server},

146 allowed_tools=["mcp__weather__get_temperature"],

147 )

148

149 async for message in query(

150 prompt="What's the temperature in San Francisco?",

151 options=options,

152 ):

153 # ResultMessage is the final message after all tool calls complete

154 if isinstance(message, ResultMessage) and message.subtype == "success":

155 print(message.result)

156

157

158 asyncio.run(main())

159 ```

160

161 ```typescript TypeScript theme={null}

162 import { query } from "@anthropic-ai/claude-agent-sdk";

163

164 for await (const message of query({

165 prompt: "What's the temperature in San Francisco?",

166 options: {

167 mcpServers: { weather: weatherServer },

168 allowedTools: ["mcp__weather__get_temperature"]

169 }

170 })) {

171 // "result" is the final message after all tool calls complete

172 if (message.type === "result" && message.subtype === "success") {

173 console.log(message.result);

174 }

175 }

176 ```

177</CodeGroup>

178

179### Adicionar mais ferramentas

180

181Um servidor contém quantas ferramentas você listar em seu array `tools`. Com mais de uma ferramenta em um servidor, você pode listar cada uma em `allowedTools` individualmente ou usar o curinga `mcp__weather__*` para cobrir cada ferramenta que o servidor expõe.

182

183O exemplo abaixo adiciona uma segunda ferramenta, `get_precipitation_chance`, ao `weatherServer` do [exemplo de ferramenta de clima](#weather-tool-example) e o reconstrói com ambas as ferramentas no array.

184

185<CodeGroup>

186 ```python Python theme={null}

187 # Define a second tool for the same server

188 @tool(

189 "get_precipitation_chance",

190 "Get the hourly precipitation probability for a location. "

191 "Optionally pass 'hours' (1-24) to control how many hours to return.",

192 {"latitude": float, "longitude": float},

193 )

194 async def get_precipitation_chance(args: dict[str, Any]) -> dict[str, Any]:

195 # 'hours' isn't in the schema - read it with .get() to make it optional

196 hours = args.get("hours", 12)

197 async with httpx.AsyncClient() as client:

198 response = await client.get(

199 "https://api.open-meteo.com/v1/forecast",

200 params={

201 "latitude": args["latitude"],

202 "longitude": args["longitude"],

203 "hourly": "precipitation_probability",

204 "forecast_days": 1,

205 },

206 )

207 data = response.json()

208 chances = data["hourly"]["precipitation_probability"][:hours]

209

210 return {

211 "content": [

212 {

213 "type": "text",

214 "text": f"Next {hours} hours: {'%, '.join(map(str, chances))}%",

215 }

216 ]

217 }

218

219

220 # Rebuild the server with both tools in the array

221 weather_server = create_sdk_mcp_server(

222 name="weather",

223 version="1.0.0",

224 tools=[get_temperature, get_precipitation_chance],

225 )

226 ```

227

228 ```typescript TypeScript theme={null}

229 // Define a second tool for the same server

230 const getPrecipitationChance = tool(

231 "get_precipitation_chance",

232 "Get the hourly precipitation probability for a location",

233 {

234 latitude: z.number(),

235 longitude: z.number(),

236 hours: z

237 .number()

238 .int()

239 .min(1)

240 .max(24)

241 .default(12) // .default() makes the parameter optional

242 .describe("How many hours of forecast to return")

243 },

244 async (args) => {

245 const response = await fetch(

246 `https://api.open-meteo.com/v1/forecast?latitude=${args.latitude}&longitude=${args.longitude}&hourly=precipitation_probability&forecast_days=1`

247 );

248 const data: any = await response.json();

249 const chances = data.hourly.precipitation_probability.slice(0, args.hours);

250

251 return {

252 content: [{ type: "text", text: `Next ${args.hours} hours: ${chances.join("%, ")}%` }]

253 };

254 }

255 );

256

257 // Rebuild the server with both tools in the array

258 const weatherServer = createSdkMcpServer({

259 name: "weather",

260 version: "1.0.0",

261 tools: [getTemperature, getPrecipitationChance]

262 });

263 ```

264</CodeGroup>

265

266Cada ferramenta neste array consome espaço de janela de contexto a cada turno. Se você está definindo dezenas de ferramentas, veja [tool search](/pt/agent-sdk/tool-search) para carregá-las sob demanda em vez disso.

267

268### Adicionar anotações de ferramentas

269

270[Anotações de ferramentas](https://modelcontextprotocol.io/docs/concepts/tools#tool-annotations) são metadados opcionais descrevendo como uma ferramenta se comporta. Passe-as como o quinto argumento para o auxiliar `tool()` em TypeScript ou via o argumento de palavra-chave `annotations` para o decorador `@tool` em Python. Todos os campos de dica são Booleanos.

271

272| Campo | Padrão | Significado |

273| :---------------- | :------ | :------------------------------------------------------------------------------------------------------------------------------------ |

274| `readOnlyHint` | `false` | A ferramenta não modifica seu ambiente. Controla se a ferramenta pode ser chamada em paralelo com outras ferramentas somente leitura. |

275| `destructiveHint` | `true` | A ferramenta pode executar atualizações destrutivas. Apenas informativo. |

276| `idempotentHint` | `false` | Chamadas repetidas com os mesmos argumentos não têm efeito adicional. Apenas informativo. |

277| `openWorldHint` | `true` | A ferramenta alcança sistemas fora de seu processo. Apenas informativo. |

278

279Anotações são metadados, não imposição. Uma ferramenta marcada com `readOnlyHint: true` ainda pode escrever em disco se é isso que o manipulador faz. Mantenha a anotação precisa em relação ao manipulador.

280

281Este exemplo adiciona `readOnlyHint` à ferramenta `get_temperature` do [exemplo de ferramenta de clima](#weather-tool-example).

282

283<CodeGroup>

284 ```python Python theme={null}

285 from claude_agent_sdk import tool, ToolAnnotations

286

287

288 @tool(

289 "get_temperature",

290 "Get the current temperature at a location",

291 {"latitude": float, "longitude": float},

292 annotations=ToolAnnotations(

293 readOnlyHint=True

294 ), # Lets Claude batch this with other read-only calls

295 )

296 async def get_temperature(args):

297 return {"content": [{"type": "text", "text": "..."}]}

298 ```

299

300 ```typescript TypeScript theme={null}

301 tool(

302 "get_temperature",

303 "Get the current temperature at a location",

304 { latitude: z.number(), longitude: z.number() },

305 async (args) => ({ content: [{ type: "text", text: `...` }] }),

306 { annotations: { readOnlyHint: true } } // Lets Claude batch this with other read-only calls

307 );

308 ```

309</CodeGroup>

310

311Veja `ToolAnnotations` na referência [TypeScript](/pt/agent-sdk/typescript#toolannotations) ou [Python](/pt/agent-sdk/python#toolannotations).

312

313## Controlar acesso a ferramentas

314

315O [exemplo de ferramenta de clima](#weather-tool-example) registrou um servidor e listou ferramentas em `allowedTools`. Esta seção cobre como nomes de ferramentas são construídos e como escopar acesso quando você tem múltiplas ferramentas ou quer restringir integrados.

316

317### Formato de nome de ferramenta

318

319Quando ferramentas MCP são expostas a Claude, seus nomes seguem um formato específico:

320

321* Padrão: `mcp__{server_name}__{tool_name}`

322* Exemplo: Uma ferramenta nomeada `get_temperature` no servidor `weather` torna-se `mcp__weather__get_temperature`

323

324### Configurar ferramentas permitidas

325

326A opção `tools` e as listas de permitidas/não permitidas operam em camadas separadas. `tools` controla quais ferramentas integradas aparecem no contexto de Claude. As listas de ferramentas permitidas e não permitidas controlam se chamadas são aprovadas ou negadas uma vez que Claude tenta chamá-las.

327

328| Opção | Camada | Efeito |

329| :------------------------- | :-------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

330| `tools: ["Read", "Grep"]` | Disponibilidade | Apenas os integrados listados estão no contexto de Claude. Integrados não listados são removidos. Ferramentas MCP não são afetadas. |

331| `tools: []` | Disponibilidade | Todos os integrados são removidos. Claude pode usar apenas suas ferramentas MCP. |

332| ferramentas permitidas | Permissão | Ferramentas listadas executam sem um prompt de permissão. Ferramentas não listadas permanecem disponíveis; chamadas passam pelo [fluxo de permissão](/pt/agent-sdk/permissions). |

333| ferramentas não permitidas | Permissão | Cada chamada para uma ferramenta listada é negada. A ferramenta permanece no contexto de Claude, então Claude ainda pode tentar chamá-la antes da chamada ser rejeitada. |

334

335Para limitar quais integrados Claude pode usar, prefira `tools` em vez de ferramentas não permitidas. Omitir uma ferramenta de `tools` a remove do contexto para que Claude nunca tente; listá-la em `disallowedTools` (Python: `disallowed_tools`) bloqueia a chamada mas deixa a ferramenta visível, então Claude pode desperdiçar um turno tentando. Veja [Configurar permissões](/pt/agent-sdk/permissions) para a ordem de avaliação completa.

336

337## Tratar erros

338

339Como seu manipulador relata erros determina se o loop do agente continua ou para:

340

341| O que acontece | Resultado |

342| :-------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------- |

343| Manipulador lança uma exceção não capturada | Loop do agente para. Claude nunca vê o erro, e a chamada `query` falha. |

344| Manipulador captura o erro e retorna `isError: true` (TS) / `"is_error": True` (Python) | Loop do agente continua. Claude vê o erro como dados e pode tentar novamente, tentar uma ferramenta diferente ou explicar a falha. |

345

346O exemplo abaixo captura dois tipos de falhas dentro do manipulador em vez de deixá-las lançar. Um status HTTP não-200 é capturado da resposta e retornado como um resultado de erro. Um erro de rede ou JSON inválido é capturado pelo `try/except` (Python) ou `try/catch` (TypeScript) circundante e também retornado como um resultado de erro. Em ambos os casos o manipulador retorna normalmente e o loop do agente continua.

347

348<CodeGroup>

349 ```python Python theme={null}

350 import json

351 import httpx

352 from typing import Any

353

354

355 @tool(

356 "fetch_data",

357 "Fetch data from an API",

358 {"endpoint": str}, # Simple schema

359 )

360 async def fetch_data(args: dict[str, Any]) -> dict[str, Any]:

361 try:

362 async with httpx.AsyncClient() as client:

363 response = await client.get(args["endpoint"])

364 if response.status_code != 200:

365 # Return the failure as a tool result so Claude can react to it.

366 # is_error marks this as a failed call rather than odd-looking data.

367 return {

368 "content": [

369 {

370 "type": "text",

371 "text": f"API error: {response.status_code} {response.reason_phrase}",

372 }

373 ],

374 "is_error": True,

375 }

376

377 data = response.json()

378 return {"content": [{"type": "text", "text": json.dumps(data, indent=2)}]}

379 except Exception as e:

380 # Catching here keeps the agent loop alive. An uncaught exception

381 # would end the whole query() call.

382 return {

383 "content": [{"type": "text", "text": f"Failed to fetch data: {str(e)}"}],

384 "is_error": True,

385 }

386 ```

387

388 ```typescript TypeScript theme={null}

389 tool(

390 "fetch_data",

391 "Fetch data from an API",

392 {

393 endpoint: z.string().url().describe("API endpoint URL")

394 },

395 async (args) => {

396 try {

397 const response = await fetch(args.endpoint);

398

399 if (!response.ok) {

400 // Return the failure as a tool result so Claude can react to it.

401 // isError marks this as a failed call rather than odd-looking data.

402 return {

403 content: [

404 {

405 type: "text",

406 text: `API error: ${response.status} ${response.statusText}`

407 }

408 ],

409 isError: true

410 };

411 }

412

413 const data = await response.json();

414 return {

415 content: [

416 {

417 type: "text",

418 text: JSON.stringify(data, null, 2)

419 }

420 ]

421 };

422 } catch (error) {

423 // Catching here keeps the agent loop alive. An uncaught throw

424 // would end the whole query() call.

425 return {

426 content: [

427 {

428 type: "text",

429 text: `Failed to fetch data: ${error instanceof Error ? error.message : String(error)}`

430 }

431 ],

432 isError: true

433 };

434 }

435 }

436 );

437 ```

438</CodeGroup>

439

440## Retornar imagens e recursos

441

442O array `content` em um resultado de ferramenta aceita blocos `text`, `image` e `resource`. Você pode misturá-los na mesma resposta.

443

444### Imagens

445

446Um bloco de imagem carrega os bytes da imagem inline, codificados como base64. Não há campo de URL. Para retornar uma imagem que vive em uma URL, busque-a no manipulador, leia os bytes da resposta e codifique-os em base64 antes de retornar. O resultado é processado como entrada visual.

447

448| Campo | Tipo | Notas |

449| :--------- | :-------- | :------------------------------------------------------------------------------------- |

450| `type` | `"image"` | |

451| `data` | `string` | Bytes codificados em base64. Apenas base64 bruto, sem prefixo `data:image/...;base64,` |

452| `mimeType` | `string` | Obrigatório. Por exemplo `image/png`, `image/jpeg`, `image/webp`, `image/gif` |

453

454<CodeGroup>

455 ```python Python theme={null}

456 import base64

457 import httpx

458

459

460 # Define a tool that fetches an image from a URL and returns it to Claude

461 @tool("fetch_image", "Fetch an image from a URL and return it to Claude", {"url": str})

462 async def fetch_image(args):

463 async with httpx.AsyncClient() as client: # Fetch the image bytes

464 response = await client.get(args["url"])

465

466 return {

467 "content": [

468 {

469 "type": "image",

470 "data": base64.b64encode(response.content).decode(

471 "ascii"

472 ), # Base64-encode the raw bytes

473 "mimeType": response.headers.get(

474 "content-type", "image/png"

475 ), # Read MIME type from the response

476 }

477 ]

478 }

479 ```

480

481 ```typescript TypeScript theme={null}

482 tool(

483 "fetch_image",

484 "Fetch an image from a URL and return it to Claude",

485 {

486 url: z.string().url()

487 },

488 async (args) => {

489 const response = await fetch(args.url); // Fetch the image bytes

490 const buffer = Buffer.from(await response.arrayBuffer()); // Read into a Buffer for base64 encoding

491 const mimeType = response.headers.get("content-type") ?? "image/png";

492

493 return {

494 content: [

495 {

496 type: "image",

497 data: buffer.toString("base64"), // Base64-encode the raw bytes

498 mimeType

499 }

500 ]

501 };

502 }

503 );

504 ```

505</CodeGroup>

506

507### Recursos

508

509Um bloco de recurso incorpora um pedaço de conteúdo identificado por uma URI. A URI é um rótulo para Claude referenciar; o conteúdo real fica no campo `text` ou `blob` do bloco. Use isto quando sua ferramenta produz algo que faz sentido endereçar por nome depois, como um arquivo gerado ou um registro de um sistema externo.

510

511| Campo | Tipo | Notas |

512| :------------------ | :----------- | :---------------------------------------------------------- |

513| `type` | `"resource"` | |

514| `resource.uri` | `string` | Identificador para o conteúdo. Qualquer esquema de URI |

515| `resource.text` | `string` | O conteúdo, se for texto. Forneça isto ou `blob`, não ambos |

516| `resource.blob` | `string` | O conteúdo codificado em base64, se for binário |

517| `resource.mimeType` | `string` | Opcional |

518

519Este exemplo mostra um bloco de recurso retornado de dentro de um manipulador de ferramenta. A URI `file:///tmp/report.md` é um rótulo que Claude pode referenciar depois; o SDK não lê desse caminho.

520

521<CodeGroup>

522 ```typescript TypeScript theme={null}

523 return {

524 content: [

525 {

526 type: "resource",

527 resource: {

528 uri: "file:///tmp/report.md", // Label for Claude to reference, not a path the SDK reads

529 mimeType: "text/markdown",

530 text: "# Report\n..." // The actual content, inline

531 }

532 }

533 ]

534 };

535 ```

536

537 ```python Python theme={null}

538 return {

539 "content": [

540 {

541 "type": "resource",

542 "resource": {

543 "uri": "file:///tmp/report.md", # Label for Claude to reference, not a path the SDK reads

544 "mimeType": "text/markdown",

545 "text": "# Report\n...", # The actual content, inline

546 },

547 }

548 ]

549 }

550 ```

551</CodeGroup>

552

553Estas formas de bloco vêm do tipo MCP `CallToolResult`. Veja a [especificação MCP](https://modelcontextprotocol.io/specification/2025-06-18/server/tools#tool-result) para a definição completa.

554

555## Retornar dados estruturados

556

557`structuredContent` é um objeto JSON opcional no resultado, separado do array `content`. Use-o para retornar valores brutos que Claude pode ler como campos exatos em vez de analisá-los de uma string de texto ou imagem.

558

559Quando `structuredContent` é definido, Claude recebe o JSON mais quaisquer blocos de imagem ou recurso de `content`. Blocos de texto em `content` não são encaminhados, já que são assumidos duplicar os dados estruturados. O exemplo abaixo renderiza um gráfico como um bloco de imagem e retorna os pontos de dados por trás dele em `structuredContent` do mesmo manipulador.

560

561```typescript TypeScript theme={null}

562return {

563 content: [

564 {

565 type: "image",

566 data: chartPngBuffer.toString("base64"),

567 mimeType: "image/png"

568 }

569 ],

570 structuredContent: {

571 series: "temperature_2m",

572 unit: "fahrenheit",

573 points: [62.1, 63.4, 65.0, 64.2]

574 }

575};

576```

577

578<Note>

579 O decorador Python `@tool` encaminha apenas `content` e `is_error` do dict de retorno do manipulador. Para retornar `structuredContent` de Python, execute um [servidor MCP autônomo](/pt/agent-sdk/mcp) em vez de um servidor SDK em processo.

580</Note>

581

582## Exemplo: conversor de unidades

583

584Esta ferramenta converte valores entre unidades de comprimento, temperatura e peso. Um usuário pode perguntar "converter 100 quilômetros para milhas" ou "qual é 72°F em Celsius," e Claude escolhe o tipo de unidade certo e unidades da solicitação.

585

586Demonstra dois padrões:

587

588* **Esquemas de enum:** `unit_type` é restrito a um conjunto fixo de valores. Em TypeScript, use `z.enum()`. Em Python, o esquema dict não suporta enums, então o dict completo de JSON Schema é necessário.

589* **Tratamento de entrada não suportada:** quando um par de conversão não é encontrado, o manipulador retorna `isError: true` para que Claude possa dizer ao usuário o que deu errado em vez de tratar uma falha como um resultado normal.

590

591<CodeGroup>

592 ```python Python theme={null}

593 from typing import Any

594 from claude_agent_sdk import tool, create_sdk_mcp_server

595

596

597 # z.enum() in TypeScript becomes an "enum" constraint in JSON Schema.

598 # The dict schema has no equivalent, so full JSON Schema is required.

599 @tool(

600 "convert_units",

601 "Convert a value from one unit to another",

602 {

603 "type": "object",

604 "properties": {

605 "unit_type": {

606 "type": "string",

607 "enum": ["length", "temperature", "weight"],

608 "description": "Category of unit",

609 },

610 "from_unit": {

611 "type": "string",

612 "description": "Unit to convert from, e.g. kilometers, fahrenheit, pounds",

613 },

614 "to_unit": {"type": "string", "description": "Unit to convert to"},

615 "value": {"type": "number", "description": "Value to convert"},

616 },

617 "required": ["unit_type", "from_unit", "to_unit", "value"],

618 },

619 )

620 async def convert_units(args: dict[str, Any]) -> dict[str, Any]:

621 conversions = {

622 "length": {

623 "kilometers_to_miles": lambda v: v * 0.621371,

624 "miles_to_kilometers": lambda v: v * 1.60934,

625 "meters_to_feet": lambda v: v * 3.28084,

626 "feet_to_meters": lambda v: v * 0.3048,

627 },

628 "temperature": {

629 "celsius_to_fahrenheit": lambda v: (v * 9) / 5 + 32,

630 "fahrenheit_to_celsius": lambda v: (v - 32) * 5 / 9,

631 "celsius_to_kelvin": lambda v: v + 273.15,

632 "kelvin_to_celsius": lambda v: v - 273.15,

633 },

634 "weight": {

635 "kilograms_to_pounds": lambda v: v * 2.20462,

636 "pounds_to_kilograms": lambda v: v * 0.453592,

637 "grams_to_ounces": lambda v: v * 0.035274,

638 "ounces_to_grams": lambda v: v * 28.3495,

639 },

640 }

641

642 key = f"{args['from_unit']}_to_{args['to_unit']}"

643 fn = conversions.get(args["unit_type"], {}).get(key)

644

645 if not fn:

646 return {

647 "content": [

648 {

649 "type": "text",

650 "text": f"Unsupported conversion: {args['from_unit']} to {args['to_unit']}",

651 }

652 ],

653 "is_error": True,

654 }

655

656 result = fn(args["value"])

657 return {

658 "content": [

659 {

660 "type": "text",

661 "text": f"{args['value']} {args['from_unit']} = {result:.4f} {args['to_unit']}",

662 }

663 ]

664 }

665

666

667 converter_server = create_sdk_mcp_server(

668 name="converter",

669 version="1.0.0",

670 tools=[convert_units],

671 )

672 ```

673

674 ```typescript TypeScript theme={null}

675 import { tool, createSdkMcpServer } from "@anthropic-ai/claude-agent-sdk";

676 import { z } from "zod";

677

678 const convert = tool(

679 "convert_units",

680 "Convert a value from one unit to another",

681 {

682 unit_type: z.enum(["length", "temperature", "weight"]).describe("Category of unit"),

683 from_unit: z

684 .string()

685 .describe("Unit to convert from, e.g. kilometers, fahrenheit, pounds"),

686 to_unit: z.string().describe("Unit to convert to"),

687 value: z.number().describe("Value to convert")

688 },

689 async (args) => {

690 type Conversions = Record<string, Record<string, (v: number) => number>>;

691

692 const conversions: Conversions = {

693 length: {

694 kilometers_to_miles: (v) => v * 0.621371,

695 miles_to_kilometers: (v) => v * 1.60934,

696 meters_to_feet: (v) => v * 3.28084,

697 feet_to_meters: (v) => v * 0.3048

698 },

699 temperature: {

700 celsius_to_fahrenheit: (v) => (v * 9) / 5 + 32,

701 fahrenheit_to_celsius: (v) => ((v - 32) * 5) / 9,

702 celsius_to_kelvin: (v) => v + 273.15,

703 kelvin_to_celsius: (v) => v - 273.15

704 },

705 weight: {

706 kilograms_to_pounds: (v) => v * 2.20462,

707 pounds_to_kilograms: (v) => v * 0.453592,

708 grams_to_ounces: (v) => v * 0.035274,

709 ounces_to_grams: (v) => v * 28.3495

710 }

711 };

712

713 const key = `${args.from_unit}_to_${args.to_unit}`;

714 const fn = conversions[args.unit_type]?.[key];

715

716 if (!fn) {

717 return {

718 content: [

719 {

720 type: "text",

721 text: `Unsupported conversion: ${args.from_unit} to ${args.to_unit}`

722 }

723 ],

724 isError: true

725 };

726 }

727

728 const result = fn(args.value);

729 return {

730 content: [

731 {

732 type: "text",

733 text: `${args.value} ${args.from_unit} = ${result.toFixed(4)} ${args.to_unit}`

734 }

735 ]

736 };

737 }

738 );

739

740 const converterServer = createSdkMcpServer({

741 name: "converter",

742 version: "1.0.0",

743 tools: [convert]

744 });

745 ```

746</CodeGroup>

747

748Uma vez que o servidor é definido, passe-o para `query` da mesma forma que o exemplo de clima. Este exemplo envia três prompts diferentes em um loop para mostrar a mesma ferramenta tratando diferentes tipos de unidades. Para cada resposta, ele inspeciona objetos `AssistantMessage` (que contêm as chamadas de ferramenta que Claude fez durante esse turno) e imprime cada `ToolUseBlock` antes de imprimir o texto final de `ResultMessage`. Isto permite que você veja quando Claude está usando a ferramenta versus respondendo de seu próprio conhecimento.

749

750<CodeGroup>

751 ```python Python theme={null}

752 import asyncio

753 from claude_agent_sdk import (

754 query,

755 ClaudeAgentOptions,

756 ResultMessage,

757 AssistantMessage,

758 ToolUseBlock,

759 )

760

761

762 async def main():

763 options = ClaudeAgentOptions(

764 mcp_servers={"converter": converter_server},

765 allowed_tools=["mcp__converter__convert_units"],

766 )

767

768 prompts = [

769 "Convert 100 kilometers to miles.",

770 "What is 72°F in Celsius?",

771 "How many pounds is 5 kilograms?",

772 ]

773

774 for prompt in prompts:

775 async for message in query(prompt=prompt, options=options):

776 if isinstance(message, AssistantMessage):

777 for block in message.content:

778 if isinstance(block, ToolUseBlock):

779 print(f"[tool call] {block.name}({block.input})")

780 elif isinstance(message, ResultMessage) and message.subtype == "success":

781 print(f"Q: {prompt}\nA: {message.result}\n")

782

783

784 asyncio.run(main())

785 ```

786

787 ```typescript TypeScript theme={null}

788 import { query } from "@anthropic-ai/claude-agent-sdk";

789

790 const prompts = [

791 "Convert 100 kilometers to miles.",

792 "What is 72°F in Celsius?",

793 "How many pounds is 5 kilograms?"

794 ];

795

796 for (const prompt of prompts) {

797 for await (const message of query({

798 prompt,

799 options: {

800 mcpServers: { converter: converterServer },

801 allowedTools: ["mcp__converter__convert_units"]

802 }

803 })) {

804 if (message.type === "assistant") {

805 for (const block of message.message.content) {

806 if (block.type === "tool_use") {

807 console.log(`[tool call] ${block.name}`, block.input);

808 }

809 }

810 } else if (message.type === "result" && message.subtype === "success") {

811 console.log(`Q: ${prompt}\nA: ${message.result}\n`);

812 }

813 }

814 }

815 ```

816</CodeGroup>

817

818## Próximos passos

819

820Ferramentas personalizadas envolvem funções assíncronas em uma interface padrão. Você pode misturar os padrões nesta página no mesmo servidor: um único servidor pode conter uma ferramenta de banco de dados, uma ferramenta de gateway de API e um renderizador de imagem lado a lado.

821

822A partir daqui:

823

824* Se seu servidor crescer para dezenas de ferramentas, veja [tool search](/pt/agent-sdk/tool-search) para adiar o carregamento delas até Claude precisar delas.

825* Para conectar a servidores MCP externos (sistema de arquivos, GitHub, Slack) em vez de construir os seus próprios, veja [Conectar servidores MCP](/pt/agent-sdk/mcp).

826* Para controlar quais ferramentas executam automaticamente versus exigindo aprovação, veja [Configurar permissões](/pt/agent-sdk/permissions).

827

828## Documentação relacionada

829

830* [Referência do SDK TypeScript](/pt/agent-sdk/typescript)

831* [Referência do SDK Python](/pt/agent-sdk/python)

832* [Documentação MCP](https://modelcontextprotocol.io)

833* [Visão geral do SDK](/pt/agent-sdk/overview)

agent-sdk/python.md +46 −7

Details

757 allowed_tools: list[str] = field(default_factory=list)757 allowed_tools: list[str] = field(default_factory=list)

758 system_prompt: str | SystemPromptPreset | None = None758 system_prompt: str | SystemPromptPreset | None = None

759 mcp_servers: dict[str, McpServerConfig] | str | Path = field(default_factory=dict)759 mcp_servers: dict[str, McpServerConfig] | str | Path = field(default_factory=dict)

760 strict_mcp_config: bool = False

760 permission_mode: PermissionMode | None = None761 permission_mode: PermissionMode | None = None

761 continue_conversation: bool = False762 continue_conversation: bool = False

762 resume: str | None = None763 resume: str | None = None

781 hooks: dict[HookEvent, list[HookMatcher]] | None = None782 hooks: dict[HookEvent, list[HookMatcher]] | None = None

782 user: str | None = None783 user: str | None = None

783 include_partial_messages: bool = False784 include_partial_messages: bool = False

785 include_hook_events: bool = False

784 fork_session: bool = False786 fork_session: bool = False

785 agents: dict[str, AgentDefinition] | None = None787 agents: dict[str, AgentDefinition] | None = None

786 setting_sources: list[SettingSource] | None = None788 setting_sources: list[SettingSource] | None = None

788 plugins: list[SdkPluginConfig] = field(default_factory=list)790 plugins: list[SdkPluginConfig] = field(default_factory=list)

789 max_thinking_tokens: int | None = None # Deprecated: use thinking instead791 max_thinking_tokens: int | None = None # Deprecated: use thinking instead

790 thinking: ThinkingConfig | None = None792 thinking: ThinkingConfig | None = None

791 effort: Literal["low", "medium", "high", "max"] | None = None793 effort: Literal["low", "medium", "high", "xhigh", "max"] | None = None

792 enable_file_checkpointing: bool = False794 enable_file_checkpointing: bool = False

793 session_store: SessionStore | None = None795 session_store: SessionStore | None = None

794 session_store_flush: SessionStoreFlushMode = "batched"796 session_store_flush: SessionStoreFlushMode = "batched"

800| `allowed_tools` | `list[str]` | `[]` | Ferramentas para auto-aprovar sem solicitar. Isso não restringe Claude apenas a essas ferramentas; ferramentas não listadas caem através de `permission_mode` e `can_use_tool`. Use `disallowed_tools` para bloquear ferramentas. Veja [Permissions](/pt/agent-sdk/permissions#allow-and-deny-rules) |802| `allowed_tools` | `list[str]` | `[]` | Ferramentas para auto-aprovar sem solicitar. Isso não restringe Claude apenas a essas ferramentas; ferramentas não listadas caem através de `permission_mode` e `can_use_tool`. Use `disallowed_tools` para bloquear ferramentas. Veja [Permissions](/pt/agent-sdk/permissions#allow-and-deny-rules) |

801| `system_prompt` | `str \| SystemPromptPreset \| None` | `None` | Configuração de prompt do sistema. Passe uma string para prompt personalizado, ou use `{"type": "preset", "preset": "claude_code"}` para o prompt do sistema do Claude Code. Adicione `"append"` para estender o preset |803| `system_prompt` | `str \| SystemPromptPreset \| None` | `None` | Configuração de prompt do sistema. Passe uma string para prompt personalizado, ou use `{"type": "preset", "preset": "claude_code"}` para o prompt do sistema do Claude Code. Adicione `"append"` para estender o preset |

802| `mcp_servers` | `dict[str, McpServerConfig] \| str \| Path` | `{}` | Configurações de servidor MCP ou caminho para arquivo de configuração |804| `mcp_servers` | `dict[str, McpServerConfig] \| str \| Path` | `{}` | Configurações de servidor MCP ou caminho para arquivo de configuração |

805| `strict_mcp_config` | `bool` | `False` | Quando `True`, use apenas os servidores passados em `mcp_servers` e ignore o projeto `.mcp.json`, configurações do usuário e servidores MCP fornecidos por plugins. Mapeia para o sinalizador CLI `--strict-mcp-config` |

819| `env` | `dict[str, str]` | `{}` | Variáveis de ambiente mescladas no topo do ambiente de processo herdado. Veja [Environment variables](/pt/env-vars) para variáveis que o CLI subjacente lê |822| `env` | `dict[str, str]` | `{}` | Variáveis de ambiente mescladas no topo do ambiente de processo herdado. Veja [Environment variables](/pt/env-vars) para variáveis que o CLI subjacente lê, e [Handle slow or stalled API responses](#handle-slow-or-stalled-api-responses) para variáveis relacionadas a timeout |

820| `extra_args` | `dict[str, str \| None]` | `{}` | Argumentos CLI adicionais a passar diretamente para o CLI |823| `extra_args` | `dict[str, str \| None]` | `{}` | Argumentos CLI adicionais a passar diretamente para o CLI |

832| `setting_sources` | `list[SettingSource] \| None` | `None` (CLI defaults: all sources) | Controle quais configurações do sistema de arquivos carregar. Passe `[]` para desabilitar configurações de usuário, projeto e local. Configurações de política gerenciada carregam independentemente. Veja [Use Claude Code features](/pt/agent-sdk/claude-code-features#what-settingsources-does-not-control) |836| `setting_sources` | `list[SettingSource] \| None` | `None` (CLI defaults: all sources) | Controle quais configurações do sistema de arquivos carregar. Passe `[]` para desabilitar configurações de usuário, projeto e local. Configurações de política gerenciada carregam independentemente. Veja [Use Claude Code features](/pt/agent-sdk/claude-code-features#what-settingsources-does-not-control) |

836| `session_store` | [`SessionStore`](/pt/agent-sdk/session-storage#the-sessionstore-interface) ` \| None` | `None` | Espelhe transcrições de sessão para um backend externo para que qualquer host possa retomá-las. Veja [Persist sessions to external storage](/pt/agent-sdk/session-storage) |840| `session_store` | [`SessionStore`](/pt/agent-sdk/session-storage#the-sessionstore-interface) ` \| None` | `None` | Espelhe transcrições de sessão para um backend externo para que qualquer host possa retomá-las. Veja [Persist sessions to external storage](/pt/agent-sdk/session-storage) |

837| `session_store_flush` | `Literal["batched", "eager"]` | `"batched"` | Quando fazer flush das entradas de transcrição espelhadas para `session_store`. `"batched"` faz flush uma vez por turno ou quando o buffer enche; `"eager"` dispara um flush de fundo após cada frame. Ignorado quando `session_store` é `None` |841| `session_store_flush` | `Literal["batched", "eager"]` | `"batched"` | Quando fazer flush das entradas de transcrição espelhadas para `session_store`. `"batched"` faz flush uma vez por turno ou quando o buffer enche; `"eager"` dispara um flush de fundo após cada frame. Ignorado quando `session_store` é `None` |

838 842

843#### Lidar com respostas de API lentas ou travadas

844

845O subprocess CLI lê várias variáveis de ambiente que controlam timeouts de API e detecção de travamento. Passe-as através de `ClaudeAgentOptions.env`:

846

847```python theme={null}

848options = ClaudeAgentOptions(

849 env={

850 "API_TIMEOUT_MS": "120000",

851 "CLAUDE_CODE_MAX_RETRIES": "2",

852 "CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS": "120000",

853 },

854)

855```

856

857* `API_TIMEOUT_MS`: timeout por solicitação no cliente Anthropic, em milissegundos. Padrão `600000`. Aplica-se ao loop principal e a todos os subagentes.

858* `CLAUDE_CODE_MAX_RETRIES`: máximo de tentativas de API. Padrão `10`. Cada tentativa obtém sua própria janela `API_TIMEOUT_MS`, então o tempo de parede no pior caso é aproximadamente `API_TIMEOUT_MS × (CLAUDE_CODE_MAX_RETRIES + 1)` mais backoff.

859* `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS`: watchdog de travamento para subagentes lançados com `run_in_background`. Padrão `600000`. Redefine em cada evento de stream; em caso de travamento, aborta o subagente, marca a tarefa como falha e expõe o erro ao pai com qualquer resultado parcial. Não se aplica a subagentes síncronos.

860* `CLAUDE_ENABLE_STREAM_WATCHDOG=1` com `CLAUDE_STREAM_IDLE_TIMEOUT_MS`: aborta a solicitação quando os cabeçalhos chegaram mas o corpo da resposta para de fazer stream. Desativado por padrão. `CLAUDE_STREAM_IDLE_TIMEOUT_MS` padrão é `300000` e é fixado nesse mínimo. A solicitação abortada passa pelo caminho de tentativa normal.

861

839### `OutputFormat`862### `OutputFormat`

840 863

841Configuração para validação de saída estruturada. Passe isso como um `dict` para o campo `output_format` em `ClaudeAgentOptions`:864Configuração para validação de saída estruturada. Passe isso como um `dict` para o campo `output_format` em `ClaudeAgentOptions`:

1015 initialPrompt: str | None = None1038 initialPrompt: str | None = None

1016 maxTurns: int | None = None1039 maxTurns: int | None = None

1017 background: bool | None = None1040 background: bool | None = None

1018 effort: Literal["low", "medium", "high", "max"] | int | None = None1041 effort: Literal["low", "medium", "high", "xhigh", "max"] | int | None = None

1019 permissionMode: PermissionMode | None = None1042 permissionMode: PermissionMode | None = None

1020```1043```

1021 1044

1080class ToolPermissionContext:1103class ToolPermissionContext:

1081 signal: Any | None = None # Future: abort signal support1104 signal: Any | None = None # Future: abort signal support

1082 suggestions: list[PermissionUpdate] = field(default_factory=list)1105 suggestions: list[PermissionUpdate] = field(default_factory=list)

1106 blocked_path: str | None = None

1107 decision_reason: str | None = None

1108 title: str | None = None

1109 display_name: str | None = None

1110 description: str | None = None

1083```1111```

1084 1112

1086| :------------ | :----------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |1114| :---------------- | :----------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

1088| `suggestions` | `list[PermissionUpdate]` | Sugestões de atualização de permissão do CLI. Prompts Bash incluem uma sugestão com o destino `localSettings`, então retorná-la em `updated_permissions` escreve a regra em `.claude/settings.local.json` e persiste entre sessões. |1116| `suggestions` | `list[PermissionUpdate]` | Sugestões de atualização de permissão do CLI. Prompts Bash incluem uma sugestão com o destino `localSettings`, então retorná-la em `updated_permissions` escreve a regra em `.claude/settings.local.json` e persiste entre sessões. |

1089 1122

1090### `PermissionResult`1123### `PermissionResult`

1091 1124

1466 is_error: bool1499 is_error: bool

1467 num_turns: int1500 num_turns: int

1468 session_id: str1501 session_id: str

1502 stop_reason: str | None = None

1469 total_cost_usd: float | None = None1503 total_cost_usd: float | None = None

1470 usage: dict[str, Any] | None = None1504 usage: dict[str, Any] | None = None

1471 result: str | None = None1505 result: str | None = None

1472 stop_reason: str | None = None

1473 structured_output: Any = None1506 structured_output: Any = None

1474 model_usage: dict[str, Any] | None = None1507 model_usage: dict[str, Any] | None = None

1508 permission_denials: list[Any] | None = None

1509 deferred_tool_use: DeferredToolUse | None = None

1510 errors: list[str] | None = None

1511 api_error_status: int | None = None

1512 uuid: str | None = None

1475```1513```

1476 1514

1477O dict `usage` contém as seguintes chaves quando presentes:1515O dict `usage` contém as seguintes chaves quando presentes:

2128```python theme={null}2166```python theme={null}

2129class PreToolUseHookSpecificOutput(TypedDict):2167class PreToolUseHookSpecificOutput(TypedDict):

2130 hookEventName: Literal["PreToolUse"]2168 hookEventName: Literal["PreToolUse"]

2131 permissionDecision: NotRequired[Literal["allow", "deny", "ask"]]2169 permissionDecision: NotRequired[Literal["allow", "deny", "ask", "defer"]]

2132 permissionDecisionReason: NotRequired[str]2170 permissionDecisionReason: NotRequired[str]

2133 updatedInput: NotRequired[dict[str, Any]]2171 updatedInput: NotRequired[dict[str, Any]]

2134 additionalContext: NotRequired[str]2172 additionalContext: NotRequired[str]

2137class PostToolUseHookSpecificOutput(TypedDict):2175class PostToolUseHookSpecificOutput(TypedDict):

2138 hookEventName: Literal["PostToolUse"]2176 hookEventName: Literal["PostToolUse"]

2139 additionalContext: NotRequired[str]2177 additionalContext: NotRequired[str]

2178 updatedToolOutput: NotRequired[Any]

2140 updatedMCPToolOutput: NotRequired[Any]2179 updatedMCPToolOutput: NotRequired[Any]

2141 2180

2142 2181

agent-sdk/typescript.md +56 −7

Details

8 8

9<script src="/components/typescript-sdk-type-links.js" defer />9<script src="/components/typescript-sdk-type-links.js" defer />

10 10

~~11<Note>~~

12 **Experimente a nova interface V2 (prévia):** Uma interface simplificada com padrões `send()` e `stream()` agora está disponível, facilitando conversas multi-turno. [Saiba mais sobre a prévia do TypeScript V2](/pt/agent-sdk/typescript-v2-preview)

~~13</Note>~~

15## Instalação11## Instalação

16 12

17```bash theme={null}13```bash theme={null}

338| `env` | `Record<string, string \| undefined>` | `process.env` | Variáveis de ambiente. Veja [Variáveis de ambiente](/pt/env-vars) para variáveis que a CLI subjacente lê. Defina `CLAUDE_AGENT_SDK_CLIENT_APP` para identificar sua aplicação no cabeçalho User-Agent |334| `env` | `Record<string, string \| undefined>` | `process.env` | Variáveis de ambiente. Veja [Variáveis de ambiente](/pt/env-vars) para variáveis que a CLI subjacente lê, e [Handle slow or stalled API responses](#handle-slow-or-stalled-api-responses) para variáveis relacionadas a timeout. Defina `CLAUDE_AGENT_SDK_CLIENT_APP` para identificar sua aplicação no cabeçalho User-Agent |

341| `extraArgs` | `Record<string, string \| null>` | `{}` | Argumentos adicionais |337| `extraArgs` | `Record<string, string \| null>` | `{}` | Argumentos adicionais |

362| `sessionStore` | [`SessionStore`](/pt/agent-sdk/session-storage#the-sessionstore-interface) | `undefined` | Espelhar transcrições de sessão para um backend externo para que qualquer host possa retomá-las. Veja [Persist sessions to external storage](/pt/agent-sdk/session-storage) |358| `sessionStore` | [`SessionStore`](/pt/agent-sdk/session-storage#the-sessionstore-interface) | `undefined` | Espelhar transcrições de sessão para um backend externo para que qualquer host possa retomá-las. Veja [Persist sessions to external storage](/pt/agent-sdk/session-storage) |

359| `settings` | `string \| Settings` | `undefined` | Objeto de [configurações](/pt/settings) inline ou caminho para um arquivo de configurações. Popula a camada de configurações de flag na [ordem de precedência](/pt/settings#settings-precedence). Altere em tempo de execução com [`applyFlagSettings()`](#applyflagsettings) |

363| `settingSources` | [`SettingSource`](#settingsource)`[]` | Padrões da CLI (todas as fontes) | Controle quais configurações do sistema de arquivos carregar. Passe `[]` para desativar configurações de usuário, projeto e local. Configurações de política gerenciada carregam independentemente. Veja [Use Claude Code features](/pt/agent-sdk/claude-code-features#what-settingsources-does-not-control) |360| `settingSources` | [`SettingSource`](#settingsource)`[]` | Padrões da CLI (todas as fontes) | Controle quais configurações do sistema de arquivos carregar. Passe `[]` para desativar configurações de usuário, projeto e local. Configurações de política gerenciada carregam independentemente. Veja [Use Claude Code features](/pt/agent-sdk/claude-code-features#what-settingsources-does-not-control) |

364| `spawnClaudeCodeProcess` | `(options: SpawnOptions) => SpawnedProcess` | `undefined` | Função personalizada para gerar o processo Claude Code. Use para executar Claude Code em VMs, contêineres ou ambientes remotos |361| `spawnClaudeCodeProcess` | `(options: SpawnOptions) => SpawnedProcess` | `undefined` | Função personalizada para gerar o processo Claude Code. Use para executar Claude Code em VMs, contêineres ou ambientes remotos |

370| `tools` | `string[] \| { type: 'preset'; preset: 'claude_code' }` | `undefined` | Configuração de ferramenta. Passe um array de nomes de ferramentas ou use o preset para obter as ferramentas padrão do Claude Code |367| `tools` | `string[] \| { type: 'preset'; preset: 'claude_code' }` | `undefined` | Configuração de ferramenta. Passe um array de nomes de ferramentas ou use o preset para obter as ferramentas padrão do Claude Code |

371 368

369#### Lidar com respostas de API lentas ou travadas

370

371O subprocesso da CLI lê várias variáveis de ambiente que controlam timeouts de API e detecção de travamento. Passe-as através da opção `env`:

372

373```typescript theme={null}

374const result = query({

375 prompt: "Analyze this code",

376 options: {

377 env: {

378 ...process.env,

379 API_TIMEOUT_MS: "120000",

380 CLAUDE_CODE_MAX_RETRIES: "2",

381 CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS: "120000",

382 },

383 },

384});

385```

386

387* `API_TIMEOUT_MS`: timeout por solicitação no cliente Anthropic, em milissegundos. Padrão `600000`. Aplica-se ao loop principal e a todos os subagentes.

388* `CLAUDE_CODE_MAX_RETRIES`: máximo de tentativas de API. Padrão `10`. Cada tentativa obtém sua própria janela `API_TIMEOUT_MS`, então o tempo de parede no pior caso é aproximadamente `API_TIMEOUT_MS × (CLAUDE_CODE_MAX_RETRIES + 1)` mais backoff.

389* `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS`: watchdog de travamento para subagentes lançados com `run_in_background`. Padrão `600000`. Redefine em cada evento de stream; em caso de travamento, aborta o subagente, marca a tarefa como falhada e expõe o erro ao pai com qualquer resultado parcial. Não se aplica a subagentes síncronos.

390* `CLAUDE_ENABLE_STREAM_WATCHDOG=1` com `CLAUDE_STREAM_IDLE_TIMEOUT_MS`: aborta a solicitação quando os cabeçalhos chegaram mas o corpo da resposta para de fazer stream. Desativado por padrão. `CLAUDE_STREAM_IDLE_TIMEOUT_MS` padrão é `300000` e é fixado nesse mínimo. A solicitação abortada passa pelo caminho de tentativa normal.

391

372### Objeto `Query`392### Objeto `Query`

373 393

374Interface retornada pela função `query()`.394Interface retornada pela função `query()`.

383 setPermissionMode(mode: PermissionMode): Promise<void>;403 setPermissionMode(mode: PermissionMode): Promise<void>;

384 setModel(model?: string): Promise<void>;404 setModel(model?: string): Promise<void>;

385 setMaxThinkingTokens(maxThinkingTokens: number | null): Promise<void>;405 setMaxThinkingTokens(maxThinkingTokens: number | null): Promise<void>;

406 applyFlagSettings(settings: { [K in keyof Settings]?: Settings[K] | null }): Promise<void>;

386 initializationResult(): Promise<SDKControlInitializeResponse>;407 initializationResult(): Promise<SDKControlInitializeResponse>;

387 supportedCommands(): Promise<SlashCommand[]>;408 supportedCommands(): Promise<SlashCommand[]>;

388 supportedModels(): Promise<ModelInfo[]>;409 supportedModels(): Promise<ModelInfo[]>;

409| `setMaxThinkingTokens()` | *Descontinuado:* Use a opção `thinking` em vez disso. Altera os tokens de pensamento máximos |430| `setMaxThinkingTokens()` | *Descontinuado:* Use a opção `thinking` em vez disso. Altera os tokens de pensamento máximos |

431| `applyFlagSettings(settings)` | Mescla configurações na camada de configurações de flag da sessão em tempo de execução (apenas disponível em modo de entrada de transmissão). Veja [`applyFlagSettings()`](#applyflagsettings) |

410| `initializationResult()` | Retorna o resultado de inicialização completo incluindo comandos suportados, modelos, informações de conta e configuração de estilo de saída |432| `initializationResult()` | Retorna o resultado de inicialização completo incluindo comandos suportados, modelos, informações de conta e configuração de estilo de saída |

422 444

445#### `applyFlagSettings()`

446

447Altera qualquer [configuração](/pt/settings) em uma sessão em execução sem reiniciar a consulta. Use-a quando uma configuração que não tem um setter dedicado precisa mudar no meio da sessão, como apertar `permissions` depois que o agente lê entrada não confiável. `setModel()` e `setPermissionMode()` são setters dedicados para essas duas chaves; `applyFlagSettings()` é a forma geral que aceita qualquer subconjunto das chaves de configurações, e passar `model` aqui se comporta igual a `setModel()`.

448

449Os valores são escritos na camada de configurações de flag, a mesma camada que a opção `settings` inline de `query()` popula na inicialização. Configurações de flag ficam perto do topo da [ordem de precedência de configurações](/pt/settings#settings-precedence): elas substituem configurações de usuário, projeto e local, e apenas configurações de política gerenciada podem substituí-las. Esta é a mesma camada que a [seção de precedência na página](#settings-precedence) chama de opções programáticas.

450

451Chamadas sucessivas fazem shallow-merge de chaves de nível superior. Uma segunda chamada com `{ permissions: {...} }` substitui o objeto `permissions` inteiro da chamada anterior em vez de fazer deep-merge nele. Para limpar uma chave da camada de flag e voltar a fontes de precedência mais baixa, passe `null` para essa chave. Passar `undefined` não tem efeito porque a serialização JSON a descarta.

452

453Apenas disponível em modo de entrada de transmissão, a mesma restrição que `setModel()` e `setPermissionMode()`.

454

455O exemplo abaixo muda o modelo ativo no meio da sessão, depois limpa a substituição para que o modelo volte ao que as configurações de usuário ou projeto especificam.

456

457```typescript theme={null}

458const q = query({ prompt: messageStream });

459

460// Substituir o modelo para o resto da sessão

461await q.applyFlagSettings({ model: "claude-opus-4-6" });

462

463// Depois: limpar a substituição e voltar a configurações de precedência mais baixa

464await q.applyFlagSettings({ model: null });

465```

466

467<Note>

468 `applyFlagSettings()` é apenas TypeScript. O SDK Python não expõe um método equivalente.

469</Note>

470

423### `WarmQuery`471### `WarmQuery`

424 472

425Handle retornado por [`startup()`](#startup). O subprocesso já está gerado e inicializado, então chamar `query()` neste handle escreve o prompt diretamente em um processo pronto sem latência de inicialização.473Handle retornado por [`startup()`](#startup). O subprocesso já está gerado e inicializado, então chamar `query()` neste handle escreve o prompt diretamente em um processo pronto sem latência de inicialização.

6172. Configurações de projeto (`.claude/settings.json`)6652. Configurações de projeto (`.claude/settings.json`)

6183. Configurações do usuário (`~/.claude/settings.json`)6663. Configurações do usuário (`~/.claude/settings.json`)

619 667

620Opções programáticas como `agents` e `allowedTools` substituem configurações do sistema de arquivos de usuário, projeto e local. Configurações de política gerenciada têm precedência sobre opções programáticas.668Opções programáticas como `agents`, `allowedTools` e `settings` substituem configurações do sistema de arquivos de usuário, projeto e local. Configurações de política gerenciada têm precedência sobre opções programáticas.

621 669

622### `PermissionMode`670### `PermissionMode`

623 671

2443 2491

2444### `CallToolResult`2492### `CallToolResult`

2445 2493

2446Tipo de resultado de ferramenta MCP (de `@modelcontextprotocol/sdk/types.js`).2494Tipo de resultado de ferramenta MCP (de `@modelcontextprotocol/sdk/types.js`). `structuredContent` é um objeto JSON que pode ser retornado junto com `content`, incluindo blocos de imagem. Veja [Retornar dados estruturados](/pt/agent-sdk/custom-tools#return-structured-data).

2447 2495

2448```typescript theme={null}2496```typescript theme={null}

2449type CallToolResult = {2497type CallToolResult = {

2451 type: "text" | "image" | "resource";2499 type: "text" | "image" | "resource";

2452 // Campos adicionais variam por tipo2500 // Campos adicionais variam por tipo

2453 }>;2501 }>;

2502 structuredContent?: Record<string, unknown>;

2454 isError?: boolean;2503 isError?: boolean;

2455};2504};

2456```2505```

amazon-bedrock.md +11 −1

Details

361 361

362```bash theme={null}362```bash theme={null}

363# Usando ID de perfil de inferência363# Usando ID de perfil de inferência

364export ANTHROPIC_MODEL='global.anthropic.claude-sonnet-4-6'364export ANTHROPIC_MODEL='us.anthropic.claude-sonnet-4-6'

365export ANTHROPIC_DEFAULT_HAIKU_MODEL='us.anthropic.claude-haiku-4-5-20251001-v1:0'365export ANTHROPIC_DEFAULT_HAIKU_MODEL='us.anthropic.claude-haiku-4-5-20251001-v1:0'

366 366

367# Usando ARN de perfil de inferência de aplicação367# Usando ARN de perfil de inferência de aplicação

462 462

463O [assistente de configuração](#sign-in-with-bedrock) oferece uma opção de contexto de 1M quando fixa modelos. Para habilitá-lo para um modelo fixado manualmente em vez disso, acrescente `[1m]` ao ID do modelo. Veja [Fixar modelos para implantações de terceiros](/pt/model-config#pin-models-for-third-party-deployments) para detalhes.463O [assistente de configuração](#sign-in-with-bedrock) oferece uma opção de contexto de 1M quando fixa modelos. Para habilitá-lo para um modelo fixado manualmente em vez disso, acrescente `[1m]` ao ID do modelo. Veja [Fixar modelos para implantações de terceiros](/pt/model-config#pin-models-for-third-party-deployments) para detalhes.

464 464

465## Camadas de serviço

466

467[Camadas de serviço do Amazon Bedrock](https://docs.aws.amazon.com/bedrock/latest/userguide/service-tiers-inference.html) permitem que você negocie custo contra latência. Defina `ANTHROPIC_BEDROCK_SERVICE_TIER` como `default`, `flex` ou `priority`:

468

469```bash theme={null}

470export ANTHROPIC_BEDROCK_SERVICE_TIER=priority

471```

472

473Claude Code envia isso como o cabeçalho `X-Amzn-Bedrock-Service-Tier` em cada solicitação. A disponibilidade de camada varia por modelo e região. A capacidade reservada usa um [ARN de throughput provisionado](https://docs.aws.amazon.com/bedrock/latest/userguide/prov-throughput.html) como o ID do modelo em vez desta configuração.

474

465## AWS Guardrails475## AWS Guardrails

466 476

467[Amazon Bedrock Guardrails](https://docs.aws.amazon.com/bedrock/latest/userguide/guardrails.html) permitem que você implemente filtragem de conteúdo para Claude Code. Crie um Guardrail no [console do Amazon Bedrock](https://console.aws.amazon.com/bedrock/), publique uma versão, então adicione os cabeçalhos do Guardrail ao seu [arquivo de configurações](/pt/settings). Habilite inferência entre regiões em seu Guardrail se você estiver usando perfis de inferência entre regiões.477[Amazon Bedrock Guardrails](https://docs.aws.amazon.com/bedrock/latest/userguide/guardrails.html) permitem que você implemente filtragem de conteúdo para Claude Code. Crie um Guardrail no [console do Amazon Bedrock](https://console.aws.amazon.com/bedrock/), publique uma versão, então adicione os cabeçalhos do Guardrail ao seu [arquivo de configurações](/pt/settings). Habilite inferência entre regiões em seu Guardrail se você estiver usando perfis de inferência entre regiões.

authentication.md +6 −1

Details

113 113

114Claude Code gerencia com segurança suas credenciais de autenticação:114Claude Code gerencia com segurança suas credenciais de autenticação:

115 115

116* **Local de armazenamento**: no macOS, as credenciais são armazenadas no Keychain do macOS criptografado. No Linux e Windows, as credenciais são armazenadas em `~/.claude/.credentials.json`, ou sob `$CLAUDE_CONFIG_DIR` se essa variável estiver definida. No Linux, o arquivo é escrito com modo `0600`; no Windows, ele herda os controles de acesso do diretório do seu perfil de usuário.116* **Local de armazenamento**:

117 * No macOS, as credenciais são armazenadas no Keychain do macOS criptografado.

118 * No Linux, as credenciais são armazenadas em `~/.claude/.credentials.json` com modo de arquivo `0600`.

119 * No Windows, as credenciais são armazenadas em `%USERPROFILE%\.claude\.credentials.json` e herdam os controles de acesso do diretório do seu perfil de usuário, o que restringe o arquivo à sua conta de usuário por padrão.

120 * Se você definiu a variável de ambiente `CLAUDE_CONFIG_DIR` no Linux ou Windows, o arquivo `.credentials.json` fica sob esse diretório em vez disso.

121 * Claude Code gerencia `.credentials.json` através de `/login` e `/logout`. Para rotear solicitações através de um endpoint de API personalizado, defina a variável de ambiente [`ANTHROPIC_BASE_URL`](/pt/env-vars) em vez disso.

117* **Tipos de autenticação suportados**: credenciais Claude.ai, credenciais da API Claude, Azure Auth, Bedrock Auth e Vertex Auth.122* **Tipos de autenticação suportados**: credenciais Claude.ai, credenciais da API Claude, Azure Auth, Bedrock Auth e Vertex Auth.

118* **Scripts de credenciais personalizados**: a configuração [`apiKeyHelper`](/pt/settings#available-settings) pode ser configurada para executar um script de shell que retorna uma chave de API.123* **Scripts de credenciais personalizados**: a configuração [`apiKeyHelper`](/pt/settings#available-settings) pode ser configurada para executar um script de shell que retorna uma chave de API.

119* **Intervalos de atualização**: por padrão, `apiKeyHelper` é chamado após 5 minutos ou em resposta HTTP 401. Defina a variável de ambiente `CLAUDE_CODE_API_KEY_HELPER_TTL_MS` para intervalos de atualização personalizados.124* **Intervalos de atualização**: por padrão, `apiKeyHelper` é chamado após 5 minutos ou em resposta HTTP 401. Defina a variável de ambiente `CLAUDE_CODE_API_KEY_HELPER_TTL_MS` para intervalos de atualização personalizados.

claude-code-on-the-web.md +39 −4

Details

113 113

114Cada sessão em nuvem tem uma URL de transcrição em claude.ai, e a sessão pode ler seu próprio ID a partir da variável de ambiente `CLAUDE_CODE_REMOTE_SESSION_ID`. Use isso para colocar um link rastreável em corpos de PR, mensagens de commit, posts do Slack ou relatórios gerados para que um revisor possa abrir a execução que os produziu.114Cada sessão em nuvem tem uma URL de transcrição em claude.ai, e a sessão pode ler seu próprio ID a partir da variável de ambiente `CLAUDE_CODE_REMOTE_SESSION_ID`. Use isso para colocar um link rastreável em corpos de PR, mensagens de commit, posts do Slack ou relatórios gerados para que um revisor possa abrir a execução que os produziu.

115 115

116Peça a Claude para construir o link a partir da variável de ambiente. O seguinte comando imprime a URL:116O valor da variável usa um prefixo `cse_`, enquanto o caminho da URL de transcrição usa o mesmo ID com um prefixo `session_`. Substitua o prefixo ao construir o link. O seguinte comando imprime a URL:

117 117

118```bash theme={null}118```bash theme={null}

119echo "https://claude.ai/code/${CLAUDE_CODE_REMOTE_SESSION_ID}"119echo "https://claude.ai/code/${CLAUDE_CODE_REMOTE_SESSION_ID/#cse_/session_}"

120```120```

121 121

122### Execute testes, inicie serviços e adicione pacotes122### Execute testes, inicie serviços e adicione pacotes

156| Ação | Como |156| Ação | Como |

157| :------------------------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |157| :------------------------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

158| Adicione um ambiente | Selecione o ambiente atual para abrir o seletor, depois selecione **Add environment**. O diálogo inclui nome, nível de acesso à rede, variáveis de ambiente e script de configuração. |158| Adicione um ambiente | Selecione o ambiente atual para abrir o seletor, depois selecione **Add environment**. O diálogo inclui nome, nível de acesso à rede, variáveis de ambiente e script de configuração. |

159| Edite um ambiente | Selecione o ícone de configurações à direita do nome do ambiente. |159| Edite um ambiente | Selecione o ícone de nuvem mostrando o nome do ambiente atual para abrir o seletor, passe o mouse sobre um ambiente e clique no ícone de configurações que aparece à direita. |

160| Arquive um ambiente | Abra o ambiente para edição e selecione **Archive**. Ambientes arquivados ficam ocultos do seletor mas as sessões existentes continuam em execução. |160| Arquive um ambiente | Abra o ambiente para edição e selecione **Archive**. Ambientes arquivados ficam ocultos do seletor mas as sessões existentes continuam em execução. |

161| Defina o padrão para `--remote` | Execute `/remote-env` em seu terminal. Se você tiver um único ambiente, este comando mostra sua configuração atual. `/remote-env` apenas seleciona o padrão; adicione, edite e arquive ambientes a partir da interface web. |161| Defina o padrão para `--remote` | Execute `/remote-env` em seu terminal. Se você tiver um único ambiente, este comando mostra sua configuração atual. `/remote-env` apenas seleciona o padrão; adicione, edite e arquive ambientes a partir da interface web. |

162 162

185 185

186Se o script sair com código diferente de zero, a sessão falha ao iniciar. Acrescente `|| true` a comandos não críticos para evitar bloquear a sessão em uma falha de instalação intermitente.186Se o script sair com código diferente de zero, a sessão falha ao iniciar. Acrescente `|| true` a comandos não críticos para evitar bloquear a sessão em uma falha de instalação intermitente.

187 187

188Mantenha o tempo de execução total do script abaixo de aproximadamente cinco minutos para que o [cache de ambiente](#environment-caching) possa ser construído. Execute instalações independentes em paralelo com `&` e `wait`. Se um único download não se encaixar no limite de cinco minutos, mova-o para um [hook SessionStart](#setup-scripts-vs-sessionstart-hooks) que o inicia em segundo plano.

189

188<Note>190<Note>

189 Os scripts de configuração que instalam pacotes precisam de acesso à rede para alcançar registros. O acesso à rede padrão **Trusted** permite conexões com [domínios comuns permitidos](#default-allowed-domains) incluindo npm, PyPI, RubyGems e crates.io. Os scripts falharão ao instalar pacotes se seu ambiente usar acesso à rede **None**.191 Scripts de configuração que instalam pacotes precisam de acesso à rede para alcançar registros. O acesso à rede padrão **Trusted** permite conexões com [domínios comuns permitidos](#default-allowed-domains) incluindo npm, PyPI, RubyGems e crates.io. Os scripts falharão ao instalar pacotes se seu ambiente usar acesso à rede **None**.

190</Note>192</Note>

191 193

192### Armazenamento em cache de ambiente194### Armazenamento em cache de ambiente

265 267

266O acesso à rede controla conexões de saída do ambiente em nuvem. Cada ambiente especifica um nível de acesso, e você pode estendê-lo com domínios permitidos personalizados. O padrão é **Trusted**, que permite registros de pacotes e outros [domínios na lista de permissões](#default-allowed-domains).268O acesso à rede controla conexões de saída do ambiente em nuvem. Cada ambiente especifica um nível de acesso, e você pode estendê-lo com domínios permitidos personalizados. O padrão é **Trusted**, que permite registros de pacotes e outros [domínios na lista de permissões](#default-allowed-domains).

267 269

270Para alterar o acesso à rede de um ambiente, [abra-o para edição](#configure-your-environment) e use o seletor **Network access** no diálogo. Não há uma página Environments separada. O ícone de nuvem aparece em qualquer lugar que você inicie uma sessão em nuvem ou configure uma [routine](/pt/routines#environments-and-network-access).

271

272<Note>

273 O tráfego do conector MCP é roteado através dos servidores da Anthropic, então os conectores que você habilita em uma sessão ou routine funcionam sem adicionar seus hosts aos **Allowed domains**. Os conectores são configurados por sessão ou por routine; remova qualquer um que você não precise para limitar quais ferramentas Claude pode alcançar. Isso depende do mesmo canal vinculado à Anthropic observado em [Segurança e isolamento](#security-and-isolation).

274</Note>

275

268### Níveis de acesso276### Níveis de acesso

269 277

270Escolha um nível de acesso quando você criar ou editar um ambiente:278Escolha um nível de acesso quando você criar ou editar um ambiente:

754* **Proteção de credenciais**: credenciais sensíveis como credenciais git ou chaves de assinatura nunca estão dentro da sandbox com Claude Code. A autenticação é tratada através de um proxy seguro usando credenciais com escopo.762* **Proteção de credenciais**: credenciais sensíveis como credenciais git ou chaves de assinatura nunca estão dentro da sandbox com Claude Code. A autenticação é tratada através de um proxy seguro usando credenciais com escopo.

755* **Análise segura**: o código é analisado e modificado dentro de VMs isoladas antes de criar PRs763* **Análise segura**: o código é analisado e modificado dentro de VMs isoladas antes de criar PRs

756 764

765## Troubleshooting

766

767Para erros de API de tempo de execução que aparecem na conversa como `API Error: 500`, `529 Overloaded`, `429` ou `Prompt is too long`, veja a [referência de erros](/pt/errors). Esses erros e suas correções são compartilhados com o CLI e aplicativo Desktop. As seções abaixo cobrem problemas específicos para sessões em nuvem.

768

769### Session creation failed

770

771Se uma nova sessão falha ao iniciar com `Session creation failed` ou fica presa em provisioning, Claude Code não conseguiu alocar um ambiente em nuvem.

772

773* Verifique [status.claude.com](https://status.claude.com) para incidentes de sessão em nuvem

774* Tente novamente após um minuto, já que a capacidade é provisionada sob demanda

775* Confirme que seu repositório é acessível. Repositórios privados requerem o GitHub App instalado com acesso a esse repositório, ou um token `gh` sincronizado via `/web-setup`. Veja [Opções de autenticação do GitHub](#github-authentication-options).

776

777### Remote Control session expired or access denied

778

779`--teleport` se conecta através da mesma infraestrutura de sessão Remote Control que as sessões em nuvem usam, então erros de autenticação e expiração de sessão aparecem com wording de Remote Control. Você pode ver `Remote Control session has expired` ou `Access denied`. O token de conexão é de curta duração e limitado à sua conta.

780

781* Execute `/login` localmente para atualizar suas credenciais, depois reconecte

782* Confirme que você está conectado à mesma conta que possui a sessão

783* Se você ver `Remote Control may not be available for this organization`, seu admin não habilitou sessões remotas para seu plano

784

785### Environment expired

786

787As sessões em nuvem param após um período de inatividade e o ambiente subjacente é recuperado. A partir de um terminal local, isso aparece como `Could not resume session ... its environment has expired. Creating a fresh session instead.` Na web, a sessão é marcada como expirada na lista de sessões.

788

789Reabra a sessão de [claude.ai/code](https://claude.ai/code) para provisionar um ambiente fresco com seu histórico de conversa restaurado.

790

757## Limitações791## Limitações

758 792

759Antes de confiar em sessões em nuvem para um fluxo de trabalho, leve em conta essas restrições:793Antes de confiar em sessões em nuvem para um fluxo de trabalho, leve em conta essas restrições:

761* **Limites de taxa**: Claude Code na web compartilha limites de taxa com todo o outro uso de Claude e Claude Code dentro de sua conta. Executar múltiplas tarefas em paralelo consome mais limites de taxa proporcionalmente. Não há cobrança de computação separada para a VM em nuvem.795* **Limites de taxa**: Claude Code na web compartilha limites de taxa com todo o outro uso de Claude e Claude Code dentro de sua conta. Executar múltiplas tarefas em paralelo consome mais limites de taxa proporcionalmente. Não há cobrança de computação separada para a VM em nuvem.

762* **Autenticação de repositório**: você pode apenas mover sessões de web para local quando está autenticado na mesma conta796* **Autenticação de repositório**: você pode apenas mover sessões de web para local quando está autenticado na mesma conta

763* **Restrições de plataforma**: clonagem de repositório e criação de pull request requerem GitHub. Instâncias [GitHub Enterprise Server](/pt/github-enterprise-server) auto-hospedadas são suportadas para planos Team e Enterprise. GitLab, Bitbucket e outros repositórios não-GitHub podem ser enviados para sessões em nuvem como um [pacote local](#send-local-repositories-without-github), mas a sessão não pode enviar resultados de volta para o remoto797* **Restrições de plataforma**: clonagem de repositório e criação de pull request requerem GitHub. Instâncias [GitHub Enterprise Server](/pt/github-enterprise-server) auto-hospedadas são suportadas para planos Team e Enterprise. GitLab, Bitbucket e outros repositórios não-GitHub podem ser enviados para sessões em nuvem como um [pacote local](#send-local-repositories-without-github), mas a sessão não pode enviar resultados de volta para o remoto

798* **IP allowlist da organização**: as sessões em nuvem chamam a API Anthropic a partir de infraestrutura gerenciada pela Anthropic, não de sua rede. Se sua organização tem [IP allowlisting](https://support.claude.com/en/articles/13200993-restrict-access-to-claude-with-ip-allowlisting) habilitado, cada sessão em nuvem falha com um erro de autenticação. O mesmo se aplica a [Code Review](/pt/code-review) e [Routines](/pt/routines). Entre em contato com [suporte Anthropic](https://support.claude.com/) para isentar serviços hospedados pela Anthropic do allowlist de IP de sua organização.

764 799

765## Recursos relacionados800## Recursos relacionados

766 801

cli-reference.md +10 −9

Details

41 41

43| :---------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------- |43| :---------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------- |

44| `--add-dir` | Adicionar diretórios de trabalho adicionais para Claude ler e editar arquivos. Concede acesso a arquivos; a maioria da configuração `.claude/` [não é descoberta](/pt/permissions#additional-directories-grant-file-access-not-configuration) desses diretórios. Valida se cada caminho existe como um diretório | `claude --add-dir ../apps ../lib` |44| `--add-dir` | Adicionar diretórios de trabalho adicionais para Claude ler e editar arquivos. Concede acesso a arquivos; a maioria da configuração `.claude/` [não é descoberta](/pt/permissions#additional-directories-grant-file-access-not-configuration) desses diretórios. Valida se cada caminho existe como um diretório. Para persistir esses diretórios entre sessões, defina [`permissions.additionalDirectories`](/pt/settings#permission-settings) nas configurações | `claude --add-dir ../apps ../lib` |

46| `--agents` | Definir subagents personalizados dinamicamente via JSON. Usa os mesmos nomes de campo que o [frontmatter](/pt/sub-agents#supported-frontmatter-fields) de subagent, mais um campo `prompt` para as instruções do agente | `claude --agents '{"reviewer":{"description":"Reviews code","prompt":"You are a code reviewer"}}'` |46| `--agents` | Definir subagents personalizados dinamicamente via JSON. Usa os mesmos nomes de campo que o [frontmatter](/pt/sub-agents#supported-frontmatter-fields) de subagent, mais um campo `prompt` para as instruções do agente | `claude --agents '{"reviewer":{"description":"Reviews code","prompt":"You are a code reviewer"}}'` |

47| `--allow-dangerously-skip-permissions` | Adicionar `bypassPermissions` ao ciclo de modo `Shift+Tab` sem iniciar nele. Permite começar em um modo diferente como `plan` e mudar para `bypassPermissions` depois. Veja [modos de permissão](/pt/permission-modes#skip-all-checks-with-bypasspermissions-mode) | `claude --permission-mode plan --allow-dangerously-skip-permissions` |47| `--allow-dangerously-skip-permissions` | Adicionar `bypassPermissions` ao ciclo de modo `Shift+Tab` sem iniciar nele. Permite começar em um modo diferente como `plan` e mudar para `bypassPermissions` depois. Veja [modos de permissão](/pt/permission-modes#skip-all-checks-with-bypasspermissions-mode) | `claude --permission-mode plan --allow-dangerously-skip-permissions` |

59| `--debug-file <path>` | Escrever logs de depuração em um caminho de arquivo específico. Ativa implicitamente o modo de depuração. Tem precedência sobre `CLAUDE_CODE_DEBUG_LOGS_DIR` | `claude --debug-file /tmp/claude-debug.log` |59| `--debug-file <path>` | Escrever logs de depuração em um caminho de arquivo específico. Ativa implicitamente o modo de depuração. Tem precedência sobre `CLAUDE_CODE_DEBUG_LOGS_DIR` | `claude --debug-file /tmp/claude-debug.log` |

62| `--effort` | Definir o [nível de esforço](/pt/model-config#adjust-effort-level) para a sessão atual. Opções: `low`, `medium`, `high`, `xhigh`, `max`; os níveis disponíveis dependem do modelo. Escopo de sessão e não persiste nas configurações | `claude --effort high` |62| `--effort` | Definir o [nível de esforço](/pt/model-config#adjust-effort-level) para a sessão atual. Opções: `low`, `medium`, `high`, `xhigh`, `max`; os níveis disponíveis dependem do modelo. Substitui a configuração [`effortLevel`](/pt/settings#available-settings) para esta sessão e não persiste | `claude --effort high` |

63| `--enable-auto-mode` | {/* max-version: 2.1.110 */}Removido em v2.1.111. Auto mode agora está no ciclo `Shift+Tab` por padrão; use `--permission-mode auto` para iniciar nele | `claude --permission-mode auto` |63| `--enable-auto-mode` | {/* max-version: 2.1.110 */}Removido em v2.1.111. Auto mode agora está no ciclo `Shift+Tab` por padrão; use `--permission-mode auto` para iniciar nele | `claude --permission-mode auto` |

64| `--exclude-dynamic-system-prompt-sections` | Mover seções por máquina do prompt do sistema (diretório de trabalho, informações de ambiente, caminhos de memória, status do git) para a primeira mensagem do usuário. Melhora a reutilização de prompt-cache em diferentes usuários e máquinas executando a mesma tarefa. Aplica-se apenas com o prompt do sistema padrão; ignorado quando `--system-prompt` ou `--system-prompt-file` está definido. Use com `-p` para cargas de trabalho com script e multi-usuário | `claude -p --exclude-dynamic-system-prompt-sections "query"` |64| `--exclude-dynamic-system-prompt-sections` | Mover seções por máquina do prompt do sistema (diretório de trabalho, informações de ambiente, caminhos de memória, status do git) para a primeira mensagem do usuário. Melhora a reutilização de prompt-cache em diferentes usuários e máquinas executando a mesma tarefa. Aplica-se apenas com o prompt do sistema padrão; ignorado quando `--system-prompt` ou `--system-prompt-file` está definido. Use com `-p` para cargas de trabalho com script e multi-usuário | `claude -p --exclude-dynamic-system-prompt-sections "query"` |

65| `--fallback-model` | Ativar fallback automático para modelo especificado quando o modelo padrão está sobrecarregado (apenas modo print) | `claude -p --fallback-model sonnet "query"` |65| `--fallback-model` | Ativar fallback automático para modelo especificado quando o modelo padrão está sobrecarregado (apenas modo print) | `claude -p --fallback-model sonnet "query"` |

77| `--max-turns` | Limitar o número de turnos de agente (apenas modo print). Sai com um erro quando o limite é atingido. Sem limite por padrão | `claude -p --max-turns 3 "query"` |77| `--max-turns` | Limitar o número de turnos de agente (apenas modo print). Sai com um erro quando o limite é atingido. Sem limite por padrão | `claude -p --max-turns 3 "query"` |

79| `--model` | Define o modelo para a sessão atual com um alias para o modelo mais recente (`sonnet` ou `opus`) ou o nome completo de um modelo | `claude --model claude-sonnet-4-6` |79| `--model` | Define o modelo para a sessão atual com um alias para o modelo mais recente (`sonnet` ou `opus`) ou o nome completo de um modelo. Substitui a configuração [`model`](/pt/settings#available-settings) e [`ANTHROPIC_MODEL`](/pt/model-config#environment-variables) | `claude --model claude-sonnet-4-6` |

80| `--name`, `-n` | Definir um nome de exibição para a sessão, mostrado em `/resume` e no título do terminal. Você pode retomar uma sessão nomeada com `claude --resume <name>`. <br /><br />[`/rename`](/pt/commands) altera o nome durante a sessão e também o mostra na barra de prompt | `claude -n "my-feature-work"` |80| `--name`, `-n` | Definir um nome de exibição para a sessão, mostrado em `/resume` e no título do terminal. Você pode retomar uma sessão nomeada com `claude --resume <name>`. <br /><br />[`/rename`](/pt/commands) altera o nome durante a sessão e também o mostra na barra de prompt | `claude -n "my-feature-work"` |

82| `--no-session-persistence` | Desativar persistência de sessão para que as sessões não sejam salvas em disco e não possam ser retomadas (apenas modo print) | `claude -p --no-session-persistence "query"` |82| `--no-session-persistence` | Desativar persistência de sessão para que as sessões não sejam salvas em disco e não possam ser retomadas. Apenas modo print. A variável de ambiente [`CLAUDE_CODE_SKIP_PROMPT_HISTORY`](/pt/env-vars) faz o mesmo em qualquer modo | `claude -p --no-session-persistence "query"` |

84| `--permission-mode` | Começar em um [modo de permissão](/pt/permission-modes) especificado. Aceita `default`, `acceptEdits`, `plan`, `auto`, `dontAsk` ou `bypassPermissions`. Substitui `defaultMode` dos arquivos de configuração | `claude --permission-mode plan` |84| `--permission-mode` | Começar em um [modo de permissão](/pt/permission-modes) especificado. Aceita `default`, `acceptEdits`, `plan`, `auto`, `dontAsk` ou `bypassPermissions`. Substitui `defaultMode` dos arquivos de configuração | `claude --permission-mode plan` |

85| `--permission-prompt-tool` | Especificar uma ferramenta MCP para lidar com prompts de permissão em modo não interativo | `claude -p --permission-prompt-tool mcp_auth_tool "query"` |85| `--permission-prompt-tool` | Especificar uma ferramenta MCP para lidar com prompts de permissão em modo não interativo | `claude -p --permission-prompt-tool mcp_auth_tool "query"` |

86| `--plugin-dir` | Carregar plugins de um diretório apenas para esta sessão. Cada sinalizador leva um caminho. Repita o sinalizador para vários diretórios: `--plugin-dir A --plugin-dir B` | `claude --plugin-dir ./my-plugins` |86| `--plugin-dir` | Carregar um plugin de um diretório ou arquivo `.zip` apenas para esta sessão. Cada sinalizador leva um caminho. Repita o sinalizador para vários plugins: `--plugin-dir A --plugin-dir B.zip` | `claude --plugin-dir ./my-plugin` |

87| `--plugin-url` | Buscar um arquivo `.zip` de plugin de uma URL apenas para esta sessão. Cada sinalizador leva uma URL. Repita o sinalizador para vários plugins | `claude --plugin-url https://example.com/plugin.zip` |

87| `--print`, `-p` | Imprimir resposta sem modo interativo (veja [documentação do Agent SDK](/pt/agent-sdk/overview) para detalhes de uso programático) | `claude -p "query"` |88| `--print`, `-p` | Imprimir resposta sem modo interativo (veja [documentação do Agent SDK](/pt/agent-sdk/overview) para detalhes de uso programático) | `claude -p "query"` |

89| `--remote-control`, `--rc` | Iniciar uma sessão interativa com [Remote Control](/pt/remote-control#start-a-remote-control-session) ativado para que você também possa controlá-la a partir de claude.ai ou do aplicativo Claude. Opcionalmente, passe um nome para a sessão | `claude --remote-control "My Project"` |90| `--remote-control`, `--rc` | Iniciar uma sessão interativa com [Remote Control](/pt/remote-control#start-a-remote-control-session) ativado para que você também possa controlá-la a partir de claude.ai ou do aplicativo Claude. Opcionalmente, passe um nome para a sessão | `claude --remote-control "My Project"` |

92| `--resume`, `-r` | Retomar uma sessão específica por ID ou nome, ou mostrar um seletor interativo para escolher uma sessão. Inclui sessões que adicionaram este diretório com `/add-dir` | `claude --resume auth-refactor` |93| `--resume`, `-r` | Retomar uma sessão específica por ID ou nome, ou mostrar um seletor interativo para escolher uma sessão. Inclui sessões que adicionaram este diretório com `/add-dir` | `claude --resume auth-refactor` |

95| `--settings` | Caminho para um arquivo JSON de configurações ou uma string JSON para carregar configurações adicionais | `claude --settings ./settings.json` |96| `--settings` | Caminho para um arquivo JSON de configurações ou uma string JSON para carregar configurações adicionais. Os valores que você define aqui substituem as mesmas chaves em seus arquivos `settings.json` para esta sessão. As chaves que você omite mantêm seus valores baseados em arquivo. Veja [precedência de configurações](/pt/settings#settings-precedence) | `claude --settings ./settings.json` |

96| `--strict-mcp-config` | Usar apenas servidores MCP de `--mcp-config`, ignorando todas as outras configurações de MCP | `claude --strict-mcp-config --mcp-config ./mcp.json` |97| `--strict-mcp-config` | Usar apenas servidores MCP de `--mcp-config`, ignorando todas as outras configurações de MCP | `claude --strict-mcp-config --mcp-config ./mcp.json` |

100| `--teammate-mode` | Definir como [equipe de agentes](/pt/agent-teams) colegas de equipe são exibidos: `auto` (padrão), `in-process` ou `tmux`. Veja [Escolher um modo de exibição](/pt/agent-teams#choose-a-display-mode) | `claude --teammate-mode in-process` |101| `--teammate-mode` | Definir como [equipe de agentes](/pt/agent-teams) colegas de equipe são exibidos: `auto` (padrão), `in-process` ou `tmux`. Substitui a configuração [`teammateMode`](/pt/settings#available-settings) para esta sessão. Veja [Escolher um modo de exibição](/pt/agent-teams#choose-a-display-mode) | `claude --teammate-mode in-process` |

101| `--tmux` | Criar uma sessão tmux para o worktree. Requer `--worktree`. Usa painéis nativos do iTerm2 quando disponível; passe `--tmux=classic` para tmux tradicional | `claude -w feature-auth --tmux` |102| `--tmux` | Criar uma sessão tmux para o worktree. Requer `--worktree`. Usa painéis nativos do iTerm2 quando disponível; passe `--tmux=classic` para tmux tradicional | `claude -w feature-auth --tmux` |

102| `--tools` | Restringir quais ferramentas integradas Claude pode usar. Use `""` para desativar todas, `"default"` para todas, ou nomes de ferramentas como `"Bash,Edit,Read"` | `claude --tools "Bash,Edit,Read"` |103| `--tools` | Restringir quais ferramentas integradas Claude pode usar. Use `""` para desativar todas, `"default"` para todas, ou nomes de ferramentas como `"Bash,Edit,Read"` | `claude --tools "Bash,Edit,Read"` |

105| `--worktree`, `-w` | Iniciar Claude em um [git worktree](/pt/common-workflows#run-parallel-claude-code-sessions-with-git-worktrees) isolado em `<repo>/.claude/worktrees/<name>`. Se nenhum nome for fornecido, um será gerado automaticamente | `claude -w feature-auth` |106| `--worktree`, `-w` | Iniciar Claude em um [git worktree](/pt/worktrees) isolado em `<repo>/.claude/worktrees/<name>`. Se nenhum nome for fornecido, um será gerado automaticamente | `claude -w feature-auth` |

106 107

107### Sinalizadores de prompt do sistema108### Sinalizadores de prompt do sistema

108 109

commands.md +7 −5

Details

10 10

11Digite `/` para ver todos os comandos disponíveis para você, ou digite `/` seguido de letras para filtrar.11Digite `/` para ver todos os comandos disponíveis para você, ou digite `/` seguido de letras para filtrar.

12 12

13Um comando é reconhecido apenas no início da sua mensagem. O texto que segue o nome do comando é passado para ele como argumentos.

13A tabela abaixo lista todos os comandos incluídos no Claude Code. As entradas marcadas como **[Skill](/pt/skills#bundled-skills)** são skills agrupadas. Elas usam o mesmo mecanismo que as skills que você escreve: um prompt entregue ao Claude, que Claude também pode invocar automaticamente quando relevante. Tudo o mais é um comando integrado cujo comportamento é codificado na CLI. Para adicionar seus próprios comandos, consulte [skills](/pt/skills).15A tabela abaixo lista todos os comandos incluídos no Claude Code. As entradas marcadas como **[Skill](/pt/skills#bundled-skills)** são skills agrupadas. Elas usam o mesmo mecanismo que as skills que você escreve: um prompt entregue ao Claude, que Claude também pode invocar automaticamente quando relevante. Tudo o mais é um comando integrado cujo comportamento é codificado na CLI. Para adicionar seus próprios comandos, consulte [skills](/pt/skills).

14 16

15Nem todo comando aparece para todos os usuários. A disponibilidade depende da sua plataforma, plano e ambiente. Por exemplo, `/desktop` aparece apenas no macOS e Windows, e `/upgrade` aparece apenas nos planos Pro e Max.17Nem todo comando aparece para todos os usuários. A disponibilidade depende da sua plataforma, plano e ambiente. Por exemplo, `/desktop` aparece apenas no macOS e Windows, e `/upgrade` aparece apenas nos planos Pro e Max.

21| `/add-dir <path>` | Adicionar um diretório de trabalho para acesso a arquivos durante a sessão atual. A maioria da configuração `.claude/` [não é descoberta](/pt/permissions#additional-directories-grant-file-access-not-configuration) do diretório adicionado. Você pode retomar a sessão posteriormente do diretório adicionado com `--continue` ou `--resume` |23| `/add-dir <path>` | Adicionar um diretório de trabalho para acesso a arquivos durante a sessão atual. A maioria da configuração `.claude/` [não é descoberta](/pt/permissions#additional-directories-grant-file-access-not-configuration) do diretório adicionado. Você pode retomar a sessão posteriormente do diretório adicionado com `--continue` ou `--resume` |

23| `/autofix-pr [prompt]` | Gerar uma sessão [Claude Code na web](/pt/claude-code-on-the-web#auto-fix-pull-requests) que monitora o PR do branch atual e envia correções quando o CI falha ou revisores deixam comentários. Detecta o PR aberto do seu branch verificado com `gh pr view`; para monitorar um PR diferente, primeiro verifique seu branch. Por padrão, a sessão remota é instruída a corrigir todas as falhas de CI e comentários de revisão; passe um prompt para dar instruções diferentes, por exemplo `/autofix-pr only fix lint and type errors`. Requer a CLI `gh` e acesso a [Claude Code na web](/pt/claude-code-on-the-web#who-can-use-claude-code-on-the-web) |25| `/autofix-pr [prompt]` | Gerar uma sessão [Claude Code na web](/pt/claude-code-on-the-web#auto-fix-pull-requests) que monitora o PR do branch atual e envia correções quando o CI falha ou revisores deixam comentários. Detecta o PR aberto do seu branch verificado com `gh pr view`; para monitorar um PR diferente, primeiro verifique seu branch. Por padrão, a sessão remota é instruída a corrigir todas as falhas de CI e comentários de revisão; passe um prompt para dar instruções diferentes, por exemplo `/autofix-pr only fix lint and type errors`. Requer a CLI `gh` e acesso a [Claude Code na web](/pt/claude-code-on-the-web#who-can-use-claude-code-on-the-web) |

24| `/batch <instruction>` | **[Skill](/pt/skills#bundled-skills).** Orquestrar mudanças em larga escala em um codebase em paralelo. Pesquisa o codebase, decompõe o trabalho em 5 a 30 unidades independentes e apresenta um plano. Uma vez aprovado, gera um agente de fundo por unidade em um [git worktree](/pt/common-workflows#run-parallel-claude-code-sessions-with-git-worktrees) isolado. Cada agente implementa sua unidade, executa testes e abre uma solicitação de pull. Requer um repositório git. Exemplo: `/batch migrate src/ from Solid to React` |26| `/batch <instruction>` | **[Skill](/pt/skills#bundled-skills).** Orquestrar mudanças em larga escala em um codebase em paralelo. Pesquisa o codebase, decompõe o trabalho em 5 a 30 unidades independentes e apresenta um plano. Uma vez aprovado, gera um agente de fundo por unidade em um [git worktree](/pt/worktrees) isolado. Cada agente implementa sua unidade, executa testes e abre uma solicitação de pull. Requer um repositório git. Exemplo: `/batch migrate src/ from Solid to React` |

25| `/branch [name]` | Criar um branch da conversa atual neste ponto. Alterna você para o branch e preserva o original, ao qual você pode retornar com `/resume`. Alias: `/fork`. Quando [`CLAUDE_CODE_FORK_SUBAGENT`](/pt/env-vars) está definido, `/fork` em vez disso gera um [subagent bifurcado](/pt/sub-agents#fork-the-current-conversation) e não é mais um alias para este comando |27| `/branch [name]` | Criar um branch da conversa atual neste ponto. Alterna você para o branch e preserva o original, ao qual você pode retornar com `/resume`. Alias: `/fork`. Quando [`CLAUDE_CODE_FORK_SUBAGENT`](/pt/env-vars) está definido, `/fork` em vez disso gera um [subagent bifurcado](/pt/sub-agents#fork-the-current-conversation) e não é mais um alias para este comando |

28| `/claude-api [migrate\|managed-agents-onboard]` | **[Skill](/pt/skills#bundled-skills).** Carregar material de referência da API Claude para a linguagem do seu projeto (Python, TypeScript, Java, Go, Ruby, C#, PHP ou cURL) e referência de Managed Agents. Cobre uso de ferramentas, streaming, lotes, saídas estruturadas e armadilhas comuns. Também ativa automaticamente quando seu código importa `anthropic` ou `@anthropic-ai/sdk`. Execute `/claude-api migrate` para atualizar o código existente da API Claude para um modelo mais recente: Claude pergunta quais arquivos verificar e qual modelo direcionar, depois atualiza IDs de modelo, configuração de thinking e outros parâmetros que mudaram entre versões. Execute `/claude-api managed-agents-onboard` para um passo a passo interativo que cria um novo Managed Agent do zero |30| `/claude-api [migrate\|managed-agents-onboard]` | **[Skill](/pt/skills#bundled-skills).** Carregar material de referência da API Claude para a linguagem do seu projeto (Python, TypeScript, Java, Go, Ruby, C#, PHP ou cURL) e referência de Managed Agents. Cobre uso de ferramentas, streaming, lotes, saídas estruturadas e armadilhas comuns. Também ativa automaticamente quando seu código importa `anthropic` ou `@anthropic-ai/sdk`. Execute `/claude-api migrate` para atualizar o código existente da API Claude para um modelo mais recente: Claude pergunta quais arquivos verificar e qual modelo direcionar, depois atualiza IDs de modelo, configuração de thinking e outros parâmetros que mudaram entre versões. Execute `/claude-api managed-agents-onboard` para um passo a passo interativo que cria um novo Managed Agent do zero |

29| `/clear` | Iniciar uma nova conversa com contexto vazio. A conversa anterior permanece disponível em `/resume`. Para liberar contexto enquanto continua a mesma conversa, use `/compact` em vez disso. Aliases: `/reset`, `/new` |31| `/clear` | Iniciar uma nova conversa com contexto vazio. A conversa anterior permanece disponível em `/resume`. Para liberar contexto enquanto continua a mesma conversa, use `/compact` em vez disso. Aliases: `/reset`, `/new` |

30| `/color [color\|default]` | Definir a cor da barra de prompt para a sessão atual. Cores disponíveis: `red`, `blue`, `green`, `yellow`, `purple`, `orange`, `pink`, `cyan`. Use `default` para redefinir. Quando [Remote Control](/pt/remote-control) está conectado, a cor sincroniza com claude.ai/code |32| `/color [color\|default]` | Definir a cor da barra de prompt para a sessão atual. Cores disponíveis: `red`, `blue`, `green`, `yellow`, `purple`, `orange`, `pink`, `cyan`. Use `default` para redefinir, ou execute sem argumento para escolher uma cor aleatória. Quando [Remote Control](/pt/remote-control) está conectado, a cor sincroniza com claude.ai/code |

31| `/compact [instructions]` | Liberar contexto resumindo a conversa até agora. Opcionalmente, passe instruções de foco para o resumo. Consulte [como a compactação lida com regras, skills e arquivos de memória](/pt/context-window#what-survives-compaction) |33| `/compact [instructions]` | Liberar contexto resumindo a conversa até agora. Opcionalmente, passe instruções de foco para o resumo. Consulte [como a compactação lida com regras, skills e arquivos de memória](/pt/context-window#what-survives-compaction) |

32| `/config` | Abrir a interface de [Configurações](/pt/settings) para ajustar tema, modelo, [estilo de saída](/pt/output-styles) e outras preferências. Alias: `/settings` |34| `/config` | Abrir a interface de [Configurações](/pt/settings) para ajustar tema, modelo, [estilo de saída](/pt/output-styles) e outras preferências. Alias: `/settings` |

33| `/context` | Visualizar o uso atual de contexto como uma grade colorida. Mostra sugestões de otimização para ferramentas pesadas em contexto, inchaço de memória e avisos de capacidade |35| `/context` | Visualizar o uso atual de contexto como uma grade colorida. Mostra sugestões de otimização para ferramentas pesadas em contexto, inchaço de memória e avisos de capacidade |

44| `/fast [on\|off]` | Alternar [modo rápido](/pt/fast-mode) ativado ou desativado |46| `/fast [on\|off]` | Alternar [modo rápido](/pt/fast-mode) ativado ou desativado |

46| `/fewer-permission-prompts` | **[Skill](/pt/skills#bundled-skills).** Verificar seus transcritos para chamadas de ferramentas Bash e MCP comuns somente leitura, depois adicionar uma lista de permissões priorizada ao projeto `.claude/settings.json` para reduzir prompts de permissão |48| `/fewer-permission-prompts` | **[Skill](/pt/skills#bundled-skills).** Verificar seus transcritos para chamadas de ferramentas Bash e MCP comuns somente leitura, depois adicionar uma lista de permissões priorizada ao projeto `.claude/settings.json` para reduzir prompts de permissão |

47| `/focus` | Alternar a visualização de foco, que mostra apenas seu último prompt, um resumo de chamada de ferramenta de uma linha com estatísticas de edição de diff e a resposta final. A seleção persiste entre sessões. Disponível apenas em [renderização em tela cheia](/pt/fullscreen) |49| `/focus` | Alternar a visualização de foco, que mostra apenas seu último prompt, um resumo de chamada de ferramenta de uma linha com estatísticas de edição de diff e a resposta final. A seleção persiste entre sessões; defina [`viewMode`](/pt/settings#available-settings) nas configurações para substituir. Disponível apenas em [renderização em tela cheia](/pt/fullscreen) |

48| `/heapdump` | Escrever um snapshot de heap JavaScript e um detalhamento de memória para `~/Desktop`, ou seu diretório inicial no Linux sem uma pasta Desktop, para diagnosticar alto uso de memória. Consulte [solução de problemas](/pt/troubleshooting#high-cpu-or-memory-usage) |50| `/heapdump` | Escrever um snapshot de heap JavaScript e um detalhamento de memória para `~/Desktop`, ou seu diretório inicial no Linux sem uma pasta Desktop, para diagnosticar alto uso de memória. Consulte [solução de problemas](/pt/troubleshooting#high-cpu-or-memory-usage) |

83| `/setup-bedrock` | Configurar autenticação, região e fixações de modelo do [Amazon Bedrock](/pt/amazon-bedrock) através de um assistente interativo. Visível apenas quando `CLAUDE_CODE_USE_BEDROCK=1` está definido. Usuários do Bedrock pela primeira vez também podem acessar este assistente na tela de login |85| `/setup-bedrock` | Configurar autenticação, região e fixações de modelo do [Amazon Bedrock](/pt/amazon-bedrock) através de um assistente interativo. Visível apenas quando `CLAUDE_CODE_USE_BEDROCK=1` está definido. Usuários do Bedrock pela primeira vez também podem acessar este assistente na tela de login |

84| `/setup-vertex` | Configurar autenticação, projeto, região e fixações de modelo do [Google Vertex AI](/pt/google-vertex-ai) através de um assistente interativo. Visível apenas quando `CLAUDE_CODE_USE_VERTEX=1` está definido. Usuários do Vertex AI pela primeira vez também podem acessar este assistente na tela de login |86| `/setup-vertex` | Configurar autenticação, projeto, região e fixações de modelo do [Google Vertex AI](/pt/google-vertex-ai) através de um assistente interativo. Visível apenas quando `CLAUDE_CODE_USE_VERTEX=1` está definido. Usuários do Vertex AI pela primeira vez também podem acessar este assistente na tela de login |

85| `/simplify [focus]` | **[Skill](/pt/skills#bundled-skills).** Revisar seus arquivos alterados recentemente para problemas de reutilização de código, qualidade e eficiência, depois corrigi-los. Gera três agentes de revisão em paralelo, agrega suas descobertas e aplica correções. Passe texto para focar em preocupações específicas: `/simplify focus on memory efficiency` |87| `/simplify [focus]` | **[Skill](/pt/skills#bundled-skills).** Revisar seus arquivos alterados recentemente para problemas de reutilização de código, qualidade e eficiência, depois corrigi-los. Gera três agentes de revisão em paralelo, agrega suas descobertas e aplica correções. Passe texto para focar em preocupações específicas: `/simplify focus on memory efficiency` |

86| `/skills` | Listar [skills](/pt/skills) disponíveis. Pressione `t` para classificar por contagem de tokens |88| `/skills` | Listar [skills](/pt/skills) disponíveis. Pressione `t` para classificar por contagem de tokens. Pressione `Space` para [ocultar uma skill do Claude ou do menu `/`](/pt/skills#override-skill-visibility-from-settings), depois `Enter` para salvar |

88| `/status` | Abrir a interface de Configurações (aba Status) mostrando versão, modelo, conta e conectividade. Funciona enquanto Claude está respondendo, sem esperar a resposta atual terminar |90| `/status` | Abrir a interface de Configurações (aba Status) mostrando versão, modelo, conta e conectividade. Funciona enquanto Claude está respondendo, sem esperar a resposta atual terminar |

89| `/statusline` | Configurar a [linha de status](/pt/statusline) do Claude Code. Descreva o que você quer, ou execute sem argumentos para auto-configurar a partir do seu prompt de shell |91| `/statusline` | Configurar a [linha de status](/pt/statusline) do Claude Code. Descreva o que você quer, ou execute sem argumentos para auto-configurar a partir do seu prompt de shell |

92| `/team-onboarding` | Gerar um guia de integração de equipe a partir do seu histórico de uso do Claude Code. Claude analisa suas sessões, comandos e uso de servidor MCP dos últimos 30 dias e produz um guia markdown que um colega de equipe pode colar como primeira mensagem para se configurar rapidamente |94| `/team-onboarding` | Gerar um guia de integração de equipe a partir do seu histórico de uso do Claude Code. Claude analisa suas sessões, comandos e uso de servidor MCP dos últimos 30 dias e produz um guia markdown que um colega de equipe pode colar como primeira mensagem para se configurar rapidamente. Para assinantes do claude.ai nos planos Pro, Max, Team e Enterprise, também retorna um link de compartilhamento que colegas de equipe podem abrir diretamente no Claude Code |

93| `/teleport` | Puxar uma sessão [Claude Code na web](/pt/claude-code-on-the-web#from-web-to-terminal) para este terminal: abre um seletor, depois busca o branch e a conversa. Também disponível como `/tp`. Requer uma assinatura claude.ai |95| `/teleport` | Puxar uma sessão [Claude Code na web](/pt/claude-code-on-the-web#from-web-to-terminal) para este terminal: abre um seletor, depois busca o branch e a conversa. Também disponível como `/tp`. Requer uma assinatura claude.ai |

94| `/terminal-setup` | Configurar atalhos de teclado do terminal para Shift+Enter e outros atalhos. Visível apenas em terminais que precisam, como VS Code, Cursor, Windsurf, Alacritty ou Zed |96| `/terminal-setup` | Configurar atalhos de teclado do terminal para Shift+Enter e outros atalhos. Visível apenas em terminais que precisam, como VS Code, Cursor, Windsurf, Alacritty ou Zed |

95| `/theme` | Alterar o tema de cor. Inclui uma opção `auto` que segue o modo escuro ou claro do seu terminal, variantes claro e escuro, temas acessíveis para daltônicos (daltonizados), temas ANSI que usam a paleta de cores do seu terminal e qualquer [tema personalizado](/pt/terminal-config#create-a-custom-theme) de `~/.claude/themes/` ou plugins. Selecione **New custom theme…** para criar um |97| `/theme` | Alterar o tema de cor. Inclui uma opção `auto` que segue o modo escuro ou claro do seu terminal, variantes claro e escuro, temas acessíveis para daltônicos (daltonizados), temas ANSI que usam a paleta de cores do seu terminal e qualquer [tema personalizado](/pt/terminal-config#create-a-custom-theme) de `~/.claude/themes/` ou plugins. Selecione **New custom theme…** para criar um |

debug-your-config.md +24 −4

Details

17Para detalhes sobre uma categoria específica, acompanhe com o comando dedicado:17Para detalhes sobre uma categoria específica, acompanhe com o comando dedicado:

18 18

19| Comando | Mostra |19| Comando | Mostra |

~~20| :------------- | :--------------------------------------------------------------------------------------- |~~20| :--------------- | :-------------------------------------------------------------------------------------------------------------------------- |

21| `/memory` | Quais arquivos `CLAUDE.md` e rules foram carregados, além de entradas de auto-memória |21| `/memory` | Quais arquivos `CLAUDE.md` e rules foram carregados, além de entradas de auto-memória |

22| `/skills` | Skills disponíveis de fontes de projeto, usuário e plugin |22| `/skills` | Skills disponíveis de fontes de projeto, usuário e plugin |

23| `/agents` | Subagentes configurados e suas configurações |23| `/agents` | Subagentes configurados e suas configurações |

25| `/mcp` | Servidores MCP conectados e seu status |25| `/mcp` | Servidores MCP conectados e seu status |

26| `/permissions` | Regras de permissão e negação resolvidas atualmente em vigor |26| `/permissions` | Regras de permissão e negação resolvidas atualmente em vigor |

27| `/doctor` | Diagnósticos de configuração: chaves inválidas, erros de schema, saúde da instalação |27| `/doctor` | Diagnósticos de configuração: chaves inválidas, erros de schema, saúde da instalação |

28| `/debug [issue]` | Ativa o log de depuração para a sessão e solicita que Claude diagnostique usando a saída do log e caminhos de configurações |

28| `/status` | Fontes de configurações ativas, incluindo se as configurações gerenciadas estão em vigor |29| `/status` | Fontes de configurações ativas, incluindo se as configurações gerenciadas estão em vigor |

29 30

30Se um arquivo de memória estiver faltando em `/memory`, verifique sua localização em relação a [como os arquivos CLAUDE.md são carregados](/pt/memory#how-claude-md-files-load). Os arquivos `CLAUDE.md` do subdiretório são carregados sob demanda quando Claude lê um arquivo nesse diretório com a ferramenta Read, não no início da sessão.31Se um arquivo de memória estiver faltando em `/memory`, verifique sua localização em relação a [como os arquivos CLAUDE.md são carregados](/pt/memory#how-claude-md-files-load). Os arquivos `CLAUDE.md` do subdiretório são carregados sob demanda quando Claude lê um arquivo nesse diretório com a ferramenta Read, não no início da sessão.

41 42

42As configurações se mesclam entre escopos gerenciados, de usuário, de projeto e locais. As configurações gerenciadas sempre vencem quando presentes. Entre o resto, o escopo mais próximo substitui o mais amplo na ordem local, depois projeto, depois usuário. Algumas configurações também podem ser definidas por sinalizadores de linha de comando ou [variáveis de ambiente](/pt/env-vars), que atuam como outra camada de substituição. Quando uma configuração não parece se aplicar, o valor que você definiu geralmente está sendo substituído por outro escopo ou uma variável de ambiente.43As configurações se mesclam entre escopos gerenciados, de usuário, de projeto e locais. As configurações gerenciadas sempre vencem quando presentes. Entre o resto, o escopo mais próximo substitui o mais amplo na ordem local, depois projeto, depois usuário. Algumas configurações também podem ser definidas por sinalizadores de linha de comando ou [variáveis de ambiente](/pt/env-vars), que atuam como outra camada de substituição. Quando uma configuração não parece se aplicar, o valor que você definiu geralmente está sendo substituído por outro escopo ou uma variável de ambiente.

43 44

44Execute `/doctor` para validar seus arquivos de configuração e expor chaves inválidas ou erros de schema. Execute `/status` para ver quais fontes de configurações estão ativas, incluindo se as configurações gerenciadas estão em vigor. Para entender qual escopo vence para uma chave específica, consulte [Como os escopos interagem](/pt/settings#how-scopes-interact).45Execute `/doctor` para validar seus arquivos de configuração e expor chaves inválidas ou erros de schema. Quando `/doctor` relata problemas, pressione `f` para enviar o relatório de diagnóstico a Claude e deixe-o orientá-lo através das correções.

47Execute `/status` para ver quais fontes de configurações estão ativas, incluindo se as configurações gerenciadas estão em vigor. Para entender qual escopo vence para uma chave específica, consulte [Como os escopos interagem](/pt/settings#how-scopes-interact).

45 48

46## Verifique os servidores MCP49## Verifique os servidores MCP

47 50

63 66

64Se `/hooks` mostrar o hook mas ele ainda não disparar, o próximo passo é observar a avaliação do hook ao vivo. Inicie uma sessão com `claude --debug hooks` e dispare a chamada de ferramenta. O log de depuração registra cada evento, quais matchers foram verificados e o código de saída e saída do hook. Consulte [Debug hooks](/pt/hooks#debug-hooks) para o formato do log e [troubleshooting de hooks](/pt/hooks-guide#limitations-and-troubleshooting) para padrões de falha comuns.67Se `/hooks` mostrar o hook mas ele ainda não disparar, o próximo passo é observar a avaliação do hook ao vivo. Inicie uma sessão com `claude --debug hooks` e dispare a chamada de ferramenta. O log de depuração registra cada evento, quais matchers foram verificados e o código de saída e saída do hook. Consulte [Debug hooks](/pt/hooks#debug-hooks) para o formato do log e [troubleshooting de hooks](/pt/hooks-guide#limitations-and-troubleshooting) para padrões de falha comuns.

65 68

~~66## Causas comuns~~69## Teste contra uma configuração limpa

71Se as verificações direcionadas não isolarem a causa, ou sua configuração estiver em um estado desconhecido, compare contra uma sessão que não carrega nada de sua configuração usual. Aponte [`CLAUDE_CONFIG_DIR`](/pt/env-vars) para um diretório vazio para contornar tudo sob `~/.claude` e inicie a partir de um diretório que não tenha pasta `.claude`, `.mcp.json` ou `CLAUDE.md` para que a configuração do projeto também seja ignorada.

73```bash theme={null}

74cd /tmp && CLAUDE_CONFIG_DIR=/tmp/claude-clean claude

75```

77A sessão limpa não tem configurações de usuário ou projeto, hooks, servidores MCP, plugins ou memória.

79* As configurações gerenciadas ainda se aplicam se sua organização as implanta, pois vivem em um caminho do sistema fora de `~/.claude`

80* No Linux e Windows, você será solicitado a fazer login novamente porque as credenciais são armazenadas sob o diretório de configuração

81* No macOS, as credenciais estão no Keychain e são transferidas para a sessão limpa

83Se o problema desaparecer aqui, a causa está em algum lugar em seus arquivos reais `~/.claude` ou `.claude` do projeto. Reintroduza-os um de cada vez, copiando arquivos para o diretório temporário ou iniciando a partir de seu projeto, para encontrar qual. Se persistir na sessão limpa, a causa está fora de sua configuração de usuário e projeto. Execute `/status` para verificar se as configurações gerenciadas estão em vigor, procure por [variáveis de ambiente](/pt/env-vars) que afetam Claude Code e consulte [Solução de problemas](/pt/troubleshooting).

85## Verifique as causas comuns

67 86

68A maioria das surpresas de configuração rastreia um pequeno conjunto de regras de localização e sintaxe. Verifique estas antes de assumir um bug:87A maioria das surpresas de configuração rastreia um pequeno conjunto de regras de localização e sintaxe. Verifique estas antes de assumir um bug:

69 88

71| :----------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |90| :---------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

73| Hook nunca dispara | O valor de `matcher` está em minúsculas, por exemplo `"bash"` | A correspondência diferencia maiúsculas de minúsculas. Os nomes das ferramentas são capitalizados: `Bash`, `Edit`, `Write`, `Read`. |92| Hook nunca dispara | O valor de `matcher` está em minúsculas, por exemplo `"bash"` | A correspondência diferencia maiúsculas de minúsculas. Os nomes das ferramentas são capitalizados: `Bash`, `Edit`, `Write`, `Read`. |

74| Hook nunca dispara | Hooks estão em um arquivo `.claude/hooks.json` autônomo | Não há arquivo de hooks autônomo. Defina hooks sob a chave `"hooks"` em `settings.json`. Consulte [configuração de hook](/pt/hooks). |93| Hook nunca dispara | Hooks estão em um arquivo `.claude/hooks.json` autônomo | Não há arquivo de hooks autônomo. Defina hooks sob a chave `"hooks"` em `settings.json`. Consulte [configuração de hook](/pt/hooks). |

80| Subagente ignora as instruções de `CLAUDE.md` | Subagentes nem sempre herdam memória de projeto | Coloque regras críticas no corpo do arquivo do agente, que se torna o prompt do sistema do subagente. Consulte [configuração de subagente](/pt/sub-agents). |99| Subagente ignora as instruções de `CLAUDE.md` | Subagentes nem sempre herdam memória de projeto | Coloque regras críticas no corpo do arquivo do agente, que se torna o prompt do sistema do subagente. Consulte [configuração de subagente](/pt/sub-agents). |

81| A lógica de limpeza nunca é executada no final da sessão | Nenhum hook `SessionEnd` configurado | Adicione um hook `SessionEnd` em `settings.json`. Consulte a [lista de eventos de hook](/pt/hooks#hook-events). |100| A lógica de limpeza nunca é executada no final da sessão | Nenhum hook `SessionEnd` configurado | Adicione um hook `SessionEnd` em `settings.json`. Consulte a [lista de eventos de hook](/pt/hooks#hook-events). |

82| Servidores MCP em `.mcp.json` nunca são carregados | O arquivo está sob `.claude/` ou usa o formato de configuração do Claude Desktop | A configuração MCP do projeto vai na raiz do repositório como `.mcp.json`, não dentro de `.claude/`. Consulte [configuração MCP](/pt/mcp). |101| Servidores MCP em `.mcp.json` nunca são carregados | O arquivo está sob `.claude/` ou usa o formato de configuração do Claude Desktop | A configuração MCP do projeto vai na raiz do repositório como `.mcp.json`, não dentro de `.claude/`. Consulte [configuração MCP](/pt/mcp). |

102| Servidores MCP adicionados sob `mcpServers` em `settings.json` nunca aparecem | `settings.json` não lê uma chave `mcpServers` | Defina servidores de projeto em `.mcp.json` na raiz do repositório, ou execute `claude mcp add --scope user` para servidores com escopo de usuário. Consulte [configuração MCP](/pt/mcp). |

83| Servidor MCP do projeto adicionado mas não aparece | O prompt de aprovação única foi descartado | Servidores com escopo de projeto requerem aprovação. Execute `/mcp` para ver o status e aprovar. |103| Servidor MCP do projeto adicionado mas não aparece | O prompt de aprovação única foi descartado | Servidores com escopo de projeto requerem aprovação. Execute `/mcp` para ver o status e aprovar. |

84| Servidor MCP falha ao iniciar de alguns diretórios | `command` ou `args` usa um caminho de arquivo relativo | Use caminhos absolutos para scripts locais. Executáveis em seu `PATH` como `npx` ou `uvx` funcionam como estão. |104| Servidor MCP falha ao iniciar de alguns diretórios | `command` ou `args` usa um caminho de arquivo relativo | Use caminhos absolutos para scripts locais. Executáveis em seu `PATH` como `npx` ou `uvx` funcionam como estão. |

85| Servidor MCP inicia sem variáveis de ambiente esperadas | As variáveis estão em `settings.json` `env`, que não se propaga para processos filhos MCP | Defina `env` por servidor dentro de `.mcp.json` em vez disso. |105| Servidor MCP inicia sem variáveis de ambiente esperadas | As variáveis estão em `settings.json` `env`, que não se propaga para processos filhos MCP | Defina `env` por servidor dentro de `.mcp.json` em vez disso. |

discover-plugins.md +19 −11

Details

4 4

5# Descubra e instale plugins pré-construídos através de marketplaces5# Descubra e instale plugins pré-construídos através de marketplaces

6 6

~~7> Encontre e instale plugins de marketplaces para estender Claude Code com novos comandos, agentes e capacidades.~~7> Encontre e instale plugins de marketplaces para estender Claude Code com novas skills, agentes e capacidades.

8 8

9Plugins estendem Claude Code com skills, agentes, hooks e MCP servers. Marketplaces de plugins são catálogos que ajudam você a descobrir e instalar essas extensões sem construí-las você mesmo.9Plugins estendem Claude Code com skills, agentes, hooks e MCP servers. Marketplaces de plugins são catálogos que ajudam você a descobrir e instalar essas extensões sem construí-las você mesmo.

10 10

36/plugin install github@claude-plugins-official36/plugin install github@claude-plugins-official

37```37```

38 38

39Se Claude Code relatar que o plugin não foi encontrado em nenhum marketplace, seu marketplace está ausente ou desatualizado. Execute `/plugin marketplace update claude-plugins-official` para atualizá-lo, ou `/plugin marketplace add anthropics/claude-plugins-official` se você não o adicionou antes. Depois tente instalar novamente.

39<Note>41<Note>

40 O marketplace oficial é mantido pela Anthropic. Para enviar um plugin para o marketplace oficial, use um dos formulários de envio no aplicativo:42 O marketplace oficial é mantido pela Anthropic. Para enviar um plugin para o marketplace oficial, use um dos formulários de envio no aplicativo:

41 43

95 97

96### Fluxos de trabalho de desenvolvimento98### Fluxos de trabalho de desenvolvimento

97 99

~~98Plugins que adicionam comandos e agentes para tarefas comuns de desenvolvimento:~~100Plugins que adicionam skills e agentes para tarefas comuns de desenvolvimento:

99 101

100* **commit-commands**: Fluxos de trabalho de commit do Git incluindo commit, push e criação de PR102* **commit-commands**: Fluxos de trabalho de commit do Git incluindo commit, push e criação de PR

101* **pr-review-toolkit**: Agentes especializados para revisar pull requests103* **pr-review-toolkit**: Agentes especializados para revisar pull requests

142 * **Project scope**: instale para todos os colaboradores neste repositório144 * **Project scope**: instale para todos os colaboradores neste repositório

143 * **Local scope**: instale para você neste repositório apenas145 * **Local scope**: instale para você neste repositório apenas

144 146

145 Por exemplo, selecione **commit-commands** (um plugin que adiciona comandos de fluxo de trabalho git) e instale-o no seu escopo de usuário.147 Por exemplo, selecione **commit-commands** (um plugin que adiciona skills de fluxo de trabalho git) e instale-o no seu escopo de usuário.

146 148

147 Você também pode instalar diretamente da linha de comando:149 Você também pode instalar diretamente da linha de comando:

148 150

154 </Step>156 </Step>

155 157

156 <Step title="Use seu novo plugin">158 <Step title="Use seu novo plugin">

157 Após instalar, execute `/reload-plugins` para ativar o plugin. Comandos de plugin são nomeados com namespace pelo nome do plugin, então **commit-commands** fornece comandos como `/commit-commands:commit`.159 Após instalar, execute `/reload-plugins` para ativar o plugin. Skills de plugin são nomeadas com namespace pelo nome do plugin, então **commit-commands** fornece skills como `/commit-commands:commit`.

158 160

159 Experimente fazendo uma mudança em um arquivo e executando:161 Experimente fazendo uma mudança em um arquivo e executando:

160 162

164 166

165 Isso prepara suas mudanças, gera uma mensagem de commit e cria o commit.167 Isso prepara suas mudanças, gera uma mensagem de commit e cria o commit.

166 168

167 Cada plugin funciona diferentemente. Verifique a descrição do plugin na aba **Discover** ou sua página inicial para aprender quais comandos e capacidades ele fornece.169 Cada plugin funciona diferentemente. Verifique a descrição do plugin na aba **Discover** ou sua página inicial para aprender quais skills e capacidades ele fornece.

168 </Step>170 </Step>

169</Steps>171</Steps>

170 172

195 197

196### Adicione de outros hosts Git198### Adicione de outros hosts Git

197 199

198Adicione qualquer repositório git fornecendo a URL completa. Isso funciona com qualquer host Git, incluindo GitLab, Bitbucket e servidores auto-hospedados:200Adicione qualquer repositório git fornecendo a URL completa. Isso funciona com qualquer host Git, incluindo GitLab, Bitbucket e servidores auto-hospedados. Inclua o sufixo `.git` para que Claude Code clone o repositório em vez de tratar a URL como um link direto para um arquivo `marketplace.json` hospedado.

199 201

200Usando HTTPS:202Usando HTTPS:

201 203

257 259

258Você também pode ver plugins com escopo **managed**—esses são instalados por administradores via [managed settings](/pt/settings#settings-files) e não podem ser modificados.260Você também pode ver plugins com escopo **managed**—esses são instalados por administradores via [managed settings](/pt/settings#settings-files) e não podem ser modificados.

259 261

260Execute `/plugin` e vá para a aba **Installed** para ver seus plugins agrupados por escopo.

~~261~~

262<Warning>262<Warning>

263 Certifique-se de confiar em um plugin antes de instalá-lo. Anthropic não controla quais MCP servers, arquivos ou outro software estão incluídos em plugins e não pode verificar que funcionam conforme pretendido. Verifique a página inicial de cada plugin para mais informações.263 Certifique-se de confiar em um plugin antes de instalá-lo. Anthropic não controla quais MCP servers, arquivos ou outro software estão incluídos em plugins e não pode verificar que funcionam conforme pretendido. Verifique a página inicial de cada plugin para mais informações.

264</Warning>264</Warning>

265 265

266## Gerencie plugins instalados266## Gerencie plugins instalados

267 267

268Execute `/plugin` e vá para a aba **Installed** para visualizar, habilitar, desabilitar ou desinstalar seus plugins. Digite para filtrar a lista por nome ou descrição do plugin.268Execute `/plugin` e vá para a aba **Installed** para visualizar, habilitar, desabilitar ou desinstalar seus plugins. A lista é agrupada por escopo e classificada para que você veja problemas primeiro: plugins com erros de carregamento ou dependências não resolvidas aparecem no topo, seguidos por seus favoritos, com plugins desabilitados dobrados atrás de um cabeçalho recolhido na parte inferior.

269

270Da lista você pode:

271

272* pressionar `f` para marcar como favorito ou desmarcar como favorito o plugin selecionado

273* digitar para filtrar por nome ou descrição do plugin

274* pressionar Enter para abrir a visualização de detalhes de um plugin e habilitar, desabilitar ou desinstalá-lo

275

276Quando você instala um plugin que declara dependências, a saída de instalação lista quais dependências foram auto-instaladas junto com ele.

269 277

270Você também pode gerenciar plugins com comandos diretos.278Você também pode gerenciar plugins com comandos diretos.

271 279

400 408

4011. **Verifique sua versão**: Execute `claude --version` para ver o que está instalado.4091. **Verifique sua versão**: Execute `claude --version` para ver o que está instalado.

4022. **Atualize Claude Code**:4102. **Atualize Claude Code**:

403 * **Homebrew**: `brew upgrade claude-code`411 * **Homebrew**: `brew upgrade claude-code` (ou `brew upgrade claude-code@latest` se você instalou esse cask)

404 * **npm**: `npm update -g @anthropic-ai/claude-code`412 * **npm**: `npm install -g @anthropic-ai/claude-code@latest`

405 * **Native installer**: Re-execute o comando de instalação de [Setup](/pt/setup)413 * **Native installer**: Re-execute o comando de instalação de [Setup](/pt/setup)

4063. **Reinicie Claude Code**: Após atualizar, reinicie seu terminal e execute `claude` novamente.4143. **Reinicie Claude Code**: Após atualizar, reinicie seu terminal e execute `claude` novamente.

407 415

env-vars.md +15 −9

Details

42| `ANTHROPIC_SMALL_FAST_MODEL_AWS_REGION` | Substitua a região AWS para o modelo da classe Haiku ao usar Bedrock ou Bedrock Mantle |42| `ANTHROPIC_SMALL_FAST_MODEL_AWS_REGION` | Substitua a região AWS para o modelo da classe Haiku ao usar Bedrock ou Bedrock Mantle |

43| `ANTHROPIC_VERTEX_BASE_URL` | Substitua a URL do endpoint Vertex AI. Use para endpoints Vertex personalizados ou ao rotear através de um [gateway LLM](/pt/llm-gateway). Veja [Google Vertex AI](/pt/google-vertex-ai) |43| `ANTHROPIC_VERTEX_BASE_URL` | Substitua a URL do endpoint Vertex AI. Use para endpoints Vertex personalizados ou ao rotear através de um [gateway LLM](/pt/llm-gateway). Veja [Google Vertex AI](/pt/google-vertex-ai) |

44| `ANTHROPIC_VERTEX_PROJECT_ID` | ID do projeto GCP para Vertex AI. Obrigatório ao usar [Google Vertex AI](/pt/google-vertex-ai) |44| `ANTHROPIC_VERTEX_PROJECT_ID` | ID do projeto GCP para solicitações Vertex AI. Substituído por `GCLOUD_PROJECT`, `GOOGLE_CLOUD_PROJECT` ou o projeto no seu arquivo de credenciais `GOOGLE_APPLICATION_CREDENTIALS`. Veja [Google Vertex AI](/pt/google-vertex-ai) |

45| `API_TIMEOUT_MS` | Tempo limite para solicitações de API em milissegundos (padrão: 600000, ou 10 minutos; máximo: 2147483647). Aumente isso quando as solicitações expiram em redes lentas ou ao rotear através de um proxy. Valores acima do máximo causam overflow do temporizador subjacente e fazem com que as solicitações falhem imediatamente |45| `API_TIMEOUT_MS` | Tempo limite para solicitações de API em milissegundos (padrão: 600000, ou 10 minutos; máximo: 2147483647). Aumente isso quando as solicitações expiram em redes lentas ou ao rotear através de um proxy. Valores acima do máximo causam overflow do temporizador subjacente e fazem com que as solicitações falhem imediatamente |

46| `AWS_BEARER_TOKEN_BEDROCK` | Chave de API do Bedrock para autenticação (veja [Chaves de API do Bedrock](https://aws.amazon.com/blogs/machine-learning/accelerate-ai-development-with-amazon-bedrock-api-keys/)) |46| `AWS_BEARER_TOKEN_BEDROCK` | Chave de API do Bedrock para autenticação (veja [Chaves de API do Bedrock](https://aws.amazon.com/blogs/machine-learning/accelerate-ai-development-with-amazon-bedrock-api-keys/)) |

51| `CLAUDECODE` | Defina como `1` em ambientes de shell que Claude Code gera (ferramenta Bash, sessões tmux). Não definido em [hooks](/pt/hooks) ou comandos de [linha de status](/pt/statusline). Use para detectar quando um script está sendo executado dentro de um shell gerado por Claude Code |51| `CLAUDECODE` | Defina como `1` em ambientes de shell que Claude Code gera (ferramenta Bash, sessões tmux). Não definido em [hooks](/pt/hooks) ou comandos de [linha de status](/pt/statusline). Use para detectar quando um script está sendo executado dentro de um shell gerado por Claude Code |

52| `CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS` | Defina como `1` para desabilitar todos os tipos de [subagente](/pt/sub-agents) integrados, como Explore e Plan. Aplica-se apenas em modo não interativo (a flag `-p`). Útil para usuários do SDK que desejam uma tela em branco |52| `CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS` | Defina como `1` para desabilitar todos os tipos de [subagente](/pt/sub-agents) integrados, como Explore e Plan. Aplica-se apenas em modo não interativo (a flag `-p`). Útil para usuários do SDK que desejam uma tela em branco |

53| `CLAUDE_AGENT_SDK_MCP_NO_PREFIX` | Defina como `1` para pular o prefixo `mcp__<server>__` em nomes de ferramentas de servidores MCP criados pelo SDK. As ferramentas usam seus nomes originais. Apenas uso do SDK |53| `CLAUDE_AGENT_SDK_MCP_NO_PREFIX` | Defina como `1` para pular o prefixo `mcp__<server>__` em nomes de ferramentas de servidores MCP criados pelo SDK. As ferramentas usam seus nomes originais. Apenas uso do SDK |

54| `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS` | Tempo limite de travamento em milissegundos para subagentes em segundo plano. Padrão `600000` (10 minutos). O temporizador é reiniciado em cada evento de progresso de streaming; se nenhum progresso chegar dentro da janela, o subagente é abortado e a tarefa é marcada como falha, exibindo qualquer resultado parcial para o pai |

54| `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` | Defina a porcentagem da capacidade de contexto (1-100) na qual a auto-compactação é acionada. Por padrão, a auto-compactação é acionada em aproximadamente 95% de capacidade. Use valores mais baixos como `50` para compactar mais cedo. Valores acima do limite padrão não têm efeito. Aplica-se a conversas principais e subagentes. Esta porcentagem se alinha com o campo `context_window.used_percentage` disponível na [linha de status](/pt/statusline) |55| `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` | Defina a porcentagem da capacidade de contexto (1-100) na qual a auto-compactação é acionada. Por padrão, a auto-compactação é acionada em aproximadamente 95% de capacidade. Use valores mais baixos como `50` para compactar mais cedo. Valores acima do limite padrão não têm efeito. Aplica-se a conversas principais e subagentes. Esta porcentagem se alinha com o campo `context_window.used_percentage` disponível na [linha de status](/pt/statusline) |

55| `CLAUDE_AUTO_BACKGROUND_TASKS` | Defina como `1` para forçar a habilitação do envio automático para segundo plano de tarefas de agente de longa duração. Quando habilitado, subagentes são movidos para o segundo plano após executarem por aproximadamente dois minutos |56| `CLAUDE_AUTO_BACKGROUND_TASKS` | Defina como `1` para forçar a habilitação do envio automático para segundo plano de tarefas de agente de longa duração. Quando habilitado, subagentes são movidos para o segundo plano após executarem por aproximadamente dois minutos |

56| `CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR` | Retorne ao diretório de trabalho original após cada comando Bash ou PowerShell na sessão principal |57| `CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR` | Retorne ao diretório de trabalho original após cada comando Bash ou PowerShell na sessão principal |

59| `CLAUDE_CODE_API_KEY_HELPER_TTL_MS` | Intervalo em milissegundos no qual as credenciais devem ser atualizadas (ao usar [`apiKeyHelper`](/pt/settings#available-settings)) |60| `CLAUDE_CODE_API_KEY_HELPER_TTL_MS` | Intervalo em milissegundos no qual as credenciais devem ser atualizadas (ao usar [`apiKeyHelper`](/pt/settings#available-settings)) |

60| `CLAUDE_CODE_ATTRIBUTION_HEADER` | Defina como `0` para omitir o bloco de atribuição (versão do cliente e impressão digital do prompt) do início do prompt do sistema. Desabilitá-lo melhora as taxas de acerto do cache de prompt ao rotear através de um [gateway LLM](/pt/llm-gateway). O cache da API Anthropic não é afetado |61| `CLAUDE_CODE_ATTRIBUTION_HEADER` | Defina como `0` para omitir o bloco de atribuição (versão do cliente e impressão digital do prompt) do início do prompt do sistema. Desabilitá-lo melhora as taxas de acerto do cache de prompt ao rotear através de um [gateway LLM](/pt/llm-gateway). O cache da API Anthropic não é afetado |

61| `CLAUDE_CODE_AUTO_COMPACT_WINDOW` | Defina a capacidade de contexto em tokens usada para cálculos de auto-compactação. Padrão é a janela de contexto do modelo: 200K para modelos padrão ou 1M para modelos de [contexto estendido](/pt/model-config#extended-context). Use um valor mais baixo como `500000` em um modelo de 1M para tratar a janela como 500K para fins de compactação. O valor é limitado à janela de contexto real do modelo. `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` é aplicado como uma porcentagem deste valor. Definir esta variável desacopla o limite de compactação do `used_percentage` da linha de status, que sempre usa a janela de contexto completa do modelo |62| `CLAUDE_CODE_AUTO_COMPACT_WINDOW` | Defina a capacidade de contexto em tokens usada para cálculos de auto-compactação. Padrão é a janela de contexto do modelo: 200K para modelos padrão ou 1M para modelos de [contexto estendido](/pt/model-config#extended-context). Use um valor mais baixo como `500000` em um modelo de 1M para tratar a janela como 500K para fins de compactação. O valor é limitado à janela de contexto real do modelo. `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` é aplicado como uma porcentagem deste valor. Definir esta variável desacopla o limite de compactação do `used_percentage` da linha de status, que sempre usa a janela de contexto completa do modelo |

62| `CLAUDE_CODE_AUTO_CONNECT_IDE` | Substitua a [conexão IDE](/pt/vs-code) automática. Por padrão, Claude Code se conecta automaticamente quando iniciado dentro do terminal integrado de uma IDE suportada. Defina como `false` para evitar isso. Defina como `true` para forçar uma tentativa de conexão quando a detecção automática falha, como quando tmux obscurece o terminal pai |63| `CLAUDE_CODE_AUTO_CONNECT_IDE` | Substitua a [conexão IDE](/pt/vs-code) automática. Por padrão, Claude Code se conecta automaticamente quando iniciado dentro do terminal integrado de uma IDE suportada. Defina como `false` para evitar isso. Defina como `true` para forçar uma tentativa de conexão quando a detecção automática falha, como quando tmux obscurece o terminal pai. Tem precedência sobre a configuração global [`autoConnectIde`](/pt/settings#global-config-settings) |

63| `CLAUDE_CODE_CERT_STORE` | Lista separada por vírgula de fontes de certificado CA para conexões TLS. `bundled` é o conjunto de CA Mozilla fornecido com Claude Code. `system` é o armazenamento de confiança do sistema operacional. Padrão é `bundled,system`. A distribuição binária nativa é necessária para integração de armazenamento do sistema. No runtime Node.js, apenas o conjunto agrupado é usado independentemente deste valor |64| `CLAUDE_CODE_CERT_STORE` | Lista separada por vírgula de fontes de certificado CA para conexões TLS. `bundled` é o conjunto de CA Mozilla fornecido com Claude Code. `system` é o armazenamento de confiança do sistema operacional. Padrão é `bundled,system` |

68| `CLAUDE_CODE_DEBUG_LOG_LEVEL` | Nível de log mínimo escrito no arquivo de log de depuração. Valores: `verbose`, `debug` (padrão), `info`, `warn`, `error`. Defina como `verbose` para incluir diagnósticos de alto volume como saída completa de comando de linha de status, ou aumente para `error` para reduzir ruído |69| `CLAUDE_CODE_DEBUG_LOG_LEVEL` | Nível de log mínimo escrito no arquivo de log de depuração. Valores: `verbose`, `debug` (padrão), `info`, `warn`, `error`. Defina como `verbose` para incluir diagnósticos de alto volume como saída completa de comando de linha de status, ou aumente para `error` para reduzir ruído |

69| `CLAUDE_CODE_DISABLE_1M_CONTEXT` | Defina como `1` para desabilitar suporte a [janela de contexto de 1M](/pt/model-config#extended-context). Quando definido, variantes de modelo de 1M não estão disponíveis no seletor de modelo. Útil para ambientes corporativos com requisitos de conformidade |70| `CLAUDE_CODE_DISABLE_1M_CONTEXT` | Defina como `1` para desabilitar suporte a [janela de contexto de 1M](/pt/model-config#extended-context). Quando definido, variantes de modelo de 1M não estão disponíveis no seletor de modelo. Útil para ambientes corporativos com requisitos de conformidade |

70| `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING` | Defina como `1` para desabilitar [raciocínio adaptativo](/pt/model-config#adjust-effort-level) em Opus 4.6 e Sonnet 4.6 e voltar ao orçamento de pensamento fixo controlado por `MAX_THINKING_TOKENS`. {/* min-version: 2.1.111 */}Não tem efeito em Opus 4.7, que sempre usa raciocínio adaptativo |71| `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING` | Defina como `1` para desabilitar [raciocínio adaptativo](/pt/model-config#adjust-effort-level) em Opus 4.6 e Sonnet 4.6 e voltar ao orçamento de pensamento fixo controlado por `MAX_THINKING_TOKENS`. {/* min-version: 2.1.111 */}Não tem efeito em Opus 4.7, que sempre usa raciocínio adaptativo |

72| `CLAUDE_CODE_DISABLE_ALTERNATE_SCREEN` | Defina como `1` para desabilitar [renderização em tela cheia](/pt/fullscreen) e usar o renderizador de tela principal clássico. A conversa permanece no scrollback nativo do seu terminal para que `Cmd+f` e modo de cópia tmux funcionem como de costume. Tem precedência sobre `CLAUDE_CODE_NO_FLICKER` e a configuração [`tui`](/pt/settings#available-settings). Você também pode alternar com `/tui default` |

71| `CLAUDE_CODE_DISABLE_ATTACHMENTS` | Defina como `1` para desabilitar o processamento de anexos. Menções de arquivo com sintaxe `@` são enviadas como texto simples em vez de serem expandidas para conteúdo de arquivo |73| `CLAUDE_CODE_DISABLE_ATTACHMENTS` | Defina como `1` para desabilitar o processamento de anexos. Menções de arquivo com sintaxe `@` são enviadas como texto simples em vez de serem expandidas para conteúdo de arquivo |

72| `CLAUDE_CODE_DISABLE_AUTO_MEMORY` | Defina como `1` para desabilitar [memória automática](/pt/memory#auto-memory). Defina como `0` para forçar a memória automática durante o lançamento gradual. Quando desabilitada, Claude não cria ou carrega arquivos de memória automática |74| `CLAUDE_CODE_DISABLE_AUTO_MEMORY` | Defina como `1` para desabilitar [memória automática](/pt/memory#auto-memory). Defina como `0` para forçar a memória automática durante o lançamento gradual. Quando desabilitada, Claude não cria ou carrega arquivos de memória automática |

73| `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` | Defina como `1` para desabilitar toda a funcionalidade de tarefas em segundo plano, incluindo o parâmetro `run_in_background` em ferramentas Bash e subagent, auto-backgrounding e o atalho Ctrl+B |75| `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` | Defina como `1` para desabilitar toda a funcionalidade de tarefas em segundo plano, incluindo o parâmetro `run_in_background` em ferramentas Bash e subagent, auto-backgrounding e o atalho Ctrl+B |

75| `CLAUDE_CODE_DISABLE_CRON` | Defina como `1` para desabilitar [tarefas agendadas](/pt/scheduled-tasks). A skill `/loop` e ferramentas cron ficam indisponíveis e qualquer tarefa já agendada para de disparar, incluindo tarefas que já estão em execução no meio da sessão |77| `CLAUDE_CODE_DISABLE_CRON` | Defina como `1` para desabilitar [tarefas agendadas](/pt/scheduled-tasks). A skill `/loop` e ferramentas cron ficam indisponíveis e qualquer tarefa já agendada para de disparar, incluindo tarefas que já estão em execução no meio da sessão |

76| `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS` | Defina como `1` para remover cabeçalhos de solicitação `anthropic-beta` específicos do Anthropic e campos de esquema de ferramenta beta (como `defer_loading` e `eager_input_streaming`) de solicitações de API. Use isso quando um gateway proxy rejeita solicitações com erros como "Unexpected value(s) for the `anthropic-beta` header" ou "Extra inputs are not permitted". Campos padrão (`name`, `description`, `input_schema`, `cache_control`) são preservados. |78| `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS` | Defina como `1` para remover cabeçalhos de solicitação `anthropic-beta` específicos do Anthropic e campos de esquema de ferramenta beta (como `defer_loading` e `eager_input_streaming`) de solicitações de API. Use isso quando um gateway proxy rejeita solicitações com erros como "Unexpected value(s) for the `anthropic-beta` header" ou "Extra inputs are not permitted". Campos padrão (`name`, `description`, `input_schema`, `cache_control`) são preservados. |

78| `CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY` | Defina como `1` para desabilitar as pesquisas de qualidade de sessão "Como Claude está se saindo?". Pesquisas também são desabilitadas quando `DISABLE_TELEMETRY` ou `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` está definido. Veja [Pesquisas de qualidade de sessão](/pt/data-usage#session-quality-surveys) |80| `CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY` | Defina como `1` para desabilitar as pesquisas de qualidade de sessão "Como Claude está se saindo?". Pesquisas também são desabilitadas quando `DISABLE_TELEMETRY` ou `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` está definido. Para definir uma taxa de amostra em vez de desabilitar completamente, use a configuração [`feedbackSurveyRate`](/pt/settings#available-settings). Veja [Pesquisas de qualidade de sessão](/pt/data-usage#session-quality-surveys) |

79| `CLAUDE_CODE_DISABLE_FILE_CHECKPOINTING` | Defina como `1` para desabilitar [checkpointing](/pt/checkpointing) de arquivo. O comando `/rewind` não será capaz de restaurar alterações de código |81| `CLAUDE_CODE_DISABLE_FILE_CHECKPOINTING` | Defina como `1` para desabilitar [checkpointing](/pt/checkpointing) de arquivo. O comando `/rewind` não será capaz de restaurar alterações de código |

80| `CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS` | Defina como `1` para remover instruções de fluxo de trabalho de commit e PR integradas e o snapshot de status git do prompt do sistema do Claude. Útil ao usar suas próprias skills de fluxo de trabalho git. Tem precedência sobre a configuração [`includeGitInstructions`](/pt/settings#available-settings) quando definido |82| `CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS` | Defina como `1` para remover instruções de fluxo de trabalho de commit e PR integradas e o snapshot de status git do prompt do sistema do Claude. Útil ao usar suas próprias skills de fluxo de trabalho git. Tem precedência sobre a configuração [`includeGitInstructions`](/pt/settings#available-settings) quando definido |

81| `CLAUDE_CODE_DISABLE_LEGACY_MODEL_REMAP` | Defina como `1` para evitar remapeamento automático de Opus 4.0 e 4.1 para a versão Opus atual na API Anthropic. Use quando você deseja intencionalmente fixar um modelo mais antigo. O remapeamento não é executado em Bedrock, Vertex ou Foundry |83| `CLAUDE_CODE_DISABLE_LEGACY_MODEL_REMAP` | Defina como `1` para evitar remapeamento automático de Opus 4.0 e 4.1 para a versão Opus atual na API Anthropic. Use quando você deseja intencionalmente fixar um modelo mais antigo. O remapeamento não é executado em Bedrock, Vertex ou Foundry |

90| `CLAUDE_CODE_EFFORT_LEVEL` | Defina o nível de esforço para modelos suportados. Valores: `low`, `medium`, `high`, `xhigh`, `max` ou `auto` para usar o padrão do modelo. Os níveis disponíveis dependem do modelo. Tem precedência sobre `/effort` e a configuração `effortLevel`. Veja [Ajustar nível de esforço](/pt/model-config#adjust-effort-level) |92| `CLAUDE_CODE_EFFORT_LEVEL` | Defina o nível de esforço para modelos suportados. Valores: `low`, `medium`, `high`, `xhigh`, `max` ou `auto` para usar o padrão do modelo. Os níveis disponíveis dependem do modelo. Tem precedência sobre `/effort` e a configuração `effortLevel`. Veja [Ajustar nível de esforço](/pt/model-config#adjust-effort-level) |

91| `CLAUDE_CODE_ENABLE_AWAY_SUMMARY` | Substitua a disponibilidade de [recapitulação de sessão](/pt/interactive-mode#session-recap). Defina como `0` para forçar recapitulações desativadas independentemente do toggle `/config`. Defina como `1` para forçar recapitulações ativadas quando [`awaySummaryEnabled`](/pt/settings#available-settings) é `false`. Tem precedência sobre a configuração e toggle `/config` |93| `CLAUDE_CODE_ENABLE_AWAY_SUMMARY` | Substitua a disponibilidade de [recapitulação de sessão](/pt/interactive-mode#session-recap). Defina como `0` para forçar recapitulações desativadas independentemente do toggle `/config`. Defina como `1` para forçar recapitulações ativadas quando [`awaySummaryEnabled`](/pt/settings#available-settings) é `false`. Tem precedência sobre a configuração e toggle `/config` |

92| `CLAUDE_CODE_ENABLE_BACKGROUND_PLUGIN_REFRESH` | Defina como `1` para atualizar o estado do plugin em limites de turno em [modo não interativo](/pt/headless) após a conclusão de uma instalação em segundo plano. Desativado por padrão porque a atualização altera o prompt do sistema no meio da sessão, o que invalida [prompt caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching) para esse turno |94| `CLAUDE_CODE_ENABLE_BACKGROUND_PLUGIN_REFRESH` | Defina como `1` para atualizar o estado do plugin em limites de turno em [modo não interativo](/pt/headless) após a conclusão de uma instalação em segundo plano. Desativado por padrão porque a atualização altera o prompt do sistema no meio da sessão, o que invalida [prompt caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching) para esse turno |

93| `CLAUDE_CODE_ENABLE_FINE_GRAINED_TOOL_STREAMING` | Defina como `1` para forçar a habilitação do streaming de entrada de ferramenta de granulação fina. Sem isso, a API armazena em buffer parâmetros de entrada de ferramenta completamente antes de enviar eventos delta, o que pode atrasar a exibição em entradas de ferramenta grandes. Apenas API Anthropic: não tem efeito em Bedrock, Vertex ou Foundry |95| `CLAUDE_CODE_ENABLE_FINE_GRAINED_TOOL_STREAMING` | Controla se as entradas de chamada de ferramenta são transmitidas da API conforme Claude as gera. Com isso desativado, uma entrada de ferramenta grande, como uma escrita de arquivo longa, chega apenas após Claude terminar de gerá-la, o que pode parecer que está travando. Habilitado por padrão para conexões diretas da API Anthropic. Defina como `0` para optar por não participar. Defina como `1` para forçar a habilitação mesmo quando o padrão do lado do servidor está desativado. Não tem efeito em conexões Bedrock, Vertex, Foundry ou [gateway](/pt/llm-gateway) |

96| `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY` | Defina como `1` para popular o seletor `/model` a partir do endpoint `/v1/models` do seu gateway quando `ANTHROPIC_BASE_URL` aponta para um gateway compatível com Anthropic, como LiteLLM, Kong ou um proxy interno. Desativado por padrão porque gateways apoiados por uma chave de API compartilhada mostrariam de outra forma cada usuário cada modelo que a chave pode acessar. Modelos descobertos ainda são filtrados pela lista de permissões [`availableModels`](/pt/settings#available-settings) |

94| `CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION` | Defina como `false` para desabilitar sugestões de prompt (o toggle "Prompt suggestions" em `/config`). Estas são as previsões acinzentadas que aparecem na sua entrada de prompt após Claude responder. Veja [Sugestões de prompt](/pt/interactive-mode#prompt-suggestions) |97| `CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION` | Defina como `false` para desabilitar sugestões de prompt (o toggle "Prompt suggestions" em `/config`). Estas são as previsões acinzentadas que aparecem na sua entrada de prompt após Claude responder. Veja [Sugestões de prompt](/pt/interactive-mode#prompt-suggestions) |

95| `CLAUDE_CODE_ENABLE_TASKS` | Defina como `1` para habilitar o sistema de rastreamento de tarefas em modo não interativo (a flag `-p`). As tarefas estão ativadas por padrão em modo interativo. Veja [Lista de tarefas](/pt/interactive-mode#task-list) |98| `CLAUDE_CODE_ENABLE_TASKS` | Defina como `1` para habilitar o sistema de rastreamento de tarefas em modo não interativo (a flag `-p`). As tarefas estão ativadas por padrão em modo interativo. Veja [Lista de tarefas](/pt/interactive-mode#task-list) |

96| `CLAUDE_CODE_ENABLE_TELEMETRY` | Defina como `1` para habilitar coleta de dados OpenTelemetry para métricas e logging. Obrigatório antes de configurar exportadores OTel. Veja [Monitoramento](/pt/monitoring-usage) |99| `CLAUDE_CODE_ENABLE_TELEMETRY` | Defina como `1` para habilitar coleta de dados OpenTelemetry para métricas e logging. Obrigatório antes de configurar exportadores OTel. Veja [Monitoramento](/pt/monitoring-usage) |

98| `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` | Defina como `1` para habilitar [equipes de agentes](/pt/agent-teams). As equipes de agentes são experimentais e desabilitadas por padrão |101| `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` | Defina como `1` para habilitar [equipes de agentes](/pt/agent-teams). As equipes de agentes são experimentais e desabilitadas por padrão |

99| `CLAUDE_CODE_EXTRA_BODY` | Objeto JSON para mesclar no nível superior de cada corpo de solicitação de API. Útil para passar parâmetros específicos do provedor que Claude Code não expõe diretamente |102| `CLAUDE_CODE_EXTRA_BODY` | Objeto JSON para mesclar no nível superior de cada corpo de solicitação de API. Útil para passar parâmetros específicos do provedor que Claude Code não expõe diretamente |

100| `CLAUDE_CODE_FILE_READ_MAX_OUTPUT_TOKENS` | Substitua o limite de token padrão para leituras de arquivo. Útil quando você precisa ler arquivos maiores na íntegra |103| `CLAUDE_CODE_FILE_READ_MAX_OUTPUT_TOKENS` | Substitua o limite de token padrão para leituras de arquivo. Útil quando você precisa ler arquivos maiores na íntegra |

104| `CLAUDE_CODE_FORCE_SYNC_OUTPUT` | Defina como `1` para forçar a habilitação do modo privado DEC 2026 [saída sincronizada](https://gist.github.com/christianparpart/d8a62cc1ab659194337d73e399004036) quando seu terminal suporta mas não é detectado automaticamente. Útil para emuladores como `eat` do Emacs que implementam BSU/ESU mas não respondem à sonda de capacidade. Não tem efeito sob tmux |

101| `CLAUDE_CODE_FORK_SUBAGENT` | Defina como `1` para habilitar [subagentes bifurcados](/pt/sub-agents#fork-the-current-conversation). Um subagente bifurcado herda o contexto de conversa completo da sessão principal em vez de começar do zero. Quando habilitado, `/fork` gera um subagente bifurcado em vez de agir como um alias para [`/branch`](/pt/commands), e todos os spawns de subagente são executados em segundo plano. Funciona em modo interativo e via SDK ou `claude -p` |105| `CLAUDE_CODE_FORK_SUBAGENT` | Defina como `1` para habilitar [subagentes bifurcados](/pt/sub-agents#fork-the-current-conversation). Um subagente bifurcado herda o contexto de conversa completo da sessão principal em vez de começar do zero. Quando habilitado, `/fork` gera um subagente bifurcado em vez de agir como um alias para [`/branch`](/pt/commands), e todos os spawns de subagente são executados em segundo plano. Funciona em modo interativo e via SDK ou `claude -p` |

102| `CLAUDE_CODE_GIT_BASH_PATH` | Apenas Windows: caminho para o executável Git Bash (`bash.exe`). Use quando Git Bash está instalado mas não está no seu PATH. Veja [Configuração do Windows](/pt/setup#set-up-on-windows) |106| `CLAUDE_CODE_GIT_BASH_PATH` | Apenas Windows: caminho para o executável Git Bash (`bash.exe`). Use quando Git Bash está instalado mas não está no seu PATH. Veja [Configuração do Windows](/pt/setup#set-up-on-windows) |

103| `CLAUDE_CODE_GLOB_HIDDEN` | Defina como `false` para excluir dotfiles dos resultados quando Claude invoca a [ferramenta Glob](/pt/tools-reference). Incluído por padrão. Não afeta autocomplete de arquivo `@`, `ls`, Grep ou Read |107| `CLAUDE_CODE_GLOB_HIDDEN` | Defina como `false` para excluir dotfiles dos resultados quando Claude invoca a [ferramenta Glob](/pt/tools-reference). Incluído por padrão. Não afeta autocomplete de arquivo `@`, `ls`, Grep ou Read |

120| `CLAUDE_CODE_OTEL_FLUSH_TIMEOUT_MS` | Tempo limite em milissegundos para liberar spans OpenTelemetry pendentes (padrão: 5000). Veja [Monitoramento](/pt/monitoring-usage) |124| `CLAUDE_CODE_OTEL_FLUSH_TIMEOUT_MS` | Tempo limite em milissegundos para liberar spans OpenTelemetry pendentes (padrão: 5000). Veja [Monitoramento](/pt/monitoring-usage) |

121| `CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS` | Intervalo para atualizar cabeçalhos OpenTelemetry dinâmicos em milissegundos (padrão: 1740000 / 29 minutos). Veja [Cabeçalhos dinâmicos](/pt/monitoring-usage#dynamic-headers) |125| `CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS` | Intervalo para atualizar cabeçalhos OpenTelemetry dinâmicos em milissegundos (padrão: 1740000 / 29 minutos). Veja [Cabeçalhos dinâmicos](/pt/monitoring-usage#dynamic-headers) |

122| `CLAUDE_CODE_OTEL_SHUTDOWN_TIMEOUT_MS` | Tempo limite em milissegundos para o exportador OpenTelemetry terminar no desligamento (padrão: 2000). Aumente se métricas forem descartadas na saída. Veja [Monitoramento](/pt/monitoring-usage) |126| `CLAUDE_CODE_OTEL_SHUTDOWN_TIMEOUT_MS` | Tempo limite em milissegundos para o exportador OpenTelemetry terminar no desligamento (padrão: 2000). Aumente se métricas forem descartadas na saída. Veja [Monitoramento](/pt/monitoring-usage) |

127| `CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE` | Defina como `1` para permitir que Claude Code execute o comando de atualização do seu gerenciador de pacotes em segundo plano quando uma nova versão estiver disponível. Aplica-se a instalações Homebrew e WinGet. Outros gerenciadores de pacotes continuam a mostrar o comando de atualização sem executá-lo. Veja [Auto updates](/pt/setup#auto-updates) |

123| `CLAUDE_CODE_PERFORCE_MODE` | Defina como `1` para habilitar proteção de escrita ciente de Perforce. Quando definido, Edit, Write e NotebookEdit falham com uma dica `p4 edit <file>` se o arquivo de destino não tiver o bit de escrita do proprietário, que Perforce limpa em arquivos sincronizados até que `p4 edit` os abra. Isso evita que Claude Code contorne o rastreamento de mudanças do Perforce |128| `CLAUDE_CODE_PERFORCE_MODE` | Defina como `1` para habilitar proteção de escrita ciente de Perforce. Quando definido, Edit, Write e NotebookEdit falham com uma dica `p4 edit <file>` se o arquivo de destino não tiver o bit de escrita do proprietário, que Perforce limpa em arquivos sincronizados até que `p4 edit` os abra. Isso evita que Claude Code contorne o rastreamento de mudanças do Perforce |

124| `CLAUDE_CODE_PLUGIN_CACHE_DIR` | Substitua o diretório raiz de plugins. Apesar do nome, isso define o diretório pai, não o cache em si: marketplaces e o cache de plugin vivem em subdiretórios sob este caminho. Padrão é `~/.claude/plugins` |129| `CLAUDE_CODE_PLUGIN_CACHE_DIR` | Substitua o diretório raiz de plugins. Apesar do nome, isso define o diretório pai, não o cache em si: marketplaces e o cache de plugin vivem em subdiretórios sob este caminho. Padrão é `~/.claude/plugins` |

125| `CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS` | Tempo limite em milissegundos para operações git ao instalar ou atualizar plugins (padrão: 120000). Aumente este valor para repositórios grandes ou conexões de rede lentas. Veja [Operações Git expiram](/pt/plugin-marketplaces#git-operations-time-out) |130| `CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS` | Tempo limite em milissegundos para operações git ao instalar ou atualizar plugins (padrão: 120000). Aumente este valor para repositórios grandes ou conexões de rede lentas. Veja [Operações Git expiram](/pt/plugin-marketplaces#git-operations-time-out) |

131| `CLAUDE_CODE_REMOTE_SESSION_ID` | Definido automaticamente em [sessões em nuvem](/pt/claude-code-on-the-web) para o ID da sessão atual. Leia isso para construir um link de volta para a transcrição da sessão. Veja [Vincular artefatos de volta à sessão](/pt/claude-code-on-the-web#link-artifacts-back-to-the-session) |136| `CLAUDE_CODE_REMOTE_SESSION_ID` | Definido automaticamente em [sessões em nuvem](/pt/claude-code-on-the-web) para o ID da sessão atual. Leia isso para construir um link de volta para a transcrição da sessão. Veja [Vincular artefatos de volta à sessão](/pt/claude-code-on-the-web#link-artifacts-back-to-the-session) |

132| `CLAUDE_CODE_RESUME_INTERRUPTED_TURN` | Defina como `1` para retomar automaticamente se a sessão anterior terminou no meio de uma volta. Usado em modo SDK para que o modelo continue sem exigir que o SDK reenvie o prompt |137| `CLAUDE_CODE_RESUME_INTERRUPTED_TURN` | Defina como `1` para retomar automaticamente se a sessão anterior terminou no meio de uma volta. Usado em modo SDK para que o modelo continue sem exigir que o SDK reenvie o prompt |

133| `CLAUDE_CODE_SCRIPT_CAPS` | Objeto JSON limitando quantas vezes scripts específicos podem ser invocados por sessão quando `CLAUDE_CODE_SUBPROCESS_ENV_SCRUB` está definido. As chaves são substrings correspondidas contra o texto do comando; os valores são limites de chamadas inteiras. Por exemplo, `{"deploy.sh": 2}` permite que `deploy.sh` seja chamado no máximo duas vezes. A correspondência é baseada em substring, então truques de expansão de shell como `./scripts/deploy.sh $(evil)` ainda contam contra o limite. Fan-out em tempo de execução via `xargs` ou `find -exec` não é detectado; este é um controle de defesa em profundidade |138| `CLAUDE_CODE_SCRIPT_CAPS` | Objeto JSON limitando quantas vezes scripts específicos podem ser invocados por sessão quando `CLAUDE_CODE_SUBPROCESS_ENV_SCRUB` está definido. As chaves são substrings correspondidas contra o texto do comando; os valores são limites de chamadas inteiras. Por exemplo, `{"deploy.sh": 2}` permite que `deploy.sh` seja chamado no máximo duas vezes. A correspondência é baseada em substring, então truques de expansão de shell como `./scripts/deploy.sh $(evil)` ainda contam contra o limite. Fan-out em tempo de execução via `xargs` ou `find -exec` não é detectado; este é um controle de defesa em profundidade |

134| `CLAUDE_CODE_SCROLL_SPEED` | Defina o multiplicador de rolagem da roda do mouse em [renderização em tela cheia](/pt/fullscreen#mouse-wheel-scrolling). Aceita valores de 1 a 20. Defina como `3` para corresponder a `vim` se seu terminal enviar um evento de roda por entalhe sem amplificação |139| `CLAUDE_CODE_SCROLL_SPEED` | Defina o multiplicador de rolagem da roda do mouse em [renderização em tela cheia](/pt/fullscreen#mouse-wheel-scrolling). Aceita valores de 1 a 20. Defina como `3` para corresponder a `vim` se seu terminal enviar um evento de roda por entalhe sem amplificação. Ignorado no terminal IDE JetBrains, onde Claude Code usa seu próprio tratamento de rolagem |

135| `CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS` | Substitua o orçamento de tempo em milissegundos para hooks [SessionEnd](/pt/hooks#sessionend). Aplica-se à saída de sessão, `/clear` e alternância de sessões via `/resume` interativo. Por padrão, o orçamento é 1,5 segundos, automaticamente aumentado para o `timeout` por hook mais alto configurado em arquivos de configuração, até 60 segundos. Timeouts em hooks fornecidos por plugin não aumentam o orçamento |140| `CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS` | Substitua o orçamento de tempo em milissegundos para hooks [SessionEnd](/pt/hooks#sessionend). Aplica-se à saída de sessão, `/clear` e alternância de sessões via `/resume` interativo. Por padrão, o orçamento é 1,5 segundos, automaticamente aumentado para o `timeout` por hook mais alto configurado em arquivos de configuração, até 60 segundos. Timeouts em hooks fornecidos por plugin não aumentam o orçamento |

141| `CLAUDE_CODE_SESSION_ID` | Definido automaticamente em subprocessos de ferramenta Bash e PowerShell para o ID da sessão atual. Corresponde ao campo `session_id` passado para [hooks](/pt/hooks). Atualizado em `/clear`. Use para correlacionar scripts e ferramentas externas com a sessão Claude Code que as iniciou |

136| `CLAUDE_CODE_SHELL` | Substitua a detecção automática de shell. Útil quando seu shell de login difere do seu shell de trabalho preferido (por exemplo, `bash` vs `zsh`) |142| `CLAUDE_CODE_SHELL` | Substitua a detecção automática de shell. Útil quando seu shell de login difere do seu shell de trabalho preferido (por exemplo, `bash` vs `zsh`) |

137| `CLAUDE_CODE_SHELL_PREFIX` | Prefixo de comando que envolve comandos shell que Claude Code gera: chamadas de ferramenta Bash, comandos [hook](/pt/hooks) e comandos de inicialização de [servidor MCP](/pt/mcp) stdio. Útil para logging ou auditoria. Exemplo: definir `/path/to/logger.sh` executa cada comando como `/path/to/logger.sh <command>` |143| `CLAUDE_CODE_SHELL_PREFIX` | Prefixo de comando que envolve comandos shell que Claude Code gera: chamadas de ferramenta Bash, comandos [hook](/pt/hooks) e comandos de inicialização de [servidor MCP](/pt/mcp) stdio. Útil para logging ou auditoria. Exemplo: definir `/path/to/logger.sh` executa cada comando como `/path/to/logger.sh <command>` |

138| `CLAUDE_CODE_SIMPLE` | Defina como `1` para executar com um prompt do sistema mínimo e apenas as ferramentas Bash, leitura de arquivo e edição de arquivo. Ferramentas MCP de `--mcp-config` ainda estão disponíveis. Desabilita auto-descoberta de hooks, skills, plugins, servidores MCP, memória automática e CLAUDE.md. A flag CLI [`--bare`](/pt/headless#start-faster-with-bare-mode) define isso |144| `CLAUDE_CODE_SIMPLE` | Defina como `1` para executar com um prompt do sistema mínimo e apenas as ferramentas Bash, leitura de arquivo e edição de arquivo. Ferramentas MCP de `--mcp-config` ainda estão disponíveis. Desabilita auto-descoberta de hooks, skills, plugins, servidores MCP, memória automática e CLAUDE.md. A flag CLI [`--bare`](/pt/headless#start-faster-with-bare-mode) define isso |

146| `CLAUDE_CODE_SUBPROCESS_ENV_SCRUB` | Defina como `1` para remover credenciais do Anthropic e do provedor de nuvem de ambientes de subprocesso (ferramenta Bash, hooks, servidores MCP stdio). O processo Claude pai mantém essas credenciais para chamadas de API, mas processos filhos não podem lê-las, reduzindo a exposição a ataques de injeção de prompt que tentam exfiltrar segredos via expansão de shell. No Linux, isso também executa subprocessos Bash em um namespace PID isolado para que não possam ler ambientes de processo do host via `/proc`; como efeito colateral, `ps`, `pgrep` e `kill` não podem ver ou sinalizar processos do host. `claude-code-action` define isso automaticamente quando `allowed_non_write_users` está configurado |152| `CLAUDE_CODE_SUBPROCESS_ENV_SCRUB` | Defina como `1` para remover credenciais do Anthropic e do provedor de nuvem de ambientes de subprocesso (ferramenta Bash, hooks, servidores MCP stdio). O processo Claude pai mantém essas credenciais para chamadas de API, mas processos filhos não podem lê-las, reduzindo a exposição a ataques de injeção de prompt que tentam exfiltrar segredos via expansão de shell. No Linux, isso também executa subprocessos Bash em um namespace PID isolado para que não possam ler ambientes de processo do host via `/proc`; como efeito colateral, `ps`, `pgrep` e `kill` não podem ver ou sinalizar processos do host. `claude-code-action` define isso automaticamente quando `allowed_non_write_users` está configurado |

147| `CLAUDE_CODE_SYNC_PLUGIN_INSTALL` | Defina como `1` em modo não interativo (a flag `-p`) para aguardar a conclusão da instalação de plugin antes da primeira consulta. Sem isso, plugins instalam em segundo plano e podem não estar disponíveis na primeira volta. Combine com `CLAUDE_CODE_SYNC_PLUGIN_INSTALL_TIMEOUT_MS` para limitar a espera |153| `CLAUDE_CODE_SYNC_PLUGIN_INSTALL` | Defina como `1` em modo não interativo (a flag `-p`) para aguardar a conclusão da instalação de plugin antes da primeira consulta. Sem isso, plugins instalam em segundo plano e podem não estar disponíveis na primeira volta. Combine com `CLAUDE_CODE_SYNC_PLUGIN_INSTALL_TIMEOUT_MS` para limitar a espera |

148| `CLAUDE_CODE_SYNC_PLUGIN_INSTALL_TIMEOUT_MS` | Tempo limite em milissegundos para instalação síncrona de plugin. Quando excedido, Claude Code prossegue sem plugins e registra um erro. Sem padrão: sem essa variável, instalação síncrona aguarda até a conclusão |154| `CLAUDE_CODE_SYNC_PLUGIN_INSTALL_TIMEOUT_MS` | Tempo limite em milissegundos para instalação síncrona de plugin. Quando excedido, Claude Code prossegue sem plugins e registra um erro. Sem padrão: sem essa variável, instalação síncrona aguarda até a conclusão |

149| `CLAUDE_CODE_SYNTAX_HIGHLIGHT` | Defina como `false` para desabilitar destaque de sintaxe na saída de diff. Útil quando cores interferem com sua configuração de terminal |155| `CLAUDE_CODE_SYNTAX_HIGHLIGHT` | Defina como `false` para desabilitar destaque de sintaxe na saída de diff. Útil quando cores interferem com sua configuração de terminal. Para também desabilitar destaque em blocos de código e visualizações de arquivo, use a configuração [`syntaxHighlightingDisabled`](/pt/settings) |

150| `CLAUDE_CODE_TASK_LIST_ID` | Compartilhe uma lista de tarefas entre sessões. Defina o mesmo ID em múltiplas instâncias do Claude Code para coordenar em uma lista de tarefas compartilhada. Veja [Lista de tarefas](/pt/interactive-mode#task-list) |156| `CLAUDE_CODE_TASK_LIST_ID` | Compartilhe uma lista de tarefas entre sessões. Defina o mesmo ID em múltiplas instâncias do Claude Code para coordenar em uma lista de tarefas compartilhada. Veja [Lista de tarefas](/pt/interactive-mode#task-list) |

151| `CLAUDE_CODE_TEAM_NAME` | Nome da equipe de agentes à qual este companheiro pertence. Definido automaticamente em membros de [equipe de agentes](/pt/agent-teams) |157| `CLAUDE_CODE_TEAM_NAME` | Nome da equipe de agentes à qual este companheiro pertence. Definido automaticamente em membros de [equipe de agentes](/pt/agent-teams) |

152| `CLAUDE_CODE_TMPDIR` | Substitua o diretório temporário usado para arquivos temporários internos. Claude Code acrescenta `/claude-{uid}/` (Unix) ou `/claude/` (Windows) a este caminho. Padrão: `/tmp` em macOS, `os.tmpdir()` em Linux/Windows |158| `CLAUDE_CODE_TMPDIR` | Substitua o diretório temporário usado para arquivos temporários internos. Claude Code acrescenta `/claude-{uid}/` (Unix) ou `/claude/` (Windows) a este caminho. Padrão: `/tmp` em macOS, `os.tmpdir()` em Linux/Windows |

184| `DISABLE_TELEMETRY` | Defina como `1` para optar por não participar da telemetria Statsig (note que eventos Statsig não incluem dados do usuário como código, caminhos de arquivo ou comandos bash) |190| `DISABLE_TELEMETRY` | Defina como `1` para optar por não participar da telemetria. Eventos de telemetria não incluem dados do usuário como código, caminhos de arquivo ou comandos bash |

185| `DISABLE_UPDATES` | Defina como `1` para bloquear todas as atualizações, incluindo manual `claude update` e `claude install`. Mais rigoroso que `DISABLE_AUTOUPDATER`. Use ao distribuir Claude Code através de seus próprios canais e usuários não devem auto-atualizar |191| `DISABLE_UPDATES` | Defina como `1` para bloquear todas as atualizações, incluindo manual `claude update` e `claude install`. Mais rigoroso que `DISABLE_AUTOUPDATER`. Use ao distribuir Claude Code através de seus próprios canais e usuários não devem auto-atualizar |

187| `ENABLE_CLAUDEAI_MCP_SERVERS` | Defina como `false` para desabilitar [servidores MCP claude.ai](/pt/mcp#use-mcp-servers-from-claude-ai) no Claude Code. Habilitado por padrão para usuários conectados |193| `ENABLE_CLAUDEAI_MCP_SERVERS` | Defina como `false` para desabilitar [servidores MCP claude.ai](/pt/mcp#use-mcp-servers-from-claude-ai) no Claude Code. Habilitado por padrão para usuários conectados |

198| `MAX_STRUCTURED_OUTPUT_RETRIES` | Número de vezes para tentar novamente quando a resposta do modelo falha na validação contra o [`--json-schema`](/pt/cli-reference#cli-flags) em modo não interativo (a flag `-p`). Padrão é 5 |204| `MAX_STRUCTURED_OUTPUT_RETRIES` | Número de vezes para tentar novamente quando a resposta do modelo falha na validação contra o [`--json-schema`](/pt/cli-reference#cli-flags) em modo não interativo (a flag `-p`). Padrão é 5 |

199| `MAX_THINKING_TOKENS` | Substitua o orçamento de token de [pensamento estendido](https://platform.claude.com/docs/en/build-with-claude/extended-thinking). O teto é o [max output tokens](https://platform.claude.com/docs/en/about-claude/models/overview#latest-models-comparison) do modelo menos um. Defina como `0` para desabilitar pensamento inteiramente. Em modelos com [raciocínio adaptativo](/pt/model-config#adjust-effort-level), o orçamento é ignorado a menos que raciocínio adaptativo seja desabilitado via `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING` |205| `MAX_THINKING_TOKENS` | Substitua o orçamento de token de [pensamento estendido](https://platform.claude.com/docs/en/build-with-claude/extended-thinking). O teto é o [max output tokens](https://platform.claude.com/docs/en/about-claude/models/overview#latest-models-comparison) do modelo menos um. Defina como `0` para desabilitar pensamento inteiramente. Em modelos com [raciocínio adaptativo](/pt/model-config#adjust-effort-level), o orçamento é ignorado a menos que raciocínio adaptativo seja desabilitado via `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING` |

200| `MCP_CLIENT_SECRET` | Segredo do cliente OAuth para servidores MCP que requerem [credenciais pré-configuradas](/pt/mcp#use-pre-configured-oauth-credentials). Evita o prompt interativo ao adicionar um servidor com `--client-secret` |206| `MCP_CLIENT_SECRET` | Segredo do cliente OAuth para servidores MCP que requerem [credenciais pré-configuradas](/pt/mcp#use-pre-configured-oauth-credentials). Evita o prompt interativo ao adicionar um servidor com `--client-secret` |

201| `MCP_CONNECTION_NONBLOCKING` | Defina como `true` em modo não interativo (`-p`) para pular a espera de conexão MCP inteiramente. Útil para pipelines com script onde ferramentas MCP não são necessárias. Sem essa variável, a primeira consulta aguarda até 5 segundos para conexões de servidor `--mcp-config` |207| `MCP_CONNECTION_NONBLOCKING` | Defina como `true` em modo não interativo (`-p`) para pular a espera de conexão MCP inteiramente. Útil para pipelines com script onde ferramentas MCP não são necessárias. Sem essa variável, a primeira consulta aguarda até 5 segundos para conexões de servidor `--mcp-config`. Servidores configurados com [`alwaysLoad: true`](/pt/mcp#exempt-a-server-from-deferral) sempre bloqueiam a inicialização independentemente dessa variável, já que suas ferramentas devem estar presentes quando o primeiro prompt é construído |

202| `MCP_OAUTH_CALLBACK_PORT` | Porta fixa para o callback de redirecionamento OAuth, como alternativa a `--callback-port` ao adicionar um servidor MCP com [credenciais pré-configuradas](/pt/mcp#use-pre-configured-oauth-credentials) |208| `MCP_OAUTH_CALLBACK_PORT` | Porta fixa para o callback de redirecionamento OAuth, como alternativa a `--callback-port` ao adicionar um servidor MCP com [credenciais pré-configuradas](/pt/mcp#use-pre-configured-oauth-credentials) |

203| `MCP_REMOTE_SERVER_CONNECTION_BATCH_SIZE` | Número máximo de servidores MCP remotos (HTTP/SSE) para conectar em paralelo durante a inicialização (padrão: 20) |209| `MCP_REMOTE_SERVER_CONNECTION_BATCH_SIZE` | Número máximo de servidores MCP remotos (HTTP/SSE) para conectar em paralelo durante a inicialização (padrão: 20) |

204| `MCP_SERVER_CONNECTION_BATCH_SIZE` | Número máximo de servidores MCP locais (stdio) para conectar em paralelo durante a inicialização (padrão: 3) |210| `MCP_SERVER_CONNECTION_BATCH_SIZE` | Número máximo de servidores MCP locais (stdio) para conectar em paralelo durante a inicialização (padrão: 3) |

errors.md +28 −6

Details

11Esses erros e comandos de recuperação se aplicam em toda a CLI, no [aplicativo Desktop](/pt/desktop) e no [Claude Code na web](/pt/claude-code-on-the-web), já que todos os três envolvem a mesma CLI do Claude Code. Para problemas específicos da superfície, consulte a seção de solução de problemas na página dessa superfície.11Esses erros e comandos de recuperação se aplicam em toda a CLI, no [aplicativo Desktop](/pt/desktop) e no [Claude Code na web](/pt/claude-code-on-the-web), já que todos os três envolvem a mesma CLI do Claude Code. Para problemas específicos da superfície, consulte a seção de solução de problemas na página dessa superfície.

12 12

13<Note>13<Note>

14 O Claude Code chama a API Claude para respostas do modelo, portanto, a maioria dos erros de tempo de execução mapeia para um código de erro de API subjacente. Esta página cobre o que cada erro significa dentro do Claude Code e como se recuperar. Para as definições de código de status HTTP bruto, consulte a [referência de erro da plataforma Claude](https://platform.claude.com/docs/en/api/errors).14 O Claude Code chama a API Claude para respostas do modelo, portanto, a maioria dos erros de tempo de execução mapeia para um código de erro de API subjacente. Esta página cobre o que cada erro significa dentro do Claude Code e como se recuperar. Para as definições de código de status HTTP bruto, consulte a [referência de erro da plataforma Claude](https://platform.claude.com/docs/pt/api/errors).

15</Note>15</Note>

16 16

17## Encontre seu erro17## Encontre seu erro

38| `403` with `x-deny-reason: host_not_allowed` in a cloud or routine session | [Rede](#host-not-allowed-in-a-cloud-session) |

282 283

283## Erros de rede e conexão284## Erros de rede e conexão

284 285

285Esses erros significam que o Claude Code não conseguiu alcançar a API. Eles quase sempre se originam em sua rede local, proxy ou firewall em vez da infraestrutura Anthropic.286Esses erros significam que uma solicitação de rede do Claude Code não conseguiu alcançar seu destino. Eles geralmente se originam em sua rede local, proxy ou firewall, ou na política de rede do ambiente em nuvem.

286 287

287### Unable to connect to API288### Unable to connect to API

288 289

307* Certifique-se de que seu firewall permite os hosts listados em [Network access requirements](/pt/network-config#network-access-requirements)308* Certifique-se de que seu firewall permite os hosts listados em [Network access requirements](/pt/network-config#network-access-requirements)

308* Falhas intermitentes são [repetidas automaticamente](#automatic-retries); falhas persistentes apontam para um problema de rede local309* Falhas intermitentes são [repetidas automaticamente](#automatic-retries); falhas persistentes apontam para um problema de rede local

309 310

310Se `curl` for bem-sucedido mas o Claude Code ainda falhar, a causa geralmente é algo entre Node.js e a rede em vez da rede em si:311Se `curl` for bem-sucedido mas o Claude Code ainda falhar, a causa geralmente é algo entre o runtime e a rede em vez da rede em si:

311 312

312* No Linux e WSL, verifique `/etc/resolv.conf` para um servidor de nomes inacessível. WSL em particular pode herdar um resolvedor quebrado do host.313* No Linux e WSL, verifique `/etc/resolv.conf` para um servidor de nomes inacessível. WSL em particular pode herdar um resolvedor quebrado do host.

313* No macOS, um cliente VPN que foi desconectado ou desinstalado pode deixar uma interface de túnel ou regra de roteamento para trás. Verifique `ifconfig` para interfaces `utun` obsoletas e remova a extensão de rede da VPN em Configurações do Sistema.314* No macOS, um cliente VPN que foi desconectado ou desinstalado pode deixar uma interface de túnel ou regra de roteamento para trás. Verifique `ifconfig` para interfaces `utun` obsoletas e remova a extensão de rede da VPN em Configurações do Sistema.

315 316

316### SSL certificate errors317### SSL certificate errors

317 318

318Um proxy ou dispositivo de segurança em sua rede está interceptando tráfego TLS com seu próprio certificado, e Node.js não confia nele.319Um proxy ou dispositivo de segurança em sua rede está interceptando tráfego TLS com seu próprio certificado, e o Claude Code não confia nele.

319 320

320```text theme={null}321```text theme={null}

321Unable to connect to API: SSL certificate verification failed. Check your proxy or corporate SSL certificates322Unable to connect to API: SSL certificate verification failed. Check your proxy or corporate SSL certificates

324 325

325**O que fazer:**326**O que fazer:**

326 327

327* Exporte o pacote CA da sua organização e aponte Node para ele com `NODE_EXTRA_CA_CERTS=/path/to/ca-bundle.pem`328* Exporte o pacote CA da sua organização e aponte o Claude Code para ele com `NODE_EXTRA_CA_CERTS=/path/to/ca-bundle.pem`

328* Consulte [Network configuration](/pt/network-config#custom-ca-certificates) para instruções de configuração completas329* Consulte [Network configuration](/pt/network-config#custom-ca-certificates) para instruções de configuração completas

329* Não defina `NODE_TLS_REJECT_UNAUTHORIZED=0`, que desabilita completamente a validação de certificado330* Não defina `NODE_TLS_REJECT_UNAUTHORIZED=0`, que desabilita completamente a validação de certificado

330 331

332### Host not allowed in a cloud session

333

334Uma solicitação HTTP de saída de uma sessão em nuvem ou rotina foi bloqueada pela política de rede do ambiente.

335

336```text theme={null}

337HTTP 403

338x-deny-reason: host_not_allowed

339```

340

341Você também pode ver um certificado TLS que não corresponde ao certificado real do destino. O ambiente em nuvem roteia o tráfego de saída através de um proxy que aplica a política de rede, portanto um certificado incompatível significa que o proxy encerrou a conexão, não o destino.

342

343Isso não é um problema de rede do lado do cliente. As sessões em nuvem e [routines](/pt/routines) são executadas dentro de um ambiente sandboxed cuja tráfego de saída é filtrado para a lista de permissões do ambiente. O ambiente **Default** usa acesso **Trusted**, que permite a [lista de permissões padrão](/pt/claude-code-on-the-web#default-allowed-domains) de registros de pacotes, APIs de provedores de nuvem, registros de contêiner e domínios de desenvolvimento comuns, mas bloqueia tudo o mais.

344

345**O que fazer:**

346

347* Abra a rotina para edição ou inicie uma sessão em nuvem. Selecione o ícone de nuvem mostrando o nome do seu ambiente, como **Default**, para abrir o seletor. Passe o mouse sobre seu ambiente e clique no ícone de configurações.

348* Na caixa de diálogo **Update cloud environment**, altere **Network access** de **Trusted** para **Custom** e adicione o domínio bloqueado a **Allowed domains**. Digite um domínio por linha. Marque **Also include default list of common package managers** para manter a [lista de permissões padrão](/pt/claude-code-on-the-web#default-allowed-domains) junto com seus domínios personalizados. Selecione **Full** em vez disso se você quiser acesso irrestrito.

349* Clique em **Save changes**. A próxima execução usa a lista de permissões atualizada.

350

351Consulte [Network access](/pt/claude-code-on-the-web#network-access) para níveis de acesso e a lista de permissões padrão. As sessões locais da CLI não são afetadas por essa política.

352

331## Erros de solicitação353## Erros de solicitação

332 354

333Esses erros significam que a API recebeu sua solicitação mas rejeitou seu conteúdo.355Esses erros significam que a API recebeu sua solicitação mas rejeitou seu conteúdo.

487**O que fazer:**509**O que fazer:**

488 510

489* Reduza `MAX_THINKING_TOKENS`, ou aumente [`CLAUDE_CODE_MAX_OUTPUT_TOKENS`](/pt/env-vars) acima do orçamento de thinking511* Reduza `MAX_THINKING_TOKENS`, ou aumente [`CLAUDE_CODE_MAX_OUTPUT_TOKENS`](/pt/env-vars) acima do orçamento de thinking

490* Consulte [Extended thinking](/pt/common-workflows#use-extended-thinking-thinking-mode) para saber como o orçamento interage com o comprimento de saída512* Consulte [Extended thinking](/pt/model-config#extended-thinking) para saber como o orçamento interage com o comprimento de saída

491 513

492### Tool use or thinking block mismatch514### Tool use or thinking block mismatch

493 515

features-overview.md +3 −3

Details

221 221

222\*Por padrão, descrições de skill carregam no início da sessão para que Claude possa decidir quando usá-las. Defina `disable-model-invocation: true` no frontmatter de uma skill para ocultá-la de Claude inteiramente até que você a invoque manualmente. Isso reduz o custo de contexto para zero para skills que você só dispara você mesmo.222\*Por padrão, descrições de skill carregam no início da sessão para que Claude possa decidir quando usá-las. Defina `disable-model-invocation: true` no frontmatter de uma skill para ocultá-la de Claude inteiramente até que você a invoque manualmente. Isso reduz o custo de contexto para zero para skills que você só dispara você mesmo. Para uma skill que você não escreveu, defina [`skillOverrides`](/pt/skills#override-skill-visibility-from-settings) em configurações para fazer o mesmo sem editar seu arquivo.

223 223

224### Entender como os recursos carregam224### Entender como os recursos carregam

225 225

233 233

234 **O que carrega:** Conteúdo completo de todos os arquivos CLAUDE.md (níveis gerenciado, usuário e projeto).234 **O que carrega:** Conteúdo completo de todos os arquivos CLAUDE.md (níveis gerenciado, usuário e projeto).

235 235

236 **Herança:** Claude lê arquivos CLAUDE.md do seu diretório de trabalho até a raiz e descobre aninhados em subdiretórios conforme acessa esses arquivos. Consulte [Como arquivos CLAUDE.md carregam](/pt/memory#how-claudemd-files-load) para detalhes.236 **Herança:** Claude lê arquivos CLAUDE.md do seu diretório de trabalho até a raiz e descobre aninhados em subdiretórios conforme acessa esses arquivos. Consulte [Como arquivos CLAUDE.md carregam](/pt/memory#how-claude-md-files-load) para detalhes.

237 237

238 <Tip>Mantenha CLAUDE.md com menos de 200 linhas. Mova material de referência para skills, que carregam sob demanda.</Tip>238 <Tip>Mantenha CLAUDE.md com menos de 200 linhas. Mova material de referência para skills, que carregam sob demanda.</Tip>

239 </Tab>239 </Tab>

282 </Tab>282 </Tab>

283 283

284 <Tab title="Hooks">284 <Tab title="Hooks">

285 **Quando:** No disparo. Hooks disparam em eventos de ciclo de vida específicos como execução de ferramenta, limites de sessão, envio de prompt, solicitações de permissão e compactação. Consulte [Hooks](/pt/hooks-guide) para a lista completa.285 **Quando:** No disparo. Hooks disparam em eventos de ciclo de vida específicos como execução de ferramenta, limites de sessão, envio de prompt, solicitações de permissão e compactação. Consulte [Hooks](/pt/hooks) para a lista completa.

286 286

287 **O que carrega:** Nada por padrão. Hooks são executados fora da conversa principal.287 **O que carrega:** Nada por padrão. Hooks são executados fora da conversa principal.

288 288

fullscreen.md +10 −2

Details

93 93

94Um valor de `3` corresponde ao padrão em `vim` e aplicativos semelhantes. A configuração aceita valores de 1 a 20.94Um valor de `3` corresponde ao padrão em `vim` e aplicativos semelhantes. A configuração aceita valores de 1 a 20.

95 95

96### Rolagem no terminal do IDE JetBrains

98No terminal do IDE JetBrains, Claude Code aplica sua própria manipulação de rolagem e ignora `CLAUDE_CODE_SCROLL_SPEED`. O terminal envia eventos de rolagem em uma taxa muito mais alta do que outros emuladores, portanto um multiplicador ajustado em outro lugar ultrapassa aqui.

100Em 2025.2, o terminal também tem bugs de rolagem de roda que produzem teclas de seta espúrias e eventos de direção incorreta. Claude Code detecta esses em tempo de execução e os mitiga automaticamente, portanto a rolagem do trackpad e da roda do mouse funcionam sem configuração. Para a melhor experiência de rolagem, atualize para 2025.3 ou posterior. Claude Code mostra uma dica na primeira vez que você rola se detectar o bug.

101

96## Buscar e revisar a conversa102## Buscar e revisar a conversa

97 103

98`Ctrl+o` alterna entre o prompt normal e o modo de transcrição. Para uma visualização mais silenciosa que mostra apenas seu último prompt, um resumo de uma linha de chamadas de ferramenta com estatísticas de diff de edição e a resposta final, execute `/focus`. A configuração persiste entre sessões. Execute `/focus` novamente para desativá-la.104`Ctrl+o` alterna entre o prompt normal e o modo de transcrição. Para uma visualização mais silenciosa que mostra apenas seu último prompt, um resumo de uma linha de chamadas de ferramenta com estatísticas de diff de edição e a resposta final, execute `/focus`. A configuração persiste entre sessões. Execute `/focus` novamente para desativá-la.

122 128

123## Usar com tmux129## Usar com tmux

124 130

125A renderização em tela cheia funciona dentro do tmux, com duas ressalvas.131A renderização em tela cheia funciona dentro do tmux, com três ressalvas.

126 132

127A rolagem da roda do mouse requer o modo de mouse do tmux. Se seu `~/.tmux.conf` ainda não o ativa, adicione esta linha e recarregue sua configuração:133A rolagem da roda do mouse requer o modo de mouse do tmux. Se seu `~/.tmux.conf` ainda não o ativa, adicione esta linha e recarregue sua configuração:

128 134

134 140

135A renderização em tela cheia é incompatível com o modo de integração tmux do iTerm2, que é o modo que você entra com `tmux -CC`. No modo de integração, o iTerm2 renderiza cada painel tmux como uma divisão nativa em vez de deixar o tmux desenhar no terminal. O buffer de tela alternativa e o rastreamento de mouse não funcionam corretamente lá: a roda do mouse não faz nada e o clique duplo pode corromper o estado do terminal. Não ative a renderização em tela cheia em sessões `tmux -CC`. O tmux regular dentro do iTerm2, sem `-CC`, funciona bem.141A renderização em tela cheia é incompatível com o modo de integração tmux do iTerm2, que é o modo que você entra com `tmux -CC`. No modo de integração, o iTerm2 renderiza cada painel tmux como uma divisão nativa em vez de deixar o tmux desenhar no terminal. O buffer de tela alternativa e o rastreamento de mouse não funcionam corretamente lá: a roda do mouse não faz nada e o clique duplo pode corromper o estado do terminal. Não ative a renderização em tela cheia em sessões `tmux -CC`. O tmux regular dentro do iTerm2, sem `-CC`, funciona bem.

136 142

143O tmux não suporta saída sincronizada, portanto você pode ver mais cintilação durante redesenhos do que ao executar Claude Code diretamente em seu terminal. Se a cintilação for perceptível, especialmente via SSH, execute Claude Code em sua própria aba de terminal fora do tmux.

144

137## Manter seleção de texto nativa145## Manter seleção de texto nativa

138 146

139A captura de mouse é o ponto de atrito mais comum, especialmente sobre SSH ou dentro do tmux. Quando Claude Code captura eventos de mouse, a cópia nativa ao selecionar do seu terminal para de funcionar. A seleção que você faz com clique e arraste existe dentro do Claude Code, não no buffer de seleção do seu terminal, portanto o modo de cópia tmux, dicas do Kitty e ferramentas semelhantes não a veem.147A captura de mouse é o ponto de atrito mais comum, especialmente sobre SSH ou dentro do tmux. Quando Claude Code captura eventos de mouse, a cópia nativa ao selecionar do seu terminal para de funcionar. A seleção que você faz com clique e arraste existe dentro do Claude Code, não no buffer de seleção do seu terminal, portanto o modo de cópia tmux, dicas do Kitty e ferramentas semelhantes não a veem.

156 164

157Se encontrar um problema, execute `/feedback` dentro do Claude Code para relatá-lo, ou abra uma issue no [repositório GitHub claude-code](https://github.com/anthropics/claude-code/issues). Inclua o nome e a versão do seu emulador de terminal.165Se encontrar um problema, execute `/feedback` dentro do Claude Code para relatá-lo, ou abra uma issue no [repositório GitHub claude-code](https://github.com/anthropics/claude-code/issues). Inclua o nome e a versão do seu emulador de terminal.

158 166

159Para desativar a renderização em tela cheia, execute `/tui default`, ou desdefina a variável de ambiente se você a ativou dessa forma.167Para desativar a renderização em tela cheia, execute `/tui default`, ou desdefina `CLAUDE_CODE_NO_FLICKER` se você a ativou dessa forma. Para forçar o renderizador clássico independentemente da configuração `tui` salva, defina `CLAUDE_CODE_DISABLE_ALTERNATE_SCREEN=1`. O renderizador clássico mantém a conversa no scrollback nativo do seu terminal, portanto `Cmd+f` e o modo de cópia do tmux funcionam como de costume.

google-vertex-ai.md +22 −1

Details

266Claude Code v2.1.121 ou posterior suporta [Federação de Identidade de Carga de Trabalho baseada em certificado X.509](https://cloud.google.com/iam/docs/workload-identity-federation-with-x509-certificates) através da mesma cadeia de Credenciais Padrão da Aplicação. Defina `GOOGLE_APPLICATION_CREDENTIALS` para o caminho do seu arquivo de configuração de credenciais.266Claude Code v2.1.121 ou posterior suporta [Federação de Identidade de Carga de Trabalho baseada em certificado X.509](https://cloud.google.com/iam/docs/workload-identity-federation-with-x509-certificates) através da mesma cadeia de Credenciais Padrão da Aplicação. Defina `GOOGLE_APPLICATION_CREDENTIALS` para o caminho do seu arquivo de configuração de credenciais.

267 267

268<Note>268<Note>

269 Ao autenticar, Claude Code usará automaticamente o ID do projeto da variável de ambiente `ANTHROPIC_VERTEX_PROJECT_ID`. Para substituir isso, defina uma destas variáveis de ambiente: `GCLOUD_PROJECT`, `GOOGLE_CLOUD_PROJECT` ou `GOOGLE_APPLICATION_CREDENTIALS`.269 Claude Code usa `ANTHROPIC_VERTEX_PROJECT_ID` como o ID do projeto para solicitações Vertex AI. As variáveis de ambiente `GCLOUD_PROJECT` e `GOOGLE_CLOUD_PROJECT` e o arquivo de credenciais referenciado por `GOOGLE_APPLICATION_CREDENTIALS` têm precedência sobre ele. Se nenhum destes estiver definido, o ID do projeto é resolvido a partir da sua configuração `gcloud` ou da conta de serviço anexada.

270</Note>270</Note>

271 271

272#### Configuração avançada de credenciais

273

274Claude Code suporta atualização automática de credenciais para GCP através da configuração `gcpAuthRefresh`. Quando Claude Code detecta que suas credenciais GCP expiraram ou não podem ser carregadas, ele executa o comando configurado para obter novas credenciais antes de tentar novamente a solicitação.

275

276```json theme={null}

277{

278 "gcpAuthRefresh": "gcloud auth application-default login",

279 "env": {

280 "ANTHROPIC_VERTEX_PROJECT_ID": "your-project-id"

281 }

282}

283```

284

285A saída do comando é exibida ao usuário, mas entrada interativa não é suportada. Isso funciona bem para fluxos de autenticação baseados em navegador onde a CLI mostra uma URL e você completa a autenticação no navegador. O comando de atualização expira após três minutos se a autenticação não for concluída. Se você definir `gcpAuthRefresh` em configurações de projeto como `.claude/settings.json`, o comando é executado apenas após você aceitar o prompt de confiança do workspace.

286

272### 4. Configurar Claude Code287### 4. Configurar Claude Code

273 288

274Defina as seguintes variáveis de ambiente:289Defina as seguintes variáveis de ambiente:

363 378

364## Resolução de problemas379## Resolução de problemas

365 380

381Se você encontrar erros "Não foi possível carregar as credenciais padrão":

382

383* Execute `gcloud auth application-default login` para configurar Credenciais Padrão da Aplicação

384* Defina `GOOGLE_APPLICATION_CREDENTIALS` para um caminho de arquivo de chave de conta de serviço

385* Consulte [Configurar credenciais do GCP](#3-configure-gcp-credentials) para todas as opções

386

366Se você encontrar problemas de cota:387Se você encontrar problemas de cota:

367 388

368* Verifique cotas atuais ou solicite aumento de cota através do [Cloud Console](https://cloud.google.com/docs/quotas/view-manage)389* Verifique cotas atuais ou solicite aumento de cota através do [Cloud Console](https://cloud.google.com/docs/quotas/view-manage)

headless.md +33 −3

Details

54| Configurações | `--settings <file-or-json>` |54| Configurações | `--settings <file-or-json>` |

55| Servidores MCP | `--mcp-config <file-or-json>` |55| Servidores MCP | `--mcp-config <file-or-json>` |

56| Agentes personalizados | `--agents <json>` |56| Agentes personalizados | `--agents <json>` |

58 58

59O modo bare pula leituras de OAuth e keychain. A autenticação do Anthropic deve vir de `ANTHROPIC_API_KEY` ou um `apiKeyHelper` no JSON passado para `--settings`. Bedrock, Vertex e Foundry usam suas credenciais de provedor usuais.59O modo bare pula leituras de OAuth e keychain. A autenticação do Anthropic deve vir de `ANTHROPIC_API_KEY` ou um `apiKeyHelper` no JSON passado para `--settings`. Bedrock, Vertex e Foundry usam suas credenciais de provedor usuais.

60 60

66 66

67Estes exemplos destacam padrões comuns de CLI. Para CI e outras chamadas com script, adicione [`--bare`](#start-faster-with-bare-mode) para que não captem o que quer que esteja configurado localmente.67Estes exemplos destacam padrões comuns de CLI. Para CI e outras chamadas com script, adicione [`--bare`](#start-faster-with-bare-mode) para que não captem o que quer que esteja configurado localmente.

68 68

69### Canalizar dados através do Claude

71O modo não interativo lê stdin, então você pode canalizar dados e redirecionar a resposta como qualquer outra ferramenta de linha de comando.

73Este exemplo canaliza um log de compilação para Claude e escreve a explicação em um arquivo:

75```bash theme={null}

76cat build-error.txt | claude -p 'concisely explain the root cause of this build error' > output.txt

77```

79Com `--output-format json`, a carga de resposta inclui `total_cost_usd` e um detalhamento de custo por modelo, para que os chamadores com script possam rastrear gastos por invocação sem consultar o [painel de uso](/pt/costs).

81<Note>

82 A partir do Claude Code v2.1.128, stdin canalizado é limitado a 10MB. Se você exceder o limite, Claude Code sai com um erro claro e um status diferente de zero. Para trabalhar com entradas maiores, escreva o conteúdo em um arquivo e faça referência ao caminho do arquivo em seu prompt em vez de canalizá-lo.

83</Note>

85### Adicionar Claude a um script de compilação

87Você pode envolver uma chamada não interativa em um script para usar Claude como um linter ou revisor específico do projeto.

89Este script `package.json` canaliza o diff contra `main` para Claude e pede que ele relate erros de digitação. Canalizar o diff significa que Claude não precisa de permissão Bash para lê-lo, e as aspas duplas escapadas mantêm o script portável para Windows:

91```json theme={null}

92{

93 "scripts": {

94 "lint:claude": "git diff main | claude -p \"you are a typo linter. for each typo in this diff, report filename:line on one line and the issue on the next. return nothing else.\""

95 }

96}

97```

69### Obter saída estruturada99### Obter saída estruturada

70 100

71Use `--output-format` para controlar como as respostas são retornadas:101Use `--output-format` para controlar como as respostas são retornadas:

137O evento `system/init` relata metadados de sessão incluindo o modelo, ferramentas, servidores MCP e plugins carregados. É o primeiro evento no stream a menos que [`CLAUDE_CODE_SYNC_PLUGIN_INSTALL`](/pt/env-vars) esteja definido, caso em que eventos `plugin_install` o precedem. Use os campos de plugin para falhar CI quando um plugin não foi carregado:167O evento `system/init` relata metadados de sessão incluindo o modelo, ferramentas, servidores MCP e plugins carregados. É o primeiro evento no stream a menos que [`CLAUDE_CODE_SYNC_PLUGIN_INSTALL`](/pt/env-vars) esteja definido, caso em que eventos `plugin_install` o precedem. Use os campos de plugin para falhar CI quando um plugin não foi carregado:

138 168

140| --------------- | ----- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |170| --------------- | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

142| `plugin_errors` | array | erros de tempo de carregamento de plugin, como uma versão de dependência insatisfeita, cada um com `plugin`, `type` e `message`. Os plugins afetados são rebaixados e ausentes de `plugins`. A chave é omitida quando não há erros |172| `plugin_errors` | array | erros de tempo de carregamento de plugin, cada um com `plugin`, `type` e `message`. Inclui versões de dependência insatisfeitas e falhas de carregamento de `--plugin-dir` como um caminho ausente ou arquivo inválido. Os plugins afetados são rebaixados e ausentes de `plugins`. A chave é omitida quando não há erros |

143 173

144Quando [`CLAUDE_CODE_SYNC_PLUGIN_INSTALL`](/pt/env-vars) está definido, Claude Code emite eventos `system/plugin_install` enquanto plugins do marketplace instalam antes da primeira volta. Use estes para exibir o progresso de instalação em sua própria UI.174Quando [`CLAUDE_CODE_SYNC_PLUGIN_INSTALL`](/pt/env-vars) está definido, Claude Code emite eventos `system/plugin_install` enquanto plugins do marketplace instalam antes da primeira volta. Use estes para exibir o progresso de instalação em sua própria UI.

145 175

how-claude-code-works.md +9 −15

Details

94 94

95## Trabalhe com sessões95## Trabalhe com sessões

96 96

97Claude Code salva sua conversa localmente conforme você trabalha. Cada mensagem, uso de ferramenta e resultado é armazenado, o que permite [retroceder](#undo-changes-with-checkpoints), [retomar e bifurcar](#resume-or-fork-sessions) sessões. Antes de Claude fazer alterações de código, ele também tira um snapshot dos arquivos afetados para que você possa reverter se necessário.97Claude Code salva sua conversa localmente conforme você trabalha. Cada mensagem, uso de ferramenta e resultado é escrito em um arquivo JSONL em texto simples sob `~/.claude/projects/`, o que permite [retroceder](#undo-changes-with-checkpoints), [retomar e bifurcar](#resume-or-fork-sessions) sessões. Antes de Claude fazer alterações de código, ele também tira um snapshot dos arquivos afetados para que você possa reverter se necessário. Para caminhos, retenção e como limpar esses dados, consulte [dados de aplicação em `~/.claude`](/pt/claude-directory#application-data).

98 98

99**As sessões são independentes.** Cada nova sessão começa com uma janela de contexto fresca, sem o histórico de conversa de sessões anteriores. Claude pode persistir aprendizados entre sessões usando [auto memory](/pt/memory#auto-memory), e você pode adicionar suas próprias instruções persistentes em [CLAUDE.md](/pt/memory).99**As sessões são independentes.** Cada nova sessão começa com uma janela de contexto fresca, sem o histórico de conversa de sessões anteriores. Claude pode persistir aprendizados entre sessões usando [auto memory](/pt/memory#auto-memory), e você pode adicionar suas próprias instruções persistentes em [CLAUDE.md](/pt/memory).

100 100

101### Trabalhe entre branches101### Trabalhe entre branches

102 102

103Cada conversa de Claude Code é uma sessão vinculada ao seu diretório atual. Quando você retoma, você só vê sessões desse diretório.103Cada conversa de Claude Code é uma sessão vinculada ao seu diretório atual. O seletor `/resume` mostra sessões do worktree atual por padrão, com atalhos de teclado para ampliar a lista para outros worktrees ou projetos. Consulte [Gerenciar sessões](/pt/sessions#use-the-session-picker) para a lista completa de atalhos do seletor e como funciona a resolução de nomes.

104 104

105Claude vê os arquivos do seu branch atual. Quando você muda de branch, Claude vê os arquivos do novo branch, mas seu histórico de conversa permanece o mesmo. Claude se lembra do que você discutiu mesmo após mudar de branch.105Claude vê os arquivos do seu branch atual. Quando você muda de branch, Claude vê os arquivos do novo branch, mas seu histórico de conversa permanece o mesmo. Claude se lembra do que você discutiu mesmo após mudar de branch.

106 106

107Como as sessões estão vinculadas a diretórios, você pode executar sessões paralelas de Claude Code usando [git worktrees](/pt/common-workflows#run-parallel-claude-code-sessions-with-git-worktrees), que criam diretórios separados para branches individuais.107Como as sessões estão vinculadas a diretórios, você pode executar sessões paralelas de Claude Code usando [git worktrees](/pt/worktrees), que criam diretórios separados para branches individuais.

108 108

109### Retome ou bifurque sessões109### Retome ou bifurque sessões

110 110

111Quando você retoma uma sessão com `claude --continue` ou `claude --resume`, você continua de onde parou usando o mesmo ID de sessão. Novas mensagens são anexadas à conversa existente. Seu histórico de conversa completo é restaurado, mas as permissões com escopo de sessão não são. Você precisará re-aprovar essas.111Retomar uma sessão com `claude --continue` ou `claude --resume` reabre-a sob o mesmo ID de sessão e anexa novas mensagens à conversa existente. Bifurcar com `--fork-session` ou `/branch` copia o histórico em um novo ID de sessão, deixando o original inalterado.

112 112

113<img src="https://mintcdn.com/claude-code/c5r9_6tjPMzFdDDT/images/session-continuity.svg?fit=max&auto=format&n=c5r9_6tjPMzFdDDT&q=85&s=fa41d12bfb57579cabfeece907151d30" alt="Continuidade de sessão: retomar continua a mesma sessão, bifurcar cria um novo branch com um novo ID." width="560" height="280" data-path="images/session-continuity.svg" />113<img src="https://mintcdn.com/claude-code/c5r9_6tjPMzFdDDT/images/session-continuity.svg?fit=max&auto=format&n=c5r9_6tjPMzFdDDT&q=85&s=fa41d12bfb57579cabfeece907151d30" alt="Continuidade de sessão: retomar continua a mesma sessão, bifurcar cria um novo branch com um novo ID." width="560" height="280" data-path="images/session-continuity.svg" />

114 114

115Para ramificar e tentar uma abordagem diferente sem afetar a sessão original, use a flag `--fork-session`:115Para as flags de retomada, o seletor `/resume`, nomeação e o que acontece quando a mesma sessão está aberta em dois terminais, consulte [Gerenciar sessões](/pt/sessions).

~~116~~

117```bash theme={null}

118claude --continue --fork-session

119```

~~120~~

121Isso cria um novo ID de sessão enquanto preserva o histórico de conversa até esse ponto. A sessão original permanece inalterada. Como retomar, sessões bifurcadas não herdam permissões com escopo de sessão.

~~122~~

123**Mesma sessão em múltiplos terminais**: Se você retomar a mesma sessão em múltiplos terminais, ambos os terminais escrevem no mesmo arquivo de sessão. Mensagens de ambos ficam intercaladas, como duas pessoas escrevendo no mesmo caderno. Nada se corrompe, mas a conversa fica confusa. Cada terminal vê apenas suas próprias mensagens durante a sessão, mas se você retomar essa sessão mais tarde, verá tudo intercalado. Para trabalho paralelo a partir do mesmo ponto de partida, use `--fork-session` para dar a cada terminal sua própria sessão limpa.

124 116

125### A janela de contexto117### A janela de contexto

126 118

134 126

135Para controlar o que é preservado durante a compactação, adicione uma seção "Compact Instructions" a CLAUDE.md ou execute `/compact` com um foco (como `/compact focus on the API changes`).127Para controlar o que é preservado durante a compactação, adicione uma seção "Compact Instructions" a CLAUDE.md ou execute `/compact` com um foco (como `/compact focus on the API changes`).

136 128

129Se um único arquivo ou saída de ferramenta for tão grande que o contexto se reencheça imediatamente após cada resumo, Claude Code para de compactar automaticamente após algumas tentativas e mostra um erro em vez de fazer loop. Consulte [Auto-compactação para com um erro de thrashing](/pt/troubleshooting#auto-compaction-stops-with-a-thrashing-error) para etapas de recuperação.

130

137Execute `/context` para ver o que está usando espaço. Definições de ferramentas MCP são adiadas por padrão e carregadas sob demanda via [busca de ferramentas](/pt/mcp#scale-with-mcp-tool-search), então apenas nomes de ferramentas consomem contexto até Claude usar uma ferramenta específica. Execute `/mcp` para verificar custos por servidor.131Execute `/context` para ver o que está usando espaço. Definições de ferramentas MCP são adiadas por padrão e carregadas sob demanda via [busca de ferramentas](/pt/mcp#scale-with-mcp-tool-search), então apenas nomes de ferramentas consomem contexto até Claude usar uma ferramenta específica. Execute `/mcp` para verificar custos por servidor.

138 132

139#### Gerencie contexto com skills e subagents133#### Gerencie contexto com skills e subagents

140 134

141Além da compactação, você pode usar outros recursos para controlar o que é carregado no contexto.135Além da compactação, você pode usar outros recursos para controlar o que é carregado no contexto.

142 136

143[Skills](/pt/skills) carregam sob demanda. Claude vê descrições de skills no início da sessão, mas o conteúdo completo só carrega quando uma skill é usada. Para skills que você invoca manualmente, defina `disable-model-invocation: true` para manter descrições fora do contexto até que você precise delas.137[Skills](/pt/skills) carregam sob demanda. Claude vê descrições de skills no início da sessão, mas o conteúdo completo só carrega quando uma skill é usada. Para skills que você invoca manualmente, defina `disable-model-invocation: true` para manter descrições fora do contexto até que você precise delas. Para skills que você não escreveu, use [`skillOverrides`](/pt/skills#override-skill-visibility-from-settings) para fazer o mesmo a partir das configurações.

144 138

145[Subagents](/pt/sub-agents) obtêm seu próprio contexto fresco, completamente separado de sua conversa principal. Seu trabalho não incha seu contexto. Quando terminado, eles retornam um resumo. Esse isolamento é por que subagents ajudam em sessões longas.139[Subagents](/pt/sub-agents) obtêm seu próprio contexto fresco, completamente separado de sua conversa principal. Seu trabalho não incha seu contexto. Quando terminado, eles retornam um resumo. Esse isolamento é por que subagents ajudam em sessões longas.

146 140

161Pressione `Shift+Tab` para percorrer os modos de permissão:155Pressione `Shift+Tab` para percorrer os modos de permissão:

162 156

163* **Padrão**: Claude pergunta antes de edições de arquivo e comandos shell157* **Padrão**: Claude pergunta antes de edições de arquivo e comandos shell

164* **Auto-aceitar edições**: Claude edita arquivos sem perguntar, ainda pergunta por comandos158* **Auto-aceitar edições**: Claude edita arquivos e executa comandos comuns do sistema de arquivos como `mkdir` e `mv` sem perguntar, ainda pergunta por outros comandos

165* **Plan Mode**: Claude usa apenas ferramentas somente leitura, criando um plano que você pode aprovar antes da execução159* **Plan Mode**: Claude usa apenas ferramentas somente leitura, criando um plano que você pode aprovar antes da execução

166* **Auto mode**: Claude avalia todas as ações com verificações de segurança em segundo plano. Atualmente uma visualização de pesquisa160* **Auto mode**: Claude avalia todas as ações com verificações de segurança em segundo plano. Atualmente uma visualização de pesquisa

167 161

interactive-mode.md +6 −5

Details

11<Note>11<Note>

12 Os atalhos de teclado podem variar por plataforma e terminal. Pressione `?` para ver os atalhos disponíveis para seu ambiente.12 Os atalhos de teclado podem variar por plataforma e terminal. Pressione `?` para ver os atalhos disponíveis para seu ambiente.

13 13

~~14 **Usuários de macOS**: Os atalhos da tecla Option/Alt (`Alt+B`, `Alt+F`, `Alt+Y`, `Alt+M`, `Alt+P`, `Alt+T`) exigem configurar Option como Meta no seu terminal:~~14 **Usuários de macOS**: Os atalhos da tecla Option/Alt (`Alt+B`, `Alt+F`, `Alt+Y`, `Alt+M`, `Alt+P`) exigem configurar Option como Meta no seu terminal:

15 15

16 * **iTerm2**: Configurações → Profiles → Keys → General → defina Left/Right Option key para "Esc+"16 * **iTerm2**: Configurações → Profiles → Keys → General → defina Left/Right Option key para "Esc+"

17 * **Apple Terminal**: Configurações → Profiles → Keyboard → marque "Use Option as Meta Key"17 * **Apple Terminal**: Configurações → Profiles → Keyboard → marque "Use Option as Meta Key"

40| `Shift+Tab` ou `Alt+M` (algumas configurações) | Alternar modos de permissão | Alternar entre `default`, `acceptEdits`, `plan` e qualquer modo que você tenha ativado, como `auto` ou `bypassPermissions`. Veja [modos de permissão](/pt/permission-modes). |40| `Shift+Tab` ou `Alt+M` (algumas configurações) | Alternar modos de permissão | Alternar entre `default`, `acceptEdits`, `plan` e qualquer modo que você tenha ativado, como `auto` ou `bypassPermissions`. Veja [modos de permissão](/pt/permission-modes). |

42| `Option+T` (macOS) ou `Alt+T` (Windows/Linux) | Alternar pensamento estendido | Ativar ou desativar modo de pensamento estendido. No macOS, configure seu terminal para enviar Option como Meta para que este atalho funcione |42| `Option+T` (macOS) ou `Alt+T` (Windows/Linux) | Alternar pensamento estendido | Ativar ou desativar modo de pensamento estendido. A partir da v2.1.132, este atalho funciona no macOS sem configurar Option como Meta |

44 44

45### Edição de texto45### Edição de texto

68| :-------------------- | :---------------- | :------------------------------------------------------------------------------------------------ |68| :-------------------- | :---------------- | :------------------------------------------------------------------------------------------------ |

74 74

75<Tip>75<Tip>

76 Shift+Enter funciona sem configuração em iTerm2, WezTerm, Ghostty, Kitty, Warp e Apple Terminal. Para VS Code, Cursor, Windsurf, Alacritty e Zed, execute `/terminal-setup` para instalar o atalho.76 Shift+Enter funciona sem configuração em iTerm2, WezTerm, Ghostty, Kitty, Warp, Apple Terminal e Windows Terminal. Para VS Code, Cursor, Windsurf, Alacritty e Zed, execute `/terminal-setup` para instalar o atalho.

77</Tip>77</Tip>

78 78

79### Comandos rápidos79### Comandos rápidos

130| Comando | Ação |130| Comando | Ação |

131| :-------------- | :------------------------------------------------------- |131| :-------------- | :------------------------------------------------------- |

133| `Space` | Mover para a direita |

133| `w` | Próxima palavra |134| `w` | Próxima palavra |

134| `e` | Final da palavra |135| `e` | Final da palavra |

135| `b` | Palavra anterior |136| `b` | Palavra anterior |

2201. **Iniciar pesquisa**: pressione `Ctrl+R` para ativar pesquisa de histórico reverso2211. **Iniciar pesquisa**: pressione `Ctrl+R` para ativar pesquisa de histórico reverso

2212. **Digitar consulta**: insira texto para pesquisar em comandos anteriores. O termo de pesquisa é destacado nos resultados correspondentes2222. **Digitar consulta**: insira texto para pesquisar em comandos anteriores. O termo de pesquisa é destacado nos resultados correspondentes

2223. **Navegar correspondências**: pressione `Ctrl+R` novamente para ciclar através de correspondências mais antigas2233. **Navegar correspondências**: pressione `Ctrl+R` novamente para ciclar através de correspondências mais antigas

2234. **Mudar escopo**: pressione `Ctrl+S` para alternar entre esta sessão, este projeto e todos os projetos2244. **Mudar escopo**: a pesquisa padrão é de prompts de todos os projetos. Pressione `Ctrl+S` para alternar o escopo entre esta sessão, este projeto e todos os projetos

2245. **Aceitar correspondência**:2255. **Aceitar correspondência**:

225 * Pressione `Tab` ou `Esc` para aceitar a correspondência atual e continuar editando226 * Pressione `Tab` ou `Esc` para aceitar a correspondência atual e continuar editando

226 * Pressione `Enter` para aceitar e executar o comando imediatamente227 * Pressione `Enter` para aceitar e executar o comando imediatamente

llm-gateway.md +1 −1

Details

53 53

54Por padrão, Claude Code usa nomes de modelo padrão para o formato de API selecionado.54Por padrão, Claude Code usa nomes de modelo padrão para o formato de API selecionado.

55 55

56Quando `ANTHROPIC_BASE_URL` aponta para um gateway que expõe o formato Anthropic Messages, Claude Code consulta o endpoint `/v1/models` do gateway na inicialização e adiciona os modelos retornados ao seletor `/model`. Cada entrada descoberta é rotulada como "From gateway" e usa o campo `display_name` da resposta quando um é fornecido. Isso requer Claude Code v2.1.126 ou posterior.56Quando `ANTHROPIC_BASE_URL` aponta para um gateway que expõe o formato Anthropic Messages, Claude Code consulta o endpoint `/v1/models` do gateway na inicialização e adiciona os modelos retornados ao seletor `/model`. Defina `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1` para ativar isso. A descoberta está desativada por padrão para que gateways apoiados por uma chave de API compartilhada não exponham todos os modelos que a chave pode acessar para cada usuário. Cada entrada descoberta é rotulada como "From gateway" e usa o campo `display_name` da resposta quando um é fornecido. Isso requer Claude Code v2.1.129 ou posterior.

57 57

58A descoberta se aplica apenas ao formato Anthropic Messages. Ela não é executada para endpoints de passagem Bedrock ou Vertex, e não é executada quando `ANTHROPIC_BASE_URL` não está definido ou aponta para `api.anthropic.com`.58A descoberta se aplica apenas ao formato Anthropic Messages. Ela não é executada para endpoints de passagem Bedrock ou Vertex, e não é executada quando `ANTHROPIC_BASE_URL` não está definido ou aponta para `api.anthropic.com`.

59 59

mcp.md +11 −1

Details

327/mcp327/mcp

328```328```

329 329

330O painel `/mcp` mostra a contagem de ferramentas ao lado de cada servidor conectado e sinaliza servidores que anunciam a capacidade de ferramentas, mas não expõem nenhuma ferramenta.

331

332O nome do servidor `workspace` é reservado para uso interno. Se sua configuração define um servidor com esse nome, Claude Code o ignora no tempo de carregamento e mostra um aviso pedindo que você o renomeie.

333

330### Atualizações dinâmicas de ferramentas334### Atualizações dinâmicas de ferramentas

331 335

332Claude Code suporta notificações MCP `list_changed`, permitindo que servidores MCP atualizem dinamicamente suas ferramentas, prompts e recursos disponíveis sem exigir que você se desconecte e reconecte. Quando um servidor MCP envia uma notificação `list_changed`, Claude Code atualiza automaticamente as capacidades disponíveis desse servidor.336Claude Code suporta notificações MCP `list_changed`, permitindo que servidores MCP atualizem dinamicamente suas ferramentas, prompts e recursos disponíveis sem exigir que você se desconecte e reconecte. Quando um servidor MCP envia uma notificação `list_changed`, Claude Code atualiza automaticamente as capacidades disponíveis desse servidor.

423 427

424## Escopos de instalação de MCP428## Escopos de instalação de MCP

425 429

426Os servidores MCP podem ser configurados em três escopos diferentes dependendo de suas necessidades:430Os servidores MCP podem ser configurados em três escopos. O escopo que você escolhe controla em quais projetos o servidor é carregado e se a configuração é compartilhada com sua equipe. Os administradores também podem implantar servidores no nível empresarial via [configuração gerenciada](#managed-mcp-configuration).

427 431

429| ------------------------- | ---------------------- | --------------------------- | ------------------------------ |433| ------------------------- | ---------------------- | --------------------------- | ------------------------------ |

944 </Step>948 </Step>

945</Steps>949</Steps>

946 950

951Um servidor que você adicionou no Claude Code tem [precedência](#scope-hierarchy-and-precedence) sobre um conector do claude.ai que aponta para a mesma URL. Quando isso acontece, `/mcp` lista o conector como oculto e mostra como remover a duplicata se você preferir usar o conector.

952

947Para desabilitar servidores MCP do claude.ai no Claude Code, defina a variável de ambiente `ENABLE_CLAUDEAI_MCP_SERVERS` como `false`:953Para desabilitar servidores MCP do claude.ai no Claude Code, defina a variável de ambiente `ENABLE_CLAUDEAI_MCP_SERVERS` como `false`:

948 954

949```bash theme={null}955```bash theme={null}

1183 1189

1184O campo `alwaysLoad` está disponível em todos os tipos de servidor e requer Claude Code v2.1.121 ou posterior. Um servidor MCP também pode marcar ferramentas individuais como sempre carregadas incluindo `"anthropic/alwaysLoad": true` no objeto `_meta` da ferramenta, que tem o mesmo efeito apenas para essa ferramenta.1190O campo `alwaysLoad` está disponível em todos os tipos de servidor e requer Claude Code v2.1.121 ou posterior. Um servidor MCP também pode marcar ferramentas individuais como sempre carregadas incluindo `"anthropic/alwaysLoad": true` no objeto `_meta` da ferramenta, que tem o mesmo efeito apenas para essa ferramenta.

1185 1191

1192Definir `alwaysLoad: true` também bloqueia a inicialização até que o servidor se conecte, limitado ao tempo limite de conexão padrão de 5 segundos. Isso se aplica mesmo quando [`MCP_CONNECTION_NONBLOCKING=1`](/pt/env-vars) está definido, já que as ferramentas devem estar presentes quando o primeiro prompt é construído. Outros servidores ainda se conectam em segundo plano quando o modo não bloqueante está habilitado.

1193

1186## Usar prompts MCP como comandos1194## Usar prompts MCP como comandos

1187 1195

1188Os servidores MCP podem expor prompts que se tornam disponíveis como comandos no Claude Code.1196Os servidores MCP podem expor prompts que se tornam disponíveis como comandos no Claude Code.

1351* `https://*.example.com/*` - Permitir qualquer subdomínio de example.com1359* `https://*.example.com/*` - Permitir qualquer subdomínio de example.com

1352* `http://localhost:*/*` - Permitir qualquer porta em localhost1360* `http://localhost:*/*` - Permitir qualquer porta em localhost

1353 1361

1362A correspondência de nome de host é insensível a maiúsculas e minúsculas e ignora um ponto FQDN à direita, correspondendo à semântica de DNS. Um padrão como `*://Mcp.Example.com/*` corresponde a `https://mcp.example.com/api`, e `https://mcp.example.com.` é tratado da mesma forma que `https://mcp.example.com`. Esquemas e caminhos permanecem sensíveis a maiúsculas e minúsculas.

1363

1354**Comportamento do servidor remoto**:1364**Comportamento do servidor remoto**:

1355 1365

1356* Quando a lista de permissão contém **qualquer** entrada `serverUrl`, servidores remotos **devem** corresponder a um desses padrões de URL1366* Quando a lista de permissão contém **qualquer** entrada `serverUrl`, servidores remotos **devem** corresponder a um desses padrões de URL

memory.md +2 −0

Details

378* Torne as instruções mais específicas. "Use indentação de 2 espaços" funciona melhor do que "formate o código adequadamente."378* Torne as instruções mais específicas. "Use indentação de 2 espaços" funciona melhor do que "formate o código adequadamente."

379* Procure por instruções conflitantes entre arquivos CLAUDE.md. Se dois arquivos dão orientação diferente para o mesmo comportamento, Claude pode escolher um arbitrariamente.379* Procure por instruções conflitantes entre arquivos CLAUDE.md. Se dois arquivos dão orientação diferente para o mesmo comportamento, Claude pode escolher um arbitrariamente.

380 380

381Se a instrução é algo que deve ser executado em um ponto específico, como antes de cada commit ou após cada edição de arquivo, escreva-a como um [hook](/pt/hooks-guide) em vez disso. Hooks são executados como comandos shell em eventos de ciclo de vida fixos e se aplicam independentemente do que Claude decidir fazer.

382

381Para instruções que você quer no nível do prompt do sistema, use [`--append-system-prompt`](/pt/cli-reference#system-prompt-flags). Isso deve ser passado a cada invocação, então é mais adequado para scripts e automação do que para uso interativo.383Para instruções que você quer no nível do prompt do sistema, use [`--append-system-prompt`](/pt/cli-reference#system-prompt-flags). Isso deve ser passado a cada invocação, então é mais adequado para scripts e automação do que para uso interativo.

382 384

383<Tip>385<Tip>

model-config.md +18 −4

Details

184 184

185A escala de esforço é calibrada por modelo, portanto o mesmo nome de nível não representa o mesmo valor subjacente entre modelos.185A escala de esforço é calibrada por modelo, portanto o mesmo nome de nível não representa o mesmo valor subjacente entre modelos.

186 186

187Para raciocínio profundo único sem alterar sua configuração de sessão, inclua "ultrathink" em seu prompt. Isso adiciona uma instrução no contexto dizendo ao modelo para raciocinar mais nessa vez; não altera o nível de esforço enviado para a API.187#### Usar ultrathink para raciocínio profundo único

188

189Inclua `ultrathink` em qualquer lugar em seu prompt para solicitar raciocínio mais profundo nessa volta sem alterar sua configuração de esforço de sessão. Claude Code reconhece a palavra-chave e adiciona uma instrução no contexto. O nível de esforço enviado para a API permanece inalterado. Outras frases como "think", "think hard" e "think more" são passadas como texto de prompt ordinário e não são reconhecidas como palavras-chave.

188 190

189#### Definir o nível de esforço191#### Definir o nível de esforço

190 192

209 211

210Em Opus 4.6 e Sonnet 4.6, você pode definir `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=1` para reverter para o orçamento de pensamento fixo anterior controlado por `MAX_THINKING_TOKENS`. Veja [variáveis de ambiente](/pt/env-vars).212Em Opus 4.6 e Sonnet 4.6, você pode definir `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=1` para reverter para o orçamento de pensamento fixo anterior controlado por `MAX_THINKING_TOKENS`. Veja [variáveis de ambiente](/pt/env-vars).

211 213

214### Pensamento estendido

215

216Pensamento estendido é o raciocínio que Claude emite antes de responder. Em modelos que suportam [raciocínio adaptativo](#adjust-effort-level), o nível de esforço é o controle principal para quanto pensamento acontece; as configurações abaixo ativam ou desativam o pensamento e controlam como ele é exibido.

217

218| Controle | Como defini-lo |

219| :--------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

220| Alternar para a sessão atual | Pressione `Option+T` no macOS ou `Alt+T` no Windows e Linux |

221| Definir o padrão global | Execute `/config` e alterne o modo de pensamento. Salvo como `alwaysThinkingEnabled` em `~/.claude/settings.json` |

222| Desabilitar independentemente do esforço | Defina [`MAX_THINKING_TOKENS=0`](/pt/env-vars). Outros valores se aplicam apenas com um [orçamento de pensamento fixo](#adaptive-reasoning-and-fixed-thinking-budgets) |

223

224A saída de pensamento é recolhida por padrão. Pressione `Ctrl+O` para alternar o modo verboso e ver o raciocínio como texto em itálico cinzento. Sessões interativas na API Anthropic recebem blocos de pensamento redigidos por padrão, portanto defina `showThinkingSummaries: true` em [configurações](/pt/settings) se você quiser os resumos completos disponíveis quando expandir. Você é cobrado por todos os tokens de pensamento gerados, mesmo quando recolhidos ou redigidos.

225

212### Contexto estendido226### Contexto estendido

213 227

214Opus 4.7, Opus 4.6 e Sonnet 4.6 suportam uma [janela de contexto de 1 milhão de tokens](https://platform.claude.com/docs/pt/build-with-claude/context-windows#1m-token-context-window) para sessões longas com grandes bases de código.228Opus 4.7, Opus 4.6 e Sonnet 4.6 suportam uma [janela de contexto de 1 milhão de tokens](https://platform.claude.com/docs/pt/build-with-claude/context-windows#1m-token-context-window) para sessões longas com grandes bases de código.

247 261

248## Adicionar uma opção de modelo personalizado262## Adicionar uma opção de modelo personalizado

249 263

250Use `ANTHROPIC_CUSTOM_MODEL_OPTION` para adicionar uma única entrada personalizada ao seletor `/model` sem substituir os aliases integrados. Isso é útil para testar IDs de modelo que Claude Code não lista por padrão. Para implantações de gateway LLM, Claude Code popula o seletor automaticamente a partir do endpoint `/v1/models` do gateway, portanto essa variável é necessária apenas quando a descoberta não retorna o modelo que você deseja. Consulte [Seleção de modelo de gateway LLM](/pt/llm-gateway#model-selection).264Use `ANTHROPIC_CUSTOM_MODEL_OPTION` para adicionar uma única entrada personalizada ao seletor `/model` sem substituir os aliases integrados. Isso é útil para testar IDs de modelo que Claude Code não lista por padrão. Para implantações de gateway LLM, Claude Code pode preencher o seletor a partir do endpoint `/v1/models` do gateway quando `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1` está definido, portanto essa variável é necessária apenas quando a descoberta está desabilitada ou não retorna o modelo que você deseja. Consulte [Seleção de modelo de gateway LLM](/pt/llm-gateway#model-selection).

251 265

252Este exemplo define todas as três variáveis para tornar uma implantação Opus roteada por gateway selecionável:266Este exemplo define todas as três variáveis para tornar uma implantação Opus roteada por gateway selecionável:

253 267

320 334

321Os mesmos sufixos `_NAME`, `_DESCRIPTION` e `_SUPPORTED_CAPABILITIES` estão disponíveis para `ANTHROPIC_DEFAULT_SONNET_MODEL`, `ANTHROPIC_DEFAULT_HAIKU_MODEL` e `ANTHROPIC_CUSTOM_MODEL_OPTION`.335Os mesmos sufixos `_NAME`, `_DESCRIPTION` e `_SUPPORTED_CAPABILITIES` estão disponíveis para `ANTHROPIC_DEFAULT_SONNET_MODEL`, `ANTHROPIC_DEFAULT_HAIKU_MODEL` e `ANTHROPIC_CUSTOM_MODEL_OPTION`.

322 336

323Claude Code habilita recursos como [níveis de esforço](#adjust-effort-level) e [pensamento estendido](/pt/common-workflows#use-extended-thinking-thinking-mode) correspondendo o ID do modelo contra padrões conhecidos. IDs específicos do provedor, como ARNs Bedrock ou nomes de implantação personalizados, geralmente não correspondem a esses padrões, deixando recursos suportados desabilitados. Defina `_SUPPORTED_CAPABILITIES` para informar ao Claude Code quais recursos o modelo realmente suporta:337Claude Code habilita recursos como [níveis de esforço](#adjust-effort-level) e [pensamento estendido](#extended-thinking) correspondendo o ID do modelo contra padrões conhecidos. IDs específicos do provedor, como ARNs Bedrock ou nomes de implantação personalizados, geralmente não correspondem a esses padrões, deixando recursos suportados desabilitados. Defina `_SUPPORTED_CAPABILITIES` para informar ao Claude Code quais recursos o modelo realmente suporta:

324 338

325| Valor de capacidade | Habilita |339| Valor de capacidade | Habilita |

326| ---------------------- | --------------------------------------------------------------------------------------------- |340| ---------------------- | --------------------------------------------------------------------------------------------- |

328| `xhigh_effort` | {/* min-version: 2.1.111 */}O nível de esforço `xhigh` |342| `xhigh_effort` | {/* min-version: 2.1.111 */}O nível de esforço `xhigh` |

333 347

monitoring-usage.md +18 −7

Details

64 As configurações gerenciadas podem ser distribuídas via MDM (Mobile Device Management) ou outras soluções de gerenciamento de dispositivos. As variáveis de ambiente definidas no arquivo de configurações gerenciadas têm alta precedência e não podem ser substituídas pelos usuários.64 As configurações gerenciadas podem ser distribuídas via MDM (Mobile Device Management) ou outras soluções de gerenciamento de dispositivos. As variáveis de ambiente definidas no arquivo de configurações gerenciadas têm alta precedência e não podem ser substituídas pelos usuários.

65</Note>65</Note>

66 66

67Claude Code não passa variáveis de ambiente `OTEL_*` para os subprocessos que ele gera, incluindo a ferramenta Bash, hooks, servidores MCP e servidores de linguagem. Um aplicativo instrumentado com OpenTelemetry que você executa através da ferramenta Bash não herda o endpoint do exportador ou cabeçalhos do Claude Code, então defina essas variáveis diretamente no comando se esse aplicativo precisar exportar sua própria telemetria.

67## Detalhes de configuração69## Detalhes de configuração

68 70

69### Variáveis de configuração comuns71### Variáveis de configuração comuns

83| `OTEL_EXPORTER_OTLP_METRICS_CLIENT_KEY` | Chave do cliente para autenticação mTLS | Caminho para arquivo de chave do cliente |

84| `OTEL_EXPORTER_OTLP_METRICS_CLIENT_CERTIFICATE` | Certificado do cliente para autenticação mTLS | Caminho para arquivo de certificado do cliente |

85| `OTEL_METRIC_EXPORT_INTERVAL` | Intervalo de exportação em milissegundos (padrão: 60000) | `5000`, `60000` |85| `OTEL_METRIC_EXPORT_INTERVAL` | Intervalo de exportação em milissegundos (padrão: 60000) | `5000`, `60000` |

86| `OTEL_LOGS_EXPORT_INTERVAL` | Intervalo de exportação de logs em milissegundos (padrão: 5000) | `1000`, `10000` |86| `OTEL_LOGS_EXPORT_INTERVAL` | Intervalo de exportação de logs em milissegundos (padrão: 5000) | `1000`, `10000` |

91| `OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE` | Preferência de temporalidade de métricas (padrão: `delta`). Defina como `cumulative` se seu backend espera temporalidade cumulativa | `delta`, `cumulative` |91| `OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE` | Preferência de temporalidade de métricas (padrão: `delta`). Defina como `cumulative` se seu backend espera temporalidade cumulativa | `delta`, `cumulative` |

92| `CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS` | Intervalo para atualizar cabeçalhos dinâmicos (padrão: 1740000ms / 29 minutos) | `900000` |92| `CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS` | Intervalo para atualizar cabeçalhos dinâmicos (padrão: 1740000ms / 29 minutos) | `900000` |

93 93

94### Autenticação mTLS

96Como você configura certificados de cliente para o exportador OTLP depende do protocolo OTLP em uso para esse sinal, definido via `OTEL_EXPORTER_OTLP_PROTOCOL` ou a substituição por sinal. A mesma configuração se aplica a métricas, logs e rastreamentos.

98| Protocolo | Variáveis de certificado do cliente | Confiar na CA do coletor com |

99| :--------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------- |

100| `http/protobuf`, `http/json` | `CLAUDE_CODE_CLIENT_CERT`, `CLAUDE_CODE_CLIENT_KEY` e opcionalmente `CLAUDE_CODE_CLIENT_KEY_PASSPHRASE`. Veja [Configuração de rede](/pt/network-config#mtls-authentication) | `NODE_EXTRA_CA_CERTS` |

101| `grpc` | `OTEL_EXPORTER_OTLP_CLIENT_KEY` e `OTEL_EXPORTER_OTLP_CLIENT_CERTIFICATE`, ou as variantes por sinal como `OTEL_EXPORTER_OTLP_METRICS_CLIENT_KEY` para usar um certificado diferente por sinal | `OTEL_EXPORTER_OTLP_CERTIFICATE` |

102

103Para `grpc`, o SDK OpenTelemetry lê as variáveis OTLP padrão diretamente, então as configurações existentes que definem as variáveis de métricas por sinal continuam funcionando.

104

94### Controle de cardinalidade de métricas105### Controle de cardinalidade de métricas

95 106

96As seguintes variáveis de ambiente controlam quais atributos são incluídos nas métricas para gerenciar a cardinalidade:107As seguintes variáveis de ambiente controlam quais atributos são incluídos nas métricas para gerenciar a cardinalidade:

107 118

108O rastreamento distribuído exporta spans que vinculam cada prompt do usuário às solicitações de API e execuções de ferramentas que ele dispara, para que você possa visualizar uma solicitação completa como um único rastreamento no seu backend de rastreamento.119O rastreamento distribuído exporta spans que vinculam cada prompt do usuário às solicitações de API e execuções de ferramentas que ele dispara, para que você possa visualizar uma solicitação completa como um único rastreamento no seu backend de rastreamento.

109 120

110O rastreamento está desativado por padrão. Para ativá-lo, defina tanto `CLAUDE_CODE_ENABLE_TELEMETRY=1` quanto `CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1`, depois defina `OTEL_TRACES_EXPORTER` para escolher para onde os spans são enviados. Os rastreamentos reutilizam a [configuração OTLP comum](#variáveis-de-configuração-comuns) para endpoint, protocolo e cabeçalhos.121O rastreamento está desativado por padrão. Para ativá-lo, defina tanto `CLAUDE_CODE_ENABLE_TELEMETRY=1` quanto `CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1`, depois defina `OTEL_TRACES_EXPORTER` para escolher para onde os spans são enviados. Os rastreamentos reutilizam a [configuração OTLP comum](#variáveis-de-configuração-comuns) para endpoint, protocolo, cabeçalhos e [mTLS](#autenticação-mtls).

111 122

113| ------------------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------ |124| ------------------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------ |

198**`claude_code.tool.blocked_on_user`**209**`claude_code.tool.blocked_on_user`**

199 210

201| ------------- | -------------------------------------------------------------------------------------- | -------------- |212| ------------- | -------------------------------------------------------------------------------------------------------------- | -------------- |

205 216

206**`claude_code.tool.execution`**217**`claude_code.tool.execution`**

207 218

233 244

234### Cabeçalhos dinâmicos245### Cabeçalhos dinâmicos

235 246

236Para ambientes corporativos que exigem autenticação dinâmica, você pode configurar um script para gerar cabeçalhos dinamicamente:247Para ambientes corporativos que exigem autenticação dinâmica, você pode configurar um script para gerar cabeçalhos dinamicamente. Cabeçalhos dinâmicos se aplicam apenas aos protocolos `http/protobuf` e `http/json`. O exportador `grpc` usa apenas o valor estático `OTEL_EXPORTER_OTLP_HEADERS`.

237 248

238#### Configuração de configurações249#### Configuração de configurações

239 250

410 421

411#### Contador de pull request422#### Contador de pull request

412 423

413Incrementado ao criar pull requests via Claude Code.424Incrementado quando Claude Code cria um pull request ou merge request através de um comando shell ou uma ferramenta MCP.

414 425

415**Atributos**:426**Atributos**:

416 427

output-styles.md +12 −3

Details

6 6

7> Adapte Claude Code para usos além da engenharia de software7> Adapte Claude Code para usos além da engenharia de software

8 8

~~9Os estilos de saída permitem que você use Claude Code como qualquer tipo de agente, mantendo suas capacidades principais, como executar scripts locais, ler/escrever arquivos e rastrear TODOs.~~9Os estilos de saída alteram como Claude responde, não o que Claude sabe. Eles modificam o prompt do sistema para definir papel, tom e formato de saída, mantendo capacidades principais como executar scripts, ler e escrever arquivos e rastrear TODOs. Use um quando você continua re-solicitando a mesma voz ou formato a cada turno, ou quando você quer que Claude atue como algo diferente de um engenheiro de software.

11Para instruções sobre seu projeto, convenções ou base de código, use [CLAUDE.md](/pt/memory) em vez disso.

10 12

11## Estilos de saída integrados13## Estilos de saída integrados

12 14

63[Define how the assistant should behave in this style...]65[Define how the assistant should behave in this style...]

64```66```

65 67

~~66Você pode salvar esses arquivos no nível do usuário (`~/.claude/output-styles`) ou no nível do projeto (`.claude/output-styles`).~~68Você pode salvar esses arquivos em três níveis:

70* Usuário: `~/.claude/output-styles`

71* Projeto: `.claude/output-styles`

72* Política gerenciada: `.claude/output-styles` dentro do [diretório de configurações gerenciadas](/pt/settings#settings-files)

74[Plugins](/pt/plugins-reference) também podem enviar estilos de saída em um diretório `output-styles/`.

67 75

68### Frontmatter76### Frontmatter

69 77

70Os arquivos de estilo de saída suportam frontmatter para especificar metadados:78Os arquivos de estilo de saída suportam frontmatter para especificar metadados:

71 79

~~73| :------------------------- | :--------------------------------------------------------------------------------------- | :----------------------- |~~81| :------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------- |

85| `force-for-plugin` | Apenas estilos de saída de plugin: aplique este estilo automaticamente sempre que o plugin estiver habilitado, sem exigir que os usuários o selecionem. Substitui a configuração `outputStyle` do usuário. Se vários plugins habilitados definirem isso, o primeiro carregado vence. | false |

77 86

78## Comparações com recursos relacionados87## Comparações com recursos relacionados

79 88

plugins.md +6 −0

Details

315 ```315 ```

316</Tip>316</Tip>

317 317

318Para testar um plugin que já está empacotado como um arquivo `.zip` e hospedado em uma URL, como um artefato de compilação de CI, use `--plugin-url` em vez disso. Claude Code busca o arquivo no início e o carrega apenas para essa sessão. Se a busca falhar ou o arquivo for inválido, Claude Code relata um erro de carregamento de plugin e inicia sem ele. As mesmas [considerações de confiança](/pt/discover-plugins#security) se aplicam como para qualquer fonte de plugin: apenas aponte esse flag para arquivos que você controla ou confia.

319

320```bash theme={null}

321claude --plugin-url https://example.com/my-plugin.zip

322```

323

318### Depure problemas de plugin324### Depure problemas de plugin

319 325

320Se seu plugin não está funcionando como esperado:326Se seu plugin não está funcionando como esperado:

plugins-reference.md +15 −9

Details

301]301]

302```302```

303 303

304Para declarar monitors inline, defina a chave `monitors` em `plugin.json` para o mesmo array. Para carregar de um caminho não padrão, defina `monitors` para uma string de caminho relativo como `"./config/monitors.json"`.304Para declarar monitors inline, defina `experimental.monitors` em `plugin.json` para o mesmo array. Para carregar de um caminho não padrão, defina `experimental.monitors` para uma string de caminho relativo como `"./config/monitors.json"`. Monitors são um [componente experimental](#experimental-components).

305 305

306**Campos obrigatórios:**306**Campos obrigatórios:**

307 307

323 323

324### Themes324### Themes

325 325

326Os plugins podem fornecer temas de cor que aparecem em `/theme` ao lado das predefinições integradas e dos temas locais do usuário. Um tema é um arquivo JSON em `themes/` com uma predefinição `base` e um mapa esparso `overrides` de tokens de cor.326Os plugins podem fornecer temas de cor que aparecem em `/theme` ao lado das predefinições integradas e dos temas locais do usuário. Um tema é um arquivo JSON em `themes/` com uma predefinição `base` e um mapa esparso `overrides` de tokens de cor. Themes são um [componente experimental](#experimental-components).

327 327

328```json theme={null}328```json theme={null}

329{329{

384 "hooks": "./config/hooks.json",384 "hooks": "./config/hooks.json",

385 "mcpServers": "./mcp-config.json",385 "mcpServers": "./mcp-config.json",

386 "outputStyles": "./styles/",386 "outputStyles": "./styles/",

387 "themes": "./themes/",

388 "lspServers": "./.lsp.json",387 "lspServers": "./.lsp.json",

389 "monitors": "./monitors.json",388 "experimental": {

389 "themes": "./themes/",

390 "monitors": "./monitors.json"

391 },

390 "dependencies": [392 "dependencies": [

391 "helper-lib",393 "helper-lib",

392 { "name": "secrets-vault", "version": "~2.1.0" }394 { "name": "secrets-vault", "version": "~2.1.0" }

420### Campos de caminho de componente422### Campos de caminho de componente

421 423

423| :------------- | :-------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------- |425| :---------------------- | :-------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------- |

435| `dependencies` | array | Outros plugins que este plugin requer, opcionalmente com restrições de versão semver. Veja [Restringir versões de dependência de plugin](/pt/plugin-dependencies) | `[{ "name": "secrets-vault", "version": "~2.1.0" }]` |437| `dependencies` | array | Outros plugins que este plugin requer, opcionalmente com restrições de versão semver. Veja [Restringir versões de dependência de plugin](/pt/plugin-dependencies) | `[{ "name": "secrets-vault", "version": "~2.1.0" }]` |

436 438

439### Componentes experimentais

440

441Componentes sob a chave `experimental`, `themes` e `monitors`, têm um esquema de manifesto que pode mudar entre versões enquanto se estabilizam. Onde você os declara é uma migração separada: o nível superior ainda funciona, `claude plugin validate` avisa, e uma versão futura exigirá `experimental.*`.

442

437### Configuração do usuário443### Configuração do usuário

438 444

439O campo `userConfig` declara valores que Claude Code solicita ao usuário quando o plugin é habilitado. Use isso em vez de exigir que os usuários editem manualmente `settings.json`.445O campo `userConfig` declara valores que Claude Code solicita ao usuário quando o plugin é habilitado. Use isso em vez de exigir que os usuários editem manualmente `settings.json`.

504 510

505### Regras de comportamento de caminho511### Regras de comportamento de caminho

506 512

507Para `skills`, `commands`, `agents`, `outputStyles`, `themes` e `monitors`, um caminho personalizado substitui o padrão. Se o manifesto especificar `skills`, o diretório padrão `skills/` não é verificado; se especificar `monitors`, o padrão `monitors/monitors.json` não é carregado. [Hooks](#hooks), [MCP servers](#mcp-servers) e [LSP servers](#lsp-servers) têm semântica diferente para lidar com múltiplas fontes.513Para `skills`, `commands`, `agents`, `outputStyles`, `experimental.themes` e `experimental.monitors`, um caminho personalizado substitui o padrão. Se o manifesto especificar `skills`, o diretório padrão `skills/` não é verificado; se especificar `experimental.monitors`, o padrão `monitors/monitors.json` não é carregado. [Hooks](#hooks), [MCP servers](#mcp-servers) e [LSP servers](#lsp-servers) têm semântica diferente para lidar com múltiplas fontes.

508 514

509* Todos os caminhos devem ser relativos à raiz do plugin e começar com `./`515* Todos os caminhos devem ser relativos à raiz do plugin e começar com `./`

510* Componentes de caminhos personalizados usam as mesmas regras de nomenclatura e namespacing516* Componentes de caminhos personalizados usam as mesmas regras de nomenclatura e namespacing

605 611

606Os plugins são especificados de uma de duas maneiras:612Os plugins são especificados de uma de duas maneiras:

607 613

608* Através de `claude --plugin-dir`, pela duração de uma sessão.614* Através de `claude --plugin-dir` ou `claude --plugin-url`, pela duração de uma sessão.

609* Através de um marketplace, instalado para sessões futuras.615* Através de um marketplace, instalado para sessões futuras.

610 616

611Para fins de segurança e verificação, Claude Code copia plugins do *marketplace* para o **cache de plugin** local do usuário (`~/.claude/plugins/cache`) em vez de usá-los no local. Entender esse comportamento é importante ao desenvolver plugins que referenciam arquivos externos.617Para fins de segurança e verificação, Claude Code copia plugins do *marketplace* para o **cache de plugin** local do usuário (`~/.claude/plugins/cache`) em vez de usá-los no local. Entender esse comportamento é importante ao desenvolver plugins que referenciam arquivos externos.

routines.md +75 −23

Details

14 14

15Cada rotina pode ter um ou mais acionadores anexados a ela:15Cada rotina pode ter um ou mais acionadores anexados a ela:

16 16

~~17* **Agendada**: executada em uma cadência recorrente como horária, noturna ou semanal~~17* **Agendada**: executada em uma cadência recorrente como horária, noturna ou semanal, ou uma vez em um momento futuro específico

18* **API**: acionada sob demanda enviando um POST HTTP para um endpoint por rotina com um token de portador18* **API**: acionada sob demanda enviando um POST HTTP para um endpoint por rotina com um token de portador

19* **GitHub**: executada automaticamente em resposta a eventos de repositório, como pull requests ou lançamentos19* **GitHub**: executada automaticamente em resposta a eventos de repositório, como pull requests ou lançamentos

20 20

44 44

45## Criar uma rotina45## Criar uma rotina

46 46

47Crie uma rotina a partir da web, do aplicativo Desktop ou da CLI. Todas as três superfícies escrevem na mesma conta em nuvem, portanto uma rotina que você cria na CLI aparece em claude.ai/code/routines imediatamente. No aplicativo Desktop, clique em **Nova tarefa** e escolha **Nova tarefa remota**; escolher **Nova tarefa local** em vez disso cria uma [tarefa agendada local do Desktop](/pt/desktop-scheduled-tasks), que é executada em sua máquina e não é uma rotina.47Crie uma rotina a partir da web em [claude.ai/code/routines](https://claude.ai/code/routines), do aplicativo Desktop ou da CLI. Todas as três superfícies escrevem na mesma conta em nuvem, portanto uma rotina que você cria em uma aparece nas outras imediatamente. No aplicativo Desktop, clique em **Routines** na barra lateral, depois em **New routine**, e escolha **Remote**; escolher **Local** em vez disso cria uma [tarefa agendada do Desktop](/pt/desktop-scheduled-tasks), que é executada em sua máquina em vez de na nuvem.

48 48

49O formulário de criação configura o prompt da rotina, repositórios, ambiente, conectores e acionadores.49O formulário de criação configura o prompt da rotina, repositórios, ambiente, conectores e acionadores.

50 50

56 56

57<Steps>57<Steps>

58 <Step title="Abrir o formulário de criação">58 <Step title="Abrir o formulário de criação">

~~59 Visite [claude.ai/code/routines](https://claude.ai/code/routines) e clique em **Nova rotina**.~~59 Visite [claude.ai/code/routines](https://claude.ai/code/routines) e clique em **New routine**.

60 </Step>60 </Step>

61 61

62 <Step title="Nomeie a rotina e escreva o prompt">62 <Step title="Nomeie a rotina e escreva o prompt">

66 </Step>66 </Step>

67 67

68 <Step title="Selecionar repositórios">68 <Step title="Selecionar repositórios">

69 Adicione um ou mais repositórios do GitHub para Claude trabalhar. Cada repositório é clonado no início de uma execução, começando a partir do branch padrão. Claude cria branches com prefixo `claude/` para suas alterações. Para permitir pushes para qualquer branch, ative **Permitir pushes de branch sem restrições** para esse repositório.69 Adicione um ou mais repositórios do GitHub para Claude trabalhar. Cada repositório é clonado no início de uma execução, começando a partir do branch padrão. Claude cria branches com prefixo `claude/` para suas alterações.

70 </Step>70 </Step>

71 71

72 <Step title="Selecionar um ambiente">72 <Step title="Selecionar um ambiente">

76 * **Variáveis de ambiente**: forneça chaves de API, tokens ou outros segredos que Claude pode usar76 * **Variáveis de ambiente**: forneça chaves de API, tokens ou outros segredos que Claude pode usar

77 * **Script de configuração**: instale dependências e ferramentas que a rotina precisa. O resultado é [armazenado em cache](/pt/claude-code-on-the-web#environment-caching), portanto o script não é executado novamente em cada sessão77 * **Script de configuração**: instale dependências e ferramentas que a rotina precisa. O resultado é [armazenado em cache](/pt/claude-code-on-the-web#environment-caching), portanto o script não é executado novamente em cada sessão

78 78

~~79 Um ambiente **Padrão** é fornecido. Para usar um ambiente personalizado, [crie um](/pt/claude-code-on-the-web#the-cloud-environment) antes de criar a rotina.~~79 Um ambiente **Default** é fornecido com acesso à rede **Trusted**, que permite o [conjunto padrão](/pt/claude-code-on-the-web#default-allowed-domains) de registros de pacotes, APIs de provedores de nuvem, registros de contêineres e domínios de desenvolvimento comuns, mas bloqueia tudo o mais. Se sua rotina precisar alcançar seus próprios serviços ou um domínio fora dessa lista, edite o [acesso à rede](/pt/claude-code-on-the-web#network-access) do ambiente antes de executar. Para usar um ambiente separado, [crie um](/pt/claude-code-on-the-web#configure-your-environment) primeiro.

80 </Step>80 </Step>

81 81

82 <Step title="Selecionar um acionador">82 <Step title="Selecionar um acionador">

~~83 Em **Selecionar um acionador**, escolha como a rotina inicia. Você pode escolher um tipo de acionador ou combinar vários.~~83 Em **Select a trigger**, escolha como a rotina inicia. Você pode escolher um tipo de acionador ou combinar vários.

84 84

85 <Tabs>85 <Tabs>

~~86 <Tab title="Cronograma">~~86 <Tab title="Schedule">

87 Escolha uma frequência predefinida: horária, diária, dias da semana ou semanal. Consulte [Adicionar um acionador de cronograma](#add-a-schedule-trigger) para tratamento de fuso horário, escalonamento e intervalos cron personalizados.87 Escolha uma frequência predefinida para uma execução recorrente ou agende uma execução única em um timestamp específico. Consulte [Add a schedule trigger](#add-a-schedule-trigger) para tratamento de fuso horário, escalonamento, intervalos cron personalizados e execuções únicas.

88 </Tab>88 </Tab>

89 89

~~90 <Tab title="Evento do GitHub">~~90 <Tab title="GitHub event">

91 Selecione o repositório, o evento para reagir e filtros opcionais. Consulte [Adicionar um acionador do GitHub](#add-a-github-trigger) para a lista completa de eventos suportados e campos de filtro.91 Selecione o repositório, o evento para reagir e filtros opcionais. Consulte [Add a GitHub trigger](#add-a-github-trigger) para a lista completa de eventos suportados e campos de filtro.

92 </Tab>92 </Tab>

93 93

94 <Tab title="API">94 <Tab title="API">

95 Selecione **API** aqui e salve a rotina. A URL e o token são gerados após a rotina ser salva, pois dependem do ID da rotina. Consulte [Adicionar um acionador de API](#add-an-api-trigger) para copiar a URL e gerar um token.95 Selecione **API** aqui e salve a rotina. A URL e o token são gerados após a rotina ser salva, pois dependem do ID da rotina. Consulte [Add an API trigger](#add-an-api-trigger) para copiar a URL e gerar um token.

96 </Tab>96 </Tab>

97 </Tabs>97 </Tabs>

98 </Step>98 </Step>

99 99

100 <Step title="Revisar conectores">100 <Step title="Revisar conectores e permissões">

101 Todos os seus [conectores MCP](/pt/mcp) conectados são incluídos por padrão. Remova qualquer um que a rotina não precise. Os conectores dão a Claude acesso a serviços externos como Slack, Linear ou Google Drive durante cada execução.101 As abas **Connectors** e **Permissions** na parte inferior do formulário controlam o que a rotina pode alcançar.

102

103 Em Connectors, todos os seus [conectores MCP](/pt/mcp) conectados são incluídos por padrão. Remova qualquer um que a rotina não precise. Claude pode usar todas as ferramentas de um conector incluído, incluindo escritas, sem pedir permissão durante uma execução.

104

105 Em Permissions, ative **Allow unrestricted branch pushes** para qualquer repositório onde Claude deve ser capaz de fazer push para branches existentes em vez de apenas aqueles com prefixo `claude/`.

102 </Step>106 </Step>

103 107

104 <Step title="Criar a rotina">108 <Step title="Criar a rotina">

105 Clique em **Criar**. A rotina aparece na lista e é executada na próxima vez que um de seus acionadores corresponder. Para iniciar uma execução imediatamente, clique em **Executar agora** na página de detalhes da rotina.109 Clique em **Create**. A rotina aparece na lista e é executada na próxima vez que um de seus acionadores corresponder. Para iniciar uma execução imediatamente, clique em **Run now** na página de detalhes da rotina.

106 110

107 Cada execução cria uma nova sessão ao lado de suas outras sessões, onde você pode ver o que Claude fez, revisar alterações e criar um pull request.111 Cada execução cria uma nova sessão ao lado de suas outras sessões, onde você pode ver o que Claude fez, revisar alterações e criar um pull request.

108 </Step>112 </Step>

110 114

111### Criar a partir da CLI115### Criar a partir da CLI

112 116

113Execute `/schedule` em qualquer sessão para criar uma rotina agendada conversacionalmente. Você também pode passar uma descrição diretamente, como em `/schedule daily PR review at 9am`. Claude percorre as mesmas informações que o formulário web coleta e salva a rotina em sua conta.117Execute `/schedule` em qualquer sessão para criar uma rotina agendada conversacionalmente. Você também pode passar uma descrição diretamente, para uma rotina recorrente como `/schedule daily PR review at 9am` ou uma única como `/schedule clean up feature flag in one week`. Claude percorre as mesmas informações que o formulário web coleta e salva a rotina em sua conta.

114 118

115`/schedule` na CLI cria apenas rotinas agendadas. Para adicionar um acionador de API ou GitHub, edite a rotina na web em [claude.ai/code/routines](https://claude.ai/code/routines).119`/schedule` na CLI cria apenas rotinas agendadas. Para adicionar um acionador de API ou GitHub, edite a rotina na web em [claude.ai/code/routines](https://claude.ai/code/routines).

116 120

117A CLI também suporta o gerenciamento de rotinas existentes. Execute `/schedule list` para ver todas as rotinas, `/schedule update` para alterar uma ou `/schedule run` para acioná-la imediatamente.121A CLI também suporta o gerenciamento de rotinas existentes. Execute `/schedule list` para ver todas as rotinas, `/schedule update` para alterar uma ou `/schedule run` para acioná-la imediatamente.

118 122

119### Criar a partir do aplicativo Desktop

~~120~~

121Abra a página **Cronograma** no aplicativo Desktop, clique em **Nova tarefa** e escolha **Nova tarefa remota**. O aplicativo Desktop mostra tarefas agendadas locais e rotinas na mesma grade. Consulte [Tarefas agendadas do Desktop](/pt/desktop-scheduled-tasks) para detalhes sobre a opção local.

~~122~~

123## Configurar acionadores123## Configurar acionadores

124 124

125Uma rotina inicia quando um de seus acionadores corresponde. Você pode anexar qualquer combinação de cronograma, API e acionadores do GitHub à mesma rotina e adicioná-los ou removê-los a qualquer momento na seção **Selecionar um acionador** do formulário de edição da rotina.125Uma rotina inicia quando um de seus acionadores corresponde. Você pode anexar qualquer combinação de cronograma, API e acionadores do GitHub à mesma rotina e adicioná-los ou removê-los a qualquer momento na seção **Selecionar um acionador** do formulário de edição da rotina.

126 126

127### Adicionar um acionador de cronograma127### Adicionar um acionador de cronograma

128 128

129Um acionador de cronograma executa a rotina em uma cadência recorrente. Escolha uma frequência predefinida na seção **Selecionar um acionador**: horária, diária, dias da semana ou semanal. Os horários são inseridos em seu fuso horário local e convertidos automaticamente, portanto a rotina é executada naquele horário de parede independentemente de onde a infraestrutura em nuvem está localizada.129Um acionador de cronograma executa a rotina em uma cadência recorrente ou uma única vez em um momento futuro específico. Escolha uma frequência predefinida na seção **Selecionar um acionador**: horária, diária, dias da semana ou semanal. Os horários são inseridos em seu fuso horário local e convertidos automaticamente, portanto a rotina é executada naquele horário de parede independentemente de onde a infraestrutura em nuvem está localizada.

130 130

131As execuções podem começar alguns minutos após o horário agendado devido ao escalonamento. O deslocamento é consistente para cada rotina.131As execuções podem começar alguns minutos após o horário agendado devido ao escalonamento. O deslocamento é consistente para cada rotina.

132 132

133Para um intervalo personalizado, como a cada duas horas ou no primeiro de cada mês, escolha a predefinição mais próxima no formulário e execute `/schedule update` na CLI para definir uma expressão cron específica. O intervalo mínimo é uma hora; expressões que são executadas com mais frequência são rejeitadas.133Para um intervalo personalizado, como a cada duas horas ou no primeiro de cada mês, escolha a predefinição mais próxima no formulário e execute `/schedule update` na CLI para definir uma expressão cron específica. O intervalo mínimo é uma hora; expressões que são executadas com mais frequência são rejeitadas.

134 134

135#### Agendar uma execução única

136

137Um cronograma único dispara a rotina uma única vez em um timestamp específico. Use-o para lembrá-lo mais tarde na semana, para abrir um PR de limpeza após um rollout terminar ou para iniciar uma tarefa de acompanhamento quando uma mudança upstream chegar. Após a rotina disparar, ela se desativa automaticamente e a interface web a marca como **Executada**. Para executá-la novamente, edite a rotina e defina um novo horário único.

138

139Crie uma execução única a partir da CLI descrevendo o horário em linguagem natural. Claude resolve a frase em relação ao horário atual e confirma o timestamp absoluto antes de salvar.

140

141```text theme={null}

142/schedule tomorrow at 9am, summarize yesterday's merged PRs

143```

144

145```text theme={null}

146/schedule in 2 weeks, open a cleanup PR that removes the feature flag

147```

148

149A mesma conversão local-para-UTC que os cronogramas recorrentes se aplica aos timestamps únicos.

150

151As execuções únicas não contam contra o limite diário de execução de rotina. Elas consomem o uso de assinatura regular do seu plano como qualquer outra sessão. Consulte [Uso e limites](#usage-and-limits) para obter detalhes.

152

135### Adicionar um acionador de API153### Adicionar um acionador de API

136 154

137Um acionador de API fornece a uma rotina um endpoint HTTP dedicado. POSTando para o endpoint com o token de portador da rotina inicia uma nova sessão e retorna uma URL de sessão. Use isso para conectar Claude Code em sistemas de alerta, pipelines de implantação, ferramentas internas ou em qualquer lugar onde você possa fazer uma solicitação HTTP autenticada.155Um acionador de API fornece a uma rotina um endpoint HTTP dedicado. POSTando para o endpoint com o token de portador da rotina inicia uma nova sessão e retorna uma URL de sessão. Use isso para conectar Claude Code em sistemas de alerta, pipelines de implantação, ferramentas internas ou em qualquer lugar onde você possa fazer uma solicitação HTTP autenticada.

144 </Step>162 </Step>

145 163

146 <Step title="Adicionar um acionador de API">164 <Step title="Adicionar um acionador de API">

147 Role até a seção **Selecionar um acionador** abaixo do prompt, clique em **Adicionar outro acionador** e escolha **API**.165 Role até a seção **Selecionar um acionador** abaixo da caixa **Instruções**, clique em **Adicionar outro acionador** e escolha **API**.

148 </Step>166 </Step>

149 167

150 <Step title="Copiar a URL e gerar um token">168 <Step title="Copiar a URL e gerar um token">

273 291

274Clique em qualquer execução para abri-la como uma sessão completa. De lá você pode ver o que Claude fez, revisar alterações, criar um pull request ou continuar a conversa. Cada sessão de execução funciona como qualquer outra sessão: use o menu suspenso ao lado do título da sessão para renomear, arquivar ou excluir.292Clique em qualquer execução para abri-la como uma sessão completa. De lá você pode ver o que Claude fez, revisar alterações, criar um pull request ou continuar a conversa. Cada sessão de execução funciona como qualquer outra sessão: use o menu suspenso ao lado do título da sessão para renomear, arquivar ou excluir.

275 293

294<Note>

295 Um status verde na lista de execuções significa que a sessão iniciou e saiu sem um erro de infraestrutura. Isso não significa que a tarefa em seu prompt foi bem-sucedida. Abra a execução para ler a transcrição e confirmar o que Claude realmente fez. Solicitações de rede bloqueadas, ferramentas de conectores ausentes e falhas no nível da tarefa aparecem lá em vez de no indicador de status.

296</Note>

297

276### Editar e controlar rotinas298### Editar e controlar rotinas

277 299

278Na página de detalhes da rotina você pode:300Na página de detalhes da rotina você pode:

298 320

299Para gerenciar ou adicionar conectores fora do formulário de rotina, visite **Configurações > Conectores** em claude.ai ou use `/schedule update` na CLI.321Para gerenciar ou adicionar conectores fora do formulário de rotina, visite **Configurações > Conectores** em claude.ai ou use `/schedule update` na CLI.

300 322

301### Ambientes323### Ambientes e acesso à rede

302 324

303Cada rotina é executada em um [ambiente em nuvem](/pt/claude-code-on-the-web#the-cloud-environment) que controla acesso à rede, variáveis de ambiente e scripts de configuração. Configure ambientes antes de criar uma rotina para dar a Claude acesso a APIs, instalar dependências ou restringir o escopo da rede. Consulte [ambiente em nuvem](/pt/claude-code-on-the-web#the-cloud-environment) para o guia de configuração completo.325Cada rotina é executada em um [ambiente em nuvem](/pt/claude-code-on-the-web#the-cloud-environment) que controla acesso à rede, variáveis de ambiente e scripts de configuração. A rotina herda a política de rede do ambiente em cada execução.

326

327O ambiente **Padrão** usa acesso à rede **Confiável**: a [lista de permissões padrão](/pt/claude-code-on-the-web#default-allowed-domains) de registros de pacotes, APIs de provedores de nuvem, registros de contêineres e domínios de desenvolvimento comuns é acessível, mas domínios arbitrários não são. Solicitações de saída para outros hosts falham com `403` e `x-deny-reason: host_not_allowed`. O tráfego do conector MCP é roteado através dos servidores da Anthropic, portanto os conectores que você adiciona à rotina funcionam sem adicionar seus hosts aos **Domínios permitidos**. Remova qualquer conectores que você não precise em [Conectores](#conectores).

328

329Para permitir domínios adicionais:

330

331<Steps>

332 <Step title="Abra a rotina para edição">

333 Na página de detalhes da rotina, clique no ícone de lápis para abrir **Editar rotina**.

334 </Step>

335

336 <Step title="Abra o seletor de ambiente">

337 Abaixo da caixa **Instruções**, selecione o ícone de nuvem mostrando o nome do seu ambiente, como **Padrão**.

338 </Step>

339

340 <Step title="Abra as configurações de ambiente">

341 Passe o mouse sobre o ambiente na lista e clique no ícone de configurações que aparece à direita.

342 </Step>

343

344 <Step title="Altere o nível de acesso à rede">

345 Na caixa de diálogo **Atualizar ambiente em nuvem**, altere **Acesso à rede** para **Personalizado** e insira seus domínios em **Domínios permitidos**. Marque **Também incluir lista padrão de gerenciadores de pacotes comuns** para manter a [lista de permissões padrão](/pt/claude-code-on-the-web#default-allowed-domains) junto com seus domínios personalizados. Selecione **Completo** em vez disso para acesso irrestrito.

346 </Step>

347

348 <Step title="Salvar">

349 Clique em **Salvar alterações**. A nova política se aplica a partir da próxima execução.

350 </Step>

351</Steps>

352

353Consulte [Acesso à rede](/pt/claude-code-on-the-web#network-access) para detalhes sobre níveis de acesso e a lista de permissões padrão.

304 354

305## Uso e limites355## Uso e limites

306 356

308 358

309Quando uma rotina atinge o limite diário ou seu limite de uso de assinatura, organizações com uso extra ativado podem continuar executando rotinas em excesso medido. Sem uso extra, execuções adicionais são rejeitadas até que a janela seja redefinida. Ative o uso extra em **Configurações > Faturamento** em claude.ai.359Quando uma rotina atinge o limite diário ou seu limite de uso de assinatura, organizações com uso extra ativado podem continuar executando rotinas em excesso medido. Sem uso extra, execuções adicionais são rejeitadas até que a janela seja redefinida. Ative o uso extra em **Configurações > Faturamento** em claude.ai.

310 360

361As execuções únicas não contam contra o limite diário de execução de rotina. Elas reduzem seu uso de assinatura regular como qualquer outra sessão, mas estão isentas da permissão de execução de rotina diária por conta.

362

311## Recursos relacionados363## Recursos relacionados

312 364

313* [`/loop` e agendamento em sessão](/pt/scheduled-tasks): agende tarefas locais dentro de uma sessão CLI aberta365* [`/loop` e agendamento em sessão](/pt/scheduled-tasks): agende tarefas locais dentro de uma sessão CLI aberta

settings.md +19 −15

Details

164| `allowManagedHooksOnly` | (Apenas configurações gerenciadas) Apenas hooks gerenciados, hooks SDK, e hooks de plugins força-habilitados em configurações gerenciadas `enabledPlugins` são carregados. Hooks de usuário, projeto e todos os outros plugins são bloqueados. Veja [Configuração de hooks](#hook-configuration) | `true` |164| `allowManagedHooksOnly` | (Apenas configurações gerenciadas) Apenas hooks gerenciados, hooks SDK, e hooks de plugins força-habilitados em configurações gerenciadas `enabledPlugins` são carregados. Hooks de usuário, projeto e todos os outros plugins são bloqueados. Veja [Configuração de hooks](#hook-configuration) | `true` |

165| `allowManagedMcpServersOnly` | (Apenas configurações gerenciadas) Apenas `allowedMcpServers` de configurações gerenciadas são respeitados. `deniedMcpServers` ainda se mescla de todas as fontes. Usuários ainda podem adicionar MCP servers, mas apenas a lista de permissões definida pelo administrador se aplica. Veja [Configuração MCP gerenciada](/pt/mcp#managed-mcp-configuration) | `true` |165| `allowManagedMcpServersOnly` | (Apenas configurações gerenciadas) Apenas `allowedMcpServers` de configurações gerenciadas são respeitados. `deniedMcpServers` ainda se mescla de todas as fontes. Usuários ainda podem adicionar MCP servers, mas apenas a lista de permissões definida pelo administrador se aplica. Veja [Configuração MCP gerenciada](/pt/mcp#managed-mcp-configuration) | `true` |

166| `allowManagedPermissionRulesOnly` | (Apenas configurações gerenciadas) Impedir que configurações de usuário e projeto definam regras de permissão `allow`, `ask` ou `deny`. Apenas regras em configurações gerenciadas se aplicam. Veja [Configurações apenas gerenciadas](/pt/permissions#managed-only-settings) | `true` |166| `allowManagedPermissionRulesOnly` | (Apenas configurações gerenciadas) Impedir que configurações de usuário e projeto definam regras de permissão `allow`, `ask` ou `deny`. Apenas regras em configurações gerenciadas se aplicam. Veja [Configurações apenas gerenciadas](/pt/permissions#managed-only-settings) | `true` |

167| `alwaysThinkingEnabled` | Ativar [pensamento estendido](/pt/model-config#extended-thinking) por padrão para todas as sessões. Tipicamente configurado via comando `/config` em vez de editar diretamente | `true` |167| `alwaysThinkingEnabled` | Ativar [pensamento estendido](/pt/model-config#extended-thinking) por padrão para todas as sessões. Tipicamente configurado via comando `/config` em vez de editar diretamente. Para forçar o pensamento desligado independentemente desta configuração, defina [`CLAUDE_CODE_DISABLE_THINKING`](/pt/env-vars) em `env` | `true` |

168| `apiKeyHelper` | Script personalizado, a ser executado em `/bin/sh`, para gerar um valor de autenticação. Este valor será enviado como cabeçalhos `X-Api-Key` e `Authorization: Bearer` para solicitações de modelo | `/bin/generate_temp_api_key.sh` |168| `apiKeyHelper` | Script personalizado, a ser executado em `/bin/sh`, para gerar um valor de autenticação. Este valor será enviado como cabeçalhos `X-Api-Key` e `Authorization: Bearer` para solicitações de modelo. Defina o intervalo de atualização com [`CLAUDE_CODE_API_KEY_HELPER_TTL_MS`](/pt/env-vars) | `/bin/generate_temp_api_key.sh` |

169| `attribution` | Personalizar atribuição para commits git e pull requests. Veja [Configurações de atribuição](#attribution-settings) | `{"commit": "🤖 Generated with Claude Code", "pr": ""}` |169| `attribution` | Personalizar atribuição para commits git e pull requests. Veja [Configurações de atribuição](#attribution-settings) | `{"commit": "🤖 Generated with Claude Code", "pr": ""}` |

170| `autoMemoryDirectory` | Diretório personalizado para armazenamento de [memória automática](/pt/memory#storage-location). Aceita um caminho absoluto ou um caminho com prefixo `~/`. Aceito de configurações de política e usuário, e da flag `--settings`. Não aceito de configurações de projeto ou local, já que um repositório clonado poderia fornecer qualquer arquivo para redirecionar escritas de memória para locais sensíveis | `"~/my-memory-dir"` |170| `autoMemoryDirectory` | Diretório personalizado para armazenamento de [memória automática](/pt/memory#storage-location). Aceita um caminho absoluto ou um caminho com prefixo `~/`. Aceito de configurações de política e usuário, e da flag `--settings`. Não aceito de configurações de projeto ou local, já que um repositório clonado poderia fornecer qualquer arquivo para redirecionar escritas de memória para locais sensíveis | `"~/my-memory-dir"` |

171| `autoMemoryEnabled` | Ativar [memória automática](/pt/memory#enable-or-disable-auto-memory). Quando `false`, Claude não lê ou escreve no diretório de memória automática. Padrão: `true`. Você também pode alternar isto com `/memory` durante uma sessão | `false` |171| `autoMemoryEnabled` | Ativar [memória automática](/pt/memory#enable-or-disable-auto-memory). Quando `false`, Claude não lê ou escreve no diretório de memória automática. Padrão: `true`. Você também pode alternar isto com `/memory` durante uma sessão. Para desabilitar via variável de ambiente, defina [`CLAUDE_CODE_DISABLE_AUTO_MEMORY`](/pt/env-vars) em `env` | `false` |

172| `autoMode` | Personalizar o que o classificador de [modo automático](/pt/permission-modes#eliminate-prompts-with-auto-mode) bloqueia e permite. Contém arrays `environment`, `allow`, e `soft_deny` de regras em prosa. Inclua a string literal `"$defaults"` em um array para herdar as regras integradas nessa posição. Veja [Configurar modo automático](/pt/auto-mode-config). Não lido de configurações de projeto compartilhadas | `{"soft_deny": ["$defaults", "Never run terraform apply"]}` |172| `autoMode` | Personalizar o que o classificador de [modo automático](/pt/permission-modes#eliminate-prompts-with-auto-mode) bloqueia e permite. Contém arrays `environment`, `allow`, e `soft_deny` de regras em prosa. Inclua a string literal `"$defaults"` em um array para herdar as regras integradas nessa posição. Veja [Configurar modo automático](/pt/auto-mode-config). Não lido de configurações de projeto compartilhadas | `{"soft_deny": ["$defaults", "Never run terraform apply"]}` |

173| `autoScrollEnabled` | Em [renderização fullscreen](/pt/fullscreen), seguir nova saída até o fundo da conversa. Padrão: `true`. Aparece em `/config` como **Auto-scroll**. Prompts de permissão ainda rolam para a vista quando isto está desligado | `false` |173| `autoScrollEnabled` | Em [renderização fullscreen](/pt/fullscreen), seguir nova saída até o fundo da conversa. Padrão: `true`. Aparece em `/config` como **Auto-scroll**. Prompts de permissão ainda rolam para a vista quando isto está desligado | `false` |

174| `autoUpdatesChannel` | Canal de lançamento a seguir para atualizações. Use `"stable"` para uma versão que é tipicamente cerca de uma semana antiga e pula versões com regressões maiores, ou `"latest"` (padrão) para o lançamento mais recente | `"stable"` |174| `autoUpdatesChannel` | Canal de lançamento a seguir para atualizações. Use `"stable"` para uma versão que é tipicamente cerca de uma semana antiga e pula versões com regressões maiores, ou `"latest"` (padrão) para o lançamento mais recente. Para desabilitar auto-atualizações completamente, defina [`DISABLE_AUTOUPDATER`](/pt/setup#disable-auto-updates) em `env` | `"stable"` |

175| `availableModels` | Restringir quais modelos os usuários podem selecionar via `/model`, `--model`, ou `ANTHROPIC_MODEL`. Não afeta a opção Padrão. Veja [Restringir seleção de modelo](/pt/model-config#restrict-model-selection) | `["sonnet", "haiku"]` |175| `availableModels` | Restringir quais modelos os usuários podem selecionar via `/model`, `--model`, ou `ANTHROPIC_MODEL`. Não afeta a opção Padrão. Veja [Restringir seleção de modelo](/pt/model-config#restrict-model-selection) | `["sonnet", "haiku"]` |

176| `awaySummaryEnabled` | Mostrar um resumo de sessão de uma linha quando você retorna ao terminal após alguns minutos ausente. Defina como `false` ou desative Resumo de sessão em `/config` para desabilitar. Mesmo que [`CLAUDE_CODE_ENABLE_AWAY_SUMMARY`](/pt/env-vars) | `true` |176| `awaySummaryEnabled` | Mostrar um resumo de sessão de uma linha quando você retorna ao terminal após alguns minutos ausente. Defina como `false` ou desative Resumo de sessão em `/config` para desabilitar. Mesmo que [`CLAUDE_CODE_ENABLE_AWAY_SUMMARY`](/pt/env-vars) | `true` |

177| `awsAuthRefresh` | Script personalizado que modifica o diretório `.aws` (veja [configuração avançada de credenciais](/pt/amazon-bedrock#advanced-credential-configuration)) | `aws sso login --profile myprofile` |177| `awsAuthRefresh` | Script personalizado que modifica o diretório `.aws` (veja [configuração avançada de credenciais](/pt/amazon-bedrock#advanced-credential-configuration)) | `aws sso login --profile myprofile` |

178| `awsCredentialExport` | Script personalizado que produz JSON com credenciais AWS (veja [configuração avançada de credenciais](/pt/amazon-bedrock#advanced-credential-configuration)) | `/bin/generate_aws_grant.sh` |178| `awsCredentialExport` | Script personalizado que produz JSON com credenciais AWS (veja [configuração avançada de credenciais](/pt/amazon-bedrock#advanced-credential-configuration)) | `/bin/generate_aws_grant.sh` |

179| `blockedMarketplaces` | (Apenas configurações gerenciadas) Lista de negação de fontes de marketplace. Aplicado em adição de marketplace e em instalação, atualização, atualização e auto-atualização de plugin, então um marketplace adicionado antes da política ser definida não pode ser usado para buscar plugins. Fontes bloqueadas são verificadas antes do download, então nunca tocam o sistema de arquivos. Veja [Restrições de marketplace gerenciado](/pt/plugin-marketplaces#managed-marketplace-restrictions) | `[{ "source": "github", "repo": "untrusted/plugins" }]` |179| `blockedMarketplaces` | (Apenas configurações gerenciadas) Lista de negação de fontes de marketplace. Aplicado em adição de marketplace e em instalação, atualização, atualização e auto-atualização de plugin, então um marketplace adicionado antes da política ser definida não pode ser usado para buscar plugins. Fontes bloqueadas são verificadas antes do download, então nunca tocam o sistema de arquivos. Veja [Restrições de marketplace gerenciado](/pt/plugin-marketplaces#managed-marketplace-restrictions) | `[{ "source": "github", "repo": "untrusted/plugins" }]` |

180| `channelsEnabled` | (Apenas configurações gerenciadas) Permitir [channels](/pt/channels) para a organização. Em planos Claude.ai Team e Enterprise, channels são bloqueados quando isto está indefinido ou `false`. Para contas [Anthropic Console](/pt/authentication#claude-console-authentication) usando autenticação de chave de API, channels são permitidos por padrão a menos que sua organização implante configurações gerenciadas, nesse caso esta chave deve ser definida como `true` | `true` |180| `channelsEnabled` | (Apenas configurações gerenciadas) Permitir [channels](/pt/channels) para a organização. Em planos Claude.ai Team e Enterprise, channels são bloqueados quando isto está indefinido ou `false`. Para contas [Anthropic Console](/pt/authentication#claude-console-authentication) usando autenticação de chave de API, channels são permitidos por padrão a menos que sua organização implante configurações gerenciadas, nesse caso esta chave deve ser definida como `true` | `true` |

181| `claudeMdExcludes` | Padrões Glob ou caminhos absolutos de arquivos `CLAUDE.md` para pular ao carregar [memória](/pt/memory). Padrões correspondem contra caminhos de arquivo absolutos. Aplica-se apenas a memória de usuário, projeto e local; arquivos de política gerenciada não podem ser excluídos | `["**/vendor/**/CLAUDE.md"]` |

181| `cleanupPeriodDays` | Arquivos de sessão mais antigos que este período são deletados na inicialização (padrão: 30 dias, mínimo 1). Definir como `0` é rejeitado com um erro de validação. Também controla o corte de idade para remoção automática de [worktrees de subagent órfãos](/pt/worktrees#clean-up-worktrees) na inicialização. Para desabilitar escritas de transcrição completamente, defina a variável de ambiente [`CLAUDE_CODE_SKIP_PROMPT_HISTORY`](/pt/env-vars), ou em modo não interativo (`-p`) use a flag `--no-session-persistence` ou a opção SDK `persistSession: false`. | `20` |182| `cleanupPeriodDays` | Arquivos de sessão mais antigos que este período são deletados na inicialização (padrão: 30 dias, mínimo 1). Definir como `0` é rejeitado com um erro de validação. Também controla o corte de idade para remoção automática de [worktrees de subagent órfãos](/pt/worktrees#clean-up-worktrees) na inicialização. Para desabilitar escritas de transcrição completamente, defina a variável de ambiente [`CLAUDE_CODE_SKIP_PROMPT_HISTORY`](/pt/env-vars), ou em modo não interativo (`-p`) use a flag `--no-session-persistence` ou a opção SDK `persistSession: false`. | `20` |

182| `companyAnnouncements` | Anúncio a ser exibido aos usuários na inicialização. Se múltiplos anúncios forem fornecidos, eles serão alternados aleatoriamente. | `["Welcome to Acme Corp! Review our code guidelines at docs.acme.com"]` |183| `companyAnnouncements` | Anúncio a ser exibido aos usuários na inicialização. Se múltiplos anúncios forem fornecidos, eles serão alternados aleatoriamente. | `["Welcome to Acme Corp! Review our code guidelines at docs.acme.com"]` |

183| `defaultShell` | Shell padrão para comandos `!` da caixa de entrada. Aceita `"bash"` (padrão) ou `"powershell"`. Definir `"powershell"` roteia comandos `!` interativos através do PowerShell no Windows. Requer `CLAUDE_CODE_USE_POWERSHELL_TOOL=1`. Veja [Ferramenta PowerShell](/pt/tools-reference#powershell-tool) | `"powershell"` |184| `defaultShell` | Shell padrão para comandos `!` da caixa de entrada. Aceita `"bash"` (padrão) ou `"powershell"`. Definir `"powershell"` roteia comandos `!` interativos através do PowerShell no Windows. Requer `CLAUDE_CODE_USE_POWERSHELL_TOOL=1`. Veja [Ferramenta PowerShell](/pt/tools-reference#powershell-tool) | `"powershell"` |

189| `disableRemoteControl` | {/* min-version: 2.1.128 */}Desabilitar [Controle Remoto](/pt/remote-control): bloqueia `claude remote-control`, a flag `--remote-control`, auto-start, e o toggle em sessão. Tipicamente colocado em [configurações gerenciadas](/pt/permissions#managed-settings) para aplicação de MDM por dispositivo, mas funciona de qualquer escopo. Requer Claude Code v2.1.128 ou posterior | `true` |190| `disableRemoteControl` | {/* min-version: 2.1.128 */}Desabilitar [Controle Remoto](/pt/remote-control): bloqueia `claude remote-control`, a flag `--remote-control`, auto-start, e o toggle em sessão. Tipicamente colocado em [configurações gerenciadas](/pt/permissions#managed-settings) para aplicação de MDM por dispositivo, mas funciona de qualquer escopo. Requer Claude Code v2.1.128 ou posterior | `true` |

190| `disableSkillShellExecution` | Desabilitar execução de shell inline para blocos `` !`...` `` e ` ```! ` em [skills](/pt/skills) e comandos personalizados de fontes de usuário, projeto, plugin ou diretório adicional. Comandos são substituídos por `[shell command execution disabled by policy]` em vez de serem executados. Skills agrupadas e gerenciadas não são afetadas. Mais útil em [configurações gerenciadas](/pt/permissions#managed-settings) onde os usuários não podem substituir | `true` |191| `disableSkillShellExecution` | Desabilitar execução de shell inline para blocos `` !`...` `` e ` ```! ` em [skills](/pt/skills) e comandos personalizados de fontes de usuário, projeto, plugin ou diretório adicional. Comandos são substituídos por `[shell command execution disabled by policy]` em vez de serem executados. Skills agrupadas e gerenciadas não são afetadas. Mais útil em [configurações gerenciadas](/pt/permissions#managed-settings) onde os usuários não podem substituir | `true` |

191| `editorMode` | Modo de atalho de teclado para o prompt de entrada: `"normal"` ou `"vim"`. Padrão: `"normal"`. Aparece em `/config` como **Editor mode** | `"vim"` |192| `editorMode` | Modo de atalho de teclado para o prompt de entrada: `"normal"` ou `"vim"`. Padrão: `"normal"`. Aparece em `/config` como **Editor mode** | `"vim"` |

192| `effortLevel` | Persistir o [nível de esforço](/pt/model-config#adjust-effort-level) entre sessões. Aceita `"low"`, `"medium"`, `"high"`, ou `"xhigh"`. Escrito automaticamente quando você executa `/effort` com um desses valores. Veja [Ajustar nível de esforço](/pt/model-config#adjust-effort-level) para modelos suportados | `"xhigh"` |193| `effortLevel` | Persistir o [nível de esforço](/pt/model-config#adjust-effort-level) entre sessões. Aceita `"low"`, `"medium"`, `"high"`, ou `"xhigh"`. Escrito automaticamente quando você executa `/effort` com um desses valores. `--effort` e [`CLAUDE_CODE_EFFORT_LEVEL`](/pt/env-vars) substituem isto para uma sessão. Veja [Ajustar nível de esforço](/pt/model-config#adjust-effort-level) para modelos suportados | `"xhigh"` |

195| `env` | Variáveis de ambiente que serão aplicadas a cada sessão | `{"FOO": "bar"}` |196| `env` | Variáveis de ambiente que serão aplicadas a cada sessão | `{"FOO": "bar"}` |

196| `fastModePerSessionOptIn` | Quando `true`, o modo rápido não persiste entre sessões. Cada sessão começa com modo rápido desligado, exigindo que os usuários o habilitem com `/fast`. A preferência de modo rápido do usuário ainda é salva. Veja [Exigir opt-in por sessão](/pt/fast-mode#require-per-session-opt-in) | `true` |197| `fastModePerSessionOptIn` | Quando `true`, o modo rápido não persiste entre sessões. Cada sessão começa com modo rápido desligado, exigindo que os usuários o habilitem com `/fast`. A preferência de modo rápido do usuário ainda é salva. Veja [Exigir opt-in por sessão](/pt/fast-mode#require-per-session-opt-in) | `true` |

197| `feedbackSurveyRate` | Probabilidade (0–1) que a [pesquisa de qualidade de sessão](/pt/data-usage#session-quality-surveys) aparece quando elegível. Defina como `0` para suprimir completamente. Útil ao usar Bedrock, Vertex, ou Foundry onde a taxa de amostra padrão não se aplica | `0.05` |198| `feedbackSurveyRate` | Probabilidade (0–1) que a [pesquisa de qualidade de sessão](/pt/data-usage#session-quality-surveys) aparece quando elegível. Defina como `0` para suprimir completamente, ou defina [`CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY`](/pt/env-vars) em `env`. Útil ao usar Bedrock, Vertex, ou Foundry onde a taxa de amostra padrão não se aplica | `0.05` |

198| `fileSuggestion` | Configure um script personalizado para preenchimento automático de arquivo `@`. Veja [Configurações de sugestão de arquivo](#file-suggestion-settings) | `{"type": "command", "command": "~/.claude/file-suggestion.sh"}` |199| `fileSuggestion` | Configure um script personalizado para preenchimento automático de arquivo `@`. Veja [Configurações de sugestão de arquivo](#file-suggestion-settings) | `{"type": "command", "command": "~/.claude/file-suggestion.sh"}` |

199| `forceLoginMethod` | Use `claudeai` para restringir login a contas Claude.ai, `console` para restringir login a contas Claude Console (faturamento de uso de API) | `claudeai` |200| `forceLoginMethod` | Use `claudeai` para restringir login a contas Claude.ai, `console` para restringir login a contas Claude Console (faturamento de uso de API) | `claudeai` |

200| `forceLoginOrgUUID` | Exigir que o login pertença a uma organização específica. Aceita uma string UUID única, que também pré-seleciona essa organização durante o login, ou um array de UUIDs onde qualquer organização listada é aceita sem pré-seleção. Quando definido em configurações gerenciadas, o login falha se a conta autenticada não pertencer a uma organização listada; um array vazio falha fechado e bloqueia o login com uma mensagem de configuração incorreta | `"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"` ou `["xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy"]` |201| `forceLoginOrgUUID` | Exigir que o login pertença a uma organização específica. Aceita uma string UUID única, que também pré-seleciona essa organização durante o login, ou um array de UUIDs onde qualquer organização listada é aceita sem pré-seleção. Quando definido em configurações gerenciadas, o login falha se a conta autenticada não pertencer a uma organização listada; um array vazio falha fechado e bloqueia o login com uma mensagem de configuração incorreta | `"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"` ou `["xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy"]` |

201| `forceRemoteSettingsRefresh` | (Apenas configurações gerenciadas) Bloquear inicialização da CLI até que configurações gerenciadas remotas sejam buscadas recentemente do servidor. Se a busca falhar, a CLI sai em vez de continuar com configurações em cache ou sem configurações. Quando não definido, a inicialização continua sem esperar por configurações remotas. Veja [aplicação fail-closed](/pt/server-managed-settings#enforce-fail-closed-startup) | `true` |202| `forceRemoteSettingsRefresh` | (Apenas configurações gerenciadas) Bloquear inicialização da CLI até que configurações gerenciadas remotas sejam buscadas recentemente do servidor. Se a busca falhar, a CLI sai em vez de continuar com configurações em cache ou sem configurações. Quando não definido, a inicialização continua sem esperar por configurações remotas. Veja [aplicação fail-closed](/pt/server-managed-settings#enforce-fail-closed-startup) | `true` |

203| `gcpAuthRefresh` | Script personalizado que atualiza as Credenciais Padrão de Aplicação GCP quando expiram ou não podem ser carregadas. Veja [configuração avançada de credenciais](/pt/google-vertex-ai#advanced-credential-configuration) | `gcloud auth application-default login` |

202| `hooks` | Configure comandos personalizados para executar em eventos do ciclo de vida. Veja [documentação de hooks](/pt/hooks) para formato | Veja [hooks](/pt/hooks) |204| `hooks` | Configure comandos personalizados para executar em eventos do ciclo de vida. Veja [documentação de hooks](/pt/hooks) para formato | Veja [hooks](/pt/hooks) |

203| `httpHookAllowedEnvVars` | Lista de permissões de nomes de variáveis de ambiente que hooks HTTP podem interpolar em cabeçalhos. Quando definido, o `allowedEnvVars` efetivo de cada hook é a interseção com esta lista. Indefinido = sem restrição. Arrays se mesclam entre fontes de configuração. Veja [Configuração de hooks](#hook-configuration) | `["MY_TOKEN", "HOOK_SECRET"]` |205| `httpHookAllowedEnvVars` | Lista de permissões de nomes de variáveis de ambiente que hooks HTTP podem interpolar em cabeçalhos. Quando definido, o `allowedEnvVars` efetivo de cada hook é a interseção com esta lista. Indefinido = sem restrição. Arrays se mesclam entre fontes de configuração. Veja [Configuração de hooks](#hook-configuration) | `["MY_TOKEN", "HOOK_SECRET"]` |

204| `includeCoAuthoredBy` | **Descontinuado**: Use `attribution` em vez disso. Se deve incluir a linha `co-authored-by Claude` em commits git e pull requests (padrão: `true`) | `false` |206| `includeCoAuthoredBy` | **Descontinuado**: Use `attribution` em vez disso. Se deve incluir a linha `co-authored-by Claude` em commits git e pull requests (padrão: `true`) | `false` |

205| `includeGitInstructions` | Incluir instruções de workflow de commit e PR integradas e o snapshot de status git no prompt do sistema do Claude (padrão: `true`). Defina como `false` para remover ambos, por exemplo ao usar suas próprias skills de workflow git. A variável de ambiente `CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS` tem precedência sobre esta configuração quando definida | `false` |207| `includeGitInstructions` | Incluir instruções de workflow de commit e PR integradas e o snapshot de status git no prompt do sistema do Claude (padrão: `true`). Defina como `false` para remover ambos, por exemplo ao usar suas próprias skills de workflow git. A variável de ambiente `CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS` tem precedência sobre esta configuração quando definida | `false` |

206| `language` | Configure o idioma de resposta preferido do Claude (por exemplo, `"japanese"`, `"spanish"`, `"french"`). Claude responderá neste idioma por padrão. Também define o idioma de [ditado por voz](/pt/voice-dictation#change-the-dictation-language) | `"japanese"` |208| `language` | Configure o idioma de resposta preferido do Claude (por exemplo, `"japanese"`, `"spanish"`, `"french"`). Claude responderá neste idioma por padrão. Também define o idioma de [ditado por voz](/pt/voice-dictation#change-the-dictation-language) | `"japanese"` |

207| `minimumVersion` | Piso que impede auto-atualizações em background e `claude update` de instalar uma versão abaixo desta. Mudar do canal `"latest"` para `"stable"` via `/config` solicita que você fique na versão atual ou permita o downgrade. Escolher ficar define este valor. Também útil em [configurações gerenciadas](/pt/permissions#managed-settings) para fixar um mínimo em toda a organização | `"2.1.100"` |209| `minimumVersion` | Piso que impede auto-atualizações em background e `claude update` de instalar uma versão abaixo desta. Mudar do canal `"latest"` para `"stable"` via `/config` solicita que você fique na versão atual ou permita o downgrade. Escolher ficar define este valor. Também útil em [configurações gerenciadas](/pt/permissions#managed-settings) para fixar um mínimo em toda a organização | `"2.1.100"` |

209| `modelOverrides` | Mapear IDs de modelo Anthropic para IDs de modelo específicos do provedor, como ARNs de perfil de inferência Bedrock. Cada entrada do seletor de modelo usa seu valor mapeado ao chamar a API do provedor. Veja [Substituir IDs de modelo por versão](/pt/model-config#override-model-ids-per-version) | `{"claude-opus-4-6": "arn:aws:bedrock:..."}` |211| `modelOverrides` | Mapear IDs de modelo Anthropic para IDs de modelo específicos do provedor, como ARNs de perfil de inferência Bedrock. Cada entrada do seletor de modelo usa seu valor mapeado ao chamar a API do provedor. Veja [Substituir IDs de modelo por versão](/pt/model-config#override-model-ids-per-version) | `{"claude-opus-4-6": "arn:aws:bedrock:..."}` |

210| `otelHeadersHelper` | Script para gerar cabeçalhos OpenTelemetry dinâmicos. Executa na inicialização e periodicamente (veja [Cabeçalhos dinâmicos](/pt/monitoring-usage#dynamic-headers)) | `/bin/generate_otel_headers.sh` |212| `otelHeadersHelper` | Script para gerar cabeçalhos OpenTelemetry dinâmicos. Executa na inicialização e periodicamente. Defina o intervalo de atualização com [`CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS`](/pt/env-vars). Veja [Cabeçalhos dinâmicos](/pt/monitoring-usage#dynamic-headers) | `/bin/generate_otel_headers.sh` |

219| `showClearContextOnPlanAccept` | Mostrar a opção "limpar contexto" na tela de aceitação do plano. Padrão: `false`. Defina como `true` para restaurar a opção | `true` |221| `showClearContextOnPlanAccept` | Mostrar a opção "limpar contexto" na tela de aceitação do plano. Padrão: `false`. Defina como `true` para restaurar a opção | `true` |

220| `showThinkingSummaries` | Mostrar resumos de [pensamento estendido](/pt/model-config#extended-thinking) em sessões interativas. Quando indefinido ou `false` (padrão em modo interativo), blocos de pensamento são redatados pela API e mostrados como um stub recolhido. A redação apenas muda o que você vê, não o que o modelo gera: para reduzir gastos de pensamento, [reduza o orçamento ou desabilite o pensamento](/pt/model-config#extended-thinking) em vez disso. Modo não interativo (`-p`) e chamadores SDK sempre recebem resumos independentemente desta configuração | `true` |222| `showThinkingSummaries` | Mostrar resumos de [pensamento estendido](/pt/model-config#extended-thinking) em sessões interativas. Quando indefinido ou `false` (padrão em modo interativo), blocos de pensamento são redatados pela API e mostrados como um stub recolhido. A redação apenas muda o que você vê, não o que o modelo gera: para reduzir gastos de pensamento, [reduza o orçamento ou desabilite o pensamento](/pt/model-config#extended-thinking) em vez disso. Modo não interativo (`-p`) e chamadores SDK sempre recebem resumos independentemente desta configuração | `true` |

221| `showTurnDuration` | Mostrar mensagens de duração de turno após respostas, por exemplo "Cooked for 1m 6s". Padrão: `true`. Aparece em `/config` como **Show turn duration** | `false` |223| `showTurnDuration` | Mostrar mensagens de duração de turno após respostas, por exemplo "Cooked for 1m 6s". Padrão: `true`. Aparece em `/config` como **Show turn duration** | `false` |

224| `skillOverrides` | {/* min-version: 2.1.129 */}Substituições de visibilidade por skill com chave de nome de skill. O valor é `"on"`, `"name-only"`, `"user-invocable-only"`, ou `"off"`. Permite ocultar ou recolher uma skill sem editar seu SKILL.md. Não se aplica a skills de plugin, que são gerenciadas através de `/plugin`. O menu `/skills` escreve estes em `.claude/settings.local.json`. Veja [Substituir visibilidade de skill a partir de configurações](/pt/skills#override-skill-visibility-from-settings). Requer Claude Code v2.1.129 ou posterior | `{"legacy-context": "name-only", "deploy": "off"}` |

222| `skipWebFetchPreflight` | Pular a [verificação de segurança de domínio WebFetch](/pt/data-usage#webfetch-domain-safety-check) que envia cada nome de host solicitado para `api.anthropic.com` antes de buscar. Defina como `true` em ambientes que bloqueiam tráfego para Anthropic, como implantações Bedrock, Vertex AI, ou Foundry com egresso restritivo. Quando pulado, WebFetch tenta qualquer URL sem consultar a lista de bloqueio | `true` |225| `skipWebFetchPreflight` | Pular a [verificação de segurança de domínio WebFetch](/pt/data-usage#webfetch-domain-safety-check) que envia cada nome de host solicitado para `api.anthropic.com` antes de buscar. Defina como `true` em ambientes que bloqueiam tráfego para Anthropic, como implantações Bedrock, Vertex AI, ou Foundry com egresso restritivo. Quando pulado, WebFetch tenta qualquer URL sem consultar a lista de bloqueio | `true` |

224| `spinnerTipsOverride` | Substituir dicas do spinner com strings personalizadas. `tips`: array de strings de dica. `excludeDefault`: se `true`, mostrar apenas dicas personalizadas; se `false` ou ausente, dicas personalizadas são mescladas com dicas integradas | `{ "excludeDefault": true, "tips": ["Use our internal tool X"] }` |227| `spinnerTipsOverride` | Substituir dicas do spinner com strings personalizadas. `tips`: array de strings de dica. `excludeDefault`: se `true`, mostrar apenas dicas personalizadas; se `false` ou ausente, dicas personalizadas são mescladas com dicas integradas | `{ "excludeDefault": true, "tips": ["Use our internal tool X"] }` |

226| `sshConfigs` | Conexões SSH para mostrar no dropdown de ambiente [Desktop](/pt/desktop#pre-configure-ssh-connections-for-your-team). Cada entrada requer `id`, `name`, e `sshHost`; `sshPort`, `sshIdentityFile`, e `startDirectory` são opcionais. Quando definido em configurações gerenciadas, conexões são somente leitura para usuários. Lido apenas de configurações gerenciadas e de usuário | `[{"id": "dev-vm", "name": "Dev VM", "sshHost": "user@dev.example.com"}]` |229| `sshConfigs` | Conexões SSH para mostrar no dropdown de ambiente [Desktop](/pt/desktop#pre-configure-ssh-connections-for-your-team). Cada entrada requer `id`, `name`, e `sshHost`; `sshPort`, `sshIdentityFile`, e `startDirectory` são opcionais. Quando definido em configurações gerenciadas, conexões são somente leitura para usuários. Lido apenas de configurações gerenciadas e de usuário | `[{"id": "dev-vm", "name": "Dev VM", "sshHost": "user@dev.example.com"}]` |

227| `statusLine` | Configure uma linha de status personalizada para exibir contexto. Veja [documentação de `statusLine`](/pt/statusline) | `{"type": "command", "command": "~/.claude/statusline.sh"}` |230| `statusLine` | Configure uma linha de status personalizada para exibir contexto. Veja [documentação de `statusLine`](/pt/statusline) | `{"type": "command", "command": "~/.claude/statusline.sh"}` |

228| `strictKnownMarketplaces` | (Apenas configurações gerenciadas) Lista de permissões de marketplaces de plugin. Indefinido = sem restrições, array vazio = bloqueio. Aplicado em adição de marketplace e em instalação, atualização, atualização e auto-atualização de plugin, então um marketplace adicionado antes da política ser definida não pode ser usado para buscar plugins. Veja [Restrições de marketplace gerenciado](/pt/plugin-marketplaces#managed-marketplace-restrictions) | `[{ "source": "github", "repo": "acme-corp/plugins" }]` |231| `strictKnownMarketplaces` | (Apenas configurações gerenciadas) Lista de permissões de marketplaces de plugin. Indefinido = sem restrições, array vazio = bloqueio. Aplicado em adição de marketplace e em instalação, atualização, atualização e auto-atualização de plugin, então um marketplace adicionado antes da política ser definida não pode ser usado para buscar plugins. Veja [Restrições de marketplace gerenciado](/pt/plugin-marketplaces#managed-marketplace-restrictions) | `[{ "source": "github", "repo": "acme-corp/plugins" }]` |

229| `teammateMode` | Como [colegas de equipe de agente](/pt/agent-teams) são exibidos: `auto` (escolhe painéis divididos em tmux ou iTerm2, em processo caso contrário), `in-process`, ou `tmux`. Veja [escolher um modo de exibição](/pt/agent-teams#choose-a-display-mode) | `"in-process"` |232| `syntaxHighlightingDisabled` | Desabilitar destaque de sintaxe em diffs, blocos de código e visualizações de arquivo | `true` |

233| `teammateMode` | Como [colegas de equipe de agente](/pt/agent-teams) são exibidos: `auto` (escolhe painéis divididos em tmux ou iTerm2, em processo caso contrário), `in-process`, ou `tmux`. `--teammate-mode` substitui isto para uma sessão. Veja [escolher um modo de exibição](/pt/agent-teams#choose-a-display-mode) | `"in-process"` |

230| `terminalProgressBarEnabled` | Mostrar a barra de progresso do terminal em terminais suportados: ConEmu, Ghostty 1.2.0+, e iTerm2 3.6.6+. Padrão: `true`. Aparece em `/config` como **Terminal progress bar** | `false` |234| `terminalProgressBarEnabled` | Mostrar a barra de progresso do terminal em terminais suportados: ConEmu, Ghostty 1.2.0+, e iTerm2 3.6.6+. Padrão: `true`. Aparece em `/config` como **Terminal progress bar** | `false` |

231| `tui` | Renderizador de UI de terminal. Use `"fullscreen"` para o renderizador [alt-screen](/pt/fullscreen) sem cintilação com scrollback virtualizado. Use `"default"` para o renderizador clássico de tela principal. Defina via `/tui` | `"fullscreen"` |235| `tui` | Renderizador de UI de terminal. Use `"fullscreen"` para o renderizador [alt-screen](/pt/fullscreen) sem cintilação com scrollback virtualizado. Use `"default"` para o renderizador clássico de tela principal. Defina via `/tui`. Você também pode definir a variável de ambiente [`CLAUDE_CODE_NO_FLICKER`](/pt/env-vars) | `"fullscreen"` |

232| `useAutoModeDuringPlan` | Se Plan Mode usa semântica de modo automático quando o modo automático está disponível. Padrão: `true`. Não lido de configurações de projeto compartilhadas. Aparece em `/config` como "Use auto mode during plan" | `false` |236| `useAutoModeDuringPlan` | Se Plan Mode usa semântica de modo automático quando o modo automático está disponível. Padrão: `true`. Não lido de configurações de projeto compartilhadas. Aparece em `/config` como "Use auto mode during plan" | `false` |

233| `viewMode` | Modo de visualização de transcrição padrão na inicialização: `"default"`, `"verbose"`, ou `"focus"`. Substitui a seleção pegajosa `/focus` quando definido | `"verbose"` |237| `viewMode` | Modo de visualização de transcrição padrão na inicialização: `"default"`, `"verbose"`, ou `"focus"`. Substitui a seleção pegajosa `/focus` quando definido. O flag `--verbose` substitui isto para uma sessão | `"verbose"` |

234| `voice` | Configurações de [ditado por voz](/pt/voice-dictation): `enabled` ativa ditado, `mode` seleciona `"hold"` ou `"tap"`, e `autoSubmit` envia o prompt ao soltar a tecla em modo hold. Escrito automaticamente quando você executa `/voice`. Requer uma conta Claude.ai | `{ "enabled": true, "mode": "tap" }` |238| `voice` | Configurações de [ditado por voz](/pt/voice-dictation): `enabled` ativa ditado, `mode` seleciona `"hold"` ou `"tap"`, e `autoSubmit` envia o prompt ao soltar a tecla em modo hold. Escrito automaticamente quando você executa `/voice`. Requer uma conta Claude.ai | `{ "enabled": true, "mode": "tap" }` |

236| `wslInheritsWindowsSettings` | (Apenas configurações gerenciadas do Windows) Quando `true`, Claude Code no WSL lê configurações gerenciadas da cadeia de política do Windows além de `/etc/claude-code`, com fontes do Windows tendo prioridade. Apenas honrado quando definido na chave de registro HKLM ou `C:\Program Files\ClaudeCode\managed-settings.json`, ambos exigindo admin do Windows para escrever. Para que a política HKCU também se aplique no WSL, a flag deve ser adicionalmente definida no HKCU em si. Não tem efeito no Windows nativo | `true` |240| `wslInheritsWindowsSettings` | (Apenas configurações gerenciadas do Windows) Quando `true`, Claude Code no WSL lê configurações gerenciadas da cadeia de política do Windows além de `/etc/claude-code`, com fontes do Windows tendo prioridade. Apenas honrado quando definido na chave de registro HKLM ou `C:\Program Files\ClaudeCode\managed-settings.json`, ambos exigindo admin do Windows para escrever. Para que a política HKCU também se aplique no WSL, a flag deve ser adicionalmente definida no HKCU em si. Não tem efeito no Windows nativo | `true` |

244</Note>248</Note>

245 249

247| :------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :------ |251| :------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :------ |

248| `autoConnectIde` | Conectar automaticamente a um IDE em execução quando Claude Code inicia de um terminal externo. Padrão: `false`. Aparece em `/config` como **Auto-connect to IDE (external terminal)** ao executar fora de um terminal VS Code ou JetBrains | `true` |252| `autoConnectIde` | Conectar automaticamente a um IDE em execução quando Claude Code inicia de um terminal externo. Padrão: `false`. Aparece em `/config` como **Auto-connect to IDE (external terminal)** ao executar fora de um terminal VS Code ou JetBrains. A variável de ambiente [`CLAUDE_CODE_AUTO_CONNECT_IDE`](/pt/env-vars) substitui isto quando definida | `true` |

249| `autoInstallIdeExtension` | Instalar automaticamente a extensão IDE do Claude Code ao executar de um terminal VS Code. Padrão: `true`. Aparece em `/config` como **Auto-install IDE extension** ao executar dentro de um terminal VS Code ou JetBrains. Você também pode definir a variável de ambiente [`CLAUDE_CODE_IDE_SKIP_AUTO_INSTALL`](/pt/env-vars) | `false` |253| `autoInstallIdeExtension` | Instalar automaticamente a extensão IDE do Claude Code ao executar de um terminal VS Code. Padrão: `true`. Aparece em `/config` como **Auto-install IDE extension** ao executar dentro de um terminal VS Code ou JetBrains. Você também pode definir a variável de ambiente [`CLAUDE_CODE_IDE_SKIP_AUTO_INSTALL`](/pt/env-vars) | `false` |

250| `externalEditorContext` | Prepend a resposta anterior do Claude como contexto comentado com `#` quando você abre o editor externo com `Ctrl+G`. Padrão: `false`. Aparece em `/config` como **Show last response in external editor** | `true` |254| `externalEditorContext` | Prepend a resposta anterior do Claude como contexto comentado com `#` quando você abre o editor externo com `Ctrl+G`. Padrão: `false`. Aparece em `/config` como **Show last response in external editor** | `true` |

251 255

444 448

445**Restringir URLs de hook HTTP:**449**Restringir URLs de hook HTTP:**

446 450

447Limitar quais URLs hooks HTTP podem almejar. Suporta `*` como curinga para correspondência. Quando o array é definido, hooks HTTP almejando URLs não correspondentes são silenciosamente bloqueados.451Limitar quais URLs hooks HTTP podem almejar. Suporta `*` como curinga para correspondência. Quando o array é definido, hooks HTTP almejando URLs não correspondentes são silenciosamente bloqueados. A correspondência de nome de host é insensível a maiúsculas e minúsculas e ignora um ponto FQDN à direita, correspondendo à semântica de DNS.

448 452

449```json theme={null}453```json theme={null}

450{454{

472 * Dentro do nível gerenciado, a precedência é: gerenciadas pelo servidor > políticas de nível MDM/SO > baseadas em arquivo (`managed-settings.d/*.json` + `managed-settings.json`) > registro HKCU (apenas Windows). Apenas uma fonte gerenciada é usada; fontes não se mesclam entre camadas. Dentro da camada baseada em arquivo, arquivos drop-in e o arquivo base são mesclados juntos.476 * Dentro do nível gerenciado, a precedência é: gerenciadas pelo servidor > políticas de nível MDM/SO > baseadas em arquivo (`managed-settings.d/*.json` + `managed-settings.json`) > registro HKCU (apenas Windows). Apenas uma fonte gerenciada é usada; fontes não se mesclam entre camadas. Dentro da camada baseada em arquivo, arquivos drop-in e o arquivo base são mesclados juntos.

473 477

4742. **Argumentos de linha de comando**4782. **Argumentos de linha de comando**

475 * Substituições temporárias para uma sessão específica479 * Substituições temporárias para uma sessão específica. JSON passado via `--settings <file-or-json>` se mescla com configurações baseadas em arquivo usando as mesmas regras que as outras camadas: uma chave definida aqui substitui a mesma chave em configurações local, projeto, ou usuário, e omitir uma chave deixa o valor da camada inferior no lugar

476 480

4773. **Configurações de projeto local** (`.claude/settings.local.json`)4813. **Configurações de projeto local** (`.claude/settings.local.json`)

478 * Configurações pessoais específicas do projeto482 * Configurações pessoais específicas do projeto

setup.md +8 −4

Details

175 175

176## Atualizar Claude Code176## Atualizar Claude Code

177 177

178As instalações nativas são atualizadas automaticamente em segundo plano. Você pode [configurar o canal de lançamento](#configure-release-channel) para controlar se recebe atualizações imediatamente ou em um cronograma estável com atraso, ou [desabilitar atualizações automáticas](#disable-auto-updates) completamente. As instalações do Homebrew, WinGet e [gerenciador de pacotes Linux](#install-with-linux-package-managers) requerem atualizações manuais.178As instalações nativas são atualizadas automaticamente em segundo plano. Você pode [configurar o canal de lançamento](#configure-release-channel) para controlar se recebe atualizações imediatamente ou em um cronograma estável com atraso, ou [desabilitar atualizações automáticas](#disable-auto-updates) completamente. As instalações do Homebrew, WinGet e [gerenciador de pacotes Linux](#install-with-linux-package-managers) requerem atualizações manuais por padrão.

179 179

180### Atualizações automáticas180### Atualizações automáticas

181 181

182Claude Code verifica atualizações na inicialização e periodicamente durante a execução. As atualizações são baixadas e instaladas em segundo plano, depois entram em vigor na próxima vez que você inicia Claude Code.182Claude Code verifica atualizações na inicialização e periodicamente durante a execução. As atualizações são baixadas e instaladas em segundo plano, depois entram em vigor na próxima vez que você inicia Claude Code.

183 183

184<Note>184<Note>

185 As instalações do Homebrew, WinGet, apt, dnf e apk não são atualizadas automaticamente. Para Homebrew, execute `brew upgrade claude-code` ou `brew upgrade claude-code@latest`, dependendo de qual cask você instalou. Para WinGet, execute `winget upgrade Anthropic.ClaudeCode`. Para gerenciadores de pacotes Linux, consulte os comandos de atualização em [Instalar com gerenciadores de pacotes Linux](#install-with-linux-package-managers).185 As instalações do Homebrew, WinGet, apt, dnf e apk não são atualizadas automaticamente por padrão; veja abaixo para optar por Homebrew e WinGet. Para atualizar o Homebrew manualmente, execute `brew upgrade claude-code` ou `brew upgrade claude-code@latest`, dependendo de qual cask você instalou. Para WinGet, execute `winget upgrade Anthropic.ClaudeCode`. Para gerenciadores de pacotes Linux, consulte os comandos de atualização em [Instalar com gerenciadores de pacotes Linux](#install-with-linux-package-managers).

186

187 Para que Claude Code execute o comando de atualização para você no Homebrew ou WinGet, defina [`CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE`](/pt/env-vars) como `1`. Claude Code então executa a atualização em segundo plano quando uma nova versão está disponível e mostra um prompt de reinicialização em caso de sucesso. A atualização visa apenas o pacote Claude Code e não afeta outro software que você tenha instalado.

188

189 No WinGet, a atualização pode falhar enquanto Claude Code está em execução porque o Windows bloqueia o executável. Nesse caso, Claude Code mostra o comando manual em vez disso. apt, dnf e apk continuam a exigir uma atualização manual porque esses comandos precisam de privilégios elevados.

186 190

187 **Problema conhecido:** Claude Code pode notificá-lo sobre atualizações antes que a nova versão esteja disponível nesses gerenciadores de pacotes. Se uma atualização falhar, aguarde e tente novamente mais tarde.191 **Problema conhecido:** Claude Code pode notificá-lo sobre atualizações antes que a nova versão esteja disponível nesses gerenciadores de pacotes. Se uma atualização falhar, aguarde e tente novamente mais tarde.

188 192

489 493

490## Desinstalar Claude Code494## Desinstalar Claude Code

491 495

492Para remover Claude Code, siga as instruções para seu método de instalação.496Para remover Claude Code, siga as instruções para seu método de instalação. Se `claude` ainda for executado depois, você provavelmente tem uma segunda instalação ou um alias de shell residual de um instalador mais antigo. Consulte [Verificar instalações conflitantes](/pt/troubleshoot-install#check-for-conflicting-installations) para encontrá-lo e removê-lo.

493 497

494### Instalação nativa498### Instalação nativa

495 499

572### Remover arquivos de configuração576### Remover arquivos de configuração

573 577

574<Warning>578<Warning>

575 Remover arquivos de configuração excluirá todas as suas configurações, ferramentas permitidas, configurações do MCP server e histórico de sessão.579 Remover arquivos de configuração excluirá todas as suas configurações, ferramentas permitidas, configurações do servidor MCP e histórico de sessão.

576</Warning>580</Warning>

577 581

578A extensão VS Code, o plugin JetBrains e o aplicativo de desktop também escrevem em `~/.claude/`. Se algum deles ainda estiver instalado, o diretório será recriado na próxima vez que for executado. Para remover Claude Code completamente, desinstale a [extensão VS Code](/pt/vs-code#uninstall-the-extension), o plugin JetBrains e o aplicativo de desktop antes de excluir esses arquivos.582A extensão VS Code, o plugin JetBrains e o aplicativo de desktop também escrevem em `~/.claude/`. Se algum deles ainda estiver instalado, o diretório será recriado na próxima vez que for executado. Para remover Claude Code completamente, desinstale a [extensão VS Code](/pt/vs-code#uninstall-the-extension), o plugin JetBrains e o aplicativo de desktop antes de excluir esses arquivos.

skills.md +61 −28

Details

20 20

21## Skills agrupadas21## Skills agrupadas

22 22

23Claude Code inclui um conjunto de skills agrupadas que estão disponíveis em cada sessão, incluindo `/simplify`, `/batch`, `/debug`, `/loop`, e `/claude-api`. Diferentemente da maioria dos comandos integrados, que executam lógica fixa diretamente, skills agrupadas são baseadas em prompt: elas dão ao Claude um manual detalhado e deixam que ele orquestre o trabalho usando suas ferramentas. Você invoca elas da mesma forma que qualquer outra skill, digitando `/` seguido do nome da skill.23Claude Code inclui um conjunto de skills agrupadas que estão disponíveis em cada sessão, incluindo `/simplify`, `/batch`, `/debug`, `/loop`, e `/claude-api`. Diferentemente da maioria dos comandos integrados, que executam lógica fixa diretamente, skills agrupadas são baseadas em prompt: elas dão ao Claude instruções detalhadas e deixam que ele orquestre o trabalho usando suas ferramentas. Você invoca elas da mesma forma que qualquer outra skill, digitando `/` seguido do nome da skill.

24 24

25Skills agrupadas estão listadas junto com comandos integrados na [referência de comandos](/pt/commands), marcadas como **Skill** na coluna Propósito.25Skills agrupadas estão listadas junto com comandos integrados na [referência de comandos](/pt/commands), marcadas como **Skill** na coluna Propósito.

26 26

28 28

29### Crie sua primeira skill29### Crie sua primeira skill

30 30

31Este exemplo cria uma skill que ensina Claude a explicar código usando diagramas visuais e analogias. Como usa frontmatter padrão, Claude pode carregá-la automaticamente quando você pergunta como algo funciona, ou você pode invocá-la diretamente com `/explain-code`.31Este exemplo cria uma skill que resume as mudanças não confirmadas em seu repositório git e sinaliza qualquer coisa arriscada. Ele puxa o diff ao vivo para o prompt antes de Claude lê-lo, então a resposta é fundamentada em sua árvore de trabalho real em vez do que Claude pode adivinhar a partir de arquivos abertos. Claude carrega a skill automaticamente quando você pergunta sobre suas mudanças, ou você pode invocá-la diretamente com `/summarize-changes`.

32 32

33<Steps>33<Steps>

34 <Step title="Crie o diretório da skill">34 <Step title="Crie o diretório da skill">

35 Crie um diretório para a skill em sua pasta de skills pessoais. Skills pessoais estão disponíveis em todos os seus projetos.35 Crie um diretório para a skill em sua pasta de skills pessoais. Skills pessoais estão disponíveis em todos os seus projetos.

36 36

37 ```bash theme={null}37 ```bash theme={null}

~~38 mkdir -p ~/.claude/skills/explain-code~~38 mkdir -p ~/.claude/skills/summarize-changes

39 ```39 ```

40 </Step>40 </Step>

41 41

42 <Step title="Escreva SKILL.md">42 <Step title="Escreva SKILL.md">

43 Cada skill precisa de um arquivo `SKILL.md` com duas partes: frontmatter YAML (entre marcadores `---`) que diz ao Claude quando usar a skill, e conteúdo markdown com instruções que Claude segue quando a skill é invocada. O nome do diretório se torna o `/slash-command`, e a `description` ajuda Claude a decidir quando carregá-la automaticamente.43 Cada skill precisa de um arquivo `SKILL.md` com duas partes: frontmatter YAML entre marcadores `---` que diz ao Claude quando usar a skill, e conteúdo markdown com as instruções que Claude segue quando a skill é executada. O nome do diretório se torna o comando que você digita, e a `description` ajuda Claude a decidir quando carregar a skill automaticamente.

44 44

~~45 Crie `~/.claude/skills/explain-code/SKILL.md`:~~45 Salve isto em `~/.claude/skills/summarize-changes/SKILL.md`:

46 46

47 ```yaml theme={null}47 ```yaml theme={null}

48 ---48 ---

49 description: "Explica código com diagramas visuais e analogias. Use ao explicar como o código funciona, ensinando sobre uma base de código, ou quando o usuário pergunta 'como isso funciona?'"49 description: Summarizes uncommitted changes and flags anything risky. Use when the user asks what changed, wants a commit message, or asks to review their diff.

50 ---50 ---

51 51

~~52 When explaining code, always include:~~52 ## Current changes

53 53

~~54 1. **Start with an analogy**: Compare the code to something from everyday life~~54 !`git diff HEAD`

~~55 2. **Draw a diagram**: Use ASCII art to show the flow, structure, or relationships~~

~~56 3. **Walk through the code**: Explain step-by-step what happens~~

~~57 4. **Highlight a gotcha**: What's a common mistake or misconception?~~

58 55

~~59 Keep explanations conversational. For complex concepts, use multiple analogies.~~56 ## Instructions

58 Summarize the changes above in two or three bullet points, then list any risks you notice such as missing error handling, hardcoded values, or tests that need updating. If the diff is empty, say there are no uncommitted changes.

60 ```59 ```

61 A linha `` !`git diff HEAD` `` usa [injeção de contexto dinâmico](#inject-dynamic-context): Claude Code executa o comando e substitui a linha por sua saída antes de Claude ver o conteúdo da skill, então as instruções chegam com o diff atual já embutido.

61 </Step>62 </Step>

62 63

63 <Step title="Teste a skill">64 <Step title="Teste a skill">

~~64 Você pode testá-la de duas formas:~~65 Abra um projeto git, faça uma pequena edição em qualquer arquivo e inicie Claude Code executando `claude`. Você pode testar a skill de duas formas.

65 66

66 **Deixe Claude invocá-la automaticamente** perguntando algo que corresponda à descrição:67 **Deixe Claude invocá-la automaticamente** perguntando algo que corresponda à descrição:

67 68

68 ```text theme={null}69 ```text theme={null}

~~69 How does this code work?~~70 What did I change?

70 ```71 ```

71 72

72 **Ou invoque-a diretamente** com o nome da skill:73 **Ou invoque-a diretamente** com o nome da skill:

73 74

74 ```text theme={null}75 ```text theme={null}

~~75 /explain-code src/auth/login.ts~~76 /summarize-changes

76 ```77 ```

77 78

~~78 De qualquer forma, Claude deve incluir uma analogia e diagrama ASCII em sua explicação.~~79 De qualquer forma, Claude deve responder com um breve resumo de sua edição e uma lista de riscos.

79 </Step>80 </Step>

80</Steps>81</Steps>

81 82

112 └── validate.sh # Script que Claude pode executar113 └── validate.sh # Script que Claude pode executar

113```114```

114 115

115O `SKILL.md` contém as instruções principais e é obrigatório. Outros arquivos são opcionais e permitem que você construa skills mais poderosas: templates para Claude preencher, exemplos de saída mostrando o formato esperado, scripts que Claude pode executar, ou documentação de referência detalhada. Referencie esses arquivos de seu `SKILL.md` para que Claude saiba o que cada arquivo contém e quando carregá-lo. Consulte [Adicione arquivos de suporte](#add-supporting-files) para mais detalhes.116O `SKILL.md` contém as instruções principais e é obrigatório. Outros arquivos são opcionais e permitem que você construa skills mais poderosas: templates para Claude preencher, exemplos de saída mostrando o formato esperado, scripts que Claude pode executar, ou documentação de referência detalhada. Referencie esses arquivos de seu `SKILL.md` para que Claude saiba o que eles contêm e quando carregá-los. Consulte [Adicione arquivos de suporte](#add-supporting-files) para mais detalhes.

116 117

117<Note>118<Note>

118 Arquivos em `.claude/commands/` ainda funcionam e suportam o mesmo [frontmatter](#frontmatter-reference). Skills são recomendadas já que suportam recursos adicionais como arquivos de suporte.119 Arquivos em `.claude/commands/` ainda funcionam e suportam o mesmo [frontmatter](#frontmatter-reference). Skills são recomendadas já que suportam recursos adicionais como arquivos de suporte.

168 169

169Seu `SKILL.md` pode conter qualquer coisa, mas pensar em como você quer que a skill seja invocada (por você, por Claude, ou ambos) e onde você quer que seja executada (inline ou em um subagent) ajuda a guiar o que incluir. Para skills complexas, você também pode [adicionar arquivos de suporte](#add-supporting-files) para manter a skill principal focada.170Seu `SKILL.md` pode conter qualquer coisa, mas pensar em como você quer que a skill seja invocada (por você, por Claude, ou ambos) e onde você quer que seja executada (inline ou em um subagent) ajuda a guiar o que incluir. Para skills complexas, você também pode [adicionar arquivos de suporte](#add-supporting-files) para manter a skill principal focada.

170 171

172Mantenha o corpo em si conciso. Uma vez que uma skill carrega, seu conteúdo [permanece em contexto entre turnos](#skill-content-lifecycle), então cada linha é um custo de token recorrente. Declare o que fazer em vez de narrar como ou por que, e aplique o mesmo teste de concisão que você faria para [conteúdo de CLAUDE.md](/pt/best-practices#write-an-effective-claude-md).

173

171### Referência de frontmatter174### Referência de frontmatter

172 175

173Além do conteúdo markdown, você pode configurar o comportamento da skill usando campos de frontmatter YAML entre marcadores `---` no topo de seu arquivo `SKILL.md`:176Além do conteúdo markdown, você pode configurar o comportamento da skill usando campos de frontmatter YAML entre marcadores `---` no topo de seu arquivo `SKILL.md`:

305 308

306O campo `allowed-tools` concede permissão para as ferramentas listadas enquanto a skill está ativa, para que Claude possa usá-las sem solicitar sua aprovação. Ele não restringe quais ferramentas estão disponíveis: cada ferramenta permanece chamável, e suas [configurações de permissão](/pt/permissions) ainda governam ferramentas que não estão listadas.309O campo `allowed-tools` concede permissão para as ferramentas listadas enquanto a skill está ativa, para que Claude possa usá-las sem solicitar sua aprovação. Ele não restringe quais ferramentas estão disponíveis: cada ferramenta permanece chamável, e suas [configurações de permissão](/pt/permissions) ainda governam ferramentas que não estão listadas.

307 310

311Para skills verificadas em um diretório `.claude/skills/` de um projeto, `allowed-tools` entra em vigor após você aceitar o diálogo de confiança do workspace para essa pasta, o mesmo que regras de permissão em `.claude/settings.json`. Revise skills de projeto antes de confiar em um repositório, já que uma skill pode conceder a si mesma acesso amplo a ferramentas.

312

308Esta skill deixa Claude executar comandos git sem aprovação por uso sempre que você invoca:313Esta skill deixa Claude executar comandos git sem aprovação por uso sempre que você invoca:

309 314

310```yaml theme={null}315```yaml theme={null}

416Para desabilitar este comportamento para skills e comandos personalizados de fontes de usuário, projeto, plugin ou [diretório adicional](#skills-from-additional-directories), defina `"disableSkillShellExecution": true` em [configurações](/pt/settings). Cada comando é substituído com `[shell command execution disabled by policy]` em vez de ser executado. Skills agrupadas e gerenciadas não são afetadas. Esta configuração é mais útil em [configurações gerenciadas](/pt/permissions#managed-settings), onde usuários não podem sobrescrevê-la.421Para desabilitar este comportamento para skills e comandos personalizados de fontes de usuário, projeto, plugin ou [diretório adicional](#skills-from-additional-directories), defina `"disableSkillShellExecution": true` em [configurações](/pt/settings). Cada comando é substituído com `[shell command execution disabled by policy]` em vez de ser executado. Skills agrupadas e gerenciadas não são afetadas. Esta configuração é mais útil em [configurações gerenciadas](/pt/permissions#managed-settings), onde usuários não podem sobrescrevê-la.

417 422

418<Tip>423<Tip>

419 Para habilitar [pensamento estendido](/pt/common-workflows#use-extended-thinking-thinking-mode) em uma skill, inclua a palavra "ultrathink" em qualquer lugar no conteúdo de sua skill.424 Para solicitar raciocínio mais profundo quando uma skill é executada, inclua `ultrathink` em qualquer lugar no conteúdo da skill. Consulte [Use ultrathink for one-off deep reasoning](/pt/model-config#use-ultrathink-for-one-off-deep-reasoning).

420</Tip>425</Tip>

421 426

422### Execute skills em um subagent427### Execute skills em um subagent

496 O campo `user-invocable` apenas controla visibilidade de menu, não acesso à ferramenta Skill. Use `disable-model-invocation: true` para bloquear invocação programática.501 O campo `user-invocable` apenas controla visibilidade de menu, não acesso à ferramenta Skill. Use `disable-model-invocation: true` para bloquear invocação programática.

497</Note>502</Note>

498 503

504### Substitua visibilidade de skill a partir de configurações

505

506A configuração `skillOverrides` controla visibilidade de skill a partir de suas [configurações](/pt/settings) em vez do frontmatter da própria skill. Use-a para skills cujo SKILL.md você não quer editar, como aquelas verificadas em um repositório de projeto compartilhado ou fornecidas por um servidor MCP. O menu `/skills` escreve para você: destaque uma skill e pressione `Space` para alternar estados, depois `Enter` para salvar em `.claude/settings.local.json`.

507

508Cada chave é um nome de skill e cada valor é um de quatro estados:

509

510| Valor | Listado para Claude | No menu `/` |

511| :---------------------- | :------------------ | :---------- |

512| `"on"` | Nome e descrição | Sim |

513| `"name-only"` | Apenas nome | Sim |

514| `"user-invocable-only"` | Oculto | Sim |

515| `"off"` | Oculto | Oculto |

516

517Uma skill que está ausente de `skillOverrides` é tratada como `"on"`. O exemplo abaixo colapsa uma skill para seu nome e desativa outra inteiramente:

518

519```json theme={null}

520{

521 "skillOverrides": {

522 "legacy-context": "name-only",

523 "deploy": "off"

524 }

525}

526```

527

528Skills de plugin não são afetadas por `skillOverrides`. Gerencie aquelas através de `/plugin` em vez disso.

529

499## Compartilhe skills530## Compartilhe skills

500 531

501Skills podem ser distribuídas em diferentes escopos dependendo do seu público:532Skills podem ser distribuídas em diferentes escopos dependendo do seu público:

516mkdir -p ~/.claude/skills/codebase-visualizer/scripts547mkdir -p ~/.claude/skills/codebase-visualizer/scripts

517```548```

518 549

519Crie `~/.claude/skills/codebase-visualizer/SKILL.md`. A descrição diz ao Claude quando ativar esta Skill, e as instruções dizem ao Claude para executar o script agrupado:550Salve isto em `~/.claude/skills/codebase-visualizer/SKILL.md`. A descrição diz ao Claude quando ativar esta Skill, e as instruções dizem ao Claude para executar o script agrupado. O caminho do script usa [`${CLAUDE_SKILL_DIR}`](#available-string-substitutions) para que seja resolvido corretamente se a skill estiver instalada no nível pessoal, de projeto ou de plugin:

520 551

521````yaml theme={null}552````yaml theme={null}

522---553---

523name: codebase-visualizer554name: codebase-visualizer

524description: Generate an interactive collapsible tree visualization of your codebase. Use when exploring a new repo, understanding project structure, or identifying large files.555description: Generate an interactive collapsible tree visualization of your codebase. Use when exploring a new repo, understanding project structure, or identifying large files.

525allowed-tools: Bash(python *)556allowed-tools: Bash(python3 *)

526---557---

527 558

528# Codebase Visualizer559# Codebase Visualizer

534Run the visualization script from your project root:565Run the visualization script from your project root:

535 566

536```bash567```bash

537python ~/.claude/skills/codebase-visualizer/scripts/visualize.py .568python3 ${CLAUDE_SKILL_DIR}/scripts/visualize.py .

538```569```

539 570

540This creates `codebase-map.html` in the current directory and opens it in your default browser.571This creates `codebase-map.html` in the current directory and opens it in your default browser.

547- **Directory totals**: Shows aggregate size of each folder578- **Directory totals**: Shows aggregate size of each folder

548````579````

549 580

550Crie `~/.claude/skills/codebase-visualizer/scripts/visualize.py`. Este script varre uma árvore de diretório e gera um arquivo HTML auto-contido com:581Salve isto em `~/.claude/skills/codebase-visualizer/scripts/visualize.py`. Este script varre uma árvore de diretório e gera um arquivo HTML auto-contido com:

551 582

552* Uma **barra lateral de resumo** mostrando contagem de arquivos, contagem de diretórios, tamanho total e número de tipos de arquivo583* Uma **barra lateral de resumo** mostrando contagem de arquivos, contagem de diretórios, tamanho total e número de tipos de arquivo

553* Um **gráfico de barras** dividindo o codebase por tipo de arquivo (top 8 por tamanho)584* Um **gráfico de barras** dividindo o codebase por tipo de arquivo (top 8 por tamanho)

554* Uma **árvore recolhível** onde você pode expandir e recolher diretórios, com indicadores de tipo de arquivo codificados por cor585* Uma **árvore recolhível** onde você pode expandir e recolher diretórios, com indicadores de tipo de arquivo codificados por cor

555 586

556O script requer Python mas usa apenas bibliotecas integradas, então não há pacotes para instalar:587O script requer Python 3 mas usa apenas bibliotecas integradas, então não há pacotes para instalar:

557 588

558```python expandable theme={null}589```python expandable theme={null}

559#!/usr/bin/env python3590#!/usr/bin/env python3

562import json593import json

563import sys594import sys

564import webbrowser595import webbrowser

596from html import escape

565from pathlib import Path597from pathlib import Path

566from collections import Counter598from collections import Counter

567 599

650 {lang_bars}682 {lang_bars}

651 </div>683 </div>

652 <div class="main">684 <div class="main">

653 <h1>📁 {data["name"]}</h1>685 <h1>📁 {escape(data["name"])}</h1>

654 <ul class="tree" id="root"></ul>686 <ul class="tree" id="root"></ul>

655 </div>687 </div>

656 </div>688 </div>

658 const data = {json.dumps(data)};690 const data = {json.dumps(data)};

659 const colors = {json.dumps(colors)};691 const colors = {json.dumps(colors)};

660 function fmt(b) {{ if (b < 1024) return b + ' B'; if (b < 1048576) return (b/1024).toFixed(1) + ' KB'; return (b/1048576).toFixed(1) + ' MB'; }}692 function fmt(b) {{ if (b < 1024) return b + ' B'; if (b < 1048576) return (b/1024).toFixed(1) + ' KB'; return (b/1048576).toFixed(1) + ' MB'; }}

693 function esc(s) {{ return s.replace(/[&<>"']/g, c => ({{"&":"&","<":"<",">":">",'"':""","'":"'"}}[c])); }}

661 function render(node, parent) {{694 function render(node, parent) {{

662 if (node.children) {{695 if (node.children) {{

663 const det = document.createElement('details');696 const det = document.createElement('details');

664 det.open = parent === document.getElementById('root');697 det.open = parent === document.getElementById('root');

665 det.innerHTML = `<summary><span class="folder">📁 ${{node.name}}</span><span class="size">${{fmt(node.size)}}</span></summary>`;698 det.innerHTML = `<summary><span class="folder">📁 ${{esc(node.name)}}</span><span class="size">${{fmt(node.size)}}</span></summary>`;

666 const ul = document.createElement('ul'); ul.className = 'tree';699 const ul = document.createElement('ul'); ul.className = 'tree';

667 node.children.sort((a,b) => (b.children?1:0)-(a.children?1:0) || a.name.localeCompare(b.name));700 node.children.sort((a,b) => (b.children?1:0)-(a.children?1:0) || a.name.localeCompare(b.name));

668 node.children.forEach(c => render(c, ul));701 node.children.forEach(c => render(c, ul));

670 const li = document.createElement('li'); li.appendChild(det); parent.appendChild(li);703 const li = document.createElement('li'); li.appendChild(det); parent.appendChild(li);

671 }} else {{704 }} else {{

672 const li = document.createElement('li'); li.className = 'file';705 const li = document.createElement('li'); li.className = 'file';

673 li.innerHTML = `<span class="dot" style="background:${{colors[node.ext]||'#6b7280'}}"></span>${{node.name}}<span class="size">${{fmt(node.size)}}</span>`;706 li.innerHTML = `<span class="dot" style="background:${{colors[node.ext]||'#6b7280'}}"></span>${{esc(node.name)}}<span class="size">${{fmt(node.size)}}</span>`;

674 parent.appendChild(li);707 parent.appendChild(li);

675 }}708 }}

676 }}709 }}

691 724

692Para testar, abra Claude Code em qualquer projeto e peça "Visualize this codebase." Claude executa o script, gera `codebase-map.html`, e abre em seu navegador.725Para testar, abra Claude Code em qualquer projeto e peça "Visualize this codebase." Claude executa o script, gera `codebase-map.html`, e abre em seu navegador.

693 726

694Este padrão funciona para qualquer saída visual: gráficos de dependência, relatórios de cobertura de testes, documentação de API, ou visualizações de esquema de banco de dados. O script agrupado faz o trabalho pesado enquanto Claude lida com orquestração.727Este padrão funciona para qualquer saída visual: gráficos de dependência, relatórios de cobertura de testes, documentação de API, ou visualizações de esquema de banco de dados. O script agrupado faz o trabalho enquanto Claude lida com orquestração.

695 728

696## Solução de problemas729## Solução de problemas

697 730

715 748

716Descrições de skills são carregadas em contexto para que Claude saiba o que está disponível. Todos os nomes de skills são sempre incluídos, mas se você tem muitas skills, descrições são encurtadas para caber no orçamento de caracteres, o que pode remover as palavras-chave que Claude precisa para corresponder sua solicitação. O orçamento escala dinamicamente em 1% da janela de contexto, com fallback de 8.000 caracteres.749Descrições de skills são carregadas em contexto para que Claude saiba o que está disponível. Todos os nomes de skills são sempre incluídos, mas se você tem muitas skills, descrições são encurtadas para caber no orçamento de caracteres, o que pode remover as palavras-chave que Claude precisa para corresponder sua solicitação. O orçamento escala dinamicamente em 1% da janela de contexto, com fallback de 8.000 caracteres.

717 750

718Para aumentar o limite, defina a variável de ambiente `SLASH_COMMAND_TOOL_CHAR_BUDGET`. Ou corte descrições na fonte: coloque o caso de uso principal na frente, já que o texto combinado de cada entrada é limitado a 1.536 caracteres independentemente do orçamento.751Para aumentar o limite, defina a variável de ambiente `SLASH_COMMAND_TOOL_CHAR_BUDGET`. Para liberar orçamento para outras skills, defina entradas de baixa prioridade como `"name-only"` em [`skillOverrides`](#override-skill-visibility-from-settings) para que sejam listadas sem uma descrição. Você também pode aparar o texto de `description` e `when_to_use` na fonte: coloque o caso de uso principal na frente, já que o texto combinado de cada entrada é limitado a 1.536 caracteres independentemente do orçamento.

719 752

720## Recursos relacionados753## Recursos relacionados

721 754

statusline.md +10 −11

Details

134 134

135**Quando é atualizado**135**Quando é atualizado**

136 136

137Seu script é executado após cada nova mensagem do assistente, quando o modo de permissão muda ou quando o modo vim alterna. As atualizações são debounced em 300ms, significando que mudanças rápidas são agrupadas e seu script é executado uma vez que as coisas se estabilizam. Se uma nova atualização for acionada enquanto seu script ainda está em execução, a execução em andamento é cancelada. Se você editar seu script, as alterações não aparecerão até que sua próxima interação com o Claude Code acione uma atualização.137Seu script é executado após cada nova mensagem do assistente, após `/compact` terminar, quando o modo de permissão muda ou quando o modo vim alterna. As atualizações são debounced em 300ms, significando que mudanças rápidas são agrupadas e seu script é executado uma vez que as coisas se estabilizam. Se uma nova atualização for acionada enquanto seu script ainda está em execução, a execução em andamento é cancelada. Se você editar seu script, as alterações não aparecerão até que sua próxima interação com o Claude Code acione uma atualização.

138 138

139Estes gatilhos podem ficar silenciosos quando a sessão principal está ociosa, por exemplo enquanto um coordenador aguarda subagentes em segundo plano. Para manter segmentos baseados em tempo ou de origem externa atualizados durante períodos ociosos, defina [`refreshInterval`](#manually-configure-a-status-line) para também executar novamente o comando em um temporizador fixo.139Estes gatilhos podem ficar silenciosos quando a sessão principal está ociosa, por exemplo enquanto um coordenador aguarda subagentes em segundo plano. Para manter segmentos baseados em tempo ou de origem externa atualizados durante períodos ociosos, defina [`refreshInterval`](#manually-configure-a-status-line) para também executar novamente o comando em um temporizador fixo.

140 140

164| `context_window.total_input_tokens`, `context_window.total_output_tokens` | Contagens de tokens cumulativas em toda a sessão |164| `context_window.total_input_tokens`, `context_window.total_output_tokens` | Contagens de tokens atualmente na janela de contexto, da resposta de API mais recente. A entrada inclui leituras e escritas de cache. Antes da v2.1.132, estas eram totais cumulativos de sessão |

165| `context_window.context_window_size` | Tamanho máximo da janela de contexto em tokens. 200000 por padrão, ou 1000000 para modelos com contexto estendido. |165| `context_window.context_window_size` | Tamanho máximo da janela de contexto em tokens. 200000 por padrão, ou 1000000 para modelos com contexto estendido. |

215 "total_lines_removed": 23215 "total_lines_removed": 23

216 },216 },

217 "context_window": {217 "context_window": {

218 "total_input_tokens": 15234,218 "total_input_tokens": 15500,

219 "total_output_tokens": 4521,219 "total_output_tokens": 1200,

220 "context_window_size": 200000,220 "context_window_size": 200000,

221 "used_percentage": 8,221 "used_percentage": 8,

222 "remaining_percentage": 92,222 "remaining_percentage": 92,

272 272

273 **Campos que podem ser `null`**:273 **Campos que podem ser `null`**:

274 274

275 * `context_window.current_usage`: `null` antes da primeira chamada de API em uma sessão275 * `context_window.current_usage`: `null` antes da primeira chamada de API em uma sessão, e novamente após `/compact` até que a próxima chamada de API a repopule

276 * `context_window.used_percentage`, `context_window.remaining_percentage`: podem ser `null` no início da sessão276 * `context_window.used_percentage`, `context_window.remaining_percentage`: podem ser `null` no início da sessão

277 277

278 Trate campos ausentes com acesso condicional e valores nulos com padrões de fallback em seus scripts.278 Trate campos ausentes com acesso condicional e valores nulos com padrões de fallback em seus scripts.

280 280

281### Campos de janela de contexto281### Campos de janela de contexto

282 282

283O objeto `context_window` fornece duas maneiras de rastrear o uso de contexto:283O objeto `context_window` descreve a janela de contexto em tempo real da resposta de API mais recente. A partir da v2.1.132, `total_input_tokens` e `total_output_tokens` refletem o uso de contexto atual, não totais cumulativos de sessão.

284 284

285* **Totais cumulativos** (`total_input_tokens`, `total_output_tokens`): soma de todos os tokens em toda a sessão, útil para rastrear o consumo total285* **Totais combinados** (`total_input_tokens`, `total_output_tokens`): tokens atualmente na janela de contexto. `total_input_tokens` é a soma de `input_tokens`, `cache_creation_input_tokens` e `cache_read_input_tokens`; `total_output_tokens` são os tokens de saída da resposta mais recente. Ambos são `0` antes da primeira resposta de API.

286* **Uso atual** (`current_usage`): contagens de tokens da chamada de API mais recente, use isto para porcentagem de contexto precisa, pois reflete o estado real do contexto286* **Uso por componente** (`current_usage`): as mesmas contagens de tokens divididas por categoria. Use isto quando você precisar de acertos de cache separados da entrada fresca.

287 287

288O objeto `current_usage` contém:288O objeto `current_usage` contém:

289 289

296 296

297Se você calcular a porcentagem de contexto manualmente a partir de `current_usage`, use a mesma fórmula apenas de entrada para corresponder a `used_percentage`.297Se você calcular a porcentagem de contexto manualmente a partir de `current_usage`, use a mesma fórmula apenas de entrada para corresponder a `used_percentage`.

298 298

299O objeto `current_usage` é `null` antes da primeira chamada de API em uma sessão.299O objeto `current_usage` é `null` antes da primeira chamada de API em uma sessão, e novamente imediatamente após `/compact` até que a próxima chamada de API a repopule.

300 300

301## Exemplos301## Exemplos

302 302

1011 1011

1012**Porcentagem de contexto mostra valores inesperados**1012**Porcentagem de contexto mostra valores inesperados**

1013 1013

1014* Use `used_percentage` para estado de contexto preciso em vez de totais cumulativos1014* Use `used_percentage` para o estado de contexto mais simples e preciso

1015* `total_input_tokens` e `total_output_tokens` são cumulativos em toda a sessão e podem exceder o tamanho da janela de contexto

1016* A porcentagem de contexto pode diferir da saída `/context` devido a quando cada uma é calculada1015* A porcentagem de contexto pode diferir da saída `/context` devido a quando cada uma é calculada

1017 1016

1018**Links OSC 8 não clicáveis**1017**Links OSC 8 não clicáveis**

terminal-config.md +3 −3

Details

24Na maioria dos terminais você também pode pressionar Shift+Enter, mas o suporte varia por emulador de terminal:24Na maioria dos terminais você também pode pressionar Shift+Enter, mas o suporte varia por emulador de terminal:

25 25

26| Terminal | Shift+Enter para quebra de linha |26| Terminal | Shift+Enter para quebra de linha |

~~27| :----------------------------------------------------------------------------- | :--------------------------------------------- |~~27| :---------------------------------------------------------------------- | :--------------------------------------------- |

~~28| Ghostty, Kitty, iTerm2, WezTerm, Warp, Apple Terminal | Funciona sem configuração |~~28| Ghostty, Kitty, iTerm2, WezTerm, Warp, Apple Terminal, Windows Terminal | Funciona sem configuração |

29| VS Code, Cursor, Windsurf, Alacritty, Zed | Execute `/terminal-setup` uma vez |29| VS Code, Cursor, Windsurf, Alacritty, Zed | Execute `/terminal-setup` uma vez |

31 31

32Para VS Code, Cursor, Windsurf, Alacritty e Zed, `/terminal-setup` escreve Shift+Enter e outros atalhos de teclado no arquivo de configuração do terminal. Em VS Code, Cursor e Windsurf, também define `terminal.integrated.mouseWheelScrollSensitivity` nas configurações do editor para rolagem mais suave no [modo de tela cheia](/pt/fullscreen). As vinculações e configurações existentes são mantidas no lugar; se você vir uma mensagem como `VSCode terminal Shift+Enter key binding already configured`, nenhuma alteração foi feita. Execute `/terminal-setup` diretamente no terminal do host em vez de dentro do tmux ou screen, pois ele precisa escrever na configuração do terminal do host.32Para VS Code, Cursor, Windsurf, Alacritty e Zed, `/terminal-setup` escreve Shift+Enter e outros atalhos de teclado no arquivo de configuração do terminal. Em VS Code, Cursor e Windsurf, também define `terminal.integrated.mouseWheelScrollSensitivity` nas configurações do editor para rolagem mais suave no [modo de tela cheia](/pt/fullscreen). As vinculações e configurações existentes são mantidas no lugar; se você vir uma mensagem como `VSCode terminal Shift+Enter key binding already configured`, nenhuma alteração foi feita. Execute `/terminal-setup` diretamente no terminal do host em vez de dentro do tmux ou screen, pois ele precisa escrever na configuração do terminal do host.

33 33

Documentation 2026-05-05 23:00 UTC to 2026-05-07 22:59 UTC