Integração do Slack / Linear com SDK: Chame o Codex em outros lugares e insira-o no seu próprio produto

📚 Navegação da Série: Artigo anterior 〔28 Modo Não Interativo codex exec〕 fala sobre o método de execução autônoma "jogar uma frase, terminar de executar, retornar o resultado e sair" — esse é o primeiro quebra-cabeça para integrar o Codex a scripts e CI. Este artigo vai dois passos além: primeiro, sem abrir o terminal, basta chamar o Codex diretamente no Slack ou Linear para fazê-lo trabalhar; segundo, usando o SDK oficial / App Server, integre o Codex como um componente em seus próprios programas e produtos. O próximo artigo 〔30 Como Escolher Modelos〕 volta para o ambiente local, focando em "para a mesma frase, qual modelo devemos enviar para rodar".

ℹ️ Este artigo é de leitura opcional, voltado para leitores avançados. Se você atualmente usa o Codex apenas no terminal, aplicativo de desktop ou IDE, você não precisará do conteúdo deste artigo por enquanto; ignorá-lo não afetará em nada o seguinte. Volte a ler quando tiver a ideia de "querer delegar tarefas diretamente no IM da equipe" ou "querer colocar o Codex no seu próprio produto".

Primeiro, vamos mostrar uma conversa adaptada de um caso real, e você provavelmente entenderá sobre o que este artigo trata.

Um colega postou uma captura de tela de erro no canal do Slack e adicionou: "Esta API de login deu 500 de novo, quem pode dar uma olhada?" Eu não estava com o computador ligado, então respondi diretamente abaixo daquela mensagem: @Codex dê uma olhada nesse 500 acima, localize a causa em openai/our-backend. Poucos segundos depois, o Codex reagiu à mensagem com 👀 e respondeu com um link para a tarefa: "Iniciado, aguarde um momento". Fui para a reunião. Ao voltar, o Codex havia postado no thread a conclusão da localização e um diff de alteração, e clicando no link eu já podia abrir um PR.

Durante todo o processo, eu não escrevi uma única palavra de código, não abri o terminal e nem mesmo estava perto do computador. Isso é "chamar o Codex em outros lugares" — libertando-o completamente de "você ter que sentar na frente do terminal" e levando-o para o Slack e o Linear, onde sua equipe passa o dia todo. O SDK / App Server é um nível mais avançado: não apenas usar o Codex nos produtos de outras pessoas, mas colocar o Codex dentro do seu próprio produto.

Ao terminar de ler este artigo, você obterá:

• Uma explicação simples para distinguir os dois níveis de "chamar o Codex" — integrar com zero código no Slack/Linear ou escrever código para embuti-lo em seus próprios programas
• A configuração e o uso completos de como delegar tarefas com @Codex no Slack, além de como ele escolhe automaticamente ambientes e repositórios, e como o Enterprise gerencia dados
• Duas formas de delegar issues para o Codex no Linear (atribuição / comentário @) e como delegar tarefas automaticamente usando regras de triagem (triage)
• O que é o Codex SDK (duas versões: TypeScript / Python), qual instalar, como é a estrutura do menor código e qual a diferença entre ele e codex exec
• O que é o App Server, quando é a sua vez de entrar em cena — e uma regra de decisão de "use primeiro o SDK, não mexa no App Server logo de início"
• Um programa SDK mínimo que você pode rodar passo a passo com a saída esperada fornecida

⚠️ Qualquer comando específico, nome de pacote, item de configuração ou comportamento padrão mencionado abaixo é baseado na documentação oficial do Codex (Slack / Linear / SDK / App Server); nomes de modelos e planos que mudam com a versão devem ser baseados no que realmente aparece para você localmente no momento, este artigo não os fixa.

---

01 Primeiro, distinga os dois níveis: "Chamar" com zero código ou "Embutir" escrevendo código

Este artigo parece misturado — com Slack, Linear, SDK e App Server juntos, os iniciantes podem ficar confusos facilmente. Na verdade, eles fazem dois tipos de coisas fundamentalmente diferentes. Vamos traçar essa linha claramente primeiro, e o resto fará sentido.

Analogia: Existem duas maneiras de contratar um assistente completo para ajudar você. A primeira: esse assistente já está integrado a alguns softwares de escritório que você usa com frequência (Slack, Linear). Você só precisa dar um @ no grupo e delegar a tarefa — o Slack / Linear é esse ponto de entrada, construído para você pela OpenAI, com zero código, pronto para usar com um simples @. A segunda: você quer trazer esse assistente para a empresa que você mesmo abriu, inserindo-o no fluxo do seu negócio — isso exige assinar um contrato e integrar sistemas (escrever código para chamar o SDK / App Server), tornando-o parte do seu produto — esse é o caminho de "escrever código para embutir".

Quando se trata dessas quatro ferramentas, a divisão de trabalho é a seguinte:

Este nível	O que é especificamente	O que você precisa fazer	Onde roda
Chamar com zero código	Integração com Slack, Integração com Linear	Instalar a integração, delegar tarefas com @Codex	Tarefas na nuvem da OpenAI
Escrever código para embutir	Codex SDK (TS / Python)	Escrever código para chamar e controlar o Codex	Seu processo / CI / Serviço
Escrever código para embutir (mais baixo nível)	App Server	Conectar usando JSON-RPC para integração profunda	Seu cliente / Dentro do seu produto

