diff --git a/README.md b/README.md
index fbce91ab..7629fc38 100644
--- a/README.md
+++ b/README.md
@@ -323,6 +323,11 @@ codewhale --provider fireworks --model deepseek-v4-pro
 codewhale auth set --provider openai --api-key "YOUR_OPENAI_COMPATIBLE_API_KEY"
 OPENAI_BASE_URL="https://openai-compatible.example/v4" codewhale --provider openai --model glm-5
 
+# Custom DeepSeek-compatible endpoint
+DEEPSEEK_BASE_URL="https://your-provider.example/v1" \
+  DEEPSEEK_MODEL="deepseek-ai/DeepSeek-V4-Pro" \
+  codewhale --provider deepseek
+
 # Self-hosted SGLang
 SGLANG_BASE_URL="http://localhost:30000/v1" codewhale --provider sglang --model deepseek-v4-flash
 
@@ -468,6 +473,12 @@ Full shortcut catalog: [docs/KEYBINDINGS.md](docs/KEYBINDINGS.md).
 
 User config: `~/.codewhale/config.toml` (legacy `~/.deepseek/config.toml` fallback). Project overlay: `<workspace>/.codewhale/config.toml` (legacy `<workspace>/.deepseek/config.toml`) (denied: `api_key`, `base_url`, `provider`, `mcp_config_path`). [config.example.toml](config.example.toml) has every option.
 
+Custom DeepSeek-compatible endpoints usually do not need a new provider. Keep
+`provider = "deepseek"` and set `[providers.deepseek].base_url` / `model`, or
+use `provider = "openai"` for generic OpenAI-compatible gateways. Keep
+`provider`, `api_key`, and `base_url` in user config or environment variables;
+project overlays cannot set them.
+
 Key environment variables:
 
 | Variable | Purpose |
diff --git a/config.example.toml b/config.example.toml
index c8a7155b..e158a023 100644
--- a/config.example.toml
+++ b/config.example.toml
@@ -191,12 +191,21 @@ max_subagents = 10 # optional (1-20)
 #   SGLang:    SGLANG_BASE_URL, SGLANG_MODEL, optional SGLANG_API_KEY
 #   vLLM:      VLLM_BASE_URL, VLLM_MODEL, optional VLLM_API_KEY
 #   Ollama:    OLLAMA_BASE_URL, OLLAMA_MODEL, optional OLLAMA_API_KEY
+#
+# Custom DeepSeek-compatible APIs usually do not need a new provider table:
+# set `provider = "deepseek"` and override [providers.deepseek].base_url/model.
+# For generic OpenAI-compatible gateways, use `provider = "openai"` and the
+# [providers.openai] table below. Keep provider/api_key/base_url in user config
+# or environment variables; project overlays are not allowed to set them.
 
 # DeepSeek Platform (https://platform.deepseek.com)
 [providers.deepseek]
 # api_key = "YOUR_DEEPSEEK_API_KEY"
 # base_url = "https://api.deepseek.com/beta"
 # model = "deepseek-v4-pro"
+# Custom DeepSeek-compatible example:
+# base_url = "https://your-provider.example/v1"
+# model = "deepseek-ai/DeepSeek-V4-Pro"
 # http_headers = { "X-Model-Provider-Id" = "your-model-provider" } # optional custom request headers
 
 # NVIDIA NIM-hosted DeepSeek V4 (https://build.nvidia.com)
@@ -213,6 +222,9 @@ max_subagents = 10 # optional (1-20)
 # api_key = "YOUR_OPENAI_COMPATIBLE_API_KEY"
 # base_url = "https://api.openai.com/v1"
 # model = "gpt-4.1"
+# Gateway example:
+# base_url = "https://gateway.example/v1"
+# model = "your-deepseek-compatible-model"
 
 # AtlasCloud OpenAI-compatible endpoint (https://www.atlascloud.ai/docs/models/llm)
 [providers.atlascloud]
diff --git a/crates/tui/src/tui/views/mod.rs b/crates/tui/src/tui/views/mod.rs
index 68ce1ac7..2f56ada2 100644
--- a/crates/tui/src/tui/views/mod.rs
+++ b/crates/tui/src/tui/views/mod.rs
@@ -1137,6 +1137,7 @@ fn config_hint_for_key(key: &str) -> &'static str {
         "theme" => "system | dark | light | grayscale",
         "locale" => "auto | en | ja | zh-Hans | pt-BR",
         "background_color" => "#RRGGBB | default",
+        "base_url" => "save user config; e.g. https://api.deepseek.com/beta or https://gateway/v1",
         "default_mode" => "agent | plan | yolo",
         "sidebar_width" => "10..=50",
         "sidebar_focus" => "auto | work | tasks | agents | context | hidden",
diff --git a/docs/PROVIDERS.md b/docs/PROVIDERS.md
index 2899b980..1c0950ee 100644
--- a/docs/PROVIDERS.md
+++ b/docs/PROVIDERS.md
@@ -64,6 +64,48 @@ Non-local `http://` base URLs are rejected unless
 `DEEPSEEK_ALLOW_INSECURE_HTTP=1` is set. Loopback HTTP URLs are allowed for
 self-hosted runtimes.
 
+## Custom DeepSeek-Compatible Endpoints
+
+Most custom DeepSeek-compatible deployments can use an existing provider ID.
+Do not create `[providers.deepseek_custom]`; the provider table names are fixed.
+Instead, choose the closest shipped route and override its endpoint/model:
+
+- DeepSeek-compatible hosted API: keep `provider = "deepseek"` and set
+  `[providers.deepseek].base_url` plus `[providers.deepseek].model`, or launch
+  with `DEEPSEEK_BASE_URL` and `DEEPSEEK_MODEL`.
+- Generic OpenAI-compatible gateway: use `provider = "openai"` with
+  `[providers.openai].base_url` plus `[providers.openai].model`, or launch with
+  `OPENAI_BASE_URL` and `OPENAI_MODEL`.
+- Local OpenAI-compatible runtimes: use `provider = "vllm"`, `"sglang"`, or
+  `"ollama"` with the matching provider-specific base URL/model values.
+
+Example user config for a DeepSeek-compatible host:
+
+```toml
+provider = "deepseek"
+
+[providers.deepseek]
+api_key = "YOUR_API_KEY"
+base_url = "https://your-provider.example/v1"
+model = "deepseek-ai/DeepSeek-V4-Pro"
+```
+
+Example user config for a generic gateway:
+
+```toml
+provider = "openai"
+
+[providers.openai]
+api_key = "YOUR_GATEWAY_API_KEY"
+base_url = "https://gateway.example/v1"
+model = "your-deepseek-compatible-model"
+```
+
+Keep `provider`, `api_key`, and `base_url` in user config or process
+environment. Project-local config overlays intentionally cannot set those keys,
+so a repository cannot silently redirect prompts or credentials to another
+endpoint.
+
 ## Shipped Providers
 
 | Provider ID | TOML table | Auth env | Base URL env and default | Default or static models | Notes |