317 lines
9.7 KiB
Markdown
317 lines
9.7 KiB
Markdown
# TradingAgents 일일 자동 리포트 설정 가이드
|
|
|
|
이 문서는 현재 저장소에 추가된 `self-hosted runner + Codex + GitHub Actions + GitHub Pages` 자동화 구성을 실제로 운영하는 방법을 처음부터 끝까지 정리한 문서입니다.
|
|
|
|
적용 대상:
|
|
- 저장소: `nornen0202/TradingAgents`
|
|
- 기본 티커: `GOOGL`, `NVDA`
|
|
- LLM 제공자: `codex`
|
|
- 모델: `gpt-5.4`
|
|
- analyst 구성: `market`, `social`, `news`, `fundamentals`
|
|
- 결과 언어: `Korean`
|
|
|
|
관련 파일:
|
|
- 설정 파일: [config/scheduled_analysis.toml](/C:/Projects/TradingAgents/config/scheduled_analysis.toml)
|
|
- 예시 설정: [config/scheduled_analysis.example.toml](/C:/Projects/TradingAgents/config/scheduled_analysis.example.toml)
|
|
- 실행 엔트리포인트: [tradingagents/scheduled/runner.py](/C:/Projects/TradingAgents/tradingagents/scheduled/runner.py)
|
|
- 정적 사이트 생성기: [tradingagents/scheduled/site.py](/C:/Projects/TradingAgents/tradingagents/scheduled/site.py)
|
|
- GitHub Actions 워크플로: [.github/workflows/daily-codex-analysis.yml](/C:/Projects/TradingAgents/.github/workflows/daily-codex-analysis.yml)
|
|
|
|
## 1. 지금 이미 준비된 것
|
|
|
|
이 저장소에는 다음이 이미 구현되어 있습니다.
|
|
|
|
- 비대화식 스케줄 실행기
|
|
- 여러 티커를 순차 실행합니다.
|
|
- `latest_available` 기준으로 최근 거래일을 자동 해석합니다.
|
|
- 실패한 티커가 있어도 다른 티커를 계속 실행할 수 있습니다.
|
|
- 결과 아카이브
|
|
- 각 실행마다 run manifest, final state, markdown report, graph log를 저장합니다.
|
|
- 웹 리포트 생성
|
|
- GitHub Pages에 바로 올릴 수 있는 정적 HTML/CSS/JSON을 생성합니다.
|
|
- GitHub Actions 워크플로
|
|
- 매일 `09:13 KST` 기준으로 실행되도록 cron이 잡혀 있습니다.
|
|
- 수동 실행도 가능합니다.
|
|
|
|
## 2. 당신이 반드시 해야 하는 작업
|
|
|
|
이 부분은 제가 대신할 수 없습니다.
|
|
|
|
### 2-1. GitHub 저장소에 변경 반영
|
|
|
|
제가 로컬 저장소에는 구현을 끝냈지만, 원격 GitHub 저장소에 반영하려면 당신이 아래 둘 중 하나를 해야 합니다.
|
|
|
|
1. 직접 commit / push
|
|
2. 다음 턴에서 저에게 commit 메시지와 push/PR 작업까지 맡기기
|
|
|
|
### 2-2. self-hosted runner 준비
|
|
|
|
Codex 로그인 상태를 유지해야 하므로 GitHub-hosted runner가 아니라 self-hosted runner가 필요합니다.
|
|
|
|
권장:
|
|
- 항상 켜져 있거나, 최소한 스케줄 시간 전에 켜져 있는 Windows 머신 1대
|
|
- 이 저장소가 체크아웃된 경로 유지
|
|
- Python 3.13 사용
|
|
- `codex` 실행 가능
|
|
|
|
### 2-3. Codex 로그인
|
|
|
|
runner 머신에서 한 번 로그인해야 합니다.
|
|
|
|
PowerShell:
|
|
|
|
```powershell
|
|
where.exe codex
|
|
codex login
|
|
```
|
|
|
|
브라우저 기반 로그인이 어려우면:
|
|
|
|
```powershell
|
|
codex login --device-auth
|
|
```
|
|
|
|
확인:
|
|
|
|
```powershell
|
|
codex --version
|
|
```
|
|
|
|
참고:
|
|
- 이 환경에서는 `codex --version`이 WindowsApps alias 때문에 바로 실패했지만, TradingAgents preflight는 실제 Codex 바이너리를 자동 탐지해서 정상 통과했습니다.
|
|
- 즉 `codex` alias가 애매해도 TradingAgents 자체는 동작할 수 있습니다.
|
|
- 그래도 runner 머신에서는 가능하면 `where.exe codex`와 실제 `codex login`이 확실히 동작하도록 맞추는 편이 안전합니다.
|
|
|
|
### 2-4. GitHub Pages 설정
|
|
|
|
GitHub 저장소 설정에서 아래 작업이 필요합니다.
|
|
|
|
1. 저장소 `Settings`로 이동
|
|
2. 왼쪽 `Pages` 선택
|
|
3. `Build and deployment`의 `Source`를 `GitHub Actions`로 선택
|
|
|
|
이 단계는 GitHub UI 권한이 필요해서 당신이 해야 합니다.
|
|
|
|
### 2-5. self-hosted runner 등록
|
|
|
|
저장소 `Settings > Actions > Runners`에서 runner를 등록해야 합니다.
|
|
|
|
일반 순서:
|
|
1. 저장소 `Settings`
|
|
2. `Actions`
|
|
3. `Runners`
|
|
4. `New self-hosted runner`
|
|
5. Windows 선택
|
|
6. GitHub가 보여주는 등록 스크립트를 runner 머신에서 실행
|
|
|
|
runner label은 워크플로가 현재 아래를 요구합니다.
|
|
|
|
```yaml
|
|
runs-on: [self-hosted, Windows]
|
|
```
|
|
|
|
즉 `self-hosted`, `Windows` 라벨이 붙은 러너면 됩니다.
|
|
|
|
### 2-6. 선택이지만 강력 권장: 아카이브 경로 영속화
|
|
|
|
지금 기본 설정은 저장소 내부의 `./.runtime/tradingagents-archive`를 쓰게 되어 있습니다.
|
|
더 안정적인 운영을 원하면 GitHub repository variable에 아래 값을 넣는 것을 권장합니다.
|
|
|
|
- 이름: `TRADINGAGENTS_ARCHIVE_DIR`
|
|
- 예시 값: `D:\TradingAgentsData\archive`
|
|
|
|
이렇게 하면 저장소를 새로 checkout해도 이력 데이터가 유지됩니다.
|
|
|
|
저장소 변수 위치:
|
|
- `Settings > Secrets and variables > Actions > Variables`
|
|
|
|
## 3. 빠른 실행 순서
|
|
|
|
### 3-1. 로컬 확인
|
|
|
|
```powershell
|
|
Set-Location C:\Projects\TradingAgents
|
|
.\.venv-codex\Scripts\Activate.ps1
|
|
python -m pip install -e .
|
|
python -m tradingagents.scheduled --config config/scheduled_analysis.toml --label manual-local
|
|
```
|
|
|
|
실행 후 확인 경로:
|
|
- 아카이브: [config/scheduled_analysis.toml](/C:/Projects/TradingAgents/config/scheduled_analysis.toml)의 `archive_dir`
|
|
- 사이트: [site](/C:/Projects/TradingAgents/site)
|
|
|
|
### 3-2. GitHub Actions 수동 실행
|
|
|
|
1. GitHub 저장소의 `Actions` 탭 이동
|
|
2. `Daily Codex Analysis` 선택
|
|
3. `Run workflow` 클릭
|
|
4. 필요 시:
|
|
- `tickers`: 예: `GOOGL,NVDA,MSFT`
|
|
- `trade_date`: 예: `2026-04-04`
|
|
- `site_only`: `true` 또는 `false`
|
|
5. 실행
|
|
|
|
입력 의미:
|
|
- `tickers`: 설정 파일의 티커를 일회성으로 덮어씁니다.
|
|
- `trade_date`: `latest_available` 대신 특정 날짜를 강제합니다.
|
|
- `site_only`: 새 분석 없이 기존 아카이브만 다시 Pages로 재배포합니다.
|
|
|
|
## 4. 매일 자동 실행 방식
|
|
|
|
현재 워크플로 cron:
|
|
|
|
```yaml
|
|
- cron: "13 0 * * *"
|
|
```
|
|
|
|
이 값은 UTC 기준이므로 한국 시간으로는 매일 `09:13`입니다.
|
|
|
|
왜 `09:00`이 아니라 `09:13`인가:
|
|
- GitHub 문서상 scheduled workflow는 부하가 높은 시각, 특히 정각 부근에서 지연되거나 드롭될 수 있습니다.
|
|
- 그래서 정각보다 몇 분 비켜서 잡는 편이 안전합니다.
|
|
|
|
## 5. 산출물 구조
|
|
|
|
예시 run 디렉터리:
|
|
|
|
```text
|
|
archive/
|
|
latest-run.json
|
|
runs/
|
|
2026/
|
|
20260405T080047_real-smoke/
|
|
run.json
|
|
tickers/
|
|
GOOGL/
|
|
NVDA/
|
|
engine-results/
|
|
```
|
|
|
|
티커별 주요 파일:
|
|
- `analysis.json`: 실행 요약
|
|
- `final_state.json`: TradingAgents 최종 상태
|
|
- `report/complete_report.md`: 통합 마크다운 리포트
|
|
- `full_states_log_<date>.json`: graph 상태 로그
|
|
- 실패 시 `error.json`
|
|
|
|
사이트 구조:
|
|
|
|
```text
|
|
site/
|
|
index.html
|
|
feed.json
|
|
runs/<run_id>/index.html
|
|
runs/<run_id>/<ticker>.html
|
|
downloads/<run_id>/<ticker>/*
|
|
```
|
|
|
|
## 6. 설정 변경 방법
|
|
|
|
기본 티커를 바꾸려면 [config/scheduled_analysis.toml](/C:/Projects/TradingAgents/config/scheduled_analysis.toml)에서 이 부분만 수정하면 됩니다.
|
|
|
|
```toml
|
|
[run]
|
|
tickers = ["GOOGL", "NVDA"]
|
|
```
|
|
|
|
연구 깊이를 올리려면:
|
|
|
|
```toml
|
|
max_debate_rounds = 3
|
|
max_risk_discuss_rounds = 3
|
|
```
|
|
|
|
주의:
|
|
- 값이 커질수록 실행 시간과 Codex 사용량이 늘어납니다.
|
|
|
|
## 7. 가장 추천하는 운영 형태
|
|
|
|
### 최소 운영
|
|
|
|
- runner 머신 1대
|
|
- `codex login` 1회
|
|
- GitHub Pages 공개 배포
|
|
- `GOOGL`, `NVDA` 일일 실행
|
|
|
|
### 안정 운영
|
|
|
|
- runner 머신 1대 고정
|
|
- `TRADINGAGENTS_ARCHIVE_DIR`를 저장소 밖 영속 경로로 지정
|
|
- Windows 부팅 시 runner 자동 시작
|
|
- 주 1회 정도 Actions 실행 기록 점검
|
|
|
|
## 8. 트러블슈팅
|
|
|
|
### `Missing config/scheduled_analysis.toml`
|
|
|
|
원인:
|
|
- 실제 설정 파일이 아직 저장소에 없음
|
|
|
|
해결:
|
|
- 현재는 이미 [config/scheduled_analysis.toml](/C:/Projects/TradingAgents/config/scheduled_analysis.toml)을 추가해 두었습니다.
|
|
|
|
### Codex 인증 오류
|
|
|
|
원인:
|
|
- runner 머신에서 로그인 안 됨
|
|
|
|
해결:
|
|
|
|
```powershell
|
|
codex login
|
|
```
|
|
|
|
또는:
|
|
|
|
```powershell
|
|
codex login --device-auth
|
|
```
|
|
|
|
### Pages가 비어 있음
|
|
|
|
확인 순서:
|
|
1. `Actions` 탭에서 `Daily Codex Analysis` 실행 성공 여부 확인
|
|
2. `Settings > Pages`에서 Source가 `GitHub Actions`인지 확인
|
|
3. workflow의 `deploy` job 성공 여부 확인
|
|
|
|
### 스케줄이 안 뜸
|
|
|
|
확인 순서:
|
|
1. workflow 파일이 default branch에 있는지 확인
|
|
2. 저장소에 최근 60일 내 활동이 있었는지 확인
|
|
3. cron이 UTC 기준임을 확인
|
|
|
|
## 9. 제가 이미 직접 검증한 것
|
|
|
|
이 저장소 로컬 환경에서 아래를 확인했습니다.
|
|
|
|
- `Codex preflight` 성공
|
|
- Codex 계정 읽기 성공
|
|
- 모델 목록에서 `gpt-5.4` 확인
|
|
- mock 기반 자동화 테스트 통과
|
|
- 실제 `SPY` 1티커 end-to-end 스모크 런 성공
|
|
- 시작: `2026-04-05 08:00:47 +09:00`
|
|
- 종료: `2026-04-05 08:06:24 +09:00`
|
|
- 거래일 해석: `2026-04-02`
|
|
- 최종 decision: `SELL`
|
|
|
|
## 10. 이번 요청 기준 정리
|
|
|
|
현재 상태에서 당신이 해야 하는 최소 작업은 아래입니다.
|
|
|
|
1. 변경사항을 원격 GitHub 저장소에 반영
|
|
2. self-hosted runner 등록
|
|
3. runner 머신에서 `codex login`
|
|
4. GitHub Pages Source를 `GitHub Actions`로 설정
|
|
5. 필요하면 `TRADINGAGENTS_ARCHIVE_DIR` repository variable 추가
|
|
|
|
그 외의 저장소 코드, 설정 파일, 워크플로, 문서는 지금 이 저장소에 이미 준비되어 있습니다.
|
|
|
|
## 참고 링크
|
|
|
|
- GitHub Actions `schedule` 이벤트: https://docs.github.com/en/actions/reference/workflows-and-actions/events-that-trigger-workflows
|
|
- GitHub Pages custom workflow: https://docs.github.com/en/pages/getting-started-with-github-pages/using-custom-workflows-with-github-pages
|
|
- GitHub Pages publishing source: https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site
|
|
- OpenAI Codex cloud/docs: https://developers.openai.com/codex/cloud
|
|
- OpenAI Codex app announcement: https://openai.com/index/introducing-the-codex-app/
|