Skip to Content
Referenceoo CLI

oo keys

Personal keys, CLI sign-ins, and model and agent API keys.

Create, rotate and revoke personal API keys, and see or stop CLI sign-ins. A new secret is shown once; --output FILE keeps it in a protected file.

A personal key acts as you, limited to the --access you give it (view, chat or all) for --agents, and expires after --expires. With --agents, all is chat plus what you can do with those agents. Use it from scripts with oo --token-file FILE. An administrator can list or revoke another person's keys with --user.

oo keys model manages the API keys page's model API keys, for this Sunport's models, and oo keys agent its agent API keys, for chatting with agents and using Code.

oo keys list

Your keys and sign-ins, or another's

oo keys list [options]
ArgumentRequiredDefaultChoicesDescription
--user NAMEnoa person with a login: their name, sign-in email, account ID or person ID (oo people list)
--agent NAMEnoan agent's name or ID
--service NAMEnoan enrolled machine's name or ID
--jsonnoprint the API's JSON

It also takes the connection options.

oo keys create

Create a personal key; its secret is shown once

oo keys create [options]
ArgumentRequiredDefaultChoicesDescription
--name NAMEyes
--expires EXPIRESno30d1d, 7d, 30d, 90dhow long it lasts (default 30d)
--access ACCESSnoview, chat, allview, chat or all (default view)
--agents A,Bnoagent IDs or names (default all agents)
--permission ACTION:RESOURCEnoan exact permission instead of --access and --agents; repeatable
--output FILEnowrite the key to a protected credential file instead
--overwriteno
--jsonnoprint the API's JSON

It also takes the connection options.

oo keys rotate

Replace a personal key's secret

oo keys rotate [options] KEY
ArgumentRequiredDefaultChoicesDescription
KEYyeskey ID or name
--yesnoconfirm it now; an agent passes it only once the person confirmed it in chat
--output FILEnowrite the key to a protected credential file instead
--overwriteno
--jsonnoprint the API's JSON

It also takes the connection options.

oo keys revoke

Stop a key or sign-in at once

oo keys revoke [options] KEY
ArgumentRequiredDefaultChoicesDescription
KEYyeskey ID or name
--yesnoconfirm it now; an agent passes it only once the person confirmed it in chat
--user NAMEnoa person with a login: their name, sign-in email, account ID or person ID (oo people list)
--agent NAMEnoan agent's name or ID
--service NAMEnoan enrolled machine's name or ID
--jsonnoprint the API's JSON

It also takes the connection options.

oo keys model

Model API keys call this Sunport's models, OpenAI-compatible, and nothing else, as the API keys page's Model API keys do. Each has a name, the models it may call (all of them by default), the person it is for (its user, --owner), and a budget. A new key's secret is shown once; --output FILE keeps it in a protected file instead. With --hand-off, create doesn't show it: the key's user copies it once, within 24 hours, with oo keys model reveal.

A local agent is a model key for an OpenClaw agent on its owner's own computer: --local-agent with the models it uses (--primary, and --transcription and --embedding if it uses them).

Reading keys needs credentials.read, and everything else credentials.manage. KEY is a key's ID, its alias or its name.

oo keys model [COMMAND]

It also takes the connection options.

oo keys model list

Every model API key, with its status and models

oo keys model list [options]
ArgumentRequiredDefaultChoicesDescription
--jsonnoprint the API's JSON

It also takes the connection options.

oo keys model show

Print one model API key as JSON: the key, as oo keys model list has it, and its budget with what it has spent (budget: spend, max_budget, budget_duration and budget_reset_at; null for a revoked key). Its spend and limit are money: for anyone but an administrator, budget leaves out spend and max_budget.

oo keys model show KEY
ArgumentRequiredDefaultChoicesDescription
KEYyesthe key's ID, alias or name, from oo keys model list

It also takes the connection options.

oo keys model create

Create a model API key, as Create key on the API keys page does, and print its secret once (to stdout; what was made goes to stderr), or keep it in --output FILE. Its alias comes from its name. --owner makes it a person's key; with --hand-off, create doesn't show the secret and that person copies it once instead, within 24 hours. --local-agent makes a local agent's key, for an OpenClaw agent on its owner's computer, which --owner and --primary must name.

