본문으로 건너뛰기
stepper

구성

camelCase JSON으로 stepper를 구성합니다. 사용자 레벨의 기본 설정에 프로젝트 설정이 병합되며, 프로바이더, 레이어, 권한, MCP 서버를 다룹니다.

.stepper/setting.json 파일은 stepper의 동작과 기본값을 구성합니다. 설정은 camelCase를 사용하며 상위 호환성을 보장합니다(알 수 없는 키는 무시됨). 사용자 레벨의 ~/.stepper/setting.json이 기본 구성 역할을 하며, 그 위에 프로젝트 구성이 깊은 병합(deep-merge)됩니다. 이때 객체는 병합되고 배열은 대체됩니다.

구성 스키마

jsonc
{
  "mode": "auto",                         // auto | plan | accept-edits (CLI --mode wins)
  "defaultModel": "anthropic/claude-sonnet-4",
  "step": ["plan", "implement"],          // the layer pipeline, in order

  "providers": {
    "anthropic": { "kind": "anthropic" },
    "ollama-cloud": { "kind": "openai-compat", "baseUrl": "https://ollama.com/v1" },
    "omlx": {
      "kind": "openai-compat",
      "baseUrl": "http://localhost:8000/v1",
      "contextWindow": 128000             // override ctx% gauge for unlisted models
    },
    "codex": { "kind": "openai-responses", "auth": "codex-oauth" }
  },

  "orchestrator": { "model": "anthropic/claude-sonnet-4", "temperature": 0.2 },

  "permissions": {                        // global rules (deny > ask > allow > mode)
    "allow": ["Read(**)", "Bash(cargo *)"],
    "ask":   ["Write(**)"],
    "deny":  ["Bash(rm -rf *)", "Read(//etc/**)"]  
  },
  "approvals": [{ "rule": "Bash(npm run build)" }],   // persisted "always allow"

  "mcpServers": {
    "context7": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp", "--api-key", "{env:CONTEXT7_KEY}"],
      "alwaysLoad": true                  // visible to every layer regardless of mcp.allow
    },
    "my-http": {
      "type": "http",
      "url": "https://example/mcp",
      "headers": { "Authorization": "Bearer {env:MY_TOKEN}" }
    }
  },

  "hooks": {
    "PreToolUse": [{ "matcher": "write_file", "command": "echo blocked >&2; exit 2" }]
  },

  "compaction": { "provider": "anthropic/claude-haiku-4" },  // model-summarize folded history
  "dispatch":   { "enabled": true }       // expose the model-callable `dispatch` tool
}

스키마 검증

stepper config --schema를 실행하면 setting.json의 전체 JSON Schema가 출력됩니다. stepper config --validate를 사용하면 프로젝트 구성을 스키마와 대조하여 검증할 수 있습니다.

주요 구성 필드

  • mode — 권한 모드: auto(프로젝트 내 작업은 실행되고, 프로젝트 외부 쓰기는 확인을 요청), plan(읽기 전용; 편집 차단), accept-edits(프로젝트 내 편집은 자동 승인; 외부 읽기는 확인을 요청). CLI --mode가 우선합니다.
  • defaultModel — 기본 모델 프로바이더 및 ID(예: anthropic/claude-sonnet-4).
  • step — 파이프라인을 구성하는 레이어 이름 배열로, 순서대로 실행됩니다.
  • providers — kind(anthropic, openai-compat, openai-responses)와 연결 세부 정보를 포함하는 프로바이더 정의입니다. 선택적인 contextWindow는 목록에 없는 모델의 컨텍스트 게이지를 재정의합니다.
  • orchestrator — model과 temperature를 포함한 orchestrator 레이어의 구성입니다.
  • permissions — allow, ask, deny 목록을 갖는 전역 권한 규칙입니다. 규칙은 Bash(npm run *), Read(/path), Write(**), Mcp(server, tool) 같은 지정자를 사용합니다.
  • approvals — 영속화된 승인 규칙("항상 허용" 결정)의 배열입니다.
  • mcpServers — MCP 서버 구성입니다. 각 서버는 type(stdio 또는 http), 연결 세부 정보, 그리고 레이어 범위 필터링을 우회하는 선택적 alwaysLoad를 지정합니다.
  • hooks — 도구 실행을 가로채는 PreToolUse 같은 이벤트 훅입니다.
  • compaction — 히스토리 접기(folding) 구성으로, 접힌 부분을 요약할 (저렴한) provider 모델을 지정합니다.
  • dispatch — 병렬 서브에이전트를 위해 모델이 호출할 수 있는 dispatch 도구를 활성화합니다.