31| Variável | Descrição |31| Variável | Descrição |
32| :- | :- |32| :- | :- |
33| `CLAUDE_CODE_SESSION_ACCESS_TOKEN` | O JWT da sessão, prefixado com `sk-ant-cc-`. Sua reivindicação `act` identifica o criador da sessão, com o email do criador quando a superfície criadora o registrou. O valor é o token no momento do spawn; atualizações chegam pela stdin do filho, então um wrapper vê apenas o valor inicial. Consulte [Verify session identity](/docs/pt/self-hosted-environments-identity). |33| `CLAUDE_CODE_SESSION_ACCESS_TOKEN` | O JWT da sessão, prefixado com `sk-ant-cc-`. Sua reivindicação `act` identifica o criador da sessão, com o email do criador quando a superfície criadora o registrou. O valor é o token no momento do spawn; atualizações chegam pela stdin do filho, então um wrapper vê apenas o valor inicial. Consulte [Verify session identity](/docs/pt/self-hosted-environments-identity). |
34| `CCR_SESSION_ACCOUNT_EMAIL` | O email do criador da sessão, pré-extraído pelo runner da reivindicação `act.email` do token sem verificação de assinatura. Adequado para rotulagem, como trailers de commit. Quando o email controla a emissão de credenciais, verifique o token e leia a reivindicação dele em vez disso; consulte [Provision credentials scoped to the session creator](#provision-credentials-scoped-to-the-session-creator). Não definido quando o token não carrega email do criador. Trate como informação de identificação pessoal. |34| `CCR_SESSION_ACCOUNT_EMAIL` | O email do criador da sessão, pré-extraído pelo runner da reivindicação `act.email` do token sem verificação de assinatura. Adequado para rotulagem, como trailers de commit. Quando o email controla a emissão de credenciais, verifique o token e leia a reivindicação dele em vez disso. Consulte [Provision credentials scoped to the session creator](#provision-credentials-scoped-to-the-session-creator). Não definido quando o token não carrega email do criador, por exemplo em sessões que a identidade de serviço da sua organização cria. Trate como informação de identificação pessoal. |
35| `CLAUDE_RUNNER_CLIENT_PLATFORM` | A superfície do cliente que criou a sessão, como `web_claude_ai`, `desktop_app`, `ios`, `claude_code_cli` ou `scheduled_trigger`. Anthropic registra o valor uma vez na criação da sessão, então o wrapper e cada hook de ciclo de vida veem o mesmo valor. Use-o apenas para análise de adoção e rotulagem, não como sinal de autorização. Não definido quando a sessão não tem superfície registrada ou reconhecida, então referencie-o como `${CLAUDE_RUNNER_CLIENT_PLATFORM:-}` sob `set -u`. Requer Claude Code v2.1.229 ou posterior. |35| `CLAUDE_RUNNER_CLIENT_PLATFORM` | A superfície do cliente que criou a sessão, como `web_claude_ai`, `desktop_app`, `ios`, `claude_code_cli` ou `scheduled_trigger`. Anthropic registra o valor uma vez na criação da sessão, então o wrapper e cada hook de ciclo de vida veem o mesmo valor. Use-o apenas para análise de adoção e rotulagem, não como sinal de autorização. Não definido quando a sessão não tem superfície registrada ou reconhecida. Requer Claude Code v2.1.229 ou posterior. |
36| `CLAUDE_RUNNER_CLAUDE_BIN` | Caminho absoluto para o binário Claude Code próprio do runner. Termine seu wrapper com `exec "$CLAUDE_RUNNER_CLAUDE_BIN" "$@"` para passar o controle para o binário fixado sem codificar um caminho de instalação. |36| `CLAUDE_RUNNER_CLAUDE_BIN` | Caminho absoluto para o binário Claude Code próprio do runner. Termine seu wrapper com `exec "$CLAUDE_RUNNER_CLAUDE_BIN" "$@"` para passar o controle para o binário fixado sem codificar um caminho de instalação. |
37| `CLAUDE_CODE_REMOTE_SESSION_ID` | ID da sessão na forma marcada `cse_...`. Esta é a mesma sessão que os [lifecycle hooks](#lifecycle-hooks) veem como `CLAUDE_RUNNER_SESSION_ID` na forma `session_...`; as variáveis UUID correspondem em ambos, e substituir o prefixo `cse_` por `session_` produz o ID mostrado na URL da sessão. |37| `CLAUDE_CODE_REMOTE_SESSION_ID` | ID da sessão na forma marcada `cse_...`. Esta é a mesma sessão que os [lifecycle hooks](#lifecycle-hooks) veem como `CLAUDE_RUNNER_SESSION_ID` na forma `session_...`; as variáveis UUID correspondem em ambos, e substituir o prefixo `cse_` por `session_` produz o ID mostrado na URL da sessão. |
38| `CLAUDE_CODE_REMOTE_SESSION_UUID` | O mesmo ID da sessão na forma UUID canônica, para sistemas que usam UUIDs como chave. |38| `CLAUDE_CODE_REMOTE_SESSION_UUID` | O mesmo ID da sessão na forma UUID canônica, para sistemas que usam UUIDs como chave. |
39| `CLAUDE_CODE_REMOTE_SLACK_THREAD_URL` | Para uma sessão do [Claude Tag](https://claude.com/docs/claude-tag/overview) que pertence a uma thread do Slack, o link para essa thread. Não definido para outras sessões, e pode não estar definido também para uma sessão de thread. |
40| `CLAUDE_CODE_REMOTE_SLACK_THREAD_TS` | Para uma sessão do Claude Tag que pertence a uma thread do Slack, o timestamp do Slack dessa thread, como `1700000000.000100`. Pode não estar definido, e pode estar definido quando `CLAUDE_CODE_REMOTE_SLACK_THREAD_URL` não está, então verifique cada variável separadamente. |
39| `CLAUDE_SESSION_INGRESS_TOKEN_FILE` | Caminho absoluto para um arquivo por sessão contendo o JWT da sessão atual, mantido atualizado em atualizações de token. Subprocessos shell o leem para seu cabeçalho `Authorization` ao baixar anexos que o usuário adicionou à sessão. `exec` preserva a variável automaticamente; um wrapper que reconstrói o ambiente do filho deve levar a variável, ou downloads de anexos param silenciosamente de funcionar. |41| `CLAUDE_SESSION_INGRESS_TOKEN_FILE` | Caminho absoluto para um arquivo por sessão contendo o JWT da sessão atual, mantido atualizado em atualizações de token. Subprocessos shell o leem para seu cabeçalho `Authorization` ao baixar anexos que o usuário adicionou à sessão. `exec` preserva a variável automaticamente; um wrapper que reconstrói o ambiente do filho deve levar a variável, ou downloads de anexos param silenciosamente de funcionar. |
40| `CLAUDE_CONFIG_DIR` | Diretório de configuração Claude por sessão, escrito no início da sessão a partir do snapshot da configuração do host do runner que o runner captura na inicialização; consulte [Permissions and tool approval](#permissions-and-tool-approval). Escritas aqui são isoladas para esta sessão. O diretório fica sob `<base-dir>/_sessions/` após o término da sessão, a menos que você inicie o runner com [`--remove-session-state`](/docs/pt/self-hosted-environments-reference#runner-cli-flags); consulte [Reuse a pre-warmed checkout](/docs/pt/self-hosted-environments-deploy#reuse-a-pre-warmed-checkout). |42| `CLAUDE_CONFIG_DIR` | Diretório de configuração Claude por sessão, escrito no início da sessão a partir do snapshot da configuração do host do runner que o runner captura na inicialização; consulte [Permissions and tool approval](#permissions-and-tool-approval). Escritas aqui são isoladas para esta sessão. O diretório fica sob `<base-dir>/_sessions/` após o término da sessão, a menos que você inicie o runner com [`--remove-session-state`](/docs/pt/self-hosted-environments-reference#runner-cli-flags); consulte [Reuse a pre-warmed checkout](/docs/pt/self-hosted-environments-deploy#reuse-a-pre-warmed-checkout). |
41| `ANTHROPIC_BASE_URL` | A URL base da API que o filho usará, entregue pelo plano de controle por sessão e normalmente `https://api.anthropic.com`. Não a sobrescreva: a credencial de inferência da sessão é um token OAuth emitido pela Anthropic que outros provedores não aceitam. |43| `ANTHROPIC_BASE_URL` | A URL base da API que o filho usará, entregue pelo plano de controle por sessão e normalmente `https://api.anthropic.com`. Não a sobrescreva: a credencial de inferência da sessão é um token OAuth emitido pela Anthropic que outros provedores não aceitam. |
43 45
44O wrapper também herda o resto do ambiente gerenciado do filho, incluindo quaisquer variáveis de ambiente fornecidas pelo servidor. `exec` propaga tudo automaticamente; se seu wrapper gera o filho de outra forma, encaminhe o ambiente completo.46O wrapper também herda o resto do ambiente gerenciado do filho, incluindo quaisquer variáveis de ambiente fornecidas pelo servidor. `exec` propaga tudo automaticamente; se seu wrapper gera o filho de outra forma, encaminhe o ambiente completo.
45 47
48`CLAUDE_CODE_REMOTE_SLACK_THREAD_URL` e `CLAUDE_CODE_REMOTE_SLACK_THREAD_TS` chegam ao seu wrapper ou [hook `command`](#command). Elas também chegam ao que a sessão executa, como comandos shell, hooks do git e hooks do Claude Code. Os hooks `checkout`, `post-session` e `spawn-runner` não as recebem.
49
50<h3 id="give-a-default-to-variables-that-can-be-unset">
51 Give a default to variables that can be unset
52</h3>
53
54`CCR_SESSION_ACCOUNT_EMAIL`, `CLAUDE_RUNNER_CLIENT_PLATFORM`, `CLAUDE_CODE_REMOTE_SLACK_THREAD_URL` e `CLAUDE_CODE_REMOTE_SLACK_THREAD_TS` podem, cada uma, não estar definidas. Se seu script usa `set -u`, o Bash para com `unbound variable` ao expandir uma que não está definida, então expanda-as com um valor padrão, como `${CCR_SESSION_ACCOUNT_EMAIL:-}`.
55
56Onde quer que um shell expanda o link da thread do Slack, tome estas precauções:
57
58* **Coloque-o entre aspas**: o link pode conter caracteres que um shell interpreta, como `?` e `&`, então coloque a variável entre aspas, como em `"${CLAUDE_CODE_REMOTE_SLACK_THREAD_URL:-}"`.
59* **Mantenha seu valor fora de strings de `eval` e `sh -c`**: não substitua seu valor em uma string que `eval` ou `sh -c` executa, mesmo entre aspas. Em vez disso, faça essa string referenciar a variável.
60
46<h3 id="keep-stdin-and-file-descriptor-3-attached">61<h3 id="keep-stdin-and-file-descriptor-3-attached">
47 Keep stdin and file descriptor 3 attached62 Keep stdin and file descriptor 3 attached
48</h3>63</h3>
49 64
50A stdin do filho é o canal de controle do runner. Rotações de token e sinais de fim de sessão chegam nela. O runner também abre um pipe no descritor de arquivo 3 e lê sinais de atividade do filho dele para conduzir timeouts de inatividade e inicialização. Um simples `exec "$CLAUDE_RUNNER_CLAUDE_BIN" "$@"` preserva ambos automaticamente.65A stdin do filho é o canal de controle do runner. Rotações de token e sinais de fim de sessão chegam nela. O runner também abre um pipe no descritor de arquivo 3 e lê sinais de atividade do filho dele para conduzir timeouts de inatividade e inicialização. Um simples `exec "$CLAUDE_RUNNER_CLAUDE_BIN" "$@"` preserva ambos automaticamente.
51 66
52Se seu wrapper coloca o filho em background com um simples `&`, ele corta a stdin do filho: a sessão parece saudável até a vida útil do token OAuth inicial de aproximadamente 30 minutos expirar, então cada chamada de API falha com `401 authentication_error`. Se seu wrapper deve colocar o filho em background, por exemplo para manter uma trap de teardown viva, salve stdin no descritor de arquivo 4 ou superior e re-anexe-a explicitamente:67Se seu wrapper coloca o filho em background com um simples `&`, ele corta a stdin do filho. A sessão parece saudável até a vida útil do token OAuth inicial de aproximadamente 30 minutos expirar, e então cada chamada de API que usa o token falha com `401 authentication_error`. Se seu wrapper deve colocar o filho em background, por exemplo para manter uma trap de teardown viva, salve stdin no descritor de arquivo 4 ou superior e re-anexe-a explicitamente:
53 68
54```bash theme={null}69```bash theme={null}
55exec 4<&070exec 4<&0
59wait "$CHILD"74wait "$CHILD"
60```75```
61 76
62Não feche ou reutilize o descritor de arquivo 3 no wrapper. Redirecionar stdout e stderr do filho é aceitável.77Você pode redirecionar o stdout do filho. Mantenha o descritor de arquivo 3 e o stderr anexados ao runner:
78
79* **Descritor de arquivo 3**: transporta os sinais de atividade do filho para o runner. Não o feche nem o reutilize no wrapper.
80* **stderr**: quando o wrapper ou o filho sai com código diferente de zero, o runner publica as últimas linhas do stderr na sessão e as imprime em seu próprio log. O usuário da sessão vê essas linhas, então não imprima segredos no stderr e remova `set -x` antes de implantar o wrapper. Se você redirecionar o stderr, as sessões ainda são executadas, mas o runner relata uma falha apenas com o código de saída.
63 81
64<h3 id="pass-the-system-prompt-flags-through">82<h3 id="pass-the-system-prompt-flags-through">
65 Pass the system prompt flags through83 Pass the system prompt flags through
108 checkout126 checkout
109</h3>127</h3>
110 128
111Executado uma vez por repositório, no lugar do clone e fetch integrados do runner. Use o hook para clonar de um espelho de leitura, semear uma árvore de trabalho de um arquivo ou aplicar autenticação git por sessão. O runner define estas variáveis, e pode definir outras variáveis `CLAUDE_RUNNER_` que a tabela não lista:129Executado uma vez por repositório, no lugar do clone e fetch integrados do runner. Use o hook para clonar de um espelho de leitura que você acessa por HTTPS ou SSH, semear uma árvore de trabalho a partir de um arquivo ou aplicar autenticação git por sessão. O runner define estas variáveis, e pode definir outras variáveis `CLAUDE_RUNNER_` que a tabela não lista:
112 130
113| Variável | Descrição |131| Variável | Descrição |
114| :- | :- |132| :- | :- |
115| `CLAUDE_RUNNER_REPO_URL` | URL do repositório para clonar, após qualquer `--git-host-rewrite` e `--git-ssh-rewrite` terem sido aplicados |133| `CLAUDE_RUNNER_REPO_URL` | URL do repositório para clonar, após qualquer `--git-host-rewrite` e `--git-ssh-rewrite` terem sido aplicados |
116| `CLAUDE_RUNNER_REPO_REF` | Revisão para fazer checkout: branch, tag ou commit SHA conforme a sessão o solicitou. Vazio significa o branch padrão do repositório. |134| `CLAUDE_RUNNER_REPO_REF` | Revisão para fazer checkout, conforme a sessão a solicitou: um branch, tag, commit SHA ou nome de referência completo como `refs/pull/<number>/head`. Vazio significa o branch padrão do repositório. |
117| `CLAUDE_RUNNER_CHECKOUT_PATH` | Caminho absoluto onde a árvore de trabalho deve ser deixada |135| `CLAUDE_RUNNER_CHECKOUT_PATH` | Caminho absoluto onde a árvore de trabalho deve ser deixada |
118| `CLAUDE_RUNNER_SESSION_ID` | ID da sessão na forma marcada `session_...`, para logging e correlação |136| `CLAUDE_RUNNER_SESSION_ID` | ID da sessão na forma marcada `session_...`, para logging e correlação |
119| `CLAUDE_RUNNER_SESSION_UUID` | O mesmo ID da sessão na forma UUID canônica |137| `CLAUDE_RUNNER_SESSION_UUID` | O mesmo ID da sessão na forma UUID canônica |
120| `CLAUDE_RUNNER_API_BASE_URL` | URL base da API Anthropic para chamadas com escopo de sessão |138| `CLAUDE_RUNNER_API_BASE_URL` | URL base da API Anthropic para chamadas com escopo de sessão |
121| `CLAUDE_RUNNER_CLIENT_PLATFORM` | A superfície do cliente que criou a sessão, como `web_claude_ai`, `desktop_app` ou `ios`. Não definido quando a sessão não tem superfície registrada ou reconhecida. |139| `CLAUDE_RUNNER_CLIENT_PLATFORM` | A superfície do cliente que criou a sessão, como `web_claude_ai`, `desktop_app` ou `ios`. Não definido quando a sessão não tem superfície registrada ou reconhecida, então referencie-a como `${CLAUDE_RUNNER_CLIENT_PLATFORM:-}` sob `set -u`. Requer Claude Code v2.1.229 ou posterior. |
122| `CLAUDE_CODE_SESSION_ACCESS_TOKEN` | O token de acesso da sessão, para chamadas de API com escopo de sessão |140| `CLAUDE_CODE_SESSION_ACCESS_TOKEN` | O token de acesso da sessão, para chamadas de API com escopo de sessão |
123| `GIT_CONFIG_COUNT`, `GIT_CONFIG_KEY_n`, `GIT_CONFIG_VALUE_n` | Configurações git que o runner fixa para o git que seu hook executa. [Configuração do Git dentro de lifecycle hooks](#git-configuration-inside-lifecycle-hooks) as descreve. Requer Claude Code v2.1.280 ou posterior. |141| `GIT_CONFIG_COUNT`, `GIT_CONFIG_KEY_n`, `GIT_CONFIG_VALUE_n` | Configurações git que o runner fixa para o git que seu hook executa. [Configuração do Git dentro de lifecycle hooks](#git-configuration-inside-lifecycle-hooks) as descreve. Requer Claude Code v2.1.280 ou posterior. |
124 142
125O script deve deixar uma árvore de trabalho em `CLAUDE_RUNNER_CHECKOUT_PATH` com checkout na revisão solicitada. HEAD desanexado é aceitável; o runner cria o branch de trabalho da sessão em cima. O runner verifica se o caminho contém um `.git` depois; se seu hook materializa uma fonte não-git como Perforce ou um tarball desempacotado, defina `CLAUDE_RUNNER_SKIP_GIT_VERIFY=1` no ambiente do runner para pular essa verificação. Fluxos baseados em Git como criação de branch de trabalho e push de resultados requerem um checkout git, então exporte resultados de árvores não-git com um hook [`post-session`](#post-session).143O script deve deixar uma árvore de trabalho em `CLAUDE_RUNNER_CHECKOUT_PATH` com checkout na revisão solicitada. Um HEAD desanexado funciona, porque o runner cria o branch de trabalho da sessão em cima.
126 144
127O runner não passa uma credencial git para o hook. Em vez disso, emita uma credencial de clone por sessão a partir da identidade da sessão: verifique `CLAUDE_CODE_SESSION_ACCESS_TOKEN` com uma biblioteca JWT padrão contra o endpoint JWKS sob `CLAUDE_RUNNER_API_BASE_URL`, conforme descrito em [Verify the token from your service](/docs/pt/self-hosted-environments-identity#verify-the-token-from-your-service), então faça seu serviço de credencial emitir uma credencial de clone de curta duração para a identidade na reivindicação `act` do token. `CLAUDE_RUNNER_CLAUDE_BIN` não está definido no ambiente do checkout-hook, então o subcomando `decode-token` não está disponível aqui. Voltar para qualquer autenticação git que o host já tenha, como um agente SSH, credential helper ou `.netrc`, também é uma opção.145Depois que seu hook retorna, o runner verifica se `CLAUDE_RUNNER_CHECKOUT_PATH` contém um `.git`. Se seu hook materializa uma fonte não-git como Perforce ou um tarball desempacotado, defina `CLAUDE_RUNNER_SKIP_GIT_VERIFY=1` no ambiente do runner para pular essa verificação. Fluxos baseados em Git como criação de branch de trabalho e push de resultados requerem um checkout git, então exporte resultados de árvores não-git com um [hook `post-session`](#post-session).
128 146
129Quando o hook sai com código diferente de zero, ou sai com 0 sem deixar um checkout utilizável atrás, o que o runner faz depende do repositório:147<h4 id="get-git-credentials-in-the-hook">
148 Obter credenciais git no hook
149</h4>
130 150
131* **Um repositório para o qual a sessão faz push de resultados**: o runner falha a sessão, e em uma saída diferente de zero exibe a cauda do stderr do script para o usuário.151O runner não passa uma credencial git para o hook. O subcomando `decode-token` também não está disponível aqui, porque `CLAUDE_RUNNER_CLAUDE_BIN` não está definido no ambiente do checkout-hook. Em vez disso, emita uma credencial de clone por sessão a partir da identidade da sessão, ou recorra à própria autenticação git do host:
132* **Um repositório que a sessão apenas lê**, como um repositório adicionado a uma sessão em execução: o runner registra uma linha `[runner:warn]` com o detalhe da falha, publica um passo `Skipped` para a sessão, remove o que o hook deixou no caminho de checkout e continua com os repositórios restantes. Quando o runner não consegue remover o caminho imediatamente, ele tenta novamente a remoção no fim da sessão. Se pular deixa a sessão sem nenhum repositório, o runner falha a sessão mesmo assim.
133 152
134Antes da v2.1.228, o runner falhava a sessão em uma falha de hook para qualquer repositório, então um repositório somente leitura que o hook não conseguia servir falhava a sessão novamente em cada novo runner fresco em que a sessão retomava.153* **Credencial de clone por sessão**: verifique `CLAUDE_CODE_SESSION_ACCESS_TOKEN` com uma biblioteca JWT padrão contra o endpoint JWKS sob `CLAUDE_RUNNER_API_BASE_URL`, conforme descrito em [Verify the token from your service](/docs/pt/self-hosted-environments-identity#verify-the-token-from-your-service). Em seguida, faça seu serviço de credencial emitir uma credencial de clone de curta duração para a identidade na reivindicação `act` do token. Associe essa credencial a `act.sub`, e não exija `act.email`.
154* **Autenticação git do host**: use qualquer autenticação git que o host já tenha, como um agente SSH, credential helper ou `.netrc`.
135 155
136O runner remove o caminho de checkout após a sessão terminar.156<h4 id="when-the-hook-fails">
157 Quando o hook falha
158</h4>
159
160O hook falha quando sai com código diferente de zero, ou sai com 0 sem deixar um checkout utilizável para trás:
161
162* **Um repositório para o qual a sessão faz push de resultados**: o runner falha a sessão, e em uma saída diferente de zero exibe a cauda do stderr do script para o usuário.
163* **Um repositório que a sessão apenas lê**, como um repositório adicionado a uma sessão em execução: o runner registra uma linha `[runner:warn]` com o detalhe da falha, publica um passo `Skipped` para a sessão, remove o que o hook deixou no caminho de checkout e continua com os repositórios restantes. Se pular deixa a sessão sem nenhum repositório, o runner falha a sessão mesmo assim.
164
165Quando o hook é bem-sucedido, o runner remove o caminho de checkout após a sessão terminar.
137 166
138<h3 id="post-session">167<h3 id="post-session">
139 post-session168 post-session
151| `CLAUDE_RUNNER_WORKSPACE_PATHS` | Caminhos absolutos separados por dois-pontos das árvores de trabalho da sessão. Vazio para sessões sem repositório. |180| `CLAUDE_RUNNER_WORKSPACE_PATHS` | Caminhos absolutos separados por dois-pontos das árvores de trabalho da sessão. Vazio para sessões sem repositório. |
152| `CLAUDE_RUNNER_DEBUG_LOG_PATH` | Caminho para o log de debug da sessão, ainda em disco enquanto o hook é executado |181| `CLAUDE_RUNNER_DEBUG_LOG_PATH` | Caminho para o log de debug da sessão, ainda em disco enquanto o hook é executado |
153| `CLAUDE_RUNNER_API_BASE_URL` | URL base da API Anthropic para chamadas com escopo de sessão |182| `CLAUDE_RUNNER_API_BASE_URL` | URL base da API Anthropic para chamadas com escopo de sessão |
154| `CLAUDE_RUNNER_CLIENT_PLATFORM` | A superfície do cliente que criou a sessão, como `web_claude_ai`, `desktop_app` ou `ios`. Não definido quando a sessão não tem superfície registrada ou reconhecida. Requer Claude Code v2.1.229 ou posterior. |183| `CLAUDE_RUNNER_CLIENT_PLATFORM` | A superfície do cliente que criou a sessão, como `web_claude_ai`, `desktop_app` ou `ios`. Não definido quando a sessão não tem superfície registrada ou reconhecida, então referencie-a como `${CLAUDE_RUNNER_CLIENT_PLATFORM:-}` sob `set -u`. Requer Claude Code v2.1.229 ou posterior. |
155| `CLAUDE_CODE_SESSION_ACCESS_TOKEN` | O token de acesso da sessão, para chamadas de API com escopo de sessão |184| `CLAUDE_CODE_SESSION_ACCESS_TOKEN` | O token de acesso da sessão, para chamadas de API com escopo de sessão |
156| `GIT_CONFIG_COUNT`, `GIT_CONFIG_KEY_n`, `GIT_CONFIG_VALUE_n` | Configurações git que o runner fixa para o git que seu hook executa. [Configuração do Git dentro de lifecycle hooks](#git-configuration-inside-lifecycle-hooks) as descreve. Requer Claude Code v2.1.280 ou posterior. |185| `GIT_CONFIG_COUNT`, `GIT_CONFIG_KEY_n`, `GIT_CONFIG_VALUE_n` | Configurações git que o runner fixa para o git que seu hook executa. [Configuração do Git dentro de lifecycle hooks](#git-configuration-inside-lifecycle-hooks) as descreve. Requer Claude Code v2.1.280 ou posterior. |
157 186
158`CLAUDE_RUNNER_EXIT_REASON` toma um de quatro valores:187`CLAUDE_RUNNER_EXIT_REASON` toma um de quatro valores:
159 188
160* `completed`: a sessão terminou de forma limpa. O processo Claude Code saiu normalmente, ou a sessão foi arquivada ou deletada enquanto ainda estava em execução.189* `completed`: a sessão terminou de forma limpa. O processo Claude Code saiu normalmente, ou saiu por conta própria depois que a sessão foi arquivada ou deletada.
161* `failed`: o processo Claude Code travou, ou a configuração falhou após ele ter iniciado.190* `failed`: o processo Claude Code travou, ou a configuração falhou após ele ter iniciado.
162* `interrupted`: o runner parou a sessão. Ele liberou a sessão para liberar o slot, a sessão expirou na inicialização, o servidor moveu a sessão para fora deste runner, o runner estava drenando, ou a sessão ultrapassou seu limite [`--kill-session-after-min`](/docs/pt/self-hosted-environments-reference#runner-cli-flags).191* `interrupted`: o runner parou a sessão, em um destes casos:
192 * O runner liberou a sessão para liberar o slot.
193 * A sessão atingiu o timeout na inicialização.
194 * O servidor moveu a sessão para fora deste runner.
195 * A verificação periódica do runner detectou um arquivamento ou exclusão antes de o processo sair.
196 * O runner estava drenando.
197 * A sessão ultrapassou seu limite [`--kill-session-after-min`](/docs/pt/self-hosted-environments-reference#runner-cli-flags).
163* `abandoned`: reservado para uma sessão que outro runner reivindicou. O hook não dispara atualmente nesse caso.198* `abandoned`: reservado para uma sessão que outro runner reivindicou. O hook não dispara atualmente nesse caso.
164 199
165Os [contadores de ciclo de vida da sessão](/docs/pt/self-hosted-environments-reference#session-lifecycle-counter-semantics) contam uma liberação, um timeout de inicialização e uma movimentação de servidor como `completed` em vez de `interrupted`, porque o runner devolveu o slot de forma limpa. Espere essa diferença se você comparar recibos de hook com os contadores.200Se você comparar recibos de hook com os [contadores de ciclo de vida da sessão](/docs/pt/self-hosted-environments-reference#session-lifecycle-counter-semantics), espere que alguns recibos `interrupted` contem como `completed` ali. Os contadores contam uma liberação, um timeout de inicialização, uma movimentação de servidor e um arquivamento ou exclusão que a verificação periódica do runner detectou primeiro como `completed`, porque o runner devolveu o slot de forma limpa.
166 201
167O status de saída do hook nunca afeta o resultado da sessão; uma falha é registrada e ignorada. O runner aguarda até `--post-session-hook-timeout-sec`, 60 segundos por padrão, em cada fim de sessão incluindo shutdown do runner. Este exemplo salva trabalho não confirmado para um branch de resgate:202O status de saída do hook nunca afeta o resultado da sessão; uma falha é registrada e ignorada. O runner aguarda até `--post-session-hook-timeout-sec`, 60 segundos por padrão, em cada fim de sessão incluindo shutdown do runner. Este exemplo salva trabalho não confirmado para um branch de resgate:
168 203
169```bash theme={null}204```bash theme={null}
170#!/usr/bin/env bash205#!/usr/bin/env bash
171set -u206set -u
207export GIT_ALLOW_PROTOCOL=${GIT_ALLOW_PROTOCOL:-https:http:ssh}
172IFS=':'208IFS=':'
173# -c overrides beat repo-local settings, blocking session-written fsmonitor,209# -c overrides beat repo-local settings, blocking session-written fsmonitor,
174# hook-path, and gpg-program config from executing code with the hook's210# hook-path, and gpg-program config from executing code with the hook's
175# privileges. -c commit.gpgsign=false also leaves these rescue commits211# privileges. -c commit.gpgsign=false also leaves these rescue commits
176# unsigned under --configure-git.212# unsigned under --configure-git.
177# Repo-local credential.helper and pushurl still apply, and on a runner213# Repo-local credential.helper and pushurl still apply, and on a runner
178# before v2.1.280 so does core.sshCommand; if the hook holds credentials214# before v2.1.280 so does core.sshCommand; see the note below the script
179# the session didn't, see the note below the script.215# before you give this push a credential.
180g() { git -c core.fsmonitor=false -c core.hooksPath=/dev/null \216g() { git -c core.fsmonitor=false -c core.hooksPath=/dev/null \
181 -c commit.gpgsign=false "$@"; }217 -c commit.gpgsign=false "$@"; }
182for ws in $CLAUDE_RUNNER_WORKSPACE_PATHS; do218for ws in $CLAUDE_RUNNER_WORKSPACE_PATHS; do
188done224done
189```225```
190 226
191O hook faz push com quaisquer credenciais git disponíveis em seu próprio ambiente no host do runner. Sob a [postura de sem-credenciais-na-imagem](/docs/pt/self-hosted-environments-deploy#configure-git), incluindo quando o clone integrado passa pelo proxy git Anthropic, não há nenhuma, então emita uma credencial de push de curta duração dentro do hook antes de fazer push: troque o token de sessão que o hook recebe em `CLAUDE_CODE_SESSION_ACCESS_TOKEN` com seu próprio serviço de token, verificando-o conforme [Verify session identity](/docs/pt/self-hosted-environments-identity) descreve. Quando o hook mantém uma credencial que a sessão não tinha, substitua `origin` por uma URL fornecida pelo operador e passe `-c credential.helper=` mais seu próprio helper. [Configuração do Git dentro de lifecycle hooks](#git-configuration-inside-lifecycle-hooks) descreve o que a configuração escrita pela sessão ainda pode afetar.227A linha `GIT_ALLOW_PROTOCOL` no script limita o git a remotos HTTPS, HTTP e SSH. Se o ambiente do runner já define uma lista `GIT_ALLOW_PROTOCOL` própria não vazia, o script mantém essa lista.
228
229O hook faz push com quaisquer credenciais git disponíveis em seu próprio ambiente no host do runner. Sob a [postura de sem-credenciais-na-imagem](/docs/pt/self-hosted-environments-deploy#configure-git), incluindo quando o clone integrado passa pelo proxy git Anthropic, não há nenhuma, então emita uma credencial de push de curta duração dentro do hook antes de fazer push: troque o token de sessão que o hook recebe em `CLAUDE_CODE_SESSION_ACCESS_TOKEN` com seu próprio serviço de token, verificando-o conforme [Verify session identity](/docs/pt/self-hosted-environments-identity) descreve.
230
231Trate qualquer credencial que seu hook fornece ao git como uma que uma sessão pode obter, e emita-a de modo que ela não possa fazer mais do que este push. O git em seu hook lê arquivos de configuração que uma sessão pode escrever, e um credential helper ou filter driver nomeado em um deles é executado com os privilégios do seu hook. Opções de configuração nesses arquivos também podem alterar para onde vai um push, qualquer que seja o remoto que você nomeie. Para as configurações git que o runner fixa em seu hook e as que ele deixa para esses arquivos, consulte [Configuração do Git dentro de lifecycle hooks](#git-configuration-inside-lifecycle-hooks).
192 232
193<h4 id="hook-timing-when-the-runner-releases-a-session">233<h4 id="hook-timing-when-the-runner-releases-a-session">
194 Hook timing when the runner releases a session234 Hook timing when the runner releases a session
264| `CLAUDE_RUNNER_ORDER_ID` | Chave de idempotência opaca, única por solicitação de spawn e segura para nomes de recursos Kubernetes. Use apenas o ID de ordem como sua chave de dedup do provisionador. |304| `CLAUDE_RUNNER_ORDER_ID` | Chave de idempotência opaca, única por solicitação de spawn e segura para nomes de recursos Kubernetes. Use apenas o ID de ordem como sua chave de dedup do provisionador. |
265| `CLAUDE_RUNNER_SESSION_ID` | A sessão para a qual esta solicitação é. Ela se repete em cada re-solicitação para a sessão, então use-a para logging e roteamento, não como chave de dedup. Vazio para solicitações de pré-aquecimento, que inicializam um runner em standby antes de qualquer sessão específica quando [`--min-idle`](/docs/pt/self-hosted-environments-reference#orchestrator-cli-flags) está definido, então não assuma que a variável está definida. |305| `CLAUDE_RUNNER_SESSION_ID` | A sessão para a qual esta solicitação é. Ela se repete em cada re-solicitação para a sessão, então use-a para logging e roteamento, não como chave de dedup. Vazio para solicitações de pré-aquecimento, que inicializam um runner em standby antes de qualquer sessão específica quando [`--min-idle`](/docs/pt/self-hosted-environments-reference#orchestrator-cli-flags) está definido, então não assuma que a variável está definida. |
266| `CLAUDE_RUNNER_SESSION_UUID` | O mesmo ID da sessão na forma UUID canônica. Vazio para solicitações de pré-aquecimento. |306| `CLAUDE_RUNNER_SESSION_UUID` | O mesmo ID da sessão na forma UUID canônica. Vazio para solicitações de pré-aquecimento. |
267| `CLAUDE_RUNNER_ATTEMPT` | Quantas solicitações de spawn esta sessão teve. `0` para solicitações de pré-aquecimento. |307| `CLAUDE_RUNNER_ATTEMPT` | Um contador por sessão para usar em logging. Não é uma contagem de novas tentativas nem uma contagem de solicitações. `0` para solicitações de pré-aquecimento, embora uma solicitação para uma sessão também possa carregar `0`. |
268| `CLAUDE_RUNNER_ORDER_SERVER_TIME` | Hora do servidor do cabeçalho HTTP `Date` da resposta de poll. Quando o hook verifica o `exp` do JWT da ordem de trabalho, compare contra este valor em vez do relógio local para tolerar skew. Vazio quando o gateway omitiu o cabeçalho. |308| `CLAUDE_RUNNER_ORDER_SERVER_TIME` | Hora do servidor do cabeçalho HTTP `Date` da resposta de poll. Quando o hook verifica o `exp` do JWT da ordem de trabalho, compare contra este valor em vez do relógio local para tolerar skew. Vazio quando o gateway omitiu o cabeçalho. |
269| `CLAUDE_RUNNER_POOL_ID` | O ID do ambiente que o novo runner deve se juntar, na forma `ccpool_...` |309| `CLAUDE_RUNNER_POOL_ID` | O ID do ambiente que o novo runner deve se juntar, na forma `ccpool_...` |
270| `CLAUDE_RUNNER_ACCOUNT_ID` | ID marcado da conta que enfileirou a sessão, para roteamento por conta, quota ou chargeback. Vazio quando indisponível, e sempre vazio para sessões do canal Claude Tag, que nenhuma conta enfileira. |310| `CLAUDE_RUNNER_ACCOUNT_ID` | ID marcado da conta que enfileirou a sessão, para roteamento por conta, quota ou chargeback. Vazio quando indisponível, e sempre vazio para sessões do canal Claude Tag, que nenhuma conta enfileira. |
271| `CLAUDE_RUNNER_ACCOUNT_EMAIL` | Email da conta que enfileirou a sessão. Vazio quando indisponível. Trate o email como informação de identificação pessoal e não o registre. |311| `CLAUDE_RUNNER_ACCOUNT_EMAIL` | Email da conta que enfileirou a sessão. Vazio quando indisponível. Trate o email como informação de identificação pessoal e não o registre. |
272| `CLAUDE_RUNNER_PRIMARY_REPO_URL` | URL da primeira fonte git da sessão, para roteamento para um runner com esse repositório pré-aquecido. Vazio quando a sessão não tem fontes git. |312| `CLAUDE_RUNNER_PRIMARY_REPO_URL` | URL da primeira fonte git da sessão, para roteamento para um runner com esse repositório pré-aquecido. Vazio quando a sessão não tem fontes git. |
273| `CLAUDE_RUNNER_PRIMARY_REPO_REVISION` | Revisão da primeira fonte git da sessão: branch, SHA ou tag. Vazio quando não especificado. |313| `CLAUDE_RUNNER_PRIMARY_REPO_REVISION` | Revisão da primeira fonte git da sessão: branch, SHA, tag ou nome completo da referência. Vazio quando não especificado. |
274| `CLAUDE_RUNNER_REPO_SOURCES` | Array JSON de `{url, revision}` para todas as fontes git da sessão, para hooks que roteiam em um repositório secundário. Vazio quando não há fontes. |314| `CLAUDE_RUNNER_REPO_SOURCES` | Array JSON de `{url, revision}` para todas as fontes git da sessão, para hooks que roteiam em um repositório secundário. Vazio quando não há fontes. |
275| `CLAUDE_RUNNER_CORRELATION_ID` | O ID de correlação fornecido na criação da sessão, ecoado de volta para que o hook possa mapear esta ordem de trabalho para a solicitação que criou a sessão. Vazio quando a sessão não tem nenhum. |315| `CLAUDE_RUNNER_CORRELATION_ID` | O ID de correlação fornecido na criação da sessão, ecoado de volta para que o hook possa mapear esta ordem de trabalho para a solicitação que criou a sessão. Vazio quando a sessão não tem nenhum. |
276| `CLAUDE_RUNNER_CLIENT_PLATFORM` | A superfície do cliente que criou a sessão, como `web_claude_ai`, `desktop_app`, `ios` ou `scheduled_trigger`, para análise de adoção. Não definido quando a sessão não tem superfície registrada ou reconhecida, e para solicitações de pré-aquecimento; verifique-o com `[ -n "${CLAUDE_RUNNER_CLIENT_PLATFORM:-}" ]`, que permanece seguro sob `set -u`. |316| `CLAUDE_RUNNER_CLIENT_PLATFORM` | A superfície do cliente que criou a sessão, como `web_claude_ai`, `desktop_app`, `ios` ou `scheduled_trigger`, para análise de adoção. Não definido quando a sessão não tem superfície registrada ou reconhecida, e para solicitações de pré-aquecimento; verifique-o com `[ -n "${CLAUDE_RUNNER_CLIENT_PLATFORM:-}" ]`, que permanece seguro sob `set -u`. |
282* **Use `--capacity 1` em runners gerados**: uma ordem de trabalho vinculada a sessão registra exatamente um runner vinculado a essa sessão, então uma capacidade maior adiciona slots que nunca recebem trabalho, e o runner registra um aviso na inicialização.322* **Use `--capacity 1` em runners gerados**: uma ordem de trabalho vinculada a sessão registra exatamente um runner vinculado a essa sessão, então uma capacidade maior adiciona slots que nunca recebem trabalho, e o runner registra um aviso na inicialização.
283* **Ordens de trabalho de pré-aquecimento registram desvinculadas**: o runner em standby não está vinculado a uma sessão e reclama trabalho enfileirado como um runner de frota fixa.323* **Ordens de trabalho de pré-aquecimento registram desvinculadas**: o runner em standby não está vinculado a uma sessão e reclama trabalho enfileirado como um runner de frota fixa.
284 324
285O contrato tem quatro regras agnósticas do provisionador:325O contrato tem quatro regras, qualquer que seja a plataforma em que seu hook provisiona:
286 326
2871. **Seja idempotente em `CLAUDE_RUNNER_ORDER_ID`.** Reentrega da mesma solicitação deve gerar no máximo um runner. Derive um nome de recurso determinístico do ID de ordem e deixe sua plataforma rejeitar a duplicata. Não use `CLAUDE_RUNNER_SESSION_ID` como chave. Cada re-solicitação para uma sessão carrega o mesmo ID de sessão com um novo ID de ordem, então uma carga de trabalho nomeada ou deduplicada pelo ID de sessão é criada uma vez e nunca novamente para essa sessão.3271. **Seja idempotente em `CLAUDE_RUNNER_ORDER_ID`.** Reentrega da mesma solicitação deve gerar no máximo um runner. Derive um nome de recurso determinístico do ID de ordem e deixe sua plataforma rejeitar a duplicata. Não use `CLAUDE_RUNNER_SESSION_ID` como chave. Cada re-solicitação para uma sessão carrega o mesmo ID de sessão com um novo ID de ordem, então uma carga de trabalho nomeada ou deduplicada pelo ID de sessão é criada uma vez e nunca novamente para essa sessão.
2882. **Não tente novamente a carga de trabalho.** Um ID de ordem significa no máximo uma carga de trabalho criada. Se o runner nunca se registra, Anthropic re-solicita com um ID de ordem fresco após `--expected-spawn-seconds`.3282. **Não tente novamente a carga de trabalho.** Um ID de ordem significa no máximo uma carga de trabalho criada. Se o runner nunca se registra, Anthropic re-solicita com um ID de ordem fresco após `--expected-spawn-seconds`.
2893. **Use o contrato de código de saída.** Saída 0 significa submetido. Saída 1 significa falha retentável; a sessão recua e é re-oferecida. Saída 2 ou superior significa não-retentável; a sessão é bloqueada de gerar novamente até um [Owner](/docs/pt/cloud-environments#organization-shared-environments) selecionar **Retry** nela na aba **Activity** do ambiente. Em saída diferente de zero, a cauda do stderr do hook aparece lá como o motivo da falha, então escreva o erro acionável para stderr e nunca segredos. Para uma solicitação de pré-aquecimento não há sessão para falhar: o orquestrador registra uma saída diferente de zero localmente apenas, e o servidor re-solicita o spawn após a concessão.3293. **Use o contrato de código de saída.** Saia com o status que corresponde ao resultado:
2904. **Defina `--expected-spawn-seconds` para pelo menos seu tempo de boot p99.** Esta é a concessão no lado do servidor. Todas as réplicas do orquestrador devem usar o mesmo valor.330
331 * **Saída 0**: submetido.
332 * **Saída 1**: falha retentável. A sessão recua e é re-oferecida.
333 * **Saída 2 ou superior**: falha não-retentável. A sessão é bloqueada de gerar novamente até que um usuário envie uma nova mensagem a ela ou um [Owner](/docs/pt/cloud-environments#organization-shared-environments) selecione **Retry** nela na aba **Activity** do ambiente.
334
335 Em saída diferente de zero, a cauda do stderr do hook aparece na aba **Activity** como o motivo da falha, então escreva o erro acionável para stderr e nunca escreva segredos lá. Em um hook de shell, [mantenha falhas transitórias retentáveis](#keep-transient-failures-retryable-in-a-shell-hook).
336
337 Uma solicitação de pré-aquecimento não tem sessão para falhar: o orquestrador registra uma saída diferente de zero localmente apenas, e o servidor re-solicita o spawn após a concessão de `--expected-spawn-seconds` expirar.
3384. **Defina `--expected-spawn-seconds` para pelo menos seu tempo p99 desde a solicitação de spawn até o registro do runner.** Meça a partir do momento em que o orquestrador recebe a solicitação de spawn e inclua qualquer espera por capacidade na sua plataforma, além do tempo de boot. Este valor é a concessão no lado do servidor, e a ordem de trabalho expira com ela, então um runner cuja carga de trabalho demora mais não consegue se registrar. Todas as réplicas do orquestrador devem usar o mesmo valor.
291 339
292Tudo que o hook escreve para stdout ou stderr aparece no log do orquestrador com credenciais automaticamente redatadas. Se sessões ficarem enfileiradas, verifique o corpo `/healthz` do orquestrador para contagens de fila, então abra a aba **Activity** do seu ambiente na [página de administração **Cloud environments**](https://claude.ai/admin-settings/cloud-environments): expanda uma sessão falhada lá para seu erro de spawn e selecione **Retry** para re-solicitá-la.340Tudo que o hook escreve para stdout ou stderr aparece no log do orquestrador com credenciais automaticamente redatadas. Se sessões ficarem enfileiradas, verifique o corpo `/healthz` do orquestrador para contagens de fila, então abra a aba **Activity** do seu ambiente na [página de administração **Cloud environments**](https://claude.ai/admin-settings/cloud-environments): expanda uma sessão falhada lá para seu erro de spawn e selecione **Retry** para re-solicitá-la.
293 341
294Uma sessão que fica enfileirada sem erro de spawn na aba **Activity** pode significar que o hook está usando a chave do ID de sessão. Para confirmar, verifique se sua plataforma tem uma carga de trabalho para a primeira solicitação de spawn dessa sessão e nenhuma para as re-solicitações. Se for assim, use `CLAUDE_RUNNER_ORDER_ID` como chave da carga de trabalho.342Uma sessão que fica enfileirada sem erro de spawn na aba **Activity** pode significar que o hook está usando a chave do ID de sessão. Para confirmar, verifique se sua plataforma tem uma carga de trabalho para a primeira solicitação de spawn dessa sessão e nenhuma para as re-solicitações. Se for assim, use `CLAUDE_RUNNER_ORDER_ID` como chave da carga de trabalho.
295 343
344<h4 id="keep-transient-failures-retryable-in-a-shell-hook">
345 Mantenha falhas transitórias retentáveis em um hook de shell
346</h4>
347
348Em um hook de shell que usa `set -e`, uma falha que uma nova tentativa poderia ter resolvido pode bloquear a sessão. O hook para no comando que falhou e sai com o próprio status desse comando, e o orquestrador aplica o contrato de código de saída a esse status. Muitas falhas retornam um status de 2 ou superior, como `127` quando um comando não está instalado e `22` de `curl --fail` em um erro HTTP, então elas bloqueiam a sessão na sua primeira falha.
349
350Uma sessão que o hook já bloqueou permanece bloqueada até que um usuário envie uma nova mensagem a ela ou um [Owner](/docs/pt/cloud-environments#organization-shared-environments) selecione **Retry** nela na aba **Activity** do ambiente.
351
352Para transformar essa falha em saída 1, coloque estas linhas diretamente abaixo da linha `#!` do hook, acima de qualquer coisa que possa falhar:
353
354```bash theme={null}
355set -e
356PERMANENT=; permanent() { printf '%s\n' "$*" >&2; PERMANENT=1; exit 2; }
357trap 'rc=$?; [ "$rc" -eq 0 ] || [ -n "${PERMANENT:-}" ] || exit 1' EXIT
358```
359
360Estas linhas mudam como o restante do hook se comporta, então verifique-o quanto a cada um destes padrões depois de adicioná-las:
361
362* **`exit 2` ou superior isolado**: com o trap definido, ele se torna saída 1. Para um erro que nenhuma nova tentativa pode corrigir, chame `permanent` com o motivo, como `permanent "namespace claude-runners does not exist"`. Chame-o no shell principal, não dentro de `$( )`, `( )` ou de um pipe.
363* **`exec`**: não inicie o último comando do hook com `exec`, porque `exec` substitui o shell e o trap não é executado.
364* **Segundo trap `EXIT`**: um segundo `trap ... EXIT` substitui o primeiro, então mescle os dois em um único trap. Coloque seus comandos de limpeza diretamente após `rc=$?;` e termine cada um com `|| true;`. A limpeza então é executada tanto em caso de falha quanto de sucesso, e um comando de limpeza que falha não define o status de saída do hook. Este trap mesclado mostra o formato, com `your-cleanup-command` representando o seu próprio comando:
365
366 ```bash theme={null}
367 trap 'rc=$?; your-cleanup-command || true; [ "$rc" -eq 0 ] || [ -n "${PERMANENT:-}" ] || exit 1' EXIT
368 ```
369* **Comandos que podem falhar**: se o hook não usava `set -e` antes, agora ele para no primeiro comando que retorna diferente de zero, como uma consulta que não encontra nada ou uma submissão duplicada que sua plataforma rejeita. Se o hook age com base no resultado, faça desse comando a condição de um `if`. Se ele ignora o resultado, siga o comando com `|| true`.
370
371Para confirmar que o trap funciona, adicione uma linha diretamente abaixo da linha `trap` que chama um comando que não existe, como `no-such-command`. Execute o arquivo do hook a partir do seu shell e verifique se `echo $?` imprime `1`, depois remova a linha.
372
296<h2 id="send-model-requests-to-bedrock-or-agent-platform">373<h2 id="send-model-requests-to-bedrock-or-agent-platform">
297 Enviar requisições de modelo para Bedrock ou Agent Platform374 Enviar requisições de modelo para Bedrock ou Agent Platform
298</h2>375</h2>
381Uma sessão que envia requisições de modelo para o Amazon Bedrock ou para o Agent Platform do Google Cloud difere de uma sessão na API da Anthropic das seguintes maneiras:458Uma sessão que envia requisições de modelo para o Amazon Bedrock ou para o Agent Platform do Google Cloud difere de uma sessão na API da Anthropic das seguintes maneiras:
382 459
383* **Políticas do claude.ai**: as [configurações gerenciadas pelo servidor](/docs/pt/server-managed-settings) não chegam a essas sessões. Também não chegam as políticas da organização que um Owner define nas configurações de administração do Claude Code, portanto o Claude Code não as aplica dentro da sessão. Coloque as regras das quais você depende no [arquivo de configurações gerenciadas](/docs/pt/managed-settings#delivery-mechanisms) da imagem do runner.460* **Políticas do claude.ai**: as [configurações gerenciadas pelo servidor](/docs/pt/server-managed-settings) não chegam a essas sessões. Também não chegam as políticas da organização que um Owner define nas configurações de administração do Claude Code, portanto o Claude Code não as aplica dentro da sessão. Coloque as regras das quais você depende no [arquivo de configurações gerenciadas](/docs/pt/managed-settings#delivery-mechanisms) da imagem do runner.
461* **Skills da conta**: essas sessões não baixam as skills ativadas para a conta do claude.ai de uma pessoa. Consulte [Como a configuração de cada sessão é montada](#how-each-session’s-config-is-assembled).
384* **Arquivos**: os arquivos que as pessoas anexam a uma sessão no claude.ai ou no aplicativo móvel ou desktop não chegam a ela, e o Claude não pode enviar arquivos de volta com a [ferramenta `SendUserFile`](/docs/pt/tools-reference). Em vez disso, coloque os arquivos de entrada no repositório ou no runner.462* **Arquivos**: os arquivos que as pessoas anexam a uma sessão no claude.ai ou no aplicativo móvel ou desktop não chegam a ela, e o Claude não pode enviar arquivos de volta com a [ferramenta `SendUserFile`](/docs/pt/tools-reference). Em vez disso, coloque os arquivos de entrada no repositório ou no runner.
385* **Seleção de modelo**: o plano de controle da Anthropic envia o modelo de cada sessão e, quando uma sessão é iniciada sem um, o Claude Code usa o seu padrão para o provedor. O runner remove `ANTHROPIC_MODEL` e `ANTHROPIC_DEFAULT_MODEL` do ambiente que passa às sessões. Os exemplos das páginas dos provedores definem `ANTHROPIC_MODEL`, mas no ambiente do runner nenhuma das duas variáveis tem efeito. As variáveis por família em Fixar versões de modelo para o [Amazon Bedrock](/docs/pt/amazon-bedrock#4-pin-model-versions) e o [Agent Platform](/docs/pt/google-vertex-ai#5-pin-model-versions) chegam às sessões. Elas decidem para o que um alias como `opus` é resolvido, não para o que um ID de modelo completo é resolvido.463* **Seleção de modelo**: o plano de controle da Anthropic envia o modelo de cada sessão e, quando uma sessão é iniciada sem um, o Claude Code usa o seu padrão para o provedor. Não é possível escolher o modelo com `ANTHROPIC_MODEL` ou `ANTHROPIC_DEFAULT_MODEL` no ambiente do runner, mas você pode fixar para o que um alias é resolvido:
464 * **`ANTHROPIC_MODEL` e `ANTHROPIC_DEFAULT_MODEL`**: o runner as remove do ambiente que passa às sessões, embora os exemplos das páginas dos provedores definam `ANTHROPIC_MODEL`.
465 * **Variáveis de fixação por família**: as variáveis em Fixar versões de modelo para o [Amazon Bedrock](/docs/pt/amazon-bedrock#4-pin-model-versions) e o [Agent Platform](/docs/pt/google-vertex-ai#5-pin-model-versions) chegam, sim, às sessões. Elas decidem para o que um alias como `opus` é resolvido, não para o que um ID de modelo completo é resolvido.
386* **Modelos que a sua conta não disponibiliza**: uma sessão pode falhar em uma mensagem com um erro que nomeia o modelo. Ative os modelos que os seus desenvolvedores podem escolher, o modelo de segundo plano descrito em Fixar versões de modelo e o modelo classificador que o [modo auto](/docs/pt/permission-modes#enable-auto-mode-on-bedrock-agent-platform-or-foundry) usa. No Amazon Bedrock, permita cada um deles na sua política.466* **Modelos que a sua conta não disponibiliza**: uma sessão pode falhar em uma mensagem com um erro que nomeia o modelo. Ative os modelos que os seus desenvolvedores podem escolher, o modelo de segundo plano descrito em Fixar versões de modelo e o modelo classificador que o [modo auto](/docs/pt/permission-modes#enable-auto-mode-on-bedrock-agent-platform-or-foundry) usa. No Amazon Bedrock, permita cada um deles na sua política.
387* **Pesquisa na web e modo rápido**: a [pesquisa na web](/docs/pt/tools-reference#websearch-tool-behavior) não está disponível no Amazon Bedrock, e o [modo rápido](/docs/pt/fast-mode) não está disponível em nenhum dos dois provedores. Para outros recursos que variam por provedor, consulte [Recursos da CLI que variam por provedor](/docs/pt/feature-availability#cli-capabilities-that-vary-by-provider).467* **Pesquisa na web e modo rápido**: a [pesquisa na web](/docs/pt/tools-reference#websearch-tool-behavior) não está disponível no Amazon Bedrock, e o [modo rápido](/docs/pt/fast-mode) não está disponível em nenhum dos dois provedores. Para outros recursos que variam por provedor, consulte [Recursos da CLI que variam por provedor](/docs/pt/feature-availability#cli-capabilities-that-vary-by-provider).
388 468
411 491
412As sessões herdam o ambiente do runner, então defina [`ENABLE_TOOL_SEARCH`](/docs/pt/mcp#scale-with-mcp-tool-search) lá para controlar a busca de ferramentas MCP em todas as sessões que um runner inicia; a página de MCP aborda os valores.492As sessões herdam o ambiente do runner, então defina [`ENABLE_TOOL_SEARCH`](/docs/pt/mcp#scale-with-mcp-tool-search) lá para controlar a busca de ferramentas MCP em todas as sessões que um runner inicia; a página de MCP aborda os valores.
413 493
494<a id="connection-timing" />
495
496<h3 id="wait-for-mcp-servers-before-the-first-turn">
497 Aguardar os servidores MCP antes do primeiro turno
498</h3>
499
500Uma sessão auto-hospedada aguarda brevemente pelos servidores MCP que ainda estão se conectando, em dois pontos distintos. Um servidor que perde uma espera fica com suas ferramentas ausentes quando o primeiro turno começa, e elas ficam disponíveis mais tarde sem nenhuma ação da sua parte. As duas esperas são:
501
502* **Inicialização da sessão**: antes de a lista de ferramentas ser obtida pela primeira vez, a sessão aguarda até 5 segundos por padrão por um servidor HTTP ou SSE cuja entrada define [`alwaysLoad: true`](/docs/pt/mcp#exempt-a-server-from-deferral), ou por todos os servidores quando você define [`MCP_CONNECTION_NONBLOCKING=0`](/docs/pt/env-vars) no ambiente do runner. Caso contrário, os servidores HTTP e SSE se conectam em segundo plano. Enquanto a sessão aguarda aqui, ela demora mais para inicializar. [`MCP_CONNECT_TIMEOUT_MS`](/docs/pt/env-vars) altera o padrão de 5 segundos.
503* **Primeiro turno**: depois que a mensagem chega, o primeiro turno aguarda até 2 segundos pelos servidores stdio que ainda estão se conectando. Enquanto a sessão aguarda aqui, a primeira resposta demora mais. Para alterar a duração dessa espera, defina [`CLAUDE_CODE_MCP_STARTUP_WAIT_MS`](/docs/pt/env-vars) no ambiente do runner. Isso não altera quais servidores a espera abrange. Requer o Claude Code v2.1.274 ou posterior.
504
505O `claude mcp add` não tem uma flag `alwaysLoad`. Para definir a chave, adicione o servidor com `claude mcp add-json`, que a recebe no JSON do servidor e a grava em `.claude.json`. No seu Dockerfile:
506
507```dockerfile theme={null}
508RUN claude mcp add-json core '{"type":"http","url":"https://mcp.example.com/mcp","alwaysLoad":true}' --scope user
509```
510
511Se as ferramentas de um servidor também não aparecerem nos turnos seguintes, verifique se o servidor chegou à sessão, conforme descrito em [Servidores MCP](#mcp-servers).
512
414<h3 id="turn-off-built-in-session-tools">513<h3 id="turn-off-built-in-session-tools">
415 Desativar as ferramentas de sessão integradas514 Desativar as ferramentas de sessão integradas
416</h3>515</h3>
571 670
572Defina `SELF_HOSTED_RUNNER_HOST_CONFIG_DIR` para semear de um caminho diferente, ou aponte-o para um diretório vazio para desabilitar a semeadura.671Defina `SELF_HOSTED_RUNNER_HOST_CONFIG_DIR` para semear de um caminho diferente, ou aponte-o para um diretório vazio para desabilitar a semeadura.
573 672
574O `.claude/settings.json` com commit no repositório se sobrepõe como configurações de projeto. Em uma sessão com vários repositórios, [no máximo o arquivo de um repositório tem efeito](#repository-settings-in-sessions-with-several-repositories). Sessões também leem [`managed-settings.json`](/docs/pt/settings#where-settings-live) do caminho de sistema padrão em sua imagem do runner. Se suas chaves se aplicam ao lado de [server-managed settings](/docs/pt/server-managed-settings) segue [como Claude Code combina fontes gerenciadas](/docs/pt/managed-settings#how-claude-code-combines-managed-sources): por padrão, quando sua organização entrega quaisquer chaves gerenciadas pelo servidor, sessões ignoram o arquivo da imagem do runner além das [chaves que Claude Code lê de cada fonte de administrador](/docs/pt/managed-settings#keys-read-from-every-admin-source), como o bloco `env`, os locks de sandbox, os caminhos binários de sandbox e `forceRemoteSettingsRefresh`. Consulte [settings precedence](/docs/pt/settings#settings-precedence).673As sessões também leem estes arquivos de configurações:
674
675* **Configurações de projeto**: um `.claude/settings.json` com commit no repositório se sobrepõe à linha de base de nível de usuário. Em uma sessão com vários repositórios, [no máximo o arquivo de um repositório tem efeito](#repository-settings-in-sessions-with-several-repositories).
676* **Configurações gerenciadas**: as sessões leem [`managed-settings.json`](/docs/pt/settings#where-settings-live) do caminho de sistema padrão em sua imagem do runner. Para saber se suas chaves se aplicam ao lado de [server-managed settings](/docs/pt/server-managed-settings), consulte [como Claude Code combina fontes gerenciadas](/docs/pt/managed-settings#how-claude-code-combines-managed-sources).
677
678Para a ordem em que essas fontes se aplicam, consulte [settings precedence](/docs/pt/settings#settings-precedence).
575 679
576Quando o plano de controle da Anthropic fornece uma sessão com [Claude Code hooks](/docs/pt/hooks), o runner os instala ao lado, não sobre, sua própria configuração. Requer Claude Code v2.1.229 ou posterior.680Quando o plano de controle da Anthropic fornece uma sessão com [Claude Code hooks](/docs/pt/hooks), o runner os instala ao lado, não sobre, sua própria configuração. Requer Claude Code v2.1.229 ou posterior.
577 681
579* **Quem os autora**: o plano de controle popula os scripts de constantes fixas em sua própria implantação, nunca de entrada por sessão ou de terceiros.683* **Quem os autora**: o plano de controle popula os scripts de constantes fixas em sua própria implantação, nunca de entrada por sessão ou de terceiros.
580* **O que ainda os governa**: hooks entregues através de `--settings` entram na configuração de hook mesclada ordinária, não na camada gerenciada, então suas configurações gerenciadas ainda se aplicam. `disableAllHooks` os desabilita, e eles não estão entre as categorias que [`allowManagedHooksOnly`](/docs/pt/settings-reference#allowmanagedhooksonly) mantém carregadas.684* **O que ainda os governa**: hooks entregues através de `--settings` entram na configuração de hook mesclada ordinária, não na camada gerenciada, então suas configurações gerenciadas ainda se aplicam. `disableAllHooks` os desabilita, e eles não estão entre as categorias que [`allowManagedHooksOnly`](/docs/pt/settings-reference#allowmanagedhooksonly) mantém carregadas.
581 685
686Quando uma pessoa inicia sua própria sessão, o Claude Code também baixa as [skills habilitadas para sua conta claude.ai](/docs/pt/skills#skills-in-cowork-and-cloud-sessions) no diretório de configuração dessa sessão. Uma execução de [rotina](/docs/pt/routines) não recebe as skills de seu proprietário, e uma sessão que [envia requisições de modelo para Bedrock ou Agent Platform](#send-model-requests-to-bedrock-or-agent-platform) não baixa nenhuma. Para uma skill de que essas sessões precisem, faça commit dela no `.claude/skills/` do repositório ou adicione-a à sua imagem do runner.
687
582Fora das sessões do [Claude Tag](https://claude.com/docs/claude-tag/overview), uma sessão em um ambiente auto-hospedado é executada com a [memória automática](/docs/pt/memory#auto-memory) desativada por padrão. Para instruções que devem persistir entre sessões, use o `CLAUDE.md` em sua imagem do runner ou no repositório.688Fora das sessões do [Claude Tag](https://claude.com/docs/claude-tag/overview), uma sessão em um ambiente auto-hospedado é executada com a [memória automática](/docs/pt/memory#auto-memory) desativada por padrão. Para instruções que devem persistir entre sessões, use o `CLAUDE.md` em sua imagem do runner ou no repositório.
583 689
584O snapshot do `~/.claude/` do host feito pelo runner deixa de fora o diretório `projects/`. O local de armazenamento padrão da memória automática fica sob esse diretório. Se você colocar arquivos de memória lá, o runner não os semeia nas sessões, e eles não ativam a memória automática.690O snapshot do `~/.claude/` do host feito pelo runner deixa de fora o diretório `projects/`. O local de armazenamento padrão da memória automática fica sob esse diretório. Se você colocar arquivos de memória lá, o runner não os semeia nas sessões, e eles não ativam a memória automática.
