--- title: Configure an Agent canonical: "https://agentbarn.dev/guides/agents/configuration" pubDate: "2026-08-29T00:00:00.000Z" updatedDate: "2026-09-14T04:31:13.000Z" author: Agent Barn description: "Configure an Agent's model, Hermes approval and progress settings, and pinned behavior." tags: [Agents, How-to, "Agent operators, Agent editors, Agent owners, Organization administrators, and support engineers", default delivery target, Agent configuration, model, approval, progress messages, verbose mode, Hermes] categories: [Guides, Agents] --- 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](/guides/agents/communication-connections), which have their own lifecycle. **Note** Agent Barn separates reusable definitions from Agent-specific configuration. Edit reusable Templates and Skills under Organization settings. Use Agent Configuration to select versions, assign Skills, manage Connections, or create a private Agent-owned override. ## 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](/guides/agents/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. **Warning** Applying a runtime-relevant change to a running Agent interrupts current conversations, Tool Calls, and scheduled work, because the Agent must restart. Connection changes do not. ## 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. **Important** Not every change on this page requires a restart. Communication Connection operations reconcile independently and never restart the Agent Runtime. 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. **Tip** Use `manual` command approval while evaluating an Agent that can run consequential tools. Approval mode does not replace provider permissions, Connection policy, or Agent Access. ## 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](/guides/observe-and-govern/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](/guides/templates-and-skills/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](/guides/platforms/slack#configure-the-default-delivery-target) 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. **Important** Do not use **Apply & Restart** for a Connection-only change. Connection updates increment the Connection's own revision and the Gateway reconciles the provider session. For the full model, see [Communication Connections](/guides/agents/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](/guides/templates-and-skills/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. **Security** Slack, Microsoft Teams, Telegram, and Discord transport credentials must be configured on their Communication Connections, not here. A Platform Connection does not automatically grant a Skill tool access to that provider, and a tool Integration credential does not provide message transport. Changing an Integration credential requires secret-management permission and restarts a running Agent, because the Runtime configuration is regenerated. See [Manage Agent credentials](/guides/integrations/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. 1. **Create draft** Agent Barn copies the complete active source version into a private draft 2. **Edit and save the draft** Saving preserves the draft without changing the active configuration 3. **Publish an immutable Agent-owned version** Publishing freezes the draft and clears the editable draft slot 4. **Open Template selection** The published override appears alongside shared Template versions 5. **Select the published override version** Review its artifacts and required Skills first 6. **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. **Note** An Override contains Template behavior and files. It does not contain Runtime settings, Communication Connection credentials, or Integration Secrets. See [Use Agent Overrides](/guides/templates-and-skills/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](/guides/agents/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](/guides/get-started/verify-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](/guides/agents/communication-connections) for provider access - [Manage the Agent lifecycle](/guides/agents/lifecycle) for start, restart, and retirement - [Work with Templates](/guides/templates-and-skills/templates) and [Agent Overrides](/guides/templates-and-skills/agent-overrides) - [Work with Skills](/guides/templates-and-skills/skills) and their version pins - [Manage Agent credentials](/guides/integrations/credentials) for tool Integrations - [Manage Organizations and members](/guides/observe-and-govern/organizations-and-members) for Organization-level model defaults - [Verify your Agent](/guides/get-started/verify-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.