Há também um entendimento fundamental que precisa ser estabelecido primeiro: as tarefas enviadas pelo Slack e Linear rodam como "tarefas na nuvem" (Codex cloud, mencionado no Artigo 10). Em outras palavras, quando você usa @Codex no Slack, a essência é "fazer com que ele crie um novo contêiner na nuvem da OpenAI, clone seu repositório do GitHub, execute o trabalho e entregue o diff" — a única diferença é que a entrada para a tarefa mudou do navegador para uma mensagem do Slack. Portanto, todos os pré-requisitos da versão em nuvem do Artigo 10 (conectar ao GitHub, configurar o ambiente e ter um plano pago) são herdados pelo Slack/Linear, o que será mencionado repetidamente mais adiante.

Quando você vai se lembrar das coisas deste artigo? Três tipos de sinais:

• "Quero repassar esse erro/requisito diretamente para o Codex, mas não quero ligar o computador especificamente para abrir o terminal" — integre com Slack/Linear
• "Quero escrever um script com o mesmo fluxo do Codex e rodá-lo automaticamente no CI" — use o SDK
• "Quero fazer uma integração profunda no meu próprio produto, como uma extensão do VS Code, precisando de histórico de conversas, aprovações e fluxo de eventos (streaming)" — só então será a vez do App Server

💡 Resumo em uma frase: Este artigo está dividido em dois níveis — Slack/Linear são os pontos de entrada de "chamada com zero código" preparados pela OpenAI para você (rodando tarefas em nuvem no backend), enquanto SDK/App Server são os caminhos para você "escrever código para embutir o Codex em seu próprio produto"; identifique a qual nível você pertence antes de prosseguir.

---

02 Chamar no Slack: Delegar tarefas com uma frase usando @Codex

Vamos começar com o mais fácil de aprender e mais usado — a integração com o Slack. Em resumo: basta dar um @Codex com uma frase em um canal do Slack ou em uma thread, e ele criará uma tarefa na nuvem e retornará o resultado na thread quando terminar.

Analogia: É como dar um @ em um colega de trabalho que está sempre disponível no grupo. Você não vai até a mesa dele apenas para fazer uma pergunta — basta dar um @ no grupo, explicar a situação e ele cuidará disso quando vir a mensagem, avisando o grupo sobre o resultado depois. O Codex, após ser integrado ao Slack, torna-se um "membro do grupo" assim: você o @, diz o que precisa, ele faz na nuvem e reporta de volta na thread. E ele consegue ler as mensagens anteriores da thread, então você não precisa explicar todo o contexto novamente.

Configuração: Três etapas para conectar

De acordo com a documentação oficial, conectar ao Slack requer apenas três etapas (se não cumprir todas, ele não poderá começar a trabalhar):

1. Prepare as tarefas na nuvem primeiro. Este é o pré-requisito — você precisa ter um plano Plus, Pro, Business, Enterprise ou Edu (baseado no ChatGPT pricing oficial), uma conta do GitHub conectada e pelo menos um ambiente (environment) configurado. Esses três itens são os mesmos discutidos na versão em nuvem do Artigo 10 e são reutilizados aqui.
2. Instale o Slack app. Vá para a página de conectores (connectors) nas configurações do Codex e instale o Slack app no seu espaço de trabalho. Nota: Dependendo da política do seu espaço de trabalho do Slack, pode ser necessária a aprovação prévia do administrador.
3. Adicione @Codex ao canal. Se ainda não tiver adicionado, o Slack solicitará que você o faça quando tentar dar um @ nele no canal.

Uso: @ ele e diga o que precisa

Depois de conectado, o uso é extremamente direto:

1. Dê um @Codex no canal ou na thread junto com o seu requisito. Ele pode referenciar mensagens anteriores da thread, portanto, geralmente você não precisa repetir o contexto.
2. (Opcional) Especifique o ambiente ou repositório diretamente na mensagem, exemplo oficial: @Codex fix the above in openai/codex.
3. Aguarde a reação 👀 dele, que responderá com um link da tarefa; ao terminar, ele postará o resultado de volta e (dependendo das suas configurações) também dará uma resposta na thread.

Como ele escolhe o ambiente e o repositório por conta própria

Este é o ponto mais fácil de confundir os iniciantes — se você não especificar um repositório, como o Codex sabe em qual repositório trabalhar? A documentação oficial explica claramente:

• O Codex analisará os ambientes para os quais você tem permissão e escolherá o que melhor se adapta às suas necessidades; se a solicitação for muito vaga, ele voltará para o último ambiente que você usou.
• A tarefa será executada na branch padrão do primeiro repositório listado no mapa de repositórios (repo map) daquele ambiente. Se quiser alterar o repositório padrão ou adicionar repositórios, modifique o repo map no Codex.
• Se não houver um ambiente ou repositório adequado, o Codex responderá diretamente no Slack informando "como corrigir", para que você configure e tente novamente.

Portanto, em vez de deixá-lo adivinhar, é melhor nomear diretamente — pela minha experiência, em equipes que lidam com múltiplos repositórios, eu sempre escrevo explicitamente o repositório na mensagem (...in openai/our-backend), evitando que ele escolha o ambiente errado e trabalhe à toa. Uma vez, para poupar esforço, não especifiquei o repositório; ele escolheu um ambiente que usei recentemente, mas que não tinha absolutamente nada a ver com o assunto. O resultado foi que ele passou muito tempo tentando localizar o problema e respondeu algo totalmente fora do contexto, o que deu ainda mais trabalho.

Controle de dados Enterprise: se a resposta deve incluir o "conteúdo do trabalho"

Isso é importante para usuários corporativos. Por padrão, o Codex responderá na thread com uma mensagem que pode conter informações do ambiente em que ele rodou. Se você não quiser que essas informações apareçam no Slack:

