📈 비트코인 노드 설정 옵션 194개 가운데 54개는 기본 도움말에 안 나와요

비트코인 노드를 직접 띄워 보면 설정 파일 앞에서 한 번은 멈추게 돼요. 옵션 이름은 검색하면 나오는데, 그 옵션이 전부 몇 개인지, 지금 내 화면에 안 보이는 항목이 더 있는지는 어디에도 한 줄로 정리돼 있지 않거든요.

도움말을 띄워 훑어보고 예시 설정 파일을 열어 보면 대충 비슷한 목록이 나와요. 그래서 그 둘이 같은 것이라고 생각하기 쉬운데, 실제로는 같지 않아요.

그래서 노드 프로그램이 등록하는 설정 옵션을 전부 세어 봤어요.

이 글이 재는 자리를 먼저 못박을게요. 비트코인 코어 v31.1 소스 한 벌을 커밋 하나로 고정해 내려받은 뒤, 옵션을 등록하는 함수 호출을 통째로 떼어 내 이름과 플래그와 묶음을 따로 읽었어요. 대상 커밋은 9be056a8a72b로 시작하고 커밋 날짜는 2026년 7월 6일이에요. 조회 시각은 2026년 9월 11일 오전 11시 38분부터 11시 47분까지(한국 시각) 이고, 노드를 빌드하거나 실행하지는 않았어요. 매매 권유가 아니에요.

무엇을 어떻게 셌는지부터 밝힐게요

숫자를 말하기 전에 분모를 어떻게 정했는지 적을게요. 이런 종류의 숫자는 세는 방법에 따라 너무 쉽게 달라져요.

노드 실행 파일은 시작할 때 설정 옵션을 등록하는 함수 하나를 불러요. 그 함수가 다시 다섯 군데를 순서대로 부르고, 그 다섯 군데 안에서 등록된 것만 이 글의 분모예요. 명령줄 도구나 거래 조립 도구, 그래픽 프로그램이 자기 몫으로 따로 등록하는 옵션은 분모 밖으로 뺐어요.

세는 방식도 밝혀 둘게요. 등록 호출은 한 줄로 끝나지 않고 설명 문장까지 여러 줄에 걸쳐 있어서, 줄 수를 세면 값이 틀려요. 그래서 괄호 짝을 맞춰 호출 하나를 통째로 떼어 낸 뒤 인자 네 개를 따로 갈라 읽었어요. 이름, 설명 문장, 플래그, 묶음 이렇게 네 가지예요.

등록 호출 횟수 자체는 195회인데 그중 한 이름이 두 번 나와요. 같은 이름이 조건문 양쪽에 한 번씩 적혀 있고 빌드할 때 한쪽만 살아남는 구조라서 실제 개수는 194개예요. 등록 함수 자체가 같은 이름이 두 번 들어오면 그 자리에서 멈추도록 만들어져 있어서, 이름이 겹치지 않는다는 건 코드가 보장해 주는 셈이에요.

194개 가운데 140개만 기본 도움말에 나와요

세어 본 결과부터 표로 놓을게요.

54개가 어떻게 나오는지는 단순해요. 디버그 전용 41개와 숨김 13개는 한 개도 겹치지 않아서 그대로 더하면 54개가 돼요. 194개에서 이 54개를 빼면 140개가 남고요.

디버그 전용은 도움말을 부를 때 디버그용 도움말 옵션을 같이 붙이면 화면에 나와요. 숨김 13개는 어떤 도움말에도 안 나오는데, 그렇다고 비밀 기능은 아니에요. 13개 중 6개는 그래픽 프로그램 쪽 옵션이고, 노드도 받아는 주되 도움말에는 안 보이게 등록해 둔 것이에요. 소스 주석에 그렇게 적혀 있어요.

즉 기본 도움말은 노드가 아는 옵션의 72.2퍼센트만 보여 주고 있어요. 도움말 화면을 목록의 전부로 읽으면 그 지점에서 어긋나기 시작해요.

같은 저장소 안의 다른 산출물이 이 숫자를 받쳐 줘요

소스만 세면 파서가 틀렸을 때 확인할 방법이 없어요. 그래서 같은 저장소에 들어 있는 매뉴얼 페이지를 두 번째 원본으로 썼어요.

