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 withopenclaw 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
openclawnpm package and was written against OpenClaw 2026.11. OpenClaw requires Node.js 24.16 or later; the template below uses thenode:24image, which tracks the latest 24.x release. Models come from the official@openclaw/novita-providerplugin.
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.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:
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:
Production tips
- Timeouts — two clocks apply.
agent execstops each model attempt after 600 seconds by default; change it with--timeout <seconds>(0disables it). The sandbox’stimeout(seconds;timeoutMsin JavaScript) is its maximum lifetime — extend it while the agent works withset_timeout. Passtimeout=0tocommands.runso 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 execcall 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
finallyblock (as above) so a crash in your script doesn’t leave one running until its timeout.
Troubleshooting
402: insufficient balance when creating a sandbox
402: insufficient balance when creating a sandbox
Unknown provider or model: novita/...
Unknown provider or model: novita/...
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.agent exec exits with code 2
agent exec exits with code 2
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.