Agent Configuration controls an Agent's identity, model behavior, exact Template and Skill versions, tool Integration credentials, private overrides, and its Communication Connections.
Configuration is version-aware, permission-aware, and lifecycle-aware: it pins exact published versions rather than tracking the newest, what you can edit depends on your effective Agent permissions, and how a change is applied depends on whether the Agent is running, stopped, or in error.
Overview
An Agent is a headless execution aggregate. It executes work; it does not itself hold provider routing.
Its configuration includes:
- Agent name
- Runtime choice established at creation
- Runtime model preference
- Hermes command-approval preference
- An exact pinned Template version
- Assigned and version-pinned Skills
- Tool Integration credentials
- An optional Agent-owned Template Override
- Independently managed Communication Connections
Platform routing, provider tokens, channel allowlists, and mention policies are not Agent fields. They belong to individual Communication Connections, which have their own lifecycle.
Configuration map
The configuration page is organized in this order.
| Section | Purpose | Primary permission |
|---|---|---|
| Profile | Identity, model preference, Runtime, command approval, and deployment facts | Agent update |
| Template selection | Inspect and apply published shared or Agent-owned versions | Agent update |
| Messaging | Create and manage Communication Connections | Agent update, plus secret management for credentials |
| Skills | Assign, remove, and pin Skill versions | Agent update |
| Integrations | Manage encrypted tool Integration credentials | Agent secret management |
| Agent-owned override | Draft and publish private Template snapshots | Agent update |
| Danger zone | Irreversible Agent lifecycle actions | Agent delete |
The Messaging section is where Communication Connections are created and managed. Its label is Messaging, but the resources it manages are Communication Connections.
Agent General Access and direct Agent Access are managed through Share on the Agent detail page, not through Configuration. Retirement lives in Danger zone and is documented in Manage the Agent lifecycle.
Before you begin
You need:
- Access to the Organization that owns the Agent
- Visibility of the Agent
- Agent update permission, for ordinary configuration
- Agent secret-management permission, for credentials
- Lifecycle permission, when a running Agent must restart
- A model permitted by the Organization, when pinning an explicit model
- Any new Template and Skill versions already published
- Credentials required by newly assigned Skills
Permissions
Authorization comes from the effective Agent permissions Agent Barn computes for you, not from a role name on this page.
| Action | Required permission |
|---|---|
| Read the configuration page | Visibility of the Agent |
| Edit Agent configuration | agent.update |
| Create, edit, enable, disable, or retire a Communication Connection | agent.update |
| Create, replace, or retire Connection credentials | agent.update and agent.secret.manage |
| Change Integration credentials | agent.secret.manage |
| Restart a running Agent to apply a change | agent.lifecycle.manage |
| Delete the Agent | agent.delete |
| Manage Agent Access | Agent access-management permission |
Without the applicable action, the configuration appears read-only or the mutation control is not shown. A user with Agent update permission but without secret-management permission cannot change Integration or Connection credentials.
Apply behavior
Runtime-relevant changes include Profile settings, Template selection, Skills, and Integration credentials. Agent Barn changes the apply action based on lifecycle state.
| Agent state | Action | Result |
|---|---|---|
| Running | Apply & Restart | Stops the Agent, saves the configuration, and starts it again |
| Stopped | Apply | Saves the change and leaves the Agent stopped |
ERROR | Apply | Saves the change; resolve the cause, then Start |
Direct Agent configuration updates are not accepted while the Agent remains running, so the web application performs the stop and start around the update.
An Agent in ERROR must have its underlying configuration or Runtime problem resolved before it can start successfully. Saving a change does not by itself clear the error.
After a failed Apply & Restart, confirm both whether the requested value changed and whether the Agent returned to a working state. The previous persisted configuration may still be active.
Open Configuration
Open the Organization that owns the Agent. From Home, select the Agent, then select Configuration.
The page opens with the configuration sections listed above. Finish or cancel the current section edit before moving to another section.
Configure the Profile
Open Profile and select Edit.
Editable settings
| Setting | Behavior |
|---|---|
| Agent name | Changes the display name used across Agent Barn and in regenerated Runtime configuration |
| Model preference | Follows the Organization default, or pins a specific allowed model |
| Command approval | Configurable for Hermes Agents |
Command approval
Command approval is currently configurable only for Hermes, which supports three modes:
| Mode | Behavior |
|---|---|
auto | Automatically approves low-risk commands |
manual | Requests approval before commands run |
off | Skips command approval prompts |
For OpenClaw, the effective auto behavior is reported as managed by OpenClaw. OpenClaw does not accept an explicit non-default command-approval mode.
Command approval is a Runtime execution preference. It is not a Platform or Communication Connection policy.
Read-only facts
Profile also displays operational facts rather than editable fields:
- Runtime: Hermes or OpenClaw, established at creation
- Current lifecycle state
- Runtime deployment inventory
- Managed storage, services, Secrets, and configuration resources
- Communications being managed as independent Connections
You cannot switch the Runtime from Profile, and there is no Platform field to switch. Starting or stopping the Agent reconciles its managed deployment, Service, storage, Secret, and configuration.
Select Apply or Apply & Restart, depending on the Agent state.
Model inheritance and overrides
An Agent's model is not permanently copied at creation. There are two choices.
Use organization default
- The Agent stores no explicit model override.
- It follows the Organization's effective default model.
- The Organization default may itself follow the platform default.
- The effective model is resolved whenever the Agent starts.
- Changing the Organization default affects what an inheriting Agent will use on its next start.
Choose a specific model
- The Agent stores an explicit model override.
- Organization default changes do not alter the override.
- The selected model remains subject to the Organization's model policy and applicable allowlist checks.
Clearing a specific selection returns the Agent to inheritance. Through the API, sending model: null on update clears the override.
Reading the displayed model state
| Field | Meaning |
|---|---|
model_source | Whether the value comes from default or override |
effective_model | The model the Agent would use if started now |
running_model | The model used when the current Runtime instance started |
pending_model | The model a running Agent will switch to after restart |
An inheriting Agent may continue running its previous model until it is restarted after an Organization default changes. Changing an Organization default does not mutate a running Runtime; the new value appears as the pending model and takes effect on the next start.
Organization-level defaults are managed outside this page. See Manage Organizations and members.
Select a Template version
Open Template selection. Every Agent pins an exact published Template version.
The selector can include:
- Published shared Platform Templates
- Published Organization Templates
- Published Agent-owned Override versions
How pinning behaves:
- Publishing a newer Template version does not automatically move an existing Agent.
- Applying another published version repins the Agent.
- Required Skills are revalidated when applying a Template version.
- A stopped Agent remains stopped after applying a Template.
- A running Agent uses Apply & Restart.
To change reusable Template content, publish a new version of the Template itself, or use an Agent-owned override for Agent-specific behavior. Direct per-Agent editing of the active shared Template is not the workflow. See Work with Templates.
Manage Communication Connections
Open Messaging to create and manage the Agent's Communication Connections.
- An Agent may own zero, one, or many Communication Connections.
- Multiple Connections may use the same Platform.
- Each Connection selects a shipped Platform Plugin.
- The plugin defines its own settings and credential schema.
- Provider credentials belong to the Connection.
- Conversations, identities, provider health, and delivery diagnostics are Connection-scoped.
- Creating or editing a Connection does not modify the Agent Runtime configuration.
Slack Connections can hold the Agent's one default delivery target for scheduled work created outside a conversation. Configure it in the Connection editor. Jobs with a recorded conversation origin keep that origin; changing the default does not move them. See the Slack guide for setup and runtime limitations.
Connection operations
Communication Connections have their own lifecycle, separate from this page's Apply workflow:
- Create
- Edit
- Enable
- Disable
- Retire
- Reconnect, where supported
- Retry eligible failed deliveries
These operations:
- Reconcile through the Communications Gateway.
- Do not stop, rebuild, or restart the Agent Runtime.
- Can be performed while the Agent is running.
Retiring a Connection preserves its canonical Conversation history. Deleting the Agent retires its owned Connections as part of Agent deletion.
For the full model, see Communication Connections.
Configure Skills
Open Skills to assign, remove, and pin Skill versions.
- Assigned Skills are independent from the Markdown Template snapshot.
- Template-required Skills cannot be removed while they are required.
- Each assignment pins an exact Skill version.
- Publishing a newer Skill version does not automatically move an Agent's existing pin.
- Applying Skill assignment or version changes restarts a running Agent.
- Skill provider requirements are validated against the resulting tool Integration credentials.
Skills are tool and instruction capabilities. They are not Communication Platforms, and assigning a Skill does not create or change a Connection. See Work with Skills.
Configure Integrations
Open Integrations to manage the encrypted credentials that give the Runtime tool access.
- Agent Secrets and Shared Credentials provide tool Integration access.
- Their plaintext values are encrypted and omitted from reads.
- Connection credentials have a separate encrypted lifecycle.
Changing an Integration credential requires secret-management permission and restarts a running Agent, because the Runtime configuration is regenerated. See Manage Agent credentials.
Create an Agent-owned override
Open Agent-owned override for a private Template workflow scoped to this Agent.
- One private editable draft per Agent
- Explicit publishing into immutable versions
- Read-only version history
- Explicit selection of a published Override version
- Rollback by selecting an earlier published version
An override reaches an Agent in six ordered steps.
- Create draft Agent Barn copies the complete active source version into a private draft
- Edit and save the draft Saving preserves the draft without changing the active configuration
- Publish an immutable Agent-owned version Publishing freezes the draft and clears the editable draft slot
- Open Template selection The published override appears alongside shared Template versions
- Select the published override version Review its artifacts and required Skills first
- Apply, or Apply & Restart Only this step activates the override on the Agent
Publishing does not automatically activate the new version. Applying an Override follows the same stopped-versus-running Apply behavior as Template selection.
See Use Agent Overrides for the complete workflow.
Review the Danger zone
Danger zone holds irreversible Agent lifecycle actions, including retiring the Agent.
Deleting the Agent also retires its owned Communication Connections. Review every Connection before retiring an Agent, since retiring one Connection is a separate and much smaller action.
These actions require Agent delete permission and are documented in Manage the Agent lifecycle.
Verify the configuration
After applying a change, confirm what actually took effect.
- The saved value appears in the section you edited
- A running Agent returned to a working state after Apply & Restart
- The effective model matches your intent, and the running model matches after a restart
- The pinned Template and Skill versions are the ones you selected
- Required Skills and their provider credentials are satisfied
- Connection health is unchanged by a Runtime-only change
Check Connection health separately from Agent health. See Verify your Agent for the layered checks.
Settings you cannot change
| Property | Why |
|---|---|
| Organization | An Agent belongs to exactly one Organization |
| Agent ID | Stable identity for activity, costs, and Runtime resources |
| Creator provenance | A historical record, not an authorization setting |
| Runtime | Hermes or OpenClaw is established at creation |
There is no Platform field to change. To reach a different Platform, add another Communication Connection rather than recreating the Agent.
Troubleshooting
The section is read-only
Your effective Agent permissions do not include the required action. Ordinary configuration needs agent.update; credentials additionally need agent.secret.manage.
The update is rejected while the Agent is running
Direct configuration updates are not accepted for a running Agent. Use Apply & Restart, which stops the Agent, saves the change, and starts it again. That requires lifecycle permission.
The running model did not change
Compare the model state fields. An inheriting Agent keeps its running model until restarted, and a pending model indicates the value that applies on the next start.
If you expected inheritance but see an override, clear the specific model selection to return the Agent to the Organization default.
A newly published Template or Skill version did not appear on the Agent
This is expected. Pins are explicit, so publishing a new version never moves an existing Agent. Apply the version you want.
A required Skill cannot be removed
The pinned Template version requires it. Apply a Template version that does not require the Skill, or keep the assignment.
Messaging is not working after a configuration change
Connection behavior is not governed by this page's Apply workflow. Open the Connection and review its health, policy, and credentials.
Do not restart the Agent to fix a provider or policy problem.
The Agent stays in ERROR after Apply
Saving a change does not clear the error. Resolve the underlying configuration or Runtime problem (model availability, Runtime image, Kubernetes capacity, Template rendering, Skills, or Integration credentials), then Start the Agent.
Next steps
- Manage Communication Connections for provider access
- Manage the Agent lifecycle for start, restart, and retirement
- Work with Templates and Agent Overrides
- Work with Skills and their version pins
- Manage Agent credentials for tool Integrations
- Manage Organizations and members for Organization-level model defaults
- Verify your Agent after a configuration change
Progress messages
Hermes supports an Agent-level verbose_mode setting for progress updates while work is in progress. OpenClaw does not have a supported progress relay through its current external HTTP path; the API rejects verbose_mode=true for an OpenClaw Agent.
Progress visibility is separate from command approval. Email suppresses progress updates even when Agent-level verbosity is enabled, but approval prompts can still be delivered. Existing running Agents need a rebuilt runtime configuration to receive changed adapter behavior.