Configuração¶

flower não tem formato de arquivo de configuração, nem um subcomando de configuração que dê para usar de verdade — toda a configuração são variáveis de ambiente mais arquivos .env, mais um punhado de objetos de política que só podem ser passados pelo lado Python. Esta página junta numa coisa só o que está espalhado por cinco lugares: cada variável, em que ordem as credenciais são procuradas, que sintaxe o .env reconhece, o que exatamente setting_sources=[] isola, o que uma execução deixa em disco, o que cada uma das três camadas do session store descarta, e como ele espera quando a rede cai. A terminologia segue o glossário.

Tabela completa de variáveis de ambiente¶

Cinco grupos: credenciais e endpoint lidos diretamente pelo flower, seleção de modelo, busca de caminhos, chaves de comportamento, e as que o flower escreve para o subprocesso do agent. O último grupo você não precisa definir — se definir, será sobrescrito.

Credenciais e endpoint¶

Se nenhuma das duas estiver definida (ou ambas forem string vazia), check_credentials() devolve aquele erro de quatro linhas e Runtime.__init__ também levanta RuntimeError (env.py:184-194; runtime.py:156-158).

Seleção de modelo¶

O flower lê só três delas para tomar decisões próprias; o resto é carregado e repassado ao SDK.

Se o flower setup preencher o nome do modelo, ANTHROPIC_MODEL, ANTHROPIC_DEFAULT_OPUS_MODEL e ANTHROPIC_DEFAULT_SONNET_MODEL são escritas as três juntas (cli.py:1383-1385).

Caminhos e busca¶

Chaves de comportamento¶

As duas são saídas de emergência: o normal é não definir; definir serve para o flower fazer uma coisa a menos. Qualquer valor não vazio ativa, o valor em si não é interpretado (update.py:121; cli.py:1413).

Um flower rodando a partir do código-fonte git não é afetado pela atualização automática, e FLOWER_NO_UPDATE é no-op para ele — o passo do comando de update reconhece que há um .git no repositório e retorna None direto (update.py:83-87).

O que o flower escreve para o subprocesso do agent¶

Estas três são geradas por CompactPolicy.env() e enfiadas em ClaudeAgentOptions.env (agent.py:48-58, :241-245), controlando o compact embutido no harness. Defini-las no seu shell não tem efeito — o que vale é a cópia que o flower passa ao subprocesso.

Lidas pelo wrapper de container¶

Estas duas não são lidas pelo flower em si, e sim pelo wrapper shell docker/flowerbox. Uso completo em deploy.

As chaves do .env não se limitam às acima. O parser carrega todas as linhas k=v em os.environ, sem whitelist (env.py:30, :102-107). O conjunto KNOWN, formado por aquelas 9 chaves de credencial, só atua em dois pontos: como whitelist ao emprestar a configuração de ~/.claude (env.py:72), e como escopo de campos impressos por describe() ao subir com -v (env.py:205).

Prioridade de busca de credenciais¶

Quando load_dotenv() é chamado sem caminho, ele lê em sequência todos os arquivos existentes na ordem abaixo (env.py:45-53, :78-112):

1. Variáveis de ambiente do processo — sempre no topo. Nenhum .env sobrepõe um valor já exportado. (env.py:91)
2. O arquivo apontado por $FLOWER_ENV — só existe se estiver definida. (env.py:48-49)
3. $PWD/.env — o diretório de trabalho atual. Você faz cd num projeto e ele lê o mais próximo. (env.py:50)
4. ${XDG_CONFIG_HOME:-~/.config}/flower/.env — o local global, um por pessoa; é este que o flower setup escreve. (env.py:51, :39-42)
5. O .env na raiz do repositório de código — três níveis acima de flower/core/env.py. Só existe rodando a partir do fonte; um flower instalado por pip / pipx / uv fica em site-packages e não tem esta entrada. (env.py:52)
6. O bloco env de ~/.claude/settings.json e depois de ~/.claude/settings.local.json — o fallback final, pegando só as 9 chaves de credencial. (env.py:56-75, :109-111)

