Deploy your first Agent

Create your own Agent in the Kubernetes installation from Local setup, deploy it, and get a real response from an OpenAI model. You choose the Agent name and supply your own OpenAI API key. The Agent stays in your installation after the command exits.

Before you start

• Complete Local setup and leave the installation running.
• Start Local setup without the OpenShell Sandbox Driver, using OCC_DEVELOPMENT_SANDBOX_DRIVER=none.
• Use the same checkout and development state directory. If you set OCC_DEVELOPMENT_STATE_DIRECTORY during setup, use the same value here.
• Have an OpenAI API key that can use gpt-6-astra, the default model. To use a different model available to your project, set OPENCLAW_FIRST_AGENT_MODEL to its plain ID, without openai/.
• Keep the key out of commands, Configuration JSON, and chat. For automation, set OPENAI_API_KEY_FILE to a private file containing the key, or supply OPENAI_API_KEY through your environment's secret manager; setting both fails. The command prompts for the key without echoing it only when neither is set. An exported key is used as is, so clear a stale one with env -u OPENAI_API_KEY to be prompted instead.

The walkthrough runs from the repository root on your own development installation. If you followed Kubernetes Setup on an existing cluster, use Deploy and verify production Agents.

Steps

1. Check that the Namespace is ready

In the terminal where you set the OCC URL and service-key file during Local setup, run:

./bin/occ namespace list

Wait until default shows ready. This is where the command will create your Agent.

2. Create and deploy your Agent

Choose a name for your Agent; this example uses my-agent:

node scripts/first-agent.mjs my-agent --prompt 'What is 2 + 2?'

Enter the OpenAI API key when prompted. The command stores it in a platform Secret, creates the named Agent with the Embedded OpenClaw Harness, grants that Agent access to its Secret, and requests the first deployment. It then waits for the gateway and sends a verification prompt before sending your own. Initial startup can take several minutes.

This starter answers model prompts only. Tools and the native admin UI are disabled. The command refuses to reuse it if you change its Configuration elsewhere. For an Agent that can use tools or the native admin UI, create a separate console-managed Agent; see Agent Configuration, Plugins, and local native admin setup.

Keep the command running until it prints Model response verified: followed by the phrase it asked the model to repeat. Under Agent response:, it then prints the model's answer to your question. It also prints the Agent ID, active revision, and console URL. These returned responses complete the model check; see what each check establishes.

3. Find your Agent in the console

Open the console link from the command and sign in with the local credentials from Local setup. Current version shows the revision selected by OCC; Deployment activity shows persisted deployment progress. Use the terminal command for further model prompts. For browser access to the Agent's files, follow workspace verification.

The Agent remains available after the command exits. Run the same command with the same Agent name and a different --prompt to ask another question; you do not need to enter the model key again. Stopping the local stack with dev down deletes the installation and its Agents.

Troubleshoot

• default stays in provisioning or fails: check that OCC and Kubernetes are reachable, then check the Namespace status.
• A name is already in use: use a new name if the existing Agent was created through the console or another tool. If this command created it, rerun with the same name to verify that Agent instead of creating a duplicate.
• Deployment or the model request fails: confirm the model is available to your OpenAI project and the cluster can reach the provider. To replace an invalid key, run node scripts/first-agent.mjs my-agent --replace-key and supply the new key when prompted. An active revision without Model response verified is not a successful model check. See Troubleshoot Agents.
• The selected setup uses OpenShell: stop that development environment and start Local setup without OpenShell. The current OpenShell development profile does not support this first-Agent model-turn workflow.