Configure models and credentials
Add model profiles, set the default model, and configure cloud credentials.
Model configuration answers "which model can an agent call". This page sets up model profiles, API keys, reasoning effort, and cloud credentials so the Bind capabilities step can select a model.
Prerequisites
- An OpenAI-compatible model endpoint, or an official Ksyun / OpenAI key.
- Network access to that endpoint. For an enterprise gateway, confirm the Host machine can reach it directly.
- The cloud credentials block is needed only for builds, deployments, and cloud resource access.
Steps
Open model and credential settings
Go to Settings → Models and credentials. The panel opens automatically on first launch; you can also open it later.
The page has two blocks: Models and providers on top and Cloud credentials below. For local conversations only, cloud credentials can stay empty.
Where to look
Add a model profile
Click + Add model in the top-right corner. A new profile starts with:
| Field | Initial value |
|---|---|
| Provider | Ksyun model service |
| API base URL | That provider's official default |
| Credential name | AGENTKIT_MODEL_API_KEY_<timestamp>, generated for you |
| Enabled | Yes |
One profile is one combination of provider + base URL + model + credential. To use two providers at once, create two profiles.
Where to look
Fill in connection and credential
Connection
| Provider | API base URL | Notes |
|---|---|---|
| Ksyun model service | Read-only, shows the official default | Nothing to type; switch to Custom to edit |
| OpenAI | Prefilled with the official URL | Can be replaced with a same-protocol proxy |
| Custom provider | You must fill it in | Any OpenAI-compatible service |
Validation: the URL must be HTTP(S) and must not carry user info, query parameters, or a fragment. Failing returns MODEL_ENDPOINT_INVALID with "the model service address must use HTTP(S) and must not contain credentials, query parameters, or a fragment". Trailing /chat/completions, /responses, and /models are trimmed automatically.
Credential
Enter the secret in API Key. For a profile that is already configured, the placeholder reads "configured; leave empty to keep" — an empty value means no change.
Where the key is stored
The API key is written only to the local Host credential store. It never enters agent configuration, browser form refill, or logs. The credential source is shown below the input: local file, global configuration, current workspace, environment variable, this session, or not configured. See Security and public boundary.
After filling in the key, click Read models. The browser never talks to the model service directly — the Host performs the read.
Choose a model name and reasoning effort
Model name: once you have clicked Read models, pick from the dropdown, or type a model name outside the catalog.
Reasoning effort: every dropdown entry reads "UI level → value actually sent", for example 最高 → high. Choose Not enabled to send no reasoning level at all.
| Provider | Levels offered | Default level | reasoning_effort actually sent |
|---|---|---|---|
| Ksyun model service | low / high / max | high | low / high / max |
| OpenAI | low / medium / high | medium | low / medium / high |
| Codex | low / high / max | high | low / high / high (max degrades to high) |
| Custom provider | low / high | high | low / high |
Switching provider falls back to the new provider's default level when the previous level is not in its enum, with a notice — rather than letting the upstream reject it later.
The Input capability row is read-only and shows the text / image capabilities the catalog reported. When discovery fails it explains why: no capability information, catalog temporarily unreadable, or model not found in the catalog.
Where to look
Manage multiple profiles
| Action | Where | Behavior |
|---|---|---|
| Set as default | Top-right of the detail pane | New sessions use this model; other profiles lose the default flag |
| Disable / Enable | Top-right of the detail pane | A disabled profile disappears from an agent's selectable models |
| Revert changes | Top-right of the detail pane | Drops only this profile's in-memory draft back to the saved configuration |
| Remove | Top-right of the detail pane | Deletes the profile; hidden when only one remains |
Three hard constraints:
- At least one enabled model must remain, otherwise "keep at least one enabled model".
- Every profile needs a model name, otherwise "every model profile needs a model name".
- The default profile needs a usable credential, otherwise "enter the model API key".
Edits go into an in-memory draft first and the profile card shows an Unsaved chip. Closing and reopening the panel keeps the draft; reloading the page or changing windows loses it.
Save the configuration
Click Save configuration in the bottom-right corner (in first-run onboarding it reads Save and continue or Save and finish, depending on how you got here).
Saving runs in order: write model profiles → sync credentials → apply profiles to DSH's provider routing → broadcast the model-changed event. The button shows Saving… meanwhile.
On success the footer shows:
已保存多个模型配置;标记为“默认”的模型用于新会话,Agent 可在创建或编辑时多选模型绑定。Reload explicitly discards every draft and returns to the stored configuration; if drafts were discarded you also get "unsaved drafts discarded and saved configuration reloaded".
Optional: configure cloud credentials
Needed only for builds, deployments, and cloud resource access.
| Field | Required | Notes |
|---|---|---|
| Access Key | Yes (first time) | Shows "configured; leave empty to keep" once set |
| Secret Key | Yes (first time) | Same as above |
| Account ID | No | Optional |
| Region | No | For example cn-beijing-6 |
| Control plane URL | No | The AgentEngine control plane address |
| Object storage bucket | No | Optional |
The last four live under Advanced cloud settings. On first configuration Access Key and Secret Key must be filled together, otherwise "enter Access Key and Secret Key, or skip cloud configuration". Success reads "cloud credentials saved".
Where to look
What success looks like
All four must hold:
- The model card shows a green Configured, not Needs configuration.
- A Default chip appears next to exactly one card's title.
- The status strip in the top-right names the current default model.
- In the agent creation form's Bind capabilities step, the Default model dropdown lists that model.
Common errors
| Error code | Cause | Fix |
|---|---|---|
MODEL_CREDENTIAL_MISSING | The default profile has no API key yet | Fill in API Key for that profile and save |
MODEL_PROFILE_INVALID | Model ID, model name, or credential reference is malformed | Model ID must match ^[a-z][a-z0-9._-]{1,127}$; credential name must match ^[A-Za-z_][A-Za-z0-9_]*$ |
MODEL_PROFILE_EXISTS | A model resource with this name already exists | Use a different name, or edit the existing resource |
MODEL_ENDPOINT_INVALID | The base URL is not valid HTTP(S), or carries user info, query, or fragment | Drop ?, #, and the user:pass@ part |
MODEL_CATALOG_FAILED | The upstream returned non-2xx while listing models | Check key permissions and the endpoint; Test connection shows the status |
MODEL_CATALOG_UNAVAILABLE | The whole catalog is unavailable | Only configured profiles are shown; verify network and credentials, then Reload |
MODEL_CREDENTIAL_STATUS_FAILED | Querying credential status failed | Reopen the panel; if it persists, check Host logs |
MODEL_CREDENTIAL_SYNC_FAILED | Syncing credentials into DSH failed | Retry saving; if it still fails, restart the Host and retry |
请填写模型 API Key | The default profile has no key and was never configured | Enter the key and save |
Related reference
| What you want to know | Where to go |
|---|---|
| The full reasoning-level to upstream-enum mapping | src/model-reasoning.mjs |
| Base URL normalization rules | src/model-endpoint.mjs |
| Model profile fields and runtime options | src/model-profile-contract.mjs, src/model-service.mjs |
| Model and credential panel source | src/client/pages/model-settings.mjs |
| Credential-related environment variables | Environment variable reference |
| Create an agent from these profiles | Create and edit an agent |