App Server | Criar com o Codex | Documentação do ChatGPT

O Codex app-server é a interface que o Codex utiliza para disponibilizar clientes avançados (por exemplo, a extensão Codex para o VS Code). Utilize-o quando pretender uma integração profunda no seu próprio produto: autenticação, histórico de conversas, aprovações e eventos transmitidos do agente. A implementação do app-server é de código aberto e está disponível no repositório do Codex no GitHub (openai/codex/codex-rs/app-server). Consulte a página Código aberto para ver a lista completa de componentes de código aberto do Codex.

Ligar a interface de terminal da CLI

O modo de interface de terminal remota permite executar o app-server num computador e ligar a interface de terminal da Codex CLI a partir de outro. Inicie um serviço de escuta WebSocket:

codex app-server --listen ws://127.0.0.1:4500

Em seguida, ligue a interface de terminal:

codex --remote ws://127.0.0.1:4500

Para uma ligação não local, configure a autenticação WebSocket e coloque a ligação atrás de TLS. Guarde o token de portador numa variável de ambiente e passe o respetivo nome, em vez de colocar o token na linha de comandos:

export CODEX_REMOTE_TOKEN="$(cat "$HOME/.codex/app-server-token")"
codex --remote wss://remote-host:4500 \
  --remote-auth-token-env CODEX_REMOTE_TOKEN

A opção --remote aceita pontos finais ws://, wss://, unix:// e unix://PATH. Utilize WebSockets simples apenas para localhost ou para uma ligação reencaminhada por porta SSH.

Ligar um anfitrião remoto do Code Mode

Por predefinição, o app-server inicia um anfitrião local do Code Mode. Para utilizar antes um anfitrião remoto, passe o respetivo URL WebSocket seguro:

codex app-server --code-mode-host wss://code-mode.example.com/host

--code-mode-host controla a ligação de saída do app-server ao respetivo anfitrião do Code Mode. Não altera --listen, que controla a forma como os clientes se ligam ao app-server. Todas as threads no mesmo processo do app-server partilham a ligação selecionada ao anfitrião do Code Mode.

Utilize wss:// para um anfitrião remoto. Utilize ws:// apenas para uma ligação localhost ou reencaminhada por SSH. O comando app-server e o transporte WebSocket são experimentais e não são suportados para cargas de trabalho de produção.

Protocolo

Tal como o MCP, codex app-server suporta comunicação bidirecional através de mensagens JSON-RPC 2.0 (com o cabeçalho "jsonrpc":"2.0" omitido durante a transmissão).

Transportes suportados:

