feat(model): LLM token 预算可配置化 — models.json每模型maxTokens + LLM_FALLBACK_MAX_TOKENS回退兜底

- config.go: LLMConfig.FallbackMaxTokens(LLM_FALLBACK_MAX_TOKENS, 默认8192)
- runtimeconfig/models.go: Group.MaxTokens(models.json每模型独立预算, 负值拒绝)
- model/fallback.go: Chain.WithTokenBudget + applyBudget; runtime.go buildSnapshot接入(active.MaxTokens, env.FallbackMaxTokens)
- 优先级: 显式Request.MaxTokens > 组maxTokens > 仅多步链末端的LLM_FALLBACK_MAX_TOKENS > 适配器默认8192; 单步链不动env兜底(避免OpenAI主模型行为回归)
- gateway admin: AdminLlmProvider.MaxTokens 透传/回显/负值400
- .env.example + .env(LLM_FALLBACK_MAX_TOKENS=8192); Docs/api-client v0.27 + api-reference + design/04
- 新增测试(config/runtimeconfig/budget_test/admin_write), build/vet/test绿+3平台交叉编译

internal/config/config.go

@@ -90,6 +90,13 @@ type LLMConfig struct {
 	// set, the model router routes image content to it (see model.Router.WithVisionModel).
 	VisionModel string `env:"LLM_VISION_MODEL"`
 
+	// FallbackMaxTokens caps the last-resort fallback model in a group's chain
+	// (primary → fallback). It is the final safety budget: it only applies when
+	// the chain actually has a fallback step, that group sets no per-group
+	// MaxTokens (models.json maxTokens) and the request carries no explicit
+	// budget. Zero disables the cap (the adapter default then applies).
+	FallbackMaxTokens int `env:"LLM_FALLBACK_MAX_TOKENS" default:"8192"`
+
 	// Anthropic native provider, used when Provider=anthropic. Independent
 	// config block so each vendor is a self-contained config.
 	AnthropicBaseURL  string `env:"ANTHROPIC_BASE_URL"`

internal/config/config_test.go

@@ -91,6 +91,55 @@ IOT_PROVIDER=none
 	}
 }
 