Os administradores do Enterprise podem desmarcar "Allow Codex Slack app to post answers on task completion" nas configurações do espaço de trabalho do ChatGPT. Uma vez desativado, o Codex retornará apenas um link da tarefa, sem colar o conteúdo da resposta na thread.

Vamos ilustrar todo esse fluxo do Slack em um diagrama:

O que esta imagem quer mostrar é: dar um @ no Slack inicia um fluxo de "criar contêiner → clonar repositório → Agent trabalha → entregar resultados" que é exatamente igual a enviar uma tarefa na nuvem pelo navegador — a entrada mudou, mas o backend ainda é o mesmo pipeline na nuvem do Artigo 10.

Mãos à obra: Rodando um teste rápido no Slack em alguns minutos

Pré-requisito: Você precisa ser membro de algum espaço de trabalho do Slack, ter permissão para instalar aplicativos (ou ter um administrador disposto a ajudar) e ter o Codex conectado ao GitHub com pelo menos um ambiente configurado (caso contrário, volte ao Artigo 10 para preparar o ambiente de nuvem primeiro). Toda essa integração se conecta ao domínio chatgpt.com; se o acesso local não funcionar, use ferramentas de rede adequadas para conectar.

Primeira etapa: Instalar o app. Vá para a página de conectores (connectors), instale o Slack app e autorize conforme as instruções (pode requerer aprovação do administrador).

Esperado: O aplicativo Codex aparece no seu espaço de trabalho do Slack.

Segunda etapa: Adicioná-lo a um canal. Encontre um canal onde você tenha permissão, dê um @ em @Codex e aceite quando o Slack sugerir adicioná-lo.

Terceira etapa: Delegar uma pequena tarefa que possa ser aceita com uma única frase (lembre-se da lição do Artigo 10 — as descrições de tarefas na nuvem devem ser específicas a ponto de poderem ser aceitas):

@Codex 在 openai/你的练手仓库 里,把根目录的 README 顶部加一行 "Hello from Slack". 别动别的.

Substitua openai/你的练手仓库 pelo repositório no qual você tem permissão de escrita, use um repositório de teste para experimentar, não use um repositório de produção.

Esperado: O Codex primeiro reagirá à sua mensagem com 👀, responderá com uma mensagem contendo o link da tarefa e, depois de um tempo, postará os resultados e o link do diff na thread. Ver o diff aparecer na thread e poder abrir um PR clicando no link = esta integração funcionou. Se ele responder que "não foi possível encontrar um ambiente/repositório adequado", siga as dicas fornecidas para configurar o ambiente e o repo map, e então @ ele novamente.

💡 Resumo em uma frase: Integração com o Slack = dar um @Codex com o requisito no canal/thread, e ele entregará o resultado de volta na thread após rodar na nuvem; os pré-requisitos seguem os três itens da versão em nuvem (plano + GitHub + ambiente), é recomendado especificar o repositório diretamente para evitar suposições, e no Enterprise você pode desativar o conteúdo da resposta, mantendo apenas o link da tarefa.

---

03 Chamar no Linear: Delegar uma issue diretamente para o Codex

Se o Slack é para "chamar na conversa", o Linear é para "chamar na ferramenta de gerenciamento de projetos". Depois de conectar o Linear (uma ferramenta rápida de gerenciamento de issues / projetos) ao Codex, você pode delegar uma issue diretamente como uma tarefa para ele, como se estivesse atribuindo-a a alguém da equipe.

Analogia: É como arrastar um cartão de tarefa diretamente para um executor. No quadro kanban da equipe, há vários cartões de issues. Normalmente, você atribui um cartão a um colega responsável, que o assume, começa a trabalhar e atualiza o progresso no cartão. Após conectar o Codex ao Linear, ele se torna mais um "executor atribuível" — você delega a issue para ele, ele a assume, começa a trabalhar, posta o progresso e os resultados de volta na issue e, por fim, fornece um link para você abrir o PR.

Ele está disponível em planos pagos (baseado no Pricing oficial). No plano Enterprise, o administrador precisa activar as tarefas em nuvem nas configurações do espaço de trabalho e habilitar o Codex for Linear nas configurações do conector (connector).

Configuração: Três etapas

1. Prepare as tarefas na nuvem: Conecte ao GitHub no Codex e configure o ambiente para os repositórios em que deseja trabalhar (os mesmos pré-requisitos de nuvem).
2. Instale o Codex for Linear: Vá para a página de conectores (connectors) e instale no seu espaço de trabalho.
3. Vincule a conta do Linear: Faça um comentário com @Codex em alguma issue do Linear e siga as instruções para vincular.

Duas formas de delegar tarefas

A documentação oficial fornece dois caminhos à sua escolha:

Opção 1: Atribuir a issue ao Codex. Após configurar a integração, você atribui a issue ao Codex da mesma forma que faria com um colega. Ele começará a trabalhar e postará as atualizações de volta na issue.

Opção 2: @Codex nos comentários. Marque-o com um @ no thread de comentários da issue para delegar tarefas ou fazer perguntas. Depois que ele responder, você pode continuar perguntando no mesmo thread para prosseguir com a mesma conversa.

Assim como no Slack, ao iniciar o trabalho, o Codex escolherá o ambiente e o repositório por conta própria (a lógica é quase idêntica: o Linear sugerirá um repositório com base no contexto da issue, e o Codex escolherá o ambiente correspondente mais adequado; se for ambíguo, ele voltará para o último usado). Se quiser fixar um repositório específico, descreva-o claramente no comentário, por exemplo: @Codex fix this in openai/codex.

Existem dois lugares para acompanhar o progresso: abra a aba Activity da issue para ver as atualizações de progresso ou clique no link da tarefa para ver o processo mais detalhado. Quando terminar, o Codex postará um resumo e o link da tarefa na issue, e você poderá clicar no link para abrir o PR.

