메뉴 경로: 대시보드 > 태스크 > 로컬
로컬 워커 (CLI)
개요
로컬 워커는 내 PC에 있는 파일 속 함수입니다. 그 PC에서 3Min API CLI(npm 패키지 @3minapi/cli)가 실행되면서 AI가 보낸 태스크를 가져오고, 태스크마다 입력을 넣어 함수를 실행한 뒤 결과를 회신합니다. AI와 내 PC는 직접 통신하지 않고, 그 사이에 3Min API가 있습니다.
- 공개 URL도, 열린 포트도 필요 없습니다. CLI는 바깥으로 나가는 요청만 보냅니다
- 함수가 읽은 내용은 내 PC에 남습니다. 함수가 돌려준 값만 나갑니다
- 파일 하나 = 함수 하나 = 워커 하나
공개 URL의 서버라면 태스크(퍼블릭 워커)를 보세요.
| 용어 | 뜻 |
|---|---|
| 호스트 | CLI를 실행하는 PC. 대시보드 → 태스크 → 로컬에서 PC마다 하나씩 추가 |
| 호스트 토큰 | tm_host_…. 그 PC의 CLI가 이 토큰으로 로그인합니다. 한 번만 표시 |
| 프로젝트 폴더 | 기본값 ~/3minapi: 3minapi.json, workers/, data.db, .gitignore. 호스트당 하나 |
data.db |
프로젝트 안의 SQLite 파일. 모든 결과가 여기 저장되고, 워커가 자기 데이터를 둘 수도 있음 |
| 결과 조회 워커 | data.db에 저장된 결과를 AI가 읽을 수 있도록 CLI가 등록하는 내장 로컬 워커 |
| 종류 | worker_list의 kind |
태스크가 닿는 방식 | Free | API 호출 |
|---|---|---|---|---|
| 퍼블릭 워커 | "public" |
3Min API가 내 URL로 POST | 1개 | 전달은 0콜 |
| 로컬 워커 | "local" |
CLI가 가져감 (기본은 실시간 신호, 또는 주기 확인) | 무제한 | 실시간: 할 일이 없으면 0콜. 주기 확인: 가져올 때마다 비어 있어도 1콜 |
설치와 업데이트
명령은 내 PC의 터미널에서 실행합니다 — Windows는 터미널 또는 PowerShell(시작 메뉴), macOS는 터미널(응용 프로그램 → 유틸리티)입니다.
- Node.js 24.12 이상.
node -v로 버전을 확인합니다. 없거나 오래됐다면 nodejs.org에서 LTS를 설치하고(Windows는winget install OpenJS.NodeJS.LTS도 가능) 터미널을 새로 여세요 - CLI:
npm install -g @3minapi/cli
3minapi --version
- Windows PowerShell에서 "running scripts is disabled on this system" 이라며 거부될 수 있습니다.
3minapi대신3minapi.cmd를 입력하세요 — 아무것도 바꾸지 않고 동작합니다. 내 계정에서 스크립트를 허용하고 싶다면Set-ExecutionPolicy -Scope CurrentUser RemoteSigned로 할 수 있습니다(되돌릴 때까지 그 설정이 유지됩니다) npx @3minapi/cli <command>로 설치 없이 실행할 수 있습니다- 업데이트도 같은 명령입니다:
npm install -g @3minapi/cli 3minapi doctor가 Node.js, 설정, 토큰, 네트워크, 프록시 설정을 점검하고 고칠 점을 알려 줍니다. 프록시 뒤라면NODE_USE_ENV_PROXY=1을 설정하세요
빠른 시작
로컬 탭의 설정 카드와 같은 순서입니다.
npm install -g @3minapi/cli
3minapi init
3minapi worker new hello
3minapi worker run hello --input '{"message":"hi"}'
3minapi login
3minapi start
3minapi init이~/3minapi에 프로젝트를 만듭니다(위치를 고르려면3minapi init <folder>). 이후 명령은 어느 폴더에서든 동작합니다3minapi worker new hello가 템플릿으로workers/hello.mjs를 만듭니다. 설명을 먼저 고치고, 그다음 handler를 고치세요3minapi worker run hello --input '…'은 내 PC에서 한 번 실행합니다 — 태스크도, API 호출도 없습니다. 원하는 대로 동작할 때까지 반복하세요- 대시보드 → 태스크 → 로컬 →
호스트 추가에서 토큰을 복사한 뒤,3minapi login을 실행해 프롬프트에 붙여넣으세요 3minapi start가 워커 파일을 로컬 워커로 등록하고 태스크를 실행합니다. 이제 AI가worker_list에서kind: "local"로 볼 수 있습니다
워커 파일이 없으면 start는 바로 종료됩니다.
명령
모든 명령은 어느 폴더에서든 동작합니다. --json은 기계가 읽을 수 있는 출력을 주고, 3minapi help <command>는 모든 플래그를 보여 줍니다.
호스트
| 명령 | 하는 일 |
|---|---|
3minapi init [folder] |
호스트의 프로젝트를 만듭니다. 다시 실행해도 안전. 터미널이 없으면 --yes 필요, --move는 이동 |
3minapi login |
호스트 토큰 저장(가려진 프롬프트). 스크립트에서는 --with-token이 표준 입력에서 읽음 |
3minapi logout |
이 PC에서만 저장된 토큰 삭제 |
3minapi start |
워커 파일을 등록하고 멈출 때까지 태스크 실행. --mode poll이면 기본 실시간 대신 간격마다 가져옴. Ctrl+C로 정지 |
3minapi start --detach |
같은 동작을 백그라운드로. 재부팅 후 다시 시작되지 않음 |
3minapi reload |
실행 중인 start가 워커 파일을 다시 읽어 등록. 실행 중인 태스크는 계속됨. 1콜 |
3minapi stop |
어디서 시작했든 이 PC의 start를 정지 |
3minapi status |
start 실행 여부, 로컬 워커, 반복 태스크, 남은 한도. 1콜 |
3minapi logs [-f] |
CLI 자체 로그 — 가져오기, 정지, 에러 |
3minapi doctor |
환경 점검. 토큰을 보내지 않고 한도도 쓰지 않음 |
3minapi paths |
프로젝트 파일과 CLI 자체 폴더의 절대 경로 |
워커
| 명령 | 하는 일 |
|---|---|
3minapi worker new <name> [--ts] |
workers/<name>.mjs 생성(--ts면 .mts). start가 실행 중이면 바로 등록(--no-reload로 건너뜀) |
3minapi worker run <name> --input '<json>' |
로컬에서 한 번 실행. Windows의 셸 따옴표 문제는 --input-file <file>로 피할 수 있음 |
3minapi worker list |
프로젝트의 워커 목록, 각각 로드되는지 확인. API 호출 없음 |
3minapi worker logs <name> [-f] |
워커 하나의 로그: ctx.log, 콘솔 출력, 스택 트레이스가 포함된 에러 |
3minapi worker delete <name> |
3Min API에서 로컬 워커와 그 태스크 이력을 삭제한 뒤 파일을 삭제. 되돌릴 수 없음 |
결과와 이력
| 명령 | 하는 일 |
|---|---|
3minapi worker results list |
저장된 결과, 최신순. --worker, --since, -n |
3minapi worker results show <task_id> |
저장된 결과 하나 전체. 반복 태스크의 회차는 --run <n> |
3minapi worker results runs <task_id> |
반복 태스크의 회차 목록 |
3minapi worker results describe <task_id> |
결과 하나에 있는 경로. --worker <name>은 워커의 결과를 형태별로 묶음 |
3minapi worker results query "<SQL>" |
저장된 결과에 대한 읽기 전용 SQL. API 호출 없음 |
3minapi worker results prune --before <date> |
data.db에서 그 날짜보다 오래된 저장 결과 삭제 |
3minapi tasks prune --before <date> |
그 날짜 전에 끝난 이 호스트의 태스크 기록 삭제. 최근 것과 끝나지 않은 것은 유지 |
3minapi dashboard |
브라우저의 읽기 전용 페이지: 실행, 결과, 워커, 로그. 로그인·API 호출 없음 |
dashboard --detach는 백그라운드로 계속 실행하고,dashboard url은 링크를 다시 출력하며,dashboard stop은 종료합니다dashboard --lan은 같은 네트워크의 다른 기기에도 암호화되지 않은 HTTP로 제공합니다. 신뢰할 수 있는 네트워크에서만 쓰세요- 삭제 같은 파괴적 명령과
--lan은 확인을 묻습니다. 터미널이 없거나--json을 쓰면--yes가 필요합니다
워커 작성
workers/의 파일 하나가 워커 하나이고, 이름은 파일명을 따릅니다.
- 이름: 소문자, 숫자,
_,-만, 최대 50자,_로 시작할 수 없고 Windows 장치 이름(con,aux, …)은 불가. 대소문자 구분 없이 모든 워커 — 퍼블릭 워커와 다른 PC의 워커 포함 — 에서 고유해야 합니다 .mjs(기본) 또는.mts/.ts— TypeScript는 빌드 없이 실행됩니다(enum·namespace제외)
// workers/rename_photos.mjs
export const description =
'Renames the photos in a folder by the date taken. input: { folder: string }';
export const timeoutMs = 10 * 60_000; // 선택 — 기본 60초, 최대 23시간
export async function handler(input, ctx) {
await ctx.report('Scanning the folder'); // 진행 메시지 — task_get에 보입니다
if (ctx.signal.aborted) return; // 취소됐거나 곧 시간 초과
// … 실제 작업 …
return { renamed: 42 }; // → completed. 이 값이 결과입니다
// throw new Error('Folder not found') // → failed. 메시지가 에러가 됩니다
}
| export | 규칙 |
|---|---|
description |
필수. AI가 worker_list에서 보는 내용, 최대 500자. 입력 형태를 여기에 적으세요 |
timeoutMs |
선택. 기본 60초, 최대 23시간 |
inputSchema |
선택. 작은 JSON Schema 부분집합(type, properties, required, enum, items), 내 PC에서만 검사 |
handler |
필수. async (input, ctx) => result |
ctx |
내용 |
|---|---|
ctx.report(message) |
진행 메시지, 256자에서 잘림. 매번 1콜 |
ctx.log(message) |
워커 로그에만 기록 |
ctx.env |
시스템 환경변수 + 프로젝트의 .env(.env 우선). THREEMINAPI_로 시작하는 변수는 제거 |
ctx.signal |
취소나 타임아웃 때 발동하는 AbortSignal |
| handler가 끝나는 방식 | 태스크 결과 |
|---|---|
return value |
completed. 값은 JSON이어야 함 |
throw |
failed. 메시지(cause 포함), 토큰은 가려지고 4,000자에서 잘림. 스택은 로컬 로그에 남음 |
| 타임아웃 | failed (timeout) |
| 취소 | ctx.signal이 발동하고 2초 뒤 실행이 종료됨. 반환값은 보내지 않음 |
- 변경 반영: handler 코드와
.env수정은 다음 태스크부터 반영됩니다. 파일 추가·이름 변경, 설명 변경은3minapi reload가 필요합니다(또는 다음start).worker new는 스스로 reload합니다 - 파일을 지워도 3Min API에서 워커가 지워지지 않고, 그 태스크는 실패합니다.
3minapi worker delete <name>을 쓰세요 - 시크릿(내 API 키 등)은 프로젝트의
.env에 넣으세요..gitignore에 이미 포함돼 있습니다. UTF-8로 저장하세요(UTF-16은 거부) - 같은 태스크가 두 번 올 수 있습니다(at-least-once). 부수 효과가 있는 워커는 중복을 견뎌야 합니다
- 결과의 최상위에
_3minapi키가 있으면reserved_result_key로 실패합니다 - 워커가
data.db에 자기 데이터를 둘 수 있습니다:node:sqlite로new URL('../data.db', import.meta.url)을 여세요._3minapi_로 시작하는 테이블은 CLI 것이니 읽기만 하세요
AI에서 실행하기
start가 실행 중이면 평소처럼 AI에게 요청하면 됩니다 — 도구 이름은 몰라도 됩니다.
- "D:\Photos\2026의 사진을 날짜순으로 이름 바꿔줘"
- "BTC 가격을 1분마다 10번 확인해줘"
- "가격 확인 멈춰줘"
AI는 worker_list → task_create → task_get을 씁니다. 태스크는 CLI가 가져갈 때까지 3Min API에서 기다립니다 — 실시간 모드(기본)로 실행 중인 CLI는 신호를 받아 가져가고, 주기 확인 모드는 다음 확인 때 가져갑니다. 그때까지 task_get은 delivery: "pending", 가져간 뒤에는 "delivered"를 보여 줍니다.
반복 태스크
로컬 워커에서만 task_create에 repeat를 넣어 같은 입력을 일정 주기로 실행할 수 있습니다 — 태스크 하나, 모든 회차에 태스크 ID 하나입니다.
{
"worker": "price-feed",
"input": { "symbol": "BTC" },
"repeat": { "interval_seconds": 60, "max_runs": 10 }
}
| 필드 / 규칙 | 값 |
|---|---|
interval_seconds |
10 ~ 604,800 (7일). 다음 회차 시각에 이전 회차가 아직 실행 중이면 그 회차는 건너뜀 |
max_runs |
선택. 생략하면 취소할 때까지 반복합니다 — AI에게 취소를 요청해 멈추세요 |
| 상태 | working 유지. repeat에 runs, failed, last_run_at 표시. 마지막 회차 뒤 요약과 함께 completed |
| 실패 | 회차 하나가 실패해도 멈추지 않음. 5회 연속 실패 → failed (repeat_failed) |
| 비용 | CLI가 태스크를 받는 데 쓰는 호출과 별도로 회차마다 1콜. 끝없이 1분마다면 월 약 43,200콜 |
| 변경 | 취소하고 새로 생성 |
| CLI가 꺼져 있을 때 | 일시 정지. 24시간 + 한 주기 동안 회차 보고가 없으면 → failed |
| 퍼블릭 워커 | 불가 — repeatRequiresLocalWorker |
각 회차의 결과는 내 PC에 별도 행(run_no 1, 2, …)으로 저장됩니다.
결과 읽기
모든 결과는 내 PC의 data.db에 저장됩니다. 약 100KB 이하의 결과는 3Min API에도 보내져 task_get으로 AI에 전달됩니다. 더 큰 결과는 보내지 않고, 태스크는 result._3minapi에 대체 값(stored_locally: true, 태스크 ID, 크기, shape 요약, reader 이름)을 담아 완료됩니다.
AI — 호스트의 결과 조회 워커를 통해 읽습니다. _results_ + 호스트 ID 8자 이름의 내장 로컬 워커입니다. worker_list는 이를 워커 목록이 아니라 hosts의 해당 호스트 results_reader로 보여 줍니다. 내 PC에서 계산하고 답만 돌려보냅니다. 아래 task_result_* 도구가 각 단계를 이 워커에 넘기고, 주어진 task_id나 worker로 PC를 고르므로 AI가 워커 이름을 알 필요는 없습니다.
| 순서 | 도구 | 용도 |
|---|---|---|
| 1 | task_result_describe (task_id 또는 worker) |
형태부터 파악하세요. 결과에 없는 경로는 NULL로 읽히므로 형태가 섞이면 합계가 틀립니다 |
| 2 | task_result_query (sql, worker) |
뷰 results에 대한 읽기 전용 SQL. 집계해서 답만 돌려줌 |
| 3 | task_result_read (task_id, path, offset) |
약 90KB씩 원본 조각. 원본 데이터 자체가 필요할 때만 |
- 읽기 태스크는 하나에 최소 4콜이 들고, CLI가 가져갈 때까지 기다립니다
- 읽기 워커는 워커 파일이 하나 이상 있는 상태로
start가 실행될 때 등록됩니다
사용자 — 3minapi worker results list/show/describe/query 또는 3minapi dashboard. data.db는 자동으로 정리되지 않으니 worker results prune을 쓰세요. 개인정보가 담겨 있을 수 있습니다.
AI에게 CLI 실행 맡기기
허용하면 내 PC에서 명령을 실행할 수 있는 AI 클라이언트가 있습니다 — Claude Code·Codex 같은 코딩 에이전트와 일부 데스크톱 앱입니다. 웹의 ChatGPT처럼 그럴 수 없는 클라이언트라면 명령을 직접 실행하고 출력된 내용을 붙여넣으세요.
| AI가 해도 되는 일 | AI가 건드리면 안 되는 것 |
|---|---|
workers/*.mjs(설명, handler)와 3minapi.json 수정 |
호스트 토큰 — 채팅이나 명령줄에 절대 넣지 않음(3minapi login이 프롬프트로 받음) |
worker new, worker run, reload, status, doctor, logs, worker results … 실행 |
CLI 자체 폴더(credentials.json, control.db) — 3minapi paths 참고 |
위치를 물어본 뒤 init <folder> 또는 init --yes 실행 |
data.db에서 _3minapi_로 시작하는 테이블 |
- 터미널이 없으면 파괴적 명령에
--yes가 필요하므로--yes가 유일한 확인 절차입니다.worker delete --yes전에는 사용자에게 확인하세요 — 워커와 그 태스크 이력이 삭제됩니다 --json은 AI가 파싱할 수 있는 출력을 줍니다. 에러는{ "error": { "kind", "message", "exitCode", "code"?, "resetAt"? } }형태입니다. 쿼터 정지일 때 재설정 시각을 알면resetAt이 함께 옵니다
호스트와 토큰
| 상황 | 할 일 |
|---|---|
| PC가 여러 대 | PC마다 호스트를 하나씩 추가. PC 하나 = 호스트 하나 = 프로젝트 하나. 워커 이름은 PC 간에 달라야 함 |
| 토큰 분실·유출 | 호스트 화면에서 토큰 회전. 이전 토큰은 즉시 무효가 되고, 그 토큰을 쓰던 CLI는 정지 |
| 다른 PC로 이전 | 토큰 회전 → 프로젝트 폴더 복사 → 새 토큰으로 3minapi login → 3minapi start. 워커와 이력은 그대로 유지 |
| 호스트 삭제 | 소속 로컬 워커와 그 태스크 이력이 삭제됨. 처음부터 다시 시작할 때만 쓰세요. 실행 중인 CLI는 정지 |
| 폴더 이동 | 3minapi stop → 이동 → 그 안에서 명령 실행, 또는 3minapi init <folder> --move |
호스트 화면에는 CLI가 태스크를 받는 방식(실시간 또는 주기 확인), 마지막 연결 또는 확인 시각, 확인 주기(주기 확인일 때), 동시 실행 수, 버전, 플랫폼이 표시됩니다 — CLI가 보고한 사실이지 지금의 상태가 아닙니다.
제약사항과 한도
| 항목 | 값 |
|---|---|
| 로컬 워커 | 모든 플랜 무제한 |
| 수신 (실시간, 기본) | 연결을 유지하는 데는 호출이 들지 않습니다. 연결·재연결마다 1콜과 그 뒤 따라잡기 가져오기 1콜, 태스크나 취소 신호로 가져올 때마다 1콜. 연결은 망 사정으로 하루 몇 번 끊기고 스스로 다시 붙으므로, 할 일이 없어도 호출이 조금 듭니다 — 하루 6번 끊기면 하루 약 12콜, 월 약 360콜 |
| 수신 (주기 확인) | 대기 중인 태스크가 없어도 가져올 때마다 1콜. 기본 60초 간격 ≈ 하루 1,440콜 ≈ 월 43,200콜 |
| 그 밖의 호출 | 수신 확인 1회, 회신 1회(ctx.report와 최종 결과), 반복 회차 1회, reload/status 1회마다 각 1콜 |
| 동시 실행 | concurrency, 기본 4 (1–50). 한 번 가져올 때 최대 concurrency개 |
| 작업 기한 | 생성 후 24시간 안에 가져가지 않으면 → failed (매시 점검이라 최대 약 25시간) |
| 태스크 이력 | 유료 최소 60일. Free는 로컬 워커와 실행 기록이 워커 등록 7일 후 삭제됨. reload나 다음 start가 다시 등록 |
| 한도 소진 | CLI가 스스로 정지(종료 코드 5)하고 다시 시작하지 않음. 회신은 막히지 않음 |
| 3Min API로 보내는 결과 | 약 100KB. 더 큰 결과는 내 PC에 남음(대체 값 전송) |
| 로컬 로그 | 기본 30일 / 300MB 보관 (logRetentionDays, logMaxBytes) |
호출을 줄이려면 기본인 실시간 모드를 쓰세요. 망 때문에 주기 확인이 필요하다면 3minapi.json의 pollIntervalMs를 늘리고(태스크를 더 늦게 가져감) 다시 시작하세요.
concurrency개가 모두 실행 중이면 CLI는 새 태스크를 가져가지 않습니다 — 그 태스크는 pending으로 남습니다(취소 알림은 계속 받음). 이렇게 정해지는 처리량은 3minapi start와 3minapi status에 표시됩니다.
상태 확인과 문제 해결
실행 중인가요? 그 PC에서 3minapi status로 확인하세요. 웹의 CLI 수신과 worker_list가 AI에 주는 마지막 확인·연결 시각은 과거의 사실이지 지금의 상태가 아닙니다.
| 증상 | 원인과 해결 |
|---|---|
태스크가 delivery: "pending"으로 working에 머묾 (웹에서는 PC 대기) |
CLI가 아직 가져가지 않았습니다. 그 PC에서 3minapi start를 실행하세요 |
3minapi start가 실시간 연결을 열 수 없다고 함 |
회사 프록시나 방화벽이 막고 있습니다. 3minapi doctor로 확인하고, --mode poll로 시작하거나(receiveMode: "poll") 간격마다 가져오게 하세요 |
Not picked up within 24 hours — the 3Min API CLI on the user's PC did not fetch it. |
CLI가 24시간 꺼져 있었습니다. CLI를 시작하고 태스크를 다시 보내세요 |
No run was reported for 24 hours — the 3Min API CLI on the user's PC stopped running it. |
반복 태스크를 실행하던 CLI가 멈췄습니다. CLI를 시작하고 태스크를 다시 만드세요 |
Worker did not respond within 24 hours. |
CLI가 가져갔지만 끝내 회신하지 못한 로컬 태스크입니다 — 크래시 후 PC가 꺼진 채였습니다. 다시 실행하지 않습니다 |
host_stopped로 실패 |
실행 중에 CLI를 정지했습니다(Ctrl+C 또는 stop). 반복 태스크는 그 회차만 잃습니다 |
host_restarted로 실패 |
실행 중에 PC나 CLI가 죽었습니다. 실행됐는지 알 수 없으며 다시 실행하지 않습니다 |
| AI가 예전 형태로 입력을 보냄 | 3minapi reload 없이 설명을 바꿨습니다 |
worker_list에 워커가 없음 |
reload 없이 추가한 새 파일, 로드 에러(3minapi worker list), 또는 Free 7일 삭제(reload) |
CLI가 worker_name_taken으로 이름을 거부 |
다른 워커(퍼블릭 워커, 또는 다른 PC의 워커)가 그 이름을 쓰고 있습니다. 파일 이름을 바꾸세요 |
| CLI가 코드 4 또는 5로 종료 | 4: 토큰이 유효하지 않거나 플랜 없음 — 다시 login. 5: 월 한도 소진 |
종료 코드
| 코드 | 의미 |
|---|---|
| 0 | 정상 |
| 1 | 실패 |
| 2 | 사용법 오류 (--yes 누락 포함) |
| 3 | 환경 또는 설정 오류 |
| 4 | 정지: 토큰이 유효하지 않거나 계정에 플랜이 없음 (Free도 플랜에 포함) |
| 5 | 정지: 월 한도 소진 |
| 130 | 중단됨 (Ctrl+C) |
4나 5 뒤에는 아무것도 저절로 다시 시작되지 않습니다.
실패한 로컬 워커 태스크의 error.data.reason
| 사유 | 의미 |
|---|---|
handler_error |
handler가 예외를 던짐 |
timeout |
timeoutMs를 넘겨 실행됨 |
invalid_input |
inputSchema와 맞지 않음 — 실행하지 않음 |
invalid_worker |
파일은 있지만 쓸 수 없음 — handler 없음, 이름 중복, 또는 import 에러 |
worker_not_found |
그 PC에 해당 파일이 없음 |
unsupported_syntax |
CLI가 빌드 없이 실행할 수 없는 TypeScript (예: enum) |
result_too_large |
약 100KB를 넘었고 PC에 저장하지도 못함 |
reserved_result_key |
결과의 최상위에 _3minapi 키가 있음 |
host_stopped |
실행 중에 CLI가 정지됨 |
host_restarted |
실행 중에 PC나 CLI가 죽음. 다음 start가 보고 |
repeat_failed |
반복 태스크가 5회 연속 실패 |
프로토콜 요약
참고용으로, CLI와 3Min API가 함께 동작하는 방식입니다.
전달
- Pull: 실시간 모드에서는 CLI가 연결을 유지하다가 신호를 받으면(그리고 연결할 때마다 한 번) 3Min API에 대기 중인 태스크를 요청하고, 주기 확인 모드에서는
pollIntervalMs마다 요청합니다. 어느 쪽이든 지금 실행할 수 있는 만큼만 가져갑니다 - Ack: 받자마자 수신을 확인합니다(
delivery가"delivered"가 됨). 60초 동안 확인이 없으면 태스크를 다시 내보냅니다 — 최대 6회, 그 뒤failed - At-least-once: 같은 태스크가 두 번 올 수 있습니다
- 취소: 실시간 모드는 신호로, 주기 확인 모드는 다음 가져오기 때 알려지고 →
ctx.signal. 태스크는cancelled로 유지됩니다 - 회신: 진행 메시지와 최종 결과는 호스트 토큰으로 보냅니다. 네트워크 문제로 실패한 회신은 최대 24시간 동안 재시도합니다
크기
| 항목 | 한도 |
|---|---|
input |
100KB |
| 보내는 결과 | 약 100KB (100KiB에서 봉투 1KiB를 뺀 값) |
ctx.report |
256자 |
| 에러 메시지 | 4,000자 |
| 워커 설명 | 500자 |
| 워커 이름 | 50자 |
3minapi.json (우선순위: 플래그 > 환경변수 > 프로젝트 파일 > 기본값)
| 키 | 기본값 | 범위 | 환경변수 |
|---|---|---|---|
workersDir |
workers |
프로젝트 안 | — |
receiveMode |
live |
live 또는 poll |
THREEMINAPI_RECEIVE_MODE |
pollIntervalMs |
60000 | 5000–3600000 (주기 확인 모드에서만) | THREEMINAPI_POLL_INTERVAL_MS |
concurrency |
4 | 1–50 | THREEMINAPI_CONCURRENCY |
localServerPort |
3180 | 1024–65535 | THREEMINAPI_LOCAL_SERVER_PORT |
logRetentionDays |
30 | 1–365 | THREEMINAPI_LOG_RETENTION_DAYS |
logMaxBytes |
300 MB | 10 MB–1 GB | THREEMINAPI_LOG_MAX_BYTES |
receiveMode, pollIntervalMs, concurrency를 바꾸면 다시 시작해야 합니다. 모르는 키는 경고만 합니다.
폴더 — 3minapi paths가 출력합니다.
| OS | 토큰과 설정 | 제어 DB와 로그 |
|---|---|---|
| macOS | ~/Library/Application Support/3minapi |
~/Library/Application Support/3minapi, ~/Library/Logs/3minapi |
| Windows | %APPDATA%\3minapi |
%LOCALAPPDATA%\3minapi |
| Linux | $XDG_CONFIG_HOME/3minapi (~/.config) |
$XDG_STATE_HOME/3minapi (~/.local/state) |
토큰은 프로젝트가 아니라 이 폴더들에 있으므로, 프로젝트를 복사해도 토큰은 복사되지 않습니다.
개인정보 안내
- 워커의
result와error는 그대로 AI 대화에 전달됩니다. 필요한 것만 돌려주세요 data.db는 정리하기 전까지 모든 결과를 — 그 안의 개인정보까지 — 내 PC에 보관합니다