+// unsetEnvForTest clears key for the test and restores the original value (or
+// absence) on cleanup, so a .env file is not shadowed by an ambient process env
+// variable. config tests are not parallel, so this is safe.
+func unsetEnvForTest(t *testing.T, key string) {
+	t.Helper()
+	if v, ok := os.LookupEnv(key); ok {
+		t.Cleanup(func() { _ = os.Setenv(key, v) })
+	} else {
+		t.Cleanup(func() { _ = os.Unsetenv(key) })
+	}
+	if err := os.Unsetenv(key); err != nil {
+		t.Fatalf("unset %s: %v", key, err)
+	}
+}
+
+func TestLoad_LlmFallbackMaxTokens(t *testing.T) {
+	t.Setenv("JWT_SECRET", strings.Repeat("s", 40))
+	unsetEnvForTest(t, "LLM_FALLBACK_MAX_TOKENS")
+
+	// Default: the last-resort fallback budget is a meaningful 8192.
+	cfg, err := Load("")
+	if err != nil {
+		t.Fatalf("Load() error: %v", err)
+	}
+	if cfg.LLM.FallbackMaxTokens != 8192 {
+		t.Errorf("LLM.FallbackMaxTokens = %d, want default 8192", cfg.LLM.FallbackMaxTokens)
+	}
+
+	// A .env file is parsed into the field.
+	path := writeEnvFile(t, "LLM_FALLBACK_MAX_TOKENS=4096\n")
+	cfg, err = Load(path)
+	if err != nil {
+		t.Fatalf("Load(%q) error: %v", path, err)
+	}
+	if cfg.LLM.FallbackMaxTokens != 4096 {
+		t.Errorf("LLM.FallbackMaxTokens = %d, want 4096 from .env", cfg.LLM.FallbackMaxTokens)
+	}
+
+	// Process env wins over .env.
+	t.Setenv("LLM_FALLBACK_MAX_TOKENS", "2048")
+	cfg, err = Load(path)
+	if err != nil {
+		t.Fatalf("Load(%q) error: %v", path, err)
+	}
+	if cfg.LLM.FallbackMaxTokens != 2048 {
+		t.Errorf("LLM.FallbackMaxTokens = %d, want 2048 (process env wins)", cfg.LLM.FallbackMaxTokens)
+	}
+}
+
 func TestLoad_MissingRequiredFails(t *testing.T) {
 	// Do not set JWT_SECRET.
 	if _, err := Load(""); err == nil {

internal/config/runtimeconfig/models.go

@@ -42,6 +42,11 @@ type Group struct {
 	Model      string `json:"model"`
 	Fallback   string `json:"fallback,omitempty"`
 	Multimodal bool   `json:"multimodal,omitempty"`
+	// MaxTokens is the group's own token budget, applied to every model in the
+	// group's fallback chain (primary and fallback). Zero means "unset": the
+	// last-resort fallback step then falls back to LLM_FALLBACK_MAX_TOKENS, and
+	// beyond that the adapter default applies.
+	MaxTokens int `json:"maxTokens,omitempty"`
 }
 
 // ErrInvalidGroup is returned when a group fails schema validation.
@@ -67,6 +72,9 @@ func (g Group) Validate() error {
 	if strings.TrimSpace(g.Model) == "" {
 		return fmt.Errorf("model is required")
 	}
+	if g.MaxTokens < 0 {
+		return fmt.Errorf("maxTokens must be >= 0, got %d", g.MaxTokens)
+	}
 	return nil
 }
 

internal/config/runtimeconfig/models_test.go

@@ -164,6 +164,59 @@ func TestSaveLoadRoundTrip(t *testing.T) {
 	}
 }
 
+func TestGroupMaxTokensRoundTrip(t *testing.T) {
+	// maxTokens is decoded from a hand-written models.json.
+	path := writeModelsFile(t, `[
+		{"id":"openai","provider":"openai","baseUrl":"https://a","apiKey":"sk-1","model":"gpt-4o","maxTokens":4096}
+	]`)
+	groups, warn := LoadModels(path, envCfg())
+	if warn != nil {
+		t.Fatalf("warn = %v, want nil", warn)
+	}
+	if len(groups) != 1 || groups[0].MaxTokens != 4096 {
+		t.Fatalf("groups = %+v, want one group with maxTokens 4096", groups)
+	}
+
+	// SaveModels writes it back, and LoadModels reads it again.
+	out := filepath.Join(t.TempDir(), "models.json")
+	in := []Group{
+		{ID: "openai", Provider: ProviderOpenAI, BaseURL: "https://a", APIKey: "sk-1", Model: "gpt-4o", MaxTokens: 2048},
+		{ID: "claude", Provider: ProviderAnthropic, BaseURL: "https://b", APIKey: "sk-2", Model: "claude"},
+	}
+	if err := SaveModels(out, in); err != nil {
+		t.Fatalf("SaveModels: %v", err)
+	}
+	raw, err := os.ReadFile(out)
+	if err != nil {
+		t.Fatalf("read saved file: %v", err)
+	}
+	if !strings.Contains(string(raw), `"maxTokens": 2048`) {
+		t.Errorf("saved file missing maxTokens: %s", raw)
+	}
+	round, warn := LoadModels(out, envCfg())
+	if warn != nil {
+		t.Fatalf("load warn = %v", warn)
+	}
+	if round[0].MaxTokens != 2048 || round[1].MaxTokens != 0 {
+		t.Fatalf("round trip maxTokens = (%d,%d), want (2048,0)", round[0].MaxTokens, round[1].MaxTokens)
+	}
+
+	// Upsert and Activate preserve the field.
+	upserted := Upsert(round, Group{ID: "openai", Provider: ProviderOpenAI, BaseURL: "https://a2", Model: "gpt-4o", MaxTokens: 3000})
+	if upserted[0].MaxTokens != 3000 {
+		t.Errorf("Upsert maxTokens = %d, want 3000", upserted[0].MaxTokens)
+	}
+	activated := Activate(round, Group{ID: "claude", Provider: ProviderAnthropic, BaseURL: "https://b", Model: "claude", MaxTokens: 512})
+	if activated[0].MaxTokens != 512 {
+		t.Errorf("Activate maxTokens = %d, want 512", activated[0].MaxTokens)
+	}
+
+	// A negative budget is rejected by validation (never silently persisted).
+	if err := (Group{ID: "x", Provider: ProviderOpenAI, BaseURL: "https://x", Model: "m", MaxTokens: -1}).Validate(); err == nil {
+		t.Fatal("expected Validate to reject a negative maxTokens")
+	}
+}
+
 func TestSaveModels_RejectsInvalid(t *testing.T) {
 	path := filepath.Join(t.TempDir(), "models.json")
 	if err := SaveModels(path, []Group{{ID: "", Provider: "x", BaseURL: "https://a", Model: "m"}}); err == nil {

internal/runtime/model/budget_test.go

@@ -0,0 +1,185 @@
+package model
+
+import (
+	"context"
+	"encoding/json"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"path/filepath"
+	"testing"
+
+	"git.yeij.top/AskaEth/Cyrene_v2/internal/config"
+	"git.yeij.top/AskaEth/Cyrene_v2/internal/config/runtimeconfig"
+)
+
+// newFallbackDispatchServer serves two chain steps from one endpoint: the
+// "main" model fails so the chain moves on, every other model succeeds.
+func newFallbackDispatchServer(t *testing.T, ch chan<- capturedRequest) *httptest.Server {
+	t.Helper()
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		var body map[string]any
+		_ = json.NewDecoder(r.Body).Decode(&body)
+		ch <- capturedRequest{method: r.Method, path: r.URL.Path, body: body}
+		if body["model"] == "main" {
+			w.WriteHeader(http.StatusInternalServerError)
+			_, _ = io.WriteString(w, `{"error":"down"}`)
+			return
+		}
+		w.Header().Set("Content-Type", "application/json")
+		w.WriteHeader(http.StatusOK)
+		_, _ = io.WriteString(w, okCompletion)
+	}))
+	t.Cleanup(srv.Close)
+	return srv
+}
+
+func chatOnce(t *testing.T, chain *Chain) {
+	t.Helper()
+	if _, err := chain.Chat(context.Background(),
+		Request{Messages: []Message{TextMessage(RoleUser, "hi")}}, Options{}); err != nil {
+		t.Fatalf("Chain.Chat error: %v", err)
+	}
+}
+
+// TestChain_Chat_GroupBudgetAppliesToPrimary asserts the active group's own
+// maxTokens is applied to a request that carries no explicit budget.
+func TestChain_Chat_GroupBudgetAppliesToPrimary(t *testing.T) {
+	t.Parallel()
+	ch := make(chan capturedRequest, 1)
+	srv := newCompletionServer(t, http.StatusOK, "application/json", okCompletion, ch)
+	chain := NewChain(Step{Model: "m", Adapter: NewOpenAIChat(config.LLMConfig{BaseURL: srv.URL, Model: "m"})}).
+		WithTokenBudget(4096, 8192)
+
+	chatOnce(t, chain)
+	if got := (<-ch).body["max_tokens"]; got != float64(4096) {
+		t.Errorf("body.max_tokens = %v, want the group budget 4096", got)
+	}
+}
+
+// TestChain_Chat_ExplicitRequestWinsOverGroupBudget asserts an explicit
+// Request.MaxTokens is never overridden (the small review/judge budgets).
+func TestChain_Chat_ExplicitRequestWinsOverGroupBudget(t *testing.T) {
+	t.Parallel()
+	ch := make(chan capturedRequest, 1)
+	srv := newCompletionServer(t, http.StatusOK, "application/json", okCompletion, ch)
+	chain := NewChain(Step{Model: "m", Adapter: NewOpenAIChat(config.LLMConfig{BaseURL: srv.URL, Model: "m"})}).
+		WithTokenBudget(4096, 8192)
+
+	if _, err := chain.Chat(context.Background(),
+		Request{Messages: []Message{TextMessage(RoleUser, "hi")}, MaxTokens: 64}, Options{}); err != nil {
+		t.Fatalf("Chain.Chat error: %v", err)
+	}
+	if got := (<-ch).body["max_tokens"]; got != float64(64) {
+		t.Errorf("body.max_tokens = %v, want the explicit 64", got)
+	}
+}
+
+// TestChain_Chat_FallbackEndAppliesEnvBudget asserts the last-resort budget only
+// reaches the final fallback step, never the primary.
+func TestChain_Chat_FallbackEndAppliesEnvBudget(t *testing.T) {
+	t.Parallel()
+	primaryCh := make(chan capturedRequest, 1)
+	primary := newCompletionServer(t, http.StatusInternalServerError, "application/json", `{"error":"down"}`, primaryCh)
+	backupCh := make(chan capturedRequest, 1)
+	backup := newCompletionServer(t, http.StatusOK, "application/json", okCompletion, backupCh)
+	chain := NewChain(
+		Step{Model: "main", Adapter: NewOpenAIChat(config.LLMConfig{BaseURL: primary.URL, Model: "main"})},
+		Step{Model: "backup", Adapter: NewOpenAIChat(config.LLMConfig{BaseURL: backup.URL, Model: "backup"})},
+	).WithTokenBudget(0, 3000)
+
+	chatOnce(t, chain)
+	if got := (<-primaryCh).body["max_tokens"]; got != nil {
+		t.Errorf("primary body.max_tokens = %v, want omitted (no budget on the primary)", got)
+	}
+	if got := (<-backupCh).body["max_tokens"]; got != float64(3000) {
+		t.Errorf("fallback body.max_tokens = %v, want the env fallback budget 3000", got)
+	}
+}
+
+// TestChain_Chat_GroupBudgetWinsOverFallbackEnv asserts a group maxTokens beats
+// the last-resort env budget even on the final fallback step.
+func TestChain_Chat_GroupBudgetWinsOverFallbackEnv(t *testing.T) {
+	t.Parallel()
+	primaryCh := make(chan capturedRequest, 1)
+	primary := newCompletionServer(t, http.StatusInternalServerError, "application/json", `{"error":"down"}`, primaryCh)
+	backupCh := make(chan capturedRequest, 1)
+	backup := newCompletionServer(t, http.StatusOK, "application/json", okCompletion, backupCh)
+	chain := NewChain(
+		Step{Model: "main", Adapter: NewOpenAIChat(config.LLMConfig{BaseURL: primary.URL, Model: "main"})},
+		Step{Model: "backup", Adapter: NewOpenAIChat(config.LLMConfig{BaseURL: backup.URL, Model: "backup"})},
+	).WithTokenBudget(2000, 999)
+
+	chatOnce(t, chain)
+	if got := (<-backupCh).body["max_tokens"]; got != float64(2000) {
+		t.Errorf("fallback body.max_tokens = %v, want the group budget 2000", got)
+	}
+}
+
+// TestChain_Chat_SingleStepIgnoresFallbackEnv asserts a chain with no fallback
+// model (one step = the primary) never gets the last-resort budget, so the
+// adapter default is preserved.
+func TestChain_Chat_SingleStepIgnoresFallbackEnv(t *testing.T) {
+	t.Parallel()
+	ch := make(chan capturedRequest, 1)
+	srv := newCompletionServer(t, http.StatusOK, "application/json", okCompletion, ch)
+	chain := NewChain(Step{Model: "m", Adapter: NewOpenAIChat(config.LLMConfig{BaseURL: srv.URL, Model: "m"})}).
+		WithTokenBudget(0, 3000)
+
+	chatOnce(t, chain)
+	if got := (<-ch).body["max_tokens"]; got != nil {
+		t.Errorf("body.max_tokens = %v, want omitted (single-step chain is not a fallback)", got)
+	}
+}
+
+// TestRuntimeLLM_GroupMaxTokensEndToEnd proves the models.json maxTokens field
+// reaches the provider request body through the real runtime stack.
+func TestRuntimeLLM_GroupMaxTokensEndToEnd(t *testing.T) {
+	ch := make(chan capturedRequest, 1)
+	srv := newCompletionServer(t, http.StatusOK, "application/json", okCompletion, ch)
+	path := filepath.Join(t.TempDir(), "models.json")
+	if err := runtimeconfig.SaveModels(path, []runtimeconfig.Group{
+		{ID: "openai", Provider: ProviderOpenAI, BaseURL: srv.URL, APIKey: "sk-1", Model: "m", MaxTokens: 1234},
+	}); err != nil {
+		t.Fatalf("SaveModels: %v", err)
+	}
+	m := NewRuntimeLLM(path, rtEnv(), nil)
+	if got := m.Groups()[0].MaxTokens; got != 1234 {
+		t.Fatalf("Groups()[0].MaxTokens = %d, want 1234", got)
+	}
+	if _, err := m.Chat(context.Background(),
+		Request{Messages: []Message{TextMessage(RoleUser, "hi")}}, Options{}); err != nil {
+		t.Fatalf("RuntimeLLM.Chat error: %v", err)
+	}
+	if got := (<-ch).body["max_tokens"]; got != float64(1234) {
+		t.Errorf("body.max_tokens = %v, want the group budget 1234", got)
+	}
+}
+
+// TestRuntimeLLM_FallbackEndAppliesEnvBudget proves LLM_FALLBACK_MAX_TOKENS is
+// wired from config through buildSnapshot into the final fallback step.
+func TestRuntimeLLM_FallbackEndAppliesEnvBudget(t *testing.T) {
+	ch := make(chan capturedRequest, 2)
+	srv := newFallbackDispatchServer(t, ch)
+	path := filepath.Join(t.TempDir(), "models.json")
+	if err := runtimeconfig.SaveModels(path, []runtimeconfig.Group{
+		{ID: "openai", Provider: ProviderOpenAI, BaseURL: srv.URL, APIKey: "sk-1", Model: "main", Fallback: "backup"},
+	}); err != nil {
+		t.Fatalf("SaveModels: %v", err)
+	}
+	env := rtEnv()
+	env.FallbackMaxTokens = 2500
+	m := NewRuntimeLLM(path, env, nil)
+	if _, err := m.Chat(context.Background(),
+		Request{Messages: []Message{TextMessage(RoleUser, "hi")}}, Options{}); err != nil {
+		t.Fatalf("RuntimeLLM.Chat error: %v", err)
+	}
+	primary := <-ch
+	backup := <-ch
+	if got := primary.body["max_tokens"]; got != nil {
+		t.Errorf("primary body.max_tokens = %v, want omitted", got)
+	}
+	if got := backup.body["max_tokens"]; got != float64(2500) {
+		t.Errorf("fallback body.max_tokens = %v, want LLM_FALLBACK_MAX_TOKENS 2500", got)
+	}
+}

