🔌 技術調査 - Codex App Server

npm install -g @openai/codex
# 最新版へアップグレード
npm install -g @openai/codex@latest

brew install codex

# Rust toolchain
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
source "$HOME/.cargo/env"

# リポジトリ取得
git clone https://github.com/openai/codex.git
cd codex

# ビルド
cargo build --release --bin codex

# または cargo install
cargo install --path codex-rs

# 方法 1: 対話ログイン（ChatGPT アカウント）
codex login

# 方法 2: デバイスコードフロー（ヘッドレス）
codex login --device-auth

# 方法 3: OpenAI API キー
export OPENAI_API_KEY="sk-proj-..."

# capability-token 方式
codex app-server --listen ws://127.0.0.1:4500 \
  --ws-auth capability-token \
  --ws-token-sha256 <hex-digest>

# signed-bearer-token 方式
codex app-server --listen ws://127.0.0.1:4500 \
  --ws-auth signed-bearer-token \
  --ws-shared-secret-file /path/to/secret

# ログレベル制御
RUST_LOG=debug codex app-server

# JSON フォーマットログ（stderr）
LOG_FORMAT=json codex app-server

# TypeScript 型定義
codex app-server generate-ts --out ./schemas

# JSON Schema バンドル
codex app-server generate-json-schema --out ./schemas

# 実験的 API の型定義
codex app-server generate-ts --experimental --out ./schemas

codex --version
codex app-server --help

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

{ "method": "initialized", "params": {} }

{
  "method": "thread/start",
  "id": 10,
  "params": {
    "model": "gpt-5.1-codex",
    "cwd": "/Users/me/project",
    "approvalPolicy": "never",
    "sandbox": "workspaceWrite",
    "personality": "friendly",
    "dynamicTools": [
      {
        "name": "lookup_ticket",
        "description": "Fetch a ticket by ID",
        "deferLoading": false,
        "inputSchema": {
          "type": "object",
          "properties": { "id": { "type": "string" } },
          "required": ["id"]
        }
      }
    ]
  }
}

// 既存スレッドを再開
{ "method": "thread/resume", "id": 11, "params": { "threadId": "thr_abc123" } }

// 既存スレッドを分岐
{ "method": "thread/fork", "id": 12, "params": { "threadId": "thr_abc123", "ephemeral": true } }

{
  "method": "turn/start",
  "id": 51,
  "params": {
    "threadId": "thr_abc123",
    "input": [
      { "type": "text", "text": "最新コードのテストを実行して" },
      { "type": "mention", "name": "Demo App", "path": "app://demo-app" },
      { "type": "image", "url": "https://example.com/design.png" },
      { "type": "localImage", "path": "/Users/me/screenshot.png" }
    ],
    "model": "gpt-5.1-codex",
    "effort": "medium"
  }
}

{ "method": "turn/steer",     "id": 52, "params": { "threadId": "thr_abc123", "expectedTurnId": "turn_xyz", "input": [{ "type": "text", "text": "RS256 を使って" }] } }
{ "method": "turn/interrupt", "id": 53, "params": { "threadId": "thr_abc123", "turnId": "turn_xyz" } }

turn/started
  └─ item/started          (type: agentMessage | commandExecution | fileChange ...)
       ├─ item/agentMessage/delta        (テキスト断片)
       ├─ item/commandExecution/outputDelta (コマンド出力断片)
       ├─ item/fileChange/patchUpdated    (パッチ断片)
       └─ item/completed
  └─ turn/diff/updated     (ファイル変更サマリー)
  └─ turn/plan/updated     (エージェント計画更新)
turn/completed

// コマンド実行承認
{ "method": "item/commandExecution/requestApproval", "id": 1001, "params": { "itemId": "cmd_001", "command": "rm -rf dist/", "reason": "Potentially destructive" } }
{ "id": 1001, "result": { "decision": "accept" } }
{ "id": 1001, "result": { "decision": "acceptForSession" } }

// ファイル変更承認
{ "method": "item/fileChange/requestApproval", "id": 1002, "params": { "itemId": "file_001", "reason": "Creating new file" } }
{ "id": 1002, "result": { "decision": "accept" } }

