TeamFlow

TeamFlow는 Next.js 15 기반의 로컬 우선 팀 운영 앱입니다.
기존 인증, 대시보드, 파일/태스크/회의록 기능은 유지한 상태에서 /chat에 @zootopiafresh/agent-core@0.1.3 기반 AI 에이전트 채팅을 다시 붙였습니다.

이번 반영 범위

• @zootopiafresh/agent-core@0.1.3 사용
• GitHub Packages + Yarn 4 registry/auth 설정
• Zoopibot과 같은 OpenClaw 기반 설정
• 현재 기본 권장 경로는 openai-codex
• /chat ChatGPT 스타일 UI
• thread 목록 / message 목록 / composer
• App Router API route 분리
• SSE 기반 실시간 업데이트
• requirement override 예시 포함
• yarn dev, yarn start 실행 시 gateway 자동 기동

AI 채팅 구조

서버 런타임은 아래 조합으로 구성되어 있습니다.

• createConversationRuntime
• StaticAgentRegistry
• createSpecResolver
• createMemoryConversationStore
• createOpenClawTransport

현재는 메모리 store 기반이라 서버를 재시작하면 AI thread와 메시지는 사라집니다. 이 제한은 현재 단계에서 의도된 동작입니다.

GitHub Packages 인증

@zootopiafresh/agent-core는 GitHub Packages에서 내려받습니다.

이미 레포에는 아래 설정이 반영되어 있습니다.

• .yarnrc.yml
  • @zootopiafresh scope -> https://npm.pkg.github.com
• .npmrc
  • NODE_AUTH_TOKEN 기반 auth

설치 전에 토큰을 준비하세요.

export NODE_AUTH_TOKEN="$(gh auth token)"

반복해서 쓰기 번거로우면 아래처럼 한 번에 불러올 수 있습니다.

eval "$(yarn -s auth:env)"

gh auth status에 read:packages 또는 write:packages가 없다면 갱신해야 합니다.

gh auth refresh --scopes read:packages,write:packages

설치

yarn install

OpenClaw 초기 세팅

현재 TeamFlow 기본 권장 경로는 Codex OAuth 기반 openai-codex입니다.

yarn openclaw:setup:codex

이 스크립트가 처리하는 것:

• agent-core openclaw init --provider openai-codex --model openai-codex/gpt-5.4
• .env, .env.example, run-with-openclaw.mjs, package.json 정렬
• ~/.openclaw/openclaw.json 기본 모델을 openai-codex/gpt-5.4로 정렬
• 필요하면 openclaw models auth login --provider openai-codex 실행

사전 조건:

• openclaw 실행 파일이 PATH에 있거나 OPENCLAW_CMD로 지정돼 있어야 합니다.

수동으로 진행하려면 아래 순서를 사용합니다.

yarn agent-core openclaw init --provider openai-codex --model openai-codex/gpt-5.4
./scripts/openclaw-cli.sh models auth login --provider openai-codex

초기화 후에는 다음 파일이 생성되거나 갱신됩니다.

• .env
• .env.example
• run-with-openclaw.mjs
• package.json의 OpenClaw 관련 스크립트

상태 점검:

yarn openclaw:doctor

이 레포에는 이미 위 명령으로 생성된 run-with-openclaw.mjs와 .env.example이 반영되어 있습니다.

필요한 환경 변수

openai-codex 기준으로 최소한 아래 값이 필요합니다.

OPENCLAW_URL=http://127.0.0.1:18789
OPENCLAW_GATEWAY_HOST=127.0.0.1
OPENCLAW_GATEWAY_PORT=18789
OPENCLAW_GATEWAY_TOKEN=
OPENCLAW_AGENT_ID=main
OPENCLAW_PROVIDER_MODE=openai-codex
OPENCLAW_PRIMARY_MODEL=openai-codex/gpt-5.4

주의:

