Codex CLI에서 osFoundry 에이전트 세션으로 작업을 넘기는 방법

다 끝나면 Codex CLI는 자기가 직접 하면 안 되는 일을 osFoundry의 세션(에이전트, 팀, 루프 중 하나)에 넘길 수 있게 된다. 넘기는 건 세 가지다. 목표, 지금까지 파악한 내용의 요약, 돌려받고 싶은 결과물. 세션 오너한테 알림이 가고, 오너는 Accept and run이나 Decline을 누른다. run이 끝나면 Codex는 같은 터미널 세션에서 결과를 읽고 하던 일을 이어 간다. Runner 자리를 줘 두면 클릭 없이 상한이 걸린 run을 직접 띄울 수도 있다.

누가 뭘 하나

설정

1. 연결 만들기

osFoundry 헤더의 열쇠 아이콘을 눌러 Connected 탭("Connected agents")을 연다. "Connect in three steps" 아래에서 Assistant를 Other MCP client로 두고, Display name에 Codex CLI 같은 이름을 넣고 Add assistant를 누른다. 이 이름은 핸드오프마다 오너한테 보이니까 알아보기 쉬운 걸로 짓는 게 좋다.

예시: Codex CLI 연결이 있는 Connected agents 탭

2. Codex에 서버 붙이기(run 스코프 포함)

codex mcp add osfoundry --url https://api.osfoundry.io/api/v1/external-mcp

그다음 ~/.codex/config.toml을 열어서 이번 용도에 맞게 줄인다.

[mcp_servers.osfoundry]
url = "https://api.osfoundry.io/api/v1/external-mcp"
scopes = ["osfoundry:read", "osfoundry:write", "osfoundry:run"]
default_tools_approval_mode = "writes"
enabled_tools = [
  "list_granted_resources",
  "list_project_resources",
  "read_session_state",
  "read_session_task_result",
  "read_session_mail",
  "post_session_note",
  "propose_session_handoff",
  "cancel_session_handoff",
  "request_session_run",
]

request_session_run에 필요한 게 osfoundry:run이다. 제안만 시킬 거면 빼 두면 된다. 핸드오프와 노트는 osfoundry:write, 읽기 툴 세 개는 osfoundry:read면 충분하다. "writes"로 두면 읽기 전용이 아닌 툴 네 개 앞에서만 Codex가 확인을 받고, 읽기 툴은 그냥 통과한다.

3. 로그인

codex mcp login osfoundry

브라우저에 osFoundry의 "Connect an agent" 페이지가 뜬다. 위 스코프라면 "Requested capabilities"가 세 줄이고, 세 번째 줄이 "Run sessions where you grant a runner role"이다. 워크스페이스를 고르고 "Use pending: Codex CLI"를 선택한 다음, 승인 체크박스를 켜고 Connect를 누른다.

4. 세션이 있는 프로젝트에 연결 추가

Connected 탭으로 돌아오면 연결이 "Connected."로 바뀌어 있다. Projects에서 프로젝트를 고르고 Add to project를 누른다. 이제 프로젝트 안의 대상 세션이 보인다. 다만 아직 어느 세션에도 쓸 수는 없다.

예시: 프로젝트 하나를 추가한 Projects 섹션

5. 세션에 자리 주기

아래쪽에 "Agent, Team, and Loop sessions"가 있다. 설명문이 곧 스펙이다. Contributor로 초대하면 노트 작성과 핸드오프 제안을 할 수 있고, Runner면 run 요청까지 된다. 그래도 핸드오프는 여전히 세션 오너 승인이 필요하다.

Agent, Team, and Loop sessions
  [ Team session ▾ ]  [ Release desk ▾ ]  [ Contributor ▾ ]  [ Save role ]

예시: Agent, Team, and Loop sessions 섹션에서 Codex CLI를 팀 세션의 Contributor로 둔 화면

세션 목록에는 이 연결을 추가한 프로젝트의 세션만 나온다. 종류, 세션, 역할을 고르고 Save role을 누른다. 처음엔 Contributor로 시작하는 게 무난하다. 나중에 같은 세션에 Runner를 저장하면 역할이 바뀐다.

실제로 돌려 보면

이 글을 쓴 머신엔 Codex가 없어서 아래는 시뮬레이션한 예시다. 툴 이름과 인자 이름은 라이브 서버가 tools/list로 돌려준 것에, Codex가 MCP 툴에 붙이는 mcp__osfoundry__를 더한 거다. 저장소, 세션, 값은 전부 데모다.

Example (simulated)

> The CSV export fix is merged. Hand the customer note and the KB update
  to the osFoundry Release desk team, then tell me what they wrote.

• mcp__osfoundry__list_granted_resources {}
  ← 1 project: "Billing v2"