Distribuição automática: Regras de triagem (triage)

Esta é a parte que considero com maior potencial de inovação na integração com o Linear — permitir que novas issues que atendam aos critérios sejam atribuídas automaticamente ao Codex, sem a necessidade de triagem manual uma a uma. Configuração oficial:

1. Vá em Settings no Linear.
2. Em Your teams, selecione sua equipe.
3. Nas configurações de workflow, ative o Triage (triagem).
4. Em Triage rules, crie uma nova regra, selecione Delegate → Codex (e outros atributos que deseja definir).

Depois de configurado, as novas issues que entrarem na triagem (triage) serão atribuídas automaticamente ao Codex. Há um detalhe importante destacado oficialmente que pode ser facilmente esquecido: ao usar as regras de triagem, o Codex roda as tarefas usando a conta do "criador da issue" — o que significa que o consumo de tokens/cota será cobrado da pessoa que criou a issue, por isso é bom avisar a equipe antes de configurar essa regra.

Outro caminho: Linear MCP (para uso local do Codex)

As integrações com Slack/Linear mencionadas anteriormente pertencem à linha de 'tarefas em nuvem'. Mas se você deseja que o Codex local (App, CLI, extensão de IDE) leia diretamente as issues do Linear — por exemplo, no terminal instruir o Codex a 'modificar o código de acordo com a issue ENG-123' — esse é outro caminho: o Linear MCP server (o Artigo 20 explica o que é o MCP).

A documentação oficial recomenda usar uma única linha no CLI para conectar:

codex mcp add linear --url https://mcp.linear.app/mcp

Este comando solicitará que você faça login na sua conta do Linear e a conecte ao Codex. Você também pode escrever manualmente em ~/.codex/config.toml:

[mcp_servers.linear]
url = "https://mcp.linear.app/mcp"

Depois de escrever, execute codex mcp login linear para fazer login. A extensão de IDE e o CLI compartilham essa mesma configuração, configure uma vez e estará disponível em ambos (o que está de acordo com o Artigo 20).

Não confunda esses dois caminhos: Dar um @Codex no site do Linear para delegar tarefas = tarefa na nuvem; conectar ao Linear MCP = permitir que o Codex local leia os dados do Linear. Um é "o Codex indo ao Linear para trabalhar", o outro é "o Codex local usando o Linear como fonte de dados".

Vamos comparar os dois pontos de entrada de "chamada em nuvem", Slack e Linear:

Dimensão	Integração com Slack	Integração com Linear
Método de chamada	@Codex na thread	Atribuição de issue / @Codex nos comentários
Distribuição automática	——	✅ Regras de triage podem atribuir automaticamente
Origem do contexto	Histórico de mensagens da thread	Conteúdo da issue + Comentários
Onde o resultado é retornado	De volta na thread + Link da tarefa	De volta na issue (Activity / Comentários) + Link da tarefa
Backend	Ambas são tarefas na nuvem (criar contêiner → clonar repositório → entregar diff)	Igual ao lado
Outras formas de uso local	——	✅ Linear MCP (permite ao Codex local ler as issues)

Minha experiência pessoal: O Slack é adequado para tarefas do tipo "ideia repentina, repassar na hora" (ver um erro e dar um @ rapidamente), enquanto o Linear é adequado para tarefas que "já seguem um fluxo no sistema de chamados" — especialmente a distribuição automática por regras de triagem (triage). Uma vez ativada, aquelas "issues de pequenos bugs simples de resolver" podem ser direcionadas automaticamente para o Codex rodar uma primeira versão, deixando para as pessoas apenas o trabalho de review, o que acelera o ritmo da equipe de forma significativa.

💡 Resumo em uma frase: A integração com o Linear suporta duas formas de delegar tarefas: atribuir a issue ou usar @Codex nos comentários, além de permitir distribuição automática com regras de triagem (triage) (lembrando que roda com a conta do criador da issue); ele funciona com tarefas em nuvem no backend assim como o Slack, havendo outro caminho do Linear MCP para o Codex local ler as issues, que não deve ser confundido com a chamada em nuvem.

---

04 Codex SDK: Escrever código para embutir o Codex em seus próprios programas

Depois de falar sobre "usar pontos de entrada prontos de outras pessoas" (Slack/Linear), entramos agora na "construção do seu próprio ponto de entrada" — o Codex SDK (Software Development Kit, um conjunto de bibliotecas que permite programar e controlar o funcionamento do Codex em seus programas).

Primeiramente, qual problema ele resolve? O codex exec do Artigo 28 já permite chamar o Codex em scripts, mas o exec é essencialmente "digitar um comando e analisar a sua saída". Tentar controlar tudo detalhadamente no seu programa — iniciar uma sessão, fazer várias perguntas seguidas e obter resultados estruturados — torna-se um pouco desajeitado. O SDK existe exatamente para isso. A descrição oficial define claramente seu posicionamento:

A biblioteca TypeScript fornece uma maneira de controlar o Codex no seu aplicativo, sendo mais abrangente e flexível do que o modo não interativo.

Quando você deve usar o SDK? A documentação oficial lista quatro cenários; se você se enquadrar em qualquer um deles, vale a pena adotá-lo:

• Integrar o Codex em seus pipelines de CI/CD
• Criar um agent capaz de chamar o Codex para executar tarefas de engenharia complexas
• Embutir o Codex em suas próprias ferramentas internas e fluxos de trabalho
• Integrar o Codex em seu próprio aplicativo