// 権限承認（fileSystem.write 要求の例）
{
  "method": "item/permissions/requestApproval",
  "id": 1003,
  "params": {
    "threadId": "thr_123",
    "turnId": "turn_123",
    "itemId": "call_123",
    "cwd": "/Users/me/project",
    "reason": "Select a workspace root",
    "permissions": { "fileSystem": { "write": ["/Users/me/project", "/Users/me/shared"] } }
  }
}

// 応答（付与する subset を返す。scope を省略するとターン単位）
{
  "id": 1003,
  "result": {
    "scope": "session",
    "permissions": { "fileSystem": { "write": ["/Users/me/project"] } }
  }
}

{ "error": { "code": -32001, "message": "Server overloaded; retry later." } }

async function sendWithBackpressure(send: (msg: unknown) => void, msg: unknown, maxRetries = 5) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const res = await sendAndWait(send, msg);
    if (!res.error || res.error.code !== -32001) return res;
    const delay = Math.min(1000 * 2 ** attempt + Math.random() * 200, 30000);
    await new Promise((r) => setTimeout(r, delay));
  }
  throw new Error("Server overloaded: max retries exceeded");
}

import { spawn } from "node:child_process";
import * as readline from "node:readline";

const proc = spawn("codex", ["app-server"], {
  stdio: ["pipe", "pipe", "inherit"],
});

const rl = readline.createInterface({ input: proc.stdout! });

let msgId = 0;
const pending = new Map<number, (res: unknown) => void>();

function send(msg: unknown): void {
  proc.stdin!.write(JSON.stringify(msg) + "\n");
}

function request(method: string, params: unknown): Promise<unknown> {
  const id = ++msgId;
  return new Promise((resolve) => {
    pending.set(id, resolve);
    send({ method, id, params });
  });
}

rl.on("line", (line) => {
  const msg = JSON.parse(line) as { id?: number; method?: string; result?: unknown; error?: unknown; params?: unknown };
  if (msg.id !== undefined && pending.has(msg.id)) {
    pending.get(msg.id)!(msg);
    pending.delete(msg.id);
  } else if (msg.method) {
    handleNotification(msg.method, msg.id, msg.params);
  }
});

function handleNotification(method: string, id: number | undefined, params: unknown): void {
  switch (method) {
    case "item/agentMessage/delta":
      process.stdout.write((params as { delta: string }).delta);
      break;
    case "turn/completed":
      console.log("\n[turn completed]");
      break;
    case "item/commandExecution/requestApproval":
    case "item/fileChange/requestApproval":
      if (id !== undefined) send({ id, result: "accept" });
      break;
  }
}

async function main(): Promise<void> {
  await request("initialize", {
    clientInfo: { name: "my_app", version: "0.1.0" },
    capabilities: { experimentalApi: true },
  });
  send({ method: "initialized", params: {} });

  const threadRes = await request("thread/start", {
    model: "gpt-5.1-codex",
    cwd: process.cwd(),
    approvalPolicy: "unlessTrusted",
    sandbox: "workspaceWrite",
  }) as { result: { thread: { id: string } } };
  const threadId = threadRes.result.thread.id;

  await request("turn/start", {
    threadId,
    input: [{ type: "text", text: "このリポジトリの概要を教えて" }],
  });
}

main().catch(console.error);

import WebSocket from "ws";

const ws = new WebSocket("ws://127.0.0.1:8765");

let msgId = 0;
const pending = new Map<number, (res: unknown) => void>();

function send(msg: unknown): void {
  ws.send(JSON.stringify(msg));
}

function request(method: string, params: unknown): Promise<unknown> {
  const id = ++msgId;
  return new Promise((resolve) => {
    pending.set(id, resolve);
    send({ method, id, params });
  });
}

ws.on("open", async () => {
  await request("initialize", {
    clientInfo: { name: "ws_client", version: "1.0.0" },
    capabilities: { experimentalApi: true },
  });
  send({ method: "initialized", params: {} });

  const threadRes = await request("thread/start", {
    model: "gpt-5.1-codex",
    cwd: "/Users/me/project",
  }) as { result: { thread: { id: string } } };
  const threadId = threadRes.result.thread.id;

  await request("turn/start", {
    threadId,
    input: [{ type: "text", text: "テストを実行して失敗を修正して" }],
  });
});