Qual arquivo ganha: o item 3 (.env do projeto) ganha do item 4 (.env global), o item 4 ganha do item 5 (.env da raiz do repositório), os três ganham do item 6 (configuração do Claude Code), e nenhum deles ganha do item 1 (ambiente do processo).

A implementação é "chave que já tem valor não é sobrescrita" (env.py:90-93): quem vem antes ocupa a chave, quem vem depois só preenche as lacunas. Ou seja, a prioridade é por chave, não por arquivo — se o .env do projeto só tem ANTHROPIC_BASE_URL, o token pode perfeitamente vir do global. O primeiro valor de uma chave homônima define o destino dela.

O item 6 só entra na busca automática. Se você passar um caminho explícito (load_dotenv("/path/to/.env")), ele lê apenas aquele arquivo, sem nenhum fallback (env.py:86-87, :109).

Item 6: emprestar o token do Claude Code¶

Lê em sequência ~/.claude/settings.json e ~/.claude/settings.local.json, pega o dict data["env"] e seleciona dele estas 9 chaves (env.py:31-36, :65-74):

ANTHROPIC_API_KEY   ANTHROPIC_AUTH_TOKEN   ANTHROPIC_BASE_URL
ANTHROPIC_MODEL     ANTHROPIC_DEFAULT_OPUS_MODEL    ANTHROPIC_DEFAULT_SONNET_MODEL
ANTHROPIC_DEFAULT_HAIKU_MODEL    CLAUDE_CODE_SUBAGENT_MODEL    CLAUDE_CODE_EFFORT_LEVEL

Se o arquivo não existir, não puder ser lido, ou não for JSON válido (OSError / ValueError), retorna um dict vazio e segue adiante — um fallback que falha não deve derrubar esta execução (env.py:62-63, :66-69).

A posição no código é: o que se empresta é só "onde achar o token"; nada mais do settings.json (regras de permissão, hooks, configuração de modelo) é assumido, então isso não viola a promessa de portabilidade do setting_sources=[] (env.py:17-19, :59-61). O install.sh:77 divulga isso como um recurso: quem já tem Claude Code configurado na máquina nem chega a ver a tela de configuração.

flower 不读 ~/.claude/settings.json —— 那是可移植性的代价。

Regras de parsing do .env¶

As regras de parsing são curtas o bastante para decorar (env.py:95-107, 13 linhas): strip em cada linha, pula linhas vazias, linhas começando com # e linhas sem =; o resto é cortado no primeiro = em key e value, com strip dos dois lados, e o value passa ainda por um .strip("'\"") — aspas simples ou duplas no início e no fim são removidas, sem exigir que sejam pareadas.

Reconhece estas formas:

Não reconhece estas. Escrever assim não dá erro, apenas produz silenciosamente um valor inesperado:

Um valor vazio ocupa a chave. Se ANTHROPIC_AUTH_TOKEN= aparecer num arquivo de prioridade mais alta, take() executa os.environ["ANTHROPIC_AUTH_TOKEN"] = "", e os arquivos seguintes não conseguem preencher porque "a chave já existe" (env.py:90-93); enquanto check_credentials() avalia por veracidade, e string vazia conta como não configurado (env.py:186). O resultado é ficar sem credencial e sem fallback. Se não quer uma chave, apague a linha inteira; não deixe uma vazia.

O preço da portabilidade¶

Aquela única linha em build_options() é todo o mecanismo (agent.py:207):

"setting_sources": [] if portable else ["project"],

portable=True é o padrão do Runtime, e não existe flag de linha de comando para desligar — só dá pela API Python, escrevendo Runtime(portable=False), o que passa a ["project"], ou seja, lê o .claude/ do projeto.

O que fica isolado¶

Capacidades de domínio não passam por esse caminho — elas são distribuídas junto com o repositório e carregadas via plugins=[{"type": "local", "path": PLUGIN_DIR}] (agent.py:26, :210-212), ver deploy. Já as instruções de domínio são append depois do system prompt nativo do Claude Code, não substituição (agent.py:198-202), de modo que a especialização não custa a capacidade geral.