oo keys model create [options]
ArgumentRequiredDefaultChoicesDescription
--name NAMEyeswhat the key is for, such as reporting
--models A,Bnothe models it may call, by alias (default every model)
--owner PERSON_IDnothe person it is for: employeeId in oo people list
--hand-offnodon't show the key: its user copies it once within 24 hours
--prompt-caching PROMPT_CACHINGnoonon, offwhether its calls use prompt caching (default on)
--local-agentnoa key for an OpenClaw agent on --owner's computer
--primary MODELnothe chat model the agent uses
--transcription MODELnothe model it transcribes audio with
--embedding MODELnothe model it makes embeddings with
--output FILEnokeep the key, by itself, in a protected file instead
--overwriteno
--jsonnoprint the API's JSON

It also takes the connection options.

oo keys model reveal

Print the secret of a key made with --hand-off, once, as Show key on its page does, or keep it in --output FILE. It works within 24 hours of its creation and only once (already_claimed, claim_expired).

oo keys model reveal [options] KEY
ArgumentRequiredDefaultChoicesDescription
KEYyesthe key's ID, alias or name, from oo keys model list
--output FILEnokeep the key, by itself, in a protected file instead
--overwriteno
--jsonnoprint the API's JSON

It also takes the connection options.

oo keys model update

Change a model API key, as its settings do; what you leave out stays. --budget limits what it may spend, in US dollars, in each --budget-window (none: it never resets). A key's budget is money: only administrators change it, as in the dashboard (admin_required). A local agent's models change with oo keys model local-agent.

oo keys model update [options] KEY
ArgumentRequiredDefaultChoicesDescription
KEYyesthe key's ID, alias or name, from oo keys model list
--name NAMEnoits new name
--models A,Bnothe models it may call, by alias: the whole list
--all-modelsnolet it call every model, including ones added later
--owner PERSON_IDnothe person it is for: employeeId in oo people list
--no-ownernonot assigned to anyone
--prompt-caching PROMPT_CACHINGnoon, offwhether its calls use prompt caching
--budget USDnowhat it may spend in each window, in US dollars
--no-budgetnono budget: it may spend without a limit
--budget-window BUDGET_WINDOWnonone, 1d, 7d, 30d, 1mohow often its spend starts again: none, 1d, 7d, 30d, 1mo
--model-budgets JSONnoreplace per-model USD caps by alias and window (1d, 7d, 30d); {} clears
--jsonnoprint the API's JSON

It also takes the connection options.

oo keys model local-agent

Change the models a local agent's key lets it use, as Edit access on the agent does; what you leave out stays. none takes the transcription or embedding model away. The key itself stays the same.

oo keys model local-agent [options] KEY
ArgumentRequiredDefaultChoicesDescription
KEYyesthe key's ID, alias or name, from oo keys model list
--primary MODELnothe chat model the agent uses
--transcription MODELnothe model it transcribes audio with, or none
--embedding MODELnothe model it makes embeddings with, or none
--jsonnoprint the API's JSON

It also takes the connection options.

oo keys model revoke

Stop a key at once; its models refuse it

oo keys model revoke [options] KEY
ArgumentRequiredDefaultChoicesDescription
KEYyesthe key's ID, alias or name, from oo keys model list
--yesnoconfirm it now; an agent passes it only once the person confirmed it in chat
--jsonnoprint the API's JSON

It also takes the connection options.

oo keys model delete

Delete a revoked key; request history keeps its name

oo keys model delete [options] KEY
ArgumentRequiredDefaultChoicesDescription
KEYyesthe key's ID, alias or name, from oo keys model list
--yesnoconfirm it now; an agent passes it only once the person confirmed it in chat
--jsonnoprint the API's JSON

It also takes the connection options.

oo keys model audit

Every administrator's model API key against the model key routes, the routes the model proxy books, as the API keys page's Routes section shows them: what it called in the last 30 days, its routes now, and what narrowing it would do. model_only: used only for what the model routes keep, so oo keys model narrow keeps it working. unknown: not used in that time, or used for something narrowing would stop (listed); it keeps its routes. narrowed: nothing to do. Nothing changes here. Administrators only.

oo keys model audit [options]
ArgumentRequiredDefaultChoicesDescription
--jsonnoprint the API's JSON

It also takes the connection options.