Analogia: É como evoluir de "apertar botões no controle remoto" para "obter uma chave mestra e o manual de instruções". O codex exec funciona como um controle remoto com funções fixas — você o pressiona, ele roda uma vez e faz apenas algumas coisas. O SDK coloca a "interface de controle" da máquina do Codex diretamente nas suas mãos: você pode usar código para abrir um thread de conversa, rodar uma iteração, obter o resultado, continuar rodando a próxima iteração no mesmo thread e até mesmo alterar as permissões de sandbox desta iteração — a granularidade é muito mais fina, porque você o está controlando diretamente em seu programa.

Duas linguagens: TypeScript e Python

O Codex SDK é disponibilizado oficialmente em duas versões, permitindo que você escolha com base na linguagem do seu projeto. Contudo, há diferenças importantes entre as duas versões, não tire conclusões precipitadas (totalmente baseado na documentação oficial, sem invenções):

	TypeScript	Python
Comando de instalação	npm install @openai/codex-sdk	pip install openai-codex
Ambiente requerido	Node.js 18+	Python 3.10+
Onde roda	Lado do servidor (server-side)	Controla o app-server local
Mecanismo de backend	——	Controla o Codex app-server local via JSON-RPC
Maturidade	——	Fase beta (com armadilhas abaixo)

Destacamos alguns pontos explicitamente descritos de forma oficial onde é fácil cometer erros:

A versão em TypeScript deve ser usada no lado do servidor e requer Node.js 18 ou superior. Não tente executá-la no navegador.

A versão em Python está em beta e requer atenção ao instalar. A documentação oficial explica claramente: durante a fase beta, pip install openai-codex instala a versão beta publicada mais recente; quando a versão estável estiver disponível no futuro, se você quiser continuar experimentando as versões de pré-lançamento mais recentes, deverá usar pip install --pre openai-codex. Além disso, o pacote SDK publicado vem com um runtime do Codex CLI com versão fixada — geralmente você não precisa se preocupar com isso, a menos que queira intencionalmente fazê-lo rodar um executável específico do Codex local, passando CodexConfig(codex_bin=...).

Na primeira vez que instalei a versão em Python, quase cometi um erro — assumi subconscientemente que o nome do pacote seria semelhante ao nome do SDK, como codex-sdk, mas no final o nome instalado pelo pip era openai-codex. O nome do pacote deve seguir o oficial, não tente adivinhar com base no TypeScript, os nomes são assimétricos (TypeScript é @openai/codex-sdk, Python é openai-codex).

Como é a estrutura do menor código

Versão em TypeScript — abre um thread, roda um comando, obtém o resultado (exemplo oficial, a linha de importação foi adicionada conforme o pacote oficial):

import { Codex } from "@openai/codex-sdk";

const codex = new Codex();
const thread = codex.startThread();
const result = await thread.run(
  "Make a plan to diagnose and fix the CI failures"
);

console.log(result);

Se quiser continuar no mesmo thread, chame run() novamente; se quiser continuar conversando em um thread anterior, restaure-o com o ID do thread:

// 同一个线程上继续
const result = await thread.run("Implement the plan");
console.log(result);

// 恢复一个过去的线程
const threadId = "<thread-id>";
const thread2 = codex.resumeThread(threadId);
const result2 = await thread2.run("Pick up where you left off");
console.log(result2);

Versão em Python — estrutura semelhante, usando with para gerenciar o ciclo de vida:

from openai_codex import Codex, Sandbox

with Codex() as codex:
    thread = codex.thread_start(
        model="gpt-5.4",
        sandbox=Sandbox.workspace_write,
    )
    result = thread.run("Make a plan to diagnose and fix the CI failures")
    print(result.final_response)

O model="gpt-5.4" acima é apenas um exemplo de escrita oficial. O nome real do modelo varia com a versão e deve seguir o oficial, não o escreva de forma estática.

Se a própria aplicação já for assíncrona, use AsyncCodex:

import asyncio
from openai_codex import AsyncCodex

async def main() -> None:
    async with AsyncCodex() as codex:
        thread = await codex.thread_start(model="gpt-5.4")
        result = await thread.run("Implement the plan")
        print(result.final_response)

asyncio.run(main())

Sandbox: Usando presets para controlar as permissões de acesso

Seguindo a mesma linha do CLI/nuvem (o Artigo 15 fala sobre o sandbox), o Python SDK usa presets de Sandbox para controlar as permissões do sistema de arquivos do Codex. Isso é definido ao iniciar o thread e também pode ser alterado temporariamente em uma iteração posterior:

from openai_codex import Codex, Sandbox

with Codex() as codex:
    thread = codex.thread_start(sandbox=Sandbox.workspace_write)
    thread.run("Make the requested change.")
    review = thread.run("Review the diff only.", sandbox=Sandbox.read_only)

Três presets (conforme o oficial):

preset	O que ele pode fazer
Sandbox.read_only	Apenas leitura de arquivos, escrita não permitida
Sandbox.workspace_write	Leitura de arquivos + escrita no espaço de trabalho e diretórios configurados como graváveis
Sandbox.full_access	Execução sem restrições de acesso ao sistema de arquivos

Há aqui um comportamento padrão oficial que vale a pena lembrar: se você não passar sandbox=, o app-server usará seu próprio valor padrão configurado (não uma configuração fixa codificada). Além disso, assim que você passar um sandbox no run(...) de uma determinada iteração, ele será aplicado a essa iteração e às iterações subsequentes deste thread — não apenas para essa vez. O exemplo acima demonstra justamente essa alteração de permissão a cada iteração: primeiro altera as coisas com workspace_write e depois muda para read_only apenas para revisar o diff.

Qual é a real diferença entre o SDK e o codex exec

