자체 호스팅 샌드박스

에이전트의 실행 환경을 더 세밀하게 제어하거나 신뢰할 수 있는 컴퓨팅 리소스를 사용하려면 자체 환경을 연결하세요. 노트북, 컨테이너 또는 원격 샌드박스를 실행 환경으로 사용할 수 있습니다. OpenAI가 환경을 프로비저닝하도록 하려면 OpenAI 호스팅 샌드박스를 사용하세요.

연결 방식

OpenAI는 에이전트 하네스를 실행합니다. 자체 환경에서는 실행기인 codex exec-server를 실행하세요. 실행기는 하네스의 요청에 따라 셸 명령어를 실행하고, 파일을 읽고 쓰며, 로컬 MCP 서버를 사용합니다.

실행기는 환경 ID와 권한이 제한된 API 키를 사용해 API에 등록합니다. 그런 다음 WebSocket으로 연결해 명령어를 받고 결과를 반환합니다. 모든 연결은 아웃바운드이며, 연결이 끊기면 실행기가 다시 연결합니다.

환경 준비하기

에이전트에 필요한 파일과 종속성을 준비하세요. 사용자 또는 워크로드별로 환경을 격리하세요. 환경을 공유하는 에이전트는 동일한 파일, 자격 증명 및 기타 리소스에 접근할 수 있습니다.

review: "auto_review"로 자동 검토를 활성화하려면 샌드박스를 지원하고 Codex에 샌드박스 생성 권한을 부여하는 컨테이너에서 표준 실행기를 실행하세요. 자동 검토는 workspace-write를 기본 권한으로 설정하고 네트워크 접근을 제한하는 권한 프로필을 적용합니다. 활성화하기 전에 자동 검토 사전 요구 사항을 확인하세요.

환경 안에 작업 디렉터리를 만들고 Codex CLI를 설치하세요. 다음 예시에서는 /workspace를 사용합니다.

mkdir -p /workspace
npm install -g @openai/codex@alpha

네트워크 접근

다음 호스트로의 아웃바운드 연결을 허용하세요.

• https://api.openai.com은 환경 등록에 사용합니다.
• wss://codex-cloud-environments.chatgpt.com은 명령어 수신과 결과 전송에 사용합니다.

인증

애플리케이션 요청에는 OPENAI_API_KEY를 사용하세요. 이 키에 세션 작업을 위한 api.agents.read 및 api.agents.write 권한과 모델 추론을 위한 api.responses.write 권한을 부여하세요. 애플리케이션에서 볼트를 관리한다면 api.vaults.read 및 api.vaults.write 권한도 추가하세요.

플랫폼 대시보드의 에이전트 탭에서 별도의 환경 키를 만드세요. 키는 세션과 같은 조직 및 프로젝트에 속해야 하며, 세션을 소유한 사용자 또는 서비스 계정의 키여야 합니다. 나머지 권한은 모두 없음으로 설정하세요.

애플리케이션 또는 프로비저닝 서비스에서 OPENAI_EXECUTOR_API_KEY의 값을 이 환경 키로 설정하세요. 샌드박스에는 이 값을 CODEX_API_KEY로 전달하세요. codex exec-server가 이 변수를 읽습니다. 애플리케이션의 OPENAI_API_KEY는 샌드박스 외부에 보관하세요.

에이전트가 생성한 코드는 환경 키를 읽을 수 있지만, 이 키는 환경 연결만 허용합니다. 다른 API 작업을 승인하는 데에는 사용할 수 없습니다. 소스 코드, 컨테이너 이미지, 로그에 이 키가 포함되지 않도록 하세요. 필요할 때 키를 교체하거나 폐기하세요.

세션 만들기

다음 예시는 환경 외부의 애플리케이션에서 실행하세요. 이미 자체 호스팅 세션이 있다면 해당 세션을 재사용하세요.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16import OpenAI from "openai";
const client = new OpenAI();

const session = await client.beta.agents.sessions.create({
  agent: {
    model: "gpt-6-astra",
    instructions:
      "You are a helpful coding assistant. Write clean code and verify that it works.",
  },
  environment: {
    type: "self_hosted",
    workspace_directory: "/workspace",
  },
});

console.log(session);

1
2
3
4
5
6
7
8
9
10
11
12from openai import OpenAI

client = OpenAI()

