도구

LLM이 사용할 수 있는 도구 관리하기.

도구를 사용하면 LLM이 코드베이스에서 동작을 수행할 수 있습니다. OpenCode에는 내장 도구 세트가 함께 제공되지만, 사용자 지정 도구나 MCP 서버로 확장할 수 있습니다.

기본적으로 모든 도구는 활성화되어 있으며 실행에 권한이 필요하지 않습니다. 권한을 통해 도구 동작을 제어할 수 있습니다.

설정

permission 필드를 사용해 도구 동작을 제어하세요. 각 도구에 대해 허용, 거부, 또는 승인 요구를 설정할 수 있습니다.

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "edit": "deny",
    "bash": "ask",
    "webfetch": "allow"
  }
}

와일드카드를 사용해 여러 도구를 한 번에 제어할 수도 있습니다. 예를 들어, MCP 서버의 모든 도구에 대해 승인을 요구하려면:

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "mymcp_*": "ask"
  }
}

권한 설정에 대해 자세히 보기.

내장

다음은 OpenCode에서 사용할 수 있는 모든 내장 도구입니다.

bash

프로젝트 환경에서 셸 명령어를 실행합니다.

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "bash": "allow"
  }
}

이 도구를 사용하면 LLM이 npm install, git status 또는 기타 모든 셸 명령어와 같은 터미널 명령어를 실행할 수 있습니다.

edit

정확한 문자열 치환을 사용해 기존 파일을 수정합니다.

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "edit": "allow"
  }
}

이 도구는 정확히 일치하는 텍스트를 치환하여 파일을 정밀하게 편집합니다. LLM이 코드를 수정하는 주요 방법입니다.

write

새 파일을 만들거나 기존 파일을 덮어씁니다.

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "edit": "allow"
  }
}

LLM이 새 파일을 만들 수 있도록 허용하려면 이를 사용하세요. 이미 존재하는 파일은 덮어씁니다.

참고: write 도구는 edit 권한으로 제어되며, 이는 모든 파일 수정(edit, write, apply_patch)을 포함합니다.

read

코드베이스에서 파일 내용을 읽습니다.

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "read": "allow"
  }
}

이 도구는 파일을 읽고 그 내용을 반환합니다. 큰 파일의 경우 특정 줄 범위를 읽는 것을 지원합니다.

grep

정규 표현식을 사용해 파일 내용을 검색합니다.

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "grep": "allow"
  }
}

코드베이스 전반에 걸친 빠른 내용 검색입니다. 전체 정규식 구문과 파일 패턴 필터링을 지원합니다.

glob

패턴 매칭으로 파일을 찾습니다.

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "glob": "allow"
  }
}

**/*.js 또는 src/**/*.ts와 같은 glob 패턴을 사용해 파일을 검색합니다. 수정 시간순으로 정렬된 일치하는 파일 경로를 반환합니다.

lsp (실험적)

설정된 LSP 서버와 상호 작용하여 정의, 참조, 호버 정보, 호출 계층 구조 같은 코드 인텔리전스 기능을 얻습니다.

참고: 이 도구는 OPENCODE_EXPERIMENTAL_LSP_TOOL=true(또는 OPENCODE_EXPERIMENTAL=true)일 때만 사용할 수 있습니다.

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "lsp": "allow"
  }
}

지원되는 작업에는 goToDefinition, findReferences, hover, documentSymbol, workspaceSymbol, goToImplementation, prepareCallHierarchy, incomingCalls, outgoingCalls가 포함됩니다.

프로젝트에서 사용 가능한 LSP 서버를 설정하려면 LSP 서버를 참조하세요.

apply_patch

파일에 패치를 적용합니다.

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "edit": "allow"
  }
}

이 도구는 코드베이스에 패치 파일을 적용합니다. 다양한 소스의 diff와 패치를 적용하는 데 유용합니다.

tool.execute.before 또는 tool.execute.after 훅을 처리할 때는 input.tool === "apply_patch"("patch"가 아님)를 확인하세요.

apply_patch는 output.args.filePath 대신 output.args.patchText를 사용합니다. 경로는 patchText 내의 마커 줄에 포함되어 있으며 프로젝트 루트 기준 상대 경로입니다(예: *** Add File: src/new-file.ts, *** Update File: src/existing.ts, *** Move to: src/renamed.ts, *** Delete File: src/obsolete.ts).