Este é o ponto principal que precisa ser esclarecido ao migrar do Artigo 28. Em resumo: o exec é para "executar comandos únicos e analisar a saída", enquanto o SDK permite "manter uma sessão ativa no seu programa, com iterações sequenciais e ajuste de permissões conforme necessário".

Dimensão de comparação	codex exec (Artigo 28)	Codex SDK
Formato	Uma linha de comando	Biblioteca dentro do programa
Como usar	Digitar comando, ler stdout	Escrever código para chamar após o import
Continuidade da sessão	Depende de resume para continuar	Um objeto thread, chamando run() para múltiplas iterações
Obter resultados	Analisar texto / eventos --json	Obter diretamente o objeto de retorno (como final_response)
Ajustar permissões	Flag na linha de comando	Passar preset de sandbox no código, alterável a cada iteração
Adequado para	Casos simples de "enviar e rodar até o fim"	Controle detalhado no programa, criação de agents, incorporação em produtos

Regra prática: Se você quer apenas "fazer o Codex rodar e extrair o resultado" in um script — o codex exec é suficiente; se você precisa abrir sessões, fazer perguntas consecutivas no programa e controlar cada passo de acordo com a lógica do negócio — adote o SDK.

💡 Resumo em uma frase: O Codex SDK permite usar código para abrir threads, realizar iterações sequenciais com o Codex e controlar o sandbox a cada iteração — a versão para TS é @openai/codex-sdk (Node 18+, lado do servidor) e a para Python é openai-codex (3.10+, beta, rodando o app-server por baixo); ele tem uma granularidade de controle muito mais fina do que o codex exec, os nomes dos pacotes nas duas versões são assimétricos, e o nome do modelo deve seguir as orientações oficiais.

---

05 App Server: Apenas para integrações profundas

A última ferramenta, e também a de mais baixo nível e menos propensa a ser tocada diretamente neste artigo — é o App Server. Vamos definir seu posicionamento em uma frase: o App Server é a interface usada pelo Codex para rodar "clientes ricos" (como a extensão oficial do Codex para o VS Code), devendo ser usado apenas quando você deseja fazer uma integração profunda em seu próprio produto.

O que ele oferece? Palavras oficiais: autenticação, histórico de conversas, aprovações e fluxo de eventos do agent — exatamente o que uma extensão de IDE ou um cliente GUI de respeito precisam.

Analogia: O SDK é o "motor montado", enquanto o App Server é "o conjunto completo de fiação do motor". A maioria das pessoas quer apenas um motor pronto para uso (SDK) — conectá-lo, enviar instruções e fazê-lo rodar. Mas se você está construindo um carro completo e precisa lidar com a fiação, painel e sistema de controle (histórico de conversas, pop-ups de aprovação, fluxo de eventos em tempo real), então o que você precisa é dessa fiação de baixo nível — o App Server expõe todos os sinais internos do Codex via JSON-RPC, permitindo que você monte uma experiência de cliente completa por conta própria.

Tecnicamente, ele é semelhante ao MCP — utilizando mensagens JSON-RPC 2.0 para comunicação bidirecional, rodando por padrão via stdio (entrada/saída padrão). Inicializar também é simples:

codex app-server

Seus conceitos principais são coerentes com o que vimos antes:

• Thread: Uma conversa entre o usuário e o Codex agent, contendo várias turns.
• Turn: Uma requisição do usuário + o trabalho subsequente do agent, gerando atualizações incrementais em tempo real (streaming).
• Item: Uma unidade de entrada/saída (mensagem do usuário, mensagem do agent, execução de comando, alteração de arquivo, chamada de ferramenta...).

Todo o ciclo de vida funciona assim: "inicializar uma vez para cada conexão → abrir/restaurar um thread → iniciar uma turn → ler continuamente notificações em streaming (início/fim de item, incrementos de mensagem, progresso da ferramenta...) → turn concluída". Resumindo, você precisa gerenciar todo esse tráfego de JSON-RPC de ida e volta por conta própria — e é por isso que ele é o caminho "de mais baixo nível e mais trabalhoso".

Afinal, quando devemos usar o App Server e quando devemos usar o SDK? A documentação oficial traz uma frase extremamente direta que define essa fronteira:

Se você está rodando o Codex em tarefas automatizadas ou em CI, use o Codex SDK, não o App Server.

Portanto, a regra de decisão é bem clara:

O que você deseja fazer	Qual usar
Tarefas automatizadas, CI, escrever scripts para chamar o Codex	SDK
Criar um agent para chamar o Codex e realizar tarefas	SDK
Criar integrações profundas como extensões de IDE / clientes GUI (requerendo histórico de conversas, tela de aprovação, fluxo de eventos em tempo real)	App Server

Conclusão para a grande maioria: Provavelmente você não precisará do App Server, o SDK já basta. Ele é voltado para equipes que constroem "integrações profundas de nível de produto" (por exemplo, se você deseja criar seu próprio cliente gráfico para o Codex). Não comece focando no App Server logo de início, isso trará uma complexidade desnearia para você. Primeiro use o SDK para validar sua ideia; apenas se chegar a um ponto onde "o SDK não puder atender às necessidades e for essencial controlar cada evento individualmente", considere adotá-lo.

Sua implementação é código aberto (disponível no repositório GitHub do Codex). Se você realmente quiser se aprofundar, pode dar uma olhada no código-fonte — mas esse já é um trabalho em outro patamar de complexidade, por isso ficamos por aqui neste artigo.

💡 Resumo em uma frase: O App Server é a interface JSON-RPC de baixo nível usada pelo Codex para rodar clientes ricos (como extensões do VS Code), projetado para "integrações profundas de nível de produto"; a documentação oficial indica expressamente o uso do SDK em vez dele para automações/CI, e a maioria das pessoas não precisará usá-lo — comece validando com o SDK e não mexa nisso de primeira.

