이미 5개의 Issue가 등록되어 있었지만 아무도 해결하지 않았던 문제. TypeScript를 모르지만 Claude Code와 함께 해결하고, 프로젝트 창시자가 직접 머지해준 경험을 공유합니다.

---

🤔 시작: "아무도 안 고치면 내가 해볼까?"

OpenClaw는 GitHub 17k+ Stars의 오픈소스 AI 코딩 어시스턴트입니다. 저는 이 도구를 로컬 LLM(Ollama)과 연동하여 사용하고 싶었습니다. 그런데 문제가 있었습니다.

Ollama 모델에서 tool calling이 전혀 작동하지 않았습니다.

파일 읽기, 디렉토리 탐색, 명령어 실행 같은 도구 호출이 모두 무시되거나 실패했습니다. GitHub Issue를 검색해보니, 이미 관련 이슈가 5개나 등록되어 있었습니다. (#5769, #4028, #8630 등) 많은 사용자가 같은 문제를 겪고 있었지만, 실제로 PR을 올린 사람은 아무도 없었습니다.

그래서 생각했습니다.

"이참에 직접 해결해보면 어떨까? 오픈소스 컨트리뷰터가 되어보고 싶었는데."

한 가지 문제가 있었습니다. 저는 TypeScript를 모릅니다. 주 언어는 Java/Kotlin이고, OpenClaw의 코드베이스는 전부 TypeScript였습니다.

하지만 요즘 시대에는 AI 코딩 어시스턴트가 있지 않습니까. Claude Code를 활용하면 충분히 해결할 수 있을 거라 생각했습니다. 중요한 건 코드를 한 줄 한 줄 직접 타이핑하는 것이 아니라, 문제를 정확히 정의하고, 분석하고, 해결 방향을 설계하는 것이라고 믿었기 때문입니다.

---

🤖 Claude Code와의 협업

이 프로젝트의 전 과정에서 Claude Code를 적극적으로 활용했습니다.

내가 한 것	Claude Code가 한 것
문제 발견 및 정의	OpenClaw 코드베이스 분석
해결 방향 설계	TypeScript 구현 (760+ lines)
PR/Issue 작성 전략	38개 유닛 테스트 작성
커뮤니티 댓글 대응 방향 결정	CI 오류 수정 (lint, format, type check)
로컬 LLM 직접 테스트	코드 리뷰 피드백 반영
최종 판단과 의사결정	충돌 해결, 리팩토링

TypeScript 문법을 몰라도, "이 함수가 왜 필요한지", "이 테스트가 어떤 시나리오를 커버하는지" 는 이해할 수 있었습니다. Claude Code에게 코드베이스를 분석하게 하고, 문제의 근본 원인을 파악하게 하고, 설계 방향을 제시하면 구현은 AI가 해주었습니다.

결국 개발자의 역할은 코드를 타이핑하는 것이 아니라, 올바른 질문을 던지고 올바른 방향으로 이끄는 것이라는 걸 체감했습니다.

---

🧪 원인 분석: 3가지 근본 원인

문제 1: OpenAI 호환 엔드포인트의 한계

OpenClaw는 Ollama 연동 시 /v1/chat/completions (OpenAI 호환 shim)을 사용하고 있었습니다. 이 엔드포인트는 스트리밍 시 tool_calls 필드를 자동으로 누락시켰습니다.

문제 2: Ollama의 독특한 스트리밍 방식

Ollama는 tool_calls를 done:false인 중간 청크에서 전송합니다. OpenAI 형식의 파서는 이를 처리하지 못했습니다.

문제 3: Context Window 기본값 (4096)

Ollama의 기본 num_ctx는 4096 토큰입니다. OpenClaw의 시스템 프롬프트 + 23개 도구 정의를 합치면 이를 훨씬 초과하여, 모델이 도구 스키마 자체를 볼 수 없었습니다.

---

🛠️ 해결: Native /api/chat Provider 구현

OpenAI 호환 레이어를 우회하고, Ollama의 네이티브 /api/chat 엔드포인트와 직접 통신하는 전용 프로바이더를 설계하고 구현했습니다.

핵심 구현 포인트

구현 항목	설명
NDJSON 스트리밍 파서	줄 단위로 JSON을 파싱하여 실시간 응답 처리
메시지 포맷 변환	SDK ↔ Ollama 네이티브 프로토콜 간 양방향 변환
tool_calls 누적	중간 청크(done:false)에서 전송되는 tool_calls를 올바르게 누적
num_ctx 자동 설정	시스템 프롬프트 + 도구 정의 크기에 맞게 context window 자동 확장
에러 핸들링	연결 실패, 파싱 오류, 타임아웃 등 포괄적 처리

변경 파일 구조

src/agents/
├── ollama-stream.ts           # 🆕 네이티브 Ollama 스트리밍 클라이언트
├── ollama-stream.test.ts      # 🆕 13개 유닛 테스트
├── models-config.providers.ts # ✏️ "ollama" API 타입 등록
├── models-config.providers.ollama.test.ts  # 🆕 23개 프로바이더 설정 테스트
└── pi-embedded-runner/run/attempt.ts       # ✏️ ollama일 때 네이티브 스트림 주입

총 변경: +760 / -75 lines, 38개 유닛 테스트

---

📝 PR 제출과 커뮤니티 반응

Issue & PR 등록

• Issue: #11828 — Feature Request
• PR: #11853 — feat(ollama): add native /api/chat provider for streaming + tool calling

PR을 올린 후, 커뮤니티에서 자발적으로 다양한 모델로 테스트를 진행해주었습니다.

커뮤니티 검증 결과

모델	크기	테스터	결과
qwen3:32b	32B	@BrokenFinger98	✅ Tool calling 작동
GLM-4.7 Flash	-	@blastronaut	✅ 잘 작동
devstral-small-2:24b	24B	@stintel	✅ "It makes Ollama usable"
Qwen3-4B (GGUF)	4B	@lym000000	✅ tool_name 수정 후 작동
qwen3:4b-instruct	4B	@gonesurfing	✅ 최초 소형 모델 성공
llama3.2:3b-instruct	3B	@gonesurfing	✅ 16k context에서 작동

커뮤니티 반응

PR을 올리고 하루 만에, 댓글이 쏟아지기 시작했습니다.

"Thanks for this PR. It makes ollama usable. Tested with devstral-small-2:24b."
— @stintel

"This is excellent work! For the first time, I was able to get a small model to use a tool. ...this is already 100 times further than I've gotten so far."
— @gonesurfing

"been testing this out with GLM-4.7 Flash.. working nicely thank you."
— @blastronaut

"Pulled and tested, confirmed that it works without the additional changes. Thanks!"
— @lym000000 (스크린샷 첨부)

@gonesurfing은 이후에도 추가 테스트를 계속 진행해주었습니다:

"ollama/llama3.2:3b-instruct-q4_K_M with 16k context continues to work well with write and exec tools."
"I still think this PR fixes the underlying inability of openclaw to use tools with local ollama models."
— @gonesurfing

@lym000000은 한발 더 나아가 자신의 fork에서 tool_name 필드 누락 문제를 발견하고 직접 수정까지 해주었습니다. 이 피드백을 즉시 반영하여 커밋했고, 다시 테스트를 통해 확인했습니다. 오픈소스 협업의 선순환이 눈앞에서 일어나고 있었습니다.

처음에는 혼자서 시작한 PR이었지만, 6일 동안 10명의 참여자, 24개의 댓글, 👍 8개의 리액션이 모였습니다.

---

🎢 반전: Issue가 중복으로 닫히다

모든 것이 순탄한 것만은 아니었습니다.

2월 13일, 한 maintainer가 Issue를 기존 이슈(#5769)의 중복으로 닫았습니다. 하지만 이 PR은 단순히 문제를 보고하는 것이 아니라 해결책을 구현한 것이었습니다.

저는 정중하지만 명확하게 차이점을 설명했습니다:

"This PR is not a duplicate report — it is a working solution. The referenced issue #5769 describes the problem; this PR solves it with a native API provider, tested across 6 model families by 5 independent testers."

커뮤니티도 지지해주었고(👍 리액션 + 중복 클로즈에 👎 2개), 결국 다음 날 프로젝트 창시자인 steipete(Peter Steinberger)가 직접 리뷰하고 스쿼시 머지해주었습니다.

"Merged via squash. Thanks @BrokenFinger98!"
— @steipete (프로젝트 창시자)

머지 직후, 테스트에 참여해주었던 분들의 확인 댓글이 이어졌습니다:

"Thanks for merging this. Confirmed working."
— @gonesurfing

"It works with my setup, yes"
— @ShadowJonathan (코드 리뷰어)

머지 후에는 새로운 사용자가 설정 방법을 물어보기도 했고, 단계별 가이드를 제공하며 커뮤니티 지원을 이어갔습니다.

---

🌊 머지 이후: 다운스트림 채택

머지 후 수 시간 내에 여러 다운스트림 프로젝트에서 이 변경사항을 채택했습니다.

프로젝트	링크	내용
OpenLayer	PR #3	Ollama 네이티브 API 반영
Zee	Issue #353	Ollama 통합 개선 요청
nickytonline fork	PR #1	변경사항 포크 반영

---

📊 기여 요약

항목	수치
프로젝트 규모	GitHub ⭐ 17,000+
변경 파일	5개
커밋	13개 (squash merged)
유닛 테스트	38개 (스트리밍 15 + 프로바이더 23)
검증 모델 패밀리	6개
독립 테스터	5명
PR 참여자	9명
다운스트림 채택	3+ 프로젝트
해결한 이슈	3개 (#11828, #4028, #8630)

---

💡 배운 점

1. 커뮤니케이션이 머지를 만든다

돌이켜보면, 이 PR이 머지된 가장 큰 이유는 코드의 품질만이 아니라 커뮤니케이션이었습니다.

PR을 올리는 것만으로는 머지되지 않습니다. 커뮤니티에서 "이 변경이 정말 필요하다" 는 공감대를 만들어내는 것이 핵심이었습니다. 테스트 결과를 공유하고, 다른 사용자가 직접 검증할 수 있는 가이드를 제공하고, 피드백에 빠르게 대응한 것이 9명의 참여자와 👍 8개의 리액션으로 이어졌고, 결국 머지라는 결과를 만들었습니다.

2. 문제를 정의하는 것이 절반이다

처음에는 "Ollama에서 tool calling이 안 된다"는 단순한 증상이었지만, 파고 들어가보니 3가지 독립적인 근본 원인이 있었습니다. 증상이 아닌 원인을 찾는 것, 그리고 그 원인을 다른 사람이 이해할 수 있게 설명하는 것이 핵심이었습니다.

5개의 Issue가 이미 존재했지만 아무도 해결하지 못한 이유는, 문제가 명확하게 정의되지 않았기 때문입니다. "안 된다"는 보고는 많았지만, "왜 안 되는지"를 체계적으로 분석한 사람은 없었습니다.

3. 거절당해도 포기하지 않기

Issue가 중복으로 닫혔을 때 솔직히 당황했습니다. 하지만 사실과 근거를 바탕으로 정중하게 반박했습니다. 오픈소스에서는 코드의 품질과 커뮤니티의 지지가 결국 말해줍니다.

4. AI 시대, 개발자에게 정말 필요한 역량

이 경험을 통해 한 가지 확신이 생겼습니다.

AI Agent 시대에 개발자에게 가장 중요한 역량은 코딩 그 자체가 아닙니다.

저는 TypeScript를 모릅니다. 하지만 760줄의 TypeScript 코드와 38개의 테스트를 포함한 PR을 17k stars 프로젝트에 머지시켰습니다. Claude Code가 코드를 작성해주었지만, AI가 대신할 수 없었던 것들이 있었습니다:

• 문제를 발견하고 정의하는 눈 — 5개의 Issue를 읽고, 근본 원인 3가지를 도출한 것
• 해결 방향을 설계하는 판단력 — OpenAI 호환 레이어를 우회하고 네이티브 API를 직접 쓰자는 결정
• 사람과 소통하는 능력 — 커뮤니티를 설득하고, 테스트를 유도하고, 거절에 대응한 것
• 끝까지 밀고 나가는 끈기 — Issue가 닫히고, CI가 깨지고, 충돌이 나도 포기하지 않은 것

코드를 작성하는 능력은 AI가 점점 더 잘하게 될 것입니다. 하지만 "이 문제가 왜 발생하는가", "어떤 방향으로 해결해야 하는가", "이 해결책이 왜 필요한지 다른 사람을 어떻게 설득할 것인가" — 이런 질문에 답하는 능력은 여전히 개발자의 몫입니다.

AI는 강력한 도구입니다. 하지만 도구를 어디에 쓸지 결정하는 건 사람입니다.

---

🔗 참고 링크

• PR: https://github.com/openclaw/openclaw/pull/11853
• Issue: https://github.com/openclaw/openclaw/issues/11828
• Merge Commit: https://github.com/openclaw/openclaw/commit/11702290ff80

---

TypeScript를 모르는 Java/Kotlin 개발자가, Claude Code와 함께 GitHub 17k Stars 오픈소스에 기여한 이야기였습니다.

코드를 직접 타이핑하지 않아도, 문제를 정의하고 해결하는 과정 자체가 개발이라고 생각합니다. 오픈소스 기여에 관심 있는 분들에게 이 경험이 도움이 되면 좋겠습니다.