이 매뉴얼 페이지는 사람이 손으로 쓴 문서가 아니라, 빌드된 실행 파일을 실제로 돌려 도움말 출력을 받아 적는 도구가 만든 파일이에요. 파일 머리글에 그 도구 이름과 버전이 그대로 적혀 있고, 표기된 버전은 v31.1, 표기된 시기는 2026년 7월이라 커밋 날짜와 맞아요. 소스를 읽어 센 값과, 남이 빌드한 바이너리가 뱉은 값을 맞대 보는 셈이에요.

139개 중에 소스에 없는 이름은 0개였고, 숨김이나 디버그 전용이 섞여 들어온 것도 0개였어요. 차이 나는 한 개는 -ipcbind인데, 사유가 코드에 그대로 적혀 있어요. 이 옵션은 프로세스 분리 기능을 켜고 빌드한 바이너리에서만 등록되는 조건부 항목이라, 매뉴얼을 뽑을 때 쓴 바이너리에는 그 기능이 꺼져 있었다는 뜻이에요.

분류값 쪽도 맞아요. 소스의 분류 표에는 항목이 31개 있는데 그중 하나가 잠금 경합 진단용 조건 안에 들어 있어 보통 빌드에는 없어요. 그래서 릴리스 빌드 기준 30개가 되는데, 매뉴얼 페이지가 나열한 값도 정확히 30개였고 빠진 항목까지 같았어요.

재현하실 분을 위해 함정 두 개를 적어 둘게요. 처음에 정규식을 느슨하게 잡았더니 매뉴얼에서 145개가 나왔는데, 그중 7개는 설명 문장 속에 등장한 낱말이었어요. 반대로 붙임표가 들어간 이름 두 개는 문서 조판 규칙 때문에 붙임표 자리가 다른 기호로 감싸여 있어서 오히려 놓쳤고요. 그래서 옵션 블록의 첫 줄만 읽는 방식으로 다시 세어 139개를 얻었어요. 같은 자리를 다시 재려는 분은 이 두 함정을 그대로 밟게 돼요.

예시 설정 파일은 「모든 옵션」이라고 적어 두고 137개를 적어요

저장소에는 예시 설정 파일도 같이 들어 있어요. 많은 안내 글이 이 파일을 그대로 복사해 쓰라고 소개하는 그 파일이에요.

머리글 여섯 번째 줄에는 가능한 모든 설정 옵션을 제공한다는 문장이 적혀 있어요. 그런데 실제로 이름이 적힌 것은 137개고, 194개 기준으로 57개는 이름조차 없어요. 없는 57개의 내역은 숨김 13개, 디버그 전용 41개, 그리고 기본 도움말에는 보이는 옵션 3개예요.

반대 방향으로는 깨끗했어요. 이 파일에 적혀 있는데 실제로는 존재하지 않는 이름은 0개였어요. 허수는 없다는 뜻이에요. 기본 도움말에 나오는 140개를 분모로 잡으면 137개, 97.9퍼센트를 덮어요.

사유도 코드에 있어요. 이 파일은 사람이 관리하는 문서가 아니라 스크립트가 도움말 출력을 가공해 만드는 산출물인데, 그 스크립트 안에 도움말 항목으로 시작하는 블록을 통째로 지우는 줄이 들어 있어요. 남은 하나는 위에서 본 조건부 항목이고요. 그러니 여기서 말하는 모든 옵션은 그 빌드의 기본 도움말에 나온 옵션 전부로 읽는 편이 정확해요.

같은 프로그램의 배포 파일 쪽을 센 이야기는 비트코인 코어 배포 폴더 글에 따로 적어 뒀어요. 그쪽은 파일 서버의 상태를 셌고, 이 글은 소스와 문서를 셌어요.

구역을 안 나누면 경고가 아니라 기동 실패예요

여기서부터는 실제로 사람이 걸려 넘어지는 자리예요.

설정 옵션 중 8개에는 구역을 나눠야만 먹는다는 표시가 붙어 있어요. -addnode, -bind, -connect, -port, -rpcbind, -rpcport, -wallet, -walletdir 여덟 개예요.

이 8개를 설정 파일 맨 위, 그러니까 구역 머리글이 없는 자리에만 적어 두고 메인넷이 아닌 체인으로 노드를 띄우면 경고가 아니라 기동 실패로 끝나요. 검사를 맡은 함수가 메인넷일 때는 빈 결과를 돌려주고, 메인넷이 아닐 때만 기본 구역에 있는 항목을 모아 오기 때문이에요. 그렇게 모인 목록은 그대로 기동 오류로 넘어가요.