• 이 경로에서는 OPENAI_API_KEY가 아니라 OpenAI Codex OAuth 로그인 정보를 사용합니다.
• 실제 인증 정보는 ~/.openclaw/agents/main/agent/auth-profiles.json의 openai-codex:default 프로필에 저장됩니다.
• OPENCLAW_URL과 OPENCLAW_GATEWAY_HOST/OPENCLAW_GATEWAY_PORT는 같은 gateway를 가리키게 맞추는 편이 안전합니다.
• .env는 git에 포함되지 않습니다.
• 실제 OpenClaw global state의 기본 모델도 openai-codex/gpt-5.4로 맞아 있어야 로그와 프로젝트 설정이 일치합니다.

Codex 인증 복구

Codex 실행 전 인증이 필요하거나 만료되었으면:

./scripts/openclaw-cli.sh models auth login --provider openai-codex

상태 확인:

./scripts/openclaw-cli.sh models status --json
yarn openclaw:doctor

그 다음 현재 실행 중인 yarn dev 또는 yarn start를 한 번 중지하고 다시 시작하세요.

Claude Code 대안 경로

Anthropic setup-token 경로를 다시 쓰고 싶다면 아래 스크립트를 사용하면 됩니다.

yarn openclaw:setup:claude-token

이 경로는 현재 anthropic:manual 프로필을 직접 갱신하는 방식으로 정리해 두었습니다.

실행

gateway 포함 기본 실행:

yarn dev

프로덕션 빌드:

yarn build

gateway 포함 프로덕션 실행:

yarn start

앱만 단독 실행하고 싶다면 아래를 씁니다.

yarn dev:app
yarn start:app

OpenClaw 상태만 따로 확인:

yarn openclaw:doctor

gateway 자동 기동 동작

run-with-openclaw.mjs는 @zootopiafresh/agent-core@0.1.3의 runner를 그대로 사용합니다.

중요한 동작:

• 단순히 포트가 열려 있다는 이유만으로 기존 gateway를 재사용하지 않습니다.
• 현재 OPENCLAW_GATEWAY_TOKEN으로 정상 probe가 되는 경우에만 기존 gateway를 재사용합니다.
• probe가 실패하면 현재 프로젝트 설정 기준으로 gateway를 다시 띄웁니다.
• 앱 종료 시 gateway도 함께 종료됩니다.

/chat 사용법

• 좌측에서 새 thread 생성
• 기존 thread 클릭 시 내용 복원
• 하단 composer에서 메시지 전송
• SSE로 run 상태와 메시지 업데이트 반영
• requirement override 예시로 기본 / 코치 모드 선택 가능

API route는 아래 경로로 분리되어 있습니다.

• /api/agent/threads
• /api/agent/threads/[id]
• /api/agent/threads/[id]/messages
• /api/agent/threads/[id]/events

검증 명령

아래 명령 기준으로 확인했습니다.

export NODE_AUTH_TOKEN="$(gh auth token)"
yarn install
yarn openclaw:doctor
yarn typecheck
yarn lint
yarn build

또는 한 번만 불러오고 이어서 실행할 수 있습니다.

eval "$(yarn -s auth:env)"
yarn install
yarn openclaw:doctor
yarn typecheck
yarn lint
yarn build

파일 위치

이번 AI 채팅 관련 코드는 주로 아래에 있습니다.

• src/lib/agent/*
• src/components/chat/*
• src/app/api/agent/*
• src/app/(main)/chat/page.tsx
• run-with-openclaw.mjs

현재 제한사항

• AI thread와 메시지는 memory store라 서버 재시작 시 초기화됩니다.
• 현재 agent spec은 기본 assistant 1개만 등록되어 있습니다.
• 실제 응답 품질과 실행 가능 여부는 OpenClaw gateway 상태와 OpenAI Codex OAuth 인증 상태에 의존합니다.
• 현재는 SSE 기반 run/message 실시간 갱신을 제공하며, transport 특성상 토큰 단위 증분 스트리밍은 보장하지 않습니다.
• 기존 team chat 데이터 모델은 남아 있지만 /chat 화면은 이제 AI 채팅 UI를 사용합니다.