session = client.beta.agents.sessions.create(
    agent={
        "model": "gpt-6-astra",
        "instructions": "You are a helpful coding assistant. Write clean code and verify that it works.",
    },
    environment={"type": "self_hosted", "workspace_directory": "/workspace"},
)
print(session.to_json())

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23import (
	"context"
	"fmt"

	"github.com/openai/openai-go/v3"
)

ctx := context.Background()
client := openai.NewClient()
result, err := client.Beta.Agents.Sessions.New(ctx,
	openai.BetaAgentSessionNewParams{
		Agent: openai.BetaAgentSessionNewParamsAgent{
			Model:        openai.String("gpt-6-astra"),
			Instructions: openai.String("You are a helpful coding assistant. Write clean code and verify that it works."),
		},
		Environment: openai.EnvironmentParamUnion{
			OfParamSelfHosted: &openai.EnvironmentParamSelfHosted{WorkspaceDirectory: "/workspace"},
		},
	})
if err != nil {
	panic(err)
}
fmt.Println(result)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.beta.agents.EnvironmentParam;
import com.openai.models.beta.agents.sessions.SessionCreateParams;

OpenAIClient client = OpenAIOkHttpClient.fromEnv();
var result =
    client
        .beta()
        .agents()
        .sessions()
        .create(
            SessionCreateParams.builder()
                .agent(
                    SessionCreateParams.Agent.builder()
                        .model("gpt-6-astra")
                        .instructions(
                            "You are a helpful coding assistant. Write clean code and verify"
                                + " that it works.")
                        .build())
                .environment(
                    EnvironmentParam.SelfHosted.builder()
                        .workspaceDirectory("/workspace")
                        .build())
                .build());
System.out.println(result);

1
2
3
4
5
6
7
8
9
10
11
12
13
14require "openai"

client = OpenAI::Client.new
result = client.beta.agents.sessions.create(
  agent: {
    model: "gpt-6-astra",
    instructions: "You are a helpful coding assistant. Write clean code and verify that it works."
  },
  environment: {
    type: "self_hosted",
    workspace_directory: "/workspace"
  }
)
puts result

session.id를 애플리케이션의 대화 상태와 함께 저장하세요. 실행기에 session.environment.id와 session.environment.remote_url을 전달하세요. 다시 연결할 때도 원격 URL을 그대로 사용하세요. 저장된 에이전트를 사용하는 방법은 에이전트 구성을 참고하세요.

여러 세션에서 환경 이미지, workspace_directory, capability_directories를 재사용할 수 있습니다. 각 세션에는 고유한 환경 ID가 있으며 별도의 실행기가 필요합니다. API의 환경 템플릿은 OpenAI 호스팅 환경에만 적용됩니다.

실행기 시작하기

애플리케이션에서 세션 이벤트 스트림을 열어 연결 이벤트를 수신하세요. 그런 다음 앞서 설명한 대로 CODEX_API_KEY에 환경 키를 설정하고 해당 환경 안에서 다음 명령어를 실행하세요. 자리표시자는 API가 반환한 환경 값으로 바꾸세요.

123codex exec-server \
  --remote "<session.environment.remote_url>" \
  --environment-id "<session.environment.id>"

에이전트가 작업하는 동안에는 실행기를 계속 실행하세요.

작업 보내기 및 연결 모니터링

이벤트 스트림을 열어 둔 상태에서 애플리케이션을 통해 입력을 보내세요. 에이전트가 작업을 시작하려면 환경이 연결되어 있어야 하고 사용자 입력도 필요합니다.

스트림에는 다음과 같은 연결 상태가 표시됩니다.

• agent.session.environment.pending: 세션이 실행기의 연결을 기다리고 있습니다.
• agent.session.environment.connected: 환경이 준비되었습니다.
• agent.session.environment.failed: 연결에 실패했습니다. 환경 오류와 실행기 로그를 확인하세요.

스트림을 계속 모니터링해 해당 턴의 결과와 출력을 확인하세요. 애플리케이션에서 또는 웹훅을 통해 환경의 시작, 재연결, 종료를 관리하는 방법은 환경 수명 주기를 참고하세요.

샌드박스 제공업체

코드를 실행하고 파일을 다룰 샌드박스 제공업체를 선택하세요. 애플리케이션에서 프로비저닝을 관리하는 방식과 웹훅으로 관리하는 방식을 비교하려면 샌드박스 수명 주기를 참고하세요.

웹훅으로 프로비저닝을 관리하려면 샌드박스 수명 주기를 참고해 제공업체의 SDK 또는 API로 핸들러를 구현하세요. 프로비저닝 책임 주체와 리소스 정리 정책을 명확히 정하세요.