이 구조 때문에 생기는 헷갈림이 하나 있어요. 같은 설정 파일이 메인넷에서는 잘 돌고 테스트 체인에서만 안 뜨는 일이 벌어져요. 파일이 잘못된 것처럼 보이지 않아서 원인을 찾는 데 시간이 걸려요. 테스트 체인을 쓰신다면 이 8개는 해당 구역 머리글 아래로 옮겨 적는 게 맞아요.

로그에서만 가려지는 옵션이 4개 있어요

민감 표시가 붙은 옵션은 4개예요. -rpcauth, -rpcpassword, -rpcuser, -torpassword 네 개고요.

이 표시가 하는 일은 딱 하나예요. 노드가 디버그 로그에 설정값을 찍을 때 값 자리를 별표로 바꿔 줘요. 그게 전부예요. 설정 파일 안에는 평문 그대로 남아요. 그래서 가려지니까 안전하다고 읽으면 틀려요. 로그를 남에게 보내도 비밀번호가 안 딸려 간다는 뜻이지, 파일이 보호된다는 뜻이 아니에요. 실질적인 방어선은 파일 권한과 보관 위치예요.

이름만 살아 있는 옵션이 3개 있어요

설명 문장이 빈 문자열인 숨김 옵션이 3개 있어요. -checkpoints, -limitancestorsize, -limitdescendantsize 세 개예요.

셋 다 기능이 사라진 옵션인데, 옛 설정 파일을 그대로 쓰는 사람에게 경고를 띄우려고 이름만 남겨 둔 것이에요. 기동은 정상적으로 되고 값만 조용히 무시돼요. 검문소 관련 옵션은 그 기능이 제거됐으니 효과가 없다는 메시지가 뜨고, 나머지 둘은 조상과 자손 크기 제한이 클러스터 크기 제한으로 대체됐다는 취지의 메시지가 떠요.

그러니까 설정 파일에 적혀 있으니 동작 중일 것이라는 읽기는 이 세 개 앞에서 깨져요. 오래된 설정 파일을 물려받았다면 기동 직후 경고 줄을 한 번 훑어보는 편이 좋아요. 멤풀 정책이 어떻게 바뀌어 왔는지는 대체 거래 규칙 쪽 글에서 문서 원문으로 대조해 둔 적이 있어요.

「디버그 묶음」과 「디버그 전용」은 다른 집합이에요

이름이 비슷해서 자주 섞이는 자리예요.

도움말 화면에서 디버그 항목으로 묶여 보이는 것은 36개인데, 디버그용 도움말을 붙여야 보이는 것은 41개예요. 그런데 이 둘이 겹치는 건 24개뿐이에요.

로그 관련 옵션이나 -debug 자체는 디버그 묶음에 있지만 기본 도움말에 그냥 나와요. 반대로 체인 선택 묶음에 있는 -regtest는 디버그 전용 표시가 붙어 있어 기본 도움말에는 안 나와요. 화면에서 안 보인다고 없는 옵션이 아니라는 이야기예요.

이 숫자가 흔들리는 자리를 적어 둘게요

194라는 값에는 조건이 붙어요. 등록 호출 중 19개는 빌드 조건에 묶여 있어요.

여기에 실행 시점 조건인 -ipcbind 한 개가 더 있어요. 그래서 194는 소스가 등록할 수 있는 최대치이고, 어떤 기능을 꺼서 빌드한 바이너리라면 그보다 적어요. 앞에서 본 매뉴얼 페이지의 139개가 그 예예요.

그리고 이 숫자는 커밋 한 점의 값이에요. v31.1의 2026년 7월 6일 커밋 기준이고, 다음 릴리스에서 옵션이 늘거나 줄면 194도 140도 54도 같이 달라져요. 인용하실 때는 버전과 커밋을 같이 적어 주시는 편이 안전해요. 수수료나 거래 크기처럼 체인에서 읽어 오는 값과 달리, 이건 사람이 코드를 고치면 바로 바뀌는 값이거든요. 체인에서 읽는 쪽 숫자를 어떻게 재는지는 비트코인 송금 수수료 글에 따로 정리해 뒀어요.

확인하지 못한 것

범위를 분명히 해 둘게요.