---

06 Mãos à obra: Rodando um programa SDK mínimo em 5 minutos

Apenas ler não trará experiência prática. Esta seção guiará você para rodar passo a passo o menor programa Codex SDK possível — fazendo com que ele leia o diretório atual e dê um resumo em uma frase. A demonstração é feita em TypeScript (que roda no lado do servidor e possui o fluxo mais direto). Não requer nenhuma dependência de projetos complexos que você já tenha.

Pré-requisito: Node.js 18+ (o comando node -v deve retornar a versão) e você já deve estar usando o Codex normalmente (instalado e logado, consulte o Artigo 03). A chamada do SDK fará com que o Codex execute trabalhos e exigirá conexão com a internet; certifique-se de configurar sua conexão de rede adequadamente, se necessário.

Primeira etapa: Criar um diretório vazio e inicializar

mkdir codex-sdk-demo
cd codex-sdk-demo
npm init -y

Segunda etapa: Instalar o SDK

npm install @openai/codex-sdk

Esperado: O npm imprimirá no final added ... package(s) e o diretório node_modules conterá @openai/codex-sdk. Ver o pacote instalado = SDK pronto.

Terceira etapa: Criar um arquivo no diretório para leitura

Crie um novo arquivo hello.txt e escreva qualquer linha, por exemplo:

This project is a tiny demo for the Codex SDK.

Quarta etapa: Escrever o programa mínimo

Crie o arquivo run.mjs (usamos a extensão .mjs para suportar await no escopo global/top-level) e cole este trecho de código:

import { Codex } from "@openai/codex-sdk";

const codex = new Codex();
const thread = codex.startThread();
const result = await thread.run(
  "Read hello.txt in the current directory and summarize it in one sentence."
);

console.log(result);

Este trecho de código é a mesma estrutura explicada na seção 04: cria uma instância com new Codex(), abre um thread com startThread(), roda o comando com thread.run(...) e imprime o resultado.

Quinta etapa: Executar o programa

node run.mjs

Esperado: O terminal levará um tempo para processar (com o Codex trabalhando localmente ou na nuvem) e, por fim, imprimirá o resultado retornado por run() — que deve conter o resumo em uma frase que ele gerou a partir da linha do arquivo hello.txt. Ver a saída contendo o resumo do conteúdo do arquivo = todo o fluxo funcionou.

Se for reportado algum erro relacionado a login/autenticação, significa que o Codex em si ainda não está logado — volte ao Artigo 03 para concluir o fluxo de codex login; se houver problemas de rede, verifique as configurações de sua conexão. Os detalhes sobre como é o objeto retornado e quais campos ele possui devem seguir a documentação oficial e as definições de tipo do SDK, pois este artigo valida apenas o fluxo principal de "executar com sucesso e obter o resultado".

Ao concluir essa execução, você terá percorrido manualmente toda a estrutura básica de "instalar o SDK → abrir thread → rodar uma iteração com run() → obter resultado". O núcleo de qualquer integração futura do SDK será exatamente este — bastando apenas mudar os prompts, chamar mais iterações de run(), configurar o sandbox conforme necessário e integrar os resultados à lógica de negócios do seu próprio sistema. Se desejar criar interações consecutivas (por exemplo, pedir para ele gerar um plano primeiro e depois implementá-lo), continue chamando run() no mesmo objeto thread, exatamente como no exemplo da seção 04.

💡 Resumo em uma frase: Rodar o programa SDK mínimo requer apenas cinco etapas — criar diretório e inicializar, instalar @openai/codex-sdk, criar um arquivo para leitura, escrever new Codex() → startThread() → run(), e executar com node; fazer o processo na prática é muito mais útil do que memorizar dez APIs.

---

07 Qual escolher afinal: Identifique o seu perfil

Por fim, uma recomendação sincera para ajudar você a se posicionar, evitando aprender o que não é necessário. Dentre as quatro ferramentas explicadas neste artigo, a grande maioria das pessoas usará apenas uma ou duas, não tente abranger tudo de uma vez.

A decisão é muito simples. Basta fazer a si mesmo duas perguntas: ① Eu preciso escrever código? ② Se sim, será apenas para chamadas simples ou para fazer uma integração profunda?

Sua necessidade	O que usar	Por quê
"Quero repassar tarefas rapidamente no chat de equipe para o Codex"	Integração com Slack	Zero código, basta usar um @
"Quero direcionar issues do gerenciador de projetos para o Codex, ou até distribuí-las automaticamente"	Integração com Linear	Zero código, com suporte à distribuição automática com triage
"Quero que o Codex local leia diretamente as issues do Linear para trabalhar"	Linear MCP	Esse é um uso local, não uma chamada na nuvem
"Quero incluir o Codex em scripts/CI, rodar de forma simples e obter o resultado"	codex exec (Artigo 28)	Mais leve, apenas um comando
"Quero controlar o Codex detalhadamente em programas, criar agents ou incorporá-lo em produtos"	Codex SDK	Permite abrir sessões, iterações sequenciais e ajuste de permissões a cada rodada
"Quero criar integrações profundas, como extensões de IDE ou clientes GUI"	App Server	Comunicação JSON-RPC de baixo nível, permitindo que você mesmo monte o cliente

Gostaria de destacar algumas lições aprendidas pela experiência:

Não use o SDK para tarefas que o exec pode fazer. Já vi desenvolvedores que queriam apenas "rodar uma verificação no CI com o Codex" e começaram a importar o SDK, escrevendo uma série de códigos assíncronos — quando na verdade bastava uma linha de codex exec com a flag --json (Artigo 28). Quanto mais simples o requisito, mais você deve optar por ferramentas mais leves.

