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

O app-server do Codex é 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 do agente transmitidos em fluxo contínuo. A implementação do app-server é de código aberto e encontra-se 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 bearer numa variável de ambiente e indique 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 sem encriptação 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 um anfitrião remoto em alternativa, indique 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 na 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 predefinido do app-server do Codex ou de um caminho de socket Unix personalizado, utilizando o handshake 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 fornece sondagens 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. Os 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 fora da interface de loopback permitem ligações não autenticadas por predefinição; por isso, configure a autenticação WebSocket antes de expor um remotamente.

Opções de autenticação WebSocket suportadas:

--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 bearer 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 o handshake WebSocket, e o app-server aplica a autenticação antes de JSON-RPC initialize.

Prefira --ws-token-file a indicar tokens bearer em bruto na linha de comandos. Utilize --ws-token-sha256 apenas quando o cliente mantiver o token em bruto de alta entropia num ficheiro de segredos local separado; o hash é apenas um verificador e os clientes continuam a precisar 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 de crescimento exponencial e 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 envie initialize, seguido da notificação initialized.
Inicie uma thread e um turno e, em seguida, 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" } });

Conceitos 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 subsequente do agente. 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, entre outros).

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

Descriçã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 deste handshake.
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, entre outros.
Orientar um turno ativo: chame turn/steer para acrescentar uma entrada do utilizador ao turno atualmente em curso sem criar um novo turno.
Transmitir eventos: após turn/start, continue a ler as notificações em 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, além dos 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 para esta 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 aplicações de ambiente de trabalho que forneçam certificaçã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: use 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 seja adicionada a uma lista de clientes conhecidos. Para obter mais contexto, consulte a referência dos 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 desativação seletiva 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 rejeita 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

Descrição geral da API

