diff --git a/pageindex/config.py b/pageindex/config.py
index b40e285..92de8dd 100644
--- a/pageindex/config.py
+++ b/pageindex/config.py
@@ -46,6 +46,17 @@ class IndexConfig(BaseModel):
             _validate_max_concurrency(v)
         return v
 
+    @classmethod
+    def from_yaml(cls, path: str = None, **overrides) -> "IndexConfig":
+        """Load config from a YAML file ("yes"/"no" accepted for booleans);
+        keyword overrides take precedence. Defaults to the package config.yaml."""
+        import yaml
+        if path is None:
+            path = os.path.join(os.path.dirname(__file__), "config.yaml")
+        with open(path, "r", encoding="utf-8") as f:
+            data = yaml.safe_load(f) or {}
+        return cls(**{**data, **overrides})
+
 
 def _env_drop_params_default() -> bool:
     return os.getenv("PAGEINDEX_DROP_PARAMS", "true").strip().lower() not in (
diff --git a/pageindex/config.yaml b/pageindex/config.yaml
new file mode 100644
index 0000000..591fe93
--- /dev/null
+++ b/pageindex/config.yaml
@@ -0,0 +1,10 @@
+model: "gpt-4o-2024-11-20"
+# model: "anthropic/claude-sonnet-4-6"
+retrieve_model: "gpt-5.4"  # defaults to `model` if not set
+toc_check_page_num: 20
+max_page_num_each_node: 10
+max_token_num_each_node: 20000
+if_add_node_id: "yes"
+if_add_node_summary: "yes"
+if_add_doc_description: "no"
+if_add_node_text: "no"
\ No newline at end of file
diff --git a/run_pageindex.py b/run_pageindex.py
index c9a0714..3b5662b 100644
--- a/run_pageindex.py
+++ b/run_pageindex.py
@@ -64,7 +64,11 @@ if __name__ == "__main__":
             "if_add_node_text": args.if_add_node_text,
         }.items() if v is not None
     }
-    opt = IndexConfig(**config_overrides)
+    # Legacy config.yaml is the base when present, CLI args win
+    try:
+        opt = IndexConfig.from_yaml(**config_overrides)
+    except FileNotFoundError:
+        opt = IndexConfig(**config_overrides)
 
     if args.pdf_path:
         # Validate PDF file