oo keys model narrow

Narrow a model API key to the model key routes, in place: the same secret, spend and limits. Only a key oo keys model audit calls model_only, read again now; any other keeps its routes (routes_unknown). Whatever calls it on another route then stops. Administrators only.

oo keys model narrow [options] KEY
ArgumentRequiredDefaultChoicesDescription
KEYyesthe key's ID, alias or name, from oo keys model list
--yesnoconfirm it now; an agent passes it only once the person confirmed it in chat
--jsonnoprint the API's JSON

It also takes the connection options.

oo keys agent

Agent API keys call this Sunport's API to chat with the agents they name and, with Code access, to use Code as their user (--owner), as the API keys page's API keys do. The secret is shown once; --output FILE keeps it as a credential file for oo --token-file. Only a person creates one, signed in or with their own key (user_credential_required otherwise), and it gives at most what they hold on those agents and Code; one for someone else needs unrestricted credentials. Code access needs a user. oo keys agent list lists the keys as the API keys page does: everyone's with credentials.read, otherwise your own.

oo keys agent [COMMAND]

It also takes the connection options.

oo keys agent list

List agent API keys as the API keys page does: everyone's with credentials.read, otherwise your own, with your login or a key that carries credentials.read itself; an agent's key sees none. Each shows whether it works or is revoked, the agents it chats with, its Code access, its user and its ID. Budgets, and the last use of other people's keys, show only to administrators. --owner lists one person's keys.

oo keys agent list [options]
ArgumentRequiredDefaultChoicesDescription
--owner PERSON_IDnoonly this person's keys: employeeId in oo people list
--jsonnoprint the API's JSON

It also takes the connection options.

oo keys agent show

Print one agent API key as JSON, as oo keys agent list has it. A key you may not see is not found (api_key_not_found).

oo keys agent show KEY_ID
ArgumentRequiredDefaultChoicesDescription
KEY_IDyesthe key's ID, from oo keys agent list

It also takes the connection options.

oo keys agent create

Create an agent API key; its secret is shown once

oo keys agent create [options]
ArgumentRequiredDefaultChoicesDescription
--name NAMEyeswhat the key is for
--agents A,Bnothe agents it chats with, by ID or name
--owner PERSON_IDnoits user: employeeId in oo people list
--code CODEnononenone, read, writeits Code access: none (default), read or write
--output FILEnowrite the key to a protected credential file instead
--overwriteno
--jsonnoprint the API's JSON

It also takes the connection options.

oo keys agent update

Change an agent API key, as its settings do; what you leave out stays. --agents is the whole list. --budget limits what it may spend, in US dollars, in each --budget-window; a key with Code write access has none. A key's budget is money: only administrators change it, as in the dashboard (admin_required).

oo keys agent update [options] KEY_ID
ArgumentRequiredDefaultChoicesDescription
KEY_IDyesthe key's ID, from oo keys agent list
--name NAMEnoits new name
--agents A,Bnothe agents it chats with, by ID or name: the whole list
--owner PERSON_IDnothe person it is for: employeeId in oo people list
--no-ownernonot assigned to anyone
--code CODEnonone, read, writeits Code access: none, read or write
--budget USDnowhat it may spend in each window, in US dollars
--no-budgetnono budget: it may spend without a limit
--budget-window BUDGET_WINDOWno1d, 7d, 30dhow often its spend starts again: 1d, 7d, 30d
--agent-budgets JSONnoreplace per-agent USD caps by ID and window (1d, 7d, 30d); {} clears
--jsonnoprint the API's JSON

It also takes the connection options.

oo keys agent revoke

Stop a key at once

oo keys agent revoke [options] KEY_ID
ArgumentRequiredDefaultChoicesDescription
KEY_IDyesthe key's ID, from oo keys agent list
--yesnoconfirm it now; an agent passes it only once the person confirmed it in chat
--jsonnoprint the API's JSON

It also takes the connection options.

oo keys agent delete

Delete a revoked key; its history keeps its name

oo keys agent delete [options] KEY_ID
ArgumentRequiredDefaultChoicesDescription
KEY_IDyesthe key's ID, from oo keys agent list
--yesnoconfirm it now; an agent passes it only once the person confirmed it in chat
--jsonnoprint the API's JSON

It also takes the connection options.

On this page