internal/runtime/model/fallback.go

@@ -19,6 +19,13 @@ type Step struct {
 // single provider is expected.
 type Chain struct {
 	steps []Step
+	// groupMaxTokens is the active model group's own budget (models.json
+	// maxTokens). When > 0 it applies to every step of the group's chain and
+	// wins over fallbackMaxTokens.
+	groupMaxTokens int
+	// fallbackMaxTokens is the last-resort budget (LLM_FALLBACK_MAX_TOKENS). It
+	// only applies to the final step of a chain that actually has a fallback.
+	fallbackMaxTokens int
 }
 
 // NewChain builds a fallback chain from the given steps.
@@ -26,6 +33,37 @@ func NewChain(steps ...Step) *Chain {
 	return &Chain{steps: steps}
 }
 
+// WithTokenBudget sets the chain's token budgets: the active group's own budget
+// and the last-resort fallback budget. It must be called before the chain is
+// published to concurrent callers (the runtime builds a fresh chain per
+// snapshot and swaps it in atomically), so the fields are never mutated in
+// flight.
+func (c *Chain) WithTokenBudget(groupMaxTokens, fallbackMaxTokens int) *Chain {
+	c.groupMaxTokens = groupMaxTokens
+	c.fallbackMaxTokens = fallbackMaxTokens
+	return c
+}
+
+// applyBudget resolves the effective MaxTokens for step idx, honoring the
+// precedence: an explicit Request.MaxTokens > the group's MaxTokens > the
+// last-resort LLM_FALLBACK_MAX_TOKENS > the adapter default. The last-resort
+// budget only applies when the chain really has a fallback step (len > 1) and
+// only to that final step; a single-step chain is a primary model, not a
+// fallback, so its adapter default is left untouched.
+func (c *Chain) applyBudget(req Request, idx int) Request {
+	if req.MaxTokens != 0 {
+		return req
+	}
+	if c.groupMaxTokens > 0 {
+		req.MaxTokens = c.groupMaxTokens
+		return req
+	}
+	if c.fallbackMaxTokens > 0 && len(c.steps) > 1 && idx == len(c.steps)-1 {
+		req.MaxTokens = c.fallbackMaxTokens
+	}
+	return req
+}
+
 // NewOpenAIChatChain builds a fallback chain from a single supplier config: the
 // primary model first, then cfg.Fallback (when set and distinct), both served
 // by an OpenAIChatAdapter against the same OpenAI-compatible endpoint. It
@@ -45,8 +83,8 @@ func (c *Chain) Chat(ctx context.Context, req Request, opts Options) (Response,
 		return Response{}, ErrNoSteps
 	}
 	var lastErr error
-	for _, s := range c.steps {
-		stepReq := req
+	for i, s := range c.steps {
+		stepReq := c.applyBudget(req, i)
 		if s.Model != "" {
 			stepReq.Model = s.Model
 		}
@@ -68,8 +106,8 @@ func (c *Chain) ChatStream(ctx context.Context, req Request, onEvent func(Stream
 		return Response{}, ErrNoSteps
 	}
 	var lastErr error
-	for _, s := range c.steps {
-		stepReq := req
+	for i, s := range c.steps {
+		stepReq := c.applyBudget(req, i)
 		if s.Model != "" {
 			stepReq.Model = s.Model
 		}

internal/runtime/model/runtime.go

@@ -169,6 +169,12 @@ func buildSnapshot(groups []runtimeconfig.Group, env config.LLMConfig) (*runtime
 	if err != nil && !errors.Is(err, ErrNoModel) {
 		return nil, err
 	}
+	if chain != nil {
+		// Budgets are resolved inside the chain: the active group's own
+		// maxTokens (models.json) wins, and env.FallbackMaxTokens only caps the
+		// last step of a chain that really has a fallback (design/04 §3.1).
+		chain = chain.WithTokenBudget(active.MaxTokens, env.FallbackMaxTokens)
+	}
 	router := NewRouter(DefaultModelForProvider(cfg),
 		WithVisionModel(env.VisionModel),
 		WithDefaultProvider(cfg.Provider),

internal/services/gateway/admin.go

@@ -58,6 +58,10 @@ type AdminLlmProvider struct {
 	Multimodal bool   `json:"multimodal"`
 	Enabled    bool   `json:"enabled"`
 	Fallback   string `json:"fallback,omitempty"`
+	// MaxTokens is the group's own token budget (0 = unset; the runtime then
+	// falls back to LLM_FALLBACK_MAX_TOKENS on the last fallback step, then the
+	// adapter default).
+	MaxTokens int `json:"maxTokens,omitempty"`
 }
 
 // AdminLlmConfig is the wire shape of GET /api/v1/admin/llm.
@@ -360,6 +364,7 @@ func (s *Server) adminGetLlm(w http.ResponseWriter, r *http.Request) {
 			Multimodal: g.Multimodal,
 			Enabled:    i == 0,
 			Fallback:   g.Fallback,
+			MaxTokens:  g.MaxTokens,
 		})
 	}
 	writeJSON(w, http.StatusOK, AdminLlmConfig{Providers: providers})

internal/services/gateway/admin_write_llm_channels.go

@@ -37,7 +37,8 @@ const (
 
 // llmProviderRequest is the POST /api/v1/admin/llm body for adding/updating a
 // provider group. Name is a client-side display label (not persisted — the
-// models.json schema carries id/provider/baseUrl/apiKey/model/fallback/multimodal).
+// models.json schema carries id/provider/baseUrl/apiKey/model/fallback/
+// multimodal/maxTokens).
 type llmProviderRequest struct {
 	ID         string `json:"id"`
 	Name       string `json:"name"`
@@ -47,6 +48,10 @@ type llmProviderRequest struct {
 	Model      string `json:"model"`
 	Multimodal bool   `json:"multimodal"`
 	Fallback   string `json:"fallback"`
+	// MaxTokens is the group's own token budget. Zero means unset (the runtime
+	// falls back to LLM_FALLBACK_MAX_TOKENS on the last fallback step, then the
+	// adapter default). Negative is rejected.
+	MaxTokens int `json:"maxTokens"`
 }
 
 // adminAddLlmProvider saves a provider group to models.json (read-modify-write,
@@ -64,6 +69,11 @@ func (s *Server) adminAddLlmProvider(w http.ResponseWriter, r *http.Request) {
 		writeError(w, apperr.Wrap(apperr.ErrBadRequest, "bad_request", "baseUrl and model are required"))
 		return
 	}
+	if req.MaxTokens < 0 {
+		s.auditClaims(r, "llm.addProvider", "error")
+		writeError(w, apperr.Wrap(apperr.ErrBadRequest, "bad_request", "maxTokens must be >= 0"))
+		return
+	}
 	provider := req.Provider
 	if provider == "" {
 		provider = model.ProviderOpenAI
@@ -92,6 +102,7 @@ func (s *Server) adminAddLlmProvider(w http.ResponseWriter, r *http.Request) {
 		Model:      req.Model,
 		Fallback:   req.Fallback,
 		Multimodal: req.Multimodal,
+		MaxTokens:  req.MaxTokens,
 	})
 	if err := runtimeconfig.SaveModels(s.llm.Path(), groups); err != nil {
 		s.auditClaims(r, "llm.addProvider", "error")
@@ -114,6 +125,7 @@ func (s *Server) adminAddLlmProvider(w http.ResponseWriter, r *http.Request) {
 		Multimodal: req.Multimodal,
 		Enabled:    id == s.llm.Group().ID,
 		Fallback:   req.Fallback,
+		MaxTokens:  req.MaxTokens,
 	}
 	s.auditClaims(r, "llm.addProvider", "ok")
 	writeJSON(w, http.StatusCreated, map[string]any{

internal/services/gateway/admin_write_test.go

@@ -231,7 +231,7 @@ func TestAdminAddLlmProviderPersistsAndReloads(t *testing.T) {
 	tok := signAny(t, jwt, "acct", auth.RoleOwner)
 
 	resp, body := doReq(t, http.MethodPost, ts.URL+"/api/v1/admin/llm",
-		map[string]any{"id": "deepseek", "provider": "openai", "baseUrl": "https://api.deepseek.com/v1", "apiKey": "sk-ds", "model": "deepseek-chat", "multimodal": true}, tok)
+		map[string]any{"id": "deepseek", "provider": "openai", "baseUrl": "https://api.deepseek.com/v1", "apiKey": "sk-ds", "model": "deepseek-chat", "multimodal": true, "maxTokens": 1234}, tok)
 	if resp.StatusCode != http.StatusCreated {
 		t.Fatalf("status = %d, want 201 (body=%s)", resp.StatusCode, body)
 	}
@@ -243,7 +243,7 @@ func TestAdminAddLlmProviderPersistsAndReloads(t *testing.T) {
 	if err := json.Unmarshal(decodeBody(t, body)["data"], &res); err != nil {
 		t.Fatalf("decode add: %v", err)
 	}
-	if !res.Persisted || res.Path != modelsPath || res.Provider.Model != "deepseek-chat" {
+	if !res.Persisted || res.Path != modelsPath || res.Provider.Model != "deepseek-chat" || res.Provider.MaxTokens != 1234 {
 		t.Fatalf("add res = %+v", res)
 	}
 
@@ -252,8 +252,8 @@ func TestAdminAddLlmProviderPersistsAndReloads(t *testing.T) {
 	if warn != nil {
 		t.Fatalf("load models warn = %v", warn)
 	}
-	if len(groups) == 0 || groups[0].ID != "deepseek" || groups[0].APIKey != "sk-ds" {
-		t.Fatalf("file groups = %+v, want deepseek first with sk-ds", groups)
+	if len(groups) == 0 || groups[0].ID != "deepseek" || groups[0].APIKey != "sk-ds" || groups[0].MaxTokens != 1234 {
+		t.Fatalf("file groups = %+v, want deepseek first with sk-ds and maxTokens 1234", groups)
 	}
 
 	// The running stack reflects the new active provider/model (hot reload).
@@ -270,8 +270,8 @@ func TestAdminAddLlmProviderPersistsAndReloads(t *testing.T) {
 	if err := json.Unmarshal(decodeBody(t, gBody)["data"], &list); err != nil {
 		t.Fatalf("decode list: %v", err)
 	}
-	if len(list.Providers) == 0 || list.Providers[0].Model != "deepseek-chat" {
-		t.Fatalf("list = %+v, want deepseek-chat first", list.Providers)
+	if len(list.Providers) == 0 || list.Providers[0].Model != "deepseek-chat" || list.Providers[0].MaxTokens != 1234 {
+		t.Fatalf("list = %+v, want deepseek-chat first with maxTokens 1234", list.Providers)
 	}
 	if strings.Contains(string(gBody), "sk-ds") || strings.Contains(string(gBody), "sk-env") {
 		t.Fatalf("API key leaked in GET /admin/llm: %s", gBody)