O que levar ao trocar de máquina¶

• Credenciais: um arquivo. Copie ~/.config/flower/.env, ou refaça a configuração na máquina nova. Sem isso nada roda — nada é herdado automaticamente.
• Estado de continuidade: o diretório inteiro. runs/ (session store, manifesto, linhagem) e .flower/ (workbench).
• Mas os caminhos precisam bater. O lineage.json guarda o caminho absoluto do workspace; se não bater, é como se não existisse e ele cai silenciosamente numa session nova, sem erro (lineage.py:65-66). O motivo é que o project_key do SDK é derivado do caminho do workspace (/, _ e . viram -, runtime.py:40-41); se o diretório muda de lugar, o session_id antigo não é mais encontrado.

Layout em disco¶

Uma execução do flower escreve duas árvores: <run_dir>/ guarda a contabilidade e as sessions, <workspace>/.flower/ guarda o workbench. Por padrão as duas ficam no diretório atual, mas as bases delas são diferentes.

<run_dir>/ — padrão ./runs/¶

runs/
  sessions.db        SQLite, transcript completo (incluindo a de cada subagent)
  manifest.json      manifesto de execução: session_id / custo / retries / motivo de falha de cada passo, acumulado entre processos
  lineage.json       linhagem: nome do passo → session_id; é por ela que uma nova execução no mesmo diretório retoma
  aside/             Runtime independente das perguntas do oracle, com seus próprios sessions.db + manifest.json
  workbench/         só no caminho run / once e quando -W é passado

Cada linha do manifest.json é um asdict(StepResult) mais dois remendos (runtime.py:44-71, :579-582):

A estratégia de escrita é append, não overwrite: a cada gravação ele relê o arquivo, troca as linhas cujo run é o dele mesmo pelas mais recentes e deixa as dos outros intactas (runtime.py:564-586). Assim, vários flower rodando em paralelo no mesmo diretório não sobrescrevem a contabilidade um do outro.

O que está em runs/ é dado puro, e pode ser vasculhado offline a qualquer momento com sqlite3 ou com tools/analyze_run.py.

<workspace>/.flower/ — o workbench¶

.flower/
  INDEX.md      índice gerado automaticamente, injetado no system prompt do agent principal
  scripts/      scripts que serão executados de novo. A primeira linha `# desc: uma frase` aparece no índice
  artifacts/    saídas longas acima de 2000 caracteres: relatórios, dados, logs
  notes/        registros de decisão que atravessam passos
  spill/        resultados grandes de ferramenta que foram para o spill; nome do arquivo = primeiros 16 dígitos do sha256 do conteúdo + `.txt`

Os três subdiretórios e o índice são criados pelo Workbench (workbench.py:73-92). O INDEX.md vai pelo system_prompt.append no nível da session, e subagents não herdam — por isso a regra "saída longa vai para artifacts/" tem que ser repassada pelo coordenador dentro do task brief; é o único canal.

O caminho go gera sempre estes arquivos em notes/:

Com --isolate, o workbench sai do repositório: <diretório pai do workspace>/.flower-<nome do workspace>/ (starter.py:47-55). O worktree é a cópia privada de cada agent, e o workbench é a camada compartilhada entre agents; o que é compartilhado não pode ficar dentro da cerca privada. Nesse caso, o caminho dado ao modelo é absoluto (workbench.py:69-71, :142-145).

O spill/ tem dois escritores, com algoritmos de destino diferentes:

No layout padrão é o mesmo diretório. Mas quando o workbench é movido (com -W, caindo em runs/workbench/, ou com --isolate, caindo fora do repositório) os dois se separam — a parte do TrimPolicy fica sempre dentro do workspace, porque o Read do agent precisa alcançá-la.

O que o spill_guard coloca no lugar não é uma linha, é uma linha de ponteiro mais os primeiros 400 caracteres (guard.py:132-140). As chamadas que leem o próprio arquivo do spill são liberadas, senão "use Read para pegar o texto completo" seria conversa fiada — leria de volta, passaria do limiar, iria para o spill de novo, num laço infinito (guard.py:155-170).