ws.on("message", (data: WebSocket.Data) => {
  const msg = JSON.parse(data.toString()) as { id?: number; method?: string; result?: unknown; params?: unknown };
  if (msg.id !== undefined && pending.has(msg.id)) {
    pending.get(msg.id)!(msg);
    pending.delete(msg.id);
  } else if (msg.method === "turn/completed") {
    console.log("[完了]");
    ws.close();
  } else if (msg.method === "item/commandExecution/requestApproval" && msg.id !== undefined) {
    send({ id: msg.id, result: "accept" });
  }
});

# デバッグ出力で起動
RUST_LOG=debug codex app-server --listen ws://127.0.0.1:9000

# 構造化ログ
LOG_FORMAT=json RUST_LOG=info codex app-server --listen unix:///tmp/codex.sock

Client A ──proxy──┐
Client B ──proxy──┤──Unix Socket──▶ codex app-server プロセス
Client C ──proxy──┘

codex app-server generate-ts --out ./src/generated/
codex app-server generate-json-schema --out ./schema/

import time, random

def retry_with_backoff(fn, max_retries=5, base_delay=1.0):
    for attempt in range(max_retries):
        try:
            return fn()
        except ServerOverloadedError:
            delay = base_delay * (2 ** attempt) + random.uniform(0, 1)
            time.sleep(delay)
    raise Exception("Max retries exceeded")

{
  "method": "initialize",
  "params": {
    "capabilities": {
      "optOutNotificationMethods": [
        "item/agentMessage/delta",
        "rawResponseItem/streamed"
      ]
    }
  }
}

// v1（型なし通知、レガシー）
{ "method": "notification", "params": { "type": "turn_started", "turnId": "turn_xyz" } }

// v2（型付き通知、現行）
{ "method": "turn/started", "params": { "turn": { "id": "turn_xyz", "threadId": "thr_abc", "status": "inProgress" } } }

// 推奨
{ "permissions": { "type": "profile", "id": ":workspace" } }

// レガシー
{ "sandbox": "workspaceWrite" }

# 環境変数から取得
[model_providers.openai]
env_key = "OPENAI_API_KEY"

# コマンドで動的生成
[model_providers.openai.auth]
command = ["sh", "-c", "vault kv get -field=key secret/openai"]
timeout_ms = 5000
refresh_interval_ms = 300000

// OAuth ログイン開始
{ "method": "mcpServer/oauth/login", "params": { "server": "my-mcp-server" } }

{
  "method": "command/exec",
  "params": {
    "command": ["cargo", "test", "--workspace"],
    "cwd": "/workspace/my-project",
    "timeoutMs": 120000,
    "outputBytesCap": 1048576,
    "permissionProfile": "read-only"
  }
}

{
  "method": "thread/start",
  "params": {
    "model": "gpt-5.1-codex",
    "cwd": "/workspace",
    "approvalPolicy": "never",
    "approvalsReviewer": "auto_review",
    "permissions": { "type": "profile", "id": ":workspace" }
  }
}

# ログレベルを上げて起動
RUST_LOG=trace LOG_FORMAT=json codex app-server --listen unix:///tmp/codex-debug.sock 2>codex-debug.log

// 設定要件を確認
{ "method": "configRequirements/read" }

// MCP サーバー状態を列挙
{ "method": "mcpServerStatus/list" }

// レート制限の使用率を確認
{ "method": "account/rateLimits/read" }

// スレッド一覧（カーソルページネーション。nextCursor が null で末尾）
{ "method": "thread/list", "id": 20, "params": { "cursor": null, "limit": 20 } }

// 管理者ポリシーで強制されている制約の事前確認
{ "method": "configRequirements/read", "id": 21, "params": {} }

// レート制限の使用率
{ "method": "account/rateLimits/read", "id": 22, "params": {} }

// MCP サーバー状態の列挙
{ "method": "mcpServerStatus/list", "id": 23, "params": {} }

// MCP サーバー設定の再読み込み（プロセス再起動なし）
{ "method": "config/mcpServer/reload", "id": 24, "params": {} }

// スレッドの購読解除（30 分非活動でクリーンアップ）
{ "method": "thread/unsubscribe", "id": 25, "params": { "threadId": "thr_abc123" } }

[projects."/Users/me/trusted-project"]
trust_level = "trusted"