Skip to main content
This guide shows you how to set up an OpenClaw sandbox using Novita Sandbox. You’ll configure the environment, launch OpenClaw, and run your AI agent in an isolated runtime.
Want a persistent OpenClaw assistant, not a script? NovitaClaw deploys OpenClaw on Novita Sandbox with one command — novitaclaw launch — and gives you a Web UI, Gateway, Web Terminal, and Telegram / Slack channels that run 24/7. See Always-on OpenClaw with NovitaClaw below. This guide is for running OpenClaw programmatically from your own code.

What you’ll build

You will build a reusable sandbox template with OpenClaw and its Novita model provider pre-installed, then start a sandbox from it and give the agent a task with openclaw agent exec. The agent’s tools — shell, file edits, code execution — run inside the isolated sandbox, and a Novita-hosted model does the reasoning. Your app only sends the task and reads back the result.

Prerequisites

  • Novita API key — create one in Key Management and export it as NOVITA_API_KEY. The same key authenticates both the sandbox and the model calls.
  • Novita Sandbox SDK — Python 3.10+ or Node.js 20+:
  • OpenClaw version — this guide installs the openclaw npm package and was written against OpenClaw 2026.11. OpenClaw requires Node.js 24.16 or later; the template below uses the node:24 image, which tracks the latest 24.x release. Models come from the official @openclaw/novita-provider plugin.

Quickstart

1. Build an OpenClaw sandbox template (one time)

A template bakes OpenClaw and the Novita provider into the sandbox image, so each new sandbox starts in seconds instead of reinstalling them. Build it once; reuse it for every run.

2. Run OpenClaw in a sandbox

openclaw agent exec runs one headless agent turn and exits — OpenClaw’s recommended entry point for scripts and CI. The provider plugin reads NOVITA_API_KEY from the environment.
agent exec runs with the full execution policy a headless turn needs, scoped to --cwd: the agent can edit files and run commands there without asking. That is safe here because everything happens inside a disposable sandbox. It exits 0 on success, 1 on a model or result error, and 2 on timeout.

How it works

OpenClaw gets a full Linux environment inside the sandbox. You drive it with the SDK: files to move data in and out, commands to run the agent and anything else. The snippets below assume a sandbox created as in the Quickstart.

Execute generated code

The agent writes code and runs it in the sandbox’s shell. Add --json to get a stable JSON envelope with the final text and run metadata instead of plain output.

Read and write files

Write long instructions and inputs to files, point the agent at them with --message-file, and read the results afterwards. For whole repositories, use sandbox.git.clone.

Run commands yourself

You can run any command next to the agent — install dependencies before it starts, or verify its work afterwards without trusting its own report.
A command that exits non-zero raises CommandExitException (Python) or CommandExitError (JavaScript). Catch it when a failing run is an expected outcome.

Use Novita models

The Novita provider is already installed in the template, so switching models is a one-line change to --model. Use novita/<model ID> with any model from the Novita model library, for example:
The plugin’s starting catalog includes novita/moonshotai/kimi-k3, novita/moonshotai/kimi-k2.7-code, novita/minimax/minimax-m3, novita/zai-org/glm-5.2, novita/deepseek/deepseek-v4-pro, and novita/qwen/qwen3.7-max. Run openclaw models list --provider novita inside the sandbox to see what your account can use. Add --fallback <provider/model> (repeatable) for an ordered fallback chain. Model usage is billed separately from sandbox runtime, at the model’s own per-token rate.

Always-on OpenClaw with NovitaClaw

agent exec is one task per call. If you want a long-lived OpenClaw assistant you chat with — through a Web UI, Telegram, or Slack — use NovitaClaw. It creates the sandbox, configures OpenClaw with Novita models, and starts the Gateway for you:
The command returns a Web UI URL, a Gateway WebSocket URL and token, a Web Terminal, and a File Manager. Manage the instance with NovitaClaw commands and tune it with NovitaClaw configuration.

Production tips

  • Timeouts — two clocks apply. agent exec stops each model attempt after 600 seconds by default; change it with --timeout <seconds> (0 disables it). The sandbox’s timeout (seconds; timeoutMs in JavaScript) is its maximum lifetime — extend it while the agent works with set_timeout. Pass timeout=0 to commands.run so the SDK doesn’t cut off a long agent turn.
  • Pause and resume — for multi-step jobs, pause the sandbox between steps instead of killing it. Files and installed packages survive, and CPU and RAM billing stops while it is paused. Each agent exec call is a new one-shot turn; to keep its transcripts and run state for inspection, pass an existing directory with --state-dir.
  • Concurrency — each sandbox is isolated, so you can run one OpenClaw task per sandbox in parallel. Concurrent sandboxes are capped by your account tier (5 on Free, 100 on Paid); see Quota Limits.
  • Cost — sandboxes are billed per second while running. A 2 vCPU / 4 GiB sandbox costs about $0.0000324/s, so a 10-minute task is roughly $0.019 in sandbox time, plus model tokens. See Pricing.
  • Always clean up — kill sandboxes in a finally block (as above) so a crash in your script doesn’t leave one running until its timeout.

Troubleshooting

Your account balance can’t cover a new sandbox. Top up on the Billing page or claim the new-user credits described in Pricing, then retry.
The Novita provider plugin isn’t installed for the sandbox user, or the model ID is wrong. Check with openclaw plugins inspect novita and openclaw models list --provider novita inside the sandbox. If the plugin is missing, rebuild the template and keep set_user("user") before the plugins install step so the plugin lands in /home/user/.openclaw, the same user the sandbox runs commands as.
Exit code 2 means the run hit its deadline. Raise --timeout, split the task into smaller steps, and make sure the sandbox timeout is longer than the agent run.

Next steps

NovitaClaw

One-command, always-on OpenClaw on Novita Sandbox.

Sandbox SDK reference

Every option for creating and managing sandboxes.

Sandbox cookbook

Runnable Novita Sandbox examples on GitHub.

More agent integrations

Run OpenCode, Claude Code, or Codex in a sandbox.
Last modified on November 11, 2026