Estrutura de tabelas do sessions.db¶

Três tabelas, com os CREATE em stores/sqlite.py:27-51:

CREATE TABLE entries (
    store_key TEXT NOT NULL,
    seq       INTEGER NOT NULL,
    uid       TEXT,
    payload   TEXT NOT NULL,
    PRIMARY KEY (store_key, seq)
);
CREATE UNIQUE INDEX entries_uid
    ON entries(store_key, uid) WHERE uid IS NOT NULL;
CREATE TABLE meta (
    store_key TEXT PRIMARY KEY,
    mtime     INTEGER NOT NULL,
    next_seq  INTEGER NOT NULL
);
CREATE TABLE summaries (
    project_key TEXT NOT NULL,
    session_id  TEXT NOT NULL,
    mtime       INTEGER NOT NULL,
    data        TEXT NOT NULL,
    PRIMARY KEY (project_key, session_id)
);

Construção do store_key (sqlite.py:54-58): <project_key>/<session_id>, e para subagent acrescenta-se ainda um subpath. O project_key é derivado pelo SDK a partir do caminho do workspace — /, _ e . viram -.

Uma olhada numa amostra real (human-test/HT002/runs/sessions.db):

sqlite3 runs/sessions.db "select store_key, next_seq from meta;"

-Users-hechenyu-explore-test-ide/601c8c91-6c4b-4525-8a5f-295b99bf9515|37
-Users-hechenyu-explore-test-ide/47395075-bec7-466e-80cd-f4d60b360235|80
-Users-hechenyu-explore-test-ide/47395075-…/subagents/agent-a99a6ce30a5471f44|104

Aquela amostra tem 956 entries, 10 meta e 4 summaries — das 10 sessions, 4 são transcript principal e 6 são de subagent, e summaries bate exatamente com o número de transcripts principais.

As três camadas do session store¶

O append (escrita) sempre grava tudo, sem mudar uma palavra. As três camadas só afetam o load (a cópia que volta para o modelo). A ordem real do load é:

SqliteSessionStore.load     lê tudo da tabela entries por seq
  → TrimmingSessionStore.expire()   resultados de Bash sensíveis ao tempo → viram "expirado"
  → TrimmingSessionStore.trim()     tool_result grandes e antigos → spill + ponteiro
    → PruningSessionStore.prune()   mensagens de erro sintéticas / chamadas negadas antigas → item removido e cadeia religada

A camada 2 é trim e a camada 3 é prune — trim descarta por volume e valor, prune descarta por "é erro ou não"; não confunda. As assinaturas completas estão na API Python.

SqliteSessionStore — a fundação¶

SqliteSessionStore(path: str | Path)

Implementação SQLite sem dependências externas. Para trocar por Postgres / S3 / Redis, basta implementar o mesmo protocolo; o SDK traz a suíte de testes de conformidade claude_agent_sdk.testing.session_store_conformance, que valida direto (sqlite.py:1-8).

Além dos métodos do protocolo, há três consultas síncronas para uso do próprio flower:

TrimmingSessionStore + TrimPolicy / EphemeralPolicy¶

TrimmingSessionStore(path, workspace, policy: TrimPolicy | None = None,
                     ephemeral: EphemeralPolicy | None = None)

Duas regras ortogonais. A TrimPolicy cuida do volume:

O corpo trimado é escrito como <primeiros 16 dígitos do sha256>.txt, e no lugar original entra [工具结果已归档:N 字符。完整内容在 <路径>,需要时用 Read 读取] (trim.py:54-57, :308-317).

A EphemeralPolicy cuida da validade temporal: resultados de git status, ls, ps e afins são curtos, e por volume nunca seriam trimados, mas a correção deles decai com o tempo — aquele git status de 20 turnos atrás não é "inútil", ele engana.

Age apenas sobre resultados da ferramenta Bash, e o comando precisa casar com EPHEMERAL_CMD. Read não entra: o conteúdo de um arquivo não se distorce com o tempo a ponto de enganar, e pode ser justamente a base do raciocínio do modelo (trim.py:153-160). Conteúdo expirado não vai para o spill — arquivar um git status expirado não tem sentido, basta rodar de novo.