E também não use o App Server para tarefas que o SDK resolve. A documentação oficial já diz claramente "use o SDK em vez do App Server para automações/CI". Tentar descer ao nível do JSON-RPC para lidar com todo o ciclo de vida por conta própria é apenas criar problemas para si mesmo.

Slack/Linear e SDK/App Server não são opções do mesmo escopo. Las duas primeiras servem para "usar o Codex nos produtos de terceiros" (zero código), enquanto as duas últimas servem para "incorporar o Codex no seu próprio produto" (escrevendo código). Você pode perfeitamente usar ambos — sua equipe usa o @Codex no Slack no dia a dia para tarefas rápidas, enquanto você implementa o Codex em sua ferramenta interna usando o SDK. Eles não entram em conflito.

Minha distribuição real ao longo deste ano foi: o @Codex no Slack é o que mais utilizo (repassar tarefas de forma rápida é muito prático), o codex exec foi inserido em alguns scripts de CI, o SDK foi usado uma vez ao criar uma pequena ferramenta interna e nunca precisei mexer no App Server — ele realmente é voltado para equipes que fazem integrações profundas de produto. Se você for iniciante ou desenvolvedor solo, comece usando soluções de zero código como Slack/Linear e, quando surgir a necessidade de programar, adote o exec e o SDK, este é o caminho mais tranquilo.

💡 Resumo em uma frase: Use Slack/Linear para chamada com zero código, o Linear MCP para leitura local do Linear, o exec para execuções simples via scripts, o SDK para controle detalhado no programa e o App Server apenas para integrações profundas de produto; quanto mais simples a necessidade, mais leve deve ser a ferramenta, e a maioria das pessoas nunca precisará tocar no App Server na vida.

---

08 Resumo

Este artigo detalhou as duas frentes: "chamar o Codex em outros locais" e "embutir o Codex em seus próprios produtos" — o Codex deixou de ficar restrito apenas ao seu terminal, podendo ser levado para o chat e o sistema de chamados da sua equipe, além de ser incorporado aos programas desenvolvidos por você.

Compilando os pontos principais:

O que você deseja esclarecer	Resposta	Ponto-chave em uma frase
Como usar o Slack	Delegar tarefas com @Codex na thread	Por baixo roda tarefas na nuvem, herdando plano + GitHub + ambiente
Como usar o Linear	Atribuição de issue / @Codex nos comentários	Suporta distribuição automática com triage, rodando sob a conta de quem criou a issue
Fazer o Codex local ler o Linear	Linear MCP	codex mcp add linear --url ..., não confunda com a chamada na nuvem
O que é o SDK	Biblioteca para controlar o Codex programaticamente	TS @openai/codex-sdk / Python openai-codex (beta)
Diferença entre SDK e exec	Continuidade da sessão + Granularidade de controle	exec roda de uma vez, SDK abre sessões para múltiplas iterações e ajusta o sandbox a cada rodada
O que é o App Server	Interface JSON-RPC de baixo nível	Usado apenas para integrações profundas; a documentação indica o SDK para automação/CI

Agora você deve ser capaz de: Distinguir os dois níveis: "chamar com zero código (Slack/Linear)" e "embutir escrevendo código (SDK/App Server)"; delegar tarefas ao Codex no Slack e no Linear, sabendo que o Linear suporta distribuição automática por regras de triagem (triage) e conexão via MCP para uso local. Entender como escolher entre as duas linguagens do Codex SDK, a estrutura do código mínimo e qual a diferença entre ele e o codex exec; e saber que o App Server foi projetado para integrações profundas, sendo o SDK suficiente para a maioria das pessoas. Mais importante ainda, você agora sabe qual ferramenta atende melhor ao seu perfil — o que é muito mais valioso do que tentar aprender tudo de uma vez sem critério.

A esta altura, o Codex deixou de ser apenas "uma ferramenta de linha de comando" e passou a ser "um conjunto de capacidades de agente que pode ser chamado de qualquer lugar ou incorporado a qualquer produto".

💡 Resumo em uma frase: Use Slack/Linear para chamadas com zero código, o SDK para embutir com código e o App Server apenas para integrações profundas de produto — identifique em qual nível você se encontra e evite aprender na direção errada.

---

O próximo artigo 〔30 Como Escolher Modelos〕 — não importa se você está usando o @Codex no Slack ou escrevendo programas com o SDK, há uma questão inevitável que ainda não detalhamos: afinal, qual modelo deve ser enviado para realizar o trabalho? Você provavelmente notou que o exemplo do SDK requer o preenchimento de model=..., o CLI possui --model e é possível alternar instantaneamente com /model — mas "se a tarefa deve ser atribuída a um modelo mais forte ou mais rápido, ou qual o nível de intensidade de raciocínio a ser ajustado", ainda não foi explicado. O próximo artigo detalhará justamente isso: quais são os perfis de cada um desses modelos por trás do Codex, qual tarefa se adapta a qual modelo e como encontrar o equilíbrio ideal entre 'rápido e econômico' e 'forte e preciso'. Pense primeiro: dentre as tarefas que você delegou recentemente ao Codex, quais delas poderiam ter sido resolvidas por um modelo mais rápido e barato?

---

Leituras recomendadas

• Conectar ferramentas externas com MCP: Adicionando "portas externas" ao Codex
• Integração com Git e GitHub: Deixe o Codex atuar como revisor nos seus PRs
• Explicação detalhada da configuração config.toml: Um único arquivo para controlar todos os botões