thread/start - cria um novo thread; emite thread/started e subscreve-o automaticamente nos eventos de turno/item desse thread.
thread/resume - reabre um thread existente pelo id, para que as chamadas turn/start posteriores sejam acrescentadas ao mesmo.
thread/fork - bifurca um thread num novo id de thread, copiando o histórico armazenado. Transmita lastTurnId para copiar o histórico até esse turno e omitir os turnos posteriores, ou ephemeral: true para criar uma bifurcação em memória. Emite thread/started para o novo thread; os threads devolvidos incluem forkedFromId quando disponível.
thread/read - lê um thread armazenado pelo id sem o retomar; defina includeTurns para devolver o histórico completo de turnos. Os objetos thread devolvidos incluem o 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 o status de execução.
thread/turns/list - experimental; percorre, por páginas, o histórico de turnos de um thread armazenado sem o 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 persistidos de um thread, opcionalmente limitados a um único turnId. O armazenamento ativo de threads tem de suportar a paginação de itens.
thread/loaded/list - apresenta os ids dos threads atualmente carregados em memória.
thread/name/set - define ou atualiza o nome de um thread apresentado ao utilizador, para um thread carregado ou uma execução persistida; emite thread/name/updated.
thread/goal/set - define o objetivo de um thread; emite thread/goal/updated.
thread/goal/get - lê o objetivo atual de um thread.
thread/goal/clear - limpa o objetivo de um thread; emite thread/goal/cleared.
thread/metadata/update - aplica uma atualização parcial aos metadados armazenados de threads com suporte de SQLite, incluindo gitInfo e isPinned persistidos.
thread/archive - move o ficheiro de registo de um thread para o diretório de arquivamento e tenta arquivar os registos dos threads descendentes gerados que ainda não estejam arquivados; devolve {} em caso de êxito e emite thread/archived para cada thread arquivado.
thread/delete - elimina permanentemente um thread ativo ou arquivado persistido e todos os threads descendentes gerados; devolve {} em caso de êxito e emite thread/deleted para cada thread eliminado.
thread/unsubscribe - cancela a subscrição desta ligação nos eventos de turno/item do thread. Se este era o último subscritor, o servidor descarrega o thread após um período de tolerância de inatividade sem subscritores e emite thread/closed.
thread/unarchive - restaura uma execução 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 um thread carregado é alterado.
thread/compact/start - aciona a compactação do histórico de conversas de um 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 num thread. É executado fora do sandbox, com acesso total, e não herda a política de sandbox do thread.
thread/backgroundTerminals/clean - para todos os terminais em segundo plano em execução de um thread (experimental; requer capabilities.experimentalApi).
thread/backgroundTerminals/list - apresenta os terminais em segundo plano em execução de um thread carregado (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 persiste um marcador de reversão; devolve o thread atualizado.
turn/start - adiciona uma entrada do utilizador ou uma saída de ferramenta executada pelo cliente a um 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 não processados da Responses API ao histórico visível para o modelo de um thread carregado, sem iniciar um turno do utilizador.
turn/steer - acrescenta uma entrada do utilizador ao turno ativo em curso de um 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 um thread; emite os itens enteredReviewMode e exitedReviewMode.
command/exec - executa um único comando no sandbox do servidor sem iniciar um thread/turno.
command/exec/write - escreve bytes de stdin numa sessão command/exec em execução ou fecha stdin.
command/exec/resize - redimensiona uma sessão command/exec em execução com suporte de PTY.
command/exec/terminate - para uma sessão command/exec em execução.
command/exec/outputDelta (notificação) - emitida para blocos de stdout/stderr codificados em base64 provenientes de uma sessão command/exec de transmissão contínua.
process/spawn - inicia uma sessão de processo explícita fora do sandbox do Codex (experimental; requer capabilities.experimentalApi).
process/writeStdin - escreve bytes de stdin numa sessão process/spawn em execução ou fecha stdin (experimental).
process/resizePty - redimensiona uma sessão de processo em execução com suporte de 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 continuamente e o estado de saída do processo (experimental).
model/list - apresenta 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 - apresenta sinalizadores de funcionalidades com metadados da fase do ciclo de vida e paginação por cursor.
experimentalFeature/enablement/set - aplica uma atualização parcial às definições de execução em 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 o respetivo shell e diretório de trabalho predefinido.
permissionProfile/list - apresenta perfis de permissões beta e indica se os requisitos efetivos os permitem, com paginação por cursor.
collaborationMode/list - apresenta predefinições do modo de colaboração (experimental, sem paginação).
skills/list - apresenta competências para um ou mais valores cwd (suporta forceReload e o perCwdExtraUserRoots opcional).
skills/extraRoots/set - substitui as raízes adicionais ao nível do processo utilizadas para detetar competências autónomas, sem as persistir.
skills/changed (notificação) - emitida quando são alterados ficheiros locais de competências monitorizados.
hooks/list - apresenta hooks de ciclo de vida detetados para um ou mais valores cwd.
marketplace/add - adiciona um marketplace remoto de plugins e persiste-o na configuração de marketplaces do utilizador.
marketplace/remove - remove um marketplace configurado e, quando presente, a raiz do marketplace instalado.
marketplace/upgrade - atualiza um marketplace Git configurado ou todos os marketplaces Git configurados quando o nome do marketplace é omitido.
plugin/list - em desenvolvimento; apresenta os marketplaces de plugins detetados e o estado dos plugins, incluindo metadados de políticas de instalação/autenticação, erros de carregamento do marketplace, ids de plugins em destaque e metadados de origem de plugins locais, Git, de registo de pacotes ou remotos. Os resumos podem incluir version remoto, localVersion local, ícones estruturados para os temas claro/escuro e installPolicySource, que pode ser null, WORKSPACE_SETTING ou IMPLICIT_CANONICAL_APP para linhas remotas atuais. Ainda não invoque este método em clientes de produção.
plugin/read - em desenvolvimento; lê um plugin por caminho do marketplace ou por nome do marketplace remoto e nome do plugin, incluindo competências agrupadas, apps, nomes de servidores MCP e um shareUrl de plugin remoto quando o catálogo remoto o fornece. Ainda não invoque este método em clientes de produção.
plugin/install - em desenvolvimento; instala um plugin a partir do caminho de um marketplace ou do nome de um marketplace remoto. Ainda não invoque este método em clientes de produção.
plugin/uninstall - em desenvolvimento; desinstala um plugin instalado. Ainda não invoque este método em clientes de produção.
plugin/skill/read - lê, a pedido, o Markdown de uma competência de plugin remoto através do marketplace remoto, do id do plugin e do nome da competência.
app/installed - lê o estado de execução das apps instaladas, incluindo os estados efetivos de ativação e disponibilidade para chamada de cada app.
app/list - apresenta as apps (conectores) disponíveis, com paginação e metadados de acessibilidade/ativação.
app/read - obtém metadados e resumos opcionais de ferramentas destinados apenas à apresentação para 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 1–3 perguntas breves 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 dados estruturados de um formulário 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 das permissões de rede ou do sistema de ficheiros solicitadas pela ferramenta request_permissions incorporada.
config/mcpServer/reload - recarrega do disco a configuração dos servidores MCP e coloca em fila uma atualização para os threads carregados.
mcpServerStatus/list - apresenta servidores MCP, ferramentas, recursos e o estado de 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 um thread.
mcpServer/startupStatus/updated (notificação) - emitida quando o estado de arranque de um servidor MCP configurado é alterado para um thread carregado.
windowsSandbox/setupStart - inicia a configuração do sandbox do Windows para o modo elevated ou unelevated; devolve rapidamente e emite posteriormente windowsSandbox/setupCompleted.
feedback/upload - envia um relatório de comentários (classificação + motivo/registos opcionais + id da conversa, além de 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 o cwds opcional; cada item detetado inclui cwd (null para o diretório pessoal).
externalAgentConfig/import - aplica os itens de migração de agentes externos selecionados, transmitindo migrationItems explícito com cwd (null para o diretório 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/valor de configuração no config.toml do utilizador no disco.
config/batchWrite - aplica atomicamente alterações de configuração ao config.toml do utilizador no disco.
configRequirements/read - obtém requisitos de requirements.toml e/ou do MDM, incluindo a configuração gerida exata, listas de permissões, featureRequirements afixados e requisitos de rede (ou null caso ainda não tenha 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 marketplaces com suporte Git devolvem { "type": "git", "url": ..., "path": ..., "refName": ..., "sha": ... }, as entradas de registos de pacotes devolvem { "type": "npm", "package": ..., "version": ..., "registry": ... } e as entradas de catálogos remotos devolvem { "type": "remote" }. Para entradas de catálogos exclusivamente remotas, PluginMarketplaceEntry.path pode ser null; indique 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 - indica se o modelo está oculto na lista predefinida do seletor.
inputModalities - tipos de entrada suportados pelo modelo (por exemplo, text, image).
supportsPersonality - indica se o modelo suporta instruções específicas da personalidade, como /personality.
isDefault - indica 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 não estiver presente (catálogos de modelos mais antigos), trate-o como ["text", "image"] para manter a retrocompatibilidade.

Listar funcionalidades experimentais (`experimentalFeature/list`)

Utilize este ponto final para detetar sinalizadores de funcionalidades com metadados e 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 que não sejam 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 no mesmo. 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 caminhos nativa do ambiente. Os IDs de ambiente desconhecidos e as falhas de ligação ou protocolo devolvem erros de pedido.

Threads

thread/read lê uma thread armazenada sem a subscrever; defina includeTurns para incluir os 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 de threads persistidos, com a possibilidade de os restringir a um turno.
thread/list suporta paginação por cursor, além de modelProviders, sourceKinds, archived, isPinned, cwd, useStateDbOnly, searchTerm e a filtragem experimental parentThreadId ou ancestorThreadId.
thread/loaded/list devolve os IDs das threads atualmente na memória.
thread/archive move o registo JSONL persistido da thread para o diretório de arquivamento e tenta arquivar os registos das threads descendentes geradas que ainda não estejam arquivados.
thread/delete elimina permanentemente uma thread ativa ou arquivada persistida e as respetivas threads descendentes geradas.
thread/metadata/update corrige os metadados de threads armazenados, incluindo gitInfo e isPinned persistidos.
thread/unsubscribe cancela a subscrição da ligação atual numa thread carregada e pode acionar thread/closed após um período de tolerância de inatividade.
thread/unarchive restaura uma implementação de thread arquivada no diretório de sessões ativas.
thread/compact/start aciona a compactação e devolve {} imediatamente.
thread/rollback está descontinuado. Remove os últimos N turnos do contexto em memória e regista um marcador de reversão no registo JSONL persistido da thread.
thread/inject_items acrescenta itens em bruto da Responses API ao histórico de uma thread carregada visível para o modelo sem iniciar um turno do utilizador.

Iniciar ou retomar uma thread

Inicie uma thread nova 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 para 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é o histórico paginado ser suportado.

Os clientes beta que adiram a capabilities.experimentalApi podem indicar 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 se os requisitos geridos permitem cada um deles.

thread.sessionId identifica a raiz da árvore da sessão ativa atual. As threads raiz utilizam o seu próprio ID de thread como ID da sessão; as threads bifurcadas mantêm o ID da sessão da raiz de onde provêm. Os clientes devem ler o ID da sessão em thread.sessionId, em vez de o deduzirem a partir 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 indicar 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 thread.updatedAt (nem a hora de modificação do ficheiro da implementação) por si só. 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 conseguir inicializar, thread/start e thread/resume falham, em vez de continuarem sem o mesmo.

dynamicTools em thread/start é um campo experimental (requer capabilities.experimentalApi = true). O Codex persiste estas ferramentas dinâmicas nos metadados da implementação 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, 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 persistido 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 ter conteúdo e, no máximo, 4 000 carateres. Indicar um novo objetivo substitui o objetivo existente e repõe a contabilização da utilização. Indicar o objetivo atual não terminal, ou omitir objective, atualiza o estado ou o orçamento de tokens, preservando o histórico de utilização.

Para criar uma ramificação 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. Indique 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 reter um turno parcial sem marcação.

Indique ephemeral: true para criar uma bifurcação em memória sem a adicionar às listagens 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 seja definido posteriormente um título.

Ler uma thread armazenada (sem a retomar)

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

includeTurns - quando é true, a resposta inclui os turnos da thread; quando é false ou omitido, recebe apenas o resumo da thread.
Os objetos thread devolvidos incluem o 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 anteriores com nextCursor. A resposta também inclui backwardsCursor; indique-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 dos 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 persistidos sem retomar a thread. Indique turnId para restringir 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 a 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-lhe apresentar uma interface de histórico. Por predefinição, os resultados são ordenados do mais recente para o mais antigo por createdAt. Os filtros são aplicados antes da paginação. Indique qualquer combinação de:

cursor - cadeia opaca de uma resposta anterior; omita na primeira página.
limit - se não for definido, o servidor utiliza por predefinição um tamanho de página razoável.
sortKey - created_at (predefinição), updated_at ou recency_at.
sortDirection - desc (predefinição) ou asc.
modelProviders - restringe os resultados a fornecedores específicos; um valor não definido, nulo ou uma matriz vazia inclui todos os fornecedores.
sourceKinds - restringe os resultados a origens de threads específicas. Quando omitido ou definido como [], 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 as threads com o estado de afixação persistido correspondente. Omita-o para devolver threads afixadas e não afixadas.
cwd - restringe os resultados às threads cujo diretório de trabalho atual da sessão corresponda exatamente a este caminho ou a um dos caminhos numa matriz. Os caminhos relativos são resolvidos a partir do diretório de trabalho do processo do app-server.
useStateDbOnly - quando é true, devolve os resultados da base de dados de estado sem analisar os registos JSONL das threads para reparar metadados. Omita-o ou indique false para obter o comportamento predefinido de análise e reparação.
searchTerm - restringe os resultados às threads cujo título extraído contém este fragmento de texto sensível a maiúsculas e minúsculas.
parentThreadId - restringe os resultados às threads descendentes diretas da thread principal indicada. Este filtro é experimental e requer capabilities.experimentalApi = true.
ancestorThreadId - restringe os resultados aos descendentes gerados pela thread indicada, em 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 de threads armazenados

Utilize thread/metadata/update para corrigir os metadados de threads armazenados sem retomar a thread. Defina isPinned para afixar ou desafixar a thread, ou atualize gitInfo para alterar os metadados Git persistidos. Os campos omitidos permanecem inalterados; um null explícito limpa um valor de metadados Git armazenado.

{ "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 das threads

thread/status/changed é emitido sempre que o estado de execução de uma thread carregada é alterado. O payload 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 numa 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 nessa thread.
notLoaded quando a thread não está carregada.

Se este for o último subscritor, o servidor mantém a thread carregada até que esta não tenha 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 persistido 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 geradas 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" } }

As threads arquivadas não serão apresentadas em chamadas futuras a thread/list, a menos que indique archived: true. O servidor emite uma notificação thread/archived para cada thread que arquiva efetivamente; se não for possível arquivar uma descendente gerada, o pedido pode ainda assim ser bem-sucedido sem uma notificação de arquivamento para essa descendente.

Eliminar uma thread

Utilize thread/delete para eliminar permanentemente um thread ativo ou arquivado persistente e os respetivos threads descendentes gerados. O servidor remove os ficheiros de rollout existentes e os metadados associados antes de devolver uma indicação 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 o rollout de um thread arquivado novamente 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ó devem disponibilizá-la 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 o respetivo resultado formatado é injetado no fluxo de mensagens do turno. Se o thread estiver inativo, o app-server inicia um turno autónomo para o comando de shell.

Defina timeoutMs para limitar o tempo de execução em milissegundos. Omiti-lo ou transmitir null utiliza o valor predefinido de uma hora. 0 solicita um tempo limite imediato; os valores negativos são rejeitados. O tempo limite não atrasa a confirmação RPC imediata.

{ "method": "thread/shellCommand", "id": 26, "params": { "threadId": "thr_b", "command": "git status --short", "timeoutMs": 10000 } }
{ "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 do 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 persiste 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 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).

Estrutura 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 cuidadosamente 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 } } }

Para iniciar um turno com a saída de uma ferramenta executada pelo seu cliente, transmita toolOutput com um name não vazio, um namespace opcional e uma cadeia output ou uma matriz de itens de conteúdo. Defina input como uma matriz vazia; não pode combinar toolOutput com uma entrada do utilizador não vazia.

{
  "method": "turn/start",
  "id": 31,
  "params": {
    "threadId": "thr_123",
    "input": [],
    "toolOutput": {
      "name": "run_tests",
      "namespace": null,
      "output": "All 42 tests passed."
    }
  }
}

A saída permanece como saída de ferramenta na conversa e aparece como um item functionCallOutput nas notificações e no histórico persistido. Se já estiver ativo um turno normal, o Codex coloca a saída em fila para esse turno.

Injetar itens num thread

Utilize thread/inject_items para acrescentar itens pré-construídos da Responses API ao histórico de pedidos de um thread carregado sem iniciar um turno de utilizador. Estes itens são persistidos 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 dados introduzidos pelo 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 também um item de entrada skill.

{ "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 da revisão. Os alvos incluem:

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

Utilize delivery: "inline" (predefinição) para executar a revisão no thread existente ou delivery: "detached" para criar um fork num novo thread de revisã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 a mesma estrutura, 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 o resultado do revisor no seu cliente.

Execução de processos

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

Inicie um processo com process/spawn e forneça um processHandle; em seguida, utilize esse identificador para pedidos de entrada padrão, redimensionamento e terminação. O resultado é transmitido 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 dados de entrada. Utilize process/resizePty para eventos de redimensionamento de 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 aplicação da sandbox. Para o modo de sandbox externo, 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 a mesma estrutura utilizada por turn/start (por exemplo, dangerFullAccess, readOnly, workspaceWrite, externalSandbox).
Quando omitido, timeoutMs recorre à predefinição do servidor.
Defina tty: true para sessões suportadas por PTY e utilize processId quando pretender efetuar depois pedidos com command/exec/write, command/exec/resize ou command/exec/terminate.
Defina streamStdoutStderr: true para receber notificações command/exec/outputDelta enquanto o comando estiver em execução.

Ler requisitos de administrador (`configRequirements/read`)

Utilize configRequirements/read para inspecionar os requisitos de administrador efetivos carregados de requirements.toml e/ou do 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 existem 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 da sandbox do Windows com privilégios elevados.
unelevated - executar o fluxo de configuração/verificação preliminar legado.

Sistema de ficheiros

As APIs v2 do sistema de ficheiros operam em 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 resultantes de 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 dos threads, dos turnos e dos 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 exatos de métodos em initialize.params.capabilities.optOutNotificationMethods.

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

Eventos de pesquisa aproximada de ficheiros (experimental)

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

fuzzyFileSearch/sessionUpdated - { sessionId, query, files } com as correspondências atuais da 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 não fatais em tempo de execução.

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 o diff unificado agregado mais recente 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 de ciclo de vida síncrono começa e quando o respetivo resumo final de execução fica disponível. Estas notificações não são emitidas para hooks assíncronos.
model/safetyBuffering/updated - { threadId, turnId, model, useCases, reasons, showBufferingUi, fasterModel } quando uma resposta entra no armazenamento temporário de segurança transitório.
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 requer verificação adicional da conta.
thread/tokenUsage/updated - atualizações de utilização do 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 dos turnos.

Itens

ThreadItem é a união etiquetada incluída nas respostas de 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).
functionCallOutput - {id, name, namespace, output} para uma saída de ferramenta autónoma fornecida através de turn/start.toolOutput. namespace pode ser null.
agentMessage - {id, text, phase?} que contém a resposta acumulada do agente. Quando presente, phase utiliza valores de transmissão da Responses API (commentary, final_answer).
plan - {id, text} que contém o texto do plano proposto no modo de plano. Considere autoritativo o item plan final de item/completed.
reasoning - {id, summary, content}, em que summary contém resumos de raciocínio transmitidos continuamente e content contém blocos de raciocínio não processados.
commandExecution - {id, command, cwd, status, commandActions, aggregatedOutput?, exitCode?, durationMs?}.
fileChange - {id, changes, status} que descreve as edições propostas; changes apresenta {path, kind, diff}.
mcpToolCall - {id, server, tool, status, arguments, appContext?, pluginId?, result?, error?}. Para apps MCP fidedignas, appContext pode incluir connectorId, linkId, resourceUri, appName, templateId e o actionName estável do conector. Os itens persistidos mais antigos podem omitir metadados mais recentes. Utilize appContext.resourceUri em vez do mcpAppResourceUri de nível superior obsoleto.
dynamicToolCall - {id, tool, arguments, status, contentItems?, success?, durationMs?} para invocações dinâmicas de ferramentas 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 thread/compacted legada; utilize o item contextCompaction em alternativa.

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 se abre uma nova secção do resumo.
item/reasoning/summaryPartAdded - assinala um limite entre secções do resumo de raciocínio.
item/reasoning/textDelta - transmite o 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 o resultado de texto apply_patch legado. As versões atuais do app-server já não a emitem; utilize itens fileChange e turn/diff/updated em alternativa.

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 do 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 um payload 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 da 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, o payload 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 durante a transmissão.
O cliente responde com uma das decisões de aprovação da execução de comandos acima.
serverRequest/resolved confirma que o pedido pendente foi respondido ou limpo.
item/completed devolve o item commandExecution final com status: completed | failed | declined.

Quando networkApprovalContext está presente, o pedido é relativo ao acesso gerido à rede (e não à aprovação geral de um comando de shell). O esquema v2 atual expõe o host e o protocol de destino; os clientes devem apresentar um pedido específico da rede e não pressupor que command seja uma pré-visualização do comando de shell com significado para o utilizador.

O Codex agrupa pedidos de aprovação de rede simultâneos 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 propostas changes e status: "inProgress".
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 limpo.
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 limpo pelo início, pela conclusão ou pela interrupção do 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 automaticamente o pedido após esse intervalo se o utilizador não responder.

Pedidos de permissões

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

Pedidos de obtenção de dados do servidor MCP

Um servidor MCP pode interromper um turno com mcpServer/elicitation/request. O pedido inclui threadId, um turnId opcional, serverName e uma das seguintes estruturas 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 APIs experimentais.

Os nomes das ferramentas dinâmicas e dos espaços de nomes têm de cumprir 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 pedido do servidor ao cliente.
O payload 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 (apps)

As chamadas de ferramentas de apps (conectores) também podem exigir aprovação. Quando uma chamada de ferramenta de uma app 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 a aprovação, mesmo quando a ferramenta também anuncia indicações de privilégios inferiores. Se o utilizador recusar ou cancelar, o item mcpToolCall relacionado termina com um erro, sem executar a ferramenta.

Skills

Invoque uma skill incluindo $<skill-name> na entrada de texto do utilizador. Adicione um item de entrada skill (recomendado) para que o servidor injete as instruções completas da skill, em vez de depender de o modelo 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 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 os ficheiros locais monitorizados de uma skill são alterados. 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
  }
}

Apps (conectores)

Utilize app/installed para ler o instantâneo mais recente confirmado do runtime das apps instaladas. Cada resultado inclui o id da app, runtimeName (ou null), o estado de enabled efetivo e o estado de callable. Uma app só pode ser chamada quando a configuração efetiva a ativa e pelo menos uma ferramenta visível para o modelo está em conformidade com as políticas da app 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 do runtime do conector antes de o ler. Quando uma política global ou da área de trabalho bloqueia o acesso à app, uma app observada pode continuar a aparecer com enabled e callable definidos como false.

Utilize app/list para obter as apps 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 de apps 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 app (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 apps acessíveis e as apps do diretório serem carregadas. Defina forceRefetch: true para ignorar os caches de apps e obter dados atualizados. As entradas de cache só são substituídas quando as atualizações são bem-sucedidas.

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

{
  "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á souber os IDs das apps e precisar dos respetivos metadados, em vez do estado do runtime instalado. Forneça, no máximo, 100 appIds. O servidor conserva apenas a primeira ocorrência de cada ID repetido e mantém essa ordem em apps e missingAppIds. As apps desconhecidas ou inacessíveis são devolvidas em missingAppIds sem fazer falhar 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 das ferramentas destinados apenas à apresentação. A resposta de metadados não inclui o estado do runtime das apps instaladas nem autoriza uma chamada de ferramenta; utilize app/installed para verificar os estados efetivos de enabled e callable.

Invoque uma app 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 definições de apps

Utilize config/read, config/value/write e config/batchWrite para inspecionar ou atualizar os controlos das apps em config.toml.

Leia a estrutura efetiva da configuração das apps (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 apps, salvo se um valor por app o substituir. Quando ambos são omitidos, a app 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 app ou por ferramenta. Os requisitos geridos do modo de aprovação substituem as definições do modo de aprovação das ferramentas.

Atualize uma única definição de app:

{
  "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 apps 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 descobrir artefactos de agentes externos que possam ser migrados e, em seguida, forneça as entradas selecionadas a 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 source de nível superior 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 concluídas anteriormente:

{ "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 lista cada marketplaceName e o pluginNames que o Codex pode tentar migrar. A deteção devolve apenas itens que ainda têm trabalho por realizar. 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 do marketplace configuradas em extraKnownMarketplaces. Se enabledPlugins contiver plugins de claude-plugins-official, mas a fonte do marketplace estiver em falta, o Codex deduz 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 sessão, inspecionar os limites de utilização do ChatGPT e notificar os proprietários da área 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 mostra o modo ativo e inclui o planType atual do ChatGPT, quando disponível. account/read também comunica os 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 armazena-a para pedidos à API.
Gerido pelo ChatGPT (chatgpt) - o Codex gere o fluxo OAuth do ChatGPT, persiste os tokens e atualiza-os automaticamente. Comece com type: "chatgpt" para o fluxo do browser ou com type: "chatgptDeviceCode" para o fluxo de código do dispositivo.
Tokens externos do ChatGPT (chatgptAuthTokens) - experimental e destinado a apps anfitriãs que já gerem o ciclo de vida da autenticação do utilizador no ChatGPT. A app anfitriã fornece diretamente um accessToken, chatgptAccountId e chatgptPlanType opcional, e tem de atualizar o token quando solicitado.
Amazon Bedrock - account/read comunica as 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.

Visão geral da API

account/read - obter as informações atuais da conta; opcionalmente, atualizar os tokens.
account/login/start - iniciar sessão (apiKey, chatgpt, chatgptDeviceCode ou o chatgptAuthTokens experimental).
account/login/completed (notificação) - emitida quando uma tentativa de início de sessão termina (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 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 tokens do ChatGPT atualizados e 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 um e-mail a um proprietário da área 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 de tokens da conta ChatGPT e intervalos diários.
account/workspaceMessages/read - obter mensagens ativas da área 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; o payload inclui { name, threadId, success, error? }. threadId pode ser null para fluxos OAuth limitados a apps ou plugins.
mcpServer/startupStatus/updated (notificação) - emitida quando o estado de arranque de um servidor MCP configurado muda; o payload inclui { threadId, name, status, error, failureReason }. threadId é null para um arranque limitado a uma app. Em caso de falha no arranque, failureReason: "reauthenticationRequired" significa que as credenciais OAuth armazenadas 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 da 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 e-mail.
requiresOpenaiAuth reflete o fornecedor ativo; quando é false, o Codex pode ser executado sem credenciais da OpenAI.
O Amazon Bedrock comunica credentialSource: "codexManaged" quando utiliza uma Bedrock API key gerida pelo Codex. Comunica 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 resolver credenciais.

2) Iniciar sessão com uma API key

Envie:

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

Aguarde:

   { "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 do browser)

Inicie:

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

Por predefinição, uma chamada de retorno do browser 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ária a configuração da organização. Com a página de êxito alojada ativada, appBrand pode ser "codex" ou "chatgpt"; os 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 browser; 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 de código do dispositivo)

Utilize este fluxo quando o seu cliente gerir o processo de início de sessão ou quando uma chamada de retorno do browser 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 UX.
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ã gerir o ciclo de vida da autenticação do utilizador no ChatGPT e fornecer diretamente os tokens. 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"
     }
   }

Aguarde:

   { "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 à app 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 atingem o tempo limite 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 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 pelo 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 da janela de quota.
windowDurationMins é a duração da janela de quota.
resetsAt é um carimbo de data/hora Unix (segundos) da 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 detalhes sobre o crédito restante da área de trabalho.
rateLimitReachedType identifica o estado do limite classificado pelo servidor quando um limite é atingido.
rateLimitResetCredits contém o número de reposições obtidas disponíveis 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 de 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 de 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. São compatíveis a autenticação do ChatGPT, por tokens externos do ChatGPT, por identidade do agente e por token de acesso pessoal; a autenticação apenas por API key e a autenticação do Bedrock não são compatíveis.

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 quando 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 uma janela 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 as janelas atualizadas a partir desta resposta.

9) Notificar um proprietário da área de trabalho sobre um limite

Utilize account/sendAddCreditsNudgeEmail para pedir ao ChatGPT que envie um e-mail a um proprietário da área de trabalho quando os créditos estiverem esgotados ou um limite de utilização tiver sido atingido.

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

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

10) Mensagens da área de trabalho (ChatGPT)

Utilize account/workspaceMessages/read para obter mensagens ativas da área 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

Conceitos fundamentais

Descrição geral do ciclo de vida

Inicialização

Adesão à API experimental

Descriçã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 de threads armazenados

Acompanhar alterações do estado das threads

Listar threads carregadas

Cancelar a subscrição de uma thread carregada

Arquivar uma thread

Eliminar uma 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 aproximada 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 da execução de comandos

Aprovações de alterações de ficheiros

tool/requestUserInput

Pedidos de permissões

Pedidos de obtenção de dados do servidor MCP

Chamadas de ferramentas dinâmicas (experimental)

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

Skills

Apps (conectores)

Exemplos de RPC de configuração para definições de apps

Detetar e importar a configuração de agentes externos

Endpoints de autenticação

Modos de autenticação

Visão geral da API

1) Verificar o estado da autenticação

2) Iniciar sessão com uma API key

3) Iniciar sessão com o ChatGPT (fluxo do browser)

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

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

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

5) Terminar 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 um proprietário da área de trabalho sobre um limite

10) Mensagens da área 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`)