A função de decisão é is_ephemeral(cmd), e ela é ao mesmo tempo a lista de permissões devolvida ao coordenador: delegate_guard(allow_glance=True) usa a mesma função (trim.py:63-68, :128-150). Os dois conjuntos têm que ser sempre iguais — liberar sem trimar faz um git status expirado ocupar contexto para sempre; trimar sem liberar faz o coordenador despachar um subagent para um ls, trocando 4.3k de custo de inicialização por algumas dezenas de caracteres. Acrescentar um comando à whitelist equivale a dizer as duas coisas ao mesmo tempo.

Quando usar o quê:

• Só quer que o resíduo de queda de conexão não entre no contexto → não precisa fazer nada, o Runtime já usa PruningSessionStore por padrão. trim=False apenas deixa de trimar resultados grandes; a remoção continua acontecendo.
• Execução longa, com saídas de ferramenta muito grandes → trim=True. No caminho go o CLI já vem com isso ligado; use --no-trim para desligar.
• Coordenador com glance=True → ephemeral precisa continuar ligado, pelo motivo do parágrafo anterior.

PruningSessionStore + PrunePolicy¶

PruningSessionStore(path, workspace, policy: TrimPolicy | None = None,
                    prune: PrunePolicy | None = None,
                    ephemeral: EphemeralPolicy | None = None)

keep_denials é o único parâmetro de construção do Runtime que é repassado a esta camada (Runtime(keep_denials=N)). O motivo de o padrão ser 1 e não 0: a negação mais recente é sinal útil e evita que o modelo repita o mesmo comando bloqueado várias vezes no mesmo turno. Não aumente — uma chamada negada nunca foi executada, não há informação alguma no resultado, e na medição cada uma ocupa 273 caracteres (93 caracteres de mensagem de recusa mais 180 caracteres do comando morto original); além disso, ela engana: na prática, depois de ler algumas mensagens do tipo "não use Bash diretamente", o coordenador parava de tentar até o git status que era liberado, dizendo direto "o Bash está restrito, manda um agent olhar" (prune.py:135-148).

heal_orphans trata o caso de cada resume dar 400 depois de uma interrupção: a interrupção corta na fronteira de mensagem, e o tool_use que estava em voo pode simplesmente não ter um tool_result depois dele, sendo que a API exige que venham em par. Esse histórico ruim fica no transcript e não some sozinho, então todo resume seguinte é rejeitado por ele. A correção insere um item user logo depois daquele assistant que contém os órfãos, preenchendo de uma vez os resultados de todos os órfãos daquele item, e depois muda o parentUuid que apontava para aquele assistant para apontar para o item inserido (prune.py:95-147). Acrescenta em vez de apagar: apagar órfãos exigiria religar a cadeia pai-filho, e o mesmo assistant pode ter blocos normais, texto e thinking, que seriam levados junto (prune.py:195-204).

Três linhas vermelhas estruturais; violá-las faz a API dar erro na hora:

1. O próprio bloco tool_result precisa existir, só o content pode ser trocado. Faltar um é "Missing Tool Result Block" (trim.py:20-22; prune.py:79-92).
2. Itens isCompactSummary / isMeta não podem ser mexidos — são a única forma de existência daquele trecho de histórico que foi comprimido (trim.py:179-181).
3. Ao remover um item é obrigatório religar os filhos dele ao pai dele. O transcript é uma cadeia simples por parentUuid, e o harness caminha das folhas para trás; onde a cadeia quebra, todo o histórico anterior se perde (prune.py:95-122). Por isso relink() precisa receber a lista completa incluindo os itens a remover, e faz a filtragem por conta própria.

Nenhuma palavra do original no SQLite é alterada — as três camadas só afetam "a cópia que volta para o modelo" (trim.py:18; prune.py:8).

Resiliência a queda de rede¶