• 노드를 빌드하거나 실행하지 않았어요. 소스의 등록 코드와, 같은 저장소에 들어 있는 매뉴얼 페이지를 대조한 것까지가 전부예요.
• 각 옵션이 실제로 무슨 일을 하는지는 검증하지 않았어요. 이름과 플래그와 묶음과 설명 문장까지만 읽었어요.
• 지갑 옵션 22개는 지갑 기능을 켜고 빌드한 경우 기준이에요. 지갑을 빼고 빌드한 경우에 이 22개가 어떻게 등록되는지는 이번에 확인하지 않았어요.
• 배포판이 제공하는 바이너리마다 빌드 구성이 달라서, 여러분이 쓰시는 바이너리의 실제 개수는 이 값과 다를 수 있어요.

자주 묻는 질문 (FAQ)

Q. 도움말에 안 나오는 54개를 굳이 알아야 하나요?

전부 알 필요는 없어요. 다만 문제가 생겼을 때 검색으로 찾은 옵션이 내 도움말 화면에 없다고 해서 잘못된 정보라고 단정하지 않게 되는 정도의 이득은 있어요. 디버그 전용 41개는 도움말 옵션을 하나 더 붙이면 그 자리에서 설명까지 볼 수 있어요.

Q. 설정 파일에 없는 옵션을 적어도 되나요?

노드가 등록한 이름이라면 도움말에 안 나오더라도 설정 파일에서 그대로 읽어요. 반대로 등록되지 않은 이름을 적으면 기동이 막혀요. 그래서 오타 하나가 기동 실패로 이어지는 일이 종종 생겨요.

Q. 제 노드가 안 뜨는데 어디부터 볼까요?

메인넷이 아닌 체인을 쓰고 계신다면 구역을 나눠야 먹는 8개부터 확인해 보세요. 이 경우는 메시지에 해당 항목 이름과 필요한 구역 이름이 같이 나와요. 메인넷이라면 같은 검사가 아예 빈 결과를 돌려주니 다른 원인을 봐야 해요.

Q. 예시 설정 파일을 그대로 복사해 쓰면 되나요?

그 파일은 전부 주석 처리된 견본이라 복사만 해서는 아무 설정도 켜지지 않아요. 이번 조회에서 켜져 있는 설정 줄은 0줄이었어요. 필요한 줄의 주석만 풀어 쓰는 용도로 만들어진 파일이에요.

Q. 194개 중에 위험한 옵션도 있나요?

이 글은 옵션이 하는 일을 검증하지 않았기 때문에 위험 여부를 판정하지 않았어요. 다만 디버그 전용으로 분류된 것들은 이름만 봐도 검사 강도나 정책 한도를 손대는 항목이 많아요. 기본값을 바꾸기 전에 그 항목의 설명 문장을 먼저 읽어 보시는 편이 좋아요.

Q. 다음 버전에서도 이 숫자가 맞나요?

아닐 가능성이 높아요. 이 값들은 v31.1의 한 커밋에서 센 것이고, 릴리스마다 옵션이 추가되거나 정리돼요. 이름만 남은 옵션 3개가 있다는 사실 자체가 목록이 계속 바뀐다는 증거예요.

정리

• 노드 실행 파일이 등록하는 설정 옵션은 194개, 기본 도움말에 나오는 것은 140개, 안 나오는 것은 54개(디버그 전용 41개, 숨김 13개)예요.
• 같은 저장소의 매뉴얼 페이지는 139개를 싣고 있고, 차이 나는 한 개는 조건부로 등록되는 항목이라 사유가 코드에 적혀 있어요. 분류값 30개는 양쪽이 완전히 같았어요.
• 예시 설정 파일은 모든 옵션을 제공한다고 적어 두고 137개를 적어요. 빠진 57개는 숨김과 디버그 전용, 그리고 생성 스크립트가 잘라 낸 3개예요.
• 실전에서는 구역을 나눠야 먹는 8개가 가장 자주 사고를 내요. 메인넷이 아닌 체인에서는 기동 실패로 이어져요.
• 민감 표시 4개는 로그 출력에서만 가려지고 파일은 평문이에요. 이름만 남은 3개는 기동은 되지만 값이 무시돼요.
• 모든 숫자는 v31.1, 커밋 9be056a8a72b, 2026년 9월 11일 오전 11시 38분(한국 시각) 조회 기준이에요.

이 글은 매매 권유가 아닌 정보 제공 글입니다. 가상자산은 변동성이 크고 원금 손실 위험이 있으며, 투자 판단과 그 결과에 대한 책임은 본인에게 있습니다.