참고: apply_patch 도구는 edit 권한으로 제어되며, 이는 모든 파일 수정(edit, write, apply_patch)을 포함합니다.

skill

스킬(SKILL.md 파일)을 로드하고 그 내용을 대화에 반환합니다.

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "skill": "allow"
  }
}

todowrite

코딩 세션 중 할 일 목록을 관리합니다.

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "todowrite": "allow"
  }
}

복잡한 작업 중 진행 상황을 추적하기 위해 작업 목록을 생성하고 업데이트합니다. LLM은 이를 사용해 여러 단계의 작업을 정리합니다.

참고: 이 도구는 기본적으로 서브에이전트에 대해 비활성화되어 있지만, 수동으로 활성화할 수 있습니다. 자세히 보기

webfetch

웹 콘텐츠를 가져옵니다.

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "webfetch": "allow"
  }
}

LLM이 웹 페이지를 가져와 읽을 수 있도록 허용합니다. 문서를 조회하거나 온라인 리소스를 조사하는 데 유용합니다.

websearch

정보를 얻기 위해 웹을 검색합니다.

참고: 이 도구는 OpenCode 프로바이더를 사용할 때 또는 OPENCODE_ENABLE_EXA 환경 변수가 참 값(예: true 또는 1)으로 설정되어 있을 때만 사용할 수 있습니다.

OpenCode 실행 시 활성화하려면:
OPENCODE_ENABLE_EXA=1 opencode

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "websearch": "allow"
  }
}

Exa AI를 사용해 웹 검색을 수행하여 온라인에서 관련 정보를 찾습니다. 주제 조사, 최신 이벤트 찾기, 또는 학습 데이터 컷오프를 넘어서는 정보 수집에 유용합니다.

API 키가 필요하지 않습니다. 이 도구는 인증 없이 Exa AI의 호스팅 MCP 서비스에 직접 연결됩니다.

팁: 정보를 찾아야 할 때(탐색)는 websearch를 사용하고, 특정 URL에서 콘텐츠를 가져와야 할 때(검색)는 webfetch를 사용하세요.

question

실행 중 사용자에게 질문합니다.

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "question": "allow"
  }
}

이 도구를 사용하면 LLM이 작업 중 사용자에게 질문할 수 있습니다. 다음과 같은 경우에 유용합니다:

사용자 선호 사항이나 요구 사항 수집
모호한 지시 사항 명확화
구현 선택에 대한 결정 받기
어떤 방향으로 진행할지에 대한 선택지 제공

각 질문에는 헤더, 질문 텍스트, 옵션 목록이 포함됩니다. 사용자는 제공된 옵션 중에서 선택하거나 사용자 지정 답변을 입력할 수 있습니다. 질문이 여러 개일 경우, 사용자는 모든 답변을 제출하기 전에 질문 사이를 탐색할 수 있습니다.

사용자 지정 도구

사용자 지정 도구를 사용하면 LLM이 호출할 수 있는 자체 함수를 정의할 수 있습니다. 이는 설정 파일에 정의되며 임의의 코드를 실행할 수 있습니다.

사용자 지정 도구 생성에 대해 자세히 보기.

MCP 서버

MCP(Model Context Protocol) 서버를 사용하면 외부 도구와 서비스를 통합할 수 있습니다. 여기에는 데이터베이스 접근, API 통합, 서드파티 서비스가 포함됩니다.

MCP 서버 설정에 대해 자세히 보기.

내부 동작

내부적으로 grep과 glob 같은 도구는 ripgrep (opens in a new tab)을 내부에서 사용합니다. 기본적으로 ripgrep은 .gitignore 패턴을 존중하며, 이는 .gitignore에 나열된 파일과 디렉터리가 검색과 목록에서 제외됨을 의미합니다.

무시 패턴

일반적으로 무시되는 파일을 포함하려면, 프로젝트 루트에 .ignore 파일을 만드세요. 이 파일은 특정 경로를 명시적으로 허용할 수 있습니다.

!node_modules/
!dist/
!build/

예를 들어, 이 .ignore 파일은 node_modules/, dist/, build/ 디렉터리가 .gitignore에 나열되어 있더라도 ripgrep이 그 안에서 검색하도록 허용합니다.

GitLab 규칙