Um workflow long-horizon roda por horas, e a rede vai cair pelo menos uma vez. O comportamento padrão é péssimo: no instante da queda o harness enfia no transcript uma mensagem assistant sintética (model="<synthetic>", isApiErrorMessage=true) com o corpo API Error: Can't reach the API server …; ela vira a folha da session, e no resume seguinte é devolvida ao modelo como "a última coisa que o modelo disse", fazendo o modelo achar que está discutindo uma falha de rede; e ainda se mistura ao StepResult.text, sendo propagada pelo workflow para o prompt do passo seguinte (resilience.py:1-22).

A camada de resiliência faz três coisas, e nenhuma pode faltar: sonda, continuar em vez de recomeçar, e erro fora do contexto.

Parâmetros de Resilience¶

Fórmula do backoff (resilience.py:119-121):

min(base_delay * 2 ** (attempt - 1), max_delay) * (0.75 + random() * 0.5)

Ou seja, jitter de ±25%, para evitar que um monte de processos se atire junto no instante em que a rede volta. Com os padrões: 1ª espera de 4 segundos (na prática 3~5), 2ª de 8 segundos (6~10), da 5ª em diante teto de 120 segundos (90~150).

Estratégia da sonda¶

• Sonda o host:port de ANTHROPIC_BASE_URL, não api.anthropic.com (resilience.py:67-72). Com gateway próprio, o segundo responder não diz nada sobre o primeiro.
• Só DNS mais handshake TCP: getaddrinfo, depois connect_tcp, e fecha em seguida. Não manda HTTP, não leva credencial, não custa nada (resilience.py:75-85). A sonda precisa ser gratuita, senão "sondar a cada 15 segundos com a rede caída" vira ela mesma uma falha.
• Qualquer falha conta como inacessível — não distingue DNS caído de TCP recusado.
• wait_online() fica ali esperando: retorna True se voltar, e False se estourar max_offline_wait. Na primeira vez que fica inacessível, notifica uma linha <host>:<port> 不可达,等待恢复(最多 60 分钟), e ao voltar notifica outra linha <host>:<port> 恢复,继续, sem encher a tela no meio (resilience.py:126-140).

Aquela sonda de credenciais antes de começar é outra coisa: ela realmente dispara um POST <BASE_URL>/v1/messages com max_tokens=16 e timeout padrão de 20 segundos (env.py:126-181). Não coloque max_tokens em 1 — na medição, modelos com cadeia de raciocínio forçada não cabem nem o raciocínio, e o servidor se debate até 30 segundos para responder; com 16 leva apenas 3.6 segundos (env.py:120-123).

Classificação de erros¶

classify(text) devolve uma de três. Avalia fatal primeiro: textos de 401 e afins costumam trazer palavras como "connection", e com a ordem invertida o processo espera para sempre (resilience.py:53-64).

Separar o que é repetível do que não é é o núcleo desta camada: oscilação de rede merece espera, credencial errada merece parada imediata — esperar com a rede caída é o certo; esperar com a key errada é queimar tempo.

O que fica barrado fora do contexto¶

1. Mensagens de erro sintéticas. O PruningSessionStore remove o item inteiro no load e religa o parentUuid (prune.py:27-32, :191-195). Fica intacto no SQLite, só não é devolvido ao modelo.
2. No stream de eventos ele é kind="error" e não "text", então não entra em StepResult.text e portanto não é propagado pelo workflow para o prompt do passo seguinte (resilience.py:17-18).
3. O resume_prompt deliberadamente não traz nenhum detalhe do erro. O modelo precisa saber "fui interrompido, continue"; não precisa saber se foi ENOTFOUND ou 503. Isso pertence ao log, não ao contexto (resilience.py:112-113). O log está no campo errors do manifest.json.

Continuar em vez de recomeçar: quando a falha acontece o session_id já foi obtido, então o resume retoma do ponto de interrupção e o que já foi gasto não é jogado fora.

Relacionados¶

• Linha de comando — como cada flag mapeia para a configuração desta página.
• API Python — assinaturas completas de Runtime, dos três stores e de Resilience.
• Deploy — rodar em container, distribuir capacidades de domínio via plugin.
• Glossário — o significado exato de cada termo usado nesta página.