• mcp__osfoundry__list_project_resources {"project_id": "…", "resource_type": "team_session",
      "search": "release"}
  ← team_session "Release desk"
• mcp__osfoundry__propose_session_handoff {
      "session_type": "team_session", "session_id": "…",
      "goal": "Write the customer note for the CSV export fix and update the KB article on exports.",
      "context_summary": "Exports over 10k rows were cut at 10,000. Fixed in PR #212 (streams rows, no cap). Affects plans with scheduled exports. No data was lost; re-running an export now returns all rows.",
      "requested_output": "Draft note (<120 words) and the KB article diff, for review.",
      "max_rounds": 4, "idempotency_key": "codex-csv-212-note"}
  [Codex asks: allow this tool call? → yes]
  ← handoff pending owner review

  (in osFoundry the owner opens "Codex CLI requests a handoff" → Review handoff
   → Handoffs → Outside assistant requests → Accept and run)

• mcp__osfoundry__read_session_state {"session_type": "team_session", "session_id": "…"}
  ← running, recent task "Requested by an outside assistant"
• mcp__osfoundry__read_session_task_result {"session_type": "team_session",
      "session_id": "…", "task_id": "…"}
  ← completed: draft note + KB diff
• mcp__osfoundry__post_session_note {"session_type": "team_session", "session_id": "…",
      "subject": "Thanks, one correction",
      "body": "The fix shipped in 3.18.2, not 3.18.1.", "idempotency_key": "codex-csv-212-fix"}
  [Codex asks: allow this tool call? → yes]

The Release desk drafted a 96-word note and a KB diff that replaces the
"exports are capped at 10,000 rows" paragraph. I posted a version
correction back to the session.

오너 쪽 조작은 짧다. 알림에 "Codex CLI requests a handoff"와 "Review the request in Release desk."가 뜨고, Review handoff 버튼을 누르면 세션의 Handoffs 탭이 열린다. "Outside assistant requests" 아래에 goal이 전문으로 보이고, "Context and expected output"을 펼치면 요약과 원하는 결과물이 나온다. "Up to 4 rounds on your agent runtime" 한 줄로 이 run이 어디까지 돌지 알 수 있다. Accept and run을 누르면 큐에 들어가고("Handoff accepted and run queued"), Decline이면 끝이다.

예시: Codex CLI requests a handoff 알림과 Review handoff 버튼

예시: 세션 Handoffs 탭에 들어온 외부 어시스턴트 요청과 Accept and run, Decline 버튼

잘못 보냈으면 handoff_id를 넣어 cancel_session_handoff를 호출하면 거둘 수 있다. 오너가 승인하기 전까지만이다.

어디까지인가

제안과 run은 일부러 다른 툴이다. propose_session_handoff는 사람한테 묻는 용도다. osfoundry:write와 Contributor 자리가 필요하고, 사람이 읽을 context_summary와 requested_output이 필수고, 오너가 누르기 전엔 아무것도 시작 안 한다. request_session_run은 그 클릭을 건너뛴다. 대신 osfoundry:run과 Runner 자리가 필요하다. 오너가 자리를 줄 때 이미 한 번 눌렀다고 보는 거다. max_rounds는 둘 다 최대 10. goal은 제안이 5,000자, run이 10,000자까지다.

Codex한테 돌아오는 건 결과지, 중간 생각이 아니다. read_session_task_result는 이 연결이 시작한 태스크만 돌려준다. read_session_mail은 이 연결 앞으로 온 노트와 자기가 쓴 노트를 돌려주고, 툴 설명에도 "Internal agent analysis is excluded."라고 돼 있다. post_session_note는 이름 붙은 노트를 남길 뿐이다. 세션 에이전트가 답장은 할 수 있지만 설명대로 "does not trigger an automatic run"이다.

세션은 늘 돌던 곳에서 돈다. 핸드오프로 Codex의 모델이나 키, 저장소가 osFoundry로 넘어가는 게 아니다. 넘어가는 건 텍스트고, 세션은 자기 에이전트와 툴로 일한다. 로컬 폴더나 동기화 안 된 항목처럼 데스크톱 안에만 있는 건 닿지 않는다. 서버의 initialize 응답에도 "Local-only data is unavailable to cloud clients."라고 나온다.

권한 회수는 클릭 한 번이다. Connected 탭에서 자리를 빼거나 연결을 Revoke하면 Codex의 다음 세션 호출은 거부된다.

처음 해 보기엔 지금 손으로 돌리는 루프가 딱 좋다. Codex CLI를 Contributor로 초대하고, 저장소에서 변경을 마무리한 다음, 바뀐 점 요약을 붙여서 루프의 다음 run을 제안하게 해 보자. osFoundry 에이전트끼리 컨텍스트를 어떻게 넘기는지는 핸드오프 페이지에, Handoffs 탭 위치는 에이전트 세션 페이지에 있다.