stdio (--listen stdio://, predefinição): JSON delimitado por novas linhas (JSONL).
websocket (--listen ws://IP:PORT, experimental e não suportado): uma mensagem JSON-RPC por trama de texto WebSocket.
Socket Unix (--listen unix:// ou --listen unix://PATH): ligações WebSocket através do socket de controlo app-server predefinido do Codex ou de um socket Unix personalizado, utilizando a negociação HTTP Upgrade padrão.
off (--listen off): não expor um transporte local.

Quando executa com --listen ws://IP:PORT, o mesmo serviço de escuta também disponibiliza sondas básicas de estado HTTP:

GET /readyz devolve 200 OK assim que o serviço de escuta aceita novas ligações.
GET /healthz devolve 200 OK quando o pedido não inclui um cabeçalho Origin.
Os pedidos com um cabeçalho Origin são rejeitados com 403 Forbidden.

O transporte WebSocket é experimental e não é suportado. Serviços de escuta locais, como ws://127.0.0.1:PORT, são adequados para fluxos de trabalho com localhost e reencaminhamento de portas SSH. Atualmente, durante a implementação gradual, os serviços de escuta WebSocket que não sejam de loopback permitem ligações não autenticadas por predefinição; por isso, configure a autenticação WebSocket antes de expor um remotamente.

Sinalizadores de autenticação WebSocket suportados:

--ws-auth capability-token --ws-token-file /absolute/path
--ws-auth capability-token --ws-token-sha256 HEX
--ws-auth signed-bearer-token --ws-shared-secret-file /absolute/path

Para tokens de portador assinados, também pode definir --ws-issuer, --ws-audience e --ws-max-clock-skew-seconds. Os clientes apresentam a credencial como Authorization: Bearer <token> durante a negociação WebSocket, e o app-server aplica a autenticação antes do initialize JSON-RPC.

Prefira --ws-token-file em vez de passar tokens de portador em bruto na linha de comandos. Utilize --ws-token-sha256 apenas quando o cliente mantiver o token em bruto de alta entropia num armazenamento de segredos local separado; o hash é apenas um verificador, e os clientes continuam a necessitar do token original.

No modo WebSocket, o app-server utiliza filas limitadas. Quando a entrada de pedidos está cheia, o servidor rejeita novos pedidos com o código de erro JSON-RPC -32001 e a mensagem "Server overloaded; retry later." Os clientes devem tentar novamente com um atraso exponencialmente crescente e com variação aleatória.

Esquema das mensagens

Os pedidos incluem method, params e id:

{ "method": "thread/start", "id": 10, "params": { "model": "gpt-5.6-terra" } }

As respostas repetem o id com result ou error:

{ "id": 10, "result": { "thread": { "id": "thr_123" } } }

{ "id": 10, "error": { "code": 123, "message": "Something went wrong" } }

As notificações omitem id e utilizam apenas method e params:

{ "method": "turn/started", "params": { "turn": { "id": "turn_456" } } }

Pode gerar um esquema TypeScript ou um pacote JSON Schema a partir da CLI. Cada saída é específica da versão do Codex executada, pelo que os artefactos gerados correspondem exatamente a essa versão:

codex app-server generate-ts --out ./schemas
codex app-server generate-json-schema --out ./schemas

Introdução

Inicie o servidor com codex app-server (transporte stdio predefinido), codex app-server --listen ws://127.0.0.1:4500 (WebSocket TCP) ou codex app-server --listen unix:// (socket Unix predefinido).
Ligue um cliente através do transporte selecionado e, em seguida, envie initialize seguido da notificação initialized.
Inicie uma thread e um turno e, depois, continue a ler as notificações do fluxo de transporte ativo.

Exemplo (Node.js / TypeScript):




const proc = spawn("codex", ["app-server"], {
  stdio: ["pipe", "pipe", "inherit"],
});
const rl = readline.createInterface({ input: proc.stdout });

const send = (message: unknown) => {
  proc.stdin.write(`${JSON.stringify(message)}\n`);
};

let threadId: string | null = null;

rl.on("line", (line) => {
  const msg = JSON.parse(line) as any;
  console.log("server:", msg);

  if (msg.id === 1 && msg.result?.thread?.id && !threadId) {
    threadId = msg.result.thread.id;
    send({
      method: "turn/start",
      id: 2,
      params: {
        threadId,
        input: [{ type: "text", text: "Summarize this repo." }],
      },
    });
  }
});

send({
  method: "initialize",
  id: 0,
  params: {
    clientInfo: {
      name: "my_product",
      title: "My Product",
      version: "0.1.0",
    },
  },
});
send({ method: "initialized", params: {} });
send({ method: "thread/start", id: 1, params: { model: "gpt-5.6-terra" } });

Primitivas fundamentais

Thread: uma conversa entre um utilizador e o agente Codex. As threads contêm turnos.
Turno: um único pedido do utilizador e o trabalho do agente que se segue. Os turnos contêm itens e transmitem atualizações incrementais.
Item: uma unidade de entrada ou saída (mensagem do utilizador, mensagem do agente, execuções de comandos, alteração de ficheiros, chamada de ferramenta e muito mais).

Utilize as API de threads para criar, listar ou arquivar conversas. Conduza uma conversa com as API de turnos e transmita o progresso através de notificações de turnos.

Visão geral do ciclo de vida

Inicializar uma vez por ligação: imediatamente após abrir uma ligação de transporte, envie um pedido initialize com os metadados do cliente e, em seguida, emita initialized. O servidor rejeita qualquer pedido nessa ligação antes desta negociação.
Iniciar (ou retomar) uma thread: chame thread/start para uma nova conversa, thread/resume para continuar uma existente ou thread/fork para ramificar o histórico num novo id de thread.
Iniciar um turno: chame turn/start com o threadId de destino e a entrada do utilizador. Os campos opcionais substituem o modelo, a personalidade, cwd, a política de sandbox e outros elementos.
Orientar um turno ativo: chame turn/steer para acrescentar a entrada do utilizador ao turno atualmente em curso sem criar um novo turno.
Transmitir eventos: após turn/start, continue a ler notificações no stdout: thread/archived, thread/unarchived, item/started, item/completed, item/agentMessage/delta, o progresso das ferramentas e outras atualizações.
Concluir o turno: o servidor emite turn/completed com o estado final quando o modelo termina ou após um cancelamento turn/interrupt.

Inicialização

Os clientes têm de enviar um único pedido initialize por ligação de transporte antes de invocarem qualquer outro método nessa ligação e, em seguida, confirmar com uma notificação initialized. Os pedidos enviados antes da inicialização recebem um erro Not initialized, e chamadas initialize repetidas na mesma ligação devolvem Already initialized.

O servidor devolve a cadeia do agente do utilizador que apresentará aos serviços a montante, bem como os valores platformFamily e platformOs que descrevem o destino de execução. Defina clientInfo para identificar a sua integração.

initialize.params.capabilities também suporta estas capacidades do cliente:

optOutNotificationMethods - nomes exatos dos métodos de notificação a suprimir nesta ligação. A correspondência é exata (sem carateres universais nem prefixos); os nomes desconhecidos são aceites e ignorados.
requestAttestation - aderir ao pedido attestation/generate iniciado pelo servidor. Os anfitriões de computador que fornecem atestação a montante respondem com um valor { "token": "..." } opaco.
mcpServerOpenaiFormElicitation - permitir que servidores MCP a jusante enviem a variante de formato expandido da OpenAI de mcpServer/elicitation/request.

Importante: utilize clientInfo.name para identificar o seu cliente na OpenAI Compliance Logs Platform. Se estiver a desenvolver uma nova integração do Codex destinada a utilização empresarial, contacte a OpenAI para que esta seja adicionada a uma lista de clientes conhecidos. Para obter mais contexto, consulte a referência de registos do Codex.

Exemplo (da extensão Codex para o VS Code):

{
  "method": "initialize",
  "id": 0,
  "params": {
    "clientInfo": {
      "name": "codex_vscode",
      "title": "Codex VS Code Extension",
      "version": "0.1.0"
    }
  }
}

Exemplo com exclusão de notificações:

{
  "method": "initialize",
  "id": 1,
  "params": {
    "clientInfo": {
      "name": "my_client",
      "title": "My Client",
      "version": "0.1.0"
    },
    "capabilities": {
      "experimentalApi": true,
      "optOutNotificationMethods": ["thread/started", "item/agentMessage/delta"]
    }
  }
}

Adesão à API experimental

Alguns métodos e campos do app-server estão intencionalmente condicionados pela capacidade experimentalApi.

Omita capabilities (ou defina experimentalApi como false) para permanecer na superfície estável da API; o servidor rejeitará os métodos/campos experimentais.
Defina capabilities.experimentalApi como true para ativar métodos e campos experimentais.

{
  "method": "initialize",
  "id": 1,
  "params": {
    "clientInfo": {
      "name": "my_client",
      "title": "My Client",
      "version": "0.1.0"
    },
    "capabilities": {
      "experimentalApi": true
    }
  }
}

Se um cliente enviar um método ou campo experimental sem aderir, o app-server rejeita-o com:

<descriptor> requires experimentalApi capability

Visão geral da API

thread/start - cria uma nova thread; emite thread/started e subscreve-o automaticamente aos eventos de turnos/itens dessa thread.
thread/resume - reabre uma thread existente por id, para que chamadas turn/start posteriores sejam acrescentadas à mesma.
thread/fork - bifurca uma thread num novo id de thread, copiando o histórico armazenado. Passe lastTurnId para copiar o histórico até esse turno e omitir os turnos posteriores, ou ephemeral: true para criar uma bifurcação na memória. Emite thread/started para a nova thread; as threads devolvidas incluem forkedFromId quando disponível.
thread/read - lê uma thread armazenada por id sem a retomar; defina includeTurns para devolver o histórico completo de turnos. Os objetos thread devolvidos incluem status de execução.
thread/list - percorre por páginas os registos de threads armazenados; suporta paginação baseada em cursor, além de modelProviders, sourceKinds, archived, isPinned, cwd, useStateDbOnly, searchTerm e os filtros experimentais parentThreadId ou ancestorThreadId. Os objetos thread devolvidos incluem status de execução.
thread/turns/list - experimental; percorre por páginas o histórico de turnos de uma thread armazenada sem a retomar. itemsView controla se os itens dos turnos são omitidos, resumidos ou totalmente carregados.
thread/items/list - experimental; percorre por páginas os itens de threads persistentes, opcionalmente limitados a um turnId. O armazenamento de threads ativo tem de suportar paginação de itens.
thread/loaded/list - lista os ids das threads atualmente carregadas na memória.
thread/name/set - define ou atualiza o nome de uma thread apresentado ao utilizador, para uma thread carregada ou uma implementação gradual persistente; emite thread/name/updated.
thread/goal/set - define o objetivo de uma thread; emite thread/goal/updated.
thread/goal/get - lê o objetivo atual de uma thread.
thread/goal/clear - limpa o objetivo de uma thread; emite thread/goal/cleared.
thread/metadata/update - aplica uma correção aos metadados armazenados de threads baseados em SQLite, incluindo gitInfo e isPinned persistentes.
thread/archive - move o ficheiro de registo de uma thread para o diretório de arquivamento e tenta arquivar os registos de threads descendentes criadas que ainda não estejam arquivados; devolve {} em caso de êxito e emite thread/archived para cada thread arquivada.
thread/delete - elimina permanentemente uma thread ativa ou arquivada persistente e todas as threads descendentes criadas; devolve {} em caso de êxito e emite thread/deleted para cada thread eliminada.
thread/unsubscribe - cancela a subscrição desta ligação aos eventos de turnos/itens da thread. Se este era o último subscritor, o servidor descarrega a thread após um período de tolerância de inatividade sem subscritores e emite thread/closed.
thread/unarchive - restaura uma implementação gradual de thread arquivada no diretório de sessões ativas; devolve o thread restaurado e emite thread/unarchived.
thread/status/changed - notificação emitida quando o status de execução de uma thread carregada é alterado.
thread/compact/start - aciona a compactação do histórico de conversas de uma thread; devolve imediatamente {}, enquanto o progresso é transmitido através das notificações turn/* e item/*.
thread/shellCommand - executa um comando de shell iniciado pelo utilizador numa thread. É executado fora da sandbox, com acesso total, e não herda a política de sandbox da thread.
thread/backgroundTerminals/clean - interrompe todos os terminais em segundo plano em execução numa thread (experimental; requer capabilities.experimentalApi).
thread/backgroundTerminals/list - lista os terminais em segundo plano em execução numa thread carregada (experimental; requer capabilities.experimentalApi).
thread/backgroundTerminals/terminate - termina um terminal em segundo plano em execução através do processId do app-server (experimental; requer capabilities.experimentalApi).
thread/rollback - obsoleto; remove os últimos N turnos do contexto em memória e mantém um marcador de reversão; devolve o thread atualizado.
turn/start - adiciona a entrada do utilizador a uma thread e inicia a geração do Codex; responde com o turn inicial e transmite eventos. Para collaborationMode, settings.developer_instructions: null significa «utilizar as instruções incorporadas para o modo selecionado».
thread/inject_items - acrescenta itens em bruto da Responses API ao histórico visível para o modelo de uma thread carregada sem iniciar um turno do utilizador.
turn/steer - acrescenta a entrada do utilizador ao turno ativo em curso de uma thread; devolve o turnId aceite.
turn/interrupt - solicita o cancelamento de um turno em curso; o êxito é indicado por {} e o turno termina com status: "interrupted".
review/start - inicia o revisor do Codex para uma thread; emite itens enteredReviewMode e exitedReviewMode.
command/exec - executa um único comando na sandbox do servidor sem iniciar uma thread/um turno.
command/exec/write - escreve bytes stdin numa sessão command/exec em execução ou fecha stdin.
command/exec/resize - redimensiona uma sessão command/exec em execução apoiada por PTY.
command/exec/terminate - interrompe uma sessão command/exec em execução.
command/exec/outputDelta (notificação) - emitida para segmentos stdout/stderr codificados em base64 de uma sessão command/exec com transmissão.
process/spawn - inicia uma sessão explícita de processo fora da sandbox do Codex (experimental; requer capabilities.experimentalApi).
process/writeStdin - escreve bytes stdin numa sessão process/spawn em execução ou fecha o stdin (experimental).
process/resizePty - redimensiona uma sessão de processo em execução apoiada por PTY (experimental).
process/kill - termina uma sessão de processo em execução (experimental).
process/outputDelta e process/exited (notificação) - emitidas para a saída de processo transmitida e o estado de saída do processo (experimental).
model/list - lista os modelos disponíveis (defina includeHidden: true para incluir entradas com hidden: true), com opções de esforço, upgrade opcional e inputModalities.
modelProvider/capabilities/read - lê os limites de capacidades do fornecedor para combinações de modelo/fornecedor.
experimentalFeature/list - lista sinalizadores de funcionalidades com metadados da fase do ciclo de vida e paginação por cursor.
experimentalFeature/enablement/set - aplica uma correção às definições de execução na memória para chaves de funcionalidades suportadas, como apps e plugins.
environment/info - experimental; estabelece ligação a um ambiente de execução configurado e devolve a respetiva shell e o diretório de trabalho predefinido.
permissionProfile/list - lista perfis de permissões beta e indica se os requisitos efetivos os permitem, com paginação por cursor.
collaborationMode/list - lista predefinições do modo de colaboração (experimental, sem paginação).
skills/list - lista competências para um ou mais valores cwd (suporta forceReload e perCwdExtraUserRoots opcional).
skills/extraRoots/set - substitui as raízes adicionais ao nível do processo utilizadas para detetar competências autónomas sem as tornar persistentes.
skills/changed (notificação) - emitida quando os ficheiros locais monitorizados de competências são alterados.
hooks/list - lista os hooks de ciclo de vida detetados para um ou mais valores cwd.
marketplace/add - adiciona um marketplace remoto de plugins e torna-o persistente na configuração de marketplaces do utilizador.
marketplace/remove - remove um marketplace configurado e a respetiva raiz de marketplace instalada, quando existente.
marketplace/upgrade - atualiza um marketplace Git configurado ou todos os marketplaces Git configurados quando o nome do marketplace é omitido.
plugin/list - em desenvolvimento; lista marketplaces de plugins detetados e o estado dos plugins, incluindo metadados de políticas de instalação/autenticação, erros de carregamento de marketplaces, ids de plugins em destaque e metadados de fontes de plugins locais, Git, de registo de pacotes ou remotas. Os resumos podem incluir version remoto, localVersion local, ícones estruturados claros/escuros e installPolicySource, que pode ser null, WORKSPACE_SETTING ou IMPLICIT_CANONICAL_APP para linhas remotas atuais. Ainda não chame este método a partir de clientes de produção.
plugin/read - em desenvolvimento; lê um plugin por caminho de marketplace ou pelo nome do marketplace remoto e nome do plugin, incluindo competências incluídas, apps, nomes de servidores MCP e um shareUrl de plugin remoto quando o catálogo remoto fornece um. Ainda não chame este método a partir de clientes de produção.
plugin/install - em desenvolvimento; instala um plugin a partir de um caminho de marketplace ou do nome de um marketplace remoto. Ainda não chame este método a partir de clientes de produção.
plugin/uninstall - em desenvolvimento; desinstala um plugin instalado. Ainda não chame este método a partir de clientes de produção.
plugin/skill/read - lê Markdown de competências de plugins remotos a pedido, por marketplace remoto, id do plugin e nome da competência.
app/installed - lê o estado de execução das apps instaladas, incluindo os estados efetivos de ativação e de disponibilidade para chamada de cada app.
app/list - lista as apps (conectores) disponíveis, com paginação e metadados de acessibilidade/ativação.
app/read - obtém metadados e resumos opcionais de ferramentas apenas para apresentação relativamente a ids de apps específicos.
skills/config/write - ativa ou desativa competências por caminho.
mcpServer/oauth/login - inicia um início de sessão OAuth para um servidor MCP configurado; devolve um URL de autorização e emite mcpServer/oauthLogin/completed após a conclusão.
tool/requestUserInput - apresenta ao utilizador entre 1 e 3 perguntas curtas para uma chamada de ferramenta (experimental); as perguntas podem definir isOther para uma opção de formato livre.
mcpServer/elicitation/request (pedido do servidor) - solicita ao cliente uma entrada de formulário estruturada ou a confirmação de um fluxo de URL solicitado por um servidor MCP.
item/permissions/requestApproval (pedido do servidor) - solicita ao cliente que conceda um subconjunto de permissões de rede ou do sistema de ficheiros solicitadas pela ferramenta request_permissions incorporada.
config/mcpServer/reload - recarrega a configuração do servidor MCP a partir do disco e coloca em fila uma atualização para as threads carregadas.
mcpServerStatus/list - lista servidores MCP, ferramentas, recursos e estado da autenticação (paginação por cursor + limite). Utilize detail: "full" para obter os dados completos ou detail: "toolsAndAuthOnly" para omitir os recursos.
mcpServer/resource/read - lê um único recurso MCP através de um servidor MCP inicializado.
mcpServer/tool/call - chama uma ferramenta no servidor MCP configurado de uma thread.
mcpServer/startupStatus/updated (notificação) - emitida quando o estado de arranque de um servidor MCP configurado é alterado para uma thread carregada.
windowsSandbox/setupStart - inicia a configuração da sandbox do Windows para o modo elevated ou unelevated; devolve rapidamente e emite mais tarde windowsSandbox/setupCompleted.
feedback/upload - envia um relatório de comentários (classificação + motivo/registos opcionais + id da conversa, bem como anexos extraLogFiles opcionais).
config/read - obtém a configuração efetiva no disco após resolver as camadas de configuração.
externalAgentConfig/detect - deteta artefactos de agentes externos que podem ser migrados com includeHome e cwds opcional; cada item detetado inclui cwd (null para a pasta pessoal).
externalAgentConfig/import - aplica itens de migração de agentes externos selecionados passando migrationItems explícitos com cwd (null para a pasta pessoal). Os tipos de itens suportados incluem configuração, competências, AGENTS.md, plugins, configuração de servidores MCP, subagentes, hooks, comandos e sessões; as importações não vazias emitem externalAgentConfig/import/progress e externalAgentConfig/import/completed à medida que o trabalho é concluído. As importações de plugins e sessões podem ser concluídas de forma assíncrona.
config/value/write - escreve uma única chave/um único valor de configuração no config.toml do utilizador no disco.
config/batchWrite - aplica edições de configuração de forma atómica ao config.toml do utilizador no disco.
configRequirements/read - obtém requisitos de requirements.toml e/ou MDM, incluindo a configuração gerida exata, listas de permissões, featureRequirements fixados e requisitos de residência/rede (ou null se ainda não tiver configurado nenhum).
fs/readFile, fs/writeFile, fs/createDirectory, fs/getMetadata, fs/readDirectory, fs/remove, fs/copy, fs/watch, fs/unwatch e fs/changed (notificação) - operam em caminhos absolutos do sistema de ficheiros através da API v2 do sistema de ficheiros do app-server.

Os resumos de plugins incluem uma união source. Os plugins locais devolvem { "type": "local", "path": ... }, as entradas de marketplace baseadas em Git devolvem { "type": "git", "url": ..., "path": ..., "refName": ..., "sha": ... }, as entradas de registo de pacotes devolvem { "type": "npm", "package": ..., "version": ..., "registry": ... } e as entradas de catálogo remoto devolvem { "type": "remote" }. Para entradas de catálogo apenas remotas, PluginMarketplaceEntry.path pode ser null; passe remoteMarketplaceName em vez de marketplacePath ao ler ou instalar esses plugins.

Modelos

Listar modelos (`model/list`)

Chame model/list para detetar os modelos disponíveis e as respetivas capacidades antes de apresentar seletores de modelo ou personalidade.

{ "method": "model/list", "id": 6, "params": { "limit": 20, "includeHidden": false } }
{ "id": 6, "result": {
  "data": [{
    "id": "gpt-5.6-sol",
    "model": "gpt-5.6-sol",
    "displayName": "GPT-5.6-Sol",
    "hidden": false,
    "defaultReasoningEffort": "low",
    "supportedReasoningEfforts": [{
      "reasoningEffort": "low",
      "description": "Fast responses with lighter reasoning"
    }],
    "inputModalities": ["text", "image"],
    "supportsPersonality": true,
    "isDefault": true
  }],
  "nextCursor": null
} }

Cada entrada de modelo pode incluir:

supportedReasoningEfforts - opções de esforço suportadas pelo modelo.
defaultReasoningEffort - esforço predefinido sugerido para os clientes.
upgrade - id opcional do modelo de atualização recomendado para pedidos de migração nos clientes.
upgradeInfo - metadados opcionais de atualização para pedidos de migração nos clientes.
hidden - se o modelo está oculto da lista predefinida do seletor.
inputModalities - tipos de entrada suportados pelo modelo (por exemplo, text, image).
supportsPersonality - se o modelo suporta instruções específicas da personalidade, como /personality.
isDefault - se o modelo é a predefinição recomendada.

Por predefinição, model/list devolve apenas os modelos visíveis no seletor. Defina includeHidden: true se precisar da lista completa e pretender filtrar no lado do cliente através de hidden.

Quando inputModalities estiver em falta (catálogos de modelos mais antigos), trate-o como ["text", "image"] para garantir retrocompatibilidade.

Listar funcionalidades experimentais (`experimentalFeature/list`)

Utilize este ponto final para detetar sinalizadores de funcionalidades com metadados e a fase do ciclo de vida:

{ "method": "experimentalFeature/list", "id": 7, "params": { "limit": 20 } }
{ "id": 7, "result": {
  "data": [{
    "name": "unified_exec",
    "stage": "beta",
    "displayName": "Unified exec",
    "description": "Use the unified PTY-backed execution tool.",
    "announcement": "Beta rollout for improved command execution reliability.",
    "enabled": false,
    "defaultEnabled": false
  }],
  "nextCursor": null
} }

stage pode ser beta, underDevelopment, stable, deprecated ou removed. Para sinalizadores não beta, displayName, description e announcement podem ser null.

Inspecionar um ambiente de execução (experimental)

Utilize environment/info para inspecionar um ambiente remoto configurado antes de começar a trabalhar nele. O método requer capabilities.experimentalApi = true.

{ "method": "environment/info", "id": 8, "params": { "environmentId": "devbox" } }
{ "id": 8, "result": {
  "shell": { "name": "zsh", "path": "/bin/zsh" },
  "cwd": "file:///workspace/project"
} }

cwd pode ser null. Quando presente, é um URI file: canónico que utiliza a sintaxe de caminho nativa do ambiente. Os IDs de ambiente desconhecidos e as falhas de ligação ou de protocolo devolvem erros de pedido.

Threads

thread/read lê uma thread armazenada sem a subscrever; defina includeTurns para incluir turnos.
thread/turns/list é experimental e percorre por páginas o histórico de turnos de uma thread armazenada sem a retomar. Utilize itemsView para escolher se os itens dos turnos são omitidos, resumidos ou totalmente carregados.
thread/items/list é experimental e percorre por páginas os itens persistentes da thread, opcionalmente limitados a um turno.
thread/list suporta paginação por cursor, além de filtragem por modelProviders, sourceKinds, archived, isPinned, cwd, useStateDbOnly, searchTerm e, de forma experimental, por parentThreadId ou ancestorThreadId.
thread/loaded/list devolve os IDs das threads atualmente na memória.
thread/archive move o registo JSONL persistente da thread para o diretório de arquivamento e tenta arquivar os registos de threads descendentes criadas que ainda não estejam arquivados.
thread/delete elimina permanentemente uma thread ativa ou arquivada persistente e as respetivas threads descendentes criadas.
thread/metadata/update aplica uma correção aos metadados armazenados da thread, incluindo gitInfo e isPinned persistentes.
thread/unsubscribe cancela a subscrição da ligação atual a uma thread carregada e pode acionar thread/closed após um período de tolerância de inatividade.
thread/unarchive restaura uma implementação gradual de thread arquivada no diretório de sessões ativas.
thread/compact/start aciona a compactação e devolve imediatamente {}.
thread/rollback está obsoleto. Remove os últimos N turnos do contexto em memória e regista um marcador de reversão no registo JSONL persistente da thread.
thread/inject_items acrescenta itens em bruto da Responses API ao histórico visível para o modelo de uma thread carregada sem iniciar um turno do utilizador.

Iniciar ou retomar uma thread

Inicie uma nova thread quando precisar de uma nova conversa com o Codex.

{ "method": "thread/start", "id": 10, "params": {
  "model": "gpt-5.6-terra",
  "cwd": "/Users/me/project",
  "approvalPolicy": "never",
  "sandbox": "workspaceWrite",
  "personality": "friendly",
  "serviceName": "my_app_server_client"
} }
{ "id": 10, "result": {
  "thread": {
    "id": "thr_123",
    "sessionId": "thr_123",
    "preview": "",
    "ephemeral": false,
    "modelProvider": "openai",
    "createdAt": 1730910000
  }
} }
{ "method": "thread/started", "params": { "thread": { "id": "thr_123" } } }

serviceName é opcional. Defina-o quando pretender que o app-server identifique as métricas ao nível da thread com o nome do serviço da sua integração.

thread/start, thread/resume e thread/fork devolvem instructionSources, uma matriz de caminhos de ficheiros de instruções carregados. Cada caminho utiliza a sintaxe absoluta nativa do respetivo ambiente de origem, incluindo em ambientes remotos.

Os clientes experimentais podem definir historyMode em thread/start como "legacy" (a predefinição) ou "paginated". A criação de threads paginadas ainda não é suportada e devolve o erro JSON-RPC -32601. O app-server pode listar e ler resumos de registos paginados existentes, mas as leituras do histórico completo, a paginação de turnos e a retoma falham de forma segura até que o histórico paginado seja suportado.

Os clientes beta que adiram a capabilities.experimentalApi podem passar um id de perfil de permissões com nome em permissions, em vez do campo sandbox antigo. Não envie permissions e sandbox em conjunto. Utilize permissionProfile/list com o cwd do projeto para detetar os perfis disponíveis e verificar se os requisitos geridos permitem cada um deles.

thread.sessionId identifica a raiz atual da árvore de sessões ativas. As threads raiz utilizam o próprio id de thread como id de sessão; as threads bifurcadas mantêm o id de sessão da raiz de que provêm. Os clientes devem ler o id de sessão em thread.sessionId, em vez de o derivarem do id da thread.

Para continuar uma sessão armazenada, chame thread/resume com o thread.id que registou anteriormente. O formato da resposta corresponde a thread/start. Também pode passar as mesmas substituições de configuração suportadas por thread/start, como personality:

{ "method": "thread/resume", "id": 11, "params": {
  "threadId": "thr_123",
  "personality": "friendly"
} }
{ "id": 11, "result": { "thread": { "id": "thr_123", "name": "Bug bash notes", "ephemeral": false } } }

Retomar uma thread não atualiza, por si só, thread.updatedAt (nem a hora de modificação do ficheiro da implementação gradual). O carimbo de data/hora é atualizado quando inicia um turno.

Se marcar um servidor MCP ativado como required na configuração e esse servidor não for inicializado, thread/start e thread/resume falham em vez de continuarem sem ele.

dynamicTools em thread/start é um campo experimental (requer capabilities.experimentalApi = true). O Codex mantém estas ferramentas dinâmicas nos metadados de implementação gradual da thread e restaura-as em thread/resume quando não fornece novas ferramentas dinâmicas.

Se retomar com um modelo diferente do registado na implementação gradual, o Codex emite um aviso e aplica uma instrução única de mudança de modelo no turno seguinte.

Gerir o objetivo de uma thread

Utilize thread/goal/set, thread/goal/get e thread/goal/clear para gerir o mesmo estado persistente do objetivo apresentado por /goal na TUI.

{ "method": "thread/goal/set", "id": 13, "params": {
  "threadId": "thr_123",
  "objective": "Finish the migration and keep tests green",
  "status": "active",
  "tokenBudget": 40000
} }
{ "id": 13, "result": { "goal": {
  "threadId": "thr_123",
  "objective": "Finish the migration and keep tests green",
  "status": "active",
  "tokenBudget": 40000,
  "tokensUsed": 0,
  "timeUsedSeconds": 0
} } }
{ "method": "thread/goal/updated", "params": {
  "threadId": "thr_123",
  "goal": {
    "threadId": "thr_123",
    "objective": "Finish the migration and keep tests green",
    "status": "active",
    "tokenBudget": 40000,
    "tokensUsed": 0,
    "timeUsedSeconds": 0
  }
} }

Os objetivos têm de conter texto e ter, no máximo, 4000 carateres. O fornecimento de um novo objetivo substitui o objetivo existente e repõe a contabilização de utilização. Fornecer o objetivo atual não terminal ou omitir objective atualiza o estado ou o orçamento de tokens, mantendo o histórico de utilização.

Para criar uma ramificação a partir de uma sessão armazenada, chame thread/fork com o thread.id. Isto cria um novo id de thread e emite uma notificação thread/started para o mesmo. Passe lastTurnId para copiar o histórico até esse turno, inclusive, e omitir os turnos posteriores:

{ "method": "thread/fork", "id": 12, "params": { "threadId": "thr_123", "lastTurnId": "turn_456" } }
{ "id": 12, "result": { "thread": { "id": "thr_456", "sessionId": "thr_123", "forkedFromId": "thr_123" } } }
{ "method": "thread/started", "params": { "thread": { "id": "thr_456" } } }

O app-server rejeita um lastTurnId em curso. Se omitir o campo enquanto a thread de origem estiver a meio de um turno, a bifurcação regista um marcador de interrupção, em vez de manter um turno parcial sem marcação.

Passe ephemeral: true para criar uma bifurcação na memória sem a adicionar às listas de threads armazenadas:

{
  "method": "thread/fork",
  "id": 13,
  "params": {
    "threadId": "thr_123",
    "ephemeral": true
  }
}
{
  "id": 13,
  "result": {
    "thread": {
      "id": "thr_789",
      "sessionId": "thr_789",
      "forkedFromId": "thr_123",
      "ephemeral": true
    }
  }
}

As bifurcações efémeras de threads paginadas também requerem excludeTurns: true. Esse campo é experimental e requer capabilities.experimentalApi = true.

Quando tiver sido definido um título de thread apresentado ao utilizador, o app-server preenche thread.name nas respostas thread/list, thread/read, thread/resume, thread/unarchive e thread/rollback. thread/start e thread/fork podem omitir name (ou devolver null) até que um título seja definido mais tarde.

Ler uma thread armazenada (sem a retomar)

Utilize thread/read quando pretender dados de uma thread armazenada, mas não quiser retomar a thread nem subscrever os respetivos eventos.

includeTurns - quando é true, a resposta inclui os turnos da thread; quando é false ou omitido, obtém apenas o resumo da thread.
Os objetos thread devolvidos incluem status de execução (notLoaded, idle, systemError ou active com activeFlags).

{ "method": "thread/read", "id": 19, "params": { "threadId": "thr_123", "includeTurns": true } }
{ "id": 19, "result": { "thread": { "id": "thr_123", "name": "Bug bash notes", "ephemeral": false, "status": { "type": "notLoaded" }, "turns": [] } } }

Ao contrário de thread/resume, thread/read não carrega a thread na memória nem emite thread/started.

Listar os turnos de uma thread

thread/turns/list é experimental. Utilize-o para percorrer por páginas o histórico de turnos de uma thread armazenada sem a retomar. Por predefinição, os resultados são apresentados do mais recente para o mais antigo, para que os clientes possam obter turnos mais antigos com nextCursor. A resposta também inclui backwardsCursor; passe-o como cursor com sortDirection: "asc" para obter turnos mais recentes do que o primeiro item da página anterior.

itemsView controla a quantidade de dados dos itens de turnos incluída na resposta:

notLoaded omite os itens.
summary devolve dados resumidos dos itens e é a predefinição quando omitido.
full devolve os dados completos dos itens.

{ "method": "thread/turns/list", "id": 20, "params": {
  "threadId": "thr_123",
  "limit": 50,
  "sortDirection": "desc",
  "itemsView": "summary"
} }
{ "id": 20, "result": {
  "data": [],
  "nextCursor": "older-turns-cursor-or-null",
  "backwardsCursor": "newer-turns-cursor-or-null"
} }

thread/items/list também é experimental. Percorre por páginas os itens persistentes sem retomar a thread. Passe turnId para limitar os resultados a um turno, ou omita-o para percorrer por páginas os itens de toda a thread. O armazenamento de threads ativo tem de suportar paginação de itens; caso contrário, o servidor devolve um erro de método não suportado.

Listar threads (com paginação e filtros)

thread/list permite apresentar uma interface de histórico. Por predefinição, os resultados são ordenados por createdAt do mais recente para o mais antigo. Os filtros são aplicados antes da paginação. Passe qualquer combinação de:

cursor - cadeia opaca de uma resposta anterior; omita na primeira página.
limit - o servidor utiliza por predefinição um tamanho de página razoável se não for definido.
sortKey - created_at (predefinição), updated_at ou recency_at.
sortDirection - desc (predefinição) ou asc.
modelProviders - limita os resultados a fornecedores específicos; não definido, null ou uma matriz vazia inclui todos os fornecedores.
sourceKinds - limita os resultados a origens de threads específicas. Quando omitido ou [], o servidor utiliza por predefinição apenas origens interativas: cli e vscode.
archived - quando é true, lista apenas threads arquivadas. Quando é false ou omitido, lista threads não arquivadas (predefinição).
isPinned - quando fornecido, devolve apenas threads com o estado persistente de afixação correspondente. Omita-o para devolver threads afixadas e não afixadas.
cwd - limita os resultados a threads cujo diretório de trabalho atual da sessão corresponda exatamente a este caminho ou a um dos caminhos de uma matriz. Os caminhos relativos são resolvidos a partir do diretório de trabalho do processo app-server.
useStateDbOnly - quando é true, devolve os resultados da base de dados de estado sem analisar os registos JSONL das threads para reparar os metadados. Omita-o ou passe false para utilizar o comportamento predefinido de análise e reparação.
searchTerm - limita os resultados a threads cujo título extraído contenha este fragmento de texto sensível a maiúsculas e minúsculas.
parentThreadId - limita os resultados às threads descendentes diretas da thread principal indicada. Este filtro é experimental e requer capabilities.experimentalApi = true.
ancestorThreadId - limita os resultados aos descendentes criados da thread indicada, a qualquer profundidade. Este filtro é experimental e requer capabilities.experimentalApi = true; não o combine com parentThreadId.

sourceKinds aceita os seguintes valores:

cli
vscode
exec
appServer
subAgent
subAgentReview
subAgentCompact
subAgentThreadSpawn
subAgentOther
unknown

Exemplo:

{ "method": "thread/list", "id": 20, "params": {
  "cursor": null,
  "limit": 25,
  "sortKey": "created_at"
} }
{ "id": 20, "result": {
  "data": [
    { "id": "thr_a", "preview": "Create a TUI", "ephemeral": false, "isPinned": true, "modelProvider": "openai", "createdAt": 1730831111, "updatedAt": 1730831111, "name": "TUI prototype", "status": { "type": "notLoaded" } },
    { "id": "thr_b", "preview": "Fix tests", "ephemeral": false, "isPinned": false, "modelProvider": "openai", "createdAt": 1730750000, "updatedAt": 1730750000, "status": { "type": "notLoaded" } }
  ],
  "nextCursor": "opaque-token-or-null"
} }

Quando nextCursor é null, chegou à última página.

Atualizar os metadados armazenados de uma thread

Utilize thread/metadata/update para aplicar uma correção aos metadados armazenados da thread sem retomar a thread. Defina isPinned para afixar ou desafixar a thread, ou atualize gitInfo para alterar os metadados Git persistentes. Os campos omitidos permanecem inalterados; um null explícito limpa um valor armazenado dos metadados Git.

{ "method": "thread/metadata/update", "id": 21, "params": {
  "threadId": "thr_123",
  "isPinned": true,
  "gitInfo": { "branch": "feature/sidebar-pr" }
} }
{ "id": 21, "result": {
  "thread": {
    "id": "thr_123",
    "isPinned": true,
    "gitInfo": { "sha": null, "branch": "feature/sidebar-pr", "originUrl": null }
  }
} }

Acompanhar alterações do estado da thread

thread/status/changed é emitido sempre que o estado de execução de uma thread carregada é alterado. O conteúdo inclui threadId e o novo status.

{
  "method": "thread/status/changed",
  "params": {
    "threadId": "thr_123",
    "status": { "type": "active", "activeFlags": ["waitingOnApproval"] }
  }
}

Listar threads carregadas

thread/loaded/list devolve os IDs das threads atualmente carregadas na memória.

{ "method": "thread/loaded/list", "id": 21 }
{ "id": 21, "result": { "data": ["thr_123", "thr_456"] } }

Cancelar a subscrição de uma thread carregada

thread/unsubscribe remove a subscrição da ligação atual a uma thread. O estado da resposta é um dos seguintes:

unsubscribed quando a ligação estava subscrita e foi agora removida.
notSubscribed quando a ligação não estava subscrita a essa thread.
notLoaded quando a thread não está carregada.

Se este era o último subscritor, o servidor mantém a thread carregada até esta não ter subscritores nem atividade durante 30 minutos. Quando o período de tolerância termina, o app-server descarrega a thread e emite uma transição thread/status/changed para notLoaded, além de thread/closed.

{ "method": "thread/unsubscribe", "id": 22, "params": { "threadId": "thr_123" } }
{ "id": 22, "result": { "status": "unsubscribed" } }

Se a thread expirar posteriormente:

{ "method": "thread/status/changed", "params": {
    "threadId": "thr_123",
    "status": { "type": "notLoaded" }
} }
{ "method": "thread/closed", "params": { "threadId": "thr_123" } }

Arquivar uma thread

Utilize thread/archive para mover o registo persistente da thread (armazenado como ficheiro JSONL no disco) para o diretório de sessões arquivadas. O arquivamento de uma thread também tenta arquivar as threads descendentes criadas que ainda não estejam arquivadas.

{ "method": "thread/archive", "id": 22, "params": { "threadId": "thr_b" } }
{ "id": 22, "result": {} }
{ "method": "thread/archived", "params": { "threadId": "thr_b" } }
{ "method": "thread/archived", "params": { "threadId": "thr_child" } }

Os threads arquivados não aparecerão em chamadas futuras a thread/list, a menos que transmita archived: true. O servidor emite uma notificação thread/archived por cada thread que efetivamente arquiva; se não for possível arquivar um descendente criado, o pedido pode ainda assim ser concluído com êxito sem uma notificação de arquivamento para esse descendente.

Eliminar um thread

Utilize thread/delete para eliminar permanentemente um thread ativo ou arquivado persistido e os respetivos threads descendentes criados. O servidor remove os ficheiros de rollout existentes e os metadados associados antes de devolver uma resposta de êxito; os ficheiros de rollout em falta são considerados já eliminados. Não é possível eliminar threads raiz efémeros.

{ "method": "thread/delete", "id": 23, "params": { "threadId": "thr_b" } }
{ "id": 23, "result": {} }
{ "method": "thread/deleted", "params": { "threadId": "thr_b" } }
{ "method": "thread/deleted", "params": { "threadId": "thr_child" } }

Desarquivar um thread

Utilize thread/unarchive para mover novamente o rollout de um thread arquivado para o diretório de sessões ativas.

{ "method": "thread/unarchive", "id": 24, "params": { "threadId": "thr_b" } }
{ "id": 24, "result": { "thread": { "id": "thr_b", "name": "Bug bash notes" } } }
{ "method": "thread/unarchived", "params": { "threadId": "thr_b" } }

Acionar a compactação de um thread

Utilize thread/compact/start para acionar manualmente a compactação do histórico de um thread. O pedido devolve imediatamente {}.

O app-server emite o progresso através de notificações turn/* e item/* padrão no mesmo threadId, incluindo o ciclo de vida de um item contextCompaction (item/started e, em seguida, item/completed).

{ "method": "thread/compact/start", "id": 25, "params": { "threadId": "thr_b" } }
{ "id": 25, "result": {} }

Executar um comando de shell num thread

Utilize thread/shellCommand para comandos de shell iniciados pelo utilizador que pertençam a um thread. O pedido devolve imediatamente {}, enquanto o progresso é transmitido através de notificações turn/* e item/* padrão.

Esta API é executada fora da sandbox, com acesso total, e não herda a política de sandbox do thread. Os clientes só a devem disponibilizar para comandos explicitamente iniciados pelo utilizador.

Se o thread já tiver um turno ativo, o comando é executado como uma ação auxiliar nesse turno e a respetiva saída formatada é injetada no fluxo de mensagens do turno. Se o thread estiver inativo, o app-server inicia um turno autónomo para o comando de shell.

{ "method": "thread/shellCommand", "id": 26, "params": { "threadId": "thr_b", "command": "git status --short" } }
{ "id": 26, "result": {} }

Limpar terminais em segundo plano

Utilize thread/backgroundTerminals/clean para parar todos os terminais em segundo plano em execução associados a um thread. Este método é experimental e requer capabilities.experimentalApi = true.

{ "method": "thread/backgroundTerminals/clean", "id": 27, "params": { "threadId": "thr_b" } }
{ "id": 27, "result": {} }

Utilize thread/backgroundTerminals/list para inspecionar os terminais em segundo plano em execução num thread carregado. O pedido suporta a paginação padrão cursor e limit, e o processId devolvido é o ID do processo app-server. Este método é experimental e requer capabilities.experimentalApi = true:

{ "method": "thread/backgroundTerminals/list", "id": 28, "params": { "threadId": "thr_b" } }
{ "id": 28, "result": { "data": [
  {
    "itemId": "item_456",
    "processId": "42",
    "command": "python3 -m http.server",
    "cwd": "/workspace",
    "osPid": null,
    "cpuPercent": null,
    "rssKb": null
  }
], "nextCursor": null } }

Utilize thread/backgroundTerminals/terminate com esse processId para parar um terminal em segundo plano. Este método é experimental e requer capabilities.experimentalApi = true:

{ "method": "thread/backgroundTerminals/terminate", "id": 29, "params": { "threadId": "thr_b", "processId": "42" } }
{ "id": 29, "result": { "terminated": true } }

Reverter turnos recentes

thread/rollback foi descontinuado e será removido. Remove as últimas numTurns entradas do contexto em memória e guarda um marcador de reversão no registo de rollout. O thread devolvido inclui turns preenchido após a reversão.

{ "method": "thread/rollback", "id": 30, "params": { "threadId": "thr_b", "numTurns": 1 } }
{ "id": 30, "result": { "thread": { "id": "thr_b", "name": "Bug bash notes", "ephemeral": false } } }

Turnos

O campo input aceita uma lista de itens:

{ "type": "text", "text": "Explain this diff" }
{ "type": "image", "url": "https://.../design.png" }
{ "type": "localImage", "path": "/tmp/screenshot.png" }

Pode substituir as definições de configuração por turno (modelo, esforço, personalidade, cwd, política de sandbox, resumo). Quando especificadas, estas definições tornam-se as predefinições dos turnos posteriores no mesmo thread. outputSchema aplica-se apenas ao turno atual. Para sandboxPolicy.type = "externalSandbox", defina networkAccess como restricted ou enabled; para workspaceWrite, networkAccess continua a ser um booleano.

Para turn/start.collaborationMode, settings.developer_instructions: null significa «utilizar as instruções incorporadas para o modo selecionado», em vez de limpar as instruções do modo.

Acesso de leitura da sandbox (`ReadOnlyAccess`)

sandboxPolicy suporta controlos explícitos de acesso de leitura:

readOnly: access opcional ({ "type": "fullAccess" } por predefinição ou raízes restritas).
workspaceWrite: readOnlyAccess opcional ({ "type": "fullAccess" } por predefinição ou raízes restritas).

Formato do acesso de leitura restrito:

{
  "type": "restricted",
  "includePlatformDefaults": true,
  "readableRoots": ["/Users/me/shared-read-only"]
}

No macOS, includePlatformDefaults: true acrescenta uma política Seatbelt predefinida da plataforma e selecionada para sessões com leitura restrita. Isto melhora a compatibilidade das ferramentas sem permitir de forma abrangente todo o /System.

Exemplos:

{ "type": "readOnly", "access": { "type": "fullAccess" } }

{
  "type": "workspaceWrite",
  "writableRoots": ["/Users/me/project"],
  "readOnlyAccess": {
    "type": "restricted",
    "includePlatformDefaults": true,
    "readableRoots": ["/Users/me/shared-read-only"]
  },
  "networkAccess": false
}

Iniciar um turno

{ "method": "turn/start", "id": 30, "params": {
  "threadId": "thr_123",
  "input": [ { "type": "text", "text": "Run tests" } ],
  "cwd": "/Users/me/project",
  "approvalPolicy": "unlessTrusted",
  "sandboxPolicy": {
    "type": "workspaceWrite",
    "writableRoots": ["/Users/me/project"],
    "networkAccess": true
  },
  "model": "gpt-5.6-terra",
  "effort": "medium",
  "summary": "concise",
  "personality": "friendly",
  "outputSchema": {
    "type": "object",
    "properties": { "answer": { "type": "string" } },
    "required": ["answer"],
    "additionalProperties": false
  }
} }
{ "id": 30, "result": { "turn": { "id": "turn_456", "status": "inProgress", "items": [], "error": null } } }

Injetar itens num thread

Utilize thread/inject_items para acrescentar itens predefinidos da Responses API ao histórico de pedidos de um thread carregado sem iniciar um turno do utilizador. Estes itens são guardados no rollout e incluídos nos pedidos subsequentes ao modelo.

{ "method": "thread/inject_items", "id": 31, "params": {
  "threadId": "thr_123",
  "items": [
    {
      "type": "message",
      "role": "assistant",
      "content": [{ "type": "output_text", "text": "Previously computed context." }]
    }
  ]
} }
{ "id": 31, "result": {} }

Orientar um turno ativo

Utilize turn/steer para acrescentar mais entradas do utilizador ao turno ativo em curso.

Inclua expectedTurnId; tem de corresponder ao ID do turno ativo.
O pedido falha se não existir um turno ativo no thread.
turn/steer não emite uma nova notificação turn/started.
turn/steer não aceita substituições ao nível do turno (model, cwd, sandboxPolicy ou outputSchema).

{ "method": "turn/steer", "id": 32, "params": {
  "threadId": "thr_123",
  "input": [ { "type": "text", "text": "Actually focus on failing tests first." } ],
  "expectedTurnId": "turn_456"
} }
{ "id": 32, "result": { "turnId": "turn_456" } }

Iniciar um turno (invocar uma skill)

Invoque explicitamente uma skill incluindo $<skill-name> na entrada de texto e adicionando um item de entrada skill juntamente com esta.

{ "method": "turn/start", "id": 33, "params": {
  "threadId": "thr_123",
  "input": [
    { "type": "text", "text": "$skill-creator Add a new skill for triaging flaky CI and include step-by-step usage." },
    { "type": "skill", "name": "skill-creator", "path": "/Users/me/.codex/skills/skill-creator/SKILL.md" }
  ]
} }
{ "id": 33, "result": { "turn": { "id": "turn_457", "status": "inProgress", "items": [], "error": null } } }

Interromper um turno

{ "method": "turn/interrupt", "id": 31, "params": { "threadId": "thr_123", "turnId": "turn_456" } }
{ "id": 31, "result": {} }

Em caso de êxito, o turno termina com status: "interrupted".

Revisão

review/start executa o revisor do Codex para um thread e transmite os itens de revisão. Os destinos incluem:

uncommittedChanges
baseBranch (diferenças em relação a um branch)
commit (rever um commit específico)
custom (instruções em formato livre)

Utilize delivery: "inline" (predefinição) para executar a revisão no thread existente ou delivery: "detached" para criar um novo thread de revisão por bifurcação.

Exemplo de pedido/resposta:

{ "method": "review/start", "id": 40, "params": {
  "threadId": "thr_123",
  "delivery": "inline",
  "target": { "type": "commit", "sha": "1234567deadbeef", "title": "Polish tui colors" }
} }
{ "id": 40, "result": {
  "turn": {
    "id": "turn_900",
    "status": "inProgress",
    "items": [
      { "type": "userMessage", "id": "turn_900", "content": [ { "type": "text", "text": "Review commit 1234567: Polish tui colors" } ] }
    ],
    "error": null
  },
  "reviewThreadId": "thr_123"
} }

Para uma revisão independente, utilize "delivery": "detached". A resposta tem o mesmo formato, mas reviewThreadId será o ID do novo thread de revisão (diferente do threadId original). O servidor também emite uma notificação thread/started para esse novo thread antes de transmitir o turno de revisão.

O Codex transmite a notificação turn/started habitual, seguida de um item/started com um item enteredReviewMode:

{
  "method": "item/started",
  "params": {
    "item": {
      "type": "enteredReviewMode",
      "id": "turn_900",
      "review": "current changes"
    }
  }
}

Quando o revisor termina, o servidor emite item/started e item/completed contendo um item exitedReviewMode com o texto final da revisão:

{
  "method": "item/completed",
  "params": {
    "item": {
      "type": "exitedReviewMode",
      "id": "turn_900",
      "review": "Looks solid overall..."
    }
  }
}

Utilize esta notificação para apresentar a saída do revisor no seu cliente.

Execução de processos

process/* é uma API experimental de controlo explícito de processos. Requer capabilities.experimentalApi = true e é executada fora da sandbox do Codex. Utilize-a apenas quando o seu cliente disponibilizar intencionalmente o controlo local de processos sem uma sandbox.

Inicie um processo com process/spawn e forneça um processHandle; em seguida, utilize essa referência para pedidos de stdin, redimensionamento e terminação. A saída é transmitida através de notificações process/outputDelta e a conclusão através de process/exited.

{ "method": "process/spawn", "id": 48, "params": {
  "command": ["python3", "-m", "pytest", "-q"],
  "processHandle": "pytest-1",
  "cwd": "/Users/me/project",
  "tty": true
} }
{ "id": 48, "result": {} }
{ "method": "process/outputDelta", "params": {
  "processHandle": "pytest-1",
  "stream": "stdout",
  "deltaBase64": "Li4u"
} }
{ "method": "process/exited", "params": {
  "processHandle": "pytest-1",
  "exitCode": 0
} }

Utilize process/writeStdin com deltaBase64, closeStdin ou ambos para enviar entrada. Utilize process/resizePty para eventos de redimensionamento do PTY e process/kill para terminar um processo em execução.

Execução de comandos

command/exec executa um único comando (matriz argv) na sandbox do servidor sem criar um thread.

{ "method": "command/exec", "id": 50, "params": {
  "command": ["ls", "-la"],
  "cwd": "/Users/me/project",
  "sandboxPolicy": { "type": "workspaceWrite" },
  "timeoutMs": 10000
} }
{ "id": 50, "result": { "exitCode": 0, "stdout": "...", "stderr": "" } }

Utilize sandboxPolicy.type = "externalSandbox" se já executar o processo do servidor numa sandbox e pretender que o Codex ignore a sua própria imposição de sandbox. Para o modo de sandbox externa, defina networkAccess como restricted (predefinição) ou enabled. Para readOnly e workspaceWrite, utilize a mesma estrutura opcional access / readOnlyAccess apresentada acima.

Notas:

O servidor rejeita matrizes command vazias.
sandboxPolicy aceita o mesmo formato utilizado por turn/start (por exemplo, dangerFullAccess, readOnly, workspaceWrite, externalSandbox).
Quando omitido, timeoutMs utiliza a predefinição do servidor.
Defina tty: true para sessões baseadas em PTY e utilize processId quando pretender utilizar posteriormente command/exec/write, command/exec/resize ou command/exec/terminate.
Defina streamStdoutStderr: true para receber notificações command/exec/outputDelta enquanto o comando está em execução.

Ler requisitos de administrador (`configRequirements/read`)

Utilize configRequirements/read para inspecionar os requisitos de administrador efetivos carregados a partir de requirements.toml e/ou MDM.

{ "method": "configRequirements/read", "id": 52, "params": {} }
{ "id": 52, "result": {
  "requirements": {
    "allowedApprovalPolicies": ["onRequest", "unlessTrusted"],
    "allowedSandboxModes": ["readOnly", "workspaceWrite"],
    "featureRequirements": {
      "personality": true,
      "unified_exec": false
    },
    "network": {
      "enabled": true,
      "allowedDomains": ["api.openai.com"],
      "allowUnixSockets": ["/tmp/example.sock"],
      "dangerouslyAllowAllUnixSockets": false
    }
  }
} }

result.requirements é null quando não há requisitos configurados. Consulte a documentação sobre requirements.toml para obter detalhes sobre as chaves e os valores suportados.

Configuração da sandbox do Windows (`windowsSandbox/setupStart`)

Os clientes Windows personalizados podem acionar a configuração da sandbox de forma assíncrona, em vez de bloquearem durante as verificações de arranque.

{ "method": "windowsSandbox/setupStart", "id": 53, "params": { "mode": "elevated" } }
{ "id": 53, "result": { "started": true } }

O app-server inicia a configuração em segundo plano e emite posteriormente uma notificação de conclusão:

{
  "method": "windowsSandbox/setupCompleted",
  "params": { "mode": "elevated", "success": true, "error": null }
}

Modos:

elevated - executar o fluxo de configuração elevado da sandbox do Windows.
unelevated - executar o fluxo de configuração/verificação preliminar antigo.

Sistema de ficheiros

As API de sistema de ficheiros v2 operam sobre caminhos absolutos. Utilize fs/watch quando um cliente precisar de invalidar o estado da IU após a alteração de um ficheiro ou diretório.

{ "method": "fs/watch", "id": 54, "params": {
  "watchId": "0195ec6b-1d6f-7c2e-8c7a-56f2c4a8b9d1",
  "path": "/Users/me/project/.git/HEAD"
} }
{ "id": 54, "result": { "path": "/Users/me/project/.git/HEAD" } }
{ "method": "fs/changed", "params": {
  "watchId": "0195ec6b-1d6f-7c2e-8c7a-56f2c4a8b9d1",
  "changedPaths": ["/Users/me/project/.git/HEAD"]
} }
{ "method": "fs/unwatch", "id": 55, "params": {
  "watchId": "0195ec6b-1d6f-7c2e-8c7a-56f2c4a8b9d1"
} }
{ "id": 55, "result": {} }

A monitorização de um ficheiro emite fs/changed para o caminho desse ficheiro, incluindo atualizações efetuadas por operações de substituição ou mudança de nome.

Eventos

As notificações de eventos constituem o fluxo iniciado pelo servidor para os ciclos de vida de threads, os ciclos de vida de turnos e os respetivos itens. Depois de iniciar ou retomar um thread, continue a ler o fluxo de transporte ativo para receber notificações thread/started, thread/archived, thread/unarchived, thread/closed, thread/status/changed, turn/*, item/* e serverRequest/resolved.

Exclusão de notificações

Os clientes podem suprimir notificações específicas por ligação enviando nomes de métodos exatos em initialize.params.capabilities.optOutNotificationMethods.

Apenas correspondência exata: item/agentMessage/delta suprime apenas esse método.
Os nomes de métodos desconhecidos são ignorados.
Aplica-se às notificações thread/*, turn/*, item/* e notificações v2 relacionadas da ligação atual.
Não se aplica a pedidos, respostas ou erros.

Eventos de pesquisa difusa de ficheiros (experimental)

A API de sessões de pesquisa difusa de ficheiros emite notificações por consulta:

fuzzyFileSearch/sessionUpdated - { sessionId, query, files } com as correspondências atuais para a consulta ativa.
fuzzyFileSearch/sessionCompleted - { sessionId } quando a indexação e a correspondência dessa consulta terminam.

Eventos de aviso

configWarning - { summary, details?, path?, range? } para problemas recuperáveis de configuração ou inicialização.
warning - { threadId?, message } para avisos de execução não fatais.

Eventos de configuração da sandbox do Windows

windowsSandbox/setupCompleted - { mode, success, error } emitido após a conclusão de um pedido windowsSandbox/setupStart.

Eventos de turno

turn/started - { turn } com o ID do turno, items vazio e status: "inProgress".
turn/completed - { turn } em que turn.status é completed, interrupted ou failed; as falhas incluem { error: { message, codexErrorInfo?, additionalDetails? } }.
turn/diff/updated - { threadId, turnId, diff } com as últimas diferenças unificadas agregadas de todas as alterações de ficheiros no turno.
turn/plan/updated - { turnId, explanation?, plan } sempre que o agente partilha ou altera o seu plano; cada entrada plan é { step, status } com status em pending, inProgress ou completed.
hook/started e hook/completed - { threadId, turnId?, run } quando um hook do ciclo de vida é iniciado e quando o resumo da sua execução final está disponível.
model/safetyBuffering/updated - { threadId, turnId, model, useCases, reasons, showBufferingUi, fasterModel } quando uma resposta entra temporariamente em armazenamento de segurança intermédio.
model/rerouted - { threadId, turnId, fromModel, toModel, reason } quando o serviço encaminha um pedido para outro modelo.
model/verification - { threadId, turnId, verifications } quando o serviço exige verificação adicional da conta.
thread/tokenUsage/updated - atualizações de utilização para o thread ativo.

turn/diff/updated e turn/plan/updated incluem atualmente matrizes items vazias, mesmo quando são transmitidos eventos de itens. Utilize as notificações item/* como fonte fidedigna para os itens do turno.

Itens

ThreadItem é a união discriminada transportada nas respostas dos turnos e nas notificações item/*. Os tipos de itens comuns incluem:

userMessage - {id, content} em que content é uma lista de entradas do utilizador (text, image ou localImage).
agentMessage - {id, text, phase?} contendo a resposta acumulada do agente. Quando presente, phase utiliza valores do protocolo da Responses API (commentary, final_answer).
plan - {id, text} contendo o texto do plano proposto no modo de plano. Considere o item plan final de item/completed como definitivo.
reasoning - {id, summary, content} em que summary contém resumos de raciocínio transmitidos e content contém blocos de raciocínio em bruto.
commandExecution - {id, command, cwd, status, commandActions, aggregatedOutput?, exitCode?, durationMs?}.
fileChange - {id, changes, status} que descreve as alterações propostas; a lista changes contém {path, kind, diff}.
mcpToolCall - {id, server, tool, status, arguments, appContext?, pluginId?, result?, error?}. Para aplicações MCP fidedignas, appContext pode incluir connectorId, linkId, resourceUri, appName, templateId e o conector estável actionName. Os itens persistidos mais antigos podem omitir metadados mais recentes. Utilize appContext.resourceUri em vez do mcpAppResourceUri de nível superior descontinuado.
dynamicToolCall - {id, tool, arguments, status, contentItems?, success?, durationMs?} para invocações de ferramentas dinâmicas executadas pelo cliente.
collabToolCall - {id, tool, status, senderThreadId, receiverThreadId?, newThreadId?, prompt?, agentStatus?}.
webSearch - {id, query, action?} para pedidos de pesquisa na Web emitidos pelo agente.
imageView - {id, path} emitido quando o agente invoca a ferramenta de visualização de imagens.
enteredReviewMode - {id, review} enviado quando o revisor é iniciado.
exitedReviewMode - {id, review} emitido quando o revisor termina.
contextCompaction - {id} emitido quando o Codex compacta o histórico da conversa.

Para webSearch.action, a ação type pode ser search (query?, queries?), openPage (url?) ou findInPage (url?, pattern?).

O app-server descontinua a notificação antiga thread/compacted; utilize antes o item contextCompaction.

Todos os itens emitem dois eventos de ciclo de vida partilhados:

item/started - emite o item completo quando começa uma nova unidade de trabalho; o item.id corresponde ao itemId utilizado pelos deltas.
item/completed - envia o item final quando o trabalho termina; considere-o o estado definitivo.

Deltas de itens

item/agentMessage/delta - acrescenta texto transmitido à mensagem do agente.
item/plan/delta - transmite o texto do plano proposto. O item plan final pode não ser exatamente igual aos deltas concatenados.
item/reasoning/summaryTextDelta - transmite resumos de raciocínio legíveis; summaryIndex é incrementado quando é aberta uma nova secção do resumo.
item/reasoning/summaryPartAdded - assinala um limite entre secções do resumo de raciocínio.
item/reasoning/textDelta - transmite texto de raciocínio em bruto (quando suportado pelo modelo).
item/commandExecution/outputDelta - transmite stdout/stderr de um comando; acrescente os deltas por ordem.
item/fileChange/outputDelta - notificação de compatibilidade descontinuada para a saída de texto antiga apply_patch. As versões atuais do app-server já não a emitem; utilize os itens fileChange e turn/diff/updated.

Erros

Se um turno falhar, o servidor emite um evento error com { error: { message, codexErrorInfo?, additionalDetails? } } e termina depois o turno com status: "failed". Quando está disponível um estado HTTP a montante, este aparece em codexErrorInfo.httpStatusCode.

Os valores codexErrorInfo comuns incluem:

ContextWindowExceeded
UsageLimitExceeded
HttpConnectionFailed (erros 4xx/5xx a montante)
ResponseStreamConnectionFailed
ResponseStreamDisconnected
ResponseTooManyFailedAttempts
BadRequest, Unauthorized, SandboxError, InternalServerError, Other

Quando está disponível um estado HTTP a montante, o servidor reencaminha-o em httpStatusCode na variante codexErrorInfo relevante.

Aprovações

Consoante as definições de Codex de um utilizador, a execução de comandos e as alterações de ficheiros podem exigir aprovação. O app-server envia ao cliente um pedido JSON-RPC iniciado pelo servidor, e o cliente responde com uma carga útil de decisão.

Decisões de execução de comandos: accept, acceptForSession, decline, cancel ou { "acceptWithExecpolicyAmendment": { "execpolicy_amendment": ["cmd", "..."] } }.
Decisões de alteração de ficheiros: accept, acceptForSession, decline, cancel.
Os pedidos incluem threadId e turnId — utilize-os para limitar o estado da IU à conversa ativa.
O servidor retoma ou recusa o trabalho e termina o item com item/completed.

Aprovações de execução de comandos

Ordem das mensagens:

item/started apresenta o item commandExecution pendente com command, cwd e outros campos.
item/commandExecution/requestApproval inclui itemId, threadId, turnId, reason opcional, command opcional, cwd opcional, commandActions opcional, proposedExecpolicyAmendment opcional, networkApprovalContext opcional e availableDecisions opcional. Quando initialize.params.capabilities.experimentalApi = true, a carga útil também pode incluir o additionalPermissions experimental, que descreve o acesso à sandbox solicitado por comando. Todos os caminhos do sistema de ficheiros em additionalPermissions são absolutos no protocolo.
O cliente responde com uma das decisões de aprovação de execução de comandos acima.
serverRequest/resolved confirma que o pedido pendente foi respondido ou removido.
item/completed devolve o item commandExecution final com status: completed | failed | declined.

Quando networkApprovalContext está presente, o pedido destina-se ao acesso de rede gerido (e não à aprovação geral de um comando de shell). O esquema v2 atual apresenta o host e o protocol de destino; os clientes devem apresentar um pedido específico para a rede e não presumir que command seja uma pré-visualização do comando de shell compreensível para o utilizador.

O Codex agrupa pedidos simultâneos de aprovação de rede por destino (host, protocolo e porta). Por conseguinte, o app-server pode enviar um único pedido que desbloqueia vários pedidos em fila para o mesmo destino, enquanto portas diferentes no mesmo anfitrião são tratadas separadamente.

Aprovações de alterações de ficheiros

Ordem das mensagens:

item/started emite um item fileChange com as alterações changes e status: "inProgress" propostas.
item/fileChange/requestApproval inclui itemId, threadId, turnId, reason opcional e grantRoot opcional.
O cliente responde com uma das decisões de aprovação de alterações de ficheiros acima.
serverRequest/resolved confirma que o pedido pendente foi respondido ou removido.
item/completed devolve o item fileChange final com status: completed | failed | declined.

`tool/requestUserInput`

Quando o cliente responde a item/tool/requestUserInput, o app-server emite serverRequest/resolved com { threadId, requestId }. Se o pedido pendente for removido pelo início, pela conclusão ou pela interrupção de um turno antes de o cliente responder, o servidor emite a mesma notificação para essa limpeza.

Os parâmetros do pedido incluem autoResolutionMs como um tempo limite inteiro em milissegundos ou null. Quando presente, os clientes anfitriões podem resolver o pedido automaticamente após esse intervalo se o utilizador não responder.

Pedidos de permissão

A ferramenta request_permissions incorporada envia item/permissions/requestApproval com threadId, turnId, itemId, environmentId, cwd, reason opcional e as permissões de rede ou de sistema de ficheiros solicitadas. Responda com permissions contendo apenas o subconjunto concedido. Defina scope como "session" para manter a concessão para turnos posteriores na mesma sessão; omita-o ou utilize "turn" para uma concessão limitada ao turno. As permissões que não foram solicitadas são ignoradas.

Pedidos de elicitação do servidor MCP

Um servidor MCP pode interromper um turno com mcpServer/elicitation/request. O pedido inclui threadId, um turnId opcional, serverName e um destes formatos de pedido:

mode: "form" ou mode: "openai/form", com message e requestedSchema.
mode: "url", com message, url e elicitationId.

Responda com action: "accept" e o content solicitado, ou com action: "decline" ou "cancel" e content: null. Em seguida, o app-server emite serverRequest/resolved. Para receber a variante openai/form, ative-a com initialize.params.capabilities.mcpServerOpenaiFormElicitation.

Chamadas de ferramentas dinâmicas (experimental)

dynamicTools em thread/start e o fluxo de pedido ou resposta item/tool/call correspondente são API experimentais.

Os nomes das ferramentas dinâmicas e dos espaços de nomes têm de respeitar as restrições de nomenclatura da Responses API. Evite nomes de espaços de nomes reservados utilizados pelas ferramentas incorporadas do Codex.

Quando uma ferramenta dinâmica é invocada durante um turno, o app-server emite:

item/started com item.type = "dynamicToolCall", status = "inProgress", além de tool e arguments.
item/tool/call como um pedido do servidor ao cliente.
A carga útil da resposta do cliente com os itens de conteúdo devolvidos.
item/completed com item.type = "dynamicToolCall", o status final e qualquer valor contentItems ou success devolvido.

Aprovações de chamadas de ferramentas MCP (aplicações)

As chamadas de ferramentas de aplicações (conectores) também podem exigir aprovação. Quando a chamada de uma ferramenta de aplicação tem efeitos secundários, o servidor pode solicitar aprovação com tool/requestUserInput e opções como Aceitar, Recusar e Cancelar. As anotações de ferramentas destrutivas acionam sempre uma aprovação, mesmo que a ferramenta também indique sugestões com menos privilégios. Se o utilizador recusar ou cancelar, o item mcpToolCall relacionado termina com um erro, em vez de executar a ferramenta.

Skills

Invoque uma skill incluindo $<skill-name> na entrada de texto. Adicione um item de entrada skill (recomendado) para que o servidor injete as instruções completas da skill, em vez de depender do modelo para resolver o nome.

{
  "method": "turn/start",
  "id": 101,
  "params": {
    "threadId": "thread-1",
    "input": [
      {
        "type": "text",
        "text": "$skill-creator Add a new skill for triaging flaky CI."
      },
      {
        "type": "skill",
        "name": "skill-creator",
        "path": "/Users/me/.codex/skills/skill-creator/SKILL.md"
      }
    ]
  }
}

Se omitir o item skill, o modelo continuará a analisar o marcador $<skill-name> e a tentar localizar a skill, o que pode aumentar a latência.

Exemplo:

$skill-creator Add a new skill for triaging flaky CI and include step-by-step usage.

Utilize skills/list para obter as skills disponíveis (opcionalmente limitadas por cwds, com forceReload). Também pode incluir perCwdExtraUserRoots para analisar caminhos absolutos adicionais como âmbito user para valores cwd específicos. O app-server ignora entradas cujo cwd não esteja presente em cwds. skills/list pode reutilizar um resultado em cache por cwd; defina forceReload: true para atualizar a partir do disco. Quando presentes, o servidor lê interface e dependencies de SKILL.json.

{ "method": "skills/list", "id": 25, "params": {
  "cwds": ["/Users/me/project", "/Users/me/other-project"],
  "forceReload": true,
  "perCwdExtraUserRoots": [
    {
      "cwd": "/Users/me/project",
      "extraUserRoots": ["/Users/me/shared-skills"]
    }
  ]
} }
{ "id": 25, "result": {
  "data": [{
    "cwd": "/Users/me/project",
    "skills": [
      {
        "name": "skill-creator",
        "description": "Create or update a Codex skill",
        "enabled": true,
        "interface": {
          "displayName": "Skill Creator",
          "shortDescription": "Create or update a Codex skill"
        },
        "dependencies": {
          "tools": [
            {
              "type": "env_var",
              "value": "GITHUB_TOKEN",
              "description": "GitHub API token"
            },
            {
              "type": "mcp",
              "value": "github",
              "transport": "streamable_http",
              "url": "https://example.com/mcp"
            }
          ]
        }
      }
    ],
    "errors": []
  }]
} }

O servidor também emite notificações skills/changed quando são alterados ficheiros locais de skills monitorizados. Considere-as um sinal de invalidação e execute novamente skills/list com os seus parâmetros atuais, quando necessário.

Para ativar ou desativar uma skill por caminho:

{
  "method": "skills/config/write",
  "id": 26,
  "params": {
    "path": "/Users/me/.codex/skills/skill-creator/SKILL.md",
    "enabled": false
  }
}

Aplicações (conectores)

Utilize app/installed para ler o último instantâneo confirmado da execução das aplicações instaladas. Cada resultado inclui o id da aplicação, runtimeName (ou null), o estado efetivo de enabled e o estado de callable. Uma aplicação só pode ser chamada quando a configuração efetiva a ativa e pelo menos uma ferramenta visível para o modelo cumpre as políticas da aplicação e das ferramentas.

{
  "method": "app/installed",
  "id": 49,
  "params": {
    "threadId": "thread-1",
    "forceRefresh": false
  }
}
{
  "id": 49,
  "result": {
    "apps": [
      {
        "id": "demo-app",
        "runtimeName": "Demo App",
        "enabled": true,
        "callable": true
      }
    ]
  }
}

Omita threadId para utilizar a configuração global em vez da configuração de um thread carregado. Defina forceRefresh: true para atualizar o instantâneo de execução do conector antes de o ler. Quando uma política global ou do espaço de trabalho bloqueia o acesso à aplicação, uma aplicação observada pode ainda aparecer com enabled e callable definidos como false.

Utilize app/list para obter as aplicações disponíveis. Na CLI/TUI, /apps é o seletor apresentado ao utilizador; em clientes personalizados, chame app/list diretamente. Cada entrada inclui isAccessible (disponível para o utilizador) e isEnabled (ativada em config.toml), para que os clientes possam distinguir a instalação/o acesso do estado de ativação local. As entradas das aplicações também podem incluir os campos opcionais branding, appMetadata e labels.

{ "method": "app/list", "id": 50, "params": {
  "cursor": null,
  "limit": 50,
  "threadId": "thread-1",
  "forceRefetch": false
} }
{ "id": 50, "result": {
  "data": [
    {
      "id": "demo-app",
      "name": "Demo App",
      "description": "Example connector for documentation.",
      "logoUrl": "https://example.com/demo-app.png",
      "logoUrlDark": null,
      "distributionChannel": null,
      "branding": null,
      "appMetadata": null,
      "labels": null,
      "installUrl": "https://chatgpt.com/apps/demo-app/demo-app",
      "isAccessible": true,
      "isEnabled": true
    }
  ],
  "nextCursor": null
} }

Se fornecer threadId, a limitação de funcionalidades da aplicação (features.apps) utiliza o instantâneo de configuração desse thread. Quando omitido, o app-server utiliza a configuração global mais recente.

app/list é devolvido depois de as aplicações acessíveis e as aplicações do diretório serem carregadas. Defina forceRefetch: true para ignorar as caches das aplicações e obter dados atualizados. As entradas da cache só são substituídas quando as atualizações são concluídas com êxito.

O servidor também emite notificações app/list/updated sempre que uma das origens (aplicações acessíveis ou aplicações do diretório) termina de carregar. Cada notificação inclui a lista combinada mais recente de aplicações.

{
  "method": "app/list/updated",
  "params": {
    "data": [
      {
        "id": "demo-app",
        "name": "Demo App",
        "description": "Example connector for documentation.",
        "logoUrl": "https://example.com/demo-app.png",
        "logoUrlDark": null,
        "distributionChannel": null,
        "branding": null,
        "appMetadata": null,
        "labels": null,
        "installUrl": "https://chatgpt.com/apps/demo-app/demo-app",
        "isAccessible": true,
        "isEnabled": true
      }
    ]
  }
}

Utilize app/read quando já conhecer os IDs das aplicações e precisar dos respetivos metadados, em vez do estado da execução instalada. Transmita, no máximo, 100 appIds. O servidor mantém apenas a primeira ocorrência de cada ID repetido e preserva essa ordem em apps e missingAppIds. As aplicações desconhecidas ou inacessíveis são devolvidas em missingAppIds sem provocar a falha de todo o pedido.

{
  "method": "app/read",
  "id": 52,
  "params": {
    "appIds": ["demo-app", "missing-app"],
    "includeTools": true
  }
}
{
  "id": 52,
  "result": {
    "apps": [
      {
        "id": "demo-app",
        "name": "Demo App",
        "description": "Example connector for documentation.",
        "iconUrl": null,
        "iconUrlDark": null,
        "distributionChannel": null,
        "installUrl": null,
        "pluginDisplayNames": [],
        "toolSummaries": [
          {
            "name": "search",
            "title": "Search",
            "description": "Search the app.",
            "isEnabled": true,
            "disabledReason": null,
            "isReadOnly": true
          }
        ]
      }
    ],
    "missingAppIds": ["missing-app"]
  }
}

Defina includeTools: true para solicitar resumos públicos de ferramentas destinados apenas à apresentação. A resposta de metadados não inclui o estado da execução das aplicações instaladas nem autoriza uma chamada de ferramenta; utilize app/installed para verificar os estados efetivos de enabled e callable.

Invoque uma aplicação inserindo $<app-slug> na entrada de texto e adicionando um item de entrada mention com o caminho app://<id> (recomendado).

{
  "method": "turn/start",
  "id": 51,
  "params": {
    "threadId": "thread-1",
    "input": [
      {
        "type": "text",
        "text": "$demo-app Pull the latest updates from the team."
      },
      {
        "type": "mention",
        "name": "Demo App",
        "path": "app://demo-app"
      }
    ]
  }
}

Exemplos de RPC de configuração para as definições das aplicações

Utilize config/read, config/value/write e config/batchWrite para inspecionar ou atualizar os controlos das aplicações em config.toml.

Leia o formato efetivo da configuração das aplicações (incluindo _default e substituições por ferramenta):

{ "method": "config/read", "id": 60, "params": { "includeLayers": false } }
{ "id": 60, "result": {
  "config": {
    "apps": {
      "_default": {
        "enabled": true,
        "destructive_enabled": true,
        "open_world_enabled": true,
        "approvals_reviewer": "user",
        "default_tools_approval_mode": "auto"
      },
      "google_drive": {
        "enabled": true,
        "destructive_enabled": false,
        "approvals_reviewer": "auto_review",
        "default_tools_approval_mode": "prompt",
        "tools": {
          "files/delete": { "enabled": false, "approval_mode": "approve" }
        }
      }
    }
  }
} }

apps._default.approvals_reviewer define o revisor para todas as aplicações, salvo se um valor por aplicação o substituir. Quando ambos são omitidos, a aplicação herda o valor approvals_reviewer de nível superior. apps._default.default_tools_approval_mode define o modo de aprovação de contingência para ferramentas sem uma substituição por aplicação ou por ferramenta. Os requisitos geridos do modo de aprovação substituem as definições do modo de aprovação das ferramentas.

Atualize a definição de uma única aplicação:

{
  "method": "config/value/write",
  "id": 61,
  "params": {
    "keyPath": "apps.google_drive.default_tools_approval_mode",
    "value": "prompt",
    "mergeStrategy": "replace"
  }
}

Aplique várias edições de aplicações de forma atómica:

{
  "method": "config/batchWrite",
  "id": 62,
  "params": {
    "edits": [
      {
        "keyPath": "apps._default.destructive_enabled",
        "value": false,
        "mergeStrategy": "upsert"
      },
      {
        "keyPath": "apps.google_drive.tools.files/delete.approval_mode",
        "value": "approve",
        "mergeStrategy": "upsert"
      }
    ]
  }
}

Detetar e importar a configuração de agentes externos

Utilize externalAgentConfig/detect para detetar artefactos de agentes externos que podem ser migrados e, em seguida, transmita as entradas selecionadas para externalAgentConfig/import.

Exemplo de deteção:

{ "method": "externalAgentConfig/detect", "id": 63, "params": {
  "includeHome": true,
  "cwds": ["/Users/me/project"]
} }
{ "id": 63, "result": {
  "items": [
    {
      "itemType": "AGENTS_MD",
      "description": "Import /Users/me/project/CLAUDE.md to /Users/me/project/AGENTS.md.",
      "cwd": "/Users/me/project"
    },
    {
      "itemType": "SKILLS",
      "description": "Copy skill folders from /Users/me/.claude/skills to /Users/me/.agents/skills.",
      "cwd": null
    }
  ]
} }

Exemplo de importação:

{ "method": "externalAgentConfig/import", "id": 64, "params": {
  "migrationItems": [
    {
      "itemType": "AGENTS_MD",
      "description": "Import /Users/me/project/CLAUDE.md to /Users/me/project/AGENTS.md.",
      "cwd": "/Users/me/project"
    }
  ],
  "source": "claude-code"
} }
{ "id": 64, "result": { "importId": "8ae96ff3-3425-4f4c-8772-b6fd61502868" } }

O parâmetro de importação opcional de nível superior source identifica o produto que produziu os itens de migração selecionados.

O servidor emite externalAgentConfig/import/progress à medida que os tipos de itens são concluídos e externalAgentConfig/import/completed depois de todas as importações síncronas e em segundo plano terminarem. Estas notificações incluem o mesmo importId da resposta e itemTypeResults com successes e failures por tipo. A conclusão pode ocorrer imediatamente após a resposta ou depois de terminarem as importações remotas em segundo plano.

{ "method": "externalAgentConfig/import/progress", "params": {
  "importId": "8ae96ff3-3425-4f4c-8772-b6fd61502868",
  "itemTypeResults": [
    {
      "itemType": "AGENTS_MD",
      "successes": [
        { "itemType": "AGENTS_MD", "cwd": "/Users/me/project", "source": null, "target": "/Users/me/project/AGENTS.md" }
      ],
      "failures": []
    }
  ]
} }
{ "method": "externalAgentConfig/import/completed", "params": {
  "importId": "8ae96ff3-3425-4f4c-8772-b6fd61502868",
  "itemTypeResults": [
    {
      "itemType": "AGENTS_MD",
      "successes": [
        { "itemType": "AGENTS_MD", "cwd": "/Users/me/project", "source": null, "target": "/Users/me/project/AGENTS.md" }
      ],
      "failures": []
    }
  ]
} }

Leia as importações anteriormente concluídas:

{ "method": "externalAgentConfig/import/readHistories", "id": 65 }
{ "id": 65, "result": { "data": [
  {
    "importId": "8ae96ff3-3425-4f4c-8772-b6fd61502868",
    "completedAtMs": 1781784000000,
    "successes": [
      { "itemType": "AGENTS_MD", "cwd": "/Users/me/project", "source": null, "target": "/Users/me/project/AGENTS.md" }
    ],
    "failures": []
  }
] } }

Os valores itemType suportados são AGENTS_MD, CONFIG, SKILLS, PLUGINS, MCP_SERVER_CONFIG, SUBAGENTS, HOOKS, COMMANDS e SESSIONS. Para itens PLUGINS, details.plugins apresenta cada marketplaceName e o pluginNames que o Codex pode tentar migrar. A deteção devolve apenas itens em que ainda há trabalho por fazer. Por exemplo, o Codex ignora a migração de AGENTS quando AGENTS.md já existe e não está vazio, e as importações de skills não substituem diretórios de skills existentes.

Ao detetar plugins de .claude/settings.json, o Codex lê as fontes de marketplace configuradas em extraKnownMarketplaces. Se enabledPlugins contiver plugins de claude-plugins-official, mas a fonte de marketplace estiver em falta, o Codex infere anthropics/claude-plugins-official como a fonte.

Endpoints de autenticação

A superfície JSON-RPC de autenticação/conta disponibiliza métodos de pedido/resposta e notificações iniciadas pelo servidor (sem id). Utilize-os para determinar o estado de autenticação, iniciar ou cancelar inícios de sessão, terminar a sessão, inspecionar os limites de utilização do ChatGPT e notificar os proprietários do espaço de trabalho sobre créditos esgotados ou limites de utilização.

Modos de autenticação

O Codex suporta estes modos de autenticação. account/updated.authMode apresenta o modo ativo e inclui o planType atual do ChatGPT, quando disponível. account/read também apresenta detalhes da conta e do plano.

API key (apikey) - o autor da chamada fornece uma OpenAI API key através de type: "apiKey", e o Codex guarda-a para pedidos à API.
Gerido pelo ChatGPT (chatgpt) - o Codex gere o fluxo OAuth do ChatGPT, mantém os tokens e atualiza-os automaticamente. Comece com type: "chatgpt" para o fluxo no navegador ou type: "chatgptDeviceCode" para o fluxo com código de dispositivo.
Tokens externos do ChatGPT (chatgptAuthTokens) - experimental e destinado a aplicações anfitriãs que já gerem o ciclo de vida da autenticação do ChatGPT do utilizador. A aplicação anfitriã fornece diretamente um accessToken, chatgptAccountId e um chatgptPlanType opcional, e tem de atualizar o token quando tal for solicitado.
Amazon Bedrock - account/read apresenta contas Bedrock como type: "amazonBedrock" e indica se as credenciais provêm de uma Bedrock API key gerida pelo Codex (credentialSource: "codexManaged") ou da cadeia externa de credenciais AWS (credentialSource: "awsManaged"). account/updated.authMode utiliza bedrockApiKey para Bedrock API keys geridas pelo Codex.

Descrição geral da API

account/read - obter as informações atuais da conta; atualizar opcionalmente os tokens.
account/login/start - iniciar a sessão (apiKey, chatgpt, chatgptDeviceCode ou o chatgptAuthTokens experimental).
account/login/completed (notificação) - emitida quando termina uma tentativa de início de sessão (com êxito ou erro).
account/login/cancel - cancelar um início de sessão gerido do ChatGPT pendente através de loginId.
account/logout - terminar a sessão; aciona account/updated.
account/updated (notificação) - emitida sempre que o modo de autenticação muda (authMode: apikey, chatgpt, chatgptAuthTokens, agentIdentity, personalAccessToken, bedrockApiKey ou null) e inclui planType quando disponível.
account/chatgptAuthTokens/refresh (pedido do servidor) - solicitar novos tokens do ChatGPT geridos externamente após um erro de autorização.
account/rateLimits/read - obter os limites de utilização do ChatGPT.
account/rateLimits/updated (notificação) - emitida sempre que os limites de utilização do ChatGPT de um utilizador mudam.
account/sendAddCreditsNudgeEmail - pedir ao ChatGPT que envie uma mensagem de correio eletrónico ao proprietário de um espaço de trabalho sobre créditos esgotados ou um limite de utilização atingido.
account/rateLimitResetCredit/consume - consumir uma reposição de limite de utilização obtida, utilizando um valor idempotencyKey fornecido pelo autor da chamada.
account/usage/read - obter resumos da atividade dos tokens da conta ChatGPT e intervalos diários.
account/workspaceMessages/read - obter mensagens ativas do espaço de trabalho, incluindo títulos de notificações quando disponíveis.
mcpServer/oauthLogin/completed (notificação) - emitida após a conclusão de um fluxo mcpServer/oauth/login; a carga útil inclui { name, threadId, success, error? }. threadId pode ser null para fluxos OAuth limitados a uma aplicação ou a um plugin.
mcpServer/startupStatus/updated (notificação) - emitida quando muda o estado de arranque de um servidor MCP configurado; a carga útil inclui { threadId, name, status, error, failureReason }. threadId é null para um arranque limitado a uma aplicação. Em caso de falha no arranque, failureReason: "reauthenticationRequired" significa que as credenciais OAuth guardadas expiraram e não foi possível atualizá-las, pelo que o cliente deve disponibilizar a opção de voltar a ligar o servidor.

1) Verificar o estado de autenticação

Pedido:

{ "method": "account/read", "id": 1, "params": { "refreshToken": false } }

Exemplos de respostas:

{ "id": 1, "result": { "account": null, "requiresOpenaiAuth": false } }

{ "id": 1, "result": { "account": null, "requiresOpenaiAuth": true } }

{
  "id": 1,
  "result": { "account": { "type": "apiKey" }, "requiresOpenaiAuth": true }
}

{
  "id": 1,
  "result": {
    "account": {
      "type": "amazonBedrock",
      "credentialSource": "codexManaged"
    },
    "requiresOpenaiAuth": false
  }
}

{
  "id": 1,
  "result": {
    "account": {
      "type": "amazonBedrock",
      "credentialSource": "awsManaged"
    },
    "requiresOpenaiAuth": false
  }
}

{
  "id": 1,
  "result": {
    "account": {
      "type": "chatgpt",
      "email": "user@example.com",
      "planType": "pro"
    },
    "requiresOpenaiAuth": true
  }
}

Notas sobre os campos:

refreshToken (booleano): defina true para forçar a atualização de um token no modo gerido do ChatGPT. No modo de tokens externos (chatgptAuthTokens), o app-server ignora este sinalizador.
email é null quando a conta ChatGPT não tem um endereço de correio eletrónico.
requiresOpenaiAuth reflete o fornecedor ativo; quando false, o Codex pode ser executado sem credenciais da OpenAI.
O Amazon Bedrock apresenta credentialSource: "codexManaged" quando utiliza uma Bedrock API key gerida pelo Codex. Apresenta credentialSource: "awsManaged" para o caminho externo de credenciais AWS. Isto identifica a fonte de credenciais selecionada; não valida se a cadeia de credenciais AWS consegue obter credenciais.

2) Iniciar sessão com uma API key

Envie:

   {
     "method": "account/login/start",
     "id": 2,
     "params": { "type": "apiKey", "apiKey": "sk-..." }
   }

Resultado esperado:

   { "id": 2, "result": { "type": "apiKey" } }

Notificações:

   {
     "method": "account/login/completed",
     "params": { "loginId": null, "success": true, "error": null }
   }

   {
     "method": "account/updated",
     "params": { "authMode": "apikey", "planType": null }
   }

3) Iniciar sessão com o ChatGPT (fluxo no navegador)

Inicie:

   {
     "method": "account/login/start",
     "id": 3,
     "params": {
       "type": "chatgpt",
       "useHostedLoginSuccessPage": true,
       "appBrand": "chatgpt"
     }
   }

Por predefinição, uma chamada de retorno do navegador bem-sucedida redireciona para uma página local de êxito. Defina useHostedLoginSuccessPage: true para utilizar a página de êxito alojada quando não for necessário configurar a organização. Com a página de êxito alojada ativada, appBrand pode ser "codex" ou "chatgpt"; valores omitidos ou null utilizam "codex" por predefinição.

   {
     "id": 3,
     "result": {
       "type": "chatgpt",
       "loginId": "<uuid>",
       "authUrl": "https://chatgpt.com/...&redirect_uri=http%3A%2F%2Flocalhost%3A<port>%2Fauth%2Fcallback"
     }
   }

Abra authUrl num navegador; o app-server aloja a chamada de retorno local.
Aguarde pelas notificações:

   {
     "method": "account/login/completed",
     "params": { "loginId": "<uuid>", "success": true, "error": null }
   }

   {
     "method": "account/updated",
     "params": { "authMode": "chatgpt", "planType": "plus" }
   }

3b) Iniciar sessão com o ChatGPT (fluxo com código de dispositivo)

Utilize este fluxo quando o cliente gere o processo de início de sessão ou quando uma chamada de retorno do navegador for pouco fiável.

Inicie:

   {
     "method": "account/login/start",
     "id": 4,
     "params": { "type": "chatgptDeviceCode" }
   }

   {
     "id": 4,
     "result": {
       "type": "chatgptDeviceCode",
       "loginId": "<uuid>",
       "verificationUrl": "https://auth.openai.com/codex/device",
       "userCode": "ABCD-1234"
     }
   }

Apresente verificationUrl e userCode ao utilizador; o frontend gere a experiência do utilizador.
Aguarde pelas notificações:

   {
     "method": "account/login/completed",
     "params": { "loginId": "<uuid>", "success": true, "error": null }
   }

   {
     "method": "account/updated",
     "params": { "authMode": "chatgpt", "planType": "plus" }
   }

3c) Iniciar sessão com tokens do ChatGPT geridos externamente (`chatgptAuthTokens`)

Utilize este modo experimental apenas quando uma aplicação anfitriã gere o ciclo de vida da autenticação do ChatGPT do utilizador e fornece os tokens diretamente. Os clientes têm de definir capabilities.experimentalApi = true durante initialize antes de utilizarem este tipo de início de sessão.

Envie:

   {
     "method": "account/login/start",
     "id": 7,
     "params": {
       "type": "chatgptAuthTokens",
       "accessToken": "<jwt>",
       "chatgptAccountId": "org-123",
       "chatgptPlanType": "business"
     }
   }

Resultado esperado:

   { "id": 7, "result": { "type": "chatgptAuthTokens" } }

Notificações:

   {
     "method": "account/login/completed",
     "params": { "loginId": null, "success": true, "error": null }
   }

   {
     "method": "account/updated",
     "params": { "authMode": "chatgptAuthTokens", "planType": "business" }
   }

Quando o servidor recebe um 401 Unauthorized, pode solicitar tokens atualizados à aplicação anfitriã:

{
  "method": "account/chatgptAuthTokens/refresh",
  "id": 8,
  "params": { "reason": "unauthorized", "previousAccountId": "org-123" }
}
{ "id": 8, "result": { "accessToken": "<jwt>", "chatgptAccountId": "org-123", "chatgptPlanType": "business" } }

O servidor repete o pedido original após uma resposta de atualização bem-sucedida. Os pedidos expiram após cerca de 10 segundos.

4) Cancelar um início de sessão no ChatGPT

{ "method": "account/login/cancel", "id": 4, "params": { "loginId": "<uuid>" } }
{ "method": "account/login/completed", "params": { "loginId": "<uuid>", "success": false, "error": "..." } }

5) Terminar a sessão

{ "method": "account/logout", "id": 5 }
{ "id": 5, "result": {} }
{ "method": "account/updated", "params": { "authMode": null, "planType": null } }

6) Limites de utilização (ChatGPT)

{ "method": "account/rateLimits/read", "id": 6 }
{ "id": 6, "result": {
  "rateLimits": {
    "limitId": "codex",
    "limitName": null,
    "primary": { "usedPercent": 25, "windowDurationMins": 15, "resetsAt": 1730947200 },
    "secondary": null,
    "rateLimitReachedType": null
  },
  "rateLimitsByLimitId": {
    "codex": {
      "limitId": "codex",
      "limitName": null,
      "primary": { "usedPercent": 25, "windowDurationMins": 15, "resetsAt": 1730947200 },
      "secondary": null,
      "rateLimitReachedType": null
    },
    "codex_other": {
      "limitId": "codex_other",
      "limitName": "codex_other",
      "primary": { "usedPercent": 42, "windowDurationMins": 60, "resetsAt": 1730950800 },
      "secondary": null,
      "rateLimitReachedType": null
    }
  },
  "rateLimitResetCredits": {
    "availableCount": 2,
    "credits": [{
      "id": "RateLimitResetCredit_1",
      "resetType": "codexRateLimits",
      "status": "available",
      "grantedAt": 1781654400,
      "expiresAt": 1784246400,
      "title": "Rate-limit reset",
      "description": "Reset an eligible Codex rate-limit window."
    }]
  }
} }
{ "method": "account/rateLimits/updated", "params": {
  "rateLimits": {
    "limitId": "codex",
    "primary": { "usedPercent": 31, "windowDurationMins": 15, "resetsAt": 1730948100 }
  }
} }

Notas sobre os campos:

rateLimits é a vista de intervalo único retrocompatível.
rateLimitsByLimitId (quando presente) é a vista de vários intervalos indexada por limit_id medido (por exemplo, codex).
limitId é o identificador do intervalo medido.
limitName é uma etiqueta opcional do intervalo apresentada ao utilizador.
usedPercent é a utilização atual dentro do período da quota.
windowDurationMins é a duração do período da quota.
resetsAt é um carimbo de data/hora Unix (segundos) para a próxima reposição.
planType é incluído quando o servidor devolve o plano ChatGPT associado a um intervalo.
credits é incluído quando o servidor devolve os detalhes dos créditos restantes do espaço de trabalho.
rateLimitReachedType identifica o estado do limite classificado pelo servidor quando um limite é atingido.
rateLimitResetCredits contém o número disponível de reposições obtidas quando o serviço o fornece; caso contrário, é null.
rateLimitResetCredits.credits é null quando apenas o número é conhecido. Uma matriz vazia significa que o serviço obteve os detalhes e não devolveu créditos disponíveis. O serviço pode limitar as linhas de detalhes, pelo que availableCount é definitivo.
Cada linha de detalhes inclui um id opaco, resetType, status, grantedAt, expiresAt (que pode ser null), title (que pode ser null) e description (que pode ser null).
Obtenha account/rateLimits/read depois de consumir uma reposição.

7) Utilização de tokens (ChatGPT)

Utilize account/usage/read para obter os campos de resumo da atividade dos tokens do ChatGPT e intervalos diários opcionais.

{ "method": "account/usage/read", "id": 7 }
{ "id": 7, "result": {
  "summary": {
    "lifetimeTokens": 1234567,
    "peakDailyTokens": 45678,
    "longestRunningTurnSec": 540,
    "currentStreakDays": 8,
    "longestStreakDays": 14
  },
  "dailyUsageBuckets": [
    { "startDate": "2026-06-18", "tokens": 12345 }
  ]
} }

Notas sobre os campos:

Os valores summary podem ser null quando o serviço ainda não tiver devolvido essa métrica.
dailyUsageBuckets pode ser null; quando presente, cada intervalo inclui startDate e tokens.
O endpoint requer autenticação suportada pelos serviços do Codex. Funcionam a autenticação do ChatGPT, os tokens externos do ChatGPT, a identidade do agente e o token de acesso pessoal; a autenticação apenas por API key e a autenticação do Bedrock não funcionam.

8) Reposições obtidas do limite de utilização (ChatGPT)

Utilize account/rateLimitResetCredit/consume para consumir uma reposição obtida.

{ "method": "account/rateLimitResetCredit/consume", "id": 8, "params": { "idempotencyKey": "8ae96ff3-3425-4f4c-8772-b6fd61502868", "creditId": "RateLimitResetCredit_1" } }
{ "id": 8, "result": { "outcome": "reset" } }

Notas sobre os campos:

idempotencyKey não pode estar vazio. Utilize um UUID para cada tentativa lógica de resgate e reutilize o mesmo valor ao repetir essa tentativa.
creditId é opcional. Quando fornecido, tem de ser um ID opaco não vazio de account/rateLimits/read. Quando omitido, o serviço seleciona o próximo crédito disponível.
reset significa que foi consumido um crédito.
alreadyRedeemed significa que o mesmo resgate foi concluído anteriormente. Considere-o um êxito idempotente e atualize os limites da conta.
nothingToReset significa que não existe um período de limite de utilização elegível para reposição.
noCredit significa que a conta não tem créditos de reposição obtidos disponíveis.
Obtenha account/rateLimits/read depois de consumir uma reposição, em vez de deduzir os períodos atualizados a partir desta resposta.

9) Notificar o proprietário de um espaço de trabalho sobre um limite

Utilize account/sendAddCreditsNudgeEmail para pedir ao ChatGPT que envie uma mensagem de correio eletrónico ao proprietário de um espaço de trabalho quando os créditos estiverem esgotados ou for atingido um limite de utilização.

{ "method": "account/sendAddCreditsNudgeEmail", "id": 9, "params": { "creditType": "credits" } }
{ "id": 9, "result": { "status": "sent" } }

Utilize creditType: "credits" quando os créditos do espaço de trabalho estiverem esgotados ou creditType: "usage_limit" quando o limite de utilização do espaço de trabalho tiver sido atingido. Se o proprietário já tiver sido notificado recentemente, o estado da resposta é cooldown_active.

10) Mensagens do espaço de trabalho (ChatGPT)

Utilize account/workspaceMessages/read para obter as mensagens ativas do espaço de trabalho atual, incluindo títulos de notificações quando disponíveis.

{ "method": "account/workspaceMessages/read", "id": 10 }
{ "id": 10, "result": { "featureEnabled": true, "messages": [
  { "messageId": "msg_123", "messageType": "headline", "messageBody": "Workspace maintenance starts at 5pm.", "createdAt": 1781395200, "archivedAt": null }
] } }

Ligar a interface de terminal da CLI

Ligar um anfitrião remoto do Code Mode

Protocolo

Esquema das mensagens

Introdução

Primitivas fundamentais

Visão geral do ciclo de vida

Inicialização

Adesão à API experimental

Visão geral da API

Modelos

Listar modelos (model/list)

Listar funcionalidades experimentais (experimentalFeature/list)

Inspecionar um ambiente de execução (experimental)

Threads

Iniciar ou retomar uma thread

Gerir o objetivo de uma thread

Ler uma thread armazenada (sem a retomar)

Listar os turnos de uma thread

Listar threads (com paginação e filtros)

Atualizar os metadados armazenados de uma thread

Acompanhar alterações do estado da thread

Listar threads carregadas

Cancelar a subscrição de uma thread carregada

Arquivar uma thread

Eliminar um thread

Desarquivar um thread

Acionar a compactação de um thread

Executar um comando de shell num thread

Limpar terminais em segundo plano

Reverter turnos recentes

Turnos

Acesso de leitura da sandbox (ReadOnlyAccess)

Iniciar um turno

Injetar itens num thread

Orientar um turno ativo

Iniciar um turno (invocar uma skill)

Interromper um turno

Revisão

Execução de processos

Execução de comandos

Ler requisitos de administrador (configRequirements/read)

Configuração da sandbox do Windows (windowsSandbox/setupStart)

Sistema de ficheiros

Eventos

Exclusão de notificações

Eventos de pesquisa difusa de ficheiros (experimental)

Eventos de aviso

Eventos de configuração da sandbox do Windows

Eventos de turno

Itens

Deltas de itens

Erros

Aprovações

Aprovações de execução de comandos

Aprovações de alterações de ficheiros

tool/requestUserInput

Pedidos de permissão

Pedidos de elicitação do servidor MCP

Chamadas de ferramentas dinâmicas (experimental)

Aprovações de chamadas de ferramentas MCP (aplicações)

Skills

Aplicações (conectores)

Exemplos de RPC de configuração para as definições das aplicações

Detetar e importar a configuração de agentes externos

Endpoints de autenticação

Modos de autenticação

Descrição geral da API

1) Verificar o estado de autenticação

2) Iniciar sessão com uma API key

3) Iniciar sessão com o ChatGPT (fluxo no navegador)

3b) Iniciar sessão com o ChatGPT (fluxo com código de dispositivo)

3c) Iniciar sessão com tokens do ChatGPT geridos externamente (chatgptAuthTokens)

4) Cancelar um início de sessão no ChatGPT

5) Terminar a sessão

6) Limites de utilização (ChatGPT)

7) Utilização de tokens (ChatGPT)

8) Reposições obtidas do limite de utilização (ChatGPT)

9) Notificar o proprietário de um espaço de trabalho sobre um limite

10) Mensagens do espaço de trabalho (ChatGPT)

Listar modelos (`model/list`)

Listar funcionalidades experimentais (`experimentalFeature/list`)

Acesso de leitura da sandbox (`ReadOnlyAccess`)

Ler requisitos de administrador (`configRequirements/read`)

Configuração da sandbox do Windows (`windowsSandbox/setupStart`)

`tool/requestUserInput`

3c) Iniciar sessão com tokens do ChatGPT geridos externamente (`chatgptAuthTokens`)